frontend-project-context 1.0.0

package/docs/13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md

@@ -0,0 +1,489 @@
+# 0.8.0 Read-only Governance Dashboard 冻结设计与实现记录
+
+> 权威说明：本文冻结只读治理看板的实现合同。产品身份、内核、永久边界和不变量仍以 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 为准；当前事实与授权以 [PROJECT_STATE.json](../PROJECT_STATE.json) 为准。
+>
+> 状态：`implemented-local-verified; A-31-through-A-38-and-regressions-passed`
+>
+> 目标版本：`0.8.0`
+>
+> 审查起点基线：产品宪法 `1.1.1`、PROJECT_STATE schema `30`、运行版本 `0.7.0`、self-hosted Contract `17 sources / 17 approved items / 0 findings`；设计收录后的当前状态以 `PROJECT_STATE.json` 为准。
+>
+> 后续兼容说明：第 1 至 18 节保留 `0.8.0` 冻结设计与迭代记录；当前 `0.9.0` 的派生数据精简、View Model schema 2 和 renderer 3 由第 19 节覆盖。
+
+## 1. 决定
+
+`0.7.0` 已经让机器能够稳定读取、验证和维护 Project Contract，本仓库也已经用 `.project-context/` 完成自托管。但是普通用户仍需阅读 JSON、digest 和 CLI 输出，才能回答以下问题：
+
+1. 这个项目已经批准了什么知识？
+2. 每条知识为什么成立，来源在哪里？
+3. 哪些知识对某个目录生效，为什么生效？
+4. 当前是健康、需要关注还是已经阻断？
+5. 来源变化会影响哪些 item 和投影？
+6. 当前允许继续做什么，哪些方向仍未授权？
+
+因此 `0.8.0` 的唯一候选范围冻结为 **Read-only Governance Dashboard**：把现有 Contract、两个 lock、checker、scope compiler 和 source impact 转换为一个面向人的只读解释界面。
+
+看板是派生视图，不是新真源、审批入口、项目编辑器或 Agent Runtime。任何显示结果都必须能回溯到现有 store 和现有纯函数；看板不得自行保存状态或推断新的规范。
+
+## 2. 证据审查与唯一缺口
+
+| 现有能力 | 代码/数据证据 | 看板直接复用 | 唯一缺口 |
+| --- | --- | --- | --- |
+| Contract 与 lock | `loadProject` 已验证三份 schema 1 store 并计算 digest | 直接读取，不增加 store | 缺少面向人的汇总模型 |
+| 健康检查 | `checkProject` 已稳定输出 source、verification、scope、conflict、projection findings | 原样作为健康事实 | 缺少严重度、影响对象和用户解释分组 |
+| 来源审查 | `reviewSource` 已给出当前/锁定 digest、状态和完整影响集 | 单来源详情直接复用 | 缺少来源列表级汇总 |
+| 影响集 | `sourceImpact` 已给出 direct、override-dependent、fallback 和 projection paths | 直接呈现关系 | 缺少可读的树/表结构 |
+| Scope | `effectiveItems` / `collectBundle` 已决定某路径的最终 item | 只由既有编译语义计算 | 缺少可视化 scope explorer |
+| Approval | Contract 已保存 status、by、at、rationale | 只读展示 | 缺少人类可读的 item detail |
+| Projection | projection lock 与 checker 已给出 ownership/stale/diverged | 只读展示 | 零投影需要与“健康”分开解释 |
+| 本仓库数据 | 已有 17 sources、17 approved items、零 finding | 作为首个真实看板 fixture | 用户目前只能通过对话或 JSON 理解 |
+
+唯一缺口不是缺少新的治理语义，而是：**现有治理事实没有稳定的人类解释模型和可视化出口。**
+
+## 3. 产品边界
+
+### 3.1 必须做到
+
+- 一眼区分合同健康、知识覆盖、审批状态和投影覆盖；
+- approved value 与 statement 优先，ID、digest 和 raw JSON 次级展示；
+- 每个 item 显示 status、kind、scope、approval、sources、overrides 和 verification；
+- 每个 source 显示 kind、locator、checkpoint/current 状态、引用 item 和影响集；
+- 对已知 scope 路径显示准确的 effective item IDs 和排除原因；
+- 将 checker finding 转换为稳定、可追溯、非自动修复的解释；
+- 完全离线、无第三方依赖、无 Provider、无 Git、无业务代码写入。
+
+### 3.2 明确不做
+
+- 不编辑 Contract、source lock 或 projection lock；
+- 不提供 accept、revise、deprecate、approve、publish 或 fix 按钮；
+- 不启动 HTTP/WebSocket 服务，不监听端口，不自动打开浏览器；
+- 不写 dashboard HTML、JSON、缓存、偏好或最近项目；
+- 不新增 dashboard projection target、dashboard lock 或 schema migration；
+- 不读取或显示 source 正文、JSON Pointer 当前值、Token 或凭据；
+- 不实现任意项目文件浏览器、搜索索引、知识图谱数据库或跨仓库中心；
+- 不增加框架识别器、source kind、scope kind 或 Agent adapter；
+- 不把“零 finding”解释为“已配置投影”或“产品价值已验证”。
+
+## 4. 用户心智模型
+
+看板必须先回答人类问题，再提供机器审计字段：
+
+```text
+项目相信什么？
+  → approved Contract items
+
+为什么相信？
+  → source locator + approval + verification
+
+在哪里生效？
+  → scope tree + effective items
+
+现在安全吗？
+  → checker findings + source/projection status
+
+变化会影响什么？
+  → direct + verification + override-dependent + fallback + projections
+```
+
+术语翻译固定为：
+
+| 机器术语 | 默认界面用语 | 说明 |
+| --- | --- | --- |
+| Contract | 已批准项目知识 | 详情中保留 `Project Contract` |
+| Item | 知识项 | 以 statement/value 为主标题内容 |
+| Source | 依据来源 | locator 可见，正文不可见 |
+| Approved | 已批准 | 显示批准者与时间 |
+| Proposed | 待批准 | 明确阻断 Context/Publish |
+| Deprecated | 已废弃 | 保留审计，不作为当前规则 |
+| Finding | 待处理问题 | 不暗示自动修复 |
+| Projection | Agent 投影 | 与真源明确分层 |
+| Digest | 内容指纹 | 默认缩写，审计抽屉显示完整值 |
+
+## 5. 信息架构
+
+首版固定六个视图，使用单页客户端切换，不改变 URL、不访问网络：
+
+1. **总览 Overview**：健康、覆盖、状态、关键知识和待处理问题；
+2. **知识 Knowledge**：按 kind/status/scope 筛选全部 item；
+3. **来源 Sources**：来源状态、引用关系和单来源影响集；
+4. **范围 Scopes**：已知 scope 路径及其 effective items；
+5. **投影 Projections**：受管投影状态；零投影显示“未配置”，不是错误；
+6. **问题 Findings**：checker 的完整、稳定、可审计列表。
+
+### 5.1 总览线框
+
+```text
+┌───────────────────────────────────────────────────────────────────────┐
+│ Project Context · Frontend Project Context       Contract sha256:e854… │
+├──────────────┬────────────────────────────────────────────────────────┤
+│ 总览         │  合同健康：通过                                        │
+│ 知识         │                                                        │
+│ 来源         │  [来源 18/18] [已批准 18] [待批准 0] [投影 0 未配置]    │
+│ 范围         │                                                        │
+│ 投影         │  这个项目已经批准了什么                                │
+│ 问题         │  ┌ 产品身份 ────────────────────────────────────────┐  │
+│              │  │ 项目内、模型无关的上下文治理与编译层              │  │
+│              │  └──────────────────────────────────────────────────┘  │
+│              │                                                        │
+│              │  必须遵守                                              │
+│              │  ✓ 人工批准长期规则   ✓ 不调用 Provider                │
+│              │  ✓ 不管理 Git        ✓ 不自动接受或修复                │
+│              │                                                        │
+│              │  需要注意                                              │
+│              │  ○ 尚未配置受管投影；不影响合同健康                    │
+└──────────────┴────────────────────────────────────────────────────────┘
+```
+
+### 5.2 总览状态不使用百分比
+
+当前数据没有“完成率”或统一目标值，因此禁止伪造 87%、环形进度或仪表盘分数。固定显示离散事实：
+
+- `Contract health`：`clean | attention | blocked | conflict`；
+- `Sources`：registered / healthy / manual / changed / missing / unreadable；
+- `Items`：approved / proposed / deprecated；
+- `Projections`：configured / healthy / stale / missing / conflict；
+- `Coverage`：被至少一个 item 引用的 source 数量；
+- `Authority`：只展示 Contract 中已有的 policy，不硬编码本仓库 item ID。
+
+## 6. 各视图详细合同
+
+### 6.1 Knowledge
+
+- 默认顺序：status（proposed、approved、deprecated）→ kind → ID；
+- 卡片主内容是 statement 与 canonical approved value；
+- ID、subject、scope、source IDs、approval、verification 和 digest 在详情面板；
+- value 为对象或数组时用可折叠键值树和等宽 raw JSON 双视图；
+- 搜索只匹配已加载 snapshot，不访问项目文件；
+- deprecated 保留但视觉降级；proposed 使用文字和图标明确“不会进入 Context Bundle”。
+
+### 6.2 Sources
+
+列表字段固定为：ID、kind、locator、status、referencing item count、affected item count、projection count。
+
+单来源详情固定展示：
+
+- contract digest、locked digest、current digest 的缩写和完整审计值；
+- `unchanged | changed | missing | unreadable | manual | external`；
+- 直接 `sources` 引用、verification 引用、反向 override-dependent；
+- fallback items；
+- direct projection paths 与接受变化后会 stale 的 projection paths；
+- 不显示文件正文、JSON Pointer 值或自动接受按钮。
+
+### 6.3 Scopes
+
+首版不在浏览器重新实现 scope compiler。Dashboard Model 使用现有 `effectiveItems` 预计算有限的 `scopeViews`：
+
+- 项目根 `.`；
+- 所有 item scope path；
+- source 与 projection locator 的顶层目录；
+- 上述路径的祖先目录；
+- 稳定去重和排序。
+
+用户只能选择这些已知路径。每个路径显示：
+
+- 生效的 item，按 kind 分组；
+- item 来自 project、path-prefix 或 file scope；
+- override 关系和被排除项；
+- 与 sibling 路径的差异。
+
+任意路径输入留到后续版本；首版不得复制一份浏览器 scope 算法。
+
+### 6.4 Projections
+
+- projection lock 为空时显示 `Not configured / 未配置`，整体 health 仍可为 clean；
+- 每项显示 target、path、paths、renderer version、item count 和状态；
+- ownership conflict 使用最高严重度，但不提供覆盖按钮；
+- dashboard 自身不登记为 projection，也不进入 projection lock。
+
+### 6.5 Findings
+
+Finding 以稳定 code 为身份，界面补充中文标题、严重度和影响面；原始 details 可展开，不能改写或丢失字段。
+
+严重度固定为：
+
+- `blocked`：source、pending approval、scope、contract conflict、verification 等会阻断 Context/Publish 的 finding；
+- `attention`：projection stale/missing/renderer stale 等需要显式 publish 处理、但不阻断 Context 的 finding；
+- `conflict`：projection ownership conflict，保持退出码 3；
+- `clean`：零 finding。
+
+总健康状态按固定优先级计算：存在 `projection-ownership-conflict` 时为 `conflict`；否则存在现有 Context 阻断集合（`source-*`、`item-approval-pending`、`scope-*`、`contract-conflict`、`verification-*`）时为 `blocked`；否则只要仍有 finding 就是 `attention`；零 finding 才是 `clean`。该分类只用于解释，退出码仍完全由 `checkExitCode` 决定。
+
+不得使用颜色作为唯一信号；状态必须同时有文字、图标和可访问标签。
+
+## 7. Dashboard View Model
+
+新增的是短生命周期输出 schema，不是持久 store schema：
+
+```json
+{
+  "schemaVersion": 1,
+  "project": {
+    "id": "frontend-project-context",
+    "name": "Frontend Project Context",
+    "root": "."
+  },
+  "digests": {
+    "contract": "sha256:...",
+    "sourcesLock": "sha256:...",
+    "projectionsLock": "sha256:..."
+  },
+  "health": {
+    "status": "clean",
+    "exitCode": 0,
+    "findingCount": 0,
+    "findingsByCode": {}
+  },
+  "summary": {
+    "sources": {},
+    "items": {},
+    "projections": {}
+  },
+  "items": [],
+  "sources": [],
+  "scopeViews": [],
+  "projections": [],
+  "findings": []
+}
+```
+
+### 7.1 稳定性
+
+- 数组按稳定 ID/path 排序，对象键使用 canonical JSON 顺序；
+- 不加入 `generatedAt`、随机 ID、主机名、用户名或绝对路径；
+- 相同项目 bytes 必须产生完全相同的 JSON 和 HTML bytes；
+- HTML 只嵌入 View Model，不重新读取项目；
+- dashboard schema 独立为 version 1，不改变 contract/proposal/lock schema 1 或 renderer 2。
+
+### 7.2 Source 模型
+
+每个 source 至少包含：
+
+```text
+id, kind, locator, status
+contractDigest, lockedDigest, currentDigest?
+itemIds, directItemIds, verificationItemIds
+overrideDependentItemIds, fallbackItemIds
+directProjectionPaths, staleProjectionPaths
+```
+
+`human-decision` 和 `external-reference` 分别显示 `manual`、`external`，不伪装为 unchanged，也不尝试访问网络。
+
+### 7.3 Item 模型
+
+每个 item 使用 Contract 原始字段的只读副本，并增加纯派生字段：
+
+```text
+itemDigest, sourceLocators, effectiveScopePaths
+```
+
+不得增加 AI 摘要或从 source 正文生成解释。界面的人类说明来自 item 自身的 statement 和 approved value。
+
+## 8. 数据派生与代码复用
+
+实现只能组合现有能力：
+
+| 派生内容 | 唯一实现来源 |
+| --- | --- |
+| store/schema/digest | `loadProject` |
+| findings/exit code | `checkProject`、`checkExitCode` |
+| local source current digest/status | `readSourceDigest` / `reviewSource`；仅用于 `file`、`path`、`json-pointer` |
+| source impact | `sourceImpact`，不可复制算法 |
+| effective item | `effectiveItems` / `collectBundle` |
+| scope 文本 | `describeScope` |
+| canonical value/digest | `canonicalJson` / `digestJson` |
+
+允许把 CLI 内现有 `blockingContextFindings` 提取为 checker 的导出纯函数，让 Context、Publish 和 Dashboard 共用同一分类；不得改变现有阻断语义。
+
+Dashboard Model builder 可以并行读取来源，但最终输出必须稳定排序。任何单个来源不可读时仍生成包含 finding 的完整看板，不因一个 card 失败而返回空页面。
+
+`human-decision` 和 `external-reference` 不调用 `reviewSource`；其 `manual` / `external` 展示状态直接由已验证的 source kind 映射，并继续使用 `sourceImpact` 计算关系。这是展示分类，不改变 checker 或 maintenance 的来源审查语义。
+
+## 9. 固定 CLI 合同
+
+```text
+project-context dashboard --project PATH [--json]
+```
+
+- 命令永远只读，不接受 `--write`、`--output`、`--open`、`--port`、`--watch` 或其他命令参数；
+- 默认 stdout 是一个包含内联 CSS、内联 JS 和内联 View Model 的完整 HTML 文档；
+- `--json` 输出同一 View Model 的 pretty canonical JSON；
+- 命令不创建文件、不启动服务、不打开浏览器；调用者可以自行预览 stdout，或用 shell 重定向到临时 HTML；
+- 即使存在 finding，也尽可能输出完整 HTML/JSON，同时使用与 `check` 相同的退出码；
+- schema/path/参数错误退出 2，ownership conflict 退出 3，意外错误退出 4；
+- HTML stdout 不登记到 projection lock，不是项目资产或第二真源。
+
+选择 stdout 而不是 `--write` 的原因：在不增加 dashboard projection target 或 dashboard lock 的前提下，持久覆盖 HTML 会违反现有 managed-file ownership 不变量。首版明确选择只读、短生命周期输出。
+
+## 10. HTML、安全与隐私
+
+- 单个自包含 HTML；零 CDN、零字体请求、零图片请求、零 fetch/XHR/WebSocket；
+- 使用系统 UI 字体和 `ui-monospace`，不依赖 Google Fonts；
+- 所有 value、statement、ID、path、rationale 和 finding details 必须 HTML escape；
+- 内嵌 JSON 必须转义 `<`、`</script`、U+2028 和 U+2029；
+- 禁止 `eval`、`new Function`、字符串事件 handler 和不受控 `innerHTML`；
+- 使用严格 CSP meta，仅允许当前文档必要的 inline style/script，禁止连接外部来源；
+- external-reference 只显示为文本；不自动请求、不默认生成可点击外链；
+- 不嵌入 source 正文或当前 JSON Pointer 值；approved Contract value 可以展示，因为它本来就是受治理输出；
+- 页面加载后所有筛选、展开和导航只作用于已嵌入 snapshot。
+
+## 11. 视觉与交互系统
+
+产品类型是高密度开发者治理工具，固定设计参数：
+
+- density `8/10`：紧凑表格和详情抽屉，但正文不少于 14px；
+- variance `5/10`：使用审计台式信息层级，不使用营销式 Bento、渐变或玻璃拟态；
+- motion `2/10`：仅 150–200ms 展开、筛选和高亮；
+- 支持 light/dark system theme，不强制暗色；
+- 正文使用系统 sans，ID/digest/JSON 使用系统 monospace；
+- 状态色采用语义 token，并同时提供文字/图标；
+- network graph 不作为首版主视图；关系主视图使用可展开树和邻接表。
+
+### 11.1 响应式
+
+- `>= 1024px`：固定左导航 + 主内容 + 可选右详情；
+- `768–1023px`：左导航折叠为顶部 tab，详情覆盖主内容；
+- `< 768px`：单列、水平表格转换为定义列表，禁止页面级横向滚动；
+- 验证宽度：375、768、1024、1440px。
+
+### 11.2 无障碍
+
+- 文字对比度至少 4.5:1；
+- 所有操作可键盘完成，focus ring 始终可见；
+- tab、dialog、tree、table 使用正确语义和 label；
+- hover 信息必须也能通过 focus/展开获得；
+- `prefers-reduced-motion` 下取消非必要过渡；
+- 关系树必须有可读表格 fallback；
+- 不使用 emoji 作为状态图标，使用内联 SVG 并提供 accessible name 或 `aria-hidden`。
+
+## 12. 兼容与迁移
+
+- contract、proposal、source lock、projection lock 继续 schema 1；
+- renderer 继续 version 2；
+- `.project-context/` 不增加文件；
+- 0.7.0 项目无需迁移即可生成 dashboard；
+- dashboard View Model schema 1 只存在于 stdout；
+- 看板实现升级不能自动修改 Contract 或重新发布 projection；
+- HTML 不承诺跨版本 byte 兼容，但相同版本、相同 store bytes 必须确定性一致；
+- Node.js `>=18`，零第三方依赖。
+
+## 13. 稳定错误与退出码
+
+Dashboard 不发明第二套 finding。错误和退出码复用现有 0–4 合同：
+
+| 退出码 | 行为 |
+| --- | --- |
+| 0 | 输出 clean dashboard |
+| 1 | 输出包含 changed/missing/pending/stale 等 finding 的 dashboard |
+| 2 | 参数、路径或 schema 无效，输出稳定错误对象/文本 |
+| 3 | 输出包含 projection ownership conflict 的 dashboard |
+| 4 | 非预期内部失败 |
+
+HTML/JSON 中的每个 finding 保留原 code 和原 details。界面翻译不能改变退出码或把 warning 隐藏为 success。
+
+## 14. 唯一实现范围
+
+获得单独实现授权后，只允许以下变化：
+
+| 文件/模块 | 唯一允许变化 |
+| --- | --- |
+| `src/project-context/dashboard-model.mjs` | 新增纯派生 View Model builder；组合 checker/sourceImpact/effectiveItems |
+| `src/project-context/dashboard-renderer.mjs` | 新增确定性、自包含、离线安全 HTML renderer |
+| `src/project-context/checker.mjs` | 仅提取共享 finding blocking/severity helper，不改现有 finding 语义 |
+| `src/project-context/cli.mjs` | 新增只读 `dashboard --project PATH [--json]`、help 和 allowlist |
+| `test/project-context/dashboard.test.mjs` | A-31 至 A-38；不得弱化已有 34 项 |
+| package/README/RTK/04/05/08/13/PROJECT_STATE/self-hosted Contract | 实现后同步版本、命令、验收和来源 checkpoint |
+
+明确不得修改：
+
+- contract/proposal/lock schema；
+- `project-store`、`projection-store` 写入语义；
+- authoring/approver/maintenance 状态转换；
+- source/item/scope kind；
+- renderer 内容和 projection target；
+- discovery；
+- Provider、网络、Git、任务执行或业务源码能力。
+
+## 15. 冻结验收 A-31 至 A-38
+
+- **A-31 View Model 确定性与只读**：相同 bytes 两次 JSON 完全相同；命令前后三份 store、来源和业务文件 bytes 不变；self-host fixture 统计准确。
+- **A-32 人类总览与覆盖分离**：清晰展示项目、health、source/item 状态和 projection coverage；零 projection 显示未配置而非错误或 100%。
+- **A-33 知识与 provenance**：四类 item、三种 status、approval、scope、source、override、verification 可读；approved value 可见；raw JSON 次级；source 正文不可见。
+- **A-34 来源状态与影响集**：unchanged/changed/missing/unreadable/manual/external 分类准确；direct/verification/override-dependent/fallback/projection 集合与 maintenance 纯函数一致。
+- **A-35 Scope explorer 一致性**：已知路径的 effective item IDs 与 `effectiveItems` 一致，覆盖 project/path-prefix/file、override 和 sibling isolation；浏览器不复制任意路径编译器。
+- **A-36 Finding 与退出码**：clean、blocking、projection attention、ownership conflict 均输出完整看板并保持 check 的 0/1/3；无 finding 被吞掉或自动修复。
+- **A-37 HTML 安全、离线和无障碍**：恶意 value/path/rationale 不执行；零外部请求；语义 landmarks、键盘、focus、contrast、reduced motion、tree table fallback 和 375–1440px 布局通过。
+- **A-38 CLI、兼容与永久边界**：拒绝 `--write/--output/--open/--port/--watch` 和无关参数；schema 1/renderer 2/0.7 数据兼容；现有 34 项继续通过；零 Provider、network、dependency、child process、Git 和业务写入。
+
+实现 Gate 固定为：A-01 至 A-38、B0-01/B0-02 和 CLI 全部通过；README/help 足以让另一位前端开发者生成并理解一次 dashboard；本仓库真实 Contract 页面能够回答第 1 节六个问题。
+
+## 16. 实现顺序与停止条件
+
+实现顺序固定为：
+
+```text
+共享 finding 分类 helper
+→ dashboard-model 纯数据与 A-31/A-34/A-35/A-36
+→ dashboard-renderer 安全 HTML 与 A-32/A-33/A-37
+→ CLI/help/allowlist 与 A-38
+→ 本仓库真实 Contract dashboard 验证
+→ 文档、自托管 source checkpoint 和状态同步
+→ 停止
+```
+
+实现停止条件已经满足：信息架构、View Model、CLI、HTML 交付、安全、无障碍、兼容、错误和唯一范围均按冻结设计落地；A-31 至 A-38 与原 34 项共 42 项全部通过。本仓库自托管数据验证得到 18 sources、18 approved items、0 projections、0 findings；HTML 为单文件、零外链、stdout-only。
+
+本次一次性实现授权已经完成并消耗，未执行 Git 写入、真实外部项目访问、团队验收或正式发布。内置浏览器因安全策略拒绝直接打开本地 `file://` 产物，没有绕过或启动服务器；界面质量以 A-37 自动验收、静态 CSP/外链检查和响应式预检为证据。下一步只能独立授权阶段 3 团队维护验收或正式发布准备。
+
+## 17. 视觉重构记录
+
+用户在 `0.8.0` 首版实现后明确认为页面设计不满意，并单独授权在冻结产品边界内优化现有看板。此次授权只覆盖 HTML renderer、相关 A-37 断言和本节记录，不扩展 View Model、CLI、store、schema、projection target 或外部能力。
+
+重构采用“本地治理审计台”而非通用后台模板：
+
+- 将四个等权独立卡片收束为连续指标账本，并新增完全由现有 View Model 派生的 `来源 → Contract → Scope → 投影` 治理链路；
+- 将松散卡片列表改为连续审计记录表面，减少圆角、阴影、装饰色和重复容器；
+- 左侧导航显示各视图真实记录数，知识搜索支持 `Escape` 清空，tab 支持方向键与 `Home` / `End`；
+- 保留系统 light/dark、375/768/1024/1440 响应式、44px 控件、明显 focus ring、文字加图标状态和 reduced motion；
+- 继续使用系统字体、内联 CSS/SVG/JS、严格 CSP、零依赖、零网络、stdout-only 和确定性输出。
+
+本次没有安装所谓 Product Design 插件：当前环境没有该名称的已安装或推荐插件，而仓库的零依赖、离线边界也不需要引入它。设计方法使用本地 UI/UX 规则进行审计，项目冻结合同优先于通用设计建议。
+
+视觉重构后 A-31 至 A-38 与全部回归仍是唯一验收 Gate。该授权完成即消耗；下一步仍为单独授权的团队维护验收或正式发布准备。
+
+## 18. 中英双语界面记录
+
+用户在查看视觉重构产物后，单独授权将看板从英文占比较高的界面调整为中英双语。双语规则固定为：
+
+- 页面顶部提供“中文 / English”按钮，默认中文；选择只作用于当前 HTML 页面，不写偏好、不访问网络；
+- 导航、状态、指标、流程、筛选、审计字段、提示和空状态随按钮切换，不同时堆叠两种语言；
+- statement 支持 schema 1 string 内的 `[zh-CN] ...\n[en] ...` 双语约定；当前仓库 18 条 statement 已通过既有 revise、approve 流程正式收录双语解释；
+- value、ID、digest、path 和 machine enum 保持原值；看板不翻译机器事实或让未经批准的译文成为第二份真源；
+- 只有单语 statement 的兼容项目继续显示原文；中文模式明确提示“暂无中文译文”，不得隐式机翻；
+- 文本必须在 375px 视口正常换行，导航仍保留可见语言名称和完整键盘操作；
+- CSP、离线、stdout-only、确定性、退出码、View Model schema 1 和 A-31 至 A-38 保持不变。
+
+其他项目若希望知识解释同时具备中英版本，应由维护者通过既有 revise、approve 流程把双语 statement 正式纳入 Contract，而不是由看板临时推断。
+
+## 19. `0.9.0` 派生数据精简与交互保真
+
+系统审查确认看板的真实价值是“解释 Contract”，不是保存第二份浏览器数据仓库。因此实现删除以下可重算或空白内容：整份内嵌 View Model、每个 item 的 canonicalValue 副本、finding 中文 title 副本、`data-search` 文案副本、空 source 关系、空 overrides/verification、零差异 sibling 区块和三份相同 source digest。View Model 升为 schema 2；HTML renderer 直接从 value/finding code 派生展示。
+
+保留的交互只有：中文/英文按钮、ARIA tab 键盘导航、搜索与三个筛选器、details 渐进披露、响应式布局、可见 focus 和严格 CSP。语言显隐复用标准 `lang` 属性；状态图标复用 SVG symbol；页面本身没有动画，不输出无效 reduced-motion CSS。所有可交互控件继续使用原生 button/input/select/summary 并具有可访问名称，重要正文不截断。
+
+同一轮加固还把 Context Bundle 默认切换为单语言主解释并合并相同知识集的多个路径，避免把与人类看板无关的双语和重复 section 持续送入模型。该轮没有新增 store、框架识别、source kind、projection target、服务、网络或写入能力。
+
+## 20. 团队维护验收状态
+
+2026-09-08 经单独授权完成团队维护验收。隔离 fixture 的维护闭环与 42 项全量回归均通过；本仓库看板继续显示 18 sources、18 approved items、0 findings，并生成确定性的 schema 2 JSON 与单文件离线 HTML。该验收不改变看板设计、schema、代码或产品边界；正式发布准备仍须单独授权。
+
+## 21. Source lifecycle 兼容扩展
+
+`1.0.0` Source Lifecycle Closure 只对现有来源视图增加必要状态，不改变六视图信息架构或浏览器交互：
+
+- Dashboard View Model 升为 schema 3；active 来源继续使用既有 unchanged/changed/missing/unreadable 状态；
+- deprecated 来源显示 `deprecated` 和 Contract 中已批准的 `by/at/rationale`，不读取已经退役的 locator；
+- deprecated source 若仍在 source lock，finding 视图显示 `source-lock-deprecated`；非法当前知识引用由 schema/check fail closed；
+- HTML 中英按钮覆盖废弃负责人、时间与理由标签，机器 ID、digest、path 和审计值保持原样；
+- 不嵌入来源正文，不增加 store、写入、网络、框架识别、projection target 或自动维护。
+
+A-44 已验证 JSON/HTML、checker、context 与 deprecated source 语义一致；A-31 至 A-38 和全部既有测试继续通过。

package/docs/14-FORMAL-RELEASE-READINESS.md

@@ -0,0 +1,61 @@
+# 14 — `1.0.0` 正式发布准备
+
+> 状态：`public-npm-release-authorized-configured-authenticated-ready`
+
+## 1. 冻结候选
+
+- npm candidate：`frontend-project-context@1.0.0`
+- executable：`project-context`
+- runtime：Node.js 18+，零第三方依赖
+- license：Apache-2.0，`Copyright 2026 Fushan`
+- public compatibility surface：README 与 help 中记录的 CLI
+- internal implementation：`src/project-context/` 不作为稳定 import API
+
+`1.0.0` 只封装已经通过团队维护验收的 v1，不新增产品能力、store、source kind、projection target 或运行时。
+
+## 2. 包内容
+
+发布白名单为 `bin/`、`src/`、`docs/`、`examples/`、README、CHANGELOG、UPGRADING、PROJECT_STATE、RTK、LICENSE、NOTICE 和 package metadata。PROJECT_STATE 与 RTK 只用于保持包内文档链接完整，不成为消费项目的 Contract。测试、本仓库自托管 `.project-context/`、Git 文件、本地 dashboard、proposal 和 tarball 不进入包。
+
+`prepack` 必须先运行 `npm run check`；bin 必须保持可执行。实际 pack 使用临时 cache 与输出目录验证，不修复用户全局 npm cache。
+
+## 3. 项目与 CI 接入
+
+项目将固定版本作为 devDependency，并通过自己的 `context:check` 脚本调用 CLI。CI 只运行锁定依赖和只读检查，不包含 `--write`、source acceptance、approval、projection publish 或 package publish。最小文件见 [examples](../examples/README.md)。
+
+应提交：三个 `.project-context` store 文件，以及团队明确采用且仍由工具拥有的 AGENTS/Ruler/Markdown 投影。
+
+默认忽略：proposal、dashboard HTML/JSON、临时 Context Bundle、tarball、node_modules、缓存和日志。
+
+## 4. 兼容与升级
+
+`0.9.0 → 1.0.0` 不要求预先迁移。Contract reader 支持 schema 1/2，schema 1 仅在首次成功废弃来源时延迟升级为 2；proposal、source lock、projection lock 保持 schema 1。renderer 1/2 仍可读且 stale，显式 owned publish 才升级到 renderer 3；Dashboard JSON consumer 必须支持 View Model schema 3。详见 [UPGRADING.md](../UPGRADING.md)。
+
+## 5. A-39 与本地验证
+
+A-39 固定以下事实：package metadata 与文件白名单一致；Apache-2.0 LICENSE/NOTICE 完整入包；bin 可执行；CI 模板只读；发布资料齐全。未授权阶段验证 `private: true`；公开发布授权后验证 `private: false`、官方 npm registry 与 public access。发布准备还必须通过：
+
+1. `npm run check` 全量 49 项；
+2. `npm pack` 输出清单审查；
+3. 解包后直接运行 CLI help；
+4. 使用解包后的 CLI 在临时项目完成 init 与 clean check；
+5. JSON、Markdown links 与 diff 校验。
+
+## 6. 已授权的公开发布与当前阻断
+
+用户已明确要求完成发布，本次按先前推荐选择 public npm：
+
+1. package 使用 `private: false`；
+2. `publishConfig.registry` 固定 `https://registry.npmjs.org/`，避免误用机器默认公司 Nexus；
+3. `publishConfig.access` 固定 `public`；
+4. release commit/tag/push 与 `npm publish` 纳入本次发布工作流。
+
+只读查询已确认 `frontend-project-context` 在公共 npm 返回 404，可作为首次发布名称；发布者随后在自己的终端完成认证，`npm whoami --registry=https://registry.npmjs.org/` 已验证为 `fushanyx1`。凭据、OTP 和 token 未由本项目或自动化读取。
+
+## 7. 后续审查产生的发布保持条件
+
+重大项目调整场景的系统性审查曾确认：原 RC 无法通过稳定 CLI 废弃 missing/搬迁/永久退役的已登记 source，最终仍需直接编辑内部 JSON。该问题已经按 [15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md](./15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md) 的冻结范围实现，并通过 A-40 至 A-45 与全部回归。
+
+Source Lifecycle Closure 发布保持条件已经本地关闭。2026-09-08 使用隔离临时 npm cache 重新执行第 5 节：prepack 49/49 通过，tarball 白名单为 47 个文件；解包后的 CLI help、临时项目 init 和 clean check 通过。最初一次 pack 仅因用户级 npm cache 中历史 root-owned 文件产生 `EPERM`，未修改全局权限，改用临时 cache 后成功，产品验收不受影响。
+
+registry/可见性决策和发布者认证已经完成。Apache-2.0 和包名不变；当前进入最终 A-39/pack、release commit、`v1.0.0` tag/push 与 public `npm publish`。