@cassiomc1/forgeloop 1.2.1 → 1.2.3

package/src/commands/policy-status.js

@@ -0,0 +1,33 @@
+import { evaluateTargetPolicy } from "../core/policy-engine.js";
+
+export async function runPolicyStatus({ target = process.cwd(), packageRoot, taskId = null } = {}) {
+  return evaluateTargetPolicy({ target, packageRoot, taskId });
+}
+
+export function formatPolicyStatusResult(result) {
+  const lines = [
+    `FORGELOOP POLICY STATUS: ${result.status}`,
+    `Lock: ${result.lock?.digest ?? "none"}`,
+    `Rules: ${result.rules?.length ?? 0} total (Proven: ${result.provenRules}, Inert: ${result.inertRules}, Unsupported: ${result.unsupportedRules})`,
+    `Baseline Violations: ${result.baselineViolations}`,
+    `New Violations: ${result.newViolations?.length ?? 0}`,
+    `Drift: ${result.drift?.detected ? `DETECTED (${result.drift.classification})` : "none"}`,
+  ];
+
+  if (result.errors?.length > 0) {
+    lines.push("Errors:");
+    for (const err of result.errors) {
+      lines.push(`  - ${err.code}: ${err.why || err.message || err.ruleId}`);
+      if (err.fix) lines.push(`    Fix: ${err.fix}`);
+    }
+  }
+
+  if (result.warnings?.length > 0) {
+    lines.push("Warnings:");
+    for (const warn of result.warnings) {
+      lines.push(`  - ${warn.code}: ${warn.message || warn.why}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/profile-interview.js

@@ -0,0 +1,50 @@
+import { discoverPolicy } from "../core/policy-discovery.js";
+
+export async function runProfileInterview({
+  target = process.cwd(),
+  packageRoot,
+  dryRun = false,
+} = {}) {
+  const discovery = await discoverPolicy({ target });
+  return {
+    status: "COMPLETE",
+    mode: "OPTIONAL_INTERVIEW",
+    dryRun,
+    questions: [
+      {
+        topic: "languages",
+        detected: discovery.languages,
+        recommendation: discovery.languages.join(", ") || "none",
+      },
+      {
+        topic: "testing",
+        detected: discovery.testing.detected,
+        framework: discovery.testing.framework,
+        confidence: discovery.testing.confidence,
+      },
+      {
+        topic: "linting",
+        detected: discovery.linting.detected,
+        tool: discovery.linting.tool,
+        confidence: discovery.linting.confidence,
+      },
+      {
+        topic: "architecture",
+        detected: discovery.architecture.value,
+        confidence: discovery.architecture.confidence,
+      },
+    ],
+    discovery,
+  };
+}
+
+export function formatProfileInterviewResult(result) {
+  const lines = [
+    "FORGELOOP PROFILE INTERVIEW (OPTIONAL):",
+    `Languages: ${result.discovery?.languages?.join(", ") || "none detected"}`,
+    `Testing: ${result.discovery?.testing?.detected ? `${result.discovery.testing.framework} [${result.discovery.testing.confidence}]` : "none"}`,
+    `Linting: ${result.discovery?.linting?.detected ? `${result.discovery.linting.tool} [${result.discovery.linting.confidence}]` : "none"}`,
+    `Architecture: ${result.discovery?.architecture?.value ? `${result.discovery.architecture.value} [${result.discovery.architecture.confidence}]` : "unknown"}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/reconcile-closure.js

@@ -0,0 +1,49 @@
+import { runReconcileClosure } from "../core/reconcile-closure.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export async function reconcileClosure({
+  target,
+  packageRoot,
+  taskId,
+  task,
+  checkId,
+  checkRequirement,
+  checkDetails,
+  commandArgv,
+  authorityContext,
+  runtimeContext,
+}) {
+  return withTaskMutation(
+    target,
+    { taskId: taskId ?? task, packageRoot },
+    "reconcile-closure",
+    async (ctx) => {
+      return runReconcileClosure({
+        target,
+        packageRoot,
+        taskId: ctx?.taskId ?? null,
+        checkId,
+        requirement: checkRequirement,
+        argv: commandArgv,
+        details: checkDetails,
+        authorityContext,
+        runtimeContext,
+      });
+    },
+    { explicitRequired: true },
+  );
+}
+
+export function formatReconcileClosureResult(result) {
+  const previous = result.previousRepositoryFingerprint;
+  return [
+    "FORGELOOP CHECKPOINT RECONCILED",
+    `task: ${result.taskId}`,
+    `check: ${result.checkId} (passed)`,
+    `execution: ${result.executionId}`,
+    `previous: ${previous?.branch ?? "unknown"} @ ${previous?.head ?? "unknown"}`,
+    `current: ${result.repositoryFingerprint?.branch ?? "unknown"} @ ${result.repositoryFingerprint?.head ?? "unknown"}`,
+    `event: ${result.event}`,
+    "",
+  ].join("\n");
+}

package/src/commands/rule-verify.js

@@ -0,0 +1,36 @@
+import { loadEffectiveRules } from "../core/policy-engine.js";
+import { verifyRuleMutation } from "../core/policy-mutation.js";
+
+export async function runRuleVerify({
+  target = process.cwd(),
+  packageRoot,
+  rule = null,
+} = {}) {
+  const rules = await loadEffectiveRules(target, packageRoot);
+  const targetRules = rule ? rules.filter((r) => r.id === rule) : rules;
+
+  const verifications = [];
+  for (const r of targetRules) {
+    const res = await verifyRuleMutation({ target, rule: r });
+    verifications.push(res);
+  }
+
+  const allProven = verifications.every((v) => v.status === "PROVEN" || v.status === "UNSUPPORTED");
+
+  return {
+    status: allProven ? "VALID" : "UNPROVEN",
+    verifications,
+  };
+}
+
+export function formatRuleVerifyResult(result) {
+  const lines = [
+    `FORGELOOP RULE VERIFICATION: ${result.status}`,
+  ];
+  for (const v of result.verifications ?? []) {
+    lines.push(`  - ${v.ruleId}: ${v.status} (Mutation: ${v.mutation ?? "none"}, Expected: ${v.expected ?? "n/a"}, Observed: ${v.observed ?? "n/a"})`);
+    if (v.why) lines.push(`    Why: ${v.why}`);
+    if (v.fix && v.status !== "PROVEN") lines.push(`    Fix: ${v.fix}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/validate-receipt.js

@@ -2,9 +2,10 @@ import { assertSafePath, ensureWithin, readBytes } from "../core/filesystem.js";
 import { validateReceipt } from "../core/receipt.js";
 import { assertJsonBytes, assertJsonLimits } from "../core/json-safety.js";
 import { ARTIFACT_PATHS } from "../core/artifacts.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export async function runValidateReceipt({ target, packageRoot, file }) {
-  const relativeFile = file ?? ARTIFACT_PATHS.receipt;
+async function validateReceiptFile(target, packageRoot, relativeFile) {
   await assertSafePath(target, relativeFile);
   const receiptPath = ensureWithin(target, relativeFile);
   let receipt;
@@ -16,5 +17,39 @@ export async function runValidateReceipt({ target, packageRoot, file }) {
   } catch (error) {
     throw new Error(`Unable to parse receipt ${relativeFile}: ${error.message}`);
   }
-  return validateReceipt(receipt, packageRoot);
+  try {
+    return await validateReceipt(receipt, packageRoot);
+  } catch (error) {
+    throw new Error(`Invalid receipt ${relativeFile}: ${error.message}`);
+  }
+}
+
+/**
+ * Validates an execution receipt with deterministic resolution precedence:
+ *   1. explicit `--file` validates exactly that relative file;
+ *   2. explicit or context-resolved `--task` validates that task's namespaced
+ *      `.forgeloop/task-state/<taskKey>/execution-receipt.json`;
+ *   3. a single active task is resolved automatically through the shared
+ *      task-command resolver;
+ *   4. when no task descriptors exist, the legacy singleton
+ *      `.forgeloop/execution-receipt.json` compatibility path is preserved.
+ * Multiple active tasks without `--task`/`--file` fail with E_TASK_AMBIGUOUS
+ * through the shared resolver instead of silently falling back to the legacy
+ * singleton.
+ */
+export async function runValidateReceipt({
+  target,
+  packageRoot,
+  file = null,
+  taskId = null,
+} = {}) {
+  if (file) {
+    return validateReceiptFile(target, packageRoot, file);
+  }
+  return withResolvedTask(target, { taskId, packageRoot }, async (ctx) => {
+    const relativeFile = ctx
+      ? taskArtifactPath(ctx.taskId, "receipt")
+      : ARTIFACT_PATHS.receipt;
+    return validateReceiptFile(target, packageRoot, relativeFile);
+  });
 }

package/src/core/artifact-registry.js

@@ -163,4 +163,64 @@ export const ARTIFACT_REGISTRY = Object.freeze({
     isPersisted: true,
     description: "Attested command execution provenance recording argv, cwd, resolution, status, and exit code.",
   }),
+  policyRules: Object.freeze({
+    key: "policyRules",
+    scope: "PROJECT",
+    path: PROJECT_ARTIFACT_PATHS.policyRules,
+    schema: "policy-rules",
+    owner: "OPERATOR_OR_AGENT",
+    mutability: "MUTABLE_CONFIGURATION",
+    trustRole: "POLICY_SPECIFICATION",
+    isPublic: true,
+    isPersisted: true,
+    description: "Executable policy rule definitions declaring severities, checks, why, and fix guidance.",
+  }),
+  policyDiscovery: Object.freeze({
+    key: "policyDiscovery",
+    scope: "PROJECT",
+    path: PROJECT_ARTIFACT_PATHS.policyDiscovery,
+    schema: "policy-discovery",
+    owner: "PROTOCOL_GENERATED",
+    mutability: "MUTABLE_ON_DISCOVERY",
+    trustRole: "DISCOVERED_POLICY_SPECIFICATION",
+    isPublic: true,
+    isPersisted: true,
+    description: "Deterministic repository policy discovery report with confidence scoring.",
+  }),
+  policyBaseline: Object.freeze({
+    key: "policyBaseline",
+    scope: "PROJECT",
+    path: PROJECT_ARTIFACT_PATHS.policyBaseline,
+    schema: "policy-baseline",
+    owner: "PROTOCOL_GENERATED_OR_OPERATOR",
+    mutability: "MONOTONIC_RATCHET_DOWN",
+    trustRole: "BROWNFIELD_BASELINE",
+    isPublic: true,
+    isPersisted: true,
+    description: "Brownfield policy baseline recording existing debt with sha256 violation fingerprints.",
+  }),
+  policyLock: Object.freeze({
+    key: "policyLock",
+    scope: "PROJECT",
+    path: PROJECT_ARTIFACT_PATHS.policyLock,
+    schema: "policy-lock",
+    owner: "PROTOCOL_GENERATED",
+    mutability: "ATOMIC_DIGEST_COMPILATION",
+    trustRole: "POLICY_INTEGRITY_LOCK",
+    isPublic: true,
+    isPersisted: true,
+    description: "Canonical policy lockfile holding cryptographic digest of effective rules and baseline.",
+  }),
+  policySnapshot: Object.freeze({
+    key: "policySnapshot",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.policySnapshot}`,
+    schema: "policy-snapshot",
+    owner: "PROTOCOL_GENERATED",
+    mutability: "MUTABLE_BEFORE_EXECUTION",
+    trustRole: "TASK_POLICY_ATTESTATION",
+    isPublic: true,
+    isPersisted: true,
+    description: "Task-scoped policy snapshot binding task activation to effective policy digest.",
+  }),
 });

package/src/core/audit.js

@@ -131,6 +131,29 @@ export async function evaluateAudit({
       : blocked
         ? "INCOMPLETE"
         : "INVALID";
+  let policyStatus = null;
+  const { detectPolicyCapability, evaluateTargetPolicy } = await import("./policy-engine.js");
+  const policyCapability = await detectPolicyCapability(target, packageRoot);
+  if (policyCapability === "AVAILABLE") {
+    try {
+      const policyEval = await evaluateTargetPolicy({ target, packageRoot, taskId });
+      policyStatus = {
+        status: policyEval.status,
+        provenRules: policyEval.provenRules,
+        inertRules: policyEval.inertRules,
+        unsupportedRules: policyEval.unsupportedRules,
+        baselineViolations: policyEval.baselineViolations,
+        drift: policyEval.drift?.detected ?? false,
+      };
+    } catch {
+      policyStatus = { status: "INVALID", provenRules: 0, inertRules: 0, unsupportedRules: 0, baselineViolations: 0, drift: false };
+    }
+  } else if (policyCapability === "INVALID") {
+    policyStatus = { status: "INVALID", provenRules: 0, inertRules: 0, unsupportedRules: 0, baselineViolations: 0, drift: false };
+  } else {
+    policyStatus = { status: "NOT_APPLICABLE", provenRules: 0, inertRules: 0, unsupportedRules: 0, baselineViolations: 0, drift: false };
+  }
+
   return {
     schemaVersion: 1,
     protocolVersion: PROTOCOL_VERSION,
@@ -142,6 +165,7 @@ export async function evaluateAudit({
       status: manifest ? "ready" : manifestError ? "invalid" : "missing",
       manifest: Boolean(manifest),
     },
+    policy: policyStatus,
     completion,
     changedPaths,
     publicationStatus: completion.publicationStatus,

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

@@ -1,5 +1,5 @@
 /**
- * Canonical, declarative definition of all 36 ForgeLoop CLI commands.
+ * Canonical, declarative definition of all 42 ForgeLoop CLI commands.
  * This is the machine source of truth for CLI option parsing, help text,
  * metadata, documentation generation, and conformance validation.
  *
@@ -64,7 +64,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mutation: "MUTATING",
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
-      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "show planned writes without changing files" }),
+      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "perform deterministic init planning and conflict detection without writing" }),
     }),
     writes: [".forgeloop/*", "AGENTS.md", "CLAUDE.md", ".cursor/rules/project-loop.mdc", ".github/copilot-instructions.md"],
     removes: [],
@@ -93,7 +93,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mutation: "MUTATING",
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
-      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "show planned writes without changing files" }),
+      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "perform deterministic update planning and conflict detection without writing" }),
     }),
     writes: [".forgeloop/*", "AGENTS.md", "CLAUDE.md", ".cursor/rules/project-loop.mdc", ".github/copilot-instructions.md"],
     removes: [],
@@ -426,8 +426,22 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Evaluates active task state against named enterprise policy packs.",
   }),
-  bundle: Object.freeze({
-    name: "bundle",
+  "policy-discover": Object.freeze({
+    name: "policy-discover",
+    category: "policy-audit",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--write": Object.freeze({ targetKey: "write", parseType: "boolean", takesValue: false, description: "persist discovered policy to .forgeloop/policy/discovery.json" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/policy/discovery.json", ".forgeloop/policy/policy.lock"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Discovers repository policy facts and candidate rules deterministically.",
+  }),
+  "policy-status": Object.freeze({
+    name: "policy-status",
     category: "policy-audit",
     mutation: "READ_ONLY",
     options: Object.freeze({
@@ -438,6 +452,80 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     writes: [],
     removes: [],
     mayExecuteExternalProcess: false,
+    description: "Evaluates repository and task state against effective policy rules and baseline.",
+  }),
+  "policy-diff": Object.freeze({
+    name: "policy-diff",
+    category: "policy-audit",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--before": Object.freeze({ targetKey: "before", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--before requires a path", description: "path to before policy JSON" }),
+      "--after": Object.freeze({ targetKey: "after", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--after requires a path", description: "path to after policy JSON" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Performs semantic diffing between policy versions to detect tightening or weakening.",
+  }),
+  "rule-verify": Object.freeze({
+    name: "rule-verify",
+    category: "policy-audit",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--rule": Object.freeze({ targetKey: "rule", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--rule requires an ID", description: "verify a specific policy rule ID" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Verifies policy rules against mutation fixtures to prove detector efficacy.",
+  }),
+  baseline: Object.freeze({
+    name: "baseline",
+    category: "policy-audit",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--record": Object.freeze({ targetKey: "record", parseType: "boolean", takesValue: false, description: "record current violations as brownfield baseline" }),
+      "--update": Object.freeze({ targetKey: "update", parseType: "boolean", takesValue: false, description: "ratchet baseline downward by removing resolved violations" }),
+      "--policy-reset-authorized": Object.freeze({ targetKey: "policyResetAuthorized", parseType: "boolean", takesValue: false, description: "explicit operator authority to re-record baseline during active tasks" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/policy/baseline.json", ".forgeloop/policy/policy.lock"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Manages brownfield policy baseline violations with monotonic downward ratcheting.",
+  }),
+  "profile-interview": Object.freeze({
+    name: "profile-interview",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "show planned interview questions without changing files" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Optional interactive or dry-run interview to refine project profile facts.",
+  }),
+  bundle: Object.freeze({
+    name: "bundle",
+    category: "policy-audit",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/tasks/<taskId>"],
+    removes: [],
+    mayExecuteExternalProcess: false,
     description: "Exports current task artifacts into a portable task bundle archive.",
   }),
   inspect: Object.freeze({
@@ -498,13 +586,32 @@ 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.",
   }),
+  "reconcile-closure": Object.freeze({
+    name: "reconcile-closure",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--id": Object.freeze({ targetKey: "checkId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--id requires a check ID", description: "contract verification item id used as evidence" }),
+      "--requirement": Object.freeze({ targetKey: "checkRequirement", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--requirement requires an evidence target", description: "exact contract verification item requirement text" }),
+      "--details": Object.freeze({ targetKey: "checkDetails", parseType: "json-object", takesValue: true, valueName: "json", missingValueMessage: "--details requires a JSON object", description: "additional structured execution details" }),
+      "--": Object.freeze({ targetKey: "commandArgv", parseType: "argv", takesValue: true, valueName: "argv...", description: "exact command argv to execute as objective-satisfaction evidence" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/executions/exec-<id>.json", ".forgeloop/task-state/<taskKey>/work-state.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Refreshes the work-state checkpoint of an EXECUTING task whose objective is already satisfied in the current repository, after contract-bound executed evidence, so canonical completion can proceed.",
+  }),
   "validate-receipt": Object.freeze({
     name: "validate-receipt",
     category: "verification",
     mutation: "READ_ONLY",
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
-      "--file": Object.freeze({ targetKey: "file", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--file requires a path", description: "receipt file relative to target" }),
+      ...CLI_TASK_OPTION,
+      "--file": Object.freeze({ targetKey: "file", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--file requires a path", description: "receipt file relative to target (overrides task-based receipt resolution)" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],
@@ -544,7 +651,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       "--contract-file": Object.freeze({ targetKey: "contractFile", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--contract-file requires a path", description: "path to initial contract file" }),
       "--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>/current-contract.json"],
+    writes: [".forgeloop/task-state/<taskKey>/task.json", ".forgeloop/task-state/<taskKey>/contract.json"],
     removes: [],
     mayExecuteExternalProcess: false,
     description: "Creates a new task descriptor and initializes its isolated task state namespace.",

package/src/core/cli-metadata.js

@@ -1,7 +1,7 @@
 import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
 
 /**
- * Canonical metadata for all 27 ForgeLoop CLI commands derived directly
+ * Canonical metadata for all 43 ForgeLoop CLI commands derived directly
  * from CLI_COMMAND_DEFINITIONS to guarantee zero divergence.
  */
 export const CLI_COMMAND_METADATA = Object.freeze(

package/src/core/completion-artifacts.js

@@ -26,6 +26,32 @@ import { readTaskDescriptor } from "./task-descriptor.js";
 import { assertClaimsCoverChangedPaths } from "./task-scope.js";
 import { discoverTasks } from "./task-discovery.js";
 
+/**
+ * Canonical terminal-result types shared by runtime validation, tests, and
+ * documentation conformance. Keep these single-sourced; do not re-declare
+ * the same type lists in validators or tests.
+ */
+export const TERMINAL_RESULT_TYPES = Object.freeze([
+  "PUBLICATION",
+  "PRODUCTION_READINESS",
+]);
+
+/**
+ * Canonical terminal-status sets shared by runtime validation, tests, and
+ * documentation conformance. Keep these single-sourced; do not re-declare
+ * the same status lists in validators or tests.
+ */
+export const PUBLICATION_STATUSES = Object.freeze([
+  "committed",
+  "pushed",
+  "published",
+  "deployed",
+]);
+export const PRODUCTION_READINESS_STATUSES = Object.freeze([
+  "ready",
+  "blocked",
+]);
+
 function artifactError(code, message, artifacts = []) {
   const error = new Error(message);
   error.code = code;
@@ -706,13 +732,13 @@ export async function recordTerminalResult({
   if (!target || !requirement || !type || !status || !source || !result) {
     throw artifactError("E_CHECK_INVALID", "record-terminal-result requires target, requirement, type, status, source, and result", [ARTIFACT_PATHS.state]);
   }
-  if (!["PUBLICATION", "PRODUCTION_READINESS"].includes(type)) {
+  if (!TERMINAL_RESULT_TYPES.includes(type)) {
     throw artifactError("E_FUTURE_TERMINAL_EVIDENCE", `record-terminal-result does not support type ${type}`, [ARTIFACT_PATHS.state]);
   }
-  if (type === "PUBLICATION" && !["committed", "pushed", "published", "deployed"].includes(status)) {
+  if (type === "PUBLICATION" && !PUBLICATION_STATUSES.includes(status)) {
     throw artifactError("E_CHECK_INVALID", `Invalid publication status for record-terminal-result: ${status}`, [ARTIFACT_PATHS.state]);
   }
-  if (type === "PRODUCTION_READINESS" && !["ready", "blocked"].includes(status)) {
+  if (type === "PRODUCTION_READINESS" && !PRODUCTION_READINESS_STATUSES.includes(status)) {
     throw artifactError("E_CHECK_INVALID", `Invalid production readiness status for record-terminal-result: ${status}`, [ARTIFACT_PATHS.state]);
   }