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

package/CHANGELOG.md

@@ -2,6 +2,100 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 1.8.0
+
+第一个正式版。汇总 1.8.0-beta.1 到 beta.3 的全部内容（各节见下），并让新机器一条命令就能从零用起来。
+
+### 使用者会看到的变化
+
+- **一键安装改用站点地址**：
+  - macOS、Linux、Git Bash、WSL：`curl -fsSL https://paseo-req-kit.vercel.app/install.sh | sh`
+  - Windows PowerShell：`irm https://paseo-req-kit.vercel.app/install.ps1 | iex`
+  - 原来的 GitHub 地址仍然可用。
+- **一键安装会准备好 Paseo**：
+  - 新机器上没有 Paseo 时，脚本先安装与这个版本匹配的 Paseo 命令行（`@getpaseo/cli@~0.11.0`），开启它自带的网页界面，再启动 daemon。装完在浏览器打开 `http://localhost:6767/` 就能用 Paseo 对话，不必另装桌面版。
+  - 已有 `paseo` 命令时不重装：核对版本（不在支持范围内时提醒），开启网页界面；daemon 没在运行就启动。daemon 已在运行而网页界面是刚开启的，只提示 `paseo daemon restart`，不自动重启，因为重启会中断正在运行的 agent。
+  - 只有桌面版 Paseo 管理的 daemon（没有 `paseo` 命令）时什么都不装，只提示在桌面版中开启网页界面。
+  - 一个 agent 命令行（Claude Code、Codex、OpenCode、Pi、Copilot）都没有时会提醒。
+  - 不想让脚本动 Paseo 时加 `--skip-paseo`（PowerShell：`$ReqKitSkipPaseo = $true`）。
+- **1.8 的内容**：
+  - 按需求类型分流（缺陷先复现、重构先锁行为、评估只出报告）。
+  - 质量门、按切片实现、范围检查、关联仓库。
+  - 带例子的验收标准、开工前确认方案、评审分规格和规范两个方向、反复出现的问题变成规则。
+  - 前后端联合需求。
+
+### 升级须知
+
+- 这是 npm 上的第一个 `latest` 版本：`npm i -g paseo-req-kit` 和不带 `--beta` 的一键安装从此装正式版。在 beta 通道的（`req upgrade --beta` 或 `@beta`）照常收到之后的 beta 版；没有更新的 beta 时，一键安装的 `--beta` 装正式版，而不是更早的 1.8.0-beta.3。
+- 从 1.7.x 或更早升级：依次看下面 1.8.0-beta.1 到 beta.3 的升级须知。最重要的是在每个项目主目录的对话中再运行一次 `/req-setup`，写入检查命令、术语表和范例文件。
+- 从 1.8.0-beta.3 升级：引擎和提示词没有变化，只改了安装脚本和文档。
+
+## 1.8.0-beta.3
+
+联合需求：前端和后端分在两个仓库的需求，可以作为一个需求一起做。
+
+### 使用者会看到的变化
+
+- **联合需求**：另一个仓库已经登记为关联仓库（`relatedRepos`）时，`/req` 会问两边都要改的需求是否一起做。需求说明头部写 `- 联合开发：后端`（最多再加两个仓库）。
+  - 流水线为后端新建一个工作区（分支同名），后端那份检出本身不动。
+  - 在发起需求的仓库（主仓库）设计整体方案，并写出双方的**接口约定** `contract.md`（字段、错误码、示例），方案审核一起审，通过后冻结。
+  - 需求说明、方案和接口约定同步到后端的工作区并提交；两边**同时**实现、评审、修复，各用各的检查命令和项目说明。子 agent 列表中显示为"5-代码实现（后端）"。
+  - 提测说明、功能验证和报告在主仓库：两边的服务都由 Paseo 启动，每个缺陷发回它所在的仓库修复，再一起复验。报告写明每个仓库的分支和合并顺序，合并仍然由人来做。
+  - 进度查询显示每个仓库的工作区和各自的步骤。
+
+### 升级须知
+
+- 新的 spec 头部行 `- 联合开发：`（`relatedRepos` 中的名称）。关联仓库最好也运行过 `/req-setup`：它自己的 `checks`、验证方法和项目说明会用在它的步骤里。
+- 状态文件新增可选字段 `joint`，验证和复验的结果文件新增可选字段 `defect_repos`，格式版本仍为 1。回滚到更早的版本后，旧引擎只在主仓库继续，其他仓库工作区中的改动保持原样。
+- 自定义了 `prompts.local/` 的：新增 `joint.md`。
+- 联合需求的用量大约按仓库数增加；几个仓库的步骤同时运行，本机同时运行的 agent 也更多。设计决定见 ADR 0025。
+- 维护者：`main` 收到版本号还没有标签的 `package.json` 时，发布工作流会自动打上同名标签并发布，不必再手工打标签（手工打照样可以）。
+
+## 1.8.0-beta.2
+
+让"做成什么样"的分歧更早暴露：验收标准带例子、开工前确认方案、评审分两个方向、反复出现的问题变成规则。
+
+### 使用者会看到的变化
+
+- **验收标准带例子**：AI 写验收标准时给每条配上具体的数据（输入什么、看到什么；按规则计算的给出边界上的几组），确认前的独立审阅会检查这一点。这些例子直接成为测试的期望值：你确认的，就是测试会检查的东西。
+- **开工前确认方案**（标准档的界面改动）：方案审核通过、写代码之前，流水线停下来发来"请确认方案"：AI 讲 `preview.md` 的要点（做完后会看到什么、需要你确认的假设、不会变的地方），界面改动还有静态的原型页面（`prototype/`）。说"可以"就开工；想改就直接说，更新需求说明后方案会调整，再请你看一次。功能验证会对照确认过的原型。终端里新增 `req approve <需求>`。
+- **代码评审分两个方向**：标准档第一轮由规格评审（每条验收标准是否实现、测试是否用了验收标准的例子、有没有做需求之外的事）和规范评审（项目惯例、范例文件、术语、测试质量、安全）同时进行，再汇总成一份结论。
+- **验收测试先提交**：适合测试先行时，从例子写出的测试先单独提交；之后被改过的，代码评审前由流水线列出，评审逐个确认有没有依据。
+- **术语表和范例文件**：`/req-setup` 整理 `GLOSSARY.md`（业务词、含义、代码中的名字）并列出各类代码的范例文件；方案的每个任务写明照哪个文件的写法来。
+- **反复出现的问题变成规则**：完成报告把一条项目规则就能挡住的问题记进 `lessons.tsv`；同一类问题在两个以上需求里出现时，需求总览（`req digest`）会提示，`/req-retro` 会建议把它变成 lint 规则、测试或项目说明里的一行。
+
+### 升级须知
+
+- 新配置（都有默认值）：`designApproval`（`mode` 默认 `ui`、`profiles` 标准档、`autoContinueHours` 0）、`reviewAxes`（默认标准档开启）。不想要开工前的确认，设 `"designApproval": { "mode": "off" }`；不想多两次评审，设 `"reviewAxes": { "enabled": false }`。
+- 新状态 `waiting_for_approval`（等待需求方确认方案）和启动参数 `--approve`。等待确认时单独的 `--resume` 会被拒绝。状态文件新增可选字段 `approval`，格式版本仍为 1；回滚到更早的版本后，旧引擎会不经确认直接继续写代码。
+- 结果文件新增可选字段：方案设计和修订的 `ui_change`，代码实现的 `acceptance_tests`、`acceptance_tests_commit`。外部通知新增事件 `approval`（`notifiers/im-template.mjs` 已加上它的标题）；只订阅了部分事件的不受影响。
+- 自定义了 `prompts.local/` 的：新增 `review-axis-spec.md`、`review-axis-standards.md`；`00-shared-context.md`、`02-spec-review.md`、`03-design.md`、`04-design-review.md`、`04b-design-revise.md`、`05-implement.md`、`06-code-review.md`、`09-verify.md`、`11-report.md`、`incremental.md` 有增补，覆盖过它们的请对照合并。
+- 在项目主目录再运行一次 `/req-setup`，生成术语表和范例文件清单。`/req-doctor` 会提醒没有 `GLOSSARY.md` 的项目。设计决定见 ADR 0024。
+
+## 1.8.0-beta.1
+
+研发流程按需求类型分流，代码检查由流水线自己把关，大需求按切片实现。
+
+### 使用者会看到的变化
+
+- **需求类型**：`/req` 复述需求时会确认它是哪一类，流水线按类型走不同的做法：
+  - **缺陷**：先复现、找到根因再修。第一步改为"复现与定位"，先提交一个修复前失败的复现测试，写 `diagnosis.md`；复现不了就暂停，把需要你补充的信息发回对话。修复要让复现转绿，评审会实际确认。
+  - **重构**：先用测试锁住现有行为，再小步改动；评审首先看行为有没有变。
+  - **评估**：只调研、写评估报告（`assessment.md`），由另一个模型审阅，不写代码、不做验证；报告附需求草稿，可以接着说"按评估结果提一个新需求"。
+- **质量门**：项目配置了检查命令时，流水线在写代码和修复的步骤之后**自己运行** lint、类型检查、测试、构建。改动前通过、现在失败的，发回那一步的 agent 修复（最多 2 次）；仍然失败的交给代码评审和报告，报告结论最高为"有遗留问题"。进度查询会显示质量门的结果。
+- **按切片实现**：标准档的方案分成几个能单独验证的切片时，代码实现逐片进行，每片一个新的 agent、各自提交和检查；子 agent 列表中显示为"5-代码实现 第2/3片"，中断后只重做当前片。
+- **范围检查**：代码评审前比对方案列出的文件和实际改动的文件，清单之外的改动由评审逐一说明理由；评审新增"影响面"一节，只把影响正确性、安全、数据和验收的问题提为必须修改，避免越改越复杂。
+- **多模块与关联仓库**：检查可以只在对应模块有改动时运行；其他仓库（例如前端项目的后端）可以登记为关联仓库，各步骤只读参考，不用猜接口。
+
+### 升级须知
+
+- 在项目主目录的对话中再运行一次 `/req-setup`：它会把实际跑通的检查命令写进 `.requirement-pipeline.json` 的 `checks`，并询问关联仓库。不运行也能用，只是没有质量门，`/req-doctor` 会提醒。
+- 新配置（都有默认值）：`checks`、`qualityGate`（`fixAttempts` 2、`timeoutMinutes` 20）、`slices`（`profiles` 标准档、`max` 6）、`requirementTypes`（缺陷、重构、评估）、`relatedRepos`。spec 头部的 `- 类型：` 由引擎读取（之前只给人看）：已有 spec 中写着"缺陷"的，继续时会按缺陷的做法进行。
+- 结果文件新增可选字段：方案设计的 `slices`、`files`、`reproduced`、`questions`，方案修订的 `slices`、`files`。状态文件新增可选字段 `type`、`codeBase`、`gate`，格式版本仍为 1。回滚到 1.7 后旧引擎忽略它们；按切片实现中断的需求，旧引擎会把实现整个重做一遍。
+- 自定义了 `prompts.local/` 的：新增 `types/defect.md`、`types/refactor.md`、`types/assessment.md`、`related-repos.md`；`00-shared-context.md`、`03-design.md`、`04-design-review.md`、`04b-design-revise.md`、`05-implement.md`、`06-code-review.md`、`07-review-fix.md`、`10-defect-fix.md`、`11-report.md` 有增补，覆盖过它们的请对照合并。
+- 有质量门的项目，每次尝试开始时多一次检查运行，写代码的步骤之后各多一次；检查要能在几分钟内跑完。
+- 评估：新增用例 `text-utils-rounding-defect`（缺陷类型，检查先复现再修）。设计决定见 ADR 0023。
+
 ## 1.7.0-beta.3
 
 一键安装、产品站点，以及 `paseo.json` 跨系统。

package/README.md

@@ -18,8 +18,9 @@
 </p>
 
 <p align="center">
-  <a href="https://yiyisf.github.io/paseo-req-kit/">文档站点</a> ·
-  <a href="https://yiyisf.github.io/paseo-req-kit/guide/getting-started">快速开始</a> ·
+  <a href="https://paseo-req-kit.vercel.app/">文档站点 (Vercel)</a> ·
+  <a href="https://yiyisf.github.io/paseo-req-kit/">GitHub Pages 镜像</a> ·
+  <a href="https://paseo-req-kit.vercel.app/guide/getting-started">快速开始</a> ·
   <a href="docs/guide/使用者指南.md">使用者指南</a> ·
   <a href="CHANGELOG.md">更新记录</a>
 </p>
@@ -41,8 +42,12 @@ AI  ▸ 结论：已完成，可以验收。6 条验收标准全部通过……
 ## 特性
 
 - **对话对齐需求**：一次一个问题，给出选项和推荐；确认前由另一个模型独立审阅需求说明，减少返工。
-- **后台 agent 流水线**：方案设计 → 方案审核 ⇄ 修订 → 代码实现（适合时 TDD）→ 代码评审 ⇄ 修复 → 提测说明 → 服务启动 → 功能验证 → 缺陷修复 ⇄ 复验 → 完成报告。
-- **做事的和检查的分开**：builder 与 reviewer 可用不同模型；可选的评审小组并行评审、方案提案并行比较。
+- **后台 agent 流水线**：方案设计 → 方案审核 ⇄ 修订 → 代码实现（适合时 TDD，大需求按切片逐片实现）→ 代码评审 ⇄ 修复 → 提测说明 → 服务启动 → 功能验证 → 缺陷修复 ⇄ 复验 → 完成报告。
+- **按需求类型走不同的做法**：缺陷先复现、找到根因再修；重构先用测试锁住行为再小步改；评估只调研、写评估报告，不写代码。
+- **让分歧更早暴露**：验收标准带具体例子，测试直接用它们作为期望值；界面改动在写代码之前请你确认预览和原型；代码评审分规格、规范两个方向；反复出现的问题记下来，提示变成项目的规则。
+- **质量门**：流水线自己运行项目的 lint、类型检查、测试、构建，只拦改动前通过、现在失败的检查，发回那一步的 agent 修复；代码评审前比对方案列出的文件，清单之外的改动要说明理由。
+- **联合需求**：前后端分在两个仓库的需求可以一起做：先定接口约定，再在每个仓库各开一个工作区同时开发，最后一起验证。
+- **做事的和检查的分开**：builder 与 reviewer 可用不同模型；可选的评审小组并行评审、方案提案并行比较；其他仓库（例如后端）可以登记为只读参考。
 - **如实报告**：每一步的结论只看结果文件和证据；没验证的写"未验证"，遗留问题写进报告。
 - **分阶段提测**：研发完成写好提测说明，可以停下来交给测试同事，在已部署的测试环境中验证；缺陷可退回研发。
 - **用好 Paseo**：复用 agent profile、`paseo.json` 服务和 worktree、定时任务、内置浏览器；几个需求并行互不干扰。
@@ -51,19 +56,19 @@ AI  ▸ 结论：已完成，可以验收。6 条验收标准全部通过……
 
 ## 快速开始
 
-在运行 Paseo daemon 的机器上（需要 Node.js 22+）：
+在要运行 Paseo 的机器上（需要 Node.js 22+；还没有 Paseo 也可以，脚本会装好）：
 
 ```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
 ```
 
-安装脚本会检查环境、安装 `paseo-req-kit`、为 Claude Code / Codex / OpenCode / Pi 安装 `/req` 等 skill，并引导你为 builder 和 reviewer 选择 agent。再次运行即升级。然后：
+安装脚本会检查环境、安装 `paseo-req-kit`；没有 Paseo 时安装 Paseo 命令行，开启它自带的网页界面（`http://localhost:6767/`）并启动 daemon；为 Claude Code / Codex / OpenCode / Pi 安装 `/req` 等 skill，并引导你为 builder 和 reviewer 选择 agent。再次运行即升级。然后：
 
 1. `req doctor` —— 检查 daemon、agent 模式和额度；
 2. 在项目的 Paseo 对话中运行 `/req-setup` —— 接入项目（每个项目一次）；
@@ -88,7 +93,7 @@ Paseo 对话（/req）                              流水线引擎（后台进
 - 每一步写一个 JSON 结果文件，流水线据此决定下一步，不解析 agent 的回复文字。
 - 运行状态在 `.pipeline/state.json`，可以随时查看进度、暂停、继续。
 
-详见 [工作原理](https://yiyisf.github.io/paseo-req-kit/guide/how-it-works)。
+详见 [工作原理](https://paseo-req-kit.vercel.app/guide/how-it-works)。
 
 ## 文档
 
@@ -99,7 +104,7 @@ Paseo 对话（/req）                              流水线引擎（后台进
 | 项目维护者 | [项目定制与运行规则](docs/guide/项目定制与运行规则.md) |
 | 体系维护者 | [维护者指南](docs/guide/维护者指南.md) · [设计决定](docs/adr/) · [文件约定](contracts/) · [范围](SCOPE.md) · [评估](evals/README.md) |
 
-这些文档也发布在 [文档站点](https://yiyisf.github.io/paseo-req-kit/)，附有命令和配置参考。
+这些文档也发布在 [文档站点 (Vercel)](https://paseo-req-kit.vercel.app/)（附 [GitHub Pages 镜像](https://yiyisf.github.io/paseo-req-kit/)），附有命令和配置参考。
 
 ## 项目结构
 

package/bin/req.mjs

@@ -21,6 +21,7 @@ const HELP = `req-kit ${version}（${kitRoot}）
   req status [需求]            查看进度；只有一个需求运行过时可以不写
   req stop <需求>              停止流水线（之后可以继续）
   req resume <需求>            从上次中断处继续；需求改过时只处理变化的部分
+  req approve <需求>           需求方确认了方案（方案确认点，见 preview.md），继续开发
   req verify <需求> [--verify-env local|deployed] [--defects fix|handback|report]
                                研发完成后开始测试验证（分阶段执行时）
   req start <需求> [--profile quick|standard] [--phases gated] [--at 22:00]
@@ -126,6 +127,9 @@ switch (command) {
   case "verify":
     code = node([launcher, "--phase", "verify", ...feature(rest, true)]);
     break;
+  case "approve":
+    code = node([launcher, "--approve", ...feature(rest, true)]);
+    break;
   case "start":
     code = node([launcher, ...feature(rest, true)]);
     break;

package/config.example.json

@@ -47,7 +47,8 @@
     "report": 30,
     "panel_review": 45,
     "spec_review": 20,
-    "design_proposal": 45
+    "design_proposal": 45,
+    "handoff": 30
   },
   "waitChunkSeconds": 600,
   "permissionPollSeconds": 30,
@@ -97,5 +98,35 @@
       "defects": "fix",
       "serviceStart": null
     }
+  },
+  "requirementTypes": [
+    "defect",
+    "refactor",
+    "assessment"
+  ],
+  "checks": [],
+  "qualityGate": {
+    "fixAttempts": 2,
+    "timeoutMinutes": 20
+  },
+  "slices": {
+    "profiles": [
+      "standard"
+    ],
+    "max": 6
+  },
+  "relatedRepos": [],
+  "designApproval": {
+    "mode": "ui",
+    "profiles": [
+      "standard"
+    ],
+    "autoContinueHours": 0
+  },
+  "reviewAxes": {
+    "enabled": true,
+    "profiles": [
+      "standard"
+    ]
   }
 }

package/contracts/feature-files.md

@@ -59,6 +59,36 @@ spec.md 头部的"版本"与最新一节一致。
 
 1.7.0 起，测试验证按 `defects: handback` 把缺陷退回研发阶段时，流水线在 `changes.md` 末尾追加一节"<日期> 测试验证退回（第 N 次）"，来源为"测试验证"，缺陷清单在 `verification.md` 最后一轮。研发阶段随后从方案设计开始只处理这些缺陷。
 
+## preview.md 与 prototype/（给需求方确认的预览）
+
+1.8.0 起，方案确认点开启时（`designApproval`，默认标准档的界面改动）由方案设计写入，方案修订时同步更新。`preview.md` 五节：做完后你会看到什么（按操作顺序，注明 AC）、界面原型（列出 `prototype/` 中的文件和对应的状态）、接口示例（改接口时）、需要你确认的假设（影响界面、数据、权限的）、不会变的。`prototype/` 中是静态 HTML 页面，只用内联的 HTML 和 CSS，不引用外部文件、不连接服务，只用于确认，不是产品代码。需求方确认后，实现和功能验证都以它们为准。
+
+## diagnosis.md、assessment.md
+
+1.8.0 起。缺陷类型的"复现与定位"写 `diagnosis.md`：现象与复现（复现测试或脚本的位置、命令、修复前的失败输出）、根因（带代码位置）、排除的其他原因、影响面、修复思路。评估类型的"调研评估"写 `assessment.md`（代替 `design.md`）：结论摘要、现状、可选方案（含工作量的大小和主要工作项）、推荐、风险与未知、如果要做（需求草稿）。
+
+## contract.md（联合需求的接口约定）
+
+1.8.0 起，联合需求（spec 的 `- 联合开发：`）的方案设计在主仓库写入：每个接口一节，路径和方法、请求字段（类型、是否必填、取值范围）、响应字段、错误码和提示、一两组真实的请求和响应示例。方案审核通过后冻结，各仓库按它同时开发：提供接口的一边用示例写接口测试，调用的一边用示例做测试替身。主仓库的需求说明、访谈记录、方案、接口约定和预览在实现前同步到其他仓库工作区的同名功能目录并提交；其他仓库的实现、评审和缺陷处理记录写在它们自己的功能目录中。
+
+## lessons.tsv（可以变成规则的问题）
+
+1.8.0 起，完成报告从评审意见、质量门和缺陷中挑出一条项目规则就能挡住的问题写入，没有就不写。制表符分隔，UTF-8，第一行为表头：
+
+```text
+category	finding	source	rule	layer
+```
+
+| 列 | 内容 |
+| --- | --- |
+| `category` | 问题的类别，两到六个字，如"SQL 拼接"。同类问题在各个需求中沿用同一个名字 |
+| `finding` | 这次的问题，一句话 |
+| `source` | 出处，如 `CR-3`、`缺陷 D-2`、`质量门 lint` |
+| `rule` | 建议的规则，一句话 |
+| `layer` | `lint` / `类型` / `测试` / `项目说明` |
+
+`req digest` 把在两个以上需求中出现的类别列为"反复出现的问题"。已经变成规则（或决定不做）的类别写在仓库的 `.requirement-pipeline/lessons-handled.txt` 中，一行一个，`#` 之后是注释，总览不再提示它们。
+
 ## acceptance.md
 
 验收记录，由 `/req` 的"验收"手册写。验收标准本身只在 spec.md 中维护，这里只记录结果：

package/contracts/notifier-event.md

@@ -33,7 +33,7 @@ export default async function notify(event, options) { /* 发送 */ }
 - 每个事件调用一次，可以返回 Promise。超过 15 秒没有完成按失败处理。
 - 抛出的错误和超时只记入流水线日志（"外部通知失败……不影响流水线"），不会让流水线停下或重试。
 - 模块在一次流水线运行中只加载一次；修改模块后，对之后启动或继续的流水线生效。
-- 测试：`req notify-test [--type blocked|failed|completed|milestone|permission|phase_done|digest]` 发一条带"【测试】"字样的示例事件，不需要运行流水线。
+- 测试：`req notify-test [--type blocked|failed|completed|milestone|permission|phase_done|approval|digest]` 发一条带"【测试】"字样的示例事件，不需要运行流水线。
 
 ## 事件格式（schema 1）
 
@@ -62,8 +62,9 @@ export default async function notify(event, options) { /* 发送 */ }
 | `permission` | 步骤 agent 在等待权限批准 | `stepTitle`、`agentTitle`、`requests`（字符串数组） |
 | `failed` | 流水线因错误中断（已自动重试过的临时错误除外） | `stepTitle`、`reason`、`logPath`、`resumeCommand` |
 | `completed` | 流水线结束，报告已生成 | `outcome`（`completed`、`completed_with_issues`、`not_completed`）、`summary`、`reportPath`。"只做研发"时另有 `mode`（`develop-only`）和 `handoffPath`，报告是研发报告，需要人工测试 |
+| `approval` | 1.8.0 起。方案确认点（`designApproval`）：方案已通过审核，等待需求方确认"做完后会看到什么"，还没有开始写代码 | `previewPath`（要确认的内容）、`approveCommand`（确认后继续的命令）、`resumeCommand`（修改需求后继续的命令），都在发起的对话中执行 |
 | `phase_done` | 1.7.0 起。分阶段执行时研发阶段已完成（代码已通过评审、提测说明已写好），流水线停在闸口等待测试验证。测试退回后再次修完也会发 | `handoffPath`（提测说明）、`mode`（`gated`）、`verifyCommand`（开始测试验证的命令，在发起的对话中执行）、`verifyAt`（预约的开始时间，ISO 格式，没有为 null）、`handbacks`（已退回的次数） |
-| `digest` | `req digest --notify`（或由 `req digest --schedule` 创建的 Paseo 定时任务）发送项目的需求总览，1.6.0 起。`feature.title` 为"<项目> 需求总览"，`text` 是完整的多行总览 | `features`：每个需求的 `name`、`title`、`stage`、`branch`、`updatedAt`、`usage` |
+| `digest` | `req digest --notify`（或由 `req digest --schedule` 创建的 Paseo 定时任务）发送项目的需求总览，1.6.0 起。`feature.title` 为"<项目> 需求总览"，`text` 是完整的多行总览 | `features`：每个需求的 `name`、`title`、`stage`、`branch`、`updatedAt`、`usage`；`recurringLessons`（1.8.0 起）：在两个以上需求的 `lessons.tsv` 中出现的问题类别，每项 `category`、`features`、`rules` |
 
 ## 兼容性
 

package/contracts/result-file.md

@@ -4,14 +4,18 @@
 
 | 步骤 ID | 字段 |
 | --- | --- |
-| `design` | `has_runnable_service`: boolean |
+| `design` | `has_runnable_service`: boolean。可选（1.8 起）：`slices`: 字符串数组（实施计划的切片，按实现顺序；两片以上时按片逐个实现）；`files`: 字符串数组（预计改动的文件和目录，目录以 `/` 结尾，可用 `*`，用于范围检查）；缺陷类型的 `reproduced`: boolean，为 `false` 时 `questions`: 非空字符串数组（需要需求方补充的信息）；`ui_change`: boolean（改动是否改变使用者看到的界面或操作方式，方案确认点按它决定是否停下） |
 | `design_review` | `verdict`: `approved` \| `changes_required` \| `blocked`；为 `blocked` 时 `questions`: 非空字符串数组 |
-| `design_revise`、`implement`、`review_fix`、`defect_fix` | `status`: `done` \| `partial` |
+| `design_revise` | `status`: `done` \| `partial`。可选（1.8 起）：`slices`、`files`、`ui_change`，修订改变了它们时写新的值 |
+| `implement` | `status`: `done` \| `partial`。按切片实现时，每片的键为 `implement-s<序号>`。可选（1.8 起）：`acceptance_tests`: 字符串数组（从验收标准的例子写出、先单独提交的测试文件），`acceptance_tests_commit`: string（那次提交）；代码评审前引擎核对它们之后有没有被改过 |
+| `review_fix`、`defect_fix` | `status`: `done` \| `partial` |
 | `code_review` | `verdict`: `pass` \| `changes_required` |
 | `service_start` | `started`: boolean |
-| `verify` | `result`: `pass` \| `defects_found` \| `blocked` |
-| `reverify` | `result`: `pass` \| `defects_remaining` |
+| `verify` | `result`: `pass` \| `defects_found` \| `blocked`。可选（1.8 起，联合需求）：`defect_repos`: 字符串数组，缺陷所在的仓库（`本仓库` 或 `relatedRepos` 中的名称）；没有时每个仓库都做一轮缺陷修复 |
+| `reverify` | `result`: `pass` \| `defects_remaining`。可选：`defect_repos`，同上 |
 | `report` | `outcome`: `completed` \| `completed_with_issues` \| `not_completed`；`summary`: string |
 | `panel_review`（评审小组成员，键为 `<评审步骤>-r<轮次>-p<序号>`） | `status`: `done` \| `partial`；意见写在 `<功能目录>/review-panel/<键>.md` |
 
+联合需求中，其他仓库的步骤的键带 `@<仓库后缀>`（如 `implement@backend`、`code_review-r2@backend`），结果文件写在那个仓库工作区的功能目录中。
+
 字段定义以 `engine/src/steps.ts` 为准；改动时同步更新各步骤提示词末尾的"结果文件"一节。

package/contracts/spec.md

@@ -20,13 +20,15 @@
 | `- 状态：` | 引擎 | 以"已确认"开头才能启动流水线。正则：`^\s*-\s*状态\s*[:：]\s*已确认` |
 | `- 档位：` | 引擎 | "快速"或"标准"（也接受 `quick` / `standard`）。没有时用配置中的 `defaultProfile` |
 | `- 执行方式：` | 引擎 | "连续"、"分阶段"或"只做研发"（也接受 `continuous` / `gated` / `develop-only`）。可以没有；没有时用配置中的 `phases.mode`，启动参数 `--phases` 优先（1.7 起） |
-| `- 类型：` | `/req` | 新需求 / 小改动 / 缺陷 |
+| `- 类型：` | 引擎（1.8 起）、`/req` | 新需求 / 小改动 / 缺陷 / 重构 / 评估（也接受 `defect`、`bug`、`refactor`、`assessment`；"技术改进"同重构，"调研"同评估）。缺陷、重构、评估按各自的做法运行（`engine/prompts/types/`），配置 `requirementTypes` 可以关掉某个类型；其他写法按新需求处理 |
+| `- 联合开发：` | 引擎（1.8 起） | 这个需求还要改的其他仓库，写项目配置 `relatedRepos` 中的名称，最多两个，用顿号分开。可以没有。见 ADR 0025 |
 | `- 版本：` | `/req` | 从 1 开始，每次修改需求加 1 |
 | `- 格式：` | `/req`、引擎（将来） | `req-kit/spec@<n>`。没有这一行的旧 spec 按 `req-kit/spec@1` 处理 |
 
 ## 正文中被引用的编号
 
 - 功能需求 `FR-<n>`，验收标准 `AC-<n>.<m>`，规则 `BR-<n>`，假设 `A-<n>`。
+- 每条验收标准至少带一组具体的输入和期望输出（1.8 起由 `acceptance-criteria`、需求说明审阅检查）；方案的测试直接用这些例子作为期望值。
 - 流水线各步骤和最终报告按这些编号引用，编号一旦确认就不要重排；删除的需求保留编号并注明"已取消"。
 
 ## 变更

package/contracts/state.md

@@ -9,7 +9,7 @@
 | `version` | number | 格式版本。没有这个字段的文件按 1 处理 |
 | `repo` | string | 仓库目录（绝对路径） |
 | `featureDir` | string | 功能目录（相对路径，`/` 分隔） |
-| `status` | `running` \| `waiting_for_business` \| `failed` \| `completed` \| `phase_done` | 当前状态。`waiting_for_business` 表示等待需求方决定；`phase_done`（1.7.0 起）表示研发阶段已完成、停在闸口等待测试验证。1.7 之前的引擎把 `phase_done` 当作可以继续的中断，继续时沿用研发结果、直接做验证 |
+| `status` | `running` \| `waiting_for_business` \| `failed` \| `completed` \| `phase_done` \| `waiting_for_approval` | 当前状态。`waiting_for_business` 表示等待需求方决定；`phase_done`（1.7.0 起）表示研发阶段已完成、停在闸口等待测试验证；`waiting_for_approval`（1.8.0 起）表示方案已通过审核、等待需求方确认 `preview.md`，`--approve` 继续。旧引擎把不认识的状态当作可以继续的中断：`phase_done` 继续时直接做验证，`waiting_for_approval` 继续时不经确认直接写代码 |
 | `attempt` | number | 第几次从方案设计开始 |
 | `specHash` | string | 启动时 spec.md 的 sha256 |
 | `originAgentId` | string \| null | 发起对话的 agent，通知发往这里 |
@@ -30,8 +30,13 @@
 | `phase` | `develop` \| `verify` | 可选，1.7.0 起。当前阶段。用字符串而不是编号，以后增加阶段不用改格式 |
 | `verifyAt` | string \| null | 可选，1.7.0 起。`--verify-at`：研发完成后在这个时间开始测试验证 |
 | `handbacks` | number | 可选，1.7.0 起。测试验证把缺陷退回研发阶段的次数（`defects` 为 `handback`），上限为档位的 `defectFix` 轮数 |
+| `type` | `defect` \| `refactor` \| `assessment` \| null | 可选，1.8.0 起。spec 中"类型"对应的做法；新需求、小改动和配置关掉的类型为 null |
+| `codeBase` | object \| null | 可选，1.8.0 起。`attempt`、`commit`：这次尝试在改动任何代码之前的提交，质量门的基线和范围检查从这里比较。尝试开始时就已经写过代码的旧记录为 `commit: null` |
+| `joint` | array \| null | 可选，1.8.0 起。联合需求（spec 的 `- 联合开发：`）中其他仓库的工作区：`name`（`relatedRepos` 中的名称）、`slug`（步骤键的后缀，如 `implement@backend`）、`sourceRepo`（切出工作区的那份检出）、`repo`（工作区目录）、`workspaceId`、`branch`、`specHash`（最近一次同步过去的 spec），以及这个仓库自己的 `codeBase` 和 `gate`（格式同顶层）。见 ADR 0025 |
+| `approval` | object \| null | 可选，1.8.0 起。方案确认点：`attempt`（哪一次尝试的方案）、`status`（`waiting` / `approved`）、`at`。需求变更后的新尝试需要重新确认 |
+| `gate` | object \| null | 可选，1.8.0 起。质量门：`baseline`（`attempt`、`commit`、`at`、`results`：每项检查改动前 `pass` / `fail`），`runs`（每次运行：`key` 步骤键、`attempt`、`at`、`checks`（`name`、`result`：`pass` / `fail` / `skipped`、`failedBefore`）、`newFailures`、`fixRounds`、`passed`）。各次运行的完整输出在 `.pipeline/checks/<步骤键>/` |
 
-`schedules[].kind` 在 1.7.0 起还可能是 `verify-start`（`--verify-at` 预约的测试验证开始）。`history` 中每条步骤记录在 1.7.0 起有可选的 `phase`（`develop` / `verify`），用于按阶段统计用时与用量；没有时按研发阶段统计。
+`schedules[].kind` 在 1.7.0 起还可能是 `verify-start`（`--verify-at` 预约的测试验证开始），1.8.0 起还可能是 `approval-continue`（方案确认超时后按方案继续，`designApproval.autoContinueHours`）。`history` 中每条步骤记录在 1.7.0 起有可选的 `phase`（`develop` / `verify`），用于按阶段统计用时与用量；没有时按研发阶段统计。
 
 ## 迁移
 

package/contracts/verify.md

@@ -36,4 +36,6 @@
 - `pnpm test` 中 `report.test.ts` 偶发超时，与需求无关
 ```
 
+其中几分钟内能跑完的检查（格式、lint、类型检查、单元测试、构建）同时写进项目配置 `.requirement-pipeline.json` 的 `checks`（1.8 起）：流水线会在写代码和修复的步骤之后自己运行它们，作为质量门。`verify.md` 写给 agent 看，`checks` 由流水线执行，两处的命令保持一致。
+
 步骤 agent 发现它过时或不准确时，会在 `service-start.md` 或 `verification.md` 的"建议写入 verify.md 的内容"一节给出实际可行的做法；`/req-setup` 再次运行时会参考这些建议更新本文件。

package/docs/adr/0023-types-gate-slices.md

@@ -0,0 +1,54 @@
+# 0023 需求类型、质量门、按切片实现
+
+- 状态：已采纳（补充 [0004](0004-result-files.md)：结果文件可以带计划字段；[0022](0022-develop-and-verify-phases.md)：评估类需求没有测试验证阶段）
+
+## 背景
+
+到 1.7 为止，所有需求走同一条路：方案设计 → 审核 → 一个 agent 实现全部任务 → 评审 → 验证。三个问题反复出现：
+
+1. **不同类型的需求要不同的做法。** 修缺陷要先复现、找到原因；重构要先锁住现有行为；"能不能做"的评估根本不该写代码。用新功能的做法处理它们，结果常常"做了，但不是要的"：缺陷改的是现象，重构顺手改了行为，评估做成了半成品。
+2. **"规范"只是提示词里的建议。** lint、测试、构建是否通过，靠实现 agent 自己说，评审 agent 再跑一遍；中间没有任何确定性的检查，改坏了也可能写成"通过"。
+3. **大需求一个 agent 做不完。** 上下文被填满、时限 4 小时、中断后整步重做。
+
+业界的做法（Matt Pocock 的 skills、pstack、Claude Code 和 Cursor 的最佳实践）在这几点上相同：按任务类型走不同的剧本；能用工具判定的交给确定性的检查，不靠模型自评；把工作切成可以单独验证的纵向切片。
+
+## 决定
+
+### 需求类型
+
+- spec 头部的 `- 类型：` 由引擎读取。缺陷、重构、评估三种有自己的**剧本**；新需求、小改动和其他写法走原来的流程。配置 `requirementTypes` 可以关掉某个剧本（该类型改走原来的流程）。
+- 剧本**不新增步骤**，而是改变已有步骤做什么：每种类型一个提示词文件 `engine/prompts/types/<类型>.md`，按"## 步骤名（步骤 ID）"分节，引擎把"所有步骤"一节和当前步骤的一节接在本步骤任务之后，并在 `<pipeline-context>` 中写明类型。步骤 ID、结果文件和状态都不变，续跑、增量继续、分阶段执行照常适用；`prompts.local/types/` 可以覆盖。剧本可以改步骤的显示名称（缺陷的方案设计叫"复现与定位"）。
+- **缺陷**：方案设计改为复现与定位，先提交一个修复前失败的复现测试或脚本，写 `diagnosis.md`（根因、影响面）。复现不了时结果文件写 `reproduced: false` 和要问的问题，流水线像方案审核阻塞一样暂停，把问题发回对话。修复必须让复现转绿，评审要实际确认它修复前失败。
+- **重构**：先补特征测试锁住现有行为，单独提交；之后小步改动，每步全绿；评审的首要问题是"行为有没有变"，特征测试的断言被改要说明理由。
+- **评估**：只读。调研评估写 `assessment.md` → 评估审阅 ⇄ 修订 → 评估报告；没有实现、代码评审、提测和验证，执行方式一律按连续。功能目录之外有文件被改动时，引擎把它写进报告的上下文。报告最后给出需求草稿，对话可以接着提一个新需求。
+- 类型由 `/req` 在访谈时判断并请用户确认；访谈的重点随类型变化（复现步骤、必须不变的行为、要回答的问题）。
+
+### 质量门
+
+- 项目配置 `checks` 列出流水线**自己运行**的检查（格式、lint、类型检查、单元测试、构建），由 `/req-setup` 从实际跑通的命令写入。端到端测试和需要启动服务的检查不放这里，它们属于功能验证。
+- 每次尝试开始时（方案设计之前，任何提交之前）运行全部检查，记录**基线**。放在方案设计之前，是因为缺陷的复现测试在复现与定位时就提交了，基线晚了会把整个测试检查记成"原本就失败"。
+- 代码实现（每一片）、评审问题修复、缺陷修复结束后运行与改动相关的检查。只有**改动前通过、现在失败**的检查拦下：把命令和输出的最后部分作为追问发回**同一个 agent**（它还记得自己改了什么），最多 `qualityGate.fixAttempts` 次（默认 2）。仍然失败时**照常继续**，结果写进状态文件，交给代码评审（要求按阻塞或重要提出）和报告（结论最高为"有遗留问题"）。不让一个 lint 问题卡住整个需求，也不会无声地放过。
+- 比较以"一项检查"为单位，不细到测试用例：粗，但与项目的测试框架无关。原本就失败的检查不拦，但会在报告中列出。
+- 检查通过系统 shell 运行（Windows 上是 cmd.exe），命令要写成各系统通用的形式，与 `paseo.json` 的约定相同。没有配置检查时一切照旧，报告注明"未配置"。
+
+### 多模块与关联仓库
+
+- 检查可以带 `cwd` 或 `paths`：只有改动碰到这些路径时才运行，单仓库多模块的项目只检查改动的模块。
+- 项目配置 `relatedRepos` 登记其他仓库（例如前端项目的后端）。步骤在 `<pipeline-context>` 中看到它们的位置、分支和提交，按 `related-repos.md` **只读**参考：不修改、不提交；验证需要对方服务时优先用已部署的测试环境。
+- 两边都要改的"联合需求"（父子运行、接口约定、联合验证）不在这个版本，单独设计。
+
+### 按切片实现
+
+- 方案的实施计划分成**纵向切片**（每片能单独演示和验证），设计步骤在结果文件的可选字段 `slices` 中列出；方案修订可以给出新列表。
+- 档位在 `slices.profiles` 中（默认只有标准档）、且有两片以上时，代码实现按片逐个启动新的 agent（步骤键 `implement-s<序号>`），每片各自提交、各自过一次质量门；中断后只重做当前片。超过 `slices.max`（默认 6）时最后几片合并。只有一片、快速档时与原来相同。
+- 子需求（把大需求拆成几个各有 spec 的需求）不在这个版本：切片已经解决上下文和中断的问题。
+
+### 范围检查
+
+- 设计结果的可选字段 `files` 列出预计改动的文件和目录。代码评审前，引擎比对这次尝试实际改动的文件（不含功能目录），把清单之外的交给评审逐一判断：必需的写理由，无关的要求撤回。评审同时增加"影响面"一节，并明确只把影响正确性、安全、数据和验收的问题提为阻塞或重要，避免评审意见把代码越改越复杂。
+
+## 影响
+
+- 状态文件只增加可选字段（`type`、`codeBase`、`gate`），格式版本仍为 1；结果文件增加可选字段。回滚到 1.7 后，旧引擎忽略这些字段；按切片实现中断的需求，旧引擎会把整个实现重做一遍。
+- 有检查的项目，每次尝试多一次基线运行，写代码的步骤之后各多一次检查运行。检查要能在几分钟内跑完。
+- 不同的需求类型复用同一套步骤和状态：以后增加类型（界面改动、数据变更、性能优化）只需要一个剧本文件和少量引擎分支。

package/docs/adr/0024-confirm-early-review-axes.md

@@ -0,0 +1,27 @@
+# 0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则
+
+- 状态：已采纳（补充 [0012](0012-review-panel.md)：评审的两个方向复用评审小组的机制；[0022](0022-develop-and-verify-phases.md)：方案确认点与闸口一样停下来等人，但在写代码之前）
+
+## 背景
+
+需求做出来"不符合预期"，多半不是代码写错，而是需求方和 agent 对"做成什么样"理解不同，并且直到验收才发现。到 1.8.0-beta.1 为止，需求方在确认需求说明之后，要等到报告才再看到结果；验收标准常常是抽象的描述（"在限制时间内重复发送会被拒绝"），测试的期望值由实现者自己定；代码评审一位评审者同时看"做没做对"和"做得规不规范"，后者常被挤掉；同一类规范问题在不同需求里反复被提出、反复修。
+
+Matt Pocock 的 skills（`grill-with-docs` 的术语表、`tdd` 先写测试、`code-review` 分 Standards 和 Spec 两个方向、`retro`）、pstack 的 `correct`（把纠正变成规则）和 Specification by Example 的思路一致：把分歧放到最便宜的时候暴露，用具体的例子而不是抽象的描述对齐，把反复出现的问题交给机器挡住。
+
+## 决定
+
+- **验收标准带例子**：`acceptance-criteria` 要求每条 AC 至少一组具体的输入和期望输出，按规则计算的给出覆盖边界的几组；确认前的独立审阅检查这一点，缺的替需求方拟好例子请其确认。方案的测试直接用这些例子作为期望值，不另编。
+- **验收测试先提交**：适合测试先行时，实现先把从例子写出的测试单独提交（失败的），在结果文件中写明文件和提交（`acceptance_tests`、`acceptance_tests_commit`）。代码评审前引擎用 git 核对它们之后有没有被改，改过的交给评审逐个确认依据。只核对、不阻止：测试本身写错是常见的合理修改。
+- **方案确认点**（`designApproval`）：方案审核通过、写代码之前，引擎可以停下来（状态 `waiting_for_approval`），请需求方看 `preview.md`（做完后会看到什么、需要确认的假设、不会变的）和界面原型（`prototype/` 中的静态 HTML）。`--approve` 继续；要修改的走需求变更（更新 spec 后 `--resume`，从方案设计增量处理，再确认一次）。等待单独的 `--resume` 会被拒绝，避免对话误把"继续"当作确认。
+  - 默认只对标准档的界面改动开启（`mode: "ui"`，由方案在结果文件中判断 `ui_change`）：界面最容易"做对了但不是想要的"，其他需求不增加等待。`always` 每次都停，`off` 关闭。
+  - 无人值守的代价：等待提醒复用 `waitingReminderHours`；`autoContinueHours` 大于 0 时通过 Paseo 定时任务让对话在超时后按方案继续（默认 0，一直等待）。
+  - 方案中的假设标明对使用者可见的影响（界面、数据、权限）。影响这些、猜错会做错的转为阻塞问题；其余在确认点请需求方过目，没有确认点时由报告交给需求方。
+- **代码评审分两个方向**（`reviewAxes`，默认标准档开启）：第一轮由规格评审（每条 AC 是否实现、测试期望值是否与例子一致、范围、与预览是否一致）和规范评审（项目惯例与范例文件、术语、测试质量、安全、简单性）并行，reviewer 核实汇总成一份结论。复用评审小组的并行和汇总，两位都用配置的 reviewer；配置了评审小组时以小组为准；后续轮次仍由一位评审核对修复。代价是每个标准档需求多两次评审。
+- **术语表和范例文件**：沿用仓库根目录的 `GLOSSARY.md`（不另建文件），增加"代码中的名字"；`/req-setup` 第一次整理并在项目说明中列出各类代码的范例文件；方案的每个任务写明参照的文件，新概念补进术语表。
+- **反复出现的问题变成规则**：完成报告把一条项目规则就能挡住的问题写进功能目录的 `lessons.tsv`。放在各自的功能目录，而不是一个共用文件，避免各需求分支合并时冲突。`req digest` 汇总所有工作区中的需求，同一类别出现在两个以上需求时提示；`/req-retro` 据此建议规则，落地后把类别写进 `.requirement-pipeline/lessons-handled.txt`。规则仍由人批准。
+
+## 影响
+
+- 状态文件新增可选字段 `approval` 和状态值 `waiting_for_approval`，格式版本仍为 1。回滚到更早的版本后，旧引擎把它当作可以继续的中断，继续时不经确认直接写代码，可以接受。
+- 结果文件新增可选字段（`ui_change`、`acceptance_tests`、`acceptance_tests_commit`）。外部通知新增事件 `approval`。
+- 标准档的界面改动多一次等待；每个标准档需求的第一轮代码评审多两次 agent 运行。都可以在配置中关闭。

package/docs/adr/0025-joint-requirements.md

@@ -0,0 +1,27 @@
+# 0025 联合需求：一个需求同时改几个仓库
+
+- 状态：已采纳（扩展 [0018](0018-own-worktree-option.md)：为其他仓库新建工作区；[0023](0023-types-gate-slices.md)：质量门按仓库进行；落实 1.8 设计中"多代码库需求"的第三种形态）
+
+## 背景
+
+前后端分在两个仓库的需求很常见：后端加接口，前端加页面。1.8.0-beta.1 起其他仓库可以作为只读参考，但两边都要改时只能拆成两个互不知道的需求：接口由两边各自理解，联调问题要到人工测试时才暴露，两份报告也凑不成"这个需求做完了没有"的答案。
+
+## 决定
+
+- **主仓库协调，复用单仓库的步骤**：发起需求的仓库是主仓库，它的运行就是协调者，状态只有一份（主仓库的 `state.json`）。不另起子流水线进程：同一套步骤、结果文件、续跑和用量统计都直接适用，只是某些步骤换一个仓库运行。
+- spec 头部 `- 联合开发：<名称>` 指定还要改的仓库，名称来自 `relatedRepos`，最多两个（一共三个仓库）。启动前检查名称已登记、本机存在、是 git 仓库，否则不启动、不留运行记录。
+- **工作区**：每个联合仓库由 Paseo 新建一个工作区，分支 `feature/<需求>`，从那个仓库当前检出的分支切出；那份检出本身不切换分支、不提交（同 0018 的理由）。同名分支已存在时停下来请人处理，不覆盖。
+- **步骤怎么分**：
+  - 方案设计、方案审核与修订、方案确认点、提测说明、功能验证、复验、完成报告都在主仓库。方案按仓库分开写，并写出接口约定 `contract.md`，方案审核通过后冻结。
+  - 实现、代码评审 ⇄ 修复在**每个仓库各自进行、同时进行**：步骤 agent 的工作目录和 Paseo 工作区是那个仓库的，仍挂在发起的对话下；步骤键加仓库后缀（`implement@backend`），结果文件写在那个仓库的功能目录。联合需求不按切片实现（每个仓库一个实现步骤），避免切片与仓库交错。
+  - 实现前，主仓库的需求说明、访谈记录、方案、接口约定、预览同步到各仓库的功能目录并提交，合并那个仓库的人能在代码旁边读到。
+  - 功能验证前，各仓库 `paseo.json` 中的服务都由 Paseo 用当前代码启动。验证和复验的结果用 `defect_repos` 写明缺陷在哪个仓库，缺陷修复只在那些仓库进行；没写时每个仓库都看一遍。
+- **质量门按仓库**：每个仓库用它自己项目配置中的 `checks`、自己的基线和记录（`joint[].codeBase`、`joint[].gate`）；它自己的项目说明、验证方法和按步骤的说明用在它的步骤里。
+- **失败与继续**：同时进行的步骤中一个失败时，等其他的做完再中断，不让 agent 在没人看着的情况下继续改代码；继续时沿用已建的工作区和已完成的步骤。
+- **安全边界不变**：只做本地提交，不合并、不推送；各仓库的合并顺序写进提测说明和报告，由人决定。不克隆本机没有的仓库，不自动部署。
+
+## 影响
+
+- 状态文件新增可选字段 `joint`，结果文件新增可选字段 `defect_repos`，格式版本仍为 1。回滚到旧版本后，旧引擎忽略 `joint`，只在主仓库继续，已经在其他仓库做的改动留在它们的工作区里。
+- 每个联合仓库多一次实现和一轮以上的代码评审，用量大约按仓库数增加；三个步骤同时运行时，本机同时运行的 agent 也更多。
+- 一个需求的改动分散在几个分支上，合并需要人按顺序进行。

package/docs/adr/README.md

@@ -24,3 +24,6 @@ req-kit 自身的设计决定。修改其中任何一条，请新增一条 ADR
 - [0020 调度：用 Paseo 定时任务把消息发回对话，排队在本机进行](0020-scheduling-through-the-chat.md)
 - [0021 npm 分发：全局包是版本管理器，各版本仍装在 versions/ 下](0021-npm-version-manager.md)
 - [0022 分阶段执行：研发阶段、闸口、测试验证阶段](0022-develop-and-verify-phases.md)
+- [0023 需求类型、质量门、按切片实现](0023-types-gate-slices.md)
+- [0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则](0024-confirm-early-review-axes.md)
+- [0025 联合需求：一个需求同时改几个仓库](0025-joint-requirements.md)

package/docs/guide//344/275/277/347/224/250/350/200/205/346/214/207/345/215/227.md

@@ -21,6 +21,23 @@ req-kit 帮你把一个需求从"我想要……"做到"可以验收"：你在 P
 
 小改动（改文案、样式、一个配置项）会走快速流程：只问 2–3 个问题，开发环节各做一轮。
 
+**需求的类型**：AI 复述时会和你确认这是哪一类，流水线按类型走不同的做法：
+
+| 类型 | 说法举例 | 流水线怎么做 | 你需要讲清楚的 |
+| --- | --- | --- | --- |
+| 新需求 | "加一个……" | 方案、实现、评审、验证 | 要什么、怎么算做对 |
+| 缺陷 | "……不对""报错了" | 先复现、找到原因再修；复现不了会回来问你 | 复现步骤：环境、账号或数据、操作、看到的、应有的 |
+| 重构 | "整理一下……""升级依赖" | 先用测试锁住现有行为，再小步改，确认行为没变 | 改进目标，以及哪些行为必须保持不变 |
+| 评估 | "能不能做……""影响多大" | 只调研、写评估报告，由另一个模型审阅，不写代码 | 要回答的问题，结论用来做什么决定 |
+
+评估做完后，可以直接说"按评估结果提一个新需求"。
+
+**前端和后端都要改**：另一个仓库已经由开发同事登记过（`/req-setup` 时登记）的，AI 会问是否作为联合需求一起做：流水线先设计整体方案和双方的接口约定，再在每个仓库各开一个工作区同时开发，最后一起验证，报告里写明每个仓库的分支和合并顺序。
+
+**验收标准带例子**：AI 写验收标准时会给每条配上具体的数据（"输入 13800000000，60 秒内再点发送，提示'请 45 秒后重试'"）。请认真看这些例子：它们会直接变成测试检查的期望值，你确认的就是测试会检查的东西。
+
+**开工前先看一眼"做完后会看到什么"**（标准档的界面改动）：方案审核通过后、写代码之前，流水线会停下来，AI 把 `preview.md` 的要点讲给你听：会看到什么变化、有哪些需要你确认的假设；界面改动还会有静态的原型页面（功能目录的 `prototype/` 中），可以在浏览器里打开看。说"可以"就开始写代码；想改的直接说，AI 会更新需求说明，方案调整后再请你看一次。这时调整的成本最低。
+
 **研发和测试分开做**（标准档，确定档位时 AI 会问，团队配置里定好了就不问）：
 
 - **连续**（默认）：研发完成后流水线接着做测试验证，一次跑完。
@@ -34,6 +51,7 @@ req-kit 帮你把一个需求从"我想要……"做到"可以验收"：你在 P
 | 看进度 | "做到哪了"（会说明当前在哪一步、agent 最近在做什么，例如正在运行测试） |
 | 暂停 | "先停一下"（当前步骤做到一半的工作不保留，已完成的步骤保留） |
 | 继续 | "继续开发" |
+| 确认方案 | 收到"请确认方案"时，看过之后说"可以，按这个做"，或者说要改哪里 |
 | 改需求 | "我想改一下……"：先暂停，谈清变化的部分，更新需求说明（版本加 1，记入 `changes.md`）后继续，开发会在已有方案和代码的基础上只处理变化的部分。开发已经完成的也可以改 |
 | 看看项目里有哪些需求 | "现在有哪些需求"：列出所有工作区中的需求和各自的阶段 |
 | 研发完成后提测 | "开始测试验证"（分阶段执行时）；想晚点开始就说"等测试环境部署好，明早 9 点开始测试" |