@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/commands/task-abandon.js

@@ -0,0 +1,224 @@
+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 { withProjectClaimsLock } from "../core/task-lock.js";
+import { readTaskDescriptor } from "../core/task-descriptor.js";
+import { createTaskRecovery, writeTaskRecovery } from "../core/task-recovery.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import {
+  E_TASK_ABANDON_AUTHORIZATION_REQUIRED,
+  E_TASK_ABANDON_INCONSISTENT,
+  E_TASK_ABANDON_INVALID_STATE,
+  E_TASK_ABANDON_UNSAFE,
+  E_TASK_ALREADY_ABANDONED,
+} from "../core/error-codes.js";
+
+const ABANDONMENT_REASON_CODES = Object.freeze(["CALLER_ABANDONED"]);
+
+function abandonError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function sameList(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((value, index) => value === right[index]);
+}
+
+function snapshot(inspection) {
+  return {
+    phase: inspection.evidence.phase,
+    revision: inspection.evidence.workStateRevision,
+    ledgerLastSeq: inspection.evidence.ledgerLastSeq,
+    claimState: inspection.evidence.claimState,
+    effectiveWriteClaims: [...inspection.evidence.effectiveWriteClaims],
+  };
+}
+
+function assertSnapshotUnchanged(before, after, taskId) {
+  const unchanged = before.phase === after.phase
+    && before.revision === after.revision
+    && before.ledgerLastSeq === after.ledgerLastSeq
+    && before.claimState === after.claimState
+    && sameList(before.effectiveWriteClaims, after.effectiveWriteClaims);
+  if (!unchanged) {
+    throw abandonError(
+      E_TASK_ABANDON_UNSAFE,
+      `Task ${taskId} changed during abandonment precondition validation`,
+      { before, after },
+    );
+  }
+}
+
+async function assertAbandonableOwnership(target, taskId, packageRoot) {
+  const projection = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (projection.phase === "COMPLETE" || projection.claimState === "RELEASED_BY_COMPLETION") {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, `Task ${taskId} is COMPLETE and cannot be abandoned`);
+  }
+  if (!projection.valid || !projection.ownershipValid) {
+    throw abandonError(
+      E_TASK_ABANDON_INCONSISTENT,
+      `Task ${taskId} claim ownership is inconsistent; abandonment is blocked`,
+      { reasonCodes: projection.reasonCodes, ownershipErrors: projection.ownershipErrors },
+    );
+  }
+  if (projection.claimState === "RELEASED_BY_RECOVERY") {
+    throw abandonError(
+      E_TASK_ALREADY_ABANDONED,
+      `Task ${taskId} is already abandoned/recovered`,
+      { recovery: projection.recovery },
+    );
+  }
+  if (projection.claimState !== "ACTIVE" || projection.mutationAllowed !== true) {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, `Task ${taskId} is not an active mutable task`);
+  }
+  return projection;
+}
+
+function assertInspectionAbandonable(taskId, inspection) {
+  if (!inspection.evidence.healthy || !inspection.evidence.ledgerValid || !inspection.evidence.ownershipValid) {
+    throw abandonError(
+      E_TASK_ABANDON_INCONSISTENT,
+      `Task ${taskId} cannot be abandoned because canonical ownership or ledger validation failed`,
+      { reasonCodes: inspection.reasonCodes, ledgerErrors: inspection.evidence.ledgerErrors },
+    );
+  }
+  if (!inspection.evidence.phase || inspection.evidence.phase === "COMPLETE") {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, `Task ${taskId} is not eligible for abandonment`);
+  }
+  if (inspection.evidence.claimState !== "ACTIVE" || inspection.evidence.mutationAllowed !== true) {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, `Task ${taskId} is not an active mutable task`);
+  }
+}
+
+export async function runTaskAbandon({
+  target,
+  packageRoot,
+  taskId,
+  acknowledgeAbandonment = false,
+} = {}) {
+  if (typeof taskId !== "string" || taskId.trim() === "") {
+    throw abandonError(E_TASK_ABANDON_INVALID_STATE, "task-abandon requires an explicit --task ID");
+  }
+  if (!acknowledgeAbandonment) {
+    throw abandonError(
+      E_TASK_ABANDON_AUTHORIZATION_REQUIRED,
+      "task-abandon requires explicit caller acknowledgement: re-run with --acknowledge-abandonment",
+    );
+  }
+
+  let context;
+  try {
+    context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  } catch (error) {
+    throw abandonError(
+      E_TASK_ABANDON_INCONSISTENT,
+      `Task ${taskId} cannot be abandoned because its canonical identity is unreadable`,
+      { causeCode: error.code, causeMessage: error.message },
+    );
+  }
+  const effectiveTaskId = context.taskId;
+  await assertAbandonableOwnership(target, effectiveTaskId, packageRoot);
+
+  return withProjectClaimsLock(target, "task-abandon", async () => {
+    await assertAbandonableOwnership(target, effectiveTaskId, packageRoot);
+    const inspectionBeforeLock = await inspectTaskConflictState(target, {
+      taskId: effectiveTaskId,
+      packageRoot,
+    });
+    assertInspectionAbandonable(effectiveTaskId, inspectionBeforeLock);
+    const before = snapshot(inspectionBeforeLock);
+
+    return withTaskTransaction({
+      target,
+      taskId: effectiveTaskId,
+      operation: "task-abandon",
+      packageRoot,
+      recordCommitEvent: true,
+    }, async (transaction) => {
+      const descriptor = await readTaskDescriptor(target, context.taskKey, packageRoot);
+      if (descriptor.value.taskId !== effectiveTaskId || descriptor.value.taskKey !== context.taskKey) {
+        throw abandonError(E_TASK_ABANDON_UNSAFE, `Task ${effectiveTaskId} identity changed during abandonment`);
+      }
+
+      await assertAbandonableOwnership(target, effectiveTaskId, packageRoot);
+      const inspection = await inspectTaskConflictState(target, {
+        taskId: effectiveTaskId,
+        packageRoot,
+        ignoredLockId: transaction.lock.lockId,
+      });
+      assertInspectionAbandonable(effectiveTaskId, inspection);
+      assertSnapshotUnchanged(before, snapshot(inspection), effectiveTaskId);
+
+      const repository = await currentRepositoryFingerprint(target);
+      const recoveryId = `recovery-${randomUUID()}`;
+      const abandonedAt = new Date().toISOString();
+      const releasedClaims = [...inspection.evidence.effectiveWriteClaims];
+      const details = {
+        recoveryId,
+        classification: "ABANDONED",
+        reasonCodes: [...ABANDONMENT_REASON_CODES],
+        previousPhase: inspection.evidence.phase,
+        previousRevision: inspection.evidence.workStateRevision,
+        previousHead: inspection.evidence.repositoryHead,
+        previousBranch: inspection.evidence.repositoryBranch,
+        currentHead: repository.head,
+        currentBranch: repository.branch,
+        releasedClaims,
+        authorityKind: "CALLER_ACKNOWLEDGED",
+      };
+
+      const abandonmentEvent = await appendProtocolEvent(target, {
+        taskId: effectiveTaskId,
+        event: "TASK_ABANDONED",
+        at: abandonedAt,
+        details,
+      }, packageRoot, { taskId: effectiveTaskId });
+
+      await writeTaskRecovery(target, createTaskRecovery({
+        taskId: effectiveTaskId,
+        recoveredAt: abandonedAt,
+        recoveryId,
+        recoveryEventSeq: abandonmentEvent.seq,
+        classificationAtRecovery: "ABANDONED",
+        reasonCodes: ABANDONMENT_REASON_CODES,
+        releasedClaims,
+        previousPhase: inspection.evidence.phase,
+        previousRevision: inspection.evidence.workStateRevision,
+        repositoryFingerprint: repository,
+        authority: { kind: "CALLER_ACKNOWLEDGED" },
+      }), packageRoot);
+
+      return {
+        taskId: effectiveTaskId,
+        taskKey: context.taskKey,
+        abandoned: true,
+        recovered: true,
+        recoveryId,
+        classification: "ABANDONED",
+        reasonCodes: [...ABANDONMENT_REASON_CODES],
+        phase: inspection.evidence.phase,
+        claimsReleased: true,
+        releasedClaims,
+        effectiveWriteClaims: [],
+        claimState: "RELEASED_BY_RECOVERY",
+        mutationAllowed: false,
+        authority: { kind: "CALLER_ACKNOWLEDGED" },
+        message: `Task ${effectiveTaskId} explicitly abandoned by caller acknowledgement; write claims released without completion claim`,
+      };
+    });
+  });
+}
+
+export function formatTaskAbandonResult(result) {
+  const claims = result.releasedClaims.length === 0 ? "none" : result.releasedClaims.join(", ");
+  return `${result.message}\nclassification: ${result.classification}\nphase: ${result.phase} (unchanged)\nreleased claims: ${claims}\n`;
+}

package/src/commands/task-create.js

@@ -9,6 +9,7 @@ import { withTaskTransaction } from "../core/transaction.js";
 import { taskDirectory } from "../core/task-paths.js";
 import { ensureWithin, fileExists } from "../core/filesystem.js";
 import { validateContract, writeContract } from "../core/contract.js";
+import { createPresetContract, CONTRACT_PRESET_IDS } from "../core/contract-presets.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";
@@ -56,12 +57,45 @@ export async function assertNoScopeConflictsWithInspection(claims, existingTasks
   }
 }
 
-export async function runTaskCreate({ target, packageRoot, taskId, claims = [], contractFile = null } = {}) {
+async function validateTaskCreateScope({ target, packageRoot, claims, taskId }) {
+  const allTasks = await discoverTasks(target, packageRoot);
+  await assertNoScopeConflictsWithInspection(claims, allTasks, taskId, { target, packageRoot });
+  if (claims.length > 0) await assertScopeClean(target, claims);
+}
+
+function previewResult({ taskId, normalizedClaims, preset, proposedContract }) {
+  return {
+    preview: true,
+    taskId,
+    writeClaims: normalizedClaims,
+    preset,
+    contract: proposedContract,
+    createsLifecycleState: false,
+  };
+}
+
+export async function runTaskCreate({
+  target,
+  packageRoot,
+  taskId,
+  claims = [],
+  contractFile = null,
+  preset = null,
+  preview = false,
+} = {}) {
   if (!taskId) {
     throw taskError(E_TASK_REQUIRED, "--task is required for task-create");
   }
   assertTaskId(taskId);
 
+  if (preset && !CONTRACT_PRESET_IDS.includes(preset)) {
+    const error = new Error(`Unknown contract preset: ${preset}. Expected one of ${CONTRACT_PRESET_IDS.join(", ")}`);
+    error.code = "E_CONTRACT_PRESET_UNKNOWN";
+    throw error;
+  }
+  if (preset && contractFile) {
+    throw taskError("E_CONTRACT_INPUT_CONFLICT", "Use either --preset or --contract-file, not both");
+  }
   const existing = await findTaskById(target, taskId, packageRoot);
   if (existing) {
     throw taskError(E_TASK_ALREADY_EXISTS, `Task already exists: ${taskId}`);
@@ -69,13 +103,45 @@ export async function runTaskCreate({ target, packageRoot, taskId, claims = [],
 
   const normalizedClaims = normalizeWriteClaims(claims ?? []);
 
-  return withProjectClaimsLock(target, async () => {
-    const allTasks = await discoverTasks(target, packageRoot);
-    await assertNoScopeConflictsWithInspection(normalizedClaims, allTasks, taskId, { target, packageRoot });
-    if (normalizedClaims.length > 0) {
-      await assertScopeClean(target, normalizedClaims);
+  let proposedContract = null;
+  if (preset) proposedContract = createPresetContract({ taskId, preset, claims: normalizedClaims });
+  if (contractFile) {
+    const sourcePath = ensureWithin(target, contractFile);
+    if (!(await fileExists(sourcePath))) {
+      throw taskError("E_CONTRACT_MISSING", `Specified contract file not found: ${contractFile}`);
+    }
+    const raw = await readFile(sourcePath, "utf8");
+    try {
+      proposedContract = JSON.parse(raw);
+    } catch {
+      throw taskError("E_CONTRACT_INVALID", `Specified contract file is not valid JSON: ${contractFile}`);
     }
+    await validateContract(proposedContract, packageRoot);
+    if (proposedContract.taskId && proposedContract.taskId !== taskId) {
+      throw taskError(
+        E_TASK_DESCRIPTOR_INVALID,
+        `Contract taskId "${proposedContract.taskId}" does not match requested taskId "${taskId}"`,
+      );
+    }
+    proposedContract = { ...proposedContract, taskId };
+  }
+
+  if (proposedContract) await validateContract({ ...proposedContract, taskId }, packageRoot);
+
+  // Preview is advisory: it must never create the claims-lock directory, remove
+  // a stale lock, or fail because another process currently owns the lock.
+  if (preview) {
+    await validateTaskCreateScope({ target, packageRoot, claims: normalizedClaims, taskId });
+    return previewResult({ taskId, normalizedClaims, preset, proposedContract });
+  }
 
+  return withProjectClaimsLock(target, async () => {
+    // Re-check after acquiring the reservation. Preview results are not a
+    // reservation and the repository may have changed since they were built.
+    if (await findTaskById(target, taskId, packageRoot)) {
+      throw taskError(E_TASK_ALREADY_EXISTS, `Task already exists: ${taskId}`);
+    }
+    await validateTaskCreateScope({ target, packageRoot, claims: normalizedClaims, taskId });
     return withTaskTransaction({ target, taskId, operation: "task-create", packageRoot, recordCommitEvent: true }, async () => {
       const descriptor = createTaskDescriptor({
         taskId,
@@ -84,26 +150,9 @@ export async function runTaskCreate({ target, packageRoot, taskId, claims = [],
       const written = await writeTaskDescriptor(target, descriptor, packageRoot);
 
       let contractCopied = false;
-      if (contractFile) {
-        const sourcePath = ensureWithin(target, contractFile);
-        if (!(await fileExists(sourcePath))) {
-          throw taskError("E_CONTRACT_MISSING", `Specified contract file not found: ${contractFile}`);
-        }
-        const raw = await readFile(sourcePath, "utf8");
-        let parsed;
-        try {
-          parsed = JSON.parse(raw);
-        } catch {
-          throw taskError("E_CONTRACT_INVALID", `Specified contract file is not valid JSON: ${contractFile}`);
-        }
+      if (proposedContract) {
+        const parsed = { ...proposedContract, taskId };
         await validateContract(parsed, packageRoot);
-        if (parsed.taskId && parsed.taskId !== taskId) {
-          throw taskError(
-            E_TASK_DESCRIPTOR_INVALID,
-            `Contract taskId "${parsed.taskId}" does not match requested taskId "${taskId}"`,
-          );
-        }
-        parsed.taskId = taskId;
         await writeContract(target, parsed, packageRoot, { taskId });
         contractCopied = true;
       }
@@ -128,6 +177,16 @@ export async function runTaskCreate({ target, packageRoot, taskId, claims = [],
 }
 
 export function formatTaskCreateResult(result) {
+  if (result.preview) {
+    return `${JSON.stringify({
+      preview: true,
+      taskId: result.taskId,
+      preset: result.preset,
+      writeClaims: result.writeClaims,
+      contract: result.contract,
+      createsLifecycleState: false,
+    }, null, 2)}\n`;
+  }
   const claims = result.writeClaims.length === 0 ? "none" : result.writeClaims.join(", ");
   return `created task: ${result.taskId}\nkey: ${result.taskKey}\ndirectory: ${result.directory}\nclaims: ${claims}\n`;
 }

package/src/commands/task-list.js

@@ -1,9 +1,23 @@
 import { discoverTasks } from "../core/task-discovery.js";
+import { WORK_PHASES } from "../core/protocol.js";
 
-export async function runTaskList({ target, packageRoot } = {}) {
+export async function runTaskList({ target, packageRoot, phase = null, active = false, limit = null, offset = 0 } = {}) {
   const tasks = await discoverTasks(target, packageRoot);
+  const normalizedPhase = typeof phase === "string" && phase.trim() !== "" ? phase.trim().toUpperCase() : null;
+  if (normalizedPhase && !WORK_PHASES.includes(normalizedPhase)) {
+    const error = new Error(`Unknown task phase filter: ${phase}`);
+    error.code = "E_TASK_PHASE_INVALID";
+    throw error;
+  }
+  const phaseFiltered = normalizedPhase ? tasks.filter((task) => task.phase === normalizedPhase) : tasks;
+  const filtered = active
+    ? phaseFiltered.filter((task) => task.claimState === "ACTIVE" && task.mutationAllowed === true)
+    : phaseFiltered;
+  const start = Number.isInteger(offset) && offset >= 0 ? offset : 0;
+  const end = Number.isInteger(limit) && limit >= 0 ? start + limit : undefined;
+  const projected = filtered.slice(start, end);
   return {
-    tasks: tasks.map((task) => {
+    tasks: projected.map((task) => {
       if (task.healthy === false) {
         return {
           taskId: task.taskId ?? null,
@@ -35,6 +49,12 @@ export async function runTaskList({ target, packageRoot } = {}) {
         updatedAt: task.updatedAt,
       };
     }),
+    ...(normalizedPhase ? { phase: normalizedPhase } : {}),
+    ...(active ? { active: true } : {}),
+    offset: start,
+    ...(Number.isInteger(limit) && limit >= 0 ? { limit } : {}),
+    total: filtered.length,
+    hasMore: end !== undefined ? end < filtered.length : false,
   };
 }