@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/core/next-action-phases.js

@@ -5,7 +5,7 @@ import { resolvePlannedPhase } from "./next-action-planned-phase.js";
 import { resolvePendingActionGuidance } from "./next-action-pending-actions.js";
 import { preExecutionRefreshGuidance } from "./next-action-refresh.js";
 import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
-import { taskArtifactPath } from "./task-paths.js";
+import { taskArtifactPath, taskGatePath } from "./task-paths.js";
 import { completionIdentityErrors, evaluateCompletion } from "./completion.js";
 import { readContract } from "./contract.js";
 import { evaluatePreflight, validatePersistedPreflight } from "./preflight.js";
@@ -16,10 +16,16 @@ import { classifyLoadedWorkState } from "./work-state.js";
 
 import { evaluateStartExecutionPrerequisites } from "./execution-prerequisites.js";
 
-import { NEXT_ACTIONS, commandFor, decision, recoveryGuidanceForClassification, result, uniqueSorted } from "./next-action-model.js";
+import { NEXT_ACTIONS, commandFor, decision, gateRevalidationCommandSpec, recoveryGuidanceForClassification, result, routeCommandSpec, uniqueSorted } from "./next-action-model.js";
 import { artifactError, freshnessReasons, loadArtifact, staleReasons } from "./next-action-artifacts.js";
 
 import { inspectTaskConflictState } from "./task-conflict-inspection.js";
+import { validateEventLedger } from "./events.js";
+import {
+  isContractBootstrapRepairCandidate,
+  isLegacyContractBootstrapRepairMigrationCandidate,
+} from "./contract-bootstrap-recovery.js";
+import { contractBootstrapRepairGuidance, contractBootstrapRepairMigrationGuidance } from "./next-action-model.js";
 
 import { evaluateContinuityNextAction } from "./next-action-continuity.js";
 
@@ -32,10 +38,85 @@ export const PHASES_REQUIRING_EXECUTION_CHRONOLOGY = new Set([
   "COMPLETE",
 ]);
 
+const PHASES_ALLOWING_GATE_REVALIDATION = new Set([
+  "EXECUTING", "VERIFYING", "DIAGNOSING", "CORRECTING", "REVIEWING",
+]);
+
 export function phaseRequiresExecutionChronology(phase) {
   return PHASES_REQUIRING_EXECUTION_CHRONOLOGY.has(phase);
 }
 
+async function contractBootstrapRepairGuidanceForExplicitTask({ target, packageRoot, explicitTaskId, context, eventsRel, stateRel }) {
+  const ledger = await validateEventLedger(target, packageRoot, { taskId: explicitTaskId });
+  const candidate = isContractBootstrapRepairCandidate(ledger.events, ledger.errors, explicitTaskId);
+  if (candidate) {
+    const guidance = contractBootstrapRepairGuidance(explicitTaskId);
+    return result({
+      ...context,
+      nextAction: guidance.nextAction,
+      commands: guidance.commands,
+      commandSpecs: guidance.commandSpecs,
+      reasons: [artifactError(guidance.reason.code, guidance.reason.message, [eventsRel, taskArtifactPath(explicitTaskId, "state")])],
+      requiredArtifacts: [eventsRel, taskArtifactPath(explicitTaskId, "contract")],
+    });
+  }
+  const tolerantLedger = await validateEventLedger(target, packageRoot, {
+    taskId: explicitTaskId,
+    allowUnmigratedLegacyContractBootstrapRepairMarkers: true,
+  });
+  if (!tolerantLedger.valid || !isLegacyContractBootstrapRepairMigrationCandidate(tolerantLedger.events, explicitTaskId)) {
+    return null;
+  }
+  const guidance = contractBootstrapRepairMigrationGuidance(explicitTaskId);
+  return result({
+    ...context,
+    nextAction: guidance.nextAction,
+    commands: guidance.commands,
+    commandSpecs: guidance.commandSpecs,
+    reasons: [artifactError(guidance.reason.code, guidance.reason.message, [eventsRel, stateRel])],
+    requiredArtifacts: [eventsRel, taskArtifactPath(explicitTaskId, "contract"), stateRel],
+  });
+}
+
+async function explicitTaskConflictGuidance({ target, packageRoot, explicitTaskId, context, eventsRel, stateRel, state }) {
+  try {
+    const migrationGuidance = await contractBootstrapRepairGuidanceForExplicitTask({
+      target, packageRoot, explicitTaskId, context, eventsRel, stateRel,
+    });
+    if (migrationGuidance) return migrationGuidance;
+  } catch {
+    // The regular conflict inspection below remains the fail-closed path.
+  }
+  let inspection;
+  try {
+    inspection = await inspectTaskConflictState(target, {
+      taskId: explicitTaskId,
+      packageRoot,
+    });
+  } catch (error) {
+    inspection = {
+      classification: "INCONSISTENT",
+      reasonCodes: [error.code ?? "E_TASK_RECOVERY_INCONSISTENT"],
+    };
+  }
+  if (["ACTIVE", "COMPLETE"].includes(inspection.classification)) return null;
+  if (PHASES_ALLOWING_GATE_REVALIDATION.has(state?.phase)
+    && inspection.reasonCodes?.includes("E_GATE_STALE")) return null;
+  const guidance = recoveryGuidanceForClassification(inspection.classification, explicitTaskId);
+  return result({
+    ...context,
+    nextAction: guidance.nextAction,
+    commands: guidance.commands,
+    commandSpecs: guidance.commandSpecs,
+    reasons: inspection.reasonCodes.map((code) => artifactError(
+      code,
+      `Task conflict state is ${inspection.classification}; follow the structured recovery guidance.`,
+      [stateRel, eventsRel, taskArtifactPath(explicitTaskId, "recovery")],
+    )),
+    requiredArtifacts: [stateRel, eventsRel],
+  });
+}
+
 export async function resolveNextActionPhase({
   target,
   packageRoot,
@@ -55,33 +136,10 @@ export async function resolveNextActionPhase({
 } = {}) {
   const { policyRecoveryAction } = helpers;
   if (explicitTaskId) {
-    let inspection;
-    try {
-      inspection = await inspectTaskConflictState(target, {
-        taskId: explicitTaskId,
-        packageRoot,
-      });
-    } catch (error) {
-      inspection = {
-        classification: "INCONSISTENT",
-        reasonCodes: [error.code ?? "E_TASK_RECOVERY_INCONSISTENT"],
-      };
-    }
-    if (!["ACTIVE", "COMPLETE"].includes(inspection.classification)) {
-      const guidance = recoveryGuidanceForClassification(inspection.classification, explicitTaskId);
-      return result({
-        ...context,
-        nextAction: guidance.nextAction,
-        commands: guidance.commands,
-        commandSpecs: guidance.commandSpecs,
-        reasons: inspection.reasonCodes.map((code) => artifactError(
-          code,
-          `Task conflict state is ${inspection.classification}; follow the structured recovery guidance.`,
-          [stateRel, eventsRel, taskArtifactPath(explicitTaskId, "recovery")],
-        )),
-        requiredArtifacts: [stateRel, eventsRel],
-      });
-    }
+    const taskConflictGuidance = await explicitTaskConflictGuidance({
+      target, packageRoot, explicitTaskId, context, eventsRel, stateRel, state,
+    });
+    if (taskConflictGuidance) return taskConflictGuidance;
   }
   const actionGuidance = await resolvePendingActionGuidance({ target, packageRoot, state, context, eventsRel, authorityContext, runtimeContext, helpers });
   if (actionGuidance) return actionGuidance;
@@ -137,11 +195,11 @@ export async function resolveNextActionPhase({
     contractFile: contractRel,
   });
   if (freshness.status === "REVALIDATION_REQUIRED") {
-    const refreshGuidance = await preExecutionRefreshGuidance({ target, packageRoot, state, contract });
+    const refreshGuidance = await preExecutionRefreshGuidance({ target, packageRoot, state, contract, freshness });
     return result({
       ...context,
       ...refreshGuidance,
-      nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+      nextAction: refreshGuidance.nextAction,
       reasons: freshnessReasons(state, freshness),
       requiredArtifacts: uniqueSorted([
         stateRel,
@@ -151,13 +209,15 @@ export async function resolveNextActionPhase({
     });
   }
   if (state.phase === "CONTRACT_READY") {
-    return decision(
-      context,
-      NEXT_ACTIONS.ROUTE,
-      artifactError("PHASE_CONTRACT_READY", "Persist deterministic routing for the validated contract"),
-      contractArtifacts,
-      [routeRel],
-    );
+    return result({
+      ...context,
+      nextAction: NEXT_ACTIONS.ROUTE,
+      reasons: [artifactError("PHASE_CONTRACT_READY", "Persist deterministic routing for the validated contract")],
+      commands: [`forgeloop route --task ${explicitTaskId} --work <type> --json`],
+      commandSpecs: [routeCommandSpec(explicitTaskId)],
+      requiredArtifacts: contractArtifacts,
+      missingArtifacts: [routeRel],
+    });
   }
   const routeResult = await loadArtifact(
     () => readPersistedRoute(target, packageRoot, { taskId: explicitTaskId }),
@@ -187,6 +247,8 @@ export async function resolveNextActionPhase({
       ...context,
       nextAction: NEXT_ACTIONS.RESOLVE_STALE_ROUTE,
       reasons: stale,
+      commands: [`forgeloop route --task ${explicitTaskId} --work <type> --json`],
+      commandSpecs: [routeCommandSpec(explicitTaskId)],
       requiredArtifacts,
     });
   }
@@ -214,6 +276,20 @@ export async function resolveNextActionPhase({
         ],
       });
     }
+    const staleGateErrors = PHASES_ALLOWING_GATE_REVALIDATION.has(state.phase)
+      ? (executionPrerequisites.preflight?.errors ?? []).filter((error) => error.code === "E_GATE_STALE")
+      : [];
+    if (staleGateErrors.length > 0) {
+      const gates = [...new Set(staleGateErrors.map((error) => error.gate).filter(Boolean))].sort();
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.REVALIDATE_GATES,
+        reasons: staleGateErrors,
+        commands: gates.map((gate) => `forgeloop gate-revalidate --task ${explicitTaskId} --gate ${gate} --acknowledge-stale --json`),
+        commandSpecs: gates.map((gate) => gateRevalidationCommandSpec(explicitTaskId, gate)),
+        requiredArtifacts: executionPrerequisites.requiredArtifacts,
+      });
+    }
     if (executionPrerequisites.errors.length > 0) {
       return result({
         ...context,
@@ -238,16 +314,28 @@ export async function resolveNextActionPhase({
     : validatePersistedPreflight(preflightArtifact.value?.value, preflight);
 
   if (["ROUTED", "DESIGNING", "PLANNED"].includes(state.phase) && missingGates.length > 0) {
+    const missingGatePaths = missingGates.map((gate) => taskGatePath(state.taskId, gate));
+    const gateRecordSpec = {
+      commandId: "gate-record",
+      executable: "forgeloop",
+      subcommand: "gate-record",
+      argv: ["gate-record", `--task=${state.taskId}`, `--gate=${missingGates[0]}`, "--status=satisfied", "--json"],
+      requiredInputs: [
+        { name: "artifact", option: "--artifact=<project-relative-path>", repeatable: true },
+        { name: "decision", option: "--decision=<text>", repeatable: true },
+      ],
+    };
     return result({
       ...context,
       nextAction: NEXT_ACTIONS.SATISFY_GATES,
-      reasons: missingGates.map((gate) => artifactError(
+      reasons: missingGates.map((gate, index) => artifactError(
         "E_GATE_UNVERIFIED",
         `Required gate is missing or unverified: ${gate}`,
-        [`${ARTIFACT_PATHS.gates}/${gate}.json`],
+        [missingGatePaths[index]],
       )),
-      requiredArtifacts: [...preflightArtifacts, ...missingGates.map((gate) => `${ARTIFACT_PATHS.gates}/${gate}.json`)],
-      missingArtifacts: missingGates.map((gate) => `${ARTIFACT_PATHS.gates}/${gate}.json`),
+      requiredArtifacts: [...preflightArtifacts, ...missingGatePaths],
+      missingArtifacts: missingGatePaths,
+      commandSpecs: [gateRecordSpec],
     });
   }
   if (state.phase === "ROUTED") {

package/src/core/next-action-refresh.js

@@ -1,19 +1,53 @@
-import { validateEventLedger } from "./events.js";
+import { validateEventLedger, validateStateLedgerCoherence } from "./events.js";
 import { readPersistedRoute } from "./route-artifact.js";
-import { directCommandSpec } from "./next-action-model.js";
+import { directCommandSpec, NEXT_ACTIONS } from "./next-action-model.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
+import { sameCanonicalGuideList } from "./contract-bootstrap-recovery.js";
+import { CHECKPOINT_REVALIDATION_PHASES } from "./checkpoint-revalidation.js";
 
-/** Offer checkpoint removal only before execution, with valid blocked chronology. */
-export async function preExecutionRefreshGuidance({ target, packageRoot, state, contract }) {
-  if (!["ROUTED", "DESIGNING", "PLANNED"].includes(state.phase)) return {};
+/**
+ * Select a safe pre-execution refresh mutation. Repository-only drift keeps
+ * the checkpoint and its route identity; the legacy clear-state path remains
+ * limited to a documented blocked-preflight recovery.
+ */
+export async function preExecutionRefreshGuidance({ target, packageRoot, state, contract, freshness }) {
+  if (!["ROUTED", "DESIGNING", "PLANNED"].includes(state.phase)) return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER };
   const ledger = await validateEventLedger(target, packageRoot, { taskId: state.taskId });
-  if (!ledger.valid || ledger.events.some((entry) => entry.event === "EXECUTION_STARTED")) return {};
+  if (!ledger.valid || ledger.events.some((entry) => entry.event === "EXECUTION_STARTED")) {
+    return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER };
+  }
+  if (CHECKPOINT_REVALIDATION_PHASES.includes(state.phase)
+    && freshness?.status === "REVALIDATION_REQUIRED"
+    && [...new Set(freshness.reasons ?? [])].sort().join(",") === "REPOSITORY_CHANGED"
+    && state.contractFingerprint === contract.fingerprint) {
+    try {
+      const route = await readPersistedRoute(target, packageRoot, { taskId: state.taskId });
+      const ownership = await resolveTaskClaimState(target, { taskId: state.taskId, packageRoot });
+      const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+      const repositoryAvailable = typeof freshness.repository?.head === "string" && freshness.repository.head.length > 0;
+      const routeIdentityValid = route.value?.contractFingerprint === contract.fingerprint
+        && state.routeFingerprint === route.fingerprint
+        && sameCanonicalGuideList(state.selectedGuides, route.value.guides);
+      if (ownership.ownershipValid && ownership.mutationAllowed && repositoryAvailable
+        && coherenceErrors.length === 0 && routeIdentityValid) {
+        return {
+          nextAction: NEXT_ACTIONS.REVALIDATE_CHECKPOINT,
+          commands: [`forgeloop checkpoint-revalidate --task ${state.taskId} --json`],
+          commandSpecs: [directCommandSpec("checkpoint-revalidate", state.taskId)],
+        };
+      }
+    } catch {
+      // Unsupported or ambiguous identity stays on the fail-closed blocker.
+    }
+  }
   const lastPreflight = ledger.events.filter((entry) => ["PREFLIGHT_READY", "PREFLIGHT_BLOCKED"].includes(entry.event)).at(-1);
-  if (lastPreflight?.event !== "PREFLIGHT_BLOCKED") return {};
+  if (lastPreflight?.event !== "PREFLIGHT_BLOCKED") return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER };
   let route;
   try { route = await readPersistedRoute(target, packageRoot, { taskId: state.taskId }); }
-  catch { return {}; }
-  if (route.value.contractFingerprint !== contract.fingerprint) return {};
+  catch { return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER }; }
+  if (route.value.contractFingerprint !== contract.fingerprint) return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER };
   return {
+    nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
     commands: [`forgeloop clear-state --task ${state.taskId}`, `forgeloop preflight --task ${state.taskId}`],
     commandSpecs: [directCommandSpec("clear-state", state.taskId), directCommandSpec("preflight", state.taskId)],
   };

package/src/core/next-action-review-phase.js

@@ -2,7 +2,7 @@ import { readJsonArtifact } from "./artifacts.js";
 import { evaluateCompletion } from "./completion.js";
 import { validateReceipt } from "./receipt.js";
 import { completionRelationshipErrors } from "./completion-relationships.js";
-import { evaluateRequiredEvidence, classifyRequirement } from "./evidence-readiness.js";
+import { evaluateRequiredEvidence, classifyRequirement, terminalRequirementsForContract } from "./evidence-readiness.js";
 import { validateEventLedger, validateCompletionRecoveryAuthorization } from "./events.js";
 import { NEXT_ACTIONS, commandFor, decision, recordTerminalResultCommandSpec, result } from "./next-action-model.js";
 import { artifactError, checkListReasons, loadArtifact, requirementsAndCoverage } from "./next-action-artifacts.js";
@@ -153,9 +153,14 @@ export async function resolveReviewingPhase({ state, context, requiredArtifacts,
         err.code === "E_PUBLICATION_REQUIREMENT_PENDING" || err.code === "E_PRODUCTION_REQUIREMENT_PENDING"
       ));
       if (terminalPendingErrors.length > 0 && terminalPendingErrors.length === completion.errors.length) {
+        const canonicalTerminalRequirements = terminalRequirementsForContract(contract.value, {
+          additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+        });
         const terminalPendingReqs = terminalPendingErrors.map((err) => {
           const reqId = err.requirementId;
-          const matchingReq = evidence.requirements.find((r) => r.id === reqId)
+          const matchingReq = canonicalTerminalRequirements.find((r) => r.id === reqId)
+            ?? canonicalTerminalRequirements.find((r) => r.text === reqId)
+            ?? evidence.requirements.find((r) => r.id === reqId)
             ?? evidence.requirements.find((r) => r.text === reqId)
             ?? classifyRequirement(reqId ?? err.message);
           return matchingReq;

package/src/core/next-action.js

@@ -287,13 +287,41 @@ async function computeNextAction(targetOrOptions = {}, packageRootOption) {
         });
       }
     }
-    return decision(
-      {},
-      NEXT_ACTIONS.DISCOVER,
-      artifactError("WORK_STATE_ABSENT", "No work-state checkpoint is present", [stateRel]),
-      [stateRel],
-      [stateRel],
-    );
+    const events = await readEvents(target, packageRoot, { taskId: explicitTaskId });
+    if (events.some((event) => event.event === "DISCOVERY_STARTED")) {
+      return result({
+        taskId: explicitTaskId ?? "unknown",
+        currentPhase: "DISCOVERING",
+        nextAction: NEXT_ACTIONS.CREATE_CONTRACT,
+        reasons: [artifactError("PHASE_DISCOVERING", "Create and validate the task contract", [contractRel])],
+        commands: [`forgeloop contract-create --task ${explicitTaskId} --preset <documentation|bug|feature|release> --json`],
+        commandSpecs: [{
+          commandId: "contract-create",
+          executable: "forgeloop",
+          subcommand: "contract-create",
+          argv: ["contract-create", `--task=${explicitTaskId}`, "--json"],
+          requiredInputs: [{ name: "preset", option: "--preset=<documentation|bug|feature|release>" }],
+        }],
+        requiredArtifacts: [contractRel],
+        missingArtifacts: [contractRel, stateRel],
+      });
+    }
+    return result({
+      taskId: explicitTaskId ?? "unknown",
+      currentPhase: "RECEIVED",
+      nextAction: NEXT_ACTIONS.DISCOVER,
+      reasons: [artifactError("WORK_STATE_ABSENT", "No work-state checkpoint is present", [stateRel])],
+      commands: [`forgeloop discover --task ${explicitTaskId} --json`],
+      commandSpecs: [{
+        commandId: "discover",
+        executable: "forgeloop",
+        subcommand: "discover",
+        argv: ["discover", `--task=${explicitTaskId}`, "--json"],
+        requiredInputs: [],
+      }],
+      requiredArtifacts: [stateRel],
+      missingArtifacts: [stateRel],
+    });
   }
 
   return resolveNextActionPhase({

package/src/core/phase.js

@@ -5,6 +5,7 @@ import {
   LIFECYCLE_MILESTONES,
   validateEventLedger,
   validateStateLedgerCoherence,
+  isRevisionEpochPlanRepeat,
 } from "./events.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { assertWorkPhase, isValidTransition } from "./protocol.js";
@@ -13,7 +14,7 @@ import { authorizeCompletionRecoveryOrRebind } from "./completion-recovery-rebin
 import { evaluateCompletion, runComplete as persistCompletion } from "./completion.js";
 import { evaluatePreflight } from "./preflight.js";
 import { requiredEvidenceForTarget } from "./completion-artifacts.js";
-import { assertCompletionRelationships, assertStateIdentity } from "./completion-relationships.js";
+import { assertCompletionRelationships, assertStateIdentity, stateIdentityErrors } from "./completion-relationships.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 import { taskArtifactPath } from "./task-paths.js";
@@ -27,6 +28,13 @@ import {
   evaluateStructuredDiagnosticStall,
 } from "./information-gain-projection.js";
 import { assertStructuralQualityExecutionReady } from "./structural-quality/service.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+  ROUTE_CHECKPOINT_BOUND_EVENT,
+  resolveCanonicalPostRepairCheckpointBinding,
+  sameCanonicalGuideList,
+} from "./contract-bootstrap-recovery.js";
 
 function phaseError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -55,15 +63,13 @@ const LATE_PHASES = new Set([
   "COMPLETE",
 ]);
 
-async function assertPersistedStateIdentity(target, state, toPhase, packageRoot, options = {}) {
+async function readPhaseIdentityArtifacts(target, state, toPhase, packageRoot, options, paths) {
   const scopedTaskId = options.taskId ?? null;
   const requireContract = LATE_PHASES.has(state.phase)
     || ["CONTRACT_READY", "ROUTED", "EXECUTING"].includes(toPhase);
-  const requireRoute = LATE_PHASES.has(state.phase)
+  const requireRoute = state.phase === "ROUTED"
+    || LATE_PHASES.has(state.phase)
     || ["ROUTED", "EXECUTING"].includes(toPhase);
-  const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
-  const routeRel = options.routePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "route") : ARTIFACT_PATHS.route);
-
   let contract = null;
   let route = null;
   try {
@@ -75,7 +81,7 @@ async function assertPersistedStateIdentity(target, state, toPhase, packageRoot,
       throw phaseError(
         requireContract ? "E_PHASE_PREREQUISITE_MISSING" : error.code ?? "E_CONTRACT_INVALID",
         `${requireContract ? `Phase ${toPhase} requires current contract` : "Unable to validate current contract"}: ${error.message}`,
-        [contractRel],
+        [paths.contractRel],
       );
     }
   }
@@ -88,11 +94,69 @@ async function assertPersistedStateIdentity(target, state, toPhase, packageRoot,
       throw phaseError(
         requireRoute ? "E_PHASE_PREREQUISITE_MISSING" : error.code ?? "E_ROUTE_INVALID",
         `${requireRoute ? `Phase ${toPhase} requires persisted route` : "Unable to validate persisted route"}: ${error.message}`,
-        [routeRel],
+        [paths.routeRel],
       );
     }
   }
+  return { contract, route };
+}
+
+function assertRepairedCheckpointIdentity({ contract, route, state, events, contractRel, routeRel, stateRel }) {
+  const repairMarker = events.find((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  if (!repairMarker || state.phase === "ROUTED") return false;
+  const checkpoint = resolveCanonicalPostRepairCheckpointBinding(events, repairMarker);
+  if (!checkpoint) {
+    throw phaseError(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "Repaired late-phase state requires a canonical route checkpoint binding",
+      [contractRel, routeRel],
+    );
+  }
+  const identityErrors = [
+    ...stateIdentityErrors({ contract, state }),
+    ...stateIdentityErrors({ contract, route }),
+  ];
+  if (state.routeFingerprint !== checkpoint.routeFingerprint
+    || !sameCanonicalGuideList(state.selectedGuides, checkpoint.selectedGuides)) {
+    identityErrors.push({
+      code: "E_ROUTE_GUIDE_MISMATCH",
+      message: "Work state does not match the immutable route checkpoint identity",
+      artifacts: [routeRel, stateRel],
+    });
+  }
+  if (identityErrors.length > 0) {
+    const first = identityErrors[0];
+    throw phaseError(first.code, first.message, first.artifacts);
+  }
+  return true;
+}
+
+async function assertPersistedStateIdentity(target, state, toPhase, packageRoot, options = {}) {
+  const scopedTaskId = options.taskId ?? null;
+  const events = options.events ?? [];
+  const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
+  const routeRel = options.routePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "route") : ARTIFACT_PATHS.route);
+  const stateRel = options.statePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "state") : ARTIFACT_PATHS.state);
+  const { contract, route } = await readPhaseIdentityArtifacts(
+    target,
+    state,
+    toPhase,
+    packageRoot,
+    options,
+    { contractRel, routeRel },
+  );
   if (!contract && !route) return;
+  if (toPhase !== "ROUTED" && assertRepairedCheckpointIdentity({
+    contract,
+    route,
+    state,
+    events,
+    contractRel,
+    routeRel,
+    stateRel,
+  })) {
+    return;
+  }
   try {
     assertStateIdentity({ contract, route, state });
   } catch (error) {
@@ -116,6 +180,11 @@ function reconcileImplementationStep(state, toPhase) {
   };
 }
 
+function isRevisionPlanRepeat(events, eventType) {
+  return eventType === "PLAN_RECORDED"
+    && isRevisionEpochPlanRepeat(events, events.length, { event: eventType });
+}
+
 async function assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext, options = {}) {
   const scopedTaskId = options.taskId ?? null;
   const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
@@ -160,8 +229,39 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot, aut
   }
 }
 
+async function appendRepairRouteCheckpoint({ target, packageRoot, taskId, state, events, stateRel, eventsRel }) {
+  const repairMarker = events.find((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  const checkpointAlreadyBound = events.some((event) => event.event === ROUTE_CHECKPOINT_BOUND_EVENT);
+  if (!repairMarker || state.phase !== "ROUTED" || checkpointAlreadyBound) return;
+  if (typeof state.routeFingerprint !== "string") {
+    throw phaseError("E_ROUTE_GUIDE_MISMATCH", "ROUTED state requires a route fingerprint before checkpoint binding", [stateRel, eventsRel]);
+  }
+  await appendProtocolEvent(target, {
+    taskId: state.taskId,
+    event: ROUTE_CHECKPOINT_BOUND_EVENT,
+    details: {
+      routeFingerprint: state.routeFingerprint,
+      contractFingerprint: state.contractFingerprint,
+      selectedGuides: [...state.selectedGuides].sort(),
+    },
+  }, packageRoot, { taskId, eventsPath: eventsRel });
+}
+
 export async function advanceWorkState(target, toPhase, options = {}) {
   const normalizedOptions = typeof options === "string" ? { packageRoot: options } : options;
+  if (!normalizedOptions.taskId || await getTaskTransaction(target)) {
+    return advanceWorkStateInternal(target, toPhase, normalizedOptions);
+  }
+  return withTaskTransaction({
+    target,
+    taskId: normalizedOptions.taskId,
+    operation: "advance",
+    packageRoot: normalizedOptions.packageRoot,
+    recordCommitEvent: true,
+  }, async () => advanceWorkStateInternal(target, toPhase, normalizedOptions));
+}
+
+async function advanceWorkStateInternal(target, toPhase, normalizedOptions) {
   const {
     packageRoot,
     now = new Date().toISOString(),
@@ -211,7 +311,6 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   }
 
   await assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext, { taskId, statePath, contractPath, routePath, receiptPath, eventsPath });
-  await assertPersistedStateIdentity(target, state, toPhase, packageRoot, { taskId, contractPath, routePath });
 
   if (toPhase === "EXECUTING" && taskId) {
     // Multi-task checkout scope checks
@@ -259,6 +358,12 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   if (coherenceErrors.length > 0) {
     throw phaseError(coherenceErrors[0].code, coherenceErrors[0].message, [stateRel, eventsRel]);
   }
+  await assertPersistedStateIdentity(target, state, toPhase, packageRoot, {
+    taskId,
+    contractPath,
+    routePath,
+    events: ledger.events,
+  });
   const eventType = PHASE_EVENTS[toPhase];
   const reenteringVerification = toPhase === "VERIFYING" && ["CORRECTING", "REVIEWING"].includes(state.phase);
   if (toPhase === "VERIFYING" && state.phase === "REVIEWING") {
@@ -338,11 +443,15 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   }
   const repeatedReview = state.phase === "VERIFYING" && toPhase === "REVIEWING"
     && ledger.events.some((event) => event.taskId === state.taskId && event.event === "REVIEW_STARTED");
+  const revisionPlanRepeat = isRevisionPlanRepeat(ledger.events, eventType);
   if (eventType && !reenteringVerification && !repeatedReview
+    && !revisionPlanRepeat
     && ledger.events.some((event) => event.taskId === state.taskId && event.event === eventType)) {
     throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `Lifecycle milestone already exists: ${eventType}`, [eventsRel]);
   }
-  const milestoneIndex = reenteringVerification || repeatedReview ? -1 : LIFECYCLE_MILESTONES.indexOf(eventType);
+  const milestoneIndex = reenteringVerification || repeatedReview || revisionPlanRepeat
+    ? -1
+    : LIFECYCLE_MILESTONES.indexOf(eventType);
   if (milestoneIndex >= 0) {
     const lastMilestone = ledger.events.reduce((last, event) => Math.max(last, LIFECYCLE_MILESTONES.indexOf(event.event)), -1);
     if (lastMilestone !== milestoneIndex - 1) {
@@ -361,6 +470,15 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   }
   if (reenteringVerification) delete next.lastCompletionAttempt;
   next.revision = (state.revision ?? 0) + 1;
+  await appendRepairRouteCheckpoint({
+    target,
+    packageRoot,
+    taskId,
+    state,
+    events: ledger.events,
+    stateRel,
+    eventsRel,
+  });
   let nextReceipt = null;
   try {
     const receipt = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);