frontend-project-context 1.0.0

package/docs/04-PROGRAM-DESIGN.md

@@ -0,0 +1,428 @@
+# 04 — v1 程序设计
+
+> 权威说明：本文记录当前实现设计；如与 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 冲突，以产品宪法为准。
+
+> 状态：`1.0.0 Source Lifecycle Closure implemented locally; A-01 through A-45, B0 regressions, and CLI verified`
+>
+> 前置真源：[03-FINAL-SOLUTION.md](./03-FINAL-SOLUTION.md)。本文不得重新引入 Agent Runtime、任务执行、Git 生命周期或完整多工具适配矩阵。
+
+## 1. 程序形态
+
+v1 是一个本地 Node.js CLI 和一组无第三方依赖的可复用模块，工作名为 `project-context`。
+
+```text
+project-context init
+project-context register
+project-context propose
+project-context review-source
+project-context accept-source-change
+project-context revise
+project-context deprecate
+project-context discover
+project-context approve
+project-context context
+project-context publish
+project-context check
+```
+
+CLI 不提供 `run`、`generate-code`、`validate`、`retry`、`review-candidate`、`deliver` 或任何 Git 命令。
+
+## 2. 运行原则
+
+1. 默认命令只读并向 stdout 输出 JSON 或 Markdown。
+2. 任何文件写入都必须有命令自身的 `--write` 参数；历史授权不能复用。
+3. 写入只允许发生在目标项目内的 `.project-context/` 和用户明确指定的 projection path。
+4. 程序不启动子 shell、项目命令、Provider 或 Coding Agent。
+5. 程序不执行 Git 命令；当前分支、HEAD、index 和 remote 对本程序没有语义。
+6. 程序不下载或安装 Ruler、Rulesync 或其他依赖。
+
+## 3. 项目文件
+
+```text
+.project-context/
+  contract.json          # 唯一规范真源，人可审阅
+  sources.lock.json      # 已批准来源的最近确认指纹
+  projections.lock.json  # 受管生成文件的路径与内容指纹
+```
+
+提案默认只输出到 stdout。只有显式指定 `--output FILE --write` 时才保存；保存的 proposal 不是合同，也不会被 Context Compiler 使用。
+
+现行 schema 约定：
+
+- proposal 为 `{ schemaVersion, projectId, sources, items }`，所有 item 必须保持 `proposed`；
+- source lock 为 `{ schemaVersion, sources: [{ id, digest }] }`，只记录经过显式 register 或 approve 动作确认的本地来源；
+- projection lock 为 `{ schemaVersion, projections[] }`，每项记录输出路径、target、目标 scope paths、合同/bundle/内容 digest、item IDs 和 renderer version；
+- contract、proposal 和两个 lock 的 schema version 在 authoring closure 后仍为 1；新投影使用 renderer version 2，读取器兼容 renderer version 1 的受管投影并要求显式重发；
+- `contract.json` 中的本地 source digest 必须与 source lock 一致；lock 是上次人工批准时的确认点，`check` 不自动更新它。
+
+## 4. Project Contract schema
+
+### 4.1 顶层
+
+```json
+{
+  "schemaVersion": 1,
+  "project": {
+    "id": "tmc-mobile",
+    "name": "TMC Mobile",
+    "root": "."
+  },
+  "sources": [],
+  "items": []
+}
+```
+
+未知字段默认拒绝，防止错误拼写或未来语义悄然生效。
+
+### 4.2 Source
+
+```json
+{
+  "id": "source-package-json",
+  "kind": "file | path | json-pointer | human-decision | external-reference",
+  "path": "package.json",
+  "pointer": "/scripts/test",
+  "reference": null,
+  "digest": "sha256:..."
+}
+```
+
+约束：
+
+- `file` 和 `json-pointer` 的 path 必须是项目内相对路径。
+- `path` 只确认项目内路径及其文件/目录类型，不对目录内容做全量指纹；普通代码变化不会让目录存在事实漂移，路径删除或类型变化仍会被检查发现。
+- `json-pointer` 使用 RFC 6901 形式定位 JSON 值。
+- `human-decision` 记录人工规则来源，不伪造文件指纹。
+- `external-reference` 只保存 URL 或设计系统标识；v1 不访问网络验证。
+- `digest` 表示上次人工确认时的来源内容，不由 `check` 自动更新。
+
+### 4.3 Contract Item
+
+```json
+{
+  "id": "policy-i18n-visible-copy",
+  "kind": "policy",
+  "subject": "ui.visible-copy.i18n",
+  "value": "required",
+  "statement": "用户可见中文必须通过项目 i18n 调用并保留中文 fallback。",
+  "scope": {
+    "kind": "project | path-prefix | file",
+    "path": "pages/flight"
+  },
+  "status": "proposed | approved | deprecated",
+  "sources": ["source-i18n-guide"],
+  "overrides": [],
+  "approval": {
+    "by": "developer",
+    "at": "2026-08-31T00:00:00Z",
+    "rationale": "existing repository convention"
+  },
+  "verification": {
+    "kind": "none | file-exists | json-value | path-digest",
+    "source": "source-i18n-guide",
+    "expected": null
+  }
+}
+```
+
+约束：
+
+- ID 和 `subject` 使用稳定的小写 kebab/dot 命名。
+- `approved` item 必须包含 approval；CLI 只证明发生了显式批准动作，不提供身份认证。
+- `policy` 不能由 `discover` 直接创建为 approved。
+- `statement` 是给人和模型阅读的表达，`subject + value + scope + overrides` 提供确定性冲突检查。
+- `deprecated` item 不进入 Context Bundle，但保留审计原因。
+
+### 4.4 Scope
+
+v1 不实现 glob DSL，只支持：
+
+- `project`：整个项目；
+- `path-prefix`：某个规范化目录及其后代；
+- `file`：单个项目内文件。
+
+所有 path 使用 `/`、不得为绝对路径、不得包含 `..`，realpath 后不得越出项目根。
+
+## 5. 命令设计
+
+### 5.1 `init`
+
+```text
+project-context init --project PATH --id ID --name NAME --write
+```
+
+行为：
+
+- 验证目标目录；
+- 创建三个最小 JSON 文件；
+- 任一目标已存在时停止，不覆盖；
+- 不扫描、不生成规则、不修改 `AGENTS.md`。
+
+没有 `--write` 时只显示将创建的内容。
+
+### 5.2 `discover`
+
+```text
+project-context discover --project PATH [--output FILE --write]
+```
+
+只读发现器：
+
+- `package.json` 中的 package manager、scripts 和关键 framework/tool dependency；
+- TypeScript、lint、format、test、build 常见配置文件的存在；
+- 根和子目录中的 `AGENTS.md`、`CLAUDE.md`、`.kiro/steering/` 与 `.ruler/` 规则来源；
+- 用户在 contract 中显式登记的设计 token、组件文档和参考文件；
+- 一级非隐藏目录结构；每条目录 proposal 自身声明对应的 `path-prefix` scope。
+
+输出 `fact/reference proposal` 和来源，不输出 approved policy。发现器不递归解释全部源码，不使用 LLM 猜测架构。
+
+proposal/source/item ID 由稳定语义前缀、规范化路径或名称和短 SHA-256 后缀生成；遍历和输出稳定排序。扫描忽略 `.git`、`.project-context`、依赖与构建目录、symlink 以及带本产品 marker 的受管 projection，防止生成物反向成为来源。
+
+一级目录使用 `path` source 形成对应目录范围内的 proposed fact。只包含单行 `@另一个规则文件` 的 Agent 规则别名，在引用链最终落到另一个可发现的具体规则文件时去重；循环、越界或无法解析的别名仍保留，避免静默丢失来源。
+
+### 5.3 `register`
+
+```text
+project-context register --project PATH --id SOURCE_ID --kind KIND [--path PATH] [--pointer POINTER] [--reference TEXT] [--write]
+```
+
+通用登记现有 schema 的 file、path、json-pointer、human-decision 或 external-reference。本地来源由程序读取 digest；默认 preview，显式 `--write` 后只更新 contract 和必要的 source lock。登记不创建或批准 item，external reference 不触发网络。
+
+同 ID 的完全相同来源保持 unchanged；不同内容或重复 locator 停止。本地来源在提交前再次确认，所有 store 更新使用快照检查和失败封闭写入。
+
+### 5.4 `propose`
+
+```text
+project-context propose --project PATH --id ITEM_ID --kind KIND --subject SUBJECT
+  (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID...
+  --scope project|path-prefix|file [--scope-path PATH] [--overrides ITEM_ID...]
+  [--verification KIND] [--verification-source SOURCE_ID]
+  [--verification-expected-json JSON] [--output FILE --write]
+```
+
+从已登记来源构造一个 schema version 1 proposal。支持四类 item、三类 scope 和现有 overrides/verification；item 始终为 proposed，不含 approval。默认 stdout；显式保存时只能原子创建 `.project-context/` 内非 store 的 JSON，或确认已有字节相同，不能覆盖不同内容。
+
+### 5.5 `approve`
+
+```text
+project-context approve --project PATH --proposal FILE --ids ID... --by NAME --write
+```
+
+行为：
+
+- 读取 proposal 和当前 contract；
+- 展示将加入或更新的来源与 item；
+- 只批准用户明确列出的 ID；
+- 写入 approval、合同项和 source lock；
+- ID/subject 冲突、来源失效或合同在读取后变化时停止；
+- 写入前对 next contract 执行 override/conflict 预检，同时核对 contract/source lock 快照；
+- 不自动批准 proposal 中其余内容。
+
+人工也可以直接编辑 `contract.json`，但 `check` 仍要求 schema 和 approval 完整。
+
+### 5.6 `context`
+
+```text
+project-context context --project PATH --path RELATIVE_PATH... [--task TEXT] [--locale zh-CN|en|all]
+```
+
+行为：
+
+- 校验合同和来源状态；
+- 任一 `source-*`、`scope-*`、`verification-*` 或 contract conflict finding 都阻断 context/publish；
+- 选择对所有目标路径都适用或分别适用的 approved item；
+- 应用显式 overrides；
+- 冲突时失败，不生成可能误导模型的 bundle；
+- 输出稳定 Markdown，包含合同摘要、任务原文、适用 facts/policies/references/validation descriptions、每项 canonical approved value 和来源索引。
+
+`--task` 原样进入临时 bundle，只用于当前阅读，不参与长期合同和批准逻辑。
+
+### 5.7 `publish`
+
+```text
+project-context publish --project PATH --target agents|ruler --output RELATIVE_PATH [--path RELATIVE_PATH...] --write
+```
+
+目标：
+
+- `agents`：带受管标记的 AGENTS-compatible Markdown；
+- `ruler`：Ruler 能递归读取的普通 Markdown 源文件。
+
+v1 不生成 Claude、Gemini、Cursor、Kiro 等专用格式。用户需要这些格式时使用 Ruler/Rulesync。
+
+写入规则：
+
+1. `--output` 必须位于项目内且不是 symlink。
+   - `agents` target 只能写入名为 `AGENTS.md` 的文件；
+   - `ruler` target 只能写入 `.ruler/` 内的 Markdown 文件。
+2. 新文件可以创建。
+3. 已存在文件只有同时包含本产品 ownership marker，并且内容 digest 与 `projections.lock.json` 相符时才能覆盖。
+4. 用户手写文件、其他工具文件或被人工修改的受管文件必须停止并报告。
+   - 根 `AGENTS.md` 已由用户维护时，可以在没有冲突的目标子目录生成受管 `AGENTS.md`，利用 Agent 的层级规则加载与根规则共存；也可以使用 Ruler 投影。
+5. 每个文件写入使用同目录临时文件加原子 rename。
+6. 显式写入先提交 next projection lock，再写 projection；projection 失败时恢复原 lock。
+7. lock 恢复也失败时，lock-first 状态必须让 `check` 确定报告 projection missing 或 ownership conflict；没有 `--write` 时只输出 preview 和 diff 摘要。
+
+生成标记示意：
+
+```html
+<!-- managed-by: project-context; contract-digest: sha256:...; target: agents -->
+```
+
+### 5.8 `check`
+
+```text
+project-context check --project PATH
+```
+
+只读检查：
+
+- JSON schema、唯一 ID、枚举、路径和 approval；
+- source path、JSON pointer 和确认 digest；
+- 同 subject、重叠 scope、不同 value 且没有有效 overrides 的冲突；
+- override 是否指向更宽或同范围的有效 approved item；
+- projection ownership marker、contract digest 和内容 digest；
+- proposal 内容是否被误写入 projection；
+- lock 中是否存在已经删除的合同项或生成文件。
+
+`check` 不更新 digest、不写文件、不执行项目验证。
+
+## 6. 确定性编译规则
+
+1. 只读取 `approved` item。
+2. 对每个目标路径计算有效 item 集。
+3. 同 subject 的更窄 scope 只有声明 `overrides` 才替代上层 item。
+4. 未被覆盖的冲突使编译失败。
+5. 输出按 `kind`、scope specificity、subject、id 稳定排序。
+6. Markdown 使用 item ID 和 source ID，避免内容失去来源。
+7. 合同 digest 基于规范化 JSON 计算，不受键顺序和空白影响。
+
+## 7. 模块边界
+
+```text
+bin/project-context.mjs
+src/project-context/
+  approver.mjs
+  authoring.mjs
+  checker.mjs
+  cli.mjs
+  contract-schema.mjs
+  canonical-json.mjs
+  discovery.mjs
+  errors.mjs
+  io.mjs
+  maintenance.mjs
+  path-policy.mjs
+  project-store.mjs
+  projection-store.mjs
+  renderer.mjs
+  source-reader.mjs
+  scope-compiler.mjs
+test/project-context/
+```
+
+- `source-reader` 只读取和哈希来源。
+- `authoring` 只构造/登记显式 source 和单 item proposal，不批准内容。
+- `discovery` 产生 proposal，不接触 approved 状态。
+- `scope-compiler` 是纯函数，不访问 Runtime。
+- `projection-store` 是唯一可写目标项目文件的模块。
+- 所有模块使用 Node.js 标准库；不安装依赖。
+
+## 8. 输出与退出码
+
+所有命令支持人类摘要；`--json` 输出稳定机器结果。
+
+```text
+0  success / no findings
+1  validation or drift findings
+2  invalid input or unsupported project state
+3  managed-file ownership conflict
+4  unexpected internal failure
+```
+
+错误报告至少包含 code、message、相关 item/source/path 和建议的人工下一步。不得建议自动重试 Provider 或自动覆盖文件。
+
+## 9. 程序明确禁止
+
+源码和测试静态禁止：
+
+- OpenAI、Anthropic、Gemini 或其他 Provider SDK/HTTP 调用；
+- `child_process` 执行 shell、项目命令、Git 或第三方 CLI；
+- `git add/commit/branch/switch/checkout/merge/push/reset/clean/stash` 等任何 Git 写语义；
+- 修改 `.vue`、`.ts`、`.tsx` 等业务源文件；
+- 自动安装 Ruler、Rulesync 或依赖；
+- candidate、session、validation record、decision、delivery 和 retry loop。
+
+## 10. 实现顺序
+
+1. schema、规范化 JSON、path policy；
+2. contract 读取与 `check`；
+3. scope compiler 和 Context Bundle renderer；
+4. projection ownership 与安全写入；
+5. deterministic discovery；
+6. approve 合并；
+7. CLI 整合与完整 fixture 验收；
+8. 通用 register/propose、approval 预检、renderer v2 和 A-15 至 A-20。
+9. 来源 review/accept、同 ID revise、deprecate、pending reapproval、store 并发补强和 A-21 至 A-30。
+
+任何一步都不需要真实项目任务或 Provider。
+
+## 11. `0.7.0` Knowledge Maintenance Closure 实现结果
+
+`0.7.0` 已按 [12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md](./12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md) 的冻结设计完成本地实现。
+
+实现没有改变本文件第 1 至第 9 节的产品形态与边界，也没有推倒重写现有模块。完成范围是：
+
+- 新增只读 `review-source`、显式 `accept-source-change`、同 ID `revise`、显式 `deprecate`；
+- 扩展既有 `approve`，以 `--pending` 明确批准 contract 内 proposed item；
+- 复用 schema 1 的 approved/proposed/deprecated，使 source acceptance 确定撤销影响集旧 approval；
+- 增加 pending finding、完整影响集与 projection stale 报告；
+- 加固 project/projection store 的提交前快照和条件恢复；
+- 增加 A-21 至 A-30，同时保持原 24 项通过，当前总计 34 项。
+
+contract、proposal、source lock、projection lock schema 继续为 1，renderer 继续为 2。准确 CLI、影响集、原子性、错误、兼容和停止条件以 12 为准。当前实现版本为 `0.7.0`，已达到阶段 2 停止条件。
+
+## 12. `0.8.0` Read-only Governance Dashboard 实现结果
+
+看板已按 [13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md](./13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md) 的冻结设计完成本地实现。
+
+它只增加 `dashboard --project PATH [--json]` 的只读派生出口：默认向 stdout 输出确定性的自包含 HTML，`--json` 输出同一短生命周期 View Model。它不写文件、不启动服务、不打开浏览器，不增加 store、schema、projection target、Provider、网络或 Git 能力。
+
+实现新增纯派生 `dashboard-model.mjs` 和确定性 `dashboard-renderer.mjs`，只复用现有 checker、source impact、scope compiler、canonical JSON 和 project loader。A-31 至 A-38 已通过，原 34 项无回归，当前共 42 项。
+
+## 13. `0.9.0` Context 效率与治理加固
+
+`0.9.0` 没有新增产品能力或第三方依赖，只收紧现有不变量并删除派生重复：
+
+- 写入父目录逐级创建并校验 realpath，阻断“项目内 symlink + 尚不存在子目录”逃逸；
+- verification 按 kind 校验字段语义，Contract value 拒绝非 JSON 值；proposal approval 只允许创建新 ID，同 ID 变化必须走带 baseline digest 的 `revise`；
+- 相同知识集的多路径 Context 合并渲染；双语 statement 默认只输出中文主解释，可选 `en` 或 `all`；
+- `approve --json` 返回紧凑回执，`--full-json` 显式保留旧的完整预览；
+- Dashboard View Model 升为 2，删除可重算 canonicalValue/title；HTML 不再嵌入 View Model，搜索从可见记录建立缓存，空关系/验证/覆盖/同级差异不渲染；
+- `RTK.md` 和 `PROJECT_STATE.json` 只承担启动路由与当前状态，不重复保存完整历史。
+
+contract、proposal、source lock、projection lock schema 仍为 1。projection renderer 升为 3；renderer 1/2 可读但 stale，只有显式且所有权完整的 publish 才升级。运行版本为 `0.9.0`。
+
+2026-09-08 的团队维护验收只使用隔离临时 fixture，按公开 CLI 完整覆盖 source change → review → accept → revise/deprecate → pending approval → stale check → republish → clean check，并再次通过 42 项全量回归；没有修改产品设计或代码边界。
+
+## 14. `1.0.0` 正式发布候选
+
+`1.0.0` 只冻结已经通过验收的 v1，不新增运行时能力。稳定公共接口为 `project-context` CLI；`src/project-context/` 继续作为包内实现，不承诺可由消费者直接导入。发布包只包含 bin、src、docs、examples、README、CHANGELOG、UPGRADING、PROJECT_STATE、RTK、LICENSE、NOTICE 和 package metadata，不包含测试、自托管 Contract 或本地生成物。PROJECT_STATE 与 RTK 随包提供，是为了保持 README/设计文档的相对链接完整，不把它们提升为消费项目的 Contract。
+
+发布候选采用 Apache-2.0，版权主体为 `Copyright 2026 Fushan`。2026-09-08 后续授权已选择 public npm 并解除 private 安全闩；当前发布状态和外部权限以 PROJECT_STATE 为准，详细 Gate 见 [14-FORMAL-RELEASE-READINESS.md](./14-FORMAL-RELEASE-READINESS.md)。
+
+## 15. 首次发布前 Source Lifecycle Closure 实现结果
+
+发布候选后续审查发现：现有 CLI 能接受同一 locator 上的 source 内容变化，却不能关闭已登记来源删除、搬迁或永久退役后的 `source-missing`。`register` 拒绝同 ID locator 变化，`accept-source-change` 拒绝 missing/unreadable，而 schema 1 没有 source lifecycle；这会迫使维护者直接编辑内部 JSON。
+
+[15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md](./15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md) 冻结的最小修补已经实现：
+
+- Contract reader 同时验证 schema 1/2；schema 2 source 显式使用 active/deprecated lifecycle；
+- 新增默认 preview 的 `deprecate-source`，写入要求 source object baseline、署名、理由、无当前引用和本命令 `--write`；
+- proposed/approved item 不得引用 deprecated source，deprecated item 可保留历史 provenance；
+- checker/source reader 跳过 deprecated locator IO，source lock 不得保留 deprecated entry；
+- schema 1 只在第一次成功来源废弃时延迟升为 2；proposal 与两个 lock 保持 schema 1，renderer 保持 3；
+- Dashboard View Model 升为 3，只增加 deprecated 状态与审计字段；
+- project 双 store 写入在提交前同时核对 contract、source lock 和 projection lock snapshot，并保持 lock-first 条件恢复。
+
+A-40 至 A-45 和全部既有回归已通过，当前共 49 项。package 仍为 `1.0.0`；公开发布配置不新增 Provider、框架识别、source kind、projection target、调度、Git 管理或自动批准能力。