baldart 5.4.0 → 5.4.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [5.4.1] - 2026-07-03
+
+**Minimal light lane — the roster for a simple card is now literally: grounding (inline),
+coder, code review, doc review, commit, merge. Nothing else.** Completes v5.4.0 per the
+maintainer's directive ("per cose così semplici voglio due passaggi in croce"): the compact
+lane cut the CARD COUNT; this cuts the per-run AGENT COUNT. FEAT-0067-class run: ~33
+agents → ~7.
+
+- **Per-card doc review at light (single-card batch)**: the light review matrix adds the
+  scoped `doc-reviewer` per-card (review-cycle.md deferral-gate exception) because the
+  Final pass it used to defer to is now skippable.
+- **Final Review skip gate (`final-review.md` § F.0 + `new2.js` `skipFinalLight`)**: ONE
+  light card + zero actionable per-card findings (→ zero fixes applied) → skip F.2–F.5
+  entirely. Honors the v4.56.1 refutation (per-card PRE-fix + final POST-fix are
+  non-redundant) by scoping the skip to runs where there IS no post-fix state; any
+  finding, fix, second card, or degraded reviewer → Final runs as always.
+- **i18n fill spawn cut at light**: the owner briefing instructs the coder to fill every
+  target locale itself; the anti-hardcoded lint + locale-parity gates still enforce.
+- **Production-readiness spawn cut for all-light batches**: no deployable surface exists
+  by Rule C (no migrations/indexes/cron/schema) — the agent only ever reported zero items.
+- `check-new-parity.mjs` rule 18 locks the prose↔workflow lockstep for every cut.
+- Skills: `new` 2.2.0 · `new2` 1.6.0.
+
+Codex parity: portable (prose modules are the cross-tool SSOT; `new2.js` Claude-only by design).
+
 ## [5.4.0] - 2026-07-03
 
 **Elastic pipeline — `/prd`+`/new` compress to the minimum for trivial features and

package/VERSION

@@ -1 +1 @@
-5.4.0
+5.4.1

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

@@ -2,6 +2,17 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.2.0 — 2026-07-03 (framework v5.4.1)
+
+- **Minimal light lane — roster cut to the core four.** A single light card now runs:
+  grounding-inline (step 2d) → owner → code review (Codex-light/code-reviewer) → scoped
+  doc-reviewer per-card (review-cycle deferral exception) → commit → merge. Cut for the
+  lane: i18n fill spawn (7c — owner fills locales inline, lint gate enforces), Final
+  Review when the per-card review is clean (final-review.md § F.0 Minimal-light skip
+  gate — POST-fix verification with zero fixes is vacuous; any finding/fix/second card →
+  Final runs), production-readiness spawn for all-light batches (no deployable surface
+  by Rule C). Guarded by check-new-parity rule 18.
+
 ## 2.1.0 — 2026-07-03 (framework v5.4.0)
 
 - **Light-lane inline grounding (implement.md step 2d).** A `review_profile: light` card

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

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 2.1.0
+version: 2.2.0
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards
   end-to-end inside a dedicated worktree, with code review, doc review, QA, and

package/framework/.claude/skills/new/references/final-review.md

@@ -42,6 +42,19 @@ Once ALL cards are committed in the worktree:
 > A single card has no cross-card surface, so a finder's per-card pass and its final pass are genuinely
 > the same review.
 
+### Step F.0 — Minimal-light skip gate (v5.4.1)
+
+When the batch has exactly ONE committed card AND it is `review_profile: light` AND its
+per-card review surfaced ZERO actionable findings (no blocks, no scope-expansion → no fix
+pass was applied), **SKIP the entire Final Review** (F.2–F.5) and proceed to merge. The
+Final pass exists for POST-fix verification and cross-card surface (v4.56.1 — per-card
+PRE-fix + final POST-fix are non-redundant); with zero fixes and zero cross-card surface,
+both reasons are absent — and doc coverage already ran per-card (the single-card light
+review matrix includes the scoped doc-reviewer instead of deferring here, see
+review-cycle.md § Deferral gate). Any finding on the card, any fix applied, any second
+card, or any degraded reviewer → run the Final Review as written below. Log
+`final-review: SKIPPED (single light card, clean per-card review — nothing post-fix to verify)`.
+
 ### Step F.1 — Resolve scope
 
 (All cards are committed; the batch now enters Final Review. No visibility emission — the internal tracker is the only state surface, see SKILL.md § "State surface — the tracker only". Record the Final-Review start/finish in the tracker only.)

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

@@ -500,7 +500,7 @@
    - **Grounding (cheap `grep`, like the Phase-1 plan-auditor grounding):** every cited source symbol/class MUST appear in `mockups/_src/` (`grep -rF "<symbol>" <prd_dir>/<slug>/mockups/_src/`), and every cited registry primitive MUST exist in the registry (`grep` `${paths.design_system}/INDEX.md` / `components/`). A symbol that is not in the source, or a primitive that is not in the registry, means a fabricated declaration → reject + re-spawn (do NOT pass it to the gates). Log `design-source: grounded` or `design-source: rejected (<reason>)` in the tracker.
    - This does NOT re-verify pixels — that stays with `visual-fidelity-verifier` (Phase 2.6). It only proves the source was read and the reuse-mapping targets are real. When the card has no design source, skip this step entirely.
 
-7c. **i18n fill pass (explicit, deterministic — v5.0.0, promoted from the step-9 sub-bullet).** When `features.has_i18n: true` AND this card's diff added new source-locale keys — detect deterministically, never by intuition:
+7c. **i18n fill pass (explicit, deterministic — v5.0.0, promoted from the step-9 sub-bullet).** **Light lane (v5.4.1): SKIP this spawn** — on the light lane (step 2d) the owner briefing already instructed the coder to fill EVERY target locale itself (context-aware from the registry); the anti-hardcoded lint + locale-parity gates at step 8 enforce it. Log `i18n-fill: SKIP (light lane — owner fills inline)`. Otherwise: when `features.has_i18n: true` AND this card's diff added new source-locale keys — detect deterministically, never by intuition:
    ```bash
    cd <worktree-path>
    # $SRC_LOCALE = the source-language locale file path (from i18n config / the project's locales root)

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

@@ -6,6 +6,12 @@
 
 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.
 
+> **Minimal light lane (v5.4.1): SKIP the spawn for an all-`light` batch** — a light card
+> carries no deployable surface by Rule C (no migrations, indexes, cron, schema, env); the
+> checklist agent would only report zero items. Log
+> `phase7-production: SKIPPED (all-light batch — no deployable surface)`. Any
+> `balanced`/`deep` card in the batch → run as written.
+
 ### How to detect items
 
 Scan ALL files changed across the batch (use the tracker's completed cards + `git diff` against the base branch) and check for the items below.

package/framework/.claude/skills/new/references/review-cycle.md

@@ -305,7 +305,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 > **Note**: Code review is NOT performed in this phase — it is handled by the **mandatory unconditional `/codexreview` gate in Phase 3.7**, which runs per-card BEFORE the Phase 4 commit. The post-batch `/codexreview` in the Final review remains as a final FULL-diff sweep over the entire batch (since v3.37.0 — the guaranteed full-depth merge gate). This Phase 3 focuses exclusively on documentation sync, which must happen per-card (tied to the specific commit).
 
-> **Deferral gate (since v4.7.0 — enumerated, `review_profile`-driven)**: SKIP per-card doc-review and defer it to the **Final Review F.3 doc-reviewer** (which runs over the entire batch) when the card is **`review_profile == light` AND its committed diff touches NO documentation file** (no `.md`, no path under `${paths.references_dir}`, no data-model/ssot/api doc). These are small code changes with no doc surface of their own; their only doc concern is drift, which the batch-wide Final doc-reviewer catches. Log `doc-review: DEFERRED to Final FULL gate (light, no doc files in diff)` and proceed to Phase 3.5. **KEEP per-card doc-review** for: `deep` cards, `balanced` cards (they may still PASS-fast via the deterministic gate below — that gate, not this deferral, is their only skip lane), ANY card whose diff touches a doc file (the change IS doc-relevant), and trivial cards (doc-review is their primary gate — § "Trivial-card fast-lane", unchanged). Never defer "for time" — the only enumerated reasons are `light + non-doc diff` and the deterministic PASS-fast below.
+> **Deferral gate (since v4.7.0 — enumerated, `review_profile`-driven)**: SKIP per-card doc-review and defer it to the **Final Review F.3 doc-reviewer** (which runs over the entire batch) when the card is **`review_profile == light` AND its committed diff touches NO documentation file** (no `.md`, no path under `${paths.references_dir}`, no data-model/ssot/api doc). These are small code changes with no doc surface of their own; their only doc concern is drift, which the batch-wide Final doc-reviewer catches. Log `doc-review: DEFERRED to Final FULL gate (light, no doc files in diff)` and proceed to Phase 3.5. **KEEP per-card doc-review** for: `deep` cards, `balanced` cards (they may still PASS-fast via the deterministic gate below — that gate, not this deferral, is their only skip lane), ANY card whose diff touches a doc file (the change IS doc-relevant), and trivial cards (doc-review is their primary gate — § "Trivial-card fast-lane", unchanged). Never defer "for time" — the only enumerated reasons are `light + non-doc diff` and the deterministic PASS-fast below. **Single-card light batch exception (v5.4.1 minimal light lane): do NOT defer** — when the batch has exactly ONE card and it is `light`, the Final Review is itself SKIPPED if the per-card review is clean (see final-review.md § Minimal-light skip gate), so the deferral target would never run: run the scoped per-card doc-reviewer here instead.
 >
 > **Deterministic PASS-fast (v5.0.0 — measured: 84/127 per-card doc reviews returned PASS)**: when implement.md step 11c produced `/tmp/docinv-<CARD-ID>.json` AND it says `pass_fast_eligible: true` (zero non-advisory invariant rows triggered + no doc file in the diff + the card declares no `documentation_impact`/`canonical_docs`) AND the card is NOT `deep` → log `doc-review: PASS-fast (doc-invariants: 0 blocking rows) — Final doc-reviewer backstop stands` and **skip the per-card spawn** (proceed to Phase 3.5). No gate is removed: the batch-Final F.3 doc-reviewer still sees this card's diff. Own-Doc Closure: NEW-file obligations are definitionally empty (no invariant row fired, no docs declared); obligations on MODIFIED primitives/routes are covered by the automatic spec resync (`DS_COMPONENT_STALE` serializer gate, v4.70.0) plus the Final F.3 backstop — the invariant table's R1/R3 fire on new files only, by design. `deep` cards always spawn. Missing docinv JSON → no PASS-fast (fall through to the normal path).
 

package/framework/.claude/skills/new2/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## (workflow new2.js, framework v5.4.1) — 2026-07-03
+
+- Minimal light lane mirror: single-card light adds per-card doc-reviewer to the review
+  matrix, skips the i18n fill spawn (owner briefing carries the fill instruction),
+  skips new-final-review when `lightLane && cleanReview` (zero actionable findings),
+  skips production-readiness for all-light batches. Result objects carry
+  `lightLane`/`cleanReview` for the Final gate.
+
 ## (workflow new2.js, framework v5.4.0) — 2026-07-03
 
 - Light lane: `review_profile: light|skip` cards no longer spawn the Phase-1 retriever —

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

@@ -1,7 +1,7 @@
 ---
 name: new2
 effort: high
-version: 1.5.0
+version: 1.6.0
 description: >
   Workflow-hosted batch engine for /new. Implements one or
   more backlog cards end-to-end by delegating the WHOLE batch to a background

package/framework/.claude/workflows/new2.js

@@ -617,7 +617,7 @@ async function runCard(cardId, cardPath) {
   const phase1Brief = architectOk
     ? `Phase 1 already ran as specialist agents. READ the architecture baseline at ${baselinePath} BEFORE writing any code — it is your codebase context; do NOT redo the exploration.${auditCorrections.length ? `\nPlan-audit corrections (apply them as amendments to this briefing — do NOT modify the backlog YAML):\n${auditCorrections.map((c, i) => `  ${i + 1}. ${c}`).join('\n')}` : ''}`
     : phase1.architect === 'inline-light'
-      ? `Phase 1 light lane (v5.4.0): this card is review_profile '${reviewProfile}' (≤3-file scale) — no dedicated retriever ran. Ground INLINE per AGENTS.md § Change Tiers (orchestrated-pipeline exception): BEFORE writing code, read the files in scope + their immediate integration points (imports/consumers). Scoped exploration of the touched area only — not a repo sweep; the understanding obligation is unchanged, only the delegation was waived.`
+      ? `Phase 1 light lane (v5.4.0): this card is review_profile '${reviewProfile}' (≤3-file scale) — no dedicated retriever ran. Ground INLINE per AGENTS.md § Change Tiers (orchestrated-pipeline exception): BEFORE writing code, read the files in scope + their immediate integration points (imports/consumers). Scoped exploration of the touched area only — not a repo sweep; the understanding obligation is unchanged, only the delegation was waived.${features.has_i18n ? ' I18N (light lane): NO separate fill pass runs for this card — fill EVERY target locale yourself for any new key (context-aware from the registry); the anti-hardcoded lint gate must pass.' : ''}`
       : `Phase 1 fallback: the architect specialist was unavailable — do the Phase 1 claim+architect exploration yourself per ${REF}/implement.md and persist the baseline to ${baselinePath} before coding.`
   // T1.A (v4.90.0) — mockup cards: binding-compliance is verified deterministically by the
   // check-bindings.mjs script (ui-implement Step 5b is the SSOT; this is the new2 parallel).
@@ -670,7 +670,10 @@ async function runCard(cardId, cardPath) {
   // v5.0.0 — explicit i18n fill pass (implement.md step 7c mirror; closes the measured leakage
   // where locale fills were spawned as general-purpose). The translator is named BY TYPE; it
   // self-detects new source-locale keys from the diff and no-ops cheaply when there are none.
-  if (features.has_i18n) {
+  // v5.4.1 minimal light lane — no separate fill pass: the owner filled every locale itself
+  // (its briefing carries the instruction) and the Phase-2 anti-hardcoded lint gate enforces it.
+  if (features.has_i18n && lightLane) g('i18n-fill', 'SKIP', 'light lane — owner fills locales inline; lint gate enforces')
+  else if (features.has_i18n) {
     try {
       const fill = await agentSafe(
         `You are i18n-translator (fill pass for card ${cardId} — agents/i18n-protocol.md per-card cascade). cd into the card worktree. FIRST detect deterministically whether this card's diff (/tmp/diff-${cardId}.txt) added NEW source-locale keys; if none → return { ran:false, keys:0 } immediately (no-op). If keys exist: fill the missing TARGET locales for exactly those keys, context-aware from the registry at ${paths.i18n_registry || 'the i18n registry'} — the source locale stays untouched (the coder is source-only by design). Then re-run the project's locale-parity check if one exists. Return: { ran, keys, note }`,
@@ -834,7 +837,14 @@ async function runCard(cardId, cardPath) {
   }
   let reviewers
   if (reviewProfile === 'skip') reviewers = []
-  else if (reviewProfile === 'light') reviewers = codexAvail ? ['codex'] : ['code-reviewer']
+  else if (reviewProfile === 'light') {
+    reviewers = codexAvail ? ['codex'] : ['code-reviewer']
+    // v5.4.1 minimal light lane — a single-card light batch skips the Final workflow when its
+    // per-card review is clean (nothing post-fix to verify), so doc coverage cannot defer
+    // there: run the scoped doc-reviewer per-card instead. Multi-card light keeps the
+    // deferral (the Final batch pass still runs and covers it).
+    if (cardIds.length === 1) reviewers.push('doc-reviewer')
+  }
   else if (noEvidence) reviewers = FULL_FANOUT // balanced/deep, no surface evidence → conservative full
   else reviewers = relevanceGated() // balanced AND deep — surface-gated breadth
   if (reviewProfile !== 'skip') g('review-matrix', 'PLANNED', `[${reviewProfile}${noEvidence ? '→conservative-full (no surface evidence)' : ''}] ${reviewers.join('+') || '(none)'} · docs:${touchesDocs} code:${touchesCode} api/data:${touchesApiData} sec:${securityRelevant}`)
@@ -974,8 +984,13 @@ async function runCard(cardId, cardPath) {
     // B6 — which reviewers ACTUALLY ran (the gated matrix); Phase Final keys its slim/skip
     // decision on this, and per_card telemetry records it for the A/B spawn accounting.
     reviewersRun: reviewers,
-    // B7 — Phase-1 specialist record (architect: done|inline-fallback; audit: pass|fixes|skipped-*).
+    // B7 — Phase-1 specialist record (architect: done|inline-fallback|inline-light; audit: pass|fixes|skipped-*).
     phase1,
+    // v5.4.1 minimal light lane — Phase Final keys its skip on these: a single light card whose
+    // per-card review surfaced NOTHING actionable has no post-fix state for the Final pass to
+    // verify (the Final review's purpose — v4.56.1 — is POST-fix verification, not re-review).
+    lightLane,
+    cleanReview: blocks.length === 0 && scopeExp.length === 0,
     scopeFiles, archBaselinePath: `/tmp/arch-baseline-${cardId}.md`, gates,
   }
 }
@@ -1151,7 +1166,13 @@ const committed = perCardResults.filter((r) => r.status === 'committed')
 phase('Final')
 let finalSummary = null
 let mergeBlocked = degraded
-if (committed.length && !degraded) {
+// v5.4.1 minimal light lane — ONE light card, clean per-card review (zero actionable
+// findings → zero fixes applied): the Final pass has nothing post-fix to verify and its
+// doc coverage already ran per-card (the light single-card matrix includes doc-reviewer).
+// Any finding/fix on the card, any second card, or any degradation → Final runs as always.
+const skipFinalLight = committed.length === 1 && committed[0].lightLane && committed[0].cleanReview && !degraded
+if (skipFinalLight) ledger(firstCard, 'final-review', 'SKIPPED', 'single light card, clean per-card review — nothing post-fix to verify (doc ran per-card)')
+if (committed.length && !degraded && !skipFinalLight) {
   const reviewScopeFiles = dedupe(committed.flatMap((r) => r.scopeFiles || []))
   const archPaths = committed.map((r) => r.archBaselinePath).filter(Boolean)
   const allArch = archPaths.length === committed.length ? archPaths : null
@@ -1295,7 +1316,11 @@ if (!committed.length) {
 // Phase Production (Phase 7) — non-blocking; report-not-execute (F-011 infra-deferred).
 // ───────────────────────────────────────────────────────────────────────────
 phase('Production')
-if (mergeResult && mergeResult.merged) {
+if (mergeResult && mergeResult.merged && committed.length && committed.every((r) => r.lightLane)) {
+  // v5.4.1 minimal light lane — light cards carry no deployable surface by Rule C (no
+  // migrations/indexes/cron/schema); the checklist would only burn a spawn to report zero items.
+  ledger(firstCard, 'phase7-production', 'SKIPPED', 'all-light batch — no deployable surface (Rule C)')
+} else if (mergeResult && mergeResult.merged) {
   try {
     // Schema-deploy-from-trunk-only invariant (v4.33.0): a remote schema/RLS/index/
     // migration deploy desyncs a shared remote datastore when run off-trunk. When the

package/package.json

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