@andyqiu/codeforge 0.5.26 → 0.5.27

package/agent-templates/codeforge.md

@@ -0,0 +1,221 @@
+# CodeForge 完整模板
+
+> 此文档由 `agents/codeforge.md` 剥离而来，承接 4 块派 subagent 的完整 `task({...})` prompt 模板。
+> **LLM runtime 不会自动加载此文件** —— 只在 codeforge agent 派 task 时主动 `read` 取对应模板。
+>
+> 主体约束、能力边界场景表、跨 subagent 上下文传递规则（**plan_id 机制**）、与其他 agent 边界等见 [agents/codeforge.md](../../agents/codeforge.md)。
+
+---
+
+## 派 planner（复杂多步任务）
+
+```
+task({
+  description: "规划 <一句话需求>",
+  subagent_type: "planner",
+  prompt: `请按你的工作流程出实现方案。
+
+# 需求
+<完整复述用户需求，自包含>
+
+# 关键背景（如果有）
+<我已查到的项目地图 / 历史经验摘要，自包含>
+
+# 走 spec 路径时额外塞（用户已确认 candidate-specs 后）
+spec=<slug>
+<!-- planner Step 2 必须 read .codeforge/specs/<slug>/handoff.yaml -->
+
+# 你必须做的
+1. 按 planner.md 工作流程出方案
+2. 方案 ≥ 50 行必须调 plan_write({ title, content }) 写入，工具返回 plan_id
+3. boomerang 摘要必须含独占一行的「plan_id: plan-YYYYMMDD-HHmmss-NNN」+「建议下一步派: coder / 需要 reviewer 先看」+「关键风险一句话」
+4. 不要自己派 task（派 subagent 是 codeforge 的职责）
+5. 不要用 pending_changes.stage 写方案（已废弃，统一用 plan_write）
+6. 含 spec= 时方案必须有「需求溯源」段（引用 PRE-x / AC-x 作为 evidence）`,
+})
+```
+
+---
+
+## 派 coder（执行方案，有 planner 的 plan_id）
+
+```
+task({
+  description: "执行方案 <一句话>",
+  subagent_type: "<按难度分级节选定的变体：coder-quick | coder | coder-deep>",
+  prompt: `方案已通过 plan_write 写入，第一步调用 plan_read 拿完整内容：
+
+# 方案 plan_id
+plan_id=<planner 回报的 plan-YYYYMMDD-HHmmss-NNN>
+
+# 当前 session 信息（guard plugin 用于 gate 闭合校验）
+sessionId=<当前 codeforge session id>
+
+# 走 spec 路径时额外塞（用户已确认 candidate-specs 后）
+spec=<slug>
+pre_ack=PRE-1,PRE-2     # 多条逗号分隔；仅列出用户已逐条授权的 PRE id
+<!-- coder Step 0「PRE 阻断校验」会先 read handoff.yaml 核对；任一 PRE 未在 pre_ack 中 → 拒绝启动 -->
+
+# 你必须做的
+1. 立刻 plan_read({ plan_id: "<plan_id>" }) 获取完整方案（同时闭合 session-worktree-guard plan-read hard gate；不调则所有写操作被阻断）
+2. 含 spec= 时先跑工作流 Step 0（PRE 阻断校验），通过后再 Step 1
+3. 按方案【步骤】章节顺序执行
+4. 每步直接在 session worktree 内写文件（edit / write / ast_edit / bash 均可，无需 stage）
+5. 失败立即停下不要硬修，汇报错误首行
+6. 全部完成后跑测试，回报「plan_id + 改动文件列表（git diff --stat）+ 测试结果 + 关键风险」
+
+⚠️ 你只在 worktree 内写文件；merge 由 codeforge 在 APPROVE 后调 session_merge，或用户通过 /merge 命令触发 —— coder 自身不要调 session_merge`,
+})
+```
+
+---
+
+## 派 coder（小改动 short-circuit，无 planner 方案）
+
+```
+task({
+  description: "<一句话改动>",
+  subagent_type: "<coder-quick | coder | coder-deep>",
+  prompt: `# 改动需求
+<自包含描述：改哪个文件 / 改什么 / 为什么>
+
+# 当前 session 信息
+sessionId=<当前 codeforge session id>
+
+# 你必须做的
+1. 直接在 session worktree 内写文件（edit / write / ast_edit 均可，worktree 已被 guard plugin 隔离）
+2. 跑相关测试
+3. 回报改动文件列表（git diff --stat） + 测试结果`,
+})
+```
+
+> small short-circuit 路径**无 plan_id**（无方案 → guard plugin 不强制 plan_read gate），也**不走 spec=/pre_ack=**。
+
+---
+
+## 派 reviewer（审 session worktree 改动 —— 新模式，默认）
+
+```
+task({
+  description: "审阅 session worktree 改动",
+  subagent_type: "reviewer",
+  prompt: `[Session Merge Review]
+
+请审阅当前 session worktree 内的全部改动并给出 APPROVE / REQUEST_CHANGES / BLOCK：
+
+# session 信息（4 项均必填）
+sessionId=<当前 session id>          # reviewer 调 review_approval 时用 session:<sessionId>
+worktreePath=<worktree 绝对路径>
+baseSha=<bind 时主仓 HEAD sha，作为 diff base>
+plan_id=<planner 的 plan-xxx>
+
+# 你必须做的（并发 emit 以下 3 个调用）
+1. plan_read({ plan_id: "<plan_id>" })               # 拿方案原文对照
+2. bash: cd <worktreePath> && git diff <baseSha>..HEAD              # 全部改动
+3. bash: cd <worktreePath> && git diff --stat <baseSha>..HEAD       # 文件清单
+
+不要调 pending_changes.list（新模式没有 pending 概念）
+
+# 上下文
+- 测试结果：<coder 回报的 pass / fail 摘要>
+- 重点关注：<安全 / 性能 / 与方案一致性 等>
+
+# 回报要求
+- APPROVE 前必须先调 review_approval({ verdict: "APPROVE", pendingIds: ["session:<sessionId>"], notes: "<摘要>" })
+- boomerang 摘要 = Decision (APPROVE/REQUEST_CHANGES/BLOCK) + File-by-File 关键意见，不要复制 diff 全文`,
+})
+```
+
+---
+
+## 派 reviewer（审方案 `plan_only`）
+
+```
+task({
+  description: "审方案",
+  subagent_type: "reviewer",
+  prompt: `请审阅方案并给出 APPROVE / REQUEST_CHANGES / BLOCK：
+
+review_target=plan_only
+plan_id=<plan-xxx>
+
+# 你必须做的
+- plan_read({ plan_id: "<plan_id>" }) 拿方案原文
+- 按 reviewer.md「审方案」章节出意见（章节-by-章节）
+- 不审代码 diff，不调 bash git diff，不调 pending_changes.list
+
+# 回报要求
+- APPROVE 前必须先调 review_approval({ verdict: "APPROVE", pendingIds: ["plan:<plan_id>"], notes: "<摘要>" })
+- boomerang 摘要 = Decision + 章节-by-章节关键意见`,
+})
+```
+
+---
+
+## 派 reviewer（审决策 `decision_only`）
+
+```
+task({
+  description: "审派单决策",
+  subagent_type: "reviewer",
+  prompt: `请审阅以下决策并给出 APPROVE / REQUEST_CHANGES / BLOCK：
+
+review_target=decision_only
+user_choice=<用户选项>
+proposed_dispatch=<候选派单方案：派哪个 agent 做什么>
+
+# 你必须做的
+- 审决策风险 / 是否有更好替代方案
+- 如无明显问题直接 APPROVE（避免过度干预用户决策）
+- REQUEST_CHANGES 时给替代建议（≤ 2 条），不必给"改哪行"
+
+# 回报要求
+- APPROVE 前必须先调 review_approval({ verdict: "APPROVE", pendingIds: ["decision:<hash>"], notes: "<摘要>" })`,
+})
+```
+
+---
+
+## 派 reviewer（legacy pending-changes 审，过渡期兼容）
+
+> 仅当还有 pending-changes 待审场景（Phase 5 删除 pending_changes 工具前）才使用。
+
+```
+task({
+  description: "审阅 pending-changes (legacy)",
+  subagent_type: "reviewer",
+  prompt: `请审阅 pending-changes 并给出 APPROVE / REQUEST_CHANGES / BLOCK：
+
+# 待审 pending id 列表
+<pc-xxx, pc-yyy, ...>
+
+# 上下文
+- 测试结果：<coder 回报的 pass / fail 摘要>
+- 重点关注：<安全 / 性能 / 与方案一致性 等>
+
+# 回报要求
+- APPROVE 前必须先调 review_approval({ verdict: "APPROVE", pendingIds: ["pc-xxx", "pc-yyy"], notes: "<摘要>" })
+- boomerang 摘要 = Decision + File-by-File 关键意见，不要复制 diff 全文`,
+})
+```
+
+---
+
+## review_target 选择说明（ADR:reviewer-multi-profile）
+
+派 reviewer 时**必须**根据待审内容选 `review_target`，reviewer 会动态 `read review-profiles/<target>.md` 加载专属清单。
+
+| 待审内容 | review_target | 备注 |
+|---|---|---|
+| pending 含 `plans/*.md` | `plan_only` | 7 维度方案审（需求覆盖 / 架构合理性 / ADR 覆盖 / Phase 拆分 / 接口稳定 / 风险 / 可回滚） |
+| pending 含 `docs/adr/*.md` | `adr` | ADR 决策审 + 三向引用机审清单（code-refs / prd-refs / tests 实际存在性） |
+| pending 含 `docs/**/*.md` / `README.md`（非 ADR、非 plan） | `docs` | 7 维度文档审（目标读者 / 步骤可复现 / 信息完整 / 准确性 / 结构 / 陷阱 / 链接） |
+| pending 主要是代码文件（混合或语言不确定） | `code` | 默认；reviewer 自动按 pending 扩展名追加 `code-typescript` / `code-python` / `code-csharp-lua-c` |
+| ≥ 80% 是 TS/JS 文件（.ts/.tsx/.js/.jsx/.mjs/.cjs） | `code:typescript` | 显式提示，跳过 reviewer 端自动检测扫描 |
+| ≥ 80% 是 Python 文件（.py/.pyi） | `code:python` | 显式提示 |
+| ≥ 80% 是 C# / Lua / C 文件 | `code:csharp-lua-c` | 显式提示 |
+| 用户选项驱动派单的中审（Q3-a 范围） | `decision_only` | 中审：识别明显风险 + 替代建议 ≤ 2 条，避免过度干预用户决策 |
+
+**禁止自创未列出的 `review_target`**（如 `code:rust` / `code:go`）—— reviewer 会 fallback 到 `code` + 在 Summary 段 warn，不如直接显式传 `code` 让 reviewer 自动按扩展名追加专项 profile。
+
+**派 reviewer 模板里如何传**：把 `review_target=<value>` 作为 prompt 内独立一行（参考上方四个 reviewer 派单模板的 `review_target=plan_only` / `review_target=decision_only` 写法），reviewer 会从 prompt 中解析该行（若 runtime 提供 inject_context.review_target 则优先使用结构化值）；

package/agent-templates/coder.md

@@ -0,0 +1,73 @@
+# Coder 完整模板
+
+> 此文档由 `agents/coder.md` 剥离而来，承接派 reviewer fallback 的完整 `task({...})` 模板 + 手动 `Tab` 切 agent 指令 + Step 0 PRE 拒绝启动 boomerang 详细示例。
+> **LLM runtime 不会自动加载此文件** —— 只在 coder agent 走 fallback 路径（无 codeforge 上游）或需要拒绝启动时主动 `read` 取模板。
+>
+> 主体约束、3 项不可删的微步进度 / pending-only 写入约束、工作流程、失败回退等见 [agents/coder.md](../../agents/coder.md)。
+
+---
+
+## 🛑 PRE 拒绝启动 boomerang 详细示例（Step 0 校验未通过时）
+
+> agents/coder.md 已含极简模板（≤ 6 行），下面是含真实数据的完整示例，供首次走 spec 路径时参照填写。
+
+**场景**：codeforge 派 prompt 含 `spec=user-feed-recsys`，但未含 `pre_ack=`，而 handoff.yaml 含 2 条 `pre_coding_blockers[]`。
+
+```markdown
+❌ 拒绝启动：spec=user-feed-recsys 含未解除 PRE 阻断
+
+**检测 PRE**（来源 .codeforge/specs/user-feed-recsys/handoff.yaml `pre_coding_blockers[]`，v1.2 显式字段）：
+- `PRE-1`: 上游推荐 API 鉴权方案未定（OAuth2 vs API key？）— source: assumption / must_resolve_by: user
+- `PRE-2`: redis 集群是否支持 BITCOUNT 命令需运维确认 — source: open_issue / must_resolve_by: codeforge
+
+**已检测父 prompt pre_ack**：无
+
+**建议下一步**（codeforge 决定，本 coder 不自动派下一棒）：
+- a) 用户已逐条授权 → codeforge 派回时补 `pre_ack=PRE-1,PRE-2`
+- b) PRE 未真正解除 → 退回 discover / planner，让 discover 把 must_resolve_by 字段升 `resolved` 或方案显式说明绕过路径
+- c) 用户明文「跳过 PRE 阻断校验，我接受风险」 → codeforge 下次派 prompt 含该短语
+
+**未做**：尚未 stage 任何改动；仅完成 `read .codeforge/specs/user-feed-recsys/handoff.yaml`（只读操作）
+**已做**：解析 PRE 集合 + 核对 pre_ack 解除路径
+```
+
+---
+
+## 🚀 派 reviewer 审阅（fallback — 仅当无 codeforge 上游时）
+
+⚠️ 默认行为：完成后 boomerang 摘要回报 codeforge，由 codeforge 决定是否派 reviewer。
+只有被用户直接 `@coder` 或 `/quick` 调出（无 codeforge 上游）时才走本节自派 reviewer。
+
+全部步骤完成且 pending-changes 列表已生成后，调 `task` 让 reviewer 审：
+
+```
+task({
+  description: "审阅 pending-changes",
+  subagent_type: "reviewer",
+  prompt: `请审阅 pending-changes 并给出 APPROVE / REQUEST_CHANGES / BLOCK：
+- 待审改动：<N 个文件，+X / -Y 行；附 pending change ID 列表>
+- 测试结果：<pass / fail，失败请保留输出摘要>
+- 方案出处：<复制 planner 方案的【涉及文件】+【步骤】两节>
+- 重点关注：<本次特别要看的维度，如安全 / 性能 / 与方案一致性>`,
+})
+```
+
+opencode 会创建 reviewer 子 session 并把 Decision 回传。子 session 出现在父 session 树里，TUI 按 `Ctrl+→` / `Ctrl+←` 切换查看。
+
+如果 `REQUEST_CHANGES`，把意见复述给用户并问"要不要直接派回我修复"。
+
+---
+
+## 🔀 手动切到 reviewer（task 工具不可用时回退）
+
+- **TUI**: 按 `Tab` 切到 `reviewer`，把下面这段话作为新消息发出
+- **Mention**: 在新消息开头写 `@reviewer` + 下面这段话
+
+**给 reviewer 的指令**（复制粘贴即可）：
+
+```text
+请审阅 pending-changes 并给出 APPROVE / REQUEST_CHANGES / BLOCK 决策：
+- 待审改动：<N 个文件，+X / -Y 行>
+- 测试已跑：<pass / fail>
+- 方案出处：上方 planner 的方案 + 步骤清单
+```

package/agent-templates/planner.md

@@ -0,0 +1,85 @@
+# Planner 完整模板
+
+> 此文档由 `agents/planner.md` 剥离而来，承接方案输出的完整 Markdown 模板示例。
+> **LLM runtime 不会自动加载此文件** —— 只在 planner agent 出方案前主动 `read` 取模板套。
+>
+> 主体约束、工作流程 8 步、行为约束 MUST / MUST NOT 等见 [agents/planner.md](../../agents/planner.md)。
+
+---
+
+## 方案输出格式（强制 Markdown 模板）
+
+```markdown
+## 需求理解
+
+<一句话复述>
+
+**关键问题**（如有）：
+- Q1: ...
+- Q2: ...
+
+## 项目上下文
+
+- repo_map 摘要：<2-3 行>
+- KH 历史经验：<引用 KH 命中条目，无则说"无相关经验">
+
+## 需求溯源（**走 spec 路径时必含；否则省略整段**）
+
+来源：`.codeforge/specs/<slug>/handoff.yaml`
+
+**Needs**：
+- `needs[0]` (must): <statement>
+- `needs[1]` (should): <statement>
+
+**Boundaries（excluded）**：
+- <excluded> — <reason>
+
+**Pre-coding Blockers**（v1.2 显式 / v1.1 fallback 推断）：
+- `PRE-1`: <blocker>（source: assumption, must_resolve_by: user）— 本方案**已解除**：<理由>
+- `PRE-2`: <blocker>（source: red_flag, must_resolve_by: codeforge）— 留给 coder 启动时 `pre_ack`
+
+**Acceptance Criteria 覆盖**：
+- `AC-1`: <description> → 由 Step 3 / Step 5 覆盖
+- `AC-2`: <description> → 由 Step 4 + 测试 X 覆盖
+
+## 实现方案
+
+### 涉及文件
+- `path/a.ts` — 改 X
+- `path/b.ts` — 新增 Y
+
+### 步骤
+1. ...
+2. ...
+3. ...
+
+### 测试策略
+- 单元测试：...
+- 集成测试：...
+
+## 风险与缓解
+| # | 风险 | 缓解 |
+|---|---|---|
+| 1 | ... | ... |
+| 2 | ... | ... |
+
+## ADR-Draft
+
+**Context**: <为什么要做这件事 / 当前痛点>
+**Options Considered**: <选项 A / B / C + 各自优缺点>
+**Decision**: <选哪个 + 关键理由 — 走 spec 路径时必须显式引用 PRE-x / AC-x 作为 evidence，如「Decision 选 A：解除 PRE-1（外部 API 已确认可用）+ 覆盖 AC-1 / AC-3」>
+
+<!-- trivial 改动可写：「无需 ADR：理由 ____」 -->
+```
+
+---
+
+## 套模板要点
+
+1. **章节顺序不可调换** —— executor / 后续 agent 按章节名定位
+2. **`## ADR-Draft` 必含** —— trivial 改动也要写"无需 ADR：理由 ____"，不允许整段省略
+3. **`## 需求溯源` 段**：走 spec 路径必含；非 spec 路径可整段省略（不要写"无 spec"占位）
+4. **`### 涉及文件` 必含路径列表** —— codeforge 派 coder 时会按此清单判定是否需要拆 phase
+5. **风险表至少 2 条** —— 不允许"无明显风险"作为唯一行
+6. **方案 ≥ 50 行必须 `pending_changes.stage` 到 `plans/<ts>-<slug>.md`**，回报 pending id 给 codeforge
+7. **走 spec 路径时 ADR-Draft Decision 段必须有 PRE-x / AC-x 引用**，让 reviewer 能机械核对需求溯源链

package/agent-templates/reviewer.md

@@ -0,0 +1,75 @@
+# Reviewer 完整模板
+
+> 此文档由 `agents/reviewer.md` 剥离而来，承接决策后下一步 fallback 的完整 `task({...})` 模板 + 手动 `Tab` 切 agent 指令。
+> **LLM runtime 不会自动加载此文件** —— 只在 reviewer agent 走 fallback 路径（无 codeforge 上游）时主动 `read` 取对应档模板。
+>
+> 主体约束、Decision 首行格式约束、审阅清单 8 项、输出格式 Markdown 模板等见 [agents/reviewer.md](../../agents/reviewer.md)。
+
+---
+
+## 决策后下一步（fallback — 仅当无 codeforge 上游时）
+
+⚠️ 默认行为：boomerang 摘要回报 codeforge（含 Decision + 关键意见），由 codeforge 决定下一棒。
+只有被用户直接 `@reviewer` 或工作流显式调出（无 codeforge 上游）时才走本节自派后续 agent。
+
+reviewer 永远不直接改代码。`REQUEST_CHANGES` / `BLOCK` 时**优先用 `task` 工具移交 coder / planner**（opencode 1.14+ 主线 Task，自动闭环、子 session 隔离）；不可用时回退到手动 `Tab` 切 agent。
+
+---
+
+## 如果 `APPROVE`
+
+切回主 agent（如 `plan`）应用 pending-changes：
+
+- **TUI**: 按 `Tab` 切回主 agent，发新消息：
+
+```text
+APPROVE 已通过，请 apply-changes 把 pending 全部落盘
+```
+
+---
+
+## 如果 `REQUEST_CHANGES`
+
+**首选 — 调 task 派 coder 修复**：
+
+```
+task({
+  description: "按 review 意见修复",
+  subagent_type: "coder",
+  prompt: `请按以下意见修复 pending-changes，修完跑测试并列出新的 pending-changes 等我复审：
+1. 修改 \`path/a.ts:88\` 为 prepared statement（理由：SQL 注入风险）
+2. <其他 REQUEST_CHANGES 意见，每条带文件:行 + 改成什么 + 为什么>`,
+})
+```
+
+opencode 会创建 coder 子 session，结束后回传摘要给 reviewer 继续第二轮审阅。
+
+**手动回退**：按 `Tab` 选 `coder`，发：
+
+```text
+请按以下意见修复 pending-changes 后让我重新审：
+1. 修改 `path/a.ts:88` 为 prepared statement
+2. 重新跑 `npm test`
+3. 列出新的 pending-changes
+```
+
+---
+
+## 如果 `BLOCK`
+
+**首选 — 调 task 派 planner 重新设计**：
+
+```
+task({
+  description: "重新规划（绕过被 BLOCK 的方案）",
+  subagent_type: "planner",
+  prompt: `reviewer 给了 BLOCK：<原因摘要 + 涉及文件>。原方案存在 <根本性风险描述>。请重新规划方案，避开此风险。原方案概要：<复制原方案的【涉及文件】+【步骤】两节>`,
+})
+```
+
+**手动回退**：按 `Tab` 选 `planner`，发：
+
+```text
+reviewer 给了 BLOCK：<原因摘要>。
+请重新规划方案，避开此风险。
+```

package/agents/codeforge.md

@@ -22,7 +22,7 @@ model_thinking:
   type: enabled
   budget_tokens: 4000
 fallback_models:
-  - anthropic/claude-opus-4-7    # 路由判断失败 / 复杂场景升档
+  - anthropic/claude-opus-4-8    # 路由判断失败 / 复杂场景升档
   - openai/gpt-5.5
   - google/gemini-3-pro
 ---
@@ -180,7 +180,7 @@ codeforge 在 session 内维护两个 loop 计数器：
 
 ## 派 subagent 模板
 
-派 planner / coder / reviewer 完整 prompt 模板见 **[docs/agent-templates/codeforge.md](../docs/agent-templates/codeforge.md)** —— 派 task 时主动 `read` 该文件取对应模板，禁止凭印象拼 prompt。
+派 planner / coder / reviewer 完整 prompt 模板见 `~/.config/opencode/agent-templates/codeforge.md`（Windows：`%APPDATA%\opencode\agent-templates\codeforge.md`）—— 派 task 时主动 `read` 该绝对路径取对应模板（若 `read` 不展开 `~`，改用 `bash cat ~/.config/opencode/agent-templates/codeforge.md`），禁止凭印象拼 prompt。
 
 ## 失败回退
 

package/agents/coder-deep.md

@@ -99,7 +99,7 @@ fallback_models:
 
 只有被用户直接 `@coder` 或 `/deep` 调出（无 codeforge 上游）时才走 fallback：调 `task` 派 reviewer 或手动 `Tab` 切 agent。
 
-完整 `task({...})` prompt 模板 + 手动 `Tab` / `@reviewer` mention 指令模板见 **[docs/agent-templates/coder.md](../docs/agent-templates/coder.md)** —— 走 fallback 时主动 `read` 该文件，禁止凭印象拼 prompt（漏字段就破坏 reviewer 回报契约）。
+完整 `task({...})` prompt 模板 + 手动 `Tab` / `@reviewer` mention 指令模板见 `~/.config/opencode/agent-templates/coder.md` —— 走 fallback 时主动 `read` 该绝对路径（若 `read` 不展开 `~`，改用 `bash cat ~/.config/opencode/agent-templates/coder.md`），禁止凭印象拼 prompt（漏字段就破坏 reviewer 回报契约）。
 
 ## 失败回退
 

package/agents/coder-quick.md

@@ -98,7 +98,7 @@ fallback_models:
 
 只有被用户直接 `@coder` 或 `/quick` 调出（无 codeforge 上游）时才走 fallback：调 `task` 派 reviewer 或手动 `Tab` 切 agent。
 
-完整 `task({...})` prompt 模板 + 手动 `Tab` / `@reviewer` mention 指令模板见 **[docs/agent-templates/coder.md](../docs/agent-templates/coder.md)** —— 走 fallback 时主动 `read` 该文件，禁止凭印象拼 prompt（漏字段就破坏 reviewer 回报契约）。
+完整 `task({...})` prompt 模板 + 手动 `Tab` / `@reviewer` mention 指令模板见 `~/.config/opencode/agent-templates/coder.md` —— 走 fallback 时主动 `read` 该绝对路径（若 `read` 不展开 `~`，改用 `bash cat ~/.config/opencode/agent-templates/coder.md`），禁止凭印象拼 prompt（漏字段就破坏 reviewer 回报契约）。
 
 ## 失败回退
 

package/agents/coder.md

@@ -23,7 +23,7 @@ model_thinking:
   budget_tokens: 4000
 fallback_models:
   - openai/gpt-5.5
-  - anthropic/claude-opus-4-7
+  - anthropic/claude-opus-4-8
   - google/gemini-3-pro
 ---
 
@@ -93,7 +93,7 @@ fallback_models:
 **未做**：未写任何文件；仅 read 了 handoff.yaml
 ```
 
-完整模板示例（含派 reviewer fallback 的 `task({...})` prompt + 手动 `Tab` / `@reviewer` mention 指令）见 **[docs/agent-templates/coder.md](../docs/agent-templates/coder.md)** —— 走 fallback 时主动 `read` 该文件，禁止凭印象拼 prompt（漏字段就破坏 reviewer 回报契约）。
+完整模板示例（含派 reviewer fallback 的 `task({...})` prompt + 手动 `Tab` / `@reviewer` mention 指令）见 `~/.config/opencode/agent-templates/coder.md` —— 走 fallback 时主动 `read` 该绝对路径（若 `read` 不展开 `~`，改用 `bash cat ~/.config/opencode/agent-templates/coder.md`），禁止凭印象拼 prompt（漏字段就破坏 reviewer 回报契约）。
 
 ## 失败回退
 

package/agents/discover-challenger.md

@@ -17,14 +17,14 @@ allowed_tools:
   # 故意不给 save_chat_insight：challenger 是过程角色，不沉淀
   # 故意不给 task：物理禁止派子 agent（避免嵌套对抗）
   # 故意不给 edit/write：零写权（worktree 也不允许写）
-model: openai/gpt-5.5
+model: openai/gpt-5.5-pro
 model_category: ultrabrain
 tier: deep
 model_thinking:
   type: enabled
   budget_tokens: 3000
 fallback_models:
-  - anthropic/claude-opus-4-7
+  - anthropic/claude-opus-4-8
   - anthropic/claude-sonnet-4-6
   - google/gemini-3-pro
 ---
@@ -33,7 +33,7 @@ fallback_models:
 
 你是 discover 召唤的**强对抗专家**。职责：用第十人视角给现状/PRD 草稿挑刺，给出离散的红旗判定（YES / NO）。
 
-> **选 gpt-5.5 作为主模型的理由**：与 discover 主模型（claude-opus-4-7）跨家族，避免同源视角偏见（与 reviewer agent 选型一致）；红旗 YES/NO 由 §3 离散触发组合锁死，模型迎合倾向只影响"理由文笔"而非"结论"。fallback 链 opus → sonnet → gemini 跨三家保高可用。
+> **选 gpt-5.5 作为主模型的理由**：与 discover 主模型（claude-opus-4-8）跨家族，避免同源视角偏见（与 reviewer agent 选型一致）；红旗 YES/NO 由 §3 离散触发组合锁死，模型迎合倾向只影响"理由文笔"而非"结论"。fallback 链 opus → sonnet → gemini 跨三家保高可用。
 >
 > **历史**：Phase 0 曾选 google/gemini-3-pro（看中"直说"倾向），但 C5 dogfooding 暴露 provider 注册缺失导致 ProviderModelNotFoundError，Phase 1.1 切换至 gpt-5.5。
 

package/agents/planner.md

@@ -101,7 +101,7 @@ ADR: worktree-session-isolation Phase 4 —— planner 改用 plan_write 替代
 5. `## 风险与缓解` — Markdown 表格，至少 2 条风险
 6. `## ADR-Draft` — Context / Options Considered / Decision 三段（trivial 改动可写"无需 ADR：理由 ____"）
 
-完整模板示例（含每节字段、表格列、注释）见 **[docs/agent-templates/planner.md](../docs/agent-templates/planner.md)** —— 出方案前主动 `read` 该文件按模板套，禁止凭印象拼章节顺序或漏 ADR-Draft 章节。
+完整模板示例（含每节字段、表格列、注释）见 `~/.config/opencode/agent-templates/planner.md` —— 出方案前主动 `read` 该绝对路径按模板套（若 `read` 不展开 `~`，改用 `bash cat ~/.config/opencode/agent-templates/planner.md`），禁止凭印象拼章节顺序或漏 ADR-Draft 章节。
 
 ## 失败回退
 

package/agents/reviewer-lite.md

@@ -108,7 +108,7 @@ reviewer 的 `read` 工具**仅允许**读以下路径（白名单）：
 | 允许路径 | 用途 |
 |---|---|
 | `review-profiles/*.md` | 加载对应 review_target 的专项 profile |
-| `docs/agent-templates/*.md` | 兜底参考 reviewer 自身模板（仅 fallback 场景） |
+| `~/.config/opencode/agent-templates/*.md` | 兜底参考 reviewer 自身模板（仅 fallback 场景） |
 | `.codeforge/specs/<slug>/handoff.yaml` | 走 spec 路径时核对需求溯源 |
 | `docs/adr/*.md` | 审 adr profile 时读对照 ADR 内容（仅 review_target=adr 场景） |
 | `docs/adr/template.md` / `docs/adr/README.md` | 审 ADR 时核对模板与索引（仅 adr 场景） |
@@ -237,7 +237,7 @@ reviewer 的 `read` 工具**仅允许**读以下路径（白名单）：
 - **REQUEST_CHANGES** → 首选调 `task` 派 coder 修复（带具体到行的意见），不可用时手动 `Tab` 切 coder
 - **BLOCK** → 首选调 `task` 派 planner 重设计（带原 plan_id + BLOCK 原因），不可用时手动 `Tab` 切 planner
 
-完整 `task({...})` prompt 模板见 **[docs/agent-templates/reviewer.md](../docs/agent-templates/reviewer.md)**。
+完整 `task({...})` prompt 模板见 `~/.config/opencode/agent-templates/reviewer.md`（若 `read` 不展开 `~`，改用 `bash cat ~/.config/opencode/agent-templates/reviewer.md`）。
 
 ## 失败回退
 

package/agents/reviewer.md

@@ -107,7 +107,7 @@ reviewer 的 `read` 工具**仅允许**读以下路径（白名单）：
 | 允许路径 | 用途 |
 |---|---|
 | `review-profiles/*.md` | 加载对应 review_target 的专项 profile |
-| `docs/agent-templates/*.md` | 兜底参考 reviewer 自身模板（仅 fallback 场景） |
+| `~/.config/opencode/agent-templates/*.md` | 兜底参考 reviewer 自身模板（仅 fallback 场景） |
 | `.codeforge/specs/<slug>/handoff.yaml` | 走 spec 路径时核对需求溯源 |
 | `docs/adr/*.md` | 审 adr profile 时读对照 ADR 内容（仅 review_target=adr 场景） |
 | `docs/adr/template.md` / `docs/adr/README.md` | 审 ADR 时核对模板与索引（仅 adr 场景） |
@@ -236,7 +236,7 @@ reviewer 的 `read` 工具**仅允许**读以下路径（白名单）：
 - **REQUEST_CHANGES** → 首选调 `task` 派 coder 修复（带具体到行的意见），不可用时手动 `Tab` 切 coder
 - **BLOCK** → 首选调 `task` 派 planner 重设计（带原 plan_id + BLOCK 原因），不可用时手动 `Tab` 切 planner
 
-完整 `task({...})` prompt 模板见 **[docs/agent-templates/reviewer.md](../docs/agent-templates/reviewer.md)**。
+完整 `task({...})` prompt 模板见 `~/.config/opencode/agent-templates/reviewer.md`（若 `read` 不展开 `~`，改用 `bash cat ~/.config/opencode/agent-templates/reviewer.md`）。
 
 ## 失败回退
 

package/commands/deep.md

@@ -16,7 +16,7 @@ codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）
 
 # /deep — 临时升档到 deep（Opus + 大 thinking）
 
-把指定 agent 的模型临时升到 `deep` 档（默认 `anthropic/claude-opus-4-7` + 大 thinking budget）。
+把指定 agent 的模型临时升到 `deep` 档（默认 `anthropic/claude-opus-4-8` + 大 thinking budget）。
 改动会直接写入当前 session worktree（由 session-worktree-guard 隔离主仓），**由用户 `/merge` 拍板合并到主仓后才会真正生效**。
 
 ## 输入

package/dist/index.js

@@ -13046,9 +13046,7 @@ async function mergeSessionBack(opts) {
         throw new Error(`${buildScript} 失败已 reset 主仓: ${msg}`);
       }
     }
-  } else {
-    console.debug(`[session-worktree] skip build step: merge.postMergeScript not configured in .codeforge/codeforge.json (project may not need post-merge build)`);
-  }
+  } else {}
   const squashedRaw = await runGit2(wt, ["log", "--format=%s", `${baseSha}..HEAD`]);
   const squashedCommits = squashedRaw.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
   const message = opts.commitMessage ?? buildMergeMessage(opts.sessionId, branch, baseSha, squashedCommits);
@@ -17526,6 +17524,40 @@ function extractCreatedChild(event) {
     return null;
   return { childID: session.id, parentID: session.parentID, agent: null };
 }
+var ERROR_REASON_MAX_LEN = 300;
+function extractErrorReason(props) {
+  function sanitize(s) {
+    const folded = s.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim();
+    if (folded.length <= ERROR_REASON_MAX_LEN)
+      return folded;
+    return folded.slice(0, ERROR_REASON_MAX_LEN) + "…";
+  }
+  function extractFromValue(v) {
+    if (typeof v === "string" && v.trim())
+      return sanitize(v);
+    if (v && typeof v === "object") {
+      const obj = v;
+      const dataMsg = obj["data"] && typeof obj["data"] === "object" ? obj["data"]["message"] : undefined;
+      const fromMsg = obj["message"] ?? dataMsg ?? obj["reason"];
+      if (typeof fromMsg === "string" && fromMsg.trim())
+        return sanitize(fromMsg);
+    }
+    return null;
+  }
+  const fromError = extractFromValue(props["error"]);
+  if (fromError !== null)
+    return fromError;
+  if (typeof props["message"] === "string" && props["message"].trim())
+    return sanitize(props["message"]);
+  if (typeof props["reason"] === "string" && props["reason"].trim())
+    return sanitize(props["reason"]);
+  if (props["info"] && typeof props["info"] === "object") {
+    const fromInfoError = extractFromValue(props["info"]["error"]);
+    if (fromInfoError !== null)
+      return fromInfoError;
+  }
+  return null;
+}
 function extractEndedSessionID(event) {
   if (!event || typeof event !== "object")
     return null;
@@ -17537,15 +17569,19 @@ function extractEndedSessionID(event) {
   }
   const props = e.properties ?? {};
   const direct = props["sessionID"];
-  if (typeof direct === "string" && direct)
-    return { type: e.type, sessionID: direct };
-  const info = props["info"];
-  if (info && typeof info === "object") {
-    const sid = info.id;
-    if (typeof sid === "string" && sid)
-      return { type: e.type, sessionID: sid };
-  }
-  return null;
+  const sessionID = typeof direct === "string" && direct ? direct : (() => {
+    const info = props["info"];
+    if (info && typeof info === "object") {
+      const sid = info.id;
+      if (typeof sid === "string" && sid)
+        return sid;
+    }
+    return null;
+  })();
+  if (!sessionID)
+    return null;
+  const errorReason = e.type === "session.error" ? extractErrorReason(props) : null;
+  return { type: e.type, sessionID, errorReason };
 }
 function extractTaskArgs(args) {
   if (!args || typeof args !== "object")
@@ -17765,6 +17801,15 @@ function buildAfterLogLine(toolName, ok, durationMs, now = Date.now()) {
     duration_ms: durationMs
   });
 }
+function buildErrorLogLine(errorReason, elapsedMs, now = Date.now()) {
+  return JSON.stringify({
+    ts: Math.floor(now / 1000),
+    phase: "error",
+    ok: false,
+    error_reason: errorReason ?? "(unknown)",
+    elapsed_ms: elapsedMs
+  });
+}
 async function appendSubagentLog(filePath, line, log7) {
   try {
     await fsPromises.mkdir(path20.dirname(filePath), { recursive: true });
@@ -17952,6 +17997,40 @@ var subtaskHeartbeatServer = async (ctx) => {
               toast_sent: sent,
               end_toast_message: t.message
             });
+            if (ended.type === "session.error" && isLogPersistenceEnabled(cwd)) {
+              const elapsedMs = Date.now() - r.startedAt;
+              const errLine = buildErrorLogLine(ended.errorReason, elapsedMs);
+              const logFile = subagentLogPath(cwd, r.parentID, r.childID);
+              appendSubagentLog(logFile, errLine, log7);
+              const parentID = r.parentID;
+              const who = r.agent ? titleCase(r.agent) : "subagent";
+              const elapsed = fmtElapsed(elapsedMs);
+              const noticeText = [
+                `❌ ${who} 失败（${elapsed}）`,
+                ended.errorReason ? `错误：${ended.errorReason.slice(0, 150)}` : null,
+                `日志：${logFile}`,
+                `排查：cat "${logFile}" | tail -30`
+              ].filter(Boolean).join(`
+`);
+              const logAdapter = (level, msg, data) => {
+                if (level === "warn" || level === "error") {
+                  log7.warn(`[sendParentNotice] ${msg}`, data);
+                }
+              };
+              (async () => {
+                try {
+                  await sendParentNotice(client, parentID, noticeText, { directory: cwd, log: logAdapter });
+                  safeWriteLog(PLUGIN_NAME11, {
+                    hook: "event",
+                    type: "session.error.notified",
+                    child: r.childID,
+                    parent: r.parentID,
+                    has_error_reason: ended.errorReason !== null,
+                    notice_text_len: noticeText.length
+                  });
+                } catch {}
+              })();
+            }
             if (ended.type === "session.deleted") {
               const logFile = subagentLogPath(cwd, r.parentID, r.childID);
               fsPromises.unlink(logFile).catch(() => {});
@@ -21150,7 +21229,7 @@ import * as zlib from "node:zlib";
 // lib/version-injected.ts
 function getInjectedVersion() {
   try {
-    const v = "0.5.26";
+    const v = "0.5.27";
     if (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v)) {
       return v;
     }

package/install.ps1

@@ -88,7 +88,8 @@ $CodeforgeCfgDir = Join-Path $XdgConfigBase 'codeforge'
 # v0.1 之前 install.ps1 装的目录（卸载时一并清掉）
 $LegacyDirs    = @('agent', 'command', 'tool', 'tools', 'plugin', 'plugins', 'lib')
 # v0.1+ 才有的目录（review-profiles 由 ADR:reviewer-multi-profile 引入）
-$ManagedDirs   = @('codeforge', 'agents', 'commands', 'workflows', 'context-templates', 'review-profiles')
+# agent-templates 由 ADR:agent-templates-move-to-root 移到根目录（supersedes agent-templates-distribution）
+$ManagedDirs   = @('codeforge', 'agents', 'commands', 'workflows', 'context-templates', 'review-profiles', 'agent-templates')
 
 # v0.1+ 文件分发计划
 $BundleSrcRel  = 'dist/index.js'
@@ -103,10 +104,12 @@ $MdCopyMap = @(
   @{ Src='commands'; Dst='commands' }
 )
 # 普通整目录 copy（review-profiles 由 ADR:reviewer-multi-profile 引入）
+# ADR:agent-templates-move-to-root — agent-templates 随 install 分发到全局目录
 $CopyMap = @(
-  @{ Src='workflows';         Dst='workflows'         },
-  @{ Src='context-templates'; Dst='context-templates' },
-  @{ Src='review-profiles';   Dst='review-profiles'   }
+  @{ Src='workflows';            Dst='workflows'            },
+  @{ Src='context-templates';    Dst='context-templates'    },
+  @{ Src='review-profiles';      Dst='review-profiles'      },
+  @{ Src='agent-templates';      Dst='agent-templates'      }
 )
 
 # ────────────── opencode.json 管理 ──────────────

package/install.sh

@@ -118,7 +118,8 @@ CODEFORGE_CFG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/codeforge"
 # v0.1 之前装的目录（卸载时一并清掉）
 LEGACY_DIRS=(agent command tool tools plugin plugins lib)
 # v0.1+ 才有的目录（review-profiles 由 ADR:reviewer-multi-profile 引入）
-MANAGED_DIRS=(codeforge agents commands workflows context-templates review-profiles)
+# agent-templates 由 ADR:agent-templates-move-to-root 移到根目录（supersedes agent-templates-distribution）
+MANAGED_DIRS=(codeforge agents commands workflows context-templates review-profiles agent-templates)
 
 BUNDLE_SRC_REL="dist/index.js"
 BUNDLE_DST_REL="codeforge/index.js"
@@ -126,7 +127,8 @@ BUNDLE_DST_REL="codeforge/index.js"
 # 文件级 copy 白名单（.md，排除 README/_*/.bak/.*）
 MD_COPY_DIRS=("agents:agents" "commands:commands")
 # 整目录拷贝（review-profiles 由 ADR:reviewer-multi-profile 引入，避开 maxdepth 1 限制）
-COPY_DIRS=("workflows:workflows" "context-templates:context-templates" "review-profiles:review-profiles")
+# ADR:agent-templates-move-to-root — agent-templates 随 install 分发到全局目录
+COPY_DIRS=("workflows:workflows" "context-templates:context-templates" "review-profiles:review-profiles" "agent-templates:agent-templates")
 
 # KH 行为规范模板（B3 智能合并的输入）
 KH_TEMPLATE_REL="context-templates/kh-instructions.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andyqiu/codeforge",
-  "version": "0.5.26",
+  "version": "0.5.27",
   "description": "CodeForge — opencode 的零侵入扩展包",
   "type": "module",
   "private": false,
@@ -110,6 +110,7 @@
     "dist/adr-init.js",
     "dist/adr-init.d.ts",
     "agents/",
+    "agent-templates/",
     "assets/",
     "bin/",
     "commands/",

package/review-profiles/plan-only.md

@@ -27,7 +27,7 @@
 
 ## 强制章节检查（机审清单 — 等价章节可接受）
 
-按 `docs/agent-templates/planner.md` 模板核对，**允许等价章节命名**：
+按 `agent-templates/planner.md` 模板核对，**允许等价章节命名**：
 
 - [ ] **需求理解**（标题包含「需求」/「理解」/「目标」之一即可，≤ 5 行）
 - [ ] **项目上下文**（标题含「上下文」/「背景」/「现状」之一）