baldart 3.14.1 → 3.15.0

package/framework/.claude/skills/prd/assets/prd-template.md

@@ -44,6 +44,40 @@ Backlog cards to be created after PRD approval.
 |----------|--------|
 | {{doc path}} | {{what to update}} |
 
+## Design Reference & Mockup Inventory
+
+> Omit this entire section only if UI impact is N/A. Otherwise include with
+> `Mockup status: none` when the user did not provide mockups in Step 1.6.
+
+**Mockup status:** {{provided | partial | none | n/a}}
+**Step 3 mode:** {{full | hybrid | skipped}}
+**Design entry point:** {{`docs/prd/<slug>/design.html` | `docs/prd/<slug>/mockups/` | both}}
+
+### Screen inventory
+
+| Schermata | User story | Mockup path | Origine | Note |
+|-----------|------------|-------------|---------|------|
+| {{Lista ordini}} | US-1 | `mockups/lista.png` | mockup utente | tokens align: ✅ |
+| {{Onboarding}} | US-4 | `design.html#onboarding` | generato Step 3b | option scelta: B |
+
+### Mapping schermata → componenti registry
+
+> Populate only when `features.has_design_system: true`. Otherwise remove this
+> subsection.
+
+| Schermata | Componenti riusati | Componenti nuovi | Token violations |
+|-----------|---------------------|------------------|------------------|
+| {{Lista ordini}} | DataTable, Pagination | — | — |
+| {{Dettaglio ordine}} | Card, StatusBadge | OrderTimeline (nuovo — vedi spec) | shadow `0 2px 8px` → `--shadow-card-elevated` |
+
+### Source files originali
+
+Per i mockup forniti come path locali, riportare il percorso utente pre-copia
+(traceability). Per immagini in chat, scrivere `chat://image-N`.
+
+- `{{~/Desktop/orders-mockup.png}}` → `mockups/orders-mockup.png`
+- `chat://image-1` → analizzata inline, non copiata su disco
+
 ---
 
 ## 1. Problem Statement
@@ -99,22 +133,55 @@ Backlog cards to be created after PRD approval.
 
 ## 5. Data Model
 
-{{TypeScript interfaces, Firestore schema changes, validation rules.}}
+{{Type definitions (TypeScript interfaces / Python dataclasses / SQL schema /
+schema validators), persistence-layer schema changes, validation rules.}}
+
+### Database Indexes & Query Optimization
 
-### Firestore Composite Indexes
+> **Stack-specific variant** — populate the variant matching `stack.database`
+> from `baldart.config.yml`. Remove the variants that do not apply. If
+> `stack.database: ""` (unset), the PRD writer SHOULD ask the user which
+> database is in use before completing this section.
 
-Every query that combines `where()` on one field with `orderBy()` on a different field,
-or multiple `where()` on different fields, REQUIRES a composite index. Missing indexes
-cause runtime `FAILED_PRECONDITION` errors (500s in production).
+**Variant A — Firestore** (`stack.database: firestore`)
+
+Every query that combines `where()` on one field with `orderBy()` on a different
+field, or multiple `where()` on different fields, REQUIRES a composite index.
+Missing indexes cause runtime `FAILED_PRECONDITION` errors (500s in production).
 
 | # | Collection | Fields | Order | Query Location | Status |
 |---|-----------|--------|-------|----------------|--------|
 | IDX-1 | `{{collection}}` | `{{field1}}` ASC, `{{field2}}` DESC | {{ASC/DESC}} | `{{file:function}}` | NEW / EXISTS |
 
-**Rules:**
-- Every API endpoint or server action that reads from Firestore with compound queries MUST have its indexes listed here.
-- The `firestore.indexes.json` file MUST be updated in the same commit as the query code.
-- If no compound queries are needed: state "Nessun indice composito richiesto — tutte le query usano un singolo campo."
+Rules: every endpoint that reads with compound queries MUST list its indexes
+here; `firestore.indexes.json` MUST be updated in the same commit; if no
+compound queries: "Nessun indice composito richiesto".
+
+**Variant B — Relational (Postgres / Supabase / MySQL / SQLite)**
+
+| # | Table | Columns | Type | Used by | Migration |
+|---|-------|---------|------|---------|-----------|
+| IDX-1 | `{{table}}` | `{{col1}}, {{col2}}` | B-tree / GIN / partial | `{{query location}}` | `{{migration file}}` |
+
+Rules: indexes ship in the same migration as the query; for Supabase, RLS
+policies live alongside in `### Row-Level Security` below; queries on >100k
+rows without a matching index → CRITICAL finding in api-perf-gate.
+
+**Variant C — MongoDB**
+
+| # | Collection | Fields | Type | Used by | Notes |
+|---|-----------|--------|------|---------|-------|
+| IDX-1 | `{{collection}}` | `{{field1}}: 1, {{field2}}: -1}` | compound / text / 2dsphere | `{{aggregation pipeline}}` | TTL / partial / sparse if applicable |
+
+**Variant D — DynamoDB**
+
+| # | Table | PK / SK | GSI / LSI | Access Pattern | Notes |
+|---|-------|---------|-----------|----------------|-------|
+| GSI-1 | `{{table}}` | `{{pk}} / {{sk}}` | GSI: {{name}} on {{attrs}} | {{query pattern}} | provisioned / on-demand |
+
+**Variant E — None / no DB / N/A**
+
+State explicitly: "Feature is stateless / does not touch the persistence layer".
 
 ---
 
@@ -126,7 +193,12 @@ cause runtime `FAILED_PRECONDITION` errors (500s in production).
 
 ## 7. UI Specifications
 
-{{Layout, components, styling, responsive behavior, a11y.}}
+> Canonical visual reference: **Design Reference & Mockup Inventory** section above.
+> This section describes specs that are NOT obvious from the mockups themselves
+> (behavioral, responsive breakpoints, a11y, motion, copy variants by locale).
+> Do NOT duplicate the screen list or component table — link to them above.
+
+{{Layout details not visible in mockups, responsive behavior, a11y, motion, copy variants.}}
 
 ---
 
@@ -191,10 +263,14 @@ cause runtime `FAILED_PRECONDITION` errors (500s in production).
 
 ### Test Credentials
 
-| Persona | Auth Method | Credentials | Notes |
-|---------|------------|-------------|-------|
-| {{Consumer}} | OTP | phone: 3486417303 | OTP inserito manualmente dall'utente durante il test |
-| {{Merchant}} | password | {{username}} / {{password}} | Store: {{store name}} |
+> Personas drawn from `identity.audience_segments[]`. Credential values come
+> from `.baldart/overlays/prd.md § Test Credentials` (preferred), or were asked
+> to the user during discovery. **Do NOT paste real secrets here** — use
+> references to a secret manager / `.env.test` / 1Password item.
+
+| Persona | Auth Method | Credentials Reference | Notes |
+|---------|-------------|-----------------------|-------|
+| {{audience_segments[0]}} | {{OTP / password / magic link / token}} | {{secret-manager://path or .env.test:VAR}} | {{notes about context, tenant, store, etc.}} |
 
 ### Test Data Prerequisites
 

package/framework/.claude/skills/prd/assets/state-template.md

@@ -67,6 +67,24 @@ Scenarios: pending
 
 ## UI Design
 
+mockups.status: pending           # none | requested | provided | partial
+mockups.format: pending           # chat-images | local-paths | mixed
+mockups.original_paths: []        # user-provided paths or chat://image-N
+mockups.canonical_paths: []       # mockups/<file> after copy
+
+mockup_analysis.screens: []       # see discovery-phase.md § Mockup analysis schema
+mockup_analysis.user_flow: []
+mockup_analysis.design_system_alignment:
+  status: pending                 # aligned | violations | not-applicable
+  violations: []
+
+step_3_mode: pending              # full | hybrid | skipped
+design.html_path: pending         # path | n/a (mockup-only)
+
+screens_in_scope: []              # [{ name, covered_by_mockups: bool, generated_in_step_3b: bool }]
+
+ui_inventory: []                  # populated by Step 3d
+
 ## Confirmed Specs
 
 ## Backlog Cards

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