@cassiomc1/forgeloop 1.1.1 → 1.2.2

package/src/core/next-action.js

@@ -1,4 +1,5 @@
 import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
+import { taskArtifactPath } from "./task-paths.js";
 import { completionIdentityErrors, evaluateCompletion } from "./completion.js";
 import { readContract } from "./contract.js";
 import { evaluatePreflight, validatePersistedPreflight, validateReadyProtocolConsistency } from "./preflight.js";
@@ -17,6 +18,7 @@ import {
   commandFor,
   decision,
   recordCheckCommandSpec,
+  recordDiagnosisCommandSpec,
   recordTerminalResultCommandSpec,
   result,
   uniqueSorted,
@@ -31,75 +33,113 @@ import {
 } from "./next-action-artifacts.js";
 import { PHASES_REQUIRING_EXECUTION_CHRONOLOGY } from "./next-action-phases.js";
 import { evaluateContinuityNextAction } from "./next-action-continuity.js";
+import { currentCycleDiagnosis } from "./diagnosis-model.js";
+import { evaluateProgress, PROGRESS_STATUS } from "./progress.js";
+import { criterionForDecision } from "./settlement-model.js";
+import { readEvents } from "./events.js";
 
 export { NEXT_ACTIONS } from "./next-action-model.js";
 
-export async function getNextAction(targetOrOptions = {}, packageRootOption) {
+export function policyRecoveryAction(errors = []) {
+  if (errors.some((e) => e.code === "E_POLICY_WEAKENING" || e.code === "E_POLICY_LOCK_MISMATCH")) {
+    return NEXT_ACTIONS.RESTORE_POLICY;
+  }
+  if (errors.some((e) => e.code === "E_CHECK_MUTATION_EXECUTION_ERROR" || e.code === "E_CHECK_MUTATION_NOT_DETECTED")) {
+    return NEXT_ACTIONS.REPAIR_CHECKER;
+  }
+  if (errors.some((e) => e.code === "E_POLICY_INVALID" || e.code === "E_POLICY_EVALUATION_FAILED")) {
+    return NEXT_ACTIONS.REPAIR_POLICY;
+  }
+  if (errors.some((e) => e.code === "E_POLICY_DRIFT_UNKNOWN")) {
+    return NEXT_ACTIONS.REVERIFY_AFTER_POLICY_CHANGE;
+  }
+  if (errors.some((e) => e.code === "E_BASELINE_EXPANSION")) {
+    return NEXT_ACTIONS.RESTORE_BASELINE;
+  }
+  if (errors.some((e) => e.code === "E_BASELINE_RECORD_DURING_ACTIVE_TASK")) {
+    return NEXT_ACTIONS.CONTINUE_WITH_EXISTING_BASELINE;
+  }
+  if (errors.some((e) => e.code === "E_CHECK_INERT")) {
+    return NEXT_ACTIONS.RESOLVE_INERT_CHECK;
+  }
+  return null;
+}
+
+async function computeNextAction(targetOrOptions = {}, packageRootOption) {
   const normalized = typeof targetOrOptions === "string"
     ? { target: targetOrOptions, packageRoot: packageRootOption }
     : targetOrOptions;
-  const { target, packageRoot, authorityContext, runtimeContext } = normalized ?? {};
+  const { target, packageRoot, taskId: explicitTaskId, authorityContext, runtimeContext } = normalized ?? {};
+
+  const stateRel = explicitTaskId ? taskArtifactPath(explicitTaskId, "state") : ARTIFACT_PATHS.state;
+  const preflightRel = explicitTaskId ? taskArtifactPath(explicitTaskId, "preflight") : ARTIFACT_PATHS.preflight;
+  const contractRel = explicitTaskId ? taskArtifactPath(explicitTaskId, "contract") : ARTIFACT_PATHS.contract;
+  const routeRel = explicitTaskId ? taskArtifactPath(explicitTaskId, "route") : ARTIFACT_PATHS.route;
+  const receiptRel = explicitTaskId ? taskArtifactPath(explicitTaskId, "receipt") : ARTIFACT_PATHS.receipt;
+  const eventsRel = explicitTaskId ? taskArtifactPath(explicitTaskId, "events") : ARTIFACT_PATHS.events;
+
   const workState = await loadArtifact(
-    () => readWorkState(target, packageRoot),
-    ARTIFACT_PATHS.state,
+    () => readWorkState(target, { packageRoot, taskId: explicitTaskId }),
+    stateRel,
   );
   if (workState.error) {
     return decision(
       {},
       NEXT_ACTIONS.RESOLVE_BLOCKER,
-      artifactError("WORK_STATE_INVALID", workState.error.message, [ARTIFACT_PATHS.state]),
-      [ARTIFACT_PATHS.state],
+      artifactError("WORK_STATE_INVALID", workState.error.message, [stateRel]),
+      [stateRel],
       workState.missingArtifacts,
     );
   }
   if (!workState.value) {
     const persistedPreflight = await loadArtifact(
-      () => readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot),
-      ARTIFACT_PATHS.preflight,
+      () => readJsonArtifact(target, preflightRel, "preflight", packageRoot),
+      preflightRel,
     );
     if (!persistedPreflight.error && persistedPreflight.value?.value?.status === "READY") {
       try {
         const consistencyErrors = await validateReadyProtocolConsistency({
           target,
           packageRoot,
+          taskId: explicitTaskId,
           persisted: persistedPreflight.value.value,
         });
         if (consistencyErrors.length > 0) {
           return result({
-            taskId: persistedPreflight.value.value.taskId ?? "unknown",
+            taskId: persistedPreflight.value.value.taskId ?? explicitTaskId ?? "unknown",
             currentPhase: "ROUTED",
             nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
             reasons: consistencyErrors,
             requiredArtifacts: [
-              ARTIFACT_PATHS.state,
-              ARTIFACT_PATHS.contract,
-              ARTIFACT_PATHS.route,
-              ARTIFACT_PATHS.preflight,
-              ARTIFACT_PATHS.events,
+              stateRel,
+              contractRel,
+              routeRel,
+              preflightRel,
+              eventsRel,
             ],
-            missingArtifacts: [ARTIFACT_PATHS.state],
+            missingArtifacts: [stateRel],
           });
         }
       } catch (error) {
         return result({
-          taskId: persistedPreflight.value.value.taskId ?? "unknown",
+          taskId: persistedPreflight.value.value.taskId ?? explicitTaskId ?? "unknown",
           currentPhase: "ROUTED",
           nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
           reasons: [artifactError(
             error.code ?? "E_PREFLIGHT_READY_INCONSISTENT",
             error.message,
-            error.artifacts ?? [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events],
+            error.artifacts ?? [preflightRel, eventsRel],
           )],
-          requiredArtifacts: [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events],
+          requiredArtifacts: [preflightRel, eventsRel],
         });
       }
     }
     return decision(
       {},
       NEXT_ACTIONS.DISCOVER,
-      artifactError("WORK_STATE_ABSENT", "No work-state checkpoint is present", [ARTIFACT_PATHS.state]),
-      [ARTIFACT_PATHS.state],
-      [ARTIFACT_PATHS.state],
+      artifactError("WORK_STATE_ABSENT", "No work-state checkpoint is present", [stateRel]),
+      [stateRel],
+      [stateRel],
     );
   }
 
@@ -110,7 +150,7 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       context,
       NEXT_ACTIONS.DISCOVER,
       artifactError("PHASE_RECEIVED", "Discovery has not started"),
-      [ARTIFACT_PATHS.state],
+      [stateRel],
     );
   }
   if (state.phase === "DISCOVERING") {
@@ -118,14 +158,14 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       context,
       NEXT_ACTIONS.CREATE_CONTRACT,
       artifactError("PHASE_DISCOVERING", "Create and validate the task contract"),
-      [ARTIFACT_PATHS.state],
+      [stateRel],
     );
   }
   const contractResult = await loadArtifact(
-    () => readContract(target, packageRoot),
-    ARTIFACT_PATHS.contract,
+    () => readContract(target, packageRoot, { taskId: explicitTaskId }),
+    contractRel,
   );
-  const contractArtifacts = [ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract];
+  const contractArtifacts = [stateRel, contractRel];
 
   if (contractResult.error) {
     return result({
@@ -154,7 +194,7 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
   const freshness = await classifyLoadedWorkState({
     target,
     state,
-    contractFile: ARTIFACT_PATHS.contract,
+    contractFile: contractRel,
   });
   if (freshness.status === "REVALIDATION_REQUIRED") {
     return result({
@@ -162,8 +202,8 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
       reasons: freshnessReasons(state, freshness),
       requiredArtifacts: uniqueSorted([
-        ARTIFACT_PATHS.state,
-        ARTIFACT_PATHS.contract,
+        stateRel,
+        contractRel,
         ...(state.requiredArtifacts?.map((artifact) => artifact.path) ?? []),
       ]),
     });
@@ -174,14 +214,14 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       NEXT_ACTIONS.ROUTE,
       artifactError("PHASE_CONTRACT_READY", "Persist deterministic routing for the validated contract"),
       contractArtifacts,
-      [ARTIFACT_PATHS.route],
+      [routeRel],
     );
   }
   const routeResult = await loadArtifact(
-    () => readPersistedRoute(target, packageRoot),
-    ARTIFACT_PATHS.route,
+    () => readPersistedRoute(target, packageRoot, { taskId: explicitTaskId }),
+    routeRel,
   );
-  const requiredArtifacts = [...contractArtifacts, ARTIFACT_PATHS.route];
+  const requiredArtifacts = [...contractArtifacts, routeRel];
   const missingArtifacts = [...routeResult.missingArtifacts];
 
   if (routeResult.error) {
@@ -213,7 +253,7 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
   let executionPrerequisites = null;
   if (phaseNeedsChronology) {
     try {
-      executionPrerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot });
+      executionPrerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot, taskId: explicitTaskId });
     } catch (error) {
       return result({
         ...context,
@@ -221,14 +261,14 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
         reasons: [artifactError(
           error?.code ?? "E_PHASE_CHRONOLOGY_INVALID",
           `Unable to evaluate post-execution prerequisites: ${error?.message ?? String(error)}`,
-          Array.isArray(error?.artifacts) ? error.artifacts : [ARTIFACT_PATHS.events],
+          Array.isArray(error?.artifacts) ? error.artifacts : [eventsRel],
         )],
         requiredArtifacts: [
-          ARTIFACT_PATHS.state,
-          ARTIFACT_PATHS.contract,
-          ARTIFACT_PATHS.route,
-          ARTIFACT_PATHS.preflight,
-          ARTIFACT_PATHS.events,
+          stateRel,
+          contractRel,
+          routeRel,
+          preflightRel,
+          eventsRel,
         ],
       });
     }
@@ -242,15 +282,15 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
     }
   }
 
-  const preflight = executionPrerequisites?.preflight ?? await evaluatePreflight({ target, packageRoot });
+  const preflight = executionPrerequisites?.preflight ?? await evaluatePreflight({ target, packageRoot, taskId: explicitTaskId });
   const preflightArtifact = phaseNeedsChronology
     ? null
     : await loadArtifact(
-      () => readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot),
-      ARTIFACT_PATHS.preflight,
+      () => readJsonArtifact(target, preflightRel, "preflight", packageRoot),
+      preflightRel,
     );
   const missingGates = preflight.requiredGates.filter((gate) => !preflight.satisfiedGates.includes(gate));
-  const preflightArtifacts = [...requiredArtifacts, ARTIFACT_PATHS.preflight];
+  const preflightArtifacts = [...requiredArtifacts, preflightRel];
   const persistedPreflightErrors = phaseNeedsChronology
     ? []
     : validatePersistedPreflight(preflightArtifact.value?.value, preflight);
@@ -285,7 +325,7 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
     return decision(context, NEXT_ACTIONS.PLAN, artifactError("PHASE_DESIGNING", "Required gates are ready for planning"));
   }
   if (state.phase === "PLANNED") {
-    const prerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot });
+    const prerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot, taskId: explicitTaskId });
     if (prerequisites.errors.length > 0) {
       const preflightOnly = prerequisites.errors.every((error) => error.code.startsWith("E_PREFLIGHT_")
         || (error.code === "E_PHASE_CHRONOLOGY_INVALID"
@@ -345,7 +385,7 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       return decision(
         context,
         NEXT_ACTIONS.DIAGNOSE,
-        artifactError("E_CHECK_FAILED", `Observed check failed: ${failed.check.id}`, [ARTIFACT_PATHS.state]),
+        artifactError("E_CHECK_FAILED", `Observed check failed: ${failed.check.id}`, [stateRel]),
       );
     }
     const blocked = authoritative.find(({ check }) => check?.status === "blocked");
@@ -353,28 +393,28 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       return decision(
         context,
         NEXT_ACTIONS.RESOLVE_BLOCKER,
-        artifactError("E_CHECK_BLOCKED", `Observed check is blocked: ${blocked.check.id}`, [ARTIFACT_PATHS.state]),
+        artifactError("E_CHECK_BLOCKED", `Observed check is blocked: ${blocked.check.id}`, [stateRel]),
       );
     }
     const receipt = await loadArtifact(
-      () => readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot),
-      ARTIFACT_PATHS.receipt,
+      () => 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", [ARTIFACT_PATHS.receipt]),
-          [...requiredArtifacts, ARTIFACT_PATHS.receipt],
+          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}`, [ARTIFACT_PATHS.receipt]),
-        [...requiredArtifacts, ARTIFACT_PATHS.receipt],
+        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${receipt.error.message}`, [receiptRel]),
+        [...requiredArtifacts, receiptRel],
       );
     }
     try {
@@ -388,8 +428,8 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       return decision(
         context,
         NEXT_ACTIONS.RESOLVE_BLOCKER,
-        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${error.message}`, [ARTIFACT_PATHS.receipt]),
-        [...requiredArtifacts, ARTIFACT_PATHS.receipt],
+        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${error.message}`, [receiptRel]),
+        [...requiredArtifacts, receiptRel],
       );
     }
     const readiness = evaluateRequiredEvidence({
@@ -422,15 +462,15 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
         return decision(
           context,
           NEXT_ACTIONS.PREPARE_COMPLETION,
-          artifactError("E_RECEIPT_STATE_MISMATCH", "Run forgeloop prepare-completion to refresh the execution receipt with current state", [ARTIFACT_PATHS.receipt]),
-          [...requiredArtifacts, ARTIFACT_PATHS.receipt],
+          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, ARTIFACT_PATHS.receipt],
+        requiredArtifacts: [...requiredArtifacts, receiptRel],
       });
     }
     if (readiness.ready) {
@@ -450,25 +490,56 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
               ? "E_EVIDENCE_PARTIAL"
               : "E_EVIDENCE_REQUIRED",
           "Run the required check and record observed evidence through the structured command specification.",
-          [ARTIFACT_PATHS.state],
+          [stateRel],
         )),
       requiredArtifacts: requiredArtifacts,
     });
   }
   if (state.phase === "DIAGNOSING") {
-    if (typeof state.diagnosedHypothesis !== "string" || !state.diagnosedHypothesis.trim()) {
-      return decision(
-        context,
-        NEXT_ACTIONS.RESOLVE_BLOCKER,
-        artifactError(
-          "E_DIAGNOSIS_HYPOTHESIS_MISSING",
-          "Record diagnosedHypothesis in .forgeloop/work-state.json before advancing to CORRECTING",
-          [ARTIFACT_PATHS.state],
-        ),
+    const ledger = await validateEventLedger(target, packageRoot, { taskId: normalized.taskId ?? null });
+    const cycle = state.verificationCycle ?? 1;
+    const diagEvent = currentCycleDiagnosis(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) {
+      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,
         requiredArtifacts,
-      );
+      });
     }
-    return decision(context, NEXT_ACTIONS.CORRECT, artifactError("PHASE_DIAGNOSING", "The persisted diagnosis hypothesis permits correction"));
+    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,
+    });
   }
   if (state.phase === "CORRECTING") {
     return decision(context, NEXT_ACTIONS.ENTER_VERIFYING, artifactError("PHASE_CORRECTING", "Correction is ready for verification"));
@@ -504,10 +575,10 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       let recoveryAuthorized = false;
       if (state.lastCompletionAttempt?.status === "REJECTED") {
         try {
-          const ledger = await validateEventLedger(target, packageRoot);
+          const ledger = await validateEventLedger(target, packageRoot, { taskId: explicitTaskId, eventsPath: eventsRel });
           let currentReceipt = null;
           try {
-            const receiptArtifact = await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+            const receiptArtifact = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
             currentReceipt = receiptArtifact?.value;
           } catch {}
           const recoveryAuth = validateCompletionRecoveryAuthorization({
@@ -534,22 +605,22 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
               ? "E_EVIDENCE_REQUIRED"
               : item.reasonCode ?? "E_EVIDENCE_PARTIAL",
             `Evidence is not ready: ${item.text}`,
-            [ARTIFACT_PATHS.state],
+            [stateRel],
           )),
         requiredArtifacts,
       });
     }
     const receipt = await loadArtifact(
-      () => readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot),
-      ARTIFACT_PATHS.receipt,
+      () => 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}`, [ARTIFACT_PATHS.receipt]),
-          [...requiredArtifacts, ARTIFACT_PATHS.receipt],
+          artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${receipt.error.message}`, [receiptRel]),
+          [...requiredArtifacts, receiptRel],
         );
       }
       return decision(
@@ -558,9 +629,9 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
         artifactError(
           receipt.error.code === "ARTIFACT_MISSING" ? "E_RECEIPT_MISSING" : "E_RECEIPT_INVALID",
           receipt.error.message,
-          [ARTIFACT_PATHS.receipt],
+          [receiptRel],
         ),
-        [...requiredArtifacts, ARTIFACT_PATHS.receipt],
+        [...requiredArtifacts, receiptRel],
         receipt.missingArtifacts,
       );
     }
@@ -575,8 +646,8 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       return decision(
         context,
         NEXT_ACTIONS.RESOLVE_BLOCKER,
-        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${error.message}`, [ARTIFACT_PATHS.receipt]),
-        [...requiredArtifacts, ARTIFACT_PATHS.receipt],
+        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${error.message}`, [receiptRel]),
+        [...requiredArtifacts, receiptRel],
       );
     }
     const receiptRelationships = completionRelationshipErrors({
@@ -601,18 +672,19 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
         return decision(
           context,
           NEXT_ACTIONS.PREPARE_COMPLETION,
-          artifactError("E_RECEIPT_STATE_MISMATCH", "Run forgeloop prepare-completion to refresh the execution receipt with current state", [ARTIFACT_PATHS.receipt]),
-          [...requiredArtifacts, ARTIFACT_PATHS.receipt],
+          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, ARTIFACT_PATHS.receipt],
+        requiredArtifacts: [...requiredArtifacts, receiptRel],
       });
     }
-    const completion = await evaluateCompletion({ target, packageRoot, authorityContext, runtimeContext });
+
+    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"
@@ -631,28 +703,38 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
           commands: ["forgeloop record-terminal-result"],
           commandSpecs: terminalPendingReqs.map(recordTerminalResultCommandSpec),
           reasons: completion.errors,
-          requiredArtifacts: [...requiredArtifacts, ARTIFACT_PATHS.receipt, ARTIFACT_PATHS.events],
+          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, ARTIFACT_PATHS.receipt, ARTIFACT_PATHS.events],
+        requiredArtifacts: [...requiredArtifacts, receiptRel, eventsRel],
       });
     }
     return decision(context, NEXT_ACTIONS.RUN_COMPLETE, artifactError("COMPLETION_READY", "Completion artifacts and cross-artifact validation are valid"));
   }
   if (state.phase === "COMPLETE") {
-    const completion = await evaluateCompletion({ target, packageRoot, authorityContext, runtimeContext });
+    const completion = await evaluateCompletion({ target, packageRoot, taskId: explicitTaskId, authorityContext, runtimeContext });
     if (completion.status === "VALID") {
       return decision(context, NEXT_ACTIONS.NONE, artifactError("PHASE_COMPLETE", "Completion is validator-backed and terminal"));
     }
+    const policyAction = policyRecoveryAction(completion.errors);
     return result({
       ...context,
-      nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+      nextAction: policyAction ?? NEXT_ACTIONS.RESOLVE_BLOCKER,
       reasons: completion.errors,
-      requiredArtifacts: [...requiredArtifacts, ARTIFACT_PATHS.receipt, ARTIFACT_PATHS.events],
+      requiredArtifacts: [...requiredArtifacts, receiptRel, eventsRel],
     });
   }
   if (state.phase === "BLOCKED") {
@@ -662,7 +744,7 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
       reasons: state.blockers.map((blocker) => artifactError(
         "WORK_STATE_BLOCKED",
         blocker.reason ?? "Work state has a recorded blocker",
-        [ARTIFACT_PATHS.state],
+        [stateRel],
       )),
       requiredArtifacts,
     });
@@ -675,3 +757,64 @@ export async function getNextAction(targetOrOptions = {}, packageRootOption) {
     requiredArtifacts,
   );
 }
+
+export async function getNextAction(targetOrOptions = {}, packageRootOption) {
+  const res = await computeNextAction(targetOrOptions, packageRootOption);
+  if (res && res.reasons && res.reasons.some((r) => r.code === "E_CONTRACT_UNRESOLVED_DECISION" || r.code === "E_UNRESOLVED_DECISION")) {
+    const normalized = typeof targetOrOptions === "string" ? { target: targetOrOptions, packageRoot: packageRootOption } : targetOrOptions;
+    const { target, packageRoot, taskId } = normalized ?? {};
+    try {
+      const explicitTaskId = taskId ?? null;
+      const contract = await readContract(target, packageRoot, { taskId: explicitTaskId });
+      const events = await readEvents(target, packageRoot, { taskId: explicitTaskId });
+      if (contract?.value?.unresolvedDecisions?.length > 0) {
+        const foundCriteria = [];
+        for (const dec of contract.value.unresolvedDecisions) {
+          const criterion = criterionForDecision(events, res.taskId, dec, contract.fingerprint);
+          if (criterion) {
+            foundCriteria.push({
+              decisionId: criterion.decisionId,
+              decision: dec,
+              settledBy: criterion.settledBy,
+            });
+          }
+        }
+
+        if (foundCriteria.length > 0) {
+          let resolution;
+          if (foundCriteria.length === 1) {
+            resolution = {
+              kind: "SETTLEMENT_CRITERION",
+              itemId: foundCriteria[0].decisionId,
+              decision: foundCriteria[0].decision,
+              settledBy: foundCriteria[0].settledBy,
+            };
+          } else {
+            resolution = {
+              kind: "SETTLEMENT_CRITERIA",
+              items: foundCriteria,
+            };
+          }
+
+          const enrichedReasons = res.reasons.map((r) => {
+            if (r.code === "E_CONTRACT_UNRESOLVED_DECISION" || r.code === "E_UNRESOLVED_DECISION") {
+              return {
+                ...r,
+                resolution,
+              };
+            }
+            return r;
+          });
+
+          return result({
+            ...res,
+            reasons: enrichedReasons,
+          });
+        }
+      }
+    } catch {
+      // Ignore read errors
+    }
+  }
+  return res;
+}

package/src/core/phase.js

@@ -21,6 +21,7 @@ import { discoverTasks } from "./task-discovery.js";
 import { assertNoScopeConflicts, assertScopeClean } from "./task-scope.js";
 import { readTaskDescriptor } from "./task-descriptor.js";
 import { E_TASK_SCOPE_REQUIRED } from "./error-codes.js";
+import { currentCycleDiagnosis } from "./diagnosis-model.js";
 
 function phaseError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -242,7 +243,35 @@ export async function advanceWorkState(target, toPhase, options = {}) {
       );
     }
   }
+  if (toPhase === "CORRECTING" && state.phase === "DIAGNOSING") {
+    const cycle = state.verificationCycle ?? 1;
+    const diagEvent = currentCycleDiagnosis(ledger.events, state.taskId, cycle);
+    if (!diagEvent) {
+      throw phaseError(
+        "E_DIAGNOSIS_REQUIRED",
+        "DIAGNOSING -> CORRECTING requires an append-only diagnosis record for the active verification cycle",
+        [eventsRel],
+      );
+    }
+    const details = diagEvent.details;
+    if (!details || details.informationGain === "NONE") {
+      throw phaseError(
+        "E_DIAGNOSIS_NO_NEW_INFORMATION",
+        "The proposed retry repeats the previous hypothesis with the same evidence without new information",
+        [eventsRel],
+      );
+    }
+  }
   if (toPhase === "VERIFYING" && state.phase === "CORRECTING") {
+    const cycle = state.verificationCycle ?? 1;
+    const diagEvent = currentCycleDiagnosis(ledger.events, state.taskId, cycle);
+    if (!diagEvent) {
+      throw phaseError(
+        "E_DIAGNOSIS_REQUIRED",
+        "CORRECTING -> VERIFYING requires an append-only diagnosis record for the current cycle",
+        [eventsRel],
+      );
+    }
     if (typeof state.diagnosedHypothesis !== "string" || !state.diagnosedHypothesis.trim()) {
       throw phaseError(
         "E_PHASE_PREREQUISITE_MISSING",