@cassiomc1/forgeloop 1.12.0 → 1.14.0

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,
@@ -238,16 +314,28 @@ export async function resolveNextActionPhase({
     : validatePersistedPreflight(preflightArtifact.value?.value, preflight);
 
   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

@@ -2,7 +2,7 @@ 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 { 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";
@@ -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.js

@@ -287,13 +287,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({

package/src/core/next-explanation.js

@@ -0,0 +1,63 @@
+const MAX_EXPLANATION_TEXT = 240;
+const MAX_EXPLANATION_REASON_CODE = 96;
+const MAX_EXPLANATION_ARTIFACT_TEXT = 240;
+const MAX_EXPLANATION_REASONS = 3;
+const MAX_EXPLANATION_ARTIFACTS = 6;
+
+const REQUIRED_CHANGES = Object.freeze({
+  E_CONTRACT_STALE: "Refresh the contract-bound checkpoint and route before continuing.",
+  E_ROUTE_STALE: "Re-run the canonical route for the current contract before continuing.",
+  E_REPOSITORY_CHANGED: "Revalidate the repository and record new evidence before continuing.",
+  E_RECEIPT_STALE: "Inspect the receipt boundary and obtain a fresh independently verifiable receipt.",
+  E_RECEIPT_MISSING: "Provide the required task-bound receipt or record the check as unavailable.",
+  E_CHECK_OBSERVATION_REQUIRED: "Run the required check through an observable verification boundary and record its result.",
+  E_TASK_SCOPE_CONFLICT: "Resolve the overlapping task ownership through the canonical task recovery or coordination path.",
+  E_VERIFICATION_EXECUTION_INVALID: "Repair or replace the verification execution boundary before recording evidence.",
+  E_PUBLICATION_REQUIREMENT_PENDING: "Obtain independently verifiable publication evidence; do not infer publication from local checks.",
+});
+
+function bounded(value, limit = MAX_EXPLANATION_TEXT) {
+  const text = String(value ?? "").trim();
+  return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+}
+
+function reasonExplanation(reason) {
+  const source = reason && typeof reason === "object" ? reason : {};
+  const artifacts = [...new Set((Array.isArray(source.artifacts) ? source.artifacts : [])
+    .filter((artifact) => typeof artifact === "string" && artifact.length > 0)
+    .map((artifact) => bounded(artifact, MAX_EXPLANATION_ARTIFACT_TEXT)))]
+    .slice(0, MAX_EXPLANATION_ARTIFACTS);
+  return {
+    code: bounded(source.code ?? "E_NEXT_ACTION_BLOCKED", MAX_EXPLANATION_REASON_CODE),
+    failedInvariant: bounded(source.message),
+    safeArtifacts: artifacts,
+    requiredChange: REQUIRED_CHANGES[source.code] ?? "Satisfy the canonical condition described by this reason before continuing.",
+    evidenceNeeded: artifacts.length > 0
+      ? `Inspect or update only the listed protocol artifacts, then re-run the canonical next action.`
+      : "Provide a fresh, scoped, independently observable result for the blocked condition.",
+  };
+}
+
+export function explainNextAction(result) {
+  const reasons = (Array.isArray(result?.reasons) ? result.reasons : [])
+    .slice(0, MAX_EXPLANATION_REASONS)
+    .map(reasonExplanation);
+  const mutating = (Array.isArray(result?.commandSpecs) ? result.commandSpecs : []).some((spec) => [
+    "advance",
+    "clear-state",
+    "complete",
+    "record-check",
+    "record-diagnosis",
+    "record-intervention",
+    "prepare-completion",
+    "route",
+  ].includes(spec.commandId));
+  return {
+    schemaVersion: 1,
+    summary: bounded(`Next action ${result?.nextAction ?? "UNKNOWN"} is required for phase ${result?.currentPhase ?? "UNKNOWN"}.`),
+    actionKind: mutating ? "MUTATING_COMMAND_MAY_BE_REQUIRED" : "READ_ONLY_OR_HOST_ACTION",
+    requiresExternalAuthority: Boolean(result?.authorityRequired || result?.hostActionRequired || result?.approvalRequired),
+    reasons,
+    bounded: true,
+  };
+}