@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/src/core/error-codes.js

@@ -32,6 +32,106 @@ export const E_TASK_SCOPE_FROZEN = "E_TASK_SCOPE_FROZEN";
 export const E_TASK_CHANGE_OUTSIDE_SCOPE = "E_TASK_CHANGE_OUTSIDE_SCOPE";
 export const E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE = "E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE";
 
+export const E_WORKSPACE_IDENTITY_UNAVAILABLE = "E_WORKSPACE_IDENTITY_UNAVAILABLE";
+export const E_WORKSPACE_BINDING_INVALID = "E_WORKSPACE_BINDING_INVALID";
+export const E_WORKSPACE_BINDING_MISMATCH = "E_WORKSPACE_BINDING_MISMATCH";
+export const E_HANDOFF_INVALID = "E_HANDOFF_INVALID";
+export const E_HANDOFF_STATE_UNAVAILABLE = "E_HANDOFF_STATE_UNAVAILABLE";
+export const E_HANDOFF_TAMPERED = "E_HANDOFF_TAMPERED";
+export const E_HANDOFF_NOT_FOUND = "E_HANDOFF_NOT_FOUND";
+export const E_RESPONSIBILITY_INVALID = "E_RESPONSIBILITY_INVALID";
+export const E_RESPONSIBILITY_SCOPE_VIOLATION = "E_RESPONSIBILITY_SCOPE_VIOLATION";
+export const E_RESPONSIBILITY_FROZEN_INPUT_DRIFT = "E_RESPONSIBILITY_FROZEN_INPUT_DRIFT";
+export const E_RESPONSIBILITY_REQUIRED_CHECK_MISSING = "E_RESPONSIBILITY_REQUIRED_CHECK_MISSING";
+export const E_VERIFICATION_SCOPE_INVALID = "E_VERIFICATION_SCOPE_INVALID";
+export const E_VERIFICATION_SCOPE_STALE = "E_VERIFICATION_SCOPE_STALE";
+export const E_VERIFICATION_SCOPE_UNRESOLVED = "E_VERIFICATION_SCOPE_UNRESOLVED";
+export const E_REVISION_PROVIDER_UNAVAILABLE = "E_REVISION_PROVIDER_UNAVAILABLE";
+export const E_REVISION_PROVIDER_AMBIGUOUS = "E_REVISION_PROVIDER_AMBIGUOUS";
+export const E_REVISION_PROVIDER_INVALID = "E_REVISION_PROVIDER_INVALID";
+export const E_REVISION_NOT_FOUND = "E_REVISION_NOT_FOUND";
+export const E_REVISION_CONTENT_UNAVAILABLE = "E_REVISION_CONTENT_UNAVAILABLE";
+export const E_ATTESTATION_DISABLED = "E_ATTESTATION_DISABLED";
+export const E_ATTESTATION_GIT_REQUIRED = "E_ATTESTATION_GIT_REQUIRED";
+export const E_ATTESTATION_MANIFEST_MISSING = "E_ATTESTATION_MANIFEST_MISSING";
+export const E_ATTESTATION_MANIFEST_INVALID = "E_ATTESTATION_MANIFEST_INVALID";
+export const E_ATTESTATION_MANIFEST_STALE = "E_ATTESTATION_MANIFEST_STALE";
+export const E_ATTESTATION_CONTENT_MISMATCH = "E_ATTESTATION_CONTENT_MISMATCH";
+export const E_ATTESTATION_SCOPE_MISMATCH = "E_ATTESTATION_SCOPE_MISMATCH";
+export const E_ATTESTATION_COVERAGE_GAP = "E_ATTESTATION_COVERAGE_GAP";
+export const E_ATTESTATION_COVERAGE_CONFLICT = "E_ATTESTATION_COVERAGE_CONFLICT";
+export const E_ATTESTATION_STATEMENT_MISSING = "E_ATTESTATION_STATEMENT_MISSING";
+export const E_ATTESTATION_STATEMENT_INVALID = "E_ATTESTATION_STATEMENT_INVALID";
+export const E_ATTESTATION_SUBJECT_MISMATCH = "E_ATTESTATION_SUBJECT_MISMATCH";
+export const E_ATTESTATION_RECEIPT_MISMATCH = "E_ATTESTATION_RECEIPT_MISMATCH";
+export const E_ATTESTATION_STATE_MISMATCH = "E_ATTESTATION_STATE_MISMATCH";
+export const E_ATTESTATION_ROUTE_MISMATCH = "E_ATTESTATION_ROUTE_MISMATCH";
+export const E_ATTESTATION_CONTRACT_MISMATCH = "E_ATTESTATION_CONTRACT_MISMATCH";
+export const E_ATTESTATION_LEDGER_MISMATCH = "E_ATTESTATION_LEDGER_MISMATCH";
+export const E_ATTESTATION_UNSIGNED = "E_ATTESTATION_UNSIGNED";
+export const E_ATTESTATION_SIGNATURE_INVALID = "E_ATTESTATION_SIGNATURE_INVALID";
+export const E_ATTESTATION_SIGNER_UNAVAILABLE = "E_ATTESTATION_SIGNER_UNAVAILABLE";
+export const E_ATTESTATION_IDENTITY_UNTRUSTED = "E_ATTESTATION_IDENTITY_UNTRUSTED";
+export const E_ATTESTATION_ISSUER_UNTRUSTED = "E_ATTESTATION_ISSUER_UNTRUSTED";
+export const E_ATTESTATION_TARGET_REF_INVALID = "E_ATTESTATION_TARGET_REF_INVALID";
+export const E_ATTESTATION_INVALID = "E_ATTESTATION_INVALID";
+export const E_ATTESTATION_CONFIGURATION_INVALID = "E_ATTESTATION_CONFIGURATION_INVALID";
+export const E_CLI_INVOCATION_INVALID = "E_CLI_INVOCATION_INVALID";
+
+const EXTENSION_PUBLIC_ERROR_CODES = Object.freeze(Object.fromEntries([
+  E_WORKSPACE_IDENTITY_UNAVAILABLE,
+  E_WORKSPACE_BINDING_INVALID,
+  E_WORKSPACE_BINDING_MISMATCH,
+  E_HANDOFF_INVALID,
+  E_HANDOFF_STATE_UNAVAILABLE,
+  E_HANDOFF_TAMPERED,
+  E_HANDOFF_NOT_FOUND,
+  E_RESPONSIBILITY_INVALID,
+  E_RESPONSIBILITY_SCOPE_VIOLATION,
+  E_RESPONSIBILITY_FROZEN_INPUT_DRIFT,
+  E_RESPONSIBILITY_REQUIRED_CHECK_MISSING,
+  E_VERIFICATION_SCOPE_INVALID,
+  E_VERIFICATION_SCOPE_STALE,
+  E_VERIFICATION_SCOPE_UNRESOLVED,
+  E_REVISION_PROVIDER_UNAVAILABLE,
+  E_REVISION_PROVIDER_AMBIGUOUS,
+  E_REVISION_PROVIDER_INVALID,
+  E_REVISION_NOT_FOUND,
+  E_REVISION_CONTENT_UNAVAILABLE,
+  E_ATTESTATION_DISABLED,
+  E_ATTESTATION_GIT_REQUIRED,
+  E_ATTESTATION_MANIFEST_MISSING,
+  E_ATTESTATION_MANIFEST_INVALID,
+  E_ATTESTATION_MANIFEST_STALE,
+  E_ATTESTATION_CONTENT_MISMATCH,
+  E_ATTESTATION_SCOPE_MISMATCH,
+  E_ATTESTATION_COVERAGE_GAP,
+  E_ATTESTATION_COVERAGE_CONFLICT,
+  E_ATTESTATION_STATEMENT_MISSING,
+  E_ATTESTATION_STATEMENT_INVALID,
+  E_ATTESTATION_SUBJECT_MISMATCH,
+  E_ATTESTATION_RECEIPT_MISMATCH,
+  E_ATTESTATION_STATE_MISMATCH,
+  E_ATTESTATION_ROUTE_MISMATCH,
+  E_ATTESTATION_CONTRACT_MISMATCH,
+  E_ATTESTATION_LEDGER_MISMATCH,
+  E_ATTESTATION_UNSIGNED,
+  E_ATTESTATION_SIGNATURE_INVALID,
+  E_ATTESTATION_SIGNER_UNAVAILABLE,
+  E_ATTESTATION_IDENTITY_UNTRUSTED,
+  E_ATTESTATION_ISSUER_UNTRUSTED,
+  E_ATTESTATION_TARGET_REF_INVALID,
+  E_ATTESTATION_INVALID,
+  E_ATTESTATION_CONFIGURATION_INVALID,
+  E_CLI_INVOCATION_INVALID,
+].map((code) => [code, Object.freeze({
+  code,
+  category: code.slice(2).split("_")[0].toLowerCase(),
+  classification: "PUBLIC_STABLE",
+  meaning: "A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied.",
+  safeResolution: "Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command.",
+})])));
+
 export const E_TASK_LAYOUT_LEGACY = "E_TASK_LAYOUT_LEGACY";
 export const E_TASK_MIGRATION_INVALID = "E_TASK_MIGRATION_INVALID";
 export const E_TASK_RECOVERY_UNSAFE = "E_TASK_RECOVERY_UNSAFE";
@@ -114,6 +214,7 @@ export const E_TRAJECTORY_REFERENCE_REQUIRED = "E_TRAJECTORY_REFERENCE_REQUIRED"
  * Public, stable ForgeLoop error and reason codes documented for users and harnesses.
  */
 export const PUBLIC_ERROR_CODES = Object.freeze({
+  ...EXTENSION_PUBLIC_ERROR_CODES,
   E_PREFLIGHT_NOT_READY: Object.freeze({
     code: "E_PREFLIGHT_NOT_READY",
     category: "preflight",
@@ -880,6 +981,51 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_SCOPE_DIRTY,
   E_TASK_SCOPE_FROZEN,
   E_TASK_CHANGE_OUTSIDE_SCOPE,
+  E_WORKSPACE_IDENTITY_UNAVAILABLE,
+  E_WORKSPACE_BINDING_INVALID,
+  E_WORKSPACE_BINDING_MISMATCH,
+  E_HANDOFF_INVALID,
+  E_HANDOFF_STATE_UNAVAILABLE,
+  E_HANDOFF_TAMPERED,
+  E_HANDOFF_NOT_FOUND,
+  E_RESPONSIBILITY_INVALID,
+  E_RESPONSIBILITY_SCOPE_VIOLATION,
+  E_RESPONSIBILITY_FROZEN_INPUT_DRIFT,
+  E_RESPONSIBILITY_REQUIRED_CHECK_MISSING,
+  E_VERIFICATION_SCOPE_INVALID,
+  E_VERIFICATION_SCOPE_STALE,
+  E_VERIFICATION_SCOPE_UNRESOLVED,
+  E_REVISION_PROVIDER_UNAVAILABLE,
+  E_REVISION_PROVIDER_AMBIGUOUS,
+  E_REVISION_PROVIDER_INVALID,
+  E_REVISION_NOT_FOUND,
+  E_REVISION_CONTENT_UNAVAILABLE,
+  E_ATTESTATION_DISABLED,
+  E_ATTESTATION_GIT_REQUIRED,
+  E_ATTESTATION_MANIFEST_MISSING,
+  E_ATTESTATION_MANIFEST_INVALID,
+  E_ATTESTATION_MANIFEST_STALE,
+  E_ATTESTATION_CONTENT_MISMATCH,
+  E_ATTESTATION_SCOPE_MISMATCH,
+  E_ATTESTATION_COVERAGE_GAP,
+  E_ATTESTATION_COVERAGE_CONFLICT,
+  E_ATTESTATION_STATEMENT_MISSING,
+  E_ATTESTATION_STATEMENT_INVALID,
+  E_ATTESTATION_SUBJECT_MISMATCH,
+  E_ATTESTATION_RECEIPT_MISMATCH,
+  E_ATTESTATION_STATE_MISMATCH,
+  E_ATTESTATION_ROUTE_MISMATCH,
+  E_ATTESTATION_CONTRACT_MISMATCH,
+  E_ATTESTATION_LEDGER_MISMATCH,
+  E_ATTESTATION_UNSIGNED,
+  E_ATTESTATION_SIGNATURE_INVALID,
+  E_ATTESTATION_SIGNER_UNAVAILABLE,
+  E_ATTESTATION_IDENTITY_UNTRUSTED,
+  E_ATTESTATION_ISSUER_UNTRUSTED,
+  E_ATTESTATION_TARGET_REF_INVALID,
+  E_ATTESTATION_INVALID,
+  E_ATTESTATION_CONFIGURATION_INVALID,
+  E_CLI_INVOCATION_INVALID,
   E_RECONCILE_NOT_STALE,
   E_RECONCILE_PHASE_INVALID,
   E_RECONCILE_UNSUPPORTED_DRIFT,

package/src/core/events.js

@@ -148,6 +148,42 @@ export function validateKnownEventDetails(event) {
         throw protocolError("E_EVENT_INVALID", "TRAJECTORY_EVALUATED requires a bound evaluationId, scenarioId, and fingerprint");
       }
       return;
+    case "WORKSPACE_BOUND":
+      assertStructuredArtifactEvent(event, ["workspaceFingerprint"], "WORKSPACE_BOUND");
+      return;
+    case "HANDOFF_CREATED":
+      if (!event.details || typeof event.details !== "object" || Array.isArray(event.details)
+        || typeof event.details.handoffId !== "string" || !/^handoff-[A-Za-z0-9_-]+$/.test(event.details.handoffId)
+        || typeof event.details.artifact !== "string" || !event.details.artifact
+        || typeof event.details.digest !== "string") {
+        throw protocolError("E_EVENT_INVALID", "HANDOFF_CREATED requires a handoff ID, artifact path, and digest");
+      }
+      assertFingerprint(event.details.digest, "HANDOFF_CREATED details.digest");
+      return;
+    case "RESPONSIBILITY_SET":
+      assertStructuredArtifactEvent(event, ["responsibilityFingerprint"], "RESPONSIBILITY_SET");
+      if (typeof event.details.label !== "string" || !event.details.label) {
+        throw protocolError("E_EVENT_INVALID", "RESPONSIBILITY_SET details.label must be a non-empty string");
+      }
+      return;
+    case "VERIFICATION_SCOPE_CAPTURED":
+      assertStructuredArtifactEvent(event, ["scopeFingerprint"], "VERIFICATION_SCOPE_CAPTURED");
+      if (!["AUTO", "CHANGED", "CLAIMED", "FULL"].includes(event.details.resolvedMode)
+        || !Number.isInteger(event.details.verificationCycle) || event.details.verificationCycle < 1) {
+        throw protocolError("E_EVENT_INVALID", "VERIFICATION_SCOPE_CAPTURED requires a valid mode and verification cycle");
+      }
+      return;
+    case "CODE_MANIFEST_CAPTURED":
+      assertStructuredArtifactEvent(event, ["manifestFingerprint"], "CODE_MANIFEST_CAPTURED");
+      assertFingerprint(event.details.contentDigest, "CODE_MANIFEST_CAPTURED details.contentDigest");
+      if (!Number.isInteger(event.details.coveredPaths) || event.details.coveredPaths < 0) {
+        throw protocolError("E_EVENT_INVALID", "CODE_MANIFEST_CAPTURED details.coveredPaths must be a non-negative integer");
+      }
+      return;
+    case "ATTESTATION_STATEMENT_CREATED":
+      assertStructuredArtifactEvent(event, ["statementFingerprint"], "ATTESTATION_STATEMENT_CREATED");
+      assertFingerprint(event.details.manifestFingerprint, "ATTESTATION_STATEMENT_CREATED details.manifestFingerprint");
+      return;
     default:
       if (isActionEventName(event.event)) {
         assertActionEventDetails(event);
@@ -167,6 +203,27 @@ function assertStringList(value, label) {
   }
 }
 
+function assertFingerprint(value, label) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+    throw protocolError("E_EVENT_INVALID", `${label} must be a lowercase SHA-256 fingerprint`);
+  }
+}
+
+function assertStructuredArtifactEvent(event, requiredDetails, label) {
+  if (!event.details || typeof event.details !== "object" || Array.isArray(event.details)) {
+    throw protocolError("E_EVENT_INVALID", `${label} requires structured details`);
+  }
+  for (const key of requiredDetails) {
+    if (typeof event.details[key] !== "string" || !event.details[key]) {
+      throw protocolError("E_EVENT_INVALID", `${label} details.${key} must be a non-empty string`);
+    }
+    assertFingerprint(event.details[key], `${label} details.${key}`);
+  }
+  if (event.fingerprint !== event.details[requiredDetails[0]]) {
+    throw protocolError("E_EVENT_INVALID", `${label} fingerprint must match details.${requiredDetails[0]}`);
+  }
+}
+
 function assertRecoveryRecordedDetails(details) {
   if (!details || typeof details !== "object" || Array.isArray(details)) {
     throw protocolError("E_EVENT_INVALID", "recovery event requires structured details");
@@ -221,6 +278,44 @@ export function eventHash(event) {
   return canonicalFingerprint(body);
 }
 
+export function buildProtocolEvent(input, { checkpoint } = {}) {
+  if (!checkpoint || !Number.isInteger(checkpoint.seq) || checkpoint.seq < 0
+    || (checkpoint.lastHash !== null && !/^[a-f0-9]{64}$/.test(checkpoint.lastHash))) {
+    throw protocolError("E_EVENT_INVALID", "event checkpoint is invalid");
+  }
+  const event = {
+    seq: checkpoint.seq + 1,
+    schemaVersion: EVENT_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: input.taskId,
+    event: input.event,
+    at: input.at ?? new Date().toISOString(),
+    ...(input.fingerprint ? { fingerprint: input.fingerprint } : {}),
+    previousHash: checkpoint.lastHash,
+    ...(input.details ? { details: structuredClone(input.details) } : {}),
+  };
+  validateKnownEventDetails(event);
+  assertSecretFree(event);
+  event.hash = eventHash(event);
+  return event;
+}
+
+export async function previewProtocolEvent(target, input, packageRoot, options = {}) {
+  const activeTransaction = getActiveTaskTransaction();
+  if (!activeTransaction) {
+    return withTaskTransaction({
+      target,
+      taskId: options.taskId ?? input.taskId,
+      lockTaskId: options.taskId ?? input.taskId,
+      operation: "preview-event",
+      packageRoot,
+    }, async () => previewProtocolEvent(target, input, packageRoot, options));
+  }
+  const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
+  const checkpoint = await readEventCheckpoint(target, packageRoot, relPath, options, activeTransaction);
+  return buildProtocolEvent(input, { checkpoint });
+}
+
 function protocolError(code, message, artifacts = [ARTIFACT_PATHS.events]) {
   const error = new Error(message);
   error.code = code;
@@ -232,6 +327,11 @@ export async function readEvents(target, packageRoot, options = {}) {
   const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
   await assertSafePath(target, relPath);
   const eventsPath = ensureWithin(target, relPath);
+  const transaction = getActiveTaskTransaction();
+  if (transaction) {
+    const stagedText = await transaction.readText(relPath);
+    if (stagedText !== null) return parseEventsText(stagedText, relPath, packageRoot);
+  }
   if (!(await fileExists(eventsPath))) return [];
   const text = await readFile(eventsPath, "utf8");
   return parseEventsText(text, relPath, packageRoot);
@@ -245,6 +345,14 @@ export async function readEventTail(target, packageRoot, options = {}) {
   const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
   await assertSafePath(target, relPath);
   const eventsPath = ensureWithin(target, relPath);
+  const transaction = getActiveTaskTransaction();
+  if (transaction) {
+    const stagedText = await transaction.readText(relPath);
+    if (stagedText !== null) {
+      const lines = stagedText.split(/\r?\n/).filter((line) => line.trim() !== "");
+      return parseEventsText(lines.slice(-limit).join("\n"), relPath, packageRoot);
+    }
+  }
   if (!(await fileExists(eventsPath))) return [];
   const size = (await stat(eventsPath)).size;
   let window = Math.min(size, 64 * 1024);
@@ -306,19 +414,7 @@ export async function appendProtocolEvent(target, input, packageRoot, options =
     }, async () => appendProtocolEvent(target, input, packageRoot, options));
   }
   const checkpoint = await readEventCheckpoint(target, packageRoot, relPath, options, activeTransaction);
-  const event = {
-    seq: checkpoint.seq + 1,
-    schemaVersion: EVENT_SCHEMA_VERSION,
-    protocolVersion: PROTOCOL_VERSION,
-    taskId: input.taskId,
-    event: input.event,
-    at: input.at ?? new Date().toISOString(),
-    ...(input.fingerprint ? { fingerprint: input.fingerprint } : {}),
-    previousHash: checkpoint.lastHash,
-    ...(input.details ? { details: structuredClone(input.details) } : {}),
-  };
-  validateKnownEventDetails(event);
-  assertSecretFree(event);
+  const event = buildProtocolEvent(input, { checkpoint });
   const schema = await readSchema("event", packageRoot);
   assertSchema(event, schema, relPath);
   event.hash = eventHash(event);

package/src/core/exit-codes.js

@@ -0,0 +1,22 @@
+const ENVIRONMENT_OR_PROVIDER_CODES = new Set([
+  "E_CLI_INVOCATION_INVALID",
+  "E_REPOSITORY_GIT_COMMAND_FAILED",
+  "E_REVISION_PROVIDER_UNAVAILABLE",
+  "E_REVISION_PROVIDER_AMBIGUOUS",
+  "E_REVISION_PROVIDER_INVALID",
+  "E_REVISION_NOT_FOUND",
+  "E_REVISION_CONTENT_UNAVAILABLE",
+  "E_ATTESTATION_GIT_REQUIRED",
+  "E_ATTESTATION_CONFIGURATION_INVALID",
+  "E_ATTESTATION_SIGNER_UNAVAILABLE",
+  "E_ATTESTATION_TARGET_REF_INVALID",
+]);
+
+export function exitCodeForError(error) {
+  return ENVIRONMENT_OR_PROVIDER_CODES.has(error?.code) ? 2 : 1;
+}
+
+export function exitCodeForAttestationResult(result) {
+  if (result?.status === "VALID") return 0;
+  return result?.errors?.some((error) => ENVIRONMENT_OR_PROVIDER_CODES.has(error?.code)) ? 2 : 1;
+}

package/src/core/handoff.js

@@ -0,0 +1,208 @@
+import { randomUUID } from "node:crypto";
+import { readdir } from "node:fs/promises";
+
+import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { assertSecretFree } from "./receipt.js";
+import { appendProtocolEvent } from "./events.js";
+import { currentChangedPaths } from "./repository.js";
+import { readContract } from "./contract.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { readWorkState } from "./work-state.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
+import { readContinuity } from "./continuity.js";
+import { getPackageRoot } from "./templates.js";
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import { taskArtifactPath, taskHandoffDirectory, taskHandoffPath } from "./task-paths.js";
+import { PROTOCOL_VERSION, WORK_PHASES } from "./protocol.js";
+import { assertTaskMutationAllowed } from "./task-claim-state.js";
+import { assertWorkspaceBinding } from "./workspace-binding.js";
+import { withTaskTransaction } from "./transaction.js";
+
+function handoffError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.name = "HandoffError";
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function optionalText(value, label) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw handoffError("E_HANDOFF_INVALID", `${label} must be a non-empty string when provided`);
+  }
+  return value;
+}
+
+function pathList(value) {
+  return [...new Set((value ?? []).map((item) => String(item).replaceAll("\\", "/")))].sort();
+}
+
+function handoffWithoutDigest(value) {
+  const { artifactDigest: _artifactDigest, ...body } = value;
+  return body;
+}
+
+export function validateHandoffDigest(handoff) {
+  assertSecretFree(handoff);
+  if (typeof handoff?.artifactDigest !== "string"
+    || handoff.artifactDigest !== canonicalFingerprint(handoffWithoutDigest(handoff))) {
+    throw handoffError("E_HANDOFF_TAMPERED", "Handoff artifact digest does not match its canonical content");
+  }
+  return handoff;
+}
+
+async function currentContinuity(target, packageRoot, taskId) {
+  try {
+    const artifact = await readContinuity(target, { packageRoot, taskId });
+    return { ref: artifact.path, fingerprint: artifact.fingerprint };
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") {
+      return { ref: taskArtifactPath(taskId, "continuity"), fingerprint: null };
+    }
+    throw handoffError("E_HANDOFF_STATE_UNAVAILABLE", `Continuity state cannot be read: ${error.message}`, [taskArtifactPath(taskId, "continuity")]);
+  }
+}
+
+export async function buildCanonicalHandoff(target, {
+  taskId,
+  recipientHint,
+  note,
+  packageRoot = getPackageRoot(),
+  handoffId = `handoff-${randomUUID()}`,
+  createdAt = new Date().toISOString(),
+} = {}) {
+  if (!taskId) throw handoffError("E_HANDOFF_STATE_UNAVAILABLE", "taskId is required to build a handoff");
+  const [state, contract, route, claims, changedPaths, continuity] = await Promise.all([
+    readWorkState(target, { packageRoot, taskId }),
+    readContract(target, packageRoot, { taskId }),
+    readPersistedRoute(target, packageRoot, { taskId }),
+    resolveTaskClaimState(target, { packageRoot, taskId }),
+    currentChangedPaths(target),
+    currentContinuity(target, packageRoot, taskId),
+  ]);
+  if (!state || !contract || !route || changedPaths === null || !claims.valid) {
+    throw handoffError("E_HANDOFF_STATE_UNAVAILABLE", "Canonical task state, route, claims, and changed paths are required for a handoff");
+  }
+  const checkItems = [...(state.checks ?? [])];
+  const executionRefs = pathList(checkItems.map((check) => check.executionRef).filter(Boolean));
+  const checkIds = pathList(checkItems.map((check) => check.id).filter(Boolean));
+  const body = {
+    schemaVersion: 1,
+    protocolVersion: PROTOCOL_VERSION,
+    handoffId,
+    taskId: state.taskId,
+    createdAt,
+    intent: {
+      ...(optionalText(recipientHint, "recipientHint") ? { recipientHint } : {}),
+      ...(optionalText(note, "note") ? { note } : {}),
+    },
+    state: {
+      phase: WORK_PHASES.includes(state.phase) ? state.phase : "UNKNOWN",
+      revision: state.revision ?? 0,
+      verificationCycle: state.verificationCycle ?? 1,
+      contractFingerprint: contract.fingerprint,
+      routeFingerprint: route.fingerprint ?? null,
+      repositoryFingerprint: state.repositoryFingerprint ?? { branch: null, head: null },
+      writeClaims: pathList(claims.effectiveWriteClaims ?? []),
+      changedPaths: pathList(changedPaths),
+    },
+    evidence: { executionRefs, checkIds },
+    continuity,
+  };
+  return {
+    ...body,
+    artifactDigest: canonicalFingerprint(body),
+  };
+}
+
+export async function validateCanonicalHandoff(target, handoff, {
+  taskId,
+  packageRoot = getPackageRoot(),
+} = {}) {
+  const { readSchema, assertSchema } = await import("./schema-validation.js");
+  try {
+    assertSchema(handoff, await readSchema("handoff-envelope", packageRoot), "handoff envelope");
+  } catch (error) {
+    throw handoffError("E_HANDOFF_INVALID", error.message);
+  }
+  if (taskId && handoff.taskId !== taskId) {
+    throw handoffError("E_HANDOFF_INVALID", "Handoff taskId does not match the selected task");
+  }
+  return validateHandoffDigest(handoff);
+}
+
+export async function writeCanonicalHandoff(target, handoff, {
+  packageRoot = getPackageRoot(),
+  taskId = handoff?.taskId,
+} = {}) {
+  await validateCanonicalHandoff(target, handoff, { taskId, packageRoot });
+  const relativePath = taskHandoffPath(taskId, handoff.handoffId);
+  await assertSafePath(target, relativePath);
+  if (await fileExists(ensureWithin(target, relativePath))) {
+    throw handoffError("E_HANDOFF_INVALID", "An existing handoff cannot be overwritten", [relativePath]);
+  }
+  const artifact = await writeJsonArtifact(target, relativePath, handoff, "handoff-envelope", packageRoot, { taskId, operation: "handoff-create" });
+  await appendProtocolEvent(target, {
+    taskId,
+    event: "HANDOFF_CREATED",
+    fingerprint: artifact.fingerprint,
+    details: { handoffId: handoff.handoffId, artifact: relativePath, digest: handoff.artifactDigest },
+  }, packageRoot, { taskId });
+  return { path: relativePath, fingerprint: artifact.fingerprint, handoff };
+}
+
+export async function createCanonicalHandoff(target, options = {}) {
+  return withTaskTransaction({ target, taskId: options.taskId, packageRoot: options.packageRoot, operation: "handoff-create", recordCommitEvent: true }, async () => {
+    await assertTaskMutationAllowed(target, { taskId: options.taskId, packageRoot: options.packageRoot }).catch((error) => {
+      if (error.code !== "E_TASK_COMPLETE") throw error;
+    });
+    await assertWorkspaceBinding(target, { taskId: options.taskId, packageRoot: options.packageRoot, operation: "handoff-create" });
+    const handoff = await buildCanonicalHandoff(target, options);
+    return writeCanonicalHandoff(target, handoff, options);
+  });
+}
+
+export async function readCanonicalHandoff(target, {
+  taskId,
+  handoffId,
+  packageRoot = getPackageRoot(),
+} = {}) {
+  const relativePath = taskHandoffPath(taskId, handoffId);
+  try {
+    const artifact = await readJsonArtifact(target, relativePath, "handoff-envelope", packageRoot);
+    await validateCanonicalHandoff(target, artifact.value, { taskId, packageRoot });
+    if (artifact.value.handoffId !== handoffId) {
+      throw handoffError("E_HANDOFF_INVALID", "Handoff ID does not match its path", [relativePath]);
+    }
+    return { ...artifact, value: artifact.value };
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") {
+      throw handoffError("E_HANDOFF_NOT_FOUND", `Handoff not found: ${handoffId}`, [relativePath]);
+    }
+    if (error.code === "E_HANDOFF_TAMPERED" || error.code === "E_HANDOFF_INVALID") throw error;
+    throw handoffError("E_HANDOFF_INVALID", error.message, [relativePath]);
+  }
+}
+
+export async function listCanonicalHandoffs(target, { taskId, packageRoot = getPackageRoot() } = {}) {
+  const directory = taskHandoffDirectory(taskId);
+  if (!(await fileExists(ensureWithin(target, directory)))) return [];
+  const entries = await readdir(ensureWithin(target, directory), { withFileTypes: true });
+  const handoffs = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !/^handoff-[A-Za-z0-9_-]+\.json$/u.test(entry.name)) continue;
+    const handoffId = entry.name.slice(0, -5);
+    const artifact = await readCanonicalHandoff(target, { taskId, handoffId, packageRoot });
+    handoffs.push(artifact.value);
+  }
+  return handoffs.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.handoffId.localeCompare(right.handoffId));
+}
+
+export async function resolveLatestHandoff(target, { taskId, packageRoot = getPackageRoot() } = {}) {
+  const handoffs = await listCanonicalHandoffs(target, { taskId, packageRoot });
+  const latest = handoffs.at(-1);
+  return latest
+    ? { handoffId: latest.handoffId, createdAt: latest.createdAt, digest: latest.artifactDigest }
+    : null;
+}

package/src/core/information-gain-projection.js

@@ -156,10 +156,10 @@ export function buildInformationGainProjection(events, taskId) {
     const previousCycle = previousDiagnostic?.details?.verificationCycle ?? null;
     const surface = [...(failure.surfaces.get(cycle) ?? new Set())].sort();
     const signatures = [...(failure.signatures.get(cycle) ?? new Set())].sort();
-    const previousSurface = previousCycle != null
+    const previousSurface = previousCycle !== null && previousCycle !== undefined
       ? [...(failure.surfaces.get(previousCycle) ?? new Set())].sort()
       : null;
-    const previousSignatures = previousCycle != null
+    const previousSignatures = previousCycle !== null && previousCycle !== undefined
       ? [...(failure.signatures.get(previousCycle) ?? new Set())].sort()
       : null;
     const hasPreviousFailureState = previousSurface !== null;
@@ -257,7 +257,7 @@ export function buildInformationGainProjection(events, taskId) {
 //   retry. The first diagnosis is never stalled. Legacy diagnosis keeps its
 //   own compatibility rule (informationGain === NONE).
 export function evaluateStructuredDiagnosticStall(gainProjection, { verificationCycle = null } = {}) {
-  const candidates = verificationCycle == null
+  const candidates = verificationCycle === null || verificationCycle === undefined
     ? (gainProjection ?? [])
     : (gainProjection ?? []).filter((entry) => entry.verificationCycle === verificationCycle);
 

package/src/core/integration-invocation-policy.js

@@ -29,6 +29,8 @@ const READ_ONLY_COMMANDS = Object.freeze(new Set([
   "inspect", "validate-state", "validate-protocol", "validate-receipt",
   "policy-status", "policy-diff", "rule-verify", "policy",
   "history", "trace", "reflect",
+  "workspace-status", "handoff-list", "handoff-show", "responsibility-status",
+  "attestation-verify", "attestation-status", "attestation-verify-range",
 ]));
 
 const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
@@ -37,6 +39,7 @@ const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
   "record-check", "record-diagnosis", "record-decision-criterion",
   "record-terminal-result", "complete",
   "record-intervention", "record-hypothesis-disposition",
+  "workspace-bind", "handoff-create", "responsibility-set", "verify-scope", "attestation-create",
 ]));
 
 const STATIC_RISK_CLASSES = Object.freeze({
@@ -134,6 +137,38 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
         readOnlyMetrics: true,
         projectLocalReference: true,
       },
+      workspaceBinding: {
+        version: 1,
+        supported: true,
+        optional: true,
+        explicitRebinding: false,
+      },
+      canonicalHandoffs: {
+        version: 1,
+        supported: true,
+        immutable: true,
+        lifecycleAuthority: false,
+      },
+      responsibilityConstraints: {
+        version: 1,
+        supported: true,
+        immutableDuringPass: true,
+        completionEnforced: true,
+      },
+      differentialVerificationScope: {
+        version: 1,
+        supported: true,
+        modes: ["AUTO", "CHANGED", "CLAIMED", "FULL"],
+        impactedMode: false,
+      },
+      codeAttestation: {
+        version: 1,
+        supported: true,
+        modes: ["off", "optional", "required"],
+        revisionProviders: ["git"],
+        signingProviders: ["none", "sigstore"],
+        completionLedgerBound: true,
+      },
       verificationExecutionIsolation: {
         version: 1,
         supported: true,
@@ -150,6 +185,11 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
       { name: "task/ownership", scope: "TASK" },
       { name: "task/contract", scope: "TASK" },
       { name: "task/continuity", scope: "TASK" },
+      { name: "task/workspace-binding", scope: "TASK" },
+      { name: "task/handoffs", scope: "TASK" },
+      { name: "task/responsibility", scope: "TASK" },
+      { name: "task/verification-scope", scope: "TASK" },
+      { name: "task/attestation", scope: "TASK" },
       { name: "task/actions", scope: "TASK" },
       { name: "task/action", scope: "TASK" },
       { name: "task/approvals", scope: "TASK" },