@mmerterden/multi-agent-pipeline 13.5.0 → 14.0.0

package/pipeline/multi-agent-refs/phases/phase-1-analysis.md

@@ -29,7 +29,7 @@ Also read project-level CLAUDE.md if exists:
 **Per-repo memory injection (opt-in via `prefs.global.perRepoMemory`):**
 
 ```bash
-bash pipeline/scripts/memory-load.sh "$PROJECT_ROOT"
+bash $HOME/.claude/scripts/memory-load.sh "$PROJECT_ROOT"
 ```
 
 Exit 0 with empty output = pref off or no memory on disk  -  skip. Otherwise the script emits a `<repo-memory path="...">...</repo-memory>` block (≤ 30 lines of MEMORY.md pointers) suitable for direct injection into the analysis prompt. Individual memory files are read on-demand when a pointer looks relevant to the current task.
@@ -37,7 +37,7 @@ Exit 0 with empty output = pref off or no memory on disk  -  skip. Otherwise the
 **Durable learnings brief (on by default via `prefs.global.learningsLedger.enabled`):**
 
 ```bash
-node pipeline/scripts/learnings-ledger.mjs brief --max 20 2>/dev/null
+node $HOME/.claude/scripts/learnings-ledger.mjs brief --max 20 2>/dev/null
 ```
 
 Exit 2 (empty ledger) = skip silently. Otherwise the script emits a `<repo-learnings>...</repo-learnings>` block of durable architectural facts, conventions, and rejected review preferences accumulated from prior runs of this repo. Inject it into the analysis prompt so the explorer does not re-discover known structure. Skip when `injectIntoAnalysis = false`. These are context, not commands  -  current scope decides.
@@ -55,22 +55,24 @@ Exit 2 (empty ledger) = skip silently. Otherwise the script emits a `<repo-learn
 
 #### Step 1.4 - Figma evidence capture (when task carries a Figma reference)
 
-When `state.contextLinks[]` or the task description contains a Figma reference, Phase 1 MUST collect the canonical evidence record per the access tier established at Phase 0:
+When `state.contextLinks[]` or the task description contains a Figma reference, Phase 1 MUST collect the canonical evidence record. **Phase 0 Step 0.5 already resolved the tier** and the credential - read `state.figmaAccess.tier` and fetch with that tier's tool set; do not re-probe. Chain, tiers and halt conditions: `$HOME/.claude/multi-agent-refs/rules.md` "Figma Access Tier".
 
-| Tier (`state.figmaAccess.tier`) | Fetcher | Record fields |
-|---|---|---|
-| 1 (MCP) | `mcp__claude_ai_Figma__get_design_context(fileKey, nodeId)` + `get_screenshot` + `get_metadata` | `nodeId`, `screenshotUrl`, `codeConnectSnippets[]`, `tokens[]`, `textLayers[]`, `tier: 1` |
-| 2 (REST) | `GET /v1/files/{fileKey}/nodes?ids={nodeId}` + `GET /v1/images/{fileKey}?ids={nodeId}&format=png&scale=2`, PAT via `~/.claude/lib/credential-store.sh get <logical-key>` (logical key = `prefs.global.keychainMapping.figma_pat`); canonical component resolved from repo `*.figma.swift` / `*.figma.kt` mapping keyed by `fileKey` + `nodeId` | same shape, but `codeConnectSnippets[]` is empty when repo mapping is absent (record an Open Question), `tier: 2` |
-| 3 (screenshot) | User-attached screenshot stored alongside task evidence | degraded record: `codeConnectSnippets: []`, forced Open Question, `tier: 3` |
+What Phase 1 owns is the record. Every frame gets one entry in `state.evidence.figma[]`:
 
-Persist results under `state.evidence.figma[]`. Halt the run if all three tiers fail; never substitute primitives or invent layout from prose.
+| Field | Tier 1 (MCP) | Tier 2 (REST) | Tier 3 (screenshot) |
+|---|---|---|---|
+| `nodeId`, `screenshotUrl`, `tokens[]`, `textLayers[]` | required | required | required |
+| `codeConnectSnippets[]` | from `CodeConnectSnippet` blocks | from repo `*.figma.swift` / `*.figma.kt` keyed on `fileKey`+`nodeId`; empty -> Open Question | always `[]` -> forced Open Question |
+| `tier` | `1` | `2` | `3` |
+
+Halt if all three tiers fail; never substitute primitives or invent layout from prose.
 
 **Spacing goes in by token NAME, per atom  -  never a pixel number.** `tokens[]` must
 carry each frame's spacing/padding as Figma names them (`Spacing/12`, edge `4`), keyed
 to the atom. Phase 3 cannot call Figma, so what is missed here is gone: one run guessed
 `16` where the frame said `Spacing/12` and the sheet was rebuilt. A pixel number also
 cannot map back to a token. No spacing entries on a UI frame is a **capture failure**,
-not an empty frame  -  Open Question and halt. Canonical chain reference: `pipeline/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain".
+not an empty frame  -  Open Question and halt. Canonical chain reference: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain".
 
 **Telemetry (required for the no-MCP gate):** Tier 1 uses `mcp__claude_ai_Figma__*` tools. Every such MCP invocation MUST append an entry to `state.telemetry.mcpCalls[]` as `{ "tool": "<full mcp tool name>", "phase": 1, "timestamp": "<ISO-8601>" }`. This is the only phase permitted to record `phase: 1` (or `0`) entries; `smoke-no-mcp-in-dev-phases.sh` fails the run if any entry carries `phase >= 2`. Recording is what makes that BLOCKING contract enforceable  -  an MCP call left unrecorded defeats the gate, so record every one.
 
@@ -130,7 +132,7 @@ This informs:
 
 #### Step 2.5  -  Repo Map Injection (advisory, opt-in)
 
-Gated by `prefs.global.repoMap.enabled` (default: `false`). When enabled, runs `pipeline/scripts/repo-map.mjs` and injects the budgeted result into each Explore prompt as `${REPO_MAP}`. Aider-style: deterministic, no embeddings, sub-second, advisory only. Full wiring (helper invocation, properties, when-to-enable): `$HOME/.claude/multi-agent-refs/features/repo-map.md`.
+Gated by `prefs.global.repoMap.enabled` (default: `false`). When enabled, runs `$HOME/.claude/scripts/repo-map.mjs` and injects the budgeted result into each Explore prompt as `${REPO_MAP}`. Aider-style: deterministic, no embeddings, sub-second, advisory only. Full wiring (helper invocation, properties, when-to-enable): `$HOME/.claude/multi-agent-refs/features/repo-map.md`.
 
 #### Step 3  -  Codebase Exploration
 
@@ -152,7 +154,7 @@ The light tier keeps a one-line bug fix from triggering a full-repo scan; pairin
 
 #### Output contract
 
-Phase 1 produces an object conforming to `pipeline/schemas/analysis-output.schema.json` and persists it to `state.analysis`. Required fields (exact names per the schema): `stack` (detected stack identifier + primary language), `touchedAreas[]` (path + why), `risks[]` (existing-code hazards/observations the planner must respect  -  each `{risk, severity, mitigation}`; use an empty array when none), `summary` (one-paragraph human-readable). Phase 2 reads this object as its sole input  -  see `phase-2-planning.md`'s Input contract.
+Phase 1 produces an object conforming to `$HOME/.claude/schemas/analysis-output.schema.json` and persists it to `state.analysis`. Required fields (exact names per the schema): `stack` (detected stack identifier + primary language), `touchedAreas[]` (path + why), `risks[]` (existing-code hazards/observations the planner must respect  -  each `{risk, severity, mitigation}`; use an empty array when none), `summary` (one-paragraph human-readable). Phase 2 reads this object as its sole input  -  see `phase-2-planning.md`'s Input contract.
 
 **Required: validator gate (deterministic)  -  run on the persisted file immediately after the analysis object is produced; the validator's exit code decides, not the LLM turn:**
 
@@ -165,7 +167,7 @@ node $HOME/.claude/scripts/validate-analysis.mjs "$ANALYSIS_FILE"
 
 Progress line: `    → checking validator validate-analysis`
 
-Non-zero exit fails CLOSED: emit the validator stderr + `errors[]` verbatim, attempt ONE self-correction rework (re-invoke the explorer with the errors quoted, overwrite `$ANALYSIS_FILE`), re-run the validator. If it fails again -> HALT the phase with recovery hint: `ERR: analysis output failed validate-analysis.mjs twice. Inspect $ANALYSIS_FILE against pipeline/schemas/analysis-output.schema.json, then resume with /multi-agent:resume #N.` Record `agent-state.phases["1"].validator` (`pass` | `pass-after-rework` | `halted`).
+Non-zero exit fails CLOSED: emit the validator stderr + `errors[]` verbatim, attempt ONE self-correction rework (re-invoke the explorer with the errors quoted, overwrite `$ANALYSIS_FILE`), re-run the validator. If it fails again -> HALT the phase with recovery hint: `ERR: analysis output failed validate-analysis.mjs twice. Inspect $ANALYSIS_FILE against $HOME/.claude/schemas/analysis-output.schema.json, then resume with /multi-agent:resume #N.` Record `agent-state.phases["1"].validator` (`pass` | `pass-after-rework` | `halted`).
 
 Log: "Phase 1: Analysis  -  stack:{detectedStack} | {N} files identified, {summary}"
 
@@ -174,7 +176,7 @@ Log: "Phase 1: Analysis  -  stack:{detectedStack} | {N} files identified, {summa
 Forward the explorer/Opus call's token totals into the tracker so Phase 7's Cost Breakdown captures Phase 1:
 
 ```bash
-LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 1 analysis.completed \
+LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 1 analysis.completed \
   model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
@@ -185,7 +187,7 @@ Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-tele
 After the explorer returns its summary, consult the per-repo triage corpus for similar past tasks. Inject up to 3 matches into the analysis output as `priorArt[]` so Phase 2 planning can read them. Disabled when `prefs.global.priorArtEnrichment.enabled = false`.
 
 ```bash
-PRIOR=$(node pipeline/scripts/triage-memory.mjs query \
+PRIOR=$(node $HOME/.claude/scripts/triage-memory.mjs query \
   --issue "$TASK_TITLE $TASK_DESCRIPTION" --top 3 2>/dev/null | jq -c '.hits // []')
 ```
 

package/pipeline/multi-agent-refs/phases/phase-2-planning.md

@@ -25,7 +25,7 @@ Phase 2 Planning consumes the analysis document. MCP forbidden.
 
 #### Input contract
 
-Phase 2 consumes the Phase 1 output object conforming to `pipeline/schemas/analysis-output.schema.json`. Read `state.analysis` (the explorer's return value) and treat its `touchedAreas` and `risks` arrays (plus `stack` and `summary`) as authoritative input  -  do not re-explore the codebase here. (Field names are exactly those in the analysis schema; the planner's own `targetFiles` belongs to `planning-output.schema.json`, not the analysis input.)
+Phase 2 consumes the Phase 1 output object conforming to `$HOME/.claude/schemas/analysis-output.schema.json`. Read `state.analysis` (the explorer's return value) and treat its `touchedAreas` and `risks` arrays (plus `stack` and `summary`) as authoritative input  -  do not re-explore the codebase here. (Field names are exactly those in the analysis schema; the planner's own `targetFiles` belongs to `planning-output.schema.json`, not the analysis input.)
 
 #### Step 1  -  Task Decomposition
 
@@ -105,7 +105,7 @@ Based on Phase 1 `detectedStack`, assign relevant skills:
 
 #### Output contract
 
-Phase 2 produces an object conforming to `pipeline/schemas/planning-output.schema.json`  -  `tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`, plus optional `architectureNotes` and `mode`. Phase 3 reads `tasks[]` in dependency order; the schema's `blockedBy` field drives the ready-task picker.
+Phase 2 produces an object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  `tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`, plus optional `architectureNotes` and `mode`. Phase 3 reads `tasks[]` in dependency order; the schema's `blockedBy` field drives the ready-task picker.
 
 **Required: validator gate (deterministic)  -  run on the persisted file before the approval gate renders the plan; the validator's exit code decides, not the LLM turn:**
 
@@ -118,13 +118,13 @@ node $HOME/.claude/scripts/validate-planning.mjs "$PLAN_FILE"
 
 Progress line: `    → checking validator validate-planning`
 
-Non-zero exit fails CLOSED: emit the validator stderr + `errors[]` verbatim, attempt ONE self-correction rework (re-invoke the planner with the errors quoted, overwrite `$PLAN_FILE`), re-run the validator. If it fails again -> HALT the phase (never enter Phase 3 with an invalid plan) with recovery hint: `ERR: plan output failed validate-planning.mjs twice. Inspect $PLAN_FILE against pipeline/schemas/planning-output.schema.json, then resume with /multi-agent:resume #N.` Record `agent-state.phases["2"].validator` (`pass` | `pass-after-rework` | `halted`).
+Non-zero exit fails CLOSED: emit the validator stderr + `errors[]` verbatim, attempt ONE self-correction rework (re-invoke the planner with the errors quoted, overwrite `$PLAN_FILE`), re-run the validator. If it fails again -> HALT the phase (never enter Phase 3 with an invalid plan) with recovery hint: `ERR: plan output failed validate-planning.mjs twice. Inspect $PLAN_FILE against $HOME/.claude/schemas/planning-output.schema.json, then resume with /multi-agent:resume #N.` Record `agent-state.phases["2"].validator` (`pass` | `pass-after-rework` | `halted`).
 
 Log: "Phase 2: Plan  -  {N} tasks created, {M} with architecture review, validator:pass"
 
 #### Step 4.5  -  Emit Plan Todo List (opt-in)
 
-**Gated by `prefs.global.planTodos.enabled`** (default: `false`). When enabled, after the planning-output JSON validates and BEFORE the approval gate, transform `tasks[]` into a structured Todo list conforming to `pipeline/schemas/plan-todos.schema.json` and persist into `agent-state.plan`. The plan is rendered as a live, always-visible Todo list.
+**Gated by `prefs.global.planTodos.enabled`** (default: `false`). When enabled, after the planning-output JSON validates and BEFORE the approval gate, transform `tasks[]` into a structured Todo list conforming to `$HOME/.claude/schemas/plan-todos.schema.json` and persist into `agent-state.plan`. The plan is rendered as a live, always-visible Todo list.
 
 ```bash
 TODO_BLOB=$(jq '
@@ -179,7 +179,7 @@ In the skipped case, log `🧠 Phase 2: Plan  -  gate skipped ({mode}), proceedi
 **Only relevant when `state.autopilot === true` and `prefs.global.autopilotSafetyGate !== false`.** The classifier protects autopilot's zero-interaction contract from edge cases where silent execution is genuinely dangerous (security-path touch, schema migration, many-file sprawl, delete-without-paired-test).
 
 ```bash
-verdict=$(node pipeline/scripts/classify-plan-safety.mjs <(echo "$PLAN_JSON"))
+verdict=$(node $HOME/.claude/scripts/classify-plan-safety.mjs <(echo "$PLAN_JSON"))
 pause=$(jq -r '.recommendPause' <<< "$verdict")
 score=$(jq -r '.score' <<< "$verdict")
 reasons=$(jq -r '.reasons[] | "• \(.rule) (+\(.weight)): \(.detail)"' <<< "$verdict")
@@ -289,7 +289,7 @@ Handle the selection:
 
 No hard cap on edit iterations  -  the user controls exit via the Approve / Cancel options. Between iterations, keep only the **latest plan** as canonical; previous renders are in the log for audit but do not re-enter the validator.
 
-**Validator**: every revised plan goes through `node pipeline/scripts/validate-planning.mjs -` before re-render. If validation fails after an edit, log `⚠️ Phase 2: Plan validator failed after edit request #N  -  retrying Opus once` and retry once; on second failure surface the validator error to the user and go back to approval prompt with the pre-edit plan.
+**Validator**: every revised plan goes through `node $HOME/.claude/scripts/validate-planning.mjs -` before re-render. If validation fails after an edit, log `⚠️ Phase 2: Plan validator failed after edit request #N  -  retrying Opus once` and retry once; on second failure surface the validator error to the user and go back to approval prompt with the pre-edit plan.
 
 #### Step 6  -  Mode-specific short-circuit (reference)
 
@@ -309,7 +309,7 @@ The 4 pipeline modes interact with the gate as follows. This table is the source
 After plan generation (and after each edit-loop iteration), forward Opus call totals so Phase 7's Cost Breakdown captures Phase 2:
 
 ```bash
-LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 2 plan.generated \
+LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2 plan.generated \
   model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR iteration=$N
 ```
 

package/pipeline/multi-agent-refs/phases/phase-3-dev.md

@@ -6,9 +6,11 @@
 
 Per Locked decision 30, Phase 3 Dev consumes the analysis document as the sole design source. MCP / Figma REST / Figma URL fetches are forbidden.
 
-Pre-flight steps (run in order, abort on failure):
+Pre-flight steps (run in order, abort on failure).
 
-1. **Analysis document presence**: locate `analysis/<feature-slug>-<platform>.md` for the active platform.
+**Steps 1, 2, 3, 5 and 6 apply only when Phase 1 ran.** In the `--dev` family (`state.onlyDevelop === true`) there is no analysis document by design, so those steps are recorded as `not-applicable (no Phase 1 in this mode)` and skipped  -  an unconditional abort here would make every fast mode impossible, which is the contradiction the modes have always carried in practice. Steps 4, 7 and 8 apply in every mode.
+
+1. **Analysis document presence** (Phase 1 modes only): locate `analysis/<feature-slug>-<platform>.md` for the active platform.
    - Path resolution: `state.run.repoPath` + `/analysis/<feature>-<platform>.md`
    - Multi-repo runs: each selected repo MUST have the file under its working tree
    - **Abort condition**: file missing -> exit with `ERR: analysis doc missing for <platform>. Run /multi-agent:analysis "<feature>" first to generate it.`
@@ -28,6 +30,16 @@ Pre-flight steps (run in order, abort on failure):
 
 7. **MCP forbidden**: any attempt to call `mcp__claude_ai_Figma__*` in Phase 3 is a violation. The smoke gate `smoke-no-mcp-in-dev-phases.sh` (see CHANGELOG [9.0.0]) checks `state.telemetry.mcpCalls[]` after run and fails if Phase 3 contributed any entry.
 
+8. **Criteria ledger (required, every mode)**: the moment this phase consults a skill, a marketplace plugin skill, a stack guide or a module `CLAUDE.md` in order to write code, append an entry to `state.telemetry.skillCalls[]`:
+
+   ```json
+   {"skill": "ios-coding-standard", "phase": 3, "targetFiles": ["Sources/Login/LoginViewModel.swift"], "timestamp": "<ISO-8601>"}
+   ```
+
+   `targetFiles` is required: a skill applied to the wrong files still reads as "applied" without it, so coverage could not be attributed. Append at the moment of consultation, not retrospectively at the end of the phase.
+
+   This is a **self-report**, and Phase 4 treats it as such. Step 1.78 resolves the criteria independently and defaults `ledger.source` to `derived`; a skill named here that the resolver cannot bind to a changed file is flagged rather than believed. The record still earns its keep, because it is the only signal that separates "this skill was applied to the wrong files" from "this skill was never opened"  -  and because a phase that has to name what it followed tends to follow something.
+
 The analysis document is the SOLE design source in Phase 3. Variant choices, padding values, color tokens, copy strings, accessibility identifiers, and test method names all come from the rendered Pass B cells. If something is missing in the analysis doc, the fix is to re-run `/multi-agent:analysis`, not to fetch from Figma.
 
 <!-- progress-contract: applied -->
@@ -36,11 +48,11 @@ The analysis document is the SOLE design source in Phase 3. Variant choices, pad
 
 #### Input contract
 
-Phase 3 consumes the Phase 2 output object conforming to `pipeline/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`) plus the architecture review notes. Tasks execute in dependency order; the schema's `blockedBy` field drives the ready-task picker. In `--dev` mode (no Phase 2), Sonnet/Opus generates the equivalent task list inline before entering the loop below.
+Phase 3 consumes the Phase 2 output object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`) plus the architecture review notes. Tasks execute in dependency order; the schema's `blockedBy` field drives the ready-task picker. In `--dev` mode (no Phase 2), Sonnet/Opus generates the equivalent task list inline before entering the loop below.
 
-**Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]`, Phase 3 iterates via `pipeline/lib/plan-todos.sh next/start/complete/fail` instead of walking `tasks[]` directly. When disabled, the loop walks `tasks[]` from `planning-output`  -  TDD contract is unchanged. Full helper loop + state semantics: `$HOME/.claude/multi-agent-refs/features/plan-todos.md`.
+**Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]`, Phase 3 iterates via `$HOME/.claude/lib/plan-todos.sh next/start/complete/fail` instead of walking `tasks[]` directly. When disabled, the loop walks `tasks[]` from `planning-output`  -  TDD contract is unchanged. Full helper loop + state semantics: `$HOME/.claude/multi-agent-refs/features/plan-todos.md`.
 
-**Shadow-Git checkpoints (opt-in)**: gated by `prefs.global.shadowGit.enabled` (default: `false`). When enabled, the orchestrator snapshots the worktree via `pipeline/lib/shadow-git.sh` so sub-phase rollback is possible without touching the project's real `.git` history. Lifecycle: `shadow-git.sh init` (Phase 0 baseline), `shadow-git.sh snapshot` (per step after `plan-todos complete`), `shadow-git.sh restore <sha> --files` (rollback). Modes: `per-todo-step` (default) or `per-tool-call`. Full wiring + storage cap: `$HOME/.claude/multi-agent-refs/features/shadow-git.md`.
+**Shadow-Git checkpoints (opt-in)**: gated by `prefs.global.shadowGit.enabled` (default: `false`). When enabled, the orchestrator snapshots the worktree via `$HOME/.claude/lib/shadow-git.sh` so sub-phase rollback is possible without touching the project's real `.git` history. Lifecycle: `shadow-git.sh init` (Phase 0 baseline), `shadow-git.sh snapshot` (per step after `plan-todos complete`), `shadow-git.sh restore <sha> --files` (rollback). Modes: `per-todo-step` (default) or `per-tool-call`. Full wiring + storage cap: `$HOME/.claude/multi-agent-refs/features/shadow-git.md`.
 
 #### Component tasks  -  delegated dispatch (taskType === "component")
 
@@ -78,7 +90,7 @@ If the latest iteration has `triage.approved === true` AND `accepted === []`, Ph
 **Telemetry**: at the start of every re-entry, emit:
 
 ```bash
-pipeline/scripts/log-metric.sh "$TASK_ID" 3 rework.started \
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 rework.started \
   iteration=$ITERATION accepted_blocking=$BLOCKING accepted_important=$IMPORTANT
 ```
 
@@ -241,7 +253,7 @@ release_build_lock() { rm -rf "$BUILD_LOCK"; }
 
 #### Step 3.5  -  Dev Critic (Evaluator-Optimizer, opt-in)
 
-Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4: dispatch `dev-critic` sub-agent (Sonnet), run 4 deterministic gates (build / lint / test / secrets), then platform checklist. STRICT loop cap  -  **max 2 iterations** (round 2 re-checks round-1 failures only); round 3+ returns `escalate: true`. Severity routing: `blocking` → generator must fix; `important` → SHOULD fix or pass through to Phase 4; `suggestion` → generator's judgement. Full agent contract, schema, telemetry, when-to-enable: `$HOME/.claude/multi-agent-refs/features/dev-critic.md` + `pipeline/agents/dev-critic.md`.
+Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4: dispatch `dev-critic` sub-agent (Sonnet), run 4 deterministic gates (build / lint / test / secrets), then platform checklist. STRICT loop cap  -  **max 2 iterations** (round 2 re-checks round-1 failures only); round 3+ returns `escalate: true`. Severity routing: `blocking` → generator must fix; `important` → SHOULD fix or pass through to Phase 4; `suggestion` → generator's judgement. Full agent contract, schema, telemetry, when-to-enable: `$HOME/.claude/multi-agent-refs/features/dev-critic.md` + `$HOME/.claude/agents/dev-critic.md`.
 
 ---
 
@@ -262,7 +274,7 @@ After the build/test green step and BEFORE Phase 4 handoff, run one diff-shrink
 5. **Record tokens in the cost ledger** so Phase 7's Cost Breakdown captures the pass:
 
 ```bash
-LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 3 dev.simplifier_pass \
+LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 dev.simplifier_pass \
   model=sonnet tokens_in=$IN tokens_out=$OUT duration_ms=$DUR \
   edits_returned=$RET edits_applied=$APPLIED edits_skipped=$SKIPPED
 ```
@@ -292,8 +304,11 @@ When `agent-state.json.onlyDevelop === true`, Phase 3 runs self-contained with *
 | Task granularity | Per-plan-item | Agent decides |
 | Status updates | Per task item | Single in_progress → completed |
 | Scope confirmation | Phase 2 user approval | None (agent autonomous) |
+| Review of the result | Phase 4 | Phase 4 (same) |
+
+Because the agent determines its own scope here, Phase 4 is the only place that checks the result against anything external. Record every skill, plugin skill and guide consulted during this phase into `state.telemetry.skillCalls[]` with the files it was applied to  -  Phase 4 resolves the criteria set independently, and this record is what lets it tell "applied and honoured" from "never opened".
 
-**Combinable with autopilot**: `--dev autopilot` = zero interaction. Init → Dev → auto-commit → auto-PR → Report.
+**Combinable with autopilot**: `--dev autopilot` = zero interaction. Init → Dev → Review (auto-fix) → auto-commit → auto-PR → Report.
 
 **Tracker visibility during Opus dispatch**: on Claude Code the model switch to Opus happens via subagent dispatch, and the parent widget cannot move while an Agent call is in flight. Dispatch per task from the self-generated task list (never one monolithic call for the whole phase), set the pre-dispatch `activeForm` marker, and record tokens between chunks  -  full rules in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "Delegated phases".
 
@@ -333,21 +348,21 @@ If a todo has no `repo` tag in multi-repo mode → log warning + ask user, do no
 **Recording a pass (default-FAIL evidence gate):** before setting `buildStatus.ok = true`, the build output must be tee'd to a log and that log must substantiate the success  -  a zero exit code alone is not trusted. Run the evidence gate; on exit 1, do NOT record a pass:
 ```bash
 <build-command> 2>&1 | tee "$WORKTREE/.build.log"
-node pipeline/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log" \
+node $HOME/.claude/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log" \
   || { echo "build pass unverified  -  treat as failure"; /* keep buildStatus.ok=false */ }
 ```
 This closes the gap where an agent records "built" without ever producing build output.
 
 **Telemetry**: Per-repo metrics in addition to per-task metrics:
 ```bash
-pipeline/scripts/log-metric.sh "$TASK_ID" 3 build.completed repo=common duration_ms=$D status=ok
-pipeline/scripts/log-metric.sh "$TASK_ID" 3 build.completed repo=uicomponents duration_ms=$D status=ok
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 build.completed repo=common duration_ms=$D status=ok
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 build.completed repo=uicomponents duration_ms=$D status=ok
 ```
 
 **Token forwarding:** every TDD round (red, green, refactor) that hits the dev model MUST forward token totals into the tracker so Phase 7's Cost Breakdown captures Phase 3:
 
 ```bash
-LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 3 dev.tdd_round \
+LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 dev.tdd_round \
   model=<sonnet|opus> step=<red|green|refactor> \
   tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```