haiku-method 2.2.0

package/studios/software/examples/add-oauth-login/stages/design/units/unit-02-oauth-flow.md

@@ -0,0 +1,19 @@
+---
+title: OAuth Flow
+type: design
+status: complete
+depends_on: [unit-01-login-screen]
+---
+
+# Unit 02: OAuth Flow
+
+Design the user experience for the OAuth authorization and callback flow.
+
+## Completion Criteria
+
+- [x] Loading state while redirecting to provider (spinner + "Redirecting to Google/GitHub...")
+- [x] Callback processing state (spinner + "Signing you in...")
+- [x] Error states for each error type: access denied, expired code, rate limited, generic error
+- [x] Success redirect: callback -> brief success indicator -> app dashboard
+- [x] Error redirect: callback -> login page with contextual error message
+- [x] Flow diagram covering happy path, error paths, and rate-limit path

package/studios/software/examples/add-oauth-login/stages/development/state.json

@@ -0,0 +1,11 @@
+{
+  "stage": "development",
+  "status": "complete",
+  "current_unit": null,
+  "completed_units": [
+    "unit-01-oauth-provider",
+    "unit-02-login-ui",
+    "unit-03-session-mgmt"
+  ],
+  "iteration": 0
+}

package/studios/software/examples/add-oauth-login/stages/development/units/unit-01-oauth-provider.md

@@ -0,0 +1,21 @@
+---
+title: OAuth Provider Integration
+type: backend
+status: complete
+depends_on: []
+---
+
+# Unit 01: OAuth Provider Integration
+
+Implement the OAuth provider abstraction and concrete providers for Google and GitHub.
+
+## Completion Criteria
+
+- [x] `OAuthProvider` interface implemented with `getAuthorizationUrl`, `exchangeCode`, `getUserProfile`
+- [x] `GoogleOAuthProvider` implements server-side code exchange with PKCE support
+- [x] `GitHubOAuthProvider` implements code exchange + separate user profile and email API calls
+- [x] Provider registry: `getProvider(name: string): OAuthProvider` with runtime validation
+- [x] Callback route `GET /auth/callback/:provider` validates state, exchanges code, creates/links user, creates session
+- [x] Race condition fix: mutex lock on token write to prevent concurrent token exchanges from corrupting the token store
+- [x] Unit tests for both providers with mocked HTTP responses (>80% coverage)
+- [x] Integration test: full callback flow with test OAuth server

package/studios/software/examples/add-oauth-login/stages/development/units/unit-02-login-ui.md

@@ -0,0 +1,21 @@
+---
+title: Login UI
+type: frontend
+status: complete
+depends_on: [unit-01-oauth-provider]
+---
+
+# Unit 02: Login UI
+
+Build the login page components following the design brief specifications.
+
+## Completion Criteria
+
+- [x] `LoginPage` component: full-page layout with centered card, app logo, social buttons
+- [x] `OAuthButton` component: provider logo, label, all interactive states (hover, focus, active, loading, disabled)
+- [x] Responsive layout verified at 375px, 768px, and 1280px breakpoints
+- [x] "Forgot password?" link positioned below social buttons, navigates to `/forgot-password`
+- [x] Error display: reads `?error=` query param and shows contextual error message
+- [x] Loading state: button shows spinner and "Connecting..." during OAuth redirect
+- [x] Touch targets: all buttons at least 44px on mobile
+- [x] Accessibility: `aria-label` on buttons, `aria-busy` on loading, focus ring on all interactive elements

package/studios/software/examples/add-oauth-login/stages/development/units/unit-03-session-mgmt.md

@@ -0,0 +1,21 @@
+---
+title: Session Management
+type: backend
+status: complete
+depends_on: [unit-01-oauth-provider]
+---
+
+# Unit 03: Session Management
+
+Implement the session lifecycle including creation, storage, refresh, and expiration.
+
+## Completion Criteria
+
+- [x] Session creation: generates access token (1h expiry) and refresh token (30d expiry), stored in httpOnly cookies
+- [x] Cookie flags: `Secure`, `SameSite=Lax`, `HttpOnly`, `Path=/`
+- [x] Refresh endpoint `POST /auth/refresh`: validates refresh token, issues new access token, rotates refresh token
+- [x] Logout endpoint `POST /auth/logout`: clears cookies and invalidates refresh token in database
+- [x] Rate limiting: callback endpoint enforces 100 req/min per IP, returns 429 with `Retry-After` header
+- [x] Concurrent sessions: user can be logged in from multiple devices simultaneously
+- [x] Database migration: `sessions` table with `user_id`, `refresh_token_hash`, `expires_at`, `created_at`
+- [x] Unit tests for session creation, refresh, expiration, and revocation

package/studios/software/examples/add-oauth-login/stages/inception/state.json

@@ -0,0 +1,12 @@
+{
+  "stage": "inception",
+  "status": "complete",
+  "current_unit": null,
+  "completed_units": [
+    "unit-01-oauth-provider-setup",
+    "unit-02-callback-handler",
+    "unit-03-session-management",
+    "unit-04-callback-error-handling"
+  ],
+  "iteration": 0
+}

package/studios/software/examples/add-oauth-login/stages/inception/units/unit-01-oauth-provider-setup.md

@@ -0,0 +1,18 @@
+---
+title: OAuth Provider Setup
+type: research
+status: complete
+depends_on: []
+---
+
+# Unit 01: OAuth Provider Setup
+
+Research and map the OAuth provider abstraction layer for Google and GitHub.
+
+## Completion Criteria
+
+- [x] Provider abstraction interface defined with `getAuthorizationUrl`, `exchangeCode`, and `getUserProfile` methods
+- [x] Google OAuth flow mapped: authorization URL construction, server-side code exchange, id_token parsing
+- [x] GitHub OAuth flow mapped: authorization URL, token exchange, separate `/user` and `/user/emails` API calls
+- [x] PKCE support documented — Google supports it, GitHub does not (state param + client_secret only)
+- [x] Scope requirements documented for each provider

package/studios/software/examples/add-oauth-login/stages/inception/units/unit-02-callback-handler.md

@@ -0,0 +1,18 @@
+---
+title: Callback Handler
+type: backend
+status: complete
+depends_on: [unit-01-oauth-provider-setup]
+---
+
+# Unit 02: Callback Handler
+
+Analyze the OAuth callback flow for both providers and define the handler contract.
+
+## Completion Criteria
+
+- [x] Callback handler route defined: `GET /auth/callback/:provider`
+- [x] State parameter validation flow documented (CSRF protection)
+- [x] Google code exchange flow mapped — server-side exchange returns id_token directly
+- [x] GitHub code exchange flow mapped — returns access_token, requires separate API call for profile
+- [x] Token-to-session mapping defined: exchange result -> user lookup/create -> session creation

package/studios/software/examples/add-oauth-login/stages/inception/units/unit-03-session-management.md

@@ -0,0 +1,18 @@
+---
+title: Session Management
+type: backend
+status: complete
+depends_on: [unit-02-callback-handler]
+---
+
+# Unit 03: Session Management
+
+Define session lifecycle: creation, storage, refresh, and expiration.
+
+## Completion Criteria
+
+- [x] Session stored as httpOnly cookie with Secure and SameSite=Lax flags
+- [x] Access token expires after 1 hour, refresh token after 30 days
+- [x] Refresh endpoint defined: `POST /auth/refresh`
+- [x] Session revocation on logout: `POST /auth/logout` clears cookie and invalidates refresh token in database
+- [x] Concurrent session support — user can be logged in from multiple devices

package/studios/software/examples/add-oauth-login/stages/inception/units/unit-04-callback-error-handling.md

@@ -0,0 +1,18 @@
+---
+title: Callback Error Handling
+type: backend
+status: complete
+depends_on: [unit-02-callback-handler]
+---
+
+# Unit 04: Callback Error Handling
+
+Map error paths for both OAuth providers. Google and GitHub have different failure modes that need separate error handling.
+
+## Completion Criteria
+
+- [x] Google error responses mapped: `access_denied`, `invalid_grant` (expired code), `invalid_client`
+- [x] GitHub error responses mapped: `bad_verification_code`, `incorrect_client_credentials`, `redirect_uri_mismatch`
+- [x] Error-to-user-message mapping defined — each provider error maps to a user-friendly message
+- [x] Rate limiting on callback endpoint: 100 requests/minute per IP, returns 429 with `Retry-After` header
+- [x] All error paths redirect to `/login?error={code}` with provider-specific error codes

package/studios/software/examples/add-oauth-login/stages/operations/state.json

@@ -0,0 +1,9 @@
+{
+  "stage": "operations",
+  "status": "complete",
+  "current_unit": null,
+  "completed_units": [
+    "unit-01-deploy-config"
+  ],
+  "iteration": 0
+}

package/studios/software/examples/add-oauth-login/stages/operations/units/unit-01-deploy-config.md

@@ -0,0 +1,21 @@
+---
+title: Deploy Configuration
+type: ops
+status: complete
+depends_on: []
+---
+
+# Unit 01: Deploy Configuration
+
+Configure deployment infrastructure for OAuth integration including secret management, health checks, and operational readiness.
+
+## Completion Criteria
+
+- [x] Vault policy created: `oauth-secrets` policy with read access to `secret/data/oauth/{google,github}`
+- [x] Vault injector sidecar configured in Helm values — secrets mounted as env vars `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`
+- [x] Health check endpoint `/health/oauth` verifies connectivity to both provider token endpoints
+- [x] Health check timeout: 5 seconds, failure triggers alert
+- [x] Terraform resource `oauth.tf` defines Vault policy and role bindings
+- [x] Rollback plan documented: revert Helm release, rotate compromised secrets via Vault CLI
+- [x] Monitoring: error rate alert at >1% over 5 minutes on `/auth/callback/*` routes
+- [x] Runbook covers: secret rotation, provider outage response, rate limit tuning

package/studios/software/examples/add-oauth-login/stages/product/state.json

@@ -0,0 +1,9 @@
+{
+  "stage": "product",
+  "status": "complete",
+  "current_unit": null,
+  "completed_units": [
+    "unit-01-auth-spec"
+  ],
+  "iteration": 0
+}

package/studios/software/examples/add-oauth-login/stages/product/units/unit-01-auth-spec.md

@@ -0,0 +1,21 @@
+---
+title: Auth Specification
+type: product
+status: complete
+depends_on: []
+---
+
+# Unit 01: Auth Specification
+
+Define the behavioral specification and acceptance criteria for the OAuth authentication flow.
+
+## Completion Criteria
+
+- [x] Happy path specified: user clicks provider button -> redirect -> authorize -> callback -> session created -> redirect to dashboard
+- [x] Error scenario: invalid authorization code -> 400 error with user-friendly message -> redirect to login with error
+- [x] Error scenario: expired authorization code -> redirect to login with "session expired, please try again" message
+- [x] Error scenario: user denies authorization at provider -> redirect to login with "authorization cancelled" message
+- [x] Rate limiting: callback endpoint returns 429 with `Retry-After` header at 100 requests/minute per IP
+- [x] Data contract: `POST /auth/callback/:provider` request/response schema with field types, required fields, and validation rules
+- [x] Data contract: `POST /auth/refresh` request/response schema
+- [x] Data contract: `POST /auth/logout` request/response schema

package/studios/software/examples/add-oauth-login/stages/security/state.json

@@ -0,0 +1,10 @@
+{
+  "stage": "security",
+  "status": "complete",
+  "current_unit": null,
+  "completed_units": [
+    "unit-01-threat-model",
+    "unit-02-pen-test"
+  ],
+  "iteration": 0
+}

package/studios/software/examples/add-oauth-login/stages/security/units/unit-01-threat-model.md

@@ -0,0 +1,41 @@
+---
+title: Threat Model
+type: security
+status: complete
+depends_on: []
+---
+
+# Unit 01: Threat Model
+
+STRIDE analysis of the OAuth authentication surface.
+
+## Completion Criteria
+
+- [x] Spoofing: state parameter validated on callback to prevent CSRF — cryptographically random, single-use, expires after 10 minutes
+- [x] Tampering: all tokens stored in httpOnly cookies — no client-side JavaScript access
+- [x] Repudiation: authentication events logged with timestamp, provider, user_id, IP, success/failure
+- [x] Information Disclosure: no sensitive data (tokens, secrets) in URL params, logs, or error messages
+- [x] Denial of Service: rate limiting on callback endpoint (100 req/min per IP) with 429 response
+- [x] Elevation of Privilege: OAuth scopes limited to minimum needed (`openid email profile` for Google, `user:email read:user` for GitHub)
+
+## Known Risks (Accepted)
+
+### GitHub PKCE Gap — MEDIUM
+
+GitHub's OAuth implementation does not support PKCE (Proof Key for Code Exchange). This means the authorization code flow relies solely on the `state` parameter for CSRF protection and `client_secret` for code exchange security.
+
+**Compensating controls:**
+- Strict state validation (cryptographically random, single-use, 10-minute expiry)
+- Short-lived authorization codes (GitHub default: 10 minutes)
+- Client secret stored in Vault, never exposed client-side
+- All token exchanges happen server-side
+
+**Risk acceptance:** This is a GitHub platform limitation, not a fixable vulnerability. The compensating controls reduce the practical risk to acceptable levels.
+
+## Findings Addressed
+
+### localStorage Token Storage — HIGH (Fixed)
+
+One code path stored the access token in `localStorage` instead of an httpOnly cookie. This was found in the OAuth callback error recovery flow where a failed cookie write fell through to a localStorage fallback.
+
+**Fix:** Removed the localStorage fallback entirely. Failed cookie writes now redirect to login with a `cookie-error` message. No tokens are ever accessible to client-side JavaScript.

package/studios/software/examples/add-oauth-login/stages/security/units/unit-02-pen-test.md

@@ -0,0 +1,21 @@
+---
+title: Penetration Test
+type: security
+status: complete
+depends_on: [unit-01-threat-model]
+---
+
+# Unit 02: Penetration Test
+
+Automated and manual security testing of the OAuth implementation.
+
+## Completion Criteria
+
+- [x] OWASP Top 10 coverage: each category tested or documented as N/A with justification
+- [x] SQL injection: all queries use Prisma parameterized statements — grep confirms no raw query string concatenation
+- [x] XSS: error messages sanitized before rendering, no `dangerouslySetInnerHTML` with user input
+- [x] CSRF: state parameter validation confirmed — replayed state values rejected
+- [x] Token security: confirmed no tokens in URL params, response bodies to client, or application logs
+- [x] Cookie flags verified: `HttpOnly`, `Secure`, `SameSite=Lax` on all auth cookies
+- [x] Rate limiting confirmed: 429 returned at 101st request within 1-minute window
+- [x] Secret exposure scan: no OAuth secrets in source code, CI logs, or Terraform state files

package/studios/software/fix-hats/reconciler.md

@@ -0,0 +1,10 @@
+---
+agent_type: general-purpose
+---
+**Focus:** Reconcile cross-stage artifacts against studio-wide standards. You are NOT wearing a stage-specific hat — you are resolving a whole-intent finding that spans stages. Your mandate is alignment and consistency, not fresh design or implementation.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** create new units, new design directions, or new implementation features
+- The agent **MUST NOT** modify unit workflow engine fields (`bolt`, `hat`, `status`, `iterations`)
+- The agent **MUST NOT** touch artifacts unrelated to the named finding
+- The agent **MUST NOT** re-open settled decisions from each stage's review gate

package/studios/software/fix-hats/validator.md

@@ -0,0 +1,10 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**Focus:** Independently verify that the reconciler's fix actually resolves the intent-scope feedback finding. You are the terminal hat in the studio fix-hat sequence — the parent will trust your closure decision.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** edit any file — you are a verifier, not a fixer
+- The agent **MUST NOT** close a finding that isn't actually resolved — that's how drift hides
+- The agent **MUST NOT** reject a finding because "it's not worth fixing" — either the reconciler fixes it, it gets escalated at the bolt cap, or it's a genuinely invalid finding

package/studios/software/operations/backup-verification.md

@@ -0,0 +1,21 @@
+---
+name: backup-verification
+type: scheduled
+owner: agent
+schedule: "0 3 1 * *"
+runtime: node
+---
+
+**Purpose:** Verify that backups are actually restorable. An untested backup is not a backup.
+
+**Procedure:**
+- List most recent backups for all data stores
+- Restore the latest backup to a test environment
+- Run integrity checks against the restored data
+- Verify row counts match production within tolerance
+- Clean up test environment
+
+**Signals:**
+- Monthly schedule
+- After any database schema migration
+- After any storage infrastructure change

package/studios/software/operations/dependency-audit.md

@@ -0,0 +1,20 @@
+---
+name: dependency-audit
+type: scheduled
+owner: agent
+schedule: "0 9 * * 1"
+runtime: node
+---
+
+**Purpose:** Detect vulnerable, outdated, or deprecated dependencies before they become incidents. Supply chain security is a leading attack vector.
+
+**Procedure:**
+- Run `npm audit` / `yarn audit` or equivalent for the package manager
+- Check for critical and high severity vulnerabilities
+- Identify dependencies more than 2 major versions behind
+- Flag deprecated packages that need replacement
+
+**Signals:**
+- CI audit step starts failing
+- Dependabot/Renovate PRs accumulating without review
+- CVE announcements affecting project dependencies

package/studios/software/operations/health-check.md

@@ -0,0 +1,21 @@
+---
+name: health-check
+type: reactive
+owner: agent
+trigger: "deployment completed"
+runtime: node
+---
+
+**Purpose:** Verify the system is healthy after each deployment. Catch regressions before users do.
+
+**Procedure:**
+- Hit all health check endpoints and verify 200 responses
+- Verify database connectivity and migration state
+- Check that background job queues are processing
+- Verify external service integrations are responding
+- Compare error rate against pre-deployment baseline
+
+**Signals:**
+- Deployment pipeline completes
+- Alert fires within 30 minutes of deployment
+- Error rate exceeds baseline by more than 2x

package/studios/software/operations/secret-rotation.md

@@ -0,0 +1,21 @@
+---
+name: secret-rotation
+type: scheduled
+owner: human
+frequency: "quarterly"
+---
+
+**Purpose:** Rotate API keys, tokens, and credentials on a regular cadence to limit blast radius of any undetected compromise.
+
+**Procedure:**
+- [ ] Inventory all secrets in use (env vars, vault entries, CI secrets)
+- [ ] Generate new credentials for each service
+- [ ] Update secrets in all environments (dev, staging, production)
+- [ ] Verify services function with new credentials
+- [ ] Revoke old credentials
+- [ ] Update documentation if secret format changed
+
+**Signals:**
+- Quarterly calendar reminder
+- After any team member departure
+- After any suspected credential exposure

package/studios/software/reflections/architecture.md

@@ -0,0 +1,17 @@
+---
+name: architecture
+studio: software
+---
+
+**Analyze:** Technical debt introduced vs resolved, module boundary violations, dependency direction changes.
+
+**Look for:**
+- New abstractions introduced: were they justified or premature?
+- Shared code changes that affected multiple consumers
+- Circular dependency introductions
+- Patterns that diverge from existing codebase conventions
+
+**Produce:**
+- Architectural impact assessment
+- Technical debt delta (net increase or decrease)
+- Recommendations for structural improvements in follow-up intents

package/studios/software/reflections/process.md

@@ -0,0 +1,17 @@
+---
+name: process
+studio: software
+---
+
+**Analyze:** Hat effectiveness, stage transition friction, tool failure patterns from session transcripts.
+
+**Look for:**
+- Planner plans that the builder immediately abandoned (wasted work)
+- Stage transitions that required stage-back refinements (upstream gaps)
+- Tool failures that caused repeated retries
+- Context loss across sessions (same decisions remade, same questions asked)
+
+**Produce:**
+- Hat instruction improvement recommendations
+- Stage input/output completeness assessment
+- Settings and CLAUDE.md update recommendations

package/studios/software/reflections/quality.md

@@ -0,0 +1,17 @@
+---
+name: quality
+studio: software
+---
+
+**Analyze:** Review agent findings, quality gate pass/fail rates, test coverage changes, and reviewer hat rejection patterns.
+
+**Look for:**
+- Review agent categories with the most HIGH findings (security, correctness, etc.)
+- Quality gates that always pass (potentially useless) or always fail (potentially misconfigured)
+- Test coverage trends across units
+- Reviewer rejections that led to productive fixes vs circular rework
+
+**Produce:**
+- Quality gate effectiveness assessment
+- Review agent value ranking (which agents caught real issues vs noise)
+- Recommendations for gate/agent configuration changes

package/studios/software/reflections/velocity.md

@@ -0,0 +1,17 @@
+---
+name: velocity
+studio: software
+---
+
+**Analyze:** Bolt counts per unit, blocker frequency, retry patterns, and session count.
+
+**Look for:**
+- Units that took disproportionately many bolts compared to their estimated complexity
+- Systemic blockers vs one-off issues
+- Whether elaboration granularity matched actual implementation complexity
+- Sessions that ended due to context exhaustion vs natural completion
+
+**Produce:**
+- Velocity assessment: which units were smooth, which were grinding
+- Elaboration quality score: were units right-sized?
+- Recommendations for future elaboration (too coarse, too fine, or just right)

package/studios/software/review-agents/cross-stage-consistency.md

@@ -0,0 +1,18 @@
+---
+scope: intent
+interpretation: lens
+---
+**Mandate:** Verify the intent's artifacts are internally consistent across stages. You are the ONLY reviewer that sees the whole intent at once — inception, product, design, development, security, operations. Your job is to catch the seams.
+
+**Check:**
+- The agent **MUST** verify that the design artifacts match what product specified — no invented requirements, no dropped ones
+- The agent **MUST** verify that development implements what design specified — component names, interaction contracts, responsive behavior, accessibility requirements
+- The agent **MUST** verify that security and operations concerns raised in inception/product were actually addressed in the implementation (not silently ignored)
+- The agent **MUST** verify that naming is consistent across stages — a feature called `checkout-v2` in product should not be `new-cart-flow` in design and `v2Checkout` in code
+- The agent **MUST** verify that stages' declared outputs exist at the paths their unit frontmatter promised — broken cross-stage references are findings
+- The agent **MUST** verify that the stages collectively deliver the intent's stated goal (read `intent.md`) — partial delivery is a finding
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** re-litigate decisions made at each stage's gate — this is a consistency check, not a redesign
+- The agent **MUST NOT** propose new features or scope additions
+- The agent **MUST NOT** flag stylistic preferences — concrete divergence only

package/studios/software/stages/design/STAGE.md

@@ -0,0 +1,19 @@
+---
+name: design
+description: Visual and interaction design for user-facing surfaces
+hats: [designer-prep, designer, design-reviewer]
+fix_hats: [designer, feedback-assessor]
+review: [external, ask]
+elaboration: collaborative
+inputs:
+  - stage: inception
+    discovery: discovery
+---
+
+# Design
+
+Where the work gets its shape. The designer translates the elaborated problem into wireframes, component states, interaction specs, and layout rules that downstream stages can build against. Scope is visual and interaction design only — not product contracts, not implementation.
+
+## Why `designer-prep` is absent from `fix_hats`
+
+The fix loop dispatches `designer` (and `feedback-assessor`) against open feedback — `designer-prep` is intentionally NOT in `fix_hats`. Mirrors the development stage's omission of `planner`: plan-class hats produce upstream baton artifacts (here, `DESIGN-SYSTEM-ANCHOR.md`), not the visual deliverables under review. If a finding targets the anchor itself (wrong color cited, missing state) — which means the plan was wrong — the correct response is a stage revisit that re-runs the full chain, not a fix-loop dispatch that would invoke `designer` against a baton it doesn't author. Do NOT add `designer-prep` here without first changing the architecture's plan-vs-do split.

package/studios/software/stages/design/discovery/DESIGN-BRIEF.md

@@ -0,0 +1,32 @@
+---
+name: design-brief
+location: .haiku/intents/{intent-slug}/stages/design/DESIGN-BRIEF.md
+scope: intent
+format: design
+required: true
+---
+
+# Design Brief
+
+Screen-by-screen design specifications for the intent's user-facing surfaces. This output is the contract between design and development — what gets built should match what's specified here.
+
+## Content Guide
+
+For each screen or view:
+
+- **Layout structure** — columns, sections, positioning, and spacing
+- **Component inventory** — each component with its location, purpose, and props
+- **Interaction states** — default, hover, focus, active, disabled, error, loading, empty for each interactive element
+- **Responsive behavior** — layout changes at each breakpoint (mobile 375px, tablet 768px, desktop 1280px)
+- **Navigation flows** — how users move between screens, what triggers transitions
+- **Accessibility requirements** — contrast ratios, label associations, keyboard navigation paths, focus management
+
+Include a **design gaps** section documenting known missing states and their disposition (designed, deferred, out of scope).
+
+## Quality Signals
+
+- Every interactive element has all applicable states specified
+- Responsive behavior is described per breakpoint, not just "it's responsive"
+- Colors reference named tokens, never raw hex values
+- Touch targets are at least 44px on mobile
+- Keyboard navigation order is defined for complex interactions