@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/src/core/command-input.js

@@ -1,4 +1,11 @@
 import { continuityOptionDefaults, validateContinuityOptions } from "./continuity-cli-options.js";
+import { E_CLI_INVOCATION_INVALID } from "./error-codes.js";
+
+function inputError(message) {
+  const error = new Error(message);
+  error.code = E_CLI_INVOCATION_INVALID;
+  return error;
+}
 
 /**
  * Transport-neutral option defaults shared by the CLI parser and the
@@ -39,11 +46,35 @@ export function defaultCommandInputValues() {
     checkDetails: null,
     checkExecutionRef: null,
     checkProvenance: null,
+    timeoutMs: null,
+    scopeRef: null,
     commandArgv: [],
     checkType: null,
     checkSource: null,
     policy: null,
     taskId: null,
+    recipientHint: null,
+    handoffNote: null,
+    handoffId: null,
+    responsibilityLabel: null,
+    responsibilityAllowedPaths: [],
+    responsibilityReadOnlyPaths: [],
+    responsibilityRequiredChecks: [],
+    responsibilityFreezeContract: false,
+    responsibilityFreezeRoute: false,
+    responsibilityFreezeClaims: false,
+    verificationScopeMode: null,
+    revisionProvider: null,
+    signingProvider: null,
+    trustedRoot: null,
+    baseRevision: null,
+    headRevision: null,
+    requireCompleteCoverage: false,
+    requireSignature: false,
+    attestationRef: null,
+    attestationBundle: null,
+    attestationIdentity: null,
+    attestationIssuer: null,
     help: false,
     version: false,
     ...continuityOptionDefaults(),
@@ -60,48 +91,68 @@ export function validateForgeLoopCommandInput({ command, input, help = false } =
   if (!command) return;
 
   if (command === "policy" && !options.policy) {
-    throw new Error("policy requires a name");
+    throw inputError("policy requires a name");
   }
   if (command !== "policy" && options.policy) {
-    throw new Error(`Policy name is not valid for ${command}`);
+    throw inputError(`Policy name is not valid for ${command}`);
   }
   if (command === "bundle" && !options.taskId) {
-    throw new Error("bundle requires --task");
+    throw inputError("bundle requires --task");
   }
   if (command === "task-create" && !options.taskId) {
-    throw new Error("task-create requires --task");
+    throw inputError("task-create requires --task");
+  }
+  if (["workspace-bind", "workspace-status", "handoff-create", "handoff-list", "handoff-show", "responsibility-set", "responsibility-status", "verify-scope", "attestation-create", "attestation-status", "attestation-verify"].includes(command)
+    && !options.taskId) {
+    throw inputError(`${command} requires --task`);
+  }
+  if (command === "handoff-show" && !help && !options.handoffId) {
+    throw inputError("handoff-show requires --id");
+  }
+  if (command === "responsibility-set" && !help && !options.responsibilityLabel) {
+    throw inputError("responsibility-set requires --label");
+  }
+  if (command === "verify-scope" && !help) {
+    const mode = String(options.verificationScopeMode ?? "AUTO").toUpperCase();
+    if (!["AUTO", "CHANGED", "CLAIMED", "FULL"].includes(mode)) {
+      throw inputError("verify-scope --mode must be AUTO, CHANGED, CLAIMED, or FULL");
+    }
+  }
+  if (command === "attestation-verify-range" && !help) {
+    if (!options.baseRevision) throw inputError("attestation-verify-range requires --base");
+    if (!options.headRevision) throw inputError("attestation-verify-range requires --head");
   }
 
   validateContinuityOptions(command, options);
 
   if (command === "record-check" && !help) {
-    if (!options.checkId) throw new Error("record-check requires --id");
-    if (!options.checkRequirement) throw new Error("record-check requires --requirement");
-    if (!options.checkStatus) throw new Error("record-check requires --status");
-    if (!options.checkEvidenceKind) throw new Error("record-check requires --evidence-kind");
-    if (!options.checkCommand && !options.checkResult) throw new Error("record-check requires --command or --result");
+    if (!options.checkId) throw inputError("record-check requires --id");
+    if (!options.checkRequirement) throw inputError("record-check requires --requirement");
+    if (!options.checkStatus) throw inputError("record-check requires --status");
+    if (!options.checkEvidenceKind) throw inputError("record-check requires --evidence-kind");
+    if (!options.checkCommand && !options.checkResult) throw inputError("record-check requires --command or --result");
   }
   if (command === "run-check" && !help) {
-    if (!options.checkId) throw new Error("run-check requires --id");
-    if (!options.checkRequirement) throw new Error("run-check requires --requirement");
+    if (!options.checkId) throw inputError("run-check requires --id");
+    if (!options.checkRequirement) throw inputError("run-check requires --requirement");
     if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
       || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
-      throw new Error("run-check accepts only --id, --requirement, --details, --timeout-ms, and -- <argv>");
+      throw inputError("run-check accepts only --id, --requirement, --details, --timeout-ms, --scope-ref, and -- <argv>");
     }
     if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) {
-      throw new Error("run-check requires -- followed by an exact command argv");
+      throw inputError("run-check requires -- followed by an exact command argv");
     }
   }
   if (command === "reconcile-closure" && !help) {
-    if (!options.taskId) throw new Error("reconcile-closure requires --task");
-    if (!options.checkId) throw new Error("reconcile-closure requires --id");
-    if (!options.checkRequirement) throw new Error("reconcile-closure requires --requirement");
+    if (!options.taskId) throw inputError("reconcile-closure requires --task");
+    if (!options.checkId) throw inputError("reconcile-closure requires --id");
+    if (!options.checkRequirement) throw inputError("reconcile-closure requires --requirement");
     if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
       || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
-      throw new Error("reconcile-closure accepts only --id, --requirement, --details, and -- <argv>");
+      throw inputError("reconcile-closure accepts only --id, --requirement, --details, and -- <argv>");
     }
     if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) {
-      throw new Error("reconcile-closure requires -- followed by an exact command argv");
+      throw inputError("reconcile-closure requires -- followed by an exact command argv");
     }
   }
 }

package/src/core/command-runtime.js

@@ -4,6 +4,7 @@ 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";
+import { exitCodeForError } from "./exit-codes.js";
 
 export const FORGELOOP_INTEGRATION_RUNTIME_VERSION = 1;
 
@@ -105,7 +106,7 @@ export async function executeForgeLoopCommand({
     return {
       ok: false,
       command,
-      exitCode: 1,
+      exitCode: exitCodeForError(error),
       result: null,
       error: {
         code: error.code ?? "E_COMMAND_EXECUTION_FAILED",

package/src/core/completion.js

@@ -1,6 +1,6 @@
 import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { requiredEvidenceForTarget, validateChecksExecutionProvenance } from "./completion-artifacts.js";
-import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger, validateStateLedgerCoherence } from "./events.js";
+import { appendProtocolEvent, previewProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger, validateStateLedgerCoherence } from "./events.js";
 import { evaluatePreflight } from "./preflight.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
@@ -11,9 +11,29 @@ import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { evaluateStartExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
 import { evaluateTerminalRequirements } from "./evidence-readiness.js";
-import { PROJECT_ARTIFACT_PATHS, taskArtifactPath } from "./task-paths.js";
+import { PROJECT_ARTIFACT_PATHS, taskArtifactPath, taskCodeManifestPath } from "./task-paths.js";
 import { detectPolicyCapability, evaluateTargetPolicy } from "./policy-engine.js";
 import { listActions } from "./actions.js";
+import { readConfig } from "./config.js";
+import { resolveResponsibilityStatus } from "./responsibility.js";
+import { createCodeManifest, readCodeManifest, validateCodeManifestBindings, writeCodeManifest } from "./code-manifest.js";
+import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
+
+async function attestationConfiguration(target, packageRoot, errors) {
+  try {
+    const config = await readConfig(target, packageRoot);
+    return {
+      mode: config.attestation?.mode ?? "off",
+      revisionProvider: config.attestation?.revisionProvider ?? "git",
+      requireCompleteCoverage: config.attestation?.requireCompleteCoverage === true,
+      signing: config.attestation?.signing ?? { provider: "none", required: false, policy: {} },
+    };
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return { mode: "off", revisionProvider: "git", requireCompleteCoverage: false, signing: { provider: "none", required: false, policy: {} } };
+    errors.push(issue(error.code ?? "E_ATTESTATION_INVALID", `Attestation configuration is invalid: ${error.message}`, [PROJECT_ARTIFACT_PATHS.config]));
+    return { mode: "off", revisionProvider: "git", requireCompleteCoverage: false, signing: { provider: "none", required: false, policy: {} } };
+  }
+}
 
 async function actionReceiptSummary(target, packageRoot, taskId) {
   const actions = await listActions(target, { packageRoot, taskId });
@@ -290,6 +310,59 @@ export async function evaluateCompletion({
     [receiptRel],
     errors,
   );
+  const attestationConfig = await attestationConfiguration(target, packageRoot, errors);
+  let attestation = {
+    mode: attestationConfig.mode,
+    status: attestationConfig.mode === "off" ? "DISABLED" : "MISSING",
+    level: "PROCESSED",
+    manifest: null,
+    revisionProvider: attestationConfig.revisionProvider,
+    requireCompleteCoverage: attestationConfig.requireCompleteCoverage,
+  };
+
+  if (state?.phase === "COMPLETE" && attestationConfig.mode !== "off") {
+    try {
+      const manifest = await readCodeManifest({ target, packageRoot, taskId: contract?.value?.taskId ?? taskId });
+      await validateCodeManifestBindings({
+        target,
+        packageRoot,
+        taskId: contract?.value?.taskId ?? taskId,
+        manifest: manifest.value,
+        revisionProvider: attestationConfig.revisionProvider,
+      });
+      attestation = {
+        ...attestation,
+        status: "CAPTURED",
+        level: "VERIFIED",
+        manifest: { path: manifest.path, fingerprint: manifest.fingerprint, contentDigest: manifest.value.contentDigest },
+      };
+    } catch (error) {
+      if (attestationConfig.mode === "required") {
+        errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_ATTESTATION_MANIFEST_MISSING" : error.code ?? "E_ATTESTATION_MANIFEST_STALE", error.message, error.artifacts ?? [taskArtifactPath(contract?.value?.taskId ?? taskId, "attestations")]));
+      }
+      attestation = {
+        ...attestation,
+        status: error.code === "ARTIFACT_MISSING" ? "MISSING" : "UNAVAILABLE",
+        error: { code: error.code ?? "E_ATTESTATION_MANIFEST_STALE", message: error.message },
+      };
+    }
+  }
+
+  let responsibility = { status: "NOT_APPLICABLE", taskId: contract?.value?.taskId ?? taskId, errors: [] };
+  if (taskId || contract?.value?.taskId) {
+    try {
+      responsibility = await resolveResponsibilityStatus(target, {
+        packageRoot,
+        taskId: contract?.value?.taskId ?? taskId,
+      });
+      for (const error of responsibility.errors ?? []) {
+        errors.push(issue(error.code, error.message, [responsibility.path ?? taskArtifactPath(taskId, "responsibility")]));
+      }
+    } catch (error) {
+      errors.push(issue(error.code ?? "E_RESPONSIBILITY_INVALID", error.message, [taskArtifactPath(taskId, "responsibility")]));
+      responsibility = { status: "INVALID", taskId: contract?.value?.taskId ?? taskId, errors: [{ code: error.code ?? "E_RESPONSIBILITY_INVALID", message: error.message }] };
+    }
+  }
 
   if (state && hasExecutionStarted(state.phase)) {
     const prerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot, taskId, statePath, contractPath, routePath });
@@ -508,10 +581,15 @@ export async function evaluateCompletion({
       pending: durableActions.filter((action) => !["VERIFIED", "FAILED", "CANCELLED"].includes(action.state)).length,
       actionRefs: durableActions.map((action) => action.actionId),
     },
+    responsibility: {
+      status: responsibility.status,
+      ...(responsibility.fingerprint ? { fingerprint: responsibility.fingerprint } : {}),
+    },
+    attestation,
   };
 }
 
-export async function runComplete({
+async function runCompleteInternal({
   target,
   packageRoot,
   strict = false,
@@ -631,6 +709,7 @@ export async function runComplete({
     const state = await readWorkState(target, { packageRoot, taskId, statePath });
     if (state && state.phase !== "COMPLETE") {
       const receipt = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
+      const contract = await readContract(target, packageRoot, { taskId, contractPath });
       const next = {
         ...state,
         previousPhase: state.phase,
@@ -647,6 +726,47 @@ export async function runComplete({
         stateFingerprint: canonicalFingerprint(next),
         verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
       }, packageRoot, { target, taskId: state.taskId, authorityContext, runtimeContext });
+      const ledger = await validateEventLedger(target, packageRoot, { taskId, eventsPath });
+      const existingCompletion = ledger.events.find((event) => event.taskId === contract.value.taskId && event.event === "COMPLETION_VALIDATED");
+      const completionEvent = existingCompletion ?? await previewProtocolEvent(target, {
+        taskId: contract.value.taskId,
+        event: "COMPLETION_VALIDATED",
+      }, packageRoot, { taskId, eventsPath });
+      let manifestCapture = null;
+      const attestationConfig = result.attestation ?? { mode: "off", revisionProvider: "git" };
+      if (attestationConfig.mode !== "off") {
+        try {
+          manifestCapture = await createCodeManifest({
+            target,
+            packageRoot,
+            taskId: contract.value.taskId,
+            revisionProvider: attestationConfig.revisionProvider,
+            baseRevision: state.repositoryFingerprint?.head ?? null,
+            headRevision: "WORKTREE",
+            captureMode: "WORKTREE",
+            candidateState: next,
+            candidateReceipt: nextReceipt,
+            candidateCompletionCheckpoint: { seq: completionEvent.seq, hash: completionEvent.hash },
+          });
+          result.attestation = {
+            ...result.attestation,
+            status: "CAPTURED",
+            level: "VERIFIED",
+            manifest: {
+              path: taskCodeManifestPath(contract.value.taskId),
+              fingerprint: manifestCapture.fingerprint,
+              contentDigest: manifestCapture.manifest.contentDigest,
+            },
+          };
+        } catch (error) {
+          if (attestationConfig.mode === "required") throw error;
+          result.attestation = {
+            ...result.attestation,
+            status: "UNAVAILABLE",
+            error: { code: error.code ?? "E_ATTESTATION_MANIFEST_INVALID", message: error.message },
+          };
+        }
+      }
       await mutateWorkState(target, {
         expectedRevision: state.revision ?? 0,
         packageRoot,
@@ -654,12 +774,54 @@ export async function runComplete({
         statePath,
       }, () => next);
       await writeJsonArtifact(target, receiptRel, nextReceipt, "execution-receipt", packageRoot);
-    }
-    const contract = await readContract(target, packageRoot, { taskId, contractPath });
-    const ledger = await validateEventLedger(target, packageRoot, { taskId, eventsPath });
-    if (!ledger.events.some((event) => event.taskId === contract.value.taskId && event.event === "COMPLETION_VALIDATED")) {
-      await appendProtocolEvent(target, { taskId: contract.value.taskId, event: "COMPLETION_VALIDATED" }, packageRoot, { taskId, eventsPath });
+      if (!existingCompletion) {
+        const persistedCompletion = await appendProtocolEvent(target, {
+          taskId: contract.value.taskId,
+          event: "COMPLETION_VALIDATED",
+          at: completionEvent.at,
+        }, packageRoot, { taskId, eventsPath });
+        if (persistedCompletion.hash !== completionEvent.hash) {
+          throw new Error("Precomputed completion event changed before persistence");
+        }
+      }
+      if (manifestCapture) {
+        const manifestArtifact = await writeCodeManifest({
+          target,
+          packageRoot,
+          taskId: contract.value.taskId,
+          manifest: manifestCapture.manifest,
+        });
+        await appendProtocolEvent(target, {
+          taskId: contract.value.taskId,
+          event: "CODE_MANIFEST_CAPTURED",
+          fingerprint: manifestArtifact.fingerprint,
+          details: {
+            manifestFingerprint: manifestArtifact.fingerprint,
+            contentDigest: manifestCapture.manifest.contentDigest,
+            coveredPaths: new Set(manifestCapture.manifest.entries.flatMap((entry) => [entry.path, entry.sourcePath].filter(Boolean))).size,
+            verificationCycle: manifestCapture.manifest.verificationCycle,
+          },
+        }, packageRoot, { taskId, eventsPath });
+      }
+    } else if (state?.phase === "COMPLETE" && result.attestation?.status === "MISSING" && result.attestation.mode === "required") {
+      const error = new Error("Required code manifest is missing from a COMPLETE task");
+      error.code = "E_ATTESTATION_MANIFEST_MISSING";
+      throw error;
     }
   }
   return result;
 }
+
+export async function runComplete(options = {}) {
+  const taskId = options.taskId ?? null;
+  if (options.persist !== false && taskId && !getActiveTaskTransaction()) {
+    return withTaskTransaction({
+      target: options.target,
+      taskId,
+      packageRoot: options.packageRoot,
+      operation: "complete",
+      recordCommitEvent: true,
+    }, () => runCompleteInternal(options));
+  }
+  return runCompleteInternal(options);
+}

package/src/core/config.js

@@ -1,20 +1,76 @@
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { E_ATTESTATION_CONFIGURATION_INVALID } from "./error-codes.js";
+import { normalizeVerificationConfiguration } from "./verification-scope-capability.js";
 
 export const CONFIG_SCHEMA_VERSION = 1;
 export const COMPLIANCE_MODES = Object.freeze(["advisory", "standard", "strict"]);
+export const ATTESTATION_MODES = Object.freeze(["off", "optional", "required"]);
 
 function stringArray(value, label) {
   if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
-    throw new Error(`${label} must be an array of non-empty strings`);
+    const error = new Error(`${label} must be an array of non-empty strings`);
+    error.code = E_ATTESTATION_CONFIGURATION_INVALID;
+    throw error;
   }
   return [...new Set(value)];
 }
 
+function configurationError(message) {
+  const error = new Error(message);
+  error.code = E_ATTESTATION_CONFIGURATION_INVALID;
+  return error;
+}
+
 export function createConfig(input = {}) {
   const complianceMode = input.complianceMode ?? "standard";
   if (!COMPLIANCE_MODES.includes(complianceMode)) {
-    throw new Error(`Unknown compliance mode: ${complianceMode}`);
+    throw configurationError(`Unknown compliance mode: ${complianceMode}`);
+  }
+  let attestation;
+  if (input.attestation !== undefined) {
+    if (!input.attestation || typeof input.attestation !== "object" || Array.isArray(input.attestation)) {
+      throw configurationError("attestation must be an object");
+    }
+    const mode = input.attestation.mode ?? "optional";
+    if (!ATTESTATION_MODES.includes(mode)) throw configurationError(`Unknown attestation mode: ${mode}`);
+    const revisionProvider = input.attestation.revisionProvider ?? "git";
+    if (typeof revisionProvider !== "string" || !revisionProvider.trim()) throw configurationError("attestation.revisionProvider must be a non-empty string");
+    const signing = input.attestation.signing ?? {};
+    if (!signing || typeof signing !== "object" || Array.isArray(signing)) {
+      throw configurationError("attestation.signing must be an object");
+    }
+    const provider = signing.provider ?? "none";
+    if (!["none", "sigstore"].includes(provider)) throw configurationError(`Unknown attestation signing provider: ${provider}`);
+    const policy = signing.policy ?? {};
+    if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+      throw configurationError("attestation.signing.policy must be an object");
+    }
+    if (policy.issuer !== undefined && typeof policy.issuer !== "string") throw configurationError("attestation.signing.policy.issuer must be a string");
+    if (policy.identities !== undefined) stringArray(policy.identities, "attestation.signing.policy.identities");
+    attestation = {
+      mode,
+      revisionProvider,
+      requireCompleteCoverage: input.attestation.requireCompleteCoverage === true,
+      coverage: { exclude: stringArray(input.attestation.coverage?.exclude ?? [], "attestation.coverage.exclude") },
+      signing: {
+        provider,
+        required: signing.required === true,
+        policy: {
+          ...(policy.issuer !== undefined ? { issuer: policy.issuer } : {}),
+          identities: [...(policy.identities ?? [])],
+          requireTransparencyLog: policy.requireTransparencyLog !== false,
+        },
+      },
+    };
+  }
+  let verification;
+  if (input.verification !== undefined) {
+    try {
+      verification = normalizeVerificationConfiguration(input.verification);
+    } catch (error) {
+      throw configurationError(error.message);
+    }
   }
   return {
     schemaVersion: CONFIG_SCHEMA_VERSION,
@@ -23,6 +79,8 @@ export function createConfig(input = {}) {
     ...(input.policy !== undefined ? { policy: input.policy } : {}),
     ...(input.requiredGates !== undefined ? { requiredGates: stringArray(input.requiredGates, "requiredGates") } : {}),
     ...(input.requiredEvidence !== undefined ? { requiredEvidence: stringArray(input.requiredEvidence, "requiredEvidence") } : {}),
+    ...(verification ? { verification } : {}),
+    ...(attestation ? { attestation } : {}),
   };
 }
 

package/src/core/continuity-cli-options.js

@@ -8,6 +8,12 @@ const OPTION_FIELDS = Object.freeze({
   "--resume-note": ["continuityResumeNote", false],
 });
 
+function continuityInputError(message) {
+  const error = new Error(message);
+  error.code = "E_CLI_INVOCATION_INVALID";
+  return error;
+}
+
 export function continuityOptionDefaults() {
   return {
     continuityFocusId: null,
@@ -24,7 +30,7 @@ export function consumeContinuityOption({ argument, argv, index, options }) {
   const definition = OPTION_FIELDS[argument];
   if (!definition) return { handled: false, index };
   const value = argv[index + 1];
-  if (!value || value.startsWith("-")) throw new Error(`${argument} requires a value`);
+  if (!value || value.startsWith("-")) throw continuityInputError(`${argument} requires a value`);
   const [field, repeatable] = definition;
   if (repeatable) options[field].push(value);
   else options[field] = value;
@@ -45,13 +51,13 @@ export function hasContinuityOptions(options = {}) {
 
 export function validateContinuityOptions(command, options = {}) {
   if (command !== "record-continuity" && hasContinuityOptions(options)) {
-    throw new Error(`Continuity recording options are not valid for ${command}`);
+    throw continuityInputError(`Continuity recording options are not valid for ${command}`);
   }
   if (command === "record-continuity") {
     const hasFocusId = Boolean(options.continuityFocusId);
     const hasFocusSummary = Boolean(options.continuityFocusSummary);
     if (hasFocusId !== hasFocusSummary) {
-      throw new Error("record-continuity requires --focus-id and --focus-summary together");
+      throw continuityInputError("record-continuity requires --focus-id and --focus-summary together");
     }
   }
   return options;

package/src/core/continuity-reconciliation.js

@@ -177,6 +177,7 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
   ]);
 
   const state = await readWorkState(target, { packageRoot, taskId });
+  const latestHandoff = await resolveLatestHandoffSafe(target, { packageRoot, taskId: state?.taskId ?? taskId });
   let continuityArtifact;
   try {
     continuityArtifact = await readContinuity(target, { packageRoot, taskId });
@@ -186,6 +187,7 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
         ...classifyContinuity({ continuity: null, state }),
         path: ".forgeloop/continuity.json",
         present: false,
+        latestHandoff,
         diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
       };
     }
@@ -197,6 +199,7 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
       path: ".forgeloop/continuity.json",
       present: true,
       error: error.message,
+      latestHandoff,
     };
   }
 
@@ -225,10 +228,27 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
     present: true,
     fingerprint: continuityArtifact.fingerprint,
     continuity: continuityArtifact.value,
+    latestHandoff,
     diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
   };
 }
 
+async function resolveLatestHandoffSafe(target, { packageRoot, taskId } = {}) {
+  if (!taskId) return null;
+  try {
+    const { resolveLatestHandoff } = await import("./handoff.js");
+    return await resolveLatestHandoff(target, { packageRoot, taskId });
+  } catch (error) {
+    return {
+      status: "INVALID",
+      error: {
+        code: error.code ?? "E_HANDOFF_INVALID",
+        message: error.message,
+      },
+    };
+  }
+}
+
 async function deriveDiagnosticContextSafe({ target, packageRoot, state }) {
   try {
     const [{ readEvents }, { deriveDiagnosticContext }] = await Promise.all([

package/src/core/diagnostic-projection.js

@@ -30,7 +30,9 @@ export function resolveCurrentCycleDiagnostic(events, taskId, verificationCycle)
   const candidates = diagnosticEventsForTask(events, taskId)
     .filter((event) => {
       const cycle = event.details?.verificationCycle;
-      return verificationCycle == null || cycle == null || cycle === verificationCycle;
+      return (verificationCycle === null || verificationCycle === undefined)
+        || (cycle === null || cycle === undefined)
+        || cycle === verificationCycle;
     })
     .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));