@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/commands/gate-revalidate.js

@@ -0,0 +1,137 @@
+import { lstat } from "node:fs/promises";
+
+import { optionalConfig } from "../core/preflight-loaders.js";
+import { readContract } from "../core/contract.js";
+import { appendProtocolEvent, validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
+import { ensureWithin, isPathWithin, readBytes, realpathWithTransientWindowsRetry } from "../core/filesystem.js";
+import { sha256 } from "../core/manifest.js";
+import { requiredGatesForGuides } from "../core/guide-metadata.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { staleReasons } from "../core/next-action-artifacts.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import { taskGatePath, taskArtifactPath } from "../core/task-paths.js";
+import { withTaskMutation } from "../core/task-command.js";
+import { readWorkState } from "../core/work-state.js";
+import { stateIdentityErrors } from "../core/completion-relationships.js";
+import { persistGate, readGateIfPresent, validateGateArtifacts } from "../core/gate-artifact.js";
+import {
+  GATE_REVALIDATED_EVENT,
+  assertGateRevalidatedDetails,
+} from "../core/gate-provenance.js";
+
+const POST_EXECUTION_PHASES = new Set([
+  "EXECUTING", "VERIFYING", "DIAGNOSING", "CORRECTING", "REVIEWING",
+]);
+
+function revalidationError(message, code = "E_GATE_REVALIDATION_UNSAFE", artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+async function hashGateArtifact(target, relativePath) {
+  let artifactPath;
+  try {
+    artifactPath = ensureWithin(target, relativePath);
+    const stat = await lstat(artifactPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("artifact must be a regular file");
+    const rootReal = await realpathWithTransientWindowsRetry(target);
+    const artifactReal = await realpathWithTransientWindowsRetry(artifactPath);
+    if (!isPathWithin(rootReal, artifactReal)) throw new Error("artifact resolves outside the project");
+    return { path: relativePath, sha256: sha256(await readBytes(artifactReal)) };
+  } catch (cause) {
+    throw revalidationError(`Cannot refresh gate artifact ${relativePath}: ${cause.message}`, "E_GATE_REVALIDATION_UNSAFE", [relativePath]);
+  }
+}
+
+async function assertCurrentGateBinding(target, packageRoot, taskId, state, gate) {
+  const contract = await readContract(target, packageRoot, { taskId });
+  const route = await readPersistedRoute(target, packageRoot, { taskId });
+  const identityErrors = stateIdentityErrors({ contract, route, state });
+  if (identityErrors.length > 0) {
+    throw revalidationError(
+      "Gate revalidation requires coherent current contract, route, state, and selected guides",
+      "E_GATE_REVALIDATION_UNSAFE",
+      [taskArtifactPath(taskId, "contract"), taskArtifactPath(taskId, "route"), taskArtifactPath(taskId, "state")],
+    );
+  }
+  const routeStale = staleReasons(state, contract, route);
+  if (routeStale.length > 0) {
+    throw revalidationError("Gate revalidation cannot repair stale contract or route identity", "E_GATE_REVALIDATION_UNSAFE", routeStale.flatMap((reason) => reason.artifacts));
+  }
+  const config = await optionalConfig(target, packageRoot, []);
+  const required = [...new Set([
+    ...(await requiredGatesForGuides(route.value.guides, packageRoot)),
+    ...(config.requiredGates ?? []),
+  ])];
+  if (!required.includes(gate)) {
+    throw revalidationError(`Gate is not required by the active route: ${gate}`, "E_GATE_NOT_REQUIRED", [taskArtifactPath(taskId, "route")]);
+  }
+  return { contract, route };
+}
+
+export async function runGateRevalidate({ target, packageRoot, taskId, gate, acknowledgeStale = false } = {}) {
+  if (!acknowledgeStale) {
+    throw revalidationError("gate-revalidate requires --acknowledge-stale", "E_GATE_REVALIDATION_ACK_REQUIRED");
+  }
+  if (typeof gate !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(gate)) {
+    throw revalidationError(`Invalid gate name: ${gate}`, "E_GATE_INVALID");
+  }
+  return withTaskMutation(target, { taskId, packageRoot }, "gate-revalidate", async (ctx) => {
+    const state = await readWorkState(target, { packageRoot, taskId: ctx.taskId });
+    if (!state || !POST_EXECUTION_PHASES.has(state.phase)) {
+      throw revalidationError(
+        `gate-revalidate is only available for post-execution repair phases; found ${state?.phase ?? "no phase"}`,
+        "E_GATE_REVALIDATION_PHASE_INVALID",
+        [taskArtifactPath(ctx.taskId, "state")],
+      );
+    }
+    const ledger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+    if (!ledger.valid) throw revalidationError("Gate revalidation requires a valid append-only event ledger", "E_EVENT_INVALID", ledger.errors);
+    const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+    if (coherenceErrors.length > 0) throw revalidationError("Gate revalidation requires coherent state and ledger", "E_PHASE_CHRONOLOGY_INVALID", coherenceErrors);
+    const ownership = await resolveTaskClaimState(target, { taskId: ctx.taskId, packageRoot });
+    if (!ownership.ownershipValid || !ownership.mutationAllowed || ownership.claimState !== "ACTIVE") {
+      throw revalidationError("Gate revalidation cannot bypass active task claim ownership", "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT", ownership.ownershipErrors);
+    }
+    await assertCurrentGateBinding(target, packageRoot, ctx.taskId, state, gate);
+    const existing = await readGateIfPresent(target, gate, packageRoot, { taskId: ctx.taskId });
+    if (!existing || existing.value.status !== "satisfied") {
+      throw revalidationError("Only an existing satisfied gate can be revalidated", "E_GATE_UNVERIFIED", [taskGatePath(ctx.taskId, gate)]);
+    }
+    const stale = await validateGateArtifacts(target, existing.value, packageRoot);
+    if (stale.length === 0) {
+      throw revalidationError("Gate artifacts are already fresh; no revalidation event is required", "E_GATE_REVALIDATION_NOT_STALE", [existing.path]);
+    }
+    const refreshedArtifacts = [];
+    for (const artifact of existing.value.artifacts ?? []) refreshedArtifacts.push(await hashGateArtifact(target, artifact.path));
+    const refreshedGate = { ...existing.value, artifacts: refreshedArtifacts };
+    const persisted = await persistGate(target, refreshedGate, packageRoot, { taskId: ctx.taskId });
+    const details = {
+      gate,
+      previousGateFingerprint: existing.fingerprint,
+      gateFingerprint: persisted.fingerprint,
+      stalePaths: stale.map((entry) => entry.path).sort(),
+    };
+    assertGateRevalidatedDetails(details);
+    const event = await appendProtocolEvent(target, {
+      taskId: ctx.taskId,
+      event: GATE_REVALIDATED_EVENT,
+      details,
+    }, packageRoot, { taskId: ctx.taskId });
+    return {
+      taskId: ctx.taskId,
+      gate,
+      stalePaths: details.stalePaths,
+      gateFingerprint: persisted.fingerprint,
+      eventSeq: event.seq,
+      transactionCommitSeq: event.seq + 1,
+      path: persisted.path ?? persisted.relativePath ?? taskGatePath(ctx.taskId, gate),
+    };
+  });
+}
+
+export function formatGateRevalidateResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/model-route.js

@@ -0,0 +1,32 @@
+import { projectModelRoute } from "../core/model-router/router.js";
+import { resolveRequiredSemanticDecision } from "../core/decision/resolver.js";
+import { readCurrentDecisionBindings } from "../core/decision/task-bindings.js";
+
+export async function runModelRoute({ target, packageRoot, taskId, decisionId, workType, surfaces, risks, platforms, behaviorChange, executableChange, generationRequired, architectureChange, ambiguity, semanticRecommendation, contract } = {}) {
+  if (target && taskId) {
+    const bindings = await readCurrentDecisionBindings(target, packageRoot, taskId);
+    const decision = await resolveRequiredSemanticDecision({
+      target, packageRoot, taskId, decisionId, decisionKind: "MODEL_ROUTE", currentBindings: bindings,
+    });
+    semanticRecommendation = decision.decision;
+  }
+  return projectModelRoute({
+    input: {
+      workType,
+      surfaces,
+      risks,
+      platforms,
+      behaviorChange,
+      executableChange,
+      generationRequired,
+      architectureChange,
+      ambiguity,
+      contract,
+    },
+    semanticRecommendation,
+  });
+}
+
+export function formatModelRouteResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/route.js

@@ -1,13 +1,104 @@
 import { evaluateRoute } from "../core/router.js";
-import { persistRoute } from "../core/route-artifact.js";
+import { persistRoute, readPersistedRoute } from "../core/route-artifact.js";
 import { readContract } from "../core/contract.js";
 import { readConfig } from "../core/config.js";
+import { appendProtocolEvent, readEvents } from "../core/events.js";
 import { detectProjectEvidence } from "../core/project-detection.js";
-import { withTaskMutation } from "../core/task-command.js";
+import { withResolvedTask, withTaskMutation } from "../core/task-command.js";
+import { advanceWorkState } from "../core/phase.js";
+import { mutateWorkState, readWorkState } from "../core/work-state.js";
+import { buildExecutionProfileQuestionSet, buildRouteQuestionSet } from "../core/decision/question-registry.js";
+import { ensureSemanticDecision } from "../core/decision/service.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import {
+  resolveEffectiveContractBootstrapRepairAnchor,
+} from "../core/contract-bootstrap-recovery.js";
 
-export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange, executionProfile = null, taskId, task }) {
-  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "route", async (ctx) => {
-    const effectiveTaskId = ctx?.taskId ?? null;
+function canAppendRepairedRouteWitness({ stateBefore, marker, previousPersistedRouteFingerprint, persistedRoute }) {
+  if (previousPersistedRouteFingerprint === null) {
+    return stateBefore.phase === "CONTRACT_READY"
+      && marker.details.reconstructedPhase === "CONTRACT_READY"
+      && marker.details.routeFingerprint === null;
+  }
+  return persistedRoute.fingerprint !== previousPersistedRouteFingerprint
+    && persistedRoute.value.contractFingerprint === marker.details.contractFingerprint;
+}
+
+function canAppendCanonicalRouteWitness({ stateBefore, previousPersistedRouteFingerprint, persistedRoute }) {
+  return stateBefore?.phase === "ROUTED"
+    && previousPersistedRouteFingerprint !== null
+    && persistedRoute.fingerprint !== previousPersistedRouteFingerprint
+    && stateBefore.contractFingerprint === persistedRoute.value.contractFingerprint;
+}
+
+async function appendRouteWitness({ target, packageRoot, taskId, stateBefore, previousPersistedRouteFingerprint, persistedRoute }) {
+  if (!stateBefore) return;
+  const events = await readEvents(target, packageRoot, { taskId });
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+  const canAppend = anchor
+    ? canAppendRepairedRouteWitness({
+      stateBefore,
+      marker: anchor.sourceMarker,
+      previousPersistedRouteFingerprint,
+      persistedRoute,
+    })
+    : canAppendCanonicalRouteWitness({ stateBefore, previousPersistedRouteFingerprint, persistedRoute });
+  if (!canAppend) return;
+  await appendProtocolEvent(target, {
+    taskId,
+    event: "ROUTE_REBOUND",
+    details: {
+      routeFingerprint: persistedRoute.fingerprint,
+      contractFingerprint: persistedRoute.value.contractFingerprint,
+      previousRouteFingerprint: previousPersistedRouteFingerprint,
+    },
+  }, packageRoot, { taskId });
+}
+
+async function persistRoutedState({ target, packageRoot, taskId, route, transaction }) {
+  const stateBefore = await readWorkState(target, { packageRoot, taskId });
+  let previousPersistedRouteFingerprint = null;
+  try {
+    previousPersistedRouteFingerprint = (await readPersistedRoute(target, packageRoot, { taskId })).fingerprint;
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+  let contractFingerprint;
+  try {
+    contractFingerprint = (await readContract(target, packageRoot, { taskId })).fingerprint;
+  } catch {
+    contractFingerprint = undefined;
+  }
+  const persistedRoute = await persistRoute(target, route, packageRoot, { contractFingerprint, taskId });
+  const state = await readWorkState(target, { packageRoot, taskId });
+  if (state?.phase === "CONTRACT_READY") {
+    await mutateWorkState(target, {
+      packageRoot,
+      taskId,
+      expectedRevision: state.revision ?? 0,
+    }, () => ({
+      ...state,
+      routeFingerprint: persistedRoute.fingerprint,
+      selectedGuides: [...persistedRoute.value.guides],
+    }));
+    await advanceWorkState(target, "ROUTED", { packageRoot, taskId });
+  }
+  if (transaction?.operation === "route") {
+    await appendRouteWitness({
+      target,
+      packageRoot,
+      taskId,
+      stateBefore,
+      previousPersistedRouteFingerprint,
+      persistedRoute,
+    });
+  }
+}
+
+export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange, executionProfile = null, taskId, task, semanticProvider = null, provider = null }) {
+  return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (context) => {
+    const effectiveTaskId = context?.taskId ?? null;
+    const effectiveSemanticProvider = semanticProvider ?? provider;
     let contract = null;
     try {
       contract = (await readContract(target, packageRoot, { taskId: effectiveTaskId })).value;
@@ -21,9 +112,9 @@ export async function runRoute({ target, packageRoot, workType, surfaces, risks,
       if (error.code !== "ARTIFACT_MISSING") throw error;
     }
     const projectEvidence = target
-      ? await detectProjectEvidence(target, { claims: ctx?.descriptor?.writeClaims ?? [] })
+      ? await detectProjectEvidence(target, { claims: context?.descriptor?.writeClaims ?? [] })
       : null;
-    const route = evaluateRoute({
+    const routeInput = {
       workType,
       surfaces,
       risks,
@@ -31,22 +122,59 @@ export async function runRoute({ target, packageRoot, workType, surfaces, risks,
       behaviorChange,
       executableChange,
       ...(projectEvidence ? { projectEvidence } : {}),
-    }, {
+    };
+    const deterministicRoute = evaluateRoute(routeInput, {
       contract,
-      taskDescriptor: ctx?.descriptor ?? null,
+      taskDescriptor: context?.descriptor ?? null,
       configuredProfile,
       requestedProfile: executionProfile,
     });
-    if (target && packageRoot) {
-      let contractFingerprint;
-      try {
-        contractFingerprint = (await readContract(target, packageRoot, { taskId: effectiveTaskId })).fingerprint;
-      } catch {
-        contractFingerprint = undefined;
-      }
-      await persistRoute(target, route, packageRoot, { contractFingerprint, taskId: effectiveTaskId });
+    let semanticRecommendation = null;
+    if (target && packageRoot && effectiveTaskId) {
+      await ensureSemanticDecision({
+        target, packageRoot, taskId: effectiveTaskId, provider: effectiveSemanticProvider,
+        request: { decisionKind: "INTAKE", questionSetId: "intake-v1", state: { routeInput: deterministicRoute.input } },
+      });
+      const questionSet = buildRouteQuestionSet(deterministicRoute.guides);
+      const routeDecision = await ensureSemanticDecision({
+        target, packageRoot, taskId: effectiveTaskId, provider: effectiveSemanticProvider,
+        request: {
+          decisionKind: "ROUTE", questionSetId: questionSet.id, questionSet,
+          state: { routeInput: deterministicRoute.input, eligibleGuides: deterministicRoute.guides.map((guide) => ({ id: guide, reasons: deterministicRoute.reasons[guide] })) },
+          candidateIds: deterministicRoute.guides,
+          candidateSetFingerprint: canonicalFingerprint(deterministicRoute.guides),
+        },
+      });
+      const profileQuestionSet = buildExecutionProfileQuestionSet();
+      const profileDecision = await ensureSemanticDecision({
+        target, packageRoot, taskId: effectiveTaskId, provider: effectiveSemanticProvider,
+        request: {
+          decisionKind: "EXECUTION_PROFILE", questionSetId: profileQuestionSet.id, questionSet: profileQuestionSet,
+          state: {
+            routeInput: deterministicRoute.input,
+            deterministicFloor: deterministicRoute.executionProfile.floor,
+            requestedProfile: deterministicRoute.executionProfile.requested,
+          },
+        },
+      });
+      semanticRecommendation = {
+        guideRelevance: routeDecision.artifact.decision,
+        executionProfile: profileDecision.artifact.decision,
+      };
     }
-    return route;
+    const route = evaluateRoute(routeInput, {
+      contract,
+      taskDescriptor: context?.descriptor ?? null,
+      configuredProfile,
+      requestedProfile: executionProfile,
+      semanticRecommendation,
+    });
+    return withTaskMutation(target, { taskId: effectiveTaskId, packageRoot }, "route", async (ctx) => {
+      if (target && packageRoot) {
+        await persistRoutedState({ target, packageRoot, taskId: effectiveTaskId, route, transaction: ctx?.transaction });
+      }
+      return route;
+    });
   });
 }
 

package/src/commands/semantic-plan.js

@@ -0,0 +1,17 @@
+import { runSemanticPlan as projectPlan } from "../core/semantic-planning/service.js";
+import { resolveRequiredSemanticDecision } from "../core/decision/resolver.js";
+import { readCurrentDecisionBindings } from "../core/decision/task-bindings.js";
+
+export async function runSemanticPlan({ target, packageRoot, taskId, decisionId, kind, input, semanticRecommendation } = {}) {
+  if (target && taskId) {
+    const decisionKind = { failure: "FAILURE_TRIAGE", diagnosis: "DIAGNOSIS_PRIORITY", review: "REVIEW_PLAN" }[kind];
+    const bindings = await readCurrentDecisionBindings(target, packageRoot, taskId);
+    const decision = await resolveRequiredSemanticDecision({ target, packageRoot, taskId, decisionId, decisionKind, currentBindings: bindings });
+    semanticRecommendation = decision.decision;
+  }
+  return projectPlan({ kind, input, semanticRecommendation });
+}
+
+export function formatSemanticPlanResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

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`;
+}