ccgx-workflow 2.4.1 → 2.5.0

package/dist/shared/{ccgx-workflow.j1spUsik.mjs → ccgx-workflow.CdHnJLak.mjs}

@@ -13,7 +13,7 @@ import { join as join$2 } from 'node:path/posix';
 import { join as join$1 } from 'node:path';
 import i18next from 'i18next';
 
-const version = "2.4.1";
+const version = "2.5.0";
 
 function cmd(id, order, category, name, nameEn, description, descriptionEn, cmdOverride) {
   return {
@@ -90,13 +90,16 @@ const HOOK_FILES = [
   "ccg-session-state.cjs",
   "ccg-loop-detector.cjs",
   "ccg-skill-router.cjs",
-  "ccg-stop-gate.cjs"
+  "ccg-stop-gate.cjs",
+  "ccg-subagent-context.cjs"
 ];
 const POST_TOOL_MATCHER = "Bash|Edit|Write|MultiEdit|Agent|Task";
 const POST_TOOL_TIMEOUT_SEC = 10;
 const SESSION_START_TIMEOUT_SEC = 15;
 const USER_PROMPT_TIMEOUT_SEC = 5;
 const STOP_TIMEOUT_SEC = 5;
+const PRE_TOOL_MATCHER = "Task|Agent";
+const PRE_TOOL_TIMEOUT_SEC = 10;
 const CCG_SKILL_OVERRIDES = {
   "codex:rescue": "user-invocable-only",
   "gemini:rescue": "user-invocable-only"
@@ -141,6 +144,7 @@ async function patchSettingsJson(ctx) {
   const loopDetectorPath = join(hooksDir, "ccg-loop-detector.cjs");
   const skillRouterPath = join(hooksDir, "ccg-skill-router.cjs");
   const stopGatePath = join(hooksDir, "ccg-stop-gate.cjs");
+  const subagentContextPath = join(hooksDir, "ccg-subagent-context.cjs");
   let settings = {};
   if (await fs.pathExists(settingsPath)) {
     try {
@@ -256,6 +260,26 @@ async function patchSettingsJson(ctx) {
       }
     }
   }
+  if (await fs.pathExists(subagentContextPath)) {
+    if (!settings.hooks) settings.hooks = {};
+    if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
+    const alreadyRegistered = settings.hooks.PreToolUse.some(
+      (entry) => entry?.hooks?.some((h) => typeof h?.command === "string" && h.command.includes("ccg-subagent-context"))
+    );
+    if (!alreadyRegistered) {
+      settings.hooks.PreToolUse.push({
+        matcher: PRE_TOOL_MATCHER,
+        hooks: [
+          {
+            type: "command",
+            command: buildHookCommand(subagentContextPath),
+            timeout: PRE_TOOL_TIMEOUT_SEC
+          }
+        ]
+      });
+      modified = true;
+    }
+  }
   if (typeof settings.skillOverrides !== "object" || settings.skillOverrides === null) {
     settings.skillOverrides = {};
   }
@@ -333,6 +357,24 @@ async function uninstallHooks(installDir) {
         modified = true;
       }
     }
+    if (Array.isArray(settings.hooks?.PreToolUse)) {
+      const before = settings.hooks.PreToolUse.length;
+      settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((entry) => {
+        const hasCcg = entry?.hooks?.some(
+          (h) => typeof h?.command === "string" && h.command.includes("ccg-subagent-context")
+        );
+        return !hasCcg;
+      });
+      if (settings.hooks.PreToolUse.length !== before) modified = true;
+      if (settings.hooks.PreToolUse.length === 0) {
+        delete settings.hooks.PreToolUse;
+        modified = true;
+      }
+      if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+        modified = true;
+      }
+    }
     if (Array.isArray(settings.hooks?.UserPromptSubmit)) {
       const before = settings.hooks.UserPromptSubmit.length;
       settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter((entry) => {
@@ -519,7 +561,7 @@ function findPackageRoot$1(startDir) {
   Start dir: ${startDir}
   Last checked: ${dir}
   This will cause commands/skills/prompts to not be installed.
-  Please report this issue at: https://github.com/fengshao1227/ccg-workflow/issues`
+  Please report this issue at: https://github.com/wzyxdwll/ccgx-workflow/issues`
   );
   return startDir;
 }
@@ -666,6 +708,8 @@ function normalizeSkillRecord(skillsDir, skillDir, meta) {
   const contextRaw = String(meta.context || "inline").toLowerCase();
   const context = contextRaw === "fork" ? "fork" : "inline";
   const paths = meta.paths ? meta.paths.split(",").map((p) => p.trim()).filter(Boolean) : [];
+  const gateTypeRaw = String(meta["gate-type"] || "").toLowerCase();
+  const gateType = ["pre-flight", "revision-loop", "escalation", "abort"].find((g) => g === gateTypeRaw);
   return {
     name,
     description,
@@ -679,7 +723,8 @@ function normalizeSkillRecord(skillsDir, skillDir, meta) {
     skillPath: join(skillDir, "SKILL.md"),
     scriptPath: scriptEntries[0] || null,
     context,
-    paths
+    paths,
+    gateType
   };
 }
 function collectSkills(skillsDir) {
@@ -1485,7 +1530,7 @@ async function installShim(ctx) {
     const srcMjs = join(ctx.templateDir, "scripts", "invoke-model.mjs");
     if (!await fs.pathExists(srcMjs)) {
       ctx.result.errors.push(
-        `Bundled invoke-model.mjs missing at ${srcMjs}. npm package may be incomplete \u2014 try: npm cache clean --force && npx ccg-workflow@latest`
+        `Bundled invoke-model.mjs missing at ${srcMjs}. npm package may be incomplete \u2014 try: npm cache clean --force && npx ccgx-workflow@latest`
       );
       ctx.result.success = false;
       return;
@@ -1527,6 +1572,38 @@ async function installShim(ctx) {
         await fs.chmod(destSpecSuggestion, 493);
       }
     }
+    const srcTaskStore = join(ctx.templateDir, "scripts", "task-store.cjs");
+    if (await fs.pathExists(srcTaskStore)) {
+      const destTaskStore = join(scriptDir, "task-store.cjs");
+      await fs.copy(srcTaskStore, destTaskStore, { overwrite: true });
+      if (process.platform !== "win32") {
+        await fs.chmod(destTaskStore, 493);
+      }
+    }
+    const srcTeamSchedule = join(ctx.templateDir, "scripts", "ccg-team-schedule.cjs");
+    if (await fs.pathExists(srcTeamSchedule)) {
+      const destTeamSchedule = join(scriptDir, "ccg-team-schedule.cjs");
+      await fs.copy(srcTeamSchedule, destTeamSchedule, { overwrite: true });
+      if (process.platform !== "win32") {
+        await fs.chmod(destTeamSchedule, 493);
+      }
+    }
+    const srcStateLock = join(ctx.templateDir, "scripts", "ccg-state-lock.cjs");
+    if (await fs.pathExists(srcStateLock)) {
+      const destStateLock = join(scriptDir, "ccg-state-lock.cjs");
+      await fs.copy(srcStateLock, destStateLock, { overwrite: true });
+      if (process.platform !== "win32") {
+        await fs.chmod(destStateLock, 493);
+      }
+    }
+    const srcRepatch = join(ctx.templateDir, "scripts", "repatch-gemini-plugin.mjs");
+    if (await fs.pathExists(srcRepatch)) {
+      const destRepatch = join(scriptDir, "repatch-gemini-plugin.mjs");
+      await fs.copy(srcRepatch, destRepatch, { overwrite: true });
+      if (process.platform !== "win32") {
+        await fs.chmod(destRepatch, 493);
+      }
+    }
     if (process.platform === "win32") {
       const cmdMjs = destMjs.replace(/\//g, "\\");
       const cmdPath = join(binDir, "codeagent-wrapper.cmd");
@@ -1585,7 +1662,7 @@ async function installWorkflows(workflowIds, installDir, force = false, config)
     }
   };
   if (!await fs.pathExists(ctx.templateDir)) {
-    const errorMsg = `Template directory not found: ${ctx.templateDir} (PACKAGE_ROOT=${PACKAGE_ROOT$1}). This usually means the npm package is incomplete or the cache is corrupted. Try: npm cache clean --force && npx ccg-workflow@latest`;
+    const errorMsg = `Template directory not found: ${ctx.templateDir} (PACKAGE_ROOT=${PACKAGE_ROOT$1}). This usually means the npm package is incomplete or the cache is corrupted. Try: npm cache clean --force && npx ccgx-workflow@latest`;
     ctx.result.errors.push(errorMsg);
     ctx.result.success = false;
     return ctx.result;
@@ -4144,7 +4221,7 @@ async function init(options = {}) {
       if (!result.success) {
         console.log();
         console.log(ansis.yellow(`  \u5C1D\u8BD5\u4FEE\u590D / Try to fix:`));
-        console.log(ansis.cyan(`    npx ccg-workflow@latest init --force`));
+        console.log(ansis.cyan(`    npx ccgx-workflow@latest init --force`));
         console.log(ansis.gray(`    \u5982\u4ECD\u5931\u8D25\uFF0C\u8BF7\u63D0\u4EA4 issue \u5E76\u9644\u4E0A\u4EE5\u4E0A\u9519\u8BEF\u4FE1\u606F`));
         console.log(ansis.gray(`    If still failing, report an issue with the errors above`));
       }
@@ -4351,6 +4428,7 @@ function findPackageRoot(startDir) {
   }
 }
 const PACKAGE_ROOT = findPackageRoot(__dirname$1);
+const PACKAGE_NAME = "ccgx-workflow";
 async function readPackageVersion(pkgPath) {
   try {
     if (!await fs.pathExists(pkgPath)) {
@@ -4388,7 +4466,7 @@ async function getCurrentVersion() {
   }
   return process.env.npm_package_version || "0.0.0";
 }
-async function getLatestVersion(packageName = "ccg-workflow") {
+async function getLatestVersion(packageName = PACKAGE_NAME) {
   try {
     const { stdout } = await execAsync$2(`npm view ${packageName} version`);
     return stdout.trim();
@@ -4481,8 +4559,8 @@ async function update() {
 }
 async function checkIfGlobalInstall$1() {
   try {
-    const { stdout } = await execAsync$1("npm list -g ccg-workflow --depth=0", { timeout: 5e3 });
-    return stdout.includes("ccg-workflow@");
+    const { stdout } = await execAsync$1(`npm list -g ${PACKAGE_NAME} --depth=0`, { timeout: 5e3 });
+    return stdout.includes(`${PACKAGE_NAME}@`);
   } catch {
     return false;
   }
@@ -4503,7 +4581,7 @@ async function performUpdate(fromVersion, toVersion, isNewVersion) {
     console.log();
     console.log(`${i18n.t("update:recommendNpm")}`);
     console.log();
-    console.log(ansis.cyan("  npm install -g ccg-workflow@latest"));
+    console.log(ansis.cyan(`  npm install -g ${PACKAGE_NAME}@latest`));
     console.log();
     console.log(ansis.gray(i18n.t("update:willUpdateBoth")));
     console.log();
@@ -4517,7 +4595,7 @@ async function performUpdate(fromVersion, toVersion, isNewVersion) {
       console.log();
       console.log(ansis.cyan(i18n.t("update:runInNewTerminal")));
       console.log();
-      console.log(ansis.cyan.bold("  npm install -g ccg-workflow@latest"));
+      console.log(ansis.cyan.bold(`  npm install -g ${PACKAGE_NAME}@latest`));
       console.log();
       console.log(ansis.gray(`(${i18n.t("update:autoUpdateAfter")})`));
       console.log();
@@ -4543,7 +4621,7 @@ async function performUpdate(fromVersion, toVersion, isNewVersion) {
       }
     }
     spinner.text = i18n.t("update:downloading");
-    await execAsync$1(`npx --yes ccg-workflow@latest --version`, { timeout: 6e4 });
+    await execAsync$1(`npx --yes ${PACKAGE_NAME}@latest --version`, { timeout: 6e4 });
     spinner.succeed(i18n.t("update:downloadDone"));
   } catch (error) {
     spinner.fail(i18n.t("update:downloadFailed"));
@@ -4614,9 +4692,9 @@ async function performUpdate(fromVersion, toVersion, isNewVersion) {
   spinner = ora(i18n.t("update:installingNew")).start();
   let installSuccess = false;
   try {
-    await execAsync$1(`npx --yes ccg-workflow@latest init --force --skip-mcp --skip-prompt`, {
+    await execAsync$1(`npx --yes ${PACKAGE_NAME}@latest init --force --skip-mcp --skip-prompt`, {
       timeout: 3e5,
-      // 5min — binary download from GitHub Release may be slow (especially in China)
+      // 5min — npx downloading the npm package may be slow (especially in China)
       env: {
         ...process.env,
         CCG_UPDATE_MODE: "true"
@@ -4624,7 +4702,9 @@ async function performUpdate(fromVersion, toVersion, isNewVersion) {
     });
     const commandsDir = join(installDir, "commands", "ccg");
     const hasCommands = await fs.pathExists(commandsDir) && (await fs.readdir(commandsDir)).some((f) => f.endsWith(".md"));
-    if (hasCommands) {
+    const fingerprintPath = join(installDir, ".ccg", "scripts", "invoke-model.mjs");
+    const hasFingerprint = await fs.pathExists(fingerprintPath);
+    if (hasCommands && hasFingerprint) {
       installSuccess = true;
       spinner.succeed(i18n.t("update:installDone"));
       const config = await readCcgConfig();
@@ -4637,7 +4717,11 @@ async function performUpdate(fromVersion, toVersion, isNewVersion) {
       }
     } else {
       spinner.fail(i18n.t("update:installFailed"));
-      console.log(ansis.red("  Install subprocess completed but no command files were created"));
+      if (!hasCommands) {
+        console.log(ansis.red("  Install subprocess completed but no command files were created"));
+      } else {
+        console.log(ansis.red(`  Install fingerprint missing: ${fingerprintPath}`));
+      }
     }
   } catch (error) {
     spinner.fail(i18n.t("update:installFailed"));
@@ -4674,7 +4758,7 @@ async function performUpdate(fromVersion, toVersion, isNewVersion) {
     }
     console.log();
     console.log(ansis.yellow(i18n.t("update:manualRetry")));
-    console.log(ansis.cyan("  npx ccg-workflow@latest"));
+    console.log(ansis.cyan(`  npx ${PACKAGE_NAME}@latest`));
     return;
   }
   console.log();
@@ -5095,7 +5179,7 @@ async function configModelRouting() {
   const spinner = ora(i18n.t("init:model.reinstalling")).start();
   try {
     const { execSync } = await import('node:child_process');
-    execSync("npx --yes ccg-workflow init --force --skip-prompt --skip-mcp", {
+    execSync(`npx --yes ${PACKAGE_NAME} init --force --skip-prompt --skip-mcp`, {
       timeout: 3e5,
       stdio: "pipe",
       env: { ...process.env, CCG_UPDATE_MODE: "true" }
@@ -5236,8 +5320,8 @@ async function handleInstallClaude() {
 }
 async function checkIfGlobalInstall() {
   try {
-    const { stdout } = await execAsync("npm list -g ccg-workflow --depth=0", { timeout: 5e3 });
-    return stdout.includes("ccg-workflow@");
+    const { stdout } = await execAsync(`npm list -g ${PACKAGE_NAME} --depth=0`, { timeout: 5e3 });
+    return stdout.includes(`${PACKAGE_NAME}@`);
   } catch {
     return false;
   }
@@ -5299,7 +5383,7 @@ async function uninstall() {
       console.log();
       console.log(`  ${i18n.t("menu:uninstall.runInNewTerminal")}`);
       console.log();
-      console.log(ansis.cyan.bold("    npm uninstall -g ccg-workflow"));
+      console.log(ansis.cyan.bold(`    npm uninstall -g ${PACKAGE_NAME}`));
       console.log();
       console.log(ansis.gray(`  (${i18n.t("menu:uninstall.afterDone")})`));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccgx-workflow",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Multi-model orchestration for Claude Code. Codex + Gemini parallel collaboration with fresh-context subagent protocols, OS-level process isolation, and Plan-Critic-Verify quality tiers. Successor to ccg-workflow.",
   "type": "module",
   "packageManager": "pnpm@10.17.1",

package/templates/commands/agents/code-fixer.md

@@ -34,7 +34,7 @@ color: orange
 | `current_branch` | 用户当前所在分支（cleanup 第 1 步 ff-only merge 的目标） |
 | `workdir` | 项目绝对路径 |
 | `fix_scope` | `critical_warning`（默认）/ `all`（含 Info）/ `auto`（多轮收敛） |
-| `auto_round` | 仅 `--auto` 模式下传入，当前轮次（1-indexed），用于多轮收敛识别 |
+| `auto_round` | 多轮模式（`--fix` Ralph auto-retry 与 `--fix --auto` 都算）下传入，当前轮次（1-indexed），用于多轮收敛识别 |
 
 ---
 
@@ -186,7 +186,7 @@ rm .context/review-fix-recovery-pending.json
 # REVIEW-FIX Report
 
 **Status**: completed | partial | escalated
-**Round**: <auto_round> / 3   (仅 --auto 模式)
+**Round**: <auto_round> / 3   (多轮模式)
 **Findings processed**: <N>
 **Commits made**: <M>
 
@@ -206,12 +206,12 @@ rm .context/review-fix-recovery-pending.json
 - sentinel_remove: ok
 ```
 
-### Phase G. 多轮收敛（仅 `--auto` 模式）
+### Phase G. 多轮收敛（多轮模式：`--fix` Ralph auto-retry / `--fix --auto`）
 
-`--auto` 模式下，主线在你完成后会再跑一次 `/ccg:review` 生成新 REVIEW.md，再 spawn 你做下一轮。**收敛判定由主线**用 `decideConverge()` helper 做：
+多轮模式（`--fix` Ralph auto-retry 与 `--fix --auto` 都算）下，主线在你完成后会再跑一次 `/ccg:review` 生成新 REVIEW.md，再 spawn 你做下一轮。**收敛判定由主线**用 `decideConverge()` helper 做，收敛口径（blocking 第三参）也归主线按 flag 选择——`--fix` 用 `'critical'`（无 Critical 即 pass through），`--fix --auto` 用 `'critical_warning'`（critical+warning 全清）：
 
-- `continue` → 主线再 spawn 你跑下一轮
-- `converged` → critical+warning 全清，主线停
+- `continue` → 主线再 spawn 你跑下一轮（不问用户）
+- `converged` → blocking 口径下 finding 全清，主线停（pass through）
 - `escalate` → 达到 3 轮 cap 或 stall（连续 2 轮 finding 数没下降），主线升级用户
 
 **你的责任**：每轮跑完老老实实输出 REVIEW-FIX.md，不要自作主张多跑 / 少跑。`AUTO_CONVERGE_CAP = 3` 是 CCG 全体系硬规约（与 plan-checker / verify-work 一致）。

package/templates/commands/agents/phase-runner.md

@@ -32,19 +32,23 @@ color: cyan
 
 | `nested_rescue` 值 | 行为 |
 |--------------------|------|
-| `true` | 按 phase_type 路由 spawn rescue plugin 委派代码改动 |
+| `true` | 按 phase_type 路由 **Bash 直调 plugin helper** 委派代码改动（你是 fresh-context subagent，工具列表不含 Agent/Task，**只能走 Bash** 委派——见下方"为什么是 Bash 直调"） |
 | `false` 或缺省 | 自实施模式，**默认** |
 
 ### 路由（仅 `nested_rescue: true` 时）
 
-| phase_type | 委派路径 |
+占位符 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` 由 install 渲染为 `node <ccgx-call-plugin.mjs 绝对路径> <vendor> --json`：
+
+| phase_type | 委派路径（Bash 直调 helper） |
 |-----------|---------|
-| `backend` | `Agent(subagent_type="codex:codex-rescue")` |
-| `frontend` | `Agent(subagent_type="gemini:gemini-rescue")` |
-| `fullstack` | 串行：先 codex（schema/逻辑），再 gemini（前端联动） |
+| `backend` | Write 任务到 tmpfile → `Bash({ command: \`{{CODEX_BASH_TASK}} --prompt-file <tmpfile>\`, run_in_background: false })` |
+| `frontend` | Write 任务到 tmpfile → `Bash({ command: \`{{GEMINI_BASH_TASK}} --prompt-file <tmpfile>\`, run_in_background: false })` |
+| `fullstack` | 串行：先 codex（schema/逻辑）helper，再 gemini（前端联动）helper |
 | `docs` / `generic` | 自实施（rescue plugin 对文档/通用任务无优势） |
 
-接口名严格按 ground_truth_path 校验——双前缀 `codex:codex-rescue` / `gemini:gemini-rescue`（不是单前缀 `codex:rescue`）。
+**为什么是 Bash 直调**：你是主进程 sidechain subagent，工具列表**不含 Agent/Task**（引擎硬限制，line 19），所以委派只能通过 Bash 调 helper——这同时绕开 `Agent→gemini-companion→ACP` 慢路径（gemini 实测 5+min 卡死）与 sonnet wrapper silent-fallback。**tmpfile 内容必须含硬约束"必须前台执行，禁止 --background / --wait"**（helper 已被你以 `run_in_background: false` 同步等待；plugin 内再 background = 双重后台，状态全盲），并写"角色定义见对应 reviewer/architect 路径，先 Read 再开始"。`JSON.parse(stdout).text` 取委派结果。
+
+接口/占位符名严格按 ground_truth_path 校验——vendor 为 `codex` / `gemini`。
 
 ### 单 phase nested CAP
 
@@ -64,10 +68,10 @@ color: cyan
 
 | 失败场景 | 行为 |
 |---------|------|
-| Agent spawn 立即报错（plugin 未装 / subagent_type 不存在）| 当前 phase 切自实施 + 摘要 STATUS=degraded + NOTES 标 `plugin-unavailable: <name>` |
-| Plugin 报告 partial / failed | 自己评估能否修补：能修自己 Edit；不能修就 STATUS=partial 上报 |
-| Plugin 超时 / 卡死 | 30 分钟后强制 STATUS=partial + NOTES 标 `nested-timeout` |
-| 同一 phase 内 spawn 2 次都失败 | 不再尝试 nested，剩余切自实施 + STATUS=degraded |
+| Bash 直调 helper 立即报错（plugin 未装 / exit ≠ 0 / stdout < 100B）| 当前 phase 切自实施 + 摘要 STATUS=degraded + NOTES 标 `plugin-unavailable: <name>` |
+| Plugin 报告 partial / failed（`JSON.parse(stdout)` status 非 ok）| 自己评估能否修补：能修自己 Edit；不能修就 STATUS=partial 上报 |
+| Plugin 超时 / 卡死（helper 已带 wall/idle 双层超时，可显式 `--timeout-ms`）| 30 分钟后强制 STATUS=partial + NOTES 标 `nested-timeout` |
+| 同一 phase 内委派 2 次都失败 | 不再尝试 nested，剩余切自实施 + STATUS=degraded |
 
 ### 摘要扩展字段
 
@@ -105,8 +109,12 @@ color: cyan
 | `commit_prefix` | git commit message 前缀，如 `feat(v4-p2):` |
 | `design_brief`（可选） | triple/debate 模式 plan wave 后由主线注入的 Markdown brief（共识 / 分歧 / 必决策点）；fast 模式下缺省 |
 | `verify_findings`（可选） | 修订轮（revise）由主线注入的 verify wave critical findings 反馈块，要求"仅修复 critical，不重做整个 phase" |
-| `nested_rescue`（可选） | 布尔；`true` 启用 nested rescue 委派（按 phase_type spawn `codex:codex-rescue` / `gemini:gemini-rescue`），`false` 或缺省走自实施。详见"Nested rescue delegation"段 |
+| `nested_rescue`（可选） | 布尔；`true` 启用 nested rescue 委派（按 phase_type Bash 直调 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` helper），`false` 或缺省走自实施。详见"路由"段 |
 | `job_id`（可选） | 主线 launcher 分配的 job-id；用于读 `.context/jobs/<job_id>/degraded.flag` 决定是否中止 nested |
+| `summary_format`（可选） | **Workflow 编排模式专属**；值为 `json` 时最终摘要输出为 7 字段 JSON 对象（见"Workflow 编排模式"段）。缺省走 Phase G 文本格式 |
+| `checkpoint_path`（可选） | **Workflow 编排模式专属**；开工前 Read 它做幂等重入，收尾把摘要 JSON Write 到此路径 |
+| `cancel_flag_path`（可选） | **Workflow 编排模式专属**；开工前 Read，文件存在 → 立即返回 `{status:'failed', notes:'cancel-flag-detected'}` |
+| `progress_log`（可选） | **Workflow 编排模式专属**；收尾向此 jsonl append 一行 `{"type":"phase-result","phase_id":...,"status":...}` |
 
 **禁止从 `~/.claude/.ccg/config.toml` 读 `BACKEND_PRIMARY/FRONTEND_PRIMARY`**——主线在 prompt 里明确告知模型路由（避免双源不一致）。
 
@@ -167,12 +175,12 @@ color: cyan
 **两条路径，由 `nested_rescue` 字段决定**：
 
 - **`nested_rescue: false`（默认）**：自己用 Edit/Write/Bash 做完所有事
-- **`nested_rescue: true`**：按"Nested rescue delegation"段路由 spawn `codex:codex-rescue` / `gemini:gemini-rescue` 委派代码改动；spawn 前先 Read `degraded.flag` 校验；遵守 CAP=3；失败按降级路径处理
+- **`nested_rescue: true`**：按"路由"段 Bash 直调 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` helper（`run_in_background: false` 同步等待，tmpfile 含"禁止 --background"硬约束）委派代码改动；委派前先 Read `degraded.flag` 校验；遵守 CAP=3；失败按降级路径处理
 
 实施过程（两路径共用）：
 1. **理解 phase**：Read phase_goal / phase_acceptance / phase_depends_on（依赖产物文件）
 2. **codebase 探索**：用 Glob/Grep/Read 找相关文件 + 现有 pattern
-3. **代码改动**：自实施时 Edit/Write 落地；nested 时 spawn rescue 委派 + 拿回报告 + 自己 wrap up
+3. **代码改动**：自实施时 Edit/Write 落地；nested 时 Bash 直调 helper 委派 + `JSON.parse(stdout).text` 拿回报告 + 自己 wrap up
 4. **走完 acceptance 每条**：每改完一项立即用 Bash 跑命令验证（test focused / typecheck / grep 等）
 
 ### Phase C. 写报告
@@ -233,7 +241,7 @@ challenger 钩子由主线层编排（与 nested rescue 是两个独立机制）
 输出**严格 200 token 内**的字符串给主线：
 
 ```
-STATUS: completed | partial | failed
+STATUS: completed | partial | failed | degraded
 COMMIT: <sha7> | none
 TESTS: <pass>/<total> passed (delta +<n> from <baseline>)
 TYPECHECK: pass | fail
@@ -251,6 +259,30 @@ NOTES: <一行关键发现 / 灰区决策点 / 下一步建议>
 
 **禁止超过 200 token**——主线推进 phase 决策只看这个摘要。多余信息放报告文件 + git commit message。
 
+### Workflow 编排模式（summary_format: json）
+
+主线走 `/ccg:autonomous` 原生 Workflow 编排时，prompt 含 `summary_format: json`。此模式下你的**最终输出**不再是 Phase G 的文本格式，而是符合以下 7 字段 JSON schema 的对象（Workflow 引擎 schema 强制结构化返回）：
+
+```json
+{
+  "status": "completed | partial | failed | degraded",
+  "commit": "<sha7> 或 \"none\"",
+  "tests": "<pass>/<total> passed (delta +<n>) 或 \"n/a\"",
+  "typecheck": "pass | fail | unknown",
+  "handoff_taken": ["git_commit", "test_run", "typecheck"],
+  "context_delta": "≤50 字",
+  "notes": "≤80 字"
+}
+```
+
+字段名小写下划线，语义与 Phase G 文本字段 1:1 对应（schema 真相源：`src/utils/workflow-autonomous.ts` 的 `PHASE_SUMMARY_SCHEMA`）。**文本格式仍是 legacy 默认**——`summary_format` 缺省时照旧输出 Phase G 文本，零行为变化。
+
+三项额外责任（按时序）：
+
+1. **cancel.flag 检查（开工前）**：Read `cancel_flag_path`，文件存在 → 立即返回 `{"status":"failed","notes":"cancel-flag-detected","commit":"none","tests":"n/a","typecheck":"unknown","handoff_taken":[],"context_delta":"canceled before start"}`，不做任何代码改动
+2. **checkpoint 幂等重入（开工前）**：Read `checkpoint_path`，存在且其 `status` 为 `completed` → **原样返回其内容**，不重做实施（`--resume` 缓存未命中时防重复工作）
+3. **checkpoint + progress 落盘（收尾）**：Write `checkpoint_path`（内容 = 你的摘要 JSON 本体）+ 向 `progress_log` append 一行 `{"type":"phase-result","phase_id":"<id>","status":"<status>"}`（供 `/ccg:status` dashboard / tail 观测）
+
 ---
 
 ## 失败模式

package/templates/commands/agents/plan-checker.md

@@ -9,6 +9,7 @@ color: purple
 
 ## 核心定位
 
+- **Gate 类型**：revision-loop（max 3）→ escalation（taxonomy 见 `/ccg:verify` 的 Gates Taxonomy 段，SSoT = `src/utils/verify-orchestrator.ts:GATE_REGISTRY`）
 - **5 维度强校验**：GSD plan-checker 12 维度的高 ROI 子集（Dim 1 / 2 / 5 / 7b / 10）
 - **判定算法显式化**：每个维度都有明确触发条件 + 修复建议格式
 - **max-3-loop 收敛环**：BLOCKER 退回 planner，最多 3 轮；超限升级用户决策
@@ -62,6 +63,14 @@ for r in missing:
 
 **注意**：大小写不敏感匹配（`REQ-01` == `req-01`）。
 
+**REQ-ID 来源格式**（确定性提取，规则权威 `src/utils/plan-checker.ts`）：
+
+| 来源 | 格式 | 提取函数 |
+|------|------|---------|
+| roadmap | `- **Requirements**: REQ-01, REQ-02` 行（phase 块内） | `extractPhaseRequirementIds` |
+| OPSX proposal | checkbox `- [ ] **REQ-NN** <描述>` 或表格首列 `| REQ-NN | ... |` | `extractRequirementIds` |
+| plan 声明 | frontmatter `requirements: [REQ-01, REQ-02]`（inline 或多行 list） | `parsePlanFrontmatter` |
+
 #### Dim 2: Task Completeness（任务完整性）
 
 **算法**：对每个 task 检查 4 字段（中英双语字段名都接受）：
@@ -188,6 +197,7 @@ if loop_count == 3 and result.hasBlocker:
 - 单次 loop 内 plan-checker 必须返回完整 findings（不允许"再确认一下"中途返回）
 - planner 修订时**只允许针对 BLOCKER**改动（不要顺手改其他段，避免引入新问题）
 - 第 3 次 loop 仍失败 → **不允许默认通过**，必须 AskUserQuestion 升级
+- **stall detection（提前升级）**：连续两轮 BLOCKER 数不下降（本轮 ≥ 上一轮）→ 不等满 3 轮直接 AskUserQuestion 升级（`src/utils/verify-orchestrator.ts:resolveVerifyGateAction` 同源语义——收敛环不收敛就别空转）
 
 ---
 

package/templates/commands/analyze.md

@@ -37,14 +37,14 @@ argument-hint: "<分析问题或任务> [--role=architect|critic|implementer|tes
 
 ## 调用通道路由（CCG codeagent 退役）
 
-CCG 把双模型并行通道从 `Bash(codeagent-wrapper)` **默认切换**为 plugin spawn：
+CCG 把双模型并行通道从 `Bash(codeagent-wrapper)` **默认切换**为 Bash 直调 plugin 快路径：
 
-1. **优先 plugin spawn**（默认）：装了 `codex@openai-codex` + gemini plugin（推荐 `gemini@gemini-ccgx` fork，含 P-1..P-21 + W1/W2/I1 patch；或上游 `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，含 P-1..P-21 + W1/W2/I1 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)` 取 `.text`。
 2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → fallback 到 Bash 调用，行为与 plugin 路径等价。
 
-**判定**：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）。
 
-⚠️ Analyze 命令在主线 context 内，**允许** `Agent(...)`——与 subagent "禁止嵌套 spawn" 约束不冲突。
+⚠️ Analyze 命令在主线 context 内执行，通道 A 走 Bash 直调（不再 spawn `Agent(...)`），无嵌套 spawn 顾虑。
 
 ---
 
@@ -57,28 +57,69 @@ CCG 把双模型并行通道从 `Bash(codeagent-wrapper)` **默认切换**为 pl
 
 **调用语法**（双通道）：
 
-**通道 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>`、运行**。helper 内部处理路径解析、
+> spawn array args、shell escape 全部规避——LLM 不参与任何命令构造，也不写 `Agent(...)`。
+> 这条 Bash 直调通道自动吃到 gemini-batch 29s 快路径，消除 `Agent→gemini-companion→ACP`
+> 的 5+min 卡死与 sonnet wrapper silent-fallback（broker 故障时自答 fabricated 视角）。
+
+```
+Step 1. 用 Write 把任务描述写到 tmpfile（≤2KB，只放任务说明 + 角色提示词路径，不塞大段代码/diff）：
+   Write({
+     file_path: ".context/tmp/ccg-analyze-codex-$JOB.txt",
+     content: <下方"任务描述模板">
+   })
+   Write({ 同上，gemini 版本，file_path: ".context/tmp/ccg-analyze-gemini-$JOB.txt" })
+
+Step 2. 用 Bash 调 helper（占位符已渲染；纯分析只读，加 `--no-write`；并行两个在同一 message 内 run_in_background: true）：
+   Bash({
+     command: `{{CODEX_BASH_TASK}} --no-write --prompt-file .context/tmp/ccg-analyze-codex-$JOB.txt`,
+     description: "Analyze: backend (codex direct)",
+     run_in_background: true
+   })
+   Bash({
+     command: `{{GEMINI_BASH_TASK}} --no-write --prompt-file .context/tmp/ccg-analyze-gemini-$JOB.txt`,
+     description: "Analyze: frontend (gemini direct)",
+     run_in_background: true
+   })
+
+Step 3. 等 task-notification 后 Read 各自 stdout，`JSON.parse(stdout)` 取 helper 扁平化后的
+   `.text` 字段（= 模型真实输出）；`.threadId` / `.stats` 同层可读。
 ```
-Agent({
-  subagent_type: "<codex:codex-rescue|gemini:gemini-rescue>",
-  description: "Analyze: <backend|frontend>",
-  prompt: `ROLE_FILE: <角色提示词路径>
 
-<TASK>
+**任务描述模板**（写到 tmpfile 的内容；保持 ≤2KB）：
+
+```
+# 任务：技术分析
+
+工作目录：<工作目录绝对路径>（你已在此，可直接用 Bash/Read）
+角色定义见 <角色提示词路径>（codex 用 ~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md，gemini 用 {{FRONTEND_PRIMARY}}/analyzer.md），**先用 Read 工具读取该文件再开始分析**。
+
+## 你要做的事（用你自己的工具）
+
 需求：<增强后的需求（如未增强则用 $ARGUMENTS）>
-上下文：<前序阶段检索到的代码上下文>
-</TASK>
+上下文：<前序阶段检索到的关键文件路径 + 符号名，不塞大段源码，让你自己 Read>
 
-OUTPUT: 期望输出格式
-Return ≤200 token structured summary (plugin-native protocol).
-`
-})
+- codex (backend)：技术可行性、架构影响、性能考量、潜在风险
+- gemini (frontend)：UI/UX 影响、用户体验、视觉设计考量
+
+## 硬约束
+
+- **必须前台执行，禁止 `--background` / `--wait`**（ccgx 编排层已用 Agent run_in_background 包裹，插件内再 background = 双重后台，stop-gate / status / cancel 全盲）。
+- 对文件系统零写入，仅分析。
+
+## 输出（JSON）
+
+{ "feasibility": "...", "impacts": [...], "risks": [...], "recommendations": [...] }
+只输出 JSON，无其他文本。
 ```
 
-并行**两个 Agent 在同一 message 内同时 spawn**。
+⛔ **严禁**：在 prompt 里塞大段源码 / git diff（撞 OS argv ~32KB 上限）；写 `Agent(subagent_type="gemini:gemini-rescue")`（走 ACP 慢路径 + sonnet wrapper silent-fallback）；heredoc / `-p "..."` 内联；硬编码 plugin 路径。**唯一允许**：copy 占位符 + 追加 `--prompt-file <tmpfile>`（纯分析只读流另加 `--no-write`）。
 
-**通道 B — codeagent-wrapper fallback**（plugin 未装时降级，并行用 `run_in_background: true`）：
+**通道 B — codeagent-wrapper fallback**（plugin 未装时降级，并行用 `run_in_background: true`；wrapper 走 stdin pipe，无 ARG_MAX 限制，其 `ROLE_FILE:` 由 `invoke-model.mjs` 解析故保留）：
 
 ```
 Bash({
@@ -96,7 +137,7 @@ EOF",
 })
 ```
 
-> ⚠️ 通道 B `codeagent-wrapper` 已标 **deprecated**。
+> ⚠️ 通道 B `codeagent-wrapper` 已标 **deprecated**，仅 plugin 未装时使用。
 
 **角色提示词**：
 
@@ -110,7 +151,7 @@ EOF",
 1. 同 message 内 spawn 多个 `Bash(run_in_background: true)` 并行任务
 2. spawn 完后主线说明已启动 task-id，**直接 turn end**，**不调 TaskOutput**
 3. Claude Code 引擎在每个 task 完成时自动发 `<task-notification>` system-reminder 触发主线新 turn
-4. 主线在新 turn 处理：从 `<output-file>` 路径 read stdout，按通道 schema parse 结果
+4. 主线在新 turn 处理：从 `<output-file>` 路径 read stdout，`JSON.parse(stdout)` 取 helper 扁平化后的 `.text`（通道 A）/ `--progress` 行（通道 B）
 5. **必须等所有相关 task 都收到通知**才进入下一阶段（按 task-id 计数已收齐）
 
 ⛔ **禁止**：
@@ -142,14 +183,14 @@ EOF",
 
 `[模式：分析]`
 
-**⚠️ 必须发起两个并行 Bash 调用**（参照上方调用规范）：
+**⚠️ 必须发起两个并行 Bash 直调 helper 调用**（参照上方调用规范，先 Write tmpfile 再 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}` + `--prompt-file`）：
 
-1. **{{BACKEND_PRIMARY}} 后端分析**：`Bash({ command: "...--backend {{BACKEND_PRIMARY}}...", run_in_background: true })`
-   - ROLE_FILE: `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md`
+1. **{{BACKEND_PRIMARY}} 后端分析**：`{{CODEX_BASH_TASK}} --no-write --prompt-file <tmpfile>`（`run_in_background: true`）
+   - 角色：tmpfile 内写"角色定义见 `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md`，先用 Read 工具读取再开始"
    - OUTPUT：技术可行性、架构影响、性能考量
 
-2. **{{FRONTEND_PRIMARY}} 前端分析**：`Bash({ command: "...--backend {{FRONTEND_PRIMARY}}...", run_in_background: true })`
-   - ROLE_FILE: `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md`
+2. **{{FRONTEND_PRIMARY}} 前端分析**：`{{GEMINI_BASH_TASK}} --no-write --prompt-file <tmpfile>`（`run_in_background: true`）
+   - 角色：tmpfile 内写"角色定义见 `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md`，先用 Read 工具读取再开始"
    - OUTPUT：UI/UX 影响、用户体验、视觉设计考量
 
 事件驱动等待：spawn 完两个 Bash bg 后主线 turn end，等 task-notification 自动唤醒。**必须等所有模型返回后才能进入下一阶段**。