baldart 4.92.0 → 4.93.0

package/framework/scripts/stamp-holistic-audit.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * stamp-holistic-audit.js — deterministic writer of the `metadata.holistic_audit`
+ * provenance block on backlog cards.
+ *
+ * Why this exists (/prd gate-hygiene wave): the per-card stamp write in
+ * audit-phase.md Step 6.9.4 and its backstop in validation-phase.md Step 7 item 5b
+ * were BOTH model-driven prose — and both failed together on a real run (a whole
+ * card family shipped with zero audit trail, so `/new` re-spawned the plan-auditor
+ * on every card). A prose gate degrades under context pressure; this script makes
+ * the stamp a single deterministic operation both call sites EXECUTE.
+ *
+ * Semantics are defined in audit-phase.md § "Holistic-audit provenance stamp" —
+ * this script only mechanizes the write:
+ *   - idempotent: a card already carrying `holistic_audit` with a non-empty
+ *     `audited_commit` is left untouched;
+ *   - additive: never overwrites other `metadata` keys;
+ *   - EPIC cards are skipped (they carry `planning_session` only — card-schema.md);
+ *   - `--commit ""` is written EXPLICITLY (never omitted) so `/new` treats it as
+ *     drift and runs its own plan-auditor (the fail-safe contract).
+ *
+ * Usage:
+ *   node framework/scripts/stamp-holistic-audit.js \
+ *     --at "2026-07-02T10:00:00Z" --commit "<sha-or-empty>" \
+ *     --set "FEAT-0070-01,FEAT-0070-02" <card1.yml> [<card2.yml> ...]
+ *
+ * Exit 0 = every non-epic card carries the stamp afterwards; exit 1 = a write or
+ * parse failed (per-file errors printed). Zero-dep, node-core only.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseCardYaml, detectProfile } = require(path.join(__dirname, 'validate-card-baseline.js'));
+
+function argValue(args, flag) {
+  const i = args.indexOf(flag);
+  return i > -1 && i + 1 < args.length ? args[i + 1] : null;
+}
+
+/** True when the card text already carries holistic_audit with a non-empty audited_commit. */
+function alreadyStamped(text) {
+  const m = String(text).match(/^\s+holistic_audit:\s*$[\s\S]*?^\s+audited_commit:\s*"([^"]+)"/m);
+  return !!(m && m[1].trim() !== '');
+}
+
+/** Remove a pre-existing holistic_audit block (e.g. one with an empty commit) so the rewrite is clean. */
+function stripExistingBlock(text) {
+  const lines = String(text).split('\n');
+  const start = lines.findIndex((l) => /^\s+holistic_audit:\s*$/.test(l));
+  if (start === -1) return text;
+  const indent = lines[start].length - lines[start].trimStart().length;
+  let end = start + 1;
+  while (end < lines.length) {
+    const l = lines[end];
+    if (l.trim() === '') { end++; continue; }
+    const li = l.length - l.trimStart().length;
+    if (li <= indent) break;
+    end++;
+  }
+  return lines.slice(0, start).concat(lines.slice(end)).join('\n');
+}
+
+function buildBlock(at, commit, set, childIndent) {
+  const pad = ' '.repeat(childIndent);
+  const inner = ' '.repeat(childIndent + 2);
+  const ids = set.map((s) => `"${s}"`).join(', ');
+  return [
+    `${pad}holistic_audit:`,
+    `${inner}audited_at: "${at}"`,
+    `${inner}audited_commit: "${commit}"`,
+    `${inner}audited_set: [${ids}]`,
+  ].join('\n');
+}
+
+function stampFile(file, at, commit, set) {
+  let text = fs.readFileSync(file, 'utf8');
+  let card;
+  try { card = parseCardYaml(text); } catch (e) { return { file, status: 'error', detail: `YAML parse error — ${e.message}` }; }
+  if (!card || typeof card !== 'object') return { file, status: 'error', detail: 'not a YAML mapping' };
+  if (detectProfile(card, path.basename(file)) === 'EPIC') return { file, status: 'epic-skipped' };
+  if (alreadyStamped(text)) return { file, status: 'already-stamped' };
+
+  text = stripExistingBlock(text);
+  const lines = text.split('\n');
+  const metaIdx = lines.findIndex((l) => /^metadata:\s*$/.test(l));
+  if (metaIdx > -1) {
+    // child indent = indent of the first existing metadata child, else 2 spaces
+    let childIndent = 2;
+    for (let j = metaIdx + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l.trim() === '') continue;
+      const li = l.length - l.trimStart().length;
+      if (li > 0) childIndent = li;
+      break;
+    }
+    lines.splice(metaIdx + 1, 0, buildBlock(at, commit, set, childIndent));
+    text = lines.join('\n');
+  } else {
+    if (!text.endsWith('\n')) text += '\n';
+    text += `\nmetadata:\n${buildBlock(at, commit, set, 2)}\n`;
+  }
+  fs.writeFileSync(file, text);
+  // verify the write landed (the 5b "re-read one card" contract, made universal)
+  if (!alreadyStamped(fs.readFileSync(file, 'utf8')) && commit !== '') {
+    return { file, status: 'error', detail: 'post-write verification failed — stamp not found' };
+  }
+  return { file, status: 'stamped' };
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  const at = argValue(args, '--at');
+  const commit = argValue(args, '--commit'); // may legitimately be "" — must still be PASSED
+  const setRaw = argValue(args, '--set');
+  const files = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--at' || args[i] === '--commit' || args[i] === '--set') { i++; continue; }
+    files.push(args[i]);
+  }
+  if (!at || commit === null || setRaw === null || !files.length) {
+    process.stderr.write('Usage: stamp-holistic-audit.js --at <iso8601> --commit <sha-or-empty> --set "ID1,ID2" <card.yml> [...]\n');
+    return 2;
+  }
+  const set = setRaw.split(',').map((s) => s.trim()).filter(Boolean).sort();
+  let failed = 0, stamped = 0, already = 0, epics = 0;
+  for (const f of files) {
+    let r;
+    try { r = stampFile(f, at, commit, set); } catch (e) { r = { file: f, status: 'error', detail: e.message }; }
+    if (r.status === 'error') { failed++; process.stdout.write(`✖ ${f}: ${r.detail}\n`); }
+    else if (r.status === 'stamped') { stamped++; process.stdout.write(`✓ ${f}: stamped\n`); }
+    else if (r.status === 'already-stamped') { already++; process.stdout.write(`· ${f}: already stamped\n`); }
+    else { epics++; process.stdout.write(`· ${f}: epic — skipped\n`); }
+  }
+  process.stdout.write(`holistic_audit provenance: ${stamped + already}/${files.length - epics} non-epic cards stamped (${stamped} written here, ${already} already present, ${epics} epic skipped)\n`);
+  return failed ? 1 : 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = { stampFile, alreadyStamped, stripExistingBlock };

package/framework/scripts/structural-compare.mjs

@@ -111,9 +111,14 @@ function signature(texts) {
         sig.grid_cols_responsive_max = Math.max(sig.grid_cols_responsive_max, countTracks(m[1]));
       }
     }
-    // Tailwind: grid-cols-N (+ responsive variants), incl. arbitrary grid-cols-[a_b]
+    // Tailwind: grid-cols-N (+ responsive variants), incl. arbitrary grid-cols-[a_b].
+    // Arbitrary values use `_` as the space stand-in and may contain functions —
+    // `grid-cols-[repeat(2,_minmax(0,1fr))]` is 2 tracks, not split('_').length=3:
+    // normalize `_`→space and reuse the parens-aware countTracks().
     for (const m of t.matchAll(/(?:^|[\s"'`])(?:(sm|md|lg|xl|2xl):)?grid-cols-(\d+|\[[^\]]+\])/g)) {
-      const cols = m[2].startsWith('[') ? m[2].split('_').length : parseInt(m[2], 10);
+      const cols = m[2].startsWith('[')
+        ? countTracks(m[2].slice(1, -1).replace(/_/g, ' '))
+        : parseInt(m[2], 10);
       sig.grid_cols_max = Math.max(sig.grid_cols_max, cols);
       if (m[1]) {
         sig.has_responsive_prefixes = true;

package/framework/scripts/validate-card-baseline.js

@@ -19,8 +19,18 @@
  *
  * Usage:
  *   node framework/scripts/validate-card-baseline.js <card.yml> [<card2.yml> ...]
+ *   node framework/scripts/validate-card-baseline.js --prd <card.yml> [...]
  * Exit 0 = all valid; exit 1 = at least one card has errors (printed per-field).
  *
+ * --prd (since the /prd gate-hygiene wave): adds the deterministic subset of the
+ * /prd validation-phase Step 6 item 0 checks, so the orchestrator EXECUTES them
+ * instead of reciting them (prose gates fail silently under context pressure):
+ *   - conditional `requirements` (PO1): child/standalone with non-empty
+ *     acceptance_criteria + scope MUST have non-empty requirements;
+ *   - epic `review_profile` must be `skip`;
+ *   - `[NEEDS CLARIFICATION: …]` ambiguity markers in the raw YAML are BLOCKERS —
+ *     a card ships only when every planning ambiguity has been resolved.
+ *
  * Module API (for CI self-tests in scripts/check-card-baseline.js):
  *   const { validateCard, detectProfile, loadSchema, loadEnums } = require(...)
  */
@@ -349,21 +359,56 @@ function validateCard(card, { matrix, enums, filename = '' } = {}) {
   return { profile, errors };
 }
 
+// --- /prd deterministic gate additions (--prd) -------------------------------
+
+/** Scan raw YAML text for unresolved planning-ambiguity markers. */
+function scanAmbiguityMarkers(text) {
+  const out = [];
+  const lines = String(text).split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes('[NEEDS CLARIFICATION')) {
+      out.push(`line ${i + 1}: ${lines[i].trim().slice(0, 120)}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * The deterministic subset of /prd validation-phase Step 6 item 0 (see file header).
+ * Returns string[] errors. `text` is the raw YAML (marker scan), `card` the parsed map.
+ */
+function prdGateChecks(card, text, profile) {
+  const errors = [];
+  if (profile !== 'EPIC' && nonEmpty(card.acceptance_criteria) && nonEmpty(card.scope) && !nonEmpty(card.requirements)) {
+    errors.push("has acceptance_criteria + scope but no 'requirements' — emit requirements (faithful restatement of AC + scope) before commit (PO1)");
+  }
+  if (profile === 'EPIC' && nonEmpty(card.review_profile) && String(card.review_profile) !== 'skip') {
+    errors.push(`epic 'review_profile' must be 'skip' (got '${card.review_profile}') — trackers have no code work`);
+  }
+  for (const m of scanAmbiguityMarkers(text)) {
+    errors.push(`unresolved ambiguity marker — resolve with the user before commit: ${m}`);
+  }
+  return errors;
+}
+
 // --- CLI --------------------------------------------------------------------
 
 function main(argv) {
-  const files = argv.slice(2);
+  const args = argv.slice(2);
+  const prdMode = args.includes('--prd');
+  const files = args.filter((a) => a !== '--prd');
   if (!files.length) {
-    process.stderr.write('Usage: validate-card-baseline.js <card.yml> [<card2.yml> ...]\n');
+    process.stderr.write('Usage: validate-card-baseline.js [--prd] <card.yml> [<card2.yml> ...]\n');
     return 2;
   }
   const matrix = loadSchema();
   const enums = loadEnums();
   let failed = 0;
   for (const file of files) {
-    let card;
+    let text, card;
     try {
-      card = parseCardYaml(fs.readFileSync(file, 'utf8'));
+      text = fs.readFileSync(file, 'utf8');
+      card = parseCardYaml(text);
     } catch (e) {
       process.stdout.write(`✖ ${file}: YAML parse error — ${e.message}\n`);
       failed++;
@@ -375,6 +420,7 @@ function main(argv) {
       continue;
     }
     const { profile, errors } = validateCard(card, { matrix, enums, filename: path.basename(file) });
+    if (prdMode) errors.push(...prdGateChecks(card, text, profile));
     if (errors.length) {
       failed++;
       process.stdout.write(`✖ ${file} [${profile}] — ${errors.length} issue(s):\n`);
@@ -390,4 +436,4 @@ if (require.main === module) {
   process.exit(main(process.argv));
 }
 
-module.exports = { validateCard, detectProfile, loadSchema, loadEnums, nonEmpty, parseCardYaml };
+module.exports = { validateCard, detectProfile, loadSchema, loadEnums, nonEmpty, parseCardYaml, prdGateChecks, scanAmbiguityMarkers };

package/package.json

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