@cassiomc1/forgeloop 1.1.1 → 1.2.2

package/src/core/preflight-consistency.js

@@ -86,64 +86,72 @@ export async function validateReadyProtocolConsistency({
   persisted,
   current = null,
   evaluateCurrentPreflight,
+  taskId = null,
 } = {}) {
   if (persisted?.status !== "READY") return [];
-  const result = current ?? await evaluateCurrentPreflight({ target, packageRoot });
+  const result = current ?? await evaluateCurrentPreflight({ target, packageRoot, taskId });
   const errors = [...validatePersistedPreflight(persisted, result)];
 
+  const stateRel = taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state;
+  const eventsRel = taskId ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events;
+  const preflightRel = taskId ? taskArtifactPath(taskId, "preflight") : ARTIFACT_PATHS.preflight;
+  const contractRel = taskId ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract;
+  const routeRel = taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route;
+  const gatesRel = taskId ? taskArtifactPath(taskId, "gates") : ARTIFACT_PATHS.gates;
+
   let state = null;
   try {
-    state = await readWorkState(target, packageRoot);
+    state = await readWorkState(target, { packageRoot, taskId });
   } catch (error) {
-    errors.push(issue("E_STATE_INVALID", error.message, [ARTIFACT_PATHS.state]));
+    errors.push(issue("E_STATE_INVALID", error.message, [stateRel]));
   }
   if (!state) {
     errors.push(issue(
       "E_STATE_MISSING_AFTER_PREFLIGHT_READY",
       "A persisted READY preflight must have a resumable work-state checkpoint",
-      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.state],
+      [preflightRel, stateRel],
     ));
   } else {
     if (state.taskId !== persisted.taskId) {
-      errors.push(issue("E_STATE_TASK_MISMATCH", "The resumable checkpoint does not belong to the READY preflight task", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.preflight]));
+      errors.push(issue("E_STATE_TASK_MISMATCH", "The resumable checkpoint does not belong to the READY preflight task", [stateRel, preflightRel]));
     }
     if (state.contractFingerprint !== result.fingerprints.contract) {
-      errors.push(issue("E_CONTRACT_STALE", "The resumable checkpoint does not match the READY contract fingerprint", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract]));
+      errors.push(issue("E_CONTRACT_STALE", "The resumable checkpoint does not match the READY contract fingerprint", [stateRel, contractRel]));
     }
     if (state.routeFingerprint !== result.fingerprints.routing) {
-      errors.push(issue("E_ROUTE_STALE", "The resumable checkpoint does not match the READY routing fingerprint", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.route]));
+      errors.push(issue("E_ROUTE_STALE", "The resumable checkpoint does not match the READY routing fingerprint", [stateRel, routeRel]));
     }
     if (JSON.stringify(state.selectedGuides) !== JSON.stringify(result.routing.guides)) {
-      errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "The resumable checkpoint guides do not match the READY routing result", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.route]));
+      errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "The resumable checkpoint guides do not match the READY routing result", [stateRel, routeRel]));
     }
     if (!sameStringSet(state.requiredGates ?? [], persisted.requiredGates)
       || !sameStringSet(state.satisfiedGates ?? [], persisted.satisfiedGates)) {
-      errors.push(issue("E_PREFLIGHT_GATES_STALE", "The resumable checkpoint gate sets do not match the READY preflight", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.gates]));
+      errors.push(issue("E_PREFLIGHT_GATES_STALE", "The resumable checkpoint gate sets do not match the READY preflight", [stateRel, preflightRel, gatesRel]));
     }
   }
 
-  const ledger = await validateEventLedger(target, packageRoot);
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
   if (!ledger.valid) {
-    errors.push(...ledger.errors.map((error) => issue(error.code ?? "E_EVENT_INVALID", error.message, [ARTIFACT_PATHS.events])));
+    errors.push(...ledger.errors.map((error) => issue(error.code ?? "E_EVENT_INVALID", error.message, [eventsRel])));
   }
   const events = ledger.events ?? [];
   for (const requiredEvent of ["CONTRACT_VALIDATED", "ROUTE_VALIDATED"]) {
     if (!events.some((event) => event.event === requiredEvent && event.taskId === persisted.taskId)) {
-      errors.push(issue("E_PREFLIGHT_EVENT_MISSING", `READY preflight is missing lifecycle event: ${requiredEvent}`, [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight]));
+      errors.push(issue("E_PREFLIGHT_EVENT_MISSING", `READY preflight is missing lifecycle event: ${requiredEvent}`, [eventsRel, preflightRel]));
     }
   }
   for (const gate of persisted.satisfiedGates ?? []) {
     if (!events.some((event) => event.event === "GATE_SATISFIED"
       && event.taskId === persisted.taskId
       && event.details?.gate === gate)) {
-      errors.push(issue("E_PREFLIGHT_GATE_EVENT_MISSING", `READY preflight is missing lifecycle gate event: ${gate}`, [ARTIFACT_PATHS.events, `${ARTIFACT_PATHS.gates}/${gate}.json`]));
+      errors.push(issue("E_PREFLIGHT_GATE_EVENT_MISSING", `READY preflight is missing lifecycle gate event: ${gate}`, [eventsRel, `${gatesRel}/${gate}.json`]));
     }
   }
   const readyEvents = events.filter((event) => event.event === "PREFLIGHT_READY" && event.taskId === persisted.taskId);
   if (readyEvents.length === 0) {
-    errors.push(issue("E_PREFLIGHT_READY_EVENT_MISSING", "Persisted READY preflight is missing the matching PREFLIGHT_READY lifecycle event", [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events]));
+    errors.push(issue("E_PREFLIGHT_READY_EVENT_MISSING", "Persisted READY preflight is missing the matching PREFLIGHT_READY lifecycle event", [preflightRel, eventsRel]));
   } else if (!readyEvents.some((event) => sameReadyPreflightEvent(event, result))) {
-    errors.push(issue("E_PREFLIGHT_READY_EVENT_MISMATCH", "PREFLIGHT_READY lifecycle details do not match the persisted READY preflight", [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events]));
+    errors.push(issue("E_PREFLIGHT_READY_EVENT_MISMATCH", "PREFLIGHT_READY lifecycle details do not match the persisted READY preflight", [preflightRel, eventsRel]));
   }
   return sortIssues(errors);
 }

package/src/core/preflight-model.js

@@ -34,11 +34,19 @@ export function sameStringSet(left, right) {
 export function validatePersistedPreflight(persisted, current) {
   const errors = [];
   if (persisted?.status !== "READY") {
-    errors.push(issue("E_PREFLIGHT_NOT_READY", "A persisted READY preflight is required", [ARTIFACT_PATHS.preflight]));
+    if (Array.isArray(persisted?.errors) && persisted.errors.length > 0) {
+      errors.push(...persisted.errors);
+    } else {
+      errors.push(issue("E_PREFLIGHT_NOT_READY", "A persisted READY preflight is required", [ARTIFACT_PATHS.preflight]));
+    }
     return errors;
   }
   if (current?.status !== "READY") {
-    errors.push(issue("E_PREFLIGHT_NOT_READY", "The current preflight evaluation is not READY", [ARTIFACT_PATHS.preflight]));
+    if (Array.isArray(current?.errors) && current.errors.length > 0) {
+      errors.push(...current.errors);
+    } else {
+      errors.push(issue("E_PREFLIGHT_NOT_READY", "The current preflight evaluation is not READY", [ARTIFACT_PATHS.preflight]));
+    }
   }
   if (persisted.taskId !== current?.taskId) {
     errors.push(issue(

package/src/core/preflight.js

@@ -27,7 +27,7 @@ import {
 import { PROFILE_PATH } from "./target-layout.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { validateEventLedger } from "./events.js";
-import { taskArtifactPath } from "./task-paths.js";
+import { PROJECT_ARTIFACT_PATHS, taskArtifactPath } from "./task-paths.js";
 
 const PREVIEW_DECISION_LIMIT = 10;
 const PREVIEW_DECISION_MAX_LENGTH = 240;
@@ -91,6 +91,24 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
     errors.push(issue("E_CONTRACT_STALE", "work-state references a different contract", [contractRelPath, stateRelPath]));
   }
 
+  const { detectPolicyCapability } = await import("./policy-engine.js");
+  const policyCapability = await detectPolicyCapability(target, packageRoot);
+  if (policyCapability === "INVALID") {
+    errors.push(issue(
+      "E_POLICY_INVALID",
+      "Executable policy artifacts are present but invalid.",
+      [
+        PROJECT_ARTIFACT_PATHS.policyRules,
+        PROJECT_ARTIFACT_PATHS.policyBaseline,
+        PROJECT_ARTIFACT_PATHS.policyDiscovery,
+        PROJECT_ARTIFACT_PATHS.policyLock,
+      ],
+      {
+        next: "Repair the invalid policy artifact and rerun forgeloop preflight.",
+      },
+    ));
+  }
+
   const sortedErrors = sortIssues(errors);
   const effectiveTaskId = taskId ?? contract?.value?.taskId ?? state?.taskId ?? "unknown";
   return {
@@ -178,6 +196,52 @@ export async function runPreflight({
   }
 
   if (result.taskId !== "unknown") {
+    const {
+      detectPolicyCapability,
+      loadEffectiveRules,
+      readBaseline,
+      computePolicyLockData,
+      readTaskPolicySnapshot,
+      writeTaskPolicySnapshot,
+    } = await import("./policy-engine.js");
+
+    const policyCapability = await detectPolicyCapability(target, packageRoot);
+    if (policyCapability === "INVALID") {
+      throw preflightError(
+        "E_POLICY_INVALID",
+        "Executable policy artifacts are present but invalid.",
+        [
+          PROJECT_ARTIFACT_PATHS.policyRules,
+          PROJECT_ARTIFACT_PATHS.policyBaseline,
+          PROJECT_ARTIFACT_PATHS.policyDiscovery,
+          PROJECT_ARTIFACT_PATHS.policyLock,
+        ],
+      );
+    }
+
+    if (policyCapability === "AVAILABLE") {
+      try {
+        const existingSnapshot = await readTaskPolicySnapshot(target, result.taskId, packageRoot);
+        if (!existingSnapshot) {
+          const rules = await loadEffectiveRules(target, packageRoot);
+          const baseline = await readBaseline(target, packageRoot);
+          const lock = computePolicyLockData(rules, baseline);
+          const snapshot = {
+            schemaVersion: 1,
+            policyDigest: lock.digest,
+            rules,
+            baseline: baseline ?? { schemaVersion: 1, entries: [] },
+            baselineDigest: lock.baselineDigest,
+            capturedAt: new Date().toISOString(),
+          };
+          await writeTaskPolicySnapshot(target, result.taskId, snapshot, packageRoot);
+        }
+      } catch (error) {
+        const snapRel = taskArtifactPath(result.taskId, "policySnapshot");
+        throw preflightError("E_POLICY_SNAPSHOT_WRITE_FAILED", `Failed to persist task policy snapshot: ${error.message}`, [snapRel]);
+      }
+    }
+
     await appendActivationEvents(target, packageRoot, ledger, result, { eventsPath, taskId });
     const afterEvents = await validateEventLedger(target, packageRoot, { eventsPath, taskId });
     if (!afterEvents.valid) {

package/src/core/progress.js

@@ -0,0 +1,143 @@
+import { diagnosisEventsForTask } from "./diagnosis-model.js";
+
+export const PROGRESS_STATUS = Object.freeze({
+  ADVANCING: "ADVANCING",
+  WATCH: "WATCH",
+  STALLED: "STALLED",
+});
+
+export const PROGRESS_SIGNAL = Object.freeze({
+  NO_DIAGNOSTIC_INFORMATION_GAIN: "NO_DIAGNOSTIC_INFORMATION_GAIN",
+  REPEATED_FAILED_REQUIREMENT: "REPEATED_FAILED_REQUIREMENT",
+  REPEATED_FAILURE_WITH_SAME_DIAGNOSIS: "REPEATED_FAILURE_WITH_SAME_DIAGNOSIS",
+  HIGH_CORRECTION_CYCLE_COUNT: "HIGH_CORRECTION_CYCLE_COUNT",
+});
+
+export function diagnosisRequirements(diagnosis, checksById) {
+  if (!diagnosis) return [];
+  return [...new Set(
+    (diagnosis.evidenceRefs ?? [])
+      .map((id) => checksById.get(id)?.requirement)
+      .filter(Boolean),
+  )].sort();
+}
+
+export function evaluateProgress({ state, events = [] } = {}) {
+  const signals = [];
+  let status = PROGRESS_STATUS.ADVANCING;
+
+  if (!state) {
+    return { status, signals };
+  }
+
+  const taskEvents = Array.isArray(events) ? events.filter((e) => !state.taskId || e.taskId === state.taskId) : [];
+  const diagEvents = diagnosisEventsForTask(taskEvents, state.taskId);
+  const latestDiag = diagEvents.at(-1)?.details ?? null;
+
+  // Build checksById index for resolving requirement from check IDs
+  const checksById = new Map();
+  for (const check of state.checks ?? []) {
+    if (check.id) checksById.set(check.id, check);
+    if (check.checkId) checksById.set(check.checkId, check);
+  }
+  for (const event of taskEvents) {
+    if (event.event === "VERIFICATION_RECORDED" && event.details) {
+      if (event.details.id) checksById.set(event.details.id, event.details);
+      if (event.details.checkId) checksById.set(event.details.checkId, event.details);
+    }
+  }
+
+  // 1. Check if latest diagnosis has NO information gain (global stall)
+  if (latestDiag && latestDiag.informationGain === "NONE") {
+    status = PROGRESS_STATUS.STALLED;
+    signals.push({
+      code: PROGRESS_SIGNAL.NO_DIAGNOSTIC_INFORMATION_GAIN,
+      severity: "BLOCKING_FOR_RETRY",
+      message: "Latest diagnosis repeats the prior hypothesis with the same evidence.",
+      verificationCycles: [latestDiag.verificationCycle],
+    });
+  }
+
+  // 2. Track failed requirements across distinct verification cycles
+  const reqCycles = new Map();
+  const checks = state.checks ?? [];
+  for (const check of checks) {
+    if (check.status === "failed" || check.status === "blocked") {
+      const cycle = check.details?.verificationCycle ?? state.verificationCycle ?? 1;
+      const req = check.requirement ?? "default";
+      if (!reqCycles.has(req)) reqCycles.set(req, new Set());
+      reqCycles.get(req).add(cycle);
+    }
+  }
+
+  // Also extract from VERIFICATION_RECORDED events
+  for (const event of taskEvents) {
+    if (event.event === "VERIFICATION_RECORDED") {
+      const details = event.details ?? {};
+      if (details.status === "failed" || details.status === "blocked") {
+        const cycle = details.verificationCycle ?? 1;
+        const req = details.requirement ?? "default";
+        if (!reqCycles.has(req)) reqCycles.set(req, new Set());
+        reqCycles.get(req).add(cycle);
+      }
+    }
+  }
+
+  const latestDiagReqs = diagnosisRequirements(latestDiag, checksById);
+
+  for (const [req, cyclesSet] of [...reqCycles.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    if (cyclesSet.size >= 3) {
+      const sortedCycles = [...cyclesSet].sort((a, b) => a - b);
+      const isLatestStalledForThisReq = latestDiag && latestDiag.informationGain === "NONE" && latestDiagReqs.includes(req);
+      if (isLatestStalledForThisReq) {
+        if (!signals.some((s) => s.code === PROGRESS_SIGNAL.REPEATED_FAILURE_WITH_SAME_DIAGNOSIS && s.requirement === req)) {
+          signals.push({
+            code: PROGRESS_SIGNAL.REPEATED_FAILURE_WITH_SAME_DIAGNOSIS,
+            severity: "BLOCKING_FOR_RETRY",
+            message: `Requirement "${req}" failed in ${cyclesSet.size} cycles and the latest diagnoses contain no new information.`,
+            verificationCycles: sortedCycles,
+            requirement: req,
+          });
+        }
+        status = PROGRESS_STATUS.STALLED;
+      } else {
+        if (!signals.some((s) => s.code === PROGRESS_SIGNAL.REPEATED_FAILED_REQUIREMENT && s.requirement === req)) {
+          signals.push({
+            code: PROGRESS_SIGNAL.REPEATED_FAILED_REQUIREMENT,
+            severity: "ADVISORY",
+            message: `Requirement "${req}" failed across ${cyclesSet.size} distinct verification cycles.`,
+            verificationCycles: sortedCycles,
+            requirement: req,
+          });
+        }
+        if (status !== PROGRESS_STATUS.STALLED) {
+          status = PROGRESS_STATUS.WATCH;
+        }
+      }
+    }
+  }
+
+  // 3. High cycle count
+  const currentCycle = state.verificationCycle ?? 1;
+  if (currentCycle >= 4) {
+    signals.push({
+      code: PROGRESS_SIGNAL.HIGH_CORRECTION_CYCLE_COUNT,
+      severity: "ADVISORY",
+      message: `Task has reached verification cycle ${currentCycle}.`,
+      verificationCycles: Array.from({ length: currentCycle }, (_, i) => i + 1),
+    });
+    if (status !== PROGRESS_STATUS.STALLED) {
+      status = PROGRESS_STATUS.WATCH;
+    }
+  }
+
+  // Sort signals deterministically
+  signals.sort((left, right) =>
+    left.code.localeCompare(right.code) || (left.requirement || "").localeCompare(right.requirement || "")
+  );
+
+  return {
+    status,
+    signals,
+  };
+}

package/src/core/protocol.js

@@ -93,6 +93,14 @@ export const FAILURE_CODES = Object.freeze([
   "E_CONTINUITY_CONTRACT_MISMATCH",
   "E_CONTINUITY_PHASE_MISMATCH",
   "E_CONTINUITY_RECONCILIATION_REQUIRED",
+  "E_DIAGNOSIS_REQUIRED",
+  "E_DIAGNOSIS_INVALID",
+  "E_DIAGNOSIS_EVIDENCE_INVALID",
+  "E_DIAGNOSIS_CYCLE_MISMATCH",
+  "E_DIAGNOSIS_NO_NEW_INFORMATION",
+  "E_PROGRESS_STALLED",
+  "E_DECISION_CRITERION_INVALID",
+  "E_DECISION_NOT_UNRESOLVED",
 ]);
 
 export const WORK_PHASES = Object.freeze([

package/src/core/reconcile-closure.js

@@ -0,0 +1,173 @@
+import { readContract } from "./contract.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { runCommandExecution } from "./execution.js";
+import { currentRepositoryFingerprint } from "./repository.js";
+import { taskArtifactPath } from "./task-paths.js";
+import { classifyLoadedWorkState, readWorkState, writeWorkState } from "./work-state.js";
+
+export const RECONCILE_EVENT = "CHECKPOINT_RECONCILED";
+
+const RECONCILABLE_DRIFT = new Set(["REPOSITORY_CHANGED"]);
+
+function reconcileError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+/**
+ * Canonical recovery for an EXECUTING task whose objective is already
+ * satisfied in the current repository but whose work-state checkpoint is
+ * stale because the repository fingerprint moved.
+ *
+ * The command refreshes the checkpoint repository fingerprint only after:
+ *   - the task is EXECUTING,
+ *   - classification requires revalidation and the only drift is
+ *     REPOSITORY_CHANGED,
+ *   - the append-only event ledger is valid,
+ *   - a contract-bound verification check (exact verification item id and
+ *     requirement text, type VERIFICATION) executes successfully in the
+ *     current repository as evidence that the objective is present.
+ *
+ * Closure itself proceeds through the canonical pipeline (advance to
+ * VERIFYING, prepare-completion, record-check, complete); claims are
+ * released only by canonical COMPLETE.
+ */
+export async function runReconcileClosure({
+  target,
+  packageRoot,
+  taskId,
+  checkId,
+  requirement,
+  argv,
+  details,
+  authorityContext,
+  runtimeContext,
+} = {}) {
+  if (typeof taskId !== "string" || !taskId.trim()) {
+    throw reconcileError("E_TASK_REQUIRED", "reconcile-closure requires --task", []);
+  }
+  if (typeof checkId !== "string" || !checkId.trim()) {
+    throw reconcileError("E_RECONCILE_REQUIREMENT_UNKNOWN", "reconcile-closure requires --id", []);
+  }
+  if (typeof requirement !== "string" || !requirement.trim()) {
+    throw reconcileError("E_RECONCILE_REQUIREMENT_UNKNOWN", "reconcile-closure requires --requirement", []);
+  }
+  if (!Array.isArray(argv) || argv.length === 0) {
+    throw reconcileError("E_RECONCILE_EVIDENCE_FAILED", "reconcile-closure requires -- followed by the evidence command argv", []);
+  }
+
+  const stateRel = taskArtifactPath(taskId, "state");
+  const contractRel = taskArtifactPath(taskId, "contract");
+  const eventsRel = taskArtifactPath(taskId, "events");
+
+  const state = await readWorkState(target, { packageRoot, taskId });
+  if (!state) {
+    throw reconcileError("E_RECONCILE_PHASE_INVALID", "Cannot reconcile without work state", [stateRel]);
+  }
+  if (state.phase !== "EXECUTING") {
+    throw reconcileError(
+      "E_RECONCILE_PHASE_INVALID",
+      `reconcile-closure supports EXECUTING tasks whose objective is already satisfied; found ${state.phase}`,
+      [stateRel],
+    );
+  }
+
+  const freshness = await classifyLoadedWorkState({ target, state, contractFile: contractRel });
+  if (freshness.status !== "REVALIDATION_REQUIRED" || !freshness.reasons.includes("REPOSITORY_CHANGED")) {
+    throw reconcileError(
+      "E_RECONCILE_NOT_STALE",
+      `work-state checkpoint is ${freshness.status === "FRESH" ? "fresh" : "not revalidation-required"}; no reconciliation required`,
+      [stateRel, contractRel],
+    );
+  }
+  const unsupported = freshness.reasons.filter((reason) => !RECONCILABLE_DRIFT.has(reason));
+  if (unsupported.length > 0) {
+    throw reconcileError(
+      "E_RECONCILE_UNSUPPORTED_DRIFT",
+      `reconcile-closure only reconciles repository fingerprint drift; unresolved drift: ${unsupported.join(", ")}`,
+      [stateRel, contractRel],
+    );
+  }
+
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    throw reconcileError(
+      "E_RECONCILE_LEDGER_INVALID",
+      `append-only event ledger must be valid before reconciliation: ${first?.message ?? "invalid ledger"}`,
+      [eventsRel],
+    );
+  }
+
+  const contract = await readContract(target, packageRoot, { taskId });
+  const verificationItem = (contract.value.verification ?? []).find(
+    (item) => item.type === "VERIFICATION" && item.id === checkId && item.text === requirement,
+  );
+  if (!verificationItem) {
+    throw reconcileError(
+      "E_RECONCILE_REQUIREMENT_UNKNOWN",
+      `no contract verification item matches id "${checkId}" with the exact requirement text`,
+      [contractRel],
+    );
+  }
+
+  const execution = await runCommandExecution({
+    target,
+    packageRoot,
+    taskId,
+    checkId,
+    requirement,
+    verificationCycle: state.verificationCycle ?? 1,
+    argv,
+    details,
+    authorityContext,
+    runtimeContext,
+  });
+  if (execution.execution.status !== "passed") {
+    throw reconcileError(
+      "E_RECONCILE_EVIDENCE_FAILED",
+      `objective-satisfaction evidence failed (exit ${execution.execution.exitCode ?? "not-started"}): ${execution.result}`,
+      [execution.path],
+    );
+  }
+
+  const repository = await currentRepositoryFingerprint(target);
+  const previous = state.repositoryFingerprint;
+
+  await appendProtocolEvent(target, {
+    taskId,
+    event: RECONCILE_EVENT,
+    details: {
+      previousBranch: previous?.branch ?? null,
+      previousHead: previous?.head ?? null,
+      currentBranch: repository.branch,
+      currentHead: repository.head,
+      checkId,
+      requirement,
+      command: argv.join(" "),
+      exitCode: execution.execution.exitCode ?? 0,
+      executionId: execution.execution.executionId,
+    },
+  }, packageRoot, { taskId });
+
+  await writeWorkState(target, {
+    ...state,
+    repositoryFingerprint: repository,
+    lastUpdated: new Date().toISOString(),
+  }, { packageRoot, taskId });
+
+  return {
+    taskId,
+    phase: state.phase,
+    reconciled: true,
+    previousRepositoryFingerprint: previous,
+    repositoryFingerprint: repository,
+    checkId,
+    requirement,
+    executionId: execution.execution.executionId,
+    executionPath: execution.path,
+    event: RECONCILE_EVENT,
+  };
+}

package/src/core/schema-validation.js

@@ -24,6 +24,11 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "event",
   "activation",
   "policy",
+  "policy-rules",
+  "policy-discovery",
+  "policy-baseline",
+  "policy-lock",
+  "policy-snapshot",
   "task-bundle",
   "execution",
   "authority",
@@ -40,6 +45,7 @@ export class SchemaValidationError extends Error {
 }
 
 function typeMatches(value, type) {
+  if (Array.isArray(type)) return type.some((t) => typeMatches(value, t));
   if (type === "object") return value !== null && typeof value === "object" && !Array.isArray(value);
   if (type === "array") return Array.isArray(value);
   if (type === "integer") return Number.isInteger(value);

package/src/core/settlement-model.js

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+
+export function normalizeDecisionText(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    const error = new Error("Decision text must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  return value.trim().replace(/\s+/gu, " ").toLowerCase();
+}
+
+export function decisionId(decisionText) {
+  const normalized = normalizeDecisionText(decisionText);
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return `decision-${hash}`;
+}
+
+export function normalizeDecisionCriterionInput(input) {
+  if (!input || typeof input !== "object") {
+    const error = new Error("Decision criterion input must be an object");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof input.decision !== "string" || !input.decision.trim()) {
+    const error = new Error("decision must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof input.settledBy !== "string" || !input.settledBy.trim()) {
+    const error = new Error("settledBy must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  return {
+    decision: input.decision.trim(),
+    settledBy: input.settledBy.trim(),
+  };
+}
+
+export function assertDecisionCriterionDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    const error = new Error("Decision criterion details must be an object");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof details.decision !== "string" || !details.decision.trim()) {
+    const error = new Error("Decision criterion decision must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  const expectedId = decisionId(details.decision);
+  if (details.decisionId !== expectedId) {
+    const error = new Error(`Decision criterion decisionId "${details.decisionId}" does not match computed "${expectedId}"`);
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof details.settledBy !== "string" || !details.settledBy.trim()) {
+    const error = new Error("Decision criterion settledBy must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof details.contractFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(details.contractFingerprint)) {
+    const error = new Error("Decision criterion contractFingerprint must be a 64-char hex string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  return details;
+}
+
+export function decisionCriterionEvents(events, taskId) {
+  if (!Array.isArray(events)) return [];
+  return events.filter((e) => e.event === "DECISION_CRITERION_RECORDED" && (!taskId || e.taskId === taskId));
+}
+
+export function criterionForDecision(events, taskId, decisionText, contractFingerprint) {
+  const decId = decisionId(decisionText);
+  const taskEvents = decisionCriterionEvents(events, taskId);
+  for (let i = taskEvents.length - 1; i >= 0; i--) {
+    const details = taskEvents[i].details;
+    if (details?.decisionId === decId && (!contractFingerprint || details?.contractFingerprint === contractFingerprint)) {
+      return details;
+    }
+  }
+  return null;
+}