@cassiomc1/forgeloop 1.1.1 → 1.2.2

package/src/core/cli-command-definitions.js

@@ -1,5 +1,5 @@
 /**
- * Canonical, declarative definition of all 33 ForgeLoop CLI commands.
+ * Canonical, declarative definition of all 42 ForgeLoop CLI commands.
  * This is the machine source of truth for CLI option parsing, help text,
  * metadata, documentation generation, and conformance validation.
  *
@@ -64,7 +64,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mutation: "MUTATING",
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
-      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "show planned writes without changing files" }),
+      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "perform deterministic init planning and conflict detection without writing" }),
     }),
     writes: [".forgeloop/*", "AGENTS.md", "CLAUDE.md", ".cursor/rules/project-loop.mdc", ".github/copilot-instructions.md"],
     removes: [],
@@ -93,7 +93,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mutation: "MUTATING",
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
-      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "show planned writes without changing files" }),
+      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "perform deterministic update planning and conflict detection without writing" }),
     }),
     writes: [".forgeloop/*", "AGENTS.md", "CLAUDE.md", ".cursor/rules/project-loop.mdc", ".github/copilot-instructions.md"],
     removes: [],
@@ -317,6 +317,55 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Records external terminal result evidence (PUBLICATION or PRODUCTION_READINESS) into receipt.",
   }),
+  "record-diagnosis": Object.freeze({
+    name: "record-diagnosis",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--hypothesis": Object.freeze({ targetKey: "hypothesis", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--hypothesis requires text", description: "specific root-cause hypothesis explaining the verification failure" }),
+      "--failure-class": Object.freeze({ targetKey: "failureClass", parseType: "string", takesValue: true, valueName: "class", missingValueMessage: "--failure-class requires a class", description: "canonical failure class taxonomy" }),
+      "--evidence-ref": Object.freeze({ targetKey: "evidenceRefs", parseType: "string", takesValue: true, valueName: "check-id", repeatable: true, missingValueMessage: "--evidence-ref requires a check ID", description: "reference to failed/blocked check from current cycle" }),
+      "--settled-by": Object.freeze({ targetKey: "settledBy", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--settled-by requires text", description: "falsification or settlement criteria for the hypothesis" }),
+      "--next-safe-action": Object.freeze({ targetKey: "nextSafeAction", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--next-safe-action requires text", description: "smallest safe action to address the hypothesis" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson", ".forgeloop/task-state/<taskKey>/work-state.json"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Records an append-only diagnosis event in the lifecycle event ledger for the active cycle.",
+  }),
+  progress: Object.freeze({
+    name: "progress",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit progress evaluation as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Evaluates task progress across verification cycles and detects stalls deterministically.",
+  }),
+  "record-decision-criterion": Object.freeze({
+    name: "record-decision-criterion",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--decision": Object.freeze({ targetKey: "decision", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--decision requires text", description: "unresolved decision text matching current contract" }),
+      "--settled-by": Object.freeze({ targetKey: "settledBy", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--settled-by requires text", description: "criteria or guidance that settles the decision" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Records an append-only decision settlement criterion bound to the active contract fingerprint.",
+  }),
   complete: Object.freeze({
     name: "complete",
     category: "lifecycle",
@@ -377,18 +426,106 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Evaluates active task state against named enterprise policy packs.",
   }),
-  bundle: Object.freeze({
-    name: "bundle",
+  "policy-discover": Object.freeze({
+    name: "policy-discover",
+    category: "policy-audit",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--write": Object.freeze({ targetKey: "write", parseType: "boolean", takesValue: false, description: "persist discovered policy to .forgeloop/policy/discovery.json" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/policy/discovery.json", ".forgeloop/policy/policy.lock"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Discovers repository policy facts and candidate rules deterministically.",
+  }),
+  "policy-status": Object.freeze({
+    name: "policy-status",
+    category: "policy-audit",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Evaluates repository and task state against effective policy rules and baseline.",
+  }),
+  "policy-diff": Object.freeze({
+    name: "policy-diff",
     category: "policy-audit",
     mutation: "READ_ONLY",
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
+      "--before": Object.freeze({ targetKey: "before", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--before requires a path", description: "path to before policy JSON" }),
+      "--after": Object.freeze({ targetKey: "after", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--after requires a path", description: "path to after policy JSON" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],
     removes: [],
     mayExecuteExternalProcess: false,
+    description: "Performs semantic diffing between policy versions to detect tightening or weakening.",
+  }),
+  "rule-verify": Object.freeze({
+    name: "rule-verify",
+    category: "policy-audit",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--rule": Object.freeze({ targetKey: "rule", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--rule requires an ID", description: "verify a specific policy rule ID" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Verifies policy rules against mutation fixtures to prove detector efficacy.",
+  }),
+  baseline: Object.freeze({
+    name: "baseline",
+    category: "policy-audit",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--record": Object.freeze({ targetKey: "record", parseType: "boolean", takesValue: false, description: "record current violations as brownfield baseline" }),
+      "--update": Object.freeze({ targetKey: "update", parseType: "boolean", takesValue: false, description: "ratchet baseline downward by removing resolved violations" }),
+      "--policy-reset-authorized": Object.freeze({ targetKey: "policyResetAuthorized", parseType: "boolean", takesValue: false, description: "explicit operator authority to re-record baseline during active tasks" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/policy/baseline.json", ".forgeloop/policy/policy.lock"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Manages brownfield policy baseline violations with monotonic downward ratcheting.",
+  }),
+  "profile-interview": Object.freeze({
+    name: "profile-interview",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "show planned interview questions without changing files" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Optional interactive or dry-run interview to refine project profile facts.",
+  }),
+  bundle: Object.freeze({
+    name: "bundle",
+    category: "policy-audit",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/tasks/<taskId>"],
+    removes: [],
+    mayExecuteExternalProcess: false,
     description: "Exports current task artifacts into a portable task bundle archive.",
   }),
   inspect: Object.freeze({
@@ -449,13 +586,32 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Removes work-state.json for the active task only, preserving sibling contract, routing, and ledger files.",
   }),
+  "reconcile-closure": Object.freeze({
+    name: "reconcile-closure",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--id": Object.freeze({ targetKey: "checkId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--id requires a check ID", description: "contract verification item id used as evidence" }),
+      "--requirement": Object.freeze({ targetKey: "checkRequirement", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--requirement requires an evidence target", description: "exact contract verification item requirement text" }),
+      "--details": Object.freeze({ targetKey: "checkDetails", parseType: "json-object", takesValue: true, valueName: "json", missingValueMessage: "--details requires a JSON object", description: "additional structured execution details" }),
+      "--": Object.freeze({ targetKey: "commandArgv", parseType: "argv", takesValue: true, valueName: "argv...", description: "exact command argv to execute as objective-satisfaction evidence" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/executions/exec-<id>.json", ".forgeloop/task-state/<taskKey>/work-state.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Refreshes the work-state checkpoint of an EXECUTING task whose objective is already satisfied in the current repository, after contract-bound executed evidence, so canonical completion can proceed.",
+  }),
   "validate-receipt": Object.freeze({
     name: "validate-receipt",
     category: "verification",
     mutation: "READ_ONLY",
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
-      "--file": Object.freeze({ targetKey: "file", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--file requires a path", description: "receipt file relative to target" }),
+      ...CLI_TASK_OPTION,
+      "--file": Object.freeze({ targetKey: "file", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--file requires a path", description: "receipt file relative to target (overrides task-based receipt resolution)" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],
@@ -495,7 +651,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       "--contract-file": Object.freeze({ targetKey: "contractFile", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--contract-file requires a path", description: "path to initial contract file" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
-    writes: [".forgeloop/task-state/<taskKey>/task.json", ".forgeloop/task-state/<taskKey>/current-contract.json"],
+    writes: [".forgeloop/task-state/<taskKey>/task.json", ".forgeloop/task-state/<taskKey>/contract.json"],
     removes: [],
     mayExecuteExternalProcess: false,
     description: "Creates a new task descriptor and initializes its isolated task state namespace.",

package/src/core/cli-metadata.js

@@ -1,7 +1,7 @@
 import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
 
 /**
- * Canonical metadata for all 27 ForgeLoop CLI commands derived directly
+ * Canonical metadata for all 43 ForgeLoop CLI commands derived directly
  * from CLI_COMMAND_DEFINITIONS to guarantee zero divergence.
  */
 export const CLI_COMMAND_METADATA = Object.freeze(

package/src/core/completion-artifacts.js

@@ -26,6 +26,32 @@ import { readTaskDescriptor } from "./task-descriptor.js";
 import { assertClaimsCoverChangedPaths } from "./task-scope.js";
 import { discoverTasks } from "./task-discovery.js";
 
+/**
+ * Canonical terminal-result types shared by runtime validation, tests, and
+ * documentation conformance. Keep these single-sourced; do not re-declare
+ * the same type lists in validators or tests.
+ */
+export const TERMINAL_RESULT_TYPES = Object.freeze([
+  "PUBLICATION",
+  "PRODUCTION_READINESS",
+]);
+
+/**
+ * Canonical terminal-status sets shared by runtime validation, tests, and
+ * documentation conformance. Keep these single-sourced; do not re-declare
+ * the same status lists in validators or tests.
+ */
+export const PUBLICATION_STATUSES = Object.freeze([
+  "committed",
+  "pushed",
+  "published",
+  "deployed",
+]);
+export const PRODUCTION_READINESS_STATUSES = Object.freeze([
+  "ready",
+  "blocked",
+]);
+
 function artifactError(code, message, artifacts = []) {
   const error = new Error(message);
   error.code = code;
@@ -706,13 +732,13 @@ export async function recordTerminalResult({
   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)) {
+  if (!TERMINAL_RESULT_TYPES.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)) {
+  if (type === "PUBLICATION" && !PUBLICATION_STATUSES.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)) {
+  if (type === "PRODUCTION_READINESS" && !PRODUCTION_READINESS_STATUSES.includes(status)) {
     throw artifactError("E_CHECK_INVALID", `Invalid production readiness status for record-terminal-result: ${status}`, [ARTIFACT_PATHS.state]);
   }
 

package/src/core/completion.js

@@ -11,7 +11,29 @@ import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { evaluateStartExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
 import { evaluateTerminalRequirements } from "./evidence-readiness.js";
-import { taskArtifactPath } from "./task-paths.js";
+import { PROJECT_ARTIFACT_PATHS, taskArtifactPath } from "./task-paths.js";
+import { detectPolicyCapability, evaluateTargetPolicy } from "./policy-engine.js";
+
+/**
+ * Canonical completion return statuses shared by the runtime, tests, and
+ * documentation conformance. The CLI reference's return-status prose is
+ * mechanically checked against this set.
+ */
+export const COMPLETION_STATUSES = Object.freeze(["VALID", "REJECTED"]);
+
+/**
+ * Canonical completion verification-status values returned by
+ * evaluateCompletion. The asymmetric casing (VALID / invalid) is the actual
+ * runtime contract and is intentionally preserved; documentation conformance
+ * checks documented examples and prose against this exact set, and the runtime
+ * derives its output from these same named constants.
+ */
+export const VERIFICATION_STATUS_VALID = "VALID";
+export const VERIFICATION_STATUS_INVALID = "invalid";
+export const VERIFICATION_STATUSES = Object.freeze([
+  VERIFICATION_STATUS_VALID,
+  VERIFICATION_STATUS_INVALID,
+]);
 
 function issue(code, message, artifacts = [], details = {}) {
   return { code, message, artifacts, ...details };
@@ -74,13 +96,20 @@ function repairNext(error) {
       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.";
-    case "E_PROFILE_UNVERIFIED":
+    case "E_CYCLE_CLOSED":
+      return "Advance the task through valid lifecycle phases (PLANNED -> EXECUTING -> VERIFYING -> REVIEWING).";
+    case "E_LEDGER_INVALID":
+    case "E_LEDGER_STALE":
+    case "E_STATE_LEDGER_MISMATCH":
+      return "Inspect the event ledger and repair sequence or integrity violations.";
+    case "E_EVIDENCE_MISSING":
+    case "E_EVIDENCE_BLOCKED":
+    case "E_CHECK_FAILED":
+    case "E_REQUIREMENT_UNMET":
+      return "Execute and pass all required checks using forgeloop run-check before completion.";
+    case "E_CHECK_EXECUTION_PROVENANCE_MISSING":
+      return "Re-run checks via forgeloop run-check to ensure ForgeLoop execution provenance.";
+    case "E_CONTRACT_PROFILE_STRICT_UNVERIFIED":
       return "Use Standard mode for a fresh target, or verify PROJECT_PROFILE.md before Strict completion.";
     case "E_INSTALLATION_AUTHORITY_REQUIRED":
     case "E_AUTHORITY_INVALID":
@@ -89,6 +118,28 @@ function repairNext(error) {
       return "Do not execute installation-capable verification commands without explicit scoped installation authority; use local equivalents or record NOT_VERIFIED.";
     case "E_VERIFICATION_TOOL_UNAVAILABLE":
       return "Use an available local verifier, an existing equivalent, or record NOT_VERIFIED if installation was not authorized.";
+    case "E_NEW_POLICY_VIOLATION":
+      return "Resolve the new policy violation or record baseline if adopted debt before completion.";
+    case "E_POLICY_WEAKENING":
+      return "Restore the original policy configuration or obtain explicit project authority before retrying completion.";
+    case "E_CHECK_INERT":
+      return "Configure an applicable target scope or mark the inert check unsupported.";
+    case "E_CHECK_MUTATION_NOT_DETECTED":
+      return "Fix checker logic to properly detect intentional mutation fixtures.";
+    case "E_CHECK_MUTATION_EXECUTION_ERROR":
+      return "Repair the checker execution path and rerun rule verification.";
+    case "E_POLICY_LOCK_MISMATCH":
+      return "Re-evaluate effective rules and update policy.lock or restore modified rules.";
+    case "E_POLICY_DRIFT":
+    case "E_POLICY_DRIFT_UNKNOWN":
+      return "Re-verify affected checks or restore original policy.";
+    case "E_POLICY_INVALID":
+      return "Validate and repair rules.json, baseline.json, or discovery.json against schema.";
+    case "E_POLICY_EVALUATION_FAILED":
+      return "Inspect policy configuration and checker adapters for unhandled errors.";
+    case "E_BASELINE_EXPANSION":
+    case "E_BASELINE_RECORD_DURING_ACTIVE_TASK":
+      return "Resolve new violations rather than expanding the baseline.";
     default:
       return "Resolve this validator finding in the named artifact before retrying completion.";
   }
@@ -333,12 +384,52 @@ export async function evaluateCompletion({
     }
   }
 
+  const policyCapability = await detectPolicyCapability(target, packageRoot);
+  if (policyCapability === "INVALID") {
+    errors.push(issue(
+      "E_POLICY_INVALID",
+      "Policy configuration or baseline artifacts are malformed or fail schema validation.",
+      [PROJECT_ARTIFACT_PATHS.policyRules, PROJECT_ARTIFACT_PATHS.policyBaseline],
+    ));
+  } else if (policyCapability === "AVAILABLE") {
+    try {
+      const policyEval = await evaluateTargetPolicy({
+        target,
+        packageRoot,
+        taskId: contract?.value?.taskId ?? taskId,
+      });
+      for (const policyErr of policyEval.errors ?? []) {
+        const code = policyErr.code === "NEW_VIOLATION" ? "E_NEW_POLICY_VIOLATION"
+          : policyErr.code === "POLICY_WEAKENING" ? "E_POLICY_WEAKENING"
+          : policyErr.code === "CHECK_INERT" ? "E_CHECK_INERT"
+          : policyErr.code === "CHECK_MUTATION_NOT_DETECTED" ? "E_CHECK_MUTATION_NOT_DETECTED"
+          : policyErr.code === "CHECK_MUTATION_EXECUTION_ERROR" ? "E_CHECK_MUTATION_EXECUTION_ERROR"
+          : policyErr.code === "POLICY_LOCK_MISMATCH" ? "E_POLICY_LOCK_MISMATCH"
+          : policyErr.code === "POLICY_DRIFT_UNKNOWN" ? "E_POLICY_DRIFT_UNKNOWN"
+          : policyErr.code === "POLICY_EVALUATION_FAILED" ? "E_POLICY_EVALUATION_FAILED"
+          : policyErr.code;
+        errors.push(issue(
+          code,
+          policyErr.why || policyErr.message,
+          [PROJECT_ARTIFACT_PATHS.policyLock],
+          { ruleId: policyErr.ruleId, fix: policyErr.fix },
+        ));
+      }
+    } catch (error) {
+      errors.push(issue(
+        "E_POLICY_EVALUATION_FAILED",
+        `Policy evaluation threw an unexpected error: ${error.message}`,
+        [PROJECT_ARTIFACT_PATHS.policyLock],
+      ));
+    }
+  }
+
   const sortedErrors = sortIssues(errors);
   const valid = sortedErrors.length === 0;
   return {
-    status: valid ? "VALID" : "REJECTED",
+    status: valid ? COMPLETION_STATUSES[0] : COMPLETION_STATUSES[1],
     taskStatus: valid ? "COMPLETE" : receiptValue?.status === "blocked" ? "BLOCKED" : "INCOMPLETE",
-    verificationStatus: valid ? "VALID" : "invalid",
+    verificationStatus: valid ? VERIFICATION_STATUS_VALID : VERIFICATION_STATUS_INVALID,
     publicationStatus: publication,
     productionReadiness: receiptValue?.productionReadiness ?? "not-verified",
     errors: sortedErrors,

package/src/core/diagnosis-model.js

@@ -0,0 +1,214 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { assertFailureClass } from "./protocol.js";
+
+export const DIAGNOSIS_INFORMATION_GAIN = Object.freeze([
+  "FIRST_DIAGNOSIS",
+  "NEW_HYPOTHESIS",
+  "NEW_EVIDENCE",
+  "NEW_HYPOTHESIS_AND_EVIDENCE",
+  "NONE",
+]);
+
+export function normalizeDiagnosisText(value, label = "value") {
+  if (typeof value !== "string" || !value.trim()) {
+    const error = new Error(`${label} must be a non-empty string`);
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  return value.trim().replace(/\s+/gu, " ").toLowerCase();
+}
+
+export function diagnosisFingerprint({ failureClass, hypothesis, evidenceRefs }) {
+  assertFailureClass(failureClass);
+  const normalizedHypothesis = normalizeDiagnosisText(hypothesis, "hypothesis");
+  if (!Array.isArray(evidenceRefs) || evidenceRefs.length === 0) {
+    const error = new Error("evidenceRefs must be a non-empty array of strings");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  const cleanRefs = evidenceRefs.map((ref) => {
+    if (typeof ref !== "string" || !ref.trim()) {
+      const error = new Error("evidenceRef must be a non-empty string");
+      error.code = "E_DIAGNOSIS_INVALID";
+      throw error;
+    }
+    return ref.trim();
+  });
+  const normalizedRefs = [...new Set(cleanRefs)].sort();
+  return canonicalFingerprint({
+    failureClass,
+    hypothesis: normalizedHypothesis,
+    evidenceRefs: normalizedRefs,
+  });
+}
+
+export function classifyDiagnosisInformationGain(current, previous) {
+  if (!previous) return "FIRST_DIAGNOSIS";
+
+  const currentHypothesis = normalizeDiagnosisText(current.hypothesis, "current hypothesis");
+  const prevHypothesis = normalizeDiagnosisText(previous.hypothesis, "previous hypothesis");
+  const sameHypothesis = currentHypothesis === prevHypothesis;
+
+  const currentEvidence = [...new Set((current.evidenceRefs ?? []).map((r) => String(r).trim()))].sort();
+  const prevEvidence = [...new Set((previous.evidenceRefs ?? []).map((r) => String(r).trim()))].sort();
+  const sameEvidence = JSON.stringify(currentEvidence) === JSON.stringify(prevEvidence);
+
+  if (sameHypothesis && sameEvidence) return "NONE";
+  if (!sameHypothesis && !sameEvidence) return "NEW_HYPOTHESIS_AND_EVIDENCE";
+  if (!sameHypothesis) return "NEW_HYPOTHESIS";
+  return "NEW_EVIDENCE";
+}
+
+export function createDiagnosisDetails(input, previous = null) {
+  if (typeof input?.verificationCycle !== "number" || !Number.isInteger(input.verificationCycle) || input.verificationCycle < 1) {
+    const error = new Error("verificationCycle must be an integer >= 1");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  try {
+    assertFailureClass(input.failureClass);
+  } catch {
+    const error = new Error(`Invalid failureClass: ${input.failureClass}`);
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof input.hypothesis !== "string" || !input.hypothesis.trim()) {
+    const error = new Error("hypothesis must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (!Array.isArray(input.evidenceRefs) || input.evidenceRefs.length === 0) {
+    const error = new Error("evidenceRefs must be a non-empty array");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  const cleanRefs = input.evidenceRefs.map((r) => {
+    if (typeof r !== "string" || !r.trim()) {
+      const error = new Error("each evidenceRef must be a non-empty string");
+      error.code = "E_DIAGNOSIS_INVALID";
+      throw error;
+    }
+    return r.trim();
+  });
+  const uniqueRefs = [...new Set(cleanRefs)].sort();
+  if (typeof input.settledBy !== "string" || !input.settledBy.trim()) {
+    const error = new Error("settledBy must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof input.nextSafeAction !== "string" || !input.nextSafeAction.trim()) {
+    const error = new Error("nextSafeAction must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+
+  const fingerprint = diagnosisFingerprint({
+    failureClass: input.failureClass,
+    hypothesis: input.hypothesis,
+    evidenceRefs: uniqueRefs,
+  });
+  const infoGain = classifyDiagnosisInformationGain(
+    { hypothesis: input.hypothesis, evidenceRefs: uniqueRefs },
+    previous ? { hypothesis: previous.hypothesis, evidenceRefs: previous.evidenceRefs } : null,
+  );
+
+  return {
+    verificationCycle: input.verificationCycle,
+    failureClass: input.failureClass,
+    hypothesis: input.hypothesis.trim(),
+    evidenceRefs: uniqueRefs,
+    settledBy: input.settledBy.trim(),
+    nextSafeAction: input.nextSafeAction.trim(),
+    diagnosisFingerprint: fingerprint,
+    informationGain: infoGain,
+    previousDiagnosisFingerprint: previous?.diagnosisFingerprint ?? null,
+  };
+}
+
+export function assertDiagnosisDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    const error = new Error("Diagnosis details must be an object");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof details.verificationCycle !== "number" || !Number.isInteger(details.verificationCycle) || details.verificationCycle < 1) {
+    const error = new Error("Diagnosis verificationCycle must be an integer >= 1");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  try {
+    assertFailureClass(details.failureClass);
+  } catch {
+    const error = new Error(`Invalid diagnosis failureClass: ${details.failureClass}`);
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof details.hypothesis !== "string" || !details.hypothesis.trim()) {
+    const error = new Error("Diagnosis hypothesis must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (!Array.isArray(details.evidenceRefs) || details.evidenceRefs.length === 0) {
+    const error = new Error("Diagnosis evidenceRefs must be a non-empty array");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  for (const ref of details.evidenceRefs) {
+    if (typeof ref !== "string" || !ref.trim()) {
+      const error = new Error("Diagnosis evidenceRef must be a non-empty string");
+      error.code = "E_DIAGNOSIS_INVALID";
+      throw error;
+    }
+  }
+  if (typeof details.settledBy !== "string" || !details.settledBy.trim()) {
+    const error = new Error("Diagnosis settledBy must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof details.nextSafeAction !== "string" || !details.nextSafeAction.trim()) {
+    const error = new Error("Diagnosis nextSafeAction must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (!DIAGNOSIS_INFORMATION_GAIN.includes(details.informationGain)) {
+    const error = new Error(`Invalid diagnosis informationGain: ${details.informationGain}`);
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof details.diagnosisFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(details.diagnosisFingerprint)) {
+    const error = new Error("Invalid diagnosisFingerprint");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  const computed = diagnosisFingerprint({
+    failureClass: details.failureClass,
+    hypothesis: details.hypothesis,
+    evidenceRefs: details.evidenceRefs,
+  });
+  if (computed !== details.diagnosisFingerprint) {
+    const error = new Error("Diagnosis fingerprint does not match computed fingerprint");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (details.previousDiagnosisFingerprint !== null && (typeof details.previousDiagnosisFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(details.previousDiagnosisFingerprint))) {
+    const error = new Error("Invalid previousDiagnosisFingerprint");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  return details;
+}
+
+export function diagnosisEventsForTask(events, taskId) {
+  if (!Array.isArray(events)) return [];
+  return events.filter((e) => e.event === "DIAGNOSIS_RECORDED" && (!taskId || e.taskId === taskId));
+}
+
+export function currentCycleDiagnosis(events, taskId, verificationCycle) {
+  const taskEvents = diagnosisEventsForTask(events, taskId);
+  for (let i = taskEvents.length - 1; i >= 0; i--) {
+    if (taskEvents[i].details?.verificationCycle === verificationCycle) {
+      return taskEvents[i];
+    }
+  }
+  return null;
+}