@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/core/checkpoint-revalidation.js

@@ -0,0 +1,319 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import {
+  resolveCanonicalRouteEvolution,
+  resolveCanonicalPostRepairRouteBinding,
+  resolveEffectiveContractBootstrapRepairAnchor,
+} from "./contract-bootstrap-recovery.js";
+import { resolveCanonicalContractEvolution } from "./contract-revision.js";
+
+export const CHECKPOINT_REVALIDATED_EVENT = "CHECKPOINT_REVALIDATED";
+export const CHECKPOINT_REVALIDATION_PHASES = Object.freeze(["ROUTED"]);
+
+const REPOSITORY_FINGERPRINT_KEYS = Object.freeze(["branch", "head"]);
+const REVALIDATION_DETAIL_KEYS = Object.freeze([
+  "phase",
+  "previousRepositoryFingerprint",
+  "repositoryFingerprint",
+  "contractFingerprint",
+  "routeFingerprint",
+  "previousStateRevision",
+  "revalidatedStateRevision",
+  "previousStateFingerprint",
+  "revalidatedStateFingerprint",
+]);
+
+function invalid(message) {
+  const error = new Error(message);
+  error.code = "E_CHECKPOINT_REVALIDATION_UNSAFE";
+  return error;
+}
+
+function isFingerprint(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+
+export function assertRepositoryFingerprint(value, label = "repository fingerprint", { requireHead = false } = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).length !== REPOSITORY_FINGERPRINT_KEYS.length
+    || REPOSITORY_FINGERPRINT_KEYS.some((key) => !Object.prototype.hasOwnProperty.call(value, key))) {
+    throw invalid(`${label} must contain exactly branch and head`);
+  }
+  for (const key of REPOSITORY_FINGERPRINT_KEYS) {
+    if (value[key] !== null && (typeof value[key] !== "string" || !value[key].trim())) {
+      throw invalid(`${label}.${key} must be a non-empty string or null`);
+    }
+  }
+  if (requireHead && typeof value.head !== "string") {
+    throw invalid(`${label}.head must be available`);
+  }
+  return value;
+}
+
+export function assertCheckpointRevalidatedDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== REVALIDATION_DETAIL_KEYS.length
+    || REVALIDATION_DETAIL_KEYS.some((key) => !Object.prototype.hasOwnProperty.call(details, key))) {
+    throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} requires its exact state-transition detail set`);
+  }
+  if (!CHECKPOINT_REVALIDATION_PHASES.includes(details.phase)) {
+    throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} details.phase is unsupported`);
+  }
+  assertRepositoryFingerprint(details.previousRepositoryFingerprint, `${CHECKPOINT_REVALIDATED_EVENT} details.previousRepositoryFingerprint`);
+  assertRepositoryFingerprint(details.repositoryFingerprint, `${CHECKPOINT_REVALIDATED_EVENT} details.repositoryFingerprint`, { requireHead: true });
+  if (JSON.stringify(details.previousRepositoryFingerprint) === JSON.stringify(details.repositoryFingerprint)) {
+    throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} must record repository drift`);
+  }
+  for (const key of ["contractFingerprint", "routeFingerprint", "previousStateFingerprint", "revalidatedStateFingerprint"]) {
+    if (!isFingerprint(details[key])) throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} details.${key} must be a lowercase SHA-256 fingerprint`);
+  }
+  for (const key of ["previousStateRevision", "revalidatedStateRevision"]) {
+    if (!Number.isInteger(details[key]) || details[key] < 0) {
+      throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} details.${key} must be a non-negative integer`);
+    }
+  }
+  if (details.revalidatedStateRevision !== details.previousStateRevision + 1) {
+    throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} state revisions must advance exactly once`);
+  }
+  return details;
+}
+
+function sameRepositoryFingerprint(left, right) {
+  return left?.branch === right?.branch && left?.head === right?.head;
+}
+
+function bindingError(message) {
+  return { code: "E_CHECKPOINT_REVALIDATION_UNSAFE", message };
+}
+
+function eventHash(event) {
+  const { hash, ...body } = event ?? {};
+  return canonicalFingerprint(body);
+}
+
+function routeEvolutionAfter(
+  events,
+  sourceEvent,
+  sourceRouteFingerprint,
+  targetRouteFingerprint,
+  targetContractFingerprint = sourceEvent.details?.contractFingerprint,
+) {
+  const sourceIndex = events.indexOf(sourceEvent);
+  if (sourceIndex < 0 || !isFingerprint(sourceRouteFingerprint) || !isFingerprint(targetRouteFingerprint)) {
+    return false;
+  }
+
+  const contractFingerprint = sourceEvent.details?.contractFingerprint;
+  if (targetContractFingerprint !== contractFingerprint) {
+    const contractEvolution = resolveCanonicalContractEvolution(events, {
+      taskId: sourceEvent.taskId,
+      sourceSeq: sourceEvent.seq,
+      sourceContractFingerprint: contractFingerprint,
+      targetContractFingerprint,
+    });
+    if (!contractEvolution?.revisionEvents?.length) return false;
+
+    let currentRouteFingerprint = sourceRouteFingerprint;
+    let currentContractFingerprint = contractFingerprint;
+    let currentSeq = sourceEvent.seq;
+    for (const revisionEvent of contractEvolution.revisionEvents) {
+      const boundaryRouteFingerprint = revisionEvent.details.previousRouteFingerprint;
+      if (!isFingerprint(boundaryRouteFingerprint)) return false;
+      const preRevisionEvents = events.filter((event) => event.seq <= revisionEvent.seq);
+      const preRevisionRoute = resolveCanonicalRouteEvolution(preRevisionEvents, {
+        taskId: sourceEvent.taskId,
+        sourceSeq: currentSeq,
+        sourceRouteFingerprint: currentRouteFingerprint,
+        targetRouteFingerprint: boundaryRouteFingerprint,
+        contractFingerprint: currentContractFingerprint,
+      });
+      if (!preRevisionRoute) return false;
+      currentRouteFingerprint = boundaryRouteFingerprint;
+      currentContractFingerprint = revisionEvent.details.contractFingerprint;
+      currentSeq = revisionEvent.seq;
+    }
+    const postRevisionRoute = resolveCanonicalRouteEvolution(events, {
+      taskId: sourceEvent.taskId,
+      sourceSeq: currentSeq,
+      sourceRouteFingerprint: currentRouteFingerprint,
+      targetRouteFingerprint,
+      contractFingerprint: currentContractFingerprint,
+    });
+    return Boolean(postRevisionRoute);
+  }
+
+  const canonical = resolveCanonicalRouteEvolution(events, {
+    taskId: sourceEvent.taskId,
+    sourceSeq: sourceEvent.seq,
+    sourceRouteFingerprint,
+    targetRouteFingerprint,
+    contractFingerprint,
+  });
+  if (!canonical) return false;
+
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+  if (anchor?.details?.contractFingerprint === contractFingerprint) {
+    const binding = resolveCanonicalPostRepairRouteBinding(
+      events,
+      anchor.sourceMarker,
+      targetRouteFingerprint,
+    );
+    return Boolean(binding?.reboundEvents?.some(({ reboundEvent }) =>
+      reboundEvent.seq > sourceEvent.seq
+      && reboundEvent.details.routeFingerprint === targetRouteFingerprint));
+  }
+  return canonical.valid;
+}
+
+/**
+ * Resolves the only valid transaction witness for a checkpoint revalidation.
+ * The witness is intentionally positional: a later transaction commit cannot
+ * retroactively authorize an earlier revalidation event.
+ */
+export function resolveCheckpointRevalidationBoundary(events = [], revalidationEvent) {
+  const index = events.findIndex((candidate) => candidate === revalidationEvent
+    || (candidate?.seq === revalidationEvent?.seq
+      && candidate?.taskId === revalidationEvent?.taskId
+      && candidate?.event === CHECKPOINT_REVALIDATED_EVENT));
+  if (index < 0) return null;
+  const commitEvent = events[index + 1];
+  if (!commitEvent
+    || revalidationEvent?.event !== CHECKPOINT_REVALIDATED_EVENT
+    || commitEvent.event !== "TRANSACTION_COMMITTED"
+    || commitEvent.seq !== revalidationEvent.seq + 1
+    || commitEvent.previousHash !== revalidationEvent.hash
+    || revalidationEvent.hash !== eventHash(revalidationEvent)
+    || commitEvent.hash !== eventHash(commitEvent)
+    || commitEvent.taskId !== revalidationEvent.taskId
+    || typeof commitEvent.details?.transactionId !== "string"
+    || !commitEvent.details.transactionId
+    || commitEvent.details.operation !== "checkpoint-revalidate") {
+    return null;
+  }
+  return { revalidationEvent, transactionCommitEvent: commitEvent };
+}
+
+export function validateCheckpointRevalidationEventBindings(events = []) {
+  const errors = [];
+  const revalidations = events.filter((event) => event.event === CHECKPOINT_REVALIDATED_EVENT);
+  for (let index = 0; index < revalidations.length; index += 1) {
+    const event = revalidations[index];
+    let details;
+    try {
+      details = assertCheckpointRevalidatedDetails(event.details);
+    } catch (error) {
+      errors.push(bindingError(`event ${event.seq}: ${error.message}`));
+      continue;
+    }
+    if (!resolveCheckpointRevalidationBoundary(events, event)) {
+      errors.push(bindingError(`event ${event.seq} must be immediately followed by its checkpoint-revalidate transaction commit`));
+    }
+    const previous = revalidations[index - 1]?.details;
+    if (previous) {
+      if (!sameRepositoryFingerprint(details.previousRepositoryFingerprint, previous.repositoryFingerprint)) {
+        errors.push(bindingError(`event ${event.seq} is disconnected from the previous checkpoint revalidation repository`));
+      }
+      if (details.previousStateRevision < previous.revalidatedStateRevision) {
+        errors.push(bindingError(`event ${event.seq} rolls back the previous checkpoint revalidation revision`));
+      }
+      if (details.previousStateRevision === previous.revalidatedStateRevision
+        && details.previousStateFingerprint !== previous.revalidatedStateFingerprint) {
+        errors.push(bindingError(`event ${event.seq} does not continue the previous checkpoint revalidation state fingerprint`));
+      }
+      const contractEvolved = details.contractFingerprint !== previous.contractFingerprint
+        && resolveCanonicalContractEvolution(events, {
+          taskId: event.taskId,
+          sourceSeq: revalidations[index - 1].seq,
+          sourceContractFingerprint: previous.contractFingerprint,
+          targetContractFingerprint: details.contractFingerprint,
+        });
+      if (details.contractFingerprint !== previous.contractFingerprint && !contractEvolved) {
+        errors.push(bindingError(`event ${event.seq} changes the checkpoint revalidation contract identity without canonical contract provenance`));
+      }
+      if (details.routeFingerprint !== previous.routeFingerprint) {
+        const evolved = details.previousStateRevision > previous.revalidatedStateRevision
+          && routeEvolutionAfter(
+            events,
+            revalidations[index - 1],
+            previous.routeFingerprint,
+            details.routeFingerprint,
+            details.contractFingerprint,
+          );
+        if (!evolved) {
+          errors.push(bindingError(`event ${event.seq} changes the checkpoint revalidation route identity without canonical route provenance`));
+        }
+      }
+    } else {
+      const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+      if (anchor?.details?.reconstructedStateRevision === details.previousStateRevision
+        && anchor.details.reconstructedStateFingerprint !== details.previousStateFingerprint) {
+        errors.push(bindingError(`event ${event.seq} does not bind the repaired checkpoint state fingerprint`));
+      }
+    }
+  }
+  return errors;
+}
+
+function validateCurrentContractBinding(state, events, event) {
+  const details = event.details;
+  if (!state?.contractFingerprint || details?.contractFingerprint === state.contractFingerprint) return null;
+  const evolved = Number.isInteger(state.revision)
+    && Number.isInteger(details?.revalidatedStateRevision)
+    && state.revision > details.revalidatedStateRevision
+    && resolveCanonicalContractEvolution(events, {
+      taskId: event.taskId,
+      sourceSeq: event.seq,
+      sourceContractFingerprint: details.contractFingerprint,
+      targetContractFingerprint: state.contractFingerprint,
+    });
+  return evolved ? null : bindingError(`event ${event.seq} does not bind the current contract identity through canonical contract provenance`);
+}
+
+function validateCurrentRouteBinding(state, events, event) {
+  const details = event.details;
+  if (!state?.routeFingerprint || details?.routeFingerprint === state.routeFingerprint) return null;
+  const routeChangedAfterCheckpoint = Number.isInteger(state.revision)
+    && Number.isInteger(details?.revalidatedStateRevision)
+    && state.revision > details.revalidatedStateRevision;
+  const evolved = routeChangedAfterCheckpoint
+    && routeEvolutionAfter(events, event, details.routeFingerprint, state.routeFingerprint, state.contractFingerprint);
+  return evolved ? null : bindingError(`event ${event.seq} does not bind the current route identity through canonical route provenance`);
+}
+
+function validateLatestCheckpointBinding(state, latest) {
+  if (!state || !latest || state.revision !== latest.details.revalidatedStateRevision) return [];
+  const details = latest.details;
+  const errors = [];
+  if (!sameRepositoryFingerprint(state.repositoryFingerprint, details.repositoryFingerprint)) {
+    errors.push(bindingError(`event ${latest.seq} does not bind the current repository fingerprint`));
+  }
+  if (state.phase !== details.phase || canonicalFingerprint(state) !== details.revalidatedStateFingerprint) {
+    errors.push(bindingError(`event ${latest.seq} does not bind the current checkpoint state`));
+  }
+  return errors;
+}
+
+export function validateCheckpointRevalidationCurrentBinding(state, events = []) {
+  const errors = [];
+  const revalidations = events.filter((event) => event.event === CHECKPOINT_REVALIDATED_EVENT);
+  const latest = revalidations.at(-1);
+  for (const event of revalidations) {
+    const contractError = validateCurrentContractBinding(state, events, event);
+    if (contractError) errors.push(contractError);
+    const routeError = validateCurrentRouteBinding(state, events, event);
+    if (routeError) errors.push(routeError);
+  }
+  errors.push(...validateLatestCheckpointBinding(state, latest));
+  return errors;
+}
+
+/**
+ * Validates the semantic chain of checkpoint-revalidation events. The event
+ * hash proves bytes were not changed accidentally; these checks prove that a
+ * rehashed event still describes a valid state transition.
+ */
+export function validateCheckpointRevalidationBindings(state, events = []) {
+  return [
+    ...validateCheckpointRevalidationEventBindings(events),
+    ...validateCheckpointRevalidationCurrentBinding(state, events),
+  ];
+}

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

@@ -71,6 +71,188 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Reports versioning, lifecycle, command, guide, and public error compatibility metadata for external harnesses.",
   }),
+  "decision-status": Object.freeze({
+    name: "decision-status",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--health": Object.freeze({ targetKey: "health", parseType: "boolean", takesValue: false, description: "perform a bounded live Jev health check when credentials are configured" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit decision-plane status as JSON" }),
+    }),
+    writes: [], removes: [], mayExecuteExternalProcess: true,
+    description: "Reports the pinned semantic decision-plane configuration without exposing credentials.",
+  }),
+  "decision-show": Object.freeze({
+    name: "decision-show",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--decision": Object.freeze({ targetKey: "decisionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--decision requires an ID", description: "decision artifact ID" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit the decision artifact as JSON" }),
+    }),
+    writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Shows one persisted semantic decision artifact without performing a live request.",
+  }),
+  "context-plan": Object.freeze({
+    name: "context-plan",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--decision": Object.freeze({ targetKey: "decisionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--decision requires an ID", description: "persisted Jev decision artifact ID" }),
+      "--profile": Object.freeze({ targetKey: "profile", parseType: "string", takesValue: true, valueName: "profile", missingValueMessage: "--profile requires light, balanced, or full", description: "bounded context budget profile" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit the bounded context plan as JSON" }),
+    }),
+    writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Compiles a bounded non-authoritative context plan from deterministic candidates.",
+  }),
+  "model-route": Object.freeze({
+    name: "model-route",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--decision": Object.freeze({ targetKey: "decisionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--decision requires an ID", description: "persisted Jev decision artifact ID" }),
+      "--work": Object.freeze({ targetKey: "workType", parseType: "string", takesValue: true, valueName: "type", missingValueMessage: "--work requires a type", description: "declared work type" }),
+      "--surface": Object.freeze({ targetKey: "surfaces", parseType: "string", takesValue: true, valueName: "value", repeatable: true, missingValueMessage: "--surface requires a value", description: "affected surface" }),
+      "--risk": Object.freeze({ targetKey: "risks", parseType: "string", takesValue: true, valueName: "value", repeatable: true, missingValueMessage: "--risk requires a value", description: "task risk" }),
+      "--platform": Object.freeze({ targetKey: "platforms", parseType: "string", takesValue: true, valueName: "value", repeatable: true, missingValueMessage: "--platform requires a value", description: "affected platform" }),
+      "--behavior-change": Object.freeze({ targetKey: "behaviorChange", parseType: "boolean", takesValue: false, description: "declare behavior change" }),
+      "--executable-change": Object.freeze({ targetKey: "executableChange", parseType: "boolean", takesValue: false, description: "declare executable/configuration change" }),
+      "--generation-required": Object.freeze({ targetKey: "generationRequired", parseType: "boolean", takesValue: false, description: "declare that generation is required" }),
+      "--architecture-change": Object.freeze({ targetKey: "architectureChange", parseType: "boolean", takesValue: false, description: "declare an architectural change" }),
+      "--ambiguous": Object.freeze({ targetKey: "ambiguity", parseType: "boolean", takesValue: false, description: "declare unresolved ambiguity" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit model-route projection as JSON" }),
+    }),
+    writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Projects a deterministic model-routing floor with advisory Jev escalation only.",
+  }),
+  "semantic-plan": Object.freeze({
+    name: "semantic-plan",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--decision": Object.freeze({ targetKey: "decisionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--decision requires an ID", description: "persisted Jev decision artifact ID" }),
+      "--kind": Object.freeze({ targetKey: "semanticPlanKind", parseType: "string", takesValue: true, valueName: "failure|diagnosis|review", missingValueMessage: "--kind requires failure, diagnosis, or review", description: "bounded semantic planning projection" }),
+      "--input": Object.freeze({ targetKey: "semanticPlanInput", parseType: "json-object", takesValue: true, valueName: "json", missingValueMessage: "--input requires a JSON object", description: "bounded failure, diagnosis, or review context" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit semantic plan projection as JSON" }),
+    }),
+    writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Projects fail-closed failure triage, diagnosis priority, or review planning without authority.",
+  }),
+  "test-inventory": Object.freeze({
+    name: "test-inventory",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit deterministic test inventory as JSON" }),
+    }),
+    writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Discovers tests deterministically and assigns stable semantic test IDs without pruning authority.",
+  }),
+  "test-utility": Object.freeze({
+    name: "test-utility",
+    category: "diagnostics",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit test utility analysis as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/test-utility.json"], removes: [], mayExecuteExternalProcess: false,
+    description: "Persists non-evidence test utility analysis; never deletes tests or authorizes pruning.",
+  }),
+  "test-prune-plan": Object.freeze({
+    name: "test-prune-plan", 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 test prune plan as JSON" }) }),
+    writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Projects KEEP, PROBE_REMOVAL, or BLOCKED without deleting tests.",
+  }),
+  "test-prune-probe": Object.freeze({
+    name: "test-prune-probe", category: "verification", mutation: "EXTERNAL_EXECUTION",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION, "--test": Object.freeze({ targetKey: "testId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--test requires a test ID", description: "stable test ID to probe in isolation" }), "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit test prune probe as JSON" }) }),
+    writes: [], removes: [], mayExecuteExternalProcess: true,
+    description: "Runs only an isolated, fail-closed removal probe; never modifies the live worktree.",
+  }),
+  discover: Object.freeze({
+    name: "discover",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured discovery output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Records the canonical initial discovery milestone for a newly created task.",
+  }),
+  "contract-create": Object.freeze({
+    name: "contract-create",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--contract-file": Object.freeze({ targetKey: "contractFile", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--contract-file requires a path", description: "validated JSON contract relative to the target" }),
+      "--preset": Object.freeze({ targetKey: "preset", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--preset requires a name", description: "bounded contract preset: documentation, bug, feature, or release" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured contract output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/contract.json", ".forgeloop/task-state/<taskKey>/work-state.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Persists a validated contract and materializes the first real lifecycle checkpoint.",
+  }),
+  "contract-revise": Object.freeze({
+    name: "contract-revise",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--contract-file": Object.freeze({ targetKey: "contractFile", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--contract-file requires a path", description: "validated replacement JSON contract relative to the target" }),
+      "--preset": Object.freeze({ targetKey: "preset", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--preset requires a name", description: "bounded replacement contract preset: documentation, bug, feature, or release" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured contract revision output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/contract.json", ".forgeloop/task-state/<taskKey>/work-state.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Replaces an existing contract canonically before execution while preserving task identity and invalidating derived evidence.",
+  }),
+  "gate-record": Object.freeze({
+    name: "gate-record", category: "lifecycle", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--gate": Object.freeze({ targetKey: "gate", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--gate requires a name", description: "required gate name" }),
+      "--status": Object.freeze({ targetKey: "gateStatus", parseType: "string", takesValue: true, valueName: "status", missingValueMessage: "--status requires a status", description: "satisfied, unverified, or blocked" }),
+      "--artifact": Object.freeze({ targetKey: "gateArtifacts", parseType: "string", takesValue: true, repeatable: true, valueName: "path", missingValueMessage: "--artifact requires a path", description: "project-relative evidence artifact" }),
+      "--decision": Object.freeze({ targetKey: "gateDecisions", parseType: "string", takesValue: true, repeatable: true, valueName: "text", missingValueMessage: "--decision requires text", description: "caller-recorded gate decision" }),
+      "--unknown": Object.freeze({ targetKey: "gateUnknowns", parseType: "string", takesValue: true, repeatable: true, valueName: "text", missingValueMessage: "--unknown requires text", description: "known unresolved item" }),
+       "--assumption": Object.freeze({ targetKey: "gateAssumptions", parseType: "string", takesValue: true, repeatable: true, valueName: "text", missingValueMessage: "--assumption requires text", description: "approved local assumption" }),
+       "--evidence-file": Object.freeze({ targetKey: "gateEvidenceFile", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--evidence-file requires a path", description: "bounded local descriptive evidence JSON" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured gate output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/gates/<gate>.json"], removes: [], mayExecuteExternalProcess: false,
+    description: "Records a required pre-execution gate with ForgeLoop-owned artifact hashes.",
+  }),
+  "gate-revalidate": Object.freeze({
+    name: "gate-revalidate", category: "lifecycle", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--gate": Object.freeze({ targetKey: "gate", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--gate requires a name", description: "satisfied gate to refresh after safe artifact drift" }),
+      "--acknowledge-stale": Object.freeze({ targetKey: "acknowledgeStale", parseType: "boolean", takesValue: false, description: "explicitly acknowledge refresh of stale gate artifacts inside active task claims" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured gate revalidation output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/gates/<gate>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Refreshes a stale satisfied gate after execution only when current identity and active claims prove the change is safe.",
+  }),
   init: Object.freeze({
     name: "init",
     category: "project-maintenance",
@@ -976,6 +1158,20 @@ 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.",
   }),
+  "checkpoint-revalidate": Object.freeze({
+    name: "checkpoint-revalidate",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured revalidation output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/work-state.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Revalidates a safe ROUTED checkpoint after repository-only drift without changing contract or route identity.",
+  }),
   "reconcile-closure": Object.freeze({
     name: "reconcile-closure",
     category: "lifecycle",
@@ -1170,6 +1366,51 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Caller-acknowledged recovery of a STALE or ABANDONED task; records durable state and releases effective write claims.",
   }),
+  "task-abandon": Object.freeze({
+    name: "task-abandon",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--acknowledge-abandonment": Object.freeze({ targetKey: "acknowledgeAbandonment", parseType: "boolean", takesValue: false, description: "explicitly acknowledge abandonment of an active task (required; not completion authority)" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured abandonment output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/recovery.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Explicitly abandons an active non-terminal task; records append-only evidence and releases claims without completion authority.",
+  }),
+  "task-repair-contract-bootstrap": Object.freeze({
+    name: "task-repair-contract-bootstrap",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--acknowledge-repair": Object.freeze({ targetKey: "acknowledgeRepair", parseType: "boolean", takesValue: false, description: "explicit caller acknowledgement of the exact append-only repair (required)" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured repair output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/work-state.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Repairs the exact duplicate contract bootstrap defect without rewriting history; idempotent and append-only.",
+  }),
+  "task-migrate-contract-bootstrap-repair": Object.freeze({
+    name: "task-migrate-contract-bootstrap-repair",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--acknowledge-migration": Object.freeze({ targetKey: "acknowledgeMigration", parseType: "boolean", takesValue: false, description: "fresh explicit caller acknowledgement of the exact legacy marker migration (required)" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured migration output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Migrates the exact legacy contract bootstrap repair marker by appending a bound migration event; the original marker and artifacts remain unchanged.",
+  }),
   "task-repair-legacy-recovery": Object.freeze({
     name: "task-repair-legacy-recovery",
     category: "project-maintenance",