@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/multi-agent-refs/multi-repo-integration-build.md

@@ -7,7 +7,7 @@
 - [Auto-run steps (when host is learned)](#auto-run-steps-when-host-is-learned)
 - [Error evaluation contract](#error-evaluation-contract)
 - [Autopilot behavior](#autopilot-behavior)
-- [Phase 7 knowledge capture](#phase-7-knowledge-capture)
+- [Phase 5 knowledge capture](#phase-5-knowledge-capture)
 - [Generic rule (for copilot-instructions.md)](#generic-rule-for-copilot-instructionsmd)
 - [Schema](#schema)
 - [Smoke coverage](#smoke-coverage)
@@ -27,7 +27,7 @@ Codegen outputs (identifiers, localization keys, tokens) in Repo A get reference
 
 ## When this rule fires
 
-In Phase 6 (Commit & PR), **before** the pre-commit local checkout prompt, if `state.projects.length >= 2`:
+In Phase 4 (Commit & PR), **before** the pre-commit local checkout prompt, if `state.projects.length >= 2`:
 
 1. Compute `repoSet` = sorted array of touched repo names.
 2. Look up `prefs.global.multiRepoIntegrationHosts` for an entry whose `repoSet` (sorted) equals this combo.
@@ -100,7 +100,7 @@ Persist to `prefs.global.multiRepoIntegrationHosts[]`:
 
 ## Auto-run steps (when host is learned)
 
-Progress-contract line `→ integrating <host-scheme> with <N> submodules`. Tracker sub-step on Phase 6 to show live status: `phase-tracker.sh sub 6 0 "Integration build" in_progress`.
+Progress-contract line `→ integrating <host-scheme> with <N> submodules`. Tracker sub-step on Phase 4 to show live status: `phase-tracker.sh sub 4 0 "Integration build" in_progress`.
 
 ```bash
 HOST="$(jq -r --arg key "$repoSet_sorted_joined" \
@@ -126,12 +126,12 @@ BUILD_ERRORS=$(eval "$BUILD_CMD" 2>&1 | grep -E "error:|FAILURE:|error FS" || tr
 
 # 4. Evaluate + decide
 if [ -z "$BUILD_ERRORS" ]; then
-  phase-tracker.sh sub 6 0 "Integration build" completed
-  log "Phase 6.0: Integration build  -  clean"
+  phase-tracker.sh sub 4 0 "Integration build" completed
+  log "Phase 4.0: Integration build  -  clean"
   # proceed to pre-commit checkout prompt + commit
 else
-  phase-tracker.sh sub 6 0 "Integration build" failed
-  log "Phase 6.0: Integration build  -  NEW errors detected"
+  phase-tracker.sh sub 4 0 "Integration build" failed
+  log "Phase 4.0: Integration build  -  NEW errors detected"
   # show errors, ask user
 fi
 ```
@@ -150,13 +150,13 @@ Three outcomes after the build:
    Integration build failed with N new errors. Pipeline can go back to
    Phase 3 to fix, or you can fix manually and tell the pipeline to retry.
 
-   [1] Return to Phase 3: Dev with these errors as input (auto-fix attempt)
+   [1] Return to Phase 2: Dev with these errors as input (auto-fix attempt)
    [2] Pause  -  I'll fix manually, then /multi-agent resume
-   [3] Override  -  proceed to commit anyway (logs a warning in Phase 7 report)
+   [3] Override  -  proceed to commit anyway (logs a warning in Phase 5 report)
 
    Select [1-3]:
    ```
-3. **Pre-existing errors (unrelated to this task)** → if the pipeline has a baseline error count (from a clean pre-change build), compare deltas. When `current_errors <= baseline`, treat as **no new errors** and proceed; log the pre-existing count in Phase 7 Report.
+3. **Pre-existing errors (unrelated to this task)** → if the pipeline has a baseline error count (from a clean pre-change build), compare deltas. When `current_errors <= baseline`, treat as **no new errors** and proceed; log the pre-existing count in Phase 5 Report.
 
 ---
 
@@ -164,13 +164,13 @@ Three outcomes after the build:
 
 Autopilot skips the "Override / pause" prompt. If `count` < 3 on this combo (new / low-confidence), autopilot treats a build failure as BLOCKING and returns to Phase 3 automatically (option 1). If `count >= 3` and `lastResult == success`, a new failure is treated as blocking the same way  -  but with lower surprise since we've seen this combo succeed before.
 
-The learn-once prompt itself also skips under autopilot: instead, autopilot logs `"Phase 6.0: SKIPPED  -  no learned host for this combo, autopilot refuses to prompt. Run in normal mode once to teach."` and proceeds. This is explicit and recoverable.
+The learn-once prompt itself also skips under autopilot: instead, autopilot logs `"Phase 4.0: SKIPPED  -  no learned host for this combo, autopilot refuses to prompt. Run in normal mode once to teach."` and proceeds. This is explicit and recoverable.
 
 ---
 
-## Phase 7 knowledge capture
+## Phase 5 knowledge capture
 
-When a learn-once prompt writes a new entry, Phase 7 Step 5 (knowledge + memory) ALSO writes a project-scoped memory:
+When a learn-once prompt writes a new entry, Phase 5 Step 5 (knowledge + memory) ALSO writes a project-scoped memory:
 
 ```
 Type: reference

package/pipeline/multi-agent-refs/payload-contracts.md

@@ -1,26 +1,26 @@
 ---
-description: "Canonical required-reading list for outward-facing payloads (PR body, Jira comment, closing report) plus the markup dialect per surface. Loaded by every mode that runs Phase 6 or Phase 7."
+description: "Canonical required-reading list for outward-facing payloads (PR body, Jira comment, closing report) plus the markup dialect per surface. Loaded by every mode that runs Phase 4 or Phase 5."
 ---
 
 # Outward-facing payload contracts
 
 > Every mode that opens a PR, comments on a tracker, or closes out a run reads this file first. It does not restate the contracts  -  it names them, so no mode has to carry its own copy and drift from the others.
 
-## Read before Phase 6
+## Read before Phase 4
 
 | Read | Before | Governs |
 |---|---|---|
 | [`channels/pr.md`]($HOME/.claude/multi-agent-refs/channels/pr.md) | assembling the PR body | fixed section set (`summary` → `changes` → `architecture` cond. → `verification` → `risk` cond. → `dependencies` cond. → `related`), Markdown-only rule, reviewer-preserving Bitbucket PUT payload |
-| [`phases/phase-6-commit.md`]($HOME/.claude/multi-agent-refs/phases/phase-6-commit.md) | committing | commit convention, default-reviewer fetch, draft/ready prompt, push-must-succeed loop |
+| [`phases/phase-4-commit.md`]($HOME/.claude/multi-agent-refs/phases/phase-4-commit.md) | committing | commit convention, default-reviewer fetch, draft/ready prompt, push-must-succeed loop |
 | [`rules.md`]($HOME/.claude/multi-agent-refs/rules.md) "External System Outputs" | any REST payload | real newlines, no HTML entities, no hand-rolled JSON, markup dialect per surface |
 
-## Read before Phase 7
+## Read before Phase 5
 
 | Read | Before | Governs |
 |---|---|---|
 | [`channels/jira.md`]($HOME/.claude/multi-agent-refs/channels/jira.md) | posting the Jira comment | fixed section set incl. **Test Scenarios** (Given/When/Then, always present), markdown→wiki conversion table |
 | [`channels/confluence.md`]($HOME/.claude/multi-agent-refs/channels/confluence.md) | writing a Confluence page | storage-format conversion, endpoint flavor |
-| [`phases/phase-7-report.md`]($HOME/.claude/multi-agent-refs/phases/phase-7-report.md) | closing out | Timeline + Agent Activity + Cost Breakdown tables, missing-telemetry disclosure |
+| [`phases/phase-5-report.md`]($HOME/.claude/multi-agent-refs/phases/phase-5-report.md) | closing out | Timeline + Agent Activity + Cost Breakdown tables, missing-telemetry disclosure |
 | [`tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md) | every phase boundary | per-phase token narration, completion tile suffix |
 
 ## Markup dialect per surface
@@ -44,12 +44,12 @@ A payload that is in the right language but the wrong dialect is a defect of the
 
 The run ends with the phase tracker glyph block **and** the numbers behind it  -  per-phase duration and token spend, plus totals.
 
-- Record spend as you go: `phase-tracker.sh tokens <N> <in> <out> [cached]` after **every** LLM call, including each Phase 4 reviewer subagent and each Phase 3 chunk. Counts are additive and nothing reconstructs them after the fact.
+- Record spend as you go: `phase-tracker.sh tokens <N> <in> <out> [cached]` after **every** LLM call, including each Phase 3 reviewer subagent and each Phase 3 chunk. Counts are additive and nothing reconstructs them after the fact.
 - Tag the model once per phase (`phase-tracker.sh model <N> <name>`) or the cost helper cannot price it and prints `-`.
 - Durations come from the phase timestamps and survive a missed `tokens` call; token spend does not.
 - If any phase has no token data, name those phases and say their cost is unavailable. Never print a report whose cost section is simply absent  -  the reader cannot tell "cheap run" from "nobody recorded it".
 
-### Missing-telemetry disclosure (Phase 7, required)
+### Missing-telemetry disclosure (Phase 5, required)
 
 Before composing the report, compute which phases carry no token data:
 
@@ -64,4 +64,4 @@ Non-empty `UNTRACKED` → both the agent-log report and the closing chat summary
 
 ## Fast modes are not exempt
 
-A Short run skips Analysis and Planning, and the autopilot and local entries skip the interactive test gate. They run Phase 6 and Phase 7 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.
+A Short run skips Analysis and Planning, and the autopilot and local entries skip the interactive test gate. They run Phase 4 and Phase 5 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.

package/pipeline/multi-agent-refs/phases/log-format.md

@@ -33,13 +33,13 @@ Create at `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-log.md`:
 ## Phase Duration Distribution
 
 Phase 0: Init ████░░░░░░░░░░░░ 5s
-Phase 1: Analysis ██████░░░░░░░░░░ 12s
-Phase 2: Planning █████░░░░░░░░░░░ 8s
-Phase 3: Dev ████████████████ 2m 35s
-Phase 4: Review ████████░░░░░░░░ 37s
-Phase 5: Test ██░░░░░░░░░░░░░░ (user wait)
-Phase 6: Commit ██░░░░░░░░░░░░░░ 3s
-Phase 7: Report █░░░░░░░░░░░░░░░ 2s
+Phase 1: Plan (analysis) ██████░░░░░░░░░░ 12s
+Phase 1: Plan █████░░░░░░░░░░░ 8s
+Phase 2: Dev ████████████████ 2m 35s
+Phase 3: Review ████████░░░░░░░░ 37s
+Phase 3: Review (user test) ██░░░░░░░░░░░░░░ (user wait)
+Phase 4: Commit ██░░░░░░░░░░░░░░ 3s
+Phase 5: Report █░░░░░░░░░░░░░░░ 2s
 
 ## Review Iterations
 
@@ -62,7 +62,7 @@ Verdict: unverified (3 reviewers)
 
 ## Cost Breakdown
 
-(emit by Phase 7 via `$HOME/.claude/scripts/render-agent-log-cost.sh <task-id>`. Renders unconditionally on every run. If the renderer exits 2 (no tracker data + no OTel spans), Phase 7 omits this section without failing the run.)
+(emit by Phase 5 via `$HOME/.claude/scripts/render-agent-log-cost.sh <task-id>`. Renders unconditionally on every run. If the renderer exits 2 (no tracker data + no OTel spans), Phase 5 omits this section without failing the run.)
 
 | Phase | Model | Tokens in | Tokens out | Est. USD |
 | ----- | ----- | --------- | ---------- | -------- |
@@ -86,7 +86,7 @@ Verdict: unverified (3 reviewers)
 
 ### Cost Breakdown  -  emission contract
 
-Phase 7 MUST attempt to render the Cost Breakdown section as part of the agent-log compose step:
+Phase 5 MUST attempt to render the Cost Breakdown section as part of the agent-log compose step:
 
 ```bash
 COST_BLOCK=$(bash $HOME/.claude/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
@@ -97,7 +97,7 @@ Emission is best-effort  -  exit 2 (no data) is silently skipped. Never fail the
 
 ### Tokens telemetry  -  phase responsibility
 
-Every phase that dispatches a billable LLM agent MUST forward its token totals to the tracker. The minimal contract (already enforced via `smoke-tracker-contract.sh` for Phase 4):
+Every phase that dispatches a billable LLM agent MUST forward its token totals to the tracker. The minimal contract (already enforced via `smoke-tracker-contract.sh` for Phase 3):
 
 ```bash
 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" <phase-id> <event> \

package/pipeline/multi-agent-refs/phases/modes.md

@@ -31,27 +31,27 @@ Autopilot mode skips interactive confirmations and runs the pipeline end-to-end
 
 | Phase               | Normal (full)                                           | autopilot (full)                            | local (full)                                | local autopilot (full)                      |
 | ------------------- | ------------------------------------------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- |
-| Phase 2 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop  -  user: approve/abort/free-text edit | **Gate skip**  -  log the plan, proceed directly to Phase 3 (autopilot contract: zero interaction) | Same as Normal | Same as autopilot |
-| Phase 5 (User Test) | Interactive prompt ("Want to test?" -> wait)            | Skip (autopilot suppresses interactive prompts) -> proceed directly to Phase 6 | **Not in the phase set** (the gate checks the change out of a worktree; local has none) | Not in the phase set |
-| Phase 6 (Commit)    | "Want to commit?" -> wait                               | Auto commit + push                          | "Want to commit?" -> wait                   | Auto commit + push                          |
-| Phase 6 (PR)        | "Want to open a PR?" -> wait                            | Auto create PR                              | "Want to open a PR?" -> wait                | Auto create PR                              |
-| **Phase 7 (Channels)**  | Multi-select channel + content menu                 | **STILL PAUSES**  -  see "Phase 7 autopilot exception" below | Multi-select (same as Normal) | **STILL PAUSES** (same as autopilot) |
+| Phase 1 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop  -  user: approve/abort/free-text edit | **Gate skip**  -  log the plan, proceed directly to Phase 2 (autopilot contract: zero interaction) | Same as Normal | Same as autopilot |
+| Phase 3 (User Test) | Interactive prompt ("Want to test?" -> wait)            | Skip (autopilot suppresses interactive prompts) -> proceed directly to Phase 4 | **Not in the phase set** (the gate checks the change out of a worktree; local has none) | Not in the phase set |
+| Phase 4 (Commit)    | "Want to commit?" -> wait                               | Auto commit + push                          | "Want to commit?" -> wait                   | Auto commit + push                          |
+| Phase 4 (PR)        | "Want to open a PR?" -> wait                            | Auto create PR                              | "Want to open a PR?" -> wait                | Auto create PR                              |
+| **Phase 5 (Channels)**  | Multi-select channel + content menu                 | **STILL PAUSES**  -  see "Phase 5 autopilot exception" below | Multi-select (same as Normal) | **STILL PAUSES** (same as autopilot) |
 
 **What NEVER skips (even in autopilot):**
 
-- Phase 4 Review -> if blocking finding, returns to Phase 3, auto fix + rebuild (safety)
+- Phase 3 Review -> if blocking finding, returns to Phase 2, auto fix + rebuild (safety)
 - Kill/Purge confirmations -> destructive operations always ask
 - Build fail -> auto fix + rebuild (max 3 retries). After 3 retries still failing -> pause, ask user
 - **Circuit-breaker** -> autopilot halts (records reason, waits for `resume`) on a no-progress stall, an identical repeated failure, a rework storm, cost drift past the `costBudget` ceiling, or a merge/rebase conflict. Full wiring: `$HOME/.claude/multi-agent-refs/features/autopilot-circuit-breaker.md`. This is the sanctioned autopilot pause  -  continuing unattended off the happy path is the less safe choice.
-- **Phase 7 channels dispatch** -> always pauses for multi-select. Rationale: Jira/Confluence are externally visible; silently posting wrong-tone content leaks team-visible artifacts. See below.
+- **Phase 5 channels dispatch** -> always pauses for multi-select. Rationale: Jira/Confluence are externally visible; silently posting wrong-tone content leaks team-visible artifacts. See below.
 
 **State tracking**: `agent-state.json` gets `"autopilot": true`. Autopilot continues on resume as well.
 
-### Phase 7 autopilot exception
+### Phase 5 autopilot exception
 
-The generic "zero-interaction" contract covers Phases 0-6 only. Phase 7 channels dispatch is the **single exception**:
+The generic "zero-interaction" contract covers Phases 0-4 only. Phase 5 channels dispatch is the **single exception**:
 
-- ALL modes (`autopilot`, `--local autopilot`, and a Short run reaching Phase 7) pause at the channels multi-select menu.
+- ALL modes (`autopilot`, `--local autopilot`, and a Short run reaching Phase 5) pause at the channels multi-select menu.
 - Menu pre-ticks from `prefs.global.reportChannels` + `prefs.global.reportContent`  -  user can accept with one keypress if prefs are stable.
 - **30-minute timeout**  -  if user does not respond, session ends cleanly:
   - External delivery aborted (no silent apply  -  prevents accidental Jira comments / Confluence pages).
@@ -60,13 +60,13 @@ The generic "zero-interaction" contract covers Phases 0-6 only. Phase 7 channels
   - Resume: `/multi-agent:resume <task-id>` re-opens menu with same inputs.
 - Post-hoc `/multi-agent:channels <task>` never times out  -  user invoked it explicitly.
 
-Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` (Autopilot pause contract) + `commands/multi-agent/channels/SKILL.md`.
+Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` (Autopilot pause contract) + `commands/multi-agent/channels/SKILL.md`.
 
 ---
 
 ## Pipeline depth (Full / Short)
 
-Short strips the pipeline to what an already-scoped task needs: no deep analysis, no planning phase. The **Opus** dev agent reads the task scope and implements, and Phase 4 then reviews what it produced. Review is deliberately NOT part of the strip: analysis and planning shape work that has not happened yet, so a task the user has already scoped can skip them, while review judges work that now exists and has no substitute.
+Short strips the pipeline to what an already-scoped task needs: no deep analysis, no planning phase. The **Opus** dev agent reads the task scope and implements, and Phase 3 then reviews what it produced. Review is deliberately NOT part of the strip: analysis and planning shape work that has not happened yet, so a task the user has already scoped can skip them, while review judges work that now exists and has no substitute.
 
 **How it is chosen.** Phase 0 Step 7.5, after `taskType` is known:
 
@@ -85,7 +85,7 @@ Bu is icin hangi pipeline? / Which pipeline for this task?
 **Pipeline in a Short run:**
 
 ```
-Phase 0: Init -> Phase 3: Dev (self-contained) -> Phase 4: Review -> Phase 5: Test -> Phase 6: Commit -> Phase 7: Report
+Phase 0: Init -> Phase 2: Dev (self-contained) -> Phase 3: Review -> Phase 3: Review (user test) -> Phase 4: Commit -> Phase 5: Report
 ```
 
 **What changes (Tablo 2  -  Short runs):**
@@ -94,14 +94,14 @@ Phase 0: Init -> Phase 3: Dev (self-contained) -> Phase 4: Review -> Phase 5: Te
 | ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------- |
 | Phase 0 (Init)      | Full setup                                      | Same  -  worktree, branch, state, and the depth question itself                      | Same  -  no worktree, branch on `$PROJECT_ROOT` |
 | Phase 1 (Analysis)  | Parallel Explore agents + analysis document     | **SKIP**  -  no tile is ever drawn for it (registration is deferred to Step 7.5)     | **SKIP**                                      |
-| Phase 2 (Planning)  | TaskCreate + architecture review + **Plan Approval Gate** | **SKIP** (no plan means no plan gate)                                    | **SKIP**                                      |
-| Phase 3 (Dev)       | Follows the Phase 2 plan, TDD cycle (Sonnet)    | **Self-contained** (Opus): agent scans relevant files, implements with TDD, builds | Same, on the local branch                     |
-| Phase 4 (Review)    | Parallel review + Fable triage (3 reviewers on every host: Claude Code Fable + Opus + Sonnet, Copilot GPT-5.4 + Opus + Sonnet) | **Same**  -  gates, parallel review, triage; blocking findings return to Phase 3 (cap 3) | **Same**, on the local branch diff |
-| Phase 5 (User Test) | Interactive prompt                              | **Interactive prompt**                                                             | Not in the set  -  no worktree to check out    |
-| Phase 6 (Commit)    | Commit + PR                                     | Same  -  still asks                                                                  | Same                                          |
-| Phase 7 (Report)    | Full report + channels multi-select             | Simplified  -  no analysis section, review section IS present, channels menu still pauses | Same                              |
+| Phase 1 (Planning)  | TaskCreate + architecture review + **Plan Approval Gate** | **SKIP** (no plan means no plan gate)                                    | **SKIP**                                      |
+| Phase 2 (Dev)       | Follows the Phase 1 plan, TDD cycle (Sonnet)    | **Self-contained** (Opus): agent scans relevant files, implements with TDD, builds | Same, on the local branch                     |
+| Phase 3 (Review)    | Parallel review + Fable triage (3 reviewers on every host: Claude Code Fable + Opus + Sonnet, Copilot GPT-5.4 + Opus + Sonnet) | **Same**  -  gates, parallel review, triage; blocking findings return to Phase 2 (cap 3) | **Same**, on the local branch diff |
+| Phase 3 (User Test) | Interactive prompt                              | **Interactive prompt**                                                             | Not in the set  -  no worktree to check out    |
+| Phase 4 (Commit)    | Commit + PR                                     | Same  -  still asks                                                                  | Same                                          |
+| Phase 5 (Report)    | Full report + channels multi-select             | Simplified  -  no analysis section, review section IS present, channels menu still pauses | Same                              |
 
-**Phase 3 in a Short run (self-contained):**
+**Phase 2 in a Short run (self-contained):**
 
 The **Opus** agent receives the task description (from Jira, GitHub issue, or free-text) and:
 
@@ -115,7 +115,7 @@ No separate task breakdown  -  the agent handles scope autonomously.
 
 ### Intake warnings for a Short run
 
-**An analysis document was supplied.** Because Phase 1 and Phase 2 are skipped, no phase turns that document into a task breakdown. The doc becomes raw context for one Dev pass, and work comes out ordered by whatever the model read first: the bottom of the dependency chain lands, the screen wiring does not.
+**An analysis document was supplied.** Because Phase 1 and Phase 1 are skipped, no phase turns that document into a task breakdown. The doc becomes raw context for one Dev pass, and work comes out ordered by whatever the model read first: the bottom of the dependency chain lands, the screen wiring does not.
 
 The depth picker is where this is caught. When the intake carried an analysis document or a Figma reference, say so in the question itself rather than after the choice:
 
@@ -134,10 +134,10 @@ Autopilot never sees this: it runs Full.
 
 ## Analysis Mode (`/multi-agent:analysis`)
 
-Not a depth permutation - a different **output kind**. It produces the analysis document and stops; no code, no branch, no PR. The 8-phase contract holds, with four phases reinterpreted the same way a Short run reinterprets Phase 3.
+Not a depth permutation - a different **output kind**. It produces the analysis document and stops; no code, no branch, no PR. The 6-phase contract holds, with four phases reinterpreted the same way a Short run reinterprets Phase 2.
 
 ```
-Phase 0: Init -> Phase 1: Analysis -> Phase 2: Planning -> Phase 4: Review -> Phase 6: Publish -> Phase 7: Report
+Phase 0: Init -> Phase 1: Plan (analysis) -> Phase 1: Plan -> Phase 3: Review -> Phase 4: Publish -> Phase 5: Report
 ```
 
 | Phase | Analysis mode |
@@ -153,7 +153,7 @@ Phase 0: Init -> Phase 1: Analysis -> Phase 2: Planning -> Phase 4: Review -> Ph
 
 **No `local` or `autopilot` variant.** Worktree isolation buys nothing when no code is written, and the intake, the Pass B convention preview and the open-question resolution are interactive by nature; a zero-interaction analysis would be a document nobody agreed to.
 
-**Where the document lands.** Drafts go to `/tmp/analysis-<slug>-<ts>/` first, then the Phase 6 picker decides: Local writes `<repo>/analysis/<feature>-<platform>.md` uncommitted, Confluence posts the page, Jira updates the description. In the full pipeline the same engine writes into the worktree instead and `prefs.global.analysisPhase.commitDoc` decides whether it rides along with the commit.
+**Where the document lands.** Drafts go to `/tmp/analysis-<slug>-<ts>/` first, then the Phase 4 picker decides: Local writes `<repo>/analysis/<feature>-<platform>.md` uncommitted, Confluence posts the page, Jira updates the description. In the full pipeline the same engine writes into the worktree instead and `prefs.global.analysisPhase.commitDoc` decides whether it rides along with the commit.
 
 ---
 
@@ -167,11 +167,11 @@ front so the question resolves without being asked.
 ```
 Bu is nerede kossun? / Where should this task run?
   1. Worktree       .worktrees/{id}/ - your current checkout stays untouched
-  2. Lokal / Local  the project root, on a new branch - no Phase 5
+  2. Lokal / Local  the project root, on a new branch - no Phase 3
 ```
 
 Two genuine options, so it meets the two-option floor in `picker-contract.md` on
-its own. **Say what local costs inside the question**: Phase 5 is not in a local
+its own. **Say what local costs inside the question**: Phase 3 is not in a local
 run's set (the user-test gate checks the change out of a worktree, and there is
 none), and uncommitted work in the project root is in the way of the checkout. A
 user choosing local should learn both before choosing, not after.
@@ -196,9 +196,9 @@ and doing that in the user's own checkout is what worktrees exist to prevent.
 | Phase          | Normal (worktree)                                | Local                                                          |
 | -------------- | ------------------------------------------------ | -------------------------------------------------------------- |
 | Phase 0 Step 8 | Creates worktree at `.worktrees/{id}/`           | `git checkout -b {branch}` directly in `$PROJECT_ROOT`         |
-| Phase 3        | Works in worktree path                           | Works in `$PROJECT_ROOT`                                       |
-| Phase 5        | WIP commit -> remove worktree -> checkout branch | **Not in the phase set**  -  nothing to check out, nothing to remove |
-| Phase 6        | Commit in worktree, push                         | Commit in project root, push                                   |
+| Phase 2        | Works in worktree path                           | Works in `$PROJECT_ROOT`                                       |
+| Phase 3        | WIP commit -> remove worktree -> checkout branch | **Not in the phase set**  -  nothing to check out, nothing to remove |
+| Phase 4        | Commit in worktree, push                         | Commit in project root, push                                   |
 | All paths      | `{worktreePath}` references                      | All paths use `$PROJECT_ROOT` directly                         |
 
 **Phase 0 Step 8 in local mode:**
@@ -211,7 +211,7 @@ git -C $PROJECT_ROOT config user.name "{identity.name}"
 git -C $PROJECT_ROOT config user.email "{identity.email}"
 ```
 
-**Phase 5 in local mode:** it is not in the phase set. The gate exists to hand the user a change checked out of a worktree, and in local mode the code is already on the branch in `$PROJECT_ROOT` with nothing to check out or remove. `gen-mode-dispatch.mjs --mode=local` is the enforced statement of this; the row above mirrors it.
+**Phase 3 in local mode:** it is not in the phase set. The gate exists to hand the user a change checked out of a worktree, and in local mode the code is already on the branch in `$PROJECT_ROOT` with nothing to check out or remove. `gen-mode-dispatch.mjs --mode=local` is the enforced statement of this; the row above mirrors it.
 
 **State tracking**: `agent-state.json` gets `"localMode": true`, `"worktreePath": null`. All path references resolve to `$PROJECT_ROOT`.
 

package/pipeline/multi-agent-refs/phases/operations.md

@@ -2,7 +2,7 @@
 >
 > - **Task IDs** auto-increment from `$HOME/.claude/logs/multi-agent/{project}/.counter` (persistent).
 > - **Kill/Purge/Clear-logs** require explicit user confirm; destructive ops never chain.
-> - **Resume** re-enters at `currentPhase + 1`; always re-runs Phase 7 for knowledge capture.
+> - **Resume** re-enters at `currentPhase + 1`; always re-runs Phase 5 for knowledge capture.
 > - **3-iteration hard kill**: any retry loop stops after 3 attempts and hands off to the user.
 > - Subagents return JSON (not prose), get only the diff + relevant files, and must reflect before each retry.
 
@@ -61,11 +61,11 @@ Every task gets an auto-incremented short ID. Counter stored at `$HOME/.claude/l
 
 1. Find state file: `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-state.json`
 2. **Validate before re-entry** (required  -  a half-written or corrupt state silently resumes at the wrong phase):
-   - `node $HOME/.claude/scripts/validate-state.mjs <state-file>` (resume-safety check: parseable JSON + `currentPhase` in 0..7 + well-formed `phases`; tolerant of legacy shapes, not a strict schema match). On non-zero exit, do NOT guess a phase: surface the error and stop with `ERR: agent-state.json is unsafe to resume; inspect it or 'kill #N' and restart.`
+   - `node $HOME/.claude/scripts/validate-state.mjs <state-file>` (resume-safety check: parseable JSON + `currentPhase` in 0..5 + well-formed `phases`; tolerant of legacy shapes, not a strict schema match). On non-zero exit, do NOT guess a phase: surface the error and stop with `ERR: agent-state.json is unsafe to resume; inspect it or 'kill #N' and restart.`
    - Confirm the worktree path on `state.worktreePath` / `state.projects[].worktreePath` exists and `git -C <wt> status` is clean-or-known. If the worktree is missing or locked, run the Phase 0 "Worktree stale-lock heal" before continuing.
 3. Read `agent-log.md` for previous findings
 4. Resume from `currentPhase + 1`. If `state.phases[currentPhase+1].subStep` is set, re-enter that phase and skip already-recorded sub-steps (see "Sub-step checkpoints").
-5. **Always run Phase 7** on resume completion  -  ensures knowledge capture even if task was paused mid-pipeline
+5. **Always run Phase 5** on resume completion  -  ensures knowledge capture even if task was paused mid-pipeline
 6. Log: "Resumed {jiraId} from Phase {N}"
 
 ---
@@ -78,8 +78,9 @@ Update `agent-state.json` at EVERY phase transition.
 
 ### Writing `agent-state.json` (required mechanism)
 
-Every state update goes through `write-state.mjs`. Never write the file with a
-plain read-modify-write (`jq ... > tmp && mv`, an editor tool, `cat >`):
+Every state write goes through `write-state.mjs`, **including the first one in
+Phase 0**. Never write the file with a plain read-modify-write (`jq ... > tmp &&
+mv`, an editor tool, `cat >`):
 
 ```bash
 # Merge a patch into the current state (the normal case).
@@ -97,6 +98,16 @@ the first landed. `write-state.mjs` does tmpfile + rename (atomic on POSIX) unde
 an advisory `.lock`, reclaims a lock whose holder PID is dead, and releases the
 lock on every error path.
 
+Why the CREATE matters as much as the updates: the writer stamps `rev` on every
+write and `schemaVersion` on the first one. A document written by hand in Phase 0
+starts with neither, so every later writer compares against an absent revision
+and `migrate-state.mjs` can never place the file on a migration path. Measured on
+a real install before this was fixed: 39 of 43 `agent-state.json` files carried no
+`rev` and 43 of 43 carried no `schemaVersion`, which is the whole of
+`$HOME/.claude/schemas/migrations/` sitting unreachable. `migrate-state.mjs --all`
+reports the legacy ones; it does not stamp them, because a stamp would assert a
+conformance nothing checked.
+
 Exit codes the caller must handle: `0` written, `1` invalid JSON on stdin, `2`
 lock timeout (another writer held it past the acquire window  -  retry once, then
 halt per the halt-visibility rule), `3` I/O error.
@@ -127,13 +138,13 @@ lose the update behind it. `WRITE_STATE_LOCK_STALE_MS` now applies only to a
 lock with no readable PID, and `WRITE_STATE_LOCK_ABANDON_MS` (default ten times
 that) is the last-resort ceiling for a PID that has been recycled.
 
-**Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`; (d) if `prefs.global.usageLog.enabled` is true, emit the end-of-run report so a run that never reaches Phase 7 is still recorded with the phase it stopped at (`state.currentPhase` + `haltReason`) - the emitter no-ops when it is off or unconfigured:
+**Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`; (d) if `prefs.global.usageLog.enabled` is true, emit the end-of-run report so a run that never reaches Phase 5 is still recorded with the phase it stopped at (`state.currentPhase` + `haltReason`) - the emitter no-ops when it is off or unconfigured:
 
 ```bash
 node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" >/dev/null 2>&1 || true
 ```
 
-Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log. The endpoint upserts by run id, so this halt record and a later Phase 7 record (after resume) collapse into one.
+Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log. The endpoint upserts by run id, so this halt record and a later Phase 5 record (after resume) collapse into one.
 
 ### Pipeline Best Practices
 
@@ -149,7 +160,7 @@ This keeps orchestrator context lean and enables programmatic routing.
 
 **Retry reflection**: Before each retry, force reflection: "What failed? What specific change fixes it? Am I repeating the same approach?"  -  prevents infinite loops on broken strategies.
 
-**Semantic revert**: Track which files each phase produces in `agent-state.json`. If Phase 5 (testing) fails, revert only Phase 4 (implementation) outputs, not Phase 2 (artifacts):
+**Semantic revert**: Track which files each phase produces in `agent-state.json`. If Phase 3 (testing) fails, revert only Phase 3 (implementation) outputs, not Phase 1 (artifacts):
 
 ```json
 "phases": {
@@ -165,7 +176,7 @@ This keeps orchestrator context lean and enables programmatic routing.
   bash $HOME/.claude/scripts/capture-flush.sh --state "$STATE_FILE" --quiet
   ```
 
-  The durable stores used to be written only in Phase 7, which is the phase a run is LEAST likely to reach: a run killed in Phase 3 threw away every finding it had established, and the next run on the same repo paid to rediscover it. The flush is idempotent (the second call through writes 0 rows), costs no API tokens, calls no model, and never fails the transition. Phase 7 is now the LAST flush rather than the only one. The trigger is deliberately mechanical - a phase transition, not a model noticing that a moment qualifies.
+  The durable stores used to be written only in Phase 5, which is the phase a run is LEAST likely to reach: a run killed in Phase 2 threw away every finding it had established, and the next run on the same repo paid to rediscover it. The flush is idempotent (the second call through writes 0 rows), costs no API tokens, calls no model, and never fails the transition. Phase 5 is now the LAST flush rather than the only one. The trigger is deliberately mechanical - a phase transition, not a model noticing that a moment qualifies.
 - *Compaction trigger.* If conversation context exceeds ~50%, run `/compact` preserving "modified files, plan, open review findings, current phase + sub-step" before continuing. Don't wait for auto-compaction near the limit  -  it triggers exactly when context is worst and is lossy. After compaction, re-read `agent-state.json` AND the latest `## Handoff` block in `agent-log.md` to re-ground.
 
 **Handoff block (v10.8.0)**: the structured artifact the phase-boundary checkpoint appends to `agent-log.md`. Written by the orchestrator from state it already holds  -  no agent dispatch, no extra LLM call. Cap at ~15 lines; the latest block is authoritative (earlier ones are history). This is the fresh-context re-entry contract: a resume or post-compaction session rebuilds working context from the latest handoff + `agent-state.json` + git log, never from conversation memory.
@@ -181,6 +192,6 @@ This keeps orchestrator context lean and enables programmatic routing.
 
 Full `agent-log.md` shape: `$HOME/.claude/multi-agent-refs/phases/log-format.md`. Resume-side consumption: `resume.md` Step 3 reads the latest handoff FIRST, then falls back to per-phase findings for logs written before v10.8.
 
-**Sub-step checkpoints (long phases)**: Phase 3 (dev/TDD cycles) and Phase 7 (report/channels) can run many minutes; a crash mid-phase loses everything since the last phase boundary and forces a full phase re-run on resume. For these phases, also record `state.phases[<n>].subStep` (a short token: `red`, `green`, `build`, `pr-opened`, `confluence-synced`, ...) and the `files[]` written so far after each meaningful unit of work. On resume, re-enter the phase but skip units whose `subStep` is already recorded and whose `files[]` exist in the worktree  -  re-do only the unfinished tail, never the whole phase.
+**Sub-step checkpoints (long phases)**: Phase 2 (dev/TDD cycles) and Phase 5 (report/channels) can run many minutes; a crash mid-phase loses everything since the last phase boundary and forces a full phase re-run on resume. For these phases, also record `state.phases[<n>].subStep` (a short token: `red`, `green`, `build`, `pr-opened`, `confluence-synced`, ...) and the `files[]` written so far after each meaningful unit of work. On resume, re-enter the phase but skip units whose `subStep` is already recorded and whose `files[]` exist in the worktree  -  re-do only the unfinished tail, never the whole phase.
 
 **3-iteration hard kill**: Any retry loop (build fix, review fix) MUST stop after 3 attempts. On 4th failure -> pause, ask user. No exceptions.