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

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

@@ -0,0 +1,29 @@
+# 设计决定（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)
+- [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

@@ -0,0 +1,96 @@
+# 使用者指南
+
+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 复述时会和你确认这是哪一类，流水线按类型走不同的做法：
+
+| 类型 | 说法举例 | 流水线怎么做 | 你需要讲清楚的 |
+| --- | --- | --- | --- |
+| 新需求 | "加一个……" | 方案、实现、评审、验证 | 要什么、怎么算做对 |
+| 缺陷 | "……不对""报错了" | 先复现、找到原因再修；复现不了会回来问你 | 复现步骤：环境、账号或数据、操作、看到的、应有的 |
+| 重构 | "整理一下……""升级依赖" | 先用测试锁住现有行为，再小步改，确认行为没变 | 改进目标，以及哪些行为必须保持不变 |
+| 评估 | "能不能做……""影响多大" | 只调研、写评估报告，由另一个模型审阅，不写代码 | 要回答的问题，结论用来做什么决定 |
+
+评估做完后，可以直接说"按评估结果提一个新需求"。
+
+**前端和后端都要改**：另一个仓库已经由开发同事登记过（`/req-setup` 时登记）的，AI 会问是否作为联合需求一起做：流水线先设计整体方案和双方的接口约定，再在每个仓库各开一个工作区同时开发，最后一起验证，报告里写明每个仓库的分支和合并顺序。
+
+**验收标准带例子**：AI 写验收标准时会给每条配上具体的数据（"输入 13800000000，60 秒内再点发送，提示'请 45 秒后重试'"）。请认真看这些例子：它们会直接变成测试检查的期望值，你确认的就是测试会检查的东西。
+
+**开工前先看一眼"做完后会看到什么"**（标准档的界面改动）：方案审核通过后、写代码之前，流水线会停下来，AI 把 `preview.md` 的要点讲给你听：会看到什么变化、有哪些需要你确认的假设；界面改动还会有静态的原型页面（功能目录的 `prototype/` 中），可以在浏览器里打开看。说"可以"就开始写代码；想改的直接说，AI 会更新需求说明，方案调整后再请你看一次。这时调整的成本最低。
+
+**研发和测试分开做**（标准档，确定档位时 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` 做一次体检，或请开发同事看一下。

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

@@ -0,0 +1,348 @@
+# 安装与升级
+
+本文面向负责安装的人：通常是开发同事，有经验的测试或产品同事也可以按步骤完成。安装在**运行 Paseo daemon 的那台机器**上做一次，之后这台机器上所有项目的 Paseo 对话都能使用 `/req`。
+
+## 1. 安装布局
+
+程序和本机配置分开存放。升级时只替换程序，配置不动；旧版本目录保留，可以随时回滚。
+
+```text
+<npm 全局目录>/paseo-req-kit/   版本管理器（npm i -g 安装，提供 req 命令）
+~/tools/req-kit/versions/
+├── 1.7.0/node_modules/paseo-req-kit/   一个版本的程序（npm 安装；依赖在 1.7.0/node_modules 下）
+├── 1.6.0/                 git 方式安装的版本（含 node_modules），继续可用
+└── …                      各版本并存，随时切换
+~/.req-kit/
+├── config.json            本机配置
+├── prompts.local/         本机提示词覆盖（可选）
+├── active.json            当前启用的版本
+├── bin/req、req.cmd       req 命令，指向当前启用的版本
+├── notifiers/             外部通知模块（可选，自己实现，见第 12 节）
+└── install-log/           安装、升级、回滚记录
+~/.agents/skills/…          安装器复制的 skill（Codex、Pi、OpenCode 等读取）
+~/.claude/skills/…          同上（Claude Code；~/.claude 存在时）
+```
+
+Windows 上 `~` 即 `%USERPROFILE%`（如 `D:\Users\<用户名>`）。安装器不使用符号链接，不需要管理员权限。环境变量 `REQ_KIT_HOME` 可以把 `~/.req-kit` 换到别的位置。
+
+## 2. 前置条件
+
+| 项目 | 要求 | 如何确认 |
+| --- | --- | --- |
+| Paseo | 0.11，daemon 在运行 | Paseo 桌面端能正常对话；默认地址 `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` |
+| agent | Claude Code、Codex、OpenCode、Pi 至少一种，已在 Paseo 中登录 | 在 Paseo 中用它开一个对话 |
+| 网络 | 能访问 GitHub 和 npm 源（或公司镜像） | `npm ping` |
+| daemon 密码 | daemon 设了密码时，放在环境变量中（默认 `PASEO_DAEMON_PASSWORD`） | 未设密码可跳过 |
+| Paseo 工具和浏览器（可选） | 设置 → 本机 → Agents 打开 **Enable Paseo tools**，并开启浏览器工具：步骤 agent 可以重启 Paseo 管理的服务、用内置浏览器验证网页（需要桌面端在线） | `/req-doctor` 的"Paseo daemon"一节 |
+| Agent profiles（推荐） | 设置 → 本机 → Agents → Agent profiles 中建好"实现""评审"等 profile，配置中引用，见第 4 节 | `/req-doctor` |
+
+## 3. 首次安装
+
+**推荐：一键安装。** 一条命令完成检查环境、安装、启用、安装 skill 和配置 agent，再次运行即升级：
+
+```bash
+# macOS、Linux、Windows 的 Git Bash 或 WSL
+curl -fsSL https://raw.githubusercontent.com/yiyisf/paseo-req-kit/main/install.sh | sh
+```
+
+```powershell
+# Windows PowerShell（不受脚本执行策略限制）
+irm https://raw.githubusercontent.com/yiyisf/paseo-req-kit/main/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`）。完成后接着做下面的**第四步**到**第六步**。
+
+**也可以用 npm 安装（1.7.0 起）。** 一键安装做的就是这几条命令，Windows 上 `req` 命令由 npm 放进 PATH，不用自己设置：
+
+```bash
+npm i -g paseo-req-kit        # beta 版：npm i -g paseo-req-kit@beta
+req setup                     # 装进 ~/tools/req-kit/versions/<版本>，安装 skill，生成本机配置
+req configure                 # 配置向导：选 builder 和 reviewer 用的 agent
+req doctor --no-project       # 体检
+```
+
+全局安装的包是版本管理器：`req setup` 把这个版本装进 `versions/<版本>`，之后 `req upgrade` 安装新版本、`req use <版本>` 切换，各版本并存，正在运行的流水线不受影响。其他 `req` 命令都转交给当前启用的版本。公司网络使用 npm 镜像或私有仓库时，按平常的方式配置 `.npmrc` 即可。
+
+完全离线时，用 GitHub Release 上附带的安装包：`npm i -g ./paseo-req-kit-<版本>.tgz`，再 `req setup`（依赖需要能从本机 npm 缓存或镜像取得）。
+
+还没有发布到 npm 的版本（或 npm 上取不到时），也可以直接用 Release 上安装包的地址：`npm i -g https://github.com/yiyisf/paseo-req-kit/releases/download/<版本>/paseo-req-kit-<版本>.tgz`，再 `req setup`。
+
+之后接着做下面的**第三步**到**第六步**（配置 agent、体检和冒烟测试、接入项目、使用者上手）。
+
+**其他方式：用 git 安装。** 不方便用 npm 全局安装时，可以把版本放进它自己的目录：
+
+**第一步：取得程序。** 把要安装的版本放进它自己的版本目录：
+
+```bash
+git clone --branch 1.8.0-beta.3 --depth 1 https://github.com/yiyisf/paseo-req-kit ~/tools/req-kit/versions/1.8.0-beta.3
+```
+
+Windows PowerShell：
+
+```powershell
+git clone --branch 1.8.0-beta.3 --depth 1 https://github.com/yiyisf/paseo-req-kit "$env:USERPROFILE\tools\req-kit\versions\1.8.0-beta.3"
+```
+
+**第二步：安装依赖并启用。**
+
+```bash
+cd ~/tools/req-kit/versions/1.8.0-beta.3
+npm install
+node install.mjs
+```
+
+`install.mjs` 会：检查 Node.js 和依赖；`~/.req-kit/config.json` 不存在时从示例生成一份；把 `skills/` 下的全部 skill 复制到各 agent 的 skill 目录，并把其中的路径替换为这个版本目录的绝对路径；在每个 skill 目录写入标记文件 `.req-kit-install.json`；记录当前启用的版本；在 `~/.req-kit/bin` 写入 `req` 命令。同名目录已存在但不是 req-kit 装的，不会覆盖，除非加 `--force`。
+
+**第三步：配置 agent。** 为 `builder`（方案设计、实现、修复、报告）和 `reviewer`（方案审核、代码评审、功能验证）各选一个 agent。推荐用配置向导（Paseo 需要在运行）：
+
+```bash
+node install.mjs --configure
+```
+
+它会列出 daemon 上已登录可用的 agent 和模型，自动选择不会停下来等待批准的模式，问几个选择题（直接回车选推荐项），确认后写入 `~/.req-kit/config.json`（原文件备份），其他设置保持不变。也可以手工编辑，写法见第 4 节；不确定模型 ID 时运行 `npm run smoke -- check` 查看可用的值。配好后再运行一次 `node install.mjs`，全部 ✓ 即完成。
+
+**`req` 命令（可选）。** 安装输出会给出把 `~/.req-kit/bin` 加入 PATH 的命令，执行一次后，新开的终端中可以直接用 `req`：
+
+| 命令 | 作用 |
+| --- | --- |
+| `req list` | 列出当前项目的所有需求和阶段 |
+| `req status [需求]` | 查看进度；只有一个需求运行过时可以不写 |
+| `req stop <需求>` / `req resume <需求>` | 停止 / 继续 |
+| `req doctor` | 体检 |
+| `req configure` | 配置向导 |
+| `req upgrade` | 升级到最新版本 |
+| `req notify-test` | 给外部通知发测试消息 |
+| `req digest` | 项目的需求总览；`--notify` 发到外部通知，`--schedule "0 9 * * 1"` 每周一 9 点自动发送 |
+
+`<需求>` 可以只写名称中能唯一确定的一部分，如 `sms-login`。`req help` 查看全部。不加 PATH 也可以用完整路径 `~/.req-kit/bin/req`（Windows 为 `%USERPROFILE%\.req-kit\bin\req.cmd`）。
+
+团队有统一配置时（统一的模型、评审小组、超时、要求的 req-kit 版本），把团队配置仓库克隆到本机，在本机配置中加上 `"teamConfig": "<团队配置文件的路径>"`（绝对路径，或相对 `~/.req-kit/` 的路径）。团队配置不能设置 daemon 地址和密码。详见 [项目定制与运行规则](项目定制与运行规则.md) 的"团队配置"。
+
+**第四步：体检和冒烟测试。** 先运行：
+
+```bash
+node bin/req-doctor.mjs --no-project
+```
+
+然后按第 5 节做冒烟测试。
+
+**第五步：接入项目（每个项目一次，推荐）。** 在项目主目录、主分支上开一个 Paseo 对话，输入 `/req-setup`。它会读项目、只问读不出来的事、实际运行验证命令，生成 `.requirement-pipeline/project-notes.md`（项目约定）和 `.requirement-pipeline/verify.md`（验证方法），确认后提交。详见 [项目定制与运行规则](项目定制与运行规则.md)。
+
+**第六步：使用者上手。** 把 [使用者指南](使用者指南.md) 发给使用者，陪他们完成第一个小需求。
+
+### 安装器参数
+
+| 参数 | 作用 |
+| --- | --- |
+| （无） | 安装或切换到这个版本 |
+| `--check` | 只检查，不修改任何文件 |
+| `--import-legacy <目录>` | 先从旧脚本版导入配置和 `prompts.local/` |
+| `--target <目录>` | 额外安装到另一个 skill 目录（可重复，会被记住，之后的升级也会更新它） |
+| `--force` | 覆盖不是 req-kit 安装的同名 skill |
+| `--prune` | 列出可以删除的旧版本目录（保留当前和上一个版本） |
+| `--uninstall` | 删除 req-kit 安装的 skill 和 `req` 命令，保留 `~/.req-kit` 中的配置 |
+| `--configure` | 配置向导 |
+| `--upgrade [版本]` | 下载并切换到最新版本或指定版本，见第 6 节 |
+| `--latest` | 查看最新发布的版本 |
+| `--from npm\|git\|<git 地址>` | 配合 `--upgrade`、`--latest`：指定升级来源 |
+| `--beta` | 配合 `--upgrade`、`--latest`：正式版也考虑 beta 版 |
+| `--setup` / `--use <版本>` / `--versions` | 版本管理（即 `req setup`、`req use`、`req versions`） |
+
+## 4. 不同 agent 的配置
+
+**推荐：引用 Paseo 的 agent profile。** 在 Paseo 的 设置 → 本机 → Agents → Agent profiles 中为"实现"和"评审"各建一个 profile（选好 provider、模型、免确认的模式），然后在配置中只写名称：
+
+```json
+"agents": {
+  "builder":  { "paseoProfile": "实现" },
+  "reviewer": { "paseoProfile": "评审" }
+}
+```
+
+每次运行开始时从 Paseo 读取 profile 的设置，之后换模型只需在 Paseo 中修改 profile。写在 `paseoProfile` 旁边的字段（如 `modeId`、`thinkingOptionId`）优先于 profile 中的设置。名称写错时流水线不会启动，并列出现有的 profile；`/req-doctor` 也会检查。配置向导在 Paseo 中有 profile 时会先列出它们。
+
+也可以直接写各项设置：
+
+每个角色的配置项：
+
+| 字段 | 含义 |
+| --- | --- |
+| `provider` | `<Paseo 中的 provider ID>/<模型 ID>`，只在第一个 `/` 处拆分 |
+| `modeId` | agent 的模式。必须选不会停下来等待批准的模式；没有模式的 agent 不写 |
+| `featureValues` | agent 的功能开关，目前只有 OpenCode 需要 |
+| `thinkingOptionId` | 可选，思考强度，可用值取决于 agent 和模型 |
+
+| agent | `provider` 写法 | 无人值守的设置 | 思考强度 |
+| --- | --- | --- | --- |
+| Claude Code | `claude/<模型 ID>` | `"modeId": "bypassPermissions"` | 取决于模型 |
+| Codex | `codex/<模型 ID>` | `"modeId": "full-access"` | 取决于模型 |
+| OpenCode | `opencode/<上游>/<模型 ID>` | `"modeId": "build"` 加 `"featureValues": { "auto_accept": true }` | 取决于模型（variant） |
+| Pi | `pi/<上游>/<模型 ID>` | 不写 `modeId`（Pi 没有模式，也不请求批准） | `off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max` |
+
+以上来自 Paseo 0.11.2 源码，以你的 daemon 实际返回为准（`npm run smoke -- check` 或 `/req-doctor`）。
+
+- **Claude Code**：其他模式（`default`、`acceptEdits`、`auto`）都可能停下来等待批准，`plan` 不能改文件，都不适合流水线。
+- **OpenCode**：模型 ID 带上游前缀，如 `anthropic/...`、`openai/...`。模式就是 OpenCode 中定义的 primary agent，默认 `build` 可以改文件和执行命令。不开 `auto_accept` 的话，执行命令时会停下来等待批准。
+- **Pi**：写了 `modeId` 会被 daemon 拒绝。只有装了会弹出确认的 Pi 扩展时，才可能停下来等待。
+
+混用示例：
+
+```json
+"agents": {
+  "builder":  { "provider": "claude/<模型 ID>", "modeId": "bypassPermissions" },
+  "reviewer": { "provider": "opencode/openai/<模型 ID>", "modeId": "build", "featureValues": { "auto_accept": true } }
+}
+```
+
+### 作为聊天 agent（使用者对话的那一个）
+
+| agent | 读取 skill 的位置 | 如何触发 |
+| --- | --- | --- |
+| Claude Code | `~/.claude/skills` | `/req 我想……` |
+| OpenCode | `~/.agents/skills`（也读 `~/.claude/skills`） | `/req 我想……`；命令列表中没有时直接说"用 req 帮我……" |
+| Pi | `~/.agents/skills` | `/skill:req 我想……` |
+| Codex | `~/.agents/skills` | 直接说"用 req 帮我……"，或用 Codex 点名 skill 的方式 |
+
+聊天 agent 需要能执行命令和访问本机网络（流水线要连接 daemon）。用 Codex 做聊天 agent 时请用 `full-access` 模式。新开的对话立即可用，已经打开的对话需要新开一个。
+
+## 5. 冒烟测试
+
+编排逻辑已在模拟环境中测试过，下面四项确认的是你的真实环境。第一次安装、更换 agent、升级 Paseo 后都建议做一遍。命令在当前版本目录中运行。
+
+| # | 测什么 | 怎么测 | 预期 |
+| --- | --- | --- | --- |
+| 1 | daemon、模型和模式 | 终端运行 `npm run smoke -- check` | 两个角色各启动一个小 agent，能写文件、能执行命令、不停下等权限 |
+| 2 | 通知回发、子 agent 挂载 | 在 Paseo 对话中让聊天 agent 执行 `npm run smoke -- notify`（先 `cd` 到版本目录） | 对话中出现"通知通道工作正常"；子 agent 列表出现"[冒烟测试] 子 agent" |
+| 3 | 回合结束后后台进程是否存活 | 让聊天 agent 执行 `npm run smoke -- detach-start` 并结束本轮；一分钟后再让它执行 `npm run smoke -- detach-check` | 显示 ✓。显示 ✗ 说明环境会终止后台进程，需要改用插件方式启动 |
+| 4 | 完整跑一遍 | 在一个测试项目的 worktree 对话中输入 `/req 在 README 末尾加一行版权声明` | 走快速档，收到进展和完成通知；功能目录中各产物齐全；工作分支上有本地提交 |
+
+第 2、3 项依赖对话提供的 `PASEO_AGENT_ID`、`PASEO_AGENT_CWD`，必须在 Paseo 对话中由聊天 agent 执行。
+
+## 6. 升级
+
+**一键升级。**
+
+```bash
+req upgrade --check        # 只看有没有新版本
+req upgrade                # 升级到最新版本（能支持本机 Paseo 的）
+req upgrade 1.8.0          # 升级到指定版本
+req upgrade --beta         # 当前是正式版时，也考虑 beta 版
+req versions               # 已安装的版本和 npm 上的版本
+```
+
+- **用 npm 安装的**（1.7.0 起）：从 npm 仓库读取已发布的版本，先读本机 Paseo daemon 的版本，跳过不支持它的 req-kit（每个版本都声明了支持的 Paseo 范围），装进 `versions/<版本>` 后切换。被跳过的版本会说明原因，例如"1.9.0 需要 Paseo >=0.12.0 <0.13.0，本机是 0.11.2"。读不到 daemon 版本时不筛选，升级后请运行 `req doctor`。
+- **用 git 安装的**：读取 git 标签，下载到 `versions/<版本>`，执行 `npm install`，再切换。公司网络只能访问内网镜像时，用 `--from <镜像地址>` 或环境变量 `REQ_KIT_REPO_URL` 指定。想改用 npm 升级时加 `--from npm`。
+- 当前是正式版时只升级到正式版；当前是 beta 时也会升级到更新的 beta。任何一步失败，当前版本不受影响。
+- 也可以按 Paseo 版本直接安装管理器：`npm i -g paseo-req-kit@paseo-0.11`（每个支持的 Paseo 小版本有一个这样的标签）。
+
+升级前后建议：
+
+1. 阅读 `CHANGELOG.md` 中两个版本之间的"升级须知"（升级完成时会给出新版本的 CHANGELOG 位置）。
+2. 运行 `req doctor --no-project`，确认当前状态正常。正在运行的流水线不用停，见下表。
+3. 升级后至少跑冒烟测试第 1 项；升级须知提到通知、后台进程或启动方式有变化时，再跑第 2、3 项；主版本升级跑全部四项。
+4. 把"使用者会看到的变化"转给使用者，提醒新需求请开新对话。
+
+**手工升级**（1.2 及更早的版本还没有 `--upgrade`，从它们升级时用这种方式；或者不方便访问 GitHub 时）。以从 1.0.0 升到 1.1.0 为例，先完成上面的第 1、2 项，然后把新版本放进新的版本目录，安装依赖并启用：
+
+```bash
+git clone --branch 1.1.0 --depth 1 https://github.com/yiyisf/paseo-req-kit ~/tools/req-kit/versions/1.1.0
+cd ~/tools/req-kit/versions/1.1.0
+npm install
+node install.mjs
+```
+
+PowerShell：
+
+```powershell
+git clone --branch 1.1.0 --depth 1 https://github.com/yiyisf/paseo-req-kit "$env:USERPROFILE\tools\req-kit\versions\1.1.0"
+cd "$env:USERPROFILE\tools\req-kit\versions\1.1.0"
+npm install
+node install.mjs
+```
+
+之后同样完成上面的第 3、4 项。
+
+安装器替换各 agent 目录中带标记的 skill，把路径指向新版本，删除新版本不再包含的旧 skill，并更新启用记录。不会动：`~/.req-kit/` 下的配置和提示词覆盖、各项目仓库中的文件、不是 req-kit 安装的 skill。
+
+| 升级时的状态 | 会发生什么 |
+| --- | --- |
+| 还在聊天对齐阶段 | 对话已加载的是旧版 skill，继续使用即可；启动的是新版引擎 |
+| 流水线正在运行 | 进程已载入旧版代码，旧版本目录仍在，按旧版跑完 |
+| 已暂停、失败或等待需求方决定 | 继续时由新版引擎读取；状态格式有变化时自动迁移，原文件备份为 `state.json.bak-v<旧版本>` |
+| 已完成 | 不受影响 |
+
+## 7. 回滚
+
+```bash
+req use 1.6.0              # 切换到已安装的旧版本
+```
+
+不用 `req` 时，在旧版本目录中重新运行安装器也一样（npm 安装的版本在 `versions/<版本>/node_modules/paseo-req-kit` 中）：
+
+```bash
+cd ~/tools/req-kit/versions/1.0.0
+node install.mjs
+```
+
+这会把 skill 和引擎路径改回 1.0.0，配置不变。如果某个功能目录的状态文件已被新版迁移，旧版引擎会拒绝继续并提示：把 `state.json.bak-v<旧版本>` 恢复为 `state.json`，或者用 `--restart` 从头开始。
+
+旧版本目录建议保留到新版本稳定运行一周以上、且没有由它启动的流水线仍在运行。`node install.mjs --prune` 会列出可以删除的旧版本。
+
+## 8. 从脚本版（paseo-requirement-workflow）迁移
+
+适用于已经装了 `~/tools/requirement-pipeline` 和 `/requirement-kickoff` 的机器。
+
+| 对象 | 脚本版 | req-kit | 迁移方式 |
+| --- | --- | --- | --- |
+| 入口 | `/requirement-kickoff` | `/req` | 安装器替换旧的 skill；1.x 期间保留同名的引导入口，提示改用 `/req` 并转交 |
+| 本机配置 | `~/tools/requirement-pipeline/pipeline.config.json` | `~/.req-kit/config.json` | `node install.mjs --import-legacy ~/tools/requirement-pipeline`，同时导入 `prompts.local/`；顶层 `rounds` 继续有效 |
+| 项目配置 | `.requirement-pipeline.json`、`.requirement-pipeline/` | 同名同位置 | 无需迁移 |
+| 功能目录 | `docs/features/<日期>-<名称>/` | 同左 | 无需迁移；没有 `version` 字段的状态文件按第 1 版读取 |
+| 术语文件 | `CONTEXT.md` | `GLOSSARY.md` | 继续读取 `CONTEXT.md`，新术语写入 `GLOSSARY.md` |
+| 依赖的外部 skill | `grilling`、`domain-modeling` | 不再需要 | 可以保留，也可以自行卸载 |
+
+建议顺序：
+
+1. 等脚本版启动的流水线跑完（或记下它们，迁移后用新版续跑）。
+2. 按第 3 节取得程序并 `npm install`，然后运行 `node install.mjs --import-legacy ~/tools/requirement-pipeline`。
+3. 跑冒烟测试第 1–3 项。
+4. 告诉使用者入口改为 `/req`。
+5. 一周后删除 `~/tools/requirement-pipeline`。
+
+## 9. Paseo 或 agent 升级之后
+
+运行 `/req-doctor`（或 `node bin/req-doctor.mjs`），确认 SDK 版本在支持范围内、配置中的模型和模式仍然存在；然后跑冒烟测试第 1–3 项。有失败时，先看 req-kit 是否已有适配的新版本；没有的话，把输出反馈给维护者，并暂时回退 Paseo 或 agent 的版本。
+
+## 10. 卸载
+
+```bash
+node ~/tools/req-kit/versions/<当前版本>/install.mjs --uninstall
+```
+
+这会删除 req-kit 安装的 skill 和 `req` 命令。确认不再使用后，再手工删除 `~/tools/req-kit` 和 `~/.req-kit`。各项目中的配置文件和功能目录保留，它们本身就是文档。
+
+## 11. 安全提示
+
+- 步骤 agent 以免确认模式运行，可以在本机执行命令。仓库和本机环境变量中不要放生产凭据；最好用专门的开发机或虚拟机运行 daemon。
+- 流水线只做本地提交，合并和上线始终由人决定。
+
+## 12. 接入企业内部 IM（可选）
+
+流水线默认只把消息发回发起的对话。希望"需要你决定""开发中断""已完成"等时刻在企业 IM 中也收到时，需要自己实现一个通知模块（req-kit 不内置任何 IM）：
+
+1. 把安装目录中的 `notifiers/im-template.mjs` 复制到 `~/.req-kit/notifiers/im.mjs`，按其中的 TODO 实现发送（通常是向 IM 的机器人 webhook 发一个 HTTP 请求）。口令放在环境变量中，不要写进文件。
+2. 在 `~/.req-kit/config.json`（或团队配置）中加上：
+
+   ```json
+   "notifiers": [
+     { "module": "~/.req-kit/notifiers/im.mjs", "events": ["blocked", "failed", "completed"], "options": { "webhook": "https://…" } }
+   ]
+   ```
+
+3. 运行 `req notify-test`（可加 `--type blocked` 等）发一条测试消息。
+
+事件的类型和字段见 [contracts/notifier-event.md](../../contracts/notifier-event.md)。通知失败只记日志，不影响流水线。项目配置（`.requirement-pipeline.json`）中的 `notifiers` 会被忽略。
+

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

@@ -0,0 +1,85 @@
+# 维护者指南
+
+面向维护 req-kit 本身的人：改提示词和 skill、发布新版本、处理复盘提交的问题。
+
+## 1. 改动之前
+
+- 先看 [SCOPE.md](../../SCOPE.md) 和 [.out-of-scope/](../../.out-of-scope/)：新提议须服务于"帮助非专职开发的同事把一个需求从对齐做到可验收"，至少有两个真实场景，并且无法通过项目配置或项目说明解决。
+- 改动已有的设计决定（[docs/adr/](../adr/)）时，新增一条 ADR 说明理由，并在旧的一条中注明被哪条取代。
+- 改动文件格式（spec、状态文件、结果文件、决策记录等）时，同时更新 [contracts/](../../contracts/)、代码和测试；状态文件的格式变化要加迁移（见 `contracts/state.md`）。
+
+## 2. 改 skill 和提示词的规则
+
+- **入口不调用入口**（ADR 0008）。`/req`、`/req-setup`、`/req-doctor`、`/req-retro` 之间只能"告诉用户去运行"，不能互相加载。
+- **路径用占位符**：skill 中引用安装目录内的文件写 `{{REQ_KIT_ROOT}}/...`，启动命令写 `{{PIPELINE_LAUNCHER}}`，版本号写 `{{REQ_KIT_VERSION}}`。安装器会替换它们；`npm test` 会检查引用的文件都存在。
+- **frontmatter** 只用 `name`、`description`，agent 专属的放在 `metadata` 下；`description` 中不要出现半角的 `: `。
+- **手册**（`skills/req/playbooks/*.md`）开头必须有"## 步骤"编号列表，`/req` 会把它原样放进待办列表；新增手册要加进 `/req` 的路由表。
+- **原则**：增加一条原则需要至少两次真实失误作为依据，并且无法用 CI 或配置解决；总数不超过 10 条。原则的一句话版本写进 `principles/INDEX.md`，它同时被聊天和每个步骤的提示词使用。
+- **措辞**：读者是有技术背景、但不读代码的使用者（测试、产品、项目经理）。讲需求和结果，不讲代码实现。
+
+## 3. 验证改动
+
+| 改了什么 | 至少要做 |
+| --- | --- |
+| 引擎代码 | `npm test`、`npm run typecheck` |
+| 步骤提示词 | 上面两项 + `npm run eval`（至少跑受影响的用例），与上一次的结果对比 |
+| 入口、手册、方法 skill、原则 | `npm test` + 对话评估中受影响的剧本（`evals/conversation/`） |
+| 安装器 | `npm test`（在临时 HOME 中测试），并在 Windows 上实际装一次 |
+| 评估用例 | `npm run eval:self-check`（参考实现必须通过隐藏验收） |
+
+提示词改动以评估结果为准：如实率（不夸大）不能下降；隐藏验收通过率、用时、轮次与上一次对比，变差时说明原因。
+
+## 4. 发布
+
+版本号遵循语义化版本，标签**不带 `v` 前缀**（例如 `1.2.0`、`1.3.0-beta.1`）。
+
+1. **确定版本号**：修订号（修复、措辞调整）、次版本号（新手册、新配置项，完全兼容）、主版本号（文件格式、配置字段或入口名称的不兼容变化）。同一主版本内，配置字段只增不删（废弃的继续生效并在 `/req-doctor` 中提示），文件格式只做可以自动迁移的变更。
+2. **更新 `package.json` 的 `version`**；Paseo 支持范围有变化时同时更新 `reqKit.paseo`，并复查 `engine/src/paseo-runtime.ts` 开头列出的 SDK 用法（其中工作区脚本用的是内部接口，见 ADR 0017）。
+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`，标签自动打上**：`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 上已有的包的设置页里配置，所以第一个版本在本机手工发布一次，不需要生成任何口令：
+
+1. npmjs.com 账号开启双重验证（2FA）；本机 `npm login`。
+2. 等版本标签的工作流跑到"Publish"（第一次会因为包不存在而失败，前面的测试已经通过），从仓库取出这个标签：`git checkout <版本>`，执行 `npm publish --tag beta --provenance=false`（正式版去掉 `--tag beta`）。本机不能生成来源证明，所以要关掉 provenance；以后由工作流发布的版本会自动带上。
+3. 在 npmjs.com 打开包的 Settings → Trusted publishing，选 GitHub Actions：Organization or user 填 `yiyisf`，Repository 填 `paseo-req-kit`，Workflow filename 填 `release.yml`，Environment 留空，允许的操作勾上 `npm publish`（和 `npm dist-tag`）。保存后 2 天内要有一次成功的发布，否则配置失效需要重建。
+4. 到 GitHub Actions 中重新运行这个标签的 release 工作流：版本已经在 npm 上，会跳过发布，只建 GitHub Release。之后的版本推送标签即可自动发布。
+
+不建议为发布生成长期口令：npm 正在收紧可以跳过 2FA 的口令，计划 2027 年 1 月起不再允许它们直接发布。工作流仍然支持仓库 Secrets 中的 `NPM_TOKEN`（有就用），供无法用可信发布的内网仓库使用。
+
+**重新发布已有的标签**：GitHub → Actions → release → Run workflow，填版本标签（如 `1.7.0-beta.2`）。用的是当前 main 上的流程、标签上的代码；手机网页也能操作。npm 发布失败时仍会建好 Release 和 `.tgz`，最后再报错。
+
+**检查**：`ci.yml` 在每次推送到 main 和每个 PR 时运行测试、类型检查、评估自检和打包检查。推送版本标签前先确认它是绿的。`paseo-<小版本>` 标签的设置需要一个口令：在仓库的 Secrets 中加 `NPM_TOKEN`（自动化口令）；不加时工作流会提示手工执行 `npm dist-tag add`。`req upgrade` 按各版本声明的 `reqKit.paseo` 选择版本，不依赖这个标签。
+
+**维护分支**：Paseo 出了新的小版本、`main` 跟进之后，从上一个支持线的最后版本拉出 `release/paseo-<小版本>` 分支，只合修复，在那里打补丁版本的标签（工作流会把它标成 `paseo-<小版本>`）；同时在 `package.json` 中加 `"publishConfig": { "tag": "paseo-<小版本>" }`，避免补丁版本抢走 `latest`。只维护最新和上一条支持线。
+
+**企业私有仓库**：只代理 npmjs 的不用做什么。需要单独发布到内网仓库时，下载 Release 上的 `.tgz`，执行 `npm publish paseo-req-kit-<版本>.tgz --registry <内网地址> --tag <同名标签>`，再在内网仓库设置相同的 `paseo-<小版本>` 标签。
+
+没有使用 changesets 等发布工具（见 ADR 0013）：发布频率低，CHANGELOG 由人写更贴近使用者。
+
+**对外约定**：通知事件（`contracts/notifier-event.md`）由各团队自己的 IM 模块读取，同一 `schema` 内只增加字段；`req` 的子命令和参数会被写进各团队的使用说明，改名时保留旧名一个主版本。
+
+## 5. 处理复盘提交的问题
+
+`/req-retro` 会把 req-kit 本身的问题写成报告草稿交给用户。收到后：
+
+1. 能复现的，先加一个评估用例或对话剧本，确认它在当前版本失败。
+2. 修改后跑同一个评估，确认修好，并且其他用例没有变差。
+3. 在 CHANGELOG 中记录。
+
+## 6. 目录速查
+
+| 目录 | 内容 |
+| --- | --- |
+| `skills/` | 安装到各 agent 的 skill：入口、手册、方法、原则、旧入口的引导 |
+| `principles/INDEX.md` | 原则索引 |
+| `engine/src/` | 引擎：启动器、主流程、配置、状态与迁移、体检、评估运行器 |
+| `engine/prompts/` | 步骤提示词（含 `00-shared-context.md` 和评审小组成员的 `panel-member.md`） |
+| `engine/test/` | 引擎测试，`fake-runtime.ts` 是模拟的 Paseo |
+| `test/` | 安装器、体检、skill 的测试 |
+| `evals/` | 评估：样例仓库、用例、对话剧本 |
+| `contracts/` | 文件格式约定 |
+| `docs/adr/` | 设计决定 |