@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/scripts/generate-agent-protocol-summary.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ARTIFACT_REGISTRY } from "../src/core/artifact-registry.js";
+import { CLI_COMMAND_DEFINITIONS } from "../src/core/cli-command-definitions.js";
+import { PUBLIC_ERROR_REGISTRY } from "../src/core/error-codes.js";
+import { protocolInfo } from "../src/core/protocol-info.js";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const outputPath = path.join(repositoryRoot, "docs", "AGENT_PROTOCOL_SUMMARY.md");
+
+function cell(value) {
+  const normalized = String(value ?? "");
+  return (normalized || "n/a").replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+function table(headers, rows) {
+  const lines = [
+    `| ${headers.map(cell).join(" | ")} |`,
+    `| ${headers.map(() => "---").join(" | ")} |`,
+  ];
+  for (const row of rows) lines.push(`| ${row.map(cell).join(" | ")} |`);
+  return lines.join("\n");
+}
+
+function commandCatalog() {
+  const groups = new Map();
+  for (const command of Object.values(CLI_COMMAND_DEFINITIONS).sort((left, right) => left.name.localeCompare(right.name))) {
+    const commands = groups.get(command.category) ?? [];
+    commands.push(command);
+    groups.set(command.category, commands);
+  }
+  return [...groups.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([category, commands]) => [
+      `### ${category}`,
+      table(["Command", "Mutation", "Purpose"], commands.map((command) => [command.name, command.mutation, command.description])),
+    ])
+    .flat()
+    .join("\n\n");
+}
+
+async function render() {
+  const packageJson = JSON.parse(await readFile(path.join(repositoryRoot, "package.json"), "utf8"));
+  const info = protocolInfo({ packageVersion: packageJson.version });
+  const features = Object.entries(info.features)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, feature]) => [name, feature.version ?? "n/a", feature.supported === false ? "no" : "yes"]);
+  const artifacts = Object.values(ARTIFACT_REGISTRY)
+    .filter((artifact) => artifact.isPublic)
+    .sort((left, right) => left.key.localeCompare(right.key))
+    .map((artifact) => [artifact.key, artifact.scope, artifact.path, artifact.schema, artifact.trustRole]);
+  const errors = Object.values(PUBLIC_ERROR_REGISTRY)
+    .filter((error) => /^(E_(CLI|WORKSPACE|HANDOFF|RESPONSIBILITY|VERIFICATION_SCOPE|REVISION|ATTESTATION)_)/u.test(error.code))
+    .sort((left, right) => left.code.localeCompare(right.code))
+    .map((error) => [error.code, error.meaning]);
+
+  return `# ForgeLoop Agent Protocol Summary
+
+> Generated from the ForgeLoop protocol registries. This file is a concise navigation aid; the normative documents, schemas, and CLI implementation remain authoritative.
+
+## Scope
+
+ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
+
+Protocol version: ${info.protocolVersion}
+Package version: ${packageJson.version}
+
+## Canonical loop
+
+1. Discover existing work with forgeloop task-list --json.
+2. Select or create one task, then run forgeloop next --task <id> --json.
+3. Persist the contract, route, gates, and source registry; require forgeloop preflight to return READY.
+4. Execute bounded checks through the canonical CLI and preserve execution provenance.
+5. Reconcile continuity, inspect evidence, and advance through VERIFYING and REVIEWING.
+6. Run forgeloop complete; accept completion only when the validator returns VALID.
+7. Run forgeloop next again and follow the returned lifecycle action to a terminal state or an explicit blocker.
+
+## Authority boundaries
+
+- Protocol-derived facts outrank actor-provided labels, free-form summaries, and guessed identities.
+- Optional artifacts are reported as NOT_APPLICABLE when absent; malformed active security artifacts fail closed.
+- Workspace binding confirms an explicit Git worktree identity but is not a portability requirement for attestation.
+- Handoff envelopes record immutable intent and state snapshots; they do not delegate work or grant completion authority.
+- Responsibility contracts constrain paths, checks, and frozen inputs; they do not prove identity or authorship.
+- Verification scope describes planned verification breadth. Attestation coverage proves content for a concrete revision. These are separate claims.
+- Attestation manifests exclude ForgeLoop protocol metadata and bind to the completion receipt and append-only ledger without circular references.
+- Verification commands are read-only. Signing is external; private keys and credentials are never persisted by ForgeLoop.
+
+## Lifecycle
+
+Phases: ${info.lifecycle.phases.join(", ")}
+
+## Feature registry
+
+${table(["Feature", "Version", "Supported"], features)}
+
+## Public artifact registry
+
+${table(["Key", "Scope", "Path", "Schema", "Trust role"], artifacts)}
+
+## Command catalog
+
+${commandCatalog()}
+
+## Stable boundary and attestation errors
+
+${table(["Code", "Meaning"], errors)}
+
+## Authoritative implementation surfaces
+
+- Normative protocol: LOOP_ENGINEERING.md and PROTOCOL_INTEGRATION.md.
+- Artifact contracts: schemas/.
+- Lifecycle and command behavior: src/core/ and src/cli.js.
+- Integration surface: src/integration.js, src/integration.d.ts, and integrations/.
+- User-facing command and artifact references: docs/CLI_REFERENCE.md and docs/ARTIFACT_REFERENCE.md.
+`;
+}
+
+const check = process.argv.includes("--check");
+const content = await render();
+let current = null;
+try {
+  current = await readFile(outputPath, "utf8");
+} catch (error) {
+  if (error.code !== "ENOENT") throw error;
+}
+
+if (check) {
+  if (current !== content) {
+    console.error(`Generated agent summary is stale: ${path.relative(repositoryRoot, outputPath)}`);
+    process.exit(1);
+  }
+  console.log(`Generated agent summary is current: ${path.relative(repositoryRoot, outputPath)}`);
+} else {
+  await writeFile(outputPath, content, "utf8");
+  console.log(`Generated ${path.relative(repositoryRoot, outputPath)}`);
+}

package/scripts/generate-shell-completions.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CLI_COMMAND_DEFINITIONS } from "../src/core/cli-command-definitions.js";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const completionDirectory = path.join(repositoryRoot, "completions");
+const commands = Object.keys(CLI_COMMAND_DEFINITIONS).sort();
+
+function shellSingleQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\\"'\\\"'")}'`;
+}
+
+function optionsFor(command) {
+  return Object.keys(CLI_COMMAND_DEFINITIONS[command].options)
+    .filter((name) => name.startsWith("--"))
+    .sort();
+}
+
+function bashCompletion() {
+  const commandWords = commands.join(" ");
+  const commandCases = commands
+    .map((command) => `${command}) command="${command}" ;;`)
+    .join("\n      ");
+  const optionCases = commands
+    .map((command) => `    ${command}) COMPREPLY=( $(compgen -W ${shellSingleQuote(optionsFor(command).join(" "))} -- "$cur") );;`)
+    .join("\n");
+  return [
+    "# Generated by scripts/generate-shell-completions.mjs. Do not edit.",
+    "_forgeloop() {",
+    "  local cur command",
+    "  COMPREPLY=()",
+    "  cur=\"\\${COMP_WORDS[COMP_CWORD]}\"",
+    "  command=\"\"",
+    "  for word in \"\\${COMP_WORDS[@]:1}\"; do",
+    "    case \"\\${word}\" in",
+    `      ${commandCases}`,
+    "    esac",
+    "  done",
+    "  if [[ -z \"\\${command}\" && \"\\${cur}\" != -* ]]; then",
+    `    COMPREPLY=( $(compgen -W ${shellSingleQuote(commandWords)} -- "$cur") )`,
+    "    return",
+    "  fi",
+    "  case \"\\${command}\" in",
+    optionCases,
+    `    *) COMPREPLY=( $(compgen -W ${shellSingleQuote("--help --version --path")} -- "$cur") ) ;;`,
+    "  esac",
+    "}",
+    "complete -F _forgeloop forgeloop",
+    "",
+  ].join("\n");
+}
+
+function zshCompletion() {
+  const commandCaseLines = commands
+    .map((command) => {
+      const options = optionsFor(command)
+        .map((option) => shellSingleQuote(`${option}[${CLI_COMMAND_DEFINITIONS[command].options[option].description}]`))
+        .join(" ");
+      return `  ${command}) _arguments ${options} ;;`;
+    })
+    .join("\n");
+  return [
+    "#compdef forgeloop",
+    "# Generated by scripts/generate-shell-completions.mjs. Do not edit.",
+    `_arguments \\
+  '1:command:(${commands.join(" ")})' \\
+  '*::options:->options'`,
+    "case $words[2] in",
+    commandCaseLines,
+    "  *) _arguments '--help[show this help]' '--version[show the installed package version]' '--path[target project directory]' ;;",
+    "esac",
+    "",
+  ].join("\n");
+}
+
+function fishCompletion() {
+  const lines = [
+    "# Generated by scripts/generate-shell-completions.mjs. Do not edit.",
+    `complete -c forgeloop -f -n '__fish_use_subcommand' -a '${commands.join(" ")}'`,
+  ];
+  for (const command of commands) {
+    for (const option of optionsFor(command)) {
+      const description = CLI_COMMAND_DEFINITIONS[command].options[option].description.replaceAll("'", "\\'");
+      lines.push(`complete -c forgeloop -f -n '__fish_seen_subcommand_from ${command}' -l '${option.slice(2)}' -d '${description}'`);
+    }
+  }
+  lines.push("complete -c forgeloop -f -l help -s h -d 'show this help'");
+  lines.push("complete -c forgeloop -f -l version -s v -d 'show the installed package version'");
+  return `${lines.join("\n")}\n`;
+}
+
+const outputs = new Map([
+  ["forgeloop.bash", bashCompletion()],
+  ["_forgeloop", zshCompletion()],
+  ["forgeloop.fish", fishCompletion()],
+]);
+
+export async function generateShellCompletions({ write = false } = {}) {
+  const results = [];
+  for (const [name, expected] of outputs) {
+    const filePath = path.join(completionDirectory, name);
+    let actual = null;
+    try {
+      actual = await readFile(filePath, "utf8");
+    } catch {
+      // A missing generated file is reported below.
+    }
+    if (write) {
+      await writeFile(filePath, expected, "utf8");
+      results.push({ name, status: "written" });
+    } else {
+      results.push({ name, status: actual === expected ? "current" : "stale" });
+    }
+  }
+  return results;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const write = process.argv.includes("--write");
+  const results = await generateShellCompletions({ write });
+  const stale = results.filter((item) => item.status === "stale");
+  if (stale.length > 0) {
+    console.error(`Generated shell completions are stale: ${stale.map((item) => item.name).join(", ")}`);
+    process.exitCode = 1;
+  } else {
+    console.log(write ? "Generated shell completions." : "Shell completions are current.");
+  }
+}

package/scripts/write-forgeloop-attestation-summary.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+function usage() {
+  return [
+    "Usage: node scripts/write-forgeloop-attestation-summary.mjs --input <result.json> [--output <summary.md>]",
+    "",
+    "When --output is omitted, GITHUB_STEP_SUMMARY is used when available; otherwise the summary is written to stdout.",
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const options = { input: null, output: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--help" || argument === "-h") {
+      console.log(usage());
+      return null;
+    }
+    if (argument === "--input" || argument === "--output") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("-")) throw new Error(`${argument} requires a value`);
+      options[argument.slice(2)] = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${argument}`);
+  }
+  if (!options.input) throw new Error("--input is required");
+  return options;
+}
+
+function safeNumber(value) {
+  return Number.isFinite(value) ? value : 0;
+}
+
+function summaryFor(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    throw new Error("The attestation result must be a JSON object");
+  }
+  const changed = safeNumber(result.changedPaths);
+  const covered = safeNumber(result.coveredPaths);
+  const uncovered = Array.isArray(result.uncoveredPaths) ? result.uncoveredPaths.length : 0;
+  const signature = result.signature && typeof result.signature === "object"
+    ? result.signature
+    : {};
+  const errorCodes = Array.isArray(result.errors)
+    ? [...new Set(result.errors.map((error) => error?.code).filter(Boolean))].sort()
+    : [];
+  const lines = [
+    "## ForgeLoop Attestation",
+    "",
+    `- **Status:** ${String(result.status ?? "UNKNOWN")}`,
+    `- **Level:** ${String(result.level ?? "UNKNOWN")}`,
+    `- **Revision provider:** ${String(result.revisionProvider ?? "unknown")}`,
+    `- **Base:** ${String(result.baseRevision ?? "unknown")}`,
+    `- **Head:** ${String(result.headRevision ?? "unknown")}`,
+    `- **Coverage:** ${covered} / ${changed} changed paths`,
+    `- **Uncovered paths:** ${uncovered}`,
+    `- **Tasks:** ${safeNumber(result.tasks)}`,
+    `- **Signature:** ${String(signature.status ?? "NOT_CHECKED")}`,
+  ];
+  if (errorCodes.length > 0) {
+    lines.push("", "**Stable error codes**", "", ...errorCodes.map((code) => `- \`${code}\``));
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  if (!options) return 0;
+  const result = JSON.parse(await readFile(path.resolve(options.input), "utf8"));
+  const summary = summaryFor(result);
+  const destination = options.output ?? process.env.GITHUB_STEP_SUMMARY;
+  if (destination) {
+    await writeFile(path.resolve(destination), `${summary}\n`, "utf8");
+    console.log(`Wrote ForgeLoop attestation summary to ${destination}`);
+  } else {
+    process.stdout.write(`${summary}\n`);
+  }
+  return 0;
+}
+
+try {
+  process.exitCode = await main();
+} catch (error) {
+  console.error(`Attestation summary failed: ${error.message}`);
+  console.error(usage());
+  process.exitCode = 2;
+}

package/src/cli.js

@@ -67,11 +67,25 @@ import {
 } from "./commands/task-repair-legacy-recovery.js";
 import { formatTaskLockStatusResult } from "./commands/task-lock-status.js";
 import { formatProtocolInfoResult } from "./commands/protocol-info.js";
+import { formatWorkspaceBindResult } from "./commands/workspace-bind.js";
+import { formatWorkspaceStatusResult } from "./commands/workspace-status.js";
+import { formatHandoffCreateResult } from "./commands/handoff-create.js";
+import { formatHandoffListResult } from "./commands/handoff-list.js";
+import { formatHandoffShowResult } from "./commands/handoff-show.js";
+import { formatResponsibilitySetResult } from "./commands/responsibility-set.js";
+import { formatResponsibilityStatusResult } from "./commands/responsibility-status.js";
+import { formatVerifyScopeResult } from "./commands/verify-scope.js";
+import { formatAttestationCreateResult } from "./commands/attestation-create.js";
+import { formatAttestationVerifyResult } from "./commands/attestation-verify.js";
+import { formatAttestationStatusResult } from "./commands/attestation-status.js";
+import { formatAttestationVerifyRangeResult } from "./commands/attestation-verify-range.js";
 import { defaultCommandInputValues, validateForgeLoopCommandInput } from "./core/command-input.js";
 import { COMMAND_EXECUTORS } from "./core/command-executors.js";
 import { resolveTarget } from "./core/filesystem.js";
 import { getPackageRoot } from "./core/templates.js";
 import { CLI_COMMAND_DEFINITIONS, buildOptionLookup, getPositionalDefinitions } from "./core/cli-command-definitions.js";
+import { exitCodeForError } from "./core/exit-codes.js";
+import { E_CLI_INVOCATION_INVALID } from "./core/error-codes.js";
 
 export const COMMANDS = Object.freeze(Object.keys(CLI_COMMAND_DEFINITIONS));
 
@@ -295,9 +309,14 @@ export function validateCliSemantics({ command, options } = {}) {
 }
 
 export function parseArgs(argv) {
-  const parsed = parseCliSyntax(argv);
-  validateCliSemantics(parsed);
-  return parsed;
+  try {
+    const parsed = parseCliSyntax(argv);
+    validateCliSemantics(parsed);
+    return parsed;
+  } catch (error) {
+    if (!error.code) error.code = E_CLI_INVOCATION_INVALID;
+    throw error;
+  }
 }
 
 async function packageVersion(packageRoot) {
@@ -337,7 +356,9 @@ export const COMMAND_HANDLERS = Object.freeze({
       for (const item of result.findings) {
         console.log(`${item.severity}: ${item.code}: ${item.path} - ${item.message}`);
       }
-      console.log(result.ok ? "healthy: ForgeLoop target is ready" : "unhealthy: ForgeLoop target needs attention");
+      console.log(result.ok
+        ? "healthy: ForgeLoop target is ready; project profile is available"
+        : "unhealthy: ForgeLoop target needs attention");
     }
     return result.ok ? 0 : 1;
   },
@@ -396,6 +417,66 @@ export const COMMAND_HANDLERS = Object.freeze({
     renderJsonOr(options, result, formatRunCheckResult);
     return exitCode;
   },
+  "workspace-bind": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["workspace-bind"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatWorkspaceBindResult);
+    return exitCode;
+  },
+  "workspace-status": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["workspace-status"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatWorkspaceStatusResult);
+    return exitCode;
+  },
+  "handoff-create": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["handoff-create"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatHandoffCreateResult);
+    return exitCode;
+  },
+  "handoff-list": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["handoff-list"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatHandoffListResult);
+    return exitCode;
+  },
+  "handoff-show": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["handoff-show"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatHandoffShowResult);
+    return exitCode;
+  },
+  "responsibility-set": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["responsibility-set"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatResponsibilitySetResult);
+    return exitCode;
+  },
+  "responsibility-status": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["responsibility-status"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatResponsibilityStatusResult);
+    return exitCode;
+  },
+  "verify-scope": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["verify-scope"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatVerifyScopeResult);
+    return exitCode;
+  },
+  "attestation-create": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["attestation-create"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatAttestationCreateResult);
+    return exitCode;
+  },
+  "attestation-verify": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["attestation-verify"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatAttestationVerifyResult);
+    return exitCode;
+  },
+  "attestation-status": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["attestation-status"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatAttestationStatusResult);
+    return exitCode;
+  },
+  "attestation-verify-range": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["attestation-verify-range"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatAttestationVerifyRangeResult);
+    return exitCode;
+  },
   "run-action": async ({ target, packageRoot, options }) => {
     const { result, exitCode } = await COMMAND_EXECUTORS["run-action"]({ target, packageRoot, options });
     renderJsonOr(options, result, formatRunActionResult);
@@ -667,7 +748,17 @@ export const COMMAND_TABLE = Object.freeze(
 );
 
 export async function main(argv = process.argv.slice(2)) {
+  const jsonRequested = argv.some((argument) => argument === "--json" || argument.startsWith("--json="));
+  const jsonErrorsAllowed = jsonRequested;
   try {
+    if (argv[0] === "help") {
+      const helpCommand = argv[1] ?? null;
+      if (helpCommand && !CLI_COMMAND_DEFINITIONS[helpCommand]) {
+        throw new Error(`Unknown command for help: ${helpCommand}`);
+      }
+      console.log(usage(helpCommand));
+      return helpCommand ? 0 : 1;
+    }
     const { command, options } = parseArgs(argv);
     if (options.version) {
       console.log(await packageVersion(getPackageRoot()));
@@ -693,8 +784,25 @@ export async function main(argv = process.argv.slice(2)) {
       options,
     });
   } catch (error) {
-    console.error(`error: ${error.code ? `${error.code}: ` : ""}${error.message}`);
-    return 1;
+    if (jsonErrorsAllowed) {
+      const payload = JSON.stringify({
+        status: "ERROR",
+        ok: false,
+        error: {
+          code: error.code ?? "E_CLI_INVOCATION_INVALID",
+          message: error.message,
+          ...(error.next ? { next: error.next } : {}),
+          ...(error.artifacts ? { artifacts: error.artifacts } : {}),
+        },
+      }, null, 2);
+      // Keep stderr as the diagnostic channel while also emitting the same
+      // structured envelope on stdout for machine consumers.
+      console.log(payload);
+      console.error(payload);
+    } else {
+      console.error(`error: ${error.code ? `${error.code}: ` : ""}${error.message}`);
+    }
+    return exitCodeForError(error);
   }
 }
 

package/src/commands/attestation-create.js

@@ -0,0 +1,30 @@
+import { buildAttestationStatement, writeAttestationStatement } from "../core/attestation.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import { assertTaskMutationAllowed } from "../core/task-claim-state.js";
+import { readWorkState } from "../core/work-state.js";
+import { assertWorkspaceBinding } from "../core/workspace-binding.js";
+
+export async function runAttestationCreate({ target, packageRoot, taskId } = {}) {
+  return withTaskTransaction({ target, taskId, packageRoot, operation: "attestation-create", recordCommitEvent: true }, async () => {
+    const state = await readWorkState(target, { packageRoot, taskId });
+    if (!state || state.phase !== "COMPLETE") {
+      const error = new Error("attestation-create requires a COMPLETE task");
+      error.code = "E_ATTESTATION_STATEMENT_INVALID";
+      throw error;
+    }
+    // COMPLETE releases ordinary write claims, but a statement is a
+    // protocol-owned derivative of that terminal state. Keep this command
+    // terminal-safe while refusing all ordinary task mutations.
+    await assertTaskMutationAllowed(target, { taskId, packageRoot }).catch((error) => {
+      if (error.code !== "E_TASK_COMPLETE") throw error;
+    });
+    await assertWorkspaceBinding(target, { taskId, packageRoot, operation: "attestation-create" });
+    const built = await buildAttestationStatement({ target, packageRoot, taskId });
+    const written = await writeAttestationStatement({ target, packageRoot, taskId, statement: built.statement });
+    return { ...written, statementFingerprint: built.fingerprint, manifestFingerprint: built.manifest.fingerprint };
+  });
+}
+
+export function formatAttestationCreateResult(result) {
+  return `FORGELOOP ATTESTATION CREATED\ntask: ${result.statement.predicate.task.taskId}\nfingerprint: ${result.statementFingerprint}\npath: ${result.path}\nsubject: sha256:${result.statement.subject[0].digest.sha256}\n\n`;
+}

package/src/commands/attestation-status.js

@@ -0,0 +1,12 @@
+import { resolveAttestationStatus } from "../core/attestation.js";
+
+export async function runAttestationStatus({ target, packageRoot, taskId } = {}) {
+  return resolveAttestationStatus({ target, packageRoot, taskId });
+}
+
+export function formatAttestationStatusResult(result) {
+  const lines = [`FORGELOOP ATTESTATION: ${result.status}`, `TASK: ${result.taskId}`, `LEVEL: ${result.level}`, `CONTENT: ${result.content}`, `RECEIPT: ${result.receipt}`, `LEDGER: ${result.ledger}`, `SIGNATURE: ${result.signature}`, `FILES: ${result.files}`];
+  if (result.subject) lines.push(`SUBJECT: ${result.subject}`);
+  for (const error of result.errors ?? []) lines.push(`${error.code}: ${error.message}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/attestation-verify-range.js

@@ -0,0 +1,32 @@
+import { evaluateAttestationCoverage } from "../core/attestation-coverage.js";
+
+export async function runAttestationVerifyRange(options = {}) {
+  return evaluateAttestationCoverage({
+    target: options.target,
+    packageRoot: options.packageRoot,
+    revisionProvider: options.revisionProvider ?? "git",
+    baseRevision: options.baseRevision,
+    headRevision: options.headRevision,
+    requireCompleteCoverage: options.requireCompleteCoverage === true,
+    requireSignature: options.requireSignature === true,
+    signingProvider: options.signingProvider,
+    signerPolicy: {
+      identity: options.attestationIdentity,
+      issuer: options.attestationIssuer,
+      trustedRoot: options.trustedRoot,
+    },
+  });
+}
+
+export function formatAttestationVerifyRangeResult(result) {
+  return [
+    `FORGELOOP REVISION VERIFICATION: ${result.status}`,
+    `LEVEL: ${result.level}`,
+    `CHANGED: ${result.changedPaths}`,
+    `COVERED: ${result.coveredPaths}`,
+    `UNCOVERED: ${result.uncoveredPaths.length}`,
+    `TASKS: ${result.tasks}`,
+    ...result.errors.map((error) => `${error.code}: ${error.message}`),
+    "",
+  ].join("\n");
+}

package/src/commands/attestation-verify.js

@@ -0,0 +1,23 @@
+import { verifyAttestation } from "../core/attestation-verifier.js";
+
+export async function runAttestationVerify(options = {}) {
+  return verifyAttestation({
+    target: options.target,
+    packageRoot: options.packageRoot,
+    taskId: options.taskId,
+    revision: options.attestationRef,
+    bundlePath: options.attestationBundle,
+    identity: options.attestationIdentity,
+    issuer: options.attestationIssuer,
+    revisionProvider: options.revisionProvider,
+    signingProvider: options.signingProvider,
+    trustedRoot: options.trustedRoot,
+    requireSignature: options.requireSignature === true,
+  });
+}
+
+export function formatAttestationVerifyResult(result) {
+  const lines = [`FORGELOOP ATTESTATION: ${result.status}`, `LEVEL: ${result.level}`, `CONTENT: ${result.content.status}`];
+  for (const error of result.errors ?? []) lines.push(`${error.code}: ${error.message}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/handoff-create.js

@@ -0,0 +1,9 @@
+import { createCanonicalHandoff } from "../core/handoff.js";
+
+export async function runHandoffCreate({ target, packageRoot, taskId, recipientHint, handoffNote } = {}) {
+  return createCanonicalHandoff(target, { packageRoot, taskId, recipientHint, note: handoffNote });
+}
+
+export function formatHandoffCreateResult(result) {
+  return `FORGELOOP HANDOFF CREATED\ntask: ${result.handoff.taskId}\nid: ${result.handoff.handoffId}\ndigest: ${result.handoff.artifactDigest}\npath: ${result.path}\n\n`;
+}

package/src/commands/handoff-list.js

@@ -0,0 +1,12 @@
+import { listCanonicalHandoffs } from "../core/handoff.js";
+
+export async function runHandoffList({ target, packageRoot, taskId } = {}) {
+  const handoffs = await listCanonicalHandoffs(target, { packageRoot, taskId });
+  return { taskId, count: handoffs.length, handoffs };
+}
+
+export function formatHandoffListResult(result) {
+  const lines = [`FORGELOOP HANDOFFS: ${result.count}`];
+  for (const handoff of result.handoffs) lines.push(`${handoff.handoffId} ${handoff.createdAt} ${handoff.artifactDigest}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/handoff-show.js

@@ -0,0 +1,10 @@
+import { readCanonicalHandoff } from "../core/handoff.js";
+
+export async function runHandoffShow({ target, packageRoot, taskId, handoffId } = {}) {
+  const artifact = await readCanonicalHandoff(target, { packageRoot, taskId, handoffId });
+  return { taskId, path: artifact.path, fingerprint: artifact.fingerprint, handoff: artifact.value };
+}
+
+export function formatHandoffShowResult(result) {
+  return `FORGELOOP HANDOFF: VALID\nid: ${result.handoff.handoffId}\ntask: ${result.handoff.taskId}\ndigest: ${result.handoff.artifactDigest}\npath: ${result.path}\n\n`;
+}