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

package/engine/prompts/05-implement.md

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

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

@@ -0,0 +1,66 @@
+# 本步骤任务：代码评审（第 6 步）
+
+## 目标
+
+你是独立的评审者，没有参与实现。请判断这次改动是否正确、安全地实现了 spec，并指出需要修复的问题。需求方不懂代码，在功能验证之前，你是唯一会逐行阅读这些改动的人。
+
+本步骤只产出 `code-review.md`。不修改产品代码和测试代码，修复由下一步完成。
+
+## 做法
+
+1. 读 `spec.md` 和 `design.md`，明确应该做成什么样。
+2. 从 `implementation.md` 第一节取得基线提交号，查看从它到当前 `HEAD` 的全部改动（`git diff <基线提交>...HEAD`，以及 `git log`）。基线提交号缺失时，用功能分支与其来源分支的分叉点代替，并在评审里注明。
+3. 亲自运行测试、代码检查、类型检查和构建，不要直接采信 `implementation.md` 里的结果。两者不一致时记录下来。
+4. 阅读改动本身以及它周围的代码，理解改动在整体中的作用。
+5. 按下面的方面检查，优先级从高到低：
+   - **是否实现了需求**：逐条 AC 核对是否真的实现了、是否有测试覆盖。有没有做 spec 之外的事？
+   - **正确性**：逻辑错误、遗漏的边界情况、出错路径、并发和重复操作、空值和异常输入。
+   - **安全与数据**：权限校验是否完整、输入是否校验、有没有注入风险、有没有泄露敏感信息、数据变更是否安全并且可以回退、有没有把密钥写进代码。
+   - **测试质量**：测试是否真的在检查行为（而不是恒为真的断言，或只是把实现重复了一遍）？异常和边界情况有没有测到？有没有被删除、跳过或放宽的已有测试？
+   - **与方案和项目惯例的一致性**：偏离方案的地方是否合理并且已有记录？命名、结构、错误处理的方式是否跟随项目现状？
+   - **范围与简单性**：有没有无关的改动、遗留的调试代码、不必要的复杂度？
+6. 写 `code-review.md`。
+
+## 评审意见的写法
+
+每条意见包含：
+
+- 编号（CR-1、CR-2…）
+- 级别：
+  - **阻塞**：会导致功能错误、数据损坏、安全问题，或某条 AC 没有实现
+  - **重要**：应当在交付前修复的缺陷或明显的质量问题
+  - **建议**：改进项，不修也可以交付
+- 位置：文件路径和行号
+- 问题和依据：具体会在什么情况下出错。最好给出能触发问题的输入或操作步骤。
+- 修复方向
+
+只报告你读过代码并确认的问题。有怀疑但没能确认的，标为"待核实"并说明你查了什么。没有发现问题时如实写明，不需要凑数；纯粹的个人写法偏好不要提为"阻塞"或"重要"。
+
+## `code-review.md` 的结构
+
+1. **结论**：通过 / 需要修改，以及一句话理由
+2. **评审范围**：基线提交、当前提交、改动的文件数
+3. **你实际运行的检查及结果**
+4. **验收标准核对表**：逐条 AC，是否实现、是否有测试
+5. **评审意见**：按级别排列
+6. **处理记录**：留空，由下一步填写
+
+## 第 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` 的方法启动。它记录的结论是启动失败时，自己再尝试一次；仍然失败的话，端到端部分记为"无法验证"。
+- 项目已有端到端测试工具：用它为本需求编写端到端测试并运行，测试代码提交到仓库，以后可以重复运行。
+- 项目没有端到端测试工具：直接操作真实入口来验证（调用接口、执行命令、有浏览器自动化工具时操作页面），并记录执行的命令和得到的输出。不要为了这次验证给项目引入新的测试框架。
+- 没有常驻服务的项目（库、脚本、命令行工具）：端到端验证是指像使用者那样，从对外的入口调用并检查结果。
+
+每个场景都要检查用户最终看到的结果，以及应当发生的数据变化确实发生了。验证过程中产生的测试数据，结束后清理掉。
+
+### 判定
+
+对每条 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 不通过或无法验证，或仍有遗留的"严重"或"一般"级别缺陷。

package/engine/prompts/11-report.md

@@ -0,0 +1,93 @@
+# 本步骤任务：完成报告与总结（第 11 步）
+
+## 目标
+
+为提出这个需求的人写一份报告 `report.md`，让他们读完之后知道三件事：需求做成了没有、现在可以怎么用、接下来需要他们做什么。
+
+读者是需求方：测试、产品或项目经理这类有一定技术背景、但不读代码的同事，也没有看过中间任何过程。他们会根据这份报告决定是否验收，并且可能亲自核对，所以报告里的每个结论都必须有前面步骤的记录作为依据，并写明证据在哪里（运行的命令、关键输出、截图或日志的路径）。
+
+无论流水线走到了哪一步，本步骤都会执行。如果前面在方案审核时被阻塞，或者验证没有通过，报告的任务就是把实际情况和需要他们做的决定讲清楚。
+
+## 做法
+
+1. 阅读功能目录里的全部文件。有些文件可能不存在，这说明对应的步骤没有执行。根据 `progress.md` 和现有的文件，判断流水线实际走到了哪里。
+2. 确定总体结论，按下面的规则从严判定：
+   - **已完成，可以验收**：所有 AC 的最终结论都是通过，没有遗留的"严重"或"一般"缺陷，也没有未处理的"阻塞"或"重要"评审意见。
+   - **已完成，有遗留问题**：功能已经实现并且主流程可用，但有 AC 不通过或无法验证，或有尚未解决的问题。
+   - **未完成**：没有进入实现（例如方案审核阻塞），或者实现没有做完，或者主流程不可用。
+
+   AC 的最终结论以 `verification.md` 中最后一轮"复验结果"为准；没有复验时以功能验证的结果为准；没有做过验证的 AC 一律按"未验证"处理，不能算作通过。
+3. 花一点时间核对最关键的事实：功能分支是否存在、最近的提交是否与记录一致。如果发现记录之间互相矛盾，采用更保守的那个说法，并在报告里指出。
+4. 写 `report.md`。
+
+## 写作要求
+
+- 第一句话就给出结论，不要铺垫。
+- 正文讲需求和结果，不讲代码实现。说"提交之后审批人会立刻收到通知"，而不是"实现了事件发布和订阅"。接口、字段、页面、测试命令这类需求方熟悉的内容可以直接写；类名、函数名、提交号放到附录里。
+- 引用 spec 的编号（FR、AC）时，同时写出它的内容，读者不会去翻 spec。
+- 不夸大，也不轻描淡写。有问题的地方，说明它对使用者意味着什么（谁会受到影响、在什么情况下出现、有没有临时的应对办法）。
+- 需要读者做决定的事项，写成他们可以直接回答的问题，并附上你的建议。
+- 篇幅以读者能在五分钟内读完正文为准。
+
+## `report.md` 的结构
+
+**正文（给需求方）**
+
+1. **结论**：三种结论之一，加上一两句话说明
+2. **现在可以做什么**：做成之后用户能看到的变化。可以引用 `design.md` 的"影响摘要"，但要按照实际完成的情况修正。
+3. **验收对照**：
+
+   | 你提的要求 | 结果（已达成 / 未达成 / 未验证） | 是怎么确认的 |
+   | --- | --- | --- |
+
+   每条 AC 一行，"你提的要求"一栏转述它的内容；"是怎么确认的"一栏写明证据，例如运行的测试命令及结果、截图路径，方便需求方自己复核。
+4. **遗留问题与风险**：每一项说明现象、复现方式、对使用者的影响、建议的处理方式。没有就写"无"。
+5. **需要你确认的决定**：汇总 spec、方案、实现各阶段的假设，以及 `decisions.tsv` 中 `needs_human` 为 `yes` 的行，请他们确认。每条写清：做了什么决定、为什么、如果不同意会怎样。被驳回的评审意见只要影响使用者能看到的结果，也列在这里。纯技术性的决定不放在这里，放在附录。
+6. **需要你做的事**：按顺序列出。通常包括：怎么亲自试用一下（给出具体步骤，能用命令验证的给出命令）、需要回答的问题、请开发同事审阅代码并合并上线。
+7. **没有做的事**：spec 中明确不做的范围，以及这次没有完成的部分，避免误会。
+
+**过程总结**
+
+8. **各阶段情况**：方案设计、方案审核、代码实现、代码评审、服务启动、功能验证、缺陷修复，每个阶段用一两句话说明结果和经过了几轮（例如"审核两轮：第一轮提出 3 条必须修改的意见，修订后第二轮通过"）。没有执行的阶段写明"未执行"和原因。
+9. **经验与改进建议**：这次过程中暴露了什么（例如某个问题本来可以在需求对齐阶段就问清楚），下次可以怎么改进。只写确实从这次过程中观察到的，两三条即可。
+
+**附录（给开发同事）**
+
+10. 功能分支名、基线提交和最终提交
+11. 改动文件概览
+12. 测试情况：数量、通过率、新增的测试
+13. 未处理的评审意见和缺陷的编号清单；`decisions.tsv` 中 `needs_human` 为 `no` 的决定条数，以及其中的驳回意见
+14. 各产物文件的路径
+15. 用时与用量：照抄 `<pipeline-context>` 中"用时与用量"的数字，不要自行估算；没有时写"未记录"
+
+## 只做研发时
+
+`<pipeline-context>` 中有"只做研发"一行时，流水线没有做测试验证，测试由人按 `handoff.md` 来做。这时写的是**研发报告**：
+
+- 结论一节说明"研发已完成，待人工测试"，再按上面的规则给出结论，但 AC 没有经过验证这件事本身不算遗留问题。
+- 验收对照表的"结果"一栏，有自动化测试覆盖的写"自动化测试通过（待人工确认）"，其余写"待人工测试"；"是怎么确认的"一栏写对应的测试或"未测试"。
+- "需要你做的事"第一条是按 `handoff.md` 做人工测试，列出"建议重点测试"中的要点。
+- 结果文件的 `outcome`：研发完成且代码评审没有遗留"阻塞"或"重要"意见时写 `completed`；有遗留意见或未完成项时写 `completed_with_issues`；没有完成实现时写 `not_completed`。
+
+## 测试验证的其他做法
+
+`<pipeline-context>` 中的"测试验证"一行说明这次验证的环境和缺陷处理方式：
+
+- 在已部署的测试环境中验证的，在验收对照的证据中写明测试环境和被测的版本；"待重新部署后复验"的项目列入"需要你做的事"。
+- 缺陷"只记录，不修复"的，所有缺陷都列入遗留问题，写明严重程度和复现方式，结论按上面的规则判定。
+- 缺陷"退回研发阶段修复"的，在各阶段情况中写明退回了几次、每次修了什么（见 `changes.md` 中"测试验证退回"各节）。
+
+## 结果文件
+
+```json
+{
+  "outcome": "completed",
+  "summary": "给需求方的结果摘要"
+}
+```
+
+- `outcome`，三选一，与报告结论一致：
+  - `completed`：已完成，可以验收
+  - `completed_with_issues`：已完成，有遗留问题
+  - `not_completed`：未完成
+- `summary`：不超过 8 行的摘要，会被直接转达给需求方。包括：做成了什么、有什么遗留问题（如有）、需要他们做的第一件事。不讲代码实现，不写文件路径（报告路径会另外附上）。

package/engine/prompts/browser-verify.md

@@ -0,0 +1,13 @@
+# 用浏览器验证网页界面
+
+`<pipeline-context>` 中有"浏览器"一行，说明你可以使用 Paseo 内置的浏览器（`browser_*` 工具）。需求方可以在 Paseo 桌面端实时看到你在浏览器中的操作。
+
+涉及网页界面的验收标准，**像使用者一样在浏览器里实际操作一遍**，而不是只看代码或只调接口：
+
+1. 用 `browser_new_tab` 打开服务地址（服务由 Paseo 管理时用给出的地址）。
+2. 按验收标准的"操作"一步步做：`browser_snapshot` 找到元素，用 `browser_click`、`browser_fill`、`browser_select` 等操作，用 `browser_wait` 等待结果出现。
+3. 用 `browser_snapshot` 核对页面上的结果是否符合"预期结果"；关键画面用 `browser_screenshot` 截图。需要检查手机布局时用 `browser_resize`。出现异常时用 `browser_logs` 查看控制台和网络请求。
+4. 在产物中记录：打开的地址、操作步骤、看到的结果、对应的 AC 编号，并注明"浏览器验证，截图见该步骤 agent 的对话记录"。
+5. 用完关闭你打开的标签页（`browser_close_tab`）。
+
+浏览器工具返回 `browser_no_host`（桌面端没有连接）或 `browser_disabled` 时，不要反复重试，改用接口调用、端到端测试等其他方式验证，并在产物中说明浏览器验证没能进行。不要在浏览器中登录生产环境或输入真实的个人信息。

package/engine/prompts/incremental.md

@@ -0,0 +1,21 @@
+# 这次是需求变更后的继续
+
+`<pipeline-context>` 中有"增量继续"一行，说明这个需求之前已经做过一轮（方案，可能还有代码），之后需求说明被修改了：需求方改了需求、回答了方案审核提出的问题，或者验收时发现了问题。这一次**在已有工作的基础上只处理变化的部分**，不要推倒重来。
+
+先了解变了什么：
+
+- 读 `changes.md` 的最后一节（变更内容、原因），再对照 `spec.md` 当前版本。没有 `changes.md` 时，用 `git log -p -- <功能目录>/spec.md` 查看 spec 最近的改动。
+- 方案审核提出过问题的，读 `design-review.md` 最后一轮的问题和 `alignment.md` 中对应的回答。
+- 验收发现问题的，读 `acceptance.md` 中"不通过的处理"。
+- 测试验证退回的（增量继续的原因写着"测试验证发现缺陷"），读 `changes.md` 最后的"测试验证退回"一节和 `verification.md` 最后一轮的缺陷清单。这一次只修这些缺陷：方案设计写修复计划，代码实现逐个修复并补测试，最后重新写 `handoff.md`（追加"第 N 次提测"一节，说明修了哪些缺陷）。
+
+各步骤的做法：
+
+- **方案设计**：保留仍然成立的部分，在 `design.md` 末尾追加"## 第 N 次尝试：需求变更"一节，写明变化点、受影响的 FR/AC、对已有代码的改动计划（改哪些、新增哪些、哪些不动），以及需要补充或修改的测试。原有内容中已经不成立的地方，就地标注"（第 N 次尝试起不再适用，见下文）"，不要整篇重写。
+- **方案审核**：重点审核变化部分是否完整、是否与没变的部分冲突。
+- **代码实现**：在现有代码上修改，只动与变化相关的部分；已有的、仍然正确的实现和测试保留。在 `implementation.md` 末尾追加本次的记录。
+- **代码评审**：评审范围是"本次开始时的提交"之后的改动（`git diff <该提交>..HEAD`），同时确认这些改动没有破坏之前已经通过评审的部分。
+- **功能验证**：变化涉及的 AC 全部重新验证；其余 AC 至少跑一遍现有的自动化测试，确认没有回退。
+- **完成报告**：在开头说明这是第几次尝试、因为什么变化，验收对照表中标出哪些 AC 是这次新增或修改的。
+
+上一次没有写过代码时（`<pipeline-context>` 中"上一次是否已经写过代码：否"），实现类步骤按正常方式进行，只是方案设计要在已有的 `design.md` 基础上修订。

package/engine/prompts/panel-member.md

@@ -0,0 +1,38 @@
+# 本步骤任务：评审小组成员
+
+## 目标
+
+这一轮评审由一个评审小组完成：几位评审者（通常使用不同的模型）各自独立评审，之后由一位汇总者核实全部意见、归类，并写出正式的评审结论。你是其中一位成员。你是哪一轮、哪一位、意见写到哪里，见 `<pipeline-context>` 中"评审小组"和"你的意见文件"两行。
+
+不同评审者容易发现不同的问题，所以请**独立判断**：不要读其他成员的意见文件（`review-panel/` 目录下的其他文件），也不要试图和他们保持一致。
+
+## 做法
+
+1. 按下文"评审标准"中的方法评审：读什么、检查什么、意见怎么分级，都以它为准。
+2. `<pipeline-context>` 中有"你的关注重点"时，在完整评审的基础上，对那个方面看得更仔细。
+3. 把意见写进**你自己的意见文件**（路径见 `<pipeline-context>`）。不要写入或修改 `design-review.md`、`code-review.md`，也不要改动代码。
+
+## 意见文件的内容
+
+1. **总体判断**：你认为应该通过、需要修改，还是存在必须由需求方决定的问题，一句话理由
+2. **你实际检查了什么**：读了哪些文件，运行了哪些命令及结果
+3. **意见**：按"评审标准"中的格式和级别逐条列出。每条写清问题、依据（代码位置、spec 编号、能触发问题的输入或步骤）和修复方向。只写你确认过的问题；有怀疑但没能确认的，标为"待核实"
+4. **需要需求方决定的问题**（如有）
+
+没有发现问题时如实写明，不需要凑数。
+
+## 与其他成员同时运行
+
+其他成员和你在同一个目录中同时工作，所以：
+
+- 不要提交任何东西，也不要写 `progress.md` 和 `decisions.tsv`。这些优先于前文"结束方式"和"记录不显而易见的决定"中的要求；你的判断写在意见文件里，由汇总者决定是否记入决策记录。汇总者会核实你的意见，并把意见文件和正式结论一起提交。
+- 不要修改任何已有文件，只写你自己的意见文件和结果文件。
+- 需要启动服务时，使用不会与别人冲突的端口；拿不准时以阅读代码、运行单元测试和静态检查为主，并在意见文件中说明。
+
+## 结果文件
+
+```json
+{ "status": "done" }
+```
+
+- `status`：完成了完整的评审时为 `"done"`；因为时间或环境原因只评审了一部分时为 `"partial"`，并在意见文件的"你实际检查了什么"中说明没有覆盖的部分。