diff --git a/AGENTS.md b/AGENTS.md index 460c99ce..77ffd7a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - 长期参考入口：[docs/reference/README.md](docs/reference/README.md) - 中文优先规则：[docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md) - 用户反馈分流规则：[docs/reference/user-feedback-triage.md](docs/reference/user-feedback-triage.md) -- 文档治理与 docs-spec 入库规则：[docs/reference/documentation-governance.md](docs/reference/documentation-governance.md) +- 文档治理与 docs-spec 本地权威：[docs/reference/documentation-governance.md](docs/reference/documentation-governance.md) - 架构和 M3 主线：[docs/reference/architecture.md](docs/reference/architecture.md) - DEV 运行态、端口、k3s 和 DB DNS 边界：[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md) - 部署正规化、镜像发布、回滚和 Cloud Web 路径：[docs/reference/deployment-publish.md](docs/reference/deployment-publish.md) @@ -33,6 +33,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - 中文优先：issue、PR 正文、长期参考文档和用户可见说明默认用中文；英文术语只在命令、协议、接口、ID、路径和标准名需要保真时保留，详见 [docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md)。 - 用户反馈优先：用户和参谋提出的问题默认按高优先级用户反馈处理，blocker 状态不能替代反馈分流，必须挂到 [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7) 醒目位置，详见 [docs/reference/user-feedback-triage.md](docs/reference/user-feedback-triage.md)。 +- docs-spec 本地权威优先：涉及 `AGENTS.md`、`docs/reference/*.md` 或过程文档蒸馏时，先按 [docs/reference/documentation-governance.md](docs/reference/documentation-governance.md) 执行，不另建同级规则副本。 - PR 工作流优先：从最新 `origin/main` 创建短分支，提交 PR 到 `pikasTech/HWLAB:main`，runner 不直推 `main`、不合并 PR、不改 PROD、不重启服务，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 ## 常用轻量命令 diff --git a/docs/reference/README.md b/docs/reference/README.md index abe80c48..c5173d80 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -6,7 +6,7 @@ | 规则 | 唯一权威出处 | 边界 | | --- | --- | --- | -| `docs-spec` 使用、长期参考入库和过程文档蒸馏 | [documentation-governance.md](documentation-governance.md) | 其他 reference 只交叉引用，不另写一套文档治理规则。 | +| `docs-spec` 本地权威、长期参考入库和过程文档蒸馏 | [documentation-governance.md](documentation-governance.md) | 该文件等价承担 `docs/reference/docs-spec.md` 的职责；其他 reference 只交叉引用，不另写一套文档治理规则。 | | 中文优先的 issue、PR 和文档规则 | [chinese-first-documentation.md](chinese-first-documentation.md) | 英文标识可保真，解释、约束和验收口径必须中文化。 | | 用户和参谋反馈默认高优先级分流 | [user-feedback-triage.md](user-feedback-triage.md) | `blocked`、等待上游或环境限制只描述状态，不能替代反馈优先级。 | | 指挥官一手事实、真实推进和 PR 协作边界 | [commander-collaboration.md](commander-collaboration.md) | 本目录的文档治理规则不覆盖 [pikasTech/HWLAB#131](https://github.com/pikasTech/HWLAB/issues/131) 的指挥作风边界。 | @@ -17,7 +17,7 @@ | --- | --- | | 中文优先规则 | [chinese-first-documentation.md](chinese-first-documentation.md) | | 用户反馈分流规则 | [user-feedback-triage.md](user-feedback-triage.md) | -| 文档治理与 docs-spec 入库规则 | [documentation-governance.md](documentation-governance.md) | +| 文档治理与 docs-spec 本地权威 | [documentation-governance.md](documentation-governance.md) | | 架构和 M3 上位约束 | [architecture.md](architecture.md) | | DEV 运行态、端口、k3s、DB readiness 和环境边界 | [dev-runtime-boundary.md](dev-runtime-boundary.md) | | 部署正规化、artifact 发布、回滚和 Cloud Web rollout | [deployment-publish.md](deployment-publish.md) | @@ -33,7 +33,7 @@ - [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78)：`DC-DCSN-P0-2026-003`，M3 虚拟硬件可信闭环方向和上位约束。 - [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121)：issue 和长期文档中文化要求。 - [pikasTech/HWLAB#122](https://github.com/pikasTech/HWLAB/issues/122)：用户和参谋反馈默认按高优先级用户反馈处理，并挂到 `#7`。 -- [pikasTech/HWLAB#123](https://github.com/pikasTech/HWLAB/issues/123)：docs-spec 规则必须固化进 HWLAB 长期参考文档。 +- [pikasTech/HWLAB#123](https://github.com/pikasTech/HWLAB/issues/123)：docs-spec 规则必须固化进 HWLAB 长期参考文档；本仓库由 [documentation-governance.md](documentation-governance.md) 作为等价本地权威。 - [pikasTech/HWLAB#131](https://github.com/pikasTech/HWLAB/issues/131)：指挥作风纠偏、一手事实优先和真实推进规则。 - [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99)：Cloud Workbench 默认前端方向。 - [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108)：禁止外层页面纵向滚动、中文 UI 和内部 Markdown 帮助页。 diff --git a/docs/reference/documentation-governance.md b/docs/reference/documentation-governance.md index e74de27d..a0aee3cf 100644 --- a/docs/reference/documentation-governance.md +++ b/docs/reference/documentation-governance.md @@ -1,6 +1,6 @@ # HWLAB 文档治理与 docs-spec 入库规则 -本文是 HWLAB 仓库内固化的 `docs-spec` 规则副本和可执行摘要，也是本仓库唯一维护 `docs-spec` 使用规则的长期参考。编辑 `AGENTS.md`、`docs/reference/*.md` 或把过程记录蒸馏为长期参考时，必须先按本文执行；如果 runner 能读取外部 `docs-spec` skill，也要以本文作为 HWLAB 本地权威落点。 +本文是 HWLAB 仓库内固化的 `docs-spec` 规则副本和可执行摘要，也是本仓库唯一维护 `docs-spec` 使用规则的长期参考。它等价承担 `docs/reference/docs-spec.md` 的职责；不要再新增同级 `docs-spec` 规则副本，避免多处口径漂移。编辑 `AGENTS.md`、`docs/reference/*.md` 或把过程记录蒸馏为长期参考时，必须先按本文执行；如果 runner 能读取外部 `docs-spec` skill，也要以本文作为 HWLAB 本地权威落点。 中文优先规则只在 [chinese-first-documentation.md](chinese-first-documentation.md) 维护，用户和参谋反馈分流规则只在 [user-feedback-triage.md](user-feedback-triage.md) 维护。本文只交叉引用这些规则，不替代 [commander-collaboration.md](commander-collaboration.md) 中由 [pikasTech/HWLAB#131](https://github.com/pikasTech/HWLAB/issues/131) 固化的一手事实和真实推进边界。 @@ -40,7 +40,7 @@ ## 本地入库和同步机制 -- 本文保留外部 `docs-spec` 的完整核心规则，使没有 skill 可见性的 runner 仍能执行 HWLAB 文档治理。 +- 本文保留外部 `docs-spec` 的完整核心规则，使没有 skill 可见性的 runner 仍能执行 HWLAB 文档治理；它是 `#123` 要求的 repo 内权威落点。 - 每次任务涉及 `AGENTS.md`、`docs/reference/*.md` 或过程文档蒸馏时，runner 应先读取外部 `docs-spec` skill；如果外部规则与本文不同，必须在同一 PR 中同步更新本文并说明差异。 - 如果外部 skill 不可读，按本文执行，并在 PR body 中说明“使用仓库内 docs-spec 固化规则，外部 skill 不可用或未校验”。 - `docs/reference/README.md` 是长期参考入口；新增 reference 后必须更新该索引和 `AGENTS.md`。 @@ -51,7 +51,7 @@ - `#78` / `DC-DCSN-P0-2026-003` 是 M3 虚拟硬件可信闭环上位约束。 - `#121` 要求 issue 和长期文档中文化。 - `#122` 要求用户和参谋反馈默认高优先级并挂到 `#7`。 -- `#123` 要求 docs-spec 规则固化进 HWLAB 长期参考文档，而不是只在 issue 里引用外部 skill。 +- `#123` 要求 docs-spec 规则固化进 HWLAB 长期参考文档，而不是只在 issue 里引用外部 skill；本文就是该规则的等价本地文档。 - 当前 HWLAB 的 `16666/16667`、D601 工作区、M3 证据、Cloud Workbench 默认路由和 PR 工作流，分别由本目录的专项 reference 维护。 ## docs-spec 原文副本