buildanything 2.0.0 → 2.1.1

package/protocols/product-spec-schema.md

@@ -0,0 +1,354 @@
+# product-spec.md Schema
+
+## Purpose
+
+Step 1.6's product-spec-writer emits `docs/plans/product-spec.md` with stable section anchors so that Phase 2 architects, Phase 2 planner, Phase 3 UX architect, Phase 4 Product Owner, and Phase 4 Briefing Officers can receive content-addressed refs instead of pasted content. This document defines the required structure, anchor convention, format rules, validation checklist, and product-type variations.
+
+## Required Top-Level Sections
+
+The product spec MUST contain these top-level headings, in this order:
+
+- `# Product Spec`
+- `## App Overview`
+- `## Screen Inventory`
+- `## Permissions & Roles`
+- `## Cross-Feature Interactions`
+
+Then, one `## Feature: {Name}` section per feature in the PRD scope.
+
+### App Overview
+
+Two parts, both required.
+
+**Part 1 — Grounding paragraph.** One paragraph: what this app is and core value proposition. Not a restatement of the PRD — a grounding paragraph that any engineer can read in 10 seconds to understand the product.
+
+**Part 2 — Persona Table.** A table listing every persona the product serves. One row flagged `(primary)` next to its name. Required columns: `Persona`, `Role`, `Primary JTBD`, `Relationship to Other Personas`.
+
+Format:
+
+```
+| Persona | Role | Primary JTBD | Relationship to Other Personas |
+|---------|------|--------------|--------------------------------|
+| Buyer (primary) | End consumer placing orders | Find a trusted seller and complete a purchase fast | Buys from Seller; rates Seller post-transaction |
+| Seller | Independent merchant fulfilling orders | Receive, fulfill, and get paid for orders without manual chasing | Sells to Buyer; notified by Buyer order events |
+| Admin | Platform operator handling disputes | Resolve disputes between Buyer and Seller without losing trust on either side | Mediates Buyer ↔ Seller |
+```
+
+Rules:
+- ≥ 1 row required. A single-persona product still uses the table — name the one persona explicitly.
+- Exactly one row carries `(primary)` after the name.
+- Persona names defined here are the canonical identifiers used in every per-feature `Persona Constraints` block. Do not introduce a persona name in a feature that does not appear in this table.
+- Pull persona enumeration directly from `ux-research.md` (Persona Enumeration section). If `ux-research.md` lists N personas, this table has N rows.
+
+Anchors: `product-spec.md#app-overview` (top-level grounding paragraph + table), `product-spec.md#app-overview/personas` (the table specifically, for refs.json indexing).
+
+### Screen Inventory
+
+Complete list of every screen in the app with a one-line description. Format:
+
+```
+| Screen | Description | Features |
+|--------|-------------|----------|
+| Login | Email/password + social auth | Auth |
+| Dashboard | KPI cards, activity feed, charts | Dashboard, Notifications |
+| Checkout (3 screens) | Cart review → Shipping → Confirmation | Checkout |
+| Settings | Profile, notifications, billing, security tabs | Settings |
+| Admin Panel | User management, analytics | Admin |
+```
+
+This is the master list. Per-feature sections reference screens from this inventory.
+
+### Permissions & Roles
+
+Define every role in the system and what each can access. Format:
+
+```
+| Role | Can Do | Cannot Do |
+|------|--------|-----------|
+| Anonymous | View public pages, sign up | Access dashboard, place orders |
+| User | CRUD own resources, checkout | Manage other users, view admin |
+| Admin | All user actions + manage users, view analytics | Delete system config |
+```
+
+If the product has no roles beyond "authenticated user," say so explicitly: "Single role: authenticated user. No admin or public access."
+
+### Cross-Feature Interactions
+
+A dependency map showing how features connect. Where an interaction crosses a persona boundary (one persona's action triggers another persona's experience), call this out explicitly with `(Persona) → (Persona)` notation. This is critical for marketplaces and other multi-sided products — without it, the seller-side and buyer-side experiences diverge silently.
+
+Format:
+
+```
+- Auth → Checkout: user must be authenticated to check out
+- Order Placement (Buyer) → Order Notification (Seller): seller notified within 60s when buyer submits order
+- Order Fulfillment (Seller) → Order Status (Buyer): buyer sees status update when seller marks shipped
+- Dispute (Buyer or Seller) → Mediation (Admin): admin queue receives dispute when either party files
+- Checkout → Inventory: stock check at cart review and at submit
+- Dashboard → Settings: display preferences read from user settings
+- Notifications → Auth, Checkout, Dashboard: triggered by events in each
+```
+
+Every dependency must be bidirectional — if A depends on B, B's feature section must mention A under its own interactions. Persona-crossing interactions must appear in BOTH personas' feature sections.
+
+## Required Per-Feature Sections
+
+Every `## Feature: {Name}` section MUST contain these subsections, in this order:
+
+### States
+Flat list of all states this feature can be in. Minimum 3: a loaded state, an empty/initial state, and an error state. Include meta-states as relevant: loading, stale, offline, permission-denied, disabled. The first entry is the initial state.
+
+Format: `States: initial (initial), loading, loaded, empty, error, stale`
+
+### Transitions
+Table of valid state changes.
+
+Format:
+```
+| From → To | Trigger | Preconditions | Side Effects |
+|-----------|---------|---------------|--------------|
+| initial → loading | Page mount | User authenticated | Fetch GET /api/orders |
+| loading → loaded | API 200 | Response has ≥1 item | Render list |
+| loading → empty | API 200 | Response has 0 items | Show empty state |
+| loading → error | API 4xx/5xx or timeout | — | Show error message |
+```
+
+### Data Requirements
+Per-state data needs. What data is displayed, where it comes from, what shape it has.
+
+Format:
+```
+- loaded: list of orders [{id, status, total, created_at, items[]}] from GET /api/orders
+- empty: no data needed, static copy
+- error: error message string from API response or "Something went wrong. Please try again."
+```
+
+### Failure Modes
+Per-transition failures. What can go wrong, what the user sees (exact copy), what they can do, what the system does.
+
+Format:
+```
+- Network failure during checkout submit →
+  User sees: "We couldn't process your order. Please check your connection and try again."
+  User can: Retry (button), go back to cart
+  System: Log error, do NOT create partial order
+```
+
+### Business Rules
+Bullet list with concrete values. Every rule has a number or a `[DECISION NEEDED]` flag.
+
+### Happy Path
+Numbered steps. Each step: what the user sees, what they can do, what happens.
+
+### Persona Constraints
+Which personas this feature serves and what research findings shaped its design for each. Every constraint MUST attribute to a specific persona named in the App Overview persona table. Cite specific findings from `ux-research.md` and `feature-intel.md`.
+
+Rules:
+- One constraint block per persona that uses this feature.
+- Persona names must match the App Overview table verbatim (including `(primary)` flag where applicable).
+- If a feature serves multiple personas, list a constraint block per persona — even if some constraints overlap, attribute each to the persona it shapes the design for.
+- If a feature serves only one persona, name it explicitly. Do not leave persona attribution implicit.
+
+Format (multi-persona example — marketplace order placement):
+```
+- Persona: Buyer (primary) — time-poor, scans, doesn't read [ux-research.md]
+  Constraint: keep checkout to 3 steps max — competitors average 5+ [feature-intel.md]
+  Constraint: show progress indicator at top of each step — persona abandons flows without visible progress [ux-research.md]
+- Persona: Seller — needs visibility into pending orders to plan fulfillment [ux-research.md]
+  Constraint: notification within 60s of order placed — sellers report losing time-sensitive orders to slower competitors [ux-research.md]
+  Constraint: order detail must include buyer-supplied notes verbatim — fulfillment errors traced to truncated notes in v0 [ux-research.md]
+```
+
+### Empty/Loading/Error States
+What the user sees in each non-happy state. Include specific copy and call-to-action for empty states.
+
+### Acceptance Criteria
+Testable statements using checkbox format. Each starts with "Verify that..."
+
+Format:
+```
+- [ ] Verify that checkout completes in 3 steps or fewer
+- [ ] Verify that discount code validates without page reload
+- [ ] Verify that out-of-stock items show inline notification, not a generic error page
+```
+
+## Optional Per-Feature Sections
+
+Include based on product type. Omit if not applicable — do not stub empty sections.
+
+- **Notification Triggers** — channel (email/push/in-app), timing (immediate/delayed/batched), content summary, opt-out mechanism. Required for: SaaS with user accounts, marketplaces, mobile apps.
+- **Technical Constraints & Integrations** — third-party services this feature depends on (payment processor, geocoding API, email provider, analytics), rate limits, SDK requirements, authentication method for each. Required for: features that call external APIs or use third-party SDKs.
+- **Copy Direction** — tone examples for CTAs, errors, empty states, confirmations specific to this feature. Required for: consumer-facing products, marketplaces.
+- **Offline Behavior** — what's cached, what degrades, what's blocked. Required for: mobile apps, PWAs.
+- **Multi-User Scenarios** — concurrent access, conflict resolution, real-time sync. Required for: collaborative tools, marketplaces, multi-tenant SaaS.
+- **Performance Expectations** — latency targets per interaction. Required for: search-heavy products, real-time dashboards, e-commerce checkout.
+- **Inter-Screen Data Flow** — what state carries from this feature's screens to other screens (URL params, local storage, context providers, server session). What data this feature reads that another feature writes, and vice versa. Required for: multi-screen flows, features that share state.
+
+## Anchor Naming Convention
+
+Anchors follow `product-spec.md#{feature}/{section}` format for refs.json indexing.
+
+Rules:
+- Feature names are kebab-case: `checkout`, `user-dashboard`, `admin-settings`
+- Section names are kebab-case: `states`, `transitions`, `data-requirements`, `failure-modes`, `business-rules`, `happy-path`, `persona-constraints`, `empty-states`, `acceptance-criteria`
+- Full anchor example: `product-spec.md#checkout/business-rules`
+- Top-level sections use flat anchors: `product-spec.md#app-overview`, `product-spec.md#screen-inventory`, `product-spec.md#permissions`, `product-spec.md#cross-feature`
+- Anchors must be stable across regeneration — same inputs produce same anchors
+
+The Refs Indexer (Phase 2.2) parses these anchors into `refs.json` alongside architecture and PRD anchors.
+
+## Product-Type Variations
+
+| Section | Web SaaS | Dashboard/Analytics | API/Dev Tool | iOS/Mobile | CLI | Marketplace |
+|---------|----------|-------------------|-------------|-----------|-----|-------------|
+| States | Required | Required | Omit (use request lifecycle) | Required + app lifecycle | Omit (use exit codes) | Required × 2 roles |
+| Transitions | Required | Required (lighter) | Required (request/response) | Required + background states | Required (command flow) | Required × 2 roles |
+| Data Requirements | Required | Required (heavy) | Required (request/response shapes) | Required + cache strategy | Required (stdin/stdout) | Required × 2 roles |
+| Failure Modes | Required | Required | Required (error codes) | Required + offline failures | Required (exit codes) | Required × 2 roles |
+| Happy Path | Required | Required | Required (request examples) | Required | Required (command examples) | Required × 2 roles |
+| Business Rules | Required | Light | Required (rate limits, quotas) | Required | Light | Required (both sides) |
+| Empty States | Required | Required | N/A | Required | N/A | Required × 2 roles |
+| Notification Triggers | Optional | Optional | N/A | Required | N/A | Required |
+| Offline Behavior | Optional | N/A | N/A | Required | N/A | Optional |
+| Multi-User Scenarios | Optional | Optional | Optional | Optional | N/A | Required |
+| Performance | Optional | Required | Required | Optional | Optional | Optional |
+
+## Validation Checklist
+
+Step 1.7 runs these checks. Failure sends the spec back to the product-spec-writer with specific gaps.
+
+**Mechanical checks (no LLM, ~0 tokens):**
+1. Every feature in `design-doc.md` scope has a `## Feature: {Name}` section
+2. Every feature section has all 9 required subsections (States through Acceptance Criteria, including Persona Constraints)
+3. Every States list has ≥ 3 entries
+4. Every Transitions table has ≥ 1 row
+5. No banned vague phrases: "appropriate," "as needed," "standard," "graceful," "configurable," "reasonable," "properly," "adequate"
+6. All `[DECISION NEEDED]` tags are well-formed: `[DECISION NEEDED: question | Suggest: value]` or `[DECISION NEEDED: question]`
+7. Permissions & Roles section exists and is non-empty
+8. Cross-Feature Interactions section exists and is non-empty
+9. Screen Inventory section exists and is non-empty
+10. Every acceptance criterion starts with "Verify that"
+11. App Overview persona table has ≥ 1 row, each persona has a role and JTBD, exactly one persona is flagged `(primary)`, and the `Relationship to Other Personas` column is filled for each row
+12. Every feature's Persona Constraints attributes each constraint to a named persona that appears in the App Overview persona table (no orphan persona names, no implicit attribution)
+13. For multi-persona products: every Cross-Feature Interactions entry that crosses a persona boundary uses the `(Persona) → (Persona)` annotation
+
+**State machine checks (mechanical, ~0 tokens):**
+14. Every state in a States list appears in at least one Transitions row (no orphan states)
+15. Every Transitions row references states that exist in the States list
+16. No transition has empty preconditions (every transition requires something to be true, even if it's just "user clicks button")
+17. Error states have at least one outgoing transition (recovery path) OR are marked terminal
+18. The initial state is explicitly identified in the States list (first entry or marked with "(initial)")
+
+## Worked Example: Marketplace Order Placement (Buyer + Seller)
+
+This example illustrates the multi-persona pattern. App Overview persona table for this hypothetical product would include at minimum `Buyer (primary)` and `Seller`. The feature below is order placement, which originates with the Buyer but has direct downstream effects on the Seller (notification, fulfillment queue) — so its `Persona Constraints` block has entries for both personas, and the top-level `Cross-Feature Interactions` map records the persona-crossing edge.
+
+```markdown
+## Feature: Checkout
+
+### States
+States: empty-cart (initial), cart-review, entering-shipping, confirming, processing, completed, failed
+
+### Transitions
+| From → To | Trigger | Preconditions | Side Effects |
+|-----------|---------|---------------|--------------|
+| empty-cart → cart-review | Add first item | User authenticated | Cart created in local storage |
+| cart-review → entering-shipping | Click "Continue to Shipping" | Cart has ≥ 1 in-stock item | Validate inventory via GET /api/inventory/check |
+| cart-review → empty-cart | Remove last item | — | Clear cart from local storage |
+| entering-shipping → confirming | Submit shipping form | All required fields valid, address verified | Calculate tax via POST /api/tax/calculate |
+| confirming → processing | Click "Place Order" | — | POST /api/orders, disable button, show spinner |
+| processing → completed | API 201 | Order created | Show confirmation, send email, clear cart |
+| processing → failed | API 4xx/5xx or 30s timeout | — | Show error message, re-enable "Place Order" |
+| failed → processing | Click "Try Again" | Poll GET /api/orders/{id} confirms no order exists | Retry POST /api/orders |
+| failed → cart-review | Click "Review Cart" | — | Navigate back, cart preserved |
+| any → cart-review | Click browser back / breadcrumb | — | State preserved, no data loss |
+
+### Data Requirements
+- cart-review: cart items [{id, name, price, quantity, image_url}] from local storage, inventory status from GET /api/inventory/check
+- entering-shipping: saved addresses from GET /api/user/addresses (if any), country list static
+- confirming: order summary {items, subtotal, shipping, tax, discount, total} computed client-side, tax from API
+- processing: no new data, spinner only
+- completed: order {id, estimated_delivery, email} from POST /api/orders response
+- failed: error message from API response body
+- empty-cart: no data, static copy
+
+### Failure Modes
+- Inventory check fails (item out of stock after carting) →
+  User sees: "'{item name}' is no longer available. We've updated your cart."
+  User can: Continue with remaining items, or go back to browse
+  System: Remove item from cart, recalculate total
+
+- Shipping address validation fails →
+  User sees: Inline field errors ("Enter a valid ZIP code")
+  User can: Correct fields and resubmit
+  System: No API call until client-side validation passes
+
+- Payment processing fails →
+  User sees: "We couldn't process your payment. Please check your card details and try again."
+  User can: Retry, change payment method, go back to cart
+  System: Log failure reason, do NOT create partial order, do NOT charge card
+
+- Network failure during order submit →
+  User sees: "Connection lost. Your cart is saved — try again when you're back online."
+  User can: Retry when connection restores
+  System: Cart persisted in local storage, no server-side state created
+
+- 30s timeout during processing →
+  User sees: "This is taking longer than expected. Please wait or try again."
+  User can: Wait (spinner continues) or click "Try Again"
+  System: If order was created server-side, poll GET /api/orders/{id} to confirm before retrying
+
+### Business Rules
+- Discount codes: one per order, validated in real-time via POST /api/discounts/validate, shows adjusted total immediately
+- Tax: calculated by jurisdiction based on shipping address, displayed at confirmation step
+- Inventory: checked at cart-review entry AND at order submit — stale cart items removed with notification
+- Minimum order: [DECISION NEEDED: Is there a minimum order value? Suggest: no minimum]
+- Shipping: [DECISION NEEDED: Free shipping threshold? Suggest: free over $50, flat $5.99 under]
+- Order timeout: 30 seconds before showing timeout message
+- Cart persistence: local storage, survives browser close, expires after 7 days
+- Pricing display: [DECISION NEEDED: Include tax in displayed prices or show separately? Common options: tax-exclusive (US standard) or tax-inclusive (EU standard)]
+
+### Happy Path
+1. User is on cart-review screen. Sees: item list with names, prices, quantities, images. Subtotal displayed. Can: edit quantities (inline +/- buttons), remove items, apply discount code, click "Continue to Shipping."
+2. User clicks "Continue to Shipping." Sees: shipping form with saved addresses (if any) or empty form. Required fields: name, street, city, state, ZIP, country. Can: select saved address or enter new one.
+3. User submits shipping. Sees: order confirmation screen with full summary — items, subtotal, shipping cost, tax, discount (if applied), total. Can: edit any section (back navigation preserves all data), click "Place Order."
+4. User clicks "Place Order." Sees: button disabled, spinner. Waits up to 10 seconds.
+5. Order succeeds. Sees: confirmation page with order ID, estimated delivery date, "A confirmation email has been sent to {email}." Can: click "Continue Shopping" or view order in account.
+
+### Persona Constraints
+- Persona: Buyer (primary) — time-poor, scans, doesn't read [ux-research.md]
+  Constraint: checkout must complete in 3 steps — competitors average 5+ steps; research shows each additional step loses ~10% of users [feature-intel.md]
+  Constraint: show progress indicator at top of each step — persona abandons flows without visible progress [ux-research.md]
+  Constraint: real-time discount validation — competitors require page reload, this is a key differentiator [feature-intel.md]
+- Persona: Seller — needs immediate visibility into incoming orders to plan fulfillment [ux-research.md]
+  Constraint: order notification fires within 60s of buyer's `processing → completed` transition — sellers in interviews reported losing time-sensitive orders to faster-notifying competitors [ux-research.md]
+  Constraint: order payload to seller includes buyer-supplied notes verbatim (no truncation) — fulfillment errors traced to truncated notes in v0 research [ux-research.md]
+
+### Empty/Loading/Error States
+- Empty cart: "Your cart is empty. Browse our products to find something you'll love." CTA: "Start Shopping" button linking to product catalog.
+- Loading (inventory check): Skeleton cards matching item layout, no spinner.
+- Loading (tax calculation): Subtotal visible, tax line shows "Calculating..." with shimmer.
+- Loading (order processing): "Place Order" button disabled, inline spinner, "Processing your order..." text.
+- Error (generic): "Something went wrong. Please try again." with "Retry" button. Never a full-page error — always inline within the checkout flow.
+
+### Performance Expectations
+- Cart page load: < 1s TTI (Time to Interactive) on 4G connection
+- Discount code validation: < 500ms API response, show inline spinner during request
+- Tax calculation: < 1s API response, show shimmer placeholder during calculation
+- Order submission: < 10s to confirmation, show spinner, timeout message at 30s
+
+### Notification Triggers
+- Order placed → Email (immediate): order confirmation with item summary, order ID, estimated delivery, tracking link
+- Payment failed → Email (immediate): retry prompt with direct link to payment page, cart preserved
+- Cart abandoned (7 days) → Email (delayed, 24h after last activity): reminder with cart contents and direct link to resume
+
+### Acceptance Criteria
+- [ ] Verify that checkout completes in 3 steps (cart review, shipping, confirmation)
+- [ ] Verify that user can navigate back to any previous step without losing entered data
+- [ ] Verify that discount code validates in real-time without page reload
+- [ ] Verify that out-of-stock items detected during checkout show inline notification with item name
+- [ ] Verify that payment failure shows specific error message with retry option, not a generic error page
+- [ ] Verify that cart persists across browser close and is recoverable
+- [ ] Verify that order confirmation displays order ID and sends confirmation email
+- [ ] Verify that the "Place Order" button is disabled during processing to prevent double-submit
+- [ ] Verify that 30s timeout during processing shows timeout message with retry option
+```

package/protocols/sprint-tasks-schema.md

@@ -0,0 +1,53 @@
+# Sprint Tasks Schema
+
+Schema for `docs/plans/sprint-tasks.md` — the pipe-delimited markdown table produced by the planner agent (Step 2.3.2) and parsed by `src/graph/parser/sprint-tasks.ts`.
+
+## Columns (required, in order)
+
+| # | Column | Format | Rules |
+|---|--------|--------|-------|
+| 1 | Task ID | `T-{N}` (e.g. `T-1`, `T-2`) | Must not be empty. No duplicates (case-insensitive). |
+| 2 | Title | Free text | Human-readable task description. |
+| 3 | Size | `S`, `M`, or `L` | Case-insensitive; parser normalizes to uppercase. |
+| 4 | Dependencies | Comma-separated Task IDs | e.g. `T-1, T-3`. Use `—` for none. Phase 4 uses this to batch independent tasks in parallel. |
+| 5 | Behavioral Test | Concrete testable interaction | UI: `Navigate to X, click Y, verify Z`. API: curl-based. Should reference a product-spec acceptance criterion. |
+| 6 | Owns Files | Comma-separated file paths | Files this task creates or modifies. Use `—` for none. |
+| 7 | Implementing Phase | Phase identifier | e.g. `phase-4-frontend`, `phase-4-backend`. |
+| 8 | Feature | Exact feature name from `product-spec.md` | Must match a `## Feature: X` heading. Use `—` for infrastructure tasks. Parser generates graph ID via kebab-case: `Order Placement` → `feature__order-placement`. |
+| 9 | Screens | Comma-separated screen names | From the product-spec Screen Inventory. Use `—` for backend-only tasks. Parser generates IDs via kebab-case: `Catalog` → `screen__catalog`. |
+
+## Validation Rules
+
+The parser enforces these rules and rejects the table on any violation:
+
+1. Table must have **exactly 9 columns**.
+2. All 9 column headers must be present (matched case-insensitively).
+3. **Task ID** must not be empty.
+4. **Task ID** must not be duplicated (case-insensitive comparison).
+5. **Size** must be one of `S`, `M`, `L`.
+
+The DAG validator (Step 2.3, dispatch #3) additionally checks:
+- No circular dependencies.
+- All Task IDs referenced in Dependencies exist.
+- Every UI task has a Behavioral Test; every API task has a curl-based test.
+
+## Graph Edges Emitted Per Row
+
+| Relation | Condition | Source | Target |
+|----------|-----------|--------|--------|
+| `task_implements_feature` | Feature is not `—` | `task__{task-id}` | `feature__{kebab-name}` |
+| `task_touches_screen` | Per screen when Screens is not `—` | `task__{task-id}` | `screen__{kebab-name}` |
+| `task_depends_on` | Per dependency in Dependencies | `task__{task-id}` | `task__{dep-id}` |
+
+## Example Row
+
+```
+| T-3 | Implement product catalog grid | M | T-1, T-2 | Navigate to /catalog, verify 12 product cards render with images and prices | src/components/CatalogGrid.tsx, src/api/products.ts | phase-4-frontend | Product Browsing | Catalog, Product Detail |
+```
+
+## References
+
+- **Parser:** `src/graph/parser/sprint-tasks.ts`
+- **Planner prompt:** `commands/build.md` Step 2.3, dispatch #2 ("Sprint breakdown")
+- **DAG validator:** `commands/build.md` Step 2.3, dispatch #3 ("Task DAG validator")
+- **Graph index command:** `node ${CLAUDE_PLUGIN_ROOT}/bin/graph-index.js docs/plans/sprint-tasks.md`

package/protocols/state-schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$comment": "Schema version migration table: schema_version 1 = Stages 1-3; schema_version 2 = Stage 4 (adds backward_routing_count, backward_routing_count_by_target_phase, in_flight_backward_edge, mode_transitions); schema_version 3 = Stage 5 (adds lrr_cycle_state); schema_version 4 = Stage 6 (adds current_sprint_context_hash). --- Runtime validation rules (not encodable in JSON Schema, require code): Rule 5 — step prefix must match current phase number; Rule 6 — mode/autonomous consistency (mode==='autonomous' iff autonomous===true); Rule 7 — iOS fields gating (app_name, bundle_id, xcodeproj_path, ios_features, phase_progress.phase_minus_1 exist iff project_type==='ios'); Rule 10 — pending/in-progress disjoint (in_progress_task.task_id not in pending_tasks or completed_tasks); Rule 11 — resume_point.phase/step must not be ahead of top-level phase/step; Rule 12 — timestamps monotonic (session_last_saved >= session_started).",
+  "$comment": "Schema version migration table: schema_version 1 = Stages 1-3; schema_version 2 = Stage 4 (adds backward_routing_count, backward_routing_count_by_target_phase, in_flight_backward_edge, mode_transitions); schema_version 3 = Stage 5 (adds lrr_cycle_state); schema_version 4 = Stage 6 (adds current_sprint_context_hash), schema_version 5 = Stage 7 (adds feature_delegation_plan_path, current_wave, completed_features, feature_acceptance, feature_briefs). --- Runtime validation rules (not encodable in JSON Schema, require code): Rule 5 — step prefix must match current phase number; Rule 6 — mode/autonomous consistency (mode==='autonomous' iff autonomous===true); Rule 7 — iOS fields gating (app_name, bundle_id, xcodeproj_path, ios_features, phase_progress.phase_minus_1 exist iff project_type==='ios'); Rule 10 — pending/in-progress disjoint (in_progress_task.task_id not in pending_tasks or completed_tasks); Rule 11 — resume_point.phase/step must not be ahead of top-level phase/step; Rule 12 — timestamps monotonic (session_last_saved >= session_started).",
   "title": ".build-state.json",
   "description": "Typed source of truth for BuildAnything build state. Validated by the PreToolUse schema lint hook (W2-2). additionalProperties: false enforces fail-closed per A8 SSOT rule.",
   "type": "object",
@@ -229,8 +229,8 @@
     "schema_version": {
       "type": "integer",
       "minimum": 1,
-      "maximum": 4,
-      "description": "Currently 1 (Stages 1-3). Bumped to 2 at Stage 4, 3 at Stage 5, 4 at Stage 6."
+      "maximum": 5,
+      "description": "Currently 5 (Stage 7). Bumped to 2 at Stage 4, 3 at Stage 5, 4 at Stage 6, 5 at Stage 7."
     },
     "project_type": {
       "type": "string",
@@ -349,6 +349,11 @@
       "items": { "$ref": "#/$defs/blocker" },
       "description": "Open blockers. Omitted when empty."
     },
+    "decisions_pruned_at_phase0": {
+      "type": "boolean",
+      "default": false,
+      "description": "Set to true after Phase 0 archives stale decision rows from previous builds"
+    },
     "decisions_next_id": {
       "type": "object",
       "additionalProperties": { "type": "integer", "minimum": 0 },
@@ -383,6 +388,36 @@
     "current_sprint_context_hash": {
       "type": "string",
       "description": "Stage 6+ (schema_version >= 4). Hash of sprint-scoped shared context; triggers re-render only on sprint boundary."
+    },
+
+    "feature_delegation_plan_path": {
+      "type": "string",
+      "$comment": "Stage 7+ (schema_version >= 5). Populated at Phase 4 Step 4.1 by product-owner agent.",
+      "description": "Stage 7+ (schema_version >= 5). Path to feature-delegation-plan.json written by Product Owner in Phase 4 Step 4.1."
+    },
+    "current_wave": {
+      "type": "integer",
+      "minimum": 1,
+      "$comment": "Stage 7+ (schema_version >= 5). Initialized to 1 at Step 4.1; incremented by orchestrator at Step 4.4.",
+      "description": "Stage 7+ (schema_version >= 5). Current wave number in the feature-delegation plan."
+    },
+    "completed_features": {
+      "type": "array",
+      "items": { "type": "string" },
+      "$comment": "Stage 7+ (schema_version >= 5). Append-only. Set by orchestrator after product-owner ACCEPTED verdict.",
+      "description": "Stage 7+ (schema_version >= 5). Feature names accepted by Product Owner."
+    },
+    "feature_acceptance": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "enum": ["ACCEPTED", "NEEDS_REVISION", "PENDING"] },
+      "$comment": "Stage 7+ (schema_version >= 5). Written by orchestrator after each product-owner acceptance dispatch (Step 4.3).",
+      "description": "Stage 7+ (schema_version >= 5). Product Owner acceptance verdict per feature."
+    },
+    "feature_briefs": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "$comment": "Stage 7+ (schema_version >= 5). Written by orchestrator after each briefing-officer dispatch (Step 4.2.a).",
+      "description": "Stage 7+ (schema_version >= 5). Map of feature name to feature brief file path (docs/plans/feature-briefs/{feature}.md)."
     }
   }
 }

package/protocols/state-schema.md

@@ -16,6 +16,7 @@
 | 2 | Stage 4 | `backward_routing_count` (newly typed), `backward_routing_count_by_target_phase`, `in_flight_backward_edge`, `mode_transitions[]` | A7 forward-reject on `schema_version > MAX_SUPPORTED_SCHEMA_VERSION`; A3 stale-edge decrement on `--resume` |
 | 3 | Stage 5 | `lrr_cycle_state` (object; interior fields loose-typed pending Stage 5 iteration — see "Fields added at v3" below) | `BUILDANYTHING_SDK_LRR=false` reverts to markdown aggregator; `lrr_cycle_state` becomes an ignored field on the orchestrator read path (additive-only, no data loss on downgrade) |
 | 4 | Stage 6 | `current_sprint_context_hash` | `BUILDANYTHING_SDK_SPRINT_CONTEXT=false` (web) and/or `BUILDANYTHING_SDK_SPRINT_CONTEXT_IOS=false` (iOS parity gate) reverts Phase 4 to per-task refs re-send; `current_sprint_context_hash` becomes an ignored field on the orchestrator read path (additive-only, no data loss on downgrade) |
+| 5 | Stage 7 | `feature_delegation_plan_path`, `current_wave`, `completed_features`, `feature_acceptance`, `feature_briefs` | Feature-level fields are additive and optional; a Stage 6 runtime reading a Stage 7 state file with `schema_version` downgraded to `4` will ignore these fields without data loss on the read path |
 
 **A7 forward-reject rule.** When `bin/buildanything-runtime.ts` reads `.build-state.json` at session start, if `schema_version > MAX_SUPPORTED_SCHEMA_VERSION`, the runtime refuses to proceed and emits a clear error pointing to the compat matrix (`docs/migration/sdk-host-compat.md`). This is the A7 defense against silent schema drift — an old runtime must never silently ignore fields a newer runtime persisted. See **Task 4.5.2** for the runtime implementation (out of scope for this prose-only update).
 
@@ -23,7 +24,7 @@
 
 ```jsonc
 {
-  "schema_version": 1,
+  "schema_version": 5,
   "project_type": "ios",
   "phase": 6,
   "step": "6.4",
@@ -53,7 +54,7 @@
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
-| `schema_version` | integer | yes | Currently `2` (Stage 4); see version table above. Bumped on each Shape-B migration stage. |
+| `schema_version` | integer | yes | Currently `5`; see version table above. Bumped on each Shape-B migration stage. |
 | `project_type` | enum | yes | `"ios"` or `"web"`. Drives mode-branch routing. |
 | `phase` | integer | yes | Current phase, one of `-1, 0, 1, 2, 3, 4, 5, 6, 7`. |
 | `step` | string | yes | Dotted step identifier within the phase (e.g., `"5.3b"`, `"6.4"`). |
@@ -80,6 +81,11 @@
 | `resume_point` | object | yes | `{phase, step, autonomous, completed_summary, git_branch}`. Snapshot used by Phase-0 resume logic. |
 | `verification` | object | yes | `{last_verify_result, last_verify_timestamp}`. `last_verify_result` is one of `"PRODUCTION_READY"`, `"NEEDS_WORK"`, `"BLOCKED"`, or `null`. |
 | `blockers` | array | no | Open blockers. Each: `{id, description, surfaced_at, type}`. Type is `"build"`, `"design"`, `"dep"`, or `"external"`. |
+| `decisions_pruned_at_phase0` | boolean | no | Default `false`. Set to `true` after Phase 0 archives stale decision rows. |
+
+### Decision Log Pruning (Phase 0)
+
+At Phase 0, if `docs/plans/decisions.jsonl` exists and contains rows from a previous `session_id`, archive them: copy the file to `docs/plans/decisions.jsonl.prev`, then filter `decisions.jsonl` to retain only rows matching the current `session_id`. Set `decisions_pruned_at_phase0: true`. This prevents unbounded growth across builds while preserving history in the `.prev` file. The LRR Aggregator's star rule only needs current-build decisions for backward routing.
 
 ### Fields added at v2 (Stage 4)
 
@@ -118,6 +124,22 @@ These fields are present only when `schema_version >= 4`. They support the Shape
 
 **SSOT note.** Kiro-owned `protocols/state-schema.json` is authoritative: `properties.current_sprint_context_hash` (string) is already declared, `schema_version.maximum` is already `4`, and the top-level `$comment` migration table already lists Stage 6. This prose mirrors that shape; any future interior fields (should the sprint-context module persist more than a hash) will be documented by tightening this entry alongside a JSON Schema update.
 
+### Fields added at v5 (Stage 7)
+
+These fields are present only when `schema_version >= 5`. They support the three-tier feature delegation architecture in Phase 4 — Product Owner planning, Briefing Officer per-feature briefs, and wave-based execution with acceptance gates.
+
+| Field | Type | Required | Added in | Notes |
+|---|---|---|---|---|
+| `feature_delegation_plan_path` | string | no | v5 | Path to `docs/plans/feature-delegation-plan.json`. Set at Step 4.1. |
+| `current_wave` | integer | no | v5 | Current wave being executed (1-indexed). Set at Step 4.1, incremented at Step 4.4. |
+| `completed_features` | string[] | no | v5 | Feature names that have been ACCEPTED by the Product Owner. |
+| `feature_acceptance` | object | no | v5 | Map of feature name → verdict (`ACCEPTED`, `NEEDS_REVISION`, `IN_PROGRESS`). |
+| `feature_briefs` | object | no | v5 | Map of feature name → path to feature brief file (`docs/plans/feature-briefs/{feature}.md`). |
+
+**v5 migration concern — none in wild.** As of this task, Stage 7 has not shipped. No `.build-state.json` files with `schema_version: 5` exist outside development probes. The runtime will be bumped to `5` as part of Stage 7 activation, not here.
+
+**v5 rollback semantics.** All five fields are additive and optional. A Stage 6 runtime reading a Stage 7 state file with `schema_version` downgraded to `4` will ignore these fields without data loss on the read path. Phase 4 simply reverts to the flat per-task execution model without feature-level delegation.
+
 ## Rendering contract
 
 `.build-state.md` is regenerated from `.build-state.json` on every state change by the orchestrator's state-save routine. It is a view, not a source. The rendering is deterministic: same JSON in → same markdown out.
@@ -152,6 +174,10 @@ Direct writes to `.build-state.json` are prohibited — a partial write leaves u
 
 This section is the authoritative write contract. Other protocol/command files that say "write to `.build-state.json`" mean "via this protocol."
 
+### Compaction Safety Net
+
+The PreCompact hook is a prompt-level reminder (type: "prompt"), not a hard command. As defense-in-depth, the `session-start` hook reads `.build-state.json` on every session start and rebuilds TodoWrite from it. If compaction fires without the orchestrator saving state first, the session-start recovery path restores from the last checkpoint. This is a safety net, not a substitute for the orchestrator honoring compaction checkpoints.
+
 ## Validation rules
 
 A well-formed `.build-state.json` must satisfy:
@@ -170,3 +196,7 @@ A well-formed `.build-state.json` must satisfy:
 12. **Timestamps monotonic** — `session_last_saved >= session_started`.
 
 The Wave 2 `PreToolUse` schema lint hook (W2-2) validates every Write|Edit to `.build-state.json` against these rules and denies writes that fail.
+
+## Consumers — non-orchestrator readers of state
+
+- **Step 7.1.5 Completion Report** (`commands/build.md`) reads `backward_routing_count`, `backward_routing_count_by_target_phase`, and `mode_transitions[]` to surface end-of-build quality signals. See `commands/build.md` Step 7.1.5 for the report template.

package/protocols/verify.md

@@ -47,6 +47,27 @@ The agent runs these checks in order, stopping on the first FAIL:
 ONE AGENT, ONE PASS: The orchestrator spawns exactly ONE agent for the entire verification. This is a single Agent tool call, not 6 separate agents. The agent runs each check as a sequential shell command and evaluates the result before proceeding.
 </HARD-GATE>
 
+**Scope macros** (the caller selects which subset of the 7 checks to run):
+
+| Scope | Checks included |
+|-------|-----------------|
+| `full` | All 7 checks (default) |
+| `build` | Check 1 only |
+| `types` | Check 2 only |
+| `lint` | Check 3 only |
+| `test` | Check 4 only |
+| `security` | Check 5 only |
+| `diff` | Check 6 only |
+| `behavioral` | Check 7 only |
+| `static` | Checks 1, 2, 3, 6 (build, types, lint, diff — no test/security/behavioral) |
+| `ci` | Checks 1, 2, 3, 4 (build, types, lint, test — no security/diff/behavioral) |
+
+The `static` macro is the standard Phase 6 post-metric-loop scope — the metric loop owns behavioral evaluation, so Phase 6 verify skips checks 4 (test), 5 (security), and 7 (behavioral).
+
+The `ci` macro is for CI pipeline integration — it runs the four deterministic, automatable checks and skips security (often handled by separate CI tooling), diff review (no uncommitted changes in CI), and behavioral (requires a running app).
+
+If no scope is specified, default to `full`.
+
 ## Step 2b — Test stub detector
 
 After running the Test check in Step 2, AND after running it as PASS, the orchestrator MUST run the test-stub detector. The detector greps every test file in the project's test directory and fails the verification if any file matches a stub pattern.
@@ -105,10 +126,15 @@ exit $EXIT
 
 ## Step 3: Handle Result
 
-**On PASS:** Log `VERIFY: PASS (7/7)` to `docs/plans/.build-state.md`. Proceed to next phase.
+**On PASS:** Return `VERIFY: PASS (N/N)` to the caller via stdout. State persistence is the orchestrator's responsibility (`.build-state.json.verification` is Reality Checker's field, not the gate's). Proceed to next phase.
 
 **On FAIL:** Read the failure reason and spawn a targeted fix agent:
 
+**Fix-agent dispatch mode (SDK-gated — matches `commands/build.md:946`):**
+
+- **`BUILDANYTHING_SDK=on` (default):** dispatch the fix agent through `claude-agent-sdk` with `maxTurns: 15`. This is a hard safety rail preventing runaway remediation loops. If a fix exceeds 15 turns, the orchestrator flags to user (interactive mode) or logs a warning and fails the verify (autonomous mode) — do NOT let the subagent churn indefinitely.
+- **`BUILDANYTHING_SDK=off`:** fall back to Agent tool dispatch with a self-reported 15-tool-call cap (surfaced via `tool_calls_used` in the agent's return). Same enforcement policy as SDK mode.
+
 | Failed Check | Fix Strategy |
 |-------------|-------------|
 | Build / Type-Check / Lint | Run the Build-Fix Protocol (`protocols/build-fix.md`). It isolates the first error, fixes it, rebuilds, detects cascade resolution, and reverts bad fixes automatically. |
@@ -119,6 +145,8 @@ exit $EXIT
 
 After the fix agent completes, re-run verification from Step 2.
 
+**Token accounting (Stage 3 G3):** each fix-agent dispatch emits a cost line to `docs/plans/build-log.md` via `src/orchestrator/hooks/token-accounting-emitter.ts`. Under `BUILDANYTHING_SDK=on`, the emitter subscribes to SDK `usage` messages automatically. Under markdown fallback, the orchestrator writes the line using the subagent's self-reported token count. Verify's fix loop is a known cost hotspot and must be attributed to the parent phase.
+
 <HARD-GATE>
 MAX 3 FIX ATTEMPTS: If verification fails 3 times on the same phase:
 - **Interactive mode:** present the failure history to the user. Ask for direction.