@andyqiu/codeforge 0.3.10 → 0.3.12

package/assets/adr-init/docs/adr/README.md

@@ -0,0 +1,105 @@
+# Architecture Decision Records (ADR)
+
+本目录记录项目所有架构与设计决策。每个决策 = 一份独立 ADR 文件，**永不删除、永不编辑历史**。
+
+## 为什么需要 ADR
+
+代码告诉你 **What**（做了什么），ADR 告诉你 **Why**（当时为什么这么决定）。
+半年后看到一段奇怪的代码想重构？先翻 ADR——也许当年就是因为某个权衡才这么写的，重构会撞回老坑。
+
+## 编号规则
+
+- **新 ADR**：文件名 `<kebab-slug>.md`（例：`add-redis-cache.md`、`split-auth-service.md`），无序号、无日期前缀；时间靠 frontmatter `date` 字段，索引按 date 排序
+- **slug 唯一性**：文件名 stem（去 `.md`）在 `docs/adr/` 下不允许重名，`scripts/adr-check.mjs` 强校验
+- **不允许新 ADR 用 `NNNN-` 前缀**（防回潮），`adr-check.mjs` 会报错
+- `template.md` 是模板，不计入正式编号；frontmatter 不再有 `adr` 字段
+
+## 状态机
+
+```
+Proposed ──accept──▶ Accepted ──supersede──▶ Superseded
+   │                     │
+   └──reject──▶ Rejected └──deprecate──▶ Deprecated
+```
+
+| 状态 | 含义 | 何时用 |
+|---|---|---|
+| `Proposed` | 草拟中，未实施 | 出方案时 |
+| `Accepted` | 已实施，当前生效 | 代码落地后 |
+| `Superseded` | 被新 ADR 替换 | 必须填 `superseded-by: <slug>` |
+| `Deprecated` | 废弃但未替换（特性下线） | 单纯不再生效 |
+| `Rejected` | 提案被否，未实施 | 保留作历史参考 |
+
+**铁律**：`Status` 字段可改，其他内容**永不编辑**。要修正/补充 → 写新 ADR。
+
+## 三向引用约定
+
+每个 ADR 必须双向链接到 PRD（如有）和 Code：
+
+| 方向 | 怎么写 |
+|---|---|
+| ADR → PRD | frontmatter `prd-refs: ["§6.2"]`（如项目无 PRD 可填 `["TBD"]`） |
+| ADR → Code | frontmatter `code-refs: ["lib/foo.ts"]` |
+| PRD → ADR | PRD 章节末尾加注释 `<!-- ADR: <slug> -->` |
+| Code → ADR | 文件头注释 `// ADR:<slug>: 简短说明` |
+
+## 工作流（每次新决策走这 3 步）
+
+```
+1. 出方案时
+   → cp template.md docs/adr/<kebab-slug>.md       （slug 全局唯一即可，无需查最大编号）
+   → 填 Context / Options / Decision
+   → status: Proposed
+
+2. 实现时
+   → 代码注释加 // ADR:<slug>
+   → 更新 ADR frontmatter 的 code-refs
+
+3. 落地完成时
+   → ADR 改 status: Accepted
+   → 如果替换旧 ADR：老 ADR 加 superseded-by: <slug>（填新 ADR 的 slug）
+```
+
+## 强制约束
+
+- **scripts/adr-check.mjs**：校验三向引用 + status 闭环 + slug 唯一性 + 改动文件必须有对应 ADR
+- **.githooks/pre-commit**：commit 前自动跑 `adr-check.mjs --diff-mode=staged`
+- **.githooks/pre-push**：push 前自动跑 `adr-check.mjs --diff-mode=last-commit`（兜底）
+- **PR 模板**（可选）：`.github/pull_request_template.md` 必填 ADR checklist（新建 / 更新 / 无需，三选一）
+
+## 历史补全规则（触发式）
+
+不要求一次性补完历史，而是**触发式补全**：
+
+- 改到哪块代码 → 必须先补该代码对应的 ADR 才能改
+- `adr-check.mjs` 看 git diff，对未改文件只警告，对改动文件强校验
+- 这样永远不会出现"想改 X 但 X 没决策记录"的窘境
+
+## 启用 git hooks（首次 clone 后跑一次）
+
+````
+git config core.hooksPath .githooks
+````
+
+npm 项目可在 `package.json` 加 `"prepare": "git config core.hooksPath .githooks"`，`npm install` 时自动生效。
+
+也可以重跑 `codeforge adr-init --write-prepare` 让 codeforge 帮你合并 prepare 链路（写前会自动 backup `package.json`）。
+
+## 索引
+
+> 表格由 `scripts/adr-index-sync.mjs` 自动同步：按 `frontmatter.date` 升序排序（同 date 按 ID 二级排）。请勿手工编辑 marker 之间的内容。
+>
+> 重生成命令：`node scripts/adr-index-sync.mjs`
+
+<!-- adr-index:start -->
+| ID | Date | 标题 | 状态 | 替换关系 |
+|---|---|---|---|---|
+| template | — | Template（模板） | — | — |
+<!-- adr-index:end -->
+
+## 参考
+
+- [adr.github.io](https://adr.github.io/) — ADR 社区主站
+- [MADR](https://adr.github.io/madr/) — Markdown ADR 模板（本目录采用）
+- [Michael Nygard 原始论文](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
+- AWS Prescriptive Guidance — [ADR process](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html)

package/assets/adr-init/docs/adr/template.md

@@ -0,0 +1,83 @@
+---
+# ── ADR Frontmatter（必填字段）──
+# 注：新 ADR 不再用 `adr: NNNN` 数字编号字段；文件名本身就是唯一 slug 标识。
+#     所有 ADR 均为纯 slug 命名（`kebab-case-slug.md`），无数字前缀。
+title: "<决策的简短标题，10 个字以内>"
+status: Proposed
+date: 2026-01-01              # YYYY-MM-DD，确定决策的日期
+deciders:
+  - <Your Name>
+# 关系字段（可选，按需填写）
+supersedes: []                # 例：[some-old-slug]（用 slug，不能用数字）
+superseded-by: []             # 由后续 ADR 回填，本人通常不填
+# 三向引用（必填，至少各 1 条；新决策无对应实现时填 [TBD]）
+prd-refs:
+  - "TBD"                     # 例："§6.2 review 闭环"
+code-refs:
+  - "TBD"                     # 例："lib/auto-feedback.ts"
+tests:
+  - "TBD"                     # 例："tests/auto-feedback.test.ts"
+tags:
+  - architecture              # 自由分类：architecture / workflow / convention / tooling 等
+---
+
+# ADR: <决策标题>
+
+## Context（背景与问题）
+
+<2-4 段说明：当时遇到什么问题？为什么需要决策？相关约束是什么？
+不要写"我们决定 X"——那是 Decision 段的事。这里只描述"问题空间"。>
+
+## Options Considered（对比的备选方案）
+
+至少列 2 个候选方案，每个要写优劣。**只有一个候选** = 没真正决策。
+
+### Option 1: <方案 A 名称>
+- 优点：...
+- 缺点：...
+
+### Option 2: <方案 B 名称>（✅ 已选）
+- 优点：...
+- 缺点：...
+
+### Option 3: <方案 C 名称>
+- 优点：...
+- 缺点：...
+- 不选原因：...
+
+## Decision（最终决策）
+
+**采用 Option N**，关键理由（≤ 3 条）：
+
+1. ...
+2. ...
+3. ...
+
+## Consequences（代价与影响）
+
+### 正面
+- ...
+
+### 负面 / 代价
+- ...
+
+### 后续行动
+- 需要更新：...
+- 留待后续 ADR 处理：...（可写"无"）
+
+## References
+
+- 相关讨论 / Issue / PR：
+- 业界资料：
+- 灵感来源：
+
+---
+<!-- 复制本模板时：
+  1. 复制本文件 → `docs/adr/<kebab-slug>.md`
+     - slug = 决策内容的 kebab-case 描述（例：`add-redis-cache.md`、`split-auth-service.md`）
+     - **无需查最大编号**：新 ADR 不再用 NNNN- 前缀
+     - slug 需在整个 docs/adr/ 下唯一（adr-check.mjs 会校验）
+  2. 把 title 改为正式标题
+  3. 把 date 改为今天
+  4. 删除本注释块
+  -->

package/assets/adr-init/githooks/pre-commit.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env sh
+# Generated by codeforge adr-init — 提交前 ADR 体系合规校验
+#
+# 安装方式：
+#   git config core.hooksPath .githooks
+# 或 npm 项目可在 package.json scripts.prepare 加 "git config core.hooksPath .githooks"
+#
+# 紧急绕过（不推荐）：
+#   git commit --no-verify
+
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+cd "$ROOT" || exit 0
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "⚠️  未找到 node，跳过 ADR 校验（请安装 Node.js >= 20）"
+  exit 0
+fi
+
+# 1. ADR 文件改动 → 同步 README 索引
+STAGED_ADR=$(git diff --cached --name-only --diff-filter=ACMR \
+  | grep -E '^docs/adr/.*\.md$' \
+  | grep -v '^docs/adr/README\.md$' || true)
+
+if [ -n "$STAGED_ADR" ] && [ -f "$ROOT/scripts/adr-index-sync.mjs" ]; then
+  echo "📚 检测到 ADR 改动，自动同步 README 索引..."
+  if node "$ROOT/scripts/adr-index-sync.mjs"; then
+    if ! git diff --quiet docs/adr/README.md; then
+      git add docs/adr/README.md
+      echo "  ✓ docs/adr/README.md 已自动同步并加入 commit"
+    else
+      echo "  ✓ README 索引已是最新（无需改动）"
+    fi
+  else
+    echo "❌ adr-index-sync 失败，请手动跑 node scripts/adr-index-sync.mjs 后重试"
+    exit 1
+  fi
+fi
+
+# 2. ADR 合规校验（staged 模式）
+if [ -f "$ROOT/scripts/adr-check.mjs" ]; then
+  echo "🔍 ADR 合规校验中..."
+  ADR_STRICT=1 ADR_DIFF_MODE=staged node "$ROOT/scripts/adr-check.mjs" || {
+    echo "❌ ADR 校验失败 — commit 已阻断；紧急绕过 git commit --no-verify（不推荐）"
+    exit 1
+  }
+fi

package/assets/adr-init/githooks/pre-push.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env sh
+# Generated by codeforge adr-init — push 前 ADR 体系合规校验（last-commit 模式）
+#
+# 兜底 pre-commit 漏网（如有人 --no-verify commit）；扫最后一个 commit 的改动。
+#
+# 紧急绕过（不推荐）：
+#   git push --no-verify
+
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+cd "$ROOT" || exit 0
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "⚠️  未找到 node，跳过 ADR 校验（请安装 Node.js >= 20）"
+  exit 0
+fi
+
+if [ -f scripts/adr-check.mjs ]; then
+  echo "🔍 ADR 合规校验中（push 前 last-commit 模式）..."
+  ADR_STRICT=1 ADR_DIFF_MODE=last-commit node scripts/adr-check.mjs || {
+    echo "❌ ADR 校验失败 — push 已阻断；紧急绕过 git push --no-verify（不推荐）"
+    exit 1
+  }
+fi

package/assets/adr-init/scripts/adr-check.mjs

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+/**
+ * adr-check.mjs — ADR 体系合规校验（泛化版，由 codeforge adr-init 下发）
+ *
+ * 与 CodeForge 自仓库 scripts/adr-check.mjs 的区别：
+ *   - 增加 ADR_ROOT / ADR_DIR 环境变量参数化，便于在不同项目结构中复用
+ *   - 默认 ROOT 仍按 `path.resolve(__dirname, "..")` 解析（脚本放 scripts/ 子目录时指向项目根）
+ *   - PR 模板硬性必需 → 改为 warn（不强制目标项目用 .github/pull_request_template.md）
+ *   - 不含 CodeForge 专属业务逻辑
+ *
+ * 校验项：
+ *   A. ADR 文件结构（docs/adr/）
+ *      - 文件命名：纯 slug，小写字母开头，kebab-case，不允许数字开头
+ *      - slug 唯一性（文件名 stem 全局唯一）
+ *      - frontmatter 必填：title / status / date / deciders / code-refs
+ *      - status 合法（Proposed / Accepted / Superseded / Deprecated / Rejected）
+ *      - Superseded 必须有 superseded-by 指向
+ *      - supersedes 必须双向闭环（用 slug stem 互查）
+ *
+ *   B. 三向引用
+ *      - ADR 的 code-refs 列出的文件必须存在（[TBD] / "—" / N/A 跳过；支持 glob）
+ *      - ADR 的 prd-refs 章节必须能在 docs/PRD.md grep 到（warn，若 PRD 不存在则跳过）
+ *      - PRD 中 `<!-- ADR: <slug[, slug...]> -->` 注释引用的 ADR 必须真存在
+ *
+ *   C. 触发式历史补全
+ *      - 检查 git diff 改动文件
+ *      - 对每个 plugins/*.ts、workflows/*.yaml、tools/*.ts、agents/*.md、commands/*.md、lib/*.ts：
+ *        * 该文件必须能 grep 到 `ADR:<slug>` 或 `ADR-NNNN` 注释，或某 ADR 的 code-refs 包含它
+ *      - 迁移期起点：.adr-migration-start 文件读取（不存在则今天）
+ *      - 环境变量 ADR_STRICT=1 强制升级为错误（CI 用）
+ *      - 环境变量 ADR_DIFF_MODE=last-commit 用 push 前模式（默认 staged）
+ *
+ *   D. PR 模板存在性（warn-only，下发版不强制）
+ *
+ *   E. README 索引同步（调 adr-index-sync.mjs --check）
+ *
+ * 环境变量：
+ *   ADR_ROOT       项目根目录绝对/相对路径；默认 path.resolve(__dirname, "..")
+ *   ADR_DIR        ADR 目录；默认 <ROOT>/docs/adr
+ *   ADR_STRICT     "1" 时把触发式补全 warn 升级为 error
+ *   ADR_DIFF_MODE  "last-commit" | "staged"（默认 staged）
+ *
+ * 退出码：
+ *   0 = 全过 / 仅警告
+ *   1 = 有错误
+ */
+
+// 注意：fs.globSync 在 Node 22+ 才稳定（Node 20 没有），用 namespace import + 运行时能力检测
+import * as nodeFs from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+import { execSync } from "node:child_process"
+
+const { existsSync, promises: fs } = nodeFs
+const globSync = typeof nodeFs.globSync === "function" ? nodeFs.globSync : null
+
+// ── 参数化 ROOT / ADR_DIR ─────────────────────────────────
+// 默认：脚本位于 <ROOT>/scripts/ 或 <ROOT>/.githooks/，向上一层即项目根
+const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const ROOT = process.env.ADR_ROOT ? path.resolve(process.env.ADR_ROOT) : DEFAULT_ROOT
+const ADR_DIR = process.env.ADR_DIR ? path.resolve(process.env.ADR_DIR) : path.join(ROOT, "docs", "adr")
+const MIGRATION_FILE = path.join(ROOT, ".adr-migration-start")
+const STRICT = process.env.ADR_STRICT === "1"
+const MIGRATION_DAYS = 7
+
+// ── ADR 文件命名 regex ──
+// 纯 slug：小写字母开头、kebab-case；template.md 与 README.md 排除
+const SLUG_RE = /^[a-z][a-z0-9-]*\.md$/
+const isTemplate = (f) => f === "template.md"
+const isReadme = (f) => f === "README.md"
+const isAdrFile = (f) => !isTemplate(f) && !isReadme(f) && SLUG_RE.test(f)
+
+let failed = 0
+let warned = 0
+let passed = 0
+
+const ok = (msg) => { passed++; console.log(`  ✅ ${msg}`) }
+const warn = (msg) => { warned++; console.log(`  ⚠️  ${msg}`) }
+const bad = (msg) => { failed++; console.log(`  ❌ ${msg}`) }
+const section = (t) => console.log(`\n=== ${t} ===`)
+
+// ─── 工具：解析 ADR frontmatter ──────────────────────────
+async function parseADR(filepath) {
+  const raw = await fs.readFile(filepath, "utf8")
+  const m = raw.match(/^---\n([\s\S]*?)\n---/)
+  if (!m) return null
+  const fm = {}
+  const lines = m[1].split("\n")
+  let curKey = null
+  let curArr = null
+  for (const line of lines) {
+    const kv = line.match(/^([a-z][\w-]*):\s*(.*)$/)
+    if (kv) {
+      curKey = kv[1]
+      const val = kv[2].trim()
+      if (/^\[.*\]$/.test(val)) {
+        fm[curKey] = val.slice(1, -1).split(",")
+          .map(s => s.trim().replace(/^["']|["']$/g, ""))
+          .filter(Boolean)
+        curArr = null
+      } else if (val === "" || val === "[]") {
+        fm[curKey] = []
+        curArr = fm[curKey]
+      } else {
+        fm[curKey] = val.replace(/^["']|["']$/g, "")
+        curArr = null
+      }
+    } else if (curArr && line.startsWith("  - ")) {
+      curArr.push(line.slice(4).trim().replace(/^["']|["']$/g, ""))
+    }
+  }
+  return { fm, raw }
+}
+
+const stemOf = (f) => f.replace(/\.md$/, "")
+
+// ─── A. ADR 文件结构校验 ────────────────────────────────
+
+section("A. ADR 文件结构")
+
+const REQUIRED_FIELDS = ["title", "status", "date", "deciders", "code-refs"]
+const VALID_STATUS = ["Proposed", "Accepted", "Superseded", "Deprecated", "Rejected"]
+
+if (!existsSync(ADR_DIR)) {
+  bad(`${path.relative(ROOT, ADR_DIR)} 不存在`)
+} else {
+  const all = (await fs.readdir(ADR_DIR)).sort()
+
+  // 防回潮：旧 NNNN- 前缀命名一律报错
+  for (const f of all) {
+    if (/^\d{4}-/.test(f)) {
+      bad(`${f}: 检测到旧 NNNN- 前缀命名，请改为纯 slug`)
+    }
+  }
+
+  const files = all.filter(isAdrFile)
+  const adrs = []
+  for (const f of files) {
+    const parsed = await parseADR(path.join(ADR_DIR, f))
+    if (!parsed) { bad(`${f}: frontmatter 解析失败`); continue }
+    adrs.push({ file: f, stem: stemOf(f), ...parsed })
+  }
+
+  // slug 唯一性（stem 即 key）
+  const slugMap = new Map()
+  for (const a of adrs) {
+    if (!slugMap.has(a.stem)) slugMap.set(a.stem, [])
+    slugMap.get(a.stem).push(a.file)
+  }
+  let dupFound = false
+  for (const [stem, files] of slugMap) {
+    if (files.length > 1) {
+      bad(`ADR slug 重名："${stem}" 出现在多个文件：${files.join(", ")}`)
+      dupFound = true
+    }
+  }
+  if (!dupFound) ok(`ADR 文件 ${adrs.length} 份，slug 唯一`)
+
+  // byKey map
+  const byKey = new Map()
+  for (const a of adrs) byKey.set(a.stem, a)
+
+  // 字段 + status + supersedes 闭环
+  const requiredArrayFields = new Set(["deciders", "code-refs"])
+  for (const a of adrs) {
+    for (const f of REQUIRED_FIELDS) {
+      if (!a.fm[f] || (requiredArrayFields.has(f) && (!Array.isArray(a.fm[f]) || a.fm[f].length === 0))) {
+        bad(`${a.file}: 缺字段 ${f}`)
+      }
+    }
+    if (!VALID_STATUS.includes(a.fm.status)) {
+      bad(`${a.file}: status="${a.fm.status}" 非法`)
+    }
+    if (a.fm.status === "Superseded") {
+      const sb = Array.isArray(a.fm["superseded-by"]) ? a.fm["superseded-by"] : []
+      if (sb.length === 0) {
+        bad(`${a.file}: status=Superseded 但 superseded-by 为空`)
+      } else {
+        for (const sbSlug of sb) {
+          const tgtSb = byKey.get(String(sbSlug).trim())
+          if (!tgtSb) bad(`${a.file}: superseded-by "${sbSlug}" 不存在`)
+        }
+      }
+    }
+    const supers = Array.isArray(a.fm.supersedes) ? a.fm.supersedes : []
+    for (const target of supers) {
+      const tgtStr = String(target).trim()
+      const tgt = byKey.get(tgtStr)
+      if (!tgt) { bad(`${a.file}: supersedes ${target} 不存在`); continue }
+      const tgtSb = Array.isArray(tgt.fm["superseded-by"]) ? tgt.fm["superseded-by"] : []
+      const closed = tgtSb.map(String).map((s) => s.trim()).includes(a.stem)
+      if (!closed) {
+        bad(`${a.file} → ${tgt.file}: supersedes 未双向闭环（${tgt.file} 缺 superseded-by: ${a.stem}）`)
+      }
+    }
+  }
+  ok(`字段 / status / supersedes 闭环检查完成`)
+}
+
+// ─── B. 三向引用 ─────────────────────────────────────────
+
+section("B. 三向引用（ADR → Code）")
+
+if (existsSync(ADR_DIR)) {
+  const files = (await fs.readdir(ADR_DIR)).filter(isAdrFile)
+  for (const f of files) {
+    const parsed = await parseADR(path.join(ADR_DIR, f))
+    if (!parsed) continue
+    const refs = Array.isArray(parsed.fm["code-refs"]) ? parsed.fm["code-refs"] : []
+    for (const ref of refs) {
+      if (!ref || ref === "TBD" || ref === "—" || ref === "N/A") continue
+      const filepath = ref.split(/[,(#]/)[0].trim()
+      if (/[*?\[\{]/.test(filepath)) {
+        if (!globSync) {
+          warn(`${f}: 当前 Node 不支持 fs.globSync，跳过 code-refs glob "${filepath}" 存在性检查`)
+          continue
+        }
+        try {
+          const matches = globSync(filepath, { cwd: ROOT })
+          if (!matches || matches.length === 0) {
+            warn(`${f}: code-refs glob "${filepath}" 无任何匹配（追溯型 ADR 可忽略）`)
+          }
+        } catch (err) {
+          warn(`${f}: code-refs glob "${filepath}" 解析失败：${err.message}`)
+        }
+        continue
+      }
+      const abs = path.join(ROOT, filepath)
+      if (!existsSync(abs)) {
+        warn(`${f}: code-refs "${filepath}" 不存在（追溯型 ADR 可忽略）`)
+      }
+    }
+  }
+  ok(`code-refs 文件存在性检查完成`)
+}
+
+// ─── B'. PRD 反向引用双向校验 ──────────────────────────
+
+section("B'. PRD ↔ ADR 双向引用")
+
+const PRD_PATH = path.join(ROOT, "docs", "PRD.md")
+if (!existsSync(PRD_PATH)) {
+  warn(`docs/PRD.md 不存在,跳过 B' 段（下发版可选）`)
+} else {
+  const prdContent = await fs.readFile(PRD_PATH, "utf8")
+
+  if (existsSync(ADR_DIR)) {
+    const files = (await fs.readdir(ADR_DIR)).filter(isAdrFile)
+    let prdRefChecked = 0
+    let prdRefMissing = 0
+    for (const f of files) {
+      const parsed = await parseADR(path.join(ADR_DIR, f))
+      if (!parsed) continue
+      const refs = Array.isArray(parsed.fm["prd-refs"]) ? parsed.fm["prd-refs"] : []
+      for (const ref of refs) {
+        if (!ref || ref === "TBD" || ref === "—") continue
+        const m = String(ref).match(/§\s*(\d+(?:\.\d+)*)/)
+        if (!m) continue
+        prdRefChecked++
+        const sectionId = m[1]
+        const sectionRegex = new RegExp(`^##+\\s+${sectionId.replace(".", "\\.")}\\b`, "m")
+        if (!sectionRegex.test(prdContent)) {
+          warn(`${f}: prd-refs "${ref}" 在 PRD.md 找不到对应章节 §${sectionId}`)
+          prdRefMissing++
+        }
+      }
+    }
+    ok(`PRD 章节存在性：${prdRefChecked} 个 prd-refs 检查，${prdRefMissing} 个找不到`)
+  }
+
+  // 反向：PRD 中 <!-- ADR: <slug> --> 注释引用的 ADR 必须真存在
+  const adrCommentRe = /<!--\s*ADR:\s*([^>]+?)\s*-->/g
+  let prdAdrCommentCount = 0
+  let prdAdrInvalid = 0
+  const knownAdrKeys = new Set()
+  if (existsSync(ADR_DIR)) {
+    const files = (await fs.readdir(ADR_DIR)).filter(isAdrFile)
+    for (const f of files) knownAdrKeys.add(stemOf(f))
+  }
+  let cm
+  while ((cm = adrCommentRe.exec(prdContent)) !== null) {
+    const ids = cm[1].split(",").map((x) => x.trim()).filter(Boolean)
+    for (const rawId of ids) {
+      prdAdrCommentCount++
+      if (!knownAdrKeys.has(rawId)) {
+        bad(`docs/PRD.md: <!-- ADR: ${rawId} --> 注释引用的 ADR 不存在（位置 char ${cm.index}）`)
+        prdAdrInvalid++
+      }
+    }
+  }
+  if (prdAdrCommentCount === 0) {
+    warn(`docs/PRD.md 中没有任何 <!-- ADR: <slug> --> 注释（建议至少给关键章节加反向引用）`)
+  } else {
+    ok(`PRD 反向注释：${prdAdrCommentCount} 个 ADR 引用，${prdAdrInvalid} 个无效`)
+  }
+}
+
+// ─── C. 触发式历史补全 ──────────────────────────────────
+
+section("C. 触发式补全（git diff 模式）")
+
+let migrationStart
+if (existsSync(MIGRATION_FILE)) {
+  migrationStart = new Date(await fs.readFile(MIGRATION_FILE, "utf8"))
+} else {
+  migrationStart = new Date()
+  await fs.writeFile(MIGRATION_FILE, migrationStart.toISOString())
+  console.log(`  ℹ️  初始化迁移期起点：${migrationStart.toISOString()}`)
+}
+const daysSince = Math.floor((Date.now() - migrationStart.getTime()) / 86400000)
+const grace = daysSince < MIGRATION_DAYS && !STRICT
+console.log(`  迁移期已过 ${daysSince} / ${MIGRATION_DAYS} 天，模式：${grace ? "warn" : "error"}（STRICT=${STRICT}）`)
+
+let diffFiles = []
+try {
+  const diffMode = process.env.ADR_DIFF_MODE === "last-commit" ? "last-commit" : "staged"
+  const diffCmd = diffMode === "last-commit"
+    ? "git diff --name-status HEAD~1 HEAD"
+    : "git diff --cached --name-status"
+  console.log(`  ℹ️  diff 模式：${diffMode}（${diffCmd}）`)
+  const out = execSync(diffCmd, { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] })
+  diffFiles = out.toString()
+    .split("\n")
+    .map((x) => x.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const parts = line.split("\t")
+      const status = parts[0]
+      const file = parts[parts.length - 1]
+      return { status, file }
+    })
+    .filter(({ status }) => !status.startsWith("D"))
+    .map(({ file }) => file)
+} catch {
+  console.log(`  ℹ️  无 git diff（首次提交或非 git 仓库），跳过 C 校验`)
+  diffFiles = []
+}
+
+const allCodeRefs = new Set()
+if (existsSync(ADR_DIR)) {
+  const files = (await fs.readdir(ADR_DIR)).filter(isAdrFile)
+  for (const f of files) {
+    const parsed = await parseADR(path.join(ADR_DIR, f))
+    if (!parsed) continue
+    const refs = Array.isArray(parsed.fm["code-refs"]) ? parsed.fm["code-refs"] : []
+    for (const r of refs) {
+      const fp = String(r).split(/[,(#]/)[0].trim().replace(/\\/g, "/")
+      if (!fp || fp === "TBD" || fp === "—" || fp === "N/A") continue
+      if (/[*?\[\{]/.test(fp)) {
+        if (globSync) {
+          try {
+            for (const match of globSync(fp, { cwd: ROOT })) {
+              allCodeRefs.add(String(match).replace(/\\/g, "/"))
+            }
+          } catch (err) {
+            warn(`${f}: code-refs glob "${fp}" 展开失败：${err.message}`)
+            allCodeRefs.add(fp)
+          }
+        } else {
+          warn(`${f}: 当前 Node 不支持 fs.globSync，跳过 code-refs glob "${fp}" 展开`)
+          allCodeRefs.add(fp)
+        }
+      } else {
+        allCodeRefs.add(fp)
+      }
+    }
+  }
+}
+
+const TARGET_PATTERNS = [/^plugins\/.+\.ts$/, /^workflows\/.+\.yaml$/, /^tools\/.+\.ts$/, /^agents\/.+\.md$/, /^commands\/.+\.md$/, /^lib\/.+\.ts$/]
+const ADR_COMMENT_RE = /ADR:[a-z][a-z0-9-]+|ADR-\d{4}/
+let trigChecked = 0
+for (const file of diffFiles) {
+  const norm = file.replace(/\\/g, "/")
+  if (!TARGET_PATTERNS.some((p) => p.test(norm))) continue
+  trigChecked++
+  let hasComment = false
+  try {
+    const content = await fs.readFile(path.join(ROOT, file), "utf8")
+    if (ADR_COMMENT_RE.test(content)) hasComment = true
+  } catch { /* 文件可能被删 */ }
+  const inRefs = allCodeRefs.has(norm)
+  if (!hasComment && !inRefs) {
+    const msg = `${file}: 改动了但找不到 ADR 引用（既无注释 ADR:<slug>/ADR-NNNN 也无 ADR code-refs）`
+    grace ? warn(msg) : bad(msg)
+  }
+}
+ok(`触发式补全检查完成（扫描 ${trigChecked} 个改动文件）`)
+
+// ─── D. PR 模板（下发版 warn-only） ─────────────────────
+
+section("D. PR 模板")
+const PR_TEMPLATE = path.join(ROOT, ".github", "pull_request_template.md")
+if (!existsSync(PR_TEMPLATE)) {
+  warn(`.github/pull_request_template.md 不存在（下发版不强制；建议复制 assets/adr-init/.github/pull_request_template.md）`)
+} else {
+  const content = await fs.readFile(PR_TEMPLATE, "utf8")
+  if (!/ADR/.test(content)) warn(`PR 模板未含 "ADR" 关键字（建议加 ADR checklist）`)
+  else ok(`PR 模板存在且含 ADR checklist`)
+}
+
+// ─── E. README 索引同步 ──────────────────────────────────
+
+section("E. README 索引同步")
+const indexSyncScript = path.join(ROOT, "scripts", "adr-index-sync.mjs")
+if (!existsSync(indexSyncScript)) {
+  warn(`scripts/adr-index-sync.mjs 不存在，跳过索引同步检查`)
+} else {
+  try {
+    execSync(`node "${indexSyncScript}" --check`, {
+      cwd: ROOT,
+      stdio: "pipe",
+      env: { ...process.env, ADR_ROOT: ROOT, ADR_DIR },
+    })
+    ok(`README 索引与 ADR 文件同步`)
+  } catch {
+    warn(`README 索引未同步 — 跑 \`node scripts/adr-index-sync.mjs\` 修复`)
+  }
+}
+
+// ─── 总结 ───────────────────────────────────────────────
+
+console.log(`\n=== 总结 ===`)
+console.log(`  ✅ 通过：${passed}`)
+console.log(`  ⚠️  警告：${warned}`)
+console.log(`  ❌ 失败：${failed}`)
+
+process.exit(failed === 0 ? 0 : 1)