frontend-project-context 1.8.0 → 1.10.0

package/docs/39-SELF-HOST-RELEASE-ACCEPTANCE.md

@@ -0,0 +1,39 @@
+# 自托管验收与前端验证交接
+
+`2026-10-02`，用户要求先验收当前自研项目，再发布、更新前端项目，用真实任务验证后继续优化。本文件定义这次验收的证据和后续交接；实际包摘要、认证、发布及目标项目结果只记录在源码仓库的 `PROJECT_STATE.json.localReview.selfHostReleaseAcceptance`，避免将发布前动态状态固定进安装包。
+
+## 当前仓库的实际消费
+
+任务为 `.project-context-tasks/self-host-pre-release-acceptance.json`，基线提交 `6efbe30`，源码版本 `1.10.0`。开始时 status 为 clean / contract-ready，入口 renderer 7。当前 Host 使用工作视图取得同一份完整 Context，实际核对所需文件及当前用户原话、docs/37 设计，再提交绑定 taskId、requirementsDigest、contextBundleDigest 和 consumerRunId 的声明；调查与实施交接均从 hold 进入 proceed。
+
+命中 29 个 item；30 个目标中 17 个 scoped、13 个 project-only。required 32 个，conditional 20 个；本次适用并读取 docs/11、16、17、22、32，其余未扩展的历史协议按当前任务判断不适用，provenance-only 不重读。完整 IDs、路径、摘要和消费声明保存在当前 Host 的临时验收结果中；不将这些短期输入放进长期 Contract。
+
+本任务同时检查发布文档，修正旧的 248 项、capabilities 10、renderer 6 描述，保持 package、示例和安装 pin 均为 1.10.0。实际包检查发现 upgrade-check 将无需摘要 lock 的 human-decision 误报为 source-lock-missing；修复与 check 相同的来源分类规则，补 A-115 回归，先证实旧代码失败，再验证修复通过。本地来源缺失 lock 仍阻断，来源检查保持只读。修复时新增 checker 与 upgrade 测试两个读取目标，重新交接后 required 为 35 个。工作视图显式输出 schema 2，省略 view 仍输出 legacy schema 1。
+
+这份证据证明当前 Host 在一个实际维护任务中使用了交接，不能证明新窗口已正确续接，更不能证明移动端或 PC 的业务收益。
+
+## 实际发布包的固定检查
+
+1. 执行实际 `npm pack`，由 prepack 运行完整检查；检查包版本、所有文件、bin 可执行位和公开 schema 的相对引用。
+2. 排除源码仓库状态、RTK、AGENTS、Git、自托管 store、任务记录、测试、缓存和凭据。保留运行时、schema、文档、示例、迁移清单和许可证。
+3. 在隔离临时目录离线安装这份 tarball，使用安装后的 CLI 验证 capabilities、instructions、status、project-brief、当前真实任务 handoff 与 legacy 兼容。
+4. 用新 consumerRunId 验证未声明阅读时保持 hold、旧声明不能继承。这是机械协议检查，不标记为独立 Agent 验收。
+5. 通过后只发布已检查的同一 tarball；核对 registry 的版本、latest、integrity、下载字节，再在新临时消费者中核对安装版本。
+
+任何未完成的检查均保持待验收；npm 登录失败单列为发布环境问题。包版本尚未发布不等于可以省略上述检查。
+
+## 无历史消费者
+
+新窗口只接收当前仓库入口、准确 taskId、当前授权范围和验证目标。由它独立读取任务记录与工作视图、核对依据，提交自己的消费声明并报告已完成、剩余和下一步。不得把旧窗口的读取声明、ready 或本文的预期结论当成实际结果。
+
+该消费者的实际报告应回答：是否定位到本任务、是否看见当前原话和设计、是否拒绝继承旧声明、是否准确恢复进度、是否区分发布与前端收益仍待验证。新窗口创建与目标选择按用户明确指示执行；本窗口不虚构该结果。
+
+## 前端项目窗口的交接
+
+发布确认后，每个所选目标在自己的窗口执行。先 `pwd -P` 固定 targetRoot，保留原工作区改动，只读取当前项目，不访问父目录或兄弟项目；本自研窗口只观察目标 Host 返回的证据。
+
+目标 Host 核对当前版本和状态，使用项目原包管理器将依赖、lockfile 精确更新为 `frontend-project-context@1.10.0`。不得重新 setup 覆盖已有 store。用 upgrade-check / plan 核对现状，仅对仍拥有的旧入口显式 republish，按现有维护流程处理真实来源变化，并恢复 clean。运行与这次升级有关的验证，不凭包安装成功声称业务验收通过。
+
+随后在自然发生的真实业务任务中使用日常链路，共收集两个任务及一次无历史续接。保持原始资料和验收要求可比较，记录准备/录入、阅读/定位、用户澄清、遗漏/返工、续接恢复、来源维护与知识候选审查的实际时间和范围。没有可比较基线时净收益标记未知，不推测节省百分比。
+
+一次反馈先分类：产品漏报缺口或错误放行、项目资料缺失、Host 未遵循交接、外部环境。只有可复现的产品问题进入有界修复；收益不足先收窄长期知识和任务记录，避免为一次任务无限扩展内核。没有可靠知识候选时记录 0 条，不为了流程创建重复规则。

package/docs/AI-PROJECT-INITIALIZATION.md

@@ -2,7 +2,7 @@
 
 > Instruction ID: `ai-project-initialization`
 >
-> Instruction version: `1`
+> Instruction version: `2`
 >
 > Applies to: the exact locally installed `frontend-project-context` package version that contains this file
 
@@ -31,6 +31,7 @@ Turn the user-selected target project into a development-ready, human-approved P
 3. Before creating stores, inspect only target-root material needed to establish current project truth: AI context entries and their references; package/build/format/lint/test configuration; stable application, routing, request, state, and localization entry points; active team rules; and whether historical plans, logs, or review caches are still consumed.
 4. Verify statements against current configuration or necessary source. A file's existence alone does not make its contents authoritative. Do not register all source code as long-lived truth.
 5. Identify each critical development domain as one of: included in the proposed Contract, explicitly excluded with a human-reviewed reason, or an unresolved blocker. Any unresolved blocker prevents approval.
+6. Classify every duplicated or legacy human `AGENTS.md` rule as `migrated-to-contract`, `kept-in-entry-intentionally`, `excluded-as-stale`, or `unresolved-blocker`. Kept rules require a reason; unresolved blockers prevent completion. The product never deletes human entry text automatically.
 
 ## Phase B: govern the project entry first
 
@@ -39,7 +40,7 @@ Prepare an exact whole-file before digest, human-owned-region diff, and expected
 - Preserve valid project boundaries.
 - Correct descriptions contradicted by current configuration or source.
 - Downgrade or remove obsolete mandatory workflows and unconsumed plan/log/review requirements.
-- Make the root entry route every real task through local `status` and task/path `context` before source development.
+- Make the root entry route every real task through local work-view handoff (which checks status and compiles Context) before source development; read required evidence and resubmit the current-consumer declaration.
 - Move durable facts and rules into the Project Contract instead of accumulating them in entry prose.
 
 The product may write only its marker-delimited managed region. Any change to the human-owned region requires the user's approval of the exact diff.
@@ -83,7 +84,11 @@ Run all of the following inside `targetRoot`:
 
 1. `check` has no findings.
 2. `status --json` reports `health=clean`, `contractReadiness=contract-ready`, active sources, approved items, and current AI Entry renderer.
-3. Representative `context --path ... --task ...` calls prove project, path-prefix, and file scope hits and sibling isolation; record the actual item IDs, scopes, and necessary read targets.
+3. Representative `context --locate --task ... --json` and `context --path ... --task ... --json` calls prove unknown-path routing, project/path-prefix/file scope hits, sibling isolation, scopeCoverage, typed read targets, provenance-only sources, and explicit gaps.
 4. No setup proposal, initialization proposal, Action Plan, Review Bundle, log, or initialization cache remains in the repository.
 
 These facts establish local onboarding readiness, not full product acceptance. A separately authorized, memoryless Host must later receive only the initialized target project and a real development request, discover Project Context from the entry, consume the applicable Contract, report actual IDs/scopes/sources, remain within `targetRoot`, and only then enter target source. Until that external gate passes, stop and report that real Host acceptance is pending.
+
+After local onboarding, `project-brief --project PATH --view work --json` gives a read-only project and task overview. For a concrete task, create or select a minimal `.project-context-tasks/<taskId>.json` record outside this CLI, then use `task-handoff --project PATH --input FILE_OR_DASH --view work --json`. A first call lists required and conditional targets; the current Host reads them and resubmits a consumption declaration with path and SHA-256 for each required read. The result is an instructional context gate, not execution authority. A later Agent must submit its own consumerRunId and read declaration. No hook or vendor-specific configuration is required for this local entry protocol; actual compliance still needs real-Agent validation.
+
+The work view delivers the complete Context compiled by the same existing selector alongside task evidence, decisions and Host-reported progress. Default legacy output remains schema 1; the explicit work view uses schema 2 and never grants authority. A withheld delivery requires finite narrowing, not repeated retries. See [Everyday Handoff Operation](./38-EVERYDAY-HANDOFF-OPERATION.md) for one end-to-end example and the bounded, optional knowledge suggestions after completion. Suggestions are not persistent approval; unregistered sources require separate registration and a fresh item-plan baseline.

package/docs/PRODUCT-SHARING-AND-ADOPTION-GUIDE.md

@@ -0,0 +1,111 @@
+# 让 AI 真正读懂我们的项目
+
+> Frontend Project Context 产品分享·入门版  
+> 面向第一次接触的开发、测试、产品和项目负责人
+
+## 先记住这一句话
+
+**它是放在项目里的“AI 项目说明书”，让不同 AI 都按团队确认过的规则工作。**
+
+![从分散知识到统一项目上下文](./assets/product-sharing-01-overview.svg)
+
+AI 会写代码，但它并不天然了解我们的项目。每次换人、换工具、换对话，常常又要重新解释：
+
+- 哪份文档才是现在有效的？
+- 这条规则适用整个项目，还是只适用某个模块？
+- 项目变了，AI 读到的规则还对吗？
+
+Frontend Project Context 就是为了把这些问题变得可管理。
+
+## 它具体做了什么？
+
+![Frontend Project Context 的四步工作方式](./assets/product-sharing-02-how-it-works.svg)
+
+### 1. 收集可靠来源
+
+找到项目中真正有效的文档、配置和人工决定，并记住每条信息来自哪里。
+
+### 2. 由人确认项目规则
+
+把稳定的事实和规则收进 `Project Contract`。可以把它理解为：**团队共同认可的项目说明书**。
+
+AI 可以提建议，但只有人能让规则正式生效。
+
+### 3. 只给 AI 当前任务需要的内容
+
+修改航班模块，就给航班规则；修改酒店模块，就给酒店规则。不把整个项目的文档全部塞给 AI。
+
+### 4. 项目变化时及时提醒
+
+来源文档、规则或对外说明发生变化时，系统会报告哪些内容需要复核，不会自动猜测或悄悄修改。
+
+## 举一个例子
+
+![不同模块获得不同的精准上下文](./assets/product-sharing-03-example.svg)
+
+假设团队规定：
+
+> 航班价格页面必须使用统一价格明细，但这条规则不适用于酒店模块。
+
+传统做法中，这条规则可能藏在文档或聊天记录里。AI 可能没看到，也可能错用到酒店页面。
+
+使用 Frontend Project Context 后：
+
+- 这条规则会标明来源和适用范围；
+- AI 修改航班代码时会读到它；
+- AI 修改酒店代码时不会被这条规则干扰；
+- 来源变更后，旧规则会进入人工复核，不会继续被当作新事实。
+
+## 它能带来什么？
+
+| 对团队 | 对 AI 使用 | 对项目管理 |
+| --- | --- | --- |
+| 项目知识属于团队，不只在某个人脑中 | 换工具、换对话仍从同一份上下文出发 | 知道每条规则来自哪里、谁批准、适用哪里 |
+| 减少反复解释项目规则 | 少读无关材料，降低“凭经验猜项目” | 规则过期或冲突时能及时发现 |
+
+> 减少返工、提高 AI 首轮实现质量是我们希望获得的价值，但仍要通过团队试点用数据验证，不将它们提前当作已证明的结果。
+
+## 它不是什么？
+
+**它不是另一个 AI，也不会自动接管项目。**
+
+它不负责写业务代码、管理 Git、运行发布、自动批准规则。这些事继续交给现有 AI 工具、Git、CI 和人。
+
+它只专注一件事：**让 AI 开工前，拿到准确、适用且经过人确认的项目上下文。**
+
+## 现在到什么阶段了？
+
+`frontend-project-context@1.8.0` 已经：
+
+- 完成 `207/207` 本地验收；
+- 通过隔离真实项目接入和无历史 AI Host 接管；
+- 发布到官方 public npm，并完成包完整性复验。
+
+这证明产品已能安全接入项目；它在团队日常中能带来多大收益，是下一步试点要回答的问题。
+
+## 接下来想做什么？
+
+未来方向还没有被冻结成路线图。目前更关心三个问题：
+
+1. **日常真的有用吗？** 用真实任务测量首轮质量、纠正次数和维护成本。
+2. **多人协作时仍然可信吗？** 未来可继续验证多分支、测试和发布阶段的上下文衔接。
+3. **能不能更高效？** 在不牺牲人工批准和来源追溯的前提下，探索更低成本的增量上下文。
+
+## 怎么开始试点？
+
+不需要一开始就全团队推广，只做一个小实验：
+
+1. 选一个经常使用 AI、又经常需要重复解释规则的项目；
+2. 只整理 5–10 条最容易遗漏的高价值规则；
+3. 选 2–3 个真实任务，对比使用前后的纠正次数、首轮质量和上下文成本；
+4. 收益大于治理成本，再决定是否扩大。
+
+## 分享时可以这样结尾
+
+> 我们不是想再做一个 AI，而是想让任何 AI 进入项目时，都站在同一份、由团队认可的项目上下文上工作。如果你的项目也经常重复解释规则、纠正 AI 对项目的误解，我们可以先选一个小场景试点，用结果决定要不要继续。
+
+---
+
+想了解安装、CLI 和完整技术边界，请查看 [README](../README.md)、[产品宪法](./00-PRODUCT-CONSTITUTION.md) 和 [AI 项目初始化指令](./AI-PROJECT-INITIALIZATION.md)。
+
+本文是介绍材料，不是新的产品规范、路线图或执行授权。

package/docs/README.md

@@ -14,11 +14,35 @@
 
 记录 `2026-09-14` 关于“让团队共同拥有同一份项目上下文”的产品意义、真实项目应用重点，以及 Stateful Agent、Persistent KV 和增量上下文的远期讨论方向。该文档仅供团队查看和继续讨论，不是冻结设计、路线或实现授权。
 
-## 已冻结、待实现设计
+## 当前本地实施设计
+
+[35-CONTEXT-FIRST-TASK-HANDOFF-DESIGN.md](./35-CONTEXT-FIRST-TASK-HANDOFF-DESIGN.md)
+
+本地 L 阶段已按此文实施项目概览、跨消费者最小任务记录和指令式上下文门禁，并完成第 11 节治理采纳。用户选择先正式发布 `1.10.0`，再由真实项目窗口更新并提供实际观察证据；CF-14 跨 Agent 验收仍未完成。发布状态由当前 registry 与 `PROJECT_STATE.json` 确认。历史 A0 钩子结论不再阻断此主线。
+
+## 已获批产品方向与历史阶段方案
+
+[32-PROJECT-TO-TASK-INTERACTION-PROPOSAL.md](./32-PROJECT-TO-TASK-INTERACTION-PROPOSAL.md)
+
+`2026-09-29` 用户批准面向开发人员的项目上下文交互和生命周期方向。该文的硬保护阶段方案已由 `docs/35` 的上下文优先 D/L/H 顺序取代；更广的提醒和环境流转不属于当前 L 范围。
+
+## 当前实现基线
+
+[31-TASK-CONTEXT-INTEGRITY-REPAIR-DESIGN.md](./31-TASK-CONTEXT-INTEGRITY-REPAIR-DESIGN.md)
+
+已完成 `1.9.1 — Task Context Integrity Repair` 实现：修复 task target 与 registered source 同路径的重复 read target、同文件多 JSON Pointer 聚合丢失，以及 Context Bundle / Coverage Audit 的 coverage profile 双解析不一致。HC-01 至 HC-14、TC-01 至 TC-16 与全部回归共 237/237 通过，自托管 Contract 已采用 schema 3 consumption、`outside-owned-ai-entry` 和 coverage profile v2。两个隔离真实 Host 使用同一冻结源码候选完成只读复验，当时未确认产品缺陷；后续真实开发任务确认了任务上下文交接缺陷，由 `docs/32` 接管新方向。公开 schema、Exchange Protocol 9 与 AI Entry renderer 5 在 `1.9.1` 中未升级；发布状态由动态项目状态记录，不由本索引授权。
+
+## 已归档的前一本地实现基线
+
+[30-TASK-CONTEXT-CONSUMPTION-CLOSURE-DESIGN.md](./30-TASK-CONTEXT-CONSUMPTION-CLOSURE-DESIGN.md)
+
+基于两个真实项目的跨项目观察和 `1.8.0` 正式初始化后证据，冻结并完成 `1.9.0 — Task Context Consumption Closure` 本地实现：未知路径两阶段入口、精确多路径 Context、Context Bundle schema 1、required/conditional/provenance-only 读取职责、Contract schema 3、coverage profile v2、人工真源与受管 AI Entry 摘要解耦、AI Entry renderer 5，以及 TC-01 至 TC-16。TC-01 至 TC-16 与当时全部回归共 223/223 通过；后续审计发现的完整性缺陷由 docs/31 接管，原两个真实项目 Host 复验门在 `1.9.1` 本地修复完成前暂停。
+
+## 已完成的最新冻结设计
 
 [28-REAL-PROJECT-ONBOARDING-CLOSURE-DESIGN.md](./28-REAL-PROJECT-ONBOARDING-CLOSURE-DESIGN.md)
 
-基于 `2026-09-15` 在真实 `dtg-tmc-pc` 隔离副本中的正式接入与无历史 Host 接管过程，`1.8.0 — Real Project Onboarding Closure` 冻结并完成：包内唯一初始化指令、严格 targetRoot、目标入口治理、完整 proposal 一次语义确认、AI Entry renderer 4、project-status schema 2、O-01 至 O-12 以及无历史 Host 发布门。实现与 Host 验收事实见 `docs/28` 第 13、14 节；当前只执行用户另行授权的发布流程。
+基于 `2026-09-15` 在真实 `dtg-tmc-pc` 隔离副本中的正式接入与无历史 Host 接管过程，`1.8.0 — Real Project Onboarding Closure` 冻结并完成：包内唯一初始化指令、严格 targetRoot、目标入口治理、完整 proposal 一次语义确认、AI Entry renderer 4、project-status schema 2、O-01 至 O-12 以及无历史 Host 发布门。实现、Host 验收与官方 public npm 发布事实见 `docs/28` 第 13 至第 15 节；发布授权已经消费。
 
 ## 支持性设计文档
 

package/docs/USER-AND-AI-OPERATION-MANUAL.md

@@ -1,6 +1,6 @@
 # Frontend Project Context 操作手册
 
-> 适用版本：`frontend-project-context@1.8.0` 本地实现
+> 适用版本：`frontend-project-context@1.10.0`；真实项目 Agent 验收仍待后续观察，发布事实以 `PROJECT_STATE.json` 为准。
 >
 > 适用对象：项目维护者、开发者、使用 Codex / Claude / Cursor / 其他 Coding Agent 的团队，以及集成该 CLI 的 AI Host Agent。
 >
@@ -101,7 +101,7 @@ AI 可以提取事实、整理文字、去重、建议 scope/override、生成 p
 固定为项目开发依赖，使本地与 CI 使用同一版本：
 
 ```bash
-npm install --save-dev frontend-project-context@1.8.0
+npm install --save-dev --save-exact frontend-project-context@1.10.0
 ```
 
 建议在 `package.json` 中提供稳定入口：
@@ -130,7 +130,7 @@ npm exec --offline -- project-context status --project . --json
 
 `instructions` 和 `capabilities` 在项目未初始化时也可用。初始化的唯一规范正文是 [AI-PROJECT-INITIALIZATION.md](./AI-PROJECT-INITIALIZATION.md)；本手册只引用它，不另行定义执行顺序。
 
-`1.8.0` 的 AI Entry renderer 4 固定离线项目本地 CLI 入口，并要求 clean 状态的真实任务先运行 task/path `context`、消费实际命中的 item IDs、scope 与 read targets。既有 renderer 1/2/3 不会被静默覆盖，升级后会报告 stale，必须先预览并获得明确写入授权再 republish。
+当前本地源码的 AI Entry renderer 7 固定离线项目本地 CLI 入口，并通过 `project-brief --view work` 和 `task-handoff --view work` 交付完整 Context、任务依据和进度：先确认当前任务及依据，再报告 item IDs、scopeCoverage、required/conditional read targets、gaps 和本次指令式门禁。既有 renderer 1/2/3/4/5/6 不会被静默覆盖，必须明确授权 republish。门禁就绪不等于用户授予业务写入权限。
 
 ### 4.3 全新初始化不是普通升级
 
@@ -842,3 +842,9 @@ Receipt 只记录阶段证据，不代表人已验收、合并或批准长期规
 ```bash
 npm exec --offline -- project-context --help
 ```
+
+## 日常链路工作视图
+
+当前源码新增显式 `--view work`，详见 [完整日常示例](./38-EVERYDAY-HANDOFF-OPERATION.md)：无任务看已批准知识与声明范围；有任务直接获取完整 Context、当前依据、进度与具体缺口，实际读取后提交本消费者声明；完成时保存进度并给出 0–3 条有来源与范围的知识建议。用户选择后才进入既有治理，不自动批准长期知识。
+
+默认 legacy 输出不变，新视图不会增加 Host 权限；大于 1 MiB 的工作交付明确 withheld，收窄目标后重交接。本地行为验收与真实任务的净收益、维护成本分别记录。

package/docs/assets/product-sharing-01-overview.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="520" viewBox="0 0 1200 520" role="img" aria-labelledby="title desc">
+  <title id="title">从分散知识到统一项目上下文</title>
+  <desc id="desc">分散的文档、配置和人工决定经过 Frontend Project Context，变成同一份可信上下文，供不同 AI 工具使用。</desc>
+  <defs>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%"><feDropShadow dx="0" dy="8" stdDeviation="12" flood-color="#0f172a" flood-opacity=".12"/></filter>
+    <marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"><path d="M0,0 L12,6 L0,12 Z" fill="#64748b"/></marker>
+  </defs>
+  <rect width="1200" height="520" rx="28" fill="#f8fafc"/>
+  <text x="600" y="54" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif" font-size="28" font-weight="700" fill="#0f172a">把“到处找规则”变成“从同一份上下文开工”</text>
+  <g font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif" filter="url(#shadow)">
+    <rect x="60" y="105" width="260" height="74" rx="16" fill="#fff"/><circle cx="98" cy="142" r="20" fill="#dbeafe"/><path d="M89 132h18v21H89zM93 127h10l4 5H89z" fill="#2563eb"/><text x="132" y="150" font-size="21" fill="#1e293b">设计与业务文档</text>
+    <rect x="60" y="205" width="260" height="74" rx="16" fill="#fff"/><circle cx="98" cy="242" r="20" fill="#fef3c7"/><path d="M86 237h24v13H86zM90 232h16v5H90z" fill="#d97706"/><text x="132" y="250" font-size="21" fill="#1e293b">配置与代码事实</text>
+    <rect x="60" y="305" width="260" height="74" rx="16" fill="#fff"/><circle cx="98" cy="342" r="20" fill="#ede9fe"/><path d="M88 342l7 7 14-17" fill="none" stroke="#7c3aed" stroke-width="5" stroke-linecap="round"/><text x="132" y="350" font-size="21" fill="#1e293b">团队的人工决定</text>
+  </g>
+  <path d="M350 242H438" stroke="#64748b" stroke-width="4" marker-end="url(#arrow)"/>
+  <g filter="url(#shadow)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif">
+    <rect x="465" y="130" width="300" height="225" rx="28" fill="#1d4ed8"/>
+    <circle cx="615" cy="198" r="38" fill="#60a5fa"/><path d="M597 198h36M615 180v36" stroke="#fff" stroke-width="6" stroke-linecap="round"/>
+    <text x="615" y="270" text-anchor="middle" font-size="22" font-weight="700" fill="#fff">Frontend Project Context</text>
+    <text x="615" y="308" text-anchor="middle" font-size="20" fill="#dbeafe">统一、筛选、追溯、检查</text>
+  </g>
+  <path d="M792 242H866" stroke="#64748b" stroke-width="4" marker-end="url(#arrow)"/>
+  <g filter="url(#shadow)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif">
+    <rect x="895" y="112" width="245" height="260" rx="26" fill="#fff"/>
+    <rect x="930" y="143" width="175" height="72" rx="14" fill="#ecfdf5"/><circle cx="966" cy="179" r="18" fill="#10b981"/><text x="966" y="186" text-anchor="middle" font-size="18" font-weight="700" fill="#fff">AI</text><text x="995" y="186" font-size="19" fill="#14532d">工具 A</text>
+    <rect x="930" y="228" width="175" height="72" rx="14" fill="#eff6ff"/><circle cx="966" cy="264" r="18" fill="#3b82f6"/><text x="966" y="271" text-anchor="middle" font-size="18" font-weight="700" fill="#fff">AI</text><text x="995" y="271" font-size="19" fill="#1e3a8a">工具 B</text>
+    <text x="1018" y="337" text-anchor="middle" font-size="18" fill="#475569">同一份项目上下文</text>
+  </g>
+  <text x="190" y="425" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif" font-size="18" fill="#64748b">分散、难找、可能过期</text>
+  <text x="615" y="425" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif" font-size="18" fill="#64748b">人工确认后才生效</text>
+  <text x="1018" y="425" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif" font-size="18" fill="#64748b">换工具不再重新解释</text>
+</svg>

package/docs/assets/product-sharing-02-how-it-works.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="430" viewBox="0 0 1200 430" role="img" aria-labelledby="title desc">
+  <title id="title">Frontend Project Context 的四步工作方式</title>
+  <desc id="desc">从找到可靠来源，经过人工确认，按任务选择内容，到变化时提醒复核。</desc>
+  <defs><marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"><path d="M0,0 L12,6 L0,12 Z" fill="#94a3b8"/></marker></defs>
+  <rect width="1200" height="430" rx="28" fill="#0f172a"/>
+  <text x="600" y="58" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif" font-size="28" font-weight="700" fill="#fff">只需要理解四个动作</text>
+  <g font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif">
+    <g><rect x="55" y="112" width="235" height="220" rx="24" fill="#fff"/><circle cx="172" cy="168" r="34" fill="#dbeafe"/><text x="172" y="179" text-anchor="middle" font-size="30" font-weight="700" fill="#2563eb">1</text><text x="172" y="231" text-anchor="middle" font-size="24" font-weight="700" fill="#0f172a">找来源</text><text x="172" y="270" text-anchor="middle" font-size="18" fill="#64748b">知道信息从哪来</text><text x="172" y="299" text-anchor="middle" font-size="18" fill="#64748b">不把传言当规则</text></g>
+    <path d="M300 222H332" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+    <g><rect x="345" y="112" width="235" height="220" rx="24" fill="#fff"/><circle cx="462" cy="168" r="34" fill="#dcfce7"/><text x="462" y="179" text-anchor="middle" font-size="30" font-weight="700" fill="#16a34a">2</text><text x="462" y="231" text-anchor="middle" font-size="24" font-weight="700" fill="#0f172a">人确认</text><text x="462" y="270" text-anchor="middle" font-size="18" fill="#64748b">AI 可以提议</text><text x="462" y="299" text-anchor="middle" font-size="18" fill="#64748b">人决定是否生效</text></g>
+    <path d="M590 222H622" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+    <g><rect x="635" y="112" width="235" height="220" rx="24" fill="#fff"/><circle cx="752" cy="168" r="34" fill="#fef3c7"/><text x="752" y="179" text-anchor="middle" font-size="30" font-weight="700" fill="#d97706">3</text><text x="752" y="231" text-anchor="middle" font-size="24" font-weight="700" fill="#0f172a">按任务给</text><text x="752" y="270" text-anchor="middle" font-size="18" fill="#64748b">只给当前需要的</text><text x="752" y="299" text-anchor="middle" font-size="18" fill="#64748b">不用每次读全部</text></g>
+    <path d="M880 222H912" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+    <g><rect x="925" y="112" width="220" height="220" rx="24" fill="#fff"/><circle cx="1035" cy="168" r="34" fill="#fee2e2"/><text x="1035" y="179" text-anchor="middle" font-size="30" font-weight="700" fill="#dc2626">4</text><text x="1035" y="231" text-anchor="middle" font-size="24" font-weight="700" fill="#0f172a">变了提醒</text><text x="1035" y="270" text-anchor="middle" font-size="18" fill="#64748b">规则过期时报告</text><text x="1035" y="299" text-anchor="middle" font-size="18" fill="#64748b">不自动猜测修复</text></g>
+  </g>
+  <text x="600" y="385" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif" font-size="20" fill="#cbd5e1">核心原则：上下文属于项目和团队，人保留最终决定权</text>
+</svg>

package/docs/assets/product-sharing-03-example.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="500" viewBox="0 0 1200 500" role="img" aria-labelledby="title desc">
+  <title id="title">不同模块获得不同的精准上下文</title>
+  <desc id="desc">全局规则适用于整个项目，航班规则只传递给航班任务，酒店规则只传递给酒店任务。</desc>
+  <defs><marker id="blueArrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"><path d="M0,0 L12,6 L0,12 Z" fill="#3b82f6"/></marker><marker id="greenArrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"><path d="M0,0 L12,6 L0,12 Z" fill="#10b981"/></marker></defs>
+  <rect width="1200" height="500" rx="28" fill="#f8fafc"/>
+  <text x="600" y="52" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif" font-size="28" font-weight="700" fill="#0f172a">不是给得越多越好，而是给得越准越好</text>
+  <g font-family="-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif">
+    <rect x="55" y="98" width="290" height="92" rx="20" fill="#0f172a"/><text x="200" y="137" text-anchor="middle" font-size="22" font-weight="700" fill="#fff">全项目共同规则</text><text x="200" y="169" text-anchor="middle" font-size="17" fill="#cbd5e1">例：接口错误处理原则</text>
+    <rect x="55" y="226" width="290" height="92" rx="20" fill="#dbeafe"/><text x="200" y="265" text-anchor="middle" font-size="22" font-weight="700" fill="#1d4ed8">航班模块规则</text><text x="200" y="297" text-anchor="middle" font-size="17" fill="#1e40af">例：统一价格明细</text>
+    <rect x="55" y="354" width="290" height="92" rx="20" fill="#d1fae5"/><text x="200" y="393" text-anchor="middle" font-size="22" font-weight="700" fill="#047857">酒店模块规则</text><text x="200" y="425" text-anchor="middle" font-size="17" fill="#065f46">例：房型和入住人校验</text>
+    <rect x="515" y="130" width="280" height="250" rx="28" fill="#fff" stroke="#cbd5e1" stroke-width="2"/><circle cx="655" cy="202" r="42" fill="#2563eb"/><text x="655" y="212" text-anchor="middle" font-size="24" font-weight="700" fill="#fff">AI</text><text x="655" y="276" text-anchor="middle" font-size="24" font-weight="700" fill="#0f172a">当前任务</text><text x="655" y="315" text-anchor="middle" font-size="20" fill="#475569">修改航班价格页面</text><rect x="570" y="338" width="170" height="28" rx="14" fill="#eff6ff"/><text x="655" y="358" text-anchor="middle" font-size="15" fill="#1d4ed8">目标：src/flight</text>
+    <path d="M355 144C430 144 430 190 500 190" fill="none" stroke="#64748b" stroke-width="4" marker-end="url(#blueArrow)"/>
+    <path d="M355 272C430 272 430 250 500 250" fill="none" stroke="#3b82f6" stroke-width="6" marker-end="url(#blueArrow)"/>
+    <path d="M355 400C440 400 438 334 500 322" fill="none" stroke="#cbd5e1" stroke-width="4" stroke-dasharray="9 9"/>
+    <circle cx="468" cy="340" r="15" fill="#fff" stroke="#ef4444" stroke-width="3"/><path d="M461 333l14 14M475 333l-14 14" stroke="#ef4444" stroke-width="3"/>
+    <rect x="875" y="150" width="270" height="210" rx="26" fill="#eff6ff" stroke="#93c5fd" stroke-width="2"/><text x="1010" y="198" text-anchor="middle" font-size="23" font-weight="700" fill="#1e3a8a">AI 本次拿到</text><text x="915" y="247" font-size="19" fill="#1e3a8a">✓ 全项目共同规则</text><text x="915" y="286" font-size="19" fill="#1e3a8a">✓ 航班模块规则</text><text x="915" y="325" font-size="19" fill="#64748b">— 不带入酒店规则</text>
+    <path d="M810 255H855" stroke="#10b981" stroke-width="5" marker-end="url(#greenArrow)"/>
+  </g>
+</svg>

package/examples/package.json

@@ -14,6 +14,6 @@
     "context:upgrade-check": "project-context upgrade-check --project ."
   },
   "devDependencies": {
-    "frontend-project-context": "1.8.0"
+    "frontend-project-context": "1.10.0"
   }
 }

package/migration-manifest.json

@@ -23,14 +23,15 @@
   "consumerChanges": {
     "actionPlan": {"reason": "Action Plan schema 1 and 2 readers remain compatible; writers remain schema 2.", "state": "preserve"},
     "adaptiveContextBundle": {"reason": "Schema 1 Adaptive Context Bundles lack task lineage and strict withheld-delivery semantics; regenerate as schema 2.", "state": "regenerate"},
-    "capabilities": {"reason": "Consumers must branch on capabilities schema 8 and exchange protocol 8.", "state": "regenerate"},
+    "capabilities": {"reason": "Consumers must branch on capabilities schema 11 and exchange protocol 9; explicit work views use output schema 2 while defaults remain legacy.", "state": "regenerate"},
+    "contextBundle": {"reason": "Context Bundle schema 1 is short-lived and must be regenerated from the current Contract and exact task paths.", "state": "regenerate"},
     "contextQuery": {"reason": "Context Query schema 1 is short-lived and must use current snapshots.", "state": "regenerate"},
-    "coverageAudit": {"reason": "Coverage Audit schema 1 is derived from the current Contract and filesystem evidence.", "state": "regenerate"},
+    "coverageAudit": {"reason": "Coverage Audit schema 2 is derived from the current Contract and declared coverage profile.", "state": "regenerate"},
     "evidenceBundle": {"reason": "Evidence Bundle schema 1 remains readable and separate from upgrade results.", "state": "preserve"},
     "evidenceInput": {"reason": "Evidence Input schema 1 remains readable and is never rewritten by upgrade.", "state": "preserve"},
-    "exchange": {"reason": "Exchange protocol capability metadata changes to version 8.", "state": "regenerate"},
+    "exchange": {"reason": "Exchange protocol capability metadata changes to version 9.", "state": "regenerate"},
     "hostPromotionEvidence": {"reason": "Host Promotion Evidence is short-lived and remains bound to exact code, artifact, and Project Context snapshots.", "state": "regenerate"},
-    "initializationInstruction": {"reason": "Schema 1 is package-derived from the exact installed instruction and resolved target root.", "state": "regenerate"},
+    "initializationInstruction": {"reason": "Schema 2 adds concentrated human entry rule dispositions and remains package-derived.", "state": "regenerate"},
     "integrationReviewBundle": {"reason": "Short-lived integration review bundles must be regenerated against current baselines.", "state": "regenerate"},
     "projectStatus": {"reason": "Schema 2 separates governance health from Contract readiness and task-context routing.", "state": "regenerate"},
     "reviewBundle": {"reason": "Review Bundle schema 2 remains readable but short-lived reviews must be regenerated when their baselines change.", "state": "regenerate"},
@@ -42,8 +43,8 @@
     ,"truthReconciliationReviewBundle": {"reason": "Schema 1 reviews lack finding digests and machine-verifiable resolution outcomes; recompute as schema 2.", "state": "regenerate"}
   },
   "externalEffects": {"automaticUpgrade": false, "businessCode": false, "git": false, "network": false, "packageManager": false, "projectTests": false},
-  "manifestDigest": "sha256:be29e7ee930d34533380e6d2408f614fc7406ad3491a1657776d904bcc5ebacf",
-  "package": {"name": "frontend-project-context", "version": "1.8.0"},
+  "manifestDigest": "sha256:fd439d7a88064f7069b95cbdd5a8d2d33499c48c6522f7084a49d32f939834fd",
+  "package": {"name": "frontend-project-context", "version": "1.10.0"},
   "paths": [
     {
       "acceptance": ["project-context-clean", "target-renderers-current"],
@@ -84,18 +85,43 @@
       "migrationIds": ["upgrade.republish-ai-entry.v1"],
       "requiresHumanReview": false,
       "rollbackClass": "package-only"
+    },
+    {
+      "acceptance": ["project-context-clean", "target-renderers-current"],
+      "classification": "package-only",
+      "fromVersion": "1.8.0",
+      "migrationIds": ["upgrade.republish-ai-entry.v1"],
+      "requiresHumanReview": false,
+      "rollbackClass": "package-only"
+    },
+    {
+      "acceptance": ["project-context-clean", "target-renderers-current"],
+      "classification": "package-only",
+      "fromVersion": "1.9.0",
+      "migrationIds": ["upgrade.republish-ai-entry.v1"],
+      "requiresHumanReview": false,
+      "rollbackClass": "package-only"
+    },
+    {
+      "acceptance": ["project-context-clean", "target-renderers-current"],
+      "classification": "package-only",
+      "fromVersion": "1.9.1",
+      "migrationIds": ["upgrade.republish-ai-entry.v1"],
+      "requiresHumanReview": false,
+      "rollbackClass": "package-only"
     }
   ],
   "protocols": {
     "actionPlan": {"readable": [1, 2], "written": 2},
     "adaptiveContextBundle": {"readable": [2], "written": 2},
+    "contextBundle": {"readable": [1], "written": 1},
     "contextQuery": {"readable": [2], "written": 2},
-    "coverageAudit": {"readable": [1], "written": 1},
+    "coverageAudit": {"readable": [1, 2], "written": 2},
     "evidenceBundle": {"readable": [1], "written": 1},
     "evidenceInput": {"readable": [1], "written": 1},
-    "exchange": {"readable": [4, 5, 6, 7, 8], "written": 8},
+    "exchange": {"readable": [4, 5, 6, 7, 8, 9], "written": 9},
     "hostPromotionEvidence": {"readable": [1], "written": 1},
-    "initializationInstruction": {"readable": [1], "written": 1},
+    "initializationInstruction": {"readable": [1, 2], "written": 2},
     "integrationReviewBundle": {"readable": [1], "written": 1},
     "projectStatus": {"readable": [1, 2], "written": 2},
     "reviewBundle": {"readable": [1, 2], "written": 2},
@@ -107,16 +133,16 @@
     "truthReconciliationReviewBundle": {"readable": [2], "written": 2}
   },
   "renderers": {
-    "aiEntry": {"readable": [1, 2, 3, 4], "written": 4},
+    "aiEntry": {"readable": [1, 2, 3, 4, 5, 6, 7], "written": 7},
     "projection": {"readable": [1, 2, 3], "written": 3}
   },
   "rollback": {"automatic": false, "defaultClass": "package-only", "externalRestoreRequired": true},
   "schemaVersion": 2,
   "stores": {
-    "contract": {"readable": [1, 2], "written": [1, 2]},
+    "contract": {"readable": [1, 2, 3], "written": [1, 2, 3]},
     "projectionLock": {"readable": [1, 2], "written": [1, 2]},
     "proposal": {"readable": [1], "written": [1]},
     "sourceLock": {"readable": [1], "written": [1]}
   },
-  "upgradeFrom": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0"]
+  "upgradeFrom": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0", "1.8.0", "1.9.0", "1.9.1"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-project-context",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Govern, compile, and verify project-local context for AI coding tools.",
   "private": false,
   "publishConfig": {
@@ -27,7 +27,7 @@
   },
   "scripts": {
     "check": "node --check bin/project-context.mjs && npm test",
-    "test": "node --test test/project-context/acceptance.test.mjs test/project-context/adaptive-context.test.mjs test/project-context/adaptive-delivery-v2.test.mjs test/project-context/assist.test.mjs test/project-context/cli.test.mjs test/project-context/dashboard.test.mjs test/project-context/evidence.test.mjs test/project-context/exchange.test.mjs test/project-context/maintenance.test.mjs test/project-context/onboarding-closure.test.mjs test/project-context/source-lifecycle.test.mjs test/project-context/task-context.test.mjs test/project-context/takeover.test.mjs test/project-context/truth-reconciliation.test.mjs test/project-context/upgrade.test.mjs test/release/acceptance.test.mjs",
+    "test": "node --test test/project-context/acceptance.test.mjs test/project-context/adaptive-context.test.mjs test/project-context/adaptive-delivery-v2.test.mjs test/project-context/assist.test.mjs test/project-context/cli.test.mjs test/project-context/context-first-handoff.test.mjs test/project-context/dashboard.test.mjs test/project-context/evidence.test.mjs test/project-context/exchange.test.mjs test/project-context/maintenance.test.mjs test/project-context/onboarding-closure.test.mjs test/project-context/source-lifecycle.test.mjs test/project-context/task-context.test.mjs test/project-context/task-context-consumption.test.mjs test/project-context/takeover.test.mjs test/project-context/truth-reconciliation.test.mjs test/project-context/upgrade.test.mjs test/release/acceptance.test.mjs",
     "prepack": "npm run check"
   },
   "engines": {

package/schemas/capabilities.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:frontend-project-context:schema:capabilities:8",
+  "$id": "urn:frontend-project-context:schema:capabilities:11",
   "title": "Frontend Project Context Capabilities",
   "type": "object",
   "additionalProperties": false,
@@ -16,20 +16,22 @@
     "initialization",
     "initialized",
     "project",
-    "boundaries"
+    "boundaries",
+    "views"
   ],
   "properties": {
-    "schemaVersion": { "const": 8 },
+    "views": {"type": "object", "additionalProperties": false, "required": ["projectBrief", "taskHandoff"], "properties": {"projectBrief": {"type": "object", "additionalProperties": false, "required": ["default", "legacy", "work"], "properties": {"default": {"const": "legacy"}, "legacy": {"type": "object", "additionalProperties": false, "required": ["schemaVersion"], "properties": {"schemaVersion": {"const": 1}}}, "work": {"type": "object", "additionalProperties": false, "required": ["schemaVersion"], "properties": {"schemaVersion": {"const": 2}}}}}, "taskHandoff": {"type": "object", "additionalProperties": false, "required": ["default", "legacy", "work"], "properties": {"default": {"const": "legacy"}, "legacy": {"type": "object", "additionalProperties": false, "required": ["schemaVersion"], "properties": {"schemaVersion": {"const": 1}}}, "work": {"type": "object", "additionalProperties": false, "required": ["schemaVersion"], "properties": {"schemaVersion": {"const": 2}}}}}}},
+    "schemaVersion": { "const": 11 },
     "package": {
       "type": "object",
       "additionalProperties": false,
       "required": ["name", "version"],
       "properties": {
         "name": { "const": "frontend-project-context" },
-        "version": { "const": "1.8.0" }
+        "version": { "const": "1.10.0" }
       }
     },
-    "exchangeProtocolVersion": { "const": 8 },
+    "exchangeProtocolVersion": { "const": 9 },
     "schemas": {
       "type": "object",
       "additionalProperties": false,
@@ -39,6 +41,8 @@
         "assistBundle",
         "capabilities",
         "contract",
+        "contractReadable",
+        "contextBundle",
         "contextQuery",
         "coverageAudit",
         "dashboardViewModel",
@@ -62,32 +66,38 @@
         "stageContextBundle",
         "stageReceipt",
         "taskContextPlan",
+        "taskContextRecord",
+        "taskHandoffInput",
+        "taskHandoffResult",
         "truthReconciliationInput",
         "truthReconciliationReviewBundle",
         "upgradeAssessment",
-        "upgradeResultBundle"
+        "upgradeResultBundle",
+        "projectBrief"
       ],
       "properties": {
         "actionPlan": { "const": 2 },
         "adaptiveContextBundle": { "const": 2 },
         "assistBundle": { "const": 1 },
-        "capabilities": { "const": 8 },
-        "contract": { "const": 2 },
+        "capabilities": { "const": 11 },
+        "contract": { "const": 3 },
+        "contractReadable": { "const": [1, 2, 3] },
+        "contextBundle": { "const": 1 },
         "contextQuery": { "const": 2 },
-        "coverageAudit": { "const": 1 },
+        "coverageAudit": { "const": 2 },
         "dashboardViewModel": { "type": "integer" },
         "evidenceBundle": { "const": 1 },
         "evidenceInput": { "const": 1 },
         "hostPromotionEvidence": { "const": 1 },
         "integrationReviewBundle": { "const": 1 },
-        "initializationInstruction": { "const": 1 },
+        "initializationInstruction": { "const": 2 },
         "projectionLock": { "const": 2 },
         "projectionLockReadable": { "const": [1, 2] },
         "projectionLockWritten": { "enum": [1, 2] },
         "projectionRenderer": { "type": "integer" },
         "proposal": { "const": 1 },
         "projectStatus": { "const": 2 },
-        "aiEntryRenderer": { "const": 4 },
+        "aiEntryRenderer": { "const": 7 },
         "migrationManifest": { "const": 2 },
         "migrationPlan": { "const": 1 },
         "reviewBundle": { "const": 2 },
@@ -96,6 +106,10 @@
         "stageContextBundle": { "const": 1 },
         "stageReceipt": { "const": 1 },
         "taskContextPlan": { "const": 1 },
+        "taskContextRecord": { "const": 1 },
+        "taskHandoffInput": { "const": 1 },
+        "projectBrief": { "const": 1 },
+        "taskHandoffResult": { "const": 1 },
         "truthReconciliationInput": { "const": 2 },
         "truthReconciliationReviewBundle": { "const": 2 },
         "upgradeAssessment": { "const": 1 },
@@ -139,7 +153,7 @@
       "required": ["id", "version", "packagePath", "digest", "command"],
       "properties": {
         "id": {"const": "ai-project-initialization"},
-        "version": {"const": 1},
+        "version": {"const": 2},
         "packagePath": {"const": "docs/AI-PROJECT-INITIALIZATION.md"},
         "digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
         "command": {"const": "project-context instructions --project PATH [--json | --prompt]"}