buildanything 1.7.1 → 2.0.0

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,105 @@ 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 listed in `docs/plans/agent-dispatch-audit.md` — they are orchestrator helpers (Brainstorm Facilitator, Research Synthesizer, Design Doc Writer, Prereq Collector, Task DAG Validator, Refs Indexer, Briefing Officer, Dogfood runner, Fake-Data Detector, 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 dispatch audit.
+</HARD-GATE>
+
+<HARD-GATE>
+ARTIFACT WRITER-OWNER RULE.
+
+Every shared artifact has ONE concurrent writer at any instant. The writer-owner table in `docs/plans/orchestration-proposed-state.md` §6 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)
+  - `design-doc.md` (PRD)    — P1 writer
+  - `architecture.md`        — P2 writer
+  - `sprint-tasks.md`        — P2 writer
+  - `quality-targets.json`   — P2 writer
+  - `visual-design-spec.md`  — P3 writer (web) / `ios-design-board.md` P3 writer (iOS)
+  - `refs.json`              — P2 writer + P3 writer (P3 extends after visual spec lands)
+  - `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)
+  - `learnings.jsonl`        — P5, P7 writers
+  - `evidence/*.json`        — P5 writer (P4 contributes per-task, P6/P7 readers)
+  - `lrr/*.json`             — P6 writer (1 per chapter + Aggregator)
+  - `lrr-aggregate.json`     — P6 writer (Aggregator only)
+
+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 Phase 2 dispatch.
+</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 `visual-dna.md` 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 docs/plans/visual-dna.md — 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 `docs/plans/visual-dna.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 `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.
+**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.
+
+**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,608 +119,968 @@ 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.
+
+### Metric Loop (callable service)
 
-Every phase uses a **metric-driven iteration loop** to drive quality. Read the full protocol at `protocols/metric-loop.md`. Critical rules (survive compaction):
+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 (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.
+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.
 
-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:
+### Learnings (callable service)
 
-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
+`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.
 
-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.
+### Refs-Not-Pastes Rule
+
+For Phase 3+ agents, the orchestrator passes REFS to live downstream docs (`design-doc.md`, `architecture.md`, `visual-design-spec.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 `visual-design-spec.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)
 
 Tag agent prompts with `[COMPLEXITY: S/M/L]` based on task size from `docs/plans/sprint-tasks.md`. This is advisory — the tag documents intent for future model routing support.
 
+### Mode-Specific Tool Stacks
+
+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 5 Audit (code issue)      →   Phase 4 target task
+Phase 5 Audit (design issue)    →   Phase 3 target step
+Phase 5 Audit (spec issue)      →   Phase 2 re-architect
+Phase 6 LRR BLOCK (⭐⭐)         →   Aggregator reads decisions.jsonl
+                                     by related_decision_id →
+                                     authoring phase → re-open
+Phase 6 LRR NEEDS_WORK (code)   →   Phase 4 target task
+Phase 6 LRR NEEDS_WORK (struct) →   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 → Phase N re-open, Reality Checker BLOCK → Phase M re-entry, Gate "no" → 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`, `docs/plans/visual-design-spec.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 MVP 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. |
 
-### Step 0.2 — Human Prerequisites Checklist
+### Step 0.1b — Project Type Classification (iOS vs Web)
 
-Identify everything that requires HUMAN action before going heads-down:
+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**.
 
-- **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.
+| 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.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` |
 
-Present the checklist:
+**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`.
 
-```
-BEFORE I GO HEADS-DOWN, please set up:
+**Conditional branch-file load:**
+- `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.
+
+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.
+
+**Mode-specific additions to Phase 0:** See `protocols/ios-phase-branches.md` §Phase 0 additions (iOS only).
+
+### Step 0.1d — Learnings Loader (PITFALL replay)
 
-[ ] [Service] API key → add as [KEY_NAME] to .env
-[ ] [Database] → add connection URL to .env
-[ ] GitHub repo → share the URL
-[ ] [Deployment service] connected (optional)
+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.
 
-Once done, say "ready" and I'll start building.
+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:
+
+```markdown
+## Prior Learnings (top 3 relevant)
+
+- **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 }`. 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.
+
+iOS structural changes are out of scope for this orchestrator migration (per proposed-state §7).
+
+**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.
 
-### Step 1.1 — Brainstorming
+**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.
 
-Follow the Brainstorm Protocol (`protocols/brainstorm.md`).
+**Mode-specific branch:**
+- `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.
 
-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/`.
+### Step 1.0 — INITIAL BRAINSTORM
 
-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`.
+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.
 
-### Step 1.2 — Parallel Research (5 agents, ONE message)
+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."
+
+**Autonomous mode:** facilitator synthesizes directly from build request + available context without asking questions. Logs rationale to `docs/plans/build-log.md`.
+
+**Returns:** `docs/plans/phase1-scratch/idea-draft.md`
+
+### 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, MVP scope, 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
+
+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`
 
-Structure:
+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 — MVP features (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 MVP 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?"
+
+<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>
+
+**Autonomous:** Log design-doc path + digest path to `docs/plans/build-log.md`. Auto-approve. Proceed.
 
-**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>
+Update TodoWrite and `.build-state.json`.
 
-Update TodoWrite and `docs/plans/.build-state.md`.
+### Step 1.5 — PREREQ COLLECTOR (post-Gate 1)
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+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.
 
 ---
 
-## 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).
 
-### Step 2.1 — Explore (existing codebase only)
+**Mode-specific branch:**
+- `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.
 
-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."
+### Step 2.1 — Explore existing codebase (only if existing code)
+
+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.
 
-Read the Design Document and Research Brief. Pass both to every agent.
+**Step 2.2a — Create the team.**
 
-Call the Agent tool 4 times in a single message:
+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.
 
-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.2b — Dispatch 6 architects as teammates (ONE message).**
 
-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."
+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.
 
-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."
+Shared brief appended to every architect prompt:
 
-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."
+```
+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)
+
+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.
+```
 
-After all 4 return, YOU synthesize into one Architecture Document. Save to `docs/plans/architecture.md`.
+Per-architect dispatches:
 
-### Step 2.3 — Metric Loop: Architecture Quality
+**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.
 
-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.
 
-### Step 2.4 — Sprint Planning
+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  - 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.\n\n[paste shared team brief above]"
 
-Follow the Planning Protocol (`protocols/planning.md`). Use 2 sequential Agent tool calls:
+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  - 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.\n\n[paste shared team brief above]"
 
-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."
+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  - 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.\n\n[paste shared team brief above]"
 
-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."
+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  - DIGEST: `docs/plans/phase1-scratch/findings-digest.md`\nCover auth model, input validation, secrets management, threat model, dependency hygiene. Note: no raw research file routed — digest only (security architecture is a cross-cutting concern).\n\n[paste shared team brief above]"
 
-Save to `docs/plans/sprint-tasks.md`.
+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  - 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.\n\n[paste shared team brief above]"
+
+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  - 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 from `orchestration-proposed-state.md` §11: Marketing 500KB / Product 300KB / Dashboard 400KB / Internal 200KB gzipped.\n\n[paste shared team brief above]"
+
+**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.
+
+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.
+
+**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.
+
+### Step 2.3 — Sequence: Implementation Blueprint → Sprint Breakdown → DAG Validator → Refs Indexer
+
+Four sequential dispatches.
+
+**CONTEXT header:** Reuse `rendered_context_header` from phase 2 (already rendered above). Prepend to Step 2.3 synthesizer + sprint-breakdown prompts.
+
+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 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, not adjudicate. 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, MVP Scope, Out of Scope. Scope to MVP boundary from the PRD."
+
+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. Read these files via your Read tool before starting:\n  - ARCHITECTURE: `docs/plans/architecture.md`\n  - PRD: `docs/plans/design-doc.md`\nScope to MVP only. Save to `docs/plans/sprint-tasks.md`. Dependencies field is load-bearing — Phase 4 uses it to batch independent tasks in parallel."
+
+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."
+
+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`
+  - `docs/plans/visual-design-spec.md` (if it exists yet — Phase 3 extends refs.json after it writes this file)
+
+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."
+
+**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.
+
+**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?"
+
+<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>
+
+**Autonomous:** Log to `docs/plans/build-log.md`. Auto-approve. Proceed.
 
-**Interactive:** Present Architecture + Sprint Task List. Ask: "Approve to start building, or flag changes?" <HARD-GATE>DO NOT PROCEED without user approval.</HARD-GATE>
+Update TodoWrite and `.build-state.json`.
 
-Update TodoWrite and `docs/plans/.build-state.md`.
+**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, proven with Playwright screenshots. Fully autonomous — agents research, decide, and iterate without user input.
+**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. The agents must research real competitors and award-winning sites, make deliberate visual choices backed by that research, build a living style guide with every component rendered and interactive, and iterate with Playwright-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 `docs/plans/visual-design-spec.md`. If it does not exist, return here.
+Phase 4 WILL NOT START without `docs/plans/visual-design-spec.md` (web) or `docs/plans/ios-design-board.md` (iOS). If the artifact does not exist, return here.
 </HARD-GATE>
 
-### Step 3.1 — Design Research (2 agents, parallel, both use Playwright)
+**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 `orchestration-proposed-state.md` §11 for the component library strategy.
 
-Follow the Design Protocol (`protocols/design.md`), Step 3.1.
+**Phase 3 write discipline:** Phase 3 is the writer for `docs/plans/visual-design-spec.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.
 
-Call the Agent tool 2 times in one message:
+<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>
 
-1. Description: "Competitive visual audit" — Prompt: "Research the top 5-8 competitors/analogues for: [product description]. Use Playwright to screenshot each site (desktop 1920x1080 + mobile 375x812). Screenshot standout components (hero, cards, forms, nav, CTAs). Save to docs/plans/design-references/competitors/. Analyze visual language: colors, typography, spacing, what feels premium vs cheap. Rank by visual quality. DESIGN DOC: [paste]."
+**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: "docs/plans/visual-design-spec.md" or "docs/plans/visual-dna.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 — DNA lock, component manifest, or visual spec — 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.
 
-2. Description: "Design inspiration mining" — Prompt: "Search Awwwards.com, Godly.website, SiteInspire for award-winning sites in category: [product category]. Use Playwright to screenshot top 5-8 results + standout components. Save to docs/plans/design-references/inspiration/. Identify visual trends, what separates best-in-class from generic. DESIGN DOC: [paste]."
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
 
-After both return, synthesize a **Design Research Brief** to `docs/plans/design-research.md`. Include all screenshot paths.
+---
 
-### Step 3.2 — Design Direction (2 agents, sequential)
+## Phase 4: Build — PARALLEL BATCHES by task dependencies
 
-Follow the Design Protocol (`protocols/design.md`), Step 3.2.
+<HARD-GATE>
+Before starting Phase 4: Phase 2 must be approved, Phase 3 must have produced the design artifact for this mode (`visual-design-spec.md` web / `ios-design-board.md` iOS). You MUST call the Agent tool for EVERY task. No exceptions.
+</HARD-GATE>
 
-1. Call the Agent tool — description: "UX architecture" — Prompt: "Create structural design foundation. INPUTS: frontend architecture section from architecture.md [paste], Design Research Brief [paste], reference screenshot paths [list], user persona [paste]. OUTPUT: information architecture, layout strategy, component hierarchy, responsive approach, interaction patterns. Base decisions on competitive research, not generic patterns."
+**Goal**: Scaffold project + execute sprint tasks in dependency-ordered batches. Independent sibling tasks run in parallel (~30-50% wall-clock saving on typical sprint).
 
-2. Call the Agent tool — description: "Visual design spec" — Prompt: "Create the Visual Design Spec with AUTONOMOUS decisions — pick the single best direction, do not present options. INPUTS: UX foundation [paste previous output], Design Research Brief [paste], reference screenshot paths [list], user persona [paste]. OUTPUT: color system (with hex, light+dark), typography (Google Fonts, mathematical scale), 8px spacing system, tinted shadow system, border radius, animation/motion, component styles with ALL states. Every choice must cite the research. Apply anti-AI-template rules from the Design Protocol. Save to docs/plans/visual-design-spec.md."
+**Mode-specific branch:**
+- `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).
+- `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 4 (web project scaffolding, CSS design system tokens, Playwright acceptance test stubs).
 
-### Step 3.3 — Living Style Guide (1 implementation agent)
+### Step 4.0 — Scaffold (old Phase 4 Foundation merged here)
 
-Follow the Design Protocol (`protocols/design.md`), Step 3.3.
+Scaffolding is project skeleton + design system + acceptance test stubs. Three sequential dispatches (full details in the mode-specific branch file):
 
-Call the Agent tool — description: "Build living style guide" — mode: "bypassPermissions" — prompt: "[COMPLEXITY: L] Build a living style guide page (/design-system route or standalone HTML). INPUTS: Visual Design Spec [paste], UX foundation [paste relevant sections], reference screenshots [list paths — these are your quality targets]. Must include rendered, interactive examples of: color swatches, typography scale, spacing scale, buttons (all states), form elements (all states), cards, navigation, feedback components (alerts, toasts, spinners, empty states), modals/overlays, and layout grid examples. Every component interactive (hover, focus, transitions work). Mobile-responsive. This ships with the product. Commit: 'feat: living style guide'."
+**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 scaffold prompt below; branch files do the same for per-task flow.
 
-### Step 3.4 — Visual QA Loop (Playwright + Metric Loop)
+1. Description: "Project scaffolding" — subagent_type: `engineering-rapid-prototyper` — mode: "bypassPermissions" — prompt per branch file (web: Next.js/Vite/etc; iOS: Xcode project from bootstrap). Prepend CONTEXT header above. [COMPLEXITY: M]
 
-Run the Metric Loop Protocol (`protocols/metric-loop.md`) using the measurement criteria from the Design Protocol (`protocols/design.md`, Step 3.4).
+2. Description: "Design system setup" — subagent_type: `engineering-frontend-developer` — mode: "bypassPermissions" — prompt per branch file. Prepend CONTEXT header above. Implements design tokens from `visual-design-spec.md` or `ios-design-board.md`. The living style guide from Phase 3 is the reference implementation — components must match. [COMPLEXITY: M]
 
-Measurement: Playwright screenshots of the living style guide sections (desktop + mobile). Design critic agent scores 0-100 across 6 dimensions: spacing/alignment, typography hierarchy, color harmony, component polish, responsive quality, originality (anti-AI-template check). Receives screenshots + Visual Design Spec + reference screenshots.
+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. Read `docs/plans/sprint-tasks.md`. For every task with a Behavioral Test field, create a Playwright test stub (web) or Maestro flow stub (iOS). Each stub: navigate → interact → assert. Stubs must FAIL right now (features aren't built yet) — that's correct. Commit: 'test: scaffold acceptance tests from sprint tasks'."
 
-**Target: 80. Max 5 iterations.** On stall: accept if >= 65, log warning below 65.
+**Scaffold verification:** Run the Verify Protocol (INTERNAL inline — "Verify scaffolding") — 7 checks sequentially, stop on first FAIL. Do not proceed to Step 4.1 until PASS.
 
-### Step 3.5 — Autonomous Quality Gate
+### Step 4.1+ — Task execution in dependency-ordered batches
 
-Log to `docs/plans/build-log.md`: final screenshot paths, score history table, design decisions, originality score. No user pause. Proceed to Phase 4.
+Expand TodoWrite with each sprint task.
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+Build a DAG from `sprint-tasks.md` Dependencies fields. Execute in batches: the next batch is the set of all tasks whose dependencies are all complete. Dispatch each batch as parallel Agent tool calls in ONE message.
 
----
+**Per-task flow (runs for every task in every batch):**
 
-## Phase 4: Foundation
+#### Briefing Officer (INTERNAL inline)
 
-<HARD-GATE>
-Before starting Phase 4: Phase 2 must be approved AND Phase 3 must have produced `docs/plans/visual-design-spec.md`.
-If visual-design-spec.md does not exist, DO NOT PROCEED. Return to Phase 3.
-Step 4.2 (Design System) MUST implement from visual-design-spec.md — not generic architecture tokens.
-</HARD-GATE>
+Dispatch before every implementer. Assembles a compact <40-line context map that tells the implementer EXACTLY where to look for each kind of context. Refs not pastes.
+
+Call the Agent tool — description: "Briefing for [task name]" — INTERNAL inline role-string — prompt: "You are the Briefing Officer. Read `docs/plans/refs.json` and the task row for [task-id] from `docs/plans/sprint-tasks.md`. Build a compact context map (~40 lines max) in this exact shape:
 
-### Step 4.1 — Scaffolding
+```
+CONTEXT MAP — [task-id] [task name]
+  persona / JTBD     → design-doc.md#persona
+  product scope      → design-doc.md#scope
+  visual tokens      → visual-design-spec.md#tokens
+  component variants → component-manifest.md#[category]
+  auth model         → architecture.md#auth
+  data schema        → architecture.md#data-model
+  sibling task deps  → sprint-tasks.md#[dep-id-1], #[dep-id-2]
+  prior decisions    → decisions.jsonl rows [row-id-1], [row-id-2]
+  quality targets    → quality-targets.json (full file)
+```
 
-Call the Agent tool — description: "Project scaffolding" — mode: "bypassPermissions" — prompt: "[COMPLEXITY: M] Set up the project from this architecture: [paste]. Create directory structure, dependencies, build tooling, linting config, test framework with one passing test, .gitignore, .env.example. Commit: 'feat: initial scaffolding'."
+CLAUDE.md is NOT in the map — it auto-loads into every subagent. Raw Phase 1 research is NOT in the map — it is SPENT. The implementer reads refs on-demand using the Read tool; no full pastes."
 
-### Step 4.2 — Design System (frontend only)
+The Briefing Officer's output is the handoff payload for the implementer — not for the orchestrator to re-paste.
 
-Call the Agent tool — description: "Design system setup" — mode: "bypassPermissions" — prompt: "Implement the design system from the Visual Design Spec: [paste from docs/plans/visual-design-spec.md]. Create CSS tokens matching the spec's color system, typography scale, spacing system, shadow/elevation tokens, and base layout components. The living style guide from Phase 3 is the reference implementation — components must match. Commit: 'feat: design system'."
+#### Implementer dispatch (subagent_type by task type)
 
-### Step 4.2b — Acceptance Test Scaffolding
+Dispatch by task type and complexity:
+- UI tasks: `subagent_type: engineering-frontend-developer` (S/M) or `subagent_type: engineering-senior-developer` (L)
+- Backend tasks: `subagent_type: engineering-backend-architect` (L) or `subagent_type: engineering-senior-developer` (M)
+- Hard / complex / cross-cutting tasks: `subagent_type: engineering-senior-developer`
 
-Call the Agent tool — description: "Scaffold acceptance tests" — mode: "bypassPermissions" — prompt: "Read docs/plans/sprint-tasks.md. For every task with a Behavioral Test field, create a Playwright test stub in tests/e2e/acceptance/. Use Page Object Model. Each test should: navigate to the page, perform the interaction, assert the expected outcome. Tests should FAIL right now (features aren't built yet) — that's correct. Also ensure agent-browser is available (run `which agent-browser`). Commit: 'test: scaffold acceptance tests from sprint tasks'."
+Call the Agent tool — description: "[task-id] [task name]" — subagent_type per above — mode: "bypassPermissions" — prompt: "[CONTEXT header above] [COMPLEXITY: S/M/L from sprint-tasks.md]. TASK: [task description + acceptance criteria from sprint-tasks.md]. Sprint context is prepended; focus on this task.
 
-### Step 4.3 — Metric Loop: Scaffold Health
+## Prior Learnings
+[paste contents of `docs/plans/.active-learnings.md` if it exists, otherwise omit this section]
 
-Run the Metric Loop Protocol. Define a metric: builds clean, tests pass, lint clean, structure matches architecture. Max 3 iterations.
+## 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.
 
-### Step 4.4 — Verification Gate
+Implement fully with real code and tests. Commit: 'feat: [task]'. Report what you built, files changed, and test results.
 
-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.
+## On Re-entry (from LRR backward routing)
+**[ORCHESTRATOR: Include the "On Re-entry" section below ONLY when this is a re-entry dispatch from LRR backward routing. For normal Phase 4 execution, OMIT it.]**
 
-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."
+If this dispatch is a re-entry (the orchestrator passes `blocking_finding`, `prior_output`, and `decision_row` in the prompt), DO NOT treat this as a fresh task. Read `prior_output` (the path to your previous task artifact under `.task-outputs/[task-id].json` + changed files) and `decision_row` (the original deviation rationale from decisions.jsonl). Revise ONLY what `blocking_finding` requires — do not redo unaffected code, do not re-run acceptance tests that already passed, do not touch files outside the blast radius of the finding. Return a fresh `deviation_row` in your result payload documenting the revision rationale (author=this task-id, type and summary describing the revision)."
 
-Do not proceed to Phase 5 until verification passes.
+#### Per-task security review (auth/PII tasks only)
 
-Update TodoWrite and state.
+FOR tasks touching auth, PII, secrets, or payment flows — add a per-task security review BEFORE Senior Dev cleanup:
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+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]."
 
----
+#### Senior Dev cleanup (simplifier + refactor-cleaner if TS)
+
+Two-pass cleanup. Scope is sacred: ONLY files from the implementation changeset. Zero exceptions.
+
+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. If simplification breaks acceptance criteria, revert and skip. 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]. Remove orphaned exports, unused deps, dead files. Same scope rules as simplifier — changeset only. Files: [list]."
+
+Skip cleanup if trivial (< 20 lines, single file).
+
+#### Per-task code review (parallel pair)
+
+Call the Agent tool 2 times in one message after Senior Dev cleanup:
+
+1. Description: "Code review for [task-id]" — subagent_type: `code-reviewer` — Prompt: "[CONTEXT header above] Review changed files from [task-id]. Report findings with 80%+ confidence threshold only — skip low-confidence nitpicks. Scope: changeset only. Acceptance criteria: [paste from task]. 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]. Targets: empty catch blocks, try/catch returning null, swallowed errors, unhandled promise rejections, assertions disabled in production. Files: [list]. Report blocking findings only."
+
+#### Metric Loop (generator/critic) — authoritative behavioral check
+
+Run the Metric Loop Protocol (callable service) 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.
+
+The metric loop's final measurement IS the authoritative behavioral verification for this task — no separate smoke-test dispatch. The critic's final score + pass/fail is what downstream steps consume.
+
+Generator: same implementer agent re-invoked. Critic: measurement agent dispatched fresh. Never share context.
+
+On target met: mark task complete. On stall: accept if score >= 60% of target (autonomous) or present to user (interactive).
+
+#### Verify Service (static checks only)
 
-## Phase 5: Build — Metric-Driven Dev Loops
+Run the Verify Protocol (INTERNAL inline — "Verify scaffolding") after the metric loop exits. Verify now covers STATIC checks only: type-check, lint, build. Behavioral verification has already happened in the metric loop above — verify consumes the metric loop's final pass/fail + score from `.build-state.json.metric_loop_scores[]` rather than re-running behavioral checks. If any static check FAILS, dispatch a fix agent with the error, re-verify. Max 3 fix attempts.
+
+#### After each task completes
+
+Update TodoWrite and `.build-state.json`. Write a compact summary to `docs/plans/.task-outputs/[task-id].json` with {files-changed, tests-passing, verify-status}.
+
+**Writes:** source code, `docs/plans/.task-outputs/`. Deviation rows flow through the orchestrator's `scribe_decision` MCP calls below — implementers do NOT touch `decisions.jsonl`.
 
 <HARD-GATE>
-Before starting: Phase 2 must be approved, Phase 3 must produce docs/plans/visual-design-spec.md, Phase 4 must pass. You MUST call the Agent tool for EVERY task. No exceptions.
+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>
 
-Expand TodoWrite with each sprint task.
+#### Orchestrator-scribe dispatch (route deviation rows through `scribe_decision` MCP)
 
-**For EACH task:**
+Runs after every Phase 4 parallel batch returns (and anywhere else a subagent returns a `deviation_row`, including Phase 1 synthesis and Phase 2 architecture synthesis). The scribe MCP is the single writer for `docs/plans/decisions.jsonl`; the orchestrator is the single caller of the MCP.
 
-### Step 5.1 — Implement
+1. Walk `batch_results`. Collect every non-null `deviation_row` from each subagent return.
+2. For each row, invoke the `scribe_decision` MCP tool with the row's fields (`phase`, `category`/`type`, `summary`, `decided_by`/`author`, `impact_level`, `rationale`, `related_files`) per the MCP's documented schema. One MCP call per row.
+3. The MCP allocates the `decision_id` (`D-{N}-<seq>`), stamps `timestamp` (ISO-8601) and `status: "open"`, validates against `decisions.schema.json`, and atomically appends the line. The orchestrator MUST NOT Write or Edit `docs/plans/decisions.jsonl` directly, MUST NOT pre-compute decision IDs, and MUST NOT read or allocate `.build-state.json.decisions_next_id.P{N}` — ID allocation is the MCP's responsibility.
+4. Regenerate `.build-state.md` after the batch completes so the rendered view reflects the newly appended rows.
 
-Call the Agent tool — description: "[task name]" — mode: "bypassPermissions" — prompt: "TASK: [task description + acceptance criteria]. HANDOFF — Architecture section: [paste ONLY the relevant section from architecture.md]. Design section: [paste ONLY the relevant section from the design doc]. Previous task output: [what the last completed task produced, if relevant]. For UI tasks: the living style guide at /design-system shows every component's exact styling and states — match it. Implement fully with real code and tests. Commit: 'feat: [task]'. Report what you built, files changed, and test results."
+**On resume:** the scribe MCP reconstructs its ID allocator internally on first invocation by scanning `docs/plans/decisions.jsonl` (for each phase `N`, `max(seq)+1` across rows whose `decision_id` matches `D-{N}-<seq>`). The orchestrator no longer maintains `decisions_next_id` in `.build-state.json`; the field is effectively deprecated under Stage 2 (scribe owns ID allocation end-to-end) and is scheduled for formal removal in Stage 4 schema bump A7 (see Task 4.5.1 in `docs/migration/sdk-hybrid/TASK-BREAKDOWN.md`). TODO(stage-4-A7): drop `decisions_next_id` from the state schema.
 
-Pick the right developer framing: frontend, backend, AI, etc. Set `[COMPLEXITY: S/M/L]` based on the task's Size from sprint-tasks.md.
+<HARD-GATE>
+LRR NEEDS_WORK backward edge: `LRR NEEDS_WORK (code-level) → back to Phase 4 target task`. The Aggregator classifies the finding and routes to the specific task via `related_decision_id` lookup; Phase 4 re-opens that task with the finding as input.
+</HARD-GATE>
 
-### Step 5.1b — Cleanup (De-Sloppify)
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
 
-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.
+---
 
-Call the Agent tool — description: "Cleanup [task name]" — mode: "bypassPermissions" — with the list of files changed and the task's acceptance criteria.
+## Phase 5: Audit — TEAM of 6 + eval harness + 3 parallel + feedback synth
 
-### Step 5.2 — Metric Loop: Task Quality
+<HARD-GATE>
+Before starting Phase 5: run the Verify Protocol (7 checks) one more time. All checks must pass before expensive audit agents fire.
+</HARD-GATE>
 
-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: the measurement agent should use agent-browser to verify the feature renders and responds to interaction, not just read the code. Max 5 iterations.
+**Goal**: Surface quality issues before Launch Review. Split from old Phase 6 — old 6.1-6.3 (5-agent audit, eval harness, E2E + dogfood + fake-data) live here. Old 6.4-6.5 (Reality Check + LRR) move to Phase 6.
 
-### Step 5.3 — Loop Exit
+**Mode-specific branch:**
+- `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 5 (iOS twin commands: `/buildanything:verify` → `/buildanything:ux-review` → `/buildanything:fix` in sequence; Maestro smoke tests). Skip the web TEAM below and jump to Step 5.4 Feedback Synthesizer with iOS evidence.
+- `project_type=web`: continue below.
 
-On target met: mark task complete in TodoWrite, report "Task X/N: [name] — COMPLETE (score: [final], iterations: [count])".
+### Step 5.1 — TEAM of 6 parallel auditors (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`.
+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.
 
-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 Phase 5 prompt below.
 
-### Step 5.3b — Behavioral Smoke Test
+Call the Agent tool 6 times in one message:
 
-Skip if this task has no Behavioral Test criteria (API-only, config, infrastructure tasks).
+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."
 
-Run the Smoke Test Protocol (`protocols/smoke-test.md`). This uses agent-browser to open the app, execute the task's behavioral acceptance criteria, and verify the feature actually works.
+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."
 
-Evidence saved to `docs/plans/evidence/[task-name]/`: annotated screenshot, snapshot diff, error log, network log, HAR file.
+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)."
 
-On FAIL: spawn fix agent with the evidence. The fix agent receives: what was expected (from acceptance criteria), what actually happened (snapshot diff + errors + screenshot), and the relevant source files. Max 2 fix-and-retest cycles.
+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."
 
-On PASS: proceed to Step 5.4.
+5. Description: "UX quality audit" — subagent_type: `design-ux-researcher` — Prompt: "[CONTEXT header above] UX quality review of every user-facing page. First, screenshot the living style guide at /design-system (web) as your reference. Then review every product page: loading states (every async action shows a loading indicator), error states (every form and API call shows user-friendly feedback), empty states (lists/tables handle zero items), mobile responsiveness (test at 375px — touch targets >= 44px, no horizontal scroll), form validation (inline feedback, not alert()), transition smoothness, visual consistency vs style guide (buttons, inputs, cards, colors, spacing should match). Report issues with page, severity, and screenshot."
 
-### Step 5.4 — Post-Task Verification
+6. Description: "Brand Guardian drift check" — subagent_type: `design-brand-guardian` — Prompt: "[CONTEXT header above] You are the Phase 5 drift check. Read docs/plans/visual-dna.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."
 
-Run the Verification Protocol (`protocols/verify.md`). If FAIL, fix before starting the next task.
+### Step 5.2 — Sequence: Eval Harness → Metric Loop
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+Run the Eval Harness Protocol (`protocols/eval-harness.md`). Define 8-15 concrete, executable eval cases from the audit findings and architecture doc. Run the eval agent. Record baseline pass rate. CRITICAL and HIGH failures feed into the Metric Loop as specific issues to fix.
 
----
+Run the Metric Loop Protocol (callable service) on the full codebase using audit findings as initial input. Define a composite metric based on what this project needs. Max 4 iterations. When fixing, dispatch to the RIGHT specialist — security → `security-reviewer`, a11y → `engineering-frontend-developer`, perf → `testing-performance-benchmarker`. Don't send everything to one agent.
 
-## Phase 6: Harden — Metric-Driven Hardening
+Re-run the Eval Harness after the metric loop exits. All CRITICAL eval cases must now pass. If any CRITICAL case still fails, include it as evidence for Phase 6.
 
-### Step 6.0 — Pre-Hardening Verification
+### Step 5.3 — TEAM of 3 parallel (ONE message)
 
-Run the Verification Protocol (`protocols/verify.md`). All checks must pass before starting expensive audit agents.
+Call the Agent tool 3 times in one message:
 
-### Step 6.1 — Initial Audit (5 agents in parallel, 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`."
 
-Read the NFRs from `docs/plans/sprint-tasks.md`. Pass the relevant NFR thresholds to each audit agent so they have concrete targets, not generic checks.
+2. Description: "Dogfood the app" — INTERNAL inline role-string + agent-browser skill — mode: "bypassPermissions" — Prompt: "You are the Dogfood runner. Run the agent-browser dogfood skill against the running app at http://localhost:[port]. Explore every reachable page. Click every button. Fill every form. Check console for errors. Report a structured list of issues with severity ratings, screenshots, repro steps. Write findings to `docs/plans/evidence/dogfood/findings.md`. Do NOT classify or route findings — that's the Feedback Synthesizer's job at Step 5.4."
 
-Call the Agent tool 5 times in one message:
+3. Description: "Fake-data detector" — INTERNAL inline role-string — 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."
 
-1. Description: "API testing" — Prompt: "Comprehensive API validation: all endpoints, edge cases, error responses, auth flows. NFR targets: [paste performance and reliability NFRs]. Report findings with counts."
+### Step 5.4 — Feedback Synthesizer
 
-2. Description: "Performance audit" — Prompt: "Measure response times, identify bottlenecks, flag performance issues. NFR targets: [paste performance NFRs — e.g., API < 200ms, page load < 3s]. Report benchmarks AGAINST these targets."
+The Dogfood findings used to dead-end. Now route them to fix loops.
 
-3. Description: "Accessibility audit" — Prompt: "WCAG compliance audit on all interfaces. NFR target: [paste accessibility NFR — e.g., WCAG AA]. Check screen reader, keyboard nav, contrast. Report issues with counts."
+Call the Agent tool — description: "Synthesize dogfood findings" — subagent_type: `product-feedback-synthesizer` — Prompt: "[CONTEXT header above] Interpret Dogfood output. Input: `docs/plans/evidence/dogfood/findings.md`. For each finding, classify it and assign a target phase for the fix:
+  - 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
 
-4. Description: "Security audit" — Prompt: "Security review: auth, input validation, data exposure, dependency vulnerabilities. NFR targets: [paste security NFRs]. Report findings with severity."
+Output: `docs/plans/evidence/dogfood/classified-findings.json` with shape `[{finding_id, severity, target_phase, target_task_or_step, description, evidence_ref}, ...]`. This file is read by the Phase 5 fix loop and by the Phase 6 LRR Aggregator for backward routing."
 
-5. Description: "UX quality audit" — Prompt: "UX quality review of every user-facing page. NFR targets: [paste accessibility NFRs]. First, screenshot the living style guide at /design-system as your reference for how components should look. Then review every product page and check: loading states (every async action must show a loading indicator), error states (every form and API call must show user-friendly error feedback), empty states (every list/table must handle zero items gracefully), mobile responsiveness (test at 375px viewport — touch targets >= 44px, no horizontal scroll, readable text), form validation (inline feedback, not just alert()), transition smoothness (no layout shifts, no janky animations), visual consistency (compare each page's components against the style guide — buttons, inputs, cards, colors, spacing should match). Report issues with page, severity, and screenshot."
+**Phase 5 fix loop:** For each CRITICAL/HIGH classified finding, dispatch the appropriate fix agent based on `target_phase`. Max 2 fix cycles.
 
-### Step 6.1b — Eval Harness
+**Writes:** `docs/plans/evidence/*.json`, `docs/plans/evidence/fake-data-audit.md`, `docs/plans/evidence/dogfood/classified-findings.json`, `docs/plans/learnings.jsonl` (reality sweep writes PITFALL/PATTERN rows — see `protocols/decision-log.md` for the Dissent Log Revisit Pass path).
 
-Run the Eval Harness Protocol (`protocols/eval-harness.md`). Define 8-15 concrete, executable eval cases from the audit findings and architecture doc. For UI flows, eval cases should use agent-browser: "agent-browser open /dashboard -> agent-browser click @submit -> agent-browser wait --text Success -> expect text contains confirmation ID". Run the eval agent. Record baseline pass rate. CRITICAL and HIGH failures feed into the metric loop in Step 6.2 as specific issues to fix.
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
 
-### Step 6.2 — Metric Loop: Hardening Quality
+---
 
-Run the Metric Loop Protocol on the full codebase using audit findings as initial input. Define a composite metric based on what this project needs. Max 4 iterations.
+## Phase 6: Launch Readiness Review
 
-When fixing, dispatch to the RIGHT specialist. Security → security agent. Accessibility → frontend agent. Don't send everything to one agent.
+**Goal**: 5 independent chapter judges + mechanical aggregator with file-completeness checkpoint + author-aware backward routing on BLOCK.
 
-### Step 6.2b — Eval Re-run
+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.
 
-Re-run the Eval Harness after the metric loop exits. All CRITICAL eval cases must now pass. If any CRITICAL case still fails, include it as evidence for the Reality Checker.
+### Step 6.0 — Reality Check (evidence sweep + dissent log revisit pass)
 
-### Step 6.2c — E2E Testing (3 mandatory iterations)
+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>
-ALL 3 ITERATIONS ARE MANDATORY. Do NOT stop after iteration 1 even if all tests pass. The purpose of 3 runs is to catch flaky tests, timing-dependent failures, and race conditions that only surface on repeated execution. Skip this step ONLY if the project has no user-facing frontend.
+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/eval-harness/baseline.json` (non-empty)
+  - `docs/plans/evidence/eval-harness/final.json` (non-empty)
+  - `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/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>
 
-Generate and execute end-to-end tests using Playwright against the running application. Tests cover the **User Journeys** defined in `docs/plans/sprint-tasks.md` (Step 0 of the Planning Protocol). Each journey = one E2E test file.
+**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).
 
-**Iteration 1 — Generate & Run:**
+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').
 
-Call the Agent tool — description: "E2E test generation" — mode: "bypassPermissions" — prompt:
+Evidence paths to verify: [orchestrator pastes the precondition list per project_type].
 
-"[COMPLEXITY: L] Generate and run end-to-end Playwright tests for this application.
+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.
 
-INPUTS:
-- User Journeys from docs/plans/sprint-tasks.md: [paste the User Journeys section — each journey becomes one E2E test]
-- Architecture doc (API contracts): [paste relevant sections from docs/plans/architecture.md]
-- NFRs from docs/plans/sprint-tasks.md: [paste — use performance thresholds as test assertions]
-- Visual Design Spec (component selectors): [paste relevant sections from docs/plans/visual-design-spec.md]
+For every architecture MUST in `docs/plans/architecture.md`, verify the implementation file exists via Glob AND contains the named symbol via Grep.
 
-REQUIREMENTS:
-1. One E2E test per User Journey from sprint-tasks.md (each journey = one test file covering the full flow)
-2. Use Page Object Model pattern — one page object per major view
-3. Use data-testid selectors (add them to components if missing)
-4. Wait for API responses, NEVER use arbitrary timeouts (no waitForTimeout)
-5. Capture screenshots at critical verification points
-6. Configure multi-browser: Chromium + Firefox + WebKit
-7. Set up playwright.config.ts with: fullyParallel, retries: 0 (we handle retries ourselves), screenshot: 'only-on-failure', video: 'retain-on-failure', trace: 'on-first-retry'
-8. Run all tests. Report: total, passed, failed, with failure details and screenshot paths.
-9. Commit: 'test: e2e test suite for critical user journeys'
+**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
 
-Test priority:
-- CRITICAL: Auth, core feature happy path, data submission, payment/transaction flows
-- HIGH: Search, filtering, navigation, error states
-- MEDIUM: Responsive layout, animations, edge cases"
+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."
 
-Record results: total tests, pass count, fail count, failure details. Log to `docs/plans/.build-state.md` under `## E2E Testing`:
+### Step 6.1 — LRR: 5 chapter judges in parallel (ONE message)
 
-```
-| Iter | Total | Passed | Failed | Flaky | Top Failure |
-|------|-------|--------|--------|-------|-------------|
-| 1    | ...   | ...    | ...    | ...   | ...         |
-```
+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).
 
-**Iteration 2 — Fix & Re-run:**
+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 — description: "E2E fix iteration 2" — mode: "bypassPermissions" — prompt: "[COMPLEXITY: M] Fix E2E test failures from iteration 1: [paste failure details — test names, error messages, screenshot paths]. Diagnose each as real bug, flaky test, or missing selector. Fix accordingly — do NOT delete or skip tests. Re-run ALL tests. Commit: 'fix: e2e test failures iteration 2'."
+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.
 
-Record results in the E2E table. Identify flaky candidates (passed iter 1, failed iter 2 or vice versa).
+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.
 
-**Iteration 3 — Final Stability Run:**
+Read: `docs/plans/architecture.md`, `docs/plans/design-doc.md` (PRD — needed for requirements coverage evaluation), `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, eval-harness results from `docs/plans/evidence/eval-harness/`. Also read `docs/plans/decisions.jsonl` for cross-chapter context.
 
-Call the Agent tool — description: "E2E stability run" — mode: "bypassPermissions" — prompt: "[COMPLEXITY: M] Final E2E stability run (3 of 3). Previous results — Iter 1: [pass/fail counts], Iter 2: [pass/fail counts], Flaky candidates: [list]. Run ALL tests with --repeat-each=3. Quarantine inconsistent tests with test.fixme(). Fix remaining consistent failures. PASS CRITERIA: 95%+ pass rate (quarantined flaky tests excluded but logged). Commit: 'test: e2e stability fixes iteration 3'."
+Requirements coverage is folded into this chapter — not a separate dispatch. For EVERY feature listed in the MVP scope of `design-doc.md`, evaluate: (1) does it have a corresponding implemented task in sprint-tasks.md, (2) does it have a passing test or behavioral verification in evidence, (3) is it reachable and functional per the task-outputs. Emit a `requirements_coverage` field in your verdict JSON with shape `[{feature: \"<name>\", status: \"COVERED\" | \"PARTIAL\" | \"MISSING\"}, ...]`. Any MISSING feature is a BLOCK finding. Any PARTIAL feature is a CONCERNS finding at minimum.
 
-Record final results. Include in Reality Checker evidence.
+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.
 
-### Step 6.2d — Autonomous Dogfooding
+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 MVP features all COVERED?
 
-Run the agent-browser dogfood skill against the running app. Unlike the per-task smoke tests (which verify specific acceptance criteria), dogfooding is **exploratory** — it autonomously navigates every reachable page, clicks buttons, fills forms, checks console errors, and finds issues we didn't think to test.
+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[]` (one entry per MVP feature with `{feature, status}`), `follow_up_spawned=false`, `follow_up_findings=null`. Eng-Quality CANNOT spawn follow-ups."
 
-Start the dev server if not running. Then invoke the dogfood skill:
+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), eval-harness security cases. Also read `docs/plans/decisions.jsonl` for context.
 
-Call the Agent tool — description: "Dogfood the app" — mode: "bypassPermissions" — prompt: "Run the agent-browser dogfood skill against the running app at http://localhost:[port]. Explore every reachable page. Click every button. Fill every form. Check console for errors. Report a structured list of issues with severity ratings (critical/high/medium/low), screenshots, and repro steps. If dogfood skill is not available, use agent-browser manually: snapshot each page, click all interactive elements, check errors and network requests. Also evaluate UX quality: missing loading states, poor error messages, broken mobile layouts (resize to 375px), visual inconsistencies, missing empty states, form validation gaps. Report UX issues separately from functional issues."
+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).
 
-**Fix loop:** For each CRITICAL or HIGH issue found:
-1. Classify: is this a code bug (fix in Phase 5 style — spawn implementation fix agent) or a structural problem (needs architecture change — spawn architect agent to propose a fix plan, then implementation agent to execute)?
-2. Spawn the appropriate fix agent with: the issue description, repro steps, screenshot, affected page/component.
-3. After fixes, re-run dogfood on the affected pages only (not the full app). If new CRITICAL/HIGH issues appear, repeat. Max 3 fix cycles.
+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."
 
-MEDIUM/LOW issues: log to `docs/plans/build-log.md` for the Reality Checker.
+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 + Step 5.2 eval-harness perf cases), 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.
 
-### Step 6.2e — Fake Data Detector
+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.
 
-Call the Agent tool — description: "Fake data audit" — mode: "bypassPermissions" — prompt: "Run the Fake Data Detector Protocol (protocols/fake-data-detector.md). Check for mock/hardcoded data in production paths. Static analysis: grep for Math.random() business data, 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. Report findings with file:line references and severity."
+SRE MAY spawn ONE read-only follow-up investigation, but ONLY if verdict would be BLOCK. Same caps as Security."
 
-**Fix loop:** For each CRITICAL finding:
-1. Spawn a fix agent with: the finding (file:line, what's fake, what it should be), and the relevant source files.
-2. The fix agent replaces fake data with real API calls, real WebSocket connections, real data sources. If real data sources aren't available (missing API keys, no backend), the fix agent must flag this as a blocker — not paper over it with better-looking fake data.
-3. After fixes, re-run the fake data detector (static checks only — fast). Max 2 fix cycles.
+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.
 
-Remaining findings feed into the Reality Checker in Step 6.4.
+Scoring rules:
+  - PASS if zero Serious + zero Critical findings
+  - CONCERNS if 1-3 Serious + 0 Critical
+  - BLOCK if any Critical OR >3 Serious
 
-### Step 6.4 — Reality Check
+Write verdict to `docs/plans/evidence/lrr/a11y.json` per schema. A11y CANNOT spawn follow-ups."
 
-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."
+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.
 
-<HARD-GATE>Do NOT self-approve. Reality Checker must give the verdict.</HARD-GATE>
+Read: `docs/plans/visual-design-spec.md`, `docs/plans/visual-dna.md` (the 6-axis DNA card locked at Phase 3.0), `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`.
 
-**On PRODUCTION READY:** Log verdict. Proceed to Phase 7.
+Evaluate DRIFT: did the built product stay true to the DNA card locked at Phase 3.0? Score the gap on 6 DNA axes (Scope, Density, Character, Material, Motion, Type) + 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').
 
-**On NEEDS WORK:** The Reality Checker returns specific issues. These must be fixed — not logged and ignored.
+Write verdict to `docs/plans/evidence/lrr/brand-guardian.json` per schema. Fields per protocol. Brand Guardian CANNOT spawn follow-ups."
 
-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.
+**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.
 
-<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.
-</HARD-GATE>
+### Step 6.1a — PM coverage fold-in
 
-**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+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` MVP scope and emitted as a `requirements_coverage[]` field on `eng-quality.json`. The LRR Aggregator runs exactly once. Chapter count stays 5.
 
----
+### Step 6.2 — LRR Aggregator (sequential, after all 5 chapter files exist)
 
-## Phase 7: Ship
+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.
+
+**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`
+
+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.
+
+**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
+
+**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.
+
+**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.
 
-### Step 7.0 — Pre-Ship Verification
+Write routing decisions to `docs/plans/evidence/lrr-routing.json` with shape `[{finding_id, chapter, related_decision_id, authoring_phase, action: \"re-open\"}, ...]`.
 
-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 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.
 
-### Step 7.0b — Requirements Coverage Report
+**STEP 5 — ON READY:** Write `docs/plans/evidence/lrr-aggregate.json` with shape:
 
-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:
+```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.
+
+Cite triggering rule number in output. No verdict is valid without citing the rule."
 
-| MVP Feature | Task | Test | Verified | Status |
-|-------------|------|------|----------|--------|
+### Step 6.3 — Verdict resolution
 
-Mark each as COVERED, PARTIAL (implemented but untested), or MISSING. Any MISSING feature is a blocker — report it immediately."
+The LRR Aggregator's `combined_verdict` is the authoritative verdict. Resolution rules:
 
-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.
+  - **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.
+
+**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
+  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.
+```
 
-### Step 7.1 — Documentation
+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).
 
-Call the Agent tool — description: "Documentation" — mode: "bypassPermissions" — prompt: "Write project docs: README with setup/architecture/usage, API docs if applicable, deployment notes. Commit: 'docs: project documentation'."
+<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.
 
-### Step 7.2 — Metric Loop: Documentation Quality
+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>
 
-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.
+**Writes:** `docs/plans/evidence/lrr/*.json`, `docs/plans/evidence/lrr-aggregate.json`, `docs/plans/evidence/lrr-routing.json`.
 
-### Step 7.3 — Record Learnings
+**Compaction checkpoint.** Update `.build-state.json` per the format above.
 
-Append to `docs/plans/learnings.md` (create if it doesn't exist). Review the build and record 3-5 learnings:
+---
 
-- **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]
+## Phase 7: Ship
 
-Base learnings on: metric loop stall patterns, build-fix frequency, phases that exceeded expected iterations, agent prompts that needed rework.
+**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.
 
-### Completion Report
+**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).
 
-Create final commit. Present:
+### 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 the LRR Aggregator's structured output (`docs/plans/evidence/lrr-aggregate.json`) and the Reality Checker evidence manifest (`docs/plans/evidence/reality-check-manifest.json`) — NOT 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 | — |
+
+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.