baldart 3.23.0 → 3.24.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.24.0] - 2026-05-27
+
+Nuovo gate **AC-Closure** (Phase 2.5b) in `/new` + regola **Scope Closure Discipline** in `framework/agents/workflows.md`. Risolve il pattern ricorrente in cui l'orchestratore — sotto pressione di context-window o complessità inattesa — defer-iva unilateralmente acceptance criteria numerate marcandole `deferred` negli `implementation_notes` YAML con razionalizzazione post-hoc ("ApproveSheet già copre il confirm"). Caso reale che ha innescato la fix: sessione `/new` su FEAT-0005 (2026-05-27) dove 5 AC su 22 sono state silenziosamente deferite con razionalizzazione poi rivelata falsa alla verifica funzionale. Le decisioni di deferral sono ora **sempre routate all'utente via `AskUserQuestion`** una-per-AC.
+
+### Added — Phase 2.5b AC-Closure Gate (BLOCKING)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: nuova Phase 2.5b inserita tra Phase 2.5 (Completeness Check) e Phase 2.55 (Simplify). 6 step:
+  1. **AC Closure Ledger** — tabella esplicita una-riga-per-AC con status enum binario `implemented` | `deferred` (nessuna terza categoria — l'AC è nel diff o sta venendo deferita), evidence `file:line`, campo `User-approved?`.
+  2. **Rationalization scan** — per ogni AC `deferred`, se la giustificazione matcha pattern `covered by X` / `already handles` / `redundant with Y` / `out of scope`, l'orchestratore DEVE leggere `X/Y` e produrre una scope-mapping line-per-line nel tracker sotto `## Rationalization Verification`. Il pattern senza verifica NON auto-approva il deferral.
+  3. **User gate** — `AskUserQuestion` BLOCKING uno-per-AC (mai batched), con testo AC verbatim + 4 opzioni: implementa adesso (spawna fix coder scoped al ownership map) / approva deferral (registra `[USER-APPROVED DEFERRAL] <date>: <reason>` in `implementation_notes`) / sposta su follow-up card (crea `<CARD-ID>-followup-AC<N>.yml` con `status: TODO`) / ferma il batch.
+  4. **`implementation_notes` audit** — grep finale per phrase `deferred` / `out of scope` / `covered by` / `skipped` etc.; ogni match deve carry il prefisso `[USER-APPROVED DEFERRAL]` o tornare allo Step 3.
+  5. **Context-pressure exception** — directive esplicita: sotto context pressure si ferma e si chiede, NON si compensa skippando AC. Auto Mode's "bias toward proceeding" non override questa regola.
+- **Top-level directive** in `/new` SKILL.md (riga 13, subito dopo YOLO MODE banner): riassume la Scope Closure Discipline e linka workflows.md.
+
+### Added — Scope Closure Discipline rule (citable protocol)
+
+- **[framework/agents/workflows.md](framework/agents/workflows.md)**: nuova sezione `## Scope Closure Discipline (MUST)` tra "Status Tracking" e "Deploys and Publications". 3 violazioni esplicite (silent deferral, rationalization-without-verification, scope reduction under context pressure) + protocollo di enforcement via `AskUserQuestion`. Citable da skill/agent come autorità — un finding "silent AC deferral" è BLOCKING in code review.
+
+### Why MINOR (not PATCH)
+
+Aggiunta di capability: nuovo gate obbligatorio in `/new` che cambia comportamento osservabile per i consumer (Phase 2.55 non parte più finché Phase 2.5b non passa). Nessun breaking change — card senza AC-deferral passano il gate transparently in <1s con `ac-closure: implemented=N | deferrals=0 | follow-ups=0`. Per la decision tree in MAINTAINING.md "Added an agent / command / skill / routine / template (or capability)? → MINOR".
+
+### Why no schema-change propagation
+
+Modifiche testuali a due file framework. Zero chiavi nuove in `baldart.config.yml`, zero modifiche CLI (`src/commands/*`), zero hook, zero adapter, zero template. Il gate sfrutta strutture YAML già esistenti (`acceptance_criteria`, `implementation_notes`) e `${paths.backlog_dir}` già nella config schema da v3.0.0.
+
 ## [3.23.0] - 2026-05-27
 
 Aggiunto il flag `-full` / `--full` a `/new` per espandere un epic ai suoi figli in un colpo solo — `/new FEAT-005 -full` lancia automaticamente `FEAT-005-1`, `FEAT-005-2`, … senza domande di grouping né di branch. Risolve il pattern ricorrente "ho un epic con 5 child card, le voglio tutte ora": prima richiedeva di listarle a mano (`/new FEAT-005-1 FEAT-005-2 FEAT-005-3 …`) o di usare l'hyphen-range solo se gli ID erano numericamente contigui.

package/VERSION

@@ -1 +1 @@
-3.23.0
+3.24.0

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

@@ -10,6 +10,8 @@ description: >
 
 > **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
 
+> **SCOPE CLOSURE DISCIPLINE (BLOCKING)**: This orchestrator NEVER unilaterally defers an acceptance criterion. Silent deferral via `implementation_notes`, commit message, or final recap is a protocol violation per `framework/agents/workflows.md § Scope Closure Discipline`. Under context-window pressure, time pressure, or unforeseen complexity, the correct action is to STOP and route the decision back to the user via `AskUserQuestion` — Auto Mode's "bias toward proceeding" applies to routine decisions, NOT to scope reduction. **Phase 2.5b (AC-Closure Gate)** enforces this at the per-card level before commit and is non-skippable.
+
 ## Project Context
 
 **Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`.
@@ -793,6 +795,75 @@ Rationale: BUG-0558's introducing card (FEAT-0850-02) had its tests deferred to
 
 6. **Update tracker**: phase = "2.5-completeness DONE", log result (PASS / GAPS REMAIN + count).
 
+### Phase 2.5b — AC-Closure Gate (BLOCKING — Scope Closure Discipline)
+
+This gate enforces `framework/agents/workflows.md § Scope Closure Discipline` at the per-card level. It runs after Phase 2.5's gap-resolution loops have settled and BEFORE Phase 2.55 (Simplify). It is non-skippable.
+
+**Why this exists**: Phase 2.5's fix loops handle items an agent can implement autonomously. They do NOT handle the case where the implementer (or you, the orchestrator) decides — under context pressure or perceived complexity — that an AC is "good enough as is" or "already covered by an existing component". Burying that decision in the card YAML's `implementation_notes`, in a commit message, or in a final recap is a silent scope reduction. The decision belongs to the user.
+
+**Step-by-step**:
+
+1. **Update tracker**: phase = "2.5b-ac-closure".
+
+2. **Build the AC Closure Ledger** — one row per `acceptance_criteria` entry from the card YAML (NOT requirements — only the AC list, because ACs are the user-facing contract):
+
+   ```
+   ## AC Closure Ledger — <CARD-ID>
+   | AC# | Text (verbatim) | Status | Evidence (file:line) | User-approved? |
+   |-----|-----------------|--------|----------------------|----------------|
+   | AC-1 | [text] | implemented | src/x.ts:42 | n/a |
+   | AC-2 | [text] | deferred | n/a | pending |
+   ```
+
+   Status enum: `implemented` | `deferred`. The Phase 2.5 categories map as follows: `Done` → `implemented`; `Partial` or `Missing` (after gap-resolution exhausted retries) → `deferred`. There is no third option — an AC is either in the diff or it is being deferred.
+
+3. **Rationalization scan (BLOCKING for every `deferred` row)** — read the coder's completion report and the card's `implementation_notes`. If the justification for a `deferred` AC matches any of the patterns below, classify the row as `RATIONALIZATION_NEEDS_PROOF`:
+
+   - "covered by <X>" / "already covers" / "existing <X> handles" / "<X> already does"
+   - "implicit in <X>" / "no longer needed" / "redundant with <X>"
+   - "out of scope of this card" (when the AC is clearly listed in the card YAML)
+
+   For each `RATIONALIZATION_NEEDS_PROOF` row, the orchestrator MUST verify by reading `<X>` and producing a line-for-line scope mapping between the AC text and the alleged coverage. The mapping goes in the tracker under `## Rationalization Verification`. If the mapping does not hold (or cannot be produced confidently), the row stays `deferred` and proceeds to Step 4 — the rationalization does NOT auto-approve the deferral.
+
+4. **User gate (BLOCKING `AskUserQuestion` — one per `deferred` AC that is not pre-approved)**:
+
+   For each `deferred` row whose `User-approved?` is `pending`, invoke `AskUserQuestion` with:
+   - Question: `"AC-<N> of <CARD-ID> non implementata. Testo verbatim: '<AC text>'. Motivazione dell'implementer: '<reason or 'nessuna — silent skip'>'. Come procedo?"`
+   - Options (max 4):
+     1. **"Implementa adesso"** — spawn a targeted fix `coder` agent scoped to this card's MAY EDIT files (from `## File Ownership Map`) with the instruction "Implement ONLY AC-<N>: '<AC text>'. Do not refactor or expand scope." Re-run Phase 2.5 verification on the resulting diff. On second failure of the same AC, return to this gate (do NOT loop indefinitely).
+     2. **"Approva il deferral"** — record `[USER-APPROVED DEFERRAL] <today>: <user-supplied reason>` on its own line in the card's `implementation_notes`. Mark the row `User-approved? yes`.
+     3. **"Sposta su follow-up card"** — create a backlog stub at `${paths.backlog_dir}/<CARD-ID>-followup-AC<N>.yml` with the AC text + minimal context + `status: TODO`. Mark the row `User-approved? yes (follow-up: <new-card-id>)`. Do NOT proceed to Phase 2.55 until the follow-up file exists on disk.
+     4. **"Ferma il batch"** — halt the orchestrator, leave the worktree intact, log the reason in `## Issues & Flags`. Do NOT commit.
+
+   Do NOT batch the question across multiple ACs — one `AskUserQuestion` per AC, so the user sees each AC's text in isolation. Issue the questions sequentially.
+
+5. **`implementation_notes` deferral audit (cheap text grep — also BLOCKING)** — before exiting the phase, scan the card YAML's `implementation_notes` field (post-edits, including any text added during this phase) for any of these phrases:
+
+   - `deferred` / `deferral` / `defer to`
+   - `out of scope` / `scope cut`
+   - `covered by` / `already handles` / `redundant`
+   - `skipped` / `dropped`
+
+   For each match, verify the line carries the `[USER-APPROVED DEFERRAL]` prefix AND the corresponding AC row in the ledger has `User-approved? yes`. Any mismatch is a silent deferral that escaped Step 4 — trigger the Step 4 `AskUserQuestion` for the AC referenced (or for "the unspecified AC implied by this note" if no AC is named, asking the user to clarify which AC the note refers to).
+
+6. **Update tracker**: phase = "2.5b-ac-closure DONE". Persist the AC Closure Ledger AND the Rationalization Verification (if any) in the tracker. Log counts on one line:
+
+   ```
+   ac-closure: implemented=N | user-approved deferrals=M | follow-up cards created=K | rationalization-verifications passed=L
+   ```
+
+The gate exits PASS only when every ledger row is either `implemented` or `deferred` with `User-approved? yes`. Phase 2.55 (Simplify) MUST NOT start until this gate exits PASS.
+
+#### Context-pressure exception (still BLOCKING — no escape)
+
+If at any point in Phases 2 / 2.5 / 2.5b you detect context-window pressure (your context is being summarized, you have ≥ 1 forced compaction, you are racing through verification, you are tempted to "just mark this AC as covered"), do NOT compensate by skipping ACs. The correct response is:
+
+1. Stop the current card's pipeline.
+2. Write the current state to the tracker under `## Issues & Flags` with the prefix `[CONTEXT-PRESSURE]` (which Phase 2 finished, which ACs are open, which files are dirty).
+3. Invoke `AskUserQuestion` with options: (a) finish remaining ACs in a fresh `/new` session that resumes from the tracker, (b) commit the complete ACs and route the rest through this gate's Step 4, (c) hand off the worktree intact to the user.
+
+Auto Mode does NOT override this rule. "Bias toward proceeding" applies to routine decisions ("should I rerun this check?", "should I confirm this safe rename?"), NEVER to scope reduction.
+
 ### Phase 2.55 — Simplify (code cleanup before review)
 
 After completeness is verified, clean up the implementation before it reaches reviewers and E2E tests. This phase launches three parallel agents on the card's diff, then applies fixes directly.

package/framework/agents/workflows.md

@@ -51,6 +51,16 @@ Define how agents plan, track, and complete work safely.
 - `IN_PROGRESS` requires Active Code Context set.
 - `BLOCKED` requires blocker documented in card and status file.
 
+## Scope Closure Discipline (MUST)
+
+When a card's `acceptance_criteria` cannot be fully implemented as written, the deferral is a USER decision, not an agent decision. The following are protocol violations regardless of perceived risk or convenience:
+
+- **Silent deferral** — marking an AC as not implemented inside the card YAML (`implementation_notes`, `notes`, comments) without explicit user approval recorded in the same session. Approved deferrals MUST carry the `[USER-APPROVED DEFERRAL] <date>: <reason>` prefix on the same line; the prefix is the audit trail.
+- **Rationalization-without-verification** — justifying an unimplemented AC with "X already covers it" / "Y already handles this" / "redundant with Z" without (a) reading X / Y / Z, and (b) showing a line-for-line scope mapping between the AC and the alleged coverage. The mapping lives in the tracker under `## Rationalization Verification`.
+- **Scope reduction under context pressure** — when context-window pressure, time pressure, or unforeseen complexity makes the original scope hard to meet, the correct action is to STOP and surface the situation via `AskUserQuestion` (preferred options: implement now, defer with explicit approval, move to a follow-up card, halt and hand off). Trading completeness for visible coverage across more cards is forbidden.
+
+Any deferral travels through an explicit `AskUserQuestion` with the AC text quoted verbatim, one question per AC. For orchestrator skills (`/new`, `/prd`) this discipline is enforced in the per-card AC-closure gate before commit. Auto Mode's "bias toward proceeding" applies to routine decisions, NOT to scope reduction — silent deferral of a numbered AC is a violation even in Auto Mode.
+
 ## Deploys and Publications
 
 - Production deploys and publications must follow `agents/deployment-protocol.md` if it exists.

package/package.json

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