@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/commands/action-show.js

@@ -1,9 +1,12 @@
 import { readAction } from "../core/actions.js";
 import { resolveTaskContext } from "../core/task-context.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
 export async function runActionShow({ target, packageRoot, taskId, actionId }) {
-  const ctx = await resolveTaskContext(target, { packageRoot, taskId });
-  return readAction(target, { packageRoot, taskId: ctx.taskId, actionId });
+  return withProjectReadSnapshot(target, async () => {
+    const ctx = await resolveTaskContext(target, { packageRoot, taskId });
+    return readAction(target, { packageRoot, taskId: ctx.taskId, actionId });
+  });
 }
 export function formatActionShowResult(result) {
   return `FORGELOOP ACTION\naction: ${result.actionId}\nstate: ${result.state}\ncapability: ${result.capability}\n`;

package/src/commands/advance.js

@@ -1,10 +1,14 @@
+import { assertCanonicalPersistence } from "../storage/operational-context.js";
 import { advanceWorkState } from "../core/phase.js";
 import { withTaskMutation } from "../core/task-command.js";
 
 export { advanceWorkState };
 
-export async function runAdvance({ target, packageRoot, to, taskId, task, authorityContext, runtimeContext }) {
+export async function runAdvance({ target, packageRoot, to, taskId, task, authorityContext, runtimeContext, persistence = null }) {
   if (!to) throw new Error("--to is required for advance");
+
+  assertCanonicalPersistence(persistence);
+
   return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "advance", async (ctx) => {
     return advanceWorkState(target, to, {
       packageRoot,

package/src/commands/baseline.js

@@ -1,3 +1,4 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import {
   computePersistedPolicyLockData,
   evaluateTargetPolicy,
@@ -18,6 +19,17 @@ function baselineError(code, message) {
   return err;
 }
 
+async function hasActivePolicySnapshot(target, packageRoot) {
+  return withProjectReadSnapshot(target, async () => {
+    const tasks = await discoverTasks(target, packageRoot);
+    for (const task of tasks) {
+      if (task.healthy && task.phase && task.phase !== "COMPLETE" && task.phase !== "BLOCKED"
+        && await readTaskPolicySnapshot(target, task.taskId, packageRoot)) return true;
+    }
+    return false;
+  });
+}
+
 export async function runBaseline({
   target = process.cwd(),
   packageRoot,
@@ -28,17 +40,7 @@ export async function runBaseline({
   const policyEval = await evaluateTargetPolicy({ target, packageRoot });
   let baseline = await readBaseline(target, packageRoot);
 
-  const tasks = await discoverTasks(target, packageRoot);
-  let hasActivePolicyTask = false;
-  for (const t of tasks) {
-    if (t.healthy && t.phase && t.phase !== "COMPLETE" && t.phase !== "BLOCKED") {
-      const snap = await readTaskPolicySnapshot(target, t.taskId, packageRoot);
-      if (snap) {
-        hasActivePolicyTask = true;
-        break;
-      }
-    }
-  }
+  const hasActivePolicyTask = await hasActivePolicySnapshot(target, packageRoot);
 
   if (record) {
     if (hasActivePolicyTask && !policyResetAuthorized) {

package/src/commands/checkpoint-revalidate.js

@@ -0,0 +1,192 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { readContract } from "../core/contract.js";
+import {
+  appendProtocolEvent,
+  validateEventLedger,
+  validateStateLedgerCoherence,
+} from "../core/events.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { currentRepositoryFingerprint } from "../core/repository.js";
+import { resolveTaskContext } from "../core/task-context.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import { assertTaskMutationAllowed } from "../core/task-claim-state.js";
+import { getTaskTransaction, withTaskTransaction } from "../core/transaction.js";
+import {
+  CHECKPOINT_REVALIDATED_EVENT,
+  assertCheckpointRevalidatedDetails,
+  assertRepositoryFingerprint,
+} from "../core/checkpoint-revalidation.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import { sameCanonicalGuideList, resolveEffectiveContractBootstrapRepairAnchor } from "../core/contract-bootstrap-recovery.js";
+import {
+  classifyLoadedWorkState,
+  createWorkState,
+  mutateWorkState,
+  readWorkState,
+} from "../core/work-state.js";
+
+function revalidationError(message, details = {}) {
+  const error = new Error(message);
+  error.code = "E_CHECKPOINT_REVALIDATION_UNSAFE";
+  Object.assign(error, details);
+  return error;
+}
+
+function sameRepositoryFingerprint(left, right) {
+  return left?.branch === right?.branch && left?.head === right?.head;
+}
+
+function assertRouteIdentity(state, contract, route) {
+  if (!route || route.value?.contractFingerprint !== contract.fingerprint
+    || state.routeFingerprint !== route.fingerprint
+    || !sameCanonicalGuideList(state.selectedGuides, route.value.guides)) {
+    throw revalidationError("ROUTED checkpoint route identity cannot be proven safe", {
+      artifacts: [taskArtifactPath(state.taskId, "state"), taskArtifactPath(state.taskId, "route")],
+    });
+  }
+}
+
+async function inspectEligibility(target, packageRoot, taskId) {
+  return withProjectReadSnapshot(target, () => inspectSelectedEligibility(target, packageRoot, taskId));
+}
+
+async function inspectSelectedEligibility(target, packageRoot, taskId) {
+  const state = await readWorkState(target, { packageRoot, taskId });
+  if (!state) throw revalidationError("A persisted work-state checkpoint is required");
+  if (state.phase !== "ROUTED") throw revalidationError(`Checkpoint revalidation supports phase ROUTED, found ${state.phase}`);
+
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) throw revalidationError("Checkpoint revalidation requires a structurally valid event ledger", { errors: ledger.errors });
+  if (ledger.events.some((event) => event.event === "EXECUTION_STARTED")) {
+    throw revalidationError("Checkpoint revalidation is unavailable after execution has started");
+  }
+  const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+  if (coherenceErrors.length > 0) throw revalidationError("Checkpoint revalidation requires coherent state and ledger", { errors: coherenceErrors });
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid || !ownership.mutationAllowed) {
+    throw revalidationError("Checkpoint revalidation cannot bypass invalid task ownership", { errors: ownership.ownershipErrors });
+  }
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (state.contractFingerprint !== contract.fingerprint) {
+    throw revalidationError("Checkpoint contract identity changed; use the contract revision path");
+  }
+  const route = await readPersistedRoute(target, packageRoot, { taskId });
+  assertRouteIdentity(state, contract, route);
+
+  const freshness = await classifyLoadedWorkState({
+    target,
+    state,
+    contractFile: taskArtifactPath(taskId, "contract"),
+  });
+  const repository = freshness.repository;
+  assertRepositoryFingerprint(repository, "current repository fingerprint", { requireHead: true });
+  const reasons = [...new Set(freshness.reasons)].sort();
+  if (reasons.length === 0) {
+    return { state, contract, route, ledger, repository, freshness, alreadyFresh: true };
+  }
+  if (reasons.length !== 1 || reasons[0] !== "REPOSITORY_CHANGED") {
+    throw revalidationError(`Checkpoint freshness is not repository-only: ${reasons.join(", ")}`);
+  }
+  const repairAnchor = resolveEffectiveContractBootstrapRepairAnchor(ledger.events);
+  if (repairAnchor && (repairAnchor.details.contractFingerprint !== contract.fingerprint
+    || repairAnchor.details.routeFingerprint !== route.fingerprint)) {
+    throw revalidationError("Repaired checkpoint identity does not match the current contract and route");
+  }
+  return { state, contract, route, ledger, repository, freshness, repairAnchor, alreadyFresh: false };
+}
+
+function resultFor(taskId, state, repository, event = null, transaction = null, alreadyFresh = false) {
+  return {
+    taskId,
+    revalidated: !alreadyFresh,
+    alreadyFresh,
+    phase: state.phase,
+    previousRevision: event ? event.details.previousStateRevision : state.revision,
+    revalidatedRevision: event ? event.details.revalidatedStateRevision : state.revision,
+    previousRepositoryFingerprint: event?.details.previousRepositoryFingerprint ?? repository,
+    repositoryFingerprint: event?.details.repositoryFingerprint ?? repository,
+    eventSeq: event?.seq ?? null,
+    transactionCommitSeq: transaction?.seq ?? null,
+  };
+}
+
+async function revalidateLocked(target, packageRoot, taskId, transaction) {
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid || !ownership.mutationAllowed) {
+    throw revalidationError("Checkpoint revalidation cannot bypass invalid task ownership", { errors: ownership.ownershipErrors });
+  }
+  await assertTaskMutationAllowed(target, { taskId, packageRoot });
+  const inspected = await inspectEligibility(target, packageRoot, taskId);
+  if (inspected.alreadyFresh) return resultFor(taskId, inspected.state, inspected.repository, null, null, true);
+
+  const before = inspected.state;
+  const previousStateFingerprint = canonicalFingerprint(before);
+  const previousRepositoryFingerprint = structuredClone(before.repositoryFingerprint);
+  const repository = await currentRepositoryFingerprint(target);
+  assertRepositoryFingerprint(repository, "current repository fingerprint", { requireHead: true });
+  if (!sameRepositoryFingerprint(repository, inspected.repository)) {
+    throw revalidationError("Repository identity changed during checkpoint revalidation");
+  }
+  const next = await mutateWorkState(target, {
+    expectedRevision: before.revision,
+    packageRoot,
+    taskId,
+  }, (current) => createWorkState({
+    ...current,
+    repositoryFingerprint: repository,
+    lastUpdated: new Date().toISOString(),
+  }));
+  const details = {
+    phase: next.phase,
+    previousRepositoryFingerprint,
+    repositoryFingerprint: structuredClone(repository),
+    contractFingerprint: next.contractFingerprint,
+    routeFingerprint: next.routeFingerprint,
+    previousStateRevision: before.revision,
+    revalidatedStateRevision: next.revision,
+    previousStateFingerprint,
+    revalidatedStateFingerprint: canonicalFingerprint(next),
+  };
+  assertCheckpointRevalidatedDetails(details);
+  const event = await appendProtocolEvent(target, {
+    taskId,
+    event: CHECKPOINT_REVALIDATED_EVENT,
+    details,
+  }, packageRoot, { taskId });
+  const commitEvent = await appendProtocolEvent(target, {
+    taskId,
+    event: "TRANSACTION_COMMITTED",
+    details: { transactionId: transaction.transactionId, operation: "checkpoint-revalidate" },
+  }, packageRoot, { taskId });
+  return resultFor(taskId, next, repository, event, commitEvent, false);
+}
+
+export async function runCheckpointRevalidate({ target, packageRoot, taskId } = {}) {
+  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  const effectiveTaskId = context.taskId;
+  const initial = await inspectEligibility(target, packageRoot, effectiveTaskId);
+  if (initial.alreadyFresh) return resultFor(effectiveTaskId, initial.state, initial.repository, null, null, true);
+  const nested = Boolean(await getTaskTransaction(target));
+  try {
+    return await withTaskTransaction({
+      target,
+      taskId: effectiveTaskId,
+      operation: "checkpoint-revalidate",
+      packageRoot,
+      recordCommitEvent: false,
+    }, async (transaction) => revalidateLocked(target, packageRoot, effectiveTaskId, transaction));
+  } catch (error) {
+    if (nested || error?.code !== "E_STATE_REVISION_CONFLICT") throw error;
+    // A competing writer may have completed this exact revalidation. Recheck
+    // all eligibility and history after our preparation rolled back; never
+    // replay mutation or convert an unrelated conflict into success.
+    const current = await inspectEligibility(target, packageRoot, effectiveTaskId);
+    if (!current.alreadyFresh) throw error;
+    return resultFor(effectiveTaskId, current.state, current.repository, null, null, true);
+  }
+}
+
+export function formatCheckpointRevalidateResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/complete.js

@@ -1,13 +1,29 @@
 import { runComplete as evaluateAndComplete } from "../core/completion.js";
 import { withTaskMutation } from "../core/task-command.js";
+import { isRecoverableCompletionEvidenceCode } from "../core/completion-recovery.js";
 
 export async function runComplete(options = {}) {
   const target = options.target;
   const packageRoot = options.packageRoot;
   const taskId = options.taskId ?? options.task ?? null;
-  return withTaskMutation(target, { taskId, packageRoot }, "complete", async (ctx) => {
-    return evaluateAndComplete({ ...options, taskId: ctx?.taskId ?? null });
-  });
+  const rejected = new Error("Completion validation rejected");
+  let rejectedResult;
+  try {
+    return await withTaskMutation(target, { taskId, packageRoot }, "complete", async (ctx) => {
+      const result = await evaluateAndComplete({ ...options, taskId: ctx?.taskId ?? null });
+      const recordsEvidenceRecovery = options.persist !== false && result.errors.length > 0
+        && result.errors.every(error => isRecoverableCompletionEvidenceCode(error.code));
+      if (result.status === "REJECTED" && !recordsEvidenceRecovery) {
+        rejectedResult = result;
+        throw rejected;
+      }
+      return result;
+    });
+  } catch (error) {
+    // Return the domain rejection only after its transaction has rolled back.
+    if (error === rejected) return rejectedResult;
+    throw error;
+  }
 }
 
 export function formatCompleteResult(result) {

package/src/commands/context-plan.js

@@ -0,0 +1,38 @@
+import { compileContext } from "../core/context-compiler/compiler.js";
+import { normalizeContextCandidates } from "../core/context-compiler/candidates.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { buildContextQuestionSet } from "../core/decision/question-registry.js";
+import { ensureSemanticDecision } from "../core/decision/service.js";
+
+export async function runContextPlan({ target, packageRoot, taskId, decisionId, profile = "balanced", candidates = [], mandatoryIds = [], provider = null, readOnly = false } = {}) {
+  if (readOnly) return compileContext({ profile, candidates, mandatoryIds });
+  if (target && taskId) {
+    const normalized = normalizeContextCandidates(candidates);
+    const candidateSetFingerprint = canonicalFingerprint(normalized.map((candidate) => ({
+      id: candidate.id, sourceRef: candidate.sourceRef, summary: candidate.summary,
+      required: candidate.required, mandatory: candidate.mandatory,
+    })));
+    const questionSet = buildContextQuestionSet(normalized);
+    const decision = await ensureSemanticDecision({
+      target, packageRoot, taskId, decisionId, provider, allowNetwork: !readOnly,
+      request: {
+        decisionKind: "CONTEXT_PLAN", questionSetId: questionSet.id, questionSet,
+        state: { candidates: normalized.map(({ id, sourceRef, kind, summary, required, mandatory, risk, trust }) => ({ id, sourceRef, kind, summary, required, mandatory, risk, trust })) },
+        candidateIds: normalized.map((candidate) => candidate.id), candidateSetFingerprint,
+      },
+    });
+    return compileContext({ profile, candidates, mandatoryIds, semanticRanker: () => ({ rankedIds: decision.artifact.decision?.rankedIds ?? [], excludedIds: decision.artifact.decision?.excludedIds ?? [] }) });
+  }
+  return compileContext({ profile, candidates, mandatoryIds });
+}
+
+export function formatContextPlanResult(result) {
+  return [
+    `Context plan: ${result.selectedItems}/${result.candidateItems} items`,
+    `Profile: ${result.profile}`,
+    `Selected chars: ${result.selectedChars}/${result.budget.maxChars}`,
+    `Prompt-injection candidates: ${result.promptInjectionIds.length}`,
+    `Fingerprint: ${result.decisionFingerprint}`,
+    "",
+  ].join("\n");
+}

package/src/commands/contract-create.js

@@ -0,0 +1,266 @@
+import { readFile } from "node:fs/promises";
+
+import { createPresetContract } from "../core/contract-presets.js";
+import { contractFingerprint, readContract, validateContract, writeContract } from "../core/contract.js";
+import { appendProtocolEvent, readEvents, validateEventLedger } from "../core/events.js";
+import { isContractBootstrapRepairCandidate } from "../core/contract-bootstrap-recovery.js";
+import { currentRepositoryFingerprint } from "../core/repository.js";
+import { createWorkState, initializeWorkState, readWorkState } from "../core/work-state.js";
+import { ensureWithin, fileExists } from "../core/filesystem.js";
+import { withTaskMutation } from "../core/task-command.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import {
+  buildResumableWorkStateFields,
+  deriveResumePhaseFromLedger,
+} from "../core/resumability.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import { ensureSemanticDecision } from "../core/decision/service.js";
+import { operationalArtifactExists } from "../storage/operational-context.js";
+
+function bootstrapInconsistent(message, candidate = false) {
+  const error = new Error(message);
+  error.code = candidate ? "E_CONTRACT_BOOTSTRAP_REPAIR_AVAILABLE" : "E_CONTRACT_BOOTSTRAP_INCONSISTENT";
+  return error;
+}
+
+async function hasValidatedContractHistory(target, packageRoot, taskId) {
+  if (!target || !packageRoot || !taskId) return false;
+  const events = await readEvents(target, packageRoot, { taskId });
+  return events.some((event) => event.event === "CONTRACT_VALIDATED");
+}
+
+/**
+ * Resolves the reconstruction projection for a task with a validated ledger
+ * whose work-state checkpoint is missing.
+ *
+ * Ownership rule: the existing canonical contract plus the validated
+ * CONTRACT_VALIDATED event are authoritative. Caller-supplied --preset or
+ * --contract-file material is only used to prove fingerprint equivalence; the
+ * preset generator never redefines historical truth. Reconstruction is
+ * recovery, not contract creation.
+ *
+ * Fail-closed rule: the ledger proves which lifecycle milestones happened.
+ * A ROUTE_VALIDATED event with a missing, malformed, or differently-bound
+ * route artifact cannot be downgraded to CONTRACT_READY; that would regress
+ * the lifecycle and allow a later route command to append a duplicate
+ * ROUTE_VALIDATED milestone.
+ */
+async function loadReconstructionEvidence(target, packageRoot, taskId) {
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) {
+    const candidate = isContractBootstrapRepairCandidate(ledger.events, ledger.errors, taskId);
+    const error = bootstrapInconsistent(
+      candidate
+        ? "The exact contract bootstrap defect requires task-repair-contract-bootstrap"
+        : "Existing contract has an inconsistent ledger; cannot overwrite",
+      !!candidate,
+    );
+    error.next = candidate
+      ? `forgeloop task-repair-contract-bootstrap --task ${taskId} --acknowledge-repair --json`
+      : undefined;
+    throw error;
+  }
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (!ledger.events.some((event) => event.event === "CONTRACT_VALIDATED"
+    && event.details?.contractFingerprint === contract.fingerprint)) {
+    throw bootstrapInconsistent("Existing contract is not bound to a valid CONTRACT_VALIDATED event");
+  }
+
+  const routeValidated = ledger.events.some((event) => event.event === "ROUTE_VALIDATED");
+  const route = await readPersistedRoute(target, packageRoot, { taskId }).catch((error) => ({
+    __reconstructionError: error,
+  }));
+  if (routeValidated) {
+    if (route?.__reconstructionError || !route?.fingerprint) {
+      throw bootstrapInconsistent(
+        "Ledger contains ROUTE_VALIDATED but the route artifact is missing or malformed; reconstruction must not downgrade the lifecycle",
+      );
+    }
+    if (route.value?.contractFingerprint !== undefined
+      && route.value.contractFingerprint !== contract.fingerprint) {
+      throw bootstrapInconsistent(
+        "Persisted route artifact is bound to a different contract than the validated contract",
+      );
+    }
+  }
+  const scopedEvents = ledger.events.filter((event) => event.taskId === taskId);
+  const resumedPhase = routeValidated
+    ? (await deriveResumePhaseFromLedger(target, packageRoot, taskId) ?? "ROUTED")
+    : "CONTRACT_READY";
+  const projection = buildResumableWorkStateFields({ events: scopedEvents, resumedPhase });
+  return { ledger, contract, route: routeValidated ? route : null, projection };
+}
+
+async function reconstructFromExistingContract(target, packageRoot, taskId, requestedFingerprint = null) {
+  const { contract, route, projection } = await loadReconstructionEvidence(target, packageRoot, taskId);
+  if (requestedFingerprint !== null && requestedFingerprint !== contract.fingerprint) {
+    throw bootstrapInconsistent("A different contract already exists for this task; contract-create is not contract-revise");
+  }
+  const repositoryFingerprint = await currentRepositoryFingerprint(target);
+  const reconstructedState = createWorkState({
+    taskId,
+    contractFingerprint: contract.fingerprint,
+    ...(route ? { routeFingerprint: route.fingerprint } : {}),
+    repositoryFingerprint,
+    phase: projection.phase,
+    selectedGuides: route ? [...route.value.guides] : [],
+    requiredGates: [],
+    satisfiedGates: [],
+    completedSteps: projection.completedSteps,
+    pendingSteps: projection.pendingSteps,
+    ...(projection.verificationCycle !== undefined ? { verificationCycle: projection.verificationCycle } : {}),
+    requiredArtifacts: [],
+    checks: [],
+    failures: [],
+    blockers: [],
+    verificationEvidence: [],
+  });
+  await initializeWorkState(target, reconstructedState, { packageRoot, taskId });
+  return {
+    taskId,
+    phase: projection.phase,
+    idempotent: true,
+    contractFingerprint: contract.fingerprint,
+    reconstructed: true,
+  };
+}
+
+export async function runContractCreate({ target, packageRoot, taskId, task, contractFile = null, preset = null, semanticProvider = null } = {}) {
+  if (!preset && !contractFile) throw new Error("contract-create requires --preset or --contract-file");
+  if (preset && contractFile) throw new Error("contract-create accepts either --preset or --contract-file, not both");
+
+  const effectiveTaskId = taskId ?? task;
+  const hasCanonicalContract = await hasValidatedContractHistory(target, packageRoot, effectiveTaskId);
+  if (target && packageRoot && effectiveTaskId && !hasCanonicalContract) {
+    await ensureSemanticDecision({
+      target, packageRoot, taskId: effectiveTaskId, provider: semanticProvider,
+      request: {
+        decisionKind: "CONTRACT_APPLICABILITY", questionSetId: "contract-v1",
+        state: { source: preset ? "preset" : "contract-file", preset: preset ?? null },
+      },
+    });
+  }
+  return withTaskMutation(target, { taskId: effectiveTaskId, packageRoot }, "contract-create", async (ctx) => {
+    const events = await readEvents(target, packageRoot, { taskId: ctx.taskId });
+    if (!events.some((event) => event.event === "DISCOVERY_STARTED")) {
+      const error = new Error("Contract creation requires completed discovery");
+      error.code = "E_DISCOVERY_REQUIRED";
+      throw error;
+    }
+    const existingState = await readWorkState(target, { packageRoot, taskId: ctx.taskId });
+    if (existingState) {
+      if (existingState.phase !== "CONTRACT_READY") throw new Error("Contract already exists beyond the contract-ready phase");
+      const existingContract = await readContract(target, packageRoot, { taskId: ctx.taskId });
+      const existingLedger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+      if (!existingLedger.valid) {
+        const candidate = isContractBootstrapRepairCandidate(existingLedger.events, existingLedger.errors, ctx.taskId);
+        const error = bootstrapInconsistent(
+          candidate
+            ? "The exact contract bootstrap defect requires task-repair-contract-bootstrap"
+            : "Existing contract checkpoint has an invalid event ledger",
+          !!candidate,
+        );
+        error.next = candidate ? `forgeloop task-repair-contract-bootstrap --task ${ctx.taskId} --acknowledge-repair --json` : undefined;
+        throw error;
+      }
+      if (existingState.contractFingerprint !== existingContract.fingerprint
+        || !existingLedger.events.some((event) => event.event === "CONTRACT_VALIDATED"
+          && event.details?.contractFingerprint === existingContract.fingerprint)) {
+        throw bootstrapInconsistent("Existing contract checkpoint is not bound to its validated contract event");
+      }
+      return { taskId: ctx.taskId, phase: existingState.phase, idempotent: true, contractFingerprint: existingContract.fingerprint };
+    }
+
+    // Reconstruction precedes preset generation: when the task already has a
+    // canonical contract, recover from it without generating a replacement
+    // candidate first. The requested preset/file contract is only compared by
+    // fingerprint to prove idempotent equivalence; it never redefines the
+    // canonical historical contract.
+    const existingContractPath = taskArtifactPath(ctx.taskId, "contract");
+    if (operationalArtifactExists(target, existingContractPath)
+      ?? await fileExists(ensureWithin(target, existingContractPath)).catch(() => false)) {
+      const existingContract = await readContract(target, packageRoot, { taskId: ctx.taskId });
+      const existingLedger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+      const validatedContractEvents = existingLedger.events.filter(
+        (event) => event.event === "CONTRACT_VALIDATED",
+      );
+
+      // task-create persists the proposed contract before contract-create has
+      // validated it. That artifact is not yet canonical history, so preserve
+      // ordinary first-time contract creation when no CONTRACT_VALIDATED event
+      // exists. Once validation history exists, reconstruction must be
+      // authoritative and fail closed on any binding mismatch.
+      if (validatedContractEvents.length > 0) {
+        if (!validatedContractEvents.some(
+          (event) => event.details?.contractFingerprint === existingContract.fingerprint,
+        )) {
+          throw bootstrapInconsistent("Existing contract is not bound to a valid CONTRACT_VALIDATED event");
+        }
+
+        let requestedFingerprint = null;
+        if (contractFile) {
+          const source = ensureWithin(target, contractFile);
+          if (await fileExists(source).catch(() => false)) {
+            try {
+              const candidate = { ...JSON.parse(await readFile(source, "utf8")), taskId: ctx.taskId };
+              await validateContract(candidate, packageRoot);
+              requestedFingerprint = contractFingerprint(candidate);
+            } catch {
+              requestedFingerprint = undefined;
+            }
+          }
+        }
+        // A preset selector is not historical contract authority. If the
+        // caller supplied a replacement file, compare it; otherwise recover
+        // the persisted contract independently of current preset generation.
+        return reconstructFromExistingContract(
+          target,
+          packageRoot,
+          ctx.taskId,
+          requestedFingerprint ?? null,
+        );
+      }
+    }
+
+    let contract;
+    if (preset) {
+      contract = createPresetContract({ taskId: ctx.taskId, preset, claims: ctx.descriptor.writeClaims });
+    } else {
+      const source = ensureWithin(target, contractFile);
+      if (!(await fileExists(source))) throw new Error(`Specified contract file not found: ${contractFile}`);
+      contract = JSON.parse(await readFile(source, "utf8"));
+      contract = { ...contract, taskId: ctx.taskId };
+    }
+    await validateContract(contract, packageRoot);
+    const fingerprint = contractFingerprint(contract);
+
+    await writeContract(target, contract, packageRoot, { taskId: ctx.taskId });
+    const repositoryFingerprint = await currentRepositoryFingerprint(target);
+    await initializeWorkState(target, createWorkState({
+      taskId: ctx.taskId,
+      contractFingerprint: fingerprint,
+      repositoryFingerprint,
+      phase: "CONTRACT_READY",
+      selectedGuides: [],
+      requiredGates: [],
+      satisfiedGates: [],
+      completedSteps: ["contract"],
+      pendingSteps: ["route", "planning", "implementation", "verification"],
+      requiredArtifacts: [],
+      checks: [],
+      failures: [],
+      blockers: [],
+      verificationEvidence: [],
+    }), { packageRoot, taskId: ctx.taskId });
+    await appendProtocolEvent(target, {
+      taskId: ctx.taskId,
+      event: "CONTRACT_VALIDATED",
+      details: { contractFingerprint: fingerprint },
+    }, packageRoot, { taskId: ctx.taskId });
+    return { taskId: ctx.taskId, phase: "CONTRACT_READY", idempotent: false, contractFingerprint: fingerprint };
+  });
+}
+
+export function formatContractCreateResult(result) {
+  return `phase: ${result.phase}\n${result.idempotent ? "idempotent: true\n" : ""}`;
+}