@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

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:
@@ -514,7 +514,7 @@ done
 
 State file in multi-repo mode:
 - Single shared `agent-state.json` lives at `$HOME/.claude/logs/multi-agent/{first-project}/{task-id}/agent-state.json` (anchored on the first repo for back-compat with `multi-agent log`/`status` commands)
-- Every update to it, here and in every later phase, goes through `node $HOME/.claude/scripts/write-state.mjs`  -  the required mechanism in `operations.md` "Writing `agent-state.json`", and the race a per-repo read-modify-write loses `projects[]` entries to.
+- Every write to it, creation included, goes through `node $HOME/.claude/scripts/write-state.mjs`  -  the required mechanism in `operations.md` "Writing `agent-state.json`", and the race a per-repo read-modify-write loses `projects[]` entries to.
 - `state.projects[]` holds per-repo `{name, root, worktreePath, branch, baseBranch, identity, platform, baseFetchStatus, commit, pr, pushAttempts, buildStatus}`  -  see `agent-state.schema.json`
 - Scalar fields (`project`, `projectRoot`, `worktreePath`, `branch`, `baseBranch`, `identity`) mirror `projects[0]` so legacy phases that read scalars keep working
 - Atomicity: if any repo's worktree creation fails (collision aborted, fetch aborted, disk full), roll back already-created worktrees: `git -C $proj worktree remove --force $WT_PATH; git -C $proj branch -D $BRANCH`. Never leave a partial multi-repo state.
@@ -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.