baldart 4.2.2 → 4.3.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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).
 
+## [4.3.0] - 2026-06-03
+
+**`/new` skips its pre-flight cross-card Codex check when `/prd` already audited the same batch jointly and nothing drifted since.** The `/prd` Step 6.6 holistic audit (4-agent team + Codex adversarial pass, 6.6d) already reviews the full card set for `files_likely_touched` conflicts, dependency shadows, implicit ordering, and shared-state mutation — the *exact* lens of `/new` Step 3d's cross-card check. Running Step 3d unconditionally re-paid that Codex call on every multi-card batch, even when implementing the freshly-audited PRD set with zero intervening change. Now the audit phase **stamps provenance** on each card (`metadata.holistic_audit`: `audited_at` + `audited_commit` + `audited_set`), and `/new` Step 3d evaluates a four-condition skip: provenance present (S1), batch jointly audited (S2), batch ⊆ audited set (S3), and no commit touched the batch's claimed paths since the audit baseline (S4). All four hold → SKIP (logged, non-decision); any fails → RUN as before. **MINOR** (new card-template field + new conditional capability; NOT a `baldart.config.yml` key — `metadata.holistic_audit` is a backlog-card field written by the audit phase).
+
+> **Why.** The two checks are not "different lenses" — Step 3d's `FILE_CONFLICT / IMPLICIT_DEP / ORDER_RISK / STATE_MUTATION` questions map 1:1 onto 6.6d's `attack_surface`, run over the same card set + adjacent cards. The only residual value of re-running at implementation time is the two cases the authoring-time audit *cannot* have covered: (a) the `/new` batch is not the audited set (a subset, or cards stitched from separate PRD runs), or (b) the codebase drifted on the claimed paths between audit and implementation. The gate isolates exactly those two cases via provenance + a `git log <audited_commit>..<trunk> -- <claimed_paths>` drift probe, and **degrades safely in every direction** — missing/partial provenance, mismatched sets, empty/unreachable commit, or any git error all fall through to RUN, never to a silent skip. Aligns with the standing "data-driven over arbitrary thresholds" and "no silent confirmation gates for non-decisions" principles: the skip is deterministic and auditable (the RUN/SKIP reason is logged in the tracker), not a heuristic.
+
+### Added
+
+- **`framework/templates/feature-card.template.yml`** — documents the optional `metadata.holistic_audit` block (`audited_at` / `audited_commit` / `audited_set`), written by the audit phase (not at authoring), consumed by `/new` Step 3d.
+
+### Changed
+
+- **`framework/.claude/skills/prd/references/audit-phase.md`** — Step 6.9 (Apply Findings to Cards) adds a "Holistic-audit provenance stamp" subsection: capture three run-level values once (`audited_at` = UTC now, `audited_commit` = `git merge-base HEAD <trunk>` fork point, `audited_set` = sorted jointly-audited card IDs) and write `metadata.holistic_audit` on each card. New per-card workflow step (was 5 steps, now 6). Fail-safe contract: the stamp is an optimization hint, never a gate — never blocks the PRD if it can't be written.
+- **`framework/.claude/skills/new/SKILL.md`** — Step 3d replaces the flat "Skip if batch has only 1 card" with a provenance-aware four-condition skip decision (S1 provenance present, S2 jointly audited, S3 batch ⊆ audited set, S4 no drift on claimed paths via `git log <audited_commit>..<trunk> -- <paths>`). SKIP logs `SKIPPED (provenance) — …` and proceeds with the file-ownership map unchanged; otherwise RUN with the reason recorded. Tracker `## Cross-Card Conflicts (Codex)` placeholder updated to note the possible skip. Every ambiguity falls through to RUN.
+
 ## [4.2.2] - 2026-06-03
 
 **`/new` Phase 0 stops blocking on framework-owned noise: telemetry-only dirty trees and `baldart update`/subtree commits are auto-ignored.** Every batch tripped its own Phase 0 gates: (1) the dirty-tree gate fired on `${paths.metrics}/archive/batch-tracker-*.md` + `skill-runs.jsonl` + `sessions/` — telemetry that Phase 8 writes *after* the merge and never commits, so the next batch always saw a "dirty" tree and forced a stash/commit decision; (2) the divergence gate fired on `.framework/` subtree commits + the `[CHORE] baldart update …` chore, treating expected framework-management divergence as the FEAT-0006 orphan-commit pattern and forcing a push/cherry-pick decision. Both gates now **partition the working tree / the ahead-commits before prompting** and surface only genuine in-progress user work. The FEAT-0006 protection is intact — real orphan commits and real uncommitted work still gate. **PATCH** (bugfix to an existing gate's classification; no new agent/skill/template, no `baldart.config.yml` key — `paths.metrics` already exists).

package/VERSION

@@ -1 +1 @@
-4.2.2
+4.3.0

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

@@ -100,7 +100,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 |------|--------------------------|
 
 ## Cross-Card Conflicts (Codex)
-(pending — runs during worktree setup for batches > 1 card)
+(pending — for batches > 1 card; may be SKIPPED if the batch was already audited jointly by /prd Step 6.6 with no drift since — see Step 3d skip decision)
 
 ## Issues & Flags
 (none yet)
@@ -276,7 +276,24 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 
    > **Why**: a non-Anthropic frontier model (Codex, via `codex-companion.mjs`) reviews the full card batch for cross-card conflicts that per-card plan-auditor checks cannot detect (each plan-auditor sees only one card).
 
-   **Skip if**: batch has only 1 card (no cross-card conflicts possible).
+   **Skip decision (provenance-aware — since v4.3.0).** The `/prd` Step 6.6 holistic audit (4-agent team + Codex adversarial pass) ALREADY ran this exact cross-card analysis over the cards when they were authored — its Codex prompt covers `files_likely_touched` conflicts, dependency shadows, implicit ordering, and shared-state mutation across the whole audited set. Re-running here is only worth the Codex call when **something changed between that audit and now**. Compute the skip before launching:
+
+   1. **Always skip** if the batch has only 1 card (no cross-card conflicts possible).
+   2. Otherwise, read `metadata.holistic_audit` from every card in the batch and evaluate the four SKIP conditions — **all must hold**:
+      - **S1 — provenance present**: every batch card has `metadata.holistic_audit` with non-empty `audited_at`, `audited_commit`, and `audited_set`. (Missing/partial on any card ⇒ condition fails.)
+      - **S2 — jointly audited**: all batch cards carry the **same** `audited_set` value (they were reviewed together, not stitched from separate PRD runs).
+      - **S3 — batch ⊆ audited set**: every batch card ID is present in that shared `audited_set`.
+      - **S4 — no drift on the claimed paths**: no commit touched any path the batch claims, between the audit baseline and the trunk this run grounds on. Using the shared `audited_commit` (`$AC`) and the batch's union of claimed/touched paths from the file-ownership map (step 3b, `$BATCH_PATHS`):
+        ```bash
+        # empty AC, or AC not in history → treat as drift (do NOT skip)
+        DRIFT="$(git -C "$MAIN" log --oneline "$AC".."$TRUNK" -- $BATCH_PATHS 2>/dev/null || echo "DRIFT")"
+        ```
+        S4 holds **iff** `$AC` is non-empty AND the command succeeds AND `$DRIFT` is empty.
+   3. **If S1–S4 all hold → SKIP the Codex cross-card check.** Log in the tracker under `## Cross-Card Conflicts (Codex)`:
+      `SKIPPED (provenance) — batch ⊆ holistic_audit set <audited_set>, no drift since <AC short sha> (audited <audited_at>)`. Then proceed to step 4 with the file-ownership map unchanged. Do NOT present anything to the user — this is a non-decision.
+   4. **Otherwise → RUN the check** (launch below). Record WHY in the same tracker section so the choice is auditable: `RUN — <reason>` where reason is one of `no/partial provenance` (S1) · `batch spans multiple audit sets` (S2) · `batch not a subset of audited set` (S3) · `drift on <first drifted path>` (S4).
+
+   `$MAIN` and `$TRUNK` are the same variables resolved in Phase 0. This gate degrades safely in every direction: any missing signal, ambiguity, or git error falls through to RUN — never to a silent skip.
 
    Launch via `Bash` with `run_in_background: true` and `timeout: 300000`:
 

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

@@ -473,14 +473,43 @@ Applied N findings to structured fields (H high, M medium).
 Manual review needed: [list [MANUAL] items, or "none"].
 ```
 
+### Holistic-audit provenance stamp (since v4.3.0) — consumed by `/new` Step 3d
+
+This audit (the 4-agent team + Codex adversarial pass of Step 6.6) IS the holistic cross-card review: Step 6.6d's Codex prompt already covers `files_likely_touched … conflicting across cards`, dependency shadows, implicit ordering, and shared-state mutation across the whole `${CARD_PATHS}` set. To let `/new` AVOID re-running its own pre-flight cross-card Codex check (Step 3d) when nothing has changed since this audit, stamp each audited card with a machine-readable provenance block.
+
+**Capture three run-level values ONCE** (same for every card in this audit run):
+
+```bash
+HOLISTIC_AUDITED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+# Grounding baseline = the trunk commit the cards were authored against.
+# The PRD docs worktree was forked from trunk, so the fork point is that baseline.
+HOLISTIC_AUDITED_COMMIT="$(git merge-base HEAD "${git.trunk_branch}" 2>/dev/null || git rev-parse "${git.trunk_branch}" 2>/dev/null || echo "")"
+# audited_set = sorted card IDs reviewed JOINTLY in this run (the Step 6.6d ${CARD_PATHS} set).
+```
+
+`audited_set` is the **same list for every card** — it records which cards were considered together, so `/new` can verify its batch is a subset of one coherent jointly-audited set (not a mix of cards audited in separate PRD runs).
+
+Write under `metadata.holistic_audit` on each card (additive — never overwrite other `metadata` keys):
+
+```yaml
+metadata:
+  holistic_audit:
+    audited_at: "<HOLISTIC_AUDITED_AT>"
+    audited_commit: "<HOLISTIC_AUDITED_COMMIT>"   # "" if git unavailable → /new treats as drift (runs Step 3d)
+    audited_set: ["FEAT-XXXX-01", "FEAT-XXXX-02", ...]   # sorted; the joint cross-card scope
+```
+
+> **Fail-safe contract**: this block is an OPTIMIZATION hint, never a gate. If it is absent, partial, or has an empty `audited_commit`, `/new` Step 3d simply RUNS as before — there is no correctness risk, only a redundant Codex pass. Do NOT block the PRD if the stamp can't be written.
+
 ### Per-card workflow
 
 For each card:
 1. Read persisted report → collect all findings for this card ID.
 2. Read current card YAML.
 3. Apply HIGH findings first, then MEDIUM, then write audit trail.
-4. Write updated card YAML.
-5. Re-read to verify edits landed correctly.
+4. Write the `metadata.holistic_audit` provenance block (see "Holistic-audit provenance stamp" above) using the run-level values captured once.
+5. Write updated card YAML.
+6. Re-read to verify edits landed correctly.
 
 **Note**: No separate commit here — the validation-phase.md Step 7 handles committing all PRD artifacts together.
 

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

@@ -130,3 +130,13 @@ metadata:
   # 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
+  # holistic_audit — provenance of the /prd Step 6.6 cross-model holistic audit
+  # (4-agent team + Codex adversarial pass). WRITTEN BY the audit phase, not at
+  # authoring — leave absent when creating a card by hand. /new reads it to decide
+  # whether its pre-flight cross-card check (Step 3d) can be skipped because the
+  # batch was already audited jointly AND nothing changed since. Fail-safe: if
+  # absent/partial, /new just runs Step 3d (no correctness risk).
+  # holistic_audit:
+  #   audited_at: ""        # ISO-8601-UTC of the audit
+  #   audited_commit: ""    # trunk commit the cards were grounded against
+  #   audited_set: []       # card IDs audited jointly (the cross-card scope)

package/package.json

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