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

v0.2 文档治理规格

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

实施和历史归档见 pikasTech/HWLAB#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。
• D601 只允许作为 legacy 事故回放、迁移对照或 Windows 硬件 bridge 背景出现在长期参考中；不得作为当前 v0.2 发布、验收或权限规格。
• 任何根文档或计划文档如果仍把 D601、旧 DEV gate、旧 main、旧 16666/16667 或 simulator/patch-panel 写成当前规格，应删除或改为引用新 spec。

本次收敛映射

被删除来源	处理
README.md	有效入口信息已由 AGENTS.md、architecture.md、dev-runtime-boundary.md 和 spec-v02-services.md 承接；全文归档到 #532。
docs/cloud-web-workbench.md	稳定前端约束由 cloud-workbench.md 承接；全文归档到 #532。
docs/dev-acceptance-matrix.md、docs/dev-gate-*、docs/dev-evidence-*	旧 DEV/D601 gate 和报告材料仅作历史归档；当前边界见 dev-runtime-boundary.md、MVP-e2e-acceptance.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。
docs/topology-constraints.md	simulator/patch-panel 旧拓扑规格与 v0.2 裁撤口径冲突；当前服务取舍见 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 评论；长期规格见 spec-v02-cicd.md。
docs/plan/v02-multi-user-migration.md	全文迁入 pikasTech/HWLAB#531 评论；长期规格见 spec-user-access.md。
旧设备执行规格和旧 MVP plan	旧路线只保留在对应 issue 历史评论；当前长期规格见 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。