@cassiomc1/forgeloop 1.3.0 → 1.5.0

package/src/commands/audit.js

@@ -14,6 +14,11 @@ export async function runAudit(options = {}) {
 
 export function formatAuditResult(result) {
   const lines = [`FORGELOOP AUDIT: ${result.status}`];
+  if (result.recovery) lines.push(`RECOVERY: ${result.recovery.status} (${result.recovery.recoveryId})`);
+  if (result.claims) {
+    lines.push(`CLAIM STATE: ${result.claims.state}`);
+    lines.push(`MUTATION ALLOWED: ${result.claims.mutationAllowed ? "yes" : "no"}`);
+  }
   for (const error of result.errors) {
     lines.push(`${error.code}: ${error.message}`);
     if (error.next) lines.push(`NEXT: ${error.next}`);

package/src/commands/inspect.js

@@ -19,6 +19,12 @@ export function formatInspectResult(report) {
     `Authority source: ${report.authority.sourceType ?? "none configured"} / ${report.authority.trusted ? "TRUSTED" : report.authority.trustMode === "NONE" ? "UNATTESTED" : "UNTRUSTED"}`,
     `Authority trust: ${report.authority.trustMode}`,
     `State: ${report.state.status}`,
+    ...(report.recovery
+      ? [`Recovery: ${report.recovery.status} (${report.recovery.recoveryId})`]
+      : []),
+    ...(report.claims
+      ? [`Claim state: ${report.claims.state}`, `Mutation allowed: ${report.claims.mutationAllowed ? "yes" : "no"}`]
+      : []),
     `Adapters: ${report.adapters.detected.length} detected`,
     `Findings: ${report.findings.length}`,
     report.ok ? "healthy: ForgeLoop target is ready" : "unhealthy: ForgeLoop target needs attention",

package/src/commands/progress.js

@@ -1,12 +1,16 @@
 import { evaluateProgress, PROGRESS_STATUS } from "../core/progress.js";
 import { readEvents } from "../core/events.js";
 import { readWorkState } from "../core/work-state.js";
-import { resolveTaskContext } from "../core/task-context.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
 
 export { evaluateProgress };
 
 export async function runProgress({ target, packageRoot, taskId, task }) {
-  const resolved = await resolveTaskContext(target, { packageRoot, explicitTaskId: taskId ?? task });
+  const resolved = await resolveTaskContext(target, {
+    packageRoot,
+    taskId: taskId ?? task,
+    selectionMode: TASK_SELECTION_MODES.READ,
+  });
   const activeTaskId = resolved.taskId;
 
   const state = await readWorkState(target, { packageRoot, taskId: activeTaskId });

package/src/commands/status.js

@@ -2,6 +2,7 @@ import { readAndClassifyWorkState } from "../core/work-state.js";
 import { inspectSchemaHealth } from "../core/schema-validation.js";
 import { reconcileContinuity } from "../core/continuity-reconciliation.js";
 import { withResolvedTask } from "../core/task-command.js";
+import { findTaskById } from "../core/task-discovery.js";
 
 export async function runStatus({ target, packageRoot, contractFile = null, taskId, task } = {}) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
@@ -11,10 +12,19 @@ export async function runStatus({ target, packageRoot, contractFile = null, task
       inspectSchemaHealth(target),
       reconcileContinuity({ target, packageRoot, taskId: effectiveTaskId }),
     ]);
+    const taskInfo = effectiveTaskId ? await findTaskById(target, effectiveTaskId, packageRoot) : null;
     return {
       ...state,
       taskId: effectiveTaskId,
       taskKey: ctx?.taskKey ?? null,
+      recovery: taskInfo?.recovery ?? null,
+      claimState: taskInfo?.claimState ?? null,
+      historicalWriteClaims: taskInfo?.historicalWriteClaims ?? [],
+      effectiveWriteClaims: taskInfo?.effectiveWriteClaims ?? [],
+      mutationAllowed: taskInfo?.mutationAllowed ?? true,
+      ownershipValid: taskInfo?.ownershipValid ?? true,
+      ownershipErrors: taskInfo?.ownershipErrors ?? taskInfo?.errors ?? [],
+      reasonCodes: taskInfo?.reasonCodes ?? [],
       protocol,
       continuity,
       evidence: [...(state.evidence ?? []), ...(protocol.evidence ?? [])],
@@ -31,6 +41,13 @@ export function formatStatusResult(result) {
     `Pending: ${result.pending.join(", ") || "none"}`,
   ];
   if (result.reasons.length > 0) lines.push(`Reasons: ${result.reasons.join(", ")}`);
+  if (result.recovery) {
+    lines.push(`Recovery: ${result.recovery.status} (${result.recovery.recoveryId})`);
+  }
+  if (result.claimState) {
+    lines.push(`Claim state: ${result.claimState}`);
+    lines.push(`Mutation allowed: ${result.mutationAllowed ? "yes" : "no"}`);
+  }
   if (result.warnings?.length > 0) lines.push(`Warnings: ${result.warnings.join(", ")}`);
   if (result.contractComparison) lines.push(`Contract: ${result.contractComparison}`);
   if (result.artifactComparison) lines.push(`Artifacts: ${result.artifactComparison}`);

package/src/commands/task-create.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { assertTaskId } from "../core/task-identity.js";
 import { createTaskDescriptor, writeTaskDescriptor } from "../core/task-descriptor.js";
 import { normalizeWriteClaims, assertNoScopeConflicts, assertScopeClean } from "../core/task-scope.js";
+import { inspectTaskConflictState } from "../core/task-conflict-inspection.js";
 import { discoverTasks, findTaskById } from "../core/task-discovery.js";
 import { withProjectClaimsLock } from "../core/task-lock.js";
 import { withTaskTransaction } from "../core/transaction.js";
@@ -10,6 +11,7 @@ import { ensureWithin, fileExists } from "../core/filesystem.js";
 import { validateContract, writeContract } from "../core/contract.js";
 import { appendProtocolEvent } from "../core/events.js";
 import { E_TASK_REQUIRED, E_TASK_ALREADY_EXISTS, E_TASK_DESCRIPTOR_INVALID } from "../core/error-codes.js";
+import { recoveryGuidanceForClassification } from "../core/next-action-model.js";
 
 function taskError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -18,6 +20,42 @@ function taskError(code, message, artifacts = []) {
   return error;
 }
 
+export async function assertNoScopeConflictsWithInspection(claims, existingTasks, currentTaskId, { target, packageRoot } = {}) {
+  try {
+    assertNoScopeConflicts(claims, existingTasks, currentTaskId);
+  } catch (error) {
+    if (error.code !== "E_TASK_SCOPE_CONFLICT") throw error;
+    const inspected = [];
+    for (const conflict of error.conflicts ?? []) {
+      let inspection = null;
+      try {
+        inspection = await inspectTaskConflictState(target, { taskId: conflict.taskId, packageRoot });
+      } catch (inspectionError) {
+        inspection = {
+          taskId: conflict.taskId,
+          classification: "INCONSISTENT",
+          reasonCodes: [inspectionError.code ?? "E_TASK_NOT_FOUND"],
+          recoverable: false,
+        };
+      }
+      const guidance = recoveryGuidanceForClassification(inspection.classification, conflict.taskId);
+      inspected.push({
+        ...conflict,
+        classification: inspection.classification,
+        reasonCodes: inspection.reasonCodes,
+        nextAction: guidance.nextAction,
+        commandSpecs: guidance.commandSpecs,
+        inspection,
+      });
+    }
+    error.conflicts = inspected;
+    error.message = `${error.message}; conflicting task classifications: ${inspected
+      .map((item) => `${item.taskId}=${item.inspection.classification}`)
+      .join(", ")}`;
+    throw error;
+  }
+}
+
 export async function runTaskCreate({ target, packageRoot, taskId, claims = [], contractFile = null } = {}) {
   if (!taskId) {
     throw taskError(E_TASK_REQUIRED, "--task is required for task-create");
@@ -33,7 +71,7 @@ export async function runTaskCreate({ target, packageRoot, taskId, claims = [],
 
   return withProjectClaimsLock(target, async () => {
     const allTasks = await discoverTasks(target, packageRoot);
-    assertNoScopeConflicts(normalizedClaims, allTasks, taskId);
+    await assertNoScopeConflictsWithInspection(normalizedClaims, allTasks, taskId, { target, packageRoot });
     if (normalizedClaims.length > 0) {
       await assertScopeClean(target, normalizedClaims);
     }

package/src/commands/task-list.js

@@ -20,6 +20,14 @@ export async function runTaskList({ target, packageRoot } = {}) {
         healthy: true,
         phase: task.phase,
         writeClaims: task.writeClaims ?? [],
+        historicalWriteClaims: task.historicalWriteClaims ?? [],
+        effectiveWriteClaims: task.effectiveWriteClaims ?? [],
+        claimState: task.claimState,
+        recovery: task.recovery,
+        mutationAllowed: task.mutationAllowed,
+        ownershipValid: task.ownershipValid,
+        ownershipErrors: task.ownershipErrors ?? task.errors ?? [],
+        reasonCodes: task.reasonCodes ?? [],
         locked: task.locked,
         hasContinuity: task.hasContinuity,
         hasReceipt: task.hasReceipt,
@@ -40,8 +48,13 @@ export function formatTaskListResult(result) {
       lines.push(`- ${task.taskKey} [CORRUPT]: ${task.error?.message ?? "unhealthy task namespace"}`);
     } else {
       const lockStr = task.locked ? " [LOCKED]" : "";
+      const recoveryStr = task.claimState === "RELEASED_BY_RECOVERY"
+        ? " [RECOVERED]"
+        : task.claimState === "INCONSISTENT"
+          ? " [OWNERSHIP INCONSISTENT]"
+          : "";
       const claimsStr = task.writeClaims.length > 0 ? ` (claims: ${task.writeClaims.join(", ")})` : "";
-      lines.push(`- ${task.taskId}: ${task.phase ?? "UNINITIALIZED"}${lockStr}${claimsStr}`);
+      lines.push(`- ${task.taskId}: ${task.phase ?? "UNINITIALIZED"}${lockStr}${recoveryStr}${claimsStr}`);
     }
   }
   return `${lines.join("\n")}\n`;

package/src/commands/task-lock-status.js

@@ -1,8 +1,8 @@
-import { resolveTaskContext } from "../core/task-context.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
 import { classifyLockStaleness, readLockInfo } from "../core/task-lock.js";
 
 export async function runTaskLockStatus({ 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 lock = await readLockInfo(target, context.taskId);
   if (!lock) {
     return {

package/src/commands/task-recover.js

@@ -0,0 +1,202 @@
+import { randomUUID } from "node:crypto";
+
+import { resolveTaskContext } from "../core/task-context.js";
+import { inspectTaskConflictState } from "../core/task-conflict-inspection.js";
+import { appendProtocolEvent } from "../core/events.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import { currentRepositoryFingerprint } from "../core/repository.js";
+import {
+  readLockInfo,
+  releaseStaleTaskLockIfUnchanged,
+  withProjectClaimsLock,
+} from "../core/task-lock.js";
+import {
+  E_TASK_RECOVERY_AUTHORIZATION_REQUIRED,
+  E_TASK_RECOVERY_INCONSISTENT,
+  E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE,
+  E_TASK_RECOVERY_UNSAFE,
+  E_TASK_ALREADY_RECOVERED,
+} from "../core/error-codes.js";
+import { readTaskDescriptor } from "../core/task-descriptor.js";
+import {
+  createTaskRecovery,
+  writeTaskRecovery,
+} from "../core/task-recovery.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+
+export const TASK_RECOVERY_ALLOWED_CLASSIFICATIONS = Object.freeze(new Set([
+  "STALE",
+  "ABANDONED",
+]));
+
+function recoveryError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function alreadyRecoveredError(taskId, recovery) {
+  const error = recoveryError(E_TASK_ALREADY_RECOVERED, `Task ${taskId} is already RECOVERED`);
+  error.recovery = recovery;
+  return error;
+}
+
+async function assertConsistentRecoverableOwnership(target, taskId, packageRoot) {
+  const projection = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!projection.valid) {
+    const error = recoveryError(
+      E_TASK_RECOVERY_INCONSISTENT,
+      `Task ${taskId} claim ownership is inconsistent; repair recovery state before task-recover`,
+    );
+    error.reasonCodes = projection.reasonCodes;
+    error.recoveryErrors = projection.ownershipErrors;
+    throw error;
+  }
+  if (projection.claimState === "RELEASED_BY_RECOVERY") {
+    throw alreadyRecoveredError(taskId, projection.recovery);
+  }
+  return projection;
+}
+
+function assertRecoveryAllowed(taskId, inspection) {
+  if (inspection.classification === "RECOVERABLE") {
+    throw recoveryError(
+      E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE,
+      `Task ${taskId} is RECOVERABLE through canonical reconciliation; claim-release recovery is refused`,
+    );
+  }
+  if (inspection.classification === "INCONSISTENT") {
+    throw recoveryError(
+      E_TASK_RECOVERY_INCONSISTENT,
+      `Task ${taskId} state is INCONSISTENT (${inspection.reasonCodes.join(", ")}); repair the underlying artifact first`,
+    );
+  }
+  if (!TASK_RECOVERY_ALLOWED_CLASSIFICATIONS.has(inspection.classification)) {
+    throw recoveryError(
+      E_TASK_RECOVERY_UNSAFE,
+      `Task ${taskId} is ${inspection.classification} (${inspection.reasonCodes.join(", ")}); only STALE or ABANDONED tasks may release claims`,
+    );
+  }
+}
+
+export async function runTaskRecover({
+  target,
+  packageRoot,
+  taskId,
+  acknowledgeRecovery = false,
+  operatorAuthorized = false,
+} = {}) {
+  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  const effectiveTaskId = context.taskId;
+
+  if (!acknowledgeRecovery && !operatorAuthorized) {
+    throw recoveryError(
+      E_TASK_RECOVERY_AUTHORIZATION_REQUIRED,
+      "task-recover requires explicit caller acknowledgement: re-run with --acknowledge-recovery",
+    );
+  }
+
+  await assertConsistentRecoverableOwnership(target, effectiveTaskId, packageRoot);
+
+  return withProjectClaimsLock(target, "task-recover", async () => {
+    await assertConsistentRecoverableOwnership(target, effectiveTaskId, packageRoot);
+
+    const inspectionBeforeLock = await inspectTaskConflictState(target, {
+      taskId: effectiveTaskId,
+      packageRoot,
+    });
+    assertRecoveryAllowed(effectiveTaskId, inspectionBeforeLock);
+
+    if (inspectionBeforeLock.evidence.lockStatus === "STALE") {
+      const expectedLock = await readLockInfo(target, effectiveTaskId);
+      const released = await releaseStaleTaskLockIfUnchanged(target, effectiveTaskId, expectedLock);
+      if (!released.released && released.reason !== "LOCK_MISSING") {
+        throw recoveryError(
+          E_TASK_RECOVERY_UNSAFE,
+          `Task ${effectiveTaskId} lock changed during recovery (${released.reason}); retry after re-inspection`,
+        );
+      }
+    }
+
+    return withTaskTransaction({
+      target,
+      taskId: effectiveTaskId,
+      operation: "task-recover",
+      packageRoot,
+      recordCommitEvent: true,
+    }, async (transaction) => {
+      await assertConsistentRecoverableOwnership(target, effectiveTaskId, packageRoot);
+
+      const inspection = await inspectTaskConflictState(target, {
+        taskId: effectiveTaskId,
+        packageRoot,
+        ignoredLockId: transaction.lock.lockId,
+      });
+      assertRecoveryAllowed(effectiveTaskId, inspection);
+      if (inspection.evidence.workStateRevision !== inspectionBeforeLock.evidence.workStateRevision
+        || inspection.evidence.ledgerLastSeq !== inspectionBeforeLock.evidence.ledgerLastSeq
+        || inspection.evidence.phase !== inspectionBeforeLock.evidence.phase) {
+        throw recoveryError(
+          E_TASK_RECOVERY_UNSAFE,
+          `Task ${effectiveTaskId} changed during recovery precondition validation`,
+        );
+      }
+
+      const descriptorArtifact = await readTaskDescriptor(target, context.taskKey, packageRoot);
+      const releasedClaims = descriptorArtifact?.value?.writeClaims ?? [];
+      const repository = await currentRepositoryFingerprint(target);
+      const recoveryId = `recovery-${randomUUID()}`;
+      const recoveredAt = new Date().toISOString();
+      const recoveryEvent = await appendProtocolEvent(target, {
+        taskId: effectiveTaskId,
+        event: "OPERATOR_RECOVERY_RECORDED",
+        at: recoveredAt,
+        details: {
+          recoveryId,
+          classification: inspection.classification,
+          reasonCodes: inspection.reasonCodes,
+          previousPhase: inspection.evidence.phase,
+          previousRevision: inspection.evidence.workStateRevision ?? 0,
+          previousHead: inspection.evidence.repositoryHead,
+          previousBranch: inspection.evidence.repositoryBranch,
+          currentHead: repository.head,
+          currentBranch: repository.branch,
+          releasedClaims,
+          authorityKind: "CALLER_ACKNOWLEDGED",
+        },
+      }, packageRoot, { taskId: effectiveTaskId });
+
+      await writeTaskRecovery(target, createTaskRecovery({
+        taskId: effectiveTaskId,
+        recoveredAt,
+        recoveryId,
+        recoveryEventSeq: recoveryEvent.seq,
+        classificationAtRecovery: inspection.classification,
+        reasonCodes: inspection.reasonCodes,
+        releasedClaims,
+        previousPhase: inspection.evidence.phase,
+        previousRevision: inspection.evidence.workStateRevision ?? 0,
+        repositoryFingerprint: repository,
+        authority: { kind: "CALLER_ACKNOWLEDGED" },
+      }), packageRoot);
+
+      return {
+        taskId: effectiveTaskId,
+        taskKey: context.taskKey,
+        recovered: true,
+        recoveryId,
+        classification: inspection.classification,
+        reasonCodes: inspection.reasonCodes,
+        phase: inspection.evidence.phase,
+        claimsReleased: true,
+        releasedClaims,
+        authority: { kind: "CALLER_ACKNOWLEDGED" },
+        message: `Task ${effectiveTaskId} recovered by caller acknowledgement; write claims released without completion claim`,
+      };
+    });
+  });
+}
+
+export function formatTaskRecoverResult(result) {
+  return `${result.message}\nclassification: ${result.classification}\nphase: ${result.phase} (unchanged)\n`;
+}