@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/commands/action-authorize.js

@@ -0,0 +1,41 @@
+import { authorizeAction } from "../core/action-authorization.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+/**
+ * Canonical public authorization surface. This command is only an adapter
+ * over the core authorization service: it creates no new trust mechanism and
+ * accepts no authority fields in actor-controlled arguments. Trusted host
+ * authority arrives exclusively through the out-of-band executor context.
+ */
+export async function runActionAuthorize({
+  target,
+  packageRoot,
+  taskId,
+  actionId,
+  approvalId,
+  authorityContext,
+}) {
+  return withTaskMutation(
+    target,
+    { taskId, packageRoot },
+    "action-authorize",
+    (ctx) => authorizeAction({
+      target,
+      packageRoot,
+      taskId: ctx.taskId,
+      actionId,
+      approvalId,
+      authorityContext,
+    }),
+  );
+}
+
+export function formatActionAuthorizeResult(result) {
+  return [
+    "FORGELOOP ACTION AUTHORIZED",
+    `action: ${result.action.actionId}`,
+    `state: ${result.action.state}`,
+    `decision: ${result.authorization.capabilityDecision}`,
+    "",
+  ].join("\n");
+}

package/src/commands/action-propose.js

@@ -0,0 +1,10 @@
+import { proposeAction } from "../core/actions.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export async function runActionPropose({ target, packageRoot, taskId, input }) {
+  return withTaskMutation(target, { taskId, packageRoot }, "action-propose", (ctx) =>
+    proposeAction(target, { packageRoot, taskId: ctx.taskId, input: { ...input, provenance: "CALLER_REPORTED" } }));
+}
+export function formatActionProposeResult(result) {
+  return `FORGELOOP ACTION PROPOSED\naction: ${result.action.actionId}\nstate: ${result.action.state}\n`;
+}

package/src/commands/action-reconcile.js

@@ -0,0 +1,10 @@
+import { reconcileAction } from "../core/action-reconciliation.js";
+import { withTaskMutation } from "../core/task-command.js";
+export async function runActionReconcile(args) {
+  const { target, packageRoot, taskId } = args;
+  return withTaskMutation(target, { taskId, packageRoot }, "action-reconcile", (ctx) =>
+    reconcileAction({ ...args, taskId: ctx.taskId }));
+}
+export function formatActionReconcileResult(result) {
+  return `FORGELOOP ACTION RECONCILED\naction: ${result.action.actionId}\noutcome: ${result.outcome}\nstate: ${result.action.state}\n`;
+}

package/src/commands/action-record.js

@@ -0,0 +1,47 @@
+import { transitionAction } from "../core/actions.js";
+import { withTaskMutation } from "../core/task-command.js";
+import {
+  E_ACTION_AUTHORIZATION_INVALID,
+  E_ACTION_INVALID,
+  E_ACTION_VERIFICATION_REQUIRED,
+} from "../core/error-codes.js";
+
+// Public action-record may only record observations that do not create
+// authority. AUTHORIZED and VERIFIED are owned by canonical core services and
+// are rejected here even if a transport mistakenly exposes this command.
+const CALLER_RECORDABLE_ACTION_STATES = Object.freeze([
+  "STARTED",
+  "COMMITTED",
+  "COMMIT_UNKNOWN",
+  "FAILED",
+  "CANCELLED",
+]);
+
+export async function runActionRecord({ target, packageRoot, taskId, actionId, state, provenance, evidenceRef }) {
+  if (!["CALLER_REPORTED", "EXTERNAL_OBSERVED"].includes(provenance)) {
+    const error = new Error("action-record provenance must be CALLER_REPORTED or EXTERNAL_OBSERVED");
+    error.code = E_ACTION_INVALID;
+    throw error;
+  }
+  if (state === "AUTHORIZED") {
+    const error = new Error("AUTHORIZED is owned by the canonical authorization service; caller surfaces cannot authorize actions");
+    error.code = E_ACTION_AUTHORIZATION_INVALID;
+    throw error;
+  }
+  if (state === "VERIFIED") {
+    const error = new Error("VERIFIED requires canonical independent postcondition evidence via forgeloop action-verify");
+    error.code = E_ACTION_VERIFICATION_REQUIRED;
+    throw error;
+  }
+  if (!CALLER_RECORDABLE_ACTION_STATES.includes(state)) {
+    const error = new Error(`action-record state must be one of ${CALLER_RECORDABLE_ACTION_STATES.join(", ")}`);
+    error.code = E_ACTION_INVALID;
+    throw error;
+  }
+  return withTaskMutation(target, { taskId, packageRoot }, "action-record", (ctx) =>
+    transitionAction(target, { packageRoot, taskId: ctx.taskId, actionId, to: state,
+      details: { ...(evidenceRef ? { evidenceRef } : {}), reportedProvenance: provenance } }));
+}
+export function formatActionRecordResult(result) {
+  return `FORGELOOP ACTION RECORDED\naction: ${result.actionId}\nstate: ${result.state}\n`;
+}

package/src/commands/action-show.js

@@ -0,0 +1,10 @@
+import { readAction } from "../core/actions.js";
+import { resolveTaskContext } from "../core/task-context.js";
+
+export async function runActionShow({ target, packageRoot, taskId, actionId }) {
+  const ctx = await resolveTaskContext(target, { packageRoot, taskId });
+  return readAction(target, { packageRoot, taskId: ctx.taskId, actionId });
+}
+export function formatActionShowResult(result) {
+  return `FORGELOOP ACTION\naction: ${result.actionId}\nstate: ${result.state}\ncapability: ${result.capability}\n`;
+}

package/src/commands/action-verify.js

@@ -0,0 +1,10 @@
+import { verifyAction } from "../core/action-verification.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export async function runActionVerify({ target, packageRoot, taskId, actionId, evidenceRef }) {
+  return withTaskMutation(target, { taskId, packageRoot }, "action-verify", (ctx) =>
+    verifyAction({ target, packageRoot, taskId: ctx.taskId, actionId, evidenceRef }));
+}
+export function formatActionVerifyResult(result) {
+  return `FORGELOOP ACTION VERIFIED\naction: ${result.actionId}\nstate: ${result.state}\nevidence: ${result.lastEvidenceRef}\n`;
+}

package/src/commands/advance.js

@@ -3,10 +3,15 @@ import { withTaskMutation } from "../core/task-command.js";
 
 export { advanceWorkState };
 
-export async function runAdvance({ target, packageRoot, to, taskId, task }) {
+export async function runAdvance({ target, packageRoot, to, taskId, task, authorityContext, runtimeContext }) {
   if (!to) throw new Error("--to is required for advance");
   return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "advance", async (ctx) => {
-    return advanceWorkState(target, to, { packageRoot, taskId: ctx?.taskId ?? null });
+    return advanceWorkState(target, to, {
+      packageRoot,
+      taskId: ctx?.taskId ?? null,
+      authorityContext,
+      runtimeContext,
+    });
   });
 }
 

package/src/commands/approval-request.js

@@ -0,0 +1,64 @@
+import { readAction } from "../core/actions.js";
+import { readWorkState } from "../core/work-state.js";
+import { requestApproval } from "../core/approvals.js";
+import { evaluateActionCapability } from "../core/capability-policy.js";
+import { loadPolicyIdentity } from "../core/policy-engine.js";
+import {
+  E_ACTION_APPROVAL_NOT_REQUIRED,
+  E_ACTION_AUTHORITY_REQUIRED,
+  E_ACTION_CAPABILITY_DENIED,
+} from "../core/error-codes.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+function approvalPolicyError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export async function runApprovalRequest({ target, packageRoot, taskId, approvalId, actionId, reason }) {
+  return withTaskMutation(target, { taskId, packageRoot }, "approval-request", async (ctx) => {
+    const action = await readAction(target, { packageRoot, taskId: ctx.taskId, actionId });
+    const state = await readWorkState(target, { packageRoot, taskId: ctx.taskId });
+    let policyIdentity;
+    try {
+      policyIdentity = await loadPolicyIdentity(target, packageRoot, ctx.taskId);
+    } catch (error) {
+      throw approvalPolicyError(
+        error.code ?? "E_POLICY_INVALID",
+        `Capability policy epoch validation failed before requesting approval: ${error.message}`,
+      );
+    }
+    if (policyIdentity.status !== "VALID") {
+      throw approvalPolicyError(
+        policyIdentity.code ?? "E_ACTION_POLICY_LOCK_REQUIRED",
+        "The current capability policy is not bound to a valid task policy epoch; repair or refresh policy state before requesting approval.",
+      );
+    }
+    const capability = await evaluateActionCapability({ target, packageRoot, action });
+    if (capability.decision === "ALLOW") {
+      throw approvalPolicyError(
+        E_ACTION_APPROVAL_NOT_REQUIRED,
+        "The current capability policy allows this action without approval.",
+      );
+    }
+    if (capability.decision === "DENY") {
+      throw approvalPolicyError(
+        capability.reasonCode ?? E_ACTION_CAPABILITY_DENIED,
+        `The current capability policy denies ${action.capability}; approval cannot override a denial.`,
+      );
+    }
+    if (capability.decision === "REQUIRE_AUTHORITY") {
+      throw approvalPolicyError(
+        capability.reasonCode ?? E_ACTION_AUTHORITY_REQUIRED,
+        "The current capability policy requires trusted host authority; approval cannot substitute for it.",
+      );
+    }
+    return requestApproval(target, { packageRoot, taskId: ctx.taskId, input: {
+      approvalId, actionId: action.actionId, actionFingerprint: action.actionFingerprint,
+      contractFingerprint: state.contractFingerprint, taskRevision: state.revision ?? 0,
+      capability: action.capability, reason,
+    } });
+  });
+}
+export function formatApprovalRequestResult(result) { return `FORGELOOP APPROVAL REQUESTED\napproval: ${result.approval.approvalId}\nstatus: ${result.approval.status}\n`; }

package/src/commands/approval-resolve.js

@@ -0,0 +1,10 @@
+import { resolveApproval } from "../core/approvals.js";
+import { withTaskMutation } from "../core/task-command.js";
+export async function runApprovalResolve({ target, packageRoot, taskId, approvalId, decision, authorityKind, hostGrantRef, authorityContext, reason }) {
+  return withTaskMutation(target, { taskId, packageRoot }, "approval-resolve", (ctx) => resolveApproval(target, {
+    packageRoot, taskId: ctx.taskId, approvalId, decision, authorityKind, hostGrantRef, reason,
+    // Trusted host authority arrives out-of-band; it is never actor input.
+    authorityContext,
+  }));
+}
+export function formatApprovalResolveResult(result) { return `FORGELOOP APPROVAL RESOLVED\napproval: ${result.approvalId}\ndecision: ${result.decision}\n`; }

package/src/commands/audit.js

@@ -14,6 +14,11 @@ export async function runAudit(options = {}) {
 
 export function formatAuditResult(result) {
   const lines = [`FORGELOOP AUDIT: ${result.status}`];
+  if (result.recovery) lines.push(`RECOVERY: ${result.recovery.status} (${result.recovery.recoveryId})`);
+  if (result.claims) {
+    lines.push(`CLAIM STATE: ${result.claims.state}`);
+    lines.push(`MUTATION ALLOWED: ${result.claims.mutationAllowed ? "yes" : "no"}`);
+  }
   for (const error of result.errors) {
     lines.push(`${error.code}: ${error.message}`);
     if (error.next) lines.push(`NEXT: ${error.next}`);

package/src/commands/baseline.js

@@ -1,5 +1,5 @@
 import {
-  computePolicyLockData,
+  computePersistedPolicyLockData,
   evaluateTargetPolicy,
   loadEffectiveRules,
   writePolicyLock,
@@ -56,7 +56,7 @@ export async function runBaseline({
     await writeBaseline(target, baseline, packageRoot);
 
     const rules = await loadEffectiveRules(target, packageRoot);
-    const lock = computePolicyLockData(rules, baseline);
+    const lock = await computePersistedPolicyLockData(target, packageRoot, rules, baseline);
     await writePolicyLock(target, lock, packageRoot);
 
     return {
@@ -85,7 +85,7 @@ export async function runBaseline({
     await writeBaseline(target, baseline, packageRoot);
 
     const rules = await loadEffectiveRules(target, packageRoot);
-    const lock = computePolicyLockData(rules, baseline);
+    const lock = await computePersistedPolicyLockData(target, packageRoot, rules, baseline);
     await writePolicyLock(target, lock, packageRoot);
 
     return {

package/src/commands/eval.js

@@ -0,0 +1,6 @@
+import { evaluateTrajectory } from "../core/trajectory-evaluation.js";
+import { withResolvedTask } from "../core/task-command.js";
+export async function runEval({ target, packageRoot, taskId, scenarioPath }) {
+  return withResolvedTask(target, { taskId, packageRoot }, (ctx) => evaluateTrajectory({ target, packageRoot, taskId: ctx.taskId, scenarioPath }));
+}
+export function formatEvalResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }

package/src/commands/history.js

@@ -0,0 +1,18 @@
+import { buildTaskHistory, formatHistoryResult } from "../core/history.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
+
+export { buildTaskHistory, formatHistoryResult };
+
+export async function runHistory({ target, packageRoot, taskId, task, filters = {} }) {
+  const resolved = await resolveTaskContext(target, {
+    packageRoot,
+    taskId: taskId ?? task,
+    selectionMode: TASK_SELECTION_MODES.READ,
+  });
+  return buildTaskHistory({
+    target,
+    packageRoot,
+    taskId: resolved?.taskId ?? null,
+    filters,
+  });
+}

package/src/commands/init.js

@@ -187,7 +187,7 @@ export async function runInit({
   const { discoverPolicy } = await import("../core/policy-discovery.js");
   const {
     loadEffectiveRules,
-    computePolicyLockData,
+    computePersistedPolicyLockData,
     writeDiscoveryReport,
     writePolicyLock,
     detectPolicyCapability,
@@ -210,7 +210,7 @@ export async function runInit({
     }
     baseline = createBaselineFromViolations([]);
     effectiveRules = await loadEffectiveRules(target, packageRoot);
-    lock = computePolicyLockData(effectiveRules, baseline);
+    lock = await computePersistedPolicyLockData(target, packageRoot, effectiveRules, baseline);
   } catch (cause) {
     throw policyInitializationError(cause);
   }

package/src/commands/inspect.js

@@ -11,6 +11,8 @@ export async function inspectTarget(options = {}) {
 }
 
 export function formatInspectResult(report) {
+  const task = report.taskInspection;
+  if (task) return formatTaskInspection(report, task);
   const lines = [
     `Target: ${report.target.path}`,
     `Manifest: ${report.manifest.status}`,
@@ -19,9 +21,62 @@ export function formatInspectResult(report) {
     `Authority source: ${report.authority.sourceType ?? "none configured"} / ${report.authority.trusted ? "TRUSTED" : report.authority.trustMode === "NONE" ? "UNATTESTED" : "UNTRUSTED"}`,
     `Authority trust: ${report.authority.trustMode}`,
     `State: ${report.state.status}`,
+    ...(report.recovery
+      ? [`Recovery: ${report.recovery.status} (${report.recovery.recoveryId})`]
+      : []),
+    ...(report.claims
+      ? [`Claim state: ${report.claims.state}`, `Mutation allowed: ${report.claims.mutationAllowed ? "yes" : "no"}`]
+      : []),
     `Adapters: ${report.adapters.detected.length} detected`,
     `Findings: ${report.findings.length}`,
     report.ok ? "healthy: ForgeLoop target is ready" : "unhealthy: ForgeLoop target needs attention",
   ];
   return `${lines.join("\n")}\n`;
 }
+
+function formatTaskInspection(report, task) {
+  const rule = "-".repeat(56);
+  const lines = [
+    "ForgeLoop Task Inspection",
+    rule,
+    `Task:                ${task.task ?? report.claims?.state ?? "-"}`,
+    `Phase:               ${task.lifecycle.phase ?? "-"}`,
+    `Verification cycle:  ${task.lifecycle.verificationCycle ?? "-"}`,
+    `Ledger:              ${task.integrity.valid ? "VALID" : "INVALID"}`,
+    `Snapshot:            ${task.snapshot.consistent ? "CONSISTENT" : "INCONSISTENT"}`,
+    `Progress:            ${task.progress.status}`,
+    "",
+    "Verification",
+  ];
+  for (const check of task.verification.checks) {
+    lines.push(`  ${check.id.padEnd(20)} ${check.currentResult ?? "unknown"}${Number.isInteger(check.attemptCount) ? `   attempts: ${check.attemptCount}` : ""}`);
+  }
+  if (task.verification.checks.length === 0) lines.push("  (no checks recorded)");
+  lines.push(
+    "",
+    "Diagnostics",
+    `  Cases:            ${task.diagnostics.diagnosticCaseCount}`,
+    `  Legacy diagnoses: ${task.diagnostics.legacyDiagnosisCount}`,
+    `  Interventions:    ${task.diagnostics.interventionCount}`,
+    `  Dispositions:     ${task.diagnostics.dispositionCount}`,
+  );
+  const surfaces = task.failureSurfaces ?? [];
+  if (surfaces.length > 0) {
+    lines.push("", "Failure surface");
+    for (const entry of surfaces) {
+      lines.push(`  cycle ${entry.verificationCycle}: ${entry.surface.join(", ")}`);
+    }
+  }
+  if ((task.issues ?? []).length > 0) {
+    lines.push("", "Signals");
+    for (const issue of task.issues) {
+      lines.push(`  ${issue.code}`);
+    }
+  }
+  lines.push(
+    "",
+    "Recommended next command",
+    `  ${task.next.command}`,
+  );
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/metrics.js

@@ -0,0 +1,7 @@
+import { buildTrajectoryMetrics } from "../core/trajectory-metrics.js";
+import { withResolvedTask } from "../core/task-command.js";
+export async function runMetrics({ target, packageRoot, taskId }) {
+  return withResolvedTask(target, { taskId, packageRoot }, (ctx) =>
+    buildTrajectoryMetrics({ target, packageRoot, taskId: ctx.taskId }));
+}
+export function formatMetricsResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }

package/src/commands/next.js

@@ -1,9 +1,15 @@
 import { getNextAction } from "../core/next-action.js";
 import { withResolvedTask } from "../core/task-command.js";
 
-export async function runNext({ target, packageRoot, taskId, task }) {
+export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext }) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
-    return getNextAction({ target, packageRoot, taskId: ctx?.taskId ?? null });
+    return getNextAction({
+      target,
+      packageRoot,
+      taskId: ctx?.taskId ?? null,
+      authorityContext,
+      runtimeContext,
+    });
   });
 }
 

package/src/commands/policy-discover.js

@@ -1,6 +1,6 @@
 import { discoverPolicy } from "../core/policy-discovery.js";
 import {
-  computePolicyLockData,
+  computePersistedPolicyLockData,
   loadEffectiveRules,
   readBaseline,
   writeDiscoveryReport,
@@ -15,7 +15,7 @@ export async function runPolicyDiscover({ target = process.cwd(), packageRoot, w
     await writeDiscoveryReport(target, discovery, packageRoot);
     const baseline = await readBaseline(target, packageRoot);
     const rules = await loadEffectiveRules(target, packageRoot);
-    lock = computePolicyLockData(rules, baseline);
+    lock = await computePersistedPolicyLockData(target, packageRoot, rules, baseline);
     await writePolicyLock(target, lock, packageRoot);
   }
 

package/src/commands/progress.js

@@ -1,12 +1,16 @@
 import { evaluateProgress, PROGRESS_STATUS } from "../core/progress.js";
 import { readEvents } from "../core/events.js";
 import { readWorkState } from "../core/work-state.js";
-import { resolveTaskContext } from "../core/task-context.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
 
 export { evaluateProgress };
 
 export async function runProgress({ target, packageRoot, taskId, task }) {
-  const resolved = await resolveTaskContext(target, { packageRoot, explicitTaskId: taskId ?? task });
+  const resolved = await resolveTaskContext(target, {
+    packageRoot,
+    taskId: taskId ?? task,
+    selectionMode: TASK_SELECTION_MODES.READ,
+  });
   const activeTaskId = resolved.taskId;
 
   const state = await readWorkState(target, { packageRoot, taskId: activeTaskId });

package/src/commands/record-diagnosis.js

@@ -1,11 +1,13 @@
 import { recordDiagnosis } from "../core/diagnosis.js";
+import { recordStructuredDiagnosticCase } from "../core/diagnostic-record.js";
 import { withTaskMutation } from "../core/task-command.js";
 
-export { recordDiagnosis };
+export { recordDiagnosis, recordStructuredDiagnosticCase };
 
 export async function runRecordDiagnosis({
   target,
   packageRoot,
+  file = null,
   hypothesis,
   failureClass,
   evidenceRefs = [],
@@ -15,6 +17,26 @@ export async function runRecordDiagnosis({
   taskId,
   task,
 }) {
+  if (file) {
+    const legacyFields = [hypothesis, failureClass, settledBy, nextSafeAction].some((value) => value !== undefined && value !== null)
+      || (Array.isArray(evidenceRefs) && evidenceRefs.length > 0)
+      || Boolean(evidenceRef);
+    if (legacyFields) {
+      const error = new Error("record-diagnosis accepts either --file (structured case) or legacy diagnosis fields, not both");
+      error.code = "E_INPUT_CONFLICT";
+      throw error;
+    }
+    return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-diagnosis", async (ctx) => {
+      return recordStructuredDiagnosticCase({
+        target,
+        packageRoot,
+        caseFile: file,
+        caseInput: null,
+        taskId: ctx?.taskId ?? null,
+      });
+    });
+  }
+
   const refs = Array.isArray(evidenceRefs) && evidenceRefs.length > 0
     ? evidenceRefs
     : (evidenceRef ? [evidenceRef] : []);
@@ -34,6 +56,20 @@ export async function runRecordDiagnosis({
 }
 
 export function formatRecordDiagnosisResult(result) {
+  if (result.diagnosticCase) {
+    const d = result.diagnosticCase;
+    return [
+      `FORGELOOP DIAGNOSTIC CASE RECORDED`,
+      `CYCLE: ${d.verificationCycle}`,
+      `REVISION: ${d.diagnosticRevision}`,
+      `FAILURE CLASS: ${d.failureClass}`,
+      `OBSERVATIONS: ${(d.observations ?? []).length}`,
+      `CONTRIBUTORS: ${(d.contributors ?? []).length}`,
+      `HYPOTHESES: ${(d.hypotheses ?? []).map((hypothesis) => hypothesis.id).join(", ")}`,
+      `NEXT SAFE ACTION: ${d.nextSafeAction?.statement ?? ""}`,
+      `FINGERPRINT: ${d.diagnosticFingerprint}`,
+    ].join("\n") + "\n";
+  }
   const d = result.diagnosis ?? result.event?.details ?? {};
   return [
     `FORGELOOP DIAGNOSIS RECORDED`,

package/src/commands/record-hypothesis-disposition.js

@@ -0,0 +1,45 @@
+import { recordHypothesisDisposition } from "../core/diagnostic-record.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export { recordHypothesisDisposition };
+
+export async function runRecordHypothesisDisposition({
+  target,
+  packageRoot,
+  hypothesis,
+  hypothesisRef = null,
+  status,
+  evidenceRefs = [],
+  evidenceRef = null,
+  reason,
+  taskId,
+  task,
+}) {
+  const refs = Array.isArray(evidenceRefs) && evidenceRefs.length > 0
+    ? evidenceRefs
+    : (evidenceRef ? [evidenceRef] : []);
+
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-hypothesis-disposition", async (ctx) => {
+    return recordHypothesisDisposition({
+      target,
+      packageRoot,
+      hypothesisRef: hypothesis ?? hypothesisRef,
+      status,
+      evidenceRefs: refs,
+      reason,
+      taskId: ctx?.taskId ?? null,
+    });
+  });
+}
+
+export function formatRecordHypothesisDispositionResult(result) {
+  const disposition = result.disposition ?? {};
+  return [
+    "FORGELOOP HYPOTHESIS DISPOSITION RECORDED",
+    `CYCLE: ${disposition.verificationCycle}`,
+    `HYPOTHESIS: ${disposition.hypothesisRef}`,
+    `STATUS: ${disposition.status}`,
+    `EVIDENCE: ${(disposition.evidenceRefs ?? []).join(", ")}`,
+    `REASON: ${disposition.reason}`,
+  ].join("\n") + "\n";
+}

package/src/commands/record-intervention.js

@@ -0,0 +1,35 @@
+import { recordIntervention } from "../core/diagnostic-record.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export { recordIntervention };
+
+export async function runRecordIntervention({
+  target,
+  packageRoot,
+  file = null,
+  taskId,
+  task,
+}) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-intervention", async (ctx) => {
+    return recordIntervention({
+      target,
+      packageRoot,
+      interventionFile: file,
+      interventionInput: null,
+      taskId: ctx?.taskId ?? null,
+    });
+  });
+}
+
+export function formatRecordInterventionResult(result) {
+  const intervention = result.intervention?.intervention ?? {};
+  return [
+    "FORGELOOP INTERVENTION RECORDED",
+    `CYCLE: ${result.intervention?.verificationCycle}`,
+    `ID: ${intervention.id}`,
+    `KIND: ${intervention.kind}`,
+    `STATEMENT: ${intervention.statement}`,
+    `HYPOTHESES: ${(intervention.hypothesisRefs ?? []).join(", ")}`,
+    result.repeatedSemanticIntervention ? "WARNING: this semantic intervention has been recorded before" : null,
+  ].filter((line) => line !== null).join("\n") + "\n";
+}

package/src/commands/reflect.js

@@ -0,0 +1,38 @@
+import { buildTaskReflection } from "../core/reflection.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
+
+export { buildTaskReflection };
+
+export function formatReflectResult(result) {
+  const lines = [
+    "ForgeLoop Reflection",
+    "─".repeat(56),
+    "",
+    `Task:       ${result.taskId ?? "unknown"}`,
+    `Phase:      ${result.taskPhase ?? "UNKNOWN"}`,
+    `Status:     ${result.status}`,
+    `Cycles:     ${result.verificationCycles}`,
+    `Integrity:  ${result.integrityValid ? "VALID" : "INCONSISTENT"}`,
+    "",
+    `Hypotheses: ${result.hypotheses.created} created, ${result.hypotheses.open} open, ${result.hypotheses.supported} supported, ${result.hypotheses.weakened} weakened, ${result.hypotheses.falsified} falsified`,
+    `Interventions: ${result.interventions.count} (${result.interventions.informative} informative, ${result.interventions.nonInformative} non-informative)`,
+    `Oscillation: ${result.oscillation.detected ? "DETECTED" : "none"}`,
+    result.signals.length > 0 ? `Signals: ${result.signals.join(", ")}` : "Signals: none",
+    "",
+    `Recommended protocol action: ${result.recommendedProtocolAction}`,
+  ];
+  return lines.join("\n") + "\n";
+}
+
+export async function runReflect({ target, packageRoot, taskId, task }) {
+  const resolved = await resolveTaskContext(target, {
+    packageRoot,
+    taskId: taskId ?? task,
+    selectionMode: TASK_SELECTION_MODES.READ,
+  });
+  return buildTaskReflection({
+    target,
+    packageRoot,
+    taskId: resolved?.taskId ?? null,
+  });
+}

package/src/commands/report.js

@@ -1,6 +1,14 @@
 import { evaluateReport } from "../core/report.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export { evaluateReport as runReport };
+export async function runReport(options = {}) {
+  const target = options.target;
+  const packageRoot = options.packageRoot;
+  const taskId = options.taskId ?? options.task ?? null;
+  return withResolvedTask(target, { taskId, packageRoot }, async (ctx) => {
+    return evaluateReport({ ...options, taskId: ctx?.taskId ?? null });
+  });
+}
 
 export function formatReportResult(result) {
   const lines = ["ForgeLoop Compliance"];