@cassiomc1/forgeloop 0.1.1 → 0.1.2

package/src/core/completion-artifacts.js

@@ -0,0 +1,281 @@
+import {
+  ARTIFACT_PATHS,
+  canonicalFingerprint,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { appendProtocolEvent } 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 { 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";
+
+function artifactError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function requiredString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw artifactError("E_CHECK_INVALID", `${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+async function readCurrentReceipt(target, packageRoot) {
+  try {
+    return await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") {
+      throw artifactError(
+        "E_RECEIPT_MISSING",
+        "Execution receipt is missing; run forgeloop prepare-completion first",
+        [ARTIFACT_PATHS.receipt],
+      );
+    }
+    throw error;
+  }
+}
+
+async function readOptionalConfig(target, packageRoot) {
+  try {
+    return (await readJsonArtifact(target, ARTIFACT_PATHS.config, "config", packageRoot)).value;
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return {};
+    throw error;
+  }
+}
+
+export async function requiredEvidenceForTarget({ target, contract, route, packageRoot, additionalEvidence = [] }) {
+  const config = await readOptionalConfig(target, packageRoot);
+  const guideEvidence = await completionEvidenceForGuides(route.value.guides, packageRoot);
+  return [...new Set([
+    ...(contract.value.successCriteria ?? []),
+    ...guideEvidence,
+    ...(config.requiredEvidence ?? []),
+    ...additionalEvidence,
+  ])].sort();
+}
+
+export async function prepareCompletion({ target, packageRoot }) {
+  const contract = await readContract(target, packageRoot);
+  const route = await readPersistedRoute(target, packageRoot);
+  const state = await readWorkState(target, packageRoot);
+  if (!state) {
+    throw artifactError("E_STATE_MISSING", "Work state is required before preparing completion", [ARTIFACT_PATHS.state]);
+  }
+
+  let existing = null;
+  try {
+    existing = await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+    await validateReceipt(existing.value, packageRoot);
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+
+  const preflight = await evaluatePreflight({ target, packageRoot });
+  const requiredEvidence = await requiredEvidenceForTarget({
+    target,
+    contract,
+    route,
+    packageRoot,
+    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+  });
+  const existingValue = existing?.value ?? {};
+  const changedPaths = existing
+    ? [...(existingValue.changedPaths ?? [])]
+    : (await currentChangedPaths(target) ?? []);
+  const checks = [...(existingValue.checks ?? [])];
+  const receipt = await createReceipt({
+    ...existingValue,
+    taskId: contract.value.taskId,
+    contractFingerprint: contract.fingerprint,
+    routeFingerprint: route.fingerprint,
+    ...(Object.hasOwn(existingValue, "stateFingerprint")
+      ? { stateFingerprint: canonicalFingerprint(state) }
+      : {}),
+    status: existingValue.status ?? "in-progress",
+    taskStatus: existingValue.taskStatus ?? "in-progress",
+    verificationStatus: existingValue.verificationStatus ?? "not-verified",
+    publicationStatus: existingValue.publicationStatus ?? "local-only",
+    productionReadiness: existingValue.productionReadiness ?? "not-verified",
+    selectedGuides: [...route.value.guides],
+    changedPaths,
+    checks,
+    evidence: [...(existingValue.evidence ?? [])],
+    evidenceCoverage: coverageForRequirements(requiredEvidence, checks),
+    review: existingValue.review ?? { status: "not-run", independent: false },
+    limitations: [...(existingValue.limitations ?? [])],
+    publication: existingValue.publication ?? {
+      committed: false,
+      pushed: false,
+      pullRequest: null,
+      deployed: false,
+    },
+  }, packageRoot);
+  const written = await writeJsonArtifact(
+    target,
+    ARTIFACT_PATHS.receipt,
+    receipt,
+    "execution-receipt",
+    packageRoot,
+  );
+  return {
+    path: written.path,
+    receipt: written.value,
+    requiredEvidence,
+    changedPaths,
+  };
+}
+
+function mergeByCheckId(checks, nextCheck) {
+  const next = [...checks];
+  const index = next.findIndex((item) => item?.schemaVersion === 1 && item.id === nextCheck.id);
+  if (index >= 0) next[index] = nextCheck;
+  else next.push(nextCheck);
+  return next;
+}
+
+function appendUniqueEvidence(evidence, nextEvidence) {
+  const exists = evidence.some((item) => item.kind === nextEvidence.kind
+    && item.source === nextEvidence.source
+    && item.result === nextEvidence.result
+    && JSON.stringify(item.details ?? null) === JSON.stringify(nextEvidence.details ?? null));
+  return exists ? [...evidence] : [...evidence, nextEvidence];
+}
+
+export async function recordCheck({
+  target,
+  packageRoot,
+  id,
+  kind = "command",
+  requirement,
+  status,
+  evidenceKind,
+  command,
+  result,
+  exitCode,
+  details,
+}) {
+  requiredString(id, "check id");
+  requiredString(kind, "check kind");
+  requiredString(requirement, "check requirement");
+  requiredString(status, "check status");
+  requiredString(evidenceKind, "evidence kind");
+  if (command !== undefined && typeof command !== "string") {
+    throw artifactError("E_CHECK_INVALID", "command must be a string when supplied");
+  }
+  if (result !== undefined && typeof result !== "string") {
+    throw artifactError("E_CHECK_INVALID", "result must be a string when supplied");
+  }
+  if (details !== undefined && (!details || typeof details !== "object" || Array.isArray(details))) {
+    throw artifactError("E_CHECK_INVALID", "check details must be a JSON object");
+  }
+  if ((typeof command !== "string" || command.trim() === "")
+    && (typeof result !== "string" || result.trim() === "")) {
+    throw artifactError("E_CHECK_INVALID", "record-check requires --command or --result");
+  }
+
+  const state = await readWorkState(target, packageRoot);
+  if (!state) throw artifactError("E_STATE_MISSING", "Work state is required before recording a check", [ARTIFACT_PATHS.state]);
+  if (["COMPLETE", "BLOCKED"].includes(state.phase)) {
+    throw artifactError("E_PHASE_TRANSITION_INVALID", `Cannot record a check in ${state.phase}`, [ARTIFACT_PATHS.state]);
+  }
+  if (state.phase !== "VERIFYING") {
+    throw artifactError(
+      "E_PHASE_PREREQUISITE_MISSING",
+      `record-check requires VERIFYING before review; found ${state.phase}`,
+      [ARTIFACT_PATHS.state],
+    );
+  }
+
+  const existingReceipt = await readCurrentReceipt(target, packageRoot);
+  await validateReceipt(existingReceipt.value, packageRoot);
+  const source = command?.trim() || `check:${id}`;
+  const recordedResult = result?.trim() || `recorded command: ${command.trim()}`;
+  const check = createCheck({
+    id,
+    kind,
+    requirement,
+    status,
+    evidenceKind,
+    source,
+    ...(exitCode === undefined ? {} : { exitCode }),
+    details: {
+      ...(command === undefined ? {} : { command }),
+      ...(result === undefined ? {} : { result }),
+      ...(details === undefined ? {} : details),
+    },
+  });
+  const evidence = createEvidence({
+    kind: evidenceKind,
+    source,
+    result: recordedResult,
+    ...(details === undefined ? {} : { details: structuredClone(details) }),
+  });
+
+  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 ?? [],
+  });
+  const coverage = coverageForRequirements(requiredEvidence, checks);
+  const nextState = {
+    ...state,
+    checks,
+    verificationEvidence: appendUniqueEvidence(state.verificationEvidence ?? [], evidence),
+    evidenceCoverage: coverage,
+    lastUpdated: new Date().toISOString(),
+  };
+  const nextReceipt = await createReceipt({
+    ...existingReceipt.value,
+    checks,
+    evidence: evidenceList,
+    evidenceCoverage: coverage,
+    ...(Object.hasOwn(existingReceipt.value, "stateFingerprint")
+      ? { stateFingerprint: canonicalFingerprint(nextState) }
+      : {}),
+  }, packageRoot);
+
+  await writeWorkState(target, nextState, { packageRoot });
+  const written = await writeJsonArtifact(
+    target,
+    ARTIFACT_PATHS.receipt,
+    nextReceipt,
+    "execution-receipt",
+    packageRoot,
+  );
+  const event = await appendProtocolEvent(target, {
+    taskId: state.taskId,
+    event: "VERIFICATION_RECORDED",
+    details: {
+      checkId: check.id,
+      requirement: check.requirement,
+      status: check.status,
+      evidenceKind: check.evidenceKind,
+    },
+  }, packageRoot);
+  return {
+    path: written.path,
+    receipt: written.value,
+    check,
+    evidence,
+    coverage,
+    event,
+  };
+}

package/src/core/completion.js

@@ -0,0 +1,295 @@
+import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact } from "./artifacts.js";
+import { requiredEvidenceForTarget } from "./completion-artifacts.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { evaluatePreflight } from "./preflight.js";
+import { readContract } from "./contract.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { readWorkState, writeWorkState, classifyLoadedWorkState } from "./work-state.js";
+import { validateReceipt } from "./receipt.js";
+import { assertCheckList, requiredChecksSatisfied } from "./checks.js";
+import { assertCoverageList, coverageForRequirements } from "./coverage.js";
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+
+function issue(code, message, artifacts = [], details = {}) {
+  return { code, message, artifacts, ...details };
+}
+
+function repairNext(error) {
+  switch (error.code) {
+    case "E_RECEIPT_MISSING":
+      return "Run forgeloop prepare-completion after recording verification evidence.";
+    case "E_RECEIPT_INVALID":
+    case "E_RECEIPT_CONTRACT_MISMATCH":
+    case "E_RECEIPT_ROUTE_MISMATCH":
+    case "E_RECEIPT_STATE_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.";
+    case "E_PHASE_CHRONOLOGY_INVALID":
+      return "Record the missing lifecycle event through the normal phase transition or forgeloop record-check path.";
+    case "E_EVIDENCE_REQUIRED":
+    case "E_EVIDENCE_COVERAGE_INVALID":
+    case "E_EVIDENCE_COVERAGE_PARTIAL":
+    case "E_EVIDENCE_KIND_INVALID":
+    case "E_CHECK_INVALID":
+    case "E_CHECK_STATUS_CONTRADICTION":
+      return "Run forgeloop record-check with compatible observed evidence for the named requirement.";
+    case "E_GATE_UNVERIFIED":
+    case "E_GATE_STALE":
+      return "Satisfy or refresh the named gate, then rerun forgeloop preflight.";
+    case "E_PROFILE_UNVERIFIED":
+      return "Use Standard mode for a fresh target, or verify PROJECT_PROFILE.md before Strict completion.";
+    default:
+      return "Resolve this validator finding in the named artifact before retrying completion.";
+  }
+}
+
+function withRepairGuidance(error) {
+  const normalized = {
+    ...error,
+    code: error.code ?? "E_COMPLETION_REJECTED",
+    message: error.message ?? String(error),
+    artifacts: error.artifacts ?? [],
+  };
+  if (!normalized.next) normalized.next = repairNext(normalized);
+  return normalized;
+}
+
+function sortIssues(errors) {
+  const unique = [...new Map(errors.map((rawError) => {
+    const error = withRepairGuidance(rawError);
+    return [
+      `${error.code}\0${(error.artifacts ?? []).join("\0")}\0${error.message}`,
+      error,
+    ];
+  })).values()];
+  return unique.sort((left, right) => left.code.localeCompare(right.code)
+    || left.artifacts.join("\0").localeCompare(right.artifacts.join("\0"))
+    || left.message.localeCompare(right.message));
+}
+
+async function loadRequired(loader, code, message, artifacts, errors) {
+  try {
+    return await loader();
+  } catch (error) {
+    errors.push(issue(error.code === "ARTIFACT_MISSING" ? code : `${code.replace(/_MISSING$/, "")}_INVALID`, `${message}: ${error.message}`, artifacts));
+    return null;
+  }
+}
+
+function publicationStatus(receipt) {
+  if (receipt.publicationStatus) return receipt.publicationStatus;
+  if (receipt.publication?.deployed) return "deployed";
+  if (receipt.publication?.pushed) return "pushed";
+  if (receipt.publication?.committed) return "committed";
+  return receipt.changedPaths?.length > 0 ? "local-only" : "not-published";
+}
+
+async function validateLedger(target, taskId, state, errors, packageRoot) {
+  await assertSafePath(target, ARTIFACT_PATHS.events);
+  const eventsPath = ensureWithin(target, ARTIFACT_PATHS.events);
+  if (!(await fileExists(eventsPath))) {
+    errors.push(issue("E_PHASE_CHRONOLOGY_INVALID", "Protocol event ledger is required before completion", [ARTIFACT_PATHS.events]));
+    return { valid: false, events: [], errors: [] };
+  }
+  const ledger = await validateEventLedger(target, packageRoot);
+  for (const error of ledger.errors) errors.push({ ...error, artifacts: [ARTIFACT_PATHS.events] });
+  const requiredEvents = ["CONTRACT_VALIDATED", "ROUTE_VALIDATED", "PREFLIGHT_READY", "EXECUTION_STARTED", "VERIFICATION_RECORDED"];
+  const observed = new Set(ledger.events.filter((event) => event.taskId === taskId).map((event) => event.event));
+  for (const event of requiredEvents) {
+    if (!observed.has(event)) {
+      errors.push(issue("E_PHASE_CHRONOLOGY_INVALID", `Required protocol event is missing: ${event}`, [ARTIFACT_PATHS.events], { event }));
+    }
+  }
+  if (ledger.events.some((event) => event.taskId !== taskId)) {
+    errors.push(issue("E_PHASE_CHRONOLOGY_INVALID", "Protocol events must belong to the current task", [ARTIFACT_PATHS.events]));
+  }
+  if (state?.phase === "COMPLETE" && !observed.has("COMPLETION_VALIDATED")) {
+    errors.push(issue("E_PHASE_CHRONOLOGY_INVALID", "COMPLETE state requires COMPLETION_VALIDATED", [ARTIFACT_PATHS.events]));
+  }
+  return ledger;
+}
+
+export async function evaluateCompletion({ target, packageRoot, strict = false } = {}) {
+  const errors = [];
+  const preflight = await evaluatePreflight({ target, packageRoot, strict });
+  errors.push(...preflight.errors);
+  const contract = await loadRequired(
+    () => readContract(target, packageRoot),
+    "E_CONTRACT_MISSING",
+    "Current contract is not available",
+    [ARTIFACT_PATHS.contract],
+    errors,
+  );
+  const route = await loadRequired(
+    () => readPersistedRoute(target, packageRoot),
+    "E_ROUTE_MISSING",
+    "Persisted routing result is not available",
+    [ARTIFACT_PATHS.route],
+    errors,
+  );
+  const state = await loadRequired(
+    () => readWorkState(target, packageRoot).then((value) => {
+      if (!value) {
+        const error = new Error("Work state is missing");
+        error.code = "ARTIFACT_MISSING";
+        throw error;
+      }
+      return value;
+    }),
+    "E_STATE_MISSING",
+    "Work state is not available",
+    [ARTIFACT_PATHS.state],
+    errors,
+  );
+  const receipt = await loadRequired(
+    () => readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot),
+    "E_RECEIPT_MISSING",
+    "Execution receipt is not available",
+    [ARTIFACT_PATHS.receipt],
+    errors,
+  );
+
+  if (receipt) {
+    try {
+      await validateReceipt(receipt.value, packageRoot);
+    } catch (error) {
+      errors.push(issue(error.code ?? "E_RECEIPT_INVALID", `Execution receipt is invalid: ${error.message}`, [ARTIFACT_PATHS.receipt]));
+    }
+  }
+
+  if (contract && route && route.value.contractFingerprint !== undefined
+    && route.value.contractFingerprint !== contract.fingerprint) {
+    errors.push(issue("E_ROUTE_STALE", "Routing result does not match the current contract", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.contract]));
+  }
+  if (contract && state && state.contractFingerprint !== contract.fingerprint) {
+    errors.push(issue("E_CONTRACT_STALE", "Work state does not match the current contract", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract]));
+  }
+  if (route && state && JSON.stringify(route.value.guides) !== JSON.stringify(state.selectedGuides)) {
+    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "Work state guides do not match the persisted route", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.state]));
+  }
+  if (route && receipt && JSON.stringify(route.value.guides) !== JSON.stringify(receipt.value.selectedGuides)) {
+    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "Receipt guides do not match the persisted route", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.receipt]));
+  }
+  if (contract && receipt && receipt.value.contractFingerprint !== contract.fingerprint) {
+    errors.push(issue("E_RECEIPT_CONTRACT_MISMATCH", "Receipt does not match the current contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt]));
+  }
+  if (route && receipt && receipt.value.routeFingerprint !== undefined && receipt.value.routeFingerprint !== route.fingerprint) {
+    errors.push(issue("E_RECEIPT_ROUTE_MISMATCH", "Receipt does not match the persisted route", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.receipt]));
+  }
+  if (state && receipt && receipt.value.stateFingerprint !== undefined && receipt.value.stateFingerprint !== canonicalFingerprint(state)) {
+    errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Receipt does not match the recorded work state", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
+  }
+  if (state && !["REVIEWING", "COMPLETE"].includes(state.phase)) {
+    errors.push(issue("E_PHASE_PREREQUISITE_MISSING", `Completion requires REVIEWING or COMPLETE state, found ${state.phase}`, [ARTIFACT_PATHS.state]));
+  }
+
+  let coverage = [];
+  if (receipt && contract && route) {
+    const requiredEvidence = await requiredEvidenceForTarget({
+      target,
+      contract,
+      route,
+      packageRoot,
+      additionalEvidence: preflight?.policy?.requiredEvidence ?? [],
+    });
+    coverage = receipt.value.evidenceCoverage
+      ? receipt.value.evidenceCoverage
+      : coverageForRequirements(requiredEvidence, receipt.value.checks);
+    try {
+      assertCoverageList(coverage);
+    } catch (error) {
+      errors.push(issue(error.code ?? "E_EVIDENCE_COVERAGE_PARTIAL", error.message, [ARTIFACT_PATHS.receipt]));
+    }
+    const byRequirement = new Map(coverage.map((item) => [item.requirement, item]));
+    for (const requirement of requiredEvidence) {
+      const item = byRequirement.get(requirement);
+      if (!item) {
+        errors.push(issue("E_EVIDENCE_REQUIRED", `Evidence coverage is missing: ${requirement}`, [ARTIFACT_PATHS.receipt], { requirement }));
+      } else if (item.status !== "COVERED") {
+        errors.push(issue(
+          item.status === "BLOCKED" ? "E_EVIDENCE_COVERAGE_PARTIAL" : "E_EVIDENCE_COVERAGE_PARTIAL",
+          `Evidence coverage is ${item.status}: ${requirement}`,
+          [ARTIFACT_PATHS.receipt],
+          { requirement, status: item.status },
+        ));
+      }
+    }
+    const structuredChecks = receipt.value.checks.filter((check) => check?.schemaVersion === 1 || check?.id !== undefined || check?.evidenceKind !== undefined);
+    if (structuredChecks.length > 0) {
+      try {
+        assertCheckList(structuredChecks, "receipt.checks");
+        errors.push(...requiredChecksSatisfied(structuredChecks, requiredEvidence));
+      } catch (error) {
+        errors.push(issue(error.code ?? "E_CHECK_INVALID", error.message, [ARTIFACT_PATHS.receipt]));
+      }
+    }
+  }
+
+  const ledger = contract && state
+    ? await validateLedger(target, contract.value.taskId, state, errors, packageRoot)
+    : { valid: false, events: [], errors: [] };
+
+  if (state) {
+    try {
+      const classification = await classifyLoadedWorkState({
+        target,
+        state,
+        contractFile: ARTIFACT_PATHS.contract,
+      });
+      if (classification.status === "REVALIDATION_REQUIRED") {
+        for (const reason of classification.reasons) {
+          errors.push(issue(reason === "CONTRACT_CHANGED" ? "E_CONTRACT_STALE" : "E_PHASE_ARTIFACT_STALE", `State freshness check failed: ${reason}`, [ARTIFACT_PATHS.state]));
+        }
+      }
+    } catch (error) {
+      errors.push(issue("E_PHASE_ARTIFACT_STALE", error.message, [ARTIFACT_PATHS.state]));
+    }
+  }
+
+  const sortedErrors = sortIssues(errors);
+  const receiptValue = receipt?.value;
+  const publication = receiptValue ? publicationStatus(receiptValue) : "not-published";
+  const valid = sortedErrors.length === 0;
+  return {
+    status: valid ? "VALID" : "REJECTED",
+    taskStatus: valid ? "COMPLETE" : receiptValue?.status === "blocked" ? "BLOCKED" : "INCOMPLETE",
+    verificationStatus: valid ? "VALID" : "invalid",
+    publicationStatus: publication,
+    productionReadiness: receiptValue?.productionReadiness ?? "not-verified",
+    errors: sortedErrors,
+    warnings: [],
+    preflight,
+    coverage,
+    ledger: {
+      status: ledger.valid ? "valid" : "invalid",
+      events: ledger.events.length,
+    },
+  };
+}
+
+export async function runComplete({ target, packageRoot, strict = false, persist = true } = {}) {
+  const result = await evaluateCompletion({ target, packageRoot, strict });
+  if (persist && result.status === "VALID") {
+    const state = await readWorkState(target, packageRoot);
+    if (state && state.phase !== "COMPLETE") {
+      const receipt = await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+      const next = {
+        ...state,
+        previousPhase: state.phase,
+        phase: "COMPLETE",
+        evidenceCoverage: result.coverage,
+        verificationEvidence: receipt.value.evidence,
+        publicationStatus: result.publicationStatus,
+        lastUpdated: new Date().toISOString(),
+      };
+      await writeWorkState(target, next, { packageRoot });
+    }
+    const contract = await readContract(target, packageRoot);
+    const ledger = await validateEventLedger(target, packageRoot);
+    if (!ledger.events.some((event) => event.event === "COMPLETION_VALIDATED")) {
+      await appendProtocolEvent(target, { taskId: contract.value.taskId, event: "COMPLETION_VALIDATED" }, packageRoot);
+    }
+  }
+  return result;
+}

package/src/core/config.js

@@ -0,0 +1,35 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+
+export const CONFIG_SCHEMA_VERSION = 1;
+export const COMPLIANCE_MODES = Object.freeze(["advisory", "standard", "strict"]);
+
+function stringArray(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`);
+  }
+  return [...new Set(value)];
+}
+
+export function createConfig(input = {}) {
+  const complianceMode = input.complianceMode ?? "standard";
+  if (!COMPLIANCE_MODES.includes(complianceMode)) {
+    throw new Error(`Unknown compliance mode: ${complianceMode}`);
+  }
+  return {
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    complianceMode,
+    ...(input.policy !== undefined ? { policy: input.policy } : {}),
+    ...(input.requiredGates !== undefined ? { requiredGates: stringArray(input.requiredGates, "requiredGates") } : {}),
+    ...(input.requiredEvidence !== undefined ? { requiredEvidence: stringArray(input.requiredEvidence, "requiredEvidence") } : {}),
+  };
+}
+
+export async function readConfig(target, packageRoot) {
+  return (await readJsonArtifact(target, ARTIFACT_PATHS.config, "config", packageRoot)).value;
+}
+
+export async function writeConfig(target, config, packageRoot, options = {}) {
+  return writeJsonArtifact(target, ARTIFACT_PATHS.config, config, "config", packageRoot, options);
+}

package/src/core/conformance.js

@@ -1,5 +1,6 @@
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { createEvidence } from "./evidence.js";
+import { canonicalFingerprint } from "./artifacts.js";
 
 function error(code, message, artifacts = []) {
   return { code, message, artifacts };
@@ -51,6 +52,12 @@ export function validateTaskArtifactSet({
   if (route && state && JSON.stringify(route.guides) !== JSON.stringify(state.selectedGuides)) {
     errors.push(error("ROUTE_STATE_GUIDES_MISMATCH", "work-state.selectedGuides must equal routing-result.guides", ["route", "state"]));
   }
+  if (route && state && state.routeFingerprint !== undefined && state.routeFingerprint !== canonicalFingerprint(route)) {
+    errors.push(error("ROUTE_STATE_FINGERPRINT_MISMATCH", "work-state.routeFingerprint must match routing-result", ["route", "state"]));
+  }
+  if (route && receipt && receipt.routeFingerprint !== undefined && receipt.routeFingerprint !== canonicalFingerprint(route)) {
+    errors.push(error("STATE_RECEIPT_ROUTE_MISMATCH", "execution-receipt.routeFingerprint must match routing-result", ["route", "receipt"]));
+  }
   if (state && receipt && JSON.stringify(state.selectedGuides) !== JSON.stringify(receipt.selectedGuides)) {
     errors.push(error("STATE_RECEIPT_GUIDES_MISMATCH", "execution-receipt.selectedGuides must equal work-state.selectedGuides", ["state", "receipt"]));
   }