baldart 3.37.0 → 3.38.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.38.0] - 2026-06-01
+
+**The per-card review depth (QA + Codex) is now decided deterministically in the backlog card via a new `review_profile` field, computed once at PRD authoring time — instead of being re-derived heuristically by `/new` at runtime.** This removes the implementing agent's interpretation latitude: the card carries `skip|light|balanced|deep`, `/new` READS it, and only falls back to runtime computation for legacy cards that predate the field. **No new `baldart.config.yml` keys** — this is a backlog-card schema change, propagated end-to-end across templates + card-writer + validation + `/new` in the same release.
+
+> **Why.** Previously the QA Profile Selector (Phase 3.5) and the Codex Review Profile Selector (Phase 3.7) both recomputed the profile inside `/new` from soft signals (title keywords, the self-admittedly-unreliable `files_likely_touched`), so the same card could be reviewed differently depending on the orchestrator's reading. The card already encodes every hard signal needed (`owner_agent`, type, `areas`, `data_fields`, `db_indexes`, `acceptance_criteria`, `estimated_complexity`) — so the decision is now made once, in the card, by the deterministic rules in `prd-card-writer.md § Rule C` (the SSOT).
+
+### Added — `review_profile` card field (deterministic review depth)
+
+- **[framework/.claude/skills/prd/assets/card-template.yml](framework/.claude/skills/prd/assets/card-template.yml)** + **[framework/templates/feature-card.template.yml](framework/templates/feature-card.template.yml)** + **[framework/.claude/skills/prd/assets/epic-template.yml](framework/.claude/skills/prd/assets/epic-template.yml)**: new `review_profile: skip|light|balanced|deep` field. Epics are always `skip` (trackers, no code work). Authors MAY override the computed value by hand.
+- **[framework/.claude/agents/prd-card-writer.md](framework/.claude/agents/prd-card-writer.md)**: new **Rule C** — the canonical mapping table (metadata → profile) and the SSOT for the decision. Added `review_profile` to the required-fields list. `feature`/`enhancement` cards are floored at `balanced` (never `light`).
+- **[framework/.claude/skills/prd/references/validation-phase.md](framework/.claude/skills/prd/references/validation-phase.md)**: Step 6.0 now BLOCKS on a missing/out-of-enum `review_profile` (mirrors the `owner_agent` gate), with a soft WARN+normalize for `feature`-card-`light` violations and epic non-`skip` values.
+- **[framework/.claude/skills/prd/references/backlog-phase.md](framework/.claude/skills/prd/references/backlog-phase.md)**: documents that `prd-card-writer` populates `review_profile`.
+
+### Changed — `/new` reads the field instead of recomputing it
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** (QA Profile Selector): primary path now READS `review_profile` from the card verbatim; the existing rule table is demoted to a **legacy-card fallback** with an explicit "keep in sync with `prd-card-writer.md § Rule C` (SSOT)" note.
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** (Phase 3.7 Step C.0): the Codex profile derives from the card's `review_profile` (`skip`/`light` → Codex `light`, `balanced`/`deep` → Codex `full`). New **escalation-only invariant**: the Step A high-risk diff detector can only promote `light` → `full` (a risk surfaced at implementation time the authored profile didn't anticipate), never downgrade `full` → `light`. The card's `review_profile` is the deterministic floor; the diff detector is the safety net on top.
+- **[framework/.claude/commands/new.md](framework/.claude/commands/new.md)**: thin mirror updated to the read-from-card primary path with compute-fallback.
+
+### Changed — `light` profile no longer runs the per-card Codex adversarial pass
+
+- **[framework/.claude/commands/codexreview.md](framework/.claude/commands/codexreview.md)** (Step -0.5) + **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** (Phase 3.7 Step C.0, Team D.4b): at `profile: light`, `/codexreview` now omits agent #5 (Codex adversarial) in addition to qa-sentinel + api-perf-cost-auditor + Step 3.5 CoVe. **`light` per-card = `code-reviewer` + the false-positive gate only.** The Codex adversarial review becomes the prerogative of `full` and of the final cross-check.
+- **Why it's safe (BUG-0530 invariant relocated, not dropped)**: the "never miss a blocker on a low-risk path" guarantee is now carried by (1) the **escalation-only** Step A detector — any high-risk path in the actual diff promotes `light` → `full`, so risky code still gets per-card Codex adversarial immediately; and (2) the unconditional **Final-review FULL gate** (v3.37.0), which runs Codex adversarial over the entire batch diff before merge. So every `light` card's code is still Codex-reviewed at least once pre-merge — the pass is paid once at the batch gate instead of N times per-card. Trade-off: a Codex-class finding on a 0-trigger `light` card surfaces at the final gate rather than per-card (later fix-cycle, still pre-merge).
+- **Revert**: re-add agent #5 to the `light` branch of `/codexreview` Step -0.5.
+
+### Backward compatibility
+
+- **Non-breaking**: backlogs authored before v3.38.0 have no `review_profile`. `/new` silently falls back to the runtime rule table (logging `computed — review_profile absent`), so existing cards run exactly as before. New PRD-generated cards get the field automatically.
+
+## [3.37.1] - 2026-06-01
+
+**`/prd` Step 7 merge is fully seamless — auto merge + worktree cleanup with zero end-of-session questions; the user is asked ONLY for conflicts `mw-docs` genuinely cannot auto-resolve.** Fixes a drift between the `/prd` `validation-phase.md` and the real `worktree-manager mw-docs` behaviour that made the skill over-ask. No new `baldart.config.yml` keys.
+
+### Fixed — `/prd` no longer over-asks at merge time
+
+- **[framework/.claude/skills/prd/references/validation-phase.md](framework/.claude/skills/prd/references/validation-phase.md)**: the cross-PRD-collision note and the Step 7 conflict-resolution table claimed structured registries (`project-status.md`, `ssot-registry.md`, …) "abort the rebase and ask for manual resolution". That contradicted `worktree-manager` `mw-docs`, which actually strips markers + runs a structural validation and only aborts when the validation fails (the rare same-row collision). Aligned both spots to the real behaviour: append-only registries auto-resolve and merge with zero questions; escalation happens **only** on a genuinely unresolvable conflict (code/test/fixture, or a structured registry whose strip+validate failed).
+- **[framework/.claude/skills/prd/references/validation-phase.md](framework/.claude/skills/prd/references/validation-phase.md)** (Step 7 step 9): reinforced "no confirmation prompt" — explicitly forbids the "vuoi che mergi e pulisca il worktree?" pre-emptive gate. Merge **and** cleanup run automatically; the model lets `mw-docs` run and only surfaces what it actually reports as unresolvable, instead of asking "just in case".
+
 ## [3.37.0] - 2026-05-30
 
 **Two-tier review for `/new`: fast `light` per-card during the loop, one guaranteed FULL pass over the whole batch before merge.** This activates the dormant v3.35.0 Review Profile Selector AND re-introduces an unconditional final full review — together they cut tokens/wall-clock on low-risk cards *without* weakening the merge gate. **No new `baldart.config.yml` keys** — both are changes inside the skill, so the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.37.0
+3.38.0

package/framework/.claude/agents/prd-card-writer.md

@@ -155,6 +155,40 @@ files and one file would be torn between two cards), prefer a single
 assign `ui-expert` to a mixed card. The dispatcher's specialist routing
 breaks down when scope is mixed.
 
+### Rule C — Compute `review_profile` on every child card (SSOT — deterministic)
+
+Every child card MUST set `review_profile` to exactly one of:
+
+```
+skip | light | balanced | deep
+```
+
+This field materializes the per-card review DEPTH **at authoring time**, so the
+`/new` orchestrator READS it instead of re-deriving it heuristically at runtime.
+The single field drives BOTH the QA depth (`/new` Phase 3.5) and the Codex review
+profile (`/new` Phase 3.7 — `skip`/`light` → Codex `light`, `balanced`/`deep` →
+Codex `full`). **This table is the Single Source of Truth**; the fallback table in
+`framework/.claude/skills/new/SKILL.md § QA Profile Selector` exists only for legacy
+cards that predate this field and MUST stay in sync with the rules below.
+
+Apply the **first matching rule** (priority order — top wins):
+
+| Profile | When to assign |
+|---------|----------------|
+| **DEEP** | ANY of: `areas` includes both `api` AND `data` — OR title/scope/areas touch `auth`, `payment`, `permission`, `schema`, `migration`, `cron`, `webhook`, `transaction` — OR `data_fields` has ≥3 entries with `status: new` or `status: modified` — OR `db_indexes` present (legacy `firestore_indexes` too) — OR acceptance criteria count > 5 — OR `estimated_complexity: HIGH` — OR API contract changed |
+| **LIGHT** | Card is a `bugfix` or `refactor` — AND ≤3 files in `files_likely_touched` — AND none of the DEEP high-risk keywords/areas apply. **NEVER for `feature` or `enhancement` cards.** |
+| **SKIP** | Card is `docs`, `chore`, or `config` — OR all `files_likely_touched` are `.md`/non-API `.yml`/CSS with zero logic files — OR a pure-cosmetic card (typo/rename/copy/wording/style) with no code areas |
+| **BALANCED** | Default for everything else — ALL `feature`/`enhancement` cards not matching DEEP, plus any `bugfix`/`refactor` with >3 files or breadth that isn't DEEP |
+
+**Critical**: `feature` and `enhancement` cards are ALWAYS `balanced` minimum — never
+`light`. When in doubt between `balanced` and `deep`, choose `deep`. `files_likely_touched`
+counts are advisory only — never downgrade a feature card below `balanced` because the
+file count looks small. **Epic cards** always use `review_profile: skip` (no code work).
+
+The human author MAY override the computed value by editing the card YAML — e.g. to
+force `deep` on a card they consider sensitive. Honor any explicit value already present;
+only compute when the field is empty.
+
 ## Card Atomicity Rules
 
 Cards MUST be as atomic as possible to enable parallel execution:
@@ -284,6 +318,7 @@ Every card MUST include ALL fields from the template:
 - `definition_of_done` (checklist including doc invariants)
 - `depends_on` / `blocks` (card IDs)
 - `estimated_complexity`
+- `review_profile` (`skip`|`light`|`balanced`|`deep` — computed via Rule C, or honored if pre-set)
 - `files_likely_touched` (exact paths with NEW/MODIFY)
 - `links.prd` (path to PRD)
 - `links.design` (path to design.html — REQUIRED for any card with UI scope)

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

@@ -55,17 +55,21 @@ For the (single) card in scope, check for `/tmp/codexreview-lean-<CARD-ID>.json`
   - `skip_doc_reviewer: true` → **omit agent #4 (`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`) and agent #3 (`api-perf-cost-auditor`),
-    and **skip Step 3.5 (CoVe)**. Agent #1 (`code-reviewer`), agent #5 (**Codex adversarial**), and
-    the Step 3 false-positive gate ALWAYS run. *(B1)*
-  - `profile: "full"` (or missing) → full agent set, minus #4 if `skip_doc_reviewer`.
-
-**Invariant**: lean mode NEVER suppresses the run itself — at minimum `code-reviewer` + Codex
-adversarial + Step 3 FP-gate execute on every card. If the contract file is malformed/unreadable,
-fall back to **full mode** and note it. **Consume-once**: delete `/tmp/codexreview-lean-<CARD-ID>.json`
+  - `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
+    (`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`.
+
+**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
+contract file is malformed/unreadable, fall back to **full mode** and note it. **Consume-once**: delete `/tmp/codexreview-lean-<CARD-ID>.json`
 immediately after parsing it, so a later standalone `/codexreview <CARD-ID>` on the same card never
 inherits a stale lean contract from a prior `/new` run. Record the resolved mode in the Step 4 report
-`Method` section, e.g. `lean: profile=light, architect=reused, doc-reviewer=skipped(Phase 3), cove=skipped`.
+`Method` section, e.g. `lean: profile=light, architect=reused, doc-reviewer=skipped(Phase 3), codex=skipped(light), cove=skipped`.
 
 ---
 
@@ -144,8 +148,10 @@ Launch these agents in parallel for each card:
 5. **Codex (GPT-5.5)** — adversarial review via `codex-companion.mjs`
 
 > **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 and #3. Agents
-> #1 (`code-reviewer`) and #5 (Codex) ALWAYS launch. In full mode (no contract file), launch all five.
+> 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.
 
 **Codex invocation rules (agent #5):**
 
@@ -238,7 +244,7 @@ Write one consolidated report per run to `/tmp/codexreview-report-<TIMESTAMP>.md
 Report structure:
 
 1. `Scope Reviewed`
-2. `Method` (agents used + validation flow; note whether Codex was available or `CODEX_UNAVAILABLE`; note whether Step 3.5 CoVe ran fully or hit budget cap; in lean mode, record the resolved contract — `lean: profile=<light|full>, architect=<reused|spawned>, doc-reviewer=<skipped(Phase 3)|run>, cove=<skipped|run>`)
+2. `Method` (agents used + validation flow; note whether Codex was available or `CODEX_UNAVAILABLE`; note whether Step 3.5 CoVe ran fully or hit budget cap; in lean mode, record the resolved contract — `lean: profile=<light|full>, architect=<reused|spawned>, doc-reviewer=<skipped(Phase 3)|run>, codex=<skipped(light)|run>, cove=<skipped|run>`)
 3. `Verified Bugs` (ordered: BLOCKER -> HIGH -> MEDIUM -> LOW; tag findings with `[codex]` if originating from Codex; tag `[ripple-expanded]` if Step 3.5 added `ripple_files`; tag `[cove_unverified]` if Step 3.5 budget exhausted before reaching it)
 4. `Needs Manual Confirmation`
 5. `False Positives Discarded` (with reason)

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

@@ -98,9 +98,9 @@ Main repo: [/absolute/path/to/main/repo]
 
 ## QA Profile Selector
 
-Before Phase 3.5, determine the QA profile for each card by reading its YAML metadata. Use the **first matching rule** (priority order):
+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 |
+| 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 |
@@ -141,7 +141,7 @@ For each card, execute these phases in order:
 ### Phase 3.5 — QA Validation
 
 18. **Update tracker**: phase = "3.5-qa".
-19. **Select QA profile** using the QA Profile Selector table above. Log the chosen profile and rationale in the tracker (1 line).
+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:
 

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

@@ -297,7 +297,21 @@ Main repo: [/absolute/path/to/main/repo]
 
 ## QA Profile Selector
 
-Before Phase 3.5, determine the QA profile for each card by reading its YAML metadata. Use the **first matching rule** (priority order):
+Before Phase 3.5, determine the review profile for each card.
+
+**Primary path (deterministic — since v3.38.0): READ `review_profile` from the card YAML.**
+The PRD `prd-card-writer` computes this field at authoring time (`prd-card-writer.md §
+Rule C` — the SSOT) so the decision is made once, in the card, not re-interpreted here.
+If the card has a `review_profile` ∈ {`skip`, `light`, `balanced`, `deep`}, **use it
+verbatim** — do NOT recompute. Log `profile=<x> (from card)` in the tracker.
+
+**Fallback path (legacy cards only): compute from the table below.** Cards authored before
+v3.38.0 (or manually without the field) have no `review_profile`. Only then, derive it using
+the **first matching rule** (priority order). Log `profile=<x> (computed — review_profile absent)`.
+
+> ⚠️ This fallback table MUST stay in sync with `prd-card-writer.md § Rule C`, which is the
+> SSOT. If you edit the rules, edit both. The two differ only in *when* they run (authoring
+> time vs `/new` runtime), never in *what* they decide.
 
 | Profile | When to apply |
 |---------|--------------|
@@ -1176,7 +1190,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 ### Phase 3.5 — QA Validation
 
 18. **Update tracker**: phase = "3.5-qa".
-19. **Select QA profile** using the QA Profile Selector table above. Log the chosen profile and rationale in the tracker (1 line).
+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 its 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**: SKIP qa-sentinel — Phase 2 step 8 already ran lint/tsc/test/build gates. Log "QA LIGHT skipped — gates already passed in Phase 2" in the tracker. Proceed to Phase 4.
 22. **If profile is BALANCED or DEEP**: invoke the **`qa-sentinel`** agent (subagent_type: `qa-sentinel`) via Task tool with the following context:
@@ -1215,7 +1229,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 **This gate is NON-SKIPPABLE and runs for EVERY card before the Phase 4 commit, no matter what.** A per-card `/codexreview` MUST run BEFORE the Phase 4 commit, regardless of file paths, card type, or perceived risk. The historical conditional High-Risk Path detector is preserved below — but only as a **signal-logging step** to record *which* triggers matched in the tracker. It NEVER suppresses the `/codexreview` invocation. Even if zero triggers match, `/codexreview` runs.
 
-**Rationale**: leaving the gate conditional caused it to be silently skipped on the majority of cards, defeating the AGENTS.md "MUST run BEFORE merge" requirement. The cost of a per-card Codex pass is acceptable; the cost of a missed blocker on a "low-risk" path (BUG-0530-class regressions) is not.
+**Rationale**: leaving the gate conditional caused it to be silently skipped on the majority of cards, defeating the AGENTS.md "MUST run BEFORE merge" requirement. The gate itself is unconditional — what varies is its DEPTH (`light` vs `full`). The protection against a missed blocker on a "low-risk" path (BUG-0530-class regressions) is carried by two mechanisms, not by an always-on per-card Codex pass: (1) the Step A detector escalates any risky diff to `full` per-card, and (2) the unconditional **Final-review FULL gate** runs Codex adversarial over the entire batch diff before merge. So `light` can safely run `code-reviewer` + FP-gate only (since v3.38.0) without weakening the merge gate.
 
 #### Step A — Detect (signal-logging only, NEVER gates the next step)
 
@@ -1276,26 +1290,40 @@ Log the detector output in the tracker for traceability. **This step never short
 
 For EVERY card (no conditional skip — the gate ALWAYS runs; only its DEPTH varies):
 
-0. **Select the review profile (deterministic — Review Profile Selector, since v3.35.0)** from
-   signals ALREADY computed (no new thresholds):
-   - **`light`** ⟺ Step A matched **zero** high-risk triggers **AND** this card's QA profile
-     (Phase 3.5) ∈ {`skip`, `light`}.
-   - **`full`** ⟺ otherwise (any trigger matched, OR QA ∈ {`balanced`, `deep`}).
-
-   `light` is **NOT** a skip: `/codexreview` still runs `code-reviewer` + Codex adversarial + the
-   Step 3 false-positive gate. It drops only the breadth agents (qa-sentinel, api-perf-cost-auditor,
-   doc-reviewer) and Step 3.5 CoVe — exactly the passes that yield ~nothing on a 0-trigger, QA-light
-   diff. The BUG-0530 invariant ("never miss a blocker on a low-risk path") holds because the Codex
-   adversarial pass — the one that catches those — always runs.
-   **ACTIVE since v3.37.0**: the selector above runs as written. Here `light` is an **early-feedback
-   optimization** for the per-card loop — NOT the merge-gate. Safety is guaranteed downstream: since
-   v3.37.0 the **Final review ALWAYS runs a single FULL `/codexreview` over the entire batch diff before
-   merge** (no N=1 skip, no scope reduction — see "Final review → Final-review FULL gate"). So every card
-   reviewed at `light` here still receives a full-depth review before merge; `light` shifts the breadth
-   passes (qa-sentinel, api-perf-cost-auditor, doc-reviewer) + CoVe from the per-card loop to that single
-   final full pass, it does not drop them from the merge gate. The BUG-0530 invariant still holds per-card
-   (Codex adversarial + `code-reviewer` + FP-gate always run in `light`). To make Phase 3.7 always-full
-   again: restore `profile = full` here (the final full gate is independent and stays regardless).
+0. **Select the Codex review profile (deterministic — Review Profile Selector)** by mapping the
+   card's review profile (read from the card's `review_profile` field per the QA Profile Selector
+   above — since v3.38.0; fallback-computed only for legacy cards) and the Step A detector:
+   - **`light`** ⟺ the card's profile ∈ {`skip`, `light`} **AND** Step A matched **zero**
+     high-risk triggers.
+   - **`full`** ⟺ otherwise — i.e. the card's profile ∈ {`balanced`, `deep`}, **OR** any Step A
+     trigger matched.
+
+   **Escalation-only invariant (since v3.38.0)**: the Step A detector runs on the ACTUAL diff and
+   can only ever **escalate** `light` → `full` (a high-risk path surfaced at implementation time
+   that the card's authored profile didn't anticipate). It can NEVER downgrade `full` → `light`.
+   The card's `review_profile` is the deterministic floor; the diff detector is the safety net on
+   top of it.
+
+   `light` is **NOT** a skip: `/codexreview` still runs `code-reviewer` + the Step 3 false-positive
+   gate. **Since v3.38.0 the per-card Codex adversarial pass is NO LONGER run at `light`** — it is the
+   prerogative of `full` and of the final cross-check. `light` drops the Codex adversarial pass AND the
+   breadth agents (qa-sentinel, api-perf-cost-auditor, doc-reviewer) AND Step 3.5 CoVe — leaving exactly
+   `code-reviewer` + FP-gate, the cheap per-card pass that yields the early feedback worth having on a
+   0-trigger, QA-light diff. `full` is unchanged (Codex adversarial + the full agent set, minus the
+   duplicate doc-reviewer).
+   **Where the BUG-0530 invariant now lives.** Pre-v3.38.0 the per-card Codex adversarial was the
+   "never miss a blocker on a low-risk path" guard. Two mechanisms now carry that guarantee instead,
+   so dropping it from `light` is safe:
+   1. **Escalation-only (Step A)** — any high-risk trigger on the ACTUAL diff promotes `light` → `full`,
+      so genuinely risky paths (auth/payment/permission/schema/…) STILL get per-card Codex adversarial.
+      Only a 0-trigger, authored-`light` card defers it.
+   2. **Final-review FULL gate (since v3.37.0)** — the **Final review ALWAYS runs a single FULL
+      `/codexreview` over the entire batch diff before merge** (no N=1 skip, no scope reduction — see
+      "Final review → Final-review FULL gate"), and FULL includes Codex adversarial. So every line of
+      every `light` card receives Codex adversarial at least once before merge.
+   Net effect: `light` per-card = early `code-reviewer` feedback; the Codex adversarial review is paid
+   once, at the final batch gate (or per-card the moment a risk trigger fires). To put per-card Codex
+   back on `light`, re-add agent #5 to the `light` branch of `/codexreview` Step -0.5.
 
    Then dump the card diff (reviewer grounding) and write the lean contract `/codexreview` consumes:
    ```bash
@@ -1316,7 +1344,7 @@ For EVERY card (no conditional skip — the gate ALWAYS runs; only its DEPTH var
    ```
    ## Pre-Merge Codex Review
    - Triggered: unconditional (mandatory pre-merge gate)
-   - Profile: light | full — reason: <triggers=0, qa=light | trigger #N matched | qa=deep>
+   - Profile: light | full — reason: <review_profile=<skip|light|balanced|deep> (from card | computed); triggers=0 | trigger #N matched (escalated light→full)>
    - Matched high-risk triggers: <list from detector, or "none">
    - Action: invoking /codexreview <CARD-ID> (per-card, pre-merge gate; lean contract written)
    ```
@@ -1330,8 +1358,9 @@ For EVERY card (no conditional skip — the gate ALWAYS runs; only its DEPTH var
 
    `/codexreview` Step -0.5 consumes `/tmp/codexreview-lean-<CARD-ID>.json`: reuses the Phase-1
    architecture baseline (no re-spawn), drops the duplicate doc-reviewer, and for `profile: light`
-   also drops qa-sentinel + api-perf-cost-auditor + Step 3.5 CoVe. Codex adversarial + Step 3
-   FP-gate + Step 4 report ALWAYS run. (`full` = standard pipeline minus the duplicate doc-reviewer.)
+   also drops qa-sentinel + api-perf-cost-auditor + **the Codex adversarial pass** + Step 3.5 CoVe
+   (since v3.38.0). `code-reviewer` + Step 3 FP-gate + Step 4 report ALWAYS run. (`full` = standard
+   pipeline incl. Codex adversarial, minus the duplicate doc-reviewer.)
 
 3. **Read the consolidated report** from `/tmp/codexreview-report-<TIMESTAMP>.md`. Extract:
    - Verified BLOCKER count
@@ -2198,11 +2227,11 @@ After ALL agents in the group complete successfully:
 
 3c. **D.3c — Phase 2.6 E2E-Review (per-card)** — For EACH card in the group, honor the existing Gate table (skip when `features.has_e2e_review: false`, backend-only diff per the diff predicate documented in Phase 2.6, or card type `docs`/`chore`/`config`). For cards that pass the gate, invoke `/e2e-review` in programmatic mode with that card's payload. BLOCKING per-card: if `/e2e-review` returns `"blocked"` or `"error"`, surface to the user via the same `AskUserQuestion` documented in Phase 2.6 — do NOT proceed to D.4 with an unresolved card. Skips are logged with the documented gate reason, never with `"time budget"` or similar.
 
-4. **D.4 — QA gate (group)** — Select the HIGHEST QA profile across all cards in the group (e.g., if one card is BALANCED and another is DEEP, use DEEP). Invoke **qa-sentinel** once for the group.
+4. **D.4 — QA gate (group)** — Read each card's `review_profile` field (fallback: compute via the QA Profile Selector table for legacy cards). Select the HIGHEST profile across all cards in the group (e.g., if one card is BALANCED and another is DEEP, use DEEP). Invoke **qa-sentinel** once for the group.
 
 4a. **D.4a — Per-card doc gate (consumes D.2, since v3.35.0)** — Do NOT re-spawn `doc-reviewer`. For EACH card in the group, take that card's doc findings from D.2's per-card-attributed output; if any exist, spawn a targeted fix-coder for that card only. (Previously D.4a re-ran doc-reviewer per card — a duplicate of D.2; collapsed to a single attributed D.2 pass. D.4b's per-card `/codexreview` also skips its doc-reviewer via the lean contract, so doc-review now runs once per group instead of ~3× per card.)
 
-4b. **D.4b — Pre-Merge Codex Review Gate (per-card, MANDATORY — UNCONDITIONAL)** — Invoke `/codexreview` for EACH card in the group, one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path and is non-skippable regardless of file paths or perceived risk. Apply the same fix sub-loop: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and re-run `/codexreview <CARD-ID>` (max 2 retries per card). If still BLOCKER/HIGH after retries, ask the user before proceeding to D.5. The D.5 commits MUST NOT happen until every card in the group has a PASS verdict (or explicit user override via `AskUserQuestion`). Log results in the tracker under `## Pre-Merge Codex Review` per card. **Lean + profile (since v3.35.0)**: before each card's `/codexreview`, apply the same Review Profile Selector and write the same `/tmp/codexreview-lean-<CARD-ID>.json` contract as sequential Phase 3.7 Step C — `arch_baseline_path` pointing at `/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`, `skip_doc_reviewer: true`, and `profile: light|full` from (0 triggers + QA ∈ {skip,light}). LIGHT still runs Codex adversarial + code-reviewer + FP-gate. The Review Profile Selector is **ACTIVE since v3.37.0** — same status as sequential Phase 3.7 Step C above: `light` is per-card early feedback, and the merge-gate safety is the post-batch **Final-review FULL gate** (a single FULL `/codexreview` over the entire batch diff, which team mode reaches via "Post-batch — same as sequential mode"). To make per-card always-full again, restore `profile = full`; the final full gate stays regardless.
+4b. **D.4b — Pre-Merge Codex Review Gate (per-card, MANDATORY — UNCONDITIONAL)** — Invoke `/codexreview` for EACH card in the group, one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path and is non-skippable regardless of file paths or perceived risk. Apply the same fix sub-loop: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and re-run `/codexreview <CARD-ID>` (max 2 retries per card). If still BLOCKER/HIGH after retries, ask the user before proceeding to D.5. The D.5 commits MUST NOT happen until every card in the group has a PASS verdict (or explicit user override via `AskUserQuestion`). Log results in the tracker under `## Pre-Merge Codex Review` per card. **Lean + profile (since v3.35.0)**: before each card's `/codexreview`, apply the same Review Profile Selector and write the same `/tmp/codexreview-lean-<CARD-ID>.json` contract as sequential Phase 3.7 Step C — `arch_baseline_path` pointing at `/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`, `skip_doc_reviewer: true`, and `profile: light|full` derived from the card's `review_profile` (`skip`/`light` → `light`, `balanced`/`deep` → `full`; since v3.38.0 read from the card, not recomputed) — with the same **escalation-only** rule: a Step A high-risk trigger on the actual diff promotes `light` → `full`, never the reverse. LIGHT runs `code-reviewer` + FP-gate only — the per-card **Codex adversarial pass is dropped at `light` since v3.38.0** (prerogative of `full` + the final cross-check). The Review Profile Selector is **ACTIVE since v3.37.0** — same status as sequential Phase 3.7 Step C above: `light` is per-card early feedback, and the merge-gate safety is the post-batch **Final-review FULL gate** (a single FULL `/codexreview` over the entire batch diff, which team mode reaches via "Post-batch — same as sequential mode"). To make per-card always-full again, restore `profile = full`; the final full gate stays regardless.
 
 5. **D.5 — Commit** — One commit per card using explicit staging from the ownership map. **NO stash in worktrees** (stashes are globally shared via `refs/stash` — see Phase 4 WORKTREE COMMIT RULE):
    ```bash

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

@@ -108,6 +108,20 @@ blocks: [{{card IDs}}]
 
 estimated_complexity: {{LOW|MEDIUM|HIGH}}
 
+# review_profile — REQUIRED. Decides the per-card review DEPTH deterministically,
+# at PRD authoring time, so /new READS it instead of re-deriving it at runtime.
+# One field drives BOTH QA depth (Phase 3.5) and the Codex profile (Phase 3.7).
+#   skip     → docs/chore/config or pure-cosmetic cards; no QA/Codex depth needed
+#   light    → bugfix/refactor, ≤3 files, no high-risk areas (NEVER for feature/enhancement)
+#   balanced → default for feature/enhancement, or bugfix/refactor with breadth/risk
+#   deep     → api+data, auth/payment/permission/schema/migration, ≥3 new/modified
+#              data_fields, db_indexes, AC count > 5, or HIGH estimated_complexity
+# Auto-computed by prd-card-writer (§ Review Profile Rules — the SSOT). You MAY
+# override it by hand to force a deeper/shallower review on a specific card.
+# /new maps skip|light → Codex `light`, balanced|deep → Codex `full` (Phase 3.7);
+# a high-risk path in the actual diff can only ESCALATE the Codex profile, never lower it.
+review_profile: {{skip|light|balanced|deep}}
+
 # Parallelization metadata (auto-computed by /prd backlog phase)
 parallel_group: {{N}}          # Layer di esecuzione: 0 = prima, 1 = dopo layer 0, etc.
                                # Card nello stesso gruppo possono girare in parallelo

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

@@ -116,6 +116,11 @@ blocks: []
 
 estimated_complexity: {{LOW|MEDIUM|HIGH}}
 
+# review_profile — epics are trackers with NO code-touching work, so review depth
+# is N/A. Always `skip` (consistent with owner_agent: "" on epics). The real
+# review depth lives on the child cards.
+review_profile: skip
+
 parallel_group: 0
 
 # =============================================================================

package/framework/.claude/skills/prd/references/backlog-phase.md

@@ -216,6 +216,7 @@ The `prd-card-writer` agent owns the entire card writing pipeline:
 - `execution_strategy` block on epic parent card
 - State file update with card list and matrices
 - `env_vars` field: per ogni card che introduce/modifica/rimuove env vars (rilevabile da PRD Section 6 o da requirements che menzionano `process.env`, segreti, API keys, feature flags), popola il campo con `action: new|modified|removed`, `scope`, `required`, `note`. Se la card non tocca env vars, scrivi `env_vars: []`.
+- `review_profile` field: deterministic per-card review depth (`skip|light|balanced|deep`) computed via `prd-card-writer.md § Rule C` from the card's own metadata (type, areas, data_fields, db_indexes, AC count, estimated_complexity). This materializes the review decision at authoring time so `/new` reads it instead of re-deriving it. Epics always get `review_profile: skip`. Honor any explicit author override already present in the YAML.
 
 ### What stays in the main context
 

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -24,7 +24,16 @@ Mark task 5 as `in_progress`.
       - The check is intentionally a soft gate: substrings like "API contract per il mock" or "consumes the auth state from `useAuth()`" are legitimate UI references. The WARN exists to prompt human review, not to block.
       - Exception (no WARN): the marker appears INSIDE a quoted string that explicitly says "consume", "mock", "contract reference", or "exposed by sibling card" — those are UI cards reading an upstream contract, which is expected.
 
-   **Gate**: every card has `owner_agent` in the enum. WARN entries from check (b) are noted in the audit log; user may accept them after review.
+   c. **`review_profile` enum check (BLOCKING)** — read the `review_profile` field on each child card. It MUST equal one of:
+      ```
+      skip | light | balanced | deep
+      ```
+      - **Missing or empty** = **BLOCKER** — the card-writer must compute it via `prd-card-writer.md § Rule C` (the SSOT mapping table). Message: `"Card <ID> has no review_profile — compute it from Rule C (skip|light|balanced|deep) before commit."`
+      - **Out-of-enum value** = **BLOCKER**. Message: `"Card <ID> has review_profile: '<value>' — must be one of {skip, light, balanced, deep}."`
+      - **Consistency WARN (soft)**: a `feature`/`enhancement` card with `review_profile: light` violates Rule C ("never light for feature/enhancement"). Log `"[REVIEW-PROFILE-WARN] Card <ID> is feature/enhancement but review_profile: light — Rule C floors these at balanced."` and bump to `balanced` unless the author left an explicit override note.
+      - **Epics**: `review_profile` MUST be `skip` (trackers have no code work). Any other value = WARN, normalize to `skip`.
+
+   **Gate**: every card has `owner_agent` AND `review_profile` in their enums. WARN entries from checks (b)/(c) are noted in the audit log; user may accept them after review.
 
 1. **Field Name Audit (runs BEFORE audit agents)** — for each generated card:
 
@@ -73,9 +82,13 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    in parallel. The rebase in step 8 below brings the worktree up to the latest
    `origin/develop` BEFORE the merge, so two parallel PRDs ending at the same
    time produce a clean append-only diff in most cases. If the rebase reports
-   conflicts on these two files specifically, the `worktree-manager mw-docs`
-   protocol stops and asks for manual resolution — do NOT auto-strip merge
-   markers on structured files like these.
+   conflicts on these two files, `worktree-manager mw-docs` does **not** ask
+   immediately: it strips the markers ("keep both sides", which on append-only
+   registries is the correct additive result) and then runs a structural
+   validation. The merge proceeds automatically when the validation passes. It
+   escalates to the user **only** in the rare case where both PRDs modified the
+   same row and the validation fails — i.e. a conflict that genuinely cannot be
+   auto-resolved. See `/mw` step 4b "Structured registries" row.
 
 ### Commit (inside the worktree)
 
@@ -110,9 +123,18 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
 ### Merge into develop (worktree-manager mw-docs)
 
 9. **Invoke `worktree-manager` programmatic mw-docs immediately** — no
-   confirmation prompt. The user opted into the full PRD pipeline when they
-   ran `/prd`; chiedere conferma a fine sessione è friction inutile e rompe
-   il "seamless" che è il punto della v3.22.0.
+   confirmation prompt, no "vuoi che mergi e pulisca il worktree?" question.
+   The user opted into the full PRD pipeline when they ran `/prd`; chiedere
+   conferma a fine sessione è friction inutile e rompe il "seamless" che è il
+   punto della v3.22.0. Merge **and** worktree cleanup run automatically.
+
+   **The ONLY thing that stops the automatic merge is a conflict `mw-docs`
+   genuinely cannot auto-resolve** (a code/test conflict, or a structured
+   registry whose strip+validate failed — see step 10). Everything `mw-docs`
+   can auto-resolve (additive docs/YAML/JSONL, append-only registries that pass
+   validation) merges with zero questions. Do NOT pre-empt the merge with a
+   confirmation gate "just in case there might be conflicts" — let `mw-docs`
+   run and only surface what it actually reports as unresolvable.
 
    The merge is recoverable: if something goes wrong post-merge the user can
    `git revert` on develop just like any other commit. The hard-to-reverse
@@ -141,9 +163,10 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    - Conflict auto-resolution table (see `/mw` step 4b): additive docs/yaml and
      append-only `.jsonl` files auto-resolve; **structured registries**
      (`project-status.md`, `ssot-registry.md`, `field-registry.*`,
-     `traceability-matrix.md`, `REGISTRY.md`) abort the rebase and report —
-     these must be resolved manually because blindly stripping markers would
-     corrupt their internal structure.
+     `traceability-matrix.md`, `REGISTRY.md`) are auto-resolved by strip +
+     structural validation, and only abort (escalating to the user) when the
+     validation fails — the rare same-row collision. Code / test / fixture
+     conflicts always abort and escalate.
    - Merge via the configured `git.merge_strategy` (`pr` or `local-push`).
    - Cleanup: `git worktree remove` + `git branch -d` + registry entry removal.
    - Local develop ref sync (only if main repo HEAD is already `develop`).

package/framework/templates/feature-card.template.yml

@@ -123,3 +123,10 @@ metadata:
   created: YYYY-MM-DD
   updated: YYYY-MM-DD
   estimated_effort: ""  # S | M | L | XL
+  # review_profile — decides the per-card review depth deterministically.
+  # /new reads this instead of re-deriving it at runtime; one field drives both
+  # QA depth (Phase 3.5) and the Codex profile (Phase 3.7).
+  #   skip | light | balanced | deep
+  # Auto-computed by prd-card-writer for PRD-generated cards; set it by hand here
+  # when authoring a card manually (omit to let /new fall back to runtime compute).
+  review_profile: ""  # skip | light | balanced | deep

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.37.0",
+  "version": "3.38.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"