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

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/README.md

@@ -0,0 +1,26 @@
+# 设计决定（ADR）
+
+req-kit 自身的设计决定。修改其中任何一条，请新增一条 ADR 说明理由，并在旧的一条中注明被哪条取代。
+
+- [0001 步骤 agent 挂在发起的对话下](0001-step-agents-under-origin-chat.md)
+- [0002 对话过程中不切换工作目录](0002-no-directory-switch-in-chat.md)
+- [0003 第 3–11 步由脚本引擎驱动，不用 Hub 多步骤工作流](0003-script-engine-not-hub.md)
+- [0004 步骤结论只看结果文件](0004-result-files.md)
+- [0005 不在默认分支上运行，只做本地提交](0005-no-default-branch-local-commits-only.md)
+- [0006 只安装到 ~/.agents/skills 和 ~/.claude/skills](0006-skill-install-targets.md)
+- [0007 自带需求访谈 skill，不依赖外部 skill 包](0007-own-interview-skill.md)
+- [0008 入口 skill 之间不互相调用](0008-entries-do-not-call-entries.md)
+- [0009 程序与本机配置分开存放，按版本目录并存](0009-versioned-install-layout.md)
+- [0010 需求总览现场生成，不维护 INDEX.md](0010-generated-feature-overview.md)
+- [0011 完成后修改 spec 可以继续开发](0011-resume-after-completion.md)
+- [0012 评审小组：首轮并行评审，评审者核实汇总](0012-review-panel.md)
+- [0013 发布不使用 changesets 等工具](0013-no-release-tooling.md)
+- [0014 外部通知只留接口，不内置任何 IM](0014-notifier-slot.md)
+- [0015 需求变更后增量继续，而不是从零重做](0015-incremental-continue.md)
+- [0016 一键升级：从 git 标签下载到 versions/ 再切换](0016-upgrade-from-tags.md)
+- [0017 用好 Paseo 自身的能力：profile、工作区脚本、用量和时间线](0017-use-paseo-capabilities.md)
+- [0018 可选：流水线为需求新建 worktree 工作区](0018-own-worktree-option.md)
+- [0019 用 Paseo 的并行子 agent：确认前独立审阅、方案提案](0019-parallel-orchestration.md)
+- [0020 调度：用 Paseo 定时任务把消息发回对话，排队在本机进行](0020-scheduling-through-the-chat.md)
+- [0021 npm 分发：全局包是版本管理器，各版本仍装在 versions/ 下](0021-npm-version-manager.md)
+- [0022 分阶段执行：研发阶段、闸口、测试验证阶段](0022-develop-and-verify-phases.md)

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

@@ -0,0 +1,78 @@
+# 使用者指南
+
+req-kit 帮你把一个需求从"我想要……"做到"可以验收"：你在 Paseo 的对话里把需求讲清楚、确认一份需求说明，之后的方案设计、写代码、评审、测试和报告由一组 AI agent 在后台完成，结果发回同一个对话。
+
+适合测试、产品经理、项目经理等不写代码、但熟悉需求和测试的同事。你不需要读代码，但可以随时查看每一步的产物，也可以亲自执行测试命令核对结果。
+
+## 第一次使用之前
+
+请开发同事确认这台机器已经装好 req-kit（`/req-doctor` 全部正常），并且项目已经接入：在项目根目录的对话中运行过 `/req-setup`，生成了项目说明和验证方法。测试同事熟悉项目的话，也可以自己运行 `/req-setup`。
+
+## 提一个需求
+
+1. **准备工作区**：每个需求最好有自己的 worktree 工作区，几个需求可以同时进行，互不影响。两种方式任选：
+   - 直接在项目的对话里开始，AI 问到时选"开发时自动新建工作区"：照常谈需求，启动开发时流水线会自动新建工作区并在那里开发，这个对话不用动。
+   - 自己新建：在 Paseo 中点 **New workspace** → 选择项目 → **Isolation** 选 **New worktree** → 起点选主分支，然后在新工作区的对话里开始。
+2. **输入 `/req` 和一句话**：例如 `/req 登录页增加短信验证码登录`。用 Pi 时输入 `/skill:req ……`。
+3. **回答问题**：AI 会先复述它的理解，然后一次问一个问题，给出选项和推荐。它会问到异常情况、权限、已有数据、测试数据和验证环境，这些往往是你最清楚的。拿不准时可以说"你定"，它会采用推荐项并记为假设，最后请你过目。
+4. **独立审阅**（标准档）：确认之前，AI 会请另一个模型把需求说明独立审一遍，几分钟后把发现的问题（歧义、遗漏、没法验证的验收标准）逐个问你。这一步常常能省掉开发之后的返工。
+5. **确认需求说明**：AI 给出一份 10 行以内的摘要，完整的需求说明在 `docs/features/<日期>-<名称>/spec.md`。确认后它会问是否开始开发。
+6. **等待**：开发在后台进行，通常需要几个小时，不需要盯着。期间你会收到几句进展（方案定了、开始验证等）。
+
+小改动（改文案、样式、一个配置项）会走快速流程：只问 2–3 个问题，开发环节各做一轮。
+
+**研发和测试分开做**（标准档，确定档位时 AI 会问，团队配置里定好了就不问）：
+
+- **连续**（默认）：研发完成后流水线接着做测试验证，一次跑完。
+- **分阶段**：研发完成、写好提测说明（`handoff.md`）后停下来通知你："研发完成，可以提测"。你或测试同事准备好之后说"开始测试验证"，AI 会讲一遍提测说明，问清在哪里测（本地，或已部署的测试环境）、发现缺陷怎么办（当场修复、退回研发修复后再提测，或只记录），然后开始；也可以预约时间。用"开发时自动新建工作区"开发的需求，测试同事可以在自己的对话里输入 `/req 开始测试验证 <需求名称>` 接手。
+- **只做研发**：做到提测说明和研发报告为止，测试由人完成，验收时 AI 会按提测说明带你逐条测试。
+
+## 过程中
+
+| 你想做的 | 在对话里说 |
+| --- | --- |
+| 看进度 | "做到哪了"（会说明当前在哪一步、agent 最近在做什么，例如正在运行测试） |
+| 暂停 | "先停一下"（当前步骤做到一半的工作不保留，已完成的步骤保留） |
+| 继续 | "继续开发" |
+| 改需求 | "我想改一下……"：先暂停，谈清变化的部分，更新需求说明（版本加 1，记入 `changes.md`）后继续，开发会在已有方案和代码的基础上只处理变化的部分。开发已经完成的也可以改 |
+| 看看项目里有哪些需求 | "现在有哪些需求"：列出所有工作区中的需求和各自的阶段 |
+| 研发完成后提测 | "开始测试验证"（分阶段执行时）；想晚点开始就说"等测试环境部署好，明早 9 点开始测试" |
+| 晚点再开始 | 确认需求后说"今晚 10 点开始""明天早上开始"：到时会在这个对话里自动开始，说"先停一下"可以取消 |
+| 接手别人的需求 | "这个需求之前是同事提的，现在什么情况"：讲清现状、待决事项和下一步 |
+
+也可以不进对话，在终端里用 `req` 命令（需要开发同事装好并加入 PATH，见 [安装与升级](安装与升级.md)）：在项目目录中 `req list` 看所有需求，`req status` 看进度（多个需求时写名称的一部分，如 `req status sms-login`），`req stop`、`req resume` 暂停和继续。
+
+每个步骤都会出现在这个对话的子 agent 列表里（名字形如"[20261012-sms-login] 6-代码评审 第2轮"），点开可以看到它在做什么。功能目录下的 `progress.md` 按时间记录了每一步的结果。
+
+可能收到的通知（团队接入了企业 IM 的话，这些通知也会发到 IM）：
+
+- **需要你决定**：方案审核发现只有你能回答的问题。AI 会逐个问你，然后继续。一天没有回答的话，会在对话里提醒一次。
+- **研发完成，可以提测**（分阶段执行时）：代码已写完并通过评审，提测说明在 `handoff.md`。一天没有开始测试验证的话，会在对话里提醒一次。
+- **等待批准**：某一步在等权限批准，按提示打开对应的 agent 处理，或请开发同事处理。
+- **中断**：限流、网络中断这类临时问题会先自动等待重试，仍然不行才中断，并预约半小时后自动继续（说"先停一下"可以取消）。AI 会说明原因和日志位置。环境类问题（例如测试服务没启动）你可以自己处理；涉及配置或代码的请开发同事处理。处理后说"继续开发"。
+
+## 验收
+
+完成后你会收到结论和摘要，完整报告在功能目录的 `report.md`：
+
+- **验收对照表**：每条验收标准的结果，以及是怎么确认的（运行了什么命令、看到了什么、截图在哪里）。
+- **需要你确认的决定**：开发过程中替你做的假设和取舍，以及被驳回的评审意见里会影响结果的那些。请逐条表态。
+- **遗留问题**和**需要你做的事**。
+- **用时与用量**：各步骤 agent 合计用了多长时间、多少 token、大约多少费用，便于估算后续需求的成本。
+
+然后说"我要验收"。AI 会按验收标准一条一条带你核对：告诉你怎么操作、应该看到什么；能用命令验证的给出命令，你可以自己执行。每条结果记入功能目录的 `acceptance.md`。
+
+- **全部通过**：请开发同事审阅代码并合并上线。流水线只做本地提交，不会自己合并或上线。
+- **有不通过的**：逐项决定怎么处理：做得不对的，补进需求说明后继续开发；发现想要的不是这样的，按改需求处理；也可以接受现状并记下理由。
+
+测试同事可以把验收标准直接转成测试用例：每条都写成了"前置条件 / 操作 / 预期结果"。
+
+## 上线后发现问题
+
+说"线上发现……不对"。AI 会先问这个问题是否正在影响真实用户：是的话，请马上联系开发同事或值班人员处理线上情况（req-kit 不碰生产环境）。然后它会问清现象、复现步骤、影响范围，关联到原来的需求，生成一份缺陷说明，按快速流程修复，修复后照常验收。
+
+## 注意
+
+- 一个对话只谈一个需求；对话过程中不要切换工作目录。
+- 需求属于另一个项目时，到那个项目里新开对话。
+- 遇到"未启动"或其他看不懂的情况，输入 `/req-doctor` 做一次体检，或请开发同事看一下。