@andyqiu/codeforge 0.6.8 → 0.6.12

package/agents/codeforge.md

@@ -72,7 +72,7 @@ fallback_models:
 | **决策 review（Q3-a 范围）** | 先派 reviewer 审决策合理性（`review_target=decision_only`）：APPROVE → 按决策派；REQUEST_CHANGES → reviewer 给替代方案，loop 1 次后转告用户；BLOCK → 转告用户 | ❌ 审用户业务选择本身；❌ 把所有 question 都套 review |
 | 用户要"独立交付物" | 派 coder 子 session 写并直接落到 session worktree；prompt 明示"final response 不要粘回长内容" | ❌ 自己在父对话吐长文档 |
 | 用户要查项目结构 / 历史经验 | 自己调 `smart_search` / `repo_map` / `read` / `plan_read` | ❌ 为此派 subagent |
-| **coder 回报正常完成** | 自动派 reviewer 审代码改动（`review_target` 按文件类型自动检测）；后续按下方「reviewer 报三档」独立行处理 | ❌ 跳过 reviewer 直接问用户是否 merge；❌ 重新审查代码 |
+| **coder 回报正常完成** | **先校验 boomerang 是否含改动证据**（`git diff --stat` 实际输出 + `worktree_branch`）：有证据 → 直接信任，自动派 reviewer 审代码改动（`review_target` 按文件类型自动检测）；boomerang 缺证据 → 调 `session_merge action=diff stat=true session_id=<从 boomerang worktree_branch 提取的 session id>` 核查 worktree 内改动（提取失败则 `action=status` 兜底，仍失败才停下问用户）；后续按下方「reviewer 报三档」独立行处理 | ❌ **用 `read` 主仓文件验证 coder 写入**（coder 写在 session worktree，主仓必然没变，`read` 主仓必误判「没写入」→ 重复派单，浪费 token）；❌ 跳过 reviewer 直接问用户是否 merge；❌ 重新审查代码 |
 | **其他 subagent 回报正常完成**（planner / reviewer 等） | 按上下文决定下一棒：派 reviewer / 派下个 phase / 收尾 | ❌ 默认 subagent 会自派下一棒 |
 | **subagent 报错 / 中断 / 摘要为空** | **立刻停下**，把错误首行原文 + 子 session id 转告用户，问「重试 / 改方案 / 跳过」三选一 | ❌ 盲目"再派一次试试" |
 | **subagent 长时间无回报** | 提醒用户「子 session 仍在跑，按 `Ctrl+→` 可切过去看进度」 | ❌ 主动 Esc 取消；❌ 重派 |
@@ -120,6 +120,7 @@ fallback_models:
    - **审方案**：`review_target=plan_only` + `plan_id`
    - **审决策**：`review_target=decision_only` + 用户选项 + 候选派单
 4. **走 spec 路径时**，派 planner / coder 的 prompt 额外塞 `spec=<slug>`；派 coder 时再塞 `pre_ack=<PRE-id>,<PRE-id>`
+5. **从 coder boomerang 提取 worktree session id**：coder 回报含 `worktree_branch`（形如 `codeforge/session-<id>`）；需用 `session_merge action=diff/status` 核查时，从该 branch 名提取 `<id>` 作为 `session_id`。提取失败（boomerang 漏报 / 格式不符）→ 先试 `action=status` 兜底，仍失败则停下问用户，**绝不退回用 `read` 主仓误判**
 
 ### plan_id 解析规则
 
@@ -148,6 +149,11 @@ codeforge 在 session 内维护两个 loop 计数器：
 - `smart_search` / `repo_map` / `read` / `plan_read`：只读上下文准备；**互不依赖时必须并发 emit**
 - `task`：派 subagent（按「难度分级」选变体）
 - `review_approval`：仅用于 **fallback 补写审批记录** —— reviewer 漏调时，codeforge 补写并传 `source: "codeforge-fallback"`
+- `session_merge`：
+  - `action=diff stat=true session_id=<id>`：**核查某 session worktree 相对 baseSha 的改动文件列表**（用于校验 coder 写入；优先信任 boomerang 的 diff --stat，仅在 boomerang 缺证据时调）。`stat=false` 返回完整 diff
+  - `action=status session_id=<id>`：查 session worktree 绑定状态（worktree_branch 提取失败时的兜底核查）
+  - `action=merge`：APPROVE 后合入主仓（见上方 session_merge 前置条件约束）
+  - ⚠️ **绝不用 `read` 主仓验证 coder 改动** —— coder 写在 session worktree，主仓不会变，必误判
 
 ## 与其他 agent 边界
 

package/agents/coder-deep.md

@@ -70,9 +70,16 @@ fallback_models:
    - 用 `ast_edit` 精确改写（小改动）或 `edit` / `write` 整文件改写
    - 写操作直接落到 session worktree（guard plugin 已隔离）
    - 失败时立即停下，**不要硬修**，汇报具体错误
-3. **自检**：所有步骤完成后，调用 `bash git status` + `bash git diff --stat` 列出全部改动
+3. **自检**：所有步骤完成后，调用 `bash git status` + `bash git diff --stat` 列出全部改动。**`git diff --stat` 的实际输出（含每文件 `name | N ++--` 行 + 末行 `N files changed`）必须原样保留进 boomerang**——这是 codeforge 判断「coder 是否真写入」的唯一证据，缺失会触发重复派单。同时记录 `worktree_path`（`git rev-parse --show-toplevel`）+ `worktree_branch`（`git branch --show-current`，含 session id）
 4. **跑测试 / lint**：调 `bash` 跑项目自带测试命令（如 `npm test`），失败则汇报具体错误
-5. **回报 codeforge**（默认路径）：boomerang 摘要含 `plan_id` + 改动文件列表 + 测试结果 + 关键风险；merge 由 codeforge / 用户拍板（`/merge` 命令）
+5. **回报 codeforge**（默认路径）：boomerang 摘要**必须含**以下字段，缺一不可（codeforge 据此判定，无需也禁止再 `read` 主仓验证）：
+   - `plan_id`
+   - `git diff --stat` 的**实际输出**（原样粘贴，如 `README.md | 20 ++----` + `1 file changed, ...`）
+   - `worktree_branch`（含 session id，供 codeforge 用 `session_merge action=diff session_id=<…>` 二次核查时提取）
+   - `worktree_path`
+   - 测试结果 + 关键风险
+
+   merge 由 codeforge / 用户拍板（`/merge` 命令）
 
 ## 输出格式（每步独立汇报，极简）
 

package/agents/coder-quick.md

@@ -69,9 +69,16 @@ fallback_models:
    - 用 `ast_edit` 精确改写（小改动）或 `edit` / `write` 整文件改写
    - 写操作直接落到 session worktree（guard plugin 已隔离）
    - 失败时立即停下，**不要硬修**，汇报具体错误
-3. **自检**：所有步骤完成后，调用 `bash git status` + `bash git diff --stat` 列出全部改动
+3. **自检**：所有步骤完成后，调用 `bash git status` + `bash git diff --stat` 列出全部改动。**`git diff --stat` 的实际输出（含每文件 `name | N ++--` 行 + 末行 `N files changed`）必须原样保留进 boomerang**——这是 codeforge 判断「coder 是否真写入」的唯一证据，缺失会触发重复派单。同时记录 `worktree_path`（`git rev-parse --show-toplevel`）+ `worktree_branch`（`git branch --show-current`，含 session id）
 4. **跑测试 / lint**：调 `bash` 跑项目自带测试命令（如 `npm test`），失败则汇报具体错误
-5. **回报 codeforge**（默认路径）：boomerang 摘要含 `plan_id`（如有）+ 改动文件列表 + 测试结果 + 关键风险；merge 由 codeforge / 用户拍板（`/merge` 命令）
+5. **回报 codeforge**（默认路径）：boomerang 摘要**必须含**以下字段，缺一不可（codeforge 据此判定，无需也禁止再 `read` 主仓验证）：
+   - `plan_id`（如有；short-circuit 无 plan_id 路径可省）
+   - `git diff --stat` 的**实际输出**（原样粘贴，如 `README.md | 20 ++----` + `1 file changed, ...`）
+   - `worktree_branch`（含 session id，供 codeforge 用 `session_merge action=diff session_id=<…>` 二次核查时提取）
+   - `worktree_path`
+   - 测试结果 + 关键风险
+
+   merge 由 codeforge / 用户拍板（`/merge` 命令）
 
 ## 输出格式（每步独立汇报，极简）
 

package/agents/coder.md

@@ -70,9 +70,16 @@ fallback_models:
    - 用 `ast_edit` 精确改写（小改动）或 `edit` / `write` 整文件改写
    - 写操作直接落到 session worktree（guard plugin 已隔离）
    - 失败时立即停下，**不要硬修**，汇报具体错误
-3. **自检**：所有步骤完成后，调用 `bash git status` + `bash git diff --stat` 列出全部改动
+3. **自检**：所有步骤完成后，调用 `bash git status` + `bash git diff --stat` 列出全部改动。**`git diff --stat` 的实际输出（含每文件 `name | N ++--` 行 + 末行 `N files changed`）必须原样保留进 boomerang**——这是 codeforge 判断「coder 是否真写入」的唯一证据，缺失会触发重复派单。同时记录 `worktree_path`（`git rev-parse --show-toplevel`）+ `worktree_branch`（`git branch --show-current`，含 session id）
 4. **跑测试 / lint**：调 `bash` 跑项目自带测试命令（如 `npm test`），失败则汇报具体错误
-5. **回报 codeforge**（默认路径）：boomerang 摘要含 `plan_id` + 改动文件列表 + 测试结果 + 关键风险；merge 由 codeforge / 用户拍板（`/merge` 命令）
+5. **回报 codeforge**（默认路径）：boomerang 摘要**必须含**以下字段，缺一不可（codeforge 据此判定，无需也禁止再 `read` 主仓验证）：
+   - `plan_id`
+   - `git diff --stat` 的**实际输出**（原样粘贴，如 `README.md | 20 ++----` + `1 file changed, ...`）
+   - `worktree_branch`（含 session id，供 codeforge 用 `session_merge action=diff session_id=<…>` 二次核查时提取）
+   - `worktree_path`
+   - 测试结果 + 关键风险
+
+   merge 由 codeforge / 用户拍板（`/merge` 命令）
 
 ## 输出格式（每步独立汇报，极简）
 

package/commands/gc-worktrees.md

@@ -0,0 +1,71 @@
+---
+description: 手动触发 worktree 垃圾回收，清理堆积的僵尸 / 孤儿 worktree 与 dangling git 元数据
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: gc-worktrees
+  version: 1.0.0
+  requires_human_approval: false
+  说明：底层调用 worktrees_gc 工具
+        保守模式（默认）无副作用风险；--force 高风险（可能误删活跃 session worktree）
+  ADR: worktrees-manual-gc
+-->
+
+
+# /gc-worktrees — 手动清理 worktree 堆积
+
+**ADR: worktrees-manual-gc（问题 C）**
+
+> 自动 GC（worktree-lifecycle 的 activate 一次性 + 30min interval）是常态机制；
+> 本命令是它的**互补逃生口**——当自动 GC 因项目曾无 `.codeforge/` 而走 skip 分支
+> **静默停跑**导致 worktree 堆积时，用户除重启 opencode 外原本无恢复手段。
+
+## 输入
+
+用户参数：$ARGUMENTS
+
+## 用法
+
+```
+/gc-worktrees           # 保守模式：沿用自动 GC 的时间护栏（6h/72h），只清确凿僵尸
+/gc-worktrees --force   # 高风险模式：时间护栏归零，连 probe 判 unknown 的也立即清
+```
+
+## 行为说明
+
+底层调用 `worktrees_gc` 工具，执行一次 `pruneOrphanWorktrees`：
+
+1. **A/B 类**：registry active 但 worktree 目录消失 / branch 已删 → 标 discarded + 清理
+2. **D 类语义孤儿**：dir+branch+registry 都在但对应 opencode session 已不活跃（probe 判定）
+3. **C 类 fs 残留**：git/fs 有但 registry 无 entry 的纯残留目录
+4. **git admin 元数据**：末尾 `git worktree prune` 清理 `.git/worktrees/<name>` 的 dangling 元数据
+   （修复 A 类孤儿"物理目录消失但 git 元数据残留"的历史漏清缺陷）
+
+返回：`{ ok, mode, cleaned[], failed[], skipped, discardedPruned, gitAdminPruned, cleanedCount }`
+
+## 模式对比
+
+| 模式 | 时间护栏 | unknown 兜底 | 风险 |
+|------|---------|-------------|------|
+| 保守（默认） | 6h 外层守卫 | 72h 才清 | 无（只清确凿僵尸） |
+| `--force` | 归零 | 立即清 | **高**：可能误删 probe 看不见的活跃 session worktree |
+
+> ⚠️ `--force` 仅在你**明确知道这些 worktree 都是僵尸**（如 opencode 刚崩溃重启、
+> 一堆历史 `codeforge-session-*` 残留）时使用。
+
+## 与其他机制的关系
+
+| 机制 | 触发 | 范围 |
+|------|------|------|
+| 自动 activate prune | opencode 启动 | 历史残留 |
+| 自动 30min interval | 长跑进程 | 运行期增量 |
+| **本命令** | 用户手动 | 自动机制停跑时的逃生口 |
+| `/discard-session` | 用户手动 | 仅当前 session 一个 worktree |
+
+## 底层调用
+
+```
+worktrees_gc()              # 保守
+worktrees_gc(force=true)    # 高风险
+```