@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/src/core/phase.js

@@ -10,7 +10,7 @@ import { readPersistedRoute } from "./route-artifact.js";
 import { assertWorkPhase, isValidTransition } from "./protocol.js";
 import { readWorkState, mutateWorkState } from "./work-state.js";
 import { authorizeCompletionRecoveryOrRebind } from "./completion-recovery-rebind.js";
-import { evaluateCompletion } from "./completion.js";
+import { evaluateCompletion, runComplete as persistCompletion } from "./completion.js";
 import { evaluatePreflight } from "./preflight.js";
 import { requiredEvidenceForTarget } from "./completion-artifacts.js";
 import { assertCompletionRelationships, assertStateIdentity } from "./completion-relationships.js";
@@ -174,6 +174,34 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   const eventsRel = eventsPath ?? (taskId ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events);
   const receiptRel = receiptPath ?? (taskId ? taskArtifactPath(taskId, "receipt") : ARTIFACT_PATHS.receipt);
 
+  // COMPLETE must use the same transactional completion path regardless of
+  // whether the caller selected the dedicated command or a phase transition.
+  // This keeps required code-manifest capture and its ledger event atomic with
+  // the final state and receipt.
+  if (toPhase === "COMPLETE" && state.phase === "REVIEWING") {
+    const completion = await persistCompletion({
+      target,
+      packageRoot,
+      taskId,
+      authorityContext,
+      runtimeContext,
+      contractPath,
+      routePath,
+      statePath,
+      receiptPath,
+      eventsPath,
+      preflightPath: null,
+    });
+    if (completion.status !== "VALID") {
+      throw phaseError(
+        "E_COMPLETION_REJECTED",
+        "COMPLETE requires a valid completion audit",
+        completion.errors.flatMap((error) => error.artifacts ?? []),
+      );
+    }
+    return readWorkState(target, { packageRoot, taskId, statePath });
+  }
+
   await assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext, { taskId, statePath, contractPath, routePath, receiptPath, eventsPath });
   await assertPersistedStateIdentity(target, state, toPhase, packageRoot, { taskId, contractPath, routePath });
 

package/src/core/protocol-info.js

@@ -17,7 +17,8 @@ function publicSchemaVersions() {
   return Object.fromEntries(
     [...new Set(Object.values(ARTIFACT_REGISTRY)
       .filter((artifact) => artifact.isPublic && artifact.isPersisted)
-      .map((artifact) => artifact.schema))]
+      .map((artifact) => artifact.schema)
+      .filter(Boolean))]
       .sort()
       .map((schema) => [schema, [SCHEMA_COMPATIBILITY_POLICY.schemaVersion]]),
   );
@@ -93,6 +94,45 @@ export function protocolInfo({ packageVersion = null } = {}) {
       durableApprovals: { version: 1, supported: true, fingerprintBound: true, hostAttestationMinting: false },
       trajectoryMetrics: { version: 1, supported: true, usageUnknownWhenUnreported: true, overallScore: false },
       trajectoryEvaluation: { version: 1, supported: true, requiresReferenceScenario: true, source: "PROJECT_LOCAL_REFERENCE" },
+      workspaceBinding: {
+        version: 1,
+        supported: true,
+        optional: true,
+        modes: ["GIT_WORKTREE"],
+        statuses: ["UNBOUND", "MATCH", "MISMATCH", "INVALID", "UNAVAILABLE"],
+        rebinding: "EXPLICIT_ONLY",
+      },
+      canonicalHandoffs: {
+        version: 1,
+        supported: true,
+        immutable: true,
+        actorControlledIntent: true,
+        lifecycleAuthority: false,
+      },
+      responsibilityConstraints: {
+        version: 1,
+        supported: true,
+        immutableDuringPass: true,
+        frozenInputs: ["contract", "route", "claims"],
+        completionEnforced: true,
+      },
+      differentialVerificationScope: {
+        version: 1,
+        supported: true,
+        modes: ["AUTO", "CHANGED", "CLAIMED", "FULL"],
+        heuristicImpactedMode: false,
+        staleBinding: true,
+      },
+      codeAttestation: {
+        version: 1,
+        supported: true,
+        modes: ["off", "optional", "required"],
+        revisionProviders: ["git"],
+        signingProviders: ["none", "sigstore"],
+        statementType: "https://in-toto.io/Statement/v1",
+        completionLedgerBound: true,
+        excludesProtocolMetadata: true,
+      },
       observabilityStability: {
         executionHistory: "stable",
         structuredTrace: "stable",

package/src/core/repository.js

@@ -1,8 +1,131 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import path from "node:path";
 
 const execFileAsync = promisify(execFile);
 
+const GIT_EXECUTION_OPTIONS = Object.freeze({
+  windowsHide: true,
+  maxBuffer: 64 * 1024 * 1024,
+});
+
+function repositoryError(code, message, cause = null) {
+  const error = new Error(message);
+  error.code = code;
+  if (cause) error.cause = cause;
+  return error;
+}
+
+async function runGit(target, args, { binary = false } = {}) {
+  try {
+    const result = await execFileAsync("git", ["-C", target, ...args], {
+      ...GIT_EXECUTION_OPTIONS,
+      ...(binary ? { encoding: "buffer" } : {}),
+    });
+    return result.stdout;
+  } catch (error) {
+    throw repositoryError(
+      "E_REPOSITORY_GIT_COMMAND_FAILED",
+      `Git command failed (${args.join(" ")}): ${String(error.stderr ?? error.message).trim()}`,
+      error,
+    );
+  }
+}
+
+function text(value) {
+  return Buffer.isBuffer(value) ? value.toString("utf8") : String(value ?? "");
+}
+
+function assertRepositoryPath(relativePath) {
+  if (typeof relativePath !== "string" || relativePath.length === 0
+    || relativePath.startsWith("/") || /^[A-Za-z]:[\\/]/u.test(relativePath)
+    || /[\u0000-\u001f\u007f]/u.test(relativePath) || relativePath.includes("\\")) {
+    throw repositoryError("E_REVISION_CONTENT_UNAVAILABLE", "Repository path must be a non-empty relative path");
+  }
+  const normalized = path.posix.normalize(relativePath);
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized !== relativePath) {
+    throw repositoryError("E_REVISION_CONTENT_UNAVAILABLE", `Repository path escapes the target: ${relativePath}`);
+  }
+  return normalized;
+}
+
+function isGitNotFound(error) {
+  return error?.code === 128
+    || error?.cause?.code === 128
+    || error?.cause?.cause?.code === 128;
+}
+
+function assertRevision(value, label = "revision") {
+  if (typeof value !== "string" || !value.trim() || value.startsWith("-") || value.includes("\0") || /\s/u.test(value)) {
+    throw repositoryError("E_REVISION_NOT_FOUND", `${label} must be a non-empty opaque revision identifier`);
+  }
+  return value;
+}
+
+function parseNameStatusZ(output) {
+  const tokens = text(output).split("\0").filter(Boolean);
+  const entries = [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    const statusToken = tokens[index];
+    const status = statusToken.slice(0, 1);
+    const score = statusToken.slice(1);
+    if (["R", "C"].includes(status)) {
+      const sourcePath = assertRepositoryPath(tokens[index + 1] ?? "");
+      const filePath = assertRepositoryPath(tokens[index + 2] ?? "");
+      entries.push({
+        path: filePath,
+        sourcePath,
+        status,
+        score: score ? Number(score) : null,
+      });
+      index += 2;
+    } else {
+      const embeddedPath = statusToken.length > 1 ? statusToken.slice(1).replace(/^\t/u, "") : null;
+      const pathToken = embeddedPath || tokens[++index] || "";
+      entries.push({
+        path: assertRepositoryPath(pathToken),
+        sourcePath: null,
+        status,
+        score: score ? Number(score) : null,
+      });
+    }
+  }
+  return entries.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function parseStatusZ(output) {
+  const tokens = text(output).split("\0").filter(Boolean);
+  const entries = [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    const item = tokens[index];
+    const status = item.slice(0, 2);
+    const firstPath = item.slice(3).replace(/^\t/u, "");
+    if (status.includes("R") || status.includes("C")) {
+      const sourcePath = assertRepositoryPath(tokens[index + 1] ?? "");
+      const filePath = assertRepositoryPath(firstPath);
+      entries.push({ path: filePath, sourcePath, status, score: null });
+      index += 1;
+    } else {
+      entries.push({ path: assertRepositoryPath(firstPath), sourcePath: null, status, score: null });
+    }
+  }
+  return entries.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function parseIndexEntriesZ(output) {
+  const tokens = text(output).split("\0").filter(Boolean);
+  return tokens.map((token) => {
+    const match = token.match(/^(\d+) ([0-9a-f]+) (\d+)\t([\s\S]*)$/u);
+    if (!match) throw repositoryError("E_REVISION_PROVIDER_INVALID", "Cannot parse Git index entry");
+    return {
+      mode: match[1],
+      objectId: match[2],
+      stage: Number(match[3]),
+      path: assertRepositoryPath(match[4]),
+    };
+  });
+}
+
 export async function currentRepositoryFingerprint(target) {
   try {
     const [{ stdout: branchOutput }, { stdout: headOutput }] = await Promise.all([
@@ -18,6 +141,135 @@ export async function currentRepositoryFingerprint(target) {
   }
 }
 
+export async function repositoryObjectFormat(target) {
+  const output = await runGit(target, ["rev-parse", "--show-object-format"]);
+  return text(output).trim() || "sha1";
+}
+
+export async function repositoryWorktreeMetadata(target) {
+  const [commonDirectory, gitDirectory, topLevel] = await Promise.all([
+    runGit(target, ["rev-parse", "--git-common-dir"]),
+    runGit(target, ["rev-parse", "--git-dir"]),
+    runGit(target, ["rev-parse", "--show-toplevel"]),
+  ]);
+  return {
+    commonDirectory: text(commonDirectory).trim(),
+    gitDirectory: text(gitDirectory).trim(),
+    topLevel: text(topLevel).trim(),
+    objectFormat: await repositoryObjectFormat(target),
+  };
+}
+
+export async function repositoryHead(target, { revision = "HEAD" } = {}) {
+  const output = await runGit(target, ["rev-parse", "--verify", assertRevision(revision)]);
+  return text(output).trim();
+}
+
+export async function repositoryTree(target, { revision = "HEAD" } = {}) {
+  const output = await runGit(target, ["rev-parse", "--verify", `${assertRevision(revision)}^{tree}`]);
+  return text(output).trim();
+}
+
+export async function repositoryRemoteUrl(target, { remote = "origin" } = {}) {
+  try {
+    const output = await runGit(target, ["remote", "get-url", remote]);
+    return text(output).trim() || null;
+  } catch (error) {
+    if (error.cause?.code === 2 || /No such remote|no such remote/iu.test(error.message)) return null;
+    throw error;
+  }
+}
+
+export async function repositoryDiffEntries(target, {
+  baseRevision,
+  headRevision = "HEAD",
+  paths = null,
+} = {}) {
+  if (typeof baseRevision !== "string" || !baseRevision.trim()) {
+    throw repositoryError("E_REVISION_NOT_FOUND", "baseRevision is required for a repository diff");
+  }
+  const args = ["diff", "--name-status", "-z", "--find-renames", "--find-copies", assertRevision(baseRevision, "baseRevision"), assertRevision(headRevision, "headRevision")];
+  if (Array.isArray(paths) && paths.length > 0) {
+    args.push("--", ...paths.map(assertRepositoryPath));
+  }
+  return parseNameStatusZ(await runGit(target, args));
+}
+
+export async function repositoryIndexEntries(target, { paths = null } = {}) {
+  const args = ["ls-files", "--stage", "-z"];
+  if (Array.isArray(paths) && paths.length > 0) args.push("--", ...paths.map(assertRepositoryPath));
+  return parseIndexEntriesZ(await runGit(target, args));
+}
+
+export async function repositoryTreeEntry(target, { revision = "HEAD", path: repositoryPath } = {}) {
+  if (typeof revision !== "string" || !revision.trim()) throw repositoryError("E_REVISION_NOT_FOUND", "revision is required");
+  const safeRevision = assertRevision(revision);
+  const safePath = assertRepositoryPath(repositoryPath);
+  const output = await runGit(target, ["ls-tree", "-z", safeRevision, "--", safePath]);
+  const treeEntry = text(output).split("\0").find(Boolean);
+  if (!treeEntry) {
+    const error = repositoryError("E_REVISION_CONTENT_UNAVAILABLE", `Path is absent at revision ${safeRevision}: ${safePath}`);
+    error.notFound = true;
+    throw error;
+  }
+  const match = treeEntry.match(/^(\d+)\s+(\w+)\s+([a-f0-9]+)\t(.*)$/u);
+  if (!match) throw repositoryError("E_REVISION_PROVIDER_INVALID", `Cannot parse Git tree entry for ${safePath}`);
+  return { mode: match[1], type: match[2], objectId: match[3], path: match[4] };
+}
+
+export async function repositoryStatusEntries(target, { paths = null } = {}) {
+  const args = ["status", "--porcelain=v1", "-z", "--untracked-files=all"];
+  if (Array.isArray(paths) && paths.length > 0) args.push("--", ...paths.map(assertRepositoryPath));
+  return parseStatusZ(await runGit(target, args));
+}
+
+export async function repositoryBlobAtRef(target, { ref, path: repositoryPath } = {}) {
+  const safeRef = assertRevision(ref, "ref");
+  const safePath = assertRepositoryPath(repositoryPath);
+  try {
+    return Buffer.from(await runGit(target, ["cat-file", "blob", `${safeRef}:${safePath}`], { binary: true }));
+  } catch (error) {
+    const wrapped = repositoryError("E_REVISION_CONTENT_UNAVAILABLE", `Cannot read ${safePath} at revision ${safeRef}`, error);
+    wrapped.notFound = isGitNotFound(error);
+    throw wrapped;
+  }
+}
+
+export async function repositoryBlobOidAtRef(target, { ref, path: repositoryPath } = {}) {
+  const safeRef = assertRevision(ref, "ref");
+  const safePath = assertRepositoryPath(repositoryPath);
+  try {
+    const output = await runGit(target, ["rev-parse", "--verify", `${safeRef}:${safePath}`]);
+    return text(output).trim();
+  } catch (error) {
+    const wrapped = repositoryError("E_REVISION_CONTENT_UNAVAILABLE", `Cannot resolve ${safePath} at revision ${safeRef}`, error);
+    wrapped.notFound = isGitNotFound(error);
+    throw wrapped;
+  }
+}
+
+export async function expectedGitBlobOid(target, { path: repositoryPath } = {}) {
+  const safePath = assertRepositoryPath(repositoryPath);
+  try {
+    const output = await runGit(target, ["hash-object", `--path=${safePath}`, "--", safePath]);
+    return text(output).trim();
+  } catch (error) {
+    throw repositoryError("E_REVISION_CONTENT_UNAVAILABLE", `Cannot hash worktree path ${safePath}`, error);
+  }
+}
+
+export async function repositoryHasUnstagedChanges(target, { paths = null } = {}) {
+  const args = ["diff", "--quiet"];
+  if (Array.isArray(paths) && paths.length > 0) args.push("--", ...paths.map(assertRepositoryPath));
+  try {
+    await runGit(target, args);
+    return false;
+  } catch (error) {
+    if (error.cause?.code === 1) return true;
+    throw error;
+  }
+}
+
 export function parsePorcelainV1Z(stdout) {
   if (!stdout) return [];
   const entries = [];
@@ -54,17 +306,10 @@ export function parsePorcelainV1Z(stdout) {
 
 export async function currentChangedPaths(target, { paths = null } = {}) {
   try {
-    const args = ["-C", target];
-    if (paths && paths.length > 0) {
-      args.unshift("--literal-pathspecs");
-    }
-    args.push("status", "--porcelain=v1", "-z", "--untracked-files=all");
-    if (paths && paths.length > 0) {
-      args.push("--", ...paths);
-    }
-
-    const { stdout } = await execFileAsync("git", args, { windowsHide: true });
-    return parsePorcelainV1Z(stdout);
+    const entries = await repositoryStatusEntries(target, { paths });
+    return [...new Set(entries
+      .flatMap((entry) => [entry.path, entry.sourcePath].filter(Boolean))
+      .filter((relativePath) => !relativePath.startsWith(".forgeloop/")))].sort((a, b) => a.localeCompare(b));
   } catch {
     return null;
   }

package/src/core/responsibility.js

@@ -0,0 +1,265 @@
+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 { 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 { normalizeWriteClaims } from "./task-scope.js";
+import { taskResponsibilityPath } from "./task-paths.js";
+import { ensureWithin, fileExists } from "./filesystem.js";
+import { appendProtocolEvent } from "./events.js";
+import { withTaskTransaction } from "./transaction.js";
+import { assertTaskMutationAllowed } from "./task-claim-state.js";
+import { assertWorkspaceBinding } from "./workspace-binding.js";
+
+function responsibilityError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.name = "ResponsibilityError";
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function normalizePaths(paths, label) {
+  try {
+    return normalizeWriteClaims(paths ?? []);
+  } catch (error) {
+    throw responsibilityError("E_RESPONSIBILITY_INVALID", `${label}: ${error.message}`);
+  }
+}
+
+function coversPath(prefix, candidate) {
+  if (prefix === ".") return true;
+  return candidate === prefix || candidate.startsWith(`${prefix}/`);
+}
+
+function pathScopeErrors(responsibility, changedPaths) {
+  if (changedPaths === null) {
+    return [responsibilityError("E_RESPONSIBILITY_SCOPE_VIOLATION", "Changed paths cannot be resolved for responsibility validation")];
+  }
+  if (!Array.isArray(changedPaths)) {
+    return [responsibilityError("E_RESPONSIBILITY_SCOPE_VIOLATION", "Changed paths must be a list of relative paths")];
+  }
+  const unsafePaths = [];
+  const normalizedChangedPaths = [];
+  for (const value of changedPaths) {
+    try {
+      normalizedChangedPaths.push(normalizeWriteClaims([value])[0]);
+    } catch {
+      unsafePaths.push(String(value));
+    }
+  }
+  const allowed = responsibility.allowedPaths;
+  const readOnly = responsibility.readOnlyPaths;
+  const outOfScope = normalizedChangedPaths.filter((item) => !allowed.some((prefix) => coversPath(prefix, item)));
+  const readOnlyChanges = normalizedChangedPaths.filter((item) => readOnly.some((prefix) => coversPath(prefix, item)));
+  const errors = [];
+  if (unsafePaths.length > 0) {
+    errors.push(responsibilityError("E_RESPONSIBILITY_SCOPE_VIOLATION", `Changed paths are not safe relative paths: ${unsafePaths.join(", ")}`));
+  }
+  if (outOfScope.length > 0) {
+    errors.push(responsibilityError("E_RESPONSIBILITY_SCOPE_VIOLATION", `Changed paths are outside allowed responsibility paths: ${outOfScope.join(", ")}`));
+  }
+  if (readOnlyChanges.length > 0) {
+    errors.push(responsibilityError("E_RESPONSIBILITY_SCOPE_VIOLATION", `Changed paths violate read-only responsibility paths: ${readOnlyChanges.join(", ")}`));
+  }
+  return errors;
+}
+
+/** Validate the active responsibility boundary against canonical changed paths. */
+export function validateResponsibilityScope(responsibility, changedPaths) {
+  return pathScopeErrors(responsibility, changedPaths);
+}
+
+export async function validateResponsibilityContract(value, packageRoot = getPackageRoot()) {
+  try {
+    assertSchema(value, await readSchema("responsibility", packageRoot), "responsibility contract");
+  } catch (error) {
+    throw responsibilityError("E_RESPONSIBILITY_INVALID", error.message);
+  }
+  try {
+    const allowedPaths = normalizePaths(value.allowedPaths, "allowedPaths");
+    const readOnlyPaths = normalizePaths(value.readOnlyPaths, "readOnlyPaths");
+    const requiredCheckIds = [...new Set(value.requiredCheckIds)].sort();
+    if (requiredCheckIds.length !== value.requiredCheckIds.length) {
+      throw responsibilityError("E_RESPONSIBILITY_INVALID", "requiredCheckIds must not contain duplicates");
+    }
+    if (allowedPaths.some((item) => item === ".forgeloop" || item.startsWith(".forgeloop/"))) {
+      throw responsibilityError("E_RESPONSIBILITY_INVALID", "allowedPaths cannot include ForgeLoop protocol metadata");
+    }
+    if (readOnlyPaths.some((item) => item === ".forgeloop" || item.startsWith(".forgeloop/"))) {
+      throw responsibilityError("E_RESPONSIBILITY_INVALID", "readOnlyPaths cannot include ForgeLoop protocol metadata");
+    }
+    const normalized = {
+      ...value,
+      allowedPaths,
+      readOnlyPaths,
+      requiredCheckIds,
+      frozenInputs: {
+        contract: value.frozenInputs?.contract === true,
+        route: value.frozenInputs?.route === true,
+        claims: value.frozenInputs?.claims === true,
+      },
+      baseline: {
+        contractFingerprint: value.baseline.contractFingerprint,
+        routeFingerprint: value.baseline.routeFingerprint ?? null,
+        claimsFingerprint: value.baseline.claimsFingerprint,
+      },
+    };
+    assertSecretFree(normalized);
+    return normalized;
+  } catch (error) {
+    if (error.code === "E_RESPONSIBILITY_INVALID") throw error;
+    throw responsibilityError("E_RESPONSIBILITY_INVALID", error.message);
+  }
+}
+
+export async function readResponsibility(target, { taskId, packageRoot = getPackageRoot() } = {}) {
+  const relativePath = taskResponsibilityPath(taskId);
+  if (!(await fileExists(ensureWithin(target, relativePath)))) return null;
+  try {
+    const artifact = await readJsonArtifact(target, relativePath, "responsibility", packageRoot);
+    const value = await validateResponsibilityContract(artifact.value, packageRoot);
+    if (value.taskId !== taskId) throw responsibilityError("E_RESPONSIBILITY_INVALID", "Responsibility taskId does not match its task namespace", [relativePath]);
+    return { ...artifact, value };
+  } catch (error) {
+    if (error.code === "E_RESPONSIBILITY_INVALID") throw error;
+    throw responsibilityError("E_RESPONSIBILITY_INVALID", `Responsibility contract is invalid: ${error.message}`, [relativePath]);
+  }
+}
+
+async function currentResponsibilityInputs(target, { taskId, packageRoot }) {
+  const [contract, route, state, claims] = await Promise.all([
+    readContract(target, packageRoot, { taskId }),
+    readPersistedRoute(target, packageRoot, { taskId }),
+    readWorkState(target, { packageRoot, taskId }),
+    resolveTaskClaimState(target, { packageRoot, taskId }),
+  ]);
+  return {
+    contract,
+    route,
+    state,
+    claims,
+    claimsFingerprint: canonicalFingerprint(claims.effectiveWriteClaims ?? []),
+  };
+}
+
+export function validateResponsibilityFrozenInputs(responsibility, inputs) {
+  const errors = [];
+  const baseline = responsibility.baseline;
+  if (responsibility.frozenInputs.contract && baseline.contractFingerprint !== inputs.contract.fingerprint) {
+    errors.push(responsibilityError("E_RESPONSIBILITY_FROZEN_INPUT_DRIFT", "The current contract differs from the responsibility baseline"));
+  }
+  if (responsibility.frozenInputs.route && baseline.routeFingerprint !== (inputs.route?.fingerprint ?? null)) {
+    errors.push(responsibilityError("E_RESPONSIBILITY_FROZEN_INPUT_DRIFT", "The current route differs from the responsibility baseline"));
+  }
+  if (responsibility.frozenInputs.claims && baseline.claimsFingerprint !== inputs.claimsFingerprint) {
+    errors.push(responsibilityError("E_RESPONSIBILITY_FROZEN_INPUT_DRIFT", "The current effective write claims differ from the responsibility baseline"));
+  }
+  return errors;
+}
+
+export function validateResponsibilityChecks(responsibility, state) {
+  const checks = new Map((state?.checks ?? [])
+    .filter((check) => (check.details?.verificationCycle ?? state?.verificationCycle ?? 1) === (state?.verificationCycle ?? 1))
+    .map((check) => [check.id, check]));
+  const missing = responsibility.requiredCheckIds.filter((id) => checks.get(id)?.status !== "passed");
+  return missing.length === 0
+    ? []
+    : [responsibilityError("E_RESPONSIBILITY_REQUIRED_CHECK_MISSING", `Required responsibility checks are missing or not passed: ${missing.join(", ")}`)];
+}
+
+export async function resolveResponsibilityStatus(target, { taskId, packageRoot = getPackageRoot() } = {}) {
+  const artifact = await readResponsibility(target, { taskId, packageRoot });
+  if (!artifact) return { status: "NOT_APPLICABLE", taskId, path: taskResponsibilityPath(taskId), responsibility: null, errors: [] };
+  let inputs;
+  try {
+    inputs = await currentResponsibilityInputs(target, { taskId, packageRoot });
+  } catch (error) {
+    return { status: "INVALID", taskId, path: artifact.path, responsibility: artifact.value, errors: [{ code: error.code ?? "E_RESPONSIBILITY_INVALID", message: error.message }] };
+  }
+  const changedPaths = await currentChangedPaths(target);
+  const errors = [
+    ...validateResponsibilityScope(artifact.value, changedPaths),
+    ...validateResponsibilityFrozenInputs(artifact.value, inputs),
+    ...validateResponsibilityChecks(artifact.value, inputs.state),
+  ];
+  return {
+    status: errors.length === 0 ? "VALID" : "INVALID",
+    taskId,
+    path: artifact.path,
+    fingerprint: artifact.fingerprint,
+    responsibility: artifact.value,
+    changedPaths,
+    errors: errors.map((error) => ({ code: error.code, message: error.message })),
+  };
+}
+
+export async function assertResponsibilityValid(target, options = {}) {
+  const result = await resolveResponsibilityStatus(target, options);
+  if (result.status === "NOT_APPLICABLE" || result.status === "VALID") return result;
+  const first = result.errors[0] ?? { code: "E_RESPONSIBILITY_INVALID", message: "Responsibility constraints are invalid" };
+  throw responsibilityError(first.code, first.message, [result.path]);
+}
+
+export async function buildResponsibilityContract(target, {
+  taskId,
+  label,
+  allowedPaths,
+  readOnlyPaths = [],
+  requiredCheckIds = [],
+  frozenInputs = {},
+  packageRoot = getPackageRoot(),
+  createdAt = new Date().toISOString(),
+} = {}) {
+  const inputs = await currentResponsibilityInputs(target, { taskId, packageRoot });
+  const value = {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    taskId,
+    label,
+    createdAt,
+    allowedPaths: normalizePaths(allowedPaths ?? inputs.claims.effectiveWriteClaims, "allowedPaths"),
+    readOnlyPaths: normalizePaths(readOnlyPaths, "readOnlyPaths"),
+    requiredCheckIds: [...new Set(requiredCheckIds)].sort(),
+    frozenInputs: {
+      contract: frozenInputs.contract === true,
+      route: frozenInputs.route === true,
+      claims: frozenInputs.claims === true,
+    },
+    baseline: {
+      contractFingerprint: inputs.contract.fingerprint,
+      routeFingerprint: inputs.route?.fingerprint ?? null,
+      claimsFingerprint: inputs.claimsFingerprint,
+    },
+  };
+  return validateResponsibilityContract(value, packageRoot);
+}
+
+export async function setResponsibilityContract(target, options = {}) {
+  const { taskId, packageRoot = getPackageRoot() } = options;
+  const relativePath = taskResponsibilityPath(taskId);
+  return withTaskTransaction({ target, taskId, packageRoot, operation: "responsibility-set", recordCommitEvent: true }, async () => {
+    await assertTaskMutationAllowed(target, { taskId, packageRoot });
+    await assertWorkspaceBinding(target, { taskId, packageRoot, operation: "responsibility-set" });
+    if (await fileExists(ensureWithin(target, relativePath))) {
+      throw responsibilityError("E_RESPONSIBILITY_INVALID", "Responsibility contract is immutable during a pass", [relativePath]);
+    }
+    const state = await readWorkState(target, { packageRoot, taskId });
+    if (state && ["EXECUTING", "VERIFYING", "DIAGNOSING", "CORRECTING", "REVIEWING", "COMPLETE"].includes(state.phase)) {
+      throw responsibilityError("E_RESPONSIBILITY_INVALID", `Responsibility must be established before execution begins (current phase: ${state.phase})`, [relativePath]);
+    }
+    const value = await buildResponsibilityContract(target, options);
+    const artifact = await writeJsonArtifact(target, relativePath, value, "responsibility", packageRoot, { taskId, operation: "responsibility-set" });
+    await appendProtocolEvent(target, {
+      taskId,
+      event: "RESPONSIBILITY_SET",
+      fingerprint: artifact.fingerprint,
+      details: { responsibilityFingerprint: artifact.fingerprint, label: value.label },
+    }, packageRoot, { taskId });
+    return { taskId, path: relativePath, fingerprint: artifact.fingerprint, responsibility: value };
+  });
+}