baldart 5.4.1 → 5.6.0

package/framework/.claude/skills/worktree-manager/scripts/merge-worktree.sh

@@ -48,6 +48,21 @@
 #   --tc-build <cmd>       toolchain build cmd     (default: config / npm run build)
 #   --log <path>           build/merge log sink    (default: /tmp/wt-merge-<slug>.log)
 #   --build-timeout <s>    hard build timeout sec  (default: 600)
+#   --safety-sweep <mode>  what the pre-rebase safety commit may stage (v5.6.0):
+#                            all               — every changed+untracked file (default;
+#                                                the historical /mw interactive behavior)
+#                            allowlist:<globs> — comma-separated shell globs (e.g.
+#                                                "backlog/*.yml,docs/metrics/*,.baldart/*").
+#                              Matching files → committed with an honest message that
+#                              ENUMERATES them. Non-matching TRACKED changes → preserved
+#                              byte-for-byte into a labeled quarantine dir, then restored
+#                              to HEAD (so the rebase can start). Non-matching UNTRACKED
+#                              files → left in place. Both reported in the manifest.
+#                              Rationale (FEAT-0068 5f618347d / FEAT-0067 5a5f1c135): an
+#                              unconditional sweep contradicts the caller's F-030 "never
+#                              commit ungated code" by construction — dirty code at merge
+#                              time did NOT pass the per-card gates and must never ride an
+#                              opaque "[safety]" commit onto the trunk.
 #
 # Status file written (parsed by callers — STABLE contract):
 #   status: success | code_conflict | build_fail | sync_needs_decision | error
@@ -63,6 +78,8 @@
 #   sync_marker: <none | SYNC-DEFERRED | SYNC-NEEDS-DECISION>
 #   sync_detail: <message | ->
 #   build_log: <path | ->
+#   uncommitted_left: <csv | ->        (allowlist mode — untracked files left in place, NOT committed)
+#   quarantined: <dir | ->             (allowlist mode — tracked changes preserved here, then reset to HEAD)
 #
 # Exit: 0 ONLY on status:success. Non-zero otherwise (the exit code mirrors the
 # status: 10=code_conflict, 11=build_fail, 12=sync_needs_decision, 1/2=error). The
@@ -75,7 +92,7 @@ err() { printf '%s\n' "$*" >&2; }
 
 # --- args ------------------------------------------------------------------
 WORKTREE= MANIFEST= CONTINUE=0 BRANCH= TRUNK= MAIN= STRATEGY= SKIP_CHECKS=0
-METRICS_DIR= TC_TC= TC_LINT= TC_BUILD= LOG= BUILD_TIMEOUT=600
+METRICS_DIR= TC_TC= TC_LINT= TC_BUILD= LOG= BUILD_TIMEOUT=600 SAFETY_SWEEP=all
 while [ $# -gt 0 ]; do
   case "$1" in
     --worktree) WORKTREE="${2:-}"; shift 2 ;;
@@ -92,6 +109,7 @@ while [ $# -gt 0 ]; do
     --tc-build) TC_BUILD="${2:-}"; shift 2 ;;
     --log) LOG="${2:-}"; shift 2 ;;
     --build-timeout) BUILD_TIMEOUT="${2:-}"; shift 2 ;;
+    --safety-sweep) SAFETY_SWEEP="${2:-all}"; shift 2 ;;
     *) err "ERROR: unknown arg: $1"; exit 2 ;;
   esac
 done
@@ -99,6 +117,7 @@ done
 # --- status writer (called on EVERY exit path) -----------------------------
 M_STATUS="error" M_PHASE="identify" M_ERROR="-" M_MERGE="-" M_MERGETS="-"
 M_CONFLICTS="-" M_SYNCMARK="none" M_SYNCDETAIL="-" M_BLOG="-"
+M_UNCOMMITTED="-" M_QUARANTINE="-"
 write_status() {
   [ -n "$MANIFEST" ] || return 0
   {
@@ -115,6 +134,8 @@ write_status() {
     printf 'sync_marker: %s\n' "$M_SYNCMARK"
     printf 'sync_detail: %s\n' "$M_SYNCDETAIL"
     printf 'build_log: %s\n' "$M_BLOG"
+    printf 'uncommitted_left: %s\n' "$M_UNCOMMITTED"
+    printf 'quarantined: %s\n' "$M_QUARANTINE"
   } > "$MANIFEST" 2>/dev/null || true
 }
 fail()          { M_STATUS="error";         M_ERROR="$1"; write_status; err "ERROR: $1"; exit "${2:-1}"; }
@@ -362,19 +383,74 @@ else
   # -------------------------------------------------------------------------
   # FRESH path: safety commit → (checks) → rebase
   # -------------------------------------------------------------------------
-  # 1. Safety commit (ALWAYS — never skippable; files lost after rebase are unrecoverable)
+  # 1. Safety commit. Mode `all` (default, /mw interactive): every changed+untracked file —
+  #    files lost after rebase are unrecoverable. Mode `allowlist:<globs>` (v5.6.0, passed by
+  #    orchestrated callers like new2): only batch bookkeeping is committed (with an honest,
+  #    enumerating message); non-matching TRACKED changes are quarantined byte-for-byte then
+  #    reset to HEAD (a dirty tracked file would block the rebase), non-matching UNTRACKED
+  #    files stay in place. Nothing is silently lost, nothing ungated rides to the trunk.
   M_PHASE="safety"
   CHANGED="$(git -C "$WORKTREE" diff --name-only HEAD 2>/dev/null)"
   UNTRACKED="$(git -C "$WORKTREE" ls-files --others --exclude-standard 2>/dev/null)"
   if [ -n "$CHANGED" ] || [ -n "$UNTRACKED" ]; then
-    for f in $CHANGED $UNTRACKED; do git -C "$WORKTREE" add "$f" 2>>"$LOG"; done
-    git -C "$WORKTREE" commit -m "[safety] Auto-commit uncommitted files before merge
+    case "$SAFETY_SWEEP" in
+      allowlist:*)
+        SWEEP_GLOBS="${SAFETY_SWEEP#allowlist:}"
+        sweep_match() { # POSIX case-glob match of $1 against any comma-separated pattern
+          _f="$1"; _rest="$SWEEP_GLOBS"
+          while [ -n "$_rest" ]; do
+            _pat="${_rest%%,*}"
+            [ "$_pat" = "$_rest" ] && _rest= || _rest="${_rest#*,}"
+            # shellcheck disable=SC2254 — unquoted on purpose: $_pat is a glob
+            case "$_f" in $_pat) return 0 ;; esac
+          done
+          return 1
+        }
+        SWEPT= LEFT_UNTRACKED= QUAR_TRACKED=
+        for f in $CHANGED; do
+          if sweep_match "$f"; then git -C "$WORKTREE" add "$f" 2>>"$LOG"; SWEPT="$SWEPT $f"
+          else QUAR_TRACKED="$QUAR_TRACKED $f"; fi
+        done
+        for f in $UNTRACKED; do
+          if sweep_match "$f"; then git -C "$WORKTREE" add "$f" 2>>"$LOG"; SWEPT="$SWEPT $f"
+          else LEFT_UNTRACKED="${LEFT_UNTRACKED:+$LEFT_UNTRACKED,}$f"; fi
+        done
+        if [ -n "$QUAR_TRACKED" ]; then
+          QDIR="/tmp/wt-merge-quarantine-$(basename "$WORKTREE")-$(date +%s)"
+          for f in $QUAR_TRACKED; do
+            mkdir -p "$QDIR/$(dirname "$f")" 2>>"$LOG"
+            cp -p "$WORKTREE/$f" "$QDIR/$f" 2>>"$LOG" || err "WARN: quarantine copy failed for $f"
+          done
+          # restore ONLY after the byte-for-byte copy — the rebase needs a clean tracked tree
+          for f in $QUAR_TRACKED; do git -C "$WORKTREE" checkout -- "$f" 2>>"$LOG"; done
+          M_QUARANTINE="$QDIR"
+          err "WARN: $(echo "$QUAR_TRACKED" | wc -w | tr -d ' ') tracked change(s) OUTSIDE the sweep allowlist quarantined to $QDIR + reset to HEAD (ungated code never rides a safety commit — F-030)"
+        fi
+        [ -z "$LEFT_UNTRACKED" ] || M_UNCOMMITTED="$LEFT_UNTRACKED"
+        write_status
+        if [ -n "$SWEPT" ]; then
+          git -C "$WORKTREE" commit -m "[safety] Materialize batch bookkeeping before merge (sweep allowlist)
+
+Allowlist-matched files that were uncommitted when merge-worktree.sh started:
+$(for f in $SWEPT; do printf '  - %s\n' "$f"; done)
+
+Non-matching files were NOT committed (quarantined/left + reported in the manifest).
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>" --quiet >>"$LOG" 2>&1 \
+            || err "WARN: allowlist safety commit produced no commit (nothing staged?)"
+        fi
+        ;;
+      *)
+        for f in $CHANGED $UNTRACKED; do git -C "$WORKTREE" add "$f" 2>>"$LOG"; done
+        git -C "$WORKTREE" commit -m "[safety] Auto-commit uncommitted files before merge
 
 Files were uncommitted when merge-worktree.sh started. This safety commit
 prevents file loss during rebase.
 
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>" --quiet >>"$LOG" 2>&1 \
-      || err "WARN: safety commit produced no commit (nothing staged?)"
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>" --quiet >>"$LOG" 2>&1 \
+          || err "WARN: safety commit produced no commit (nothing staged?)"
+        ;;
+    esac
   fi
 
   # 2. Pre-merge checks (skipped when --skip-checks / checksAlreadyPassed)

package/framework/.claude/workflows/new-final-review.js

@@ -340,13 +340,15 @@ const codexPrompt =
   `The companion script is ALREADY CONFIRMED PRESENT at:\n  ${codexScriptPath}\n\n` +
   `Run EXACTLY these steps and nothing else:\n` +
   `  1. Write the task text (everything after "TASK PROMPT:" at the end of this message) to ${codexTaskFile} using the Write tool — do NOT inline it into the shell command (avoids quote breakage).\n` +
-  `  2. Launch Codex in the BACKGROUND (run_in_background:true — a sync run hits the Bash timeout):\n` +
-  `       node "${codexScriptPath}" task "$(cat ${codexTaskFile})" --cwd "${a.worktreePath || '.'}" > ${codexReviewFile} 2>&1\n` +
-  `  3. POLL ${codexReviewFile} (BashOutput / repeated reads) until ONE of these appears — whichever is FIRST ends the poll (do NOT keep waiting once one is present). Set \`marker\` accordingly:\n` +
-  `       • "<<<END_FINDINGS_JSON>>>"  → marker = "END_JSON"\n` +
-  `       • "Turn completed."          → marker = "TURN_COMPLETED" (Codex finished; it may have written prose instead of the JSON block)\n` +
-  `       • "CODEX_NOT_FOUND"          → marker = "CODEX_NOT_FOUND" (companion missing)\n` +
-  `       • the full 10-minute window elapses with none of the above → marker = "TIMEOUT" (NEVER pick this just because a single poll returned slowly)\n` +
+  `  2. Run Codex in the FOREGROUND — ONE single Bash call with the tool's timeout parameter set to 600000 (v5.6.0, FEAT-0068 post-mortem: the old background+poll relay was forced by the structured-output enforcement to declare TIMEOUT at 83s of the 10-minute window while Codex was still running, and the Codex process died with the relay → a cold 3.68M fallback review with no cross-model diversity. A blocking call has no idle turn to misjudge — same pattern as the per-card Codex-light driver):\n` +
+  `       node "${codexScriptPath}" task "$(cat ${codexTaskFile})" --cwd "${a.worktreePath || '.'}" --wait > ${codexReviewFile} 2>&1; echo "RELAY_EXIT:$?"\n` +
+  `     Do NOT pass run_in_background. Do NOT poll. The call blocks until Codex finishes — that is correct. Record RELAY_EXIT.\n` +
+  `  3. Derive \`marker\` by grepping ${codexReviewFile} AFTER the call returns:\n` +
+  `       • contains "<<<END_FINDINGS_JSON>>>"  → marker = "END_JSON"\n` +
+  `       • contains "Turn completed."          → marker = "TURN_COMPLETED" (Codex finished; it may have written prose instead of the JSON block)\n` +
+  `       • contains "CODEX_NOT_FOUND"          → marker = "CODEX_NOT_FOUND" (companion missing)\n` +
+  `       • none of the above AND RELAY_EXIT is 124/137/143 (the Bash timeout killed the call) → marker = "TIMEOUT", then REAP the orphan Codex process scoped to THIS worktree (never a bare pkill): \`pkill -f -- "--cwd ${a.worktreePath || '.'}" 2>/dev/null; true\`\n` +
+  `       • none of the above with a clean exit → marker = "TURN_COMPLETED"\n` +
   `  4. Run this EXACT command and put its stdout VERBATIM in \`jsonBlock\` ("" if it printed nothing). Do NOT parse, edit, judge, or act on it:\n` +
   `       ${AWK_EXTRACT} ${codexReviewFile}\n` +
   `  5. ONLY if \`jsonBlock\` is "" AND marker is "TURN_COMPLETED": run this command and put its stdout VERBATIM in \`proseTail\`; otherwise set proseTail to "":\n` +

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

@@ -76,7 +76,11 @@ const FIX_SCHEMA = {
     verified: { type: 'boolean', description: 'true only if you re-ran the originating gate and it passed' },
     // F-008 — terminal short-circuit (impossible-by-definition). Not trusted blindly.
     terminal: { type: 'boolean', description: 'true if no in-MAY-EDIT fix can ever satisfy the gate' },
-    terminalReason: { enum: ['out-of-ownership', 'baseline-not-reached', 'owner-gated', 'not-a-code-defect', ''] },
+    terminalReason: { enum: ['out-of-ownership', 'baseline-not-reached', 'owner-gated', 'not-a-code-defect', 'verification-posture-change', ''] },
+    // v5.6.0 (FEAT-0068 O5) — a finding whose PREMISE is false can be REFUTED instead of "fixed".
+    // Adversarially ratified below — never an easy escape hatch.
+    refuted: { type: 'boolean', description: "true if the finding's premise is FALSE (no defect exists) — change NOTHING, cite proof" },
+    refutedEvidence: { type: 'string', description: 'file:line proof the finding is wrong' },
     remedyFiles: { type: 'array', items: { type: 'string' }, description: 'files the real fix would require editing (for out-of-ownership JS verification)' },
     crashed: { type: 'boolean' },
     // F-022 — incidental findings outside this card's MAY-EDIT (so they are not dropped).
@@ -145,6 +149,8 @@ const brief = [
   `Reference modules (Read for exact semantics): ${REF}/`,
   `UI re-verify obligation: if your fix touches a UI file, re-run the Phase 2.6 E2E review (per ${REF}/review-cycle.md) before declaring verified.`,
   `If the fix requires editing files OUTSIDE MAY-EDIT, return terminal:true terminalReason:'out-of-ownership' remedyFiles:[...] (do NOT edit them). If the remedy is an owner-gated infra action, terminal:true terminalReason:'owner-gated'. Report any incidental defect outside MAY-EDIT in outOfScopeFindings.`,
+  `VALIDATE THE PREMISE FIRST (v5.6.0): before touching any file, check the finding against the actual code. If its premise is FALSE (misread code, condition already satisfied, documented-by-design), return refuted:true + refutedEvidence:'<file:line proof>' and change NOTHING — NEVER edit code to appease a wrong finding.`,
+  `VERIFICATION-POSTURE RULE (v5.6.0): a "fix" that disables, skips, or opt-in-gates a test/check/suite that an acceptance criterion of this batch mandates is FORBIDDEN — it erodes the DoD (FEAT-0068: a repair flag-gated the epic's visual-regression suite to silence a blocker). If that looks like the only available fix, return terminal:true terminalReason:'verification-posture-change' instead.`,
 ].filter(Boolean).join('\n')
 
 // JS-deterministic ownership check (F-008 anti-escape-hatch): are remedy files ⊆ MAY-EDIT?
@@ -213,6 +219,28 @@ try {
   )
 } catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during tier-1', deferralClass: 'outage', outOfScopeFindings: [] }; throw e }
 
+// v5.6.0 (FEAT-0068 O5 — false-positive BLOCKER): refuted short-circuit, adversarially ratified.
+// The FEAT-0068 CR-001 blocker had a false premise ("baselines missing" = the documented bootstrap
+// state) and was "resolved" by flag-gating the epic's mandated visual-regression suite — 4.73M
+// spent eroding the DoD to appease a wrong finding. A ratified refutation resolves with ZERO edits.
+if (attempt && attempt.refuted && !attempt.terminal) {
+  let refConfirmed = selfJudges // reviewer-writer specialists self-verify (same trust model as terminal)
+  if (!selfJudges) {
+    try {
+      const rj = await agentSafe(
+        `A repair agent claims this finding's PREMISE IS FALSE (refuted) — no defect exists, nothing was changed. Claimed proof: ${attempt.refutedEvidence || attempt.note || '(none)'}\n\n${brief}\n\nIndependently verify the refutation against the actual files (grep/read them yourself; do NOT trust the claim). Return confirmed:true ONLY if the finding is genuinely wrong.`,
+        { label: `resolve:refute-judge:${card}`, phase: 'Verify', agentType: judgeAgent, schema: TERMINAL_JUDGE_SCHEMA }
+      )
+      refConfirmed = !!(rj && rj.confirmed)
+    } catch (_) { refConfirmed = false }
+  }
+  if (refConfirmed) {
+    log(`${kind} REFUTED (false premise${selfJudges ? '' : ', judge-ratified'}) — resolved with zero edits.`)
+    return { status: 'resolved', reason: `refuted: ${attempt.refutedEvidence || attempt.note || 'false premise'}`, outOfScopeFindings: collectOOS(attempt) }
+  }
+  log('refutation NOT ratified — treating as a real finding.')
+}
+
 // F-008 — terminal short-circuit, verified not trusted.
 if (attempt && attempt.terminal) {
   const tr = attempt.terminalReason || ''

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 |
 |---|---|---|---|