@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/docs/features.md

@@ -4,18 +4,19 @@ Comprehensive list of every feature the pipeline ships. The top-level `README.md
 
 ## Core Pipeline
 
-### 8-Phase Orchestration (0-7)
+### 6-Phase Orchestration (0-5)
 
 ```
 Phase 0: Init      Project selection, branch setup, identity, worktree
-Phase 1: Analysis  Stack detection, codebase exploration (parallel Explore agents)
-Phase 2: Planning  Task decomposition, architecture review, user approval
-Phase 3: Dev       TDD cycle: test → code → build (Sonnet)
-Phase 4: Review    Deterministic gates + parallel AI review + Fable triage
+Phase 1: Plan      Stack detection, codebase exploration (parallel Explore agents),
+                   task decomposition, architecture review, user approval
+Phase 2: Dev       TDD cycle: test → code → build (Sonnet), then the Verify exit
+                   gate: build · lint · tests · secrets, run once
+Phase 3: Review    Parallel AI review + Fable triage against Dev's logs, then the
+                   optional user test + on-demand device audits
                    (Claude Code: Fable + Opus + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
-Phase 5: Test      Optional manual testing + on-demand device audits
-Phase 6: Commit    Git commit, push, PR with default reviewers + draft/ready prompt
-Phase 7: Report   External: Jira comment · Wiki + Figma screenshots · Confluence
+Phase 4: Commit    Git commit, push, PR with default reviewers + draft/ready prompt
+Phase 5: Report    External: Jira comment · Wiki + Figma screenshots · Confluence
                    Internal: agent-log.md + Quality & Metrics + knowledge + memory
 ```
 
@@ -28,7 +29,7 @@ Each phase reads its own spec file under `pipeline/multi-agent-refs/phases/phase
 | `autopilot` | Skip all confirmation prompts; still fails safe on review blockers + build retries. |
 | `--local`   | Answers the workspace question up front: no worktree, work directly in `$PROJECT_ROOT` on a local branch. |
 
-Neither the workspace nor the depth is a flag. **Where the branch lives** is asked at Phase 0 Step 5b - worktree (`.worktrees/{id}/`, your checkout untouched) or local (the project root, which drops Phase 5 because the user-test gate checks the change out of a worktree and there is none). `:local` and `--local` state it in advance; every autopilot entry resolves it to a worktree and never asks, because an unattended run commits and pushes from wherever it stands and doing that in the user's own checkout is what worktrees exist to prevent. `state.workspaceSource` records who decided - `localMode: false` alone is both "the user chose a worktree" and "nothing asked".
+Neither the workspace nor the depth is a flag. **Where the branch lives** is asked at Phase 0 Step 5b - worktree (`.worktrees/{id}/`, your checkout untouched) or local (the project root, which drops the user test because that gate checks the change out of a worktree and there is none). `:local` and `--local` state it in advance; every autopilot entry resolves it to a worktree and never asks, because an unattended run commits and pushes from wherever it stands and doing that in the user's own checkout is what worktrees exist to prevent. `state.workspaceSource` records who decided - `localMode: false` alone is both "the user chose a worktree" and "nothing asked".
 
 Depth is not a flag either. `/multi-agent` and `/multi-agent:local` ask Full or Short at Phase 0 Step 7.5, recommending from the detected `taskType`; Short strips to Init → Dev(Opus self-contained) → Review → Test → Commit → Report. Autopilot never asks and always runs Full - "fast plus unattended" was removed in v16.0.0, because something has to choose when nobody is asked and unattended is the worst place to drop analysis and planning.
 
@@ -46,7 +47,7 @@ Uninstall preserves the whole layer - tokens, the reader that opens them, the ma
 
 A deterministic, LLM-free map of what a repo declares and what refers to what, extracted by regex over comment-stripped source into `~/.claude/knowledge/<project>/code-graph.json`. Four stacks build today (Swift, Kotlin/Java, TypeScript/JavaScript, Python); each is one rules file, and the engine is the same for all of them. Zero runtime dependencies, zero API cost, read-only on the repo.
 
-Phase 1 queries it to hand Explore a ranked starting file set instead of a full scan, and Phase 7 rebuilds it after the branch changed code - a rebuild is seconds, so staleness is a `baseCommit` comparison rather than a date heuristic. Off by default behind `prefs.global.codeGraph.enabled`; with it off the pipeline behaves exactly as before.
+Phase 1 queries it to hand Explore a ranked starting file set instead of a full scan, and Phase 5 rebuilds it after the branch changed code - a rebuild is seconds, so staleness is a `baseCommit` comparison rather than a date heuristic. Off by default behind `prefs.global.codeGraph.enabled`; with it off the pipeline behaves exactly as before.
 
 `GRAPH_REPORT.md` also ends with **Symbols nothing else references**: symbols no other file in the repo names, split from the ones referenced only by their own tests. Candidates, never verdicts - the extractor is regex, not a parser, so the four classes that could not carry a reference edge either way (a kind outside the stack's `referenceKinds`, a name declared twice, a nested declaration, a test file) are counted and excluded rather than listed, and nothing gates on the result.
 
@@ -78,9 +79,9 @@ Stack skill sets ship as versioned plugins in the `multi-agent-plugins` marketpl
 /multi-agent:stack all         # every stack plugin
 ```
 
-### Package Manager Resolution (Phase 3, node-shaped stacks)
+### Package Manager Resolution (Phase 2, node-shaped stacks)
 
-Phase 3's web test arm and its build step used to type `npm`. A repo on pnpm, yarn or bun then failed in Phase 3 - with a worktree and a branch already created - or, worse, npm resolved against a lock file it does not own and the run continued on a tree the repo's own tooling would never have produced.
+Phase 2's web test arm and its build step used to type `npm`. A repo on pnpm, yarn or bun then failed in Phase 2 - with a worktree and a branch already created - or, worse, npm resolved against a lock file it does not own and the run continued on a tree the repo's own tooling would never have produced.
 
 `scripts/package-manager.mjs` resolves it from the repo instead: `$MA_PACKAGE_MANAGER`, then `package.json#packageManager`, then a lock file, then npm - reported AS a default, never as evidence, because "npm because nothing said otherwise" and "npm because the repo committed a package-lock" are different answers. Node core only (ADR-0004): a resolver that shelled out would need a working install of the tool it is identifying. The walk goes up to the directory holding `.git` and stops there, so a monorepo's root lock file is found and a stray one in a home directory is not. Two lock files means a migration left one behind: the newest wins and both are named.
 
@@ -121,15 +122,15 @@ Result persisted to `agent-state.taskType`:
 
 | Type        | Downstream effects                                                            |
 | ----------- | ----------------------------------------------------------------------------- |
-| `component` | Phase 3 dispatches to the marketplace component plugin (create-component) with SubPhase reporting |
-| `bugfix`    | Phase 4 emphasizes test coverage + regression; Phase 6 uses `fix(...)` prefix |
-| `feature`   | Standard TDD flow; Phase 6 uses `feat(...)` prefix                            |
-| `refactor`  | Phase 4 emphasizes behavior preservation; Phase 6 uses `refactor(...)` prefix |
-| `chore`     | Lightweight flow; Phase 6 uses `chore(...)` prefix                            |
+| `component` | Phase 2 dispatches to the marketplace component plugin (create-component) with SubPhase reporting |
+| `bugfix`    | Phase 3 emphasizes test coverage + regression; Phase 4 uses `fix(...)` prefix |
+| `feature`   | Standard TDD flow; Phase 4 uses `feat(...)` prefix                            |
+| `refactor`  | Phase 3 emphasizes behavior preservation; Phase 4 uses `refactor(...)` prefix |
+| `chore`     | Lightweight flow; Phase 4 uses `chore(...)` prefix                            |
 
 ### SubPhase Convention
 
-When a specialized skill takes over a main pipeline phase, progress is reported as SubPhases (e.g. `SubPhase 3.0: Init`, `SubPhase 3.1: Gather`). The top-level pipeline stays fixed at 8 phases (0-7) - specialized work slots into its parent phase without inflating the count.
+When a specialized skill takes over a main pipeline phase, progress is reported as SubPhases (e.g. `SubPhase 3.0: Init`, `SubPhase 3.1: Gather`). The top-level pipeline stays fixed at 6 phases (0-5) - specialized work slots into its parent phase without inflating the count.
 
 ## PR & Review Flow
 
@@ -141,14 +142,14 @@ When a specialized skill takes over a main pipeline phase, progress is reported
 
 ### Draft vs Ready Prompt
 
-Phase 6 asks `DRAFT or READY?` before creating the PR and persists the choice in `prefs.projects[].defaultPrMode`.
+Phase 4 asks `DRAFT or READY?` before creating the PR and persists the choice in `prefs.projects[].defaultPrMode`.
 
 - Bitbucket: `draft: true` flag (DC 8.x+) with `[DRAFT]` title fallback for older servers.
 - GitHub: `gh pr create --draft` + `gh pr ready` for promotion.
 
 ### `channels` Command
 
-Multi-channel reporter - Phase 7 delegates to it, and it's also invocable post-hoc for fixes closed outside the pipeline:
+Multi-channel reporter - Phase 5 delegates to it, and it's also invocable post-hoc for fixes closed outside the pipeline:
 
 ```bash
 /multi-agent:channels                              # current branch, current PR
@@ -170,7 +171,7 @@ Never auto-closes issues - uses `Ref: #N` / `Related: #N` / `See: PROJ-12345`, n
 
 ## Review Quality
 
-### Deterministic Gates (Phase 4 Step 1)
+### Deterministic Gates (Phase 3 Step 1)
 
 Cheap, objective checks run BEFORE any AI token is spent:
 
@@ -181,23 +182,23 @@ Cheap, objective checks run BEFORE any AI token is spent:
 
 If any gate fails, fix first. Don't waste AI tokens reviewing broken code.
 
-### Analysis Document Review (Phase 3.2 + 3.3)
+### Analysis Document Review (Phase 2.2 + 2.3)
 
 `/multi-agent:analysis` published behind a structural validator alone until v16.12.0: nothing read the
-document before it reached Confluence. Phase 3.2 now runs the same reviewer set and triage a code diff
+document before it reached Confluence. Phase 2.2 now runs the same reviewer set and triage a code diff
 gets, on the draft, before the destination is even chosen. Its first question is what the run skipped -
 an input declared missing that nothing searched for, an open question about evidence nobody read, a gap
 with no owner, a scope call made without asking. A blocking finding returns to synthesis with dispatch
 closed; it never becomes an open question, because "the document is wrong" is not something to ask the
 reader.
 
-Phase 3.3 then sorts what is left: reachable evidence is searched (never asked about), decisions the
+Phase 2.3 then sorts what is left: reachable evidence is searched (never asked about), decisions the
 user owns are asked with `AskUserQuestion`, and only genuinely external gaps enter the document as
 `AS-NN` rows with an owner. A gap carrying neither a `searched, not found` nor an `asked, external`
 stamp fails the dispatch gate. Autopilot runs both phases; only the asking degrades, into rows stamped
 `autopilot: could not ask`.
 
-### CLI-Aware Parallel Review + Fable Triage (Phase 4 Steps 2-3)
+### CLI-Aware Parallel Review + Fable Triage (Phase 3 Steps 2-3)
 
 | Reviewer   | Model               | Focus                             | Where it runs        |
 | ---------- | ------------------- | --------------------------------- | -------------------- |
@@ -207,7 +208,7 @@ stamp fails the dispatch gate. Autopilot runs both phases; only the asking degra
 
 The reviewer set is **CLI-aware**: Claude Code dispatches 3 reviewers in parallel (Fable + Opus + Sonnet - Opus fills the slot GPT-5.4 takes elsewhere); Copilot CLI dispatches all 3. Each returns structured JSON for deterministic aggregation. Cross-model diversity catches blind spots that any single model family would miss.
 
-**Fable Triage** (Phase 4 Step 3, Opus on Copilot CLI): Evaluates merged raw findings against task scope. Classifies each as `accepted` (fix now), `deferred` (out of scope, log for later), or `rejected` (false positive / noise). Only triage-accepted blocking items loop back to Phase 3.
+**Fable Triage** (Phase 3 Step 3, Opus on Copilot CLI): Evaluates merged raw findings against task scope. Classifies each as `accepted` (fix now), `deferred` (out of scope, log for later), or `rejected` (false positive / noise). Only triage-accepted blocking items loop back to Phase 3.
 
 ### Runtime Triage Validator
 
@@ -224,13 +225,13 @@ After triage returns, output is validated by `validate-triage.mjs`:
 
 If triage returns `approved: false` but has no blocking items, the validator forces `approved: true`. Conversely, if `approved: true` but blocking items exist, it forces `approved: false`. Hardened with an `if`/`then` constraint in the schema itself.
 
-### Verify-by-Test Triage (Phase 4 Step 3.7, opt-in)
+### Verify-by-Test Triage (Phase 3 Step 3.7, opt-in)
 
-A triage verdict is a judgment call; a failing repro test is proof. When `prefs.global.verifyByTest.enabled` is on, one verifier agent (default Sonnet) writes a minimal repro test per accepted blocking finding (cap: `maxFindings`=3) and runs only that test. Fails as predicted -> finding confirmed, the repro test becomes the Phase 3 rework RED test. Passes under `evidence-gate.mjs` -> finding downgraded to `deferred`. Compile error / timeout -> `inconclusive`, judgment stands. Timeout-bounded, never blocks. Full spec: `refs/features/verify-by-test.md`.
+A triage verdict is a judgment call; a failing repro test is proof. When `prefs.global.verifyByTest.enabled` is on, one verifier agent (default Sonnet) writes a minimal repro test per accepted blocking finding (cap: `maxFindings`=3) and runs only that test. Fails as predicted -> finding confirmed, the repro test becomes the Phase 2 rework RED test. Passes under `evidence-gate.mjs` -> finding downgraded to `deferred`. Compile error / timeout -> `inconclusive`, judgment stands. Timeout-bounded, never blocks. Full spec: `refs/features/verify-by-test.md`.
 
 ### Immutable-Test Rule + `test_lines_removed` Signal
 
-Existing tests are immutable during a task: deleting, renaming, or weakening an assertion to reach green is a violation (`refs/rules.md`, Phase 3 GREEN step). A test changes only when the task changes the spec it encodes, named in the commit body. Deterministic backstop: `diff-risk-score.mjs` emits `test_lines_removed` (w=3.0) for any test-classified file whose diff removes more lines than it adds.
+Existing tests are immutable during a task: deleting, renaming, or weakening an assertion to reach green is a violation (`refs/rules.md`, Phase 2 GREEN step). A test changes only when the task changes the spec it encodes, named in the commit body. Deterministic backstop: `diff-risk-score.mjs` emits `test_lines_removed` (w=3.0) for any test-classified file whose diff removes more lines than it adds.
 
 ### Update Check at Run Start
 
@@ -244,7 +245,7 @@ Phase 0 Step 0.6. Once per `ttlHours` window (cached, 3s-bounded curl to the npm
 
 Every phase transition appends a `## Handoff` block (Done / Remaining / Decisions / Open findings / Next) to `agent-log.md` - orchestrator-written from existing state, no LLM call. `/multi-agent:resume` and post-`/compact` re-grounding read the latest handoff first, so long runs re-enter from durable artifacts instead of conversation memory (fresh-context discipline from Anthropic's long-running-agent harness guidance).
 
-### Accessibility Code Review (Phase 4 Step 1.5)
+### Accessibility Code Review (Phase 3 Step 1.5)
 
 If changes include UI files, reviewers check for:
 
@@ -256,16 +257,16 @@ Pure code analysis - no simulator needed. Device-level audits run in Phase 5 whe
 
 ### Status Enforcement
 
-Phase 3 treats the issue-tracker status update as a required step with a post-mutation verify step that re-reads the field and retries once on silent `VALIDATION` failures (e.g. stale Projects V2 option IDs after a board rebuild).
+Phase 2 treats the issue-tracker status update as a required step with a post-mutation verify step that re-reads the field and retries once on silent `VALIDATION` failures (e.g. stale Projects V2 option IDs after a board rebuild).
 
 ## Safety & Hygiene
 
 - **Pre-Commit Secret Detection** (12 patterns): `PreToolUse` hook scans staged files for API keys/tokens, AWS access keys, private keys, `.env` files, service account JSON. Commit **blocked** if found.
 - **Read-Size Gate** (opt-in, `prefs.global.bulkRead.mode`): a `PreToolUse` hook inspects `Read` and the shell commands that read a file whole. In `observe` it only logs what it would have caught - the baseline you measure before routing anything. In `enforce` a file over `minLines` (default 350) is blocked and delegated to a haiku-rung worker (`bulk-read.sh`), which returns a line-numbered summary so the follow-up is a bounded `Read(offset:limit:)` instead of the whole file; the full text is parked under `.multi-agent/refs/`. The development phase and any file the run has already touched are exempt, because Claude Code's `Edit` requires its own `Read` first.
-- **Capture Hooks** (`SessionEnd`, `PreCompact`, `SessionStart`): every durable write used to live in Phase 7, the phase a run is least likely to reach. `SessionEnd` flushes a run that never got there; `PreCompact` flushes before an auto-compaction summarizes a long phase mid-flight, which is the same loss one level down; `SessionStart` prints at most two lines about an unfinished run. None calls a model, none reads a payload, and all exit 0 on every path - a hook that fails a session over bookkeeping is worse than the bookkeeping.
+- **Capture Hooks** (`SessionEnd`, `PreCompact`, `SessionStart`): every durable write used to live in Phase 5, the phase a run is least likely to reach. `SessionEnd` flushes a run that never got there; `PreCompact` flushes before an auto-compaction summarizes a long phase mid-flight, which is the same loss one level down; `SessionStart` prints at most two lines about an unfinished run. None calls a model, none reads a payload, and all exit 0 on every path - a hook that fails a session over bookkeeping is worse than the bookkeeping.
 - **Operational Reporting** (`prefs.global.usageLog`): coarse run metadata - task id, phase, status, durations, token counts - and never prompts, code, diffs or absolute paths. The per-machine token is REQUESTED from the endpoint by `usage-register.mjs` (setup, update, and the Phase 0 exit gate as a backstop), is write-only, and lives in the OS credential store; prefs hold only the entry name and the switch. `usageLog.optOut: true` blocks registration permanently and is checked before the network call. An unreachable endpoint leaves reporting off with one line and exit 0 - a run is never failed over bookkeeping.
 - **Build Queue**: All `xcodebuild` calls acquire a lock. Each worktree uses own `-derivedDataPath`. Stale locks auto-clean after 15 min. Non-Xcode builds don't need the lock.
-- **Context Management**: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=65` - compaction at 65% usage (prevents degradation in 8-phase sessions).
+- **Context Management**: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=65` - compaction at 65% usage (prevents degradation in 6-phase sessions).
 - **3-Iteration Hard Kill**: Any retry loop stops after 3 attempts, then pauses for user. No infinite loops.
 
 ## Testing & Quality
@@ -300,51 +301,51 @@ Per-phase token budgets prevent runaway sessions. If a phase exceeds its budget,
 - **Cost Telemetry**: Per-phase token cost tracking (`tokens_in`, `tokens_out`, `model`, `duration_ms`). Omitted fields handled gracefully.
 - **Phase Tracker**: Cross-CLI visual progress (current phase, elapsed time, iteration count).
 - **Phase Banner**: Terminal UI for phase transitions with Unicode box-drawing characters.
-- **Per-task Cost Breakdown in agent-log.md**: Phase 7 appends a 4-column block (Phase · Model · Tokens in/out · Est. USD) to every run's `agent-log.md`. Sourced from `phase-tracker.sh tokens` accumulators × `cost-table.json` prices. Independent of the channels-side `reportContent.costSummary` toggle. The `LOG_METRIC_FORWARD_TO_TRACKER=1` env flag mirrors `tokens_in`/`tokens_out`/`model` from `log-metric.sh` into the tracker so JSONL metrics and the cost block stay in sync from one call site.
+- **Per-task Cost Breakdown in agent-log.md**: Phase 5 appends a 4-column block (Phase · Model · Tokens in/out · Est. USD) to every run's `agent-log.md`. Sourced from `phase-tracker.sh tokens` accumulators × `cost-table.json` prices. Independent of the channels-side `reportContent.costSummary` toggle. The `LOG_METRIC_FORWARD_TO_TRACKER=1` env flag mirrors `tokens_in`/`tokens_out`/`model` from `log-metric.sh` into the tracker so JSONL metrics and the cost block stay in sync from one call site.
 
 ### Diff Risk Scoring
 
-`pipeline/scripts/diff-risk-score.mjs` runs at Phase 4 Step 1.75 - before reviewer dispatch. Heuristic, deterministic, sub-second, no LLM. Top-N risk-ranked files inject into each reviewer's prompt as a `${PRIORITY_FILES}` block; reviewers read those files first but still review the entire diff.
+`pipeline/scripts/diff-risk-score.mjs` runs at Phase 3 Step 1.75 - before reviewer dispatch. Heuristic, deterministic, sub-second, no LLM. Top-N risk-ranked files inject into each reviewer's prompt as a `${PRIORITY_FILES}` block; reviewers read those files first but still review the entire diff.
 
 Signals + weights: `security_path` ×3, `migration` ×4, `public_api` ×2, `no_test_change` ×2.5, `test_lines_removed` ×3 (test file shrinks - immutable-test backstop), `complexity_delta` ×1.5, `ui_critical` ×1.5, `loc_changed` ×1. Toggle via `prefs.global.diffRiskAdvisory` (default ON).
 
 ### Test Gap Detection
 
-`pipeline/scripts/test-gap-scan.mjs` runs at Phase 5 Step 0. Walks the diff for newly added public symbols and reports those with no paired test. Stack-specific rules ship for iOS, Android, Python, Node.js. iOS Views and Android `@Composable` symbols default to `important`; other public API additions to `suggestion`. Optional gating via `prefs.testGap.blockingThreshold` - when set, the report becomes a Phase 4 rework finding once `important + blocking` count exceeds the threshold.
+`pipeline/scripts/test-gap-scan.mjs` runs at Phase 3 Step 0. Walks the diff for newly added public symbols and reports those with no paired test. Stack-specific rules ship for iOS, Android, Python, Node.js. iOS Views and Android `@Composable` symbols default to `important`; other public API additions to `suggestion`. Optional gating via `prefs.testGap.blockingThreshold` - when set, the report becomes a Phase 4 rework finding once `important + blocking` count exceeds the threshold.
 
 ### Visual Evidence (UI changes)
 
 A UI change carries its own picture. `state.visualEvidence.required` is decided mechanically from `taskType` plus the changed-file list, never from a reading of the task.
 
-**Stills.** The "before" is the reporter's own ticket attachment, harvested in Phase 0; the pipeline never rebuilds the old state to photograph it. The "after" is captured in Phase 3 right after the build goes green, not Phase 5, which autopilot and both local modes drop. `capture-evidence.sh` cleans the status bar and downscales to 1242px so two captures of one screen differ by the change and not by the clock.
+**Stills.** The "before" is the reporter's own ticket attachment, harvested in Phase 0; the pipeline never rebuilds the old state to photograph it. The "after" is captured in Phase 2 right after the build goes green, not in the user test, which autopilot and both local modes drop. `capture-evidence.sh` cleans the status bar and downscales to 1242px so two captures of one screen differ by the change and not by the clock.
 
-**The flow video rides on a test run.** `probe-evidence-capability.sh` measures the UI test target, the tests matching this change, the device, the recorder and the MCP registration; Phase 0 Step 7.7 then asks the depth with the options built from that measurement, and a closed option keeps its row and states why. Tier 1 runs the repo's own UI test and records around it, tier 2 drives the flow through `agent_run_steps`, tier 3 records nothing and says so. The tier is re-checked before the recording starts, because a simulator booted at intake can be gone by Phase 3.
+**The flow video rides on a test run.** `probe-evidence-capability.sh` measures the UI test target, the tests matching this change, the device, the recorder and the MCP registration; Phase 0 Step 7.7 then asks the depth with the options built from that measurement, and a closed option keeps its row and states why. Tier 1 runs the repo's own UI test and records around it, tier 2 drives the flow through `agent_run_steps`, tier 3 records nothing and says so. The tier is re-checked before the recording starts, because a simulator booted at intake can be gone by Phase 2.
 
 UI test detection keys on `XCUIApplication` rather than on a folder named `*UITests`: in a real app the overwhelming majority of files under such a path are snapshot tests, which never launch the app and would produce a still frame filed as a flow.
 
-**Where it lands.** Jira takes both stills and video as attachments. With no Jira the stills go to an orphan `evidence/<task-id>` branch and the PR body embeds them, or links them with a blob permalink when the repo is private (GitHub's image proxy has no credentials for a private repo, and a broken image reads as missing evidence). Phase 6 blocks when a required artefact is neither published nor explained; the gate is against silence, not against an honest "the ticket carries no image".
+**Where it lands.** Jira takes both stills and video as attachments. With no Jira the stills go to an orphan `evidence/<task-id>` branch and the PR body embeds them, or links them with a blob permalink when the repo is private (GitHub's image proxy has no credentials for a private repo, and a broken image reads as missing evidence). Phase 4 blocks when a required artefact is neither published nor explained; the gate is against silence, not against an honest "the ticket carries no image".
 
 Toggle via `prefs.global.visualEvidence.enabled` (default ON), `visualEvidence.githubHost`, `visualEvidence.maxAttachmentMb`, `visualEvidence.maxVideoSeconds`, `prefs.global.testDepth.default`.
 
 ### Triage Memory
 
-Per-repo append-only JSONL corpus at `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl`. Phase 7 ingests every triage output (idempotent), Phase 1 enriches the analysis with similar past tasks, Phase 4 triage attaches prior-art hits to each raw finding with an explicit bias hedge. Token-overlap recall, zero deps, Node-18-compatible. `/multi-agent:search "<text>" --semantic` routes the query to the corpus instead of agent-log grep. Toggle via `prefs.global.priorArtEnrichment.enabled` (default ON).
+Per-repo append-only JSONL corpus at `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl`. Phase 5 ingests every triage output (idempotent), Phase 1 enriches the analysis with similar past tasks, Phase 3 triage attaches prior-art hits to each raw finding with an explicit bias hedge. Token-overlap recall, zero deps, Node-18-compatible. `/multi-agent:search "<text>" --semantic` routes the query to the corpus instead of agent-log grep. Toggle via `prefs.global.priorArtEnrichment.enabled` (default ON).
 
 ## Learning
 
 ### Knowledge Base (per project)
 
-Incremental learning. Phase 7 captures architecture, patterns, gotchas, and decisions into `$HOME/.claude/knowledge/{project}/`. Phase 1 reads it on the next run. Token cost decreases over time as the base grows.
+Incremental learning. Phase 5 captures architecture, patterns, gotchas, and decisions into `$HOME/.claude/knowledge/{project}/`. Phase 1 reads it on the next run. Token cost decreases over time as the base grows.
 
 ### Memory Capture (cross-session)
 
-Pipeline learns behavioral signals (feedback corrections, project constraints, external references). Phase 7 saves, Phase 1 injects. Max 3 new memories per run. Merge-over-duplicate. Stale memories verified before use.
+Pipeline learns behavioral signals (feedback corrections, project constraints, external references). Phase 5 saves, Phase 1 injects. Max 3 new memories per run. Merge-over-duplicate. Stale memories verified before use.
 
 **What does NOT go in memory**: architecture, code patterns, build gotchas, design decisions - those belong in the knowledge base.
 
 ### Lesson Diagnosis (Reflexion)
 
-Phase 4's lesson-memory loop records the causal root cause of each fix (`--diagnosis`), not just the outcome: the verbal "why" that prevents recurrence (Reflexion). `learnings-ledger.mjs brief` renders it as `(why: ...)` back into Phase 1 + triage on the next run, so the reason re-enters the loop, not only the symptom.
+Phase 3's lesson-memory loop records the causal root cause of each fix (`--diagnosis`), not just the outcome: the verbal "why" that prevents recurrence (Reflexion). `learnings-ledger.mjs brief` renders it as `(why: ...)` back into Phase 1 + triage on the next run, so the reason re-enters the loop, not only the symptom.
 
 ### Corpus Freshness Gate
 
@@ -366,7 +367,7 @@ Turn a recurring, project-specific job into a first-class `/multi-agent:<name>`
 
 ### Figma / Component Generation (dispatched to marketplace plugins)
 
-Component + Figma-to-code work is no longer bundled in this repo. When Phase 0 classifies a task as `component`, Phase 3 dispatches it to the per-stack marketplace plugins (`ai-ios-toolkit` / `ai-android-toolkit` in the `multi-agent-plugins` marketplace) via the Skill tool. The plugin's component skill generates `{Name}Configuration.swift`, `{Name}View.swift`, `{Name}+Modifiers.swift`, `{Name}.figma.swift`, and `FIGMA.md` with a variant matrix, then runs a 14-item pre-commit checklist covering design tokens, accessibility, tests, and Code Connect.
+Component + Figma-to-code work is no longer bundled in this repo. When Phase 0 classifies a task as `component`, Phase 2 dispatches it to the per-stack marketplace plugins (`ai-ios-toolkit` / `ai-android-toolkit` in the `multi-agent-plugins` marketplace) via the Skill tool. The plugin's component skill generates `{Name}Configuration.swift`, `{Name}View.swift`, `{Name}+Modifiers.swift`, `{Name}.figma.swift`, and `FIGMA.md` with a variant matrix, then runs a 14-item pre-commit checklist covering design tokens, accessibility, tests, and Code Connect.
 
 The plugin's cross-cutting integration skills feed component detection + implementation when the design triggers them (content: form / price / ui-patterns; interaction: navigation / overlays / bottom-sheets). Each is native-SwiftUI-first and reads project specifics (token namespaces, component paths, UI systems) from `figma-config`, including the optional `ui.navigationSystem` / `ui.overlaySystem` / `ui.sheetSystem` hooks (absent -> stock SwiftUI), so the same capabilities work on any SwiftUI codebase. The plugin's evolve-component skill reconciles an existing component against current Figma (drift-heal) and additively extends it, behind a human gate.
 
@@ -376,20 +377,20 @@ Automated visual testing and compliance audits via direct Bash (no MCP server de
 
 | Audit                 | When                | Command                      |
 | --------------------- | ------------------- | ---------------------------- |
-| iOS Accessibility     | Phase 5, on request | `swift ui-tree-dumper.swift` |
-| Android Accessibility | Phase 5, on request | `adb shell uiautomator dump` |
-| iOS Biometric         | Phase 5, auth flow  | `xcrun simctl keychain`      |
-| Android Launch Time   | Phase 5, perf       | `adb shell am start -W`      |
-| iOS Archive           | Phase 6, release    | `codesign`, `plutil`, `nm`   |
-| Android APK           | Phase 6, release    | `aapt2`, `apksigner`         |
+| iOS Accessibility     | Phase 3, on request | `swift ui-tree-dumper.swift` |
+| Android Accessibility | Phase 3, on request | `adb shell uiautomator dump` |
+| iOS Biometric         | Phase 3, auth flow  | `xcrun simctl keychain`      |
+| Android Launch Time   | Phase 3, perf       | `adb shell am start -W`      |
+| iOS Archive           | Phase 4, release    | `codesign`, `plutil`, `nm`   |
+| Android APK           | Phase 4, release    | `aapt2`, `apksigner`         |
 
 Audits are **on-demand** - triggered by user, never automatic.
 
 ### Jira + Confluence
 
-- Phase 3: transition issue to `In Progress` (verified post-mutation).
-- Phase 7: post analysis + test scenarios as Jira comment (Turkish by default, configurable).
-- Phase 7 (optional): create Confluence page under chosen parent, cached per project.
+- Phase 2: transition issue to `In Progress` (verified post-mutation).
+- Phase 5: post analysis + test scenarios as Jira comment (Turkish by default, configurable).
+- Phase 5 (optional): create Confluence page under chosen parent, cached per project.
 
 ### Keychain
 

package/docs/performance.md

@@ -13,7 +13,7 @@ node pipeline/scripts/aggregate-metrics.mjs
 # Markdown table (for PR descriptions, wikis, dashboards)
 node pipeline/scripts/aggregate-metrics.mjs --markdown
 
-# JSON (for machine consumption - Phase 7 report uses this)
+# JSON (for machine consumption - Phase 5 report uses this)
 node pipeline/scripts/aggregate-metrics.mjs --json
 
 # Filtered - only recent runs
@@ -77,7 +77,7 @@ _Source: ~/.claude/logs/multi-agent/metrics.jsonl · Events: 421 (0 parse errors
 - **`cycles per task avg` > 2.0** - triage is rejecting too many real findings
   or Phase 3 isn't converging. Inspect the edge-cases table.
 - **Most-common edge case = `over_rejection_guard_tripped`** - the triage
-  prompt lost scope context. Look at `phase-4-review.md:57-91`.
+  prompt lost scope context. Look at `phase-3-review.md:57-91`.
 - **`p95` much higher than `avg`** - a few tasks are looping 3+ times. Usually
   means one of: bad acceptance criteria in Phase 2, tests that flake, or
   environment-dependent build failures.
@@ -103,11 +103,11 @@ Current totals (v3.5.0):
 Lazy loading keeps these off the model's context until each phase actually
 runs - the full 14 k total is never loaded at once.
 
-## Embedding Metrics in Phase 7 Reports
+## Embedding Metrics in Phase 5 Reports
 
-Phase 7 automatically calls `aggregate-metrics.mjs --json` with the current
+Phase 5 automatically calls `aggregate-metrics.mjs --json` with the current
 task id and embeds the last 30 days' summary into the report body. See the
-template in `phase-7-report.md`.
+template in `phase-5-report.md`.
 
 ## Disabling Metrics
 

package/docs/recovery-guide.md

@@ -10,8 +10,8 @@ the answer across `modes.md`, `operations.md`, and the individual phase specs.
 | ------------------------------------------------------- | ----------------------------------------------- |
 | Pipeline paused/halted mid-run                          | [Resume a paused task](#resume-a-paused-task)   |
 | Phase 3 build failed > 3 times                          | [Build retry exhausted](#build-retry-exhausted) |
-| Phase 4 triage returned exit 1 (invalid JSON) twice     | [Triage fallback](#triage-fallback)             |
-| Phase 4 triage returned exit 2 (over-rejection)         | [Over-rejection](#over-rejection-guard)         |
+| Phase 3 triage returned exit 1 (invalid JSON) twice     | [Triage fallback](#triage-fallback)             |
+| Phase 3 triage returned exit 2 (over-rejection)         | [Over-rejection](#over-rejection-guard)         |
 | Worktree already exists / dirty                         | [Worktree collisions](#worktree-collisions)     |
 | `agent-state.json` corrupt or unreadable                | [State corruption](#state-corruption)           |
 | Wrong git identity committed                            | [Identity rewind](#identity-rewind)             |
@@ -58,7 +58,7 @@ Path forward:
    environment and `resume` - the 3-retry counter resets.
 3. If the failure is logic (compile error in the generated code), edit the
    offending file in the worktree, then `resume` - Phase 3 re-runs build.
-4. If the task itself is wrong-shaped (Phase 2 plan is infeasible), `kill` and
+4. If the task itself is wrong-shaped (Phase 1 plan is infeasible), `kill` and
    restart with a better-scoped prompt.
 
 ---
@@ -79,7 +79,7 @@ If exit 1 fires twice (fallback path):
 1. The pipeline logs `Phase 4: triage failed twice - fallback, all findings accepted as blocking`.
 2. All raw findings loop back into Phase 3 as if they were all real blockers.
 3. This is intentionally conservative - we'd rather over-fix than skip
-   something real. You can manually mark noise in the Phase 6 PR description.
+   something real. You can manually mark noise in the Phase 4 PR description.
 
 ## Over-Rejection Guard
 
@@ -216,7 +216,7 @@ cat .worktrees/{id}/agent-state.json | grep status
 ## Instruction Fallback
 
 `state.instructionDriven=true` but the file at `state.instructionFiles.commit`
-is missing on disk. Phase 6 logs an error, sets
+is missing on disk. Phase 4 logs an error, sets
 `state.instructionDrivenFallback=true`, and uses the standard commit path.
 
 This is rarely fatal - usually the instruction file was removed between
@@ -320,7 +320,7 @@ cp "$TRACKER_STATE" "$TRACKER_STATE.bak.$(date +%s)"
 # 3. Either restore from a recent valid snapshot in the same dir, or
 #    reinitialize from the agent-log timeline:
 bash $HOME/.claude/scripts/phase-tracker.sh init "<task-id>"
-for p in 0:Init 1:Analysis 2:Planning 3:Dev 4:Review 5:Test 6:Commit 7:Report; do
+for p in 0:Init 1:Plan 2:Dev 3:Review 4:Commit 5:Report; do
   bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
 done
 # Replay completed phases from agent-log.md headers
@@ -338,7 +338,7 @@ reinit. A footnote in `agent-log.md` documenting the rebuild is good practice.
 ## Token Rotation Mid-Pipeline (v8.0.0)
 
 A token (Jira / Bitbucket / GitHub / Vercel) was rotated while a long-running
-pipeline was active. Phase 6 / Phase 7 then fail with `401 Unauthorized` even
+pipeline was active. Phase 4 / Phase 5 then fail with `401 Unauthorized` even
 though earlier phases worked.
 
 Fix:
@@ -362,7 +362,7 @@ echo "$NEW_TOKEN" | secret-tool store --label="$LABEL" account "$ACCOUNT" servic
 # 2. Sanity-check the doctor reports the new token's prefix
 bash pipeline/lib/credential-store.sh doctor
 
-# 3. Resume the pipeline - Phase 6/7 re-resolve the token on each invocation,
+# 3. Resume the pipeline - Phase 4/5 re-resolve the token on each invocation,
 #    so no state edit is required.
 /multi-agent:resume <task-id>
 ```
@@ -446,7 +446,7 @@ versions).
 ## Failed Push + Force-Push Decision (v8.0.0)
 
 `git push` rejects the branch (non-fast-forward, hook rejected, branch
-protection mismatch, etc.). The pipeline is paused at Phase 6 Step 3.
+protection mismatch, etc.). The pipeline is paused at Phase 4 Step 3.
 
 Decision tree:
 

package/docs/server-readiness.md

@@ -0,0 +1,188 @@
+# Running multi-agent on a machine nobody is sitting at
+
+This describes what a Mac has to have before an unattended run works, and what
+breaks if it does not. **Nothing here is set up by reading it** - `install`
+still writes nothing about permissions and no scheduler is loaded unless you
+ask for one. That is deliberate: every item below changes what runs on a
+machine without a human, and none of it should happen because someone ran an
+installer.
+
+Scope is macOS. Linux and Windows were removed on purpose (ADR-0012) and
+nothing here reintroduces them.
+
+The mechanical half of this page is `doctor --profile=server`, which checks
+four of the conditions below and says which are missing. Read that first; this
+page explains why each one matters and what to do about it.
+
+## The failure this page exists for
+
+An unattended run does not fail loudly. It **stops without saying so**, and
+every way it does that looks identical from outside: a process that is running,
+printing nothing, finishing never.
+
+Four causes, in the order they bite.
+
+## 1. The permission posture
+
+autopilot spawns its child with `--permission-prompts none`. That stops Claude
+Code from ASKING, and it does not grant anything - the tools the child then
+calls still have to be allowed. On the maintainer's machine they are, because
+`Bash`, `Edit`, `Write` and `Agent` sit in the global allow list from years of
+interactive use. On a fresh machine they do not, and the first tool call ends
+the run.
+
+There is no DEFAULT that fixes this and should not be: writing a permission
+posture into someone's settings during an install is the one action an
+installer must never take silently. There is now a flag that asks for it:
+
+```bash
+npx @mmerterden/multi-agent-pipeline install --unattended --dry-run   # see it first
+npx @mmerterden/multi-agent-pipeline install --unattended             # write it
+```
+
+It prints the whole profile with a reason per line before writing anything, and
+it is additive: an entry you added by hand survives, a narrower `Bash(...)` rule
+is kept alongside, unrelated settings are untouched, and a second run changes
+nothing. A `settings.json` that does not parse is refused rather than
+overwritten.
+
+By hand, the same thing is:
+
+```jsonc
+// ~/.claude/settings.json
+{
+  "permissions": {
+    "allow": ["Bash", "Edit", "Write", "Agent"]
+  }
+}
+```
+
+Grant the narrowest set the work needs. A server that only reviews does not
+need `Write` - though note that the shipped profile is deliberately broad,
+because a run builds and tests whatever the target repo uses and a narrow list
+is the one the first unfamiliar repo stops at.
+
+`doctor --profile=server` reports this as `unattended-permissions`, against the
+same rule the writer applies.
+
+## 2. The scheduler, and why it is a LaunchAgent
+
+Something has to start the work. The template ships as a **LaunchAgent**
+(`install/templates/multi-agent-autopilot.plist.template`), loaded in the
+user's session at login - not a LaunchDaemon at boot.
+
+That is a keychain decision, not a preference. Every credential the pipeline
+reads lives in the login keychain, and the login keychain is **locked until the
+user logs in**. A daemon started at boot gets a locked one: each credential
+read fails, and those failures surface much later as 401s that blame the token.
+The lock is the cause and nothing in the error says so.
+
+So the machine needs to reach a logged-in session by itself:
+
+- **System Settings → Users & Groups → Automatic login**, for the account that
+  owns the agent.
+- A **keychain with no lock timeout** for that account, or the agent survives
+  a login and dies at the first idle period:
+  ```
+  security set-keychain-settings -l ~/Library/Keychains/login.keychain-db
+  ```
+  (no `-t`, so there is no timeout; `-l` still locks on sleep.)
+
+Automatic login means physical access to the machine is access to the
+credentials. On a server in a locked room that is the trade being made; on a
+laptop it is not.
+
+`doctor --profile=server` reports these as `scheduler` and `keychain-unlock`.
+
+## 3. The unattended contract
+
+`MULTI_AGENT_UNATTENDED=1` is how a run states that nobody is watching.
+`multi-agent-refs/unattended-contract.md` lists exactly which entry points read
+it and what each resolves to - four of them, named, because a claim of coverage
+that is not true is worse than a short list.
+
+The variable does **not** grant permissions and does not suppress errors. It
+only stops a process from waiting for an answer that is not coming.
+
+`doctor --profile=server` reports this as `unattended-contract`.
+
+## 4. Which credential each phase needs
+
+A server fails differently from a laptop here: an interactive run asks for a
+missing token, an unattended one does not.
+
+| Phase | Needs | Absent |
+|---|---|---|
+| 0 Init | `github` (issue intake), `jira` (ticket intake) | the run cannot resolve its input and stops at the picker |
+| 1-2 Analysis, Plan | `figma` or `figma_mcp` when the task names a design | halts by contract rather than guessing at layout |
+| 3 Dev | none beyond git access | - |
+| 4 Review | `github` for PR comments | findings are computed and never posted |
+| 5 Test | none | - |
+| 6 Commit | git push credential | the branch stays local, which reads as "no PR yet" |
+| 7 Report | `jira`, `confluence` as configured | the report is composed and dropped |
+
+`credential-store.sh doctor` lists what is mapped. `doctor --probe` additionally
+checks each one is alive, which costs network calls and is why it is opt-in.
+
+## 4b. What the runner does when nobody is looking
+
+Three behaviours that are invisible on a laptop and decide whether a server
+survives a month.
+
+**The log.** launchd appends the runner's stdout to `runner.log` forever. Each
+tick truncates it past `MA_AP_LOG_MAX_BYTES` (5MB by default), keeping the last
+256KB in `runner.log.1`. It truncates the SAME file rather than renaming it,
+because launchd holds it open with `O_APPEND` - rename it and that descriptor
+keeps writing into the renamed file while the new one stays empty, which is the
+rotation that looks correct and silently stops logging.
+
+**The breaker.** An expired token, a `claude` that no longer launches, a full
+disk: every queued item fails the same way, minutes apart, until the queue is
+empty and the ledger is a list of identical failures with no indication which
+came first. After `MA_AP_BREAKER_LIMIT` consecutive attempts that produced
+nothing (3 by default, 0 disables), the runner stops taking new work, writes the
+reason into `queue.json` so `autopilot-status` shows it, and says what to check.
+One successful attempt clears it. A run waiting for a person (`needs-input`) and
+an item arming refused (`blocked-*`) are deliberately not failures.
+
+**Telemetry.** `ticks.jsonl` gets one JSON line per tick. The human log answers
+"what happened just now"; a server is only ever asked "how has this been
+behaving for a week".
+
+## 5. Self-hosted CI runner
+
+ADR-0011 rejected a self-hosted runner because "a self-hosted runner on a
+public repository executes code from any fork's pull request". Half of that has
+changed and half has not, and the difference matters before wiring a runner to
+a machine that holds credentials.
+
+Measured, not assumed: the repo is **private**, and it has **one fork**, owned
+by another account. "Zero forks" is a claim worth not making - GitHub requires
+approval before a fork's pull request runs a workflow, but that protection is a
+SETTING, and a self-hosted runner turns "someone approved a workflow run by
+reflex" into code on this machine with this keychain.
+
+So: a runner here is defensible on a private single-owner repo, and it is
+defensible only while fork-PR approval stays on and every approval is treated
+as a decision rather than a formality.
+
+The same machine can host the runner:
+
+```
+mkdir ~/actions-runner && cd ~/actions-runner
+# download and configure per GitHub's instructions for the repo
+./svc.sh install && ./svc.sh start
+```
+
+Two things to keep in mind. The runner service runs in the same session as the
+autopilot agent, so a long CI job and a pipeline run compete for the same CPU
+and the same `~/.claude` state root. And the runner inherits that session's
+keychain, which means a workflow can read the credentials - acceptable on a
+single-owner machine, not on a shared one.
+
+## What this page does NOT cover
+
+- Turning any of it on. Every step here is the operator's to take.
+- Linux, Windows, systemd, Docker. Out of scope and staying there.
+- Multi-user servers. Everything above assumes one account owns the install,
+  the keychain and the queue.