[pull] develop from shadowsocks:develop

.agents/skills/.gitignore

@@ -0,0 +1,5 @@
+*
+!.gitignore
+!/xcodegen/
+!/shadowsocksx-ng2-local-validation/
+

.agents/skills/shadowsocksx-ng2-local-validation/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: shadowsocksx-ng2-local-validation
+description: Validate ShadowsocksX-NG2 changes and diagnose retained local validation results.
+---
+
+# ShadowsocksX-NG2 local validation
+
+This repository copy is the maintained skill. Copies under `~/.codex/memories/skills/` are historical snapshots. Paths below are relative to the repository root unless stated otherwise.
+
+## Select the evidence
+
+1. Inspect the request, staged and unstaged diffs, `ShadowsocksX-NG2/AGENTS.md`, and relevant ADRs. Read `ShadowsocksX-NG2/README.md` for build/signing conventions and `ShadowsocksX-NG2/Taskfile.dist.yml` for current gate definitions.
+2. Identify the requested level: focused tests, full hostless suite, real-process smoke, Debug/Release build, native/manual UI, or real system-proxy behavior. Retain that scope; documentation-only changes do not require repeating full suites.
+3. For structural/resource changes, update authoritative `project.yml` and run `task gen:prj` from `ShadowsocksX-NG2/`; never hand-edit the generated project.
+
+## Run the selected checks
+
+- Work from `ShadowsocksX-NG2/`. For combined validation use `task --exit-code validate`. From another directory use `task --exit-code --taskfile /absolute/path/to/ShadowsocksX-NG2/Taskfile.dist.yml validate`.
+- Default gates are `lint test test:smoke build`, executed in order with fail-fast behavior. To select a non-duplicated subset, append e.g. `-- lint test`. Diagnose the first failure; later selected gates are `not_run`, not skipped tests.
+- `test` runs offline binary/rule checks before the hostless arm64 Xcode suite. Its Xcode test counts do not count those earlier checks. `test:smoke` uses the separate `ShadowsocksX-NG2Smoke` scheme and real processes. `build` is Debug; Release is a separate `task build:release` and is outside `validate`.
+- Run focused tests when appropriate using the existing Xcode scheme and test selection; a focused Xcode run does not cover the preceding Taskfile checks. Use isolated derived data when needed. Follow the repository Debug ad-hoc signing baseline; Release requires Developer ID signing and has no unsigned fallback.
+- `task format` and `task lint:fix` mutate source; use when requested or needed for the change, then inspect the diff. Current commands and options belong in Taskfile, not this skill.
+
+## Read retained evidence
+
+`validate` prints its run directory, `ShadowsocksX-NG2/.build/validation/<UTC>-<random>/`. Gate directories use the gate name with `:` replaced by `-` (`test:smoke` → `test-smoke/`). `task clean` removes these artifacts; copy them elsewhere if long-term retention is needed.
+
+1. Read the run's `summary.txt` first. It records the overall exit code, selected gates, gate status/exit codes, test counts and evidence warnings. Per-gate `status.txt` supplies the same gate summary.
+2. For failed Xcode tests, read that gate's `test-summary.json`, especially `testFailures`. Report each failing case using `testIdentifierString` (or `testName`) and its `failureText`. For example, `plutil -extract testFailures json -o - <gate-dir>/test-summary.json` reads the retained failures without reopening the result bundle.
+3. If the summary is absent, unreadable, or insufficient, read the relevant diagnostics: `test-summary.stderr.log` for extraction failure, `count-reader.log` for invalid counts, and `raw.log` for gate output, pre-Xcode failures, build/lint errors, or missing context. Query `result.xcresult` only for unresolved detail. When retained summaries answer the question, do not repeat `xcresulttool` extraction.
+4. Keep command outcome and evidence completeness separate. `validate:result` writes the original gate exit code; summary extraction does not replace it. A missing result bundle or unreadable/invalid test summary means `evidence incomplete` and unknown counts, never zero counts or an inferred pass. `validate:summary` preserves the overall exit code and marks unexecuted selected gates `not_run`. Build has no test-count summary; lint has no xcresult requirement.
+
+## Diagnose within the evidence boundary
+
+- If XcodeGen reports `No project spec found`, check cwd. Permission failures in Xcode, macros, signing or Git may be environment boundaries: retry the unchanged command through authorized macOS execution before changing source. Distinguish missing Release signing configuration from source failure.
+- Preserve assertions and default parallel execution when investigating flakes. Prefer deterministic readiness and explicit fixture release, cancellation and drainage over extra sleeps or increased timeouts. For parallelism claims, inspect runner evidence; configuration alone does not prove concurrent execution.
+- For connectivity/latency smoke, verify listener ownership by the spawned process (`RuntimeSocketOwnershipProbe` or its current equivalent), response-header deadlines, and process-group/temp-environment cleanup. Use local DNS/loopback fixtures and proxy-egress observations where routing assertions require them.
+- Keep inherited XCTest `test*` methods out of shared fixture bases to avoid duplicate execution. Measure slow rule/runtime segments before adding delay injection.
+- Hostless tests, real-process smoke, native/manual UI, and real system-proxy acceptance are separate evidence levels. Hostless/smoke success does not establish SystemConfiguration writes, helper approval, notification behavior, or visual acceptance.
+
+## Finish
+
+Inspect staged and unstaged diffs and run `git diff --check`. Report the actual commands, run directory, exit codes, counts in Xcode's summary convention (parameterized executions may differ), warnings, evidence gaps, and omitted acceptance levels. Commit locally only when requested; push only with explicit authorization.

.agents/skills/shadowsocksx-ng2-local-validation/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

.agents/skills/xcodegen/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: xcodegen
+description: Generate and manage Xcode projects with XcodeGen — write project.yml as the source of truth and produce .xcodeproj from it instead of hand-editing pbxproj files. Use this skill whenever creating or modifying an Xcode project's structure (targets, schemes, build settings, Info.plist, entitlements, dependencies like SPM packages or frameworks), when the user mentions xcodegen / project.yml / regenerating or fixing a .xcodeproj, or when asked to add files or targets to an Xcode project — even if they don't name XcodeGen explicitly. Also applies to CI project generation and migrating a repo to a generated-project workflow.
+---
+
+# XcodeGen
+
+XcodeGen generates `.xcodeproj` files from a declarative `project.yml` spec.
+
+**Core mental model: `project.yml` is the source of truth; `.xcodeproj` is a disposable build artifact.** Never hand-edit the `.xcodeproj` and never tell the user to add files through Xcode's UI — every structural change (new target, new source directory, new dependency) goes through `project.yml` + regeneration. That is the entire point of the tool: no pbxproj merge conflicts, and the project structure becomes reviewable YAML in git.
+
+## The workflow
+
+1. Check the tool exists: `which xcodegen` (install with `brew install xcodegen`). If the spec uses newer features, note them in `options.minimumXcodeGenVersion`.
+2. Write or edit `project.yml` at the repo/project root.
+3. Generate: `xcodegen generate` (add `--use-cache` in scripts/CI so unchanged specs skip regeneration).
+4. Verify the result — a generated project that doesn't build is not done:
+   - `xcodebuild -list -project <Name>.xcodeproj` — schemes and configurations are as expected.
+   - `xcodebuild -project <Name>.xcodeproj -scheme <Scheme> build` — the real gate.
+   - `xcodegen dump --spec project.yml` prints the fully-resolved spec; use it to debug `include:` merges or surprising settings presets.
+
+## Minimal working example
+
+macOS app + unit tests + scheme — the shape most projects need; adapt platform, paths, and deployment target:
+
+```yaml
+name: MyApp
+options:
+  bundleIdPrefix: com.example        # targets without PRODUCT_BUNDLE_IDENTIFIER get com.example.<TargetName>
+  deploymentTarget:
+    macOS: "13.0"
+  createIntermediateGroups: true
+targets:
+  MyApp:
+    type: application
+    platform: macOS
+    sources:
+      - path: MyApp                  # a directory: everything under it is picked up
+    info:
+      path: MyApp/Info.plist         # generated and written to disk; CFBundle* keys auto-filled
+      properties:
+        LSMinimumSystemVersion: "13.0"
+    scheme:
+      testTargets:
+        - MyAppTests                 # scheme "MyApp" builds app + runs tests
+  MyAppTests:
+    type: bundle.unit-test
+    platform: macOS
+    sources:
+      - path: MyAppTests
+    dependencies:
+      - target: MyApp                # TEST_HOST is set automatically for unit tests
+```
+
+```bash
+xcodegen generate
+xcodebuild -project MyApp.xcodeproj -scheme MyApp build
+```
+
+## Rules that prevent most mistakes
+
+- **Regenerate after adding/removing source files.** Source globs are resolved when `xcodegen generate` runs, not live by Xcode — a new `.swift` file on disk is invisible to the project until then. "My file isn't in the target" almost always means: run `xcodegen generate`. (Xcode auto-reloads a regenerated project that's already open.)
+- **Never mix settings styles.** In a `settings:` block, if you use `base:`, `configs:`, or `groups:`, a sibling plain map (e.g. `MARKETING_VERSION: 1.0` at the same level) is *silently ignored*. Pick one style per block; the plain-map style only works alone.
+- **Quote deployment targets**: `deploymentTarget: "14.0"`, not `14.0` (YAML parses the latter as a float and trailing zeros vanish).
+- **Prefer `info:` / `entitlements:` blocks** over committing static plists: XcodeGen writes the files and sets `INFOPLIST_FILE` / `CODE_SIGN_ENTITLEMENTS` for you, and fills `CFBundleIdentifier`, `CFBundleExecutable`, `CFBundleShortVersionString` etc. automatically. Anything you put in `properties:` wins. Info.plist files found in sources are never added to build phases.
+- **Mark generated/optional paths** with `optional: true` on a source, or generation fails when the directory doesn't exist yet.
+- **Test targets**: declare the app as a `dependencies: - target:` of the test target — that alone wires up `TEST_HOST` (unit tests) or `TEST_TARGET_NAME` (UI tests, type `bundle.ui-testing`).
+- **Extensions embed themselves**: a dependency of an `application` target defaults to `embed: true`, so `- target: MyExtension` is usually all an app needs — no copy-files phase to write.
+- **Extension bundle IDs must live under the app's bundle ID.** macOS/iOS validate that an embedded extension's bundle ID starts with the parent app's — `com.example.MyProxy.Tunnel`, not `com.example.Tunnel`. Since `bundleIdPrefix` auto-derivation gives every target `prefix.TargetName`, extensions fail a *build-validation* step (not compilation) with "Embedded binary's bundle identifier is not prefixed with the parent app's bundle identifier". Always set `PRODUCT_BUNDLE_IDENTIFIER` explicitly on extension targets (see recipes.md #2).
+- **`.gitignore` the generated project** (`*.xcodeproj`) so no one edits it by accident. If the repo currently tracks one, flag the migration step (remove from index, regenerate locally) rather than doing it silently.
+- **`xcodegen generate` is idempotent.** When in doubt, re-run it; there is no state to corrupt.
+
+## Choosing between the reference files
+
+- `references/project-spec.md` — syntax cheat sheet: every section of `project.yml` with exact key names. Read when you need a field you don't remember precisely (source exclude patterns, dependency options, scheme fields, SPM version constraints).
+- `references/recipes.md` — complete copy-pasteable `project.yml` examples: app + unit/UI tests, app extension (e.g. network extension) with entitlements, SPM remote/local packages, per-config xcconfig, vendored pre-built binaries/frameworks, build-script phases, splitting a spec with `include:`. Read before writing any non-trivial spec — reuse a recipe rather than assembling from memory.