baldart 3.14.1 → 3.16.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,12 +219,44 @@ 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.
 
 ---
 
+## Agent Routing (Phase 2 dispatcher)
+
+Phase 2 reads the card's `owner_agent` field and dispatches to the matching
+specialist. The enum is defined by the PRD card writer
+(`framework/.claude/agents/prd.md:538` + `prd-card-writer.md § Agent
+Specialization Rules`) and validated by the PRD validation phase
+(`framework/.claude/skills/prd/references/validation-phase.md` Step 6 → 0).
+
+| `owner_agent` | Dispatcher action in Phase 2 step 7 | Briefing variant |
+|---|---|---|
+| `coder` | Spawn `coder` | Standard coder briefing (default body below) |
+| `ui-expert` | Spawn `ui-expert` | UI briefing — adds BLOCKING registry-first cascade + Post-Intervention Coherence Check (see step 7 § UI branch) |
+| `plan` | Fallback to `coder` + WARN | Standard coder briefing + log `"[ROUTER] plan-only briefing not yet implemented — using coder"` |
+| `visual-designer` | Fallback to `coder` + WARN | Standard coder briefing + same WARN format |
+| `motion-expert` | Fallback to `coder` + WARN | Standard coder briefing + same WARN format |
+| missing / `claude` / unknown | Fallback to `coder` + WARN | Standard coder briefing; for unknown value also log the literal value |
+
+The three `plan` / `visual-designer` / `motion-expert` stubs exist so the
+router never blocks a card; specialized briefings are tracked as a follow-up.
+
+If you change which values are valid here, also update:
+
+- `framework/.claude/agents/prd.md:538` (the canonical enum comment),
+- `framework/.claude/skills/prd/assets/card-template.yml` (the placeholder),
+- `framework/.claude/agents/prd-card-writer.md § Agent Specialization Rules`,
+- `framework/.claude/skills/prd/references/validation-phase.md` Step 6 → 0a,
+- `framework/.claude/agents/REGISTRY.md` decision-tree.
+
+Keep them in lockstep — drift between any two layers silently mis-routes cards.
+
+---
+
 ## Per-card pipeline
 
 For each card, execute these phases in order:
@@ -261,7 +294,28 @@ For each card, execute these phases in order:
 
 ### Phase 2 — Implement (self-healing, up to 3 retries)
 6. **Update tracker**: phase = "2-implement".
-7. Spawn the **coder** agent (or appropriate specialist from `.claude/agents/REGISTRY.md`) using this **standardized mission briefing** — fill in each section from the card YAML, tracker, and codebase-architect findings:
+6b. **Agent dispatch (router)** — read `owner_agent` from the card YAML and resolve the spawn target per the table in § Agent Routing above:
+
+   ```
+   Let raw = card.owner_agent (string, may be missing).
+   Switch on raw:
+     - "coder"           → spawn = "coder",       briefing = "coder"
+     - "ui-expert"       → spawn = "ui-expert",   briefing = "ui-expert"
+     - "plan"            → spawn = "coder",       briefing = "coder"
+                           + log: "[ROUTER] plan-only briefing not yet implemented — using coder"
+     - "visual-designer" → spawn = "coder",       briefing = "coder"
+                           + log: "[ROUTER] visual-designer briefing not yet implemented — using coder"
+     - "motion-expert"   → spawn = "coder",       briefing = "coder"
+                           + log: "[ROUTER] motion-expert briefing not yet implemented — using coder"
+     - "" | missing | "claude"
+                         → spawn = "coder",       briefing = "coder"
+                           + log: "[ROUTER] card <ID> has no valid owner_agent (got '<raw>'); defaulting to coder"
+     - anything else     → HALT. Log: "[ROUTER] card <ID> has unknown owner_agent '<raw>' — not in {coder, ui-expert, plan, visual-designer, motion-expert}. Ask the user how to proceed."
+   ```
+
+   Log the resolved `spawn` and `briefing` in the tracker (1 line: `"router: owner_agent=<raw> → spawn=<agent>, briefing=<variant>"`). This is the audit trail for which specialist actually handled the card.
+
+7. Spawn the **resolved agent** (from step 6b) using this **standardized mission briefing** — fill in each section from the card YAML, tracker, and codebase-architect findings. When `briefing = "ui-expert"`, ALSO include the additional UI sections marked **[UI-ONLY]** below:
 
    ```
    ## MISSION BRIEFING — <CARD-ID>
@@ -293,6 +347,70 @@ For each card, execute these phases in order:
    Read the design.html file and use it as the visual reference for your implementation.
    The design was approved by the user — your implementation MUST match it.
 
+   ### [UI-ONLY] Registry-first BLOCKING pre-work (include ONLY when briefing = "ui-expert")
+   You are spawned as `ui-expert`. Before writing any UI code, you MUST complete
+   the registry-first cascade defined in
+   `framework/.claude/agents/ui-expert.md` § "Authoritative Style Reference —
+   Registry-First Protocol" (the SSOT lives in
+   `framework/agents/design-system-protocol.md`). Reproduce its 5 steps
+   verbatim, do NOT paraphrase or skip:
+
+   1. Read `${paths.design_system}/INDEX.md` (component index + Canonical
+      Authority Matrix).
+   2. Read `${paths.ui_guidelines}` (visual language, typography,
+      accessibility, brand voice).
+   3. Read `${paths.design_system}/tokens-reference.md` (token contract —
+      SSOT for every color / spacing / shadow / radius / motion value).
+   4. For EACH primitive in scope on this card, read
+      `${paths.design_system}/components/<Name>.md`. "In scope" = any
+      component named in the mockup, the requirements, or `files_likely_touched`.
+   5. For EACH pattern in scope, read the relevant
+      `${paths.design_system}/patterns/<topic>.md`.
+
+   State, in your first response, which Authority Matrix rows govern this
+   card, which component specs you read (step 4), and which patterns you
+   read (step 5). Skipping this declaration = the orchestrator will reject
+   the implementation and re-spawn.
+
+   The `features.has_design_system: true` flag in `baldart.config.yml` is
+   the precondition for the full cascade. When `features.has_design_system:
+   false`, only step 2 applies — log the gap, recommend `/design-system-init`
+   if drift is visible, and proceed with coder-level diligence (no cascade
+   enforced).
+
+   ### [UI-ONLY] Implementation-only constraint (include ONLY when briefing = "ui-expert")
+   This `/new` invocation gives you the role of IMPLEMENTER, not designer:
+
+   - DO NOT redesign the mockup. The mockup at `links.design` is the
+     user-approved visual contract for this card.
+   - DO NOT silently adapt a mockup detail that conflicts with the registry
+     (e.g. a custom shadow not in `tokens-reference.md`, a font size off the
+     type scale, a color outside the palette). If you find such a conflict:
+     STOP, log it in the tracker as `[DS-DRIFT] mockup-vs-registry`, and ask
+     the user which side to honor.
+   - DO NOT extend scope into business logic, API calls, state management, or
+     validation rules. Those belong to a sibling `coder` card (see
+     `backlog-phase.md § Rule B`). If a requirement appears to need logic,
+     STOP and ask — do not implement it.
+
+   ### [UI-ONLY] Post-Intervention Coherence Check (include ONLY when briefing = "ui-expert")
+   Before declaring the card done, you MUST reconcile the three design-system
+   sources in the SAME commit as your UI change, per
+   `framework/agents/design-system-protocol.md § Post-Intervention Coherence Check`:
+
+   - `${paths.design_system}/INDEX.md` — add / update entries for any primitive
+     introduced or modified. Drift code: `DS_INDEX_DRIFT`.
+   - `${paths.design_system}/components/<Name>.md` — ship the per-component
+     spec for any new primitive; update the spec when a primitive's API or
+     visual changes. Drift code: `DS_COMPONENT_STALE`.
+   - `${paths.design_system}/tokens-reference.md` — add / update token entries
+     when introducing new semantic tokens. Drift code: `DS_TOKENS_DRIFT`.
+
+   The four conditions defined in `design-system-protocol.md` are the SSOT —
+   reproduce them in your completion report under a `design_system_coherence:`
+   block listing which conditions applied and which artifacts you updated.
+   Omitting the block = the orchestrator treats the card as not done.
+
    ### File Permissions (ENFORCED — no exceptions)
    MAY EDIT — your files for this card:
    [list from ownership map for this card]
@@ -306,29 +424,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,15 +641,48 @@ 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.
 
+   - **[UI-ONLY] Design-system conformance** → run ONLY when `briefing = "ui-expert"` from step 6b
+     AND `features.has_design_system: true` in `baldart.config.yml`:
+     - Grep the changed files for hardcoded design values that bypass the registry:
+       hex colors (`#[0-9a-fA-F]{3,8}`), `rgb(`/`rgba(`, `box-shadow:` with inline
+       offsets/blurs, `border-radius:` with px/rem literals, `font-size:` with raw
+       px/rem (outside the type scale), `padding`/`margin` with raw px (outside the
+       spacing scale). Each hit on a NEW or MODIFIED line = Partial — the value
+       should come from a token, not a literal.
+     - Verify the completion report includes the `design_system_coherence:` block
+       required by the UI-ONLY briefing. Missing block = Missing (orchestrator
+       cannot confirm Post-Intervention Coherence Check ran).
+     - For each new primitive declared by the report (or detected via Grep for new
+       components in `${paths.components_primitives}`), verify the matching
+       `${paths.design_system}/components/<Name>.md` spec was created in the same
+       commit. Missing spec = Partial — fix by re-spawning `ui-expert` with the
+       narrow instruction "ship the component spec for <Name> per
+       design-system-protocol.md".
+     - For each token change declared by the report, verify the entry exists in
+       `${paths.design_system}/tokens-reference.md`. Missing entry = Partial.
+     - If `features.has_design_system: false`, log "DS conformance skipped — flag is false" and continue.
+
 5. Classify each item:
    - **Done** — code exists AND satisfies the FULL scope of the requirement (not just partial).
    - **Partial** — some code exists but the criterion is not fully satisfied (e.g., UI renders but no error state, endpoint exists but wrong response shape).
@@ -695,7 +863,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 +920,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 +1428,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 +1486,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 +1495,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 +1523,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 `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.
+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).
 
-**Verification procedure:**
+**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).
+
+**Verification procedure — pick the variant matching `stack.database`:**
+
+#### 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 +1570,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 +1590,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