add-coder 0.3.24 → 0.3.25

package/templates/core/scripts/mcp-server/tools/hitl.ts

@@ -2,14 +2,18 @@ import * as z from "zod/v4"
 import { inputRequired, acceptedContent } from "@modelcontextprotocol/server"
 import type { ToolRegistrar } from "./registrar.js"
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from "fs"
-import { join, basename } from "path"
+import { join, basename, relative } from "path"
 import { textResponse, errorResponse } from "../shared/response.js"
 import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import { prisma } from "../shared/prisma.js"
 import { HITL_INTERACTION_CONFIG } from "../shared/hitl-interaction.strategy.js"
+import type { HitlRow, PlanRow } from "../shared/db-types.js"
+import { HitlRowSchema, PlanRowSchema, validatedDelegate } from "../shared/db-types.js"
 
+// 无类型边界单点（zod 托管）：动态加载的 prisma client 在此一次性转为运行期校验的泛型委托
 const db = {
-  get hitl() { return prisma.hitlRecord as unknown as Record<string, (...a: unknown[]) => unknown> },
+  get hitl() { return validatedDelegate<HitlRow>(prisma.hitlRecord, HitlRowSchema, "HitlRecord") },
+  get plan() { return validatedDelegate<PlanRow>(prisma.planRecord, PlanRowSchema, "PlanRecord") },
 }
 
 export function registerHitlTools(server: ToolRegistrar) {
@@ -22,18 +26,32 @@ export function registerHitlTools(server: ToolRegistrar) {
 
   // genui 模式客户端（如 Qoder）未声明 elicitation capability，弹框必然失败 → 返回 genui 流程引导
   function _genuiGuide(recallStep: string): string {
+    // D2（Review 回流）：widget 模板多候选探测——sync 实际落脚含 core/ 层级，
+    // toml 原值为源仓路径（消费方不存在），逐候选回退，全 miss 显式告警。
+    // 输出必须为 workspace 相对路径：genui show_widget 实测拒绝绝对路径（2026-08-11 验证）。
     let widgetPath = ""
     if (_interaction.widget_path) {
-      // genui show_widget 仅接受 workspace 相对路径，绝对路径会被拒
-      const bakedRel = join(MAGIC_DIR, "templates", basename(_interaction.widget_path))
-      widgetPath = existsSync(join(PROJECT_ROOT, bakedRel)) ? bakedRel : _interaction.widget_path
+      const base = basename(_interaction.widget_path)
+      const candidates = [
+        join(PROJECT_ROOT, MAGIC_DIR, "templates", "core", "templates", base),
+        join(PROJECT_ROOT, MAGIC_DIR, "templates", base),
+        join(PROJECT_ROOT, _interaction.widget_path),
+      ]
+      const abs = candidates.find((p) => existsSync(p)) ?? ""
+      widgetPath = abs ? relative(PROJECT_ROOT, abs) : ""
     }
-    return [
+    const lines = [
       `⚠️ 当前环境（${MAGIC_DIR}）客户端不支持 elicitation 弹框，交互模式已裁决为 genui。请按以下流程完成：`,
-      `1. 调用 genui show_widget 渲染审批表单${widgetPath ? `（widget_path: ${widgetPath}，workspace 相对路径，维度列表经 data 注入）` : ""}`,
-      `2. 用户在 widget 中逐项拍板`,
-      `3. ${recallStep}`,
-    ].join("\n")
+    ]
+    if (widgetPath) {
+      lines.push(`1. 调用 genui show_widget 渲染审批表单（widget_path: ${widgetPath}，workspace 相对路径，维度列表经 data 注入）`)
+    } else {
+      lines.push(`1. ⚠️ widget 模板缺失（hitl-approval-widget.html 未同步到 ${MAGIC_DIR}/templates/），请先执行 add-coder sync 补齐，再走 genui show_widget 流程`)
+      lines.push(`   - 兜底可用 inline widget_code 渲染；数据契约: window.__WIDGET_DATA__ = { planName, type, dimensions: [{name, content}] }`)
+    }
+    lines.push(`2. 用户在 widget 中逐项拍板`)
+    lines.push(`3. ${recallStep}`)
+    return lines.join("\n")
   }
 
   // ═══════════════ 辅助：解析 inputRequired 响应 ═══════════════
@@ -115,6 +133,19 @@ export function registerHitlTools(server: ToolRegistrar) {
     try {
       const { planName, type, dimensions, _fallback, _use_genui } = args as { planName: string; type: string; dimensions?: { name: string; content?: string }[]; _fallback?: boolean; _use_genui?: boolean }
 
+      // ── planName 入口强校验（弱模型友好：不合规返回可照抄修正调用，而非让错误漂移） ──
+      const _pnValid = /-(plan|collab-contract)-v\d+$/.test(planName)
+        || /-review(-v\d+|-implementation(-v\d+)?|-runtime(-v\d+)?)?$/.test(planName)
+        || planName.endsWith(".hitl")
+      if (!_pnValid) {
+        const suggested = type === "COLLAB_CONTRACT" ? `${planName}-collab-contract-v1` : `${planName}-plan-v1`
+        return errorResponse(
+          `planName 格式不合规: "${planName}"\n` +
+          `要求: 以 -plan-v{n} / -collab-contract-v{n} / -review-* 结尾（哨兵命名依赖此后缀剥离）\n` +
+          `可照抄修正: create_hitl({ planName: "${suggested}", type: "${type}" })`
+        )
+      }
+
       // ── 最终维度内容（从弹框结果合并） ──
       let finalDims: { name: string; content: string }[] = []
 
@@ -210,21 +241,44 @@ export function registerHitlTools(server: ToolRegistrar) {
       }
 
       // ── 原始业务逻辑（创建 DB + 生成 hitl.md。降级模式也走此路） ──
+      const now = new Date()
+      const yyyyMM = `${now.getFullYear()}-${String(now.getMonth()+1).padStart(2,"0")}`
+      const dd = String(now.getDate()).padStart(2,"0")
+      const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans", yyyyMM, dd)
+      const proposalPath = join(plansDir, `${planName}.hitl.md`)
+
+      // ── FK 断环修复：HitlRecord.planName 外键要求 PlanRecord 先行。
+      //    全新 Plan 首次审批时自动预置占位行（约定式 planPath，文件存在性即指纹），
+      //    Plan 文件写出后由 plan_track 回刷真实路径——机器占位机器回刷，不消耗 LLM 认知。
+      //    D5（Review 回流）：占位路径按 type 分流——PLAN_REVIEW 指向 reviews/ 目录，
+      //    review 文档写出后由 review_track/plan_track 回刷消解（避免永久悬空）。 ──
+      let planProvisioned = false
+      const existingPlan = await db.plan.findFirst({ where: { planName } })
+      if (!existingPlan) {
+        const placeholderPath = type === "PLAN_REVIEW"
+          ? join(PROJECT_ROOT, MAGIC_DIR, "reviews", yyyyMM, dd, `${planName}.md`)
+          : join(plansDir, `${planName}.md`)
+        await db.plan.create({
+          data: {
+            planName,
+            planPath: placeholderPath,
+            planKeyword: String(planName).replace(/-(plan|collab-contract|review)-v\d+$/, ""),
+            totalTasks: 0, doneTasks: 0, checklistT: 0, checklistTDone: 0, checklistR: 0,
+          },
+        })
+        planProvisioned = true
+      }
+
       const rows = await db.hitl.findMany({
         where: { planName },
         orderBy: { round: "desc" },
         take: 1,
-      }) as { round: number | null }[]
+      })
       const round = (rows[0]?.round ?? 0) + 1
       const record = await db.hitl.create({
-        data: { planName, round, type, status: "DRAFT" },
-      }) as { id: string }
+        data: { planName, round, type: type as HitlRow["type"], status: "DRAFT" },
+      })
       // 生成 hitl.md
-      const now = new Date()
-      const yyyyMM = `${now.getFullYear()}-${String(now.getMonth()+1).padStart(2,"0")}`
-      const dd = String(now.getDate()).padStart(2,"0")
-      const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans", yyyyMM, dd)
-      const proposalPath = join(plansDir, `${planName}.hitl.md`)
       const isoNow = now.toISOString()
 
       // 动态生成维度表格行
@@ -270,10 +324,18 @@ export function registerHitlTools(server: ToolRegistrar) {
         `recordId: ${record.id}`,
       ]
       if (finalDims.length > 0) lines.push(`dimensions: ${finalDims.length} 项`)
+      if (planProvisioned) lines.push(`PlanRecord: 自动预置（占位行，Plan 文件写出后 plan_track 回刷真实路径）`)
       if (_fallback) lines.push(`mode:     _fallback (跳过 dialog，原始代码降级)`)
       return textResponse(lines.join("\n"))
     } catch (e) {
-      return errorResponse(`create_hitl 失败: ${e instanceof Error ? e.message : String(e)}`)
+      const msg = e instanceof Error ? e.message : String(e)
+      if (msg.includes("Foreign key")) {
+        return errorResponse(
+          `create_hitl 外键异常（PlanRecord 自动预置可能失败）: ${msg}\n` +
+          `处方: 检查数据库连接与 PlanRecord 表结构，或改用 plan_track({ planName }) 先建立追踪记录后重试`
+        )
+      }
+      return errorResponse(`create_hitl 失败: ${msg}`)
     }
   })
 
@@ -296,7 +358,13 @@ export function registerHitlTools(server: ToolRegistrar) {
     }),
   }, async (args: Record<string, unknown>, ctx: Record<string, unknown>) => {
     try {
-      const { planName, type, status, reason, _fallback, _use_genui } = args as Record<string, string | boolean | undefined>
+      const _raw = args as Record<string, string | boolean | undefined>
+      const planName = String(_raw.planName ?? "")
+      const type = String(_raw.type ?? "")
+      const status = typeof _raw.status === "string" ? _raw.status : undefined
+      const reason = typeof _raw.reason === "string" ? _raw.reason : undefined
+      const _fallback = _raw._fallback === true
+      const _use_genui = _raw._use_genui === true
 
       // ── 交互式确认（非降级模式且非 genui 模式） ──
       let effectiveStatus = status as string | undefined
@@ -384,26 +452,38 @@ export function registerHitlTools(server: ToolRegistrar) {
       // 降级模式必须传 status
 
       // ── 原始业务逻辑（更新 DB + 写哨兵文件。降级模式也走此路） ──
-      const s = effectiveStatus!
+      const s = effectiveStatus as HitlRow["status"]
+      const qType = type as HitlRow["type"]
       const rows = await db.hitl.findMany({
-        where: { planName, type },
+        where: { planName, type: qType },
         orderBy: { round: "desc" },
         take: 1,
-      }) as Record<string, unknown>[]
+      })
       if (!rows.length) return errorResponse(`未找到 HITL 记录: planName=${planName}, type=${type}`)
       const r = rows[0]
-      const prevStatus = r.status as string
+      const prevStatus = r.status
       if (prevStatus === "TONGYI" || prevStatus === "BOHUI") {
         return errorResponse(`HITL 已终态（${prevStatus}），不可再更新。BOHUI 后请用 create_hitl 新建 round。`)
       }
       // 更新
-      const data: Record<string, unknown> = { status: s }
+      const data: Partial<HitlRow> = { status: s }
       if (s === "TONGYI") data.approvedAt = new Date()
       if (s === "BOHUI") {
         data.rejectedAt = new Date()
-        if (reason) data.rejectReason = reason
+        if (reason) data.rejectReason = String(reason)
       }
       await db.hitl.update({ where: { id: r.id }, data })
+      // ── BOHUI 清算：Plan 文件不存在 → 预置 PlanRecord 无存续理由，连同本 plan 全部 HitlRecord 删除（孤儿即时归零）。
+      //    已写出文件的驳回 Plan 保留记录（历史价值）。 ──
+      let orphanCleaned = ""
+      if (s === "BOHUI") {
+        const planRow = await db.plan.findFirst({ where: { planName } })
+        if (planRow && !existsSync(planRow.planPath)) {
+          await db.hitl.deleteMany({ where: { planName } })
+          await db.plan.delete({ where: { id: planRow.id } })
+          orphanCleaned = `预置数据已清算（Plan 文件不存在: ${planRow.planPath}）`
+        }
+      }
       // 写哨兵文件（双命名：原始 planName + pre-tool-use hook §C 剥后缀推导名，保持闸门一致）
       const markerDir = join(PROJECT_ROOT, MAGIC_DIR, "hitl")
       mkdirSync(markerDir, { recursive: true })
@@ -440,7 +520,8 @@ export function registerHitlTools(server: ToolRegistrar) {
       if (s === "BOHUI") {
         lines.push(`marker:   ${marker}`)
         lines.push(`reason:   ${reason || "—"}`)
-        lines.push(``, `💡 驳回后请用 create_hitl 新建 round ${Number(r.round) + 1} 重新发起审批。`)
+        if (orphanCleaned) lines.push(`cleanup:  ${orphanCleaned}`)
+        lines.push(``, `💡 驳回后请用 create_hitl 新建 round ${r.round + 1} 重新发起审批。`)
       }
       return textResponse(lines.join("\n"))
     } catch (e) {
@@ -458,11 +539,12 @@ export function registerHitlTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { planName, type } = args as { planName: string; type?: string }
+      const qType = (type || "PLAN") as HitlRow["type"]
       const rows = await db.hitl.findMany({
-        where: { planName, type },
+        where: { planName, type: qType },
         orderBy: { round: "desc" },
         take: 1,
-      }) as Record<string, unknown>[]
+      })
       if (!rows.length) {
         return textResponse(
           `📋 HITL: 未发起\n` +
@@ -472,7 +554,7 @@ export function registerHitlTools(server: ToolRegistrar) {
         )
       }
       const r = rows[0]
-      const status = r.status as string
+      const status = r.status
       const icons: Record<string, string> = { DRAFT: "⏳", SUBMITTED: "📤", TONGYI: "✅", BOHUI: "❌" }
       const icon = icons[status] || "❓"
       const lines = [
@@ -481,13 +563,13 @@ export function registerHitlTools(server: ToolRegistrar) {
         `planName:   ${planName}`,
         `type:       ${r.type}`,
         `round:      ${r.round}`,
-        r.createdAt ? `createdAt:  ${(r.createdAt as Date).toISOString()}` : null,
-        r.approvedAt ? `approvedAt: ${(r.approvedAt as Date).toISOString()}` : null,
-        r.rejectedAt ? `rejectedAt: ${(r.rejectedAt as Date).toISOString()}` : null,
+        r.createdAt ? `createdAt:  ${r.createdAt.toISOString()}` : null,
+        r.approvedAt ? `approvedAt: ${r.approvedAt.toISOString()}` : null,
+        r.rejectedAt ? `rejectedAt: ${r.rejectedAt.toISOString()}` : null,
         r.rejectReason ? `reason:     ${r.rejectReason}` : null,
       ].filter(Boolean)
       if (status === "BOHUI") {
-        lines.push(``, `💡 驳回后可 create_hitl 新建 round ${Number(r.round) + 1}。`)
+        lines.push(``, `💡 驳回后可 create_hitl 新建 round ${r.round + 1}。`)
       }
       if (status === "DRAFT" || status === "SUBMITTED") {
         lines.push(``, `操作: update_hitl({ planName: "${planName}", type: "${r.type}", status: "TONGYI|BOHUI" })`)

package/templates/core/scripts/mcp-server/tools/plan.ts

@@ -5,9 +5,12 @@ import { join, basename } from "path"
 import { textResponse, errorResponse } from "../shared/response.js"
 import { readFileSafe, readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import { prisma } from "../shared/prisma.js"
+import type { PlanRow } from "../shared/db-types.js"
+import { PlanRowSchema, validatedDelegate } from "../shared/db-types.js"
 
+// 无类型边界单点（zod 托管）：动态加载的 prisma client 在此一次性转为运行期校验的泛型委托
 const db = {
-  get plan() { return prisma.planRecord as unknown as Record<string, (...a: unknown[]) => unknown> },
+  get plan() { return validatedDelegate<PlanRow>(prisma.planRecord, PlanRowSchema, "PlanRecord") },
 }
 
 export function registerPlanTools(server: ToolRegistrar) {
@@ -81,8 +84,8 @@ export function registerPlanTools(server: ToolRegistrar) {
         )
         const addRoutePath = addRouteFile ? join(plansDir, addRouteFile) : undefined
         // upsert PlanRecord
-        const existing = await db.plan.findFirst({ where: { planName: t.name } }) as Record<string, unknown> | null
-        const data = {
+        const existing = await db.plan.findFirst({ where: { planName: t.name } })
+        const data: Partial<PlanRow> = {
           planPath: t.path,
           specPath: existsSync(specPath) ? specPath : undefined,
           tasksPath: existsSync(tasksPath) ? tasksPath : undefined,
@@ -100,6 +103,20 @@ export function registerPlanTools(server: ToolRegistrar) {
           newPlans.push(t.name.replace(/-plan-v\d+$/, ""))
         }
       }
+      // ── 孤儿对账（全量扫描时）：PlanRecord 存在但 planPath 文件缺失 → 悬空清单。
+      //    来源：create_hitl 预置行被中断 / 用户放弃未清理。允许暂时存在，不允许不可见。 ──
+      if (!pn) {
+        const allPlans = await db.plan.findMany({ orderBy: { createdAt: "desc" } })
+        const orphans = allPlans.filter(p => !existsSync(p.planPath))
+        if (orphans.length > 0) {
+          results.push("", `⚠️ 悬空 Plan（记录在、文件缺失）— 续写或清理:`)
+          const cutoff = Date.now() - 14 * 86400000
+          for (const o of orphans) {
+            const stale = o.createdAt.getTime() < cutoff
+            results.push(`   ${stale ? "🔴 超 14 天，建议清理" : "·"} ${o.planName} → ${o.planPath}`)
+          }
+        }
+      }
       // scanAll 完成后提示用户调用 review_track 填充缺陷指标
       if (newPlans.length > 0) {
         results.push(``, `💡 以下 Plan 为新创建，ReviewRecord 暂无 P0/P1 指标：`)
@@ -120,13 +137,13 @@ export function registerPlanTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { planName } = args as { planName: string }
-      const plan = await db.plan.findFirst({ where: { planName } }) as Record<string, unknown> | null
+      const plan = await db.plan.findFirst({ where: { planName } })
       if (!plan) return textResponse(`📋 Plan: 未跟踪\nplanName: ${planName}\n\n操作: plan_track({ planName: "${planName}" })`)
-      const t = plan.totalTasks as number || 0
-      const d = plan.doneTasks as number || 0
-      const ct = plan.checklistT as number || 0
-      const ctd = plan.checklistTDone as number || 0
-      const cr = plan.checklistR as number || 0
+      const t = plan.totalTasks || 0
+      const d = plan.doneTasks || 0
+      const ct = plan.checklistT || 0
+      const ctd = plan.checklistTDone || 0
+      const cr = plan.checklistR || 0
       const taskPct = t > 0 ? Math.round((d / t) * 100) : 0
       const lines = [
         `📊 ${planName}`,
@@ -155,16 +172,16 @@ export function registerPlanTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { planName } = args as { planName: string }
-      const plan = await db.plan.findFirst({ where: { planName } }) as Record<string, unknown> | null
+      const plan = await db.plan.findFirst({ where: { planName } })
       if (!plan) return errorResponse(`PlanRecord 未找到: ${planName}`)
-      const planPath = plan.planPath as string
+      const planPath = plan.planPath
       if (!existsSync(planPath)) return errorResponse(`Plan 文件不存在: ${planPath}`)
       const content = readFileSync(planPath, "utf-8")
-      const t = plan.totalTasks as number || 0
-      const d = plan.doneTasks as number || 0
-      const ct = plan.checklistT as number || 0
-      const ctd = plan.checklistTDone as number || 0
-      const cr = plan.checklistR as number || 0
+      const t = plan.totalTasks || 0
+      const d = plan.doneTasks || 0
+      const ct = plan.checklistT || 0
+      const ctd = plan.checklistTDone || 0
+      const cr = plan.checklistR || 0
       const pct = t > 0 ? Math.round((d / t) * 100) : 0
       const snapshot = [
         `## 📊 Plan 进度快照`,

package/templates/core/scripts/mcp-server/tools/review.ts

@@ -5,14 +5,17 @@ import { join, basename } from "path"
 import { textResponse, errorResponse } from "../shared/response.js"
 import { readFileSafe, readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import { prisma } from "../shared/prisma.js"
+import type { PlanRow, ReviewRow } from "../shared/db-types.js"
+import { PlanRowSchema, ReviewRowSchema, validatedDelegate } from "../shared/db-types.js"
 
 const db = {
-  get review() { return prisma.reviewRecord as unknown as Record<string, (...a: unknown[]) => unknown> },
-  get plan() { return prisma.planRecord as unknown as Record<string, (...a: unknown[]) => unknown> },
+  get review() { return validatedDelegate<ReviewRow>(prisma.reviewRecord, ReviewRowSchema, "ReviewRecord") },
+  get plan() { return validatedDelegate<PlanRow>(prisma.planRecord, PlanRowSchema, "PlanRecord") },
 }
 
-// 检测 review 类型
-function detectReviewType(filename: string): string {
+// 检测 review 类型（与 ReviewRowSchema.type 枚举对齐）
+type ReviewTypeValue = "PLAN_REVIEW" | "IMPLEMENTATION" | "RUNTIME"
+function detectReviewType(filename: string): ReviewTypeValue {
   const l = filename.toLowerCase()
   if (l.includes("implementation")) return "IMPLEMENTATION"
   if (l.includes("runtime")) return "RUNTIME"
@@ -67,9 +70,9 @@ export function registerReviewTools(server: ToolRegistrar) {
         // 需要用 contains 匹配，而不是 exact match
         const planMatch = await db.plan.findFirst({
           where: { planName: { contains: derivedPlan } },
-        }) as Record<string, unknown> | null
+        })
         const actualPlanName = planMatch
-          ? (planMatch.planName as string)
+          ? planMatch.planName
           : derivedPlan // fallback，让外键约束报错时提示更清晰
 
         const content = await readFileSafe(fullPath)
@@ -79,7 +82,7 @@ export function registerReviewTools(server: ToolRegistrar) {
         const stats = countIssueType(content)
         const record = await db.review.findFirst({
           where: { planName: actualPlanName, type: rtype },
-        }) as Record<string, unknown> | null
+        })
 
         const data = {
           reviewPath: fullPath,
@@ -117,7 +120,7 @@ export function registerReviewTools(server: ToolRegistrar) {
       const rows = await db.review.findMany({
         where: { planName },
         orderBy: { type: "asc" },
-      }) as Record<string, unknown>[]
+      })
 
       if (!rows.length) {
         return textResponse(
@@ -155,7 +158,7 @@ export function registerReviewTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { planName } = args as { planName: string }
-      const rows = await db.review.findMany({ where: { planName } }) as Record<string, unknown>[]
+      const rows = await db.review.findMany({ where: { planName } })
 
       if (!rows.length) return errorResponse(`无 ReviewRecord: ${planName}`)
 

package/templates/core/templates/simple-plan-template.md

@@ -34,6 +34,19 @@
 
 ---
 
+## Review 回流记录
+
+> **功能**：总览索引——记录所有 review 发现及其回流落点。读者可从表快速扫描“有哪些问题”，再跳转到对应位置看“改了什么”。
+> **回流规则**：每条发现必须在 Plan 体中对应位置有落点（补充 Task / 修正描述 / 新增约束），表行与落点双向一致。
+
+| # | 来源阶段 | 严重度 | 发现 | 回流落点 |
+|---|:---:|:---:|------|------|
+| R1 | Plan Review | 🔴高 | {发现简述} | Task {N} / §{章节}：{具体修改} |
+
+> **来源阶段枚举**：`Plan Review`（Step 0.6.5 设计审查）| `Impl Review`（Step 3-7 实现审查）| `Runtime Review`（Step 8+ 运行时纠偏）
+
+---
+
 ## 一、Plan 概述
 
 - **现状**: 一句话描述当前问题

package/templates/core/templates/simple-plan-template.schema.json

@@ -12,6 +12,16 @@
             "required": true,
             "note": "AI 必须先在此表中列出实际完整文件路径和方案决策，等待人类拍板后再执行。禁止偷懒写'等 N 个文件'。"
         },
+        {
+            "id": "review-backflow",
+            "heading": "## Review 回流记录",
+            "required": true,
+            "note": "总览索引表：记录所有 review 发现及其回流落点。列：'#' + '来源阶段' + '严重度' + '发现' + '回流落点'。来源阶段枚举：Plan Review / Impl Review / Runtime Review。",
+            "validation": {
+                "columns": ["#", "来源阶段", "严重度", "发现", "回流落点"],
+                "source_phase_enum": ["Plan Review", "Impl Review", "Runtime Review"]
+            }
+        },
         {
             "id": "changes",
             "heading": "## 二、变更范围",

package/templates/core/templates/standard-plan-template.md

@@ -37,6 +37,19 @@
 
 ---
 
+## Review 回流记录
+
+> **功能**：总览索引——记录所有 review 发现及其回流落点。读者可从表快速扫描“有哪些问题”，再跳转到对应位置看“改了什么”。
+> **回流规则**：每条发现必须在 Plan 体中对应位置有落点（补充 Task / 修正描述 / 新增约束），表行与落点双向一致。
+
+| # | 来源阶段 | 严重度 | 发现 | 回流落点 |
+|---|:---:|:---:|------|------|
+| R1 | Plan Review | 🔴高 | {发现简述} | Task {N.M} / §{章节}：{具体修改} |
+
+> **来源阶段枚举**：`Plan Review`（Step 0.6.5 设计审查）| `Impl Review`（Step 3-7 实现审查）| `Runtime Review`（Step 8+ 运行时纠偏）
+
+---
+
 ## 一、背景与目标
 
 ### 1.1 问题现状

package/templates/core/templates/standard-plan-template.schema.json

@@ -12,6 +12,16 @@
             "required": true,
             "note": "AI 必须先在此表中列出全部关键决策，等待人类拍板后再展开详细设计。"
         },
+        {
+            "id": "review-backflow",
+            "heading": "## Review 回流记录",
+            "required": true,
+            "note": "总览索引表：记录所有 review 发现及其回流落点。列：'#' + '来源阶段' + '严重度' + '发现' + '回流落点'。来源阶段枚举：Plan Review / Impl Review / Runtime Review。",
+            "validation": {
+                "columns": ["#", "来源阶段", "严重度", "发现", "回流落点"],
+                "source_phase_enum": ["Plan Review", "Impl Review", "Runtime Review"]
+            }
+        },
         {
             "id": "background",
             "heading": "## 一、背景与目标",