paseo-req-kit 1.7.0-beta.3 → 1.8.0

package/docs/guide//345/256/211/350/243/205/344/270/216/345/215/207/347/272/247.md

@@ -29,7 +29,7 @@ Windows 上 `~` 即 `%USERPROFILE%`（如 `D:\Users\<用户名>`）。安装器
 
 | 项目 | 要求 | 如何确认 |
 | --- | --- | --- |
-| Paseo | 0.11，daemon 在运行 | Paseo 桌面端能正常对话；默认地址 `ws://127.0.0.1:6767/ws` |
+| Paseo | 0.11，daemon 在运行（一键安装会在没有时安装 Paseo 命令行并启动） | Paseo 桌面端能正常对话，或浏览器打开 `http://localhost:6767/`；默认地址 `ws://127.0.0.1:6767/ws` |
 | Node.js | 22 或更新 | `node -v` |
 | npm | Node.js 自带；公司网络需配置镜像（`npm config get registry`） | `npm -v` |
 | git | 近期版本（只有 git 方式安装时需要） | `git --version` |
@@ -45,15 +45,24 @@ Windows 上 `~` 即 `%USERPROFILE%`（如 `D:\Users\<用户名>`）。安装器
 
 ```bash
 # macOS、Linux、Windows 的 Git Bash 或 WSL
-curl -fsSL https://raw.githubusercontent.com/yiyisf/paseo-req-kit/main/install.sh | sh
+curl -fsSL https://paseo-req-kit.vercel.app/install.sh | sh
 ```
 
 ```powershell
 # Windows PowerShell（不受脚本执行策略限制）
-irm https://raw.githubusercontent.com/yiyisf/paseo-req-kit/main/install.ps1 | iex
+irm https://paseo-req-kit.vercel.app/install.ps1 | iex
 ```
 
-脚本依次：检查 Node.js 22+、npm、git；从 npm 安装 `paseo-req-kit`，npm 上没有时改用 GitHub Release 的安装包；npm 全局目录不可写时装到 `~/.req-kit/npm`（不需要 sudo）；运行 `req setup`；本机配置还没填时运行 `req configure`；最后提示把 `req` 加入 PATH（如需要）。选项：`install.sh` 写在 `sh -s --` 之后（`--beta`、`--version <版本>`、`--from npm|release`、`--no-configure`）；`install.ps1` 用变量（`$ReqKitBeta = $true; irm … | iex`，还有 `$ReqKitVersion`、`$ReqKitFrom`、`$ReqKitNoConfigure`）。完成后接着做下面的**第四步**到**第六步**。
+脚本依次：检查 Node.js 22+、npm、git；从 npm 安装 `paseo-req-kit`，npm 上没有时改用 GitHub Release 的安装包；npm 全局目录不可写时装到 `~/.req-kit/npm`（不需要 sudo）；**检查 Paseo**（见下）；运行 `req setup`；本机配置还没填时运行 `req configure`；最后提示把 `req` 加入 PATH（如需要）。选项：`install.sh` 写在 `sh -s --` 之后（`--beta`、`--version <版本>`、`--from npm|release`、`--no-configure`、`--skip-paseo`）；`install.ps1` 用变量（`$ReqKitBeta = $true; irm … | iex`，还有 `$ReqKitVersion`、`$ReqKitFrom`、`$ReqKitNoConfigure`、`$ReqKitSkipPaseo`）。
+
+检查 Paseo 这一步：
+
+- **有 `paseo` 命令**：核对它的版本是否在这个 req-kit 支持的范围内（不在时提醒，不替换）；开启 daemon 自带的网页界面（`paseo daemon config set features.webUi.enabled true`）；daemon 没在运行就 `paseo daemon start`。daemon 已在运行而网页界面是刚开启的，只提示 `paseo daemon restart`，不自动重启——重启会中断正在运行的 agent。
+- **没有 `paseo` 命令，但 daemon 在运行**：通常是桌面版 Paseo 管理的 daemon，什么都不装；需要网页界面时在桌面版中开启。
+- **都没有（新机器）**：用 npm 安装与 req-kit 匹配的 Paseo 命令行（例如 `@getpaseo/cli@~0.11.0`），开启网页界面，启动 daemon。之后在浏览器打开 `http://localhost:6767/` 就能用 Paseo 对话。
+- 最后检查有没有 agent 命令行（Claude Code、Codex、OpenCode、Pi、Copilot），一个都没有时提醒：至少装一个并登录，再运行 `req configure`。
+
+不想让脚本动 Paseo（例如由别人统一管理）时加 `--skip-paseo`。完成后接着做下面的**第四步**到**第六步**。
 
 **也可以用 npm 安装（1.7.0 起）。** 一键安装做的就是这几条命令，Windows 上 `req` 命令由 npm 放进 PATH，不用自己设置：
 
@@ -77,19 +86,19 @@ req doctor --no-project       # 体检
 **第一步：取得程序。** 把要安装的版本放进它自己的版本目录：
 
 ```bash
-git clone --branch 1.7.0-beta.3 --depth 1 https://github.com/yiyisf/paseo-req-kit ~/tools/req-kit/versions/1.7.0-beta.3
+git clone --branch 1.8.0 --depth 1 https://github.com/yiyisf/paseo-req-kit ~/tools/req-kit/versions/1.8.0
 ```
 
 Windows PowerShell：
 
 ```powershell
-git clone --branch 1.7.0-beta.3 --depth 1 https://github.com/yiyisf/paseo-req-kit "$env:USERPROFILE\tools\req-kit\versions\1.7.0-beta.3"
+git clone --branch 1.8.0 --depth 1 https://github.com/yiyisf/paseo-req-kit "$env:USERPROFILE\tools\req-kit\versions\1.8.0"
 ```
 
 **第二步：安装依赖并启用。**
 
 ```bash
-cd ~/tools/req-kit/versions/1.7.0-beta.3
+cd ~/tools/req-kit/versions/1.8.0
 npm install
 node install.mjs
 ```

package/docs/guide//347/273/264/346/212/244/350/200/205/346/214/207/345/215/227.md

@@ -38,7 +38,7 @@
 3. **写 `CHANGELOG.md`**：新增一节，分"使用者会看到的变化"和"升级须知"两部分。升级须知写清：要不要重跑 `/req-setup`、提示词有哪些变化（影响用 `prompts.local/` 覆盖过的人）、文件格式有没有变化、旧行为的兼容方式。
 4. **验证**：`npm test`、`npm run typecheck`、`npm run eval:self-check`；步骤提示词或引擎有改动时跑 `npm run eval`，把 `summary.md` 复制到 `evals/baselines/<版本>.md`；入口或手册有改动时跑对话评估，记入记分表。主版本发布前，在一个真实项目里试运行一周。
 5. **冒烟测试**：在一台干净的机器（或临时的 `REQ_KIT_HOME` 和 HOME）上按 [安装与升级](安装与升级.md) 安装，跑冒烟测试第 1–4 项；至少有一台是 Windows。
-6. **合并到 `main` 并打标签**：在 GitHub 上建 Release 并新建标签 `<版本>`（或推送 `git tag -a <版本>`）。标签触发 `.github/workflows/release.yml`：再跑一遍测试、类型检查和评估自检，核对标签与 `package.json` 版本一致，然后发布到 npm（预发布版用 `beta` 标签，正式版用 `latest`），正式版再设置 `paseo-<小版本>` 标签，把 `npm pack` 的安装包附在 Release 上，Release 正文取自 CHANGELOG 的这一节。标签同时也是 git 方式安装的版本列表，所以要在验证完成后再打；打错了尽快删除标签，npm 上发布错的版本用 `npm deprecate` 标注（npm 不允许重新发布同一版本号）。
+6. **合并到 `main`，标签自动打上**：`main` 收到 `package.json` 版本号还没有标签的提交时，`.github/workflows/release.yml` 先把这个提交打上同名标签（不用自己打，也不需要推送标签的权限），接着在同一次运行里发布。也可以照旧自己打：在 GitHub 上建 Release 并新建标签 `<版本>`，或推送 `git tag -a <版本>`，同样会触发发布。发布流程：再跑一遍测试、类型检查和评估自检，核对标签与 `package.json` 版本一致，然后发布到 npm（预发布版用 `beta` 标签，正式版用 `latest`），正式版再设置 `paseo-<小版本>` 标签，把 `npm pack` 的安装包附在 Release 上，Release 正文取自 CHANGELOG 的这一节。标签同时也是 git 方式安装的版本列表，所以改版本号的提交要在验证完成后再合到 `main`（自动打标签的时机就是它）；打错了尽快删除标签，npm 上发布错的版本用 `npm deprecate` 标注（npm 不允许重新发布同一版本号）。
 7. **通知**：把"使用者会看到的变化"发给使用者，把"升级须知"发给各台机器的安装者；团队配置的 `requiredVersion` 需要提高时，在团队配置仓库中修改。
 
 **npm 发布的一次性设置**：可信发布（trusted publisher）要在 npm 上已有的包的设置页里配置，所以第一个版本在本机手工发布一次，不需要生成任何口令：

package/docs/guide//351/241/271/347/233/256/345/256/232/345/210/266/344/270/216/350/277/220/350/241/214/350/247/204/345/210/231.md

@@ -19,6 +19,109 @@
 
 `/req` 会根据需求推荐档位，用户确认后写进 spec（`- 档位：快速`）。流水线按以下顺序决定档位：`--profile` 参数 → 续跑时沿用上次的档位 → spec 中的档位 → 配置中的 `defaultProfile`。各档的轮数和是否做服务启动验证可以在配置的 `profiles` 中调整。
 
+## 需求类型
+
+spec 头部的 `- 类型：` 决定流水线走哪种做法（1.8 起）。缺陷、重构、评估有自己的做法，新需求和小改动走通常的流程：
+
+| 类型 | 做法 | 关键证据 |
+| --- | --- | --- |
+| 缺陷（`缺陷`、`bug`） | 方案设计改为"复现与定位"：先提交一个修复前失败的复现测试或脚本，写 `diagnosis.md`（根因、影响面）；复现不了就暂停，把需要补充的信息发回对话。修复要让复现转绿，评审实际确认它修复前失败 | 同一个复现，修复前失败、修复后通过 |
+| 重构（`重构`、`技术改进`） | 先补特征测试锁住现有行为并单独提交，再小步改动、每步全绿；评审的首要问题是"行为有没有变" | 重构前后同一组测试一致 |
+| 评估（`评估`、`调研`） | 只读：调研评估（`assessment.md`）→ 评估审阅 ⇄ 修订 → 评估报告；没有实现、评审、提测和验证，执行方式按连续 | 引用的代码位置和实际运行的命令 |
+
+各类型的做法写在 `engine/prompts/types/<类型>.md`，按步骤分节，接在每一步的任务之后；可以用 `prompts.local/types/` 覆盖。不想用某个类型的做法时，从配置 `requirementTypes`（默认 `["defect", "refactor", "assessment"]`）中去掉它，这个类型就按新需求处理。设计决定见 ADR 0023。
+
+## 方案确认点：开工前请需求方确认"做完后会看到什么"
+
+方案审核通过后、写代码之前，流水线可以停下来请需求方确认（1.8 起）。方案设计写 `preview.md`（按操作顺序描述做完后会看到什么、需要确认的假设、不会变的地方），界面改动还在 `prototype/` 中画出静态的原型页面。对话里的 AI 把要点讲给需求方：确认后执行 `--approve`（终端里 `req approve <需求>`）开始写代码；要改的，更新需求说明后 `--resume`，方案调整后再确认一次。需求方确认过的预览和原型，实现和功能验证都以它为准：界面与原型不一致按缺陷处理。
+
+| 配置 | 默认 | 说明 |
+| --- | --- | --- |
+| `designApproval.mode` | `ui` | `ui`：方案判断这次是界面改动（结果文件 `ui_change`）时才停；`always`：每次都停；`off`：不停 |
+| `designApproval.profiles` | `["standard"]` | 哪些档位使用；快速档默认不停 |
+| `designApproval.autoContinueHours` | 0 | 大于 0 时，等了这么久还没确认就按方案继续（通过对话执行）；0 表示一直等待。等待超过 `waitingReminderHours` 会提醒一次 |
+
+等待确认时进度显示"等待需求方确认方案"，需求总览归入"需要处理"，外部通知收到 `approval` 事件。评估类需求不写代码，不经过确认点。
+
+## 代码评审分两个方向
+
+标准档第一轮代码评审由两位评审者同时进行（1.8 起），各自写意见，再由 reviewer 核实、汇总成一份结论：
+
+- **规格评审**：每条验收标准是否真的实现并有测试、测试的期望值是否与验收标准的例子一致、有没有做需求之外的事、与确认过的预览是否一致。
+- **规范评审**：项目惯例和范例文件、术语表中的代码名称、测试质量、安全与数据、简单性，以及可以变成规则的问题。
+
+两位都用配置的 reviewer agent，相当于多两次评审的用量；之后的轮次只核对修复，仍由一位评审。`reviewAxes.enabled` 设为 `false` 关闭，`reviewAxes.profiles` 选择档位（默认只有标准档）。配置了评审小组（`reviewPanel`）时，以评审小组为准。
+
+## 验收测试先提交
+
+方案判断适合测试先行时，代码实现先把从验收标准的例子写出的测试单独提交一次（这时它们是失败的），在结果文件中写明这些测试文件和那次提交。代码评审前，流水线核对它们之后有没有被改过，被改过的交给评审逐个确认有没有依据：为了让测试通过而放宽断言的，按阻塞提出。
+
+## 术语表和范例文件
+
+- **`GLOSSARY.md`**（仓库根目录）：业务词、含义、代码中的名字。`/req-setup` 第一次整理，访谈遇到新词时补充，方案设计为新概念补上代码中的名字；各步骤按它命名，规范评审检查是否一致。
+- **范例文件**：`/req-setup` 在 `project-notes.md` 中列出各类代码（接口、页面、测试、迁移脚本）写得最好的文件。方案的每个任务写明参照哪个文件，实现照它的结构、命名、错误处理和测试写法来。
+
+## 反复出现的问题变成规则
+
+完成报告把这次评审、质量门、缺陷中"一条项目规则就能挡住"的问题写进功能目录的 `lessons.tsv`（类别、问题、出处、建议的规则、放在哪一层）。同一个类别在两个以上的需求里出现时，`req digest` 的需求总览会列在"反复出现的问题"中，`/req-retro` 会建议把它变成 lint 规则、类型约束、测试或项目说明里的一行，批准后落地。已经处理的类别写进 `.requirement-pipeline/lessons-handled.txt`（一行一个），总览不再提示。
+
+## 质量门：流水线自己运行的检查
+
+项目配置 `.requirement-pipeline.json` 的 `checks` 列出流水线**自己运行**的检查，通常由 `/req-setup` 从实际跑通的命令写入：
+
+```json
+{
+  "checks": [
+    { "name": "lint", "command": "npm run lint" },
+    { "name": "web 测试", "command": "npm test", "cwd": "web" },
+    { "name": "server 测试", "command": "npm test", "cwd": "server", "timeoutMinutes": 15 }
+  ]
+}
+```
+
+- **基线**：每次尝试开始时（方案设计之前）把所有检查运行一遍，记下哪些原本就失败。
+- **之后**：代码实现（每一片）、评审问题修复、缺陷修复结束后，运行与改动相关的检查。**改动前通过、现在失败**的，把命令和输出发回那一步的 agent 修复，最多 `qualityGate.fixAttempts` 次（默认 2）。仍然失败时照常往下走，交给代码评审和报告：报告的结论最高为"有遗留问题"。原本就失败的检查不拦，但会在报告中列出。
+- **多模块**：带 `cwd` 的检查只在这个目录有改动时运行；需要更精确时用 `paths`（例如 `["server/", "shared/"]`，可以用 `*`）。
+- 只放几分钟内能跑完的检查（格式、lint、类型检查、单元测试、构建）。端到端测试、需要启动服务的检查由功能验证负责。命令通过系统 shell 运行（Windows 上是 cmd.exe），和 `paseo.json` 一样写成各系统通用的形式。单项检查的时限是 `timeoutMinutes`，默认 `qualityGate.timeoutMinutes`（20 分钟）。
+- 输出保存在 `<功能目录>/.pipeline/checks/<步骤>/`，结果在状态文件的 `gate` 中，进度查询显示最近一次的结果。没有配置 `checks` 时不运行，报告注明"未配置"，`/req-doctor` 会提醒。
+
+## 按切片实现
+
+方案把实施计划分成几个**纵向切片**（每片是一段能单独演示和验证的功能，例如"能发送验证码"）。标准档有两片以上时，代码实现按片逐个进行：每片一个新的 agent、各自提交、各自过一次质量门，子 agent 列表中显示为"5-代码实现 第2/3片"；中断后只重做当前片。快速档、只有一片时与原来相同。
+
+| 配置 | 默认 | 说明 |
+| --- | --- | --- |
+| `slices.profiles` | `["standard"]` | 哪些档位按切片实现；`[]` 关闭 |
+| `slices.max` | 6 | 最多几片；方案分得更多时最后几片合并 |
+
+## 范围检查
+
+方案在结果文件中列出预计改动的文件和目录（`files`）。代码评审前，流水线比对这次实际改动的文件，把清单之外的列给评审逐一判断：为实现需求所必需的写理由，与需求无关的要求撤回。结论写进报告附录。
+
+## 关联仓库（只读参考）
+
+前端项目要用后端的接口、一个服务要用另一个服务的数据格式时，在项目配置中登记相关的仓库，步骤 agent 就能读它们，不用猜：
+
+```json
+{ "relatedRepos": [{ "name": "后端", "path": "../backend", "role": "提供登录和订单接口" }] }
+```
+
+- `path` 相对项目目录（团队约定把相关仓库放在同一个上级目录最方便），也可以写 `~/` 开头的路径。本机没有这个目录时跳过，`/req-doctor` 会提醒。
+- 步骤会看到每个关联仓库的位置、当前分支和提交，只读参考：不修改、不提交、不切换分支。验证需要对方的服务时，优先用已部署的测试环境。
+- 两边都要改的需求（例如后端加接口、前端加页面）可以作为联合需求一起做，见下一节。
+
+## 联合需求：一个需求，几个仓库
+
+需求说明头部写 `- 联合开发：后端`（`relatedRepos` 中登记的名称，最多两个）时（1.8 起）：
+
+1. **准备**：流水线为每个联合开发的仓库新建一个 Paseo 工作区，分支同名（`feature/<需求>`），从那个仓库当前检出的分支切出；那份检出本身不动。需求说明同步过去并提交。
+2. **方案和接口约定**：在主仓库（发起需求的仓库）设计整个需求，`design.md` 按仓库分开写，`contract.md` 写双方的接口约定（字段、错误码、示例）。方案审核把接口约定一起审，通过后冻结。需求说明、方案、接口约定同步到其他仓库的功能目录并提交。
+3. **同时开发**：每个仓库各由一个 agent 实现、各自评审和修复，互不等待：提供接口的一边按约定写接口测试，调用的一边用约定的示例做测试替身。每个仓库用它自己的 `checks` 做质量门（写在它自己的 `.requirement-pipeline.json` 中），用它自己的项目说明和验证方法。
+4. **一起验证**：提测说明、功能验证和报告在主仓库。验证前各仓库 `paseo.json` 中的服务都由 Paseo 用当前代码启动；验证结果写明每个缺陷属于哪个仓库，缺陷发回那个仓库修复，再一起复验。
+5. **合并**：每个仓库各有自己的分支，只做本地提交。提测说明和报告写明合并顺序（通常先合提供接口的一边），由人来合并。
+
+一个仓库的步骤失败时，流水线等其他仓库正在进行的步骤做完再中断；继续时沿用已建的工作区和已完成的步骤。不做的：跨仓库的统一提交或合并、自动部署、超过三个仓库、克隆本机没有的仓库。设计决定见 ADR 0025。
+
 ## 执行方式：连续、分阶段、只做研发
 
 第 3–11 步分为两个阶段：**研发**（方案设计 → 方案审核 ⇄ 修订 → 实现 → 代码评审 ⇄ 修复 → 提测说明）和**测试验证**（服务启动 → 功能验证 → 缺陷处理），之后是完成报告。研发阶段的最后一步写提测说明 `handoff.md`：改了什么、怎么跑起来、自测结果、建议重点测试、已知问题、测试前的准备。
@@ -105,6 +208,8 @@
 
 **`verify.md`** 写这个项目怎么安装依赖、启动服务、运行测试、准备测试数据，命令要实际运行过。结构建议见 `contracts/verify.md`。步骤 agent 发现它过时或不准确时，会在 `service-start.md` 或 `verification.md` 的"建议写入 verify.md 的内容"一节给出实际可行的做法；再次运行 `/req-setup` 会参考这些建议更新它。项目的构建文件改过而 `verify.md` 没有更新时，`/req-doctor` 会提醒。
 
+项目配置还常写 `checks`（质量门）和 `relatedRepos`（关联仓库），见上文。`checks`、`relatedRepos`、`requirementTypes` 整体替换，`qualityGate`、`slices` 按项合并。
+
 **`steps/<步骤>.md`** 的文件名用步骤 ID：`design`、`design_review`、`design_revise`、`implement`、`code_review`、`review_fix`、`service_start`、`verify`、`defect_fix`、`reverify`、`report`。例如 `steps/verify.md` 写"端到端测试用 `pnpm e2e` 运行，测试账号见 docs/test-accounts.md"。
 
 这些内容追加在步骤任务之后，并注明"与通用要求冲突时以项目说明为准"，但"如实报告"和安全要求始终有效。

package/engine/prompts/00-shared-context.md

@@ -10,6 +10,8 @@
 
 `<pipeline-context>` 中的"档位"说明这次需求的规模。档位为"快速"时，这是一个小改动：每个环节只做一轮，各产物只写对这个改动真正有用的内容（例如方案只需几段话，测试只覆盖验收标准），不必逐项填满模板；对质量和"如实报告"的要求不变。
 
+`<pipeline-context>` 中有"需求类型"（缺陷修复、重构、评估）时，本步骤任务之后会有"本需求类型的做法"一节，说明这类需求在这一步要多做或少做什么；两者不一致时，以它为准。
+
 带 ⇄ 的环节会按需重复，每个环节都有最多轮数，用完后流程继续往下走，未解决的问题由最终报告交给人来决定。你负责其中哪一步、是第几轮，见本文末尾的 `<pipeline-context>`。
 
 ## 仓库目录和功能目录
@@ -24,11 +26,13 @@
 | `alignment.md` | 需求对齐阶段（已完成） | 访谈中每个决定的记录 |
 | `design.md` | 方案设计、方案修订 | 技术方案、实施计划、测试策略 |
 | `design-review.md` | 方案审核 | 审核意见和结论 |
+| `preview.md`、`prototype/` | 方案设计、方案修订（开启方案确认点时） | 给需求方确认的"做完后你会看到什么"和界面原型；需求方确认后，实现和验证以它为准 |
 | `implementation.md` | 代码实现 | 实际做了什么、测试结果、与方案的偏离 |
 | `code-review.md` | 代码评审、评审问题修复 | 评审意见和处理记录 |
 | `service-start.md` | 服务启动验证 | 启动方法和启动结果 |
 | `verification.md` | 功能验证、缺陷修复、复验 | 逐条验收结果、缺陷和处理记录 |
 | `report.md` | 完成报告 | 给需求方看的最终报告 |
+| `lessons.tsv` | 完成报告（如有） | 一条项目规则就能挡住的问题，用来发现反复出现的问题 |
 | `progress.md` | 每个步骤 | 每步结束时追加一行 |
 | `decisions.tsv` | 每个步骤 | 决策记录：每个不显而易见的选择追加一行 |
 | `changes.md` | 需求对齐阶段（如有） | 需求变更记录：spec 每次修改改了什么、为什么 |

package/engine/prompts/02-spec-review.md

@@ -19,7 +19,7 @@
 3. 逐项检查：
    - **歧义**：同一句话能理解成两种做法，而两种做法结果不同。
    - **遗漏**：异常和边界情况（输入为空、超长、重复提交、并发、超时、外部服务失败）、权限（谁能做、谁不能）、已有数据怎么处理、和已有功能的关系。
-   - **验收标准能否验证**：每条 AC 是否写清前置条件、操作和预期结果，预期结果是否具体到可以判断对错（"提示友好"这类说法不行）。
+   - **验收标准能否验证**：每条 AC 是否写清前置条件、操作和预期结果，预期结果是否具体到可以判断对错（"提示友好"这类说法不行）；是否至少有一组具体的输入和期望输出（这些例子会直接成为测试的期望值）；按规则计算的，例子是否覆盖了边界。缺少例子的，在问题里替需求方拟好例子，请他们确认或修改。
    - **冲突**：FR 之间、FR 与 AC 之间、与访谈记录、与现有系统行为之间的矛盾。
    - **范围**：写进来但与目标无关的内容，或者为了达到目标显然还需要、却没有写的内容。
 4. 只报告真正会影响结果的问题。措辞、格式之类的小问题最多列三条，放在最后。

package/engine/prompts/03-design.md

@@ -13,9 +13,10 @@
    - 这个需求会涉及哪些模块、数据和接口？
    - 项目里类似的功能是怎么做的？哪些可以直接复用？
    - 项目怎么运行、怎么测试？实际执行一次现有的测试、类型检查和构建命令，记录基线结果。后面的步骤需要用它来区分"原来就失败"和"这次改坏的"。
-3. 设计满足 spec 的最简单方案。优先沿用项目已有的模式；不为 spec 没有提出的将来需求做预留。如果确实存在值得认真比较的另一种做法，简要写明取舍；没有就不必硬凑。
-4. 把方案拆成可以独立完成、独立验证的小任务，排好顺序。
-5. 写 `design.md`。
+3. 命名用项目的说法：`GLOSSARY.md` 中已有的业务词，用它写明的代码名称；这次引入的新业务概念，在 `GLOSSARY.md` 中补一条（含义和代码中的名字），和 `design.md` 一起提交。
+4. 设计满足 spec 的最简单方案。优先沿用项目已有的模式；不为 spec 没有提出的将来需求做预留。如果确实存在值得认真比较的另一种做法，简要写明取舍；没有就不必硬凑。
+5. 把方案拆成可以独立完成、独立验证的小任务，排好顺序；需要时再把任务分组成纵向切片（见下文"实施计划"）。
+6. 写 `design.md`。
 
 ## `design.md` 的内容
 
@@ -24,17 +25,32 @@
 3. **现状**：相关的模块和文件（带路径）、会复用的现有做法。
 4. **方案**：数据的变化、接口和交互的变化、关键流程、出错时的处理、权限控制、对已有数据和已有功能的兼容。写到实现者不需要再做设计决定的程度。
 5. **影响范围与风险**：会碰到哪些已有功能，可能出什么问题，怎么回退。
-6. **实施计划**：按顺序列出任务。每个任务写明要改或新建的文件、完成的标志、对应的 AC。
+6. **实施计划**：按顺序列出任务。每个任务写明要改或新建的文件、完成的标志、对应的 AC，以及**参照的已有文件**：项目里做同类事情（同类接口、页面、测试、迁移脚本）写得最好的一个文件，实现时照它的结构、命名、错误处理和测试写法来（项目说明中列了范例文件的，优先用它们）。找不到合适参照的写"无"。
+   - **切片**（`<pipeline-context>` 中有"切片上限"时）：把任务分组成几个**纵向切片**。每一片是一段能单独演示和验证的完整功能，从入口一直做到数据（例如"能发送验证码"），而不是按技术层横着切（例如"先写完所有数据库代码"）。每片写明：编号和标题、包含哪些任务、对应的 AC、依赖前面哪一片、做完的标志。按依赖排序，片数以 `<pipeline-context>` 中的"切片上限"为限，通常 2–4 片就够。需求本来就小、拆开反而别扭的，只写一片。每一片会由一个新的 agent 单独完成和提交，所以片与片之间的交接要在方案里写清楚（前一片留下了什么、后一片从哪里接着做）。`<pipeline-context>` 写着"本次不按切片实现"时不用分片。
+   - **改动的文件清单**：汇总所有任务要改或新建的文件和目录（不含功能目录本身），写进结果文件的 `files`。流水线会在代码评审前比对实际改动的文件，清单之外的改动要由评审逐一说明是否必要，所以要列全，但不要为了"保险"把整个仓库写进去。
 7. **测试策略**：
    - 项目现有的测试方式、运行命令和基线结果。
    - 本需求是否适合测试先行（TDD），并给出理由。适合的情况：项目已有可用的测试框架，并且要改的是可以单独测试的逻辑。不适合的情况：例如纯配置或样式调整、项目没有任何测试基础、改动主要是胶水代码而测试成本远高于收益。不适合时，写明用什么方式替代验证。可以对不同任务给出不同结论。
-   - 测试用例清单：每条 AC 用什么测试覆盖（单元、集成，还是端到端）。
+   - 测试用例清单：每条 AC 用什么测试覆盖（单元、集成，还是端到端）。测试的输入和期望值**直接取自 AC 中的例子**，不另行编造；AC 没有给例子的，写明你采用的例子，并记入"假设"。
    - 端到端验证方式：项目是否已有端到端测试工具；没有的话，用什么方式从用户入口把关键流程走一遍（页面操作、接口调用、命令行调用）。
 8. **运行方式**：这个项目是否有需要启动起来才能验证的常驻服务（Web 服务、API、后台进程等）。有的话写明启动命令、依赖的本地服务、端口、怎么判断启动成功。库、脚本、一次性命令行工具这类不需要常驻进程的项目，写"无常驻服务"。
-9. **假设**：你按最合理的理解定下来、但 spec 没有明说的事。
+9. **假设**：你按最合理的理解定下来、但 spec 没有明说的事。每条标明对使用者可见的影响：**界面**、**数据**、**权限**或**无**。影响界面、数据或权限、并且猜错就会做出错误东西的，不要当作假设，写进"阻塞问题"；猜错容易调整的，留在这里：开启了方案确认点时它们会写进 `preview.md` 请需求方过目，否则由最终报告交给需求方确认。
 10. **阻塞问题**：只有需求方能回答、猜错会做出错误东西的问题。没有就写"无"。有阻塞问题时，仍然把能确定的部分设计完整。
 11. **影响摘要**：用 3–6 句话说明，做完之后使用者会看到什么变化、什么不会变。可以提到接口、页面、字段这类需求方熟悉的东西，但不讲代码结构。这段话会被最终报告引用。
 
+## 方案确认点（`<pipeline-context>` 中有"方案确认点"时）
+
+方案审核通过后、写代码之前，流水线会停下来请需求方确认"做完之后会看到什么"。这是发现"做对了，但不是想要的"成本最低的时候，所以要写得让不读代码的人一看就能判断。
+
+- **判断是不是界面改动**：这次改动会不会改变使用者在页面、窗口、命令行输出、导出文件中看到的样子或操作方式。结果文件中写 `ui_change`（`true` / `false`）。
+- `<pipeline-context>` 写着"开启"，或者写着"界面改动时开启"且 `ui_change` 为 `true` 时，在功能目录写 `preview.md`：
+  1. **做完后你会看到什么**：按使用者的操作顺序描述（打开哪个页面、看到什么、点了之后发生什么），每一段注明对应的 AC。
+  2. **界面原型**（界面改动）：在功能目录的 `prototype/` 下写一个或几个**静态 HTML 页面**（只用内联的 HTML 和 CSS，不引用外部文件，不连接任何服务），按项目现有页面的布局、文字和样式画出改动后的样子；正常、出错、空数据等关键状态各画一份或在同一页中并列。`preview.md` 中列出每个原型文件对应的 AC 和状态。原型只用来确认，不是产品代码，实现时不要复用它的代码。
+  3. **接口示例**（改动接口时）：一两组真实的请求和响应。
+  4. **需要你确认的假设**：上文"假设"中影响界面、数据、权限的那些，用需求方的话写出来。
+  5. **不会变的**：使用者可能担心、但这次不改的地方。
+- 不需要写 `preview.md` 时不写。
+
 ## 完成标准
 
 - 每条 AC 在需求对照表和测试用例清单里都能找到。
@@ -44,7 +60,14 @@
 ## 结果文件
 
 ```json
-{ "has_runnable_service": true }
+{
+  "has_runnable_service": true,
+  "slices": ["S1 发送验证码（AC-1.1、AC-1.2）", "S2 验证码登录（AC-2.1、AC-2.2）"],
+  "files": ["src/auth/", "src/pages/login.tsx", "test/auth/"]
+}
 ```
 
-- `has_runnable_service`（布尔值）：项目有需要启动才能验证的常驻服务时为 `true`，否则为 `false`。它决定后面是否执行"服务启动验证"这一步。
+- `has_runnable_service`（布尔值，必填）：项目有需要启动才能验证的常驻服务时为 `true`，否则为 `false`。它决定后面是否执行"服务启动验证"这一步。
+- `slices`（字符串数组，可选）：实施计划的切片，按实现顺序，每项写"编号 标题（对应的 AC）"，与 `design.md` 一致。只有一片或本次不按切片实现时可以省略。有两片以上时，流水线会按片逐个启动实现。
+- `files`（字符串数组，可选，建议填写）：预计要改或新建的文件和目录，相对仓库目录。目录以 `/` 结尾；可以用 `*` 通配（如 `src/**/*.test.ts`）。
+- `ui_change`（布尔值，`<pipeline-context>` 中有"方案确认点"时必填）：这次改动是否改变使用者看到的界面或操作方式。

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

@@ -17,8 +17,9 @@
    - **风险**：数据安全、权限漏洞、不可回退的变更、对外部系统的影响。
    - **简单性**：有没有更简单的做法能达到同样效果？有没有不必要的抽象或预留？
    - **可验证性**：测试策略能否真正证明每条 AC？"是否采用测试先行"的判断理由是否成立？端到端验证方式是否可行？
-   - **可执行性**：实施计划的任务是否足够小、顺序是否合理、完成标志是否明确？
-   - **假设与阻塞问题**：假设是否合理？有没有被当作"假设"处理、实际上应该由需求方决定的事？
+   - **可执行性**：实施计划的任务是否足够小、顺序是否合理、完成标志是否明确？分了切片的：每一片是否是能单独验证的纵向功能（而不是按技术层横切）、依赖顺序是否成立、片与片的交接是否写清楚、数量是否适中？结果文件中的文件清单（`files`）是否覆盖了实施计划要改的文件？
+   - **假设与阻塞问题**：假设是否合理、是否标明了对使用者可见的影响？有没有被当作"假设"处理、实际上应该由需求方决定的事？
+   - **给需求方的预览**（有 `preview.md` 时）：是否与方案一致；不读代码的人能否据此判断"是不是我要的"；原型是否覆盖了关键状态（正常、出错、空数据）；影响界面、数据、权限的假设是否都列出来了。
 4. 写 `design-review.md`。
 
 ## 审核意见的写法

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

@@ -18,7 +18,8 @@
    | 意见编号 | 级别 | 处理结果（已修改 / 部分采纳 / 未采纳） | 说明，以及改动了哪些章节 |
    | --- | --- | --- | --- |
 
-4. 审核中提出的"需要需求方决定的问题"，原样保留在方案的"阻塞问题"或"假设"一节中，写明你暂时采用的处理方式。最终报告会把它们交给需求方。
+4. 有 `preview.md` 或 `prototype/` 时，方案改动涉及的部分同步修改，保持与 `design.md` 一致；`ui_change` 的判断变了的，在结果文件中写上新的值。
+5. 审核中提出的"需要需求方决定的问题"，原样保留在方案的"阻塞问题"或"假设"一节中，写明你暂时采用的处理方式。最终报告会把它们交给需求方。
 
 ## 完成标准
 
@@ -31,4 +32,10 @@
 { "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

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

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

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

@@ -14,7 +14,7 @@
    - 核实后如果认为某条意见不成立，不要直接跳过。写明依据（代码位置、spec 编号或实际运行结果）。
 3. "建议"级别的意见：改动小、风险低、确实更好的就处理；其余的记录为不处理并说明原因。
 4. 修复不能改变 spec 要求的行为，也不要借机做评审意见之外的改动。
-5. 全部处理完后，运行完整的测试、代码检查、类型检查和构建，确认没有引入新的失败。
+5. 全部处理完后，运行完整的测试、代码检查、类型检查和构建，确认没有引入新的失败。流水线随后也会自己运行项目配置的检查，改动之前通过、现在失败的会发回给你修复。
 6. 在 `code-review.md` 中最新一轮评审的"处理记录"小节填写下表。评审者写的内容保持原样，只追加：
 
    | 意见编号 | 级别 | 处理结果（已修复 / 不成立 / 未处理） | 提交号 | 说明 |

package/engine/prompts/09-verify.md

@@ -27,7 +27,7 @@
 - 项目没有端到端测试工具：直接操作真实入口来验证（调用接口、执行命令、有浏览器自动化工具时操作页面），并记录执行的命令和得到的输出。不要为了这次验证给项目引入新的测试框架。
 - 没有常驻服务的项目（库、脚本、命令行工具）：端到端验证是指像使用者那样，从对外的入口调用并检查结果。
 
-每个场景都要检查用户最终看到的结果，以及应当发生的数据变化确实发生了。验证过程中产生的测试数据，结束后清理掉。
+每个场景都要检查用户最终看到的结果，以及应当发生的数据变化确实发生了。功能目录中有 `preview.md`（需求方确认过的"做完后你会看到什么"）和 `prototype/`（界面原型）时，逐项对照：界面与原型不一致、或行为与预览描述不一致的，按缺陷登记；能截图的，把实际界面截图和原型放在一起作为证据。验证过程中产生的测试数据，结束后清理掉。
 
 ### 判定
 

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

@@ -16,7 +16,7 @@
    - **修复要通用。** 不要针对验证用的特定输入做特殊处理，也不要通过修改或删除验证者的测试来让它通过。
    - **核对 spec。** 修复之后的行为必须与 spec 一致。如果发现这个"缺陷"其实是测试写错了，或者 spec 本身有两种合理的理解，不要改动产品行为去迁就测试。记录你的依据，交给复验和报告处理。
 3. "轻微"级别的缺陷：改动小、风险低的就一并修复；其余的记录为未处理。
-4. 全部处理完后，运行完整的测试、代码检查、类型检查和构建，确认修复没有破坏其他功能。
+4. 全部处理完后，运行完整的测试、代码检查、类型检查和构建，确认修复没有破坏其他功能。流水线随后也会自己运行项目配置的检查，改动之前通过、现在失败的会发回给你修复。
 5. 在 `verification.md` 末尾追加"## 缺陷处理记录（第 N 轮）"一节，填写下表。验证者写的内容保持原样，只追加：
 
    | 缺陷编号 | 严重程度 | 处理结果（已修复 / 不是缺陷 / 无法复现 / 未修复） | 原因 | 修复方式 | 提交号 |

package/engine/prompts/11-report.md

@@ -16,6 +16,8 @@
    - **已完成，有遗留问题**：功能已经实现并且主流程可用，但有 AC 不通过或无法验证，或有尚未解决的问题。
    - **未完成**：没有进入实现（例如方案审核阻塞），或者实现没有做完，或者主流程不可用。
 
+   流水线质量门中"要求修复后仍失败"的检查（见 `<pipeline-context>`），视同未解决的问题：结论最高为"已完成，有遗留问题"，并在遗留问题中说明是哪个检查、对使用者意味着什么。
+
    AC 的最终结论以 `verification.md` 中最后一轮"复验结果"为准；没有复验时以功能验证的结果为准；没有做过验证的 AC 一律按"未验证"处理，不能算作通过。
 3. 花一点时间核对最关键的事实：功能分支是否存在、最近的提交是否与记录一致。如果发现记录之间互相矛盾，采用更保守的那个说法，并在报告里指出。
 4. 写 `report.md`。
@@ -55,11 +57,28 @@
 
 10. 功能分支名、基线提交和最终提交
 11. 改动文件概览
-12. 测试情况：数量、通过率、新增的测试
+12. 测试情况：数量、通过率、新增的测试；流水线质量门的结果（照抄 `<pipeline-context>` 中"质量门"几行的结论：基线、每次运行是否通过、要求修复后仍失败的检查）；范围检查的结论（方案之外改动了哪些文件、评审的判断）
 13. 未处理的评审意见和缺陷的编号清单；`decisions.tsv` 中 `needs_human` 为 `no` 的决定条数，以及其中的驳回意见
 14. 各产物文件的路径
 15. 用时与用量：照抄 `<pipeline-context>` 中"用时与用量"的数字，不要自行估算；没有时写"未记录"
 
+## 记录可以变成规则的问题（`lessons.tsv`）
+
+报告写完后，从 `code-review.md`（包括评审小组和"规范评审"的意见）、质量门的结果和 `verification.md` 的缺陷中，挑出**一条项目级的规则就能在以后挡住**的问题：例如"拼接 SQL 字符串""接口没有校验分页参数""测试里用了真实的当前时间"。只和这个需求本身有关的问题不算。
+
+有这样的问题时，在功能目录写 `lessons.tsv`（UTF-8，制表符分隔，第一行为表头，同一个问题只写一行）：
+
+```text
+category	finding	source	rule	layer
+```
+
+- `category`：问题的类别，两到六个字，例如"输入校验""SQL 拼接""时间处理"。先看看其他需求的 `docs/features/*/lessons.tsv` 用过哪些类别，同一类问题沿用同一个名字，这样才能看出它在反复出现
+- `finding`：一句话说明这次的问题；`source`：出处，如 `CR-3`、`缺陷 D-2`、`质量门 lint`
+- `rule`：建议的规则，一句话，例如"lint 规则 no-restricted-syntax 禁止模板字符串拼接 SQL"
+- `layer`：规则放在哪一层：`lint`、`类型`、`测试`、`项目说明`（能用前三种的，不写成项目说明）
+
+没有这样的问题就不写这个文件。它和报告一起提交。需求总览会提示在几个需求里反复出现的类别，`/req-retro` 会据此建议把它变成项目的规则。
+
 ## 只做研发时
 
 `<pipeline-context>` 中有"只做研发"一行时，流水线没有做测试验证，测试由人按 `handoff.md` 来做。这时写的是**研发报告**：

package/engine/prompts/incremental.md

@@ -7,6 +7,7 @@
 - 读 `changes.md` 的最后一节（变更内容、原因），再对照 `spec.md` 当前版本。没有 `changes.md` 时，用 `git log -p -- <功能目录>/spec.md` 查看 spec 最近的改动。
 - 方案审核提出过问题的，读 `design-review.md` 最后一轮的问题和 `alignment.md` 中对应的回答。
 - 验收发现问题的，读 `acceptance.md` 中"不通过的处理"。
+- 方案确认时需求方提出修改的（`changes.md` 最后一节的原因写着"方案确认时的修改"），方案设计按修改调整方案，并同步更新 `preview.md` 和 `prototype/`，之后会再请需求方确认一次。
 - 测试验证退回的（增量继续的原因写着"测试验证发现缺陷"），读 `changes.md` 最后的"测试验证退回"一节和 `verification.md` 最后一轮的缺陷清单。这一次只修这些缺陷：方案设计写修复计划，代码实现逐个修复并补测试，最后重新写 `handoff.md`（追加"第 N 次提测"一节，说明修了哪些缺陷）。
 
 各步骤的做法：

package/engine/prompts/joint.md

@@ -0,0 +1,55 @@
+# 联合需求：一个需求，几个仓库
+
+这个需求同时要改几个仓库（例如前端和后端），见 `<pipeline-context>` 中"联合需求"几行。发起需求的仓库是**主仓库**：需求说明、方案、接口约定、提测说明和报告都在它的功能目录里。其他仓库各有一个为这个需求新建的工作区，分支同名；它们的功能目录中是从主仓库同步过来的需求说明、方案和接口约定，以及在那里进行的实现和评审记录。
+
+## 所有步骤
+
+- **接口约定**（主仓库功能目录的 `contract.md`）是各仓库之间唯一的约定：接口路径、请求和响应的字段、错误码、示例。方案审核通过后它就冻结了，各仓库按它同时开发、互不等待。实现中发现它有错或不够用时，不要各自改成不同的样子：在你的产物里写明问题和建议的修改，交给评审和报告，由人决定。
+- 每个仓库只改它自己的代码，只在它自己的工作区提交。不要修改其他仓库的文件，也不要去别的仓库提交。需要了解另一边的现状时，读它工作区中的代码（只读）。
+- 只做本地提交，不 push，不合并。各仓库的合并顺序（通常先合提供接口的一边）写在提测说明和报告里，由人来合并。
+
+## 方案设计（design）
+
+在主仓库中设计整个需求：
+
+1. 读所有仓库的相关代码（各仓库工作区的路径见 `<pipeline-context>`）。
+2. 写 `contract.md`：每个接口一节，写路径和方法、请求字段（类型、是否必填、取值范围）、响应字段、错误码和对应的提示、一两组真实的请求和响应示例。示例要能直接用作测试数据：提供接口的一边用它写接口测试，调用的一边用它做测试替身（mock）。
+3. `design.md` 的方案和实施计划**按仓库分开**写：每个仓库一节，写它要改的文件、任务、测试，以及参照的已有文件。写明哪些验收标准由哪个仓库负责，哪些需要几个仓库一起才能验证（端到端）。
+4. 结果文件的 `files` 只写主仓库中的文件；其他仓库的改动范围写在 `design.md` 对应的一节。
+
+## 方案审核（design_review）
+
+额外检查 `contract.md`：字段和错误码是否完整、两边的理解会不会不同、示例是否覆盖了正常和出错的情况；各仓库的计划是否都只依赖接口约定，而不依赖对方未写明的实现细节。
+
+## 代码实现（implement）
+
+你在哪个仓库，见 `<pipeline-context>`。只实现方案中**这个仓库**的那一节，严格按 `contract.md` 来：
+
+- 提供接口的一边：为约定中的每个接口写接口测试，请求和响应用约定中的示例。
+- 调用接口的一边：用约定中的示例做测试替身，不要等另一边写完，也不要去调用另一边正在开发的代码。
+
+## 代码评审（code_review）
+
+评审的是**这个仓库**的改动。额外核对：实现与 `contract.md` 是否完全一致（路径、字段名、类型、错误码、提示文字）；有没有依赖约定之外的东西。
+
+## 提测说明（handoff）
+
+`handoff.md` 写在主仓库，覆盖所有仓库：每个仓库的工作区、分支和提交范围、各自改了什么；合并顺序；怎么把几个仓库一起跑起来（各自的启动方式、调用的一边怎么指向提供接口的一边的地址）。分阶段提测时写明几个仓库都要部署到测试环境。
+
+## 功能验证（verify）
+
+几个仓库一起验证：`<pipeline-context>` 中有各仓库由 Paseo 启动的服务和地址；调用的一边需要指向提供接口的一边时，按各自的验证方法配置（例如环境变量），配置方法写进 `verification.md`。按端到端的验收标准从用户入口走一遍，并核对接口的实际请求和响应与 `contract.md` 一致。
+
+每个缺陷写明属于哪个仓库。结果文件中加上 `defect_repos`：有缺陷的仓库名称，主仓库写 `"本仓库"`，例如 `{ "result": "defects_found", "defect_repos": ["后端"] }`。判断不了的，几个都写上。
+
+## 复验（reverify）
+
+各仓库的缺陷处理记录在各自功能目录的 `verification.md` 中（主仓库的在这里，其他仓库的在它们的工作区），都要读。其余与功能验证相同：仍有缺陷时，结果文件中的 `defect_repos` 写明这些缺陷所在的仓库。
+
+## 缺陷修复（defect_fix）
+
+你在哪个仓库，见 `<pipeline-context>`。缺陷登记在主仓库的 `verification.md` 中（`<pipeline-context>` 中"联合需求的主仓库"一行给出了它的位置），只修其中属于这个仓库的。处理记录写在**这个仓库**功能目录的 `verification.md` 末尾（"## 缺陷处理记录（第 N 轮）"，没有这个文件就新建），和代码一起提交在这个仓库；不要修改主仓库的文件。修复要符合 `contract.md`；缺陷其实是约定本身的问题时，不要改约定，写明情况交给复验和报告。
+
+## 完成报告（report）
+
+报告在主仓库，覆盖所有仓库。附录中按仓库列出工作区、分支、改动前后的提交、改动的文件和质量门的结果，并写明合并顺序。某个仓库没有完成的，结论最高为"已完成，有遗留问题"，并说明对使用者意味着什么。

package/engine/prompts/related-repos.md

@@ -0,0 +1,7 @@
+# 关联仓库（只读参考）
+
+`<pipeline-context>` 中的"关联仓库"是与本项目相关的其他代码库（例如前端项目对应的后端），由项目维护者登记，供你**阅读参考**：
+
+- 需要了解对方的接口、数据格式、错误码、调用方式时，去读它的代码和文档，不要猜。在产物里引用时写明仓库名和文件路径，以及上下文中给出的分支和提交（对方的代码会变）。
+- **只读**：不修改、不提交、不切换它的分支，不在其中安装依赖或运行会改动文件的命令。发现对方的问题，或需要对方配合的改动，写进你的产物（假设、风险或遗留问题），交给人协调。
+- 验证需要对方的服务运行时：优先使用已部署的测试环境（如有说明）；需要在本地启动对方的服务时，按它自己的说明启动、只用测试数据，用完关掉，不改它的任何文件。启动不了的，把相关验证记为"无法验证"并写明原因。