@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

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

@@ -54,7 +54,7 @@ ticket that referenced nothing. The run then produced a plan from a partial pict
 reported success, and the user found out by reading the output.
 
 So on exit `3`, classify the stderr and surface an `AskUserQuestion` before continuing.
-The classification is the same shape the Phase 6 remote gate uses, because the failures
+The classification is the same shape the Phase 4 remote gate uses, because the failures
 are the same failures:
 
 | stderr signal | Diagnosis | Question offers |
@@ -78,14 +78,14 @@ Rules that make this actionable rather than decorative:
    "planned without Crashlytics, user's choice at <ts>" in the analysis doc's limitations
    section instead of leaving a silent hole.
 5. **Autopilot still reports.** Autopilot takes "continue without this source" without
-   asking, but the skipped source is logged and carried into the Phase 7 report. An
+   asking, but the skipped source is logged and carried into the Phase 5 report. An
    autopilot run that quietly planned from a partial picture is the same defect with a
    flag on it.
 
 Failures remain non-fatal at Phase 1 by default - the agent still runs analysis. What
 changed is that the user learns about it while the choice is still theirs to make.
 
-**Graylog specifics.** `fetch-graylog.sh` degrades to empty on any network/VPN failure: it emits a normalized empty object and exits `0`, so an unreachable host reads as `{status:"skipped", reason:"vpn-unreachable"}` and never blocks. **Exiting `0` is not permission to stay quiet.** The payload carries `degraded: true` and a `degradeReason`; when it does, log one line naming the host and the reason, and carry it into the Phase 7 report. Logs are advisory, so this never asks a question and never blocks - but "I searched the logs and found nothing" and "I never reached the log server" are different statements, and only one of them is true. Only a genuine auth rejection on a reachable host exits `3` (marked `failed`, still non-fatal here). `state.graylogContext` is prepended to the analysis prompt inside the **Referenced External Sources** section as diagnostic context that is **advisory only**  -  the agent may use it to orient on a reported error, but code remains ground truth, and there is no Phase 4 review gate for logs.
+**Graylog specifics.** `fetch-graylog.sh` degrades to empty on any network/VPN failure: it emits a normalized empty object and exits `0`, so an unreachable host reads as `{status:"skipped", reason:"vpn-unreachable"}` and never blocks. **Exiting `0` is not permission to stay quiet.** The payload carries `degraded: true` and a `degradeReason`; when it does, log one line naming the host and the reason, and carry it into the Phase 5 report. Logs are advisory, so this never asks a question and never blocks - but "I searched the logs and found nothing" and "I never reached the log server" are different statements, and only one of them is true. Only a genuine auth rejection on a reachable host exits `3` (marked `failed`, still non-fatal here). `state.graylogContext` is prepended to the analysis prompt inside the **Referenced External Sources** section as diagnostic context that is **advisory only**  -  the agent may use it to orient on a reported error, but code remains ground truth, and there is no Phase 3 review gate for logs.
 
 ## Prompt injection shape
 

package/pipeline/multi-agent-refs/features/maturity-followup.md

@@ -128,15 +128,15 @@ maturity step has `currentPhase: 0`, so resuming would start at Phase 1 and skip
 the check - the halt would be permanent in the one direction that matters.
 
 So resume reads `state.waitingFor` first: when it names a step, the run re-enters
-THAT step rather than the next phase. `waitingFor` already existed and Phase 7's
+THAT step rather than the next phase. `waitingFor` already existed and Phase 5's
 channels pause already documented itself as resumable through it
-(`phases/phase-7-report.md`), while `resume/SKILL.md` never mentioned the field -
+(`phases/phase-5-report.md`), while `resume/SKILL.md` never mentioned the field -
 so that pause had the same gap and this fixes both.
 
 | `waitingFor` | Re-entry |
 |---|---|
 | `maturity` | Phase 0, the maturity step, with the item re-fetched |
-| `user-channels-choice` | Phase 7, the channels menu |
+| `user-channels-choice` | Phase 5, the channels menu |
 | absent | `currentPhase + 1`, as before |
 
 `waitingFor` is cleared by the write that records the answer. A field that

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

@@ -42,7 +42,7 @@ architect/reviewer roles with no file edits.
 Personas and dispatch read the **rung** (`fable`, `opus`, `sonnet`, `haiku`). The wire
 model ID each rung resolves to lives in exactly two places: `scripts/cost-table.json`
 (`prices.<rung>.modelId`) and the per-host reviewer table in
-`phases/phase-4-review.md`. A generation move edits those; it never renames a rung and
+`phases/phase-3-review.md`. A generation move edits those; it never renames a rung and
 never touches a persona file.
 
 Current resolution: `fable` -> `claude-fable-5`, `opus` -> `claude-opus-5`,
@@ -61,7 +61,7 @@ Three shifts on the current opus rung are worth knowing when reading a run that
 different rather than broken, and none of them are bugs in this contract:
 
 - **Longer user-facing output.** Effort is not the lever; prompt-level conciseness is.
-  Phase 7 report length and reviewer prose are where this shows.
+  Phase 5 report length and reviewer prose are where this shows.
 - **Self-verification without being asked.** Explicit "double-check your work"
   scaffolding now causes over-verification rather than preventing under-verification.
   Phase 4's deterministic gates already carry that load.
@@ -162,7 +162,7 @@ prints it once instead:
    with `PHASE_MODEL_OVERRIDE=<floorModel>`. A failure at the floor (or when no
    floor is configured) falls through to the normal phase-error path (pause ->
    resume). Never silent-skip the persona. Each downgrade emits its own
-   `model_fallback` metric line so a two-step degrade is visible in Phase 7.
+   `model_fallback` metric line so a two-step degrade is visible in Phase 5.
 3. **Cost budget ceiling (existing gate).** When `cost-budget-check.mjs` exits 11
    (exceeded) mid-run, the run already pauses per the cost-budget contract; on
    user-approved continue, `preferredModel` personas downgrade to `fallbackModel` for the
@@ -172,7 +172,7 @@ prints it once instead:
 
 Every fallback emits one `log-metric.sh` line (`metric: model_fallback`,
 attributes: `persona`, `from`, `to`, `trigger: date-gate|dispatch-error|budget`)
-and one agent-log line so Phase 7 reports show which phases ran degraded.
+and one agent-log line so Phase 5 reports show which phases ran degraded.
 The cost ledger prices the dispatch at the model actually used (the tracker's
 per-phase `model` field already carries the override).
 
@@ -213,5 +213,5 @@ parent model and reasoning effort and silently discards the override, so a
 fallback that omits it appears to apply while changing nothing.
 
 The three model ids above live in exactly three places - this table,
-`pipeline/scripts/cost-table.json`, and the Phase 4 reviewer matrix - so an OpenAI
+`pipeline/scripts/cost-table.json`, and the Phase 3 reviewer matrix - so an OpenAI
 rename is a three-file change.

package/pipeline/multi-agent-refs/features/plan-todos.md

@@ -1,6 +1,6 @@
 # Feature: Plan Todos Iteration (Phase 3)
 
-**Gated by `prefs.global.planTodos.enabled`** (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]` (conforming to `$HOME/.claude/schemas/plan-todos.schema.json`), Phase 3 iterates with the helper instead of walking `tasks[]` directly:
+**Gated by `prefs.global.planTodos.enabled`** (default: `false`). When enabled and Phase 1 Step 11 emitted a `plan.todos[]` (conforming to `$HOME/.claude/schemas/plan-todos.schema.json`), Phase 2 iterates with the helper instead of walking `tasks[]` directly:
 
 ```bash
 while next=$(bash "$HOME/.claude/lib/plan-todos.sh" next "$TASK_ID"); [ -n "$next" ]; do

package/pipeline/multi-agent-refs/features/repo-map.md

@@ -23,7 +23,7 @@ fi
 - **Deterministic**  -  same worktree state → same map. No embeddings, no network. Sub-second on monorepos.
 - **Advisory**  -  Explore agents may ignore the map if they have stronger signals (Phase 0 knowledge cache, explicit user context). Never gates the pipeline.
 - **Truncation-safe**  -  output is capped at `tokenBudget`; the script falls back to "no files extracted within budget" rather than over-spending.
-- **Cost ledger**  -  emit `phase-1.repo_map_emitted bytes=$(wc -c <<<"$REPO_MAP") budget=$BUDGET` so Phase 7 cost summary can show the size injected.
+- **Cost ledger**  -  emit `phase-1.repo_map_emitted bytes=$(wc -c <<<"$REPO_MAP") budget=$BUDGET` so Phase 5 cost summary can show the size injected.
 
 ## When to enable
 

package/pipeline/multi-agent-refs/features/review-delta.md

@@ -6,7 +6,7 @@ Gated by `prefs.global.autopilotCircuitBreaker` (`enabled` default true, `identi
 
 ## Files per round
 
-Phase 4 Step 3.2.1 writes `$WORKTREE/.pipeline/triage-round-<N>.json` (N = `state.reviewIterations | length`), validates it, annotates it and copies it to `$WORKTREE/triage-output.json`, the name Phase 7, `worktree-finalize.sh`, `render-work-summary.sh` and `diff-explain.mjs` read. A copy rather than a symlink because the salvage is `cp -R`, and `.pipeline/` is on the salvage list, so every round survives into `artifactsPath`. Step 3.7 rewrites the round file; the copy is repeated after it.
+Phase 3 Step 3.2.1 writes `$WORKTREE/.pipeline/triage-round-<N>.json` (N = `state.reviewIterations | length`), validates it, annotates it and copies it to `$WORKTREE/triage-output.json`, the name Phase 5, `worktree-finalize.sh`, `render-work-summary.sh` and `diff-explain.mjs` read. A copy rather than a symlink because the salvage is `cp -R`, and `.pipeline/` is on the salvage list, so every round survives into `artifactsPath`. Step 3.7 rewrites the round file; the copy is repeated after it.
 
 ## Step 2.1 block: previous-round findings (iteration >= 2)
 
@@ -34,7 +34,7 @@ The cap of 40 entries drops `important` before `blocking` so the prefix stays bo
 
 ## Step 2.2 block: scope self-check (every iteration)
 
-Phase 3 Step 3.7 wrote `$WORKTREE/.pipeline/scope-check.json` (contract: `features/scope-check.md`). Render it so reviewers judge the diff against the dev's stated scope and do not re-propose what was rejected:
+Phase 2 Step 3.7 wrote `$WORKTREE/.pipeline/scope-check.json` (contract: `features/scope-check.md`). Render it so reviewers judge the diff against the dev's stated scope and do not re-propose what was rejected:
 
 ```bash
 SCOPE_JSON="$WORKTREE/.pipeline/scope-check.json"
@@ -82,7 +82,7 @@ Same argument `shortId()` in `_retrieval.mjs` makes for corpus rows: derived fro
 
 ## Telemetry
 
-`review.delta` once per iteration >= 2: `iteration`, `new`, `still_present`, `resolved`, `plateau`, `tripped`. `run-metrics.mjs` reports `reviewDelta.stillPresentFinal`, `resolvedTotal` and `tripped`; Phase 7 renders the three counts per round.
+`review.delta` once per iteration >= 2: `iteration`, `new`, `still_present`, `resolved`, `plateau`, `tripped`. `run-metrics.mjs` reports `reviewDelta.stillPresentFinal`, `resolvedTotal` and `tripped`; Phase 5 renders the three counts per round.
 
 ## Reference
 

package/pipeline/multi-agent-refs/features/review-multi-repo.md

@@ -1,6 +1,6 @@
 # Phase 4 Review  -  Multi-Repo Mode
 
-> Loaded on demand from `phases/phase-4-review.md`. Conditional on
+> Loaded on demand from `phases/phase-3-review.md`. Conditional on
 > `state.projects[].length > 1`; a single-repo run (the common case) never needs
 > it and used to pay for it on every review.
 

package/pipeline/multi-agent-refs/features/scope-check.md

@@ -1,6 +1,6 @@
-# Feature: Scope self-check (Phase 3 Step 3.7)
+# Feature: Scope self-check (Phase 2 Step 3.7)
 
-**Pattern**: Phase 4 reconstructs everything from the diff. The one thing it cannot reconstruct is why each file was touched and what was left out on purpose, so Dev states both before the handoff, and a deterministic gate checks the statement against the real diff. The record also carries the code-simplifier rationales (Step 3.6) that used to be discarded, and it feeds two later consumers: the `<scope-self-check>` block in the Phase 4 reviewer prefix and the PR body in Phase 6.
+**Pattern**: Phase 3 reconstructs everything from the diff. The one thing it cannot reconstruct is why each file was touched and what was left out on purpose, so Dev states both before the handoff, and a deterministic gate checks the statement against the real diff. The record also carries the code-simplifier rationales (Step 3.6) that used to be discarded, and it feeds two later consumers: the `<scope-self-check>` block in the Phase 3 reviewer prefix and the PR body in Phase 4.
 
 ## The record
 
@@ -33,8 +33,8 @@ Output `{ok, justified, unjustified[], unlisted[], notDone}`. Exit 1 lists `unju
 
 ## Consumers
 
-- Phase 4 Step 2.2 renders file reasons, unjustified files and `notDone[]` into the shared reviewer prefix (`features/review-delta.md`).
-- Phase 6 Step 3 builds the PR `## Changes` bullets from `files[].reason` and lists `notDone[]` under `## Related` as "Follow-ups not done in this PR", merged with the final triage `deferred[]` (`channels/pr.md`).
+- Phase 3 Step 2.2 renders file reasons, unjustified files and `notDone[]` into the shared reviewer prefix (`features/review-delta.md`).
+- Phase 4 Step 3 builds the PR `## Changes` bullets from `files[].reason` and lists `notDone[]` under `## Related` as "Follow-ups not done in this PR", merged with the final triage `deferred[]` (`channels/pr.md`).
 
 ## Reference
 

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

@@ -13,7 +13,7 @@
 - [Preference](#preference)
 <!-- /toc -->
 
-> **TLDR**  -  Phase 4 Step 1.78 resolves, deterministically and before any reviewer runs, WHAT the changed code was supposed to honour: declared rule registries scoped to the diff's languages, in-repo module guides, and the toolchains those registries delegate to. The result is `criteria-manifest.json`: a bounded set of rule IDs that becomes the denominator for "was this applied completely". Reviewers answer per rule ID. An ID that is neither checked nor explicitly waived fails the stage.
+> **TLDR**  -  Phase 3 Step 1.78 resolves, deterministically and before any reviewer runs, WHAT the changed code was supposed to honour: declared rule registries scoped to the diff's languages, in-repo module guides, and the toolchains those registries delegate to. The result is `criteria-manifest.json`: a bounded set of rule IDs that becomes the denominator for "was this applied completely". Reviewers answer per rule ID. An ID that is neither checked nor explicitly waived fails the stage.
 
 ## Why this exists
 
@@ -88,7 +88,7 @@ Cheap, language-agnostic, and it answers "completely" head on  -  an exception i
 |---|---|
 | `detectedStack` (Phase 1) | language census of the diff by file extension. Describes what the diff CONTAINS, not what the repo is nominally built in, so one Objective-C bridging file in a Swift repo is classified correctly |
 | Phase 1 analysis summary (triage scope) | the task description plus the inline task list Phase 3 generated for itself |
-| Phase 2 plan | same inline task list |
+| Phase 1 plan | same inline task list |
 | `state.evidence.figma[]` (Step 1.8) | recorded as `not-applicable (no Phase 1 evidence)` |
 | Step 2.8 visual conformance | recorded as `not-applicable (no Phase 1 evidence)` |
 

package/pipeline/multi-agent-refs/features/stack-skill-routing.md

@@ -67,7 +67,7 @@ Append one `state.telemetry.skillCalls[]` entry per skill actually loaded:
 
 `routedBy` names the index and version that chose it. That is the difference between "the model happened to read a skill" and "the toolkit said this skill governs this task".
 
-What Phase 4 actually does with it, precisely: Step 1.78 lists these entries in the manifest under `ledger.routedByToolkit`, so a reviewer and the Phase 7 report can see which skills the project's own toolkit selected. It does **not** give them extra weight in the coverage maths. The deterministic resolver stays primary because an unrecorded load and no load are indistinguishable in state, and no `routedBy` tag changes that  -  the tag says who chose the skill, not that the code honoured it.
+What Phase 4 actually does with it, precisely: Step 1.78 lists these entries in the manifest under `ledger.routedByToolkit`, so a reviewer and the Phase 5 report can see which skills the project's own toolkit selected. It does **not** give them extra weight in the coverage maths. The deterministic resolver stays primary because an unrecorded load and no load are indistinguishable in state, and no `routedBy` tag changes that  -  the tag says who chose the skill, not that the code honoured it.
 
 ## Failure modes, and why none of them halt
 

package/pipeline/multi-agent-refs/features/verify-by-test.md

@@ -1,4 +1,4 @@
-# Feature: Verify-by-Test Triage (Phase 4 Step 3.7)
+# Feature: Verify-by-Test Triage (Phase 3 Step 3.7)
 
 **Pattern**: reviewer findings are hypotheses; a failing repro test is proof. Adversarial-review research (Refute-or-Promote, 2026) found that plausible-but-wrong findings survive debate rounds but die on a single empirical test. This step converts the highest-stakes verdicts (accepted blocking) from judgment into evidence before the Phase 3 rework loop fires.
 
@@ -19,7 +19,7 @@
 | Passes on some runs, fails on others | `inconclusive` | Flake, not proof either way. Finding stays accepted blocking, `verification.note = "flaky: passed k/N"`, repro test file deleted, telemetry line gains `flaky=<count>`. |
 | Compile error / timeout / not unit-testable | `inconclusive` | Finding stays accepted blocking (judgment stands). Partial test deleted, cause in `verification.note`. |
 
-Downgrades go to `deferred`, never `rejected`: triage judged the issue real, and deferred items surface in the Phase 7 report for a human eye.
+Downgrades go to `deferred`, never `rejected`: triage judged the issue real, and deferred items surface in the Phase 5 report for a human eye.
 
 ## Red-test handoff to Phase 3
 
@@ -27,7 +27,7 @@ Downgrades go to `deferred`, never `rejected`: triage judged the issue real, and
 
 ## Cleanup invariant
 
-After Step 3.7, the only uncommitted verifier artifacts are the confirmed repro tests listed in `redTests[]` (committed later with the fix) and logs under `$WORKTREE/.pipeline/` (outside Phase 6 commit scope). `not-reproduced` and `inconclusive` test files are always deleted.
+After Step 3.7, the only uncommitted verifier artifacts are the confirmed repro tests listed in `redTests[]` (committed later with the fix) and logs under `$WORKTREE/.pipeline/` (outside Phase 4 commit scope). `not-reproduced` and `inconclusive` test files are always deleted.
 
 ## Telemetry
 
@@ -39,4 +39,4 @@ Adds one Sonnet call plus up to `maxFindings` single-test runs (and build-lock c
 
 ## Reference
 
-Wiring: `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` Step 3.7. Schema: `$HOME/.claude/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `$HOME/.claude/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` (including `repeatCount`) in `$HOME/.claude/schemas/prefs.schema.json`.
+Wiring: `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` Step 3.7. Schema: `$HOME/.claude/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `$HOME/.claude/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` (including `repeatCount`) in `$HOME/.claude/schemas/prefs.schema.json`.

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

@@ -0,0 +1,83 @@
+# verify - is this install the thing that was published
+
+The install is a COPY. `install.js` writes the pipeline tree into `~/.claude`,
+`~/.copilot` and `~/.codex`, and from that moment the two halves drift
+independently. Both directions produce bugs that are hard to name:
+
+- an edit made in the installed copy is a behaviour with no source, and the next
+  update silently reverts it;
+- a file the installer failed to write is a script the docs describe and nobody
+  has, which reads as a documentation error.
+
+`multi-agent-pipeline verify` answers both mechanically.
+
+```bash
+npx @mmerterden/multi-agent-pipeline verify              # package + install
+npx @mmerterden/multi-agent-pipeline verify --package    # package integrity only
+npx @mmerterden/multi-agent-pipeline verify --install    # install drift only
+npx @mmerterden/multi-agent-pipeline verify --json
+```
+
+| Code | Meaning |
+|---|---|
+| 0 | everything matches |
+| 1 | a difference was found, named file by file |
+| 2 | nothing to verify - a source checkout, or a version published before manifests existed |
+
+Exit 2 is not a pass and not a failure. A dev checkout has no manifest by
+design, and reporting that as either would be a lie in one direction or the
+other.
+
+## The manifest
+
+`manifest.json` is written at pack time by `prepack`, never committed. A
+manifest in git is stale one commit after it is written, and a stale manifest
+reports honest edits as tampering - which is worse than having none, because
+people learn to ignore it.
+
+The file list is not guessed. It comes from `npm pack --dry-run --json`, so by
+construction it is the same set npm publishes, `files` globs and all. The gate
+asserts the two counts agree, which is what catches a `files` entry and a
+manifest that have stopped describing the same package.
+
+Two things it cannot cover, said here rather than discovered later: it cannot
+hash itself, and a signature over it does not authenticate the tarball.
+
+## What a green result proves, and what it does not
+
+It proves the bytes match what the publisher recorded. It is not proof of WHO
+published them. The manifest, the signature and the verifier all travel inside
+the same tarball, so anyone able to rewrite one can rewrite the others.
+Provenance belongs to npm's own integrity field.
+
+What this does catch is the set of failures that actually happen: a damaged or
+partial install, a file edited after install, and an update that did not land.
+
+Signing is optional. `make-manifest.mjs --sign` reads an ed25519 private key
+from the credential store (or `MULTI_AGENT_SIGNING_KEY` on a build host with no
+store) and writes `manifest.sig`; `verify` checks it against
+`MULTI_AGENT_SIGNING_PUBKEY` when one is pinned. Without a key it says "signed,
+no public key to check it against" rather than claiming valid - a signature
+nobody can check is not a signature that passed.
+
+## How each tree is compared
+
+| Tree | Mode | Why |
+|---|---|---|
+| `scripts` | bytes | verbatim copy, minus the dev-only set |
+| `lib` | bytes | verbatim copy |
+| `multi-agent-refs` | bytes | verbatim copy |
+| `agents` | bytes | verbatim copy |
+| `commands/multi-agent` | presence | `install.js` rewrites each SKILL.md `description` into the user's `outputLanguage` |
+
+Byte-comparing `commands/` reports every command as drift on a perfectly
+healthy machine. Measured here: all 57 command files differ, and 56 of them
+differ by nothing except the translated description. A report that is wrong by
+default is a report nobody reads.
+
+The dev-only filter matters just as much: smokes, linters and fixtures ship in
+the package and are deliberately NOT installed. Without excluding them, `verify`
+would report 252 files as "the installer skipped this".
+
+`~/.copilot` and `~/.codex` are reported as present, not compared: the installer
+rewrites paths for both on purpose, so a byte difference there is the design.

package/pipeline/multi-agent-refs/features/visual-evidence.md

@@ -3,7 +3,7 @@
 <!-- toc -->
 - [1. When it is required](#1-when-it-is-required)
 - [2. Before  -  the reporter's screenshot, or nothing](#2-before---the-reporters-screenshot-or-nothing)
-- [3. After  -  Phase 3, not Phase 5](#3-after---phase-3-not-phase-5)
+- [3. After  -  Phase 2, not the Phase 3 user test](#3-after---phase-2-not-the-phase-3-user-test)
 - [4. Video  -  the recording rides on a test run](#4-video---the-recording-rides-on-a-test-run)
 - [5. Size, and what happens when it does not fit](#5-size-and-what-happens-when-it-does-not-fit)
 - [5b. Where the artefacts live  -  the host](#5b-where-the-artefacts-live---the-host)
@@ -18,10 +18,10 @@ This contract makes the pipeline carry the picture: the state the reporter saw,
 the state the fix produces, and where possible a recording of the flow running.
 
 The artefacts live as **Jira attachments** and are referenced from two places -
-the Phase 7 Jira comment, where the picture belongs next to the work summary and
+the Phase 5 Jira comment, where the picture belongs next to the work summary and
 the test scenarios, and the PR body, which tells the reviewer they exist.
 
-Consumers: Phase 3 (capture), Phase 5 (video, preferred host), Phase 6 (blocker),
+Consumers: Phase 2 (capture), Phase 3 (video, user test), Phase 4 (blocker),
 `channels/jira.md` and `channels/pr.md` (render). Gate: `smoke-visual-evidence.sh`.
 
 ## 1. When it is required
@@ -49,16 +49,16 @@ artefact is absent, the absence is written down with its reason (section 5).
 
 **Phase 0 Step 7.7 writes `required`, `requiredBy` and `platform`**, before it
 probes. Naming the writer is not a formality: five phases read these three fields
-and nothing set them, so `required` was never true, Step 7.7 never ran, Phase 3
-never captured, and Phase 6's blocker never blocked. A contract with readers and
+and nothing set them, so `required` was never true, Step 7.7 never ran, Phase 2
+never captured, and Phase 4's blocker never blocked. A contract with readers and
 no writer reads exactly like a contract that is satisfied.
 
 Phase 0 has no diff, so it decides on what it actually knows - `taskType` and
 whether the intake carried a Figma reference - and that is enough for the whole
 design-work row. The `bugfix` row needs a changed-file list, so Phase 0 records
-it as provisional (`requiredBy: "bugfix (pending diff)"`) and **Phase 3 re-decides
+it as provisional (`requiredBy: "bugfix (pending diff)"`) and **Phase 2 re-decides
 from the real diff** before capturing. A provisional `false` never suppresses the
-Phase 3 decision.
+Phase 2 decision.
 
 ### 1b. The platform, and when there is not one
 
@@ -120,15 +120,15 @@ No image on the ticket means no "before". Record the gap
 (`before_missing: "ticket carries no image attachment"`) and continue. The
 section still renders, saying so.
 
-## 3. After  -  Phase 3, not Phase 5
+## 3. After  -  Phase 2, not the Phase 3 user test
 
-Phase 5 is the natural home: the simulator is already up. It is also **dropped by
-every `autopilot` and `--local` entry** (`phase-5-test.md` TLDR), so a capture
+The user test is the natural home: the simulator is already up. It is also **dropped by
+every `autopilot` and `--local` entry** (`phase-3-review.md` TLDR), so a capture
 that lives only there produces nothing for unattended runs - which are exactly
 the runs where nobody watched the screen.
 
-The capture therefore happens in **Phase 3, after the build+test gate passes**,
-which is in every mode's phase set. Phase 5 may add richer evidence on top; it is
+The capture therefore happens in **Phase 2, after the build+test gate passes**,
+which is in every mode's phase set. The Phase 3 user test may add richer evidence on top; it is
 never the only source.
 
 ```bash
@@ -192,8 +192,8 @@ The recorder itself is `capture-evidence.sh video start|stop`, which writes
 `<task-id>[-<label>]-flow.mp4` into the evidence directory. The label is optional
 because one recording per task is the common case, and both renderers cite the
 unlabelled form. It is shell rather than MCP for three reasons: the sibling still capture already shells out,
-a host with no toolkit MCP registered still produces evidence, and Phase 3 and
-Phase 5 are exactly where an MCP call is contested.
+a host with no toolkit MCP registered still produces evidence, and Phase 2 and
+Phase 3 are exactly where an MCP call is contested.
 
 **iOS UI test targets are not named, they are detected.** A path containing
 `UITests` is not the signal: in the reference app 477 files sit under such a path
@@ -210,8 +210,8 @@ wearing a measurement's clothes.
 
 ### 4.4 Re-check before recording
 
-The probe runs at intake and the recording happens in Phase 3. A simulator booted
-then can be gone by the time the build goes green, so Phase 3 re-measures the
+The probe runs at intake and the recording happens in Phase 2. A simulator booted
+then can be gone by the time the build goes green, so Phase 2 re-measures the
 device row alone and downgrades the tier if it has to, recording the transition
 (`tier 1 -> 3: simulator no longer booted`). A tier taken from a stale
 measurement is a promise the run cannot keep.
@@ -232,7 +232,7 @@ never asserted against wall clock anywhere, because doing so fails a correct
 capture of a static screen.
 
 `visualEvidence.enabled` turns the whole feature off - capture, upload, both
-render sections and the Phase 6 blocker with it.
+render sections and the Phase 4 blocker with it.
 
 ### 4.6 Web - the recorder IS the runner
 
@@ -283,7 +283,7 @@ Never silently attach nothing.
 
 ## 5b. Where the artefacts live  -  the host
 
-Resolved in Phase 6 Step 2.9, recorded as `state.visualEvidence.host`:
+Resolved in Phase 4 Step 2.9, recorded as `state.visualEvidence.host`:
 
 | Order | Host | Condition | Stills | Video |
 |---|---|---|---|---|
@@ -342,7 +342,7 @@ where it lives - the images themselves stay on the ticket:
 ## 7. Blocker
 
 When section 1 says required and `state.visualEvidence` carries neither an
-artefact nor a recorded reason for its absence, **Phase 6 Step 3 blocks** - the
+artefact nor a recorded reason for its absence, **Phase 4 Step 3 blocks** - the
 same shape as the `risk` section blocker. A recorded reason is enough to pass:
 the gate is against silence, not against an honest "no image on the ticket".
 

package/pipeline/multi-agent-refs/features/worktree-finalize.md

@@ -1,6 +1,6 @@
 # Worktree finalize  -  removing a task's worktree once its PR is open
 
-> **TLDR**  -  Phase 6 step 9. Once the PR exists the worktree is dead weight, so it is removed: artefacts are salvaged into the log dir first, the branch is kept and deliberately NOT checked out, and every destructive path is gated. Gated by `prefs.global.settings.worktreeAutoRemoveOnPr` (default **true**). Script: `worktree-finalize.sh`.
+> **TLDR**  -  Phase 4 step 9. Once the PR exists the worktree is dead weight, so it is removed: artefacts are salvaged into the log dir first, the branch is kept and deliberately NOT checked out, and every destructive path is gated. Gated by `prefs.global.settings.worktreeAutoRemoveOnPr` (default **true**). Script: `worktree-finalize.sh`.
 
 ## Why it exists
 
@@ -21,12 +21,12 @@ Removing it at PR-open is only safe because of the salvage, so the two are one s
 | Condition | Why it blocks |
 |---|---|
 | `worktreePath == projectRoot` (`--local` mode) | there is no worktree; removing it would delete the user's checkout |
-| cwd is inside the worktree | a shell left on a deleted inode is worse than a leftover directory, and Phase 6 legitimately `cd`s into the worktree earlier |
+| cwd is inside the worktree | a shell left on a deleted inode is worse than a leftover directory, and Phase 4 legitimately `cd`s into the worktree earlier |
 | not a registered worktree of the project root | a mistyped path must not delete an unrelated directory |
 | real uncommitted changes | never discarded; see the artefact carve-out below |
 | HEAD not on the remote | removing a worktree whose commits exist nowhere else is data loss, not cleanup |
 
-Exit codes: `0` removed, `3` skipped with a reason (report and continue to Phase 7), `1` usage error.
+Exit codes: `0` removed, `3` skipped with a reason (report and continue to Phase 5), `1` usage error.
 
 ### The artefact carve-out, and why `--untracked-files=no` is wrong
 
@@ -49,10 +49,10 @@ This is why the removal is safe:
 
 | Consumer | Reads | Without salvage |
 |---|---|---|
-| Phase 7 triage-memory ingest | `triage-output.json` | `[ -f ]`-guarded, so it degrades **silently**: the triage corpus and learnings ledger stop being fed and no error appears. Since v16.20.0 Phase 4 writes `triage-output.json` itself (Step 3.2.1, the latest copy of `.pipeline/triage-round-<N>.json`), so the salvage is a second copy, not the only bridge |
-| Phase 7 learnings-ledger distill | same file | same silent degradation |
+| Phase 5 triage-memory ingest | `triage-output.json` | `[ -f ]`-guarded, so it degrades **silently**: the triage corpus and learnings ledger stop being fed and no error appears. Since v16.20.0 Phase 4 writes `triage-output.json` itself (Step 3.2.1, the latest copy of `.pipeline/triage-round-<N>.json`), so the salvage is a second copy, not the only bridge |
+| Phase 5 learnings-ledger distill | same file | same silent degradation |
 | `render-work-summary.sh` | `agent-state.json`, `phase-tracker.json` (falls back to `logs/multi-agent/<task>/tracker-state.json`, which survives removal) | loses the salvaged copies but keeps the tracker via the logs fallback |
-| `:resume` | `agent-state.json` | cannot continue a Phase 7 pause |
+| `:resume` | `agent-state.json` | cannot continue a Phase 5 pause |
 | `:status`, `:log` | `agent-state.json` | the task becomes invisible |
 
 `state.worktreeRemovedAt` and `state.artifactsPath` record the outcome. The timestamp is what tells a reader that a worktree-less task was finished-and-tidied rather than killed  -  without it, a missing worktree is indistinguishable from a broken run.

package/pipeline/multi-agent-refs/issue-jira-triad.md

@@ -3,15 +3,15 @@
 <!-- toc -->
 - [The triad at a glance](#the-triad-at-a-glance)
 - [Phase 0 auto-create policy](#phase-0-auto-create-policy)
-- [Phase 7 wiki → Jira comment](#phase-7-wiki-jira-comment)
+- [Phase 5 wiki → Jira comment](#phase-5-wiki-jira-comment)
 - [Autopilot behaviour](#autopilot-behaviour)
 - [Preferences involved](#preferences-involved)
 - [Cross-CLI parity](#cross-cli-parity)
 <!-- /toc -->
 
-> **TLDR**  -  When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 7 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
+> **TLDR**  -  When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 5 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
 
-This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.
+This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.
 
 ## The triad at a glance
 
@@ -24,7 +24,7 @@ Jira issue (new, linked both ways)
      ▼  Phase 3  -  component implementation
 wiki markdown in pipeline/skills/...
      │
-     ▼  Phase 7 Report Step 2  -  wiki capture + Jira comment post
+     ▼  Phase 5 Report Step 2  -  wiki capture + Jira comment post
 Jira comment (humanizer'd component summary)
 ```
 
@@ -59,13 +59,13 @@ Decision table:
 5. On success: store new Jira key in `state.jiraId`. Emit `→ created Jira {newKey}`.
 6. Patch the GitHub issue body: append a line `Jira: [{newKey}]({jira.baseUrl}/browse/{newKey})` so the bidirectional link is visible on GitHub without refetching the pipeline state.
 
-**Skip path** (`never` or user declined): Branch falls back to `feature/GH{issueNo}-{kebab}`; Phase 7 later emits `→ no Jira linked (policy: {preference})`.
+**Skip path** (`never` or user declined): Branch falls back to `feature/GH{issueNo}-{kebab}`; Phase 5 later emits `→ no Jira linked (policy: {preference})`.
 
 **Failure isolation:** Jira API 5xx or network error → log the error, warn the user, and **continue with no Jira link** (do not halt Phase 0). Rationale: a transient Jira outage should not block code work; user can link manually post-hoc.
 
-## Phase 7 wiki → Jira comment
+## Phase 5 wiki → Jira comment
 
-Runs after Phase 7 Report Step 2 (wiki capture) has produced markdown and only when:
+Runs after Phase 5 Report Step 2 (wiki capture) has produced markdown and only when:
 
 - `state.jiraId` is non-null (from Phase 0 scan or auto-create).
 - `prefs.global.wikiToJiraComment !== false` (default true).
@@ -78,9 +78,9 @@ Flow:
 3. Render as Jira comment: title line (`h3. Component docs  -  {componentName}`) + an overview paragraph + a link to the full page (wiki URL, if the adapter returned `pushedRemote`). The overview lines come from a Markdown file  -  convert them via the `channels/jira.md` table before POST, exactly like the title line already is, then run the whole body through `node "$HOME/.claude/scripts/jira-wiki-escape.mjs"` per that file's *Emoticon escaping* section.
 4. **Run through the humanizer skill**  -  same policy as Step 4 Confluence: user-facing content must read naturally.
 5. `POST {jira.baseUrl}/rest/api/2/issue/{jiraId}/comment`.
-6. Log: `Phase 7: wiki summary posted to Jira {jiraId}`.
+6. Log: `Phase 5: wiki summary posted to Jira {jiraId}`.
 
-On failure: log + continue. Wiki is already written; the Jira comment is an augmentation. Don't regress Phase 7 over a Jira 5xx.
+On failure: log + continue. Wiki is already written; the Jira comment is an augmentation. Don't regress Phase 5 over a Jira 5xx.
 
 ## Autopilot behaviour
 
@@ -96,7 +96,7 @@ Rationale: autopilot is explicit consent for side-effect creation; muting Jira a
 | key | type | default | controls |
 |---|---|---|---|
 | `prefs.global.autoJiraFromGithubIssue` | enum ask/always/never | `ask` | Phase 0 auto-create decision |
-| `prefs.global.wikiToJiraComment` | bool | `true` | Phase 7 wiki → Jira comment post |
+| `prefs.global.wikiToJiraComment` | bool | `true` | Phase 5 wiki → Jira comment post |
 | `figmaConfig.jira.projectKey` | string |  -  | Target project for new issues (falls back to `prefs.global.defaultJiraKey`) |
 | `prefs.global.keychainMapping.jira` | string |  -  | Jira token keychain lookup |
 

package/pipeline/multi-agent-refs/knowledge.md

@@ -30,11 +30,11 @@ $HOME/.claude/knowledge/
 ### How It Works
 
 ```
-Task 1 (first time): Phase 1 -> full Explore -> Phase 7 -> create knowledge
-Task 2:             Phase 1 -> read knowledge -> targeted Explore -> Phase 7 -> update knowledge
-Task 3:             Phase 1 -> read knowledge -> minimal Explore -> Phase 7 -> update knowledge
+Task 1 (first time): Phase 1 -> full Explore -> Phase 5 -> create knowledge
+Task 2:             Phase 1 -> read knowledge -> targeted Explore -> Phase 5 -> update knowledge
+Task 3:             Phase 1 -> read knowledge -> minimal Explore -> Phase 5 -> update knowledge
   ...
-Task N:             Phase 1 -> knowledge sufficient -> SKIP Explore -> Phase 7 -> update knowledge
+Task N:             Phase 1 -> knowledge sufficient -> SKIP Explore -> Phase 5 -> update knowledge
 ```
 
 Each task teaches the project a bit more. Token cost decreases over time.
@@ -45,7 +45,7 @@ Each task teaches the project a bit more. Token cost decreases over time.
 | ------------------------------------------- | --------------------- | ------------------------------------------ | ------------------------ |
 | `$PROJECT_ROOT/CLAUDE.md`                   | User                  | Project rules, build commands              | Persistent (in git)      |
 | Auto Memory (`~/.claude/projects/`)         | Claude (automatic)    | User preferences, feedback                 | Persistent (global)      |
-| **Knowledge Base** (`~/.claude/knowledge/`) | Multi-agent (Phase 7) | Architecture, patterns, gotchas, decisions | Persistent (per-project) |
+| **Knowledge Base** (`~/.claude/knowledge/`) | Multi-agent (Phase 5) | Architecture, patterns, gotchas, decisions | Persistent (per-project) |
 
 They all complement each other  -  no conflicts.
 
@@ -54,7 +54,7 @@ They all complement each other  -  no conflicts.
 A Short run skips Phase 1, but knowledge **is still read**:
 
 - Knowledge files are added to the prompt before the Opus agent starts in Phase 3
-- Knowledge capture is still performed in Phase 7 (simplified report)
+- Knowledge capture is still performed in Phase 5 (simplified report)
 
 ### Knowledge Maintenance
 
@@ -107,18 +107,18 @@ When calling sub-agents, inject task-specific context from previous phases:
 ### Phase -> Agent -> Context Flow
 
 ```
-Phase 1: Analysis
+Phase 1: Plan (analysis)
   -- Explore agents (parallel) -> codebase scan
 
-Phase 2: Planning
+Phase 1: Plan
   -- Architecture review agent
        Context: task description + Phase 1 findings + affected modules
 
-Phase 3: Dev
+Phase 2: Dev
   -- Sonnet agent (TDD)
-       Context: Phase 2 plan + task dependencies
+       Context: Phase 1 plan + task dependencies
 
-Phase 4: Review (CLI-aware parallel + triage)
+Phase 3: Review (CLI-aware parallel + triage)
   Claude Code (3 parallel):
     |-- Reviewer (opus)   -> security + architecture
     +-- Reviewer (sonnet) -> quality + correctness + edge cases