frontend-project-context 1.2.0 → 1.3.0

package/src/project-context/task-context-schema.mjs

@@ -0,0 +1,290 @@
+import { canonicalValue, digestJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+
+export const TASK_CONTEXT_PLAN_SCHEMA_VERSION = 1;
+export const STAGE_RECEIPT_SCHEMA_VERSION = 1;
+export const STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION = 1;
+export const INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION = 1;
+export const CONTEXT_BUDGET_UNIT = "canonical-utf8-bytes";
+
+const ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const FORBIDDEN = /^(?:write|approve|approval|by|token|secret|shell|command|provider|autoRun|authority|execute|execution)$/iu;
+
+function invalid(kind, message, details) {
+  fail(`${kind}-schema-invalid`, message, { details });
+}
+
+function object(value, label, kind) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(kind, `${label} must be an object`);
+}
+
+function exactKeys(value, allowed, label, kind) {
+  for (const key of Object.keys(value)) {
+    if (FORBIDDEN.test(key)) invalid(kind, `${label} contains forbidden authority or execution field: ${key}`);
+    if (!allowed.has(key)) invalid(kind, `${label} contains unknown field: ${key}`);
+  }
+}
+
+function string(value, label, kind, options = {}) {
+  if (typeof value !== "string" || (!options.empty && value.length === 0)) invalid(kind, `${label} must be a non-empty string`);
+}
+
+function stableId(value, label, kind) {
+  string(value, label, kind);
+  if (!ID.test(value)) invalid(kind, `${label} must use stable lowercase dot/kebab naming`);
+}
+
+function digest(value, label, kind) {
+  string(value, label, kind);
+  if (!SHA256.test(value)) invalid(kind, `${label} must be sha256`);
+}
+
+function uniqueStrings(values, label, kind, options = {}) {
+  if (!Array.isArray(values) || (!options.empty && values.length === 0)) {
+    invalid(kind, `${label} must be ${options.empty ? "an" : "a non-empty"} array`);
+  }
+  const seen = new Set();
+  for (const value of values) {
+    string(value, `${label} entry`, kind);
+    if (seen.has(value)) invalid(kind, `${label} contains duplicate value: ${value}`);
+    seen.add(value);
+  }
+  return [...values].sort((left, right) => left.localeCompare(right));
+}
+
+function paths(values, label, kind, options = {}) {
+  const original = uniqueStrings(values, label, kind, options);
+  const normalized = original.map((value) => {
+    try {
+      return normalizeRelativePath(value, { label: `${label} entry` });
+    } catch (error) {
+      invalid(kind, `${label} must stay inside the project`, { path: value, reason: error.code ?? "invalid-path" });
+    }
+  });
+  if (new Set(normalized).size !== normalized.length) invalid(kind, `${label} contains duplicate normalized paths`);
+  return normalized.sort((left, right) => left.localeCompare(right));
+}
+
+function snapshots(value, label, kind) {
+  object(value, label, kind);
+  exactKeys(value, new Set(["contract", "sourcesLock", "projectionsLock"]), label, kind);
+  for (const key of ["contract", "sourcesLock", "projectionsLock"]) digest(value[key], `${label}.${key}`, kind);
+  return canonicalValue(value);
+}
+
+function isWithin(target, scope) {
+  return target === scope || target.startsWith(`${scope}/`);
+}
+
+function overlaps(left, right) {
+  return isWithin(left, right) || isWithin(right, left);
+}
+
+function transitiveDependencies(stages) {
+  const byId = new Map(stages.map((stage) => [stage.id, stage]));
+  const memo = new Map();
+  const visiting = new Set();
+  function visit(id) {
+    if (memo.has(id)) return memo.get(id);
+    if (visiting.has(id)) invalid("task-context-plan", `task context plan contains a dependency cycle at ${id}`);
+    visiting.add(id);
+    const dependencies = new Set();
+    for (const dependency of byId.get(id).dependsOn) {
+      if (!byId.has(dependency)) invalid("task-context-plan", `stage ${id} depends on unknown stage: ${dependency}`);
+      dependencies.add(dependency);
+      for (const inherited of visit(dependency)) dependencies.add(inherited);
+    }
+    visiting.delete(id);
+    memo.set(id, dependencies);
+    return dependencies;
+  }
+  for (const stage of stages) visit(stage.id);
+  return memo;
+}
+
+export function validateTaskContextPlan(input) {
+  const kind = "task-context-plan";
+  object(input, "task context plan", kind);
+  exactKeys(input, new Set(["schemaVersion", "kind", "projectId", "task", "workspace", "snapshots", "budget", "stages"]), "task context plan", kind);
+  if (input.schemaVersion !== TASK_CONTEXT_PLAN_SCHEMA_VERSION) invalid(kind, `task context plan schemaVersion must be ${TASK_CONTEXT_PLAN_SCHEMA_VERSION}`);
+  if (input.kind !== "task-context-plan") invalid(kind, "task context plan.kind must be task-context-plan");
+  stableId(input.projectId, "task context plan.projectId", kind);
+
+  object(input.task, "task context plan.task", kind);
+  exactKeys(input.task, new Set(["id", "title", "goal", "acceptance"]), "task context plan.task", kind);
+  stableId(input.task.id, "task context plan.task.id", kind);
+  string(input.task.title, "task context plan.task.title", kind);
+  string(input.task.goal, "task context plan.task.goal", kind);
+  if (!Array.isArray(input.task.acceptance) || input.task.acceptance.length === 0) invalid(kind, "task context plan.task.acceptance must be a non-empty array");
+  const acceptanceIds = new Set();
+  const acceptance = input.task.acceptance.map((entry, index) => {
+    const label = `task context plan.task.acceptance[${index}]`;
+    object(entry, label, kind);
+    exactKeys(entry, new Set(["id", "text"]), label, kind);
+    stableId(entry.id, `${label}.id`, kind);
+    string(entry.text, `${label}.text`, kind);
+    if (acceptanceIds.has(entry.id)) invalid(kind, `task context plan contains duplicate acceptance id: ${entry.id}`);
+    acceptanceIds.add(entry.id);
+    return { id: entry.id, text: entry.text };
+  }).sort((left, right) => left.id.localeCompare(right.id));
+
+  object(input.workspace, "task context plan.workspace", kind);
+  exactKeys(input.workspace, new Set(["branchLabel", "baseRevision"]), "task context plan.workspace", kind);
+  string(input.workspace.branchLabel, "task context plan.workspace.branchLabel", kind);
+  string(input.workspace.baseRevision, "task context plan.workspace.baseRevision", kind);
+
+  object(input.budget, "task context plan.budget", kind);
+  exactKeys(input.budget, new Set(["maxUtf8Bytes", "maxReadTargets"]), "task context plan.budget", kind);
+  for (const key of ["maxUtf8Bytes", "maxReadTargets"]) {
+    if (!Number.isSafeInteger(input.budget[key]) || input.budget[key] <= 0) invalid(kind, `task context plan.budget.${key} must be a positive integer`);
+  }
+
+  if (!Array.isArray(input.stages) || input.stages.length === 0) invalid(kind, "task context plan.stages must be a non-empty array");
+  const stageIds = new Set();
+  const stages = input.stages.map((stage, index) => {
+    const label = `task context plan.stages[${index}]`;
+    object(stage, label, kind);
+    exactKeys(stage, new Set(["id", "title", "objective", "dependsOn", "paths", "acceptanceIds"]), label, kind);
+    stableId(stage.id, `${label}.id`, kind);
+    if (stageIds.has(stage.id)) invalid(kind, `task context plan contains duplicate stage id: ${stage.id}`);
+    stageIds.add(stage.id);
+    string(stage.title, `${label}.title`, kind);
+    string(stage.objective, `${label}.objective`, kind);
+    const dependsOn = uniqueStrings(stage.dependsOn, `${label}.dependsOn`, kind, { empty: true });
+    dependsOn.forEach((id) => stableId(id, `${label}.dependsOn entry`, kind));
+    if (dependsOn.includes(stage.id)) invalid(kind, `stage ${stage.id} cannot depend on itself`);
+    const acceptanceForStage = uniqueStrings(stage.acceptanceIds, `${label}.acceptanceIds`, kind);
+    acceptanceForStage.forEach((id) => {
+      stableId(id, `${label}.acceptanceIds entry`, kind);
+      if (!acceptanceIds.has(id)) invalid(kind, `stage ${stage.id} references unknown acceptance id: ${id}`);
+    });
+    return {
+      id: stage.id,
+      title: stage.title,
+      objective: stage.objective,
+      dependsOn,
+      paths: paths(stage.paths, `${label}.paths`, kind),
+      acceptanceIds: acceptanceForStage,
+    };
+  }).sort((left, right) => left.id.localeCompare(right.id));
+  const dependencies = transitiveDependencies(stages);
+  for (let leftIndex = 0; leftIndex < stages.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < stages.length; rightIndex += 1) {
+      const left = stages[leftIndex];
+      const right = stages[rightIndex];
+      if (dependencies.get(left.id).has(right.id) || dependencies.get(right.id).has(left.id)) continue;
+      const conflict = left.paths.find((leftPath) => right.paths.some((rightPath) => overlaps(leftPath, rightPath)));
+      if (conflict) invalid(kind, `independent stages ${left.id} and ${right.id} have overlapping paths`, { path: conflict });
+    }
+  }
+
+  return canonicalValue({
+    schemaVersion: TASK_CONTEXT_PLAN_SCHEMA_VERSION,
+    kind: "task-context-plan",
+    projectId: input.projectId,
+    task: { id: input.task.id, title: input.task.title, goal: input.task.goal, acceptance },
+    workspace: { branchLabel: input.workspace.branchLabel, baseRevision: input.workspace.baseRevision },
+    snapshots: snapshots(input.snapshots, "task context plan.snapshots", kind),
+    budget: { maxUtf8Bytes: input.budget.maxUtf8Bytes, maxReadTargets: input.budget.maxReadTargets },
+    stages,
+  });
+}
+
+export function taskContextPlanDigest(plan) {
+  return digestJson(validateTaskContextPlan(plan));
+}
+
+function acceptanceResult(value, label, kind) {
+  object(value, label, kind);
+  exactKeys(value, new Set(["id", "status", "evidence"]), label, kind);
+  stableId(value.id, `${label}.id`, kind);
+  if (!["observed", "not-observed"].includes(value.status)) invalid(kind, `${label}.status must be observed or not-observed`);
+  return { id: value.id, status: value.status, evidence: paths(value.evidence, `${label}.evidence`, kind, { empty: true }) };
+}
+
+function verificationResult(value, label, kind) {
+  object(value, label, kind);
+  exactKeys(value, new Set(["id", "status", "summary", "evidence"]), label, kind);
+  stableId(value.id, `${label}.id`, kind);
+  if (!["passed", "failed", "observed", "skipped"].includes(value.status)) invalid(kind, `${label}.status is invalid`);
+  string(value.summary, `${label}.summary`, kind);
+  return { id: value.id, status: value.status, summary: value.summary, evidence: paths(value.evidence, `${label}.evidence`, kind, { empty: true }) };
+}
+
+export function validateStageReceipt(input, planInput, options = {}) {
+  const kind = "stage-receipt";
+  object(input, "stage receipt", kind);
+  exactKeys(input, new Set([
+    "schemaVersion", "kind", "projectId", "taskId", "stageId", "planDigest", "inputBundleDigest", "status",
+    "changedPaths", "acceptanceResults", "verificationResults", "decisions", "openIssues", "nextStageId",
+  ]), "stage receipt", kind);
+  if (input.schemaVersion !== STAGE_RECEIPT_SCHEMA_VERSION) invalid(kind, `stage receipt schemaVersion must be ${STAGE_RECEIPT_SCHEMA_VERSION}`);
+  if (input.kind !== "stage-receipt") invalid(kind, "stage receipt.kind must be stage-receipt");
+  for (const [field, label] of [["projectId", "projectId"], ["taskId", "taskId"], ["stageId", "stageId"]]) stableId(input[field], `stage receipt.${label}`, kind);
+  digest(input.planDigest, "stage receipt.planDigest", kind);
+  digest(input.inputBundleDigest, "stage receipt.inputBundleDigest", kind);
+  if (options.expectedInputBundleDigest !== undefined && input.inputBundleDigest !== options.expectedInputBundleDigest) {
+    invalid(kind, "stage receipt input bundle digest is stale", { expected: options.expectedInputBundleDigest, actual: input.inputBundleDigest });
+  }
+  if (!["completed", "blocked"].includes(input.status)) invalid(kind, "stage receipt.status must be completed or blocked");
+  const changedPaths = paths(input.changedPaths, "stage receipt.changedPaths", kind, { empty: true });
+  if (!Array.isArray(input.acceptanceResults)) invalid(kind, "stage receipt.acceptanceResults must be an array");
+  const resultIds = new Set();
+  const acceptanceResults = input.acceptanceResults.map((entry, index) => {
+    const normalized = acceptanceResult(entry, `stage receipt.acceptanceResults[${index}]`, kind);
+    if (resultIds.has(normalized.id)) invalid(kind, `stage receipt contains duplicate acceptance result: ${normalized.id}`);
+    resultIds.add(normalized.id);
+    return normalized;
+  }).sort((left, right) => left.id.localeCompare(right.id));
+  if (!Array.isArray(input.verificationResults)) invalid(kind, "stage receipt.verificationResults must be an array");
+  const verificationIds = new Set();
+  const verificationResults = input.verificationResults.map((entry, index) => {
+    const normalized = verificationResult(entry, `stage receipt.verificationResults[${index}]`, kind);
+    if (verificationIds.has(normalized.id)) invalid(kind, `stage receipt contains duplicate verification result: ${normalized.id}`);
+    verificationIds.add(normalized.id);
+    return normalized;
+  }).sort((left, right) => left.id.localeCompare(right.id));
+  const decisions = uniqueStrings(input.decisions, "stage receipt.decisions", kind, { empty: true });
+  const openIssues = uniqueStrings(input.openIssues, "stage receipt.openIssues", kind, { empty: true });
+  if (input.status === "blocked" && openIssues.length === 0) invalid(kind, "blocked stage receipt requires at least one open issue");
+  if (input.status === "completed" && openIssues.length > 0) invalid(kind, "completed stage receipt cannot contain open issues");
+  if (input.nextStageId !== undefined) stableId(input.nextStageId, "stage receipt.nextStageId", kind);
+
+  if (planInput !== undefined) {
+    const plan = validateTaskContextPlan(planInput);
+    if (input.projectId !== plan.projectId || input.taskId !== plan.task.id) invalid(kind, "stage receipt project or task does not match its plan");
+    if (input.planDigest !== digestJson(plan)) invalid(kind, "stage receipt plan digest is stale");
+    const stage = plan.stages.find((entry) => entry.id === input.stageId);
+    if (!stage) invalid(kind, `stage receipt references unknown stage: ${input.stageId}`);
+    for (const id of resultIds) if (!stage.acceptanceIds.includes(id)) invalid(kind, `stage receipt references acceptance outside stage: ${id}`);
+    if (input.status === "completed") {
+      const missing = stage.acceptanceIds.filter((id) => !resultIds.has(id));
+      if (missing.length > 0) invalid(kind, "completed stage receipt does not cover all stage acceptance IDs", { missing });
+      if (acceptanceResults.some((entry) => entry.status !== "observed")) invalid(kind, "completed stage receipt requires observed acceptance results");
+    }
+    if (input.nextStageId !== undefined && !plan.stages.some((entry) => entry.id === input.nextStageId)) invalid(kind, `stage receipt references unknown next stage: ${input.nextStageId}`);
+  }
+
+  return canonicalValue({
+    schemaVersion: STAGE_RECEIPT_SCHEMA_VERSION,
+    kind: "stage-receipt",
+    projectId: input.projectId,
+    taskId: input.taskId,
+    stageId: input.stageId,
+    planDigest: input.planDigest,
+    inputBundleDigest: input.inputBundleDigest,
+    status: input.status,
+    changedPaths,
+    acceptanceResults,
+    verificationResults,
+    decisions,
+    openIssues,
+    ...(input.nextStageId !== undefined ? { nextStageId: input.nextStageId } : {}),
+  });
+}
+
+export function stageReceiptDigest(receipt, plan) {
+  return digestJson(validateStageReceipt(receipt, plan));
+}

package/src/project-context/task-context.mjs

@@ -0,0 +1,361 @@
+import { canonicalJson, digestJson } from "./canonical-json.mjs";
+import { blockingContextFindings, checkProject } from "./checker.mjs";
+import { ProjectContextError, fail } from "./errors.mjs";
+import { readJsonFile } from "./io.mjs";
+import { normalizeRelativePath, resolveExistingInside, resolveWritableInside } from "./path-policy.mjs";
+import { loadProject } from "./project-store.mjs";
+import { effectiveItems, scopeApplies } from "./scope-compiler.mjs";
+import {
+  CONTEXT_BUDGET_UNIT,
+  INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+  STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+  taskContextPlanDigest,
+  validateStageReceipt,
+  validateTaskContextPlan,
+} from "./task-context-schema.mjs";
+
+const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
+const EXCLUDED_BODIES = Object.freeze(["chat-history", "code-bodies", "git-diffs", "source-bodies", "verification-logs"]);
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function snapshots(project) {
+  return {
+    contract: project.contractDigest,
+    sourcesLock: project.sourcesLockDigest,
+    projectionsLock: project.projectionsLockDigest,
+  };
+}
+
+function pathWithin(target, scope) {
+  return target === scope || target.startsWith(`${scope}/`);
+}
+
+function pathsOverlap(left, right) {
+  return pathWithin(left, right) || pathWithin(right, left);
+}
+
+function finding(code, severity, details = {}) {
+  return { code, severity, ...details };
+}
+
+function stableFindings(findings) {
+  const byJson = new Map();
+  for (const entry of findings) byJson.set(canonicalJson(entry), entry);
+  return [...byJson.values()].sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right)));
+}
+
+async function validateProjectPaths(root, values, label) {
+  for (const value of values) {
+    try {
+      try {
+        await resolveExistingInside(root, value);
+      } catch (error) {
+        if (error?.code !== "source-missing") throw error;
+        await resolveWritableInside(root, value);
+      }
+    } catch (error) {
+      fail("task-context-path-invalid", `${label} leaves the project or resolves through an unsafe path: ${value}`, {
+        details: { path: value, reason: error.code ?? "invalid-path" },
+      });
+    }
+  }
+}
+
+function normalizeSignalPaths(values, label) {
+  const normalized = values.map((value) => normalizeRelativePath(value, { label }));
+  if (new Set(normalized).size !== normalized.length) fail("task-context-path-invalid", `${label} contains duplicate normalized paths`);
+  return normalized.sort((left, right) => left.localeCompare(right));
+}
+
+async function validatePlanPaths(root, plan) {
+  await validateProjectPaths(root, plan.stages.flatMap((stage) => stage.paths), "task stage path");
+}
+
+function normalizedReceipts(receiptInputs, plan) {
+  const digest = taskContextPlanDigest(plan);
+  const byStage = new Map();
+  for (const input of receiptInputs) {
+    const structural = validateStageReceipt(input);
+    if (byStage.has(structural.stageId)) fail("stage-receipt-duplicate", `multiple receipts were provided for stage: ${structural.stageId}`);
+    if (structural.planDigest === digest) validateStageReceipt(structural, plan);
+    else {
+      // Validate all plan-bound semantics independently while preserving the stale digest as a finding.
+      validateStageReceipt({ ...structural, planDigest: digest }, plan);
+    }
+    byStage.set(structural.stageId, structural);
+  }
+  return byStage;
+}
+
+function selectedItems(contract, targetPaths, findings) {
+  const byId = new Map();
+  for (const targetPath of targetPaths) {
+    try {
+      for (const item of effectiveItems(contract.items, targetPath)) byId.set(item.id, item);
+    } catch (error) {
+      if (!(error instanceof ProjectContextError) || error.code !== "contract-conflict") throw error;
+      findings.push(finding("contract-conflict", "blocked", { path: targetPath }));
+      for (const item of contract.items.filter((entry) => entry.status === "approved" && scopeApplies(entry.scope, targetPath))) byId.set(item.id, item);
+    }
+  }
+  return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id)).map((item) => ({
+    id: item.id,
+    kind: item.kind,
+    subject: item.subject,
+    value: structuredClone(item.value),
+    statement: item.statement,
+    scope: structuredClone(item.scope),
+    sourceIds: [...item.sources].sort((left, right) => left.localeCompare(right)),
+  }));
+}
+
+function sourceReadTargets(contract, items) {
+  const sourceIds = new Set(items.flatMap((item) => item.sourceIds));
+  return contract.sources
+    .filter((source) => sourceIds.has(source.id) && LOCAL_SOURCE_KINDS.has(source.kind))
+    .map((source) => ({ path: source.path, reason: "contract-source", sourceId: source.id }));
+}
+
+function mergeReadTargets(targets) {
+  const byPath = new Map();
+  for (const target of targets) {
+    const current = byPath.get(target.path);
+    if (!current) byPath.set(target.path, target);
+    else if (canonicalJson(target).localeCompare(canonicalJson(current)) < 0) byPath.set(target.path, target);
+  }
+  return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function receiptSummary(receipt) {
+  return {
+    stageId: receipt.stageId,
+    status: receipt.status,
+    inputBundleDigest: receipt.inputBundleDigest,
+    changedPaths: [...receipt.changedPaths],
+    acceptanceResults: structuredClone(receipt.acceptanceResults),
+    verificationResults: structuredClone(receipt.verificationResults),
+    decisions: [...receipt.decisions],
+    openIssues: [...receipt.openIssues],
+  };
+}
+
+function withDigestAndBytes(input, digestField) {
+  const value = structuredClone(input);
+  let used = 0;
+  for (let iteration = 0; iteration < 8; iteration += 1) {
+    if (value.budget) value.budget.usedUtf8Bytes = used;
+    delete value[digestField];
+    value[digestField] = digestJson(value);
+    const next = Buffer.byteLength(canonicalJson(value), "utf8");
+    if (next === used) break;
+    used = next;
+  }
+  if (value.budget) value.budget.usedUtf8Bytes = used;
+  delete value[digestField];
+  value[digestField] = digestJson(value);
+  return value;
+}
+
+function baselineFindings(plan, project) {
+  const current = snapshots(project);
+  const findings = [];
+  for (const key of Object.keys(current)) {
+    if (plan.snapshots[key] !== current[key]) findings.push(finding(`${key === "contract" ? "contract-baseline" : key === "sourcesLock" ? "sources-lock-baseline" : "projections-lock-baseline"}-stale`, "blocked", {
+      expected: plan.snapshots[key],
+      actual: current[key],
+    }));
+  }
+  return findings;
+}
+
+function checkerFindings(entries) {
+  const blocking = new Set(blockingContextFindings(entries).map((entry) => canonicalJson(entry)));
+  return entries.map((entry) => finding(
+    entry.code.startsWith("source-") ? "source-drift" : entry.code,
+    blocking.has(canonicalJson(entry)) ? "blocked" : "attention",
+    { projectFinding: entry },
+  ));
+}
+
+function acceptanceFor(plan, stage) {
+  const ids = new Set(stage.acceptanceIds);
+  return plan.task.acceptance.filter((entry) => ids.has(entry.id)).map((entry) => structuredClone(entry));
+}
+
+export async function buildStageContextBundle(root, project, planInput, options) {
+  const plan = validateTaskContextPlan(planInput);
+  if (plan.projectId !== project.contract.project.id) fail("task-context-project-mismatch", "task context plan belongs to a different project");
+  await validatePlanPaths(root, plan);
+  const stage = plan.stages.find((entry) => entry.id === options.stageId);
+  if (!stage) fail("task-context-stage-missing", `task context plan has no stage: ${options.stageId}`);
+  const changedPaths = normalizeSignalPaths(options.changedPaths ?? [], "changed path");
+  await validateProjectPaths(root, changedPaths, "changed path");
+  const receipts = normalizedReceipts(options.receipts ?? [], plan);
+  const planDigest = taskContextPlanDigest(plan);
+  const findings = [...baselineFindings(plan, project), ...checkerFindings(await checkProject(root, project))];
+  const dependencyReceipts = [];
+  for (const dependencyId of stage.dependsOn) {
+    const receipt = receipts.get(dependencyId);
+    if (!receipt) {
+      findings.push(finding("stage-dependency-missing", "blocked", { stageId: stage.id, dependencyStageId: dependencyId }));
+      continue;
+    }
+    dependencyReceipts.push(receiptSummary(receipt));
+    if (receipt.planDigest !== planDigest) findings.push(finding("stage-receipt-stale", "blocked", { stageId: dependencyId, reason: "plan-digest" }));
+    if (receipt.status !== "completed") findings.push(finding("stage-dependency-blocked", "blocked", { stageId: stage.id, dependencyStageId: dependencyId }));
+  }
+  const targetPaths = uniqueSorted([...stage.paths, ...changedPaths]);
+  const contractItems = selectedItems(project.contract, targetPaths, findings);
+  const readTargets = mergeReadTargets([
+    ...stage.paths.map((entry) => ({ path: entry, reason: "stage-scope" })),
+    ...changedPaths.map((entry) => ({ path: entry, reason: "host-changed-path-signal" })),
+    ...sourceReadTargets(project.contract, contractItems),
+  ]);
+  if (readTargets.length > plan.budget.maxReadTargets) findings.push(finding("read-target-budget-insufficient", "blocked", {
+    limit: plan.budget.maxReadTargets,
+    required: readTargets.length,
+  }));
+  let bundle = withDigestAndBytes({
+    schemaVersion: STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+    kind: "stage-context-bundle",
+    project: { id: project.contract.project.id, name: project.contract.project.name },
+    task: { id: plan.task.id, title: plan.task.title, goal: plan.task.goal },
+    stage: {
+      id: stage.id,
+      title: stage.title,
+      objective: stage.objective,
+      acceptance: acceptanceFor(plan, stage),
+      paths: [...stage.paths],
+    },
+    workspace: structuredClone(plan.workspace),
+    planDigest,
+    snapshots: snapshots(project),
+    dependencyReceipts: dependencyReceipts.sort((left, right) => left.stageId.localeCompare(right.stageId)),
+    changedPaths,
+    contractItems,
+    readTargets,
+    findings: stableFindings(findings),
+    excluded: [...EXCLUDED_BODIES],
+    budget: {
+      unit: CONTEXT_BUDGET_UNIT,
+      maxUtf8Bytes: plan.budget.maxUtf8Bytes,
+      maxReadTargets: plan.budget.maxReadTargets,
+      usedUtf8Bytes: 0,
+      readTargetCount: readTargets.length,
+    },
+    status: findings.some((entry) => entry.severity === "blocked") ? "blocked" : "ready",
+  }, "bundleDigest");
+  if (bundle.budget.usedUtf8Bytes > plan.budget.maxUtf8Bytes && !bundle.findings.some((entry) => entry.code === "context-budget-insufficient")) {
+    bundle.findings = stableFindings([...bundle.findings, finding("context-budget-insufficient", "blocked", {
+      limit: plan.budget.maxUtf8Bytes,
+      required: bundle.budget.usedUtf8Bytes,
+    })]);
+    bundle.status = "blocked";
+    bundle = withDigestAndBytes(bundle, "bundleDigest");
+  }
+  return bundle;
+}
+
+function receiptScopeEscapes(plan, receipt) {
+  const stage = plan.stages.find((entry) => entry.id === receipt.stageId);
+  if (!stage) return receipt.changedPaths;
+  return receipt.changedPaths.filter((changedPath) => !stage.paths.some((stagePath) => pathWithin(changedPath, stagePath)));
+}
+
+function pathOverlapFindings(mainPaths, branchPaths) {
+  const findings = [];
+  for (const mainPath of mainPaths) {
+    for (const branchPath of branchPaths) {
+      if (pathsOverlap(mainPath, branchPath)) findings.push(finding("path-overlap", "attention", { mainPath, branchPath }));
+    }
+  }
+  return findings;
+}
+
+function itemIdsForPaths(contract, paths, findings) {
+  return new Set(selectedItems(contract, paths, findings).map((item) => item.id));
+}
+
+export async function buildIntegrationReviewBundle(root, project, planInput, options = {}) {
+  const plan = validateTaskContextPlan(planInput);
+  if (plan.projectId !== project.contract.project.id) fail("task-context-project-mismatch", "task context plan belongs to a different project");
+  await validatePlanPaths(root, plan);
+  const mainChangedPaths = normalizeSignalPaths(options.mainChangedPaths ?? [], "main changed path");
+  const branchChangedPaths = normalizeSignalPaths(options.branchChangedPaths ?? [], "branch changed path");
+  await validateProjectPaths(root, [...mainChangedPaths, ...branchChangedPaths], "integration changed path");
+  const receipts = normalizedReceipts(options.receipts ?? [], plan);
+  const planDigest = taskContextPlanDigest(plan);
+  const findings = [
+    ...baselineFindings(plan, project),
+    ...checkerFindings(await checkProject(root, project)),
+    ...pathOverlapFindings(mainChangedPaths, branchChangedPaths),
+  ];
+  for (const stage of plan.stages) {
+    const receipt = receipts.get(stage.id);
+    if (!receipt || receipt.status !== "completed") {
+      findings.push(finding("stage-incomplete", "blocked", { stageId: stage.id, reason: receipt ? receipt.status : "missing-receipt" }));
+      continue;
+    }
+    if (receipt.planDigest !== planDigest) findings.push(finding("stage-receipt-stale", "blocked", { stageId: stage.id, reason: "plan-digest" }));
+    for (const escapedPath of receiptScopeEscapes(plan, receipt)) findings.push(finding("stage-scope-escaped", "blocked", { stageId: stage.id, path: escapedPath }));
+  }
+  const mainItems = itemIdsForPaths(project.contract, mainChangedPaths, findings);
+  const branchItems = itemIdsForPaths(project.contract, branchChangedPaths, findings);
+  for (const itemId of [...mainItems].filter((id) => branchItems.has(id)).sort()) findings.push(finding("contract-overlap", "attention", { itemId }));
+  const decisionCandidates = [...receipts.values()].flatMap((receipt) => receipt.decisions.map((decision) => ({ stageId: receipt.stageId, decision })))
+    .sort((left, right) => left.stageId.localeCompare(right.stageId) || left.decision.localeCompare(right.decision));
+  for (const candidate of decisionCandidates) findings.push(finding("decision-candidate", "attention", candidate));
+  const conflictPaths = uniqueSorted(findings.flatMap((entry) => [entry.mainPath, entry.branchPath, entry.path].filter(Boolean)));
+  const relevantItems = selectedItems(project.contract, uniqueSorted([...mainChangedPaths, ...branchChangedPaths]), findings);
+  const readTargets = mergeReadTargets([
+    ...conflictPaths.map((entry) => ({ path: entry, reason: "integration-conflict" })),
+    ...sourceReadTargets(project.contract, relevantItems),
+  ]);
+  const normalizedFindings = stableFindings(findings);
+  const bundle = {
+    schemaVersion: INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+    kind: "integration-review-bundle",
+    project: { id: project.contract.project.id, name: project.contract.project.name },
+    task: { id: plan.task.id, title: plan.task.title, goal: plan.task.goal },
+    workspace: structuredClone(plan.workspace),
+    planDigest,
+    planSnapshots: structuredClone(plan.snapshots),
+    currentSnapshots: snapshots(project),
+    mainChangedPaths,
+    branchChangedPaths,
+    receipts: [...receipts.values()].map(receiptSummary).sort((left, right) => left.stageId.localeCompare(right.stageId)),
+    contractOverlapItemIds: [...mainItems].filter((id) => branchItems.has(id)).sort(),
+    decisionCandidates,
+    readTargets,
+    findings: normalizedFindings,
+    excluded: [...EXCLUDED_BODIES, "git-operations", "test-execution"].sort(),
+    status: normalizedFindings.some((entry) => entry.severity === "blocked") ? "blocked" : "reviewable",
+  };
+  return { ...bundle, bundleDigest: digestJson(bundle) };
+}
+
+async function readInputs(root, planPath, receiptPaths) {
+  const resolvedPlan = await resolveExistingInside(root, planPath);
+  const plan = await readJsonFile(resolvedPlan.absolute, "task context plan");
+  const receipts = [];
+  for (const receiptPath of receiptPaths) {
+    const resolved = await resolveExistingInside(root, receiptPath);
+    receipts.push(await readJsonFile(resolved.absolute, "stage receipt"));
+  }
+  return { plan, receipts };
+}
+
+export async function buildStageContextBundleFiles(root, planPath, options) {
+  const { plan, receipts } = await readInputs(root, planPath, options.receiptPaths ?? []);
+  const project = await loadProject(root);
+  return buildStageContextBundle(root, project, plan, { ...options, receipts });
+}
+
+export async function buildIntegrationReviewBundleFiles(root, planPath, options) {
+  const { plan, receipts } = await readInputs(root, planPath, options.receiptPaths ?? []);
+  const project = await loadProject(root);
+  return buildIntegrationReviewBundle(root, project, plan, { ...options, receipts });
+}