@cassiomc1/forgeloop 1.3.0 → 1.5.0

package/src/commands/task-show.js

@@ -1,4 +1,4 @@
-import { resolveTaskContext } from "../core/task-context.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
 import { readTaskDescriptor } from "../core/task-descriptor.js";
 import { classifyLockStaleness, readLockInfo } from "../core/task-lock.js";
 import { taskDirectory, taskArtifactPath } from "../core/task-paths.js";
@@ -6,6 +6,7 @@ import { readWorkState } from "../core/work-state.js";
 import { readContract } from "../core/contract.js";
 import { fileExists, ensureWithin } from "../core/filesystem.js";
 import { E_TASK_NOT_FOUND } from "../core/error-codes.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
 
 function taskError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -15,7 +16,7 @@ function taskError(code, message, artifacts = []) {
 }
 
 export async function runTaskShow({ target, packageRoot, taskId } = {}) {
-  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true, selectionMode: TASK_SELECTION_MODES.READ });
   const effectiveTaskId = context.taskId;
 
   let descriptor = null;
@@ -30,6 +31,13 @@ export async function runTaskShow({ target, packageRoot, taskId } = {}) {
   }
 
   const state = await readWorkState(target, { packageRoot, taskId: effectiveTaskId });
+  const claimProjection = await resolveTaskClaimState(target, {
+    taskId: effectiveTaskId,
+    packageRoot,
+    descriptor,
+    state,
+  });
+  const recovery = claimProjection.recovery;
   let contract = null;
   try {
     const contractArtifact = await readContract(target, packageRoot, { taskId: effectiveTaskId });
@@ -40,7 +48,7 @@ export async function runTaskShow({ target, packageRoot, taskId } = {}) {
 
   const lockInfo = await readLockInfo(target, effectiveTaskId);
   const artifacts = {};
-  for (const name of ["contract", "route", "state", "preflight", "receipt", "continuity", "events"]) {
+  for (const name of ["contract", "route", "state", "preflight", "receipt", "continuity", "events", "recovery"]) {
     const rel = taskArtifactPath(effectiveTaskId, name);
     artifacts[name] = {
       path: rel,
@@ -53,7 +61,8 @@ export async function runTaskShow({ target, packageRoot, taskId } = {}) {
     taskKey: context.taskKey,
     directory: taskDirectory(effectiveTaskId),
     phase: state?.phase ?? "UNINITIALIZED",
-    writeClaims: descriptor.writeClaims ?? [],
+    ...claimProjection,
+    recovery,
     lock: lockInfo ? { ...lockInfo, classification: classifyLockStaleness(lockInfo) } : null,
     contract: contract ? { title: contract.title ?? null, taskType: contract.taskType ?? null } : null,
     artifacts,
@@ -73,6 +82,11 @@ export function formatTaskShowResult(result) {
     `Directory: ${result.directory}`,
     `Phase: ${result.phase}`,
     `Write Claims: ${claims}`,
+    `Claim State: ${result.claimState}`,
+    `Mutation Allowed: ${result.mutationAllowed ? "yes" : "no"}`,
+    ...(result.recovery
+      ? [`Recovery: ${result.recovery.recoveryId} at ${result.recovery.recoveredAt}`]
+      : []),
     `Lock: ${lockStatus}`,
     `Created: ${result.createdAt}`,
     `Updated: ${result.updatedAt}`,

package/src/commands/validate-protocol.js

@@ -12,6 +12,7 @@ import { validateEventLedger, validateStateLedgerCoherence } from "../core/event
 import { validateChecksExecutionProvenance } from "../core/completion-artifacts.js";
 import { assertContinuitySemantics } from "../core/continuity.js";
 import { currentChangedPaths, currentRepositoryFingerprint } from "../core/repository.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
 
 async function readArtifact(target, relativePath, label) {
   if (!relativePath) return null;
@@ -164,6 +165,22 @@ export async function runValidateProtocol({
       })),
     ];
   }
+  const recoveryErrors = [];
+  if (effectiveTaskId) {
+    try {
+      const claimProjection = await resolveTaskClaimState(target, { taskId: effectiveTaskId, packageRoot });
+      recoveryErrors.push(...(claimProjection.ownershipErrors ?? []).map((error) => ({
+        ...error,
+        artifacts: [taskArtifactPath(effectiveTaskId, "recovery"), effectiveEventsFile],
+      })));
+    } catch (error) {
+      recoveryErrors.push({
+        code: "E_TASK_RECOVERY_INCONSISTENT",
+        message: `Recovery state is unreadable: ${error.message}`,
+        artifacts: [taskArtifactPath(effectiveTaskId, "recovery")],
+      });
+    }
+  }
   const continuityContext = continuity && state && !stateValidationError
     ? {
       contractFingerprint: state.contractFingerprint,
@@ -182,11 +199,11 @@ export async function runValidateProtocol({
     delegatedResults,
     events: ledgerEvents,
   });
-    if (readErrors.length > 0 || schemaErrors.length > 0 || readyConsistencyErrors.length > 0 || ledgerErrors.length > 0) {
+    if (readErrors.length > 0 || schemaErrors.length > 0 || readyConsistencyErrors.length > 0 || ledgerErrors.length > 0 || recoveryErrors.length > 0) {
       return {
         ...result,
         status: "INVALID",
-        errors: [...result.errors, ...readErrors, ...schemaErrors, ...readyConsistencyErrors, ...ledgerErrors]
+        errors: [...result.errors, ...readErrors, ...schemaErrors, ...readyConsistencyErrors, ...ledgerErrors, ...recoveryErrors]
           .sort((left, right) => left.code.localeCompare(right.code) || left.message.localeCompare(right.message)),
       };
     }

package/src/core/artifact-registry.js

@@ -223,4 +223,16 @@ export const ARTIFACT_REGISTRY = Object.freeze({
     isPersisted: true,
     description: "Task-scoped policy snapshot binding task activation to effective policy digest.",
   }),
+  recovery: Object.freeze({
+    key: "recovery",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.recovery}`,
+    schema: "task-recovery",
+    owner: "PROTOCOL_GENERATED",
+    mutability: "RECOVERY_STATE_TRANSITIONS",
+    trustRole: "TASK_RECOVERY_STATE",
+    isPublic: true,
+    isPersisted: true,
+    description: "Durable task recovery state recording claim release and explicit resume requirements.",
+  }),
 });

package/src/core/audit.js

@@ -6,7 +6,7 @@ import { readJsonArtifact } from "./artifacts.js";
 import { currentChangedPaths } from "./repository.js";
 import { validateReadyProtocolConsistency } from "./preflight.js";
 import { taskArtifactPath } from "./task-paths.js";
-import { readTaskDescriptor } from "./task-descriptor.js";
+import { findTaskById } from "./task-discovery.js";
 
 function sortErrors(errors) {
   return [...errors].sort((left, right) => left.code.localeCompare(right.code)
@@ -25,8 +25,8 @@ async function compareChangedPaths(target, packageRoot, options = {}) {
   let writeClaims = [];
   if (options.taskId) {
     try {
-      const desc = await readTaskDescriptor(target, options.taskId, packageRoot);
-      writeClaims = desc.value.writeClaims ?? [];
+      const task = await findTaskById(target, options.taskId, packageRoot);
+      writeClaims = task?.writeClaims ?? [];
     } catch {
       // ignore
     }
@@ -110,7 +110,14 @@ export async function evaluateAudit({
   } catch {
     // Completion already reports missing or invalid preflight artifacts.
   }
-  const errors = sortErrors([...completion.errors, ...readyConsistencyErrors]);
+  const taskInfo = taskId ? await findTaskById(target, taskId, packageRoot) : null;
+  const ownershipErrors = taskInfo?.ownershipValid === false
+    ? (taskInfo.ownershipErrors ?? taskInfo.errors ?? []).map((error) => ({
+      ...error,
+      artifacts: error.artifacts ?? [taskArtifactPath(taskId, "recovery"), taskArtifactPath(taskId, "events")],
+    }))
+    : [];
+  const errors = sortErrors([...completion.errors, ...readyConsistencyErrors, ...ownershipErrors]);
   const changedPaths = await compareChangedPaths(target, packageRoot, { taskId, receiptPath });
   if (changedPaths.status === "MISMATCH") {
     errors.push({
@@ -167,6 +174,15 @@ export async function evaluateAudit({
     },
     policy: policyStatus,
     completion,
+    recovery: taskInfo?.recovery ?? null,
+    claims: taskInfo ? {
+      state: taskInfo.claimState,
+      historical: taskInfo.historicalWriteClaims,
+      effective: taskInfo.effectiveWriteClaims,
+      mutationAllowed: taskInfo.mutationAllowed,
+      ownershipValid: taskInfo.ownershipValid,
+      ownershipErrors: taskInfo.ownershipErrors ?? taskInfo.errors ?? [],
+    } : null,
     changedPaths,
     publicationStatus: completion.publicationStatus,
     productionReadiness: completion.productionReadiness,

package/src/core/bundles.js

@@ -8,6 +8,8 @@ import { validateChecksExecutionProvenance } from "./completion-artifacts.js";
 import { readExecutionArtifact } from "./execution.js";
 import { assertContinuitySemantics } from "./continuity.js";
 import { taskArtifactPath, taskDirectory } from "./task-paths.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
+import { E_TASK_CLAIM_OWNERSHIP_INCONSISTENT } from "./error-codes.js";
 
 export const BUNDLE_SCHEMA_VERSION = 1;
 const BUNDLE_ROOT = ".forgeloop/tasks";
@@ -53,6 +55,17 @@ export async function exportTaskBundle(target, taskId, packageRoot) {
   const directory = bundleDirectory(taskId);
   const artifacts = [];
 
+  if (await fileExists(ensureWithin(target, taskArtifactPath(taskId, "descriptor")))) {
+    const claimProjection = await resolveTaskClaimState(target, { taskId, packageRoot });
+    if (!claimProjection.valid) {
+      const error = new Error(`Task ${taskId} claim ownership is inconsistent and cannot be exported safely`);
+      error.code = E_TASK_CLAIM_OWNERSHIP_INCONSISTENT;
+      error.reasonCodes = claimProjection.reasonCodes;
+      error.errors = claimProjection.ownershipErrors;
+      throw error;
+    }
+  }
+
   const stateSource = await tryReadJson(target, taskArtifactPath(taskId, "state"), ARTIFACT_PATHS.state, "work-state", packageRoot);
   let receiptSource = null;
   try {
@@ -102,6 +115,7 @@ export async function exportTaskBundle(target, taskId, packageRoot) {
     [ARTIFACT_PATHS.sources, null, "sources.json", "source-registry"],
     [ARTIFACT_PATHS.config, null, "config.json", "config"],
     [taskArtifactPath(taskId, "continuity"), ARTIFACT_PATHS.continuity, "continuity.json", "continuity"],
+    [taskArtifactPath(taskId, "recovery"), null, "recovery.json", "task-recovery"],
   ];
   for (const [taskRel, legacyRel, destinationName, schemaName] of optional) {
     let copied = null;
@@ -180,6 +194,7 @@ export async function readTaskBundle(target, taskId, packageRoot) {
     "config.json": ["config", "config"],
     "continuity.json": ["continuity", "continuity"],
     "task.json": ["descriptor", "task-descriptor"],
+    "recovery.json": ["recovery", "task-recovery"],
   };
   const executions = {};
   for (const artifact of manifest.value.artifacts) {

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

@@ -1,5 +1,5 @@
 /**
- * Canonical, declarative definition of all 42 ForgeLoop CLI commands.
+ * Canonical, declarative definition of all ForgeLoop CLI commands.
  * This is the machine source of truth for CLI option parsing, help text,
  * metadata, documentation generation, and conformance validation.
  *
@@ -43,7 +43,7 @@ export const CLI_COMMON_OPTIONS = Object.freeze({
  */
 export const CLI_TASK_OPTION = Object.freeze({
   "--task": Object.freeze({
-    targetKey: "task",
+    targetKey: "taskId",
     parseType: "string",
     takesValue: true,
     valueName: "id",
@@ -133,7 +133,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
-      "--work": Object.freeze({ targetKey: "work", parseType: "string", takesValue: true, valueName: "type", missingValueMessage: "--work requires a type", description: "declared work type" }),
+      "--work": Object.freeze({ targetKey: "workType", parseType: "string", takesValue: true, valueName: "type", missingValueMessage: "--work requires a type", description: "declared work type" }),
       "--surface": Object.freeze({ targetKey: "surfaces", parseType: "string", takesValue: true, valueName: "value", repeatable: true, missingValueMessage: "--surface requires a value", description: "affected surface" }),
       "--risk": Object.freeze({ targetKey: "risks", parseType: "string", takesValue: true, valueName: "value", repeatable: true, missingValueMessage: "--risk requires a value", description: "task risk" }),
       "--platform": Object.freeze({ targetKey: "platforms", parseType: "string", takesValue: true, valueName: "value", repeatable: true, missingValueMessage: "--platform requires a value", description: "affected platform" }),
@@ -767,10 +767,56 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],
-    removes: [".forgeloop/task-state/<taskKey>/.lock"],
+    removes: [".forgeloop/locks/<taskKey>.lock"],
     mayExecuteExternalProcess: false,
     description: "Removes an orphaned task lock file to recover an interrupted task.",
   }),
+  "task-recover": Object.freeze({
+    name: "task-recover",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--acknowledge-recovery": Object.freeze({ targetKey: "acknowledgeRecovery", parseType: "boolean", takesValue: false, description: "acknowledge release of claims for a STALE or ABANDONED task (required; not host attestation)" }),
+      "--operator-authorized": Object.freeze({ targetKey: "operatorAuthorized", parseType: "boolean", takesValue: false, description: "deprecated alias for --acknowledge-recovery; does not attest operator authority" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/recovery.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Caller-acknowledged recovery of a STALE or ABANDONED task; records durable state and releases effective write claims.",
+  }),
+  "task-repair-legacy-recovery": Object.freeze({
+    name: "task-repair-legacy-recovery",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--acknowledge-recovery": Object.freeze({ targetKey: "acknowledgeRecovery", parseType: "boolean", takesValue: false, description: "fresh explicit acknowledgement of the legacy boundary migration (required)" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/recovery.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Migrates one recognized legacy OPERATOR_RECOVERY_RECORDED boundary event into the modern durable recovery representation (append-only; original event unchanged).",
+  }),
+  "task-resume": Object.freeze({
+    name: "task-resume",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--claim": Object.freeze({ targetKey: "claims", parseType: "string", takesValue: true, repeatable: true, valueName: "path", missingValueMessage: "--claim requires a path", description: "write claim to reacquire (defaults to all released claims)" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/task.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [".forgeloop/task-state/<taskKey>/recovery.json"],
+    mayExecuteExternalProcess: false,
+    description: "Reacquires a recovered task's write claims under project serialization and restores ordinary mutation authority.",
+  }),
 });
 
 /**