@mmerterden/multi-agent-pipeline 12.7.0 → 12.9.0

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

@@ -0,0 +1,65 @@
+# Phase 4 Review  -  Multi-Repo Mode
+
+> Loaded on demand from `phases/phase-4-review.md`. Conditional on
+> `state.projects[].length > 1`; a single-repo run (the common case) never needs
+> it and used to pay for it on every review.
+
+
+Active when `state.projects[].length > 1`. The 3-reviewer/triage architecture is unchanged  -  what changes is the diff that reviewers see.
+
+**Combined diff assembly**  -  reviewers get **one combined diff** covering all repos, with explicit per-repo headers so they can flag cross-repo impact:
+
+```bash
+COMBINED_DIFF=$(mktemp)
+for proj in $(jq -r '.projects[] | "\(.name)\t\(.worktreePath)\t\(.baseBranch)"' "$STATE_FILE"); do
+  IFS=$'\t' read -r name wt base <<< "$proj"
+  ORIGIN=$(git -C "$wt" config --get remote.origin.url)
+  printf '\n=== repo: %s (origin: %s) ===\n' "$name" "$ORIGIN" >> "$COMBINED_DIFF"
+  printf 'Base: %s ... HEAD\n\n' "$base" >> "$COMBINED_DIFF"
+  git -C "$wt" diff "origin/$base...HEAD" >> "$COMBINED_DIFF"
+done
+```
+
+Same reviewer set (Fable-or-Opus / GPT-5.4 / Sonnet) receive `COMBINED_DIFF` with a multi-repo prefix in the system prompt:
+
+```
+This is a multi-repo task spanning {N} repos: {repo names}.
+Each repo's diff is prefixed with `=== repo: <name> ===`.
+A finding may span repos (e.g. "common adds API X, but uicomponents calls X with wrong type").
+For cross-repo findings, set `crossRepo: true` and list all impacted repos in `affectedRepos: []`.
+```
+
+**Schema extension for findings** (additive, single-repo `crossRepo` defaults to false):
+
+```json
+{
+  "severity": "blocking|important|suggestion",
+  "file": "uicomponents/Sources/Foo.swift",
+  "line": 42,
+  "issue": "...",
+  "fix": "...",
+  "crossRepo": false,
+  "affectedRepos": []
+}
+```
+
+`file` paths are repo-name-prefixed (`<repo-name>/<path-relative-to-repo>`) so triage and rework can resolve them back to the right worktree. The triage prompt receives `state.projects[]` so it can validate `affectedRepos` entries.
+
+**Triage cross-check**: Cross-repo findings are NEVER auto-rejected  -  the cross-cutting nature is exactly what reviewers are best at catching. Triage may still defer (out-of-scope) but rejection requires explicit reasoning.
+
+**Token-budget guard** (per `token-budget.json` Phase 4 allowance): if `COMBINED_DIFF` exceeds 80% of the budget, truncate the largest repo's diff with a footer header:
+```
+[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]
+```
+And log `review.diff_truncated repo=<name> bytes_dropped=<N>`. Triage receives the same truncated view + the truncation marker so it can flag suggestions to "review the full diff manually."
+
+**Deterministic gates per repo**: Step 1 gates (build/lint/test/secrets) run **per repo**  -  failure in any one repo blocks AI review for the whole task. Build queue lock applies as in Phase 3 (multi-repo doesn't change Xcode serialization).
+
+**Telemetry**: Per-repo build/test gate timings + a single combined review/triage call set:
+```bash
+pipeline/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=common status=pass duration_ms=$D
+pipeline/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=uicomponents status=pass duration_ms=$D
+pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.combined_diff repos=2 bytes=$BYTES truncated=false
+```
+
+---

package/pipeline/multi-agent-refs/features/url-enrichment.md

@@ -0,0 +1,93 @@
+# Step 1b  -  URL Enrichment (Phase 0)
+
+> Loaded on demand from `phases/phase-0-init.md` Step 1b. It lives here rather
+> than inline because it applies only to a task that carries URLs: a bare Jira
+> ID, a GitHub issue number, or a free-text task never needs any of it, yet every
+> run used to pay for all 9.6 kB of it. Deep-fetch sub-steps 1b.1-1b.3 are
+> themselves conditional on `state.contextLinks[]` carrying that link type.
+
+
+After Step 1 fetches the Jira description (or free-text input), every URL in the text gets classified and catalogued. Targeted deep fetches (Crashlytics, Fortify) run when the matching link type is present; the rest (Swagger, Confluence, Figma, generic doc) are catalogued so Phase 1 (Analysis) can consume them via the typed fetchers documented in `$HOME/.claude/multi-agent-refs/channels/*.md`.
+
+##### Step 1b.0  -  Extract context links (always runs)
+
+Pipe the description text through `~/.claude/lib/context-link-extractor.sh` and store the result on the state:
+
+```bash
+printf '%s' "$DESCRIPTION_TEXT" \
+  | ~/.claude/lib/context-link-extractor.sh \
+  > /tmp/context-links-${TASK_ID}.json
+
+# Persist into agent-state.json under state.contextLinks
+jq --slurpfile links /tmp/context-links-${TASK_ID}.json \
+   '.contextLinks = $links[0]' \
+   "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+```
+
+Output schema (one array entry per URL  -  full contract in `~/.claude/lib/context-link-extractor.sh`):
+
+```jsonc
+"contextLinks": [
+  { "type": "swagger",     "url": "<url>", "metadata": { "format": "json|yaml|unknown" } },
+  { "type": "confluence",  "url": "<url>", "metadata": { "host": "<host>", "pageId": "<id|null>", "spaceKey": "<key|null>" } },
+  { "type": "crashlytics", "url": "<url>", "metadata": { "projectId": "...", "platform": "ios|android", "bundle": "...", "issueId": "...", "sessionId": "<id|null>" } },
+  { "type": "fortify",     "url": "<url>", "metadata": { "host": "<host>", "projectId": "<id|null>" } },
+  { "type": "graylog",     "url": null,    "metadata": { "idType": "trx|conversation", "id": "...", "label": "..." } },
+  { "type": "figma",       "url": "<url>", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "<id|null>" } },
+  { "type": "generic-doc", "url": "<url>", "metadata": { "host": "<host>", "kind": "notion|google-docs|gist|github-doc" } }
+]
+```
+
+The catalogue is the single source of truth for downstream phases  -  they read `state.contextLinks[]` and dispatch per `type`. The extractor is deterministic: same input → same output, no network calls, no auth.
+
+##### Step 1b.1  -  Firebase Crashlytics deep fetch (runs when `type == "crashlytics"` present in `state.contextLinks[]`)
+
+URL pattern (caught by the extractor): `console.firebase.google.com/(u/[0-9]+/)?project/<projectId>/crashlytics/app/(ios|android)(:|%3A)<bundleOrPackage>/issues/<issueId>(/sessions/<sessionId>)?`
+
+- Host is fixed (`console.firebase.google.com`); no `hosts.firebase` pref needed.
+- Token resolution: `prefs.global.keychainMapping.firebase` → `~/.claude/lib/credential-store.sh get "<key>" | base64 -d` → Service Account JSON. `project_id` read from decoded JSON  -  verify it matches the `<projectId>` from the URL; mismatch → warn, skip enrichment.
+- Exchange the SA JSON for a short-lived GCP access token (scope `https://www.googleapis.com/auth/firebase https://www.googleapis.com/auth/cloud-platform`) using `google-auth` (Python) or an inline JWT exchange (OpenSSL sign → `https://oauth2.googleapis.com/token`). Cache in-memory for the pipeline run only  -  never persist.
+- Fetch crash detail: `GET https://firebasecrashlytics.googleapis.com/v1alpha/projects/<projectId>/apps/<appId>/issues/<issueId>` (issue summary + top device + OS + impacted users + top stack frame). If `sessionId` present, also fetch `/sessions/<sessionId>` for the full session timeline.
+- Store as `state.crashContext = { projectId, appId, issueId, title, subtitle, impactedUsers, topDevices[], topOS[], topStackFrame, sessionTimeline?, fetchedAt }`.
+- Phase 1 Analysis prepends `state.crashContext` to the agent prompt under a **Known Crash Context** section (do not rediscover, use as ground truth).
+- Soft-fail: any network/auth error → log warning, continue pipeline without enrichment (ticket still gets manually analysed).
+
+##### Step 1b.2  -  Fortify SSC deep fetch (runs when `type == "fortify"` present in `state.contextLinks[]`)
+
+URL pattern (caught by the extractor): `https://<prefs.global.hosts.fortify>/ssc/html/(ssc/)?version/<versionId>(/.*)?(#/version/<versionId>)?(/audit|/issues|/artifacts)?(\?issue=<issueId>)?` (plus the short-link variant `/ssc/html/ssc/version/<versionId>/fix/<issueInstanceId>`).
+
+- Host comes from `prefs.global.hosts.fortify` (collected during Token Save Flow Step 3.5). URL host must match, else warn and skip (protects against pasting another company's Fortify URL by accident).
+- Token resolution: `prefs.global.keychainMapping.fortify` → `~/.claude/lib/credential-store.sh get "<key>"` → API token. Auth header: `Authorization: FortifyToken <base64(token)>` (legacy tokens) or `Bearer <token>` (scoped tokens)  -  try Bearer first, fall back to FortifyToken on 401.
+- Fetch finding detail (VPN required; respect `vpnServices.fortify`):
+  - Version: `GET /ssc/api/v1/projectVersions/<versionId>` → name, project name, current issue count.
+  - Issue list / single issue: if `issueInstanceId` in URL → `GET /ssc/api/v1/projectVersions/<versionId>/issues?q=issueInstanceId:"<id>"&fields=id,issueName,friority,fullFileName,lineNumber,analyzer,kingdom`. Otherwise fetch top open issue of the version.
+  - Issue details + recommendation: `GET /ssc/api/v1/issueDetails/<issueId>` → description, recommendation, code snippet (if the artifact is retained).
+- Store as `state.fortifyFinding = { host, versionId, versionName, projectName, issueId?, issueName?, severity, friority, kingdom, analyzer, file, line, description, recommendation, codeSnippet?, fetchedAt }`.
+- Phase 2 Planning injects `state.fortifyFinding` into the architectural-review prompt under a **Known Security Finding** section, and the generated task breakdown includes a task addressing the finding (naming convention: `sec(fortify-<issueId>): <issueName> at <file>:<line>`).
+- Soft-fail: 401 → re-run Token Save Flow for `fortify`; 403 → warn and skip; network timeout → respect VPN fallback (skip enrichment, mark `state.fortifyFinding = { skipped: "vpn-unreachable" }`).
+
+##### Step 1b.3  -  Graylog deep fetch (runs when `type == "graylog"` present in `state.contextLinks[]`)
+
+The extractor emits `graylog` entries from free-text trx / conversation ids (labels like `trx`, `trxId`, `transaction id`, `conversationId`, `convId`, `X-conversationId`), not from a URL  -  so these entries carry `"url": null`. When at least one is present, pull the matching diagnostic logs.
+
+- Host comes from `prefs.global.hosts.graylog` (`GRAYLOG_HOST_OVERRIDE` env forces it for tests/CI); no literal host lives in any source file. Missing host → the fetcher exits `6`; log a setup hint and skip.
+- Token resolution: `prefs.global.keychainMapping.graylog` → `~/.claude/lib/credential-store.sh get "<key>"` → Graylog PAT (fallback key `${USER}_Graylog_Access_Token`). Auth is HTTP Basic with the token as username and the literal `token` as password; the token is fed to `curl` only via a `-K` config file (process substitution), never on argv.
+- Fetch logs (VPN required; respect `vpnServices.graylog`): call `~/.claude/lib/fetch-graylog.sh --trx <id>` (or `--conv <id>` for conversation ids) once per extracted id. The fetcher emits a normalized JSON object of matching log messages.
+- Store as `state.graylogContext = { idType, id, messages[], fetchedAt }` (or an array keyed per id when several were extracted).
+- Phase 1 Analysis prepends `state.graylogContext` to the agent prompt under the **Referenced External Sources** section as **diagnostic context, advisory only** (never contradicts code; no task is generated from it, no Phase 4 gate).
+- Soft-fail (non-blocking, mirrors Crashlytics): unreachable host / VPN down / network timeout → the fetcher emits a normalized empty object and exits `0`; mark `state.graylogContext = { skipped: "vpn-unreachable" }` and continue. Only a genuine auth rejection (4xx on a reachable host, fetcher exit `3`) is logged as `skipped` with the auth reason. A log fetch never blocks the run.
+
+##### Step 1b.4  -  Other link types (catalogued only at Phase 0; fetched at Phase 1)
+
+For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLinks[]`, no Phase 0 fetch runs. The entries pass through to Phase 1, which dispatches the matching fetcher (Block B work: `fetch-swagger.sh`, `fetch-confluence.sh`, etc.). Until those fetchers land, the entries are surfaced in Phase 1 context as "referenced but not fetched  -  agent should treat the URL as an authoritative external source and read it directly when relevant."
+
+**Jira project key addendum**: Support multi-tenant Jira  -  `prefs.projects[{project}].jiraProjectKeys[]` is already a list. When Step 1 extracts a Jira key from input, `upsert` it at the head (dedup, cap 10). Sibling keys for the same project (e.g. one key per team or tracker board) coexist; `prefs.global.defaultJiraKey` is the fallback for ambiguous free-text input only.
+
+**Log line shape** (progress contract):
+
+```
+→ context links: total=<N>, by-type={swagger:<n>, confluence:<n>, crashlytics:<n>, fortify:<n>, graylog:<n>, figma:<n>, generic-doc:<n>}
+→ URL deep fetch: crashlytics=<hit|miss|skipped>, fortify=<hit|miss|skipped>, graylog=<hit|miss|skipped>
+```
+
+Two lines emit at the end of Step 1b. The first reports the catalogue from 1b.0 (always runs). The second reports the deep-fetch outcomes from 1b.1 / 1b.2 / 1b.3  -  `miss` = type not present in catalogue (normal), `skipped` = present but auth/VPN/mismatch skipped the fetch (for graylog this includes the non-blocking VPN-unreachable degrade), `hit` = context stored in state.

package/pipeline/multi-agent-refs/phases/operations.md

@@ -67,6 +67,34 @@ Run phases sequentially. Log every step to `agent-log.md`.
 If any phase fails, mark task as `paused` and stop  -  user can `resume` later.
 Update `agent-state.json` at EVERY phase transition.
 
+### Writing `agent-state.json` (required mechanism)
+
+Every state update goes through `write-state.mjs`. Never write the file with a
+plain read-modify-write (`jq ... > tmp && mv`, an editor tool, `cat >`):
+
+```bash
+# Merge a patch into the current state (the normal case).
+echo '{"currentPhase":4,"phases":{"4":{"status":"running"}}}' \
+  | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
+
+# Full replacement, only when rewriting the document wholesale.
+printf '%s' "$NEW_STATE" | node $HOME/.claude/scripts/write-state.mjs --replace "$STATE_FILE"
+```
+
+Why the indirection is required: multi-repo mode and concurrent worktrees share
+one `agent-state.json` per task id, so two writers using read-then-write lose one
+of the two updates  -  the second write is computed from a snapshot taken before
+the first landed. `write-state.mjs` does tmpfile + rename (atomic on POSIX) under
+an advisory `.lock`, reclaims a lock whose holder PID is dead, and releases the
+lock on every error path.
+
+Exit codes the caller must handle: `0` written, `1` invalid JSON on stdin, `2`
+lock timeout (another writer held it past the acquire window  -  retry once, then
+halt per the halt-visibility rule), `3` I/O error.
+
+Reads need no wrapper; the rename makes any read see either the old or the new
+document, never a truncated one.
+
 **Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`. Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log.
 
 ### Pipeline Best Practices

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

@@ -200,90 +200,9 @@ Sequential prompts (standard UX pattern with Recent suggestion): Project Key →
 
 #### Step 1b  -  URL Enrichment (catalogue + targeted deep fetches)
 
-After Step 1 fetches the Jira description (or free-text input), every URL in the text gets classified and catalogued. Targeted deep fetches (Crashlytics, Fortify) run when the matching link type is present; the rest (Swagger, Confluence, Figma, generic doc) are catalogued so Phase 1 (Analysis) can consume them via the typed fetchers documented in `$HOME/.claude/multi-agent-refs/channels/*.md`.
+**Runs only when Step 1 found at least one URL in the task input** (Jira/Confluence/Figma/Swagger/Crashlytics/Fortify/Graylog links). Otherwise skip straight to Step 2.
 
-##### Step 1b.0  -  Extract context links (always runs)
-
-Pipe the description text through `~/.claude/lib/context-link-extractor.sh` and store the result on the state:
-
-```bash
-printf '%s' "$DESCRIPTION_TEXT" \
-  | ~/.claude/lib/context-link-extractor.sh \
-  > /tmp/context-links-${TASK_ID}.json
-
-# Persist into agent-state.json under state.contextLinks
-jq --slurpfile links /tmp/context-links-${TASK_ID}.json \
-   '.contextLinks = $links[0]' \
-   "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
-```
-
-Output schema (one array entry per URL  -  full contract in `~/.claude/lib/context-link-extractor.sh`):
-
-```jsonc
-"contextLinks": [
-  { "type": "swagger",     "url": "<url>", "metadata": { "format": "json|yaml|unknown" } },
-  { "type": "confluence",  "url": "<url>", "metadata": { "host": "<host>", "pageId": "<id|null>", "spaceKey": "<key|null>" } },
-  { "type": "crashlytics", "url": "<url>", "metadata": { "projectId": "...", "platform": "ios|android", "bundle": "...", "issueId": "...", "sessionId": "<id|null>" } },
-  { "type": "fortify",     "url": "<url>", "metadata": { "host": "<host>", "projectId": "<id|null>" } },
-  { "type": "graylog",     "url": null,    "metadata": { "idType": "trx|conversation", "id": "...", "label": "..." } },
-  { "type": "figma",       "url": "<url>", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "<id|null>" } },
-  { "type": "generic-doc", "url": "<url>", "metadata": { "host": "<host>", "kind": "notion|google-docs|gist|github-doc" } }
-]
-```
-
-The catalogue is the single source of truth for downstream phases  -  they read `state.contextLinks[]` and dispatch per `type`. The extractor is deterministic: same input → same output, no network calls, no auth.
-
-##### Step 1b.1  -  Firebase Crashlytics deep fetch (runs when `type == "crashlytics"` present in `state.contextLinks[]`)
-
-URL pattern (caught by the extractor): `console.firebase.google.com/(u/[0-9]+/)?project/<projectId>/crashlytics/app/(ios|android)(:|%3A)<bundleOrPackage>/issues/<issueId>(/sessions/<sessionId>)?`
-
-- Host is fixed (`console.firebase.google.com`); no `hosts.firebase` pref needed.
-- Token resolution: `prefs.global.keychainMapping.firebase` → `~/.claude/lib/credential-store.sh get "<key>" | base64 -d` → Service Account JSON. `project_id` read from decoded JSON  -  verify it matches the `<projectId>` from the URL; mismatch → warn, skip enrichment.
-- Exchange the SA JSON for a short-lived GCP access token (scope `https://www.googleapis.com/auth/firebase https://www.googleapis.com/auth/cloud-platform`) using `google-auth` (Python) or an inline JWT exchange (OpenSSL sign → `https://oauth2.googleapis.com/token`). Cache in-memory for the pipeline run only  -  never persist.
-- Fetch crash detail: `GET https://firebasecrashlytics.googleapis.com/v1alpha/projects/<projectId>/apps/<appId>/issues/<issueId>` (issue summary + top device + OS + impacted users + top stack frame). If `sessionId` present, also fetch `/sessions/<sessionId>` for the full session timeline.
-- Store as `state.crashContext = { projectId, appId, issueId, title, subtitle, impactedUsers, topDevices[], topOS[], topStackFrame, sessionTimeline?, fetchedAt }`.
-- Phase 1 Analysis prepends `state.crashContext` to the agent prompt under a **Known Crash Context** section (do not rediscover, use as ground truth).
-- Soft-fail: any network/auth error → log warning, continue pipeline without enrichment (ticket still gets manually analysed).
-
-##### Step 1b.2  -  Fortify SSC deep fetch (runs when `type == "fortify"` present in `state.contextLinks[]`)
-
-URL pattern (caught by the extractor): `https://<prefs.global.hosts.fortify>/ssc/html/(ssc/)?version/<versionId>(/.*)?(#/version/<versionId>)?(/audit|/issues|/artifacts)?(\?issue=<issueId>)?` (plus the short-link variant `/ssc/html/ssc/version/<versionId>/fix/<issueInstanceId>`).
-
-- Host comes from `prefs.global.hosts.fortify` (collected during Token Save Flow Step 3.5). URL host must match, else warn and skip (protects against pasting another company's Fortify URL by accident).
-- Token resolution: `prefs.global.keychainMapping.fortify` → `~/.claude/lib/credential-store.sh get "<key>"` → API token. Auth header: `Authorization: FortifyToken <base64(token)>` (legacy tokens) or `Bearer <token>` (scoped tokens)  -  try Bearer first, fall back to FortifyToken on 401.
-- Fetch finding detail (VPN required; respect `vpnServices.fortify`):
-  - Version: `GET /ssc/api/v1/projectVersions/<versionId>` → name, project name, current issue count.
-  - Issue list / single issue: if `issueInstanceId` in URL → `GET /ssc/api/v1/projectVersions/<versionId>/issues?q=issueInstanceId:"<id>"&fields=id,issueName,friority,fullFileName,lineNumber,analyzer,kingdom`. Otherwise fetch top open issue of the version.
-  - Issue details + recommendation: `GET /ssc/api/v1/issueDetails/<issueId>` → description, recommendation, code snippet (if the artifact is retained).
-- Store as `state.fortifyFinding = { host, versionId, versionName, projectName, issueId?, issueName?, severity, friority, kingdom, analyzer, file, line, description, recommendation, codeSnippet?, fetchedAt }`.
-- Phase 2 Planning injects `state.fortifyFinding` into the architectural-review prompt under a **Known Security Finding** section, and the generated task breakdown includes a task addressing the finding (naming convention: `sec(fortify-<issueId>): <issueName> at <file>:<line>`).
-- Soft-fail: 401 → re-run Token Save Flow for `fortify`; 403 → warn and skip; network timeout → respect VPN fallback (skip enrichment, mark `state.fortifyFinding = { skipped: "vpn-unreachable" }`).
-
-##### Step 1b.3  -  Graylog deep fetch (runs when `type == "graylog"` present in `state.contextLinks[]`)
-
-The extractor emits `graylog` entries from free-text trx / conversation ids (labels like `trx`, `trxId`, `transaction id`, `conversationId`, `convId`, `X-conversationId`), not from a URL  -  so these entries carry `"url": null`. When at least one is present, pull the matching diagnostic logs.
-
-- Host comes from `prefs.global.hosts.graylog` (`GRAYLOG_HOST_OVERRIDE` env forces it for tests/CI); no literal host lives in any source file. Missing host → the fetcher exits `6`; log a setup hint and skip.
-- Token resolution: `prefs.global.keychainMapping.graylog` → `~/.claude/lib/credential-store.sh get "<key>"` → Graylog PAT (fallback key `${USER}_Graylog_Access_Token`). Auth is HTTP Basic with the token as username and the literal `token` as password; the token is fed to `curl` only via a `-K` config file (process substitution), never on argv.
-- Fetch logs (VPN required; respect `vpnServices.graylog`): call `~/.claude/lib/fetch-graylog.sh --trx <id>` (or `--conv <id>` for conversation ids) once per extracted id. The fetcher emits a normalized JSON object of matching log messages.
-- Store as `state.graylogContext = { idType, id, messages[], fetchedAt }` (or an array keyed per id when several were extracted).
-- Phase 1 Analysis prepends `state.graylogContext` to the agent prompt under the **Referenced External Sources** section as **diagnostic context, advisory only** (never contradicts code; no task is generated from it, no Phase 4 gate).
-- Soft-fail (non-blocking, mirrors Crashlytics): unreachable host / VPN down / network timeout → the fetcher emits a normalized empty object and exits `0`; mark `state.graylogContext = { skipped: "vpn-unreachable" }` and continue. Only a genuine auth rejection (4xx on a reachable host, fetcher exit `3`) is logged as `skipped` with the auth reason. A log fetch never blocks the run.
-
-##### Step 1b.4  -  Other link types (catalogued only at Phase 0; fetched at Phase 1)
-
-For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLinks[]`, no Phase 0 fetch runs. The entries pass through to Phase 1, which dispatches the matching fetcher (Block B work: `fetch-swagger.sh`, `fetch-confluence.sh`, etc.). Until those fetchers land, the entries are surfaced in Phase 1 context as "referenced but not fetched  -  agent should treat the URL as an authoritative external source and read it directly when relevant."
-
-**Jira project key addendum**: Support multi-tenant Jira  -  `prefs.projects[{project}].jiraProjectKeys[]` is already a list. When Step 1 extracts a Jira key from input, `upsert` it at the head (dedup, cap 10). Sibling keys for the same project (e.g. one key per team or tracker board) coexist; `prefs.global.defaultJiraKey` is the fallback for ambiguous free-text input only.
-
-**Log line shape** (progress contract):
-
-```
-→ context links: total=<N>, by-type={swagger:<n>, confluence:<n>, crashlytics:<n>, fortify:<n>, graylog:<n>, figma:<n>, generic-doc:<n>}
-→ URL deep fetch: crashlytics=<hit|miss|skipped>, fortify=<hit|miss|skipped>, graylog=<hit|miss|skipped>
-```
-
-Two lines emit at the end of Step 1b. The first reports the catalogue from 1b.0 (always runs). The second reports the deep-fetch outcomes from 1b.1 / 1b.2 / 1b.3  -  `miss` = type not present in catalogue (normal), `skipped` = present but auth/VPN/mismatch skipped the fetch (for graylog this includes the non-blocking VPN-unreachable degrade), `hit` = context stored in state.
+When it runs, load `$HOME/.claude/multi-agent-refs/features/url-enrichment.md` and follow it. It covers: 1b.0 extract + catalogue every link into `state.contextLinks[]` (always runs when this step runs), then the deep fetches that are each conditional on their link type being present  -  1b.1 Crashlytics -> `state.crashContext`, 1b.2 Fortify SSC -> `state.fortifyFinding`, 1b.3 Graylog, 1b.4 catalogue-only types (fetched at Phase 1). It also owns the two closing log lines and the Phase 1 / Phase 2 prepend contracts.
 
 #### Step 2  -  Project Selection
 
@@ -487,6 +406,7 @@ done
 
 State file in multi-repo mode:
 - Single shared `agent-state.json` lives at `$HOME/.claude/logs/multi-agent/{first-project}/{task-id}/agent-state.json` (anchored on the first repo for back-compat with `multi-agent log`/`status` commands)
+- **One shared file + per-repo writers is exactly the race `write-state.mjs` exists for.** Every update to it (here and in every later phase) goes through `node $HOME/.claude/scripts/write-state.mjs` per the required mechanism in `operations.md` "Writing `agent-state.json`". A read-modify-write from two repos in the same loop drops one repo's `projects[]` entry.
 - `state.projects[]` holds per-repo `{name, root, worktreePath, branch, baseBranch, identity, platform, baseFetchStatus, commit, pr, pushAttempts, buildStatus}`  -  see `agent-state.schema.json`
 - Scalar fields (`project`, `projectRoot`, `worktreePath`, `branch`, `baseBranch`, `identity`) mirror `projects[0]` so legacy phases that read scalars keep working
 - Atomicity: if any repo's worktree creation fails (collision aborted, fetch aborted, disk full), roll back already-created worktrees: `git -C $proj worktree remove --force $WT_PATH; git -C $proj branch -D $BRANCH`. Never leave a partial multi-repo state.

package/pipeline/multi-agent-refs/phases/phase-2-planning.md

@@ -13,7 +13,7 @@ Phase 2 Planning consumes the analysis document. MCP forbidden.
    - Abort with `ERR: analysis doc missing. Run /multi-agent:analysis "<feature>" first.`
 
 2. **Parse YAML front-matter**: `feature`, `platform`, `language`, `mode`, `evidence_digest`, `template_version`. Persist into `state.analysis.frontMatter`.
-   - **Soft-skip (v9.1.0+, Locked 30)**: when `template_version == v2` AND (`prefs.global.legacyV2AnalysisAllowed == true` OR env `MULTI_AGENT_LEGACY_V2_ANALYSIS=allow`), emit `WARN: legacy v2 analysis doc detected; v3 expected. Continuing in degraded mode.` Step 3 section coverage check skips v3-specific sections (10 Localization, 11 Analytics, 12 Deeplink/Push, 13.6 SwiftUI Preview, 21 References). Phase 4 reviewer flags missing v3 sections rather than blocking. Escape hatch removed in v9.2.0; users must regenerate v3 docs by then.
+   - **`template_version` < `v3` aborts**: `ERR: analysis doc is template v<n>; v3 required. Re-run /multi-agent:analysis to regenerate.` No degraded mode.
 
 3. **Section coverage check**: verify these sections are non-empty (template v3 required sections per Locked 2):
    - Section 1 Summary, Section 2 Goals + Non-Goals, Section 4 User Stories, Section 9 API Contracts, Section 13 Architecture Plan, Section 14 Files to Add, Section 20 Risks, Section 21 References

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

@@ -16,8 +16,7 @@ Pre-flight steps (run in order, abort on failure):
 2. **Parse YAML front-matter** (the doc has a `template_version: v3` header):
    - `feature`, `platform`, `language`, `mode (full | lite)`, `evidence_digest`
    - Persist into `state.analysis.frontMatter`
-   - **Abort condition (v9.0.x strict)**: `template_version` < `v3` -> exit with `ERR: analysis doc is template v<n>; v9 requires v3. Re-run analysis to regenerate.`
-   - **Soft-skip (v9.1.0+, Locked 30)**: when `prefs.global.legacyV2AnalysisAllowed == true` OR env `MULTI_AGENT_LEGACY_V2_ANALYSIS=allow` is set AND `template_version == v2`, emit `WARN: legacy v2 analysis doc detected; v3 expected. Continuing with reduced binding strength.` and persist `state.dev.legacyAnalysisMode = true`. Step 4 (Code Connect lookup) and Step 6 (conventions handoff) still run, but Step 5 (standards binding) and Pass B footnote enforcement degrade to warning level (Phase 4 reviewer flags missing citations rather than blocking). Escape hatch removed in v9.2.0.
+   - **Abort condition**: `template_version` < `v3` -> exit with `ERR: analysis doc is template v<n>; v3 required. Re-run /multi-agent:analysis to regenerate.` No degraded mode.
 
 3. **Evidence digest match (cache validation)**: if `state.run.lastAnalysisDigest` is present AND matches `frontMatter.evidence_digest`, mark as fresh; otherwise WARN that analysis is stale (continue but flag).
 

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -112,11 +112,16 @@ Cost ledger: `phase-4.repo_map_emitted bytes=N budget=B cache_hit=true|false`  -
 
 Before dispatching reviewers, run the deterministic diff risk scorer and inject the top-N files into each reviewer's prompt as a priority hint. **Advisory only  -  never gates the pipeline.** Heuristic, zero LLM, runs in well under a second.
 
+Score the diff **once, in full** (no `--top`): Steps 1.76/1.77 need every scored file (a shrinking test file ranked 20th; whether ANY file is high-stakes). The top-N hint is derived from that report, not a second git walk.
+
 ```bash
-RISK_JSON=$(node pipeline/scripts/diff-risk-score.mjs \
+RISK_FULL=$(node pipeline/scripts/diff-risk-score.mjs \
   --base "$BASE_BRANCH" --head HEAD \
-  --task-id "$TASK_ID" --top 5 2>/dev/null)
-echo "$RISK_JSON" | node pipeline/scripts/validate-diff-risk.mjs - >/dev/null 2>&1 || RISK_JSON=""
+  --task-id "$TASK_ID" 2>/dev/null)
+echo "$RISK_FULL" | node pipeline/scripts/validate-diff-risk.mjs - >/dev/null 2>&1 || RISK_FULL=""
+
+# Priority hint for the reviewer prompts: top 5 of the full report.
+RISK_JSON=$([ -n "$RISK_FULL" ] && jq -c '.files |= (sort_by(-.score) | .[:5])' <<< "$RISK_FULL" || echo "")
 ```
 
 **Signals & weights** (see `pipeline/schemas/diff-risk.schema.json`):
@@ -151,6 +156,35 @@ pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.diff_risk \
 
 **Opt-out**: `prefs.global.diffRiskAdvisory = false` skips this step entirely (no script invocation, no priority block injection). Default `true` because the cost is bounded and the signal-to-noise has been measured against the golden-task fixture set.
 
+#### Step 1.76  -  Test-integrity gate (produces BLOCKING findings)
+
+Step 1.75 uses `test_lines_removed` as an advisory hint only  -  too weak for what it detects: a suite made green by deleting tests instead of fixing code. This turns the signal into blocking findings triage must adjudicate. Pure function of the full report, no git, no LLM.
+
+```bash
+TEST_INTEGRITY_JSON=$(printf '%s' "$RISK_FULL" | node pipeline/scripts/test-integrity-gate.mjs 2>/dev/null || echo "")
+TI_COUNT=$(jq -r '.count // 0' <<< "${TEST_INTEGRITY_JSON:-{\}}" 2>/dev/null || echo 0)
+[ "$TI_COUNT" -gt 0 ] && pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.test_integrity findings="$TI_COUNT"
+```
+
+`findings[]` are reviewer-shaped (`test_integrity`, `blocking`), so they merge into the reviewer findings at Step 3.0 and need no triage-prompt or `validate-triage.mjs` change. Triage keeps each blocking unless the removal is justified per the immutable-test rule (spec changed AND commit body names the test) → `deferred[]`.
+
+The gate never blocks the phase; it *emits* blocking findings. Empty or unreadable input yields zero findings and the phase continues. Feed it the FULL report  -  `--top` hides a shrinking test file below the cut. **No opt-out**: a run that can switch off its own anti-reward-hacking control cannot be trusted to report a pass.
+
+#### Step 1.77  -  Reviewer scope (cost gate)
+
+On a trivial diff every reviewer agrees and the extra models plus triage are paid for nothing. Reviewer count comes from the same report, no LLM.
+
+```bash
+SCOPE_JSON=$(printf '%s' "$RISK_FULL" | node pipeline/scripts/review-scope.mjs 2>/dev/null \
+  || echo '{"scope":"full","reason":"no risk report - failing safe"}')
+REVIEW_SCOPE=$(jq -r '.scope // "full"' <<< "$SCOPE_JSON")
+pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.scope scope="$REVIEW_SCOPE"
+```
+
+`single` (Reviewer 1 only) requires **all** of: churn <= 20 lines, `totals.max_score` < 3.0, and no `security_path` / `migration` / `public_api` / `no_test_change` / `test_lines_removed` on any file. Anything else → `full`.
+
+Fails safe in one direction only: empty report, parse failure or validator rejection all resolve to `full`, because skipping a reviewer trades coverage for cost. `consensus.reviewerCount` records what actually ran, so a single-reviewer run never reads as cross-model agreement. Opt-out: `prefs.global.reviewScopeGate = false` forces `full`.
+
 #### Step 1.8  -  Figma visual-fidelity context (when task carries a Figma reference)
 
 When `state.evidence.figma[]` is non-empty, the reviewer subagents MUST receive the captured screenshot URLs / paths and the canonical-component name (from `state.evidence.figma[i].screenshotUrl` and `state.evidence.figma[i].codeConnectSnippets[0].componentName` when present) so they can compare visual fidelity. Pass them inline in each reviewer prompt under a `## Figma evidence` block, one row per frame.
@@ -182,6 +216,8 @@ Phase 4 sends the same diff to every reviewer and then to triage, so the diff is
 
 Launch Agent instances **in parallel** using the shared `code-reviewer` subagent definition (`~/.claude/agents/code-reviewer.md`). The reviewer set is determined by the host CLI  -  GPT-5.4 is only available on Copilot CLI, so Claude Code skips that reviewer and runs a 2-model parallel review; Copilot CLI runs all three.
 
+**Scope from Step 1.77.** `$REVIEW_SCOPE == "single"` → dispatch **Reviewer 1 only**, and skip Step 2.5 + 3.6 (both no-ops with one reviewer). `"full"` (default + fail-safe) → the whole set below. Either way record the count in `consensus.reviewerCount`.
+
 | Reviewer   | subagent_type     | Model               | Focus                             | Skills Referenced                             | Where it runs        |
 | ---------- | ----------------- | ------------------- | --------------------------------- | --------------------------------------------- | -------------------- |
 | Reviewer 1 | `code-reviewer`   | `claude-fable-5` (Claude Code) / `claude-opus-4-8` (Copilot CLI) | Deep security + architecture      | `api-security-best-practices`, `architecture` | Both CLIs            |
@@ -259,9 +295,18 @@ Exit 0 = valid. Exit 2 = contradiction (approved=true with blocking findings)  -
 
 Opt-in empirical layer: when `prefs.global.verifyByTest.enabled` is `true`, accepted blocking findings additionally go through Step 3.7 (verify-by-test), which tries to reproduce each one with a minimal failing test before the Phase 3 rework loop fires. Full wiring: `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`.
 
+##### 3.0 Merge the deterministic findings in
+
+Append the Step 1.76 test-integrity findings to the reviewer findings before counting, so they are adjudicated like any reviewer finding rather than resolved by triage never seeing them:
+
+```bash
+MERGED=$(jq -s '.[0] + (.[1].findings // [])' \
+  <(printf '%s' "$REVIEWER_FINDINGS_JSON") <(printf '%s' "${TEST_INTEGRITY_JSON:-{\}}"))
+```
+
 ##### 3.1 Short-circuit: no findings
 
-If merged findings `length === 0`, **skip triage**: write empty result `{"accepted": [], "deferred": [], "rejected": [], "approved": true}`, log, proceed to Phase 5.
+If **merged** findings `length === 0`, **skip triage**: write empty result `{"accepted": [], "deferred": [], "rejected": [], "approved": true}`, log, proceed to Phase 5. Note this is the merged count from 3.0: a run with zero reviewer findings but a non-empty test-integrity set must NOT short-circuit.
 
 ##### 3.2 Launch triage agent
 
@@ -429,64 +474,7 @@ Log: "Phase 4: Review  -  raw={N1+N2} accepted={Na} deferred={Nd} rejected={Nr}
 
 #### Multi-Repo Mode
 
-Active when `state.projects[].length > 1`. The 3-reviewer/triage architecture is unchanged  -  what changes is the diff that reviewers see.
-
-**Combined diff assembly**  -  reviewers get **one combined diff** covering all repos, with explicit per-repo headers so they can flag cross-repo impact:
-
-```bash
-COMBINED_DIFF=$(mktemp)
-for proj in $(jq -r '.projects[] | "\(.name)\t\(.worktreePath)\t\(.baseBranch)"' "$STATE_FILE"); do
-  IFS=$'\t' read -r name wt base <<< "$proj"
-  ORIGIN=$(git -C "$wt" config --get remote.origin.url)
-  printf '\n=== repo: %s (origin: %s) ===\n' "$name" "$ORIGIN" >> "$COMBINED_DIFF"
-  printf 'Base: %s ... HEAD\n\n' "$base" >> "$COMBINED_DIFF"
-  git -C "$wt" diff "origin/$base...HEAD" >> "$COMBINED_DIFF"
-done
-```
-
-Same reviewer set (Fable-or-Opus / GPT-5.4 / Sonnet) receive `COMBINED_DIFF` with a multi-repo prefix in the system prompt:
-
-```
-This is a multi-repo task spanning {N} repos: {repo names}.
-Each repo's diff is prefixed with `=== repo: <name> ===`.
-A finding may span repos (e.g. "common adds API X, but uicomponents calls X with wrong type").
-For cross-repo findings, set `crossRepo: true` and list all impacted repos in `affectedRepos: []`.
-```
-
-**Schema extension for findings** (additive, single-repo `crossRepo` defaults to false):
-
-```json
-{
-  "severity": "blocking|important|suggestion",
-  "file": "uicomponents/Sources/Foo.swift",
-  "line": 42,
-  "issue": "...",
-  "fix": "...",
-  "crossRepo": false,
-  "affectedRepos": []
-}
-```
-
-`file` paths are repo-name-prefixed (`<repo-name>/<path-relative-to-repo>`) so triage and rework can resolve them back to the right worktree. The triage prompt receives `state.projects[]` so it can validate `affectedRepos` entries.
-
-**Triage cross-check**: Cross-repo findings are NEVER auto-rejected  -  the cross-cutting nature is exactly what reviewers are best at catching. Triage may still defer (out-of-scope) but rejection requires explicit reasoning.
-
-**Token-budget guard** (per `token-budget.json` Phase 4 allowance): if `COMBINED_DIFF` exceeds 80% of the budget, truncate the largest repo's diff with a footer header:
-```
-[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]
-```
-And log `review.diff_truncated repo=<name> bytes_dropped=<N>`. Triage receives the same truncated view + the truncation marker so it can flag suggestions to "review the full diff manually."
-
-**Deterministic gates per repo**: Step 1 gates (build/lint/test/secrets) run **per repo**  -  failure in any one repo blocks AI review for the whole task. Build queue lock applies as in Phase 3 (multi-repo doesn't change Xcode serialization).
-
-**Telemetry**: Per-repo build/test gate timings + a single combined review/triage call set:
-```bash
-pipeline/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=common status=pass duration_ms=$D
-pipeline/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=uicomponents status=pass duration_ms=$D
-pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.combined_diff repos=2 bytes=$BYTES truncated=false
-```
-
----
+**Only when `state.projects[].length > 1`.** Load `$HOME/.claude/multi-agent-refs/features/review-multi-repo.md` and follow it: per-repo diff scoping, how one merged finding set is attributed back to the repo that owns each file, and the per-repo `buildStatus` contract. A single-repo run skips this section entirely.
 
 ## Token telemetry  -  invoke after every LLM call
 

package/pipeline/schemas/prefs.schema.json

@@ -960,6 +960,12 @@
           "default": true,
           "description": "v8.3+ - Phase 4 Step 1.75 advisory diff risk scoring. When enabled, `pipeline/scripts/diff-risk-score.mjs` runs before reviewer dispatch and the top-N risk-ranked files are injected into each reviewer's prompt as a priority hint (security paths, public API surfaces, untested source changes, schema migrations). Heuristic, deterministic, no LLM cost. Default ON - the run is sub-second and never gates the pipeline. Flip to false to skip the script and the prompt injection entirely."
         },
+        "reviewScopeGate": {
+          "type": "boolean",
+          "default": true,
+          "description": "v12.8+ - Phase 4 Step 1.77 reviewer-scope gate. Decides the reviewer count from the deterministic diff-risk report via `pipeline/scripts/review-scope.mjs`: a diff under 20 lines of churn with max_score < 3.0 and no security_path / migration / public_api / no_test_change / test_lines_removed signal runs ONE reviewer instead of the full CLI-aware set (2 on Claude Code, 3 on Copilot CLI). No LLM. Fails safe in one direction only - any error, empty report or validator rejection resolves to the full set, because skipping a reviewer trades coverage for cost. Set false to force the full set on every diff.",
+          "$comment": "Shipped inert for a release: the script existed, was unit- and smoke-tested, and no phase doc referenced it, so every diff paid for the full reviewer set. Wired in Step 1.77; smoke-gate-wiring.sh keeps it reachable."
+        },
         "priorArtEnrichment": {
           "type": "object",
           "additionalProperties": false,

package/pipeline/scripts/_smoke-root.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# _smoke-root.sh  -  resolve the pipeline tree for a smoke that must run in BOTH
+# the repo checkout and an end-user install.
+#
+# Why this exists: the repo and an install have different shapes.
+#
+#   repo checkout          install (~/.claude or ~/.copilot)
+#   ------------------     --------------------------------
+#   pipeline/scripts/      scripts/
+#   pipeline/schemas/      schemas/
+#   pipeline/multi-agent-refs/  multi-agent-refs/
+#   pipeline/commands/     commands/
+#   package.json           (absent)
+#
+# A smoke that hardcodes `REPO_ROOT="$(dirname "$0")/../.."` and then reads
+# `$REPO_ROOT/pipeline/...` resolves to `$HOME/pipeline/...` once installed, so
+# every path check fails. Whoever ran it sees a red report and concludes the
+# install is broken. Source this file instead and read the MA_* variables.
+#
+# Usage (from any script in pipeline/scripts/):
+#   . "$(dirname "${BASH_SOURCE[0]}")/_smoke-root.sh"
+#   grep -q needle "$MA_REFS/phases/phase-4-review.md"
+#
+# Exports:
+#   MA_LAYOUT     "repo" | "install"
+#   MA_ROOT       repo root, or the install root (~/.claude)
+#   MA_SCRIPTS    directory holding this script
+#   MA_SCHEMAS    JSON schemas
+#   MA_REFS       multi-agent-refs
+#   MA_COMMANDS   slash-command tree
+#   MA_SKILLS     skills tree
+#
+# Every exported directory is verified to exist; a missing one is left empty so
+# the caller can skip that check rather than report a false failure.
+
+MA_SCRIPTS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# The repo is the only layout with pipeline/ beside package.json. Checking both
+# rules out an install that happens to sit next to an unrelated pipeline/ dir.
+_ma_candidate="$(cd "$MA_SCRIPTS/../.." && pwd)"
+if [ -f "$_ma_candidate/package.json" ] && [ -d "$_ma_candidate/pipeline" ]; then
+  MA_LAYOUT="repo"
+  MA_ROOT="$_ma_candidate"
+  _ma_base="$_ma_candidate/pipeline"
+else
+  MA_LAYOUT="install"
+  MA_ROOT="$(cd "$MA_SCRIPTS/.." && pwd)"
+  _ma_base="$MA_ROOT"
+fi
+unset _ma_candidate
+
+_ma_dir() { [ -d "$1" ] && echo "$1" || echo ""; }
+
+MA_SCHEMAS="$(_ma_dir "$_ma_base/schemas")"
+MA_REFS="$(_ma_dir "$_ma_base/multi-agent-refs")"
+MA_COMMANDS="$(_ma_dir "$_ma_base/commands")"
+MA_SKILLS="$(_ma_dir "$_ma_base/skills")"
+unset _ma_base
+
+export MA_LAYOUT MA_ROOT MA_SCRIPTS MA_SCHEMAS MA_REFS MA_COMMANDS MA_SKILLS