buildanything 2.0.0 → 2.1.1

package/docs/migration/phase-graph.yaml

@@ -28,27 +28,126 @@ artifacts:
   - path: docs/plans/quality-targets.json
     writer: phase-2
     readers: [phase-4, phase-5, phase-6]
-  - path: docs/plans/visual-design-spec.md
-    platform: web
-    writer: phase-3
-    readers: [phase-4, phase-5, phase-6]
-  - path: docs/plans/ios-design-board.md
-    platform: ios
-    writer: phase-3
-    readers: [phase-4, phase-5, phase-6]
+  - path: docs/plans/phase-2-contracts/*.md
+    writer: phase-2
+    readers: [phase-2, phase-3]
+    notes: |
+      Per-architect post-debate contract files written by the 6 Phase-2.2b
+      teammates (backend, frontend, data, security, a11y, perf). Each file
+      captures the architect's initial decisions plus any peer-driven
+      revisions. Read by the Phase 2.3.1 Implementation Blueprint synthesizer.
+  - path: docs/plans/visual-dna-preview.md
+    writers: [phase-2, design-brand-guardian, ios-swift-ui-design]
+    readers: [phase-2, phase-3]
+    notes: |
+      Lightweight directional DNA preview surfaced at Gate 2. Web writer is
+      design-brand-guardian (protocols/web-phase-branches.md:33); iOS writer
+      is ios-swift-ui-design (protocols/ios-phase-branches.md:172). Agent-role
+      enforcement fires alongside the phase-2 phase-match so only the two
+      legitimate dispatching subagents can write this file. Discarded after
+      Gate 2 — Phase 3.0 re-invokes to produce the locked card.
+  - path: DESIGN.md
+    writers: [phase-3, design-brand-guardian, design-ui-designer, ios-swift-ui-design]
+    readers: [phase-3, phase-4, phase-5, phase-6]
+    notes: |
+      Single design-system artifact at repo root. Web + iOS. Replaces the
+      prior visual-dna.md + visual-design-spec.md pair (web) and
+      ios-design-board.md (iOS). Authored in two passes:
+      Step 3.0 (design-brand-guardian, both platforms) writes Pass 1 —
+      Overview, Brand DNA, Rationale, Locked At, References, Do's and Don'ts.
+      Pass 2 writer differs by platform: web uses design-ui-designer at
+      Step 3.4; iOS uses ios-swift-ui-design at Step 3.2-ios. Pass 2 fills
+      YAML tokens (colors, typography, rounded, spacing, components) plus
+      the prose for Colors, Typography, Layout, Elevation & Depth, Shapes,
+      Components. Format spec is vendored at protocols/design-md-spec.md
+      (Apache 2.0). Pipeline contract is in protocols/design-md-authoring.md
+      (§9 covers the iOS schema). Agent-role enforcement fires alongside
+      the phase-3 phase-match so only the three legitimate authoring
+      subagents can write this file.
   - path: docs/plans/component-manifest.md
     platform: web
     writer: phase-3
     readers: [phase-4]
     notes: HARD-GATE import source
-  - path: docs/plans/visual-dna.md
+  - path: docs/plans/design-references.md
+    platform: web
+    writer: visual-research
+    readers: [phase-3, phase-4, phase-6-brand-guardian]
+    notes: |
+      Reference paths grouped by DNA axis. Written by the 2 parallel
+      visual-research subagents at Step 3.1 (competitive-audit + inspiration-
+      mining modes — both append).
+  - path: docs/plans/design-references/**
+    platform: web
+    writer: visual-research
+    readers: [phase-3, phase-4, phase-6-brand-guardian]
+    notes: |
+      Screenshots harvested by visual-research subagents — competitors/,
+      inspiration/, plus mode-keyed subdirs. Binary assets referenced from
+      design-references.md; gate must cover non-markdown file types.
+  - path: docs/plans/dna-persona-check.md
+    platform: web
+    writer: design-ux-researcher
+    readers: [phase-3, phase-3-brand-guardian]
+    notes: |
+      Step 3.2b persona/DNA cross-check. Mismatches may backward-edge to
+      Step 3.0 (DNA re-lock). Agent-role writer pinned to
+      design-ux-researcher per protocols/web-phase-branches.md.
+  - path: docs/plans/ux-architecture.md
     platform: web
     writer: phase-3
-    readers: [phase-3, phase-4, phase-5, phase-6]
+    readers: [phase-3, phase-4, phase-5]
+  - path: docs/plans/ux-flow-validation.md
+    platform: web
+    writer: design-ux-researcher
+    readers: [phase-3, phase-4, phase-5]
+    notes: |
+      Step 3.3b persona-driven flow validation. Flags friction points
+      and unnecessary screens before the Visual Design Spec is built.
+  - path: docs/plans/inclusive-visuals-audit.md
+    platform: web
+    writer: phase-3
+    readers: [phase-3, phase-5, phase-6]
+  - path: docs/plans/a11y-design-review.md
+    platform: web
+    writers: [phase-3, a11y-architect]
+    readers: [phase-5, phase-6-a11y-chapter]
+    notes: |
+      Phase 3.7 WCAG 2.2 AA design-time review. Written by a11y-architect
+      acting as Phase 3 step owner (protocols/web-phase-branches.md:151);
+      agent-role enforcement fires alongside the phase-3 phase-match. LRR
+      A11y chapter reads this plus the Phase 5 runtime audit per
+      protocols/launch-readiness.md.
+  - path: docs/plans/page-specs/*.md
+    platform: web
+    writer: design-ux-architect
+    readers: [phase-4, phase-5, phase-6]
+    notes: |
+      Per-screen wireframes + layout specs written at Step 3.3 by
+      design-ux-architect. ASCII wireframes + content hierarchy + key copy
+      + responsive behavior + data loading strategy. One file per screen
+      from the product-spec Screen Inventory. Follows
+      protocols/page-spec-schema.md.
   - path: docs/plans/refs.json
-    writer: phase-2
-    extended_by: phase-3
+    writers: [phase-2, phase-3]
     readers: [phase-4-briefing-officer]
+    notes: |
+      Phase 2 Refs Indexer writes the initial anchor index after architecture.md
+      lands. Phase 3 extends it after DESIGN.md lands (see
+      commands/build.md:167). Both phases are legitimate writers.
+  - path: docs/plans/feature-delegation-plan.json
+    writer: product-owner
+    readers: [orchestrator, briefing-officer]
+    notes: |
+      Feature delegation plan written by the Product Owner at Step 4.1.
+      Contains wave assignments, feature priorities, and acceptance criteria.
+  - path: docs/plans/feature-briefs/*.md
+    writers: [briefing-officer]
+    readers: [orchestrator, phase-4-execution-agents]
+    notes: |
+      Per-feature briefs written by the Briefing Officer at Step 4.2
+      (one per feature per wave). Consumed by the orchestrator-driven
+      per-task pipeline during wave execution.
   - path: docs/plans/decisions.jsonl
     writer: orchestrator-scribe
     write_mode: append-only
@@ -57,21 +156,136 @@ artifacts:
   - path: docs/plans/learnings.jsonl
     writers: [phase-5, phase-7]
     readers: [phase-0-learnings-loader, phase-5-reality-sweep]
+  - path: docs/plans/evidence/product-reality/{feature_id}/results.json
+    platform: web
+    writer: product-reality-auditor
+    readers: [phase-5-feedback-synthesizer, phase-6-eng-quality]
+    notes: |
+      Per-feature pass/fail evidence from Track B audit. Schema in
+      agents/product-reality-auditor.md.
+  - path: docs/plans/evidence/product-reality/{feature_id}/findings.json
+    platform: web
+    writer: product-reality-auditor
+    readers: [phase-5-feedback-synthesizer]
+    notes: |
+      Per-feature failures with target_phase pre-set by auditor;
+      synthesizer validates and passes through.
+  - path: docs/plans/evidence/product-reality/{feature_id}/coverage.json
+    platform: web
+    writer: product-reality-auditor
+    readers: [phase-6-eng-quality]
+    notes: |
+      Per-feature {COVERED|PARTIAL|MISSING} verdict. LRR Eng-Quality
+      reads these (one per feature) instead of recomputing.
+  - path: docs/plans/evidence/product-reality/{feature_id}/tests-generated.md
+    platform: web
+    writer: product-reality-auditor
+    readers: [phase-5-feedback-synthesizer, phase-6-eng-quality]
+    notes: |
+      Synthesized agent-browser scripts (one block per check case).
+      Provides debug context when results.json shows FAIL.
+  - path: docs/plans/evidence/product-reality/{feature_id}/results.json
+    platform: ios
+    writer: ios-product-reality-auditor
+    readers: [phase-5-feedback-synthesizer, phase-6-eng-quality]
+    notes: |
+      iOS Track B per-feature pass/fail evidence. Same schema as web
+      product-reality-auditor but driven by XcodeBuildMCP + Maestro.
+  - path: docs/plans/evidence/product-reality/{feature_id}/findings.json
+    platform: ios
+    writer: ios-product-reality-auditor
+    readers: [phase-5-feedback-synthesizer]
+  - path: docs/plans/evidence/product-reality/{feature_id}/coverage.json
+    platform: ios
+    writer: ios-product-reality-auditor
+    readers: [phase-6-eng-quality]
+  - path: docs/plans/evidence/product-reality/{feature_id}/tests-generated.md
+    platform: ios
+    writer: ios-product-reality-auditor
+    readers: [phase-5-feedback-synthesizer, phase-6-eng-quality]
+    notes: |
+      Synthesized Maestro YAML flows (one block per check case).
+  - path: docs/plans/evidence/track-a/*.json
+    writers: [phase-5, testing-api-tester, testing-performance-benchmarker, a11y-architect, engineering-security-engineer]
+    readers: [phase-5-feedback-synthesizer, phase-6]
+    notes: |
+      Track A engineering audit evidence. Web and iOS both write here.
+      Per-auditor files: api-contract.json, performance.json,
+      accessibility.json, security.json.
   - path: docs/plans/evidence/*.json
     writer: phase-5
     contributors: [phase-4]
     readers: [phase-6, phase-7]
+  - path: docs/plans/evidence/*.md
+    writers: [phase-5, design-brand-guardian, silent-failure-hunter]
+    readers: [phase-5, phase-6, phase-7]
+    notes: |
+      Top-level evidence markdown (fake-data-audit.md, brand-drift findings
+      outside a nested dir, etc.). Matched explicitly because the **/*.md
+      glob requires an intermediate directory segment.
+      design-brand-guardian is named explicitly as the Phase 5.1 writer of
+      brand-drift.md (commands/build.md:806, protocols/web-phase-branches.md:251);
+      silent-failure-hunter writes fake-data-audit.md (commands/build.md:984);
+      agent-role enforcement fires alongside the phase-5 phase-match.
+  - path: docs/plans/evidence/**/*.json
+    writers: [phase-4, phase-5, phase-6, ios-product-reality-auditor]
+    readers: [phase-6, phase-7]
+    notes: |
+      Nested per-task / per-run evidence JSON (smoke-test HAR analysis,
+      e2e iter-3 results, dogfood classified findings, product-reality
+      per-feature results/findings/coverage, maestro run summaries).
+      eval-harness baseline/final files are no longer Phase 5 primary
+      outputs (Phase 5 restructured into Track A/B as of 2026-05-01) but
+      the eval-harness service is still callable ad-hoc from Step 5.5
+      fixes. Top-level evidence/*.json kept separate above for the
+      phase-5 writer narrowing.
+  - path: docs/plans/evidence/**/*.md
+    writers: [phase-4, phase-5, ios-product-reality-auditor]
+    readers: [phase-5, phase-6, phase-7]
+    notes: |
+      Nested per-task / per-run evidence markdown (brand-drift.md,
+      fake-data-audit.md, dogfood/findings.md, per-task smoke-test notes).
+  - path: docs/plans/evidence/**/*.png
+    writers: [phase-3, phase-4, phase-5, ios-product-reality-auditor]
+    readers: [phase-5, phase-6, phase-7]
+    notes: |
+      Playwright screenshots, SwiftUI Preview captures, Maestro run captures,
+      design-reference screenshots. Written across multiple phases.
+  - path: docs/plans/evidence/**/*.{txt,har}
+    writers: [phase-4, phase-5]
+    readers: [phase-5, phase-6]
+    notes: |
+      Smoke-test evidence per protocols/smoke-test.md (HAR captures,
+      DOM snapshots, uncaught-exception logs).
   - path: docs/plans/evidence/lrr/*.json
-    writers: [code-reviewer, security-reviewer, engineering-sre, a11y-architect, design-brand-guardian]
+    writers: [code-reviewer, security-reviewer, engineering-sre, a11y-architect, design-brand-guardian, pr-test-analyzer]
     readers: [phase-6-aggregator, orchestrator]
     notes: |
-      One file per LRR chapter. Writer set = the 5 chapter subagents (aka
-      "chapter-judge" role per MIGRATION-PLAN-FINAL §Stage 5). Aggregator and
-      orchestrator are READ-ONLY on chapter files. Enforced agent-role match
-      in hooks/pre-tool-use.ts against subagent_type staged by subagent-start.
+      5 chapter verdict files (one per chapter subagent, aka "chapter-judge"
+      role per MIGRATION-PLAN-FINAL §Stage 5) plus 1 sub-verdict file:
+      pr-test-analyzer writes eng-quality-coverage.json as a parallel
+      sub-dispatch from the Eng-Quality chapter (commands/build.md Step 6.1);
+      code-reviewer reads that file and folds its findings into eng-quality.json.
+      Aggregator and orchestrator are READ-ONLY on every file in this dir.
+      Enforced agent-role match in hooks/pre-tool-use.ts against subagent_type
+      staged by subagent-start.
   - path: docs/plans/evidence/lrr-aggregate.json
     writer: phase-6-aggregator
     readers: [phase-7]
+  - path: docs/plans/evidence/lrr-incomplete.json
+    writer: phase-6-aggregator
+    readers: [orchestrator, user]
+    notes: File-completeness checkpoint output per protocols/launch-readiness.md Step 1.
+  - path: docs/plans/evidence/lrr-routing.json
+    writer: phase-6-aggregator
+    readers: [orchestrator]
+    notes: BLOCK routing via decided_by per commands/build.md Phase 6.2 STEP 4.
+  - path: docs/plans/evidence/reality-check-manifest.json
+    writer: testing-reality-checker
+    readers: [phase-6-aggregator, phase-7]
+    notes: |
+      Evidence-sweep manifest per commands/build.md Phase 6.0. Reality
+      Checker no longer issues combined_verdict (moved to LRR Aggregator).
   - path: docs/plans/.build-state.json
     writer: orchestrator
     write_frequency: every-phase-boundary
@@ -87,6 +301,26 @@ artifacts:
     writer: every-phase
     write_mode: append-on-transition
     readers: [user, resume]
+  - path: docs/plans/.active-learnings.md
+    writer: phase-0
+    readers: [phase-4-implementer]
+    notes: |
+      Top-3 cross-run learnings filtered at Step 0.1d and injected into
+      Phase 4 implementer briefings per protocols/decision-log.md.
+  - path: docs/plans/ios-verify-report.md
+    platform: ios
+    writer: phase-5
+    readers: [phase-6]
+    notes: |
+      Written by the /buildanything:verify iOS twin (Phase 5 dispatch).
+      Required before Phase 6 on iOS per protocols/ios-phase-branches.md.
+  - path: docs/plans/ios-ux-review-report.md
+    platform: ios
+    writer: phase-5
+    readers: [phase-6]
+    notes: |
+      Written by the /buildanything:ux-review iOS twin (Phase 5 dispatch).
+      Required before Phase 6 on iOS per protocols/ios-phase-branches.md.
 
 phase_internal_scratch:
   path_glob: docs/plans/phase1-scratch/*.{md,json}
@@ -100,8 +334,10 @@ phase_internal_scratch:
     - suggested-questions.md
     - user-decisions.md
     - prereqs.json
-  readers: [phase-1-only]
-  notes: Never read by phase 3+.
+  readers: [phase-1-only, phase-1.6-product-spec]
+  notes: |
+    SPENT after Step 1.6 (Product Spec). The product spec is the last
+    consumer of raw research files. Never read by Phase 3+.
 
 # ---------------------------------------------------------------------------
 # 2. Classification matrix
@@ -397,11 +633,18 @@ phases:
       source: protocols/web-phase-branches.md
       steps:
         - id: "3.0"
-          name: Visual DNA Selection
+          name: DESIGN.md Pass 1 — Brand DNA + Overview + Do's and Don'ts
           kind: dispatch-single
           subagent_type: design-brand-guardian
-          produces: 6-axis DNA card (Scope, Density, Character, Material, Motion, Type)
-          source: protocols/visual-dna.md
+          produces: |
+            DESIGN.md Pass 1 at repo root — Overview prose + ### Brand DNA
+            (7 axis values: Scope, Density, Character, Material, Motion, Type,
+            Copy) + Rationale + Locked At + References + Do's and Don'ts.
+            Pass 2 sections present as placeholder headings. YAML front
+            matter contains version + name only.
+          source: protocols/design-md-authoring.md
+          format_spec: protocols/design-md-spec.md
+          writes: [DESIGN.md]
         - id: "3.1"
           name: Visual Research (2 parallel, Playwright-driven)
           kind: dispatch-parallel
@@ -419,17 +662,39 @@ phases:
           subagent_type: design-ux-researcher
           may_route_to: "3.0"
         - id: "3.3"
-          name: UX Architecture
+          name: UX Architecture + Page Layouts
           kind: dispatch-single
           subagent_type: design-ux-architect
-          writes: [ux-architecture.md]
+          reads: [product-spec.md, DESIGN.md, component-manifest.md, architecture.md, design-references/]
+          writes: [ux-architecture.md, docs/plans/page-specs/*.md]
+          notes: |
+            Merged Step 3.3 + former Step 3.9 (Option C). Produces both
+            UX architecture (flows, navigation, IA) AND per-screen ASCII
+            wireframes + structured layout specs together. Flows and layouts
+            inform each other. Follows protocols/page-spec-schema.md.
+            One file per screen from product-spec Screen Inventory.
+        - id: "3.3b"
+          name: UX Flow Validation
+          kind: dispatch-single
+          dispatches: [design-ux-researcher]
+          reads: [docs/plans/ux-architecture.md, docs/plans/page-specs/, docs/plans/product-spec.md, docs/plans/design-doc.md, DESIGN.md]
+          writes: [docs/plans/ux-flow-validation.md]
+          backward_edges:
+            - from: critical-flow-issues
+              to: phase-3.step-3.3
         - id: "3.4"
-          name: Visual Design Spec
+          name: DESIGN.md Pass 2 — Tokens + remaining prose
           kind: dispatch-single
           subagent_type: design-ui-designer
           role: writer
-          writes: [visual-design-spec.md]
-          contains: [tokens, material, motion, typography, state-matrix]
+          writes: [DESIGN.md]
+          contains: [yaml-tokens, colors, typography, layout, elevation, shapes, components, motion-as-h3, component-state-matrix-via-variants]
+          source: protocols/design-md-authoring.md
+          gate: |
+            DESIGN.md lint runs at Step 3.8. broken-refs == 0 is hard-fail.
+            Warnings (missing-primary, contrast-ratio WCAG AA, orphaned-tokens,
+            missing-typography, section-order) are logged to build-log.md but
+            do not block.
         - id: "3.5"
           name: Inclusive Visuals Check
           kind: dispatch-single
@@ -441,8 +706,9 @@ phases:
           service: metric-loop
           generator: engineering-frontend-developer
           critic: design-critic
-          metric: 6-DNA-axes x 5-craft-dims = /220
-          target: 180
+          metric: 7-DNA-axes (140) + 5-craft-dims (100) = /240
+          target: 195
+          approaching_threshold: 163
           max_iterations: 5
         - id: "3.7"
           name: A11y Design Review
@@ -458,12 +724,22 @@ phases:
         - UI/UX IS THE PRODUCT — do NOT skip this phase.
         - Compositional not reconstructive — every element with a library variant MUST be mapped to that variant in component-manifest.md.
       phase_4_entry_requirements:
-        - visual-dna.md
-        - visual-design-spec.md
+        - DESIGN.md (Pass 1 + Pass 2 complete; broken-refs lint == 0)
         - component-manifest.md
+        - page-specs/ (at least one file)
     ios_branch:
       source: protocols/ios-phase-branches.md
       steps:
+        - id: "3.0"
+          name: DESIGN.md Pass 1 — Brand DNA + Overview + Do's and Don'ts (shared with web)
+          kind: dispatch-single
+          subagent_type: design-brand-guardian
+          writes: [DESIGN.md]
+          notes: |
+            Same dispatch as web Step 3.0. Brand Guardian writes Pass 1
+            (Overview + 7-axis Brand DNA + Rationale + Locked At + References
+            + Do's and Don'ts). Pass 2 sections are placeholders. iOS-specific
+            Material gating (Liquid Glass requires iOS 26+ target) honored.
         - id: "3.1-ios"
           name: Visual research
           kind: dispatch-single
@@ -472,11 +748,35 @@ phases:
           sources: [screenlane.com, App Store web listings, Apple HIG pages, SF Symbols browser]
           constraints: [no paid sources]
         - id: "3.2-ios"
-          name: iOS Design Board
+          name: DESIGN.md Pass 2 — iOS YAML tokens + remaining prose
           kind: dispatch-single
           subagent_type: ios-swift-ui-design
-          writes: [ios-design-board.md]
-          grounded_in: [HIG, Liquid Glass, SF Symbols]
+          role: writer
+          writes: [DESIGN.md]
+          contains: [yaml-tokens, colors-with-dark-pairs, typography-as-DynamicType-roles, rounded, spacing, components-iOS-vocabulary, motion-as-h3, component-state-matrix-via-variants]
+          source: protocols/design-md-authoring.md
+          grounded_in: [HIG, Liquid Glass (iOS 26+), SF Symbols, design-references.md]
+        - id: "3.3-ios"
+          name: UX Architecture + Page Layouts (iOS)
+          kind: dispatch-single
+          subagent_type: design-ux-architect
+          reads: [product-spec.md, DESIGN.md, architecture.md, design-references/]
+          writes: [ux-architecture.md, docs/plans/page-specs/*.md]
+          notes: |
+            iOS page-specs use single mobile-first ASCII wireframes (iPhone 16 Pro
+            393x852), HIG navigation annotations, DESIGN.md component token refs,
+            Dynamic Type role declarations, and safe-area handling per screen.
+            Same agent as web Step 3.3 — design-ux-architect platform-gates via
+            skill bundle.
+        - id: "3.3b-ios"
+          name: UX Flow Validation (iOS)
+          kind: dispatch-single
+          dispatches: [design-ux-researcher]
+          reads: [docs/plans/ux-architecture.md, docs/plans/page-specs/, docs/plans/product-spec.md, docs/plans/design-doc.md, DESIGN.md]
+          writes: [docs/plans/ux-flow-validation.md]
+          backward_edges:
+            - from: critical-flow-issues
+              to: phase-3.step-3.3-ios
         - id: "3.4-ios"
           name: Visual QA loop
           kind: loop
@@ -485,8 +785,18 @@ phases:
           critic: design-critic
           tooling: XcodeBuildMCP SwiftUI Preview captures
           max_iterations: 3
+        - id: "3.8-ios"
+          name: DESIGN.md lint gate
+          kind: gate
+          tooling: hooks/design-md-lint
+          rules: |
+            broken-refs == 0 hard-fails back to Step 3.2-ios.
+            Warnings logged. Plus iOS-specific post-process checks
+            (dark-pair rule, Dynamic Type role check, iOS 26 gating)
+            per protocols/design-md-authoring.md §9.5.
       phase_4_entry_requirements:
-        - ios-design-board.md
+        - DESIGN.md (Pass 1 + Pass 2 complete; broken-refs lint == 0)
+        - page-specs/ (at least one file from Step 3.3-ios)
 
   - id: "4"
     name: Build
@@ -502,8 +812,15 @@ phases:
         - id: "4.0.b"
           name: Design system setup
           kind: dispatch-single
-          web: {subagent_type: engineering-frontend-developer, produces: CSS tokens from visual-design-spec}
-          ios: {subagent_type: engineering-senior-developer, produces: SwiftUI Color/Font/ShapeStyle tokens from ios-design-board.md}
+          web: {subagent_type: engineering-frontend-developer, produces: CSS tokens from DESIGN.md (YAML front matter)}
+          ios:
+            subagent_type: engineering-senior-developer
+            produces: |
+              Sources/<target>/DesignTokens.swift per protocols/design-md-authoring.md §9.4
+              SwiftUI translator (Color extensions Asset Catalog–backed with -dark pairs,
+              Font extensions mapped to Font.TextStyle Dynamic Type roles, Spacing/Radius
+              enums as CGFloat constants). Also Resources/Assets.xcassets color sets per
+              colors: token with light + dark appearances.
         - id: "4.0.c"
           name: Acceptance test scaffolding
           kind: dispatch-single-internal
@@ -523,91 +840,135 @@ phases:
           kind: gate
           service: verify-protocol
           notes: 7 checks must PASS before Step 4.1
-    per_task_flow:
-      executes: every task in every dependency-ordered batch
-      parallelism: Independent sibling tasks run in parallel (~30-50% wall-clock saving)
-      sub_steps:
-        - id: briefing
-          kind: dispatch-single
-          subagent_type: briefing-officer-internal
-          reads: [refs.json, task-row]
-          writes: ~40-line CONTEXT MAP
-        - id: impl
-          kind: dispatch-single
-          dispatch_table:
-            web:
-              ui_SM: engineering-frontend-developer
-              ui_L: engineering-senior-developer
-              backend: engineering-backend-architect OR engineering-senior-developer
-              ai_ml: engineering-ai-engineer
-            ios:
-              ui_planner: ios-swift-ui-design
-              ui_impl: [engineering-senior-developer, engineering-mobile-app-builder]
-              foundation_models: ios-foundation-models-specialist
-              storekit: ios-storekit-specialist
-        - id: impl.re-entry
-          kind: dispatch-single
-          trigger: LRR backward-routing
-          inputs: [blocking_finding, prior_output, decision_row]
-          constraint: revise ONLY what finding requires
-        - id: sec-review
-          kind: dispatch-single
-          subagent_type: security-reviewer
-          conditional_on: [auth, PII, Keychain, credential tasks]
-        - id: swift-review
+    product_owner_planning:
+      steps:
+        - id: "4.1"
+          name: Product Owner planning
           kind: dispatch-single
-          platform: ios
-          subagent_type: swift-reviewer
-          checklist: [Swift concurrency 6.2, SwiftUI, protocol DI, Foundation Models]
-        - id: cleanup
-          kind: dispatch-parallel
-          parallel_count: 2
-          dispatches:
-            - code-simplifier
-            - refactor-cleaner
-          scope: changeset-only
-        - id: review
-          kind: dispatch-parallel
-          parallel_count: 2
-          dispatch_mode: single-message
-          dispatches:
-            - code-reviewer
-            - silent-failure-hunter
-          confidence_threshold: 80
-        - id: metric-loop
-          kind: loop
-          service: metric-loop
-          max_iterations: 5
-          notes: THIS IS THE AUTHORITATIVE BEHAVIORAL VERIFICATION
-          ui_tooling:
-            web: agent-browser
-            ios: SwiftUI Preview captures
-        - id: smoke
+          subagent_type: product-owner
+          reads: [sprint-tasks.md, architecture.md, design-doc.md]
+          writes: [docs/plans/feature-delegation-plan.json]
+          writes_state: [feature_delegation_plan_path, current_wave]
+          notes: |
+            Product Owner decomposes sprint tasks into features, assigns
+            wave priorities, and defines acceptance criteria per feature.
+            Sets current_wave=1 in build state.
+    wave_execution:
+      id: "4.2"
+      name: Wave execution
+      kind: wave-loop
+      notes: |
+        For each wave in the feature delegation plan:
+        1. Dispatch briefing-officer per feature in the wave (writes feature-briefs/{feature}.md)
+        2. Orchestrator-driven per-task pipeline per feature (unchanged mechanics from prior per_task_flow)
+      briefing:
+        kind: dispatch-single
+        subagent_type: briefing-officer
+        reads: [refs.json, feature-delegation-plan.json, task-rows-for-feature]
+        writes: [docs/plans/feature-briefs/*.md]
+      per_task_flow:
+        executes: every task in every dependency-ordered batch within the feature
+        parallelism: Independent sibling tasks run in parallel (~30-50% wall-clock saving)
+        sub_steps:
+          - id: impl
+            kind: dispatch-single
+            dispatch_table:
+              web:
+                ui_SM: engineering-frontend-developer
+                ui_L: engineering-senior-developer
+                backend: engineering-backend-architect OR engineering-senior-developer
+                ai_ml: engineering-ai-engineer
+              ios:
+                ui_planner: ios-swift-ui-design
+                ui_impl: [engineering-senior-developer, engineering-mobile-app-builder]
+                foundation_models: ios-foundation-models-specialist
+                storekit: ios-storekit-specialist
+          - id: impl.re-entry
+            kind: dispatch-single
+            trigger: LRR backward-routing
+            inputs: [blocking_finding, prior_output, decision_row]
+            constraint: revise ONLY what finding requires
+          - id: sec-review
+            kind: dispatch-single
+            subagent_type: security-reviewer
+            conditional_on: [auth, PII, Keychain, credential tasks]
+          - id: swift-review
+            kind: dispatch-single
+            platform: ios
+            subagent_type: swift-reviewer
+            checklist: [Swift concurrency 6.2, SwiftUI, protocol DI, Foundation Models]
+          - id: cleanup
+            kind: dispatch-parallel
+            parallel_count: 2
+            dispatches:
+              - code-simplifier
+              - refactor-cleaner
+            scope: changeset-only
+          - id: review
+            kind: dispatch-parallel
+            parallel_count: 2
+            dispatch_mode: single-message
+            dispatches:
+              - code-reviewer
+              - silent-failure-hunter
+            confidence_threshold: 80
+          - id: metric-loop
+            kind: loop
+            service: metric-loop
+            max_iterations: 5
+            notes: THIS IS THE AUTHORITATIVE BEHAVIORAL VERIFICATION
+            ui_tooling:
+              web: agent-browser
+              ios: SwiftUI Preview captures
+          - id: smoke
+            kind: dispatch-single
+            platform: ios
+            tooling: Maestro flow against booted simulator
+            preconditions: [Maestro CLI installed, flow files exist, booted simulator available]
+            on_precondition_fail: BLOCKED
+          - id: verify
+            kind: gate
+            service: verify-protocol
+            scope: static-only
+            checks: [type-check, lint, build]
+            max_fix_attempts: 3
+            build_fix:
+              ios: swift-build-resolver
+          - id: scribe
+            kind: internal
+            role: orchestrator-scribe
+            action: |
+              Walks batch_results, collects non-null deviation_row objects, and
+              invokes the scribe_decision MCP tool once per row. The MCP is the
+              single writer for decisions.jsonl — it allocates D-{phase}-<seq>
+              IDs, stamps timestamp + status, validates against
+              decisions.schema.json, and atomically appends. The orchestrator
+              MUST NOT Write/Edit decisions.jsonl directly and MUST NOT
+              pre-compute IDs. .build-state.json.decisions_next_id is
+              deprecated under Stage 2 and removed at Stage 4 A7.
+    product_owner_acceptance:
+      steps:
+        - id: "4.3"
+          name: Product Owner acceptance
           kind: dispatch-single
-          platform: ios
-          tooling: Maestro flow against booted simulator
-          preconditions: [Maestro CLI installed, flow files exist, booted simulator available]
-          on_precondition_fail: BLOCKED
-        - id: verify
-          kind: gate
-          service: verify-protocol
-          scope: static-only
-          checks: [type-check, lint, build]
-          max_fix_attempts: 3
-          build_fix:
-            ios: swift-build-resolver
-        - id: scribe
+          subagent_type: product-owner
+          reads: [feature-delegation-plan.json, task-outputs, evidence]
+          writes_state: [feature_acceptance, completed_features]
+          verdict: ACCEPTED | NEEDS_REVISION
+          notes: |
+            Product Owner reviews each feature in the completed wave.
+            ACCEPTED features are added to completed_features.
+            NEEDS_REVISION features are flagged for re-work in a subsequent wave.
+    wave_transition:
+      steps:
+        - id: "4.4"
+          name: Wave transition
           kind: internal
-          role: orchestrator-scribe
-          action: |
-            Walks batch_results, collects non-null deviation_row objects, and
-            invokes the scribe_decision MCP tool once per row. The MCP is the
-            single writer for decisions.jsonl — it allocates D-{phase}-<seq>
-            IDs, stamps timestamp + status, validates against
-            decisions.schema.json, and atomically appends. The orchestrator
-            MUST NOT Write/Edit decisions.jsonl directly and MUST NOT
-            pre-compute IDs. .build-state.json.decisions_next_id is
-            deprecated under Stage 2 and removed at Stage 4 A7.
+          writes_state: [current_wave]
+          notes: |
+            Increments current_wave. If more waves remain in the feature
+            delegation plan, loops back to Step 4.2. If all waves complete
+            (all features ACCEPTED), Phase 4 ends.
     hard_gates:
       - decisions.jsonl is orchestrator-scribe ONLY. Subagents return deviation_row objects.
       - "Web compositional: component-manifest.md variants MUST be imported; writing from scratch triggers cleanup revert."
@@ -616,22 +977,25 @@ phases:
       - docs/plans/.task-outputs/[task-id].json
     backward_edges:
       - from: LRR-NEEDS_WORK-code-level
-        to: phase-4.target-task
+        to: phase-4.target-feature
       - from: phase-5-dogfood-feedback-synthesizer
-        to: phase-4.target-task
+        to: phase-4.target-feature
+      - from: phase-5-track-b-feedback-synthesizer
+        to: phase-1.6-product-spec-writer
+        condition: spec-gap finding (target_phase 1, target_task_or_step "1.6")
 
   - id: "5"
     name: Audit
-    kind: team-then-eval-then-parallel-then-synth
+    kind: track-a-then-track-b-then-cross-cutting-then-synth
     skip_conditions: []
     precondition: verify-protocol passes
     web_branch:
       steps:
         - id: "5.1"
-          name: TEAM of 6 parallel auditors
+          name: Track A — Engineering Reality (5 parallel auditors)
           kind: dispatch-parallel
           dispatch_mode: single-message
-          parallel_count: 6
+          parallel_count: 5
           dispatches:
             - subagent_type: testing-api-tester
               focus: API validation, edge cases, error responses, auth flows
@@ -648,53 +1012,104 @@ phases:
               checks: [contrast, keyboard, focus, touch-targets>=44px, reduced-motion]
             - subagent_type: engineering-security-engineer
               focus: auth, input validation, data exposure, dependency vulns
-            - subagent_type: design-ux-researcher
-              focus: loading/error/empty states, mobile@375px, form validation, visual consistency vs style guide
             - subagent_type: design-brand-guardian
               focus: DNA drift check
               notes: Phase 5 re-invite, does NOT issue verdict — feeds LRR Brand Guardian chapter
+          notes: |
+            design-ux-researcher (formerly item 5) was REMOVED — its work is
+            subsumed by Track B per-feature audits at Step 5.2.
         - id: "5.2"
-          name: Eval Harness -> Metric Loop
-          kind: loop
-          service: metric-loop
-          eval_case_count: 8-15
-          max_iterations: 4
-          fix_routing:
-            security: security-reviewer
-            a11y: engineering-frontend-developer
-            perf: testing-performance-benchmarker
-          post_loop: re-run-eval
+          name: Track B — Product Reality (parallel per-feature)
+          kind: dispatch-parallel-per-feature
+          dispatch_mode: single-message
+          parallel_count: N (one per feature_id from graph_query_feature)
+          subagent_type: product-reality-auditor
+          feature_enumeration: graph-query-then-file-fallback
+          zero_feature_gate: stop-and-route-to-1.6
+          post_dispatch_verification:
+            - presence-and-json-parseability-of-four-evidence-files
+            - retry_once_with_graph_used_false
+            - synthesize_finding_target_phase_1_step_1.6_on_second_failure
+          writes_per_feature:
+            - docs/plans/evidence/product-reality/{feature_id}/tests-generated.md
+            - docs/plans/evidence/product-reality/{feature_id}/results.json
+            - docs/plans/evidence/product-reality/{feature_id}/findings.json
+            - docs/plans/evidence/product-reality/{feature_id}/coverage.json
+            - docs/plans/evidence/product-reality/{feature_id}/screenshots/
+        - id: "5.2.idx"
+          name: Track B evidence graph index (best-effort)
+          kind: graph-index
+          best_effort: true
+          rationale: hard-gated at Phase 6.0 by file presence + JSON parseability, not by graph index
+          command: "node ${CLAUDE_PLUGIN_ROOT}/bin/graph-index.js docs/plans/evidence/product-reality/"
         - id: "5.3"
-          name: TEAM of 3 parallel
+          name: Cross-cutting (3 parallel, ONE message)
           kind: dispatch-parallel
           dispatch_mode: single-message
           parallel_count: 3
           dispatches:
-            - e2e-runner: Playwright, 3 iters mandatory
-            - dogfood-runner: agent-browser
+            - e2e-runner:
+                tool: Playwright
+                iterations: 3-mandatory
+                scope: multi-feature User Journeys ONLY (single-feature happy paths covered by Track B at 5.2)
+            - dogfood-runner:
+                tool: agent-browser
+                scope: emergent issues only (do not re-audit per-feature spec coverage)
             - fake-data-detector
         - id: "5.4"
           name: Feedback Synthesizer
           kind: dispatch-single
           subagent_type: product-feedback-synthesizer
-          classifies_to: [phase-4-code, phase-3-visual, phase-2-structural]
+          inputs:
+            - docs/plans/evidence/dogfood/findings.md
+            - docs/plans/evidence/product-reality/*/findings.json
+          output: docs/plans/evidence/dogfood/classified-findings.json
+          output_per_finding_fields: [finding_id, source, severity, target_phase, target_task_or_step, description, evidence_ref, related_decision_id]
+          output_footer_fields: [graph_used, re_routed_findings, source_counts]
+          source_discriminator: "dogfood | product-reality"
+          routing_arms: [phase-4-code, phase-3-visual, phase-2-structural, phase-1.6-spec-gap]
+          track_b_handling: validate-pass-through (re-route only if graph rejects)
+        - id: "5.5"
+          name: Fix loop
+          kind: loop
           max_fix_cycles: 2
+          spec_gap_routing: target_phase 1, target_task_or_step "1.6" -> product-spec-writer (re-triggers Track B for affected feature)
     ios_branch:
       replaces: web-6+3
-      mode: three-slash-commands-in-sequence
-      sequence:
-        - /buildanything:verify
-        - /buildanything:ux-review
-        - /buildanything:fix
+      mode: track-a-b-crosscutting
+      protocol: protocols/ios-phase-branches.md §Phase 5
+      track_a:
+        - testing-api-tester (API contract via XcodeBuildMCP test runner)
+        - testing-performance-benchmarker (app launch, memory, binary size, scroll jank)
+        - a11y-architect (swift-accessibility skill, XcodeBuildMCP describe_ui)
+        - engineering-security-engineer (swift-security-expert skill, Keychain/ATS/privacy)
+        - design-brand-guardian (simulator screenshots vs DESIGN.md DNA)
+      track_b:
+        agent: ios-product-reality-auditor
+        execution_surface: XcodeBuildMCP + Maestro
+        check_classes: [screen_reachability, state_coverage, transition_firing, rule_enforcement, happy_path, persona_walkthrough, wiring_manifest]
+      crosscutting:
+        - Maestro E2E (3 iterations, multi-device)
+        - iOS Dogfood (XcodeBuildMCP exploratory via ios-debugger-agent)
+        - iOS Fake-Data Detector (protocols/ios-fake-data-detector.md)
+      shared_steps: Steps 5.4-5.5 in commands/build.md (synthesizer + fix loop)
       required_artifacts:
-        - docs/plans/ios-verify-report.md
-        - docs/plans/ios-ux-review-report.md
+        - "docs/plans/evidence/track-a/*.json (5 files)"
+        - docs/plans/evidence/brand-drift.md
+        - "docs/plans/evidence/product-reality/*/results.json (one per feature)"
+        - docs/plans/evidence/e2e/iter-3-results.json
+        - docs/plans/evidence/dogfood/findings.md
+        - docs/plans/evidence/fake-data-audit.md
         - "maestro/*.yaml (>=1)"
         - "docs/plans/evidence/maestro-runs/*.png (>=1)"
     writes:
       - docs/plans/evidence/*.json
       - evidence/fake-data-audit.md
       - evidence/dogfood/classified-findings.json
+      - evidence/product-reality/*/tests-generated.md
+      - evidence/product-reality/*/results.json
+      - evidence/product-reality/*/findings.json
+      - evidence/product-reality/*/coverage.json
       - "learnings.jsonl (reality sweep PITFALL/PATTERN rows)"
 
   - id: "6"
@@ -706,12 +1121,12 @@ phases:
       hard_gate_preconditions:
         all_projects: [".build-state.json exists + has recent VERIFY:PASS"]
         web:
-          - eval-harness/baseline.json
-          - eval-harness/final.json
           - e2e/iter-3-results.json
           - dogfood/findings.md
           - dogfood/classified-findings.json
           - fake-data-audit.md
+          - "product-reality/*/coverage.json (one per feature in product-spec; missing = BLOCK)"
+          - "product-reality/*/findings.json (one per feature)"
           - manifest.json
         ios:
           - ios-verify-report.md
@@ -984,17 +1399,18 @@ callable_services:
     cross_run_injection: phase-4 implementer reads .active-learnings.md (top-3 filtered at phase-0)
 
   briefing_officer:
-    kind: INTERNAL
-    callable_per: phase-4-task
+    kind: dispatch-single
+    subagent_type: briefing-officer
+    callable_per: phase-4-feature
     contract:
-      reads: [refs.json, task-row]
-      writes: CONTEXT MAP (~40 lines)
+      reads: [refs.json, feature-delegation-plan.json, task-rows-for-feature]
+      writes: [docs/plans/feature-briefs/*.md]
       mode: refs-not-pastes
       excluded: [CLAUDE.md (auto-loaded), phase1-scratch (SPENT)]
     context_map_shape:
       persona_jtbd: design-doc.md#persona
       product_scope: design-doc.md#scope
-      visual_tokens: visual-design-spec.md#tokens
+      visual_tokens: DESIGN.md#tokens
       component_variants: component-manifest.md#[category]
       auth_model: architecture.md#auth
       data_schema: architecture.md#data-model
@@ -1016,7 +1432,7 @@ backward_routing:
     to: phase-3.step-3.0
     note: re-lock DNA
   - from: phase-5-audit-code-issue
-    to: phase-4.target-task
+    to: phase-4.target-feature
   - from: phase-5-audit-design-issue
     to: phase-3.target-step
   - from: phase-5-audit-spec-issue
@@ -1028,7 +1444,7 @@ backward_routing:
     via: star-star-rule
     to: authoring-phase (per decisions.jsonl.decided_by)
   - from: phase-6-LRR-NEEDS_WORK-code
-    to: phase-4.target-task
+    to: phase-4.target-feature
     via: related_decision_id
   - from: phase-6-LRR-NEEDS_WORK-structural
     to: phase-2-or-phase-3
@@ -1042,7 +1458,7 @@ re_entry_template: |
 re_entry_rules:
   phase-2: "Only the architect whose domain matches decision_row.author re-runs. Synthesizer re-runs once."
   phase-3: "Only the step named by decision_row.author re-runs (DNA lock, component manifest, or visual spec)."
-  phase-4: "Target task only. Reads prior_output + changed files. Revises ONLY what blocking_finding requires. Does NOT re-run acceptance tests that passed. Does NOT touch files outside finding blast radius."
+  phase-4: "Target feature's Briefing Officer re-plans affected task(s). Orchestrator re-executes. Product-level issues route to Product Owner. Does NOT re-run unaffected tasks."
 
 needs_work_loop_cap:
   max_cycles: 2