@andyqiu/codeforge 0.3.11 → 0.3.13

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)

package/assets/adr-init/scripts/adr-index-sync.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * adr-index-sync.mjs — 自动同步 docs/adr/README.md 索引表（泛化版，由 codeforge adr-init 下发）
+ *
+ * 与 CodeForge 自仓库 scripts/adr-index-sync.mjs 的区别：
+ *   - LEGACY_ID_MAP 默认为空（不展示「曾用编号」列）
+ *   - README marker 改为 HTML 注释锚点：`<!-- adr-index:start --> / <!-- adr-index:end -->`
+ *   - ROOT 支持 ADR_ROOT 环境变量参数化
+ *
+ * 用法：
+ *   node scripts/adr-index-sync.mjs           # 默认：写回 README.md
+ *   node scripts/adr-index-sync.mjs --check   # 仅检查，不写；不同步退出码 1
+ *
+ * 环境变量：
+ *   ADR_ROOT  项目根目录绝对/相对路径；默认 path.resolve(__dirname, "..")
+ *   ADR_DIR   ADR 目录；默认 <ROOT>/docs/adr
+ *
+ * 工作原理：
+ *   1. 扫 docs/adr/*.md（纯 slug 格式）取 frontmatter
+ *   2. 按 date 升序排序（同 date 按 id 二级排序）生成索引行
+ *   3. 在 README.md 找 marker `<!-- adr-index:start --> ... <!-- adr-index:end -->` 之间整段替换
+ *   4. --check 模式不写文件，diff 不为空则 exit 1
+ */
+
+import { existsSync, promises as fs } from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+
+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 README = path.join(ADR_DIR, "README.md")
+const CHECK_ONLY = process.argv.includes("--check")
+
+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)
+
+// 模板行：固定 prepend 在首行；template.md 单独列出避免被 isAdrFile 排除
+const TEMPLATE_LINE = "| template | — | Template（模板） | — | — |"
+
+// 下发版默认为空映射；如目标项目从旧 NNNN- 编号体系迁移，可在此显式补充
+const LEGACY_ID_MAP = new Map()
+
+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 = {}
+  let curArr = null
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^([a-z][\w-]*):\s*(.*)$/)
+    if (kv) {
+      const v = kv[2].trim()
+      if (/^\[.*\]$/.test(v)) {
+        fm[kv[1]] = v.slice(1, -1).split(",")
+          .map(s => s.trim().replace(/^["']|["']$/g, ""))
+          .filter(Boolean)
+        curArr = null
+      } else if (v === "" || v === "[]") {
+        fm[kv[1]] = []
+        curArr = fm[kv[1]]
+      } else {
+        fm[kv[1]] = v.replace(/^["']|["']$/g, "")
+        curArr = null
+      }
+    } else if (curArr && line.startsWith("  - ")) {
+      curArr.push(line.slice(4).trim().replace(/^["']|["']$/g, ""))
+    }
+  }
+  return fm
+}
+
+async function buildIndex() {
+  const files = (await fs.readdir(ADR_DIR)).filter(isAdrFile)
+  const rows = []
+  for (const f of files) {
+    const fm = await parseADR(path.join(ADR_DIR, f))
+    if (!fm) continue
+    const id = f.replace(/\.md$/, "")
+    const date = String(fm.date || "").trim() || "—"
+    const title = String(fm.title || "").replace(/^["']|["']$/g, "")
+    const status = fm.status || "?"
+    const sb = Array.isArray(fm["superseded-by"]) ? fm["superseded-by"].filter(Boolean) : []
+    const sup = Array.isArray(fm.supersedes) ? fm.supersedes.filter(Boolean) : []
+    let rel = "—"
+    if (sb.length) rel = `by ${sb.map((x) => String(x).trim()).join(", ")}`
+    else if (sup.length) rel = `Supersedes ${sup.map((x) => String(x).trim()).join(", ")}`
+    const statusCell = status === "Superseded" ? `**${status}**` : status
+    const titleCell = `[${title}](./${f})`
+    // LEGACY_ID_MAP 留作扩展：如目标项目有旧编号要展示，可在源码 const 处补充并改表头
+    rows.push({
+      id,
+      date,
+      title,
+      status,
+      sb,
+      sup,
+      file: f,
+      line: `| ${id} | ${date} | ${titleCell} | ${statusCell} | ${rel} |`,
+    })
+  }
+  rows.sort((a, b) => a.date.localeCompare(b.date) || a.id.localeCompare(b.id))
+  return [TEMPLATE_LINE, ...rows.map((r) => r.line)]
+}
+
+async function main() {
+  if (!existsSync(README)) {
+    console.error(`✗ 未找到 ${README}`)
+    process.exit(1)
+  }
+  const old = await fs.readFile(README, "utf8")
+  const rows = await buildIndex()
+  const tableHeader = "| ID | Date | 标题 | 状态 | 替换关系 |\n|---|---|---|---|---|"
+  const tableBlock = `${tableHeader}\n${rows.join("\n")}`
+
+  // marker：HTML 注释锚点
+  const markerRe = /(<!--\s*adr-index:start\s*-->)[\s\S]*?(<!--\s*adr-index:end\s*-->)/
+  const m = old.match(markerRe)
+  if (!m) {
+    console.error(`✗ README 找不到 marker "<!-- adr-index:start --> ... <!-- adr-index:end -->"`)
+    console.error(`  请确认 ${path.relative(ROOT, README)} 含一对 HTML 注释锚点。`)
+    process.exit(1)
+  }
+
+  const newContent = old.replace(markerRe, `$1\n${tableBlock}\n$2`)
+
+  if (CHECK_ONLY) {
+    if (newContent === old) {
+      console.log(`✓ README 索引与 ADR 文件同步（${rows.length} 行）`)
+      process.exit(0)
+    } else {
+      console.error(`✗ README 索引与 ADR 文件不同步`)
+      console.error(`  跑 \`node scripts/adr-index-sync.mjs\` 自动修复`)
+      process.exit(1)
+    }
+  }
+
+  if (newContent === old) {
+    console.log(`✓ README 索引已是最新（${rows.length} 行），未改动`)
+  } else {
+    await fs.writeFile(README, newContent, "utf8")
+    console.log(`✓ README 索引已更新：${rows.length} 行`)
+  }
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})