@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/protocol.js

@@ -99,6 +99,20 @@ export const FAILURE_CODES = Object.freeze([
   "E_DIAGNOSIS_CYCLE_MISMATCH",
   "E_DIAGNOSIS_NO_NEW_INFORMATION",
   "E_PROGRESS_STALLED",
+  "E_DIAGNOSTIC_CASE_INVALID",
+  "E_DIAGNOSTIC_CASE_CYCLE_MISMATCH",
+  "E_DIAGNOSTIC_CASE_EVIDENCE_INVALID",
+  "E_OBSERVATION_INVALID",
+  "E_CONTRIBUTOR_INVALID",
+  "E_CONTRIBUTOR_REFERENCE_INVALID",
+  "E_HYPOTHESIS_INVALID",
+  "E_HYPOTHESIS_SETTLEMENT_MISSING",
+  "E_HYPOTHESIS_DISPOSITION_INVALID",
+  "E_HYPOTHESIS_DISPOSITION_EVIDENCE_INVALID",
+  "E_INTERVENTION_INVALID",
+  "E_INTERVENTION_HYPOTHESIS_MISSING",
+  "E_INTERVENTION_REFERENCE_INVALID",
+  "E_STRATEGY_OSCILLATION",
   "E_DECISION_CRITERION_INVALID",
   "E_DECISION_NOT_UNRESOLVED",
 ]);

package/src/core/receipt.js

@@ -158,6 +158,7 @@ export async function createReceipt(input, packageRoot, options = {}) {
     selectedGuides: [...(input.selectedGuides ?? [])],
     changedPaths: [...(input.changedPaths ?? [])],
     checks: [...(input.checks ?? [])],
+    ...(input.actions !== undefined ? { actions: structuredClone(input.actions) } : {}),
     evidence: [...(input.evidence ?? [])],
     ...(input.evidenceCoverage !== undefined ? { evidenceCoverage: [...input.evidenceCoverage] } : {}),
     review: input.review ?? { status: "not-run", independent: false },

package/src/core/reconcile-closure.js

@@ -1,6 +1,7 @@
 import { readContract } from "./contract.js";
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { appendProtocolEvent, 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";
@@ -11,7 +12,7 @@ export const RECONCILE_EVENT = "CHECKPOINT_RECONCILED";
 
 const RECONCILABLE_DRIFT = new Set(["REPOSITORY_CHANGED"]);
 
-const RECONCILABLE_PHASES = new Set(["EXECUTING", "VERIFYING"]);
+const RECONCILABLE_PHASES = new Set(["EXECUTING", "VERIFYING", "REVIEWING"]);
 
 function reconcileError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -21,12 +22,13 @@ function reconcileError(code, message, artifacts = []) {
 }
 
 /**
- * Canonical recovery for an EXECUTING or VERIFYING task whose objective is
- * already satisfied in the current repository but whose work-state
- * checkpoint is stale because the repository fingerprint moved.
+ * 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 or VERIFYING,
+ *   - the task is EXECUTING, VERIFYING, or (with authorized completion
+ *     recovery) REVIEWING,
  *   - classification requires revalidation and the only drift is
  *     REPOSITORY_CHANGED,
  *   - the append-only event ledger is valid,
@@ -67,17 +69,37 @@ export async function runReconcileClosure({
   const eventsRel = taskArtifactPath(taskId, "events");
   const receiptRel = taskArtifactPath(taskId, "receipt");
 
-  const state = await readWorkState(target, { packageRoot, taskId });
+  let state = await readWorkState(target, { packageRoot, taskId });
   if (!state) {
     throw reconcileError("E_RECONCILE_PHASE_INVALID", "Cannot reconcile without work state", [stateRel]);
   }
   if (!RECONCILABLE_PHASES.has(state.phase)) {
     throw reconcileError(
       "E_RECONCILE_PHASE_INVALID",
-      `reconcile-closure supports EXECUTING or VERIFYING tasks whose objective is already satisfied; found ${state.phase}`,
+      `reconcile-closure supports EXECUTING, VERIFYING, or REVIEWING tasks whose objective is already satisfied; found ${state.phase}`,
       [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")) {
@@ -107,9 +129,12 @@ export async function runReconcileClosure({
   }
 
   const contract = await readContract(target, packageRoot, { taskId });
-  const verificationItem = (contract.value.verification ?? []).find(
-    (item) => item.type === "VERIFICATION" && item.id === checkId && item.text === requirement,
-  );
+  const verificationItem = (contract.value.verification ?? []).find((item) => {
+    if (typeof item === "string") {
+      return item === requirement;
+    }
+    return item.type === "VERIFICATION" && item.id === checkId && item.text === requirement;
+  });
   if (!verificationItem) {
     throw reconcileError(
       "E_RECONCILE_REQUIREMENT_UNKNOWN",

package/src/core/recovery-history.js

@@ -0,0 +1,116 @@
+import {
+  LEGACY_RECOVERY_MIGRATION_EVENT,
+  isLegacyRecoveryEventShape,
+} from "./task-recovery-migration.js";
+
+const RECOVERY_EVENT_TYPES = new Set([
+  "TASK_RECOVERY_RECORDED",
+  "OPERATOR_RECOVERY_RECORDED",
+  LEGACY_RECOVERY_MIGRATION_EVENT,
+]);
+
+function recoveryError(message) {
+  return {
+    code: "E_TASK_RECOVERY_INCONSISTENT",
+    message,
+  };
+}
+
+function recoveryIdOf(event) {
+  return typeof event?.details?.recoveryId === "string" && event.details.recoveryId !== ""
+    ? event.details.recoveryId
+    : null;
+}
+
+export function classifyRecoveryHistory(events = []) {
+  const recoveries = [];
+  const completedRecoveries = [];
+  const errors = [];
+  const seenRecoveryIds = new Set();
+  let activeCycle = null;
+
+  for (const event of events) {
+    if (RECOVERY_EVENT_TYPES.has(event?.event)) {
+      // The known legacy defect signature is never an owning recovery cycle by
+      // itself. It remains non-owning historical evidence; ownership comes
+      // exclusively from its valid LEGACY_RECOVERY_MIGRATION_RECORDED event,
+      // which is validated (binding, uniqueness) by the ledger validator.
+      if (!event.details?.recoveryId && isLegacyRecoveryEventShape(event)) continue;
+      // A migration event only counts as a canonical recovery cycle when it
+      // binds an actual legacy event present earlier in this ledger.
+      if (event.event === LEGACY_RECOVERY_MIGRATION_EVENT
+        && !events.some((candidate) => candidate.seq === event.details?.legacyEventSeq
+          && isLegacyRecoveryEventShape(candidate))) {
+        errors.push(recoveryError(
+          `Legacy migration event at seq ${event?.seq ?? "unknown"} does not bind a legacy recovery event in this ledger`,
+        ));
+        continue;
+      }
+      const recoveryId = recoveryIdOf(event);
+      if (!recoveryId) {
+        errors.push(recoveryError(`Recovery event at seq ${event?.seq ?? "unknown"} has no recoveryId`));
+        continue;
+      }
+      if (seenRecoveryIds.has(recoveryId)) {
+        errors.push(recoveryError(`Recovery event at seq ${event.seq} reuses recovery id ${recoveryId}`));
+        continue;
+      }
+      if (activeCycle) {
+        errors.push(recoveryError(
+          `Recovery ${recoveryId} was recorded while recovery ${activeCycle.recoveryId} is unresolved`,
+        ));
+        continue;
+      }
+
+      activeCycle = {
+        recoveryId,
+        recoveryEventSeq: event.seq,
+        resumedEventSeq: null,
+        active: true,
+        event,
+        resumedEvent: null,
+      };
+      seenRecoveryIds.add(recoveryId);
+      recoveries.push(activeCycle);
+      continue;
+    }
+
+    if (event?.event !== "TASK_RECOVERY_RESUMED") continue;
+
+    const recoveryId = recoveryIdOf(event);
+    if (!recoveryId || !activeCycle || activeCycle.recoveryId !== recoveryId) {
+      errors.push(recoveryError(
+        `TASK_RECOVERY_RESUMED at seq ${event?.seq ?? "unknown"} does not reference an active recovery`,
+      ));
+      continue;
+    }
+    if (!Number.isInteger(event.seq) || event.seq <= activeCycle.recoveryEventSeq) {
+      errors.push(recoveryError(
+        `Resume sequence for recovery ${recoveryId} must be greater than recovery sequence ${activeCycle.recoveryEventSeq}`,
+      ));
+      continue;
+    }
+
+    activeCycle.resumedEventSeq = event.seq;
+    activeCycle.resumedEvent = event;
+    activeCycle.active = false;
+    completedRecoveries.push(activeCycle);
+    activeCycle = null;
+  }
+
+  const valid = errors.length === 0;
+  return {
+    recoveries,
+    activeRecoveryId: valid ? activeCycle?.recoveryId ?? null : null,
+    activeRecovery: valid && activeCycle
+      ? { recoveryId: activeCycle.recoveryId, event: activeCycle.event }
+      : null,
+    completedRecoveries,
+    valid,
+    errors,
+  };
+}
+
+export function resolveRecoveryHistory(events = []) {
+  return classifyRecoveryHistory(events);
+}

package/src/core/reflection.js

@@ -0,0 +1,305 @@
+import { buildTaskTrace } from "./trace.js";
+import { readEvents } from "./events.js";
+import { findTaskById } from "./task-discovery.js";
+import { projectHypothesisStates } from "./hypothesis-projection.js";
+import {
+  buildInformationGainProjection,
+  evaluateStructuredDiagnosticStall,
+} from "./information-gain-projection.js";
+import { computeFailureSignature } from "./failure-signature.js";
+import {
+  computeStrategyFingerprints as computeStrategyFingerprintsImpl,
+  detectOscillation as detectOscillationImpl,
+  evaluateInterventionEffectiveness as evaluateInterventionEffectivenessImpl,
+} from "./strategy-analysis.js";
+
+export const REFLECTION_STATUS = Object.freeze({
+  ADVANCING: "ADVANCING",
+  WATCH: "WATCH",
+  STALLED: "STALLED",
+});
+
+
+export function summarizeHypotheses(trace) {
+  const summary = { created: 0, supported: 0, weakened: 0, falsified: 0, superseded: 0, unresolved: 0, open: 0 };
+
+  const pseudoEvents = [
+    ...trace.diagnostics.cases.map((diagnosticCase) => ({
+      seq: diagnosticCase.sequence,
+      event: "DIAGNOSTIC_CASE_RECORDED",
+      details: diagnosticCase,
+    })),
+    ...trace.diagnostics.legacyDiagnoses.map((legacy) => ({
+      seq: legacy.sequence,
+      event: "DIAGNOSIS_RECORDED",
+      details: legacy,
+    })),
+    ...trace.diagnostics.dispositions.map((disposition) => ({
+      seq: disposition.sequence,
+      event: "HYPOTHESIS_DISPOSITION_RECORDED",
+      details: disposition,
+    })),
+  ];
+  const projection = projectHypothesisStates(pseudoEvents);
+
+  for (const hypothesis of projection.hypotheses) {
+    if (hypothesis.id === "h-legacy" && hypothesis.sourceEventSeq !== null) {
+      summary.created += 1;
+    } else if (hypothesis.id !== "h-legacy") {
+      summary.created += 1;
+    }
+    const status = hypothesis.currentStatus.toLowerCase();
+    if (summary[status] !== undefined) summary[status] += 1;
+  }
+  summary.open = projection.openHypotheses.length;
+  return summary;
+}
+
+export function detectOscillation(strategies) {
+  return detectOscillationImpl(strategies);
+}
+
+export function evaluateInterventionEffectiveness(trace, surfacesByCycle) {
+  return evaluateInterventionEffectivenessImpl(trace, surfacesByCycle);
+}
+
+function failedRequirementSurfacesFromEvents(events = [], state = null) {
+  const byCycle = new Map();
+  const record = (cycle, requirement) => {
+    if (!requirement) return;
+    if (!byCycle.has(cycle)) byCycle.set(cycle, new Set());
+    byCycle.get(cycle).add(requirement);
+  };
+  for (const event of events) {
+    if (event.event !== "VERIFICATION_RECORDED") continue;
+    const d = event.details ?? {};
+    if (d.status === "failed" || d.status === "blocked") {
+      record(d.verificationCycle ?? 1, d.requirement ?? d.id ?? d.checkId);
+    }
+  }
+  for (const check of state?.checks ?? []) {
+    if (check.status !== "failed" && check.status !== "blocked") continue;
+    record(check.details?.verificationCycle ?? state?.verificationCycle ?? 1, check.requirement ?? check.id ?? check.checkId);
+  }
+  return byCycle;
+}
+
+function signatureSetsByCycle(trace) {
+  const byCycle = new Map();
+  for (const entry of trace.failureSignatures) {
+    for (const cycle of entry.cycles ?? []) {
+      if (!byCycle.has(cycle)) byCycle.set(cycle, new Set());
+      byCycle.get(cycle).add(entry.signature);
+    }
+  }
+  return byCycle;
+}
+
+export function deriveDiagnosticContext(events = [], state = null) {
+  const cycle = state?.verificationCycle ?? null;
+  const taskEvents = events.filter((event) => !state?.taskId || event.taskId === state.taskId);
+
+  // Canonical failure-signature hashes for the active verification cycle.
+  const activeFailureSignatures = [...new Set(
+    taskEvents
+      .filter((event) => event.event === "VERIFICATION_RECORDED"
+        && ["failed", "blocked"].includes(event.details?.status)
+        && (cycle === null || event.details?.verificationCycle === cycle))
+      .map((event) => {
+        const d = event.details;
+        return computeFailureSignature({
+          requirement: d.requirement ?? d.id ?? d.checkId,
+          status: d.status,
+          exitCode: Number.isInteger(d.exitCode) ? d.exitCode : null,
+          failureToken: typeof d.failureToken === "string" && d.failureToken
+            ? d.failureToken
+            : (typeof d.details?.failureToken === "string" ? d.details.failureToken : null),
+        });
+      }),
+  )].sort();
+
+  const activeFailedRequirements = [...new Set(
+    [
+      ...taskEvents
+        .filter((event) => event.event === "VERIFICATION_RECORDED"
+          && ["failed", "blocked"].includes(event.details?.status)
+          && (cycle === null || event.details?.verificationCycle === cycle))
+        .map((event) => event.details?.requirement ?? event.details?.id ?? event.details?.checkId),
+      ...((state?.checks ?? []))
+        .filter((check) => ["failed", "blocked"].includes(check.status)
+          && (cycle === null || check.details?.verificationCycle === cycle))
+        .map((check) => check.requirement ?? check.id ?? check.checkId),
+    ].filter(Boolean),
+  )].sort();
+
+  const projection = projectHypothesisStates(taskEvents);
+  const openHypotheses = [...projection.openHypotheses].sort();
+
+  const interventions = taskEvents.filter((event) => event.event === "INTERVENTION_RECORDED");
+  const latestIntervention = interventions.at(-1)?.details?.intervention?.id ?? null;
+
+  // doNotRepeat requires semantic repetition AND at least two completed
+  // post-intervention verification cycles AND unchanged failure surface.
+  const surfacesByCycle = failedRequirementSurfacesFromEvents(taskEvents, state);
+  const completedCycles = [...new Set(
+    taskEvents.filter((event) => event.event === "VERIFICATION_STARTED")
+      .map((event) => event.details?.verificationCycle)
+      .filter(Number.isInteger),
+  )].sort((a, b) => a - b);
+
+  const fingerprintGroups = new Map();
+  for (const event of interventions) {
+    const fingerprint = event.details?.interventionSemanticFingerprint;
+    if (!fingerprint) continue;
+    if (!fingerprintGroups.has(fingerprint)) fingerprintGroups.set(fingerprint, []);
+    fingerprintGroups.get(fingerprint).push(event);
+  }
+
+  const doNotRepeat = [];
+  for (const [fingerprint, group] of fingerprintGroups.entries()) {
+    if (group.length < 2) continue;
+    const lastInterventionCycle = Math.max(...group.map((event) => event.details?.verificationCycle ?? 1));
+    const postCycles = completedCycles.filter((completed) => completed > lastInterventionCycle);
+    if (postCycles.length < 2) continue;
+    const firstSurface = [...(surfacesByCycle.get(lastInterventionCycle) ?? [])].sort();
+    const latestSurface = [...(surfacesByCycle.get(postCycles.at(-1)) ?? [])].sort();
+    if (JSON.stringify(firstSurface) === JSON.stringify(latestSurface)) {
+      doNotRepeat.push(fingerprint);
+    }
+  }
+  doNotRepeat.sort();
+
+  return {
+    activeFailureSignatures,
+    activeFailedRequirements,
+    openHypotheses,
+    latestIntervention,
+    nextExperiment: null,
+    doNotRepeat,
+  };
+}
+
+export async function buildTaskReflection({ target, packageRoot, taskId = null } = {}) {
+  const trace = await buildTaskTrace({ target, packageRoot, taskId });
+  // Modern tasks own a scoped ledger; legacy singleton callers still pass a
+  // taskId that must be used only as a filter over the canonical ledger.
+  const task = taskId ? await findTaskById(target, taskId, packageRoot) : null;
+  const rawEvents = await readEvents(target, packageRoot, task ? { taskId } : {});
+
+  // Authoritative surfaces come from the canonical trace projection.
+  const surfaceEntries = {};
+  for (const entry of trace.failureSurfaces) {
+    surfaceEntries[entry.verificationCycle] = { surface: entry.surface, signatures: [] };
+  }
+  const signatureSets = signatureSetsByCycle(trace);
+  for (const [cycle, signatures] of signatureSets.entries()) {
+    if (!surfaceEntries[cycle]) surfaceEntries[cycle] = { surface: [], signatures: [] };
+    surfaceEntries[cycle].signatures = [...signatures].sort();
+  }
+
+  const cycles = [...new Set([
+    ...trace.failureSurfaces.map((entry) => entry.verificationCycle),
+    ...trace.diagnostics.cases.map((diagnosticCase) => diagnosticCase.verificationCycle),
+  ])].sort((a, b) => a - b);
+
+  const strategies = computeStrategyFingerprintsImpl(trace);
+  const oscillation = detectOscillation(strategies);
+
+  const signals = [];
+  let status = REFLECTION_STATUS.ADVANCING;
+
+  const evaluatedInterventions = evaluateInterventionEffectiveness(trace, surfaceEntries);
+  const repeatedNonInformative = evaluatedInterventions
+    .filter((intervention) => intervention.effectiveness === "NON_INFORMATIVE");
+  if (oscillation.detected) {
+    signals.push("OSCILLATING_STRATEGY");
+    status = REFLECTION_STATUS.WATCH;
+  }
+  if (repeatedNonInformative.length >= 2) {
+    signals.push("REPEATED_INTERVENTION");
+    status = REFLECTION_STATUS.WATCH;
+  }
+
+  const lastTwoSameStrategy = strategies.length >= 2
+    && strategies.at(-1).strategyFingerprint === strategies.at(-2).strategyFingerprint
+    && JSON.stringify(surfaceEntries[strategies.at(-1)?.verificationCycle]?.signatures ?? [])
+      === JSON.stringify(surfaceEntries[strategies.at(-2)?.verificationCycle]?.signatures ?? []);
+  if (lastTwoSameStrategy && !signals.includes("OSCILLATING_STRATEGY")) {
+    status = status === REFLECTION_STATUS.ADVANCING ? REFLECTION_STATUS.WATCH : status;
+  }
+
+  // Information Gain v2 truth comes fully from the authoritative cycle
+  // analysis projection. Consumers must not redefine gain semantics.
+  const gainProjection = buildInformationGainProjection(rawEvents, taskId ?? null);
+  const cyclesWithoutEffectiveGain = gainProjection
+    .filter((entry) => !entry.effectiveGain)
+    .map((entry) => entry.verificationCycle);
+
+  // One canonical structured-stall truth shared with phase and progress.
+  const stallAnalysis = evaluateStructuredDiagnosticStall(gainProjection);
+  const latestNoGain = Boolean(stallAnalysis.stalled);
+  let consecutiveNoGainCycles = 0;
+  for (let i = gainProjection.length - 1; i >= 0 && gainProjection[i].effectiveGain === false; i--) {
+    consecutiveNoGainCycles += 1;
+  }
+  const previousEntry = gainProjection.length >= 2 ? gainProjection.at(-2) : null;
+  const currentEntry = gainProjection.at(-1) ?? null;
+  if (latestNoGain) {
+    status = REFLECTION_STATUS.STALLED;
+    if (!signals.includes("NO_EFFECTIVE_INFORMATION_GAIN")) signals.push("NO_EFFECTIVE_INFORMATION_GAIN");
+  }
+  if ((trace.actions?.ambiguous ?? 0) > 0) {
+    signals.push("EXTERNAL_ACTION_RECONCILIATION_REQUIRED");
+    status = status === REFLECTION_STATUS.ADVANCING ? REFLECTION_STATUS.WATCH : status;
+  }
+
+  const recommendedProtocolAction = (trace.actions?.ambiguous ?? 0) > 0
+    ? "RECONCILE_EXTERNAL_ACTION"
+    : oscillation.detected
+    ? "INTRODUCE_NEW_OBSERVATION"
+    : (status === REFLECTION_STATUS.STALLED ? "REQUIRE_NEW_DIAGNOSTIC_INFORMATION" : "CONTINUE");
+
+  return {
+    schemaVersion: 1,
+    command: "reflect",
+    taskId: trace.task.id,
+    taskPhase: trace.task.phase,
+    integrityValid: trace.integrity.valid,
+    snapshotConsistent: trace.snapshot.consistent,
+    status,
+    verificationCycles: cycles.length,
+    failureSurfaces: trace.failureSurfaces,
+    hypotheses: summarizeHypotheses(trace),
+    interventions: (() => {
+      const evaluated = evaluatedInterventions;
+      return {
+        count: evaluated.length,
+        informative: evaluated.filter((intervention) => ["INFORMATIVE", "IMPROVED"].includes(intervention.effectiveness)).length,
+        nonInformative: evaluated.filter((intervention) => intervention.effectiveness === "NON_INFORMATIVE").length,
+        details: evaluated,
+      };
+    })(),
+    informationGain: {
+      cyclesWithCases: trace.diagnostics.cases.map((diagnosticCase) => diagnosticCase.verificationCycle),
+      cyclesWithoutEffectiveGain,
+      cycles: gainProjection.map(({ dimensions, ...rest }) => ({ ...rest, dimensions })),
+    },
+    strategies,
+    oscillation,
+    signals,
+    stallAnalysis: {
+      latestNoGain,
+      consecutiveNoGainCycles,
+      sameStrategyAsPrevious: Boolean(previousEntry && currentEntry
+        && previousEntry.evidence.strategyFingerprint === currentEntry.evidence.strategyFingerprint),
+      sameFailureSurfaceAsPrevious: Boolean(previousEntry && currentEntry
+        && JSON.stringify(previousEntry.evidence.failureSurface) === JSON.stringify(currentEntry.evidence.failureSurface)),
+      sameFailureSignaturesAsPrevious: Boolean(previousEntry && currentEntry
+        && JSON.stringify(previousEntry.evidence.failureSignatures) === JSON.stringify(currentEntry.evidence.failureSignatures)),
+    },
+    recommendedProtocolAction,
+    actions: trace.actions,
+  };
+}
+
+export { computeStrategyFingerprintsImpl as computeStrategyFingerprints };

package/src/core/resumability.js

@@ -1,22 +1,76 @@
 import { currentRepositoryFingerprint } from "./repository.js";
+import { validateEventLedger } from "./events.js";
 import { createWorkState, initializeWorkState, readWorkState, mutateWorkState } from "./work-state.js";
 
 const DEFAULT_PENDING_STEPS = ["planning", "implementation", "verification"];
 
+/**
+ * Resume phase derived from the highest lifecycle milestone already recorded in
+ * a validated ledger. Recreating a checkpoint at ROUTED for a task whose ledger
+ * already passed EXECUTION_STARTED would make every subsequent advance append a
+ * duplicate non-repeatable milestone and invalidate the ledger, so restoration
+ * must resume at the phase the recorded chronology supports.
+ */
+const RESUME_PHASE_BY_MILESTONE = Object.freeze({
+  PLAN_RECORDED: "PLANNED",
+  EXECUTION_STARTED: "EXECUTING",
+  VERIFICATION_STARTED: "VERIFYING",
+  VERIFICATION_RECORDED: "VERIFYING",
+});
+
+async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
+  let ledger;
+  try {
+    ledger = await validateEventLedger(target, packageRoot, { taskId });
+  } catch {
+    return null;
+  }
+  if (!ledger?.valid) return null;
+  const scoped = (ledger.events ?? []).filter((event) => event.taskId === taskId);
+  if (scoped.some((event) => event.event === "COMPLETION_VALIDATED")) return null;
+  const positions = RESUME_PHASE_BY_MILESTONE;
+  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";
+  }
+  return derived;
+}
+
+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";
+  const steps = resumeSteps(resumedPhase);
   const state = createWorkState({
     taskId: contract.value.taskId,
     contractFingerprint: contract.fingerprint,
     routeFingerprint: route.fingerprint,
     repositoryFingerprint: await currentRepositoryFingerprint(target),
-    phase: "ROUTED",
+    phase: resumedPhase,
     selectedGuides: route.value.guides,
-    completedSteps: ["contract", "route"],
-    pendingSteps: DEFAULT_PENDING_STEPS,
+    completedSteps: steps.completedSteps,
+    pendingSteps: steps.pendingSteps,
     checks: [],
     failures: [],
     blockers: [],

package/src/core/schema-validation.js

@@ -33,6 +33,15 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "execution",
   "authority",
   "task-descriptor",
+  "task-recovery",
+  "diagnostic-case",
+  "intervention",
+  "hypothesis-disposition",
+  "action",
+  "approval",
+  "capability-policy",
+  "trajectory-evaluation",
+  "trajectory-scenario",
 ]);
 
 export class SchemaValidationError extends Error {