@mmerterden/multi-agent-pipeline 12.11.0 → 13.1.0

package/pipeline/commands/multi-agent/testflight-validation/SKILL.md

@@ -0,0 +1,219 @@
+---
+description: "Pre-submission validation for a TestFlight / App Store build (iOS, local-only). Three gates: static archive audit, Apple's own `altool --validate-app`, and a Review-Guidelines check. ITMS codes are mapped to the rule each implies. Validates only, never uploads. Use when a build is about to go to TestFlight, or a submission was rejected and you need why."
+description-tr: "TestFlight / App Store yüklemesi öncesi doğrulama (iOS, yalnızca lokal). Repo + branch seç, sonra ya build'i sen ver ya da koşu archive alsın; üç kapıyı geç: statik 18-kurallı archive denetimi, Apple'ın kendi `altool --validate-app`'i, ve App Store Review Guidelines'a karşı guideline incelemesi. Her kapı için ayrı verdict, ITMS kodları ilgili kurala eşlenmiş. Sadece doğrular  -  asla yüklemez."
+argument-hint: "[repo]  -  empty = pick from prefs; repo name or path; --ipa=<path>; --archive=<path>; --resume"
+allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, AskUserQuestion, Skill, mcp__dev-toolkit__ios_app_store_audit, mcp__dev-toolkit__ios_export_ipa, mcp__dev-toolkit__ios_testflight_validate, mcp__dev-toolkit__ios_xcodebuild, mcp__dev-toolkit__ios_xcresult
+---
+
+# /multi-agent:testflight-validation  -  pre-submission validation
+
+Catch, before you upload, what App Store Connect would send back after you do.
+
+**Local-only.** No commits, no push, no PR, no channels. The worktree exists only
+to archive without touching your working tree.
+
+**It never uploads.** Only `--validate-app` is ever invoked, never `--upload-app`.
+A validation run must not be able to ship a build by accident.
+
+## Why three gates and not one
+
+Each gate sees something the others structurally cannot. Reporting one of them as
+"the check" is how a build passes locally and gets rejected anyway.
+
+| Gate | What runs | Needs | Sees | Blind to |
+|---|---|---|---|---|
+| **1. Static** | `ios_app_store_audit` (18 rules, real ITMS codes) | an `.xcarchive` | privacy manifest, required-reason API, Info.plist, code signing, entitlements, embedded SDK, IPv6, debug-tool leak, binary size | anything that depends on the App Store Connect account |
+| **2. Authoritative** | `ios_testflight_validate` → `altool --validate-app` | an `.ipa` + credentials | unregistered bundle ID, profile that does not match the app record, **a version+build pair already used**, entitlements not provisioned for the App ID | the Review Guidelines  -  Apple's validator does not read them |
+| **3. Guideline** | `app-store-review` skill + repo evidence | repo checkout | ATT flow, privacy policy, account deletion, IAP rules, purpose-string wording, permission justification | anything not visible in source |
+
+Gate 2 is the only one that asks Apple, and Gate 3 is the only one that covers the
+rejections a human reviewer writes. Most "we passed validation and still got
+rejected" cases are Gate 3 findings.
+
+## Step 0  -  parse input
+
+| Input | Meaning |
+|---|---|
+| (empty) | ask which repo (Step 1) |
+| `my-ios-app` or a path | that repo |
+| `--ipa=<path>` | Mode B with an `.ipa`; Gate 1 cannot run (see Step 3) |
+| `--archive=<path>` | Mode B with an `.xcarchive`; all three gates run |
+| `--resume` | continue the last run from its state file |
+
+State lives at `$HOME/.claude/logs/multi-agent/<task_id>/agent-state.json` with
+`taskId = TFV-<repo>-<yyyymmddHHMM>`. Register phases with the tracker
+(`$HOME/.claude/multi-agent-refs/tracker-contract.md`) so `:resume` and `:status`
+work like any other run.
+
+## Step 1  -  pickers (native, always)
+
+Use `AskUserQuestion` for every step  -  never a numbered text menu. Questions and
+descriptions render in `prefs.global.outputLanguage`; `label` and `header` stay
+English, per `$HOME/.claude/multi-agent-refs/picker-contract.md`. Print the
+`Step <i>/<n>: <what this decides>` breadcrumb for each.
+
+1. **Repo**  -  from `prefs.projects` where the stack is iOS. A single match
+   auto-resolves (say so in the breadcrumb, do not silently skip the step).
+2. **Branch**  -  the branch to validate. Resolution order:
+   - `git fetch --prune` first, capturing **stderr**. **If the fetch fails, do not
+     silently fall back to a cached ref**, and **classify before naming a cause**  -
+     the same rule as the `/multi-agent:dev` remote gate:
+
+     | stderr contains | Cause | Remedy |
+     |---|---|---|
+     | `could not read Password`, `Authentication failed`, `403` | credential | store the PAT in the credential helper or switch the remote to SSH. **A VPN cannot fix this**, and the base ref being stale is unrelated to what broke  -  do not offer the cached-ref fallback. |
+     | `Could not resolve host`, `Operation timed out`, `Connection refused` | network | retry / continue on the cached ref with an explicit warning / switch remote / abort, per `$HOME/.claude/multi-agent-refs/rules.md` |
+     | `Repository not found`, `404` | wrong remote | show `git remote -v` and ask |
+
+     Always print the observed stderr line next to the classification. Asserting
+     `unreachable (VPN/DNS)` for a missing-credential error that returns in under a
+     second sends the user to fix something that was never broken.
+   - Offer the current branch, the default branch, and any `release/*` /
+     `tkdevelop/*` heads.
+3. **Mode**  -  how the build is obtained:
+   - `Supply a build` (Mode B, default)  -  fastest, no signing needed in-run.
+   - `Archive from this branch` (Mode A)  -  needs a distribution certificate and
+     profile in the keychain, and takes as long as a release archive.
+
+## Step 2  -  pre-flight, before anything expensive
+
+Report every line; a missing prerequisite is a halt, not a warning.
+
+```bash
+xcrun --find altool >/dev/null 2>&1 || echo "MISSING: altool (install Xcode)"
+xcodebuild -version | head -1
+```
+
+Then resolve credentials, and **state which tier is active in the report**:
+
+| Tier | Source | Effect |
+|---|---|---|
+| 1 | ASC API key  -  key id + issuer id from the keychain via `prefs.global.keychainMapping`, `.p8` at `~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8` | Gate 2 runs |
+| 2 | Apple ID + app-specific password, referenced as a keychain item | Gate 2 runs |
+| 3 | neither | **Gate 2 reports `SKIPPED`, and the run says so in the verdict line** |
+
+Credentials come from `/multi-agent:setup`; never prompt for a secret value in
+chat. If nothing is configured, tell the user which of the two tiers they can set
+up and that tier 2 needs no elevated App Store Connect role.
+
+Multi-provider accounts need `--provider-public-id`. When it is not in prefs, run
+`ios_testflight_validate({list_providers: true})` once and ask which provider.
+
+## Step 3  -  obtain the build
+
+### Mode B  -  a build you supply
+
+- `.xcarchive` → Gate 1 runs on it. To reach Gate 2 the archive must be exported,
+  so run `ios_export_ipa` (see Mode A step 3 for the signing inputs).
+- `.ipa` only → **Gate 1 is reported `SKIPPED (needs .xcarchive)`.** The static
+  audit reads archive structure that an `.ipa` does not carry. Do not present a
+  two-gate run as a full pass; say which gate did not run and why, and offer to
+  re-run with the archive.
+
+### Mode A  -  archive from the branch
+
+1. Worktree at `{projectRoot}/{worktreeBasePath}/{taskId}` on the chosen branch.
+   **Never under `$HOME`**, never a direct checkout of the main working tree.
+2. Resolve the scheme and workspace/project from prefs; ask if ambiguous.
+3. Archive:
+   `ios_xcodebuild({workspace|project, scheme, action: "archive", configuration: "Release", destination: "generic/platform=iOS"})`
+   Note the destination: the simulator default would produce an archive that
+   cannot be exported for distribution.
+4. Export:
+   `ios_export_ipa({archive_path, output_dir, method: "app-store-connect", team_id, provisioning_profiles?, signing_style?})`
+   Leave `allow_provisioning_updates` off unless the user asks: it lets xcodebuild
+   create or modify profiles in the developer account, which a validation run has
+   no business doing.
+5. A failed export halts with the parsed errors. The usual causes are a missing
+   distribution certificate, a profile that does not match the bundle ID, or
+   `signing_style: "manual"` with no `provisioning_profiles` map.
+
+## Step 4  -  Gate 1, static audit
+
+`ios_app_store_audit({archive_path, rules: "all"})`.
+
+`error` findings are blocking; `warning` is advisory. Group the output by severity
+and keep each finding's ITMS code  -  Gate 2 may return the same code, and seeing
+it in both places tells the user it is real rather than a heuristic.
+
+## Step 5  -  Gate 2, Apple's own validation
+
+`ios_testflight_validate({ipa_path, platform: "ios", <credential args>})`.
+
+Render the verdict exactly as returned:
+
+- `PASS`  -  Apple accepted the binary for delivery.
+- `FAIL`  -  list each issue with its ITMS code, the mapped guideline, and the hint.
+- `SKIPPED`  -  print the reason. **Never render this as a pass.** The verdict line
+  for the whole run must read `2 of 3 gates cleared, 1 skipped`, not `passed`.
+
+Gate 2 is the only gate that catches a build number already used  -  the most
+common wasted upload  -  so when it fails on that, say so plainly and name the next
+free build number.
+
+## Step 6  -  Gate 3, guideline review
+
+Load the `app-store-review` skill and review the repo against it. This is the gate
+that catches what a human reviewer rejects, so it reads source, not the binary:
+
+| Area | Evidence to gather |
+|---|---|
+| Purpose strings | every `NS*UsageDescription` in Info.plist  -  present, specific, user-facing, and matching what the code actually does with the data |
+| Privacy manifest | `PrivacyInfo.xcprivacy` exists, declares required-reason APIs, and matches the SDKs actually linked |
+| Tracking | if any tracking API or SDK is present, an ATT prompt exists and runs before collection |
+| Account deletion | if the app creates accounts, an in-app deletion path exists (guideline 5.1.1(v)) |
+| Privacy policy | reachable in-app and in the metadata |
+| IAP | anything unlocking features goes through StoreKit, with no external purchase path |
+| Sign in with Apple | present when a third-party social login is offered |
+
+For each: `pass` / `fail` / `not-applicable` with the evidence path that justifies
+it. `not-applicable` needs a reason  -  an unexamined area is not a pass.
+
+## Step 7  -  report
+
+Write to `~/TestFlightChecks/<repo>-<branch>-<timestamp>/report.md` and print a
+summary. Structure:
+
+```
+Verdict: <N> of 3 gates cleared[, <M> skipped]
+Build:   <ipa or archive path>  ·  <bundle id> <version> (<build>)
+Auth:    tier <1|2|none>  ·  <method>
+
+Gate 1  static audit        PASS | FAIL (<n> blocking, <n> advisory) | SKIPPED (<reason>)
+Gate 2  Apple validation    PASS | FAIL (<n> issues) | SKIPPED (<reason>)
+Gate 3  guideline review    PASS | FAIL (<n> findings) | <n> not-applicable
+
+Blocking  -  fix before uploading
+  [ITMS-90683] Info.plist: NSCameraUsageDescription missing
+      guideline 5.1.1 Data Collection and Storage
+      <hint>
+      <file:line>
+
+Advisory
+  ...
+
+Not run
+  Gate 1: needs an .xcarchive; only an .ipa was supplied
+```
+
+Rules for the report:
+
+- A skipped gate is never folded into the pass count. The verdict line states the
+  skip.
+- Every blocking finding carries a file path or an ITMS code. A finding the user
+  cannot act on is noise.
+- No AI or assistant attribution anywhere, per
+  `$HOME/.claude/rules/git-conventions.md`.
+- Real newlines, no HTML entities, per
+  `$HOME/.claude/rules/pipeline-output-formatting.md`.
+
+## Step 8  -  offer the next action, do not take it
+
+Print, and stop:
+
+- the exact `xcrun altool --upload-app` command for when the gates are clear, so
+  uploading stays an explicit human act
+- `/multi-agent:testflight-validation --resume` to re-run after fixes
+- `/multi-agent:fix-bug` when Gate 3 produced code-level findings
+
+Never upload, never bump the build number, never commit.

package/pipeline/commands/multi-agent/update/SKILL.md

@@ -52,15 +52,18 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
    fi
    ```
 
-4c. **Prune retired adapter files** (Cursor / Antigravity / Codex / Copilot Chat were removed in v10.7.0 - the pipeline now targets Claude Code + Copilot CLI only):
+4c. **Prune retired adapter files** (Cursor / Antigravity / Copilot Chat were removed in v10.7.0 - the pipeline targets Claude Code, Copilot CLI and Codex CLI):
    ```bash
-   # Global Codex adapter prompt is safe to remove (no longer produced).
-   rm -f "$HOME/.codex/prompts/multi-agent.md"
-   echo "  -> pruned retired global Codex adapter prompt (if present)"
    # Per-project adapter files (.cursor/, .agent/, .github/copilot-instructions.md)
    # live in your repos and are left untouched - remove them manually if you like.
+   echo "  -> no global adapter files to prune"
    ```
 
+   > **Do NOT delete `$HOME/.codex/prompts/multi-agent.md`.** Releases up to
+   > v12.11.0 removed it here as a retired v9.7.0 adapter leftover. Codex CLI is a
+   > supported target again as of v13.0.0 and the installer writes that file, so
+   > deleting it silently breaks the `/multi-agent` slash command on Codex.
+
 5. **Migrate preferences** (if there is an old schema):
    ```bash
    if [ -f "$HOME/.claude/scripts/migrate-prefs.mjs" ]; then

package/pipeline/multi-agent-refs/_input-parser.md

@@ -6,7 +6,7 @@ description: "Internal  -  input type detection for multi-agent dispatcher."
 
 The top-level `multi-agent` command classifies user arguments per the rules below.
 
-> **Language**: Schema reference only  -  no user-facing text. Picker UI strings always English (`promptLanguage` is locked to `"en"`). Commit/PR/Jira payloads stay English.
+> **Language**: Schema reference only  -  no user-facing text. Picker `label` + `header` always English (`promptLanguage` is locked to `"en"`); `question` + `description` follow `outputLanguage` per the `rules.md` matrix. Commit/PR/Jira payloads stay English.
 
 ## Type Table
 

package/pipeline/multi-agent-refs/component-dispatch.md

@@ -11,20 +11,53 @@ Phase 3 checks, in order:
 1. `agent-state.json` has `taskType: "component"` (set by Phase 0 Step 7).
 2. `agent-state.json` has a non-null `figmaUrl`.
 
-Either missing → log the anomaly to `agent-log.md` ("component dispatch expected but state incomplete"), fall through to the standard TDD path. Never silently skip the Figma work.
+Either missing → **HALT.** Log the anomaly to `agent-log.md` ("component dispatch
+expected but state incomplete: <which field>") and stop with a user-visible error
+naming the missing field and pointing at `phase0-exit-gate.mjs`.
+
+> Earlier wording sent an incomplete-state component task down the generic TDD path,
+> which contradicted the sentence that followed it: taking the generic path **is**
+> skipping the Figma work.
+> It also authorised the exact degradation that broke a real run  -  Phase 0 never
+> wrote `agent-state.json`, so `taskType` was absent, so a Figma-driven screen was
+> built through the generic path with no token-compliance check, no Code Connect
+> publish and no component review. Spacing came out `16` where the frame said
+> `Spacing/12`, and half the branch's commits were rework.
+>
+> The Phase 0 exit gate now prevents reaching Phase 3 in that state at all; this
+> halt is the second line of defence. A component task that cannot be dispatched as
+> one must fail loudly, because the generic path produces artefacts that look
+> finished and are not.
 
 ## Plugin skill resolution
 
+Scope first, then platform. A screen and a single component are different jobs and
+the plugin ships a skill for each; routing a screen to the component skill is why one
+run produced entities and a mapper but left the screen half-wired.
+
+| `state.componentScope` | Meaning | iOS skill | Android skill |
+|---|---|---|---|
+| `screen` (default when the frame is a full screen, or the task names a screen) | Full clean-architecture vertical: Entity → Repository → Mapper → UseCase → LocalizedText → AnalyticsTracking → CoordinatorEvent → ViewModel → Scene → Preview, then verify | `ai-ios-engineering-toolkit:create-screen` | `ai-android-engineering-toolkit:create-screen` |
+| `component` | One reusable UI component (Configuration / View / +Modifiers / Code Connect) | `ai-ios-engineering-toolkit:create-component` (fallback `create-ui-component`) | `ai-android-engineering-toolkit:create-component` (fallback `create-ui-component`) |
+| `evolve` | Change an existing component | `evolve-component` (fallback `evolve-ui-component`) | same |
+
 ```
-project.platform  → component skill (enabled marketplace plugin, Claude Code)
-──────────────────────────────────────────────────────────────────────────────
-ios               → Skill: ai-ios-engineering-toolkit:create-component
-                            (fallback: ai-ios-engineering-toolkit:create-ui-component)
-android           → Skill: ai-android-engineering-toolkit:create-component
-                            (fallback: ai-android-engineering-toolkit:create-ui-component)
 web, multi-*      → HALT with clear error (no web target)
 ```
 
+Phase 0 Step 7 sets `state.componentScope` alongside `taskType`: a Figma frame that
+is a full screen, or a task whose title names a screen, is `screen`; a frame that is
+a single atom is `component`. When it cannot be decided, ask  -  do not default to
+`component`, because the screen path is a superset and the component path silently
+omits the wiring.
+
+**Pre-implementation validation is not optional on iOS.** Before the create skill
+runs, dispatch `ai-ios-engineering-toolkit:figma-validate` for the frame. It checks
+registry presence, Code Connect strategy, **design token compliance**, dependency
+readiness, atomic scope and already-implemented status in about ten seconds. Those
+are precisely the checks whose absence produced guessed spacing and an unpublished
+Code Connect binding. A `figma-validate` failure halts the dispatch.
+
 **Dual-name resolution.** The public (`multi-agent-plugins`) and a corporate/private marketplace named the same skill differently  -  `create-component` vs `create-ui-component`. Dispatch tries `create-component` first; if it is not available in the current repo, tries `create-ui-component`. (Same dual-name rule applies when `taskType` maps to evolve → `evolve-component`/`evolve-ui-component`, or fix → `fix-bug`.)
 
 If **neither** resolves, the platform's `ai-<platform>-engineering-toolkit` plugin is not enabled in this repo. **Halt with a user-visible error**: "component task requires the ai-<platform>-engineering-toolkit plugin enabled in this repo (`.claude/settings.local.json`)." Do not silently fall back to TDD  -  a component task ran through the bugfix path would produce wrong artefacts.

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -1,19 +1,19 @@
-# Cross-CLI Contract (Claude Code ↔ Copilot CLI)
+# Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
 > **Non-negotiable**. Any change that breaks this contract blocks merge. Validated by `smoke-cross-cli-behavior.sh`.
 
-**Purpose**: every pipeline command must produce identical artifacts (state, logs, outputs) and respect identical placeholder vocabulary regardless of which CLI invokes it. This file is the source of truth for "what must stay the same."
+**Purpose**: every pipeline command must produce identical artifacts (state, logs, outputs) and respect identical placeholder vocabulary regardless of which of the three host CLIs invokes it. This file is the source of truth for "what must stay the same."
 
 ---
 
-## 1. Command Inventory (42 commands)
+## 1. Command Inventory (43 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-routines, save, scan, search, setup, stack, status, sync, test, uninstall, update
+routines, save, scan, search, setup, stack, status, sync, test, testflight-validation, uninstall, update
 ```
 
 Categories:
@@ -24,6 +24,7 @@ Categories:
 - **Fast modes** (Init -> Dev(Opus) -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
 - **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
+- **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 - **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
 
@@ -110,14 +111,43 @@ Legacy names found during the v3.7 audit  -  replaced per this contract.
 
 ---
 
-## 2.6 Intentional structural divergence  -  `multi-agent.md` vs `multi-agent/SKILL.md`
+## 2.6 Intentional structural divergence  -  thin dispatcher vs inlined orchestrator
 
-The top-level orchestrator has two deliberately different shapes on the two CLIs. This is **not drift**  -  it reflects a real capability gap between the host CLIs, and auditors must not flag it as a parity violation.
+The top-level orchestrator has two deliberately different shapes. This is **not
+drift**  -  it reflects a real capability gap between the host CLIs, and auditors
+must not flag it as a parity violation.
 
 | Surface | File | Shape | Why |
 |---|---|---|---|
-| Claude Code (colon-form) | `pipeline/commands/multi-agent.md` | ~300 lines  -  thin dispatcher that routes to `$HOME/.claude/multi-agent-refs/phases/phase-N-*.md` on demand | Claude Code supports lazy-loaded reference files (`@refs/phases/...`), so only the active phase's docs enter the context window. Saves tokens. |
-| Copilot CLI (dash-form) | `pipeline/skills/shared/core/multi-agent/SKILL.md` | ~830 lines  -  full inline orchestrator with all 8 phase specs embedded | Copilot CLI loads the whole SKILL.md into context once the skill is dispatched; it doesn't have an equivalent of Claude's ref-file loading pattern. Embedding keeps behavior identical without relying on a feature Copilot lacks. |
+| Claude Code (colon-form) | `pipeline/commands/multi-agent/SKILL.md` | ~300 lines  -  thin dispatcher that routes to `$HOME/.claude/multi-agent-refs/phases/phase-N-*.md` on demand | Claude Code lazy-loads reference files, so only the active phase's docs enter the context window. Saves tokens. |
+| Copilot CLI (dash-form) | `pipeline/skills/shared/core/multi-agent/SKILL.md` | ~830 lines  -  full inline orchestrator with all 8 phase specs embedded | Copilot CLI loads the whole SKILL.md once the skill is dispatched; it has no equivalent of Claude's ref-file loading. Embedding keeps behavior identical without relying on a feature Copilot lacks. |
+| Codex CLI | installed as `~/.codex/skills/multi-agent/SKILL.md`, generated from the Claude dispatcher | thin dispatcher, refs under `~/.codex/multi-agent-refs/` | Codex reads files on demand, so it takes the Claude shape  -  **and it has to.** See below. |
+
+### Why Codex takes the thin-dispatcher shape, and must keep it
+
+Codex assembles every discovered skill's name + description into a single prompt
+block and **silently drops entries when that block overflows**. Measured against
+Codex 0.145 during the install design: installing one plugin that declares 142
+skills took the block from 11 skills / 4,710 bytes to 83 skills / 22,111 bytes  -
+only **75 of the 142** surfaced, **and an unrelated user-scope skill was evicted**.
+Removing the plugin brought it back.
+
+So shipping the 43 sub-commands as peer skills on Codex would silently lose
+pipeline commands next to any stack toolkit, with no error anywhere. The pipeline
+therefore contributes **exactly one** skill on Codex (`multi-agent`) and keeps the
+43 sub-command specs as reference files that cost nothing until read.
+
+**Do not "fix" this by adding per-command skills on Codex.** The layout is
+capability-derived, and `smoke-install-layout.sh` fails if the Codex skills tree
+gains a second pipeline entry.
+
+### Parity axis differs per host
+
+Claude Code and Copilot CLI are compared on their **skill directory sets**. Codex is
+compared on its **ref set**: the 43 command specs must all exist under
+`~/.codex/multi-agent-refs/commands/<cmd>/SKILL.md`, and
+`smoke-codex-install.sh` asserts the count against the source tree. Comparing Codex
+on skill directories would demand exactly the layout that breaks it.
 
 **What must stay identical** (byte-level) across the two files:
 
@@ -175,13 +205,17 @@ argument-hint: "<input hint>"
 
 ### 4.1 TaskCreate ↔ phase-tracker.sh
 
-| Concept | Claude Code | Copilot CLI |
-|---|---|---|
-| Register a phase | `TaskCreate` tool call with subject/description | `phase-tracker.sh add <N> <name>` |
-| Mark a phase in-progress | `TaskUpdate` → `in_progress` | `phase-tracker.sh update <N> in_progress` |
-| Mark a phase complete | `TaskUpdate` → `completed` | `phase-tracker.sh update <N> completed` |
-| Mark a phase failed | `TaskUpdate` → `completed` + log failure in agent-log | `phase-tracker.sh update <N> failed` |
-| Sub-phase progress | TaskCreate with `addBlockedBy` | `phase-tracker.sh sub <N> <sub> <name> <status>` |
+| Concept | Claude Code | Copilot CLI | Codex CLI |
+|---|---|---|---|
+| Register a phase | `TaskCreate` tool call with subject/description | `phase-tracker.sh add <N> <name>` | `update_plan` step, `status: pending` |
+| Mark a phase in-progress | `TaskUpdate` → `in_progress` | `phase-tracker.sh update <N> in_progress` | `update_plan` step → `in_progress` |
+| Mark a phase complete | `TaskUpdate` → `completed` | `phase-tracker.sh update <N> completed` | `update_plan` step → `completed` |
+| Mark a phase failed | `TaskUpdate` → `completed` + log failure in agent-log | `phase-tracker.sh update <N> failed` | `update_plan` step → `completed` + failure in agent-log |
+| Sub-phase progress | TaskCreate with `addBlockedBy` | `phase-tracker.sh sub <N> <sub> <name> <status>` | `phase-tracker.sh sub ...` (the plan tool has no nesting) |
+
+`update_plan` takes the FULL step list, not a delta, so each boundary rewrites the
+whole plan. It must never be called in parallel with another tool, and it is
+unavailable in Codex plan mode  -  fall back to `phase-tracker.sh render` there.
 
 ### 4.2 Contract
 
@@ -227,9 +261,9 @@ Modifier flags are orthogonal and compose:
 
 ## 7. Platform Guards (macOS / Linux / WSL)
 
-Commands invoked via Copilot CLI may run on Linux or WSL. Claude Code currently macOS-only. Shell code in `pipeline/skills/shared/core/` command files and in `pipeline/lib` / `pipeline/scripts` must be portable.
+Commands invoked via Copilot CLI or Codex CLI may run on Linux or WSL. Claude Code currently macOS-only. Shell code in `pipeline/skills/shared/core/` command files and in `pipeline/lib` / `pipeline/scripts` must be portable.
 
-For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` on Copilot installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic  -  no per-OS branching needed.
+For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` / `~/.codex/lib/credential-store.sh` on those installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic  -  no per-OS branching needed.
 
 | Purpose | Canonical (cross-platform) | Underlying backend (for reference / debugging) |
 |---|---|---|

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -101,3 +101,32 @@ per-phase `model` field already carries the override).
   reviewer models (GPT-5.4 + Opus + Sonnet - Fable 5 is not offered there) and
   does not use this persona ladder. Only Claude Code dispatches Reviewer-1 on
   Fable.
+
+## Codex CLI
+
+Codex offers no Anthropic models, so the tier names map onto OpenAI models plus a
+reasoning effort - effort carries the depth distinction that the model id carries
+on Claude Code. The map is applied at install time by
+`install/_codex-agents.mjs`, which writes `model` + `model_reasoning_effort` into
+each `~/.codex/agents/<persona>.toml`:
+
+| Tier | Codex model | Effort |
+|---|---|---|
+| `fable` | `gpt-5.6` | `xhigh` |
+| `opus` | `gpt-5.6` | `high` |
+| `sonnet` | `gpt-5.4` | `medium` |
+| `haiku` | `gpt-5.6-terra` | `low` |
+
+Ladder on Codex: `gpt-5.6 @ xhigh -> gpt-5.6 @ high -> gpt-5.4 -> gpt-5.6-terra`.
+The first step down lowers effort rather than switching model, which is the
+cheapest useful degradation when the top tier is rate-limited rather than
+unavailable.
+
+**Per-dispatch override on Codex** goes through `spawn_agent`, and it MUST pass
+`fork_turns: "none"` (or a positive integer). A full-history fork inherits the
+parent model and reasoning effort and silently discards the override, so a
+fallback that omits it appears to apply while changing nothing.
+
+The three model ids above live in exactly three places - this table,
+`pipeline/scripts/cost-table.json`, and the Phase 4 reviewer matrix - so an OpenAI
+rename is a three-file change.

package/pipeline/multi-agent-refs/features/review-multi-repo.md

@@ -20,7 +20,7 @@ for proj in $(jq -r '.projects[] | "\(.name)\t\(.worktreePath)\t\(.baseBranch)"'
 done
 ```
 
-Same reviewer set (Fable-or-Opus / GPT-5.4 / Sonnet) receive `COMBINED_DIFF` with a multi-repo prefix in the system prompt:
+Same reviewer set (per host: Fable+Sonnet on Claude Code, Opus/GPT-5.4/Sonnet on Copilot CLI, gpt-5.6/gpt-5.4/gpt-5.6 on Codex CLI) receive `COMBINED_DIFF` with a multi-repo prefix in the system prompt:
 
 ```
 This is a multi-repo task spanning {N} repos: {repo names}.

package/pipeline/multi-agent-refs/phases/log-format.md

@@ -101,7 +101,7 @@ Every phase that dispatches a billable LLM agent MUST forward its token totals t
 
 ```bash
 pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> <event> \
-  model=<fable|opus|sonnet|haiku|gpt-5.4> tokens_in=$IN tokens_out=$OUT tokens_cached=$CACHED duration_ms=$DUR
+  model=<fable|opus|sonnet|haiku|gpt-5.4|gpt-5.6|gpt-5.6-terra> tokens_in=$IN tokens_out=$OUT tokens_cached=$CACHED duration_ms=$DUR
 LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> tokens \
   model=<...> tokens_in=$IN tokens_out=$OUT tokens_cached=$CACHED
 ```

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -300,11 +300,23 @@ Branch name is deterministic  -  no user confirmation needed.
 6. If empty after kebab (e.g. all-emoji title) → fall back to `task-{shortId}`
 
 **Collision handling** (automatic  -  no prompt):
-- Probe local + remote for existing branch:
+- Probe local + remote for existing branch. **Distinguish "no such ref" from "the
+  probe failed"**: with `2>/dev/null` and an empty-output test they look identical,
+  so an auth or network failure reads as "no collision" and the run creates a
+  branch that already exists on the remote  -  surfacing as a rejected push at
+  Phase 6, far from its cause.
   ```bash
   LOCAL_HIT=$(git -C "$root" rev-parse --verify --quiet "refs/heads/$branch")
-  REMOTE_HIT=$(git -C "$root" ls-remote --exit-code --heads origin "$branch" 2>/dev/null)
+  REMOTE_ERR=$(git -C "$root" ls-remote --exit-code --heads origin "$branch" 2>&1 >/dev/null)
+  REMOTE_RC=$?
+  # 0 = ref exists (collision) · 2 = no matching ref (authoritative "free")
+  # anything else = the probe itself failed; REMOTE_ERR holds why
   ```
+- `REMOTE_RC` is 0 or 2 → treat as authoritative
+- `REMOTE_RC` is anything else → the remote answer is **unknown**, not "free". Log
+  `Remote collision probe failed: <REMOTE_ERR>`, fall back to the local check only,
+  and record `"remoteCollisionProbe": "failed"` in `agent-state.json` so Phase 6
+  expects a possible non-fast-forward and re-checks before pushing.
 - No collision → use as-is
 - Collision found → append `-v2`, `-v3`, etc. until unique:
   `bugfix/ABC-12345` exists → `bugfix/ABC-12345-v2`
@@ -519,3 +531,32 @@ Phase 7 cost rollup carries this as a `phase 0` line item so the user sees ambig
 **Progress (per `$HOME/.claude/multi-agent-refs/progress-contract.md`):** emit one `→ <verb> <object>` line for each of: `→ parsing input`, `→ checking token <service>`, `→ scanning project <root>`, `→ creating worktree <repo>`, `→ binding identity <name>`, `→ writing state`. When `clarifyAmbiguous.enabled`, also emit `→ scoring task ambiguity` before Step 8 and `→ asking clarifying questions <N>` when `stopAndAsk` fires.
 
 **Save preferences**: Write updated prefs to `$HOME/.claude/multi-agent-preferences.json` with all Phase 0 selections.
+
+---
+
+#### Phase 0 exit gate (BLOCKING  -  run before marking the phase completed)
+
+Phase 0 owns `agent-state.json`. Do not call
+`phase-tracker.sh update 0 completed` until this gate passes:
+
+```bash
+node "$HOME/.claude/scripts/phase0-exit-gate.mjs" "$TASK_ID" --input "$ORIGINAL_INPUT"
+```
+
+It asserts three things, each of which has failed silently in a real run:
+
+1. **`agent-state.json` exists.** A run once reported Phase 0 `completed` with only
+   `tracker-state.json` on disk. Every later phase then reasons from fields that are
+   not there.
+2. **`taskType` is set.** Phase 3 branches on it (Step 7). Absent, a Figma-driven
+   screen is dispatched as generic development, skipping the stack plugin's
+   token-compliance check, Code Connect publish and component review. That run
+   guessed `16` where the frame said `Spacing/12`, and half its commits were rework.
+3. **A Figma reference forces `taskType: "component"`, and `figmaAccess.tier` is
+   recorded.** Without the tier, a later phase cannot tell "the design was confirmed"
+   from "the design was never fetched"  -  which is exactly when spacing gets guessed.
+
+A failure is a halt, not a warning. Fix the state and re-run the gate; the phase
+stays `in_progress` until it passes. **Never** mark Phase 0 completed on the grounds
+that its steps ran  -  the gate checks the output, and the output is what Phase 3
+consumes.

package/pipeline/multi-agent-refs/phases/phase-1-analysis.md

@@ -63,7 +63,14 @@ When `state.contextLinks[]` or the task description contains a Figma reference,
 | 2 (REST) | `GET /v1/files/{fileKey}/nodes?ids={nodeId}` + `GET /v1/images/{fileKey}?ids={nodeId}&format=png&scale=2`, PAT via `~/.claude/lib/credential-store.sh get <logical-key>` (logical key = `prefs.global.keychainMapping.figma_pat`); canonical component resolved from repo `*.figma.swift` / `*.figma.kt` mapping keyed by `fileKey` + `nodeId` | same shape, but `codeConnectSnippets[]` is empty when repo mapping is absent (record an Open Question), `tier: 2` |
 | 3 (screenshot) | User-attached screenshot stored alongside task evidence | degraded record: `codeConnectSnippets: []`, forced Open Question, `tier: 3` |
 
-Persist results under `state.evidence.figma[]`. Halt the run if all three tiers fail; never substitute primitives or invent layout from prose. Canonical chain reference: `pipeline/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain".
+Persist results under `state.evidence.figma[]`. Halt the run if all three tiers fail; never substitute primitives or invent layout from prose.
+
+**Spacing goes in by token NAME, per atom  -  never a pixel number.** `tokens[]` must
+carry each frame's spacing/padding as Figma names them (`Spacing/12`, edge `4`), keyed
+to the atom. Phase 3 cannot call Figma, so what is missed here is gone: one run guessed
+`16` where the frame said `Spacing/12` and the sheet was rebuilt. A pixel number also
+cannot map back to a token. No spacing entries on a UI frame is a **capture failure**,
+not an empty frame  -  Open Question and halt. Canonical chain reference: `pipeline/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain".
 
 **Telemetry (required for the no-MCP gate):** Tier 1 uses `mcp__claude_ai_Figma__*` tools. Every such MCP invocation MUST append an entry to `state.telemetry.mcpCalls[]` as `{ "tool": "<full mcp tool name>", "phase": 1, "timestamp": "<ISO-8601>" }`. This is the only phase permitted to record `phase: 1` (or `0`) entries; `smoke-no-mcp-in-dev-phases.sh` fails the run if any entry carries `phase >= 2`. Recording is what makes that BLOCKING contract enforceable  -  an MCP call left unrecorded defeats the gate, so record every one.
 
@@ -73,6 +80,22 @@ Progress lines:
 → figma evidence: <N> frames captured (tier=<n>, code-connect=<M>, open-questions=<K>)
 ```
 
+#### Step 1.45  -  Reuse discovery (BLOCKING for new services, entities, mappers)
+
+Before proposing any new service call, entity or mapper, search for what already
+covers it. Record hits under `state.reuse[]` and cite them in the doc; proposing new
+code over a hit needs a one-line reason.
+
+Search for: a **wrapper** over the same endpoint (especially one supplying parameters
+the generated call leaves optional); an **entity** for the same concept (module's
+shared entities first, then siblings); a **mapper** over the same response; a **screen**
+doing the same interaction.
+
+Why blocking: one run proposed a new repository over an endpoint a sibling already
+wrapped **with its country parameter**, called the generated method without it, and
+re-invented an entity the module had. Half that branch's commits went to converging
+back. "Copy X and rename it" is the reuse answer, not a hint  -  name X's files.
+
 #### Step 1.5  -  External Context Injection (`state.contextLinks[]`)
 
 Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, graylog, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt  -  so the agent doesn't re-discover what the ticket already pointed at. `state.graylogContext` is injected there too, as diagnostic context (advisory only). Failures never fatal (a non-zero fetcher exit is marked skipped and the analysis still runs, exactly as for crashlytics); pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `$HOME/.claude/multi-agent-refs/features/external-context-injection.md`.

package/pipeline/multi-agent-refs/phases/phase-3-dev.md

@@ -367,3 +367,35 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens 3 <input_count> <output_count
 The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 3  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
 
 If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.
+
+
+#### Generated trees are not yours to edit
+
+Many repos generate part of their source: a service client from an OpenAPI spec, mock
+scenario indexes, localization keys, testing identifiers, design tokens. A generated
+file is regenerated on the next build, so an edit there is lost silently, and the
+matching hand-authored tree is the one that takes the change.
+
+Before writing into any path, check whether it is generated:
+
+```bash
+# a Generated/ segment, or a header saying so, is the signal
+find . -type d -name Generated -not -path './.*' | head
+grep -rl "DO NOT EDIT\|auto-generated\|Generated by" --include="*.swift" --include="*.kt" . | head
+```
+
+The pairing is usually `Generated/<x>` for output and `Custom<X>/` or
+`CustomSources/` for input. Two concrete shapes seen in the wild:
+
+| Want to | Wrong place | Right place |
+|---|---|---|
+| add a mock fixture / named scenario | a `Fixtures/` file under a generated tree | the repo's custom fixture tree, plus registering the scenario in the generated index the build reads |
+| add or change a service endpoint | the generated client method | the OpenAPI source the generator consumes, then regenerate |
+
+One run wrote a mock fixture into the generated fixtures tree; the fix commit moved it
+to the custom tree and registered the scenario in the generated index. Same content,
+wrong side of the generator, and the Debug menu never showed it.
+
+When the analysis doc has not recorded which trees are generated, that is a Phase 1
+gap  -  say so rather than guessing, since guessing wrong is invisible until the next
+regeneration.