frontend-project-context 1.0.0

package/docs/05-ACCEPTANCE-CONTRACT.md

@@ -0,0 +1,348 @@
+# 05 — v1 验收合同
+
+> 权威说明：本文记录核心引擎验收；完整 v1 完成定义以 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 第 7 节为准。
+
+> 状态：`A-01 through A-45 plus B0-01/B0-02 and CLI passed locally; 49 tests total on 2026-09-08`
+
+## 1. 验收原则
+
+所有程序验收使用系统临时目录中的前端项目 fixture，不安装依赖、不访问网络、不调用 Provider、不执行 Git 命令，也不修改真实业务源码。
+
+测试只验证 [04-PROGRAM-DESIGN.md](./04-PROGRAM-DESIGN.md)，不得通过失败案例现场扩展产品边界。
+
+## 2. 必须通过的程序场景
+
+### A-01 空项目初始化
+
+- 没有 `--write` 时只显示 preview。
+- 显式 `--write` 后只创建 `.project-context/` 三个文件。
+- 再次初始化停止，不覆盖已有内容。
+
+### A-02 确定性发现
+
+- fixture 包含 package、TypeScript、lint、test 和 Agent 规则文件。
+- 两次 discover 输出字节等价。
+- 输出只有 proposal，没有 approved policy。
+- 每条 proposal 都能追溯到真实来源。
+- 一级非隐藏目录生成带 path identity 来源的 scoped fact。
+- 单行规则别名只有在最终落到具体规则文件时去重；循环和未解析别名不丢失。
+
+### A-03 人工批准边界
+
+- approve 只接纳命令明确列出的 ID。
+- approved item 包含人、时间和来源。
+- 未批准 proposal 不进入合同和 Context Bundle。
+- 来源已经变化时 approve 停止。
+
+### A-04 合同 schema
+
+- 未知字段、重复 ID、非法枚举、绝对路径、`..` 和项目外 realpath 全部失败。
+- `path` source 只能描述项目内文件或目录身份，不接受 pointer 或外部 reference。
+- JSON Pointer 拒绝非法 `~` escape，只能读取 JSON 自身成员，不能穿透对象原型或读取数组 `length`。
+- approved item 缺少 approval 时失败。
+- 错误不修改任何文件。
+
+### A-05 目录作用域
+
+- project、path-prefix 和 file scope 能产生正确有效集合。
+- sibling 目录规则不会泄漏。
+- 多个目标路径的 bundle 能明确区分各自适用规则。
+
+### A-06 显式覆盖
+
+- 子目录 item 引用上层 item ID 时可以覆盖。
+- 没有 `overrides` 的不同 value 被报告为冲突。
+- 指向不存在、已废弃或更窄 scope 的 override 失败。
+
+### A-07 稳定 Context Bundle
+
+- 同一规范化合同和路径产生相同 Markdown。
+- bundle 包含 item ID、source ID、作用域和任务原文。
+- task 原文不写入合同或 lock。
+
+### A-08 Source drift
+
+- 已确认文件、JSON pointer 或 path digest 改变后 `check` 报告 `source-changed`。
+- path identity source 下的普通目录内容变化不产生 drift，路径删除或文件/目录类型变化产生 finding。
+- 来源删除后报告 `source-missing`。
+- check 不自动接受新值或更新 digest。
+
+### A-09 安全 projection 写入
+
+- preview 不写文件。
+- 显式写入可创建受管文件。
+- 未受管的已有 `AGENTS.md` 不能被覆盖。
+- 根规则存在时可在无冲突的子目录创建受管 `AGENTS.md`，且根文件保持不变。
+- 人工修改过的受管 projection 不能被覆盖。
+- 完整未修改的受管 projection 可以原子更新。
+
+### A-10 Projection drift
+
+- 合同改变但 projection 未发布时报告 `projection-stale`。
+- 文件内容与 lock 不同报告 ownership conflict。
+- 删除 projection 后报告缺失，不自动重建。
+
+### A-11 Ruler 边界
+
+- `ruler` target 只生成普通 Markdown 源。
+- 程序不安装、不调用、不检测 Ruler 可执行文件。
+- 源文件可由 Ruler 递归读取，但专用 Agent 输出不由本程序生成。
+
+### A-12 零 Runtime 与零 Git
+
+- 静态扫描不存在 Provider SDK、网络请求、`child_process` 和 Git 调用。
+- 测试记录所有文件写入，仅合同目录和显式 projection path 可变。
+- fixture 中的业务源码字节保持不变。
+
+### A-13 中断与失败
+
+- JSON 损坏、路径越界、写权限失败和原子 rename 失败都返回明确错误。
+- 临时文件被限定并清理。
+- 合同和既有 projection 不出现部分写入。
+- projection 使用 lock-first 提交；写入和 lock 恢复连续失败时，`check` 必须报告 missing 或 ownership conflict。
+- 不 retry、不 rollback 业务代码、不调用外部工具。
+
+### A-14 多消费者一致性
+
+- 同一合同生成通用 Context Bundle 与 AGENTS/Ruler 投影。
+- 三种输出包含相同 approved item ID 和语义内容。
+- 消费者格式差异不产生第二份规则真源。
+
+### A-15 通用来源登记
+
+- register 默认 preview，显式写入只更新 contract 和必要的 source lock。
+- file、path、human-decision 主路径及现有 json-pointer、external-reference schema 均可表达。
+- digest 由程序读取；越界、symlink escape、重复 ID/locator 和无效参数失败。
+- 未被 approved item 使用的来源不进入 bundle。
+
+### A-16 四类 item 与三类 scope authoring
+
+- propose 无需手改 JSON 即可创建 fact、policy、reference、validation-description。
+- project、path-prefix、file scope、typed JSON value、overrides 和 verification 可准确表达。
+- 输出保持 schema 1 和 proposed 状态；安全 proposal output 不覆盖 store 或已有不同内容。
+
+### A-17 显式批准与失败封闭
+
+- approve 仍只批准明确 ID，不存在隐式批准快捷方式。
+- stale source、invalid override、contract conflict 和 contract/source lock 快照变化在写前失败。
+- 任一 `verification-*` finding 都阻断 context 和 publish，不能只在 check 中显示后继续编译。
+- 双文件第二步失败恢复 source lock；恢复失败留下的状态能被 check 阻断。
+- 原 discover proposal approval 保持兼容。
+
+### A-18 完整 Context Bundle
+
+- 四类 approved item 的 statement 和 canonical value 均进入 Context Bundle 与投影。
+- item ID、scope、source provenance 和可选 overrides 保持可追溯。
+- proposed/deprecated 不进入，sibling scope 不泄漏，canonical value 输出确定。
+
+### A-19 Renderer 迁移兼容
+
+- schema 1 contract/proposal/lock 无需迁移。
+- renderer 1 受管投影可读并报告 stale，只有显式 publish 且所有权完整时才能升级为 renderer 2。
+- 被人工修改的旧投影不能借升级覆盖。
+
+### A-20 独立 CLI 闭环
+
+- 在临时 fixture 完成 init → register → propose → approve → context → publish → check。
+- 同一闭环覆盖 file/path/human source、四类 item 和三类 scope。
+- 全程离线、零 Provider、零 shell/Git、零业务源码修改。
+- 每个命令拒绝属于其他命令的已知参数，不能静默忽略。
+
+## 3. 实现完成 Gate
+
+只有同时满足以下条件，状态才能变为 `implemented-local`：
+
+1. A-01 至 A-20 全部通过。
+2. README、RTK、PROJECT_STATE、CLI help 和源码边界一致。
+3. 默认入口不再指向历史 Harness。
+4. 没有第三方依赖、Provider、网络、shell 或 Git 操作。
+5. 程序不能修改业务代码。
+6. 历史 candidate/validation/decision 模型没有进入新 schema。
+
+### 3.1 本地实现结果
+
+2026-09-04 的本地实现已满足以上 Gate：
+
+- 新入口为 `bin/project-context.mjs`，核心模块位于 `src/project-context/`；
+- 默认 `npm test` 只运行 `test/project-context/` 中的现行验收，A-01 至 A-20 和 CLI 端到端测试全部通过；
+- 默认 `npm run check` 只检查现行实现；
+- 2026-09-04 新增 2 项 B0 通用回归和 6 项 authoring closure 验收，该阶段总计 24 项测试通过；
+- `0.6.1` 把审查发现的 verification 阻断、projection 失败封闭、RFC 6901 和命令参数合同回归并入现有 A-04、A-13、A-17 与 CLI 测试，测试总数保持 24；
+- 2026-09-02 已从工作树删除历史 Harness 源码、入口、测试、任务模板及其 prototype 脚本；历史结论仍可通过文档和 Git 历史追溯；
+- 没有新增第三方依赖、Provider、网络、shell 或 Git 调用。
+
+## 4. 真实项目 Beta
+
+程序完成后，真实 Beta 分两层，不能混成自动循环。
+
+### B0 — 只读项目接入
+
+- 在一个真实前端项目运行 discover/check/context；
+- 不调用任何模型；
+- 开发者确认事实来源、冲突和 bundle 是否准确；
+- 不允许工具改业务代码。
+
+### B1 — 模型无关价值验证
+
+获得每次任务单独 Provider 授权后：
+
+- 选择一个自然出现的真实任务；
+- 将同一合同生成的 context 分别提供给两个成熟 Coding Agent，或与开发者原有方式进行对照；
+- Agent 在各自正常 Runtime 中工作，本产品不执行或观察其 loop；
+- 记录上下文准备时间、规则遗漏、错误假设和开发者修正次数。
+
+一次 Beta 结束后先记录结果，不自动修改合同、不调用第二轮模型修复产品。
+
+## 5. 产品价值 Gate
+
+独立程序只有在 B0/B1 证明以下至少一项时保留：
+
+- 自动发现减少了人工整理项目事实的时间；
+- provenance 帮助发现了手写规则无法识别的过期或冲突；
+- scope compiler 减少了无关上下文和错误规则泄漏；
+- 同一合同显著降低了不同 Agent 之间的项目理解差异。
+
+如果只使用 Ruler + 手写 AGENTS.md 达到同等结果，程序降级为模板、Skill 或 Ruler 配置，不继续扩展。
+
+## 6. 防止再次进入死循环
+
+真实 Beta 中出现问题时：
+
+1. 先完成或停止真实业务任务，由用户自己的 Coding Agent 工作流处理。
+2. 把问题记录为 `product-defect`、`unsupported` 或 `project-specific`。
+3. 不在同一业务任务中修改本程序并重新调用 Provider。
+4. 产品缺陷集中修复后重新跑 A-01 至 A-20。
+5. 新功能只有在两个独立项目场景重复出现时才进入下一版设计。
+
+## 7. `0.7.0` Knowledge Maintenance Closure 验收（已实现并通过）
+
+本节细化 [12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md](./12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md) 的阶段 1 Gate，并记录阶段 2 的本地通过结果。
+
+### A-21 来源审查只读与稳定
+
+- `review-source` 稳定分类 changed/unchanged/missing/unreadable，输出旧/新 digest、direct/override-dependent/fallback item 和 projection 集合。
+- 同一状态两次 JSON 输出等价；列表稳定排序；不输出来源正文。
+- 命令前后 contract、两个 lock、proposal、projection 和业务文件 bytes 全部相同。
+- human-decision/external-reference 返回 `source-review-unsupported` 和退出码 2。
+
+### A-22 显式接受与 TOCTOU
+
+- preview 零写入；没有本命令 `--write` 不能更新任何 digest 或 item status。
+- 缺失/错误 `--expected-digest`、来源在 review 后再次变化、`--affected-items` 缺失/多余/过期均退出 1 且零写入。
+- 只有准确 digest 与完整影响集同时确认时，contract source digest 和 source lock 才更新为相同值。
+- missing/unreadable/unchanged/unverifiable source 不能被接受。
+
+### A-23 影响集与 approval 失效
+
+- direct set 同时覆盖 `item.sources` 与 `verification.source`。
+- reverse override dependents 递归进入影响集；无关 subject、sibling scope、proposed/deprecated item 不误入。
+- 受影响 item 所覆盖的上层 approved item 作为 fallback 揭示但不被误撤销。
+- 接受后完整影响集统一改为 proposed 并移除 approval；`check` 报告 `item-approval-pending`，context/publish 均阻断。
+
+### A-24 同 ID revision 与重新批准
+
+- 四类 item、三类 scope、typed value、sources、overrides 和 verification 均可完整 replacement，无需手改 JSON。
+- ID/kind/subject 不能改变；deprecated 不能复活；current item digest 变化时写入失败。
+- `revise --write` 只产生 pending item，绝不批准；pending 不进入 bundle。
+- `approve --pending` 只批准明确 IDs，可在一个 next contract 中共同批准 override 基项与依赖项，并重新写入 by/at/rationale。
+
+### A-25 显式 deprecation
+
+- approved 或 proposed item 可 preview；`--write` 要求匹配 item digest、`--by` 和非空 `--rationale`。
+- deprecated item 保留 ID、内容、scope、sources、overrides，并以 approval 记录本次废弃责任与理由。
+- 仍有 approved override dependent 时预检失败；处理后 deprecated 不进入 Context Bundle、AGENTS 或 Ruler。
+
+### A-26 store 并发与失败恢复
+
+- contract/source/projection lock、目标 source/item/projection file 任一依赖快照变化时，相关写命令在首次写前失败。
+- accept 的 source-lock-first、publish 的 projection-lock-first 顺序保持不变。
+- 模拟第二步失败时仅在 lock 仍是本命令 next value 时恢复；恢复失败或观察到并发值时不得覆盖它。
+- 所有失败最终由 check 报告 source mismatch、pending、projection missing/stale/ownership conflict，不能出现静默可编译的部分批准。
+
+### A-27 projection stale 与所有权
+
+- accept/revise/deprecate/pending approval 都不写 projection lock 或 projection 文件。
+- 任一 contract digest 变化后旧 projection 确定 stale；显式 owned `publish --write` 后恢复一致。
+- 目标文件人工变化、marker/lock/content digest 不一致仍退出 3，维护命令不能绕过所有权。
+
+### A-28 独立 CLI 维护闭环
+
+- 仅依据 README/help，在临时 fixture 完成 source change → review → accept → revise/reapprove 与 deprecate → stale check → publish → clean check。
+- 全程不直接编辑三个 store JSON；每次写入都来自当前命令自己的 `--write`。
+- JSON 与人类输出足以取得后续 digest、item ID 和安全下一步。
+
+### A-29 `0.6.1` 兼容
+
+- schema 1 contract/proposal/source lock/projection lock 原样可读，无读取时迁移或自动写入。
+- register/propose/discover/`approve --proposal`/context/publish/check 合同保持兼容。
+- renderer 1/2 兼容与显式升级规则不变，0.7.0 不提升 renderer。
+- 维护完成后的数据仍符合 schema 1；维护中降级风险以 pending finding 和文档明确说明。
+
+### A-30 永久边界与全量回归
+
+- A-01 至 A-20、B0-01、B0-02 和现有 CLI 测试全部继续通过，不删除、不跳过、不弱化。
+- 静态扫描与写入记录证明零 Provider、网络、dependency install、child process、shell/Git 管理和业务代码修改。
+- 只使用临时 fixture，不访问真实项目；所有新旧命令拒绝不属于自身 allowlist 的参数。
+
+`0.7.0` 实现 Gate 已满足：A-01 至 A-30、B0-01/B0-02 和 CLI 共 34 项全部通过；README/help/04/05/08/12/RTK/PROJECT_STATE 已与真实实现同步。测试只使用临时 fixture，没有访问真实业务项目。
+
+## 8. `0.8.0` Read-only Governance Dashboard 验收（已实现并通过）
+
+完整行为以 [13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md](./13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md) 为准。以下编号和边界已经实现并通过：
+
+- **A-31**：Dashboard View Model 确定性、统计准确、全程只读；
+- **A-32**：人类总览明确区分 health、knowledge coverage 和 projection coverage；
+- **A-33**：四类 item、approval、scope 和 provenance 可读，source 正文不可见；
+- **A-34**：来源状态和 direct/verification/override/fallback/projection 影响集准确；
+- **A-35**：已知路径 scope explorer 与现有 compiler 一致，不复制浏览器编译器；
+- **A-36**：finding 完整保留，dashboard 退出码与 check 的 0/1/3 一致；
+- **A-37**：HTML 注入安全、CSP hash 与真实 inline 内容一致、零外部请求、键盘/对比度/响应式通过；页面没有 transition 或 animation，因此不需要伪造 reduced-motion override；
+- **A-38**：只读 CLI allowlist、store schema 1、renderer 1/2 读取兼容、Dashboard View Model schema 2、已有 34 项回归和永久边界全部保持。
+
+实现 Gate 已满足：A-01 至 A-38、B0-01/B0-02 和 CLI 共 42 项全部通过；本仓库真实 Contract 的 JSON/HTML 输出为 18 sources、18 approved items、0 projections、0 findings，能够回答设计第 1 节六个问题。验证未访问真实业务项目、Provider 或网络，也未产生项目持久写入。
+
+## 9. `0.9.0` 加固验收（已合并到既有编号）
+
+- A-03 同时证明 proposal approval 遇到既有 ID 必须失败并指向 `revise`；
+- A-04 覆盖 verification kind/字段组合和非 JSON Contract value；
+- A-07 覆盖多路径同知识集合并、默认中文、显式英文与 `all`；
+- A-09 证明 symlink 指向项目外时不会先在外部创建缺失父目录；
+- A-19/A-29 证明 renderer 1/2 可读且 stale，并可显式升级为 renderer 3；
+- CLI 验证紧凑 approval receipt 与 renderer 3；A-31/A-33/A-37/A-38 验证 View Model schema 2、无嵌入模型、无预计算搜索副本和真实 CSP hash。
+
+这些断言强化原有验收语义，测试总数仍为 42；不通过增加编号来制造虚假的能力增长。
+
+## 10. 团队维护验收结果
+
+2026-09-08 经单独授权执行阶段 3。验收只使用隔离临时 fixture，以 README/help 和公开 CLI 完成一次来源变化 → review → accept → revise → deprecate → pending reapproval → stale check → owned republish → clean check。结果证明：旧批准会按精确影响集失效，废弃项不会进入新投影，业务源码保持不变，最终 `check` 为 clean。
+
+随后 `npm run check` 全量 42/42 通过；本仓库自托管真源复核为 18 sources、18 approved items、0 proposed、0 deprecated、0 findings。该验收没有访问真实业务项目、网络或 Provider，没有安装依赖，也没有执行 Git 或发布操作。
+
+## 11. `1.0.0` 发布准备验收
+
+### A-39 发布候选边界
+
+- package name/version 固定为 `frontend-project-context@1.0.0`，bin 为 `project-context`，Node.js 下限为 18，第三方 runtime dependency 为零；
+- package metadata 声明 Apache-2.0，发布包包含官方 LICENSE 和 `Copyright 2026 Fushan` NOTICE；
+- `files` 白名单包含保持文档链接完整所需的 PROJECT_STATE/RTK 和许可证文件，但不包含测试、自托管 `.project-context/` 或本地生成物；
+- `prepack` 必须运行全量检查，bin 保持可执行；
+- changelog、升级说明、最小 consumer 配置与只读 CI 模板同时存在，CI 不包含 `--write`、自动批准或发布命令；
+- 本地 `npm pack` 清单与白名单一致，解包后 CLI help、临时项目 init/check 和确定性输出可运行；
+- 未获发布授权时 `private: true` 必须保持；获得公开发布授权后，A-39 必须反向验证 `private: false`、官方 npm registry 和 public access，防止误发到机器默认 registry。
+
+A-39 是发布工件一致性验证，不扩展 Project Contract、CLI、schema、source kind、projection target 或产品边界。2026-09-08 的公开发布授权已把安全断言切换为 `private: false`、`https://registry.npmjs.org/` 和 public access；npm 身份认证仍由发布者本人完成。
+
+## 12. Source Lifecycle Closure 验收（已实现并通过）
+
+[15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md](./15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md) 冻结的 A-40 至 A-45 已按单独实现授权落地：
+
+- **A-40** missing source 的替代、item revision/reapproval、旧 source 废弃与 clean check 闭环；
+- **A-41** source deprecation preview、baseline、署名和理由权限；
+- **A-42** proposed/approved 引用阻断与 deprecated provenance 保留；
+- **A-43** Contract schema 1/2 延迟兼容迁移；
+- **A-44** checker、dashboard、context、publish 对 lifecycle 的一致语义；
+- **A-45** 多 store 原子性、全量回归与永久边界。
+
+实现结果证明：missing active source 可经 register → revise/reapprove → deprecate-source → republish 恢复 clean；preview、source object baseline、署名、理由、引用阻断、schema 1 延迟迁移、deprecated provenance、checker/dashboard/context/publish 一致性和 lock-first 失败恢复均按冻结合同工作。测试只使用隔离临时 fixture，没有访问真实业务项目、Provider、网络、Git 或依赖安装，也没有修改业务源码。
+
+当前通过事实为 A-01 至 A-45、B0-01/B0-02 和 CLI 共 49 项；A-40 至 A-45 没有删除、跳过或弱化既有验收。

package/docs/06-HISTORICAL-PROTOTYPE.md

@@ -0,0 +1,55 @@
+# 06 — 历史任务执行 Harness
+
+> 状态：`Historical evidence; rejected as current product core`
+
+## 1. 归档方式
+
+2026-09-02，以下实验代码、测试和模板已从工作树删除：
+
+- `bin/frontend-harness.mjs`
+- `src/first-slice.mjs`
+- `test/first-slice.test.mjs`
+- `bin/project-harness.mjs`
+- `src/project-harness.mjs`
+- `test/project-harness.test.mjs`
+- `templates/task.json`
+
+这些内容仍可通过 Git 历史追溯，但不再参与安装、检查、测试或发布。它们不得恢复为产品入口、用于新的真实任务或作为当前程序设计依据。
+
+## 2. 原型验证过的局部事实
+
+- 可以为候选目录计算内容身份；
+- 可以检测 scope 外变化；
+- 可以识别验证后内容变化造成的 stale；
+- 可以限制单次 Provider turn 和 candidate 数量；
+- Runtime 完成、验证、人工决定和交付是不同事实。
+
+这些结论只对“任务执行与候选交付系统”有意义。当前产品不拥有这些对象，因此不迁移对应 schema 和流程。
+
+## 3. 为什么拒绝为产品核心
+
+### 3.1 它包装了成熟 Coding Agent 已经拥有的能力
+
+Provider、Agent loop、工具、sandbox、approval、session 和 code editing 都由现有 Runtime 更好地提供。
+
+### 3.2 它没有解决最初的稳定问题
+
+真实开发者最需要复用的是项目事实、设计原则、代码模式和验证规则，而旧 Harness 把主要复杂度投入 candidate、workspace、validation record 和 decision lifecycle。
+
+### 3.3 隔离与验证产生无界兼容工作
+
+复制项目、第二层 sandbox、父级配置、ignored 文件、monorepo、symlink 和工具版本都会形成新的兼容分支，最终进入“验证失败—修 Harness—重试”的循环。
+
+### 3.4 它错误进入 Git 和交付边界
+
+分支、commit、merge、push 和交付属于用户现有开发流程。把这些纳入产品会增加触碰错误分支和污染真实工作的风险。
+
+## 4. 当前处理决定
+
+- 旧原型源码不再留在工作树；Git 历史和本文保留其反例与局部结论；
+- 不继续修复 Runtime、candidate、validator sandbox、session 或 delivery；
+- 现行程序只使用 `bin/project-context.mjs` 入口和 `src/project-context/` 命名空间；
+- 新 schema 不导入 Task、Run、Revision、Evidence、Decision 或 Delivery；
+- 不保留 prototype npm 脚本、可执行入口或任务模板。
+
+历史原型最重要的贡献，是证明了当前产品应该回到 `Project Contract + Context Compiler`，而不是继续成为任务执行器。

package/docs/07-REAL-TASK-EVIDENCE.md

@@ -0,0 +1,52 @@
+# 07 — 首个真实任务证据
+
+> 状态：`Historical evidence; not a workflow or authorization source`
+
+## 1. 任务概述
+
+首个真实任务在前端业务仓库中查找多个相似 flight-model 组件，提取用户可见中文，生成一致的 i18n key 和英文翻译，并把源码替换为带中文 fallback 的 `$t` 调用。
+
+开发者负责把 key、中文和英文录入语言库。任务本身不要求工具管理 Git 或形成独立候选交付系统。
+
+## 2. AI 带来的真实价值
+
+成熟 Coding Agent 在一次 Provider turn 中完成了跨目录查找、去重、命名、翻译和批量替换，覆盖六个相关组件及 32 个初始去重 key。
+
+这说明 AI 的直接价值是：快速理解代码范围并完成重复但需要语义判断的开发工作。
+
+它不说明本产品应当接管 Provider、candidate、validator、decision 或 Git。
+
+## 3. 旧 Harness 暴露的问题
+
+1. source 与 candidate manifest 排序不一致，产生错误 subject 判断。
+2. Validator 隔离环境阻止 Prettier 向父目录发现配置，正确代码被误判。
+3. candidate cleanup 删除唯一完整业务结果，需要从有限证据恢复。
+4. 为了处理验证故障又引入 ValidationIncident、重试上限和更多状态。
+5. 工作范围扩展到业务分支、commit、merge 和 push，增加了触碰错误目标分支的严重风险。
+
+这些问题共同证明：用中间层重新包装真实开发执行会持续追赶环境差异，容易让简单任务变成基础设施修复循环。
+
+## 4. 与当前产品核心真正相关的发现
+
+任务也暴露了应该长期沉淀的项目知识：
+
+- 哪些目录包含同类 flight-model 组件；
+- 用户可见中文采用怎样的 i18n 调用形式；
+- key 如何命名和复用；
+- 中文 fallback 是否必须保留；
+- 哪些命令是项目认可的格式和业务检查入口；
+- 哪些组件可以作为后续任务的参考实现。
+
+这些内容应被表达为有来源、有人批准、带 scope 的 Contract Item，而不是埋在一次聊天、candidate session 或历史 commit 中。
+
+## 5. 当前架构结论
+
+首个真实任务支持以下结论：
+
+- Coding Agent 完成业务工作，本产品不应复制 Agent Runtime；
+- 项目长期价值来自可复用规则和参考来源，而不是一次任务的内部状态；
+- 真实业务仓库、工作区和 Git 生命周期必须完全留给开发者；
+- 产品验证应关注“同一 Project Contract 是否帮助不同 Agent 正确理解项目”；
+- 任何真实任务发现的问题都应在任务结束后集中分析，不能启动无界修复循环。
+
+该任务到此只作为历史样本保留。它不授权 Provider、依赖安装、Git 操作或新的真实项目执行。

package/docs/08-INSTALLATION-AND-DISTRIBUTION.md

@@ -0,0 +1,199 @@
+# 安装与分发决策
+
+> 权威说明：本文是支持性设计文档；当前唯一规范真源是 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md)。
+
+状态：`frontend-project-context@1.0.0` 公开 npm 发布已授权、完成配置并验证发布者 CLI 身份
+适用项目：`dtg-frontend-delivery-agent`  
+本文只确定产品如何交付、安装、共享、升级和验证，不授权实现。
+
+## 1. 决策摘要
+
+`dtg-frontend-delivery-agent` 不以“一个需要所有成员学习的 CLI”作为产品定义，而以“给现有项目启用 DTG 项目上下文能力”作为用户认知。
+
+首选交付组合为：
+
+1. 以单一项目依赖承载模型无关的解析、编译和验证能力。
+2. 以一次性运行器提供首次初始化入口。
+3. 以项目内锁定版本作为正式使用方式，不依赖全局安装。
+4. 将可复现、可审查的 Agent 投影提交到仓库，使普通团队成员能够零安装消费。
+5. 由 CI 使用项目锁定版本执行只读漂移检查。
+6. Ruler、Rulesync、Skill 或目标 Agent 文件属于兼容出口或生成目标，不形成第二份规范真源。
+7. MCP、IDE 插件和桌面应用不是 v1 安装前提；是否引入留到核心闭环验证之后。
+
+## 2. 用户角色与安装责任
+
+### 2.1 项目维护者
+
+项目维护者负责初始化 DTG、维护 `Project Contract`、刷新投影和审查升级结果。其正式使用项目内依赖，版本进入现有包管理器的 lockfile。
+
+### 2.2 普通项目成员
+
+普通成员默认不需要单独安装 DTG。克隆项目后，其 AI 编程工具直接消费仓库内已批准、已生成的静态投影。
+
+只有在修改合同、重新生成投影、执行本地漂移检查时，成员才需要安装项目开发依赖或运行项目已有脚本。
+
+### 2.3 CI
+
+CI 安装项目锁定的依赖版本并执行只读检查。CI 不依赖机器上的全局 DTG，不静默修复文件，也不批准规则候选。
+
+## 3. 推荐安装路径
+
+### 3.1 首次初始化：一次性运行器
+
+面向 Node.js 前端项目，推荐支持包管理器的一次性运行方式，例如：
+
+```bash
+npx frontend-project-context@1.0.0 init --project . --id PROJECT_ID --name "Project Name"
+pnpm dlx frontend-project-context@1.0.0 init --project . --id PROJECT_ID --name "Project Name"
+bunx frontend-project-context@1.0.0 init --project . --id PROJECT_ID --name "Project Name"
+```
+
+以上命令只在包实际发布后可用；当前未访问 registry。包名冻结为 `frontend-project-context`，可执行文件名为 `project-context`，CLI 合同以 [04-PROGRAM-DESIGN.md](./04-PROGRAM-DESIGN.md) 为准。
+
+初始化入口只负责：
+
+- 识别当前项目并建立 DTG 配置；
+- 选择需要生成的通用 Markdown、AGENTS 或 Ruler 兼容出口；
+- 明确哪些文件由 DTG 管理、哪些文件由人维护；
+- 预览即将写入的文件；
+- 在用户明确确认后执行首次写入。
+
+初始化不得自动访问网络、安装额外依赖、批准规范候选或修改业务代码。
+
+### 3.2 正式安装：项目开发依赖
+
+初始化后，DTG 应作为项目开发依赖被锁定，例如：
+
+```bash
+pnpm add -D frontend-project-context@1.0.0
+```
+
+选择项目内安装而不是全局安装，原因是：
+
+- 团队成员和 CI 使用相同版本；
+- 不同项目可以独立升级；
+- 依赖升级及生成物变化可以通过 Git diff 审查；
+- 全局环境变化不会改变项目输出；
+- 回滚项目版本时可以同步回滚 DTG 行为。
+
+### 3.3 团队消费：静态投影随仓库分发
+
+由 DTG 从唯一的 `Project Contract` 生成、且体积可控的静态 Agent 投影，默认应提交到仓库。
+
+提交生成投影不意味着它们成为新的事实源。任何投影与合同不一致时，以合同为准，并由检查命令报告漂移。
+
+下列内容原则上不提交：
+
+- 本地扫描缓存和代码索引；
+- 用户凭据、Token 和个人路径；
+- 临时任务上下文；
+- 调试日志和运行状态；
+- 可由相同输入确定性重建、但体积较大的中间产物。
+
+## 4. 操作界面定位
+
+CLI 是初始化、编译、检查和 CI 自动化的参考操作界面，不是产品本体。
+
+未来命令能力可以围绕以下职责设计：
+
+- 初始化项目配置；
+- 预览和生成受管理投影；
+- 只读检查来源、合同与投影之间的漂移；
+- 解释某项规则的来源、作用域和最终生效原因；
+- 显式执行配置结构迁移。
+
+具体命令、参数和退出码已经在 [04-PROGRAM-DESIGN.md](./04-PROGRAM-DESIGN.md)、[12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md](./12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md)、[13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md](./13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md) 与 [15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md](./15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md) 冻结并实现。安装阶段不得通过 `postinstall` 静默修改项目文件。
+
+无需启动服务即可生成一次性的本地治理看板：
+
+```bash
+project-context dashboard --project . > project-context-dashboard.html
+project-context dashboard --project . --json
+```
+
+HTML/JSON 都只写 stdout；重定向到文件是调用者自己的 shell 行为。命令不创建 dashboard store、lock 或 projection，不打开浏览器，也不访问网络。
+
+## 5. Ruler、Skill 与多工具分发
+
+DTG 不重新实现完整的多工具适配矩阵。
+
+- `Project Contract` 始终是唯一规范真源。
+- v1 提供通用 Markdown、AGENTS 投影和 Ruler 兼容出口。
+- 当采用 Ruler 或 Rulesync 时，由其承担目标工具格式分发。
+- Skill 可以作为特定宿主的发布产物，但不能独立维护项目规则。
+- 目标 Agent 文件只能由明确生成操作更新，并应带有受管理标识。
+
+因此，用户安装的是 DTG 项目能力，而不是分别安装一套 DTG CLI、DTG Skill、DTG preset 和 DTG MCP。
+
+## 6. MCP、IDE 插件与桌面应用
+
+### 6.1 MCP
+
+MCP 适合未来按需提供大型或动态资料，但不作为 v1 安装前提，也不用于替代必须稳定生效的静态规则。
+
+若后续验证确有需要，应优先由同一项目包提供本地、项目级入口，避免形成独立版本和第二套安装生命周期。远程 MCP 会引入部署、认证、权限和可用性问题，应另行立项评估。
+
+### 6.2 IDE 插件
+
+IDE 插件可以在未来提供状态提示、冲突解释和可视化配置，但核心能力不得依赖某个 IDE。终端、CI 和其他编辑器必须拥有等价的基础能力。
+
+### 6.3 桌面应用
+
+桌面应用只在出现明确的跨项目治理、非开发角色参与或企业权限管理需求后考虑，不进入 v1。
+
+## 7. 升级与迁移原则
+
+升级必须是显式、可审查和可回滚的：
+
+1. 项目先更新 DTG 依赖版本。
+2. 用户显式运行迁移并查看配置变化。
+3. 用户显式重新生成投影。
+4. 用户运行只读检查。
+5. 依赖、配置与生成物变化一起进入代码审查。
+
+安装或升级过程不得：
+
+- 在 `postinstall` 中静默改写仓库；
+- 自动批准新的事实或规范；
+- 覆盖非 DTG 管理的文件；
+- 自动安装或配置外部 Agent；
+- 自动执行 Git commit、merge 或 push；
+- 因本机存在不同全局版本而产生不同结果。
+
+配置格式需要独立的 schema 版本。破坏性迁移必须明确说明影响，并在写入前提供预览。
+
+## 8. v1 安装闭环验收
+
+在考虑更重的交付形态前，v1 至少应证明：
+
+1. 维护者可以通过一次性入口为已有前端项目启用 DTG。
+2. 正式版本可以作为项目依赖锁定并由 CI 复现。
+3. 普通成员不安装全局工具也能消费已提交的 Agent 投影。
+4. 相同输入和相同版本能够产生确定性输出。
+5. 检查操作保持只读，并能发现合同与投影漂移。
+6. 所有写入均由明确命令触发，且只覆盖 DTG 管理的文件。
+7. 不支持的 Agent 可以通过通用 Markdown 或 Ruler 兼容出口接入。
+8. 离线情况下仍可完成核心解析、生成和检查闭环。
+
+## 9. 明确不采用的默认形态
+
+- 不以全局 CLI 作为团队默认安装方式。
+- 不要求所有成员分别安装 Skill 或 preset。
+- 不以 Docker 作为本地默认入口。
+- 不以 MCP Server 作为唯一或强制运行时。
+- 不以 IDE 插件作为核心能力前置条件。
+- 不在 v1 提供独立桌面应用。
+- 不将生成的 Agent 文件提升为第二份规范真源。
+
+## 10. `1.0.0` 发布准备结论
+
+本地 `1.0.0` 候选采用 `.project-context/`、`project-context` 可执行文件、Contract schema 1/2 reader、proposal/source lock/projection lock schema 1、renderer version 3、Dashboard View Model schema 3、受管 marker 和 04 所列退出码；authoring、knowledge maintenance、只读治理看板与 source lifecycle 均已闭合。发布层冻结如下：
+
+- 包名/版本为 `frontend-project-context@1.0.0`；公共 npm 查询确认该名称当前不存在，发布目标固定为 `https://registry.npmjs.org/`、public access；
+- 开源许可证为 Apache-2.0，版权主体为 `Copyright 2026 Fushan`；LICENSE 与 NOTICE 必须随包分发；
+- `.project-context/contract.json`、两个 lock 和团队明确采用的受管投影应提交；proposal、dashboard HTML、tarball、node_modules 与临时 Context 不提交；
+- CI 模板只安装锁定依赖并运行项目脚本 `context:check`，不得写入、接受、批准或发布；
+- v1 不提供本地 MCP、IDE 插件、桌面应用或独立二进制；Node.js 18+ 是正式运行前提；
+- `0.9.0 → 1.0.0` 不预先迁移 store；Contract schema 1 只在首次成功 `deprecate-source --write` 时延迟升为 2，两个 lock 保持 1；renderer 1/2 仍可读并仅在显式 owned publish 时升级为 3。
+
+详细工件、验证与发布步骤见 [14-FORMAL-RELEASE-READINESS.md](./14-FORMAL-RELEASE-READINESS.md)。用户已经授权 public npm、解除 private 安全闩、release commit/tag/push 和实际 publish；npmjs.org CLI 身份已经验证。