@mmerterden/multi-agent-pipeline 18.0.0 → 19.0.0

package/pipeline/multi-agent-refs/phases/{phase-3-dev.md → phase-2-dev.md}

@@ -1,10 +1,10 @@
-### Phase 3: Dev (Sonnet)
+### Phase 2: Dev (Sonnet)
 
-> **TLDR**  -  Sonnet executes the plan task-by-task with TDD (red→green→refactor). Required: issue-tracker status moved to "In Progress" before any code, with a post-mutation verify step (re-reads the field, retries once on silent VALIDATION failures). Build verification after each task (up to 3 retries). Build-queue lock serializes concurrent xcodebuild. A Short run (`state.onlyDevelop`) uses Opus self-contained, with no Phase 2 plan. `taskType === component` **short-circuits the TDD path** and delegates the whole phase to the enabled `ai-<platform>-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`)  -  see next subsection.
+> **TLDR**  -  Sonnet executes the plan task-by-task with TDD (red→green→refactor). Required: issue-tracker status moved to "In Progress" before any code, with a post-mutation verify step (re-reads the field, retries once on silent VALIDATION failures). Build verification after each task (up to 3 retries). Build-queue lock serializes concurrent xcodebuild. A Short run (`state.onlyDevelop`) uses Opus self-contained, with no Phase 1 plan. `taskType === component` **short-circuits the TDD path** and delegates the whole phase to the enabled `ai-<platform>-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`)  -  see next subsection.
 
-## Phase 3 Pre-flight (BLOCKING, v9.0.0)
+## Phase 2 Pre-flight (BLOCKING, v9.0.0)
 
-Per Locked decision 30, Phase 3 Dev consumes the analysis document as the sole design source. **Figma** MCP / REST / URL fetches are forbidden; the toolkit MCP is not, and Steps 3.4 and 3.55 call it.
+Per Locked decision 30, Phase 2 Dev consumes the analysis document as the sole design source. **Figma** MCP / REST / URL fetches are forbidden; the toolkit MCP is not, and Steps 3.4 and 3.55 call it.
 
 Pre-flight steps (run in order, abort on failure).
 
@@ -17,19 +17,19 @@ Pre-flight steps (run in order, abort on failure).
 
 2. **Parse YAML front-matter** into `state.analysis.frontMatter`: `feature`, `platform`, `language`, `mode`, `evidence_digest`, `template_version`. **Abort** when `template_version` < `v3`; there is no degraded mode.
 
-3. **Spec freshness**: two checks, both non-blocking, both flagged for Phase 4.
+3. **Spec freshness**: two checks, both non-blocking, both flagged for Phase 3.
    - **Digest**: `state.run.lastAnalysisDigest` against `frontMatter.evidence_digest`. Mismatch = written from different evidence. Key absent -> `not-verifiable`, never `fresh`.
    - **Repo drift**: `git diff --name-only <state.run.analysisBaseCommit>..HEAD` intersected with Section 14 paths. Non-empty = the repo moved under the spec. This is the one that fires on a `reused` doc, where the digest still matches because the evidence inputs did not change.
 
-4. **Code Connect mapping lookup**: for each component named in analysis Section 6 (Bileşen Envanteri), search the repo for matching `*.figma.swift` / `*.figma.kt` files. Persist hits to `state.dev.codeConnect[<componentName>]`. Missing mappings are not blockers but the Phase 4 reviewer will flag them.
+4. **Code Connect mapping lookup**: for each component named in analysis Section 6 (Bileşen Envanteri), search the repo for matching `*.figma.swift` / `*.figma.kt` files. Persist hits to `state.dev.codeConnect[<componentName>]`. Missing mappings are not blockers but the Phase 3 reviewer will flag them.
 
-5. **Standards binding citations**: read `analysis Section 21 References` table. For each row with `Rol: bağlayıcı / binding`, persist the source path into `state.dev.standardsBindings[]`. Phase 3 Dev tasks MUST cite at least one binding source per architectural decision (pre-existing Locked decision 8).
+5. **Standards binding citations**: read `analysis Section 21 References` table. For each row with `Rol: bağlayıcı / binding`, persist the source path into `state.dev.standardsBindings[]`. Phase 2 Dev tasks MUST cite at least one binding source per architectural decision (pre-existing Locked decision 8).
 
 5b. **Test plan handoff (the RED input)**: read `analysis Section 15` into `state.dev.testPlan[]` (15.1 unit rows with name/arrange/act/expected/`BR-` id, 15.2 snapshot variants, 15.6 UI flows, 15.7 manual scenarios). **RED writes these tests, not invented ones** - development is TDD, so the analysis matrix is literally the first thing written. A row too vague to write from is an analysis defect: open a Section 20 question, do not improvise.
 
-6. **Conventions handoff**: read `analysis Section 13.1 Concept Table` (Pass B output with footnotes). Persist concept-to-realization mapping into `state.dev.conventions[<concept>]`. Phase 3 implementation uses these names verbatim, and a non-empty `sharedUtilities` bucket is binding: bind those formatters/rule-facades/tokens, never hand-roll a duplicate (e.g., if Section 13.1 says "State holder: PassengerFlightViewModel", Phase 3 names the class exactly `PassengerFlightViewModel`).
+6. **Conventions handoff**: read `analysis Section 13.1 Concept Table` (Pass B output with footnotes). Persist concept-to-realization mapping into `state.dev.conventions[<concept>]`. Phase 2 implementation uses these names verbatim, and a non-empty `sharedUtilities` bucket is binding: bind those formatters/rule-facades/tokens, never hand-roll a duplicate (e.g., if Section 13.1 says "State holder: PassengerFlightViewModel", Phase 2 names the class exactly `PassengerFlightViewModel`).
 
-7. **MCP forbidden**: calling `mcp__claude_ai_Figma__*` in Phase 3 is a violation. `smoke-no-mcp-in-dev-phases.sh` reads `state.telemetry.mcpCalls[]` after the run and fails if Phase 3 contributed an entry.
+7. **MCP forbidden**: calling `mcp__claude_ai_Figma__*` in Phase 2 is a violation. `smoke-no-mcp-in-dev-phases.sh` reads `state.telemetry.mcpCalls[]` after the run and fails if Phase 2 contributed an 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[]`:
 
@@ -37,11 +37,11 @@ Pre-flight steps (run in order, abort on failure).
    {"skill": "ios-coding-standard", "phase": 3, "targetFiles": ["Sources/Login/LoginViewModel.swift"], "timestamp": "<ISO-8601>"}
    ```
 
-   `targetFiles` is required  -  without it a skill applied to the wrong files still reads as "applied". Append at the moment of consultation, not at the end of the phase. Phase 4 Step 1.78 treats this as self-report only and resolves criteria independently; it is the one signal separating "applied to the wrong files" from "never opened".
+   `targetFiles` is required  -  without it a skill applied to the wrong files still reads as "applied". Append at the moment of consultation, not at the end of the phase. Phase 3 Step 1.78 treats this as self-report only and resolves criteria independently; it is the one signal separating "applied to the wrong files" from "never opened".
 
 9. **Stack skill routing (every `taskType`, when a stack toolkit plugin is enabled)**: ask each enabled toolkit's own `index` skill which skills govern this task, load them BEFORE writing code, and record each into `state.telemetry.skillCalls[]` with `routedBy: "<toolkit>:index@<version>"`. Candidates are the effective `enabledPlugins`, not a stack table. The routing table stays in the plugin  -  a copy here would be the stale one, and `rules/outside-the-pipeline.md` runs the same routing outside a run. A screen-creation task loads the routed toolkit's `workflow/create-screen` when one exists. No toolkit, or none enabled, is a recorded no-op, not a halt. Contract: [`features/stack-skill-routing.md`]($HOME/.claude/multi-agent-refs/features/stack-skill-routing.md).
 
-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.
+The analysis document is the SOLE design source in Phase 2. 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 -->
 
@@ -49,15 +49,15 @@ 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 `$HOME/.claude/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `title`, `type`, `files`, and optional `dependsOn` / `acceptanceCriteria`) plus the architecture review notes. Tasks execute in dependency order; the schema's `dependsOn` field drives the ready-task picker. In a Short run (no Phase 2), Opus generates the equivalent task list inline before entering the loop below.
+Phase 2 consumes the Phase 1 output object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `title`, `type`, `files`, and optional `dependsOn` / `acceptanceCriteria`) plus the architecture review notes. Tasks execute in dependency order; the schema's `dependsOn` field drives the ready-task picker. In a Short run (no Phase 1), 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 `$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`. A todo with `sourceTag: Reuse` binds the file analysis already found; `Modify` edits in place. Writing a new file over a `Reuse` step is a Locked 11 violation and Phase 4 flags it.
+**Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 1 Step 11 emitted a `plan.todos[]`, Phase 2 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`. A todo with `sourceTag: Reuse` binds the file analysis already found; `Modify` edits in place. Writing a new file over a `Reuse` step is a Locked 11 violation and Phase 3 flags it.
 
 **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")
 
-When Phase 0 Step 7 classified the task as `component`, Phase 3 delegates the entire phase to the enabled `ai-<platform>-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`) via the Skill tool and does NOT run the TDD loop below. The dispatch layer passes the plugin skill the analysis Section 6 (Bileşen Envanteri) entry + Section 13.1 conventions for the named component as context. Because plugin skills do not write pipeline state, the **dispatch layer** (not the skill) owns `state.phases["3"].subphases[]`, recording a coarse component-build row - multi-agent's `phase-tracker` reads that array with no special case. Plugin resolution (dual-name), dispatch call, failure/resume, multi-repo, Short-run elisions, and the intentional cross-CLI divergence live in `$HOME/.claude/multi-agent-refs/component-dispatch.md` - read it before editing component-task behaviour here. Phase 3 still owns: progress line `-> dispatching create-component <name>`, `retryCount` cap at 3, and fallthrough to the TDD path when dispatch prerequisites are missing (`taskType` absent OR the plugin is not enabled in this repo -> log anomaly, halt or run TDD per component-dispatch.md).
+When Phase 0 Step 7 classified the task as `component`, Phase 2 delegates the entire phase to the enabled `ai-<platform>-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`) via the Skill tool and does NOT run the TDD loop below. The dispatch layer passes the plugin skill the analysis Section 6 (Bileşen Envanteri) entry + Section 13.1 conventions for the named component as context. Because plugin skills do not write pipeline state, the **dispatch layer** (not the skill) owns `state.phases["2"].subphases[]`, recording a coarse component-build row - multi-agent's `phase-tracker` reads that array with no special case. Plugin resolution (dual-name), dispatch call, failure/resume, multi-repo, Short-run elisions, and the intentional cross-CLI divergence live in `$HOME/.claude/multi-agent-refs/component-dispatch.md` - read it before editing component-task behaviour here. Phase 2 still owns: progress line `-> dispatching create-component <name>`, `retryCount` cap at 3, and fallthrough to the TDD path when dispatch prerequisites are missing (`taskType` absent OR the plugin is not enabled in this repo -> log anomaly, halt or run TDD per component-dispatch.md).
 
 For non-component taskTypes (`bugfix`, `feature`, `refactor`, `chore`), continue with the standard TDD section below.
 
@@ -67,27 +67,27 @@ Applies to EVERY task whose analysis doc carries design ground truth (Section 6
 
 1. **1:1, not interpretation.** The captured frames are the reference for every UI line. Layout, variant states, copy, and colours come from the analysis doc's measured values  -  never eyeballed, never "close enough".
 2. **Code Connect decides the component.** A mapped component (`CodeConnectSnippet` / repo `*.figma.swift` / `*.figma.kt` row) MUST be used verbatim  -  sound-alike substitutes are forbidden; a missing modifier is added to the component's `+Modifiers` extension, never forked. No mapping exists -> write a NEW component per the Configuration/View/Modifiers architecture; never inline ad-hoc UI into the consumer screen.
-3. **Inter-component spacing is part of the design.** Gaps, paddings, and alignment BETWEEN components must match the frame's measured values, mapped to spacing tokens (`Spacing*`)  -  never invented numbers. A spacing/layout deviation is a `review_blocking` finding in Phase 4 Step 1.8, not a nitpick.
+3. **Inter-component spacing is part of the design.** Gaps, paddings, and alignment BETWEEN components must match the frame's measured values, mapped to spacing tokens (`Spacing*`)  -  never invented numbers. A spacing/layout deviation is a `review_blocking` finding in Phase 3 Step 1.8, not a nitpick.
 
 Missing design data (variant, padding, copy) → HALT and instruct the user to re-run `/multi-agent:analysis`; never guess and never call Figma MCP from this phase.
 
-#### Re-entry from Phase 4 triage
+#### Re-entry from Phase 3 triage
 
-Phase 3 runs twice in the pipeline lifetime: first for initial development, then optionally for rework after Phase 4 review. **Phase 3 never acts on raw reviewer output.** It only consumes `triage.accepted` findings  -  Fable triage in Phase 4 already filtered false-positives, deferred out-of-scope items, and rejected noise.
+Phase 2 runs twice in the pipeline lifetime: first for initial development, then optionally for rework after Phase 3 review. **Phase 2 never acts on raw reviewer output.** It only consumes `triage.accepted` findings  -  Fable triage in Phase 3 already filtered false-positives, deferred out-of-scope items, and rejected noise.
 
-When re-entering from Phase 4:
+When re-entering from Phase 3:
 
 1. Read `state.reviewIterations[-1]`  -  the latest iteration's **accepted** list.
 2. For each `accepted` finding where `severity === "blocking"` or `severity === "important"`:
-   - Treat it exactly like a Phase 2 plan task (TDD cycle, build verify).
+   - Treat it exactly like a Phase 1 plan task (TDD cycle, build verify).
    - Quote the original `issue` + `fix` text in the task description so the dev agent has full context.
 3. `accepted.suggestion` items are applied opportunistically (no TDD loop required) unless the user asked for suggestions to be treated strictly.
-4. `deferred` items are NOT actioned in this re-entry  -  they surface in Phase 7's "Follow-up items" section.
+4. `deferred` items are NOT actioned in this re-entry  -  they surface in Phase 5's "Follow-up items" section.
 5. `rejected` items are never touched. Log their IDs + triage reasons for audit only.
-6. After rework, increment `state.phases["3"].retryCount`; hard-kill at `retryCount === 3` and escalate to the user. Do not loop indefinitely. When `prefs.global.autopilotCircuitBreaker.enabled` is true (default), record the hard-kill before escalating as `state.circuitBreaker = {tripped: true, trigger: 3, detail: "rework cycles exhausted", checkpoint: {phase: 3, step: "re-entry", iteration: <n>}, trippedAt, counters: {reworkCycles: <n>}}`: the rework-storm trigger; `autopilotCircuitBreaker.maxReworkCycles` (default 3) is bounded above by this cap.
+6. After rework, increment `state.phases["2"].retryCount`; hard-kill at `retryCount === 3` and escalate to the user. Do not loop indefinitely. When `prefs.global.autopilotCircuitBreaker.enabled` is true (default), record the hard-kill before escalating as `state.circuitBreaker = {tripped: true, trigger: 3, detail: "rework cycles exhausted", checkpoint: {phase: 3, step: "re-entry", iteration: <n>}, trippedAt, counters: {reworkCycles: <n>}}`: the rework-storm trigger; `autopilotCircuitBreaker.maxReworkCycles` (default 3) is bounded above by this cap.
 7. When `state.reviewIterations[-1].delta` exists, `stillPresent[]` findings come first in the task list, quoted `STILL PRESENT after round N-1's fix`; repeating the previous attempt is the loop the circuit-breaker stops.
 
-If the latest iteration has `triage.approved === true` AND `accepted === []`, Phase 3 was entered by mistake  -  log the anomaly and return to Phase 5.
+If the latest iteration has `triage.approved === true` AND `accepted === []`, Phase 2 was entered by mistake  -  log the anomaly and return to Phase 3.
 
 **Telemetry**: at the start of every re-entry, emit:
 
@@ -105,7 +105,7 @@ For each task (respecting dependency order):
    - **Where it applies**:
      - Jira: transition issue to "In Progress" via REST API (`/rest/api/2/issue/{id}/transitions`)
      - GitHub Projects V2: `updateProjectV2ItemFieldValue` on the Status field (singleSelectOptionId)
-     - Internal state: `agent-state.json` → `phases["3"].status = "in_progress"`
+     - Internal state: `agent-state.json` → `phases["2"].status = "in_progress"`
    - **Post-update verify** (catches silent VALIDATION errors from stale option IDs after board rebuilds):
      - Re-read the Status field after mutation.
      - If the value is NOT `In Progress` (Jira) / `In Develop` (Projects V2), re-fetch current option IDs and retry ONCE.
@@ -117,7 +117,7 @@ For each task (respecting dependency order):
 3. **TDD cycle** (Launch Agent with `model: "sonnet"`)  -  gated by `state.testPolicy`: `tdd` = the loop below; `tests-after` = skip RED, author the same tests once green; `none` = author no tests (existing ones never weakened), report "tests not written - project policy" rather than a gap.
 
    **RED  -  Write ONE failing test first:**
-   - **Rework re-entry**: if `state.reviewIterations[-1].verifyByTest.redTests[]` exists (Phase 4 Step 3.7 ran), those failing repro tests ARE the RED step for their findings  -  make them green, do not write a duplicate failing test and do not delete or weaken them. See `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`.
+   - **Rework re-entry**: if `state.reviewIterations[-1].verifyByTest.redTests[]` exists (Phase 3 Step 3.7 ran), those failing repro tests ARE the RED step for their findings  -  make them green, do not write a duplicate failing test and do not delete or weaken them. See `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`.
    - Test framework: use whatever the project already uses. Detect from existing test files:
      - `@Test` / `#expect` → Swift Testing
      - `XCTestCase` / `XCTAssert` → XCTest
@@ -146,7 +146,7 @@ For each task (respecting dependency order):
 
    **GREEN  -  Minimal code to pass:**
    - Smallest change that makes the test green  -  no extras
-   - **Existing tests are immutable**: deleting, renaming, skipping, or weakening an existing assertion to reach green is a violation. A test may change only when the task itself changes the spec that test encodes, and the commit body must name the changed test and the spec change. (Deterministic backstop: the `test_lines_removed` signal in Phase 4 Step 1.75 flags test files that shrink.)
+   - **Existing tests are immutable**: deleting, renaming, skipping, or weakening an existing assertion to reach green is a violation. A test may change only when the task itself changes the spec that test encodes, and the commit body must name the changed test and the spec change. (Deterministic backstop: the `test_lines_removed` signal in Phase 3 Step 1.75 flags test files that shrink.)
    - Run the same test again → must PASS
    - Run full test suite → no regressions:
      ```bash
@@ -162,7 +162,7 @@ For each task (respecting dependency order):
    **REFACTOR (if needed):**
    - Only if duplication or naming is poor
    - Re-run tests after refactor → still GREEN
-   - **Stability (required):** run every test added or changed in this diff `prefs.global.testStability.repeatCount` times (default 3; 1 disables) with the single-test invocation above. Disagreeing outcomes are not GREEN: log `test.flake_signal file=<f> passed=<k> of=<N>` and fix the test or the code first. A pass only on retry is a flake signal, not a pass. Same rule on the Phase 4 rework re-entry.
+   - **Stability (required):** run every test added or changed in this diff `prefs.global.testStability.repeatCount` times (default 3; 1 disables) with the single-test invocation above. Disagreeing outcomes are not GREEN: log `test.flake_signal file=<f> passed=<k> of=<N>` and fix the test or the code first. A pass only on retry is a flake signal, not a pass. Same rule on the Phase 3 rework re-entry.
 
    **Target resolution** (auto-detect once per project, cache in `agent-state.json`; ios resolves scheme + simulator, android resolves module + variant, backend/web need none):
    ```bash
@@ -185,9 +185,9 @@ For each task (respecting dependency order):
    git -C "{worktreePath}" add -A
    git -C "{worktreePath}" commit -m "wip({scope}): {task summary} [{jiraId}]"
    ```
-   WIP commits are squashed in Phase 6 before PR. This prevents work loss if a later task fails or the session crashes.
+   WIP commits are squashed in Phase 4 before PR. This prevents work loss if a later task fails or the session crashes.
 7. Update task status: `completed` (apply the same verify rule  -  re-read the Status field and retry once on mismatch)
-8. Log: "Phase 3: {task}  -  Test + Build passed"
+8. Log: "Phase 2: {task}  -  Test + Build passed"
 
 ---
 
@@ -226,9 +226,9 @@ release_build_lock() { rm -rf "$BUILD_LOCK"; }
 
 **This applies to ALL xcodebuild calls in the pipeline:**
 
-- Phase 3 Step 4 (build after development)
-- Phase 4 Step 1 Gate 1 (build gate before review)
-- Phase 4 Step 1 Gate 3 (test gate before review)
+- Phase 2 Step 4 (build after development)
+- Phase 3 Step 1 Gate 1 (build gate before review)
+- Phase 3 Step 1 Gate 3 (test gate before review)
 
 **Android**: same lock discipline  -  the Gradle daemon and `build/` outputs contend across parallel worktrees. **Backend/web** (Python, Node.js): no lock needed  -  these build/test in parallel without conflicts.
 
@@ -236,13 +236,13 @@ 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` + `$HOME/.claude/agents/dev-critic.md`.
+Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 3: 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 3; `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`.
 
 ---
 
 #### Step 3.55  -  Visual evidence capture (UI changes only)
 
-Re-decide `visualEvidence.required` from the real diff first - Phase 0's `bugfix` verdict is provisional (section 1a). When required, capture with the build that just went green - here, not Phase 5 (section 3). Exit 4 anywhere below is a gap, not a failure. Contract: `features/visual-evidence.md`.
+Re-decide `visualEvidence.required` from the real diff first - Phase 0's `bugfix` verdict is provisional (section 1a). When required, capture with the build that just went green - here, not Phase 3 (section 3). Exit 4 anywhere below is a gap, not a failure. Contract: `features/visual-evidence.md`.
 
 `EVIDENCE_PLATFORM=$(jq -r '.visualEvidence.platform // ""' "$STATE_FILE")`. Empty closes every tier below with that reason; passing it on is exit 2.
 
@@ -258,11 +258,11 @@ Re-decide `visualEvidence.required` from the real diff first - Phase 0's `bugfix
 
 Persist `state.uiTest` and the artefact entries. A UI test that ran is subject to the default-FAIL rule like the build: run `evidence-gate.mjs --claim test --status passed --evidence "$WORKTREE/.pipeline/ui-test.log"` first, because a runner that died before reaching the tests also exits non-zero.
 
-#### Step 3.6  -  Code-simplifier pass (required diff shrink, before Phase 4 handoff)
+#### Step 3.6  -  Code-simplifier pass (required diff shrink, before Phase 3 handoff)
 
-After the build/test green step and BEFORE Phase 4 handoff, run one diff-shrink round (bloated diffs waste Phase 4 reviewer tokens and unfocus the PR).
+After the build/test green step and BEFORE Phase 3 handoff, run one diff-shrink round (bloated diffs waste Phase 3 reviewer tokens and unfocus the PR).
 
-1. **Dispatch ONE subagent** (`subagent_type: "general-purpose"`, model: `sonnet`); input is ONLY the working diff (`git -C "$WORKTREE" diff "origin/$BASE_BRANCH"...HEAD`) + task summary. No correctness re-review (Phase 4's job), no new features. Exactly four smells:
+1. **Dispatch ONE subagent** (`subagent_type: "general-purpose"`, model: `sonnet`); input is ONLY the working diff (`git -C "$WORKTREE" diff "origin/$BASE_BRANCH"...HEAD`) + task summary. No correctness re-review (Phase 3's job), no new features. Exactly four smells:
    - **Comment bloat**  -  comments restating code, scaffolding notes, TODO chatter
    - **Unrelated rewrites**  -  hunks outside task scope (re-formatting, unrequested rename sweeps)
    - **Dead code**  -  unused symbols, unreachable branches, commented-out blocks from this diff
@@ -272,7 +272,7 @@ After the build/test green step and BEFORE Phase 4 handoff, run one diff-shrink
 2. **Return contract**  -  a list of shrink edits `{ "file", "lines", "edit", "rationale", "risk": "safe|unsafe" }`; the subagent never writes files. Keep the `rationale` strings: Step 3.7 writes them into `scope-check.json`.
 3. **Apply safe edits only**  -  skip `unsafe` (logged). Zero edits is normal  -  log and continue. Progress line: `    → applying shrink edits ({N} applied, {M} skipped)`
 4. **Re-run build + tests** (same build-queue lock + evidence-gate rule as Step 4). Any breakage -> revert shrink edits wholesale and proceed pre-shrink; the simplifier must never cost a green state.
-5. **Record tokens in the cost ledger** so Phase 7's Cost Breakdown captures the pass:
+5. **Record tokens in the cost ledger** so Phase 5's Cost Breakdown captures the pass:
 
 ```bash
 LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 dev.simplifier_pass \
@@ -286,20 +286,20 @@ Scope guard: a single pass, never looped. Runs in a Short run too; component tas
 
 #### Step 3.7  -  Scope self-check (required handoff artifact)
 
-Phase 4 cannot reconstruct why each file was touched or what was left out on purpose, so Dev states both before the handoff: write `$WORKTREE/.pipeline/scope-check.json` (`schemas/scope-check.schema.json`: one `{path, reason}` per file in the diff, `notDone[]` with `why` in `out-of-scope | follow-up | rejected-abstraction`, and the Step 3.6 `simplifier` rationales), then run the gate. **Record rules, consumers and the full contract: `$HOME/.claude/multi-agent-refs/features/scope-check.md`.**
+Phase 3 cannot reconstruct why each file was touched or what was left out on purpose, so Dev states both before the handoff: write `$WORKTREE/.pipeline/scope-check.json` (`schemas/scope-check.schema.json`: one `{path, reason}` per file in the diff, `notDone[]` with `why` in `out-of-scope | follow-up | rejected-abstraction`, and the Step 3.6 `simplifier` rationales), then run the gate. **Record rules, consumers and the full contract: `$HOME/.claude/multi-agent-refs/features/scope-check.md`.**
 
 ```bash
 git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
   | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$WORKTREE/.pipeline/scope-check.json" --diff-files -
 ```
 
-Exit 1 lists `unjustified[]`: complete the record once and re-run. A second exit 1 does not block; log `dev.scope_check=incomplete unjustified=<n>` and hand off, and Phase 4 shows the gate output to reviewers inside `<scope-self-check>`. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
+Exit 1 lists `unjustified[]`: complete the record once and re-run. A second exit 1 does not block; log `dev.scope_check=incomplete unjustified=<n>` and hand off, and Phase 3 shows the gate output to reviewers inside `<scope-self-check>`. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
 
 ---
 
 #### Short pipeline (`state.onlyDevelop === true`)
 
-Set by the Phase 0 Step 7.5 depth picker, or by autopilot never (autopilot always runs Full). When it is true, Phase 3 runs self-contained with **Opus** (not Sonnet). No Phase 2 plan exists  -  the agent creates its own scope.
+Set by the Phase 0 Step 7.5 depth picker, or by autopilot never (autopilot always runs Full). When it is true, Phase 2 runs self-contained with **Opus** (not Sonnet). No Phase 1 plan exists  -  the agent creates its own scope.
 
 **Flow:**
 1. Read task description (from Jira, GitHub issue, or free-text)
@@ -314,13 +314,13 @@ Set by the Phase 0 Step 7.5 depth picker, or by autopilot never (autopilot alway
 | Aspect | Full | Short |
 |--------|--------|----------|
 | Model | Sonnet | **Opus** |
-| Plan source | Phase 2 task list | Self-determined |
+| Plan source | Phase 1 task list | Self-determined |
 | 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) |
+| Scope confirmation | Phase 1 user approval | None (agent autonomous) |
+| Review of the result | Phase 3 | Phase 3 (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".
+Because the agent determines its own scope here, Phase 3 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 3 resolves the criteria set independently, and this record is what lets it tell "applied and honoured" from "never opened".
 
 **Never combined with autopilot.** Autopilot skips the depth question and runs Full, so `onlyDevelop` is false in every unattended run. "Fast plus unattended" was removed in v16.0.0 and no longer exists: something has to choose when nobody is asked, and unattended is the worst place to drop analysis and planning.
 
@@ -332,7 +332,7 @@ Because the agent determines its own scope here, Phase 4 is the only place that
 
 Active when `state.projects[].length > 1` (set by Phase 0 multi-select). Single-repo flow above is preserved verbatim  -  this section adds the deltas.
 
-**Todo tagging**: Phase 2 plan items in multi-repo mode carry a `repo` field naming the target project root. The dev agent uses this tag to dispatch each todo:
+**Todo tagging**: Phase 1 plan items in multi-repo mode carry a `repo` field naming the target project root. The dev agent uses this tag to dispatch each todo:
 
 ```json
 {
@@ -352,12 +352,12 @@ If a todo has no `repo` tag in multi-repo mode → log warning + ask user, do no
 
 **Build serialization**:
 - Xcode worktrees still share `BUILD_LOCK = /tmp/claude-xcodebuild.lock`  -  multi-repo just means more callers contending for the same lock; the existing `mkdir`-based queue handles it correctly.
-- Non-Xcode repos may build in parallel across worktrees  -  but ONLY when builds are independent. If repo B's build depends on repo A's freshly-published artifact (e.g. SPM local path dependency), serialize them in dependency order. Plan items declare dependencies via Phase 2's `dependsOn` field; multi-repo dispatch respects that order.
+- Non-Xcode repos may build in parallel across worktrees  -  but ONLY when builds are independent. If repo B's build depends on repo A's freshly-published artifact (e.g. SPM local path dependency), serialize them in dependency order. Plan items declare dependencies via Phase 1's `dependsOn` field; multi-repo dispatch respects that order.
 
 **Failure isolation**: A build/test failure in one repo's worktree must NOT silently leave the other repos in a half-built state. On failure:
 1. Capture the failure into `state.projects[i].buildStatus = { ok: false, attempts: N, lastError: "..." }`
-2. The ENTIRE Phase 3 retries within that repo's worktree (max 3, same as single-repo)
-3. After 3 attempts, escalate; do NOT proceed to Phase 4 with any unbuilt repo
+2. The ENTIRE Phase 2 retries within that repo's worktree (max 3, same as single-repo)
+3. After 3 attempts, escalate; do NOT proceed to Phase 3 with any unbuilt repo
 
 **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
@@ -376,7 +376,7 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 build.completed repo=common dur
 $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:
+**Token forwarding:** every TDD round (red, green, refactor) that hits the dev model MUST forward token totals into the tracker so Phase 5's Cost Breakdown captures Phase 2:
 
 ```bash
 LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 dev.tdd_round \
@@ -427,3 +427,83 @@ wrong side of the generator, and the Debug menu never showed it.
 When the analysis doc has not recorded which trees are generated, that is a Phase 1
 gap  -  say so rather than guessing, since guessing wrong is invisible until the next
 regeneration.
+
+---
+
+## Exit gate: Verify (BLOCKING)
+
+These four deterministic gates ran at the top of Review until v19.0.0, which meant
+the build ran twice: once here at the end of Dev, once again as Review's Stage 1.
+They now run once, at this phase's exit, and Review inherits the logs instead of
+regenerating them. A failure here does not reach Review at all.
+
+#### Step 1  -  Deterministic Gates (run BEFORE AI review)
+
+If any gate fails → fix first, don't waste AI tokens reviewing broken code.
+
+```bash
+# Gate 1: Build (xcodebuild/gradle assemble/tsc/py compile  -  stack-dependent; Xcode uses the build queue lock, see Phase 2)  -  tee output to a log
+<build-command> 2>&1 | tee "$WORKTREE/.build.log"
+# Gate 2: Lint (swiftlint/ktlint/ruff/eslint  -  stack-dependent)
+# Gate 3: Tests pass (xcodebuild/gradle/pytest/the resolved node command)  -  tee output to a log
+<test-command> 2>&1 | tee "$WORKTREE/.test.log"
+# Gate 4: Secrets  -  run the scanner against the staged diff
+bash $HOME/.claude/scripts/pre-commit-check.sh
+```
+
+**Default-FAIL evidence gate (required before recording any pass):** a green exit code is not enough  -  the captured log must actually show success. Before marking build/test passed, run the evidence gate against the tee'd log; it fails CLOSED when the log is missing, empty, or shows failure markers:
+
+```bash
+node $HOME/.claude/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log" || BUILD_PASS=false
+node $HOME/.claude/scripts/evidence-gate.mjs --claim test  --status passed --evidence "$WORKTREE/.test.log"  || TEST_PASS=false
+```
+
+This prevents a false "it built" claim with no log behind it. On exit 1, treat the gate as failed (do NOT proceed to AI review) and surface the gate's `reason`.
+
+**Inherited failures (when `state.baseline.tests` exists).** Phase 0 Step 7.6 recorded whether the suite was already red, so Gate 3 blocks on what this work broke, not what it walked into:
+
+| baseline status | Gate 3 |
+|---|---|
+| `green` | unchanged; every failure is this run's |
+| `red` + `failing[]` | subtract those ids. Nothing left -> pass, logged `test:pass (inherited {N})`. A NEW failure still blocks. |
+| `red`, empty `failing[]` | do NOT pass and do NOT silently block: report `test:inherited-red (not attributable, <logPath>)` and ask. Inventing a set here masks regressions. |
+| `unknown` / absent | unchanged from today |
+
+The subtraction never widens: match on identifier only, and when identifiers cannot be compared fall to the `not attributable` row.
+
+**Gate results:**
+
+- All pass (including the evidence gate) -> proceed to AI review
+- Any fail -> fix immediately, re-run gates (no AI review until clean)
+  Log: "Phase 3: Gates  -  build:{pass/fail} lint:{pass/fail} test:{pass/fail/inherited-red} secrets:{clean/found} evidence:{ok/unverified}"
+
+##### Gate 5  -  Fortify SSC findings (runs when `state.contextLinks[]` contains a `fortify` entry, or when `prefs.global.fortify.alwaysCheck === true`)
+
+If the task description referenced a Fortify version, or named a bare issue instance id, `~/.claude/lib/fetch-fortify.sh` already populated `state.fortifyFinding` in Phase 0 (`alwaysCheck` needs `prefs.global.fortify.versionIds` to know what to scan). Phase 3 reuses that payload and applies the deterministic gate:
+
+```bash
+gate=$(jq -r '.fortifyFinding.gateOutcome // empty' "$STATE_FILE")
+if [ -z "$gate" ]; then
+  # No fortify entry in contextLinks; gate is N/A.
+  echo "→ fortify gate: n/a (no Fortify URL referenced)"
+elif [ "$(jq -r '.fortifyFinding.gateOutcome.blocking' "$STATE_FILE")" = "true" ]; then
+  reason=$(jq -r '.fortifyFinding.gateOutcome.reason' "$STATE_FILE")
+  critical=$(jq -r '.fortifyFinding.severityCounts.Critical' "$STATE_FILE")
+  echo "→ fortify gate: BLOCKED ($reason, critical=$critical)"
+  # Treat as a deterministic gate failure  -  fix the critical findings before AI review.
+  exit 1
+else
+  high=$(jq -r '.fortifyFinding.severityCounts.High // 0' "$STATE_FILE")
+  echo "→ fortify gate: pass (high=$high warnings carry into the channel summary)"
+fi
+```
+
+Gate semantics:
+
+| `gateOutcome.reason` | Phase 3 action |
+|---|---|
+| `critical-findings` | **Blocking**  -  Phase 2 re-dispatches with the finding list; pipeline does not advance until Critical count is 0. |
+| `high-findings-warning` | Pass-with-warning  -  High findings appear in the channels summary (`## Security Scan (Fortify)` section in PR + Jira); they don't block the merge. |
+| `clean` | Pass silently  -  section omitted from the channels summary. |
+
+When `state.fortifyFinding.status === "skipped"` (token missing, VPN unreachable, or host mismatch) the gate logs `→ fortify gate: skipped (<reason>)` and never blocks  -  the user already saw the structured Save Flow signal at Phase 0 and chose to proceed.