buildanything 1.8.0 → 2.0.0

package/protocols/ios-phase-branches.md

@@ -2,6 +2,31 @@
 
 _Loaded into orchestrator session context when `project_type=ios`. Contains per-phase iOS-specific instructions. Mode-agnostic phase scaffolding lives in `commands/build.md`._
 
+## Dispatch rules
+
+Every Agent tool call in this file MUST include a `subagent_type:` field unless explicitly marked INTERNAL. See `commands/build.md` top preamble for the project-wide HARD-GATE. iOS agents live at `/agents/ios-*.md` plus the general-purpose engineering and testing agents from ECC and agency-agents.
+
+## CONTEXT header injection (iOS branch — project_type hardcoded)
+
+Every `subagent_type:` dispatch in this file prepends a CONTEXT header to its prompt. Per `commands/build.md` CONTEXT HEADER HARD-GATE: the orchestrator MUST render this header ONCE at the start of each phase by resolving all values into concrete strings, then reuse the rendered header verbatim for every dispatch in that phase. DO NOT leave `{read from ...}` placeholders — resolve them before the first dispatch.
+
+```
+CONTEXT:
+  project_type: ios
+  phase: <resolved: current phase number>
+  ios_features: <resolved: 16-flag block from .build-state.json — the literal YAML values, NOT a pointer>
+
+TASK:
+```
+
+**Resolution rules:**
+- `ios_features` = the 16 boolean flags resolved to their values. ~200 tokens.
+- The rendered header is a stable prefix — it does not change between dispatches within a phase.
+
+Individual dispatches below reference `[CONTEXT header above]` and rely on this rendered template.
+
+Individual dispatches below reference `[CONTEXT header above]` and rely on this template. The orchestrator fills `phase` per the enclosing section.
+
 ## iOS Mode Tool Stack
 
 When `project_type=ios` is set in `docs/plans/.build-state.md`, use this stack in place of the web defaults:
@@ -25,7 +50,7 @@ When Phase 0 classifier sets `project_type=ios`:
 - Load `protocols/ios-context.md` into orchestrator session context — it holds the Senior iOS Engineer persona inherited by every iOS implementation agent (injected into agent prompts).
 - Reference `protocols/ios-frameworks-map.md` by **path only** — do NOT load its 323 lines into session context or inject into agent prompts. It is a lookup reference: agents `Read` it on-demand when they hit a "user wants X → which Apple framework?" question, grep for their capability, extract the 1-2 relevant rows. The orchestrator cites it by path when dispatching the architect, entitlements-generator, and impl agents; those agents open it themselves.
 - Use the iOS Mode Tool Stack above — not the web defaults.
-- Phase 3 skips `/design-system` (no web style guide). Phase 6 dispatches to iOS twins of `/verify` + `/ux-review` + `/fix`.
+- Phase 3 skips `/design-system` (no web style guide). Phase 5 dispatches to iOS twins of `/verify` + `/ux-review` + `/fix`.
 - If greenfield (no `.xcodeproj` exists), **Phase -1 Bootstrap** runs before Phase 1.
 
 ## Phase -1 — iOS Bootstrap (iOS-only, greenfield only)
@@ -47,7 +72,59 @@ Verify (or guide the user to install):
 
 Dispatch the `ios-bootstrap` skill (or inline the prompt if the skill isn't available):
 
-Call the Agent tool — description: "iOS bootstrap" — mode: "bypassPermissions" — prompt: "Guide the user through creating a new Xcode project via Xcode's New Project dialog (File > New > Project > iOS App). Target: iOS 26.0+, Swift 6.2+, SwiftUI interface, SwiftData storage (if data persistence is in the design). Do NOT use Tuist or XcodeGen. After the user confirms project creation, verify: `.xcodeproj` exists, the project builds clean via XcodeBuildMCP, and the app launches on a simulator. Also create the canonical `maestro/` directory at the project root (for Phase 4 flow stubs + Phase 5 smoke tests) — no leading dot, committed to git. Report the project path and bundle identifier."
+Call the Agent tool — description: "iOS bootstrap" — subagent_type: INTERNAL (user-guided skill dispatch, no backing agent file) — mode: "bypassPermissions" — prompt: "[CONTEXT header above — phase: -1] Guide the user through creating a new Xcode project via Xcode's New Project dialog (File > New > Project > iOS App). Target: iOS 26.0+, Swift 6.2+, SwiftUI interface, SwiftData storage (if data persistence is in the design). Do NOT use Tuist or XcodeGen. After the user confirms project creation, verify: `.xcodeproj` exists, the project builds clean via XcodeBuildMCP, and the app launches on a simulator. Also create the canonical `maestro/` directory at the project root (for Phase 4 flow stubs + Phase 5 smoke tests) — no leading dot, committed to git. Report the project path and bundle identifier."
+
+### Step -1.2b — Overwrite Apple template test files with AUTOGENERATED HARNESS marker
+
+Immediately after the Xcode project is created (and BEFORE Step -1.3 Bootstrap Verification), the orchestrator MUST overwrite the auto-generated Apple-template test files with an AUTOGENERATED HARNESS marker. This closes the "forgot Apple templates exist and shipped them" failure mode at the earliest possible point in the build.
+
+Locate the test files at `<app-target>Tests/<app-target>Tests.swift` and `<app-target>UITests/<app-target>UITests.swift` (paths depend on the Xcode target name chosen in Step -1.2 — derive from `.xcodeproj` path). Use the Write tool to replace each file's contents with the marker below. Substitute `<TargetName>` with the actual test-target name.
+
+**Unit test file** (`<app-target>Tests/<app-target>Tests.swift`):
+
+```swift
+// AUTOGENERATED BY /buildanything:build iOS BOOTSTRAP — DO NOT SHIP THIS TEMPLATE. Replace with actual tests per sprint-tasks.md Behavioral Test fields.
+//
+// Layer C stub detector directive: any test file containing this AUTOGENERATED BY /buildanything:build iOS BOOTSTRAP header
+// MUST be reported as "MARKER: pending implementation" (not STUB). The marker is a deliberate placeholder, not an accidental
+// Apple template. It is intentionally sized >500 bytes with >=1 assertion so it compiles and runs, while the header comment
+// flags it for human replacement before ship. Replace this entire file before Phase 6 Step 6.0 Reality Check.
+
+import Testing
+import Foundation
+
+@Suite("Bootstrap marker — replace before ship")
+struct BootstrapMarkerTests {
+    @Test func bootstrapMarkerSanityCheck() async throws {
+        #expect(Bundle.main.bundleIdentifier != nil)
+    }
+}
+```
+
+**UI test file** (`<app-target>UITests/<app-target>UITests.swift`):
+
+```swift
+// AUTOGENERATED BY /buildanything:build iOS BOOTSTRAP — DO NOT SHIP THIS TEMPLATE. Replace with actual tests per sprint-tasks.md Behavioral Test fields.
+//
+// Layer C stub detector directive: any test file containing this AUTOGENERATED BY /buildanything:build iOS BOOTSTRAP header
+// MUST be reported as "MARKER: pending implementation" (not STUB). The marker is a deliberate placeholder, not an accidental
+// Apple template. It is intentionally sized >500 bytes with >=1 assertion so it compiles and runs, while the header comment
+// flags it for human replacement before ship. Replace this entire file before Phase 6 Step 6.0 Reality Check.
+
+import XCTest
+
+final class BootstrapMarkerUITests: XCTestCase {
+    func testBootstrapMarkerSanityCheck() throws {
+        let app = XCUIApplication()
+        app.launch()
+        XCTAssertTrue(app.state == .runningForeground || app.state == .runningBackground)
+    }
+}
+```
+
+**Layer C detector PASS-through directive:** The `protocols/verify.md` Step 2 test-stub detector MUST treat any test file whose first non-blank line contains the literal string `AUTOGENERATED BY /buildanything:build iOS BOOTSTRAP` as a "MARKER: pending implementation" result — NOT as a STUB. Rationale: the marker is a deliberate placeholder with a conspicuous header and known sanity assertion; the STUB classification is reserved for accidental/unmodified templates. The orchestrator MUST still surface MARKER results in the Phase 6 Step 6.0 Reality Check as an unresolved task, and the user MUST replace marker files before `combined_verdict = PRODUCTION READY` can be emitted.
+
+After writing both marker files, verify via XcodeBuildMCP that the test targets still compile.
 
 ### Step -1.3 — Bootstrap Verification
 
@@ -57,11 +134,11 @@ Confirm all of: Xcode version OK, `.xcodeproj` exists, XcodeBuildMCP responds, a
 
 ## Phase 1 — Plan (iOS additions)
 
-Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 1. Planning agent = `ios-swift-architect` (not the generic web planner). Market/tech-feasibility research agents must check App Store category landscape, TestFlight constraints, and iOS 26 API availability (via apple-docs-mcp) in addition to standard research.
+Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 1. The Phase 1.1 research team is the same 4 agents as the web branch (`subagent_type: feature-intel`, `subagent_type: tech-feasibility`, `subagent_type: design-ux-researcher`, `subagent_type: business-model`) but each prompt must additionally check App Store category landscape, TestFlight constraints, and iOS 26 API availability (via apple-docs-mcp). For AI / Foundation Models prompts, additionally dispatch `subagent_type: ios-foundation-models-specialist`. Note: the Phase 2.3 sprint-breakdown `subagent_type: planner` is replaced by `subagent_type: ios-swift-architect` for iOS mode (see Phase 2 additions below).
 
 ## Phase 2 — Architecture (iOS additions)
 
-Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 2. Architecture agents must select iOS 26 APIs via apple-docs-mcp (verify availability, deprecations, minimum OS). Replace "Backend architecture" / "Frontend architecture" with: (1) SwiftUI view hierarchy + navigation model, (2) SwiftData schema + CloudKit strategy, (3) Swift Concurrency / actor isolation plan, (4) iOS-specific security (Keychain, entitlements, ATS). Implementation blueprint lists Swift files + Xcode targets, not web modules.
+Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 2. Architecture agents must select iOS 26 APIs via apple-docs-mcp (verify availability, deprecations, minimum OS). Replace the web `subagent_type: engineering-backend-architect` / `subagent_type: engineering-frontend-developer` architecture dispatches with a single `subagent_type: ios-swift-architect` dispatch covering: (1) SwiftUI view hierarchy + navigation model, (2) SwiftData schema + CloudKit strategy, (3) Swift Concurrency / actor isolation plan, (4) iOS-specific security (Keychain, entitlements, ATS). Implementation blueprint lists Swift files + Xcode targets, not web modules. Security architecture stays on `subagent_type: engineering-security-engineer` (unchanged from web branch — the security engineer handles both stacks).
 
 ### Feature Flag Resolution (end of Phase 2)
 
@@ -84,35 +161,69 @@ Before leaving Phase 2, resolve the `ios_features` flag block (schema in `protoc
 - `calendar` — true if EventKit / calendar / reminders mentioned.
 - `appleWatch` — true if watchOS companion mentioned.
 
-Resolution rule: keyword-match the brainstorm transcript + architecture doc; in autonomous mode default to `false` on ambiguous flags and log the assumption to `build-log.md`; in interactive mode confirm ambiguous flags with the user. These flags gate Phase 5 skill loading and Phase 4 entitlement generation.
+Resolution rule: keyword-match the brainstorm transcript + architecture doc; in autonomous mode default to `false` on ambiguous flags and log the assumption to `build-log.md`; in interactive mode confirm ambiguous flags with the user. These flags gate Phase 4 per-task skill loading and Phase 4 Step 4.0 entitlement generation.
+
+### Visual DNA Directional Preview (pre-Gate-2)
+
+Before the Quality Gate 2 approval prompt in `commands/build.md` is rendered, dispatch a lightweight directional preview of the intended iOS visual direction. This is NOT the full `ios-design-board.md` (that remains Phase 3.2's job) — it is a 3-5 bullet sanity-check surfaced at Gate 2 so the user catches wrong visual direction before Phase 3+ burns tokens against it.
+
+Call the Agent tool once:
+
+1. Description: "iOS visual direction preview" — subagent_type: `ios-swift-ui-design` — prompt: "[CONTEXT header above — phase: 2] Read `docs/plans/design-doc.md` (#persona, #scope, #voice), `docs/plans/findings-digest.md`, and `docs/plans/architecture.md`. Emit a 3-5 bullet DIRECTIONAL preview of the intended iOS visual direction — one-line brand read, then proposed leanings on: navigation pattern (TabView vs NavigationStack vs sheets), typography (Dynamic Type scale + tone), color (semantic + dark mode leaning), motion/material feel (Liquid Glass on iOS 26+ yes/no, haptic-forward yes/no), SF Symbol family vibe. NO rationale paragraphs, NO reference citations. Save to `docs/plans/visual-dna-preview.md` as a flat bullet list. Target 150 tokens, max 250."
+
+Output: `docs/plans/visual-dna-preview.md` — surfaced by the orchestrator in the Gate 2 prompt. Phase 3.2 produces the full `ios-design-board.md`; the preview is discarded after Gate 2 approval.
 
 ## Phase 3 — Design (iOS branch)
 
 Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 3. Do **NOT** build `/design-system` (web-only). Instead:
 
-- **Step 3.1 iOS** — agent-browser (`-p desktop`) harvests iOS UI references from **free** sources: screenlane.com (iOS screenshots), App Store web listings for top apps in the product category, Apple HIG pages, SF Symbols browser. No Mobbin (paid). Fallback: vibe-only design board if scraping blocked.
-- **Step 3.2 iOS** — synthesize an **iOS Design Board** (`docs/plans/ios-design-board.md`) grounded in Apple HIG + Liquid Glass (iOS 26+) + SF Symbols + the harvested references + the user's stated app vibe. Cover: typography (Dynamic Type scale), color (semantic + dark mode), spacing (HIG-compliant), navigation pattern (TabView / NavigationStack / sheets), iconography (SF Symbols).
+- **Step 3.1 iOS** — dispatch `subagent_type: visual-research` with the agent-browser (`-p desktop`) skill to harvest iOS UI references from **free** sources: screenlane.com (iOS screenshots), App Store web listings for top apps in the product category, Apple HIG pages, SF Symbols browser. No Mobbin (paid). Fallback: vibe-only design board if scraping blocked.
+- **Step 3.2 iOS** — dispatch `subagent_type: ios-swift-ui-design` to synthesize an **iOS Design Board** (`docs/plans/ios-design-board.md`) grounded in Apple HIG + Liquid Glass (iOS 26+) + SF Symbols + the harvested references + the user's stated app vibe. Cover: typography (Dynamic Type scale), color (semantic + dark mode), spacing (HIG-compliant), navigation pattern (TabView / NavigationStack / sheets), iconography (SF Symbols).
 - **Skip Step 3.3** (Living Style Guide) — no web route.
-- **Step 3.4 iOS** — visual QA loop uses XcodeBuildMCP SwiftUI Preview captures (not Playwright screenshots). Exit criterion = user-approved pass/fail (not a 0-100 rubric). **Max 3 iterations** (tighter than web's 5). On stall: present captures + remaining issues to user for accept/reject decision.
+- **Step 3.4 iOS** — Per `protocols/metric-loop.md` Step 0.5, extract scoring criteria from `ios-design-board.md` (HIG values, spacing, typography scale, navigation pattern, color tokens, SF Symbol choices) into the Scoring Criteria Checklist. Extraction is **mechanical** — `ios-design-board.md` has named sections with explicit values. Persist to `active_metric_loop.scoring_criteria_checklist` in `.build-state.json`. Visual QA loop uses XcodeBuildMCP SwiftUI Preview captures (not Playwright screenshots). The loop runs `subagent_type: ios-swift-ui-design` as the generator (Preview tweaks) paired with `subagent_type: design-critic` as the critic. Critic receives the checklist + fresh Preview captures each iteration (NOT the full `ios-design-board.md`). Generator re-invocation on iteration 2+ follows the lean context rule (top issue + file paths + relevant checklist values only). Exit criterion = user-approved pass/fail (not a 0-100 rubric). **Max 3 iterations** (tighter than web's 5). On stall or max iterations, present the score history to the user.
 - Save final artifact to `docs/plans/ios-design-board.md` (Phase 4 gate reads this file instead of `visual-design-spec.md`).
 
 Phase 4 HARD-GATE: iOS mode requires `docs/plans/ios-design-board.md` to exist before Phase 4 starts. If missing, return to Phase 3.
 
-## Phase 4 — Foundation (iOS branch)
+## Phase 4 — Build (iOS branch)
+
+Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 4 — Build (Step 4.0 Scaffold).
+
+Phase 4 in the iOS branch contains the Step 4.0 Scaffold work (iOS project bootstrap follow-up, entitlements, Info.plist, XcodeBuildMCP folder structure, SwiftUI design tokens, Maestro flow stubs). Per-task implementation (Step 4.1+) is handled inline in the "Phase 4 — Build per-task flow (iOS branch)" section below.
+
+Dispatch the `ios-entitlements-generator` skill (Info.plist + entitlements based on features: push, background, HealthKit, etc.) and the `ios-info-plist-hardening` skill (ATS config, privacy usage strings, URL schemes). Both live under `skills/ios/` and are loaded as skill bundles, not agents — they inherit the active implementer's `subagent_type` rather than being dispatched standalone. The active implementer for Phase 4 scaffold work is `subagent_type: engineering-senior-developer` (inheriting the `ios-context.md` persona).
+
+- **Step 4.0.a (iOS):** Scaffolding is already done by Phase -1 Bootstrap. Instead, create the app target's folder structure (`Views/`, `Models/`, `Services/`, `Resources/`) via XcodeBuildMCP.
+- **Step 4.0.b (iOS):** Implement iOS-native design tokens from `docs/plans/ios-design-board.md` (SwiftUI `Color` extensions, `Font` extensions, `ShapeStyle` tokens, spacing constants) — NOT web CSS.
+- **Step 4.0.c (iOS):** Replace Playwright acceptance scaffolds with Maestro YAML flow stubs in `maestro/` directory.
+- **Step 4.0.d (iOS):** Metric Loop on scaffold health — builds clean via XcodeBuildMCP, Swift Testing `@Test`s pass, structure matches architecture. Max 3 iterations. Scoring criteria = clean build + @Test pass + expected folder structure. Checklist is minimal and **mechanical** — no large doc extraction needed. On `xcodebuild` failure, spawn the Swift build resolver — see the dispatch block below.
+- **Step 4.0.e (iOS):** Verification Gate via XcodeBuildMCP build + test. Do not proceed to Step 4.1+ per-task flow until it passes.
+
+**Step 4.0.d build-fix dispatch (iOS):** When the scaffold-health metric loop hits an `xcodebuild` failure, the orchestrator MUST dispatch the Swift build resolver rather than re-running the scaffolder blindly.
 
-Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 4.
+Call the Agent tool — description: "Swift build fix (scaffold)" — subagent_type: `swift-build-resolver` — mode: "bypassPermissions" — prompt: "[CONTEXT header above — phase: 4] xcodebuild failed with this error: [paste]. Apply the minimal diff to fix the specific error. No architectural edits, no dependency changes, no refactors. Confirm green before returning."
 
-Dispatch `ios-entitlements-generator` (Info.plist + entitlements based on features: push, background, HealthKit, etc.) and `ios-info-plist-hardening` (ATS config, privacy usage strings, URL schemes).
+If the resolver returns `status: blocked` (architectural change required), the orchestrator returns to Step 4.0.a/4.0.b with the blocker surfaced — the resolver is NOT permitted to restructure foundation types.
 
-- **Step 4.1 (iOS):** Scaffolding is already done by Phase -1 Bootstrap. Instead, create the app target's folder structure (`Views/`, `Models/`, `Services/`, `Resources/`) via XcodeBuildMCP.
-- **Step 4.2 (iOS):** Implement iOS-native design tokens from `docs/plans/ios-design-board.md` (SwiftUI `Color` extensions, `Font` extensions, `ShapeStyle` tokens, spacing constants) — NOT web CSS.
-- **Step 4.2b (iOS):** Replace Playwright acceptance scaffolds with Maestro YAML flow stubs in `maestro/` directory.
-- **Step 4.3 (iOS):** Metric Loop on scaffold health — builds clean via XcodeBuildMCP, Swift Testing `@Test`s pass, structure matches architecture. Max 3 iterations.
-- **Step 4.4 (iOS):** Verification Gate via XcodeBuildMCP build + test. Do not proceed to Phase 5 until it passes.
+**Step 4.0.c HARD-GATE (Maestro flow scaffold assertion):** At the end of Step 4.0.c — before proceeding to Step 4.0.d — the orchestrator MUST run:
 
-## Phase 5 — Build (iOS branch)
+```bash
+find maestro -name '*.yaml' -type f | wc -l
+```
 
-Load full iOS skill bundle per `protocols/ios-context.md` §Phase 5. Every implementation agent inherits the `ios-context.md` Senior iOS Engineer persona. Bundle includes: `swiftui-pro`, `swift-concurrency`, `swiftdata-pro`, `swift-security-expert`, `swift-accessibility`.
+The result MUST be `>= 2`. If less than 2, re-dispatch the Maestro stub scaffolder ONCE (max 1 retry) via:
+
+Call the Agent tool — description: "Maestro stub scaffold (retry)" — subagent_type: `engineering-senior-developer` — mode: "bypassPermissions" — prompt: "[CONTEXT header above — phase: 4] Step 4.0.c regression: Maestro flow stubs were not scaffolded. Load the `skills/ios/ios-maestro-flow-author/` skill bundle and scaffold at least 2 .yaml flow stubs in `maestro/` per the sprint-tasks.md Behavioral Test fields. Do NOT touch other files."
+
+After the retry, re-run the `find` command. If still `< 2`, HALT the build with directive: "Step 4.0.c regression: Maestro flow stubs were not scaffolded. Return to Step 4.0.c before proceeding." Do NOT advance to Step 4.0.d / Step 4.0.e / Step 4.1+ per-task flow until the assertion passes.
+
+## Phase 4 — Build per-task flow (iOS branch)
+
+These are the iOS-specific prompt templates for the per-task flow inside Phase 4 Step 4.1+. The orchestrator-side machinery (wave-based parallel dispatch by DAG, Briefing Officer, Senior Dev cleanup, code review pair, Metric Loop, Verify Service) lives in `commands/build.md` Phase 4. This section overrides the implementer dispatch and iOS-specific verification prompts.
+
+**Wave dispatch (topological, dependency-bounded):** Build the DAG from the `Dependencies:` field on each row in `docs/plans/sprint-tasks.md`. A wave is the set of all not-yet-dispatched tasks whose declared dependencies are ALL complete. Dispatch every task in a wave as parallel Agent tool calls in ONE message, wait for the full wave to return, write back any `deviation_row` payloads via the orchestrator-scribe (single-writer pattern per `commands/build.md` §Decision log scribe), then compute the next wave. No magic parallelism cap — the dependency graph is the limit. iOS wave 1 commonly contains independent `Models/`, `Services/`, and static-view scaffolds; downstream view-model and navigation tasks fall into later waves as their deps clear.
+
+Load full iOS skill bundle per `protocols/ios-context.md` §Phase 4 — Build (Step 4.1+ per-task flow). Every implementation agent inherits the `ios-context.md` Senior iOS Engineer persona. Bundle includes: `swiftui-pro`, `swift-concurrency`, `swiftdata-pro`, `swift-security-expert`, `swift-accessibility`.
 
 **Feature-flag gated skill loading** — before dispatching any gated skill, the orchestrator MUST read `ios_features` from `docs/plans/.build-state.md`. Load a gated skill only when its flag is `true`:
 - `widgets: true` → load `skills/ios/widgetkit/`
@@ -123,40 +234,104 @@ Load full iOS skill bundle per `protocols/ios-context.md` §Phase 5. Every imple
 
 **Other Apple frameworks** (HealthKit, GameKit, ARKit, RealityKit, Vision, CoreML, MapKit, PhotoKit, WeatherKit, MusicKit, Contacts, EventKit, CallKit) — **available via iOS 26 SDK `import`**; agent uses `apple-docs-mcp` lookups + `ios-context.md` persona + `ios-entitlements-generator` for capability wiring. No dedicated mentor-skill yet — add one only if a specific framework becomes friction during dogfooding.
 
-### Step 5.1 — Implement (iOS)
+### Step 4.1 — Implement (iOS)
 
-Call the Agent tool — description: "[task name]" — mode: "bypassPermissions" — prompt: "TASK: [task description + acceptance criteria]. HANDOFF — Architecture section: [paste]. Design section: [paste relevant section from `docs/plans/ios-design-board.md`]. Previous task output: [if relevant]. For UI tasks: consult `docs/plans/ios-design-board.md` for visual tokens + HIG patterns, and `skills/ios/swiftui-design-principles/` for the 10-rule polish checklist. Match the design board's tokens exactly. Implement fully with real Swift code, Swift Testing `@Test`s, and XcodeBuildMCP validation. Commit: 'feat: [task]'. Report what you built, files changed, and test results."
+Call the Agent tool — description: "[task name]" — subagent_type per the Agent selection table below — mode: "bypassPermissions" — prompt: "[CONTEXT header above — phase: 4] TASK: [task description + acceptance criteria]. HANDOFF — Read these files via your Read tool before starting:\n  - Architecture: `docs/plans/architecture.md`\n  - Design board: `docs/plans/ios-design-board.md`\nFor UI tasks: also consult `skills/ios/swiftui-design-principles/` for the 10-rule polish checklist. Match the design board's tokens exactly. Previous task output: [if relevant]. Implement fully with real Swift code, Swift Testing `@Test`s, and XcodeBuildMCP validation. Commit: 'feat: [task]'. Report what you built, files changed, and test results."
 
 Implementation agents edit Swift files directly and build/diagnose via XcodeBuildMCP. Set `[COMPLEXITY: S/M/L]` based on the task's Size from sprint-tasks.md.
 
-### Step 5.2 — Metric Loop (iOS)
+**Agent selection table for Step 4.1 (keyed on `ios_features.*` + task kind):**
+
+| Task kind | Gating flag | Dispatch `subagent_type` |
+|-----------|-------------|--------------------------|
+| Foundation Models / on-device LLM | `ios_features.foundationModels == true` | `ios-foundation-models-specialist` |
+| StoreKit / IAP / subscriptions | `ios_features.storekit == true` | `ios-storekit-specialist` |
+| Widgets / Lock Screen | `ios_features.widgets == true` | `engineering-senior-developer` (loads `skills/ios/widgetkit/`) |
+| Live Activities / Dynamic Island | `ios_features.liveActivities == true` | `engineering-senior-developer` (loads `skills/ios/activitykit/`) |
+| App Intents / Siri / Shortcuts | `ios_features.appIntents == true` | `engineering-senior-developer` (loads `skills/ios/app-intents/`) |
+| SwiftUI view / view model / navigation (UI task) | n/a | `engineering-senior-developer` (L) or `engineering-mobile-app-builder` (S/M) |
+| Exploratory Swift-code search before implementation | n/a | `ios-swift-search` |
+| General / cross-cutting | n/a | `engineering-senior-developer` (L) or `engineering-mobile-app-builder` (S/M) |
+
+Precedence rule: if a task matches multiple rows, the most specific (top-down) wins. UI *planning* (not implementation) may additionally dispatch `ios-swift-ui-design` as a separate plan step — the implementer proper remains per the table.
+
+### Step 4.1b — Swift review (iOS)
+
+After every Step 4.1 implementer returns (and before Step 4.2 Metric Loop / verify), run a Swift-specific review pass to catch concurrency / SwiftUI / protocol-DI issues the generic code-reviewer misses. Run in parallel with the generic code-reviewer + silent-failure-hunter pair from `commands/build.md` per-task review block.
+
+Call the Agent tool — description: "Swift review: [task name]" — subagent_type: `swift-reviewer` — prompt: "[CONTEXT header above — phase: 4] Review the Swift changes in this task. Task: [name]. Files changed: [list]. Walk the CRITICAL → HIGH → MEDIUM checklist for Swift concurrency 6.2, SwiftUI patterns, protocol DI testability, and Foundation Models integration. Confidence-filter at 80%."
+
+For auth / PII / Keychain / credential tasks, also dispatch `subagent_type: security-reviewer` per the build.md per-task review block.
+
+### Step 4.1c — Cleanup (iOS)
+
+Run the code-simplifier + refactor-cleaner pair from `commands/build.md` per-task cleanup block against the Swift changeset. Swift dead-code detection relies on SwiftLint / xcodebuild warnings rather than `knip` / `depcheck` — the refactor-cleaner runs in a Swift-aware mode.
+
+1. Call the Agent tool — description: "Simplify [task name]" — subagent_type: `code-simplifier` — mode: "bypassPermissions" — prompt: "[CONTEXT header above — phase: 4] Simplify changed Swift files from [task]. Remove dead code, unused imports, redundant abstractions. Do NOT add features. Do NOT change architecture. Do NOT touch files outside the changeset. Files: [list]."
+2. Call the Agent tool — description: "Refactor-clean [task name]" — subagent_type: `refactor-cleaner` — mode: "bypassPermissions" — prompt: "[CONTEXT header above — phase: 4] Clean dead code from changed Swift files in [task]. Run SwiftLint / xcodebuild warning sweep and remove orphaned helpers, unused types, dead functions. Same scope rules — changeset only. Files: [list]."
+
+### Step 4.2 — Metric Loop (iOS)
 
-Metric loop uses XcodeBuildMCP SwiftUI Preview captures for UI verification (not agent-browser). Max 5 iterations.
+Per `protocols/metric-loop.md` Step 0.5, extract task acceptance criteria from `sprint-tasks.md` Behavioral Test field into the Scoring Criteria Checklist. **Phase 4 per-task extraction is mechanical — no dispatch.** The Behavioral Test field is a single structured value per task; the orchestrator copies it directly into `active_metric_loop.scoring_criteria_checklist` in `.build-state.json`.
 
-### Step 5.3b — Behavioral Smoke Test (iOS)
+Metric loop uses XcodeBuildMCP SwiftUI Preview captures for UI verification (not agent-browser). Critic receives the checklist + fresh Preview captures each iteration. Generator re-invocation on iteration 2+ follows the lean context rule (top issue + file paths + relevant checklist values only — no full `[CONTEXT header above]`). Max 5 iterations.
+
+**Build-fix dispatch (iOS):** When `xcodebuild` fails during the metric loop (or during Step 4.1 implementer return), the orchestrator MUST spawn the Swift build resolver rather than asking the generic implementer to guess at the error.
+
+Call the Agent tool — description: "Swift build fix" — subagent_type: `swift-build-resolver` — mode: "bypassPermissions" — prompt: "[CONTEXT header above — phase: 4] xcodebuild failed with this error: [paste]. Apply the minimal diff to fix the specific error. No architectural edits, no dependency changes, no refactors. Confirm green before returning."
+
+If the resolver returns `status: blocked` (architectural or dependency change required), the orchestrator hands back to the Step 4.1 implementer with the resolver's `blocking_error` payload so the implementer can make an informed architectural fix — the resolver is NOT permitted to restructure types.
+
+### Step 4.3b — Behavioral Smoke Test (iOS) — PRECONDITIONS
+
+Before running the Maestro smoke test, the orchestrator MUST verify:
+
+1. **Maestro CLI installed:** `which maestro`. If missing, dispatch installer agent: `brew install --cask maestro` OR `curl -Ls https://get.maestro.mobile.dev | bash`. MAX 2 attempts. If still missing, hard-fail with directive: "Maestro is required for iOS behavioral verification. Install manually or downgrade affected tasks' Behavioral Test fields to N/A in sprint-tasks.md."
+
+2. **Maestro flow files exist:** `find maestro -name '*.yaml' -type f | wc -l`. If zero AND any iOS task in `sprint-tasks.md` has a non-N/A Behavioral Test field, hard-fail with directive: "Step 4.0.c regression: Maestro flow stubs were not scaffolded. Return to Step 4.0.c before proceeding to Step 4.3b."
+
+3. **Booted simulator available:** XcodeBuildMCP `BootSimulator` returns success for the project's deployment target.
+
+If any precondition fails, log "SMOKE: BLOCKED -- precondition [N] failed" to `docs/plans/.build-state.md` and return BLOCKED. Do NOT proceed to the smoke test execution. Do NOT log SKIPPED. Do NOT log PASS.
+
+### Step 4.3b — Behavioral Smoke Test (iOS)
 
 Executes the task's **Maestro** flow from `maestro/` against a booted simulator (via XcodeBuildMCP `BuildAndRun` → `maestro test maestro/<flow>.yaml`) — NOT agent-browser or localhost. Evidence = Maestro run log + Preview/simulator screenshots. For OAuth/web-view flows on the simulator only, use agent-browser `-p ios`.
 
-## Phase 6 — Harden (iOS branch)
+## Phase 5 — Audit (iOS branch)
 
-Phase 6 does NOT run the web audit bundle. Instead, **dispatch to the three iOS twin commands in sequence**:
+Phase 5 does NOT run the web audit bundle. Instead, **dispatch to the three iOS twin commands in sequence** (these are slash-command dispatches, not Agent tool calls — each twin command owns its own internal `subagent_type` wiring):
 
 1. `/buildanything:verify` (iOS twin — functional correctness, XcodeBuildMCP diagnostics, Maestro E2E)
 2. `/buildanything:ux-review` (iOS twin — HIG audit via SwiftUI Preview captures + Apple HIG checklist)
-3. `/buildanything:fix` (iOS twin — dispatches specialist iOS agents for each finding)
+3. `/buildanything:fix` (iOS twin — dispatches specialist iOS agents for each finding, including `subagent_type: ios-app-review-guardian` for App Review rejection risks)
+
+Each twin owns its own scope and reviewer — they are NOT merged into a single loop. After all three twins complete, verify the following output artifacts exist and are non-empty before proceeding to Phase 6:
+
+- `docs/plans/ios-verify-report.md` — written by the `/buildanything:verify` twin
+- `docs/plans/ios-ux-review-report.md` — written by the `/buildanything:ux-review` twin
+- At least one `*.yaml` file in `maestro/` — Maestro flows from Phase 4 scaffold
+- At least one `*.png` screenshot in `docs/plans/evidence/maestro-runs/` — from the verify run
 
-Each twin owns its own scope and reviewer — they are NOT merged into a single loop. After all three twins complete, run **Step 6.4 Reality Check** (in `commands/build.md`) with iOS evidence (Maestro run logs, Preview captures, HIG findings).
+If any required artifact is missing, re-dispatch the owning twin once. If still missing after one retry, log a blocker and present to user (interactive) or proceed with a warning in the Completion Report (autonomous).
 
-Skip Steps 6.1, 6.1b, 6.2, 6.2b, 6.2c (Playwright E2E), 6.2d (agent-browser dogfood), 6.2e (web fake-data patterns).
+Then run **Phase 6 Step 6.0 Reality Check** (in `commands/build.md`, backed by `subagent_type: testing-reality-checker`) with iOS evidence (Maestro run logs, Preview captures, HIG findings).
+
+The Launch Readiness Review (Phase 6 in `commands/build.md`) also runs unchanged for iOS mode, with the usual LRR chapter agents: `subagent_type: code-reviewer` (Eng-Quality, paired with `subagent_type: swift-reviewer` for Swift-specific code review), `subagent_type: security-reviewer` (Security), `subagent_type: engineering-sre` (SRE), `subagent_type: a11y-architect` (A11y), `subagent_type: design-brand-guardian` (Brand).
+
+Skip the web-only audit steps from `protocols/web-phase-branches.md` Phase 5 (5-agent audit team, eval harness, hardening metric loop, 3-iteration Playwright E2E, agent-browser dogfood, web fake-data patterns).
 
 ## Phase 7 — Ship (iOS branch, optional)
 
 Ship pipeline is **optional** (simulator-only is a valid end-state — no Apple Developer account required).
 
-If the user opts to ship: run the iOS `asc-*` pipeline:
-- `asc-metadata-generator` (App Store Connect listing + keywords + description)
-- `asc-screenshot-generator` (generate App Store screenshots via XcodeBuildMCP at all required device sizes)
-- `asc-privacy-manifest` (PrivacyInfo.xcprivacy)
-- Then `fastlane` for code signing + TestFlight upload.
+If the user opts to ship: run the iOS `asc-*` pipeline. The per-agent wiring for Phase 7 lives in `commands/build.md` §Phase 7 — the iOS branch here only names the role slots:
+
+- App Store Connect listing + keywords + description → `subagent_type: marketing-app-store-optimizer` (dispatch lives in `commands/build.md` Phase 7). The `asc-metadata-generator`, `asc-screenshot-generator`, and `asc-privacy-manifest` items below are skill bundles the optimizer pulls in, not standalone agents.
+- `asc-metadata-generator` (skill — App Store Connect listing + keywords + description, loaded by marketing-app-store-optimizer)
+- `asc-screenshot-generator` (skill — generate App Store screenshots via XcodeBuildMCP at all required device sizes)
+- `asc-privacy-manifest` (skill — PrivacyInfo.xcprivacy)
+- iOS app review sanity check → `subagent_type: ios-app-review-guardian` before TestFlight upload — catches rejection risks (IAP rules, HIG violations, entitlement issues, metadata problems).
+- Code signing + TestFlight upload → `subagent_type: engineering-devops-automator` with `fastlane` as the underlying tool.
 
 This is SEPARATE from the web ship pipeline — do NOT run web README/deployment steps. Documentation = README with simulator run instructions + TestFlight invite link (if shipped). Skip Step 7.1 web docs and web deployment notes.

package/protocols/launch-readiness.md

@@ -0,0 +1,258 @@
+# Launch Readiness Review Protocol
+
+You are the orchestrator. You are about to run a Launch Readiness Review (LRR) — a multi-chapter, independent-verdict gate that sits between the Phase 6 Reality Check and Phase 7.
+
+## Purpose
+
+LRR replaces the monolithic Reality Checker verdict with five independent chapter verdicts plus a mechanical aggregator.
+
+## Chapters
+
+LRR runs **five chapters**: Eng-Quality, Security, SRE, A11y, and Brand Guardian.
+
+Requirements coverage is evaluated as a sub-input of the Eng-Quality chapter. There is no separate PM chapter, no `pm.json` file, and the LRR Aggregator runs exactly once. The Eng-Quality chapter agent reads the Design Doc + `sprint-tasks.md` MVP scope directly alongside its other evidence and emits COVERED/PARTIAL/MISSING per feature inline on its own verdict (see the `requirements_coverage` field in the schema below). There is no separate Step 7.0 dispatch and no Aggregator re-run.
+
+### Primary evidence inputs
+
+| Chapter | Primary evidence inputs |
+|---|---|
+| Eng-Quality | `architecture.md`, `task-outputs/`, `verify.md` check outputs, test results, eval results, Design Doc + `sprint-tasks.md` MVP scope (read directly for the Requirements Coverage sub-input) |
+| Security | `evidence/fake-data-audit.md`, Phase 5 security audit output, eval-harness security cases |
+| SRE | Phase 5 performance-audit outputs, Performance Benchmarker evidence, NFRs from `sprint-tasks.md`, reliability checks |
+| A11y | Phase 5 a11y audit output, Phase 3.7 `a11y-design-review.md`, WCAG 2.2 AA runtime findings, per-page accessibility findings |
+| Brand Guardian | `docs/plans/visual-design-spec.md`, `docs/plans/visual-dna.md`, `docs/plans/design-references.md`, Playwright screenshots under `docs/plans/evidence/` matching product pages |
+
+## Chapter verdict schema
+
+Each chapter agent runs fresh-context, reads its own slice of the evidence manifest, and writes a verdict file with this shape:
+
+```json
+{
+  "chapter": "eng-quality | security | sre | a11y | brand-guardian",
+  "verdict": "PASS | CONCERNS | BLOCK",
+  "override_blocks_launch": false,
+  "evidence_files_read": ["docs/plans/evidence/..."],
+  "findings": [
+    {"severity": "block|concern|info", "description": "...", "evidence_ref": "path", "related_decision_id": "D-2-03"}
+  ],
+  "follow_up_spawned": false,
+  "follow_up_findings": null
+}
+```
+
+The **Eng-Quality** chapter additionally carries the Requirements Coverage sub-input inline on its verdict:
+
+```json
+{
+  "requirements_coverage": [
+    {"feature": "string", "status": "COVERED | PARTIAL | MISSING", "note": "optional string"}
+  ]
+}
+```
+
+This field carries the PM coverage signal directly on the Eng-Quality verdict — there is no separate `pm.json` file and no separate PM dispatch. The Eng-Quality chapter agent reads the Design Doc + `sprint-tasks.md` MVP scope as part of its own evidence sweep and emits the coverage list alongside its code-quality judgment.
+
+<HARD-GATE>
+SCHEMA CONTRACT:
+
+- `verdict` MUST be one of `PASS | CONCERNS | BLOCK`. `CONCERNS` means "I have concerns but won't block" and is aggregated as NEEDS WORK. `BLOCK` means "this fails my chapter's criteria" and is aggregated as NEEDS WORK unless `override_blocks_launch: true`.
+- `override_blocks_launch: true` is a veto-of-vetoes — no other chapter's PASS can override it. Only legal when `verdict == BLOCK`.
+- `evidence_files_read` MUST be non-empty. A verdict file with empty `evidence_files_read` is treated as malformed. "Looks good to me" verdicts are not permitted.
+- `follow_up_spawned` is only legal for the **Security** and **SRE** chapters. Brand Guardian and A11y chapters CANNOT spawn follow-ups — they render their verdict on what they can read and write it directly.
+</HARD-GATE>
+
+## A11y chapter rules
+
+The A11y chapter gates on WCAG 2.2 AA runtime findings from the Phase 5 accessibility audit and the Phase 3.7 a11y design review.
+
+- **PASS** if: zero Critical findings AND zero Serious findings AND zero failed WCAG 2.2 AA success criteria (runtime-measurable ones).
+- **CONCERNS** if: zero Critical AND 1-3 Serious findings (reviewable but not blocking).
+- **BLOCK** if: any Critical finding OR >3 Serious findings OR any failed WCAG 2.2 AA success criterion.
+
+Runtime measurement is required — spec-only compliance is not sufficient. Evidence must come from a Playwright + axe-core sweep (or equivalent) run against the actual built product pages, not the design system route alone.
+
+## Brand Guardian chapter rules
+
+The Brand Guardian chapter gates on **DNA drift** — did the built product stay true to the 6-axis Visual DNA locked at Phase 3.0?
+
+Prepend this anti-sycophancy preamble **verbatim** to the chapter dispatch prompt (stolen from ECC `gan-evaluator`):
+
+> "Your natural tendency is to be encouraging. Fight it. Default verdict: NEEDS WORK. You are not here to validate — you are here to find the gap."
+
+The chapter agent reads: `docs/plans/visual-dna.md` (the locked DNA card), `docs/plans/visual-design-spec.md`, `docs/plans/design-references.md`, and Playwright screenshots under `docs/plans/evidence/` matching **product pages** (not just `/design-system`).
+
+Scoring — 6 DNA axes (20 pts each = 120) + 5 craft dimensions (20 pts each = 100) = **220 total**, target **≥ 180**.
+
+- **PASS** if: DNA score ≥ 180 AND craft score ≥ 75 AND no single axis scoring < 12/20.
+- **CONCERNS** if: DNA score 150-179 OR any single axis scoring 10-12/20.
+- **BLOCK** if: DNA score < 150 OR any axis scoring < 10/20.
+
+Every finding must cite a specific element with a `file:line` reference and reference either the DNA card or a `design-references.md` path. Vague findings ("the hero needs work") are not admissible — they are rejected by the Aggregator's schema check and the verdict defaults to CONCERNS. Brand Guardian is forbidden from rubber-stamping.
+
+## Follow-up investigation flow (Security and SRE only)
+
+Security and SRE — and only these chapters — may spawn one read-only follow-up investigation per LRR round. Eng-Quality, A11y, and Brand Guardian render their verdict on what they can read and rely on the existing NEEDS_WORK loop when concerns arise.
+
+The trigger is now tightened: follow-ups fire **only on a BLOCK verdict**. The previous "or suspicious, need to verify" escape hatch is gone — suspicion without a BLOCK is recorded as a CONCERNS verdict, not as a follow-up spawn.
+
+```
+Security/SRE chapter agent runs → reads evidence manifest + 2-3 targeted files
+  |
+  If verdict = PASS or CONCERNS → write lrr/{chapter}.json, done (1 dispatch)
+  |
+  If verdict = BLOCK → CAN spawn ONE follow-up (no longer legal on "suspicion")
+  |
+  Follow-up agent spawned with:
+    - Mode: read-only (no Write, no Edit, no Bash write ops)
+    - Allowed tools: Read, Grep, Glob
+    - Max tool calls: 15 (enforced via prompt + self-report)
+    - Scope: single named concern from parent chapter's findings
+    - Returns typed JSON (see below)
+  |
+  Parent chapter reads follow-up output + its own earlier findings,
+  validates follow-up schema, writes FINAL lrr/{chapter}.json with
+  follow_up_findings populated.
+```
+
+### Follow-up return schema
+
+```json
+{
+  "confirmed": true,
+  "evidence": ["path1", "path2"],
+  "findings": [
+    {"severity": "block|concern|info", "description": "...", "evidence_ref": "path"}
+  ],
+  "tool_calls_used": 12
+}
+```
+
+<HARD-GATE>
+HARD CAPS ON FOLLOW-UPS:
+
+- **Max 1 follow-up per chapter per LRR round.** No follow-ups spawning follow-ups — investigation chains are banned because that is where dispatch counts actually explode.
+- **Read-only.** Allowed tools: Read, Grep, Glob. No Write, no Edit, no Bash write ops. If the follow-up finds a real fix, it documents it — the fix is executed in a separate Phase 6 NEEDS_WORK cycle, never inline.
+- **15 tool call cap, self-reported via `tool_calls_used`.** Parent chapter validates `tool_calls_used <= 15` before accepting the follow-up output.
+- **Only Security and SRE have the power.** Eng-Quality, A11y, and Brand Guardian chapters with concerns write a CONCERNS verdict; they do not spawn follow-ups.
+- **BLOCK-only trigger.** A follow-up can only be spawned when the parent chapter's verdict is BLOCK. Concerns without a BLOCK are logged as CONCERNS; they do not justify a second dispatch.
+</HARD-GATE>
+
+## Fallback on malformed or timed-out follow-up
+
+<HARD-GATE>
+DEFAULT: HARD BLOCK WITH `override_blocks_launch: true`.
+
+If a Security/SRE follow-up times out, returns invalid JSON, or reports `tool_calls_used > 15`, the parent chapter writes:
+
+```json
+{
+  "chapter": "security|sre",
+  "verdict": "BLOCK",
+  "reason": "follow_up_malformed",
+  "override_blocks_launch": true,
+  "detail": "Follow-up returned {timeout|invalid_json|cap_violation} — cannot verify security/reliability claim, blocking per pessimistic default"
+}
+```
+
+A security or reliability check that cannot produce a typed result is itself a signal — pessimistic-block is the only safe default. You cannot ship a build whose security check is unverifiable.
+</HARD-GATE>
+
+## LRR Aggregator
+
+The Reality Checker keeps its evidence-manifest sweep role but its verdict generation is replaced by LRR aggregation. The Aggregator now runs a **5-step flow**: file-completeness checkpoint → apply the 6 rules → BLOCK routing via the decision log → classification for NEEDS WORK findings → READY handoff.
+
+### Step 1: File-completeness checkpoint (NEW barrier)
+
+Before applying any aggregation rule, the Aggregator MUST Glob `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`
+
+The Aggregator does **not** expect or read any `pm.json` file. Requirements coverage lives inline on the Eng-Quality verdict (`requirements_coverage` field) and is not a separate artifact.
+
+If any of the 5 required files are missing, OR any file fails to parse as valid JSON, OR any file is missing required schema fields (`chapter`, `verdict`, non-empty `evidence_files_read`), the Aggregator:
+
+1. Logs `LRR INCOMPLETE: missing [filename] / malformed [filename]` to `docs/plans/build-log.md`.
+2. Writes `docs/plans/evidence/lrr-aggregate.json` with `combined_verdict = INCOMPLETE` and the list of missing/malformed files.
+3. STOPS — does **NOT** proceed to the 6 aggregation rules.
+
+This is the partial-glob race fix — the explicit roster check makes the race impossible: the Aggregator fails loudly instead of silently under-counting.
+
+### Step 2: Apply the 6 aggregation rules
+
+Once all 5 chapter files are present and parseable, the Aggregator applies these rules:
+
+1. **ANY `override_blocks_launch: true`** → `combined_verdict = BLOCKED`, regardless of other verdicts. This is the veto-of-vetoes rule.
+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`, with that chapter's findings routed into the existing fix-and-retest loop.
+4. **ANY verdict `CONCERNS`** → `combined_verdict = NEEDS WORK`, concerns logged to `build-log.md` for later triage.
+5. **Follow-up spawned AND `follow_up.confirmed: true`** → treat the parent chapter's verdict as if it were `BLOCK` (since the follow-up confirmed the concern).
+6. **Contradictions between chapters on typed fields** → `combined_verdict = BLOCKED` with the specific finding `cross-chapter contradiction: {field} differs between {chapter_a} and {chapter_b}`.
+
+Rule 6 detects cross-chapter conflicts mechanically on typed fields only — no chapter reads another's draft, preserving fresh-context independence.
+
+### Step 3: BLOCK routing via `decisions.jsonl` `decided_by` lookup
+
+When the Aggregator determines `combined_verdict = BLOCKED` or `NEEDS WORK` via a BLOCK finding, it MUST NOT stop and wait. Instead:
+
+1. For each BLOCK finding in the aggregated output, read the `related_decision_id` field on the finding.
+2. Read `docs/plans/decisions.jsonl` and find the row with that `decision_id`.
+3. Read the `decided_by` field — this is the phase that authored the original decision (e.g., `architect` or `design-brand-guardian`). Cross-reference with the `phase` field on the row to disambiguate between phases that share a `decided_by` value.
+4. Route the finding BACKWARD to that phase as re-entry input. The build resumes at that phase with the BLOCK finding as a correction signal.
+
+If no `related_decision_id` is present on the finding (legacy finding, or a non-decision-backed issue such as a runtime crash or a fresh test failure), fall back to the legacy routing: classify by severity and route to Phase 4 (code-level) or Phase 2 (structural) per Step 4 below.
+
+This replaces "BLOCKED → return to failing step" with author-aware re-entry — a BLOCK on an auth model flaw routes to the Phase 2 architecture synthesizer who authored the decision, not the Phase 4 implementer.
+
+### Step 4: Classification for NEEDS WORK findings
+
+For any NEEDS WORK findings that did not carry a `related_decision_id` (and therefore fell through Step 3's `decided_by` lookup), the Aggregator applies the existing legacy classification:
+
+- **code-level** findings (test failure, runtime error, lint/type error, per-file bug) → route to Phase 4 target task.
+- **structural** findings (architectural mismatch, API contract violation, persistence model error, DNA drift at the component-library layer) → route to Phase 2 or Phase 3 per the finding's domain.
+- **CONCERNS** entries (no BLOCK) → logged to `build-log.md` for triage, do not block launch on their own.
+
+### Step 5: READY handoff
+
+If Step 2 resolves to `combined_verdict = PRODUCTION READY`, the Aggregator writes `docs/plans/evidence/lrr-aggregate.json` with the combined verdict, per-chapter summaries, and forwards to Phase 7 (Launch). No backward routing is triggered — the build moves forward.
+
+## File paths
+
+- Chapter verdicts: `docs/plans/evidence/lrr/{eng-quality,security,sre,a11y,brand-guardian}.json`
+- Aggregator output: `docs/plans/evidence/lrr-aggregate.json`
+
+## Token budget
+
+~12-17K tokens per LRR cycle, net of PM fold-in: five chapter dispatches at 2-3K each, plus the nested `pr-test-analyzer` sub-dispatch inside Eng-Quality at ~1.5-2K, plus one aggregator at 1-2K. The Aggregator runs exactly once per cycle.
+
+
+## Design Notes (non-operational)
+
+### Rationale: single-verdict failure mode
+
+The current Reality Checker collapses code quality, security, reliability, accessibility, and product completeness into a single verdict from a single agent — the exact failure mode matrix organizations exist to prevent. Independence matters most for Security and SRE: production incidents from those chapters are asymmetric in consequence — a security finding that goes unchallenged is a breach; a reliability finding is an outage. That asymmetry justifies the extra dispatch power and the pessimistic-block fallback.
+
+### Structural shifts from the prior 5-chapter panel
+
+- **Eng and QA merged into Eng-Quality.** More than half of their evidence overlapped (tests, verify outputs, task-level quality signals), and two nearly-identical verdicts produced two-thirds the signal of one coherent view.
+- **A11y is a new seat.** The WCAG gap was the biggest coverage hole in the prior panel — a mechanical contrast field on the old Design chapter is not a runtime accessibility check.
+- **Brand Guardian replaces the Design mechanical check.** The prior Design chapter was a 15-line threshold on a Phase 3 metric score — theater, not judgment.
+
+### Why each chapter cannot be folded
+
+- **Eng-Quality:** Merged from the previous Eng+QA chapters because >50% of their evidence overlapped, which produced two near-identical verdicts instead of one stronger one.
+- **Security:** Production breach risk is asymmetric, so an independent chapter runs fresh-context against security evidence with the power to veto launch outright.
+- **SRE:** Now explicitly reads Performance Benchmarker evidence (previously unclear which chapter owned perf NFRs), plus reliability checks and NFR thresholds from `sprint-tasks.md`.
+- **A11y:** The prior Design chapter had a mechanical contrast check and nothing runtime. A11y reads the Phase 5 runtime accessibility sweep and the Phase 3.7 design review, and gates on Critical/Serious finding counts.
+- **Brand Guardian:** Reads the locked DNA card + rendered screenshots + visual design spec + design references, and judges drift from the DNA. Taste judgment, not checklist theater.
+
+### Rule 6 — anchoring cost rationale
+
+A naive matrix-org design would have Security read Eng-Quality's draft to catch disagreements — that reintroduces the exact anchoring bias that fresh-context-per-chapter is designed to prevent (Madaan et al. Self-Refine; Gou et al. CRITIC). Instead, the aggregator does the cross-chapter check mechanically on typed fields only. Typed fields are mechanically diffable; free-form findings prose is not — and the prose is where the anchoring bias would come from.
+
+### Why under `evidence/`
+
+The existing evidence manifest sweep picks up anything under `docs/plans/evidence/` for free, and these files ARE evidence — typed attestations from independent chapters. Putting them elsewhere would create a second manifest path the aggregator has to know about separately.