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

package/contracts/state.md

@@ -0,0 +1,49 @@
+# state.json
+
+流水线的运行状态，位于 `docs/features/<目录>/.pipeline/state.json`，只由引擎写入，不提交。
+
+## 当前格式：version 1
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `version` | number | 格式版本。没有这个字段的文件按 1 处理 |
+| `repo` | string | 仓库目录（绝对路径） |
+| `featureDir` | string | 功能目录（相对路径，`/` 分隔） |
+| `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，通知发往这里 |
+| `pid` | number | 流水线进程 |
+| `startedAt` / `updatedAt` | ISO 时间 | |
+| `results` | object | 已完成步骤的结果，键为步骤键（如 `code_review-r2`） |
+| `history` | array | 每次步骤执行的记录：agent、起止时间、结果、错误；`usage`（可选，1.3.0 起）为 agent 报告的用量：`inputTokens`、`cachedInputTokens`、`outputTokens`、`totalCostUsd`，agent 没有报告时为 null 或缺少 |
+| `stopReason` / `outcome` | string \| null | 停止原因；最终结论 |
+| `profile` | `quick` \| `standard` | 档位 |
+| `branch` | string \| null | 工作分支，启动时确定 |
+| `milestones` | string[] | 已发送的进展通知，续跑时不重复发送 |
+| `incremental` | object \| null | 可选，1.3.0 起。需求变更或回答问题后的继续：`fromAttempt`（接着哪一次）、`reason`、`baseCommit`（本次开始时的提交，评审看这之后的改动）、`hadImplementation`（上一次是否已写过代码）。第一次运行和 `--restart` 为 null |
+| `worktree` | object \| null | 可选，1.5.0 起。用 `--worktree` 启动、在为需求新建的工作区中开发时：`workspaceId`（Paseo 工作区）、`sourceRepo`（对话所在的目录）。此时 `repo` 是新工作区的目录 |
+| `schedules` | array | 可选，1.6.0 起。这次运行创建的 Paseo 定时任务：`id`、`kind`（`reminder` 提醒 / `auto-resume` 自动继续 / `watchdog` 定时检查）、`at`。下一次运行或暂停命令会取消它们 |
+| `autoResumes` | object \| null | 可选，1.6.0 起。`attempt`、`count`：这次尝试已经预约过几次自动继续 |
+| `queuedSince` | string \| null | 可选，1.6.0 起。正在排队（`maxConcurrentPipelines`）时为开始排队的时间 |
+| `phases` | object \| null | 可选，1.7.0 起。这次运行的执行方式：`mode`（`continuous` / `gated` / `develop-only`）、`environment`（`local` / `deployed`）、`defects`（`fix` / `handback` / `report`）。没有时按 `continuous`、`local`、`fix` 处理 |
+| `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` 预约的测试验证开始），1.8.0 起还可能是 `approval-continue`（方案确认超时后按方案继续，`designApproval.autoContinueHours`）。`history` 中每条步骤记录在 1.7.0 起有可选的 `phase`（`develop` / `verify`），用于按阶段统计用时与用量；没有时按研发阶段统计。
+
+## 迁移
+
+只增加可选字段（缺少时按默认值处理，旧版本引擎读到也不出错）时不提升版本，以便回滚到旧版本后仍能继续已有的流水线；在上表中注明"可选"和起始版本即可。
+
+引擎（`engine/src/state.ts`）中 `STATE_VERSION` 是当前版本，`STATE_MIGRATIONS[n]` 把第 n 版升级到第 n+1 版。增加必需字段或改变已有字段的含义时：
+
+1. `STATE_VERSION` 加 1。
+2. 在 `STATE_MIGRATIONS` 中加一个从旧版本到新版本的函数，为旧文件补上默认值。
+3. 在 `engine/test/state.test.ts` 中加一条迁移测试，更新本文件。

package/contracts/verify.md

@@ -0,0 +1,41 @@
+# .requirement-pipeline/verify.md
+
+项目的验证方法：怎么安装依赖、启动服务、运行测试、准备测试数据。由 `/req-setup` 生成，其中的命令要实际运行过。流水线把它追加到实现、评审修复、服务启动、功能验证、缺陷修复、复验这几个步骤的提示词中（"本项目的验证方法"一节）。
+
+格式自由，建议按下面的结构写，每节给出可以直接复制执行的命令：
+
+```markdown
+# 验证方法
+
+最后核对：2026-10-13（/req-setup，全部命令已运行）
+
+## 环境准备
+- Node.js 22，pnpm 9
+- 安装依赖：`pnpm install`
+- 依赖的本地服务：PostgreSQL（`docker compose up -d db`），Redis 不需要
+
+## 构建与静态检查
+- 类型检查：`pnpm typecheck`
+- 代码检查：`pnpm lint`
+
+## 单元与集成测试
+- 全部：`pnpm test`（约 2 分钟，基线 412 个用例全部通过）
+- 单个文件：`pnpm test path/to/file.test.ts`
+
+## 启动服务
+- 命令：`pnpm dev`（在仓库根目录）
+- 就绪判断：`GET http://localhost:3000/health` 返回 200，通常 10 秒内
+- 停止：结束该进程；端口 3000
+
+## 端到端验证
+- 工具：Playwright，`pnpm e2e`；或手工用浏览器访问 http://localhost:3000
+- 测试账号：见 docs/test-accounts.md（不要写入真实口令）
+- 测试替身：短信、支付走 `MOCK_EXTERNAL=1`
+
+## 已知问题
+- `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/0001-step-agents-under-origin-chat.md

@@ -0,0 +1,15 @@
+# 0001 步骤 agent 挂在发起的对话下
+
+- 状态：已采纳（[0018](0018-own-worktree-option.md) 增加了一种可选方式：步骤放在为需求新建的工作区中，仍挂在对话下，对话目录不变）
+
+## 背景
+
+Paseo 在创建子 agent 时，如果传了 parent，会使用 parent 的工作目录而不是传入的 cwd。早期版本在两者不一致时改为创建独立 agent，结果步骤的产物写到了别处。
+
+## 决定
+
+步骤 agent 一律作为子 agent 挂在发起的对话下；仓库目录就是这个对话的工作目录。启动前核对两者，不一致时拒绝启动；创建后再核对 agent 的工作目录，不对就归档并报错。
+
+## 影响
+
+使用者在对话的子 agent 列表里就能看到每一步；不会出现产物写错目录的情况。代价是必须在需求所在项目的对话中发起。

package/docs/adr/0002-no-directory-switch-in-chat.md

@@ -0,0 +1,15 @@
+# 0002 对话过程中不切换工作目录
+
+- 状态：已采纳（[0018](0018-own-worktree-option.md) 增加了一种可选方式：步骤放在为需求新建的工作区中，仍挂在对话下，对话目录不变）
+
+## 背景
+
+一个对话对应一个需求的工作现场。中途切换目录会让功能目录、分支和流水线的仓库目录对不上。
+
+## 决定
+
+skill 明确要求不 cd 到别的目录执行命令，功能目录必须建在当前工作目录之内；需求属于其他项目时，到那个项目新开对话。
+
+## 影响
+
+规则简单、可检查。跨项目的需求需要分别发起。

package/docs/adr/0003-script-engine-not-hub.md

@@ -0,0 +1,15 @@
+# 0003 第 3–11 步由脚本引擎驱动，不用 Hub 多步骤工作流
+
+- 状态：已采纳
+
+## 背景
+
+Paseo Hub 的多步骤格式在文档中属于旧格式，不支持循环（审核 ⇄ 修订）、断点续跑，也不能把进展发回发起的对话。
+
+## 决定
+
+用 Node/TypeScript 编写确定性的引擎，通过 SDK 创建步骤 agent、等待结果、发通知。Hub 版本移到 legacy/，不再维护。
+
+## 影响
+
+流程顺序、轮数、续跑由程序保证，可测试。需要在本机安装 Node.js 和依赖。

package/docs/adr/0004-result-files.md

@@ -0,0 +1,15 @@
+# 0004 步骤结论只看结果文件
+
+- 状态：已采纳
+
+## 背景
+
+模型最后一条回复的格式不稳定，无法可靠解析。
+
+## 决定
+
+每个步骤写一个 JSON 结果文件，字段由引擎校验；缺失或无效时在同一会话中追问，次数有上限。
+
+## 影响
+
+引擎的分支判断可靠、可测试。提示词需要说明结果文件的写法。

package/docs/adr/0005-no-default-branch-local-commits-only.md

@@ -0,0 +1,15 @@
+# 0005 不在默认分支上运行，只做本地提交
+
+- 状态：已采纳
+
+## 背景
+
+流水线无人值守地修改和提交代码，合并上线必须由人决定。
+
+## 决定
+
+拒绝在默认分支（main、master、origin/HEAD 指向的分支）和 detached HEAD 上启动；续跑时分支必须与上次一致；步骤只做本地提交，不 push、不合并。
+
+## 影响
+
+推荐每个需求一个 worktree 工作区。

package/docs/adr/0006-skill-install-targets.md

@@ -0,0 +1,15 @@
+# 0006 只安装到 ~/.agents/skills 和 ~/.claude/skills
+
+- 状态：已采纳
+
+## 背景
+
+Paseo 运行各 agent 自己的命令行工具。~/.agents/skills 被 Codex、Pi、OpenCode 读取；Claude Code 读 ~/.claude/skills。同时装到更多目录会让同一个 skill 出现多份。
+
+## 决定
+
+默认安装到 ~/.agents/skills，以及存在时的 ~/.claude/skills；其他目录用 --target 追加并被记住。暂不安装到 ~/.codex/skills。
+
+## 影响
+
+覆盖四种 agent。Codex 的触发方式需要在真实环境中确认。

package/docs/adr/0007-own-interview-skill.md

@@ -0,0 +1,15 @@
+# 0007 自带需求访谈 skill，不依赖外部 skill 包
+
+- 状态：已采纳
+
+## 背景
+
+脚本版依赖 Matt Pocock 的 grilling 和 domain-modeling。后者已把术语文件从 CONTEXT.md 改为 GLOSSARY.md，说明外部依赖的文件约定会漂移。
+
+## 决定
+
+req-kit 自带 requirement-interview，术语写入 GLOSSARY.md，读取时兼容 CONTEXT.md。
+
+## 影响
+
+安装少一步，行为由 req-kit 自己掌控和评估。

package/docs/adr/0008-entries-do-not-call-entries.md

@@ -0,0 +1,15 @@
+# 0008 入口 skill 之间不互相调用
+
+- 状态：已采纳
+
+## 背景
+
+入口（/req、/req-doctor 等）由用户触发。一个入口调用另一个入口，会让行为难以预期，也难以单独评估。
+
+## 决定
+
+入口可以调用方法 skill、引用原则、执行引擎命令；需要另一个入口时，告诉用户去运行它。
+
+## 影响
+
+每个入口的行为可以独立预期和测试。

package/docs/adr/0009-versioned-install-layout.md

@@ -0,0 +1,15 @@
+# 0009 程序与本机配置分开存放，按版本目录并存
+
+- 状态：已采纳
+
+## 背景
+
+脚本版的配置放在程序目录里，升级要手工保留配置；运行中的流水线依赖程序文件，直接覆盖有风险；也无法快速回滚。
+
+## 决定
+
+程序放在 ~/tools/req-kit/versions/<版本>/，本机配置放在 ~/.req-kit/。在哪个版本目录运行 install.mjs，就启用哪个版本。状态文件带格式版本，可迁移。
+
+## 影响
+
+升级不动配置；运行中的流水线按旧版本跑完；回滚是一条命令。旧版本目录需要定期清理（install.mjs --prune 会列出）。

package/docs/adr/0010-generated-feature-overview.md

@@ -0,0 +1,15 @@
+# 0010 需求总览现场生成，不维护 INDEX.md
+
+- 状态：已采纳
+
+## 背景
+
+设计方案计划在 `docs/features/INDEX.md` 中维护所有需求的一览。但每个需求在自己的 worktree 和分支上进行，如果每个分支都修改同一个提交进仓库的文件，合并时会反复冲突；而且一个工作区里看不到其他工作区尚未合并的需求。
+
+## 决定
+
+不提交 `INDEX.md`。`start-pipeline --list` 现场扫描这个仓库所有 worktree 中的 `docs/features/*/spec.md`、状态文件和验收记录，生成总览；同一需求出现在多个工作区时取最近更新的一份。`/req` 在路由、查看进度和接手时使用它。
+
+## 影响
+
+没有合并冲突，能看到所有工作区中的需求。代价是总览只在本机生成；不在这台机器上的工作区看不到。

package/docs/adr/0011-resume-after-completion.md

@@ -0,0 +1,15 @@
+# 0011 完成后修改 spec 可以继续开发
+
+- 状态：已采纳
+
+## 背景
+
+修改需求、验收发现问题时，流水线往往已经完成。原来的规则是"已完成的流水线不能 --resume，只能 --restart"，而 --restart 会丢掉运行记录，也不是使用者想表达的意思。
+
+## 决定
+
+流水线已完成、且 spec.md 在完成后被修改过时，`--resume` 从方案设计重新开始（第 N+1 次尝试），沿用原来的发起对话和分支；spec 没有改过时仍然拒绝，并说明先更新 spec。
+
+## 影响
+
+"修改需求"和"验收"手册可以统一用"继续"命令；每次重开都有 changes.md 中的记录可查。

package/docs/adr/0012-review-panel.md

@@ -0,0 +1,18 @@
+# 0012 评审小组：首轮并行评审，评审者核实汇总
+
+- 状态：已采纳
+
+## 背景
+
+单一模型评审容易有固定的盲区；参考 pstack 的 `/interrogate`，多个模型独立评审能发现更多问题。但成员意见直接投票会放大误报，而且并行的成员在同一个目录里提交代码会互相冲突。
+
+## 决定
+
+- 配置 `reviewPanel` 开启，默认关闭；默认只用于标准档、方案审核和代码评审的第一轮。后续轮次只核对修复，用单个评审者。
+- 成员并行运行，只读代码，各写一份意见文件到 `<功能目录>/review-panel/`，不提交、不写 `progress.md` 和 `decisions.tsv`。
+- 配置的 `reviewer` 作为汇总者，逐条核实并归入"必须修改 / 建议修改 / 留给人决定 / 已驳回"四类；结论只依据核实后的"必须修改"，不按成员数量投票。被驳回和留给人决定的意见记入 `decisions.tsv`，最终报告展示。
+- 部分成员失败时只汇总完成的成员；全部失败时该步骤失败。
+
+## 影响
+
+开启后每次评审多出 N 个 agent 的用量。汇总者的核实质量决定了效果，需要通过评估观察误报和漏报。

package/docs/adr/0013-no-release-tooling.md

@@ -0,0 +1,15 @@
+# 0013 发布不使用 changesets 等工具
+
+- 状态：已采纳（取代设计方案中"由 changesets 维护 CHANGELOG"的计划）
+
+## 背景
+
+设计方案计划用 changesets 维护版本号和 CHANGELOG。req-kit 是单一包、发布频率低，CHANGELOG 的主要读者是使用者和安装者，需要"使用者会看到的变化"和"升级须知"这样的结构，工具生成的条目还要人工改写。
+
+## 决定
+
+版本号和 CHANGELOG 由维护者按 [维护者指南](../guide/维护者指南.md) 的发布流程手工维护；标签不带 `v` 前缀。
+
+## 影响
+
+少一个开发依赖。需要维护者在每次发布时认真写 CHANGELOG；发布流程中的验证步骤由指南约束。

package/docs/adr/0014-notifier-slot.md

@@ -0,0 +1,19 @@
+# 0014 外部通知只留接口，不内置任何 IM
+
+- 状态：已采纳
+
+## 背景
+
+需求方往往不一直盯着 Paseo 对话，"需要你决定""开发中断""已完成"这几个时刻希望在企业内部 IM 中收到。各企业的 IM 不同，鉴权和接口多是内部的，req-kit 无法也不应该内置。
+
+## 决定
+
+- 引擎在 milestone、blocked、permission、failed、completed 五个时刻，除发回发起的对话外，调用配置中 `notifiers` 列出的本机模块，事件格式见 [contracts/notifier-event.md](../../contracts/notifier-event.md)（`schema: 1`）。
+- 模块由使用方实现（从 `notifiers/im-template.mjs` 复制），req-kit 不为它安装依赖。
+- `notifiers` 只能写在本机或团队配置中，项目配置中的会被忽略：项目仓库里的内容不应决定在本机执行哪段代码、往哪里发消息。
+- 通知失败或超过 15 秒只记日志，不影响流水线。
+- `req notify-test` 发示例事件，接入时不需要真的运行流水线。
+
+## 影响
+
+接入 IM 只需写一个函数。事件格式成为对外约定，同一 `schema` 内只增加字段。

package/docs/adr/0015-incremental-continue.md

@@ -0,0 +1,17 @@
+# 0015 需求变更后增量继续，而不是从零重做
+
+- 状态：已采纳（细化 [0011](0011-resume-after-completion.md)：0011 决定"可以继续"，本条决定"怎么继续"）
+
+## 背景
+
+1.2 中 spec 改动或回答了需求方的问题后继续，是"从方案设计重新开始"：步骤 agent 拿到的提示与第一次相同，往往重新写一遍方案、重新审核全部代码，耗时接近第一次，还可能改掉已经验收过的部分。
+
+## 决定
+
+- 从方案设计继续时，状态中记录 `incremental`：接着第几次尝试、原因、本次开始时的提交、上一次是否已写过代码。
+- 各步骤的提示附加 `engine/prompts/incremental.md`：方案在原文末尾追加"第 N 次尝试：需求变更"一节，只设计变化的部分；实现只改需要改的；代码评审只看本次开始以来的改动；验证重点验变化的验收标准，并回归其余的；报告说明这是第几次。
+- `--restart` 仍是完全从零开始，不参考上次的方案和代码。
+
+## 影响
+
+变更后的继续通常比第一次快很多。增量的前提是上次的方案和提交还在分支上；如果分支被重置过，应使用 `--restart`。

package/docs/adr/0016-upgrade-from-tags.md

@@ -0,0 +1,19 @@
+# 0016 一键升级：从 git 标签下载到 versions/ 再切换
+
+- 状态：已采纳（在 [0009](0009-versioned-install-layout.md) 的目录结构上增加自动化）
+
+## 背景
+
+手工升级要 clone、npm install、运行 install.mjs 三步，非专业开发的使用者容易漏掉 npm install 或在错误的目录运行。
+
+## 决定
+
+- `node install.mjs --upgrade [版本]`（`req upgrade`）：用 `git ls-remote --tags` 读取已发布版本，`git clone --depth 1 --branch <标签>` 到 `versions/<版本>`，`npm install --omit=dev`，再运行新版本的 `install.mjs` 切换。
+- 不写版本时取最新版本；当前是正式版时只升级到正式版，当前是预发布版（beta）时也考虑预发布版。
+- 下载地址取 `package.json` 的 `repository`，可用环境变量 `REQ_KIT_REPO_URL` 或 `--from` 改为内网镜像。
+- 任何一步失败，当前版本不受影响；下载先写到临时目录，完整后才改名为版本目录。
+- 安装时在 `~/.req-kit/bin` 写入 `req`（和 Windows 的 `req.cmd`），指向当前启用的版本。是否加入 PATH 由使用者决定，安装程序只给出命令，不修改系统设置。
+
+## 影响
+
+升级只需要 git 和 npm 可用；回滚仍是在旧版本目录运行 `node install.mjs`。体检会提示有新版本（离线时跳过）。

package/docs/adr/0017-use-paseo-capabilities.md

@@ -0,0 +1,18 @@
+# 0017 用好 Paseo 自身的能力：profile、工作区脚本、用量和时间线
+
+- 状态：已采纳
+
+## 背景
+
+1.3 及以前，req-kit 只用到 Paseo 的"创建 agent 并挂在对话下"和"等待结束"。Paseo 0.11 已经提供了 agent profile（带使用说明的启动配置）、`paseo.json`（worktree 准备脚本和受监管的服务，每个工作区独立端口）、provider 用量、agent 时间线等能力。req-kit 自己再实现一遍既重复，又和使用者在 Paseo 界面里看到的不一致。
+
+## 决定
+
+- **agent 配置可以引用 Paseo profile**（`paseoProfile`），在每次运行开始时从 daemon 读取并解析；找不到时拒绝启动并列出现有的 profile。
+- **服务交给 Paseo**：对话所在工作区的 `paseo.json` 定义了服务时，流水线在需要服务的步骤前通过 Paseo 重启它们，结束后停止；步骤 agent 只拿到地址和状态。`paseoServices: "off"` 或没有发起对话时，仍由步骤 agent 自己启动。
+- **用量和时间线只用于提示**：额度紧张时提醒一次，不阻止运行；查看进度时附上 agent 最近的活动，读不到就省略。
+- 工作区脚本在 `@getpaseo/client` 0.11 的公开 API 中还没有，暂时通过它导出的 `internal/daemon-client` 调用，并且每一处都在不可用时退回原来的做法。req-kit 已经把 Paseo 版本限定在 0.11.x（`reqKit.paseo`），升级 Paseo 支持范围时必须复查这一处。
+
+## 影响
+
+使用者在 Paseo 里改 profile、写 `paseo.json` 就能影响流水线，不必再改 req-kit 的配置。依赖了一个内部接口，升级 Paseo 时有额外的检查项（维护者指南的发布流程中已列出）。

package/docs/adr/0018-own-worktree-option.md

@@ -0,0 +1,21 @@
+# 0018 可选：流水线为需求新建 worktree 工作区
+
+- 状态：已采纳（补充 [0001](0001-step-agents-under-origin-chat.md)、[0002](0002-no-directory-switch-in-chat.md)：两条的规则不变，增加一种由流水线放置步骤的方式）
+
+## 背景
+
+在项目主目录、主分支上发起的需求，原来只能请使用者自己在 Paseo 中新建 worktree 工作区、换到那里的对话重新开始，或者在主目录新建分支（主目录被占用几个小时）。对不熟悉 worktree 的使用者来说，第一种多了一次切换，第三种影响主目录。
+
+Paseo 0.11 支持在指定的工作区中创建 agent，同时保持它是发起对话的子 agent（"放置不改变归属"），也能由 SDK 新建 worktree 工作区并执行 `paseo.json` 的准备脚本。
+
+## 决定
+
+- 启动时加 `--worktree`（`/req` 中的"启动（自动新建工作区）"）：流水线用 Paseo 从当前分支切出 `feature/<功能目录名>`，新建 worktree 工作区；把需求说明等文件移过去并在新分支上提交（原处未提交的副本删除，已提交的保留）；之后各步骤 agent 放在这个工作区中运行，仍然挂在发起的对话下。
+- **对话的工作目录不变**（0002 不变）。对话里的查看进度、暂停、继续、验收命令照常在原目录执行，启动器会按状态文件中记录的来源目录找到新工作区；只允许从这个来源目录的对话操作。
+- 发给对话的通知中，功能目录和报告写完整路径，因为它们不在对话的目录里。
+- 只用于第一次启动；已经在原处运行过的需求不能中途改为新工作区。
+- 默认仍然是原来的方式，这是一个可选项。
+
+## 影响
+
+主分支上发起的需求不再需要使用者手动建工作区；`paseo.json` 的准备脚本自动执行。对话 agent 需要用完整路径读写需求文件，`/req` 中已写明。新工作区的归档和清理仍由使用者在 Paseo 中决定。

package/docs/adr/0019-parallel-orchestration.md

@@ -0,0 +1,21 @@
+# 0019 用 Paseo 的并行子 agent：确认前独立审阅、方案提案
+
+- 状态：已采纳
+
+## 背景
+
+Paseo 自带 `/paseo-advisor`（第二意见）、`/paseo-committee`（两个模型独立分析）等编排 skill。它们由聊天 agent 自由发挥，结果没有固定的去处，也不会稳定地写回需求文件；直接让 `/req` 调用它们还违反"入口不调用入口"（ADR 0008）。
+
+## 决定
+
+同样的思路由 req-kit 的引擎以固定的步骤实现，产物写进功能目录：
+
+- **需求说明审阅**（`--spec-review`）：在需求方确认之前，由 reviewer（通常与对话用的不是同一个模型）在后台独立审阅草稿，写 `spec-review.md`，把问题写成带推荐的选择题；完成后通知对话，由对话 agent 核对后逐个问用户。不改 spec、不提交。默认只用于标准档（`specReview`）。
+- **方案提案**（`designProposals`，默认关闭）：标准档的方案设计之前，几个 agent（默认 builder 和 reviewer）并行各提一份方案，方案设计步骤比较后决定，并在 `design.md` 中写"方案比较"。增量继续时不做。
+- **浏览器验证**（`browserVerify`）：步骤 agent 有 Paseo 浏览器工具时，验证类步骤按验收标准在浏览器中实际操作。
+
+Paseo 的编排 skill 仍然推荐使用者单独使用（例如对一个疑难问题请 `/paseo-committee`），文档中说明。
+
+## 影响
+
+确认前多一次几分钟的审阅，能在开发之前发现遗漏和歧义；方案提案以多一份方案的用量换取复杂需求的方案质量，所以默认关闭。

package/docs/adr/0020-scheduling-through-the-chat.md

@@ -0,0 +1,21 @@
+# 0020 调度：用 Paseo 定时任务把消息发回对话，排队在本机进行
+
+- 状态：已采纳
+
+## 背景
+
+需求开发要几个小时，使用者常常不在电脑前：希望晚上或明天早上再开始；限流中断后能自己接着做；等自己回答问题太久时有人提醒；同一台机器同时跑太多条流水线会抢资源和额度。
+
+流水线进程是后台脚本，进程结束后就没有谁来做"过一会儿再做某事"。Paseo 的定时任务（schedules）由 daemon 保存，机器重启后仍然有效，可以在指定时间把一段话发进某个 agent 的对话，也可以按时间表启动新 agent。
+
+## 决定
+
+- **需要"以后再做"的事，都用 Paseo 定时任务把一条写明步骤的消息发回发起的对话**，由对话 agent 执行 req-kit 的命令：预约开始（`--at`）、等待回答的提醒（`waitingReminderHours`）、临时错误后的自动继续（`autoResumeMinutes`，每次尝试最多 `autoResumeMax` 次）、可选的定时检查（`watchdogMinutes`，默认关闭）。消息先让对话 agent 查看进度，状态不符就什么也不做，所以重复或过期的消息无害。
+- 这些定时任务记在状态文件中，下一次运行和暂停命令会取消它们；预约开始记在 `.pipeline/scheduled-start.json`。
+- **并发上限在本机实现**（`maxConcurrentPipelines`，`~/.req-kit/slots/`）：排队的流水线进程自己等待名额，不需要 Paseo 参与。
+- **需求总览**（`req digest`）发给外部通知；`--schedule` 用 Paseo 定时任务按时间表启动一个短暂的 agent 执行这条命令（会产生少量用量）。
+- Paseo 定时任务在 0.11 的公开 SDK 中还没有，和工作区脚本一样经由内部客户端调用（见 ADR 0017），不可用时这些功能自动关闭，并在输出中说明。
+
+## 影响
+
+使用者不在时，开发可以按时开始、出错后自己继续、等待太久会被提醒。每条定时消息会让对话 agent 运行一个回合，有少量用量；定时检查的回合最多，所以默认关闭。

package/docs/adr/0021-npm-version-manager.md

@@ -0,0 +1,19 @@
+# 0021 npm 分发：全局包是版本管理器，各版本仍装在 versions/ 下
+
+- 状态：已采纳（在 [0009](0009-versioned-install-layout.md)、[0016](0016-upgrade-from-tags.md) 的基础上增加 npm 来源）
+
+## 背景
+
+git 安装要 clone、npm install、运行安装器三步，Windows 上还要自己把 `~/.req-kit/bin` 加进 PATH。npm 全局安装能解决这两点，但 `npm i -g` 升级时原地覆盖：正在运行的流水线每个步骤都从磁盘读提示词，会混用新旧版本，也失去了"旧版本目录保留、随时回滚"的保证（0009）。
+
+## 决定
+
+- 只发布一个包 `paseo-req-kit`。用 `npm i -g` 安装的那一份是**版本管理器**：`req setup`、`req upgrade`、`req use`、`req versions` 由它处理，其他命令转交给 `~/.req-kit/active.json` 指向的版本。
+- 版本仍装在 `~/tools/req-kit/versions/<版本>`，用 `npm install --prefix versions/<版本> paseo-req-kit@<版本>` 安装，程序在其中的 `node_modules/paseo-req-kit`。`req setup` 用 `npm pack` 把管理器自己装进去，不必再从仓库下载一次。
+- `req upgrade` 从 npm 读版本列表，用本机 daemon 报告的版本和每个版本声明的 `reqKit.paseo` 范围筛选，只升级到能支持本机 Paseo 的版本。正式版另设 `paseo-<小版本>` dist-tag，供手工安装。
+- git 方式安装继续支持，默认来源按安装方式决定，`--from` 可以改。
+- 发布由 GitHub Actions 在标签推送时完成，使用 npm 可信发布（OIDC），不保存 npm 口令；Release 附带 `npm pack` 的安装包供离线和内网仓库使用。
+
+## 影响
+
+安装变成两条命令，PATH 由 npm 处理。管理器自身很少需要升级（`npm i -g paseo-req-kit` 即可），版本切换不受影响。读不到 daemon 版本时不能按 Paseo 版本筛选，会提示并在升级后建议体检。

package/docs/adr/0022-develop-and-verify-phases.md

@@ -0,0 +1,32 @@
+# 0022 分阶段执行：研发阶段、闸口、测试验证阶段
+
+- 状态：已采纳（补充 [0015](0015-incremental-continue.md)、[0018](0018-own-worktree-option.md)：测试阶段可以由同一仓库另一个工作区的对话接手）
+
+## 背景
+
+原来第 3–11 步一口气跑完，只在方案审核需要需求方决定时停下。很多团队的研发和测试是两拨人、两个节奏：研发完成要"提测"，测试同事先部署测试环境、准备数据，再验证，或者干脆人工测试；验证也可能想用另一个模型，在另一个时间进行。
+
+代码评审通过之后、服务启动和功能验证之前，是天然的分界。
+
+## 决定
+
+- 分成固定的两个阶段：**研发**（方案设计 → 方案审核 ⇄ 修订 → 实现 → 代码评审 ⇄ 修复 → 提测说明）和**测试验证**（服务启动 → 功能验证 → 缺陷处理），中间一个闸口。不做任意切分、可配置的阶段：常见的交接点只有"提测"一处，任意切分会让状态、继续规则和手册都变复杂。阶段名在状态里用字符串（`develop`、`verify`），以后增加阶段不用改格式。
+- 研发阶段最后新增一步"提测说明"（builder，`handoff.md`）。三种执行方式都写：连续时它是功能验证的输入，分阶段时是交给测试的单据，只做研发时是人工测试的依据。
+- 闸口怎么走由**执行方式**决定，来源后者覆盖前者：配置 `phases.mode` → spec 头部 `- 执行方式：` → 启动参数 `--phases`。
+  - `continuous`（连续，默认）：直接进入测试验证，与之前的行为一致。
+  - `gated`（分阶段）：状态变为 `phase_done`，进程正常退出、不占排队名额；通知对话"研发完成，可以提测"，外部通知新事件 `phase_done`；等待提醒（`waitingReminderHours`）也覆盖这个状态。`--resume --phase verify`（或在闸口单独的 `--resume`）开始测试验证，沿用研发阶段的结果。`--verify-at` 在研发完成时预约开始时间（复用 [0020](0020-scheduling-through-the-chat.md) 的定时任务）；研发完成时时间已过就直接继续。
+  - `develop-only`（只做研发）：写完提测说明后写一份研发报告并结束，状态为 `completed`；之后仍可用 `--phase verify` 让流水线做测试验证。
+- 测试验证阶段的选项写在 `phases.verify`，开始测试时也可以用参数临时指定：
+  - `environment`：`local`（本地启动服务）或 `deployed`（对已部署的测试环境验证，需要功能目录中的 `test-env.md`，没有就拒绝开始；不在本地启动服务）。
+  - `agents`：测试阶段的步骤（服务启动、功能验证、缺陷修复、复验）可以用单独的 agent，格式同顶层 `agents`，可用 `paseoProfile`。完成报告仍用顶层的 builder。
+  - `defects`：`fix`（当场修复并复验，原来的做法）、`handback`（只记录，退回研发阶段：在 `changes.md` 追加"测试验证退回"一节，开始新的一次尝试，按 [0015](0015-incremental-continue.md) 从方案设计增量处理，修复经过代码评审、重新写提测说明后再提测；次数上限为档位的缺陷修复轮数）、`report`（只记录，直接出报告）。
+- 测试阶段开始前需求说明改过：按增量继续的规则回到研发阶段的方案设计。
+- **测试同事接手**：需求在自动新建的工作区中开发（0018）且研发已完成（或已在测试验证阶段）时，同一仓库任何工作区中的对话都可以开始或继续测试验证；通知转到那个对话，步骤仍放在需求的工作区、挂在那个对话下。研发阶段仍然只能从来源目录的对话操作。不在自动新建工作区中的需求，测试同事需要在同一目录的对话中接手（步骤 agent 使用对话的目录，见 [0001](0001-step-agents-under-origin-chat.md)）。
+- 安全边界不变：测试环境只能是测试用途的环境；`test-env.md` 只写口令在哪里取，不写口令本身；提示词继续禁止连接生产环境、使用生产凭据。
+
+## 影响
+
+- 状态文件只增加可选字段（`phases`、`phase`、`verifyAt`、`handbacks`、步骤记录的 `phase`）和状态值 `phase_done`，格式版本仍为 1。回滚到 1.6 后，旧引擎把 `phase_done` 当作可以继续的中断，继续时沿用研发结果、直接做验证，可以接受。
+- 所有运行（包括连续方式）多一个"提测说明"步骤，通常几分钟。
+- 外部通知按约定只增加了事件类型 `phase_done` 和字段。
+- 用时与用量可以按阶段统计（状态、完成报告）。

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 运行。都可以在配置中关闭。