baldart 3.14.1 → 3.16.0

package/framework/.claude/skills/prd/references/api-perf-gate.md

@@ -14,13 +14,21 @@ flagged after implementation.
 
 **Gates 1-4 run ONLY** when Gate 5 finds matches OR the PRD contains any of:
 - `## API contract changes` section with endpoints
-- `## Data model` section with new Firestore collections/fields
-- Server Actions with Firestore writes
+- `## Data model` section with new {entity}s/{field}s (collections+documents in
+  Firestore/Mongo, tables+rows in SQL, items in DynamoDB)
+- Server-side mutations touching the persistence layer
 - Background jobs, cron, batch operations
 
 If none of the above: log `API Performance Gate: N/A — no API/data surface` in
 state file and skip to "Present and Confirm".
 
+**Stack-awareness:** before running Gates 1-4, read `stack.database` and
+`stack.framework` from `baldart.config.yml`. The gate sections below have a
+universal core (works for any stack) PLUS stack-specific addenda that activate
+only when the matching value is set. When `stack.database: ""` (unset), the
+gate degrades to the universal core and logs a recommendation to run `npx
+baldart configure` so future gates pick up the stack-specific rules.
+
 ---
 
 ## The 5-Gate Protocol
@@ -39,50 +47,80 @@ Scan the PRD text for these keywords. Each match = a finding.
 | "no limit" / "unlimited" / "senza limiti" / "illimitato" | Unbounded data growth | HIGH |
 | "save all in document" / "embed list" / "array nel documento" | Unbounded array in doc (max 1MB, degrades at 40K) | HIGH |
 | "upload file/image via API" / "carica file" | 4.5MB payload limit on Vercel Functions | HIGH |
-| "auto-increment ID" / "sequential ID" / "ID sequenziale" | Firestore hotspot | HIGH |
-| "search by name" / "full-text search" / "cerca per nome" | Firestore cannot do full-text search | HIGH |
-| "page N" / "skip" / "offset" / "pagina N" | Offset pagination (charges for ALL skipped docs) | MEDIUM |
-| "send email/SMS" in request path / "invia email/SMS" | Blocking I/O in request path (use waitUntil) | MEDIUM |
-| "filter by A and B and C" / "filtra per A e B e C" | Composite index explosion | MEDIUM |
-| "import CSV" / "bulk insert" / "importa CSV" | Batch 500-doc limit per write | MEDIUM |
+| "search by name" / "full-text search" / "cerca per nome" | Many DBs need a dedicated search index (Algolia/Typesense/Postgres FTS/Mongo Atlas Search) — DB-specific | HIGH |
+| "page N" / "skip" / "offset" / "pagina N" | Offset pagination is inefficient in most DBs (Firestore charges for skipped docs; SQL scans them) | MEDIUM |
+| "send email/SMS" in request path / "invia email/SMS" | Blocking I/O in request path (use waitUntil / background job) | MEDIUM |
+| "filter by A and B and C" / "filtra per A e B e C" | Composite index explosion (Firestore: explicit indexes; SQL: pick a covering index; Mongo: compound index) | MEDIUM |
+
+**Stack-specific keyword addenda** (apply only when matching `stack.database`):
+
+| Stack | Keyword | Problem | Severity |
+|-------|---------|---------|----------|
+| firestore | "auto-increment ID" / "sequential ID" / "ID sequenziale" | Firestore write hotspot (sequential keys serialize on a single tablet) | HIGH |
+| firestore | "import CSV" / "bulk insert" / "importa CSV" | Firestore batch limit: 500 docs/write | MEDIUM |
+| firestore / mongodb | "save all in document" / "embed list" / "array nel documento" | Unbounded array in doc (Firestore max 1MB, degrades >40K elements; Mongo 16MB doc cap) | HIGH |
+| postgres / supabase | "SELECT \\*" on hot path | Avoid; specify columns to keep index-only scans viable | MEDIUM |
+| postgres / supabase | "JSONB column" + indexed query | Verify GIN index exists | MEDIUM |
+| dynamodb | "filter expression" instead of KeyCondition | Filter scans full partition — pick a GSI instead | HIGH |
 
 **If 0 matches AND no API/data sections**: skip Gates 1-4, proceed to present.
 **If any match**: continue to Gates 1-4.
 
 ### Gate 1 — Data Model Review
 
-Check the PRD `## Data model` section for:
+Universal checks (apply to any persistence layer):
 
-- [ ] **Unbounded arrays**: any array field that can grow without limit → CRITICAL
-- [ ] **Document size**: will any document exceed ~100KB regularly? → HIGH
-- [ ] **Sequential/predictable IDs**: custom IDs based on timestamp or counter → HIGH (Firestore hotspot, use auto-ID)
-- [ ] **Fan-out writes**: one user action writing to N documents where N scales with users/data → HIGH
-- [ ] **Global counters**: fields incremented by many concurrent writers → HIGH (transaction serialization)
-- [ ] **Real-time listeners**: justified? Can polling or ISR replace them? → HIGH (1 read/matched doc at attach)
+- [ ] **Unbounded arrays/lists**: any array field/JSONB column/list-typed attribute that can grow without limit → CRITICAL
+- [ ] **Row/document size**: will any row exceed a healthy size (Firestore ~100KB, Mongo 16MB, Postgres tuple alignment) regularly? → HIGH
+- [ ] **Fan-out writes**: one user action writing to N rows/docs where N scales with users/data → HIGH
+- [ ] **Global counters**: columns/fields incremented by many concurrent writers → HIGH (write-skew, contention, or transaction serialization depending on stack)
 - [ ] **Denormalization strategy**: read-heavy paths should denormalize; write-heavy should normalize → MEDIUM
-- [ ] **Index exemptions**: large text/description fields should exempt from indexing → MEDIUM (N+1 index writes per doc write)
+
+Stack-specific addenda (activate when matching `stack.database`):
+
+- [ ] firestore: **Sequential/predictable IDs** (timestamp/counter) → HIGH (write hotspot, use auto-ID)
+- [ ] firestore: **Real-time listeners** — justified? Can polling or ISR replace them? → HIGH (1 read/matched doc at attach + 1 per change)
+- [ ] firestore: **Index exemptions** for large text fields → MEDIUM (N+1 index writes per doc write)
+- [ ] mongodb: **Embedded vs referenced** — embedded grows the parent doc; referenced needs $lookup → MEDIUM
+- [ ] postgres/supabase: **JSONB vs typed columns** — JSONB without GIN index = full scan → MEDIUM
+- [ ] supabase: **RLS coverage** — every new table MUST have RLS policies aligned with the auth contract → CRITICAL
+- [ ] dynamodb: **Hot partition** — does the partition key distribute evenly under load? → HIGH
 
 ### Gate 2 — Query & Index Review
 
-Check the PRD `## API contract changes` and data access patterns for:
+Universal checks:
+
+- [ ] **Pagination on all list endpoints**: every endpoint returning multiple rows/docs MUST specify cursor-based pagination (keyset / `startAfter` / `cursor`), never raw offset → CRITICAL
+- [ ] **N+1 queries**: "get parent, then for each child get details" pattern → CRITICAL (use a single query with join / `collectionGroup` / `$lookup` / denormalize depending on stack)
+- [ ] **Index table completeness**: if the PRD has read endpoints touching the persistence layer but Section 5 has no `### Database Indexes & Query Optimization` table (or says "nessun indice"), verify this is actually correct by checking each query pattern. Missing the table when compound queries exist → **CRITICAL**
+
+Stack-specific addenda:
 
-- [ ] **Pagination on all list endpoints**: every endpoint returning multiple docs MUST specify cursor-based pagination (startAfter), never offset → CRITICAL
-- [ ] **N+1 queries**: "get parent, then for each child get details" pattern → CRITICAL (use collectionGroup or denormalize)
-- [ ] **Composite index specification**: every query combining `where()` + `orderBy()` on different fields, or multiple `where()` on different fields, MUST have an explicit entry in the PRD's `### Firestore Composite Indexes` table (Section 5). Missing index = runtime FAILED_PRECONDITION (500 in production) → **CRITICAL**
-- [ ] **Composite index count**: >3 inequality filters on different fields = index explosion → MEDIUM
-- [ ] **orderBy + inequality on different fields**: requires composite index, max 1 inequality per query. Verify the PRD index table includes the correct field order (the inequality field MUST be last in the index definition) → **HIGH**
-- [ ] **Full-text search**: Firestore doesn't support it natively; require Algolia/Typesense or array-contains workaround → HIGH
-- [ ] **Index table completeness**: if the PRD has API endpoints that read from Firestore but Section 5 has no `### Firestore Composite Indexes` table (or says "nessun indice"), verify this is actually correct by checking each query pattern. Missing the table when compound queries exist → **CRITICAL**
+- [ ] firestore: **Composite index** for every query combining `where()` + `orderBy()` on different fields or multiple `where()` on different fields MUST appear in the PRD index table (Variant A). Missing index = runtime FAILED_PRECONDITION → **CRITICAL**
+- [ ] firestore: **orderBy + inequality on different fields** requires composite index, max 1 inequality per query (inequality field MUST be last) → HIGH
+- [ ] firestore: **>3 inequality filters on different fields** = index explosion → MEDIUM
+- [ ] firestore: **Full-text search** — not native, needs Algolia/Typesense or array-contains workaround → HIGH
+- [ ] postgres/supabase: **EXPLAIN check** on the slowest query in the PRD — sequential scans on >100k rows → CRITICAL
+- [ ] postgres/supabase: **Covering index** for hot read paths → MEDIUM
+- [ ] mongodb: **Compound index field order** matches query equality → range → sort rule → HIGH
+- [ ] dynamodb: **GSI / LSI definition** for every access pattern that doesn't hit the primary key → CRITICAL
 
-### Gate 3 — Serverless Architecture Review
+### Gate 3 — Serverless / Runtime Architecture Review
 
-Check endpoint design and background processing for:
+Universal checks:
 
-- [ ] **Payload size**: any endpoint accepting/returning >4.5MB → CRITICAL (use signed URL pattern for uploads)
-- [ ] **Sync vs async**: long operations (email, PDF, image processing) in request path → HIGH (use waitUntil or background job)
-- [ ] **Function duration**: operations that may exceed 300s → HIGH (split into steps or use queue)
-- [ ] **CPU-intensive ops**: image resize, PDF gen, heavy computation in serverless → MEDIUM (consider dedicated worker)
-- [ ] **GET Route Handler caching**: new GET endpoints MUST specify `revalidate` or `use cache` — dynamic by default since Next.js 15 → HIGH
+- [ ] **Payload size**: any endpoint accepting/returning >4.5MB → CRITICAL (use signed URL / multipart upload pattern). Limit varies by deployment (Vercel 4.5MB, Cloudflare Workers 100MB, AWS Lambda 6MB sync) — calibrate to `stack.deployment`.
+- [ ] **Sync vs async**: long operations (email, PDF, image processing) in request path → HIGH (use queue / waitUntil / background worker per stack)
+- [ ] **Function duration**: operations that may exceed the platform timeout (Vercel 300s Hobby / 800s Pro; Lambda 900s; Cloudflare Workers 30s CPU) → HIGH
+- [ ] **CPU-intensive ops**: image resize, PDF gen, heavy computation in serverless → MEDIUM (consider dedicated worker / container)
+
+Stack-specific addenda (`stack.framework`):
+
+- [ ] nextjs: **GET Route Handler caching** — new GET endpoints MUST specify `revalidate` or `use cache` — dynamic by default since Next.js 15 → HIGH
+- [ ] nextjs: **Server Action vs Route Handler** chosen explicitly per use case → MEDIUM
+- [ ] remix: **`loader`/`action` separation** + `headers` for `Cache-Control` set explicitly → MEDIUM
+- [ ] sveltekit: **`+page.server.ts` vs `+page.ts`** chosen explicitly; Edge vs Node runtime declared → MEDIUM
+- [ ] astro: **`output: 'static'|'server'|'hybrid'`** declared per route group; `prerender` flag set for static routes → MEDIUM
 
 ### Gate 4 — Caching Strategy Review
 
@@ -123,30 +161,42 @@ Check data display and freshness requirements for:
 
 ## Reference Data
 
-### Firestore Pricing (Blaze Plan)
-- Reads: $0.06 / 100K
-- Writes: $0.18 / 100K
-- Deletes: $0.02 / 100K
-- Offset pagination charges for ALL skipped docs
-- Index writes: N+1 per document (1 doc + N indexed fields)
-- Listener: 1 read/matched doc at attach + 1 per change
-
-### Vercel Fluid Compute
-- Payload limit: 4.5 MB request/response
-- Active CPU pricing: pauses during I/O
-- Max duration: 300s (Hobby) / 800s (Pro)
-- File descriptor limit: 1,024 shared
-- Cold start: archived after 2 weeks (prod) / 48h (preview)
-
-### Next.js App Router
-- GET Route Handlers: DYNAMIC by default since v15 (must opt-in to caching)
-- `use cache` in serverless: in-memory LRU, not persisted across cold starts
-- `React.cache()`: single-request dedup only
-- Sequential `await` = waterfall; use `Promise.all()` for independent fetches
+Cite ONLY the section matching the project's `stack.database` /
+`stack.framework` / `stack.deployment`. Sections for other stacks are
+informational and should be removed from the populated PRD section.
+
+### Database pricing & cost-model snapshots
+
+**Firestore (Blaze Plan):** Reads $0.06/100K, Writes $0.18/100K, Deletes $0.02/100K. Offset pagination charges for ALL skipped docs. Index writes: N+1 per document. Listener: 1 read/matched doc at attach + 1 per change.
+
+**Supabase / Postgres:** Compute + storage + egress billing. Hot row updates serialize on a single page; HOT updates and `FILLFACTOR` matter for write-heavy tables. Sequential scan >100k rows is a HIGH finding regardless of price.
+
+**MongoDB Atlas:** Cluster tier dictates IOPS ceiling. Aggregation `$lookup` cost ≈ N queries when uncached. WiredTiger cache hit rate <90% on hot path = HIGH finding.
+
+**DynamoDB:** On-demand vs provisioned billing model dictates RCU/WCU sizing. Hot partition (skewed PK distribution) triggers throttle errors before billing impact shows.
+
+### Runtime limits (by `stack.deployment`)
+
+| Platform | Payload | Duration | Notes |
+|----------|---------|----------|-------|
+| Vercel (Fluid Compute) | 4.5 MB | 300s Hobby / 800s Pro | Active CPU pricing, FD limit 1024 shared, archived after 2w prod / 48h preview |
+| Cloudflare Workers | 100 MB | 30s CPU | No FD pool, smaller heap |
+| AWS Lambda | 6 MB sync / 256 KB async | 900s | Cold start ~100-500ms; provisioned concurrency to mitigate |
+| Firebase Functions (gen 2) | 32 MB | 540s 2nd-gen | Cold start ~200-2000ms |
+
+### Framework caching primitives (by `stack.framework`)
+
+**Next.js App Router:** GET Route Handlers DYNAMIC by default since v15 (opt-in to caching via `revalidate` / `'use cache'`). `'use cache'` in serverless: in-memory LRU, not persisted across cold starts. `React.cache()`: single-request dedup only. Sequential `await` = waterfall; use `Promise.all()` for independent fetches.
+
+**Remix:** `headers` function sets `Cache-Control`; `loader` revalidation via `shouldRevalidate`. No built-in cache layer — relies on CDN.
+
+**SvelteKit:** `setHeaders({'cache-control': ...})` in `load`; `prerender = true` for static; Edge vs Node runtime per route.
+
+**Astro:** SSG by default; `output: 'server'` enables on-demand rendering; per-route `prerender` toggle.
 
 ### When to Skip
 
 - Hotfix cards (single-line bug fixes): Gate 5 only
-- Purely frontend cards (no API/Firestore): skip entirely
+- Purely frontend cards (no persistence/API touch): skip entirely
 - Documentation-only: skip entirely
 - Prototype/spike (throw-away): skip entirely

package/framework/.claude/skills/prd/references/audit-phase.md

@@ -24,11 +24,11 @@ Scan each card for security signals to decide whether the `security-reviewer` ag
 |--------|---------------|
 | **New or modified API route** | `files_likely_touched` contains `route.ts`, `api/`, or requirements mention new endpoints |
 | **Authentication/authorization changes** | Requirements/files mention `withAuth`, `checkPermission`, `permissions`, login, session, token, JWT, OAuth |
-| **Firestore security rules** | `files_likely_touched` contains `firestore.rules` or requirements mention rule changes |
+| **Persistence-layer access rules** | `files_likely_touched` contains rule/policy files matching `stack.database` (e.g. `firestore.rules`, Supabase RLS migration, MongoDB validator) or requirements mention rule changes |
 | **External integrations** | Requirements mention webhooks, third-party APIs, payment, SMS, email providers, or external callbacks |
 | **File upload or media handling** | Requirements mention upload, image, file, media, or `files_likely_touched` contains upload/media paths |
 | **User input processing** | Requirements mention forms, search, filters, or query parameters that flow into DB queries or server logic |
-| **Multi-tenant data access** | Requirements mention cross-store, cross-merchant, or data visible to multiple tenants |
+| **Multi-tenant data access** | Requirements mention cross-tenant boundaries (cross-org, cross-workspace, cross-store, cross-account — actual tenant noun from `identity.audience_segments[]`) or data visible to multiple tenants |
 | **Sensitive data handling** | Requirements mention PII, credentials, tokens, secrets, or personal data |
 
 **How to assess**: Read each card's `requirements`, `acceptance_criteria`, `files_likely_touched`, `areas`, `existing_patterns`, `anti_patterns`, `validation_commands`, `error_handling`, and `scope_boundaries` fields. This is a deterministic check — no LLM judgment calls needed.
@@ -48,7 +48,7 @@ Scan each card for performance signals to decide whether the `api-perf-cost-audi
 | Signal | Where to look |
 |--------|---------------|
 | **New or modified API route** | `files_likely_touched` contains `route.ts`, `api/`, or requirements mention new endpoints |
-| **Firestore read/write operations** | Requirements mention collection, query, document, write, transaction, batch, listener, onSnapshot |
+| **Persistence-layer read/write operations** | Requirements mention {entity} read/write, query, transaction, batch, listener/subscription/change-stream (terminology depends on `stack.database`) |
 | **List/search/filter endpoints** | Requirements mention listing, searching, filtering, sorting, pagination, or "show all" |
 | **Background/batch processing** | Requirements mention cron, batch, import, export, bulk, queue, or scheduled tasks |
 | **Real-time/live updates** | Requirements mention real-time, live, auto-update, listener, onSnapshot, subscription |
@@ -172,12 +172,12 @@ Requirements smell detection:
 - Compound requirements covering multiple behaviors
 - Dependency shadows: implicit deps not in depends_on
 
-Firestore-specific (this project uses Firestore):
-- Unbounded reads without .limit()
-- Offset-based pagination instead of cursor-based
-- getDoc() in loops instead of batch reads
-- Missing composite index declarations
-- Transaction hotspot risks
+Database-specific (apply the subset matching `stack.database`):
+- Universal: unbounded reads without limit, offset-based pagination instead of cursor/keyset, N+1 read in loops, transaction/concurrency hotspot risks
+- firestore: missing composite index declarations, sequential-ID hotspots, listener attach cost not budgeted
+- postgres/supabase: sequential scan on >100k rows, RLS policy missing on new table, JSONB without GIN index
+- mongodb: missing compound index for hot aggregation, embedded array unbounded growth
+- dynamodb: missing GSI for non-PK access pattern, hot-partition risk
 
 Card structure:
 - files_likely_touched missing entries or conflicting across cards
@@ -339,8 +339,8 @@ After challenge pass, rank ALL surviving findings relative to each other by impa
 ### Severity Calibration Examples
 
 **HIGH** (must fix before implementation):
-- "acceptance_criteria says 'user can see bookings' but doesn't specify pagination → unbounded Firestore read"
-  > Evidence: "AC-2: Il merchant visualizza le prenotazioni" — no limit/pagination mentioned
+- "acceptance_criteria says 'user can see <list>' but doesn't specify pagination → unbounded persistence-layer read"
+  > Evidence: "AC-2: <persona from identity.audience_segments[]> views <entity>" — no limit/pagination mentioned
 
 **MEDIUM** (should fix, skip if ambiguous):
 - "files_likely_touched missing the API route doc update"
@@ -359,9 +359,9 @@ After challenge pass, rank ALL surviving findings relative to each other by impa
 
 **doc-reviewer**: Check documentation links, PRD references are valid and aligned, planned changes requiring doc updates not mentioned. Verify `files_likely_touched` includes doc files. Check `areas` completeness. Flag `git_strategy: TBD`. Include Obsidian trigger assessment (section H) in findings -- evaluate whether the planned docs will require KB sync per `.claude/skills/doc-reviewer-support/references/obsidian-integration.md`.
 
-**api-perf-cost-auditor** (only when `perf_review_needed: true`): Apply the 5-gate protocol from `.claude/agent-memory/senior-researcher/api-perf-cost-audit-protocol.md`. Read referenced source files. Check: unbounded reads, N+1 queries, fan-out writes, missing pagination, offset pagination, missing GET Route Handler caching, listener vs polling costs, 4.5MB payload limits, transaction hotspots.
+**api-perf-cost-auditor** (only when `perf_review_needed: true`): Apply the 5-gate protocol from `.claude/agent-memory/senior-researcher/api-perf-cost-audit-protocol.md`. Read referenced source files. Universal checks: unbounded reads, N+1 queries, fan-out writes, missing pagination, offset pagination, listener vs polling costs, payload size limits per `stack.deployment`, transaction hotspots. Stack-specific addenda apply per `stack.database` + `stack.framework` (see `framework/.claude/skills/prd/references/api-perf-gate.md`).
 
-**security-reviewer** (only when `security_review_needed: true`): Read `.claude/agents/security-reviewer.md` for full methodology. Focus on: auth gaps, input validation, multi-tenant isolation, Firestore rules alignment, sensitive data exposure, webhook validation, rate limiting, IDOR risks.
+**security-reviewer** (only when `security_review_needed: true`): Read `.claude/agents/security-reviewer.md` for full methodology. Focus on: auth gaps, input validation, multi-tenant isolation, persistence-layer access rules alignment (Firestore rules / Supabase RLS / Mongo validator / DynamoDB IAM — per `stack.database`), sensitive data exposure, webhook validation, rate limiting, IDOR risks.
 
 ## Step 6.7 — Collect & Merge Findings
 

package/framework/.claude/skills/prd/references/backlog-phase.md

@@ -4,6 +4,87 @@
 
 Mark task 4 as `in_progress`.
 
+## MANDATORY Card Rules (zero tolerance — read first)
+
+These two rules apply to EVERY child card (epics use `owner_agent: ""`). The
+`prd-card-writer` agent enforces them; the skill MUST verify post-generation
+and HALT if violated.
+
+### Rule A — `owner_agent` is mandatory and enum-validated
+
+Every child card MUST declare `owner_agent` with one of the five values:
+
+```
+coder | ui-expert | plan | visual-designer | motion-expert
+```
+
+There is no implicit default and `claude` is NOT a valid value. Cards with
+missing, empty, placeholder, or non-enum values fail Step 6 (validation-phase)
+and BLOCK the commit. The `/new` orchestrator dispatches implementation
+agent by this field (see `framework/.claude/skills/new/SKILL.md` § Agent
+Routing), so a wrong value silently routes the card to the wrong specialist.
+
+### Rule B — UI cards have UI-only scope (no mixed scope)
+
+A card with `owner_agent: ui-expert` MUST be scoped EXCLUSIVELY to graphical
+concerns: components, layout, styling, token usage, motion, accessibility.
+It MUST NOT bundle:
+
+- business logic / domain rules
+- API integration or data fetching
+- state management beyond local UI state
+- form validation logic (rendering validation states is UI; the rules are not)
+- backend changes (routes, handlers, DB schema)
+
+If a feature step involves BOTH UI and logic, the writer MUST split it into:
+
+- one `owner_agent: ui-expert` card — visual implementation, consumes mocked
+  or contract-stable data
+- one `owner_agent: coder` card — logic, API call, state, persistence
+
+The two cards are wired via `depends_on:` / `blocks:`. A common ordering is
+`coder → ui-expert` (contract ready before UI), but the reverse is acceptable
+when the UI card consumes a hand-written mock.
+
+#### Split example — Login feature
+
+**Bad** (single mixed card):
+
+```yaml
+id: FEAT-XXXX-01
+owner_agent: coder
+scope:
+  summary: |
+    Implement the login page: form layout, validation states, call to
+    POST /api/auth/login, token storage, redirect to dashboard.
+```
+
+**Good** (split into UI + logic):
+
+```yaml
+# UI card — visual only, consumes a mocked auth contract
+id: FEAT-XXXX-02
+owner_agent: ui-expert
+depends_on: [FEAT-XXXX-01]
+scope:
+  summary: |
+    Login form layout (email/password fields, primary CTA, link to recovery),
+    visual states (idle / loading / error / success), a11y (focus order,
+    aria-live for inline errors), responsive breakpoints. Consumes the
+    `useAuth()` mock provided by FEAT-XXXX-01.
+```
+
+```yaml
+# Logic card — API call + state + redirect
+id: FEAT-XXXX-01
+owner_agent: coder
+blocks: [FEAT-XXXX-02]
+scope:
+  summary: |
+    POST /api/auth/login handler, token storage in httpOnly cookie, redirect
+    on success, `useAuth()` hook exposing { status, error, signIn }.
+```
+
 ## MANDATORY Card Structure (zero tolerance — read first)
 
 Every PRD generates **1 epic card + N children**, regardless of N. The