baldart 4.61.0 → 4.61.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.61.1] - 2026-06-22
+
+**`/new` pre-flight no longer wrongly HALTs/skips well-specified `/prd` cards that merely omit the top-level `requirements` block.** Real-world friction: implementing a `/prd`-designed epic with `/new` repeatedly hit *"N cards lack the top-level `requirements` field (profile CHILD)"* even though those cards had complete `scope`, `scope_boundaries`, `acceptance_criteria`, and `business_rationale` — the requirements were fully derivable, and the user had to hand-back-fill them every time or risk the gate destroying the epic. Root cause: `card-schema.md` listed `requirements` as an **unconditional** HALT (non-derivable), so a derivable-but-omitted block forced an ask/skip. The `prd-card-writer` still mandates emitting `requirements`; this only adds the consumer-side safety net that already exists for `review_profile`/`owner_agent`.
+
+**PATCH** — repairs an over-strict ingestion gate; no new capability, no new `baldart.config.yml` key, no install change. The validator and the matrix `R` classification are unchanged (the writer must still emit `requirements`; the back-fill makes it present before validation runs).
+
+### Changed
+
+- **`framework/agents/card-schema.md`** (SSOT consumer contract) — `requirements` reclassified from unconditional HALT to a **conditional** HALT member: it HALTs **only when its deriving material is itself absent** (`acceptance_criteria` empty OR `scope` empty — a genuinely thin card). When both are present and non-empty, a missing `requirements` block is recovered via a new BACK-FILL **sub-kind (b): faithful derivation** — a bounded restatement/decomposition of the existing AC + scope (faithful, never generative; never invents new scope).
+- **`framework/.claude/skills/new/references/setup.md`** — pre-flight 1b-i drops `requirements` from the unconditional HALT list (now conditional on AC/scope being empty); 1b-ii gains the faithful-derivation back-fill (derive from AC + scope, persist to the card on disk in the main repo, log `[BACKFILL] … requirements=<N items, AC+scope-derived>`).
+- **`framework/.claude/workflows/new2.js`** (parallel location, gate G4) — a card missing `requirements` with AC + scope present is now faithfully derived + written back (F-040 main-repo discipline) instead of excluded from the batch; only excluded when AC or scope is also absent.
+
 ## [4.61.0] - 2026-06-22
 
 **UI design-quality critic — a separate, rigorous reviewer for *"is this good design?"*, distinct from the existing *"does it match the mockup?"* check.** Born from the observation that implemented UIs were often poor despite the full `ui-expert` + `/e2e-review` machinery. Root cause, confirmed by exploration: every existing UI verification checks **fidelity / conformance**, not **intrinsic quality** — `visual-fidelity-verifier` asks only whether the render matches the mockup (and never reads source, never judges aesthetics), `code-reviewer`'s design-system steward is mechanical (token/primitive compliance), and the only agent judging quality (`ui-expert`) is *also the implementer*, so it grades its own work. The generator-grades-itself antipattern is exactly what the critic-in-the-loop research (vision-guided iterative refinement; rubric-based LLM-as-judge with per-dimension calibration) identifies as the failure mode. This release adds the missing layer: a separate critic that judges the rendered output against a scientific rubric, in the existing bounded self-heal loop.

package/VERSION

@@ -1 +1 @@
-4.61.0
+4.61.1

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

@@ -136,15 +136,17 @@
 1b. **Normalize & validate card baseline (pre-flight gate)** — `/new` is **type-blind**: it runs the same pipeline on `FEAT`/`CHORE`/`BUG`/`DOC`/`PERF`. The universal, profile-aware baseline is the SSOT in [`framework/agents/card-schema.md`](../../../agents/card-schema.md). Detect each card's profile (epic / child / standalone) per that module, then run three stages. (Epic-parent cards are excluded from the per-card loop — skip 1b-i/ii for them; the validator at 1b-iii still checks their EPIC column.)
 
    **1b-i — HALT on non-derivable fields (ask the user).** Verify the fields that cannot be safely synthesized are present and non-empty:
-   - `requirements` (>=1), `acceptance_criteria` (>=1), `files_likely_touched` (>=1 file), and `scope`.
+   - `acceptance_criteria` (>=1), `files_likely_touched` (>=1 file), and `scope`.
+   - **`requirements` is conditional, NOT an unconditional HALT** (card-schema.md consumer contract): it HALTs here **only when `acceptance_criteria` OR `scope` is itself empty** (a genuinely thin card). When `acceptance_criteria` AND `scope` are both present and non-empty, a missing `requirements` block is **faithfully derivable** and is back-filled in 1b-ii — do NOT HALT or skip the card for it. (This is the common `/prd` shape: complete AC + scope + scope_boundaries but no top-level `requirements` — skipping it would destroy the epic.)
    - `scope_boundaries` is **NOT** in this set (it is conditional — legitimately omitted for standalone cards with no siblings; see card-schema.md).
    If any card fails: log the specific missing fields in `## Issues & Flags`, ask the user to fill them in before proceeding with that card, and continue pre-flight for any remaining valid cards. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=none safe (non-derivable fields cannot be fabricated — SC-4 "missing fields → SKIP+report, never fabricate") → skip that card from the batch and log `AUTO: card-baseline → skipped <CARD-ID> (missing <fields>)`; continue with the valid cards. NEVER invent requirements/AC/scope.**
 
    **1b-ii — Back-fill deterministically-computable fields (compute → persist → log).** For each non-epic card missing a derivable field, compute it and **write it back to the card on disk in `$MAIN/${paths.backlog_dir}`** (the main repo path resolved at Phase 0 step 1 — NOT the worktree copy; same F-040 discipline `new2` uses for follow-ups):
    - `review_profile` absent → compute via `prd-card-writer.md § Rule C` (the SSOT), write it.
    - `owner_agent` absent/empty/`claude` → default `coder`, write it. (Never back-fill an epic's `""`.)
+   - `requirements` absent **AND** `acceptance_criteria` + `scope` both present and non-empty → **faithfully derive** it (card-schema.md consumer contract, BACK-FILL sub-kind b): write a `requirements` list that is a concrete restatement/decomposition of the card's existing AC + scope. **Faithful, not generative** — restate only what the AC and scope already commit to; NEVER invent new scope, constraints, or behaviour. (If `acceptance_criteria` OR `scope` is also empty, this is NOT derivable — it was already HALTed at 1b-i; never reach here.) Log it as `requirements=<N items, derived from AC+scope>`.
    - **Check-and-skip (idempotent):** write ONLY when the field is genuinely absent. A card that already has the field is untouched — so a pre-flight re-entry after compaction never double-writes.
-   - Log each write on its own line in `## Issues & Flags`: `[BACKFILL] <CARD-ID>: <field>=<value> (Rule C / coder-default)`.
+   - Log each write on its own line in `## Issues & Flags`: `[BACKFILL] <CARD-ID>: <field>=<value> (Rule C / coder-default / AC+scope-derived)`.
    - **Commit discipline:** after all cards are processed, if ANY back-fill was written, commit them together in `$MAIN` with the COMMIT_LOCK + doc-freshness precautions of `merge-cleanup.md` Phase 6b (clear stale `COMMIT_LOCK`; `git add` only the back-filled card YAMLs; if the doc-freshness hook blocks, stage `ssot-registry.md`; ≤2 retries): `git commit -m "chore(backlog): normalise card baseline [BACKFILL]"`. Do NOT leave `$MAIN` dirty for the batch duration — an uncommitted backlog edit would surface as noise in the Phase 3/4 git-diff gates.
    - `canonical_docs` / `links.prd` absent on a standalone/non-PRD card → **WARN** only (log, do not block, do not back-fill).
 

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

@@ -271,7 +271,7 @@ try {
       `• Worktree (setup.md step 4): the ENTIRE build sequence (worktree add → install → env copy → port → registry → baseline) is the SSOT script \`scripts/setup-worktree.sh\` — the SAME script /nw and classic /new run. Do NOT hand-roll the bash (a re-authored copy is the duplication CLAUDE.md forbids, and the script cannot fabricate a baseline or stall). Resolve the branch from the lead/parent card's git_strategy.branch (fallback feat/<PARENT-ID|lead>-<slug>) + a kebab slug, then derive the git-authoritative idempotency pre-check (existing worktree for the branch → reset the half-built orphan before running, never re-create into a fail-loud collision). Resolve the script: \`SETUP_SH="$(ls .framework/framework/.claude/skills/worktree-manager/scripts/setup-worktree.sh .claude/skills/worktree-manager/scripts/setup-worktree.sh 2>/dev/null | head -1)"\`. Run it (foreground — you ARE the background context here): \`bash "$SETUP_SH" --main ${MAIN} --trunk ${TRUNK} --branch <branch> --slug <slug> --cards "${cardIds.join(',')}" --group-parent "<PARENT|>" --env-files "${ENV_FILES.join(',')}" --manifest /tmp/new2-wt-${firstCard}.txt\`. It installs non-interactively, copies stack.env_files (FILES plain cp / DIRS cp -R / missing FILE → WARN, never abort; never .env.example, never bulk-copy untracked), allocates a locked port, writes the registry, and runs the baseline under timeout 600 (tsc/lint report-but-continue, build STOP-on-fail). Read the manifest block (status/baseline/worktree_path/port/created_at/baseline_log): map baseline → your baseline field (pass|fail|timeout) and baseline_log → baselineLog. E2: a \`baseline:fail\`/\`status:error\` build break is NOT yours to fix (role boundary — the coder repairs it); just return it precisely. Then, INDEPENDENTLY of the manifest, VERIFY the worktree on disk and return EVIDENCE (the workflow E2.5 gate string-matches it, never the script's word): set worktreeVerified:true ONLY after running \`git -C ${MAIN} worktree list --porcelain\` (the worktree path MUST appear) AND \`test -d <wt>/node_modules\` AND confirming the branch; put the LITERAL stdout into worktreeEvidence{ worktreeListPorcelain, artifactsLs:\`ls -la <wt>/node_modules <wt>/.next 2>/dev/null | head\`, baselineLogTail }. If the script is ABSENT (older subtree), fall back to running the sequence inline per setup.md step 4 prose. NEVER report worktreeVerified:true without actually running the verify commands.\n` +
       codexResolveBullet +
       g3Bullet +
-      `• G4 card-field validation (setup.md 1b/1c): card missing requirements/acceptance_criteria/files_likely_touched → EXCLUDE (excluded[] + reason). Never HALT for one bad card.\n` +
+      `• G4 card-field validation (setup.md 1b/1c, card-schema.md consumer contract): card missing acceptance_criteria/files_likely_touched/scope → EXCLUDE (excluded[] + reason). \`requirements\` is CONDITIONAL, not an auto-exclude: if it is missing BUT acceptance_criteria + scope are both present and non-empty, FAITHFULLY DERIVE it (a concrete restatement/decomposition of the existing AC + scope — faithful, never inventing new scope) and WRITE it back to the card YAML on disk in ${MAIN}/${paths.backlog_dir || 'backlog'} (F-040: main repo, not the worktree copy; the card artifact is NOT a source/doc file, so this is allowed despite the role boundary), logging \`[BACKFILL] <id>: requirements=<N items, AC+scope-derived>\`. Only EXCLUDE for missing requirements when acceptance_criteria OR scope is ALSO empty (a genuinely thin card). Never HALT for one bad card.\n` +
       `• G5 depends-on: a card whose depends_on names a non-DONE card NOT in this batch → EXCLUDE it AND every in-batch card that transitively depends on it.\n` +
       `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha, isEpic (implement.md §6b epic guard: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements), filesLikelyTouched (verbatim from the YAML) }.\n` +
       `• B1/F-026 idempotency (per card, AFTER the worktree exists): set alreadyCommitted:true (+ alreadyCommittedSha) IFF ALL hold: (a) a commit referencing the card id exists in ${TRUNK}..HEAD of the worktree; (b) the card's validation_commands re-run GREEN right now; (c) NO open follow-up card for it exists in ${paths.backlog_dir || 'backlog'}. On a FRESH worktree ${TRUNK}..HEAD is empty → all false, zero extra work.\n` +

package/framework/agents/card-schema.md

@@ -55,7 +55,7 @@ Legend: **R** = required, present **and non-empty** · **E** = required key, val
 | `context` | R | R | R | |
 | `scope` | R | R | R | **never omittable** — encodes intent |
 | `scope_boundaries` | R | C | C | "Omit for standalone cards with no siblings" (`prd-card-writer.md`) |
-| `requirements` | C | R | R | EPIC tracks via AC-EPIC, not `requirements` |
+| `requirements` | C | R | R | EPIC tracks via AC-EPIC; CHILD/STANDALONE: faithfully derivable from AC+scope when both present — see consumer contract |
 | `acceptance_criteria` | R (AC-EPIC) | R | R | |
 | `definition_of_done` | R | R | R | |
 | `depends_on` / `blocks` | E (`[]`) | E | E | |
@@ -81,13 +81,24 @@ The three classes are deliberately distinct so a thin card is fixed where it can
 blocks where intent is genuinely missing:
 
 - **HALT (non-derivable — ask the user):** a **R** field that cannot be safely synthesized.
-  The canonical HALT set is `requirements`, `acceptance_criteria`, `files_likely_touched`,
-  and `scope` (CHILD/STANDALONE). `scope_boundaries` is **NOT** in the HALT set — it is **C**.
-- **BACK-FILL (deterministically computable — compute, persist, log):** `review_profile`
-  (compute via `prd-card-writer.md § Rule C`) and `owner_agent` (default `coder` for a
-  non-epic; **never** back-fill an epic's `""`). Write the value to the card on disk in the
-  **main repo** with a `[BACKFILL] <id>: <field>=<value>` log. **Check-and-skip**: only write
-  when the field is genuinely absent (idempotent across pre-flight re-entry).
+  The canonical HALT set is `acceptance_criteria`, `files_likely_touched`, and `scope`
+  (CHILD/STANDALONE). `scope_boundaries` is **NOT** in the HALT set — it is **C**.
+  `requirements` is a **conditional** member: it HALTs **only when its deriving material is
+  itself absent** (`acceptance_criteria` empty OR `scope` empty) — a genuinely thin card. When
+  `acceptance_criteria` AND `scope` are both present and non-empty, a missing `requirements`
+  block is *recoverable by faithful derivation* (next bullet, sub-kind b), not a HALT — a
+  well-specified card must never be skipped just because the writer omitted a derivable block.
+- **BACK-FILL (recoverable without asking — compute/derive, persist, log):** two sub-kinds.
+  *(a) Deterministically computable:* `review_profile` (compute via `prd-card-writer.md § Rule C`)
+  and `owner_agent` (default `coder` for a non-epic; **never** back-fill an epic's `""`).
+  *(b) Faithful derivation (bounded synthesis):* `requirements` — **only when**
+  `acceptance_criteria` AND `scope` are both present and non-empty — synthesize the
+  `requirements` list as a concrete restatement/decomposition of the existing AC + scope. This
+  is **faithful, not generative**: restate what the AC and scope already commit to; NEVER invent
+  new scope, constraints, or behaviour (the same procedure a card author performs by hand). For
+  either sub-kind, write the value to the card on disk in the **main repo** with a
+  `[BACKFILL] <id>: <field>=<value>` log. **Check-and-skip**: only write when the field is
+  genuinely absent (idempotent across pre-flight re-entry).
 - **WARN (expected but tolerable absent):** `canonical_docs` / `links.prd` on a STANDALONE /
   non-PRD card. Log, do not block.
 

package/package.json

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