frontend-project-context 1.9.1 → 1.10.0

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

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

@@ -0,0 +1,135 @@
+import { canonicalJson, prettyCanonicalJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { validateWorkView } from "./work-view-schema.mjs";
+
+export const WORK_VIEW_MAX_BYTES = 1024 * 1024;
+const priority = { policy: 0, "validation-description": 1, fact: 2, reference: 3 };
+const intentNames = { investigate: "调查", design: "设计", implement: "实施" };
+const ranked = (items) => [...items].sort((a, b) => priority[a.kind] - priority[b.kind] || a.id.localeCompare(b.id));
+const excerpt = (value, limit = 240) => {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  return text.length <= limit ? text : `${text.slice(0, limit)}…（预览省略，须消费完整内容）`;
+};
+const progress = (record) => record ? { revision: record.revision, identity: "host-reported", ...structuredClone(record.progress) } : null;
+
+function constraints(items) {
+  return ranked(items).slice(0, 5).map((x) => ({ text: excerpt(`${x.statement}；内容：${JSON.stringify(x.value)}`), itemIds: [x.id], scope: x.scope }));
+}
+
+function issue(gap, record) {
+  const object = gap.path ?? gap.evidenceId ?? gap.requirementId ?? gap.decisionId ?? gap.id;
+  const descriptions = {
+    "required-not-read": ["Host", `还需读取 ${object} 并核对当前内容。`, "读取该文件后提交本次消费声明。"],
+    "context-not-consumed": ["Host", "当前 Context 尚未提交本次消费声明。", "实际阅读 required、判断 conditional，并核对任务证据后复查。"],
+    "requirements-not-consumed": ["Host", "声明没有绑定当前需求与依据。", "核对最新需求摘要并重新消费；不要求用户重述未变需求。"],
+    "consumption-task-mismatch": ["Host", "消费声明不属于当前任务。", "使用当前任务身份重新消费。"],
+    "evidence-missing": ["Host", `任务依据 ${object} 缺失。`, "在授权范围内定位具体依据；无法找到时报告缺口。"],
+    "evidence-changed": ["Host", `任务依据 ${object} 已变化。`, "读取并比较最新内容；必要的业务决定变化才请人确认。"],
+    "decision-open": ["用户", record?.decisions.find((x) => x.id === gap.decisionId)?.question ?? `决定 ${object} 尚未确认。`, "回答该具体问题；Host 不推断确认值。"],
+    "read-target-needs-file-scope": ["Host", `${object} 是目录，不能作为已读文件。`, "在 targetRoot 内收窄到实际文件并重新交接。"],
+    "target-path-not-yet-known": ["Host", "目标路径尚未锁定。", "消费项目范围 Context，在 targetRoot 内有限定位，再提交完整最小文件集合。"],
+    "project-needs-governance": ["维护者", "项目来源、批准或入口需要维护，当前交接保持阻断。", "运行 sync，审查并处理精确维护项，恢复 clean 后继续。"],
+    "work-view-budget-exceeded": ["Host", "工作交付超过上限，完整内容未交付。", "收窄具体目标或证据；概览枚举过大时提供明确 taskId。无新事实不重复重试。"],
+  };
+  const [actor, explanation, nextStep] = descriptions[gap.code] ?? ["Host", `${gap.code}：${object}`, "核对该对象和原始缺口；不能忽略后开工。"];
+  return { code: gap.code, object, explanation, actor, nextStep };
+}
+
+function presentation(base, context, record) {
+  const items = context?.items ?? [];
+  const issues = (base.gaps ?? base.findingCodes?.map((code) => ({ id: code, code })) ?? []).map((x) => issue(x, record));
+  const active = base.tasks?.filter((x) => x.lifecycle === "active") ?? [];
+  const questions = base.questions?.filter((x) => x.blockingNow).map((x) => ({ decisionId: x.id, question: x.question })) ?? [];
+  const basis = record ? [
+    ...record.requirements.map((x) => ({ text: excerpt(x.text), requirementIds: [x.id], evidenceIds: x.evidenceIds })),
+    ...record.decisions.filter((x) => x.status === "confirmed").map((x) => ({ text: excerpt(`${x.question}：${x.value}`), decisionIds: [x.id], evidenceIds: x.evidenceIds })),
+  ] : [];
+  let nextStep;
+  if (base.kind === "project-brief") {
+    nextStep = base.connection === "not-connected" ? "Host 先读取包内 instructions，按唯一初始化指引接入。" : base.connection !== "available" ? "维护者按项目 findings 处理治理或入口问题。" : active.length ? "直接点名任务标题继续，或描述新需求；有歧义时只核对一次选择。" : "直接描述要改的现象或功能，给出现有设计，或请求只读盘点。";
+  } else {
+    nextStep = base.gate.status === "not-applicable" ? "该任务已结束；可查看历史，不自动恢复实施。" : base.gate.status === "hold" ? (issues[0]?.nextStep ?? base.gate.instruction) : `Host 核对当前用户授权后继续${intentNames[base.intent]}；门禁不授予权限。`;
+  }
+  return {
+    headline: record ? `任务「${excerpt(base.taskIdentity.title)}」：当前${intentNames[base.intent]}；${base.gate.status === "hold" ? "需处理缺口" : base.gate.status === "not-applicable" ? "已结束" : "当前上下文就绪"}。` : `项目「${excerpt(base.project?.name ?? "未接入")}」：${base.connection === "available" ? "规则可用，目前没有选定开发任务" : "需要接入或维护"}。`,
+    constraints: constraints(items), remainingConstraints: Math.max(0, items.length - 5),
+    basis: basis.slice(0, 3), remainingBasis: Math.max(0, basis.length - 3),
+    progress: progress(record), issues, questions, nextStep,
+  };
+}
+
+function measure(value) {
+  for (let i = 0; i < 8; i += 1) {
+    const bytes = Buffer.byteLength(prettyCanonicalJson(value));
+    if (bytes === value.delivery.bytes) return bytes;
+    value.delivery.bytes = bytes;
+  }
+  fail("work-view-budget-exceeded", "cannot stabilize output byte count", { exitCode: 1 });
+}
+
+export function finalizeWorkView(value) {
+  value.delivery.bytes = 0;
+  if (measure(value) > WORK_VIEW_MAX_BYTES) {
+    const gap = { id: "delivery:budget", code: "work-view-budget-exceeded" };
+    value.context = null;
+    value.delivery = { status: "withheld", reasonCodes: [gap.code], bytes: 0, maxBytes: WORK_VIEW_MAX_BYTES };
+    if (value.kind === "task-handoff-result") {
+      value.taskSnapshot = null;
+      value.gaps = [gap]; value.questions = []; value.itemIds = []; value.scopeCoverage = [];
+      value.requiredTargets = []; value.conditionalTargets = []; value.evidenceResults = [];
+      if (value.taskStatus !== "inactive" && value.taskStatus !== "blocked") value.taskStatus = "needs-evidence";
+      value.gate = { ...value.gate, status: value.taskStatus === "inactive" ? "not-applicable" : "hold", reasonIds: [gap.id], instruction: "完整内容未交付，收窄目标后重新交接。" };
+      value.nextAction = "narrow-work-view-targets";
+    } else {
+      value.tasks = []; value.overview = { items: [], scopeSummary: [], limitations: [gap.code] };
+      value.findingCodes = [...new Set([...value.findingCodes, gap.code])]; value.nextAction = "provide-exact-task-id-or-narrow-context";
+    }
+    value.presentation = { headline: "完整工作内容未交付，当前不能据此开始任务。", constraints: [], remainingConstraints: 0, basis: [], remainingBasis: 0, progress: null, issues: [issue(gap)], questions: [], nextStep: issue(gap).nextStep };
+    if (measure(value) > WORK_VIEW_MAX_BYTES) fail("work-view-budget-exceeded", "metadata also exceeds output budget; provide a smaller explicit task record", { exitCode: 1 });
+  }
+  return validateWorkView(value);
+}
+
+export function taskWorkView(base, context, record) {
+  const evidenceMap = new Map(base.evidenceResults.map((x) => [x.id, x.status]));
+  const taskSnapshot = record ? {
+    origin: structuredClone(record.origin), scope: structuredClone(record.scope),
+    requirements: structuredClone(record.requirements), decisions: structuredClone(record.decisions),
+    evidence: record.evidence.map((x) => ({ ...structuredClone(x), status: evidenceMap.get(x.id) ?? "not-checked" })),
+    progress: progress(record),
+  } : null;
+  return finalizeWorkView({ ...base, schemaVersion: 2, context, taskSnapshot, presentation: presentation(base, context, record), delivery: { status: context ? "ready" : "withheld", reasonCodes: context ? [] : base.gaps.map((x) => x.code), bytes: 0, maxBytes: WORK_VIEW_MAX_BYTES } });
+}
+
+export function projectWorkView(base, context, items) {
+  const scopeMap = new Map();
+  for (const x of items) {
+    const key = canonicalJson(x.scope);
+    if (!scopeMap.has(key)) scopeMap.set(key, { scope: structuredClone(x.scope), items: 0 });
+    scopeMap.get(key).items += 1;
+  }
+  const cards = ranked(items).slice(0, 5).map((x) => ({ id: x.id, kind: x.kind, subject: x.subject, statement: x.statement, value: structuredClone(x.value), scope: structuredClone(x.scope), sourceIds: [...x.sources].sort() }));
+  const limitations = context ? [...new Set(context.gaps.map((x) => x.code).filter((x) => x !== "target-path-not-yet-known"))] : [...base.findingCodes];
+  return finalizeWorkView({ ...base, schemaVersion: 2, context, overview: { items: cards, scopeSummary: [...scopeMap.values()].sort((a, b) => canonicalJson(a.scope).localeCompare(canonicalJson(b.scope))), limitations }, presentation: presentation(base, context), delivery: { status: context ? "ready" : "withheld", reasonCodes: context ? [] : base.findingCodes, bytes: 0, maxBytes: WORK_VIEW_MAX_BYTES } });
+}
+
+export function renderWorkView(value) {
+  const p = value.presentation;
+  const lines = [p.headline];
+  if (value.kind !== "project-brief" && p.constraints.length) lines.push("本次可追溯规则：", ...p.constraints.map((x) => `- ${x.text}`));
+  if (value.kind !== "project-brief" && p.remainingConstraints) lines.push(`还有 ${p.remainingConstraints} 条，请消费完整 Context。`);
+  if (p.basis.length) lines.push("当前依据：", ...p.basis.map((x) => `- ${x.text}`));
+  if (p.remainingBasis) lines.push(`还有 ${p.remainingBasis} 条依据，请查看完整 taskSnapshot。`);
+  if (p.progress) lines.push("进度（Host 记录）：", ...p.progress.completed.map((x) => `- 已完成：${excerpt(x)}`), ...p.progress.remaining.map((x) => `- 剩余：${excerpt(x)}`));
+  if (value.kind === "project-brief") {
+    if (value.overview.items.length) lines.push("已批准知识预览（按声明范围适用）：", ...value.overview.items.map((x) => `- [${x.scope.kind}${x.scope.path ? `：${x.scope.path}` : ""}] ${excerpt(`${x.statement}；内容：${JSON.stringify(x.value)}`)}`));
+    if (value.overview.scopeSummary.length) lines.push("已声明范围：", ...value.overview.scopeSummary.map((x) => `- ${x.scope.kind}${x.scope.path ? `：${x.scope.path}` : ""}，${x.items} 条；仅说明注册范围。`));
+    const active = value.tasks.filter((x) => x.lifecycle === "active");
+    if (active.length) lines.push("活动任务：", ...active.map((x) => `- ${excerpt(x.title)} (${x.taskId})；下一步：${excerpt(x.progressSummary.nextAction)}`));
+    if (value.overview.limitations.length) lines.push(`覆盖提示：${value.overview.limitations.join("、")}；未声明业务语义完整。`);
+  }
+  if (p.issues.length) lines.push("当前缺口：", ...p.issues.map((x) => `- ${x.actor}：${excerpt(x.explanation)}`));
+  if (p.questions.length) lines.push("需要决定：", ...p.questions.map((x) => `- ${excerpt(x.question)}`));
+  lines.push(`下一步：${p.nextStep}`);
+  return `${lines.join("\n")}\n`;
+}