pikasTech-HWLAB/docs/reference/spec-v02-documentation-governance.md

# v0.2 文档治理规格

本文是 HWLAB `v0.2` 文档体系的长期规格。它定义哪些文档可以留在仓库、哪些过程材料必须迁入 GitHub issue、旧 D601/G14 口径如何处理，以及 `docs/` 根目录不得再堆放 Markdown 或 JSON 的收敛规则。

实施和历史归档见 [pikasTech/HWLAB#532](https://github.com/pikasTech/HWLAB/issues/532)。本文只记录稳定规则；被迁移文档的全文在 issue 评论中按源路径归档。

## 设计目标

- `AGENTS.md` 是唯一顶级入口；不再维护根 `README.md` 或 `docs/reference/README.md`。
- `docs/reference/` 是长期参考唯一目录，只放规格、约束、入口、判定标准和稳定 runbook。
- `v0.2` 专项长期规格必须使用 `spec-` 前缀，例如 `spec-v02-cicd.md`、`spec-user-access.md`。
- 计划、里程碑、阶段推进、一次性排障、报告合同和历史验收材料不留在仓库文档树；全文迁入 GitHub issue 后删除源 Markdown。
- `docs/` 根目录不得直接放 `*.md` 或 `*.json`。机器契约放 `protocol/`、`deploy/` 或源码相邻目录；临时报告放 `/tmp`、`.state` 或 CI artifact。
- D601、旧 DEV gate、旧 `16666/16667`、M0-M5 里程碑和 simulator/patch-panel 旧规格只作为历史归档，不作为 `v0.2` 当前规格。

## 允许的文档形态

| 位置 | 允许内容 | 不允许内容 |
| --- | --- | --- |
| `AGENTS.md` | 入口索引、一句话规则、长期参考链接 | 详细设计、计划全文、过程记录、二级 README 口径 |
| `docs/reference/*.md` | 长期规格、稳定边界、判定标准、可复用 runbook | 日期化流水账、阶段计划、迁移 TODO 全文、临时 evidence、旧规格副本 |
| GitHub issue/PR | 计划全文、里程碑拆解、过程记录、一次性排障、执行证据 | 作为长期权威替代 `docs/reference` |
| `protocol/` / `deploy/` | 机器可消费 schema、deploy intent、GitOps 模板 | 人写过程报告、临时 JSON dump |
| `/tmp` / `.state` / CI artifact | 临时报告、运行输出、截图、trace dump | 需要长期复用的规格 |

## 迁移规则

1. 发现 `README.md`、`docs/*.md`、`docs/*.json` 或 `docs/plan/*.md` 时，先判断是否有长期价值。
2. 有长期价值的，只把稳定结论吸收到对应 `docs/reference/` 权威文档；不要整篇搬入 reference。
3. 属于计划、里程碑、阶段迁移、报告、一次性排障或历史验收的，全文迁入 GitHub issue body/comment，再删除源文件。
4. 属于旧规格且与当前 `v0.2` spec 冲突的，直接删除；必要时在新 spec 中用一句话说明旧口径已被替代。
5. 迁移后的 reference 必须引用相关 issue，尤其是规格尚未完全实现、仍需要 issue 承接实施步骤时。
6. GitHub issue/PR 写入必须走 UniDesk CLI `bun scripts/cli.ts gh ...`，不能直接用原生 `gh` 或手写 GitHub API。

## 当前状态沉淀规则

- 当当前实现状态和目标状态不同，`docs/reference/` 与 `spec-*.md` 必须分别标明：当前已经存在并应继续遵守的 runtime/source 权限链路，以及仍按 issue 收口的目标能力。不要把目标状态写成已完成，也不要把当前临时过程写成长期规则。
- 当前状态可以记录稳定服务组成、authority 链路、用户入口、SecretRef 边界和可复用判定标准；不要写 commit、日期、PR 流水、临时命令输出或一次性实测全文。
- 已移除的实现路径、断言、预检、兼容入口和门禁只保留在 issue/PR 证据中。长期参考中应替换为当前 authority 和删除规则，不维护已移除对象清单，也不把它们迁移成新的负向 gate。
- SPEC 的测试规格只表达当前目标行为。发现测试只保护历史路径时，直接删除或改写为当前 Web session/API key/OpenFGA/Admin Access 行为，不另建 legacy mode 或双路径验收。

## D601/G14 口径处理

- 当前 HWLAB DEV/PROD 真相是 G14 k3s、`G14`/`G14-gitops` 和 `hwlab-dev`/`hwlab-prod`。
- `v0.2` 真相是 `origin/v0.2`、`/root/hwlab-v02-cicd.git`、`devops-infra` git mirror/relay、`v0.2-gitops`、`hwlab-v02` 和 `19666/19667`；`/root/hwlab-v02` 只作为人工开发和短连接源码工具 workspace，权威规格见 [spec-v02-cicd.md](spec-v02-cicd.md)。
- D601 只允许作为 legacy 事故回放、迁移对照或 Windows 硬件 bridge 背景出现在长期参考中；不得作为当前 `v0.2` 发布、验收或权限规格。
- 任何根文档或计划文档如果仍把 D601、旧 DEV gate、旧 `main`、旧 `16666/16667` 或 simulator/patch-panel 写成当前规格，应删除或改为引用新 spec。

## 本次收敛映射

| 被删除来源 | 处理 |
| --- | --- |
| `README.md` | 有效入口信息已由 `AGENTS.md`、[architecture.md](architecture.md)、[dev-runtime-boundary.md](dev-runtime-boundary.md) 和 [spec-v02-services.md](spec-v02-services.md) 承接；全文归档到 #532。 |
| `docs/cloud-web-workbench.md` | 稳定前端约束由 [cloud-workbench.md](cloud-workbench.md) 承接；全文归档到 #532。 |
| `docs/dev-acceptance-matrix.md`、`docs/dev-gate-*`、`docs/dev-evidence-*` | 旧 DEV/D601 gate 和报告材料仅作历史归档；当前边界见 [dev-runtime-boundary.md](dev-runtime-boundary.md)、[MVP-e2e-acceptance.md](MVP-e2e-acceptance.md) 和 [spec-v02-cicd.md](spec-v02-cicd.md)。 |
| `docs/dev-acceptance-checklist.json` | 旧 M5 dry-run 机器 fixture 已退休并从源码移除；当前 v0.2 非视觉验收走 `hwlab-cli client` 真实 Cloud Web API。历史全文归档到 #532。 |
| `docs/m0-*`、`docs/m1-*`、`docs/m3-*`、`docs/m4-*`、`docs/m5-*`、`docs/operator-runbook.md` | 旧里程碑和 operator 阶段材料迁入 #532；当前 M3 判定见 [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md)。 |
| `docs/topology-constraints.md` | simulator/patch-panel 旧拓扑规格与 `v0.2` 裁撤口径冲突；当前服务取舍见 [spec-v02-services.md](spec-v02-services.md)。 |
| `docs/schema-drift-map.md` | 人写摘要归档到 #532；机器 source of truth 仍是 `protocol/schema-drift-map.json`。 |
| `docs/plan/hwlab-v02-namespace-cicd.md` | 全文迁入 [pikasTech/HWLAB#530](https://github.com/pikasTech/HWLAB/issues/530) 评论；长期规格见 [spec-v02-cicd.md](spec-v02-cicd.md)。 |
| `docs/plan/v02-multi-user-migration.md` | 全文迁入 [pikasTech/HWLAB#531](https://github.com/pikasTech/HWLAB/issues/531) 评论；长期规格见 [spec-user-access.md](spec-user-access.md)。 |
| 旧设备执行规格和旧 MVP plan | 旧路线只保留在对应 issue 历史评论；当前长期规格见 [spec-hwpod-harness.md](spec-hwpod-harness.md)。 |

## 验收标准

- `AGENTS.md` 索引本文，并且不再把 `README.md` 当入口。
- `find docs -maxdepth 1 -type f \( -name '*.md' -o -name '*.json' \)` 为空。
- `docs/plan` 不再包含仓库内计划 Markdown；后续计划写入 GitHub issue。
- `docs/reference/` 中不存在指向已删除根文档或 `docs/plan` 的相对链接。
- `D601` 只以 legacy/回放/bridge 背景出现在长期参考；不会作为 `v0.2` 当前规格或验收路径。
- 任何未完成规格都必须引用承接实施的 GitHub issue。