paseo-req-kit 1.14.0-beta.3 → 1.14.0-beta.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 1.14.0-beta.4
+
+### 使用者会看到的变化
+
+- **代码审查**（插件需求页面上的"代码审查"，`req code-review <需求>`）：列出需求分支相对起点的全部改动（需求文档放最后、折叠），AI 代码评审的意见放在对应的代码行旁边，带级别和修复步骤的处理结果；评审人可以在任意一行写意见、把 AI 意见标为"要改 / 不用改"、写总体意见。
+- **审核人默认取自 `CODEOWNERS`**（支持 GitLab / GitHub 格式和 GitLab 的分节），按改动的文件给出，提交前可以修改，以后建合并请求时使用。
+- **退回修改**：意见写进 `code-review.md` 的"人工评审"一节（HR-1 起）和 `changes.md` 并提交，流水线开始新的一次尝试（`req review-fix`），需求说明不变、方案确认不用重来，从方案设计开始只处理这些意见，之后照常经过 AI 代码评审和验证。**评审通过**：记下评审人、审核人和评审的提交；之后又有新提交时提示需要重新评审。
+- AI 代码评审的结果文件新增 `findings`（每条意见的级别、文件、行号、问题、修复方向）；没有它的旧需求从 `code-review.md` 的 CR 条目中读取。
+
+### 升级须知
+
+- 合并请求还没有接入：等 shenbing 提供类似 `gh pr create / gh pr merge` 的命令后，用评审通过时记下的审核人建合并请求。
+- `req api status` 新增 `humanReview`；`req api review-url` 的 `--page` 新增 `code`；启动参数新增 `--review-fix`（`req review-fix <需求>`）。
+
 ## 1.14.0-beta.3
 
 ### 使用者会看到的变化

package/bin/req.mjs

@@ -31,6 +31,8 @@ const HELP = `req-kit ${version}（${kitRoot}）
                                让 Paseo 按时间表发送需求总览（例子为每周一 9:00）；取消：req digest --cancel <ID>
   req sync <需求>              把需求同步到对接的外部系统（补发失败的调用、补建卡片、更新状态）
   req review <需求>            在浏览器打开原型审查页：点选要改的地方、直接改文字，提交意见或确认方案
+  req code-review <需求>       代码审查页：看这次的改动和 AI 评审意见，在代码行上写意见，退回修改或评审通过
+  req review-fix <需求>        按代码审查页上退回的意见开始修改（插件里提交"退回修改"时自动执行）
   req try <需求> [--stop]      把做好的需求跑起来试用：给出访问地址和测试数据（--stop 停止）
   req checklist <需求>         验收清单：按验收标准逐条勾选，提交后写成验收记录
   req ui-check <网址> [--prototype <原型文件>] [--width 1280,390]
@@ -168,6 +170,12 @@ switch (command) {
   case "approve":
     code = node([launcher, "--approve", ...feature(rest, true)]);
     break;
+  case "review-fix":
+    code = node([launcher, "--review-fix", ...feature(rest, true)]);
+    break;
+  case "code-review":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "review.ts"), "--page", "code", ...rest]) : 1;
+    break;
   case "start":
     // From a card in the requirement management system (1.10): no chat needed to begin.
     if (rest.some((a) => a === "--from" || a.startsWith("--from="))) code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "card-cmd.ts"), "start", ...rest]) : 1;

package/contracts/cli-json.md

@@ -32,7 +32,7 @@
 | `req api config [--repo <目录>] [--machine]` | 1.12 起。`{ sources, ignored, error, repo, groups }`：`sources` 是生效的配置文件（`layer` 为 `machine` / `team` / `project`，按叠加顺序）；`groups` 按主题分组，每项 `{ key, label, description, display, value, setBy, scope, changed }`：`display` 是用大白话写的值，`value` 中看起来像密钥的值和个人账号替换为 `••••`，`setBy` 是写了它的文件，`changed` 表示与默认值不同。配置有错误时 `error` 写明原因，值按各文件所写。`--machine` 不看项目配置 |
 | `req api set-agents --json <设置>` | 1.12 起。`{ ok, message }`。`<设置>` 是 `{ builder, reviewer, fallback }`（`fallback` 可以为 null），检查后写入本机配置的 `agents`，原文件备份 |
 | `req api watchdog [--by plugin\|factory] [--dry-run]` | 1.13 起。`{ checked, resumed, failed, skipped }`：把本机"运行中但后台进程已不在"的需求直接继续（`req resume`）。每个进程只继续一次，每个需求 24 小时内最多 3 次；`--by plugin` 同时记下插件在检查（流水线据此不再预约对话的定时检查） |
-| `req api review-url <需求> [--repo <目录>] [--read-only] [--page check]` | 1.13 起；`--page check`（1.14）给出同一服务上的验收清单页地址（需要 `spec.md`）。`{ url, readOnly }`：这个需求的原型审查页地址（需要时在后台启动审查页的服务）。`--read-only` 的地址只能看，不能提交意见或确认方案。需求不在本机的需求索引中或还没有 `prototype/` 时报 `not_found` |
+| `req api review-url <需求> [--repo <目录>] [--read-only] [--page check]` | 1.13 起；`--page check`（1.14）给出同一服务上的验收清单页地址（需要 `spec.md`），`--page code`（1.14）给出代码审查页地址（需要已经写过代码）。`{ url, readOnly }`：这个需求的原型审查页地址（需要时在后台启动审查页的服务）。`--read-only` 的地址只能看，不能提交意见或确认方案。需求不在本机的需求索引中或还没有 `prototype/` 时报 `not_found` |
 
 `<需求>` 的写法与 `req status` 相同：功能目录、目录名或名称中能唯一确定的一部分。需求在为它新建的工作区中开发时，`--repo` 写对话所在的目录或那个工作区都可以。
 

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

@@ -97,6 +97,14 @@ req-kit 帮你把一个需求从"我想要……"做到"可以验收"：你在 P
 
 然后说"我要验收"。AI 会按验收标准一条一条带你核对：告诉你怎么操作、应该看到什么；能用命令验证的给出命令，你可以自己执行。每条结果记入功能目录的 `acceptance.md`。
 
+**代码审查（1.14 起，给开发同事和评审人）。** 需求页面上点**"代码审查"**（终端里是 `req code-review <需求>`），代码审查页在 Paseo 里打开：
+
+- 列出这次改动的全部文件（相对需求分支的起点，需求文档排在最后、默认折叠），上面是提测说明里"这次改了什么"。
+- AI 代码评审的每条意见放在它说的那一行旁边，标着级别（阻塞 / 重要 / 建议）和修复步骤的处理结果（已修复、判为不成立、决定不修复）；可以标**要改**或**不用改**，补一句话。
+- 点任意一行代码写意见；最下面可以写总体意见。
+- **审核人**默认取自仓库的 `CODEOWNERS`（按改动的文件），提交前可以改；以后建合并请求时会用它。
+- **退回修改**：意见写进 `code-review.md` 的"人工评审"一节（HR-1 起）和 `changes.md`，流水线随即开始新的一次尝试，需求说明不变，从方案设计开始只处理这些意见，改完再经过 AI 代码评审和验证，进展发回需求的对话。**评审通过**：记下评审人和审核人；之后代码又有改动时，页面会提示需要重新评审。
+
 **在插件里自己验收（1.14 起）。** 需求页面上点**"验收清单（可一键试用）"**（终端里是 `req checklist <需求>`），验收清单在 Paseo 里打开：
 
 - 每条验收标准写着前置条件、怎么操作、应该看到什么，以及流水线的验证结果；流水线没验证或没通过的排在最前面，报告里"需要你确认的决定"也列在后面请你表态。

package/engine/prompts/06-code-review.md

@@ -49,6 +49,10 @@
 6. **评审意见**：按级别排列
 7. **处理记录**：留空，由下一步填写
 
+## 人工评审意见
+
+`code-review.md` 中有"人工评审"一节、列出 HR-1、HR-2… 时，那是评审人在插件的代码审查页上提出的意见，这一次尝试就是为了处理它们。逐条核对是否已经解决：没有解决的按"重要"重新提出（在 CR 意见里注明对应的 HR 编号）；评审人的意见与 spec 冲突时，按 spec 判断，并写明冲突、记入 `decisions.tsv`（`needs_human` 写 `yes`）。
+
 ## 第 2 轮及以后
 
 上一轮的意见已经由修复步骤处理，处理记录在 `code-review.md` 中。这一轮：
@@ -60,11 +64,18 @@
 ## 结果文件
 
 ```json
-{ "verdict": "pass" }
+{
+  "verdict": "changes_required",
+  "findings": [
+    { "id": "CR-1", "severity": "阻塞", "file": "src/order/export.ts", "line": 42, "title": "导出没有校验权限，普通用户也能导出全部订单", "suggestion": "调用 checkPermission('order:export')" }
+  ]
+}
 ```
 
 - `verdict`，二选一：
   - `pass`：没有尚未解决的"阻塞"或"重要"级别意见。
   - `changes_required`：存在尚未解决的"阻塞"或"重要"级别意见，接下来会执行评审问题修复。
 
+- `findings`：这一轮提出的每条意见（和 `code-review.md` 中的 CR 编号一致），给 Paseo 插件的代码审查页使用：人在改动的代码旁边看到它们，决定要不要改。`severity` 写"阻塞"、"重要"、"建议"或"待核实"；`file` 是相对仓库根目录的路径，`line` 是改动后文件中的行号（不确定就省略）；`title` 一句话说清问题，`suggestion` 一句话说修复方向。没有意见时写空数组。
+
 代码改动不存在，或者无法确定评审范围时，选择 `changes_required` 并在结论里说明情况。

package/engine/prompts/incremental.md

@@ -20,3 +20,5 @@
 - **完成报告**：在开头说明这是第几次尝试、因为什么变化，验收对照表中标出哪些 AC 是这次新增或修改的。
 
 上一次没有写过代码时（`<pipeline-context>` 中"上一次是否已经写过代码：否"），实现类步骤按正常方式进行，只是方案设计要在已有的 `design.md` 基础上修订。
+
+**人工代码评审退回的**（`changes.md` 最后一节的来源是"人工代码评审"）：这次要处理的是 `code-review.md` 中最后一个"人工评审"小节里的 HR-1、HR-2…意见，需求说明没有变。方案只写针对这些意见的改法；实现逐条处理，并在 `implementation.md` 中逐条写明每个 HR 怎么改的（或为什么不改，记入 `decisions.tsv`，`needs_human` 写 `yes`）；不要借机做意见之外的改动。

package/engine/src/api.ts

@@ -27,6 +27,7 @@ import { defaultConfigPath, KIT_ROOT, kitVersion } from "./locations.js";
 import { configView } from "./config-view.js";
 import { pruneIndex, readIndex, registerRequirement, requirementKey } from "./records.js";
 import { listWorktreeRecords } from "./worktree.js";
+import { readHumanReview } from "./code-review.js";
 import { isAlive, type PipelineState, readState, statePath, type StepRecord } from "./state.js";
 import { parsePeriod, summarizeRuns } from "./stats.js";
 import { readRuns, runsFile } from "./records.js";
@@ -376,12 +377,21 @@ export function apiStatus(repoArg: string, feature: string) {
     steps: state ? state.history.map((h) => stepJson(h, state)) : [],
     // 1.13: what to expect, from this machine's completed requirements of the same profile.
     estimate: estimateOf(state),
+    // 1.14: the person's code review (plugin's code review page).
+    humanReview: humanReviewOf(repo, featureDir),
     gate: state?.gate ?? null,
     external: Object.entries(state?.external ?? {}).map(([name, r]) => ({ name, id: r.id, url: r.url, status: r.status, syncedAt: r.syncedAt, pending: r.pending.length, lastError: r.pending.at(-1)?.error ?? null })),
     joint: (state?.joint ?? []).map((j) => ({ name: j.name, slug: j.slug, repo: j.repo, sourceRepo: j.sourceRepo, branch: j.branch, workspaceId: j.workspaceId, gate: j.gate ?? null })),
   };
 }
 
+function humanReviewOf(repo: string, featureDir: string) {
+  const r = readHumanReview(path.join(repo, featureDir));
+  if (!r) return null;
+  const head = spawnSync("git", ["rev-parse", "HEAD"], { cwd: repo, encoding: "utf8", windowsHide: true }).stdout?.trim() || null;
+  return { status: r.status, reviewer: r.reviewer, at: r.at, reviewers: r.reviewers, items: r.items.length, stale: r.status === "approved" && !!head && r.head !== head, consumedAttempt: r.consumedAttempt };
+}
+
 function estimateOf(state: PipelineState | null) {
   if (!state || state.status === "completed") return null;
   const t = typical(state.profile ?? "standard");
@@ -580,15 +590,17 @@ export function apiMain(argvIn: string[], cwd = process.cwd()): unknown {
       const feature = need("需求");
       const readOnly = flag(argv, "--read-only");
       // 1.14 --page check: the acceptance checklist page of the same server.
-      const page = option(argv, "--page") === "check" ? "check" : "prototype";
+      const pageArg = option(argv, "--page");
+      const page = pageArg === "check" ? "check" : pageArg === "code" ? "code" : "prototype";
       const { repo: r, featureDir } = locate(repo, feature);
       return import("./review.js").then(async ({ ensureReviewServer, keyOf, reviewUrl }) => {
         const key = keyOf(r, featureDir);
         if (!key) throw new ApiError("not_found", `${featureDir} 不在本机的需求列表中`);
         if (page === "prototype" && !fs.existsSync(path.join(r, featureDir, "prototype"))) throw new ApiError("not_found", `${featureDir} 还没有界面原型`);
         if (page === "check" && !fs.existsSync(path.join(r, featureDir, "spec.md"))) throw new ApiError("not_found", `${featureDir} 中没有 spec.md`);
+        if (page === "code" && !["implementation.md", "code-review.md"].some((f) => fs.existsSync(path.join(r, featureDir, f)))) throw new ApiError("not_found", `${featureDir} 还没有写代码，没有可以审查的改动`);
         const url = reviewUrl(await ensureReviewServer(), key, readOnly);
-        return { url: page === "check" ? `${url}check/` : url, readOnly };
+        return { url: page === "check" ? `${url}check/` : page === "code" ? `${url}code/` : url, readOnly };
       });
     }
     default:

package/engine/src/cli-args.ts

@@ -56,6 +56,7 @@ export function parseLaunchArgs(argv: string[]): LaunchArgs {
       list: { type: "boolean", default: false },
       "card-fields": { type: "boolean", default: false },
       track: { type: "boolean", default: false },
+      "review-fix": { type: "boolean", default: false },
       "spec-review": { type: "boolean", default: false },
       worktree: { type: "boolean", default: false },
       "source-repo": { type: "string" },
@@ -118,7 +119,7 @@ export function parseLaunchArgs(argv: string[]): LaunchArgs {
     repo: path.resolve(values.repo ?? process.env.PASEO_AGENT_CWD ?? process.cwd()),
     featureDir: values.feature ?? "",
     originAgentId: origin ? origin : null,
-    resume: (values.resume ?? false) || phase === "verify" || (values.approve ?? false),
+    resume: (values.resume ?? false) || phase === "verify" || (values.approve ?? false) || (values["review-fix"] ?? false),
     restart: values.restart ?? false,
     configPath: values.config ? path.resolve(values.config) : null,
     profile: (profile as ProfileName | undefined) ?? null,
@@ -127,6 +128,7 @@ export function parseLaunchArgs(argv: string[]): LaunchArgs {
     list: values.list ?? false,
     cardFields: values["card-fields"] ?? false,
     track: values.track ?? false,
+    reviewFix: values["review-fix"] ?? false,
     specReview: values["spec-review"] ?? false,
     worktree: values.worktree ?? false,
     sourceRepo: values["source-repo"] ? path.resolve(values["source-repo"]) : null,
@@ -210,6 +212,7 @@ export function launchArgv(args: LaunchArgs): string[] {
   if (args.profile) out.push("--profile", args.profile);
   if (args.resume) out.push("--resume");
   if (args.restart) out.push("--restart");
+  if (args.reviewFix) out.push("--review-fix");
   if (args.sourceRepo) out.push("--source-repo", args.sourceRepo);
   if (args.workspaceId) out.push("--workspace-id", args.workspaceId);
   if (args.specReview) out.push("--spec-review");

package/engine/src/code-review.ts

@@ -0,0 +1,419 @@
+// Code review in the plugin (1.14): the requirement's change as a diff, the AI review's findings
+// placed on the lines they are about, and a person's review on top: comments on lines, "要改" /
+// "不用改" on each AI finding, reviewers (from CODEOWNERS, editable), then "退回修改" (a new
+// incremental attempt handles the comments) or "评审通过" (recorded for the merge request).
+// Plain git and file parsing, no model.
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { section } from "./checklist.js";
+import { ownersFor, readCodeowners } from "./codeowners.js";
+import { KIT_ROOT } from "./locations.js";
+import { isAlive, readState, statePath } from "./state.js";
+import { readWorktreeRecord } from "./worktree.js";
+
+export interface DiffLine {
+  /** "+" added, "-" removed, " " context. */
+  t: "+" | "-" | " ";
+  o: number | null;
+  n: number | null;
+  s: string;
+}
+
+export interface DiffFile {
+  path: string;
+  oldPath: string | null;
+  status: "added" | "deleted" | "modified" | "renamed";
+  additions: number;
+  deletions: number;
+  binary: boolean;
+  /** The requirement's own documents (spec, design, …): shown last, folded. */
+  doc: boolean;
+  hunks: Array<{ header: string; lines: DiffLine[] }>;
+  /** Too big to show whole. */
+  truncated: boolean;
+}
+
+export type Severity = "阻塞" | "重要" | "建议" | "待核实";
+
+export interface Finding {
+  id: string;
+  round: number;
+  severity: Severity;
+  file: string | null;
+  line: number | null;
+  title: string;
+  suggestion: string | null;
+  /** What the fix step recorded: fixed, rejected (不成立), wontfix (不修复), or open. */
+  status: "open" | "fixed" | "rejected" | "wontfix";
+}
+
+export interface HumanItem {
+  id: string;
+  file: string | null;
+  line: number | null;
+  text: string;
+  /** The AI finding it takes up, if any. */
+  finding: string | null;
+}
+
+export interface HumanReview {
+  status: "approved" | "changes_requested";
+  at: string;
+  reviewer: string;
+  reviewers: string[];
+  /** The commit that was reviewed. */
+  head: string | null;
+  items: HumanItem[];
+  note: string;
+  /** For changes_requested: the attempt that took the comments up (null until a run starts). */
+  consumedAttempt: number | null;
+}
+
+const MAX_LINES_PER_FILE = 3000;
+const MAX_LINES_TOTAL = 20000;
+
+function git(cwd: string, ...args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
+  } catch {
+    return null;
+  }
+}
+
+function read(file: string): string {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** Where the requirement's change starts: the fork point from the branch it was cut from. */
+export function baseOf(repo: string, featureDir: string): { ref: string | null; commit: string | null } {
+  const state = readState(statePath(repo, featureDir));
+  const source = state?.worktree?.sourceRepo ?? null;
+  const recorded = source ? readWorktreeRecord(source, featureDir)?.baseRef ?? null : null;
+  const branch = (git(repo, "rev-parse", "--abbrev-ref", "HEAD") ?? "").trim();
+  const remoteHead = (git(repo, "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD") ?? "").trim();
+  const candidates = [recorded, remoteHead || null, "main", "master", "origin/main", "origin/master"].filter((x): x is string => !!x && x !== branch);
+  for (const ref of candidates) {
+    const mb = (git(repo, "merge-base", "HEAD", ref) ?? "").trim();
+    const head = (git(repo, "rev-parse", "HEAD") ?? "").trim();
+    if (mb && mb !== head) return { ref, commit: mb };
+  }
+  // On the base branch itself, or no common history: the baseline the implementation wrote down.
+  const baseline = /基线提交[^0-9a-f]{0,40}([0-9a-f]{7,40})/.exec(read(path.join(repo, featureDir, "implementation.md")))?.[1] ?? null;
+  return { ref: null, commit: baseline && git(repo, "cat-file", "-e", `${baseline}^{commit}`) !== null ? baseline : null };
+}
+
+/** `git diff` output as files and hunks. */
+export function parseDiff(text: string, featureDir: string): DiffFile[] {
+  const files: DiffFile[] = [];
+  let file: DiffFile | null = null;
+  let hunk: DiffFile["hunks"][number] | null = null;
+  let o = 0;
+  let n = 0;
+  let total = 0;
+  let inFile = 0;
+  const unquote = (p: string) => p.replace(/^"|"$/g, "").replace(/^[ab]\//, "");
+  for (const line of text.split("\n")) {
+    if (line.startsWith("diff --git ")) {
+      const m = /^diff --git (?:"?a\/(.+?)"?) (?:"?b\/(.+?)"?)$/.exec(line);
+      const p = m ? m[2] : line.slice(11);
+      file = { path: p, oldPath: null, status: "modified", additions: 0, deletions: 0, binary: false, doc: p === featureDir || p.startsWith(`${featureDir}/`), hunks: [], truncated: false };
+      files.push(file);
+      hunk = null;
+      inFile = 0;
+      continue;
+    }
+    if (!file) continue;
+    if (line.startsWith("new file mode")) file.status = "added";
+    else if (line.startsWith("deleted file mode")) file.status = "deleted";
+    else if (line.startsWith("rename from ")) {
+      file.status = "renamed";
+      file.oldPath = line.slice("rename from ".length);
+    } else if (line.startsWith("Binary files ")) file.binary = true;
+    else if (line.startsWith("+++ ") || line.startsWith("--- ")) {
+      if (line.startsWith("+++ ") && line !== "+++ /dev/null") file.path = unquote(line.slice(4));
+    } else if (line.startsWith("@@")) {
+      const m = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@(.*)$/.exec(line);
+      o = m ? Number(m[1]) : 0;
+      n = m ? Number(m[2]) : 0;
+      hunk = { header: line, lines: [] };
+      file.hunks.push(hunk);
+    } else if (hunk && (line.startsWith("+") || line.startsWith("-") || line.startsWith(" "))) {
+      const t = line[0] as DiffLine["t"];
+      if (t === "+") file.additions++;
+      if (t === "-") file.deletions++;
+      if (inFile >= MAX_LINES_PER_FILE || total >= MAX_LINES_TOTAL) {
+        file.truncated = true;
+        continue;
+      }
+      hunk.lines.push({ t, o: t === "+" ? null : o, n: t === "-" ? null : n, s: line.slice(1) });
+      if (t !== "+") o++;
+      if (t !== "-") n++;
+      inFile++;
+      total++;
+    }
+  }
+  // Code first, then the requirement's documents.
+  return [...files.filter((f) => !f.doc), ...files.filter((f) => f.doc)];
+}
+
+const SEVERITIES: Array<[RegExp, Severity]> = [
+  [/阻塞|blocker|critical|high/i, "阻塞"],
+  [/重要|major|medium/i, "重要"],
+  [/待核实|unverified|unsure/i, "待核实"],
+  [/建议|minor|low|nit|suggest/i, "建议"],
+];
+
+function severityOf(text: unknown): Severity {
+  const s = String(text ?? "");
+  for (const [re, v] of SEVERITIES) if (re.test(s)) return v;
+  return "重要";
+}
+
+function locationOf(text: string): { file: string | null; line: number | null } {
+  const m = /([\w@./\\-]+\.[A-Za-z0-9]+)(?::(\d+))?/.exec(text);
+  return { file: m ? m[1].replace(/\\/g, "/") : null, line: m?.[2] ? Number(m[2]) : null };
+}
+
+/** The fix step's record for each CR: fixed / rejected / won't fix. */
+function statuses(review: string): Map<string, Finding["status"]> {
+  const out = new Map<string, Finding["status"]>();
+  const lines = review.split(/\r?\n/);
+  let inRecord = false;
+  for (const line of lines) {
+    if (/^#{1,6}\s/.test(line)) inRecord = /处理记录/.test(line);
+    if (!inRecord) continue;
+    for (const m of line.matchAll(/CR-(\d+)/g)) {
+      const id = `CR-${m[1]}`;
+      if (/不成立|驳回|不认可/.test(line)) out.set(id, "rejected");
+      else if (/不修复|暂不|以后再|不改/.test(line)) out.set(id, "wontfix");
+      else if (/已修复|修复|已改|已处理|fixed/i.test(line)) out.set(id, "fixed");
+    }
+  }
+  return out;
+}
+
+/**
+ * The AI review's findings: the structured ones the review step put in its result file
+ * (`findings`), or, from older runs, the CR items of code-review.md.
+ */
+export function aiFindings(repo: string, featureDir: string): { findings: Finding[]; rounds: Array<{ round: number; verdict: string }> } {
+  const state = readState(statePath(repo, featureDir));
+  const review = read(path.join(repo, featureDir, "code-review.md"));
+  const status = statuses(review);
+  const rounds: Array<{ round: number; verdict: string }> = [];
+  const findings: Finding[] = [];
+  const seen = new Set<string>();
+  for (const [key, value] of Object.entries(state?.results ?? {})) {
+    const m = /^code_review(?:-r(\d+))?$/.exec(key);
+    if (!m) continue;
+    const round = Number(m[1] ?? 1);
+    rounds.push({ round, verdict: String(value.verdict ?? "") });
+    const list = Array.isArray(value.findings) ? (value.findings as Array<Record<string, unknown>>) : [];
+    list.forEach((f, i) => {
+      if (!f || typeof f !== "object") return;
+      const title = String(f.title ?? f.problem ?? f.issue ?? f.description ?? "").trim();
+      if (!title) return;
+      const id = String(f.id ?? `CR-${round}.${i + 1}`).trim();
+      if (seen.has(id)) return;
+      seen.add(id);
+      const loc = typeof f.file === "string" ? { file: f.file.replace(/\\/g, "/"), line: Number.parseInt(String(f.line ?? ""), 10) || null } : locationOf(String(f.location ?? ""));
+      findings.push({ id, round, severity: severityOf(f.severity ?? f.level), file: loc.file, line: loc.line, title: title.slice(0, 600), suggestion: typeof f.suggestion === "string" ? f.suggestion.slice(0, 600) : typeof f.fix === "string" ? f.fix.slice(0, 600) : null, status: status.get(id) ?? "open" });
+    });
+  }
+  rounds.sort((a, b) => a.round - b.round);
+  if (findings.length === 0 && review) {
+    // Older runs: "CR-3（重要）src/a.ts:12 …" items in code-review.md.
+    const lines = review.split(/\r?\n/);
+    let round = 1;
+    let heading = "";
+    for (let i = 0; i < lines.length; i++) {
+      if (/^#{1,6}\s/.test(lines[i])) {
+        heading = lines[i];
+        const r = /第\s*(\d+)\s*轮/.exec(heading);
+        if (r) round = Number(r[1]);
+      }
+      // Items are where they are raised, not where the fix step records them.
+      if (/处理记录|人工评审/.test(heading) && !/^#{1,6}\s+(?:\**)?CR-/.test(lines[i])) continue;
+      const m = /^\s*(?:[-*]|#{1,6}|\d+[.、])?\s*\**\s*(CR-\d+)\b\**[\s:：.、)）-]*(.*)$/.exec(lines[i]);
+      if (!m || seen.has(m[1])) continue;
+      seen.add(m[1]);
+      const block = [m[2], ...lines.slice(i + 1, i + 8).filter((l) => l.trim() && !/CR-\d+/.test(l) && !/^#{1,6}\s/.test(l))].join(" ");
+      const loc = locationOf(block);
+      const title = block.replace(/\*\*/g, "").replace(/级别[:：]\s*\S+/, "").replace(/位置[:：]\s*\S+/, "").replace(/\s+/g, " ").trim();
+      findings.push({ id: m[1], round, severity: severityOf(block), file: loc.file, line: loc.line, title: title.slice(0, 600) || m[1], suggestion: null, status: status.get(m[1]) ?? "open" });
+    }
+  }
+  return { findings, rounds };
+}
+
+const humanDir = (featureAbs: string) => path.join(featureAbs, ".pipeline", "code-review");
+
+export function readHumanReview(featureAbs: string): HumanReview | null {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(humanDir(featureAbs), "human.json"), "utf8")) as HumanReview;
+  } catch {
+    return null;
+  }
+}
+
+export function writeHumanReview(featureAbs: string, review: HumanReview): void {
+  fs.mkdirSync(humanDir(featureAbs), { recursive: true });
+  fs.writeFileSync(path.join(humanDir(featureAbs), "human.json"), JSON.stringify(review, null, 2));
+}
+
+export interface CodeReviewData {
+  title: string;
+  featureDir: string;
+  branch: string | null;
+  base: { ref: string | null; commit: string | null };
+  head: string | null;
+  files: DiffFile[];
+  findings: Finding[];
+  rounds: Array<{ round: number; verdict: string }>;
+  /** handoff.md "这次改了什么": the change in plain words. */
+  summary: string[];
+  reviewers: { suggested: string[]; byFile: Record<string, string[]>; source: string | null };
+  human: (HumanReview & { stale: boolean }) | null;
+  status: string | null;
+  running: boolean;
+}
+
+export function buildCodeReview(repo: string, featureDir: string): CodeReviewData {
+  const featureAbs = path.join(repo, featureDir);
+  const state = readState(statePath(repo, featureDir));
+  const base = baseOf(repo, featureDir);
+  const head = (git(repo, "rev-parse", "HEAD") ?? "").trim() || null;
+  const diff = base.commit ? (git(repo, "diff", "--no-color", "--no-ext-diff", "-M", "--unified=3", `${base.commit}..HEAD`) ?? "") : "";
+  const files = parseDiff(diff, featureDir);
+  const { findings, rounds } = aiFindings(repo, featureDir);
+  const owners = readCodeowners(repo);
+  const code = files.filter((f) => !f.doc).map((f) => f.path);
+  const o = owners ? ownersFor(owners.rules, code) : { byFile: {}, all: [] };
+  const spec = read(path.join(featureAbs, "spec.md"));
+  const human = readHumanReview(featureAbs);
+  const summary = section(read(path.join(featureAbs, "handoff.md")), /这次改了什么|改了什么|改动概要|变更内容/)
+    .map((l) => l.replace(/\s+$/, ""))
+    .filter((l) => l.trim())
+    .slice(0, 30);
+  return {
+    title: (/^#\s+(.+)$/m.exec(spec)?.[1] ?? path.basename(featureDir)).replace(/^需求说明[:：\s]*/, "").trim(),
+    featureDir,
+    branch: state?.branch ?? ((git(repo, "rev-parse", "--abbrev-ref", "HEAD") ?? "").trim() || null),
+    base,
+    head,
+    files,
+    findings,
+    rounds,
+    summary,
+    reviewers: { suggested: o.all, byFile: o.byFile, source: owners?.file ?? null },
+    human: human ? { ...human, stale: human.status === "approved" && !!head && human.head !== head } : null,
+    status: state?.status ?? null,
+    running: !!state && state.status === "running" && isAlive(state.pid),
+  };
+}
+
+export interface Submission {
+  verdict: "approve" | "changes";
+  reviewer: string;
+  reviewers: string[];
+  comments: Array<{ file: string | null; line: number | null; text: string }>;
+  /** AI findings the reviewer wants fixed, with an optional remark. */
+  fix: Array<{ id: string; note?: string }>;
+  note: string;
+}
+
+function commitDocs(repo: string, files: string[], message: string): boolean {
+  const rels = files.filter((f) => fs.existsSync(path.join(repo, f)));
+  if (git(repo, "rev-parse", "--git-dir") === null || rels.length === 0) return false;
+  if (git(repo, "add", "--", ...rels) === null) return false;
+  if (!(git(repo, "diff", "--cached", "--name-only", "--", ...rels) ?? "").trim()) return false;
+  return git(repo, "commit", "-q", "-m", message, "--", ...rels) !== null;
+}
+
+/** The person's review, recorded in code-review.md (and changes.md when changes are asked for). */
+export function recordHumanReview(repo: string, featureDir: string, sub: Submission, now = new Date()): { review: HumanReview; committed: boolean } {
+  const featureAbs = path.join(repo, featureDir);
+  const data = buildCodeReview(repo, featureDir);
+  const byId = new Map(data.findings.map((f) => [f.id, f]));
+  const items: HumanItem[] = [];
+  for (const f of sub.fix) {
+    const found = byId.get(f.id);
+    if (!found) continue;
+    items.push({ id: `HR-${items.length + 1}`, file: found.file, line: found.line, finding: found.id, text: `AI 评审意见 ${found.id}（${found.severity}）：${found.title}${f.note?.trim() ? `。评审人补充：${f.note.trim()}` : ""}` });
+  }
+  for (const c of sub.comments) {
+    if (!c.text?.trim()) continue;
+    items.push({ id: `HR-${items.length + 1}`, file: c.file, line: c.line, finding: null, text: c.text.trim().slice(0, 2000) });
+  }
+  if (sub.note.trim() && sub.verdict === "changes") items.push({ id: `HR-${items.length + 1}`, file: null, line: null, finding: null, text: sub.note.trim().slice(0, 2000) });
+  const date = now.toISOString().slice(0, 10);
+  const reviewer = sub.reviewer.trim().slice(0, 60) || "评审人（插件）";
+  const review: HumanReview = {
+    status: sub.verdict === "approve" ? "approved" : "changes_requested",
+    at: now.toISOString(),
+    reviewer,
+    reviewers: [...new Set(sub.reviewers.map((r) => r.trim()).filter(Boolean))].slice(0, 20),
+    head: data.head,
+    items,
+    note: sub.note.trim().slice(0, 2000),
+    consumedAttempt: null,
+  };
+  const where = (i: HumanItem) => (i.file ? `[${i.file}${i.line ? `:${i.line}` : ""}] ` : "");
+  const block = [
+    "",
+    `## 人工评审（${date}，${reviewer}）`,
+    "",
+    `- 结论：${sub.verdict === "approve" ? "通过" : "需要修改"}`,
+    `- 评审的提交：${data.head ?? "（未知）"}`,
+    `- 审核人：${review.reviewers.length ? review.reviewers.join("、") : "（未指定）"}`,
+    ...(sub.verdict === "approve" && review.note ? [`- 说明：${review.note}`] : []),
+    ...(items.length ? ["", ...items.map((i) => `- **${i.id}** ${where(i)}${i.text}`)] : []),
+    ...(sub.verdict === "changes" ? ["", "以上 HR 意见由下一次尝试逐条处理；处理记录写在这一节之后。"] : []),
+    "",
+  ].join("\n");
+  const reviewFile = path.join(featureAbs, "code-review.md");
+  fs.appendFileSync(reviewFile, fs.existsSync(reviewFile) ? block : `# 代码评审\n${block}`);
+  const touched = [path.join(featureDir, "code-review.md")];
+  if (sub.verdict === "changes") {
+    const changes = path.join(featureAbs, "changes.md");
+    const n = (read(changes).match(/人工代码评审退回/g) ?? []).length + 1;
+    const text = [
+      "",
+      `## ${date} 人工代码评审退回（第 ${n} 次）`,
+      "",
+      "- 来源：人工代码评审",
+      `- 内容：${reviewer} 提出了 ${items.length} 条修改意见，见 code-review.md 的“人工评审（${date}，${reviewer}）”一节（HR-1 起）`,
+      "- 处理：从方案设计开始只处理这些意见（需求说明不变），修改经过代码评审后重新验证",
+      "",
+    ].join("\n");
+    fs.appendFileSync(changes, fs.existsSync(changes) ? text : `# 变更记录\n${text}`);
+    touched.push(path.join(featureDir, "changes.md"));
+  }
+  writeHumanReview(featureAbs, review);
+  const committed = commitDocs(repo, touched, `docs(${path.basename(featureDir)}): 人工代码评审${sub.verdict === "approve" ? "通过" : "意见"}`);
+  // A new review replaces the draft.
+  fs.rmSync(path.join(humanDir(featureAbs), "draft.json"), { force: true });
+  return { review, committed };
+}
+
+/** Starts the attempt that handles the comments: `req review-fix <需求>` in the requirement's checkout. */
+export function startReviewFix(repo: string, featureDir: string): { ok: boolean; message: string } {
+  const state = readState(statePath(repo, featureDir));
+  const cwd = state?.worktree?.sourceRepo ?? repo;
+  const env = { ...process.env };
+  delete env.PASEO_AGENT_ID;
+  delete env.PASEO_AGENT_CWD;
+  const r = spawnSync(process.execPath, [path.join(KIT_ROOT, "bin", "req.mjs"), "review-fix", featureDir], { cwd, env, encoding: "utf8", timeout: 180_000, windowsHide: true });
+  return { ok: r.status === 0, message: r.error ? r.error.message : `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+}
+
+/** Comments waiting for an attempt to take them up (for `--review-fix`). */
+export function pendingHumanReview(featureAbs: string): HumanReview | null {
+  const r = readHumanReview(featureAbs);
+  return r && r.status === "changes_requested" && r.consumedAttempt === null ? r : null;
+}