frontend-project-context 1.8.0 → 1.9.1

package/docs/31-TASK-CONTEXT-INTEGRITY-REPAIR-DESIGN.md

@@ -0,0 +1,281 @@
+# 31 — Task Context Integrity Repair 设计
+
+> 日期：`2026-09-22`
+>
+> 状态：`implemented-local; self-host-adopted; two-project-real-host-revalidation-passed`
+>
+> 目标版本：`1.9.1 — Task Context Integrity Repair`
+>
+> 权威边界：本文冻结 `1.9.0` 本地实现后发现的 Context 消费正确性修复、兼容合同与可证伪验收。`2026-09-22` 已按本文完成本地实现、自托管采用与两个真实项目的独立授权复验；该阶段未调用 Provider，未执行 Git、网络、打包或发布。后续打包与发布的授权及结果只由动态项目状态记录。
+
+## 1. 结论先行
+
+`1.9.0` 已完成 TC-01 至 TC-16 与既有回归，但后续自托管只读审计发现三个会破坏其冻结语义的内核正确性缺陷：
+
+1. task target 与 registered source 指向同一路径时，会生成重复 `readTargets.path`，随后被 Context Bundle 自身的严格 validator 拒绝；
+2. 同一 JSON 文件存在多个 `json-pointer` source 时，聚合记录没有合并全部 `pointers`，Host 可能获得不完整的最小读取位置；
+3. Context Bundle 与 Coverage Audit 各自解析 coverage profile，其中前者会把部分非法 v2 静默降级，导致同一 Contract 在两个入口产生不同结论。
+
+三项均属于 `docs/30` 已冻结能力的正确性缺陷，不是新产品能力、目标项目数据缺口或 Host 执行偏差。`1.9.0` 保留为“本地实现完成但被新证据阻断的未发布候选”；下一本地候选改为补丁版本 `1.9.1`。在本设计实现并通过验收前，不进入原定的两个真实项目 Host 复验。
+
+## 2. 已确认事实与缺陷归类
+
+| ID | 事实 | 分类 | 发布影响 |
+| --- | --- | --- | --- |
+| IR-01 | `consumptionRecords()` 分别用 `task:<path>` 和 `source:<path>` 建立记录；同一物理路径可出现两次 | P0 内核缺陷 | 阻断 1.9 真实 Host 复验 |
+| IR-02 | merge 只合并 role、item IDs、source IDs 和 reasons，不合并 `pointers` | P0 内核缺陷 | 阻断最小读取职责可信性 |
+| IR-03 | Context Bundle 使用宽松 coverage parser，Coverage Audit 使用严格 parser | P0 内核缺陷 | 阻断 coverage 结论一致性 |
+| IR-04 | `PROJECT_STATE.json` 的 compatibility 摘要仍残留 1.8.0 协议版本 | 动态事实缺陷 | 在冻结设计同步中修正，不算产品实现 |
+| IR-05 | 当前自托管 Contract 仍为 schema 1，尚未实际采用 consumption、digestMode 或 coverage profile | 本地采用缺口 | 纳入实现后的自托管采用门，不冒充内核缺陷 |
+
+本轮不把 npm cache `EPERM`、真实项目尚未复验或未启用 Provider 归入产品缺陷。
+
+## 3. 版本与永久边界
+
+### 3.1 版本裁决
+
+- 目标 package version 为 `1.9.1`；
+- 公共已发布基线仍为 `1.8.0`；
+- `1.9.0` 未打包、未发布、未做两个项目的真实 Host 复验；
+- `1.9.1` 是对 `1.9.0` 冻结语义的补丁修复，不新增用户能力；
+- 实现后从 `1.8.0` 或本地 `1.9.0` 进入 `1.9.1` 均为 `package-only`，不自动迁移任何目标项目 Contract。
+
+### 3.2 保持不变
+
+- 产品宪法、产品身份与七项内核不变；
+- Contract 可读 schema `1/2/3`、特性 schema `3` 不变；
+- Context Bundle schema `1` 不变；
+- Coverage Audit schema `2`、coverage profile v2 不变；
+- Capabilities / Exchange Protocol `9` 不变；
+- Initialization Instruction schema `2`、AI Entry renderer `5` 不变；
+- Project Status、projection renderer 和全部其他公开 schema 不变；
+- 不新增持久 store、CLI 命令、权限、Provider、Agent Runtime 或业务代码写入器。
+
+## 4. Read Target 唯一身份与聚合合同
+
+### 4.1 唯一身份
+
+`readTargets[]` 的唯一身份固定为规范化后的项目相对 `path`。task target、file source、path source 和 json-pointer source 不得再用不同前缀形成独立身份。
+
+所有贡献先进入同一个 path record，再统一输出：
+
+```text
+normalize path
+→ get-or-create one record by path
+→ merge role and all provenance fields
+→ remove provenance-only records from readTargets
+→ stable sort by path
+→ validate and seal bundle
+```
+
+每个规范化 path 最多输出一条 read target。严格 validator 继续拒绝外部构造的重复 path；修复的是 builder 不再生成非法数据，不是放宽 validator。
+
+### 4.2 完整、无损合并
+
+同一路径的所有贡献固定按以下规则合并：
+
+- `role`：按 `required > conditional > provenance-only` 取最强职责；
+- `itemIds`：完整并集、去重、稳定排序；
+- `sourceIds`：完整并集、去重、稳定排序；
+- `reasons`：完整并集、去重、稳定排序；
+- `pointers`：全部 json-pointer locator 的完整并集、去重、稳定排序；
+- 不存在 json-pointer contribution 时省略 `pointers`，不得输出空数组；
+- RFC 6901 的空字符串根 pointer `""` 是合法值，不得按假值过滤。
+
+如果 task target 与任意 source 同路径：
+
+- 最终 role 必须为 `required`；
+- 必须保留 `task-target` 和全部 `contract-source:*` reasons；
+- source/item provenance 不得因 task target 已要求读取而丢失；
+- `pointers` 只表达该路径关联的 JSON Pointer locator，不得覆盖或收窄 task target、file source 或 path source 的路径级读取职责。
+
+### 4.3 provenance-only 去重
+
+- 只有 provenance-only 贡献的路径不进入 `readTargets`；
+- 其来源继续按 source ID 出现在 `provenanceSources`；
+- 同一路径已有 required 或 conditional read target 时，相关本地 provenance source 只并入该 path record，不得再重复出现在 `provenanceSources`；
+- required target 的存在性检查每个 path 只执行一次；
+- 输入 target、item 和 source 的遍历顺序不得改变规范输出或 `bundleDigest`。
+
+## 5. Coverage Profile 单一解析源
+
+### 5.1 共享模块
+
+实现阶段抽取一个纯本地、无持久副作用的共享模块，例如：
+
+```text
+src/project-context/coverage-profile.mjs
+```
+
+该模块唯一负责：
+
+- 找到唯一 approved `policy / project.registration-coverage`；
+- 无 profile 时返回 `null`；
+- 多个 active profile 时返回 `coverage-profile-conflict`；
+- 严格解析和规范化既有 v1；
+- 严格解析 v2 exact keys、domain ID/path 唯一性、稳定顺序、disposition、itemIds、有效 scope 和 exclusion rationale；
+- 以最长路径优先、domain ID 打破平局的规则选择匹配 domain；
+- 返回供 Context Bundle 与 Coverage Audit 共同使用的规范结果。
+
+`context-bundle.mjs` 与 `adaptive-context.mjs` 不得继续保存各自的 parser。为避免内部调用漂移，后者可以 re-export 既有 helper 名称，但实现必须只有一处。
+
+### 5.2 失败封闭
+
+- 合法 v1/v2 的既有含义不变；
+- 非法 v2 不再静默降级为 v1；
+- 两个入口对非法 profile 都返回 `coverage-profile-invalid`；
+- 两个入口对多 active profile 都返回 `coverage-profile-conflict`；
+- 不自动把 v1 迁移为 v2；
+- 不自动生成、修改或批准 coverage；
+- Context Bundle 与 Coverage Audit 可以保留各自的展示映射，但不得重新解释 profile。
+
+## 6. 自托管采用门
+
+`1.9.1` 本地实现通过代码测试后，才允许在同一实现授权内使用现有治理原语完成有界 self-host adoption：
+
+1. 注册本文及 `PROJECT_STATE.json#/planning/taskContextIntegrityRepair` 为 source；
+2. 新增 `task.context.integrity-repair` Contract item；
+3. 对少量高价值现有 item 显式 author required/conditional source 职责，使 Contract 升级至 schema 3；
+4. 若登记根 `AGENTS.md` 作为人工真源，必须使用 `outside-owned-ai-entry` 且验证 marker/ownership；
+5. 新增 coverage profile v2 时，必须诚实区分 `contract-covered`、`dynamic-investigation`、`excluded-approved` 和 `unresolved`；不得把全仓伪装为已覆盖；
+6. 用已修复的 exact-path Context 对本文、`PROJECT_STATE.json`、`package.json` 等 registered source/多 pointer 路径做本地 dogfood；
+7. 最终 `check/status` 回到 clean。
+
+这一门只证明本仓库采用了 1.9 能力，不能替代两个真实项目的无历史 Host 复验。
+
+## 7. 兼容合同
+
+允许变化：
+
+- 受 IR-01/IR-02 影响的短生命周期 Context Bundle 内容和 `bundleDigest`；
+- 非法 coverage profile 从错误容忍收紧为失败封闭；
+- package/runtime/docs 中的候选版本事实从 `1.9.0` 更新为 `1.9.1`；
+- 自托管 Contract 在显式治理动作后使用 schema-3 字段和 coverage profile。
+
+必须保持：
+
+- CLI 命令与参数；
+- 纯文本 Context 与 `--json.content` 的选择语义；
+- 合法 Context Bundle schema 1 的字段形状；
+- schema-1/2 Contract 的只读字节稳定性；
+- source/projection lock 兼容；
+- 所有不受缺陷影响的 bundle 语义；
+- 现有 TC-01 至 TC-16 的断言不得删除、改名或弱化。
+
+## 8. 冻结验收合同
+
+| ID | 可证伪验收事实 |
+| --- | --- |
+| HC-01 | 任意 task/source contribution 聚合后，每个规范化 path 只产生一个记录，输出按 path 稳定排序。 |
+| HC-02 | task target 恰好也是 registered source 时，Context Bundle 成功生成；该 path 只出现一次、role 为 required，并保留 task 与 Contract reasons。 |
+| HC-03 | 表驱动覆盖职责格：仅 provenance 不进入 readTargets；conditional 压过 provenance；required 压过其余；task target 与任何来源重合均为 required。 |
+| HC-04 | 同一 path 由 task、required、conditional 和 provenance 多项共同贡献时，itemIds、sourceIds、reasons、pointers 均为完整、唯一、排序并集。 |
+| HC-05 | 同一 JSON 文件登记多个 json-pointer source 时只产生一个 read target，并完整保留根 pointer 与多个嵌套 pointer。 |
+| HC-06 | file/path/json-pointer 混合贡献及遍历顺序不改变 pointer/provenance 结果；无 pointer contribution 时省略 pointers。 |
+| HC-07 | 同一 source 被多个 effective item 以不同职责引用时，source ID 唯一、全部 item/reason 保留、职责取最强值。 |
+| HC-08 | 纯 provenance source 仍进入 provenanceSources；同 path 已有 read target 时不得重复出现。 |
+| HC-09 | 反转 target、item、source 顺序不改变 bundle 或 digest；手工构造重复 path 的 bundle 仍被严格 validator 拒绝。 |
+| HC-10 | 生产代码只有一个 coverage profile parser/selector；Context Bundle 与 Coverage Audit 均使用共享模块。 |
+| HC-11 | 合法 v2 的四种 disposition、outside-declared 和嵌套最长路径命中在两个消费者中一致。 |
+| HC-12 | v2 未知字段、重复 ID/path、非规范路径、非法 disposition、未排序 itemIds、无效 item 引用或缺 rationale 时，两入口均失败封闭。 |
+| HC-13 | 合法 v1 在两个入口继续可读；非法 v1 和多个 active profile 分别得到一致的 invalid/conflict 错误。 |
+| HC-14 | HC-01 至 HC-14、TC-01 至 TC-16 及全部既有 223 项回归通过；公开 schema/protocol/renderer 不升级，且实现过程无边界外副作用。 |
+
+若每个 HC 对应一个顶层自动化用例，最低总数为 `237/237`。最终实现事实必须记录实际测试数，但不得用计数替代上述语义断言。
+
+## 9. 有界实施单元
+
+### 工作单元 1：路径级消费聚合
+
+- 将 read target map key 收敛为 normalized path；
+- 完成 role 与所有集合字段的无损 merge；
+- 修复 provenance-only 去重和 required path 单次检查；
+- 完成 HC-01 至 HC-09。
+
+### 工作单元 2：Coverage 单一解释器
+
+- 抽取共享 parser/selector；
+- 两个消费者改用共享结果；
+- 保留合法 v1/v2 兼容并收紧非法 profile；
+- 完成 HC-10 至 HC-13。
+
+### 工作单元 3：版本事实、回归与本地采用
+
+- 更新 package、migration manifest、必要文档与测试版本事实到 `1.9.1`；
+- 保持公开安装/发布声明与实际 registry 状态一致；
+- 完成 HC-14、全部回归和第 6 节 self-host adoption；
+- 同步实现事实并恢复 clean。
+
+## 10. 预计实现文件边界
+
+允许范围：
+
+- `src/project-context/context-bundle.mjs`；
+- `src/project-context/adaptive-context.mjs`；
+- 一个共享 coverage profile helper；
+- `test/project-context/task-context-consumption.test.mjs`、必要 coverage 测试及 release metadata 测试；
+- `package.json`、`migration-manifest.json` 和现有包白名单/版本元数据；
+- README、操作手册、本文、`PROJECT_STATE.json`、`RTK.md`；
+- 通过正式治理命令完成的本仓库 Contract/source/coverage/consumption 同步。
+
+明确禁止：
+
+- 修改产品宪法；
+- Context Bundle schema 2、Contract schema 4、coverage profile v3；
+- 新 CLI、自动读取、自动批准、自动迁移或语义完整性声明；
+- 借补丁重构 discovery、scope compiler、renderer、source digest 或其他无关模块；
+- 访问或修改真实目标项目；
+- Provider、Agent Runtime、业务代码写入；
+- 依赖安装、Git、网络、打包或发布。
+
+## 11. 外部验收门
+
+本地 `1.9.1` 实现、HC-01 至 HC-14、全部回归及 self-host adoption 刚完成、尚未取得外部复验授权时，只允许声明：
+
+```text
+1.9.1-local-implementation-complete;
+two-project-real-host-revalidation-not-authorized;
+release-not-authorized
+```
+
+随后必须获得独立授权，才可在两个真实项目中使用同一冻结候选复验：未知路径 locate、跨页面/组件/API/store 多路径、registered source 与 task target 重合、typed read targets、coverage gap、最小读取和结束 clean。该授权及结果现已记录于第 14 节；Provider、打包与发布仍是更后的独立授权门。
+
+## 12. 已消费的实现授权
+
+本轮实现授权文本为：
+
+> 按 `docs/31-TASK-CONTEXT-INTEGRITY-REPAIR-DESIGN.md` 冻结合同实现 `1.9.1`，范围仅限本地产品代码、共享 coverage parser、版本元数据、文档、自托管 Contract 采用、HC-01 至 HC-14、TC-01 至 TC-16 及全部回归；保护现有工作，不访问真实目标项目，不调用 Provider，不执行依赖安装、Git、网络、打包或发布。完成后同步实现事实并停止，等待两个项目使用 `1.9.1` 冻结候选进行真实 Host 复验的独立授权。
+
+该授权已执行并消费完毕。未来不得据此继续访问真实项目、调用 Provider、执行 Git/网络/打包/发布，或扩大产品实现范围。
+
+## 13. 本地实现事实
+
+`2026-09-22` 已完成以下闭环：
+
+- package/runtime/migration/schema 版本事实更新为 `1.9.1`，公开 registry 基线仍如实保持 `1.8.0`；
+- read target 按规范化 path 唯一聚合，完整保留 role、item/source/reason 并集与所有 JSON Pointer；
+- `src/project-context/coverage-profile.mjs` 成为 Context Bundle 与 Coverage Audit 的唯一严格 parser/selector；
+- HC-01 至 HC-14、TC-01 至 TC-16 与全部回归共 `237/237` 通过；
+- 自托管 Contract 已升级为 schema 3，采用了显式 consumption、`outside-owned-ai-entry` 与 coverage profile v2；
+- Context Bundle schema 1、Coverage Audit schema 2、Capabilities / Exchange Protocol 9、Initialization Instruction schema 2 和 AI Entry renderer 5 均保持不变；
+- 未新增持久 store，未访问真实目标项目，未调用 Provider，未执行依赖安装、Git、网络、打包或发布。
+
+本地实现完成时的唯一下一步是等待独立授权，在两个真实项目中使用同一 `1.9.1` 冻结候选执行真实 Host 复验；该门已在第 14 节完成。
+
+## 14. 两项目真实 Host 复验事实
+
+`2026-09-22`，用户单独授权两个真实项目使用同一 `1.9.1` 冻结候选进行真实 Host 复验。两项目共同挂载只读候选快照 `sha256:be7d15fa66e289c6a7cf7e482649a2b5a6ded4d573c270cd2fa2d3ac883d78ee`，未运行 package manager，未修改 package manifest 或 lockfile。
+
+- `dtg-tmc-mobile` 从未知路径任务先执行 locate，再收敛到 `pages/trip/index.vue`、`pages/trip/components/non-whitelist-confirm.vue`、`common/config/api.order.js` 与 `pages.json`；`pages.json` 同时是 task target 与 registered source，最终只有一个规范化 required read target，item/source/reason 并集完整；
+- `dtg-tmc-pc` 收敛到机票页面、确认弹窗、客规弹窗、路由与 API 配置六条最小路径；实际链路未使用 Vuex/store，因此没有为满足验收标签虚构 store 路径；另以 `src/main.js` 验证 task/source 同路径只生成一个规范化 read target；
+- 两个 Host 均按 required/conditional/provenance-only 做最小读取，没有重复读取 provenance-only；两项目 registered source 均为 file locator，因此 JSON Pointer 的真实项目重合验证不适用，指针无损语义继续由 HC 自动化覆盖；
+- 两个目标 Contract 均报告 `registration-coverage-not-declared`；mobile 的 `common/config/api.order.js` 另为 `project-scope-only`。这些属于目标 Contract 数据 gap，不是本轮已证产品缺陷；
+- 两项目结束时均为 `health=clean`、`contractReadiness=contract-ready`、renderer 5、0 findings、0 pending items；未调用 Provider，未执行 Git、网络、构建、项目测试、业务代码修改、打包或发布。
+
+本轮未确认新的产品缺陷。后端 `101005` payload 与 `type=2` 的运行时业务语义未做接口实测，保留为未证风险，不进入产品修补。真实 Host 复验授权已消费；当前唯一下一步是等待对 `1.9.1` 打包与发布的独立决定和授权。
+
+## 15. 复验后自托管 coverage 治理收口
+
+`2026-09-23` 的只读审计发现：普通 `status` 为 `clean/contract-ready`，但自托管 `coverage-audit` 因 `templates` 域的 `unresolved` disposition 返回 `registrationCoverage=unresolved`。该目录当前为空，没有可登记的模板文件；这属于已批准 coverage profile 的待裁定域，不是产品内核缺陷。
+
+本次单独授权的治理收口将 `templates` 改为 `dynamic-investigation`：未来若出现模板内容，Host 仍须按具体任务调查、判断是否需要登记到 Contract；不把空目录宣称为 `contract-covered`，也不以 `excluded-approved` 隐藏未来内容。coverage 的保证继续仅限已声明域，且不代表全仓语义完整。页首阶段事实同步为两项目复验已完成；打包与发布仍是独立授权门。

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
 
@@ -83,7 +84,7 @@ 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.

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,23 @@
 
 记录 `2026-09-14` 关于“让团队共同拥有同一份项目上下文”的产品意义、真实项目应用重点，以及 Stateful Agent、Persistent KV 和增量上下文的远期讨论方向。该文档仅供团队查看和继续讨论，不是冻结设计、路线或实现授权。
 
-## 已冻结、待实现设计
+## 当前实现基线
+
+[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 已使用同一冻结源码候选在 `dtg-tmc-mobile` 与 `dtg-tmc-pc` 完成只读复验，未确认产品缺陷。公开 schema、Exchange Protocol 9 与 AI Entry renderer 5 未升级；发布状态由动态项目状态记录，不由本索引授权。
+
+## 已归档的前一本地实现基线
+
+[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.9.1` 本地冻结候选；公开 registry 基线仍为 `1.8.0`
 >
 > 适用对象：项目维护者、开发者、使用 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 frontend-project-context@1.9.1
 ```
 
 建议在 `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。
+`1.9.1` 本地候选的 AI Entry renderer 5 固定离线项目本地 CLI 入口：路径未知时先运行 `context --locate --task ... --json`，定位后用完整路径集合重新运行 targeted Context；路径已知时直接使用多路径 `--path`。Host 报告 item IDs、scopeCoverage、required/conditional read targets、provenance-only sources 与 gaps。既有 renderer 1/2/3/4 不会被静默覆盖，必须明确授权 republish。
 
 ### 4.3 全新初始化不是普通升级
 

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.9.1"
   }
 }