@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/core/protocol-info.js

@@ -4,6 +4,8 @@ import { PUBLIC_ERROR_REGISTRY } from "./error-codes.js";
 import { GUIDE_REGISTRY } from "./guide-registry.js";
 import { PROTOCOL_VERSION, WORK_PHASES, WORK_TRANSITIONS } from "./protocol.js";
 import { VERIFICATION_ISOLATION_MODES } from "./verification-execution.js";
+import { PROVIDER_KINDS } from "../providers/capabilities.js";
+import { DECISION_DEFAULT_POLICY, DECISION_ENGINE_ID, PINNED_JEV_MODEL } from "./decision/constants.js";
 
 export const SCHEMA_COMPATIBILITY_POLICY = Object.freeze({
   protocolVersion: PROTOCOL_VERSION,
@@ -36,6 +38,42 @@ export function protocolInfo({ packageVersion = null } = {}) {
     writesSchemaVersions: schemaVersions,
     compatibility: SCHEMA_COMPATIBILITY_POLICY,
     features: {
+      semanticDecisionPlane: {
+        version: 1,
+        supported: true,
+        requiredForNewSemanticDecisions: true,
+        engine: DECISION_ENGINE_ID,
+        model: PINNED_JEV_MODEL,
+        policyVersion: DECISION_DEFAULT_POLICY.policyVersion,
+        authority: "SEMANTIC_DECISION",
+        evidenceAuthority: "NONE",
+        lifecycleAuthority: false,
+        completionAuthority: false,
+        ownershipAuthority: false,
+        installationAuthority: false,
+        commands: ["decision-status", "decision-show", "context-plan", "model-route", "semantic-plan", "test-inventory", "test-utility", "test-prune-plan", "test-prune-probe"],
+        resource: "task/decisions",
+        contextPlanResource: "task/context-plan",
+        modelRouteResource: "task/model-route",
+        testUtilityResource: "task/test-utility",
+        testPruneResource: "task/test-utility",
+        offlineInspection: true,
+        completePerformsLiveRequest: false,
+        modelRouting: {
+          version: 1,
+          tiers: ["NONE", "FAST", "STANDARD", "PRIMARY"],
+          deterministicFloor: true,
+          advisoryEscalationOnly: true,
+          vendorSelection: false,
+        },
+        semanticPlanning: {
+          version: 1,
+          questionSets: ["intake-v1", "contract-v1", "route-v1", "context-v1", "model-route-v1", "failure-v1", "diagnosis-v1", "review-v1", "task-overlap-v1", "test-utility-v1", "test-prune-v1"],
+          authority: "SEMANTIC_DECISION",
+          evidenceAuthority: "NONE",
+          lifecycleAuthority: false,
+        },
+      },
       taskClaimRecovery: {
         version: 1,
         durableRecoveryState: true,
@@ -153,6 +191,18 @@ export function protocolInfo({ packageVersion = null } = {}) {
         commands: ["next", "task-show"],
         preservesDefaultOutput: true,
       },
+      auditUx: {
+        version: 1,
+        supported: true,
+        readOnly: true,
+        resource: "task/audit-view",
+        timeline: true,
+        lifecycleAuthority: false,
+        evidenceAuthority: false,
+        completionAuthority: false,
+        mutationAuthority: false,
+        externalExecution: false,
+      },
       usageTelemetry: {
         version: 1,
         supported: true,
@@ -205,6 +255,21 @@ export function protocolInfo({ packageVersion = null } = {}) {
         evidenceAuthority: false,
         executable: false,
       },
+      providerExtensions: {
+        version: 1,
+        supported: true,
+        providerNeutral: true,
+        maturity: "experimental",
+        publicRegistryApi: false,
+        packageSubpathExported: false,
+        autoInstall: false,
+        lifecycleAuthority: false,
+        completionAuthority: false,
+        evidenceAuthority: false,
+        providerKinds: [...PROVIDER_KINDS],
+        resultBoundary: "STRICT_JSON_SNAPSHOT",
+        cancellation: "COOPERATIVE_ABORT_SIGNAL",
+      },
       responsibilityConstraints: {
         version: 1,
         supported: true,

package/src/core/protocol.js

@@ -30,6 +30,9 @@ export const FAILURE_CODES = Object.freeze([
   "E_GATE_REQUIRED",
   "E_GATE_UNVERIFIED",
   "E_GATE_STALE",
+  "E_GATE_NOT_REQUIRED",
+  "E_GATE_INVALID",
+  "E_PHASE_FREEZE",
   "E_PHASE_TRANSITION_INVALID",
   "E_PHASE_PREREQUISITE_MISSING",
   "E_PHASE_CHRONOLOGY_INVALID",
@@ -113,6 +116,23 @@ export const FAILURE_CODES = Object.freeze([
   "E_INTERVENTION_HYPOTHESIS_MISSING",
   "E_INTERVENTION_REFERENCE_INVALID",
   "E_STRATEGY_OSCILLATION",
+  "E_DECISION_ENGINE_UNAVAILABLE",
+  "E_DECISION_ENGINE_AUTH_REQUIRED",
+  "E_DECISION_ENGINE_AUTH_INVALID",
+  "E_DECISION_MODEL_UNSUPPORTED",
+  "E_DECISION_REQUEST_INVALID",
+  "E_DECISION_RESULT_INVALID",
+  "E_DECISION_TIMEOUT",
+  "E_DECISION_RATE_LIMITED",
+  "E_DECISION_STATE_UNSAFE",
+  "E_DECISION_STATE_LIMIT",
+  "E_DECISION_LOW_CONFIDENCE",
+  "E_DECISION_STALE",
+  "E_DECISION_POLICY_INVALID",
+  "E_DECISION_CACHE_INVALID",
+  "E_DECISION_QUESTION_SET_UNKNOWN",
+  "E_DECISION_QUESTION_SET_STALE",
+  "E_DECISION_REQUIRED",
   "E_DECISION_CRITERION_INVALID",
   "E_DECISION_NOT_UNRESOLVED",
 ]);

package/src/core/reconcile-closure.js

@@ -1,17 +1,17 @@
 import { readContract } from "./contract.js";
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
-import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { appendProtocolEvent, validateCompletionRecoveryAuthorization, validateEventLedger } from "./events.js";
 import { authorizeCompletionRecoveryOrRebind } from "./completion-recovery-rebind.js";
 import { runCommandExecution } from "./execution.js";
 import { createReceipt } from "./receipt.js";
 import { currentRepositoryFingerprint } from "./repository.js";
 import { taskArtifactPath } from "./task-paths.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
 import { classifyLoadedWorkState, readWorkState, mutateWorkState } from "./work-state.js";
+import { classifyRequirement } from "./evidence-readiness.js";
 
 export const RECONCILE_EVENT = "CHECKPOINT_RECONCILED";
 
-const RECONCILABLE_DRIFT = new Set(["REPOSITORY_CHANGED"]);
-
 const RECONCILABLE_PHASES = new Set(["EXECUTING", "VERIFYING", "REVIEWING"]);
 
 function reconcileError(code, message, artifacts = []) {
@@ -21,14 +21,126 @@ function reconcileError(code, message, artifacts = []) {
   return error;
 }
 
+function assertRepositoryOnlyFreshness(freshness, stateRel, contractRel) {
+  if (freshness.status !== "REVALIDATION_REQUIRED") {
+    throw reconcileError(
+      "E_RECONCILE_NOT_STALE",
+      `work-state checkpoint is ${freshness.status === "FRESH" ? "fresh" : "not revalidation-required"}; no reconciliation required`,
+      [stateRel, contractRel],
+    );
+  }
+  if (freshness.reasons.length === 1 && freshness.reasons[0] === "REPOSITORY_CHANGED") return;
+  throw reconcileError(
+    "E_RECONCILE_UNSUPPORTED_DRIFT",
+    `reconcile-closure only reconciles repository fingerprint drift; unresolved drift: ${freshness.reasons.join(", ")}`,
+    [stateRel, contractRel],
+  );
+}
+
+async function assertFreshReviewingRecoveryIsAuthorized({
+  target,
+  packageRoot,
+  taskId,
+  state,
+  eventsRel,
+  receiptRel,
+}) {
+  if (state.phase !== "REVIEWING" || !Object.prototype.hasOwnProperty.call(state, "lastCompletionAttempt")) return;
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) return;
+  let receipt = null;
+  try {
+    receipt = (await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot)).value;
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+  const recoveryAuth = validateCompletionRecoveryAuthorization({ state, receipt, events: ledger.events });
+  if (!recoveryAuth.authorized) {
+    const first = recoveryAuth.errors?.[0] ?? {};
+    throw reconcileError(
+      first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
+      `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
+      [eventsRel, receiptRel],
+    );
+  }
+}
+
+async function validateReconciliationCheckpoint({
+  target,
+  packageRoot,
+  taskId,
+  state,
+  stateRel,
+  contractRel,
+  eventsRel,
+  receiptRel,
+  authorityContext,
+  runtimeContext,
+}) {
+  const freshness = await classifyLoadedWorkState({ target, state, contractFile: contractRel });
+  if (freshness.status !== "REVALIDATION_REQUIRED") {
+    await assertFreshReviewingRecoveryIsAuthorized({
+      target,
+      packageRoot,
+      taskId,
+      state,
+      eventsRel,
+      receiptRel,
+    });
+  }
+  assertRepositoryOnlyFreshness(freshness, stateRel, contractRel);
+
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    throw reconcileError(
+      "E_RECONCILE_LEDGER_INVALID",
+      `append-only event ledger must be valid before reconciliation: ${first?.message ?? "invalid ledger"}`,
+      [eventsRel],
+    );
+  }
+
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid || !ownership.mutationAllowed || ownership.claimState !== "ACTIVE") {
+    const first = ownership.ownershipErrors?.[0] ?? ownership.errors?.[0] ?? {};
+    throw reconcileError(
+      first.code ?? "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT",
+      `reconcile-closure requires active, valid task claim ownership: ${first.message ?? ownership.claimState}`,
+      [stateRel, eventsRel],
+    );
+  }
+
+  if (state.phase !== "REVIEWING" || !Object.prototype.hasOwnProperty.call(state, "lastCompletionAttempt")) {
+    return state;
+  }
+
+  const recovery = await authorizeCompletionRecoveryOrRebind({
+    target,
+    packageRoot,
+    taskId,
+    authorityContext,
+    runtimeContext,
+  });
+  if (!recovery.recoveryAuth.authorized) {
+    const first = recovery.recoveryAuth.errors?.[0] ?? {};
+    throw reconcileError(
+      first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
+      `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
+      [stateRel, receiptRel],
+    );
+  }
+  return recovery.rebound ? recovery.state : state;
+}
+
 /**
  * Canonical recovery for an EXECUTING, VERIFYING, or REVIEWING task whose
  * objective is already satisfied in the current repository but whose
  * work-state checkpoint is stale because the repository fingerprint moved.
  *
  * The command refreshes the checkpoint repository fingerprint only after:
- *   - the task is EXECUTING, VERIFYING, or (with authorized completion
- *     recovery) REVIEWING,
+ *   - the task is EXECUTING, VERIFYING, or REVIEWING (with either a
+ *     persisted completion rejection or the narrow repository-only bootstrap
+ *     path),
  *   - classification requires revalidation and the only drift is
  *     REPOSITORY_CHANGED,
  *   - the append-only event ledger is valid,
@@ -80,60 +192,27 @@ export async function runReconcileClosure({
       [stateRel],
     );
   }
-  if (state.phase === "REVIEWING") {
-    const recovery = await authorizeCompletionRecoveryOrRebind({
-      target,
-      packageRoot,
-      taskId,
-      authorityContext,
-      runtimeContext,
-    });
-    if (!recovery.recoveryAuth.authorized) {
-      const first = recovery.recoveryAuth.errors?.[0] ?? {};
-      throw reconcileError(
-        first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
-        `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
-        [stateRel, receiptRel],
-      );
-    }
-    if (recovery.rebound) {
-      state = recovery.state;
-    }
-  }
-
-  const freshness = await classifyLoadedWorkState({ target, state, contractFile: contractRel });
-  if (freshness.status !== "REVALIDATION_REQUIRED" || !freshness.reasons.includes("REPOSITORY_CHANGED")) {
-    throw reconcileError(
-      "E_RECONCILE_NOT_STALE",
-      `work-state checkpoint is ${freshness.status === "FRESH" ? "fresh" : "not revalidation-required"}; no reconciliation required`,
-      [stateRel, contractRel],
-    );
-  }
-  const unsupported = freshness.reasons.filter((reason) => !RECONCILABLE_DRIFT.has(reason));
-  if (unsupported.length > 0) {
-    throw reconcileError(
-      "E_RECONCILE_UNSUPPORTED_DRIFT",
-      `reconcile-closure only reconciles repository fingerprint drift; unresolved drift: ${unsupported.join(", ")}`,
-      [stateRel, contractRel],
-    );
-  }
-
-  const ledger = await validateEventLedger(target, packageRoot, { taskId });
-  if (!ledger.valid) {
-    const first = ledger.errors[0];
-    throw reconcileError(
-      "E_RECONCILE_LEDGER_INVALID",
-      `append-only event ledger must be valid before reconciliation: ${first?.message ?? "invalid ledger"}`,
-      [eventsRel],
-    );
-  }
+  state = await validateReconciliationCheckpoint({
+    target,
+    packageRoot,
+    taskId,
+    state,
+    stateRel,
+    contractRel,
+    eventsRel,
+    receiptRel,
+    authorityContext,
+    runtimeContext,
+  });
 
   const contract = await readContract(target, packageRoot, { taskId });
   const verificationItem = (contract.value.verification ?? []).find((item) => {
     if (typeof item === "string") {
       return item === requirement;
     }
-    return item.type === "VERIFICATION" && item.id === checkId && item.text === requirement;
+    return classifyRequirement(item).type === "VERIFICATION"
+      && item.id === checkId
+      && item.text === requirement;
   });
   if (!verificationItem) {
     throw reconcileError(

package/src/core/recovery-history.js

@@ -6,6 +6,7 @@ import {
 const RECOVERY_EVENT_TYPES = new Set([
   "TASK_RECOVERY_RECORDED",
   "OPERATOR_RECOVERY_RECORDED",
+  "TASK_ABANDONED",
   LEGACY_RECOVERY_MIGRATION_EVENT,
 ]);
 

package/src/core/resumability.js

@@ -4,6 +4,12 @@ import { createWorkState, initializeWorkState, readWorkState, mutateWorkState }
 
 const DEFAULT_PENDING_STEPS = ["planning", "implementation", "verification"];
 
+const CURRENT_ROUTE_CHECKPOINT_PHASES = new Set(["ROUTED"]);
+
+export function routeCheckpointMustMatchCurrentRoute(phase) {
+  return CURRENT_ROUTE_CHECKPOINT_PHASES.has(phase);
+}
+
 /**
  * Resume phase derived from the highest lifecycle milestone already recorded in
  * a validated ledger. Recreating a checkpoint at ROUTED for a task whose ledger
@@ -16,9 +22,88 @@ const RESUME_PHASE_BY_MILESTONE = Object.freeze({
   EXECUTION_STARTED: "EXECUTING",
   VERIFICATION_STARTED: "VERIFYING",
   VERIFICATION_RECORDED: "VERIFYING",
+  REVIEW_STARTED: "REVIEWING",
+});
+
+const RESUME_STEPS_BY_PHASE = Object.freeze({
+  CONTRACT_READY: {
+    completedSteps: ["contract"],
+    pendingSteps: ["route", ...DEFAULT_PENDING_STEPS],
+  },
+  ROUTED: {
+    completedSteps: ["contract", "route"],
+    pendingSteps: [...DEFAULT_PENDING_STEPS],
+  },
+  PLANNED: {
+    completedSteps: ["contract", "route", "planning"],
+    pendingSteps: [...DEFAULT_PENDING_STEPS.filter((step) => step !== "planning")],
+  },
+  EXECUTING: {
+    completedSteps: ["contract", "route", "planning", "implementation"],
+    pendingSteps: ["verification"],
+  },
+  VERIFYING: {
+    completedSteps: ["contract", "route", "planning", "implementation"],
+    pendingSteps: ["verification"],
+  },
+  REVIEWING: {
+    completedSteps: ["contract", "route", "planning", "implementation", "verification"],
+    pendingSteps: [],
+  },
 });
 
-async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
+function cycleEvents(events) {
+  const CYCLE_EVENT_NAMES = new Set([
+    "VERIFICATION_STARTED",
+    "VERIFICATION_RECORDED",
+    "DIAGNOSIS_RECORDED",
+    "DIAGNOSTIC_CASE_RECORDED",
+  ]);
+  const cycles = events
+    .filter((event) => CYCLE_EVENT_NAMES.has(event.event))
+    .map((event) => event.details?.verificationCycle)
+    .filter((cycle) => Number.isInteger(cycle) && cycle >= 1);
+  return cycles.at(-1);
+}
+
+/**
+ * Canonical reconstruction projection: for a resumed phase derived from a
+ * validated ledger, returns the single source of truth for completedSteps and
+ * pendingSteps. Unknown phases fall back to the ROUTED projection, matching the
+ * historical default resume checkpoint.
+ */
+export function resumeStepsForPhase(phase) {
+  return RESUME_STEPS_BY_PHASE[phase] ?? RESUME_STEPS_BY_PHASE.ROUTED;
+}
+
+/**
+ * Canonical verification cycle derived from the ledger when history proves
+ * verification has started; undefined when the ledger has no cycle metadata.
+ */
+export function resumeVerificationCycleForPhase(events) {
+  return cycleEvents(events);
+}
+
+/**
+ * Canonical work-state identity fields for reconstruction from a validated
+ * ledger: resumed phase, completedSteps, pendingSteps, and verificationCycle.
+ * This is the one projection shared by ensureResumableState and
+ * contract-create reconstruction so later phases cannot be reconstructed with
+ * contradictory steps.
+ */
+export function buildResumableWorkStateFields({ events, resumedPhase }) {
+  const steps = resumeStepsForPhase(resumedPhase);
+  return {
+    phase: resumedPhase,
+    completedSteps: [...steps.completedSteps],
+    pendingSteps: [...steps.pendingSteps],
+    ...(events && events.length > 0 && cycleEvents(events) !== undefined
+      ? { verificationCycle: cycleEvents(events) }
+      : {}),
+  };
+}
+
+export async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
   let ledger;
   try {
     ledger = await validateEventLedger(target, packageRoot, { taskId });
@@ -32,71 +117,37 @@ async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
   let derived = null;
   for (const event of scoped) {
     const phase = positions[event.event];
-    if (!phase) continue;
-    if (!derived) {
-      derived = phase;
-      continue;
-    }
-    if (phase === "VERIFYING") derived = "VERIFYING";
+    if (phase) derived = phase;
   }
   return derived;
 }
 
-function deriveVerificationCycleFromLedger(events) {
-  const cycleEvents = new Set([
-    "VERIFICATION_STARTED",
-    "VERIFICATION_RECORDED",
-    "DIAGNOSIS_RECORDED",
-    "DIAGNOSTIC_CASE_RECORDED",
-  ]);
-  const cycles = events
-    .filter((event) => cycleEvents.has(event.event))
-    .map((event) => event.details?.verificationCycle)
-    .filter((cycle) => Number.isInteger(cycle) && cycle >= 1);
-  return cycles.at(-1);
-}
-
-function resumeSteps(phase) {
-  if (phase === "EXECUTING" || phase === "VERIFYING") {
-    return {
-      completedSteps: ["contract", "route", "planning", "implementation"],
-      pendingSteps: ["verification"],
-    };
-  }
-  return {
-    completedSteps: ["contract", "route"],
-    pendingSteps: [...DEFAULT_PENDING_STEPS],
-  };
-}
-
 export async function ensureResumableState({ target, packageRoot, contract, route, taskId, statePath }) {
   if (!contract || !route) return null;
   const existing = await readWorkState(target, { packageRoot, taskId, statePath });
   if (existing) return existing;
 
   const resumedPhase = await deriveResumePhaseFromLedger(target, packageRoot, taskId) ?? "ROUTED";
-  let verificationCycle;
+  let events = [];
   try {
     const ledger = await validateEventLedger(target, packageRoot, { taskId });
     if (ledger.valid) {
-      verificationCycle = deriveVerificationCycleFromLedger(
-        (ledger.events ?? []).filter((event) => !taskId || event.taskId === taskId),
-      );
+      events = (ledger.events ?? []).filter((event) => !taskId || event.taskId === taskId);
     }
   } catch {
-    verificationCycle = undefined;
+    events = [];
   }
-  const steps = resumeSteps(resumedPhase);
+  const projection = buildResumableWorkStateFields({ events, resumedPhase });
   const state = createWorkState({
     taskId: contract.value.taskId,
     contractFingerprint: contract.fingerprint,
     routeFingerprint: route.fingerprint,
     repositoryFingerprint: await currentRepositoryFingerprint(target),
-    phase: resumedPhase,
+    phase: projection.phase,
     selectedGuides: route.value.guides,
-    completedSteps: steps.completedSteps,
-    pendingSteps: steps.pendingSteps,
-    ...(verificationCycle !== undefined ? { verificationCycle } : {}),
+    completedSteps: projection.completedSteps,
+    pendingSteps: projection.pendingSteps,
+    ...(projection.verificationCycle !== undefined ? { verificationCycle: projection.verificationCycle } : {}),
     checks: [],
     failures: [],
     blockers: [],
@@ -105,6 +156,65 @@ export async function ensureResumableState({ target, packageRoot, contract, rout
   return initializeWorkState(target, state, { packageRoot, taskId, statePath });
 }
 
+function routeSyncError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function sameStringList(left, right) {
+  const a = [...(left ?? [])].sort();
+  const b = [...(right ?? [])].sort();
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+/**
+ * Rebinds an existing ROUTED checkpoint to an already-persisted route.
+ *
+ * Only the route-bound identity fields are updated; contract, repository,
+ * steps, checks, evidence, and phase are preserved. Same-identity reruns are
+ * a no-op. Every other situation fails closed.
+ */
+export async function synchronizePersistedRouteState({ target, packageRoot, taskId, route, contract = null, statePath } = {}) {
+  if (!route || !route.value || typeof route.fingerprint !== "string") {
+    throw routeSyncError("E_ROUTE_STALE", "A persisted route artifact is required to synchronize checkpoint identity");
+  }
+  const state = await readWorkState(target, { packageRoot, taskId, statePath });
+  if (!state) return null;
+  if (state.phase !== "ROUTED") {
+    throw routeSyncError(
+      "E_ROUTE_PHASE_UNSUPPORTED",
+      `Route checkpoint synchronization supports phase ROUTED, found ${state.phase}`,
+    );
+  }
+  if (taskId && state.taskId !== taskId) {
+    throw routeSyncError("E_ROUTE_STALE", "Work state does not belong to the current route task");
+  }
+  if (contract && state.contractFingerprint !== contract.fingerprint) {
+    // Contract evolution with regenerated routing is a pre-existing flow whose
+    // stale checkpoint is recovered through the sanctioned clear-state and
+    // preflight recreation path. Never rebind route identity across a contract
+    // boundary here; leave the checkpoint untouched.
+    return state;
+  }
+  if (route.value.contractFingerprint !== undefined && state.contractFingerprint !== route.value.contractFingerprint) {
+    return state;
+  }
+  if (state.routeFingerprint === route.fingerprint && sameStringList(state.selectedGuides, route.value.guides)) {
+    return state;
+  }
+  return mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath,
+  }, () => ({
+    ...state,
+    routeFingerprint: route.fingerprint,
+    selectedGuides: [...route.value.guides],
+  }));
+}
+
 export async function synchronizePreflightState({
   target,
   packageRoot,

package/src/core/route-artifact.js

@@ -1,9 +1,12 @@
 import { assertRouteInvariants } from "./router.js";
 import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { readContract } from "./contract.js";
-import { ensureResumableState } from "./resumability.js";
+import { ensureResumableState, synchronizePersistedRouteState } from "./resumability.js";
+import { readWorkState } from "./work-state.js";
 import { taskArtifactPath } from "./task-paths.js";
 
+
+
 export async function persistRoute(target, route, packageRoot, options = {}) {
   assertRouteInvariants(route);
   const { contractFingerprint, ...writeOptions } = options;
@@ -21,6 +24,14 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
     : { ...route, contractFingerprint };
   assertRouteInvariants(value);
   const taskId = options.taskId ?? contractArtifact?.value?.taskId ?? null;
+  let existingState = null;
+  if (taskId) {
+    try {
+      existingState = await readWorkState(target, { packageRoot, taskId });
+    } catch {
+      existingState = null;
+    }
+  }
   const relPath = options.routePath ?? options.routeFile ?? options.relativePath ?? (taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route);
   const artifact = await writeJsonArtifact(
     target,
@@ -33,6 +44,9 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
   if (contractArtifact && contractArtifact.fingerprint === artifact.value.contractFingerprint) {
     await ensureResumableState({ target, packageRoot, contract: contractArtifact, route: artifact, taskId });
   }
+  if (existingState?.phase === "ROUTED") {
+    await synchronizePersistedRouteState({ target, packageRoot, taskId, route: artifact, contract: contractArtifact });
+  }
   return artifact;
 }