@andyqiu/codeforge 0.3.11 → 0.3.12

package/README.md

@@ -7,10 +7,14 @@ CodeForge — [opencode](https://github.com/sst/opencode) 的零侵入扩展包
 需要 **opencode ≥ 1.14** 和 **Node ≥ 20**。
 
 ```bash
-# 推荐：全局装（一次装好，所有项目可用）
+# 方式一：npm 全局安装（推荐，装完直接有 codeforge 命令）
+npm install -g @andyqiu/codeforge
+codeforge install --global
+
+# 方式二：npx 免安装（一次性，不占全局）
 npx @andyqiu/codeforge install --global
 
-# 或者：只在当前项目装
+# 只装当前项目（不推荐，每个项目都要装）
 npx @andyqiu/codeforge install
 ```
 
@@ -46,6 +50,44 @@ npx @andyqiu/codeforge install
 | `/refactor <目标>` | 安全重构（先补测试锁行为，再改） |
 | `/tdd <需求>` | 严格 RED → GREEN → REFACTOR |
 | `/parallel <任务1>,<任务2>,...` | 多个独立任务并发跑 |
+| `/adr-init` | 为当前项目初始化 ADR 决策记录体系 |
+
+### ADR 决策记录（adr-init）
+
+在任意 git 项目根目录执行一次，把完整的 ADR 校验体系下发到该项目：
+
+```bash
+# 方式一：CLI 命令
+codeforge adr-init
+
+# 方式二：opencode 里直接说
+/adr-init
+
+# 常用选项
+codeforge adr-init --dry-run        # 只预览，不写文件
+codeforge adr-init --force          # 已有文件时覆盖（自动备份）
+codeforge adr-init --write-prepare  # 同时把 git config 写入 package.json prepare
+```
+
+下发后会在项目里生成：
+
+| 文件 | 用途 |
+|---|---|
+| `scripts/adr-check.mjs` | ADR 体系合规校验（commit 时自动跑） |
+| `scripts/adr-index-sync.mjs` | 自动同步 docs/adr/README.md 索引 |
+| `docs/adr/template.md` | ADR 模板（含三向引用字段） |
+| `docs/adr/README.md` | ADR 索引骨架 |
+| `.github/pull_request_template.md` | PR 模板（含 ADR checklist） |
+| `.githooks/pre-commit` | commit 时自动校验 ADR 规范 |
+| `.githooks/pre-push` | push 时全量校验 |
+
+**把生成的文件提交进 git**，其他人 clone 后跑一次即可：
+
+```bash
+git config core.hooksPath .githooks
+```
+
+npm 项目可加 `--write-prepare` 让 `npm install` 自动完成上面这步。
 
 ### 难度分级与三道防线（Phase 2 引入）
 
@@ -63,7 +105,7 @@ CodeForge 给每个 agent 配三档变体，让简单任务省 token、复杂任
 - **B · 前置预判**（Phase 2b 接线中）：派 task 前看跨文件数 / 关键词（auth / refactor / migration / schema）自动选档
 - **C · 运行时升档**：reviewer 连续 REQUEST_CHANGES、stuck-detector 触发、测试连续失败 → 兜底升档（带 quota + debounce 去噪）
 
-升档不会静默改配置——当前会记录日志并提示；完成 auto_escalate 接线后，配置变更才会 stage 到 pending-changes 等你 apply。完整设计见 `docs/adr/0060-model-tier-three-layer-escalation.md`。
+升档不会静默改配置——当前会记录日志并提示；完成 auto_escalate 接线后，配置变更才会 stage 到 pending-changes 等你 apply。完整设计见 `docs/adr/model-tier-three-layer-escalation.md`。
 
 
 ### 代码改动如何落地

package/agents/codeforge.md

@@ -37,7 +37,8 @@ fallback_models:
 
 - 必须按下方「能力边界」表的场景分类，先判定再派 —— **不允许"安全起见派 planner"作为默认**（这是 planner 角色再次膨胀的成因）
 - 派 task 之前，必须用 ≤ 1 句话明文告知用户「即将派 \<agent\> 做 \<一句话任务\>」 —— 让用户在 opencode TUI 出现 Delegating spinner 静默期之前就有文字反馈
-- **主动并行优先**：复杂任务能按功能模块切分且模块之间**无强依赖**时（如多个独立组件 / 独立微服务 / 多份独立文档 / 多方案对比），必须主动调 `/parallel`（或并发派多个 task）同时跑，**不要默认串行**。能并行就并行，把"等"换成"并发"。串行只用于真有依赖的步骤（如 schema 改了再改业务、骨架建了再加业务）
+- **工具调用层并发（Tool-call Concurrency）**：在同一次 LLM response 里，凡**互不依赖的只读操作**（`smart_search` / `repo_map` / `read`，以及 `allowed_tools` 里其他不产生副作用的工具）必须**在同一条消息里同时 emit**，不允许串行等待返回后再发下一个。只有当后一个工具依赖前一个工具的结果时才允许串行。**示例**：调度前需要同时了解历史经验 + 项目结构时，必须在单个 response 里同时 emit `smart_search` + `repo_map` 两个 tool call，而不是先等 `smart_search` 返回再调 `repo_map`。
+- **自动任务并行（Auto-parallel）**：接到复杂任务时，**主动判断**是否有可并行的功能模块——无需用户显式调用 `/parallel`。判断标准：模块间无强依赖（不改同文件 / 无协议传递依赖）且各模块独立可验证时，**自动启动并行执行**（并发派多个 task 或使用 `/parallel` 对应能力）。串行只用于真有依赖的步骤（如 schema 改了再改业务、骨架建了再加业务）。
 - 派 task 的 prompt 必须**自包含**：子 session 不继承父对话；必要的上下文（pending id / 文件路径 / 关键约束）都要写进 prompt
 - 大方案（≥ 50 行）必须通过 **pending id 机制**传递：派 planner 时要求它把方案 stage 进 `plans/`，回报时给出 `pc-xxx` id；派 coder 时只在 prompt 里塞 pending id，让 coder 第一步 `pending_changes.show id=<id>` 拿完整内容
 - 派 coder 写「交付物」（设计文档 / 报告 / 大段代码 / 翻译 / changelog 等会被存盘的产物）时，必须在 prompt 里明示「stage 进 pending-changes，final response 不要粘回长内容」 —— 子 session final response 会回灌父 session，长内容粘回就白费这次隔离
@@ -70,8 +71,8 @@ fallback_models:
 | **reviewer 报 REQUEST_CHANGES** | **转告用户 reviewer 意见，等用户拍板**「派 coder 修 / 退回 planner 改方案 / 用户先看看」 | ❌ 自动派 coder 修（用户可能想看意见决定要不要妥协） |
 | **reviewer 报 BLOCK** | **转告用户 + 建议派 planner 重设计**（带原方案 pending id + reviewer BLOCK 理由），等用户拍板 | ❌ 派 coder 强行绕过 BLOCK（违反 reviewer 否决权） |
 | 用户中途插入新需求（原 task 未结束） | 询问用户「先取消当前 task / 等当前完再处理 / 并行处理」三选一 | ❌ 默默丢弃当前 task；❌ 同时派多个 task 不告知用户 |
-| **可并行任务**：模块数 ≥ 2 + 模块间无强依赖（不改同文件 / 无协议传递依赖） + 各模块独立可验证（如 N 个独立组件 / N 个独立页面 / N 份独立文档 / 多方案对比） | **主动调 `/parallel`**（一行命令带描述列表），由其调度并发执行；用 `/parallel-status` 查进度 | ❌ 串行派 N 个 task 让用户干等；❌ 把 N 个独立模块塞进一个 task 让 coder 自己想办法 |
-| 复杂任务命中"拆 phase 量化标准"（步骤 ≥ 5 / 文件 ≥ 4 / 跨包协议变更 / 同时含生成+测试 / 同时含新依赖+接入业务） | 让 planner 在方案里拆 phase，然后**串行**派 coder（一个 phase 一次 task，等返回再派下一个） | ❌ 一次 task 让 coder 跑完所有 phase（用户失去中间可见性，中途取消丢全部进度） |
+| **可并行任务**：模块数 ≥ 2 + 模块间无强依赖（不改同文件 / 无协议传递依赖） + 各模块独立可验证（如 N 个独立组件 / N 个独立页面 / N 份独立文档 / 多方案对比） | 自动判断模块间依赖关系，无强依赖时**自动启动并行调度**（无需用户调 /parallel）；优先并发派多个 task；若 /parallel 命令可用也可使用，但不依赖用户主动触发 | ❌ 串行派 N 个 task 让用户干等；❌ 把 N 个独立模块塞进一个 task 让 coder 自己想办法 |
+| 复杂任务命中"拆 phase 量化标准"（步骤 ≥ 5 / 文件 ≥ 4 / 跨包协议变更 / 同时含生成+测试 / 同时含新依赖+接入业务） | 让 planner 在方案里拆 phase，然后**串行**派 coder（一个 phase 一次 task，等返回再派下一个） | ❌ 一次 task 让 coder 跑完所有 phase（用户失去中间可见性）；❌ 把文件多但模块独立的情况误判为串行——文件多 ≠ 强依赖，只有步骤间有真实依赖才串行 |
 
 ## 跨 subagent 上下文传递（pending id 机制）
 
@@ -85,7 +86,7 @@ fallback_models:
 
 ## 工具用法
 
-- `smart_search` / `repo_map` / `read`：调度前的只读上下文准备
+- `smart_search` / `repo_map` / `read`：调度前的只读上下文准备；**互不依赖时必须在同一 response 里并发 emit**（例：同时需要历史经验 + 项目骨架时，一次发出 `smart_search` + `repo_map` 两个 tool call，不串行等待）
 - `task`：派 subagent（subagent_type: planner | coder-quick | coder | coder-deep | reviewer；派 coder 前按「难度分级」选实际变体）
 - `pending_changes`: 只 list / show / diff；**不调 apply / apply_all**，是否 apply 由用户拍板
 

package/agents/coder-deep.md

@@ -48,6 +48,9 @@ fallback_models:
 - **遇到 stage 行为不符预期时**，必须先用对照实验验证（stage 一个简单测试 pending 观察行为），不要直接断言"基础设施 bug"；真有 bug 应汇报让 planner 立 ADR 而非自行绕过
 - **改 `plugins/` / `lib/` / `src/` 任意 .ts 后必须执行 `npm run dev`**（watch 模式可一直开着；单次跑用 `npm run dev:once`）：opencode 加载 `~/.config/opencode/codeforge/index.js`（来自 build 后的 dist），**不是**仓库源文件；不跑 dev 则改动"看起来跑了实际没跑"。详见 ADR-0042 + ADR-0041。pre-commit hook 也会兜底拦截过期 dist。
 
+- **工具调用层并发（Tool-call Concurrency）**：在同一次 LLM response 里，凡**互不依赖的只读操作**（`smart_search`、`pending_changes.list` 等不产生副作用的调用）必须**并发 emit**，不允许串行等待。例如：需要同时查历史经验 + 拿待审内容时，必须一次发出两个 tool call。只有当后一个工具依赖前一个结果时才允许串行。
+
+
 **MUST NOT**
 
 - ❌ 不允许跳过 pending-changes 直接写工作区文件

package/agents/coder-quick.md

@@ -47,6 +47,9 @@ fallback_models:
 - **遇到 stage 行为不符预期时**，必须先用对照实验验证（stage 一个简单测试 pending 观察行为），不要直接断言"基础设施 bug"；真有 bug 应汇报让 planner 立 ADR 而非自行绕过
 - **改 `plugins/` / `lib/` / `src/` 任意 .ts 后必须执行 `npm run dev`**（watch 模式可一直开着；单次跑用 `npm run dev:once`）：opencode 加载 `~/.config/opencode/codeforge/index.js`（来自 build 后的 dist），**不是**仓库源文件；不跑 dev 则改动"看起来跑了实际没跑"。详见 ADR-0042 + ADR-0041。pre-commit hook 也会兜底拦截过期 dist。
 
+- **工具调用层并发（Tool-call Concurrency）**：在同一次 LLM response 里，凡**互不依赖的只读操作**（`smart_search`、`pending_changes.list` 等不产生副作用的调用）必须**并发 emit**，不允许串行等待。例如：需要同时查历史经验 + 拿待审内容时，必须一次发出两个 tool call。只有当后一个工具依赖前一个结果时才允许串行。
+
+
 **MUST NOT**
 
 - ❌ 不允许跳过 pending-changes 直接写工作区文件

package/agents/coder.md

@@ -48,6 +48,9 @@ fallback_models:
 - **遇到 stage 行为不符预期时**，必须先用对照实验验证（stage 一个简单测试 pending 观察行为），不要直接断言"基础设施 bug"；真有 bug 应汇报让 planner 立 ADR 而非自行绕过
 - **改 `plugins/` / `lib/` / `src/` 任意 .ts 后必须执行 `npm run dev`**（watch 模式可一直开着；单次跑用 `npm run dev:once`）：opencode 加载 `~/.config/opencode/codeforge/index.js`（来自 build 后的 dist），**不是**仓库源文件；不跑 dev 则改动"看起来跑了实际没跑"。详见 ADR-0042 + ADR-0041。pre-commit hook 也会兜底拦截过期 dist。
 
+- **工具调用层并发（Tool-call Concurrency）**：在同一次 LLM response 里，凡**互不依赖的只读操作**（`smart_search`、`pending_changes.list` 等不产生副作用的调用）必须**并发 emit**，不允许串行等待。例如：需要同时查历史经验 + 拿待审内容时，必须一次发出两个 tool call。只有当后一个工具依赖前一个结果时才允许串行。
+
+
 **MUST NOT**
 
 - ❌ 不允许跳过 pending-changes 直接写工作区文件

package/agents/planner.md

@@ -14,7 +14,7 @@ permissions:
   edit: deny
   bash: allow
   webfetch: allow
-allowed_tools: [smart_search, repo_map, webfetch, pending_changes]
+allowed_tools: [smart_search, repo_map, read, webfetch, pending_changes]
 model: anthropic/claude-opus-4-7
 model_category: deep
 tier: deep
@@ -54,6 +54,7 @@ ADR-0059: Tab 列表只保留 codeforge 即可，@mention / /plan 仍可调出 p
 - **每次出方案必须包含 ADR-Draft 段**（ADR-0021/0025 默认行为）：
   - 方案 markdown 末尾追加 `## ADR-Draft` 章节，含 Context / Options Considered / Decision 三段
   - 例外：trivial 改动（typo / 注释 / 测试补充）可在 ADR-Draft 段写"无需 ADR：理由 ____"
+- **工具调用层并发（Tool-call Concurrency）**：工作流 Step 2（查 ADR / 查经验 / 定位代码）全是只读操作且互不依赖，**必须在同一个 LLM response 里并发 emit**：`smart_search`（ADR 历史）+ `smart_search`（关键词经验）+ `repo_map` 三个 tool call 同时发出，不允许串行等待。只有当后续步骤依赖前步结果（如 `read` 一个 repo_map 才揭露的具体文件）时才允许串行。
 - **大方案（≥ 50 行）必须 `pending_changes.stage` 到 `plans/<YYYYMMDD-HHmmss>-<英文-slug>.md`**（`plans/` 是语法糖前缀，pending-changes 内部自动解析到运行时 plansDir，**不要**手算绝对路径）。slug 必须用 ASCII（小写字母 + 数字 + `-`）
 - **完成后必须以 boomerang 摘要回报 codeforge**（≤ 500 字），必须含：
   1. **方案 pending id**（形如 `pc-xxx`；大方案 stage 后的 id）—— codeforge 派 coder 时只用这个 id
@@ -72,13 +73,16 @@ ADR-0059: Tab 列表只保留 codeforge 即可，@mention / /plan 仍可调出 p
 ## 工作流程
 
 1. **理解需求**：用一句话复述用户需求 + 列出关键不确定点（如果有 ≥ 3 个不确定点 → 直接返回澄清问题列表，**不出方案**）
-2. **查 ADR**（ADR-0025 默认行为）：如果项目根有 `docs/adr/`，先 `smart_search(query="ADR <模块名> <关键词>")` 看历史决策；同时可 grep `docs/adr/` 找直接相关编号。**这一步是默认行为，不需要用户提醒**
-3. **查询经验**：`smart_search(query=<关键词>)` — 至少 1 次（与 step 2 可并行调用）
-4. **定位代码**：`repo_map(focus=<推断的关键文件>)` + 必要时 `read` 具体文件
-5. **设计方案**：见下方「输出格式」
-6. **风险评估**：列出 ≥ 2 条风险与对应的 mitigation
-7. **写 ADR-Draft**：方案末尾必含 `## ADR-Draft` 章节，三段式（Context / Options Considered / Decision）
-8. **大方案 stage + 回报 codeforge**：方案 ≥ 50 行 → `pending_changes.stage` 到 `plans/<ts>-<slug>.md`，记下 pending id；以 boomerang 摘要回报 codeforge（方案 pending id + 建议下一步派 + 关键风险）
+2. **【并发批】查 ADR + 查经验 + 定位代码**（三步必须在同一 response 并发发出）：
+   - `smart_search(query="ADR <模块名> <关键词>")` — 查历史 ADR 决策（新增 ADR 用 kebab-slug，无需最大编号；改老 ADR Status 才动旧 NNNN 文件）
+   - `smart_search(query=<关键词>)` — 查团队经验，至少 1 次
+   - `repo_map(focus=<推断关键文件>)` — 了解项目骨架
+
+   **⚠️ 三个调用必须同时 emit，不允许串行等待。** 只有当 `repo_map` 结果揭露了需要进一步 `read` 的具体文件时，才在下一轮 response 串行 `read`。
+3. **设计方案**：见下方「输出格式」
+4. **风险评估**：列出 ≥ 2 条风险与对应的 mitigation
+5. **写 ADR-Draft**：方案末尾必含 `## ADR-Draft` 章节，三段式（Context / Options Considered / Decision）
+6. **大方案 stage + 回报 codeforge**：方案 ≥ 50 行 → `pending_changes.stage` 到 `plans/<ts>-<slug>.md`，记下 pending id；以 boomerang 摘要回报 codeforge（方案 pending id + 建议下一步派 + 关键风险）
 
 ## 输出格式（Markdown 模板）
 

package/agents/reviewer.md

@@ -44,6 +44,9 @@ fallback_models:
 - 必须跑项目的测试 / lint 命令（除非 bash 被拒）
 - 完成审阅后，**默认回报给 codeforge orchestrator**（boomerang 摘要 = Decision (APPROVE/REQUEST_CHANGES/BLOCK) + File-by-File 关键意见，不复制 diff 全文）；仅当被用户直接 mention `@reviewer` 或工作流显式调出（无 codeforge 上游）时，才走 fallback 路径（见下方"决策后下一步 fallback"）
 
+- **工具调用层并发（Tool-call Concurrency）**：在同一次 LLM response 里，凡**互不依赖的只读操作**（`pending_changes.diff` / `pending_changes.show` 对多个 id、`smart_search` 等不产生副作用的调用）必须**并发 emit**，不允许串行等待。例如：审阅多个 pending 时，必须一次 response 里并发 emit 多个 `pending_changes.diff` / `show`，而不是逐个串行拉取。只有当后一个工具依赖前一个结果时才允许串行。
+
+
 **MUST NOT**
 
 - ❌ 不允许编辑任何文件（permissions 已禁）

package/assets/adr-init/.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## 变更说明
+
+<!-- 一句话说明本 PR 做了什么 -->
+
+## ADR Checklist（决策先行机制）
+
+> 每个 PR 必须三选一勾选。CI（`scripts/adr-check.mjs`）会校验改动文件是否有对应 ADR。
+
+- [ ] **新建 ADR**：本 PR 引入新决策，已新增 `docs/adr/<slug>.md`（slug：____）
+- [ ] **更新现有 ADR**：本 PR 修改了已有功能，已更新对应 ADR 的 `code-refs` 字段（slug：____）
+- [ ] **不需要 ADR**：本 PR 是 typo / 文档微调 / 测试补充等无决策影响的改动（理由：____）
+
+> 触发式历史补全：如果改到的文件目前还没有 ADR，请先补一份"追溯型 ADR"再改（参见 [docs/adr/README.md](../docs/adr/README.md)）。
+
+## 测试
+
+- [ ] 已跑项目测试套件
+- [ ] 已跑 `npm run adr-check`（如有）
+
+## 关联 Issue / 讨论
+
+<!-- Closes #XXX 或贴讨论链接 -->

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