@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

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

@@ -14,7 +14,7 @@
 - [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)".
+> **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-2-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

@@ -19,16 +19,16 @@ Standalone audit commands  -  runs directly via Bash, **no MCP server dependency
 **These audits are on-demand.** They run when:
 
 1. User explicitly requests: `/multi-agent test "accessibility"`, `/multi-agent test "store-ready"`
-2. User asks during Phase 5: "run accessibility audit", "check store compliance"
+2. User asks during the Phase 3 user test: "run accessibility audit", "check store compliance"
 3. Pipeline suggests and user confirms: "UI changes detected  -  want to run accessibility audit?"
 
-**Pipeline never runs audits without user intent.** Phase 4 does code-level review (free, automatic). Phase 5 does device-level audit only when requested.
+**Pipeline never runs audits without user intent.** Phase 3 does code-level review (free, automatic) and the device-level audit only when requested - both live in Review now, at different steps, which is why "Review ran" does not mean a device was touched.
 
 ---
 
 ### iOS Accessibility Audit
 
-**When**: Phase 5  -  user requests, app is running on simulator
+**When**: Phase 3 user test  -  user requests, app is running on simulator
 **What it checks**: Missing labels, small tap targets (<44pt), missing identifiers
 
 **How to run** (requires ui-tree-dumper.swift in project or ~/.claude/scripts/):
@@ -73,7 +73,7 @@ Accessibility Audit:
 
 ### Android Accessibility Audit
 
-**When**: Phase 5  -  user requests, app is running on emulator
+**When**: Phase 3 user test  -  user requests, app is running on emulator
 **What it checks**: Missing contentDescription, small touch targets (<48dp), missing resource-id
 
 ```bash
@@ -98,7 +98,7 @@ cat /tmp/_audit_ui.xml
 
 ### iOS Biometric Test
 
-**When**: Phase 5  -  auth flow testing
+**When**: Phase 3 user test  -  auth flow testing
 
 ```bash
 DEVICE_ID=$(xcrun simctl list devices booted -j | python3 -c "import sys,json; devs=json.load(sys.stdin)['devices']; print(next(d['udid'] for ds in devs.values() for d in ds if d['state']=='Booted'))")
@@ -119,7 +119,7 @@ xcrun simctl keychain $DEVICE_ID biometric-match --face --no-match
 
 ### Android Launch Time
 
-**When**: Phase 5  -  performance baseline
+**When**: Phase 3 user test  -  performance baseline
 
 ```bash
 # Force stop first (cold start)
@@ -143,7 +143,7 @@ adb shell am start -W -n {package_name}/.MainActivity 2>&1
 
 ### iOS Archive Audit (App Store Compliance)
 
-**When**: Phase 6  -  release branches only, user confirms
+**When**: Phase 4  -  release branches only, user confirms
 **Input**: Path to .xcarchive
 
 ```bash
@@ -198,7 +198,7 @@ ls "$APP_DIR/Frameworks/" 2>/dev/null
 
 ### Android APK Audit (Play Store Compliance)
 
-**When**: Phase 6  -  release branches only, user confirms
+**When**: Phase 4  -  release branches only, user confirms
 **Input**: Path to .apk
 
 ```bash
@@ -238,11 +238,11 @@ unzip -l "$APK" 2>/dev/null | grep "classes.*\.dex" | wc -l
 
 | Phase            | What Happens                                        | Method                          |
 | ---------------- | --------------------------------------------------- | ------------------------------- |
-| Phase 4 (Review) | Accessibility check  -  **code-level only**           | AI reads source code, no device |
-| Phase 5 (Test)   | Accessibility audit  -  **device-level, on-demand**   | Bash commands above             |
-| Phase 5 (Test)   | Biometric test  -  **on-demand**                      | `xcrun simctl keychain`         |
-| Phase 5 (Test)   | Launch time  -  **on-demand**                         | `adb shell am start -W`         |
-| Phase 6 (Commit) | Archive/APK audit  -  **release branches, on-demand** | Bash commands above             |
+| Phase 3 (Review)      | Accessibility check  -  **code-level only**           | AI reads source code, no device |
+| Phase 3 (user test)   | Accessibility audit  -  **device-level, on-demand**   | Bash commands above             |
+| Phase 3 (user test)   | Biometric test  -  **on-demand**                      | `xcrun simctl keychain`         |
+| Phase 3 (user test)   | Launch time  -  **on-demand**                         | `adb shell am start -W`         |
+| Phase 4 (Commit)      | Archive/APK audit  -  **release branches, on-demand** | Bash commands above             |
 
 ### Graceful Degradation
 

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

@@ -124,10 +124,10 @@ Token resolution: `gh auth status` for the active GitHub account selected in Pha
 
 ## Pairing with the Progress flag updater
 
-Every issue comment post is paired with `$HOME/.claude/scripts/update-issue-progress.sh "$TASK_ID"` in the same Phase 7 step. Order: comment FIRST (so the timestamp marks the run), flags SECOND (so the body diff is one logical change).
+Every issue comment post is paired with `$HOME/.claude/scripts/update-issue-progress.sh "$TASK_ID"` in the same Phase 5 step. Order: comment FIRST (so the timestamp marks the run), flags SECOND (so the body diff is one logical change).
 
 ```bash
-# Phase 7 Step 5  -  issue channel
+# Phase 5 Step 5  -  issue channel
 gh issue comment "$ISSUE_NUMBER" --repo "$ORG/$REPO" --body-file /tmp/channels-$TASK_ID-issue.md
 bash $HOME/.claude/scripts/update-issue-progress.sh "$TASK_ID"
 ```

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

@@ -42,7 +42,7 @@ it is the PR body (`channels/pr.md`).
 
 **`summary`**  -  2-5 sentences in `outputLanguage`. What changed, why, and the user-visible impact. No "we", no marketing tone. Past tense (the work is done at the time the comment goes up).
 
-**Visual evidence inside these sections.** When `state.visualEvidence` carries artefacts, they render INSIDE `summary` and `test_scenarios` - never as a section of their own, which the fixed section order forbids. Phase 6 Step 2.9 has already uploaded them and written the returned name to `visualEvidence.*[].jiraFilename`: reference that name, and call `jira-attach.sh <issue> <file>...` only for an artefact whose `jiraFilename` is absent. Uploading unconditionally here attaches every file a second time whenever the comment is re-rendered - which is exactly what a post-hoc `/multi-agent:channels` run does.
+**Visual evidence inside these sections.** When `state.visualEvidence` carries artefacts, they render INSIDE `summary` and `test_scenarios` - never as a section of their own, which the fixed section order forbids. Phase 4 Step 2.9 has already uploaded them and written the returned name to `visualEvidence.*[].jiraFilename`: reference that name, and call `jira-attach.sh <issue> <file>...` only for an artefact whose `jiraFilename` is absent. Uploading unconditionally here attaches every file a second time whenever the comment is re-rendered - which is exactly what a post-hoc `/multi-agent:channels` run does.
 
 - `summary`, after its sentences: one line naming the pair in `outputLanguage` (`Düzeltme öncesi / Düzeltme sonrası`), then the thumbnails on the next line - `!<file>-before.png|thumbnail! !<file>-after.png|thumbnail!`.
 - `test_scenarios`, under the scenario the recording demonstrates: `!<file>-flow.mp4!` plus one line stating the tier used.
@@ -191,7 +191,7 @@ The adapter prepends the linked PR URL on the **first line** so reviewers can ju
 ```
 PR: https://github.com/<org>/<repo>/pull/4321
 
-Phase 4 review accepted 2 findings...
+Phase 3 review accepted 2 findings...
 ```
 
 In multi-repo mode, `channels-multi-repo.sh render-jira <state> <body>` prepends a bulleted `* PR:` list  -  primary first, extras after. Single-repo tasks fall through to the unchanged body.
@@ -255,6 +255,6 @@ When the **Wiki** adapter writes pages on the same run AND `prefs.global.wikiToJ
 - UTF-8 in, UTF-8 out  -  the body file is UTF-8 and `--data-binary` ships its bytes verbatim. Never round-trip the body through `unicode_escape`, `latin-1`, or any re-encode step, and never hand-roll a Python/curl helper that re-decodes it: that mangles Turkish chars (ç ş ı ö ü ğ) into mojibake (`Çözüm` → `Ãözüm`). Use the `jq --rawfile` + `--data-binary @file` path above as-is. Same rule for the PR / Confluence / Wiki adapters.
 - Section order is fixed: `summary` → `test_scenarios` → `context_refs`. Never insert sections between them; never reorder.
 - Humanizer pass runs **after** body assembly and **before** wiki-markup conversion. Tone target: informal but technical. No marketing voice, no "we are excited", no "I have...".
-- **No decorative glyphs anywhere in the comment body**  -  neither emotive (    ) nor status glyphs ([done] [pending] failed skipped active ). The comment is plain technical prose. Status is written in words: `[done]` / `[pending]`, and `done · active · failed · skipped · pending` in the phase strip. This applies to every channel, not only Jira  -  see `channels/README` note in `phase-7-report.md`.
+- **No decorative glyphs anywhere in the comment body**  -  neither emotive (    ) nor status glyphs ([done] [pending] failed skipped active ). The comment is plain technical prose. Status is written in words: `[done]` / `[pending]`, and `done · active · failed · skipped · pending` in the phase strip. This applies to every channel, not only Jira  -  see `channels/README` note in `phase-5-report.md`.
 - Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, type names, branch names, and the wiki-markup syntax stay verbatim. The `promptLanguage="en"` lock means any LLM prompt that produces the body is in English; the body itself is then rendered in the user's language.
 - Adapter failures are non-blocking  -  a missing token or 401 returns `skipped`/`failed`, the loop keeps going for PR / Confluence / Wiki.

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

@@ -45,7 +45,7 @@ all - it is the section whose absence over there is the point.
 
 **`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.
 
-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:
+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 2 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
@@ -135,7 +135,7 @@ The base sha matters because "it builds" is a claim about a merge base, and the
 
 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:
+**`risk`**  -  only when `state.diffRisk.signals` (Phase 3 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 4 Step 3 blocker:
 
 ```markdown
 ## Risk and Security
@@ -146,7 +146,7 @@ Pick commands for the project's stack  -  the pipeline supports iOS (Swift/Xcode
 - Rollback: feature flag <name> | git revert <sha> | none, and why
 ```
 
-**`visuals`**  -  only when `state.visualEvidence.required`. What this section can show depends on where the artefacts are hosted, which Phase 6 resolves into `state.visualEvidence.host`. Render the form for that host and no other.
+**`visuals`**  -  only when `state.visualEvidence.required`. What this section can show depends on where the artefacts are hosted, which Phase 4 resolves into `state.visualEvidence.host`. Render the form for that host and no other.
 
 **`host: jira`.** Filenames, never URLs. A Jira attachment URL is auth-gated and renders as a broken image for anyone reading the PR outside a Jira session, and a broken image is worse than a filename because it looks like the evidence is missing.
 
@@ -192,7 +192,7 @@ Pick commands for the project's stack  -  the pipeline supports iOS (Swift/Xcode
 
 **Video is Jira-only.** On a GitHub-hosted run no recording is made and none is published: an mp4 behind a blob link is a download, not something a reviewer opens mid-review, and paying for a recording nobody watches is worse than saying plainly that there is none. The gap line carries that reason.
 
-Every `state.visualEvidence.gaps[]` entry becomes its own line with the reason instead of a filename (`- Before: none  -  the ticket carries no image attachment`). Phase 6 Step 3 blocks on a required artefact that is neither listed nor explained. Contract: `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
+Every `state.visualEvidence.gaps[]` entry becomes its own line with the reason instead of a filename (`- Before: none  -  the ticket carries no image attachment`). Phase 4 Step 3 blocks on a required artefact that is neither listed nor explained. Contract: `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
 
 **`dependencies`**  -  only when `Package.swift` / `Podfile` / `build.gradle` / `package.json` changed. Each entry: `package@old → new  -  reason`.
 

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

@@ -64,4 +64,4 @@ Adapter implementation chooses the right git push target + commit message format
 - Screenshots cover light/dark + LTR/RTL  -  wiki adapter refuses to commit if any quadrant is missing.
 - Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, type names, design token names, and Markdown formatting stay verbatim across languages (wiki pages are `.md` files  -  "wiki markup" in this doc set means Jira's dialect, which never appears here). The template (this doc) is English because `promptLanguage="en"` is locked.
 - No decorative/emotive emoji or smileys (    ) in the page prose. Only functional/structural marks a fixed template defines are allowed.
-- Autopilot always pauses at the channels menu (per `phase-7-report.md` autopilot contract)  -  even in autopilot mode the user gets to confirm wiki scope.
+- Autopilot always pauses at the channels menu (per `phase-5-report.md` autopilot contract)  -  even in autopilot mode the user gets to confirm wiki scope.

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

@@ -13,7 +13,7 @@
 
 > **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.
+This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-2-dev.md`. Keeping it separate lets `phase-2-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.
 
 ## Entry conditions
 
@@ -122,9 +122,9 @@ On failure (the plugin skill returns an unrecoverable build/test error, or the d
 
 ## Short-run behaviour
 
-When the Phase 0 Step 7.5 depth picker answered Short (`state.onlyDevelop === true`), the dispatch layer passes `mode: "dev"` so the plugin skill can elide unit tests and wiki (structural + snapshot still required; wiki deferred to Phase 7). If the plugin does not honor a `mode` hint, dispatch simply skips the post-build wiki step itself.
+When the Phase 0 Step 7.5 depth picker answered Short (`state.onlyDevelop === true`), the dispatch layer passes `mode: "dev"` so the plugin skill can elide unit tests and wiki (structural + snapshot still required; wiki deferred to Phase 5). If the plugin does not honor a `mode` hint, dispatch simply skips the post-build wiki step itself.
 
-Phase 4 runs in a Short run as it does in a Full one, and its reviewer count is **not** Phase 3's concern  -  the Step 1.77 scope gate decides that from diff risk, independently of `mode`. What the dispatch layer owes Phase 4 is the record of which plugin skill it delegated to, appended to `state.telemetry.skillCalls[]`, so the review can check the delivered component against the criteria that skill imposes.
+Phase 3 runs in a Short run as it does in a Full one, and its reviewer count is **not** Phase 3's concern  -  the Step 1.77 scope gate decides that from diff risk, independently of `mode`. What the dispatch layer owes Phase 4 is the record of which plugin skill it delegated to, appended to `state.telemetry.skillCalls[]`, so the review can check the delivered component against the criteria that skill imposes.
 
 ## Cross-CLI behaviour (intentional divergence)
 

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

@@ -1,9 +1,10 @@
 # Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
 <!-- toc -->
-- [1. Command Inventory (56 commands)](#1-command-inventory-56-commands)
+- [1. Command Inventory (60 commands)](#1-command-inventory-60-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)
+- [2.7 One command, three different meanings: `/multi-agent:model`](#27-one-command-three-different-meanings-multi-agentmodel)
 - [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)
@@ -19,16 +20,17 @@
 
 ---
 
-## 1. Command Inventory (56 commands)
+## 1. Command Inventory (60 commands)
 
 ```
 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,
+language, local, local-autopilot, log, manual-test, model, prune-logs,
 prune-prompts, purge, refactor, resume, resume-local, review,
-review-analysis, review-issue, review-jira, routines, save, scan, search,
+review-analysis, review-issue, review-jira, route-off, route-on,
+route-status, routines, save, scan, search,
 setup, stack, status, steer, store-ready, sync, test, test-accessibility,
 test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation,
 uninstall, update
@@ -199,7 +201,7 @@ on skill directories would demand exactly the layout that breaks it.
 
 **What must stay identical** (byte-level) across the two files:
 
-- Phase canonical labels (Phase 0-7)
+- Phase canonical labels (Phase 0-5)
 - Input parsing table (Section 5 of this doc)
 - Routing decisions for each input type
 - Placeholder vocabulary (Section 2 of this doc)
@@ -216,7 +218,7 @@ Future changes that break an item in the "stay identical" list must update **bot
 
 ### Panel diversity per host
 
-Phase 4 runs three reviewers everywhere, but the diversity those three buy is not the
+Phase 3 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
@@ -236,6 +238,29 @@ members available there are closer to each other than Fable and Sonnet are. That
 weaker axis, not an equivalent one, and treating it as equivalent is the error this
 section exists to prevent.
 
+## 2.7 One command, three different meanings: `/multi-agent:model`
+
+Most commands do the same thing on all three hosts. This one does not, and the
+divergence is stated here rather than discovered at runtime, because a command
+that quietly no-ops is worse than one that says it cannot act.
+
+| Host | What `model on|off` does | Why |
+|---|---|---|
+| Claude Code | live switch: flips `modelFallback.fableEnabled` and realigns `costBudget.pricingModel` | the only host where the `fable` rung is Fable 5 |
+| Copilot CLI | writes the preference, changes no dispatch | Fable 5 is not offered there; its personas never sat on this rung |
+| Codex CLI | writes the preference, changes no dispatch, **deliberately** | the `fable` rung on Codex means `gpt-5.6 @ xhigh` - a different model on a different account. A knob named after an Anthropic model must not silently retune a Codex run |
+
+`model-rung.sh` prints which of the three it is on every invocation. The rule it
+follows: report the host's actual behaviour, never claim a change that did not
+happen.
+
+The routing trio (`route-on`, `route-off`, `route-status`) has no such split -
+it writes `prefs.global.modelRouting` identically everywhere. Its honest limit is
+different and applies on every host: a subagent cannot be dispatched to a
+non-Anthropic model, because subagent dispatch belongs to the host. External
+providers are reachable only where the pipeline makes the HTTP call itself
+(`bulk-read.sh`, `research_ask`). `route-status` prints that on every run.
+
 ## 3. Frontmatter Transform Rules (Claude ↔ Copilot)
 
 Each file has a different frontmatter schema. The sync flow transforms between them:

package/pipeline/multi-agent-refs/features/autopilot-circuit-breaker.md

@@ -1,6 +1,15 @@
 # Feature: Autopilot Circuit-Breaker
 
-**Pattern**: autopilot runs with zero interaction, which is exactly when a silent failure loop is most expensive  -  an agent can burn a budget re-attempting the same broken fix, or thrash between two phases, with nobody watching. A circuit-breaker converts "keep going no matter what" into "keep going until a defined unsafe condition, then halt and hand back to the user." This is the sanctioned autopilot pause (same class as the Phase 7 channels pause): the run stops, records why, and waits for an explicit `resume`.
+<!-- toc -->
+- [Trip conditions](#trip-conditions)
+- [Wiring status](#wiring-status)
+- [Action on trip](#action-on-trip)
+- [Why this is the right autopilot exception](#why-this-is-the-right-autopilot-exception)
+- [The runner-level breaker (a different failure, a different layer)](#the-runner-level-breaker-a-different-failure-a-different-layer)
+- [Two more things a long-running runner needs](#two-more-things-a-long-running-runner-needs)
+<!-- /toc -->
+
+**Pattern**: autopilot runs with zero interaction, which is exactly when a silent failure loop is most expensive  -  an agent can burn a budget re-attempting the same broken fix, or thrash between two phases, with nobody watching. A circuit-breaker converts "keep going no matter what" into "keep going until a defined unsafe condition, then halt and hand back to the user." This is the sanctioned autopilot pause (same class as the Phase 5 channels pause): the run stops, records why, and waits for an explicit `resume`.
 
 **Gated by `prefs.global.autopilotCircuitBreaker`** (`enabled` default true, `identicalFindingCycles` default 2, `maxReworkCycles` default 3; `schemas/prefs.schema.json`). Halting is always safe, so the breaker itself defaults on. Disable per-run only with an explicit override. Complements, does not replace, the existing autopilot safety rules (build-fail max 3 retries, Phase 4 blocking-finding rework, destructive-op confirmations).
 
@@ -14,7 +23,7 @@ Any one trips the breaker. All are evaluated from `agent-state.json` + telemetry
 | 2 | **Identical repeated failure** | same normalized build-error signature, or the same Phase 4 finding fingerprint, recurs across consecutive Phase 3 rework cycles | 2 cycles |
 | 3 | **Rework storm** | Phase 4 -> Phase 3 rework cycles exceed the cap (distinct from the build-retry cap) | `maxReworkCycles` = 3 |
 | 4 | **Cost drift** | cumulative spend crosses the `costBudget` ceiling, or the projected next-phase spend would exceed it, after model-fallback has already downgraded | `costBudget` ceiling |
-| 5 | **Merge/rebase conflict** | Phase 6 push blocked by a conflict that requires history reconciliation | any conflict |
+| 5 | **Merge/rebase conflict** | Phase 4 push blocked by a conflict that requires history reconciliation | any conflict |
 
 Trigger 2 is the key addition over the plain build-retry cap: a build can "fail differently" three times (legitimate iteration) or "fail identically" twice (stuck). Only the identical-failure case is a stall; the retry cap catches the rest.
 
@@ -22,12 +31,12 @@ Trigger 2 is the key addition over the plain build-retry cap: a build can "fail
 
 | Trigger | Evaluated by | Status |
 |---|---|---|
-| 2, finding half | `review-delta.mjs` exit 3 at Phase 4 Step 3.8: a blocking/important finding whose `fingerprint` (finding-fingerprint.mjs) stays in the accepted set for `identicalFindingCycles` consecutive rounds | **code** (v16.20.0) |
+| 2, finding half | `review-delta.mjs` exit 3 at Phase 3 Step 3.8: a blocking/important finding whose `fingerprint` (finding-fingerprint.mjs) stays in the accepted set for `identicalFindingCycles` consecutive rounds | **code** (v16.20.0) |
 | 3 | Phase 3 re-entry item 6: the `retryCount === 3` hard-kill records the trip | **code** (v16.20.0) |
 | 2, build-error half | needs a build-log signature normaliser | documented behaviour, no script yet |
 | 1 | needs checkpoint-to-checkpoint artifact diffing | documented behaviour, no script yet |
 | 4 | belongs to `cost-budget-check.mjs` | documented behaviour, no script yet |
-| 5 | Phase 6 push | documented behaviour, no script yet |
+| 5 | Phase 4 push | documented behaviour, no script yet |
 
 State shape: `state.circuitBreaker = {tripped, trigger, detail, checkpoint: {phase, step, iteration}, trippedAt, counters: {identicalFindingCycles, reworkCycles}}` (`schemas/agent-state.schema.json`). The per-round classification the finding half reads lives in `state.reviewIterations[i].delta` (`new`, `stillPresent`, `resolved`, `downgraded`, `recurrence`, `plateau`). `smoke-autopilot-circuit-breaker.sh` asserts the schema fields, the scripts and the phase wiring, not only this prose.
 
@@ -43,3 +52,64 @@ State shape: `state.circuitBreaker = {tripped, trigger, detail, checkpoint: {pha
 Autopilot's contract is "no interaction on the happy path." The circuit-breaker fires only off the happy path, where continuing unattended is the *less* safe choice: repeating a proven-broken action, or spending past a ceiling the user set, is not autonomy, it is a runaway. Halting with a precise reason is cheaper than the tokens (and trust) a silent loop burns.
 
 Inspired by autonomous-loop operators that gate on explicit stop conditions (no-progress, identical-stack-trace repetition, cost drift, conflict blocking), adapted to this pipeline's phase/rework/state model.
+
+## The runner-level breaker (a different failure, a different layer)
+
+Everything above is the IN-RUN breaker: one run, one state file, triggers that
+mean "this task is not converging". It cannot see the failure a server actually
+hits, which is not about any one task.
+
+An expired token, a `claude` binary that no longer launches, a full disk: every
+item fails identically, a few minutes apart, until the queue is empty. Nothing
+above notices, because each individual run failed for its own apparently local
+reason. What is left afterwards is a ledger of failures with no indication of
+which came first and no queue to resume.
+
+`autopilot-runner.mjs` therefore refuses to take NEW work after
+`MA_AP_BREAKER_LIMIT` consecutive attempts produced nothing (default 3, zero
+disables). The count is CONSECUTIVE and read from `attempted.jsonl` rather than
+kept as a counter, because a counter is a second piece of state that can
+disagree with the ledger - and the ledger is what a person reads when they ask
+why the runner stopped.
+
+Two outcomes are deliberately not failures:
+
+- `needs-input` is a run that did its work and is waiting for a person. That is
+  the system behaving correctly, and counting it would stop a machine whose only
+  problem is that somebody has not answered yet.
+- `blocked-*` items never ran at all - arming refused them - so they say nothing
+  about whether a run would have worked.
+
+When it opens, the reason goes into `queue.json.blockedReason` (so
+`autopilot-status` shows it rather than reporting an idle queue), a
+`breaker-open` line goes into `ticks.jsonl`, and the log names the outcome that
+opened it plus the override.
+
+It is HALF-OPEN rather than latched, and that distinction is load-bearing. The
+breaker returns before the only writer of `attempted.jsonl`, so a version that
+simply stopped could never record another attempt, the consecutive count could
+never fall, and the runner would be off for good - while its own log said
+"until an attempt succeeds". After `MA_AP_BREAKER_COOLDOWN_SEC` (30 min by
+default) one probe is let through: a recovered machine succeeds and the count
+resets on its own, and a still-broken one fails, becomes the newest attempt, and
+closes the breaker for another cooldown. One wasted run per cooldown is the
+price of not needing a person to notice.
+
+## Two more things a long-running runner needs
+
+**The log.** launchd appends the runner's stdout to `runner.log` forever. On a
+laptop that file is never read; on a machine ticking every few minutes for
+months it is what fills the disk, and a full disk stops the runs the log existed
+to record. Each tick truncates it past `MA_AP_LOG_MAX_BYTES` (default 5MB),
+keeping the last 256KB in `runner.log.1`.
+
+Truncating the same inode is the mechanism, not renaming: launchd holds the file
+open with `O_APPEND`, so a rename leaves that descriptor writing into the renamed
+file while the new one stays empty forever. That is the rotation that looks
+correct and silently stops logging.
+
+**Telemetry.** `ticks.jsonl` gets one JSON line per tick - what the tick did,
+what it took, what came out, how many consecutive failures preceded it. The
+human log answers "what happened just now"; this answers "how has this been
+behaving for a week", which is the question a server raises and prose cannot be
+asked.

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

@@ -1,8 +1,8 @@
-## Code Graph (Phase 1 Step 2.6 + Phase 7 Step 3)
+## Code Graph (Phase 1 Step 2.6 + Phase 5 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)
+- [Phase 5 Step 3  -  refresh after the branch changed code](#phase-5-step-3---refresh-after-the-branch-changed-code)
 - [What the report answers that a file-level view cannot](#what-the-report-answers-that-a-file-level-view-cannot)
 - [The graph is drawable, and one place already asks for it](#the-graph-is-drawable-and-one-place-already-asks-for-it)
 <!-- /toc -->
@@ -10,7 +10,7 @@
 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
-Phase 7 behave exactly as they did before. Design, trade and measurements:
+Phase 5 behave exactly as they did before. Design, trade and measurements:
 `docs/adr/0010-own-code-graph.md`.
 
 ### Phase 1 Step 2.6  -  query before dispatching Explore
@@ -38,7 +38,7 @@ at a graph that was never built. Pass it.
 
 Build when there is no graph at all, and when `baseCommit` no longer matches
 HEAD. The missing case is the one that matters in practice: `architecture.md`
-and its siblings are written in Phase 7, which is the phase a run is least
+and its siblings are written in Phase 5, which is the phase a run is least
 likely to reach, so a repo can have a long history of tasks and an empty
 knowledge directory. The graph must not inherit that. `--status` exits 1 on a
 missing file, and that exit means build, not skip.
@@ -56,7 +56,7 @@ already spells out. Measured on a 4,300-file Swift app at a fixed 30k retrieval
 budget, it roughly doubled coverage at under half the cost on domain-word
 questions and lost narrowly to `grep -lw` on exact type names.
 
-### Phase 7 Step 3  -  refresh after the branch changed code
+### Phase 5 Step 3  -  refresh after the branch changed code
 
 Runs when `prefs.global.codeGraph.enabled` and `prefs.global.codeGraph.autoRefresh`
 are both true.

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

@@ -0,0 +1,93 @@
+# cost analysis - projection, anomaly, burn, diff
+
+`cost-budget-check.mjs` answers one question, live, for one run: is THIS task
+about to cross its ceiling. Two ways a budget actually empties are invisible to
+it. A slow drift never trips any single run's ceiling. And one pathological
+session can burn a week's worth in an hour while every individual run stays
+comfortably under its cap.
+
+`cost-analyze.mjs` answers the other four questions off one series.
+
+| Sub-command | Question |
+|---|---|
+| `projection` | at this rate, what does a week / a month / a quarter cost, and when does a stated budget run out |
+| `anomaly` | which day or session is out of family |
+| `burn` | is the last day accelerating against the preceding week |
+| `diff` | two saved snapshots, side by side |
+
+```bash
+node "$HOME/.claude/scripts/cost-analyze.mjs" projection --days 14 [--monthly-usd 200]
+node "$HOME/.claude/scripts/cost-analyze.mjs" anomaly --days 30 [--by day|session] [--threshold 3.5]
+node "$HOME/.claude/scripts/cost-analyze.mjs" burn [--factor 3]
+node "$HOME/.claude/scripts/cost-analyze.mjs" --save [--days 30]
+node "$HOME/.claude/scripts/cost-analyze.mjs" diff [a.json b.json]
+```
+
+Exit 0 means nothing to report, 10 means a finding, 2 is a usage error. Every
+sub-command takes `--json`, and the human output and the JSON are rendered from
+the same numbers.
+
+## Where the numbers come from, and what that makes them worth
+
+The per-run token accumulators in `tracker-state.json` are the pipeline's own
+ledger, and they are the obvious source. They are also empty: the schema has
+`tokens_in` / `tokens_out` / `tokens_cached` per phase, they are written only
+when a phase reports them, and on a real machine no tracker carries them at all.
+
+The series that does exist is the host's own transcripts, one usage record per
+assistant turn, under `~/.claude/projects/<slug>/<session>.jsonl`. So that is
+what this reads, and three consequences follow that are stated here rather than
+discovered later:
+
+- It covers everything Claude Code did on this machine, not only pipeline runs.
+- The figures are ESTIMATES priced from `cost-table.json`, at LIST price. On a
+  subscription they are the right number for comparing one day to another and
+  the wrong number to call a bill. The human output says so on every run.
+- A host with no such transcripts (Copilot, Codex) reports `UNMEASURED`, never
+  zero. Zero would read as "you spent nothing" when it means "I could not see".
+
+Records whose model is not in `cost-table.json` are COUNTED as unpriced and left
+out of the total. Folding them in at zero would make an unknown model look free,
+which is the direction that hurts.
+
+Cache writes are priced at 1.25x input, derived rather than read from the table,
+because `cost-table.json` carries a cache READ rate only. Dropping the component
+would make every long-context session look cheap.
+
+## Why the median and the MAD, not the mean
+
+The single expensive session `anomaly` exists to find is also the observation
+that inflates a mean and a standard deviation - it hides inside the statistic
+measured against it. With six ordinary days and one at fifty times the rest, a
+mean-based z-score puts the outlier at about 2.3 sigma, under every usual
+threshold. The median does not move for one observation, and neither does the
+median absolute deviation.
+
+The score is the modified z-score of Iglewicz and Hoaglin, `0.6745 * (x - median)
+/ MAD`, flagged at 3.5.
+
+When more than half the values are identical the MAD is zero. That is not an
+error and not a licence to divide by zero: the published fallback is the mean
+absolute deviation scaled by 1.253314. When THAT is zero too there is no
+dispersion at all, and the honest answer is that no anomaly can be called -
+which is what it says.
+
+Fewer than five points is refused outright, with the number it needs.
+
+## Why projection divides by the calendar window
+
+Total over the window, divided by the WINDOW, not by the days that happen to
+have data. Dividing by active days answers a different question - what a working
+day costs - and then projecting a month as thirty working days overstates it by
+roughly a third.
+
+`--monthly-usd` is optional and there is no default. Without it the projection
+is reported and the exhaustion date is not, with the reason given. Inventing a
+budget to compare against would produce a number that looks measured.
+
+## Snapshots
+
+`--save` writes `~/.claude/state/cost/<iso>.json`: the window, the total, the
+per-day rate and the per-day breakdown. `diff` compares two, by path or the last
+two by default, and says when the windows differ - the per-day rate is
+comparable across different windows, the total is not.

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

@@ -21,7 +21,7 @@ Derived generically from an upstream corporate screen-QA tool (recorded in
 catalogs and product examples are not, and were not taken - section 7 says what
 replaces them.
 
-Consumers: `/multi-agent:design-check` (the runner), Phase 4 review when a UI
+Consumers: `/multi-agent:design-check` (the runner), Phase 3 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`.
 

package/pipeline/multi-agent-refs/features/dev-critic.md

@@ -1,6 +1,6 @@
-# Feature: Dev Critic (Phase 3 Step 3.5 Evaluator-Optimizer)
+# Feature: Dev Critic (Phase 2 Step 3.5 Evaluator-Optimizer)
 
-**Pattern**: Anthropic's evaluator-optimizer from "Building Effective Agents" (Dec 2024). Generator (Phase 3 Dev) and critic (`agents/dev-critic.md`) loop on deterministic criteria already written in `rules/*.md` before any Phase 4 reviewer call.
+**Pattern**: Anthropic's evaluator-optimizer from "Building Effective Agents" (Dec 2024). Generator (Phase 2 Dev) and critic (`agents/dev-critic.md`) loop on deterministic criteria already written in `rules/*.md` before any Phase 3 reviewer call.
 
 **Gated by `prefs.global.devCritic.enabled`** (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4:
 
@@ -25,7 +25,7 @@
 
 ## Telemetry
 
-Each critic call emits `dev_critic.call` with `iteration`, `pass`, `gates_failed`, `blocking`, `important`, `duration_ms`, `tokens_in/out`. Phase 7 cost rollup lists these as `phase 3.5` line items so the net saving (Phase 4 reviewer/triage calls avoided) is measurable.
+Each critic call emits `dev_critic.call` with `iteration`, `pass`, `gates_failed`, `blocking`, `important`, `duration_ms`, `tokens_in/out`. Phase 5 cost rollup lists these as `phase 3.5` line items so the net saving (Phase 3 reviewer/triage calls avoided) is measurable.
 
 ## Off by default reason
 

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

@@ -8,6 +8,7 @@
 - [The line shape](#the-line-shape)
 - [It recommends, it never fixes](#it-recommends-it-never-fixes)
 - [Checks](#checks)
+- [The server profile (`--profile=server`)](#the-server-profile---profileserver)
 <!-- /toc -->
 
 Every check `/multi-agent:doctor` can report has a `### <id>` heading here, and
@@ -152,7 +153,7 @@ after the user has already answered the pickers.
 ### identity
 
 A git identity resolves for the account the run would commit as. WARN: the run
-reaches Phase 6 and stops there.
+reaches Phase 4 and stops there.
 
 ### hook-coverage
 
@@ -245,10 +246,54 @@ file it was writing at the time.
 
 Worktrees left under `<repo>/.worktrees/` in the repository the caller is
 standing in. WARN at five or more, or at 2 GB. A finished task removes its own
-worktree at PR time, but a run that stops before Phase 6 never reaches that
+worktree at PR time, but a run that stops before Phase 4 never reaches that
 step and nothing else collects it: the finalizer only runs on success, and
 `gc-worktrees` only sweeps entries git has already forgotten. Each survivor is
 a full second checkout, so the total is measured in gigabytes rather than
 megabytes. SKIP outside a git repository - a project name in prefs is a name,
 not a path, and guessing checkout locations to produce a number is how a
 diagnostic starts lying.
+
+## The server profile (`--profile=server`)
+
+Four checks that only run under `--profile=server`. They are ADDITIVE: a
+default run is byte-for-byte what it was, and `--list-checks` reports whichever
+set the invocation would actually perform, because a list that disagrees with
+the run is worse than no list.
+
+None of them may BLOCK. The blocking set is closed at six and these are
+readiness, not correctness: a machine that fails all four still runs the
+pipeline perfectly well with someone watching it. What they catch is the
+failure mode of an unwatched run - stopping without saying so.
+
+### unattended-contract
+
+Is `multi-agent-refs/unattended-contract.md` installed. It is the only place
+that says which entry points honour `MULTI_AGENT_UNATTENDED=1` and what each
+one resolves to. Without it an operator setting up a server has to read the
+scripts to find out, which is how the wrong assumption gets made.
+
+### unattended-permissions
+
+Does `settings.json` carry `permissions.allow` entries covering Bash, Edit and
+Write. autopilot spawns its child with `--permission-prompts none`, but the
+tools that child then calls still have to be allowed, and on a fresh machine
+they are not - the run stops at the first prompt with nobody there to answer
+it, printing nothing. This is the single most likely reason a server sits idle
+and looks healthy.
+
+### scheduler
+
+Is a multi-agent launchd agent loaded. Something has to start the work; a
+server with no agent and an empty queue looks exactly like a server that has
+finished everything.
+
+### keychain-unlock
+
+Is a default keychain reachable from this session. Every credential the
+pipeline reads lives there, and a LaunchDaemon started before login sees a
+LOCKED keychain: each fetch fails, and the failures surface much later as 401s
+that blame the token rather than the lock. The check is a proxy - reading a
+real credential would be a network call and a side effect - so it asks whether
+a login keychain is reachable at all, which is the condition a boot-time
+daemon fails.