docs: 统一 SPEC 预期终态规则

2026-07-13 08:44:08 +02:00
parent cf8630a701
commit f1a0411ec8
13 changed files with 431 additions and 274 deletions
@@ -9,9 +9,24 @@ HWLAB Cloud M1 / UniDesk / AgentRun 跨仓项目治理锚定在 UniDesk 仓库

 ## 高频规则

- 项目管理 stable source of truth 在 `project-management/PJ2026-01/`，GitHub issue 承载执行流和证据索引。
+- 项目管理稳定事实源按项目编号维护在 `project-management/PJ*/`，GitHub issue 承载执行流和证据索引。
 - 重大项目/方向/课题/子课题层级、任务书、实施方案、测试规格、阶段报告和项目偏离按项目编号目录维护。
 - 形成多阶段实施、架构或长期 API/数据模型时，先 SPEC，再实现和 issue 阶段计划。
+- SPEC 规范性正文只定义预期终态：
+  - 目标能力；
+  - 稳定边界；
+  - 目标架构、数据流和接口；
+  - 原子需求；
+  - 验收契约。
+- SPEC 不得写入执行态内容：
+  - 当前实现状态或能力基线；
+  - 已完成、未完成和当前阻塞；
+  - 临时运行面、本轮差距和一次性证据；
+  - 源码路径、作业编号、日志、截图或样片清单。
+- 规格生命周期状态与实现进度必须分离：
+  - 文档控制可以记录规格已生效、未生效或已废弃；
+  - 不得在 SPEC 中增加“实现状态”字段或用目标需求宣称能力已经上线。
+- 当前状态进入阶段报告、任务报告、偏离记录或 GitHub issue；验证证据只从这些执行态载体引用 SPEC，不反向写入 SPEC 正文。
 - GitHub issue/PR 写入仍走 `$unidesk-gh`；正文必须写目标合并分支/lane。

 ## Reference 路由
@@ -22,6 +37,6 @@ HWLAB Cloud M1 / UniDesk / AgentRun 跨仓项目治理锚定在 UniDesk 仓库
 ## 常用检查

 ```bash
-find project-management/PJ2026-01 -maxdepth 3 -type f | sort
+find "project-management/${PJ_ID:?请先设置 PJ_ID}" -maxdepth 3 -type f | sort
 bun scripts/cli.ts gh issue list --repo pikasTech/unidesk --state open --limit 30
 ```
@@ -1,4 +1,4 @@
 interface:
  display_name: "UniDesk OA"
-  short_description: "管理 UniDesk 项目规格目录和 issue 层级。"
-  default_prompt: "使用本技能规划 project-management/PJ2026-01 项目结构、总规格和相互链接的 GitHub issue 执行记录。"
+  short_description: "管理 UniDesk 项目终态规格、层级与执行态报告"
+  default_prompt: "使用 $unidesk-oa 为指定项目编号维护预期终态 SPEC，并把当前状态放入报告或 issue。"
@@ -20,6 +20,19 @@ HWLAB Cloud M1 需要一个项目控制结构，避免局部 issue/PR 工作偏
 - 决策依据。
 - 稳定验收标准。

+SPEC 只承载预期终态：
+
+- 目标能力和稳定责任边界。
+- 目标架构、数据流、接口和原子需求。
+- 可重复执行的验收契约。
+- 规格生命周期状态可以记录已生效、未生效或已废弃，但不等于实现进度。
+
+SPEC 不承载执行态：
+
+- 当前实现状态、阶段基线和本轮差距。
+- 已完成、未完成、当前阻塞和临时运行面。
+- 源码路径、commit、PR、作业、日志、截图、样片或一次性验收证据。
+
 用 issue 承载执行状态：

 - 当前负责人和状态。
@@ -30,11 +43,16 @@ HWLAB Cloud M1 需要一个项目控制结构，避免局部 issue/PR 工作偏
 - 收口评论。
 - 长证据索引、CaseRun registry、运行日志、历史 issue 摘要。

-不要把稳定需求的唯一副本放在 issue 评论里。长期有效的需求必须蒸馏到 `project-management/PJ2026-01`，再从 issue 链接过去。
+阶段报告、任务报告和偏离记录承载跨 issue 的状态汇总。不得为了保存执行进度，把这些内容回填到 SPEC 规范性正文。
+
+不要把稳定需求的唯一副本放在 issue 评论里。长期有效的需求必须蒸馏到对应 `project-management/PJ*/` 项目编号目录，再从 issue 链接过去。
 不要把长证据正文放进项目管理目录。项目管理目录只承载规格、治理和阶段中心；长证据保留在 GitHub issue。
 规格文件和 GitHub issue 的引用规则分开处理：

- `project-management/PJ2026-01/specs/*.md` 不保留单独的迁移来源块；历史来源只写在修改历史 `v0.1` 变更说明中，格式为 `迁移来源 <owner>/<repo>#<number>`。
+- 规格文件不保留单独的迁移来源块：
+  - 范围是 `project-management/PJ*/specs/*.md`；
+  - 历史来源只写在修改历史 `v0.1` 变更说明中；
+  - 格式为 `迁移来源 <owner>/<repo>#<number>`。
 - 规格文件引用其他规格时，使用同目录相对路径 Markdown 链接，例如 `[PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md)`；不要引用其他规格的 GitHub issue、证据 issue、PR 或裸 `#<number>`。
 - GitHub issue/PR 正文和评论中的 issue/PR 引用必须写成 `[#<number>](https://github.com/<owner>/<repo>/issues/<number>)` 或 `[#<number>](https://github.com/<owner>/<repo>/pull/<number>)`，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 `owner/repo` 加井号编号。`owner/repo#number` 只允许作为 CLI 命令参数 shorthand。

@@ -48,6 +66,7 @@ P0 SPEC 必须完成：
 - 按模板写清文档控制、目的和范围、术语表、系统边界、内部分工、原子需求和过程控制。
 - 为涉及实现架构的数据面补齐目标架构图、数据流图和关键时序图；图形优先使用 Markdown 内嵌 `mermaid`。
 - 在 SPEC 中写明后续代码文件头部应标注的 SPEC 编号、短名和实现引用版本。
+- 把正文写成预期终态，不以当前实现、阶段基线或未完成清单解释目标。

 后续代码阶段只能在 P0 SPEC 明确后开始。后续讨论改变稳定需求、数据流、接口或验收口径时，先更新 SPEC，再更新 issue 计划。该规划型 issue 范围内新增或修改的源码文件，文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本；自动生成文件、第三方 vendored 文件、纯配置、锁文件和不能承载注释头的二进制产物可例外，但对应生成器、渲染器或配置入口必须能追溯到 SPEC。

@@ -103,15 +122,15 @@ specs/spec-governance.md                 # 编号、层级、回写与偏离规

 | 层级 | 负责 | 不负责 | 回写到 |
 | --- | --- | --- | --- |
-| L0 | 使命、非目标、当前中心、L1 方向树、全局验收、偏离规则 | PR 细节、CaseRun 日志、日报流水、实现设计 | `project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md` 和 L1 issue |
+| L0 | 使命、非目标、预期终态、方向树、全局验收 | 当前中心、PR/CaseRun/日报与实现设计 | L0 规格和 L1 issue |
 | L1 | 能力域范围、成功标准、L2 课题清单、原始验收类型 | 单个 PR、一次性 smoke、仓库/工具/运行面名称、项目管理动作 | L0 规格和对应 L1 规格文件 |
-| L2 | 一个 L1 内的具体课题、交付物、阻塞项、验证计划 | 宽泛能力域或实现细节流水 | L1 issue，重大移动再回写 L0 |
+| L2 | 一个 L1 内的具体课题、目标交付物和验证计划 | 当前阻塞、宽泛能力域或实现细节流水 | L1 issue，重大移动再回写 L0 |
 | L3 | 一个有界验收切片和单一验收路径 | 路线图、多课题计划、父级范围变化 | L2/L1 issue 并带证据 |
 | L4 | 具体执行：PR、CaseRun、smoke、部署、文档收口 | 新需求、新方向、验收规则变化 | 最近的 L3/L2/L1，并带原入口证据 |

 分类规则：

- 改变使命、当前中心、L1 列表或全局验收的，属于 L0。
+- 改变使命、预期终态、L1 列表或全局验收的，属于 L0。
 - 定义可以容纳多个课题的稳定能力域的，属于 L1。
 - 在一个方向内规划具体工作计划的，属于 L2。
 - 可以通过一个有界路径验收的，属于 L3。
@@ -122,7 +141,7 @@ specs/spec-governance.md                 # 编号、层级、回写与偏离规
 L0 定义：

 - 使命和非目标。
- 当前工作重心。
+- 预期终态。
 - 产品入口。
 - 方向列表。
 - 全局验收标准。
@@ -139,10 +158,10 @@ L1 方向是直接服务 L0 使命的顶层能力域，不是项目管理工件
 每个方向必须回答：

 - 它服务 L0 目标的哪一部分。
- 什么状态算完成。
+- 什么终态算完成。
 - 涉及哪些仓库、分支、lane。
 - 哪个原始用户/运行面入口可以验收它。
- 当前重要的 L2 课题有哪些。
+- 目标 L2 课题有哪些。

 以下内容不能作为 L1 方向：

@@ -158,7 +177,7 @@ L1 方向是直接服务 L0 使命的顶层能力域，不是项目管理工件
 - 主责不清楚时，问“什么证据能关闭这个 issue”：硬件资源就绪、Agent 执行生命周期、Harness/RL 证据、客户端/API 行为、用户/管理策略，还是平台交付/运维。
 - 先按完成标准判断主责，再看实现表面。CLI、Web 页面、HTTP API、hwpod 工具或服务路由不会自动归入 `客户端`；它们主归属定义正确性的领域。只有当完成标准是 Web、CLI、HTTP API 的入口行为、用户交互、兼容性或输出格式时，`客户端` 才是主责 L1。

-HWLAB Cloud M1 当前 L1 职责矩阵：
+HWLAB Cloud M1 L1 职责矩阵：

 | 编号 | 短名 | 主责 | 不负责 | 交接示例 |
 | --- | --- | --- | --- | --- |
@@ -189,7 +208,7 @@ HWLAB Cloud M1 当前 L1 职责矩阵：

 ### 硬件池 L2 标准

-`PJ2026-0101 硬件池` 当前 L2 拆分为：
+`PJ2026-0101 硬件池` L2 拆分为：

 | 编号 | 短名 | 主责 | 关联 L1 | 边界 |
 | --- | --- | --- | --- | --- |
@@ -1,5 +1,13 @@
 # UniDesk OA 模板

+## SPEC 正文边界
+
+- SPEC 只写预期终态、目标能力、稳定边界和验收契约。
+- 文档控制中的“状态”只表示规格生命周期，不表示实现进度。
+- SPEC 不增加“实现状态”“当前基线”“当前阻塞”或“已完成能力”章节。
+- 当前状态、阶段差距和实现证据进入阶段报告、任务报告、偏离记录或 GitHub issue。
+- 源码路径、commit、PR、作业、日志、截图和样片清单不得作为 SPEC 规范性正文。
+
 ## L0 总规格骨架

 ```markdown
@@ -9,9 +17,9 @@

 | 版本 | 对应 commit id | 更新日期 | 变更说明 |
 | --- | --- | --- | --- |
-| v0.1 | <commit> | <YYYY-MM-DD> | 创建需求规格；如来自历史 issue，只在这里写迁移来源 <owner>/<repo>#<number>。 |
+| v0.1 | <commit> | <YYYY-MM-DD> | 创建预期终态需求规格；如来自历史 issue，只在这里写迁移来源 <owner>/<repo>#<number>。 |

-当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。

 ## 正文

@@ -24,7 +32,7 @@
 | 编号 | PJ2026-01 |
 | 短名 | HWLAB |
 | 层级 | L0 总项目 |
-| 状态 | 已生效、已废弃或未生效 |
+| 规格状态 | 已生效、已废弃或未生效；只表示规格生命周期 |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
 | 规格治理索引 | [规格治理](spec-governance.md) |