@cassiomc1/forgeloop 0.1.0

package/THREAT_MODEL.md

@@ -0,0 +1,35 @@
+# ForgeLoop protocol threat model
+
+**Status:** Implemented boundary inventory; verify target-specific permissions
+and external publication evidence separately.
+
+`ForgeLoop` reads untrusted project files and local protocol artifacts, but it is
+not an agent runtime. It does not execute commands found in those files, call
+an LLM, or publish on behalf of a target. The controls below describe the
+remaining trust boundaries and their executable evidence.
+
+| Threat | Impact | Trust boundary | Mitigation | Residual limitation | Test evidence |
+| --- | --- | --- | --- | --- | --- |
+| Path traversal | Writes or reads outside the selected target | Target path and every managed relative path | `ensureWithin`, safe-path checks, realpath containment, Windows-drive rejection | A separately privileged process can change the filesystem after validation | `tests/core.test.js`, `tests/portability.test.js`, `tests/fixtures/protocol/invalid/path-traversal.json` |
+| Symlink escape | Redirects a managed path to another directory | Existing target parents and artifact paths | Reject symlinked targets, parents, and destinations before access | The check is not a filesystem lock | `tests/core.test.js`, `tests/portability.test.js`, `tests/fixtures/protocol/invalid/symlink-target.json` |
+| Malicious manifest | Causes unsafe update or false ownership claims | `.forgeloop/manifest.json` | Schema, hash, safe-path, and preserve-flag validation; conflicts remain visible | A trusted operator can still deliberately edit the manifest | `tests/cli.test.js`, `tests/core.test.js` |
+| Malicious work-state | Resumes stale, secret-bearing, or invalid work | `.forgeloop/work-state.json` | Schema/semantic checks, version checks, transition checks, contract/HEAD/artifact freshness, secret scan, size/depth bounds | Freshness cannot prove that an external process did not alter a file immediately afterward | `tests/work-state.test.js`, `tests/checkpoint-freshness.test.js`, `tests/security-limits.test.js` |
+| Malicious receipt | Turns local claims into false publication or completion claims | Execution receipt JSON | Semantic evidence checks for completion, checks, review, push, commit, and deployment; explicit publication booleans | Evidence text is declarative and must still be reviewed for provenance | `tests/receipt-semantics.test.js`, `tests/observability.test.js` |
+| Malicious task brief | Grants a child task more authority than intended | Delegation brief JSON and host harness | Relative path boundaries, guide/verification/authority checks, secret-free validation, set validation, parent integration ownership | The host harness remains responsible for OS permissions and execution policy | `tests/delegation.test.js`, `tests/delegation-set.test.js` |
+| Artifact content exposure | Sensitive material enters portable artifacts or diagnostics | State, receipt, delegation, evidence, and repository text | Nested key/value detection, shaped marker patterns, scanner coverage, no content echo in errors | Content scanners cannot prove that an unknown encoding is harmless | `tests/security-limits.test.js`, `tests/test_scan_secrets.py`, `scripts/scan_secrets.py` |
+| Stale checkpoint replay | Repeats work against a changed contract or material file | Resume boundary between a saved state and current target | Contract fingerprint, repository fingerprint, required-artifact hashes, protocol version, and conservative revalidation | A contract author must provide the current contract file for comparison | `tests/checkpoint-freshness.test.js`, `tests/cli.test.js` |
+| Unsafe publication claim | Local output is mistaken for push, PR, merge, or deployment | Receipt publication fields and evidence | Publication starts false; each true claim requires matching evidence; no CLI publication action | Remote provider state is outside local verification | `tests/receipt-semantics.test.js`, `README.md` |
+| Schema confusion | A malformed or altered schema is treated as available | Shipped and target-local `schemas/` directory | Health checks parse every schema and classify valid, missing, invalid, or unsupported-version | Schema health does not replace review of semantic relationships | `tests/schema-health.test.js`, `src/core/schema-validation.js` |
+| Protocol-version confusion | Old/future artifacts are silently reinterpreted | Cross-artifact protocol boundary | Explicit v1 checks and conformance errors for unsupported or mixed versions | A future protocol needs a deliberate migration implementation | `tests/conformance.test.js`, `tests/fixtures/protocol/invalid/` |
+| Dependency-cycle denial of service | Coordination cannot make progress or spends unbounded work | Delegation dependency graph | Deterministic DFS cycle detection, unknown-reference rejection, and bounded JSON | A caller can still submit many valid tasks; host-level quotas remain external | `tests/delegation.test.js`, `tests/delegation-set.test.js` |
+| Oversized JSON artifacts | Excess CPU or memory during validation | Any untrusted JSON artifact | Byte, depth, array, object-key, and string limits before semantic traversal | Limits are conservative defaults, not a complete resource scheduler | `tests/security-limits.test.js`, `src/core/json-safety.js` |
+
+## Boundary rules
+
+- Safe paths are checked before reading or writing; no protocol field is a
+  shell command.
+- A `NOT_VERIFIED` or `BLOCKED` evidence record is never upgraded to observed
+  success by a formatter.
+- Local checks do not imply remote publication, merge, deployment, or provider
+  confirmation.
+- Credentials remain outside Git and outside protocol artifacts.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@cassiomc1/forgeloop",
+  "version": "0.1.0",
+  "description": "Portable, verifiable instruction kit for AI agents and developers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cassiomc1/mdfiles.git"
+  },
+  "homepage": "https://github.com/cassiomc1/mdfiles#readme",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "forgeloop": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "ENG",
+    "schemas",
+    ".forgeloop/.gitignore",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GUIDE_ROUTER.md",
+    "LOOP_ENGINEERING.md",
+    "LOOP_SYSTEM_DESIGN.md",
+    "QUALITY_SCORECARD.md",
+    "TERMINOLOGY.md",
+    "EXECUTION_STATE.md",
+    "DELEGATION_PROTOCOL.md",
+    "ORCHESTRATOR_INTEGRATION.md",
+    "THREAT_MODEL.md",
+    "CONTRACT_COVERAGE.md",
+    "AGENT_COMPATIBILITY.md",
+    "PROJECT_PROFILE.md",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE",
+    "LICENSE-DOCS.md",
+    ".cursor",
+    ".github/copilot-instructions.md",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node scripts/run-tests.js",
+    "pack:check": "node --test tests/package.test.js"
+  }
+}

package/schemas/delegated-result.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/delegated-result.schema.json",
+  "title": "ForgeLoop delegated result",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "status", "changes", "verification", "openFindings", "limitations"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["complete", "blocked", "needs-context", "complete-with-concerns"] },
+    "changes": { "type": "array", "items": { "type": "string" } },
+    "verification": { "type": "array", "items": { "type": "string" } },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "source", "result"],
+        "properties": {
+          "schemaVersion": { "const": 1 },
+          "kind": { "enum": ["OBSERVED", "INFERRED", "NOT_VERIFIED", "BLOCKED"] },
+          "source": { "type": "string", "minLength": 1 },
+          "result": { "type": "string", "minLength": 1 },
+          "details": { "type": "object" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "openFindings": { "type": "array", "items": { "type": "string" } },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": false
+}

package/schemas/evidence.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/evidence.schema.json",
+  "title": "ForgeLoop evidence record",
+  "type": "object",
+  "required": ["schemaVersion", "kind", "source", "result"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "enum": ["OBSERVED", "INFERRED", "NOT_VERIFIED", "BLOCKED"] },
+    "source": { "type": "string", "minLength": 1 },
+    "result": { "type": "string", "minLength": 1 },
+    "details": { "type": "object" }
+  },
+  "additionalProperties": false
+}

package/schemas/execution-receipt.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/execution-receipt.schema.json",
+  "title": "ForgeLoop execution receipt",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "contractFingerprint", "selectedGuides", "changedPaths", "checks", "review", "limitations", "publication"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "status": { "enum": ["in-progress", "complete", "blocked", "complete-with-concerns"] },
+    "selectedGuides": { "type": "array", "items": { "type": "string" } },
+    "changedPaths": { "type": "array", "items": { "type": "string" } },
+    "checks": { "type": "array", "items": { "type": "object" } },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "source", "result"],
+        "properties": {
+          "schemaVersion": { "const": 1 },
+          "kind": { "enum": ["OBSERVED", "INFERRED", "NOT_VERIFIED", "BLOCKED"] },
+          "source": { "type": "string", "minLength": 1 },
+          "result": { "type": "string", "minLength": 1 },
+          "details": { "type": "object" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "review": { "type": "object" },
+    "limitations": { "type": "array", "items": { "type": "string" } },
+    "publication": {
+      "type": "object",
+      "required": ["committed", "pushed", "pullRequest", "deployed"],
+      "properties": {
+        "committed": { "type": "boolean" },
+        "pushed": { "type": "boolean" },
+        "pullRequest": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+        "deployed": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/routing-input.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/routing-input.schema.json",
+  "title": "ForgeLoop routing input",
+  "type": "object",
+  "required": ["schemaVersion", "workType", "surfaces", "risks", "platforms"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "workType": { "type": "string", "minLength": 1 },
+    "surfaces": { "type": "array", "items": { "type": "string" } },
+    "risks": { "type": "array", "items": { "type": "string" } },
+    "platforms": { "type": "array", "items": { "type": "string" } },
+    "behaviorChange": { "type": "boolean" },
+    "executableChange": { "type": "boolean" }
+  },
+  "additionalProperties": false
+}

package/schemas/routing-result.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/routing-result.schema.json",
+  "title": "ForgeLoop routing result",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "input", "primary", "guides", "reasons", "excluded"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "input": { "type": "object" },
+    "primary": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+    "guides": { "type": "array", "items": { "type": "string" } },
+    "reasons": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } },
+    "excluded": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }
+  },
+  "additionalProperties": false
+}

package/schemas/task-brief.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/task-brief.schema.json",
+  "title": "ForgeLoop delegation task brief",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "parentTaskId", "objective", "allowedPaths", "readOnlyPaths", "dependencies", "constraints", "requiredGuides", "verification", "authority", "deliverables"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "parentTaskId": { "type": "string", "minLength": 1 },
+    "objective": { "type": "string", "minLength": 1 },
+    "allowedPaths": { "type": "array", "items": { "type": "string" } },
+    "readOnlyPaths": { "type": "array", "items": { "type": "string" } },
+    "dependencies": { "type": "array", "items": { "type": "string" } },
+    "constraints": { "type": "array", "items": { "type": "string" } },
+    "requiredGuides": { "type": "array", "items": { "type": "string" } },
+    "verification": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "authority": { "type": "array", "items": { "type": "string" } },
+    "deliverables": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "executionMode": { "enum": ["delegated", "inline"] }
+  },
+  "additionalProperties": false
+}

package/schemas/work-state.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/work-state.schema.json",
+  "title": "ForgeLoop work state",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "contractFingerprint", "repositoryFingerprint", "phase", "selectedGuides", "completedSteps", "pendingSteps", "checks", "failures", "blockers", "lastUpdated"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "repositoryFingerprint": {
+      "type": "object",
+      "required": ["branch", "head"],
+      "properties": {
+        "branch": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+        "head": { "oneOf": [{ "type": "string" }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "phase": { "type": "string", "minLength": 1 },
+    "selectedGuides": { "type": "array", "items": { "type": "string" } },
+    "completedSteps": { "type": "array", "items": { "type": "string" } },
+    "pendingSteps": { "type": "array", "items": { "type": "string" } },
+    "requiredArtifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "sha256"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "checks": { "type": "array", "items": { "type": "object" } },
+    "failures": { "type": "array", "items": { "type": "object" } },
+    "blockers": { "type": "array", "items": { "type": "object" } },
+    "lastUpdated": { "type": "string", "minLength": 1 },
+    "previousPhase": { "type": "string" },
+    "diagnosedHypothesis": { "type": "string", "minLength": 1 },
+    "verificationEvidence": { "type": "array", "items": { "type": "object" } }
+  },
+  "additionalProperties": false
+}

package/src/cli.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { runDoctor } from "./commands/doctor.js";
+import { formatStatusResult, runStatus } from "./commands/status.js";
+import { formatValidateStateResult, runValidateState } from "./commands/validate-state.js";
+import { formatClearStateResult, runClearState } from "./commands/clear-state.js";
+import { formatInspectResult, inspectTarget } from "./commands/inspect.js";
+import { runInit } from "./commands/init.js";
+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 { resolveTarget } from "./core/filesystem.js";
+import { getPackageRoot } from "./core/templates.js";
+
+function usage(command = null) {
+  const commands = "init|doctor|update|route|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");
+  }
+  if (!command || command === "doctor") {
+    options.push("  --json              emit doctor findings as JSON");
+    options.push("  --strict            treat warnings as unhealthy");
+    options.push("  --adopt <path>      preserve an existing adapter in the manifest");
+  }
+  if (!command || command === "route") {
+    options.push("  --work <type>       declared work type");
+    options.push("  --surface <value>   affected surface (repeatable)");
+    options.push("  --risk <value>      task risk (repeatable)");
+    options.push("  --platform <value>  affected platform (repeatable)");
+    options.push("  --behavior-change   declare behavior change");
+    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)) {
+    options.push("  --json              emit structured output as JSON");
+  }
+  if (!command || ["status", "inspect", "validate-protocol"].includes(command)) {
+    options.push("  --contract-file <path>  current JSON contract used for freshness comparison");
+  }
+  if (!command || command === "validate-protocol") {
+    options.push("  --route-file <path>  routing-result JSON relative to target");
+    options.push("  --state-file <path>  work-state JSON relative to target");
+    options.push("  --receipt-file <path>  execution-receipt JSON relative to target");
+    options.push("  --task-brief-file <path>  task brief JSON (repeatable)");
+    options.push("  --delegated-result-file <path>  delegated result JSON (repeatable)");
+  }
+  if (!command || command === "validate-receipt") {
+    options.push("  --file <path>       receipt file relative to target");
+  }
+  options.push("  --version           show the installed package version");
+  options.push("  --help              show this help");
+
+  return `Usage: forgeloop <${command ?? commands}> [options]\n\nOptions:\n${options.join("\n")}\n`;
+}
+
+export function parseArgs(argv) {
+  const options = {
+    path: ".",
+    dryRun: false,
+    json: false,
+    strict: false,
+    adopt: [],
+    work: null,
+    surfaces: [],
+    risks: [],
+    platforms: [],
+    behaviorChange: false,
+    executableChange: false,
+    file: null,
+    contractFile: null,
+    routeFile: null,
+    stateFile: null,
+    receiptFile: null,
+    taskBriefFiles: [],
+    delegatedResultFiles: [],
+    help: false,
+    version: false,
+  };
+  let command = null;
+
+  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 (command) throw new Error(`Multiple commands are not supported: ${argument}`);
+      command = argument;
+    } else if (argument === "--help" || argument === "-h") {
+      options.help = true;
+    } else if (argument === "--dry-run") {
+      options.dryRun = true;
+    } else if (argument === "--json") {
+      options.json = true;
+    } else if (argument === "--strict") {
+      options.strict = true;
+    } else if (argument === "--adopt") {
+      const relativePath = argv[index + 1];
+      if (!relativePath || relativePath.startsWith("-")) throw new Error("--adopt requires a path");
+      options.adopt.push(relativePath);
+      index += 1;
+    } else if (argument === "--work") {
+      const workType = argv[index + 1];
+      if (!workType || workType.startsWith("-")) throw new Error("--work requires a type");
+      options.work = workType;
+      index += 1;
+    } else if (argument === "--surface") {
+      const surface = argv[index + 1];
+      if (!surface || surface.startsWith("-")) throw new Error("--surface requires a value");
+      options.surfaces.push(surface);
+      index += 1;
+    } else if (argument === "--risk") {
+      const risk = argv[index + 1];
+      if (!risk || risk.startsWith("-")) throw new Error("--risk requires a value");
+      options.risks.push(risk);
+      index += 1;
+    } else if (argument === "--platform") {
+      const platform = argv[index + 1];
+      if (!platform || platform.startsWith("-")) throw new Error("--platform requires a value");
+      options.platforms.push(platform);
+      index += 1;
+    } else if (argument === "--behavior-change") {
+      options.behaviorChange = true;
+    } else if (argument === "--executable-change") {
+      options.executableChange = true;
+    } else if (argument === "--file") {
+      const file = argv[index + 1];
+      if (!file || file.startsWith("-")) throw new Error("--file requires a path");
+      options.file = file;
+      index += 1;
+    } else if (argument === "--contract-file") {
+      const contractFile = argv[index + 1];
+      if (!contractFile || contractFile.startsWith("-")) throw new Error("--contract-file requires a path");
+      options.contractFile = contractFile;
+      index += 1;
+    } else if (["--route-file", "--state-file", "--receipt-file"].includes(argument)) {
+      const file = argv[index + 1];
+      if (!file || file.startsWith("-")) throw new Error(`${argument} requires a path`);
+      if (argument === "--route-file") options.routeFile = file;
+      if (argument === "--state-file") options.stateFile = file;
+      if (argument === "--receipt-file") options.receiptFile = file;
+      index += 1;
+    } else if (argument === "--task-brief-file") {
+      const file = argv[index + 1];
+      if (!file || file.startsWith("-")) throw new Error("--task-brief-file requires a path");
+      options.taskBriefFiles.push(file);
+      index += 1;
+    } else if (argument === "--delegated-result-file") {
+      const file = argv[index + 1];
+      if (!file || file.startsWith("-")) throw new Error("--delegated-result-file requires a path");
+      options.delegatedResultFiles.push(file);
+      index += 1;
+    } else if (argument === "--path") {
+      options.path = argv[index + 1];
+      if (!options.path || options.path.startsWith("-")) throw new Error("--path requires a directory");
+      index += 1;
+    } else if (argument.startsWith("--path=")) {
+      options.path = argument.slice("--path=".length);
+      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) {
+      command = argument;
+    } else {
+      throw new Error(`Unknown option: ${argument}`);
+    }
+  }
+
+  if (!command) return { command: null, options };
+
+  const jsonCommands = ["doctor", "route", "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}`);
+  }
+  if (![
+    "init",
+    "update",
+  ].includes(command) && options.dryRun) {
+    throw new Error(`Option --dry-run is not valid for ${command}`);
+  }
+  if (command !== "doctor" && options.strict) {
+    throw new Error(`Option --strict is not valid for ${command}`);
+  }
+  if (command !== "doctor" && options.adopt.length > 0) {
+    throw new Error(`Option --adopt is not valid for ${command}`);
+  }
+  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 !== "validate-receipt" && options.file) {
+    throw new Error(`Option --file is not valid for ${command}`);
+  }
+  if (!["status", "inspect", "validate-protocol"].includes(command) && options.contractFile) {
+    throw new Error(`Option --contract-file is not valid for ${command}`);
+  }
+  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}`);
+  }
+  return { command, options };
+}
+
+async function packageVersion(packageRoot) {
+  const packageJson = JSON.parse(
+    await readFile(path.join(packageRoot, "package.json"), "utf8"),
+  );
+  return packageJson.version;
+}
+
+function printActions(actions) {
+  for (const item of actions) {
+    const reason = item.reason ? ` (${item.reason})` : "";
+    console.log(`${item.action.replaceAll("-", " ")}: ${item.path}${reason}`);
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  try {
+    const { command, options } = parseArgs(argv);
+    if (options.version) {
+      console.log(await packageVersion(getPackageRoot()));
+      return 0;
+    }
+    if (!command || options.help) {
+      console.log(usage(command));
+      return options.help ? 0 : 1;
+    }
+
+    const target = await resolveTarget(process.cwd(), options.path);
+    const packageRoot = getPackageRoot();
+    const version = await packageVersion(packageRoot);
+
+    if (command === "init") {
+      const result = await runInit({ target, dryRun: options.dryRun, packageRoot, packageVersion: version });
+      printActions(result.actions);
+      return 0;
+    }
+
+    if (command === "doctor") {
+      const result = await runDoctor({
+        target,
+        packageRoot,
+        adoptPaths: options.adopt,
+        strict: options.strict,
+      });
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        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");
+      }
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === "route") {
+      const result = runRoute({
+        workType: options.work,
+        surfaces: options.surfaces,
+        risks: options.risks,
+        platforms: options.platforms,
+        behaviorChange: options.behaviorChange,
+        executableChange: options.executableChange,
+      });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatRouteResult(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));
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === "validate-receipt") {
+      const result = await runValidateReceipt({ target, packageRoot, file: options.file });
+      console.log(options.json ? JSON.stringify(result, null, 2) : "valid: execution receipt");
+      return 0;
+    }
+
+    if (command === "validate-protocol") {
+      const result = await runValidateProtocol({
+        target,
+        packageRoot,
+        routeFile: options.routeFile,
+        stateFile: options.stateFile,
+        receiptFile: options.receiptFile,
+        contractFile: options.contractFile,
+        taskBriefFiles: options.taskBriefFiles,
+        delegatedResultFiles: options.delegatedResultFiles,
+      });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatValidateProtocolResult(result));
+      return result.status === "VALID" ? 0 : 1;
+    }
+
+    if (command === "status") {
+      const result = await runStatus({ target, packageRoot, contractFile: options.contractFile });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatStatusResult(result));
+      return 0;
+    }
+
+    if (command === "validate-state") {
+      const result = await runValidateState({ target, packageRoot });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatValidateStateResult(result));
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === "clear-state") {
+      const result = await runClearState({ target });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatClearStateResult(result));
+      return 0;
+    }
+
+    const result = await runUpdate({ target, dryRun: options.dryRun, packageRoot, packageVersion: version });
+    printActions(result.actions);
+    for (const conflict of result.conflicts) {
+      console.log(`conflict: ${conflict.path} - ${conflict.message}`);
+    }
+    return result.conflicts.length === 0 ? 0 : 1;
+  } catch (error) {
+    console.error(`error: ${error.message}`);
+    return 1;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  const exitCode = await main();
+  process.exitCode = exitCode;
+}

package/src/commands/clear-state.js

@@ -0,0 +1,11 @@
+import { clearWorkState } from "../core/work-state.js";
+
+export { clearWorkState };
+
+export async function runClearState({ target }) {
+  return clearWorkState(target);
+}
+
+export function formatClearStateResult(result) {
+  return `${result.removed ? "removed" : "absent"}: ${result.path}\n`;
+}