paseo-req-kit 0.0.0-stage → 1.8.0-beta.3

package/engine/prompts/03a-design-proposal.md

@@ -0,0 +1,30 @@
+# 本步骤任务：方案提案（方案设计之前，几个 agent 各自独立提出方案）
+
+## 目标
+
+这一次方案设计分两步：先由几个 agent（通常使用不同的模型）各自独立提出一份方案提案，再由方案设计步骤比较这些提案、做出决定并写出正式的 `design.md`。你负责其中一份提案。你是哪一份、写到哪里，见 `<pipeline-context>` 中"方案提案"和"你的提案文件"两行。
+
+不同的模型容易想到不同的做法，所以请**独立判断**：不要读其他提案（`design-proposals/` 目录下的其他文件），也不要试图和别人保持一致。
+
+## 做法
+
+1. 读 `spec.md`、`alignment.md`、`changes.md`（如有），以及与需求相关的现有代码、测试、配置。
+2. 想清楚你会怎么做，然后写提案。提案是给方案设计步骤做决定用的，重点是**思路和取舍**，不是完整的设计文档。
+3. 只写你自己的提案文件和结果文件：不要修改代码和其他文件，不要提交，不要写 `progress.md`、`decisions.tsv`。这些优先于上文"结束方式"和"记录不显而易见的决定"中的要求。
+
+## 提案文件的内容
+
+1. **思路**：一段话说明整体做法
+2. **改动范围**：要改或新增哪些模块、文件、接口、数据结构，大致规模
+3. **逐条对应**：每个 FR 怎么实现，每条 AC 打算怎么测试
+4. **关键取舍**：你考虑过但没有选的做法，以及理由
+5. **风险**：最可能出问题的地方，和应对方法
+6. **需要需求方决定的问题**（如有）
+
+## 结果文件
+
+```json
+{ "status": "done" }
+```
+
+- `status`：写完了完整的提案为 `"done"`；只完成了一部分为 `"partial"`，并在提案中说明缺了什么。

package/engine/prompts/04-design-review.md

@@ -0,0 +1,73 @@
+# 本步骤任务：方案审核（第 4 步）
+
+## 目标
+
+你是独立的审核者，没有参与方案的编写。请在开始写代码之前找出方案里会导致返工的问题，此时修正的成本最低。你的结论决定流水线是否继续往下走。
+
+本步骤只产出 `design-review.md`。不修改 `design.md`，不修改代码。
+
+## 做法
+
+1. 先读 `spec.md`，形成你自己对"这个需求要什么"的理解，再读 `design.md`。这个顺序可以避免被方案的叙述带着走。
+2. 方案中关于现有代码的说法，去读对应的代码来核实，不要直接采信。
+3. 按下面的方面逐项检查，优先级从高到低：
+   - **需求覆盖**：每条 FR 和 AC 是否都有对应的设计？方案有没有做 spec 没要求的事？
+   - **正确性**：按这个方案做出来，每条 AC 真的能通过吗？异常、边界、权限、并发、已有数据这些情况是否都处理到了？
+   - **与现有系统的契合**：是否符合项目已有的结构和做法？会不会破坏已有功能？
+   - **风险**：数据安全、权限漏洞、不可回退的变更、对外部系统的影响。
+   - **简单性**：有没有更简单的做法能达到同样效果？有没有不必要的抽象或预留？
+   - **可验证性**：测试策略能否真正证明每条 AC？"是否采用测试先行"的判断理由是否成立？端到端验证方式是否可行？
+   - **可执行性**：实施计划的任务是否足够小、顺序是否合理、完成标志是否明确？分了切片的：每一片是否是能单独验证的纵向功能（而不是按技术层横切）、依赖顺序是否成立、片与片的交接是否写清楚、数量是否适中？结果文件中的文件清单（`files`）是否覆盖了实施计划要改的文件？
+   - **假设与阻塞问题**：假设是否合理、是否标明了对使用者可见的影响？有没有被当作"假设"处理、实际上应该由需求方决定的事？
+   - **给需求方的预览**（有 `preview.md` 时）：是否与方案一致；不读代码的人能否据此判断"是不是我要的"；原型是否覆盖了关键状态（正常、出错、空数据）；影响界面、数据、权限的假设是否都列出来了。
+4. 写 `design-review.md`。
+
+## 审核意见的写法
+
+每条意见包含：
+
+- 编号（DR-1、DR-2…）
+- 级别：
+  - **必须修改**：不改会导致做错、做不出来，或带来明显风险
+  - **建议**：改了更好，不改也能交付
+  - **备注**：供参考的信息
+- 位置：`design.md` 的哪一节，或涉及的代码路径
+- 问题是什么，以及依据（引用 spec 编号或代码位置）
+- 为什么重要：不处理会有什么后果
+- 修改方向：指出方向即可，不必替设计者重写
+
+请按实际情况判断。没有发现问题时如实写"未发现需要修改的问题"，这是正常的结果；不要为了显得认真而凑意见，也不要对不影响交付的写法偏好提"必须修改"。不确定的问题标明"待核实"并说明你查了什么。
+
+## `design-review.md` 的结构
+
+1. **结论**：通过 / 需要修改 / 阻塞，以及一句话理由
+2. **需求覆盖核对表**：逐条 AC，方案是否覆盖
+3. **审核意见**：按级别排列
+4. **需要需求方决定的问题**（如有）：围绕需求和行为来问，给出选项和影响，需求方不读代码也能回答
+
+## 第 2 轮及以后
+
+设计者已按上一轮意见修订了 `design.md`，修订记录在它的末尾。这一轮请逐条核对上一轮"必须修改"的意见是否真正解决，并检查修订是否引入了新问题或前后矛盾。已经解决的不要重复提出。结论写在 `design-review.md` 新增的"## 第 N 轮"一节中。
+
+## 结果文件
+
+```json
+{ "verdict": "approved" }
+```
+
+或者，存在必须由需求方决定的问题时：
+
+```json
+{
+  "verdict": "blocked",
+  "questions": ["需求方不读代码也能回答的问题一", "问题二"]
+}
+```
+
+- `verdict`，三选一：
+  - `approved`：没有"必须修改"的意见，可以直接进入实现。
+  - `changes_required`：有"必须修改"的意见，但设计者不需要询问需求方就能改好。之后会执行方案修订，再进行下一轮审核（轮数用完则直接进入实现）。
+  - `blocked`：`spec.md` 或 `design.md` 缺失；或者存在必须由需求方决定的问题，而且在答案出来之前动手实现很可能做出错误的东西。选择它会让流水线暂停，并把 `questions` 中的问题转给需求方。
+- `questions`（字符串数组）：`verdict` 为 `blocked` 时必填。每个问题都要让不懂技术的人能直接回答，必要时在问题里给出选项，例如"历史订单是否也需要显示新的配送状态？可选：A. 只有新订单显示；B. 历史订单也显示（需要补录数据）"。
+
+只在继续实现确实弊大于利时选择 `blocked`。可以靠合理假设推进、并且假设错了也容易调整的问题，记为意见即可。

package/engine/prompts/04b-design-revise.md

@@ -0,0 +1,41 @@
+# 本步骤任务：方案修订（第 4 步的后续，在审核结论为"需要修改"时执行）
+
+## 目标
+
+根据 `design-review.md` 的审核意见修订 `design.md`，让下一步的实现者拿到一份可以直接执行的方案。修订之后可能还有一轮审核，也可能因为轮数用完而直接进入实现；无论哪种情况，审核者和实现者都会对照你的修订记录，所以每条意见是怎么处理的要写清楚。
+
+本步骤不写产品代码，不修改 `design-review.md`。
+
+## 做法
+
+1. 读 `spec.md`、`design.md`、`design-review.md`。
+2. 逐条处理审核意见：
+   - **必须修改**：先去读相关代码或 spec，确认问题成立，然后修改方案。修改时检查受影响的其他章节（需求对照表、实施计划、测试策略）并一并更新，保持方案前后一致。
+   - 如果核实后你认为某条"必须修改"不成立，不要直接忽略。写明你的依据（代码位置或 spec 编号），并在两种做法中选择更稳妥的那一种。
+   - **建议**：采纳成本低且确实更好的就采纳；不采纳的写明原因。
+3. 在 `design.md` 末尾新增"修订记录（第 N 轮）"一节，N 与你处理的那一轮审核一致：
+
+   | 意见编号 | 级别 | 处理结果（已修改 / 部分采纳 / 未采纳） | 说明，以及改动了哪些章节 |
+   | --- | --- | --- | --- |
+
+4. 有 `preview.md` 或 `prototype/` 时，方案改动涉及的部分同步修改，保持与 `design.md` 一致；`ui_change` 的判断变了的，在结果文件中写上新的值。
+5. 审核中提出的"需要需求方决定的问题"，原样保留在方案的"阻塞问题"或"假设"一节中，写明你暂时采用的处理方式。最终报告会把它们交给需求方。
+
+## 完成标准
+
+- 每条"必须修改"和"建议"都出现在修订记录里。
+- 修订后的方案自身没有矛盾，每条 AC 仍然都有着落。
+
+## 结果文件
+
+```json
+{ "status": "done" }
+```
+
+修订改变了实施计划的切片或改动的文件清单时，把新的完整列表写上（写法与方案设计步骤的结果文件相同），流水线以最新的为准；没有变化时省略：
+
+```json
+{ "status": "done", "slices": ["S1 …（AC-1.1）", "S2 …（AC-2.1）"], "files": ["src/auth/", "test/auth/"] }
+```
+
+- `status`：所有"必须修改"的意见都已处理（修改或说明了不采纳的依据）时为 `"done"`；有意见没能处理时为 `"partial"`，并在修订记录中说明。

package/engine/prompts/05-implement.md

@@ -0,0 +1,72 @@
+# 本步骤任务：代码实现（第 5 步）
+
+## 目标
+
+按照 `design.md` 的实施计划完成代码，使 spec 中的每条验收标准都得到实现，并有相应的测试或其他验证方式作为依据。
+
+## 开始前
+
+1. 读 `spec.md`、`design.md`（包括末尾的"修订记录"，如有）和 `design-review.md`。有 `preview.md` 的，需求方已经确认过它和 `prototype/` 中的原型：做出来的界面和行为要与它们一致，不一致的地方写进"与方案的偏离"并说明原因。
+2. 记下基线提交：执行 `git rev-parse HEAD`，把结果写进 `implementation.md` 的第一行。之后的代码评审会从这个提交开始比较，所以要在改动任何代码之前记录。
+3. 运行一次现有测试，确认与 `design.md` 记录的基线一致。不一致时把差异记下来再继续。
+
+## 做法
+
+按实施计划的顺序逐个任务完成。
+
+**方案判断该任务适合测试先行时**，按红、绿、重构的节奏进行：
+1. 先写测试，用它表达对应验收标准所要求的行为，输入和期望值用 AC 中的例子（方案的测试用例清单写明了对应关系）。
+2. 运行测试，确认它失败，而且失败的原因是功能尚未实现，而不是测试本身写错了。
+3. **把这些验收测试单独提交一次**（这时它们是失败的），提交信息注明"验收测试"，并在结果文件中写上 `acceptance_tests`（这些测试文件）和 `acceptance_tests_commit`（这次提交的提交号）。之后不再修改它们的断言：流水线会在代码评审前核对，被改过的要由评审逐个确认有没有依据。确实需要改的（spec 要求的行为变了，或者测试本身写错了），在 `implementation.md` 中写明改了什么、为什么。
+4. 写出能让测试通过的最少代码。
+5. 测试通过后整理代码，保持测试通过。
+
+**方案判断该任务不适合测试先行时**，不要硬套。按方案指定的替代方式验证，并把验证过程记录下来。
+
+实现过程中如果发现方案对测试先行的判断与实际不符（比如实际上很容易测，或者实际上测不了），按实际情况调整，并在"与方案的偏离"里说明。
+
+无论采用哪种方式：
+
+- 方案的任务写了"参照的已有文件"时，照它的结构、命名、错误处理和测试写法来；业务概念用 `GLOSSARY.md` 中的代码名称。
+
+- 测试检查的是对外可见的行为和结果，不是内部实现细节。这样的测试在以后重构时仍然有效。
+- 写出对所有合理输入都正确的通用实现。不要只让测试用例里的那几个值通过。
+- 不要为了通过而删除、跳过或放宽已有测试。如果某个已有测试失败是因为 spec 要求的行为确实变了，更新它，并在 `implementation.md` 里写明改了哪个测试、对应哪条需求。
+- 每完成一个任务，运行相关测试，通过后提交一次。
+- 发现方案有错或行不通时，可以偏离方案，选择仍然满足 spec 的做法，并记录原因。偏离不能改变 spec 要求的行为。
+- 临时文件、调试输出、试验性代码在结束前清理掉。
+
+全部任务完成后，运行完整的测试、代码检查、类型检查和构建（项目有哪些就运行哪些），处理本次改动引入的问题。
+
+**流水线会复查。** 本步骤结束后，流水线会自己运行项目配置的检查（质量门：格式、lint、类型检查、测试、构建，以项目配置为准），只看改动之前通过、现在失败的项。有这样的项，会把输出发回给你修复。所以结束前先自己把这些检查跑一遍；改动之前就失败的检查不算你的问题，但要在产物里如实写明。
+
+**做不下去时**：某个任务经过合理尝试仍然无法完成，停止在那里，如实记录做到了哪一步、卡在哪里、试过什么。保留已经完成并且测试通过的部分。不要用占位实现、写死的返回值或跳过的测试让它看起来已经完成。
+
+## `implementation.md` 的内容
+
+1. **基线提交**：改动前的提交号
+2. **任务完成情况**：
+
+   | 任务 | 状态（完成 / 部分完成 / 未完成） | 对应 AC | 提交号 | 说明 |
+   | --- | --- | --- | --- | --- |
+
+3. **改动清单**：新建和修改的文件，每个一句话说明
+4. **验收标准与测试对照**：每条 AC 由哪个测试或哪种验证方式覆盖
+5. **测试与检查结果**：实际运行的命令和结果摘要（通过和失败的数量，失败项的名称）
+6. **与方案的偏离**：哪里没有按方案做，原因是什么
+7. **未完成事项和已知问题**：没有就写"无"
+
+## 完成标准
+
+- 计划中的任务都已完成，或者未完成的部分已如实记录。
+- 完整测试的结果来自你在最后一次改动之后的实际运行。
+- 工作区里没有遗留本步骤产生的未提交改动。
+
+## 结果文件
+
+```json
+{ "status": "done", "acceptance_tests": ["test/auth/sms-login.test.ts"], "acceptance_tests_commit": "3f9c2ab" }
+```
+
+- `status`：计划中的任务全部完成时为 `"done"`；有任务未完成或部分完成时为 `"partial"`，并在 `implementation.md` 中说明。
+- `acceptance_tests`、`acceptance_tests_commit`（可选）：按上文先单独提交了验收测试时填写；没有测试先行的任务时省略。

package/engine/prompts/06-code-review.md

@@ -0,0 +1,70 @@
+# 本步骤任务：代码评审（第 6 步）
+
+## 目标
+
+你是独立的评审者，没有参与实现。请判断这次改动是否正确、安全地实现了 spec，并指出需要修复的问题。需求方不懂代码，在功能验证之前，你是唯一会逐行阅读这些改动的人。
+
+本步骤只产出 `code-review.md`。不修改产品代码和测试代码，修复由下一步完成。
+
+## 做法
+
+1. 读 `spec.md` 和 `design.md`，明确应该做成什么样。
+2. 从 `implementation.md` 第一节取得基线提交号，查看从它到当前 `HEAD` 的全部改动（`git diff <基线提交>...HEAD`，以及 `git log`）。基线提交号缺失时，用功能分支与其来源分支的分叉点代替，并在评审里注明。
+3. 亲自运行测试、代码检查、类型检查和构建，不要直接采信 `implementation.md` 里的结果。两者不一致时记录下来。`<pipeline-context>` 中有"质量门"几行时，那是流水线自己运行检查的结果：写明"要求修复后仍失败"的检查，按"阻塞"或"重要"提出（除非你核实后确认与本次改动无关，并写明依据）。
+4. 阅读改动本身以及它周围的代码，理解改动在整体中的作用。
+5. 按下面的方面检查，优先级从高到低：
+   - **是否实现了需求**：逐条 AC 核对是否真的实现了、是否有测试覆盖。有没有做 spec 之外的事？
+   - **正确性**：逻辑错误、遗漏的边界情况、出错路径、并发和重复操作、空值和异常输入。
+   - **安全与数据**：权限校验是否完整、输入是否校验、有没有注入风险、有没有泄露敏感信息、数据变更是否安全并且可以回退、有没有把密钥写进代码。
+   - **测试质量**：测试是否真的在检查行为（而不是恒为真的断言，或只是把实现重复了一遍）？测试的期望值是否与 AC 中的例子一致？异常和边界情况有没有测到？有没有被删除、跳过或放宽的已有测试？`<pipeline-context>` 中"验收测试锁定"列出了先提交、后来又被修改的验收测试，逐个看修改有没有依据（spec 要求的行为变了，或测试本身写错并在 `implementation.md` 中说明了）；为了让测试通过而放宽断言的，按"阻塞"提出。
+   - **与方案和项目惯例的一致性**：偏离方案的地方是否合理并且已有记录？命名、结构、错误处理的方式是否跟随项目现状？
+   - **范围与简单性**：有没有无关的改动、遗留的调试代码、不必要的复杂度？`<pipeline-context>` 中的"范围检查"列出了方案文件清单之外被改动的文件，逐个判断：为实现需求所必需的（方案漏列了），记一句理由；与需求无关的，按"重要"提出，要求撤回。
+   - **影响面**：改动的函数、接口、数据结构、配置还被哪些地方使用（用搜索找出调用方，不要凭印象）？这些地方的行为会不会因此改变？关键的调用方要实际运行相关的测试或命令来确认。
+6. 写 `code-review.md`。
+
+## 评审意见的写法
+
+每条意见包含：
+
+- 编号（CR-1、CR-2…）
+- 级别：
+  - **阻塞**：会导致功能错误、数据损坏、安全问题，或某条 AC 没有实现
+  - **重要**：应当在交付前修复的缺陷或明显的质量问题
+  - **建议**：改进项，不修也可以交付
+- 位置：文件路径和行号
+- 问题和依据：具体会在什么情况下出错。最好给出能触发问题的输入或操作步骤。
+- 修复方向
+
+只报告你读过代码并确认的问题。有怀疑但没能确认的，标为"待核实"并说明你查了什么。没有发现问题时如实写明，不需要凑数。
+
+"阻塞"和"重要"只用于会影响正确性、安全、数据或验收结果的问题。写法偏好、不会发生的情况、为假想的将来增加的防御代码或抽象，最多提为"建议"：评审意见会被逐条修复，把它们提成必须修改，只会让代码越改越复杂。
+
+## `code-review.md` 的结构
+
+1. **结论**：通过 / 需要修改，以及一句话理由
+2. **评审范围**：基线提交、当前提交、改动的文件数；范围检查列出的方案外文件逐个给出判断
+3. **影响面**：改动的接口和函数被哪些地方使用、你确认了什么
+4. **你实际运行的检查及结果**（以及流水线质量门的结果，如有）
+5. **验收标准核对表**：逐条 AC，是否实现、是否有测试
+6. **评审意见**：按级别排列
+7. **处理记录**：留空，由下一步填写
+
+## 第 2 轮及以后
+
+上一轮的意见已经由修复步骤处理，处理记录在 `code-review.md` 中。这一轮：
+- 评审范围是上一轮评审之后新增的提交（`git log` 中修复步骤的提交），同时留意修复对周围代码的影响。
+- 逐条核对上一轮"阻塞"和"重要"意见是否真正解决。处理记录里标为"不成立"的，自己重新判断：认可的，确认 `decisions.tsv` 中有对应的一行（没有就补上，`kind` 为 `驳回意见`）；不认可的，重新提出并说明理由。
+- 已经解决的不要重复提出；新发现的问题接着往后编号。
+- 结论写在 `code-review.md` 新增的"## 第 N 轮评审"一节中，并保留一个空的"处理记录"小节供修复步骤填写。
+
+## 结果文件
+
+```json
+{ "verdict": "pass" }
+```
+
+- `verdict`，二选一：
+  - `pass`：没有尚未解决的"阻塞"或"重要"级别意见。
+  - `changes_required`：存在尚未解决的"阻塞"或"重要"级别意见，接下来会执行评审问题修复。
+
+代码改动不存在，或者无法确定评审范围时，选择 `changes_required` 并在结论里说明情况。

package/engine/prompts/07-review-fix.md

@@ -0,0 +1,41 @@
+# 本步骤任务：评审问题修复（第 7 步，在代码评审结论为"需要修改"时执行）
+
+## 目标
+
+处理 `code-review.md` 中的评审意见，让代码达到可以进入功能验证的状态。修复之后通常还有一轮代码评审来核对你的处理；轮数用完时，功能验证会直接在你的修复结果上进行。所以每条意见的处理结果要记录清楚。
+
+## 做法
+
+1. 读 `spec.md`、`design.md`、`implementation.md` 和 `code-review.md`。
+2. 逐条处理"阻塞"和"重要"级别的意见：
+   - 先确认问题成立：读相关代码，能复现的先复现。
+   - 修复产生问题的原因，而不是只让报告的那个现象消失。检查同样的问题是否在别处也存在。
+   - 合适的时候为它补一个测试：修复前会失败，修复后通过。
+   - 核实后如果认为某条意见不成立，不要直接跳过。写明依据（代码位置、spec 编号或实际运行结果）。
+3. "建议"级别的意见：改动小、风险低、确实更好的就处理；其余的记录为不处理并说明原因。
+4. 修复不能改变 spec 要求的行为，也不要借机做评审意见之外的改动。
+5. 全部处理完后，运行完整的测试、代码检查、类型检查和构建，确认没有引入新的失败。流水线随后也会自己运行项目配置的检查，改动之前通过、现在失败的会发回给你修复。
+6. 在 `code-review.md` 中最新一轮评审的"处理记录"小节填写下表。评审者写的内容保持原样，只追加：
+
+   | 意见编号 | 级别 | 处理结果（已修复 / 不成立 / 未处理） | 提交号 | 说明 |
+   | --- | --- | --- | --- | --- |
+
+   并在表后写明修复之后实际运行的检查命令和结果。
+
+判定为"不成立"或决定不处理的意见，同时在 `decisions.tsv` 中追加一行（`kind` 为 `驳回意见` 或 `不修复`）。会影响需求方能看到的结果的，`needs_human` 写 `yes`。
+
+**修不了的情况**：某条"阻塞"或"重要"意见经过合理尝试仍无法修复时，标为"未处理"，写明原因和已经尝试的做法。它会被带进最终报告。不要用绕过检查的方式让它看起来已经解决。
+
+## 完成标准
+
+- 每条评审意见都出现在处理记录里。
+- 完整测试的结果来自你在最后一次改动之后的实际运行。
+- 工作区里没有遗留本步骤产生的未提交改动。
+
+## 结果文件
+
+```json
+{ "status": "done" }
+```
+
+- `status`：所有"阻塞"和"重要"意见都已处理（修复或说明了不成立的依据）时为 `"done"`；有意见未处理时为 `"partial"`。

package/engine/prompts/07b-handoff.md

@@ -0,0 +1,45 @@
+# 本步骤任务：提测说明（研发阶段的最后一步，在代码评审之后执行）
+
+## 目标
+
+写一份提测说明 `handoff.md`，交给接下来做测试验证的人或 agent。读者可能是测试同事，也可能是之后另一个时间、另一个对话里启动的验证 agent，他们都没有看过研发过程。读完这份说明，他们应该知道：这次改了什么、怎么把它跑起来、哪些已经自测过、应该重点测什么、测试前要准备什么。
+
+`<pipeline-context>` 中有"执行方式"一行时，按它理解这份说明的用途：
+
+- **分阶段**：研发阶段到此结束，这份说明就是提测单。流水线会停下来，由人决定什么时候开始测试验证，可能是几个小时甚至几天之后。
+- **只做研发**：流水线不做测试验证，测试由人按这份说明来做。
+- 没有这一行（连续）：功能验证马上开始，这份说明是它的输入。
+
+本步骤只写文档，不修改产品代码和测试代码。
+
+## 做法
+
+1. 读 `spec.md`、`design.md`、`implementation.md`、`code-review.md`（包括处理记录），以及 `decisions.tsv`。
+2. 用 `git log` 和 `git diff` 确认实际的改动范围：工作分支、本需求的第一个提交和最后一个提交。增量继续时（`<pipeline-context>` 中有"增量继续"），写明本次开始时的提交之后的改动，并说明这是第几次提测、修了什么。
+3. 核对"怎么跑起来"中的每一条：依赖安装、数据库迁移、配置项、启动命令。能在本地确认的就实际执行一遍确认命令可用，不能确认的标明"未在本地确认"。项目有 `paseo.json` 的，写出服务对应的脚本名。
+4. 写 `handoff.md`，然后提交（只提交这个文件）。
+
+## `handoff.md` 的结构
+
+1. **这次改了什么**：按 FR 列出，每条一句话，用需求方能懂的话说。附上分支名和提交范围（起止提交）。
+2. **怎么跑起来**：需要安装的依赖、数据库迁移、新增或修改的配置项（写配置名和用途，不写密钥的值）、启动命令或 `paseo.json` 中的脚本名、部署到测试环境时要注意的事项。
+3. **自测结果**：单元测试和其他自动化检查的结果（数量、是否通过）；代码评审的结论和轮数；哪些 AC 已经有自动化测试覆盖（列出 AC 编号和对应的测试）。
+4. **建议重点测试**：风险最高的 AC 及原因；可能受影响的已有功能（回归范围）；容易出问题的边界情况和异常路径。按优先级排序。
+5. **已知问题和未完成项**：代码评审没有处理的意见、实现中没有完成的部分、已知的限制。没有就写"无"。
+6. **测试需要的准备**：测试数据、测试账号、功能开关、外部服务的模拟。**只写在哪里取、怎么准备，不写口令、密钥本身。** 只能用于测试环境，不要写任何生产环境的地址或凭据。
+
+篇幅以测试同事十分钟内能读完为准。档位为"快速"时，每节几句话即可。
+
+## 完成标准
+
+- 六节都在；没有内容的写"无"。
+- 提交范围和自测结果来自你实际运行的命令，不是照抄前面的记录。
+- `handoff.md` 已提交，工作区里没有本步骤产生的未提交改动。
+
+## 结果文件
+
+```json
+{ "status": "done" }
+```
+
+- `status`：六节都写完时为 `"done"`；有无法确认的内容（例如启动命令没能在本地确认）时为 `"partial"`，并在 `handoff.md` 中标明。

package/engine/prompts/08-service-start.md

@@ -0,0 +1,59 @@
+# 本步骤任务：服务启动验证（第 8 步，在项目有常驻服务时执行）
+
+## 目标
+
+确认带着这次改动的服务能够正常启动，并留下一份准确的启动方法，供下一步的功能验证使用。
+
+下一步由另一个 agent 在新的会话中执行，你启动的进程不会保留到那时。所以这一步要交付的是两样东西：**"能否启动"的结论**，和**一份照着做就能启动的方法**。结束前请把你启动的进程关掉。
+
+**服务由 Paseo 管理时**（`<pipeline-context>` 中有"Paseo 管理的服务"）：服务已经由流水线启动，不要自己再启动，也不需要关闭。跳过下面的第 2、3、6 步，从第 4 步（就绪判断）开始检查给出的地址；`service-start.md` 的"启动命令"写 `paseo.json` 中的脚本名和命令，"停止方法"写"由流水线通过 Paseo 管理"。
+
+## 做法
+
+1. 如果后文有"本项目的验证方法"，按其中的启动方式执行。否则读 `design.md` 的"运行方式"一节，以及项目的 `README`、启动脚本和配置样例。
+2. 准备本地运行环境：
+   - 安装项目依赖（只装在项目目录内）。
+   - 用项目提供的样例配置生成本地配置。数据库、缓存等依赖使用本地实例或测试实例。
+   - 这次改动包含数据结构变更时，只在本地或测试数据库上执行。
+3. 在后台启动服务，把输出保存到日志文件。
+4. 等待服务就绪。用明确的信号来判断（健康检查接口返回成功、日志出现启动完成的标志、端口开始监听），并设定超时时间。不要只靠等待固定的秒数。
+5. 启动之后检查：
+   - 启动日志里有没有报错，或者这次改动带来的新警告。
+   - 访问一个最基本的入口（首页、健康检查接口，或一个不依赖本次功能的已有接口），确认服务确实在响应。
+   - 访问一个与本次功能相关的入口，确认它已经加载。这里只确认它存在，功能是否正确留给下一步验证。
+6. 关闭服务，确认进程已经退出、端口已经释放。
+7. 写 `service-start.md`。
+
+## 启动失败时
+
+先看日志找出原因，再决定怎么处理：
+
+- **由这次的代码改动引起**（语法错误、配置项缺失、依赖没有声明、迁移脚本有问题等）：做最小的修复，重新启动验证，提交修复，并把问题和修复方式记录下来。
+- **由环境引起**（缺少某个本地服务、缺少凭据、端口被占用等）：能在仓库范围内安全解决的就解决（例如换一个空闲端口）；解决不了的，准确记录缺什么、在哪一步失败、报错内容是什么。不要为了让服务启动而连接生产环境，或者屏蔽报错。
+- 使用基线提交也同样启动不了，说明问题不是这次改动造成的，把这一点记录清楚。
+
+## `service-start.md` 的内容
+
+1. **结论**：启动成功 / 启动失败 / 无法判断，以及一句话说明
+2. **环境准备**：需要的依赖服务、配置文件、一次性的准备命令
+3. **启动命令**：可以直接复制执行的完整命令，以及执行所在的目录
+4. **就绪判断**：怎么知道服务已经启动好（检查的地址或日志标志，通常需要等多久）
+5. **访问地址**：服务地址和端口，以及与本次功能相关的入口
+6. **停止方法**
+7. **启动日志摘录**：关键的几行，有报错时附上完整的报错
+8. **发现的问题和处理**：没有就写"无"
+9. **建议写入 verify.md 的内容**：项目还没有验证方法说明，或者它与实际情况不符时，把这次摸索出来、实际跑通的准备步骤和启动命令整理在这里，供项目维护者更新 `.requirement-pipeline/verify.md`。已经准确时写"无"
+
+## 完成标准
+
+- 结论来自你的实际启动。
+- 启动命令是你实际执行并且成功的那一条。
+- 你启动的进程都已经关闭。
+
+## 结果文件
+
+```json
+{ "started": true }
+```
+
+- `started`（布尔值）：带着这次改动的服务成功启动并能响应请求时为 `true`，否则为 `false`。为 `false` 时流水线仍会继续，由功能验证决定哪些内容无法验证。

package/engine/prompts/09-verify.md

@@ -0,0 +1,90 @@
+# 本步骤任务：功能验证（第 9 步）
+
+## 目标
+
+你是独立的验证者，没有参与实现。请以证据为依据，逐条判断 spec 的验收标准是否达成。需求方会根据你的结论决定是否验收，他们自己没有能力核对。
+
+本步骤可以新增或修改测试代码，但不修改产品代码。发现缺陷时记录下来，由下一步修复。把"发现问题"和"修复问题"分开，是为了让验证结论不受修复者视角的影响。
+
+## 做法
+
+### 准备
+
+1. 读 `spec.md`。在阅读实现之前，先根据每条 AC 以及 spec 里的业务规则、异常情况，列出你打算验证的场景。像一个不了解内部实现的用户那样去设计场景，这样才能发现实现者没有想到的情况。
+2. 读 `handoff.md`（提测说明）：它写了这次改了什么、怎么跑起来、自测覆盖了哪些 AC、建议重点测试什么。把"建议重点测试"和"已知问题"纳入你的场景，但不要只测它列出的内容，你的场景仍以 spec 为准。没有 `handoff.md` 时（较早开始的需求），跳过这一项。
+3. 如果后文有"本项目的验证方法"，运行测试、启动服务、准备测试数据时按其中的做法执行。再读 `design.md` 的测试策略、`implementation.md`、`code-review.md` 的处理记录，以及 `service-start.md`（如有）。前面步骤记录的"未完成""未处理"事项，要重点验证。
+
+### 第一层：基础检查
+
+运行项目完整的自动化测试、代码检查、类型检查和构建。与 `design.md` 记录的基线比较，区分三种情况：原本就失败的、这次新增并且通过的、这次改动导致失败的。
+
+### 第二层：端到端验证
+
+从用户实际使用的入口，把 spec"主流程"里的关键路径和重要的异常路径完整走一遍。
+
+- 项目有常驻服务：`<pipeline-context>` 中有"Paseo 管理的服务"时，服务已经带着当前代码启动好，直接使用给出的地址。否则按 `service-start.md` 的方法启动。它记录的结论是启动失败时，自己再尝试一次；仍然失败的话，端到端部分记为"无法验证"。
+- 项目已有端到端测试工具：用它为本需求编写端到端测试并运行，测试代码提交到仓库，以后可以重复运行。
+- 项目没有端到端测试工具：直接操作真实入口来验证（调用接口、执行命令、有浏览器自动化工具时操作页面），并记录执行的命令和得到的输出。不要为了这次验证给项目引入新的测试框架。
+- 没有常驻服务的项目（库、脚本、命令行工具）：端到端验证是指像使用者那样，从对外的入口调用并检查结果。
+
+每个场景都要检查用户最终看到的结果，以及应当发生的数据变化确实发生了。功能目录中有 `preview.md`（需求方确认过的"做完后你会看到什么"）和 `prototype/`（界面原型）时，逐项对照：界面与原型不一致、或行为与预览描述不一致的，按缺陷登记；能截图的，把实际界面截图和原型放在一起作为证据。验证过程中产生的测试数据，结束后清理掉。
+
+### 判定
+
+对每条 AC 给出结论：
+
+- **通过**：你实际执行了验证，结果符合 AC 的描述。
+- **不通过**：结果与 AC 不符。登记为缺陷。
+- **无法验证**：因为环境或条件的限制没能验证。写明原因，以及需要什么条件才能验证。
+
+单元测试通过不等于 AC 通过。一条 AC 要有与它的描述对应的验证才能判为通过。
+
+## 缺陷的写法
+
+每个缺陷包含：
+
+- 编号（BUG-1、BUG-2…）
+- 严重程度：
+  - **严重**：主流程走不通、数据出错，或有安全问题
+  - **一般**：某条 AC 没有达成，但不影响主流程
+  - **轻微**：不影响任何 AC 的小问题
+- 关联的 AC
+- 复现步骤：别人照着做就能重现
+- 期望的结果（引用 spec）和实际的结果
+- 证据：命令输出、报错信息、日志片段
+
+登记之前先确认这是产品的问题，而不是测试写错了或环境没有准备好。无法确定时如实说明。
+
+## `verification.md` 的内容
+
+1. **结论**：通过 / 发现缺陷 / 无法验证，以及一句话说明
+2. **验证环境**：提交号、启动方式、使用的数据
+3. **基础检查结果**：运行的命令、通过和失败的数量、与基线的比较
+4. **验收标准逐条结果**：
+
+   | AC | 结论 | 验证方式 | 证据（命令及关键输出、截图或日志路径） |
+   | --- | --- | --- | --- |
+
+5. **端到端场景记录**：每个场景的步骤和结果
+6. **缺陷清单**
+7. **没有验证到的内容和原因**
+8. **建议写入 verify.md 的内容**：项目还没有验证方法说明，或者它与实际情况不符时，把这次实际跑通的测试命令、测试数据准备、端到端验证方式整理在这里，供项目维护者更新 `.requirement-pipeline/verify.md`。已经准确时写"无"
+
+之后的缺陷修复和复验会在文件末尾按轮次追加自己的小节。
+
+## 结束前
+
+关闭你启动的所有进程，清理测试数据，提交新增的测试代码和 `verification.md`。
+
+## 结果文件
+
+```json
+{ "result": "pass" }
+```
+
+- `result`，三选一：
+  - `pass`：所有 AC 都判为通过，并且没有"严重"或"一般"级别的缺陷。
+  - `defects_found`：存在"严重"或"一般"级别的缺陷。接下来会执行缺陷修复和复验。
+  - `blocked`：由于环境原因，关键的 AC 无法验证，也没有发现可以修复的缺陷。流水线会直接进入报告，由报告向需求方说明哪些内容没有得到验证。
+
+同时存在缺陷和无法验证的项时，选择 `defects_found`。

package/engine/prompts/10-defect-fix.md

@@ -0,0 +1,41 @@
+# 本步骤任务：测试缺陷修复（第 10 步，在功能验证或复验发现缺陷时执行）
+
+## 目标
+
+修复 `verification.md` 中登记的、尚未解决的缺陷，使对应的验收标准能够达成。修复完成后，会有另一个 agent 独立复验你的结果。
+
+第 2 轮及以后，要处理的是上一轮复验后仍未解决的缺陷，以及复验中新发现的问题，见 `verification.md` 最新一轮"复验结果"中的"遗留问题汇总"。
+
+## 做法
+
+1. 读 `spec.md`、`design.md`、`implementation.md` 和 `verification.md`。
+2. 按严重程度从高到低处理"严重"和"一般"级别的缺陷。对每一个缺陷：
+   - **先复现。** 按复现步骤操作，亲眼看到问题。复现不了时，不要凭猜测修改代码，记录你的操作和看到的结果。
+   - **找到原因。** 弄清楚为什么会这样，而不是只让报告的那个现象消失。检查同样的原因是否还会在别处造成问题。
+   - **先补测试，再修复。** 条件允许时，先写一个能重现这个缺陷的测试，看到它失败，再去修复，直到它通过。
+   - **修复要通用。** 不要针对验证用的特定输入做特殊处理，也不要通过修改或删除验证者的测试来让它通过。
+   - **核对 spec。** 修复之后的行为必须与 spec 一致。如果发现这个"缺陷"其实是测试写错了，或者 spec 本身有两种合理的理解，不要改动产品行为去迁就测试。记录你的依据，交给复验和报告处理。
+3. "轻微"级别的缺陷：改动小、风险低的就一并修复；其余的记录为未处理。
+4. 全部处理完后，运行完整的测试、代码检查、类型检查和构建，确认修复没有破坏其他功能。流水线随后也会自己运行项目配置的检查，改动之前通过、现在失败的会发回给你修复。
+5. 在 `verification.md` 末尾追加"## 缺陷处理记录（第 N 轮）"一节，填写下表。验证者写的内容保持原样，只追加：
+
+   | 缺陷编号 | 严重程度 | 处理结果（已修复 / 不是缺陷 / 无法复现 / 未修复） | 原因 | 修复方式 | 提交号 |
+   | --- | --- | --- | --- | --- | --- |
+
+   并在表后写明修复之后实际运行的检查命令和结果。
+
+**修不了的情况**：经过合理尝试仍无法修复的缺陷，标为"未修复"，写明已经查明的原因和尝试过的做法。它会被带进最终报告，由人来决定下一步。这比一个看起来通过、实际没有解决的修复要好。
+
+## 完成标准
+
+- 每个缺陷都出现在处理记录里。
+- 完整测试的结果来自你在最后一次改动之后的实际运行。
+- 你启动的进程都已经关闭，工作区里没有遗留本步骤产生的未提交改动。
+
+## 结果文件
+
+```json
+{ "status": "done" }
+```
+
+- `status`：本轮要处理的"严重"和"一般"缺陷都已处理（修复，或说明了不是缺陷 / 无法复现的依据）时为 `"done"`；有缺陷未修复时为 `"partial"`。

package/engine/prompts/10b-reverify.md

@@ -0,0 +1,43 @@
+# 本步骤任务：复验（第 10 步的后续，每轮缺陷修复之后执行）
+
+## 目标
+
+你是独立的验证者，没有参与缺陷修复。请确认缺陷是否真的已经解决，以及修复有没有破坏其他功能，然后给出每条验收标准的最终结论。
+
+如果你判定仍有问题，并且修复轮数还没用完，流水线会再安排一轮修复和复验；轮数用完后，仍然存在的问题会由报告如实告知需求方。无论哪种情况，你的任务都是准确地记录现状，而不是让结果看起来通过。
+
+本步骤可以新增或修改测试代码，不修改产品代码。
+
+## 做法
+
+1. 读 `spec.md` 和 `verification.md`，包括其中的缺陷清单和缺陷处理记录。
+2. 重新运行完整的基础检查：自动化测试、代码检查、类型检查、构建。
+3. 逐个复验缺陷：
+   - 严格按照原来的复现步骤操作，确认原来的问题不再出现，并且现在的结果符合 spec。
+   - 检查修复者有没有修改或删除原来用于验证的测试。测试被改动的，判断改动是否合理。
+   - 处理记录里标为"不是缺陷"或"无法复现"的，自己重新判断一次，不要直接采信。
+4. 回归检查：把上一轮已经通过的关键端到端场景重新执行一遍。修复一个问题时碰坏另一个功能是常见的情况。
+5. 有常驻服务的项目，按 `service-start.md` 的方法启动；结束前关闭服务并清理测试数据。
+6. 在 `verification.md` 末尾追加"## 复验结果（第 N 轮）"一节，写入：
+   - **复验结论**：全部通过 / 仍有问题
+   - **缺陷复验表**：
+
+     | 缺陷编号 | 复验结论（已解决 / 未解决 / 部分解决） | 证据 |
+     | --- | --- | --- |
+
+   - **验收标准最终结果表**：逐条 AC 到这一轮为止的结论（通过 / 不通过 / 无法验证）和证据。最后一轮的这张表会被报告直接引用。
+   - **回归检查结果**
+   - **本轮新发现的问题**（如有，按缺陷的格式登记，编号接着上一轮往后排）
+   - **遗留问题汇总**：到此为止仍未解决的全部问题
+
+   上一轮验证者和修复者写的内容保持原样，只追加。
+
+## 结果文件
+
+```json
+{ "result": "pass" }
+```
+
+- `result`，二选一：
+  - `pass`：所有 AC 的结论都是通过，没有遗留的"严重"或"一般"级别缺陷。
+  - `defects_remaining`：仍有 AC 不通过或无法验证，或仍有遗留的"严重"或"一般"级别缺陷。