frontend-project-context 1.8.0 → 1.10.0

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;
+}

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

@@ -0,0 +1,259 @@
+import { lstat, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { digestJson, sha256 } from "./canonical-json.mjs";
+import { buildContextBundle } from "./context-bundle.mjs";
+import { ProjectContextError, fail } from "./errors.mjs";
+import { inspectContextTarget, normalizeRelativePath, resolveExistingInside } from "./path-policy.mjs";
+import { loadProject } from "./project-store.mjs";
+import { buildProjectStatus } from "./project-status.mjs";
+import { PERMANENT_BOUNDARIES } from "./capabilities.mjs";
+import { TASK_DIRECTORY, TASK_HANDOFF_RESULT_SCHEMA_VERSION, normalizeTaskRecordPaths, validateHandoffInput, validateTaskRecord, taskPath } from "./task-handoff-schema.mjs";
+import { projectWorkView, taskWorkView } from "./work-view.mjs";
+import { validateProjectBrief } from "./work-view-schema.mjs";
+
+const MAX_RECORD = 256 * 1024;
+const MAX_INPUT = 512 * 1024;
+const MAX_TASKS = 100;
+const ordered = (values) => [...new Set(values)].sort((a, b) => a.localeCompare(b));
+
+async function readBounded(file, max, label) {
+  const stat = await lstat(file);
+  if (!stat.isFile() || stat.size > max) fail("task-record-invalid", `${label} is not a bounded regular file`);
+  return readFile(file, "utf8");
+}
+
+async function parseBoundedJson(file, max, label) {
+  let content;
+  try { content = await readBounded(file, max, label); }
+  catch (error) {
+    if (error instanceof ProjectContextError) throw error;
+    fail("task-record-unavailable", `cannot read ${label}`, { details: { reason: error.code ?? "unavailable" } });
+  }
+  try { return JSON.parse(content); }
+  catch { fail("task-handoff-schema-invalid", `${label} is not JSON`); }
+}
+
+export async function loadTaskRecord(root, recordPath) {
+  const normalized = normalizeRelativePath(recordPath, { label: "record path" });
+  const taskId = normalized.startsWith(`${TASK_DIRECTORY}/`) && normalized.endsWith(".json") ? normalized.slice(TASK_DIRECTORY.length + 1, -5) : "";
+  if (!/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u.test(taskId) || normalized !== taskPath(taskId)) {
+    fail("task-handoff-schema-invalid", "recordPath must identify a top-level task record");
+  }
+  let stat;
+  try { stat = await lstat(path.join(root, normalized)); }
+  catch (error) {
+    if (error?.code === "ENOENT") fail("task-record-unavailable", "task record does not exist", { details: { path: normalized } });
+    throw error;
+  }
+  if (!stat.isFile()) fail("task-record-invalid", "task record must be a regular file");
+  const resolved = await resolveExistingInside(root, normalized);
+  const record = validateTaskRecord(await parseBoundedJson(resolved.absolute, MAX_RECORD, "task record"));
+  if (normalized !== taskPath(record.taskId)) fail("task-handoff-schema-invalid", "task record filename and taskId differ");
+  return record;
+}
+
+export async function buildProjectBrief(root, options = {}) {
+  const statusResult = await buildProjectStatus(root, PERMANENT_BOUNDARIES);
+  const status = statusResult.status;
+  const taskDir = path.join(root, TASK_DIRECTORY);
+  const tasks = [];
+  let entries;
+  try {
+    const stat = await lstat(taskDir);
+    if (!stat.isDirectory()) fail("task-record-invalid", "task directory must be a regular directory");
+    entries = await readdir(taskDir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") entries = [];
+    else throw error;
+  }
+  const candidates = entries.filter((entry) => entry.name.endsWith(".json")).sort((a, b) => a.name.localeCompare(b.name));
+  if (candidates.length > MAX_TASKS) fail("task-discovery-budget-exceeded", "too many task records; provide an exact taskId", { exitCode: 1, details: { count: candidates.length, limit: MAX_TASKS } });
+  for (const entry of candidates) {
+    if (!entry.isFile()) { tasks.push({ path: `${TASK_DIRECTORY}/${entry.name}`, status: "invalid-record" }); continue; }
+    try {
+      const record = await loadTaskRecord(root, `${TASK_DIRECTORY}/${entry.name}`);
+      tasks.push({ taskId: record.taskId, title: record.title, lifecycle: record.lifecycle, readPaths: record.scope.readPaths, writePaths: record.scope.writeTargets.map((x) => x.path), unresolvedDecisions: record.decisions.filter((x) => x.status === "open").length,
+        ...(options.view === "work" ? { progressSummary: { revision: record.revision, identity: "host-reported", ...record.progress } } : {}),
+      });
+    } catch (error) {
+      tasks.push({ path: `${TASK_DIRECTORY}/${entry.name}`, status: "invalid-record", reason: error.code ?? "invalid" });
+    }
+  }
+  const brief = {
+    schemaVersion: 1, kind: "project-brief",
+    project: status.project, package: status.package,
+    connection: status.initialization.state === "uninitialized" ? "not-connected" : status.health === "clean" && status.contractReadiness === "contract-ready" && status.entry.state === "current" ? "available" : "needs-governance",
+    projectHealth: status.health, contractReadiness: status.contractReadiness,
+    findingCodes: status.findingCodes, taskStatus: "none", tasks,
+    nextAction: status.initialization.state === "uninitialized" ? "read-initialization-instructions" :
+      status.health !== "clean" ? "resolve-project-findings" :
+      status.contractReadiness !== "contract-ready" ? "complete-onboarding" :
+      tasks.length === 0 ? "describe-task-or-provide-existing-design" : "select-task-by-id-or-describe-new-task",
+    authorityGranted: false,
+  };
+  if (options.view !== "work") return validateProjectBrief(brief);
+  let context = null;
+  let items = [];
+  if (brief.connection === "available") {
+    const project = await loadProject(root);
+    if (project.contractDigest !== status.snapshots.contract || project.sourcesLockDigest !== status.snapshots.sourcesLock || project.projectionsLockDigest !== status.snapshots.projectionsLock) fail("project-state-changed", "project snapshot changed while building the brief", { exitCode: 1 });
+    context = await buildContextBundle(root, project, { mode: "locate", task: "项目概览；没有选定开发任务" });
+    items = project.contract.items.filter((x) => x.status === "approved");
+  }
+  return projectWorkView(brief, context, items);
+}
+
+async function readInput(root, inputPath, stdinText) {
+  if (inputPath === "-") {
+    if (typeof stdinText !== "string" || Buffer.byteLength(stdinText) > MAX_INPUT) fail("task-handoff-schema-invalid", "stdin handoff input is absent or over budget");
+    try { return JSON.parse(stdinText); } catch { fail("task-handoff-schema-invalid", "stdin handoff input is not JSON"); }
+  }
+  const resolved = await resolveExistingInside(root, inputPath);
+  return parseBoundedJson(resolved.absolute, MAX_INPUT, "handoff input");
+}
+
+function relevant(entry, intent) { return entry.appliesTo.includes(intent); }
+function evidenceStatus(id, map) { return map.get(id)?.status ?? "missing"; }
+function sourceEvidenceIds(record, requirement) {
+  return requirement.evidenceIds.filter((id) => record.evidence.some((entry) => entry.id === id));
+}
+
+function currentEvidence(record, intent) {
+  const allRefs = new Set([...record.requirements, ...record.decisions].flatMap((entry) => entry.evidenceIds));
+  const currentRefs = new Set([...record.requirements, ...record.decisions].filter((entry) => relevant(entry, intent)).flatMap((entry) => entry.evidenceIds));
+  // Unassigned evidence is shared task context. Evidence assigned only to a
+  // different intent must not silently become a blocker for this one.
+  return record.evidence.filter((entry) => !allRefs.has(entry.id) || currentRefs.has(entry.id));
+}
+
+async function targetDigest(root, target) {
+  const resolved = await resolveExistingInside(root, target);
+  const stat = await lstat(resolved.absolute);
+  if (!stat.isFile()) fail("task-read-target-not-file", "task consumption needs an exact regular file; narrow directory targets before handoff", { details: { path: target }, exitCode: 2 });
+  return sha256(await readFile(resolved.absolute));
+}
+
+export async function buildTaskHandoff(root, inputPath, stdinText, options = {}) {
+  const input = validateHandoffInput(await readInput(root, inputPath, stdinText));
+  if (input.record && Buffer.byteLength(JSON.stringify(input.record)) > MAX_RECORD) fail("task-record-invalid", "inline task record exceeds 256 KiB");
+  const rawRecord = input.recordPath ? await loadTaskRecord(root, input.recordPath) : input.record;
+  const record = normalizeTaskRecordPaths(rawRecord);
+  const selectedRecord = { ...record, requirements: record.requirements.filter((x) => relevant(x, input.intent)), decisions: record.decisions.filter((x) => relevant(x, input.intent)), evidence: currentEvidence(record, input.intent) };
+  const status = (await buildProjectStatus(root, PERMANENT_BOUNDARIES)).status;
+  const project = status.initialization.state === "initialized" ? await loadProject(root) : null;
+  const base = {
+    schemaVersion: TASK_HANDOFF_RESULT_SCHEMA_VERSION, kind: "task-handoff-result",
+    taskIdentity: { projectId: record.projectId, taskId: record.taskId, title: record.title, lifecycle: record.lifecycle },
+    projectHealth: status.health, intent: input.intent, recordDigest: digestJson(rawRecord),
+    authorityGranted: false, semanticCompleteness: "not-claimed",
+  };
+  if (!project || status.health !== "clean" || status.contractReadiness !== "contract-ready" || project.contract.project.id !== record.projectId) {
+    const reason = !project ? "project-unavailable" : project.contract.project.id !== record.projectId ? "project-mismatch" : "project-needs-governance";
+    const blocked = { ...base, taskStatus: "blocked", gate: { mode: "instructional", currentAction: input.intent === "implement" ? "implementation" : "read-only", status: "hold", reasonIds: [reason], instruction: "先处理项目或任务身份问题。" }, contextBundleDigest: null, requirementsDigest: null, progressKey: digestJson([record.taskId, reason]), itemIds: [], scopeCoverage: [], requiredTargets: [], conditionalTargets: [], evidenceResults: [], gaps: [{ id: reason, code: reason }], questions: [], nextAction: "resolve-project-findings" };
+    return options.view === "work" ? taskWorkView(blocked, null, selectedRecord) : blocked;
+  }
+
+  const evidence = currentEvidence(record, input.intent);
+  const currentRequirements = record.requirements.filter((x) => relevant(x, input.intent));
+  const currentDecisions = record.decisions.filter((x) => relevant(x, input.intent));
+  const targetPaths = ordered([...record.scope.readPaths, ...record.scope.writeTargets.map((x) => x.path), ...evidence.filter((x) => x.kind === "local").map((x) => x.path)]);
+  const bundle = await buildContextBundle(root, project, { mode: targetPaths.length ? "targeted" : "locate", paths: targetPaths, task: record.origin.text });
+  const evidenceResults = [];
+  for (const entry of evidence) {
+    let state = "current";
+    if (entry.kind === "local") {
+      try {
+        state = await targetDigest(root, entry.path) === entry.digest ? "current" : "changed";
+      } catch (error) {
+        if (error?.code === "source-missing") state = "missing";
+        else throw error;
+      }
+    }
+    evidenceResults.push({ id: entry.id, status: state, identity: entry.identity });
+  }
+  const evidenceMap = new Map(evidenceResults.map((x) => [x.id, x]));
+  const gaps = [];
+  const add = (id, code, details = {}) => { if (!gaps.some((x) => x.id === id)) gaps.push({ id, code, ...details }); };
+  for (const gap of bundle.gaps) {
+    if (gap.code === "target-path-not-yet-known") continue;
+    if (gap.code === "project-scope-only" || gap.code === "registration-coverage-not-declared") continue;
+    add(`context:${gap.code}:${gap.path ?? "."}`, gap.code, { path: gap.path ?? null });
+  }
+  for (const entry of evidenceResults) {
+    if (entry.status !== "current" && record.evidence.find((x) => x.id === entry.id)?.purpose !== "implementation") add(`evidence:${entry.id}`, `evidence-${entry.status}`, { evidenceId: entry.id });
+  }
+  if (input.intent === "implement" && record.scope.writeTargets.length === 0) add("target:implementation-scope-empty", "implementation-scope-empty");
+  if (input.intent === "implement" && currentRequirements.length === 0) add("requirements:empty", "requirements-empty");
+  for (const entry of currentRequirements.filter((x) => x.blocking)) {
+    const refs = sourceEvidenceIds(record, entry);
+    if (refs.length === 0 || refs.every((id) => evidenceStatus(id, evidenceMap) !== "current")) add(`requirement:${entry.id}`, "requirement-evidence-missing", { requirementId: entry.id });
+  }
+  for (const entry of currentDecisions.filter((x) => x.blocking)) {
+    if (entry.status !== "confirmed" || entry.evidenceIds.some((id) => evidenceStatus(id, evidenceMap) !== "current")) add(`decision:${entry.id}`, "decision-open", { decisionId: entry.id });
+  }
+  for (const target of input.intent === "implement" ? record.scope.writeTargets : []) {
+    const actual = await inspectContextTarget(root, target.path);
+    const progress = record.progress.implementation.find((x) => x?.path === target.path && x?.operation === target.operation && x?.status === "completed");
+    if (target.operation === "create" && actual === "existing" && !progress) add(`target:${target.path}`, "create-target-exists", { path: target.path });
+    if (target.operation !== "create" && actual !== "existing" && !progress) add(`target:${target.path}`, "target-missing", { path: target.path });
+    if (progress && target.operation === "delete" && actual === "existing") add(`target:${target.path}`, "completed-delete-still-exists", { path: target.path });
+    if (progress && target.operation !== "delete") {
+      if (actual !== "existing") add(`target:${target.path}`, "completed-output-missing", { path: target.path });
+      else if (await targetDigest(root, target.path) !== progress.digest) add(`target:${target.path}`, "completed-output-changed", { path: target.path });
+    }
+  }
+  const requiredTargets = bundle.readTargets.filter((x) => x.role === "required" && !record.scope.writeTargets.some((target) => {
+    if (target.path !== x.path) return false;
+    const completed = record.progress.implementation.some((entry) => entry.path === target.path && entry.operation === target.operation && entry.status === "completed");
+    return (target.operation === "create" && !completed) || (target.operation === "delete" && completed);
+  })).map((x) => x.path);
+  const conditionalTargets = bundle.readTargets.filter((x) => x.role === "conditional").map((x) => x.path);
+  for (const target of requiredTargets) {
+    try {
+      const resolved = await resolveExistingInside(root, target);
+      const stat = await lstat(resolved.absolute);
+      if (!stat.isFile()) add(`read:${target}`, "read-target-needs-file-scope", { path: target });
+    } catch (error) { if (error?.code !== "source-missing") throw error; }
+  }
+  const requirementsDigest = digestJson({ projectId: record.projectId, taskId: record.taskId, intent: input.intent, requirements: currentRequirements, decisions: currentDecisions, scope: record.scope, evidence: evidence.filter((x) => x.purpose !== "implementation").map((x) => ({ id: x.id, digest: x.digest })), items: bundle.items.map((x) => ({ id: x.id, value: x.value })) });
+  if (input.consumption && input.consumption.taskId !== record.taskId) add("consumption:task", "consumption-task-mismatch");
+  if (input.consumption && input.consumption.requirementsDigest !== requirementsDigest) add("consumption:requirements", "requirements-not-consumed");
+  if (input.consumption?.contextBundleDigest !== bundle.bundleDigest) add("consumption:digest", "context-not-consumed");
+  if (input.consumption?.contextBundleDigest === bundle.bundleDigest) {
+    for (const target of requiredTargets) {
+      if (gaps.some((x) => x.id === `read:${target}` && x.code === "read-target-needs-file-scope")) continue;
+      const consumed = input.consumption.readTargets.find((x) => x.path === target);
+      if (!consumed) add(`read:${target}`, "required-not-read", { path: target });
+      else {
+        try {
+          if (await targetDigest(root, target) !== consumed.digest) add(`read:${target}`, "required-read-changed", { path: target });
+        } catch (error) { if (error?.code === "source-missing") add(`read:${target}`, "required-source-missing", { path: target }); else throw error; }
+      }
+    }
+    for (const target of conditionalTargets) {
+      const decision = input.consumption.conditional.find((x) => x.path === target);
+      if (!decision) add(`conditional:${target}`, "conditional-not-evaluated", { path: target });
+      else if (decision.decision === "read") {
+        try {
+          if (await targetDigest(root, target) !== decision.digest) add(`conditional:${target}`, "conditional-read-changed", { path: target });
+        } catch (error) { if (error?.code === "source-missing") add(`conditional:${target}`, "conditional-source-missing", { path: target }); else if (error?.code === "task-read-target-not-file") add(`conditional:${target}`, "read-target-needs-file-scope", { path: target }); else throw error; }
+      }
+    }
+    for (const entry of evidence.filter((x) => x.purpose !== "implementation")) if (!input.consumption.evidenceIds.includes(entry.id)) add(`consume-evidence:${entry.id}`, "evidence-not-consumed", { evidenceId: entry.id });
+  }
+  if (targetPaths.length === 0) add("target:unknown", "target-path-not-yet-known");
+  const hasDecision = gaps.some((x) => x.code === "decision-open");
+  const hasEvidence = gaps.some((x) => !["decision-open", "target-path-not-yet-known", "implementation-scope-empty"].includes(x.code));
+  const taskStatus = record.lifecycle !== "active" ? "inactive" : targetPaths.length === 0 || (input.intent === "implement" && record.scope.writeTargets.length === 0) ? "discovering" : hasEvidence ? "needs-evidence" : hasDecision ? "needs-decision" : input.intent === "implement" ? "ready-to-implement" : "ready-for-read-only";
+  const gateStatus = taskStatus === "inactive" ? "not-applicable" : taskStatus.startsWith("ready-") ? "proceed" : "hold";
+  const nextAction = taskStatus === "inactive" ? "select-active-task-or-explicitly-restore" : taskStatus === "discovering" ? "locate-target-paths" : gaps.some((x) => x.code === "read-target-needs-file-scope") ? "narrow-directory-targets-to-files" : hasEvidence ? "read-or-update-required-evidence" : hasDecision ? "resolve-listed-decisions" : input.intent === "implement" ? "check-current-user-authority-then-implement" : "complete-current-read-only-task";
+  const result = {
+    ...base, taskStatus,
+    gate: { mode: "instructional", currentAction: input.intent === "implement" ? "implementation" : "read-only", status: gateStatus, reasonIds: gaps.map((x) => x.id), instruction: gateStatus === "hold" ? "处理列出的缺口后重新交接；当前不要实施受阻的业务修改。" : gateStatus === "proceed" && input.intent === "implement" ? "先核对当前用户授权与范围，再执行实施。" : "按当前只读意图继续。" },
+    contextBundleDigest: bundle.bundleDigest, requirementsDigest,
+    progressKey: digestJson({ requirementsDigest, gaps: gaps.map((x) => x.id), nextAction, consumed: input.consumption ? [input.consumption.readTargets, input.consumption.evidenceIds, input.consumption.conditional] : null }),
+    itemIds: bundle.items.map((x) => x.id), scopeCoverage: bundle.targets.map((x) => ({ path: x.path, coverage: x.scopeCoverage })), requiredTargets, conditionalTargets, evidenceResults,
+    gaps, questions: record.decisions.filter((x) => x.status === "open").map((x) => ({ id: x.id, question: x.question, blockingNow: x.blocking && relevant(x, input.intent) })), nextAction,
+  };
+  return options.view === "work" ? taskWorkView(result, bundle, selectedRecord) : result;
+}

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

@@ -121,7 +121,7 @@ export function validateUpgradeAssessment(input) {
     stores: new Set(["contract", "projectionLock", "proposal", "sourceLock"]),
     renderers: new Set(["aiEntry", "projection"]),
     protocols: new Set([
-      "actionPlan", "adaptiveContextBundle", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
+      "actionPlan", "adaptiveContextBundle", "contextBundle", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
       "hostPromotionEvidence", "integrationReviewBundle", "reviewBundle", "routingIndex", "stageContextBundle", "stageReceipt",
       "taskContextPlan", "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
     ]),

package/src/project-context/upgrade.mjs

@@ -123,6 +123,7 @@ async function inspectUpgradeState(root, project) {
   const lockedSources = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
   for (const source of project.contract.sources) {
     if (sourceStatus(source) === "deprecated") continue;
+    if (source.kind === "human-decision" || source.kind === "external-reference") continue;
     const locked = lockedSources.get(source.id);
     if (!locked) findings.push({ code: "source-lock-missing", source: source.id });
     else if (source.digest !== undefined && source.digest !== locked) findings.push({ code: "source-lock-mismatch", source: source.id });

package/src/project-context/work-view-schema.mjs

@@ -0,0 +1,125 @@
+import { prettyCanonicalJson } from "./canonical-json.mjs";
+import { validateContextBundle } from "./context-bundle.mjs";
+import { validateTaskContent } from "./task-handoff-schema.mjs";
+import { fail } from "./errors.mjs";
+
+const briefKeys = ["schemaVersion", "kind", "project", "package", "connection", "projectHealth", "contractReadiness", "findingCodes", "taskStatus", "tasks", "nextAction", "authorityGranted"];
+const handoffKeys = ["schemaVersion", "kind", "taskIdentity", "projectHealth", "intent", "recordDigest", "authorityGranted", "semanticCompleteness", "taskStatus", "gate", "contextBundleDigest", "requirementsDigest", "progressKey", "itemIds", "scopeCoverage", "requiredTargets", "conditionalTargets", "evidenceResults", "gaps", "questions", "nextAction"];
+function invalid(message) { fail("work-view-schema-invalid", message); }
+function object(value, keys, label, optional = []) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(`${label} must be an object`);
+  for (const key of Object.keys(value)) if (!keys.includes(key) && !optional.includes(key)) invalid(`${label}.${key} is unknown`);
+  for (const key of keys) if (!Object.hasOwn(value, key)) invalid(`${label}.${key} is required`);
+}
+function string(value, label) { if (typeof value !== "string" || !value.length) invalid(`${label} must be a non-empty string`); }
+function array(value, label) { if (!Array.isArray(value)) invalid(`${label} must be an array`); return value; }
+function strings(value, label) { array(value, label).forEach((x) => string(x, label)); }
+function choice(value, values, label) { if (!values.includes(value)) invalid(`${label} is invalid`); }
+function integer(value, minimum, label) { if (!Number.isSafeInteger(value) || value < minimum) invalid(`${label} is invalid`); }
+function scope(value) {
+  if (!value || typeof value !== "object") invalid("scope must be an object");
+  choice(value.kind, ["project", "path-prefix", "file"], "scope.kind");
+  object(value, value.kind === "project" ? ["kind"] : ["kind", "path"], "scope");
+  if (value.kind !== "project") string(value.path, "scope.path");
+}
+function progress(value) {
+  if (value === null) return;
+  object(value, ["revision", "identity", "completed", "remaining", "implementation", "nextAction"], "progress");
+  integer(value.revision, 1, "progress.revision");
+  if (value.identity !== "host-reported") invalid("progress identity is not a runtime verification");
+  strings(value.completed, "progress.completed"); strings(value.remaining, "progress.remaining");
+  for (const x of array(value.implementation, "progress.implementation")) {
+    object(x, ["path", "operation", "status", "digest"], "implementation");
+    string(x.path, "implementation.path"); choice(x.operation, ["create", "modify", "delete"], "implementation.operation");
+    if (x.status !== "completed" || !/^sha256:[a-f0-9]{64}$/u.test(x.digest)) invalid("implementation progress is invalid");
+  }
+  string(value.nextAction, "progress.nextAction");
+}
+function briefBase(value) {
+  if (value.kind !== "project-brief" || value.taskStatus !== "none" || value.authorityGranted !== false) invalid("brief identity/authority is invalid");
+  for (const key of ["projectHealth", "contractReadiness", "nextAction"]) string(value[key], key);
+  choice(value.connection, ["available", "needs-governance", "not-connected"], "connection");
+  strings(value.findingCodes, "findingCodes");
+  for (const x of array(value.tasks, "tasks")) {
+    if (x.status === "invalid-record") { object(x, ["path", "status"], "task", ["reason"]); string(x.path, "task.path"); continue; }
+    object(x, ["taskId", "title", "lifecycle", "readPaths", "writePaths", "unresolvedDecisions", ...(value.schemaVersion === 2 ? ["progressSummary"] : [])], "task");
+    string(x.taskId, "taskId"); string(x.title, "title"); choice(x.lifecycle, ["active", "completed", "cancelled"], "lifecycle");
+    strings(x.readPaths, "readPaths"); strings(x.writePaths, "writePaths"); integer(x.unresolvedDecisions, 0, "unresolvedDecisions");
+    if (value.schemaVersion === 2) progress(x.progressSummary);
+  }
+}
+export function validateProjectBrief(value) {
+  if (value.schemaVersion === 2) return validateWorkView(value);
+  if (value.schemaVersion !== 1) invalid("brief version is unsupported");
+  object(value, briefKeys, "brief"); briefBase(value); return value;
+}
+
+export function validateWorkView(value) {
+  if (value.schemaVersion !== 2) invalid("work view version must be 2");
+  const isBrief = value.kind === "project-brief";
+  if (!isBrief && value.kind !== "task-handoff-result") invalid("work view kind is invalid");
+  object(value, [...(isBrief ? briefKeys : handoffKeys), "context", isBrief ? "overview" : "taskSnapshot", "presentation", "delivery"], "work");
+  if (value.authorityGranted !== false) invalid("work view cannot grant authority");
+  object(value.delivery, ["status", "reasonCodes", "bytes", "maxBytes"], "delivery");
+  choice(value.delivery.status, ["ready", "withheld"], "delivery.status"); strings(value.delivery.reasonCodes, "delivery.reasonCodes");
+  integer(value.delivery.bytes, 1, "delivery.bytes");
+  if (value.delivery.maxBytes !== 1048576 || value.delivery.bytes > value.delivery.maxBytes || value.delivery.bytes !== Buffer.byteLength(prettyCanonicalJson(value))) invalid("delivery byte budget/count is invalid");
+  if ((value.context !== null) !== (value.delivery.status === "ready")) invalid("delivery/context mismatch");
+  if (value.context !== null) validateContextBundle(value.context);
+  const p = value.presentation;
+  object(p, ["headline", "constraints", "remainingConstraints", "basis", "remainingBasis", "progress", "issues", "questions", "nextStep"], "presentation");
+  string(p.headline, "headline"); string(p.nextStep, "nextStep"); progress(p.progress);
+  integer(p.remainingConstraints, 0, "remainingConstraints"); integer(p.remainingBasis, 0, "remainingBasis");
+  const itemIds = new Set(value.context?.items.map((x) => x.id) ?? []);
+  if (array(p.constraints, "constraints").length > 5 || array(p.basis, "basis").length > 3) invalid("presentation preview exceeds limit");
+  for (const x of p.constraints) {
+    object(x, ["text", "itemIds", "scope"], "constraint"); string(x.text, "constraint.text"); strings(x.itemIds, "constraint.itemIds"); scope(x.scope);
+    if (!x.itemIds.length || x.itemIds.some((id) => !itemIds.has(id))) invalid("constraint is not bound to delivered Context");
+  }
+  for (const x of p.basis) { object(x, ["text", "evidenceIds"], "basis", ["requirementIds", "decisionIds"]); string(x.text, "basis.text"); strings(x.evidenceIds, "basis.evidenceIds"); for (const key of ["requirementIds", "decisionIds"]) if (x[key] !== undefined) strings(x[key], key); }
+  for (const x of array(p.issues, "issues")) { object(x, ["code", "object", "explanation", "actor", "nextStep"], "issue"); Object.values(x).forEach((v) => string(v, "issue")); }
+  for (const x of array(p.questions, "questions")) { object(x, ["decisionId", "question"], "question"); string(x.decisionId, "decisionId"); string(x.question, "question"); }
+  if (isBrief) {
+    briefBase(value);
+    object(value.overview, ["items", "scopeSummary", "limitations"], "overview");
+    strings(value.overview.limitations, "overview.limitations");
+    if (array(value.overview.items, "overview.items").length > 5) invalid("overview preview exceeds limit");
+    for (const x of value.overview.items) {
+      object(x, ["id", "kind", "subject", "statement", "value", "scope", "sourceIds"], "overview.item");
+      for (const key of ["id", "subject", "statement"]) string(x[key], key);
+      choice(x.kind, ["fact", "policy", "reference", "validation-description"], "item.kind"); scope(x.scope); strings(x.sourceIds, "sourceIds");
+    }
+    for (const x of array(value.overview.scopeSummary, "scopeSummary")) { object(x, ["scope", "items"], "scopeSummary"); scope(x.scope); integer(x.items, 1, "scopeSummary.items"); }
+    if (value.context && (value.context.mode !== "locate" || value.project?.id !== value.context.project.id)) invalid("brief Context scope/project mismatch");
+  } else {
+    if (value.semanticCompleteness !== "not-claimed") invalid("work view cannot claim semantic completeness");
+    choice(value.intent, ["investigate", "design", "implement"], "intent");
+    choice(value.taskStatus, ["blocked", "discovering", "needs-evidence", "needs-decision", "ready-for-read-only", "ready-to-implement", "inactive"], "taskStatus");
+    object(value.gate, ["mode", "currentAction", "status", "reasonIds", "instruction"], "gate");
+    choice(value.gate.currentAction, ["read-only", "implementation"], "gate.currentAction"); strings(value.gate.reasonIds, "gate.reasonIds"); string(value.gate.instruction, "gate.instruction");
+    if (value.gate.mode !== "instructional") invalid("gate must be instructional");
+    choice(value.gate.status, ["hold", "proceed", "not-applicable"], "gate.status");
+    if (value.context && (value.context.bundleDigest !== value.contextBundleDigest || value.taskIdentity.projectId !== value.context.project.id)) invalid("handoff Context digest/project mismatch");
+    if (value.delivery.status === "withheld" && value.gate.status === "proceed") invalid("withheld delivery cannot proceed");
+    if (value.taskSnapshot !== null) {
+      const t = value.taskSnapshot;
+      object(t, ["origin", "scope", "requirements", "decisions", "evidence", "progress"], "taskSnapshot"); progress(t.progress);
+      if (!t.progress) invalid("taskSnapshot needs progress");
+      array(t.evidence, "evidence");
+      const {revision, identity, ...contentProgress} = t.progress;
+      validateTaskContent({...t, progress: contentProgress, evidence: t.evidence.map(({status, ...x}) => {
+        choice(status, ["current", "changed", "missing", "not-checked"], "evidence.status"); return x;
+      })});
+      object(t.origin, ["text"], "origin", ["reference"]); string(t.origin.text, "origin.text");
+      object(t.scope, ["readPaths", "writeTargets"], "taskScope", ["workspaceLabel"]); strings(t.scope.readPaths, "scope.readPaths"); array(t.scope.writeTargets, "scope.writeTargets");
+      array(t.requirements, "requirements"); array(t.decisions, "decisions"); array(t.evidence, "evidence");
+      if ([...t.requirements, ...t.decisions].some((x) => !x.appliesTo.includes(value.intent))) invalid("taskSnapshot contains another intent");
+      const evidenceIds = new Set(t.evidence.map((x) => x.id));
+      if ([...t.requirements, ...t.decisions].some((x) => x.evidenceIds.some((id) => !evidenceIds.has(id)))) invalid("taskSnapshot evidence binding is incomplete");
+      if (p.basis.some((x) => x.evidenceIds.some((id) => !evidenceIds.has(id)) ||
+        x.requirementIds?.some((id) => !t.requirements.some((r) => r.id === id)) ||
+        x.decisionIds?.some((id) => !t.decisions.some((r) => r.id === id)))) invalid("presentation basis is unbound");
+    }
+  }
+  return value;
+}