baldart 5.5.0 → 5.6.0

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

@@ -85,7 +85,13 @@ const schemaDeployFromTrunkOnly = stack.schema_deploy_from_trunk_only === true
 const firstCard = cardIds[0] || 'BATCH'
 const gateLedger = []        // { card, gate, decision, detail }
 const residualFollowups = [] // { card, kind, followupCard, reason }
-const residuals = []         // F-020 OFFLINE-SAFE ledger: { card, kind, evidence, materialized, deferralClass, domain, remedyFiles }
+const residuals = []         // F-020 OFFLINE-SAFE ledger: { card, kind, evidence, materialized, deferralClass, domain, remedyFiles, severity? }
+// v5.6.0 (FEAT-0068 post-mortem) — epic-closure integrity state. closureInvalidating collects final
+// findings that assert an epic goal/AC is NOT met (a STATE defect: a doc fix resolves the text, not
+// the epic). closureBlockedEpics is the JS-computed deny-list the merge agent must honor: the
+// workflow sees the residual ledger; the merge agent's grep cannot see unmaterialized residuals.
+const closureInvalidating = [] // strings: "SEVERITY title: evidence"
+const closureBlockedEpics = new Set()
 const cardMayEdit = {}       // v4.30.0 — per-card MAY-EDIT, for the cross-card integration union
 const perCardResults = []
 let prodReadiness = null
@@ -209,6 +215,10 @@ const PREFLIGHT_SCHEMA = {
           designSrcDir: { type: 'string', description: "abs path of links.design_src / mockups/_src dir ('' when absent)" },
           designHtml: { type: 'string', description: "abs path of an .html links.design mockup ('' when absent)" },
           hasBindings: { type: 'boolean', description: 'card carries a non-empty component_bindings map' },
+          // v5.6.0 (FEAT-0068 post-mortem) — the card's parent epic id (group.parent / parent:).
+          // Drives the epic-closure blocklist (an epic with open scope residuals/follow-ups must
+          // not close) and the Epic goal section of the final report.
+          parentEpic: { type: 'string', description: "parent epic id from group.parent or parent: ('' when none)" },
         },
       },
     },
@@ -237,7 +247,10 @@ const MERGE_SCHEMA = {
     reconciliation: { type: 'string' },
     forcedDone: { type: 'array', items: { type: 'string' }, description: 'MUST be empty — false-DONE is forbidden (F-029)' },
     deferredLeftOpen: { type: 'array', items: { type: 'string' }, description: 'F-040 — committed cards left NON-DONE (open owner-gated AC); the skill marks them DONE post-run' },
-    epicsClosed: { type: 'array', items: { type: 'string' }, description: 'Epic/parent cards marked DONE by Phase 6b step 5e (all children DONE) — NOT a forcedDone violation' },
+    epicsClosed: { type: 'array', items: { type: 'string' }, description: 'Epic/parent cards marked DONE by Phase 6b step 5e (children DONE + no open follow-up + epic ACs verified) — NOT a forcedDone violation' },
+    // v5.6.0 (FEAT-0068) — epics deliberately NOT closed, each with the concrete reason (workflow
+    // blocklist / open child or follow-up / unverified epic AC). Feeds the Epic goal report section.
+    epicsLeftOpen: { type: 'array', items: { type: 'object', additionalProperties: true, properties: { epic: { type: 'string' }, reason: { type: 'string' } } }, description: 'epics left open by the closure predicate, with reasons' },
     uncommittedLeft: { type: 'boolean', description: 'true if dirty code was left (NOT committed) + reported (F-030)' },
     status: { type: 'string', description: 'merge-worktree.sh terminal status: success|code_conflict|build_fail|sync_needs_decision|error' },
     conflictFiles: { type: 'array', items: { type: 'string' }, description: 'on status:code_conflict — the UNRESOLVED code/test files the script paused on (left for a human / the resolver; new2 OPS agent does NOT hand-resolve)' },
@@ -292,7 +305,7 @@ try {
       g3Bullet +
       `• 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'), hasMockup (BOOLEAN — true IFF the card has a non-empty links.design OR links.design_src; drives the mockup-first build override — implement.md §6a), designSrcDir (ABS path of links.design_src / the PRD mockups/_src dir; '' when absent), designHtml (ABS path when links.design is an .html file; '' otherwise), hasBindings (BOOLEAN — non-empty component_bindings), 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` +
+      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), hasMockup (BOOLEAN — true IFF the card BUILDS the mocked UI: links.design_src non-empty, OR links.design non-empty AND (component_bindings non-empty OR files_likely_touched intersects component/style/UI source paths). A bare links.design on a docs/test/meta-only card is a POINTER to the epic's explainer, not a build target — v5.6.0, FEAT-0068: the bare test clamped a docs+ADR card to ui-expert; drives the mockup-first build override — implement.md §6a), parentEpic (the card's parent epic id from group.parent or a top-level parent: field; '' when none — drives the epic-closure blocklist + the Epic goal report section), designSrcDir (ABS path of links.design_src / the PRD mockups/_src dir; '' when absent), designHtml (ABS path when links.design is an .html file; '' otherwise), hasBindings (BOOLEAN — non-empty component_bindings), 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` +
       `• F-016 AC↔ownership consistency: for each acceptance_criterion, derive the file(s) it requires editing. If those files are NOT a subset of the card's MAY-EDIT/files_likely_touched → add the AC to policyDeferredACs:[{n,text,owningCard|owningFile,reason}] (it will become ONE follow-up, never a resolve). Do the same for any AC whose remedy is an owner-gated infra action (remote db push / deploy / secret / DNS).\n` +
       (migrationApplied
@@ -944,19 +957,28 @@ async function runCard(cardId, cardPath) {
   // must NOT be marked DONE here (its own DoD isn't met yet — e.g. the remote db:push is pending).
   // The new2 SKILL marks it DONE post-run, ONLY after the deferral's follow-up exists on disk in the
   // main repo (so a card is never DONE with a silently-dropped requirement — F-029).
+  // v5.6.0 (FEAT-0068 post-mortem) — step 4b (epic closure) REMOVED from the commit agent: closing
+  // at the last card's commit ran structurally BEFORE the final review could disprove the goal, and
+  // from a context that could not see the worktree's untracked follow-up YAMLs. final-review.md:451
+  // already assigns closure to the merge phase ONLY — new2 now honors its own SSOT (Phase 6b 5e).
   const doneStep = deferredOpen
     ? `(4) DO NOT mark the card DONE: it has an OPEN owner-gated/policy-deferred AC. Keep status IN_PROGRESS and add an implementation_note "deferred — DONE pending follow-up (new2 skill reconciles post-run)". STILL add the ssot-registry row for the committed code.`
-    : `(4) mark the card DONE in its YAML + add the ssot-registry row.${provLine} (4b) epic-closure gate (deterministic): if the card YAML has a \`parent:\` field, count sibling YAMLs in the backlog dir with that same parent whose status is NOT DONE; when the count is zero, flip the parent epic's ssot-registry entry to DONE (and the parent's own YAML status + completed_date, if one exists) in the SAME commit — these bookkeeping edits are in-scope for staging even if outside MAY-EDIT. Idempotent — skip when no parent, siblings still pending, or the parent entry is already DONE.`
+    : `(4) mark the card DONE in its YAML + add the ssot-registry row.${provLine}`
+  // The card YAML the agent edits MUST be the WORKTREE copy — the FEAT-0068 commit agent `find`-ed
+  // the main-repo copies and flipped stale siblings there (79 turns of detour, main checkout dirtied).
+  const wtCardPath = `${sharedCtx.worktreePath}/${paths.backlog_dir || 'backlog'}/${String(cardPath).split('/').pop()}`
   let commitRes
   try {
     commitRes = await agentSafe(
-      `Commit card ${cardId} in worktree ${sharedCtx.worktreePath}. MECHANICAL — do NOT re-read reference modules. ROLE BOUNDARY: you NEVER modify file contents except the card YAML status/note fields, the parent-epic YAML status (epic-closure gate only), and the ssot-registry entries — source/doc changes are not yours.\n` +
+      `Commit card ${cardId} in worktree ${sharedCtx.worktreePath}. MECHANICAL — do NOT re-read reference modules. ROLE BOUNDARY: you NEVER modify file contents except THIS card's YAML status/note fields and the ssot-registry entries — source/doc changes are not yours; sibling and parent-epic card YAMLs are READ-ONLY (epic closure happens in the merge phase, NOT here).\n` +
+        `Card YAML (edit THIS copy and no other): ${wtCardPath}\n` +
         `HARD RULE — cwd: EVERY shell command MUST begin with \`cd ${sharedCtx.worktreePath} && \` IN THE SAME Bash invocation. The shell cwd RESETS between Bash calls to the MAIN repo: a bare \`git commit\` executes against the main checkout's current branch and corrupts it (observed in FEAT-0067 — a card-DONE commit landed on the trunk mid-run). No exceptions, including 'quick' status/log commands.\n` +
-        `Steps: (1) \`git status --porcelain\`; (2) stage = MAY-EDIT (${JSON.stringify(mayEdit)}) ∩ dirty — NEVER \`git add -A\`, NEVER \`git stash\`; if dirty has files OUTSIDE MAY-EDIT, do NOT stage them and set reconcileNote; (3) commit message \`[${cardId}] <concise>\`; ${doneStep} (5) 'nothing to commit' = already committed (record HEAD); (6) VERIFY placement: \`cd ${sharedCtx.worktreePath} && git log -1 --format=%H\` MUST equal the sha you return — if it does not, your commit landed outside the worktree: report committed:false with reconcileNote naming the stray sha, do NOT retry blindly.\n` +
+        `WORKTREE ISOLATION — TOOLS TOO (v5.6.0): every path you pass to Read/Edit/Write MUST be under ${sharedCtx.worktreePath}. The cwd rule does NOT protect tool calls with absolute paths — NEVER Read/Edit/Write a path under the main repo ${MAIN}, never \`find\` files there, never cp/rsync between checkouts. A file you need that is missing from the worktree is a reconcileNote, not a fetch.\n` +
+        `Steps: (0) isolation evidence: run \`git -C ${MAIN} status --porcelain\` and record its LITERAL output as mainStatusBefore; (1) \`git status --porcelain\`; (2) stage = MAY-EDIT (${JSON.stringify(mayEdit)}) ∩ dirty — NEVER \`git add -A\`, NEVER \`git stash\` (anywhere, worktree or main); if dirty has files OUTSIDE MAY-EDIT, do NOT stage them and set reconcileNote; (3) commit message \`[${cardId}] <concise>\`; ${doneStep} (5) 'nothing to commit' = already committed (record HEAD); (6) VERIFY placement: \`cd ${sharedCtx.worktreePath} && git log -1 --format=%H\` MUST equal the sha you return — if it does not, your commit landed outside the worktree: report committed:false with reconcileNote naming the stray sha, do NOT retry blindly; (7) LAST action: re-run \`git -C ${MAIN} status --porcelain\` and record it VERBATIM as mainStatusAfter.\n` +
         `On COMMIT_LOCK: clear stale lock + retry once. Still locked → committed:false.\n\n` +
-        `Return: { committed, commit, filesChanged, reconcileNote }`,
+        `Return: { committed, commit, filesChanged, reconcileNote, mainStatusBefore, mainStatusAfter }`,
       { label: `commit:${cardId}`, phase: 'Implement', agentType: 'general-purpose', model: 'sonnet',
-        schema: { type: 'object', required: ['committed'], additionalProperties: true, properties: { committed: { type: 'boolean' }, commit: { type: 'string' }, filesChanged: { type: 'array', items: { type: 'string' } }, reconcileNote: { type: 'string' } } } }
+        schema: { type: 'object', required: ['committed'], additionalProperties: true, properties: { committed: { type: 'boolean' }, commit: { type: 'string' }, filesChanged: { type: 'array', items: { type: 'string' } }, reconcileNote: { type: 'string' }, mainStatusBefore: { type: 'string', description: 'literal `git -C <main> status --porcelain` BEFORE any other action' }, mainStatusAfter: { type: 'string', description: 'same command as the LAST action' } } } }
     )
   } catch (e) {
     if (e && e.transientExhausted) { noteDegraded('outage'); await rollbackCard(cardId, mayEdit); return { card: cardId, status: 'pending', gates } }
@@ -970,6 +992,20 @@ async function runCard(cardId, cardPath) {
   }
   if (commitRes && commitRes.reconcileNote) g('commit-reconcile', 'NOTE', commitRes.reconcileNote)
 
+  // v5.6.0 isolation guard (FEAT-0068 #60: prompts alone did not stop the main-repo detour) — the
+  // porcelain evidence is mechanical literal output (same trust model as E2.5): new lines in the
+  // main repo's status after the spawn = the agent dirtied the live checkout → VIOLATION + a HIGH
+  // residual so the skill reconciles the contamination post-run (it can run git; this JS cannot).
+  {
+    const msb = String((commitRes && commitRes.mainStatusBefore) || '').split('\n').filter(Boolean)
+    const msa = String((commitRes && commitRes.mainStatusAfter) || '').split('\n').filter(Boolean)
+    const dirtied = msa.filter((l) => !msb.includes(l))
+    if (dirtied.length) {
+      g('isolation-guard', 'VIOLATION', `main checkout dirtied during commit spawn: ${dirtied.slice(0, 5).join(' | ')}${dirtied.length > 5 ? ` (+${dirtied.length - 5})` : ''}`)
+      residuals.push({ card: cardId, kind: 'main-repo-contamination', severity: 'HIGH', evidence: `commit agent dirtied the main checkout (${dirtied.join(', ')}) — reconcile: restore/inspect these paths in ${MAIN}, never stash-and-forget`, materialized: false })
+    }
+  }
+
   g('commit', 'COMMITTED', `${(commitRes && commitRes.commit) || ''}${deferredOpen ? ' (NON-DONE — deferred, skill reconciles)' : ''}`)
   return {
     card: cardId, status: 'committed',
@@ -1200,6 +1236,18 @@ if (committed.length && !degraded && !skipFinalLight) {
     finalSummary = final.summary || null
     ledger(firstCard, 'final-review', 'DONE', `engine=${final.codexEngine}; verified=${final.summary ? final.summary.verified : '?'}`)
     const all = (final.findings || []).filter((f) => (f.classification === 'VERIFIED' || f.classification === 'NEEDS_MANUAL_CONFIRMATION') && (f.severity === 'BLOCKER' || f.severity === 'HIGH'))
+    // v5.6.0 — closure-invalidating detection (final-review.md § closure-invalidating): a finding
+    // asserting an epic goal/AC is unmet blocks/reopens the epic even after its text fix resolves.
+    // FEAT-0068: DOC-F001 ("SSOT overclaim: epic goal not achieved") was fixed as prose 13 minutes
+    // AFTER the epic closed DONE — the state contradiction merged. Scans ALL verified findings
+    // (any severity): an overclaim is state-relevant regardless of the reviewer's severity call.
+    const CLOSURE_INVALIDATING_RE = /goal[^.\n]{0,60}not[^.\n]{0,25}(achiev|met\b|reach|complete)|not[^.\n]{0,25}achiev[^.\n]{0,40}goal|overclaim|DONE[^.\n]{0,40}(unmet|not[^.\n]{0,20}(achiev|implement|complete))|epic[^.\n]{0,40}(unmet|not[^.\n]{0,30}(achiev|complete|reach))/i
+    for (const f of (final.findings || [])) {
+      if ((f.classification === 'VERIFIED' || f.classification === 'NEEDS_MANUAL_CONFIRMATION') && CLOSURE_INVALIDATING_RE.test(`${f.title || ''} ${f.evidence || ''}`)) {
+        closureInvalidating.push(`${f.severity} ${f.title}: ${String(f.evidence || '').slice(0, 200)}`)
+        ledger(f.finding_id || firstCard, 'closure-invalidating', 'EPIC-CLOSURE-BLOCKED', `${f.title} — the text fix resolves the finding, NOT the epic state`)
+      }
+    }
     // F-035 — drop merge-artifact doc findings (content exists in worktree, the merge carries it).
     const actionable = all.filter((f) => !/in (the )?main repo|not (in|on) (the )?main|merge[- ]?time|worktree.*(not|missing).*main/i.test(`${f.title} ${f.evidence}`))
     // G3 — the merge-artifact regex is loose; a BLOCKER/HIGH it over-matches must NOT vanish.
@@ -1250,6 +1298,26 @@ if (committed.length && !degraded && !skipFinalLight) {
 // ───────────────────────────────────────────────────────────────────────────
 phase('Merge')
 let mergeResult = null
+// v5.6.0 — epic-closure deny-list (FEAT-0068 post-mortem): an epic must NOT close while (a) a
+// closure-invalidating finding stands, (b) a child carries an open scope-expansion/unresolved/
+// ac-unmet/out-of-ownership residual, or (c) a residual follow-up was minted for a child. Computed
+// in JS from the ledger (the merge agent's disk grep cannot see unmaterialized residuals).
+// Conservative by design: a later-retracted residual keeps the epic open this run — the skill's
+// post-run reconciliation (REOPEN/close branch) settles it against the disk.
+{
+  const epicOf = (cid) => (graphById[cid] && graphById[cid].parentEpic) || ''
+  const BLOCKING_RESIDUAL = new Set(['scope-expansion', 'unresolved', 'ac-unmet', 'out-of-ownership', 'main-repo-contamination'])
+  if (closureInvalidating.length) for (const n of cardGraph) { const e = epicOf(n.id); if (e) closureBlockedEpics.add(e) }
+  for (const r of residuals) { if (BLOCKING_RESIDUAL.has(r.deferralClass || r.kind)) { const e = epicOf(r.card); if (e) closureBlockedEpics.add(e) } }
+  for (const fu of residualFollowups) { const e = epicOf(fu.card); if (e) closureBlockedEpics.add(e) }
+  if (closureBlockedEpics.size) ledger(firstCard, 'epic-closure-blocklist', 'ACTIVE', `${[...closureBlockedEpics].join(' ')} — open residuals/follow-ups/closure-invalidating findings; merge MUST leave these epics open`)
+}
+// v5.6.0 — safety-sweep allowlist (F-030 by construction): at merge time the only legitimately
+// uncommitted files are batch bookkeeping (follow-up YAMLs materialized in the worktree, metrics,
+// run artifacts). Dirty CODE here by definition did not pass the per-card gates → the script must
+// leave+quarantine it (manifest `uncommitted_left`/`quarantined`), never sweep it into the trunk
+// under an opaque "[safety]" commit (FEAT-0068 5f618347d, FEAT-0067 5a5f1c135).
+const sweepAllowlist = dedupe([`${paths.backlog_dir || 'backlog'}/*.yml`, `${METRICS}/*`, '.baldart/*']).join(',')
 // A2 — 'followup'/'blocked' cards were rolled back and their residuals live in the offline-safe
 // ledger: the worktree holds ONLY gate-passing committed work, so they must not strand the batch
 // (the old filter contradicted the gate's own comment and orphaned the worktree with no resume
@@ -1274,8 +1342,9 @@ if (!committed.length) {
       `Auto-merge the batch worktree to ${TRUNK} per ${REF}/merge-cleanup.md: Phase 6 via the DETERMINISTIC script merge-worktree.sh, then Phase 6b status reconciliation + Phase 6c hygiene. Run git yourself.\n\n${projectBrief}\nWorktree: ${sharedCtx.worktreePath}\nBranch: ${sharedCtx.branch}\nmerge_strategy: ${mergeStrategy}\nCommitted cards: ${committed.map((r) => r.card).join(' ')}\nPhase-0 stash to restore (if any): see "$(git -C "${MAIN}" rev-parse --git-common-dir)/baldart/run/batch-tracker-${firstCard}.md".\n\n` +
         `PHASE 6 — run the SSOT script (the merge analogue of setup-worktree.sh; NOT a hand-rolled merge, NOT /mw inline):\n` +
         `  MERGE_SH="$(ls .framework/framework/.claude/skills/worktree-manager/scripts/merge-worktree.sh .claude/skills/worktree-manager/scripts/merge-worktree.sh 2>/dev/null | head -1)"\n` +
-        `  bash "$MERGE_SH" --worktree ${sharedCtx.worktreePath} --manifest /tmp/new2-merge-status-${firstCard}.txt --skip-checks\n` +
-        `  Read /tmp/new2-merge-status-${firstCard}.txt and set status:<its status:>. \n` +
+        `  bash "$MERGE_SH" --worktree ${sharedCtx.worktreePath} --manifest /tmp/new2-merge-status-${firstCard}.txt --skip-checks --safety-sweep "allowlist:${sweepAllowlist}"\n` +
+        `  (--safety-sweep allowlist, v5.6.0: the script commits ONLY matching uncommitted files — batch bookkeeping — with an honest enumerating message; non-matching tracked changes are QUARANTINED to a labeled dir + restored, untracked left in place, both reported in the manifest keys uncommitted_left/quarantined. If the resolved script predates the flag it errors on the unknown arg → re-run WITHOUT the flag and treat any "[safety] Auto-commit" it then produces as reconciliation to report. F-030 stays binding either way.)\n` +
+        `  Read /tmp/new2-merge-status-${firstCard}.txt and set status:<its status:>. Also read uncommitted_left:/quarantined: and, when non-empty, set uncommittedLeft:true + note them.\n` +
         `  • status:success → set merged:true + mergeCommit/mergeTs from the file, then do Phase 6b/6c below. Read sync_marker:/sync_detail: from the FILE (not stdout) for the G19-23 hygiene gate.\n` +
         `  • status:code_conflict → set merged:false, status:'code_conflict', conflictFiles:[the file's conflict_files split on comma]. The script ALREADY resolved every additive doc/registry/JSONL conflict and PAUSED the rebase on the code/test files. Per your ROLE BOUNDARY you do NOT hand-resolve code — leave the worktree paused (do NOT abort), SKIP 6b/6c, and return (the workflow tracks it as a merge blocker → follow-up).\n` +
         `  • status:build_fail/error/sync_needs_decision → merged:false, note:<the file's error:>, leave the worktree intact, return.\n` +
@@ -1286,9 +1355,13 @@ if (!committed.length) {
         `• F-030 HARD RULE: NEVER \`git add\`/commit code that did not pass the per-card gates. If the worktree is dirty with uncommitted code → DO NOT commit it; leave it, set uncommittedLeft:true, and report. NO "safety commit". Security/migration code is NEVER swept in.\n` +
         `• F-029 HARD RULE: Phase 6b reconciliation marks a card DONE ONLY if it has a real commit in ${TRUNK}..HEAD AND its gates are green. NEVER force a non-implemented card to DONE. Return forcedDone:[] (must be empty).\n` +
         `• F-040 DEFERRED CARDS — leave NON-DONE (do NOT force to DONE in Phase 6b): ${deferredCards.length ? deferredCards.join(' ') : '(none)'}. These committed their code but carry an OPEN owner-gated/policy-deferred AC (e.g. a pending remote db:push). Their YAML is INTENTIONALLY IN_PROGRESS; the new2 skill marks them DONE post-run after materialising the deferral's follow-up. They ARE part of the merge — just skip them in the DONE-reconciliation. Return deferredLeftOpen:[the ones you left non-DONE].\n` +
-        `• EPIC CLOSURE (Phase 6b step 5e): the epic/parent card (group.is_epic:true) is NOT in the batch and stays TODO unless closed here. For each distinct group.parent of the batch cards (and any epic card in the batch itself): if EVERY child of that epic — \`grep -l "parent: <EPIC-ID>" ${paths.backlog_dir || 'backlog'}/*.yml | xargs grep -L "status: DONE"\` prints nothing — set the epic card status:DONE + completed_date + note "epic-closure gate — all children DONE" and fold into the reconciliation commit. If any child is still open → leave the epic untouched. This is NOT a forcedDone violation (the epic is a tracker, gated on all-children-DONE, not on its own commit). Return epicsClosed:[<EPIC-IDs marked DONE>].\n` +
-        `• G19 sync-deferred → HEAD==${TRUNK} ff-pull, else leave+report. G20 → leave+report. G21 post-batch dirty → partition-ignore framework artifacts; leave the rest + report (do NOT commit). G22 divergence → behind: ff-pull; ahead/both: leave+report; NEVER reset --hard/force-push. G23 stash restore conflict → leave intact + report.\n\n` +
-        `Return: { merged, mergeCommit, mergeTs, status, conflictFiles, reconciliation, forcedDone:[], deferredLeftOpen:[], uncommittedLeft, note }`,
+        `• EPIC CLOSURE (Phase 6b step 5e — the ONLY place an epic may close; v5.6.0 predicate, FEAT-0068 post-mortem): the epic/parent card is NOT in the batch and stays open unless closed here. For each distinct parent epic of the batch cards (and any epic card in the batch itself), close it ONLY when ALL of (a)(b)(c) hold:\n` +
+        `  (a) WORKFLOW BLOCKLIST — these epics have open scope residuals / pending follow-ups / closure-invalidating findings and MUST NOT be closed regardless of what the greps below say: ${closureBlockedEpics.size ? [...closureBlockedEpics].join(' ') : '(none)'}. A blocklisted epic goes in epicsLeftOpen with reason 'workflow blocklist (open residuals/follow-ups)'.\n` +
+        `  (b) NO OPEN CHILD — run \`grep -RIl -- "parent: <EPIC-ID>" ${paths.backlog_dir || 'backlog'}/\` in the WORKTREE (where in-batch follow-up YAMLs materialize — include untracked: also \`git ls-files --others --exclude-standard -- ${paths.backlog_dir || 'backlog'}/\`) AND in the main repo ${MAIN}; every hit (follow-up cards INCLUDED — a follow-up with that parent IS an open child) must have \`status: DONE\`. Any open hit → epicsLeftOpen with reason 'open child: <id>'.\n` +
+        `  (c) EPIC ACs VERIFIED — Read the epic YAML's acceptance_criteria: for each item run its ac_verification oracle when present (else a targeted grep/check that proves it) and flip \`[ ]\`→\`[x]\` ONLY with concrete evidence; an AC you cannot verify stays \`[ ]\` and the epic stays OPEN (epicsLeftOpen with reason 'unverified epic AC: <text>'). Never close an epic whose own checklist still has \`[ ]\` items.\n` +
+        `  Close = status:DONE + completed_date + note "epic-closure gate — children DONE + epic ACs verified", folded into the reconciliation commit. This is NOT a forcedDone violation (the epic is a tracker). Return epicsClosed:[<ids>] AND epicsLeftOpen:[{epic, reason}].\n` +
+        `• G19 sync-deferred → HEAD==${TRUNK} ff-pull, else leave+report. G20 → leave+report. G21 post-batch dirty → partition-ignore framework artifacts; leave the rest + report (do NOT commit). G22 divergence → behind: ff-pull; ahead/both: leave+report; NEVER reset --hard/force-push. G23 stash restore conflict → leave intact + report. NEVER \`git stash\` — in the worktree OR the main checkout: an ff-pull blocked by dirty files is leave+report (v5.6.0 — the FEAT-0068 run fabricated a dangling pre-ffpull stash from an unscoped sync mandate; a constraint with no escape hatch breeds fabrication).\n\n` +
+        `Return: { merged, mergeCommit, mergeTs, status, conflictFiles, reconciliation, forcedDone:[], deferredLeftOpen:[], epicsClosed:[], epicsLeftOpen:[], uncommittedLeft, note }`,
       // Sonnet, not the inherited opus: this is a deterministic OPS/GIT executor (git merge +
       // YAML status reconciliation + grep-based epic closure + leave-and-report hygiene gates), and
       // the correctness-critical checks (F-029 forcedDone guard, F-040 deferred guard) are enforced
@@ -1299,7 +1372,19 @@ if (!committed.length) {
   } catch (e) { if (e && e.transientExhausted) noteDegraded('outage'); mergeResult = null }
   if (mergeResult && (mergeResult.forcedDone || []).length) { noteDegraded('false_done'); ledger(firstCard, 'F029-guard', 'VIOLATION', `forcedDone: ${mergeResult.forcedDone.join(' ')}`) }
   if (mergeResult && mergeResult.uncommittedLeft) ledger(firstCard, 'F030-guard', 'LEFT-UNCOMMITTED', 'dirty code left (not swept) + reported')
-  if (mergeResult && (mergeResult.epicsClosed || []).length) ledger(firstCard, 'epic-closure', 'CLOSED', `epics marked DONE (all children DONE): ${mergeResult.epicsClosed.join(' ')}`)
+  // v5.6.0 epic-closure guard (the F-029 twin — `epicsClosed` was trusted blindly): an epic closed
+  // against the workflow deny-list is a false DONE → degrade + HIGH residual so the skill REOPENs it
+  // in the post-run reconciliation (this JS cannot run git; the skill can).
+  if (mergeResult && (mergeResult.epicsClosed || []).length) {
+    const wrongly = (mergeResult.epicsClosed || []).filter((e) => closureBlockedEpics.has(e))
+    if (wrongly.length) {
+      noteDegraded('false_done')
+      ledger(firstCard, 'epic-closure-guard', 'VIOLATION', `epic(s) closed against the blocklist: ${wrongly.join(' ')} — open residuals/follow-ups exist; skill must REOPEN`)
+      for (const e of wrongly) residuals.push({ card: e, kind: 'false-epic-closure', severity: 'HIGH', evidence: `epic ${e} was marked DONE despite open scope residuals/follow-ups — REOPEN it (status IN_PROGRESS) in the post-run reconciliation commit`, materialized: false })
+    }
+    ledger(firstCard, 'epic-closure', 'CLOSED', `epics marked DONE (children DONE + ACs verified): ${mergeResult.epicsClosed.join(' ')}`)
+  }
+  if (mergeResult && (mergeResult.epicsLeftOpen || []).length) ledger(firstCard, 'epic-closure', 'LEFT-OPEN', mergeResult.epicsLeftOpen.map((x) => `${x.epic}: ${x.reason}`).join(' · '))
   if (deferredCards.length) {
     ledger(firstCard, 'F040-deferred', 'LEFT-NON-DONE', `${deferredCards.join(' ')} — skill marks DONE post-run after follow-up materialises`)
     // F-040 guard — catch a merge agent that ignored the instruction and force-DONE'd a deferred card.
@@ -1543,20 +1628,67 @@ function buildTelemetry() {
   }
 }
 
+// v5.6.0 — residual severity (FEAT-0068 §3.2: residuals carried no severity, so a goal-void run
+// and a clean run produced the same headline). Explicit severity wins; else class-derived.
+function residualSeverity(r) {
+  if (r.severity) return String(r.severity).toUpperCase()
+  const cls = r.deferralClass || r.kind || ''
+  if (/^(scope-expansion|unresolved|ac-unmet|false-epic-closure|main-repo-contamination)$/.test(cls)) return 'HIGH'
+  if (/^\s*BLOCKER\b/i.test(String(r.evidence || ''))) return 'BLOCKER'
+  if (/^\s*HIGH\b/i.test(String(r.evidence || ''))) return 'HIGH'
+  if (/^(out-of-ownership|merge-artifact-skipped|out-of-scope|baseline-not-reached|outage)$/.test(cls)) return 'MEDIUM'
+  return 'LOW' // owner-gated / not-a-code-defect / policy-deferred-ac — external actions, tracked
+}
+
 function buildReport(o) {
   const L = []
   L.push(`# new2 batch — ${cardIds.join(' ')}`)
   L.push(`Variant: **new2** · Mode: sequential · Trunk: ${TRUNK}${degraded ? ' · ⚠️ DEGRADED (' + degradationReasons.join(',') + ')' : ''}`)
   if (o.fatal) { L.push(``, `## ⛔ BATCH FATAL`, o.reason || 'workspace unworkable'); return L.join('\n') }
+  // v5.6.0 PARTIAL verdict (FEAT-0068 §3.2) — the HARD headline rule: any BLOCKER/HIGH residual,
+  // any epic left open / blocklisted / falsely closed, or a false_done degradation ⇒ the FIRST
+  // line after the title says ⚠️ PARTIAL and names the gap. ✅ is RESERVED for zero-HIGH +
+  // no open epic. The FEAT-0068 report said "✅ 6/6 DONE" over a disclosed-but-buried HIGH gap;
+  // the defect was headline framing, and this is where the headline is built.
+  const sevRank = { BLOCKER: 3, HIGH: 2, MEDIUM: 1, LOW: 0 }
+  const highResiduals = residuals.filter((r) => (sevRank[residualSeverity(r)] || 0) >= 2)
+  const epicsInPlay = dedupe(cardGraph.map((n) => n.parentEpic || '').filter(Boolean).concat(cardGraph.filter((n) => n.isEpic).map((n) => n.id)))
+  const closedEpics = (mergeResult && mergeResult.epicsClosed) || []
+  const leftOpen = ((mergeResult && mergeResult.epicsLeftOpen) || []).filter((x) => x && x.epic)
+  const openEpics = epicsInPlay.filter((e) => !closedEpics.includes(e) || closureBlockedEpics.has(e))
+  const falseDone = degradationReasons.includes('false_done')
+  const partial = highResiduals.length > 0 || openEpics.length > 0 || falseDone
+  if (partial) {
+    const top = falseDone ? 'epic chiusa contro la blocklist (false DONE — da riaprire)'
+      : highResiduals.length ? `${residualSeverity(highResiduals[0])} residuo aperto: ${String(highResiduals[0].evidence || highResiduals[0].kind).slice(0, 140)}`
+      : `epic ${openEpics.join(' ')} NON chiusa (goal non ancora raggiunto/verificato)`
+    L.push(``, `## ⚠️ PARTIAL — obiettivo NON completamente raggiunto`)
+    L.push(`**${top}**`)
+    if (highResiduals.length) L.push(`Il lavoro sostanziale rimanente vive in ${highResiduals.filter((r) => r.materialized).length}/${highResiduals.length} follow-up già su disco — vedi § Residui. NON considerare la feature consegnata finché le follow-up HIGH non sono implementate.`)
+  } else {
+    L.push(``, `## ✅ COMPLETO`)
+    L.push(`Tutte le card committate, epic ${epicsInPlay.length ? 'chiuse con AC verificati' : 'non presenti'}, nessun residuo HIGH.`)
+  }
   L.push(``, `## Esito card`)
   L.push(`| Card | Status | Commit | File |`)
   L.push(`|------|--------|--------|------|`)
   for (const r of perCardResults) L.push(`| ${r.card} | ${r.status}${r.deferred ? ' (NON-DONE: deferred)' : ''} | ${r.commit || '-'} | ${(r.filesChanged || []).length} |`)
   const blockedIds = runnableCards.filter((id) => state[id] === 'blocked' || state[id] === 'pending')
   for (const id of blockedIds) L.push(`| ${id} | ${state[id]} | - | 0 |`)
+  // v5.6.0 Epic goal section — per-epic truth: closed/open + why + the open work attached to it.
+  if (epicsInPlay.length) {
+    L.push(``, `## Epic goal`)
+    for (const e of epicsInPlay) {
+      const reason = (leftOpen.find((x) => x.epic === e) || {}).reason
+      const epicHigh = residuals.filter((r) => ((graphById[r.card] && graphById[r.card].parentEpic) === e || r.card === e) && (sevRank[residualSeverity(r)] || 0) >= 2)
+      if (closedEpics.includes(e) && !closureBlockedEpics.has(e)) L.push(`- **${e}: CHIUSA** (children DONE + AC epic verificati dal merge agent)`)
+      else if (closedEpics.includes(e)) L.push(`- **${e}: ⚠️ CHIUSA CONTRO BLOCKLIST (false DONE)** — riaprire: ${epicHigh.length} residuo/i HIGH aperti`)
+      else L.push(`- **${e}: APERTA** — ${reason || (closureBlockedEpics.has(e) ? 'blocklist: residui/follow-up aperti' : 'merge non eseguito o children aperti')}${epicHigh.length ? ` · ${epicHigh.length} residuo/i HIGH` : ''}`)
+    }
+  }
   if (finalSummary) {
     L.push(``, `## Final review`)
-    L.push(`Verified: ${finalSummary.verified} (BLOCKER ${finalSummary.blockers} / HIGH ${finalSummary.highs}) · failing gates: ${(finalSummary.failingGates || []).join(', ') || 'none'}`)
+    L.push(`Verified: ${finalSummary.verified} (BLOCKER ${finalSummary.blockers} / HIGH ${finalSummary.highs}) · failing gates: ${(finalSummary.failingGates || []).join(', ') || 'none'}${closureInvalidating.length ? ` · closure-invalidating: ${closureInvalidating.length}` : ''}`)
   }
   L.push(``, `## Merge`)
   if (mergeResult && mergeResult.merged) L.push(`Merged → ${TRUNK} @ ${mergeResult.mergeCommit || '?'}${mergeResult.reconciliation ? ' · ' + mergeResult.reconciliation : ''}`)
@@ -1567,10 +1699,14 @@ function buildReport(o) {
     for (const m of man) L.push(`- [ ] ${m}`)
   }
   if (residuals.length) {
-    L.push(``, `## ⚠️ Residui (il skill materializza le follow-up mancanti — nulla perso)`)
+    // v5.6.0 — "nulla perso" is a tracking claim, not a completion claim: it may only headline
+    // when no HIGH residual exists (a HIGH follow-up is real work NOT delivered, not bookkeeping).
+    L.push(``, highResiduals.length
+      ? `## ⚠️ Residui — ATTENZIONE: ${highResiduals.length} HIGH+ = lavoro sostanziale NON consegnato (le follow-up sono il lavoro, non burocrazia)`
+      : `## Residui (bassa severità — il skill materializza le follow-up mancanti; nulla perso)`)
     const bd = residuals.reduce((b, x) => { const k = x.deferralClass || x.kind || 'unknown'; b[k] = (b[k] || 0) + 1; return b }, {})
     L.push(`Ripartizione per classe: ${Object.entries(bd).map(([k, n]) => `${k}=${n}`).join(' · ')} — una classe dominante è il segnale di causa (out-of-ownership → MAY-EDIT troppo strette · unresolved → fix difficili · scope-expansion → card sotto-specificate).`)
-    for (const f of residuals) L.push(`- ${f.card} (${f.kind})${f.materialized ? ' ✓' : ' — DA MATERIALIZZARE'}: ${f.evidence}`)
+    for (const f of residuals.slice().sort((a, b) => (sevRank[residualSeverity(b)] || 0) - (sevRank[residualSeverity(a)] || 0))) L.push(`- [${residualSeverity(f)}] ${f.card} (${f.kind})${f.materialized ? ' ✓' : ' — DA MATERIALIZZARE'}: ${f.evidence}`)
   }
   const excluded = gateLedger.filter((x) => x.decision === 'EXCLUDED')
   if (excluded.length) { L.push(``, `## Card escluse in pre-flight`); for (const e of excluded) L.push(`- ${e.card}: ${e.detail}`) }

package/framework/agents/card-schema.md

@@ -57,7 +57,7 @@ Legend: **R** = required, present **and non-empty** · **E** = required key, val
 | `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; CHILD/STANDALONE: faithfully derivable from AC+scope when both present — see consumer contract |
 | `acceptance_criteria` | R (AC-EPIC) | R | R | CHILD/STANDALONE: EARS grammar — see § "Acceptance-criteria grammar (EARS)" |
-| `ac_verification` | — | C | C | OPTIONAL map `AC-N → executable oracle` (or `manual: <check>`); authored by `/prd`, executed by `/new` Phase 2.5 — see § below |
+| `ac_verification` | R (≥1 per goal AC, v5.6.0) | C | C | EPIC: REQUIRED — ≥1 executable oracle (or `manual:`) per top-level goal AC, consumed by the epic-closure gate; CHILD/STANDALONE: OPTIONAL map `AC-N → executable oracle` (or `manual: <check>`); authored by `/prd`, executed by `/new` Phase 2.5 — see § below |
 | `definition_of_done` | R | R | R | |
 | `depends_on` / `blocks` | E (`[]`) | E | E | |
 | `estimated_complexity` | C | R | R | |
@@ -131,6 +131,23 @@ downstream cost in a real batch:
   when most cards omit it). The back-fill stays as the safety net for legacy cards; a freshly
   authored `/prd` card must not trigger it.
 
+- **Epic goal ACs are machine-checkable (v5.6.0 — FEAT-0068).** The epic's `[AC-EPIC-N]`
+  items: (1) NEVER hardcode a child count ("Tutte le 6 sub-card" broke the moment follow-up
+  cards appeared — write "all child cards including any added later"); (2) an AC with a
+  **universal quantifier over a surface** ("every screen", "tutte le route", "nessun seam su
+  ogni pagina") must carry `invariant_owners:` — the surface's owner components resolved from
+  the fresh registry/ISA census — so the epic-closure gate can verify the owners' coverage
+  instead of trusting the child count; (3) the epic carries `ac_verification` with ≥1
+  executable oracle per goal AC (field-state matrix above). An epic whose goal cannot be
+  checked is an epic that closes on bookkeeping — the FEAT-0068 epic closed DONE with all 7
+  ACs unchecked and the goal unmet on ~90% of its surface.
+- **Snapshot-suite lifecycle (v5.6.0 — FEAT-0068).** A card that CREATES a visual-regression /
+  snapshot / screenshot-diff suite MUST declare the baseline lifecycle: EITHER "baselines
+  generated and committed in-card" (the generate command in `validation_commands`, the baseline
+  dir in `files_likely_touched`) OR "assertion-based, screenshots advisory". "Baselines arrive
+  later", undeclared, is an authoring BLOCKER — it detonates as a merge-blocker and invites a
+  repair that disables the suite (`/new` completeness Phase 2.5 step 1b enforces the read-side).
+
 A back-fill never rescues a card missing a HALT field: a card without `scope` blocks regardless
 of how many derivable fields were filled.
 

package/framework/agents/research-protocol.md

@@ -38,7 +38,12 @@ dependency.
 The `PROFILE=<decision|deep|compare|regulatory>` token in the spawn prompt
 selects the research contract. **Token absent → `deep`** (preserves the legacy
 full-report semantics for direct invocation and for existing spawners that
-pass no token).
+pass no token). **Defense-in-depth (v5.6.0):** when spawned WITHOUT a `PROFILE`
+token, the agent runs the SECTION: reuse library pre-flight ITSELF before
+searching (a caller that forgot the token also forgot the pre-flight — on a
+real `/prd` session the research ran contract-less and the library reuse loop
+silently no-oped), and states in the report where the output landed
+(`${paths.research_dir}` path) so the caller never hunts for it.
 
 | Profile | Typical consumer | Output contract | Depth |
 |---|---|---|---|

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.5.0",
+  "version": "5.6.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"