@cassiomc1/forgeloop 0.1.1 → 0.1.3

package/schemas/preflight.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/preflight.schema.json",
+  "title": "ForgeLoop preflight result",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "status", "profile", "contract", "routing", "requiredGates", "satisfiedGates", "errors"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["READY", "BLOCKED"] },
+    "profile": { "type": "object" },
+    "contract": { "type": "object" },
+    "routing": { "type": "object" },
+    "requiredGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "satisfiedGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "errors": { "type": "array", "items": { "type": "object" } },
+    "fingerprints": { "type": "object" },
+    "sources": { "type": "object" },
+    "policy": { "type": "object" }
+  },
+  "additionalProperties": false
+}

package/schemas/routing-result.schema.json

@@ -7,6 +7,7 @@
   "properties": {
     "schemaVersion": { "const": 1 },
     "protocolVersion": { "const": 1 },
+    "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
     "input": { "type": "object" },
     "primary": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
     "guides": { "type": "array", "items": { "type": "string" } },

package/schemas/source-registry.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/source-registry.schema.json",
+  "title": "ForgeLoop source registry",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "sources"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "sources": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["kind", "summary"],
+        "properties": {
+          "kind": { "enum": ["user-request", "repository-fact", "observation", "command", "agent-decision", "inference", "unknown"] },
+          "summary": { "type": "string", "minLength": 1 },
+          "path": { "type": "string", "minLength": 1 },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "command": { "type": "string", "minLength": 1 },
+          "result": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/task-bundle.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/task-bundle.schema.json",
+  "title": "ForgeLoop portable task bundle manifest",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "artifacts"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "artifacts": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+  },
+  "additionalProperties": false
+}

package/schemas/work-state.schema.json

@@ -9,6 +9,7 @@
     "protocolVersion": { "const": 1 },
     "taskId": { "type": "string", "minLength": 1 },
     "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "routeFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
     "repositoryFingerprint": {
       "type": "object",
       "required": ["branch", "head"],
@@ -20,6 +21,9 @@
     },
     "phase": { "type": "string", "minLength": 1 },
     "selectedGuides": { "type": "array", "items": { "type": "string" } },
+    "requiredGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "satisfiedGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "complianceMode": { "enum": ["advisory", "standard", "strict"] },
     "completedSteps": { "type": "array", "items": { "type": "string" } },
     "pendingSteps": { "type": "array", "items": { "type": "string" } },
     "requiredArtifacts": {
@@ -40,7 +44,9 @@
     "lastUpdated": { "type": "string", "minLength": 1 },
     "previousPhase": { "type": "string" },
     "diagnosedHypothesis": { "type": "string", "minLength": 1 },
-    "verificationEvidence": { "type": "array", "items": { "type": "object" } }
+    "verificationEvidence": { "type": "array", "items": { "type": "object" } },
+    "evidenceCoverage": { "type": "array", "items": { "type": "object" } },
+    "publicationStatus": { "enum": ["not-published", "local-only", "committed", "pushed", "published", "deployed"] }
   },
   "additionalProperties": false
 }

package/src/cli.js

@@ -14,11 +14,23 @@ import { formatRouteResult, runRoute } from "./commands/route.js";
 import { runValidateReceipt } from "./commands/validate-receipt.js";
 import { formatValidateProtocolResult, runValidateProtocol } from "./commands/validate-protocol.js";
 import { runUpdate } from "./commands/update.js";
+import { formatActivateResult, runActivate } from "./commands/activate.js";
+import { formatAdvanceResult, runAdvance } from "./commands/advance.js";
+import { formatPreflightResult, runPreflight } from "./commands/preflight.js";
+import { formatCompleteResult, runComplete } from "./commands/complete.js";
+import { formatAuditResult, runAudit } from "./commands/audit.js";
+import { formatReportResult, runReport } from "./commands/report.js";
+import { formatPolicyResult, runPolicy } from "./commands/policy.js";
+import { formatBundleResult, runBundle } from "./commands/bundle.js";
+import { formatPrepareCompletionResult, runPrepareCompletion } from "./commands/prepare-completion.js";
+import { formatRecordCheckResult, runRecordCheck } from "./commands/record-check.js";
+import { formatNextActionResult, runNext } from "./commands/next.js";
 import { resolveTarget } from "./core/filesystem.js";
 import { getPackageRoot } from "./core/templates.js";
+import { ARTIFACT_PATHS } from "./core/artifacts.js";
 
 function usage(command = null) {
-  const commands = "init|doctor|update|route|inspect|status|validate-state|clear-state|validate-receipt|validate-protocol";
+  const commands = "init|doctor|update|activate|route|preflight|advance|next|prepare-completion|record-check|complete|audit|report|policy|bundle|inspect|status|validate-state|clear-state|validate-receipt|validate-protocol";
   const options = ["  --path <directory>  target project directory (default: current directory)"];
   if (!command || command === "init" || command === "update") {
     options.push("  --dry-run           show planned writes without changing files");
@@ -37,9 +49,21 @@ function usage(command = null) {
     options.push("  --executable-change declare executable/configuration change");
     options.push("  --json              emit route result as JSON");
   }
-  if (!command || ["inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(command)) {
+  if (!command || command === "advance") {
+    options.push("  --to <phase>        destination workflow phase");
+  }
+  if (!command || ["activate", "advance", "next", "prepare-completion", "record-check", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(command)) {
     options.push("  --json              emit structured output as JSON");
   }
+  if (!command || ["preflight", "complete", "audit", "report"].includes(command)) {
+    options.push("  --strict            require strict protocol compliance");
+  }
+  if (!command || command === "policy") {
+    options.push("  <name>              policy pack name");
+  }
+  if (!command || command === "bundle") {
+    options.push("  --task <id>         task ID to export as a portable bundle");
+  }
   if (!command || ["status", "inspect", "validate-protocol"].includes(command)) {
     options.push("  --contract-file <path>  current JSON contract used for freshness comparison");
   }
@@ -53,6 +77,17 @@ function usage(command = null) {
   if (!command || command === "validate-receipt") {
     options.push("  --file <path>       receipt file relative to target");
   }
+  if (!command || command === "record-check") {
+    options.push("  --id <id>            stable check identifier");
+    options.push("  --kind <kind>        check kind (default: command)");
+    options.push("  --requirement <id>   completion requirement covered by the check");
+    options.push("  --status <status>    passed, failed, blocked, or not-run");
+    options.push("  --evidence-kind <kind> OBSERVED, INFERRED, NOT_VERIFIED, or BLOCKED");
+    options.push("  --command <text>     command already run by the agent (recorded only)");
+    options.push("  --result <text>      observed result supplied by the agent");
+    options.push("  --exit-code <number> observed process exit code");
+    options.push("  --details <json>     additional structured check details");
+  }
   options.push("  --version           show the installed package version");
   options.push("  --help              show this help");
 
@@ -72,6 +107,7 @@ export function parseArgs(argv) {
     platforms: [],
     behaviorChange: false,
     executableChange: false,
+    to: null,
     file: null,
     contractFile: null,
     routeFile: null,
@@ -79,6 +115,17 @@ export function parseArgs(argv) {
     receiptFile: null,
     taskBriefFiles: [],
     delegatedResultFiles: [],
+    checkId: null,
+    checkKind: null,
+    checkRequirement: null,
+    checkStatus: null,
+    checkEvidenceKind: null,
+    checkCommand: null,
+    checkResult: null,
+    checkExitCode: null,
+    checkDetails: null,
+    policy: null,
+    task: null,
     help: false,
     version: false,
   };
@@ -86,7 +133,7 @@ export function parseArgs(argv) {
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
-    if (["init", "doctor", "update", "route", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(argument)) {
+    if (["init", "doctor", "update", "activate", "route", "preflight", "advance", "next", "prepare-completion", "record-check", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(argument)) {
       if (command) throw new Error(`Multiple commands are not supported: ${argument}`);
       command = argument;
     } else if (argument === "--help" || argument === "-h") {
@@ -126,6 +173,16 @@ export function parseArgs(argv) {
       options.behaviorChange = true;
     } else if (argument === "--executable-change") {
       options.executableChange = true;
+    } else if (argument === "--to") {
+      const phase = argv[index + 1];
+      if (!phase || phase.startsWith("-")) throw new Error("--to requires a phase");
+      options.to = phase;
+      index += 1;
+    } else if (argument === "--task") {
+      const task = argv[index + 1];
+      if (!task || task.startsWith("-")) throw new Error("--task requires an ID");
+      options.task = task;
+      index += 1;
     } else if (argument === "--file") {
       const file = argv[index + 1];
       if (!file || file.startsWith("-")) throw new Error("--file requires a path");
@@ -153,6 +210,71 @@ export function parseArgs(argv) {
       if (!file || file.startsWith("-")) throw new Error("--delegated-result-file requires a path");
       options.delegatedResultFiles.push(file);
       index += 1;
+    } else if (argument === "--id") {
+      const id = argv[index + 1];
+      if (!id || id.startsWith("-")) throw new Error("--id requires a check ID");
+      options.checkId = id;
+      index += 1;
+    } else if (argument.startsWith("--id=")) {
+      const id = argument.slice("--id=".length);
+      if (!id || id.startsWith("-")) throw new Error("--id requires a check ID");
+      options.checkId = id;
+    } else if (argument === "--kind") {
+      const kind = argv[index + 1];
+      if (!kind || kind.startsWith("-")) throw new Error("--kind requires a check kind");
+      options.checkKind = kind;
+      index += 1;
+    } else if (argument === "--requirement") {
+      const requirement = argv[index + 1];
+      if (!requirement || requirement.startsWith("-")) throw new Error("--requirement requires an evidence target");
+      options.checkRequirement = requirement;
+      index += 1;
+    } else if (argument.startsWith("--requirement=")) {
+      const requirement = argument.slice("--requirement=".length);
+      if (!requirement) throw new Error("--requirement requires an evidence target");
+      options.checkRequirement = requirement;
+    } else if (argument === "--status") {
+      const status = argv[index + 1];
+      if (!status || status.startsWith("-")) throw new Error("--status requires a check status");
+      options.checkStatus = status;
+      index += 1;
+    } else if (argument === "--evidence-kind") {
+      const evidenceKind = argv[index + 1];
+      if (!evidenceKind || evidenceKind.startsWith("-")) throw new Error("--evidence-kind requires an evidence kind");
+      options.checkEvidenceKind = evidenceKind;
+      index += 1;
+    } else if (argument === "--command") {
+      const commandText = argv[index + 1];
+      if (!commandText || commandText.startsWith("-")) throw new Error("--command requires recorded text");
+      options.checkCommand = commandText;
+      index += 1;
+    } else if (argument === "--result") {
+      const resultText = argv[index + 1];
+      if (!resultText || resultText.startsWith("-")) throw new Error("--result requires recorded text");
+      options.checkResult = resultText;
+      index += 1;
+    } else if (argument.startsWith("--result=")) {
+      const resultText = argument.slice("--result=".length);
+      if (!resultText) throw new Error("--result requires recorded text");
+      options.checkResult = resultText;
+    } else if (argument === "--exit-code") {
+      const exitCode = argv[index + 1];
+      if (!exitCode || exitCode.startsWith("-")) throw new Error("--exit-code requires a non-negative integer");
+      if (!/^\d+$/.test(exitCode)) throw new Error("--exit-code requires a non-negative integer");
+      options.checkExitCode = Number(exitCode);
+      index += 1;
+    } else if (argument === "--details") {
+      const details = argv[index + 1];
+      if (!details || details.startsWith("-")) throw new Error("--details requires a JSON object");
+      try {
+        options.checkDetails = JSON.parse(details);
+      } catch {
+        throw new Error("--details must be valid JSON");
+      }
+      if (!options.checkDetails || typeof options.checkDetails !== "object" || Array.isArray(options.checkDetails)) {
+        throw new Error("--details must be a JSON object");
+      }
+      index += 1;
     } else if (argument === "--path") {
       options.path = argv[index + 1];
       if (!options.path || options.path.startsWith("-")) throw new Error("--path requires a directory");
@@ -162,6 +284,8 @@ export function parseArgs(argv) {
       if (!options.path || options.path.startsWith("-")) throw new Error("--path requires a directory");
     } else if (argument === "--version" || argument === "-v") {
       options.version = true;
+    } else if (!argument.startsWith("-") && command === "policy" && !options.policy) {
+      options.policy = argument;
     } else if (!argument.startsWith("-") && !command) {
       command = argument;
     } else {
@@ -171,7 +295,7 @@ export function parseArgs(argv) {
 
   if (!command) return { command: null, options };
 
-  const jsonCommands = ["doctor", "route", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
+  const jsonCommands = ["doctor", "route", "activate", "advance", "next", "prepare-completion", "record-check", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
   if (!jsonCommands.includes(command) && options.json) {
     throw new Error(`Option --json is not valid for ${command}`);
   }
@@ -181,7 +305,7 @@ export function parseArgs(argv) {
   ].includes(command) && options.dryRun) {
     throw new Error(`Option --dry-run is not valid for ${command}`);
   }
-  if (command !== "doctor" && options.strict) {
+  if (!["doctor", "preflight", "complete", "audit", "report"].includes(command) && options.strict) {
     throw new Error(`Option --strict is not valid for ${command}`);
   }
   if (command !== "doctor" && options.adopt.length > 0) {
@@ -190,6 +314,21 @@ export function parseArgs(argv) {
   if (command !== "route" && (options.work || options.surfaces.length || options.risks.length || options.platforms.length || options.behaviorChange || options.executableChange)) {
     throw new Error(`Route options are not valid for ${command}`);
   }
+  if (command !== "advance" && options.to) {
+    throw new Error(`Option --to is not valid for ${command}`);
+  }
+  if (command === "policy" && !options.policy) {
+    throw new Error("policy requires a name");
+  }
+  if (command !== "policy" && options.policy) {
+    throw new Error(`Policy name is not valid for ${command}`);
+  }
+  if (command === "bundle" && !options.task) {
+    throw new Error("bundle requires --task");
+  }
+  if (command !== "bundle" && options.task) {
+    throw new Error(`--task is not valid for ${command}`);
+  }
   if (command !== "validate-receipt" && options.file) {
     throw new Error(`Option --file is not valid for ${command}`);
   }
@@ -199,6 +338,27 @@ export function parseArgs(argv) {
   if (command !== "validate-protocol" && (options.routeFile || options.stateFile || options.receiptFile || options.taskBriefFiles.length > 0 || options.delegatedResultFiles.length > 0)) {
     throw new Error(`Protocol artifact options are not valid for ${command}`);
   }
+  const checkOptions = [
+    options.checkId,
+    options.checkKind,
+    options.checkRequirement,
+    options.checkStatus,
+    options.checkEvidenceKind,
+    options.checkCommand,
+    options.checkResult,
+    options.checkExitCode,
+    options.checkDetails,
+  ];
+  if (command !== "record-check" && checkOptions.some((value) => value !== null)) {
+    throw new Error(`Check recording options are not valid for ${command}`);
+  }
+  if (command === "record-check" && !options.help) {
+    if (!options.checkId) throw new Error("record-check requires --id");
+    if (!options.checkRequirement) throw new Error("record-check requires --requirement");
+    if (!options.checkStatus) throw new Error("record-check requires --status");
+    if (!options.checkEvidenceKind) throw new Error("record-check requires --evidence-kind");
+    if (!options.checkCommand && !options.checkResult) throw new Error("record-check requires --command or --result");
+  }
   return { command, options };
 }
 
@@ -257,7 +417,9 @@ export async function main(argv = process.argv.slice(2)) {
     }
 
     if (command === "route") {
-      const result = runRoute({
+      const result = await runRoute({
+        target,
+        packageRoot,
         workType: options.work,
         surfaces: options.surfaces,
         risks: options.risks,
@@ -269,6 +431,84 @@ export async function main(argv = process.argv.slice(2)) {
       return 0;
     }
 
+    if (command === "activate") {
+      const result = await runActivate({ target, packageRoot });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatActivateResult(result));
+      return 0;
+    }
+
+    if (command === "preflight") {
+      const result = await runPreflight({ target, packageRoot, strict: options.strict });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatPreflightResult(result));
+      return result.status === "READY" ? 0 : 1;
+    }
+
+    if (command === "advance") {
+      const result = await runAdvance({ target, packageRoot, to: options.to });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatAdvanceResult(result));
+      return 0;
+    }
+
+    if (command === "next") {
+      const result = await runNext({ target, packageRoot });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatNextActionResult(result));
+      return 0;
+    }
+
+    if (command === "prepare-completion") {
+      const result = await runPrepareCompletion({ target, packageRoot });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatPrepareCompletionResult(result));
+      return 0;
+    }
+
+    if (command === "record-check") {
+      const result = await runRecordCheck({
+        target,
+        packageRoot,
+        id: options.checkId,
+        kind: options.checkKind ?? "command",
+        requirement: options.checkRequirement,
+        status: options.checkStatus,
+        evidenceKind: options.checkEvidenceKind,
+        command: options.checkCommand ?? undefined,
+        result: options.checkResult ?? undefined,
+        exitCode: options.checkExitCode,
+        details: options.checkDetails ?? undefined,
+      });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordCheckResult(result));
+      return 0;
+    }
+
+    if (command === "complete") {
+      const result = await runComplete({ target, packageRoot, strict: options.strict });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatCompleteResult(result));
+      return result.status === "VALID" ? 0 : 1;
+    }
+
+    if (command === "audit") {
+      const result = await runAudit({ target, packageRoot, strict: options.strict });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatAuditResult(result));
+      return result.status === "VALID" ? 0 : 1;
+    }
+
+    if (command === "report") {
+      const result = await runReport({ target, packageRoot, strict: options.strict });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatReportResult(result));
+      return result.verdict === "VALID" ? 0 : 1;
+    }
+
+    if (command === "policy") {
+      const result = await runPolicy({ target, packageRoot, name: options.policy });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatPolicyResult(result));
+      return 0;
+    }
+
+    if (command === "bundle") {
+      const result = await runBundle({ target, packageRoot, taskId: options.task });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatBundleResult(result));
+      return 0;
+    }
+
     if (command === "inspect") {
       const result = await inspectTarget({ target, packageRoot, contractFile: options.contractFile });
       console.log(options.json ? JSON.stringify(result, null, 2) : formatInspectResult(result));
@@ -285,9 +525,9 @@ export async function main(argv = process.argv.slice(2)) {
       const result = await runValidateProtocol({
         target,
         packageRoot,
-        routeFile: options.routeFile,
-        stateFile: options.stateFile,
-        receiptFile: options.receiptFile,
+        stateFile: options.stateFile ?? ARTIFACT_PATHS.state,
+        receiptFile: options.receiptFile ?? ARTIFACT_PATHS.receipt,
+        routeFile: options.routeFile ?? ARTIFACT_PATHS.route,
         contractFile: options.contractFile,
         taskBriefFiles: options.taskBriefFiles,
         delegatedResultFiles: options.delegatedResultFiles,

package/src/commands/activate.js

@@ -0,0 +1,11 @@
+import { activateSession } from "../core/activation.js";
+
+export { activateSession };
+
+export async function runActivate({ target, packageRoot }) {
+  return activateSession(target, packageRoot);
+}
+
+export function formatActivateResult(result) {
+  return `activated: ${result.activationMarker}\nsession: ${result.sessionId}\n`;
+}

package/src/commands/advance.js

@@ -0,0 +1,12 @@
+import { advanceWorkState } from "../core/phase.js";
+
+export { advanceWorkState };
+
+export async function runAdvance({ target, packageRoot, to }) {
+  if (!to) throw new Error("--to is required for advance");
+  return advanceWorkState(target, to, { packageRoot });
+}
+
+export function formatAdvanceResult(result) {
+  return `phase: ${result.phase}\nprevious: ${result.previousPhase ?? "none"}\n`;
+}

package/src/commands/audit.js

@@ -0,0 +1,12 @@
+import { evaluateAudit } from "../core/audit.js";
+
+export { evaluateAudit as runAudit };
+
+export function formatAuditResult(result) {
+  const lines = [`FORGELOOP AUDIT: ${result.status}`];
+  for (const error of result.errors) {
+    lines.push(`${error.code}: ${error.message}`);
+    if (error.next) lines.push(`NEXT: ${error.next}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/bundle.js

@@ -0,0 +1,10 @@
+import { exportTaskBundle } from "../core/bundles.js";
+
+export async function runBundle({ target, packageRoot, taskId }) {
+  if (!taskId) throw new Error("--task is required for bundle");
+  return exportTaskBundle(target, taskId, packageRoot);
+}
+
+export function formatBundleResult(result) {
+  return `bundle: ${result.taskId}\npath: ${result.path}\nartifacts: ${result.artifacts.join(", ")}\n`;
+}

package/src/commands/complete.js

@@ -0,0 +1,18 @@
+import { runComplete as evaluateAndComplete } from "../core/completion.js";
+
+export { evaluateAndComplete as runComplete };
+
+export function formatCompleteResult(result) {
+  const lines = [`FORGELOOP COMPLETE: ${result.status}`];
+  if (result.status === "VALID") {
+    lines.push(`TASK: ${result.taskStatus}`);
+    lines.push(`VERIFICATION: ${result.verificationStatus}`);
+    lines.push(`PUBLICATION: ${result.publicationStatus}`);
+    lines.push(`PRODUCTION_READINESS: ${result.productionReadiness}`);
+  }
+  for (const error of result.errors) {
+    lines.push(`${error.code}: ${error.message}`);
+    if (error.next) lines.push(`NEXT: ${error.next}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/next.js

@@ -0,0 +1,29 @@
+import { getNextAction } from "../core/next-action.js";
+
+export async function runNext({ target, packageRoot }) {
+  return getNextAction({ target, packageRoot });
+}
+
+export function formatNextActionResult(result) {
+  const lines = [
+    `FORGELOOP NEXT: ${result.nextAction}`,
+    `PHASE: ${result.currentPhase}`,
+  ];
+  if (result.reasons.length > 0) {
+    lines.push("REASONS:");
+    lines.push(...result.reasons.map((reason) => `- ${reason.code}: ${reason.message}`));
+  }
+  if (result.commands.length > 0) {
+    lines.push("COMMANDS (SAFE SYNOPSIS ONLY):");
+    lines.push(...result.commands.map((command) => `- ${command}`));
+  }
+  if (result.commandSpecs.length > 0) {
+    lines.push("STRUCTURED COMMAND SPECS: Available in --json output; direct-process argv data, not shell syntax.");
+  }
+  if (result.missingArtifacts.length > 0) {
+    lines.push("MISSING ARTIFACTS:");
+    lines.push(...result.missingArtifacts.map((artifact) => `- ${artifact}`));
+  }
+  if (result.terminal) lines.push("STATE: TERMINAL");
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/policy.js

@@ -0,0 +1,19 @@
+import { createConfig, writeConfig } from "../core/config.js";
+import { getPolicy, validatePolicy } from "../core/policies.js";
+
+export async function runPolicy({ target, packageRoot, name }) {
+  const policy = getPolicy(name);
+  await validatePolicy(policy, packageRoot);
+  const config = createConfig({
+    complianceMode: policy.complianceMode,
+    policy: policy.name,
+    requiredGates: policy.requiredGates,
+    requiredEvidence: policy.requiredEvidence,
+  });
+  await writeConfig(target, config, packageRoot);
+  return { policy, config };
+}
+
+export function formatPolicyResult(result) {
+  return `policy: ${result.policy.name}\nmode: ${result.policy.complianceMode}\n`;
+}

package/src/commands/preflight.js

@@ -0,0 +1,12 @@
+import { runPreflight as evaluateAndPersistPreflight } from "../core/preflight.js";
+
+export { evaluateAndPersistPreflight as runPreflight };
+
+export function formatPreflightResult(result) {
+  const lines = [`FORGELOOP PREFLIGHT: ${result.status}`];
+  for (const error of result.errors) {
+    lines.push(`${error.code}: ${error.message}`);
+    if (error.next) lines.push(`NEXT: ${error.next}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/prepare-completion.js

@@ -0,0 +1,18 @@
+import { prepareCompletion as prepareCompletionArtifacts } from "../core/completion-artifacts.js";
+
+export { prepareCompletionArtifacts as prepareCompletion };
+
+export async function runPrepareCompletion({ target, packageRoot }) {
+  return prepareCompletionArtifacts({ target, packageRoot });
+}
+
+export function formatPrepareCompletionResult(result) {
+  return [
+    "FORGELOOP COMPLETION PREPARED",
+    `receipt: ${result.path}`,
+    `task: ${result.receipt.taskId}`,
+    `required evidence: ${result.requiredEvidence.length}`,
+    `changed paths: ${result.changedPaths.length}`,
+    "",
+  ].join("\n");
+}

package/src/commands/record-check.js

@@ -0,0 +1,20 @@
+import { recordCheck as recordCheckArtifact } from "../core/completion-artifacts.js";
+
+export { recordCheckArtifact as recordCheck };
+
+export async function runRecordCheck(input) {
+  return recordCheckArtifact(input);
+}
+
+export function formatRecordCheckResult(result) {
+  return [
+    "FORGELOOP CHECK RECORDED",
+    `id: ${result.check.id}`,
+    `requirement: ${result.check.requirement}`,
+    `status: ${result.check.status}`,
+    `evidence: ${result.evidence.kind}`,
+    `coverage: ${result.coverage.find((item) => item.requirement === result.check.requirement)?.status ?? "NOT_VERIFIED"}`,
+    `receipt: ${result.path}`,
+    "",
+  ].join("\n");
+}