diff --git a/docs/prd/008_hr1_mandatory_gate_enforcement_2026-04-21.md b/docs/prd/008_hr1_mandatory_gate_enforcement_2026-04-21.md new file mode 100644 index 0000000..e92db5c --- /dev/null +++ b/docs/prd/008_hr1_mandatory_gate_enforcement_2026-04-21.md @@ -0,0 +1,96 @@ +--- +name: Human Review #1 强制执行与 Gate 顺序固化 +description: 将 HR#1 不可跳过及 Gate 2 到后续阶段的顺序约束重新固化为当前有效研发交付需求,作为 Issue #8 的 Gate 1 输入 +status: Draft +owner: Product Manager +date: 2026-04-21 +update_date: 2026-04-21 +issue: "#8" +--- + +# PRD #008 — Human Review #1 强制执行与 Gate 顺序固化 + +## 1. 背景 + +Issue #8 指向的核心问题是:项目曾出现 Gate 2 通过后直接越过 Human Review #1 的违规推进,错误地把“纯文档交付”理解为可跳过 HR#1 的理由,导致正式研发交付流程断裂。 + +当前需要将该约束重新固化为当前有效产品输入,确保后续所有 issue 都按统一口径执行。 + +## 2. 问题 + +当前 AgentDevFlow 在流程认知与工作流文档上仍存在以下风险: + +- **HR#1 强制性表达不足**:部分场景中仍可能被误读为可选环节 +- **Gate 顺序约束不够统一**:Gate 2 后进入 HR#1,再进入下游阶段的顺序需要以当前有效输入重新确认 +- **历史结论复用风险**:不能仅依赖历史治理结论,必须重新走严格研发交付流程形成当前有效产物 + +## 3. 目标 + +形成当前有效的 HR#1 强制执行需求定义,明确: + +1. Human Review #1 是 Gate 2 后的强制环节 +2. 不区分纯文档交付 / 纯代码交付 / 混合交付 +3. Gate 顺序必须满足 Gate 2 → HR#1 → 下游阶段 +4. 相关 prompts / workflow 文档需要按统一口径更新 + +## 4. 范围 + +### 4.1 HR#1 强制性口径 + +- 明确 HR#1 不可跳过 +- 明确不存在因交付类型不同而跳过 HR#1 的分支 +- 明确 HR#1 评审对象为文档阶段正式交付物 + +### 4.2 Gate 顺序固化 + +- 明确 Gate 2 完成后必须先进入 HR#1 +- 明确未完成 HR#1 前不得推进到后续实现 / 验证 / 发布阶段 +- 明确相关状态推进语义不能绕过 HR#1 + +### 4.3 文档与工作流更新范围 + +- `prompts/017_human_review_and_signoff.md` +- `prompts/004_delivery_gates.md` +- `skills/shared/workflows/human-review.md` 或其当前有效对应源文件 + +## 5. 非目标 + +- 不在本 PRD 中直接展开具体代码实现细节 +- 不改造与 HR#1 无关的其他 Gate 机制 +- 不把历史 GOV-004 留档直接视为本轮当前有效交付物 + +## 6. 用户故事 + +### US-1:流程执行者 +> 作为 AgentDevFlow 使用者,我希望明确知道 HR#1 是 Gate 2 后的强制环节,这样就不会因为交付类型判断错误而跳过正式评审。 + +### US-2:Team Lead / 审核者 +> 作为流程审核者,我希望状态推进规则明确,避免 Gate 状态被错误推进到下游阶段。 + +## 7. 验收标准 + +- [ ] 文档明确声明 HR#1 不可跳过 +- [ ] 文档明确声明 HR#1 与交付类型无关 +- [ ] 文档明确声明 Gate 2 → HR#1 → 下游阶段的强制顺序 +- [ ] 相关 prompts / workflow 更新范围已被识别并可追溯 +- [ ] 当前 issue 按严格研发交付流程重新进入 Gate 1,而非直接复用历史结论 + +## 8. 风险 + +| 风险 | 影响 | 缓解 | +|------|------|------| +| 团队继续引用历史治理结论替代当前交付 | 高 | 明确本 issue 必须重新走 PRD / Tech / QA / HR#1 链路 | +| HR#1 规则只在单一文档中更新 | 中 | 在 prompts 与 workflow 双侧同步固化 | +| 状态机仍可能被误推进 | 高 | 在 Gate 顺序文档中显式写入禁止绕过约束 | + +## 9. 依赖 + +- `docs/pmo/issues/008_2026-04-16_governance_issue3_hr1_skipped.md` +- `docs/pmo/resolutions/GOV-004_2026-04-16_issue3_hr1_skipped_resolution.md` +- 当前有效流程文档与 human-review 工作流文档 + +## 10. 评审记录 + +| 日期 | 评审人 | 备注 | 决策 | +|---|---|---|---| +| 2026-04-21 | PM | 按 Team Lead 指令重新启动严格研发交付流程,起草当前有效 PRD | Draft | diff --git a/docs/qa/008_hr1_mandatory_gate_enforcement_qa_2026-04-21.md b/docs/qa/008_hr1_mandatory_gate_enforcement_qa_2026-04-21.md new file mode 100644 index 0000000..8278fdf --- /dev/null +++ b/docs/qa/008_hr1_mandatory_gate_enforcement_qa_2026-04-21.md @@ -0,0 +1,212 @@ +--- +name: Human Review #1 强制执行与 Gate 顺序固化 — QA Case Design v1 +description: 基于 PRD #008 与 Tech-8_v1 的当前有效 QA Case Draft,定义 HR#1 不可跳过与 Gate 顺序固化在 prompts/workflow 中的验证用例 +status: Draft +owner: QA Engineer +date: 2026-04-22 +update_date: 2026-04-22 +issue: "#8" +prd: docs/prd/008_hr1_mandatory_gate_enforcement_2026-04-21.md +tech: docs/tech/008_hr1_mandatory_gate_enforcement_tech_2026-04-21.md +--- + +# QA Case Design #008 — Human Review #1 强制执行与 Gate 顺序固化 + +--- + +## 当前有效状态 + +- **当前有效版本**:v1 Draft +- **当前有效输入**:PRD #008 + Tech Spec #008 v1 +- **当前阶段**:QA Case Design(待 PM + Architect + Engineer 三方评审) +- **规则说明**:本文件为 Issue #8 的当前有效 QA Case Draft,仅绑定当前仓库内已落地的 PRD 与 Tech 输入 + +## 追溯关系 + +- **PRD**: `docs/prd/008_hr1_mandatory_gate_enforcement_2026-04-21.md` +- **Tech Spec**: `docs/tech/008_hr1_mandatory_gate_enforcement_tech_2026-04-21.md` + +### PRD #008 → QA Case 追溯矩阵 + +| PRD Section | 对应 TC | 覆盖状态 | +|-------------|---------|---------| +| 7.1 HR#1 不可跳过 | TC-8-01, TC-8-02, TC-8-03 | ✅ | +| 7.2 HR#1 与交付类型无关 | TC-8-02, TC-8-04 | ✅ | +| 7.3 Gate 2 → HR#1 → 下游阶段 | TC-8-03, TC-8-05 | ✅ | +| 7.4 文档与工作流更新范围 | TC-8-06, TC-8-07, TC-8-08 | ✅ | +| 7.5 历史治理结论隔离 | TC-8-09 | ✅ | + +### Tech Spec #008 → QA Case 追溯矩阵 + +| Tech Spec Section | 对应 TC | 覆盖状态 | +|-------------------|---------|---------| +| 规则固化范围 | TC-8-06, TC-8-07, TC-8-08 | ✅ | +| 统一技术语义 | TC-8-01, TC-8-02, TC-8-03, TC-8-04, TC-8-05 | ✅ | +| 文件级技术责任 | TC-8-06, TC-8-07, TC-8-08 | ✅ | +| 最小修改原则 | TC-8-10 | ✅ | + +--- + +## TC-8-01:HR#1 不可跳过 — 主规则验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-01 | +| 标题 | HR#1 不可跳过主规则验证 | +| 追溯 | PRD 7.1 HR#1 强制性;Tech Spec 统一技术语义 | +| 前置条件 | `prompts/017_human_review_and_signoff.md`、`skills/workflows/human-review.md` 已更新 | +| 测试步骤 | 在上述两份文件中搜索“不可跳过”“强制”“不得跳过”“不存在跳过”等关键词 | +| 预期结果 | 文件明确写出 Human Review #1 不可跳过的强制规则 | +| 验证方法 | 文档搜索 | +| 优先级 | P1 | + +--- + +## TC-8-02:HR#1 与交付类型无关 — 纯文档交付分支验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-02 | +| 标题 | HR#1 与交付类型无关验证 | +| 追溯 | PRD 7.2 / 不区分交付类型;Tech Spec 统一语义 | +| 前置条件 | `prompts/017_human_review_and_signoff.md`、`skills/workflows/human-review.md` 已更新 | +| 测试步骤 | 1. 搜索“纯文档交付”“与交付方式无关”“*md 文档是实现层”“不是跳过理由”等关键词
2. 检查是否存在按交付类型决定是否跳过 HR#1 的分支描述 | +| 预期结果 | 文档明确说明 HR#1 评审对象与交付方式无关,纯文档交付也必须经过 HR#1;不存在“纯文档可跳过”的分支 | +| 验证方法 | 文档搜索 + 反例排除 | +| 优先级 | P1 | + +--- + +## TC-8-03:开发交付路径顺序验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-03 | +| 标题 | 开发交付路径 Gate 2 → HR#1 → 下游阶段顺序验证 | +| 追溯 | PRD 7.3 Gate 顺序固化;Tech Spec 统一技术语义 | +| 前置条件 | 目标文档已更新 | +| 测试步骤 | 在三份目标文档中搜索 Gate 顺序描述:检查是否包含 Gate 2 → Human Review #1 → Gate 3 的链式推进描述 | +| 预期结果 | 开发交付路径明确为 Gate 2 → HR#1 → Gate 3 → Gate 4 → HR#2 → Gate 5,无跳过或颠倒顺序的描述 | +| 验证方法 | 文档搜索 | +| 优先级 | P1 | + +--- + +## TC-8-04:纯文档交付路径顺序验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-04 | +| 标题 | 纯文档交付路径 Gate 2 → HR#1 → Release 验证 | +| 追溯 | PRD 7.3 纯文档交付路径;Tech Spec 统一技术语义 | +| 前置条件 | 目标文档已更新 | +| 测试步骤 | 在三份目标文档中搜索纯文档交付路径:检查 Gate 2 → HR#1 → Release / Issue Close 的链式描述 | +| 预期结果 | 纯文档交付路径明确为 Gate 2 → HR#1 → Release / Issue Close,不走 Gate 3/Gate 4/HR#2,但 HR#1 环节不可省略 | +| 验证方法 | 文档搜索 | +| 优先级 | P1 | + +--- + +## TC-8-05:HR#1 后推进路径完整性验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-05 | +| 标题 | HR#1 后推进路径完整性验证 | +| 追溯 | PRD 7.3 Gate 顺序;Tech Spec 规则固化范围 | +| 前置条件 | `prompts/017_human_review_and_signoff.md` 已更新 | +| 测试步骤 | 检查 HR#1 通过后下游推进路径的描述是否完整,是否存在“HR#1 未完成即进入实现阶段”的遗漏 | +| 预期结果 | 文档明确说明:HR#1 未完成前不得推进到下游阶段,并给出 Human 合并文档 PR 后 Engineer 可进入 Implementation 的清晰路径 | +| 验证方法 | 文档内容验证 | +| 优先级 | P1 | + +--- + +## TC-8-06:`prompts/017_human_review_and_signoff.md` 更新验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-06 | +| 标题 | Human Review 与签字机制文档更新验证 | +| 追溯 | PRD 4.3 文档更新范围;Tech Spec 文件级技术责任 | +| 前置条件 | `prompts/017_human_review_and_signoff.md` 已更新 | +| 测试步骤 | 1. 检查文档是否明确 HR#1 不可跳过
2. 检查文档是否明确纯文档交付不能跳过 HR#1
3. 检查文档是否定义 Gate 2 → HR#1 → 下游阶段的顺序 | +| 预期结果 | 上述三条语义均已写入且表述一致 | +| 验证方法 | 文档内容验证 | +| 优先级 | P1 | + +--- + +## TC-8-07:`skills/workflows/human-review.md` 更新验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-07 | +| 标题 | 人工评审工作流文档更新验证 | +| 追溯 | PRD 4.3 文档更新范围;Tech Spec 文件级技术责任 | +| 前置条件 | `skills/workflows/human-review.md` 已更新 | +| 测试步骤 | 1. 检查文档是否明确 HR#1 不可跳过
2. 检查文档是否列出开发交付路径和纯文档交付路径
3. 检查文档是否将“HR#1 未完成却继续推进下游阶段”列为失败信号 | +| 预期结果 | 上述三条语义均已写入且表述一致 | +| 验证方法 | 文档内容验证 | +| 优先级 | P1 | + +--- + +## TC-8-08:`prompts/004_delivery_gates.md` 更新验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-08 | +| 标题 | 交付 Gate CI 参考文档更新验证 | +| 追溯 | PRD 4.3 文档更新范围;Tech Spec 文件级技术责任 | +| 前置条件 | `prompts/004_delivery_gates.md` 已更新 | +| 测试步骤 | 1. 检查 Gate 2 → HR#1 → Gate 3 的映射是否清晰
2. 检查 HR#1 是否被明确定义为 Gate 2 后的强制环节
3. 检查文档是否未将 GOV-004 结论写成当前自动前提 | +| 预期结果 | Gate 顺序映射清晰,HR#1 为强制环节,历史结论仅追溯 | +| 验证方法 | 文档内容验证 | +| 优先级 | P1 | + +--- + +## TC-8-09:历史治理结论隔离验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-09 | +| 标题 | 历史治理结论仅留档、不替代当前交付验证 | +| 追溯 | PRD 5.3 非目标 / 历史治理结论隔离;Tech Spec 风险 | +| 前置条件 | 全部目标文档已更新 | +| 测试步骤 | 1. 检查文档是否将 GOV-004 结论自动视为当前已通过
2. 检查 #8 的 QA Case / Tech / PRD 是否独立起草,而非直接引用历史结论 | +| 预期结果 | GOV-004 仅作为背景追溯,Issue #8 仍需按 PRD / Tech / QA / HR#1 链路完成交付;文档文本中不得出现“因 GOV-004 已通过”或类似表述 | +| 验证方法 | 文档内容验证 + 追溯矩阵检查 | +| 优先级 | P1 | + +--- + +## TC-8-10:最小修改原则验证 + +| 字段 | 内容 | +|------|------| +| 用例 ID | TC-8-10 | +| 标题 | 最小修改原则验证 | +| 追溯 | Tech Spec 最小修改原则 | +| 前置条件 | 文档与 workflow 修改已完成 | +| 测试步骤 | 1. 检查本次修改是否只涉及 HR#1 强制性与 Gate 顺序相关的文本
2. 检查是否未引入与 #8 无关的新 workflow 新脚本新机制 | +| 预期结果 | 改动面严格限定在三份目标文件,未扩散到 bootstrap-sync、CI 核心逻辑等无关领域 | +| 验证方法 | 文档范围验证 / diff 检查 | +| 优先级 | P2 | + +--- + +## 当前评审状态 + +- **当前状态**:Draft +- **下一动作**:发起 QA Case Design 三方评审(PM + Architect + Engineer) +- **评审前提**:以本文件当前 Draft 为准,后续实现与文档修改不得绕过 QA Case 评审 + +## v1 Draft 变更说明(2026-04-22) + +| 变更项 | 说明 | +|--------|------| +| 首次建立 QA Case | 基于 PRD #008 + Tech Spec #008 v1 建立当前有效 QA Case Draft | +| 覆盖范围建立 | 对 HR#1 强制性、交付类型无关性、Gate 顺序固化、三文件一致性建立追溯矩阵与测试用例 | +| 历史结论隔离 | 将 GOV-004 仅留档、不替代当前交付纳入验证范围 | diff --git a/docs/tech/008_hr1_mandatory_gate_enforcement_tech_2026-04-21.md b/docs/tech/008_hr1_mandatory_gate_enforcement_tech_2026-04-21.md new file mode 100644 index 0000000..064c64c --- /dev/null +++ b/docs/tech/008_hr1_mandatory_gate_enforcement_tech_2026-04-21.md @@ -0,0 +1,167 @@ +--- +name: Human Review #1 强制执行与 Gate 顺序固化 — Tech Spec v1 +description: 基于 PRD #008 的当前有效 Tech Spec,定义 HR#1 不可跳过与 Gate 2 后顺序固化在 prompts / workflow / CI 参考文档中的技术落点与验证路径 +status: Draft +owner: Architect +date: 2026-04-21 +update_date: 2026-04-21 +issue: "#8" +prd: docs/prd/008_hr1_mandatory_gate_enforcement_2026-04-21.md +--- + +# Tech Spec #008 — Human Review #1 强制执行与 Gate 顺序固化(v1) + +--- + +**ID**: Tech-8_v1 +**状态**: Draft +**负责人**: Architect +**日期**: 2026-04-21 +**更新日期**: 2026-04-21 +**基于**: PRD #008(Draft 已经通过 Gate 1,2026-04-21) +**当前评审状态**: 待发起 Gate 2 Tech Review(PM + QA + Engineer) + +--- + +## 上下文 + +Issue #8 的目标不是新增流程能力,而是把已经被证明不可缺失的 HR#1 约束重新固化为当前有效研发交付输入,防止以下错误再次发生: + +1. 把“纯文档交付”误解为可以跳过 Human Review #1 +2. 在 Gate 2 后直接推进到下游实现 / 验证 / 发布阶段 +3. 只引用历史治理结论,而不形成当前有效交付物 + +本 Tech Spec 将 PRD #008 的产品层需求落到当前仓库的规则文件、工作流文件和 CI 参考文档更新面。 + +## 架构 + +### 1. 规则固化范围 + +本次技术落点限定在以下当前有效源文件: + +- `prompts/017_human_review_and_signoff.md` +- `prompts/004_delivery_gates.md` +- `skills/workflows/human-review.md` + +如发现 bootstrap 产物存在对应镜像文件,仅通过源文件更新,不直接修改产物文件。 + +### 2. 需要固化的统一技术语义 + +所有目标文件必须统一承接以下语义: + +- **HR#1 不可跳过** +- **HR#1 与交付类型无关**;纯文档交付不是跳过 HR#1 的理由 +- **开发交付强制顺序**:Gate 2 → Human Review #1 → Gate 3 / Gate 4 / HR#2 / Gate 5 +- **纯文档交付强制顺序**:Gate 2 → Human Review #1 → Release / Issue Close +- **历史治理结论仅能作为背景,不得替代当前 Issue 的正式交付物** + +### 3. 文件级技术责任 + +| 文件 | 技术责任 | +|---|---| +| `prompts/017_human_review_and_signoff.md` | 定义 HR#1 的对象、强制性、禁止绕过规则、HR#1 后的正式推进路径 | +| `skills/workflows/human-review.md` | 固化工作流步骤、失败信号、开发交付路径与纯文档交付路径 | +| `prompts/004_delivery_gates.md` | 作为 CI 参考附录,明确 Gate 2、HR#1、下游阶段的映射和检查口径 | + +### 4. 最小修改原则 + +本次只做 #8 所需的最小收口,不扩展到: + +- 其他与 HR#1 无关的 Gate 机制 +- 新 workflow 新脚本 +- 额外 CI 自动化能力 + +## 接口 + +### 输入 + +- PRD #008:`docs/prd/008_hr1_mandatory_gate_enforcement_2026-04-21.md` +- 当前 human-review 相关 prompts / workflow 文本 +- GOV-004 背景留档(仅作追溯,不作当前结论替代) + +### 输出 + +- 当前有效 Tech Spec #008 +- 后续 QA Case Design #008 +- 三个目标文件中的统一规则修订 + +## 数据流 + +```text +PRD #008 Gate 1 Approved + ↓ +Tech Spec #008 Draft / Gate 2 Review + ↓ +QA Case Design #008 + ↓ +更新 prompts/017 + prompts/004 + skills/workflows/human-review + ↓ +文档 PR(HR#1) +``` + +## 可测试性 + +QA 可基于本 Tech Spec 直接派生以下验证面: + +1. **强制性验证** + - 文档明确写出 HR#1 不可跳过 + - 不存在按交付类型跳过 HR#1 的分支描述 + +2. **顺序验证** + - 开发交付路径明确为 Gate 2 → HR#1 → 下游阶段 + - 纯文档交付路径明确为 Gate 2 → HR#1 → Release / Issue Close + +3. **一致性验证** + - `prompts/017_human_review_and_signoff.md` + - `skills/workflows/human-review.md` + - `prompts/004_delivery_gates.md` + 三处口径一致,无互相冲突 + +4. **历史结论隔离验证** + - 文本中未将 GOV-004 历史结论写成当前自动通过前提 + - 当前 Issue 仍需走完整 PRD / Tech / QA / HR#1 链路 + +## 风险 + +| 风险 | 级别 | 缓解 | +|---|---|---| +| 规则只在单一文件更新,其他文件继续漂移 | 高 | 将 3 个目标文件纳入同一交付范围 | +| “纯文档交付”语义再次被误读 | 高 | 在 prompts 与 workflow 中同时写明“纯文档交付也必须经过 HR#1” | +| CI 参考附录与主规则口径不一致 | 中 | `prompts/004_delivery_gates.md` 仅保留与唯一源一致的参考描述 | +| 历史治理结论再次被误当作当前有效输入 | 中 | 在 QA Case 与后续评审中单独验证“历史仅留档” | + +## 发布推进 + +1. Gate 2 通过后,QA 起草 #8 QA Case Design +2. QA Case 通过后,修改目标 prompts / workflow 源文件 +3. 形成文档 PR,进入 Human Review #1 +4. HR#1 通过并合并后,按交付类型进入下游 Release 或后续阶段 + +## 回滚 + +- 若发现三文件口径不一致,回退到文档修订阶段重新统一 +- 若某条规则会影响其他现行主线,以 `prompts/002_develop_pipeline.md` 的唯一源定义为裁决基准 +- 若 CI 参考附录表述超出主规则定义,删除扩展表达,仅保留引用性说明 + +## 评审记录 + +| 日期 | 评审人 | 备注 | 决策 | +|---|---|---|---| +| 2026-04-21 | Architect | 基于已通过 Gate 1 的 PRD #008 起草当前有效 Tech Draft | Draft | + +## 版本历史 + +| 版本 | 日期 | 变更说明 | 变更人 | +|------|------|---------|-------| +| v1 | 2026-04-21 | 首次起草 #8 当前有效 Tech Spec Draft | Architect | + +## 前序文档追溯链 + +基于:`docs/prd/008_hr1_mandatory_gate_enforcement_2026-04-21.md` +Tech Spec 依赖:PRD #008 Gate 1 Approved + +## 评审记录表 + +| 评审日期 | 评审节点 | 评审结果 | 评审人 | 意见/打回原因 | 修改后版本 | +|----------|---------|---------|-------|-------------|-----------| +| 2026-04-21 | Gate 2 | 待评审 | PM + QA + Engineer | — | v1 |