@cassiomc1/forgeloop 0.1.10 → 0.1.12

package/src/core/completion.js

@@ -1,6 +1,6 @@
 import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { requiredEvidenceForTarget } from "./completion-artifacts.js";
-import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger } from "./events.js";
+import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger, validateStateLedgerCoherence } from "./events.js";
 import { evaluatePreflight } from "./preflight.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
@@ -9,6 +9,8 @@ import { createReceipt, validateReceipt } from "./receipt.js";
 import { completionRelationshipErrors } from "./completion-relationships.js";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { evaluateStartExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
+import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
+import { classifyRequirement, evaluateTerminalRequirements } from "./evidence-readiness.js";
 
 function issue(code, message, artifacts = [], details = {}) {
   return { code, message, artifacts, ...details };
@@ -27,6 +29,7 @@ function repairNext(error) {
     case "E_RECEIPT_CONTRACT_MISMATCH":
     case "E_RECEIPT_ROUTE_MISMATCH":
     case "E_RECEIPT_STATE_MISMATCH":
+    case "E_RECEIPT_CYCLE_MISMATCH":
       return "Run forgeloop prepare-completion, inspect the receipt, and validate it before retrying completion.";
     case "E_PHASE_PREREQUISITE_MISSING":
       return "Advance from EXECUTING through VERIFYING and REVIEWING, resolving the named prerequisite before completion.";
@@ -39,6 +42,36 @@ function repairNext(error) {
     case "E_CHECK_INVALID":
     case "E_CHECK_STATUS_CONTRADICTION":
       return "Run forgeloop record-check with compatible observed evidence for the named requirement.";
+    case "E_EVIDENCE_PARTIAL":
+      return "Run or finish the missing component checks and record observed evidence.";
+    case "E_EVIDENCE_INVALID":
+      return "Resolve the invalid evidence format or failure status with forgeloop record-check.";
+    case "E_FUTURE_LIFECYCLE_EVIDENCE":
+      return "Remove the premature terminal claim; the lifecycle event must satisfy it.";
+    case "E_CIRCULAR_COMPLETION_REQUIREMENT":
+    case "E_MIXED_TERMINAL_REQUIREMENT":
+      return "Split ordinary verification from terminal lifecycle criteria.";
+    case "E_PUBLICATION_REQUIREMENT_PENDING":
+      return "The contract explicitly requires publication. Record authoritative publication evidence or revise the contract if publication is not in scope.";
+    case "E_PRODUCTION_REQUIREMENT_PENDING":
+      return "The contract explicitly requires production readiness. Record authoritative deployment/readiness evidence before completion.";
+    case "E_TERMINAL_REQUIREMENT_PENDING":
+      return "The contract contains an unresolved terminal requirement. Ensure all terminal lifecycle criteria are satisfied.";
+    case "E_TERMINAL_REQUIREMENT_UNKNOWN":
+      return "Terminal results must reference an existing canonical requirement declared in the contract.";
+    case "E_TERMINAL_REQUIREMENT_NOT_TERMINAL":
+      return "Use forgeloop record-check for ordinary verification requirements.";
+    case "E_TERMINAL_REQUIREMENT_TYPE_MISMATCH":
+      return "Ensure the supplied terminal type matches the canonical requirement type.";
+    case "E_TERMINAL_STATUS_REGRESSION":
+      return "Terminal publication status cannot regress to a weaker state.";
+    case "E_STATE_LEDGER_DIVERGENCE":
+      return "Do not edit work-state or receipt manually; recover through supported lifecycle commands.";
+    case "E_COMPLETION_RECOVERY_UNAUTHORIZED":
+    case "E_COMPLETION_REJECTION_LEDGER_MISMATCH":
+    case "E_COMPLETION_REJECTION_STATE_FINGERPRINT_MISMATCH":
+    case "E_COMPLETION_REJECTION_RECEIPT_FINGERPRINT_MISMATCH":
+      return "Ensure a matching completion rejection exists in the protocol ledger and artifacts remain unmodified before recovery.";
     case "E_GATE_UNVERIFIED":
     case "E_GATE_STALE":
       return "Satisfy or refresh the named gate, then rerun forgeloop preflight.";
@@ -99,6 +132,9 @@ async function validateLedger(target, taskId, state, errors, packageRoot) {
   }
   const ledger = await validateEventLedger(target, packageRoot);
   for (const error of ledger.errors) errors.push({ ...error, artifacts: [ARTIFACT_PATHS.events] });
+  for (const error of validateStateLedgerCoherence(state, ledger.events)) {
+    errors.push({ ...error, artifacts: [ARTIFACT_PATHS.state, ARTIFACT_PATHS.events] });
+  }
   const requiredEvents = LIFECYCLE_MILESTONES.slice(0, state?.phase === "COMPLETE" ? undefined : -1);
   const observed = new Set(ledger.events.filter((event) => event.taskId === taskId).map((event) => event.event));
   for (const event of requiredEvents) {
@@ -213,9 +249,29 @@ export async function evaluateCompletion({ target, packageRoot, strict = false }
     }
   }
 
-  const sortedErrors = sortIssues(errors);
   const receiptValue = receipt?.value;
   const publication = receiptValue ? publicationStatus(receiptValue) : "not-published";
+
+  if (contract) {
+    const allContractReqs = [
+      ...(contract.value.verification ?? []),
+      ...(contract.value.successCriteria ?? []),
+    ];
+    const terminalEval = evaluateTerminalRequirements({
+      requirements: allContractReqs,
+      receipt: receiptValue,
+    });
+    for (const termErr of terminalEval.errors) {
+      errors.push(issue(
+        termErr.code,
+        termErr.message,
+        [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt],
+        { requirementId: termErr.requirementId },
+      ));
+    }
+  }
+
+  const sortedErrors = sortIssues(errors);
   const valid = sortedErrors.length === 0;
   return {
     status: valid ? "VALID" : "REJECTED",
@@ -236,6 +292,77 @@ export async function evaluateCompletion({ target, packageRoot, strict = false }
 
 export async function runComplete({ target, packageRoot, strict = false, persist = true } = {}) {
   const result = await evaluateCompletion({ target, packageRoot, strict });
+  const rejectionCodes = [...new Set(result.errors.map((error) => error.code))].sort();
+  const evidenceOnlyRejection = rejectionCodes.length > 0
+    && rejectionCodes.every(isRecoverableCompletionEvidenceCode);
+  if (persist && result.status === "REJECTED" && evidenceOnlyRejection) {
+    const state = await readWorkState(target, packageRoot);
+    if (state?.phase === "REVIEWING") {
+      const reasonCodes = rejectionCodes;
+      const missingRequirementIds = [...new Set(result.errors.map((error) => error.requirementId).filter(Boolean))].sort();
+      const currentCycle = state.verificationCycle ?? 1;
+      const alreadyRejected = state.lastCompletionAttempt?.status === "REJECTED"
+        && (state.lastCompletionAttempt.verificationCycle ?? 1) === currentCycle
+        && JSON.stringify([...(state.lastCompletionAttempt.reasonCodes ?? [])].sort()) === JSON.stringify(reasonCodes)
+        && JSON.stringify([...(state.lastCompletionAttempt.missingRequirementIds ?? [])].sort()) === JSON.stringify(missingRequirementIds);
+
+      if (alreadyRejected) {
+        return result;
+      }
+
+      const now = new Date().toISOString();
+      const next = {
+        ...state,
+        lastCompletionAttempt: {
+          status: "REJECTED",
+          reasonCodes,
+          missingRequirementIds,
+          verificationCycle: currentCycle,
+          timestamp: now,
+        },
+        lastUpdated: now,
+      };
+      let receipt = null;
+      try {
+        receipt = await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+      } catch {
+        // The evaluator already reports a missing or invalid receipt; evidence-only rejection can persist without one.
+      }
+      await writeWorkState(target, next, { packageRoot });
+      let nextReceipt = null;
+      if (receipt) {
+        nextReceipt = await createReceipt({
+          ...receipt.value,
+          stateFingerprint: canonicalFingerprint(next),
+          verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
+        }, packageRoot);
+        await writeJsonArtifact(target, ARTIFACT_PATHS.receipt, nextReceipt, "execution-receipt", packageRoot);
+      }
+      const ledger = await validateEventLedger(target, packageRoot);
+      const lastRejection = ledger.events.filter((e) => e.taskId === state.taskId && e.event === "COMPLETION_REJECTED").at(-1);
+      const lastDetails = lastRejection?.details ?? {};
+      const isIdentical = lastRejection
+        && (lastDetails.verificationCycle ?? 1) === currentCycle
+        && JSON.stringify([...(lastDetails.reasonCodes ?? [])].sort()) === JSON.stringify(reasonCodes)
+        && JSON.stringify([...(lastDetails.missingRequirementIds ?? [])].sort()) === JSON.stringify(missingRequirementIds)
+        && lastDetails.stateFingerprint === canonicalFingerprint(next)
+        && lastDetails.receiptFingerprint === (nextReceipt ? canonicalFingerprint(nextReceipt) : undefined);
+
+      if (!isIdentical) {
+        await appendProtocolEvent(target, {
+          taskId: state.taskId,
+          event: "COMPLETION_REJECTED",
+          details: {
+            verificationCycle: currentCycle,
+            reasonCodes,
+            missingRequirementIds,
+            stateFingerprint: canonicalFingerprint(next),
+            ...(nextReceipt ? { receiptFingerprint: canonicalFingerprint(nextReceipt) } : {}),
+          },
+        }, packageRoot);
+      }
+    }
+  }
   if (persist && result.status === "VALID") {
     const state = await readWorkState(target, packageRoot);
     if (state && state.phase !== "COMPLETE") {
@@ -252,6 +379,7 @@ export async function runComplete({ target, packageRoot, strict = false, persist
       const nextReceipt = await createReceipt({
         ...receipt.value,
         stateFingerprint: canonicalFingerprint(next),
+        verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
       }, packageRoot);
       await writeWorkState(target, next, { packageRoot });
       await writeJsonArtifact(target, ARTIFACT_PATHS.receipt, nextReceipt, "execution-receipt", packageRoot);

package/src/core/contract.js

@@ -2,26 +2,91 @@ import { PROTOCOL_VERSION } from "./protocol.js";
 import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { assertSecretFree } from "./receipt.js";
+import { REQUIREMENT_TYPES, isMixedTerminalRequirement } from "./evidence-readiness.js";
 
 export const CONTRACT_SCHEMA_VERSION = 1;
 
-const CONTRACT_ARRAY_FIELDS = Object.freeze([
+const CONTRACT_STRING_ARRAY_FIELDS = Object.freeze([
   "deliverables",
   "constraints",
   "risks",
-  "verification",
-  "successCriteria",
   "stopConditions",
   "unresolvedDecisions",
   "sourceRefs",
 ]);
 
+const CONTRACT_REQUIREMENT_FIELDS = Object.freeze([
+  "verification",
+  "successCriteria",
+]);
+
 function assertStringArray(value, label) {
   if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
     throw new Error(`${label} must be an array of non-empty strings`);
   }
 }
 
+function assertRequirementItem(item, label, seenIds) {
+  if (typeof item === "string") {
+    if (item.trim() === "") {
+      throw new Error(`${label} must be a non-empty string or requirement object`);
+    }
+    if (isMixedTerminalRequirement(item)) {
+      const err = new Error(`Mixed verification and lifecycle requirement detected in ${label}: ${item}`);
+      err.code = "E_CIRCULAR_COMPLETION_REQUIREMENT";
+      throw err;
+    }
+    return;
+  }
+  if (item && typeof item === "object" && !Array.isArray(item)) {
+    if (typeof item.text !== "string" || item.text.trim() === "") {
+      throw new Error(`${label}.text must be a non-empty string`);
+    }
+    if (isMixedTerminalRequirement(item.text)) {
+      const err = new Error(`Mixed verification and lifecycle requirement detected in ${label}: ${item.text}`);
+      err.code = "E_CIRCULAR_COMPLETION_REQUIREMENT";
+      throw err;
+    }
+    if (item.id !== undefined) {
+      if (typeof item.id !== "string" || item.id.trim() === "") {
+        throw new Error(`${label}.id must be a non-empty string`);
+      }
+      if (seenIds.has(item.id)) {
+        throw new Error(`Duplicate requirement ID in contract: ${item.id}`);
+      }
+      seenIds.add(item.id);
+    }
+    if (item.type !== undefined && !REQUIREMENT_TYPES.includes(item.type)) {
+      throw new Error(`${label}.type must be a valid requirement type`);
+    }
+    if (item.operator !== undefined && !["SINGLE", "ALL"].includes(item.operator)) {
+      throw new Error(`${label}.operator must be SINGLE or ALL`);
+    }
+    if (item.requiredEvidenceKind !== undefined && !["OBSERVED", "INFERRED", "NOT_VERIFIED", "BLOCKED", "HYPOTHESIS"].includes(item.requiredEvidenceKind)) {
+      throw new Error(`${label}.requiredEvidenceKind must be a valid evidence kind`);
+    }
+    if (item.requirements !== undefined) {
+      if (!Array.isArray(item.requirements)) {
+        throw new Error(`${label}.requirements must be an array`);
+      }
+      item.requirements.forEach((child, index) => {
+        assertRequirementItem(child, `${label}.requirements[${index}]`, seenIds);
+      });
+    }
+    return;
+  }
+  throw new Error(`${label} must be a non-empty string or requirement object`);
+}
+
+function assertRequirementArray(value, label, seenIds) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+  value.forEach((item, index) => {
+    assertRequirementItem(item, `${label}[${index}]`, seenIds);
+  });
+}
+
 const ASSUMPTION_FIELDS = Object.freeze([
   "value",
   "reason",
@@ -93,11 +158,17 @@ export function createContract(input = {}) {
     assumptions: [],
   };
   assertAssumptions(input.assumptions ?? []);
-  for (const field of CONTRACT_ARRAY_FIELDS) {
+  const seenIds = new Set();
+  for (const field of CONTRACT_STRING_ARRAY_FIELDS) {
     const value = input[field] ?? [];
     assertStringArray(value, `Contract ${field}`);
     contract[field] = [...value];
   }
+  for (const field of CONTRACT_REQUIREMENT_FIELDS) {
+    const value = input[field] ?? [];
+    assertRequirementArray(value, `Contract ${field}`, seenIds);
+    contract[field] = structuredClone(value);
+  }
   contract.assumptions = (input.assumptions ?? []).map((assumption) => ({
     value: assumption.value,
     reason: assumption.reason,
@@ -116,6 +187,13 @@ export function contractFingerprint(contract) {
 export async function validateContract(contract, packageRoot) {
   assertSecretFree(contract);
   assertAssumptions(contract.assumptions ?? []);
+  const seenIds = new Set();
+  for (const field of CONTRACT_STRING_ARRAY_FIELDS) {
+    assertStringArray(contract[field] ?? [], `Contract ${field}`);
+  }
+  for (const field of CONTRACT_REQUIREMENT_FIELDS) {
+    assertRequirementArray(contract[field] ?? [], `Contract ${field}`, seenIds);
+  }
   const schema = await readSchema("current-contract", packageRoot);
   assertSchema(contract, schema, "current contract");
   return contract;

package/src/core/coverage.js

@@ -1,4 +1,5 @@
 import { PROTOCOL_VERSION } from "./protocol.js";
+import { evaluateRequiredEvidence, normalizeRequirements } from "./evidence-readiness.js";
 
 export const COVERAGE_SCHEMA_VERSION = 1;
 export const COVERAGE_STATUSES = Object.freeze(["COVERED", "PARTIAL", "NOT_VERIFIED", "BLOCKED"]);
@@ -59,7 +60,8 @@ export function assertCoverage(value, label = "evidence coverage") {
   const expected = evaluateCoverage(requiredEvidence, observedEvidence, {
     blocked: value.status === "BLOCKED",
   });
-  if (value.status !== expected && !(value.status === "BLOCKED" && expected === "BLOCKED")) {
+  const semanticPartial = value.status === "PARTIAL" && value.details?.readinessStatus === "PARTIAL";
+  if (value.status !== expected && !semanticPartial && !(value.status === "BLOCKED" && expected === "BLOCKED")) {
     throw coverageError("E_EVIDENCE_COVERAGE_PARTIAL", `${label}.status does not match its observed evidence`);
   }
   return value;
@@ -72,18 +74,21 @@ export function assertCoverageList(value, label = "evidenceCoverage") {
 }
 
 export function coverageForRequirements(requirements, checks, { blockedIds = [] } = {}) {
-  const normalizedRequirements = stringArray(requirements ?? [], "requirements");
+  const normalizedRequirements = normalizeRequirements(requirements ?? []);
   const normalizedChecks = Array.isArray(checks) ? checks : [];
-  const observed = new Set(
-    normalizedChecks
-      .filter((check) => check?.status === "passed" && check.evidenceKind === "OBSERVED")
-      .flatMap((check) => [check.id, check.kind, check.requirement]),
-  );
+  const readiness = evaluateRequiredEvidence({ requirements: normalizedRequirements, checks: normalizedChecks });
+  const covered = new Set(readiness.covered.map((item) => item.id));
+  const partial = new Set(readiness.partial.map((item) => item.id));
+  const invalid = new Set(readiness.invalid.map((item) => item.id));
   const blocked = new Set(blockedIds);
-  return normalizedRequirements.map((requirement) => createCoverage({
-    requirement,
-    requiredEvidence: [requirement],
-    observedEvidence: observed.has(requirement) ? [requirement] : [],
-    blocked: blocked.has(requirement),
+  return normalizedRequirements.filter((requirement) => !requirement.terminalOwned).map((requirement) => createCoverage({
+    requirement: requirement.text,
+    requiredEvidence: [requirement.text],
+    observedEvidence: covered.has(requirement.id) ? [requirement.text] : [],
+    blocked: blocked.has(requirement.text) || blocked.has(requirement.id),
+    ...(partial.has(requirement.id) || invalid.has(requirement.id) ? {
+      status: "PARTIAL",
+      details: { requirementId: requirement.id, readinessStatus: "PARTIAL" },
+    } : {}),
   }));
 }

package/src/core/discovery-surfaces.js

@@ -0,0 +1,22 @@
+export const DISCOVERY_SURFACES = Object.freeze([
+  Object.freeze({
+    id: "agents-md",
+    path: "AGENTS.md",
+    kind: "project-instructions",
+  }),
+  Object.freeze({
+    id: "claude-md",
+    path: "CLAUDE.md",
+    kind: "project-instructions",
+  }),
+  Object.freeze({
+    id: "cursor-rule",
+    path: ".cursor/rules/project-loop.mdc",
+    kind: "project-instructions",
+  }),
+  Object.freeze({
+    id: "github-repository-instructions",
+    path: ".github/copilot-instructions.md",
+    kind: "project-instructions",
+  }),
+]);

package/src/core/events.js

@@ -8,6 +8,7 @@ import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { assertSecretFree } from "./receipt.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
+import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
 
 const EVENT_SCHEMA_VERSION = 1;
 export const LIFECYCLE_MILESTONES = Object.freeze([
@@ -27,7 +28,12 @@ export const ACTIVATION_EVENT_MATRIX = Object.freeze([
   Object.freeze({ stage: "preflight blocked", event: "PREFLIGHT_BLOCKED", requiredFor: "blocked activation" }),
   Object.freeze({ stage: "preflight ready", event: "PREFLIGHT_READY", requiredFor: "resumable readiness" }),
 ]);
-const REPEATABLE_MILESTONES = new Set(["VERIFICATION_RECORDED"]);
+const REPEATABLE_MILESTONES = new Set([
+  "VERIFICATION_STARTED",
+  "VERIFICATION_RECORDED",
+  "REVIEW_STARTED",
+  "TERMINAL_RESULT_RECORDED",
+]);
 
 function eventHash(event) {
   const { hash, ...body } = event;
@@ -126,7 +132,7 @@ export async function validateEventLedger(target, packageRoot) {
           code: "E_PHASE_CHRONOLOGY_INVALID",
           message: `${event.event} is missing prerequisite milestone: ${LIFECYCLE_MILESTONES[lastMilestone + 1]}`,
         });
-      } else if (milestoneIndex < lastMilestone) {
+      } else if (milestoneIndex < lastMilestone && event.event !== "VERIFICATION_STARTED") {
         errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `${event.event} is out of lifecycle order` });
       } else if (milestoneIndex === lastMilestone && !REPEATABLE_MILESTONES.has(event.event)) {
         errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
@@ -161,6 +167,181 @@ export async function validateEventLedger(target, packageRoot) {
     if (event.event === "COMPLETION_VALIDATED" && !seen.has("VERIFICATION_RECORDED")) {
       errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "completion validated before verification evidence" });
     }
+    if (event.event === "COMPLETION_REJECTED" && !seen.has("VERIFICATION_STARTED")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "completion rejected before verification started" });
+    }
   }
   return { valid: errors.length === 0, events, errors };
 }
+
+export function validateStateLedgerCoherence(state, events) {
+  const errors = [];
+  if (!Number.isInteger(state.verificationCycle)) return errors;
+  const taskEvents = events.filter((event) => event.taskId === state.taskId);
+  const observed = new Set(taskEvents.map((event) => event.event));
+  const supportsReviewEvents = taskEvents.some((event) => event.event === "REVIEW_STARTED"
+    || (event.event === "VERIFICATION_STARTED" && Number.isInteger(event.details?.verificationCycle)));
+  const phaseRequirements = {
+    EXECUTING: ["EXECUTION_STARTED"],
+    VERIFYING: ["EXECUTION_STARTED", "VERIFICATION_STARTED"],
+    DIAGNOSING: ["EXECUTION_STARTED", "VERIFICATION_STARTED"],
+    CORRECTING: ["EXECUTION_STARTED", "VERIFICATION_STARTED"],
+    REVIEWING: ["EXECUTION_STARTED", "VERIFICATION_STARTED", ...(supportsReviewEvents ? ["REVIEW_STARTED"] : [])],
+    COMPLETE: ["EXECUTION_STARTED", "VERIFICATION_STARTED", ...(supportsReviewEvents ? ["REVIEW_STARTED"] : []), "COMPLETION_VALIDATED"],
+  };
+  for (const required of phaseRequirements[state.phase] ?? []) {
+    if (!observed.has(required)) {
+      errors.push({
+        code: "E_STATE_LEDGER_DIVERGENCE",
+        message: `Work-state phase ${state.phase} requires ledger event ${required}`,
+      });
+    }
+  }
+  if (Number.isInteger(state.verificationCycle)) {
+    const verificationEvents = taskEvents
+      .map((event, index) => ({ event, index }))
+      .filter(({ event }) => event.event === "VERIFICATION_STARTED");
+    const cycles = verificationEvents.map(({ event }) => event.details?.verificationCycle ?? 1);
+    if (cycles.at(-1) !== state.verificationCycle) {
+      errors.push({
+        code: "E_STATE_LEDGER_DIVERGENCE",
+        message: "Work-state verification cycle does not match the lifecycle ledger",
+      });
+    }
+    const latestVerification = verificationEvents.at(-1);
+    const latestReview = taskEvents
+      .map((event, index) => ({ event, index }))
+      .filter(({ event }) => event.event === "REVIEW_STARTED")
+      .at(-1);
+    const latestReviewCycle = latestReview?.event.details?.verificationCycle;
+    if (state.phase === "VERIFYING"
+      && latestReviewCycle === state.verificationCycle
+      && latestReview.index > (latestVerification?.index ?? -1)) {
+      errors.push({
+        code: "E_STATE_LEDGER_DIVERGENCE",
+        message: "Work-state returned to VERIFYING without a new verification cycle in the lifecycle ledger",
+      });
+    }
+    if (["REVIEWING", "COMPLETE"].includes(state.phase)
+      && supportsReviewEvents
+      && (latestReviewCycle !== state.verificationCycle
+        || latestReview.index < (latestVerification?.index ?? -1))) {
+      errors.push({
+        code: "E_STATE_LEDGER_DIVERGENCE",
+        message: "Work-state review phase does not match the current lifecycle ledger cycle",
+      });
+    }
+  }
+  return errors;
+}
+
+export function validateCompletionRecoveryAuthorization({ state, receipt, events } = {}) {
+  const errors = [];
+  if (!state) {
+    return {
+      authorized: false,
+      errors: [{ code: "E_STATE_MISSING", message: "Work-state is required for recovery validation" }],
+    };
+  }
+  const attempt = state.lastCompletionAttempt;
+  if (!attempt || attempt.status !== "REJECTED") {
+    return {
+      authorized: false,
+      errors: [{ code: "E_COMPLETION_RECOVERY_UNAUTHORIZED", message: "Recovery requires a persisted REJECTED completion attempt" }],
+    };
+  }
+  const hasRecoverableReason = Array.isArray(attempt.reasonCodes)
+    && attempt.reasonCodes.length > 0
+    && attempt.reasonCodes.every((code) => isRecoverableCompletionEvidenceCode(code));
+  if (!hasRecoverableReason) {
+    return {
+      authorized: false,
+      errors: [{ code: "E_COMPLETION_RECOVERY_UNAUTHORIZED", message: "Completion attempt contains no recoverable evidence reason codes" }],
+    };
+  }
+
+  const taskEvents = (events ?? []).filter((event) => event.taskId === state.taskId);
+  const targetCycle = state.verificationCycle ?? 1;
+
+  if (attempt.verificationCycle !== targetCycle) {
+    errors.push({
+      code: "E_COMPLETION_REJECTION_LEDGER_MISMATCH",
+      message: `Work-state rejection verificationCycle ${attempt.verificationCycle} does not match state verificationCycle ${targetCycle}`,
+    });
+    return { authorized: false, errors };
+  }
+
+  const reviewEvents = taskEvents
+    .map((event, index) => ({ event, index }))
+    .filter(({ event }) => event.event === "REVIEW_STARTED" && (event.details?.verificationCycle ?? 1) === targetCycle);
+  const latestReviewIndex = reviewEvents.at(-1)?.index ?? -1;
+
+  const rejectionEvents = taskEvents
+    .map((event, index) => ({ event, index }))
+    .filter(({ event }) => event.event === "COMPLETION_REJECTED");
+
+  if (rejectionEvents.length === 0) {
+    errors.push({
+      code: "E_COMPLETION_RECOVERY_UNAUTHORIZED",
+      message: "No COMPLETION_REJECTED event found in protocol ledger",
+    });
+    return { authorized: false, errors };
+  }
+
+  const matchingEvent = rejectionEvents.findLast(({ event, index }) => {
+    const eventCycle = event.details?.verificationCycle ?? 1;
+    if (eventCycle !== targetCycle) return false;
+    if (latestReviewIndex >= 0 && index < latestReviewIndex) return false;
+    return true;
+  });
+
+  if (!matchingEvent) {
+    errors.push({
+      code: "E_COMPLETION_REJECTION_LEDGER_MISMATCH",
+      message: `No matching COMPLETION_REJECTED event found for verification cycle ${targetCycle}`,
+    });
+    return { authorized: false, errors };
+  }
+
+  const eventDetails = matchingEvent.event.details ?? {};
+  const stateReasons = [...new Set(attempt.reasonCodes ?? [])].sort();
+  const eventReasons = [...new Set(eventDetails.reasonCodes ?? [])].sort();
+  if (stateReasons.join(",") !== eventReasons.join(",")) {
+    errors.push({
+      code: "E_COMPLETION_REJECTION_LEDGER_MISMATCH",
+      message: "Work-state rejection reasonCodes do not match ledger COMPLETION_REJECTED event",
+    });
+  }
+
+  const stateMissing = [...new Set(attempt.missingRequirementIds ?? [])].sort();
+  const eventMissing = [...new Set(eventDetails.missingRequirementIds ?? [])].sort();
+  if (stateMissing.join(",") !== eventMissing.join(",")) {
+    errors.push({
+      code: "E_COMPLETION_REJECTION_LEDGER_MISMATCH",
+      message: "Work-state missingRequirementIds do not match ledger COMPLETION_REJECTED event",
+    });
+  }
+
+  const currentStateFingerprint = canonicalFingerprint(state);
+  if (eventDetails.stateFingerprint && eventDetails.stateFingerprint !== currentStateFingerprint) {
+    errors.push({
+      code: "E_COMPLETION_REJECTION_STATE_FINGERPRINT_MISMATCH",
+      message: "Current work-state no longer matches the rejected completion snapshot",
+    });
+  }
+
+  if (eventDetails.receiptFingerprint !== undefined) {
+    const currentReceiptFingerprint = receipt ? canonicalFingerprint(receipt) : undefined;
+    if (currentReceiptFingerprint !== eventDetails.receiptFingerprint) {
+      errors.push({
+        code: "E_COMPLETION_REJECTION_RECEIPT_FINGERPRINT_MISMATCH",
+        message: "Current receipt no longer matches the rejected completion snapshot",
+      });
+    }
+  }
+
+  return {
+    authorized: errors.length === 0,
+    errors,
+  };
+}