baldart 4.11.0 → 4.13.0

package/framework/.claude/skills/new/references/merge-cleanup.md

@@ -0,0 +1,175 @@
+<!-- Modulo on-demand di /new — NON un file installato a sé. Caricato via Read dalla § "Routing" del SKILL.md core. -->
+
+> **Modulo `/new`** — eseguilo, poi torna al core § "Routing" per la fase successiva. I `§ "..."` (Context economy, Context Tracking, Trivial-card fast-lane, Risk-signal detector, Fix Application Log) vivono nel **core SKILL.md**.
+
+## Phase 6 — Post-batch merge & cleanup (delegated to worktree-manager skill)
+
+**→ Visibility (batch transition)**: TaskUpdate `Merge & cleanup` → `in_progress` and emit a Progress Bar per § "Progress Visibility". Mark it → `completed` at the end of Phase 6c (merge done, worktree removed, workspace reconciled).
+
+After the final review passes AND all cards are committed in the worktree, delegate the entire merge and cleanup to the **worktree-manager** skill (`/mw` in programmatic mode):
+
+1. **BEFORE invoking /mw** — verify no uncommitted files remain in the worktree:
+   ```bash
+   cd <worktree-path>
+   git status --porcelain
+   ```
+   If ANY uncommitted files exist (staged, unstaged, or untracked), commit them NOW with `[safety] Auto-commit remaining files before merge`. Do NOT proceed to `/mw` with a dirty worktree — files WILL be lost during rebase.
+2. Invoke `/mw` with:
+   - The worktree path and branch from the tracker
+   - `checksAlreadyPassed: true` (final review + QA already validated the build)
+   - All card IDs for the commit message
+3. The skill handles: safety commit of any remaining uncommitted files (step 3), rebasing onto the latest trunk (`$TRUNK` = `git.trunk_branch`) (step 4b — auto-resolves doc conflicts, stops on code conflicts), merging into the trunk via the configured `git.merge_strategy` (step 4c — `pr` uses `gh pr merge`, `local-push` does a direct FF push to `origin/$TRUNK`; NEITHER runs `git checkout` of the trunk on the main repo, respecting the absolute terminal-isolation rule), post-merge verification, worktree removal, registry cleanup, and remote branch deletion.
+4. **If code merge conflicts** → the skill STOPs and reports. Doc-only conflicts (ssot-registry.md, project-status.md, etc.) are auto-resolved by keeping both sides.
+5. **If post-merge build fails** → the skill STOPs and keeps the worktree intact for investigation.
+6. Record the merge commit hash and result in the tracker. **Also record the merge timestamp** under `## Worktree Merges` (`merge_ts: <ISO-8601>`): for `local-push` use the local merge-commit time (`git log --format=%ci <hash>`); for `pr` (`gh pr merge`) use the PR merge completion time, or note `merge_ts: pending` if GitHub has not yet finalized the merge. Phase 8's `cycle_time_mins` reads THIS field as the strategy-independent end anchor (never a raw hash that may be the PR HEAD).
+
+### Phase 6b — Backlog Card Status Reconciliation (MANDATORY — ZERO TOLERANCE)
+
+**This gate runs IMMEDIATELY after Phase 6 merge completes, BEFORE presenting any summary to the user. It is NON-SKIPPABLE.**
+
+The most common failure mode is leaving cards IN_PROGRESS after merge. This creates SSOT drift and confuses downstream agents (codebase-architect, doc-reviewer). This gate prevents that.
+
+**Steps:**
+
+1. **Read the tracker file** to get the full list of card IDs in the batch.
+2. **For EACH card in the batch**, read its backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`) and check the `status` field:
+   - If `status: DONE` → OK, skip.
+   - If `status` is anything else (`IN_PROGRESS`, `READY`, `TODO`, etc.) → **FORCE UPDATE to DONE immediately**.
+3. **Early exit — all cards already DONE**: if step 2 found ALL cards are already `status: DONE`, skip steps 4-5 entirely. Log in the tracker:
+   ```
+   ## Phase 6b — Status Reconciliation
+   Cards checked: N
+   Already DONE: N (all cards marked DONE by coder agents)
+   Force-updated to DONE: 0
+   Reconciliation commit: not needed
+   ```
+   Proceed directly to step 6.
+4. **Force update procedure** for non-DONE cards:
+   ```bash
+   # In the MAIN repo (not worktree — worktree is already cleaned up)
+   cd <main-repo-path>
+   ```
+   Edit the backlog YAML: set `status: DONE`, add `completed_date: <today>`, add implementation note: `"Marked DONE by post-merge reconciliation gate (Phase 6b)"`.
+5. **If ANY card was force-updated**: commit in the main repo with these precautions:
+   a. **Clear stale COMMIT_LOCK** (common when coder agents crash or timeout):
+      ```bash
+      # Remove any stale COMMIT_LOCK from main repo or worktrees
+      rm -f <main-repo-path>/.git/COMMIT_LOCK 2>/dev/null
+      find <main-repo-path>/.git/worktrees -name COMMIT_LOCK -delete 2>/dev/null || true
+      ```
+   b. **Stage backlog YAMLs AND related docs** (pre-commit hook requires doc updates):
+      ```bash
+      # Stage only the force-updated backlog YAMLs
+      git add ${paths.backlog_dir}/CARD-001.yml ${paths.backlog_dir}/CARD-002.yml
+      # If ssot-registry.md was modified during the batch, stage it too
+      # (doc-freshness hook blocks commits that touch ${paths.backlog_dir}/ without ssot-registry.md)
+      git diff --name-only ${paths.references_dir}/ssot-registry.md && git add ${paths.references_dir}/ssot-registry.md || true
+      ```
+   c. **Commit with explicit file list**:
+      ```bash
+      git commit -m "[BATCH] Mark cards DONE — post-merge reconciliation"
+      ```
+   d. **If commit fails due to pre-commit hook** (lint-staged, doc-freshness): check the error.
+      - If "no staged files" → all changes were already committed. Log as "not needed".
+      - If doc-freshness requires ssot-registry.md → update its `last_verified_from_code` date, stage it, and retry.
+      - If COMMIT_LOCK → re-run step 5a and retry.
+      - Do NOT retry more than 2 times. Log the failure and move on.
+6. **Update tracker** with reconciliation results:
+   ```
+   ## Phase 6b — Status Reconciliation
+   Cards checked: N
+   Already DONE: M
+   Force-updated to DONE: K [list card IDs]
+   Reconciliation commit: <hash> (or "not needed")
+   ```
+7. **HALT condition**: if a card cannot be updated (e.g., file read error, YAML parse error), log it in `## Issues & Flags` and continue with the remaining cards. Report the failure in the final summary.
+
+**Why this exists**: Agents frequently skip the DONE marking in Phase 4 (step 27) due to context compaction, commit failures that interrupt the flow, or team mode where Step D.6 gets lost. This gate is the safety net that catches ALL of these cases.
+
+### Phase 6c — Workspace Hygiene Post-merge (BLOCKING — non-skippable)
+
+**Why this exists**: FEAT-0006 incident closed the batch leaving the main repo with an unpushed orphan commit (`c9d41f9`) and local `develop` diverged from `origin/develop` for a manual fix. This phase closes the loop opened by Phase 0: it verifies the main repo is clean and synchronized, parses the `[SYNC-DEFERRED]` marker emitted by `/mw` when HEAD ≠ `$TRUNK`, and restores any stash saved in Phase 0.
+
+**Auto Mode does NOT override this phase.** Every `AskUserQuestion` below is non-bypassable.
+
+**Steps:**
+
+1. **Fetch remote state**:
+   ```bash
+   git -C "$MAIN" fetch origin --quiet
+   ```
+
+2. **Parse `mw-docs` sync markers** — scan the captured stdout from every `/mw` invocation in this batch (kept in the tracker under `## Worktree Merges`):
+   - **`[SYNC-DEFERRED] main repo HEAD=<branch>`** (main repo HEAD ≠ `$TRUNK`) — surface via `AskUserQuestion`:
+     - Question: `"Una o più merge worktree hanno deferito la sincronizzazione di local $TRUNK (main repo HEAD non era $TRUNK). Come riconcilio adesso?"`
+     - Options: `[Ora HEAD è $TRUNK → ff-pull adesso]` / `[Lascia deferred (riconcilio io manualmente)]` / `[Mostra dettagli e fammi decidere]`.
+   - **`[SYNC-NEEDS-DECISION] …`** (HEAD was `$TRUNK` but the ff was blocked by a **foreign** uncommitted file, or by a divergence/rebase conflict `/mw` would not auto-commit) — this is NEVER a passive note. Surface via `AskUserQuestion`:
+     - Question: `"Il $TRUNK locale non si è sincronizzato: <dettaglio dal marker>. Come chiudo?"`
+     - Options: `[Committa tu adesso (descrivi cosa)]` / `[Lo gestisco io — chiudi senza sync locale]` / `[Mostrami il diff e decidiamo]`.
+   - **No marker** — `/mw` fast-forwarded (or auto-reconciled the framework telemetry log); nothing to parse.
+
+3. **Clean-tree assertion (BLOCKING — same framework-managed partition as Phase 0 step 3)**:
+   ```bash
+   POST_DIRTY="$(git -C "$MAIN" status --porcelain \
+     | grep -vE "^.{3}\"?${METRICS}/" \
+     | grep -vE "^.{3}\"?${METRICS}\"?$" \
+     | grep -vE "^.{3}\"?\.baldart/(generated/|state\.json|skill-conflicts\.json)" \
+     | grep -v '^[[:space:]]*$')"
+   ```
+   (Apply the **same** partition as Phase 0 step 3: telemetry under `$METRICS` and BALDART-managed `.baldart/` artifacts — `generated/`, `state.json`, `skill-conflicts.json`, but NOT `overlays/` — are auto-ignored, never surfaced. Otherwise a reinstall mid-batch would block the close on its own output.)
+   If `$POST_DIRTY` is non-empty AND no Phase 0 stash is pending → invoke `AskUserQuestion`:
+   - Question: `"Main repo ha modifiche non committate dopo il batch (non c'era stash di Phase 0). Cosa faccio?"`
+   - Options: `[Mostrami il diff e fammi decidere]` / `[Stash adesso con label baldart-post-batch-<timestamp>]` / `[Lascia così (lo gestisco io)]` / `[Halt]`.
+
+4. **Divergence assertion (BLOCKING — this catches the FEAT-0006 orphan-commit pattern)**. `$MAIN` and `$TRUNK` are read from the tracker (`## Worktree` section); HALT if either is absent/empty.
+   ```bash
+   read BEHIND AHEAD <<< "$(git -C "$MAIN" rev-list --left-right --count "origin/$TRUNK...$TRUNK")"
+   ```
+   Compute `$GENUINE_AHEAD` / `$GENUINE_LIST` / `$FW_SKIPPED` with the **exact same reclassification loop as Phase 0 step 4** (framework-management commits — subtree merges into `.framework/`, `baldart update`/`add` chores, `.framework/`-only commits — are auto-ignored, NOT orphan commits). Then branch on `$BEHIND` and `$GENUINE_AHEAD`:
+   - **`BEHIND=0` and `GENUINE_AHEAD=0`** — synchronized. If `$FW_SKIPPED > 0`, log `Divergence: $FW_SKIPPED framework-management commits ahead (auto-ignored)` and proceed. No `AskUserQuestion`.
+   - **Ahead only (`GENUINE_AHEAD > 0`, genuine unpushed commits)** — invoke `AskUserQuestion`:
+     - Question: `"Local $TRUNK ha $GENUINE_AHEAD commit genuini non pushati su origin/$TRUNK al termine del batch (esclusi $FW_SKIPPED di gestione framework). Lista: <git show -s --oneline $GENUINE_LIST>. Cosa faccio?"`
+     - Options: `[Push adesso (git push origin $TRUNK)]` / `[Cherry-pick selettivo su origin/$TRUNK]` / `[Reset --hard origin/$TRUNK (richiede conferma esplicita, DISTRUTTIVO)]` / `[Halt con stato preservato]`.
+     - On `Reset --hard origin/$TRUNK` re-ask `AskUserQuestion` to confirm: `"Confermi reset --hard? I commit <list> verranno persi se non pushati altrove."` Solo dopo conferma esplicita esegui il reset.
+   - **Behind only (`BEHIND > 0`, `GENUINE_AHEAD=0`)** — invoke `AskUserQuestion`:
+     - Question: `"Local $TRUNK è behind origin/$TRUNK di $BEHIND commit (qualcuno ha pushato durante il batch). Faccio ff-pull adesso?"`
+     - Options: `[Fast-forward pull]` / `[Lascia behind (lo gestisco io)]`.
+   - **Diverged both ways (`BEHIND > 0` and `GENUINE_AHEAD > 0`)** — invoke `AskUserQuestion`:
+     - Question: `"Local $TRUNK è diverged ($BEHIND behind, $GENUINE_AHEAD genuine ahead). Servono entrambe le riconciliazioni. Come procedo?"`
+     - Options: `[Rebase local $TRUNK su origin/$TRUNK]` / `[Mostrami i commit locali e decidiamo]` / `[Halt]`.
+
+5. **Restore Phase 0 stash (if any)** — read the tracker for `## Workspace Snapshot: <message-label>`:
+   - If the snapshot is `dirty-tree override` → skip restore, log "user retained dirty-tree responsibility".
+   - If it is a stash MESSAGE label (e.g. `baldart-new-phase0-<FIRST-CARD-ID>-<timestamp>`) — resolve the stash by its message, NEVER by positional `stash@{N}` (other stashes may have shifted the index since Phase 0). This runs on `$MAIN` (the main checkout, not a worktree), so a stash op here is safe:
+     ```bash
+     REF="$(git -C "$MAIN" stash list | grep -F "<message-label>" | head -1 | cut -d: -f1)"
+     [ -n "$REF" ] && git -C "$MAIN" stash pop "$REF" \
+       || echo "stash '<message-label>' not found — was it already restored?"
+     ```
+     On conflict, do NOT silent-drop — invoke `AskUserQuestion`:
+     - Question: `"Restore dello stash di Phase 0 ha generato conflitti. Lo stash è ancora presente (NON eliminato). Come procedo?"`
+     - Options: `[Lascia lo stash + apri istruzioni per merge manuale]` / `[Mostrami il conflitto inline]` / `[Halt]`.
+
+6. **Log and exit**:
+   ```
+   ## Phase 6c — Workspace Hygiene Post-merge
+   Status: PASS
+   Clean-tree: <yes | resolved: stashed | user-retained>
+   Divergence (local…origin/$TRUNK): <0\t0 | resolved: pushed/cherry-picked/ff-pulled/rebased>
+   Sync-deferred markers: <none | reconciled | user-retained>
+   Phase 0 snapshot restore: <n/a | popped clean | conflict-deferred-to-user>
+   Completed: <timestamp>
+   ```
+   If any step ended in HALT, set `Status: HALT` and report — Phase 7 must NOT start with an unclean main repo unless the user explicitly chose `[Lascia così]`.
+
+7. **Anti-bypass guard** — like Phase 0, before exiting Phase 6c re-read the tracker section you just wrote. Missing `## Phase 6c` → refuse to proceed to Phase 7. There is no `--skip-phase-6c` flag; treat any urge to skip as a self-correction trigger.
+
+### Fail-safe rules (enforced by worktree-manager skill)
+- **Never `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo** from inside this orchestrator. The main repo is shared across parallel terminals. Use the configured `git.merge_strategy` for trunk merges and `git -C <main> pull --ff-only` (only when `HEAD = $TRUNK` already) for sync. See `/mw` step 4c.
+- Never merge into a release/production branch — only into the integration trunk (`$TRUNK` = `git.trunk_branch`), via the configured `git.merge_strategy` (NOT local checkout).
+- Never force push to the trunk. `--force-with-lease` on feature branches after rebase is allowed.
+- Never delete a branch before successful merge verification.
+- Never remove a worktree before confirming the trunk is stable post-merge.
+- Stop execution immediately if any command fails.
+
+---

package/framework/.claude/skills/new/references/metrics.md

@@ -0,0 +1,72 @@
+<!-- Modulo on-demand di /new — NON un file installato a sé. Caricato via Read dalla § "Routing" del SKILL.md core. -->
+
+> **Modulo `/new`** — eseguilo, poi torna al core § "Routing" per la fase successiva. I `§ "..."` (Context economy, Context Tracking, Trivial-card fast-lane, Risk-signal detector, Fix Application Log) vivono nel **core SKILL.md**.
+
+## Phase 8 — Metrics Log (MONITORING SIGNAL — non-blocking — runs after Phase 7)
+
+After the Production Readiness Checklist is complete, log this batch run to the skill
+effectiveness registry. This enables tracking of first-attempt success rate, actionability,
+and QA quality over time. This is a telemetry write, NOT a gate — it never blocks the batch (see
+the fail-safe note at the end of the phase). It was previously labelled "MANDATORY", but since it
+has no blocking consequence the honest label is "monitoring signal".
+
+**Steps:**
+
+1. Read the batch tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`) to extract — every field below has a NAMED upstream producer; read the structured key, do NOT re-parse prose:
+   - Start timestamp (from `Started:` field)
+   - Worktree-creation timestamp (from `## Worktree` — the time Phase 0/Pre-flight created the worktree; the strategy-independent cycle-time anchor, see step 2)
+   - Card list and total count
+   - For each completed card:
+     - `fix_cycles` (from the per-phase retry counts logged in `## Completed Cards`)
+     - `qa_profile`, `qa_verdict` (Phase 3.5 step 25 / D.4 QA line)
+     - `qa_first_attempt` (Phase 3.5 step 25 named flag — `pass`/`fail`/`n/a`)
+     - `doc_gaps: found=<N> fixed=<M>` (Phase 3 step 15 / D.4a named counter)
+   - Batch-level `review_findings: total / verified / blockers` (Final Review F.5 step 13 named counters — the canonical source for `findings_total` / `findings_verified` / `blockers_count`)
+   - Merge commit hash (and, when `git.merge_strategy: pr`, the PR merge timestamp recorded by Phase 6 — see step 2)
+
+   If any named field is absent (e.g. a legacy tracker), record `0`/`n/a` for that field and append `metrics_gaps: <field>` to the JSONL row's notes — do NOT invent a value by re-parsing free-form prose.
+
+2. Compute aggregate metrics:
+   - `first_attempt_success_rate`: cards with fix_cycles == 0 / total_cards
+   - `mean_fix_cycles`: mean of per-card fix cycle counts
+   - `qa_profiles`: count of {skip, light, balanced, deep}
+   - `qa_pass_first_attempt_rate`: cards with `qa_first_attempt == pass` / cards where qa ran (exclude `n/a` SKIP/LIGHT cards from the denominator) — read the named flag from step 1, do NOT re-infer from `## Fix Application Log` rows
+   - `findings_total` / `findings_verified`: from the batch-level `review_findings` named counter (Final Review), NOT a per-card re-sum (which would conflate QA gate counts with codex review findings)
+   - `actionability_rate`: findings_verified / findings_total (conservative proxy — a lower-bound on reviewer precision, since some VERIFIED findings end as NEEDS_MANUAL_CONFIRMATION and never produce a fix; 0 if no findings)
+   - `severity_p0_pct`: blockers_count / findings_total (0 if no findings)
+   - `cycle_time_mins`: minutes from the **strategy-independent anchor** to batch completion. Use the **worktree-creation timestamp** (Phase 0/Pre-flight) as the start, NOT `Started:` (which precedes workspace hygiene) and NOT a merge-commit hash (which varies by `git.merge_strategy` — under `pr` the merge commit is created asynchronously by GitHub CI and may not exist locally at Phase 8 time). End anchor: read the `merge_ts` field Phase 6 step 6 recorded under `## Worktree Merges` (it is already strategy-resolved there — local merge-commit time for `local-push`, PR merge completion time for `pr`). If `merge_ts: pending` (a `pr` merge GitHub has not yet finalized), fall back to "now" (`date -u`). Never recompute from a raw merge-commit hash that may be the PR HEAD rather than the actual merge commit.
+
+   > `$METRICS` = `paths.metrics` from `baldart.config.yml` (default `docs/metrics`). All paths below resolve under `$METRICS` — never a hardcoded `docs/metrics`.
+
+3. **Assemble the full JSONL record in memory** (single atomic append — JSONL is append-only, so the row must be COMPLETE before it touches the file). If `STATS=true` (step 6), the `"cost"` key is part of THIS record — do NOT write a baseline row now and rewrite it later (a mid-file rewrite corrupts the JSONL; there is no `sed -i`/`jq` rewrite step in this skill). When `STATS=true`, defer the single append to step 6 after the cost object is computed; when `STATS=false`, append now. The record shape:
+
+   ```json
+   {"ts":"<ISO-8601-UTC>","skill":"new","run_id":"batch-<FIRST-CARD-ID>","cards":["FEAT-XXX"],"total_cards":N,"first_attempt_success_rate":0.0,"mean_fix_cycles":0.0,"qa_profiles":{"skip":0,"light":0,"balanced":0,"deep":0},"qa_pass_first_attempt_rate":0.0,"findings_total":0,"findings_verified":0,"actionability_rate":0.0,"severity_p0_pct":0.0,"doc_gaps_found":0,"doc_gaps_fixed":0,"cycle_time_mins":0,"worktree_branch":"","merge_commit":""}
+   ```
+
+   Use `date -u +%Y-%m-%dT%H:%M:%SZ` for the timestamp. Append the assembled line ONCE with `echo '<full-record>' >> "$METRICS/skill-runs.jsonl"` via Bash — never append a partial row then mutate it.
+
+4. Copy the batch tracker to archive:
+
+   ```bash
+   cp /tmp/batch-tracker-<FIRST-CARD-ID>.md "$METRICS/archive/"
+   ```
+
+5. Note in tracker: `## Metrics Log: WRITTEN (run_id: batch-<FIRST-CARD-ID>)`
+
+6. **Session token telemetry (ONLY when `STATS=true`)** — if the run was invoked with `-stats` / `--stats`:
+
+   Measure REAL per-role token + wall-clock cost by post-processing the session transcripts (zero model-token cost — runs in Bash). Invoke:
+
+   ```bash
+   node .framework/framework/scripts/analyze-session-tokens.js \
+     --skill new --run-id "batch-<FIRST-CARD-ID>" --out-dir "$METRICS"
+   ```
+
+   The script reads `$CLAUDE_CODE_SESSION_ID` from the environment and derives the transcript paths itself (do NOT pass `--session` / `--project-dir` — those are test-only overrides). It writes a human-readable breakdown to `$METRICS/sessions/batch-<FIRST-CARD-ID>.md` and prints a summary plus a final `TELEMETRY_JSON=<json>` line.
+
+   Parse the `TELEMETRY_JSON=` line and add a `"cost"` key (holding that JSON object: `by_role` + `totals` + `run_wall_ms`) to the in-memory record from step 3, then **append the complete record ONCE** to `$METRICS/skill-runs.jsonl` (this is the deferred single atomic append from step 3 — there is NO already-written row to rewrite, so JSONL semantics stay intact: exactly one line per `run_id`). If the script printed `stats: SKIPPED (...)` instead, set `"cost":{"skipped":"<reason>"}` and append the single record. Echo the script's summary to the user so they see the per-role breakdown.
+
+**If `$METRICS/skill-runs.jsonl` does not exist**: create it first with `mkdir -p "$METRICS" && touch "$METRICS/skill-runs.jsonl"`.
+**If batch tracker is missing or unreadable**: log "Metrics Log: SKIPPED (tracker not found)" and proceed without blocking.
+**This phase is NON-BLOCKING** — if it fails for any reason, do not abort the run. The `-stats` step in particular is best-effort: the script is fail-safe (always exits 0), so never let it block the commit.

package/framework/.claude/skills/new/references/production-readiness.md

@@ -0,0 +1,232 @@
+<!-- Modulo on-demand di /new — NON un file installato a sé. Caricato via Read dalla § "Routing" del SKILL.md core. -->
+
+> **Modulo `/new`** — eseguilo, poi torna al core § "Routing" per la fase successiva. I `§ "..."` (Context economy, Context Tracking, Trivial-card fast-lane, Risk-signal detector, Fix Application Log) vivono nel **core SKILL.md**.
+
+## Phase 7 — Production Readiness Checklist
+
+After Phase 6 completes (or after the final summary report if Phase 6 is deferred), present a **Production Readiness Checklist** — a clear list of all manual or infrastructure actions required to launch the implemented changes in production.
+
+### 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 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.
+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. **[DB Indexes — firestore]** Deploy composite indexes
+   - Command: `firebase deploy --only firestore:indexes`
+   - Reason: New compound query on `<entity>` (`<field1>` + `<field2>` + `<field3>`)
+
+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 <provider> dashboard)
+
+3. **[DB Access Rules — firestore]** Deploy updated security rules
+   - Command: `firebase deploy --only firestore:rules`
+   - 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
+- No database migrations
+- No DNS changes
+
+### Notes
+- 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
+
+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). 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 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 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 |
+
+**Auto-execution procedure:**
+
+1. For each auto-executable item detected, run the command immediately.
+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. **[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.
+
+### 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).
+
+**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
+   cat firestore.indexes.json | python3 -c "
+   import sys, json
+   data = json.load(sys.stdin)
+   groups = sorted(set(i['collectionGroup'] for i in data.get('indexes', [])))
+   print('\n'.join(groups))
+   "
+   ```
+
+2. **Check index states** via Firestore REST API for each collection group:
+   ```bash
+   TOKEN=$(gcloud auth print-access-token) && \
+   for CG in <collection_groups>; do
+     curl -s "https://firestore.googleapis.com/v1/projects/<your-firebase-project>/databases/(default)/collectionGroups/$CG/indexes" \
+       -H "Authorization: Bearer $TOKEN" 2>/dev/null
+   done | python3 -c "
+   import sys, json, re
+   raw = sys.stdin.read()
+   creating = []
+   for match in re.finditer(r'\{[^{}]*\"indexes\"[^}]*\}', raw, re.DOTALL):
+       try:
+           data = json.loads(match.group())
+           for idx in data.get('indexes', []):
+               state = idx.get('state', 'UNKNOWN')
+               if state != 'READY':
+                   fields = ' + '.join(f.get('fieldPath','?') for f in idx.get('fields',[]))
+                   cg = idx.get('name','').split('/collectionGroups/')[1].split('/')[0] if '/collectionGroups/' in idx.get('name','') else '?'
+                   creating.append(f'{state}: {cg} ({fields})')
+       except: pass
+   if creating:
+       print(f'NOT_READY ({len(creating)} indexes still building):')
+       for c in creating: print(f'  - {c}')
+   else:
+       print('ALL_READY')
+   "
+   ```
+
+3. **Poll if NOT_READY** — re-check every 30 seconds, up to 10 retries (5 minutes max).
+
+4. **Final status**:
+   - 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. **[DB Indexes — <stack.database>]** Deploy indexes
+   - Command: <stack-matched command>
+   - Deploy: SUCCESS (took 45s)
+   - Verification: ALL READY (5/5) | BUILDING (2 still creating after 5min) | ERROR (details)
+```
+
+### Rules
+
+- **Always present this section**, even if the checklist is empty (in that case, state "No infrastructure changes required — deploy is code-only").
+- Order items by **deployment sequence** (items that must happen first go first — e.g., indexes before code deploy, env vars before code deploy).
+- For each item, include the **reason** (which card/feature requires it) and the **exact command or UI path**.
+- If an item is **uncertain** (e.g., you suspect a new index might be needed but aren't sure), mark it with `VERIFY` and explain what to check.
+- **Update the tracker** with the full checklist under a new `## Production Readiness` section.
+
+---