baldart 3.41.0 → 4.0.0

package/framework/.claude/commands/codexreview.md

@@ -21,8 +21,12 @@ If `/codexreview` is invoked **without card IDs**, infer them from context in th
 2. **In-progress backlog cards**: run `grep -rl "status: IN_PROGRESS" /backlog/*.yml` and read their `id` fields.
 3. **Current branch name**: parse the branch name (e.g. `feat/FEAT-0123-slug` → `FEAT-0123`).
 
+The patterns above (`FEAT-`, `BUG-`, `TECH-`, `UI-`) are BALDART's default taxonomy; consumer
+projects with a different convention (e.g. JIRA-style `PROJ-123`) should extend the match list to
+their own prefixes. If 0 IDs match, fall through to `AskUserQuestion` rather than guessing.
+
 Deduplicate, then:
-- If exactly 1–3 cards are inferred: announce them ("Inferred cards from context: FEAT-XXXX, FEAT-YYYY") and proceed.
+- If exactly 1–3 cards are inferred: announce them ("Inferred cards from context: FEAT-XXXX, FEAT-YYYY") and proceed. [DESIGN-CHOICE: cap at 3 to prevent token-budget saturation in a single orchestrator context; larger batch should be split into separate runs]
 - If 0 or more than 3 are inferred: ask the user to specify which cards to review using `AskUserQuestion`. Do not guess.
 
 ---
@@ -52,17 +56,17 @@ For the (single) card in scope, check for `/tmp/codexreview-lean-<CARD-ID>.json`
   - `arch_baseline_path` readable → **skip Step 1** (do NOT re-spawn `codebase-architect`); load the
     baseline from that file and ALSO attach the `diff_summary_path` contents to every review agent so
     they see what changed against the existing-architecture map. *(A1)*
-  - `skip_doc_reviewer: true` → **omit agent #4 (`doc-reviewer`)** in Step 2. Doc concerns are covered
+  - `skip_doc_reviewer: true` → **omit agent #3 (`doc-reviewer`)** in Step 2. Doc concerns are covered
     by `/new` Phase 3, which runs `doc-reviewer` (with the spec/docs-drift lens) on the same diff
     immediately before this gate. *(A2)*
-  - `profile: "light"` → ALSO omit agent #2 (`qa-sentinel`), agent #3 (`api-perf-cost-auditor`),
-    **agent #5 (Codex adversarial)** (since v3.38.0), and **skip Step 3.5 (CoVe)**. Only agent #1
+  - `profile: "light"` → ALSO omit agent #2 (`api-perf-cost-auditor`),
+    **agent #4 (Codex adversarial)** (since v3.38.0), and **skip Step 3.5 (CoVe)**. Only agent #1
     (`code-reviewer`) and the Step 3 false-positive gate run. The Codex adversarial pass is the
     prerogative of `full` and of the final cross-check — every `light` card's code is still reviewed
     by Codex adversarial at the unconditional Final-review FULL gate before merge (see `/new`
     "Final-review FULL gate"), and any high-risk diff trigger escalates the card to `full` per-card
     so it gets Codex adversarial immediately. *(B1)*
-  - `profile: "full"` (or missing) → full agent set incl. Codex adversarial, minus #4 if `skip_doc_reviewer`.
+  - `profile: "full"` (or missing) → full agent set incl. Codex adversarial, minus #3 if `skip_doc_reviewer`.
 
 **Invariant**: lean mode NEVER suppresses the run itself — at minimum `code-reviewer` + the Step 3
 FP-gate execute on every card (`light`); `full` additionally runs the Codex adversarial pass. If the
@@ -83,9 +87,9 @@ For each provided card ID:
    - `acceptance_criteria`
    - `entrypoints`
    - `files_likely_touched` (if present)
-3. Gather git evidence:
+3. Gather git evidence (resolve `<trunk>` from `git.trunk_branch` in `baldart.config.yml`; if absent, autodetect the integration branch):
    - `git log --oneline --all --grep "<CARD-ID>"`
-   - `git diff --name-only develop...HEAD` (fallback to `git diff --name-only HEAD~1`)
+   - `git diff --name-only <trunk>...HEAD` (fallback to `git diff --name-only HEAD~1`)
 4. Build `review_scope_files` as union of card-indicated files + git-touched files.
 5. Persist scope context to `/tmp/codexreview-<CARD-ID>-scope.md`.
 
@@ -131,29 +135,32 @@ Defaults per agent (override only if scope is unusually small/large):
 | Agent | file_reads | bash_calls | search_docs |
 |---|---|---|---|
 | `code-reviewer` | 15 | 25 | 5 |
-| `qa-sentinel` | 15 | 25 | 5 |
 | `api-perf-cost-auditor` | 15 | 25 | 5 |
 | `doc-reviewer` | 20 | 25 | 8 |
 
-Codex (agent #5, via Bash + companion script) does NOT receive this block — it manages its own context.
+Codex (agent #4, via Bash + companion script) does NOT receive this block — it manages its own context.
 
 ### Agents
 
 Launch these agents in parallel for each card:
 
 1. `code-reviewer` — functional bugs, regressions, logic flaws
-2. `qa-sentinel` — reproducibility, edge cases, testing gaps
-3. `api-perf-cost-auditor` — API/data/performance/cost defects
-4. `doc-reviewer` — spec/docs drift that can cause incorrect behavior
-5. **Codex (GPT-5.5)** — adversarial review via `codex-companion.mjs`
+2. `api-perf-cost-auditor` — API/data/performance/cost defects
+3. `doc-reviewer` — spec/docs drift that can cause incorrect behavior
+4. **Codex (a non-Anthropic frontier reviewer, e.g. `gpt-5`)** — adversarial review via `codex-companion.mjs`
+
+> `qa-sentinel` is intentionally NOT in this set. It is a mechanical gate-runner (lint / tsc / tests /
+> build / audit → PASS/FAIL); it cannot read source files or perform the source-level review this step
+> requires. Gate-running for the card happens in the QA flow, not in this deep-review parallel set.
 
 > **Lean agent set (Step -0.5)**: when a contract file is active, launch only the agents the resolved
-> mode permits — `skip_doc_reviewer` omits #4; `profile: light` additionally omits #2, #3, AND **#5
-> (Codex adversarial)** (since v3.38.0). At `light`, only agent #1 (`code-reviewer`) launches (+ the
-> Step 3 FP-gate). At `full` (and in full mode with no contract file), launch all five (Codex #5
-> included). The standalone `/codexreview <CARD-ID>` invocation (no contract) is always full.
+> mode permits — `skip_doc_reviewer` omits #3 (`doc-reviewer`); `profile: light` additionally omits #2
+> (`api-perf-cost-auditor`) AND **#4 (Codex adversarial)** (since v3.38.0). At `light`, only agent #1
+> (`code-reviewer`) launches (+ the Step 3 FP-gate). At `full` (and in full mode with no contract
+> file), launch all four (Codex #4 included). The standalone `/codexreview <CARD-ID>` invocation (no
+> contract) is always full.
 
-**Codex invocation rules (agent #5):**
+**Codex invocation rules (agent #4):**
 
 Codex is NOT invoked via the `Agent` tool (the `codex:codex-rescue` subagent_type is not registered in the harness). Instead, invoke it directly with Bash:
 
@@ -164,12 +171,21 @@ node "$PLUGIN_ROOT/scripts/codex-companion.mjs" task \
   --wait
 ```
 
-- Use `--wait` to get results synchronously in the same turn.
+- **Path-safety (MUST)**: the `<file list>` is built from `review_scope_files` (card-indicated +
+  git-touched paths). Before interpolating any path into a shell command, pass each path as a
+  separate, properly-quoted argument — never splice an unvalidated, unquoted path into a command
+  string, and never feed the list through `xargs -I{} git show HEAD:{}` (an unquoted `{}` lets a
+  crafted path inject shell metacharacters). When you must read a tree blob, validate the path
+  against `review_scope_files` and quote it (`git show "HEAD:$path"` with `$path` from a vetted
+  array), or read the working-tree file directly with the `Read` tool.
+- Use `--wait` to get results synchronously in the same turn. Run this Codex call ONLY as a
+  foreground `--wait` invocation — do NOT also pass it to `run_in_background` in the same call;
+  `--wait` already blocks for the synchronous result and the two are mutually exclusive.
 - The `PLUGIN_ROOT` discovery handles version upgrades automatically.
 - Capture stdout verbatim in a `codex_raw_output` field, then normalize each Codex finding into the schema.
-- If Codex exits non-zero or the script is not found, log `CODEX_UNAVAILABLE` with the error and continue with the remaining 4 agents. Do not block the run.
+- If Codex exits non-zero or the script is not found, log `CODEX_UNAVAILABLE` with the error and continue with the remaining 3 agents. Do not block the run.
 
-Each agent (1–4) MUST return findings using this schema:
+Each agent (1–3) MUST return findings using this schema:
 
 - `finding_id`: unique ID (`<CARD-ID>-F###`)
 - `title`
@@ -182,7 +198,7 @@ Each agent (1–4) MUST return findings using this schema:
 - `risk_if_unfixed`
 - `minimal_fix_direction`
 
-Codex findings (agent #5) are normalized into the same schema after capture, with `source: "codex"` appended.
+Codex findings (agent #4) are normalized into the same schema after capture, with `source: "codex"` appended.
 
 No generic findings allowed. Every finding must have concrete evidence.
 
@@ -190,10 +206,10 @@ No generic findings allowed. Every finding must have concrete evidence.
 
 ## Step 3 — Mandatory False-Positive Check
 
-Collect all findings from Step 2 — including normalized Codex findings — into a single pool, then run independent validation in parallel for each finding:
+Collect all findings from Step 2 — including normalized Codex findings — into a single pool, then run independent validation in parallel for each finding. Both validators must be **code-aware** (able to read the source and reason about the claimed behavior) — `qa-sentinel` is excluded here because it is a mechanical gate-runner that cannot read source files:
 
-1. Static validator: `code-reviewer` or `codebase-architect`
-2. Behavior validator: `qa-sentinel`
+1. Path/pattern validator: `codebase-architect` — confirms the cited file/symbol exists and the structural claim holds.
+2. Behavior validator: `code-reviewer` — reads the cited code and confirms or refutes the claimed runtime behavior.
 
 Classify each finding strictly as:
 
@@ -215,8 +231,8 @@ Only `VERIFIED` findings can be reported as bugs.
 
 After Step 3 false-positive gating, the orchestrator runs ONE additional Chain-of-Verification pass on the consolidated VERIFIED pool. This catches two failure modes the per-agent CoVe doesn't:
 
-1. **Cross-agent echo allucination**: 2+ agents independently produce the same hallucinated finding (e.g. wrong file path that "looks plausible") and reinforce each other through Step 3 cross-validation.
-2. **Undetected ripple effects**: a VERIFIED finding is real but its scope is wider than reported (e.g. "missing withAuth on route X" is true, but routes Y and Z have the same gap and weren't flagged).
+1. **Cross-agent echo hallucination**: 2+ agents independently produce the same hallucinated finding (e.g. wrong file path that "looks plausible") and reinforce each other through Step 3 cross-validation.
+2. **Undetected ripple effects**: a VERIFIED finding is real but its scope is wider than reported (e.g. "an authz guard is missing on route X" is true, but routes Y and Z have the same gap and weren't flagged).
 
 ### Procedure
 
@@ -224,7 +240,7 @@ For each VERIFIED finding in the pool, generate ONE residual verification questi
 
 > "If this finding is true, which OTHER file or function SHOULD also be modified and is not currently flagged?"
 
-Execute targeted grep/read commands (max 10 total across all findings — shared budget). Two outcomes:
+Execute targeted grep/read commands (max 10 total across all findings — shared budget [DESIGN-CHOICE: limits CoVe cost to a bounded constant regardless of finding count; findings not reached are tagged `cove_unverified`]). Two outcomes:
 
 - **Verification expands the finding**: append a `ripple_files: [<paths>]` field to the finding's evidence, and bump severity by one level if ≥2 ripple files found. Note: `[ripple-expanded]` tag.
 - **Verification disproves the finding**: cross-validators were both fooled. Move the finding to `Hallucinated findings dropped (post-validation CoVe)` with the falsifying evidence quoted. Do NOT report as a bug.
@@ -239,7 +255,10 @@ Execute targeted grep/read commands (max 10 total across all findings — shared
 
 ## Step 4 — Final Report
 
-Write one consolidated report per run to `/tmp/codexreview-report-<TIMESTAMP>.md`.
+Write one consolidated report per run to `/tmp/codexreview-report-<CARD-ID>-<RUN-ID>.md`, where
+`<RUN-ID>` is a full timestamp-plus-uuid (e.g. `20260601T142233Z-a1b2c3`) — a date-only name collides
+across same-day concurrent runs. Return this exact path to the caller; downstream consumers must use
+the returned path, never reconstruct it via wildcard/timestamp guess.
 
 Report structure:
 

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.