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

package/bin/req.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// The `req` command: short names for the things people do in a terminal.
+// install.mjs writes ~/.req-kit/bin/req (and req.cmd on Windows) pointing here.
+// Everything it does is also available through the full commands it prints in `req help`.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findTsxCli, layoutOf } from "./locate.mjs";
+
+const kitRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const version = JSON.parse(fs.readFileSync(path.join(kitRoot, "package.json"), "utf8")).version;
+const tsxCli = findTsxCli(kitRoot) ?? path.join(kitRoot, "node_modules", "tsx", "dist", "cli.mjs");
+const launcher = path.join(kitRoot, "bin", "start-pipeline.mjs");
+
+const HELP = `req-kit ${version}（${kitRoot}）
+
+在项目目录（或它的工作区）中运行：
+  req list                     列出这个项目的所有需求和阶段
+  req status [需求]            查看进度；只有一个需求运行过时可以不写
+  req stop <需求>              停止流水线（之后可以继续）
+  req resume <需求>            从上次中断处继续；需求改过时只处理变化的部分
+  req verify <需求> [--verify-env local|deployed] [--defects fix|handback|report]
+                               研发完成后开始测试验证（分阶段执行时）
+  req start <需求> [--profile quick|standard] [--phases gated] [--at 22:00]
+                               启动流水线（通常由 /req 在对话中启动，这里用于终端中手工启动）
+  req digest [--notify]        项目的需求总览；--notify 同时发到外部通知（如企业 IM）
+  req digest --schedule "0 9 * * 1"
+                               让 Paseo 按时间表发送需求总览（例子为每周一 9:00）；取消：req digest --cancel <ID>
+
+本机维护：
+  req doctor [--no-project]    体检：安装、配置、daemon、当前项目
+  req configure                配置向导：选择 builder 和 reviewer 用的 agent
+  req upgrade [版本] [--beta]  升级到最新版本（或指定版本），自动选能支持本机 Paseo 的版本；
+                               req upgrade --check 只看有没有新版本
+  req versions                 已安装的版本和 npm 上的版本
+  req use <版本>               切换到已安装的另一个版本（回滚）
+  req check                    检查安装状态
+  req notify-test [--type blocked|failed|completed|milestone|permission]
+                               给配置的外部通知（如企业 IM）发一条测试消息
+  req version                  显示版本和安装位置
+
+<需求> 可以写功能目录（docs/features/20261012-sms-login）、目录名，或名称中能唯一确定的一部分（sms-login）。
+在对话中的用法见 /req；完整说明见 ${path.join(kitRoot, "docs", "guide")}。`;
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function node(args) {
+  const result = spawnSync(process.execPath, args, { stdio: "inherit", windowsHide: true });
+  if (result.error) {
+    console.error(result.error.message);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
+function needTsx() {
+  if (fs.existsSync(tsxCli)) return true;
+  console.error(`依赖未安装：在 ${kitRoot} 中执行 npm install，然后运行 node install.mjs`);
+  return false;
+}
+
+/** Takes the first argument as the requirement, unless it is an option. */
+function feature(rest, required) {
+  if (rest[0] && !rest[0].startsWith("-")) return ["--feature", rest[0], ...rest.slice(1)];
+  if (required) {
+    console.error(`请写出是哪个需求，例如：req ${command} sms-login（用 req list 查看全部需求）`);
+    process.exit(2);
+  }
+  return rest;
+}
+
+const [command = "help", ...rest] = process.argv.slice(2);
+const installer = path.join(kitRoot, "install.mjs");
+const MANAGED = { setup: ["--setup"], upgrade: ["--upgrade"], use: ["--use"], versions: ["--versions"] };
+
+// Installed with `npm i -g`: this copy manages the versions under ~/tools/req-kit/versions
+// and hands every other command to the version in use.
+if (layoutOf(kitRoot).kind === "manager") {
+  if (command in MANAGED) {
+    const flags = command === "upgrade" && rest.includes("--check") ? ["--latest"] : MANAGED[command];
+    process.exit(node([installer, ...flags, ...rest.filter((a) => a !== "--check")]));
+  }
+  const kitHome = process.env.REQ_KIT_HOME?.trim() ? path.resolve(process.env.REQ_KIT_HOME.trim()) : path.join(os.homedir(), ".req-kit");
+  const active = readJson(path.join(kitHome, "active.json"));
+  const activeReq = active?.root ? path.join(active.root, "bin", "req.mjs") : null;
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(`req-kit 管理器 ${version}（${kitRoot}）`);
+    console.log(active ? `当前启用的版本：${active.version}（${active.root}）` : "还没有启用任何版本：运行 req setup");
+    process.exit(0);
+  }
+  if (!activeReq || !fs.existsSync(activeReq)) {
+    if (["help", "--help", "-h"].includes(command)) {
+      console.log(`req-kit 管理器 ${version}\n\n还没有安装任何版本。先运行：req setup\n\n其他命令：req versions、req upgrade、req use <版本>`);
+      process.exit(0);
+    }
+    console.error(active ? `当前启用的版本 ${active.version} 不在了（${active.root}）。运行 req versions 查看已安装的版本，再 req use <版本>。` : "还没有安装任何 req-kit 版本。先运行：req setup");
+    process.exit(1);
+  }
+  process.exit(node([activeReq, command, ...rest]));
+}
+
+let code;
+switch (command) {
+  case "list":
+  case "ls":
+    code = node([launcher, "--list", ...rest]);
+    break;
+  case "status":
+  case "st":
+    code = node([launcher, "--status", ...feature(rest, false)]);
+    break;
+  case "stop":
+    code = node([launcher, "--stop", ...feature(rest, true)]);
+    break;
+  case "resume":
+    code = node([launcher, "--resume", ...feature(rest, true)]);
+    break;
+  case "verify":
+    code = node([launcher, "--phase", "verify", ...feature(rest, true)]);
+    break;
+  case "start":
+    code = node([launcher, ...feature(rest, true)]);
+    break;
+  case "doctor":
+    code = node([path.join(kitRoot, "bin", "req-doctor.mjs"), ...rest]);
+    break;
+  case "configure":
+  case "config":
+    code = node([path.join(kitRoot, "install.mjs"), "--configure", ...rest]);
+    break;
+  case "upgrade":
+    code = rest.includes("--check")
+      ? node([path.join(kitRoot, "install.mjs"), "--latest", ...rest.filter((a) => a !== "--check")])
+      : node([path.join(kitRoot, "install.mjs"), "--upgrade", ...rest]);
+    break;
+  case "setup":
+  case "use":
+  case "versions":
+    code = node([installer, ...MANAGED[command], ...rest]);
+    break;
+  case "check":
+    code = node([path.join(kitRoot, "install.mjs"), "--check", ...rest]);
+    break;
+  case "digest":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "digest.ts"), ...rest]) : 1;
+    break;
+  case "notify-test":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "notify-test.ts"), ...rest]) : 1;
+    break;
+  case "version":
+  case "--version":
+  case "-v":
+    console.log(`req-kit ${version}（${kitRoot}）`);
+    code = 0;
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    console.log(HELP);
+    code = 0;
+    break;
+  default:
+    console.error(`没有 "${command}" 这个命令。\n`);
+    console.error(HELP);
+    code = 2;
+}
+process.exit(code);

package/bin/start-pipeline

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Starts the requirement pipeline in the background and returns immediately.
+# Same as bin/start-pipeline.mjs, for bash users. The skill uses the .mjs launcher,
+# which also works from PowerShell and cmd.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+TOOL_DIR="$(cd -P "$(dirname "$SOURCE")/.." && pwd)"
+TSX="$TOOL_DIR/node_modules/.bin/tsx"
+if [ ! -x "$TSX" ]; then
+  TSX="$(command -v tsx || true)"
+fi
+if [ -z "$TSX" ]; then
+  echo "未启动：找不到 tsx。请先在 $TOOL_DIR 中执行 npm install。" >&2
+  exit 2
+fi
+exec "$TSX" "$TOOL_DIR/engine/src/launch.ts" "$@"

package/bin/start-pipeline.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Shell-independent launcher: works the same from bash, PowerShell and cmd, so any
+// Paseo chat agent (Claude Code, Codex, ...) can run it with plain `node "<path>" ...`.
+// Inside a Paseo chat it reads the chat's agent ID and working directory from the
+// environment Paseo provides (PASEO_AGENT_ID, PASEO_AGENT_CWD).
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findTsxCli } from "./locate.mjs";
+
+const toolDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const tsxCli = findTsxCli(toolDir) ?? path.join(toolDir, "node_modules", "tsx", "dist", "cli.mjs");
+if (!fs.existsSync(tsxCli)) {
+  console.error(`未启动：找不到 tsx。请先在 ${toolDir} 中执行 npm install。`);
+  process.exit(2);
+}
+const result = spawnSync(process.execPath, [tsxCli, path.join(toolDir, "engine", "src", "launch.ts"), ...process.argv.slice(2)], {
+  stdio: "inherit",
+  windowsHide: true,
+});
+process.exit(result.status ?? 1);

package/config.example.json

@@ -0,0 +1,101 @@
+{
+  "daemonUrl": "ws://127.0.0.1:6767/ws",
+  "daemonPasswordEnv": "PASEO_DAEMON_PASSWORD",
+  "teamConfig": null,
+  "agents": {
+    "builder": {
+      "provider": "claude/CHANGE-ME",
+      "modeId": "bypassPermissions"
+    },
+    "reviewer": {
+      "provider": "codex/CHANGE-ME",
+      "modeId": "full-access"
+    }
+  },
+  "defaultProfile": "standard",
+  "profiles": {
+    "quick": {
+      "rounds": {
+        "designReview": 1,
+        "codeReview": 1,
+        "defectFix": 1
+      },
+      "serviceStart": false
+    },
+    "standard": {
+      "rounds": {
+        "designReview": 2,
+        "codeReview": 3,
+        "defectFix": 3
+      },
+      "serviceStart": true
+    }
+  },
+  "notifyMilestones": true,
+  "notifiers": [],
+  "stepTimeoutMinutes": {
+    "design": 60,
+    "design_review": 30,
+    "design_revise": 30,
+    "implement": 240,
+    "code_review": 45,
+    "review_fix": 90,
+    "service_start": 30,
+    "verify": 120,
+    "defect_fix": 120,
+    "reverify": 90,
+    "report": 30,
+    "panel_review": 45,
+    "spec_review": 20,
+    "design_proposal": 45
+  },
+  "waitChunkSeconds": 600,
+  "permissionPollSeconds": 30,
+  "resultFollowUps": 2,
+  "attachToOriginChat": true,
+  "archiveStepAgents": false,
+  "retry": {
+    "attempts": 2,
+    "backoffSeconds": [
+      60,
+      300
+    ]
+  },
+  "paseoServices": "auto",
+  "serviceReadySeconds": 120,
+  "quotaWarnPercent": 85,
+  "specReview": "standard",
+  "designProposals": {
+    "enabled": false,
+    "profiles": [
+      "standard"
+    ],
+    "members": []
+  },
+  "browserVerify": "auto",
+  "reviewPanel": {
+    "enabled": false,
+    "steps": [
+      "design_review",
+      "code_review"
+    ],
+    "profiles": [
+      "standard"
+    ],
+    "members": []
+  },
+  "maxConcurrentPipelines": 0,
+  "waitingReminderHours": 24,
+  "autoResumeMinutes": 30,
+  "autoResumeMax": 2,
+  "watchdogMinutes": 0,
+  "phases": {
+    "mode": "continuous",
+    "verify": {
+      "environment": "local",
+      "agents": {},
+      "defects": "fix",
+      "serviceStart": null
+    }
+  }
+}

package/contracts/README.md

@@ -0,0 +1,18 @@
+# 文件格式约定
+
+这些文件同时被聊天中的 skill、流水线引擎和步骤 agent 读写。改动格式时，同时更新这里、相关代码和测试，并在 `CHANGELOG.md` 的"升级须知"中说明。
+
+| 文件 | 约定 | 格式版本 |
+| --- | --- | --- |
+| `docs/features/<目录>/spec.md` | [spec.md](spec.md) | `req-kit/spec@1` |
+| `docs/features/<目录>/.pipeline/state.json` | [state.md](state.md) | `version: 1` |
+| `docs/features/<目录>/.pipeline/results/<步骤>.json` | [result-file.md](result-file.md) | 按步骤固定字段 |
+| `decisions.tsv`、`changes.md`、`acceptance.md` 与需求总览 | [feature-files.md](feature-files.md) | 见各文件说明 |
+| `.requirement-pipeline/verify.md` | [verify.md](verify.md) | 自由格式，建议结构见文件 |
+| 外部通知（企业 IM 等）收到的事件 | [notifier-event.md](notifier-event.md) | `schema: 1` |
+
+格式版本的规则：
+
+- 同一主版本内只做可以自动迁移的变更。
+- 引擎读到旧版本的状态文件时自动迁移，原文件保留为 `state.json.bak-v<旧版本>`。
+- 读到比自己新的版本时拒绝运行，提示升级 req-kit 或恢复备份。

package/contracts/feature-files.md

@@ -0,0 +1,87 @@
+# 功能目录中由人和 /req 维护的文件
+
+除 spec.md（见 [spec.md](spec.md)）外，功能目录 `docs/features/<日期>-<名称>/` 中还有以下约定格式的文件。
+
+## decisions.tsv
+
+决策记录，由流水线各步骤追加。制表符分隔，UTF-8，第一行为表头：
+
+```text
+time	step	ref	decision	alternatives	reason	kind	needs_human
+```
+
+| 列 | 内容 |
+| --- | --- |
+| `time` | `YYYY-MM-DD HH:MM` |
+| `step` | 步骤名和轮次，如 `代码评审 第2轮` |
+| `ref` | 相关的 FR / AC / CR 编号或文件，没有写 `-` |
+| `decision` / `alternatives` / `reason` | 各一句话，不含换行和制表符 |
+| `kind` | `假设` / `取舍` / `偏离方案` / `驳回意见` / `不修复` |
+| `needs_human` | `yes` / `no`。`yes` 的行会被完成报告列入"需要你确认的决定" |
+
+## changes.md
+
+需求变更记录，由 `/req` 的"修改需求"手册追加，每次修改一节，新的在后：
+
+```markdown
+## 第 2 版（2026-10-14）
+
+- 变更内容：<改了哪些 FR / AC，新增或删除了什么>
+- 原因：<需求方给出的原因>
+- 对进度的影响：<流水线当时的状态；继续后从方案设计重新开始 / 尚未开始开发>
+- 提出人：<姓名或角色>
+```
+
+spec.md 头部的"版本"与最新一节一致。
+
+## handoff.md（提测说明）
+
+1.7.0 起由流水线研发阶段的最后一步（"提测说明"）写入并提交。分阶段执行时它是交给测试的单据，连续执行时是功能验证的输入，"只做研发"时是人工测试的依据。六节：这次改了什么（按 FR，附分支和提交范围）、怎么跑起来、自测结果、建议重点测试、已知问题和未完成项、测试需要的准备（只写在哪里取，不写口令）。测试退回后修复时追加"第 N 次提测"一节。
+
+## test-env.md（测试环境说明）
+
+1.7.0 起。在已部署的测试环境中做测试验证（`--verify-env deployed` 或配置 `phases.verify.environment`）时必须有，由 `/req` 的"开始测试验证"手册和用户一起写。流水线只使用其中列出的环境、账号和数据：
+
+```markdown
+# 测试环境：<需求名称>
+
+- 地址：https://<测试环境地址>
+- 被测版本怎么确认：<版本号接口 / 页面底部的提交号 / 部署平台上的记录>
+- 账号：<测试账号>，口令在 <环境变量 TEST_PASSWORD / 本机文件 ~/.config/xxx>（不写口令本身）
+- 可以使用的测试数据：<数据范围、可以新建和删除的数据>
+- 不能碰的：<共享数据、会触发外部通知的操作等>
+- 清理方式：<测试数据如何清理>
+```
+
+只能是测试用途的环境；不写任何生产环境的地址和凭据。
+
+## changes.md 中的"测试验证退回"
+
+1.7.0 起，测试验证按 `defects: handback` 把缺陷退回研发阶段时，流水线在 `changes.md` 末尾追加一节"<日期> 测试验证退回（第 N 次）"，来源为"测试验证"，缺陷清单在 `verification.md` 最后一轮。研发阶段随后从方案设计开始只处理这些缺陷。
+
+## acceptance.md
+
+验收记录，由 `/req` 的"验收"手册写。验收标准本身只在 spec.md 中维护，这里只记录结果：
+
+```markdown
+# 验收记录：<需求名称>
+
+- 验收结论：通过（2026-10-15） / 不通过（2026-10-15） / 进行中
+- 验收人：<姓名或角色>
+- 对照的需求版本：2
+- 对照的报告：report.md（流水线结论：已完成，可以验收）
+
+| AC | 结果 | 怎么验证的 | 备注 |
+| --- | --- | --- | --- |
+| AC-1.1 | 通过 / 不通过 / 未验 | <亲自操作 / 执行的命令> | <现象、截图路径> |
+
+## 不通过的处理
+
+- AC-2.3：<现象> → 作为缺陷处理 / 作为需求修改 / 接受现状（理由）
+```
+
+`start-pipeline --list` 读取"验收结论"一行来显示"已验收"或"验收未通过"。
+
+## 需求总览
+
+需求总览不是一个提交进仓库的文件。每个需求在自己的工作区和分支上，共用的索引文件会在合并时冲突，所以总览由 `start-pipeline --list` 现场生成：扫描这个仓库所有 worktree 中的 `docs/features/*/spec.md`、状态文件和验收记录。

package/contracts/notifier-event.md

@@ -0,0 +1,71 @@
+# 外部通知事件（notifier）
+
+流水线除了把消息发回发起的对话，还可以在关键时刻调用本机的通知模块，例如把消息转发到企业内部 IM。req-kit 只定义调用方式和事件格式，不包含任何 IM 的实现；模板见 [notifiers/im-template.mjs](../notifiers/im-template.mjs)。
+
+## 配置
+
+只能写在本机配置（`~/.req-kit/config.json`）或团队配置中，项目配置中的 `notifiers` 会被忽略（项目仓库里的代码不应该决定往哪里发消息）。
+
+```json
+"notifiers": [
+  {
+    "module": "~/.req-kit/notifiers/im.mjs",
+    "events": ["blocked", "failed", "completed"],
+    "options": { "webhook": "https://im.example.internal/hook/xxx", "tokenEnv": "IM_TOKEN" }
+  }
+]
+```
+
+| 字段 | 说明 |
+| --- | --- |
+| `module` | 通知模块的路径。相对路径相对于声明它的配置文件；`~/` 表示用户目录。 |
+| `events` | 要接收的事件类型，省略时接收全部（包括以后新增的类型）。 |
+| `options` | 原样传给模块的第二个参数。密钥不要直接写在这里，写环境变量的名字，由模块读取。 |
+
+## 模块
+
+ES 模块，默认导出（或导出名为 `notify` 的）函数：
+
+```js
+export default async function notify(event, options) { /* 发送 */ }
+```
+
+- 每个事件调用一次，可以返回 Promise。超过 15 秒没有完成按失败处理。
+- 抛出的错误和超时只记入流水线日志（"外部通知失败……不影响流水线"），不会让流水线停下或重试。
+- 模块在一次流水线运行中只加载一次；修改模块后，对之后启动或继续的流水线生效。
+- 测试：`req notify-test [--type blocked|failed|completed|milestone|permission|phase_done|digest]` 发一条带"【测试】"字样的示例事件，不需要运行流水线。
+
+## 事件格式（schema 1）
+
+```json
+{
+  "schema": 1,
+  "type": "blocked",
+  "at": "2026-10-13T08:30:00.000Z",
+  "kitVersion": "1.3.0-beta.1",
+  "feature": { "dir": "docs/features/20261012-sms-login", "name": "20261012-sms-login", "title": "短信验证码登录" },
+  "repo": "D:\\work\\shop",
+  "branch": "feature/20261012-sms-login",
+  "profile": "standard",
+  "originAgentId": "agent-id 或 null",
+  "text": "方案审核发现 1 个需要需求方决定的问题，流水线已暂停，请到发起的对话中回答。",
+  "details": { "questions": ["……"], "resumeCommand": "node \"…/start-pipeline.mjs\" … --resume" }
+}
+```
+
+`text` 是一两句可以直接发出的话；需要自己排版时用 `details`。
+
+| type | 什么时候 | details |
+| --- | --- | --- |
+| `milestone` | 方案确定、开始验证、开始修复缺陷（配置 `notifyMilestones` 为 true 时，每次尝试各一次） | `milestone`：`design-settled`、`code-reviewed`、`fixing-defects`、`handback-<n>`（1.7.0 起，测试验证第 n 次把缺陷退回研发） |
+| `blocked` | 方案审核发现需要需求方决定的问题，流水线已暂停 | `questions`（字符串数组）、`resumeCommand` |
+| `permission` | 步骤 agent 在等待权限批准 | `stepTitle`、`agentTitle`、`requests`（字符串数组） |
+| `failed` | 流水线因错误中断（已自动重试过的临时错误除外） | `stepTitle`、`reason`、`logPath`、`resumeCommand` |
+| `completed` | 流水线结束，报告已生成 | `outcome`（`completed`、`completed_with_issues`、`not_completed`）、`summary`、`reportPath`。"只做研发"时另有 `mode`（`develop-only`）和 `handoffPath`，报告是研发报告，需要人工测试 |
+| `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` |
+
+## 兼容性
+
+- 同一 `schema` 内只增加字段，不删除、不改含义；模块应忽略不认识的字段和事件类型。
+- 不兼容的变化会提升 `schema`，并在 `CHANGELOG.md` 的"升级须知"中说明。

package/contracts/result-file.md

@@ -0,0 +1,17 @@
+# 步骤结果文件
+
+每个步骤结束时写一个 JSON 对象到 `.pipeline/results/<步骤键>.json`（路径在提示词的 `<pipeline-context>` 中给出）。引擎只根据它决定下一步，不读 agent 的回复文字。缺失或格式不对时，引擎会在同一个会话里提醒补写，最多 `resultFollowUps` 次（默认 2），仍不对则判定该步骤失败。
+
+| 步骤 ID | 字段 |
+| --- | --- |
+| `design` | `has_runnable_service`: boolean |
+| `design_review` | `verdict`: `approved` \| `changes_required` \| `blocked`；为 `blocked` 时 `questions`: 非空字符串数组 |
+| `design_revise`、`implement`、`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` |
+| `report` | `outcome`: `completed` \| `completed_with_issues` \| `not_completed`；`summary`: string |
+| `panel_review`（评审小组成员，键为 `<评审步骤>-r<轮次>-p<序号>`） | `status`: `done` \| `partial`；意见写在 `<功能目录>/review-panel/<键>.md` |
+
+字段定义以 `engine/src/steps.ts` 为准；改动时同步更新各步骤提示词末尾的"结果文件"一节。

package/contracts/spec.md

@@ -0,0 +1,34 @@
+# spec.md
+
+需求说明，由 `/req`（`spec-writing` skill）按模板 `skills/spec-writing/spec-template.md` 写成，需求方确认后交给流水线。
+
+## 头部
+
+```markdown
+# <需求名称>
+
+- 状态：已确认（2026-10-12）
+- 档位：标准
+- 执行方式：连续
+- 类型：新需求
+- 版本：1
+- 格式：req-kit/spec@1
+```
+
+| 行 | 谁读 | 规则 |
+| --- | --- | --- |
+| `- 状态：` | 引擎 | 以"已确认"开头才能启动流水线。正则：`^\s*-\s*状态\s*[:：]\s*已确认` |
+| `- 档位：` | 引擎 | "快速"或"标准"（也接受 `quick` / `standard`）。没有时用配置中的 `defaultProfile` |
+| `- 执行方式：` | 引擎 | "连续"、"分阶段"或"只做研发"（也接受 `continuous` / `gated` / `develop-only`）。可以没有；没有时用配置中的 `phases.mode`，启动参数 `--phases` 优先（1.7 起） |
+| `- 类型：` | `/req` | 新需求 / 小改动 / 缺陷 |
+| `- 版本：` | `/req` | 从 1 开始，每次修改需求加 1 |
+| `- 格式：` | `/req`、引擎（将来） | `req-kit/spec@<n>`。没有这一行的旧 spec 按 `req-kit/spec@1` 处理 |
+
+## 正文中被引用的编号
+
+- 功能需求 `FR-<n>`，验收标准 `AC-<n>.<m>`，规则 `BR-<n>`，假设 `A-<n>`。
+- 流水线各步骤和最终报告按这些编号引用，编号一旦确认就不要重排；删除的需求保留编号并注明"已取消"。
+
+## 变更
+
+- spec 的内容哈希记录在状态文件中。spec 在流水线中断后被修改，续跑时从方案设计重新开始。

package/contracts/state.md

@@ -0,0 +1,44 @@
+# 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_business` 表示等待需求方决定；`phase_done`（1.7.0 起）表示研发阶段已完成、停在闸口等待测试验证。1.7 之前的引擎把 `phase_done` 当作可以继续的中断，继续时沿用研发结果、直接做验证 |
+| `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` 轮数 |
+
+`schedules[].kind` 在 1.7.0 起还可能是 `verify-start`（`--verify-at` 预约的测试验证开始）。`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,39 @@
+# .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` 偶发超时，与需求无关
+```
+
+步骤 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 列表里就能看到每一步；不会出现产物写错目录的情况。代价是必须在需求所在项目的对话中发起。