@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/command-runtime.js

@@ -0,0 +1,117 @@
+import { resolveTarget } from "./filesystem.js";
+import { getPackageRoot } from "./templates.js";
+import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
+import { COMMAND_EXECUTORS } from "./command-executors.js";
+import { defaultCommandInputValues, validateForgeLoopCommandInput } from "./command-input.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+
+export const FORGELOOP_INTEGRATION_RUNTIME_VERSION = 1;
+
+async function readPackageVersion(packageRoot) {
+  const { readFile } = await import("node:fs/promises");
+  const path = await import("node:path");
+  const packageJson = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+  return packageJson.version;
+}
+
+/**
+ * Transport-neutral ForgeLoop command execution.
+ *
+ * Resolves the project target, validates the command and its structured
+ * input, invokes the canonical executor, and returns a deterministic
+ * envelope. Performs zero terminal output, never spawns a shell to run
+ * ForgeLoop itself, never bypasses task ownership/recovery guards, and never
+ * retries mutations.
+ *
+ * A non-zero exitCode is a protocol/domain outcome (e.g. preflight BLOCKED),
+ * not an invocation failure: `ok` stays true. `ok:false` means the command
+ * could not be executed (unknown command, invalid input, canonical error).
+ */
+export async function executeForgeLoopCommand({
+  command,
+  projectPath = ".",
+  input = {},
+  authorityContext,
+  runtimeContext,
+} = {}) {
+  const metadata = Object.freeze({
+    protocolVersion: PROTOCOL_VERSION,
+    integrationApiVersion: FORGELOOP_INTEGRATION_RUNTIME_VERSION,
+  });
+
+  if (typeof command !== "string" || !CLI_COMMAND_DEFINITIONS[command]) {
+    return {
+      ok: false,
+      command: command ?? null,
+      exitCode: 1,
+      result: null,
+      error: { code: "E_COMMAND_UNSUPPORTED", message: `Unsupported ForgeLoop command: ${command ?? "(missing)"}` },
+      metadata,
+    };
+  }
+  if (CLI_COMMAND_DEFINITIONS[command].bootstrapOnly) {
+    return {
+      ok: false,
+      command,
+      exitCode: 1,
+      result: null,
+      error: { code: "E_COMMAND_UNSUPPORTED", message: `Command ${command} is not available through the programmatic runtime` },
+      metadata,
+    };
+  }
+
+  const executor = COMMAND_EXECUTORS[command];
+  if (typeof executor !== "function") {
+    return {
+      ok: false,
+      command,
+      exitCode: 1,
+      result: null,
+      error: { code: "E_COMMAND_UNSUPPORTED", message: `Command ${command} has no canonical executor` },
+      metadata,
+    };
+  }
+
+  try {
+    const options = {
+      ...defaultCommandInputValues(),
+      ...(input ?? {}),
+    };
+    validateForgeLoopCommandInput({ command, input: options });
+
+    const target = await resolveTarget(process.cwd(), projectPath);
+    const packageRoot = getPackageRoot();
+    const packageVersion = await readPackageVersion(packageRoot);
+
+    // Trusted host authority and runtime context travel out-of-band, never
+    // inside actor-controlled command input (INV-AUTH-03).
+    const { result, exitCode } = await executor({
+      target,
+      packageRoot,
+      packageVersion,
+      options,
+      authorityContext,
+      runtimeContext,
+    });
+    return {
+      ok: true,
+      command,
+      exitCode,
+      result,
+      error: null,
+      metadata: Object.freeze({ ...metadata, packageVersion }),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      command,
+      exitCode: 1,
+      result: null,
+      error: {
+        code: error.code ?? "E_COMMAND_EXECUTION_FAILED",
+        message: error.message,
+      },
+      metadata,
+    };
+  }
+}

package/src/core/completion-artifacts.js

@@ -22,9 +22,22 @@ import { normalizeRequirements } from "./evidence-readiness.js";
 import { classifyCommandResolution, validateVerificationAuthority } from "./verification-capability.js";
 import { readExecutionArtifact, validateExecutionBinding } from "./execution.js";
 import { taskArtifactPath, taskExecutionPath } from "./task-paths.js";
-import { readTaskDescriptor } from "./task-descriptor.js";
 import { assertClaimsCoverChangedPaths } from "./task-scope.js";
 import { discoverTasks } from "./task-discovery.js";
+import { listActions } from "./actions.js";
+
+async function actionReceiptSummary(target, packageRoot, taskId) {
+  const actions = await listActions(target, { packageRoot, taskId });
+  return {
+    count: actions.length,
+    required: actions.filter((action) => action.requiredForCompletion).length,
+    verified: actions.filter((action) => action.state === "VERIFIED").length,
+    failed: actions.filter((action) => action.state === "FAILED").length,
+    ambiguous: actions.filter((action) => action.state === "COMMIT_UNKNOWN").length,
+    pending: actions.filter((action) => !["VERIFIED", "FAILED", "CANCELLED"].includes(action.state)).length,
+    actionRefs: actions.map((action) => action.actionId),
+  };
+}
 
 /**
  * Canonical terminal-result types shared by runtime validation, tests, and
@@ -250,12 +263,22 @@ export async function prepareCompletion({
   if (existing && existingValue.stateFingerprint === undefined) {
     throw artifactError("E_RECEIPT_STATE_MISMATCH", "Execution receipt requires the current work-state fingerprint", [receiptRel]);
   }
+  // A checkpoint recreated after clear-state/loss starts with empty checks; a
+  // receipt still bound to the previous checkpoint fingerprint belongs to a
+  // superseded epoch and must not be adopted into the fresh one. The prior
+  // epoch remains auditable through the executions/ artifacts and the
+  // append-only ledger.
+  const receiptFromSupersededEpoch = Boolean(existing)
+    && existingValue.stateFingerprint !== undefined
+    && existingValue.stateFingerprint !== canonicalFingerprint(state)
+    && (state.checks ?? []).length === 0;
+  const adoptedValue = receiptFromSupersededEpoch ? {} : existingValue;
   assertStateIdentity({ contract, route, state });
 
   let writeClaims = [];
   try {
-    const desc = taskId ? await readTaskDescriptor(target, taskId, packageRoot) : null;
-    writeClaims = desc?.value?.writeClaims ?? [];
+    const tasks = taskId ? await discoverTasks(target, packageRoot) : [];
+    writeClaims = tasks.find((task) => task.taskId === taskId && task.healthy !== false)?.writeClaims ?? [];
   } catch {
     // descriptor may not exist
   }
@@ -287,35 +310,36 @@ export async function prepareCompletion({
 
   const changedPaths = observedPaths !== null
     ? [...observedPaths]
-    : existing
+    : !receiptFromSupersededEpoch && existing
       ? [...(existingValue.changedPaths ?? [])]
       : [];
-  const checks = existing ? [...existingValue.checks] : [...state.checks];
-  const evidence = existing ? [...(existingValue.evidence ?? [])] : [...state.verificationEvidence];
+  const checks = !receiptFromSupersededEpoch && existing ? [...existingValue.checks] : [...state.checks];
+  const evidence = !receiptFromSupersededEpoch && existing ? [...(existingValue.evidence ?? [])] : [...state.verificationEvidence];
   const receipt = await createReceipt({
-    ...existingValue,
+    ...adoptedValue,
     taskId: contract.value.taskId,
     contractFingerprint: contract.fingerprint,
     routeFingerprint: route.fingerprint,
     stateFingerprint: canonicalFingerprint(state),
     verificationCycle: state.verificationCycle ?? 1,
-    status: existingValue.status ?? "in-progress",
-    taskStatus: existingValue.taskStatus ?? "in-progress",
-    verificationStatus: existingValue.verificationStatus ?? "not-verified",
-    publicationStatus: existingValue.publicationStatus ?? "local-only",
-    productionReadiness: existingValue.productionReadiness ?? "not-verified",
+    status: adoptedValue.status ?? "in-progress",
+    taskStatus: adoptedValue.taskStatus ?? "in-progress",
+    verificationStatus: adoptedValue.verificationStatus ?? "not-verified",
+    publicationStatus: adoptedValue.publicationStatus ?? "local-only",
+    productionReadiness: adoptedValue.productionReadiness ?? "not-verified",
     selectedGuides: [...route.value.guides],
     changedPaths,
     checks,
+    actions: await actionReceiptSummary(target, packageRoot, contract.value.taskId),
     evidence,
     evidenceCoverage: coverageForRequirements(requiredEvidence, checks, {
       target,
       taskId: contract.value.taskId,
       options: { authorityContext, runtimeContext },
     }),
-    review: existingValue.review ?? { status: "not-run", independent: false },
-    limitations: [...(existingValue.limitations ?? [])],
-    publication: existingValue.publication ?? {
+    review: adoptedValue.review ?? { status: "not-run", independent: false },
+    limitations: [...(adoptedValue.limitations ?? [])],
+    publication: adoptedValue.publication ?? {
       committed: false,
       pushed: false,
       pullRequest: null,

package/src/core/completion-ownership.js

@@ -0,0 +1,88 @@
+import { LIFECYCLE_MILESTONES, validateStateLedgerCoherence } from "./events.js";
+
+export const CANONICAL_COMPLETION_EVENT = "COMPLETION_VALIDATED";
+
+/**
+ * Canonical completion ownership proof: the minimal, validator-backed evidence
+ * that the lifecycle itself officially reached COMPLETE. This is intentionally
+ * NOT a re-run of full publication/receipt/evidence semantics — it only proves
+ * that claim ownership may be released because canonical completion exists.
+ *
+ * Returns `{ valid: true, completionEvent }` or `{ valid: false, errors }`.
+ */
+export function validateCompletionOwnershipProof({ taskId, state, ledger }) {
+  const errors = [];
+  if (!taskId || typeof taskId !== "string") {
+    return { valid: false, errors: [{ code: "E_COMPLETION_OWNERSHIP_UNPROVEN", message: "Completion ownership proof requires a taskId" }] };
+  }
+  if (!state || state.phase !== "COMPLETE") {
+    errors.push({ code: "E_COMPLETION_OWNERSHIP_UNPROVEN", message: "Work-state phase is not COMPLETE" });
+  }
+  if (!ledger || ledger.valid !== true) {
+    errors.push({
+      code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+      message: `Task event ledger is invalid; completion cannot be proven${ledger?.errors?.length
+        ? `: ${ledger.errors.map((error) => error.message).join("; ")}`
+        : ""}`,
+    });
+  }
+
+  let completionEvent = null;
+  if (ledger && Array.isArray(ledger.events)) {
+    if (ledger.events.some((event) => event.taskId !== taskId)) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: "Ledger contains an event belonging to a different task",
+      });
+    }
+    const candidates = ledger.events
+      .filter((event) => event.event === CANONICAL_COMPLETION_EVENT && event.taskId === taskId);
+    if (candidates.length === 0) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: `No canonical ${CANONICAL_COMPLETION_EVENT} event exists for this task`,
+      });
+    } else if (candidates.length > 1) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: `Multiple ${CANONICAL_COMPLETION_EVENT} events exist; completion is ambiguous`,
+      });
+    } else {
+      completionEvent = candidates[0];
+    }
+  }
+
+  if (state && ledger && Array.isArray(ledger.events)) {
+    const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+    if (coherenceErrors.length > 0) {
+      for (const error of coherenceErrors) {
+        errors.push({
+          code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+          message: `State/ledger coherence invalid: ${error.message}`,
+        });
+      }
+    }
+  }
+
+  // No contradictory lifecycle activity may follow the canonical completion:
+  // any milestone at or after VERIFICATION_RECORDED occurring after the
+  // completion event means the lifecycle moved past terminal state.
+  if (completionEvent && ledger && Array.isArray(ledger.events)) {
+    const completionIndex = ledger.events.indexOf(completionEvent);
+    const contradiction = ledger.events.slice(completionIndex + 1).find((event) => {
+      const index = LIFECYCLE_MILESTONES.indexOf(event.event);
+      return index >= LIFECYCLE_MILESTONES.indexOf("VERIFICATION_RECORDED");
+    });
+    if (contradiction) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: `Lifecycle event ${contradiction.event} follows canonical completion; terminal state contradicted`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, completionEvent: null, errors };
+  }
+  return { valid: true, completionEvent };
+}

package/src/core/completion-recovery-rebind.js

@@ -0,0 +1,194 @@
+import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { appendProtocolEvent, validateCompletionRecoveryAuthorization, validateEventLedger } from "./events.js";
+import { createReceipt } from "./receipt.js";
+import { taskArtifactPath } from "./task-paths.js";
+import { mutateWorkState, readWorkState } from "./work-state.js";
+
+function resolveArtifactPath(key, taskId, override) {
+  if (override) return override;
+  return taskId ? taskArtifactPath(taskId, key) : ARTIFACT_PATHS[key];
+}
+
+const FINGERPRINT_MISMATCH_CODES = new Set([
+  "E_COMPLETION_REJECTION_STATE_FINGERPRINT_MISMATCH",
+  "E_COMPLETION_REJECTION_RECEIPT_FINGERPRINT_MISMATCH",
+]);
+
+export function isFingerprintOnlyRecoveryMismatch(errors = []) {
+  return Array.isArray(errors)
+    && errors.length > 0
+    && errors.every((error) => FINGERPRINT_MISMATCH_CODES.has(error?.code));
+}
+
+function sortedValues(values) {
+  return [...new Set(values ?? [])].sort();
+}
+
+function sameSortedValues(left, right) {
+  return JSON.stringify(sortedValues(left)) === JSON.stringify(sortedValues(right));
+}
+
+function findMatchingRejectionEvent(events, attempt, cycle) {
+  let latestReviewIndex = -1;
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    if (event.event === "REVIEW_STARTED" && (event.details?.verificationCycle ?? 1) === cycle) {
+      latestReviewIndex = index;
+    }
+  }
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event.event !== "COMPLETION_REJECTED") continue;
+    if ((event.details?.verificationCycle ?? 1) !== cycle) continue;
+    if (index < latestReviewIndex) continue;
+    return { event, index };
+  }
+  return null;
+}
+
+/**
+ * Rebind a persisted REJECTED completion attempt to the current work-state
+ * checkpoint when the only authorization failures are fingerprint mismatches.
+ *
+ * Repository drift or a recovery/resume cycle can mutate work-state after a
+ * completion rejection was persisted, so the ledger snapshot no longer matches
+ * the live checkpoint. Without rebinding, every sanctioned closure path refuses
+ * (reconcile-closure and REVIEWING -> VERIFYING require authorized completion
+ * recovery; complete cannot persist a fresh evidence-only rejection while the
+ * checkpoint is stale), which deadlocks the task.
+ *
+ * The rebind is append-only and logically conservative:
+ *   - the rejection reasonCodes, missingRequirementIds, and verification cycle
+ *     must be logically identical between work-state and the latest matching
+ *     ledger rejection; any logical difference is refused,
+ *   - the original COMPLETION_REJECTED event is never modified; a rebound
+ *     rejection carrying the current fingerprints is appended,
+ *   - the execution receipt is re-bound to the current checkpoint when present.
+ */
+export async function rebindCompletionRejectionSnapshot({
+  target,
+  packageRoot,
+  taskId = null,
+  statePath = null,
+  receiptPath = null,
+  eventsPath = null,
+  authorityContext,
+  runtimeContext,
+} = {}) {
+  const statePathResolved = resolveArtifactPath("state", taskId, statePath);
+  const receiptPathResolved = resolveArtifactPath("receipt", taskId, receiptPath);
+  const state = await readWorkState(target, { packageRoot, taskId, statePath: statePathResolved });
+  if (!state || state.phase !== "REVIEWING") {
+    return { rebound: false };
+  }
+  const attempt = state.lastCompletionAttempt;
+  if (!attempt || attempt.status !== "REJECTED") {
+    return { rebound: false };
+  }
+
+  const ledger = await validateEventLedger(target, packageRoot, { taskId, eventsPath });
+  if (!ledger.valid) {
+    return { rebound: false };
+  }
+  const cycle = attempt.verificationCycle ?? state.verificationCycle ?? 1;
+  const matching = findMatchingRejectionEvent(ledger.events, attempt, cycle);
+  if (!matching) {
+    return { rebound: false };
+  }
+  const details = matching.event.details ?? {};
+  const logicalMatch = (details.verificationCycle ?? 1) === cycle
+    && sameSortedValues(details.reasonCodes, attempt.reasonCodes)
+    && sameSortedValues(details.missingRequirementIds, attempt.missingRequirementIds);
+  if (!logicalMatch) {
+    return { rebound: false };
+  }
+
+  const next = await mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath: statePathResolved,
+  }, () => ({
+    ...state,
+    revision: (state.revision ?? 0) + 1,
+    lastUpdated: new Date().toISOString(),
+  }));
+
+  let reboundReceiptFingerprint;
+  try {
+    const receipt = await readJsonArtifact(target, receiptPathResolved, "execution-receipt", packageRoot);
+    const reboundReceipt = await createReceipt({
+      ...receipt.value,
+      stateFingerprint: canonicalFingerprint(next),
+      verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
+    }, packageRoot, { target, taskId, authorityContext, runtimeContext });
+    await writeJsonArtifact(target, receiptPathResolved, reboundReceipt, "execution-receipt", packageRoot);
+    reboundReceiptFingerprint = canonicalFingerprint(reboundReceipt);
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+
+  await appendProtocolEvent(target, {
+    taskId: state.taskId,
+    event: "COMPLETION_REJECTED",
+    details: {
+      verificationCycle: cycle,
+      reasonCodes: sortedValues(details.reasonCodes),
+      missingRequirementIds: sortedValues(details.missingRequirementIds),
+      stateFingerprint: canonicalFingerprint(next),
+      ...(reboundReceiptFingerprint ? { receiptFingerprint: reboundReceiptFingerprint } : {}),
+      ...(details.stateFingerprint ? { reboundFromStateFingerprint: details.stateFingerprint } : {}),
+    },
+  }, packageRoot, { taskId, eventsPath });
+
+  return { rebound: true, state: next };
+}
+
+export async function authorizeCompletionRecoveryOrRebind({
+  target,
+  packageRoot,
+  taskId = null,
+  statePath = null,
+  receiptPath = null,
+  eventsPath = null,
+  authorityContext,
+  runtimeContext,
+} = {}) {
+  const statePathResolved = resolveArtifactPath("state", taskId, statePath);
+  const receiptPathResolved = resolveArtifactPath("receipt", taskId, receiptPath);
+  const resolveArtifacts = async () => {
+    const state = await readWorkState(target, { packageRoot, taskId, statePath: statePathResolved });
+    let receipt = null;
+    try {
+      receipt = (await readJsonArtifact(target, receiptPathResolved, "execution-receipt", packageRoot))?.value ?? null;
+    } catch {
+      receipt = null;
+    }
+    const events = (await validateEventLedger(target, packageRoot, { taskId, eventsPath })).events;
+    return { state, receipt, events };
+  };
+
+  const initial = await resolveArtifacts();
+  const recoveryAuth = validateCompletionRecoveryAuthorization(initial);
+  if (recoveryAuth.authorized || !isFingerprintOnlyRecoveryMismatch(recoveryAuth.errors)) {
+    return { ...initial, recoveryAuth, rebound: false };
+  }
+
+  const reboundResult = await rebindCompletionRejectionSnapshot({
+    target,
+    packageRoot,
+    taskId,
+    statePath,
+    receiptPath,
+    eventsPath,
+    authorityContext,
+    runtimeContext,
+  });
+  if (!reboundResult.rebound) {
+    return { ...initial, recoveryAuth, rebound: false };
+  }
+
+  const rebounded = await resolveArtifacts();
+  const reboundAuth = validateCompletionRecoveryAuthorization(rebounded);
+  return { ...rebounded, recoveryAuth: reboundAuth, rebound: reboundAuth.authorized };
+}

package/src/core/completion.js

@@ -13,6 +13,25 @@ import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
 import { evaluateTerminalRequirements } from "./evidence-readiness.js";
 import { PROJECT_ARTIFACT_PATHS, taskArtifactPath } from "./task-paths.js";
 import { detectPolicyCapability, evaluateTargetPolicy } from "./policy-engine.js";
+import { listActions } from "./actions.js";
+
+async function actionReceiptSummary(target, packageRoot, taskId) {
+  const actions = await listActions(target, { packageRoot, taskId });
+  const { evaluateRequiredActionReadiness } = await import("./action-readiness.js");
+  const readiness = await evaluateRequiredActionReadiness({ target, packageRoot, taskId });
+  return {
+    count: actions.length,
+    required: readiness.total,
+    verified: actions.filter((action) => action.state === "VERIFIED").length,
+    // Raw state counts are observability only; trusted completion is below.
+    trustedSatisfied: readiness.satisfied,
+    unresolvedRequired: readiness.unresolved,
+    failed: actions.filter((action) => action.state === "FAILED").length,
+    ambiguous: actions.filter((action) => action.state === "COMMIT_UNKNOWN").length,
+    pending: actions.filter((action) => !["VERIFIED", "FAILED", "CANCELLED"].includes(action.state)).length,
+    actionRefs: actions.map((action) => action.actionId),
+  };
+}
 
 /**
  * Canonical completion return statuses shared by the runtime, tests, and
@@ -424,6 +443,44 @@ export async function evaluateCompletion({
     }
   }
 
+  const actionTaskId = contract?.value?.taskId ?? taskId;
+  const durableActions = actionTaskId
+    ? await listActions(target, { packageRoot, taskId: actionTaskId })
+    : [];
+  const contractRequirements = new Set([
+    ...(contract?.value?.verification ?? []), ...(contract?.value?.successCriteria ?? []),
+  ]);
+  // Completion truth consumes the canonical action-readiness projection, not
+  // raw state labels: a forged VERIFIED label can never satisfy a required
+  // action (INV-VERIFY-02).
+  const { evaluateRequiredActionReadiness } = await import("./action-readiness.js");
+  const requiredActionReadiness = actionTaskId
+    ? await evaluateRequiredActionReadiness({ target, packageRoot, taskId: actionTaskId })
+    : { total: 0, satisfied: 0, unresolved: 0, ambiguous: 0, failed: 0, untrusted: 0, actions: [] };
+  for (const readiness of requiredActionReadiness.actions) {
+    if (readiness.status === "SATISFIED") continue;
+    const action = durableActions.find((candidate) => candidate.actionId === readiness.actionId);
+    if (
+      readiness.status === "FAILED"
+      && action?.state === "CANCELLED"
+      && action.requirement
+      && !contractRequirements.has(action.requirement)
+    ) {
+      continue;
+    }
+    const code = readiness.status === "AMBIGUOUS"
+      ? "E_ACTION_RECONCILIATION_REQUIRED"
+      : readiness.status === "UNTRUSTED"
+        ? "E_ACTION_VERIFICATION_REQUIRED"
+        : "E_ACTION_STATE_MISMATCH";
+    errors.push(issue(
+      code,
+      `Required action ${readiness.actionId} is not trusted-satisfied (${readiness.status}): ${readiness.reasons[0] ?? ""}`,
+      [taskArtifactPath(action?.taskId ?? actionTaskId, "actions")],
+      { actionId: readiness.actionId, actionState: action?.state, readiness: readiness.status },
+    ));
+  }
+
   const sortedErrors = sortIssues(errors);
   const valid = sortedErrors.length === 0;
   return {
@@ -440,6 +497,17 @@ export async function evaluateCompletion({
       status: ledger.valid ? "valid" : "invalid",
       events: ledger.events.length,
     },
+    actions: {
+      count: durableActions.length,
+      required: requiredActionReadiness.total,
+      verified: durableActions.filter((action) => action.state === "VERIFIED").length,
+      trustedSatisfied: requiredActionReadiness.satisfied,
+      unresolvedRequired: requiredActionReadiness.unresolved,
+      failed: durableActions.filter((action) => action.state === "FAILED").length,
+      ambiguous: durableActions.filter((action) => action.state === "COMMIT_UNKNOWN").length,
+      pending: durableActions.filter((action) => !["VERIFIED", "FAILED", "CANCELLED"].includes(action.state)).length,
+      actionRefs: durableActions.map((action) => action.actionId),
+    },
   };
 }
 
@@ -528,6 +596,7 @@ export async function runComplete({
       if (receipt) {
         nextReceipt = await createReceipt({
           ...receipt.value,
+          actions: await actionReceiptSummary(target, packageRoot, state.taskId),
           stateFingerprint: canonicalFingerprint(next),
           verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
         }, packageRoot, { target, taskId: state.taskId, authorityContext, runtimeContext });
@@ -574,6 +643,7 @@ export async function runComplete({
       next.revision = (state.revision ?? 0) + 1;
       const nextReceipt = await createReceipt({
         ...receipt.value,
+        actions: await actionReceiptSummary(target, packageRoot, state.taskId),
         stateFingerprint: canonicalFingerprint(next),
         verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
       }, packageRoot, { target, taskId: state.taskId, authorityContext, runtimeContext });

package/src/core/continuity-reconciliation.js

@@ -169,20 +169,25 @@ export function classifyContinuity({
   });
 }
 
-export async function reconcileContinuity({ target, packageRoot } = {}) {
+export async function reconcileContinuity({ target, packageRoot, taskId = null } = {}) {
   const [{ readWorkState }, { readContract }, repository] = await Promise.all([
     import("./work-state.js"),
     import("./contract.js"),
     import("./repository.js"),
   ]);
 
-  const state = await readWorkState(target, packageRoot);
+  const state = await readWorkState(target, { packageRoot, taskId });
   let continuityArtifact;
   try {
-    continuityArtifact = await readContinuity(target, packageRoot);
+    continuityArtifact = await readContinuity(target, { packageRoot, taskId });
   } catch (error) {
     if (error.code === "ARTIFACT_MISSING") {
-      return { ...classifyContinuity({ continuity: null, state }), path: ".forgeloop/continuity.json", present: false };
+      return {
+        ...classifyContinuity({ continuity: null, state }),
+        path: ".forgeloop/continuity.json",
+        present: false,
+        diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
+      };
     }
     return {
       ...baseResult("INVALID", {
@@ -197,7 +202,7 @@ export async function reconcileContinuity({ target, packageRoot } = {}) {
 
   let contractFingerprint = null;
   try {
-    const contract = await readContract(target, packageRoot);
+    const contract = await readContract(target, packageRoot, { taskId });
     contractFingerprint = contract.fingerprint;
   } catch {
     contractFingerprint = null;
@@ -220,5 +225,19 @@ export async function reconcileContinuity({ target, packageRoot } = {}) {
     present: true,
     fingerprint: continuityArtifact.fingerprint,
     continuity: continuityArtifact.value,
+    diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
   };
 }
+
+async function deriveDiagnosticContextSafe({ target, packageRoot, state }) {
+  try {
+    const [{ readEvents }, { deriveDiagnosticContext }] = await Promise.all([
+      import("./events.js"),
+      import("./reflection.js"),
+    ]);
+    const events = await readEvents(target, packageRoot, { taskId: state?.taskId ?? null });
+    return { present: true, ...deriveDiagnosticContext(events, state) };
+  } catch {
+    return { present: false };
+  }
+}