@cassiomc1/forgeloop 1.9.0 → 1.10.1

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/portable-context.js

@@ -0,0 +1,103 @@
+import { assertJsonLimits } from "./json-safety.js";
+import { assertSecretFree } from "./receipt.js";
+import { E_PORTABLE_CONTEXT_INVALID } from "./error-codes.js";
+
+export class PortableContextError extends Error {
+  constructor(message, { code = E_PORTABLE_CONTEXT_INVALID, cause } = {}) {
+    super(message, cause !== undefined ? { cause } : undefined);
+    this.name = "PortableContextError";
+    this.code = code;
+  }
+}
+
+const PORTABLE_SECRET_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/i,
+  /(?:^|\s)(?:sk|ghp|glpat|xox[baprs])-[-_a-z0-9]{8,}/i,
+  /(?:AKIA|ASIA)[A-Z0-9]{12,}/,
+  /(?:bearer\s+[-_a-z0-9\.]{4,})/i,
+  /(?:authorization:\s*bearer)/i,
+];
+
+function containsSecretPattern(str) {
+  return PORTABLE_SECRET_PATTERNS.some((pattern) => pattern.test(str));
+}
+
+function checkObjectForSecrets(value, location = "$") {
+  if (typeof value === "string") {
+    if (containsSecretPattern(value)) {
+      throw new Error(`${location}: secret-like value is not allowed`);
+    }
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => checkObjectForSecrets(item, `${location}[${index}]`));
+  } else {
+    for (const [key, child] of Object.entries(value)) {
+      checkObjectForSecrets(child, `${location}.${key}`);
+    }
+  }
+}
+
+export function normalizePortableText(
+  value,
+  {
+    label = "portable text",
+    maxLength,
+    optional = false,
+  } = {},
+) {
+  if (value === undefined || value === null) {
+    if (optional) return null;
+    throw new PortableContextError(`${label} is required`);
+  }
+
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new PortableContextError(`${label} must be a non-empty string`);
+  }
+
+  if (typeof maxLength === "number" && value.length > maxLength) {
+    throw new PortableContextError(`${label} exceeds the ${maxLength}-character limit`);
+  }
+
+  if (/\p{Cc}/u.test(value)) {
+    throw new PortableContextError(`${label} contains control characters`);
+  }
+
+  return value;
+}
+
+export function assertPortableContextSafe(
+  value,
+  {
+    label = "portable context",
+  } = {},
+) {
+  try {
+    assertJsonLimits(value, label);
+    assertSecretFree(value);
+    checkObjectForSecrets(value, label);
+    return value;
+  } catch (error) {
+    if (error.code === E_PORTABLE_CONTEXT_INVALID) {
+      throw error;
+    }
+    throw new PortableContextError(
+      `${label} failed safety verification: ${error.message}`,
+      { code: E_PORTABLE_CONTEXT_INVALID, cause: error },
+    );
+  }
+}
+
+export function deepFreeze(object) {
+  if (object === null || typeof object !== "object" || Object.isFrozen(object)) {
+    return object;
+  }
+  Object.freeze(object);
+  for (const value of Object.values(object)) {
+    if (value !== null && typeof value === "object") {
+      deepFreeze(value);
+    }
+  }
+  return object;
+}