loopforge 3.6.0 → 3.7.1

package/dist/verification-gate.js

@@ -11,26 +11,41 @@
  *                 this round is excluded from the success trend (NOT
  *                 modified). Flags become hard constraints — the agent
  *                 must respond in the next round.
+ *
+ * v3.7: every check belongs to one of four verification domains (CHECK_DOMAIN
+ * below): evaluation consistency / evidence integrity / plan & contract /
+ * progress & recovery. A domain describes a check's semantic job — it never
+ * changes run order or verdict aggregation. Round Contract checks are further
+ * framed as declaration / execution / closure stages in their doc comments.
  */
 import { getPolicy, isConfiguredCommand } from "./policy.js";
 import { makeVerificationFlag, makeVerificationResult } from "./protocol.js";
-import { jaccardSimilarity, tokenize, entryRound as sharedEntryRound, isRecord } from "./token-utils.js";
+import { jaccardSimilarity, tokenize, isRecord, entryRound, extractFilePathTokens } from "./token-utils.js";
 import { deriveSubGoalId } from "./loop-compiler.js";
-import { committedRoundsFromEntries, machineGitMotionSeries } from "./committed-round.js";
+import { committedRoundsFromEntries, entrySubGoalUpdates, machineGitMotionSeries, entryViolations, } from "./committed-round.js";
 import { contractRoundEvaluations, contractDoneWhenSatisfied, contractItemMatches, deriveActiveRoundContract, } from "./round-contract.js";
 import { stableStringify } from "./canonical-state.js";
 import { deriveClaimView, resolveRoundFiles } from "./evidence-claims.js";
 import { effectiveSuccess, parseRoundContract } from "./self-eval.js";
+import { deriveGate, preflightStructuredGate } from "./cognitive-governance.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // v2.12: Check-name constants — single source of truth so the enforcement
 // gate and audit can reference checks without string-literal drift.
+//
+// v3.7: every check belongs to one of four verification domains (CHECK_DOMAIN
+// below). The flag set was converged from 27 to 24:
+// - progress_regression removed — self-report-only decoration; machine-side
+//   progress policing lives in the enforcement gate's progress stall row.
+// - empty_change_with_passing removed — success without machine backing is
+//   already covered by the success-evidence arms below.
+// - success_claim_conflict merged into outcome_success_contradiction.
 // ═══════════════════════════════════════════════════════════════════════════
-export const CHECK_PROGRESS_REGRESSION = "progress_regression";
-export const CHECK_EMPTY_CHANGE_WITH_PASSING = "empty_change_with_passing";
 export const CHECK_SUCCESS_WITH_REMAINING_CRITERIA = "success_with_remaining_criteria";
 export const CHECK_SUCCESS_WITHOUT_VERIFIED_EVIDENCE = "success_without_verified_evidence";
+// v3.7: single id for the outcome-vs-success axis — error when a declared
+// success contradicts success=false, warn when success=true but the outcome
+// declares a non-success (the former success_claim_conflict direction).
 export const CHECK_OUTCOME_SUCCESS_CONTRADICTION = "outcome_success_contradiction";
-export const CHECK_SUCCESS_CLAIM_CONFLICT = "success_claim_conflict";
 export const CHECK_BLOCKED_WITHOUT_BLOCKER = "blocked_without_blocker";
 export const CHECK_RETROACTIVE_CLAIM_BAD_ROUND = "retroactive_claim_bad_round";
 export const CHECK_RETROACTIVE_CLAIM_UNVERIFIED = "retroactive_claim_unverified";
@@ -62,6 +77,13 @@ export const CHECK_CRITERIA_CLAIMS_UNVERIFIED = "criteria_claims_unverified";
 // silent when their target is absent: contract-less rounds behave exactly
 // as before these checks existed, and round 1 (no committed rounds → no
 // active contract) never produces declaration off-by-one noise.
+// v3.7: the checks are framed as three contract stages — Declaration
+// (proposal quality: round_underspecified / round_unverifiable /
+// contract_premature), Execution (conformance under the ACTIVE contract:
+// round_scope_drift; premature_boundary's silently-dropped arm), Closure
+// (completion truth: contract_completion_unverified; premature_boundary's
+// claimed-met-unverified arm). The framing is documentation only — no phase
+// field exists on the contract.
 /** Contract proposed with an empty done_when — nothing is promised, so
  *  nothing can be verified at the boundary. Warn: the contract can be fixed
  *  by re-declaring next round. */
@@ -91,25 +113,45 @@ export const CHECK_CONTRACT_COMPLETION_UNVERIFIED = "contract_completion_unverif
  *  the active one closes. Warn: the walker still ignores it; this only
  *  surfaces the otherwise-silent state. */
 export const CHECK_CONTRACT_PREMATURE = "contract_premature";
+/** v3.7.1: A cited gate (evaluation.gate_ids) is not approved. Opt-in:
+ *  checked ONLY when policy.gate.enabled — citations are meaningless when
+ *  the gate layer is off. Error → enforcement rejects the round. */
+export const CHECK_USER_GATE_UNRESOLVED = "user_gate_unresolved";
+export const CHECK_DOMAIN = {
+    // ── evaluation_consistency ────────────────────────────────────────────────
+    [CHECK_SUCCESS_WITH_REMAINING_CRITERIA]: "evaluation_consistency",
+    [CHECK_OUTCOME_SUCCESS_CONTRADICTION]: "evaluation_consistency",
+    [CHECK_BLOCKED_WITHOUT_BLOCKER]: "evaluation_consistency",
+    [CHECK_RETROACTIVE_CLAIM_BAD_ROUND]: "evaluation_consistency",
+    [CHECK_RETROACTIVE_CLAIM_UNVERIFIED]: "evaluation_consistency",
+    [CHECK_DUPLICATE_CONSTRAINT_DISCOVERY]: "evaluation_consistency",
+    [CHECK_RECURRING_VIOLATION]: "evaluation_consistency",
+    [CHECK_RETRACT_FRESH_CONSTRAINT]: "evaluation_consistency",
+    // ── evidence_integrity ────────────────────────────────────────────────────
+    [CHECK_SUCCESS_WITHOUT_VERIFIED_EVIDENCE]: "evidence_integrity",
+    [CHECK_CRITERIA_CLAIMS_UNVERIFIED]: "evidence_integrity",
+    [CHECK_EVIDENCE_INTEGRITY]: "evidence_integrity",
+    [CHECK_REQUIRED_COMMAND_FAILED]: "evidence_integrity",
+    [CHECK_COMMAND_EVIDENCE_MISMATCH]: "evidence_integrity",
+    [CHECK_VERIFICATION_ENTRYPOINT_MODIFIED]: "evidence_integrity",
+    [CHECK_TEST_FILES_MODIFIED]: "evidence_integrity",
+    // ── plan_contract ─────────────────────────────────────────────────────────
+    [CHECK_INTENT_DRIFT]: "plan_contract",
+    [CHECK_SUBGOAL_DRIFT]: "plan_contract",
+    [CHECK_ROUND_UNDERSPECIFIED]: "plan_contract",
+    [CHECK_ROUND_UNVERIFIABLE]: "plan_contract",
+    [CHECK_ROUND_SCOPE_DRIFT]: "plan_contract",
+    [CHECK_PREMATURE_BOUNDARY]: "plan_contract",
+    [CHECK_CONTRACT_COMPLETION_UNVERIFIED]: "plan_contract",
+    [CHECK_CONTRACT_PREMATURE]: "plan_contract",
+    // v3.7.1: cited-gate authorization conformance (opt-in blocking layer).
+    [CHECK_USER_GATE_UNRESOLVED]: "plan_contract",
+    // ── progress_recovery ─────────────────────────────────────────────────────
+    [CHECK_BACKTRACK_WORKSPACE_NOT_RESTORED]: "progress_recovery",
+};
 // ═══════════════════════════════════════════════════════════════════════════
 // Helpers
 // ═══════════════════════════════════════════════════════════════════════════
-/** Extract the round number from a vault entry's loop_lineage.
- *  Returns 0 if the entry has no lineage or no round field.
- *  In practice, persistLoopLineage always writes round ≥ 1, so 0
- *  unambiguously means "not a valid round entry" in this context.
- *  Exported for reuse by enforcement-gate.ts. */
-export function entryRound(entry) {
-    return sharedEntryRound(entry);
-}
-/** Read constraint_violations from a vault entry (entry-level, stored from
- *  the previous round's last_round_result at persist time). */
-function entryViolations(entry) {
-    const viols = entry.constraint_violations;
-    if (Array.isArray(viols))
-        return viols.filter((v) => typeof v === "string");
-    return [];
-}
 // ── v3.3: Round Contract scope matching ─────────────────────────────────────
 /** Normalize a contract scope entry: backslashes → forward slashes, strip
  *  leading "./", trim, strip trailing slashes. "." / "./" / "" normalize to
@@ -248,44 +290,6 @@ export function machineProgressSeries(vaultEntries, currentRound, lookback) {
 // ═══════════════════════════════════════════════════════════════════════════
 // Individual checks — each returns a VerificationFlag or null
 // ═══════════════════════════════════════════════════════════════════════════
-function checkProgressRegression(selfEval, prevSelfEval) {
-    if (!prevSelfEval?.execution_evidence)
-        return null;
-    if (!selfEval.execution_evidence)
-        return null;
-    const prevProgress = prevSelfEval.execution_evidence.progress_estimate;
-    const currProgress = selfEval.execution_evidence.progress_estimate;
-    if (typeof prevProgress !== "number" || typeof currProgress !== "number")
-        return null;
-    // Use delta with epsilon to avoid IEEE 754 rounding issues (0.8 - 0.2 > 0.6 in float)
-    if (prevProgress - currProgress <= 0.2 + 1e-10)
-        return null;
-    return makeVerificationFlag({
-        severity: "warn",
-        field: "progress_estimate",
-        check: CHECK_PROGRESS_REGRESSION,
-        detail: `Progress dropped from ${prevProgress.toFixed(2)} to ` +
-            `${currProgress.toFixed(2)} (delta: ${(currProgress - prevProgress).toFixed(2)})`,
-    });
-}
-function checkEmptyChangeWithPassing(selfEval) {
-    const ev = selfEval.execution_evidence;
-    if (!ev)
-        return null;
-    const filesEmpty = ev.files_changed.length === 0;
-    const testsAllPass = ev.test_results !== null &&
-        ev.test_results.failed === 0 &&
-        ev.test_results.passed > 0;
-    if (!filesEmpty || !testsAllPass || !effectiveSuccess(selfEval))
-        return null;
-    return makeVerificationFlag({
-        severity: "warn",
-        field: "execution_evidence",
-        check: CHECK_EMPTY_CHANGE_WITH_PASSING,
-        detail: "Agent claims success with no files changed and all tests passing — " +
-            "verify that work was actually performed",
-    });
-}
 function checkSuccessWithRemainingCriteria(selfEval) {
     if (!effectiveSuccess(selfEval))
         return null;
@@ -319,10 +323,12 @@ function checkUnverifiedCriteriaClaims(selfEval, claimView) {
             "(no passing test evidence or command snapshot)",
     });
 }
-/** Declared outcome vs the core success flag. A declared success with
- *  success=false is a self-contradiction (error); a declared non-success with
- *  success=true is an inconsistent claim (warn). Also: outcome==="blocked"
- *  without a blocker description gets a warn so the next prompt asks for it. */
+/** Declared outcome vs the core success flag — one check id for the whole
+ *  axis (v3.7: the former success_claim_conflict warn direction merged here).
+ *  A declared success with success=false is a self-contradiction (error);
+ *  success=true with a non-success outcome is an inconsistent claim (warn).
+ *  Also: outcome==="blocked" without a blocker description gets a warn so the
+ *  next prompt asks for it. */
 function checkOutcomeConsistency(selfEval) {
     const outcome = selfEval.outcome;
     if (outcome === "success" && selfEval.success === false) {
@@ -337,7 +343,7 @@ function checkOutcomeConsistency(selfEval) {
         return makeVerificationFlag({
             severity: "warn",
             field: "success",
-            check: CHECK_SUCCESS_CLAIM_CONFLICT,
+            check: CHECK_OUTCOME_SUCCESS_CONTRADICTION,
             detail: `outcome=${outcome} but success=true — the declared outcome wins`,
         });
     }
@@ -385,7 +391,7 @@ function checkRetroactiveClaims(selfEval, vaultEntries, currentRound) {
             }));
             continue;
         }
-        const paths = extractFilePaths(claim.claim);
+        const paths = extractFilePathTokens(claim.claim);
         const unverified = paths.filter((path) => !observed.some((file) => file === path || file.endsWith(path) || path.endsWith(file)));
         if (paths.length > 0 && unverified.length > 0) {
             flags.push(makeVerificationFlag({
@@ -401,25 +407,59 @@ function checkRetroactiveClaims(selfEval, vaultEntries, currentRound) {
     // hid all but the first problem until the next round.
     return flags.length > 0 ? flags : null;
 }
-/** v2.12/v3.6: success without a machine-verified observation. The agent
- *  claims completion but the runtime observed no machine evidence for it.
- *  v3.6: the trigger is the runtime-derived providerStatus (verified /
- *  unavailable / absent) — the v3.2 success_unverified check merged here.
- *  ProviderStatus "verified" requires an UNTAMPERED passed after-command, so
- *  an entrypoint-tampered command no longer counts as machine evidence
- *  (that coverage previously lived in success_unverified alone); the check
- *  never self-skips on the heuristic-extraction path. Severity follows
- *  evidence.machine_backed_success — "required" rejects (error), "warn"
- *  tolerates with a warn (round commits, success excluded from the
- *  trajectory, trust drops). A declared no_change_reason is the honest
- *  escape hatch: it downgrades to info. no_change_reason is honored HERE
- *  ONLY — contract checks refuse it (v3.6). */
+/** v2.12/v3.6/v3.7: success without machine backing — the single
+ *  "success evidence" semantic. Two arms, evaluated in order:
+ *  1. Empty/missing-evidence arm (v3.7: absorbed the enforcement-only
+ *     empty_success rule): success=true with NO execution_evidence at all, or
+ *     with files_changed empty AND test_results null, is an error
+ *     unconditionally — BEFORE the providerStatus early-exit, so a passed
+ *     command never rescues it (execution_evidence stays mandatory), and
+ *     neither evidence.machine_backed_success "warn" nor a declared
+ *     no_change_reason downgrades it ("no change" with literally no evidence
+ *     recorded is still an unbacked claim).
+ *  2. Claims arm (v3.6): success=true but the runtime observed no machine
+ *     evidence for it. The trigger is the runtime-derived providerStatus
+ *     (verified / unavailable / absent) — "verified" requires an UNTAMPERED
+ *     passed after-command, so an entrypoint-tampered command no longer
+ *     counts as machine evidence. Severity follows evidence.machine_backed_
+ *     success — "required" rejects (error), "warn" tolerates with a warn
+ *     (round commits, success excluded from the trajectory, trust drops). A
+ *     declared no_change_reason is the honest escape hatch: it downgrades to
+ *     info — honored only while NO enabled verification command is
+ *     configured (machine verification was structurally impossible); a
+ *     configured command closes the escape. no_change_reason is honored HERE
+ *     ONLY — contract checks refuse it. */
 function checkSuccessWithoutVerifiedEvidence(selfEval, status) {
     if (!effectiveSuccess(selfEval))
         return null;
+    // v3.7: empty/missing-evidence arm (ex-R3 empty_success posture).
+    const ev = selfEval.execution_evidence;
+    if (!ev || (ev.files_changed.length === 0 && ev.test_results === null)) {
+        return makeVerificationFlag({
+            severity: "error",
+            field: "success",
+            check: CHECK_SUCCESS_WITHOUT_VERIFIED_EVIDENCE,
+            detail: ev
+                ? "Agent claims success but execution_evidence shows no files changed " +
+                    "and no tests were run. There is no verifiable evidence of work."
+                : "Agent claims success but provided no execution_evidence. " +
+                    "Every successful round MUST include execution_evidence with " +
+                    "files_changed, test_results, and progress_estimate.",
+        });
+    }
+    // Claims arm (v3.6).
     if (status.providerStatus === "verified")
         return null;
-    const noChange = typeof selfEval.no_change_reason === "string" &&
+    // M2 (v3.7.x): the no_change_reason escape is only honest when machine
+    // verification was STRUCTURALLY impossible. With an enabled verification
+    // command configured, the runtime had a machine-verifiable path for this
+    // round — a declared reason cannot waive it (that would let an agent
+    // dodge the configured verification by writing a sentence, even while git
+    // observed real file changes). Verification-less policies (the default:
+    // commands: []) keep the escape: there is genuinely nothing to run.
+    const verificationConfigured = getPolicy().evidence.commands.some((command) => command.enabled);
+    const noChange = !verificationConfigured &&
+        typeof selfEval.no_change_reason === "string" &&
         selfEval.no_change_reason.trim().length > 0;
     // v3.3: severity follows evidence.machine_backed_success — "required"
     // rejects (error), "warn" tolerates with a warn (round commits, success
@@ -605,52 +645,23 @@ function checkRequiredCommandEvidence(selfEval, evidenceSnapshots) {
 function extractSubGoalIds(text) {
     return [...new Set(text.toLowerCase().match(/sg-[a-f0-9]{8}/g) ?? [])];
 }
-/** Extract file-path-like tokens (e.g. "src/auth/login.ts") from text. */
-function extractFilePaths(text) {
-    return [...new Set(text.match(/[\w./-]+\.[a-z]{2,6}\b/gi) ?? [])];
-}
 /** Whether a changed path looks like a test file. */
 function isTestFile(path) {
     return /\.(test|spec)\.[a-z0-9]+$/i.test(path) ||
         /(^|[\\/])tests?[\\/]/i.test(path) ||
         /_test\.[a-z0-9]+$/i.test(path);
 }
-/** Map each referenced sub-goal ID to its known description(s), reconstructed
- *  from emerged_subtasks in the vault lineage and the previous self-eval. */
-function referencedSubGoalDescriptions(ids, vaultEntries, prevSelfEval) {
-    const map = new Map();
-    for (const id of ids)
-        map.set(id, []);
-    const descriptions = [];
-    for (const entry of vaultEntries) {
-        const emerged = Array.isArray(entry.emerged_subtasks)
-            ? entry.emerged_subtasks.filter((v) => typeof v === "string")
-            : [];
-        descriptions.push(...emerged);
-    }
-    descriptions.push(...(prevSelfEval?.emerged_subtasks ?? []));
-    for (const desc of descriptions) {
-        const trimmed = desc.trim();
-        if (!trimmed)
-            continue;
-        const id = deriveSubGoalId(trimmed);
-        if (map.has(id))
-            map.get(id).push(trimmed);
-    }
-    return map;
-}
 /** v2.1 (check 11): Compare the previous round's declared next_action with
  *  the current round's actual output_summary. Detect when the agent says it
  *  will do X but then does Y — silent drift without explanation.
  *
  *  Only fires when both next_action and output_summary are non-empty.
  *
- *  v2.14: Structured-ID-first detection. Alignment is decided by a waterfall
- *  of concrete signals before falling back to string similarity:
+ *  v2.14/v3.7.1: Structured-ID-first detection. Alignment is decided by a
+ *  waterfall of concrete signals before falling back to string similarity:
  *    1. Sub-goal IDs (sg-XXXXXXXX) in next_action matched against this
- *       round's completed_subtasks (exact ID, ID derived from the
- *       description text, or Jaccard against the referenced sub-goal's
- *       known description).
+ *       round's declared done transitions (subgoal_updates). Description
+ *       matching is gone — transitions are strict ID references now.
  *    2. File paths named in next_action appearing in files_changed.
  *    3. Test evidence — next_action mentions tests and test files were
  *       changed with tests actually run.
@@ -666,27 +677,18 @@ function checkIntentDrift(selfEval, prevSelfEval, vaultEntries) {
     const actual = selfEval.output_summary.trim();
     const policy = getPolicy();
     const filesChanged = selfEval.execution_evidence?.files_changed ?? [];
-    // ── Signal 1: sub-goal IDs referenced by next_action → completed this round
+    // ── Signal 1: sub-goal IDs referenced by next_action → a done transition
     const intentIds = extractSubGoalIds(intent);
     if (intentIds.length > 0) {
-        const completed = selfEval.completed_subtasks ?? [];
-        const referenced = referencedSubGoalDescriptions(intentIds, vaultEntries, prevSelfEval);
-        const idMatched = intentIds.some((id) => completed.some((entry) => {
-            const text = entry.trim();
-            if (!text)
-                return false;
-            if (text.toLowerCase() === id)
-                return true;
-            if (deriveSubGoalId(text) === id)
-                return true;
-            const descriptions = referenced.get(id) ?? [];
-            return descriptions.some((desc) => jaccardSimilarity(text, desc) >= policy.evolution.subgoal_match_threshold);
-        }));
+        const doneIds = new Set((selfEval.subgoal_updates ?? [])
+            .filter((u) => u.status === "done")
+            .map((u) => u.id));
+        const idMatched = intentIds.some((id) => doneIds.has(id));
         if (idMatched)
             return null;
     }
     // ── Signal 2: file paths named in next_action appear in files_changed
-    const intentPaths = extractFilePaths(intent);
+    const intentPaths = extractFilePathTokens(intent);
     if (intentPaths.length > 0 && filesChanged.length > 0) {
         const pathMatched = intentPaths.some((p) => filesChanged.some((f) => f === p || f.endsWith(p) || p.endsWith(f)));
         if (pathMatched)
@@ -707,7 +709,7 @@ function checkIntentDrift(selfEval, prevSelfEval, vaultEntries) {
     if (score >= threshold)
         return null;
     const idNote = intentIds.length > 0
-        ? `; ${intentIds.length} referenced sub-goal ID(s) did not match completed_subtasks`
+        ? `; ${intentIds.length} referenced sub-goal ID(s) did not match a declared done transition`
         : "";
     return makeVerificationFlag({
         severity: "warn",
@@ -886,9 +888,12 @@ function checkSubGoalDrift(selfEval, prevSelfEval, vaultEntries, currentRound) {
     const nextAction = selfEval.next_action?.trim();
     if (!nextAction)
         return null;
-    // Reconstruct pending sub-goal descriptions from vault entries
+    // Reconstruct the pending set from vault entries and the current eval.
+    // v3.7.1: emerged descriptions are the creation channel; done/canceled are
+    // terminal ids reached through subgoal_updates (monotone — a terminal
+    // transition can never be undone, so the terminal id set only grows).
     const pendingSubGoals = new Set();
-    const completedOrCanceled = new Set();
+    const terminalIds = new Set();
     for (const entry of vaultEntries) {
         const emerged = Array.isArray(entry.emerged_subtasks)
             ? entry.emerged_subtasks.filter((v) => typeof v === "string")
@@ -896,32 +901,23 @@ function checkSubGoalDrift(selfEval, prevSelfEval, vaultEntries, currentRound) {
         for (const desc of emerged) {
             pendingSubGoals.add(desc.trim());
         }
-        const done = Array.isArray(entry.completed_subtasks)
-            ? entry.completed_subtasks.filter((v) => typeof v === "string")
-            : [];
-        for (const desc of done) {
-            completedOrCanceled.add(desc.trim());
-        }
-        const canceled = Array.isArray(entry.canceled_subtasks)
-            ? entry.canceled_subtasks.filter((v) => typeof v === "string")
-            : [];
-        for (const desc of canceled) {
-            completedOrCanceled.add(desc.trim());
+        for (const u of entrySubGoalUpdates(entry)) {
+            if (u.status === "done" || u.status === "canceled")
+                terminalIds.add(u.id);
         }
     }
-    // Also process current selfEval
+    // Also process the current selfEval
     for (const desc of selfEval.emerged_subtasks ?? []) {
         pendingSubGoals.add(desc.trim());
     }
-    for (const desc of selfEval.completed_subtasks ?? []) {
-        completedOrCanceled.add(desc.trim());
-    }
-    for (const desc of selfEval.canceled_subtasks ?? []) {
-        completedOrCanceled.add(desc.trim());
+    for (const u of selfEval.subgoal_updates ?? []) {
+        if (u.status === "done" || u.status === "canceled")
+            terminalIds.add(u.id);
     }
-    // Remove completed/canceled from pending
-    for (const desc of completedOrCanceled) {
-        pendingSubGoals.delete(desc);
+    // Remove descriptions whose derived id reached a terminal state
+    for (const desc of [...pendingSubGoals]) {
+        if (terminalIds.has(deriveSubGoalId(desc)))
+            pendingSubGoals.delete(desc);
     }
     // Need at least 3 pending sub-goals for the check to be meaningful
     if (pendingSubGoals.size < 3)
@@ -951,37 +947,60 @@ function checkSubGoalDrift(selfEval, prevSelfEval, vaultEntries, currentRound) {
             check: CHECK_SUBGOAL_DRIFT,
             detail: `Agent's next_action doesn't align with any of ${pendingSubGoals.size} pending sub-goals. ` +
                 `Pending: ${sample}… Consider completing existing sub-goals before starting new work, ` +
-                `or cancel outdated sub-goals via canceled_subtasks.`,
+                `or cancel outdated sub-goals via subgoal_updates.`,
         });
     }
     return null;
 }
 /** v2.13: After a backtrack, check that the agent restored the workspace
- *  before working. If the agent's files_changed overlaps with files from
- *  skipped (failed) rounds, the workspace was likely not clean. */
-function checkBacktrackWorkspaceRestore(selfEval, backtrackSkippedFiles) {
-    if (backtrackSkippedFiles.length === 0)
-        return null;
+ *  before working. Two arms:
+ *
+ *  1. Machine arm (M3, error): a skipped file whose CURRENT git fingerprint
+ *     still equals the fingerprint recorded at its failed round was never
+ *     touched since the rollback — the workspace was provably not restored.
+ *     Restored or re-modified files change fingerprint and can never be
+ *     misjudged by this arm.
+ *
+ *  2. Claims arm (warn only): the agent's files_changed overlaps the skipped
+ *     list. A self-report alone cannot distinguish a restored-then-redone
+ *     file from a never-restored one — a legitimate multi-file redo would
+ *     otherwise be falsely terminated — so overlap is guidance, not a
+ *     verdict. (The old error tier for >= 3 overlapping files was removed
+ *     for exactly this reason: it fired on honest redos.) */
+function checkBacktrackWorkspaceRestore(selfEval, backtrackSkippedFiles, backtrackSkippedFingerprints = {}, evidenceSnapshots = []) {
+    // Machine arm — untouched-since-rollback proof, independent of claims.
+    const failedEntries = Object.entries(backtrackSkippedFingerprints);
+    if (failedEntries.length > 0) {
+        const git = evidenceSnapshots.find((snapshot) => snapshot.provider === "git" && isRecord(snapshot.data) &&
+            isRecord(snapshot.data.fingerprints));
+        const currentFingerprints = git
+            ? git.data.fingerprints
+            : null;
+        if (currentFingerprints) {
+            const untouched = failedEntries
+                .filter(([file, failedFp]) => currentFingerprints[file] === failedFp)
+                .map(([file]) => file)
+                .sort();
+            if (untouched.length > 0) {
+                return makeVerificationFlag({
+                    severity: "error",
+                    field: "workspace",
+                    check: CHECK_BACKTRACK_WORKSPACE_NOT_RESTORED,
+                    detail: `File(s) from the failed rounds are byte-identical to their ` +
+                        `state at the rollback: ${untouched.slice(0, 5).join(", ")}. The ` +
+                        `workspace was never restored — restore it to the restore point ` +
+                        `(git checkout/reset) before redoing the work.`,
+                });
+            }
+        }
+    }
     const ev = selfEval.execution_evidence;
     if (!ev || ev.files_changed.length === 0)
         return null;
-    // Check overlap: files the agent changed vs. files from skipped rounds
+    // Claims arm — overlap as guidance only.
     const overlap = ev.files_changed.filter((f) => backtrackSkippedFiles.some((sf) => sf === f || f.endsWith(sf) || sf.endsWith(f)));
     if (overlap.length === 0)
         return null;
-    // Agent is modifying files that were part of failed rounds without
-    // having properly restored the workspace first.
-    if (overlap.length >= 3 || overlap.length === ev.files_changed.length) {
-        return makeVerificationFlag({
-            severity: "error",
-            field: "files_changed",
-            check: CHECK_BACKTRACK_WORKSPACE_NOT_RESTORED,
-            detail: `Agent modified ${overlap.length} file(s) that were part of ` +
-                `the skipped (failed) rounds: ${overlap.slice(0, 5).join(", ")}. ` +
-                `The workspace was likely not restored before working.`,
-        });
-    }
-    // Minor overlap — warn only
     return makeVerificationFlag({
         severity: "warn",
         field: "files_changed",
@@ -1239,15 +1258,80 @@ function checkContractPremature(activeContract, selfEval) {
  * @param evidenceSnapshots    v1.18: Evidence snapshots from configured providers.
  *                             Used by checkEvidenceIntegrity for multi-provider
  *                             cross-validation. Defaults to empty array. */
-export function verifySelfEvaluation(selfEval, currentRound, vaultEntries, prevSelfEval = null, evidenceSnapshots = [], 
+/** v3.7.1: Opt-in round blocking for the gate layer. For every gate id the
+ *  round cites (gate_ids), the gate_opened record must exist, must be a
+ *  USER gate, and must have an approved gate_decision. Error flags list
+ *  every failing id with a reason. Entirely skipped when the feature is
+ *  disabled — there is nothing to cite against. */
+function checkUserGateUnresolved(selfEval, gateEntries) {
+    if (!getPolicy().gate.enabled)
+        return null;
+    const cited = (selfEval.gate_ids ?? []).filter((id) => typeof id === "string");
+    if (cited.length === 0)
+        return null;
+    const opened = new Set();
+    const userKind = new Set();
+    const approved = new Set();
+    for (const entry of gateEntries) {
+        if (entry.task_type === "gate_opened" && typeof entry.gate_id === "string") {
+            opened.add(entry.gate_id);
+            // v3.7.1: structured records declare gate_kind; legacy flat records
+            // (blocked-round auto-records) classify their stored action text.
+            if (entry.gate_kind === "user") {
+                userKind.add(entry.gate_id);
+            }
+            else if (typeof entry.gate_action === "string") {
+                let kind = null;
+                try {
+                    kind = preflightStructuredGate(JSON.parse(entry.gate_action)).kind;
+                }
+                catch {
+                    kind = deriveGate(entry.gate_action).gate.kind;
+                }
+                if (kind === "user")
+                    userKind.add(entry.gate_id);
+            }
+        }
+        if (entry.task_type === "gate_decision" && entry.approved === true &&
+            typeof entry.gate_id === "string") {
+            approved.add(entry.gate_id);
+        }
+    }
+    const failures = [];
+    for (const gateId of cited) {
+        if (!opened.has(gateId))
+            failures.push(`${gateId} (not_found)`);
+        else if (!userKind.has(gateId))
+            failures.push(`${gateId} (not_user_gate)`);
+        else if (!approved.has(gateId))
+            failures.push(`${gateId} (not_approved)`);
+    }
+    if (failures.length === 0)
+        return null;
+    return makeVerificationFlag({
+        severity: "error",
+        field: "evaluation",
+        check: CHECK_USER_GATE_UNRESOLVED,
+        detail: `The round cites gates without an approved human decision: ` +
+            `${failures.join("; ")}. Obtain approval via loopforge_gate_check / ` +
+            `loopforge_gate_resolve before claiming the action is done.`,
+    });
+}
+export function verifySelfEvaluation(selfEval, currentRound, vaultEntries, prevSelfEval = null, evidenceSnapshots = [],
 /** v2.13: Files from skipped backtrack rounds. If the agent's
  *  files_changed overlaps significantly with these, the workspace
  *  was not properly restored before working. */
-backtrackSkippedFiles = [], 
+backtrackSkippedFiles = [],
+/** M3 (v3.7.x): skipped-file git fingerprints at their failed rounds —
+ *  machine proof of "untouched since the rollback" for the restore check. */
+backtrackSkippedFingerprints = {},
 /** v2.12: Git HEAD commit of the backtrack restore point. When set, the
  *  current git snapshot must sit at this commit — otherwise the workspace
  *  was not restored and the round cannot be accepted. */
-backtrackTargetGitHead) {
+backtrackTargetGitHead,
+/** v3.7.1: gate records (task_type gate_opened / gate_decision) live
+ *  outside the round prefix — the caller passes them in explicitly. */
+gateEntries = []) {
     const flags = [];
     // Collect violations from all previous vault entries for duplicate-discovery
     // and other checks that need deeper history.
@@ -1275,11 +1359,9 @@ backtrackTargetGitHead) {
     // the list at the first problem, hiding every other bad retroactive claim
     // from the agent until the next round.
     const checks = [
-        () => checkProgressRegression(selfEval, prevSelfEval),
-        () => checkEmptyChangeWithPassing(selfEval),
         () => checkSuccessWithRemainingCriteria(selfEval),
-        // v2.12/v3.6: success without a machine-verified observation — the merged
-        // success_unverified semantics (runtime providerStatus lens, tamper-aware)
+        // v2.12/v3.6/v3.7: the single success-evidence semantic — empty/missing-
+        // evidence arm (ex-R3) + claims arm (providerStatus lens, tamper-aware)
         () => checkSuccessWithoutVerifiedEvidence(selfEval, evidenceStatus),
         // v2.12: criteria met but none machine-verified (mild criterion-specific rule)
         () => checkUnverifiedCriteriaClaims(selfEval, claimView),
@@ -1303,7 +1385,7 @@ backtrackTargetGitHead) {
         // v2.2: Detect sub-goal drift — next_action doesn't align with pending sub-goals
         () => checkSubGoalDrift(selfEval, prevSelfEval, vaultEntries, currentRound),
         // v2.13: Post-backtrack workspace restore check
-        () => checkBacktrackWorkspaceRestore(selfEval, backtrackSkippedFiles),
+        () => checkBacktrackWorkspaceRestore(selfEval, backtrackSkippedFiles, backtrackSkippedFingerprints, evidenceSnapshots),
         // v2.12: Post-backtrack git HEAD restore check
         () => checkBacktrackGitHeadRestore(evidenceSnapshots, backtrackTargetGitHead),
         // v3.3: Round Contract checks. v3.4: split by target — structural
@@ -1317,6 +1399,8 @@ backtrackTargetGitHead) {
         () => checkPrematureBoundary(activeContract, selfEval, claimView),
         () => checkContractCompletionUnverified(activeContract, selfEval, evidenceSnapshots),
         () => checkContractPremature(activeContract, selfEval),
+        // v3.7.1: opt-in gate-layer blocking (skipped when disabled)
+        () => checkUserGateUnresolved(selfEval, gateEntries),
     ];
     for (const run of checks) {
         const result = run();