loopforge 2.11.0 → 3.2.1

package/dist/verification-gate.js

@@ -14,7 +14,37 @@
  */
 import { getPolicy } from "./policy.js";
 import { makeVerificationFlag, makeVerificationResult } from "./protocol.js";
-import { jaccardSimilarity, entryRound as sharedEntryRound } from "./token-utils.js";
+import { jaccardSimilarity, tokenize, entryRound as sharedEntryRound, isRecord } from "./token-utils.js";
+import { deriveSubGoalId } from "./loop-compiler.js";
+import { deriveClaimView, resolveRoundFiles } from "./evidence-claims.js";
+import { effectiveSuccess } from "./self-eval.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// v2.12: Check-name constants — single source of truth so the enforcement
+// gate and audit can reference checks without string-literal drift.
+// ═══════════════════════════════════════════════════════════════════════════
+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";
+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";
+export const CHECK_DUPLICATE_CONSTRAINT_DISCOVERY = "duplicate_constraint_discovery";
+export const CHECK_RECURRING_VIOLATION = "recurring_violation";
+export const CHECK_RETRACT_FRESH_CONSTRAINT = "retract_fresh_constraint";
+export const CHECK_EVIDENCE_INTEGRITY = "evidence_integrity";
+export const CHECK_REQUIRED_COMMAND_FAILED = "required_command_failed";
+export const CHECK_COMMAND_EVIDENCE_MISMATCH = "command_evidence_mismatch";
+export const CHECK_INTENT_DRIFT = "intent_drift";
+export const CHECK_SUBGOAL_DRIFT = "subgoal_drift";
+export const CHECK_BACKTRACK_WORKSPACE_NOT_RESTORED = "backtrack_workspace_not_restored";
+export const CHECK_CRITERIA_CLAIMS_UNVERIFIED = "criteria_claims_unverified";
+/** v3.2: success declared with no machine-verified observation this round
+ *  (providerStatus ≠ verified). Warn-level: the round still commits, but its
+ *  success never enters the trajectory and trust drops. */
+export const CHECK_SUCCESS_UNVERIFIED = "success_unverified";
 // ═══════════════════════════════════════════════════════════════════════════
 // Helpers
 // ═══════════════════════════════════════════════════════════════════════════
@@ -34,6 +64,90 @@ function entryViolations(entry) {
         return viols.filter((v) => typeof v === "string");
     return [];
 }
+function passedAfterCommand(snapshots) {
+    return snapshots.find((snapshot) => isRecord(snapshot.data) &&
+        snapshot.data.kind === "command" &&
+        snapshot.data.phase === "after" &&
+        snapshot.data.status === "passed") ?? null;
+}
+/** v3.2: Derive the machine-verification status of a round. The verification
+ *  capability is modeled explicitly (verified / unavailable / absent) instead
+ *  of letting evidence-dependent checks silently disappear when snapshots are
+ *  missing — the fix for the "weakest when it matters most" gap. */
+export function deriveEvidenceStatus(selfEval, evidenceSnapshots) {
+    const gitSnap = evidenceSnapshots.find((snapshot) => snapshot.provider === "git") ?? null;
+    const gitObserved = gitSnap !== null && gitSnap.files.length > 0;
+    const command = passedAfterCommand(evidenceSnapshots);
+    const commandVerified = command !== null;
+    // testsMachineBacked: agent-reported test_results agree with a passed
+    // command's parsed stdout (the same comparison checkCommandEvidenceIntegrity
+    // performs — parseTestOutput lives in this module).
+    let testsMachineBacked = false;
+    const reported = selfEval.execution_evidence?.test_results;
+    if (command && reported) {
+        const parsed = parseTestOutput(String(command.data.stdout ?? ""));
+        testsMachineBacked = parsed !== null &&
+            parsed.passed === reported.passed &&
+            parsed.failed === reported.failed &&
+            parsed.skipped === reported.skipped;
+    }
+    // reportedFilesMatch: agent-reported files_changed equals the git diff set.
+    let reportedFilesMatch = false;
+    if (gitSnap && selfEval.execution_evidence) {
+        const reportedSet = [...selfEval.execution_evidence.files_changed].sort();
+        const actualSet = [...gitSnap.files].sort();
+        reportedFilesMatch = reportedSet.length === actualSet.length &&
+            reportedSet.every((file, index) => file === actualSet[index]);
+    }
+    const providerStatus = evidenceSnapshots.length === 0
+        ? "absent"
+        : gitObserved || commandVerified ? "verified" : "unavailable";
+    return {
+        providerStatus,
+        gitObserved,
+        commandVerified,
+        testsMachineBacked,
+        reportedFilesMatch,
+    };
+}
+/** v3.2: Per-round machine progress — whether git observed file changes in
+ *  each of the last `lookback` committed rounds, rebuilt from the feedback
+ *  entries' roundEvidence snapshots (already persisted at commit). Returns
+ *  null when fewer than `lookback` rounds carry git snapshots — the machine
+ *  signal is unavailable and callers (R4/R5 on the heuristic path) keep
+ *  their legacy skip. The snapshot shape is parsed defensively here because
+ *  this module must not import round-transaction (import cycle). */
+export function machineProgressSeries(vaultEntries, currentRound, lookback) {
+    const byRound = new Map();
+    for (const entry of vaultEntries) {
+        const tid = String(entry.task_id ?? "");
+        if (!tid.endsWith(":feedback"))
+            continue;
+        const rnd = entryRound(entry);
+        if (rnd <= 0 || rnd >= currentRound)
+            continue;
+        const rt = isRecord(entry.loop_lineage)
+            ? entry.loop_lineage.round_transaction
+            : null;
+        const snapshot = isRecord(rt) ? rt.snapshot : null;
+        const roundEvidence = isRecord(snapshot) ? snapshot.roundEvidence : null;
+        if (!Array.isArray(roundEvidence))
+            continue;
+        const git = roundEvidence.find((value) => isRecord(value) && value.provider === "git");
+        if (!git)
+            continue;
+        const gitFiles = git.files;
+        byRound.set(rnd, Array.isArray(gitFiles) && gitFiles.length > 0);
+    }
+    if (byRound.size < lookback)
+        return null;
+    const sorted = [...byRound.keys()].sort((a, b) => a - b);
+    const recent = sorted.slice(-lookback);
+    // Continuity: the recent rounds must be the actual last `lookback` rounds.
+    if (recent[0] < currentRound - lookback)
+        return null;
+    return recent.map((round) => byRound.get(round));
+}
 // ═══════════════════════════════════════════════════════════════════════════
 // Individual checks — each returns a VerificationFlag or null
 // ═══════════════════════════════════════════════════════════════════════════
@@ -52,7 +166,7 @@ function checkProgressRegression(selfEval, prevSelfEval) {
     return makeVerificationFlag({
         severity: "warn",
         field: "progress_estimate",
-        check: "progress_regression",
+        check: CHECK_PROGRESS_REGRESSION,
         detail: `Progress dropped from ${prevProgress.toFixed(2)} to ` +
             `${currProgress.toFixed(2)} (delta: ${(currProgress - prevProgress).toFixed(2)})`,
     });
@@ -65,18 +179,18 @@ function checkEmptyChangeWithPassing(selfEval) {
     const testsAllPass = ev.test_results !== null &&
         ev.test_results.failed === 0 &&
         ev.test_results.passed > 0;
-    if (!filesEmpty || !testsAllPass || !selfEval.success)
+    if (!filesEmpty || !testsAllPass || !effectiveSuccess(selfEval))
         return null;
     return makeVerificationFlag({
         severity: "warn",
         field: "execution_evidence",
-        check: "empty_change_with_passing",
+        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 (!selfEval.success)
+    if (!effectiveSuccess(selfEval))
         return null;
     const remaining = selfEval.execution_evidence?.success_criteria_remaining;
     if (!remaining || remaining.length === 0)
@@ -84,11 +198,154 @@ function checkSuccessWithRemainingCriteria(selfEval) {
     return makeVerificationFlag({
         severity: "error",
         field: "success",
-        check: "success_with_remaining_criteria",
+        check: CHECK_SUCCESS_WITH_REMAINING_CRITERIA,
         detail: `Agent claims success but ${remaining.length} criteria remain unmet: ` +
             remaining.slice(0, 3).join("; "),
     });
 }
+/** v2.12: Criteria reported met but none machine-verified. The agent puts
+ *  completed criteria into the ledger, but no passing test evidence or
+ *  command snapshot backs them. Warn — completion still counts, but the
+ *  next prompt tells the agent its claims are unverified. This is the
+ *  mild form of the 3.x criterion-specific completion rule. */
+function checkUnverifiedCriteriaClaims(selfEval, claimView) {
+    const met = selfEval.execution_evidence?.success_criteria_met;
+    if (!met || met.length === 0)
+        return null;
+    if (claimView.verifiedCount > 0 || claimView.hasMachineEvidence)
+        return null;
+    return makeVerificationFlag({
+        severity: "warn",
+        field: "execution_evidence",
+        check: CHECK_CRITERIA_CLAIMS_UNVERIFIED,
+        detail: `${met.length} criteria reported met but none machine-verified ` +
+            "(no passing test evidence or command snapshot)",
+    });
+}
+/** v2.12: Declared outcome vs legacy boolean consistency. A declared success
+ *  with success=false is a self-contradiction (error); a declared non-success
+ *  with success=true is a compat conflict (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) {
+        return makeVerificationFlag({
+            severity: "error",
+            field: "outcome",
+            check: CHECK_OUTCOME_SUCCESS_CONTRADICTION,
+            detail: "outcome=success but success=false — self-contradictory",
+        });
+    }
+    if (outcome !== undefined && outcome !== "success" && selfEval.success === true) {
+        return makeVerificationFlag({
+            severity: "warn",
+            field: "success",
+            check: CHECK_SUCCESS_CLAIM_CONFLICT,
+            detail: `outcome=${outcome} but success=true — the declared outcome wins`,
+        });
+    }
+    if (outcome === "blocked" &&
+        (typeof selfEval.blocker !== "string" || selfEval.blocker.trim().length === 0)) {
+        return makeVerificationFlag({
+            severity: "warn",
+            field: "blocker",
+            check: CHECK_BLOCKED_WITHOUT_BLOCKER,
+            detail: "outcome=blocked but no blocker description was provided",
+        });
+    }
+    return null;
+}
+/** v2.12: Retroactive claims reference PRIOR rounds. Each claim's file
+ *  paths are checked against the referenced round's committed git evidence
+ *  (P0 provenance layer). Unverifiable claims warn — they never upgrade
+ *  criteria status. */
+function checkRetroactiveClaims(selfEval, vaultEntries, currentRound) {
+    const claims = selfEval.retroactiveClaims;
+    if (!claims || claims.length === 0)
+        return null;
+    const loopId = vaultEntries.find((entry) => typeof entry.loop_id === "string")
+        ?.loop_id;
+    const flags = [];
+    for (const claim of claims) {
+        if (claim.round < 1 || claim.round >= currentRound) {
+            flags.push(makeVerificationFlag({
+                severity: "warn",
+                field: "retroactiveClaims",
+                check: CHECK_RETROACTIVE_CLAIM_BAD_ROUND,
+                detail: `retroactive claim targets round ${claim.round} (must be a prior round)`,
+            }));
+            continue;
+        }
+        if (!loopId)
+            continue; // no vault context → cannot verify (fail-open)
+        const observed = resolveRoundFiles(vaultEntries, loopId, claim.round);
+        if (observed === null) {
+            flags.push(makeVerificationFlag({
+                severity: "warn",
+                field: "retroactiveClaims",
+                check: CHECK_RETROACTIVE_CLAIM_UNVERIFIED,
+                detail: `retroactive claim for round ${claim.round} has no observable git evidence`,
+            }));
+            continue;
+        }
+        const paths = extractFilePaths(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({
+                severity: "warn",
+                field: "retroactiveClaims",
+                check: CHECK_RETROACTIVE_CLAIM_UNVERIFIED,
+                detail: `retroactive claim references files not observed in round ${claim.round}: ` +
+                    unverified.slice(0, 3).join(", "),
+            }));
+        }
+    }
+    return flags.length > 0 ? flags[0] : null;
+}
+/** v2.12: success with zero machine-verifiable evidence. The agent claims
+ *  completion but nothing the runtime observed backs it — no verified claims
+ *  (test evidence), no test results, no required commands. A declared
+ *  no_change_reason is the honest escape hatch: it downgrades to info. */
+function checkSuccessWithoutVerifiedEvidence(selfEval, claimView) {
+    if (!effectiveSuccess(selfEval))
+        return null;
+    if (claimView.verifiedCount > 0 || claimView.hasMachineEvidence)
+        return null;
+    const noChange = typeof selfEval.no_change_reason === "string" &&
+        selfEval.no_change_reason.trim().length > 0;
+    return makeVerificationFlag({
+        severity: noChange ? "info" : "error",
+        field: "success",
+        check: CHECK_SUCCESS_WITHOUT_VERIFIED_EVIDENCE,
+        detail: noChange
+            ? "success with zero verified claims (no_change_reason declared)"
+            : "success with zero verified claims and no test evidence",
+    });
+}
+/** v3.2: success declared but no machine-verified observation this round.
+ *  Unlike R8 (which keys off the agent's SELF-REPORTED test_results), this
+ *  keys off the runtime-derived providerStatus: git diff observed, or a
+ *  passed after-command. Warn-level by design — the round commits, but its
+ *  success never enters the trajectory (and trust drops). A declared
+ *  no_change_reason is the honest escape hatch, mirroring R8.
+ *  Crucially this check does NOT self-skip on the heuristic-extraction path:
+ *  an unstructured success claim without machine observation is flagged
+ *  exactly the same — the check degrades, it never disappears. */
+function checkSuccessUnverified(selfEval, status) {
+    if (!effectiveSuccess(selfEval))
+        return null;
+    if (typeof selfEval.no_change_reason === "string" &&
+        selfEval.no_change_reason.trim().length > 0)
+        return null;
+    if (status.providerStatus === "verified")
+        return null;
+    return makeVerificationFlag({
+        severity: "warn",
+        field: "success",
+        check: CHECK_SUCCESS_UNVERIFIED,
+        detail: `success declared but no machine-verified observation this round (providerStatus: ${status.providerStatus})`,
+    });
+}
 function checkDuplicateConstraintDiscovery(selfEval, prevSelfEval, olderViolations) {
     const discovered = selfEval.discovered_constraints;
     if (!discovered || discovered.length === 0)
@@ -111,7 +368,7 @@ function checkDuplicateConstraintDiscovery(selfEval, prevSelfEval, olderViolatio
             return makeVerificationFlag({
                 severity: "warn",
                 field: "discovered_constraints",
-                check: "duplicate_constraint_discovery",
+                check: CHECK_DUPLICATE_CONSTRAINT_DISCOVERY,
                 detail: `Constraint "${d}" was already known from a previous round`,
             });
         }
@@ -151,7 +408,7 @@ function checkRecurringViolation(selfEval, prevSelfEval, vaultEntries, currentRo
             return makeVerificationFlag({
                 severity: "error",
                 field: "constraint_violations",
-                check: "recurring_violation",
+                check: CHECK_RECURRING_VIOLATION,
                 detail: `Constraint violation "${v}" has appeared in 3 consecutive rounds ` +
                     `(rounds ${currentRound - 2}–${currentRound}) without resolution`,
             });
@@ -174,7 +431,7 @@ function checkRetractFreshConstraint(selfEval, prevSelfEval, currentRound) {
             return makeVerificationFlag({
                 severity: "warn",
                 field: "retracted_constraints",
-                check: "retract_fresh_constraint",
+                check: CHECK_RETRACT_FRESH_CONSTRAINT,
                 detail: `Retracting constraint "${r}" that was just discovered in round ` +
                     `${currentRound - 1} — may indicate rapid flip-flopping`,
             });
@@ -200,7 +457,7 @@ function checkEvidenceIntegrity(selfEval, evidenceSnapshots) {
         return makeVerificationFlag({
             severity: "warn",
             field: "files_changed",
-            check: "evidence_integrity",
+            check: CHECK_EVIDENCE_INTEGRITY,
             detail: `Agent reported no files changed but evidence shows: ${actual.join(", ")}`,
         });
     }
@@ -215,7 +472,7 @@ function checkEvidenceIntegrity(selfEval, evidenceSnapshots) {
         return makeVerificationFlag({
             severity: "warn",
             field: "files_changed",
-            check: "evidence_integrity",
+            check: CHECK_EVIDENCE_INTEGRITY,
             detail: `Agent files_changed doesn't match evidence: ${parts.join("; ")}`,
         });
     }
@@ -224,7 +481,7 @@ function checkEvidenceIntegrity(selfEval, evidenceSnapshots) {
 /** A required, explicitly configured verification command is authoritative
  * when the Agent claims success. Optional commands remain observational. */
 function checkRequiredCommandEvidence(selfEval, evidenceSnapshots) {
-    if (!selfEval.success)
+    if (!effectiveSuccess(selfEval))
         return null;
     for (const snapshot of evidenceSnapshots) {
         if (snapshot.data.kind !== "command")
@@ -243,7 +500,7 @@ function checkRequiredCommandEvidence(selfEval, evidenceSnapshots) {
         return makeVerificationFlag({
             severity: "error",
             field: "execution_evidence",
-            check: "required_command_failed",
+            check: CHECK_REQUIRED_COMMAND_FAILED,
             detail: `Agent claims success but required command "${name}" ${String(status)}${exitCode}`,
         });
     }
@@ -251,30 +508,123 @@ function checkRequiredCommandEvidence(selfEval, evidenceSnapshots) {
 }
 // ── Test output parsing ────────────────────────────────────────────────────
 // jaccardSimilarity() imported from token-utils.ts (v2.1 — intent-action drift detection)
+/** Extract stable sub-goal IDs (sg-XXXXXXXX) mentioned in text.
+ *  Matches the ID format rendered in prompts (loop-compiler deriveSubGoalId). */
+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.
- *  Uses configurable Jaccard token similarity threshold from policy. */
-function checkIntentDrift(selfEval, prevSelfEval) {
+ *
+ *  v2.14: 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).
+ *    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.
+ *    4. Jaccard token similarity against the policy threshold (weak signal).
+ *  Any signal aligning is sufficient — text similarity is never the sole
+ *  authority when structured evidence exists. */
+function checkIntentDrift(selfEval, prevSelfEval, vaultEntries) {
     if (!prevSelfEval?.next_action?.trim())
         return null;
     if (!selfEval.output_summary.trim())
         return null;
     const intent = prevSelfEval.next_action.trim();
     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
+    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);
+        }));
+        if (idMatched)
+            return null;
+    }
+    // ── Signal 2: file paths named in next_action appear in files_changed
+    const intentPaths = extractFilePaths(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)
+            return null;
+    }
+    // ── Signal 3: test evidence — intent mentions tests, test files changed,
+    //    and tests actually ran this round
+    const intentTokens = tokenize(intent);
+    const mentionsTests = intentTokens.has("test") || intentTokens.has("tests");
+    const testResults = selfEval.execution_evidence?.test_results;
+    const testsRan = !!testResults && testResults.passed + testResults.failed > 0;
+    const testFilesChanged = filesChanged.some((f) => isTestFile(f));
+    if (mentionsTests && testsRan && testFilesChanged)
+        return null;
+    // ── Signal 4 (weak): Jaccard token similarity
     const score = jaccardSimilarity(intent, actual);
-    const threshold = getPolicy().evolution.intent_drift_threshold;
+    const threshold = policy.evolution.intent_drift_threshold;
     if (score >= threshold)
         return null;
+    const idNote = intentIds.length > 0
+        ? `; ${intentIds.length} referenced sub-goal ID(s) did not match completed_subtasks`
+        : "";
     return makeVerificationFlag({
         severity: "warn",
         field: "output_summary",
-        check: "intent_drift",
+        check: CHECK_INTENT_DRIFT,
         detail: `Declared intent was "${intent.slice(0, 120)}" ` +
             `but actual output "${actual.slice(0, 120)}" — ` +
-            `similarity ${(score * 100).toFixed(0)}% below threshold ${(threshold * 100).toFixed(0)}%`,
+            `similarity ${(score * 100).toFixed(0)}% below threshold ${(threshold * 100).toFixed(0)}%` +
+            idNote,
     });
 }
 /** Best-effort parse of test counts from common test-runner output formats.
@@ -384,7 +734,7 @@ function checkCommandEvidenceIntegrity(selfEval, evidenceSnapshots) {
         return makeVerificationFlag({
             severity,
             field: "test_results",
-            check: "command_evidence_mismatch",
+            check: CHECK_COMMAND_EVIDENCE_MISMATCH,
             detail: `Agent test_results don't match "${name}" output: ${mismatches.join("; ")}`,
         });
     }
@@ -393,7 +743,11 @@ function checkCommandEvidenceIntegrity(selfEval, evidenceSnapshots) {
 /** v2.2: Check if the agent's declared next_action aligns with any pending
  *  or in_progress sub-goal. When 3+ pending sub-goals exist but the agent
  *  plans work unrelated to any of them, it may indicate task drift.
- *  This is a warn-level advisory — the agent always owns prioritization. */
+ *  This is a warn-level advisory — the agent always owns prioritization.
+ *
+ *  v2.14: Exact sub-goal ID alignment first — next_action naming a pending
+ *  sub-goal by its stable ID (sg-XXXXXXXX) is aligned by definition.
+ *  Jaccard description similarity remains as the fallback. */
 function checkSubGoalDrift(selfEval, prevSelfEval, vaultEntries, currentRound) {
     const nextAction = selfEval.next_action?.trim();
     if (!nextAction)
@@ -438,6 +792,14 @@ function checkSubGoalDrift(selfEval, prevSelfEval, vaultEntries, currentRound) {
     // Need at least 3 pending sub-goals for the check to be meaningful
     if (pendingSubGoals.size < 3)
         return null;
+    // v2.14: Stable ID match first — next_action naming a pending sub-goal
+    // by ID is aligned by definition, regardless of description wording.
+    const nextActionIds = extractSubGoalIds(nextAction);
+    if (nextActionIds.length > 0) {
+        const pendingIds = new Set([...pendingSubGoals].map((d) => deriveSubGoalId(d)));
+        if (nextActionIds.some((id) => pendingIds.has(id)))
+            return null;
+    }
     // Check if next_action aligns with any pending sub-goal
     let aligns = false;
     for (const sg of pendingSubGoals) {
@@ -452,7 +814,7 @@ function checkSubGoalDrift(selfEval, prevSelfEval, vaultEntries, currentRound) {
         return makeVerificationFlag({
             severity: "warn",
             field: "next_action",
-            check: "subgoal_drift",
+            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.`,
@@ -479,7 +841,7 @@ function checkBacktrackWorkspaceRestore(selfEval, backtrackSkippedFiles) {
         return makeVerificationFlag({
             severity: "error",
             field: "files_changed",
-            check: "backtrack_workspace_not_restored",
+            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.`,
@@ -489,11 +851,35 @@ function checkBacktrackWorkspaceRestore(selfEval, backtrackSkippedFiles) {
     return makeVerificationFlag({
         severity: "warn",
         field: "files_changed",
-        check: "backtrack_workspace_not_restored",
+        check: CHECK_BACKTRACK_WORKSPACE_NOT_RESTORED,
         detail: `Agent modified files that overlap with skipped rounds: ` +
             `${overlap.join(", ")}. Verify the workspace was restored.`,
     });
 }
+/** v2.12: After a backtrack, the working tree must return to the restore
+ *  point's git HEAD. Compares the first 12 characters (short hash), matching
+ *  how git itself disambiguates. */
+function checkBacktrackGitHeadRestore(evidenceSnapshots, backtrackTargetGitHead) {
+    if (!backtrackTargetGitHead)
+        return null;
+    const git = evidenceSnapshots.find((snapshot) => snapshot.provider === "git" && isRecord(snapshot.data) &&
+        typeof snapshot.data.head === "string");
+    if (!git)
+        return null; // git unavailable → cannot verify → skip (fail-open)
+    const currentHead = git.data.head;
+    if (currentHead.length === 0)
+        return null;
+    if (currentHead.slice(0, 12) === backtrackTargetGitHead.slice(0, 12))
+        return null;
+    return makeVerificationFlag({
+        severity: "error",
+        field: "workspace",
+        check: CHECK_BACKTRACK_WORKSPACE_NOT_RESTORED,
+        detail: `Workspace HEAD (${currentHead.slice(0, 12)}) does not match the ` +
+            `backtrack restore commit (${backtrackTargetGitHead.slice(0, 12)}). ` +
+            `Restore the working tree before continuing.`,
+    });
+}
 // ═══════════════════════════════════════════════════════════════════════════
 // Main entry point
 // ═══════════════════════════════════════════════════════════════════════════
@@ -511,7 +897,11 @@ export function verifySelfEvaluation(selfEval, currentRound, vaultEntries, prevS
 /** 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 = [], 
+/** 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) {
     const flags = [];
     // Collect violations from all previous vault entries for duplicate-discovery
     // and other checks that need deeper history.
@@ -520,11 +910,27 @@ backtrackSkippedFiles = []) {
         for (const v of entryViolations(entry))
             olderViolations.push(v);
     }
+    // v2.12: Derived claim provenance — which reported criteria completions
+    // are backed by machine evidence (pure derivation, not persisted).
+    const claimView = deriveClaimView(selfEval, evidenceSnapshots);
+    // v3.2: Runtime machine-verification status (git observed / command passed /
+    // absent). Feeds the success_unverified check that never self-skips.
+    const evidenceStatus = deriveEvidenceStatus(selfEval, evidenceSnapshots);
     // Run all checks
     const checks = [
         () => checkProgressRegression(selfEval, prevSelfEval),
         () => checkEmptyChangeWithPassing(selfEval),
         () => checkSuccessWithRemainingCriteria(selfEval),
+        // v2.12: success with zero verified claims and no test evidence
+        () => checkSuccessWithoutVerifiedEvidence(selfEval, claimView),
+        // v3.2: success without a machine-verified observation (never self-skips)
+        () => checkSuccessUnverified(selfEval, evidenceStatus),
+        // v2.12: criteria met but none machine-verified (mild criterion-specific rule)
+        () => checkUnverifiedCriteriaClaims(selfEval, claimView),
+        // v2.12: declared outcome vs legacy boolean consistency
+        () => checkOutcomeConsistency(selfEval),
+        // v2.12: retroactive claims against prior rounds
+        () => checkRetroactiveClaims(selfEval, vaultEntries, currentRound),
         () => checkDuplicateConstraintDiscovery(selfEval, prevSelfEval, olderViolations),
         () => checkRecurringViolation(selfEval, prevSelfEval, vaultEntries, currentRound),
         () => checkRetractFreshConstraint(selfEval, prevSelfEval, currentRound),
@@ -534,11 +940,13 @@ backtrackSkippedFiles = []) {
         // v2.0: Cross-validate agent-reported test_results against command output
         () => checkCommandEvidenceIntegrity(selfEval, evidenceSnapshots),
         // v2.1: Detect intent-action drift — agent said X but did Y
-        () => checkIntentDrift(selfEval, prevSelfEval),
+        () => checkIntentDrift(selfEval, prevSelfEval, vaultEntries),
         // 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),
+        // v2.12: Post-backtrack git HEAD restore check
+        () => checkBacktrackGitHeadRestore(evidenceSnapshots, backtrackTargetGitHead),
     ];
     for (const run of checks) {
         const flag = run();