docs(workflow): complete H-414 cross-agent gates

2026-07-31 15:37:10 +08:00
parent adfe4e3d69
commit f4664266cc
7 changed files with 77 additions and 6 deletions
@@ -49,6 +49,18 @@
 6. **如果基线已坏，先修基线**，不要在坏的起点上叠新功能。
 7. 基线绿了，再从 `docs/tasks/` 为当前 agent 领取唯一任务（路线图见 [`06-tasks.md`](06-tasks.md)）；启用 Gitea 时由 dispatcher 串行分配并创建 claim 标记。

+## 工作模式（跨 Agent 通用）
+
+以下规则面向 Claude Code、Codex 及其他 coding agent。共享文档描述职责和交付约束，不绑定厂商、模型名称或平台专有的代理类型。
+
+- 默认采用**单任务、单责任 Agent、单写入者**：一个任务只有一个对结果负责的 Agent，同时只有一个 Agent 修改该任务的 `write_paths`。多 Agent 并行优先拆到写路径互不重叠的不同任务。
+- 复杂任务先规划再编码。确认后的方案、不可变约束、写路径和验收门禁必须写入当前任务文件，不能只停留在对话或平台的临时规划界面。
+- 范围明确时由责任 Agent 直接查证和执行；只有范围不清、需要跨目录扇出，且只读探索能明显减少试错时，才按当前平台能力使用只读探索。探索结果回填任务文件后再进入实现。
+- 任务内委派不是默认流程。只有项目规则显式允许且收益明确时才启用；委派后仍保持唯一写入者，执行者必须继承任务文件中的不可变约束、`write_paths` 和验证要求。
+- 无论是否委派，任务所有者都对最终结果负责，并按 [`05-coding-rules.md`](05-coding-rules.md) 独立审阅差异、重跑验证；不能把执行者或工具的自我报告当成完成证据。
+
+厂商或平台专属的模型分工、代理名称和权限配置，应只放在对应的本机配置或薄入口中；通用任务流程仍以仓库级规则和本目录文档为准。
+
 ## 当前阶段

 当前项目处于：【例如：MVP 起步 / 原型验证 / 功能开发 / 上线前收尾】。
@@ -40,7 +40,22 @@ npm run dev
 npm test
 ```

-## 四、依赖纪律
+## 四、验证矩阵与构建产物
+
+项目必须把验证分层写清，任务文件再按改动范围引用对应层级。不要让 agent 自行猜测“相关测试”或“完整验证”分别包含什么。
+
+| 层级 | 触发条件 | 命令 / 操作 | 通过证据 |
+| --- | --- | --- | --- |
+| 任务相关验证 | 每个任务必跑 | `【受影响模块的测试 / 静态检查 / 构建命令】` | 【退出码、测试数或关键断言】 |
+| 完整门禁 | 发布前；修改共享契约、依赖、构建配置或跨模块基础设施时；或任务明确要求时 | `【全量测试 / 全量 lint / 发布构建命令】` | 【退出码、测试数、构建产物】 |
+| 人工 / 设备验收 | 自动化无法替代的真机、硬件、外部账号、主观体验或受控环境验收 | `【操作步骤、执行角色、设备 / 环境】` | 【人工结论、截图 / 日志 / 记录位置】 |
+
+- 任务相关验证不能省略；是否触发完整门禁，必须依据上表和任务验收要点判断，不要求所有小改动无差别跑全量。
+- 必需的人工 / 设备验收未完成时，任务保持 `DOING` 或标为 `BLOCKED` 并写明等待事项，不得标记 `DONE`。
+- 若构建产物需要部署、交接或比较新旧版本，记录产物路径、生成命令和项目选定的指纹（例如 SHA-256）；版本号不能单独证明部署的是本次构建。
+- 标准启动 / 验证入口仍以根目录 `init.sh` 或 `init.ps1` 为准；本表负责说明不同验证层级何时触发。
+
+## 五、依赖纪律

 - 新增第三方依赖前，先说明用途、替代方案和维护成本。
 - 不确定的技术选型先更新本文，再进入代码。
@@ -16,6 +16,7 @@
 - 涉及页面、表单、导航或用户可见状态时，先读取关联的 `07-user-stories.md`、`08-interaction-checklist.md`、`routes.md` 和验收标准。
 - 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
 - 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
+- 复杂任务先把确认后的方案、不可变约束、`write_paths` 和验证层级写入任务文件；不要让关键决策只停留在对话里。
 - 先找现有函数、组件、工具和测试，复用优先。
 - 如果需求含糊，或改动会偏离原则 / 架构，先问。

@@ -50,12 +51,23 @@

 ## 6. 测试与验证

+任务所有者（未委派时即当前 agent）必须亲自完成最终复核：
+
+1. 用 `git status --short` 核对实际修改集合，同时审阅 `git diff` 和 `git diff --cached`，对照任务的 `write_paths`、不可变约束和验收要点，避免漏掉已暂存改动。
+2. 用 `git diff --check` 和仓库既有格式化 / `.gitattributes` 规则检查空白与意外行尾变化；不要把某一种行尾格式硬编码成所有项目的通用要求。
+3. 按 [`03-tech-stack.md`](03-tech-stack.md) 的验证矩阵独立重跑任务相关验证；命中完整门禁触发条件时再跑完整门禁。
+4. 执行者、子 Agent、工具或 CI 的摘要只能作为线索，不能替代任务所有者看到的差异和可复现验证结果。
+5. 必需的人工 / 设备验收尚未完成时，记录等待事项并保持 `DOING` 或 `BLOCKED`，不得标记 `DONE`。
+
 完成前至少检查：

 - [ ] 构建通过。
 - [ ] 相关测试通过。
+- [ ] 已按验证矩阵判断是否需要完整门禁，并完成所有已触发层级。
 - [ ] 对得上需求验收标准。
 - [ ] 没有夹带无关改动。
+- [ ] `git status`、未暂存 / 已暂存 diff 与任务 `write_paths`、不可变约束一致，未出现意外行尾变化。
+- [ ] 必需的人工 / 设备验收已完成；不适用时已在任务文件说明。
 - [ ] 涉及文档事实变化时，文档已同步。
 - [ ] 涉及 UI 时，已验证关联 US / IX 的正常、加载、异常、权限和无障碍要求，或记录明确的不适用理由。
 - [ ] 已在当前任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录` 记录跑过的命令和结果作为证据（约定见 [`tasks/README.md`](tasks/README.md)），不靠"代码已写"判定完成。
@@ -9,10 +9,14 @@
 - [ ] 标准验证 / smoke 仍可运行，结果如实。
 - [ ] 本轮执行记录已写进当前任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录`（含跑过的命令和结果作为证据）。
 - [ ] 任务文件 frontmatter 的 `status` 真实反映 `DONE` 与未验证的边界，没有"假 DONE"。
+- [ ] 必需的人工 / 设备验收已经完成；尚在等待时任务保持 `DOING` 或 `BLOCKED`，没有提前标记 `DONE`。
 - [ ] [`current-state.md`](current-state.md) 的项目级快照与现实一致（启动/验证路径、目录要点、blocker）。
 - [ ] 没有半成品改动处于未记录状态；如有，已写明 `BLOCKED` / `PARTIAL` 和原因。
 - [ ] 代码处于可安全恢复的状态（必要时已提交，提交信息清晰）。
- [ ] 本轮实际修改没有超出任务 `write_paths`，也没有与其他活跃任务发生路径重叠。
+- [ ] 任务所有者已亲自检查 `git status --short`、`git diff` 和 `git diff --cached`；本轮实际修改没有超出任务 `write_paths`，也没有与其他活跃任务发生路径重叠。
+- [ ] 已执行 `git diff --check`，并按格式化工具 / `.gitattributes` 检查没有意外空白或行尾变化。
+- [ ] 已按 `03-tech-stack.md` 的验证矩阵独立重跑任务相关验证和所有已触发门禁，没有仅凭执行者 / 子 Agent / 工具的自我报告判定完成。
+- [ ] 需要部署或交接构建产物时，已记录产物路径、生成命令和项目规定的指纹。
 - [ ] 启用 Gitea 时，Issue 的唯一 `status/*`、claim / 工作分支、PR 和任务状态彼此一致；未完成任务没有误删 claim。
 - [ ] 已运行 `python scripts/validate_harness_governance.py`；启用且可连接 Gitea 时，还运行了只读 `python scripts/audit_gitea_coordination.py --repo 【owner/repo】 --dispatcher 【Gitea登录名】`。

@@ -39,6 +39,7 @@ write_paths:           # 允许修改的仓库相对路径
 ## 问题 / 背景
 ## 关联需求与交互（如适用）
 ## 方案
+## 不可变约束
 ## 验收要点
 ## 边界（不改什么）
 ## 协作约束
@@ -49,7 +50,10 @@ write_paths:           # 允许修改的仓库相对路径

 - 状态：`TODO` · `DOING` · `DONE` · `BLOCKED`。每个 agent 同时最多一个活跃任务；项目可以并行多个写路径互不重叠的任务。
 - 每个 agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。
+- 默认一个任务只有一个责任 Agent 和一个写入者。复杂任务在编码前把确认后的方案写进 `## 方案`；范围明确时直接执行，任务内委派只在项目规则显式允许时启用。
+- `## 不可变约束` 逐项写清不能由执行者自行改变的阈值、判定式、安全边界和既有契约字段；没有时明确写“无”，不要留空让执行者猜测。
 - `write_paths` 必须在动手前写清。两个活跃任务路径相同，或一条是另一条的目录前缀，均视为冲突，不能并行。
+- `## 验收要点` 按 [`../03-tech-stack.md`](../03-tech-stack.md) 区分任务相关验证、命中条件才执行的完整门禁，以及必需的人工 / 设备验收；人工门禁未完成时不得改为 `DONE`。
 - UI 任务在动手前写清关联的 US / IX 编号；无用户界面时，在任务文件中标记交互清单不适用。
 - P0 的 UI 任务动手前确认 `docs/design/` 有对应页面原型，没有就先生成（约定见 [`../design/README.md`](../design/README.md)）；显著改版页面的任务在 `## 方案` 中写明第一步为重新生成原型并更新 IX 草稿。
 - 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
@@ -58,6 +62,15 @@ write_paths:           # 允许修改的仓库相对路径

 未启用 Gitea 时，在独立分支 / worktree 中把任务文件从 `TODO` 改为 `DOING` 即可。启用 Gitea 时，必须先按 [`../gitea-collaboration.md`](../gitea-collaboration.md) 由 dispatcher 串行分配并创建 `claims/T-<编号>` 防御性标记；assignee、标签、读回和普通 create-branch API 都不能单独提供并发互斥。

+## 任务内委派（可选）
+
+任务内委派默认关闭；跨 Agent 并行优先拆成 `write_paths` 互不重叠的不同任务。项目显式允许任务内委派时：
+
+- 只读探索者不得修改或提交仓库；探索结论先由任务所有者核实并写回任务文件。
+- 同一时刻只有一个写入者。任务所有者若把实现交给执行者，自己不与执行者并行修改相同任务路径。
+- 派发内容必须逐项包含任务文件、不可变约束、允许的 `write_paths`、明确不改什么，以及任务相关 / 完整 / 人工三层验证要求；执行者不得自行放宽。
+- 任务所有者保留最终责任，必须独立检查 `git status`、审阅未暂存与已暂存 diff、检查意外行尾变化并重跑已触发的验证；不能仅凭执行者自报把任务标记为 `DONE`。
+
 ## 与 Gitea Issue / PR 的映射（可选）

 - 一个任务文件对应一个主 Issue；Issue 负责实时领取、阻塞和评审状态，任务文件负责版本化规格和长期证据。
@@ -26,11 +26,21 @@ write_paths:

 ## 方案

-（怎么改，落到"改哪个文件、改成什么"）
+（怎么改，落到“改哪个文件、改成什么”。复杂任务把确认后的规划结论写在这里，不只保留在对话中。）
+
+## 不可变约束
+
+- 阈值 / 数值边界：【具体值；无则写“无”】
+- 判定式 / 状态转换：【必须保持的规则；无则写“无”】
+- 安全边界：【不可绕过、不可自动执行的动作；无则写“无”】
+- 既有契约：【字段、接口、兼容性要求；无则写“无”】

 ## 验收要点

-（可验证的完成标准；按「passing 需证据」写清跑哪个验证命令，不写"应该能用"）
+- 任务相关验证：【每次必跑的命令与预期证据】
+- 完整门禁：【触发条件、命令与预期证据；不触发时写明理由】
+- 人工 / 设备验收：【是否必需、执行角色、步骤与证据；不适用时明确写“不适用”】
+- 构建产物：【需要交接 / 部署时填写路径、生成命令和指纹；不适用时明确说明】

 ## 边界（不改什么）

@@ -38,7 +48,12 @@ write_paths:

 ## 协作约束

-（启用 Gitea 时填写对应 Issue、领取时的 `context_ref`、claim / 工作分支；任何新增写路径先检查与其他活跃任务是否重叠。）
+- 责任 Agent：【Agent 标识】
+- 唯一写入者：【默认同责任 Agent；项目显式启用委派时填写执行者】
+- 委派：【默认不启用；启用时写清只读探索者 / 执行者，并声明其继承本任务全部不可变约束、`write_paths` 和验证要求】
+- Gitea：【启用时填写对应 Issue、领取时的 `context_ref`、claim / 工作分支】
+
+任何新增写路径先检查与其他活跃任务是否重叠；同一时刻只有一个 Agent 修改本任务的 `write_paths`。

 ## 执行记录

@@ -82,7 +82,7 @@ Get-ChildItem -Recurse -File
 | H-411 | 返修 H-410：恢复验收契约并重写填写示例 | H-410 | ① 恢复本文件中 H-410 验收要点为落任务时原文（见 ecd75de），状态保持 DONE；「使用规则」新增"验收要点一经领取不得改写，完成时只更新状态并另记证据；确需重新定义任务时先经用户确认"条款；② `docs/07-user-stories.md`、`docs/08-interaction-checklist.md` 的「填写示例」改写为具体但通用的示例（列表检索、删除确认等通用场景，业务对象统一用【条目】占位），每个字段给出真实可读的填法，不再逐字复读模板占位符；③ 08 示例以破坏性 P0 交互演示完整 10 行状态与异常清单和无障碍要求，低风险交互演示"只留总表条目"的用法；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、示例未混入真实业务事实（无具体接口路径 / 真实产品名） | DONE |
 | H-412 | 增加 HTML 原型输入约定 `docs/design/` | H-411 | ① 新增 `docs/design/README.md` 约定文档：原型定位（生成 07 用户故事 / 08 交互清单的一次性输入物，低保真优先）；形态（一页面一个单文件 `.html`，CSS / JS 内联、零构建依赖、双击可开，按路由命名如 `items-list.html`）；假数据要求（页面顶部固定 "PROTOTYPE" 横幅标注仅供枚举交互）；权威性边界（行为权威是 08 清单，原型与清单冲突时以清单+需求为准；禁止把原型代码直接复制进生产实现，实现按 `04-architecture.md` 组件边界重写）；工作流（需求描述 → AI 生成原型 → 人工调整认可 → 据原型产出 IX 总表草稿全标【待确认】→ 人工确认行为决策）；SVG / Excalidraw 作为快速草图的替代形态一并说明（文字须保留为真文本）；② `docs/08-interaction-checklist.md` 交互详情模板与填写示例增加可选字段「关联原型」（无原型时写不适用）；③ 登记导航：`README.md`、`docs/README.md`；`docs/00-ai-start-here.md` 的"做页面 / UI"分支提及原型可作输入；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、约定保持通用占位符不绑业务；不预置示例原型文件，不改 07 / 08 文件名 | DONE |
 | H-413 | 原型生命周期规则：开工门槛 + 触发式重新生成 | H-412 | ① `docs/design/README.md`：「定位与边界」或「维护规则」补三条——P0 的 UI 模块首次实现前应有原型，没有就先生成再拆任务（开工门槛，一次性）；新需求显著改变页面布局或控件集合时，把"重新生成该页原型 → 更新 IX 草稿"作为该任务第一步，判断标准为"agent 是否需要重新看图才能枚举交互"，小改动（文案、加字段）只改 IX 条目不碰原型；页面实现后原型即视为过期，不承担与实现同步的义务，实现后的视觉事实由任务文件执行记录中的真实截图承担；② `docs/tasks/README.md`：UI 任务规则处加一句——P0 UI 任务动手前确认 `docs/design/` 有对应原型，无则先生成；显著改版任务在任务文件方案中写明第一步重新生成原型；③ 不引入"每模块常备原型库"和"变更必同步原型"的义务，措辞明确原型是一次性输入物；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、新旧措辞无冲突（`rg` 检查"持续同步 / 必备"相关表述一致） | DONE |
-| H-414 | 提炼跨 Agent 工作模式、独立复核与验收门禁 | H-409 | ① `docs/00-ai-start-here.md` 增加跨 Claude Code、Codex 及其他 coding agent 通用的工作模式：默认单任务、单责任 Agent、单写入者；复杂任务先规划并把确认后的方案写入当前任务文件；范围明确时直接执行，范围不清或跨目录探索收益明显时才按平台能力做只读探索；任务内委派仅在项目显式启用时使用，不绑定厂商、模型或代理类型；② `docs/tasks/README.md` 与 `_template.md` 要求任务在编码前落盘方案、不可变约束（阈值 / 判定式 / 安全边界 / 既有契约）、`write_paths`、分层验证和必需人工验收，委派执行者继承全部边界且仍保持唯一写入者；③ `docs/05-coding-rules.md` 与 `docs/clean-state-checklist.md` 增加任务所有者独立复核：检查 `git status` / `git diff` 是否越界、按项目规则检查意外行尾变化、独立重跑验证，不以执行者自报判定完成；必需的人工 / 设备验收未完成不得标记 `DONE`；④ `docs/03-tech-stack.md` 增加任务相关验证、完整门禁、人工 / 设备验收三层矩阵及触发条件；构建产物可按项目需要记录 SHA-256 等指纹，不强制所有任务无差别跑全量；⑤ 保持根 `CLAUDE.md` 为薄入口，不新增厂商专属流程、不新增文档；运行上下文校验、单元测试、治理校验、相对链接和 `git diff --check` | TODO |
+| H-414 | 提炼跨 Agent 工作模式、独立复核与验收门禁 | H-409 | ① `docs/00-ai-start-here.md` 增加跨 Claude Code、Codex 及其他 coding agent 通用的工作模式：默认单任务、单责任 Agent、单写入者；复杂任务先规划并把确认后的方案写入当前任务文件；范围明确时直接执行，范围不清或跨目录探索收益明显时才按平台能力做只读探索；任务内委派仅在项目显式启用时使用，不绑定厂商、模型或代理类型；② `docs/tasks/README.md` 与 `_template.md` 要求任务在编码前落盘方案、不可变约束（阈值 / 判定式 / 安全边界 / 既有契约）、`write_paths`、分层验证和必需人工验收，委派执行者继承全部边界且仍保持唯一写入者；③ `docs/05-coding-rules.md` 与 `docs/clean-state-checklist.md` 增加任务所有者独立复核：检查 `git status` / `git diff` 是否越界、按项目规则检查意外行尾变化、独立重跑验证，不以执行者自报判定完成；必需的人工 / 设备验收未完成不得标记 `DONE`；④ `docs/03-tech-stack.md` 增加任务相关验证、完整门禁、人工 / 设备验收三层矩阵及触发条件；构建产物可按项目需要记录 SHA-256 等指纹，不强制所有任务无差别跑全量；⑤ 保持根 `CLAUDE.md` 为薄入口，不新增厂商专属流程、不新增文档；运行上下文校验、单元测试、治理校验、相对链接和 `git diff --check` | DONE |

 ## Phase 5 · Harness 评审与健康度层（Tier 2）