@mmerterden/multi-agent-pipeline 17.1.0 → 17.4.0

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

@@ -1,5 +1,19 @@
 ## Android/Kotlin Component Generation Guide
 
+<!-- toc -->
+- [Component Architecture: State / Screen / Content](#component-architecture-state-screen-content)
+- [Simple vs Complex Decision](#simple-vs-complex-decision)
+- [State Pattern](#state-pattern)
+- [Token Discipline](#token-discipline)
+- [Stability for Performance](#stability-for-performance)
+- [Accessibility](#accessibility)
+- [Preview Best Practices](#preview-best-practices)
+- [Testing](#testing)
+- [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)
+<!-- /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 Composable 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 an Android UI component (Jetpack Compose), follow this architecture.

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

@@ -1,5 +1,17 @@
 ## Audit & Quality Tools Guide
 
+<!-- toc -->
+- [Trigger Model](#trigger-model)
+- [iOS Accessibility Audit](#ios-accessibility-audit)
+- [Android Accessibility Audit](#android-accessibility-audit)
+- [iOS Biometric Test](#ios-biometric-test)
+- [Android Launch Time](#android-launch-time)
+- [iOS Archive Audit (App Store Compliance)](#ios-archive-audit-app-store-compliance)
+- [Android APK Audit (Play Store Compliance)](#android-apk-audit-play-store-compliance)
+- [Integration with Pipeline Phases](#integration-with-pipeline-phases)
+- [Graceful Degradation](#graceful-degradation)
+<!-- /toc -->
+
 Standalone audit commands  -  runs directly via Bash, **no MCP server dependency**. These are the same checks that multi-agent-toolkit-mcp provides as MCP tools, but embedded here as pipeline skills.
 
 ### Trigger Model

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

@@ -1,5 +1,15 @@
 ## Backend API Development Guide
 
+<!-- toc -->
+- [API Architecture](#api-architecture)
+- [Python/FastAPI Pattern](#pythonfastapi-pattern)
+- [Node.js/Express Pattern](#nodejsexpress-pattern)
+- [Error Handling](#error-handling)
+- [Security Checklist](#security-checklist)
+- [Testing](#testing)
+- [Quality Checklist](#quality-checklist)
+<!-- /toc -->
+
 When the task involves backend development (Python/FastAPI, Node.js/Express, Go), follow these patterns.
 
 ### API Architecture

package/pipeline/multi-agent-refs/channels/confluence.md

@@ -1,5 +1,16 @@
 # Channel adapter  -  Confluence page
 
+<!-- toc -->
+- [Required body structure](#required-body-structure)
+- [Token check](#token-check)
+- [Parent page resolution](#parent-page-resolution)
+- [Page title](#page-title)
+- [Body conversion (markdown → storage format)](#body-conversion-markdown-storage-format)
+- [POST contract](#post-contract)
+- [Recents persistence](#recents-persistence)
+- [Hard rules (must not regress)](#hard-rules-must-not-regress)
+<!-- /toc -->
+
 > Detailed contract for the `confluence` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here.
 
 The Confluence adapter creates or updates a Confluence page under a chosen parent. Like the Jira adapter, it runs **once** per invocation  -  the page lives at the primary repo's component slug in multi-repo mode.

package/pipeline/multi-agent-refs/channels/issue-comment.md

@@ -1,5 +1,17 @@
 # Channel adapter  -  GitHub Issue comment
 
+<!-- toc -->
+- [When this fires](#when-this-fires)
+- [The hard rule](#the-hard-rule)
+- [Required body structure](#required-body-structure)
+- [Hard prohibitions](#hard-prohibitions)
+- [Compaction policy](#compaction-policy)
+- [API contract](#api-contract)
+- [Pairing with the Progress flag updater](#pairing-with-the-progress-flag-updater)
+- [Drift detection](#drift-detection)
+- [Hard rules (must not regress)](#hard-rules-must-not-regress)
+<!-- /toc -->
+
 > Canonical template for the `issue` channel of `/multi-agent:channels`. Every successful run that touched a tracked GitHub issue MUST post one comment using this template  -  no exceptions, no "state-only" shortcuts.
 
 ## When this fires

package/pipeline/multi-agent-refs/channels/jira.md

@@ -1,5 +1,15 @@
 # Channel adapter  -  Jira comment
 
+<!-- toc -->
+- [Required body structure](#required-body-structure)
+- [Wiki markup conversion](#wiki-markup-conversion)
+- [Cross-link injection](#cross-link-injection)
+- [Token resolution](#token-resolution)
+- [POST contract](#post-contract)
+- [Wiki → Jira auto-link triad](#wiki-jira-auto-link-triad)
+- [Hard rules (must not regress)](#hard-rules-must-not-regress)
+<!-- /toc -->
+
 > Detailed contract for the `jira` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here.
 
 The Jira adapter posts a comment on the linked issue. The Jira ticket is shared by all repos in a multi-repo task, so the adapter runs **once** per channels invocation regardless of how many PR targets are dispatched in parallel.

package/pipeline/multi-agent-refs/channels/pr-review-actions.md

@@ -1,5 +1,18 @@
 # Channel adapter  -  Pull Request review actions
 
+<!-- toc -->
+- [When this fires](#when-this-fires)
+- [The decision rule](#the-decision-rule)
+- [Inline comment template (per finding)](#inline-comment-template-per-finding)
+- [Decision endpoints](#decision-endpoints)
+- [Order of operations](#order-of-operations)
+- [Hard prohibitions](#hard-prohibitions)
+- [Idempotency](#idempotency)
+- [Provider auto-detection](#provider-auto-detection)
+- [Pairing with the chat summary](#pairing-with-the-chat-summary)
+- [Drift detection](#drift-detection)
+<!-- /toc -->
+
 > Canonical contract for the PR-actions branch of `/multi-agent:review`. The PR-side artifacts are **per-finding inline comments + an explicit approve / needs-work decision**  -  never a single monolithic description comment.
 
 ## When this fires

package/pipeline/multi-agent-refs/channels/pr.md

@@ -1,5 +1,16 @@
 # Channel adapter  -  PR description
 
+<!-- toc -->
+- [Required body structure](#required-body-structure)
+- [Markup dialect (per surface, not per pipeline)](#markup-dialect-per-surface-not-per-pipeline)
+- [Behaviour by remote](#behaviour-by-remote)
+- [Reviewer-preserving Bitbucket payload (required)](#reviewer-preserving-bitbucket-payload-required)
+- [Multi-repo cross-links](#multi-repo-cross-links)
+- [Version mismatch handling](#version-mismatch-handling)
+- [Flags that affect this adapter](#flags-that-affect-this-adapter)
+- [Hard rules (must not regress)](#hard-rules-must-not-regress)
+<!-- /toc -->
+
 > Detailed contract for the `pr` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here.
 
 The PR adapter rewrites the pull request description with the body assembled in Step 5 of `channels.md`. Default behaviour is **replace**; `--append` opt-in preserves existing content.
@@ -66,6 +77,32 @@ Across stacks the same shape produces, for example: `LoginView.swift  -  ...` (i
 <none, or which service, contract or channel>
 ```
 
+Part 3 is the one part of this body that is MEASURED rather than recalled. The
+code graph already answers it, so draw the answer instead of re-typing it:
+
+```bash
+node "$HOME/.claude/scripts/graph-mermaid.mjs" "<changed symbol[,symbol]>"
+```
+
+Append the fenced block it prints under part 3, above the prose. GitHub renders
+mermaid natively in pull requests, so this costs no renderer and no plugin. The
+prose stays: the diagram says which symbols the change reaches, the sentence says
+which screens and flows a tester must open, and neither answers the other.
+
+Exit 1 means the repo has no graph yet (`/multi-agent:graph` builds it) or the
+symbol is not in it. That is a gap with a reason, not a failure: write the prose
+alone and say the graph was unavailable. Never hand-draw the diagram - a drawn
+blast radius nobody measured is worse than none, because a diagram is read as
+fact.
+
+The commit line the script prints stays with it. A graph built before the change
+draws the radius of an older tree, and the reader has no other way to notice.
+
+This is a GitHub-only section. `channels/jira.md` has no mermaid handling at all:
+a fence there converts to a literal `{code:mermaid}` block, so the Jira impact
+section keeps its prose. Confluence renders it through the `ac:name="mermaid"`
+macro (`md2confluence-v3.py`) when the space has the plugin.
+
 When the change deliberately fixes part of a wider problem, a closing **Risk and remaining scope** paragraph names what is still open and why it was left - a reviewer who can see the rest of the pattern in the repo will ask otherwise, and the honest answer is cheaper written down than defended in a thread.
 
 **`test_scenarios`**  -  the same titled-scenario shape the Jira adapter uses, so the tester reads one list on both surfaces, with symbols allowed here:

package/pipeline/multi-agent-refs/component-dispatch.md

@@ -1,5 +1,16 @@
 # Component Dispatch (Phase 3 short-circuit)
 
+<!-- toc -->
+- [Entry conditions](#entry-conditions)
+- [Plugin skill resolution](#plugin-skill-resolution)
+- [Dispatch call](#dispatch-call)
+- [Subphase contract (dispatch-layer owned)](#subphase-contract-dispatch-layer-owned)
+- [Multi-repo report](#multi-repo-report)
+- [Failure + resume](#failure-resume)
+- [Short-run behaviour](#short-run-behaviour)
+- [Cross-CLI behaviour (intentional divergence)](#cross-cli-behaviour-intentional-divergence)
+<!-- /toc -->
+
 > **TLDR**  -  When `taskType === "component"` (Figma URL in task description or instruction-driven figma workflow), multi-agent Phase 3 **does not run the TDD loop**. It delegates the entire phase to the enabled `ai-<platform>-toolkit` **marketplace plugin's** component skill (`create-component`, falling back to `create-ui-component`) via the Skill tool. Implementation lives in the plugin; multi-agent's job is classification, dispatch, and state report. The pipeline no longer bundles its own `figma-to-component` orchestrator  -  component skills live in one place, the plugin marketplace.
 
 This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-3-dev.md`. Keeping it separate lets `phase-3-dev.md` remain tight (it's already the largest phase doc) and gives the orchestrator-report contract a stable URL for both Claude-side and Copilot-side implementations.

package/pipeline/multi-agent-refs/component-generation.md

@@ -1,5 +1,16 @@
 # Component Generation Guide (generic)
 
+<!-- toc -->
+- [Component Architecture: Configuration / View / Modifiers](#component-architecture-configuration-view-modifiers)
+- [Configuration Purity Rule](#configuration-purity-rule)
+- [View Implementation](#view-implementation)
+- [Modifier Pattern](#modifier-pattern)
+- [Simple vs Complex Decision](#simple-vs-complex-decision)
+- [3-Layer Test Strategy](#3-layer-test-strategy)
+- [Component Checklist (Before Commit)](#component-checklist-before-commit)
+- [When a Figma URL Is Provided](#when-a-figma-url-is-provided)
+<!-- /toc -->
+
 > Lifted out of `core/multi-agent/SKILL.md`, where it was loaded on every
 > run of every mode. It applies only to a task that generates a UI
 > component from a design, so it now loads when that path is taken.

package/pipeline/multi-agent-refs/conventions-defaults.md

@@ -4,6 +4,21 @@ description: "Convention fallback defaults for /multi-agent:analysis Phase 2b Pa
 
 # Convention Defaults - Pass B Fallback Reference
 
+<!-- toc -->
+- [How the fallback chain works](#how-the-fallback-chain-works)
+- [C1 - Folder Structure](#c1---folder-structure)
+- [C2 - Class Naming](#c2---class-naming)
+- [C3 - UI State Model](#c3---ui-state-model)
+- [C4 - Test Method Naming](#c4---test-method-naming)
+- [C5 - Accessibility Identifier](#c5---accessibility-identifier)
+- [C6 - Localization Key](#c6---localization-key)
+- [C8 - SwiftUI Preview macro (iOS only)](#c8---swiftui-preview-macro-ios-only)
+- [C7 - Dependency Injection](#c7---dependency-injection)
+- [Risk row template (Section 20)](#risk-row-template-section-20)
+- [Maintenance](#maintenance)
+- [Locked decisions that govern this file](#locked-decisions-that-govern-this-file)
+<!-- /toc -->
+
 `/multi-agent:analysis` Phase 1c extracts conventions from each selected repo (folder structure, class naming, state model, test naming, accessibility identifier, localization key, DI registration). When `confidence == "none"` AND the standards binding source (`evidence.standards[]`) does not provide an explicit rule, Pass B falls back to the platform defaults catalogued here. Every applied default emits a row in Section 20 Risks of the rendered document.
 
 > **Language**: This file is read as a system prompt. Prose stays English. Examples carry generic placeholder names (`Foo`, `Bar`); the runtime substitutes the actual feature slug.

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

@@ -1,5 +1,18 @@
 # Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
+<!-- toc -->
+- [1. Command Inventory (56 commands)](#1-command-inventory-56-commands)
+- [2. Canonical Placeholder Vocabulary](#2-canonical-placeholder-vocabulary)
+- [2.6 Intentional structural divergence  -  thin dispatcher vs inlined orchestrator](#26-intentional-structural-divergence---thin-dispatcher-vs-inlined-orchestrator)
+- [3. Frontmatter Transform Rules (Claude ↔ Copilot)](#3-frontmatter-transform-rules-claude-copilot)
+- [4. Progress Signalling Parity](#4-progress-signalling-parity)
+- [5. Argument Parsing Invariants](#5-argument-parsing-invariants)
+- [6. Output Format Expectations](#6-output-format-expectations)
+- [7. Platform Guards (macOS)](#7-platform-guards-macos)
+- [8. Enforcement](#8-enforcement)
+- [9. Change Control](#9-change-control)
+<!-- /toc -->
+
 > **Non-negotiable**. Any change that breaks this contract blocks merge. Validated by `smoke-cross-cli-behavior.sh`.
 
 **Purpose**: every pipeline command must produce identical artifacts (state, logs, outputs) and respect identical placeholder vocabulary regardless of which of the three host CLIs invokes it. This file is the source of truth for "what must stay the same."
@@ -201,6 +214,28 @@ on skill directories would demand exactly the layout that breaks it.
 
 Future changes that break an item in the "stay identical" list must update **both** files in the same commit. `smoke-cross-cli-behavior.sh` enforces the identity-preserving axis (input parsing, routing, output shape); structural differences are left to manual review because enforcing them would require forcing the files to the same shape, which we intentionally don't want.
 
+### Panel diversity per host
+
+Phase 4 runs three reviewers everywhere, but the diversity those three buy is not the
+same on every host. Copilot CLI gets cross-VENDOR disagreement for free: GPT-5.4 sits
+beside two Claude models. Claude Code and Codex each run a one-vendor panel - three
+Anthropic models on one, three OpenAI models on the other - so the same three-way
+agreement is weaker evidence there, and Phase 4 says so in the triage note on a
+borderline finding.
+
+Where the budget goes instead, when vendor diversity is unavailable:
+
+| Host | Reviewer 1 | Reviewer 2 | Reviewer 3 |
+|---|---|---|---|
+| Copilot CLI | Fable/Opus, security + architecture | GPT-5.4, edge cases (cross-vendor) | Sonnet, quality |
+| Claude Code | Fable, security + architecture | Opus, edge cases | Sonnet, quality |
+| Codex | `xhigh`, security + architecture | a different family member, edge cases | `medium`, quality |
+
+On Codex the axis is reasoning effort as much as model identity, because the family
+members available there are closer to each other than Fable and Sonnet are. That is a
+weaker axis, not an equivalent one, and treating it as equivalent is the error this
+section exists to prevent.
+
 ## 3. Frontmatter Transform Rules (Claude ↔ Copilot)
 
 Each file has a different frontmatter schema. The sync flow transforms between them:
@@ -264,6 +299,35 @@ Every phase boundary MUST call EITHER TaskCreate/Update (Claude) OR `phase-track
 
 `phase-banner.sh` runs on both CLIs. Same output format, no Claude-only or Copilot-only flair.
 
+### 4.4 Continuous mode
+
+`autopilot-on`, `autopilot-off` and `autopilot-status` ship to all three hosts and
+behave identically there, because the thing they control is not a CLI feature:
+it is a launchd user agent whose tick spawns a `claude --bg` child regardless of
+which CLI you typed the command in. Continuous mode therefore requires the
+`claude` binary on `PATH` on every host, Copilot and Codex included, and there is
+no Copilot or Codex equivalent of the child.
+
+| Concept | Claude Code | Copilot CLI | Codex CLI |
+|---|---|---|---|
+| Turn the mode on | `/multi-agent:autopilot-on` | `/multi-agent-autopilot-on` | `multi-agent autopilot-on` via the router skill |
+| Scripts, libs, templates | `~/.claude/{scripts,lib,templates}` | `~/.copilot/...` | `~/.codex/...` |
+| Which one is read | `ma_ap_asset <rel>` resolves the caller's own tree first, then the other two | same | same |
+| Queue and config state | `~/.claude/autopilot/` | `~/.claude/autopilot/` | `~/.claude/autopilot/` |
+| In-flight rows on the widget | `autopilot-status --subjects` into `TaskUpdate` | into the reprinted card | into `update_plan` |
+
+The state row is the one that looks wrong and is not. `~/.claude/autopilot/` is
+shared across hosts on purpose, exactly like `logs/`, `knowledge/` and
+`multi-agent-preferences.json` (2.6, "shared state is deliberately NOT
+retargeted"): two CLIs on one machine must read ONE queue. A per-host state root
+would give a Copilot session a second, invisible queue and the same ticket would
+be taken twice.
+
+Everything that is NOT state resolves per host, and that half had to be fixed:
+`templates/` was laid down only by `install/claude.mjs`, so `autopilot-on` on a
+Codex-only machine rendered a launchd job from a file the host did not have.
+`smoke-autopilot-hosts.sh` holds the line.
+
 ---
 
 ## 5. Argument Parsing Invariants
@@ -338,6 +402,7 @@ installs on.
 
 This contract is validated by:
 
+- `smoke-autopilot-hosts.sh`  -  asserts continuous mode resolves its scripts, libs and plist template into whichever host tree is installed, and that the state root is NOT retargeted (4.4)
 - `smoke-cross-cli-behavior.sh`  -  asserts every command behaves identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 8-persona agent deployment
 - `smoke-commands-skills-parity.sh` (two assertions per command)  -  enforces colon-form command ↔ dash-form skill directory parity
 - `smoke-compliance-skills.sh`  -  enforces store-compliance skill catalog + 4 consumer wiring

package/pipeline/multi-agent-refs/features/analysis-jira.md

@@ -1,5 +1,16 @@
 # analysis-jira - an analysis document, read as work
 
+<!-- toc -->
+- [The marker gate runs first, before any network call](#the-marker-gate-runs-first-before-any-network-call)
+- [Coverage is two-way, and the second direction is the useful one](#coverage-is-two-way-and-the-second-direction-is-the-useful-one)
+- [An unverifiable run is allowed; looking verified is not](#an-unverifiable-run-is-allowed-looking-verified-is-not)
+- [Identity is a label, not a title](#identity-is-a-label-not-a-title)
+- [The write is ledgered](#the-write-is-ledgered)
+- [An existing node is skipped, never updated](#an-existing-node-is-skipped-never-updated)
+- [Every site-specific name is a VALUE, never a schema key](#every-site-specific-name-is-a-value-never-a-schema-key)
+- [Auth](#auth)
+<!-- /toc -->
+
 `/multi-agent:analysis-jira` turns a rendered analysis document into a Jira tree.
 Two files do it, and the split is the design:
 

package/pipeline/multi-agent-refs/features/code-graph.md

@@ -1,5 +1,11 @@
 ## Code Graph (Phase 1 Step 2.6 + Phase 7 Step 3)
 
+<!-- toc -->
+- [Phase 1 Step 2.6  -  query before dispatching Explore](#phase-1-step-26---query-before-dispatching-explore)
+- [Phase 7 Step 3  -  refresh after the branch changed code](#phase-7-step-3---refresh-after-the-branch-changed-code)
+- [The graph is drawable, and one place already asks for it](#the-graph-is-drawable-and-one-place-already-asks-for-it)
+<!-- /toc -->
+
 A deterministic, LLM-free map of what a repo declares and what refers to what,
 written to `~/.claude/knowledge/<project>/code-graph.json`. Gated by
 `prefs.global.codeGraph.enabled` (default `false`); with it off, Phase 1 and
@@ -67,3 +73,37 @@ The rebuild costs no API tokens, so it runs every task rather than on a stalenes
 heuristic. A non-zero validator exit keeps the previous graph and logs
 `knowledge.graph_invalid`; it never fails the run  -  a stale graph is a degraded
 Phase 1, not a broken deliverable.
+
+### The graph is drawable, and one place already asks for it
+
+The PR body's Impact Analysis, part 3, asks which symbols and files a change
+reaches. That is `graph-affected.mjs`'s question, and until now the answer was
+re-typed as prose by a model while the measurement sat on disk unread.
+
+```bash
+node $HOME/.claude/scripts/graph-mermaid.mjs "<symbol[,symbol]>" [--depth N] [--max-nodes N]
+```
+
+It emits a fenced `flowchart` and nothing else - no renderer, no plugin, no
+dependency, because mermaid is text and GitHub renders it natively in pull
+requests, issues and markdown files. Traversal is not reimplemented: `findByName`
+and `affected` are imported from `graph-affected.mjs`, so the diagram and the
+text report cannot disagree about what is affected.
+
+Three properties that are enforced rather than promised
+(`smoke-graph-mermaid.sh`):
+
+- Every drawn node and edge resolves back into `code-graph.json`, with the edge
+  kind it claims. A diagram is read as fact and checked less than prose, so an
+  invented edge is the expensive failure.
+- Over `--max-nodes` the leftover count is printed inside the diagram, not
+  dropped. A small picture of a large blast radius reads as reassurance.
+- The graph's `baseCommit` is printed beside it. A graph built before the change
+  draws an older tree, and nothing else in the PR would reveal that.
+
+Exit 1 with a reason on stderr means no graph or no such symbol. The caller
+records the gap and writes the prose alone; it never hand-draws a replacement.
+
+Jira is not a target: its renderer turns the fence into a literal
+`{code:mermaid}` block. Confluence renders it through the `ac:name="mermaid"`
+macro when the space carries the plugin (`channels/confluence.md`).

package/pipeline/multi-agent-refs/features/design-conformance.md

@@ -1,5 +1,16 @@
 # Design conformance  -  the component walk, and why a glance is not a pass
 
+<!-- toc -->
+- [0. Why this runs as a gate](#0-why-this-runs-as-a-gate)
+- [1. Enumerate first, then fill every cell](#1-enumerate-first-then-fill-every-cell)
+- [2. Measure, never read the token](#2-measure-never-read-the-token)
+- [3. Adaptive per-component convergence](#3-adaptive-per-component-convergence)
+- [4. Scope tags  -  how an item is verified](#4-scope-tags---how-an-item-is-verified)
+- [5. The catalog](#5-the-catalog)
+- [6. Output](#6-output)
+- [7. What a token catalog is, and why none ships here](#7-what-a-token-catalog-is-and-why-none-ships-here)
+<!-- /toc -->
+
 A design audit that reads a screen top to bottom and reports what looks wrong
 finds about one defect per element: the wrong font on a label, and not that same
 label's wrong colour and wrong inset. This file is the catalog, and the three
@@ -14,6 +25,19 @@ Consumers: `/multi-agent:design-check` (the runner), Phase 4 review when a UI
 diff is under review, and `features/visual-evidence.md` when a capture has to
 prove a fix. Gate: `smoke-design-conformance.sh`.
 
+## 0. Why this runs as a gate
+
+`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.
+
+The reason it cannot be advice is structural, not historical: a reviewer reading a diff
+cannot see spacing. Every other Phase 4 check reads text and reasons about text; this
+one is the only thing in the pipeline that compares a rendered result against the
+design it was drawn from. Left optional, it is the check that gets skipped on exactly
+the runs that are in a hurry, which are the runs that produce drift.
+
 ## 1. Enumerate first, then fill every cell
 
 Do **not** walk by finding, and do not walk by headline. Build the inventory

package/pipeline/multi-agent-refs/features/doctor.md

@@ -1,5 +1,15 @@
 # doctor - the check registry
 
+<!-- toc -->
+- [What the exit code means](#what-the-exit-code-means)
+- [What BLOCK means, exactly](#what-block-means-exactly)
+- [Who calls it, and what they do with the code](#who-calls-it-and-what-they-do-with-the-code)
+- [The four severities](#the-four-severities)
+- [The line shape](#the-line-shape)
+- [It recommends, it never fixes](#it-recommends-it-never-fixes)
+- [Checks](#checks)
+<!-- /toc -->
+
 Every check `/multi-agent:doctor` can report has a `### <id>` heading here, and
 `doctor.mjs --list-checks` prints exactly the same set. The equality is checked
 in both directions by `smoke-doctor.sh`: a check that ships without an entry

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

@@ -1,5 +1,12 @@
 # Feature: External Context Injection (Phase 1 Step 1.5)
 
+<!-- toc -->
+- [Dispatch table](#dispatch-table)
+- [Exit code handling](#exit-code-handling)
+- [Prompt injection shape](#prompt-injection-shape)
+- [Log line shape](#log-line-shape)
+<!-- /toc -->
+
 Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher and prepends the result to the analysis prompt under a **Referenced External Sources** section, so the agent doesn't re-discover what the ticket already pointed at.
 
 ```bash

package/pipeline/multi-agent-refs/features/jira-context.md

@@ -1,5 +1,14 @@
 # Related-issue context at intake
 
+<!-- toc -->
+- [What it costs](#what-it-costs)
+- [Shape](#shape)
+- [Settings](#settings)
+- [Maturity](#maturity)
+- [Where it goes](#where-it-goes)
+- [Not included](#not-included)
+<!-- /toc -->
+
 A development sub-task is often filed with no description of its own. The
 requirement sits on the parent, and the rest of the picture  -  the analysis, the
 test scope  -  sits on the sibling sub-tasks beside it. The fetcher already read

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -1,5 +1,15 @@
 # Model Fallback Contract
 
+<!-- toc -->
+- [Tier ladder](#tier-ladder)
+- [Prefs knob](#prefs-knob)
+- [Turning the fable rung off](#turning-the-fable-rung-off)
+- [Triggers (checked in this order)](#triggers-checked-in-this-order)
+- [Logging](#logging)
+- [Non-goals](#non-goals)
+- [Codex CLI](#codex-cli)
+<!-- /toc -->
+
 > Contract last revised in **v10.6.0** (Fable 5 restored as top tier). The version tag here tracks the last substantive change to this contract, not the pipeline release.
 
 Personas route to the top available intelligence tier they declare in

package/pipeline/multi-agent-refs/features/review-file-set.md

@@ -0,0 +1,132 @@
+# The review file set  -  what was read, and what was not, on the record
+
+<!-- toc -->
+- [Why this exists](#why-this-exists)
+- [The set is fixed before the reviewer sees the diff](#the-set-is-fixed-before-the-reviewer-sees-the-diff)
+- [Every exclusion names the pattern that produced it](#every-exclusion-names-the-pattern-that-produced-it)
+- [The reviewer answers for each file](#the-reviewer-answers-for-each-file)
+- [Invocation](#invocation)
+- [What this is not](#what-this-is-not)
+<!-- /toc -->
+
+> The denominator for Phase 4's other axis. Loaded on demand by
+> `/multi-agent:review` and by pipeline Phase 4.
+
+## Why this exists
+
+Phase 4 had a size cap and no exclusion list. When the diff exceeds the phase
+token allowance the cap truncates the LARGEST files first, so a regenerated
+lockfile or a snapshot dump is not merely wasted budget: it is the thing that
+survives while real code is cut.
+
+The second half is worse and quieter. A reviewer that opened one file of ten and
+a reviewer that read all ten and found nothing return the identical
+`{"findings": [], "approved": true}`. Nothing in the pipeline could tell them
+apart, so "no findings" has been carrying two meanings at once.
+
+Both halves are one fix: decide what is worth reading BEFORE the cap decides
+what fits, and make the reviewer answer for each file it was given.
+
+## The set is fixed before the reviewer sees the diff
+
+The same rule `selectedRules[]` follows, for the same reason. After a model has
+seen the diff, "I did not open that one" and "there was nothing there" become
+the same sentence, and whichever one is cheaper to say is the one that gets
+said. So the set is computed from `git diff --name-only`, written to
+`.pipeline/review-files.json`, and never recomputed inside the round.
+
+```bash
+git -C "$WORKTREE" diff --name-only "$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/review-file-filter.mjs \
+  > "$WORKTREE/.pipeline/review-files.json"
+```
+
+Report shape:
+
+```json
+{
+  "reviewed": ["src/App.swift"],
+  "excluded": [
+    {
+      "path": "package-lock.json",
+      "reason": "lockfile - resolved by the package manager, not written by hand",
+      "pattern": "**/package-lock.json"
+    }
+  ],
+  "total": 2,
+  "patternsSource": ".../schemas/review-file-exclusions.json",
+  "patternCount": 45
+}
+```
+
+`reviewed` is what goes into the diff cap and into the reviewer prompt, as a
+`${REVIEW_FILES}` block beside `${CRITERIA}` in the shared cache prefix. It has to
+be in the prompt: a reviewer asked to account for a set it was never shown can
+only guess, and `fileCoverage` would then fail on every single dispatch - a gate
+that always fires is a gate that gets switched off. `excluded` goes into the run
+report, never into silence.
+
+## Every exclusion names the pattern that produced it
+
+A file that disappears between the diff and the review is indistinguishable from
+a file nobody found anything in - which is the exact confusion this whole
+feature exists to remove, so reintroducing it in the filter would be
+self-defeating. Each excluded row carries both the human reason and the glob
+that matched, so a reviewer, a PR reader or a future maintainer can dispute the
+call rather than discover it.
+
+The pattern list is data, in `schemas/review-file-exclusions.json`, and it is
+generic: generated trees, lockfiles, recorded snapshots, vendored source, build
+output, binary assets. No stack, project or company name appears in it. A
+pattern with no reason invalidates the whole list rather than being defaulted -
+the default would be exactly the sentence the caller is supposed to print.
+
+**It fails open, on purpose.** An unreadable or malformed pattern file yields
+every file reviewed, the reason on stderr, and exit 2. Failing closed would
+review nothing and report a clean run.
+
+## The reviewer answers for each file
+
+`reviewer-output.schema.json` (v1.3.0) carries `fileCoverage[]`: one row per
+path in `reviewed`, `{path, verdict: reviewed|skipped, reason}`. There is
+deliberately no `partial` - a file read in part is read, and what was not
+understood belongs in a finding.
+
+`validate-reviewer.mjs --coverage <report>` enforces it, catching the same three
+failures the conformance checklist catches on the rule axis:
+
+| Failure | Why it matters |
+|---|---|
+| a file in the set with no row | silently unread, and the empty `findings[]` reads as clean |
+| a row for a path outside the set | an answer about something the reviewer was not given, the same shape as a hallucinated rule ID |
+| `skipped` with no reason | a drop with no cause is indistinguishable from a read |
+
+`skipped` is legitimate and expected: a file past the diff cap, a file whose
+content the host truncated. What it may not be is unexplained. "Not relevant" is
+a review decision and belongs in a verdict of `reviewed`, not a skip.
+
+An empty `reviewed` set (a diff that is entirely lockfiles) demands no checklist
+at all. Requiring an empty array there would fail honest output, and the
+filter's `excluded[]` is what carries that information onward.
+
+## Invocation
+
+```bash
+node $HOME/.claude/scripts/validate-reviewer.mjs "$REVIEWER_FILE" \
+  --criteria "$WORKTREE/.pipeline/criteria-manifest.json" \
+  --coverage "$WORKTREE/.pipeline/review-files.json"
+```
+
+Without `--coverage` the field stays optional, so every existing caller keeps
+working unchanged. With it, the checklist is enforced and exit 1 takes the same
+single self-correction rework the rest of the validator gate takes.
+
+## What this is not
+
+It is not a relevance filter. Nothing here decides that a file is uninteresting;
+it decides that a file is not human-authored source, which is a mechanical
+question with a mechanical answer. The moment a pattern starts encoding "we
+probably do not care about this directory", the list has become a way to hide
+work, and the near-miss assertions in `smoke-review-file-filter.sh`
+(`CodeGenerator.swift`, `generated-report.md`, `distribution/`, `buildSrc/`) are
+what fail when it does.

package/pipeline/multi-agent-refs/features/skill-conformance.md

@@ -1,5 +1,18 @@
 # Skill conformance  -  reviewing against the criteria the work was built to
 
+<!-- toc -->
+- [Why this exists](#why-this-exists)
+- [The four rules that make it work](#the-four-rules-that-make-it-work)
+- [Registry discovery is declared, never sniffed](#registry-discovery-is-declared-never-sniffed)
+- [Scope is required, and it is what makes this stack-generic](#scope-is-required-and-it-is-what-makes-this-stack-generic)
+- [What is deterministic here, and what is deliberately not](#what-is-deterministic-here-and-what-is-deliberately-not)
+- [The one bespoke scan: exception markers](#the-one-bespoke-scan-exception-markers)
+- [Dev-mode substitutes (Phases 1 and 2 never ran)](#dev-mode-substitutes-phases-1-and-2-never-ran)
+- [Invocation](#invocation)
+- [Handoff to the reviewers](#handoff-to-the-reviewers)
+- [Preference](#preference)
+<!-- /toc -->
+
 > **TLDR**  -  Phase 4 Step 1.78 resolves, deterministically and before any reviewer runs, WHAT the changed code was supposed to honour: declared rule registries scoped to the diff's languages, in-repo module guides, and the toolchains those registries delegate to. The result is `criteria-manifest.json`: a bounded set of rule IDs that becomes the denominator for "was this applied completely". Reviewers answer per rule ID. An ID that is neither checked nor explicitly waived fails the stage.
 
 ## Why this exists