@mmerterden/multi-agent-pipeline 18.0.0 → 19.0.0

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}"
 
 ---
@@ -138,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
 
@@ -160,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": {
@@ -176,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.
@@ -192,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.

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -46,7 +46,7 @@ OUTPUT_LANG=$(jq -r '.global.outputLanguage // "en"' "$PREFS_FILE" 2>/dev/null |
 
 From this point on, everything the user reads renders in `$OUTPUT_LANG`: conversational lines, `AskUserQuestion` `question`/`label`/`description`, and external payload bodies (PR/Jira/Confluence). English stays only on `header`, commit messages, branch names, PR title prefixes, identifiers. Full matrix: `rules.md` "Language Application".
 
-**Model tier resolution** (same step, once per run): read `prefs.global.modelFallback`. If `fableEnabled` is `false`, every `preferredModel: fable` persona resolves to `opus` for this run and the Phase 4 Claude Code panel is 2 reviewers, not 3; print the one-line INFO. Then, if `premiumTierUntil` is set and in the past, apply the date-gate trigger - `preferredModel` personas dispatch on `fallbackModel`, with the one-line WARN. Both lines and the exact ordering: `$HOME/.claude/multi-agent-refs/features/model-fallback.md`. Dispatch-error and budget triggers apply per-dispatch later; nothing else to do here.
+**Model tier resolution** (same step, once per run): read `prefs.global.modelFallback`. If `fableEnabled` is `false`, every `preferredModel: fable` persona resolves to `opus` for this run and the Phase 3 Claude Code panel is 2 reviewers, not 3; print the one-line INFO. Then, if `premiumTierUntil` is set and in the past, apply the date-gate trigger - `preferredModel` personas dispatch on `fallbackModel`, with the one-line WARN. Both lines and the exact ordering: `$HOME/.claude/multi-agent-refs/features/model-fallback.md`. Dispatch-error and budget triggers apply per-dispatch later; nothing else to do here.
 
 **First-run guard**: After loading prefs, check if `keychainMapping` has at least one non-null value. If ALL values are null (template defaults  -  setup never ran), show:
 ```
@@ -74,7 +74,7 @@ Used for: input parsing, branch naming, commit messages.
 
 **UX pattern**: Show `Recent: → {value}` suggestion from history, numbered alternatives, enter to accept. No history → skip suggestion line.
 
-**Save rule**: After EVERY selection, append chosen value to relevant array (dedup, most recent first, max 10). Save prefs after Phase 0 and Phase 7.
+**Save rule**: After EVERY selection, append chosen value to relevant array (dedup, most recent first, max 10). Save prefs after Phase 0 and Phase 5.
 
 **v2.1.0+ Recents update map** (which selection writes to which prefs path):
 
@@ -86,7 +86,7 @@ Used for: input parsing, branch naming, commit messages.
 | Service ping (any external API call) | `global.serviceStatus[{service}]` | `{ok, checkedAt, reason?}` (TTL `settings.serviceStatusCacheSeconds`, default 300s) | n/a |
 | Git identity routed (Step 6a) | `projects[{name}].lastIdentity` | int (index into `global.identities`) | n/a |
 
-All updates are O(1)  -  read-modify-write on the in-memory `prefs` object; single atomic write at the end of Phase 0 (and again at Phase 7).
+All updates are O(1)  -  read-modify-write on the in-memory `prefs` object; single atomic write at the end of Phase 0 (and again at Phase 5).
 
 #### Step 0.5 - Figma access pre-flight (BLOCKING when task carries a Figma reference)
 
@@ -96,12 +96,12 @@ Probe order:
 
 1. **Tier 1 (Figma MCP)**: check the host serves `mcp__claude_ai_Figma__*` before probing. Absent → set `state.figmaAccess.tier1Unavailable = "host"` and fall through to Tier 2 with no probe, no re-auth retry, no MCP-token question. Present → probe `get_metadata(fileKey, nodeId)` on the first frame; on auth failure run `authenticate` + `complete_authentication` and retry once, and only a *second* failure raises the recreate-or-continue question. Success → `state.figmaAccess.tier = 1`.
 2. **Tier 2 (Figma REST)**: when Tier 1 fails, resolve the PAT via `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma`. Probe `GET https://api.figma.com/v1/files/{fileKey}/nodes?ids={nodeId}` with header `X-Figma-Token: $TOKEN`. HTTP 200 → `state.figmaAccess.tier = 2`. Token missing / 401 / 403 → fall through.
-3. **Tier 3 (User-attached screenshot)**: when Tiers 1 + 2 both fail, scan the task payload for inline screenshots or attachments. Present → `state.figmaAccess.tier = 3` and `state.figmaAccess.reviewBlocking = true` (Phase 4 enforces this).
+3. **Tier 3 (User-attached screenshot)**: when Tiers 1 + 2 both fail, scan the task payload for inline screenshots or attachments. Present → `state.figmaAccess.tier = 3` and `state.figmaAccess.reviewBlocking = true` (Phase 3 enforces this).
 
 Save the issue's image attachments to `$WORKTREE/.pipeline/evidence/` as `state.visualEvidence.before[]`: pre-fix evidence, never re-photographed, and none present is a recorded gap rather than a search. See `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
 4. **Halt**: all three tiers fail → emit a single AskUserQuestion asking the user how to proceed (provide PAT, paste a screenshot, abort). Never proceed with text-derived guesses.
 
-Record the cause, not just the downshift. `tier1Unavailable = "host"` means the tier never existed here - routine on Copilot and Codex, where the installer registers only `multi-agent-toolkit`. `"auth"` means it existed and the credential failed, which on Claude Code points at a dead `figma_mcp` token worth surfacing in Phase 7. Conflating them costs two wasted MCP round trips and a question the user cannot act on. On those two hosts a mapped `figma` PAT is the primary path, not a fallback.
+Record the cause, not just the downshift. `tier1Unavailable = "host"` means the tier never existed here - routine on Copilot and Codex, where the installer registers only `multi-agent-toolkit`. `"auth"` means it existed and the credential failed, which on Claude Code points at a dead `figma_mcp` token worth surfacing in Phase 5. Conflating them costs two wasted MCP round trips and a question the user cannot act on. On those two hosts a mapped `figma` PAT is the primary path, not a fallback.
 
 Log the resolved tier in the agent log:
 
@@ -239,13 +239,13 @@ Sequential prompts (standard UX pattern with Recent suggestion): Project Key →
 
 **Token pre-check** (after parsing): Jira input → resolve key via `prefs.global.keychainMapping.jira`, verify token with a lightweight API call (e.g. `GET /myself`). GitHub input → verify `gh auth status`. On failure (missing key, 401, 403) → run the **Token Save Flow** from `setup.md` inline. This is the same clipboard-based flow used during setup  -  token never appears in terminal. If user skips and the token is critical for the input type (e.g. Jira token for Jira input), halt Phase 0.
 
-**VPN connectivity check**: Test VPN-dependent services (Jira, Bitbucket, Confluence, Fortify, Graylog) with `curl --connect-timeout 3`. If unreachable, warn and offer to continue. Fallback: Jira → manual input, Bitbucket → `git push` only, Confluence → skip Phase 7, Fortify → skip scan, Graylog → skip log fetch (advisory only, never blocks). Cache in `agent-state.json` → `"vpnServices": {"jira": true, ...}`.
+**VPN connectivity check**: Test VPN-dependent services (Jira, Bitbucket, Confluence, Fortify, Graylog) with `curl --connect-timeout 3`. If unreachable, warn and offer to continue. Fallback: Jira → manual input, Bitbucket → `git push` only, Confluence → skip Phase 5, Fortify → skip scan, Graylog → skip log fetch (advisory only, never blocks). Cache in `agent-state.json` → `"vpnServices": {"jira": true, ...}`.
 
 #### Step 1b  -  URL Enrichment (catalogue + targeted deep fetches)
 
 **Runs only when Step 1 found at least one URL in the task input** (Jira/Confluence/Figma/Swagger/Crashlytics/Fortify/Graylog links). Otherwise skip straight to Step 2.
 
-When it runs, load `$HOME/.claude/multi-agent-refs/features/url-enrichment.md` and follow it. It covers: 1b.0 extract + catalogue every link into `state.contextLinks[]` (always runs when this step runs), then the deep fetches that are each conditional on their link type being present  -  1b.1 Crashlytics -> `state.crashContext`, 1b.2 Fortify SSC -> `state.fortifyFinding`, 1b.3 Graylog, 1b.4 catalogue-only types (fetched at Phase 1). It also owns the two closing log lines and the Phase 1 / Phase 2 prepend contracts.
+When it runs, load `$HOME/.claude/multi-agent-refs/features/url-enrichment.md` and follow it. It covers: 1b.0 extract + catalogue every link into `state.contextLinks[]` (always runs when this step runs), then the deep fetches that are each conditional on their link type being present  -  1b.1 Crashlytics -> `state.crashContext`, 1b.2 Fortify SSC -> `state.fortifyFinding`, 1b.3 Graylog, 1b.4 catalogue-only types (fetched at Phase 1). It also owns the two closing log lines and the Phase 1 / Phase 1 prepend contracts.
 
 #### Step 2  -  Project Selection
 
@@ -275,7 +275,7 @@ later because a base branch is a property of a repo set (`picker-contract.md`,
 "Order: project, then repo, then branch").
 
 Persist `state.siblings[]` even when empty: the empty array is the record that
-the step ran. Absent, Phase 4's parity cross-check cannot tell "no siblings"
+the step ran. Absent, Phase 3's parity cross-check cannot tell "no siblings"
 from "never asked", and the exit gate below fails.
 
 #### Step 3  -  Remote Detection + Branch Selection
@@ -351,7 +351,7 @@ options:
 `{BITBUCKET_HOST}` is almost always the VPN - and make the retry real: it re-runs the
 fetch and re-enters this picker on a second failure.
 
-Persist the choice in `agent-state.json.baseFetchStatus` ∈ `"fresh" | "cached-stale" | "local-branch" | "aborted"`, and on any non-fresh one log `⚠️ Base ref stale (fetch fail @ {ts}, choice: {status})`. Phase 6 re-attempts `git fetch origin` before push and prompts to rebase if it succeeds.
+Persist the choice in `agent-state.json.baseFetchStatus` ∈ `"fresh" | "cached-stale" | "local-branch" | "aborted"`, and on any non-fresh one log `⚠️ Base ref stale (fetch fail @ {ts}, choice: {status})`. Phase 4 re-attempts `git fetch origin` before push and prompts to rebase if it succeeds.
 
 In multi-repo mode the prompt fires per repo, and Abort on any one aborts the whole task (atomic - no partial worktrees).
 
@@ -382,7 +382,7 @@ Branch name is deterministic  -  no user confirmation needed.
 **Collision handling** (automatic  -  no prompt):
 - Probe local + remote for existing branch. **Distinguish "no such ref" from "the
   probe failed"**: with `2>/dev/null` and an empty-output test a failed probe reads
-  as "no collision", and the duplicate branch surfaces as a rejected push at Phase 6.
+  as "no collision", and the duplicate branch surfaces as a rejected push at Phase 4.
   ```bash
   LOCAL_HIT=$(git -C "$root" rev-parse --verify --quiet "refs/heads/$branch")
   REMOTE_ERR=$(git -C "$root" ls-remote --exit-code --heads origin "$branch" 2>&1 >/dev/null)
@@ -393,7 +393,7 @@ Branch name is deterministic  -  no user confirmation needed.
 - `REMOTE_RC` is 0 or 2 → treat as authoritative
 - `REMOTE_RC` is anything else → the remote answer is **unknown**, not "free". Log
   `Remote collision probe failed: <REMOTE_ERR>`, fall back to the local check only,
-  and record `"remoteCollisionProbe": "failed"` in `agent-state.json` so Phase 6
+  and record `"remoteCollisionProbe": "failed"` in `agent-state.json` so Phase 4
   expects a possible non-fast-forward and re-checks before pushing.
 - No collision → use as-is
 - Collision found → append `-v2`, `-v3`, etc. until unique:
@@ -548,7 +548,7 @@ Single-repo mode (`projects.length === 1` or scalar-only) uses the legacy single
 
 **Local-only flow**  -  when every entry in `state.projects[]` has `provider="local"`:
 - `taskId` format: `LOCAL-{slug-of-freetext}-{yyyymmdd-HHMMSS}` (e.g. `LOCAL-purchase-flow-20260510-143200`). Slug = lowercase, non-alnum → `-`, trimmed, max 32 chars.
-- `state.offlineOnly = true` (Phases 6/7 read this flag).
+- `state.offlineOnly = true` (Phases 4/5 read this flag).
 - `state.remoteType` per project = `"local"`.
 - `state.baseBranch` = current branch of the local checkout (no `origin/{base}` fetch).
 - `state.branch` = local-only feature branch on the same checkout; no upstream tracking is configured (`git checkout -b {branch}` without `-u`).
@@ -577,10 +577,10 @@ Persist: `"taskType": "component" | "bugfix" | "feature" | "refactor" | "chore"`
 
 | Phase   | Behavior change                                                                                          |
 | ------- | -------------------------------------------------------------------------------------------------------- |
-| Phase 3 | `component` → dispatch to the enabled `ai-<platform>-toolkit` plugin's `create-component` skill (fallback `create-ui-component`); else standard TDD |
-| Phase 4 | `bugfix` → test coverage; `component` → accessibility+tokens; `refactor` → behavior preservation         |
-| Phase 6 | `bugfix`/`hotfix` → `fix(...)` prefix; `feature`/`component` → `feat(...)`; `refactor` → `refactor(...)` |
-| Phase 7 | `component` → includes SubPhase breakdown                                                                |
+| Phase 2 | `component` → dispatch to the enabled `ai-<platform>-toolkit` plugin's `create-component` skill (fallback `create-ui-component`); else standard TDD |
+| Phase 3 | `bugfix` → test coverage; `component` → accessibility+tokens; `refactor` → behavior preservation         |
+| Phase 4 | `bugfix`/`hotfix` → `fix(...)` prefix; `feature`/`component` → `feat(...)`; `refactor` → `refactor(...)` |
+| Phase 5 | `component` → includes SubPhase breakdown                                                                |
 
 Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
 
@@ -610,7 +610,7 @@ Log: `Phase 0 Step 7.5: depth = {full|short} (recommended {full|short}, source {
 
 #### Step 7.6  -  Test baseline (opt-in, `prefs.global.testBaseline.enabled`, default `false`)
 
-Phase 4 Gate 3 cannot tell an inherited red suite from one this run broke, so it blocks on someone else's bug or the agent "fixes" tests it never touched. Runs after Step 6, only when the stack has a test command; skipped in analysis mode.
+Phase 3 Gate 3 cannot tell an inherited red suite from one this run broke, so it blocks on someone else's bug or the agent "fixes" tests it never touched. Runs after Step 6, only when the stack has a test command; skipped in analysis mode.
 
 ```bash
 BASELINE_LOG="$WORKTREE/.baseline-test.log"
@@ -625,7 +625,7 @@ Log: `Phase 0 Step 7.6: test baseline = {green|red|unknown} ({N} pre-existing fa
 
 Decide, then probe, then ask, then run. Skipped only when `visualEvidence.enabled` is `false`. Contract: `features/visual-evidence.md` sections 1a, 1b, 4.
 
-**This step is the only writer of `visualEvidence.required`, `requiredBy` and `platform`** (section 1a). No diff exists yet, so the `bugfix` row is provisional and Phase 3 re-decides.
+**This step is the only writer of `visualEvidence.required`, `requiredBy` and `platform`** (section 1a). No diff exists yet, so the `bugfix` row is provisional and Phase 2 re-decides.
 
 ```bash
 eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"
@@ -653,7 +653,7 @@ DEPTH_DEFAULT_INDEX=1
 ASK_CHOICE_DEFAULT="$DEPTH_DEFAULT_INDEX" $HOME/.claude/lib/ask-choice.sh ...
 ```
 
-Asked by `/multi-agent` and `:local`; autopilot reads `prefs.global.testDepth.default` and degrades to the best open option. Asked here, not Phase 5, which four of the eight modes drop.
+Asked by `/multi-agent` and `:local`; autopilot reads `prefs.global.testDepth.default` and degrades to the best open option. Asked here, not Phase 3, which four of the eight modes drop.
 
 Log: `Phase 0 Step 7.7: testDepth = {unit|unit+ui|unit+mcp} (source {user|autopilot|default|forced}), tier1/tier2 = {open|closed}`
 
@@ -689,7 +689,7 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 0
   duration_ms=$D tokens_in=$TI tokens_out=$TO
 ```
 
-Phase 7 cost rollup carries this as a `phase 0` line item so the user sees ambiguity-scoring cost separately from Phase 1 Analysis.
+Phase 5 cost rollup carries this as a `phase 0` line item so the user sees ambiguity-scoring cost separately from Phase 1 Analysis.
 
 <!-- progress-contract: applied -->
 
@@ -710,15 +710,15 @@ node "$HOME/.claude/scripts/usage-register.mjs" --quiet >/dev/null 2>&1 || true
 node "$HOME/.claude/scripts/usage-report.mjs" --task-id "$TASK_ID" >/dev/null 2>&1 || true
 ```
 
-The third line reports the run as started: reporting only from Phase 7 reported
-only runs that finish, and few do. Phase 7 upserts the same key over it. The
+The third line reports the run as started: reporting only from Phase 5 reported
+only runs that finish, and few do. Phase 5 upserts the same key over it. The
 second is the backstop for a machine that reached neither setup nor update - it
 is a no-op once a token resolves, and permanently so under `usageLog.optOut`.
 
 It asserts five things, each of which has failed silently in a real run:
 
 1. **`agent-state.json` exists.** Every later phase reasons from it.
-2. **`taskType` is set.** Phase 3 branches on it (Step 7).
+2. **`taskType` is set.** Phase 2 branches on it (Step 7).
 3. **A Figma reference forces `taskType: "component"`, and `figmaAccess.tier` is
    recorded**, so a later phase can tell a confirmed design from an unfetched one.
 4. **`baseBranchSource` is recorded**, and an interactive run recorded `asked` or
@@ -730,4 +730,4 @@ Each failed silently in a real run; the script header names which.
 
 A failure is a halt, not a warning: fix the state, re-run the gate, and leave the phase
 `in_progress` until it passes. Never close Phase 0 on the grounds that its steps ran -
-the gate checks the output, which is what Phase 3 consumes.
+the gate checks the output, which is what Phase 2 consumes.