@mmerterden/multi-agent-pipeline 17.1.0 → 17.4.0

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

@@ -1,5 +1,14 @@
 # Step 1b  -  URL Enrichment (Phase 0)
 
+<!-- toc -->
+- [Step 1b.0  -  Extract context links (always runs)](#step-1b0---extract-context-links-always-runs)
+- [Step 1b.1  -  Firebase Crashlytics deep fetch (runs when `type == "crashlytics"` present in `state.contextLinks[]`)](#step-1b1---firebase-crashlytics-deep-fetch-runs-when-type-crashlytics-present-in-statecontextlinks)
+- [Step 1b.2  -  Fortify SSC deep fetch (runs when `type == "fortify"` present in `state.contextLinks[]`)](#step-1b2---fortify-ssc-deep-fetch-runs-when-type-fortify-present-in-statecontextlinks)
+- [Step 1b.3  -  Graylog deep fetch (runs when `type == "graylog"` present in `state.contextLinks[]`)](#step-1b3---graylog-deep-fetch-runs-when-type-graylog-present-in-statecontextlinks)
+- [Step 1b.3b  -  Document fetch (runs when `type == "document"` present)](#step-1b3b---document-fetch-runs-when-type-document-present)
+- [Step 1b.4  -  Other link types (catalogued only at Phase 0; fetched at Phase 1)](#step-1b4---other-link-types-catalogued-only-at-phase-0-fetched-at-phase-1)
+<!-- /toc -->
+
 > 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

package/pipeline/multi-agent-refs/features/visual-evidence.md

@@ -1,5 +1,17 @@
 # Visual evidence  -  before/after screenshots and the UI flow video
 
+<!-- toc -->
+- [1. When it is required](#1-when-it-is-required)
+- [2. Before  -  the reporter's screenshot, or nothing](#2-before---the-reporters-screenshot-or-nothing)
+- [3. After  -  Phase 3, not Phase 5](#3-after---phase-3-not-phase-5)
+- [4. Video  -  the recording rides on a test run](#4-video---the-recording-rides-on-a-test-run)
+- [5. Size, and what happens when it does not fit](#5-size-and-what-happens-when-it-does-not-fit)
+- [5b. Where the artefacts live  -  the host](#5b-where-the-artefacts-live---the-host)
+- [6. Rendering](#6-rendering)
+- [7. Blocker](#7-blocker)
+- [8. State](#8-state)
+<!-- /toc -->
+
 A UI fix that reads as three changed files in a diff is not reviewable. The
 reviewer cannot see what was wrong, and the tester cannot see what to look for.
 This contract makes the pipeline carry the picture: the state the reporter saw,
@@ -222,6 +234,36 @@ capture of a static screen.
 `visualEvidence.enabled` turns the whole feature off - capture, upload, both
 render sections and the Phase 6 blocker with it.
 
+### 4.6 Web - the recorder IS the runner
+
+Web is a real evidence platform: the schema has it in `visualEvidence.platform`,
+the probe opens tier 1 and tier 2 for it, and `run-ui-tests.sh` has a web arm.
+What it does NOT share with iOS and Android is the recording model, and forcing
+it to would record the same run twice - Playwright and Cypress write the video
+themselves.
+
+| Step | iOS / Android | Web |
+|---|---|---|
+| `after` | screenshot the booted device | drive a browser at a URL |
+| the URL | not needed, a simulator already shows something | `--url`, else `prefs.global.visualEvidence.webBaseUrl`, else a gap with that reason |
+| `video start` | spawn a recorder, hold its pid | write a marker with the current time; spawn nothing |
+| `video stop` | kill the recorder, pull the file | harvest the newest video under `test-results/` or `cypress/videos/` written AFTER the marker |
+| container | mp4 already | webm re-encoded to h264, for the same reason the iOS arm re-encodes: that is what the Jira preview and the PR body play |
+
+The marker is the part that matters and the part that is easy to leave out. Without
+a timestamp to compare against, `stop` harvests whatever video is lying around -
+and a video from yesterday's run attached as today's evidence is worse than no
+video, because an artefact that is present does not get re-checked.
+
+Two honest gaps, both exit 4 with a reason rather than a failure: no address to
+point at, and a project whose runner config does not record video at all. Neither
+is a phase failure; both are recorded and shown.
+
+Every browser call goes through `npx --no-install`, never a bare `npx`. A bare one
+DOWNLOADS the browser stack, which turns "this project has no browser tooling"
+into a silent network fetch. `run-ui-tests.sh` carries the same rule for the same
+reason, and it is the line that keeps the pipeline's own dependency list empty.
+
 ## 5. Size, and what happens when it does not fit
 
 Jira's attachment ceiling is an instance setting, so it is a preference:

package/pipeline/multi-agent-refs/generate-issue.md

@@ -1,5 +1,12 @@
 # Generate Issue  -  Shared Flow (generate)
 
+<!-- toc -->
+- [Hard rules (must not regress)](#hard-rules-must-not-regress)
+- [Standard templates](#standard-templates)
+- [Flow](#flow)
+- [Error paths](#error-paths)
+<!-- /toc -->
+
 > **TLDR**  -  Shared 12-step flow for `/multi-agent:create-jira`. Asks the issue type (Task / Bug / Story), mines the target project's existing same-type issues to learn team conventions, detects the active sprint, drafts a standards-compliant issue from a fixed standard template with auto-sizing sections, asks the user about every genuinely unknown field, renders a full preview, and creates the Jira issue only after explicit approval. Creates exactly one Jira issue per run  -  no branches, no commits, no worktrees.
 
 Consumed by `create-jira/SKILL.md`. This ref is never invoked directly.

package/pipeline/multi-agent-refs/issue-jira-triad.md

@@ -1,5 +1,14 @@
 # Issue → Jira → Wiki Triad
 
+<!-- toc -->
+- [The triad at a glance](#the-triad-at-a-glance)
+- [Phase 0 auto-create policy](#phase-0-auto-create-policy)
+- [Phase 7 wiki → Jira comment](#phase-7-wiki-jira-comment)
+- [Autopilot behaviour](#autopilot-behaviour)
+- [Preferences involved](#preferences-involved)
+- [Cross-CLI parity](#cross-cli-parity)
+<!-- /toc -->
+
 > **TLDR**  -  When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 7 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
 
 This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.

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

@@ -1,5 +1,11 @@
 ## Project Knowledge Base
 
+<!-- toc -->
+- [Project Knowledge Base](#project-knowledge-base)
+- [Retrieval order, and what each layer costs](#retrieval-order-and-what-each-layer-costs)
+- [Skill Injection Strategy](#skill-injection-strategy)
+<!-- /toc -->
+
 An incrementally growing knowledge system for each project, enabling knowledge transfer across sessions.
 
 ### Directory Structure

package/pipeline/multi-agent-refs/multi-repo-integration-build.md

@@ -1,5 +1,18 @@
 # Multi-Repo Integration Build  -  Learn Once, Auto-Apply
 
+<!-- toc -->
+- [Why this exists](#why-this-exists)
+- [When this rule fires](#when-this-rule-fires)
+- [Learn-once prompt (first encounter of a combo)](#learn-once-prompt-first-encounter-of-a-combo)
+- [Auto-run steps (when host is learned)](#auto-run-steps-when-host-is-learned)
+- [Error evaluation contract](#error-evaluation-contract)
+- [Autopilot behavior](#autopilot-behavior)
+- [Phase 7 knowledge capture](#phase-7-knowledge-capture)
+- [Generic rule (for copilot-instructions.md)](#generic-rule-for-copilot-instructionsmd)
+- [Schema](#schema)
+- [Smoke coverage](#smoke-coverage)
+<!-- /toc -->
+
 > **TLDR**  -  When a task touches ≥2 repos that have a producer→consumer dependency (e.g. shared codegen library + consuming UI library), the pipeline MUST build the **host project** that integrates them before commit/PR. Codegen mismatches (nested vs flat keys, missing entries, overwritten files) only surface when the full dependency chain builds together. Building repos in isolation gives false confidence.
 >
 > The pipeline **learns** the host per repo-combo once, persists to `prefs.global.multiRepoIntegrationHosts`, and auto-applies on subsequent runs.

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

@@ -8,6 +8,13 @@
 
 ## Autopilot Mode
 
+<!-- toc -->
+- [Autopilot Mode](#autopilot-mode)
+- [Pipeline depth (Full / Short)](#pipeline-depth-full-short)
+- [Analysis Mode (`/multi-agent:analysis`)](#analysis-mode-multi-agentanalysis)
+- [Local Mode (`--local`)](#local-mode---local)
+<!-- /toc -->
+
 Autopilot mode skips interactive confirmations and runs the pipeline end-to-end autonomously.
 
 **Activation**: Add `autopilot` flag to any pipeline command:

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

@@ -8,6 +8,15 @@
 
 ## Task ID System
 
+<!-- toc -->
+- [Task ID System](#task-id-system)
+- [Kill Logic](#kill-logic)
+- [Clear Logs](#clear-logs)
+- [Purge (Full Reset)](#purge-full-reset)
+- [Resume Logic](#resume-logic)
+- [Phase Pipeline](#phase-pipeline)
+<!-- /toc -->
+
 Every task gets an auto-incremented short ID. Counter stored at `$HOME/.claude/logs/multi-agent/{project}/.counter` (persists across sessions).
 
 ```

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

@@ -606,7 +606,7 @@ if [ -n "$EVIDENCE_PLATFORM" ]; then
 fi
 ```
 
-Empty is an outcome, not a failure: no simulator on web or backend, so the probe does not run and `evidenceCapability.skippedReason` says so. No `--changed` yet, by the same token.
+Empty is an outcome, not a failure: backend has no device, so the probe does not run and `evidenceCapability.skippedReason` says so. Web does: the browser the runner drives is the device (4.6). No `--changed` yet, by the same token.
 
 One run, both forms: stdout is `EVIDENCE_*` (shell-quoted, so the eval is safe), and the same measurement lands as JSON.
 

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

@@ -240,8 +240,7 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.criteria \
 Output conforms to `$HOME/.claude/schemas/criteria-manifest.schema.json`. The four parts that matter downstream:
 
 - **`selectedRules[]` is the denominator.** Rule IDs from every registry whose declared `scope` matches the diff, persisted BEFORE the reviewers run so the set cannot be renegotiated after one has seen the diff. That is what makes "applied completely" answerable rather than "looks fine": a reviewer finding nothing must still return a verdict per ID. Discovery is declared via `standards-registry:` frontmatter, so no stack-specific skill is named here.
-- **`coverage.declaredGaps[]` + `droppedReasons`.** An uncovered language, and every out-of-scope rule, is reported with a reason. "No rule applied", "every rule passed" and "the rule set was narrowed" must never render the same.
-- **`ledger`.** `state.telemetry.skillCalls[]` corroborates only; `ledger.source` defaults to `derived` and coverage is never computed from self-report. A declared skill the resolver cannot bind is flagged.
+- **`coverage.declaredGaps[]`, `droppedReasons`, `ledger`.** Every gap, dropped rule and unbindable declared skill is reported with a reason; coverage is never computed from self-report. Rationale: the contract above.
 - **`findings[]`.** Reviewer-shaped, merging at Step 3.0 alongside test-integrity: expired / unexplained / unknown-ID exception markers, plus any registry whose delegated linter is not wired here (those rules are unverified, so reporting no violations reports that nothing was measured).
 
 **Any non-zero exit halts** (1 = setup error incl. a bad `--skills-root`; 2 = no root resolved, unparseable registry, or a declared path escaping its skill dir): continuing would drop a rule set from the denominator, and since the reviewer validator skips the checklist when zero rules were selected, the run would report clean over criteria never loaded. A coverage gap halts only under `prefs.global.skillConformance.blockOnCoverageGap`. No opt-out for the stage or the exception-expiry check, on the same grounds as Step 1.76.
@@ -266,13 +265,25 @@ Visual-fidelity mismatches against the captured screenshot are BLOCKING findings
 
 When `state.figmaAccess.tier === 3` (user-attached screenshot, no Code Connect snippet), the reviewer additionally sets `findings[i].severity = "blocking"` and `findings[i].tag = "review_blocking_tier3"` on every UI atom that lacks a confirmed canonical-component mapping. The triage step preserves these findings unless the user has explicitly cleared the open question.
 
+#### Step 1.85  -  Review file set (the denominator, required)
+
+Decides what the reviewers read before the cap decides what fits: the cap truncates the largest files first, so a lockfile survives while real code is cut. Zero LLM. Full contract: `$HOME/.claude/multi-agent-refs/features/review-file-set.md`.
+
+```bash
+git -C "$WORKTREE" diff --name-only "$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/review-file-filter.mjs \
+  > "$WORKTREE/.pipeline/review-files.json"
+```
+
+`reviewed[]` is the denominator, fixed here for the same reason `selectedRules[]` is. `excluded[]` reaches the run report with its reason and the glob that matched. Exit 2 means the pattern list is unreadable and everything is reviewed: continue, logging `review.file_filter_failed`.
+
 #### Step 1.9  -  Context economy (cache prefix + diff cap)
 
 Phase 4 sends the same diff to every reviewer and then to triage, so the diff is the dominant token cost. Two measures keep it bounded:
 
-**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, the `${CRITERIA}` block from Step 1.78, the Phase 1 analysis summary, the Phase 2 plan  -  is a byte-identical leading block across all dispatches in this iteration. Only the per-reviewer focus + skill line varies, and it goes AFTER the shared block. `${CRITERIA}` goes in the prefix, identical for every reviewer: subsetting it per reviewer would invalidate the prefix for the whole panel and re-bill the largest block in the phase. Per-reviewer emphasis stays a one-line pointer in the suffix. When the host supports prompt caching, the 2nd/3rd reviewer and the triage call then read that prefix at the discounted cache-read rate instead of re-billing it as fresh input. Forward the host-reported cache-read count as `tokens_cached` per the Token telemetry contract so the saving lands in the cost ledger. The `<scope-self-check>` block and, from iteration 2, the `<previous-round-findings>` block (Step 2.1) close the shared block, after the plan and before the per-reviewer suffix.
+**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, the `${CRITERIA}` block from Step 1.78, the `${REVIEW_FILES}` list from Step 1.85, the Phase 1 analysis summary, the Phase 2 plan  -  is a byte-identical leading block across all dispatches in this iteration. Only the per-reviewer focus + skill line varies, and it goes AFTER the shared block. `${CRITERIA}` goes in the prefix, identical for every reviewer: subsetting it per reviewer would invalidate the prefix for the whole panel and re-bill the largest block in the phase. Per-reviewer emphasis stays a one-line pointer in the suffix. When the host supports prompt caching, the 2nd/3rd reviewer and the triage call then read that prefix at the discounted cache-read rate instead of re-billing it as fresh input. Forward the host-reported cache-read count as `tokens_cached` per the Token telemetry contract so the saving lands in the cost ledger. The `<scope-self-check>` block and, from iteration 2, the `<previous-round-findings>` block (Step 2.1) close the shared block, after the plan and before the per-reviewer suffix.
 
-**Single-repo diff cap.** If the diff exceeds the Phase 4 token allowance (`token-budget.json`), truncate the largest files and append a footer `[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]`, writing the full diff to that path. Reviewers and triage receive the same capped view + the marker so they can flag "review the full diff manually." Log `review.diff_truncated bytes_dropped=<N>`. (Multi-repo already caps the combined diff at 80% of budget; this is the single-repo equivalent.)
+**Single-repo diff cap.** Applied to the Step 1.85 `reviewed[]` set only. If it exceeds the Phase 4 token allowance (`token-budget.json`), truncate the largest files and append a footer `[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]`, writing the full diff to that path. Reviewers and triage receive the same capped view + the marker so they can flag "review the full diff manually." Log `review.diff_truncated bytes_dropped=<N>`. (Multi-repo already caps the combined diff at 80% of budget; this is the single-repo equivalent.)
 
 #### Step 2  -  Parallel AI Review (CLI-aware reviewer set)
 
@@ -291,9 +302,8 @@ Reviewer count per host: **Claude Code 3, Copilot CLI 3, Codex CLI 3**  -  **2**
 
 #### Codex CLI  -  two constraints that fail silently
 
-Both were measured against Codex 0.145, not inferred, and both produce a review that
-looks like it ran. The full statement lives in the managed block at `~/.codex/AGENTS.md`
-(always loaded on that host, so it is not restated here):
+Both measured against Codex 0.145, both produce a review that looks like it ran. Full
+statement: the managed block in `~/.codex/AGENTS.md`, always loaded on that host.
 
 1. **`fork_turns: "none"` on every `spawn_agent` that sets `model` or
    `reasoning_effort`** - a full-history fork discards the override and collapses the
@@ -304,15 +314,10 @@ looks like it ran. The full statement lives in the managed block at `~/.codex/AG
 Sub-agent delegation itself is authorized by that same managed block; without it Phase 4
 degrades to a single in-thread review.
 
-**Single-vendor caveat.** Every Codex reviewer is an OpenAI model, and every Claude
-Code reviewer is an Anthropic model, so the cross-vendor disagreement that Copilot CLI
-gets for free (GPT-5.4 beside two Claude models) is absent on both. The diversity budget
-shifts to model generation, reasoning effort and persona focus: on Codex Reviewer 1 runs
-`xhigh` on security and architecture, Reviewer 2 runs a different model family member
-on edge cases, Reviewer 3 runs `medium` on quality; on Claude Code the three slots are
-three different Claude tiers. Treat consensus among a single-vendor panel as weaker
-evidence than the same consensus on Copilot CLI, and say so in the triage note when all
-three agree on a borderline finding.
+**Single-vendor caveat.** Claude Code and Codex both run a one-vendor panel, so their
+consensus is weaker evidence than Copilot CLI's; say so in the triage note on a
+borderline finding. Where the diversity budget goes instead:
+`cross-cli-contract.md`, "Panel diversity per host".
 
 Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Architecture, Quality, Performance) and output contract. The orchestrator overrides only the model and the stack-specific skill per-reviewer  -  no prompt duplication.
 
@@ -331,7 +336,7 @@ Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Archit
 
 ##### 2.1 Previous-round findings (iteration >= 2) and 2.2 scope self-check (every iteration)
 
-A reviewer has no memory of the round before, so it rediscovers last round's findings in new words. From iteration 2, render the previous round's accepted blocking/important findings (`.pipeline/triage-round-$((ITERATION-1)).json`, max 40) into a `<previous-round-findings>` block at the end of the shared prefix: a still-present issue is reported with the SAME fingerprint and the current line, a fixed one is omitted, anything new leaves `fingerprint` unset. Every iteration also renders `.pipeline/scope-check.json` (Phase 3 Step 3.7) plus `scope-check-gate.mjs --advisory` output as `<scope-self-check>`: file reasons, unjustified files, and `notDone[]` (never re-raised as findings); a missing record logs `review.scope_check=missing`. Block text and recipes: `$HOME/.claude/multi-agent-refs/features/review-delta.md`.
+From iteration 2, render the previous round's accepted blocking/important findings (`.pipeline/triage-round-$((ITERATION-1)).json`, max 40) into a `<previous-round-findings>` block at the end of the shared prefix. Every iteration also renders `.pipeline/scope-check.json` (Phase 3 Step 3.7) plus `scope-check-gate.mjs --advisory` output as `<scope-self-check>`: file reasons, unjustified files, and `notDone[]` (never re-raised as findings); a missing record logs `review.scope_check=missing`. Block text and recipes: `$HOME/.claude/multi-agent-refs/features/review-delta.md`.
 
 #### Step 2.8  -  Visual conformance gate (component / screen work only)
 
@@ -350,11 +355,7 @@ disk with `Code Connect: Not published` in Figma means the binding does not exis
 anyone but the author. Assert the publish step ran; an unpublished binding is a
 blocking finding.
 
-Why this is a gate and not advice: `design-check` existed as a command for a while
-with **no phase invoking it**, so the only thing standing between a build and visual
-drift was the user opening the app and looking. On one run that produced 16pt padding
-where the frame said `Spacing/12`, and a full sheet rebuild afterwards. A reviewer
-reading a diff cannot see spacing; something has to compare against the design.
+Why this is a gate and not advice: `design-conformance.md`, "Why this runs as a gate".
 
 Skip only when the diff has no UI change. Record the outcome in
 `consensus.visualConformance` so Phase 7 reports whether it ran.
@@ -374,10 +375,11 @@ Step 2 produces N reviewer-output objects (one per dispatched reviewer), each co
 ```json
 {"findings":[{"severity":"blocking|important|suggestion","file":"...","line":N,"issue":"...","fix":"...","ruleId":"SEC-01","criteriaSource":"ios-coding-standard"}],
  "conformance":[{"ruleId":"SEC-01","verdict":"conformant|violated|not-applicable","file":"...","line":N,"reason":"..."}],
+ "fileCoverage":[{"path":"src/App.swift","verdict":"reviewed|skipped","reason":"..."}],
  "approved":true|false}
 ```
 
-`ruleId` + `criteriaSource` appear on a finding that cites a rule from `${CRITERIA}`. `conformance` is required whenever Step 1.78 selected at least one rule, with exactly one row per selected ID and none outside the set.
+`ruleId` + `criteriaSource` appear on a finding that cites a rule from `${CRITERIA}`. `conformance` is required whenever Step 1.78 selected at least one rule, and `fileCoverage` whenever Step 1.85 left at least one file in `reviewed[]`: one row per ID, one row per path, none outside either set.
 
 **Required: validator gate (deterministic)  -  run immediately after each reviewer returns, before merging findings.** Persist each reviewer's output and validate the file  -  the validator's exit code decides, not the LLM turn:
 
@@ -386,9 +388,15 @@ REVIEWER_FILE="$WORKTREE/.pipeline/reviewer-$N.json"
 printf '%s' "$REVIEWER_JSON" > "$REVIEWER_FILE"
 node $HOME/.claude/scripts/validate-reviewer.mjs "$REVIEWER_FILE" \
   --criteria "$WORKTREE/.pipeline/criteria-manifest.json" \
+  --coverage "$WORKTREE/.pipeline/review-files.json" \
+  && node $HOME/.claude/scripts/verify-citations.mjs "$REVIEWER_FILE" --repo "$WORKTREE" --worktree \
   && node $HOME/.claude/scripts/finding-fingerprint.mjs annotate --in-place "$REVIEWER_FILE"
 ```
 
+`verify-citations.mjs` resolves each finding's `file:line` against the checkout,
+not a commit: a round's fix is uncommitted, and HEAD would call it invented.
+Exit 1 takes the single rework below; exit 2 means not a repository.
+
 Progress line: `    → checking validator validate-reviewer ({reviewer})`
 
 `finding-fingerprint.mjs` stamps each finding with its cross-round id once the validator passes; an echoed one is kept, and anonymization leaves it intact.

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

@@ -1,5 +1,16 @@
 # Multi-Agent Pipeline  -  Phase Reference
 
+<!-- toc -->
+- [Phase Files](#phase-files)
+- [Pipeline Flow](#pipeline-flow)
+- [Phase entry  -  pending steer (every phase, every mode)](#phase-entry---pending-steer-every-phase-every-mode)
+- [Visual Phase Tracker](#visual-phase-tracker)
+- [Preferences File](#preferences-file)
+- [Host Configuration](#host-configuration)
+- [Token Budget](#token-budget)
+- [SubPhase Convention](#subphase-convention)
+<!-- /toc -->
+
 ## Phase Files
 
 | Phase                             | File                                                                 |

package/pipeline/multi-agent-refs/picker-contract.md

@@ -1,5 +1,17 @@
 # Picker Contract (cross-platform single-choice abstraction)
 
+<!-- toc -->
+- [The abstract primitive](#the-abstract-primitive)
+- [Step narration (breadcrumb)](#step-narration-breadcrumb)
+- [Per-platform rendering (degradation ladder)](#per-platform-rendering-degradation-ladder)
+- [Universal fallback: `pipeline/lib/ask-choice.sh`](#universal-fallback-pipelinelibask-choicesh)
+- [Localized labels: what the caller owns](#localized-labels-what-the-caller-owns)
+- [Order: project, then repo, then branch](#order-project-then-repo-then-branch)
+- [A single candidate is still a question](#a-single-candidate-is-still-a-question)
+- [Autopilot / non-interactive contract](#autopilot-non-interactive-contract)
+- [Deterministic gates note](#deterministic-gates-note)
+<!-- /toc -->
+
 > Native `AskUserQuestion` is a Claude-Code primitive; Copilot CLI has no
 > agent-invokable choice picker. This contract defines ONE abstract "ask the
 > user to choose" primitive that each supported CLI renders to the best

package/pipeline/multi-agent-refs/platform-parity.md

@@ -4,6 +4,16 @@ description: "Internal  -  cross-platform parity cross-check for Phase 4 and /mu
 
 # Platform parity  -  compare the change against the other platform's repo
 
+<!-- toc -->
+- [When it runs](#when-it-runs)
+- [Read-only, without exception](#read-only-without-exception)
+- [Locating the counterpart, deterministically](#locating-the-counterpart-deterministically)
+- [What is compared](#what-is-compared)
+- [What a finding may not claim](#what-a-finding-may-not-claim)
+- [Output](#output)
+- [Severity](#severity)
+<!-- /toc -->
+
 A feature that exists on iOS and Android is written twice, and the two copies
 drift. The drift is invisible from inside one repo: the iOS diff is
 self-consistent, the tests pass, and nobody notices that the Android screen

package/pipeline/multi-agent-refs/progress-contract.md

@@ -1,5 +1,15 @@
 # Progress Line Contract
 
+<!-- toc -->
+- [Why](#why)
+- [Line shape](#line-shape)
+- [When to emit](#when-to-emit)
+- [Verbosity](#verbosity)
+- [Telemetry](#telemetry)
+- [Phase adoption marker](#phase-adoption-marker)
+- [Cross-CLI parity](#cross-cli-parity)
+<!-- /toc -->
+
 > **TLDR**  -  Every non-trivial pipeline action emits an inline "I'm doing X right now" line so the user always knows what's happening. Immediate flush, no batching. One line per action, standard shape. Autopilot prefers verbose. Low overhead. Mirrored in telemetry as `progress.step` events.
 
 This contract is consumed by every phase (0-7) and every dispatched sub-skill (including the marketplace component toolkits when enabled). It is enforced by `smoke-progress-contract.sh`  -  any phase doc that drops the contract marker or diverges from the line shape fails CI.

package/pipeline/multi-agent-refs/setup/firebase.md

@@ -1,5 +1,14 @@
 # Firebase / Crashlytics Onboarding (setup Step 3c)
 
+<!-- toc -->
+- [1. Why there are three ways in](#1-why-there-are-three-ways-in)
+- [2. Tier 1 - the service account](#2-tier-1---the-service-account)
+- [3. Tier 2 - interactive session plus MCP](#3-tier-2---interactive-session-plus-mcp)
+- [4. appId discovery](#4-appid-discovery)
+- [5. v1alpha, and what to do when it breaks](#5-v1alpha-and-what-to-do-when-it-breaks)
+- [6. Skipping](#6-skipping)
+<!-- /toc -->
+
 Loaded on demand by `/multi-agent:setup` Step 3c (optional, any platform). The SKILL.md carries the step intro; this file is the full flow.
 
 Runs inside Step 3 alongside the other missing credentials. A user who already

package/pipeline/multi-agent-refs/swiftui-guide.md

@@ -1,5 +1,22 @@
 ## SwiftUI Component Generation Guide (Generic)
 
+<!-- toc -->
+- [Component Architecture: Configuration / View / Modifiers](#component-architecture-configuration-view-modifiers)
+- [Simple vs Complex Decision](#simple-vs-complex-decision)
+- [Configuration Purity Rules](#configuration-purity-rules)
+- [Fluent Modifier Pattern](#fluent-modifier-pattern)
+- [Token Discipline](#token-discipline)
+- [Variant-Driven Implementation](#variant-driven-implementation)
+- [Nested Component Handling](#nested-component-handling)
+- [Accessibility Requirements](#accessibility-requirements)
+- [Preview Best Practices](#preview-best-practices)
+- [3-Layer Test Strategy](#3-layer-test-strategy)
+- [Build Verification](#build-verification)
+- [Component Quality Checklist](#component-quality-checklist)
+- [Compliance Rules (maps to multi-agent-toolkit MCP audit tools)](#compliance-rules-maps-to-multi-agent-toolkit-mcp-audit-tools)
+- [Figma URL Given](#figma-url-given)
+<!-- /toc -->
+
 > **MUST: Figma MCP-first (BLOCKING).** If the task references any Figma frame (URL, node ID, or "from the design"), the Dev phase MUST call `mcp__claude_ai_Figma__get_design_context` for every frame BEFORE writing a single UI line. Use the `CodeConnectSnippet` component name verbatim - no sound-alike substitutions. Authentication failure is not a skip path. Full rule, trigger conditions, and gate failure modes: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)". Phase wiring: `$HOME/.claude/multi-agent-refs/phases/phase-3-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
 
 When the task involves creating a SwiftUI component (any project), follow this architecture.

package/pipeline/multi-agent-refs/tracker-contract.md

@@ -4,6 +4,18 @@ description: "Phase tracker mandatory contract  -  every mode depends on this. N
 
 # Phase Tracker  -  Mandatory Contract
 
+<!-- toc -->
+- [Why two channels](#why-two-channels)
+- [Visual channel  -  chosen by the agent based on the host CLI](#visual-channel---chosen-by-the-agent-based-on-the-host-cli)
+- [Call pattern](#call-pattern)
+- [The plan is part of the list](#the-plan-is-part-of-the-list)
+- [Resume behaviour](#resume-behaviour)
+- [Continuation runs (finish / manual-test)](#continuation-runs-finish-manual-test)
+- [Anti-patterns](#anti-patterns)
+- [Verification](#verification)
+- [Cross-reference](#cross-reference)
+<!-- /toc -->
+
 > **TLDR**  -  At every phase boundary the agent does two things: (1) writes to the state file via `phase-tracker.sh` (identical on every CLI), (2) drives the visual channel for the CLI it's running in  -  `TaskCreate`/`TaskUpdate` in Claude Code, `phase-tracker.sh render` in every other CLI. The state file alone is not enough; the user must see the phases progress.
 
 ## Why two channels

package/pipeline/multi-agent-refs/web-guide.md

@@ -1,5 +1,15 @@
 ## Web Development Guide
 
+<!-- toc -->
+- [Component Architecture](#component-architecture)
+- [React Component Pattern](#react-component-pattern)
+- [State Management](#state-management)
+- [Token Discipline](#token-discipline)
+- [Accessibility](#accessibility)
+- [Testing](#testing)
+- [Quality Checklist](#quality-checklist)
+<!-- /toc -->
+
 When the task involves web development (React, Next.js, Vue), follow these patterns.
 
 ### Component Architecture

package/pipeline/multi-agent-refs/wiki-capture.md

@@ -1,5 +1,16 @@
 # Component Wiki Capture (channels.md Wiki adapter)
 
+<!-- toc -->
+- [Applicability](#applicability)
+- [Case A  -  preconditions met (scope multi-select)](#case-a---preconditions-met-scope-multi-select)
+- [Case B  -  preconditions missing (actionable menu)](#case-b---preconditions-missing-actionable-menu)
+- [Legacy prompt + preference flow (pre-v5.7, still supported for backward compat)](#legacy-prompt-preference-flow-pre-v57-still-supported-for-backward-compat)
+- [Dispatch](#dispatch)
+- [Skip conditions (explicit log lines)](#skip-conditions-explicit-log-lines)
+- [Success log](#success-log)
+- [Cross-CLI parity](#cross-cli-parity)
+<!-- /toc -->
+
 > **TLDR**  -  Component tasks can auto-generate wiki docs + Figma screenshots. The Wiki adapter is invoked from `/multi-agent:channels` (Phase 7 delegates, or user invokes post-hoc). Four layouts supported (`submodule`, `in-repo`, `github-wiki`, `separate-repo`)  -  adapter picked from `figmaConfig.wiki.mode`. Non-blocking: failures log a warning and channels continues to other adapters. The Wiki adapter supports scope multi-select (Case A) and a precondition-failure menu (Case B)  -  see below.
 
 This doc is referenced from `commands/multi-agent/channels/SKILL.md` (Wiki adapter) and indirectly from `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` (which delegates all external delivery to channels). Keeping it separate keeps both files under their token budgets and gives the contract a stable location for Claude-side + Copilot-side implementations.

package/pipeline/schemas/prefs.schema.json

@@ -1871,6 +1871,10 @@
               "default": 60,
               "description": "Recording cap. A flow needing longer is a debugging session, not a review artefact. Android's `screenrecord` has its own ceiling of 180s that no setting can lift, so capture-evidence.sh clamps to it and says when it did: one preference honoured on one platform and silently halved on the other is worse than a stated limit."
             },
+            "webBaseUrl": {
+              "type": "string",
+              "description": "The address a web capture points the browser at. Web is the one evidence platform that needs one: a simulator is already showing something, a dev server has to be pointed at. Absent, `capture-evidence.sh after --platform web` reports a gap with that reason instead of guessing a port. Per-run override: `--url`."
+            },
             "githubHost": {
               "type": "string",
               "enum": ["branch", "off"],

package/pipeline/schemas/review-file-exclusions.json

@@ -0,0 +1,137 @@
+{
+  "$comment": "Not a JSON Schema: the data the review file filter reads. Lives beside token-budget.json for the same reason - it is a budget-shaped decision the pipeline owns, versioned with the code that consumes it.",
+  "version": 1,
+  "patterns": [
+    {
+      "glob": "**/*.generated.*",
+      "reason": "generated file - review the generator, not its output"
+    },
+    {
+      "glob": "**/Generated/**",
+      "reason": "generated tree - review the generator, not its output"
+    },
+    {
+      "glob": "**/generated/**",
+      "reason": "generated tree - review the generator, not its output"
+    },
+    { "glob": "**/*.pb.go", "reason": "generated file - review the generator, not its output" },
+    { "glob": "**/*_pb2.py", "reason": "generated file - review the generator, not its output" },
+
+    {
+      "glob": "**/package-lock.json",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/yarn.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/pnpm-lock.yaml",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Package.resolved",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Podfile.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Gemfile.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/poetry.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Cargo.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/gradle.lockfile",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+
+    {
+      "glob": "**/__snapshots__/**",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+    {
+      "glob": "**/*.snap",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+    {
+      "glob": "**/__Snapshots__/**",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+    {
+      "glob": "**/ReferenceImages/**",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+
+    {
+      "glob": "vendor/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+    {
+      "glob": "**/node_modules/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+    {
+      "glob": "Pods/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+    {
+      "glob": "**/third_party/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+
+    {
+      "glob": "**/*.min.js",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "**/*.min.css",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "**/*.map",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "dist/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "build/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": ".build/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "**/DerivedData/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+
+    { "glob": "**/*.png", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.jpg", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.jpeg", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.gif", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.webp", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.pdf", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.zip", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.ipa", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.apk", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.aab", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.mp4", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.mov", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.ttf", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.otf", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.woff", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.woff2", "reason": "binary asset - a text reviewer cannot read it" }
+  ]
+}