@cassiomc1/forgeloop 0.1.2 → 0.1.3

package/.cursor/rules/project-loop.mdc

@@ -14,6 +14,11 @@ alwaysApply: true
 7. Diagnose failures before fixing them and do not repeat an attempt without new evidence.
 8. Request authority for unrelated external or destructive actions, installations, and publications. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
 9. After implementation begins, do not return a final result in `EXECUTING`: follow `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`; otherwise report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
+
+After implementation work for the current task is complete, run `forgeloop next`
+before returning a final result. Follow the returned lifecycle action until
+ForgeLoop reaches a terminal state or an explicit blocker.
+
 10. Report only demonstrated results and checks.
 
 Do not stop for non-blocking missing product details. When a safe, reversible

package/.github/copilot-instructions.md

@@ -12,6 +12,11 @@ directory or file rules.
 - Diagnose the cause before fixing a failure; do not make random attempts.
 - Do not install unrelated software, publish, delete, migrate, or alter external state without authority. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
 - After implementation begins, do not return a final result in `EXECUTING`: follow `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`; otherwise report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
+
+After implementation work for the current task is complete, run `forgeloop next`
+before returning a final result. Follow the returned lifecycle action until
+ForgeLoop reaches a terminal state or an explicit blocker.
+
 - Report the result, checks actually run, limitations, and publication state.
 
 Do not stop for non-blocking missing product details. When a safe, reversible

package/AGENTS.md

@@ -14,7 +14,11 @@ specific rule overrides them.
 9. Before implementation, create/validate `.forgeloop/current-contract.json`, persist deterministic routing, satisfy mandatory gates, and require `forgeloop preflight` to return `READY`.
 10. Before claiming `COMPLETE`, require `forgeloop complete` to return `VALID`; otherwise report completion as not protocol-verified.
 11. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING`, record structured evidence, reach `REVIEWING`, prepare/update the execution receipt, and require `forgeloop complete` to return `VALID`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
-12. Finish with the result, checks actually run, limitations, and publication state.
+
+12. After implementation work for the current task is complete, run `forgeloop next`
+before returning a final result. Follow the returned lifecycle action until
+ForgeLoop reaches a terminal state or an explicit blocker.
+13. Finish with the result, checks actually run, limitations, and publication state.
 
 Do not stop for non-blocking missing product details. When a safe, reversible
 local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for

package/CLAUDE.md

@@ -10,7 +10,11 @@ When working in this repository:
 6. Investigate the root cause of a failure before fixing it.
 7. Request authority for unrelated installation, publication, deletion, migration, or another external or destructive action. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
 8. After implementation begins, do not return a final result in `EXECUTING`: follow `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`; otherwise report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
-9. Report current evidence, limitations, and publication state without claiming checks that were not run.
+
+9. After implementation work for the current task is complete, run `forgeloop next`
+before returning a final result. Follow the returned lifecycle action until
+ForgeLoop reaches a terminal state or an explicit blocker.
+10. Report current evidence, limitations, and publication state without claiming checks that were not run.
 
 Do not stop for non-blocking missing product details. When a safe, reversible
 local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for

package/LOOP_ENGINEERING.md

@@ -72,20 +72,44 @@ Implementation finished is not task finished, and tests executed are not the
 same as verification recorded. After implementation begins, do not stop or
 return the final result while the ForgeLoop task remains in `EXECUTING`.
 
+ACT → QUERY NEXT → ACT → QUERY NEXT → … → TERMINAL
+
+At each lifecycle boundary, query persisted state with `forgeloop next` before
+choosing the next action. Always query after implementation, verification,
+correction, and review. The query is advisory and read-only; the host agent
+runs checks and applies the returned legal transition or repair action.
+
 ```text
 POST-IMPLEMENTATION CLOSURE
 
 EXECUTING
-    ↓ advance
-VERIFYING
-    ↓ run checks and record structured evidence
-REVIEWING
-    ↓ prepare/update the execution receipt
-forgeloop complete
+    ↓ forgeloop next
+advance --to VERIFYING
+    ↓ forgeloop next
+prepare-completion
+    ↓
+run applicable project checks
+    ↓
+record observed results with record-check
+    ↓ forgeloop next
+advance --to REVIEWING
+    ↓ forgeloop next
+complete
     ↓ VALID
 COMPLETE
 ```
 
+`prepare-completion` creates or refreshes the in-progress execution receipt.
+It does not claim completion. The receipt is the structured container used by
+subsequent `record-check` operations; completion remains invalid until required
+observed evidence, review state, chronology, and validator requirements are
+satisfied.
+
+The host agent runs applicable checks after the receipt exists, records their
+observed results with `record-check`, and queries `forgeloop next` before each
+subsequent lifecycle action. `record-check` records results already observed by
+the agent; it never executes the supplied command text.
+
 Continue until the terminal outcome is either validator-backed `COMPLETE` or
 an explicitly reported `BLOCKED` / `PARTIALLY VERIFIED` result with exact
 unresolved findings. Record verification evidence before review. If a required

package/QUALITY_SCORECARD.md

@@ -15,6 +15,8 @@ policy are all present.
 | Portability | Node 20/22/24 Linux depth, OS smoke coverage, path/line-ending fixtures, and adapter compatibility evidence. |
 | Observability | `inspect`/`status`/`validate-protocol` shared derived state classification, real schema health, shared evidence, rich doctor findings, receipts, and no telemetry. |
 | Completion enforcement | Canonical contract, persisted route, guide-declared gates, preflight, phase ledger, structured checks, evidence coverage, `audit`, `report`, and `complete` validators. |
+| Agent lifecycle navigation | Read-only `forgeloop next` decisions, stable action/reason output, persisted-state safety, and adapter guidance at lifecycle boundaries. |
+| Execution → Verification handoff | Legal `EXECUTING` → `VERIFYING` transition, implementation-step reconciliation, and preservation of verification evidence. |
 | Pre-contract autonomy | Blocking vs Non-Blocking Decisions policy, explicit ASSUMPTION / source=agent-default recording, safe-boundary invariant, positive and negative tests, and a blind run showing non-blocking ambiguity continues while blocking ambiguity remains user-gated. |
 | Resume/checkpoint | Atomic local state, contract/HEAD/artifact freshness, age warning, schema/secret validation, status, safe validation, and bounded clearing without persisting derived freshness fields. |
 | Multi-agent coordination | Self-contained briefs, write/write and write/read ownership checks, dependency-set validation, reviewer independence, normalized results, and inline fallback. |
@@ -35,6 +37,16 @@ policy are all present.
 - Literal graph runtime and runtime multi-agent orchestration are `N/A by
   design`; compatible harnesses own those capabilities.
 
+## Third-run conformance position
+
+| Dimension | Classification |
+| --- | --- |
+| Execution → Verification | REPRODUCED FAILURE before this fix |
+| Verification serialization | NOT_REACHED |
+| Review transition | NOT_REACHED |
+| Receipt generation | NOT_REACHED |
+| Full conformance | PARTIAL |
+
 ## Evidence matrix
 
 The score is evidence-backed only when the contract and its executable proof

package/README.md

@@ -137,6 +137,8 @@ Protocol-support commands are local and do not invoke an agent or model:
 npx @cassiomc1/forgeloop route --work complete-website --surface ui --risk untrusted-input
 npx @cassiomc1/forgeloop activate
 npx @cassiomc1/forgeloop preflight --json
+npx @cassiomc1/forgeloop next
+npx @cassiomc1/forgeloop next --json
 npx @cassiomc1/forgeloop advance --to EXECUTING
 npx @cassiomc1/forgeloop advance --to VERIFYING
 npx @cassiomc1/forgeloop prepare-completion --json
@@ -155,6 +157,25 @@ npx @cassiomc1/forgeloop validate-receipt --file ./execution-receipt.json --json
 npx @cassiomc1/forgeloop validate-protocol --route-file ./routing-result.json --state-file .forgeloop/work-state.json --receipt-file ./execution-receipt.json --contract-file .forgeloop/current-contract.json --json
 ```
 
+The query-driven post-implementation path is:
+
+```text
+implementation
+→ forgeloop next
+→ advance --to VERIFYING
+→ forgeloop next
+→ prepare-completion
+→ forgeloop next
+→ checks + record-check
+→ forgeloop next
+→ advance --to REVIEWING
+→ forgeloop next
+→ complete
+```
+
+`forgeloop next` and `forgeloop next --json` read persisted state only. They do
+not run project checks or mutate protocol artifacts.
+
 `route` expands declared signals into deterministic guide IDs and reason codes.
 `activate` records a session marker without storing prompts or hidden reasoning.
 Before implementation, write the canonical contract, persist the route, create

package/conformance/README.md

@@ -8,6 +8,7 @@ Run a scenario in a disposable target using the Standard profile first:
 
 ```bash
 npx @cassiomc1/forgeloop preflight --json
+npx @cassiomc1/forgeloop next --json
 npx @cassiomc1/forgeloop audit --json
 npx @cassiomc1/forgeloop complete --json
 ```
@@ -15,12 +16,16 @@ npx @cassiomc1/forgeloop complete --json
 The expected post-implementation path is:
 
 ```text
-EXECUTING
+implementation
+→ forgeloop next
 → advance --to VERIFYING
+→ forgeloop next
 → prepare-completion
-→ record-check for each observed check
+→ forgeloop next
+→ checks + record-check
+→ forgeloop next
 → advance --to REVIEWING
-→ audit
+→ forgeloop next
 → complete
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Portable, verifiable instruction kit for AI agents and developers",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -24,12 +24,13 @@ 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 { 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|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|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");
@@ -51,7 +52,7 @@ function usage(command = null) {
   if (!command || command === "advance") {
     options.push("  --to <phase>        destination workflow phase");
   }
-  if (!command || ["activate", "advance", "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", "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)) {
@@ -132,7 +133,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", "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", "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") {
@@ -214,6 +215,10 @@ export function parseArgs(argv) {
       if (!id || id.startsWith("-")) throw new Error("--id requires a check ID");
       options.checkId = id;
       index += 1;
+    } else if (argument.startsWith("--id=")) {
+      const id = argument.slice("--id=".length);
+      if (!id || id.startsWith("-")) throw new Error("--id requires a check ID");
+      options.checkId = id;
     } else if (argument === "--kind") {
       const kind = argv[index + 1];
       if (!kind || kind.startsWith("-")) throw new Error("--kind requires a check kind");
@@ -224,6 +229,10 @@ export function parseArgs(argv) {
       if (!requirement || requirement.startsWith("-")) throw new Error("--requirement requires an evidence target");
       options.checkRequirement = requirement;
       index += 1;
+    } else if (argument.startsWith("--requirement=")) {
+      const requirement = argument.slice("--requirement=".length);
+      if (!requirement) throw new Error("--requirement requires an evidence target");
+      options.checkRequirement = requirement;
     } else if (argument === "--status") {
       const status = argv[index + 1];
       if (!status || status.startsWith("-")) throw new Error("--status requires a check status");
@@ -244,6 +253,10 @@ export function parseArgs(argv) {
       if (!resultText || resultText.startsWith("-")) throw new Error("--result requires recorded text");
       options.checkResult = resultText;
       index += 1;
+    } else if (argument.startsWith("--result=")) {
+      const resultText = argument.slice("--result=".length);
+      if (!resultText) throw new Error("--result requires recorded text");
+      options.checkResult = resultText;
     } else if (argument === "--exit-code") {
       const exitCode = argv[index + 1];
       if (!exitCode || exitCode.startsWith("-")) throw new Error("--exit-code requires a non-negative integer");
@@ -282,7 +295,7 @@ export function parseArgs(argv) {
 
   if (!command) return { command: null, options };
 
-  const jsonCommands = ["doctor", "route", "activate", "advance", "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", "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}`);
   }
@@ -436,6 +449,12 @@ export async function main(argv = process.argv.slice(2)) {
       return 0;
     }
 
+    if (command === "next") {
+      const result = await runNext({ target, packageRoot });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatNextActionResult(result));
+      return 0;
+    }
+
     if (command === "prepare-completion") {
       const result = await runPrepareCompletion({ target, packageRoot });
       console.log(options.json ? JSON.stringify(result, null, 2) : formatPrepareCompletionResult(result));
@@ -451,8 +470,8 @@ export async function main(argv = process.argv.slice(2)) {
         requirement: options.checkRequirement,
         status: options.checkStatus,
         evidenceKind: options.checkEvidenceKind,
-        command: options.checkCommand,
-        result: options.checkResult,
+        command: options.checkCommand ?? undefined,
+        result: options.checkResult ?? undefined,
         exitCode: options.checkExitCode,
         details: options.checkDetails ?? undefined,
       });

package/src/commands/next.js

@@ -0,0 +1,29 @@
+import { getNextAction } from "../core/next-action.js";
+
+export async function runNext({ target, packageRoot }) {
+  return getNextAction({ target, packageRoot });
+}
+
+export function formatNextActionResult(result) {
+  const lines = [
+    `FORGELOOP NEXT: ${result.nextAction}`,
+    `PHASE: ${result.currentPhase}`,
+  ];
+  if (result.reasons.length > 0) {
+    lines.push("REASONS:");
+    lines.push(...result.reasons.map((reason) => `- ${reason.code}: ${reason.message}`));
+  }
+  if (result.commands.length > 0) {
+    lines.push("COMMANDS (SAFE SYNOPSIS ONLY):");
+    lines.push(...result.commands.map((command) => `- ${command}`));
+  }
+  if (result.commandSpecs.length > 0) {
+    lines.push("STRUCTURED COMMAND SPECS: Available in --json output; direct-process argv data, not shell syntax.");
+  }
+  if (result.missingArtifacts.length > 0) {
+    lines.push("MISSING ARTIFACTS:");
+    lines.push(...result.missingArtifacts.map((artifact) => `- ${artifact}`));
+  }
+  if (result.terminal) lines.push("STATE: TERMINAL");
+  return `${lines.join("\n")}\n`;
+}

package/src/core/completion-artifacts.js

@@ -5,16 +5,18 @@ import {
   writeJsonArtifact,
 } from "./artifacts.js";
 import { readContract } from "./contract.js";
-import { appendProtocolEvent } from "./events.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
 import { completionEvidenceForGuides } from "./guide-metadata.js";
 import { createCheck } from "./checks.js";
 import { createEvidence } from "./evidence.js";
 import { coverageForRequirements } from "./coverage.js";
+import { assertCompletionRelationships } from "./completion-relationships.js";
 import { evaluatePreflight } from "./preflight.js";
 import { currentChangedPaths } from "./repository.js";
 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";
 
 function artifactError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -72,6 +74,9 @@ export async function prepareCompletion({ target, packageRoot }) {
   if (!state) {
     throw artifactError("E_STATE_MISSING", "Work state is required before preparing completion", [ARTIFACT_PATHS.state]);
   }
+  if (hasExecutionStarted(state.phase)) {
+    await assertExecutionPrerequisites({ target, state, packageRoot });
+  }
 
   let existing = null;
   try {
@@ -90,18 +95,25 @@ export async function prepareCompletion({ target, packageRoot }) {
     additionalEvidence: preflight.policy?.requiredEvidence ?? [],
   });
   const existingValue = existing?.value ?? {};
+  assertCompletionRelationships({
+    contract,
+    route,
+    state,
+    receipt: existingValue.taskId ? existingValue : null,
+    requiredEvidence,
+    requireRequiredChecks: false,
+  });
   const changedPaths = existing
     ? [...(existingValue.changedPaths ?? [])]
     : (await currentChangedPaths(target) ?? []);
-  const checks = [...(existingValue.checks ?? [])];
+  const checks = existing ? [...existingValue.checks] : [...state.checks];
+  const evidence = existing ? [...(existingValue.evidence ?? [])] : [...state.verificationEvidence];
   const receipt = await createReceipt({
     ...existingValue,
     taskId: contract.value.taskId,
     contractFingerprint: contract.fingerprint,
     routeFingerprint: route.fingerprint,
-    ...(Object.hasOwn(existingValue, "stateFingerprint")
-      ? { stateFingerprint: canonicalFingerprint(state) }
-      : {}),
+    stateFingerprint: canonicalFingerprint(state),
     status: existingValue.status ?? "in-progress",
     taskStatus: existingValue.taskStatus ?? "in-progress",
     verificationStatus: existingValue.verificationStatus ?? "not-verified",
@@ -110,7 +122,7 @@ export async function prepareCompletion({ target, packageRoot }) {
     selectedGuides: [...route.value.guides],
     changedPaths,
     checks,
-    evidence: [...(existingValue.evidence ?? [])],
+    evidence,
     evidenceCoverage: coverageForRequirements(requiredEvidence, checks),
     review: existingValue.review ?? { status: "not-run", independent: false },
     limitations: [...(existingValue.limitations ?? [])],
@@ -196,6 +208,7 @@ export async function recordCheck({
       [ARTIFACT_PATHS.state],
     );
   }
+  await assertExecutionPrerequisites({ target, state, packageRoot });
 
   const existingReceipt = await readCurrentReceipt(target, packageRoot);
   await validateReceipt(existingReceipt.value, packageRoot);
@@ -234,6 +247,26 @@ export async function recordCheck({
     packageRoot,
     additionalEvidence: preflight.policy?.requiredEvidence ?? [],
   });
+  assertCompletionRelationships({
+    contract,
+    route,
+    state,
+    receipt: existingReceipt.value,
+    requiredEvidence,
+    requireRequiredChecks: false,
+  });
+  const ledger = await validateEventLedger(target, packageRoot);
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    throw artifactError(first.code, first.message, [ARTIFACT_PATHS.events]);
+  }
+  if (!ledger.events.some((event) => event.taskId === state.taskId && event.event === "VERIFICATION_STARTED")) {
+    throw artifactError(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "record-check requires VERIFICATION_STARTED in the current task ledger",
+      [ARTIFACT_PATHS.events],
+    );
+  }
   const coverage = coverageForRequirements(requiredEvidence, checks);
   const nextState = {
     ...state,
@@ -247,11 +280,18 @@ export async function recordCheck({
     checks,
     evidence: evidenceList,
     evidenceCoverage: coverage,
-    ...(Object.hasOwn(existingReceipt.value, "stateFingerprint")
-      ? { stateFingerprint: canonicalFingerprint(nextState) }
-      : {}),
+    stateFingerprint: canonicalFingerprint(nextState),
   }, packageRoot);
 
+  assertCompletionRelationships({
+    contract,
+    route,
+    state: nextState,
+    receipt: nextReceipt,
+    requiredEvidence,
+    requireRequiredChecks: false,
+  });
+
   await writeWorkState(target, nextState, { packageRoot });
   const written = await writeJsonArtifact(
     target,

package/src/core/completion-relationships.js

@@ -0,0 +1,141 @@
+import { ARTIFACT_PATHS, canonicalFingerprint } from "./artifacts.js";
+import { assertCheckList, requiredChecksSatisfied } from "./checks.js";
+import { assertCoverageList, coverageForRequirements } from "./coverage.js";
+import { assertEvidenceList } from "./evidence.js";
+
+function issue(code, message, artifacts = []) {
+  return { code, message, artifacts };
+}
+
+function sameValue(left, right) {
+  return canonicalFingerprint(left) === canonicalFingerprint(right);
+}
+
+function addAssertion(errors, assertion, code, artifacts) {
+  try {
+    assertion();
+  } catch (error) {
+    errors.push(issue(code, error.message, artifacts));
+  }
+}
+
+export function stateIdentityErrors({
+  contract,
+  route,
+  state,
+} = {}) {
+  const errors = [];
+  const contractValue = contract?.value ?? contract;
+  const contractFingerprint = contract?.fingerprint;
+  if (contractValue && state && contractValue.taskId !== state.taskId) {
+    errors.push(issue("E_STATE_TASK_MISMATCH", "Work state does not belong to the current contract task", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.state]));
+  }
+  if (contractFingerprint && state && state.contractFingerprint !== contractFingerprint) {
+    errors.push(issue("E_CONTRACT_STALE", "Work state does not match the current contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.state]));
+  }
+  if (contractFingerprint && route && route.value.contractFingerprint !== contractFingerprint) {
+    errors.push(issue("E_ROUTE_STALE", "Routing result does not match the current contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.route]));
+  }
+  if (route && state && route.value.contractFingerprint !== undefined
+    && route.value.contractFingerprint !== state.contractFingerprint) {
+    errors.push(issue("E_ROUTE_STALE", "Routing result does not match the work state contract", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.state]));
+  }
+  if (route && state && (state.routeFingerprint !== route.fingerprint || !sameValue(state.selectedGuides, route.value.guides))) {
+    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "Work state does not match the persisted route identity", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.state]));
+  }
+  return errors;
+}
+
+export function assertStateIdentity(input) {
+  const errors = stateIdentityErrors(input);
+  if (errors.length === 0) return;
+  const first = errors[0];
+  const error = new Error(first.message);
+  error.code = first.code;
+  error.artifacts = first.artifacts;
+  throw error;
+}
+
+export function completionRelationshipErrors({
+  contract,
+  route,
+  state,
+  receipt,
+  requiredEvidence = [],
+  requireReceiptStateFingerprint = true,
+  requireRequiredChecks = true,
+} = {}) {
+  const errors = stateIdentityErrors({ contract, route, state });
+  const contractValue = contract?.value ?? contract;
+  const contractFingerprint = contract?.fingerprint;
+  if (contractValue && receipt && contractValue.taskId !== receipt.taskId) {
+    errors.push(issue("E_RECEIPT_TASK_MISMATCH", "Execution receipt does not belong to the current contract task", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt]));
+  }
+  if (route && receipt && (receipt.routeFingerprint !== route.fingerprint || !sameValue(receipt.selectedGuides, route.value.guides))) {
+    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "Execution receipt does not match the persisted route identity", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.receipt]));
+  }
+  if (contractFingerprint && receipt && receipt.contractFingerprint !== contractFingerprint) {
+    errors.push(issue("E_RECEIPT_CONTRACT_MISMATCH", "Execution receipt does not match the current contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt]));
+  }
+
+  if (state) {
+    addAssertion(errors, () => assertCheckList(state.checks, "work-state.checks"), "E_CHECK_INVALID", [ARTIFACT_PATHS.state]);
+    addAssertion(errors, () => assertEvidenceList(state.verificationEvidence, "work-state.verificationEvidence"), "E_EVIDENCE_INVALID", [ARTIFACT_PATHS.state]);
+  }
+  if (receipt) {
+    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 requiredChecksSatisfied(receipt.checks, requiredEvidence)) {
+        errors.push(issue(error.code, error.message, [ARTIFACT_PATHS.receipt]));
+      }
+    }
+  }
+
+  const expectedCoverage = state ? coverageForRequirements(requiredEvidence, state.checks) : [];
+  if (state?.evidenceCoverage !== undefined) {
+    addAssertion(errors, () => assertCoverageList(state.evidenceCoverage, "work-state.evidenceCoverage"), "E_EVIDENCE_COVERAGE_INVALID", [ARTIFACT_PATHS.state]);
+    if (!sameValue(state.evidenceCoverage, expectedCoverage)) {
+      errors.push(issue("E_EVIDENCE_COVERAGE_INVALID", "Work state evidence coverage does not match its checks", [ARTIFACT_PATHS.state]));
+    }
+  }
+  if (receipt) {
+    if (receipt.evidenceCoverage === undefined) {
+      errors.push(issue("E_EVIDENCE_COVERAGE_INVALID", "Execution receipt requires evidence coverage", [ARTIFACT_PATHS.receipt]));
+    } else {
+      addAssertion(errors, () => assertCoverageList(receipt.evidenceCoverage, "receipt.evidenceCoverage"), "E_EVIDENCE_COVERAGE_INVALID", [ARTIFACT_PATHS.receipt]);
+      if (!sameValue(receipt.evidenceCoverage, expectedCoverage)) {
+        errors.push(issue("E_EVIDENCE_COVERAGE_INVALID", "Execution receipt evidence coverage does not match current checks", [ARTIFACT_PATHS.receipt]));
+      }
+    }
+  }
+
+  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 (!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]));
+    }
+    if (!sameValue(state.verificationEvidence, receipt.evidence ?? [])) {
+      errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Work state and execution receipt evidence diverge", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+    }
+    if (state.evidenceCoverage !== undefined && receipt.evidenceCoverage !== undefined
+      && !sameValue(state.evidenceCoverage, receipt.evidenceCoverage)) {
+      errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Work state and execution receipt coverage diverge", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+    }
+  }
+  return errors;
+}
+
+export function assertCompletionRelationships(input) {
+  const errors = completionRelationshipErrors(input);
+  if (errors.length === 0) return;
+  const first = errors[0];
+  const error = new Error(first.message);
+  error.code = first.code;
+  error.artifacts = first.artifacts;
+  throw error;
+}