@mmerterden/multi-agent-pipeline 13.3.0 → 13.4.0

package/CHANGELOG.md

@@ -16,6 +16,81 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [13.4.0] - 2026-07-28
+
+### Added
+
+- **`credential-inventory.sh`** - one command that answers "what can I reach right now?"
+  A run asked the user to paste a Crashlytics stack trace by hand, offering the manual
+  path as the fastest route, while a valid Firebase service-account JSON sat in the
+  Keychain mapped as `firebase` and resolving fine. Nothing had failed: the pipeline
+  simply never asked itself whether it already held a credential that answered the
+  question. The tool reports `present` / `mapped-but-missing` / `unmapped` per logical
+  key plus what each one unlocks, and `keychain.md` Rule 2 now binds every question that
+  requests external data to its output - ask for the pointer (the issue URL), never for
+  the payload. Values are never printed.
+- `--probe` verifies that configured credentials actually answer, because "the key is in
+  the Keychain" and "the service replies" are different claims that the user fixes in
+  different ways. The verdicts stay separate on purpose: `auth-rejected` (refresh the
+  token), `unreachable` (on a corporate host, almost always the VPN),
+  `no-host-configured` (a token with nowhere to point), `well-formed` (valid shape,
+  liveness needs more input), `not-probeable`. Collapsing them into one "failed" bucket
+  is what led the user to three different wrong actions. Only configured credentials are
+  probed - an unmapped key is a capability the user chose not to enable.
+- `smoke-credential-awareness.sh` (32 assertions) and `test/phase0-exit-gate.test.mjs`
+  (20 cases) lock all of the above, including two secret-leak checks and the rule that
+  the credential reaches curl through a stdin config rather than argv, where any `ps`
+  could read it.
+- `smoke-install-layout.sh --update-fixture` regenerates the layout fixture from the
+  tree the gate itself installs. The documented hand-rolled recipe omitted the seeded
+  probe plugin, so following it baked a three-file shortfall into the fixture and the
+  next run failed on a drift that was really a bad regen.
+
+### Fixed
+
+- **The Phase 0 exit gate now asserts that the pickers ran.** It checked `taskType` and
+  the Figma access tier only, so a run that skipped the project and branch pickers and
+  developed straight on the local checkout passed cleanly - which is exactly what a
+  reported run did with a Jira ID. The gate now also requires `baseBranch`,
+  a `baseFetchStatus` from the known set, and a worktree path distinct from the project
+  root. Branch selection is marked non-skippable in `phase-0-init.md`, in every mode:
+  `--dev` skips the LLM phases, not Phase 0's pickers.
+- **An unreachable external source is announced instead of absorbed.** Exit code `3`
+  used to mean "mark it failed and continue", so 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 planned from a partial picture and reported success.
+  `external-context-injection.md` now classifies the stderr and surfaces a decision -
+  refresh the credential, connect the VPN and retry, supply a current URL, or continue
+  without - records `userDecision` in state, and requires autopilot to report what it
+  skipped rather than hide it. Retry is a real branch, not a label.
+- The base-branch and fetch-failure pickers were still written as ASCII numbered menus
+  in `phase-0-init.md`, against the picker contract's native-widget rule. Both are now
+  expressed as picker options, and the fetch-failure question names the corporate host
+  when the remote points at one - a host that will not resolve is almost always the VPN,
+  and saying so is the difference between a five-second fix and a run built on a stale ref.
+- `credential-inventory.sh --json` returned empty arrays while the table mode looked
+  correct: `python3 - <<EOF` takes its script from stdin, so the piped payload never
+  reached `sys.stdin`. Caught by the new gate on its first run.
+- The probe read hosts from `global.<service>Host`; the real path is
+  `global.hosts.<service>`, so every self-hosted service reported
+  `no-host-configured`. Found by running the probe against the real preferences instead
+  of trusting the field name.
+- `figma_mcp` is an OAuth token for the MCP server, not a REST PAT: probing it against
+  `api.figma.com` returned 403 for a healthy token and would have sent the user to
+  regenerate something that worked. It is now reported as not-probeable, with liveness
+  left to `figma-mcp-refresh.sh`, which owns the grant.
+- A failed `curl` wrote `000` through `write-out` *and* triggered the `|| echo "000"`
+  fallback, producing `000000` and a bogus verdict for what was simply a closed VPN.
+  Any non-three-digit status now reads as `probe-error` rather than being dressed up as
+  a service verdict.
+- `multi-agent-refs/rules.md` pointed at `~/.claude/scripts/vercel-deploy.sh`; the
+  wrapper installs to `lib/` with the other shell libraries. It had been reported as a
+  dangling reference for several releases.
+- `/multi-agent:setup` no longer describes an unreachable discovery source as skipped
+  "silently". Setup is where the user is configuring things, so a source that could not
+  be reached is precisely what they need told, with the classification that decides
+  their next move.
+
 ## [13.3.0] - 2026-07-28
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "13.3.0",
+  "version": "13.4.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

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

@@ -633,7 +633,8 @@ Entries are objects (not bare strings). The schema `recentProjects.items` is a `
 
 **7g. Skip / degrade rules**
 
-- Source failure (network, VPN, 401, rate-limit) skips that source silently; the others still run. Failure is recorded in `serviceStatus.{service} = { ok: false, checkedAt: <now>, reason: <short> }` so Phase 0 can also read that cache.
+- Source failure (network, VPN, 401, rate-limit) skips that source; the others still run. Failure is recorded in `serviceStatus.{service} = { ok: false, checkedAt: <now>, reason: <short> }` so Phase 0 can also read that cache.
+- **Report the skip, do not swallow it.** Setup is where the user is actively configuring things, so a source that could not be reached is exactly what they need to hear about, and the reason decides their next move: a 401 means refresh that token, no response at all on a corporate host means connect the VPN, and a missing `global.hosts.<service>` means the token has nowhere to point. Print one line per skipped source with its classification (see `refs/keychain.md` Rule 2) before moving on. A discovery pass that quietly returned three repos out of forty reads as "you only have three repos".
 - If all three sources yield zero hits, Step 5 is a no-op  -  the picker in Phase 0 falls back to manual path entry.
 - Discovery is **never destructive**: it never modifies git state, never writes outside `PREFS_FILE`.
 - Step 5 is idempotent. Re-running it refreshes `recentProjects` and `serviceStatus` but preserves user-curated entries unless explicitly deselected.

package/pipeline/lib/credential-inventory.sh

@@ -0,0 +1,351 @@
+#!/usr/bin/env bash
+# credential-inventory.sh  -  what the pipeline can reach right now, and what it cannot.
+#
+# WHY THIS EXISTS
+#
+# A run asked the user to paste a Crashlytics stack trace by hand while a Firebase
+# service-account JSON sat in the Keychain, mapped as `firebase`, fully valid. Nothing
+# was broken - the pipeline simply never asked itself "do I already hold a credential
+# that answers this?" before asking the user. From the user's side that is worse than a
+# failure: they had supplied the key precisely so this would not happen.
+#
+# One command, so there is no excuse for asking blind. Run it before any question that
+# requests data an external system holds, and let the answer shape the question:
+#
+#   - credential present  -> ask for the *pointer* (the issue URL), not the payload,
+#                            and say you will fetch it
+#   - credential missing  -> say which logical key is unmapped and offer the Save Flow
+#   - credential dead     -> say it is expired and offer to refresh it
+#
+# SAFETY
+#
+# Values are never printed, never stored in a variable that reaches stdout, and never
+# logged. Presence is probed through `credential-store.sh get` with stdout discarded, so
+# the secret goes to /dev/null and only the exit status is read.
+#
+# Usage:
+#   credential-inventory.sh              # human-readable table
+#   credential-inventory.sh --json       # machine-readable, for state files
+#   credential-inventory.sh --probe      # also verify each configured service answers
+#   credential-inventory.sh --key firebase   # single logical key, exit 0 present / 1 not
+#
+# PRESENT IS NOT THE SAME AS WORKING
+#
+# Without --probe this reports what is configured. With --probe each configured
+# credential makes one cheap authenticated request, and the verdict distinguishes the
+# three failures that need three different user actions:
+#
+#   reachable          the service answered and accepted the credential
+#   auth-rejected      401/403 - the credential is dead, the user must refresh it
+#   unreachable        no response at all - on a corporate host, almost always the VPN
+#   no-host-configured a token exists but its host was never recorded in preferences
+#   well-formed        structurally valid, liveness not checkable without more input
+#   not-probeable      no cheap probe exists for this credential type
+#
+# Only configured credentials are probed. An unmapped key is a capability the user chose
+# not to enable, not a problem to report.
+#
+# Exit codes: 0 = inventory produced (or the queried key is present), 1 = queried key
+# absent, 3 = usage error.
+
+set -uo pipefail
+
+PREFS="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+
+STORE=""
+for c in "$HOME/.claude/lib/credential-store.sh" "$HOME/.copilot/lib/credential-store.sh" \
+         "$HOME/.codex/lib/credential-store.sh" "$(dirname "$0")/credential-store.sh"; do
+  [ -f "$c" ] && { STORE="$c"; break; }
+done
+
+MODE="table"
+QUERY=""
+PROBE=0
+TIMEOUT="${MULTI_AGENT_PROBE_TIMEOUT:-6}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --json)  MODE="json"; shift ;;
+    --probe) PROBE=1; shift ;;
+    --key)   QUERY="${2:-}"; shift 2 || shift ;;
+    -h|--help)
+      echo "usage: $0 [--json] [--probe] [--key <logical-key>]" >&2; exit 3 ;;
+    *) echo "ERR: unexpected arg $1" >&2; exit 3 ;;
+  esac
+done
+
+pref() {  # pref <dotted.path> -> value or empty
+  [ -f "$PREFS" ] || return 0
+  python3 - "$PREFS" "$1" <<'PYPREF' 2>/dev/null
+import json, sys
+try:
+    d = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+for k in sys.argv[2].split("."):
+    if not isinstance(d, dict):
+        sys.exit(0)
+    d = d.get(k)
+    if d is None:
+        sys.exit(0)
+print(d if not isinstance(d, (dict, list)) else "")
+PYPREF
+}
+
+# An authenticated request whose credential never appears in argv.
+#
+# `curl -H "Authorization: Bearer $TOK"` puts the secret in the process command line,
+# where any `ps` on the machine can read it. `--config -` takes both the header and the
+# URL from stdin instead, so the token exists only in the pipe. Same reason the Vercel
+# wrapper refuses a `--token=` argv.
+#
+# probe_http <url> <header-name> <header-value> -> prints the HTTP status
+probe_http() {
+  local url="$1" hname="$2" hval="$3" out
+  # No `|| echo 000` here: curl already writes `000` through write-out when it never
+  # got a response, and exits non-zero as well. Appending produced `000000`, which fell
+  # through classify_status into a bogus `unexpected-000000` verdict for what was simply
+  # a closed VPN.
+  out=$(printf 'url = "%s"\nheader = "%s: %s"\nsilent\noutput = "/dev/null"\nwrite-out = "%%{http_code}"\nmax-time = %s\n' \
+    "$url" "$hname" "$hval" "$TIMEOUT" | curl --config - 2>/dev/null)
+  printf '%s' "${out:-000}"
+}
+
+# probe_basic <url> <user> <pass> -> prints the HTTP status
+probe_basic() {
+  local url="$1" u="$2" p="$3" out
+  out=$(printf 'url = "%s"\nuser = "%s:%s"\nsilent\noutput = "/dev/null"\nwrite-out = "%%{http_code}"\nmax-time = %s\n' \
+    "$url" "$u" "$p" "$TIMEOUT" | curl --config - 2>/dev/null)
+  printf '%s' "${out:-000}"
+}
+
+# Map an HTTP status onto the vocabulary the pipeline reasons about. `000` is curl's
+# "never got a response" - DNS failure, refused connection, timeout - which on a
+# corporate host is almost always a closed VPN, and is a completely different user
+# action from a rejected credential.
+classify_status() {
+  case "$1" in
+    2??)      echo "reachable" ;;
+    401|403)  echo "auth-rejected" ;;
+    404)      echo "reachable" ;;   # endpoint answered; the probe path may just not exist
+    000|"")   echo "unreachable" ;;
+    5??)      echo "server-error" ;;
+    # Anything that is not a three-digit status means the probe itself misbehaved.
+    # Saying so beats inventing a service verdict from a malformed value.
+    *)        echo "probe-error" ;;
+  esac
+}
+
+# Reachability for one logical key. Never prints a credential; the value is piped
+# straight into curl's stdin config and discarded.
+#
+# Hosts always come from preferences - a self-hosted Jira / Bitbucket / Confluence /
+# Fortify / Graylog address is deployment-specific and must never be baked in. Only
+# genuinely global public APIs are named literally. Host keys live at
+# `global.hosts.<service>` per prefs.schema.json - an earlier version of this probe
+# guessed `global.<service>Host` and reported no-host-configured for every
+# self-hosted service the user had actually configured.
+probe_one() {
+  local key="$1" tok host status
+  tok=$(bash "$STORE" get "$key" 2>/dev/null) || { echo "no-credential"; return; }
+  [ -n "$tok" ] || { echo "no-credential"; return; }
+
+  case "$key" in
+    jira)
+      host=$(pref global.hosts.jira)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/rest/api/2/myself" "Authorization" "Bearer $tok") ;;
+    confluence)
+      host=$(pref global.hosts.confluence)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/rest/api/user/current" "Authorization" "Bearer $tok") ;;
+    bitbucket_token)
+      host=$(pref global.hosts.bitbucket)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      local bbuser bbkey
+      bbkey=$(pref global.keychainMapping.bitbucket_user)
+      bbuser=$([ -n "$bbkey" ] && bash "$STORE" get bitbucket_user 2>/dev/null || echo "")
+      if [ -n "$bbuser" ]; then
+        status=$(probe_basic "https://${host}/rest/api/1.0/repos?limit=1" "$bbuser" "$tok")
+      else
+        status=$(probe_http "https://${host}/rest/api/1.0/repos?limit=1" "Authorization" "Bearer $tok")
+      fi ;;
+    github)
+      status=$(probe_http "https://api.github.com/user" "Authorization" "Bearer $tok") ;;
+    figma)
+      status=$(probe_http "https://api.figma.com/v1/me" "X-Figma-Token" "$tok") ;;
+    figma_mcp)
+      # An OAuth token for the Figma MCP server, not a REST PAT. Sending it to
+      # api.figma.com returns 403 for a perfectly healthy token, which is worse than
+      # not probing: it would send the user to regenerate something that works.
+      # Liveness for this one belongs to figma-mcp-refresh.sh, which owns the grant.
+      printf '%s' "$tok" | grep -q . && echo "not-probeable" || echo "malformed"
+      return ;;
+    npm)
+      status=$(probe_http "https://registry.npmjs.org/-/whoami" "Authorization" "Bearer $tok") ;;
+    fortify)
+      host=$(pref global.hosts.fortify)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/api/v1/projects?limit=1" "Authorization" "Bearer $tok") ;;
+    graylog)
+      host=$(pref global.hosts.graylog)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/api/system" "Authorization" "Bearer $tok") ;;
+    jenkins)
+      host=$(pref global.hosts.jenkins)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/api/json" "Authorization" "Bearer $tok") ;;
+    firebase)
+      # A service-account JSON, not a bearer token: an OAuth exchange would be needed
+      # to reach Crashlytics, and the fetcher does that per issue. Verifying the shape
+      # is honest about what is known - well-formed, not proven reachable.
+      if printf '%s' "$tok" | python3 -c 'import json,sys; d=json.load(sys.stdin); sys.exit(0 if d.get("project_id") and d.get("private_key") else 1)' 2>/dev/null; then
+        echo "well-formed"; return
+      fi
+      echo "malformed"; return ;;
+    appstore_connect_private_key)
+      printf '%s' "$tok" | grep -q "BEGIN PRIVATE KEY" && echo "well-formed" || echo "malformed"
+      return ;;
+    *)
+      echo "not-probeable"; return ;;
+  esac
+  classify_status "$status"
+}
+
+# What each logical key unlocks, in the pipeline's own terms. This is the column that
+# turns an inventory into an actionable question: "I hold `firebase`, so give me the
+# issue URL and I will pull the stack trace" is only sayable if the capability is
+# written down somewhere.
+capability_of() {
+  case "$1" in
+    jira)              echo "read the ticket, its comments and its linked issues; post the Phase 7 comment" ;;
+    bitbucket_token)   echo "read the repo, open and update pull requests" ;;
+    bitbucket_user)    echo "identify the PR author (paired with bitbucket_token)" ;;
+    github)            echo "read issues, open pull requests, read Actions runs" ;;
+    confluence)        echo "read linked pages and publish the analysis document" ;;
+    firebase)          echo "pull a Crashlytics issue: stack frames, affected versions, device spread (needs the issue URL)" ;;
+    fortify)           echo "pull a static-analysis finding and its remediation guidance" ;;
+    graylog)           echo "pull request logs by transaction or conversation id (advisory)" ;;
+    figma|figma_mcp)   echo "fetch design context, screenshots and Code Connect mappings" ;;
+    jenkins)           echo "read build results" ;;
+    npm)               echo "publish to the npm registry" ;;
+    appstore_connect_key_id|appstore_connect_issuer_id|appstore_connect_private_key)
+                       echo "validate an archive against App Store rules before submission" ;;
+    claude_oauth_token|claude_oauth_token_fallback)
+                       echo "run headless review and analysis passes" ;;
+    *)                 echo "(no capability recorded for this key)" ;;
+  esac
+}
+
+mapping_keys() {
+  [ -f "$PREFS" ] || return 0
+  python3 - "$PREFS" <<'PY' 2>/dev/null
+import json, sys
+try:
+    p = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+m = (p.get("global") or {}).get("keychainMapping") or {}
+for k, v in m.items():
+    print(f"{k}\t{'1' if v else '0'}")
+PY
+}
+
+# Presence probe. The value lands in /dev/null; only the exit status is observed.
+probe() {
+  [ -n "$STORE" ] || return 2
+  bash "$STORE" get "$1" >/dev/null 2>&1
+}
+
+if [ -n "$QUERY" ]; then
+  probe "$QUERY"
+  rc=$?
+  case "$rc" in
+    0)
+      if [ "$PROBE" = "1" ]; then
+        echo "$QUERY: present, $(probe_one "$QUERY")  -  can $(capability_of "$QUERY")"
+      else
+        echo "$QUERY: present  -  can $(capability_of "$QUERY")"
+      fi
+      exit 0 ;;
+    2) echo "$QUERY: no credential helper on this host" >&2; exit 1 ;;
+    *) echo "$QUERY: NOT AVAILABLE  -  onboard it via /multi-agent:setup before relying on it" >&2; exit 1 ;;
+  esac
+fi
+
+ROWS=""
+while IFS=$'\t' read -r key mapped; do
+  [ -z "$key" ] && continue
+  if [ "$mapped" != "1" ]; then
+    state="unmapped"
+    reach="not-probed"
+  elif probe "$key"; then
+    state="present"
+    # Only configured credentials are probed. A key the user never onboarded is not a
+    # problem to report - it is a capability they chose not to enable.
+    reach=$([ "$PROBE" = "1" ] && probe_one "$key" || echo "not-probed")
+  else
+    state="mapped-but-missing"
+    reach="not-probed"
+  fi
+  ROWS="${ROWS}${key}\t${state}\t${reach}\t$(capability_of "$key")\n"
+done < <(mapping_keys)
+
+if [ -z "$ROWS" ]; then
+  if [ "$MODE" = "json" ]; then
+    echo '{"status":"empty","reason":"no keychainMapping in preferences","credentials":[]}'
+  else
+    echo "no keychainMapping found in $PREFS  -  run /multi-agent:setup" >&2
+  fi
+  exit 0
+fi
+
+if [ "$MODE" = "json" ]; then
+  # The rows travel through a temp file, not a pipe. `python3 - <<EOF` takes its SCRIPT
+  # from stdin, so a piped payload never reaches sys.stdin: --json came back with empty
+  # arrays while the table mode looked correct. Caught by smoke-credential-awareness.
+  ROWS_FILE="$(mktemp)"
+  trap 'rm -f "$ROWS_FILE"' EXIT
+  printf '%b' "$ROWS" > "$ROWS_FILE"
+  python3 - "$ROWS_FILE" <<'PYJSON'
+import json, sys
+rows = []
+with open(sys.argv[1]) as fh:
+    for line in fh:
+        line = line.rstrip("\n")
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) < 4:
+            continue
+        rows.append({
+            "logical": parts[0],
+            "state": parts[1],
+            "reachability": parts[2],
+            "capability": parts[3],
+        })
+
+# `usable` is presence only, so a caller that never probed still gets a meaningful
+# answer. `reachable` is the stronger claim and exists only after --probe.
+OK_REACH = {"reachable", "well-formed"}
+BLOCKED = {"auth-rejected", "malformed"}
+probed = [r for r in rows if r["reachability"] != "not-probed"]
+print(json.dumps({
+    "status": "ok",
+    "probed": bool(probed),
+    "usable": [r["logical"] for r in rows if r["state"] == "present"],
+    "needsAttention": [r["logical"] for r in rows if r["state"] != "present"],
+    # Separated on purpose: a dead token is the user's to refresh, an unreachable host
+    # is usually a closed VPN, and a missing host is a setup gap. Collapsing them into
+    # one "failed" bucket is what made the pipeline ask blind questions.
+    "reachable": [r["logical"] for r in probed if r["reachability"] in OK_REACH],
+    "authRejected": [r["logical"] for r in probed if r["reachability"] in BLOCKED],
+    "unreachable": [r["logical"] for r in probed if r["reachability"] == "unreachable"],
+    "noHostConfigured": [r["logical"] for r in probed if r["reachability"] == "no-host-configured"],
+    "credentials": rows,
+}, indent=2))
+PYJSON
+else
+  printf '%b' "$ROWS" | awk -F'\t' '
+    BEGIN { printf "%-28s %-20s %-20s %s\n", "LOGICAL KEY", "STATE", "REACHABILITY", "UNLOCKS" }
+    { printf "%-28s %-20s %-20s %s\n", $1, $2, $3, $4 }'
+fi

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/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:**