baldart 3.14.0 → 3.15.0

package/framework/.claude/skills/new/SKILL.md

@@ -108,7 +108,7 @@ Main repo: [/absolute/path/to/main/repo]
 
 1c. **Field Registry Validation (pre-flight gate)** — for each card with a `data_fields` block, run the project's field-validation tool if available (path listed in `.baldart/overlays/new.md`; typically `python3 tools/validate-card-fields.py <card-yaml-path>`).
    - If exit 1: display the field errors in `## Issues & Flags` and HALT — ask the user to fix the card before proceeding. Do not start implementation until the card passes validation.
-   - If the card has DB-index signals (e.g. `firestore_indexes`, `data.collections`) but NO `data_fields` block: log WARNING in `## Issues & Flags` — "Card `<ID>` touches storage but has no `data_fields` block. Field names are unvalidated."
+   - If the card has DB-index signals (`db_indexes` — or legacy `firestore_indexes` — or `data.collections`/`data.tables`) but NO `data_fields` block: log WARNING in `## Issues & Flags` — "Card `<ID>` touches the persistence layer but has no `data_fields` block. Field/column names are unvalidated."
    - Cards with no `data_fields` and no storage signals: skip silently.
    - If the project does not ship a field-validation tool: skip this step.
 2. Check `${paths.references_dir}/project-status.md` for current state (skip when absent).
@@ -173,8 +173,9 @@ Main repo: [/absolute/path/to/main/repo]
       requirements assume stays unchanged? Flag missing depends_on.
    3. EXECUTION ORDER RISKS: Given the parallel_group assignments, will parallel
       execution cause merge conflicts or type errors?
-   4. SHARED STATE MUTATIONS: Do multiple cards write to the same Firestore
-      collection/document in ways that could conflict at runtime?
+   4. SHARED STATE MUTATIONS: Do multiple cards write to the same persistence
+      {entity} ({collection|table|item} per `stack.database`) in ways that could
+      conflict at runtime?
 
    For each finding return:
    - **Cards involved**: CARD-A + CARD-B
@@ -218,7 +219,7 @@ Before Phase 3.5, determine the QA profile for each card by reading its YAML met
 | **SKIP** | Card type is `docs`, `chore`, or `config` — OR all changed paths are `.md`/`.yml` (non-API)/CSS with zero logic files — OR title contains only cosmetic keywords (typo, rename, copy, wording, style) with no code areas |
 | **LIGHT** | Card type is `bugfix` OR `refactor` — AND ≤3 files likely touched — AND no HIGH-risk keywords in paths/areas/title. **NEVER applies to `feature` or `enhancement` cards.** |
 | **BALANCED** | Default for ALL `feature` / `enhancement` cards not matching DEEP rules — OR `bugfix`/`refactor` with >3 files or HIGH-risk keywords |
-| **DEEP** | ANY of: areas includes both `api` + `data` — OR paths/title contain `auth`, `payment`, `permission`, `schema`, `migration`, `cron`, `webhook`, `transaction` — OR >15 files likely touched — OR acceptance criteria count > 5 — OR Firestore indexes changed — OR API contract changed — OR `data_fields` block has ≥3 entries with `status: new` or `status: modified` |
+| **DEEP** | ANY of: areas includes both `api` + `data` — OR paths/title contain `auth`, `payment`, `permission`, `schema`, `migration`, `cron`, `webhook`, `transaction` — OR >15 files likely touched — OR acceptance criteria count > 5 — OR DB indexes changed (`db_indexes` block present, or legacy `firestore_indexes`) — OR API contract changed — OR `data_fields` block has ≥3 entries with `status: new` or `status: modified` |
 
 **Critical**: `feature` and `enhancement` cards are ALWAYS BALANCED minimum — never LIGHT. The `files_likely_touched` field in YAML underestimates actual scope; ignore it for profile decisions on feature cards. When in doubt between BALANCED and DEEP, use DEEP.
 
@@ -306,29 +307,46 @@ For each card, execute these phases in order:
    - Do NOT add unrequested features or extra error handling beyond what's specified
    - Do NOT modify test files unless the card explicitly requires it
 
-   ### Firestore Composite Indexes (if card has `firestore_indexes` field)
-   This card requires the following composite indexes in `firestore.indexes.json`.
-   You MUST add these in the SAME commit as the query code. Missing indexes cause
-   runtime FAILED_PRECONDITION errors (500 in production).
-
-   [paste firestore_indexes entries from card YAML, formatted as:]
-   | Collection | Fields | Query Location | PRD Ref |
-   |-----------|--------|----------------|---------|
-   | [collection] | [field1 ASC, field2 DESC] | [file path] | [IDX-N] |
-
-   For each index, add the corresponding entry to `firestore.indexes.json` under
-   `indexes[]` with this format:
-   ```json
-   {
-     "collectionGroup": "<collection>",
-     "queryScope": "COLLECTION",
-     "fields": [
-       { "fieldPath": "<field1>", "order": "ASCENDING" },
-       { "fieldPath": "<field2>", "order": "DESCENDING" }
-     ]
-   }
-   ```
-   Include `firestore.indexes.json` in your staged files.
+   ### Database Indexes (if card has `db_indexes` — or legacy `firestore_indexes` — field)
+   This card requires the following indexes shipped in the SAME commit as the query
+   code. Missing indexes degrade performance or break production (variant per
+   `stack.database` — see `framework/.claude/agents/coder.md § Database Index Invariant`).
+
+   [paste db_indexes entries from card YAML, formatted as:]
+   | Entity | Dialect | Fields | Kind | Query Location | PRD Ref |
+   |--------|---------|--------|------|----------------|---------|
+   | [entity] | [stack.database] | [field1 ASC, field2 DESC] | [composite/covering/GIN/GSI] | [file path] | [IDX-N] |
+
+   **Where to ship the index — pick the artifact matching `stack.database`:**
+
+   - `firestore` → append to `firestore.indexes.json` under `indexes[]`:
+     ```json
+     {
+       "collectionGroup": "<entity>",
+       "queryScope": "COLLECTION",
+       "fields": [
+         { "fieldPath": "<field1>", "order": "ASCENDING" },
+         { "fieldPath": "<field2>", "order": "DESCENDING" }
+       ]
+     }
+     ```
+     Stage `firestore.indexes.json` together with the query code.
+   - `postgres` / `supabase` / `mysql` / `sqlite` → add a migration file under the
+     project's migrations dir (`migrations/`, `db/migrate/`, `supabase/migrations/`,
+     `prisma/migrations/` per project convention) with `CREATE INDEX ...` or the
+     Prisma `@@index([...])` directive. For Supabase, RLS policies live in the same
+     migration when relevant.
+   - `mongodb` → add `db.<entity>.createIndex(...)` to the project's index-bootstrap
+     script (path declared in `.baldart/overlays/new.md § Schema Bootstrap`), or run
+     it as part of the migration command.
+   - `dynamodb` → update the table definition in the project's IaC (CDK / Terraform /
+     SAM / SST) with the matching GSI/LSI.
+   - Stack `none` or unset → if you still see `db_indexes` on the card, ask the user
+     to confirm the persistence target before staging anything.
+
+   Stage the index artifact alongside the query code in the SAME commit. Verification
+   (post-deploy index propagation) is handled in the Production Readiness Checklist
+   section below, branched by `stack.deployment`.
 
    ### Expected Output Locations
    [pre-fill from codebase-architect: for each requirement, the file:line where the change should go]
@@ -506,11 +524,23 @@ Before triggering any review, you MUST verify that the coder agent implemented *
        AND read (getter/reader path) in the changed files.
      - For each `status: modified` field: verify old-name references are removed and
        new-name references exist.
-   - **Firestore compound query** → verify: if the card has a `firestore_indexes` field,
-     check that EVERY listed index exists in `firestore.indexes.json` (match collection +
-     fields + order). Also grep the query code to confirm `where()` + `orderBy()` field
-     names match the index definition exactly. Missing or mismatched index = CRITICAL gap
-     (causes runtime 500 FAILED_PRECONDITION).
+   - **DB compound query** → verify: if the card has a `db_indexes` (or legacy
+     `firestore_indexes`) field, check that EVERY listed index has been shipped to
+     the artifact matching `stack.database`:
+     - `firestore` → entries exist in `firestore.indexes.json` (match collection +
+       fields + order); also grep the query code to confirm `where()` + `orderBy()`
+       field names match the index definition exactly. Missing index = CRITICAL
+       (runtime 500 FAILED_PRECONDITION).
+     - `postgres`/`supabase`/`mysql`/`sqlite` → a migration file exists declaring
+       the index (or `prisma/schema.prisma` `@@index([...])`); grep the query to
+       confirm the column names match. Missing migration = CRITICAL (silent
+       Seq Scan in production on hot path).
+     - `mongodb` → `createIndex` call exists in the bootstrap script (or migration);
+       compound field order in the call matches equality → range → sort in the query.
+       Missing = HIGH (no immediate error, but slow aggregation under load).
+     - `dynamodb` → the GSI/LSI is declared in the IaC table definition AND the
+       query uses the GSI name via `IndexName`. Missing = CRITICAL (throttle on
+       hot partition).
 
    If the completion report has `items_skipped` that is not "none", immediately flag those
    items as Missing regardless of the agent's justification.
@@ -695,7 +725,7 @@ If all met, ask the user: `Vuoi testarlo con Playwright E2E? (si/no)`
      fields, then submit the login form. No manual intervention needed.
 
    ## Test Data Prerequisites
-   [paste test_data_prerequisites — data that must exist in Firestore]
+   [paste test_data_prerequisites — data that must exist in the persistence layer before the test runs]
 
    ## Guidelines
    - Use page.getByRole(), page.getByText(), page.getByTestId() for selectors
@@ -752,8 +782,8 @@ Non-blocking — findings are logged but do NOT block commit.
     ### Invariant checklist (Linking Protocol — docs/guides/linking-protocol-rollout-v1.md):
     - [ ] New route.ts added? → ${paths.references_dir}/api/<module>.md + api/index.md count
     - [ ] New page.tsx added? → ${paths.references_dir}/ui/<domain>.md + ui/index.md Route Summary
-    - [ ] New Firestore collection? → ${paths.references_dir}/data-model.md + collections/<domain>.md
-    - [ ] Compound Firestore query (where+orderBy on different fields)? → firestore.indexes.json must include the composite index and be staged
+    - [ ] New persistence-layer {entity} ({collection|table|item} per `stack.database`)? → ${paths.references_dir}/data-model.md + the entity's reference doc per project convention (`collections/<domain>.md`, `tables/<domain>.md`, etc.)
+    - [ ] Compound query needing a multi-attribute index? → the matching index artifact MUST be staged in the same commit, per `stack.database`: `firestore.indexes.json` (firestore), migration file or Prisma `@@index` (SQL), `createIndex` script (mongo), GSI/LSI in IaC (dynamodb)
     - [ ] Backlog card set to DONE? → ${paths.references_dir}/ssot-registry.md entry
     - [ ] New external dependency? → agents/architecture.md External Dependencies list
     - [ ] Card has `documentation_impact` field? → verify each listed doc is updated
@@ -1260,43 +1290,57 @@ After Phase 6 completes (or after the final summary report if Phase 6 is deferre
 
 ### How to detect items
 
-Scan ALL files changed across the batch (use the tracker's completed cards + `git diff` against the base branch) and check for:
-
-| Category | Detection signal | Action to report |
-|----------|-----------------|------------------|
-| **Firestore indexes** | New/modified `.firestore.indexes.json`, or code using new compound queries with `orderBy`/`where` on multiple fields | `firebase deploy --only firestore:indexes` |
-| **Firestore security rules** | New/modified `firestore.rules` | `firebase deploy --only firestore:rules` |
-| **Storage security rules** | New/modified `storage.rules` | `firebase deploy --only storage:rules` |
-| **Environment variables** | New `process.env.*` references not present in the base branch, new entries in `.env.example` or `.env.local` | 1. Add to Vercel project settings (list each var name + environments) 2. Update `${paths.references_dir}/env-vars.md` Change Log |
-| **Firebase Remote Config** | New `remoteConfig` keys in code | Add keys in Firebase Console > Remote Config |
-| **Firebase Auth providers** | New auth provider configuration | Enable provider in Firebase Console > Authentication |
-| **Scheduled functions / cron** | New or modified cron/scheduled Cloud Functions | Deploy functions: `firebase deploy --only functions` |
-| **Database migrations** | New collections, field renames, data backfills referenced in code or ADRs | Run migration script (specify which) |
-| **New API endpoints** | New route files under `src/app/api/` | Verify CORS/auth config; update API docs if public |
-| **Third-party services** | New API keys, webhook URLs, or external service integrations | Configure in provider dashboard + add secrets to Vercel |
-| **DNS / domain changes** | Hosting or redirect config changes | Update DNS records or Vercel domain settings |
-| **Package upgrades with breaking changes** | Major version bumps in `package.json` | Verify compatibility; check migration guides |
+Scan ALL files changed across the batch (use the tracker's completed cards + `git diff` against the base branch) and check for the items below.
+
+**The "Action to report" column shows the command for the deployment target
+matching `stack.deployment` in `baldart.config.yml`.** When `stack.deployment`
+is empty, infer from `stack.database` + presence of config files
+(`vercel.json`, `firebase.json`, `wrangler.toml`, `fly.toml`) and fall back to
+asking the user.
+
+| Category | Detection signal | Action to report (per `stack.deployment`) |
+|----------|-----------------|-------------------------------------------|
+| **Database indexes** | New/modified index config file (`firestore.indexes.json`, SQL migration with `CREATE INDEX`, `prisma migrate` artifact, `db.createIndex` call, CDK/Terraform GSI) | firebase: `firebase deploy --only firestore:indexes`; vercel+postgres: run migrations during deploy; aws+dynamodb: apply CDK/Terraform; generic: run the project's migration command |
+| **Persistence-layer access rules** | New/modified `firestore.rules`, Supabase RLS migration, Mongo validator, DynamoDB IAM policy | firebase: `firebase deploy --only firestore:rules`; supabase: `supabase db push`; aws+dynamodb: apply IAM via CDK/Terraform |
+| **Storage access rules** | New/modified `storage.rules` or equivalent bucket policy | firebase: `firebase deploy --only storage:rules`; aws: apply S3 bucket policy; gcp: apply GCS IAM |
+| **Environment variables** | New `process.env.*` references not in the base branch, new entries in `.env.example` or `.env.local` | 1. Add to the deployment platform (Vercel/Firebase/Cloudflare/AWS Param Store) — list each var + target environments 2. Update `${paths.references_dir}/env-vars.md` Change Log |
+| **Feature-flag / remote config** | New flag keys in code, new `remoteConfig` calls, growthbook/launchdarkly keys | Add keys in the project's flag system (Firebase Remote Config / Growthbook / LaunchDarkly / Unleash) |
+| **Auth provider configuration** | New auth provider initialization or scope change | Configure in the auth provider console matching `stack.auth_provider` (Firebase Console / Supabase dashboard / Clerk dashboard / Auth0 / Cognito) |
+| **Scheduled functions / cron** | New or modified cron/scheduled jobs | firebase: `firebase deploy --only functions`; vercel: deploy includes cron from `vercel.json`; aws: deploy EventBridge rule + Lambda |
+| **Database migrations** | New {entities}, field renames, data backfills referenced in code or ADRs | Run the project's migration command — varies by stack (firebase admin script / `supabase db push` / `prisma migrate deploy` / Mongo migration tool / SQL migrator) |
+| **New API endpoints** | New route files (`src/app/api/` Next.js, `app/routes/api.*` Remix, `src/routes/api/+server.ts` SvelteKit, etc.) | Verify CORS/auth config; update API docs if public |
+| **Third-party services** | New API keys, webhook URLs, or external service integrations | Configure in provider dashboard + add secrets to the deployment platform |
+| **DNS / domain changes** | Hosting or redirect config changes | Update DNS records on registrar; update domain settings on the deployment platform |
+| **Package upgrades with breaking changes** | Major version bumps in `package.json` / `pyproject.toml` / `Gemfile` | Verify compatibility; check migration guides |
 
 ### Output format
 
-Present the checklist as a clearly formatted section in the final report:
+Present the checklist as a clearly formatted section in the final report.
+The example below assumes `stack.deployment: firebase` + `stack.database: firestore`;
+adapt commands and tags to the project's resolved stack.
 
 ```
 ## Production Readiness Checklist
 
 ### Required before deploy
-1. **[Firebase Indexes]** Deploy Firestore composite indexes
+1. **[DB Indexes — firestore]** Deploy composite indexes
    - Command: `firebase deploy --only firestore:indexes`
-   - Reason: New compound query on `redemptions` (storeId + tableNumber + createdAt)
+   - Reason: New compound query on `<entity>` (`<field1>` + `<field2>` + `<field3>`)
 
-2. **[Environment Variable]** Add `REDIS_URL` to Vercel
-   - Go to: Vercel > Project Settings > Environment Variables
+2. **[Environment Variable]** Add `<VAR_NAME>` to the deployment platform
+   - Go to: <Vercel/Firebase/Cloudflare/AWS> > Project Settings > Environment Variables
    - Required for: Production, Preview
-   - Value: (obtain from Upstash dashboard)
+   - Value: (obtain from <provider> dashboard)
 
-3. **[Firestore Rules]** Deploy updated security rules
+3. **[DB Access Rules — firestore]** Deploy updated security rules
    - Command: `firebase deploy --only firestore:rules`
-   - Reason: New collection `promoRedemptions` access rules added
+   - Reason: New {entity} `<name>` access rules added
+
+# Equivalent commands for other stacks:
+#   stack.database: supabase   → `supabase db push` (RLS migration)
+#   stack.database: postgres   → `prisma migrate deploy` (or project migration tool)
+#   stack.database: mongodb    → run the index/validator bootstrap script
+#   stack.database: dynamodb   → `cdk deploy` / `terraform apply` for the table+GSI
 
 ### No action needed
 - No new scheduled functions
@@ -1304,8 +1348,8 @@ Present the checklist as a clearly formatted section in the final report:
 - No DNS changes
 
 ### Notes
-- Firebase index deployment can take 5-10 minutes; deploy BEFORE releasing the code
-- Environment variables must be set BEFORE the Vercel deployment triggers
+- DB index propagation can take time (firestore 5-10 min, postgres CONCURRENTLY minutes-to-hours on large tables, dynamodb GSI minutes); deploy BEFORE releasing the code
+- Environment variables must be set on the deployment platform BEFORE the deploy triggers
 ```
 
 ### Auto-execution of agent-doable tasks
@@ -1313,22 +1357,24 @@ Present the checklist as a clearly formatted section in the final report:
 Before presenting the checklist, **auto-execute** all items that can be performed by the agent
 without manual intervention. Do NOT ask the user for approval — just run them.
 
-**Auto-executable items** (run via Bash tool, no confirmation needed):
+**Auto-executable items** (run via Bash tool, no confirmation needed). Pick the
+command matching `stack.deployment` + `stack.database`. If the inferred command
+is wrong for the project, ask the user — never auto-execute a guess.
 
-| Category | Command | Auto-execute? |
-|----------|---------|--------------|
-| Firestore indexes | `firebase deploy --only firestore:indexes --project <your-firebase-project>` | YES |
-| Firestore security rules | `firebase deploy --only firestore:rules --project <your-firebase-project>` | YES |
-| Storage security rules | `firebase deploy --only storage:rules --project <your-firebase-project>` | YES |
-| Scheduled functions | `firebase deploy --only functions --project <your-firebase-project>` | YES |
+| Category | Command per `stack.deployment` | Auto-execute? |
+|----------|-------------------------------|--------------|
+| Database indexes | firebase → `firebase deploy --only firestore:indexes --project <id>`; supabase → `supabase db push`; vercel+postgres → `prisma migrate deploy` (or project-specific) | YES (when stack-matched) |
+| Persistence access rules | firebase → `firebase deploy --only firestore:rules --project <id>`; supabase → `supabase db push` (RLS migration); aws → CDK / Terraform apply | YES (when stack-matched) |
+| Storage access rules | firebase → `firebase deploy --only storage:rules --project <id>`; aws → S3 bucket policy apply via IaC | YES (when stack-matched) |
+| Scheduled functions | firebase → `firebase deploy --only functions --project <id>`; vercel → deploy step already includes cron from `vercel.json`; aws → CDK / Terraform apply | YES (when stack-matched) |
 
 **Manual-only items** (report to user, do NOT auto-execute):
 
 | Category | Why manual |
 |----------|-----------|
-| Environment variables | Requires Vercel dashboard access or secret values |
-| Firebase Remote Config | Requires Firebase Console UI |
-| Firebase Auth providers | Requires Firebase Console UI |
+| Environment variables | Requires deployment-platform dashboard access or secret values |
+| Feature-flag / remote config | Requires flag-system console (Firebase Remote Config / GrowthBook / LaunchDarkly / Unleash) |
+| Auth provider configuration | Requires console UI of the provider matching `stack.auth_provider` |
 | Database migrations / backfills | Risk of data loss — needs human judgment |
 | Third-party service config | Requires external dashboards and secrets |
 | DNS / domain changes | Risk of downtime — needs human judgment |
@@ -1339,20 +1385,33 @@ without manual intervention. Do NOT ask the user for approval — just run them.
 2. Log the result (success/failure) in the tracker under `## Production Readiness`.
 3. In the final checklist output, mark auto-executed items with their result:
    ```
-   1. **[Firebase Indexes]** Deploy Firestore composite indexes
-      - Command: `firebase deploy --only firestore:indexes --project <your-firebase-project>`
+   1. **[DB Indexes — <stack.database>]** Deploy indexes
+      - Command: <stack-matched command from the Auto-executable table>
       - Result: DEPLOYED (took 45s) | FAILED (error: ...)
    ```
 4. If an auto-execution FAILS: log the error, mark it as `MANUAL FALLBACK NEEDED`,
    and include it in the "Required before deploy" section for the user to handle.
 
-### Firestore Index Verification (MUST — after deploy)
+### DB Index Verification (MUST — after deploy)
+
+After the deploy command succeeds, verify the indexes are actually live before
+reporting success. The deploy command typically returns before index propagation
+completes (Firestore: 5–10 minutes; Postgres `CREATE INDEX CONCURRENTLY` on a
+large table: minutes to hours; DynamoDB GSI: minutes; Mongo background index:
+minutes to hours).
+
+**Skip this section entirely when:**
+- the card has no `db_indexes` / `firestore_indexes` block, OR
+- `stack.database` is unset / `none`, OR
+- the card's index artifact is a SQL migration on a small table (the migration
+  itself is synchronous and self-verifying — the deploy step already failed if
+  the index didn't build).
 
-After `firebase deploy --only firestore:indexes` succeeds, you MUST verify that all indexes
-are actually `READY` before reporting success. The deploy command returns immediately, but
-indexes can take 5-10 minutes to build.
+**Verification procedure — pick the variant matching `stack.database`:**
 
-**Verification procedure:**
+#### Variant — Firestore (`stack.database: firestore`)
+
+After `firebase deploy --only firestore:indexes` succeeds:
 
 1. **Extract expected collection groups** from the local `firestore.indexes.json`:
    ```bash
@@ -1373,7 +1432,6 @@ indexes can take 5-10 minutes to build.
    done | python3 -c "
    import sys, json, re
    raw = sys.stdin.read()
-   # Parse multiple JSON responses concatenated
    creating = []
    for match in re.finditer(r'\{[^{}]*\"indexes\"[^}]*\}', raw, re.DOTALL):
        try:
@@ -1394,19 +1452,55 @@ indexes can take 5-10 minutes to build.
    ```
 
 3. **Poll if NOT_READY** — re-check every 30 seconds, up to 10 retries (5 minutes max).
-   After each retry, print a status update: `Index verification attempt N/10 — still N indexes building...`
 
 4. **Final status**:
-   - If all indexes are `READY`: mark as `VERIFIED READY` in the checklist
-   - If indexes are still `CREATING` after 10 retries: mark as `DEPLOYED BUT BUILDING — indexes may take a few more minutes` (this is a warning, not a failure)
-   - If any index is `NEEDS_REPAIR` or `ERROR`: mark as `INDEX ERROR — manual intervention required` and include the index details
+   - All `READY` → `VERIFIED READY`.
+   - Still `CREATING` after 10 retries → `DEPLOYED BUT BUILDING` (warning).
+   - Any `NEEDS_REPAIR` / `ERROR` → `INDEX ERROR — manual intervention required`.
+
+#### Variant — Postgres / Supabase (`stack.database` ∈ {postgres, supabase})
+
+After the migration / `supabase db push` succeeds:
+
+```bash
+# For each index named in the migration:
+psql "$DATABASE_URL" -c "SELECT indexname, indexdef FROM pg_indexes WHERE indexname = '<index_name>';"
+# If the migration used CREATE INDEX CONCURRENTLY on a large table, also check:
+psql "$DATABASE_URL" -c "SELECT pid, phase, blocks_total, blocks_done FROM pg_stat_progress_create_index;"
+```
+
+If `pg_stat_progress_create_index` returns rows → index still building, poll every
+30s. If `pg_indexes` returns 0 rows for an expected name → CRITICAL (migration
+silently skipped or rolled back).
+
+#### Variant — MongoDB (`stack.database: mongodb`)
+
+After the bootstrap script / migration runs:
+
+```bash
+mongosh "$MONGO_URL" --eval "db.<entity>.getIndexes()"
+```
+
+Confirm every expected `name`/`key` is present. For background-built indexes, watch
+`db.currentOp({'$or':[{op:'command','command.createIndexes':{$exists:true}}]})` until empty.
+
+#### Variant — DynamoDB (`stack.database: dynamodb`)
+
+After `cdk deploy` / `terraform apply`:
+
+```bash
+aws dynamodb describe-table --table-name <table> \
+  --query 'Table.GlobalSecondaryIndexes[].{Name:IndexName,Status:IndexStatus}'
+```
+
+All GSIs must show `ACTIVE`. `CREATING` → poll; `DELETING` / `UPDATING` → manual review.
 
 **Checklist output format with verification:**
 ```
-1. **[Firebase Indexes]** Deploy Firestore composite indexes
-   - Command: `firebase deploy --only firestore:indexes --project <your-firebase-project>`
+1. **[DB Indexes — <stack.database>]** Deploy indexes
+   - Command: <stack-matched command>
    - Deploy: SUCCESS (took 45s)
-   - Verification: ALL INDEXES READY (155/155) | BUILDING (3 still creating after 5min) | ERROR (details)
+   - Verification: ALL READY (5/5) | BUILDING (2 still creating after 5min) | ERROR (details)
 ```
 
 ### Rules

package/framework/.claude/skills/prd/SKILL.md

@@ -28,6 +28,7 @@ message. You ask questions, wait for answers, and iterate.
 |------|-------|-----------|
 | 0 | Context Recovery | [discovery-phase.md](references/discovery-phase.md) |
 | 1 | Kickoff | [discovery-phase.md](references/discovery-phase.md) |
+| 1.6 | Mockup Intake | [discovery-phase.md](references/discovery-phase.md) |
 | 2 | Discovery Question Loop | [discovery-phase.md](references/discovery-phase.md) |
 | 2→CR | Change Request (auto/manual) | [prd-add-phase.md](references/prd-add-phase.md) |
 | 2.5 | Research (opzionale) | [research-phase.md](references/research-phase.md) |
@@ -88,6 +89,17 @@ message. You ask questions, wait for answers, and iterate.
     **Canonical examples**: `FEAT-0875-00..08` (Survey Analytics Redesign),
     `FEAT-0876-00..11` (Menu TIPS). See `assets/epic-template.yml` for the epic
     structure and `assets/card-template.yml` for child structure.
+16. **Mockup Intake (MANDATORY).** Subito dopo Kickoff (Step 1) e prima di entrare in
+    Discovery (Step 2), esegui Step 1.6 — chiedi all'utente se ha mockup a disposizione.
+    Se **sì**: chiedi formato (immagini in chat / path locali), **STOP**, attendi. Sull'arrivo:
+    copia i path locali in `${paths.prd_dir}/<slug>/mockups/`, analizza in dettaglio (vedi
+    [discovery-phase.md](references/discovery-phase.md) § "Mockup analysis schema"), popola
+    `## UI Design` nello state, poi entra in Discovery. Se **no**: marca
+    `mockups.status: none` e procedi col flow standard. Il decision tree di Step 3 (UI Design)
+    consuma `mockups.status` + `screens_in_scope[]` per scegliere ramo Full / Hybrid / Skip
+    senza ulteriore intervento. Le ambiguità rilevate dall'analisi mockup
+    (`mockup_analysis.screens[].gaps[]`) DEVONO diventare domande mirate in Discovery o
+    essere esplicitamente waivate.
 
 ---
 
@@ -122,6 +134,7 @@ At the END of every message (after all text, before stopping), display:
 | # | Fase | Stato |
 |---|------|-------|
 | 1 | Discovery & comprensione | ⬜/🔄/✅ |
+| 1.6 | Mockup intake | ⬜/🔄/✅/⏭️ |
 | 1.5 | Ricerca best practice | ⬜/🔄/✅/⏭️ |
 | 2 | Design UI & approvazione | ⬜/🔄/✅/⏭️ |
 | 3 | Conferma specifiche | ⬜/🔄/✅ |
@@ -129,7 +142,9 @@ At the END of every message (after all text, before stopping), display:
 | 5 | Validazione e commit | ⬜/🔄/✅ |
 
 Comprensione: X% (N/M dimensioni coperte) — ISA: N punti identificati
+Mockup: ⬜ non chiesto / 🔄 in attesa / ✅ N mockup / ⏭️ nessuno
 Ricerca: ⬜ non valutata / 🔍 in corso (background) / ✅ completata / ⏭️ non necessaria
+Step 3 mode: full / hybrid / skipped (impostato dopo Step 1.6 e refinementato a Step 3)
 Prossimo passo: <what happens next>
 ```
 
@@ -183,6 +198,16 @@ Dimensions 1-8 can be resolved by: context-primer context (auto), targeted codeb
 Dimension 9 uses automated codebase scan + user validation (see discovery-phase.md).
 Dimension 10 uses a built-in evaluation tree (see discovery-phase.md).
 
+**Mockup-driven pre-population (when Step 1.6 produced `mockups.status: provided`):**
+- Dimension 5 (UI impact) is largely pre-resolved from `mockup_analysis.screens[]`
+  — log as covered with source `mockup-analysis`. Only ask UI questions for
+  ambiguities in `mockup_analysis.screens[].gaps[]` or for screens NOT in the mockups.
+- Dimension 2 (User journey) is partially pre-resolved from `mockup_analysis.user_flow`
+  — ask only for the connective steps that aren't visible from the mockup sequence
+  (entry point, exit, error branches).
+- All other dimensions follow the normal flow — mockups do not pre-resolve data
+  model, API contract, permissions, edge cases, rollout, ISA, or test strategy.
+
 ---
 
 ## COMPLETED PROGRESS BAR (for final message)
@@ -194,6 +219,7 @@ Dimension 10 uses a built-in evaluation tree (see discovery-phase.md).
 | # | Fase | Stato |
 |---|------|-------|
 | 1 | Discovery & comprensione | ✅ |
+| 1.6 | Mockup intake | ✅/⏭️ |
 | 1.5 | Ricerca best practice | ✅/⏭️ |
 | 2 | Design UI & approvazione | ✅/⏭️ |
 | 3 | Conferma specifiche | ✅ |
@@ -201,7 +227,9 @@ Dimension 10 uses a built-in evaluation tree (see discovery-phase.md).
 | 5 | Validazione e commit | ✅ |
 
 Comprensione: 100%
+Mockup: ✅ N mockup analizzati / ⏭️ nessuno fornito
 Ricerca: ✅ completata / ⏭️ non necessaria
+Step 3 mode: full / hybrid / skipped
 **Pronto per l'implementazione.**
 ```
 
@@ -218,13 +246,13 @@ After cards are created and committed, log this PRD run to `docs/metrics/skill-r
    - `ac_coverage_ratio`: total acceptance_criteria count / total user_stories count across all cards
    - `isa_count`: number of ISA items identified (from the progress bar "ISA: N punti")
    - `has_test_plan_pct`: % of cards that have a `test_plan` field (even if `e2e_required: false`)
-   - `has_firestore_indexes_pct`: % of cards that have a `firestore_indexes` field
+   - `has_db_indexes_pct`: % of cards that have a `db_indexes` field (covers any persistence layer; legacy `firestore_indexes` cards count too)
    - `discovery_iterations`: approximate number of Q&A rounds with the user (count AskUserQuestion calls in this session, default 1 if unknown)
 
 2. Write ONE JSON line (append) to `docs/metrics/skill-runs.jsonl`:
 
    ```json
-   {"ts":"<ISO-8601-UTC>","skill":"prd","run_id":"prd-<slug>","prd_slug":"<slug>","cards_created":0,"ac_coverage_ratio":0.0,"isa_count":0,"has_test_plan_pct":0.0,"has_firestore_indexes_pct":0.0,"discovery_iterations":1,"prd_path":"${paths.prd_dir}/<slug>/PRD.md"}
+   {"ts":"<ISO-8601-UTC>","skill":"prd","run_id":"prd-<slug>","prd_slug":"<slug>","cards_created":0,"ac_coverage_ratio":0.0,"isa_count":0,"has_test_plan_pct":0.0,"has_db_indexes_pct":0.0,"discovery_iterations":1,"prd_path":"${paths.prd_dir}/<slug>/PRD.md"}
    ```
 
 **This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar.

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -31,7 +31,10 @@ business_rationale: |
 scope:
   summary: |
     {{What this card delivers in 2-3 lines.}}
-  users: [{{CUSTOMER|MERCHANT|SUPER_ADMIN}}]
+  # Drawn from identity.audience_segments[] in baldart.config.yml.
+  # Use the project's own persona labels (e.g. ["customer","merchant"] or
+  # ["admin","editor","viewer"] or ["tenant","support","ops"]).
+  users: [{{persona1, persona2}}]
   value: {{Business value in one line.}}
 
 # --- Scope Boundaries (OPTIONAL — include when card is part of a multi-card epic) ---
@@ -122,13 +125,16 @@ test_plan:
       maps_to: "US-{{N}} / AC-{{N}}"
       priority: {{HIGH|MEDIUM}}
   test_credentials:
-    persona: {{CUSTOMER|MERCHANT|SUPER_ADMIN}}
-    auth_method: "{{OTP|password}}"
-    credentials: "{{phone: 3486417303 | username/password}}"
-    store: "{{store name if merchant}}"
-    notes: "{{e.g., OTP inserito manualmente dall'utente}}"
+    # Persona names come from identity.audience_segments[] in baldart.config.yml.
+    # Credential REFERENCES (not real secrets) live in .baldart/overlays/prd.md
+    # § Test Credentials. Never paste secrets in committed YAML.
+    persona: "{{from identity.audience_segments[]}}"
+    auth_method: "{{OTP | password | magic-link | api-token}}"
+    credentials_ref: "{{secret-manager://path | .env.test:VAR_NAME | overlay-reference}}"
+    context: "{{tenant / workspace / store / org — if applicable}}"
+    notes: "{{e.g., OTP entered manually during test}}"
   test_data_prerequisites:
-    - "{{any Firestore data needed before tests}}"
+    - "{{any data that must exist in the persistence layer before tests run}}"
 
 integration_points:
   - id: ISA-{{N}}
@@ -169,15 +175,17 @@ reuse_analysis:
 # --- Data Sources (MANDATORY — compile for EVERY card; use [] only for pure docs/config cards) ---
 # High-level overview of every data source or destination touched by this card.
 # Rules:
-#   type: firestore → collection name in `path`; field-level detail goes in data_fields below.
+#   type: db        → {entity} name in `path` (collection/table/index per stack.database); field-level detail in data_fields below.
 #   type: file      → repo-relative path, operations (READ|WRITE|APPEND|CREATE|DELETE), format.
 #   type: api       → URL or endpoint pattern; READ=GET, WRITE=POST/PUT/PATCH, DELETE=DELETE.
 #   type: env       → env var name; operations always [READ].
 #   []              → explicit empty list for cards that read/write NO data (docs, config stubs).
 #   NEVER omit this field silently — an empty [] signals the writer verified there are no sources.
+# Legacy "firestore" type is still accepted; prefer "db" + db_dialect.
 data_sources:
-  - type: "{{firestore|file|api|env}}"
-    path: "{{collection name | repo-relative file path | API endpoint | env var name}}"
+  - type: "{{db|file|api|env}}"
+    db_dialect: "{{firestore|postgres|supabase|mysql|mongodb|dynamodb|sqlite}}"  # only when type: db
+    path: "{{entity name | repo-relative file path | API endpoint | env var name}}"
     operations: [{{READ|WRITE|APPEND|CREATE|DELETE}}]
     # format: "{{JSONL|YAML|JSON|markdown|binary}}"  # include for file type only
     # note: "{{optional: data shape, why this source}}"
@@ -194,32 +202,41 @@ env_vars:
     feature_card: "{{nome feature / ID card, es. SPU / ADR-2026-04-24}}"
     note: "{{a cosa serve}}"
 
-# --- Data Fields (MANDATORY for cards that read/write Firestore — omit for UI/docs/config only) ---
+# --- Data Fields (MANDATORY for cards that read/write the persistence layer — omit for UI/docs/config only) ---
 # Structured field-name registry for mechanical validation (pre-commit hook + Quality Audit).
-# Field Grounding Rule: EVERY field here MUST be verified via Grep on field-registry.json
-# BEFORE ts_verified is set to true. See prd-card-writer.md Field Grounding Rule.
-# Fields id, createdAt, updatedAt are universal — do NOT include them here.
+# Field Grounding Rule: EVERY field here MUST be verified via Grep on the schema registry
+# (path resolved per .baldart/overlays/prd.md § Schema Registry — common defaults:
+#  ${paths.references_dir}/field-registry.json for Firestore-style projects,
+#  ${paths.references_dir}/schema.md for SQL, prisma/schema.prisma for Prisma).
+# Fields id, createdAt, updatedAt (or their snake_case equivalents) are universal — do NOT include here.
 data_fields:
-  - collection: "{{collectionName}}"          # exact key in ${paths.references_dir}/field-registry.json
-    field: "{{fieldName}}"                    # exact field name (verified via Grep)
-    type: "{{TypeScript type}}"               # e.g. "string", "OccasionType", "boolean"
+  - entity: "{{collection or table name}}"    # exact key in the project schema registry
+    field: "{{fieldName or column_name}}"     # exact identifier (verified via Grep)
+    type: "{{language-native type}}"          # e.g. "string", "OccasionType", "boolean", "varchar(64)", "JSONB"
     status: "{{existing|new|modified|deprecated_removed}}"
     ts_verified: {{true|false}}               # true = Grep confirmed field in registry
-    source: "{{src/types/booking.ts}}"        # TypeScript file where interface is defined
+    source: "{{src/types/booking.ts | prisma/schema.prisma:42 | migrations/2024_..._create.sql}}"
     # schema_ref: "PRD.md#schema-verification"  # ONLY for status: new fields
 
-firestore_indexes:
-  - collection: "{{collection name}}"
+db_indexes:
+  - entity: "{{collection or table name}}"
+    dialect: "{{firestore|postgres|supabase|mysql|mongodb|dynamodb|sqlite}}"
     fields:
-      - field: "{{field1}}"
-        order: "{{ASC|DESC}}"
-      - field: "{{field2}}"
+      - field: "{{field1 or column1}}"
+        order: "{{ASC|DESC}}"                 # firestore/sql; for mongo use {field1: 1|-1}
+      - field: "{{field2 or column2}}"
         order: "{{ASC|DESC}}"
+    kind: "{{composite|covering|partial|GIN|GSI|LSI|unique|fulltext}}"  # pick what matches dialect
     query_location: "{{file path where the query lives}}"
     prd_ref: "IDX-{{N}}"
-    # Omit this section entirely if the card has no compound Firestore queries.
-    # If present, the coder MUST add these indexes to firestore.indexes.json
-    # in the same commit as the query code.
+    # Omit this section entirely if the card has no compound queries / multi-column indexes.
+    # If present, the coder MUST ship the index in the same commit as the query —
+    # firestore.indexes.json (Firestore), migration file (SQL), createIndex call (Mongo),
+    # CDK/Terraform table definition (DynamoDB).
+
+# Legacy field name kept for backwards-compat with pre-3.15.0 cards. The validator
+# accepts either name; the writer should prefer db_indexes for new cards.
+firestore_indexes: []  # DEPRECATED in v3.15.0 — use db_indexes instead
 
 documentation_impact:
   - "{{doc path}} — {{what to update}}"

package/framework/.claude/skills/prd/assets/epic-template.yml

@@ -11,7 +11,7 @@
 # The epic is a TRACKER, not implementation work:
 #   - NO files_likely_touched pointing to code (only docs allowed)
 #   - NO validation_commands, existing_patterns, anti_patterns
-#   - NO data_fields, firestore_indexes
+#   - NO data_fields, db_indexes (firestore_indexes legacy too)
 #   - NO test_plan with scenarios (test scenarios live on children)
 #   - data_sources: [] (always empty)
 #
@@ -65,7 +65,8 @@ scope:
   summary: |
     Coordinamento delle {{N}} sub-card che implementano l'epic:
     {{breve descrizione di ogni sub-card in 1 riga ciascuna}}
-  users: [{{CUSTOMER|MERCHANT|SUPER_ADMIN}}]
+  # Drawn from identity.audience_segments[] in baldart.config.yml.
+  users: [{{persona1, persona2}}]
   value: "{{one-line business value}}"
 
 scope_boundaries: