baldart 5.4.1 → 5.6.0

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

@@ -22,7 +22,17 @@
  * 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> ...]
+ *     --set "FEAT-0070-01,FEAT-0070-02" \
+ *     [--audit-report /tmp/prd-audit-<slug>.md] <card1.yml> [<card2.yml> ...]
+ *
+ * EVIDENCE GATE (v5.6.0 — the FEAT-0068 phantom stamp): the stamp is only worth
+ * anything if the audit team actually ran. `--audit-report <path>` names the
+ * audit-phase report artifact; the script reads its `agents_run:` line (falling
+ * back to counting `agent:`/`###` sections) and writes `agents_run: [...]` +
+ * `findings_count` into the stamp. WITHOUT the flag — or when the file does not
+ * exist / names no agents — the script writes `status: "skipped"` and NO
+ * `agents_run`, which `/new` (implement.md Phase 1 step 4 P1) treats as ABSENT:
+ * the plan-auditor runs. A stamp can no longer claim an audit that never happened.
  *
  * 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.
@@ -61,19 +71,49 @@ function stripExistingBlock(text) {
   return lines.slice(0, start).concat(lines.slice(end)).join('\n');
 }
 
-function buildBlock(at, commit, set, childIndent) {
+/**
+ * v5.6.0 — extract audit evidence from the audit-phase report artifact.
+ * Returns { agentsRun: string[], findingsCount: number|null } or null when the
+ * report is absent/unreadable/empty of agents (→ the stamp degrades to skipped).
+ */
+function readAuditEvidence(reportPath) {
+  if (!reportPath) return null;
+  let text;
+  try { text = fs.readFileSync(reportPath, 'utf8'); } catch (_) { return null; }
+  // primary: an explicit `agents_run: a, b, c` (or YAML list) line in the report
+  const m = text.match(/^agents_run:\s*\[?([^\]\n]+)\]?/m);
+  let agents = m ? m[1].split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean) : [];
+  if (!agents.length) {
+    // fallback: agent names cited as report sections/spawn lines
+    const KNOWN = ['plan-auditor', 'codebase-architect', 'security-reviewer', 'api-perf-cost-auditor', 'qa-sentinel', 'code-reviewer', 'doc-reviewer'];
+    agents = KNOWN.filter((a) => new RegExp(`\\b${a}\\b`).test(text));
+  }
+  if (!agents.length) return null;
+  const fc = text.match(/^findings(?:_count)?:\s*(\d+)/m);
+  return { agentsRun: Array.from(new Set(agents)), findingsCount: fc ? Number(fc[1]) : null };
+}
+
+function buildBlock(at, commit, set, childIndent, evidence) {
   const pad = ' '.repeat(childIndent);
   const inner = ' '.repeat(childIndent + 2);
   const ids = set.map((s) => `"${s}"`).join(', ');
-  return [
+  const lines = [
     `${pad}holistic_audit:`,
     `${inner}audited_at: "${at}"`,
     `${inner}audited_commit: "${commit}"`,
     `${inner}audited_set: [${ids}]`,
-  ].join('\n');
+  ];
+  if (evidence) {
+    lines.push(`${inner}agents_run: [${evidence.agentsRun.map((a) => `"${a}"`).join(', ')}]`);
+    if (evidence.findingsCount !== null) lines.push(`${inner}findings_count: ${evidence.findingsCount}`);
+  } else {
+    // no audit artifact → the stamp is explicit about it; /new P1 treats this as ABSENT
+    lines.push(`${inner}status: "skipped"`);
+  }
+  return lines.join('\n');
 }
 
-function stampFile(file, at, commit, set) {
+function stampFile(file, at, commit, set, evidence) {
   let text = fs.readFileSync(file, 'utf8');
   let card;
   try { card = parseCardYaml(text); } catch (e) { return { file, status: 'error', detail: `YAML parse error — ${e.message}` }; }
@@ -94,11 +134,11 @@ function stampFile(file, at, commit, set) {
       if (li > 0) childIndent = li;
       break;
     }
-    lines.splice(metaIdx + 1, 0, buildBlock(at, commit, set, childIndent));
+    lines.splice(metaIdx + 1, 0, buildBlock(at, commit, set, childIndent, evidence));
     text = lines.join('\n');
   } else {
     if (!text.endsWith('\n')) text += '\n';
-    text += `\nmetadata:\n${buildBlock(at, commit, set, 2)}\n`;
+    text += `\nmetadata:\n${buildBlock(at, commit, set, 2, evidence)}\n`;
   }
   fs.writeFileSync(file, text);
   // verify the write landed (the 5b "re-read one card" contract, made universal)
@@ -113,20 +153,23 @@ function main(argv) {
   const at = argValue(args, '--at');
   const commit = argValue(args, '--commit'); // may legitimately be "" — must still be PASSED
   const setRaw = argValue(args, '--set');
+  const auditReport = argValue(args, '--audit-report'); // v5.6.0 evidence gate (optional flag, binding semantics)
   const files = [];
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--at' || args[i] === '--commit' || args[i] === '--set') { i++; continue; }
+    if (args[i] === '--at' || args[i] === '--commit' || args[i] === '--set' || args[i] === '--audit-report') { 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');
+    process.stderr.write('Usage: stamp-holistic-audit.js --at <iso8601> --commit <sha-or-empty> --set "ID1,ID2" [--audit-report <path>] <card.yml> [...]\n');
     return 2;
   }
   const set = setRaw.split(',').map((s) => s.trim()).filter(Boolean).sort();
+  const evidence = readAuditEvidence(auditReport);
+  if (!evidence) process.stdout.write(`⚠ no audit evidence (${auditReport ? 'report unreadable/agent-less: ' + auditReport : '--audit-report not passed'}) → stamping status:"skipped" (no agents_run; /new will RUN the plan-auditor)\n`);
   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 }; }
+    try { r = stampFile(f, at, commit, set, evidence); } 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`); }

package/package.json

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