@cassiomc1/forgeloop 0.1.10 → 0.1.12

package/schemas/work-state.schema.json

@@ -46,7 +46,50 @@
     "diagnosedHypothesis": { "type": "string", "minLength": 1 },
     "verificationEvidence": { "type": "array", "items": { "type": "object" } },
     "evidenceCoverage": { "type": "array", "items": { "type": "object" } },
-    "publicationStatus": { "enum": ["not-published", "local-only", "committed", "pushed", "published", "deployed"] }
+    "publicationStatus": { "enum": ["not-published", "local-only", "committed", "pushed", "published", "deployed"] },
+    "verificationCycle": { "type": "integer", "minimum": 1 },
+    "lastCompletionAttempt": {
+      "type": "object",
+      "required": [
+        "status",
+        "reasonCodes",
+        "missingRequirementIds",
+        "verificationCycle",
+        "timestamp"
+      ],
+      "properties": {
+        "status": { "const": "REJECTED" },
+        "reasonCodes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "missingRequirementIds": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "verificationCycle": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "stateFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "receiptFingerprint": {
+          "oneOf": [
+            { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+            { "type": "null" }
+          ]
+        },
+        "timestamp": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    }
   },
   "additionalProperties": false
 }

package/src/cli.js

@@ -24,13 +24,14 @@ import { formatPolicyResult, runPolicy } from "./commands/policy.js";
 import { formatBundleResult, runBundle } from "./commands/bundle.js";
 import { formatPrepareCompletionResult, runPrepareCompletion } from "./commands/prepare-completion.js";
 import { formatRecordCheckResult, runRecordCheck } from "./commands/record-check.js";
+import { formatRecordTerminalResult, runRecordTerminalResult } from "./commands/record-terminal-result.js";
 import { formatNextActionResult, runNext } from "./commands/next.js";
 import { resolveTarget } from "./core/filesystem.js";
 import { getPackageRoot } from "./core/templates.js";
 import { ARTIFACT_PATHS } from "./core/artifacts.js";
 
 function usage(command = null) {
-  const commands = "init|doctor|update|activate|route|preflight|advance|next|prepare-completion|record-check|complete|audit|report|policy|bundle|inspect|status|validate-state|clear-state|validate-receipt|validate-protocol";
+  const commands = "init|doctor|update|activate|route|preflight|advance|next|prepare-completion|record-check|record-terminal-result|complete|audit|report|policy|bundle|inspect|status|validate-state|clear-state|validate-receipt|validate-protocol";
   const options = ["  --path <directory>  target project directory (default: current directory)"];
   if (!command || command === "init" || command === "update") {
     options.push("  --dry-run           show planned writes without changing files");
@@ -52,7 +53,7 @@ function usage(command = null) {
   if (!command || command === "advance") {
     options.push("  --to <phase>        destination workflow phase");
   }
-  if (!command || ["activate", "advance", "next", "prepare-completion", "record-check", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(command)) {
+  if (!command || ["activate", "advance", "next", "prepare-completion", "record-check", "record-terminal-result", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(command)) {
     options.push("  --json              emit structured output as JSON");
   }
   if (!command || ["preflight", "complete", "audit", "report"].includes(command)) {
@@ -88,6 +89,14 @@ function usage(command = null) {
     options.push("  --exit-code <number> observed process exit code");
     options.push("  --details <json>     additional structured check details");
   }
+  if (!command || command === "record-terminal-result") {
+    options.push("  --requirement <id>   terminal requirement covered by the result");
+    options.push("  --type <type>        PUBLICATION or PRODUCTION_READINESS");
+    options.push("  --status <status>    observed terminal status");
+    options.push("  --source <text>      external action source (e.g. npm publish, git push)");
+    options.push("  --result <text>      observed external result description");
+    options.push("  --details <json>     additional structured result details");
+  }
   options.push("  --version           show the installed package version");
   options.push("  --help              show this help");
 
@@ -124,6 +133,8 @@ export function parseArgs(argv) {
     checkResult: null,
     checkExitCode: null,
     checkDetails: null,
+    checkType: null,
+    checkSource: null,
     policy: null,
     task: null,
     help: false,
@@ -133,7 +144,7 @@ export function parseArgs(argv) {
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
-    if (["init", "doctor", "update", "activate", "route", "preflight", "advance", "next", "prepare-completion", "record-check", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(argument)) {
+    if (["init", "doctor", "update", "activate", "route", "preflight", "advance", "next", "prepare-completion", "record-check", "record-terminal-result", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(argument)) {
       if (command) throw new Error(`Multiple commands are not supported: ${argument}`);
       command = argument;
     } else if (argument === "--help" || argument === "-h") {
@@ -248,6 +259,24 @@ export function parseArgs(argv) {
       if (!commandText || commandText.startsWith("-")) throw new Error("--command requires recorded text");
       options.checkCommand = commandText;
       index += 1;
+    } else if (argument === "--source") {
+      const sourceText = argv[index + 1];
+      if (!sourceText || sourceText.startsWith("-")) throw new Error("--source requires recorded text");
+      options.checkSource = sourceText;
+      index += 1;
+    } else if (argument.startsWith("--source=")) {
+      const sourceText = argument.slice("--source=".length);
+      if (!sourceText) throw new Error("--source requires recorded text");
+      options.checkSource = sourceText;
+    } else if (argument === "--type") {
+      const typeValue = argv[index + 1];
+      if (!typeValue || typeValue.startsWith("-")) throw new Error("--type requires a terminal type");
+      options.checkType = typeValue;
+      index += 1;
+    } else if (argument.startsWith("--type=")) {
+      const typeValue = argument.slice("--type=".length);
+      if (!typeValue) throw new Error("--type requires a terminal type");
+      options.checkType = typeValue;
     } else if (argument === "--result") {
       const resultText = argv[index + 1];
       if (!resultText || resultText.startsWith("-")) throw new Error("--result requires recorded text");
@@ -295,7 +324,7 @@ export function parseArgs(argv) {
 
   if (!command) return { command: null, options };
 
-  const jsonCommands = ["doctor", "route", "activate", "advance", "next", "prepare-completion", "record-check", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
+  const jsonCommands = ["doctor", "route", "activate", "advance", "next", "prepare-completion", "record-check", "record-terminal-result", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
   if (!jsonCommands.includes(command) && options.json) {
     throw new Error(`Option --json is not valid for ${command}`);
   }
@@ -479,6 +508,21 @@ export async function main(argv = process.argv.slice(2)) {
       return 0;
     }
 
+    if (command === "record-terminal-result") {
+      const result = await runRecordTerminalResult({
+        target,
+        packageRoot,
+        requirement: options.checkRequirement,
+        type: options.checkType,
+        status: options.checkStatus,
+        source: options.checkSource ?? options.checkCommand,
+        result: options.checkResult,
+        details: options.checkDetails ?? undefined,
+      });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordTerminalResult(result));
+      return 0;
+    }
+
     if (command === "complete") {
       const result = await runComplete({ target, packageRoot, strict: options.strict });
       console.log(options.json ? JSON.stringify(result, null, 2) : formatCompleteResult(result));

package/src/commands/record-terminal-result.js

@@ -0,0 +1,18 @@
+import { recordTerminalResult as recordTerminalResultArtifact } from "../core/completion-artifacts.js";
+
+export { recordTerminalResultArtifact as recordTerminalResult };
+
+export async function runRecordTerminalResult(input) {
+  return recordTerminalResultArtifact(input);
+}
+
+export function formatRecordTerminalResult(result) {
+  return [
+    "FORGELOOP TERMINAL RESULT RECORDED",
+    `requirement: ${result.requirementId}`,
+    `type: ${result.type}`,
+    `status: ${result.status}`,
+    `receipt: ${result.path}`,
+    "",
+  ].join("\n");
+}

package/src/commands/validate-protocol.js

@@ -8,6 +8,7 @@ import { validateReceipt } from "../core/receipt.js";
 import { validateTaskBrief, validateDelegatedResult } from "../core/delegation.js";
 import { ARTIFACT_PATHS, readJsonArtifact } from "../core/artifacts.js";
 import { evaluatePreflight, validateReadyProtocolConsistency } from "../core/preflight.js";
+import { validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
 
 async function readArtifact(target, relativePath, label) {
   if (!relativePath) return null;
@@ -118,11 +119,22 @@ export async function runValidateProtocol({
   } catch {
     // A missing or invalid preflight is already outside the optional protocol set.
   }
-  if (readErrors.length > 0 || schemaErrors.length > 0 || readyConsistencyErrors.length > 0) {
+  let ledgerErrors = [];
+  if (state && !stateValidationError) {
+    const ledger = await validateEventLedger(target, packageRoot);
+    ledgerErrors = [
+      ...ledger.errors.map((error) => ({ ...error, artifacts: [ARTIFACT_PATHS.events] })),
+      ...validateStateLedgerCoherence(state, ledger.events).map((error) => ({
+        ...error,
+        artifacts: [ARTIFACT_PATHS.state, ARTIFACT_PATHS.events],
+      })),
+    ];
+  }
+  if (readErrors.length > 0 || schemaErrors.length > 0 || readyConsistencyErrors.length > 0 || ledgerErrors.length > 0) {
     return {
       ...result,
       status: "INVALID",
-      errors: [...result.errors, ...readErrors, ...schemaErrors, ...readyConsistencyErrors]
+      errors: [...result.errors, ...readErrors, ...schemaErrors, ...readyConsistencyErrors, ...ledgerErrors]
         .sort((left, right) => left.code.localeCompare(right.code) || left.message.localeCompare(right.message)),
     };
   }

package/src/core/checks.js

@@ -26,6 +26,25 @@ function contradiction(message) {
   return checkError("E_CHECK_STATUS_CONTRADICTION", message);
 }
 
+function assertCompoundStatus(value, label) {
+  const components = value.details?.components;
+  if (!Array.isArray(components)) return;
+  for (const [index, component] of components.entries()) {
+    if (!component || typeof component !== "object" || Array.isArray(component)) {
+      throw checkError("E_CHECK_INVALID", `${label}.details.components[${index}] must be an object`);
+    }
+    string(component.requirementId ?? component.requirement, `${label}.details.components[${index}].requirementId`);
+    if (!CHECK_STATUSES.includes(component.status) || !CHECK_EVIDENCE_KINDS.includes(component.evidenceKind)) {
+      throw checkError("E_CHECK_INVALID", `${label}.details.components[${index}] has invalid status or evidenceKind`);
+    }
+  }
+  if (value.status === "passed" && components.some((component) => (
+    component.status !== "passed" || component.evidenceKind !== "OBSERVED"
+  ))) {
+    throw contradiction(`${label} passed cannot contain an unverified, partial, blocked, or failed component`);
+  }
+}
+
 export function createCheck(input = {}) {
   const check = {
     schemaVersion: CHECK_SCHEMA_VERSION,
@@ -78,6 +97,7 @@ export function assertCheck(value, label = "check") {
   if (value.status === "not-run" && value.evidenceKind !== "NOT_VERIFIED") {
     throw contradiction(`${label} not-run must use NOT_VERIFIED evidence`);
   }
+  assertCompoundStatus(value, label);
   return value;
 }
 

package/src/core/completion-artifacts.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import {
   ARTIFACT_PATHS,
   canonicalFingerprint,
@@ -17,6 +18,7 @@ import { readPersistedRoute } from "./route-artifact.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { readWorkState, writeWorkState } from "./work-state.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
+import { normalizeRequirements, classifyRequirement } from "./evidence-readiness.js";
 
 function artifactError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -114,6 +116,7 @@ export async function prepareCompletion({ target, packageRoot }) {
     contractFingerprint: contract.fingerprint,
     routeFingerprint: route.fingerprint,
     stateFingerprint: canonicalFingerprint(state),
+    verificationCycle: state.verificationCycle ?? 1,
     status: existingValue.status ?? "in-progress",
     taskStatus: existingValue.taskStatus ?? "in-progress",
     verificationStatus: existingValue.verificationStatus ?? "not-verified",
@@ -210,6 +213,27 @@ export async function recordCheck({
   }
   await assertExecutionPrerequisites({ target, state, packageRoot });
 
+  const contract = await readContract(target, packageRoot);
+  const route = await readPersistedRoute(target, packageRoot);
+  const preflight = await evaluatePreflight({ target, packageRoot });
+  const requiredEvidence = await requiredEvidenceForTarget({
+    target,
+    contract,
+    route,
+    packageRoot,
+    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+  });
+  const requested = normalizeRequirements(requiredEvidence).find((item) => (
+    item.id === requirement || item.text === requirement
+  ));
+  if (requested?.terminalOwned && status === "passed" && evidenceKind === "OBSERVED") {
+    throw artifactError(
+      "E_FUTURE_LIFECYCLE_EVIDENCE",
+      `Terminal-owned requirement cannot be recorded before its authoritative result: ${requested.text}`,
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.events],
+    );
+  }
+
   const existingReceipt = await readCurrentReceipt(target, packageRoot);
   await validateReceipt(existingReceipt.value, packageRoot);
   const source = command?.trim() || `check:${id}`;
@@ -221,32 +245,28 @@ export async function recordCheck({
     status,
     evidenceKind,
     source,
+    timestamp: new Date().toISOString(),
     ...(exitCode === undefined ? {} : { exitCode }),
     details: {
       ...(command === undefined ? {} : { command }),
       ...(result === undefined ? {} : { result }),
       ...(details === undefined ? {} : details),
+      verificationCycle: state.verificationCycle ?? 1,
     },
   });
   const evidence = createEvidence({
     kind: evidenceKind,
     source,
     result: recordedResult,
-    ...(details === undefined ? {} : { details: structuredClone(details) }),
+    verificationCycle: state.verificationCycle ?? 1,
+    details: {
+      ...(details === undefined ? {} : structuredClone(details)),
+      verificationCycle: state.verificationCycle ?? 1,
+    },
   });
 
   const checks = mergeByCheckId(existingReceipt.value.checks ?? [], check);
   const evidenceList = appendUniqueEvidence(existingReceipt.value.evidence ?? [], evidence);
-  const contract = await readContract(target, packageRoot);
-  const route = await readPersistedRoute(target, packageRoot);
-  const preflight = await evaluatePreflight({ target, packageRoot });
-  const requiredEvidence = await requiredEvidenceForTarget({
-    target,
-    contract,
-    route,
-    packageRoot,
-    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
-  });
   assertCompletionRelationships({
     contract,
     route,
@@ -281,6 +301,7 @@ export async function recordCheck({
     evidence: evidenceList,
     evidenceCoverage: coverage,
     stateFingerprint: canonicalFingerprint(nextState),
+    verificationCycle: state.verificationCycle ?? 1,
   }, packageRoot);
 
   assertCompletionRelationships({
@@ -308,6 +329,7 @@ export async function recordCheck({
       requirement: check.requirement,
       status: check.status,
       evidenceKind: check.evidenceKind,
+      verificationCycle: state.verificationCycle ?? 1,
     },
   }, packageRoot);
   return {
@@ -319,3 +341,236 @@ export async function recordCheck({
     event,
   };
 }
+
+export async function recordTerminalResult({
+  target,
+  packageRoot,
+  requirement,
+  type,
+  status,
+  source,
+  result,
+  details = {},
+} = {}) {
+  if (!target || !requirement || !type || !status || !source || !result) {
+    throw artifactError("E_CHECK_INVALID", "record-terminal-result requires target, requirement, type, status, source, and result", [ARTIFACT_PATHS.state]);
+  }
+  if (!["PUBLICATION", "PRODUCTION_READINESS"].includes(type)) {
+    throw artifactError("E_FUTURE_TERMINAL_EVIDENCE", `record-terminal-result does not support type ${type}`, [ARTIFACT_PATHS.state]);
+  }
+  if (type === "PUBLICATION" && !["committed", "pushed", "published", "deployed"].includes(status)) {
+    throw artifactError("E_CHECK_INVALID", `Invalid publication status for record-terminal-result: ${status}`, [ARTIFACT_PATHS.state]);
+  }
+  if (type === "PRODUCTION_READINESS" && !["ready", "blocked"].includes(status)) {
+    throw artifactError("E_CHECK_INVALID", `Invalid production readiness status for record-terminal-result: ${status}`, [ARTIFACT_PATHS.state]);
+  }
+
+  const state = await readWorkState(target, packageRoot);
+  if (!state) throw artifactError("E_STATE_MISSING", "Work state is required before recording a terminal result", [ARTIFACT_PATHS.state]);
+  if (["COMPLETE", "BLOCKED"].includes(state.phase)) {
+    throw artifactError("E_PHASE_TRANSITION_INVALID", `Cannot record a terminal result in ${state.phase}`, [ARTIFACT_PATHS.state]);
+  }
+  await assertExecutionPrerequisites({ target, state, packageRoot });
+
+  const contract = await readContract(target, packageRoot);
+  const route = await readPersistedRoute(target, packageRoot);
+  const preflight = await evaluatePreflight({ target, packageRoot });
+  const requiredEvidence = await requiredEvidenceForTarget({
+    target,
+    contract,
+    route,
+    packageRoot,
+    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+  });
+
+  const normalized = normalizeRequirements(requiredEvidence);
+  const requested = normalized.find((item) => (
+    item.id === requirement || item.text === requirement
+  ));
+
+  if (!requested) {
+    throw artifactError(
+      "E_TERMINAL_REQUIREMENT_UNKNOWN",
+      `Terminal results must reference an existing canonical terminal requirement: ${requirement}`,
+      [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt],
+    );
+  }
+
+  if (!requested.terminalOwned) {
+    throw artifactError(
+      "E_TERMINAL_REQUIREMENT_NOT_TERMINAL",
+      `record-terminal-result may only target terminal-owned requirements; found ${requested.type}: ${requested.text}`,
+      [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt],
+    );
+  }
+
+  if (requested.type !== type) {
+    throw artifactError(
+      "E_TERMINAL_REQUIREMENT_TYPE_MISMATCH",
+      `Requirement ${requested.id} is ${requested.type}, not ${type}.`,
+      [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt],
+    );
+  }
+
+  const existingReceipt = await readCurrentReceipt(target, packageRoot);
+  await validateReceipt(existingReceipt.value, packageRoot);
+
+  if (type === "PUBLICATION") {
+    const rank = {
+      "not-published": 0,
+      "local-only": 1,
+      "committed": 2,
+      "pushed": 3,
+      "published": 4,
+    };
+    const prev = existingReceipt.value.publicationStatus ?? "not-published";
+    if (prev in rank && status in rank && rank[status] < rank[prev]) {
+      throw artifactError(
+        "E_TERMINAL_STATUS_REGRESSION",
+        `Publication status cannot regress from ${prev} to ${status}.`,
+        [ARTIFACT_PATHS.receipt],
+      );
+    }
+  }
+
+  const cycle = state.verificationCycle ?? 1;
+
+  // Idempotency check:
+  const isIdentical = (existingReceipt.value.evidence ?? []).some((item) => (
+    item.kind === "OBSERVED"
+    && item.source === source.trim()
+    && item.result === result.trim()
+    && (item.verificationCycle ?? 1) === cycle
+    && item.details?.requirementId === requested.id
+    && item.details?.terminalType === type
+    && item.details?.terminalStatus === status
+  ));
+
+  if (isIdentical) {
+    const ledger = await validateEventLedger(target, packageRoot);
+    const matchingEvent = ledger.events.find((event) => (
+      event.taskId === state.taskId
+      && event.event === "TERMINAL_RESULT_RECORDED"
+      && event.details?.requirementId === requested.id
+      && event.details?.type === type
+      && event.details?.status === status
+      && event.details?.verificationCycle === cycle
+      && event.details?.source === source.trim()
+      && event.details?.result === result.trim()
+    ));
+
+    if (matchingEvent) {
+      return {
+        path: path.join(target, ARTIFACT_PATHS.receipt),
+        receipt: existingReceipt.value,
+        requirementId: requested.id,
+        type,
+        status,
+        idempotent: true,
+        repaired: false,
+        event: matchingEvent,
+      };
+    }
+
+    const repairedEvent = await appendProtocolEvent(target, {
+      taskId: state.taskId,
+      event: "TERMINAL_RESULT_RECORDED",
+      details: {
+        requirementId: requested.id,
+        type,
+        status,
+        verificationCycle: cycle,
+        source: source.trim(),
+        result: result.trim(),
+      },
+    }, packageRoot);
+
+    return {
+      path: path.join(target, ARTIFACT_PATHS.receipt),
+      receipt: existingReceipt.value,
+      requirementId: requested.id,
+      type,
+      status,
+      idempotent: true,
+      repaired: true,
+      event: repairedEvent,
+    };
+  }
+
+  const terminalEvidence = createEvidence({
+    kind: "OBSERVED",
+    source: source.trim(),
+    result: result.trim(),
+    verificationCycle: cycle,
+    details: {
+      requirementId: requested.id,
+      requirementText: requested.text,
+      terminalType: type,
+      terminalStatus: status,
+      ...(details === undefined ? {} : structuredClone(details)),
+      verificationCycle: cycle,
+    },
+  });
+
+  const evidenceList = appendUniqueEvidence(existingReceipt.value.evidence ?? [], terminalEvidence);
+  const nextState = {
+    ...state,
+    verificationEvidence: evidenceList,
+    lastUpdated: new Date().toISOString(),
+  };
+
+  const receiptUpdates = {
+    ...existingReceipt.value,
+    evidence: evidenceList,
+    verificationCycle: cycle,
+  };
+
+  if (type === "PUBLICATION") {
+    receiptUpdates.publicationStatus = status;
+    receiptUpdates.publication = {
+      ...(existingReceipt.value.publication ?? {}),
+      committed: status === "committed" || (existingReceipt.value.publication?.committed ?? false),
+      pushed: status === "pushed" || (existingReceipt.value.publication?.pushed ?? false),
+      deployed: status === "deployed" || (existingReceipt.value.publication?.deployed ?? false),
+    };
+  } else if (type === "PRODUCTION_READINESS") {
+    receiptUpdates.productionReadiness = status;
+  }
+
+  const nextReceipt = await createReceipt({
+    ...receiptUpdates,
+    stateFingerprint: canonicalFingerprint(nextState),
+  }, packageRoot);
+
+  await writeWorkState(target, nextState, { packageRoot });
+  await writeJsonArtifact(
+    target,
+    ARTIFACT_PATHS.receipt,
+    nextReceipt,
+    "execution-receipt",
+    packageRoot,
+  );
+
+  const event = await appendProtocolEvent(target, {
+    taskId: state.taskId,
+    event: "TERMINAL_RESULT_RECORDED",
+    details: {
+      requirementId: requested.id,
+      type,
+      status,
+      verificationCycle: cycle,
+      source: source.trim(),
+      result: result.trim(),
+    },
+  }, packageRoot);
+
+  return {
+    path: path.join(target, ARTIFACT_PATHS.receipt),
+    receipt: nextReceipt,
+    requirementId: requested.id,
+    type,
+    status,
+    evidence: terminalEvidence,
+    event,
+  };
+}

package/src/core/completion-recovery.js

@@ -0,0 +1,15 @@
+export const RECOVERABLE_COMPLETION_EVIDENCE_CODES = Object.freeze([
+  "E_EVIDENCE_REQUIRED",
+  "E_EVIDENCE_PARTIAL",
+  "E_EVIDENCE_INVALID",
+  "E_EVIDENCE_KIND_INVALID",
+  "E_EVIDENCE_COVERAGE_PARTIAL",
+  "E_EVIDENCE_COVERAGE_INVALID",
+  "E_VERIFICATION_CHECK_REQUIRED",
+  "E_CHECK_REQUIRED",
+  "E_CHECK_INVALID",
+]);
+
+export function isRecoverableCompletionEvidenceCode(code) {
+  return typeof code === "string" && RECOVERABLE_COMPLETION_EVIDENCE_CODES.includes(code);
+}

package/src/core/completion-relationships.js

@@ -1,10 +1,11 @@
 import { ARTIFACT_PATHS, canonicalFingerprint } from "./artifacts.js";
-import { assertCheckList, requiredChecksSatisfiedForRequirements } from "./checks.js";
+import { assertCheckList } from "./checks.js";
 import { assertCoverageList, coverageForRequirements } from "./coverage.js";
 import { assertEvidenceList } from "./evidence.js";
+import { evaluateRequiredEvidence } from "./evidence-readiness.js";
 
-function issue(code, message, artifacts = []) {
-  return { code, message, artifacts };
+function issue(code, message, artifacts = [], details = {}) {
+  return { code, message, artifacts, ...details };
 }
 
 function sameValue(left, right) {
@@ -86,8 +87,15 @@ export function completionRelationshipErrors({
     addAssertion(errors, () => assertCheckList(receipt.checks, "receipt.checks"), "E_CHECK_INVALID", [ARTIFACT_PATHS.receipt]);
     addAssertion(errors, () => assertEvidenceList(receipt.evidence ?? [], "receipt.evidence"), "E_EVIDENCE_INVALID", [ARTIFACT_PATHS.receipt]);
     if (requireRequiredChecks) {
-      for (const error of requiredChecksSatisfiedForRequirements(receipt.checks, requiredEvidence)) {
-        errors.push(issue(error.code, error.message, [ARTIFACT_PATHS.receipt]));
+      const readiness = evaluateRequiredEvidence({ requirements: requiredEvidence, checks: receipt.checks });
+      for (const requirement of readiness.missing) {
+        errors.push(issue("E_EVIDENCE_REQUIRED", `Required check is missing: ${requirement.text}`, [ARTIFACT_PATHS.receipt], { requirementId: requirement.id }));
+      }
+      for (const requirement of readiness.partial) {
+        errors.push(issue("E_EVIDENCE_PARTIAL", `Required evidence is partial: ${requirement.text}`, [ARTIFACT_PATHS.receipt], { requirementId: requirement.id }));
+      }
+      for (const requirement of readiness.invalid) {
+        errors.push(issue(requirement.reasonCode ?? "E_EVIDENCE_INVALID", `Required evidence is invalid: ${requirement.text}`, [ARTIFACT_PATHS.receipt], { requirementId: requirement.id }));
       }
     }
   }
@@ -111,10 +119,16 @@ export function completionRelationshipErrors({
   }
 
   if (state && receipt) {
-    if (requireReceiptStateFingerprint && receipt.stateFingerprint === undefined) {
-      errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Execution receipt requires the current work-state fingerprint", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
-    } else if (receipt.stateFingerprint !== undefined && receipt.stateFingerprint !== canonicalFingerprint(state)) {
-      errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Execution receipt does not match the recorded work state", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+    if (state.verificationCycle !== undefined && receipt.verificationCycle !== undefined
+      && state.verificationCycle !== receipt.verificationCycle) {
+      errors.push(issue("E_RECEIPT_CYCLE_MISMATCH", "Work state and execution receipt verification cycles diverge", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+    }
+    if (requireReceiptStateFingerprint) {
+      if (receipt.stateFingerprint === undefined) {
+        errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Execution receipt requires the current work-state fingerprint", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+      } else if (receipt.stateFingerprint !== canonicalFingerprint(state)) {
+        errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Execution receipt does not match the recorded work state", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+      }
     }
     if (!sameValue(state.checks, receipt.checks)) {
       errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Work state and execution receipt checks diverge", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));