@mmerterden/multi-agent-pipeline 17.1.0 → 17.3.0

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."
@@ -264,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
@@ -338,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,
@@ -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.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"],