@cassiomc1/forgeloop 1.2.4 → 1.5.0

package/src/core/integration-invocation-policy.js

@@ -0,0 +1,170 @@
+import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
+import { COMMAND_EXECUTORS } from "./command-executors.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { FORGELOOP_INTEGRATION_RUNTIME_VERSION } from "./command-runtime.js";
+
+/**
+ * Integration risk classes. They classify the *invocation*, not only the
+ * command name: input-dependent commands (doctor --fix, task-unlock --force,
+ * policy-discover --write, baseline mutations) are refined by the sparse
+ * override table below.
+ */
+export const INTEGRATION_RISK_CLASSES = Object.freeze({
+  READ_ONLY: "READ_ONLY",
+  LOOP_MUTATION: "LOOP_MUTATION",
+  CLAIM_REACQUISITION: "CLAIM_REACQUISITION",
+  EXTERNAL_EXECUTION: "EXTERNAL_EXECUTION",
+  MAINTENANCE: "MAINTENANCE",
+  CLAIM_RELEASE_RECOVERY: "CLAIM_RELEASE_RECOVERY",
+  LEGACY_MIGRATION: "LEGACY_MIGRATION",
+  FORCE_DESTRUCTIVE: "FORCE_DESTRUCTIVE",
+});
+
+const READ_ONLY_COMMANDS = Object.freeze(new Set([
+  "protocol-info", "status", "next", "continuity", "reconcile-continuity",
+  "task-list", "task-show", "task-lock-status", "progress", "audit", "report",
+  "inspect", "validate-state", "validate-protocol", "validate-receipt",
+  "policy-status", "policy-diff", "rule-verify", "policy",
+]));
+
+const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
+  "route", "preflight", "advance", "task-create", "task-scope",
+  "record-continuity", "clear-continuity", "prepare-completion",
+  "record-check", "record-diagnosis", "record-decision-criterion",
+  "record-terminal-result", "complete",
+]));
+
+const STATIC_RISK_CLASSES = Object.freeze({
+  ...Object.fromEntries([...READ_ONLY_COMMANDS].map((name) => [name, INTEGRATION_RISK_CLASSES.READ_ONLY])),
+  ...Object.fromEntries([...LOOP_MUTATION_COMMANDS].map((name) => [name, INTEGRATION_RISK_CLASSES.LOOP_MUTATION])),
+  "task-resume": INTEGRATION_RISK_CLASSES.CLAIM_REACQUISITION,
+  "run-check": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+  "reconcile-closure": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+  init: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  update: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  activate: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "task-migrate": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "migrate-protocol": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "clear-state": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  doctor: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "policy-discover": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  baseline: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "task-unlock": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  // bundle writes a bundle artifact set under the task namespace; it is not
+  // read-only despite producing no protocol-state mutations.
+  bundle: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "profile-interview": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "task-recover": INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY,
+  "task-repair-legacy-recovery": INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION,
+});
+
+// Sparse input-dependent refinements over the static table.
+function refineRiskClass(command, input) {
+  if (command === "task-unlock" && input?.force === true) {
+    return INTEGRATION_RISK_CLASSES.FORCE_DESTRUCTIVE;
+  }
+  // Fail closed: every canonical command must be explicitly classified.
+  return baseRiskClass(command);
+}
+
+export function baseRiskClass(command) {
+  const riskClass = STATIC_RISK_CLASSES[command];
+  if (!riskClass) {
+    throw new Error(`Command ${command} has no integration risk classification`);
+  }
+  return riskClass;
+}
+
+export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
+  const commands = Object.keys(CLI_COMMAND_DEFINITIONS).sort().map((name) => {
+    const def = CLI_COMMAND_DEFINITIONS[name];
+    return {
+      name,
+      category: def.category,
+      mutation: def.mutation,
+      baseRiskClass: baseRiskClass(name),
+      mayExecuteExternalProcess: def.mayExecuteExternalProcess === true,
+      description: def.description,
+    };
+  });
+  return {
+    packageVersion,
+    protocolVersion: PROTOCOL_VERSION,
+    integrationApiVersion: FORGELOOP_INTEGRATION_RUNTIME_VERSION,
+    executorParity: Object.keys(COMMAND_EXECUTORS).length === Object.keys(CLI_COMMAND_DEFINITIONS).length,
+    features: {
+      taskClaimRecovery: {
+        version: 1,
+        durableRecoveryState: true,
+        explicitResume: true,
+        validatedClaimProjection: true,
+      },
+    },
+    commands,
+    resources: [
+      { name: "protocol/info", scope: "PROJECT" },
+      { name: "project/tasks", scope: "PROJECT" },
+      { name: "task/status", scope: "TASK" },
+      { name: "task/ownership", scope: "TASK" },
+      { name: "task/contract", scope: "TASK" },
+      { name: "task/continuity", scope: "TASK" },
+    ],
+  };
+}
+
+/**
+ * Classify a concrete command invocation (command + structured input).
+ * Tool-provided input can never elevate a launch-level capability; this
+ * classifier only describes what the invocation would do.
+ */
+export function classifyForgeLoopInvocation(command, input = {}) {
+  const definition = CLI_COMMAND_DEFINITIONS[command];
+  if (!definition) {
+    throw new Error(`Unknown ForgeLoop command: ${command}`);
+  }
+  const riskClass = refineRiskClass(command, input);
+  const readOnly = riskClass === INTEGRATION_RISK_CLASSES.READ_ONLY;
+  const requiredCapability = (() => {
+    switch (riskClass) {
+      case INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION:
+        return "allowExternalExecution";
+      case INTEGRATION_RISK_CLASSES.MAINTENANCE:
+        return "allowMaintenance";
+      case INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY:
+        return "allowRecovery";
+      case INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION:
+        return "allowLegacyRepair";
+      case INTEGRATION_RISK_CLASSES.FORCE_DESTRUCTIVE:
+        return "allowForceRecovery";
+      default:
+        return null;
+    }
+  })();
+  return Object.freeze({
+    command,
+    riskClass,
+    readOnly,
+    mutatesProtocol: !readOnly && [
+      INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
+      INTEGRATION_RISK_CLASSES.CLAIM_REACQUISITION,
+      INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+      INTEGRATION_RISK_CLASSES.MAINTENANCE,
+      INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY,
+      INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION,
+      INTEGRATION_RISK_CLASSES.FORCE_DESTRUCTIVE,
+    ].includes(riskClass),
+    removesArtifacts: definition.removes.length > 0,
+    executesExternalProcess: definition.mayExecuteExternalProcess === true,
+    affectsClaimAuthority: [
+      "task-resume", "task-recover", "task-repair-legacy-recovery",
+      "task-create", "task-scope", "complete",
+    ].includes(command),
+    destructive: [
+      INTEGRATION_RISK_CLASSES.FORCE_DESTRUCTIVE,
+      INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY,
+      INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION,
+      INTEGRATION_RISK_CLASSES.MAINTENANCE,
+    ].includes(riskClass),
+    requiredCapability,
+  });
+}

package/src/core/integration-limits.js

@@ -0,0 +1,20 @@
+/**
+ * Bounded input limits for structured integrations. These bound the
+ * transport-facing surface; canonical ForgeLoop JSON safety limits remain
+ * authoritative for persisted artifacts. Values are conservative and
+ * intentionally small for an agent-facing API.
+ */
+export const INTEGRATION_LIMITS = Object.freeze({
+  /** Maximum length of any single string input (task IDs, names, text). */
+  maxStringLength: 4096,
+  /** Maximum number of entries in a repeatable string option. */
+  maxRepeatedValues: 32,
+  /** Maximum number of exact argv items passed to external execution. */
+  maxArgvItems: 64,
+  /** Maximum length of a single argv item. */
+  maxArgvItemLength: 2048,
+  /** Maximum serialized size of a JSON-object input field. */
+  maxStructuredInputBytes: 256 * 1024,
+  /** Maximum serialized size of any tool/resource response payload. */
+  maxOutputBytes: 4 * 1024 * 1024,
+});

package/src/core/integration-resources.js

@@ -0,0 +1,127 @@
+import { runProtocolInfo } from "../commands/protocol-info.js";
+import { readContract } from "./contract.js";
+import { discoverTasks } from "./task-discovery.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
+import { runStatus } from "../commands/status.js";
+import { runContinuity } from "../commands/continuity.js";
+
+/**
+ * Canonical integration resource allowlist.
+ *
+ * This is NOT a replacement for ARTIFACT_REGISTRY: the artifact registry
+ * describes persisted protocol artifacts; this registry describes what is
+ * safe to expose through structured integrations. Anything not listed here
+ * must never be readable through an integration transport.
+ *
+ * task/ownership is derived exclusively from resolveTaskClaimState() — the
+ * canonical claim resolver. Integrations must present these values; they
+ * must never derive them from raw artifacts such as task.json or
+ * recovery.json.
+ */
+export const INTEGRATION_RESOURCE_DEFINITIONS = Object.freeze({
+  "protocol/info": Object.freeze({
+    scope: "PROJECT",
+    description: "ForgeLoop protocol version, schema compatibility, features, and command metadata.",
+  }),
+  "project/tasks": Object.freeze({
+    scope: "PROJECT",
+    description: "All discovered tasks with canonical ownership projection fields.",
+  }),
+  "task/status": Object.freeze({
+    scope: "TASK",
+    description: "Canonical status projection for one task, including ownership fields.",
+  }),
+  "task/ownership": Object.freeze({
+    scope: "TASK",
+    description: "Canonical validated claim ownership for one task.",
+  }),
+  "task/contract": Object.freeze({
+    scope: "TASK",
+    description: "The task's current contract.",
+  }),
+  "task/continuity": Object.freeze({
+    scope: "TASK",
+    description: "Cross-harness continuity state for one task.",
+  }),
+});
+
+function ownershipProjection(projection) {
+  return {
+    taskId: projection.taskId,
+    phase: projection.phase,
+    claimState: projection.claimState,
+    mutationAllowed: projection.mutationAllowed,
+    ownershipValid: projection.ownershipValid,
+    recoveryStatus: projection.recoveryStatus,
+    historicalWriteClaims: [...projection.historicalWriteClaims],
+    effectiveWriteClaims: [...projection.effectiveWriteClaims],
+    reasonCodes: [...projection.reasonCodes],
+  };
+}
+
+export async function readForgeLoopIntegrationResource(uri, {
+  projectPath = ".",
+  packageRoot = undefined,
+  packageVersion = null,
+  taskId = null,
+} = {}) {
+  const resource = INTEGRATION_RESOURCE_DEFINITIONS[uri];
+  if (!resource) {
+    const error = new Error(`Unknown ForgeLoop integration resource: ${uri}`);
+    error.code = "E_INTEGRATION_RESOURCE_UNKNOWN";
+    throw error;
+  }
+
+  switch (uri) {
+    case "protocol/info": {
+      return { uri, data: await runProtocolInfo({ packageVersion }) };
+    }
+    case "project/tasks": {
+      const tasks = await discoverTasks(projectPath, packageRoot);
+      return {
+        uri,
+        data: {
+          count: tasks.length,
+          tasks: tasks.map((task) => ({
+            taskId: task.taskId,
+            healthy: task.healthy !== false,
+            phase: task.phase ?? null,
+            mutationAllowed: task.mutationAllowed !== false,
+          })),
+        },
+      };
+    }
+    case "task/status":
+    case "task/ownership":
+    case "task/contract":
+    case "task/continuity": {
+      if (typeof taskId !== "string" || !taskId) {
+        const error = new Error(`Resource ${uri} requires a taskId`);
+        error.code = "E_TASK_REQUIRED";
+        throw error;
+      }
+      break;
+    }
+  }
+
+  if (uri === "task/ownership") {
+    const projection = await resolveTaskClaimState(projectPath, { taskId, packageRoot });
+    return { uri, taskId, data: ownershipProjection(projection) };
+  }
+  if (uri === "task/status") {
+    const result = await runStatus({ target: projectPath, packageRoot, taskId });
+    return { uri, taskId, data: result };
+  }
+  if (uri === "task/contract") {
+    try {
+      const contract = await readContract(projectPath, packageRoot, { taskId });
+      return { uri, taskId, data: contract.value };
+    } catch (error) {
+      error.message = `Resource task/contract unavailable: ${error.message}`;
+      throw error;
+    }
+  }
+  // task/continuity
+  const continuity = await runContinuity({ target: projectPath, packageRoot, taskId });
+  return { uri, taskId, data: continuity };
+}

package/src/core/next-action-model.js

@@ -31,9 +31,69 @@ export const NEXT_ACTIONS = Object.freeze({
   REPAIR_POLICY: "REPAIR_POLICY",
   RESTORE_BASELINE: "RESTORE_BASELINE",
   CONTINUE_WITH_EXISTING_BASELINE: "CONTINUE_WITH_EXISTING_BASELINE",
+  RECONCILE_CLOSURE: "RECONCILE_CLOSURE",
+  RECOVER_TASK: "RECOVER_TASK",
+  RESUME_RECOVERED_TASK: "RESUME_RECOVERED_TASK",
+  RESOLVE_RECOVERY_INCONSISTENCY: "RESOLVE_RECOVERY_INCONSISTENCY",
   NONE: "NONE",
 });
 
+function directCommandSpec(commandId, taskId, requiredInputs = []) {
+  return {
+    commandId,
+    executable: "forgeloop",
+    subcommand: commandId,
+    argv: [commandId, `--task=${taskId}`, "--json"],
+    requiredInputs,
+  };
+}
+
+export function recoveryGuidanceForClassification(classification, taskId) {
+  if (classification === "RECOVERABLE") {
+    return {
+      nextAction: NEXT_ACTIONS.RECONCILE_CLOSURE,
+      commands: ["forgeloop reconcile-closure --task <id>"],
+      commandSpecs: [directCommandSpec("reconcile-closure", taskId, [
+        { name: "checkId", option: "--id=<contract-verification-id>" },
+        { name: "requirement", option: "--requirement=<exact-contract-verification-text>" },
+        { name: "command", option: "-- <verification-command...>" },
+      ])],
+    };
+  }
+  if (classification === "STALE" || classification === "ABANDONED") {
+    return {
+      nextAction: NEXT_ACTIONS.RECOVER_TASK,
+      commands: ["forgeloop task-recover --task <id> --acknowledge-recovery --json"],
+      commandSpecs: [directCommandSpec("task-recover", taskId, [
+        {
+          name: "acknowledgeRecovery",
+          option: "--acknowledge-recovery",
+          description: "Caller acknowledgement only; not host-attested authority.",
+        },
+      ])],
+    };
+  }
+  if (classification === "RECOVERED") {
+    return {
+      nextAction: NEXT_ACTIONS.RESUME_RECOVERED_TASK,
+      commands: ["forgeloop task-resume --task <id> --json"],
+      commandSpecs: [directCommandSpec("task-resume", taskId)],
+    };
+  }
+  if (classification === "INCONSISTENT") {
+    return {
+      nextAction: NEXT_ACTIONS.RESOLVE_RECOVERY_INCONSISTENCY,
+      commands: ["forgeloop validate-protocol --task <id> --json"],
+      commandSpecs: [directCommandSpec("validate-protocol", taskId)],
+    };
+  }
+  return {
+    nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+    commands: ["forgeloop task-show --task <id> --json"],
+    commandSpecs: [directCommandSpec("task-show", taskId)],
+  };
+}
+
 export function result({
   taskId = "unknown",
   currentPhase = "RECEIVED",

package/src/core/next-action.js

@@ -20,6 +20,7 @@ import {
   recordCheckCommandSpec,
   recordDiagnosisCommandSpec,
   recordTerminalResultCommandSpec,
+  recoveryGuidanceForClassification,
   result,
   uniqueSorted,
 } from "./next-action-model.js";
@@ -37,6 +38,7 @@ import { currentCycleDiagnosis } from "./diagnosis-model.js";
 import { evaluateProgress, PROGRESS_STATUS } from "./progress.js";
 import { criterionForDecision } from "./settlement-model.js";
 import { readEvents } from "./events.js";
+import { inspectTaskConflictState } from "./task-conflict-inspection.js";
 
 export { NEXT_ACTIONS } from "./next-action-model.js";
 
@@ -145,6 +147,35 @@ async function computeNextAction(targetOrOptions = {}, packageRootOption) {
 
   const state = workState.value;
   const context = { taskId: state.taskId, currentPhase: state.phase };
+  if (explicitTaskId) {
+    let inspection;
+    try {
+      inspection = await inspectTaskConflictState(target, {
+        taskId: explicitTaskId,
+        packageRoot,
+      });
+    } catch (error) {
+      inspection = {
+        classification: "INCONSISTENT",
+        reasonCodes: [error.code ?? "E_TASK_RECOVERY_INCONSISTENT"],
+      };
+    }
+    if (!["ACTIVE", "COMPLETE"].includes(inspection.classification)) {
+      const guidance = recoveryGuidanceForClassification(inspection.classification, explicitTaskId);
+      return result({
+        ...context,
+        nextAction: guidance.nextAction,
+        commands: guidance.commands,
+        commandSpecs: guidance.commandSpecs,
+        reasons: inspection.reasonCodes.map((code) => artifactError(
+          code,
+          `Task conflict state is ${inspection.classification}; follow the structured recovery guidance.`,
+          [stateRel, eventsRel, taskArtifactPath(explicitTaskId, "recovery")],
+        )),
+        requiredArtifacts: [stateRel, eventsRel],
+      });
+    }
+  }
   if (state.phase === "RECEIVED") {
     return decision(
       context,

package/src/core/phase.js

@@ -9,7 +9,7 @@ import {
 } from "./events.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { assertWorkPhase, isValidTransition } from "./protocol.js";
-import { readWorkState, writeWorkState } from "./work-state.js";
+import { readWorkState, mutateWorkState } from "./work-state.js";
 import { evaluateCompletion } from "./completion.js";
 import { evaluatePreflight } from "./preflight.js";
 import { requiredEvidenceForTarget } from "./completion-artifacts.js";
@@ -187,7 +187,8 @@ export async function advanceWorkState(target, toPhase, options = {}) {
 
     const nonCompleteTasks = discovered.filter((t) => t.phase !== "COMPLETE");
     if (nonCompleteTasks.length > 1) {
-      const claims = descriptor?.writeClaims ?? [];
+      const currentTask = discovered.find((task) => task.taskId === taskId && task.healthy !== false);
+      const claims = currentTask?.writeClaims ?? [];
       if (claims.length === 0) {
         throw phaseError(
           E_TASK_SCOPE_REQUIRED,
@@ -304,6 +305,7 @@ export async function advanceWorkState(target, toPhase, options = {}) {
     next.verificationCycle = reenteringVerification ? (state.verificationCycle ?? 1) + 1 : (state.verificationCycle ?? 1);
   }
   if (reenteringVerification) delete next.lastCompletionAttempt;
+  next.revision = (state.revision ?? 0) + 1;
   let nextReceipt = null;
   try {
     const receipt = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
@@ -361,7 +363,12 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   } catch (error) {
     if (error.code !== "ARTIFACT_MISSING") throw error;
   }
-  await writeWorkState(target, next, { packageRoot, taskId, statePath });
+  await mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath,
+  }, () => next);
   if (nextReceipt) {
     await writeJsonArtifact(target, receiptRel, nextReceipt, "execution-receipt", packageRoot);
   }

package/src/core/project-root.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+
+import { resolveTarget } from "./filesystem.js";
+
+/**
+ * Canonical project-root resolution for integrations. Applies exactly the
+ * same semantics as the CLI target resolver — the path must exist, must be a
+ * real directory (not a symlink), and is returned as an absolute path.
+ *
+ * Symlinked roots are rejected so that every transport agrees on whether a
+ * given project path is acceptable; use the resolved real directory instead.
+ */
+export async function resolveForgeLoopProjectRoot(projectPath, { cwd = process.cwd() } = {}) {
+  const target = await resolveTarget(cwd, projectPath);
+  return realpath(target);
+}
+
+export function defaultIntegrationProjectPath() {
+  return path.resolve(".");
+}

package/src/core/protocol-info.js

@@ -0,0 +1,54 @@
+import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
+import { ARTIFACT_REGISTRY } from "./artifact-registry.js";
+import { PUBLIC_ERROR_REGISTRY } from "./error-codes.js";
+import { GUIDE_REGISTRY } from "./guide-registry.js";
+import { PROTOCOL_VERSION, WORK_PHASES, WORK_TRANSITIONS } from "./protocol.js";
+
+export const SCHEMA_COMPATIBILITY_POLICY = Object.freeze({
+  protocolVersion: PROTOCOL_VERSION,
+  schemaVersion: 1,
+  read: "Readers reject unknown protocol or schema versions; compatibility changes require a new published version.",
+  write: "Writers emit only the current schema and protocol versions.",
+  migration: "Use migrate-protocol --to <version> --dry-run to plan an explicit supported migration. Legacy singleton artifacts are migrated with a receipt-backed task-migrate action.",
+});
+
+function publicSchemaVersions() {
+  return Object.fromEntries(
+    [...new Set(Object.values(ARTIFACT_REGISTRY)
+      .filter((artifact) => artifact.isPublic && artifact.isPersisted)
+      .map((artifact) => artifact.schema))]
+      .sort()
+      .map((schema) => [schema, [SCHEMA_COMPATIBILITY_POLICY.schemaVersion]]),
+  );
+}
+
+export function protocolInfo({ packageVersion = null } = {}) {
+  const errors = Object.values(PUBLIC_ERROR_REGISTRY);
+  const schemaVersions = publicSchemaVersions();
+  return {
+    packageVersion,
+    protocolVersion: PROTOCOL_VERSION,
+    readsProtocol: [PROTOCOL_VERSION],
+    writesProtocol: [PROTOCOL_VERSION],
+    readsSchemaVersions: schemaVersions,
+    writesSchemaVersions: schemaVersions,
+    compatibility: SCHEMA_COMPATIBILITY_POLICY,
+    features: {
+      taskClaimRecovery: {
+        version: 1,
+        durableRecoveryState: true,
+        explicitResume: true,
+        validatedClaimProjection: true,
+      },
+      integrationApi: {
+        version: 1,
+        structuredCommandRuntime: true,
+        canonicalResources: true,
+      },
+    },
+    lifecycle: { phases: WORK_PHASES, transitions: WORK_TRANSITIONS },
+    guides: Object.values(GUIDE_REGISTRY),
+    commands: Object.values(CLI_COMMAND_DEFINITIONS).map(({ name, category, mutation, description }) => ({ name, category, mutation, description })),
+    errors,
+  };
+}

package/src/core/protocol-migration.js

@@ -0,0 +1,59 @@
+import { E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED } from "./error-codes.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { detectLegacySingletonLayout, migrateLegacyLayout } from "./task-migration.js";
+import { getPackageRoot } from "./templates.js";
+
+function assertSupportedTarget(to) {
+  if (to === undefined || to === null || to === "") {
+    const error = new Error("migrate-protocol requires --to <protocolVersion>");
+    error.code = E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED;
+    throw error;
+  }
+
+  if (String(to) !== String(PROTOCOL_VERSION)) {
+    const error = new Error(
+      `Protocol version ${to} is not supported by this ForgeLoop release; supported target: ${PROTOCOL_VERSION}.`,
+    );
+    error.code = E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED;
+    throw error;
+  }
+}
+
+/**
+ * Migrates only state that has an explicitly supported, receipt-backed path.
+ * Future protocol versions must add a dedicated migration before becoming an
+ * accepted target here; accepting an unknown target would risk silent rewrite.
+ */
+export async function migrateProtocol(
+  target,
+  { to, dryRun = false, packageRoot = getPackageRoot() } = {},
+) {
+  assertSupportedTarget(to);
+  const legacy = await detectLegacySingletonLayout(target);
+
+  if (!legacy.hasLegacy) {
+    return {
+      migrated: false,
+      dryRun,
+      fromProtocol: PROTOCOL_VERSION,
+      toProtocol: PROTOCOL_VERSION,
+      status: "ALREADY_COMPATIBLE",
+      actions: [],
+      message: `Target already uses supported protocol ${PROTOCOL_VERSION}; no migration is required.`,
+    };
+  }
+
+  const result = await migrateLegacyLayout(target, { dryRun, packageRoot });
+  return {
+    ...result,
+    fromProtocol: PROTOCOL_VERSION,
+    toProtocol: PROTOCOL_VERSION,
+    status: dryRun ? "PLANNED_LEGACY_LAYOUT_MIGRATION" : "MIGRATED_LEGACY_LAYOUT",
+    actions: [{
+      kind: "LEGACY_LAYOUT_MIGRATION",
+      command: "task-migrate",
+      receipt: ".forgeloop/task-state/<taskKey>/migration-receipt.json",
+      artifacts: legacy.legacyFiles.map((item) => item.path),
+    }],
+  };
+}