@mmerterden/multi-agent-pipeline 12.11.0 → 13.0.0

package/pipeline/schemas/reviewer-output.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/reviewer-output.schema.json",
   "version": "1.0.0",
   "title": "Multi-Agent Pipeline  -  Phase 4 reviewer output",
-  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Reviewer set is CLI-aware: Claude Code dispatches 2 parallel reviewers (Opus, Sonnet); Copilot CLI dispatches 3 (GPT-5.4, Opus, Sonnet). Every reviewer must return an object matching this shape before Opus triage merges them.",
+  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Reviewer set is CLI-aware: Claude Code dispatches 2 parallel reviewers (Fable, Sonnet); Copilot CLI dispatches 3 (Opus, GPT-5.4, Sonnet); Codex CLI dispatches 3 (gpt-5.6 at xhigh, gpt-5.4, gpt-5.6 at medium). Every reviewer must return an object matching this shape before Opus triage merges them.",
   "type": "object",
   "additionalProperties": false,
   "required": ["findings", "approved"],

package/pipeline/schemas/triage-output.schema.json

@@ -86,7 +86,7 @@
         "reviewerCount": {
           "type": "integer",
           "minimum": 1,
-          "description": "Reviewers dispatched this iteration (Claude Code = 2, Copilot CLI = 3)."
+          "description": "Reviewers dispatched this iteration (Claude Code = 2, Copilot CLI = 3, Codex CLI = 3)."
         },
         "verdict": {
           "type": "string",

package/pipeline/scripts/cost-table.json

@@ -32,7 +32,21 @@
       "outPerMtok": 30.0,
       "cacheReadPerMtok": 1.0,
       "modelId": "gpt-5.4",
-      "note": "Copilot CLI Reviewer 2  -  approximate; verify against OpenAI pricing page before relying on totals."
+      "note": "Copilot CLI Reviewer 2 and Codex CLI Reviewer 2  -  approximate; verify against OpenAI pricing page before relying on totals."
+    },
+    "gpt-5.6": {
+      "inPerMtok": 10.0,
+      "outPerMtok": 30.0,
+      "cacheReadPerMtok": 1.0,
+      "modelId": "gpt-5.6",
+      "note": "Codex CLI top tier  -  Reviewer 1 at xhigh effort, Reviewer 3 at medium, triage at max, and the fable/opus rungs of the Codex persona tier map. Reasoning effort changes output volume, not the per-token rate, so one entry covers every effort level. Approximate; verify against OpenAI pricing before relying on totals."
+    },
+    "gpt-5.6-terra": {
+      "inPerMtok": 1.0,
+      "outPerMtok": 5.0,
+      "cacheReadPerMtok": 0.1,
+      "modelId": "gpt-5.6-terra",
+      "note": "Codex CLI floor tier  -  speed-optimised, maps the haiku rung of the Codex persona tier map (task-clarifier). Approximate; verify against OpenAI pricing before relying on totals."
     }
   }
 }

package/pipeline/scripts/smoke-cross-cli-behavior.sh

@@ -185,11 +185,12 @@ else
 fi
 
 # ──────────────────────────────────────────────────────────────────────────
-# CLI-aware reviewer-count contract: Claude Code = 2 reviewers (Opus + Sonnet),
-# Copilot CLI = 3 (GPT-5.4 + Opus + Sonnet). Nothing in code enforces the count
-# (the orchestrator dispatches per the doc), so lock the CONTRACT here against
-# drift across the phase doc, the schema, and the consensus block.
-echo "→ reviewer-count contract (Claude=2, Copilot=3)"
+# CLI-aware reviewer-count contract: Claude Code = 2 (Fable + Sonnet), Copilot CLI
+# = 3 (Opus + GPT-5.4 + Sonnet), Codex CLI = 3 (gpt-5.6 xhigh + gpt-5.4 + gpt-5.6
+# medium). Nothing in code enforces the count (the orchestrator dispatches per the
+# doc), so lock the CONTRACT here against drift across the phase doc, the schema,
+# and the consensus block.
+echo "→ reviewer-count contract (Claude=2, Copilot=3, Codex=3)"
 # `/multi-agent:update` runs this smoke on the user's machine, where the tree is
 # ~/.claude/{schemas,multi-agent-refs} and NOT <root>/pipeline/*. Resolving the
 # root by hand here reported three phantom failures in an install, which reads as
@@ -202,16 +203,30 @@ TRSCHEMA="${MA_SCHEMAS:+$MA_SCHEMAS/triage-output.schema.json}"
 
 if [ -z "$P4" ] || [ ! -f "$P4" ]; then
   echo "  ↷ SKIP: phase-4-review.md not present in this $MA_LAYOUT layout"
-elif grep -qiE "Claude Code (dispatches|=|:) ?2|2-model" "$P4" && grep -qiE "Copilot CLI (dispatches|=|:) ?3|3-model" "$P4"; then
-  pass "phase-4-review declares Claude=2 / Copilot=3 reviewers"
+elif grep -qiE "Claude Code (dispatches|=|:) ?2|2-model" "$P4" \
+  && grep -qiE "Copilot CLI (dispatches|=|:) ?3|3-model" "$P4" \
+  && grep -qiE "Codex CLI (dispatches|=|:) ?3|Claude Code 2, Copilot CLI 3, Codex CLI 3" "$P4"; then
+  pass "phase-4-review declares Claude=2 / Copilot=3 / Codex=3 reviewers"
 else
-  fail "phase-4-review does not declare the CLI-aware reviewer count"
+  fail "phase-4-review does not declare the CLI-aware reviewer count for all three hosts"
+fi
+
+# The two Codex constraints are silent-failure shaped, so the contract has to name
+# them: a spawn without fork_turns collapses the panel onto one model, and the
+# 4-slot ceiling (orchestrator included) is why the count is 3 and not more.
+if [ -n "$P4" ] && [ -f "$P4" ]; then
+  if grep -q 'fork_turns' "$P4" && grep -qiE "concurrency|slots" "$P4"; then
+    pass "phase-4-review documents the fork_turns override rule + the concurrency ceiling"
+  else
+    fail "phase-4-review must document fork_turns and the Codex concurrency ceiling"
+  fi
 fi
 
 if [ -z "$REVSCHEMA" ] || [ ! -f "$REVSCHEMA" ]; then
   echo "  ↷ SKIP: reviewer-output.schema.json not present in this $MA_LAYOUT layout"
-elif grep -qi "Copilot CLI" "$REVSCHEMA" && grep -qi "Claude" "$REVSCHEMA"; then
-  pass "reviewer-output schema notes the CLI-aware reviewer set"
+elif grep -qi "Copilot CLI" "$REVSCHEMA" && grep -qi "Claude" "$REVSCHEMA" \
+  && grep -qi "Codex" "$REVSCHEMA"; then
+  pass "reviewer-output schema notes the CLI-aware reviewer set (all three hosts)"
 else
   fail "reviewer-output schema missing the CLI-aware note"
 fi

package/pipeline/scripts/uninstall.mjs

@@ -36,6 +36,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { execFileSync } from "child_process";
 import { join } from "path";
 import { pathToFileURL } from "url";
 import { createInterface } from "readline";
@@ -123,6 +124,54 @@ function rmIfExists(path) {
   return true;
 }
 
+/**
+ * Remove generated Codex agent TOML files, identified by the header the
+ * installer stamps on them. A user-authored `.toml` sharing a persona name is
+ * left alone - `~/.codex/agents/` is a co-owned directory.
+ *
+ * @param {string} agentsDir
+ * @returns {number} files removed
+ */
+function removeGeneratedCodexAgents(agentsDir) {
+  if (!existsSync(agentsDir)) return 0;
+  const MARKER = "# Generated by multi-agent-pipeline install --codex.";
+  let removed = 0;
+  for (const name of readdirSync(agentsDir)) {
+    if (!name.endsWith(".toml")) continue;
+    const path = join(agentsDir, name);
+    try {
+      if (!readFileSync(path, "utf-8").startsWith(MARKER)) continue;
+    } catch {
+      continue;
+    }
+    if (rmIfExists(path)) removed++;
+  }
+  if (removed > 0) console.log(`    removed ${removed} generated agent file(s) under ${agentsDir}`);
+  return removed;
+}
+
+/**
+ * Hand the dev-toolkit MCP registration back to Codex.
+ *
+ * Best-effort: a missing `codex` binary or an already-absent entry is not an
+ * uninstall failure. Never edits `config.toml` directly - Codex keeps
+ * marketplace and plugin state in the same file.
+ */
+function deregisterCodexMcpServer() {
+  if (dryRun) {
+    report("would run", "codex mcp remove dev-toolkit");
+    return;
+  }
+  try {
+    execFileSync("codex", ["mcp", "remove", "dev-toolkit"], { stdio: "pipe", timeout: 20_000 });
+    console.log("    removed: dev-toolkit MCP registration");
+  } catch {
+    console.log(
+      "    note: could not run `codex mcp remove dev-toolkit` (codex not on PATH, or not registered)",
+    );
+  }
+}
+
 /**
  * Remove every directory under `parent` whose name matches a predicate.
  * @param {string} parent
@@ -160,6 +209,32 @@ function rmMatchingFiles(parent, predicate) {
 // (v11.4.1+). Must stay in sync with INSTRUCTIONS_END_MARKER there.
 const COPILOT_END_MARKER = "<!-- multi-agent-pipeline:copilot-instructions:end -->";
 
+/**
+ * Every end marker the installers write. Both host instruction files share the
+ * same START marker but terminate with their own comment, so a single-marker
+ * lookup silently falls through to the legacy heading-bounded path - and since
+ * the managed body has no top-level heading after the first, that path treats
+ * ALL trailing user content as part of the block and deletes it.
+ */
+const MANAGED_END_MARKERS = [
+  COPILOT_END_MARKER,
+  "<!-- multi-agent-pipeline:codex-instructions:end -->",
+];
+
+/**
+ * Locate whichever managed end marker terminates this block.
+ *
+ * @param {string} fromStart - content from the start marker onward
+ * @returns {{index: number, length: number}} index -1 when none is present
+ */
+function findManagedEndMarker(fromStart) {
+  for (const marker of MANAGED_END_MARKERS) {
+    const index = fromStart.indexOf(marker);
+    if (index >= 0) return { index, length: marker.length };
+  }
+  return { index: -1, length: 0 };
+}
+
 /**
  * Legacy copilot-instructions files (written before the end marker existed)
  * have no explicit terminator. Bound the pipeline span at the next top-level
@@ -205,10 +280,10 @@ function stripManagedBlock(filePath) {
       if (idx >= 0) {
         const before = content.slice(0, idx).trimEnd();
         const fromStart = content.slice(idx);
-        const endIdx = fromStart.indexOf(COPILOT_END_MARKER);
+        const end = findManagedEndMarker(fromStart);
         const rawTrailing =
-          endIdx >= 0
-            ? fromStart.slice(endIdx + COPILOT_END_MARKER.length)
+          end.index >= 0
+            ? fromStart.slice(end.index + end.length)
             : legacyTrailingContent(fromStart);
         const trailing = rawTrailing.replace(/^[\r\n]+/, "").trimEnd();
         let remaining = before;
@@ -332,7 +407,7 @@ export async function main() {
     );
   if (forCodex)
     console.log(
-      "    - OpenAI Codex CLI (~/.codex/prompts/multi-agent.md + AGENTS.md block + config.toml mcp block)",
+      "    - Codex CLI (~/.codex: skills/multi-agent, multi-agent-refs, agents/*.toml, prompts/multi-agent.md, scripts, lib, schemas, rules, AGENTS.md block, dev-toolkit MCP entry)",
     );
   console.log("");
   if (allData) {
@@ -478,14 +553,35 @@ export async function main() {
 
   if (forCodex && HOME) {
     console.log("");
-    console.log("  [OpenAI Codex CLI  -  legacy cleanup] Removing from ~/.codex...");
+    console.log("  [Codex CLI] Removing from ~/.codex...");
     const CODEX = join(HOME, ".codex");
+
+    // Wholly pipeline-owned trees.
+    rmIfExists(join(CODEX, "multi-agent-refs"));
+    rmIfExists(join(CODEX, "scripts"));
+    rmIfExists(join(CODEX, "lib"));
+    rmIfExists(join(CODEX, "schemas"));
+    rmIfExists(join(CODEX, "rules"));
+    rmIfExists(join(CODEX, ".pipeline-version"));
+
+    // Co-owned dirs: remove only what the pipeline wrote. `skills/` holds
+    // Codex's own `.system` set plus user skills; `prompts/` and `agents/` hold
+    // user-authored files.
+    const skills = join(CODEX, "skills");
+    const n = rmMatchingDirs(
+      skills,
+      (name) => name === "multi-agent" || name.startsWith("multi-agent-"),
+    );
+    if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(CODEX, "prompts", "multi-agent.md"));
+    removeGeneratedCodexAgents(join(CODEX, "agents"));
+
     stripManagedBlock(join(CODEX, "AGENTS.md"));
-    if (existsSync(join(CODEX, "config.toml")))
-      console.log(
-        "    note: ~/.codex/config.toml left untouched (may hold user MCP servers)  -  remove pipeline entries manually if present",
-      );
+
+    // The MCP entry was written by `codex mcp add`, so hand it back the same
+    // way rather than editing config.toml - Codex also stores marketplace and
+    // plugin state in that file.
+    deregisterCodexMcpServer();
   }
 
   console.log("");

package/pipeline/scripts/update-check.sh

@@ -48,7 +48,8 @@ if [ -z "$LOCAL_VERSION" ]; then
 fi
 # npx-only installs have no repo clone; the installer stamps the version here.
 if [ -z "$LOCAL_VERSION" ]; then
-  for marker in "$HOME/.claude/.pipeline-version" "$HOME/.copilot/.pipeline-version"; do
+  for marker in "$HOME/.claude/.pipeline-version" "$HOME/.copilot/.pipeline-version" \
+                "$HOME/.codex/.pipeline-version"; do
     if [ -f "$marker" ]; then
       LOCAL_VERSION=$(head -1 "$marker" 2>/dev/null | tr -d '[:space:]')
       [ -n "$LOCAL_VERSION" ] && break

package/pipeline/skills/shared/core/multi-agent-language/SKILL.md

@@ -17,7 +17,7 @@ Two-axis language preference for the pipeline:
 | `promptLanguage` | Interactive prompts during a pipeline run (account picker, project picker, dev-context picker, base-branch picker, branch-name picker, maturity ack, channels picker, Phase 5 test prompt, Phase 6 local-checkout prompt) | `prefs.global.promptLanguage` | **Fixed to `en`**  -  never toggled by this skill |
 | `outputLanguage` | Assistant's explanations, status updates, error messages, and pipeline-generated reports rendered to the user (NOT external payloads) | `prefs.global.outputLanguage` | Toggled by this skill |
 
-**Why promptLanguage is fixed:** Pipeline picker UI, confirmation prompts, and error messages are authored in English to keep tooling consistent across CLIs. Mixing Turkish prompts into otherwise-English skill output looks inconsistent. Only the assistant's free-form replies follow `outputLanguage`.
+**Why promptLanguage is fixed:** it governs the picker's structural chrome only  -  `AskUserQuestion` `label` (button text) and `header` (chip), host error UI, and internal contract identifiers. Those stay English so tooling reads the same across CLIs. Everything a user actually reads follows `outputLanguage`, including the picker `question` and each option's `description`, per the canonical per-field matrix in `multi-agent-refs/rules.md`. A picker whose question is English on a Turkish run is a bug, not the contract.
 
 **Always English regardless of either field**: commit messages, PR titles/bodies, Jira comments, wiki pages, reviewer/triage system prompts, agent-log.md payloads, skill-picker / confirmation / error UI exposed by the CLI host.
 
@@ -83,5 +83,5 @@ Render in the new outputLanguage:
 
 - `multi-agent-setup`  -  first-run language picker (asks only outputLanguage; promptLanguage seeded as `en`)
 - `prefs.schema.json`  -  `global.promptLanguage` (fixed `"en"`) and `global.outputLanguage`
-- Phase 5 / Phase 6  -  read promptLanguage for interactive prompts (always English)
+- Phase 5 / Phase 6  -  interactive prompts follow the per-field matrix: `question` + `description` in `outputLanguage`, `label` + `header` English
 - `multi-agent-help`  -  reads outputLanguage for its own copy

package/pipeline/skills/shared/core/multi-agent-setup/SKILL.md

@@ -15,7 +15,7 @@ Ask BEFORE anything else. The pipeline has two language fields:
 
 | Field | Controls | Configurable? |
 |---|---|---|
-| `promptLanguage` | Interactive pickers and prompts during pipeline runs (account, project, branch, channels, Phase 5/6 confirmations) | **No  -  fixed to `en`.** Picker UI is always English. |
+| `promptLanguage` | The picker's structural UI chrome only: `AskUserQuestion` `label` + `header`, host error UI, internal contract identifiers | **No  -  fixed to `en`.** Button and chip text stays English. |
 | `outputLanguage` | The assistant's non-interactive explanations, status updates, error messages, and pipeline-generated reports | Yes  -  set here, change later via `/multi-agent-language <en\|tr>` |
 
 `promptLanguage` is seeded as `"en"` and never offered to the user. External payloads (commits, PR/Jira/wiki, reviewer/triage prompts, agent-log.md) always stay English regardless.
@@ -278,6 +278,53 @@ pbcopy < /dev/null
 # ~/.claude/settings.json -> mcpServers -> figma
 ```
 
+### App Store Connect Credentials (optional, iOS only)
+
+Unlocks Gate 2 of `multi-agent-testflight-validation`  -  Apple's own
+`altool --validate-app`, the only check that sees an unregistered bundle ID, a
+profile that does not match the App Store Connect app record, or a version+build
+pair already used. Skipping is a first-class answer: the validation command still
+runs its static audit and guideline review and reports Gate 2 as `SKIPPED` with
+the reason, never as a pass.
+
+Ask (picker): **API key** / **Apple ID + app-specific password** / **Skip**.
+
+**API key**  -  needs an Admin or App Manager role in App Store Connect. Map the key
+id and issuer id as `appstore_connect_key_id` / `appstore_connect_issuer_id`. The
+private key is a FILE and never enters the credential store; it goes to one of the
+directories altool searches:
+
+```bash
+ls ~/.appstoreconnect/private_keys/AuthKey_*.p8 2>/dev/null \
+  || echo "MISSING: put AuthKey_<keyId>.p8 in ~/.appstoreconnect/private_keys/"
+```
+
+**Apple ID + app-specific password**  -  usable by **any Apple ID holder, no elevated
+role**, which is the realistic path when API-key creation is not permitted on the
+account. Lead with this option when the user says they cannot create an API key.
+The password goes into Apple's own keychain helper, which is what
+`altool -p @keychain:<item>` reads  -  never into chat, never into an argument:
+
+```bash
+# export AC_PASSWORD_ONCE in your own shell first, for this one command
+xcrun altool --store-password-in-keychain-item "<item-name>" \
+  -u "<apple-id>" -p @env:AC_PASSWORD_ONCE
+```
+
+Map only the ITEM NAME as `appstore_connect_password_item`, plus the Apple ID as
+`appstore_connect_apple_id`. The password stays in the keychain and is referenced,
+never read by the pipeline.
+
+**Multi-provider accounts.** A corporate Apple ID often belongs to several
+providers and altool fails opaquely without one. Resolve it once with
+`ios_testflight_validate({list_providers: true, ...})` and store the id under
+`prefs.projects[<key>].appStoreConnect.providerPublicId`  -  per-project, since a
+user can ship for more than one team.
+
+A credential that resolves but is rejected (401/403) follows the Expired-token
+decision (Regenerate / Use a different token / Skip and continue) rather than
+being silently dropped.
+
 ### Security Rules
 
 - Never paste tokens into terminal or chat  -  use `pbpaste` for input

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -20,6 +20,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 |---|-------|-----|-----|
 | 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` | source |
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
+| 2b | Codex CLI | `~/.codex/AGENTS.md` + `~/.codex/skills/multi-agent/` + `~/.codex/multi-agent-refs/` + `~/.codex/agents/*.toml` | <- from Claude (path-rewritten) |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
 | 4 | Website | `{owner}/{website-host}` | <- version + features |
 | 5 | dev-toolkit MCP server | resolved from `prefs.global.devToolkit` or the `mcpServers` registration | own repo: gate, commit, publish |
@@ -30,7 +31,8 @@ Run all steps automatically:
 
 ```
 Step 1: DETECT      Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 42 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 43 sub-command skills)
+Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 43 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
 Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
@@ -93,6 +95,41 @@ If nothing is stale -> report "All targets up to date" and stop.
    - `~/.claude/settings.json`
 
 
+## Codex Sync (Step 2b)
+
+This step does **not** hand-copy files. The Codex tree is a *transform* of the Claude
+tree, not a mirror: the 43 sub-command specs become reference files (Codex silently
+truncates its skills block  -  see `cross-cli-contract.md` 2.6), every reference to a
+CLI-owned tree is retargeted (`agents/<persona>.md` becomes `.toml`, the dispatcher
+becomes the router skill), the 8 personas are regenerated as TOML with a model +
+reasoning-effort map, and shared state (`logs/`, prefs, `knowledge/`) is deliberately
+left under `~/.claude`.
+
+That transform lives in `install/codex.mjs` and is gate-locked by
+`smoke-codex-install.sh`. Describing it again in prose would give the pipeline two
+definitions of the same thing, and the prose one would rot. So the step runs the
+installer:
+
+```bash
+cd "$HOME/multi-agent-pipeline" && node install.js --codex
+```
+
+Verify:
+
+```bash
+ls -1 "$HOME/.codex/skills" | grep -c '^multi-agent$'                  # want 1
+find "$HOME/.codex/multi-agent-refs/commands" -name SKILL.md | wc -l  # want the command count
+grep -rhoE '(\$HOME|~)/\.claude/(agents|scripts|lib|schemas|commands|multi-agent-refs|rules)' \
+  "$HOME/.codex/skills" "$HOME/.codex/multi-agent-refs" | sort -u     # want empty
+```
+
+MCP is registered by the installer via `codex mcp add dev-toolkit` (idempotent,
+skipped with a warning when `codex` is absent). Never hand-edit
+`~/.codex/config.toml`  -  Codex owns it. Run this AFTER the REPO step, since the
+installer reads the repo tree.
+
+---
+
 ## Dev-Toolkit Sync (Step 3d)
 
 The companion MCP server (`dev-toolkit-mcp`) is its own repo with its own registry. Pipeline skills call its tools and several declare a minimum version, so when it moves it has to ship.
@@ -114,13 +151,19 @@ When the toolkit ships its own gate script (`npm run gates` / `scripts/gates.sh`
 
 **Version bump**: patch for fixes and docs, minor for a new tool, major for a removed or renamed tool.
 
-**Ship**: commit with that repo's own convention, tag `v<version>`, push with `--tags`, then publish to the registry from `publishConfig` using a throwaway userconfig  -  never edit `~/.npmrc`, never a bare `npm publish`. The token depends on the registry: `npm.pkg.github.com` needs a GitHub PAT with `write:packages` (logical key `github`), `registry.npmjs.org` needs the `npm` key.
+**Ship**: commit with that repo's own convention, tag `v<version>`, push with `--tags`, then publish to the registry from `publishConfig` using a throwaway userconfig  -  never edit `~/.npmrc`, never a bare `npm publish`. The token depends on the registry AND on the package scope: the registry picks the credential type, the scope picks the account. `npm.pkg.github.com` needs a **Classic** GitHub PAT with `write:packages`; `registry.npmjs.org` needs the `npm` key. Resolving on host alone misroutes on any machine with a work and a personal GitHub identity  -  prefer a scope-specific mapping (`github_<scope>`) and fall back to the generic `github` key only when there is one identity.
 
 ```bash
 NPMRC=$(mktemp); trap 'rm -f "$NPMRC"' EXIT
 REG=$(node -p "require('./package.json').publishConfig?.registry || 'https://registry.npmjs.org'")
 HOST=${REG#https://}; HOST=${HOST%/}
-case "$HOST" in npm.pkg.github.com*) KEY=github ;; *) KEY=npm ;; esac
+SCOPE=$(node -p "(require('./package.json').name.match(/^@([^/]+)/)||[])[1] || ''")
+case "$HOST" in
+  npm.pkg.github.com*) KEY=github; [ -n "$SCOPE" ] && KEY="github_$SCOPE" ;;
+  *) KEY=npm ;;
+esac
+# Fall back to the generic key when no scope-specific mapping exists.
+bash "$HOME/.copilot/lib/credential-store.sh" get "$KEY" >/dev/null 2>&1 || KEY=github
 TOKEN=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KEY")
 [ -n "$TOKEN" ] || echo "ABORT: no '$KEY' token - onboard it via /multi-agent:setup before publishing"
 printf '%s\n' "registry=$REG" "//$HOST/:_authToken=$TOKEN" > "$NPMRC"
@@ -167,24 +210,27 @@ When invoked with the `release` argument:
 7. DEV-TOOLKIT   Ship the companion MCP server if it moved (Step 3d gates, then publish)
 8. WEBSITE       Version + features -> {website-host}
 9. COPILOT       Copilot CLI instructions + skills sync
+9b. CODEX        Codex CLI router skill + refs + agent TOML (node install.js --codex)
 10. Report       Summary: version, touched repos, deploy status
 ```
 
 
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)
 
+> Codex takes the Step 2b path instead; see that section.
+
 | Claude Code | Copilot CLI |
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**42 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**43 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 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
 ```
 
 **NOT synced**: `refs/*`  -  Lazy-load references, Claude Code specific
@@ -200,8 +246,43 @@ routines, save, scan, search, setup, stack, status, sync, test, uninstall, updat
 | `gh` CLI (personal) | `{owner}` gh auth (Keychain) |
 | `gh` CLI (work) | `${USER}_{work-gh-alias}` gh auth (Keychain) |
 | npm publish | `NODE_AUTH_TOKEN`  -  `GITHUB_TOKEN` in CI, Keychain PAT locally |
-| dev-toolkit publish (Step 3d) | `npm` logical Keychain key -> throwaway `--userconfig`, registry from that repo's `publishConfig` |
+| dev-toolkit publish (Step 3d) | scope-resolved key (`github_<scope>`, else `github`, else `npm`) -> throwaway `--userconfig`, registry from that repo's `publishConfig` |
 
 ```bash
 gh auth switch --user {owner}  # for personal repos
 ```
+
+
+## Pre-flight the token scope
+
+GitHub reports a token's scopes on any authenticated request, so check before
+uploading instead of reading it out of a 403:
+
+```bash
+curl -sI -H "Authorization: token $TOKEN" https://api.github.com/user \
+  | grep -i '^x-oauth-scopes:' | grep -q 'write:packages'
+```
+
+Candidate order for `npm.pkg.github.com`, because storage location and scope are
+not correlated: `github_<scope>` from the mapping, then `gh auth token -u <scope>`
+(gh's own OAuth token often carries `write:packages` when a hand-made PAT does
+not), then the generic `github` key only on a single-identity machine. Take the
+first candidate whose scopes include `write:packages` AND whose login matches the
+package scope. If none qualifies, stop before publishing and report each candidate
+with the login it resolved to and the scope it was missing  -  that is the
+actionable output, not a 403 body.
+
+## Publish 403s: two causes, two fixes
+
+Neither message says "wrong token" plainly, and they need opposite responses:
+
+- `Unauthorized: As an Enterprise Managed User, you cannot access this content`  -
+  the resolved token belongs to a corporate EMU account, which cannot publish to a
+  personal scope at all. No scope grant fixes this; map the personal account's PAT
+  under `github_<scope>`.
+- `The token provided does not match expected scopes`  -  right account, missing
+  permission. Regenerate as a **Classic** PAT with `write:packages`
+  (plus `repo` for a private package) and re-onboard through setup.
+
+Always report which of the two occurred. "Permission denied" alone sends the user
+to regenerate a token that was never the problem.

package/pipeline/skills/shared/core/multi-agent-testflight-validation/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: multi-agent-testflight-validation
+language: en
+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."
+user-invocable: true
+argument-hint: "[repo]  -  empty = pick from prefs; repo name or path; --ipa=<path>; --archive=<path>; --resume"
+---
+
+# 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. **It never uploads**  -  only
+`--validate-app` is ever invoked, never `--upload-app`.
+
+## Why three gates
+
+Each sees something the others structurally cannot, so reporting one as "the check"
+is how a build passes locally and gets rejected anyway.
+
+| Gate | Runs | Needs | Sees | Blind to |
+|---|---|---|---|---|
+| **1. Static** | `ios_app_store_audit` (18 rules) | `.xcarchive` | privacy manifest, required-reason API, Info.plist, signing, entitlements, embedded SDK, IPv6, debug leak | anything account-dependent |
+| **2. Authoritative** | `ios_testflight_validate` → `altool --validate-app` | `.ipa` + credentials | unregistered bundle ID, profile/app-record mismatch, **version+build already used**, entitlement not provisioned | the Review Guidelines |
+| **3. Guideline** | `app-store-review` skill + repo evidence | repo checkout | ATT, privacy policy, account deletion, IAP, purpose-string wording | anything not in source |
+
+Most "we passed validation and still got rejected" cases are Gate 3 findings:
+Apple's validator does not read the Review Guidelines.
+
+## Flow
+
+**0. Input.** `(empty)` → ask · `my-ios-app`/path → that repo · `--ipa=<path>` →
+Mode B without Gate 1 · `--archive=<path>` → Mode B with all gates · `--resume`.
+State at `~/.claude/logs/multi-agent/<task_id>/agent-state.json`,
+`taskId = TFV-<repo>-<yyyymmddHHMM>`. Register phases with
+`bash ~/.copilot/scripts/phase-tracker.sh` and render with
+`phase-tracker.sh render` at every boundary.
+
+**1. Pickers.** Repo (iOS entries in `prefs.projects`; a single match auto-resolves,
+and the breadcrumb says so) → branch → mode. Print
+`Step <i>/<n>: <what this decides>` for each. On `git fetch` failure do **not**
+silently use a cached ref, and **classify the failure before naming a cause**:
+`could not read Password` / `Authentication failed` / `403` is a credential
+problem, not a network one, and a VPN cannot fix it; `Could not resolve host` /
+`Operation timed out` is the network. Show the stderr line verbatim next to your
+classification, then offer the remedy that matches it. Only the network case gets
+the continue-on-a-stale-ref option: for a credential failure, staleness is
+unrelated to what broke.
+
+**2. Pre-flight.** `xcrun --find altool` and `xcodebuild -version`; a missing
+prerequisite halts. Resolve credentials and name the active tier in the report:
+tier 1 ASC API key (key id + issuer id from the keychain via
+`prefs.global.keychainMapping`, `.p8` at
+`~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8`), tier 2 Apple ID +
+app-specific password by keychain reference, tier 3 none → **Gate 2 is `SKIPPED`
+and the verdict line says so**. Credentials come from `/multi-agent:setup`; never
+prompt for a secret value in chat. Tier 2 needs no elevated App Store Connect
+role, which matters when API-key creation is not permitted on the account.
+
+**3. Obtain the build.**
+- Mode B `.xcarchive` → Gate 1 runs; export with `ios_export_ipa` to reach Gate 2.
+- Mode B `.ipa` only → **Gate 1 `SKIPPED (needs .xcarchive)`**. The static audit
+  reads archive structure an `.ipa` does not carry. Do not present a two-gate run
+  as a full pass.
+- Mode A → worktree at `{projectRoot}/{worktreeBasePath}/{taskId}` (**never under
+  `$HOME`**) → `ios_xcodebuild({action: "archive", configuration: "Release",
+  destination: "generic/platform=iOS"})`  -  the simulator default would produce a
+  non-distributable archive  -  then `ios_export_ipa({method:
+  "app-store-connect", team_id, ...})`. Leave `allow_provisioning_updates` off
+  unless asked: it lets xcodebuild create or modify profiles in the developer
+  account, which a validation run has no business doing.
+
+**4. Gate 1.** `ios_app_store_audit({archive_path, rules: "all"})`. `error` blocks,
+`warning` advises. Keep each ITMS code  -  Gate 2 may return the same one, and that
+agreement tells the user it is real.
+
+**5. Gate 2.** `ios_testflight_validate({ipa_path, platform: "ios", <creds>})`.
+Render the verdict as returned: `PASS` / `FAIL` (each issue with ITMS code, mapped
+guideline, hint) / `SKIPPED` (with the reason, **never as a pass**). This is the
+only gate that catches an already-used build number  -  the most common wasted
+upload  -  so when it fails on that, name the next free build number.
+
+**6. Gate 3.** Load `app-store-review` and check, with an evidence path each:
+purpose strings (present, specific, matching actual use) · `PrivacyInfo.xcprivacy`
+(exists, declares required-reason APIs, matches linked SDKs) · ATT before any
+tracking · in-app account deletion when accounts are created · privacy policy
+reachable · IAP through StoreKit with no external purchase path · Sign in with
+Apple alongside third-party social login. Mark `pass` / `fail` /
+`not-applicable`, and `not-applicable` needs a reason  -  an unexamined area is not
+a pass.
+
+**7. Report.** `~/TestFlightChecks/<repo>-<branch>-<timestamp>/report.md` plus a
+printed summary:
+
+```
+Verdict: <N> of 3 gates cleared[, <M> skipped]
+Build:   <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>
+
+Not run
+  Gate 1: needs an .xcarchive; only an .ipa was supplied
+```
+
+A skipped gate is never folded into the pass count. Every blocking finding carries
+a file path or an ITMS code. No AI or assistant attribution anywhere; real
+newlines, no HTML entities.
+
+**8. Offer, do not act.** Print the exact `xcrun altool --upload-app` command for
+when the gates are clear (uploading stays an explicit human act), plus
+`--resume` after fixes and `/multi-agent:fix-bug` for code-level Gate 3 findings.
+Never upload, never bump the build number, never commit.