@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/capability-policy.js

@@ -0,0 +1,226 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { sha256 } from "./manifest.js";
+import { ACTION_CAPABILITIES } from "./action-constants.js";
+import { validateCapabilityPolicy } from "./action-model.js";
+import { PROJECT_ARTIFACT_PATHS } from "./task-paths.js";
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import {
+  E_ACTION_INVALID,
+  E_POLICY_INVALID,
+} from "./error-codes.js";
+
+const ALLOWED_POLICY_PROPERTIES = new Set(["schemaVersion", "defaultDecision", "rules"]);
+
+function policyError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export async function loadCapabilityPolicy(target, packageRoot) {
+  const relativePath = PROJECT_ARTIFACT_PATHS.capabilityPolicy;
+  await assertSafePath(target, relativePath);
+  const absolutePath = ensureWithin(target, relativePath);
+  if (!(await fileExists(absolutePath))) {
+    return null;
+  }
+  let parsed;
+  try {
+    const { readFile } = await import("node:fs/promises");
+    parsed = JSON.parse(await readFile(absolutePath, "utf8"));
+  } catch (error) {
+    throw policyError(E_POLICY_INVALID, `capability policy is not valid JSON: ${error.message}`);
+  }
+  for (const key of Object.keys(parsed ?? {})) {
+    if (!ALLOWED_POLICY_PROPERTIES.has(key)) {
+      throw policyError(
+        E_POLICY_INVALID,
+        `capability policy.${key} is not an allowed property; project-local policy can never declare authority or trust metadata`,
+      );
+    }
+  }
+  validateCapabilityPolicy(parsed);
+  return {
+    policy: parsed,
+    fingerprint: canonicalFingerprint(parsed),
+    path: relativePath,
+  };
+}
+
+/**
+ * Canonical current capability-policy identity. The fingerprint matches the
+ * authorization-time binding; the digest is the same sha256 representation
+ * used by the policy lock so a single identity participates in locks, task
+ * snapshots, and action authorization evidence.
+ */
+export async function readCapabilityPolicyIdentity(target, packageRoot) {
+  const loaded = await loadCapabilityPolicy(target, packageRoot);
+  if (!loaded) {
+    return {
+      policy: null,
+      fingerprint: null,
+      digest: null,
+    };
+  }
+  return {
+    policy: loaded.policy,
+    fingerprint: loaded.fingerprint,
+    digest: `sha256:${sha256(canonicalFingerprint(loaded.policy))}`,
+  };
+}
+
+export function resolveCapabilityDecision(policy, capability) {
+  if (typeof capability !== "string" || !capability) {
+    throw policyError(E_ACTION_INVALID, "capability must be a non-empty string");
+  }
+  // Capabilities outside the canonical protocol vocabulary always fail closed.
+  if (!ACTION_CAPABILITIES.includes(capability)) {
+    return { decision: "DENY", reasonCode: "E_ACTION_CAPABILITY_UNKNOWN" };
+  }
+  const rule = policy.rules.find((candidate) => candidate.capability === capability);
+  const decision = rule?.decision ?? policy.defaultDecision;
+  switch (decision) {
+    case "ALLOW":
+      return { decision: "ALLOW", reasonCode: null };
+    case "DENY":
+      return { decision: "DENY", reasonCode: "E_ACTION_CAPABILITY_DENIED" };
+    case "REQUIRE_AUTHORITY":
+      return { decision: "REQUIRE_AUTHORITY", reasonCode: "E_ACTION_AUTHORITY_REQUIRED" };
+    case "REQUIRE_APPROVAL":
+      return { decision: "REQUIRE_APPROVAL", reasonCode: "E_ACTION_APPROVAL_REQUIRED" };
+    default:
+      return { decision: "DENY", reasonCode: "E_ACTION_CAPABILITY_DENIED" };
+  }
+}
+
+export function isTrustedHostAuthorityContext(authorityContext) {
+  // Only a genuine host-controlled trust boundary may satisfy
+  // REQUIRE_AUTHORITY. A project-local file, environment-selected source,
+  // CLI flag, or transport session can never promote itself to HOST_ATTESTED.
+  if (!authorityContext || typeof authorityContext !== "object") return false;
+  if (authorityContext.trustMode !== "HOST_ATTESTED") return false;
+  const source = typeof authorityContext.source === "string" ? authorityContext.source : "";
+  const forbiddenSources = ["project-local-file", "environment", "cli-flag", "transport-session"];
+  if (forbiddenSources.includes(source)) return false;
+  return authorityContext.hostSupplied === true && source === "host-boundary";
+}
+
+export async function evaluateActionCapability({
+  target,
+  packageRoot,
+  action,
+  authorityContext = { trustMode: "NONE" },
+  approval,
+}) {
+  if (!action || typeof action !== "object") {
+    throw policyError(E_ACTION_INVALID, "action is required for capability evaluation");
+  }
+
+  let loaded = null;
+  try {
+    loaded = await loadCapabilityPolicy(target, packageRoot);
+  } catch (error) {
+    if (error.code === E_POLICY_INVALID) throw error;
+    throw error;
+  }
+
+  // A poisoned local policy artifact must never grant authority.
+  if (
+    loaded &&
+    (loaded.policy.authority !== undefined ||
+      loaded.policy.trustMode !== undefined ||
+      loaded.policy.hostAttested !== undefined)
+  ) {
+    loaded = null;
+  }
+
+  if (!loaded) {
+    // No capability policy present. v1 keeps legacy flows unchanged and fails
+    // closed for new durable-action execution.
+    return {
+      capability: action.capability,
+      decision: "REQUIRE_APPROVAL",
+      allowed: false,
+      reasonCode: "E_ACTION_APPROVAL_REQUIRED",
+      policyFingerprint: null,
+    };
+  }
+
+  const resolved = resolveCapabilityDecision(loaded.policy, action.capability);
+  const base = {
+    capability: action.capability,
+    decision: resolved.decision,
+    policyFingerprint: loaded.fingerprint,
+  };
+
+  if (resolved.decision === "ALLOW") {
+    return { ...base, allowed: true, reasonCode: null };
+  }
+  if (resolved.decision === "DENY") {
+    return { ...base, allowed: false, reasonCode: resolved.reasonCode ?? "E_ACTION_CAPABILITY_DENIED" };
+  }
+  if (resolved.decision === "REQUIRE_AUTHORITY") {
+    if (
+      isTrustedHostAuthorityContext(authorityContext)
+      && typeof authorityContext.grantRef === "string"
+      && authorityContext.grantRef.length > 0
+      && authorityContext.grantRef.length <= 256
+    ) {
+      return {
+        ...base,
+        allowed: true,
+        reasonCode: null,
+        authority: {
+          authorityKind: "HOST_ATTESTED",
+          authorityRef: authorityContext.grantRef,
+        },
+      };
+    }
+    return { ...base, allowed: false, reasonCode: "E_ACTION_AUTHORITY_REQUIRED" };
+  }
+  if (approval?.approvalId) {
+    const { validateApprovalForAction, approvalFingerprint } = await import("./approvals.js");
+    try {
+      const resolvedApproval = await validateApprovalForAction(target, {
+        packageRoot,
+        taskId: action.taskId,
+        action,
+        approvalId: approval.approvalId,
+      });
+      if (resolvedApproval.authorityKind !== "HOST_ATTESTED" || !resolvedApproval.hostGrantRef) {
+        return { ...base, allowed: false, reasonCode: "E_ACTION_AUTHORITY_REQUIRED" };
+      }
+      return {
+        ...base,
+        allowed: true,
+        reasonCode: null,
+        approval: {
+          approvalId: resolvedApproval.approvalId,
+          approvalFingerprint: approvalFingerprint(resolvedApproval),
+          authorityKind: "HOST_ATTESTED",
+          authorityRef: resolvedApproval.hostGrantRef,
+        },
+      };
+    } catch (error) {
+      return { ...base, allowed: false, reasonCode: error.code ?? "E_APPROVAL_INVALID" };
+    }
+  }
+  return { ...base, allowed: false, reasonCode: "E_ACTION_APPROVAL_REQUIRED" };
+}
+
+/**
+ * Least-privilege diagnostics for project capability policies (policy is
+ * policy, never authority). A broad defaultDecision=ALLOW grants every known
+ * capability without an explicit DENY rule; standard mode surfaces a warning
+ * so operators see the least-privilege tradeoff.
+ */
+export function capabilityPolicyWarnings(policy) {
+  if (!policy || typeof policy !== "object" || policy.defaultDecision !== "ALLOW") {
+    return [];
+  }
+  return [{
+    code: "W_CAPABILITY_POLICY_BROAD_DEFAULT",
+    message:
+      "Capability policy defaultDecision=ALLOW grants every known capability without an explicit DENY rule.",
+  }];
+}

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

@@ -1,5 +1,5 @@
 /**
- * Canonical, declarative definition of all 42 ForgeLoop CLI commands.
+ * Canonical, declarative definition of all ForgeLoop CLI commands.
  * This is the machine source of truth for CLI option parsing, help text,
  * metadata, documentation generation, and conformance validation.
  *
@@ -43,7 +43,7 @@ export const CLI_COMMON_OPTIONS = Object.freeze({
  */
 export const CLI_TASK_OPTION = Object.freeze({
   "--task": Object.freeze({
-    targetKey: "task",
+    targetKey: "taskId",
     parseType: "string",
     takesValue: true,
     valueName: "id",
@@ -133,7 +133,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
-      "--work": Object.freeze({ targetKey: "work", parseType: "string", takesValue: true, valueName: "type", missingValueMessage: "--work requires a type", description: "declared work type" }),
+      "--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" }),
@@ -286,6 +286,130 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: true,
     description: "Runs an exact command, records the execution provenance artifact, and binds observed check evidence.",
   }),
+  "run-action": Object.freeze({
+    name: "run-action",
+    category: "actions",
+    mutation: "EXTERNAL_EXECUTION",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--action": Object.freeze({ targetKey: "actionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--action requires an action ID", description: "stable durable action ID" }),
+      "--capability": Object.freeze({ targetKey: "actionCapability", parseType: "string", takesValue: true, valueName: "capability", missingValueMessage: "--capability requires a capability", description: "canonical action capability" }),
+      "--effect-class": Object.freeze({ targetKey: "actionEffectClass", parseType: "string", takesValue: true, valueName: "class", missingValueMessage: "--effect-class requires a class", description: "durable action effect class" }),
+      "--target": Object.freeze({ targetKey: "actionTarget", parseType: "string", takesValue: true, valueName: "target", missingValueMessage: "--target requires a bounded target", description: "bounded external action target" }),
+      "--idempotency-key": Object.freeze({ targetKey: "actionIdempotencyKey", parseType: "string", takesValue: true, valueName: "key", missingValueMessage: "--idempotency-key requires a key", description: "immutable logical action idempotency key" }),
+      "--requirement": Object.freeze({ targetKey: "actionRequirement", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--requirement requires an ID", description: "bound completion requirement" }),
+      "--required-for-completion": Object.freeze({ targetKey: "actionRequiredForCompletion", parseType: "boolean", takesValue: false, description: "mark the action as required for completion" }),
+      "--approval": Object.freeze({ targetKey: "approvalId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--approval requires an approval ID", description: "current fingerprint-bound approval" }),
+      "--timeout-ms": Object.freeze({ targetKey: "timeoutMs", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--timeout-ms requires a non-negative integer", description: "maximum command duration before termination" }),
+      "--": Object.freeze({ targetKey: "commandArgv", parseType: "argv", takesValue: true, valueName: "argv...", description: "exact command argv; shell mode is never used" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/actions/action-<id>.json", ".forgeloop/task-state/<taskKey>/executions/exec-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Executes one policy-authorized durable action using exact argv and shell:false semantics.",
+  }),
+  "action-propose": Object.freeze({
+    name: "action-propose", category: "actions", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--id": Object.freeze({ targetKey: "actionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--id requires an action ID", description: "stable action ID" }),
+      "--capability": Object.freeze({ targetKey: "actionCapability", parseType: "string", takesValue: true, valueName: "capability", missingValueMessage: "--capability requires a capability", description: "canonical capability" }),
+      "--effect-class": Object.freeze({ targetKey: "actionEffectClass", parseType: "string", takesValue: true, valueName: "class", missingValueMessage: "--effect-class requires a class", description: "effect class" }),
+      "--target": Object.freeze({ targetKey: "actionTarget", parseType: "string", takesValue: true, valueName: "target", missingValueMessage: "--target requires a target", description: "bounded action target" }),
+      "--operation": Object.freeze({ targetKey: "actionOperation", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--operation requires text", description: "bounded operation description" }),
+      "--idempotency-key": Object.freeze({ targetKey: "actionIdempotencyKey", parseType: "string", takesValue: true, valueName: "key", missingValueMessage: "--idempotency-key requires a key", description: "logical action idempotency key" }),
+      "--requirement": Object.freeze({ targetKey: "actionRequirement", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--requirement requires an ID", description: "bound requirement" }),
+      "--required-for-completion": Object.freeze({ targetKey: "actionRequiredForCompletion", parseType: "boolean", takesValue: false, description: "mark required for completion" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/actions/action-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Proposes a caller-reported durable action without executing it.",
+  }),
+  "action-record": Object.freeze({
+    name: "action-record", category: "actions", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--action": Object.freeze({ targetKey: "actionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--action requires an action ID", description: "durable action ID" }),
+      "--state": Object.freeze({ targetKey: "actionState", parseType: "string", takesValue: true, valueName: "state", missingValueMessage: "--state requires a state", description: "next canonical action state" }),
+      "--provenance": Object.freeze({ targetKey: "actionProvenance", parseType: "string", takesValue: true, valueName: "value", missingValueMessage: "--provenance requires a value", description: "CALLER_REPORTED or EXTERNAL_OBSERVED" }),
+      "--evidence-ref": Object.freeze({ targetKey: "actionEvidenceRef", parseType: "string", takesValue: true, valueName: "ref", missingValueMessage: "--evidence-ref requires a reference", description: "bounded external evidence reference" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/actions/action-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Records a caller-reported or externally observed non-authority action transition.",
+  }),
+  "action-show": Object.freeze({
+    name: "action-show", category: "actions", mutation: "READ_ONLY",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--action": Object.freeze({ targetKey: "actionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--action requires an action ID", description: "durable action ID" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }), writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Reads one canonical durable action artifact.",
+  }),
+  "action-reconcile": Object.freeze({
+    name: "action-reconcile", category: "actions", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--action": Object.freeze({ targetKey: "actionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--action requires an action ID", description: "ambiguous durable action ID" }),
+      "--outcome": Object.freeze({ targetKey: "reconciliationOutcome", parseType: "string", takesValue: true, valueName: "outcome", missingValueMessage: "--outcome requires COMMITTED, NOT_COMMITTED, or UNKNOWN", description: "externally observed reconciliation outcome" }),
+      "--evidence-ref": Object.freeze({ targetKey: "evidenceRefs", parseType: "string", takesValue: true, repeatable: true, valueName: "ref", missingValueMessage: "--evidence-ref requires a reference", description: "bounded external evidence reference" }),
+      "--observed-at": Object.freeze({ targetKey: "observedAt", parseType: "string", takesValue: true, valueName: "timestamp", missingValueMessage: "--observed-at requires a timestamp", description: "external observation timestamp" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/actions/action-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Reconciles a COMMIT_UNKNOWN action from externally observed evidence without retrying it.",
+  }),
+  "action-verify": Object.freeze({
+    name: "action-verify", category: "actions", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--action": Object.freeze({ targetKey: "actionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--action requires an action ID", description: "durable action ID" }),
+      "--evidence": Object.freeze({ targetKey: "actionEvidenceRef", parseType: "string", takesValue: true, valueName: "ref", missingValueMessage: "--evidence requires a canonical execution reference", description: "canonical execution or check reference proving the postcondition" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/actions/action-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Verifies a COMMITTED action against independent canonical evidence; caller claims can never verify.",
+  }),
+  "action-authorize": Object.freeze({
+    name: "action-authorize", category: "actions", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--action": Object.freeze({ targetKey: "actionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--action requires an action ID", description: "durable action ID" }),
+      "--approval": Object.freeze({ targetKey: "approvalId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--approval requires an approval ID", description: "current fingerprint-bound approval" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/actions/action-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Authorizes one PROPOSED durable action through the canonical capability-policy and approval service.",
+  }),
+  metrics: Object.freeze({
+    name: "metrics", 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 trajectory metrics as JSON" }),
+    }), writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Projects trajectory, action, execution, timing, and known usage metrics without mutating state.",
+  }),
+  eval: Object.freeze({
+    name: "eval", category: "diagnostics", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--scenario": Object.freeze({ targetKey: "scenarioPath", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--scenario requires a path", description: "project-local trajectory scenario JSON" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit evaluation as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/evaluations/eval-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Evaluates the current trajectory against a validated project-local reference scenario.",
+  }),
+  "approval-request": Object.freeze({
+    name: "approval-request", category: "actions", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--approval": Object.freeze({ targetKey: "approvalId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--approval requires an ID", description: "approval artifact ID" }),
+      "--action": Object.freeze({ targetKey: "actionId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--action requires an ID", description: "bound action ID" }),
+      "--reason": Object.freeze({ targetKey: "reason", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--reason requires text", description: "bounded approval reason" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/approvals/approval-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Creates a durable fingerprint-bound approval request.",
+  }),
+  "approval-resolve": Object.freeze({
+    name: "approval-resolve", category: "actions", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--approval": Object.freeze({ targetKey: "approvalId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--approval requires an ID", description: "approval artifact ID" }),
+      "--decision": Object.freeze({ targetKey: "approvalDecision", parseType: "string", takesValue: true, valueName: "decision", missingValueMessage: "--decision requires APPROVED or REJECTED", description: "approval decision" }),
+      "--authority": Object.freeze({ targetKey: "approvalAuthorityKind", parseType: "string", takesValue: true, valueName: "kind", missingValueMessage: "--authority requires a kind", description: "CALLER_ACKNOWLEDGED or HOST_ATTESTED" }),
+      "--host-grant-ref": Object.freeze({ targetKey: "hostGrantRef", parseType: "string", takesValue: true, valueName: "ref", missingValueMessage: "--host-grant-ref requires a reference", description: "host boundary grant reference" }),
+      "--reason": Object.freeze({ targetKey: "reason", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--reason requires text", description: "bounded resolution reason" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/approvals/approval-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Resolves one durable approval exactly once.",
+  }),
   "record-check": Object.freeze({
     name: "record-check",
     category: "verification",
@@ -338,6 +462,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
+      "--file": Object.freeze({ targetKey: "file", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--file requires a path", description: "structured diagnostic case JSON file (mutually exclusive with legacy diagnosis fields)" }),
       "--hypothesis": Object.freeze({ targetKey: "hypothesis", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--hypothesis requires text", description: "specific root-cause hypothesis explaining the verification failure" }),
       "--failure-class": Object.freeze({ targetKey: "failureClass", parseType: "string", takesValue: true, valueName: "class", missingValueMessage: "--failure-class requires a class", description: "canonical failure class taxonomy" }),
       "--evidence-ref": Object.freeze({ targetKey: "evidenceRefs", parseType: "string", takesValue: true, valueName: "check-id", repeatable: true, missingValueMessage: "--evidence-ref requires a check ID", description: "reference to failed/blocked check from current cycle" }),
@@ -348,7 +473,91 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     writes: [".forgeloop/task-state/<taskKey>/events.ndjson", ".forgeloop/task-state/<taskKey>/work-state.json"],
     removes: [],
     mayExecuteExternalProcess: false,
-    description: "Records an append-only diagnosis event in the lifecycle event ledger for the active cycle.",
+    description: "Records an append-only diagnosis event or structured diagnostic case in the lifecycle event ledger.",
+  }),
+  "record-intervention": Object.freeze({
+    name: "record-intervention",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--file": Object.freeze({ targetKey: "file", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--file requires a path", description: "intervention JSON file describing the recorded change (never executed)" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Records an append-only intervention bound to hypotheses; the described change is never executed by ForgeLoop.",
+  }),
+  "record-hypothesis-disposition": Object.freeze({
+    name: "record-hypothesis-disposition",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--hypothesis": Object.freeze({ targetKey: "hypothesis", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--hypothesis requires a hypothesis ID", description: "existing hypothesis ID to disposition" }),
+      "--status": Object.freeze({ targetKey: "dispositionStatus", parseType: "string", takesValue: true, valueName: "status", missingValueMessage: "--status requires a status", description: "SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, or UNRESOLVED" }),
+      "--evidence-ref": Object.freeze({ targetKey: "evidenceRefs", parseType: "string", takesValue: true, valueName: "check-id", repeatable: true, missingValueMessage: "--evidence-ref requires a check ID", description: "check ID supporting this disposition" }),
+      "--reason": Object.freeze({ targetKey: "reason", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--reason requires text", description: "evidence-bound reason for the disposition" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Records an evidence-bound hypothesis disposition update in the lifecycle event ledger.",
+  }),
+  history: Object.freeze({
+    name: "history",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--type": Object.freeze({ targetKey: "historyType", parseType: "string", takesValue: true, valueName: "list", missingValueMessage: "--type requires a value", description: "comma-separated event types or categories to include" }),
+      "--phase": Object.freeze({ targetKey: "historyPhase", parseType: "string", takesValue: true, valueName: "list", missingValueMessage: "--phase requires a value", description: "comma-separated lifecycle phases to include" }),
+      "--failures": Object.freeze({ targetKey: "historyFailures", parseType: "boolean", takesValue: false, description: "show only failed/blocked verification events" }),
+      "--checks": Object.freeze({ targetKey: "historyChecks", parseType: "boolean", takesValue: false, description: "show only verification events" }),
+      "--since": Object.freeze({ targetKey: "historySince", parseType: "string", takesValue: true, valueName: "timestamp", missingValueMessage: "--since requires a timestamp", description: "include events at or after this timestamp" }),
+      "--until": Object.freeze({ targetKey: "historyUntil", parseType: "string", takesValue: true, valueName: "timestamp", missingValueMessage: "--until requires a timestamp", description: "include events at or before this timestamp" }),
+      "--limit": Object.freeze({ targetKey: "historyLimit", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--limit requires a non-negative integer", description: "show only the last N events after filtering" }),
+      "--compact": Object.freeze({ targetKey: "compact", parseType: "boolean", takesValue: false, description: "one line per event" }),
+      "--verbose": Object.freeze({ targetKey: "verbose", parseType: "boolean", takesValue: false, description: "show full event data" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured history output as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Shows chronological protocol history reconstructed from canonical ForgeLoop state.",
+  }),
+  trace: Object.freeze({
+    name: "trace",
+    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 structured trace output as JSON (default rendering is a summary)" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Emits detailed structured task trace with provenance and artifact relationships.",
+  }),
+  reflect: Object.freeze({
+    name: "reflect",
+    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 structured reflection output as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Analyzes diagnostic and correction history deterministically for information gain, repeated failures, ineffective interventions, and oscillation.",
   }),
   progress: Object.freeze({
     name: "progress",
@@ -767,10 +976,56 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],
-    removes: [".forgeloop/task-state/<taskKey>/.lock"],
+    removes: [".forgeloop/locks/<taskKey>.lock"],
     mayExecuteExternalProcess: false,
     description: "Removes an orphaned task lock file to recover an interrupted task.",
   }),
+  "task-recover": Object.freeze({
+    name: "task-recover",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--acknowledge-recovery": Object.freeze({ targetKey: "acknowledgeRecovery", parseType: "boolean", takesValue: false, description: "acknowledge release of claims for a STALE or ABANDONED task (required; not host attestation)" }),
+      "--operator-authorized": Object.freeze({ targetKey: "operatorAuthorized", parseType: "boolean", takesValue: false, description: "deprecated alias for --acknowledge-recovery; does not attest operator authority" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/recovery.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Caller-acknowledged recovery of a STALE or ABANDONED task; records durable state and releases effective write claims.",
+  }),
+  "task-repair-legacy-recovery": Object.freeze({
+    name: "task-repair-legacy-recovery",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--acknowledge-recovery": Object.freeze({ targetKey: "acknowledgeRecovery", parseType: "boolean", takesValue: false, description: "fresh explicit acknowledgement of the legacy boundary migration (required)" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/recovery.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Migrates one recognized legacy OPERATOR_RECOVERY_RECORDED boundary event into the modern durable recovery representation (append-only; original event unchanged).",
+  }),
+  "task-resume": Object.freeze({
+    name: "task-resume",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--claim": Object.freeze({ targetKey: "claims", parseType: "string", takesValue: true, repeatable: true, valueName: "path", missingValueMessage: "--claim requires a path", description: "write claim to reacquire (defaults to all released claims)" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/task.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [".forgeloop/task-state/<taskKey>/recovery.json"],
+    mayExecuteExternalProcess: false,
+    description: "Reacquires a recovered task's write claims under project serialization and restores ordinary mutation authority.",
+  }),
 });
 
 /**