buildanything 2.0.0 → 2.1.2

package/protocols/page-spec-schema.md

@@ -0,0 +1,234 @@
+# Page Spec Schema
+
+## Purpose
+
+Step 3.3's UX architect (`design-ux-architect`) produces page specs alongside `ux-architecture.md` — flows and layouts are created together because they inform each other. One file per screen is emitted to `docs/plans/page-specs/{screen-name}.md`. Each file is the spatial blueprint for a single screen — ASCII wireframe + structured metadata — so Phase 4 implementers know exactly what to build without interpreting prose. This protocol defines the required sections, wireframe format, platform conventions, and validation rules.
+
+## Inputs
+
+The page spec writer reads these artifacts before producing any page spec:
+
+- `docs/plans/product-spec.md` — feature states, data requirements, persona constraints, screen inventory (SOURCE OF TRUTH for what each screen does)
+- `docs/plans/architecture.md` — frontend component hierarchy, routing, API contracts
+- `DESIGN.md` `## Overview > ### Brand DNA` — 7-axis DNA card (Density axis drives layout decisions)
+- `docs/plans/component-manifest.md` — library component picks per slot
+- `docs/plans/design-references/` — competitor/inspiration screenshots for layout reference
+
+NOTE: `visual-design-spec.md` does NOT exist yet when page specs are produced (it's created at Step 3.4, after Step 3.3). Page specs use the DNA Density axis for spatial decisions (Airy vs Dense) and the component manifest for component choices. Exact spacing values and typography ramp are applied by Phase 4 implementers when they build from the visual design spec.
+
+## Questions Answered
+
+Page specs close three questions from the Phase 0-3 question map:
+
+- **Q50** — Screen layouts (spatial arrangement of every element)
+- **Q51** — Content hierarchy (what's primary, secondary, tertiary per screen)
+- **Q53** — Key copy per screen (headings, CTAs, empty states, errors)
+
+## File Convention
+
+- Path: `docs/plans/page-specs/{screen-name}.md` (kebab-case)
+- Anchors: `page-specs/{screen-name}#wireframe`, `page-specs/{screen-name}#content-hierarchy`, `page-specs/{screen-name}#key-copy`, etc.
+- One file per screen in the product-spec Screen Inventory. Multi-step flows (e.g., checkout) get one file per step.
+
+## Required Sections
+
+Every page spec MUST contain these sections, in this order.
+
+### 1. Screen Overview
+
+One line: what this screen is, which feature(s) it serves.
+
+### 2. ASCII Wireframe
+
+Spatial layout using box-drawing characters. Desktop wireframe required for all platforms. Mobile wireframe required for web projects. Section labels inside brackets map to Content Hierarchy entries.
+
+### 3. Content Hierarchy
+
+Ordered list (top → bottom, primary → tertiary) of every content section. Each entry: section name, data shown, component from manifest (or `custom`), data source (API endpoint or `local`/`computed`), visual weight (`primary`/`secondary`/`tertiary`).
+
+### 4. Key Copy
+
+Headings, CTAs, labels, empty state messages, error messages for this screen. Not every string — the ones that set the tone and guide implementation.
+
+### 5. Responsive Behavior (web only)
+
+What changes at each breakpoint: desktop (1024px+), tablet (768px), mobile (375px). What reflows, collapses, or hides.
+
+### 6. Platform Conventions
+
+Which platform patterns this screen follows. iOS: navigation stack, tab bar, sheets. Web: sidebar state, breadcrumbs, header nav. Reference the relevant HIG pattern or web convention.
+
+### 7. Data Loading
+
+What's fetched on mount, loading skeleton description, refresh strategy (pull-to-refresh, auto-refresh, manual).
+
+### 8. States
+
+Reference to product-spec feature states, plus screen-specific visual states: skeleton loading, partial data, stale indicator, empty, error.
+
+## ASCII Wireframe Format
+
+**Characters:** `┌ ┐ └ ┘ ─ │ ├ ┤ ┬ ┴ ┼`
+
+**Rules:**
+- Label every section inside brackets: `[Header]`, `[Sidebar]`, `[KPI Cards]`
+- Show relative sizing — sidebar narrower than main content
+- Desktop wireframe: ~60 chars wide
+- Mobile wireframe: ~30 chars wide
+- Include placeholder text for key copy: `[Place Order]`, `[Your cart is empty...]`
+- Density axis from visual-dna.md drives spacing: Airy = generous gaps between sections, fewer items visible. Dense = compact rows, more items per viewport.
+
+## Platform-Specific Wireframe Conventions
+
+**Web SaaS:** Sidebar + main content area. Header with nav. Sidebar collapses to hamburger on mobile.
+
+**iOS:** Navigation bar at top (title, back button if applicable), content area, tab bar at bottom. Standard HIG layout patterns. See iOS-specific conventions section below for full requirements.
+
+**Dashboard/Analytics:** Filter bar, card grid, chart placement. Dense layout with data tables.
+
+**CLI:** No wireframe. Show command output format with example terminal session instead.
+
+**Mobile (React Native/Expo):** Follow target platform conventions — iOS patterns if iOS, Material if Android, cross-platform neutral if both.
+
+### iOS-specific wireframe conventions
+
+When `project_type=ios`, page-specs follow these conventions:
+
+- **Single viewport:** iPhone 16 Pro (393×852 logical) as the primary; iPad layout deltas captured as a Notes section. No second mobile/desktop view.
+- **Navigation annotation:** name the parent NavigationStack / TabView / sheet and the back/dismiss gesture per screen.
+- **Component refs:** every interactive element references a DESIGN.md `components:` token name (e.g., `button-primary`, `list-row-grouped`, `card-elevated`) — these are SwiftUI view modifiers at Phase 4.
+- **Dynamic Type:** declare which typography role tokens the screen uses; flag any layout that breaks at xxxLarge.
+- **Safe-area handling:** name top/bottom safe-area treatments (large title vs nav bar; tab bar inset).
+- **Data loading strategy:** async/await + `.task` modifier vs `ObservableObject` reference; loading/error/empty states sourced from product-spec.md per-feature sections.
+
+## Validation Checklist
+
+1. Every screen in product-spec.md Screen Inventory has a page spec file
+2. Every page spec has all 8 required sections (skip Responsive Behavior for non-web)
+3. Every content hierarchy entry references a component from `component-manifest.md` or marks it `custom`
+4. Every data source references an API endpoint from `architecture.md#backend/api` or marks it `local`/`computed`
+5. ASCII wireframe exists for desktop (and mobile for web projects)
+6. Section labels in wireframe match content hierarchy entry names
+7. Key copy includes at least: one heading, one primary CTA, one empty state message
+
+## Worked Example: Dashboard (Web SaaS)
+
+```markdown
+# Page Spec: Dashboard
+
+## Screen Overview
+
+Main dashboard — KPI summary, recent activity, and quick actions. Features: Dashboard, Notifications.
+
+## ASCII Wireframe
+
+### Desktop (1024px+)
+
+┌──────────────────────────────────────────────────────────┐
+│ [Header]                          [Search] [Avatar ▼]    │
+├────────────┬─────────────────────────────────────────────┤
+│ [Sidebar]  │ [Page Title: Dashboard]                     │
+│            │                                             │
+│  Dashboard │ ┌─────────┐ ┌─────────┐ ┌─────────┐        │
+│  Orders    │ │[KPI:    ]│ │[KPI:    ]│ │[KPI:    ]│       │
+│  Products  │ │ Revenue  │ │ Orders   │ │ Users    │       │
+│  Customers │ │ $12,340  │ │ 142      │ │ 1,203    │       │
+│  Settings  │ └─────────┘ └─────────┘ └─────────┘        │
+│            │                                             │
+│            │ ┌──────────────────────────────────────┐    │
+│            │ │[Revenue Chart]                       │    │
+│            │ │                                      │    │
+│            │ │  ▁▂▃▅▆▇█▇▆▅▃▂▁▂▃▅▆▇                │    │
+│            │ │                                      │    │
+│            │ └──────────────────────────────────────┘    │
+│            │                                             │
+│            │ ┌──────────────────────────────────────┐    │
+│            │ │[Activity Feed]                       │    │
+│            │ │ • New order #1042 — 2m ago           │    │
+│            │ │ • User signed up — 15m ago           │    │
+│            │ │ • Payment received — 1h ago          │    │
+│            │ └──────────────────────────────────────┘    │
+├────────────┴─────────────────────────────────────────────┤
+│ [Footer]                                                 │
+└──────────────────────────────────────────────────────────┘
+
+### Mobile (375px)
+
+┌────────────────────────────┐
+│ [Header]  [☰]   [Avatar]  │
+├────────────────────────────┤
+│ [Page Title: Dashboard]    │
+│                            │
+│ ┌────────────────────────┐ │
+│ │[KPI: Revenue]  $12,340 │ │
+│ └────────────────────────┘ │
+│ ┌────────────────────────┐ │
+│ │[KPI: Orders]   142     │ │
+│ └────────────────────────┘ │
+│ ┌────────────────────────┐ │
+│ │[KPI: Users]    1,203   │ │
+│ └────────────────────────┘ │
+│                            │
+│ ┌────────────────────────┐ │
+│ │[Revenue Chart]         │ │
+│ │ ▁▂▃▅▆▇█▇▆▅▃▂▁▂▃▅▆▇   │ │
+│ └────────────────────────┘ │
+│                            │
+│ ┌────────────────────────┐ │
+│ │[Activity Feed]         │ │
+│ │ • New order — 2m ago   │ │
+│ │ • Signup — 15m ago     │ │
+│ │ • Payment — 1h ago     │ │
+│ └────────────────────────┘ │
+└────────────────────────────┘
+
+## Content Hierarchy
+
+| # | Section | Data Shown | Component | Data Source | Weight |
+|---|---------|-----------|-----------|-------------|--------|
+| 1 | KPI Cards | Revenue, order count, active users (current period + delta) | `StatCard` from manifest | `GET /api/dashboard/kpis` | primary |
+| 2 | Revenue Chart | 30-day revenue trend line | `AreaChart` from manifest | `GET /api/dashboard/revenue?range=30d` | primary |
+| 3 | Activity Feed | Last 10 events (orders, signups, payments) with relative timestamps | `FeedList` from manifest | `GET /api/dashboard/activity?limit=10` | secondary |
+| 4 | Header | App logo, search, user avatar dropdown | `AppHeader` from manifest | `local` (user session) | tertiary |
+| 5 | Sidebar | Navigation links with active state, unread badge on notifications | `SideNav` from manifest | `local` (route) + `GET /api/notifications/count` | tertiary |
+
+## Key Copy
+
+- **Page heading:** "Dashboard"
+- **KPI labels:** "Revenue" · "Orders" · "Active Users"
+- **KPI delta format:** "+12% vs last period" / "−3% vs last period"
+- **Activity feed heading:** "Recent Activity"
+- **Empty activity state:** "No activity yet. Once your first order comes in, you'll see it here."
+- **Error state:** "Couldn't load dashboard data. Check your connection and try again." CTA: [Retry]
+- **Stale indicator:** "Last updated 5 minutes ago" (appears after 60s without refresh)
+
+## Responsive Behavior
+
+| Breakpoint | Changes |
+|-----------|---------|
+| Desktop (1024px+) | Sidebar visible. KPI cards in 3-column row. Chart full width of main area. |
+| Tablet (768px) | Sidebar collapses to icon-only rail. KPI cards in 3-column row (narrower). Chart full width. |
+| Mobile (375px) | Sidebar hidden behind hamburger menu. KPI cards stack vertically (full width each). Chart full width. Activity feed below chart. |
+
+## Platform Conventions
+
+- **Web SaaS pattern:** Persistent sidebar navigation with active-state highlight on current page. Header with global search and user menu. Breadcrumbs not needed (top-level screen).
+- **Sidebar:** Collapsible — user preference persisted in local storage. Icon-only mode at tablet breakpoint.
+- **Data refresh:** No pull-to-refresh (web). Auto-refresh every 60s via polling. Manual refresh button in header.
+
+## Data Loading
+
+- **On mount:** Parallel fetch `GET /api/dashboard/kpis`, `GET /api/dashboard/revenue?range=30d`, `GET /api/dashboard/activity?limit=10`
+- **Loading skeleton:** 3 shimmer rectangles for KPI cards (same dimensions as loaded cards). Chart area shows shimmer block. Activity feed shows 3 shimmer rows with avatar circle + text lines.
+- **Refresh:** Auto-poll every 60s. Stale indicator appears if last successful fetch > 60s ago. No full-page reload — data swaps in place.
+
+## States
+
+- **From product-spec:** `initial`, `loading`, `loaded`, `empty`, `error`, `stale`
+- **Screen-specific visuals:**
+  - `skeleton-loading` — shimmer cards + shimmer chart + shimmer feed rows (see Data Loading)
+  - `partial-data` — KPIs loaded but chart still loading: show KPI cards, chart area shows shimmer
+  - `stale` — data older than 60s: subtle "Last updated X ago" badge below page title
+  - `empty` — new account, no data yet: KPI cards show "—", chart shows flat line, activity feed shows empty state copy
+  - `error` — fetch failed: inline error banner with retry button, no full-page error
+```

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`