add-coder 0.3.27 → 0.3.28

package/templates/core/governance/preload-templates.ts

@@ -0,0 +1,241 @@
+// preload-templates.ts — ADD 模板预读（bash 版 preload-templates.sh 的 TS 同语义实现）
+// 用法:
+//   preload-templates.ts --index              # 输出模板清单（文件名 + 用途）
+//   preload-templates.ts --full               # 输出全部模板全文
+//   preload-templates.ts --full --top 5       # 输出前 5 个最常用模板全文
+//   preload-templates.ts --full --mark        # 全文输出 + 落 tpl-injected 标记
+//
+// 被 SessionStart（--index）和 UserPromptSubmit（--full）调用。
+// tpl-injected 标记文件用于去重——同会话二次命中时不重复注入。
+// 协议层契约（模板预载）: 读 ${magicDir}/templates 本地物化副本；目录/标准模板缺失 fail-fast
+//
+// 设计范式: OOP 服务类封装（模板表 + 优先级序 + 校验 + 输出模式 + 标记管理单一职责聚合），
+// 纯函数负责文本变换（frontmatter 剥离），CLI 入口仅做参数解析与进程语义。
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { createHash } from "node:crypto"
+import { fileURLToPath } from "node:url"
+import { findUpSync } from "find-up"
+
+/** 模板元信息（泛型 Record 收敛：文件名 → 用途描述） */
+type TemplateRegistry = Readonly<Record<string, string>>
+
+/** 输出模式（--index / --full） */
+type OutputMode = "index" | "full"
+
+/** CLI 参数解析结果（结构化，避免散落参数） */
+interface CliArgs {
+  mode: OutputMode
+  top: number
+  mark: boolean
+}
+
+/** 纯函数：剥离 YAML frontmatter（对齐 bash awk：首行 --- 至下一个 --- 之间的内容跳过） */
+function stripFrontmatter(lines: readonly string[]): string[] {
+  const out: string[] = []
+  let inFm = false
+  lines.forEach((line, idx) => {
+    if (idx === 0 && line === "---") {
+      inFm = true
+      return
+    }
+    if (inFm && line === "---") {
+      inFm = false
+      return
+    }
+    if (!inFm) out.push(line)
+  })
+  return out
+}
+
+/** 纯函数：项目 hash（对齐 bash md5sum | cut -c1-8；失败回退 "default"） */
+function projectHash(projectDir: string): string {
+  try {
+    return createHash("md5").update(projectDir).digest("hex").slice(0, 8)
+  } catch {
+    return "default"
+  }
+}
+
+/** 纯函数：解析 CLI 参数为结构化 CliArgs */
+function parseArgs(argv: readonly string[]): CliArgs {
+  const args: CliArgs = { mode: "index", top: 0, mark: false }
+  for (let i = 0; i < argv.length; i++) {
+    switch (argv[i]) {
+      case "--index":
+        args.mode = "index"
+        break
+      case "--full":
+        args.mode = "full"
+        break
+      case "--top":
+        args.top = Number(argv[++i] ?? "0") || 0
+        break
+      case "--mark":
+        args.mark = true
+        break
+      default:
+        break
+    }
+  }
+  return args
+}
+
+/**
+ * 模板预读服务（OOP 聚合）:
+ *   - 模板注册表 + 优先级序（顺序即 --top N 的优先级）
+ *   - 目录校验（fail-fast）
+ *   - index/full 两种输出模式
+ *   - tpl-injected 标记管理（去重）
+ */
+export class PreloadTemplates {
+  private readonly templatesDir: string
+  private readonly tplFlag: string
+
+  private static readonly TEMPLATES: TemplateRegistry = Object.freeze({
+    "simple-plan-template.md": "需求方案（简单版）：六节结构，元信息+背景+方案+架构+实施+验收",
+    "spec-template.md": "功能规格：Why/What Changes/Impact/WHEN-THEN Requirements",
+    "tasks-template.md": "任务拆分：Phase→Task→SubTask层级",
+    "checklist-template.md": "验收清单：[T]编译期+[R]运行时+ADD规则合规",
+    "review-template.md": "方案审查（ADD-9）：问题复现+方案对比+决策结论+影响评估",
+    "standard-plan-template.md": "需求方案（标准版）：PLAN元信息+背景+方案+架构+实施Task+验收+关联文档",
+    "add-route-template-heavyweight.md": "ADD执行路线图（重型）：每Step验证并更新状态+spec_sync交叉校验",
+    "add-route-template.md": "ADD执行路线图（轻量）：标准Step产出检查",
+    "handoff-single-round-template.md": "单轮交接：9章节（含恢复上下文审计查询）",
+    "handoff-multi-round-template.md": "多轮交接：全局拓扑+每轮13子章节+收敛规则+启动模板",
+    "review-implementation-template.md": "实现审查（ADD-10）：格式契约+框架版本+数据模型+E2E curl",
+    "review-runtime-template.md": "运行时纠偏（ADD-11）：发现列表+根因分析+流程改进项",
+    "prd-standard-template.md": "产品需求文档（新建）：背景目标+用户场景+功能需求+验收标准",
+    "prd-incremental-template.md": "产品需求文档（增量）：变更摘要+diff式记录",
+    "fix-verification-template.md": "修复验证模板",
+    "report-template.md": "代码审查报告模板",
+    "runtime-report-template.md": "运行时报告模板",
+    "TERMINOLOGY.md": "模板术语速查",
+  })
+
+  private static readonly PRIORITY_ORDER: readonly string[] = Object.freeze([
+    "simple-plan-template.md",
+    "spec-template.md",
+    "tasks-template.md",
+    "checklist-template.md",
+    "review-template.md",
+    "standard-plan-template.md",
+    "add-route-template-heavyweight.md",
+    "add-route-template.md",
+    "handoff-single-round-template.md",
+    "handoff-multi-round-template.md",
+    "review-implementation-template.md",
+    "review-runtime-template.md",
+    "prd-standard-template.md",
+    "prd-incremental-template.md",
+    "fix-verification-template.md",
+    "report-template.md",
+    "runtime-report-template.md",
+    "TERMINOLOGY.md",
+  ])
+
+  /**
+   * 模板目录 find-up 解析（复用 find-up 包，与 src/shared/paths.ts projectRoot 同范式）：
+   *   从 startDir 向上找第一个 templates 目录（esbuild bundle 内联，产物零依赖）：
+   *     - 产物 <magicDir>/hooks/xxx.mjs → <magicDir>/templates（分发物化）
+   *     - 源码 templates/core/governance/preload-templates.ts → templates/core/templates（源码模板）
+   *   命中条件：目录含至少一个标准模板（防命中仓库根 templates/ 空壳）；
+   *   目录存在但标准模板缺失 = 物化异常 → 返回 null，由 validate() fail-fast（不继续向上找）。
+   *   缺陷修复（2026-08-14 Task 5.1）: 原写死 join(dirname, "..", "..", "templates") 固定层级，
+   *   产物从 hooks/ 上溯两级到仓库根 templates/（无标准模板）——被 refresh-fixed 反写掩盖，
+   *   golden 重抓暴露；改 find-up 锚点查找，层级零漂移。
+   */
+  private static findTemplatesDir(startDir: string): string | null {
+    const hit = findUpSync("templates", { cwd: startDir, type: "directory" })
+    if (!hit) return null
+    return PreloadTemplates.PRIORITY_ORDER.some((t) => existsSync(join(hit, t))) ? hit : null
+  }
+
+  constructor(templatesDir?: string, tplFlag?: string) {
+    const startDir = dirname(fileURLToPath(import.meta.url))
+    this.templatesDir = templatesDir ?? PreloadTemplates.findTemplatesDir(startDir) ?? join(startDir, "..", "templates")
+    this.tplFlag = tplFlag ?? `/tmp/add_tpl_${projectHash(process.env.PROJECT_DIR || process.cwd())}`
+  }
+
+  /** 模板目录存在性校验（fail-fast：目录缺失/标准模板全缺 → 抛错，由 CLI 层转 exit 1） */
+  validate(): void {
+    if (!existsSync(this.templatesDir)) {
+      throw new Error(
+        `[ADD preload] 模板目录不存在: ${this.templatesDir}（生成态物化缺失，请执行 add-coder sync 后重试）`
+      )
+    }
+    const available = PreloadTemplates.PRIORITY_ORDER.filter((t) =>
+      existsSync(join(this.templatesDir, t))
+    ).length
+    if (available === 0) {
+      throw new Error(
+        `[ADD preload] 模板目录中未找到 ADD 标准模板: ${this.templatesDir}（缺失清单: ${PreloadTemplates.PRIORITY_ORDER.join(" ")}）`
+      )
+    }
+  }
+
+  /** 读取模板内容（strip frontmatter） */
+  readTemplate(file: string): string {
+    const path = join(this.templatesDir, file)
+    if (!existsSync(path)) return ""
+    return stripFrontmatter(readFileSync(path, "utf-8").split("\n")).join("\n")
+  }
+
+  /** --index 模式输出（对齐 bash output_index 逐字） */
+  index(): string {
+    const lines: string[] = ["## ADD 可用模板清单", "", "| # | 模板文件 | 用途 |", "|---|---------|------|"]
+    let i = 1
+    for (const tmpl of PreloadTemplates.PRIORITY_ORDER) {
+      if (existsSync(join(this.templatesDir, tmpl))) {
+        lines.push(`| ${i} | ${tmpl} | ${PreloadTemplates.TEMPLATES[tmpl] ?? "模板文件"} |`)
+        i++
+      }
+    }
+    return lines.join("\n") + "\n"
+  }
+
+  /** --full 模式输出（对齐 bash output_full 逐字） */
+  full(top: number): string {
+    const lines: string[] = ["## ADD 模板全文内容", ""]
+    let count = 0
+    for (const tmpl of PreloadTemplates.PRIORITY_ORDER) {
+      if (!existsSync(join(this.templatesDir, tmpl))) continue
+      count++
+      if (top > 0 && count > top) break
+      lines.push("---", `### ${tmpl}`, "", this.readTemplate(tmpl), "")
+    }
+    return lines.join("\n") + "\n"
+  }
+
+  isInjected(): boolean {
+    return existsSync(this.tplFlag)
+  }
+
+  /** 标记模板已注入（tpl-injected 去重：同会话二次命中不重复注入） */
+  markInjected(): void {
+    try {
+      writeFileSync(this.tplFlag, "")
+    } catch {
+      /* ignore（对齐 bash touch || true） */
+    }
+  }
+
+  /** CLI 入口：解析参数 → 校验 → 输出；去重命中时 stderr 提示并 exit 0 */
+  run(argv: readonly string[]): number {
+    const { mode, top, mark } = parseArgs(argv)
+    this.validate()
+    if (mode === "index") {
+      process.stdout.write(this.index())
+      return 0
+    }
+    if (this.isInjected() && !mark) {
+      process.stderr.write("[ADD preload] 模板已在本会话注入，跳过重复注入（tpl-injected 标记存在）\n")
+      return 0
+    }
+    process.stdout.write(this.full(top))
+    this.markInjected()
+    return 0
+  }
+}
+

package/templates/core/governance/prompt-router.ts

@@ -0,0 +1,222 @@
+// prompt-router.ts — UserPromptSubmit 触发词路由基类（治理逻辑层，Task 3.1 继承体系）
+// 治理卡位 #3: Layer 1 精准触发 → Layer 2 阻断 → Layer 3 状态注入
+// 规则真源: hook-event-rules.toml（[event.daily.warn_threshold] 日报阈值）
+//
+// 设计范式: 模板方法基类——L1/L2/L3 分流流程固化，
+//   协议差异（提取方式/文本形态/输出通道/附加注入）由 adapter 子类 override。
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { spawnSync } from "node:child_process"
+import {
+  detectActiveAdd,
+  isAlreadyAccepted,
+  jsonGet,
+  localIsoSeconds,
+} from "./common.js"
+import { loadDevKeywords, matchTrigger } from "./vocabulary.js"
+import { writeHookEvent } from "./notify.js"
+import { event } from "./rules.js"
+
+/**
+ * UserPromptSubmit 触发词路由基类（模板方法）:
+ *   流程固化（不可 override）: run()
+ *   扩展点（protected，adapter 子类 override 协议差异）:
+ *     - extractPrompt(): prompt 提取（core: jsonGet；claude: grep 正则）
+ *     - acceptedText(): 验收幂等文本（core: 6 行含 ★；claude: 4 行）
+ *     - onAccepted(): 验收后置（core: spawn review-checklist；claude: 无）
+ *     - onDevKwMatched(): 开发关键词命中提示（claude: stderr；core: 无）
+ *     - layer2Channel: Layer2 输出通道（core: stderr；claude: stdout）
+ *     - layer3Text(): Layer3 状态文本（core: 单行；claude: 多行块）
+ *     - dailyWarnText(): 日报告警文本（core: 含"或检查 hooks 误报"；claude: 无）
+ *     - afterLayer3(): Layer3 附加注入（claude: 模板全文 full(5)；core: 无）
+ */
+export class PromptRouter {
+  protected readonly magicDir: string
+
+  constructor(magicDir: string) {
+    this.magicDir = magicDir
+  }
+
+  // ─────────────────────────── 扩展点 ───────────────────────────
+
+  /** prompt 提取（core: jsonGet） */
+  protected extractPrompt(input: string): string {
+    return jsonGet(input, "prompt")
+  }
+
+  /** 验收幂等文本（core 协议: 6 行含 ★ 同步检查） */
+  protected acceptedText(): string {
+    return `[ADD 验收] ⚠️ 已验收。进入 Review 模式:
+  ① 重新检查 checklist [T]/[R] 项
+  ② 审查 audit 记录完整性
+  ③ 如有差异 → Review 回流至 handoff（增量更新，不覆盖已有结论）
+  ④ 无差异 → 记录 'Review 已确认，无新发现'
+  ★ 同步检查: 如 checklist 有新 cuid 但 handoff 审计表缺失 → 更新 handoff ADD-7 表 + query_audit_logs 命令
+`
+  }
+
+  /** 验收后置处理（core: spawn review-checklist 子进程，输出丢弃） */
+  protected onAccepted(handoff: string, addRoute: string): void {
+    const reviewScript = join(this.magicDir, "hooks", "review-checklist.mjs")
+    if (existsSync(reviewScript)) {
+      spawnSync(process.execPath, [reviewScript, handoff, addRoute], { stdio: "ignore" })
+    }
+  }
+
+  /** 开发关键词命中提示（core: 无） */
+  protected onDevKwMatched(): void {
+    // core 协议: 无额外输出
+  }
+
+  /** 开发关键词匹配（core: join("|") 单正则；qoder: 逐个正则 some） */
+  protected devKwMatched(prompt: string, devKw: string[]): boolean {
+    try {
+      return new RegExp(devKw.join("|"), "i").test(prompt)
+    } catch {
+      return false
+    }
+  }
+
+  /** Layer 2 输出通道（core: stderr） */
+  protected layer2ToStderr(): boolean {
+    return true
+  }
+
+  /** Layer 3 状态文本（core: 单行） */
+  protected layer3Text(plan: string, rounds: string, step: string, handoff: string): string {
+    return `[ADD 状态] Plan: ${plan}, 轮次: ${rounds}, Step: ${step}, handoff: ${handoff}\n`
+  }
+
+  /** 日报告警文本（core: 含"或检查 hooks 误报"） */
+  protected dailyWarnText(noPlan: number, threshold: number): string {
+    return `[Hook ⚠️] 无 Plan 提示已达 ${noPlan} 次（≥${threshold}），建议创建 Plan 或检查 hooks 误报\n`
+  }
+
+  /** Layer 3 附加注入（core: 无） */
+  protected afterLayer3(): void {
+    // core 协议: 无附加注入
+  }
+
+  /** 日报跳过条件（core: 不跳过；claude: MAGIC_DIR 未设置时跳过） */
+  protected shouldSkipDaily(): boolean {
+    return false
+  }
+
+  /** 前置注入（core: 无；qoder: 无条件 "ADD workflow active" JSON） */
+  protected preamble(_input: string): void {
+    // core 协议: 无前置注入
+  }
+
+  /** Layer 3 输出形态（core: 纯文本逐行；qoder: hookSpecificOutput JSON 包） */
+  protected layer3Json(): boolean {
+    return false
+  }
+
+  /** 日报并入 Layer3 上下文（core: 独立行输出；qoder: 并入 additionalContext） */
+  protected dailyInContext(): boolean {
+    return false
+  }
+
+  // ─────────────────────────── 流程固化 ───────────────────────────
+
+  /** 主路由（模板方法）：返回 exit code（0 放行） */
+  run(input: string): number {
+    const prompt = this.extractPrompt(input)
+    if (prompt === "") return 0
+
+    // 前置注入（qoder: 无条件 JSON——bash 原文位于空 prompt 检查之后）
+    this.preamble(input)
+
+    // ─── Layer 1: 精准 P0 触发词 ───
+    const matched = matchTrigger(prompt)
+    if (matched.length > 0) {
+      // 验收幂等保护: 如果已验收，提示不重复
+      if (/验收|收敛/i.test(prompt)) {
+        const addState = detectActiveAdd()
+        if (addState !== null) {
+          const handoff = addState.split("::")[3] ?? ""
+          const addRoute = addState.split("::")[4] ?? ""
+          if (isAlreadyAccepted(addRoute, handoff)) {
+            process.stdout.write(this.acceptedText())
+            this.onAccepted(handoff, addRoute)
+            return 0
+          }
+        }
+      }
+      for (const m of matched) process.stdout.write(m + "\n")
+      return 0
+    }
+
+    // ─── 开发关键词检测（动态加载） ───
+    const devKw = loadDevKeywords()
+    if (devKw.length === 0) return 0
+
+    if (!this.devKwMatched(prompt, devKw)) return 0
+
+    this.onDevKwMatched()
+
+    // ─── Layer 2/3: 按活跃 ADD 分流 ───
+    const state = detectActiveAdd()
+    if (state === null) {
+      // Layer 2: 无活跃 ADD → 提示启动（不阻断）
+      const text = `[ADD 提示] 检测到开发任务，但无活跃 ADD Plan。建议先执行 add-paradigm SKILL:
+  Step 0: 文档先行 (Plan → Review → Specs)
+  Step 3: 代码实现 + 审计植入
+  Step 8: 收敛判断
+`
+      if (this.layer2ToStderr()) {
+        process.stderr.write(text)
+      } else {
+        process.stdout.write(text)
+      }
+      writeHookEvent("prompt-submit", "info", prompt, "无活跃 ADD Plan 下检测到开发任务", "no-active-plan", "none")
+      return 0
+    }
+
+    // Layer 3: 有活跃 ADD → 注入状态
+    const plan = state.split("::")[0] ?? ""
+    const step = state.split("::")[1] ?? ""
+    const rounds = state.split("::")[2] ?? ""
+    const handoff = state.split("::")[3] ?? ""
+    let block = this.layer3Text(plan, rounds, step, handoff)
+
+    // ─── Hook 治理日报（阈值真源: hook-event-rules.toml [event.daily.warn_threshold]）───
+    if (!this.shouldSkipDaily()) {
+      const HOOK_JSONL = join(this.magicDir, "reports", "hook-events.jsonl")
+      if (existsSync(HOOK_JSONL)) {
+        const today = localIsoSeconds().slice(0, 10) // 对齐 bash date +%Y-%m-%d（本地日期）
+        const content = readFileSync(HOOK_JSONL, "utf-8")
+        const todayLines = content.split("\n").filter((l) => l.includes(`"ts":"${today}`))
+        const total = todayLines.length
+        const noPlan = todayLines.filter((l) => l.includes('"planKeyword":"no-active-plan"')).length
+        if (total > 0) {
+          const dailyLine = `[Hook 治理] 今日提示: ${total} 次 | 无 Plan 提示: ${noPlan} 次`
+          const warnThreshold = (event.daily as { warn_threshold: number }).warn_threshold
+          const warnLine = noPlan >= warnThreshold ? this.dailyWarnText(noPlan, warnThreshold) : ""
+          if (this.dailyInContext()) {
+            // qoder 协议: 日报并入 additionalContext（\n 前缀 + 警告尾行）
+            block += `\n${dailyLine}`
+            if (warnLine) block += `\n${warnLine.trimEnd()}`
+          } else {
+            // core/claude 协议: 日报独立 stdout 行（警告随层3文本后输出）
+            process.stdout.write(dailyLine + "\n")
+            if (warnLine) process.stdout.write(warnLine)
+          }
+        }
+      }
+    }
+
+    if (this.layer3Json()) {
+      // qoder 协议: hookSpecificOutput JSON 包
+      process.stdout.write(
+        JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: block.trimEnd() } }) + "\n"
+      )
+    } else {
+      process.stdout.write(block)
+    }
+
+    this.afterLayer3()
+    return 0
+  }
+}

package/templates/core/governance/review-checklist-guard.ts

@@ -0,0 +1,186 @@
+// review-checklist-guard.ts — 验收 Review 模式：checklist 质量检查（治理逻辑层，Task 4.1 收敛）
+// bash 版 review-checklist.sh 的 TS 同语义实现（源自 qoder 私有 lib，R2 回流收敛 core）；
+// 输入: handoff 路径 + add_route 路径；输出: 质量问题清单文本（逐字对齐 bash）。
+// 参数化: specRoot（qoder: .qoder/specs；其余端按协议注入）+ PROJECT_DIR。
+
+import { existsSync, readFileSync, readdirSync } from "node:fs"
+import { join, dirname, basename } from "node:path"
+import { tryResolveMagicDir } from "./common.js"
+
+/** 从 checklist 提取全部 [x] 行（对齐 bash grep '\[x\]'） */
+function checkedLines(content: string): string[] {
+  return content.split("\n").filter((l) => l.includes("[x]"))
+}
+
+/** 定位 spec 目录下的 checklist/tasks（对齐 bash 目录优先 + find fallback） */
+function locateSpecFile(specRoot: string, planKw: string, name: string): string {
+  const specDir = join(specRoot, planKw)
+  const direct = join(specDir, name)
+  if (existsSync(direct)) return direct
+  // fallback: 搜索（对齐 bash find .qoder/specs -name ... -path "*${plan_kw}*"）
+  if (existsSync(specRoot)) {
+    for (const dir of readdirSync(specRoot)) {
+      if (!dir.includes(planKw)) continue
+      const cand = join(specRoot, dir, name)
+      if (existsSync(cand)) return cand
+    }
+  }
+  return direct
+}
+
+/**
+ * spec 目录默认定位（治理层中立——禁止偏爱任何 adapter）:
+ *   <projectDir>/<magicDir>/specs（magicDir 唯一解析链推导）；推导失败 → ""（fail-closed）。
+ *   adapter 协议差异（如 qoder 显式 .qoder/specs）由调用方显式传参，不下沉到治理层默认值。
+ */
+function defaultSpecRoot(): string {
+  const projectDir = process.env.PROJECT_DIR || process.cwd()
+  const magicDir = tryResolveMagicDir()
+  return magicDir ? join(projectDir, magicDir, "specs") : ""
+}
+
+/**
+ * checklist 质量检查（逐字对齐 bash review-checklist.sh）。
+ * 返回: 问题清单文本（无问题时为 "  ✅ Review: checklist 质量检查通过"）。
+ * Step 0 准入失败时返回 "  ❌ Step 0 未完成:..."（调用方 exit 1 语义由 CLI 层执行）。
+ */
+export function checkReviewQuality(handoff: string, addRoute: string, specRoot?: string): string {
+  if (handoff === "") return ""
+  const projectDir = process.env.PROJECT_DIR || process.cwd()
+  const planKw = basename(handoff).replace(/-handoff.*$/, "")
+  const root = specRoot ?? defaultSpecRoot()
+  const checklist = locateSpecFile(root, planKw, "checklist.md")
+  const tasksFile = locateSpecFile(root, planKw, "tasks.md")
+
+  let issues = ""
+
+  // ── 0. Step 0 准入: ADD 核心文档存在性（BLOCKING）──
+  let missingDocs = ""
+  if (!existsSync(handoff)) {
+    missingDocs += " Handoff"
+  } else {
+    const h = readFileSync(handoff, "utf-8")
+    let hSections = 0
+    if (h.includes("spec 文件")) hSections++
+    if (h.includes("你要改的文件")) hSections++
+    if (h.includes("验证标准")) hSections++
+    if (h.includes("完成后记录 ADD-7 审计")) hSections++
+    if (hSections < 4) missingDocs += ` Handoff(缺章节:${hSections}/4)`
+  }
+  if (!existsSync(addRoute)) {
+    missingDocs += " add-route"
+  } else {
+    const ar = readFileSync(addRoute, "utf-8")
+    if (!ar.includes("Task 映射表") && !ar.includes("文件清单")) {
+      missingDocs += " add-route(缺Task映射/文件清单)"
+    }
+  }
+  if (!existsSync(checklist)) {
+    missingDocs += " checklist"
+  } else {
+    const cl = readFileSync(checklist, "utf-8")
+    if (!cl.includes("[T]")) missingDocs += " checklist(无[T]项)"
+  }
+  if (!existsSync(tasksFile)) {
+    missingDocs += " tasks"
+  } else {
+    const tk = readFileSync(tasksFile, "utf-8")
+    if (!/Task|\[ \]/.test(tk)) missingDocs += " tasks(无Task项)"
+  }
+  if (missingDocs !== "") {
+    return `  ❌ Step 0 未完成:${missingDocs.trim().replace(/ /g, ", ")} 文件缺失。回退 Step 0.5/Step 1 补建后再进入代码实现。`
+  }
+
+  // ── 1-4. checklist 质量 ──
+  if (existsSync(checklist) && existsSync(tasksFile)) {
+    const cl = readFileSync(checklist, "utf-8")
+    const clChecked = checkedLines(cl).length
+    const clOpen = (cl.match(/\[ \]/g) || []).length
+    const tkChecked = (readFileSync(tasksFile, "utf-8").match(/\[x\]/g) || []).length
+
+    if (clOpen > 0) {
+      issues += `  ⚠️ checklist 有 ${clOpen} 项未勾选\n`
+    }
+
+    // 2. [T] 项是否都有 [x]
+    const tItems = (cl.match(/\[T\]/g) || []).length
+    const tChecked = checkedLines(cl).filter((l) => l.includes("[T]")).length
+    if (tItems > tChecked) {
+      issues += `  ⚠️ [T] 编译期验证: ${tChecked}/${tItems} 通过\n`
+    }
+
+    // 3. 证据缺失检测：[x] 但缺 — 证据: 标记
+    let noEvidence = 0
+    for (const line of checkedLines(cl)) {
+      if (/—\s*证据:\s*\S/.test(line)) continue
+      if (/npx|tsc|vitest|grep|✅|cmq[0-9a-z]{10}|18\/18|exit.*0/.test(line)) continue
+      noEvidence++
+    }
+    if (noEvidence > 0) {
+      issues += `  ❌ ${noEvidence} 项 [x] 缺少验收证据（需附 — 证据: tsc/vitest/grep/审计ID 等）\n`
+    }
+
+    // 4. 审计链
+    const withAudit = checkedLines(cl).filter((l) => /cmq[a-z0-9]{10,}/.test(l)).length
+    const fakeAudit = checkedLines(cl).filter((l) => /cmq\.\.\.|cmqxxx|审计.*cmq\.\./.test(l)).length
+    if (fakeAudit > 0) {
+      issues += `  ❌ ${fakeAudit} 项 [x] 使用了占位符审计ID（cmq.../cmqxxx），必须调 record_dev_operation 获取真实 cuid 后替换\n`
+    }
+    const withEvidence = checkedLines(cl).filter((l) =>
+      /tsc|vitest|npx|grep|✅|验证|确认|compgen|审计.*cmq[a-z0-9]{10}/.test(l)
+    ).length
+    if (withEvidence > 0 && withAudit === 0) {
+      issues += `  📎 初验: ${withEvidence}/${clChecked} 项有证据但未写审计 ID（需调 record_dev_operation 落库）\n`
+    } else if (withAudit > 0 && withAudit < clChecked) {
+      issues += `  📎 复验: ${withAudit}/${clChecked} 项引用审计 ID。${withEvidence}/${clChecked} 项有证据。证据一致则不需追写 devlog日志(走mcp)\n`
+    }
+  }
+
+  // 5. add-route Step 闭环
+  if (existsSync(addRoute)) {
+    const ar = readFileSync(addRoute, "utf-8")
+    const arOpen = (ar.match(/\[ \]/g) || []).length
+    if (arOpen > 0) {
+      issues += `  ⚠️ add-route ${arOpen} Step 未闭环\n`
+    }
+  }
+
+  // 6. handoff 审计表同步
+  if (existsSync(handoff) && existsSync(checklist)) {
+    const h = readFileSync(handoff, "utf-8")
+    const cl = readFileSync(checklist, "utf-8")
+    const cuids = [...new Set(cl.match(/cmq[a-z0-9]{10,}/g) || [])]
+    const newCuids = cuids.filter((c) => !h.includes(c))
+    if (newCuids.length > 0) {
+      issues += `  ❌ handoff 审计表未同步: ${newCuids.length} 个 cuid 在 checklist 中存在但 handoff 中缺失（需更新 handoff ADD-7 表 + query_audit_logs 命令）\n`
+    }
+  }
+
+  if (issues === "") {
+    return "  ✅ Review: checklist 质量检查通过"
+  }
+  return `  📋 Review 发现问题:\n${issues}`
+}
+
+/**
+ * ReviewChecklist 服务类（OOP 封装，Task 5.1 继承体系）:
+ *   run() = 检查 + 输出 + exit 语义（Step 0 准入失败 → exit 1，对齐 bash 原文）。
+ *   specRoot 缺省 = 治理层中立推导（<projectDir>/<magicDir>/specs）；adapter 显式传参覆盖。
+ */
+export class ReviewChecklistGuard {
+  private readonly specRoot: string | undefined
+
+  constructor(specRoot?: string) {
+    this.specRoot = specRoot
+  }
+
+  /** 主入口：返回 exit code（0 放行 / 1 Step 0 准入失败） */
+  run(handoff: string, addRoute: string): number {
+    if (handoff === "") return 0
+    const out = checkReviewQuality(handoff, addRoute, this.specRoot)
+    process.stdout.write(out + "\n")
+    // Step 0 准入失败 → exit 1（对齐 bash）
+    if (out.startsWith("  ❌ Step 0 未完成")) return 1
+    return 0
+  }
+}