@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

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

@@ -1,15 +1,31 @@
 import { ARTIFACT_PATHS } from "./artifacts.js";
 import { reconcileContinuity } from "./continuity-reconciliation.js";
-import { NEXT_ACTIONS, result } from "./next-action-model.js";
+import { directCommandSpec, NEXT_ACTIONS, result } from "./next-action-model.js";
+import { taskArtifactPath } from "./task-paths.js";
 
-const REQUIRED_ARTIFACTS = Object.freeze([ARTIFACT_PATHS.state, ARTIFACT_PATHS.continuity]);
+const SINGLETON_REQUIRED_ARTIFACTS = Object.freeze([ARTIFACT_PATHS.state, ARTIFACT_PATHS.continuity]);
 
-function reason(code, message, artifacts = REQUIRED_ARTIFACTS) {
+function reason(code, message, artifacts = SINGLETON_REQUIRED_ARTIFACTS) {
   return { code, message, artifacts };
 }
 
+function continuityArtifacts(taskId) {
+  if (!taskId) {
+    return {
+      continuity: ARTIFACT_PATHS.continuity,
+      required: SINGLETON_REQUIRED_ARTIFACTS,
+    };
+  }
+  return {
+    continuity: taskArtifactPath(taskId, "continuity"),
+    required: [taskArtifactPath(taskId, "state"), taskArtifactPath(taskId, "continuity")],
+  };
+}
+
 export function nextActionForContinuity({ context, continuity } = {}) {
   if (!continuity || ["ABSENT", "NOT_APPLICABLE"].includes(continuity.classification)) return null;
+  const taskId = context?.taskId ?? null;
+  const artifacts = continuityArtifacts(taskId);
 
   if (continuity.classification === "FRESH") {
     const remaining = continuity.continuity?.remainingWork ?? [];
@@ -20,22 +36,27 @@ export function nextActionForContinuity({ context, continuity } = {}) {
       reasons: [reason(
         "CONTINUITY_REMAINING_WORK",
         `Execution continuity records ${remaining.length} remaining implementation item${remaining.length === 1 ? "" : "s"}.`,
-        [ARTIFACT_PATHS.continuity],
+        [artifacts.continuity],
       )],
-      requiredArtifacts: REQUIRED_ARTIFACTS,
+      requiredArtifacts: artifacts.required,
     });
   }
 
   if (continuity.classification === "RECONCILIATION_REQUIRED") {
+    const command = taskId
+      ? `forgeloop reconcile-continuity --task ${taskId}`
+      : "forgeloop reconcile-continuity";
     return result({
       ...context,
       nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
-      commands: ["forgeloop reconcile-continuity"],
+      commands: [command],
+      ...(taskId ? { commandSpecs: [directCommandSpec("reconcile-continuity", taskId)] } : {}),
       reasons: [reason(
         "E_CONTINUITY_RECONCILIATION_REQUIRED",
         "Execution continuity no longer matches canonical state or the current checkout; reconcile it before advancing verification.",
+        artifacts.required,
       )],
-      requiredArtifacts: REQUIRED_ARTIFACTS,
+      requiredArtifacts: artifacts.required,
     });
   }
 
@@ -49,8 +70,9 @@ export function nextActionForContinuity({ context, continuity } = {}) {
       reasons: codes.map((code, index) => reason(
         code,
         continuity.reasons?.[index] ?? `Execution continuity is ${continuity.classification.toLowerCase()}.`,
+        artifacts.required,
       )),
-      requiredArtifacts: REQUIRED_ARTIFACTS,
+      requiredArtifacts: artifacts.required,
     });
   }
 
@@ -60,6 +82,6 @@ export function nextActionForContinuity({ context, continuity } = {}) {
 export async function evaluateContinuityNextAction({ target, packageRoot, context } = {}) {
   return nextActionForContinuity({
     context,
-    continuity: await reconcileContinuity({ target, packageRoot }),
+    continuity: await reconcileContinuity({ target, packageRoot, taskId: context?.taskId ?? null }),
   });
 }

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

@@ -6,6 +6,7 @@ export const NEXT_ACTIONS = Object.freeze({
   CREATE_CONTRACT: "CREATE_CONTRACT",
   ROUTE: "ROUTE",
   SATISFY_GATES: "SATISFY_GATES",
+  REVALIDATE_GATES: "REVALIDATE_GATES",
   RUN_PREFLIGHT: "RUN_PREFLIGHT",
   PLAN: "PLAN",
   START_EXECUTION: "START_EXECUTION",
@@ -47,6 +48,9 @@ export const NEXT_ACTIONS = Object.freeze({
   RECOVER_TASK: "RECOVER_TASK",
   RESUME_RECOVERED_TASK: "RESUME_RECOVERED_TASK",
   RESOLVE_RECOVERY_INCONSISTENCY: "RESOLVE_RECOVERY_INCONSISTENCY",
+  REPAIR_CONTRACT_BOOTSTRAP: "REPAIR_CONTRACT_BOOTSTRAP",
+  MIGRATE_CONTRACT_BOOTSTRAP_REPAIR: "MIGRATE_CONTRACT_BOOTSTRAP_REPAIR",
+  REVALIDATE_CHECKPOINT: "REVALIDATE_CHECKPOINT",
   NONE: "NONE",
 });
 
@@ -60,6 +64,33 @@ export function directCommandSpec(commandId, taskId, requiredInputs = []) {
   };
 }
 
+export function routeCommandSpec(taskId) {
+  return {
+    commandId: "route",
+    executable: "forgeloop",
+    subcommand: "route",
+    argv: ["route", `--task=${taskId}`, "--json"],
+    requiredInputs: [
+      { name: "workType", option: "--work=<type>" },
+      { name: "surface", option: "--surface=<value>", repeatable: true, optional: true },
+      { name: "risk", option: "--risk=<value>", repeatable: true, optional: true },
+      { name: "platform", option: "--platform=<value>", repeatable: true, optional: true },
+    ],
+  };
+}
+
+export function gateRevalidationCommandSpec(taskId, gate) {
+  return {
+    commandId: "gate-revalidate",
+    executable: "forgeloop",
+    subcommand: "gate-revalidate",
+    argv: ["gate-revalidate", `--task=${taskId}`, `--gate=${gate}`, "--acknowledge-stale", "--json"],
+    requiredInputs: [
+      { name: "acknowledgeStale", option: "--acknowledge-stale" },
+    ],
+  };
+}
+
 export function recoveryGuidanceForClassification(classification, taskId) {
   if (classification === "RECOVERABLE") {
     return {
@@ -167,8 +198,35 @@ export function result({
   };
 }
 
+export function contractBootstrapRepairGuidance(taskId, reason = null) {
+  const command = `forgeloop task-repair-contract-bootstrap --task ${taskId} --acknowledge-repair --json`;
+  return {
+    nextAction: NEXT_ACTIONS.REPAIR_CONTRACT_BOOTSTRAP,
+    commands: [command],
+    commandSpecs: [directCommandSpec("task-repair-contract-bootstrap", taskId, [
+      { name: "acknowledgeRepair", option: "--acknowledge-repair", description: "Explicit caller acknowledgement of the exact repair signature." },
+    ])],
+    reason: reason ?? { code: "E_CONTRACT_BOOTSTRAP_REPAIR_AVAILABLE", message: "The exact duplicate contract bootstrap defect is repairable through the official append-only command." },
+  };
+}
+
+export function contractBootstrapRepairMigrationGuidance(taskId, reason = null) {
+  const command = `forgeloop task-migrate-contract-bootstrap-repair --task ${taskId} --acknowledge-migration --json`;
+  return {
+    nextAction: NEXT_ACTIONS.MIGRATE_CONTRACT_BOOTSTRAP_REPAIR,
+    commands: [command],
+    commandSpecs: [directCommandSpec("task-migrate-contract-bootstrap-repair", taskId, [
+      { name: "acknowledgeMigration", option: "--acknowledge-migration", description: "Fresh explicit caller acknowledgement of the exact legacy marker migration." },
+    ])],
+    reason: reason ?? { code: "E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_AVAILABLE", message: "The exact legacy contract bootstrap repair marker can be migrated through the official append-only command." },
+  };
+}
+
 export function commandFor(action) {
   return {
+    [NEXT_ACTIONS.ROUTE]: "forgeloop route --task <id> --work <type> --json",
+    [NEXT_ACTIONS.RESOLVE_STALE_ROUTE]: "forgeloop route --task <id> --work <type> --json",
+    [NEXT_ACTIONS.REVALIDATE_GATES]: "forgeloop gate-revalidate --task <id> --gate <name> --acknowledge-stale --json",
     [NEXT_ACTIONS.PLAN]: "forgeloop advance --to PLANNED",
     [NEXT_ACTIONS.RUN_PREFLIGHT]: "forgeloop preflight --json",
     [NEXT_ACTIONS.START_EXECUTION]: "forgeloop advance --to EXECUTING",

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

@@ -5,7 +5,7 @@ import { resolvePlannedPhase } from "./next-action-planned-phase.js";
 import { resolvePendingActionGuidance } from "./next-action-pending-actions.js";
 import { preExecutionRefreshGuidance } from "./next-action-refresh.js";
 import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
-import { taskArtifactPath } from "./task-paths.js";
+import { taskArtifactPath, taskGatePath } from "./task-paths.js";
 import { completionIdentityErrors, evaluateCompletion } from "./completion.js";
 import { readContract } from "./contract.js";
 import { evaluatePreflight, validatePersistedPreflight } from "./preflight.js";
@@ -16,10 +16,16 @@ import { classifyLoadedWorkState } from "./work-state.js";
 
 import { evaluateStartExecutionPrerequisites } from "./execution-prerequisites.js";
 
-import { NEXT_ACTIONS, commandFor, decision, recoveryGuidanceForClassification, result, uniqueSorted } from "./next-action-model.js";
+import { NEXT_ACTIONS, commandFor, decision, gateRevalidationCommandSpec, recoveryGuidanceForClassification, result, routeCommandSpec, uniqueSorted } from "./next-action-model.js";
 import { artifactError, freshnessReasons, loadArtifact, staleReasons } from "./next-action-artifacts.js";
 
 import { inspectTaskConflictState } from "./task-conflict-inspection.js";
+import { validateEventLedger } from "./events.js";
+import {
+  isContractBootstrapRepairCandidate,
+  isLegacyContractBootstrapRepairMigrationCandidate,
+} from "./contract-bootstrap-recovery.js";
+import { contractBootstrapRepairGuidance, contractBootstrapRepairMigrationGuidance } from "./next-action-model.js";
 
 import { evaluateContinuityNextAction } from "./next-action-continuity.js";
 
@@ -32,10 +38,85 @@ export const PHASES_REQUIRING_EXECUTION_CHRONOLOGY = new Set([
   "COMPLETE",
 ]);
 
+const PHASES_ALLOWING_GATE_REVALIDATION = new Set([
+  "EXECUTING", "VERIFYING", "DIAGNOSING", "CORRECTING", "REVIEWING",
+]);
+
 export function phaseRequiresExecutionChronology(phase) {
   return PHASES_REQUIRING_EXECUTION_CHRONOLOGY.has(phase);
 }
 
+async function contractBootstrapRepairGuidanceForExplicitTask({ target, packageRoot, explicitTaskId, context, eventsRel, stateRel }) {
+  const ledger = await validateEventLedger(target, packageRoot, { taskId: explicitTaskId });
+  const candidate = isContractBootstrapRepairCandidate(ledger.events, ledger.errors, explicitTaskId);
+  if (candidate) {
+    const guidance = contractBootstrapRepairGuidance(explicitTaskId);
+    return result({
+      ...context,
+      nextAction: guidance.nextAction,
+      commands: guidance.commands,
+      commandSpecs: guidance.commandSpecs,
+      reasons: [artifactError(guidance.reason.code, guidance.reason.message, [eventsRel, taskArtifactPath(explicitTaskId, "state")])],
+      requiredArtifacts: [eventsRel, taskArtifactPath(explicitTaskId, "contract")],
+    });
+  }
+  const tolerantLedger = await validateEventLedger(target, packageRoot, {
+    taskId: explicitTaskId,
+    allowUnmigratedLegacyContractBootstrapRepairMarkers: true,
+  });
+  if (!tolerantLedger.valid || !isLegacyContractBootstrapRepairMigrationCandidate(tolerantLedger.events, explicitTaskId)) {
+    return null;
+  }
+  const guidance = contractBootstrapRepairMigrationGuidance(explicitTaskId);
+  return result({
+    ...context,
+    nextAction: guidance.nextAction,
+    commands: guidance.commands,
+    commandSpecs: guidance.commandSpecs,
+    reasons: [artifactError(guidance.reason.code, guidance.reason.message, [eventsRel, stateRel])],
+    requiredArtifacts: [eventsRel, taskArtifactPath(explicitTaskId, "contract"), stateRel],
+  });
+}
+
+async function explicitTaskConflictGuidance({ target, packageRoot, explicitTaskId, context, eventsRel, stateRel, state }) {
+  try {
+    const migrationGuidance = await contractBootstrapRepairGuidanceForExplicitTask({
+      target, packageRoot, explicitTaskId, context, eventsRel, stateRel,
+    });
+    if (migrationGuidance) return migrationGuidance;
+  } catch {
+    // The regular conflict inspection below remains the fail-closed path.
+  }
+  let inspection;
+  try {
+    inspection = await inspectTaskConflictState(target, {
+      taskId: explicitTaskId,
+      packageRoot,
+    });
+  } catch (error) {
+    inspection = {
+      classification: "INCONSISTENT",
+      reasonCodes: [error.code ?? "E_TASK_RECOVERY_INCONSISTENT"],
+    };
+  }
+  if (["ACTIVE", "COMPLETE"].includes(inspection.classification)) return null;
+  if (PHASES_ALLOWING_GATE_REVALIDATION.has(state?.phase)
+    && inspection.reasonCodes?.includes("E_GATE_STALE")) return null;
+  const guidance = recoveryGuidanceForClassification(inspection.classification, explicitTaskId);
+  return result({
+    ...context,
+    nextAction: guidance.nextAction,
+    commands: guidance.commands,
+    commandSpecs: guidance.commandSpecs,
+    reasons: inspection.reasonCodes.map((code) => artifactError(
+      code,
+      `Task conflict state is ${inspection.classification}; follow the structured recovery guidance.`,
+      [stateRel, eventsRel, taskArtifactPath(explicitTaskId, "recovery")],
+    )),
+    requiredArtifacts: [stateRel, eventsRel],
+  });
+}
+
 export async function resolveNextActionPhase({
   target,
   packageRoot,
@@ -55,33 +136,10 @@ export async function resolveNextActionPhase({
 } = {}) {
   const { policyRecoveryAction } = helpers;
   if (explicitTaskId) {
-    let inspection;
-    try {
-      inspection = await inspectTaskConflictState(target, {
-        taskId: explicitTaskId,
-        packageRoot,
-      });
-    } catch (error) {
-      inspection = {
-        classification: "INCONSISTENT",
-        reasonCodes: [error.code ?? "E_TASK_RECOVERY_INCONSISTENT"],
-      };
-    }
-    if (!["ACTIVE", "COMPLETE"].includes(inspection.classification)) {
-      const guidance = recoveryGuidanceForClassification(inspection.classification, explicitTaskId);
-      return result({
-        ...context,
-        nextAction: guidance.nextAction,
-        commands: guidance.commands,
-        commandSpecs: guidance.commandSpecs,
-        reasons: inspection.reasonCodes.map((code) => artifactError(
-          code,
-          `Task conflict state is ${inspection.classification}; follow the structured recovery guidance.`,
-          [stateRel, eventsRel, taskArtifactPath(explicitTaskId, "recovery")],
-        )),
-        requiredArtifacts: [stateRel, eventsRel],
-      });
-    }
+    const taskConflictGuidance = await explicitTaskConflictGuidance({
+      target, packageRoot, explicitTaskId, context, eventsRel, stateRel, state,
+    });
+    if (taskConflictGuidance) return taskConflictGuidance;
   }
   const actionGuidance = await resolvePendingActionGuidance({ target, packageRoot, state, context, eventsRel, authorityContext, runtimeContext, helpers });
   if (actionGuidance) return actionGuidance;
@@ -137,11 +195,11 @@ export async function resolveNextActionPhase({
     contractFile: contractRel,
   });
   if (freshness.status === "REVALIDATION_REQUIRED") {
-    const refreshGuidance = await preExecutionRefreshGuidance({ target, packageRoot, state, contract });
+    const refreshGuidance = await preExecutionRefreshGuidance({ target, packageRoot, state, contract, freshness });
     return result({
       ...context,
       ...refreshGuidance,
-      nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+      nextAction: refreshGuidance.nextAction,
       reasons: freshnessReasons(state, freshness),
       requiredArtifacts: uniqueSorted([
         stateRel,
@@ -151,13 +209,15 @@ export async function resolveNextActionPhase({
     });
   }
   if (state.phase === "CONTRACT_READY") {
-    return decision(
-      context,
-      NEXT_ACTIONS.ROUTE,
-      artifactError("PHASE_CONTRACT_READY", "Persist deterministic routing for the validated contract"),
-      contractArtifacts,
-      [routeRel],
-    );
+    return result({
+      ...context,
+      nextAction: NEXT_ACTIONS.ROUTE,
+      reasons: [artifactError("PHASE_CONTRACT_READY", "Persist deterministic routing for the validated contract")],
+      commands: [`forgeloop route --task ${explicitTaskId} --work <type> --json`],
+      commandSpecs: [routeCommandSpec(explicitTaskId)],
+      requiredArtifacts: contractArtifacts,
+      missingArtifacts: [routeRel],
+    });
   }
   const routeResult = await loadArtifact(
     () => readPersistedRoute(target, packageRoot, { taskId: explicitTaskId }),
@@ -187,6 +247,8 @@ export async function resolveNextActionPhase({
       ...context,
       nextAction: NEXT_ACTIONS.RESOLVE_STALE_ROUTE,
       reasons: stale,
+      commands: [`forgeloop route --task ${explicitTaskId} --work <type> --json`],
+      commandSpecs: [routeCommandSpec(explicitTaskId)],
       requiredArtifacts,
     });
   }
@@ -214,6 +276,20 @@ export async function resolveNextActionPhase({
         ],
       });
     }
+    const staleGateErrors = PHASES_ALLOWING_GATE_REVALIDATION.has(state.phase)
+      ? (executionPrerequisites.preflight?.errors ?? []).filter((error) => error.code === "E_GATE_STALE")
+      : [];
+    if (staleGateErrors.length > 0) {
+      const gates = [...new Set(staleGateErrors.map((error) => error.gate).filter(Boolean))].sort();
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.REVALIDATE_GATES,
+        reasons: staleGateErrors,
+        commands: gates.map((gate) => `forgeloop gate-revalidate --task ${explicitTaskId} --gate ${gate} --acknowledge-stale --json`),
+        commandSpecs: gates.map((gate) => gateRevalidationCommandSpec(explicitTaskId, gate)),
+        requiredArtifacts: executionPrerequisites.requiredArtifacts,
+      });
+    }
     if (executionPrerequisites.errors.length > 0) {
       return result({
         ...context,
@@ -235,19 +311,31 @@ export async function resolveNextActionPhase({
   const preflightArtifacts = [...requiredArtifacts, preflightRel];
   const persistedPreflightErrors = phaseNeedsChronology
     ? []
-    : validatePersistedPreflight(preflightArtifact.value?.value, preflight);
+    : validatePersistedPreflight(preflightArtifact.value?.value, preflight, preflightArtifact.error);
 
   if (["ROUTED", "DESIGNING", "PLANNED"].includes(state.phase) && missingGates.length > 0) {
+    const missingGatePaths = missingGates.map((gate) => taskGatePath(state.taskId, gate));
+    const gateRecordSpec = {
+      commandId: "gate-record",
+      executable: "forgeloop",
+      subcommand: "gate-record",
+      argv: ["gate-record", `--task=${state.taskId}`, `--gate=${missingGates[0]}`, "--status=satisfied", "--json"],
+      requiredInputs: [
+        { name: "artifact", option: "--artifact=<project-relative-path>", repeatable: true },
+        { name: "decision", option: "--decision=<text>", repeatable: true },
+      ],
+    };
     return result({
       ...context,
       nextAction: NEXT_ACTIONS.SATISFY_GATES,
-      reasons: missingGates.map((gate) => artifactError(
+      reasons: missingGates.map((gate, index) => artifactError(
         "E_GATE_UNVERIFIED",
         `Required gate is missing or unverified: ${gate}`,
-        [`${ARTIFACT_PATHS.gates}/${gate}.json`],
+        [missingGatePaths[index]],
       )),
-      requiredArtifacts: [...preflightArtifacts, ...missingGates.map((gate) => `${ARTIFACT_PATHS.gates}/${gate}.json`)],
-      missingArtifacts: missingGates.map((gate) => `${ARTIFACT_PATHS.gates}/${gate}.json`),
+      requiredArtifacts: [...preflightArtifacts, ...missingGatePaths],
+      missingArtifacts: missingGatePaths,
+      commandSpecs: [gateRecordSpec],
     });
   }
   if (state.phase === "ROUTED") {

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

@@ -1,19 +1,53 @@
-import { validateEventLedger } from "./events.js";
+import { validateEventLedger, validateStateLedgerCoherence } from "./events.js";
 import { readPersistedRoute } from "./route-artifact.js";
-import { directCommandSpec } from "./next-action-model.js";
+import { directCommandSpec, NEXT_ACTIONS } from "./next-action-model.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
+import { sameCanonicalGuideList } from "./contract-bootstrap-recovery.js";
+import { CHECKPOINT_REVALIDATION_PHASES } from "./checkpoint-revalidation.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 {};
+/**
+ * Select a safe pre-execution refresh mutation. Repository-only drift keeps
+ * the checkpoint and its route identity; the legacy clear-state path remains
+ * limited to a documented blocked-preflight recovery.
+ */
+export async function preExecutionRefreshGuidance({ target, packageRoot, state, contract, freshness }) {
+  if (!["ROUTED", "DESIGNING", "PLANNED"].includes(state.phase)) return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER };
   const ledger = await validateEventLedger(target, packageRoot, { taskId: state.taskId });
-  if (!ledger.valid || ledger.events.some((entry) => entry.event === "EXECUTION_STARTED")) return {};
+  if (!ledger.valid || ledger.events.some((entry) => entry.event === "EXECUTION_STARTED")) {
+    return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER };
+  }
+  if (CHECKPOINT_REVALIDATION_PHASES.includes(state.phase)
+    && freshness?.status === "REVALIDATION_REQUIRED"
+    && [...new Set(freshness.reasons ?? [])].sort().join(",") === "REPOSITORY_CHANGED"
+    && state.contractFingerprint === contract.fingerprint) {
+    try {
+      const route = await readPersistedRoute(target, packageRoot, { taskId: state.taskId });
+      const ownership = await resolveTaskClaimState(target, { taskId: state.taskId, packageRoot });
+      const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+      const repositoryAvailable = typeof freshness.repository?.head === "string" && freshness.repository.head.length > 0;
+      const routeIdentityValid = route.value?.contractFingerprint === contract.fingerprint
+        && state.routeFingerprint === route.fingerprint
+        && sameCanonicalGuideList(state.selectedGuides, route.value.guides);
+      if (ownership.ownershipValid && ownership.mutationAllowed && repositoryAvailable
+        && coherenceErrors.length === 0 && routeIdentityValid) {
+        return {
+          nextAction: NEXT_ACTIONS.REVALIDATE_CHECKPOINT,
+          commands: [`forgeloop checkpoint-revalidate --task ${state.taskId} --json`],
+          commandSpecs: [directCommandSpec("checkpoint-revalidate", state.taskId)],
+        };
+      }
+    } catch {
+      // Unsupported or ambiguous identity stays on the fail-closed blocker.
+    }
+  }
   const lastPreflight = ledger.events.filter((entry) => ["PREFLIGHT_READY", "PREFLIGHT_BLOCKED"].includes(entry.event)).at(-1);
-  if (lastPreflight?.event !== "PREFLIGHT_BLOCKED") return {};
+  if (lastPreflight?.event !== "PREFLIGHT_BLOCKED") return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER };
   let route;
   try { route = await readPersistedRoute(target, packageRoot, { taskId: state.taskId }); }
-  catch { return {}; }
-  if (route.value.contractFingerprint !== contract.fingerprint) return {};
+  catch { return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER }; }
+  if (route.value.contractFingerprint !== contract.fingerprint) return { nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER };
   return {
+    nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
     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

@@ -1,8 +1,8 @@
 import { readJsonArtifact } from "./artifacts.js";
-import { evaluateCompletion } from "./completion.js";
+import { evaluateCompletion, receiptReadFailure } from "./completion.js";
 import { validateReceipt } from "./receipt.js";
 import { completionRelationshipErrors } from "./completion-relationships.js";
-import { evaluateRequiredEvidence, classifyRequirement } from "./evidence-readiness.js";
+import { evaluateRequiredEvidence, classifyRequirement, terminalRequirementsForContract } 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";
@@ -82,7 +82,7 @@ export async function resolveReviewingPhase({ state, context, requiredArtifacts,
         return decision(
           context,
           NEXT_ACTIONS.RESOLVE_BLOCKER,
-          artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${receipt.error.message}`, [receiptRel]),
+          receiptReadFailure(receipt.error, receiptRel),
           [...requiredArtifacts, receiptRel],
         );
       }
@@ -153,9 +153,14 @@ export async function resolveReviewingPhase({ state, context, requiredArtifacts,
         err.code === "E_PUBLICATION_REQUIREMENT_PENDING" || err.code === "E_PRODUCTION_REQUIREMENT_PENDING"
       ));
       if (terminalPendingErrors.length > 0 && terminalPendingErrors.length === completion.errors.length) {
+        const canonicalTerminalRequirements = terminalRequirementsForContract(contract.value, {
+          additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+        });
         const terminalPendingReqs = terminalPendingErrors.map((err) => {
           const reqId = err.requirementId;
-          const matchingReq = evidence.requirements.find((r) => r.id === reqId)
+          const matchingReq = canonicalTerminalRequirements.find((r) => r.id === reqId)
+            ?? canonicalTerminalRequirements.find((r) => r.text === reqId)
+            ?? evidence.requirements.find((r) => r.id === reqId)
             ?? evidence.requirements.find((r) => r.text === reqId)
             ?? classifyRequirement(reqId ?? err.message);
           return matchingReq;

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

@@ -1,3 +1,4 @@
+import { receiptReadFailure } from "./completion.js";
 import { readJsonArtifact } from "./artifacts.js";
 import { taskArtifactPath, taskStructuralQualityDirectory } from "./task-paths.js";
 import { validateReceipt } from "./receipt.js";
@@ -100,7 +101,7 @@ export async function resolveVerifyingPhase({ target, packageRoot, explicitTaskI
       return decision(
         context,
         NEXT_ACTIONS.RESOLVE_BLOCKER,
-        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${receipt.error.message}`, [receiptRel]),
+        receiptReadFailure(receipt.error, receiptRel),
         [...requiredArtifacts, receiptRel],
       );
     }

package/src/core/next-action.js

@@ -15,6 +15,9 @@ import { resolveNextActionPhase } from "./next-action-phases.js";
 import { criterionForDecision } from "./settlement-model.js";
 import { validateApprovalForAction } from "./approvals.js";
 import { evaluateActionCapability } from "./capability-policy.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "./task-context.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
 export { NEXT_ACTIONS } from "./next-action-model.js";
 
@@ -287,13 +290,41 @@ async function computeNextAction(targetOrOptions = {}, packageRootOption) {
         });
       }
     }
-    return decision(
-      {},
-      NEXT_ACTIONS.DISCOVER,
-      artifactError("WORK_STATE_ABSENT", "No work-state checkpoint is present", [stateRel]),
-      [stateRel],
-      [stateRel],
-    );
+    const events = await readEvents(target, packageRoot, { taskId: explicitTaskId });
+    if (events.some((event) => event.event === "DISCOVERY_STARTED")) {
+      return result({
+        taskId: explicitTaskId ?? "unknown",
+        currentPhase: "DISCOVERING",
+        nextAction: NEXT_ACTIONS.CREATE_CONTRACT,
+        reasons: [artifactError("PHASE_DISCOVERING", "Create and validate the task contract", [contractRel])],
+        commands: [`forgeloop contract-create --task ${explicitTaskId} --preset <documentation|bug|feature|release> --json`],
+        commandSpecs: [{
+          commandId: "contract-create",
+          executable: "forgeloop",
+          subcommand: "contract-create",
+          argv: ["contract-create", `--task=${explicitTaskId}`, "--json"],
+          requiredInputs: [{ name: "preset", option: "--preset=<documentation|bug|feature|release>" }],
+        }],
+        requiredArtifacts: [contractRel],
+        missingArtifacts: [contractRel, stateRel],
+      });
+    }
+    return result({
+      taskId: explicitTaskId ?? "unknown",
+      currentPhase: "RECEIVED",
+      nextAction: NEXT_ACTIONS.DISCOVER,
+      reasons: [artifactError("WORK_STATE_ABSENT", "No work-state checkpoint is present", [stateRel])],
+      commands: [`forgeloop discover --task ${explicitTaskId} --json`],
+      commandSpecs: [{
+        commandId: "discover",
+        executable: "forgeloop",
+        subcommand: "discover",
+        argv: ["discover", `--task=${explicitTaskId}`, "--json"],
+        requiredInputs: [],
+      }],
+      requiredArtifacts: [stateRel],
+      missingArtifacts: [stateRel],
+    });
   }
 
   return resolveNextActionPhase({
@@ -327,9 +358,25 @@ async function computeNextAction(targetOrOptions = {}, packageRootOption) {
 }
 
 export async function getNextAction(targetOrOptions = {}, packageRootOption) {
-  const res = await computeNextAction(targetOrOptions, packageRootOption);
+  const target = typeof targetOrOptions === "string" ? targetOrOptions : targetOrOptions?.target;
+  const read = () => getSelectedNextAction(targetOrOptions, packageRootOption);
+  return target ? withProjectReadSnapshot(target, read) : read();
+}
+
+async function getSelectedNextAction(targetOrOptions, packageRootOption) {
+  let normalized = typeof targetOrOptions === "string"
+    ? { target: targetOrOptions, packageRoot: packageRootOption }
+    : { ...targetOrOptions };
+  if (getOperationalStore(normalized.target)) {
+    const context = await resolveTaskContext(normalized.target, {
+      taskId: normalized.taskId,
+      packageRoot: normalized.packageRoot,
+      selectionMode: TASK_SELECTION_MODES.READ,
+    });
+    if (context) normalized = { ...normalized, taskId: context.taskId };
+  }
+  const res = await computeNextAction(normalized);
   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;