@mmerterden/multi-agent-pipeline 17.0.0 → 17.3.0

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.
@@ -10,20 +21,31 @@ The PR description targets code reviewers  -  it stays technical. Every adapter
 
 | # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
 |---|---|---|---|---|
-| 1 | `summary` | `## Özet` | `## Summary` | always |
-| 2 | `changes` | `## Değişiklikler` | `## Changes` | always |
+| 1 | `summary` | `## Geliştirme Özeti` | `## Development Summary` | always |
+| 2 | `technical` | `## Teknik Açıklama` | `## Technical Explanation` | always |
 | 3 | `architecture` | `## Mimari Kararlar` | `## Architecture Decisions` | when a non-trivial design choice was made |
-| 4 | `verification` | `## Doğrulama` | `## Verification` | always |
-| 5 | `visuals` | `## Görsel Kanıt` | `## Visual Evidence` | when `state.visualEvidence.required` |
-| 6 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
-| 7 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
-| 8 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+| 4 | `impact` | `## Etki Analizi` | `## Impact Analysis` | always |
+| 5 | `test_scenarios` | `## Test Senaryoları` | `## Test Scenarios` | always |
+| 6 | `visuals` | `## Görsel Kanıt` | `## Visual Evidence` | when `state.visualEvidence.required` |
+| 7 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
+| 8 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
+| 9 | `build` | `## Build` | `## Build` | always |
+| 10 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+
+`summary`, `impact` and `test_scenarios` carry the same three section keys the
+Jira adapter uses, and that pairing is deliberate: the same three questions get
+answered on both surfaces, at the register each reader needs. The PR versions name
+symbols, files, line counts and build shas. The Jira versions name screens and
+behaviour and nothing else (`channels/jira.md`). `technical` has no Jira twin at
+all - it is the section whose absence over there is the point.
 
 ### Section content rules
 
-**`summary`**  -  1-3 sentences in `outputLanguage`. The "why" of the change. Past tense, no marketing voice. Code identifiers stay verbatim.
+**`summary`**  -  2-4 sentences in `outputLanguage`. What broke or what was added, where the user meets it, and the size of the effect when it is measurable (a crash count, a share of a known total, a version range). Past tense, no marketing voice. Code identifiers stay verbatim. This is the one section a reviewer reads before deciding whether to read the rest, so it names the user-visible behaviour before the mechanism.
+
+**`technical`**  -  the account for someone holding the diff: a short paragraph on the mechanism (what the code was actually doing wrong, or what the new code does), then the per-file bullets, then one line of diff stat (`2 files, 8 deletions, 0 insertions`). Where a change is safe for a reason that is not obvious from the diff - an equality relation preserved, an invariant kept, a call site left alone deliberately - that reason belongs here in a sentence, because it is the question the reviewer would otherwise ask in a comment. Tables are welcome when several symbols share a property worth listing side by side.
 
-**`changes`**  -  bullet list, one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". The source is `$WORKTREE/.pipeline/scope-check.json` `files[].reason` (Phase 3 Step 3.7): a file the dev could not justify there is a file this list cannot describe either, so the bullet quotes the gate output instead of inventing a reason. Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
+The bullet list is one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". The source is `$WORKTREE/.pipeline/scope-check.json` `files[].reason` (Phase 3 Step 3.7): a file the dev could not justify there is a file this list cannot describe either, so the bullet quotes the gate output instead of inventing a reason. Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
 
 ```markdown
 ## Changes
@@ -37,20 +59,55 @@ Across stacks the same shape produces, for example: `LoginView.swift  -  ...` (i
 
 **`architecture`**  -  only when the change involves a non-trivial decision (new abstraction, pattern change, data flow shift, dependency direction). Format: short paragraph stating the decision and the alternative considered. Skip the section entirely for mechanical refactors / dependency bumps / formatting passes.
 
-**`verification`**  -  what the reviewer should run to confirm the change works. Commands first, manual steps next. Pick the commands for the project's stack  -  the pipeline supports iOS (Swift/Xcode), Android (Gradle), web (npm/pnpm/yarn), and backend (varies: pytest/jest/go test/etc). Do not hardcode one stack in the body; emit only the commands relevant to the repos touched by this PR.
+**`impact`**  -  four fixed numbered parts, each answered, never a placeholder. Same four questions as the Jira `impact` section, answered here with the identifiers and numbers that section is not allowed to carry:
+
+```markdown
+## Impact Analysis
+
+**1 - The problem**
+<what was wrong, since which version, with the crash/report identifiers and counts>
+
+**2 - What was changed**
+<the change, and why behaviour around it is unchanged>
+
+**3 - Affected functions**
+<the screens, flows and symbols that must be tested, including shared components the change reaches>
+
+**4 - Effect on other systems**
+<none, or which service, contract or channel>
+```
+
+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.
 
-Skeleton (the adapter fills the body with the actual stack-appropriate lines at write-time; the template lists the shape only):
+**`test_scenarios`**  -  the same titled-scenario shape the Jira adapter uses, so the tester reads one list on both surfaces, with symbols allowed here:
 
 ```markdown
-## Verification
+## Test Scenarios
+
+**1. <what this scenario exercises>**
+1. <step>
+2. **Expected:** <observable outcome>
 
-- Build: <stack-appropriate build command>
-- Tests: <stack-appropriate test command, scoped to the touched targets/packages>
-- Lint / type-check: <if the project has one>
-- Manual: <one or more user-facing steps the reviewer can follow without setup>
+**2. <regression scenario>**
+1. <step>
+2. **Expected:** <what should still behave as before>
 ```
 
-Multi-repo PRs (one PR per repo) emit verification commands for that repo's stack only  -  never mix iOS + Android commands into a single PR body.
+Reproduction scenarios first, then regressions for whatever the change could have disturbed. When a UI test target covers a scenario, say so on the scenario line and let `## Build` carry the run result - a scenario a machine already ran is not the same request as one a human has to perform, and conflating them wastes the reviewer's time.
+
+**`build`**  -  what was built, on what, and what came out. Not a promise that it builds; the recorded result of the run that happened:
+
+```markdown
+## Build
+
+- <build command or scheme> on <base branch>@<sha>: BUILD SUCCEEDED, 0 errors
+- Tests: <test command>: <N> passed, <M> failed
+- UI tests: <target>: <status> | not run  -  <reason from state.uiTest.notRunReason>
+```
+
+The base sha matters because "it builds" is a claim about a merge base, and the reviewer's local tree is usually not that one. `state.uiTest` supplies the third line verbatim, including its `notRunReason` - "no UI test target in this repo" is a result, not a gap, and writing it stops the same question being asked on every PR.
+
+Pick commands for the project's stack  -  the pipeline supports iOS (Swift/Xcode), Android (Gradle), web (npm/pnpm/yarn) and backend (pytest/jest/go test/etc). Multi-repo PRs (one PR per repo) emit the commands for that repo's stack only  -  never mix iOS + Android commands into a single PR body.
 
 **`risk`**  -  only when `state.diffRisk.signals` (Phase 4 Step 1.75) contains a high-stakes signal. Four fixed lines, each answered, never left as a placeholder; the source is Phase 1 `touchedAreas` plus the signals themselves, and when a signal is present the absence of this section is a Phase 6 Step 3 blocker:
 
@@ -136,7 +193,7 @@ Never use `Closes #N`, `Fixes #N`, `Resolves PROJ-X`. Issues require 4-approval
 
 ```
 1. Read agent-state.json (taskId, contextLinks, identity, language).
-2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply. Section order is fixed: `summary` → `changes` → `architecture` (cond.) → `verification` → `risk` (cond.) → `dependencies` (cond.) → `related`.
+2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply. Section order is fixed: `summary` → `technical` → `architecture` (cond.) → `impact` → `test_scenarios` → `visuals` (cond.) → `risk` (cond.) → `dependencies` (cond.) → `build` → `related`.
 3. Run the assembled body through the `humanizer` skill.
 4. Apply Multi-repo cross-links (## Related PRs prepend when projects.length > 1).
 5. Dispatch per the Behaviour-by-remote table.
@@ -220,7 +277,7 @@ The Bitbucket REST API returns `409 Conflict` if `version` is stale. Adapter beh
 ## Hard rules (must not regress)
 
 - Real newlines, no HTML entities  -  heredoc + `jq --rawfile` + `curl --data-binary @file`. Never embed `\n` literally; Bitbucket stores the literal `\n` characters.
-- Section order is fixed: `summary` → `changes` → `architecture` (cond.) → `verification` → `dependencies` (cond.) → `related`. Conditional sections may be omitted but never reordered or inserted between fixed ones.
+- Section order is fixed: `summary` → `technical` → `architecture` (cond.) → `impact` → `test_scenarios` → `visuals` (cond.) → `risk` (cond.) → `dependencies` (cond.) → `build` → `related`. Conditional sections may be omitted but never reordered or inserted between fixed ones.
 - Humanizer pass runs **after** body assembly and **before** dispatch  -  every body line carries technical, non-AI tone. References at least one symbol/file/line drawn from the diff or pipeline log.
 - Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, branch names, PR titles, commands, type names, and `Closes/Fixes`-style keywords stay verbatim English. The template file (this doc) is English because `promptLanguage="en"` is locked; the body is rendered in the user's language at write-time.
 - No body markers (`<!-- channels:start -->`)  -  channels does a full replace each run.

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,18 +1,32 @@
 # 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."
 
 ---
 
-## 1. Command Inventory (53 commands)
+## 1. Command Inventory (56 commands)
 
 ```
-analysis, analysis-jira, analysis-resolve, autopilot, build-optimize, channels,
-complaint-analysis, create-jira, design-check, doctor, diff-explain, feedback,
-forget, garbage-collect, graph, help, ios-coding-standard, issue, jira,
-kill, language, local, local-autopilot, log, manual-test, prune-logs,
+analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
+autopilot-on, autopilot-status, build-optimize, channels, complaint-analysis,
+create-jira, design-check, diff-explain, doctor, feedback, forget,
+garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
+language, local, local-autopilot, log, manual-test, prune-logs,
 prune-prompts, purge, refactor, resume, resume-local, review,
 review-analysis, review-issue, review-jira, routines, save, scan, search,
 setup, stack, status, steer, store-ready, sync, test, test-accessibility,
@@ -263,6 +277,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
@@ -337,6 +380,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/design-conformance.md

@@ -1,5 +1,15 @@
 # Design conformance  -  the component walk, and why a glance is not a pass
 
+<!-- toc -->
+- [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

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

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,
@@ -59,19 +71,31 @@ EVIDENCE_PLATFORM=""
 case " $MA_STACKS " in
   *" ios "*)     EVIDENCE_PLATFORM=ios ;;
   *" android "*) EVIDENCE_PLATFORM=android ;;
+  *" web "*)     EVIDENCE_PLATFORM=web ;;
 esac
 ```
 
 iOS wins a tie, and the tie is recorded in `stackWhy`: `simctl` discovery is the
 cheaper of the two, and a repo that is honestly both gets the same answer on
-every run rather than one that depends on ordering.
-
-**An empty value is a real outcome, not an error.** A web or backend repo has no
-simulator to probe, and `probe-evidence-capability.sh` rejects anything but
-`ios|android` with exit 2. So when `EVIDENCE_PLATFORM` is empty the probe **does
-not run**, `platform` is written as `web` or `other` from `MA_STACKS`, and the
+every run rather than one that depends on ordering. Web is last for the same
+reason and not because it is lesser: a repo that is both iOS and web is a mobile
+app with a marketing site, and the screen the ticket is about is the mobile one.
+
+**Web is a device platform here.** It was not until v17.1.0, and the omission was
+not a decision anyone made: `run-ui-tests.sh` rejected everything but
+`ios|android`, so a repo with a full Playwright suite reported "no UI test
+target". The PR body then said UI tests had not run, which was true of the runner
+and false of the repo - the exact shape of claim this file exists to prevent. The
+browser is the device, the runner is the recorder (both Playwright and Cypress
+write their own video), and `npx --no-install` is what keeps a probe from
+installing one behind the user's back.
+
+**An empty value is still a real outcome, not an error.** A backend-only repo has
+nothing to probe, and `probe-evidence-capability.sh` rejects anything but
+`ios|android|web` with exit 2. So when `EVIDENCE_PLATFORM` is empty the probe
+**does not run**, `platform` is written as `other` from `MA_STACKS`, and the
 reason goes to `state.evidenceCapability.skippedReason` in the probe's own
-`*_REASON` idiom - "no device platform in stacks [web backend]". Passing an empty
+`*_REASON` idiom - "no device platform in stacks [backend]". Passing an empty
 string instead is what the probe's exit 2 exists to refuse, and swallowing that
 exit would turn a missing value into a silent skip.
 
@@ -210,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

@@ -598,7 +598,7 @@ Decide, then probe, then ask, then run. Skipped only when `visualEvidence.enable
 ```bash
 eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"
 EVIDENCE_PLATFORM=""
-case " $MA_STACKS " in *" ios "*) EVIDENCE_PLATFORM=ios ;; *" android "*) EVIDENCE_PLATFORM=android ;; esac
+case " $MA_STACKS " in *" ios "*) EVIDENCE_PLATFORM=ios ;; *" android "*) EVIDENCE_PLATFORM=android ;; *" web "*) EVIDENCE_PLATFORM=web ;; esac
 if [ -n "$EVIDENCE_PLATFORM" ]; then
   eval "$(bash $HOME/.claude/scripts/probe-evidence-capability.sh \
     --platform "$EVIDENCE_PLATFORM" --repo "$WORKTREE" \
@@ -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.