loopforge 3.7.0 → 3.8.1

package/dist/enforcement-gate.js

@@ -17,11 +17,10 @@
  *              with stopReason "enforcement_terminated".
  */
 import { makeEnforcementResult } from "./protocol.js";
-import { machineProgressSeries, CHECK_SUCCESS_WITH_REMAINING_CRITERIA, CHECK_RECURRING_VIOLATION, CHECK_SUCCESS_WITHOUT_VERIFIED_EVIDENCE, CHECK_BACKTRACK_WORKSPACE_NOT_RESTORED, CHECK_REQUIRED_COMMAND_FAILED, CHECK_COMMAND_EVIDENCE_MISMATCH, CHECK_OUTCOME_SUCCESS_CONTRADICTION, CHECK_VERIFICATION_ENTRYPOINT_MODIFIED, CHECK_PREMATURE_BOUNDARY, CHECK_ROUND_SCOPE_DRIFT, CHECK_CONTRACT_COMPLETION_UNVERIFIED } from "./verification-gate.js";
-import { deriveConstraintId, deriveCriterionId, deriveSubGoalId } from "./loop-compiler.js";
+import { machineProgressSeries, CHECK_SUCCESS_WITH_REMAINING_CRITERIA, CHECK_RECURRING_VIOLATION, CHECK_SUCCESS_WITHOUT_VERIFIED_EVIDENCE, CHECK_BACKTRACK_WORKSPACE_NOT_RESTORED, CHECK_REQUIRED_COMMAND_FAILED, CHECK_COMMAND_EVIDENCE_MISMATCH, CHECK_OUTCOME_SUCCESS_CONTRADICTION, CHECK_VERIFICATION_ENTRYPOINT_MODIFIED, CHECK_ROUND_SCOPE_DRIFT, CHECK_CONTRACT_ITEMS_UNVERIFIED, CHECK_USER_GATE_UNRESOLVED } from "./verification-gate.js";
 import { getPolicy } from "./policy.js";
-import { STABLE_ID_RE, isRecord, entryRound, extractFilePathTokens } from "./token-utils.js";
-import { committedRoundsFromEntries, decodeCommittedRound, machineEvidenceForRound, } from "./committed-round.js";
+import { isRecord, entryRound } from "./token-utils.js";
+import { derivationRounds, decodeCommittedRound, machineEvidenceForRound, } from "./committed-round.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // Helpers
 // ═══════════════════════════════════════════════════════════════════════════
@@ -29,8 +28,8 @@ import { committedRoundsFromEntries, decodeCommittedRound, machineEvidenceForRou
  *  Shared by the progress evaluator's stall and flatline tiers. */
 function collectProgressByRound(vaultEntries, currentRound) {
     const progressByRound = new Map();
-    for (const round of committedRoundsFromEntries(vaultEntries, currentRound)) {
-        const progress = round.executionEvidence?.progress_estimate;
+    for (const round of derivationRounds(vaultEntries, currentRound)) {
+        const progress = round.executionReport?.progress_estimate;
         if (typeof progress === "number")
             progressByRound.set(round.round, progress);
     }
@@ -46,7 +45,7 @@ function collectProgressByRound(vaultEntries, currentRound) {
 function progressWindow(vaultEntries, currentRound, selfEval) {
     const progressByRound = collectProgressByRound(vaultEntries, currentRound);
     if (hasCommittedBacktrack(vaultEntries, currentRound)) {
-        const pe = selfEval.execution_evidence?.progress_estimate;
+        const pe = selfEval.execution_report?.progress_estimate;
         if (typeof pe === "number")
             progressByRound.set(currentRound, pe);
     }
@@ -89,7 +88,7 @@ function isCleanRound(round) {
  *  Collects discovered_constraints from skipped rounds along the way.
  *  Returns null when no clean round is found within maxDepth. */
 export function findSafeRestorePoint(currentRound, vaultEntries, maxDepth) {
-    const completed = committedRoundsFromEntries(vaultEntries, currentRound)
+    const completed = derivationRounds(vaultEntries, currentRound)
         .sort((a, b) => b.round - a.round);
     const skippedDiscoveries = [];
     for (let depth = 1; depth <= maxDepth; depth++) {
@@ -124,13 +123,13 @@ export function findSafeRestorePoint(currentRound, vaultEntries, maxDepth) {
  *  evidence as fallback). Returns null when the round has no git snapshot
  *  or no committed feedback entry. */
 export function findBacktrackTargetGitHead(restoreRound, vaultEntries) {
-    const committed = committedRoundsFromEntries(vaultEntries)
+    const committed = derivationRounds(vaultEntries)
         .find((view) => view.round === restoreRound);
     if (!committed)
         return null;
     const evidence = machineEvidenceForRound(committed);
     for (const item of evidence) {
-        if (!isRecord(item) || item.provider !== "git" || !isRecord(item.data))
+        if (!isRecord(item) || item.providerId !== "git" || !isRecord(item.data))
             continue;
         const head = item.data.head;
         if (typeof head === "string" && head.length > 0)
@@ -138,22 +137,77 @@ export function findBacktrackTargetGitHead(restoreRound, vaultEntries) {
     }
     return null;
 }
-/** Build the backtrack prompt injected at the top of the restored round.
+/** v3.8.1: the ONE Recovery Brief renderer.
  *
- *  v2.13: Includes concrete workspace restore instructions with affected
- *  file lists from skipped rounds. The agent must restore the working tree
- *  to the clean round's state before proceeding. */
-export function buildBacktrackPrompt(fromRound, toRound, triggerRule, skippedDiscoveries, 
+ *  The rollback prompt and the state file's Recent tier used to carry two
+ *  hand-written copies of these lines — differing in punctuation
+ *  ("the redo is round N" vs "redo round N") and in whether an approach
+ *  overflow count was shown at all. Two renderers over one rollback meant the
+ *  two surfaces could describe the same event differently while both claiming
+ *  to be derived facts. The facts are supplied by the caller: the coordinator
+ *  from its live walk, the compile path from `decodeBacktrackRecord` on the
+ *  committed decision. */
+export function recoveryBriefLines(input) {
+    const maxApproaches = input.maxApproaches ?? 6;
+    const maxAssumptions = input.maxAssumptions ?? 5;
+    const lines = [
+        `- **Trigger**: ${input.triggerRule || "unknown"}`,
+        `- **Restored to round**: ${input.target} (the redo is round ${input.target + 1})`,
+    ];
+    if (input.recoveryRoundId) {
+        lines.push(`- **Recovery Round ID**: \`${input.recoveryRoundId}\``);
+    }
+    if (input.failedRounds.length > 0) {
+        lines.push(`- **Failed rounds**: ${input.failedRounds.join(", ")}`);
+    }
+    const shown = input.approaches.slice(0, maxApproaches);
+    for (const approach of shown) {
+        lines.push(`  - Failed approach: ${approach}`);
+    }
+    if (input.approaches.length > shown.length) {
+        lines.push(`  - … and ${input.approaches.length - shown.length} more failed approaches`);
+    }
+    if (input.wrongAssumptions.length > 0) {
+        lines.push("- **Falsified assumptions** (do not rebuild on these):");
+        for (const assumption of input.wrongAssumptions.slice(0, maxAssumptions)) {
+            lines.push(`  - ${assumption}`);
+        }
+    }
+    return lines;
+}
+export function buildBacktrackPrompt(fromRound, toRound, triggerRule, skippedDiscoveries,
 /** v2.13: Files changed in the skipped rounds (from evidence snapshots).
  *  Used to show the agent exactly what needs to be reverted. */
-skippedFiles = [], 
+skippedFiles = [],
 /** v2.12: Git HEAD commit hash at the backtrack point (current HEAD).
  *  The agent must discard work back to the clean round's state. */
-gitHead) {
+gitHead,
+/** v3.7.1: The redo submission's roundId (loop:<id>:round:<toRound+1>). */
+recoveryRoundId,
+/** v3.7.1: Derived Recovery Brief facts — committed facts + the
+ *  in-flight attempt only; never rejected payloads. */
+recovery) {
     const lines = [
         `## ⛔ Backtrack — Round ${fromRound} → Restored to Round ${toRound}`,
         "",
     ];
+    // ── Recovery Brief (v3.7.1) ──────────────────────────────────────────
+    // A compact structured summary at the top of the rollback directive. The
+    // detailed sections below (workspace restore, discoveries, instructions)
+    // keep their existing wording; the brief exists so the agent cannot miss
+    // why it was rolled back, what failed, and what the redo round is.
+    if (recovery) {
+        lines.push("### Recovery Brief", "");
+        lines.push(...recoveryBriefLines({
+            target: toRound,
+            triggerRule,
+            failedRounds: recovery.failedRounds,
+            approaches: recovery.approaches,
+            wrongAssumptions: recovery.wrongAssumptions,
+            recoveryRoundId,
+        }));
+        lines.push("");
+    }
     // ── Why This Happened ────────────────────────────────────────────────
     // v3.7: stall and flatline are one evaluator emitting progress_stall; the
     // former flatline-specific wording ("zero forward motion → radically
@@ -180,24 +234,33 @@ gitHead) {
         }
         lines.push("");
     }
-    lines.push("**To restore a clean workspace, run:**", "", "```bash", "# Option A: Keep everything as a safety net (recommended) — reversible", `git stash push -u -m "backtrack-safety-net-round-${fromRound}"`, "", "# Option B: Discard ALL uncommitted AND untracked changes (permanent)", "git checkout -- .", "git clean -fd", "```", "", "> Option A is a safety net — do NOT `git stash pop` before submitting " +
-        "the next round: the skipped work would look unrestored and be rejected. " +
-        "Restore only files you own after the next round commits, via " +
-        "`git checkout stash@{0} -- <path>`.", "");
-    // v2.12: Restore to the exact commit observed at the clean round.
+    // v3.8: FACTS, not commands. LoopForge never mutates the working tree, and it
+    // does not prescribe how the agent restores it either — the restore is the
+    // AGENT's action, so the prompt states what must be true (the target HEAD and
+    // the files that must be reverted) and leaves the means entirely to the
+    // agent. No `git stash` / `git reset` / `git checkout` / `git clean` line
+    // belongs here.
     if (gitHead) {
-        lines.push(`**Restore to commit \`${gitHead.slice(0, 12)}\`** — the verification ` +
-            "gate checks that your working tree returns to this commit before " +
-            "accepting your next submission.", "", "```bash", "# Option C: If the failed rounds created commits, reset HEAD to the restore point", `git reset --hard ${gitHead.slice(0, 12)}`, "```", "", "> Option C discards the failed rounds' commits — use it only when those", "> commits belong to the failed work.", "");
+        lines.push("**The workspace must be returned to the restore point before you " +
+            "continue:**", "", `- HEAD must be at \`${gitHead.slice(0, 12)}\``, `- Every file listed above must be back in its state at Round ${toRound}`, `- No leftover change from rounds ${toRound + 1}–${fromRound} may remain`, "", "Your next submission's git observation is compared against that HEAD, " +
+            "and a file whose fingerprint still matches the failed round proves the " +
+            "restore did not happen.", "");
     }
-    lines.push(`**If git is unavailable**, manually revert the files listed above ` +
-        `to their state at Round ${toRound}. Re-read the state file below — ` +
+    else {
+        lines.push(`**The workspace must be returned to its state at Round ${toRound}** — ` +
+            "every file listed above reverted, with nothing left over from the " +
+            "failed rounds.", "");
+    }
+    lines.push("Restoring the workspace is **your** responsibility. LoopForge never " +
+        "modifies the working tree; it only records the restore requirement and " +
+        "checks the result.", "", `**If git is unavailable**, revert the files listed above by hand to ` +
+        `their state at Round ${toRound}. Re-read the state file below — ` +
         `it reflects the correct state at Round ${toRound}.`, "", "> 🛡️ **Verification:** The next round's evidence check will verify that " +
         "> your workspace no longer contains the failed changes. Submissions " +
         "> with unrestored files will be **rejected**.", "");
     // ── What Must Change ──────────────────────────────────────────────────
     lines.push("### What Must Change", "", "- Do **NOT** repeat the approach used in the skipped rounds.", "- Try a **different** task decomposition or technique.", "- If the current sub-goal is stuck, consider canceling it " +
-        "(`canceled_subtasks`) and working on a different one.", 
+        "(`subgoal_updates` to canceled) and working on a different one.",
     // v3.5: the restored Current Task may be the very Round Contract that
     // stalled — the agent must be told the sanctioned way to revise it
     // (outcome=blocked closes the active contract; the revised proposal in
@@ -226,7 +289,7 @@ gitHead) {
 // Individual enforcement rules — each returns EnforcementResult | null
 // Rules are ordered by priority. The first non-null result wins.
 // ═══════════════════════════════════════════════════════════════════════════
-/** R1: Agent claims success but success_criteria_remaining has items.
+/** R1: Agent claims success but declared criteria remain outstanding.
  *  This is a lie — the agent must either finish the criteria or
  *  set success=false honestly. Triggered by the verification gate's
  *  "success_with_remaining_criteria" error flag. */
@@ -333,118 +396,91 @@ function enforceSuccessWithoutVerifiedEvidence(flags, consecutiveRejections) {
             "test evidence and no test results were observed. Success must be backed " +
             "by machine-verifiable evidence.",
         fix_instructions: "Provide verifiable evidence for your success claim: (a) run tests and " +
-            "report results in execution_evidence.test_results, or (b) configure a " +
+            "report results in execution_report.tests_reported, or (b) configure a " +
             "required verification command and run it, or (c) if no change was " +
             "genuinely needed, declare no_change_reason explaining why." + escalation,
         check: "success_without_verified_evidence",
     });
 }
-/** R-C1 (v3.3): Round Contract boundary claimed prematurely. The gate
- *  produced premature_boundary (error): success claimed while done_when
- *  items were claimed met without machine-verified evidence or silently
- *  dropped. First occurrence → reject with contract-specific fix
- *  instructions; second consecutive → terminate (R8 ladder). */
-function enforcePrematureBoundary(flags, consecutiveRejections) {
-    const flag = flags.find((f) => f.check === CHECK_PREMATURE_BOUNDARY && f.severity === "error");
-    if (!flag)
+/** v3.8: Verification debt — contract items claimed met without machine
+ *  verification. The round COMMITS (insufficient is recorded, not rejected);
+ *  this row only fires once the debt has persisted for
+ *  `engine.unverified_claim_streak_limit` consecutive rounds, then runs its
+ *  OWN ladder: reject → terminate as `incomplete`.
+ *
+ *  v3.8.1: the ladder lives here (RULE_TABLE marks the row "internal").
+ *  Declaring it "uniform" as well ran the escalation twice — the notice was
+ *  appended twice to one fix_instructions — and made the uniform terminate
+ *  branch unreachable, while its bare `consecutiveRejections` read let a
+ *  streak earned by a DIFFERENT check terminate this row on its FIRST
+ *  occurrence, which is exactly what the L4 rule forbids.
+ *
+ *  The streak is derived from COMMITTED round flags, so it survives restart
+ *  and cannot be moved by an agent self-report. Git motion does not excuse
+ *  it: churning code without verifying is exactly what this row catches. */
+function enforceContractItemsUnverified(flags, currentRound, vaultEntries, consecutiveRejections, lastRejectionCheck) {
+    const limit = getPolicy().engine.unverified_claim_streak_limit;
+    if (!Number.isFinite(limit) || limit <= 0)
         return null;
-    if (consecutiveRejections >= 2) {
-        return makeEnforcementResult({
-            action: "terminate",
-            reason: "Repeated premature Round Contract boundary claims — done_when items " +
-                "claimed without machine evidence or dropped while success is claimed.",
-            check: "premature_boundary",
-        });
+    const current = flags.find((flag) => flag.check === CHECK_CONTRACT_ITEMS_UNVERIFIED);
+    if (!current)
+        return null;
+    let streak = 1;
+    for (let round = currentRound - 1; round >= 1; round--) {
+        const entry = vaultEntries.find((item) => entryRound(item) === round && String(item.task_id ?? "").endsWith(":feedback"));
+        const committed = entry ? decodeCommittedRound(entry) : null;
+        const carried = committed?.verificationFlags.some((flag) => flag.check === CHECK_CONTRACT_ITEMS_UNVERIFIED);
+        if (!carried)
+            break;
+        streak++;
     }
-    const escalation = getPolicy().engine.enforcement_escalation_enabled &&
-        consecutiveRejections >= 1
-        ? buildEscalationNotice()
-        : "";
-    return makeEnforcementResult({
-        action: "reject",
-        reason: flag.detail,
-        fix_instructions: "You claimed success under a Round Contract but done_when items are " +
-            "unfinished or unverified. You must: (a) run the contract's " +
-            "verification_plan commands (configured in loop_policy.json " +
-            "evidence.commands) and report their actual output, listing satisfied " +
-            "done_when items in success_criteria_met; or (b) set success=false and " +
-            "list what remains in success_criteria_remaining. " +
-            "Do NOT claim contract completion without machine evidence " +
-            "(no_change_reason does not apply to contract claims)." + escalation,
-        check: "premature_boundary",
-    });
-}
-/** v3.5: Round Contract completion claimed without its verification_plan
- *  commands passing this round. The gate produced
- *  contract_completion_unverified (error): the eval's met claims satisfy
- *  every done_when of the ACTIVE contract, but the machine never observed
- *  the plan's commands pass. Closing a contract is a success-class claim —
- *  first occurrence → reject with fix instructions; second consecutive →
- *  terminate (R-C1's ladder). Registered BEFORE R-C1: the completion-truth
- *  question outranks boundary nuance. */
-function enforceContractCompletionUnverified(flags, consecutiveRejections) {
-    const flag = flags.find((f) => f.check === CHECK_CONTRACT_COMPLETION_UNVERIFIED && f.severity === "error");
-    if (!flag)
+    if (streak < limit)
         return null;
-    if (consecutiveRejections >= 2) {
+    // The counter measures the PREVIOUS round's check (the coordinator resets it
+    // whenever the check changes), so it only speaks for this row when it names
+    // this row — same rule the uniform rows apply.
+    const ownRejections = lastRejectionCheck === "contract_items_unverified"
+        ? consecutiveRejections
+        : 0;
+    if (ownRejections >= 2) {
         return makeEnforcementResult({
             action: "terminate",
-            reason: "Repeated unverified Round Contract completion claims — done_when items " +
-                "claimed complete while the verification_plan commands never passed.",
-            check: "contract_completion_unverified",
+            reason: `Verification debt persisted for ${streak} rounds — contract items ` +
+                `claimed met while no bound command was observed passing.`,
+            check: "contract_items_unverified",
+            stopReason: "incomplete",
         });
     }
     const escalation = getPolicy().engine.enforcement_escalation_enabled &&
-        consecutiveRejections >= 1
+        ownRejections >= 1
         ? buildEscalationNotice()
         : "";
     return makeEnforcementResult({
         action: "reject",
-        reason: flag.detail,
-        fix_instructions: "You claimed completion under the ACTIVE Round Contract, but its " +
-            "verification_plan commands did not pass this round. You must: (a) fix " +
-            "the underlying failure, re-run the contract's verification_plan " +
-            "commands (configured in loop_policy.json evidence.commands), and list " +
-            "satisfied done_when items in success_criteria_met; or (b) set " +
-            "success=false and list what remains in success_criteria_remaining. " +
-            "Completion claims are never accepted without machine verification — " +
-            "do NOT use no_change_reason for completion claims." + escalation,
-        check: "contract_completion_unverified",
+        reason: current.detail,
+        fix_instructions: `Contract items have been claimed met for ${streak} consecutive rounds ` +
+            "without machine verification. You must either: (a) run the item's bound " +
+            "command(s) so they are observed passing, or (b) report the item as " +
+            "remaining / declare outcome: \"blocked\" with a blocker. " +
+            "An unverified claim is never accepted as completion." + escalation,
+        check: "contract_items_unverified",
     });
 }
 /** R-C2 (v3.3): Round Contract scope drift. The gate produced
  *  round_scope_drift (warn): files changed outside the contract's declared
- *  scope. A substantive drift_clarification (≥ 20 chars with real anchors —
- *  the out-of-scope file paths count) accepts the legitimately expanded
- *  scope; no/weak clarification rejects; repeated unclarified drift
- *  terminates. Mirrors R8's ladder, not R7's streak counter — no new
- *  session state. */
-function enforceScopeDrift(flags, selfEval, consecutiveRejections, vaultEntries = []) {
+ *  scope. v3.8: scope drift is a MACHINE fact and is no longer waivable by an
+ *  agent explanation (the drift_clarification channel was deleted) — the
+ *  agent must revert the out-of-scope changes or close the active contract
+ *  and declare an extended scope. Repeated drift terminates. */
+function enforceScopeDrift(flags, consecutiveRejections) {
     const flag = flags.find((f) => f.check === CHECK_ROUND_SCOPE_DRIFT);
     if (!flag)
         return null;
-    const clarification = selfEval.drift_clarification?.trim();
-    const hasAnchor = clarification
-        ? clarificationIsSubstantive(clarification, selfEval, vaultEntries)
-        : false;
-    const isSubstantive = clarification !== undefined
-        && clarification.length >= 20
-        && hasAnchor;
-    if (isSubstantive) {
-        // Genuine scope expansion with concrete file references → accept.
-        return makeEnforcementResult({
-            action: "accept",
-            reason: "",
-            fix_instructions: "",
-            check: "round_scope_drift",
-            clarification_accepted: true,
-        });
-    }
     if (consecutiveRejections >= 2) {
         return makeEnforcementResult({
             action: "terminate",
-            reason: `Repeated scope drift without substantive drift_clarification — ` +
-                `the agent keeps changing files outside its declared contract scope.`,
+            reason: `Repeated scope drift — the agent keeps changing files outside its ` +
+                `declared contract scope.`,
             check: "round_scope_drift",
         });
     }
@@ -455,12 +491,21 @@ function enforceScopeDrift(flags, selfEval, consecutiveRejections, vaultEntries
     return makeEnforcementResult({
         action: "reject",
         reason: flag.detail,
+        // L3 (v3.7.x): option (b) previously told the agent to "extend the scope
+        // in your re-declared round_contract" — structurally unreachable: while a
+        // contract is ACTIVE, a replacement proposal is ignored as premature, so
+        // the guidance dead-ended into repeated rejects/termination. The only
+        // legal scope change is to CLOSE the active contract first: resubmit with
+        // outcome="blocked" (blocker naming the too-narrow scope) and the
+        // extended scope as the NEXT round's contract in the same submission.
         fix_instructions: "Files changed outside the contract's declared scope. You must either: " +
-            "(a) revert the out-of-scope changes, or (b) extend the scope in your " +
-            "re-declared round_contract AND explain the pivot in drift_clarification " +
-            "with concrete file paths (≥ 20 characters, real anchors). Weak or " +
-            "missing clarifications are rejected; repeated scope drift terminates " +
-            "the loop." + escalation,
+            "(a) revert the out-of-scope changes, or (b) legally extend the scope: " +
+            "a replacement contract is IGNORED while the current one is active, so " +
+            "resubmit this work with outcome: \"blocked\" (blocker naming the " +
+            "too-narrow scope) plus the extended scope as the next round's " +
+            "round_contract. Scope drift is a machine fact — no explanation waives " +
+            "it. Repeated scope drift terminates the loop." +
+            escalation,
         check: "round_scope_drift",
     });
 }
@@ -489,27 +534,57 @@ function enforceBacktrackNotRestored(flags, vaultEntries = [], currentRound = 0)
     return makeEnforcementResult({
         action: "backtrack",
         reason: "The workspace was not restored after backtrack: " + flag.detail,
-        fix_instructions: "Restore the working directory to the clean round's state " +
-            "(git checkout -- . && git clean -fd, or git stash; if the failed " +
-            "rounds created commits, git reset --hard <restore-commit>) before " +
-            "submitting the next round.",
+        // v3.8: the requirement, not the recipe — LoopForge never mutates the
+        // working tree and does not prescribe how the agent restores it.
+        fix_instructions: "Return the working directory to the clean round's state before " +
+            "submitting the next round: the skipped-round files must be reverted " +
+            "and HEAD must be back at the restore point the backtrack prompt named.",
         check: "backtrack_workspace_not_restored",
     });
 }
 /** Shared observation pipeline for the progress evaluator (stall window,
  *  flatline tier). Machine git motion is exculpatory only: it may veto a
  *  self-reported stall but can never create one. */
-function evaluateStallWindow(tier, selfEval, currentRound, vaultEntries) {
+function evaluateStallWindow(tier, selfEval, currentRound, vaultEntries,
+/** v3.8.1: the round's success is machine-verified (`deriveEvidenceStatus`).
+ *  A verified round is finishing work; a motion window cannot outvote it. */
+machineBackedSuccess) {
+    // A round the machine verified is not churn, whatever the window says. This
+    // is the machine-backed replacement for the old self-reported `>= 0.95`
+    // near-completion guard: it lets a loop FINISH (a closing round that only
+    // runs the verification and declares success changes no files).
+    if (machineBackedSuccess)
+        return null;
     const window = tier === "progress_stall"
         ? 3
         : Math.max(1, getPolicy().engine.stall_lookback_rounds);
     if (currentRound < window)
         return null;
     const progressByRound = progressWindow(vaultEntries, currentRound, selfEval);
+    const threshold = getPolicy().evolution.progress_stall_threshold;
     let stalled = false;
     let detail = "";
-    const threshold = getPolicy().evolution.progress_stall_threshold;
-    if (progressByRound.size >= window) {
+    // v3.8.1: when the MACHINE series is observable it decides the verdict, and
+    // the agent's own estimates are not consulted at all. Reading the estimates
+    // first (the pre-3.8.1 order) let an agent cancel a stall by writing a
+    // rising `progress_estimate` every round — a verdict about machine motion
+    // that the agent's own report could move, which is the one thing an external
+    // verifier must not allow. Machine motion still only ever EXCUSES: it can
+    // veto a stall it did not create; it can never create one.
+    //
+    // The self-reported window is the FALLBACK for a loop with no machine
+    // history to read (no git provider, or fewer rounds than the window). There
+    // the evaluator can only catch a stall the agent's own reports state, and
+    // the near-completion guard keeps it from rejecting a loop that reports
+    // itself nearly done.
+    const machine = machineProgressSeries(vaultEntries, currentRound, window);
+    if (machine !== null) {
+        stalled = machine.every((value) => !value);
+        detail = tier === "progress_stall"
+            ? `no machine-observed changes in the last ${window} rounds`
+            : `no machine-observed changes for ${window} consecutive rounds`;
+    }
+    else if (progressByRound.size >= window) {
         const recent = [...progressByRound.keys()].sort((a, b) => a - b).slice(-window);
         if (recent[0] < currentRound - window)
             return null;
@@ -518,7 +593,8 @@ function evaluateStallWindow(tier, selfEval, currentRound, vaultEntries) {
             return null;
         if (tier === "progress_stall") {
             stalled = values.slice(1).every((value, index) => value - values[index] < threshold);
-            detail = values.map((value) => `${(value * 100).toFixed(0)}%`).join(" → ");
+            detail = `${values.map((value) => `${(value * 100).toFixed(0)}%`).join(" → ")}` +
+                " (agent-reported, no machine history to read)";
         }
         else {
             const first = values[0];
@@ -527,22 +603,10 @@ function evaluateStallWindow(tier, selfEval, currentRound, vaultEntries) {
         }
     }
     else {
-        const machine = machineProgressSeries(vaultEntries, currentRound, window);
-        if (machine === null)
-            return null;
-        stalled = machine.every((value) => !value);
-        detail = tier === "progress_stall"
-            ? `no machine-observed changes in the last ${window} rounds`
-            : `no machine-observed changes for ${window} consecutive rounds`;
+        return null;
     }
     if (!stalled)
         return null;
-    const machine = machineProgressSeries(vaultEntries, currentRound, window);
-    if (machine?.some(Boolean))
-        return null;
-    if (machine !== null) {
-        detail += ` — no machine-observed git motion in rounds ${currentRound - window}–${currentRound - 1}`;
-    }
     return { tier, detail, window, threshold };
 }
 /** Shared progress escalation and backtrack deadlock guard (v3.7: one
@@ -616,9 +680,9 @@ function resolveStallDisposition(verdict, currentRound, vaultEntries, consecutiv
  *  shorter lookback configs), where it applies its steeper disposition
  *  ladder. Machine git motion is exculpatory only — it may veto a
  *  self-reported stall but can never create one. */
-function enforceProgressStall(selfEval, _flags, currentRound, vaultEntries, consecutiveRejections) {
-    const verdict = evaluateStallWindow("progress_stall", selfEval, currentRound, vaultEntries)
-        ?? evaluateStallWindow("progress_flatline", selfEval, currentRound, vaultEntries);
+function enforceProgressStall(selfEval, _flags, currentRound, vaultEntries, consecutiveRejections, machineBackedSuccess) {
+    const verdict = evaluateStallWindow("progress_stall", selfEval, currentRound, vaultEntries, machineBackedSuccess)
+        ?? evaluateStallWindow("progress_flatline", selfEval, currentRound, vaultEntries, machineBackedSuccess);
     return verdict
         ? resolveStallDisposition(verdict, currentRound, vaultEntries, consecutiveRejections)
         : null;
@@ -666,212 +730,6 @@ function enforceMaxRejections(consecutiveRejections) {
         check: "max_rejections",
     });
 }
-/** v2.12: Check if a drift_clarification contains at least one semantic
- *  anchor — a constraint/criterion/sub-goal ID (v2.11) or a file-path-like
- *  reference. This distinguishes genuine explanations from filler text that
- *  just happens to be ≥ 20 characters. */
-/** Extract anchor candidates from a clarification: c-/cr-/sg- IDs and
- *  file-path-like tokens. */
-function extractAnchors(clarification) {
-    const anchors = new Set();
-    for (const match of clarification.matchAll(/[c]r?-[a-f0-9]{8}|sg-[a-f0-9]{8}/gi)) {
-        anchors.add(match[0].toLowerCase());
-    }
-    for (const path of extractFilePathTokens(clarification)) {
-        anchors.add(path);
-    }
-    return [...anchors];
-}
-/** v2.12: A drift clarification is substantive only when at least one anchor
- *  is REAL — a stable ID that derives from a known constraint/criterion/
- *  sub-goal text in the vault, or a file path present in reported/observed
- *  files. Regex patterns alone (e.g. a fabricated `c-00000000`) no longer
- *  count, closing the v2.12 filler-text loophole. */
-function clarificationIsSubstantive(clarification, selfEval, vaultEntries) {
-    const anchors = extractAnchors(clarification);
-    if (anchors.length === 0)
-        return false;
-    const knownFiles = new Set();
-    const knownTexts = new Set();
-    const collect = (values) => {
-        if (!Array.isArray(values))
-            return;
-        for (const value of values) {
-            if (typeof value === "string" && value.length > 0)
-                knownTexts.add(value);
-        }
-    };
-    // The agent's own round report is a known set: its constraints, criteria,
-    // and files are legitimate anchor targets.
-    for (const file of selfEval.execution_evidence?.files_changed ?? [])
-        knownFiles.add(file);
-    collect(selfEval.discovered_constraints);
-    collect(selfEval.constraint_violations);
-    const selfEvidence = selfEval.execution_evidence;
-    if (selfEvidence) {
-        collect(selfEvidence.success_criteria_met);
-        collect(selfEvidence.success_criteria_remaining);
-    }
-    for (const entry of vaultEntries) {
-        collect(entry.constraint_violations);
-        collect(entry.discovered_constraints);
-        const ev = entry.execution_evidence;
-        if (ev) {
-            collect(ev.files_changed);
-            collect(ev.success_criteria_met);
-            collect(ev.success_criteria_remaining);
-        }
-    }
-    for (const anchor of anchors) {
-        if (STABLE_ID_RE.test(anchor)) {
-            const matches = anchor.startsWith("c-") && !anchor.startsWith("cr-")
-                ? [...knownTexts].some((text) => deriveConstraintId(text) === anchor)
-                : anchor.startsWith("cr-")
-                    ? [...knownTexts].some((text) => deriveCriterionId(text) === anchor)
-                    : [...knownTexts].some((text) => deriveSubGoalId(text) === anchor);
-            if (matches)
-                return true;
-            continue;
-        }
-        // File path: exact or suffix match against known files.
-        if ([...knownFiles].some((file) => file === anchor || file.endsWith(`/${anchor}`) || file.endsWith(`\\${anchor}`))) {
-            return true;
-        }
-    }
-    return false;
-}
-/** Build a stronger rejection notice as the clarification streak grows. */
-function buildClarificationRejectionNotice(streak) {
-    const base = "Your declared next_action from the previous round does not match " +
-        "what you actually did this round. You must either: " +
-        "(a) explain why you pivoted in the drift_clarification field, " +
-        "mentioning specific constraint/criterion/sub-goal IDs or file paths " +
-        "that prompted the change, or " +
-        "(b) redo this round and do what you said you would do.";
-    if (streak >= 2) {
-        return (base +
-            "\n\n### ⚠️ Repeated Weak Clarification\n\n" +
-            `You have submitted drift_clarification without concrete references ` +
-            `for ${streak} consecutive rounds. Your explanation MUST include at ` +
-            `least one of: a constraint ID (c-XXXXXXXX), criterion ID (cr-XXXXXXXX), ` +
-            `sub-goal ID (sg-XXXXXXXX), or a file path you changed.\n\n` +
-            `🚨 If the next clarification also lacks concrete anchors, the loop ` +
-            `will be terminated.`);
-    }
-    return base;
-}
-/** R7: Agent declared a next_action but did something unrelated.
- *
- *  v2.8: When the agent provides a substantive drift_clarification (≥ 20
- *  characters), the rejection is waived — the agent has acknowledged and
- *  explained the pivot. An empty or absent clarification still triggers
- *  the normal reject/terminate path.
- *
- *  v2.12: Clarification now requires a semantic anchor (constraint/criterion/
- *  sub-goal ID or file path) in addition to the ≥ 20 char minimum. Weak
- *  clarifications (no anchors) increment a streak counter; 3 consecutive
- *  weak clarifications terminate the loop.
- *
- *  First occurrence → reject (agent must explain the gap or realign).
- *  Second consecutive → terminate (agent cannot/will not follow its own plan). */
-function enforceIntentDrift(flags, selfEval, consecutiveRejections, driftClarificationStreak = 0, vaultEntries = []) {
-    const flag = flags.find((f) => f.check === "intent_drift");
-    if (!flag)
-        return null;
-    const clarification = selfEval.drift_clarification?.trim();
-    // v2.12: Substantive anchors — the referenced ID/path must actually exist
-    // in the vault or in reported files; a fabricated ID no longer counts.
-    const hasAnchor = clarification
-        ? clarificationIsSubstantive(clarification, selfEval, vaultEntries)
-        : false;
-    // v2.12: Substantive clarification = length check + semantic anchor
-    const isSubstantive = clarification
-        && clarification.length >= 20
-        && hasAnchor;
-    if (isSubstantive) {
-        // Genuine explanation with concrete references → accept the pivot
-        return makeEnforcementResult({
-            action: "accept",
-            reason: "",
-            fix_instructions: "",
-            check: "intent_drift",
-            clarification_accepted: true,
-        });
-    }
-    // v2.12: Clarification present but weak (no semantic anchors)
-    if (clarification && clarification.length >= 20 && !hasAnchor) {
-        const maxStreak = getPolicy().engine.drift_clarification_max_streak;
-        // When maxStreak is 0, disable the check (pre-v2.12 behavior)
-        if (maxStreak <= 0) {
-            return makeEnforcementResult({
-                action: "accept",
-                reason: "",
-                fix_instructions: "",
-                check: "intent_drift",
-                clarification_accepted: true,
-            });
-        }
-        const newStreak = driftClarificationStreak + 1;
-        if (newStreak >= maxStreak) {
-            return makeEnforcementResult({
-                action: "terminate",
-                reason: `Agent has submitted weak drift_clarification (no concrete IDs or ` +
-                    `file references) for ${newStreak} consecutive rounds. The agent ` +
-                    `systematically avoids following its own plan without substantive ` +
-                    `explanation.`,
-                check: "intent_drift",
-            });
-        }
-        return makeEnforcementResult({
-            action: "reject",
-            reason: flag.detail,
-            fix_instructions: buildClarificationRejectionNotice(newStreak),
-            check: "intent_drift",
-        });
-    }
-    // No clarification or too short — the worst form of drift. v2.14: counts
-    // toward the SAME streak as weak clarifications (maxStreak consecutive
-    // un-explained drifts terminate, per the README's "three consecutive weak
-    // clarifications"). Previously this branch used the GLOBAL
-    // consecutiveRejections counter, so an unrelated earlier rejection
-    // (e.g. R1) terminated the loop on the very first drift.
-    const maxStreak = getPolicy().engine.drift_clarification_max_streak;
-    // When maxStreak is 0, disable the check (pre-v2.12 behavior)
-    if (maxStreak <= 0) {
-        return makeEnforcementResult({
-            action: "accept",
-            reason: "",
-            fix_instructions: "",
-            check: "intent_drift",
-            clarification_accepted: true,
-        });
-    }
-    const newStreak = driftClarificationStreak + 1;
-    if (newStreak >= maxStreak) {
-        return makeEnforcementResult({
-            action: "terminate",
-            reason: `Agent has drifted from its declared next_action for ${newStreak} ` +
-                `consecutive rounds without any drift_clarification. The agent ` +
-                `cannot or will not follow its own plan — terminating loop.`,
-            check: "intent_drift",
-        });
-    }
-    return makeEnforcementResult({
-        action: "reject",
-        reason: flag.detail,
-        fix_instructions: "Your declared next_action from the previous round does not match " +
-            "what you actually did this round. You must either: " +
-            "(a) explain why you pivoted and what you learned in the " +
-            "drift_clarification field, or " +
-            "(b) redo this round and do what you said you would do. " +
-            "If you intentionally changed direction, update your objective_refinement " +
-            "and set a new next_action that reflects the new plan.",
-        check: "intent_drift",
-    });
-}
-// ═══════════════════════════════════════════════════════════════════════════
-// Escalation notice builder (v2.7)
-// ═══════════════════════════════════════════════════════════════════════════
 /** Build an escalation notice urging the agent to seek human guidance.
  *
  *  Appended to fix_instructions when a rule would otherwise terminate.
@@ -922,22 +780,21 @@ function buildDiagnosticGap(flags) {
     return lines.join("\n");
 }
 const RULE_TABLE = [
-    // R1/R2 join the contradiction umbrella per the documented four-class model
-    // (AGENTS/README/CHANGELOG): a row's category is its enforcement action
-    // class, NOT the trigger check's gate domain — claim-vs-self-reported-facts
-    // rows (outcome_success_contradiction included) belong to this class too.
-    { category: "evidence_contradiction", checks: ["success_with_remaining_criteria"], ladder: "uniform", terminalAfter: 2, noticeOnRepeat: true },
-    { category: "evidence_contradiction", checks: ["recurring_violation"], ladder: "uniform", terminalAfter: 2, noticeOnRepeat: true },
-    { category: "evidence_contradiction", checks: ["required_command_failed", "command_evidence_mismatch", "outcome_success_contradiction"], ladder: "uniform", terminalAfter: 2, noticeOnRepeat: true },
-    { category: "evidence_contradiction", checks: ["verification_entrypoint_modified"], ladder: "uniform", terminalAfter: 2, noticeOnRepeat: true },
-    { category: "contract_scope", checks: ["contract_completion_unverified"], ladder: "internal" },
-    { category: "contract_scope", checks: ["premature_boundary"], ladder: "internal" },
-    { category: "evidence_contradiction", checks: ["success_without_verified_evidence"], ladder: "internal" },
-    { category: "contract_scope", checks: ["round_scope_drift"], ladder: "internal", clarificationAllowed: true },
-    { category: "progress_recovery", checks: ["progress_stall"], ladder: "internal", backtrackAllowed: true },
-    { category: "progress_recovery", checks: ["max_rejections"], ladder: "counter" },
-    { category: "plan_drift", checks: ["intent_drift"], ladder: "internal", clarificationAllowed: true },
-    { category: "progress_recovery", checks: ["backtrack_workspace_not_restored"], ladder: "internal", backtrackAllowed: true },
+    { checks: ["success_with_remaining_criteria"], ladder: "uniform", terminalAfter: 2, noticeOnRepeat: true },
+    { checks: ["recurring_violation"], ladder: "uniform", terminalAfter: 2, noticeOnRepeat: true },
+    { checks: ["required_command_failed", "command_evidence_mismatch", "outcome_success_contradiction"], ladder: "uniform", terminalAfter: 2, noticeOnRepeat: true },
+    { checks: ["verification_entrypoint_modified"], ladder: "uniform", terminalAfter: 2, noticeOnRepeat: true },
+    { checks: ["success_without_verified_evidence"], ladder: "internal" },
+    { checks: ["round_scope_drift"], ladder: "internal" },
+    // v3.8.1: "internal" — the handler owns this row's ladder (it must terminate
+    // as `incomplete`, with its own reason). Declaring it uniform as well ran the
+    // escalation notice twice and left the uniform terminate branch dead.
+    { checks: ["contract_items_unverified"], ladder: "internal" },
+    { checks: ["progress_stall"], ladder: "internal" },
+    { checks: ["max_rejections"], ladder: "counter" },
+    { checks: ["backtrack_workspace_not_restored"], ladder: "internal" },
+    // v3.7.1: cited gates without an approved human decision
+    { checks: ["user_gate_unresolved"], ladder: "uniform", terminalAfter: 2, noticeOnRepeat: true },
 ];
 const RULE_TABLE_BY_ID = new Map();
 for (const row of RULE_TABLE) {
@@ -961,9 +818,33 @@ for (const row of RULE_TABLE) {
  * @param consecutiveRejections How many consecutive rounds have already been rejected.
  *                              Starts at 0; increments on each reject; resets on accept.
  */
-export function enforceRound(selfEval, verifyResult, currentRound, vaultEntries, consecutiveRejections = 0, 
-/** v2.12: Current clarification streak for R7 escalation. */
-driftClarificationStreak = 0) {
+/** v3.7.1: user_gate_unresolved — the round cites gates without an
+ *  approved human decision. Reject; the uniform ladder escalates repeats
+ *  (the agent should pause and obtain approval — never resubmit a claim of
+ *  completed high-risk work). */
+function enforceUserGateUnresolved(flags) {
+    const flag = flags.find((f) => f.check === CHECK_USER_GATE_UNRESOLVED && f.severity === "error");
+    if (!flag)
+        return null;
+    return makeEnforcementResult({
+        action: "reject",
+        reason: flag.detail,
+        fix_instructions: "The round depends on a high-risk action with no approved human " +
+            "decision. Run loopforge_gate_check with the action, present the " +
+            "approval question, and call loopforge_gate_resolve only after the " +
+            "human decides. Then resubmit with the approved gate id in " +
+            "evaluation.gate_ids. Do NOT claim the action is done while it is " +
+            "unapproved — safe preparation work never needs a gate.",
+        check: CHECK_USER_GATE_UNRESOLVED,
+    });
+}
+export function enforceRound(selfEval, verifyResult, currentRound, vaultEntries, consecutiveRejections = 0,
+/** L4 (v3.7.x): which check rejected the PREVIOUS round. The coordinator
+ *  resets consecutiveRejections to 1 whenever the check changes, so the
+ *  counter only ever measures one check's streak — this field names that
+ *  check and lets uniform rows escalate on THEIR OWN streak instead of
+ *  inheriting an unrelated history. */
+lastRejectionCheck = "") {
     const { flags } = verifyResult;
     // Run enforcement rules in priority order — the array order IS the
     // priority; the R-labels in the comments are historical (RULE_TABLE is
@@ -981,25 +862,25 @@ driftClarificationStreak = 0) {
         // v3.5: contract completion claimed without its verification_plan
         // commands passing — runs before R-C1: the completion-truth question
         // outranks boundary nuance.
-        () => enforceContractCompletionUnverified(flags, consecutiveRejections),
         // v3.3: R-C1 — contract boundary claimed prematurely (contract-specific
         // wording and check counting; runs before R8 so contract rounds get the
         // contract's own reason.)
-        () => enforcePrematureBoundary(flags, consecutiveRejections),
         // v2.12/v3.7: R8 — the single success-evidence row (empty/missing-evidence
         // arm merged from the former R3 empty_success posture + claims arm)
         () => enforceSuccessWithoutVerifiedEvidence(flags, consecutiveRejections),
         // v3.3: R-C2 — files changed outside the contract's declared scope
-        () => enforceScopeDrift(flags, selfEval, consecutiveRejections, vaultEntries),
+        () => enforceScopeDrift(flags, consecutiveRejections),
+        // v3.8: verification debt — contract items claimed met without machine
+        // verification (fires only after the configured streak)
+        () => enforceContractItemsUnverified(flags, currentRound, vaultEntries, consecutiveRejections, lastRejectionCheck),
         // v3.7: single progress evaluator (former R4/R5 slots merged) —
         // reject → backtrack → terminate with the deadlock guard
-        () => enforceProgressStall(selfEval, flags, currentRound, vaultEntries, consecutiveRejections),
+        () => enforceProgressStall(selfEval, flags, currentRound, vaultEntries, consecutiveRejections, verifyResult.machineBackedSuccess),
         // R6: rejection-counter catch-all (evaluated only when no row above
         // fired — a clean-looking round carrying a high persisted counter)
+        // v3.7.1: cited gate without an approved human decision
+        () => enforceUserGateUnresolved(flags),
         () => enforceMaxRejections(consecutiveRejections),
-        // v2.12: R7 — intent drift; its weak-clarification streak is a separate
-        // counter and never mixes with the global rejection count
-        () => enforceIntentDrift(flags, selfEval, consecutiveRejections, driftClarificationStreak, vaultEntries),
         // v2.12: R9 — post-backtrack workspace not restored
         () => enforceBacktrackNotRestored(flags, vaultEntries, currentRound),
     ];
@@ -1020,16 +901,26 @@ driftClarificationStreak = 0) {
             ? RULE_TABLE_BY_ID.get(result.check)
             : undefined;
         if (result.action === "reject" && row && row.ladder === "uniform") {
-            if (consecutiveRejections >= (row.terminalAfter ?? 2)) {
+            // L4: uniform rows escalate on their OWN consecutive streak only.
+            // consecutiveRejections is the streak of the PREVIOUS round's check
+            // (the coordinator resets it to 1 whenever the check changes) — a
+            // streak earned by a DIFFERENT check must not convert this first
+            // occurrence into termination. The user_gate row is the sharp case:
+            // its recovery is human approval, so a gate cited after unrelated
+            // rejections must reject with instructions, not kill the loop.
+            const ownStreak = lastRejectionCheck === result.check
+                ? consecutiveRejections
+                : 0;
+            if (ownStreak >= (row.terminalAfter ?? 2)) {
                 return makeEnforcementResult({
                     action: "terminate",
-                    reason: `${consecutiveRejections + 1} consecutive rejections for the same ` +
+                    reason: `${ownStreak + 1} consecutive rejections for the same ` +
                         `issue (${result.check}) without resolution — the agent cannot ` +
                         `correct it even after escalation.`,
                     check: result.check,
                 });
             }
-            if (consecutiveRejections >= 1 && row.noticeOnRepeat &&
+            if (ownStreak >= 1 && row.noticeOnRepeat &&
                 getPolicy().engine.enforcement_escalation_enabled) {
                 result = makeEnforcementResult({
                     ...result,