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

HWLAB 文档治理与 docs-spec 入库规则

本文是 HWLAB 仓库内固化的 docs-spec 规则副本和可执行摘要，也是本仓库唯一维护 docs-spec 使用规则的长期参考。它等价承担 docs/reference/docs-spec.md 的职责；不要再新增同级 docs-spec 规则副本，避免多处口径漂移。编辑 AGENTS.md、docs/reference/*.md 或把过程记录蒸馏为长期参考时，必须先按本文执行；如果 runner 能读取外部 docs-spec skill，也要以本文作为 HWLAB 本地权威落点。

v0.2 文档树的额外收敛规格见 spec-v02-documentation-governance.md。该规格禁止仓库保留根 README.md、docs/*.md、docs/*.json 和 docs/plan/*.md 作为长期或过程文档入口；计划、里程碑和一次性记录必须迁入 GitHub issue。

中文优先规则只在 chinese-first-documentation.md 维护，用户和参谋反馈分流规则只在 user-feedback-triage.md 维护。本文只交叉引用这些规则，不替代 commander-collaboration.md 中由 pikasTech/HWLAB#131 固化的一手事实和真实推进边界。

AGENTS.md 规则

• AGENTS.md 是 agent、指挥官和 runner 的唯一入口，用于快速定位命令、入口和长期参考文档。
• 与 AGENTS.md 同等作用的文档，例如 README.md、docs/reference/README.md、CLAUDE.md，不得作为入口或索引；v0.2 不保留这类二级入口，历史内容迁入 issue 或吸收到对应 reference。
• 每个命令在 AGENTS.md 中只保留一条主索引；参数、背景、判定标准写入链接的 reference 文档。
• AGENTS.md 的主标题、章节名和列表摘要必须中文优先；Agent、runner、Cloud Workbench、命令和路径等可保留原文，但要放在中文语境中解释。
• 每个列表项只描述一个功能点，用一句中文概括，不在顶层展开实现细节。
• AGENTS.md 必须直接索引中文优先、用户反馈分流、PR 工作流、#78 上位约束和各专项 docs/reference/*.md，不得再通过 README.md 二级入口跳转。

docs/reference 长期参考规则

• docs/reference/ 只记录长期稳定、可重复复用的入口、前置条件、约束和判定标准。
• 不写日期化日报、一次性过程记录、实测流水账、容易过时的 changelog 或临时 blocked 记录。
• 每个功能点优先对应 docs/reference/ 下的独立 Markdown 文档；AGENTS.md 只链接和摘要。
• 功能需要补充说明时，先更新 reference 详细文档，再更新 AGENTS.md 的一句话摘要。
• 知识更新遵循：增加新稳定知识、删除过时知识、修正错误知识、合并重复知识。
• 跨文档重复时，选择一个 reference 作为唯一权威出处，其他文档交叉引用它。
• 涉及 skill 的 reference 必须说明该 skill 与 HWLAB 代码、硬件、目录和验收标准的关系；通用 CLI 用法直接引用 skill，不在仓库内复制成另一份通用手册。

过程文档蒸馏规则

• 过程文档是历史资料，通常带时间戳，时效性强，不能直接进入长期参考。
• 蒸馏只提取稳定结论、边界、验收标准和禁止事项。
• 计划、plan、里程碑、阶段迁移、一次性报告和旧 gate 文档全文迁入 GitHub issue；仓库内不再维护 docs/plan/*.md。
• 不篡改过程文档；过程记录是原始来源。
• 大文件按滑动窗口阅读，读一段就提炼稳定结论，不等全部读完才更新 reference。
• 新稳定结论覆盖旧冲突结论；旧过程只作为历史来源。
• 可以简述重要发展脉络，但不能把长期参考写成流水账。

中文和反馈治理

• 中文优先规则见 chinese-first-documentation.md；长期参考必须中文主导。
• 用户和参谋反馈分流规则见 user-feedback-triage.md；默认按高优先级用户反馈处理并挂到 #7。
• 影响 M3 判定的文档必须显式对齐 DC-DCSN-P0-2026-003 / #78，不得把 SOURCE、LOCAL、DRY-RUN、fixture、edge-only health 或前端状态写成 M3 DEV-LIVE。
• 影响发布、运行态、端口和 PR 流程的规则必须交叉引用对应 reference，不在多个文档里各写一套。

本地入库和同步机制

• 本文保留外部 docs-spec 的完整核心规则，使没有 skill 可见性的 runner 仍能执行 HWLAB 文档治理；它是 #123 要求的 repo 内权威落点。
• 每次任务涉及 AGENTS.md、docs/reference/*.md 或过程文档蒸馏时，runner 应先读取外部 docs-spec skill；如果外部规则与本文不同，必须在同一 PR 中同步更新本文并说明差异。
• 如果外部 skill 不可读，按本文执行，并在 PR body 中说明“使用仓库内 docs-spec 固化规则，外部 skill 不可用或未校验”。
• 本仓库覆盖外部通用 docs-spec 中的 README 入口口径：新增 reference 后只更新对应 reference 和 AGENTS.md，不得新增或维护 README.md / docs/reference/README.md 入口。

HWLAB 当前应用

• #7 是指挥官看板和用户反馈集中入口。
• #78 / DC-DCSN-P0-2026-003 是 M3 虚拟硬件可信闭环上位约束。
• #121 要求 issue 和长期文档中文化。
• #122 要求用户和参谋反馈默认高优先级并挂到 #7。
• #123 要求 docs-spec 规则固化进 HWLAB 长期参考文档，而不是只在 issue 里引用外部 skill；本文就是该规则的等价本地文档。
• #532 是 v0.2 文档治理规格和被删除根文档/过程文档的全文归档入口；当前收敛规格见 spec-v02-documentation-governance.md。
• 当前 HWLAB 的 node/lane 工作区、运行面入口、M3 证据、Cloud Workbench 默认路由和 PR 工作流，分别由本目录的专项 reference 与受控 lane 配置维护；D601 legacy 只指旧 DEV/CD、迁移对照和事故回放路径，D601 v0.3 这类 issue/CLI 明确的 node-scoped runtime lane 不属于 legacy。

docs-spec 原文副本

以下副本来自当前 runner 可见的 docs-spec skill，用于满足 #123 的本地固化要求。后续如果外部 skill 更新，应按“本地入库和同步机制”同步。

---
name: docs-spec
description: 用于指导 docs 的文档规范，编辑 CLAUDE.md/AGENTS.md 或者 docs/reference/*.md 或者进行过程文档蒸馏时必须加载本 SKILL
---

- `AGENTS.md` 只作为项目级顶级索引，用于快速定位命令、入口和文档。
    - 其他和 `AGENTS.md` 具有同等作用的文档（例如 CLAUDE.md )中只写入一行 `@AGENTS.md` 将其引导到 `AGENTS.md`，避免多种口径互相不一致。
    - 每个命令在 `AGENTS.md` 中保留一条主索引，命令下面可以挂多个功能子列表。
    - 每个子列表只描述一个功能点，并使用一句话概括，不在此处展开实现细节、参数说明或背景分析。
- docs/reference 长期参考文档
    - `docs/reference/` 只记录长期稳定、可重复复用的入口、前置条件、约束和判定标准；不要写日期、一次性过程记录、实测流水账或容易过时的 changelog 式内容。
    - 每个子列表应独立对应一个 `docs/reference/` 下的参考文档；如果同一命令包含多个功能，则分别链接到各自文档。
    - 所有功能的详细说明统一写入 `docs/reference/` 下的独立 Markdown 文档，并在 `AGENTS.md` 中提供对应链接索引。
    - 当某项功能需要补充说明时，优先更新 `docs/reference/` 的详细文档，再回到 `AGENTS.md` 维护对应子列表的一句话摘要与链接。
    - 知识更新原则 - 增加新知识、删除过时知识、修改错误知识、合并重复知识
        - 避免重复 - 对于同文档重复的内容应当进行合并，对于跨文档重复的内容，应当选择或者新建一个文档作为唯一权威出处，其他文档交叉引用权威出处。
    - `docs/reference/` 中涉及 skill 的文档，必须突出该 skill 与当前项目代码、硬件、目录和判定标准的具体联系；通用安装、CLI 参数、子命令和完整用法直接交叉引用对应 skill 的 `SKILL.md`，不要在 reference 中重复抄写一份通用说明。
- 过程文档蒸馏
  - 过程文档指的是开发过程中的过程记录，通常带有时间戳，特征是时效性明显，容易过时，代表了系统的发展和转变过程。
  - 过程文档蒸馏指的是将过程文档蒸馏为长期参考文档。
  - 蒸馏原则
    - 从旧到新原则 - 先从旧的过程文档开始整理，然后逐渐处理新的。
      - 滑动窗口 - 对于大的过程文档文件，采用滑动窗口策略，读一定长度（例如 500 行）就更新一次长期参考文档，不要全部读完再更新。
    - 新的覆盖旧的 - 新的过程文档有更高的重要性，在新的和旧不一致时，应当以新的替换旧的。
    - 简述发展过程 - 在长期参考文档中用简短的篇幅描述总体的发展过程 OUTLINE。
      - 避免将发展过程写成流水账。
      - 越早期的发展过程越简略地写。
      - 重要的发展过程节点可以交叉引用过程文档。
  - 不要篡改过程文档 - 过程文档是一手的历史资料，禁止对过程文档进行篡改。