@mmerterden/multi-agent-pipeline 13.2.0 → 13.4.0

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

@@ -34,7 +34,38 @@ Categories:
 
 Component work is **no longer a bundled pipeline skill set**. Claude Code dispatches `taskType === "component"` to the enabled `ai-<platform>-engineering-toolkit` **marketplace plugin** (`create-component`, fallback `create-ui-component`) via the Skill tool  -  full contract in `$HOME/.claude/multi-agent-refs/component-dispatch.md`. The pipeline no longer ships `pipeline/skills/figma-ios|figma-android|figma-common`; the pipeline-unique component skills (iterate loops, performance harness, validate/review, commit, adapters, wiki) were absorbed into the `ai-ios-engineering-toolkit` plugin so component skills live in one place.
 
-**Intentional cross-CLI divergence.** Copilot CLI has no marketplace-plugin loader, so it retains its own standalone `~/.copilot/skills/figma-*` copies as a frozen fallback. Component/figma dispatch is therefore **not** byte-identical across CLIs, and figma-skill *inventory* parity is **no longer enforced**  -  this is a deliberate exception to the parity rule, not drift.
+**How each host receives the plugin's skills.** Only Claude Code loads the marketplace
+plugin natively. The other two are served by the installer, so all three end up with the
+same active skill set:
+
+| Host | Delivery | Discovery |
+|---|---|---|
+| Claude Code | the marketplace plugin, loaded natively | matched on description |
+| Copilot CLI | `install/copilot.mjs` copies the **enabled** stack plugin's authored skills (`index`, `reference/`, `workflow/`, `tools/`) into `~/.copilot/skills/` | matched on description |
+| Codex CLI | `install/codex.mjs` copies the same set **plus** `skills/shared/external` into `~/.codex/multi-agent-refs/skills/` as reference files | located by path; the AGENTS.md block carries the `ls` / `grep` recipe |
+
+Three rules make that work:
+
+1. **`knowledge/` is never copied to Copilot.** A stack plugin's `knowledge/` tree is
+   generated from this pipeline's `skills/shared/external`, which the installer already
+   lays down there. Copying it again would duplicate ~5 MB the host has.
+2. **Only the ENABLED plugins are delivered.** `fix-bug` and `branch-and-pr` exist in
+   four stack plugins, `component`, `state` and `create-component` in three, and the
+   destination is flat  -  delivering every stack would be last-write-wins, so an iOS
+   repo could end up running the Android `create-component`. The enabled list in
+   `~/.claude/settings.json` is the source of truth, exactly as on Claude Code;
+   `--platform` is the fallback when no such list exists.
+3. **Codex takes refs, not list entries.** Measured on 0.145: one plugin declaring 142
+   skills surfaced 75 and evicted an unrelated user skill, and every plugin-provided
+   skill renders with an empty description, so a block entry buys nothing even when it
+   fits. Parity on that host is **reachability**, not an identical listing.
+
+> This section previously claimed Copilot "retains its own standalone
+> `~/.copilot/skills/figma-*` copies as a frozen fallback". `install/copilot.mjs` pruned
+> exactly those directories, so the fallback did not exist: `create-screen`,
+> `figma-validate`, `figma-review`, `component`, `state` and `navigation` were all
+> absent, and a component task on Copilot had nothing to dispatch to. The contract
+> documented a safety net the installer deleted.
 
 What still MUST match across CLIs for component tasks: the `taskType === "component"` classification, the `state.phases["3"].subphases[]` shape the dispatch layer writes, and `--dev` elision semantics. Resolution/routing is Claude-plugin vs Copilot-local-copy by design.
 

package/pipeline/multi-agent-refs/features/external-context-injection.md

@@ -32,10 +32,51 @@ One fetcher per type. Each fetcher emits a normalized JSON view that the analysi
 
 - `0` (success) → output appended to `state.fetchedContext.<type>[]` and injected into the prompt.
 - `2` (blocked / missing token) → run the inline Token Save Flow per `setup.md`; on skip, mark the entry as `{status: "skipped", reason: "missing-token"}` and continue.
-- `3` (network/auth) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue.
+- `3` (network/auth) → **surface the Unreachable-source decision below.** Never silently downgrade.
 - `4`/`5`/`6` (config errors) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue and log a setup hint.
 
-Failures are never fatal at Phase 1  -  the agent still runs analysis, just without the referenced source.
+### MUST: an unreachable source is announced, not absorbed (BLOCKING)
+
+A fetcher that fails is the pipeline losing the ground truth it was told to use. The
+user is the only one who can fix it - the token is theirs to refresh, the VPN is theirs
+to connect - and they cannot fix what they are not told about.
+
+This used to read "mark as failed, continue". The observed result: an expired token and
+a VPN-off remote both reached the analysis phase as *no data*, indistinguishable from a
+ticket that referenced nothing. The run then produced a plan from a partial picture and
+reported success, and the user found out by reading the output.
+
+So on exit `3`, classify the stderr and surface an `AskUserQuestion` before continuing.
+The classification is the same shape the Phase 6 remote gate uses, because the failures
+are the same failures:
+
+| stderr signal | Diagnosis | Question offers |
+|---|---|---|
+| `401`, `403`, `invalid_grant`, `token expired`, `unauthorized` | the credential is dead | **Refresh `<KEY_NAME>`** (Save Flow Step B, then retry) · **Continue without this source** · **Abort** |
+| `could not resolve host`, `connection refused`, `timed out`, `network is unreachable`, corporate host in the URL | the host is unreachable, VPN almost certainly off | **Connect the VPN, then retry** (default) · **Continue without this source** · **Abort** |
+| `404`, `no such issue`, `not found` | the reference is stale or the link points at something deleted | **Supply a current URL** · **Continue without this source** · **Abort** |
+| anything else | unknown | verbatim stderr in the `description`, same three options |
+
+Rules that make this actionable rather than decorative:
+
+1. **Name the thing.** The question states which source (`crashlytics`), which URL, and
+   which credential key by its logical name (`firebase`, never the raw Keychain item).
+2. **Say what is lost.** "Without it I plan from the exception message alone, with no
+   stack frames and no affected-version spread" beats "continuing without context".
+3. **Retry is a real branch.** On "Connect the VPN, then retry" / "Refresh", re-run the
+   same fetcher and re-enter this table on a second failure. Do not fall through to
+   "continue" after one attempt.
+4. **Record the choice.** `state.fetchedContext.<type>[].status` ∈ `ok | skipped | failed`
+   plus `userDecision` ∈ `retried-ok | continued-without | aborted`, so Phase 1 can put
+   "planned without Crashlytics, user's choice at <ts>" in the analysis doc's limitations
+   section instead of leaving a silent hole.
+5. **Autopilot still reports.** Autopilot takes "continue without this source" without
+   asking, but the skipped source is logged and carried into the Phase 7 report. An
+   autopilot run that quietly planned from a partial picture is the same defect with a
+   flag on it.
+
+Failures remain non-fatal at Phase 1 by default - the agent still runs analysis. What
+changed is that the user learns about it while the choice is still theirs to make.
 
 **Graylog specifics.** `fetch-graylog.sh` degrades to empty on any network/VPN failure: it emits a normalized empty object and exits `0`, so an unreachable host reads as `{status:"skipped", reason:"vpn-unreachable"}` and never blocks. Only a genuine auth rejection on a reachable host exits `3` (marked `failed`, still non-fatal here). `state.graylogContext` is prepended to the analysis prompt inside the **Referenced External Sources** section as diagnostic context that is **advisory only**  -  the agent may use it to orient on a reported error, but code remains ground truth, and there is no Phase 4 review gate for logs.
 

package/pipeline/multi-agent-refs/keychain.md

@@ -40,6 +40,69 @@ Reasons:
 
 The smoke gate `pipeline/scripts/smoke-no-token-prompt.sh` greps the pipeline source for hardcoded "enter token" / "paste token" / "API key:" prompts and fails the build if any are introduced. Token I/O is exclusively `credential-store.sh` calls.
 
+### Rule 2  -  MUST: never ask the user for what a mapped credential can fetch (BLOCKING)
+
+Before asking the user for data that an external system holds - a stack trace, a log
+line, a page body, a finding, a design frame - inventory the credentials first:
+
+```bash
+bash "$HOME/.claude/lib/credential-inventory.sh" --json            # what is configured
+bash "$HOME/.claude/lib/credential-inventory.sh" --json --probe    # and what actually answers
+bash "$HOME/.claude/lib/credential-inventory.sh" --key firebase     # exit 0 = usable
+```
+
+The inventory reads `prefs.global.keychainMapping`, probes each logical key through
+`credential-store.sh get` with the value discarded, and reports `present` /
+`mapped-but-missing` / `unmapped` alongside what each key unlocks. Values are never
+printed.
+
+The answer then decides the shape of the question:
+
+| Inventory says | The question must be |
+|---|---|
+| `present` | ask for the **pointer**, not the payload, and say you will fetch it: "Give me the Crashlytics issue URL - I have the Firebase service account mapped and will pull the stack frames, affected versions and device spread myself." |
+| `mapped-but-missing` | say the credential is configured but not resolving, name the logical key, and offer the Save Flow: "`firebase` is mapped but the Keychain item is not resolving - refresh it, or paste the trace and I continue without it." |
+| `unmapped` | say the capability is not configured and offer setup: "No `firebase` key is mapped, so I cannot reach Crashlytics. Onboard it via `/multi-agent:setup`, or paste the trace." |
+
+**Never** present "paste it yourself" as the first and most efficient option when a
+credential is present. That is the defect this rule exists for: a run asked the user to
+paste a Crashlytics stack trace, offering the manual path as "the fastest and most
+certain route", while a valid Firebase service-account JSON sat in the Keychain mapped
+as `firebase`. The user had configured that key precisely so the pipeline would not ask.
+
+**State the limit honestly too.** A credential is not omniscience: the Crashlytics
+fetcher resolves a specific issue and needs its URL, so "I have the key" does not mean
+"I can find the crash from an exception message alone". Say which piece is missing and
+why, rather than implying either more or less capability than exists.
+
+#### Present is not the same as working
+
+`--probe` makes one cheap authenticated request per configured credential, because
+"the key is in the Keychain" and "the service answers" are different claims and the user
+fixes them in different ways:
+
+| Verdict | What it means | What to tell the user |
+|---|---|---|
+| `reachable` | the service answered and accepted the credential | nothing - proceed |
+| `auth-rejected` | 401/403: the credential is dead | name the logical key, run the Expired-token decision (Rule 1) |
+| `unreachable` | no response at all | on a corporate host this is almost always the VPN: "`{FORTIFY_HOST}` is not answering - connect the VPN and I will retry, or I continue without the finding" |
+| `no-host-configured` | a token exists but `global.hosts.<service>` was never recorded | "I hold the `jira` token but no Jira host is configured, so I cannot build a request URL - set it via `/multi-agent:setup`" |
+| `well-formed` | structurally valid, liveness not checkable yet | say what is still needed (the Crashlytics issue URL) |
+| `not-probeable` | no cheap probe exists for this credential type | do not claim it works, do not claim it fails |
+
+Never collapse these into one "failed" bucket. A dead token, a closed VPN and a missing
+host look identical in a `{status: "failed"}` field and lead the user to three different
+wrong actions.
+
+Probe only what is configured. An unmapped key is a capability the user chose not to
+enable - reporting it as a problem trains them to ignore the report. Cache the result in
+`prefs.global.serviceStatus.<service>` (`{ok, checkedAt, error?}`, TTL
+`settings.serviceStatusCacheSeconds`) so a phase chain probes once, not per fetcher.
+
+Record what the inventory found in `agent-state.json.credentialInventory`
+(`{usable: [...], needsAttention: [...], at: <ts>}`) so a later phase can tell "the
+source was unreachable" from "nobody looked".
+
 **Retrieve pattern (always use mapping):**
 
 ```bash

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

@@ -136,6 +136,22 @@ Results are cached in `global.serviceStatus` (existing TTL contract, default 300
 
 Probe failures caused by network (timeout, DNS) are NOT treated as expiry  -  log and continue; the mid-run 401 path still exists as the safety net.
 
+**Record the inventory.** After the probes, persist what is reachable:
+
+```bash
+# --probe when the task references an external source (Jira ID, Crashlytics/Fortify URL,
+# a remote to fetch): "the key is in the Keychain" and "the service answers" are
+# different claims, and only the second one lets the run proceed.
+bash "$HOME/.claude/lib/credential-inventory.sh" --json --probe > /tmp/cred-inventory-${TASK_ID}.json
+```
+
+Write `{usable, needsAttention, at}` into `agent-state.json.credentialInventory`. Later
+phases read it instead of re-probing, and it is what makes `keychain.md` Rule 2
+enforceable: any question that asks the user for data an external system holds must be
+shaped by this file. A run that asks the user to paste a Crashlytics stack trace while
+`firebase` is listed under `usable` is a Rule 2 violation, and the inventory is the
+evidence.
+
 #### Step 1  -  Parse Input
 
 **Branch from input**: If the user provided a branch name after the issue reference (space-separated), store as `baseBranch` and skip Step 3. Otherwise Step 3 asks interactively.
@@ -233,18 +249,30 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
      | grep -E '(develop|release|main|master)' \
      | grep -v -E '(feature/|bugfix/|fix/|hotfix/|chore/)'
    ```
-6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Present numbered list with standard UX pattern:
+6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Surface through the
+   **native picker** per `picker-contract.md` (`AskUserQuestion` on Claude Code,
+   `ask_choice.sh` on Copilot CLI) - `question` + `description` in `outputLanguage`,
+   `label` English, the recent branch first and marked `(Recommended)`. The ASCII sketch
+   below is what the options carry, not a menu to print:
+
    ```
-   Base branch:
-     Recent: → develop (enter to reuse)
-     ────────────────────
-     1. origin/develop
-     2. origin/main
-     ...
-   Select [number] or enter for suggested:
+   header: "Base branch"
+   options: origin/develop (Recommended, reused from last run) | origin/main | release/8.4.0 | Other
    ```
 7. User picks → store as `baseBranch`. Save to `prefs.projects[{project}].branches` (dedup, max 10).
 
+**MUST: this step is not skippable (BLOCKING).** The only legitimate skip is rule 4
+above - `baseBranch` already supplied in the input. Everything else asks. A run once
+took a Jira ID and implemented straight onto whatever the local checkout was pointing
+at, with neither the project nor the branch picker ever shown; nothing failed, so
+nothing surfaced it. `phase0-exit-gate.mjs` now refuses to close Phase 0 unless
+`agent-state.json` carries `baseBranch` and `baseFetchStatus`, so a skipped picker is a
+gate failure rather than a silent default.
+
+This holds in every mode. `--dev` skips the *LLM* phases (Analysis, Planning); it does
+not skip Phase 0's pickers. Autopilot resolves them to their defaults without prompting,
+which still writes the fields - it does not leave them unset.
+
 **TTL filter for recent branches**:
 
 - `prefs.global.recentBranches[{projectKey}][]` carries `{name, lastUsed}`. Filter to those whose `lastUsed` is within `settings.branchTtlDays` (default 15).
@@ -253,20 +281,25 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
 
 **Fetch-fail handling** (replaces silent `git fetch origin` failure):
 
-The legacy `git -C $PROJECT_ROOT fetch origin` step (line 110 above) MUST not silently fall back to a stale cached ref. On non-zero exit, present 4 options (per `feedback_multi_agent_fetch_fail`):
+The legacy `git -C $PROJECT_ROOT fetch origin` step (line 110 above) MUST not silently fall back to a stale cached ref. On non-zero exit, surface the **native picker** (per `picker-contract.md`) with 4 options:
 
 ```
-git fetch origin failed for {project} (exit {code}, last attempt {ts}).
-Likely causes: VPN closed, host unreachable, auth expired.
-
-  [1] Connect VPN / fix network, then resume #{taskId}     (safest)
-  [2] Use cached origin/{baseBranch} ref                    (stale risk: base sha {sha}, fetched {since})
-  [3] Use local branch "{baseBranch}" as base               (only if local branch exists; commit {sha})
-  [4] Abort  -  no worktree, no branch, no state file
-
-Select:
+question:    "git fetch failed for {project} - the base ref may be stale. How should I proceed?"
+description: "exit {code}, last successful fetch {ts}. Likely: VPN closed, host unreachable, auth expired."
+header:      "Base ref"
+options:
+  Connect VPN and retry      (Recommended)  re-run the fetch, then continue with a fresh ref
+  Use cached origin ref                     stale risk: base sha {sha}, fetched {since}
+  Use local branch as base                  only offered when the local branch exists; commit {sha}
+  Abort                                     no worktree, no branch, no state file
 ```
 
+**Say which is which.** The question must name the corporate host when the remote points
+at one - a `{BITBUCKET_HOST}` remote failing to resolve is almost always the VPN, and
+telling the user that is the difference between a five-second fix and a run built on a
+month-old ref. "Connect VPN and retry" re-runs the fetch and re-enters this picker if it
+fails again; it is a real retry, not a label.
+
 Persist user choice in `agent-state.json.baseFetchStatus` ∈ `"fresh" | "cached-stale" | "local-branch" | "aborted"`. On any non-fresh choice, log:
 ```
 ⚠️ Base ref stale (fetch fail @ {ts}, choice: {cached-stale|local-branch})

package/pipeline/multi-agent-refs/rules.md

@@ -163,10 +163,10 @@ Provider tools that print failed argv on retry leak credentials into the convers
 # goes through the cross-platform credential helper so the same snippet works
 # on macOS / Linux / Windows installs:
 VERCEL_TOKEN="$(~/.claude/lib/credential-store.sh get mmerterden_Vercel_Access_Token)" \
-  bash $HOME/.claude/scripts/vercel-deploy.sh deploy --prod
+  bash $HOME/.claude/lib/vercel-deploy.sh deploy --prod
 
 # Health check before deploy:
-bash $HOME/.claude/scripts/vercel-deploy.sh doctor
+bash $HOME/.claude/lib/vercel-deploy.sh doctor
 ```
 
 **Forbidden:**
@@ -177,7 +177,7 @@ vercel deploy --token=vcp_...
 vercel deploy --token "$VERCEL_TOKEN"
 ```
 
-The wrapper at `pipeline/lib/vercel-deploy.sh` (installed to `~/.claude/scripts/vercel-deploy.sh` and `~/.copilot/scripts/vercel-deploy.sh`) refuses any `--token=` argv input, runs the CLI with `VERCEL_TOKEN` env, and pipes every stdout/stderr line through a redact filter that scrubs `vcp_...`, `Bearer ...`, and JSON-body token shapes. Regression gate: `smoke-vercel-deploy-redact.sh` (12 assertions).
+The wrapper at `pipeline/lib/vercel-deploy.sh` (installed to `~/.claude/lib/`, `~/.copilot/lib/` and `~/.codex/lib/` with the rest of the shell libraries) refuses any `--token=` argv input, runs the CLI with `VERCEL_TOKEN` env, and pipes every stdout/stderr line through a redact filter that scrubs `vcp_...`, `Bearer ...`, and JSON-body token shapes. Regression gate: `smoke-vercel-deploy-redact.sh` (12 assertions).
 
 Same rule applies to any future provider wrapper (e.g. `cloudflare-deploy.sh`, `npm-publish.sh`)  -  never pass tokens via argv when the underlying CLI may echo argv on failure.
 

package/pipeline/scripts/build-stack-plugins.mjs

@@ -35,9 +35,14 @@ import {
 import { join } from "node:path";
 
 const args = process.argv.slice(2);
+// Accepts both `--key value` and `--key=value`. The `=` form used to fall through to
+// the default, which meant a run meant for a throwaway checkout silently retargeted
+// the user's real marketplace instead - a wrong-target write, reported as success.
 const getArg = (k, d) => {
+  const eq = args.find((a) => a.startsWith(`${k}=`));
+  if (eq) return eq.slice(k.length + 1);
   const i = args.indexOf(k);
-  return i >= 0 ? args[i + 1] : d;
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : d;
 };
 const HOME = process.env.HOME;
 const PLUGINS_REPO = getArg("--plugins-repo", join(HOME, "multi-agent-plugins"));
@@ -102,6 +107,29 @@ const isDir = (p) => {
 };
 const listDirs = (p) => (existsSync(p) ? readdirSync(p).filter((n) => isDir(join(p, n))) : []);
 
+/**
+ * Cheap content fingerprint for a skill directory: every file's relative path and
+ * size. Enough to notice an edit without hashing megabytes on every run, and it is
+ * only used to decide whether a version bump is warranted.
+ */
+function treeFingerprint(dir) {
+  const parts = [];
+  const walk = (d, rel) => {
+    for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join(d, e.name);
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(full, r);
+      else if (e.isFile()) parts.push(`${r}:${statSync(full).size}`);
+    }
+  };
+  try {
+    walk(dir, "");
+  } catch {
+    return "";
+  }
+  return parts.join("|");
+}
+
 // --- 1. enumerate authoring source ---------------------------------------
 if (!existsSync(EXTERNAL)) {
   console.error(`source not found: ${EXTERNAL}`);
@@ -180,13 +208,31 @@ for (const [plugin, want] of Object.entries(desired)) {
   const have = new Set(listDirs(kdir));
   const toAdd = [...want].filter((s) => !have.has(s)).sort();
   const toRemove = [...have].filter((s) => !want.has(s)).sort();
-  const changed = toAdd.length > 0 || toRemove.length > 0;
+  const setChanged = toAdd.length > 0 || toRemove.length > 0;
 
-  if (!DRY && changed) {
+  // Re-copy EVERY wanted skill, not just the newly added ones.
+  //
+  // This used to copy only on a set change, which quietly broke the single-source
+  // claim: editing a skill in shared/external left the plugin serving the old text
+  // forever, because the set had not changed. Found by editing a promoted skill and
+  // seeing the plugin copy stay stale while the generator reported "all plugins up
+  // to date".
+  //
+  // cpSync overwrites, so a full re-copy is idempotent and cheap relative to a
+  // publish. Removals still need the explicit delete.
+  let contentChanged = false;
+  if (!DRY) {
     if (!existsSync(kdir)) mkdirSync(kdir, { recursive: true });
-    for (const s of toAdd) cpSync(join(EXTERNAL, s), join(kdir, s), { recursive: true });
+    for (const s of want) {
+      const from = join(EXTERNAL, s);
+      const to = join(kdir, s);
+      const before = existsSync(to) ? treeFingerprint(to) : "";
+      cpSync(from, to, { recursive: true });
+      if (treeFingerprint(to) !== before) contentChanged = true;
+    }
     for (const s of toRemove) rmSync(join(kdir, s), { recursive: true, force: true });
   }
+  const changed = setChanged || contentChanged;
 
   // regenerate plugin.json skills[]: keep non-knowledge entries, rebuild knowledge set
   const pj = JSON.parse(readFileSync(pjPath, "utf8"));

package/pipeline/scripts/phase0-exit-gate.mjs

@@ -14,6 +14,12 @@
  * and spacing guessed at 16 where the frame said `Spacing/12`. Half the commits on
  * that branch were rework.
  *
+ * A second run then showed the other half of the same failure: a Jira task was
+ * implemented without the repo or branch picker ever appearing, straight on whatever
+ * the local checkout was pointing at. Step 3 and Step 8 own those decisions, and
+ * `agent-state.json` is the only durable evidence they happened - so the gate asserts
+ * their output too, not just `taskType`.
+ *
  * A phase that reports success without its output is worse than one that fails:
  * every later phase then reasons from a field that is not there. So this is a
  * gate, not a lint  -  the spec already said what to write, and prose alone did
@@ -120,6 +126,52 @@ export function evaluate(state, extraInput = "") {
     );
   }
 
+  // Step 3 picks the base branch and Step 8 creates the worktree. A run that skipped
+  // both develops on whatever the checkout happened to have, which is how a Jira task
+  // got implemented on a stale local branch with no picker ever shown. The state file
+  // is the only durable evidence those steps ran, so it has to carry their output.
+  //
+  // `local` provider runs still choose a base branch; what they skip is push and PR.
+  // So this applies to every provider.
+  const baseBranch = typeof state.baseBranch === "string" ? state.baseBranch.trim() : "";
+  if (!baseBranch) {
+    failures.push(
+      "agent-state.json has no baseBranch. Step 3 asks for it (or takes it from the " +
+        "input); an unset value means the branch picker never ran and development " +
+        "happens on whatever the checkout was already pointing at.",
+    );
+  }
+
+  // Which ref the base actually came from. Without it, "built on a fresh origin ref"
+  // and "built on a month-old local branch" are indistinguishable after the fact -
+  // and the fetch-failure picker exists precisely to make that an explicit choice.
+  const fetchStatus = typeof state.baseFetchStatus === "string" ? state.baseFetchStatus.trim() : "";
+  const FETCH_STATES = ["fresh", "cached-stale", "local-branch", "aborted"];
+  if (baseBranch && !FETCH_STATES.includes(fetchStatus)) {
+    failures.push(
+      `agent-state.json has baseFetchStatus="${fetchStatus || "<unset>"}"; Step 3 must ` +
+        `record one of ${FETCH_STATES.join(" | ")}. An unset value means nothing ` +
+        `established whether the base ref was fetched or reused from a stale cache.`,
+    );
+  }
+
+  // Worktree isolation is a standing rule: never develop in the primary checkout.
+  const worktree = typeof state.worktreePath === "string" ? state.worktreePath.trim() : "";
+  const projectRoot = typeof state.projectRoot === "string" ? state.projectRoot.trim() : "";
+  if (!worktree && !projectRoot) {
+    failures.push(
+      "agent-state.json records neither worktreePath nor projectRoot. Step 8 creates " +
+        "the worktree; with no recorded path, later phases cannot tell which tree they " +
+        "are meant to edit and default to the current directory.",
+    );
+  }
+  if (worktree && projectRoot && worktree === projectRoot) {
+    failures.push(
+      `worktreePath equals projectRoot (${worktree}). Development must happen in a ` +
+        `separate worktree, never in the primary checkout.`,
+    );
+  }
+
   // The Figma access chain records which tier answered. A component task with no
   // recorded tier means nothing verified that the design was actually reachable,
   // which is how a run ends up guessing spacing.

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

@@ -336,6 +336,25 @@ Full contract: `refs/tracker-contract.md` section "TaskCreate ordering (strict)"
 > 6. **Branch name confirm**  -  `feature/PROJ-{id}-{kebab}` or `bugfix/...`  -  user confirms or edits. In multi-repo mode the branch name is shared across all selected repos (collision check runs per-repo; any collision applies the suffix to all). (Step 4)
 > 7. **Git identity  -  per repo**  -  route via `prefs.global.platformIdentityRouting`; ask if ambiguous. Multi-repo mode resolves identity **per repo independently** (phase-0-init.md L283). (Step 6)
 > 8. **Instruction files + workspace creation  -  serially per repo**  -  detect `.instructions/figma/` etc. In multi-repo mode, worktree creation loops per repo serially (phase-0-init.md L308); any failure rolls back previously-created worktrees. Write `agent-state.json` with `state.projects[]` array (scalar `project`/`projectRoot`/`branch` mirror `projects[0]` for back-compat). (Steps 7-8)
+>
+> **Exit gate (BLOCKING).** The contract above was prose only, and a run still took a
+> Jira ID and implemented straight onto the local checkout with no picker shown. Before
+> marking Phase 0 completed:
+>
+> ```bash
+> node "$HOME/.copilot/scripts/phase0-exit-gate.mjs" "$TASK_ID" --input "$USER_INPUT"
+> ```
+>
+> Non-zero means Phase 0 did not produce its own output - `taskType`, `baseBranch`,
+> `baseFetchStatus`, a worktree path distinct from the project root, and a recorded Figma
+> access tier when the input carries a Figma URL. Fix the missing step; do not proceed.
+>
+> **Credential inventory (Step 0).** Run
+> `bash "$HOME/.copilot/lib/credential-inventory.sh" --json` and store the result in
+> `agent-state.json.credentialInventory`. Per `refs/keychain.md` Rule 2, never ask the
+> user for data a mapped credential can fetch: a run asked for a hand-pasted Crashlytics
+> stack trace while a valid Firebase service account was mapped and resolving. Ask for
+> the pointer (the issue URL) instead, and say what you will do with it.
 
 **Step 1  -  Project detection + input parsing:**