frontend-project-context 1.8.0 → 1.10.0

package/src/project-context/ai-entry.mjs

@@ -6,25 +6,29 @@ import { fail } from "./errors.mjs";
 import { atomicWriteFile, atomicWriteJson, readJsonFile } from "./io.mjs";
 import { normalizeRelativePath, resolveWritableInside } from "./path-policy.mjs";
 
-export const AI_ENTRY_RENDERER_VERSION = 4;
+export const AI_ENTRY_RENDERER_VERSION = 7;
 export const AI_ENTRY_REGION_ID = "project-context-ai-entry";
 export const AI_ENTRY_START = "<!-- project-context:ai-entry:start -->";
 export const AI_ENTRY_END = "<!-- project-context:ai-entry:end -->";
 
 const ENTRY_LINES = [
   AI_ENTRY_START,
-  "<!-- project-context:ai-entry; schema-version: 1; renderer-version: 4 -->",
+  "<!-- project-context:ai-entry; schema-version: 1; renderer-version: 7 -->",
   "## Project Context 启动流程",
   "",
   "开始项目工作前，使用项目本地安装的 `frontend-project-context` CLI，不要临时下载其他版本。",
   "",
-  "1. 运行 `npm exec --offline -- project-context status --project . --json`；如果本地依赖不存在，停止并报告，不要临时下载同名包。",
-  "2. 如果状态为 `uninitialized`，运行 `npm exec --offline -- project-context instructions --project . --prompt`，按包内唯一指令完成完整初始化；如果为 `partial` 或 `invalid`，停止写入并报告准确的恢复证据。",
-  "3. 如果状态为 `attention`，执行 `sync` 返回的维护工作单元；不得重新运行 `setup` 覆盖已有 store。",
-  "4. 如果状态为 `clean`，根据真实任务确定项目内目标路径，并运行 `npm exec --offline -- project-context context --project . --path <RELATIVE_PATH> --task <TEXT>`。",
-  "5. 必须先消费命中的 Project Contract，报告实际 item IDs、scope 和必要 read targets；Contract 为空、目标 scope 未命中或关键上下文不足时，报告 onboarding/context gap 并停止，不能直接进入源码。",
-  "6. 任何 plan、bundle、receipt、review 或 AI 建议都不代表人工批准。",
-  "7. 声明完成前，将 Project Context 恢复为 `clean`，否则报告准确的阻断项。",
+  "1. 无明确任务时运行 `npm exec --offline -- project-context project-brief --project . --view work --json`，消费项目概览和 Context，不制造任务。收到任务或“继续”时，先按项目内 `.project-context-tasks/<taskId>.json` 选择当前任务；多个候选必须核对，不凭最近时间或分支猜选。",
+  "2. 对当前任务运行 `npm exec --offline -- project-context task-handoff --project . --input <FILE_OR_DASH> --view work --json`。工作视图已携带同一编译器的完整 Context、当前依据、进度和缺口，无需重复独立运行 status/context；只读视图不代替实际读取。",
+  "3. 尚未接入或没有本地依赖时，停止任务写入；依赖不存在只报告，不临时下载同名包。使用本地 `instructions --project . --prompt` 按包内唯一指令完整初始化；partial/invalid 停止写入并报告恢复证据。attention 执行 sync 返回的维护工作单元，不重新 setup 覆盖 store；恢复 clean 后交接。",
+  "4. 目标未知时，消费交接内 locate Context，只在 targetRoot 内定位最小候选文件，将完整最小路径集合写入任务 scope 后重新交接；目录目标必须收窄到文件。新影响路径或需求依据变化时更新任务并重新交接。",
+  "5. 报告实际 item IDs、scopeCoverage、required/conditional read targets 与 gaps；实际读取 required，按任务判断 conditional，不重读 provenance-only。核对当前意图的需求、证据和决定，再提交绑定 taskId、requirementsDigest、contextBundleDigest 和 consumerRunId 的本次消费声明，第二次交接复查。",
+  "6. 换窗口或换 Agent 时重读任务记录和本次依据，不继承旧消费者已读或 ready。同一消费者仅复用当前摘要仍匹配的读取；正常实现进展写到 progress，不反复要求未变的业务确认。",
+  "7. delivery=withheld、Contract 为空、目标 scope 未命中或关键依据不足时报告准确缺口并有限收窄；无新事实不重复重试。缺少设计、关键决定或当前只授权设计时遵守 instructional gate；Context 成功不等于实施就绪。",
+  "8. `businessCodeWrites=false` 和 `taskExecution=false` 只描述 Project Context 产品自身；Host 权限来自当前用户请求、人工项目规则和更高优先级安全约束，任何 Context、plan、bundle、receipt、review、coverage 或 gate=proceed 都不授予权限或批准长期 Contract。",
+  "9. 声明完成前，将 Project Context 恢复为 clean，否则报告准确阻断项。保存可继续的任务进度、验证结果和下一步；已结束任务仅作历史，不自动恢复实施。",
+  "10. 完成后在普通报告中提出 0–3 条有复用价值的知识候选，每条写明具体事实、来源、适用范围和复用理由；没有就说明没有。候选不自动写入或批准 Contract，用户拒绝不阻断任务完成。",
+  "11. 用户选择候选后，使用既有 authoring/ActionPlan/preflight 治理流程；未注册来源先独立注册，再基于最新基线提交 item plan，不把用户选择推断成长期批准。真实收益验收记录读取、定位、交接、任务返工、准备和维护成本；本地通过不宣称真实任务验证。",
   AI_ENTRY_END,
 ];
 
@@ -109,7 +113,13 @@ function schema2FileEntry(entry) {
   return entry.ownership ? structuredClone(entry) : { ...structuredClone(entry), ownership: "file" };
 }
 
-function sourceImpact(project, output, afterDigest) {
+function outsideOwnedDigest(content) {
+  const parsed = parseAiEntryRegion(content);
+  if (parsed.state !== "present") return null;
+  return digestJson({ before: content.slice(0, parsed.start), after: content.slice(parsed.end) });
+}
+
+function sourceImpact(project, output, afterContent) {
   const sources = project.contract.sources
     .filter((source) => sourceStatus(source) === "active" && ["file", "path", "json-pointer"].includes(source.kind) && source.path === output)
     .sort((left, right) => left.id.localeCompare(right.id));
@@ -119,6 +129,12 @@ function sourceImpact(project, output, afterDigest) {
     .filter((item) => item.sources.some((id) => selected.has(id)) || selected.has(item.verification?.source))
     .map((item) => item.id)
     .sort((left, right) => left.localeCompare(right));
+  const digestMode = sources[0]?.digestMode ?? "full-file";
+  const afterDigest = afterContent === null
+    ? null
+    : digestMode === "outside-owned-ai-entry"
+      ? outsideOwnedDigest(afterContent)
+      : sha256(afterContent);
   return { sourceIds, itemIds, afterDigest: sourceIds.length > 0 ? afterDigest : null };
 }
 
@@ -249,7 +265,7 @@ export async function publishAiEntry(root, project, options, dependencies = {})
   };
   const nextLock = nextProjectionLock(project, resolved.normalized, nextEntry);
   const action = currentEntry && existing === nextContent && canonicalJson(currentEntry) === canonicalJson(nextEntry) ? "unchanged" : currentEntry ? "update" : "create";
-  const impact = sourceImpact(project, resolved.normalized, sha256(nextContent));
+  const impact = sourceImpact(project, resolved.normalized, nextContent);
   const result = {
     action,
     current: {
@@ -304,7 +320,7 @@ export async function removeAiEntry(root, project, options, dependencies = {}) {
   }
   const nextContent = `${existing.slice(0, parsed.start)}${existing.slice(parsed.end)}`;
   const nextLock = nextProjectionLock(project, resolved.normalized, null);
-  const impact = sourceImpact(project, resolved.normalized, sha256(nextContent));
+  const impact = sourceImpact(project, resolved.normalized, nextContent);
   const result = {
     action: "remove",
     current: { entry: structuredClone(currentEntry), contentDigest: sha256(existing), region: parsed.region },

package/src/project-context/approver.mjs

@@ -1,5 +1,6 @@
 import { canonicalJson } from "./canonical-json.mjs";
 import {
+  promoteContractToSchema3,
   sourceForContract,
   sourceRegistrationShape,
   sourceStatus,
@@ -52,7 +53,7 @@ export async function approveProposal(root, project, proposalInput, options) {
   for (const sourceId of selectedSourceIds) {
     const source = proposalSources.get(sourceId);
     if (!source) fail("proposal-source-missing", `proposal source is missing: ${sourceId}`);
-    const actual = await readSourceDigest(root, source);
+    const actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
     if (actual !== null && actual !== source.digest) {
       fail("proposal-source-changed", `source changed after discovery: ${sourceId}`, {
         exitCode: 1,
@@ -61,6 +62,9 @@ export async function approveProposal(root, project, proposalInput, options) {
     }
   }
   const nextContract = structuredClone(project.contract);
+  if (selected.some((item) => item.consumption !== undefined) || [...selectedSourceIds].some((id) => proposalSources.get(id)?.digestMode !== undefined)) {
+    promoteContractToSchema3(nextContract);
+  }
   for (const sourceId of selectedSourceIds) {
     const source = proposalSources.get(sourceId);
     const existing = nextContract.sources.find((entry) => entry.id === sourceId);
@@ -141,7 +145,7 @@ export async function approvePendingItems(root, project, options) {
     }
     let actual;
     try {
-      actual = await readSourceDigest(root, source);
+      actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
     } catch (error) {
       fail("pending-source-changed", `pending item source is unavailable: ${sourceId}`, {
         exitCode: 1,

package/src/project-context/authoring.mjs

@@ -1,5 +1,6 @@
 import { canonicalJson } from "./canonical-json.mjs";
 import {
+  promoteContractToSchema3,
   sourceForContract,
   sourceRegistrationShape,
   sourceStatus,
@@ -32,8 +33,8 @@ function sourceLocator(source) {
   });
 }
 
-export async function buildRegisteredSource(root, input) {
-  const { id, kind, path: sourcePath, pointer, reference } = input;
+export async function buildRegisteredSource(root, input, options = {}) {
+  const { id, kind, path: sourcePath, pointer, reference, digestMode } = input;
   let source;
   if (LOCAL_SOURCE_KINDS.has(kind)) {
     if (!has(sourcePath) || has(reference) || (kind === "json-pointer" ? !has(pointer) : has(pointer))) {
@@ -44,21 +45,23 @@ export async function buildRegisteredSource(root, input) {
       kind,
       path: normalizeRelativePath(sourcePath, { label: "source path" }),
       ...(kind === "json-pointer" ? { pointer } : {}),
+      ...(digestMode !== undefined ? { digestMode } : {}),
     };
-    source.digest = await readSourceDigest(root, source);
+    if (digestMode !== undefined && kind !== "file") fail("argument-conflict", "--digest-mode is only valid for file sources");
+    source.digest = await readSourceDigest(root, source, undefined, { projectionsLock: options.projectionsLock });
   } else if (REFERENCE_SOURCE_KINDS.has(kind)) {
-    if (!has(reference) || has(sourcePath) || has(pointer)) {
+    if (!has(reference) || has(sourcePath) || has(pointer) || has(digestMode)) {
       fail("argument-conflict", `${kind} source requires only --reference`, { details: { source: id } });
     }
     source = { id, kind, reference };
   } else {
     fail("schema-invalid-enum", `source kind is invalid: ${kind}`, { details: { source: id } });
   }
-  return validateSource(source);
+  return validateSource(source, "source", { contractSchemaVersion: digestMode === undefined ? 1 : 3, proposal: true });
 }
 
 export async function registerSource(root, project, input, options = {}) {
-  const source = await buildRegisteredSource(root, input);
+  const source = await buildRegisteredSource(root, input, { projectionsLock: project.projectionsLock });
   const existingById = project.contract.sources.find((entry) => entry.id === source.id);
   if (existingById) {
     if (sourceStatus(existingById) === "deprecated" || canonicalJson(sourceRegistrationShape(existingById)) !== canonicalJson(source)) {
@@ -77,6 +80,7 @@ export async function registerSource(root, project, input, options = {}) {
   }
 
   const nextContract = structuredClone(project.contract);
+  if (source.digestMode !== undefined) promoteContractToSchema3(nextContract);
   const storedSource = sourceForContract(source, nextContract.schemaVersion);
   nextContract.sources.push(storedSource);
   nextContract.sources.sort((left, right) => left.id.localeCompare(right.id));
@@ -91,7 +95,7 @@ export async function registerSource(root, project, input, options = {}) {
 
   if (options.write) {
     if (LOCAL_SOURCE_KINDS.has(source.kind)) {
-      const actual = await readSourceDigest(root, source);
+      const actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
       if (actual !== source.digest) {
         fail("source-changed-during-register", `source changed while registration was being prepared: ${source.id}`, {
           exitCode: 1,
@@ -157,6 +161,21 @@ export function buildItemProposal(project, input) {
       details: { item: input.id, source: verification.source },
     });
   }
+  const requiredSources = input.requiredSources ?? [];
+  const conditionalSources = input.conditionalSources ?? [];
+  if (new Set(requiredSources).size !== requiredSources.length) fail("schema-duplicate", "--required-source contains duplicate IDs");
+  if (new Set(conditionalSources).size !== conditionalSources.length) fail("schema-duplicate", "--conditional-source contains duplicate IDs");
+  const roleSources = [...requiredSources, ...conditionalSources];
+  const overlap = requiredSources.find((source) => conditionalSources.includes(source));
+  if (overlap) fail("argument-conflict", `source cannot be both required and conditional: ${overlap}`);
+  for (const sourceId of roleSources) {
+    if (!sourceIds.includes(sourceId)) fail("source-reference-missing", `consumption source must be included in --sources: ${sourceId}`);
+    if (!LOCAL_SOURCE_KINDS.has(sourceMap.get(sourceId)?.kind)) fail("argument-conflict", `consumption source must be local: ${sourceId}`);
+  }
+  const consumption = roleSources.length > 0 ? {
+    requiredSources: [...requiredSources].sort((left, right) => left.localeCompare(right)),
+    conditionalSources: [...conditionalSources].sort((left, right) => left.localeCompare(right)),
+  } : undefined;
   const item = {
     id: input.id,
     kind: input.kind,
@@ -167,9 +186,10 @@ export function buildItemProposal(project, input) {
     status: "proposed",
     sources: sourceIds,
     overrides: input.overrides ?? [],
+    ...(consumption ? { consumption } : {}),
     ...(verification ? { verification } : {}),
   };
-  validateItem(item, "proposal item", { proposal: true });
+  validateItem(item, "proposal item", { proposal: true, contractSchemaVersion: 3 });
 
   if (item.overrides.length > 0) {
     const hypothetical = { ...structuredClone(item), status: "approved", approval: { by: "proposal-preflight", at: "1970-01-01T00:00:00.000Z" } };

package/src/project-context/capabilities.mjs

@@ -13,6 +13,8 @@ import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
 import { RENDERER_VERSION } from "./renderer.mjs";
 import { AI_ENTRY_RENDERER_VERSION } from "./ai-entry.mjs";
 import { PROJECT_STATUS_SCHEMA_VERSION } from "./project-status.mjs";
+import { CONTEXT_BUNDLE_SCHEMA_VERSION } from "./context-bundle.mjs";
+import { TASK_RECORD_SCHEMA_VERSION, TASK_HANDOFF_INPUT_SCHEMA_VERSION, TASK_HANDOFF_RESULT_SCHEMA_VERSION } from "./task-handoff-schema.mjs";
 import { EVIDENCE_BUNDLE_SCHEMA_VERSION, EVIDENCE_INPUT_SCHEMA_VERSION } from "./evidence-schema.mjs";
 import {
   CONTEXT_BUDGET_UNIT,
@@ -49,7 +51,13 @@ function schemas(projectionLockWritten = 1) {
     adaptiveContextBundle: ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION,
     assistBundle: ASSIST_BUNDLE_SCHEMA_VERSION,
     capabilities: CAPABILITIES_SCHEMA_VERSION,
-    contract: 2,
+    contract: 3,
+    contractReadable: [1, 2, 3],
+    contextBundle: CONTEXT_BUNDLE_SCHEMA_VERSION,
+    taskContextRecord: TASK_RECORD_SCHEMA_VERSION,
+    taskHandoffInput: TASK_HANDOFF_INPUT_SCHEMA_VERSION,
+    taskHandoffResult: TASK_HANDOFF_RESULT_SCHEMA_VERSION,
+    projectBrief: 1,
     contextQuery: CONTEXT_QUERY_SCHEMA_VERSION,
     coverageAudit: COVERAGE_AUDIT_SCHEMA_VERSION,
     dashboardViewModel: DASHBOARD_SCHEMA_VERSION,
@@ -115,6 +123,10 @@ export async function buildCapabilities(root) {
     package: { name: "frontend-project-context", version: PACKAGE_VERSION },
     exchangeProtocolVersion: EXCHANGE_PROTOCOL_VERSION,
     schemas: schemas(projectionLockWritten),
+    views: {
+      projectBrief: { default: "legacy", legacy: { schemaVersion: 1 }, work: { schemaVersion: 2 } },
+      taskHandoff: { default: "legacy", legacy: { schemaVersion: 1 }, work: { schemaVersion: 2 } },
+    },
     commands: [...COMMANDS],
     actionKinds: [...ACTION_KINDS],
     contextBudget: { unit: CONTEXT_BUDGET_UNIT, modelTokens: false, callerMustProvideLimit: true },

package/src/project-context/checker.mjs

@@ -26,7 +26,7 @@ export async function checkProject(root, project, options = {}) {
       continue;
     }
     try {
-      const actual = await readSourceDigest(root, source, sourceReadContext);
+      const actual = await readSourceDigest(root, source, sourceReadContext, { projectionsLock: project.projectionsLock });
       if (actual !== locked) findings.push({ code: "source-changed", source: source.id, path: source.path, expected: locked, actual });
     } catch (error) {
       const code = error.code === "source-missing"

package/src/project-context/cli.mjs

@@ -5,6 +5,7 @@ import { buildItemProposal, registerSource } from "./authoring.mjs";
 import { blockingContextFindings, checkExitCode, checkProject } from "./checker.mjs";
 import { digestJson, prettyCanonicalJson } from "./canonical-json.mjs";
 import { validateProposal } from "./contract-schema.mjs";
+import { buildContextBundle } from "./context-bundle.mjs";
 import { buildDashboardModel } from "./dashboard-model.mjs";
 import { renderDashboardHtml } from "./dashboard-renderer.mjs";
 import { discoverProject } from "./discovery.mjs";
@@ -20,10 +21,11 @@ import { initializeProject, inspectProjectInitialization, loadProject } from "./
 import { publishProjection } from "./projection-store.mjs";
 import { publishAiEntry, removeAiEntry } from "./ai-entry.mjs";
 import { buildProjectStatus } from "./project-status.mjs";
-import { renderContextBundle } from "./renderer.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,21 +35,23 @@ 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]
   project-context upgrade-apply --project PATH --plan FILE [--write] [--json]
   project-context setup --project PATH --id ID --name NAME [--output FILE] [--write] [--json]
-  project-context register --project PATH --id SOURCE_ID --kind KIND [--path PATH] [--pointer POINTER] [--reference TEXT] [--write] [--json]
-  project-context propose --project PATH --id ITEM_ID --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--output FILE --write] [--json]
+  project-context register --project PATH --id SOURCE_ID --kind KIND [--path PATH] [--pointer POINTER] [--reference TEXT] [--digest-mode full-file|outside-owned-ai-entry] [--write] [--json]
+  project-context propose --project PATH --id ITEM_ID --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--required-source SOURCE_ID...] [--conditional-source SOURCE_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--output FILE --write] [--json]
   project-context review-source --project PATH --id SOURCE_ID [--json]
   project-context accept-source-change --project PATH --id SOURCE_ID --expected-digest SHA256 [--affected-items ITEM_ID...] [--write] [--json]
-  project-context revise --project PATH --id ITEM_ID [--expected-item-digest SHA256] --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--write] [--json]
+  project-context revise --project PATH --id ITEM_ID [--expected-item-digest SHA256] --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--required-source SOURCE_ID...] [--conditional-source SOURCE_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--write] [--json]
   project-context deprecate --project PATH --id ITEM_ID [--expected-item-digest SHA256] --by NAME --rationale TEXT [--write] [--json]
   project-context deprecate-source --project PATH --id SOURCE_ID [--expected-source-digest SHA256] --by NAME --rationale TEXT [--write] [--json]
   project-context discover --project PATH [--output FILE --write] [--json]
   project-context approve --project PATH (--proposal FILE | --pending) --ids ID... --by NAME [--rationale TEXT] [--write] [--json | --full-json]
-  project-context context --project PATH --path RELATIVE_PATH... [--task TEXT] [--locale zh-CN|en|all] [--json]
+  project-context context --project PATH (--locate --task TEXT | --path RELATIVE_PATH... [--task TEXT]) [--locale zh-CN|en|all] [--json]
   project-context context-query --project PATH --input FILE [--previous FILE] [--json | --prompt]
   project-context coverage-audit --project PATH [--changed-path RELATIVE_PATH...] [--json]
   project-context index-context --project PATH [--write] [--json]
@@ -67,27 +71,29 @@ All commands are read-only unless their own --write flag is present.
 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",
-  "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan", "stage", "from-version", "assessment", "previous", "previous-review",
+  "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", "view",
 ]);
 const LIST_FLAGS = new Set([
-  "ids", "path", "input", "changed-path", "sources", "overrides", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
+  "ids", "path", "input", "changed-path", "sources", "overrides", "required-source", "conditional-source", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
 ]);
-const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending", "prompt"]);
+const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending", "prompt", "locate"]);
 const COMMAND_OPTIONS = new Map([
   ["init", new Set(["project", "id", "name", "write", "json", "help"])],
   ["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"])],
   ["upgrade-apply", new Set(["project", "plan", "write", "json", "help"])],
   ["setup", new Set(["project", "id", "name", "output", "write", "json", "help"])],
-  ["register", new Set(["project", "id", "kind", "path", "pointer", "reference", "write", "json", "help"])],
+  ["register", new Set(["project", "id", "kind", "path", "pointer", "reference", "digest-mode", "write", "json", "help"])],
   ["propose", new Set([
     "project", "id", "kind", "subject", "value", "value-json", "statement", "sources", "scope", "scope-path",
-    "overrides", "verification", "verification-source", "verification-expected-json", "output", "write", "json", "help",
+    "overrides", "required-source", "conditional-source", "verification", "verification-source", "verification-expected-json", "output", "write", "json", "help",
   ])],
   ["review-source", new Set(["project", "id", "json", "help"])],
   ["accept-source-change", new Set([
@@ -95,7 +101,7 @@ const COMMAND_OPTIONS = new Map([
   ])],
   ["revise", new Set([
     "project", "id", "expected-item-digest", "kind", "subject", "value", "value-json", "statement", "sources",
-    "scope", "scope-path", "overrides", "verification", "verification-source", "verification-expected-json",
+    "scope", "scope-path", "overrides", "required-source", "conditional-source", "verification", "verification-source", "verification-expected-json",
     "write", "json", "help",
   ])],
   ["deprecate", new Set([
@@ -106,7 +112,7 @@ const COMMAND_OPTIONS = new Map([
   ])],
   ["discover", new Set(["project", "output", "write", "json", "help"])],
   ["approve", new Set(["project", "proposal", "pending", "ids", "by", "rationale", "write", "json", "full-json", "help"])],
-  ["context", new Set(["project", "path", "task", "locale", "json", "help"])],
+  ["context", new Set(["project", "path", "locate", "task", "locale", "json", "help"])],
   ["context-query", new Set(["project", "input", "previous", "json", "prompt", "help"])],
   ["coverage-audit", new Set(["project", "changed-path", "json", "help"])],
   ["index-context", new Set(["project", "write", "json", "help"])],
@@ -233,6 +239,8 @@ function itemInput(options) {
     scope: required(options, "scope"),
     scopePath: options["scope-path"],
     overrides: options.overrides ?? [],
+    requiredSources: options["required-source"] ?? [],
+    conditionalSources: options["conditional-source"] ?? [],
     verification: options.verification,
     verificationSource: options["verification-source"],
     verificationExpectedPresent: hasExpected,
@@ -372,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 = [
@@ -449,7 +495,7 @@ async function runCommand(command, options) {
   if (command === "coverage-audit") {
     const audit = await buildCoverageAuditFiles(root, options["changed-path"] ?? []);
     const summary = `Registration coverage ${audit.registrationCoverage}: ${audit.categories["review-required"].length} review-required candidate(s).\n`;
-    return { exitCode: audit.registrationCoverage === "review-required" ? 1 : 0, stdout: jsonOrText(options, audit, summary), stderr: "" };
+    return { exitCode: ["review-required", "unresolved"].includes(audit.registrationCoverage) ? 1 : 0, stdout: jsonOrText(options, audit, summary), stderr: "" };
   }
   if (command === "index-context") {
     const index = await indexContextFiles(root, { write: options.write });
@@ -479,6 +525,7 @@ async function runCommand(command, options) {
       path: optionalOneListValue(options, "path"),
       pointer: options.pointer,
       reference: options.reference,
+      digestMode: options["digest-mode"],
     }, { write: options.write });
     const summary = result.action === "unchanged"
       ? `Source unchanged: ${result.source.id}.\n`
@@ -637,9 +684,19 @@ async function runCommand(command, options) {
   if (command === "context") {
     const findings = blockingContextFindings(await checkProject(root, project));
     if (findings.length > 0) fail("context-blocked", "context generation is blocked by contract or source findings", { exitCode: 1, details: { findings } });
-    const paths = required(options, "path");
-    const content = renderContextBundle(project.contract, paths, options.task, { locale: contextLocale(options) });
-    return { exitCode: 0, stdout: options.json ? prettyCanonicalJson({ content }) : content, stderr: "" };
+    const hasLocate = options.locate === true;
+    const hasPaths = options.path !== undefined;
+    if (hasLocate === hasPaths) fail("argument-conflict", "context requires exactly one of --locate or --path");
+    if (hasLocate && (typeof options.task !== "string" || options.task.trim().length === 0)) {
+      fail("argument-missing", "--locate requires a non-empty --task");
+    }
+    const bundle = await buildContextBundle(root, project, {
+      mode: hasLocate ? "locate" : "targeted",
+      paths: options.path ?? [],
+      task: options.task,
+      locale: contextLocale(options),
+    });
+    return { exitCode: 0, stdout: options.json ? prettyCanonicalJson(bundle) : bundle.content, stderr: "" };
   }
   if (command === "publish") {
     const findings = blockingContextFindings(await checkProject(root, project));