@mmerterden/multi-agent-pipeline 12.10.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/output-quality-check.sh

@@ -89,6 +89,40 @@ else
   warn "no .pr-body.md in task dir (skipped PR-body check)"
 fi
 
+# 2b. Tracker tile titles
+#
+# `rules.md` forbids HTML entities in "titles, commit messages, task subjects, or
+# body text", but this check only ever looked at the PR body and the Jira comment.
+# Tile titles are task subjects, and that is where the rule actually broke: a real
+# run rendered `Phase 1: Build & Launch` in the TaskList widget. The rule was
+# right and its enforcement was scoped to the wrong two surfaces.
+#
+# `phase-tracker.sh add` now decodes at the funnel, so this is the backstop that
+# says so: an entity reaching the stored state means the funnel was bypassed.
+TRACKER_STATE="$TASK_DIR/tracker-state.json"
+if [ -f "$TRACKER_STATE" ]; then
+  BAD_TITLES=$(python3 -c "
+import json, re, sys
+try:
+    d = json.load(open('$TRACKER_STATE'))
+except Exception:
+    sys.exit(0)
+# named, decimal and hex - a pattern covering only the named forms would miss
+# exactly the two spellings the first version of the decoder missed.
+pat = re.compile(r'&(amp|lt|gt|quot|apos|nbsp|mdash|ndash|hellip|#[0-9]+|#[xX][0-9a-fA-F]+);')
+for p in d.get('phases', []):
+    n = p.get('name', '')
+    if pat.search(n):
+        print('%s: %s' % (p.get('id'), n))
+" 2>/dev/null)
+  if [ -n "$BAD_TITLES" ]; then
+    bad "tracker tile title(s) carry HTML entities (they render literally):"
+    printf '%s\n' "$BAD_TITLES" | sed 's/^/      /'
+  else
+    ok "tracker tile titles free of HTML entities"
+  fi
+fi
+
 # 3. Jira comment
 JIRA_COMMENT="$TASK_DIR/.jira-comment.txt"
 if [ -f "$JIRA_COMMENT" ]; then

package/pipeline/scripts/phase-tracker.sh

@@ -115,6 +115,84 @@ need_jq() {
   }
 }
 
+# Decode HTML entities in a tile title.
+#
+# `rules.md` forbids entities in "titles, commit messages, task subjects, or body
+# text" because nothing downstream decodes them - they render literally. A tracker
+# tile title IS a task subject, and it rendered exactly that way:
+#
+#   Phase 1: Build & Launch
+#   Phase 3: Drive & Compare
+#
+# The rule existed and `output-quality-check.sh` enforced it, but only over the PR
+# body and the Jira comment, never over a tile title. The one surface where the
+# rule actually broke was the one surface nothing inspected.
+#
+# `add` is the single funnel for every tile title, so fixing it here fixes every
+# caller. Decode rather than reject: the intent behind `&` is unambiguous, and
+# a display path should render correctly now rather than abort a run over
+# punctuation. The stderr warning keeps the caller mistake visible instead of
+# silently papering over it.
+#
+# Handles all three encodings, because a title can arrive in any of them:
+#   named    &  <  "     —
+#   decimal  &  <  "      —
+#   hex      & < "     —
+# A first version handled only the named forms, so the numeric spellings still
+# rendered literally: the same bug fixed for one spelling out of three.
+#
+# ONE left-to-right pass, which also gets nesting right for free: a global replace
+# never rescans its own output, so `<` yields the literal text `<` rather
+# than `<`. An ordered-sed version needed `&amp;` decoded last for the same effect,
+# and that ordering was a latent trap.
+#
+# Fancy punctuation degrades to ASCII instead of decoding faithfully. `&mdash;`
+# becomes `-`, not an em-dash: this repo bans em/en-dash and ellipsis in shipped
+# text and gates it in the scorecard, so decoding them would make this function
+# INJECT what another gate rejects. Same for any numeric entity resolving to one.
+#
+# The program is fed through a QUOTED heredoc, not `node -e '...'`. Inside a
+# single-quoted shell string every apostrophe in the JS (and in its comments)
+# terminates the string early; shellcheck flags it as SC2140 and the first version
+# here worked only by accident of where the quotes happened to fall. A quoted
+# heredoc passes the body through verbatim, so the JS can use any quote it likes.
+decode_entities() {
+  local raw="$1" out
+  out=$(MA_RAW="$raw" node - <<'MA_DECODE_JS'
+const NAMED = {
+  amp: "&", lt: "<", gt: ">", quot: '"', apos: "'",
+  nbsp: " ",
+  // Deliberately ASCII: see the note above this function.
+  ndash: "-", mdash: "-", hellip: "...", laquo: "<<", raquo: ">>",
+};
+// Codepoints that must degrade to ASCII rather than decode faithfully.
+const ASCII_FOR = new Map([
+  [0x00a0, " "], [0x2013, "-"], [0x2014, "-"], [0x2026, "..."],
+  [0x2018, "'"], [0x2019, "'"], [0x201c, '"'], [0x201d, '"'],
+  [0x00a7, ""],
+]);
+const src = process.env.MA_RAW || "";
+process.stdout.write(
+  src.replace(/&(#[xX][0-9a-fA-F]+|#[0-9]+|[a-zA-Z][a-zA-Z0-9]*);/g, (m, body) => {
+    if (body[0] === "#") {
+      const hex = body[1] === "x" || body[1] === "X";
+      const cp = parseInt(hex ? body.slice(2) : body.slice(1), hex ? 16 : 10);
+      if (!Number.isFinite(cp) || cp < 0 || cp > 0x10ffff) return m;
+      if (ASCII_FOR.has(cp)) return ASCII_FOR.get(cp);
+      try { return String.fromCodePoint(cp); } catch { return m; }
+    }
+    const key = body.toLowerCase();
+    // An unknown named entity is left alone: guessing would corrupt a title that
+    // legitimately contains "&foo;".
+    return Object.prototype.hasOwnProperty.call(NAMED, key) ? NAMED[key] : m;
+  }),
+);
+MA_DECODE_JS
+) || out="$raw"
+  [ "$out" != "$raw" ] && echo "phase-tracker: decoded HTML entities in title (rules.md forbids them): '$raw' -> '$out'" >&2
+  printf '%s' "$out"
+}
+
 # OTel-compatible span emission  -  v6.1.0+, opt-in via $MULTI_AGENT_OTEL_SPANS.
 # Appends one JSON line to otel-spans.jsonl. Never fatal on failure.
 #
@@ -575,7 +653,7 @@ case "$ACTION" in
   add)
     need_jq
     [ "$#" -ge 2 ] || { echo "add needs <phase_id> <name>" >&2; exit 64; }
-    PID="$1"; PNAME="$2"
+    PID="$1"; PNAME="$(decode_entities "$2")"
     acquire_state_lock
     state=$(load_state)
     # Idempotent: a phase id that already exists is a no-op (name, status, and

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.