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

package/bin/req.mjs

@@ -0,0 +1,179 @@
+#!/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 approve <需求>           需求方确认了方案（方案确认点，见 preview.md），继续开发
+  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 "approve":
+    code = node([launcher, "--approve", ...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,132 @@
+{
+  "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,
+    "handoff": 30
+  },
+  "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
+    }
+  },
+  "requirementTypes": [
+    "defect",
+    "refactor",
+    "assessment"
+  ],
+  "checks": [],
+  "qualityGate": {
+    "fixAttempts": 2,
+    "timeoutMinutes": 20
+  },
+  "slices": {
+    "profiles": [
+      "standard"
+    ],
+    "max": 6
+  },
+  "relatedRepos": [],
+  "designApproval": {
+    "mode": "ui",
+    "profiles": [
+      "standard"
+    ],
+    "autoContinueHours": 0
+  },
+  "reviewAxes": {
+    "enabled": true,
+    "profiles": [
+      "standard"
+    ]
+  }
+}

package/contracts/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,117 @@
+# 功能目录中由人和 /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` 最后一轮。研发阶段随后从方案设计开始只处理这些缺陷。
+
+## preview.md 与 prototype/（给需求方确认的预览）
+
+1.8.0 起，方案确认点开启时（`designApproval`，默认标准档的界面改动）由方案设计写入，方案修订时同步更新。`preview.md` 五节：做完后你会看到什么（按操作顺序，注明 AC）、界面原型（列出 `prototype/` 中的文件和对应的状态）、接口示例（改接口时）、需要你确认的假设（影响界面、数据、权限的）、不会变的。`prototype/` 中是静态 HTML 页面，只用内联的 HTML 和 CSS，不引用外部文件、不连接服务，只用于确认，不是产品代码。需求方确认后，实现和功能验证都以它们为准。
+
+## diagnosis.md、assessment.md
+
+1.8.0 起。缺陷类型的"复现与定位"写 `diagnosis.md`：现象与复现（复现测试或脚本的位置、命令、修复前的失败输出）、根因（带代码位置）、排除的其他原因、影响面、修复思路。评估类型的"调研评估"写 `assessment.md`（代替 `design.md`）：结论摘要、现状、可选方案（含工作量的大小和主要工作项）、推荐、风险与未知、如果要做（需求草稿）。
+
+## contract.md（联合需求的接口约定）
+
+1.8.0 起，联合需求（spec 的 `- 联合开发：`）的方案设计在主仓库写入：每个接口一节，路径和方法、请求字段（类型、是否必填、取值范围）、响应字段、错误码和提示、一两组真实的请求和响应示例。方案审核通过后冻结，各仓库按它同时开发：提供接口的一边用示例写接口测试，调用的一边用示例做测试替身。主仓库的需求说明、访谈记录、方案、接口约定和预览在实现前同步到其他仓库工作区的同名功能目录并提交；其他仓库的实现、评审和缺陷处理记录写在它们自己的功能目录中。
+
+## lessons.tsv（可以变成规则的问题）
+
+1.8.0 起，完成报告从评审意见、质量门和缺陷中挑出一条项目规则就能挡住的问题写入，没有就不写。制表符分隔，UTF-8，第一行为表头：
+
+```text
+category	finding	source	rule	layer
+```
+
+| 列 | 内容 |
+| --- | --- |
+| `category` | 问题的类别，两到六个字，如"SQL 拼接"。同类问题在各个需求中沿用同一个名字 |
+| `finding` | 这次的问题，一句话 |
+| `source` | 出处，如 `CR-3`、`缺陷 D-2`、`质量门 lint` |
+| `rule` | 建议的规则，一句话 |
+| `layer` | `lint` / `类型` / `测试` / `项目说明` |
+
+`req digest` 把在两个以上需求中出现的类别列为"反复出现的问题"。已经变成规则（或决定不做）的类别写在仓库的 `.requirement-pipeline/lessons-handled.txt` 中，一行一个，`#` 之后是注释，总览不再提示它们。
+
+## acceptance.md
+
+验收记录，由 `/req` 的"验收"手册写。验收标准本身只在 spec.md 中维护，这里只记录结果：
+
+```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,72 @@
+# 外部通知事件（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|approval|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`，报告是研发报告，需要人工测试 |
+| `approval` | 1.8.0 起。方案确认点（`designApproval`）：方案已通过审核，等待需求方确认"做完后会看到什么"，还没有开始写代码 | `previewPath`（要确认的内容）、`approveCommand`（确认后继续的命令）、`resumeCommand`（修改需求后继续的命令），都在发起的对话中执行 |
+| `phase_done` | 1.7.0 起。分阶段执行时研发阶段已完成（代码已通过评审、提测说明已写好），流水线停在闸口等待测试验证。测试退回后再次修完也会发 | `handoffPath`（提测说明）、`mode`（`gated`）、`verifyCommand`（开始测试验证的命令，在发起的对话中执行）、`verifyAt`（预约的开始时间，ISO 格式，没有为 null）、`handbacks`（已退回的次数） |
+| `digest` | `req digest --notify`（或由 `req digest --schedule` 创建的 Paseo 定时任务）发送项目的需求总览，1.6.0 起。`feature.title` 为"<项目> 需求总览"，`text` 是完整的多行总览 | `features`：每个需求的 `name`、`title`、`stage`、`branch`、`updatedAt`、`usage`；`recurringLessons`（1.8.0 起）：在两个以上需求的 `lessons.tsv` 中出现的问题类别，每项 `category`、`features`、`rules` |
+
+## 兼容性
+
+- 同一 `schema` 内只增加字段，不删除、不改含义；模块应忽略不认识的字段和事件类型。
+- 不兼容的变化会提升 `schema`，并在 `CHANGELOG.md` 的"升级须知"中说明。

package/contracts/result-file.md

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

package/contracts/spec.md

@@ -0,0 +1,36 @@
+# 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 起） |
+| `- 类型：` | 引擎（1.8 起）、`/req` | 新需求 / 小改动 / 缺陷 / 重构 / 评估（也接受 `defect`、`bug`、`refactor`、`assessment`；"技术改进"同重构，"调研"同评估）。缺陷、重构、评估按各自的做法运行（`engine/prompts/types/`），配置 `requirementTypes` 可以关掉某个类型；其他写法按新需求处理 |
+| `- 联合开发：` | 引擎（1.8 起） | 这个需求还要改的其他仓库，写项目配置 `relatedRepos` 中的名称，最多两个，用顿号分开。可以没有。见 ADR 0025 |
+| `- 版本：` | `/req` | 从 1 开始，每次修改需求加 1 |
+| `- 格式：` | `/req`、引擎（将来） | `req-kit/spec@<n>`。没有这一行的旧 spec 按 `req-kit/spec@1` 处理 |
+
+## 正文中被引用的编号
+
+- 功能需求 `FR-<n>`，验收标准 `AC-<n>.<m>`，规则 `BR-<n>`，假设 `A-<n>`。
+- 每条验收标准至少带一组具体的输入和期望输出（1.8 起由 `acceptance-criteria`、需求说明审阅检查）；方案的测试直接用这些例子作为期望值。
+- 流水线各步骤和最终报告按这些编号引用，编号一旦确认就不要重排；删除的需求保留编号并注明"已取消"。
+
+## 变更
+
+- spec 的内容哈希记录在状态文件中。spec 在流水线中断后被修改，续跑时从方案设计重新开始。