@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/src/core/cli-command-definitions.js

@@ -278,6 +278,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       "--requirement": Object.freeze({ targetKey: "checkRequirement", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--requirement requires an evidence target", description: "completion requirement covered by the check" }),
       "--details": Object.freeze({ targetKey: "checkDetails", parseType: "json-object", takesValue: true, valueName: "json", missingValueMessage: "--details requires a JSON object", description: "additional structured check details" }),
       "--timeout-ms": Object.freeze({ targetKey: "timeoutMs", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--timeout-ms requires a non-negative integer", description: "maximum command duration before termination" }),
+      "--scope-ref": Object.freeze({ targetKey: "scopeRef", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--scope-ref requires a path", description: "current verification-scope.json to bind to execution evidence" }),
       "--": Object.freeze({ targetKey: "commandArgv", parseType: "argv", takesValue: true, valueName: "argv...", description: "exact command argv to classify, execute, and attest" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
@@ -1026,6 +1027,201 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Reacquires a recovered task's write claims under project serialization and restores ordinary mutation authority.",
   }),
+  "workspace-bind": Object.freeze({
+    name: "workspace-bind",
+    category: "workspace",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit binding result as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/workspace-binding.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Binds a task to the current Git worktree identity; rebinding is not implicit.",
+  }),
+  "workspace-status": Object.freeze({
+    name: "workspace-status",
+    category: "workspace",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit workspace status as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Reports whether the current Git worktree matches an optional task binding.",
+  }),
+  "handoff-create": Object.freeze({
+    name: "handoff-create",
+    category: "continuity",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--recipient": Object.freeze({ targetKey: "recipientHint", parseType: "string", takesValue: true, valueName: "hint", missingValueMessage: "--recipient requires a hint", description: "non-authoritative recipient hint" }),
+      "--note": Object.freeze({ targetKey: "handoffNote", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--note requires text", description: "non-authoritative handoff note" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit handoff as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/handoffs/handoff-<id>.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Creates an immutable protocol-derived handoff snapshot without delegation or review side effects.",
+  }),
+  "handoff-list": Object.freeze({
+    name: "handoff-list",
+    category: "continuity",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit handoff list as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Lists immutable handoff snapshots for a task.",
+  }),
+  "handoff-show": Object.freeze({
+    name: "handoff-show",
+    category: "continuity",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--id": Object.freeze({ targetKey: "handoffId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--id requires a handoff ID", description: "handoff identifier" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit handoff as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Reads and verifies one immutable handoff snapshot.",
+  }),
+  "responsibility-set": Object.freeze({
+    name: "responsibility-set",
+    category: "scope",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--label": Object.freeze({ targetKey: "responsibilityLabel", parseType: "string", takesValue: true, valueName: "label", missingValueMessage: "--label requires a value", description: "descriptive pass label; not an identity or role" }),
+      "--allowed-path": Object.freeze({ targetKey: "responsibilityAllowedPaths", parseType: "string", takesValue: true, repeatable: true, valueName: "path", missingValueMessage: "--allowed-path requires a path", description: "path prefix allowed during this pass" }),
+      "--read-only-path": Object.freeze({ targetKey: "responsibilityReadOnlyPaths", parseType: "string", takesValue: true, repeatable: true, valueName: "path", missingValueMessage: "--read-only-path requires a path", description: "path prefix that must not change during this pass" }),
+      "--required-check": Object.freeze({ targetKey: "responsibilityRequiredChecks", parseType: "string", takesValue: true, repeatable: true, valueName: "id", missingValueMessage: "--required-check requires an ID", description: "current-cycle check required by this pass" }),
+      "--freeze-contract": Object.freeze({ targetKey: "responsibilityFreezeContract", parseType: "boolean", takesValue: false, description: "freeze the current contract fingerprint" }),
+      "--freeze-route": Object.freeze({ targetKey: "responsibilityFreezeRoute", parseType: "boolean", takesValue: false, description: "freeze the current route fingerprint" }),
+      "--freeze-claims": Object.freeze({ targetKey: "responsibilityFreezeClaims", parseType: "boolean", takesValue: false, description: "freeze the current effective claims fingerprint" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit responsibility result as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/responsibility.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Creates immutable, mechanically verifiable constraints for a task pass.",
+  }),
+  "responsibility-status": Object.freeze({
+    name: "responsibility-status",
+    category: "scope",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit responsibility status as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Validates active responsibility constraints against current paths, inputs, and checks.",
+  }),
+  "verify-scope": Object.freeze({
+    name: "verify-scope",
+    category: "verification",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--mode": Object.freeze({ targetKey: "verificationScopeMode", parseType: "string", takesValue: true, valueName: "mode", missingValueMessage: "--mode requires AUTO, CHANGED, CLAIMED, or FULL", description: "requested deterministic verification boundary (default: AUTO)" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit verification scope as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/verification-scope.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Resolves a provable changed, claimed, full, or unresolved verification boundary without launching checks.",
+  }),
+  "attestation-create": Object.freeze({
+    name: "attestation-create",
+    category: "attestation",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit attestation statement result as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/attestations/statement.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Builds a deterministic in-toto ForgeLoop statement from a valid completed task manifest.",
+  }),
+  "attestation-verify": Object.freeze({
+    name: "attestation-verify",
+    category: "attestation",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--ref": Object.freeze({ targetKey: "attestationRef", parseType: "string", takesValue: true, valueName: "revision", missingValueMessage: "--ref requires a revision", description: "target revision to compare with the manifest" }),
+      "--bundle": Object.freeze({ targetKey: "attestationBundle", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--bundle requires a path", description: "optional external signature bundle" }),
+      "--identity": Object.freeze({ targetKey: "attestationIdentity", parseType: "string", takesValue: true, valueName: "identity", missingValueMessage: "--identity requires an identity", description: "optional exact signer identity policy" }),
+      "--issuer": Object.freeze({ targetKey: "attestationIssuer", parseType: "string", takesValue: true, valueName: "issuer", missingValueMessage: "--issuer requires an issuer", description: "optional exact signer issuer policy" }),
+      "--revision-provider": Object.freeze({ targetKey: "revisionProvider", parseType: "string", takesValue: true, valueName: "provider", missingValueMessage: "--revision-provider requires a provider", description: "revision provider (default: git)" }),
+      "--signing-provider": Object.freeze({ targetKey: "signingProvider", parseType: "string", takesValue: true, valueName: "provider", missingValueMessage: "--signing-provider requires a provider", description: "signing provider (default: none)" }),
+      "--trusted-root": Object.freeze({ targetKey: "trustedRoot", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--trusted-root requires a path", description: "trusted signing root path" }),
+      "--require-signature": Object.freeze({ targetKey: "requireSignature", parseType: "boolean", takesValue: false, description: "require a valid external signature" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit verification result as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Verifies a task attestation and current revision without mutating task state.",
+  }),
+  "attestation-status": Object.freeze({
+    name: "attestation-status",
+    category: "attestation",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit attestation status as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Reports local ForgeLoop attestation status and trust level without network access.",
+  }),
+  "attestation-verify-range": Object.freeze({
+    name: "attestation-verify-range",
+    category: "attestation",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--revision-provider": Object.freeze({ targetKey: "revisionProvider", parseType: "string", takesValue: true, valueName: "provider", missingValueMessage: "--revision-provider requires a provider", description: "revision provider (default: git)" }),
+      "--base": Object.freeze({ targetKey: "baseRevision", parseType: "string", takesValue: true, valueName: "revision", missingValueMessage: "--base requires a revision", description: "opaque base revision" }),
+      "--head": Object.freeze({ targetKey: "headRevision", parseType: "string", takesValue: true, valueName: "revision", missingValueMessage: "--head requires a revision", description: "opaque head revision" }),
+      "--require-complete-coverage": Object.freeze({ targetKey: "requireCompleteCoverage", parseType: "boolean", takesValue: false, description: "fail when any changed source path lacks a valid attestation" }),
+      "--require-signature": Object.freeze({ targetKey: "requireSignature", parseType: "boolean", takesValue: false, description: "require a valid external signature for covered attestations" }),
+      "--signing-provider": Object.freeze({ targetKey: "signingProvider", parseType: "string", takesValue: true, valueName: "provider", missingValueMessage: "--signing-provider requires a provider", description: "signing provider (default: none)" }),
+      "--identity": Object.freeze({ targetKey: "attestationIdentity", parseType: "string", takesValue: true, valueName: "identity", missingValueMessage: "--identity requires an identity", description: "optional exact signer identity policy" }),
+      "--issuer": Object.freeze({ targetKey: "attestationIssuer", parseType: "string", takesValue: true, valueName: "issuer", missingValueMessage: "--issuer requires an issuer", description: "optional exact signer issuer policy" }),
+      "--trusted-root": Object.freeze({ targetKey: "trustedRoot", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--trusted-root requires a path", description: "trusted signing root path" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit range verification result as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Verifies complete attestation coverage for an opaque revision range through a provider-neutral contract.",
+  }),
 });
 
 /**

package/src/core/code-manifest.js

@@ -0,0 +1,293 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { assertSecretFree } from "./receipt.js";
+import { getPackageRoot } from "./templates.js";
+import { readContract } from "./contract.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { readWorkState } from "./work-state.js";
+import { validateEventLedger } from "./events.js";
+import {
+  taskArtifactPath,
+  taskCodeManifestPath,
+  taskCodeManifestHistoryPath,
+} from "./task-paths.js";
+import { ensureWithin, fileExists } from "./filesystem.js";
+import { resolveRevisionProvider } from "./revision/provider.js";
+import { REVISION_PROVIDERS } from "./revision/registry.js";
+
+const SHA256 = /^[a-f0-9]{64}$/u;
+const OPERATIONS = new Set(["ADDED", "MODIFIED", "DELETED", "RENAMED", "COPIED", "TYPE_CHANGED"]);
+const KINDS = new Set(["FILE", "SYMLINK", "GITLINK", "DELETED"]);
+
+function manifestError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.name = "CodeManifestError";
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function digestBytes(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function normalizedPath(value, label = "path") {
+  if (typeof value !== "string" || !value || value.startsWith("/") || value === "." || value === ".." || value.startsWith("../")) {
+    throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `${label} must be a safe relative path`);
+  }
+  if (/[\u0000-\u001f\u007f]/u.test(value)) {
+    throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `${label} contains a control character`);
+  }
+  if (value.includes("\\")) {
+    throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `${label} must use forward slashes`);
+  }
+  const portable = value;
+  const normalized = path.posix.normalize(portable).replace(/^\.\//u, "");
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.startsWith(".forgeloop/")) {
+    throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `${label} is unsafe or reserved: ${value}`);
+  }
+  if (normalized !== portable) {
+    throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `${label} must use a normalized relative path: ${value}`);
+  }
+  return normalized;
+}
+
+export function codeManifestContentDigest(entries) {
+  return canonicalFingerprint(entries.map((entry) => ({
+    path: entry.path,
+    sourcePath: entry.sourcePath ?? null,
+    operation: entry.operation,
+    kind: entry.kind,
+    sha256: entry.sha256 ?? null,
+    providerContentId: entry.providerContentId ?? null,
+    providerMetadata: entry.providerMetadata ?? {},
+  })));
+}
+
+function canonicalEntries(entries) {
+  if (!Array.isArray(entries)) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", "Manifest entries must be an array");
+  const normalized = entries.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Manifest entry ${index} must be an object`);
+    const item = {
+      path: normalizedPath(entry.path, `entries[${index}].path`),
+      ...(entry.sourcePath !== undefined ? { sourcePath: normalizedPath(entry.sourcePath, `entries[${index}].sourcePath`) } : {}),
+      operation: entry.operation,
+      kind: entry.kind,
+      ...(entry.sha256 !== undefined ? { sha256: entry.sha256 } : {}),
+      ...(entry.providerContentId !== undefined ? { providerContentId: entry.providerContentId } : {}),
+      ...(entry.providerMetadata !== undefined ? { providerMetadata: entry.providerMetadata } : {}),
+    };
+    if (!OPERATIONS.has(item.operation) || !KINDS.has(item.kind)) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Manifest entry ${index} has an unsupported operation or kind`);
+    if (item.operation === "DELETED" && item.kind !== "DELETED") throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Deleted entry ${item.path} must use kind DELETED`);
+    if (item.kind === "DELETED" && item.operation !== "DELETED") throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Deleted entry ${item.path} must use operation DELETED`);
+    if (item.kind === "DELETED" && item.sha256 !== undefined) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Deleted entry ${item.path} cannot have sha256`);
+    if (["FILE", "SYMLINK"].includes(item.kind) && !SHA256.test(item.sha256 ?? "")) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Entry ${item.path} requires a lowercase SHA-256 content digest`);
+    if (item.kind === "GITLINK" && (typeof item.providerContentId !== "string" || !item.providerContentId)) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Gitlink entry ${item.path} requires providerContentId`);
+    if (item.providerMetadata !== undefined && (!item.providerMetadata || typeof item.providerMetadata !== "object" || Array.isArray(item.providerMetadata))) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Entry ${item.path} providerMetadata must be an object`);
+    if (item.operation === "RENAMED" && !item.sourcePath) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Renamed entry ${item.path} requires sourcePath`);
+    return item;
+  });
+  const paths = normalized.map((entry) => entry.path);
+  if (new Set(paths).size !== paths.length) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", "Manifest entries must not contain duplicate paths");
+  const sorted = [...normalized].sort((left, right) => left.path.localeCompare(right.path));
+  if (JSON.stringify(sorted) !== JSON.stringify(normalized)) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", "Manifest entries must be sorted by normalized path");
+  return normalized;
+}
+
+export async function validateCodeManifest(manifest, packageRoot = getPackageRoot()) {
+  try {
+    assertSchema(manifest, await readSchema("code-manifest", packageRoot), "code manifest");
+    const entries = canonicalEntries(manifest.entries);
+    if (manifest.contentDigest !== codeManifestContentDigest(entries)) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", "Manifest contentDigest does not match its entries");
+    assertSecretFree(manifest);
+    return { ...manifest, entries };
+  } catch (error) {
+    if (error.code === "E_ATTESTATION_MANIFEST_INVALID") throw error;
+    throw manifestError("E_ATTESTATION_MANIFEST_INVALID", error.message);
+  }
+}
+
+async function completionCheckpoint(target, packageRoot, taskId, override = null) {
+  if (override) {
+    if (!Number.isInteger(override.seq) || override.seq < 1 || !SHA256.test(override.hash)) {
+      throw manifestError("E_ATTESTATION_LEDGER_MISMATCH", "The candidate completion checkpoint is invalid");
+    }
+    return { seq: override.seq, hash: override.hash, ledger: null };
+  }
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  const completion = ledger.events.findLast((event) => event.taskId === taskId && event.event === "COMPLETION_VALIDATED");
+  if (!ledger.valid || !completion) throw manifestError("E_ATTESTATION_LEDGER_MISMATCH", "A valid COMPLETION_VALIDATED ledger checkpoint is required for a code manifest");
+  return { seq: completion.seq, hash: completion.hash, ledger };
+}
+
+export async function createCodeManifest({
+  target,
+  packageRoot = getPackageRoot(),
+  taskId,
+  revisionProvider = null,
+  baseRevision = null,
+  headRevision = "WORKTREE",
+  captureMode = "WORKTREE",
+  candidateState = null,
+  candidateReceipt = null,
+  candidateCompletionCheckpoint = null,
+} = {}) {
+  let provider = revisionProvider;
+  if (!provider || typeof provider === "string") {
+    provider = await resolveRevisionProvider({ target, providerName: provider || "git", registry: REVISION_PROVIDERS });
+  }
+  const [contract, route, state, receipt, checkpoint] = await Promise.all([
+    readContract(target, packageRoot, { taskId }),
+    readPersistedRoute(target, packageRoot, { taskId }),
+    candidateState ?? readWorkState(target, { packageRoot, taskId }),
+    candidateReceipt
+      ? { value: candidateReceipt, fingerprint: canonicalFingerprint(candidateReceipt) }
+      : readJsonArtifact(target, taskArtifactPath(taskId, "receipt"), "execution-receipt", packageRoot),
+    completionCheckpoint(target, packageRoot, taskId, candidateCompletionCheckpoint),
+  ]);
+  if (!state || state.phase !== "COMPLETE") throw manifestError("E_ATTESTATION_MANIFEST_STALE", "Code manifests can only be captured for a COMPLETE task");
+  const observedRevision = headRevision === "WORKTREE"
+    ? (await provider.getCurrentRevision(target)) ?? "WORKTREE"
+    : headRevision;
+  let entries;
+  try {
+    entries = await provider.getChangedEntries({ target, baseRevision, headRevision, paths: null });
+  } catch (error) {
+    throw manifestError(error.code ?? "E_REVISION_PROVIDER_INVALID", error.message);
+  }
+  const manifestEntries = [];
+  for (const entry of entries) {
+    const pathValue = normalizedPath(entry.path);
+    if (pathValue.startsWith(".forgeloop/")) throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Protocol metadata cannot enter a code manifest: ${pathValue}`);
+    const kind = entry.kind ?? (entry.operation === "DELETED" ? "DELETED" : "FILE");
+    const bytes = entry.bytes ?? (kind === "DELETED" || kind === "GITLINK" ? null : await provider.readContent({ target, revision: headRevision, path: pathValue }));
+    manifestEntries.push({
+      path: pathValue,
+      ...(entry.sourcePath ? { sourcePath: normalizedPath(entry.sourcePath, "sourcePath") } : {}),
+      operation: entry.operation,
+      kind,
+      ...(bytes !== null && ["FILE", "SYMLINK"].includes(kind) ? { sha256: digestBytes(bytes) } : {}),
+      ...(entry.providerContentId ? { providerContentId: entry.providerContentId } : {}),
+      providerMetadata: entry.providerMetadata ?? {},
+    });
+  }
+  manifestEntries.sort((left, right) => left.path.localeCompare(right.path));
+  const providerMetadata = typeof provider.getProviderMetadata === "function"
+    ? await provider.getProviderMetadata(target)
+    : {};
+  const manifest = await validateCodeManifest({
+    schemaVersion: 1,
+    protocolVersion: 1,
+    taskId,
+    verificationCycle: state.verificationCycle ?? 1,
+    capture: {
+      mode: captureMode,
+      revisionProvider: provider.name ?? "unknown",
+      baseRevision,
+      observedRevision,
+      providerMetadata,
+    },
+    bindings: {
+      contractFingerprint: contract.fingerprint,
+      routeFingerprint: route.fingerprint ?? null,
+      stateFingerprint: canonicalFingerprint(state),
+      receiptFingerprint: receipt.fingerprint,
+      ledgerSeq: checkpoint.seq,
+      ledgerHash: checkpoint.hash,
+    },
+    entries: manifestEntries,
+    contentDigest: codeManifestContentDigest(manifestEntries),
+  }, packageRoot);
+  return { manifest, fingerprint: canonicalFingerprint(manifest), provider, checkpoint };
+}
+
+export async function readCodeManifest({ target, packageRoot = getPackageRoot(), taskId } = {}) {
+  const relativePath = taskCodeManifestPath(taskId);
+  try {
+    const artifact = await readJsonArtifact(target, relativePath, "code-manifest", packageRoot);
+    const value = await validateCodeManifest(artifact.value, packageRoot);
+    return { ...artifact, value };
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") throw manifestError("E_ATTESTATION_MANIFEST_MISSING", `Code manifest is missing: ${relativePath}`, [relativePath]);
+    if (error.code?.startsWith("E_ATTESTATION_")) throw error;
+    throw manifestError("E_ATTESTATION_MANIFEST_INVALID", error.message, [relativePath]);
+  }
+}
+
+export async function writeCodeManifest({ target, packageRoot = getPackageRoot(), taskId, manifest } = {}) {
+  const value = await validateCodeManifest(manifest, packageRoot);
+  const relativePath = taskCodeManifestPath(taskId);
+  if (await fileExists(ensureWithin(target, relativePath))) {
+    let previous;
+    try {
+      previous = await readCodeManifest({ target, packageRoot, taskId });
+    } catch (error) {
+      throw manifestError("E_ATTESTATION_MANIFEST_INVALID", `Existing code manifest cannot be versioned safely: ${error.message}`, [relativePath]);
+    }
+    const previousCycle = previous.value.verificationCycle;
+    if (value.verificationCycle <= previousCycle) {
+      throw manifestError("E_ATTESTATION_MANIFEST_INVALID", "Code manifest is immutable within a verification cycle", [relativePath]);
+    }
+    const historyPath = taskCodeManifestHistoryPath(taskId, previousCycle);
+    if (!(await fileExists(ensureWithin(target, historyPath)))) {
+      await writeJsonArtifact(target, historyPath, previous.value, "code-manifest", packageRoot, { taskId, operation: "code-manifest-history" });
+    }
+  }
+  return writeJsonArtifact(target, relativePath, value, "code-manifest", packageRoot, { taskId, operation: "code-manifest-capture" });
+}
+
+export async function validateCodeManifestBindings({ target, packageRoot = getPackageRoot(), taskId, manifest, revisionProvider = null } = {}) {
+  const value = await validateCodeManifest(manifest, packageRoot);
+  const [contract, route, state, receipt, checkpoint] = await Promise.all([
+    readContract(target, packageRoot, { taskId }),
+    readPersistedRoute(target, packageRoot, { taskId }),
+    readWorkState(target, { packageRoot, taskId }),
+    readJsonArtifact(target, taskArtifactPath(taskId, "receipt"), "execution-receipt", packageRoot),
+    completionCheckpoint(target, packageRoot, taskId),
+  ]);
+  const mismatches = [];
+  if (value.taskId !== taskId) mismatches.push(["taskId", "E_ATTESTATION_SUBJECT_MISMATCH"]);
+  if (value.verificationCycle !== (state.verificationCycle ?? 1)) mismatches.push(["verificationCycle", "E_ATTESTATION_SCOPE_MISMATCH"]);
+  if (value.bindings.contractFingerprint !== contract.fingerprint) mismatches.push(["contractFingerprint", "E_ATTESTATION_CONTRACT_MISMATCH"]);
+  if (value.bindings.routeFingerprint !== (route.fingerprint ?? null)) mismatches.push(["routeFingerprint", "E_ATTESTATION_ROUTE_MISMATCH"]);
+  if (value.bindings.stateFingerprint !== canonicalFingerprint(state)) mismatches.push(["stateFingerprint", "E_ATTESTATION_STATE_MISMATCH"]);
+  if (value.bindings.receiptFingerprint !== receipt.fingerprint) mismatches.push(["receiptFingerprint", "E_ATTESTATION_RECEIPT_MISMATCH"]);
+  if (value.bindings.ledgerSeq !== checkpoint.seq || value.bindings.ledgerHash !== checkpoint.hash) mismatches.push(["ledger", "E_ATTESTATION_LEDGER_MISMATCH"]);
+  if (mismatches.length > 0) {
+    const names = mismatches.map(([name]) => name).join(", ");
+    throw manifestError(mismatches[0][1], `Code manifest bindings are stale: ${names}`);
+  }
+  if (revisionProvider) {
+    const provider = typeof revisionProvider === "string"
+      ? await resolveRevisionProvider({ target, providerName: revisionProvider, registry: REVISION_PROVIDERS })
+      : revisionProvider;
+    const manifestPaths = new Set(value.entries.flatMap((entry) => [entry.path, entry.sourcePath].filter(Boolean)));
+    const currentEntries = await provider.getChangedEntries({
+      target,
+      baseRevision: value.capture.baseRevision,
+      headRevision: value.capture.mode === "WORKTREE" ? "WORKTREE" : value.capture.observedRevision,
+    });
+    const sourcePaths = (entries) => entries
+      .flatMap((entry) => [entry.path, entry.sourcePath].filter(Boolean))
+      .map((item) => normalizedPath(item))
+      .filter((item) => item !== ".forgeloop" && !item.startsWith(".forgeloop/"));
+    let currentPaths = new Set(sourcePaths(currentEntries));
+    const manifestPathsPresent = [...manifestPaths].every((item) => currentPaths.has(item));
+    if (!manifestPathsPresent && value.capture.mode === "WORKTREE" && value.capture.baseRevision) {
+      const observedRevision = typeof provider.getCurrentRevision === "function"
+        ? await provider.getCurrentRevision(target).catch(() => null)
+        : null;
+      if (observedRevision) {
+        const committedEntries = await provider.getChangedEntries({ target, baseRevision: value.capture.baseRevision, headRevision: observedRevision });
+        currentPaths = new Set(sourcePaths(committedEntries));
+      }
+    }
+    if (![...manifestPaths].every((item) => currentPaths.has(item))) {
+      throw manifestError("E_ATTESTATION_CONTENT_MISMATCH", "Current changed source paths differ from the code manifest");
+    }
+  }
+  return { valid: true, manifest: value, fingerprint: canonicalFingerprint(value), checkpoint };
+}

package/src/core/command-executors.js

@@ -63,6 +63,19 @@ import { runTaskResume } from "../commands/task-resume.js";
 import { runTaskRepairLegacyRecovery } from "../commands/task-repair-legacy-recovery.js";
 import { runTaskLockStatus } from "../commands/task-lock-status.js";
 import { runProtocolInfo } from "../commands/protocol-info.js";
+import { runWorkspaceBind } from "../commands/workspace-bind.js";
+import { runWorkspaceStatus } from "../commands/workspace-status.js";
+import { runHandoffCreate } from "../commands/handoff-create.js";
+import { runHandoffList } from "../commands/handoff-list.js";
+import { runHandoffShow } from "../commands/handoff-show.js";
+import { runResponsibilitySet } from "../commands/responsibility-set.js";
+import { runResponsibilityStatus } from "../commands/responsibility-status.js";
+import { runVerifyScope } from "../commands/verify-scope.js";
+import { runAttestationCreate } from "../commands/attestation-create.js";
+import { runAttestationVerify } from "../commands/attestation-verify.js";
+import { runAttestationStatus } from "../commands/attestation-status.js";
+import { runAttestationVerifyRange } from "../commands/attestation-verify-range.js";
+import { exitCodeForAttestationResult } from "./exit-codes.js";
 
 /**
  * Canonical transport-neutral command executors.
@@ -171,12 +184,78 @@ export const COMMAND_EXECUTORS = {
       argv: options.commandArgv,
       details: options.checkDetails ?? undefined,
       timeoutMs: options.timeoutMs ?? undefined,
+      scopeRef: options.scopeRef ?? undefined,
       taskId: options.taskId,
       authorityContext,
       runtimeContext,
     });
     return { result, exitCode: result.check.status === "passed" ? 0 : 1 };
   },
+  "workspace-bind": async ({ target, packageRoot, options }) => ({
+    result: await runWorkspaceBind({ target, packageRoot, taskId: options.taskId }),
+    exitCode: 0,
+  }),
+  "workspace-status": async ({ target, packageRoot, options }) => {
+    const result = await runWorkspaceStatus({ target, packageRoot, taskId: options.taskId });
+    return { result, exitCode: ["UNBOUND", "MATCH"].includes(result.status) ? 0 : 1 };
+  },
+  "handoff-create": async ({ target, packageRoot, options }) => ({
+    result: await runHandoffCreate({
+      target,
+      packageRoot,
+      taskId: options.taskId,
+      recipientHint: options.recipientHint,
+      handoffNote: options.handoffNote,
+    }),
+    exitCode: 0,
+  }),
+  "handoff-list": async ({ target, packageRoot, options }) => ({
+    result: await runHandoffList({ target, packageRoot, taskId: options.taskId }),
+    exitCode: 0,
+  }),
+  "handoff-show": async ({ target, packageRoot, options }) => ({
+    result: await runHandoffShow({ target, packageRoot, taskId: options.taskId, handoffId: options.handoffId }),
+    exitCode: 0,
+  }),
+  "responsibility-set": async ({ target, packageRoot, options }) => ({
+    result: await runResponsibilitySet({
+      target,
+      packageRoot,
+      taskId: options.taskId,
+      responsibilityLabel: options.responsibilityLabel,
+      responsibilityAllowedPaths: options.responsibilityAllowedPaths,
+      responsibilityReadOnlyPaths: options.responsibilityReadOnlyPaths,
+      responsibilityRequiredChecks: options.responsibilityRequiredChecks,
+      responsibilityFreezeContract: options.responsibilityFreezeContract,
+      responsibilityFreezeRoute: options.responsibilityFreezeRoute,
+      responsibilityFreezeClaims: options.responsibilityFreezeClaims,
+    }),
+    exitCode: 0,
+  }),
+  "responsibility-status": async ({ target, packageRoot, options }) => {
+    const result = await runResponsibilityStatus({ target, packageRoot, taskId: options.taskId });
+    return { result, exitCode: ["NOT_APPLICABLE", "VALID"].includes(result.status) ? 0 : 1 };
+  },
+  "verify-scope": async ({ target, packageRoot, options }) => ({
+    result: await runVerifyScope({ target, packageRoot, taskId: options.taskId, verificationScopeMode: options.verificationScopeMode }),
+    exitCode: 0,
+  }),
+  "attestation-create": async ({ target, packageRoot, options }) => ({
+    result: await runAttestationCreate({ target, packageRoot, taskId: options.taskId }),
+    exitCode: 0,
+  }),
+  "attestation-verify": async ({ target, packageRoot, options }) => {
+    const result = await runAttestationVerify({ target, packageRoot, taskId: options.taskId, ...options });
+    return { result, exitCode: exitCodeForAttestationResult(result) };
+  },
+  "attestation-status": async ({ target, packageRoot, options }) => {
+    const result = await runAttestationStatus({ target, packageRoot, taskId: options.taskId });
+    return { result, exitCode: exitCodeForAttestationResult(result) };
+  },
+  "attestation-verify-range": async ({ target, packageRoot, options }) => {
+    const result = await runAttestationVerifyRange({ target, packageRoot, ...options });
+    return { result, exitCode: exitCodeForAttestationResult(result) };
+  },
   "run-action": async ({ target, packageRoot, options, authorityContext, runtimeContext }) => {
     const result = await runAction({ target, packageRoot, taskId: options.taskId,
       actionId: options.actionId, capability: options.actionCapability,