ccgx-workflow 2.4.1 → 2.5.0

package/templates/commands/plan.md

@@ -52,16 +52,16 @@ $ARGUMENTS
 
 ## 调用通道路由（CCG codeagent 退役）
 
-CCG 把 6 核心命令的"双模型并行"通道从 `Bash(codeagent-wrapper)` **默认切换**为 plugin spawn。判定流程：
+CCG 把"双模型并行"通道从 `Bash(codeagent-wrapper)` **默认切换**为 Bash 直调 plugin 快路径。判定流程：
 
-1. **优先 plugin spawn 路径**（默认）：用户已装 `codex@openai-codex` 和 gemini plugin（推荐 `gemini@gemini-ccgx` fork，已含全部 patch；或上游 `gemini@google-gemini` 配 repatch）→ 用 `Agent(subagent_type="codex:codex-rescue")` + `Agent(subagent_type="gemini:gemini-rescue")` 并行 spawn，主线只接 plugin 自家 ≤200 token 摘要协议（`STATUS: ... / FINDINGS: ... / NOTES: ...`）。
+1. **优先 Bash 直调 plugin 快路径**（默认）：用户已装 `codex@openai-codex` 和 gemini plugin（推荐 `gemini@gemini-ccgx` fork，已含全部 patch；或上游 `gemini@google-gemini` 配 repatch）→ 用 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` 占位符 + `--prompt-file` 并行 Bash 直调（review.md 同款），绕开 sonnet wrapper silent-fallback；**仅 `gemini-ccgx` fork 走 gemini-batch 29s 快路径，上游 + repatch 仍走 companion(ACP) 慢路径**（Windows 实测 5+min 卡死风险仍在），主线 `JSON.parse(stdout)` 取 helper 扁平化后的 `.text` / `.threadId`。
 2. **降级 codeagent-wrapper 路径**（BC fallback）：plugin 未装 → fallback 到 `Bash(~/.claude/bin/codeagent-wrapper --backend ... resume ... <<'EOF' ... EOF)`，与 plugin 路径行为等价。
 
-**判断方法**：preflight `Bash` 跑 `node ~/.claude/.ccg/scripts/check-plugins.cjs`（解析 Claude Code 权威 `installed_plugins.json`）。返回 JSON `{"codex":"<ver>"|null,"gemini":"<ver>"|null}`，两个 plugin 独立判定，可分别 mix-and-match（仅 codex plugin 装了 → backend 走 plugin、frontend 走 codeagent）。exit `0` = 两 plugin 都在；非 `0` = 至少一个缺。`Agent(...)` 调用与 `Bash(...)` 调用的具体语法见下面"多模型调用规范"段。
+**判断方法**：preflight `Bash` 跑 `node ~/.claude/.ccg/scripts/check-plugins.cjs`（解析 Claude Code 权威 `installed_plugins.json`）。返回 JSON `{"codex":"<ver>"|null,"gemini":"<ver>"|null}`，两个 plugin 独立判定，可分别 mix-and-match（仅 codex plugin 装了 → backend 走 plugin、frontend 走 codeagent）。exit `0` = 两 plugin 都在；非 `0` = 至少一个缺。Bash 直调与 codeagent fallback 的具体语法见下面"多模型调用规范"段。
 
-**为什么默认 plugin**：nested-spawn 测试证明 plugin advisor 摘要协议（≤200 token）压制了 codeagent stdout 全文回灌主线的痛点，主线 context 增量从 +5%/调用 降到 +1.5%/调用。详见 `.ccg-research/07-multimodel-collaboration-rethink.md`。
+**为什么默认 Bash 直调快路径**：Bash 直调消除 `Agent(...)` 引擎启动的 sonnet wrapper 层（broker 故障 / auth 过期时 wrapper 会自答 fabricated cross-vendor 视角，主线无法察觉），stdout 即真实 plugin 输出；且 gemini 侧装 `gemini-ccgx` fork 时直吃 gemini-batch 29s 快路径，不再走 ACP broker 5+min 卡死。详见 `.ccg-research/07-multimodel-collaboration-rethink.md`。
 
-⚠️ **重要**：本命令本身不在 subagent context 内（主线命令），**可以**调 `Agent(...)` 工具——这跟 `phase-runner` 等 subagent 的"引擎层禁止嵌套 spawn Agent"约束不冲突。
+⚠️ **重要**：本命令在主线 context 内执行，通道 A 走 Bash 直调（不再 spawn `Agent(...)`），无嵌套 spawn 顾虑；`plan-checker` 校验 agent 仍按原样 `Agent(...)` spawn（主线允许）。
 
 ---
 
@@ -74,28 +74,49 @@ CCG 把 6 核心命令的"双模型并行"通道从 `Bash(codeagent-wrapper)` **
 
 **调用语法**（双通道）：
 
-**通道 A — plugin spawn（默认）**：
+**通道 A — Bash 直调 plugin 快路径（默认，绕开 sonnet wrapper + ACP 慢路径）**：
+
+> 占位符 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` 由 install 时渲染为
+> `node <ccgx-call-plugin.mjs 绝对路径> <vendor> --json`。LLM **只需把 prompt
+> 写入 tmpfile、追加 `--prompt-file <tmpfile>`、运行**，不写 `Agent(...)`。
 
 ```
-Agent({
-  subagent_type: "<codex:codex-rescue|gemini:gemini-rescue>",
-  description: "Plan analysis: <backend|frontend>",
-  prompt: `ROLE_FILE: <角色提示词路径>
+Step 1. 用 Write 把任务描述写到 tmpfile（≤2KB，上下文用文件路径 + 符号名引用，不塞大段源码）：
+   Write({ file_path: ".context/tmp/ccg-plan-codex-$JOB.txt", content: <下方"任务描述模板"> })
+   Write({ 同上，gemini 版本，file_path: ".context/tmp/ccg-plan-gemini-$JOB.txt" })
+
+Step 2. 用 Bash 调 helper（占位符已渲染；并行两个在同一 message 内 run_in_background: true）：
+   Bash({ command: `{{CODEX_BASH_TASK}} --prompt-file .context/tmp/ccg-plan-codex-$JOB.txt`, description: "Plan: backend (codex direct)", run_in_background: true })
+   Bash({ command: `{{GEMINI_BASH_TASK}} --prompt-file .context/tmp/ccg-plan-gemini-$JOB.txt`, description: "Plan: frontend (gemini direct)", run_in_background: true })
+
+Step 3. 等 task-notification 后 Read 各自 stdout，`JSON.parse(stdout)` 取 helper 扁平化后的 `.text`
+   （= 模型真实输出）与 `.threadId`（**保存为 CODEX_SESSION / GEMINI_SESSION，供 /ccg:execute resume 使用**）。
+```
+
+**任务描述模板**（写到 tmpfile 的内容；保持 ≤2KB）：
+
+```
+# 任务：多模型协作规划
+
+工作目录：<工作目录绝对路径>（你已在此，可直接用 Bash/Read）
+角色定义见 <角色提示词路径>（codex 用 ~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/<analyzer|architect>.md，gemini 用 {{FRONTEND_PRIMARY}}/<analyzer|architect>.md），**先用 Read 工具读取该文件再开始**。
+
+## 你要做的事
 
-<TASK>
 需求：<增强后的需求>
-上下文：<检索到的项目上下文>
-</TASK>
+上下文：<检索到的关键文件路径 + 符号名，不塞大段源码，让你自己 Read>
 
-OUTPUT: Step-by-step implementation plan with pseudo-code. DO NOT modify any files.
-Return ≤200 token structured summary (plugin-native protocol).
-`
-})
+OUTPUT: Step-by-step implementation plan with pseudo-code.
+
+## 硬约束
+
+- **必须前台执行，禁止 `--background` / `--wait`**（ccgx 编排层已用 Agent run_in_background 包裹，插件内再 background = 双重后台，stop-gate / status / cancel 全盲）。
+- **DO NOT modify any files**，仅规划。
 ```
 
-并行**两个 Agent 在同一 message 内同时 spawn**，主线接 plugin 摘要后无需 `TaskOutput` 轮询。
+⛔ **严禁**：塞大段源码（撞 argv ~32KB 上限）；写 `Agent(subagent_type="gemini:gemini-rescue")`（走 ACP 慢路径）；heredoc / `-p "..."` 内联；硬编码 plugin 路径。**唯一允许**：copy 占位符 + 追加 `--prompt-file <tmpfile>`。
 
-**通道 B — codeagent-wrapper fallback**（plugin 未装时降级，并行用 `run_in_background: true`）：
+**通道 B — codeagent-wrapper fallback**（plugin 未装时降级，并行用 `run_in_background: true`；wrapper 的 `ROLE_FILE:` 由 `invoke-model.mjs` 解析故保留）：
 
 ```
 Bash({
@@ -113,7 +134,7 @@ EOF",
 })
 ```
 
-> ⚠️ 通道 B 走 `codeagent-wrapper`（Node 脚本 `templates/scripts/invoke-model.mjs`），已标 **deprecated**，建议用户安装 codex/gemini plugin 享受主线 context 优化。
+> ⚠️ 通道 B 走 `codeagent-wrapper`（Node 脚本 `templates/scripts/invoke-model.mjs`），已标 **deprecated**，仅 plugin 未装时使用。
 
 **角色提示词**：
 
@@ -122,7 +143,7 @@ EOF",
 | 分析 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md` |
 | 规划 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/architect.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/architect.md` |
 
-**会话复用**：每次调用返回 `SESSION_ID: xxx`（通常由 wrapper 输出），**必须保存**以供后续 `/ccg:execute` 使用。
+**会话复用**：通道 A 从 helper 扁平化输出的 `.threadId` 取会话标识；通道 B 从 wrapper 输出的 `SESSION_ID: xxx` 取。**必须保存为 `CODEX_SESSION` / `GEMINI_SESSION`** 以供后续 `/ccg:execute resume <SESSION_ID>` 使用。
 
 **事件驱动等待**：spawn 后主线说明 task-id 然后 **turn end**，引擎自动 `<task-notification>` 触发新 turn 处理结果。**不调 TaskOutput**。
 
@@ -180,13 +201,13 @@ EOF",
 
 将**原始需求**（不带预设观点）分发给两个模型：
 
-1. **{{BACKEND_PRIMARY}} 后端分析**：
-   - ROLE_FILE: `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md`
+1. **{{BACKEND_PRIMARY}} 后端分析**（`{{CODEX_BASH_TASK}} --prompt-file <tmpfile>`）：
+   - 角色：tmpfile 内写"角色定义见 `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md`，先用 Read 工具读取再开始"
    - 关注：技术可行性、架构影响、性能考量、潜在风险
    - OUTPUT: 多角度解决方案 + 优劣势分析
 
-2. **{{FRONTEND_PRIMARY}} 前端分析**：
-   - ROLE_FILE: `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md`
+2. **{{FRONTEND_PRIMARY}} 前端分析**（`{{GEMINI_BASH_TASK}} --prompt-file <tmpfile>`）：
+   - 角色：tmpfile 内写"角色定义见 `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md`，先用 Read 工具读取再开始"
    - 关注：UI/UX 影响、用户体验、视觉设计
    - OUTPUT: 多角度解决方案 + 优劣势分析
 
@@ -206,20 +227,25 @@ EOF",
 为降低 Claude 合成计划的遗漏风险，可并行让两个模型输出“计划草案”（仍然**不允许**修改文件）：
 
 1. **{{BACKEND_PRIMARY}} 计划草案**（后端权威）：
-   - ROLE_FILE: `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/architect.md`
+   - 角色：tmpfile 内写"角色定义见 `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/architect.md`，先用 Read 工具读取再开始"
    - OUTPUT: Step-by-step plan + pseudo-code（重点：数据流/边界条件/错误处理/测试策略）
 
 2. **{{FRONTEND_PRIMARY}} 计划草案**（前端权威）：
-   - ROLE_FILE: `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/architect.md`
+   - 角色：tmpfile 内写"角色定义见 `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/architect.md`，先用 Read 工具读取再开始"
    - OUTPUT: Step-by-step plan + pseudo-code（重点：信息架构/交互/可访问性/视觉一致性）
 
-用 `TaskOutput` 等待两个模型的完整结果，并记录其建议的关键差异点。
+事件驱动等待两个模型的完整结果（task-notification 唤醒，**不调 TaskOutput**），并记录其建议的关键差异点。
 
 #### 2.4 生成实施计划（Claude 最终版）
 
 综合双方分析，生成 **Step-by-step 实施计划**：
 
 ```markdown
+---
+plan: <功能名>
+requirements: [REQ-XX, ...]  # 当 .ccg/roadmap.md 当前 phase 有 Requirements 行时必填，否则省略
+---
+
 ## 📋 实施计划：<任务名称>
 
 ### 任务类型
@@ -281,6 +307,30 @@ if loop_count == 3 and result.hasBlocker:
 
 只有 plan-checker ✅ 放行（或用户选 force）后才进入计划交付。
 
+### 🚧 Phase 2.6：Requirements Coverage Gate（确定性，[Gate: escalation]）
+
+plan-checker 放行后、计划交付前，跑确定性的 REQ-ID 覆盖检查（**算法权威：`src/utils/plan-checker.ts:extractPhaseRequirementIds` + `checkRequirementsCoverage`**，模板内描述只是其人类可读镜像）：
+
+```
+a) 读 .ccg/roadmap.md：
+   - 文件不存在，或当前 phase 块内无 `- **Requirements**:` 行
+     → SKIP（输出一行 skip 原因，直接进入 Phase 3 交付）
+b) 提取当前 phase 的 REQ-IDs（`- **Requirements**: REQ-01, REQ-02` 行；`(none)` → SKIP）
+c) 读 .claude/plan/*.md 全部 frontmatter 的 `requirements` 字段（大小写不敏感取并集）
+d) 逐 REQ-ID 判定：
+   - covered        ：∈ 任一 plan frontmatter requirements
+   - mentioned-only ：未声明但某 plan 正文 word-boundary 命中（REQ-1 不误配 REQ-10）
+                      → 不算通过，修复建议 = 在该 plan frontmatter 补 requirements 声明
+   - uncovered      ：两者皆无
+e) 全部 covered → 输出 `✓ Requirements coverage: N/N`，进入 Phase 3 交付
+   否则 → 输出 gap 表（| REQ-ID | Status | Covered By |）+ **阻断 planning 完成**，AskUserQuestion 三选：
+   1. re-plan 补覆盖（推荐）——回 Phase 2.4 修订计划补 requirements + 对应任务
+   2. 移到下一 phase——同步修改 roadmap 当前 phase 的 Requirements 行（移走的 REQ 写入下一 phase）
+   3. force 接受 gap——计划文件追加 "## Coverage Override" 段记录被接受的 gap 与理由
+```
+
+**为什么阻断在这里便宜**：plans 是规划与执行之间的契约，此处发现 gap 的修复成本远低于实施后返工（GSD §13 同源设计）。
+
 ### ⛔ Phase 3 结束：计划交付（非执行）
 
 **`/ccg:plan` 的职责到此结束，必须执行以下动作**：

package/templates/commands/review.md

@@ -36,9 +36,9 @@ argument-hint: "[代码或描述] [--adversarial] [--fix [--all] [--auto]] [--ro
 - **无参数**：自动审查 `git diff HEAD`
 - **有参数**：审查指定代码或描述
 - **`--adversarial`**：双模型审查后追加 fresh-context 敌对审查（用 `Agent(subagent_type="codex:codex-rescue")` + `--adversarial-review`），主线 token 不被吃，3-5 分钟额外时间换更深的反向意见
-- **`--fix`**：审查后 spawn `code-fixer` 修复 Critical + Warning 级 finding，worktree 隔离 + 3 层 verification + 原子 commit
+- **`--fix`**：审查后 spawn `code-fixer` 修复 Critical + Warning 级 finding（worktree 隔离 + 3 层 verification + 原子 commit）。**自带 Ralph auto-retry**——修复后自动 re-review，仍有 Critical 自动进下一轮，**不每轮问用户**；无 Critical 即 pass through（残留 Warning/Info 列入最终报告）；上限 3 轮（CCG 硬规约），3 轮仍有 Critical 才 `AskUserQuestion` 升级
 - **`--fix --all`**：同上但纳入 Info 级 finding（默认不修 Info，避免噪音）
-- **`--fix --auto`**：fix → re-review → fix 多轮收敛环，**上限 3 轮**（CCG 硬规约）。3 轮未收敛升级用户介入
+- **`--fix --auto`**：同 `--fix` 的循环骨架，但收敛目标更严：critical+warning 全清才 converged，**上限 3 轮**（CCG 硬规约）。3 轮未收敛升级用户介入
 
 ---
 
@@ -71,15 +71,15 @@ Step 1. 用 Write 工具把【小任务描述】写到 tmpfile
    })
    Write({ 同上，gemini 版本 })
 
-Step 2. 用 Bash 调 helper（占位符已渲染）：
+Step 2. 用 Bash 调 helper（占位符已渲染；审查为只读，加 `--no-write`）：
    Bash({
-     command: `{{CODEX_BASH_TASK}} --prompt-file .context/tmp/ccg-review-codex-$JOB.txt`,
+     command: `{{CODEX_BASH_TASK}} --no-write --prompt-file .context/tmp/ccg-review-codex-$JOB.txt`,
      description: "Review: backend (codex direct)",
      run_in_background: true,
      timeout: 3600000
    })
    Bash({
-     command: `{{GEMINI_BASH_TASK}} --prompt-file .context/tmp/ccg-review-gemini-$JOB.txt`,
+     command: `{{GEMINI_BASH_TASK}} --no-write --prompt-file .context/tmp/ccg-review-gemini-$JOB.txt`,
      description: "Review: frontend (gemini direct)",
      run_in_background: true,
      timeout: 3600000
@@ -124,7 +124,7 @@ Step 3. 等 task-notification 通知后 Read 各自 stdout（helper 输出 JSON
 - 不要塞文件源代码（同上）
 - 不要写 `node "$(ls ...)/codex-companion.mjs"`、不要 heredoc、不要 `-p "..."` 内联
 - 不要硬编码 plugin 路径——helper 内部解析 SSoT
-- **唯一允许**：copy 占位符内容 + 追加 `--prompt-file <tmpfile>`，tmpfile 只放任务描述
+- **唯一允许**：copy 占位符内容 + 追加 `--prompt-file <tmpfile>`（只读审查流另加 `--no-write`），tmpfile 只放任务描述
 
 ⛔ **不要**用 `Agent(subagent_type="codex:codex-rescue"|"gemini:gemini-rescue")`：
 
@@ -136,7 +136,7 @@ CLI 空答 / auth 过期时 wrapper 受 instruction-tuning 驱动**自答 fabric
 详见 `src/utils/verify-orchestrator.ts:planVerifyWave` 的 `useDirectBashInvocation` 选项 +
 `src/utils/plugin-bash-codegen.ts`（1.0.4 install-time codegen）。
 
-主线接 stdout JSON（5-50KB），按 plugin --json schema 解析 `result.text` 字段，失败信号：
+主线接 stdout JSON（5-50KB），`JSON.parse(stdout)` 取 helper 扁平化后的顶层 `.text` 字段（= 模型真实输出；helper 已把 companion envelope 的 `rawOutput`/`text` 提到顶层 `.text`，`threadId`/`sessionId` → `.threadId`，`stats` → `.stats`），失败信号：
 - exit code ≠ 0 → loud fail，触发 v1.7.87 标准 2-retry / 5s / 3-attempts 规则
 - stdout 空 / 字节 < 100 → 同上视为失败
 
@@ -174,7 +174,7 @@ Bash({
 4. 主线在收到通知的新 turn 处理：
    - 从 notification `<task-id>` 定位是哪个任务
    - 从 `<output-file>` 路径 read stdout（plugin --json 输出 5-50KB）
-   - JSON parse `result.text` 字段（plugin 通道）/ `--progress` 行（codeagent-wrapper 通道）
+   - `JSON.parse(stdout).text`（plugin 通道，helper 扁平化后的真实输出）/ `--progress` 行（codeagent-wrapper 通道）
 5. **必须等所有相关 task 都收到通知**才进入下一阶段（主线按 task-id 计数已收齐）
 
 ⛔ **禁止做**：
@@ -229,9 +229,9 @@ Bash({
 Step 1. 用 Write 把任务描述写入 tmpfile（同样不塞 diff，让 codex 自己读）:
    Write({ file_path: ".context/tmp/ccg-review-adv-$JOB.txt", content: <下方任务描述> })
 
-Step 2. 调 helper:
+Step 2. 调 helper（只读审查，加 `--no-write`）:
    Bash({
-     command: `{{CODEX_BASH_TASK}} --prompt-file .context/tmp/ccg-review-adv-$JOB.txt`,
+     command: `{{CODEX_BASH_TASK}} --no-write --prompt-file .context/tmp/ccg-review-adv-$JOB.txt`,
      description: "Adversarial review (codex direct)",
      run_in_background: true,
      timeout: 3600000
@@ -274,7 +274,7 @@ Step 2. 调 helper:
 ⛔ 不用 `Agent(subagent_type="codex:codex-rescue")`：review/verify 路径输出直接落地，silent fallback
 风险（sonnet wrapper 受 instruction-tuning 自答冒充 adversarial 视角）不可接受。详见前文「通道 A」段。
 
-收到 stdout JSON 后解析 `result.text` 字段保留待阶段 3 综合。stdout 空或 exit≠0 → 走标准 2-retry 规则。
+收到 stdout 后 `JSON.parse(stdout).text`（helper 扁平化后的真实输出）保留待阶段 3 综合。stdout 空或 exit≠0 → 走标准 2-retry 规则。
 
 **降级**：若 `codex:codex-rescue` 不可用（用户没装 `codex@openai-codex` plugin），输出"⚠️ 跳过敌对审查，未检测到 codex plugin"并继续阶段 3，不阻塞流程。
 
@@ -369,7 +369,7 @@ base_sha: <当前 HEAD 的 sha>
 current_branch: <当前分支名>
 workdir: <项目绝对路径>
 fix_scope: critical_warning | all | auto
-auto_round: <仅 --auto 模式，当前轮次 1-indexed>
+auto_round: <多轮模式（--fix Ralph auto-retry 与 --fix --auto 都算）下传入，当前轮次 1-indexed>
 
 工程契约见 templates/commands/agents/code-fixer.md：
 - 强制 git worktree 隔离 + recovery sentinel
@@ -383,19 +383,25 @@ auto_round: <仅 --auto 模式，当前轮次 1-indexed>
 
 **code-fixer 完成后产出**：`REVIEW-FIX.md`（同目录），含 per-finding outcome + cleanup tail 状态。
 
-### 5.4 多轮收敛（仅 `--fix --auto`）
+### 5.4 多轮收敛（--fix 默认 Ralph auto-retry；--auto 严格收敛）
 
-`--auto` 模式下，**每完成一轮 review + fix 都把状态持久化到 `.context/fix-log.jsonl`**——这样 `/clear`、session 重启、context 压缩都不会丢历史。轮次推进算法：
+**所有 `--fix` 变体都走多轮收敛环**，**每完成一轮 review + fix 都把状态持久化到 `.context/fix-log.jsonl`**——这样 `/clear`、session 重启、context 压缩都不会丢历史。轮次推进算法：
 
 1. 每轮 review 完成 → 主线 Read REVIEW.md 抽 finding 数 → 调 `appendFixLogEntry(workdir, {kind:'review', ts:<ISO>, round:N, findings:{critical,warning,info}})` 持久化
 2. 每轮 fix 完成 → 同样 `appendFixLogEntry(workdir, {kind:'fix', ts, round:N, status, commits:[<sha7>...]})`
-3. 判定下一步：先 `loadConvergeHistory(workdir)` 从 disk 重建 ConvergeRound[]（**不**用 context 内史，因为可能已丢），再调 `decideConverge(history)`（参考 `src/utils/code-fixer-worktree.ts:decideConverge`）：
-   - `converged`（critical+warning=0）→ 完成，输出收敛报告
-   - `escalate`（达到 3 轮 cap 或 stall）→ `AskUserQuestion`："继续手动修 / 接受现状 / 回滚全部"
-   - `continue` → 重跑阶段 1-4 生成新 REVIEW.md，再 spawn code-fixer，`auto_round` +1
+   - **首轮 append 后**额外执行一次 artifacts 指针登记（advisory，幂等可重复）：`node ~/.claude/.ccg/scripts/task-store.cjs register-artifact --type fix-log --path .context/fix-log.jsonl`——把 fix-log 指针登记到活跃任务的 `artifacts[]`；无活跃任务时输出 `{ok:false,reason:"no-active-task"}` 且 exit 0，静默跳过即可，**绝不影响收敛环**
+3. 判定下一步：先 `loadConvergeHistory(workdir)` 从 disk 重建 ConvergeRound[]（**不**用 context 内史，因为可能已丢），再调 `decideConverge(history, 3, blocking)`（参考 `src/utils/code-fixer-worktree.ts:decideConverge` 第三参）：
+   - **blocking 取值**：`--fix` → `'critical'`（Ralph auto-retry，只有 Critical 阻塞）；`--fix --auto` → `'critical_warning'`（严格收敛，现行为不变）
+   - `converged` → **pass through**：输出收敛报告；普通 `--fix` 模式把残留 Warning/Info 原样列给用户（已修则标注），不再修
+   - `escalate`（达到 3 轮 cap 或 stall）→ `AskUserQuestion`："继续手动修 / 接受现状 / 回滚全部"——**这是整个 --fix 流程唯一允许的轮间 AskUserQuestion**（5.1 sentinel 恢复问询、code-fixer STATUS=partial 问询不受影响，属异常路径）
+   - `continue` → 自动重跑阶段 1-4 生成新 REVIEW.md，再 spawn code-fixer，`auto_round` +1，**禁止在 continue 路径上 AskUserQuestion 或等待用户确认**
+
+**C5 增量复用（第 2/3 轮 re-review）**：continue 路径重跑阶段 2 审查时，给两个 helper 调用加 `--resume-last`，tmpfile **只写增量**——"上一轮你已审过 + code-fixer 已修以下 finding：<上轮 critical id 列表>，现在只复查这些修复是否到位 + 是否引入新 critical，不要重审全量 diff"。helper 透传到 codex `exec resume --last`（gemini 需 gemini-ccgx plugin ≥1.3.0——helper 有版本闸门，过旧会显式报错），省 token 且避免每轮全量重发 diff 撞 argv 上限。首轮（round 1）不加 `--resume-last`（无可接续会话）。
 
 **3 轮上限是 CCG 硬规约**（与 plan-checker / verify-work 一致），**禁止**绕过。
 
+> stop-gate hook 会在主线提前 turn end 时从 `fix-log.jsonl` 读到未清 Critical 并注入软反馈提醒续跑——但正确行为是主线自己跑完循环，不依赖 hook 兜底。
+
 **为什么走 disk 不走 context**：fork 早期版本把 ConvergeRound[] 留在主线 context；用户在 round 2 `/clear` 后继续 `--auto` → 主线见空 history → 当成 round 1 重启 → 永远到不了 escalate cap。fix-log.jsonl 在 disk 上 append-only，跨会话稳如磐石。`.context/fix-log.jsonl` 已加入 `.gitignore`（项目本地审计，不入 repo）。
 
 ### 5.5 闭环修复总结
@@ -405,6 +411,7 @@ auto_round: <仅 --auto 模式，当前轮次 1-indexed>
 
 - 修复模式：`--fix` / `--fix --all` / `--fix --auto`
 - 修复轮次：<N> / 3
+- 收敛模式：critical-only（`--fix`）/ critical+warning（`--auto`）
 - Findings 处理：<M>（Critical: <a> / Warning: <b> / Info: <c>）
 - Atomic commits: <K>
 - Worktree cleanup: ok / partial（merge 失败保留 worktree 待人工）
@@ -419,4 +426,4 @@ auto_round: <仅 --auto 模式，当前轮次 1-indexed>
 - cleanup tail 4 步**必须**严格按 `merge_ff_only → worktree_remove → branch_delete → sentinel_remove` 顺序
 - 任何步骤失败**必须**立即停（不继续后续步骤）
 - per-finding rollback **必须**用 `git checkout --`，**禁止**用 Write 工具
-- `--auto` 收敛轮次**必须** ≤ 3
+- 多轮收敛轮次**必须** ≤ 3，continue 路径**禁止**问用户

package/templates/commands/spec-impl.md

@@ -47,40 +47,34 @@ description: '按规范执行 + 多模型协作 + 归档'
 
    **调用通道路由（CCG codeagent 退役，v2.2.0+）**
 
-   1. **优先 plugin spawn**（默认）：plugin 已装 → `Agent(subagent_type="<codex:codex-rescue|gemini:gemini-rescue>")`，主线接 ≤200 token 摘要。
+   1. **优先 Bash 直调 plugin 快路径**（默认）：plugin 已装 → `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` 占位符 + `--prompt-file` Bash 直调（按 task layer 选 vendor），绕开 sonnet wrapper silent-fallback；**仅 `gemini-ccgx` fork 走 gemini-batch 29s 快路径，上游 + repatch 仍走 companion(ACP) 慢路径**（Windows 实测 5+min 卡死风险仍在），主线 `JSON.parse(stdout).text` 取 diff、`.threadId` 供 Step 7 `--resume-last` 复用。
    2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → Bash 调用，保留 SESSION_ID 供 Step 7 review 复用。
 
-   **预备动作**：主线先 Read 角色提示词（这里用 `architect.md` 或对应实施角色），把内容拼入 `<role>` 块。
+   **通道 A — Bash 直调 plugin 快路径（默认，每 task 独立）**：
 
-   **通道 A — plugin spawn（默认，每 task 独立 fresh-context）**：
+   > 占位符 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` 由 install 渲染为 `node <ccgx-call-plugin.mjs 绝对路径> <vendor> --json`。LLM 只需 Write tmpfile + 追加 `--prompt-file <tmpfile>` 运行，**不写 `Agent(...)`、不内联 role 全文**。
 
    ```
-   Agent({
-     subagent_type: "<codex:codex-rescue|gemini:gemini-rescue>",
-     description: "spec-impl: <task name>",
-     prompt: `<role>
-${implementerRole}
-</role>
-
-<workdir>{{WORKDIR}}</workdir>
-
-<task>
-TASK: <task description from tasks.md>
-CONTEXT: <relevant code context>
-CONSTRAINTS: <constraints from spec>
-</task>
-
-<action_safety>
-- Stay strictly within tasks.md scope
-- Do NOT introduce dependencies not in the plan
-- Prefer minimal targeted changes
-</action_safety>
-
-<structured_output_contract>
-Return Unified Diff Patch format ONLY (no preamble, no commentary).
-The diff will be reviewed before apply; do not assume it's been applied.
-</structured_output_contract>`
-   })
+   Step A1. Write 任务到 tmpfile（≤2KB，让模型自己 Read 角色 + 上下文文件）：
+   Write({ file_path: ".context/tmp/ccg-specimpl-<task>-$JOB.txt", content: <下方实施任务模板> })
+
+   Step A2. Bash 直调 helper（按 task layer 选占位符）：
+   Bash({ command: `{{BACKEND_PRIMARY 用 CODEX_BASH_TASK / FRONTEND_PRIMARY 用 GEMINI_BASH_TASK}} --prompt-file .context/tmp/ccg-specimpl-<task>-$JOB.txt`, description: "spec-impl: <task name> (direct)", run_in_background: true })
+   ```
+
+   实施任务模板（写入 tmpfile）：
+   ```
+   # 任务：实现 <task>（生成 Unified Diff，不落盘）
+
+   工作目录：{{WORKDIR}}（你已在此）
+   角色定义见 ~/.claude/.ccg/prompts/<backend 用 {{BACKEND_PRIMARY}}/architect.md，frontend 用 {{FRONTEND_PRIMARY}}/frontend.md（该文件不存在时退 {{FRONTEND_PRIMARY}}/architect.md）>，**先用 Read 工具读取再开始**。
+   **必须前台执行，禁止 --background / --wait**（外层已 run_in_background，插件内再 background = 双重后台，stop-gate/status/cancel 全盲）。
+
+   TASK: <task description from tasks.md>
+   CONTEXT: <相关代码文件路径，自己 Read，不内联大段源码>
+   CONSTRAINTS: <constraints from spec>
+   严格限定在 tasks.md scope 内；不引入计划外依赖；最小化改动。
+   OUTPUT: Unified Diff Patch ONLY（diff 会被审查后再 apply，不要假设已 apply）。
    ```
 
    **通道 B — codeagent-wrapper fallback**（plugin 未装时；保留 SESSION_ID 供 Step 7 复用）：
@@ -95,7 +89,7 @@ The diff will be reviewed before apply; do not assume it's been applied.
    ```
 
    **会话模型差异**：
-   - **通道 A（plugin）**：每个 task 独立 fresh-context spawn，**无显式 SESSION_ID**。Step 7 review 时由主线把 Step 4-6 的变更摘要（diff + spec 引用）显式拼入 reviewer prompt。
+   - **通道 A（Bash 直调快路径）**：每个 task 独立调用，从 `JSON.parse(stdout).threadId` 取会话标识。Step 7 review 可用 `--resume-last` 接续该 task 会话（C5 增量，只发"审查上面的实现"），或主线把变更摘要显式拼入 reviewer tmpfile。
    - **通道 B（wrapper BC）**：保存返回的 `SESSION_ID:`（{{BACKEND_PRIMARY}} → `CODEX_PROTO_SESSION`，{{FRONTEND_PRIMARY}} → `GEMINI_PROTO_SESSION`），Step 7 审查 `resume <SESSION_ID>` 复用上下文。
 
 5. **Rewrite Prototype to Production Code**
@@ -119,117 +113,55 @@ The diff will be reviewed before apply; do not assume it's been applied.
 
    **调用通道路由（CCG codeagent 退役，v2.2.0+）**
 
-   双模型并行通道从 `Bash(codeagent-wrapper)` **默认切换**为 plugin spawn：
+   双模型并行通道从 `Bash(codeagent-wrapper)` **默认切换**为 Bash 直调 plugin 快路径：
 
-   1. **优先 plugin spawn**（默认）：装了 `codex@openai-codex` + gemini plugin（推荐 `gemini@gemini-ccgx` fork；或上游 `gemini@google-gemini` 配 repatch 脚本）→ 用 `Agent(subagent_type="codex:codex-rescue")` + `Agent(subagent_type="gemini:gemini-rescue")` 并行，主线接 ≤200 token 摘要。
+   1. **优先 Bash 直调 plugin 快路径**（默认）：装了 `codex@openai-codex` + gemini plugin（推荐 `gemini@gemini-ccgx` fork；或上游 `gemini@google-gemini` 配 repatch 脚本）→ 用 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` 占位符 + `--prompt-file` 并行 Bash 直调，绕开 sonnet wrapper silent-fallback；**仅 `gemini-ccgx` fork 走 gemini-batch 29s 快路径，上游 + repatch 仍走 companion(ACP) 慢路径**（Windows 实测 5+min 卡死风险仍在），主线 `JSON.parse(stdout).text`。**C5 增量**：仅对本任务在 Step 4 实际实施过的 vendor 加 `--resume-last` 接续其实施会话，只发"审查上面的实现"，省 token；另一侧 vendor 走无状态审查（不加 `--resume-last`）。
    2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → fallback Bash 调用，**保留 Step 4 session resume** 以维持会话上下文。
 
-   **判定**：preflight `Bash` 跑 `node ~/.claude/.ccg/scripts/check-plugins.cjs`（解析 Claude Code 权威 `installed_plugins.json`）。exit `0` + stdout `{"codex":"<ver>","gemini":"<ver>"}` → 通道 A（plugin 默认）；非 `0` → 通道 B（wrapper BC fallback）。
+   **判定**：preflight `Bash` 跑 `node ~/.claude/.ccg/scripts/check-plugins.cjs`（解析 Claude Code 权威 `installed_plugins.json`）。exit `0` + stdout `{"codex":"<ver>","gemini":"<ver>"}` → 通道 A（Bash 直调快路径，默认）；非 `0` → 通道 B（wrapper BC fallback）。
 
-   ⚠️ spec-impl 命令在主线 context 内，**允许** `Agent(...)`——与 subagent "禁止嵌套 spawn" 约束不冲突。
-   ⚠️ **plugin 路径无 session resume 能力**：通道 A 不接 Step 4 的 SESSION_ID，review 任务作为独立无状态分析跑（review 是 read-only 审查，无需会话连续性）。
+   ⚠️ spec-impl 命令在主线 context 内执行，通道 A 走 Bash 直调（不再 spawn `Agent(...)`），无嵌套 spawn 顾虑。
 
    - **CRITICAL**: You MUST launch BOTH {{BACKEND_PRIMARY}} AND {{FRONTEND_PRIMARY}} in a SINGLE message with TWO parallel tool calls.
    - **DO NOT** call one model first and wait. Launch BOTH simultaneously.
 
-   **Step 7.1**: In ONE message, spawn TWO models in parallel.
-
-   **⚠ 预备动作（spawn 前必须执行）**：`codex:codex-rescue` / `gemini:gemini-rescue` 是 thin forwarder，不会主动 Read 路径文件。主线必须在 spawn 前先 Read 两个角色提示词文件，把**内容**直接拼入下方 Agent prompt 的 `<role>` 块。
+   **Step 7.1**: In ONE message, spawn TWO Bash-direct helper calls in parallel.
 
-   - backend role: `Read("~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/reviewer.md")` → `${backendRole}`
-   - frontend role: `Read("~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/reviewer.md")` → `${frontendRole}`
+   **通道 A — Bash 直调 plugin 快路径（默认）**：
 
-   Prompt 结构按 `gpt-5-4-prompting` skill 推荐：`<role>` + `<task>` + `<grounding_rules>` + `<dig_deeper_nudge>` + `<structured_output_contract>`。
+   > 占位符 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` 由 install 渲染为 `node <ccgx-call-plugin.mjs 绝对路径> <vendor> --json`。LLM 只需 Write tmpfile + 追加 `--prompt-file <tmpfile>`（只读审查加 `--no-write`；增量审查仅对有实施会话的 vendor 加 `--resume-last`）运行，**不写 `Agent(...)`、不内联 role 全文**。
 
-   **通道 A — plugin spawn（默认，无 session）**：
+   **Step 7.1a — Write 两个 tmpfile**（≤2KB，让模型自己 Read 角色 + `git diff` 读变更）：
+   ```
+   Write({ file_path: ".context/tmp/ccg-specimpl-review-codex-$JOB.txt", content: <backend review 模板> })
+   Write({ file_path: ".context/tmp/ccg-specimpl-review-gemini-$JOB.txt", content: <frontend review 模板> })
+   ```
 
-   **FIRST Agent call ({{BACKEND_PRIMARY}})**:
+   backend review 模板：
    ```
-   Agent({
-     subagent_type: "codex:codex-rescue",
-     description: "spec-impl: correctness/security review",
-     prompt: `<role>
-${backendRole}
-</role>
-
-<workdir>{{WORKDIR}}</workdir>
-
-<task>
-Review the implementation changes along backend dimensions:
-- Correctness: logic errors, edge cases
-- Security: injection, auth issues
-- Spec compliance: constraints satisfied
-
-变更摘要：<列出 Step 5/6 涉及的文件 + 关键 diff>
-
-Read-only review. Do NOT modify any file.
-</task>
-
-<grounding_rules>
-- Every finding must cite file:line in the listed diff
-- If a constraint was satisfied, list it in passed_checks
-- "I couldn't verify X" is acceptable; fabricating X is not
-</grounding_rules>
-
-<dig_deeper_nudge>
-- For each Critical finding, check whether the same root cause appears elsewhere in the diff
-- Prefer one well-cited Critical over five vague Warnings
-</dig_deeper_nudge>
-
-<structured_output_contract>
-Return JSON ONLY (no preamble):
-{
-  "findings": [{"severity": "Critical|Warning|Info", "dimension": "logic|security|spec_compliance", "file": "path", "line": N, "description": "...", "fix_suggestion": "..."}],
-  "passed_checks": ["..."],
-  "summary": "Overall assessment"
-}
-Return ≤200 token structured summary.
-</structured_output_contract>`
-   })
+   # 任务：spec-impl 实现审查（后端维度，接续实施会话）
+
+   工作目录：{{WORKDIR}}（你已在此）
+   角色定义见 ~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/reviewer.md，**先用 Read 工具读取再开始**。
+   **必须前台执行，禁止 --background / --wait**（外层已 run_in_background，插件内再 background = 双重后台，stop-gate/status/cancel 全盲）。只读审查，不改任何文件。
+
+   自己跑 `git diff` 看 Step 5/6 落盘的实现变更。沿后端维度审：correctness（逻辑/边界）、security（注入/鉴权）、spec compliance。
+   每个 finding 引 file:line；满足约束列 passed_checks；无法验证如实说，禁止编造。
+   Return JSON ONLY:
+   { "findings": [{"severity":"Critical|Warning|Info","dimension":"logic|security|spec_compliance","file":"path","line":N,"description":"...","fix_suggestion":"..."}],
+     "passed_checks": ["..."], "summary": "..." }
    ```
 
-   **SECOND Agent call ({{FRONTEND_PRIMARY}}) - IN THE SAME MESSAGE**:
+   frontend review 模板（角色换 {{FRONTEND_PRIMARY}}/reviewer.md，同硬约束；维度=maintainability/patterns/integration，dimension 枚举 maintainability|patterns|integration）。
+
+   **Step 7.1b — 并行 Bash 直调**（同一 message，`run_in_background: true`）：
+
+   **`--resume-last` 守卫**：仅对本任务在 Step 4 实际有过实施会话的 vendor 追加 `--resume-last`；另一侧 vendor 本任务内无可接续会话，走无状态审查——**不加** `--resume-last`（tmpfile 已指示模型自跑 `git diff` 读变更）。审查为只读，两侧一律加 `--no-write`。
+
    ```
-   Agent({
-     subagent_type: "gemini:gemini-rescue",
-     description: "spec-impl: maintainability/patterns review",
-     prompt: `<role>
-${frontendRole}
-</role>
-
-<workdir>{{WORKDIR}}</workdir>
-
-<task>
-Review the implementation changes along maintainability/integration dimensions:
-- Maintainability: readability, complexity
-- Patterns: consistency with project style
-- Integration: cross-module impacts
-
-变更摘要：<列出 Step 5/6 涉及的文件 + 关键 diff>
-
-Read-only review. Do NOT modify any file.
-</task>
-
-<grounding_rules>
-- Every finding must cite file:line in the listed diff
-- If an aspect was clean, list it in passed_checks
-</grounding_rules>
-
-<dig_deeper_nudge>
-- Check if the same pattern issue appears in adjacent files
-- Prefer one well-cited Critical over five vague Warnings
-</dig_deeper_nudge>
-
-<structured_output_contract>
-Return JSON ONLY (no preamble):
-{
-  "findings": [{"severity": "Critical|Warning|Info", "dimension": "maintainability|patterns|integration", "file": "path", "line": N, "description": "...", "fix_suggestion": "..."}],
-  "passed_checks": ["..."],
-  "summary": "Overall assessment"
-}
-Return ≤200 token structured summary.
-</structured_output_contract>`
-   })
+   # 示例：Step 4 由 codex 实施（backend task）→ codex 加 --resume-last，gemini 无实施会话不加
+   Bash({ command: `{{CODEX_BASH_TASK}} --resume-last --no-write --prompt-file .context/tmp/ccg-specimpl-review-codex-$JOB.txt`, description: "spec-impl review: backend (codex direct)", run_in_background: true })
+   Bash({ command: `{{GEMINI_BASH_TASK}} --no-write --prompt-file .context/tmp/ccg-specimpl-review-gemini-$JOB.txt`, description: "spec-impl review: frontend (gemini direct)", run_in_background: true })
    ```
 
    **通道 B — codeagent-wrapper fallback**（plugin 未装时降级，**保留 session resume**）：
@@ -252,8 +184,8 @@ Return ≤200 token structured summary.
    > ⚠️ 通道 B `codeagent-wrapper` 已标 **deprecated**，仅为不能升级 plugin 的环境保留——但本 step 仍是 wrapper 唯一能利用 Step 4 SESSION_ID 的场景。
 
    **Step 7.2 (事件驱动)**：
-   - **通道 A（plugin）**：两个 Agent 同 message 内 spawn，主线接 ≤200 token 摘要。Agent 完成后自动返回结果。
-   - **通道 B（BC wrapper）**：spawn 两个 Bash bg 后说明 task-id 然后 **turn end**。引擎在每个 task 完成时自动发 `<task-notification>`，主线在通知触发的新 turn 处理结果。**不调 TaskOutput**。两个 task 都收到通知后才进 step 7.3。
+   - **通道 A（Bash 直调快路径）**：spawn 两个 Bash bg 后说明 task-id 然后 **turn end**。引擎在每个 task 完成时自动发 `<task-notification>`，主线在新 turn Read stdout 后 `JSON.parse(stdout).text` 取真实输出。两个 task 都收到通知后才进 step 7.3。
+   - **通道 B（BC wrapper）**：同上 bg + 事件驱动，但 parse `--progress` 行而非 `.text`。**不调 TaskOutput**。两个 task 都收到通知后才进 step 7.3。
 
    ⛔ **禁止**：调 `TaskOutput({block: true, timeout: 600000})` (旧 freeze poll 模式) / Kill task。
    ⚠️ **失败处理**：notification status=failed / exit ≠ 0 / parse 失败 → v1.7.87 标准 2-retry / 5s / 3-attempts；3 次全失败才降级单模型。
@@ -329,6 +261,15 @@ Return ≤200 token structured summary.
        学到的事"的审计文档，随 change 一起归档；提升为 `specs/<capability>/spec.md`
        里的真正 SHALL 是下一轮 `/ccg:spec-research` 的工作。
 
+       写完 SPEC_EVOLUTION.md 后，执行 artifacts 指针登记（advisory，不阻塞归档）：
+       ```bash
+       node ~/.claude/.ccg/scripts/task-store.cjs register-artifact \
+         --type spec-evolution \
+         --path openspec/changes/<change-id>/SPEC_EVOLUTION.md
+       ```
+       把指针登记到活跃任务的 `artifacts[]`（只登记指针，不移动文件）。无活跃任务时
+       输出 `{ok:false,reason:"no-active-task"}` 且 exit 0——静默跳过，继续 Step 10e/11。
+
     e. **空跳**：通过质量门的 candidate 数 === 0 时**不创建** SPEC_EVOLUTION.md
        （避免空文件污染归档）。在主对话输出一句话："本次 Spec Evolution 无可复用约定。"