baldart 3.41.0 → 4.0.1

package/framework/.claude/commands/new.md

@@ -1,334 +1,33 @@
 ---
-description: Orchestrate a team of specialized agents to implement one or more backlog cards end-to-end, with code review, doc review, and commit for each.
+description: Orchestrate a team of specialized agents to implement one or more backlog cards end-to-end, with code review, doc review, QA, and commit for each.
 allowed-tools: Bash, Task, Edit, Write, Read, Grep, Glob, WebFetch, WebSearch, TaskCreate, TaskUpdate, TaskList, TaskGet, TeamCreate, TeamDelete, SendMessage
 ---
 
-You are the **backlog orchestrator**. When the user invokes `/new <CARD-IDS>`, you create and coordinate specialized agents to implement the listed backlog cards. You NEVER write production code yourself — you only orchestrate.
-
-Parse the card IDs from the arguments. Cards can be specified as:
-- Space-separated: `GLOB-001 GLOB-002 GLOB-003`
-- Hyphen-range: `GLOB-001-GLOB-008` (expands to all cards in range)
-- Comma-separated: `GLOB-001, GLOB-002, GLOB-003`
-- **Epic expansion (`-full` / `--full`)**: `/new <PARENT-ID> -full` (e.g., `/new FEAT-005 -full`) expands to ALL children of the parent epic with **NO questions asked**. Children = YAML files in `backlog/` whose filename starts with `<PARENT-ID>-` (e.g., `FEAT-005-1.yml`, `FEAT-005-2.yml`) OR whose `group.parent` field equals `<PARENT-ID>`. The parent epic card itself is excluded. Sort by `group.sequence` ASC, fallback to lexicographic ID. The flag is batch-scoped (`/new FEAT-005 FEAT-008 -full` expands both). If a parent has zero children → HALT and report. All children share `group.parent`, so the existing worktree logic groups them into ONE worktree under the parent's `git_strategy.branch`.
-
-If no card IDs are provided, ask the user which cards to implement.
-
----
-
-## Context Tracking (CRITICAL)
-
-You MUST maintain a **persistent tracking file** at `/tmp/batch-tracker-<FIRST-CARD-ID>.md` throughout the entire batch run (e.g., `/tmp/batch-tracker-FEAT-0396.md`). Use the **first card ID** from the batch as the suffix. This ensures multiple `/new` sessions running in parallel terminals (e.g., one per worktree) do NOT conflict.
-
-This file is your single source of truth — if your context gets compacted or you lose track of what happened, **re-read this file first**.
-
-### Tracking file format
-
-At batch start, create `/tmp/batch-tracker-<FIRST-CARD-ID>.md` with:
-
-```markdown
-# Batch Run: [CARD-IDS]
-Started: [timestamp]
-Total cards: [N]
-
-## Worktree
-Branch: [feat/FEAT-XXXX-slug]
-Path: [../wt/feat-FEAT-XXXX-slug]
-Group parent: [FEAT-XXXX or "standalone"]
-Main repo: [/absolute/path/to/main/repo]
-
-## Card Queue
-- [ ] CARD-001 — [title from backlog]
-- [ ] CARD-002 — [title from backlog]
-...
-
-## Completed Cards
-(none yet)
-
-## Current Card
-(none — starting pre-flight)
-
-## Issues & Flags
-(none yet)
-```
-
-### Update rules
-
-- **Before starting a card**: move it to `## Current Card` with phase info.
-- **After each phase**: update the current card's phase status in the tracker.
-- **After completing a card**: move it from `Current Card` to `## Completed Cards` with:
-  - Commit hash
-  - One-line summary of what was implemented
-  - Any flags/issues found
-  - Code review result (pass/fail + fixes)
-  - Doc review result (pass/fail + what was added)
-  - Test results (new + existing count, pass/fail)
-  - Fix cycles count
-  - QA result (profile used: skip/light/balanced/deep | verdict: PASS/FAIL/SKIP | confidence % | findings: N blockers, N majors)
-  - QA findings file (e.g. `/qa/FEAT-XXXX.md` or "skipped")
-- **When blocked**: log the blocker in `## Issues & Flags`.
-- **On context recovery**: if you ever feel lost or after context compaction, IMMEDIATELY read your tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`) to restore your state.
-
----
-
-## Pre-flight (once)
-
-1. Read each backlog card from `/backlog/*.yml` to understand scope and dependencies.
-2. Check `docs/references/project-status.md` for current state.
-3. Determine which cards can run in **parallel** (no shared files/components) vs which must be **sequential** (dependencies or overlapping paths). Use `group.sequence` to determine execution order within a group.
-4. **Worktree grouping** (automated from card metadata — do NOT ask the user if metadata is complete):
-   a. Check each card's `group.parent` field.
-   b. If all cards share the same `group.parent` → ONE worktree, branch derived from parent card.
-   c. If cards have no `group.parent` but share a common ID prefix (e.g., `FEAT-0396-*`) → suggest grouping to user.
-   d. If cards are unrelated (no shared parent, no common prefix) → each gets its own worktree.
-   e. Read the parent/epic card for `git_strategy.branch` if set; otherwise derive branch name per AGENTS.md naming convention: `feat/<PARENT-ID>-<slug>`.
-   f. If `group.parent` is set AND the parent card has `git_strategy.branch` → use it directly, NO questions asked.
-5. **Create worktree(s)**:
-   a. Ensure the base branch is clean: `git checkout <base-branch> && git pull`.
-   b. For each worktree group:
-      - Create: `git worktree add ../wt/<branch-name> -b <branch-name>`.
-      - Copy environment files if needed: `cp <main-repo>/.env.local <worktree-path>/.env.local 2>/dev/null`.
-      - Install dependencies in worktree (e.g., `npm install`, `pip install`, etc.).
-      - Verify build in worktree.
-      - If build fails → STOP, report, do NOT continue.
-   c. Switch working directory to worktree for all subsequent operations.
-6. Create the tracking file `/tmp/batch-tracker-<FIRST-CARD-ID>.md` (include worktree path and branch name).
-7. Create a task list to track progress across all cards.
-
----
-
-## QA Profile Selector
-
-Before Phase 3.5, determine the review profile for each card. **Primary path (since v3.38.0): READ the card's `review_profile` field** (`skip|light|balanced|deep`), computed deterministically by the PRD `prd-card-writer` (SSOT). Use it verbatim — do NOT recompute. **Fallback (legacy cards with no field): compute** from the table below (the SKILL.md version is authoritative — keep in sync with `prd-card-writer.md § Rule C`).
-
-| Profile | When to apply (fallback compute only) |
-|---------|--------------|
-| **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** | 5 or fewer files likely touched — AND no HIGH-risk keywords in paths/areas — OR card type is `bugfix` with small scope — OR pure refactoring with no logic change |
-| **BALANCED** | Default for all `feature` / `enhancement` cards not matching LIGHT or DEEP rules |
-| **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 — OR API contract changed |
-
-When in doubt between LIGHT and BALANCED, use BALANCED. When in doubt between BALANCED and DEEP, use DEEP.
-
----
-
-## Per-card pipeline
-
-For each card, execute these phases in order:
-
-### Phase 1 — Claim & Context
-1. **Update tracker**: set current card, phase = "1-claim".
-2. Set the card status to `IN_PROGRESS` and assign yourself.
-3. Update `docs/references/project-status.md` Active Code Context.
-4. Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation.
-5. **Update tracker**: phase = "1-claim DONE", log codebase-architect key findings (1-2 lines).
-
-### Phase 2 — Implement (self-healing, up to 3 retries)
-6. **Update tracker**: phase = "2-implement".
-7. Create an agent team of **coder** agent (or appropriate specialist from `.claude/agents/REGISTRY.md`) to implement the card. Pass the codebase-architect findings as context.
-8. Run tests (if they exist), build, and lint to verify everything passes.
-9. **If any check fails**: spawn a **fix agent** with the error output and the list of files touched. Do NOT ask the user — just fix and re-run. Fix the code, not the tests (unless the test itself is wrong). Repeat up to **3 times**.
-10. If still failing after 3 retries, log the failure in `## Issues & Flags` and ask the user before continuing.
-11. **Update tracker**: phase = "2-implement DONE", log files changed (short list), retry count, and test results (new + existing test count, pass/fail).
-
-### Phase 3 — Review (parallel read-only audits, then single fix pass)
-12. **Update tracker**: phase = "3-review".
-13. Invoke the **code-reviewer** agent and the **doc-reviewer** agent **in parallel** as **read-only audits** — each collects findings into a list WITHOUT making any changes.
-14. **Merge all findings** from both reviews into a single consolidated fix list.
-15. If findings exist, invoke the **coder** agent once to apply **ALL fixes sequentially in one pass**.
-16. Run tests (if they exist), lint, and build once at the end to verify everything passes. If any check fails, apply the same self-healing retry loop (up to 3 times, no user prompt).
-17. **Update tracker**: phase = "3-review DONE", log review findings count, fixes applied, and test results.
-
-### Phase 3.5 — QA Validation
-
-18. **Update tracker**: phase = "3.5-qa".
-19. **Select QA profile**: read the card's `review_profile` field (use verbatim); only compute from the QA Profile Selector table above when the field is absent (legacy card). Log the chosen profile and source (`from card` | `computed`) in the tracker (1 line).
-20. **If profile is SKIP**: log "QA skipped — [reason]" in the tracker. Proceed to Phase 4.
-21. **If profile is LIGHT, BALANCED, or DEEP**: invoke the **`qa-sentinel`** agent (subagent_type: `qa-sentinel`) via Task tool with the following context:
-
-    ```
-    Run QA on card <CARD-ID> at the tier dictated by the QA profile (do NOT default to FULL).
-
-    Context:
-    - Worktree path: <worktree-path>
-    - Branch: <branch-name>
-    - Latest commit: <hash> <message>
-    - Changed files: <list from implementation phase>
-    - Risk level: [Low | Medium | High]
-    - QA profile selected: [light | balanced | deep]
-
-    Profile → tier mapping:
-    - light    → SCOPED (related tests only)
-    - balanced → SCOPED (related tests only; risk drift in the diff may escalate to FULL)
-    - deep     → FULL (whole suite + audit + e2e smoke suite if configured)
-    Only path-based risk drift (auth/permission/payment/schema/migration/API contract) escalates;
-    file count never does.
-
-    After running all gates, write the complete QA Report to:
-    /qa/<CARD-ID>.md
-
-    Use the findings file format defined in /qa/README.md.
-    Return your full structured QA Report and final verdict.
-    ```
-
-22. **Read qa-sentinel's output.** Verify the findings file was written to `/qa/<CARD-ID>.md`.
-23. **If QA verdict is FAIL**:
-    - Spawn the **coder** agent to fix all BLOCKER findings (pass it the findings file path + list of blockers). Do NOT ask the user.
-    - After coder fixes, re-invoke `qa-sentinel` in the same mode to re-validate. Repeat up to **2 times**.
-    - If still FAIL after 2 retries: log in `## Issues & Flags` and **ask the user** whether to proceed or stop.
-    - The commit in Phase 4 MUST NOT happen until QA verdict is PASS (or user explicitly overrides).
-24. **Update tracker**: phase = "3.5-qa DONE", log: profile used, verdict (PASS/FAIL/SKIP), confidence %, findings count (blockers/majors/minors), findings file path.
-
-### Phase 4 — Commit (in worktree, NO merge yet)
-25. **Update tracker**: phase = "4-commit".
-26. Stage and commit **all changes together** in the worktree using format `[CARD-ID] Brief description` (MUST per AGENTS.md). Include all relevant files — implementation, review fixes, QA-driven fixes, and doc updates in a single commit. Do NOT merge or push yet — that happens post-batch.
-    - **IMPORTANT — atomic staging**: Always combine `git add` and `git commit` in a single chained command so staging is never lost on retry:
-      ```
-      cd <worktree-path> && git add -A && git commit -m "[CARD-ID] Brief description"
-      ```
-    - **If commit fails** (e.g., lint-staged or pre-commit hook error): re-run the **same full command** (`git add -A && git commit ...`). Never run `git commit` alone after a failure — the staging area may have been altered by lint-staged auto-fixes.
-27. Update the backlog card: set status to `DONE`, add implementation notes.
-28. **Update tracker**: move card to `## Completed Cards` with commit hash, summary, and flags.
-
-### Sub-agent failure protocol
-- If any sub-agent **crashes or errors** during any phase: log the failure in the tracker, **attempt the work yourself directly**, and note it in the final report.
-- Never block the pipeline waiting for a failed agent — recover and continue.
-
-### Phase 5 — Context Clean & Continue
-29. Archive the card from Active Code Context in `docs/references/project-status.md`.
-30. **CONTEXT PURGE**: After updating the tracker, deliberately forget the implementation details of this card. From this point forward, you should NOT reference any code, file contents, or review details from this card — only the summary in the tracker. If you need to recall what happened, read the tracker file. This keeps your working context lean for the next card.
-31. **Update tracker**: clear `## Current Card`, move to next pending card.
-32. Move to the next card.
-
----
-
-## Final review (after all cards)
-
-Once ALL cards are committed in the worktree:
-1. **Read the tracker file** to get the full picture of what was implemented.
-2. Invoke the **code-reviewer** agent and the **doc-reviewer** agent **in parallel** for a holistic review across all implementations — check for inconsistencies, duplicated logic, integration gaps between cards, and missing documentation.
-3. **Persist findings to file.** Write the consolidated final review findings to `/tmp/batch-final-review-<FIRST-CARD-ID>.md` using the Write tool. This ensures findings survive context compaction. If context is compacted before fixes are applied, re-read from this file.
-4. **Auto-apply fixes.** If findings exist, invoke the **coder** agent once to apply ALL fixes in a single pass (same pattern as Phase 3 per-card review). Run tests (if they exist), lint, and build to verify. If any check fails, apply the self-healing retry loop (up to 3 times).
-5. Run build one final time in the worktree to confirm stability.
-6. **Update tracker** with final review results (findings count, fixes applied, build status).
-7. **Proceed to Phase 6** (post-batch merge & cleanup).
-8. Present a **single summary report** to the user per card (and a batch summary at the end):
-   - **Files changed** (short list per card)
-   - **Test results** (new tests + existing tests count, pass rate at each iteration)
-   - **Build/lint status** (pass + retry count if any)
-   - **Fix cycles** (total number of self-healing retries across phases)
-   - **Review findings fixed** (count and brief description)
-   - **QA result** (profile: skip/light/balanced/deep | verdict: PASS/FAIL/SKIP | confidence % | findings: N blockers, N majors, N minors | findings file path)
-   - **Issues needing user attention** (anything unresolved, partially wired, or flagged)
-   - **Commit hashes** (from tracker)
-   - **Merge commit hash** (from Phase 6)
-   - **Worktree cleanup status** (success/failed)
-   - Overall implementation status
-9. **Proceed to Phase 7** (production readiness checklist).
-
----
-
-## Phase 6 — Post-batch merge & cleanup
-
-After the final review passes AND all cards are committed in the worktree:
-
-### 6a. Push feature branch
-1. From the worktree directory: `git push -u origin <branch-name>`.
-
-### 6b. Merge into base branch
-2. Switch to main repo: `cd <main-repo-path>` (read from tracker `## Worktree > Main repo`).
-3. `git checkout <base-branch> && git pull`.
-4. `git merge --no-ff <branch-name>`.
-5. **If merge conflicts** → STOP immediately, report conflicting files to user. Do NOT auto-resolve.
-
-### 6c. Verify post-merge integrity
-6. Run build — must pass.
-7. Run tests — must pass (if tests exist).
-8. **If anything fails** → STOP, report. Do NOT delete branch or worktree.
-
-### 6d. Push base branch
-9. `git push`.
-
-### 6e. Cleanup
-10. Delete local branch: `git branch -d <branch-name>`.
-11. Delete remote branch: `git push origin --delete <branch-name>`.
-12. Remove worktree: `git worktree remove ../wt/<branch-name>`.
-13. Prune: `git worktree prune`.
-14. **Update tracker**: log merge commit hash, cleanup status.
-
-### Fail-safe rules
-- Never force push.
-- Never delete a branch before successful merge.
-- Never remove a worktree before confirming the base branch is stable.
-- Stop execution immediately if any command fails.
-
----
-
-## 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:
-
-| Category | Detection signal | Action to report |
-|----------|-----------------|------------------|
-| **DB indexes** | New/modified index config files, or code using new compound queries | Deploy indexes (e.g., `firebase deploy --only firestore:indexes`, run migrations, etc.) |
-| **DB security/access rules** | New/modified access rule files | Deploy updated rules |
-| **Environment variables** | New `process.env.*` references not present in the base branch, new entries in `.env.example` | Add to hosting platform settings (list each var name) |
-| **Scheduled functions / cron** | New or modified cron/scheduled functions | Deploy functions |
-| **Database migrations** | New collections/tables, field renames, data backfills referenced in code or ADRs | Run migration script (specify which) |
-| **New API endpoints** | New route files | 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 |
-| **DNS / domain changes** | Hosting or redirect config changes | Update DNS records or hosting domain settings |
-| **Package upgrades with breaking changes** | Major version bumps in dependency files | Verify compatibility; check migration guides |
-
-### Output format
-
-Present the checklist as a clearly formatted section in the final report:
-
-```
-## Production Readiness Checklist
-
-### Required before deploy
-1. **[Category]** Description
-   - Command or UI path
-   - Reason: which card/feature requires it
-
-### No action needed
-- (list categories that don't apply)
-
-### Notes
-- Any timing dependencies (e.g., "deploy indexes BEFORE releasing code")
-- Any environment variables that must be set BEFORE deployment
-```
-
-### 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).
-- For each item, include the **reason** (which card/feature requires it) and the **exact command or UI path**.
-- If an item is **uncertain**, mark it with `VERIFY` and explain what to check.
-- **Update the tracker** with the full checklist under a new `## Production Readiness` section.
-
----
-
-## Context recovery protocol
-
-If at ANY point you are unsure where you are in the batch:
-1. Read your tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`)
-2. Check `## Current Card` — if populated, resume that card at the listed phase.
-3. Check `## Card Queue` — find the next unchecked card.
-4. Check `## Completed Cards` — know what's already done (don't redo).
-5. Continue the pipeline from where you left off.
-
----
-
-## Parallelism rules
-
-- Cards with non-overlapping `claimed_paths` CAN run in parallel.
-- Cards with shared dependencies or overlapping files MUST run sequentially.
-- Code review and doc review for the same card run as **parallel read-only audits**, then fixes are applied in a single sequential pass.
-- Different cards' implementations CAN run in parallel if independent.
-- When running parallel agents, expect "file modified since read" errors on shared files (like the backlog yml) — handle gracefully.
-- When running in parallel, each parallel branch updates the tracker with its own card — use card ID as prefix to avoid conflicts.
+# /new — redirect to the `new` skill (SSOT)
+
+> **This command is a thin entry point. It contains NO orchestration logic of its own.**
+> The authoritative, maintained `/new` pipeline lives in the **`new` skill**:
+> `framework/.claude/skills/new/SKILL.md` (installed as `.claude/skills/new/`).
+>
+> A previous version of this file carried a full, hand-maintained copy of the pipeline.
+> That copy silently drifted from the skill (it omitted the BLOCKING Phase 0 hygiene,
+> AC-Closure, Simplify, E2E, Pre-Merge Codex, post-merge hygiene, and Metrics phases,
+> ran `code-reviewer` where the skill forbids it, and referenced a QA README
+> file that does not exist). To eliminate the dual-source-of-truth, the logic now lives in
+> exactly one place. **Do not re-introduce pipeline steps here.**
+
+When the user invokes `/new <CARD-IDS>`:
+
+1. **Load and follow the `new` skill** (`skills/new/SKILL.md`) verbatim, passing the
+   user's arguments through unchanged (card IDs, ranges, `-full` epic expansion, etc.).
+2. The skill owns the entire flow: Phase 0 (workspace hygiene pre-flight) → Phase 1–8
+   (claim, implement, completeness, AC-closure, simplify, E2E, doc review, QA,
+   pre-merge Codex gate, commit, batch review, merge, reconciliation, post-merge
+   hygiene, production-readiness, metrics), including the `review_profile`-driven QA
+   tiering and all worktree-isolation safety rules.
+3. Do not duplicate or summarise the skill's steps in this file — read them from the
+   skill so they cannot diverge.
+
+If the `new` skill is not available in the current install, that is an install/integrity
+error: surface it (`new skill not found — run \`npx baldart\` to repair the install`)
+rather than falling back to an inline pipeline.

package/framework/.claude/commands/qa.md

@@ -27,7 +27,7 @@ You are the **QA Orchestrator**. When the user invokes `/qa [profile] [--card FE
 
 ## Step 1 — Gather Context (always)
 
-Run these in parallel:
+Run these in parallel (resolve `<base-branch>` from `git.trunk_branch` in `baldart.config.yml`; if absent, autodetect the integration branch):
 - `git rev-parse --abbrev-ref HEAD`
 - `git log -1 --pretty="%h %s"`
 - `git diff --name-only <base-branch>...HEAD 2>/dev/null || git diff --name-only HEAD~1`
@@ -38,7 +38,7 @@ Run these in parallel:
 - **MEDIUM**: everything else (feature modules, components, utilities)
 - **LOW**: only `.md`, `.yml`, style/CSS, test files, config — no logic changes
 
-If risk is HIGH and profile is LIGHT, warn the user: "Risk level is HIGH — consider running `/qa balanced` or `/qa deep` for better coverage."
+If risk is HIGH and profile is LIGHT, warn the user: "Risk level is HIGH — consider running `/qa balanced` or `/qa deep` for better coverage." This warning is advisory; the run proceeds, but the caveat MUST be carried into the QA Verdict block (Step 7) so a HIGH-risk LIGHT pass is never silently equivalent to a full one. (For per-card test depth in `/new`, the card's `review_profile` value governs scope — `review_profile` is computed by prd-card-writer (Rule C); see prd-card-writer.md for the criteria.)
 
 ---
 
@@ -98,7 +98,7 @@ Write the initial file:
 
 ## Step 3 — Execute Profile
 
-### LIGHT — Fast confidence (<3 min target)
+### LIGHT — Fast confidence (<3 min target [DESIGN-CHOICE: scoped to lint + type-check + related tests only; sufficient for low-risk or doc-only diffs])
 
 Run directly in this session (no sub-agents):
 
@@ -118,16 +118,16 @@ No findings file required. Present final verdict immediately.
 
 ### BALANCED — Solid validation (default)
 
-**Decide on parallelization first:**
-- If 3+ clearly independent risk tracks exist (e.g., auth + payments + UI, or unit + integration + DB) → use the parallel agent strategy below.
-- Otherwise → invoke a single `qa-sentinel` agent.
+qa-sentinel is a **mechanical gate-runner** (lint / tsc / scoped-or-full tests / build / `npm audit`):
+it returns PASS/FAIL + a gate table + confidence. It does NOT read source files, exercise flows, run
+a dev server, or do collateral-impact analysis. Behavioral / collateral / dev-server work in BALANCED
+belongs to the e2e and code-aware reviewers, not to qa-sentinel.
 
-**Single-agent path:**
-
-Invoke `qa-sentinel` via Task tool:
+Invoke `qa-sentinel` via Task tool to run the gates:
 
 ```
-Run QA on the current changeset at the tier dictated by the QA profile below (do NOT default to FULL).
+Run the mechanical QA gates on the current changeset at the tier dictated by the QA profile below
+(do NOT default to FULL).
 
 Context:
 - Branch: <branch>
@@ -141,21 +141,19 @@ Tier contract: balanced → SCOPED (related tests on touched modules); deep →
 path-based risk drift (auth/permission/payment/schema/migration/API contract in the diff) may
 escalate balanced→FULL.
 
-After completing validation gates (lint, tsc, tests, build, audit):
-1. Start the dev server if appropriate for the change, exercise key flows, and check for server/browser console errors and unexpected 4xx/5xx responses. Focus on flows directly touched by the diff.
-2. Identify collateral impacts on adjacent features not directly in the diff.
-3. Return your full QA Report (all gates + findings).
-
-Findings file to update: /qa/<file>.md
+Run lint, tsc, tests (per tier), build, and (deep) npm audit. Return PASS/FAIL + the gate table +
+confidence. Do NOT read source files, start a dev server, or analyze collateral impact — those are
+out of scope for this agent.
 ```
 
-After `qa-sentinel` completes:
+After `qa-sentinel` returns its PASS/FAIL + gate table:
 - Read its output.
-- Append all findings to `/qa/<file>.md` under the `## Findings` section.
-
-**Parallel-agent path (when warranted):**
+- Append the gate results to `/qa/<file>.md` under the `## Findings` section.
 
-See Step 4 below.
+**Collateral / behavioral coverage (BALANCED):** if the diff touches user-facing flows and you need
+behavioral confidence beyond the gates, use the parallel-agent path below (Step 4) — it routes
+flow-exercising and collateral-impact analysis to the appropriate code-aware / e2e agents rather than
+to qa-sentinel.
 
 ---
 
@@ -172,26 +170,31 @@ Run everything in BALANCED, plus:
 - Use MCP Playwright (if available) to open key flows related to the diff and take screenshots, checking for console errors and visual regressions.
 - Validate: login/auth flow, critical navigation, any flow directly touched by the diff.
 
-Run the e2e pass in parallel with the `qa-sentinel` FULL VALIDATION (launch both as sub-agents simultaneously).
+Run the e2e pass in parallel with the `qa-sentinel` FULL-tier gate run (launch both as sub-agents simultaneously). This inline two-agent launch is the DEEP default; escalate to the team-based strategy (Step 4) ONLY when 3+ clearly independent risk tracks exist [DESIGN-CHOICE: below this threshold, TeamCreate overhead exceeds benefit; two inline Task spawns are sufficient]. A DEEP run with fewer than 3 tracks stays on this inline path and does NOT create a team.
 
 ---
 
 ## Step 4 — Parallel Agent Strategy (Balanced/Deep when warranted)
 
-Use this when 3+ independent tracks exist.
+Use this when 3+ independent tracks exist [DESIGN-CHOICE: same threshold as DEEP inline gate — ensures consistent entry point for team-based parallelism].
 
 Create a team: `TeamCreate` with name `qa-<CARD-or-timestamp>`.
 
 Create tasks:
-- **Task A**: Unit + Lint + TypeScript — `qa-sentinel` quick subset
-- **Task B**: Integration + DB + API contract + Build — `qa-sentinel` full subset
-- **Task C** (Deep only): E2E + UI validation
-- **Task D**: Dev server log inspection + collateral impact analysis on adjacent features
+- **Task A**: Lint + TypeScript + scoped tests — `qa-sentinel` (gate run, SCOPED tier)
+- **Task B**: Full tests + build + audit — `qa-sentinel` (gate run, FULL tier)
+- **Task C** (Deep only): E2E + UI validation — `e2e-review` skill / Playwright
+- **Task D**: Collateral-impact analysis on adjacent features not in the diff — `code-reviewer` (reads source, reasons about ripple)
 
 Spawn agents in parallel (single message, multiple Task tool calls):
-- Agent A: `qa-sentinel`, tasks A + D
+- Agent A: `qa-sentinel`, task A
 - Agent B: `qa-sentinel`, task B
-- Agent C (Deep only): general-purpose agent, task C
+- Agent C (Deep only): run the `e2e-review` skill / Playwright pass for task C
+- Agent D: `code-reviewer`, task D
+
+qa-sentinel runs gates only (tasks A + B); it never receives Task D — collateral-impact analysis
+requires reading source, which qa-sentinel is forbidden from doing. If a named specialist is
+unavailable, surface `CAPABILITY_UNAVAILABLE: <agent>` and halt — never substitute a generic agent.
 
 Each agent sends findings to orchestrator via `SendMessage`. Orchestrator consolidates ALL findings into `/qa/<file>.md`.
 
@@ -220,16 +223,33 @@ After all agents/checks complete, update `/qa/<file>.md` — replace the `## Fin
 
 **Only if BLOCKER or MAJOR findings exist:**
 
-1. Invoke the **coder** agent (subagent_type: `coder`):
-   - Provide: findings file path + instruction to fix all BLOCKERs, fix MAJORs unless they require architectural change, add regression tests for all bug fixes.
-   - Do NOT ask the user — proceed directly.
-
-2. After coder completes:
-   - Re-run LIGHT profile on the fixed files to verify corrections.
-   - Invoke `doc-reviewer` and `code-reviewer` in parallel (read-only audit).
+1. Invoke the **coder** agent (subagent_type: `coder`). The coder has mandatory pre-conditions (it
+   reads a backlog card at startup, sets it IN_PROGRESS, and reads the card's `git_strategy`) and is
+   forbidden from switching branches — so it MUST be given the context it needs:
+   - **Card ID** (the resolved `<CARD-ID>` from Step 0). If Step 0 fell back to a `session-…`
+     timestamp (no card), do NOT auto-invoke the coder — there is no card for it to read. Instead,
+     surface the findings to the user and ask whether to create a card or fix manually.
+   - **Branch**: spawn the coder on the current branch (the one the diff lives on); it stays there.
+   - **Findings file path** + instruction to fix all BLOCKERs, fix MAJORs unless they require
+     architectural change, and add a regression test for every bug fix.
+   - Do NOT ask the user about whether to fix — proceed directly once a card exists.
+
+2. After coder completes, re-verify through proper subagent spawns (so results are written and
+   tracked, never run loose in this orchestrator's context):
+   - Re-invoke `qa-sentinel` (gate run, SCOPED tier) on the fixed files. It writes its
+     PASS/FAIL + gate table to `/qa/<CARD-ID>.md` and returns the structured `QA DONE` signal; the
+     orchestrator does NOT run gates in-session.
+   - Invoke `code-reviewer` (read-only audit) to confirm the fixes are correct. Invoke `doc-reviewer`
+     only if the fix touched documented behavior.
    - For DEEP: also re-run e2e smoke tests to verify UI still passes.
 
-3. Update `/qa/<file>.md` with post-fix results under a new section `## Post-Fix Verification`.
+   > **Avoid double review when embedded in `/new`**: if this `/qa` run is part of `/new`'s pipeline,
+   > `/new`'s `/codexreview` pre-merge gate already runs `code-reviewer` (and `doc-reviewer`) on the
+   > same diff. Do NOT re-run them here in that case — let the `/codexreview` gate be the single
+   > review pass and only re-run the qa-sentinel gates to confirm the fix.
+
+3. Update `/qa/<file>.md` with post-fix results under a new section `## Post-Fix Verification`,
+   including the re-run qa-sentinel verdict and any re-review findings.
 
 ---
 

package/framework/.claude/skills/api-design-principles/SKILL.md

@@ -525,7 +525,7 @@ For deeper analysis beyond design patterns, delegate to the `api-perf-cost-audit
 
 Use the agent when you need:
 - Performance bottleneck analysis
-- Cost efficiency evaluation (Firestore reads/writes, function invocations)
+- Cost efficiency evaluation (datastore reads/writes per `stack.database`, function invocations)
 - Scalability risk assessment
 - Caching strategy recommendations
 - Query optimization analysis
@@ -539,7 +539,7 @@ Task tool:
     Analyze the following API design:
 
     Endpoints: [List endpoints]
-    Database Operations: [Firestore collections/queries]
+    Database Operations: [datastore collections/tables + queries]
     Expected Load: [Users, frequency, patterns]
 
     Provide performance and cost analysis.

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

@@ -47,9 +47,9 @@ See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for th
 2. Classify the bug domain:
    - **UI/Client** → Playwright MCP is primary tool
    - **API/Server** → dev server logs + route handler analysis
-   - **Data/Firestore** → MCP Firestore tools + transaction tracing
-   - **Auth** → authMiddleware.ts + auth error codes
-   - **Build/Deploy** → Vercel logs + build output
+   - **Data/Datastore** → the project's datastore inspection tooling per `stack.database` (e.g. the Firebase MCP for `firestore`, a SQL client for `postgres`/`supabase`, the Mongo shell for `mongodb`) + transaction tracing
+   - **Auth** → the project's auth middleware/guard + auth error codes (per `stack.auth_provider`)
+   - **Build/Deploy** → the deploy platform's logs + build output (per `stack.deployment`, e.g. Vercel)
 3. Launch `codebase-architect` agent to map the affected code paths — do NOT start debugging blind.
    When `features.has_lsp_layer: true` and the symptom names a concrete symbol
    (function/type/handler), `codebase-architect` will use LSP find-references /
@@ -82,10 +82,10 @@ Goal: get a reliable reproduction that you can re-run after fixing.
 3. Check the error propagation pattern: look for `throw new Error(JSON.stringify({code, status, message}))` — this is the domain error contract
 4. Test the endpoint directly if possible (curl or Playwright network capture)
 
-**For data bugs:**
-1. Use `mcp__plugin_firebase_firebase__firestore_get_document` to inspect the document state
-2. Check field values, timestamps, missing fields
-3. If collection query: use `firestore_query_collection` to verify query results
+**For data bugs** (use the inspection tooling matching `stack.database`; the example below is for `firestore` via the Firebase MCP — for SQL stores use a SQL client / `SELECT`, for Mongo use the Mongo shell):
+1. Inspect the record state — e.g. `mcp__plugin_firebase_firebase__firestore_get_document` (Firestore)
+2. Check field/column values, timestamps, missing fields
+3. If a collection/table query is involved: re-run the query against the store (e.g. `firestore_query_collection` for Firestore) to verify results
 
 **Outcome:** a clear, repeatable reproduction OR evidence that the bug is intermittent (in which case, skip to Phase 2 immediately).
 
@@ -109,7 +109,7 @@ console.log(`[DEBUG:reservations] PATCH entry`, { // DEBUG:
 }); // DEBUG:
 ```
 
-For Firestore operations, wrap reads/writes:
+For datastore operations, wrap reads/writes to time them (Firestore shown as the example — use your store's client when `stack.database` differs):
 ```typescript
 const t0 = Date.now(); // DEBUG:
 const snap = await firestore.collection('X').doc(id).get();

package/framework/.claude/skills/bug/references/logging-patterns.md

@@ -79,9 +79,15 @@ grep -rn '// DEBUG:' src/ --include='*.ts' --include='*.tsx'
 
 Remove every line found. Run grep again. Zero results = clean.
 
-## Firestore-Specific Debugging
+## Datastore-Specific Debugging
 
-### Transaction contention
+> The patterns below are illustrated for **Firestore** — apply them only when
+> `stack.database: firestore`. For other stores, use the equivalent primitive
+> (SQL `SERIALIZABLE` retry/`SAVEPOINT` for Postgres/Supabase, Mongo
+> `withTransaction`, etc.). The *principle* (surface silent retries, log the
+> attempt counter, beware emulator-only debug hooks) is datastore-agnostic.
+
+### Transaction contention (Firestore example)
 Firestore retries transactions silently up to 5 times. Only explicit attempt counting surfaces this:
 ```typescript
 let attempt = 0; // DEBUG: