@cassiomc1/forgeloop 1.2.1 → 1.2.2

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/error-codes.js

@@ -39,6 +39,15 @@ export const E_PROGRESS_STALLED = "E_PROGRESS_STALLED";
 export const E_DECISION_CRITERION_INVALID = "E_DECISION_CRITERION_INVALID";
 export const E_DECISION_NOT_UNRESOLVED = "E_DECISION_NOT_UNRESOLVED";
 
+export const E_RECONCILE_NOT_STALE = "E_RECONCILE_NOT_STALE";
+export const E_RECONCILE_PHASE_INVALID = "E_RECONCILE_PHASE_INVALID";
+export const E_RECONCILE_UNSUPPORTED_DRIFT = "E_RECONCILE_UNSUPPORTED_DRIFT";
+export const E_RECONCILE_LEDGER_INVALID = "E_RECONCILE_LEDGER_INVALID";
+export const E_RECONCILE_REQUIREMENT_UNKNOWN = "E_RECONCILE_REQUIREMENT_UNKNOWN";
+export const E_RECONCILE_EVIDENCE_FAILED = "E_RECONCILE_EVIDENCE_FAILED";
+export const E_REPOSITORY_CHANGED = "E_REPOSITORY_CHANGED";
+export const E_STATE_REVALIDATION_REQUIRED = "E_STATE_REVALIDATION_REQUIRED";
+
 /**
  * Public, stable ForgeLoop error and reason codes documented for users and harnesses.
  */
@@ -169,6 +178,62 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
     meaning: "Modified paths in repository exceed the declared task write claims.",
     safeResolution: "Update write claims with forgeloop task-scope or revert out-of-scope modifications.",
   }),
+  E_RECONCILE_NOT_STALE: Object.freeze({
+    code: "E_RECONCILE_NOT_STALE",
+    category: "lifecycle",
+    classification: "PUBLIC_STABLE",
+    meaning: "reconcile-closure was invoked for a work-state checkpoint that is already fresh.",
+    safeResolution: "No reconciliation is required; continue the normal lifecycle.",
+  }),
+  E_RECONCILE_PHASE_INVALID: Object.freeze({
+    code: "E_RECONCILE_PHASE_INVALID",
+    category: "lifecycle",
+    classification: "PUBLIC_STABLE",
+    meaning: "reconcile-closure was invoked for a task that is not EXECUTING.",
+    safeResolution: "reconcile-closure supports EXECUTING tasks whose objective is already satisfied.",
+  }),
+  E_RECONCILE_UNSUPPORTED_DRIFT: Object.freeze({
+    code: "E_RECONCILE_UNSUPPORTED_DRIFT",
+    category: "freshness",
+    classification: "PUBLIC_STABLE",
+    meaning: "Work-state drift includes kinds other than REPOSITORY_CHANGED (contract or required-artifact drift).",
+    safeResolution: "Resolve contract or artifact drift through their dedicated recovery surfaces; reconcile-closure only refreshes repository fingerprint drift.",
+  }),
+  E_RECONCILE_LEDGER_INVALID: Object.freeze({
+    code: "E_RECONCILE_LEDGER_INVALID",
+    category: "integrity",
+    classification: "PUBLIC_STABLE",
+    meaning: "The append-only event ledger is not valid, so reconciliation cannot be recorded.",
+    safeResolution: "Inspect the ledger errors and repair before reconciling.",
+  }),
+  E_RECONCILE_REQUIREMENT_UNKNOWN: Object.freeze({
+    code: "E_RECONCILE_REQUIREMENT_UNKNOWN",
+    category: "verification",
+    classification: "PUBLIC_STABLE",
+    meaning: "The supplied check id and requirement text do not exactly match a contract verification item of type VERIFICATION.",
+    safeResolution: "Supply the exact id and requirement text of an existing contract verification item.",
+  }),
+  E_RECONCILE_EVIDENCE_FAILED: Object.freeze({
+    code: "E_RECONCILE_EVIDENCE_FAILED",
+    category: "verification",
+    classification: "PUBLIC_STABLE",
+    meaning: "The executed objective-satisfaction evidence command did not pass.",
+    safeResolution: "Inspect the execution artifact; reconciliation is refused until evidence passes in the current repository.",
+  }),
+  E_REPOSITORY_CHANGED: Object.freeze({
+    code: "E_REPOSITORY_CHANGED",
+    category: "freshness",
+    classification: "PUBLIC_STABLE",
+    meaning: "The repository fingerprint (branch or HEAD) moved after the work-state checkpoint was recorded.",
+    safeResolution: "If the task objective is already satisfied in the current repository, run forgeloop reconcile-closure; otherwise resume from a checkpoint that matches the current repository.",
+  }),
+  E_STATE_REVALIDATION_REQUIRED: Object.freeze({
+    code: "E_STATE_REVALIDATION_REQUIRED",
+    category: "freshness",
+    classification: "PUBLIC_STABLE",
+    meaning: "The work-state checkpoint must be revalidated before the lifecycle can continue.",
+    safeResolution: "Run forgeloop reconcile-closure for externally satisfied EXECUTING tasks, or inspect the freshness reasons for other drift.",
+  }),
   E_DIAGNOSIS_REQUIRED: Object.freeze({
     code: "E_DIAGNOSIS_REQUIRED",
     category: "diagnosis",
@@ -225,8 +290,145 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
     meaning: "A settlement criterion referenced a decision not present in current unresolvedDecisions.",
     safeResolution: "Use the exact current unresolved decision text or update the contract first.",
   }),
+  E_CHECK_INERT: Object.freeze({
+    code: "E_CHECK_INERT",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "An enabled check has no effective scope or target files.",
+    safeResolution: "Provide an applicable target scope, configure matching files, or mark the rule unsupported.",
+  }),
+  E_CHECK_MUTATION_NOT_DETECTED: Object.freeze({
+    code: "E_CHECK_MUTATION_NOT_DETECTED",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "A blocking rule checker failed to detect an intentional mutation fixture.",
+    safeResolution: "Fix checker logic to properly identify target violations.",
+  }),
+  E_POLICY_DRIFT: Object.freeze({
+    code: "E_POLICY_DRIFT",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Active policy lock does not match the policy snapshot captured at task activation.",
+    safeResolution: "Re-verify affected checks or restore original policy.",
+  }),
+  E_POLICY_WEAKENING: Object.freeze({
+    code: "E_POLICY_WEAKENING",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Policy rules were weakened during task execution without explicit authority.",
+    safeResolution: "Restore the original policy configuration.",
+  }),
+  E_POLICY_LOCK_INVALID: Object.freeze({
+    code: "E_POLICY_LOCK_INVALID",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Policy lockfile is missing, malformed, or corrupt.",
+    safeResolution: "Run forgeloop policy-status or regenerate policy.lock.",
+  }),
+  E_NEW_POLICY_VIOLATION: Object.freeze({
+    code: "E_NEW_POLICY_VIOLATION",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "New executable policy violation detected that is not present in brownfield baseline.",
+    safeResolution: "Fix the violation before completing the task.",
+  }),
+  E_BASELINE_EXPANSION: Object.freeze({
+    code: "E_BASELINE_EXPANSION",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Attempted unauthorized addition of new violations to brownfield baseline.",
+    safeResolution: "Resolve new violations rather than expanding the baseline.",
+  }),
+  E_POLICY_PROOF_STALE: Object.freeze({
+    code: "E_POLICY_PROOF_STALE",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Mutation verification proof is stale due to checker or fixture modifications.",
+    safeResolution: "Re-run forgeloop rule-verify to refresh mutation proof.",
+  }),
+  E_CHECK_MUTATION_EXECUTION_ERROR: Object.freeze({
+    code: "E_CHECK_MUTATION_EXECUTION_ERROR",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "A policy checker threw an unhandled exception while evaluating its mutation fixture.",
+    safeResolution: "Repair the checker execution path and rerun rule verification.",
+  }),
+  E_POLICY_EVALUATION_FAILED: Object.freeze({
+    code: "E_POLICY_EVALUATION_FAILED",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Policy evaluation threw an unexpected error during execution.",
+    safeResolution: "Inspect policy configuration and checker adapters for unhandled errors.",
+  }),
+  E_POLICY_INVALID: Object.freeze({
+    code: "E_POLICY_INVALID",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Policy artifact is malformed, corrupt, or schema-invalid.",
+    safeResolution: "Validate and repair rules.json, baseline.json, or discovery.json against schema.",
+  }),
+  E_POLICY_SNAPSHOT_WRITE_FAILED: Object.freeze({
+    code: "E_POLICY_SNAPSHOT_WRITE_FAILED",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Failed to persist task policy snapshot during preflight.",
+    safeResolution: "Ensure the target task directory is writable and repair filesystem permissions.",
+  }),
+  E_POLICY_LOCK_MISMATCH: Object.freeze({
+    code: "E_POLICY_LOCK_MISMATCH",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Persisted policy lock digest does not match current effective policy state.",
+    safeResolution: "Re-evaluate effective rules and update policy.lock or restore modified rules.",
+  }),
+  E_POLICY_DRIFT_UNKNOWN: Object.freeze({
+    code: "E_POLICY_DRIFT_UNKNOWN",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Task policy drift was detected but baseline snapshot details are unavailable.",
+    safeResolution: "Re-verify the task under the current policy state.",
+  }),
+  E_BASELINE_RECORD_DURING_ACTIVE_TASK: Object.freeze({
+    code: "E_BASELINE_RECORD_DURING_ACTIVE_TASK",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Cannot re-record baseline during an active task with policy snapshot.",
+    safeResolution: "Resolve new violations or use monotonic baseline --update.",
+  }),
+  E_POLICY_INITIALIZATION_FAILED: Object.freeze({
+    code: "E_POLICY_INITIALIZATION_FAILED",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Executable policy bootstrap could not complete during initialization.",
+    safeResolution: "Repair the reported filesystem/schema error and rerun `forgeloop init`. Initialization is restartable while no committed manifest exists.",
+  }),
+  E_INIT_KIT_CONFLICT: Object.freeze({
+    code: "E_INIT_KIT_CONFLICT",
+    category: "project-maintenance",
+    classification: "PUBLIC_STABLE",
+    meaning: "A canonical ForgeLoop kit destination already exists with content that does not match the shipped canonical template.",
+    safeResolution: "Inspect the conflicting `.forgeloop/kit/...` file. If it is stale or partial ForgeLoop output, remove or restore it and rerun `forgeloop init`. Do not overwrite unknown content automatically.",
+  }),
 });
 
+export const E_CHECK_INERT = "E_CHECK_INERT";
+export const E_CHECK_MUTATION_NOT_DETECTED = "E_CHECK_MUTATION_NOT_DETECTED";
+export const E_POLICY_DRIFT = "E_POLICY_DRIFT";
+export const E_POLICY_WEAKENING = "E_POLICY_WEAKENING";
+export const E_POLICY_LOCK_INVALID = "E_POLICY_LOCK_INVALID";
+export const E_NEW_POLICY_VIOLATION = "E_NEW_POLICY_VIOLATION";
+export const E_BASELINE_EXPANSION = "E_BASELINE_EXPANSION";
+export const E_POLICY_PROOF_STALE = "E_POLICY_PROOF_STALE";
+export const E_CHECK_MUTATION_EXECUTION_ERROR = "E_CHECK_MUTATION_EXECUTION_ERROR";
+export const E_POLICY_EVALUATION_FAILED = "E_POLICY_EVALUATION_FAILED";
+export const E_POLICY_INVALID = "E_POLICY_INVALID";
+export const E_POLICY_SNAPSHOT_WRITE_FAILED = "E_POLICY_SNAPSHOT_WRITE_FAILED";
+export const E_POLICY_LOCK_MISMATCH = "E_POLICY_LOCK_MISMATCH";
+export const E_POLICY_DRIFT_UNKNOWN = "E_POLICY_DRIFT_UNKNOWN";
+export const E_BASELINE_RECORD_DURING_ACTIVE_TASK = "E_BASELINE_RECORD_DURING_ACTIVE_TASK";
+export const E_POLICY_INITIALIZATION_FAILED = "E_POLICY_INITIALIZATION_FAILED";
+export const E_INIT_KIT_CONFLICT = "E_INIT_KIT_CONFLICT";
+
 export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   ...FAILURE_CODES,
   E_VERIFICATION_TOOL_UNAVAILABLE,
@@ -255,8 +457,33 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_SCOPE_DIRTY,
   E_TASK_SCOPE_FROZEN,
   E_TASK_CHANGE_OUTSIDE_SCOPE,
+  E_RECONCILE_NOT_STALE,
+  E_RECONCILE_PHASE_INVALID,
+  E_RECONCILE_UNSUPPORTED_DRIFT,
+  E_RECONCILE_LEDGER_INVALID,
+  E_RECONCILE_REQUIREMENT_UNKNOWN,
+  E_RECONCILE_EVIDENCE_FAILED,
+  E_REPOSITORY_CHANGED,
+  E_STATE_REVALIDATION_REQUIRED,
   E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE,
   E_TASK_LAYOUT_LEGACY,
   E_TASK_MIGRATION_INVALID,
   E_TASK_MIGRATION_IDENTITY_MISMATCH,
+  E_CHECK_INERT,
+  E_CHECK_MUTATION_NOT_DETECTED,
+  E_POLICY_DRIFT,
+  E_POLICY_WEAKENING,
+  E_POLICY_LOCK_INVALID,
+  E_NEW_POLICY_VIOLATION,
+  E_BASELINE_EXPANSION,
+  E_POLICY_PROOF_STALE,
+  E_CHECK_MUTATION_EXECUTION_ERROR,
+  E_POLICY_EVALUATION_FAILED,
+  E_POLICY_INVALID,
+  E_POLICY_SNAPSHOT_WRITE_FAILED,
+  E_POLICY_LOCK_MISMATCH,
+  E_POLICY_DRIFT_UNKNOWN,
+  E_BASELINE_RECORD_DURING_ACTIVE_TASK,
+  E_POLICY_INITIALIZATION_FAILED,
+  E_INIT_KIT_CONFLICT,
 ]));

package/src/core/events.js

@@ -49,11 +49,33 @@ export function validateKnownEventDetails(event) {
     case "DECISION_CRITERION_RECORDED":
       assertDecisionCriterionDetails(event.details);
       return;
+    case "CHECKPOINT_RECONCILED":
+      assertReconcileClosureDetails(event.details);
+      return;
     default:
       return;
   }
 }
 
+function assertReconcileClosureDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    throw protocolError("E_EVENT_INVALID", "CHECKPOINT_RECONCILED requires structured details");
+  }
+  for (const key of ["checkId", "command", "executionId"]) {
+    if (typeof details[key] !== "string") {
+      throw protocolError("E_EVENT_INVALID", `CHECKPOINT_RECONCILED details.${key} must be a string`);
+    }
+  }
+  for (const key of ["previousBranch", "currentBranch", "previousHead", "currentHead"]) {
+    if (typeof details[key] !== "string" && details[key] !== null) {
+      throw protocolError("E_EVENT_INVALID", `CHECKPOINT_RECONCILED details.${key} must be a string or null`);
+    }
+  }
+  if (typeof details.exitCode !== "number" || !Number.isInteger(details.exitCode) || details.exitCode < 0) {
+    throw protocolError("E_EVENT_INVALID", "CHECKPOINT_RECONCILED details.exitCode must be a non-negative integer");
+  }
+}
+
 function eventHash(event) {
   const { hash, ...body } = event;
   return canonicalFingerprint(body);

package/src/core/execution-prerequisites.js

@@ -5,6 +5,7 @@ import { evaluatePreflight, validatePersistedPreflight } from "./preflight.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { stateIdentityErrors } from "./completion-relationships.js";
 import { classifyLoadedWorkState } from "./work-state.js";
+import { taskArtifactPath } from "./task-paths.js";
 
 const START_EXECUTION_EVENTS = Object.freeze([
   "CONTRACT_VALIDATED",
@@ -128,34 +129,51 @@ function prerequisiteLedgerErrors(ledger, taskId, preflight, route) {
   return errors;
 }
 
-export async function evaluateStartExecutionPrerequisites({ target, state, packageRoot } = {}) {
+export async function evaluateStartExecutionPrerequisites({
+  target,
+  state,
+  packageRoot,
+  taskId = null,
+  contractPath = null,
+  routePath = null,
+  statePath = null,
+  preflightPath = null,
+  eventsPath = null,
+} = {}) {
+  const effectiveTaskId = taskId ?? null;
+  const contractRel = contractPath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "contract") : ARTIFACT_PATHS.contract);
+  const routeRel = routePath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "route") : ARTIFACT_PATHS.route);
+  const stateRel = statePath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "state") : ARTIFACT_PATHS.state);
+  const preflightRel = preflightPath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "preflight") : ARTIFACT_PATHS.preflight);
+  const eventsRel = eventsPath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "events") : ARTIFACT_PATHS.events);
+
   const errors = [];
   const requiredArtifacts = [
-    ARTIFACT_PATHS.state,
-    ARTIFACT_PATHS.contract,
-    ARTIFACT_PATHS.route,
-    ARTIFACT_PATHS.preflight,
-    ARTIFACT_PATHS.events,
+    stateRel,
+    contractRel,
+    routeRel,
+    preflightRel,
+    eventsRel,
   ];
   if (!state) {
     return {
-      errors: [issue("E_PHASE_PREREQUISITE_MISSING", "EXECUTING requires a work state", [ARTIFACT_PATHS.state])],
+      errors: [issue("E_PHASE_PREREQUISITE_MISSING", "EXECUTING requires a work state", [stateRel])],
       requiredArtifacts,
     };
   }
 
   const contract = await load(
-    () => readContract(target, packageRoot),
+    () => readContract(target, packageRoot, { taskId: effectiveTaskId, contractPath }),
     "E_PHASE_PREREQUISITE_MISSING",
-    `EXECUTING requires ${ARTIFACT_PATHS.contract}`,
-    [ARTIFACT_PATHS.contract],
+    `EXECUTING requires ${contractRel}`,
+    [contractRel],
     errors,
   );
   const route = await load(
-    () => readPersistedRoute(target, packageRoot),
+    () => readPersistedRoute(target, packageRoot, { taskId: effectiveTaskId, routePath }),
     "E_PHASE_PREREQUISITE_MISSING",
-    `EXECUTING requires ${ARTIFACT_PATHS.route}`,
-    [ARTIFACT_PATHS.route],
+    `EXECUTING requires ${routeRel}`,
+    [routeRel],
     errors,
   );
   if (!contract || !route) return { errors, requiredArtifacts, contract, route };
@@ -164,7 +182,7 @@ export async function evaluateStartExecutionPrerequisites({ target, state, packa
     errors.push(issue(
       "E_ROUTE_STALE",
       "EXECUTING requires work state and route to match the current contract",
-      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.route, ARTIFACT_PATHS.contract],
+      [stateRel, routeRel, contractRel],
     ));
   }
   errors.push(...stateIdentityErrors({ contract, route, state }));
@@ -172,14 +190,14 @@ export async function evaluateStartExecutionPrerequisites({ target, state, packa
   const freshness = await classifyLoadedWorkState({
     target,
     state,
-    contractFile: ARTIFACT_PATHS.contract,
+    contractFile: contractRel,
   });
   errors.push(...freshnessErrors(state, freshness));
 
-  const preflight = await evaluatePreflight({ target, packageRoot });
+  const preflight = await evaluatePreflight({ target, packageRoot, taskId: effectiveTaskId, contractPath, routePath, statePath });
   let persistedPreflight = null;
   try {
-    persistedPreflight = await readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot);
+    persistedPreflight = await readJsonArtifact(target, preflightRel, "preflight", packageRoot);
   } catch {
     // validatePersistedPreflight reports the stable, actionable preflight reason.
   }
@@ -189,16 +207,16 @@ export async function evaluateStartExecutionPrerequisites({ target, state, packa
     errors.push(issue(
       "E_PREFLIGHT_GATES_STALE",
       "Work state gate sets do not match the current preflight evaluation",
-      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.gates],
+      [stateRel, preflightRel, ARTIFACT_PATHS.gates],
     ));
   }
 
-  const ledger = await validateEventLedger(target, packageRoot);
+  const ledger = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId, eventsPath });
   errors.push(...prerequisiteLedgerErrors(ledger, contract.value.taskId, preflight, route));
   errors.push(...validateStateLedgerCoherence(state, ledger.events).map((error) => issue(
     error.code,
     error.message,
-    [ARTIFACT_PATHS.state, ARTIFACT_PATHS.events],
+    [stateRel, eventsRel],
   )));
   errors.push(...persistedPreflightErrors);
   return { errors, requiredArtifacts, contract, route, preflight, persistedPreflight, ledger };

package/src/core/execution.js

@@ -2,14 +2,14 @@ import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { readdir } from "node:fs/promises";
 import path from "node:path";
-import { fileExists } from "./filesystem.js";
+import { ensureWithin, fileExists } from "./filesystem.js";
 import {
   ARTIFACT_PATHS,
   executionArtifactPath,
   readJsonArtifact,
   writeJsonArtifact,
 } from "./artifacts.js";
-import { taskExecutionPath } from "./task-paths.js";
+import { taskArtifactPath, taskExecutionPath } from "./task-paths.js";
 import {
   resolveExecutionResolution,
   validateVerificationAuthority,
@@ -77,6 +77,23 @@ function executeProcess(argv, cwd) {
   });
 }
 
+/**
+ * Resolves where a new execution artifact should be written. Task-scoped
+ * execution artifacts require a real modern task namespace (a task.json
+ * descriptor). A descriptor-less task is legacy: writing task-scoped here
+ * would create a phantom `.forgeloop/task-state/<key>/executions/` namespace
+ * that corrupts task discovery. Reads already fall back across both
+ * locations, so a legacy execution stays resolvable.
+ */
+export async function resolveExecutionArtifactPath(target, taskId, executionId) {
+  if (!taskId) return executionArtifactPath(executionId);
+  const descriptorRel = taskArtifactPath(taskId, "descriptor");
+  if (await fileExists(ensureWithin(target, descriptorRel))) {
+    return taskExecutionPath(taskId, executionId);
+  }
+  return executionArtifactPath(executionId);
+}
+
 export async function runCommandExecution({
   target,
   packageRoot,
@@ -153,7 +170,7 @@ export async function runCommandExecution({
     status: processResult.exitCode === 0 && !processResult.spawnError ? "passed" : "failed",
     exitCode: processResult.exitCode,
   };
-  const execPath = executionPath ?? (taskId ? taskExecutionPath(taskId, executionId) : executionArtifactPath(executionId));
+  const execPath = executionPath ?? await resolveExecutionArtifactPath(target, taskId, executionId);
   const written = await writeJsonArtifact(target, execPath, execution, "execution", packageRoot);
   return {
     path: written.path,

package/src/core/native-adapters.js

@@ -41,10 +41,20 @@ Before changing product or executable files, establish the ForgeLoop contract,
 route, required gates, and READY preflight.
 
 Before creating or activating new lifecycle state:
-If \`.forgeloop/work-state.json\` exists, inspect the existing task,
-reconcile continuity when present, inspect the checkout, and run
-\`forgeloop next\`. A change of harness, model, provider, IDE, process,
-terminal, or session does not create a new task.
+
+1. Inspect existing ForgeLoop tasks first.
+2. Use \`forgeloop task-list --json\` to discover current task namespaces.
+3. If an existing task is selected or identifiable, use
+   \`forgeloop next --task <id> --json\` before creating another task.
+4. Reconcile continuity when the selected task has continuity state.
+5. Inspect the checkout before resuming work.
+
+A change of harness, model, provider, IDE, process, terminal, or session
+does not create a new task.
+
+Legacy singleton state such as \`.forgeloop/work-state.json\` remains
+supported only for backward compatibility and must not be treated as the
+primary modern discovery mechanism.
 
 Use the project-local ForgeLoop CLI for lifecycle-owned protocol state.
 Never manually synthesize lifecycle chronology or assign ForgeLoop COMPLETE.

package/src/core/next-action-model.js

@@ -22,6 +22,15 @@ export const NEXT_ACTIONS = Object.freeze({
   RUN_COMPLETE: "RUN_COMPLETE",
   RESOLVE_STALE_ROUTE: "RESOLVE_STALE_ROUTE",
   RESOLVE_BLOCKER: "RESOLVE_BLOCKER",
+  RESTORE_POLICY: "RESTORE_POLICY",
+  REVERIFY_AFTER_POLICY_CHANGE: "REVERIFY_AFTER_POLICY_CHANGE",
+  VERIFY_RULE: "VERIFY_RULE",
+  RESOLVE_INERT_CHECK: "RESOLVE_INERT_CHECK",
+  RUN_REQUIRED_CHECK: "RUN_REQUIRED_CHECK",
+  REPAIR_CHECKER: "REPAIR_CHECKER",
+  REPAIR_POLICY: "REPAIR_POLICY",
+  RESTORE_BASELINE: "RESTORE_BASELINE",
+  CONTINUE_WITH_EXISTING_BASELINE: "CONTINUE_WITH_EXISTING_BASELINE",
   NONE: "NONE",
 });