paseo-req-kit 1.7.0-beta.3 → 1.8.0

package/engine/src/eval.ts

@@ -199,7 +199,7 @@ export function evaluateCase(
         const rounds = (id: string) => Math.max(0, ...history.filter((h) => h.stepId === id).map((h) => h.round ?? 0));
         result.reviewRounds = { design: rounds("design_review"), code: rounds("code_review"), defectFix: rounds("defect_fix") };
         result.resultFollowUps = history.reduce((sum, h) => sum + (h.followUps ?? 0), 0);
-        result.humanInterventions = state.status === "waiting_for_business" || state.status === "failed" ? 1 : 0;
+        result.humanInterventions = ["waiting_for_business", "waiting_for_approval", "failed"].includes(state.status ?? "") ? 1 : 0;
       } else if (!result.error) {
         result.error = "流水线没有留下状态文件，见 .pipeline/eval-run.log";
       }

package/engine/src/features.ts

@@ -89,6 +89,8 @@ function stageOf(confirmed: boolean, state: RawState | null, acceptance: string
       return state.pid && isAlive(state.pid) ? "开发中" : "已中断（可继续）";
     case "waiting_for_business":
       return "等待需求方决定";
+    case "waiting_for_approval":
+      return "等待确认方案";
     case "phase_done":
       return "研发完成，待测试验证";
     case "failed":

package/engine/src/gate.ts

@@ -0,0 +1,157 @@
+// The quality gate: project checks (lint, type check, tests, build) that the engine runs
+// itself after the steps that change code, instead of trusting the agent's own report.
+// Only checks that passed before the change and fail after it block; see ADR 0023.
+
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import type { CheckDef } from "./config.js";
+import type { CheckOutcome } from "./state.js";
+
+function git(repo: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return null;
+  }
+}
+
+export function headCommit(repo: string): string | null {
+  return git(repo, ["rev-parse", "HEAD"])?.trim() || null;
+}
+
+/**
+ * Files changed since `base`: committed, staged, unstaged and untracked (repository-relative,
+ * "/" separators). Null when it cannot be told (not a git repository, unknown base).
+ */
+export function changedFiles(repo: string, base: string | null): string[] | null {
+  if (!base) return null;
+  const diff = git(repo, ["diff", "--name-only", base]);
+  if (diff === null) return null;
+  const untracked = git(repo, ["ls-files", "--others", "--exclude-standard"]) ?? "";
+  const files = new Set([...diff.split("\n"), ...untracked.split("\n")].map((f) => f.trim()).filter(Boolean));
+  return [...files].sort();
+}
+
+/**
+ * Which of `files` changed since `commit` (committed or not); null when the commit is not
+ * in this repository. Used to tell whether acceptance tests committed first were changed later.
+ */
+export function changedSince(repo: string, commit: string, files: string[]): string[] | null {
+  if (git(repo, ["rev-parse", "--verify", "--quiet", `${commit}^{commit}`]) === null) return null;
+  const out = git(repo, ["diff", "--name-only", commit, "--", ...files]);
+  if (out === null) return null;
+  return out.split("\n").map((f) => f.trim()).filter(Boolean).sort();
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let re = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === "*" && pattern[i + 1] === "*") {
+      re += ".*";
+      i += 1;
+      if (pattern[i + 1] === "/") i += 1;
+    } else if (c === "*") re += "[^/]*";
+    else if (c === "?") re += "[^/]";
+    else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/** Whether a repository-relative file falls under a path: "web/" (a directory), "src/a.ts", or a glob with *. */
+export function matchesPath(file: string, pattern: string): boolean {
+  const p = pattern.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+  if (p === "" || p === "." || p === "/") return true;
+  if (p.includes("*") || p.includes("?")) return globToRegExp(p).test(file);
+  if (p.endsWith("/")) return file.startsWith(p);
+  return file === p || file.startsWith(`${p}/`);
+}
+
+/** The paths a check watches; empty: the whole repository. */
+export function checkPaths(check: CheckDef): string[] {
+  if (check.paths && check.paths.length > 0) return check.paths;
+  if (check.cwd && check.cwd !== ".") return [`${check.cwd.replace(/\\/g, "/").replace(/\/$/, "")}/`];
+  return [];
+}
+
+/** Whether a check applies to a change; with the changed files unknown, every check applies. */
+export function checkApplies(check: CheckDef, files: string[] | null): boolean {
+  const paths = checkPaths(check);
+  if (paths.length === 0 || files === null) return true;
+  return files.some((f) => paths.some((p) => matchesPath(f, p)));
+}
+
+export interface CheckRun {
+  outcome: CheckOutcome;
+  /** Exit code, or null when it was stopped (timeout) or could not start. */
+  exitCode: number | null;
+  timedOut: boolean;
+  /** Combined output, trimmed to the end. */
+  output: string;
+  seconds: number;
+}
+
+const MAX_OUTPUT = 200_000;
+
+/** Runs one check through the system shell, in the repository (or its cwd). Never throws. */
+export function runCheck(check: CheckDef, repo: string, defaultTimeoutMinutes: number): Promise<CheckRun> {
+  const started = Date.now();
+  const cwd = path.join(repo, check.cwd ?? ".");
+  const timeoutMs = (check.timeoutMinutes ?? defaultTimeoutMinutes) * 60_000;
+  return new Promise((resolve) => {
+    let output = "";
+    const append = (chunk: Buffer) => {
+      output += chunk.toString("utf8");
+      if (output.length > MAX_OUTPUT * 2) output = output.slice(-MAX_OUTPUT);
+    };
+    const finish = (exitCode: number | null, timedOut: boolean, extra = "") => {
+      const text = `${output}${extra}`.slice(-MAX_OUTPUT);
+      resolve({ outcome: exitCode === 0 && !timedOut ? "pass" : "fail", exitCode, timedOut, output: text, seconds: Math.round((Date.now() - started) / 1000) });
+    };
+    if (!fs.existsSync(cwd)) {
+      finish(null, false, `检查的目录不存在：${cwd}`);
+      return;
+    }
+    let child;
+    try {
+      // CI=1: test runners stay non-interactive (no watch mode, no prompts).
+      child = spawn(check.command, { cwd, shell: true, env: { ...process.env, CI: process.env.CI ?? "1" }, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" });
+    } catch (error) {
+      finish(null, false, `无法启动：${(error as Error).message}`);
+      return;
+    }
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        // The whole process group: a test runner's own children too.
+        if (process.platform !== "win32" && child.pid) process.kill(-child.pid, "SIGKILL");
+        else child.kill("SIGKILL");
+      } catch {
+        // Already gone.
+      }
+    }, timeoutMs);
+    child.stdout?.on("data", append);
+    child.stderr?.on("data", append);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      finish(null, false, `\n无法启动：${error.message}`);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      finish(code, timedOut, timedOut ? `\n（超过 ${check.timeoutMinutes ?? defaultTimeoutMinutes} 分钟，已停止）` : "");
+    });
+  });
+}
+
+/** The last lines of a check's output, for a message to the agent. */
+export function tail(text: string, lines = 60): string {
+  const all = text.trimEnd().split(/\r?\n/);
+  return (all.length > lines ? ["…", ...all.slice(-lines)] : all).join("\n");
+}
+
+/** A file name for a check's log. */
+export function logName(name: string): string {
+  return `${name.replace(/[^\p{L}\p{N}._-]+/gu, "-").replace(/^-+|-+$/g, "") || "check"}.log`;
+}

package/engine/src/joint.ts

@@ -0,0 +1,173 @@
+// Joint requirements (ADR 0025): one requirement that also changes other repositories
+// (e.g. the backend of a frontend project). The run in the chat's repository coordinates:
+// it designs the whole change and the interface contract, then each other repository gets
+// a Paseo worktree on the requirement's branch where its own implementation, code review
+// and fixes run (in parallel with this repository's); handoff, verification and the report
+// stay here. Everything is committed locally only.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { type CheckDef, type RelatedRepo, resolveRelatedRepo } from "./config.js";
+import type { AgentRuntime } from "./runtime.js";
+import { ensurePipelineDir, hashFile, type JointRepo, type PipelineState } from "./state.js";
+
+/** At most this many other repositories in one requirement (three in all). */
+export const MAX_JOINT = 2;
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+/** Where a step runs: this repository (no target) or one of the joint repositories. */
+export interface StepTarget {
+  name: string;
+  slug: string;
+  repo: string;
+  featureDir: string;
+  workspaceId: string | null;
+  branch: string | null;
+  joint: JointRepo;
+}
+
+/** An ASCII suffix for step keys, from the repository's directory name. */
+export function slugFor(dir: string, taken: string[]): string {
+  const base = path.basename(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "repo";
+  let slug = base;
+  for (let i = 2; taken.includes(slug); i++) slug = `${base}-${i}`;
+  return slug;
+}
+
+/** Problems with the spec's "联合开发" names for this configuration, or null. */
+export function jointProblem(names: string[], related: RelatedRepo[], projectDir: string): string | null {
+  if (names.length === 0) return null;
+  if (names.length > MAX_JOINT) return `联合开发最多再涉及 ${MAX_JOINT} 个仓库（一共 ${MAX_JOINT + 1} 个），需求说明里写了 ${names.length} 个：${names.join("、")}`;
+  for (const name of names) {
+    const r = related.find((x) => x.name === name);
+    if (!r) {
+      return `需求说明的"联合开发"中有「${name}」，但项目配置的 relatedRepos 里没有登记这个仓库${related.length > 0 ? `（已登记：${related.map((x) => x.name).join("、")}）` : ""}。请在 .requirement-pipeline.json 中登记，或改正需求说明`;
+    }
+    const dir = resolveRelatedRepo(r, projectDir);
+    if (!fs.existsSync(dir)) return `联合开发的仓库「${name}」不在这台机器上：${dir}`;
+    try {
+      git(dir, "rev-parse", "--git-dir");
+    } catch {
+      return `联合开发的仓库「${name}」不是 git 仓库：${dir}`;
+    }
+  }
+  return null;
+}
+
+/** The joint repositories this run works in: those the spec names now, in that order. */
+export function activeJoint(state: Pick<PipelineState, "joint">, names: string[]): JointRepo[] {
+  return names.map((n) => (state.joint ?? []).find((j) => j.name === n)).filter((j): j is JointRepo => j !== undefined);
+}
+
+/**
+ * Creates the worktree of each named repository that does not have one yet, on the branch
+ * feature/<requirement>, cut from what that repository has checked out. Returns the entries.
+ */
+export async function ensureJointRepos(input: {
+  runtime: Pick<AgentRuntime, "createWorktree">;
+  state: PipelineState;
+  featureDir: string;
+  names: string[];
+  related: RelatedRepo[];
+  projectDir: string;
+  title: string;
+  log: (message: string) => void;
+}): Promise<JointRepo[]> {
+  const { state } = input;
+  state.joint ??= [];
+  for (const name of input.names) {
+    if (state.joint.some((j) => j.name === name)) continue;
+    const r = input.related.find((x) => x.name === name);
+    if (!r) throw new Error(`联合开发的仓库「${name}」没有在 relatedRepos 中登记`);
+    const sourceRepo = fs.realpathSync(resolveRelatedRepo(r, input.projectDir));
+    const branch = `feature/${path.basename(input.featureDir)}`;
+    let exists = true;
+    try {
+      git(sourceRepo, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`);
+    } catch {
+      exists = false;
+    }
+    if (exists) {
+      throw new Error(`联合开发的仓库「${name}」（${sourceRepo}）里已经有分支 ${branch}。可能是之前开始过这个需求：请在那个仓库确认后删除或改名这个分支，再继续`);
+    }
+    const head = git(sourceRepo, "rev-parse", "--abbrev-ref", "HEAD");
+    const baseRef = head === "HEAD" ? git(sourceRepo, "rev-parse", "HEAD") : head;
+    const created = await input.runtime.createWorktree({
+      sourceRepo,
+      baseRef,
+      branchName: branch,
+      title: `${input.title}（${name}）`,
+      callerAgentId: state.originAgentId,
+    });
+    const repo = fs.realpathSync(created.directory);
+    ensurePipelineDir(repo, input.featureDir);
+    const entry: JointRepo = {
+      name,
+      slug: slugFor(sourceRepo, state.joint.map((j) => j.slug)),
+      sourceRepo,
+      repo,
+      workspaceId: created.workspaceId,
+      branch,
+      specHash: null,
+    };
+    state.joint.push(entry);
+    input.log(`联合开发：为「${name}」新建了工作区 ${repo}（分支 ${branch}，从 ${baseRef} 切出）`);
+  }
+  return activeJoint(state, input.names);
+}
+
+/**
+ * Copies the requirement's documents (spec, design, contract, preview) from this repository's
+ * feature directory into each joint repository's, and commits them there when they changed,
+ * so whoever reviews and merges that repository reads them next to its code.
+ */
+export function syncJointDocs(entries: JointRepo[], mainRepo: string, featureDir: string, files: string[], title: string, log: (message: string) => void): void {
+  const from = path.join(mainRepo, featureDir);
+  for (const entry of entries) {
+    const to = path.join(entry.repo, featureDir);
+    fs.mkdirSync(to, { recursive: true });
+    ensurePipelineDir(entry.repo, featureDir);
+    const copied: string[] = [];
+    for (const file of files) {
+      const src = path.join(from, file);
+      if (!fs.existsSync(src)) continue;
+      fs.cpSync(src, path.join(to, file), { recursive: true });
+      copied.push(path.join(featureDir, file));
+    }
+    const spec = path.join(from, "spec.md");
+    if (fs.existsSync(spec)) entry.specHash = hashFile(spec);
+    if (copied.length === 0) continue;
+    try {
+      git(entry.repo, "add", "--", ...copied);
+      if (git(entry.repo, "diff", "--cached", "--name-only", "--", ...copied)) {
+        git(entry.repo, "commit", "-q", "-m", `docs(req): ${title} 的需求说明和方案（同步自主仓库）`, "--", ...copied);
+        log(`联合开发：已把 ${files.filter((f) => fs.existsSync(path.join(from, f))).join("、")} 同步到「${entry.name}」并提交`);
+      }
+    } catch (error) {
+      const stderr = (error as { stderr?: Buffer | string }).stderr?.toString().trim();
+      log(`联合开发：同步到「${entry.name}」后提交失败（${stderr || (error as Error).message}），文件已复制，步骤照常可以读到`);
+    }
+  }
+}
+
+/** The quality-gate checks a joint repository defines in its own project configuration. */
+export function loadProjectChecks(repo: string, log: (message: string) => void): CheckDef[] {
+  const file = path.join(repo, ".requirement-pipeline.json");
+  if (!fs.existsSync(file)) return [];
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8")) as { checks?: unknown };
+    if (!Array.isArray(raw.checks)) return [];
+    const checks = raw.checks.filter(
+      (c): c is CheckDef => typeof c === "object" && c !== null && typeof (c as CheckDef).name === "string" && typeof (c as CheckDef).command === "string",
+    );
+    if (checks.length !== raw.checks.length) log(`${file} 中有写法不对的检查，已跳过`);
+    return checks;
+  } catch (error) {
+    log(`读不了 ${file}：${(error as Error).message}，这个仓库不运行质量门`);
+    return [];
+  }
+}

package/engine/src/launch.ts

@@ -380,7 +380,7 @@ console.log(
   [
     checked.entersVerify
       ? `已在后台开始测试验证阶段（${PROFILE_LABELS[profile]}档），进程 ${child.pid}。提测说明：${checked.featureDir}/handoff.md`
-      : `已在后台启动（${modeText[checked.mode.kind]}，${PROFILE_LABELS[profile]}档${phaseMode === "continuous" ? "" : `，执行方式：${PHASE_MODE_LABELS[phaseMode]}`}），进程 ${child.pid}。`,
+      : `已在后台启动（${args.approve && checked.mode.kind === "resume-reuse" ? "已确认方案，开始写代码" : modeText[checked.mode.kind]}，${PROFILE_LABELS[profile]}档${phaseMode === "continuous" ? "" : `，执行方式：${PHASE_MODE_LABELS[phaseMode]}`}），进程 ${child.pid}。`,
     !checked.entersVerify && phaseMode === "gated"
       ? `研发完成（写好提测说明）后会停下来通知这个对话，等待测试验证${args.verifyAt ? `；已安排在 ${describeTime(new Date(args.verifyAt))} 之后自动开始测试验证` : ""}。`
       : !checked.entersVerify && phaseMode === "develop-only"

package/engine/src/lessons.ts

@@ -0,0 +1,72 @@
+// Recurring review findings: the report step writes lessons.tsv (problems a project-level
+// rule would prevent); the overview and /req-retro look for a category that keeps coming
+// back across requirements, the cue to turn it into a lint rule, a type, a test or a note.
+
+import fs from "node:fs";
+import path from "node:path";
+import type { FeatureSummary } from "./features.js";
+import { PROJECT_DIR } from "./prompts.js";
+
+export interface Lesson {
+  category: string;
+  finding: string;
+  source: string;
+  rule: string;
+  layer: string;
+}
+
+export interface RecurringLesson {
+  category: string;
+  /** Requirements (directory names) the category appeared in. */
+  features: string[];
+  /** Suggested rules, as written, without repeats. */
+  rules: string[];
+}
+
+/** Rows of a lessons.tsv; an unreadable or missing file gives none. */
+export function readLessons(file: string): Lesson[] {
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8").replace(/^/, "");
+  } catch {
+    return [];
+  }
+  const [header, ...rows] = text.split(/\r?\n/).filter((l) => l.trim() !== "");
+  if (!header) return [];
+  const columns = header.split("\t").map((c) => c.trim());
+  const at = (name: string) => columns.indexOf(name);
+  return rows
+    .map((row) => row.split("\t"))
+    .map((cells) => {
+      const get = (name: string) => (at(name) >= 0 ? (cells[at(name)] ?? "").trim() : "");
+      return { category: get("category"), finding: get("finding"), source: get("source"), rule: get("rule"), layer: get("layer") };
+    })
+    .filter((l) => l.category !== "");
+}
+
+/** Categories already turned into rules (or set aside), one per line in .requirement-pipeline/lessons-handled.txt. */
+export function handledCategories(repo: string): Set<string> {
+  try {
+    const text = fs.readFileSync(path.join(repo, PROJECT_DIR, "lessons-handled.txt"), "utf8");
+    return new Set(text.split(/\r?\n/).map((l) => l.replace(/#.*/, "").trim()).filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
+/** Categories found in at least `min` requirements, most frequent first. */
+export function recurringLessons(features: FeatureSummary[], handled: Set<string> = new Set(), min = 2): RecurringLesson[] {
+  const byCategory = new Map<string, RecurringLesson>();
+  for (const f of features) {
+    for (const lesson of readLessons(path.join(f.worktree, f.featureDir, "lessons.tsv"))) {
+      if (handled.has(lesson.category)) continue;
+      const entry = byCategory.get(lesson.category) ?? { category: lesson.category, features: [], rules: [] };
+      if (!entry.features.includes(f.name)) entry.features.push(f.name);
+      if (lesson.rule && !entry.rules.includes(lesson.rule)) entry.rules.push(lesson.rule);
+      byCategory.set(lesson.category, entry);
+    }
+  }
+  return [...byCategory.values()]
+    .filter((e) => e.features.length >= min)
+    .sort((a, b) => b.features.length - a.features.length || a.category.localeCompare(b.category));
+}

package/engine/src/main.ts

@@ -3,14 +3,15 @@
 
 import { execFileSync } from "node:child_process";
 import path from "node:path";
-import { LAUNCHER, parseLaunchArgs, resumeCommand, statusCommand, verifyCommand } from "./cli-args.js";
+import { approveCommand, LAUNCHER, parseLaunchArgs, resumeCommand, statusCommand, verifyCommand } from "./cli-args.js";
 import { dequeuedMessage, queuedMessage, watchdogPrompt } from "./messages.js";
 import { slotHolders, slotsDir, tryAcquireSlot } from "./queue.js";
 import { cronEvery, parseStartTime } from "./schedule-time.js";
-import { loadConfig, PHASE_MODE_LABELS, PROFILE_LABELS } from "./config.js";
+import { loadConfig, PHASE_MODE_LABELS, PROFILE_LABELS, REQUIREMENT_TYPE_LABELS } from "./config.js";
 import { defaultConfigPath, kitVersion, localPromptsDir, PRINCIPLES_INDEX, PROMPTS_DIR } from "./locations.js";
 import { satisfies } from "./daemon-check.js";
 import { describeAgentProfile, resolveConfigProfiles, usesPaseoProfiles } from "./paseo-profiles.js";
+import { jointProblem } from "./joint.js";
 import { runPipeline } from "./pipeline.js";
 import { preflight, verifyPhaseProblem } from "./preflight.js";
 import { loadRuntimeFactory } from "./runtime-loader.js";
@@ -71,6 +72,12 @@ async function main(): Promise<number> {
     args.phases ?? (reuse ? previousState?.phases?.mode : null) ?? checked.specPhases ?? previousState?.phases?.mode ?? config.phases.mode;
   // --verify-at only makes sense with a gate; asking for it implies one.
   if (args.verifyAt && phaseMode === "continuous" && !args.phases) phaseMode = "gated";
+  // A playbook type the configuration turned off runs the normal flow.
+  const type = checked.specType && config.requirementTypes.includes(checked.specType) ? checked.specType : null;
+  // An assessment writes no code: there is nothing to hand over for testing.
+  if (type === "assessment") phaseMode = "continuous";
+  // Joint requirement: other repositories this one also changes (an assessment only reads them).
+  const jointNames = type === "assessment" ? [] : checked.specJoint;
   const phases: RunPhases = {
     mode: phaseMode,
     environment: args.verifyEnv ?? previousState?.phases?.environment ?? config.phases.verify.environment,
@@ -86,6 +93,9 @@ async function main(): Promise<number> {
       const chatDir = args.sourceRepo ?? (mode.kind === "fresh" ? null : mode.previous.worktree?.sourceRepo) ?? repo;
       if (verifyAtText && !verifyAt) throw new Error(`看不懂测试验证的开始时间"${verifyAtText}"`);
       if (verifyAtText && phases.mode === "develop-only") throw new Error("只做研发时没有测试验证阶段，--verify-at 不适用");
+      if (type === "assessment" && (verifyAtText || args.phase === "verify")) throw new Error("评估类需求只做调研、不写代码，没有测试验证阶段");
+      const jointIssue = jointProblem(jointNames, config.relatedRepos, chatDir);
+      if (jointIssue) throw new Error(jointIssue);
       if (checked.entersVerify) {
         const problem = verifyPhaseProblem(repo, featureDir, phases.environment);
         if (problem) throw new Error(problem);
@@ -138,8 +148,11 @@ async function main(): Promise<number> {
       phase: "develop",
       verifyAt: verifyAt?.toISOString() ?? null,
       handbacks: 0,
+      type,
     };
-    log(`开始新的流水线：${featureDir}（${PROFILE_LABELS[profile]}档，执行方式：${PHASE_MODE_LABELS[phases.mode]}，分支 ${checked.branch ?? "无"}）`);
+    log(
+      `开始新的流水线：${featureDir}（${PROFILE_LABELS[profile]}档，${type ? `类型：${REQUIREMENT_TYPE_LABELS[type]}，` : ""}执行方式：${PHASE_MODE_LABELS[phases.mode]}，分支 ${checked.branch ?? "无"}）`,
+    );
   } else {
     const startOver = mode.kind !== "resume-reuse";
     const previousImplemented = Object.keys(mode.previous.results).some((k) => k === "implement") ||
@@ -170,13 +183,30 @@ async function main(): Promise<number> {
       phase: checked.entersVerify ? "verify" : startOver ? "develop" : (mode.previous.phase ?? "develop"),
       verifyAt: checked.entersVerify ? null : (verifyAt?.toISOString() ?? (startOver ? null : (mode.previous.verifyAt ?? null))),
       handbacks: mode.kind === "restart" ? 0 : (mode.previous.handbacks ?? 0),
+      type,
+      codeBase: startOver ? null : (mode.previous.codeBase ?? null),
+      // --approve: the requester confirmed the design that was waiting at the confirmation point.
+      approval:
+        args.approve && mode.previous.status === "waiting_for_approval"
+          ? { attempt: mode.previous.attempt, status: "approved", at: now }
+          : startOver
+            ? null
+            : (mode.previous.approval ?? null),
+      gate: mode.kind === "restart" ? null : (mode.previous.gate ?? null),
     };
     if (checked.entersVerify) {
       // A develop-only run that ends with its development report gets a full report after verification.
       delete state.results.report;
       log(`开始测试验证阶段（${phases.environment === "deployed" ? "已部署的测试环境" : "本地"}，缺陷处理：${phases.defects}）`);
     }
-    const why = mode.kind === "resume-from-design" ? mode.reason : mode.kind === "restart" ? "按 --restart 从头开始" : "从中断处继续，已完成的步骤沿用结果";
+    const why =
+      mode.kind === "resume-from-design"
+        ? mode.reason
+        : mode.kind === "restart"
+          ? "按 --restart 从头开始"
+          : args.approve
+            ? "需求方已确认方案，开始写代码"
+            : "从中断处继续，已完成的步骤沿用结果";
     log(`继续流水线：${featureDir}（第 ${state.attempt} 次尝试，${PROFILE_LABELS[profile]}档）—— ${why}`);
   }
   writeState(stateFile, state);
@@ -198,6 +228,7 @@ async function main(): Promise<number> {
     resume: resumeCommand({ repo: chatRepo, featureDir, configPath: args.configPath }),
     status: statusCommand({ repo: chatRepo, featureDir, configPath: args.configPath }),
     verify: verifyCommand({ repo: chatRepo, featureDir, configPath: args.configPath }),
+    approve: approveCommand({ repo: chatRepo, featureDir, configPath: args.configPath }),
   };
   const notify = async (text: string) => {
     log(`通知：\n${text}`);
@@ -285,11 +316,13 @@ async function main(): Promise<number> {
       resumeCommand: commands.resume,
       statusCommand: commands.status,
       verifyCommand: commands.verify,
+      approveCommand: commands.approve,
+      jointNames,
       log,
       sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     });
     log(`流水线结束：${outcome}`);
-    return outcome === "completed" || outcome === "phase_done" ? 0 : outcome === "waiting_for_business" ? 3 : 1;
+    return outcome === "completed" || outcome === "phase_done" ? 0 : outcome === "waiting_for_business" || outcome === "waiting_for_approval" ? 3 : 1;
   } finally {
     // The run ended by itself: the watchdog has nothing left to watch.
     if (watchdog) {

package/engine/src/messages.ts

@@ -12,13 +12,17 @@ export function blockedMessage(input: {
   resumeCommand: string;
   /** A reminder is scheduled after this many hours without an answer. */
   reminderHours?: number | null;
+  /** "reproduce": the defect could not be reproduced (defect playbook); default: the design review. */
+  source?: "design_review" | "reproduce";
 }): string {
   const list = input.questions.map((q, i) => `${i + 1}. ${q}`).join("\n");
   return [
     HEADER,
     "",
     `功能目录：${input.featureDir}`,
-    "情况：方案审核发现有问题必须由需求方决定，否则可能做出错误的东西。流水线已暂停，还没有开始写代码。",
+    input.source === "reproduce"
+      ? "情况：复现与定位这一步没能复现这个缺陷，需要需求方补充信息（复现步骤、环境、账号或数据、截图或报错）。流水线已暂停，还没有修改代码。"
+      : "情况：方案审核发现有问题必须由需求方决定，否则可能做出错误的东西。流水线已暂停，还没有开始写代码。",
     "",
     "需要用户决定的问题：",
     list,
@@ -128,6 +132,29 @@ export function resultFollowUp(input: { resultFile: string; problem: string }):
   ].join("\n");
 }
 
+/** Sent to the step agent when checks that passed before its change now fail (the quality gate). */
+export function gateFollowUp(input: {
+  failures: Array<{ name: string; command: string; cwd: string | null; logFile: string; tail: string }>;
+  round: number;
+  max: number;
+  /** Checks that already failed before this requirement's change: not this step's problem. */
+  preexisting: string[];
+}): string {
+  const parts = [
+    `流水线在你这一步结束后运行了项目的检查（质量门），以下检查在改动之前通过、现在失败（第 ${input.round} 次要求修复，最多 ${input.max} 次）：`,
+    "",
+  ];
+  for (const f of input.failures) {
+    parts.push(`### ${f.name}`, "", `命令：\`${f.command}\`${f.cwd ? `（在 ${f.cwd} 目录）` : ""}`, `完整输出：${f.logFile}`, "", "最后的输出：", "", "```text", f.tail, "```", "");
+  }
+  if (input.preexisting.length > 0) parts.push(`（${input.preexisting.join("、")} 在改动之前就失败，不算本次引入，不需要处理。）`, "");
+  parts.push(
+    "请找到原因并修复，让这些检查重新通过；修复要针对原因，不要删除、跳过或放宽检查和测试。修完自己运行一遍这些命令确认通过，提交，并在本步骤的产物里记一笔（哪个检查、原因、怎么修的）；结果文件按需要更新。",
+    "确实修不了的（例如需要环境或权限），在产物里写明原因后照常结束，流水线会把它带进评审和报告。",
+  );
+  return parts.join("\n");
+}
+
 export function milestoneMessage(text: string): string {
   return [
     "【需求开发流水线通知 · 进展】这条消息来自后台流水线，不是用户发的。仅告知进展，用一句话转告用户即可，不需要其他操作。",
@@ -306,3 +333,62 @@ export function verifyStartPrompt(input: { featureDir: string; statusCommand: st
     "3. 其他情况（已经开始、已完成、用户已经手动处理过）：什么也不做，也不要回复用户。",
   ].join("\n");
 }
+
+/** The design waits at the confirmation point (designApproval). */
+export function approvalMessage(input: {
+  featureDir: string;
+  previewPath: string;
+  /** The prototype (UI changes), when the design made one. */
+  prototypePath: string | null;
+  approveCommand: string;
+  resumeCommand: string;
+  reminderHours?: number | null;
+  /** The run carries on with the design at this time (text) without an answer. */
+  autoContinueAt?: string | null;
+}): string {
+  return [
+    `${HEADER.replace("【需求开发流水线通知】", "【需求开发流水线通知 · 请确认方案】")}`,
+    "",
+    `功能目录：${input.featureDir}`,
+    "情况：方案已经通过审核，还没有开始写代码。开发前请需求方确认\"做完之后会看到什么\"，这时调整的成本最低。",
+    `- 做完后你会看到什么：${input.previewPath}`,
+    ...(input.prototypePath ? [`- 界面原型：${input.prototypePath}（静态页面，可以在浏览器中打开）`] : []),
+    "",
+    "请这样处理：",
+    "1. 读 preview.md，用几句话把要点讲给用户：会看到的变化、主要的假设（尤其是影响界面、数据、权限的），有原型就告诉用户在哪里看。",
+    "2. 问用户：按这个做，还是有要改的地方？",
+    `3. 用户确认后，执行下面的命令继续开发：\n\n${input.approveCommand}`,
+    "4. 用户要改的：按需求对齐时的方式问清楚，把结论记入 alignment.md，更新 spec.md（顶部\"版本\"加 1，在 changes.md 中记一节，原因写\"方案确认时的修改\"），请用户再次确认需求说明，然后执行下面的命令，流水线会从方案设计开始按修改后的需求调整方案，再请用户确认一次：",
+    "",
+    input.resumeCommand,
+    ...(input.reminderHours ? ["", `（如果 ${input.reminderHours} 小时内还没有确认，会在这个对话里提醒一次。）`] : []),
+    ...(input.autoContinueAt ? ["", `（按团队设置，到 ${input.autoContinueAt} 仍没有确认时，会按这个方案继续开发。）`] : []),
+  ].join("\n");
+}
+
+export function approvalReminderMessage(input: { featureDir: string; hours: number; previewPath: string; approveCommand: string }): string {
+  return [
+    "【需求开发流水线通知】这是一条预约的提醒，不是用户发的。",
+    "",
+    `功能目录：${input.featureDir}`,
+    `这个需求的方案等待需求方确认已经超过 ${input.hours} 小时，开发一直暂停着（要确认的内容：${input.previewPath}）。`,
+    "",
+    "请先执行查看进度的命令确认：仍然是\"等待需求方确认方案\"时，在用户下次说话时提醒他看一下并确认；已经确认、开发已经继续或停止时，忽略这条提醒，不要打扰用户。",
+    `用户确认后继续开发的命令是：${input.approveCommand}`,
+  ].join("\n");
+}
+
+export function approvalContinuePrompt(input: { featureDir: string; hours: number; statusCommand: string; approveCommand: string }): string {
+  return [
+    "【需求开发流水线通知】这是一条预约的自动继续，不是用户发的。",
+    "",
+    `功能目录：${input.featureDir}`,
+    `这个需求的方案等待确认已经 ${input.hours} 小时。按团队的设置，超时没有确认时按方案继续开发。`,
+    "",
+    "请这样处理：",
+    `1. 先执行查看进度的命令：${input.statusCommand}`,
+    "2. 仍然是\"等待需求方确认方案\"时，执行下面的命令，然后用一句话告诉用户：方案一直没有确认，已按方案继续开发，之后仍可以修改需求：",
+    `   ${input.approveCommand}`,
+    "3. 其他情况（已经确认、需求已修改、已经停止）：什么也不做，也不要回复用户。",
+  ].join("\n");
+}