@andyqiu/codeforge 0.3.11 → 0.3.13

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