buildanything 1.8.0 → 2.1.1

package/commands/build.md

@@ -1,5 +1,5 @@
 ---
-description: "Full product build pipeline — orchestrates specialist agents through brainstorming, research, architecture, implementation, testing, hardening, and shipping"
+description: "Full product build pipeline — orchestrates specialist agents through brainstorming, research, architecture, design, implementation, audit, launch review, and ship"
 argument-hint: "Describe what to build, or path to a design doc. --autonomous for unattended mode. --resume to continue a previous build."
 ---
 
@@ -13,45 +13,134 @@ Every step below tells you to call the Agent tool. DO IT. Do not role-play as th
 For implementation agents, set mode: "bypassPermissions".
 For parallel work, put multiple Agent tool calls in ONE message.
 
-Exception: Brainstorming (Phase 1, Step 1.1) is a direct conversation with the user — you ask questions and process answers yourself. This is the ONE phase where you work directly, not through agents.
+Exception: Brainstorming in Phase 1 Step 1.0 and Step 1.3 uses an INTERNAL Brainstorm Facilitator role — the orchestrator relays between the facilitator sub-agent and the user, never role-plays the agent itself.
 </HARD-GATE>
 
+<HARD-GATE>
+SUBAGENT_TYPE REQUIRED.
+
+Every Agent tool call MUST include a `subagent_type` field unless the dispatch is explicitly marked INTERNAL (inline role-string). INTERNAL dispatches are orchestrator helpers: Brainstorm Facilitator, Research Synthesizer, Design Doc Writer, Prereq Collector, Task DAG Validator, Refs Indexer, Briefing Officer, PM chapter, LRR Aggregator, Completion Report, Verify scaffolding dispatcher.
+
+Missing `subagent_type` on a non-INTERNAL dispatch is a HARD-GATE violation. The orchestrator rejects dispatches that don't name a specific agent. If you catch yourself typing `description: "..."` without a `subagent_type:` line alongside it, STOP and look up the right agent from the per-phase dispatch tables further down in this file.
+</HARD-GATE>
+
+<HARD-GATE>
+ARTIFACT WRITER-OWNER RULE.
+
+Every shared artifact has ONE concurrent writer at any instant. The writer-owner table below defines which phase writes which file. Before any file write, the orchestrator verifies the current phase is the rightful writer. Non-owning phase writes are a HARD-GATE violation. For parallel-batch phases (e.g., Phase 4), intra-phase dispatches MUST NOT race on the same file — writes either target disjoint per-dispatch filenames OR route through an orchestrator-scribe handler (see `decisions.jsonl` handling below).
+
+Live downstream docs (read across Phase 3+):
+  - `CLAUDE.md`              — P1 writer (then auto-loaded into every subagent)
+  - `docs/plans/design-doc.md` (PRD)    — P1 writer
+  - `docs/plans/product-spec.md`        — P1 writer (Step 1.6), product-spec-writer writer
+  - `docs/plans/architecture.md`        — P2 writer
+  - `docs/plans/sprint-tasks.md`        — P2 writer
+  - `docs/plans/quality-targets.json`   — P2 writer
+  - `docs/plans/phase-2-contracts/*.md`  — P2 writer (per-architect post-debate contract files)
+  - `docs/plans/visual-dna-preview.md`  — P2 writer, design-brand-guardian writer, ios-swift-ui-design writer (directional DNA preview at Gate 2)
+  - `DESIGN.md`                         — P3 writers: design-brand-guardian (Pass 1 at Step 3.0, both modes); design-ui-designer (Pass 2 at Step 3.4, web); ios-swift-ui-design (Pass 2 at Step 3.2-ios, iOS). Replaces former visual-dna.md + visual-design-spec.md pair (web) and ios-design-board.md (iOS). Repo root.
+  - `docs/plans/component-manifest.md`  — P3 writer (web, HARD-GATE import source)
+  - `docs/plans/design-references.md`   — visual-research writer (web, Step 3.1)
+  - `docs/plans/design-references/**`   — visual-research writer (web, screenshots harvested by visual-research subagents)
+  - `docs/plans/dna-persona-check.md`   — design-ux-researcher writer (web, Step 3.2b)
+  - `docs/plans/ux-architecture.md`     — P3 writer (web)
+  - `docs/plans/ux-flow-validation.md`  — design-ux-researcher writer (web, Step 3.3b)
+  - `docs/plans/inclusive-visuals-audit.md` — P3 writer (web)
+  - `docs/plans/a11y-design-review.md`  — P3 writer, a11y-architect writer (web, Step 3.7)
+  - `docs/plans/page-specs/*.md`        — P3 writer, design-ux-architect writer (web, Step 3.3 — per-screen wireframes + layout specs)
+  - `docs/plans/refs.json`              — P2 writer, P3 writer (P3 extends after visual spec lands)
+  - `docs/plans/decisions.jsonl`        — orchestrator-scribe ONLY via `scribe_decision` MCP tool (subagents return `deviation_row` objects; the orchestrator forwards each row through the MCP, which owns ID allocation and atomic append)
+  - `docs/plans/learnings.jsonl`        — P5 writer, P7 writer
+  - `docs/plans/evidence/*.json`        — P5 writer (P4 contributes per-task, P6/P7 readers)
+  - `docs/plans/evidence/*.md`          — P5 writer, design-brand-guardian writer (brand-drift findings, fake-data-audit)
+  - `docs/plans/evidence/**/*.json`     — P4 writer, P5 writer, P6 writer (nested per-task/per-run evidence JSON)
+  - `docs/plans/evidence/**/*.md`       — P4 writer, P5 writer (nested per-task/per-run evidence markdown)
+  - `docs/plans/evidence/**/*.png`      — P3 writer, P4 writer, P5 writer (screenshots: Playwright, SwiftUI Preview, Maestro, design-reference)
+  - `docs/plans/evidence/**/*.{txt,har}` — P4 writer, P5 writer (smoke-test HAR captures, DOM snapshots)
+  - `docs/plans/evidence/lrr/*.json`    — code-reviewer writer, security-reviewer writer, engineering-sre writer, a11y-architect writer, design-brand-guardian writer, pr-test-analyzer writer (5 chapter verdicts + 1 sub-verdict)
+  - `docs/plans/evidence/lrr-aggregate.json` — phase-6-aggregator writer (Aggregator only)
+  - `docs/plans/evidence/lrr-incomplete.json` — phase-6-aggregator writer (file-completeness checkpoint)
+  - `docs/plans/evidence/lrr-routing.json`    — phase-6-aggregator writer (BLOCK routing via decided_by)
+  - `docs/plans/evidence/reality-check-manifest.json` — testing-reality-checker writer (evidence-sweep manifest)
+  - `docs/plans/.build-state.json`      — orchestrator writer (every phase boundary)
+  - `docs/plans/.build-state.md`        — auto-rendered-view writer (regenerated from .build-state.json on every update)
+  - `docs/plans/.task-outputs/[task-id].json` — P4 writer (per-task output)
+  - `docs/plans/build-log.md`           — every-phase writer (append on transition)
+  - `docs/plans/.active-learnings.md`   — P0 writer (top-3 cross-run learnings for Phase 4 implementer briefings)
+  - `docs/plans/ios-verify-report.md`   — P5 writer (iOS verify twin)
+  - `docs/plans/ios-ux-review-report.md` — P5 writer (iOS ux-review twin)
+
+Phase-internal scaffolding (lives in `docs/plans/phase1-scratch/` after Gate 1, never read by P3+):
+  - `idea-draft.md`, `feature-intel.md`, `tech-feasibility.md`, `ux-research.md`, `business-model.md`, `findings-digest.md`, `suggested-questions.md`, `user-decisions.md`, `prereqs.json`
+
+Phase 4 implementers never reference Phase 1 raw research files. They are SPENT after the Product Spec step (Step 1.6). The product spec is the LAST consumer of raw research. After Step 1.6, research insights survive in `product-spec.md`, `design-doc.md`, and `CLAUDE.md`.
+</HARD-GATE>
+
+> **Default-deny (Stage 2+):** Once Stage 2 of the SDK migration activates, any `Write|Edit` tool call targeting a path absent from this table will be denied by the `PreToolUse` hook with message `"path not in writer-owner table — please add to phase-graph.yaml or route through scribe MCP"`. This is a pre-announcement; actual hook wiring ships in Task 2.1.3.
+
+<HARD-GATE>
+CONTEXT HEADER — RENDER ONCE, HOIST AS STABLE PREFIX.
+
+Every phase uses a CONTEXT header prepended to dispatch prompts. The orchestrator MUST render this header ONCE at the start of each phase by reading `.build-state.json` (and `DESIGN.md` `## Overview > ### Brand DNA` for web, Phase 4+) and resolving all values into concrete strings. The rendered header is then reused verbatim for every dispatch in that phase.
+
+DO NOT paste `{read from .build-state.json}` placeholders into dispatch prompts. DO NOT re-read state files per dispatch. The values do not change within a phase.
+
+**Canonical template** (orchestrator resolves before first dispatch of each phase):
+```
+CONTEXT:
+  project_type: <resolved value>
+  phase: <current phase number>
+  dna: <resolved from DESIGN.md `## Overview > ### Brand DNA` (7 axis values only, ~100 tokens) — INCLUDE only if project_type=web AND phase >= 4>
+  ios_features: <resolved from .build-state.json — INCLUDE only if project_type=ios>
+
+TASK:
+```
+
+**Rendering procedure** (run once per phase boundary):
+1. Read `docs/plans/.build-state.json`. Extract `project_type`, `ios_features`.
+2. If `project_type=web` AND phase >= 4: read `DESIGN.md` and extract the DNA summary (first 5 lines or the `## Summary` section). Otherwise omit the `dna` field.
+3. If `project_type=ios`: include `ios_features`. Otherwise omit.
+4. Substitute all values into the template above. Store the result as `rendered_context_header`.
+5. For every dispatch in this phase, prepend `rendered_context_header` — do NOT re-read or re-interpolate.
+
+This keeps the prefix stable across parallel batches (enabling KV-cache reuse) and eliminates redundant state-file reads (~300K–1M tokens saved per build).
+</HARD-GATE>
+
+## SSOT Rule (machine-readable form is authoritative)
+
+For every HARD-GATE promoted to code in Stages 2–5, the machine-readable form (`phase-graph.yaml`, `decisions.schema.json`, `state-schema.md`) is AUTHORITATIVE at runtime. Prose in `commands/build.md` and `protocols/*.md` is a narrative view of the machine-readable form. Prose edits without corresponding machine-readable edits are build-breaking PRs enforced by `eval/lint_phase_graph.py` in CI.
+
 ### Orchestrator Discipline
 
 Your context window is precious. Protect it.
 
-**You are a DISPATCHER, not a DOER.** Your job is: read state → decide next step → compose agent prompt → dispatch → process result → decide next step.
+**You are a DISPATCHER, not a DOER.** Your job is: read state → decide next step → compose agent prompt → dispatch → process compact return → decide next step.
 
 **Two types of agents — handle their results differently:**
 
 | Agent Type | Examples | What you keep |
 |-----------|----------|---------------|
-| **Research/analysis** | Market research, tech feasibility, architecture design, audits, measurement | **Full output** — their response IS the deliverable. You need it to synthesize, compare, and make decisions. Save to `docs/plans/` when applicable. |
-| **Implementation** | Code writing, fixes, cleanup, verification, scaffolding | **Summary only** — their work product lives in the codebase. Keep: what was done, files changed, test results, pass/fail. Discard: code snippets, full build logs, lint output. |
-
-**After implementation agents return:**
-1. Extract: what was built, files changed, test pass/fail, any blockers
-2. Record in `docs/plans/.build-state.md` under the current phase
-3. The code is in the repo — you don't need it in your context
-
-**After research/analysis agents return:**
-1. Read and use the full output — this is your decision-making input
-2. Save the output to the appropriate file in `docs/plans/` (research brief, architecture doc, etc.)
-3. Once saved to disk, you can reference the file later instead of holding it all in context
+| **Research/analysis** | Architecture design, audits, measurement, chapter verdicts | **Compact return only** — save full output to `docs/plans/`, keep the filename + headline verdict in context. Phase 1 research goes through the Research Synthesizer — the orchestrator never reads raw research. |
+| **Implementation** | Code writing, fixes, cleanup, verification, scaffolding | **Summary only** — their work product lives in the codebase. Keep: what was done, files changed, test results, pass/fail. Discard: code snippets, full build logs. |
 
 **Never do these yourself:**
-- Read source code files to understand implementation details — spawn an Explore agent
+- Read source code files to understand implementation details — spawn an INTERNAL inline exploration agent (see Step 2.1)
 - Write or edit code — spawn an implementation agent
 - Debug failures — spawn a fix agent with the error message
+- Read raw Phase 1 research files — the Research Synthesizer (Step 1.2) reads them; you only read the digest
 
 If you catch yourself typing code or reading source files: STOP. You are wasting context. Spawn an agent.
 
-**Dispatch Counter:** Track agent dispatches in `docs/plans/.build-state.md` under `## Dispatch Counter`:
-- `dispatches_since_save: [N]`
-- `last_save: [Phase.Step]`
-Increment after each agent returns (parallel dispatch of 4 agents = +4). Reset to 0 after each compaction save.
+**Dispatch Counter:** Track agent dispatches in `docs/plans/.build-state.json` (source of truth) under the `dispatch_count` and `last_save_phase` fields:
+- `dispatch_count: [N]`
+- `last_save_phase: [Phase.Step]`
+Increment after each agent returns (parallel dispatch of 6 agents = +6). Reset to 0 after each compaction save. The rendered markdown view (`.build-state.md`) is regenerated from the JSON on every update — never edit the markdown directly.
+
+**Compaction checkpoint format:** At every phase boundary, check `dispatch_count` in `docs/plans/.build-state.json`. If >= 8: save ALL state (current phase, task statuses, metric loop scores, decisions) to `docs/plans/.build-state.json` and regenerate `.build-state.md` as the rendered view. Reset `dispatch_count` to 0. TodoWrite does NOT survive compaction — rebuild it from the JSON state file on resume. See `protocols/state-schema.md` for the full schema and rendering contract.
 
-**Compaction checkpoint format:** At every phase boundary, check `dispatches_since_save` in `docs/plans/.build-state.md`. If >= 8: save ALL state (current phase, task statuses, metric loop scores, decisions) to `docs/plans/.build-state.md`. Reset `dispatches_since_save` to 0. TodoWrite does NOT survive compaction — rebuild it from this state file on resume.
+Phase 4 context pressure: With 20+ tasks, compact returns accumulate ~30-40K tokens in the orchestrator's context. The compaction checkpoint (dispatch_count >= 8) is the primary relief valve. If Phase 4 has more than 15 tasks, force a compaction checkpoint after every wave transition regardless of dispatch_count.
+
+**Cumulative-cost banner at phase boundaries:** When announcing a phase transition (e.g. "Phase N complete — proceeding to Phase N+1"), prefix the message with `[Cost so far: $X.XX • Y tokens]`. Source the values from the last-appended entry in `docs/plans/build-log.md`'s token-accounting lines (fields `cumulative_usd=...` plus the sum of `input_tokens=...` + `output_tokens=...`), written by `src/orchestrator/hooks/token-accounting.ts` (see module for exact schema). If the build-log has no token-accounting entries yet, omit the prefix rather than guessing.
 
 Input: $ARGUMENTS
 
@@ -59,41 +148,52 @@ Input: $ARGUMENTS
 
 If the input contains `--autonomous` or `--auto`, this build runs **unattended**. The user will not be present to approve quality gates. In autonomous mode:
 - Quality gates auto-approve. Do NOT pause and wait for user input.
-- Brainstorming runs in autonomous mode (see protocol).
+- Brainstorming runs in autonomous mode (Brainstorm Facilitator synthesizes directly from build request + available context).
 - Metric loops that stall accept at >= 60% of target, skip below that.
-- Log every decision to `docs/plans/build-log.md` so the user can review later.
 
 If `--autonomous` is NOT present, all quality gates require user approval as described below.
 
 When combining `--resume` with `--autonomous`: the current invocation's flags take precedence over saved state. If you resume a previously interactive build with `--autonomous`, it continues in autonomous mode.
 
-### Metric Loop
+### Always-On Build Log
+
+`docs/plans/build-log.md` is written in **BOTH interactive and autonomous mode**. Every phase transition writes a one-line entry with the shape: `{timestamp, phase, step, action, outcome}`. Append to this file at EVERY phase boundary, EVERY LRR chapter dispatch, EVERY metric-loop iteration, and EVERY quality gate decision. In autonomous mode, ALSO log every auto-approval decision here so the user can review later.
 
-Every phase uses a **metric-driven iteration loop** to drive quality. Read the full protocol at `protocols/metric-loop.md`. Critical rules (survive compaction):
+### Metric Loop (callable service)
 
-1. YOU define a metric for this phase based on context (what you're building, what matters). The metric is NOT predefined.
-2. Spawn a **measurement agent** to score the artifact 0-100. Read its full output — it's analysis.
-3. Pick the ONE highest-impact issue. Spawn a separate **fix agent** with ONLY that issue + file paths.
+Every phase can invoke the **metric-driven iteration loop** as a service to drive quality. Read the full protocol at `protocols/metric-loop.md`. Called by Phase 3 (Design Critic loop), Phase 4 (per-task quality), Phase 5 (metric fix loop on failing audits), Phase 7 (documentation quality). Critical rules (survive compaction):
+
+1. YOU define a metric for this phase based on context. The metric is NOT predefined.
+2. Spawn a **measurement/critic agent** to score the artifact 0-100. Read its compact return.
+3. Pick the ONE highest-impact issue. Spawn a separate **fix/generator agent** with ONLY that issue + file paths.
 4. Re-measure. Repeat until: target met, stalled (2 consecutive delta <= 0), or max iterations.
-5. Track all scores in `docs/plans/.build-state.md` — this is your lifeline across compaction.
+5. Track all scores in `docs/plans/.build-state.json` — this is your lifeline across compaction.
 
 <HARD-GATE>
 METRIC LOOP NON-NEGOTIABLES:
-- Measurement agent and fix agent are SEPARATE Agent tool calls — never share context (author-bias elimination).
+- Measurement/critic agent and fix/generator agent are SEPARATE Agent tool calls — never share context (author-bias elimination).
 - Fix agent gets ONLY the top issue + file paths + acceptance criteria. NOT the full measurement findings.
 - One fix per iteration. Measure impact before fixing the next thing.
 - Each measurement is fresh — don't accumulate findings across iterations.
 </HARD-GATE>
 
-### Handoff Documents
+### Verify Protocol (callable service)
+
+The 7-check verification gate is called by Phase 2 (architecture check), Phase 4 (per task), Phase 5 (audit), and Phase 7 (pre-ship). Full protocol at `protocols/verify.md`. Phase-internal — dispatched as INTERNAL inline role-string "Verify scaffolding" with agent running 7 checks sequentially: Build → Type-Check → Lint → Test → Security → Diff Review → Artifacts.
+
+### Decision Log (callable service)
+
+`docs/plans/decisions.jsonl` — append-only, ORCHESTRATOR-SCRIBE ONLY via the `scribe_decision` MCP tool. Subagents return `deviation_row` objects in their structured result; the orchestrator forwards each row through `scribe_decision`, which allocates `D-{phase}-<seq>` IDs and atomically appends. The orchestrator MUST NOT Write or Edit this file directly. Row-producing phases: Phase 1 synthesis (3 rows), Phase 2 architecture synthesis (4 rows), Phase 4 implementers (only on deviation). Readers: Phase 0 resume handler, Phase 5 Reality Checker, Phase 6 LRR Aggregator (the ⭐⭐ backward-routing read). Schema at `protocols/decision-log.md`. Dispatch flow: see Phase 4 "Orchestrator-scribe dispatch" section.
+
+### Learnings (callable service)
 
-When spawning agents in sequence (e.g., architect → implementer → reviewer), pass **scoped handoffs** — not the full architecture dump. Each agent receives only what it needs:
+`docs/plans/learnings.jsonl` — append-only cross-run learnings store. Writers: Phase 5 reality sweep, Phase 7. Readers: Phase 0 Learnings Loader (Step 0.1d) and Phase 5 reality sweep.
 
-1. **Relevant architecture section** — the specific part of architecture.md that applies to this agent's task
-2. **Previous agent's output** — what the upstream agent produced (if any)
-3. **Acceptance criteria** — what "done" looks like for THIS agent
+### Refs-Not-Pastes Rule
 
-For implementation agents (Phase 5+): Do NOT paste the entire Design Document or Architecture Document. Extract the relevant sections only. For research and architecture agents (Phases 1-2): pass the full document — these agents need complete context to do their analysis.
+For Phase 3+ agents, the orchestrator passes REFS to live downstream docs (`design-doc.md`, `architecture.md`, `DESIGN.md`, `sprint-tasks.md`, `quality-targets.json`, `decisions.jsonl`) — NOT pasted content. The orchestrator reads `docs/plans/refs.json` (produced by the Phase 2 Refs Indexer), resolves the task topic against the flat anchor index, and passes a short ref list to the agent. The agent uses the Read tool to pull refs it needs. This keeps orchestrator context lean and lets the agent widen its view on demand. Phase 1-2 agents still receive full documents because the architecture anchors don't exist yet.
+
+**refs.json mutation invalidates sprint-context hash (Stage 6 / task 6.3.2).** Any orchestrator update to `docs/plans/refs.json` (Phase 2 Refs Indexer initial write, Phase 3 extension after `DESIGN.md` lands, or any subsequent correction) MUST be IMMEDIATELY followed by a `state_save` call that sets `.build-state.json.current_sprint_context_hash = null`. This invalidates the cached Phase 4 sprint-scoped shared-context block so the next subagent dispatch re-renders with fresh references. See `src/orchestrator/phase4-shared-context.ts#shouldInvalidate` for how the hash is consulted at render time. Skipping this invalidation causes Phase 4 implementers to read stale anchor indices — a silent correctness failure.
 
 ### Complexity Routing (Advisory)
 
@@ -101,39 +201,70 @@ Tag agent prompts with `[COMPLEXITY: S/M/L]` based on task size from `docs/plans
 
 ### Mode-Specific Tool Stacks
 
-Mode-specific tool stacks, per-phase branches, and persona rules are in separate files — the orchestrator loads only ONE based on `project_type` (see Phase 0 Step 0.1b below):
+Mode-specific tool stacks, per-phase branches, and persona rules live in separate files. Load ONE based on `project_type`:
 - iOS: `protocols/ios-phase-branches.md` (includes iOS Mode Tool Stack)
 - Web: `protocols/web-phase-branches.md` (web defaults)
 
+### Backward Edges — Routing Fix
+
+When a later phase finds a problem whose root cause lives earlier, control flows BACKWARD to the authoring phase. The orchestrator codifies these edges so problems are fixed where they were introduced, not patched locally.
+
+```
+PROBLEM FOUND AT                                              ROUTES BACK TO
+──────────────────────────────────────────────────────────────────────────────────
+Gate 1 (human says "no")                                  →   Phase 1 Step 1.0 with feedback
+Gate 2 (human says "no")                                  →   Phase 2 with feedback
+phase-3.step-3.2b-DNA-persona-mismatch                    →   phase-3.step-3.0
+Phase 5 Audit (code issue)                                →   Phase 4 target task
+Phase 5 Audit (design issue)                              →   Phase 3 target step
+Phase 5 Audit (spec issue)                                →   phase-2
+phase-5-dogfood-classified                                →   target_phase-per-classified-findings.json
+phase-5-dogfood-feedback-synthesizer                      →   phase-4.target-task
+Phase 6 LRR BLOCK (⭐⭐)                                   →   authoring-phase (per decisions.jsonl.decided_by)
+LRR-BLOCK-decided_by==architect                           →   phase-2
+LRR-BLOCK-decided_by==design-brand-guardian-or-phase-3-writer →   phase-3
+Phase 6 LRR NEEDS_WORK (code)                             →   Phase 4 target feature (via BO re-planning)
+LRR-NEEDS_WORK-code-level                                 →   phase-4.target-task
+phase-6-LRR-NEEDS_WORK-structural                        →   phase-2-or-phase-3
+```
+
+The ⭐⭐ star rule: when the LRR Aggregator receives a BLOCK verdict, it reads the `related_decision_id` on the blocker, looks up that row in `decisions.jsonl`, finds which phase authored the decision (the `decided_by` field), and re-opens that phase with the finding as input. Infrastructure already exists (decision IDs, author tracking) — wired here.
+
+**Re-entry halt rule (Stage 4 A7).** Before dispatching any backward routing (LRR BLOCK to Phase N re-open, Reality Checker BLOCK to Phase M re-entry, Gate "no" to Phase 1/2 re-entry, etc.), check `.build-state.json.backward_routing_count` AND the per-target-phase variant `.build-state.json.backward_routing_count_by_target_phase[<N>]`. If the new (post-increment) value of EITHER counter for the target phase would exceed `max_cycles` (currently 2, from `phase-graph.yaml:routing.max_cycles`) — i.e., on the attempted third backward iteration — the orchestrator MUST halt and escalate to the user instead of dispatching. The Stage 4 `cycle_counter_check` MCP is the authoritative enforcer at runtime — it increments atomically and returns `escalate_to_user` once the new value exceeds `max_cycles`. This prose documents the behavior for the markdown-mode rollback path and for human readers.
+
+**Phase-entry `in_flight_backward_edge` clear (Stage 4 A3 / task 4.3.3).** On the FIRST `state_save` after any phase entry — whether forward progression or backward-edge re-entry — the orchestrator MUST explicitly set `.build-state.json.in_flight_backward_edge = null`. This is the "successful landing" signal that closes the atomic crash-seam opened by `cycle_counter_check` (which writes `in_flight_backward_edge` in the same atomic state_save that increments the counter). If the runtime crashes between edge dispatch and landing, `--resume` in `bin/buildanything-runtime.ts` observes a stale `in_flight_backward_edge` (age > 60s) and decrements the counter (see task 4.3.4). See `src/orchestrator/mcp/cycle-counter.ts#clearInFlightEdge` for the runtime primitive.
+
 ---
 
-## Phase 0: Context & Pre-Flight
+## Phase 0: Pre-flight (state read only)
+
+Phase 0 is thin. No agent dispatch. No human input. Instant. The orchestrator reads state files and applies universal checks.
 
 **Resuming?** If the input contains `--resume` OR if context was just compacted (SessionStart hook fired with active state):
-1. Read `docs/plans/.build-state.md` — verify it exists and has a Resume Point section.
-   If `docs/plans/.build-state.md` does not exist or has no Resume Point, warn the user: 'No previous build state found. Starting fresh.' Then proceed to Step 0.1 as a new build.
+1. Read `docs/plans/.build-state.json` (source of truth) — verify it exists and has a `resume_point` field. Fall back to reading `docs/plans/.build-state.md` (rendered view) if the JSON file is missing but the markdown exists (graceful migration path from pre-W1-2 builds).
+   If neither exists, OR neither has a Resume Point, warn the user: 'No previous build state found. Starting fresh.' Then proceed to Step 0.1 as a new build.
 2. Re-read this file and all protocol files in `protocols/`.
-3. Re-read `docs/plans/sprint-tasks.md`, `docs/plans/architecture.md`, and `CLAUDE.md`.
-4. Rebuild TodoWrite from the state file (TodoWrite does NOT survive compaction or session breaks).
-5. Reset `dispatches_since_save` to 0 (fresh context window).
-6. Resume from the saved phase and step. Skip Phase 0.
+3. Re-read live downstream docs: `docs/plans/sprint-tasks.md`, `docs/plans/architecture.md`, `docs/plans/design-doc.md`, `DESIGN.md` (if exists), `CLAUDE.md`.
+4. Read `docs/plans/decisions.jsonl` if it exists (top 5 most recent rows, filtered to the current phase and upstream phases). Pass short row fields + `ref` anchors into Phase 0 rehydration context — not the full row prose. See `protocols/decision-log.md`.
+5. Rebuild TodoWrite from the state file (TodoWrite does NOT survive compaction or session breaks).
+6. Reset `dispatches_since_save` to 0 (fresh context window).
+7. Resume from the saved phase and step. Skip Phase 0.
 
 ### Step 0.1 — Read the Room
 
-Before doing anything, scan for existing context:
+Scan for existing context:
 
 - Check if the input is a file path (e.g., `docs/plans/brainstorm.md`). If so, read it.
 - Check if `docs/plans/` or `docs/briefs/` exist with prior brainstorming, design docs, decision briefs, or research. Read them.
 - Check if there's existing code in the project. If so, this is an enhancement, not greenfield.
 - Check the conversation history — has the user been discussing this idea already?
-- Check if `docs/plans/learnings.md` exists from a previous build. If so, read it. Apply relevant PATTERNS to agent prompt design, avoid listed PITFALLs, use HEURISTICS when applicable.
 
 **Classify what you found:**
 
 | Context Level | What You Have | What Happens |
 |---|---|---|
 | **Full design** | Design doc with decisions, scope, tech stack, data models | Skip Phase 1. Feed design into Phase 2. |
-| **Decision brief** | An idea-sweep brief with verdicts and MVP definition | Phase 1 skips research (Step 1.2). Brainstorming refines the brief into a design. |
+| **Decision brief** | An idea-sweep brief with verdicts and product definition | Phase 1 skips Step 1.1 research (already done). Brainstorming refines the brief into a design. |
 | **Partial context** | Some notes, conversation, rough sketch | Phase 1 runs fully. Feed context into brainstorming + research. |
 | **Raw idea** | One-line build request, no prior work | Phase 1 runs fully from scratch. |
 
@@ -141,430 +272,1028 @@ Before doing anything, scan for existing context:
 
 Scan the build request AND any context from Step 0.1 for iOS signals. Keywords: **iOS, iPhone, iPad, SwiftUI, Swift, App Store, TestFlight, Xcode, Apple, Liquid Glass, watchOS, visionOS, SwiftData, HIG**.
 
-**Classification logic:**
+To avoid false positives (e.g., a web app mentioning "Apple Pay" or "Sign in with Apple"), require at least 2 iOS keywords OR 1 keyword + existing Swift/Xcode files before triggering the iOS confirmation prompt.
 
 | Signal | Action |
 |---|---|
 | iOS keywords present in prompt | Confirm with user: "This looks like an iOS app — confirm? [y/n]" |
-| User confirms OR says iOS during brainstorming | Set `project_type: ios` in `docs/plans/.build-state.md` |
+| User confirms OR says iOS during brainstorming | Set `project_type: ios` in `docs/plans/.build-state.json` (regenerate markdown view) |
 | `.xcodeproj` / `Package.swift` / `*.swift` files in existing codebase | Set `project_type: ios` automatically |
-| No iOS signals, no Swift files | Default `project_type: web` (existing behavior) |
+| No iOS signals, no Swift files | Default `project_type: web` |
 
 **Autonomous mode:** skip the confirmation prompt. If iOS keywords are present, set `project_type: ios` and log the inference to `docs/plans/build-log.md`.
 
 **Conditional branch-file load:**
-- If `project_type=ios`: load `protocols/ios-phase-branches.md` AND `protocols/ios-context.md` into session context. Reference `protocols/ios-frameworks-map.md` by path only (do NOT load — agents Read it on-demand).
-- If `project_type=web`: load `protocols/web-phase-branches.md` into session context.
-- Load only ONE branch file. The other mode's content is irrelevant to this build.
-
-Record the classification in `docs/plans/.build-state.md` as a top-level field: `project_type: ios` or `project_type: web`. This field survives compaction and gates every branching block below.
+- `project_type=ios`: load `protocols/ios-phase-branches.md` AND `protocols/ios-context.md`. Reference `protocols/ios-frameworks-map.md` by path only.
+- `project_type=web`: load `protocols/web-phase-branches.md`.
+- Load only ONE branch file.
 
-**Mode-specific additions to Phase 0:** See `protocols/ios-phase-branches.md` §Phase 0 additions (iOS only). No web-specific Phase 0 additions.
+Record the classification in `docs/plans/.build-state.json` as the top-level `project_type` field. Regenerate `.build-state.md` after the write. This field survives compaction and gates every branching block below.
 
-### Step 0.2 — Human Prerequisites Checklist
+**Mode-specific additions to Phase 0:** See `protocols/ios-phase-branches.md` §Phase 0 additions (iOS only).
 
-Identify everything that requires HUMAN action before going heads-down:
+### Step 0.1d — Learnings Loader (PITFALL replay)
 
-- **API keys & secrets** — External services the project integrates with. List each key needed.
-- **Database setup** — Supabase, Postgres, etc. User needs to create it and provide credentials.
-- **Repository** — Git repo on GitHub? Public or private?
-- **Deployment** — Vercel, Railway, Fly.io? User needs to connect.
-- **MCP servers** — Playwright for visual testing, database access, etc.
-- **Local tooling** — Docker, specific runtimes, etc.
+Read `docs/plans/learnings.jsonl` (cross-run learnings store). If the project-local file does not exist, fall back to `~/.claude/buildanything/learnings.jsonl`. If neither exists, proceed with an empty active-learnings file and skip the rest of this step.
 
-Present the checklist:
-
-```
-BEFORE I GO HEADS-DOWN, please set up:
+If a learnings file exists:
+1. Parse each line as a JSON row with the schema written at Phase 5 reality sweep: `{run_id, timestamp, project_type, phase_where_learning_surfaced, metric, top_issue, fix_applied, score_delta, pattern_type}`.
+2. Filter entries where `project_type` matches the current build's classification.
+3. Rank the filtered entries by composite score: prefer entries matching expected `pattern_type` (PITFALL > PATTERN > HEURISTIC), then by `phase_where_learning_surfaced` (earlier phases first), then by `score_delta` magnitude.
+4. Select the top 3 most relevant entries.
+5. Write them to `docs/plans/.active-learnings.md` as a short markdown section downstream agents inject into their prompts. Format:
 
-[ ] [Service] API key → add as [KEY_NAME] to .env
-[ ] [Database] → add connection URL to .env
-[ ] GitHub repo → share the URL
-[ ] [Deployment service] connected (optional)
+```markdown
+## Prior Learnings (top 3 relevant)
 
-Once done, say "ready" and I'll start building.
+- **PITFALL (phase 4.x, iOS):** [top_issue] — fix: [fix_applied]
+- **PATTERN (phase 5.x, web):** [top_issue] — fix: [fix_applied]
+- **HEURISTIC (phase 4.x, iOS):** [top_issue] — fix: [fix_applied]
 ```
 
-<HARD-GATE>
-Interactive mode: DO NOT proceed until the user confirms prerequisites (or says to skip).
-Autonomous mode: Log checklist to `docs/plans/build-log.md`. Create `.env.example` with required keys. Proceed — log missing keys as blockers if hit during build.
-</HARD-GATE>
+Phase 4 implementer dispatch reads `.active-learnings.md` and injects its contents into every implementer prompt under a `## Prior Learnings` section. This is how learnings from build N flow into build N+1.
 
-### Step 0.3 — Initialize
+### Step 0.2 — Initialize
 
 0. Create `docs/plans/` directory if it doesn't exist (greenfield projects won't have it).
 1. Create a TodoWrite checklist with Phases 0-7.
-2. Create `docs/plans/.build-state.md` as a single write with ALL of the following: phase and step (`Phase: 0 — Starting`), input (`[build request]`), context level (`[classification]`), prerequisites (`[status]`), dispatch counter (`dispatches_since_save: 0, last_save: Phase 0`), and a `## Resume Point` section with: phase, step, autonomous mode flag, completed tasks (none), git branch name.
+2. Write `docs/plans/.build-state.json` per the schema in `protocols/state-schema.md`. Required top-level fields: `project_type`, `phase`, `step`, `input`, `context_level`, `prerequisites`, `dispatch_count`, `last_save_phase`, `autonomous`, `session_id`, `session_started`, `completed_tasks[]`, `metric_loop_scores[]`, `decisions_next_id` (object keyed by phase number — see Phase 4 orchestrator-scribe handler), `resume_point { phase, step, completed_tasks, git_branch }`, `backward_routing_count_by_target_phase` (object), `feature_delegation_plan_path`, `current_wave`, `completed_features[]`, `feature_acceptance{}`, `feature_briefs{}`. See `protocols/state-schema.md` for the complete and authoritative field list. This inline list is a summary. Then regenerate `docs/plans/.build-state.md` from the JSON as a **read-only rendered view**.
 3. Go to Phase 1 (or Phase 2 if context level is "Full design").
 
+**NO prereq collection in Phase 0.** Stack isn't decided yet. Prereqs move to Step 1.5, after Gate 1. Asking for creds before the stack is picked means asking for wrong creds or re-asking on rejection.
+
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
+
 ---
 
 ## Phase -1: iOS Bootstrap (iOS-only, greenfield only)
 
-**If `project_type=ios` AND no `.xcodeproj` exists:** follow `protocols/ios-phase-branches.md` §Phase -1 — iOS Bootstrap. Otherwise skip entirely (including all of web mode).
+**If `project_type=ios` AND no `.xcodeproj` exists:** follow `protocols/ios-phase-branches.md` §Phase -1 — iOS Bootstrap. Otherwise skip entirely.
+
+iOS structural changes are out of scope for this orchestrator migration.
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
 
 ---
 
-## Phase 1: Brainstorm & Research
+## Phase 1: Discover — BRAINSTORM ↔ RESEARCH loop
 
-**Goal**: Turn the raw idea into a validated Design Document grounded in research. This ensures Phase 2 architects receive a design, not a guess.
+**Goal**: Turn the raw idea into a validated Design Document (the PRD) grounded in research. This ensures Phase 2 architects receive a PRD, not a guess.
 
 **Skip if** Step 0.1 classified context as "Full design" — go straight to Phase 2.
 
+**Orchestrator discipline in Phase 1**: Dispatch → wait → read compact return → dispatch next. No synthesis. No reasoning. No raw artifact reads. Keep it thin. The Research Synthesizer (Step 1.2) is the only agent that reads raw research files.
+
 **Mode-specific branch:**
-- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 1 (iOS skill bundle, ios-swift-architect, App Store/TestFlight/iOS 26 research angles)
-- If `project_type=web`: no additional branch instructions — proceed with the steps below.
+- `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 1 (iOS skill bundle, ios-swift-architect, App Store/TestFlight/iOS 26 research angles).
+- `project_type=web`: no additional branch instructions.
+
+### Step 1.0 — INITIAL BRAINSTORM
 
-### Step 1.1 — Brainstorming
+Dispatch the Brainstorm Facilitator as an INTERNAL inline role-string — NO `subagent_type`. The facilitator drives a conversation to capture the raw idea: what it is, who it's for, what problem it solves, hard constraints.
 
-Follow the Brainstorm Protocol (`protocols/brainstorm.md`).
+Call the Agent tool — description: "Initial brainstorm" — INTERNAL inline role-string — prompt: "You are the Brainstorm Facilitator (round 1). Your job is to drive a conversation with the user to capture the raw idea. Ask questions one at a time in plain language. Topics to cover: WHAT is being built (product/feature), WHO it's for (persona), WHAT problem it solves, HARD CONSTRAINTS (budget, timeline, platform, integrations). Keep it to 4-8 questions. Write the raw idea to `docs/plans/phase1-scratch/idea-draft.md` with a header and a section per topic. Orchestrator relays your questions to the user and relays the user's answers back to you."
 
-In interactive mode: this is a conversation. Ask questions one at a time, propose approaches with trade-offs, let the user decide. Output: Design Document saved to `docs/plans/`.
+**Autonomous mode:** facilitator synthesizes directly from build request + available context without asking questions. Logs rationale to `docs/plans/build-log.md`.
 
-In autonomous mode: synthesize a design document directly using the build request and available context. Pick pragmatic defaults. Log rationale to `docs/plans/build-log.md`.
+**Returns:** `docs/plans/phase1-scratch/idea-draft.md`
 
-### Step 1.2 — Parallel Research (5 agents, ONE message)
+### Step 1.1 — RESEARCH (TEAM of 4 parallel agents, ONE message)
 
 Skip if context level is "Decision brief" (research already done).
 
-Call the Agent tool 5 times in a single message. Pass each agent the build request AND the Design Document draft.
+Call the Agent tool 4 times in a single message. Each gets the build request + `docs/plans/phase1-scratch/idea-draft.md`. Each writes its own output file. Raw files are NOT read by the orchestrator in Step 1.2 — a separate Research Synthesizer reads them. They ARE routed by domain to Phase 2 architects (hybrid routing — see Phase 2 Step 2.2).
 
-1. Description: "Market research" — Prompt: "Research market size (TAM/SAM/SOM), competitive landscape (5-10 players), timing, and market structure for: [build request]. Design context: [paste design doc]. Report with a Market Verdict: GREEN/AMBER/RED."
+**CONTEXT header:** Render `rendered_context_header` for phase 1 per the canonical template (see CONTEXT HEADER HARD-GATE above). Prepend to every Phase 1 research prompt below.
 
-2. Description: "Tech feasibility" — Prompt: "Evaluate hard technical problems (Solved/Hard/Unsolved), build-vs-buy decisions, MVP scope, and stack validation for: [build request]. Design context: [paste design doc]. Verify APIs and libraries from the design exist and are maintained. Report with a Technical Verdict."
+1. Description: "Feature intel" — subagent_type: `feature-intel` — Prompt: "[CONTEXT header above] Extract competitor feature matrix for: [build request]. Idea draft: read docs/plans/phase1-scratch/idea-draft.md with your Read tool. Walk 5-10 rivals. Return must-haves (features present in >=80% of rivals — table stakes) + stand-outs (features unique to individual rivals — differentiation opportunities), sorted by competitor. Save to `docs/plans/phase1-scratch/feature-intel.md`."
 
-3. Description: "User research" — Prompt: "Analyze target persona, jobs-to-be-done, current alternatives, and behavioral barriers to adoption for: [build request]. Design context: [paste design doc]. Report with a User Verdict."
+2. Description: "Tech feasibility" — subagent_type: `tech-feasibility` — Prompt: "[CONTEXT header above] Evaluate hard technical problems (Solved/Hard/Unsolved), build-vs-buy decisions, stack validation for: [build request]. Idea draft: read docs/plans/phase1-scratch/idea-draft.md with your Read tool. Verify APIs and libraries from the draft exist and are maintained. Save to `docs/plans/phase1-scratch/tech-feasibility.md`. Report with a Technical Verdict."
 
-4. Description: "Business model" — Prompt: "Evaluate revenue models, unit economics, growth loops, and first-1000-users strategy for: [build request]. Design context: [paste design doc]. Report with a Business Verdict."
+3. Description: "UX research" — subagent_type: `design-ux-researcher` — Prompt: "[CONTEXT header above] Analyze target persona, jobs-to-be-done, current alternatives, and behavioral barriers for: [build request]. Idea draft: read docs/plans/phase1-scratch/idea-draft.md with your Read tool. Save to `docs/plans/phase1-scratch/ux-research.md`. Report with a User Verdict."
 
-5. Description: "Risk analysis" — Prompt: "Adversarial review: regulatory risk, security concerns, dependency risks, competitive response, top 3 failure modes for: [build request]. Design context: [paste design doc]. Report with a Risk Verdict."
+4. Description: "Business model" — subagent_type: `business-model` — Prompt: "[CONTEXT header above] Light-touch revenue/channels/unit-economics analysis for: [build request]. Idea draft: read docs/plans/phase1-scratch/idea-draft.md with your Read tool. Surface product-impact conclusions only — which features the business model requires, which channels gate the feature set. Do not write full financial modeling. Save to `docs/plans/phase1-scratch/business-model.md`."
 
-After all 5 return, synthesize a **Research Brief** with a verdict table. Save to `docs/plans/research-brief.md`.
+### Step 1.2 — RESEARCH DIGEST (context protection)
 
-### Step 1.3 — Design Refinement
+Dispatch the Research Synthesizer as an INTERNAL inline role-string — NO `subagent_type`. The synthesizer reads all 4 raw research files IN ITS OWN context, synthesizes, and returns a compact digest + dynamic questions. The orchestrator never loads the raw files. Saves ~3-5K tokens of orchestrator context per build.
 
-Read the Design Document and Research Brief together. Check for contradictions:
+Call the Agent tool — description: "Research digest" — INTERNAL inline role-string — prompt: "You are the Research Synthesizer. Read these 4 raw research files with your own Read tool:
+  - `docs/plans/phase1-scratch/feature-intel.md`
+  - `docs/plans/phase1-scratch/tech-feasibility.md`
+  - `docs/plans/phase1-scratch/ux-research.md`
+  - `docs/plans/phase1-scratch/business-model.md`
 
-- Tech-feasibility flagged "Unsolved" hard problem → simplify or flag as risk
-- Risk-analysis returned RED → add mitigation or descope
-- User-research says "no validated demand" → flag as pivot point
-- Business-model says "no moat" → note for speed-to-market priority
+Synthesize a compact findings digest (~500 words, no padding) covering:
+  - Feature landscape summary (must-haves, stand-outs, gaps)
+  - Technical verdict with hard-problem callouts
+  - Persona + JTBD highlights
+  - Business-model implications for product scope
 
-Update the Design Document with corrections. Save final version.
+Then generate a DYNAMIC list of 4-8 brainstorm questions tuned to what actually surfaced — not a fixed script. Example: if tech-feasibility found an unsolved problem, surface a scope question. If UX research says persona is time-poor, surface a flow-simplification question.
 
-### Step 1.4 — Write CLAUDE.md
+Write:
+  1. `docs/plans/phase1-scratch/findings-digest.md` (~500 words)
+  2. `docs/plans/phase1-scratch/suggested-questions.md` (4-8 dynamic questions)
 
-Create (or overwrite) the project's `CLAUDE.md`. This is the product brain — every agent spawned during the build reads it automatically. Write it from the Design Document and Research Brief. It must give any agent enough context to make smart product, UX, and technical decisions without needing the full design doc.
+Return a compact summary to the orchestrator. The orchestrator does NOT read the raw files."
 
-<HARD-GATE>
-CLAUDE.md must be under 200 lines. It is not a wiki, not a conventions doc, not a dump of everything you know. It is the minimum context an agent needs to make correct decisions about this specific product.
-</HARD-GATE>
+### Step 1.3 — INFORMED BRAINSTORM
 
-Structure:
+Dispatch the Brainstorm Facilitator (round 2) as an INTERNAL inline role-string. This is a dynamic conversation — questions adapt to what research surfaced, not a fixed script. User makes product decisions WITH research in hand.
+
+Call the Agent tool — description: "Informed brainstorm" — INTERNAL inline role-string — prompt: "You are the Brainstorm Facilitator (round 2). Read `docs/plans/phase1-scratch/findings-digest.md` + `docs/plans/phase1-scratch/suggested-questions.md` via the Read tool. Drive a DYNAMIC conversation with the user using those questions — adapt based on answers, don't run a fixed script. Topics to cover (wording is dynamic, tuned to what surfaced):
+  - Which must-have features to include vs. cut
+  - Which stand-out features for differentiation
+  - Any persona / JTBD adjustments
+  - Does business model suggest specific features (e.g., freemium needs a free tier UI)
+
+Orchestrator relays your questions to the user and relays answers back. Write decisions to `docs/plans/phase1-scratch/user-decisions.md`."
+
+**Autonomous mode:** facilitator picks pragmatic defaults from the digest without asking questions. Logs rationale to `docs/plans/build-log.md`.
+
+### Step 1.4 — DESIGN DOC + CLAUDE.md
+
+Dispatch the Design Doc Writer as an INTERNAL inline role-string. Writes TWO outputs. The design doc is explicitly named **THE PRD** — the authoritative product document read by every Phase 2-7 agent via `refs.json` anchors, no full pastes.
+
+Call the Agent tool — description: "Design doc and CLAUDE.md" — INTERNAL inline role-string — prompt: "You are the Design Doc Writer. Read with your own Read tool:
+  - `docs/plans/phase1-scratch/idea-draft.md`
+  - `docs/plans/phase1-scratch/findings-digest.md`
+  - `docs/plans/phase1-scratch/user-decisions.md`
+
+Write TWO outputs.
+
+OUTPUT 1 — `docs/plans/design-doc.md` — **THE PRD** (authoritative product document). Header MUST begin with `# [Product Name] — PRD`. Structure:
+  - Product — what it is, core value prop, success criteria
+  - User — persona, JTBD, hard constraints
+  - Scope — Features in scope (must-haves + chosen stand-outs), explicit Out-of-Scope boundary
+  - Tech Stack — chosen stack with 1-line rationale
+  - Data Model — shape of core entities
+  - Decisions — links to `decisions.jsonl` rows
+
+This doc is read by all Phase 2-7 agents via `refs.json` anchors. Section headers should be stable (don't rename them later) so anchors survive.
+
+OUTPUT 2 — `CLAUDE.md` (project root, NOT `docs/plans/`). <200-line product brain, auto-loaded into every spawned subagent context by Claude Code. The orchestrator NEVER pastes it. Structure:
 
 ```
 ## Product
 [1-3 sentences: what this is, core value prop, what success looks like]
 
 ## User
-[Primary persona: who they are, what they care about, pain points,
-technical sophistication. This drives every UX decision.]
+[Primary persona: who they are, what they care about, pain points, technical sophistication]
 
 ## Tech Stack
-[Stack choices with 1-line rationale for each. Framework, DB, auth,
-key libraries, deployment target.]
+[Stack choices with 1-line rationale for each]
 
 ## Scope
-[What's in MVP vs. deferred. Hard boundaries. This prevents agents
-from building features that aren't scoped.]
+[What's in scope vs. deferred. Hard boundaries.]
 
 ## Rules
-[Project-specific hard rules derived from the product and user context.
-Examples: "All data must be real-time — no simulated/fake data",
-"User must be able to pause/stop any automated process at any time",
-"Every interactive element must have visible feedback within 200ms".
-Only include rules this specific project needs — not generic best practices.]
+[Project-specific hard rules derived from the product and user context.]
 ```
 
-Keep it product-focused. An implementation agent reading this should understand WHO the user is and WHAT matters enough to make the right call when the handoff prompt doesn't cover an edge case.
+<HARD-GATE>
+CLAUDE.md must be under 200 lines. Not a wiki, not a conventions doc, not a dump of everything. Minimum context an agent needs to make correct decisions about this specific product.
+</HARD-GATE>
+
+Return 3 decision rows in your structured result under a `phase_1_decisions` field — one each for tech stack, data model, and scope boundary. Each row shape: `{phase: 1, author: \"architect\", type: \"tech-stack\" | \"data-model\" | \"scope-boundary\", summary, rationale, related_files: [\"docs/plans/design-doc.md\"]}`. The orchestrator forwards each row through the `scribe_decision` MCP tool (see Phase 4 "Orchestrator-scribe dispatch"). DO NOT write `decisions.jsonl` directly."
+
+**Writes:** `docs/plans/design-doc.md` (PRD), `CLAUDE.md`. Decision rows flow through the orchestrator's `scribe_decision` MCP calls.
+
+**Post-Step 1.4 — CLAUDE.md size enforcement (mechanical check):**
+After the Design Doc Writer returns, run `wc -l < CLAUDE.md` and capture the line count. If the count exceeds 200 lines:
+1. FAIL the step. Log to `docs/plans/build-log.md`: `"CLAUDE.md size violation: {count} lines (limit: 200)"`.
+2. Re-dispatch the Design Doc Writer with this additional instruction prepended: `"CLAUDE.md EXCEEDED 200 LINES ({count} lines). Rewrite CLAUDE.md to ≤200 lines. Cut aggressively — keep only what a subagent needs to make correct product decisions. No conventions, no wiki content, no boilerplate."`.
+3. Max 2 retries. If still over 200 after 2 retries, HARD-FAIL and surface to user: `"CLAUDE.md is {count} lines after 2 rewrites. Please manually trim to ≤200 lines before proceeding — this file is auto-loaded into every subagent and bloat here multiplies across all Phases 2-7 dispatches."`.
 
 ### Quality Gate 1
 
-**Autonomous:** Log design and research paths to `docs/plans/build-log.md`. If 2+ RED verdicts, log warning. Proceed.
+**Interactive:** Present Design Doc summary + Research Digest findings to user. Ask: "Approve this design, or adjust?"
 
-**Interactive:** Present Design Document summary + Research Brief verdict table. Ask: "Approve this design, or want to adjust?" <HARD-GATE>DO NOT PROCEED without user approval.</HARD-GATE>
+<HARD-GATE>
+Gate 1 rejection path is codified:
+  - On NO → loop back to Phase 1 Step 1.0 with user feedback passed back to Brainstorm Facilitator (round 1 re-invocation).
+  - On YES → proceed to Step 1.5.
+  - DO NOT PROCEED without user approval in interactive mode.
+</HARD-GATE>
 
-Update TodoWrite and `docs/plans/.build-state.md`.
+**Autonomous:** Log design-doc path + digest path to `docs/plans/build-log.md`. Auto-approve. Proceed.
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+Update TodoWrite and `.build-state.json`.
+
+### Step 1.5 — PREREQ COLLECTOR (post-Gate 1)
+
+Dispatch the Prereq Collector as an INTERNAL inline role-string. Reads `design-doc.md` to determine which credentials are actually needed for the chosen stack. Asks the user ONLY for stack-specific creds.
+
+Call the Agent tool — description: "Prereq collection" — INTERNAL inline role-string — prompt: "You are the Prereq Collector. Read `docs/plans/design-doc.md` with your own Read tool — focus on the Tech Stack section. Determine which credentials the chosen stack actually needs (do NOT ask for a generic laundry list — ask ONLY for what this stack uses).
+
+Example: 'You chose Next.js + Supabase + Vercel — I need your Supabase URL, Supabase anon key, and Vercel auth token.' Skip anything the stack doesn't use.
+
+Output: `docs/plans/phase1-scratch/prereqs.json` with shape `{supabase_url, supabase_anon_key, ...}`. Ask the user once. If they don't have a credential, mark it as `null` and note in the JSON that Phase 4 will surface it as a blocker if hit."
+
+**Autonomous mode:** Create `.env.example` with required keys. Proceed. Log missing keys as blockers if hit during build.
+
+**Why here:** at Phase 0 we don't yet know the stack (it's decided in Step 1.3). Asking for creds before Gate 1 means asking for wrong creds or re-asking on rejection.
+
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
+
+---
+
+### Step 1.6 — PRODUCT SPEC
+
+Call the Agent tool — description: "Product spec" — subagent_type: `product-spec-writer` — prompt: "[CONTEXT header above] Write `docs/plans/product-spec.md` following the structure in `protocols/product-spec-schema.md`. Read ALL of these via your Read tool before writing (do NOT expect pasted content):
+  - `docs/plans/design-doc.md` — PRD: features, persona, JTBD, value prop, scope, tech stack
+  - `docs/plans/phase1-scratch/findings-digest.md` — research synthesis
+  - `docs/plans/phase1-scratch/ux-research.md` — behavioral patterns, pain points
+  - `docs/plans/phase1-scratch/feature-intel.md` — competitive matrix, table-stakes vs differentiators
+  - `docs/plans/phase1-scratch/business-model.md` — revenue model implications
+  - `docs/plans/phase1-scratch/tech-feasibility.md` — technical constraints, rate limits, API limitations
+  - `docs/plans/phase1-scratch/user-decisions.md` — user's product decisions from informed brainstorm
+This is the LAST step that reads raw research files. Every actionable insight must survive in product-spec.md in structured, queryable form. Commit: 'feat: product spec'."
+
+#### Step 1.6.idx — Slice 1 graph index
+
+After `product-spec-writer` returns and `docs/plans/product-spec.md` is on disk, index it into the build graph. Slice 1 graph index — required for downstream agents.
+
+Run via the Bash tool:
+
+- Command: `node ${CLAUDE_PLUGIN_ROOT}/bin/graph-index.js docs/plans/product-spec.md`
+- On exit 0: log success to `docs/plans/build-log.md` and continue.
+- On non-zero exit: STOP. Log the error to `docs/plans/build-log.md` and report the failure. Downstream agents (BO, PO, implementers) require the graph — do not proceed without a successful index.
+
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
 
 ---
 
-## Phase 2: Architecture & Planning
+## Phase 2: Plan / Architect — TEAM of 6 + sequence
 
-**Goal**: Convert the validated Design Document into a concrete architecture and ordered task list. Every agent receives the Design Document — not just the build request.
+**Goal**: Convert the PRD into a concrete architecture and ordered task list with explicit dependencies. Every architect receives the PRD (design-doc.md) + the Research Digest + its domain's raw research file (hybrid routing).
 
 **Mode-specific branch:**
-- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 2 (replaces Backend/Frontend architecture dispatch with SwiftUI/SwiftData/Concurrency/iOS security; adds Feature Flag Resolution at end of phase)
-- If `project_type=web`: no additional branch instructions — proceed with the steps below.
+- `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 2 (replaces Backend/Frontend dispatch with SwiftUI/SwiftData/Concurrency/iOS security; adds Feature Flag Resolution at end of phase).
+- `project_type=web`: no additional branch instructions.
 
-### Step 2.1 — Explore (existing codebase only)
+### Step 2.1 — Explore existing codebase (only if existing code)
 
-If existing code, call the Agent tool — description: "Explore codebase" — prompt: "Explore this codebase. Map architecture layers, file conventions, testing patterns, existing features. Report findings."
+If existing code, call the Agent tool — description: "Explore codebase" — INTERNAL inline role-string — prompt: "Explore existing codebase. Map architecture layers, file conventions, testing patterns, existing features, integration points. Return a compact summary suitable for architects to consume — not a full dump."
 
 If greenfield, skip to Step 2.2.
 
-### Step 2.2 — Architecture Design (4 agents in parallel, ONE message)
+### Step 2.2 — Architecture Design (TEAM of 6 architects coordinating via SendMessage)
+
+The 6 architects design as a TEAM — not 6 isolated subagents. Cross-domain contract boundaries (Backend↔Frontend on API shape, Security↔Backend on auth, A11y↔Frontend on component patterns, Performance↔Backend+Data on query shapes) are caught at design time via peer SendMessage, not absorbed silently by a downstream stitcher.
+
+**On re-entry from LRR backward routing:** If Phase 2 is being re-opened via the re-entry dispatch template (Step 6.3), skip team creation if the original `phase-2-architects` team is still live from this build; otherwise recreate it. Pass the re-entry payload (`{blocking_finding, prior_output: "docs/plans/architecture.md", decision_row}`) into the dispatch prompt of the architect(s) whose domain matches `decision_row.author` — only those architects re-run, not all 6. The re-dispatched architect revises its `docs/plans/phase-2-contracts/<name>.md` in place, SendMessages peers on any contract boundary it now changes, and the synthesizer re-runs once to re-stitch `architecture.md`. Do NOT redo unaffected domains.
+
+After the synthesizer re-stitches `architecture.md`, re-run the Refs Indexer (Step 2.3 dispatch #4) to update `docs/plans/refs.json` with fresh anchors, and re-run the DAG Validator (Step 2.3 dispatch #3) to verify sprint-tasks.md still references valid architecture sections. Invalidate the sprint-context hash per the refs.json mutation rule.
+
+**Step 2.2a — Create the team.**
+
+Call `TeamCreate` with `team_name: "phase-2-architects"`. This team scopes the SendMessage channel for the 6 architects below. Capture the team id in `.build-state.json` for teardown.
+
+**Step 2.2b — Dispatch 6 architects as teammates (ONE message).**
+
+Call the Agent tool 6 times in a single message. Each call passes `team_name: "phase-2-architects"` and a unique `name` (listed below). Each architect receives: `docs/plans/design-doc.md` (PRD) + `docs/plans/phase1-scratch/findings-digest.md` + ITS DOMAIN'S RAW RESEARCH FILE (hybrid routing) + the team roster + cross-check pairings + the per-architect output file path.
+
+Shared brief appended to every architect prompt:
+
+```
+TEAM: phase-2-architects
+ROSTER:
+  - backend-architect         (owns services, API contracts, DB schema)
+  - frontend-architect        (owns component hierarchy, state mgmt, routing)
+  - data-engineer             (owns ETL/ELT, schema versioning, query patterns)
+  - security-engineer         (owns auth model, input validation, threat model)
+  - accessibility-auditor     (owns WCAG 2.2 AA constraints on component/nav choice)
+  - performance-benchmarker   (owns quality-targets.json, bundle + latency budgets)
+
+CROSS-CHECK PAIRINGS (mandatory — if your design touches one of these boundaries, SendMessage the peer before you finalize):
+  - Backend ↔ Frontend         on API contract shape (REST vs GraphQL, request/response schemas, error envelope)
+  - Security ↔ Backend         on auth flow (token storage, refresh, session model, authz gates)
+  - Accessibility ↔ Frontend   on component patterns (primitives, focus management, landmark structure)
+  - Performance ↔ Backend+Data on query shapes (N+1 risk, indexing strategy, bundle impact of data layer choices)
+  - Security ↔ Frontend        on client-side auth (token storage location, CSRF protection, input sanitization, secure cookie flags)
+
+COORDINATION RULES:
+  - Plain text in your output file is INVISIBLE to teammates. If a contract boundary intersects another architect's domain, you MUST `SendMessage` to that peer using the exact `name` from the roster above. Do not assume they will read your file.
+  - If a peer SendMessage challenges a decision you have written, revise your output file and SendMessage back with the resolution — do not silently ignore.
+  - Idle (exit) only after: (1) your initial read + draft is complete, AND (2) all cross-check pairings touching your domain have either been resolved via SendMessage or confirmed non-intersecting.
+
+OUTPUT:
+  Write your findings to `docs/plans/phase-2-contracts/<your-name>.md` (e.g., `docs/plans/phase-2-contracts/backend-architect.md`). This file is the authoritative record of your post-debate position — include both your initial decisions AND any revisions driven by peer SendMessage.
+```
+
+Per-architect dispatches:
+
+**CONTEXT header:** Render `rendered_context_header` for phase 2 per the canonical template (see CONTEXT HEADER HARD-GATE above). Prepend to every Phase 2 architect prompt below.
+
+
+1. Description: "Backend architecture" — subagent_type: `engineering-backend-architect` — team_name: `phase-2-architects` — name: `backend-architect` — Prompt: "[CONTEXT header above] Design system architecture. Read these files via your Read tool before starting — do NOT expect pasted content:\n  - PRD: `docs/plans/design-doc.md`\n  - PRODUCT SPEC: `docs/plans/product-spec.md` (## App Overview, ## Screen Inventory, ## Permissions & Roles, per-feature behavioral sections — feature behaviors are the source of truth your architecture must support)\n  - DIGEST: `docs/plans/phase1-scratch/findings-digest.md`\n  - YOUR DOMAIN RAW: `docs/plans/phase1-scratch/tech-feasibility.md`, `docs/plans/phase1-scratch/feature-intel.md`\nInclude services, data models, API contracts, database schema, integration points. Respect stack choices from PRD. Map per-feature Business Rules and States to specific endpoints, persistence schemas, and validation logic — every State the product spec defines must have a backend behavior.\n\n[paste shared team brief above]"
+
+2. Description: "Frontend architecture" — subagent_type: `engineering-frontend-developer` — team_name: `phase-2-architects` — name: `frontend-architect` — Prompt: "[CONTEXT header above] Design frontend architecture. Read these files via your Read tool before starting — do NOT expect pasted content:\n  - PRD: `docs/plans/design-doc.md`\n  - PRODUCT SPEC: `docs/plans/product-spec.md` (## App Overview, ## Screen Inventory, ## Permissions & Roles, per-feature behavioral sections — feature behaviors are the source of truth your architecture must support)\n  - DIGEST: `docs/plans/phase1-scratch/findings-digest.md`\n  - YOUR DOMAIN RAW: `docs/plans/phase1-scratch/ux-research.md`, `docs/plans/phase1-scratch/feature-intel.md`\nInclude component hierarchy, layout strategy, responsive approach, state management, routing. Align UX with the persona from research. Map the Screen Inventory to your component hierarchy — every screen the product spec lists must have a routable view, and per-feature States must drive the component-state matrix.\n\n[paste shared team brief above]"
+
+3. Description: "Data engineering" — subagent_type: `engineering-data-engineer` — team_name: `phase-2-architects` — name: `data-engineer` — Prompt: "[CONTEXT header above] Design data architecture. Read these files via your Read tool before starting — do NOT expect pasted content:\n  - PRD: `docs/plans/design-doc.md`\n  - PRODUCT SPEC: `docs/plans/product-spec.md` (## App Overview, ## Screen Inventory, ## Permissions & Roles, per-feature behavioral sections — feature behaviors are the source of truth your architecture must support)\n  - DIGEST: `docs/plans/phase1-scratch/findings-digest.md`\n  - YOUR DOMAIN RAW: `docs/plans/phase1-scratch/tech-feasibility.md`\nInclude ETL/ELT patterns, schema versioning, query patterns, indexing strategy, data lineage, migration plan. Per-feature data requirements from the product spec drive your schema — derived fields, denormalizations, and access patterns must serve specific feature flows.\n\n[paste shared team brief above]"
+
+4. Description: "Security architecture" — subagent_type: `engineering-security-engineer` — team_name: `phase-2-architects` — name: `security-engineer` — Prompt: "[CONTEXT header above] Security review. Read these files via your Read tool before starting — do NOT expect pasted content:\n  - PRD: `docs/plans/design-doc.md`\n  - PRODUCT SPEC: `docs/plans/product-spec.md` (## App Overview, ## Screen Inventory, ## Permissions & Roles, per-feature behavioral sections — feature behaviors are the source of truth your architecture must support)\n  - DIGEST: `docs/plans/phase1-scratch/findings-digest.md`\n  - YOUR DOMAIN RAW: `docs/plans/phase1-scratch/tech-feasibility.md`\nCover auth model, input validation, secrets management, threat model, dependency hygiene. Use the product spec's ## Permissions & Roles section to drive your auth model — roles in the product spec must map to enforceable permissions in the architecture.\n\n[paste shared team brief above]"
 
-Read the Design Document and Research Brief. Pass both to every agent.
+5. Description: "A11y constraints" — subagent_type: `a11y-architect` — team_name: `phase-2-architects` — name: `accessibility-auditor` — Prompt: "[CONTEXT header above] Accessibility-driven architecture constraints. Read these files via your Read tool before starting — do NOT expect pasted content:\n  - PRD: `docs/plans/design-doc.md`\n  - PRODUCT SPEC: `docs/plans/product-spec.md` (## App Overview, ## Screen Inventory, ## Permissions & Roles, per-feature behavioral sections — feature behaviors are the source of truth your architecture must support)\n  - DIGEST: `docs/plans/phase1-scratch/findings-digest.md`\n  - YOUR DOMAIN RAW: `docs/plans/phase1-scratch/ux-research.md`\nIdentify WCAG 2.2 AA requirements that affect component choice, navigation structure, form patterns, focus management, landmark regions. Per-feature Persona Constraints (e.g., \"user scans, doesn't read\", \"operator on a phone in the field\") drive component-level a11y constraints.\n\n[paste shared team brief above]"
 
-Call the Agent tool 4 times in a single message:
+6. Description: "Performance constraints" — subagent_type: `testing-performance-benchmarker` — team_name: `phase-2-architects` — name: `performance-benchmarker` — Prompt: "[CONTEXT header above] Define quality targets for this build. Read these files via your Read tool before starting — do NOT expect pasted content:\n  - PRD: `docs/plans/design-doc.md`\n  - PRODUCT SPEC: `docs/plans/product-spec.md` (## App Overview, ## Screen Inventory, ## Permissions & Roles, per-feature behavioral sections — feature behaviors are the source of truth your architecture must support)\n  - DIGEST: `docs/plans/phase1-scratch/findings-digest.md`\n  - YOUR DOMAIN RAW: `docs/plans/phase1-scratch/tech-feasibility.md`\nWrite `docs/plans/quality-targets.json` covering bundle budget, LCP, TTI, API p95, Lighthouse scores. Use per-Scope budgets: Marketing 500KB / Product 300KB / Dashboard 400KB / Internal 200KB gzipped. Per-feature critical-path performance derives from the product spec's Happy Path latency expectations.\n\n[paste shared team brief above]"
 
-1. Description: "Backend architecture" — Prompt: "Design system architecture. DESIGN DOC: [paste]. RESEARCH: [paste tech + risk sections]. Include services, data models, API contracts, database schema. Be specific. Respect tech stack and constraints from the design doc."
+**Step 2.2c — Wait for all 6 teammates to idle**, then proceed to synthesis. The `docs/plans/phase-2-contracts/*.md` files now contain post-debate positions (initial draft plus any SendMessage-driven revisions). The orchestrator does NOT read these files — the synthesizer below does.
 
-2. Description: "Frontend architecture" — Prompt: "Design frontend architecture. DESIGN DOC: [paste]. RESEARCH: [paste user research section]. Include component hierarchy, layout, responsive strategy, state management. Align UX with the user persona from research."
+After all 6 teammates are idle, the 4 raw research files are **SPENT**. They sit on disk for audit but no downstream phase reads them — they are NOT in the `refs.json` index. The orchestrator MOVES them to `docs/plans/phase1-scratch/` if not already there, to make the distinction physically obvious.
 
-3. Description: "Security architecture" — Prompt: "Security review. DESIGN DOC: [paste]. RESEARCH: [paste risk section]. Cover auth model, input validation, secrets management, threat model. Address any regulatory risks flagged in research."
+**Step 2.2d — Team teardown.** After the synthesizer dispatch at Step 2.3 returns, call `TeamDelete` on `phase-2-architects` to clean up the team channel.
 
-4. Description: "Implementation blueprint" — Prompt: "Implementation blueprint. DESIGN DOC: [paste]. Include specific files to create/modify, build sequence, dependency order. Scope to MVP boundary from design doc."
+### Step 2.3 — Sequence: Implementation Blueprint → Sprint Breakdown → DAG Validator → Refs Indexer
 
-After all 4 return, YOU synthesize into one Architecture Document. Save to `docs/plans/architecture.md`.
+Four sequential dispatches.
 
-### Step 2.3 — Metric Loop: Architecture Quality
+**CONTEXT header:** Reuse `rendered_context_header` from phase 2 (already rendered above). Prepend to Step 2.3 synthesizer + sprint-breakdown prompts.
 
-Run the Metric Loop Protocol (`protocols/metric-loop.md`) on the Architecture Document. Define a metric based on: coverage of design doc requirements, specificity, consistency between agents, and **simplicity** — is this the simplest architecture that meets the requirements? Could any service, abstraction, or dependency be eliminated without losing functionality? Penalize over-engineering (microservices for a simple app, Kubernetes for a static site, complex state management for a 3-page app). Max 3 iterations.
+1. Description: "Implementation blueprint" — subagent_type: `code-architect` — Prompt: "[CONTEXT header above] Implementation blueprint. Read the PRD via your Read tool: `docs/plans/design-doc.md`. Read the product spec: `docs/plans/product-spec.md` (Screen Inventory + per-feature behavioral sections — your blueprint's file-and-build-order list must cover every feature in the spec). Read all 6 post-debate architect positions via your own Read tool from `docs/plans/phase-2-contracts/`:\n  - `backend-architect.md`\n  - `frontend-architect.md`\n  - `data-engineer.md`\n  - `security-engineer.md`\n  - `accessibility-auditor.md`\n  - `performance-benchmarker.md`\n\nThese files are the authoritative team positions AFTER any SendMessage-driven revisions — the architects already cross-checked each other's contract boundaries, so you can stitch without re-debating. Your job is to assemble the 6 positions into a coherent architecture. Where positions conflict OUTSIDE the 5 mandatory cross-check pairings, flag the contradiction explicitly in `architecture.md` under a `### Unresolved Tensions` section and pick the safer default. Do not silently absorb contradictions. Include specific files to create/modify, build sequence, dependency order. Write `docs/plans/architecture.md` with stable section anchors per `protocols/architecture-schema.md`. Required top-level sections: Overview, Frontend, Backend, Data Model, Security, Infrastructure, Scope, Out of Scope. Scope to the boundary from the PRD. Every API endpoint heading in the Backend section MUST include feature attribution annotations — e.g. `**POST /api/orders** (provides: order-placement)` — using the feature kebab names from `product-spec.md`. These annotations are required for the graph indexer to emit cross-feature dependency edges."
 
-### Step 2.4 — Sprint Planning
+2. Description: "Sprint breakdown" — subagent_type: `planner` — Prompt: "[CONTEXT header above] Break this architecture into ordered, atomic tasks. Each task needs: description, acceptance criteria, **dependencies** (list of task IDs this depends on), size (S/M/L), **Behavioral Test** field for every UI task (concrete interaction: 'Navigate to [page], click [element], verify [outcome]') or curl-based acceptance test for API tasks, **Feature** — the exact feature name from product-spec.md (e.g. 'Order Placement', 'Auth') that must match a `## Feature: X` heading in product-spec.md (use '—' for infrastructure tasks that don't belong to a specific feature), **Screens** — comma-separated screen names from the product-spec Screen Inventory (e.g. 'Catalog, Product Detail') that must match screen names in product-spec.md (use '—' for backend-only tasks). Read these files via your Read tool before starting:\n  - ARCHITECTURE: `docs/plans/architecture.md`\n  - PRODUCT SPEC: `docs/plans/product-spec.md` (per-feature behavioral sections — every feature in the spec must have at least one task, and per-feature acceptance criteria become Behavioral Test field values)\n  - PRD: `docs/plans/design-doc.md`\nSave to `docs/plans/sprint-tasks.md`. The table must have these columns in order: Task ID, Title, Size, Dependencies, Behavioral Test, Owns Files, Implementing Phase, Feature, Screens. Dependencies field is load-bearing — Phase 4 uses it to batch independent tasks in parallel. Each task's Behavioral Test field SHOULD reference a specific feature acceptance criterion from the product spec (e.g., \"User can submit form with valid email; submitted form appears in admin dashboard within 5s\" — derived from product-spec.md's Happy Path or per-state criteria)."
 
-Follow the Planning Protocol (`protocols/planning.md`). Use 2 sequential Agent tool calls:
+3. Description: "Task DAG validator" — INTERNAL inline role-string — Prompt: "You are the Task DAG Validator. Read `docs/plans/sprint-tasks.md`. Validate for DAG correctness:
+  - No circular dependencies
+  - All referenced task IDs in the Dependencies field exist
+  - Sizing is consistent (S/M/L)
+  - Dependencies match the architecture document (don't depend on a task that builds a component you don't need)
+  - Every UI task has a Behavioral Test field; every API task has a curl-based test
+Report any violations. If clean, return PASS. If violations, return a list of fix requests — Sprint Breakdown re-dispatches once with the fix list."
 
-Call the Agent tool — description: "Sprint breakdown" — prompt: "Break this architecture into ordered, atomic tasks. Each task needs: description, acceptance criteria, dependencies, size (S/M/L). Include a `**Behavioral Test:**` field for every task that has UI — a concrete interaction test: 'Navigate to [page], click [element], verify [expected outcome]'. API-only tasks should have curl-based acceptance tests instead. ARCHITECTURE: [paste]. DESIGN DOC: [paste]. Scope to MVP only."
+4. Description: "Refs indexer" — INTERNAL inline role-string — Prompt: "You are the Refs Indexer. Generate `docs/plans/refs.json` covering ALL live downstream docs:
+  - `docs/plans/design-doc.md` (PRD)
+  - `docs/plans/architecture.md`
+  - `docs/plans/sprint-tasks.md`
+  - `docs/plans/quality-targets.json`
+  - `DESIGN.md` (if it exists yet — Phase 3 extends refs.json after it writes this file)
 
-Then call the Agent tool — description: "Validate task list" — prompt: "Validate this task list: [paste]. Check scope is realistic, no missing tasks, descriptions specific enough for a developer agent to execute, all tasks within MVP boundary."
+For each doc, extract section anchors into a flat index. Schema: `[{\"anchor\": \"design-doc.md#persona\", \"topic\": \"user persona\", \"file_path\": \"docs/plans/design-doc.md\"}, ...]`. This index is consumed by the Phase 4 Briefing Officer for per-task context maps. Do NOT include Phase 1 scratch files — they are SPENT."
 
-Save to `docs/plans/sprint-tasks.md`.
+**Architecture Metric Loop (callable service):** Run the Metric Loop Protocol (`protocols/metric-loop.md`) on `architecture.md`. Define a metric: coverage of PRD requirements, specificity, consistency across the 6 architects, and **simplicity** — is this the simplest architecture that meets the requirements? Could any service, abstraction, or dependency be eliminated? Penalize over-engineering. Max 3 iterations.
+
+#### Step 2.3.1.idx — Architecture graph index
+
+After `code-architect` returns from the Implementation Blueprint dispatch (#1 above) AND the Architecture Metric Loop exits with `architecture.md` on disk, index it into the build graph. Slice 4 graph index — required for downstream agents.
+
+Run via the Bash tool:
+
+- Command: `node ${CLAUDE_PLUGIN_ROOT}/bin/graph-index.js docs/plans/architecture.md`
+- On exit 0: log success to `docs/plans/build-log.md` and continue.
+- On non-zero exit: STOP. Log the error to `docs/plans/build-log.md` and report the failure. Downstream agents require the graph — do not proceed without a successful index.
+
+#### Step 2.3.2.idx — Sprint tasks graph index
+
+After `planner` returns from the Sprint Breakdown dispatch (#2 above) AND the Task DAG Validator (#3 above) returns PASS, index `sprint-tasks.md` into the build graph. Slice 4 graph index — best-effort.
+
+Run via the Bash tool:
+
+- Command: `node ${CLAUDE_PLUGIN_ROOT}/bin/graph-index.js docs/plans/sprint-tasks.md`
+- On exit 0: log success to `docs/plans/build-log.md` and continue.
+- On non-zero exit: STOP. Log the error to `docs/plans/build-log.md` and report the failure. Downstream agents require the graph — do not proceed without a successful index.
+
+#### Step 2.3.4.idx — Decisions re-index (end of Phase 2)
+
+After the four Step 2.3 dispatches complete and the orchestrator finishes routing the 4 Phase 2 `deviation_row` objects through `scribe_decision`, re-index `decisions.jsonl` so the Slice 4 fragment reflects every Phase 2 decision before the LRR aggregator or feedback synthesizer can read it. Skip silently if `docs/plans/decisions.jsonl` does not exist (no decisions written yet).
+
+Run via the Bash tool:
+
+- Command: `node ${CLAUDE_PLUGIN_ROOT}/bin/graph-index.js docs/plans/decisions.jsonl`
+- On exit 0: log success to `docs/plans/build-log.md` and continue.
+- On non-zero exit: STOP. Log the error to `docs/plans/build-log.md` and report the failure. The decisions graph fragment must be current before downstream consumers query it.
+
+**Architecture decisions:** The Implementation Blueprint synthesizer returns 4 `deviation_row` objects (or a `phase_2_decisions` array of row objects) in its structured result — one per cross-cutting Phase 2 decision (API contract, persistence layer, auth model, framework choice). The orchestrator forwards each row through the `scribe_decision` MCP tool (see Phase 4 "Orchestrator-scribe dispatch"); the MCP allocates `D-2-<seq>` IDs and atomically appends to `docs/plans/decisions.jsonl`. Author = `architect`. Each row carries a `ref` anchor pointing into `architecture.md` per `protocols/decision-log.md`. Total: 4 rows.
+
+**Writes:** `docs/plans/architecture.md`, `docs/plans/sprint-tasks.md`, `docs/plans/quality-targets.json`, `docs/plans/refs.json`. Decision rows (4) flow through the orchestrator's `scribe_decision` MCP calls.
 
 ### Quality Gate 2
 
-**Autonomous:** Log to `docs/plans/build-log.md`. Proceed.
+**Interactive:** Present Architecture + Sprint Task List (with dependency graph). Ask: "Approve to start designing + building, or flag changes?"
 
-**Interactive:** Present Architecture + Sprint Task List. Ask: "Approve to start building, or flag changes?" <HARD-GATE>DO NOT PROCEED without user approval.</HARD-GATE>
+<HARD-GATE>
+Gate 2 rejection path is codified:
+  - On NO → loop back to Phase 2 with user feedback.
+  - On YES → proceed to Phase 3.
+  - DO NOT PROCEED without user approval in interactive mode.
+  - Also codifies the LRR BLOCK backward edge: `LRR BLOCK authoring=Phase 2 → back to Phase 2`. The ⭐⭐ star rule routes BLOCK findings via Aggregator decisions.jsonl `decided_by` lookup; if `decided_by == architect`, the build re-opens Phase 2 with the finding as input.
+</HARD-GATE>
 
-Update TodoWrite and `docs/plans/.build-state.md`.
+**Autonomous:** Log to `docs/plans/build-log.md`. Auto-approve. Proceed.
+
+Update TodoWrite and `.build-state.json`.
 
 **iOS feature flag resolution:** if `project_type=ios`, resolve `ios_features` before leaving Phase 2 per `protocols/ios-phase-branches.md` §Phase 2 → Feature Flag Resolution.
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
 
 ---
 
-## Phase 3: Design & Visual Identity
+## Phase 3: Design (DNA-first SEQUENCE)
+
+**Goal**: Lock Visual DNA first, then research against it, then compose from library, then spec, then implement, then critique, then a11y.
 
-**Goal**: Transform architecture into a research-backed visual design system grounded in real references (competitor sites for web, HIG + App Store for iOS).
+**NOTE:** Runs AFTER Phase 2. Cannot parallelize — design decisions depend on architecture outcomes.
 
 **Skip if** the project has no user-facing frontend (CLI tools, pure APIs, backend services).
 
 <HARD-GATE>
-UI/UX IS THE PRODUCT. This phase is a full peer to Architecture and Build — not a footnote, not an afterthought, not a "nice to have." Do NOT skip, compress, or rush this phase for any reason. Agents must research real references, make deliberate visual choices backed by that research, and iterate with verified visual QA before a single line of product code is written.
+UI/UX IS THE PRODUCT. This phase is a full peer to Architecture and Build — not a footnote, not an afterthought. Do NOT skip, compress, or rush this phase for any reason.
 
-Phase 4 (Foundation) WILL NOT START without the design artifact for this mode (`docs/plans/visual-design-spec.md` for web, `docs/plans/ios-design-board.md` for iOS). If it does not exist, return here.
+Phase 4 WILL NOT START without `DESIGN.md` (Pass 1 + Pass 2 complete). If the artifact does not exist, return here.
 </HARD-GATE>
 
-**Mode-specific branch:**
-- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 3 (HIG + App Store + screenlane harvest → iOS Design Board, SwiftUI Preview QA loop, max 3 iterations)
-- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 3 (competitor/Awwwards research → Visual Design Spec → living style guide at `/design-system` → Playwright visual QA, max 5 iterations)
+**Mode-specific branch files drive Phase 3 in detail:**
+- `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 3 (HIG + App Store + screenlane harvest → iOS Design Board, SwiftUI Preview QA loop).
+- `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 3 — this file contains the NEW structure with steps 3.0-3.7 covering Visual DNA Selection (Brand Guardian as DNA owner at 3.0), Visual Research, Component Library Mapping, UX Architecture, Visual Design Spec, Inclusive Visuals Check, Style Guide Implementation (wrapped in Design Critic metric loop), and A11y Design Review. See the Component Library Mapping step in that protocol for the component library strategy.
+
+**Phase 3 branch-file dispatch table (subagent_type references for SSOT lint):**
+- Step 3.0 Visual DNA Selection: subagent_type: `design-brand-guardian` (web)
+- Step 3.1 Visual Research (2 parallel): subagent_type: `visual-research` (web, competitive-audit + inspiration-mining)
+- Step 3.2 Component Library Mapping: subagent_type: `design-ui-designer` (web)
+- Step 3.2b DNA Persona Check: subagent_type: `design-ux-researcher` (web, may route to 3.0)
+- Step 3.3 UX Architecture: subagent_type: `design-ux-architect` (web)
+- Step 3.5 Inclusive Visuals Check: subagent_type: `design-inclusive-visuals-specialist` (web)
+- Step 3.2-ios iOS Design Board: subagent_type: `ios-swift-ui-design` (iOS)
+
+**Phase 3 write discipline:** Phase 3 is the writer for `DESIGN.md` (web) and extends `docs/plans/refs.json` to cover the visual spec anchors once it lands. Phase 3 does NOT write to `architecture.md` or `sprint-tasks.md` — those are Phase 2's.
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+<HARD-GATE>
+LRR BLOCK backward edge: `LRR BLOCK authoring=Phase 3 → back to Phase 3`. The ⭐⭐ star rule routes BLOCK findings via Aggregator decisions.jsonl `decided_by` lookup; if `decided_by == design-brand-guardian` or any Phase 3 writer, the build re-opens Phase 3 with the finding as input.
+</HARD-GATE>
+
+**On re-entry from LRR backward routing:** When Phase 3 is re-opened via the re-entry dispatch template (Step 6.3), the orchestrator passes the re-entry payload (`{blocking_finding, prior_output: "DESIGN.md", decision_row}`) into the specific Phase 3 step named by `decision_row.author`. That step revises the prior output to address `blocking_finding` only — DESIGN.md Pass 1 (Step 3.0), component manifest (Step 3.2), or DESIGN.md Pass 2 (Step 3.4) — and emits a new decision_row. Unaffected steps are NOT re-run. Mode-specific branch files (`protocols/web-phase-branches.md` / `protocols/ios-phase-branches.md`) define which step owns which `decided_by` value.
+
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
 
 ---
 
-## Phase 4: Foundation
+## Phase 4: Build — THREE-TIER FEATURE-BASED EXECUTION
 
 <HARD-GATE>
-Before starting Phase 4: Phase 2 must be approved AND Phase 3 must have produced the design artifact for this mode.
-- Web: `docs/plans/visual-design-spec.md` must exist.
-- iOS: `docs/plans/ios-design-board.md` must exist.
-If the artifact does not exist, DO NOT PROCEED. Return to Phase 3.
-Step 4.2 (Design System) MUST implement from the design artifact — not generic architecture tokens.
+Before starting Phase 4: Phase 2 must be approved, Phase 3 must have produced the design artifact (`DESIGN.md` — Pass 1 + Pass 2 complete; broken-refs lint == 0), and `docs/plans/page-specs/` must contain at least one file (web). You MUST call the Agent tool for EVERY task. No exceptions.
 </HARD-GATE>
 
-**Mode-specific branch (Steps 4.1, 4.2, 4.2b):**
-- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 4 (entitlements generator + Info.plist hardening, XcodeBuildMCP folder structure, SwiftUI design tokens, Maestro flow stubs)
-- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 4 (web project scaffolding, CSS design system tokens, Playwright acceptance test stubs)
+**Goal**: Scaffold project, then execute sprint tasks organized by FEATURE with product adherence checked per-feature during build. Three tiers: Product Owner (product quality) → Briefing Officers (task planning per feature) → Execution Agents (code). The orchestrator drives all dispatches — PO and BO are planning agents that write artifacts to disk.
+
+**Mode-specific branch:**
+- `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 4 for scaffold details and execution agent prompts.
+- `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 4 for scaffold details and execution agent prompts.
+
+**Phase 4 dispatch table (subagent_type references for SSOT lint):**
+- Product Owner (planning): subagent_type: `product-owner`
+- Product Owner (acceptance): subagent_type: `product-owner`
+- Briefing Officer (per feature): subagent_type: `briefing-officer`
+- Web UI (S/M): subagent_type: `engineering-frontend-developer`
+- Web UI (L): subagent_type: `engineering-senior-developer`
+- Web backend: subagent_type: `engineering-backend-architect` OR `engineering-senior-developer`
+- Web AI/ML: subagent_type: `engineering-ai-engineer`
+- iOS UI planner: subagent_type: `ios-swift-ui-design`
+- iOS UI impl: subagent_type: `engineering-senior-developer`, `engineering-mobile-app-builder`
+- iOS Foundation Models: subagent_type: `ios-foundation-models-specialist`
+- iOS StoreKit: subagent_type: `ios-storekit-specialist`
+- iOS Swift review: subagent_type: `swift-reviewer`
+- Security review: subagent_type: `security-reviewer`
+- Cleanup: subagent_type: `code-simplifier`, `refactor-cleaner`
+- Code review: subagent_type: `code-reviewer`, `silent-failure-hunter`
+
+### Step 4.0 — Scaffold (unchanged)
+
+Scaffolding is project skeleton + design system + acceptance test stubs. Three sequential dispatches (full details in the mode-specific branch file):
+
+**CONTEXT header:** Render `rendered_context_header` for phase 4 per the canonical template (see CONTEXT HEADER HARD-GATE above). Includes `dna` field for web projects. Prepend to every Phase 4 prompt below.
+
+1. Description: "Project scaffolding" — subagent_type: `engineering-rapid-prototyper` — mode: "bypassPermissions" — prompt per branch file. [COMPLEXITY: M]
+
+2. Description: "Design system setup" — subagent_type: `engineering-frontend-developer` — mode: "bypassPermissions" — prompt per branch file. Implements design tokens from `DESIGN.md`. [COMPLEXITY: M]
+
+3. Description: "Scaffold acceptance tests" — INTERNAL inline role-string — mode: "bypassPermissions" — prompt: "[CONTEXT header above] Scaffold acceptance tests from sprint-tasks.md. Use Page Object Model. For every task with a Behavioral Test field, create a Playwright test stub (web) or Maestro flow stub (iOS). Stubs must FAIL right now. Commit: 'test: scaffold acceptance tests from sprint tasks'."
+
+**Scaffold verification:** Run the Verify Protocol with `scope: static` (checks 1-3 and 6 only: Build, Type-Check, Lint, Diff Review). Test stubs are designed to fail at this point — do not run checks 4, 5, or 7 until after task implementation.
 
-### Step 4.3 — Metric Loop: Scaffold Health
+### Step 4.1 — Product Owner: Feature Planning
 
-Run the Metric Loop Protocol. Define a metric: builds clean, tests pass, lint clean, structure matches architecture. Max 3 iterations.
+Dispatch the Product Owner in planning mode. It reads the full artifact set via graph queries, groups tasks by feature, sequences features into dependency-ordered waves, and writes a delegation plan.
 
-### Step 4.4 — Verification Gate
+Call the Agent tool — description: "Product Owner: feature planning" — subagent_type: `product-owner` — prompt: "[CONTEXT header above] MODE: planning.
 
-Run the Verification Protocol (`protocols/verify.md`). Critical rules (survive compaction):
-- ONE agent runs all 6 checks sequentially: Build → Type-Check → Lint → Test → Security → Diff Review. Stop on first FAIL.
-- Agent auto-detects stack from manifest files (package.json → Node, go.mod → Go, etc.).
-- On FAIL: for build/type/lint errors, use the Build-Fix Protocol (`protocols/build-fix.md`) — fixes one error at a time with cascade detection. For test/security/diff failures, spawn a targeted fix agent. Re-verify. Max 3 fix attempts.
-- On PASS: log `VERIFY: PASS (6/6)` to `docs/plans/.build-state.md`. Proceed.
+Read these artifacts via graph queries:
+- `docs/plans/product-spec.md` — feature list, cross-feature interactions, screen inventory
+- `docs/plans/sprint-tasks.md` — task breakdown with dependencies
+- `docs/plans/architecture.md` — cross-feature API contracts, shared data entities
+- `docs/plans/page-specs/*.md` — screen assignments per feature
+- `docs/plans/quality-targets.json` — NFRs
 
-Call the Agent tool — description: "Verify scaffolding" — mode: "bypassPermissions" — prompt: "Run the Verification Protocol. Execute all 6 checks sequentially, stop on first failure. Report: VERIFY: PASS or VERIFY: FAIL with details."
+Produce `docs/plans/feature-delegation-plan.json` per the schema in `agents/product-owner.md`. For each feature: list assigned tasks (from sprint-tasks.md), write a product_context summary (~100-200 tokens: persona constraints, key business rules, critical error scenarios, competitive differentiators), extract cross-feature contracts, list page-spec refs (web: `page-specs/*.md` paths; iOS: `DESIGN.md` section anchors). Sequence features into waves by dependency order."
 
-Do not proceed to Phase 5 until verification passes.
+Output: `docs/plans/feature-delegation-plan.json`. Update `.build-state.json`: set `feature_delegation_plan_path`, initialize `current_wave: 1`, `completed_features: []`, `feature_acceptance: {}`.
 
-Update TodoWrite and state.
+### Step 4.2 — Wave Execution (repeat for each wave)
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+Read `feature-delegation-plan.json`. For each wave, execute all features. Features within a wave are independent and their Briefing Officers can be dispatched in parallel.
+
+#### 4.2.a — Briefing Officer dispatch (one per feature, parallel within wave)
+
+For each feature in the current wave, dispatch a Briefing Officer. If the wave has multiple independent features, dispatch all BOs in ONE message (parallel).
+
+Call the Agent tool — description: "Briefing Officer: [feature name]" — subagent_type: `briefing-officer` — mode: "bypassPermissions" — prompt: "[CONTEXT header above] FEATURE DELEGATION from Product Owner:
+
+Feature: [feature name]
+Product context: [paste product_context from delegation plan]
+Cross-feature contracts: [paste contracts from delegation plan]
+Assigned tasks: [paste task IDs]
+Page spec refs: [paste page_spec_refs from delegation plan]
+
+Read the full feature spec via graph query. Read task rows from `docs/plans/sprint-tasks.md`. Read page specs, architecture, component manifest, visual design spec for this feature's screens.
+
+Write `docs/plans/feature-briefs/[feature].md` per the schema in `agents/briefing-officer.md`. For each task: specify agent type, skills, structured context payload (layout, components, API contract, error states, business rules, persona constraints), and acceptance criteria."
+
+Output: `docs/plans/feature-briefs/[feature].md`. Update `.build-state.json.feature_briefs[feature]` with the path.
+
+#### 4.2.b — Task execution (orchestrator reads BO brief, dispatches per task)
+
+After the Briefing Officer writes the feature brief, the orchestrator reads it and executes each task. Tasks within a feature are executed in DAG-parallel batches (topological ordering from the Dependencies field — independent siblings run in parallel, yielding ~30-50% wall-clock saving). The per-task pipeline is unchanged in structure — only the input to the execution agent changes.
+
+**For each task in the feature brief:**
+
+**1. Implementer dispatch** — The orchestrator reads the task's execution spec from the feature brief and pastes the structured context directly into the execution agent's prompt. See mode-specific branch file (`protocols/web-phase-branches.md` §Phase 4 or `protocols/ios-phase-branches.md` §Phase 4) for the exact prompt template.
+
+Call the Agent tool — description: "[task-id] [task name]" — subagent_type: [from BO brief] — mode: "bypassPermissions" — prompt: "[CONTEXT header above] [COMPLEXITY: S/M/L from sprint-tasks.md].
+
+[Paste the full structured context payload from the feature brief — TASK, FEATURE CONTEXT, PAGE LAYOUT, COMPONENTS, API CONTRACT, ERROR STATES, BUSINESS RULES, SKILLS ASSIGNED, ACCEPTANCE. See branch file for exact format.]
+
+## Prior Learnings
+[paste contents of `docs/plans/.active-learnings.md` if it exists, otherwise omit this section]
+
+## Deviation Reporting
+If your implementation deviates from the planned architecture, return a `deviation_row` object per the schema in `protocols/decision-log.md`. If no deviation, return `deviation_row: null`. Do NOT write `decisions.jsonl` directly.
+
+Implement fully with real code and tests. Commit: 'feat: [task]'. Report what you built, files changed, and test results."
+
+**2. Per-task security review (auth/PII tasks only)** — unchanged from prior design.
+
+Call the Agent tool — description: "Security review for [task-id]" — subagent_type: `security-reviewer` — prompt: "[CONTEXT header above] Review changed files from [task-id] for security issues. Scope: auth logic, input validation, secrets handling, dependency hygiene, OWASP Top 10 for web (or iOS Keychain / ATS / data protection for iOS). Return blocking findings only — 80%+ confidence threshold. Files to review: [list from implementer's changeset]."
+
+**3. Senior Dev cleanup** — unchanged. Two-pass, changeset-scoped.
+
+1. Call the Agent tool — description: "Simplify [task-id]" — subagent_type: `code-simplifier` — mode: "bypassPermissions" — prompt: "[CONTEXT header above] Simplify changed files from [task-id]. Remove dead code, unused imports, redundant abstractions. Do NOT add features. Do NOT change architecture. Do NOT touch files outside the changeset. Files: [list]."
+
+2. If TS/JS task: Call the Agent tool — description: "Refactor [task-id]" — subagent_type: `refactor-cleaner` — mode: "bypassPermissions" — prompt: "[CONTEXT header above] Run knip/depcheck/ts-prune on changed files from [task-id]. Changeset only. Files: [list]."
+
+**4. Per-task code review (parallel pair)** — unchanged.
+
+Call the Agent tool 2 times in one message:
+
+1. Description: "Code review for [task-id]" — subagent_type: `code-reviewer` — Prompt: "[CONTEXT header above] Review changed files from [task-id]. 80%+ confidence threshold. Changeset only. Files: [list]."
+
+2. Description: "Silent failure hunt for [task-id]" — subagent_type: `silent-failure-hunter` — Prompt: "[CONTEXT header above] Hunt silent failures in changed files from [task-id]. Files: [list]."
+
+**5. Metric Loop** — unchanged. Authoritative behavioral check per `protocols/metric-loop.md`. Max 5 iterations.
+
+**6. Verify Service** — unchanged. Static checks only (type-check, lint, build). Max 2 fix attempts.
+
+**7. After each task completes** — Update TodoWrite and `.build-state.json`. Write summary to `docs/plans/.task-outputs/[task-id].json`.
+
+**8. Orchestrator-scribe** — After all tasks in a feature complete, collect deviation_rows and forward through `scribe_decision` MCP. Same mechanics as before.
+
+### Step 4.3 — Product Owner: Feature Acceptance
+
+After all tasks for a feature complete, dispatch the Product Owner in acceptance mode. It checks whether the built feature matches the product spec.
+
+Call the Agent tool — description: "Product Owner: accept [feature name]" — subagent_type: `product-owner` — prompt: "[CONTEXT header above] MODE: acceptance. FEATURE: [feature name].
+
+Read the feature's acceptance criteria and business rules via graph query. Read the feature's page spec(s) from `docs/plans/page-specs/`. Use agent-browser (web) or XcodeBuildMCP + Maestro (iOS) to verify the built feature.
+
+Check: (1) Does the feature implement the product spec's happy path? (2) Are business rules correct? (3) Are error states from the product spec handled? (4) Does the layout match the page spec? (5) Does component usage match the manifest?
+
+Write verdict: ACCEPTED or NEEDS_REVISION with specific findings citing product-spec sections."
+
+**Verdict routing:**
+- `ACCEPTED` → mark feature complete in `.build-state.json.feature_acceptance`. Proceed.
+- `NEEDS_REVISION` → orchestrator re-dispatches the Briefing Officer for this feature with the findings. BO writes an updated brief targeting only the failing tasks. Orchestrator re-executes those tasks. Max 2 revision cycles per feature. After 2nd NEEDS_REVISION: interactive → present findings to user. Autonomous → accept with gap note in build-log.md AND append a structured gap entry to `.build-state.json.feature_acceptance[feature].gaps[]` with shape `{finding, severity, accepted_at_cycle}`. The Phase 6 LRR Eng-Quality chapter reads these gaps as input evidence.
+
+### Step 4.4 — Wave Transition
+
+After all features in the current wave are ACCEPTED:
+
+1. Update `.build-state.json`: add features to `completed_features`, increment `current_wave`.
+2. Handle shared file mutations: if any BO flagged shared file changes needed by the next wave, apply them now. The orchestrator identifies shared files from BO cross-feature contract fields. For each shared file flagged by multiple features in the next wave, dispatch a single `code-architect` agent to reconcile the mutations before wave execution begins. Do NOT let multiple BOs independently modify the same shared file.
+3. Run a quick Verify Protocol (static checks) to confirm the wave didn't break anything.
+4. Proceed to next wave. Repeat Steps 4.2-4.4.
+
+After all waves complete, Phase 4 is done.
+
+#### Step 4.4.idx — Decisions re-index (end of wave)
+
+After each wave's deviation rows have been routed through `scribe_decision` (per the Orchestrator-scribe dispatch below), re-index `decisions.jsonl` so the Slice 4 fragment reflects every wave-level decision before the next wave's BOs query open decisions. Skip silently if `docs/plans/decisions.jsonl` does not exist.
+
+Run via the Bash tool:
+
+- Command: `node ${CLAUDE_PLUGIN_ROOT}/bin/graph-index.js docs/plans/decisions.jsonl`
+- On exit 0: log success to `docs/plans/build-log.md` and continue.
+- On non-zero exit: STOP. Log the error to `docs/plans/build-log.md` and report the failure. The next wave's BOs require current decision data.
+
+**Writes:** source code, `docs/plans/.task-outputs/`, `docs/plans/feature-delegation-plan.json`, `docs/plans/feature-briefs/*.md`. Deviation rows flow through the orchestrator's `scribe_decision` MCP calls.
+
+<HARD-GATE>
+DECISIONS.JSONL — ORCHESTRATOR-SCRIBE ONLY via `scribe_decision` MCP. Only the orchestrator may cause appends to `docs/plans/decisions.jsonl`, and it does so exclusively by invoking the `scribe_decision` MCP tool. Any dispatch prompt asking a subagent to write this file is a bug. The orchestrator itself MUST NOT Write or Edit the file directly. Subagents return `deviation_row` objects in their structured result; the orchestrator forwards them through the MCP, which owns ID allocation and atomic append.
+</HARD-GATE>
+
+#### Orchestrator-scribe dispatch (route deviation rows through `scribe_decision` MCP)
+
+Runs after each feature's tasks complete. Same mechanics as before:
+
+1. Collect non-null `deviation_row` from each subagent return.
+2. For each row, invoke `scribe_decision` MCP. One call per row.
+3. MCP allocates `decision_id`, stamps timestamp, validates, atomically appends.
+4. Regenerate `.build-state.md`.
+
+**On resume:** scribe MCP reconstructs its ID allocator by scanning `decisions.jsonl`. The `decisions_next_id` field in `.build-state.json` is deprecated (scribe owns ID allocation).
+
+<HARD-GATE>
+LRR NEEDS_WORK backward edge: `LRR NEEDS_WORK (code-level) → back to Phase 4 target feature`. The Aggregator classifies the finding and routes to the specific feature's Briefing Officer via `related_decision_id` lookup. The BO re-plans the affected task(s), orchestrator re-executes. Product-level issues route to the Product Owner, who re-delegates to the relevant BO.
+</HARD-GATE>
+
+**Compaction checkpoint.** Update `.build-state.json` per the format above. Feature-level state (`completed_features`, `current_wave`, `feature_acceptance`, `feature_briefs`) survives compaction — all planning artifacts are on disk.
 
 ---
 
-## Phase 5: Build — Metric-Driven Dev Loops
+## Phase 5: Audit — Track A (engineering reality) + Track B (product reality) + cross-cutting
 
 <HARD-GATE>
-Before starting: Phase 2 must be approved, Phase 3 must produce `docs/plans/visual-design-spec.md` (web) or `docs/plans/ios-design-board.md` (iOS), Phase 4 must pass. You MUST call the Agent tool for EVERY task. No exceptions.
+Before starting Phase 5: run the Verify Protocol (7 checks) one more time. All checks must pass before expensive audit agents fire.
 </HARD-GATE>
 
-**Mode-specific branch (Step 5.1 implement, Step 5.2 metric loop, Step 5.3b smoke test):**
-- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 5 (iOS skill bundle, feature-flag-gated skill loading, iOS implement prompt, SwiftUI Preview metric loop, Maestro smoke tests)
-- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 5 (web implement prompt, agent-browser metric loop, localhost smoke tests)
+**Goal**: Surface quality issues before Launch Review. Phase 5 runs in three layers: Track A audits the engineering envelope (API / perf / a11y / security / brand drift), Track B audits the built product against `product-spec.md` per-feature (states, transitions, business rules, happy path, persona constraints, wiring, manifest coverage), and Cross-cutting checks (E2E user journeys, autonomous dogfood, fake-data detector) catch what neither track anticipates. Findings from all three layers route through one Feedback Synthesizer (Step 5.4) and one Fix loop (Step 5.5).
 
-Expand TodoWrite with each sprint task.
+**Mode-specific branch:**
+- `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 5 for iOS-adapted Track A/B + cross-cutting (XcodeBuildMCP + Maestro execution surface). Steps 5.1–5.3 are defined in the iOS protocol; Steps 5.4–5.5 below are shared.
+- `project_type=web`: continue below.
 
-**For EACH task, run Steps 5.1 → 5.1b → 5.2 → 5.3 → 5.3b → 5.4 below.** Step 5.1 implementation prompt and Step 5.3b smoke test technology are defined in the mode-specific branch file. The remaining steps (cleanup, loop exit, verification) are mode-agnostic and live here.
+### Step 5.1 — Track A: Engineering Reality (5 parallel auditors, ONE message)
 
-### Step 5.1 — Implement
+Read the NFRs from `docs/plans/quality-targets.json`. Pass the relevant targets to each audit agent so they have concrete thresholds, not generic checks.
 
-Per the mode-specific branch file referenced above. Pick the right developer framing: frontend, backend, AI, etc. Set `[COMPLEXITY: S/M/L]` based on the task's Size from sprint-tasks.md.
+**CONTEXT header:** Render `rendered_context_header` for phase 5 per the canonical template (see CONTEXT HEADER HARD-GATE above). Prepend to every Step 5.X dispatch prompt below.
 
-### Step 5.1b — Cleanup (De-Sloppify)
+Call the Agent tool 5 times in one message:
 
-Follow the Cleanup Protocol (`protocols/cleanup.md`). Critical rules (survive compaction):
-[COMPLEXITY: S]
-- Skip if trivial (< 20 lines, single file).
-- Cleanup agent is a SEPARATE agent from the implementer — no cleaning your own mess.
-- Scope is sacred: ONLY files from the implementation changeset. Zero exceptions.
-- Cleanup fixes: naming, dead code, unused imports, style, DRY. Does NOT: add features, change architecture, touch other files.
-- If cleanup breaks acceptance criteria, revert and skip. Never block the metric loop on cleanup failure.
+1. Description: "API testing" — subagent_type: `testing-api-tester` — Prompt: "[CONTEXT header above] Comprehensive API validation: all endpoints, edge cases, error responses, auth flows. NFR targets: Read `docs/plans/quality-targets.json` via your Read tool for performance and reliability thresholds. Report findings with severity counts."
 
-Call the Agent tool — description: "Cleanup [task name]" — mode: "bypassPermissions" — with the list of files changed and the task's acceptance criteria.
+2. Description: "Performance audit" — subagent_type: `testing-performance-benchmarker` — Prompt: "[CONTEXT header above] Measure response times, identify bottlenecks, flag performance issues. NFR targets: Read `docs/plans/quality-targets.json` via your Read tool for performance thresholds. Bundle size per-Scope budgets apply (Marketing 500KB / Product 300KB / Dashboard 400KB / Internal 200KB gzipped). Report benchmarks AGAINST these targets, not generic metrics."
 
-### Step 5.2 — Metric Loop: Task Quality
+3. Description: "A11y audit" — subagent_type: `a11y-architect` — Prompt: "[CONTEXT header above] WCAG 2.2 AA runtime compliance audit on all interfaces. Check screen reader, keyboard nav, contrast, focus order, touch targets (>=44px), reduced-motion variants. Report issues with severity (Critical/Serious/Moderate/Minor)."
 
-Run the Metric Loop Protocol on the task implementation. Define a metric based on the task's acceptance criteria. For UI-facing tasks, include behavioral verification per the mode-specific branch file (web: agent-browser; iOS: SwiftUI Preview captures). Max 5 iterations.
+4. Description: "Security audit" — subagent_type: `engineering-security-engineer` — Prompt: "[CONTEXT header above] Security review at app level: auth, input validation, data exposure, dependency vulnerabilities. NFR targets: Read `docs/plans/quality-targets.json` via your Read tool for security thresholds. Report findings with severity."
 
-### Step 5.3 — Loop Exit
+5. Description: "Brand Guardian drift check" — subagent_type: `design-brand-guardian` — Prompt: "[CONTEXT header above] You are the Phase 5 drift check. Read DESIGN.md (the DNA card locked at Phase 3.0) + the actually-built pages via Playwright screenshots under docs/plans/evidence/. Score whether Phase 4 implementers stayed true to the DNA or drifted away from it. Specifically check: does the built Character axis match the DNA? Does Density match? Is Material consistent? Is Motion aligned? Report drift count and specific elements. Save findings to docs/plans/evidence/brand-drift.md. Note: this is a drift check only — the Phase 6 LRR Brand Guardian chapter does the verdict. You do NOT issue a pass/fail here, only surface findings."
 
-On target met: mark task complete in TodoWrite, report "Task X/N: [name] — COMPLETE (score: [final], iterations: [count])".
+### Step 5.2 — Track B: Product Reality (parallel per-feature, ONE message)
 
-On stall or max iterations:
-- **Interactive:** present score history + top remaining issue to user.
-- **Autonomous:** accept if score >= 60% of target, skip otherwise. Log to `docs/plans/build-log.md`.
+Track B audits the built app against `product-spec.md` on a per-feature basis. Each feature gets its own auditor; all auditors run in parallel.
 
-After each task: update TodoWrite and `docs/plans/.build-state.md`.
+**CONTEXT header:** Render `rendered_context_header` for phase 5 per the canonical template (see CONTEXT HEADER HARD-GATE above). Prepend to every Step 5.X dispatch prompt below.
 
-### Step 5.3b — Behavioral Smoke Test
+**Feature enumeration:** Before dispatch, query the graph for the full feature inventory:
 
-Skip if this task has no Behavioral Test criteria (API-only, config, infrastructure tasks).
+- Call `mcp__plugin_buildanything_graph__graph_list_features` (no arguments) to get the full feature inventory. Returns an array of `{id, label, kebab_anchor}` for every feature in the indexed product-spec. The orchestrator OWNS this enumeration — auditors never enumerate themselves.
+- If the call fails, STOP. Log `TRACK B BLOCKED: graph_list_features failed` to `docs/plans/build-log.md` and report the error. The graph must be indexed correctly before Track B can run.
 
-Run the Smoke Test Protocol (`protocols/smoke-test.md`). Technology is mode-specific — follow the branch file (web: agent-browser + localhost; iOS: Maestro flow against simulator via XcodeBuildMCP). Evidence saved to `docs/plans/evidence/[task-name]/`.
+**Zero-feature gate:** If feature enumeration returns zero features, STOP. This indicates either the graph indexer is broken or `product-spec.md` has no recognizable `## Feature:` sections — neither is a Phase 5 problem. Log `TRACK B BLOCKED: zero features enumerated` to `docs/plans/build-log.md` and route the build back to Step 1.6 (product-spec-writer) via the standard backward-routing template. Do NOT proceed with Cross-cutting (Step 5.3) on a feature-less Track B run.
 
-On FAIL: spawn fix agent with the evidence (expected vs actual, errors, screenshots, relevant source files). Max 2 fix-and-retest cycles.
+**Dispatch:** Call the Agent tool N times in ONE message — one per `feature_id`:
 
-On PASS: proceed to Step 5.4.
+- Description: "Product Reality Audit: {feature_label}"
+- subagent_type: product-reality-auditor
+- Prompt: "[CONTEXT header above] Audit feature_id: {feature_id}. Follow your Cognitive Protocol (ABSORB → QUERY → SYNTHESIZE → EXECUTE → CLASSIFY → SCORE → WRITE). Write evidence to docs/plans/evidence/product-reality/{feature_id}/. Report manifest of evidence paths back."
 
-### Step 5.4 — Post-Task Verification
+**Post-dispatch verification:** After all Track B auditors return, verify each feature has the four evidence files (`tests-generated.md`, `results.json`, `findings.json`, `coverage.json`) AND that each JSON file parses as valid JSON. If any feature is missing a file or has a malformed JSON file, log `TRACK B EVIDENCE MISSING/MALFORMED: {feature_id}: {path}` to `docs/plans/build-log.md` and re-dispatch that feature's auditor once (this distinguishes the retry from the first attempt). If the second attempt still fails, emit a synthetic finding with `target_phase: 1, target_task_or_step: "1.6"` (the auditor failing twice on the same feature is a strong signal the spec for that feature is malformed) and let it route through the existing spec-gap path at Step 5.4.
 
-Run the Verification Protocol (`protocols/verify.md`). If FAIL, fix before starting the next task.
+**Note on the metric loop:** The Metric Loop callable service is no longer wired as a primary Phase 5 step. It can still be invoked ad-hoc by Track A audit fixes via Step 5.5 if a single check class needs iterative tightening, but the structured per-feature audit replaces the orchestrator-improvised eval cases that the previous Step 5.2 (Eval Harness → Metric Loop) drove.
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+### Step 5.3 — Cross-cutting (3 parallel, ONE message)
 
----
+Call the Agent tool 3 times in one message:
+
+1. Description: "E2E runner" — INTERNAL inline role-string — mode: "bypassPermissions" — Prompt: "Run Playwright E2E test generation, execution, and stability check per `protocols/web-phase-branches.md` Phase 5 E2E steps (generate and run E2E tests for User Journeys, 3 mandatory iterations for flakiness detection). Report results + artifact paths. Records results to `docs/plans/evidence/e2e/iter-3-results.json`. Scope: multi-feature User Journeys ONLY (login → browse → buy, signup → onboarding → first-action). Single-feature happy paths are covered by Track B per-feature auditors at Step 5.2 — do NOT duplicate. Additionally, read the `## Cross-Feature Interactions` section from `docs/plans/product-spec.md`. For each cross-feature rule (e.g., 'Auth → Checkout: user must be authenticated'), generate a targeted E2E test that verifies the rule holds. These are NOT user journeys — they are specific behavioral contracts between features."
+
+2. Description: "Dogfood the app" — subagent_type: `testing-evidence-collector`
+
+3. Description: "Fake-data detector" — subagent_type: `silent-failure-hunter` — mode: "bypassPermissions" — Prompt: "Run the Fake Data Detector Protocol (`protocols/fake-data-detector.md`). Static analysis: grep for Math.random() in business data paths, hardcoded API responses, setTimeout faking async, placeholder text. Dynamic analysis: inspect HAR files from `docs/plans/evidence/` for missing real API calls, static responses, absent WebSocket traffic. Write findings to `docs/plans/evidence/fake-data-audit.md` with file:line refs and severity."
+
+### Step 5.4 — Feedback Synthesizer
+
+The Dogfood findings used to dead-end. Now route them to fix loops.
 
-## Phase 6: Harden — Metric-Driven Hardening
+**Pre-dispatch: finding count check.**
+Before dispatching the synthesizer, count total findings across all 5 input streams:
+- Count lines in each `evidence/product-reality/*/findings.json`
+- Count findings in `evidence/dogfood/findings.md` (count `### Finding` headings or JSON array length)
+- Count entries in `evidence/track-a/*.json`
+- Count failures in `evidence/e2e/iter-3-results.json`
+- Count findings in `evidence/fake-data-audit.md`
 
-### Step 6.0 — Pre-Hardening Verification
+If total findings ≤ 40: dispatch the synthesizer as a single pass (existing behavior below).
 
-Run the Verification Protocol (`protocols/verify.md`). All checks must pass before starting expensive audit agents.
+If total findings > 40: split into two sequential dispatches:
+- **Pass 1 (mechanical routing):** Track B findings (pre-routed, validate only) + Track A findings (static routing) + E2E failures (route to phase 4) + fake-data findings (route to phase 4). These require minimal graph queries. Output: `docs/plans/evidence/dogfood/classified-findings-pass1.json`.
+- **Pass 2 (graph-heavy classification):** Dogfood findings only (need full graph-based classification). Input includes pass-1 output for dedup. Output: merge pass-1 + pass-2 into final `docs/plans/evidence/dogfood/classified-findings.json`.
 
-**Mode-specific branch (Steps 6.1 → 6.2e):**
-- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 6 — dispatch iOS twin commands (`/buildanything:verify` → `/buildanything:ux-review` → `/buildanything:fix`) in sequence. Skip Steps 6.1, 6.1b, 6.2, 6.2b, 6.2c, 6.2d, 6.2e. Then run Step 6.4 Reality Check below with iOS evidence.
-- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 6 — run Steps 6.1 (5-agent audit), 6.1b (eval harness), 6.2 (metric loop), 6.2b (eval re-run), 6.2c (Playwright E2E, 3 mandatory iterations), 6.2d (agent-browser dogfood), 6.2e (fake data detector). Then run Step 6.4 Reality Check below.
+Call the Agent tool — description: "Synthesize all findings" — subagent_type: `product-feedback-synthesizer` — Prompt: "[CONTEXT header above] Interpret findings from Track A, Track B, and Cross-cutting streams. Inputs:
 
-### Step 6.4 — Reality Check
+- `docs/plans/evidence/dogfood/findings.md` — autonomous exploration findings, each requires classification + routing
+- `docs/plans/evidence/product-reality/*/findings.json` — one per feature (web uses agent-browser evidence; iOS uses XcodeBuildMCP + Maestro evidence). Each Track B finding ALREADY CARRIES `target_phase` and `target_task_or_step` set by the product-reality-auditor. VALIDATE these against the graph (same `graph_query_dependencies` walk used for dogfood findings) and pass through if valid; only re-route if validation fails (e.g., the targeted task no longer exists in the task DAG).
+- E2E test failures: `docs/plans/evidence/e2e/iter-3-results.json` — failures that persisted through 3 Playwright iterations. For each, set `source: "e2e"`, classify severity, route to `target_phase: 4`.
+- Fake-data findings: `docs/plans/evidence/fake-data-audit.md` — hardcoded/mock data in production paths. For each, set `source: "fake-data"`, classify severity, route to `target_phase: 4`.
+- Track A audit findings: `docs/plans/evidence/brand-drift.md`, `docs/plans/evidence/track-a/*.json` (API contract, performance, a11y, security). Web uses Playwright/Lighthouse; iOS uses XcodeBuildMCP/Instruments. These are engineering-focused findings. For each Track A finding, set `source: "track-a"`, classify severity, and route: API/perf/security findings → `target_phase: 4` (implementation fix); a11y findings → `target_phase: 4` (implementation fix); brand-drift findings → `target_phase: 3` (design fix, re-run Brand Guardian at Step 3.0).
+
+For each finding, ensure it ends up classified with:
+  - Code-level bug (broken feature, failing logic, fake data) → `target_phase: 4`, assign to the specific task that owns the affected file
+  - Visual/design issue (styling drift, missing state, a11y gap) → `target_phase: 3`, assign to the Phase 3 step that owns the relevant artifact
+  - Structural/architecture issue (missing feature, wrong data flow, API mismatch) → `target_phase: 2`, assign to the architecture section
+  - Spec-gap (acceptance criteria too vague, persona constraint not measurable) → `target_phase: 1, target_task_or_step: "1.6"`
+
+Output: `docs/plans/evidence/dogfood/classified-findings.json` with shape `[{finding_id, source: \"dogfood\" | \"product-reality\" | \"track-a\" | \"e2e\" | \"fake-data\", severity, target_phase, target_task_or_step, description, evidence_ref, related_decision_id?: string}, ...]`. The `source` field distinguishes the five input streams. The file also carries a footer object with: `graph_used: boolean` (false if any graph call failed and grep fallback ran), `re_routed_findings: [{finding_id, original_target, new_target, reason}, ...]` (Track B findings whose routing the synthesizer overrode after graph validation failed — empty array if none), `source_counts: {dogfood: N, product_reality: M, track_a: P, e2e: N, fake_data: N}` (count by input stream). This file is read by the Phase 5 fix loop and by the Phase 6 LRR Aggregator for backward routing."
+
+### Step 5.5 — Fix loop
+
+For each CRITICAL/HIGH classified finding, dispatch the appropriate fix agent based on `target_phase`. Max 2 fix cycles. Routing template at the bottom of this file ("Re-entry dispatch template"). Findings with `target_phase: 1, target_task_or_step: "1.6"` route back to `product-spec-writer` to tighten the spec, which re-triggers Track B for the affected feature on the next loop.
+
+**Writes:** `docs/plans/evidence/*.json`, `docs/plans/evidence/fake-data-audit.md`, `docs/plans/evidence/dogfood/classified-findings.json`, `docs/plans/evidence/product-reality/*/{tests-generated.md, results.json, findings.json, coverage.json, screenshots/}`, `docs/plans/learnings.jsonl` (reality sweep writes PITFALL/PATTERN rows — see `protocols/decision-log.md` for the Dissent Log Revisit Pass path).
+
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
+
+---
 
-Call the Agent tool — description: "Final verdict" — prompt: "You are the Reality Checker. Default: NEEDS WORK. The hardening loop reached score [final_score] after [iterations] iterations. Score history: [paste table]. Review all evidence. Eval harness results: [baseline pass rate] → [final pass rate]. E2E test results: [paste E2E table — 3 iterations, final pass rate, quarantined count]. Dogfood results: [paste issue count and any CRITICAL/HIGH findings, or 'clean — no issues found']. Fake data audit results: [paste findings or 'clean — no fake data detected']. CRITICAL failures remaining: [list or none]. Verdict: PRODUCTION READY or NEEDS WORK with specifics."
+## Phase 6: Launch Readiness Review
 
-<HARD-GATE>Do NOT self-approve. Reality Checker must give the verdict.</HARD-GATE>
+**Goal**: 5 independent chapter judges + mechanical aggregator with file-completeness checkpoint + author-aware backward routing on BLOCK.
 
-**On PRODUCTION READY:** Log verdict. Proceed to Phase 7.
+Split from old Phase 6. Old 6.4 (Reality Check) and 6.5 (LRR) merged and restructured. Reality Checker keeps its evidence sweep role only — the combined verdict authority moved to the LRR Aggregator.
 
-**On NEEDS WORK:** The Reality Checker returns specific issues. These must be fixed — not logged and ignored.
+#### Step 6.0.idx — Decisions re-index (pre-LRR backfill)
 
-1. Read the Reality Checker's specific findings. Classify each:
-   - **Code bug** (broken feature, failing test, fake data) → spawn implementation fix agent with the finding + affected files.
-   - **Structural issue** (missing feature, wrong architecture, data flow problem) → spawn architect agent to produce a fix plan, then implementation agent to execute it. This is a mini Phase 5 loop for the specific issue.
-   - **Blocker** (missing API key, no backend, needs human action) → log to `docs/plans/build-log.md` and present to user. Cannot be auto-fixed.
-2. After fixes, re-run verification (7 checks) + the specific failing gate (E2E, dogfood, or fake data — whichever surfaced the issue).
-3. Re-run the Reality Checker with updated evidence.
+Before dispatching the Reality Checker (Step 6.0) and the LRR chapter judges (Step 6.1), re-index `decisions.jsonl` so the Slice 4 fragment reflects any decisions appended since the last Phase 4 wave transition. The aggregator's backward-routing walk at Step 6.2 (the ⭐⭐ star rule) reads the indexed fragment via `graph_query_decisions` — running this once here catches any drift from hand-edits or out-of-band scribe writes. Skip silently if `docs/plans/decisions.jsonl` does not exist.
+
+Run via the Bash tool:
+
+- Command: `node ${CLAUDE_PLUGIN_ROOT}/bin/graph-index.js docs/plans/decisions.jsonl`
+- On exit 0: log success to `docs/plans/build-log.md` and continue.
+- On non-zero exit: STOP. Log the error to `docs/plans/build-log.md` and report the failure. The LRR aggregator's backward-routing walk requires current decision data.
+
+### Step 6.0 — Reality Check (evidence sweep + dissent log revisit pass)
+
+Reality Checker runs its existing evidence sweep per `commands/build.md` precondition list. Writes the manifest to `docs/plans/evidence/reality-check-manifest.json`. Does NOT issue a combined verdict.
 
 <HARD-GATE>
-Max 2 NEEDS WORK cycles. If the Reality Checker returns NEEDS WORK a third time:
-- **Interactive:** Present all remaining issues to user. Ask for direction.
-- **Autonomous:** Log remaining issues to `docs/plans/build-log.md`. Proceed to Phase 7 with a warning in the completion report.
-Do not loop forever.
+PRECONDITION (orchestrator-side, BEFORE dispatching Reality Checker):
+
+REQUIRED EVIDENCE FOR ALL PROJECTS:
+  - `docs/plans/.build-state.json` exists, contains current build session id, contains a recent `VERIFY: PASS` line from this session.
+
+REQUIRED EVIDENCE FOR `project_type=web`:
+  - `docs/plans/evidence/e2e/iter-3-results.json` (non-empty)
+  - `docs/plans/evidence/dogfood/findings.md` (non-empty)
+  - `docs/plans/evidence/dogfood/classified-findings.json` (non-empty)
+  - `docs/plans/evidence/fake-data-audit.md` (non-empty)
+  - `docs/plans/evidence/product-reality/*/coverage.json` — at least one per feature in product-spec.md (non-empty); a missing file for any feature listed in product-spec.md is itself a BLOCK
+  - `docs/plans/evidence/product-reality/*/findings.json` (one per feature; may be an empty array `[]` if no failures)
+  - `docs/plans/evidence/manifest.json`
+
+REQUIRED EVIDENCE FOR `project_type=ios`:
+  - `docs/plans/ios-verify-report.md` (non-empty)
+  - `docs/plans/ios-ux-review-report.md` (non-empty)
+  - At least one `*.yaml` file in `maestro/`
+  - At least one `*.png` screenshot in `docs/plans/evidence/maestro-runs/` from this build session
+  - `docs/plans/evidence/manifest.json`
+
+If any required file does not exist or is empty, do NOT dispatch Reality Checker. Log "REALITY CHECK BLOCKED" with missing-file list. Interactive: present blocker to user. Autonomous: return to the failing step and re-dispatch once; if still missing, abort.
 </HARD-GATE>
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+**CONTEXT header:** Render `rendered_context_header` for phase 6 per the canonical template (see CONTEXT HEADER HARD-GATE above). Prepend to every Phase 6 prompt below (Reality Checker + the 5 LRR chapters).
 
----
+Call the Agent tool — description: "Evidence sweep" — subagent_type: `testing-reality-checker` — Prompt: "[CONTEXT header above] You are the Reality Checker — evidence-sweep role only. Default verdict: NONE. You receive evidence by FILE PATH only — never by paste. Use Read and Glob tools to verify each file exists, is non-empty, was modified within this build session, contains no placeholder strings ('TODO', 'PLACEHOLDER', 'TBD', 'FIXME', 'XXX').
 
-## Phase 7: Ship
+Evidence paths to verify: [orchestrator pastes the precondition list per project_type].
+
+For every Behavioral Test field in `docs/plans/sprint-tasks.md`, verify a corresponding evidence file exists in `docs/plans/evidence/[task-slug]/` AND that the test-stub-detector (per `protocols/verify.md` Step 2) does not flag the corresponding test file as a stub.
+
+For every architecture MUST in `docs/plans/architecture.md`, verify the implementation file exists via Glob AND contains the named symbol via Grep.
+
+**Dissent Log Revisit Pass:** Read `docs/plans/decisions.jsonl`. For every row where `status == \"open\"` and `revisit_criterion` is non-empty, semantically evaluate the criterion against current evidence. If triggered:
+  1. Emit a structural finding in the manifest: `revisit-criterion-triggered: D-N-M — [criterion]`
+  2. Append a PITFALL row to `docs/plans/learnings.jsonl` with `{pattern_type: \"PITFALL\", top_issue: \"[decision] — [criterion]\", fix_applied: \"[what build did instead]\", provenance: {decision_id: \"D-N-M\"}}`
+  3. Flag the triggered decision — this feeds LRR as a potential cross-chapter concern
+
+Write the evidence manifest to `docs/plans/evidence/reality-check-manifest.json` with fields `{file_path, sha256, byte_count, modified_time, verdict_contribution}` per file. Emit any structural findings surfaced during the sweep. DO NOT issue a combined verdict — that authority moved to the LRR Aggregator at Step 6.1 below."
+
+### Step 6.1 — LRR: 5 chapter judges in parallel (ONE message)
+
+Follow the Launch Readiness Review Protocol (`protocols/launch-readiness.md`). The net-5 panel: Eng-Quality (merged Eng+QA with PM chapter folded in), Security, SRE (includes Performance), A11y (NEW SEAT), Brand Guardian (REPLACES old Design mechanical check).
+
+Dispatch 5 chapter judges in parallel. Each receives fresh context, its own evidence slice, and the chapter verdict schema from `protocols/launch-readiness.md`.
+
+Call the Agent tool 5 times in ONE message. Note: the Eng-Quality chapter dispatches `code-reviewer` as primary, with a parallel `pr-test-analyzer` sub-dispatch for test-coverage adequacy evidence that feeds into the Eng-Quality verdict file.
+
+1. Description: "LRR Eng-Quality chapter" — subagent_type: `code-reviewer` — Prompt: "[CONTEXT header above] You are the Eng-Quality chapter of the Launch Readiness Review. Your natural tendency is to be encouraging. Fight it. Default verdict: NEEDS WORK.
+
+Read: `docs/plans/architecture.md`, `docs/plans/design-doc.md` (PRD), `docs/plans/sprint-tasks.md`, `docs/plans/.task-outputs/`, `protocols/verify.md` check outputs from `.build-state.json`, test results from Phase 4 and 5, `docs/plans/evidence/product-reality/*/coverage.json` (Track B per-feature coverage). Also read `docs/plans/decisions.jsonl` for cross-chapter context.
+
+Requirements coverage is sourced from Phase 5 Track B evidence — do NOT recompute. Read every `docs/plans/evidence/product-reality/*/coverage.json` (one per feature). Aggregate the per-feature `coverage_pct` and `status` fields into a single `requirements_coverage[]` array on your verdict, one entry per feature with `{feature_id, feature_label, status, coverage_pct, blocker_summary}` where `blocker_summary` is a short string distilling `missing_states + broken_transitions + unenforced_rules + persona_constraint_violations` from coverage.json. Any `MISSING` status is a BLOCK finding. Any `PARTIAL` is CONCERNS at minimum. If a `coverage.json` file is missing for a feature listed in product-spec.md, that itself is a BLOCK finding (Track B did not run for that feature — pipeline integrity issue).
+
+Before writing the final verdict, spawn a parallel subagent dispatch: description: 'LRR test coverage adequacy' — subagent_type: `pr-test-analyzer` — prompt: 'You are a test-coverage auditor for the Eng-Quality LRR chapter. Read the test files under tests/, task-outputs/, and behavioral-test stub detector output. Evaluate: (1) do declared behavioral tests have non-stub bodies, (2) does coverage match the PR diff scope, (3) are edge cases covered, (4) are any tests flaky markers set. Return a JSON summary with test_coverage_score (0-100), stub_flagged_count, edge_case_gap_count, recommendations[]. Save to docs/plans/evidence/lrr/eng-quality-coverage.json.' Read the resulting eng-quality-coverage.json and fold its findings into your verdict.
+
+Evaluate code quality + test coverage adequacy + architecture conformance + requirements coverage TOGETHER (single coherent view — merged from old Eng + QA chapters). Check: do declared behavioral tests actually exercise the features? Are there stub-flagged tests? Do tests match task acceptance criteria? Does the built code match architecture MUSTs? Are features all COVERED?
+
+Write verdict to `docs/plans/evidence/lrr/eng-quality.json` per `protocols/launch-readiness.md` schema. Fields: `chapter=eng-quality`, `verdict` (PASS|CONCERNS|BLOCK), `override_blocks_launch` (false unless BLOCK), `evidence_files_read` (non-empty, MUST include eng-quality-coverage.json), `findings[]` (each with `severity`, `description`, `evidence_ref`, `related_decision_id` if blocker ties to a decisions.jsonl row), `requirements_coverage[]` (shape per the Track B aggregation paragraph above — `{feature_id, feature_label, status, coverage_pct, blocker_summary}`), `follow_up_spawned=false`, `follow_up_findings=null`. Eng-Quality CANNOT spawn follow-ups."
+
+2. Description: "LRR Security chapter" — subagent_type: `security-reviewer` — Prompt: "[CONTEXT header above] You are the Security chapter of the LRR. Read: `docs/plans/evidence/fake-data-audit.md`, Phase 5 security audit output (from Step 5.1). Also read `docs/plans/decisions.jsonl` for context.
+
+Evaluate auth model, input validation, secrets management, dependency vulnerabilities. Write verdict to `docs/plans/evidence/lrr/security.json` per schema. Fields: `chapter=security`, `verdict`, `override_blocks_launch`, `evidence_files_read` (non-empty), `findings[]` (with `related_decision_id` when applicable), `follow_up_spawned` (boolean), `follow_up_findings` (null or typed object).
+
+Security MAY spawn ONE read-only follow-up investigation, but ONLY if verdict would be BLOCK — NOT on suspicion. This is tightened from current behavior. Follow-up: read-only, Read/Grep/Glob only, max 15 tool calls, self-report tool_calls_used. See `protocols/launch-readiness.md` for follow-up flow."
+
+3. Description: "LRR SRE chapter" — subagent_type: `engineering-sre` — Prompt: "[CONTEXT header above] You are the SRE chapter of the LRR. Read: performance-audit outputs from Phase 5 (Step 5.1 performance auditor), Performance Benchmarker evidence, NFRs from `docs/plans/quality-targets.json` and `docs/plans/sprint-tasks.md`, reliability checks. Also read `docs/plans/decisions.jsonl` for context.
+
+Evaluate whether the build meets NFR targets (response time, load handling, error rates) and is production-ready under load. Bundle-size budget violations (>25% over Scope budget) auto-block. Write verdict to `docs/plans/evidence/lrr/sre.json` per schema.
+
+SRE MAY spawn ONE read-only follow-up investigation, but ONLY if verdict would be BLOCK. Same caps as Security."
+
+4. Description: "LRR A11y chapter" — subagent_type: `a11y-architect` — Prompt: "[CONTEXT header above] You are the A11y chapter of the LRR (NEW SEAT in this panel — closes the biggest coverage gap). Read: Phase 5 a11y audit output (from Step 5.1), WCAG 2.2 AA runtime check, per-page accessibility findings, `docs/plans/quality-targets.json` a11y section.
+
+Scoring rules:
+  - PASS if zero Serious + zero Critical findings
+  - CONCERNS if 1-3 Serious + 0 Critical
+  - BLOCK if any Critical OR >3 Serious
+
+Write verdict to `docs/plans/evidence/lrr/a11y.json` per schema. A11y CANNOT spawn follow-ups."
+
+5. Description: "LRR Brand Guardian chapter" — subagent_type: `design-brand-guardian` — Prompt: "[CONTEXT header above] You are the Brand Guardian chapter of the LRR (REPLACES the old Design mechanical check — real taste judgment, not a 15-line mechanical gate). Your natural tendency is to be encouraging. Fight it. Default verdict: NEEDS WORK.
+
+Read: `DESIGN.md` (full file — `## Overview > ### Brand DNA` is the locked 7-axis card from Phase 3.0; YAML tokens are what Phase 4 was supposed to honor; `## Do's and Don'ts` are the explicit guardrails), `docs/plans/design-references.md`, Playwright screenshots under `docs/plans/evidence/` matching production pages, Phase 3.6 Design Critic final score from `.build-state.json`.
+
+Evaluate DRIFT: did the built product stay true to DESIGN.md (DNA + tokens + guardrails)? Score the gap on 7 DNA axes (Scope, Density, Character, Material, Motion, Type, Copy) + 5 craft dimensions (whitespace rhythm, visual hierarchy, motion coherence, color harmony, typographic refinement). Cite specific elements ('the hero padding at landing.tsx:42 is 32px but DNA calls for Airy density — should be 48px+') — never vague ('needs polish').
+
+Write verdict to `docs/plans/evidence/lrr/brand-guardian.json` per schema. Fields per protocol. Brand Guardian CANNOT spawn follow-ups."
+
+**Security/SRE BLOCK-only follow-up dispatch — SDK-gated (Stage 5 / task 5.3.1).** The read-only follow-up investigations spawned by the Security and SRE chapters (BLOCK-only trigger per `protocols/launch-readiness.md`) are dispatched via a TS switch: when the SDK flag is active (default), the orchestrator dispatches the follow-up through `claude-agent-sdk` with `maxTurns: 15` — a hard safety rail that prevents runaway remediation loops. When the SDK is disabled (`BUILDANYTHING_SDK=off`), fall back to the standard Agent tool dispatch with the same 15 tool-call cap self-reported via `tool_calls_used` (the markdown-mode cap documented in `protocols/launch-readiness.md`). If a follow-up exceeds 15 turns under SDK mode, the orchestrator flags to the user (interactive) or logs a warning and treats the parent chapter as BLOCK confirmed (autonomous) — do NOT let the subagent churn indefinitely.
 
-**Mode-specific branch (Step 7.1 documentation + deploy):**
-- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 7 — ship pipeline is optional (simulator-only is a valid end-state). If shipping, run asc-* agents + fastlane. Skip web Step 7.1 below.
-- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 7 (Step 7.1 documentation + deploy notes).
+### Step 6.1a — PM coverage fold-in
 
-### Step 7.0 — Pre-Ship Verification
+PM coverage is a sub-input of the Eng-Quality chapter — evaluated inline within the Eng-Quality dispatch at Step 6.1 above against `design-doc.md` scope and emitted as a `requirements_coverage[]` field on `eng-quality.json`. The LRR Aggregator runs exactly once. Chapter count stays 5.
 
-Run the Verification Protocol (`protocols/verify.md`). All checks must pass before documenting and shipping. If FAIL persists after 3 fix attempts, return to Phase 6.
+### Step 6.2 — LRR Aggregator (sequential, after all 5 chapter files exist)
 
-### Step 7.0b — Requirements Coverage Report
+Call the Agent tool — description: "LRR Aggregator" — INTERNAL inline role-string — Prompt: "You are the LRR Aggregator. You mechanically apply the 6 aggregation rules from `protocols/launch-readiness.md`. You may NOT self-approve — you cite the triggering rule number on every verdict.
 
-Call the Agent tool — description: "Requirements coverage check" — prompt: "Re-read the original Design Document (docs/plans/*.md design doc) and the user journeys + NFRs from docs/plans/sprint-tasks.md. For EVERY feature listed in the MVP scope, verify: (1) it has a corresponding implemented task, (2) it has a passing test or behavioral verification, (3) it is reachable and functional in the running app. Produce a coverage table:
+**STEP 1 — FILE-COMPLETENESS CHECKPOINT:** Before applying any aggregation rule, use Glob to list `docs/plans/evidence/lrr/*.json` and verify ALL 5 expected chapter files exist and parse as valid JSON:
+  - `eng-quality.json`
+  - `security.json`
+  - `sre.json`
+  - `a11y.json`
+  - `brand-guardian.json`
 
-| MVP Feature | Task | Test | Verified | Status |
-|-------------|------|------|----------|--------|
+If any are missing or malformed, log 'LRR INCOMPLETE' with the missing file list, write a partial status to `docs/plans/evidence/lrr-incomplete.json`, and STOP — do not emit a combined verdict. This is the file-completeness checkpoint that closes the partial-glob race the current Aggregator is vulnerable to.
 
-Mark each as COVERED, PARTIAL (implemented but untested), or MISSING. Any MISSING feature is a blocker — report it immediately."
+**STEP 2 — APPLY 6 RULES per `protocols/launch-readiness.md`:**
+  1. ANY `override_blocks_launch: true` → combined_verdict = BLOCKED
+  2. ALL verdicts PASS AND zero follow-ups spawned → combined_verdict = PRODUCTION READY
+  3. ANY verdict BLOCK (with override_blocks_launch: false) → combined_verdict = NEEDS WORK + findings routed to fix loop
+  4. ANY verdict CONCERNS → combined_verdict = NEEDS WORK, concerns logged
+  5. Follow-up spawned AND follow_up.confirmed: true → treat parent chapter verdict as if BLOCK
+  6. Contradictions between chapters on typed fields → combined_verdict = BLOCKED with cross-chapter contradiction finding
 
-If any features are MISSING: spawn implementation agents to build them, then re-run verification. This is the final safety net before shipping — it catches requirements that were planned but somehow never built.
+**STEP 3 — ON BLOCK VERDICT (the ⭐⭐ star rule — backward routing):** For each BLOCK finding in any chapter, read the `related_decision_id` field. Look up that row in `docs/plans/decisions.jsonl`. Find the `decided_by` field (author of the decision — per the `decided_by` free-form role-string convention in `protocols/decision-log.md`. The Aggregator matches on the string value directly. Common values: `architect` (Phase 2 architecture decisions), `design-brand-guardian` (Phase 3 Visual DNA lock), `implementer` (Phase 4 deviation rows), `human` (Gate 1/2 user decisions)). Route BACKWARD to the authoring phase with the finding as input. This replaces the current 'stop and wait' BLOCK behavior with author-aware re-entry.
 
-### Step 7.1 — Documentation
+**BLOCK sequentialization (Stage 4 A6 / task 4.4.3).** When multiple chapters return BLOCK in the same LRR round, the aggregator MUST process the BLOCK findings one-at-a-time in chapter declaration order (Eng-Quality → Security → SRE → A11y → Brand Guardian). DO NOT dispatch backward-routing re-entries or Security/SRE follow-up investigations in parallel — sequentialize to preserve deterministic commit ordering, avoid writer-owner lease contention on shared artifacts (`decisions.jsonl`, `lrr-routing.json`), and make the per-target-phase cycle-counter increments monotonic. Parallel BLOCK dispatch is a hard error.
 
-Per the mode-specific branch file referenced at the top of Phase 7.
+Write routing decisions to `docs/plans/evidence/lrr-routing.json` with shape `[{finding_id, chapter, related_decision_id, authoring_phase, action: \"re-open\"}, ...]`.
 
-### Step 7.2 — Metric Loop: Documentation Quality
+**STEP 4 — ON NEEDS_WORK:** Classify findings & route to Phase 4 (code-level — single-task fix) or Phase 2 (structural — re-architect) or Phase 3 (visual — re-design). Same routing file.
 
-Run the Metric Loop Protocol on documentation. Define a metric based on completeness and whether a new developer could follow the README. Max 3 iterations.
+**STEP 5 — ON READY:** Write `docs/plans/evidence/lrr-aggregate.json` with shape:
 
-### Step 7.3 — Record Learnings
+```json
+{
+  \"combined_verdict\": \"PRODUCTION READY | NEEDS WORK | BLOCKED\",
+  \"chapter_verdicts\": {\"eng-quality\": \"PASS|CONCERNS|BLOCK\", \"security\": \"...\", \"sre\": \"...\", \"a11y\": \"...\", \"brand-guardian\": \"...\"},
+  \"triggered_rule\": <1-6>,
+  \"findings\": [...aggregated from all chapters...],
+  \"follow_ups_spawned\": [list of chapters that spawned follow-ups],
+  \"backward_routing\": [...from lrr-routing.json if any...],
+  \"timestamp\": \"ISO-8601\"
+}
+```
+
+Forward to Phase 7.
 
-Append to `docs/plans/learnings.md` (create if it doesn't exist). Review the build and record 3-5 learnings:
+Cite triggering rule number in output. No verdict is valid without citing the rule."
 
-- **PATTERN:** [what worked well and should be repeated in future builds]
-- **PITFALL:** [what failed, caused waste, or required excessive iterations]
-- **HEURISTIC:** [project-specific tuning discovered during this build]
+### Step 6.3 — Verdict resolution
 
-Base learnings on: metric loop stall patterns, build-fix frequency, phases that exceeded expected iterations, agent prompts that needed rework.
+The LRR Aggregator's `combined_verdict` is the authoritative verdict. Resolution rules:
 
-### Completion Report
+  - **PRODUCTION READY** → log aggregate path to `.build-state.json` and `build-log.md`. Proceed to Phase 7.
+  - **NEEDS WORK** → apply backward routing from `lrr-routing.json` per the re-entry template below. Max 2 NEEDS_WORK cycles before presenting to user (interactive) or proceeding with warning (autonomous).
+  - **BLOCKED** → apply backward routing (⭐⭐ star rule) per the re-entry template below. NEVER proceed to Phase 7 with BLOCKED.
 
-Create final commit. Present:
+**Re-entry dispatch template (used by backward routing from LRR BLOCK / NEEDS_WORK, and by the Phase 5 → Phase 4 fix loop):**
+
+```
+On re-entry from LRR BLOCK:
+  INPUT passed to the re-opened phase:
+    blocking_finding: {chapter, finding_id, severity, description, related_decision_id, related_files}
+    prior_output: path to the phase's previous artifact
+    decision_row: the row from decisions.jsonl containing original reasoning + authorship
+    cycle_number: current backward-routing cycle count for this target phase (from .build-state.json.backward_routing_count_by_target_phase)
+    downstream_phases_affected: list of phases that consume this phase's output (e.g., Phase 2 re-entry affects Phases 3, 4, 5, 6)
+  TASK for the re-opened phase:
+    Revise prior_output to address blocking_finding. Do NOT redo unaffected work. Emit a new decision_row documenting the revision rationale.
+```
+
+The orchestrator assembles this payload from `lrr-routing.json` + `decisions.jsonl` + the prior artifact path, then invokes the target phase's "on re-entry" branch (see Phase 2 Step 2.2, Phase 3, and Phase 4 implementer dispatches).
+
+<HARD-GATE>
+The LRR Aggregator is the ONLY agent that may emit `combined_verdict`. No other agent — not the orchestrator, not Reality Checker, not individual chapters — may self-issue a combined verdict. This is the non-negotiable independence guarantee.
+
+Max 2 NEEDS_WORK cycles. If LRR returns NEEDS_WORK a third time:
+  - Interactive: present all remaining issues. Ask for direction.
+  - Autonomous: log remaining issues. Proceed to Phase 7 with a warning in the Completion Report.
+Do not loop forever.
+</HARD-GATE>
+
+**Writes:** `docs/plans/evidence/lrr/*.json`, `docs/plans/evidence/lrr-aggregate.json`, `docs/plans/evidence/lrr-routing.json`.
+
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
+
+---
+
+## Phase 7: Ship
+
+**Pre-ship Verify gate:** Run the Verify Protocol (INTERNAL inline — "Verify scaffolding") before any Step 7.1 dispatch. All 7 checks (Build → Type-Check → Lint → Test → Security → Diff Review → Artifacts) must pass. If any check FAILS, dispatch a fix agent with the error, re-verify. Max 2 fix attempts. Do not proceed to Step 7.1 until PASS.
+
+**Mode-specific branch:**
+- `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 7 — ship pipeline is optional (simulator-only is a valid end-state). If shipping, run asc-* agents + fastlane.
+- `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 7 (Step 7.1 documentation + deploy notes).
+
+### Step 7.1 — Sequence: Documentation → Doc Metric Loop → ASO (iOS) → Deploy → Completion Report
+
+**CONTEXT header:** Render `rendered_context_header` for phase 7 per the canonical template (see CONTEXT HEADER HARD-GATE above). Prepend to every Phase 7 prompt below.
+
+1. Description: "Technical Writer" — subagent_type: `engineering-technical-writer` — mode: "bypassPermissions" — Prompt: "[CONTEXT header above] Write project docs: README with setup/architecture/usage, API docs if applicable, deployment notes. The README is the first thing a new developer reads — optimize for that reader. Commit: 'docs: project documentation'. Deployment target per the PRD (Vercel/Netlify/Railway/Fly.io/etc.) — include the deploy flow specific to that target in the README."
+
+2. Documentation Metric Loop: Run the Metric Loop Protocol (callable service) on documentation. Define a metric based on completeness and whether a new developer could follow the README end-to-end. Max 3 iterations.
+
+3. Description: "App Store Optimizer" (iOS only, conditional on ship) — subagent_type: `marketing-app-store-optimizer` — Prompt per `protocols/ios-phase-branches.md` §Phase 7 (asc-* flow — app name, subtitle, keywords, description, screenshots, privacy labels). Prepend CONTEXT header above. Skip entirely for web.
+
+4. Description: "Deploy" — subagent_type: `engineering-devops-automator` — mode: "bypassPermissions" — Prompt: "[CONTEXT header above] Deploy the app to the target from the PRD (`docs/plans/design-doc.md#tech-stack`). Run pre-deploy checks: build, env vars, secrets. Execute deploy. Verify the deployed URL returns 200 and serves the built app (not the placeholder). Report deploy URL and any smoke-test findings."
+
+5. Description: "Completion Report" — INTERNAL inline role-string — Prompt: "[CONTEXT header above] You are the Completion Report writer. Draw verification surface from THREE sources: the LRR Aggregator's structured output (`docs/plans/evidence/lrr-aggregate.json`), the Reality Checker evidence manifest (`docs/plans/evidence/reality-check-manifest.json`), and the build state (`docs/plans/.build-state.json` — for backward-routing counts and mode transitions per state-schema v2). Do NOT draw from orchestrator summary prose. Present:
 
 ```
 BUILD COMPLETE
 Project: [name] | Tasks: [done]/[total] | Tests: [count] passing
-Agents used: [list] | Verdict: [Reality Checker result]
+Agents used: [list distinct subagent_types] | Verdict: [combined_verdict from lrr-aggregate.json]
 Metric loops run: [count] | Avg iterations: [N]
-Remaining: [any NEEDS WORK items]
+Remaining: [any NEEDS WORK items from lrr-routing.json]
 ```
 
-Mark all TodoWrite items complete. Update `docs/plans/.build-state.md`: "Phase: 7 COMPLETE."
+**Verification table (MANDATORY — pulled from LRR aggregator output):**
+
+| Metric | Count | Status |
+|--------|-------|--------|
+| Behavioral Tests declared in spec | from sprint-tasks.md | — |
+| Behavioral Tests with non-stub bodies | from Eng-Quality findings | PASS if equal |
+| Behavioral evidence files written | count from manifest | — |
+| Maestro flows present (iOS) | count of maestro/*.yaml | — |
+| Test-stub detector flagged files | from Eng-Quality findings | PASS if 0 |
+| Combined verdict | from lrr-aggregate.json | — |
+| LRR chapter verdicts | list of chapter:verdict pairs | — |
+| LRR follow-ups spawned | count | — |
+| LRR triggered rule | rule number 1-6 | — |
+
+```
+QUALITY METRICS (from .build-state.json schema v2)
+================================================
+Backward routing: <total> events
+  by target phase: <\"2\": N, \"3\": N, \"4\": N>
+  top decisions re-opened: <decision_id: N> (up to 3)
+
+Mode transitions: <count> (autonomous ↔ interactive)
+<if count > 0: list each transition timestamp + direction>
+
+Interpretation:
+- Backward routing count is a quality signal — fewer means Phase 1-3 caught issues earlier.
+- A target phase appearing 3+ times suggests structural rework (re-architect or re-design); investigate the related decisions.
+- Mode transitions ≥ 2 in autonomous mode indicates the build hit a manual-review threshold — review the LRR rule that triggered.
+```
+
+If there's a Verification Gap (declared != passing, or stub-flagged > 0), surface a top-level 'Verification Gap' section BEFORE writing the report to disk. Ask user: 'Write Completion Report with this verification gap surfaced? [YES/NO]'. In autonomous mode: write but flag prominently.
+
+Create final commit. Mark all TodoWrite items complete. Update `.build-state.json`: 'Phase: 7 COMPLETE'."
+
+**Writes:** `docs/plans/learnings.jsonl` (late learnings only — doc friction, deploy blockers, late-surfacing gaps). If no late learnings surfaced, skip. Row schema: `{run_id, timestamp, project_type, phase_where_learning_surfaced: \"7.x\", metric, top_issue, fix_applied, score_delta, pattern_type}`.
+
+**Compaction checkpoint.** Update `.build-state.json` per the format above.