@cassiomc1/forgeloop 1.10.0 → 1.10.2

package/src/core/next-action-planned-phase.js

@@ -0,0 +1,51 @@
+import { taskArtifactPath } from "./task-paths.js";
+import { evaluateStartExecutionPrerequisites, PREFLIGHT_ROUTE_IDENTITY_ERROR_MESSAGE } from "./execution-prerequisites.js";
+import { NEXT_ACTIONS, commandFor, decision, result } from "./next-action-model.js";
+import { artifactError } from "./next-action-artifacts.js";
+import { projectStructuralQualityStatus } from "./structural-quality/service.js";
+import { structuralQualityOptionalActions } from "./next-action-quality-guidance.js";
+
+export async function resolvePlannedPhase({ target, packageRoot, explicitTaskId, state, runtimeContext, context, preflightArtifact }) {
+    const quality = await projectStructuralQualityStatus({ target, packageRoot, taskId: explicitTaskId ?? state.taskId, runtimeContext });
+    if (quality.mode === "gate" && quality.baseline.status !== "OBSERVED") {
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.CAPTURE_STRUCTURAL_QUALITY_BASELINE,
+        commands: [commandFor(NEXT_ACTIONS.CAPTURE_STRUCTURAL_QUALITY_BASELINE).replace("<id>", state.taskId)],
+        reasons: [artifactError("E_STRUCTURAL_QUALITY_BASELINE_MISSING", "Gate mode requires a structural-quality baseline before execution", [quality.baseline.artifactRef ?? taskArtifactPath(state.taskId, "structuralQuality")])],
+        requiredArtifacts: [taskArtifactPath(state.taskId, "structuralQuality")],
+      });
+    }
+    const prerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot, taskId: explicitTaskId, runtimeContext });
+    if (prerequisites.errors.length > 0) {
+      const preflightOnly = prerequisites.errors.every((error) => error.code.startsWith("E_PREFLIGHT_")
+        || (error.code === "E_PHASE_CHRONOLOGY_INVALID"
+          && error.message === PREFLIGHT_ROUTE_IDENTITY_ERROR_MESSAGE));
+      if (preflightOnly) {
+        return result({
+          ...context,
+          nextAction: NEXT_ACTIONS.RUN_PREFLIGHT,
+          reasons: prerequisites.errors,
+          commands: [commandFor(NEXT_ACTIONS.RUN_PREFLIGHT)],
+          requiredArtifacts: prerequisites.requiredArtifacts,
+          missingArtifacts: preflightArtifact.missingArtifacts,
+        });
+      }
+      const routeOnly = prerequisites.errors.every((error) => error.code === "E_ROUTE_STALE" || error.code === "E_ROUTE_GUIDE_MISMATCH");
+      return result({
+        ...context,
+        nextAction: routeOnly ? NEXT_ACTIONS.RESOLVE_STALE_ROUTE : NEXT_ACTIONS.RESOLVE_BLOCKER,
+        reasons: prerequisites.errors,
+        requiredArtifacts: prerequisites.requiredArtifacts,
+        missingArtifacts: preflightArtifact.missingArtifacts,
+      });
+    }
+    return decision(
+      context,
+      NEXT_ACTIONS.START_EXECUTION,
+      artifactError("PHASE_PLANNED", "The persisted preflight is READY"),
+      [],
+      [],
+      structuralQualityOptionalActions(quality, state.taskId),
+    );
+  }

package/src/core/next-action-quality-guidance.js

@@ -0,0 +1,19 @@
+import { NEXT_ACTIONS } from "./next-action-model.js";
+
+export function structuralQualityOptionalActions(quality, taskId) {
+  if (quality?.mode !== "observe") return [];
+  if (quality.baseline?.status !== "OBSERVED") {
+    return [{
+      action: NEXT_ACTIONS.CAPTURE_STRUCTURAL_QUALITY_BASELINE,
+      command: `forgeloop quality-baseline --task ${taskId} --json`,
+    }];
+  }
+  if (quality.freshness === "STALE" || quality.current?.verificationCycle === null
+    || quality.current?.verificationCycle === undefined) {
+    return [{
+      action: NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY,
+      command: `forgeloop quality-verify --task ${taskId} --json`,
+    }];
+  }
+  return [];
+}

package/src/core/next-action-recovery-phases.js

@@ -0,0 +1,97 @@
+import { validateEventLedger } from "./events.js";
+import { NEXT_ACTIONS, commandFor, decision, recordDiagnosisCommandSpec, recordInterventionCommandSpec, result } from "./next-action-model.js";
+import { artifactError } from "./next-action-artifacts.js";
+import { resolveCurrentCycleDiagnostic } from "./diagnostic-projection.js";
+import { buildTaskReflection } from "./reflection.js";
+import { evaluateProgress, PROGRESS_STATUS } from "./progress.js";
+
+export async function resolveDiagnosingPhase({ target, packageRoot, normalized, state, context, eventsRel, requiredArtifacts, stateRel }) {
+    const ledger = await validateEventLedger(target, packageRoot, { taskId: normalized.taskId ?? null });
+    const cycle = state.verificationCycle ?? 1;
+    const diagEvent = resolveCurrentCycleDiagnostic(ledger.events, state.taskId, cycle);
+    if (!diagEvent) {
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.RECORD_DIAGNOSIS,
+        reasons: [
+          artifactError(
+            "E_DIAGNOSIS_REQUIRED",
+            "Current correction cycle has no append-only diagnosis record.",
+            [eventsRel],
+          ),
+        ],
+        commandSpecs: [recordDiagnosisCommandSpec()],
+        requiredArtifacts: [...requiredArtifacts, eventsRel],
+      });
+    }
+    const progress = evaluateProgress({ state, events: ledger.events });
+    if (progress.status === PROGRESS_STATUS.STALLED) {
+      let oscillating = false;
+      try {
+        const reflection = await buildTaskReflection({ target, packageRoot, taskId: normalized.taskId ?? null });
+        oscillating = reflection.oscillation.detected;
+      } catch {
+        // Reflection is advisory guidance; stall handling must not depend on it.
+      }
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.CHANGE_STRATEGY,
+        reasons: [
+          artifactError(
+            "E_PROGRESS_STALLED",
+            "The current correction strategy has no new diagnostic information.",
+            [stateRel, eventsRel],
+          ),
+        ],
+        progress,
+        diagnosticGuidance: {
+          action: oscillating ? NEXT_ACTIONS.INTRODUCE_NEW_OBSERVATION : NEXT_ACTIONS.REQUIRE_NEW_DIAGNOSTIC_INFORMATION,
+          signals: oscillating ? ["OSCILLATING_STRATEGY"] : ["NO_INFORMATION_GAIN", ...progress.signals.map((signal) => signal.code)],
+          errorCodes: oscillating ? ["E_STRATEGY_OSCILLATION", "E_PROGRESS_STALLED"] : ["E_PROGRESS_STALLED"],
+        },
+        requiredArtifacts,
+      });
+    }
+    return result({
+      ...context,
+      nextAction: NEXT_ACTIONS.CORRECT,
+      commands: [commandFor(NEXT_ACTIONS.CORRECT)],
+      reasons: [
+        artifactError("PHASE_DIAGNOSING", "The persisted diagnosis hypothesis permits correction"),
+      ],
+      ...(progress.status === PROGRESS_STATUS.WATCH ? { progress } : {}),
+      requiredArtifacts,
+    });
+  }
+
+export async function resolveCorrectingPhase({ target, packageRoot, normalized, state, context, requiredArtifacts }) {
+    const ledgerForCorrection = await validateEventLedger(target, packageRoot, { taskId: normalized.taskId ?? null });
+    const correctionCycle = state.verificationCycle ?? 1;
+    const hasStructuredCase = ledgerForCorrection.events.some(
+      (event) => event.event === "DIAGNOSTIC_CASE_RECORDED"
+        && event.taskId === state.taskId
+        && event.details?.verificationCycle === correctionCycle,
+    );
+    const hasIntervention = ledgerForCorrection.events.some(
+      (event) => event.event === "INTERVENTION_RECORDED"
+        && event.taskId === state.taskId
+        && event.details?.verificationCycle === correctionCycle,
+    );
+    if (hasStructuredCase && !hasIntervention) {
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.ENTER_VERIFYING,
+        reasons: [
+          artifactError("PHASE_CORRECTING", "A structured diagnostic case is awaiting a recorded intervention"),
+        ],
+        diagnosticGuidance: {
+          action: NEXT_ACTIONS.RECORD_INTERVENTION,
+          signals: ["INTERVENTION_NOT_BOUND_TO_HYPOTHESIS"],
+          errorCodes: [],
+          commandSpecs: [recordInterventionCommandSpec(normalized.taskId)],
+        },
+        requiredArtifacts,
+      });
+    }
+    return decision(context, NEXT_ACTIONS.ENTER_VERIFYING, artifactError("PHASE_CORRECTING", "Correction is ready for verification"));
+  }

package/src/core/next-action-refresh.js

@@ -0,0 +1,20 @@
+import { validateEventLedger } from "./events.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { directCommandSpec } from "./next-action-model.js";
+
+/** Offer checkpoint removal only before execution, with valid blocked chronology. */
+export async function preExecutionRefreshGuidance({ target, packageRoot, state, contract }) {
+  if (!["ROUTED", "DESIGNING", "PLANNED"].includes(state.phase)) return {};
+  const ledger = await validateEventLedger(target, packageRoot, { taskId: state.taskId });
+  if (!ledger.valid || ledger.events.some((entry) => entry.event === "EXECUTION_STARTED")) return {};
+  const lastPreflight = ledger.events.filter((entry) => ["PREFLIGHT_READY", "PREFLIGHT_BLOCKED"].includes(entry.event)).at(-1);
+  if (lastPreflight?.event !== "PREFLIGHT_BLOCKED") return {};
+  let route;
+  try { route = await readPersistedRoute(target, packageRoot, { taskId: state.taskId }); }
+  catch { return {}; }
+  if (route.value.contractFingerprint !== contract.fingerprint) return {};
+  return {
+    commands: [`forgeloop clear-state --task ${state.taskId}`, `forgeloop preflight --task ${state.taskId}`],
+    commandSpecs: [directCommandSpec("clear-state", state.taskId), directCommandSpec("preflight", state.taskId)],
+  };
+}

package/src/core/next-action-review-phase.js

@@ -0,0 +1,189 @@
+import { readJsonArtifact } from "./artifacts.js";
+import { evaluateCompletion } from "./completion.js";
+import { validateReceipt } from "./receipt.js";
+import { completionRelationshipErrors } from "./completion-relationships.js";
+import { evaluateRequiredEvidence, classifyRequirement } from "./evidence-readiness.js";
+import { validateEventLedger, validateCompletionRecoveryAuthorization } from "./events.js";
+import { NEXT_ACTIONS, commandFor, decision, recordTerminalResultCommandSpec, result } from "./next-action-model.js";
+import { artifactError, checkListReasons, loadArtifact, requirementsAndCoverage } from "./next-action-artifacts.js";
+
+export async function resolveReviewingPhase({ state, context, requiredArtifacts, target, packageRoot, contract, route, preflight, authorityContext, runtimeContext, explicitTaskId, eventsRel, receiptRel, stateRel, policyRecoveryAction }) {
+    const invalidChecks = checkListReasons(state);
+    if (invalidChecks.length > 0) {
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+        reasons: invalidChecks,
+        requiredArtifacts,
+      });
+    }
+    const evidence = await requirementsAndCoverage({
+      target,
+      packageRoot,
+      contract,
+      route,
+      checks: state.checks,
+      additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+      authorityContext,
+      runtimeContext,
+    });
+    const readiness = evaluateRequiredEvidence({
+      requirements: evidence.requirements,
+      checks: state.checks,
+      target,
+      taskId: contract?.value?.taskId,
+      options: { authorityContext, runtimeContext },
+    });
+    if (!readiness.ready) {
+      let recoveryAuthorized = false;
+      if (state.lastCompletionAttempt?.status === "REJECTED") {
+        try {
+          const ledger = await validateEventLedger(target, packageRoot, { taskId: explicitTaskId, eventsPath: eventsRel });
+          let currentReceipt = null;
+          try {
+            const receiptArtifact = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
+            currentReceipt = receiptArtifact?.value;
+          } catch {}
+          const recoveryAuth = validateCompletionRecoveryAuthorization({
+            state,
+            receipt: currentReceipt,
+            events: ledger.events,
+          });
+          recoveryAuthorized = recoveryAuth.authorized;
+        } catch {
+          recoveryAuthorized = false;
+        }
+      }
+      return result({
+        ...context,
+        nextAction: recoveryAuthorized
+          ? NEXT_ACTIONS.ENTER_VERIFYING
+          : NEXT_ACTIONS.RESOLVE_BLOCKER,
+        commands: recoveryAuthorized
+          ? [commandFor(NEXT_ACTIONS.ENTER_VERIFYING)]
+          : [],
+        reasons: [...readiness.invalid, ...readiness.partial, ...readiness.missing]
+          .map((item) => artifactError(
+            readiness.missing.some((candidate) => candidate.id === item.id)
+              ? "E_EVIDENCE_REQUIRED"
+              : item.reasonCode ?? "E_EVIDENCE_PARTIAL",
+            `Evidence is not ready: ${item.text}`,
+            [stateRel],
+          )),
+        requiredArtifacts,
+      });
+    }
+    const receipt = await loadArtifact(
+      () => readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot),
+      receiptRel,
+    );
+    if (receipt.error) {
+      if (receipt.error.code !== "ARTIFACT_MISSING") {
+        return decision(
+          context,
+          NEXT_ACTIONS.RESOLVE_BLOCKER,
+          artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${receipt.error.message}`, [receiptRel]),
+          [...requiredArtifacts, receiptRel],
+        );
+      }
+      return decision(
+        context,
+        NEXT_ACTIONS.PREPARE_COMPLETION,
+        artifactError(
+          receipt.error.code === "ARTIFACT_MISSING" ? "E_RECEIPT_MISSING" : "E_RECEIPT_INVALID",
+          receipt.error.message,
+          [receiptRel],
+        ),
+        [...requiredArtifacts, receiptRel],
+        receipt.missingArtifacts,
+      );
+    }
+    try {
+      await validateReceipt(receipt.value.value, packageRoot, {
+        target,
+        taskId: contract?.value?.taskId,
+        authorityContext,
+        runtimeContext,
+      });
+    } catch (error) {
+      return decision(
+        context,
+        NEXT_ACTIONS.RESOLVE_BLOCKER,
+        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${error.message}`, [receiptRel]),
+        [...requiredArtifacts, receiptRel],
+      );
+    }
+    const receiptRelationships = completionRelationshipErrors({
+      contract,
+      route,
+      state,
+      receipt: receipt.value.value,
+      requiredEvidence: evidence.requirements,
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
+    });
+    if (receiptRelationships.length > 0) {
+      if (receiptRelationships.some((err) => (
+        err.code === "E_RECEIPT_STATE_MISMATCH"
+        || err.code === "E_RECEIPT_CYCLE_MISMATCH"
+        || err.code === "E_RECEIPT_CONTRACT_MISMATCH"
+        || err.code === "E_ROUTE_GUIDE_MISMATCH"
+        || err.code === "E_EVIDENCE_COVERAGE_INVALID"
+      ))) {
+        return decision(
+          context,
+          NEXT_ACTIONS.PREPARE_COMPLETION,
+          artifactError("E_RECEIPT_STATE_MISMATCH", "Run forgeloop prepare-completion to refresh the execution receipt with current state", [receiptRel]),
+          [...requiredArtifacts, receiptRel],
+        );
+      }
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+        reasons: receiptRelationships,
+        requiredArtifacts: [...requiredArtifacts, receiptRel],
+      });
+    }
+
+    const completion = await evaluateCompletion({ target, packageRoot, taskId: explicitTaskId, authorityContext, runtimeContext });
+    if (completion.status !== "VALID") {
+      const terminalPendingErrors = completion.errors.filter((err) => (
+        err.code === "E_PUBLICATION_REQUIREMENT_PENDING" || err.code === "E_PRODUCTION_REQUIREMENT_PENDING"
+      ));
+      if (terminalPendingErrors.length > 0 && terminalPendingErrors.length === completion.errors.length) {
+        const terminalPendingReqs = terminalPendingErrors.map((err) => {
+          const reqId = err.requirementId;
+          const matchingReq = evidence.requirements.find((r) => r.id === reqId)
+            ?? evidence.requirements.find((r) => r.text === reqId)
+            ?? classifyRequirement(reqId ?? err.message);
+          return matchingReq;
+        });
+        return result({
+          ...context,
+          nextAction: NEXT_ACTIONS.RECORD_TERMINAL_RESULT,
+          commands: ["forgeloop record-terminal-result"],
+          commandSpecs: terminalPendingReqs.map(recordTerminalResultCommandSpec),
+          reasons: completion.errors,
+          requiredArtifacts: [...requiredArtifacts, receiptRel, eventsRel],
+        });
+      }
+      const policyAction = policyRecoveryAction(completion.errors);
+      if (policyAction) {
+        return result({
+          ...context,
+          nextAction: policyAction,
+          reasons: completion.errors,
+          requiredArtifacts: [...requiredArtifacts, receiptRel, eventsRel],
+        });
+      }
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+        reasons: completion.errors,
+        requiredArtifacts: [...requiredArtifacts, receiptRel, eventsRel],
+      });
+    }
+    return decision(context, NEXT_ACTIONS.RUN_COMPLETE, artifactError("COMPLETION_READY", "Completion artifacts and cross-artifact validation are valid"));
+  }

package/src/core/next-action-verification-phase.js

@@ -0,0 +1,192 @@
+import { readJsonArtifact } from "./artifacts.js";
+import { taskArtifactPath, taskStructuralQualityDirectory } from "./task-paths.js";
+import { validateReceipt } from "./receipt.js";
+import { completionRelationshipErrors } from "./completion-relationships.js";
+import { evaluateRequiredEvidence, authoritativeChecksForRequirements, ordinaryLeafRequirements } from "./evidence-readiness.js";
+import { NEXT_ACTIONS, commandFor, decision, recordCheckCommandSpec, result } from "./next-action-model.js";
+import { artifactError, checkListReasons, loadArtifact, requirementsAndCoverage } from "./next-action-artifacts.js";
+import { projectStructuralQualityStatus } from "./structural-quality/service.js";
+import { structuralQualityOptionalActions } from "./next-action-quality-guidance.js";
+
+export async function resolveVerifyingPhase({ target, packageRoot, explicitTaskId, state, runtimeContext, context, requiredArtifacts, contract, route, preflight, authorityContext, stateRel, receiptRel }) {
+    const quality = await projectStructuralQualityStatus({ target, packageRoot, taskId: explicitTaskId ?? state.taskId, runtimeContext });
+    if (quality.mode === "gate") {
+      if (quality.baseline.status !== "OBSERVED") {
+        return result({
+          ...context,
+          nextAction: NEXT_ACTIONS.RESOLVE_STRUCTURAL_QUALITY_BLOCKER,
+          reasons: [artifactError("E_STRUCTURAL_QUALITY_BASELINE_MISSING", "Structural-quality gate cannot verify without its immutable baseline", [taskArtifactPath(state.taskId, "structuralQuality")])],
+          requiredArtifacts: [taskArtifactPath(state.taskId, "structuralQuality")],
+        });
+      }
+      if (!quality.current.artifactRef || quality.current.verificationCycle !== (state.verificationCycle ?? 1)) {
+        return result({
+          ...context,
+          nextAction: NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY,
+          commands: [commandFor(NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY).replace("<id>", state.taskId)],
+          reasons: [artifactError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", "The current verification cycle has no structural-quality evaluation", [taskStructuralQualityDirectory(state.taskId)])],
+          requiredArtifacts: [taskStructuralQualityDirectory(state.taskId)],
+        });
+      }
+      if (quality.freshness === "STALE") {
+        return result({
+          ...context,
+          nextAction: NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY,
+          commands: [commandFor(NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY).replace("<id>", state.taskId)],
+          reasons: [artifactError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", "Structural-quality evidence is stale; fresh verification is required before review", [quality.current.artifactRef])],
+          requiredArtifacts: [taskStructuralQualityDirectory(state.taskId)],
+        });
+      }
+      if (quality.current.status === "FAIL") {
+        return decision(context, NEXT_ACTIONS.DIAGNOSE_STRUCTURAL_QUALITY_REGRESSION, artifactError("E_STRUCTURAL_QUALITY_REGRESSION", "Structural-quality verification detected a regression", [quality.current.artifactRef]));
+      }
+      if (quality.current.status === "BLOCKED") {
+        return decision(context, NEXT_ACTIONS.RESOLVE_STRUCTURAL_QUALITY_BLOCKER, artifactError("E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE", "Structural-quality verification is blocked", [quality.current.artifactRef]));
+      }
+    }
+    const invalidChecks = checkListReasons(state);
+    if (invalidChecks.length > 0) {
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+        reasons: invalidChecks,
+        requiredArtifacts,
+      });
+    }
+    const evidence = await requirementsAndCoverage({
+      target,
+      packageRoot,
+      contract,
+      route,
+      checks: state.checks,
+      additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+      authorityContext,
+      runtimeContext,
+    });
+    const authoritative = authoritativeChecksForRequirements({
+      requirements: ordinaryLeafRequirements(evidence.requirements),
+      checks: state.checks,
+    });
+    const failed = authoritative.find(({ check }) => check?.status === "failed");
+    if (failed) {
+      return decision(
+        context,
+        NEXT_ACTIONS.DIAGNOSE,
+        artifactError("E_CHECK_FAILED", `Observed check failed: ${failed.check.id}`, [stateRel]),
+      );
+    }
+    const blocked = authoritative.find(({ check }) => check?.status === "blocked");
+    if (blocked) {
+      return decision(
+        context,
+        NEXT_ACTIONS.RESOLVE_BLOCKER,
+        artifactError("E_CHECK_BLOCKED", `Observed check is blocked: ${blocked.check.id}`, [stateRel]),
+      );
+    }
+    const receipt = await loadArtifact(
+      () => readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot),
+      receiptRel,
+    );
+    if (receipt.error) {
+      if (receipt.error.code === "ARTIFACT_MISSING") {
+        return decision(
+          context,
+          NEXT_ACTIONS.PREPARE_COMPLETION,
+          artifactError("E_RECEIPT_MISSING", "Prepare the execution receipt before recording verification checks", [receiptRel]),
+          [...requiredArtifacts, receiptRel],
+          receipt.missingArtifacts,
+        );
+      }
+      return decision(
+        context,
+        NEXT_ACTIONS.RESOLVE_BLOCKER,
+        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${receipt.error.message}`, [receiptRel]),
+        [...requiredArtifacts, receiptRel],
+      );
+    }
+    try {
+      await validateReceipt(receipt.value.value, packageRoot, {
+        target,
+        taskId: contract?.value?.taskId,
+        authorityContext,
+        runtimeContext,
+      });
+    } catch (error) {
+      return decision(
+        context,
+        NEXT_ACTIONS.RESOLVE_BLOCKER,
+        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${error.message}`, [receiptRel]),
+        [...requiredArtifacts, receiptRel],
+      );
+    }
+    const readiness = evaluateRequiredEvidence({
+      requirements: evidence.requirements,
+      checks: state.checks,
+      target,
+      taskId: contract?.value?.taskId,
+      options: { authorityContext, runtimeContext },
+    });
+    const receiptRelationships = completionRelationshipErrors({
+      contract,
+      route,
+      state,
+      receipt: receipt.value.value,
+      requiredEvidence: evidence.requirements,
+      requireRequiredChecks: false,
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
+    });
+    if (receiptRelationships.length > 0) {
+      if (receiptRelationships.some((err) => (
+        err.code === "E_RECEIPT_STATE_MISMATCH"
+        || err.code === "E_RECEIPT_CYCLE_MISMATCH"
+        || err.code === "E_RECEIPT_CONTRACT_MISMATCH"
+        || err.code === "E_ROUTE_GUIDE_MISMATCH"
+        || err.code === "E_EVIDENCE_COVERAGE_INVALID"
+      ))) {
+        return decision(
+          context,
+          NEXT_ACTIONS.PREPARE_COMPLETION,
+          artifactError("E_RECEIPT_STATE_MISMATCH", "Run forgeloop prepare-completion to refresh the execution receipt with current state", [receiptRel]),
+          [...requiredArtifacts, receiptRel],
+        );
+      }
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+        reasons: receiptRelationships,
+        requiredArtifacts: [...requiredArtifacts, receiptRel],
+      });
+    }
+    if (readiness.ready) {
+      return decision(
+        context,
+        NEXT_ACTIONS.ENTER_REVIEWING,
+        artifactError("EVIDENCE_COVERED", "All required observed verification evidence is covered"),
+        [],
+        [],
+        structuralQualityOptionalActions(quality, state.taskId),
+      );
+    }
+    const uncovered = [...readiness.invalid, ...readiness.partial, ...readiness.missing];
+    return result({
+      ...context,
+      nextAction: NEXT_ACTIONS.RECORD_VERIFICATION,
+      commands: ["forgeloop record-check"],
+      commandSpecs: uncovered.map((item) => recordCheckCommandSpec(item.text)),
+      reasons: uncovered
+        .map((item) => artifactError(
+          readiness.invalid.some((candidate) => candidate.id === item.id)
+            ? "E_EVIDENCE_INVALID"
+            : readiness.partial.some((candidate) => candidate.id === item.id)
+              ? "E_EVIDENCE_PARTIAL"
+              : "E_EVIDENCE_REQUIRED",
+          "Run the required check and record observed evidence through the structured command specification.",
+          [stateRel],
+        )),
+      requiredArtifacts: requiredArtifacts,
+      optionalActions: structuralQualityOptionalActions(quality, state.taskId),
+    });
+  }

package/src/core/task-recovery.js

@@ -5,7 +5,7 @@ import {
   E_TASK_RECOVERY_AUTHORITY_INVALID,
 } from "./error-codes.js";
 import { taskArtifactPath } from "./task-paths.js";
-import { getActiveTaskTransaction } from "./transaction.js";
+import { getTaskTransaction } from "./transaction.js";
 import { classifyRecoveryHistory } from "./recovery-history.js";
 
 export const TASK_RECOVERY_SCHEMA_VERSION = 1;
@@ -86,7 +86,7 @@ export function writeTaskRecovery(target, recovery, packageRoot) {
 }
 
 export async function clearTaskRecovery(target, { taskId } = {}) {
-  const transaction = getActiveTaskTransaction();
+  const transaction = (await getTaskTransaction(target));
   if (!transaction) {
     throw new Error("clearTaskRecovery requires an active task transaction");
   }

package/src/core/transaction-maintenance.js

@@ -0,0 +1,70 @@
+import { lstat, readdir, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { assertSafePath, ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
+import { withTaskLock } from "./task-lock.js";
+
+const ROOT = ".forgeloop/.txn";
+const TERMINAL = new Set(["COMMITTED", "ROLLED_BACK", "ABORTED"]);
+const DAY_MS = 86_400_000;
+
+async function payloadBytes(directory) {
+  let bytes = 0;
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const child = path.join(directory, entry.name);
+    const metadata = await lstat(child);
+    if (metadata.isSymbolicLink()) throw new Error("Transaction payload contains a symlink");
+    if (metadata.isDirectory()) bytes += await payloadBytes(child);
+    else if (metadata.isFile()) bytes += metadata.size;
+    else throw new Error("Transaction payload contains a special file");
+  }
+  return bytes;
+}
+
+/** Compact terminal payloads only; preserve manifests and all event ledgers. */
+export async function compactTransactions({ target, retainDays = 7, apply = false, now = Date.now() } = {}) {
+  if (!Number.isFinite(retainDays) || retainDays < 1) throw new Error("retainDays must be at least one day");
+  await assertSafePath(target, ROOT);
+  const root = ensureWithin(target, ROOT);
+  const report = { apply, scanned: 0, eligible: 0, bytes: 0, compacted: 0, skipped: [] };
+  if (!await fileExists(root)) return report;
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    report.scanned += 1;
+    const relative = `${ROOT}/${entry.name}`;
+    const manifestPath = `${relative}/manifest.json`;
+    try {
+      await assertSafePath(target, manifestPath);
+      const original = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
+      const lockTaskId = original.lockTaskId ?? original.taskId;
+      if (typeof lockTaskId !== "string" || !lockTaskId) throw new Error("Missing lock identity");
+      await withTaskLock(target, lockTaskId, "compact-transactions", async () => {
+        const manifest = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
+        if ((manifest.lockTaskId ?? manifest.taskId) !== lockTaskId || manifest.transactionId !== entry.name) throw new Error("Changed transaction identity");
+        const timestamp = Date.parse(manifest.committedAt ?? manifest.recoveredAt ?? manifest.failedAt ?? manifest.startedAt);
+        if (!TERMINAL.has(manifest.status) || !Number.isFinite(timestamp) || now - timestamp < retainDays * DAY_MS) return;
+        const payloads = [];
+        let bytes = 0;
+        for (const name of ["stage", "backup"]) {
+          const payload = `${relative}/${name}`;
+          await assertSafePath(target, payload);
+          const fullPath = ensureWithin(target, payload);
+          if (await fileExists(fullPath)) {
+            bytes += await payloadBytes(fullPath);
+            payloads.push(fullPath);
+          }
+        }
+        if (!payloads.length) return;
+        report.eligible += 1;
+        report.bytes += bytes;
+        if (!apply) return;
+        for (const payload of payloads) await rm(payload, { recursive: true, force: true, maxRetries: 3 });
+        manifest.compactedAt = new Date(now).toISOString();
+        await writeFileAtomic(ensureWithin(target, manifestPath), `${JSON.stringify(manifest, null, 2)}\n`);
+        report.compacted += 1;
+      });
+    } catch (error) {
+      report.skipped.push({ transactionId: entry.name, reason: error.message });
+    }
+  }
+  return report;
+}