frontend-project-context 1.9.1 → 1.10.0

package/src/project-context/cli.mjs

@@ -24,6 +24,8 @@ import { buildProjectStatus } from "./project-status.mjs";
 import { buildIntegrationReviewBundleFiles, buildStageContextBundleFiles } from "./task-context.mjs";
 import { applyMigrationPlanFile, buildMigrationPlanFile, buildUpgradeAssessment } from "./upgrade.mjs";
 import { buildTruthReconciliationReviewFiles } from "./truth-reconciliation.mjs";
+import { buildProjectBrief, buildTaskHandoff } from "./task-handoff.mjs";
+import { renderWorkView } from "./work-view.mjs";
 import { buildInitializationInstruction, renderInitializationPrompt } from "./initialization-instruction.mjs";
 
 const HELP = `project-context — model-neutral project contract compiler
@@ -33,6 +35,8 @@ Usage:
   project-context capabilities --project PATH [--json]
   project-context instructions --project PATH [--json | --prompt]
   project-context status --project PATH [--json]
+  project-context project-brief --project PATH [--view legacy|work] [--json]
+  project-context task-handoff --project PATH --input FILE_OR_DASH [--view legacy|work] [--json]
   project-context evidence --project PATH --input FILE [--json]
   project-context upgrade-check --project PATH --from-version VERSION [--json]
   project-context upgrade-plan --project PATH --assessment FILE [--json]
@@ -68,7 +72,7 @@ const VALUE_FLAGS = new Set([
   "project", "id", "name", "output", "proposal", "by", "task", "target", "rationale",
   "kind", "pointer", "reference", "subject", "value", "value-json", "statement", "scope", "scope-path",
   "verification", "verification-source", "verification-expected-json", "digest-mode",
-  "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan", "stage", "from-version", "assessment", "previous", "previous-review",
+  "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan", "stage", "from-version", "assessment", "previous", "previous-review", "view",
 ]);
 const LIST_FLAGS = new Set([
   "ids", "path", "input", "changed-path", "sources", "overrides", "required-source", "conditional-source", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
@@ -79,6 +83,8 @@ const COMMAND_OPTIONS = new Map([
   ["capabilities", new Set(["project", "json", "help"])],
   ["instructions", new Set(["project", "json", "prompt", "help"])],
   ["status", new Set(["project", "json", "help"])],
+  ["project-brief", new Set(["project", "json", "help", "view"])],
+  ["task-handoff", new Set(["project", "input", "json", "help", "view"])],
   ["evidence", new Set(["project", "input", "json", "help"])],
   ["upgrade-check", new Set(["project", "from-version", "json", "help"])],
   ["upgrade-plan", new Set(["project", "assessment", "json", "help"])],
@@ -374,6 +380,44 @@ async function runCommand(command, options) {
     const summary = `Project Context: ${result.status.initialization.state}; health ${result.status.health}; AI Entry ${result.status.entry.state}.\n`;
     return { exitCode: result.exitCode, stdout: jsonOrText(options, result.status, summary), stderr: "" };
   }
+  if (command === "project-brief") {
+    const view = options.view ?? "legacy";
+    if (!["legacy", "work"].includes(view)) fail("argument-conflict", "--view must be legacy or work");
+    const brief = await buildProjectBrief(root, { view });
+    if (view === "work") return { exitCode: brief.delivery.status === "withheld" || brief.connection !== "available" ? 1 : 0, stdout: jsonOrText(options, brief, renderWorkView(brief)), stderr: "" };
+    const active = brief.tasks.filter((task) => task.lifecycle === "active");
+    const invalid = brief.tasks.filter((task) => task.status === "invalid-record");
+    const summary = [
+      `已确认：项目 ${brief.project?.id ?? "未初始化"}；治理 ${brief.projectHealth}；已发现 ${brief.tasks.length} 条任务记录。`,
+      `待核实：${brief.findingCodes.join("、") || "无项目治理缺口"}${invalid.length ? `；${invalid.length} 条任务记录无效` : ""}。`,
+      `需要你决定：${active.length > 1 ? `从 ${active.length} 条活动任务中选择 taskId` : active.length === 1 ? `确认是否继续 ${active[0].taskId}` : "有新任务时提供目标和依据"}。`,
+      `接下来会做什么：${brief.nextAction}。`,
+    ].join("\n") + "\n";
+    return { exitCode: brief.connection === "available" || brief.connection === "not-connected" ? 0 : 1, stdout: jsonOrText(options, brief, summary), stderr: "" };
+  }
+  if (command === "task-handoff") {
+    const view = options.view ?? "legacy";
+    if (!["legacy", "work"].includes(view)) fail("argument-conflict", "--view must be legacy or work");
+    const inputPath = oneListValue(options, "input");
+    let stdinText;
+    if (inputPath === "-") {
+      let chunks = "";
+      for await (const chunk of process.stdin) {
+        chunks += chunk;
+        if (Buffer.byteLength(chunks) > 512 * 1024) fail("task-handoff-schema-invalid", "stdin handoff input exceeds 512 KiB");
+      }
+      stdinText = chunks;
+    }
+    const bundle = await buildTaskHandoff(root, inputPath, stdinText, { view });
+    const summary = [
+      `已确认：任务 ${bundle.taskIdentity.taskId}；当前意图 ${bundle.intent}；状态 ${bundle.taskStatus}。`,
+      `待核实：${bundle.gaps.map((gap) => `${gap.code} (${gap.id})`).join("、") || "无当前缺口"}。`,
+      `需要你决定：${bundle.questions.filter((question) => question.blockingNow).map((question) => question.question).join("、") || "无当前阻断决定"}。`,
+      `接下来会做什么：${bundle.nextAction}；${bundle.gate.instruction}`,
+    ].join("\n") + "\n";
+    const exitCode = bundle.taskStatus === "blocked" ? 2 : ["ready-to-implement", "ready-for-read-only", "inactive"].includes(bundle.taskStatus) ? 0 : 1;
+    return { exitCode: view === "work" && bundle.delivery.status === "withheld" ? bundle.taskStatus === "blocked" ? 2 : 1 : exitCode, stdout: jsonOrText(options, bundle, view === "work" ? renderWorkView(bundle) : summary), stderr: "" };
+  }
   if (command === "evidence") {
     const bundle = await buildEvidenceBundleFile(root, oneListValue(options, "input"));
     const summary = [

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

@@ -2,7 +2,7 @@ import { canonicalJson, canonicalValue, digestJson } from "./canonical-json.mjs"
 import { sourceStatus } from "./contract-schema.mjs";
 import { coverageDomainForPath, coverageProfile } from "./coverage-profile.mjs";
 import { fail } from "./errors.mjs";
-import { normalizeRelativePath, resolveExistingInside } from "./path-policy.mjs";
+import { inspectContextTarget, normalizeRelativePath, resolveExistingInside } from "./path-policy.mjs";
 import { renderCollectedContextBundle } from "./renderer.mjs";
 import { effectiveItems } from "./scope-compiler.mjs";
 
@@ -176,6 +176,7 @@ export async function buildContextBundle(root, project, input) {
     ? []
     : uniqueSorted(input.paths.map((value) => normalizeRelativePath(value, { allowRoot: true, label: "target path" })));
   const task = input.task ?? "";
+  for (const targetPath of paths) await inspectContextTarget(root, targetPath);
   const sections = mode === "locate"
     ? [{ path: ".", items: effectiveItems(project.contract.items.filter((item) => item.scope.kind === "project"), ".") }]
     : paths.map((targetPath) => ({ path: targetPath, items: effectiveItems(project.contract.items, targetPath) }));

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

@@ -361,7 +361,7 @@ export function validateProjectionLock(lock) {
       if (entry.regionId !== "project-context-ai-entry") fail("schema-invalid-enum", "AI Entry regionId is invalid");
       string(entry.regionDigest, `${label}.regionDigest`);
       if (!SHA256.test(entry.regionDigest)) fail("schema-invalid", "AI Entry regionDigest must be sha256");
-      if (![1, 2, 3, 4, 5].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, 3, 4, or 5");
+      if (![1, 2, 3, 4, 5, 6, 7].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, 3, 4, 5, 6, or 7");
       if (typeof entry.createdFile !== "boolean") fail("schema-invalid", `${label}.createdFile must be boolean`);
     } else {
       if (entry.target !== "agents" && entry.target !== "ruler") fail("schema-invalid-enum", "projection target is invalid");

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

@@ -2,11 +2,11 @@ import { canonicalValue, digestJson, validateJsonValue } from "./canonical-json.
 import { fail } from "./errors.mjs";
 import { normalizeRelativePath } from "./path-policy.mjs";
 
-export const PACKAGE_VERSION = "1.9.1";
+export const PACKAGE_VERSION = "1.10.0";
 export const EXCHANGE_PROTOCOL_VERSION = 9;
 export const ACTION_PLAN_SCHEMA_VERSION = 2;
 export const REVIEW_BUNDLE_SCHEMA_VERSION = 2;
-export const CAPABILITIES_SCHEMA_VERSION = 9;
+export const CAPABILITIES_SCHEMA_VERSION = 11;
 
 export const ACTION_KINDS = Object.freeze([
   "accept-source-change",
@@ -27,6 +27,7 @@ export const COMMANDS = Object.freeze([
   "index-context", "instructions", "publish-entry", "remove-entry", "review-source", "revise", "setup", "stage-context", "status", "sync",
   "upgrade-apply", "upgrade-check", "upgrade-plan",
   "reconcile-truth",
+  "project-brief", "task-handoff",
 ]);
 
 const ACTION_KIND_SET = new Set(ACTION_KINDS);

package/src/project-context/migration-manifest.mjs

@@ -103,7 +103,7 @@ export function validateMigrationManifest(input) {
   ]), "migration manifest");
   if (manifest.schemaVersion !== MIGRATION_MANIFEST_SCHEMA_VERSION) invalid("migration manifest schemaVersion must be 2");
   exactKeys(manifest.package, new Set(["name", "version"]), "migration manifest package");
-  if (manifest.package.name !== "frontend-project-context" || manifest.package.version !== "1.9.1") invalid("migration manifest package does not match this runtime");
+  if (manifest.package.name !== "frontend-project-context" || manifest.package.version !== "1.10.0") invalid("migration manifest package does not match this runtime");
   versions(manifest.upgradeFrom, "upgradeFrom");
   if (manifest.upgradeFrom.length === 0) invalid("upgradeFrom must not be empty");
   exactKeys(manifest.stores, new Set(["contract", "projectionLock", "proposal", "sourceLock"]), "stores");

package/src/project-context/path-policy.mjs

@@ -134,6 +134,19 @@ export async function resolveWritableInside(root, relativePath, options = {}) {
   return { normalized, absolute };
 }
 
+// Context can name a file that has not been created yet. Validate the nearest
+// existing parent as well as existing targets, without creating any directory.
+export async function inspectContextTarget(root, relativePath) {
+  try {
+    await resolveExistingInside(root, relativePath, { allowRoot: true, label: "context target" });
+    return "existing";
+  } catch (error) {
+    if (error?.code !== "source-missing") throw error;
+    await resolveWritableInside(root, relativePath, { allowRoot: true, label: "context target" });
+    return "prospective-or-deleted";
+  }
+}
+
 export function assertProjectionPath(target, normalized) {
   if (target === "agents") {
     if (path.posix.basename(normalized) !== "AGENTS.md") {

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

@@ -1,5 +1,4 @@
 import { canonicalJson, digestJson } from "./canonical-json.mjs";
-import { selectAdaptiveItems } from "./adaptive-context.mjs";
 import { blockingContextFindings, checkProject } from "./checker.mjs";
 import { ProjectContextError, fail } from "./errors.mjs";
 import { readJsonFile } from "./io.mjs";
@@ -92,18 +91,10 @@ function normalizedReceipts(receiptInputs, plan) {
   return byStage;
 }
 
-function selectedItems(contract, targetPaths, findings, adaptiveText) {
+function selectedItems(contract, targetPaths, findings) {
   const byId = new Map();
-  if (adaptiveText !== undefined) {
-    const adaptiveFindings = [];
-    const selection = selectAdaptiveItems(contract, null, {
-      task: { text: adaptiveText, topics: [], paths: targetPaths, changedPaths: [], itemIds: [] },
-      level: "initial",
-    }, { findings: adaptiveFindings });
-    findings.push(...adaptiveFindings);
-    for (const item of selection.selected) byId.set(item.id, item);
-  }
-  if (adaptiveText === undefined) {
+  // Schema-1 plans have no adaptive delivery/expansion contract. Preserve their
+  // complete scoped context; the existing budget gate blocks oversized bundles.
   for (const targetPath of targetPaths) {
     try {
       for (const item of effectiveItems(contract.items, targetPath)) byId.set(item.id, item);
@@ -113,7 +104,6 @@ function selectedItems(contract, targetPaths, findings, adaptiveText) {
       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,
@@ -217,7 +207,7 @@ async function buildStageContextBundleCore(root, project, plan, options, receipt
     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, `${plan.task.goal}\n${stage.objective}`);
+  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" })),

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

@@ -0,0 +1,185 @@
+import { digestJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+
+export const TASK_RECORD_SCHEMA_VERSION = 1;
+export const TASK_HANDOFF_INPUT_SCHEMA_VERSION = 1;
+export const TASK_HANDOFF_RESULT_SCHEMA_VERSION = 1;
+export const TASK_DIRECTORY = ".project-context-tasks";
+const ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const INTENTS = ["investigate", "design", "implement"];
+
+function invalid(message) { fail("task-handoff-schema-invalid", message); }
+function object(value, label, allowed, required = allowed) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(`${label} must be an object`);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) invalid(`${label}.${key} is unknown`);
+  for (const key of required) if (!Object.hasOwn(value, key)) invalid(`${label}.${key} is required`);
+  return value;
+}
+function string(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) invalid(`${label} must be a non-empty string`);
+  return value;
+}
+function choice(value, choices, label) {
+  if (!choices.includes(value)) invalid(`${label} is invalid`);
+  return value;
+}
+function array(value, label) { if (!Array.isArray(value)) invalid(`${label} must be an array`); return value; }
+function id(value, label) {
+  if (typeof value !== "string" || value.length > 64 || !ID.test(value)) invalid(`${label} is invalid`);
+  return value;
+}
+function digest(value, label) { if (typeof value !== "string" || !DIGEST.test(value)) invalid(`${label} is invalid`); return value; }
+function paths(values, label) {
+  const normalized = array(values, label).map((value) => normalizeRelativePath(value, { label }));
+  if (new Set(normalized).size !== normalized.length) invalid(`${label} contains duplicate paths`);
+  return normalized.sort();
+}
+function consumedTargets(values, label) {
+  const result = array(values, label).map((entry) => {
+    object(entry, label, ["path", "digest"]);
+    return { path: normalizeRelativePath(entry.path, { label }), digest: digest(entry.digest, `${label}.digest`) };
+  });
+  if (new Set(result.map((entry) => entry.path)).size !== result.length) invalid(`${label} contains duplicate paths`);
+  return result;
+}
+function applies(value, label) {
+  const result = array(value, label).map((item) => choice(item, INTENTS, label));
+  if (result.length === 0 || new Set(result).size !== result.length) invalid(`${label} must be non-empty and unique`);
+  return result.sort();
+}
+function uniqueIds(values, label) {
+  const ids = values.map((value) => value.id);
+  if (new Set(ids).size !== ids.length) invalid(`${label} contains duplicate IDs`);
+}
+function taskPath(taskId) { return `${TASK_DIRECTORY}/${taskId}.json`; }
+export { taskPath };
+
+export function normalizeTaskRecordPaths(record) {
+  const value = structuredClone(record);
+  value.scope.readPaths = paths(value.scope.readPaths, "readPaths");
+  for (const entry of value.scope.writeTargets) entry.path = normalizeRelativePath(entry.path);
+  for (const entry of value.evidence) if (entry.kind === "local") entry.path = normalizeRelativePath(entry.path);
+  for (const entry of value.progress.implementation) entry.path = normalizeRelativePath(entry.path);
+  return value;
+}
+
+export function validateTaskRecord(input) {
+  const value = object(input, "record", ["schemaVersion", "kind", "projectId", "taskId", "title", "revision", "previousDigest", "origin", "lifecycle", "scope", "requirements", "evidence", "decisions", "progress"]);
+  if (value.schemaVersion !== TASK_RECORD_SCHEMA_VERSION || value.kind !== "task-context-record") invalid("record identity is invalid");
+  string(value.projectId, "projectId"); id(value.taskId, "taskId"); string(value.title, "title");
+  if (!Number.isSafeInteger(value.revision) || value.revision < 1) invalid("revision must be a positive integer");
+  if (value.revision === 1 ? value.previousDigest !== null : !DIGEST.test(value.previousDigest ?? "")) invalid("previousDigest does not match revision");
+  choice(value.lifecycle, ["active", "completed", "cancelled"], "lifecycle");
+  return validateTaskContent(value);
+}
+
+// Shared content validation for records and delivered task snapshots.
+export function validateTaskContent(value) {
+  object(value.origin, "origin", ["text", "reference"], ["text"]);
+  string(value.origin.text, "origin.text");
+  if (value.origin.reference !== undefined) string(value.origin.reference, "origin.reference");
+  object(value.scope, "scope", ["readPaths", "writeTargets", "workspaceLabel"], ["readPaths", "writeTargets"]);
+  paths(value.scope.readPaths, "readPaths");
+  if (value.scope.workspaceLabel !== undefined) string(value.scope.workspaceLabel, "workspaceLabel");
+  const writes = array(value.scope.writeTargets, "writeTargets");
+  for (const entry of writes) {
+    object(entry, "writeTarget", ["path", "operation"]);
+    normalizeRelativePath(entry.path, { label: "write target" });
+    choice(entry.operation, ["create", "modify", "delete"], "write operation");
+  }
+  if (new Set(writes.map((entry) => normalizeRelativePath(entry.path))).size !== writes.length) invalid("writeTargets contains duplicate paths");
+  const evidence = array(value.evidence, "evidence");
+  for (const entry of evidence) {
+    object(entry, "evidence", ["id", "purpose", "kind", "path", "text", "reference", "digest", "identity"], ["id", "purpose", "kind", "digest", "identity"]);
+    id(entry.id, "evidence.id"); choice(entry.purpose, ["requirement", "design", "decision", "implementation", "reference"], "evidence.purpose");
+    choice(entry.kind, ["local", "inline", "external"], "evidence.kind"); digest(entry.digest, "evidence.digest");
+    choice(entry.identity, ["local-verified", "user-statement", "host-asserted"], "evidence.identity");
+    if (entry.kind === "local") {
+      if (entry.path === undefined || entry.text !== undefined || entry.reference !== undefined || entry.identity !== "local-verified") invalid("local evidence requires path and local-verified identity");
+      normalizeRelativePath(entry.path, { label: "evidence path" });
+    } else if (entry.kind === "inline") {
+      if (entry.text === undefined || entry.path !== undefined || entry.reference !== undefined || entry.identity !== "user-statement") invalid("inline evidence requires user-statement text");
+      string(entry.text, "evidence.text");
+      if (digestJson(entry.text) !== entry.digest) invalid("inline evidence digest mismatch");
+    } else {
+      if (entry.reference === undefined || entry.text === undefined || entry.path !== undefined || entry.identity !== "host-asserted") invalid("external evidence requires a reference and transferable text");
+      string(entry.reference, "evidence.reference"); string(entry.text, "evidence.text");
+      if (digestJson(entry.text) !== entry.digest) invalid("external evidence digest mismatch");
+    }
+  }
+  uniqueIds(evidence, "evidence");
+  const evidenceIds = new Set(evidence.map((entry) => entry.id));
+  const requirements = array(value.requirements, "requirements");
+  for (const entry of requirements) {
+    object(entry, "requirement", ["id", "text", "source", "appliesTo", "blocking", "evidenceIds"]);
+    id(entry.id, "requirement.id"); string(entry.text, "requirement.text"); string(entry.source, "requirement.source");
+    applies(entry.appliesTo, "requirement.appliesTo");
+    if (typeof entry.blocking !== "boolean") invalid("requirement.blocking must be boolean");
+    const refs = array(entry.evidenceIds, "requirement.evidenceIds").map((ref) => id(ref, "requirement.evidenceId"));
+    if (new Set(refs).size !== refs.length) invalid("requirement.evidenceIds duplicate");
+    refs.forEach((ref) => { if (!evidenceIds.has(ref)) invalid(`unknown evidence: ${ref}`); });
+  }
+  uniqueIds(requirements, "requirements");
+  const decisions = array(value.decisions, "decisions");
+  for (const entry of decisions) {
+    object(entry, "decision", ["id", "question", "appliesTo", "blocking", "status", "value", "evidenceIds"], ["id", "question", "appliesTo", "blocking", "status", "evidenceIds"]);
+    id(entry.id, "decision.id"); string(entry.question, "decision.question"); applies(entry.appliesTo, "decision.appliesTo");
+    if (typeof entry.blocking !== "boolean") invalid("decision.blocking must be boolean");
+    choice(entry.status, ["open", "confirmed"], "decision.status");
+    const decisionRefs = array(entry.evidenceIds, "decision.evidenceIds");
+    if (entry.status === "confirmed" ? typeof entry.value !== "string" || !entry.value.trim() || decisionRefs.length === 0 : entry.value !== undefined) invalid("decision value or evidence is invalid");
+    if (new Set(decisionRefs).size !== decisionRefs.length) invalid("decision.evidenceIds duplicate");
+    decisionRefs.forEach((ref) => { id(ref, "decision.evidenceId"); if (!evidenceIds.has(ref)) invalid(`unknown evidence: ${ref}`); });
+    if (entry.status === "confirmed" && !decisionRefs.some((ref) => evidence.find((source) => source.id === ref)?.identity !== "host-asserted")) invalid("confirmed decision needs user or locally verified evidence");
+  }
+  uniqueIds(decisions, "decisions");
+  object(value.progress, "progress", ["completed", "remaining", "implementation", "nextAction"]);
+  for (const key of ["completed", "remaining"]) array(value.progress[key], `progress.${key}`).forEach((item) => string(item, `progress.${key} item`));
+  const implementation = array(value.progress.implementation, "progress.implementation");
+  for (const entry of implementation) {
+    object(entry, "implementation progress", ["path", "operation", "status", "digest"]);
+    normalizeRelativePath(entry.path, { label: "implementation progress path" });
+    choice(entry.operation, ["create", "modify", "delete"], "implementation progress operation");
+    choice(entry.status, ["completed"], "implementation progress status");
+    digest(entry.digest, "implementation progress digest");
+    if (!writes.some((target) => normalizeRelativePath(target.path) === normalizeRelativePath(entry.path) && target.operation === entry.operation)) invalid("implementation progress has no matching write target");
+  }
+  if (new Set(implementation.map((entry) => normalizeRelativePath(entry.path))).size !== implementation.length) invalid("implementation progress contains duplicate paths");
+  string(value.progress.nextAction, "progress.nextAction");
+  return value;
+}
+
+export function validateHandoffInput(input) {
+  const value = structuredClone(object(input, "input", ["schemaVersion", "kind", "recordPath", "record", "intent", "consumerRunId", "consumption"], ["schemaVersion", "kind", "intent", "consumerRunId"]));
+  if (value.schemaVersion !== TASK_HANDOFF_INPUT_SCHEMA_VERSION || value.kind !== "task-handoff-input") invalid("handoff input identity is invalid");
+  if ((value.recordPath === undefined) === (value.record === undefined)) invalid("exactly one of recordPath and record is required");
+  if (value.recordPath !== undefined) {
+    const normalized = normalizeRelativePath(value.recordPath, { label: "record path" });
+    const taskId = normalized.startsWith(`${TASK_DIRECTORY}/`) && normalized.endsWith(".json") ? normalized.slice(TASK_DIRECTORY.length + 1, -5) : "";
+    if (!ID.test(taskId) || normalized !== taskPath(taskId)) invalid("recordPath must be a top-level task record");
+  } else validateTaskRecord(value.record);
+  choice(value.intent, INTENTS, "intent"); string(value.consumerRunId, "consumerRunId");
+  if (value.consumption !== undefined) {
+    const c = object(value.consumption, "consumption", ["contextBundleDigest", "taskId", "requirementsDigest", "consumerRunId", "readTargets", "evidenceIds", "conditional"], ["contextBundleDigest", "consumerRunId", "readTargets", "evidenceIds", "conditional"]);
+    digest(c.contextBundleDigest, "consumption.contextBundleDigest");
+    if (c.taskId !== undefined) id(c.taskId, "consumption.taskId");
+    if (c.requirementsDigest !== undefined) digest(c.requirementsDigest, "consumption.requirementsDigest");
+    if (c.consumerRunId !== value.consumerRunId) invalid("consumption consumerRunId mismatch");
+    c.readTargets = consumedTargets(c.readTargets, "consumption.readTargets");
+    const ids = array(c.evidenceIds, "consumption.evidenceIds").map((x) => id(x, "consumption.evidenceId"));
+    if (new Set(ids).size !== ids.length) invalid("consumption.evidenceIds duplicate");
+    const conditional = array(c.conditional, "consumption.conditional");
+    for (const entry of conditional) {
+      object(entry, "conditional", ["path", "decision", "reason", "digest"], ["path", "decision", "reason"]);
+      entry.path = normalizeRelativePath(entry.path, { label: "conditional path" });
+      choice(entry.decision, ["read", "not-applicable"], "conditional.decision");
+      string(entry.reason, "conditional.reason");
+      if (entry.decision === "read") digest(entry.digest, "conditional.digest");
+      else if (entry.digest !== undefined) invalid("not-applicable conditional cannot claim a digest");
+    }
+    if (new Set(conditional.map((x) => x.path)).size !== conditional.length) invalid("conditional paths duplicate");
+  }
+  return value;
+}