@mmerterden/multi-agent-pipeline 12.8.0 → 12.10.0

package/CHANGELOG.md

@@ -16,6 +16,140 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [12.10.0] - 2026-07-26
+
+Two pieces of abandoned residue, and a gate that had inverted.
+
+### `~/.multi-agent/` is pruned on install
+
+The "shared runtime" the Cursor / Antigravity / VS Code Copilot Chat adapters
+needed, so their emitted agents could reach the gate scripts by absolute path.
+Those adapters were deleted in v10.7.0 along with `installSharedRuntime`,
+`_base.mjs`, `rewriteScriptRefs` and `smoke-shared-runtime.sh` - but not the tree
+they had written. 222 files (174 scripts, 23 lib, 24 schemas) sat frozen at
+whatever the last adapter-era install produced.
+
+It is worse than dead weight because it is indistinguishable from a live install
+when you look at it: same directory names, same file names. Its
+`schemas/migrations/` is missing `prefs-2.3.0-to-2.4.0.mjs`, so reading it gives a
+migration chain three versions short and a reasonable conclusion that the chain
+itself is stale.
+
+`ABANDONED_TREES` now takes `root: "home"` entries for trees beside `~/.claude`
+rather than inside it, and 253 files (this plus the 31 in `~/.claude/eval`) are
+removed on the next install.
+
+### The live-prefs gate was rejecting the only correct state
+
+`smoke-schema-validation.sh` step 7 read:
+
+```bash
+if [ "$LVER" = "2.1.0" ]; then pass "live prefs already v2.1.0"
+elif ... else fail "live prefs has unknown schemaVersion: $LVER"
+```
+
+`migrate-prefs.mjs` `TARGET_VERSION` had since moved to 2.4.0, which inverted the
+gate: a prefs file left behind at 2.1.0 passed as "already current", and a file
+correctly migrated to 2.4.0 fell through to the else arm and FAILED as "unknown".
+The gate rejected the fully-migrated state it exists to encourage.
+
+It now reads the target from `migrate-prefs.mjs` and the accepted set from the
+schema's own `schemaVersion` enum, so it cannot disagree with either again, and a
+known-but-older version reports how far behind it is (`v2.1.0 -> v2.4.0`) instead
+of reading as current. This is a CONSUMER smoke (`/multi-agent:update` runs it), so
+it resolves both paths through `SMOKE_DIR`, which is `pipeline/scripts` in the repo
+and `~/.claude/scripts` in an install.
+
+### Dead-file sweep
+
+Swept refs, schemas, agents, libs and scripts for files nothing references. No
+orphans. The two candidates were both false positives from the sweep's own exclude
+flags: `design-check-config.schema.json` is referenced as the instance filename by
+the design-check command, and `count-lib.sh` is sourced by two siblings inside
+`pipeline/lib/`, which the sweep had excluded. Recorded here so the next sweep does
+not re-flag them.
+
+## [12.9.0] - 2026-07-26
+
+Context engineering follow-through, and a guard that was blocking safe commands.
+
+### Phase docs load their conditional sections on demand
+
+The two biggest phase docs carried the UNION of every branch, so a run paid for
+paths it never took. Both were over their own warn thresholds.
+
+- `phase-0-init.md` Step 1b (URL Enrichment, 9.6 kB) applies only when the task
+  input carries URLs. A bare Jira ID, a GitHub issue number or a free-text task
+  never needs it. Moved to `multi-agent-refs/features/url-enrichment.md` behind a
+  761-byte stub that states the run condition. Phase 0: 11701 -> 9469 tokens.
+- `phase-4-review.md` Multi-Repo Mode (3.0 kB) applies only when
+  `state.projects[].length > 1`. Moved to `features/review-multi-repo.md`.
+  Phase 4: 12070 -> 11048 tokens.
+
+Total phase-doc budget 50955 -> 48047 tokens, and both docs are now under warn
+rather than over. `smoke-url-enrichment.sh` follows the content to the ref and
+additionally asserts the phase doc still POINTS at it: a JIT reference nothing
+loads is worse than the inline copy it replaced.
+
+### The always-on description surface is budgeted
+
+Progressive disclosure defers reference BODIES, but a skill or command
+`description` sits in the host's listing for the whole session whether or not the
+skill is ever invoked. That is a second fixed load, it was LARGER than the
+budgeted one (76918 bytes across 236 descriptions), and nothing capped it.
+`smoke-context-budget.sh` now gates the total and the per-description average
+(the total can stay under budget while every description bloats), reports the
+whole pre-task cost as one number, and `test/context-budget-gate.test.mjs` pins
+all three ceilings as literals.
+
+### No prose block loads twice
+
+`smoke-context-duplication.sh` hashes normalised prose blocks across the files
+that can co-load in one run. 12.7.0 removed three sections the orchestrator had
+inlined from `multi-agent-refs/` - one already stale, naming a path the code no
+longer used - found by hand with nothing to prevent a recurrence.
+
+Scope mattered more than the algorithm. A first draft scanned the command and
+skill trees too and reported 10+ duplicates, every one legitimate: the
+`commands/multi-agent/X` vs `skills/shared/core/multi-agent-X` pairs are the
+cross-CLI parity contract, which `cross-cli-contract.md` REQUIRES byte-identical,
+and the mode commands repeat prose but only one loads per run. A gate that fires
+on deliberate design trains people to ignore it. Narrowed to the ref tree plus the
+orchestrator, it found one real case: three pickers each restating the Language
+matrix that `rules.md` already carries on every run - and the copies had already
+drifted, two saying "Commit/PR/Jira/Wiki" and one "Commit/PR/Jira". Replaced with
+a one-line pointer, 678 bytes reclaimed.
+
+### agent-guard stopped blocking safe pushes
+
+The force-push detector ended in `-\S*f\S*`, matching any flag containing an `f`:
+
+```
+git pull --ff-only && git push origin main    -> BLOCKED
+git push --follow-tags origin main             -> BLOCKED
+```
+
+Neither rewrites history, and `--follow-tags` is the normal way to push a release
+tag with its commit, so the guard blocked a routine release step. False positives
+are not free: people learn to route around the hook, which loses more safety than
+the guard buys. The short-flag arm is now `-[A-Za-z]*f[A-Za-z]*` (a single dash
+followed only by letters, so `-f`/`-fq` still match and no `--long-flag` can), and
+force detection is scoped to the `git push` segment so a neighbouring command's
+`-f` no longer implicates it (`rm -f stale.log && git push origin main`).
+
+Fail-closed behaviour is unchanged and now asserted: an untokenizable command, and
+a bare force-push whose target branch cannot be determined, still block.
+`test/agent-guard.test.mjs` covers 30 cases across both directions.
+
+### Also
+
+- Trees an older installer created and no current one manages are pruned on
+  install (`pruneAbandonedTrees`). `~/.claude/eval/` held 31 files that no
+  installer wrote and no uninstall removed - wipe-before-copy only protects trees
+  still being written, so an abandoned one persists forever.
+- shellcheck in CI scans `git ls-files '*.sh'` instead of `find pipeline`, so a
+  shell script added outside `pipeline/` is no longer silently unchecked.
+
 ## [12.8.0] - 2026-07-26
 
 12.7.0 fixed nine gates that reported success without checking anything. This

package/install/_common.mjs

@@ -252,25 +252,46 @@ export function pruneLegacyMultiAgentSkills(skillsDir) {
  * neither did uninstall - 31 stale files sat there with nothing left that could
  * ever read or remove them.
  *
- * @type {ReadonlyArray<{dir: string, reason: string}>}
+ * `~/.multi-agent/` is the larger case: the "shared runtime" the Cursor /
+ * Antigravity / VS Code Copilot Chat adapters needed, so their emitted agents
+ * could reach the gate scripts by absolute path. Those adapters were deleted in
+ * v10.7.0 along with `installSharedRuntime`, `_base.mjs`, `rewriteScriptRefs` and
+ * `smoke-shared-runtime.sh` - but not the tree they wrote. 221 files (174 scripts,
+ * 23 lib, 24 schemas) frozen at whatever the last adapter-era install produced,
+ * including a migrations directory missing `prefs-2.3.0-to-2.4.0.mjs`. Browsing it
+ * looks exactly like browsing a current install, which is how it comes to be
+ * mistaken for one.
+ *
+ * `root: "home"` entries sit beside `~/.claude`, not inside it.
+ *
+ * @type {ReadonlyArray<{dir: string, root?: "claude"|"home", reason: string}>}
  */
 export const ABANDONED_TREES = Object.freeze([
   {
     dir: "eval",
     reason: "eval corpora; the harnesses that read them are maintainer-only and no longer ship",
   },
+  {
+    dir: ".multi-agent",
+    root: "home",
+    reason:
+      "shared runtime for the Cursor / Antigravity / Copilot Chat adapters, all deleted in v10.7.0",
+  },
 ]);
 
 /**
- * Remove trees an older install left behind under `root`.
+ * Remove trees an older install left behind.
  *
- * @param {string} root e.g. `$HOME/.claude`
+ * @param {string} claudeDir e.g. `$HOME/.claude`
+ * @param {string} [home] `$HOME`, for entries marked `root: "home"`. Defaults to
+ *   the parent of `claudeDir`, which is the layout every installer uses.
  * @returns {number} directories removed
  */
-export function pruneAbandonedTrees(root) {
+export function pruneAbandonedTrees(claudeDir, home = dirname(claudeDir)) {
   let removed = 0;
-  for (const { dir, reason } of ABANDONED_TREES) {
-    const target = join(root, dir);
+  for (const { dir, root, reason } of ABANDONED_TREES) {
+    const base = root === "home" ? home : claudeDir;
+    const target = join(base, dir);
     if (!existsSync(target)) continue;
     if (dryRun) {
       console.log(`    [dry-run] would remove abandoned tree ${target} (${reason})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.8.0",
+  "version": "12.10.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot 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/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/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
 

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

@@ -474,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/scripts/agent-guard.py

@@ -25,7 +25,50 @@ ATTRIBUTION = re.compile(
     r"|claude code <",
     re.IGNORECASE,
 )
-FORCE = re.compile(r"(^|\s)(--force(\b|$)|--force-with-lease|-\S*f\S*)(\s|$)")
+# Force flags, and ONLY force flags.
+#
+# The previous pattern ended in `-\S*f\S*`, which matches any flag containing an
+# `f` anywhere - so it fired on `--ff-only`, `--follow-tags`, and `--file=...`.
+# Two real false positives followed:
+#
+#   git pull --ff-only && git push origin main   -> BLOCKED
+#   git push --follow-tags origin main           -> BLOCKED
+#
+# Neither rewrites history. `--follow-tags` is the normal way to push a release
+# tag with its commit, so the guard blocked a routine release step. Being
+# fail-closed is right for a data-loss guard, but only against the thing it
+# guards; blocking safe commands trains people to work around the hook, which
+# costs more safety than it buys.
+#
+# The short-flag arm is now `-[A-Za-z]*f[A-Za-z]*`: a SINGLE dash followed only by
+# letters, so it still catches `-f`, `-fq`, `-qf`, and never a `--long-flag`
+# (whose second character is `-`, not a letter).
+FORCE = re.compile(
+    r"(^|\s)("
+    r"--force(-with-lease|-if-includes)?(=\S+)?"  # --force, --force-with-lease[=ref], --force-if-includes
+    r"|-[A-Za-z]*f[A-Za-z]*"  # -f and short clusters containing f
+    r")(\s|$)"
+)
+
+
+# Shell separators that end one command and start the next. Used to attribute a
+# flag to the command it actually belongs to.
+SEPARATORS = re.compile(r"&&|\|\||;|\||\n")
+
+
+def push_segments(cmd: str) -> list:
+    """The sub-commands that invoke `git push`.
+
+    A flag must be attributed to its own command. Scanning the whole string made
+    `git commit -f ... && git push origin main` read as a force-push, because the
+    `-f` belonged to the commit. Splitting on shell separators first keeps each
+    command's flags with that command.
+
+    Deliberately coarse: a separator inside a quoted string splits too, which can
+    only ever produce MORE segments to inspect, never fewer - the safe direction
+    for a guard.
+    """
+    return [seg for seg in SEPARATORS.split(cmd) if re.search(r"git\s+push", seg.lower())]
 
 
 def decide(cmd: str) -> str:
@@ -35,8 +78,19 @@ def decide(cmd: str) -> str:
     if re.search(r"git\s+commit", low) and ATTRIBUTION.search(cmd):
         return "BLOCK_ATTRIB"
 
-    # Rule 2: force-push to a protected branch.
-    if re.search(r"git\s+push", low) and FORCE.search(cmd):
+    # Rule 2: force-push to a protected branch. Evaluate each push segment on its
+    # own so a neighbouring command's flags cannot implicate it.
+    for segment in push_segments(cmd):
+        verdict = _decide_push(segment)
+        if verdict != "OK":
+            return verdict
+
+    return "OK"
+
+
+def _decide_push(cmd: str) -> str:
+    """Verdict for a single `git push ...` command."""
+    if FORCE.search(cmd):
         try:
             toks = shlex.split(cmd)
         except Exception:

package/pipeline/scripts/smoke-schema-validation.sh

@@ -174,14 +174,40 @@ echo ""
 echo "→ 7. Live preferences (if exists)  -  post-migration check"
 if [ -f "$LIVE_PREFS" ]; then
   LVER=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$LIVE_PREFS','utf8')).schemaVersion || 'none')" 2>/dev/null)
-  if [ "$LVER" = "2.1.0" ]; then
-    pass "live prefs already v2.1.0"
-  elif [ "$LVER" = "2.0.0" ] || [ "$LVER" = "none" ]; then
-    echo "  ⓘ live prefs still $LVER  -  migration pending (Aşama 1.6)"
-    # Not a fail; migration is its own step
-    pass "live prefs present, needs migration (schemaVersion: $LVER)"
+
+  # The target is read from migrate-prefs.mjs, never hardcoded here.
+  #
+  # This block used to say `if [ "$LVER" = "2.1.0" ]; then pass "already v2.1.0"`
+  # with everything else falling through to `fail "unknown schemaVersion"`. The
+  # migration target had since moved to 2.4.0, which inverted the gate: a prefs
+  # file left behind at 2.1.0 reported PASS as "already current", while a file
+  # correctly migrated to 2.4.0 hit the else arm and FAILED as "unknown". The
+  # gate was rejecting the only fully-migrated state it exists to encourage.
+  #
+  # Reading the target from the migrator, and the accepted set from the schema
+  # enum, means this can never disagree with them again.
+  MIGRATOR="$SMOKE_DIR/migrate-prefs.mjs"
+  TARGET=$(grep -oE 'TARGET_VERSION = "[0-9.]+"' "$MIGRATOR" 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
+  KNOWN=$(node -e "
+    const s = require('$PREFS_SCHEMA');
+    process.stdout.write((s.properties.schemaVersion.enum || []).join(' '));
+  " 2>/dev/null)
+
+  if [ -z "$TARGET" ]; then
+    fail "cannot read TARGET_VERSION from migrate-prefs.mjs - the check has no reference point"
+  elif [ "$LVER" = "$TARGET" ]; then
+    pass "live prefs at the migration target (v$TARGET)"
+  elif [ "$LVER" = "none" ]; then
+    echo "  ⓘ live prefs carries no schemaVersion  -  migration pending"
+    pass "live prefs present, needs migration (schemaVersion: none)"
+  elif printf '%s\n' $KNOWN | grep -qxF "$LVER"; then
+    # A known-but-older version is legitimately "migration pending", not a
+    # failure: migration is its own install step. Say how far behind it is, so a
+    # file sitting three versions back is visible instead of reading as current.
+    echo "  ⓘ live prefs at v$LVER, target v$TARGET  -  migration pending"
+    pass "live prefs present, needs migration (v$LVER -> v$TARGET)"
   else
-    fail "live prefs has unknown schemaVersion: $LVER"
+    fail "live prefs has a schemaVersion the schema does not know: $LVER (known: $KNOWN)"
   fi
 else
   echo "  ⓘ no live prefs at $LIVE_PREFS  -  ok for fresh install"