ccgx-workflow 1.0.4 → 1.0.5

package/templates/commands/verify-work.md

@@ -1,6 +1,6 @@
 ---
 name: ccg:verify-work
-description: 会话式 UAT 工作流 - UAT.md 状态文件 + cold-start smoke 自动注入 + 自动 diagnose-plan-fix 收敛环（v4.0 P9）
+description: 会话式 UAT 工作流 - UAT.md 状态文件 + cold-start smoke 自动注入 + 自动 diagnose-plan-fix 收敛环
 argument-hint: "[task-id]"
 allowed-tools:
   - Read
@@ -13,23 +13,23 @@ allowed-tools:
   - Agent
 ---
 
-# Verify Work — 会话式 UAT 工作流（v4.0 Phase 9）
+# Verify Work — 会话式 UAT 工作流
 
-v3.0 的 verify-work 是纯**编排器**——按变更性质开 verify-{module,security,quality,change} 子门，跑完聚合报告。但它**没法做真正的 UAT**：
+早期的 verify-work 是纯**编排器**——按变更性质开 verify-{module,security,quality,change} 子门，跑完聚合报告。但它**没法做真正的 UAT**：
 
 1. 用户得自己拿着报告人肉对照"这事儿到底验没验过"；
 2. `/clear` 后所有上下文丢失，UAT 进度归零；
 3. 只看代码不跑冷启动——race condition / silent seed failure / 缺环境变量在生产才暴露；
 4. 用户报 issue 后没有自动收敛环——靠用户手动来回贴报告。
 
-v4.0 把 verify-work 改造成**有状态的会话工作流**：
+当前 verify-work 是**有状态的会话工作流**：
 
 - **UAT.md frontmatter 状态文件**：跨 `/clear` 持久化，下次进入命令自动 resume；
 - **逐项核对**（show expected → ask if matches）：每条期望行为都明示问，不让模糊滑过；
 - **Cold-start smoke 自动注入**：扫 git diff 命中关键路径即注入"杀进程 → 清临时态 → 冷启动 → 主查询返回数据"测试；
 - **自动 diagnose → planner --gaps → plan-checker 收敛环**（max 3 轮）：用户报 issue 立即触发，无需手动调度。
 
-**与 v3.0 的关系**：v3.0 的多门聚合不删，迁移为 Step 2（verify-* 子门作为静态扫描）。v4.0 的会话循环裹在外层（Step 0/1/3/4/5）。
+**多门聚合保留**：早期的多门聚合不删，迁移为 Step 2（verify-* 子门作为静态扫描）。会话循环裹在外层（Step 0/1/3/4/5）。
 
 ---
 
@@ -132,9 +132,9 @@ fi
 
 ### Step 2 — 静态门 + cold-start smoke 注入
 
-#### 2a. 静态扫描（v3.0 多门保留）
+#### 2a. 静态扫描（多门保留）
 
-按 git diff 性质开门（v3.0 决策矩阵）：
+按 git diff 性质开门（决策矩阵）：
 
 | 变更性质 | 触发判据 | 门组 |
 |---------|---------|------|
@@ -317,7 +317,7 @@ else:
 | verify-change | Step 2a 静态门，常规改动必跑 |
 | verifier agent | Step 2a 末尾兜底，做需求矩阵反向溯源（v4 Phase 8 加 Level 4 数据流） |
 
-## 与 v4.0 helper 的契约
+## 与 helper 的契约
 
 | Helper | 用途 |
 |--------|------|

package/templates/commands/verify.md

@@ -9,9 +9,9 @@ allowed-tools:
   - Agent
 ---
 
-# /ccg:verify - 统一校验关卡（v4.0+）
+# /ccg:verify - 统一校验关卡
 
-替代 v3.x 时代的 4 个独立命令 `/ccg:verify-{change,quality,security,module}`，统一入口 + 子门路由，降低命令面板认知负担。
+替代早期的 4 个独立命令 `/ccg:verify-{change,quality,security,module}`，统一入口 + 子门路由，降低命令面板认知负担。
 
 ## 使用方法
 
@@ -48,7 +48,7 @@ $ARGUMENTS
 
 ## 兼容性
 
-旧的 `/ccg:verify-change` / `/ccg:verify-quality` / `/ccg:verify-security` / `/ccg:verify-module` 仍可工作（由 Skill Registry 自动生成），但 SKILL.md 已标记 `deprecated_in: v4.0`、`replaced_by: /ccg:verify --gate=<name>`。建议新工作流使用本统一命令。
+旧的 `/ccg:verify-change` / `/ccg:verify-quality` / `/ccg:verify-security` / `/ccg:verify-module` 仍可工作（由 Skill Registry 自动生成），但 SKILL.md 已标记 `deprecated_in: 1.0.0`、`replaced_by: /ccg:verify --gate=<name>`。建议新工作流使用本统一命令。
 
 ## 执行流程
 

package/templates/commands/workflow.md

@@ -83,7 +83,7 @@ EOF",
 
 **会话复用**：每次调用返回 `SESSION_ID: xxx`，后续阶段用 `resume xxx` 复用上下文（注意：是 `resume`，不是 `--resume`）。
 
-**并行调用 + 事件驱动等待（v4.5.2 起）**：
+**并行调用 + 事件驱动等待**：
 
 1. 同 message 内 spawn 多个 `Bash(run_in_background: true)` 并行任务
 2. spawn 完后主线说明已启动 task-id，**直接 turn end**，**不调 TaskOutput**
@@ -92,7 +92,7 @@ EOF",
 5. **必须等所有相关 task 都收到通知**才进入下一阶段（按 task-id 计数已收齐）
 
 ⛔ **禁止**：
-- 调 `TaskOutput({block: true, timeout: 600000})` —— v4.5.1 之前的旧 freeze poll 模式，已废弃
+- 调 `TaskOutput({block: true, timeout: 600000})` —— 旧 freeze poll 模式，已废弃
 - 收到部分通知就跳过等其他模型
 - 主动 Kill task
 

package/templates/rules/ccg-skills.md

@@ -2,7 +2,7 @@
 
 When working in a project, automatically invoke the corresponding quality gate skills based on the scenario below. These skills are installed at `~/.claude/skills/ccg/` and can be called directly.
 
-**v4.0+ NOTE**: The unified entry point `/ccg:verify --gate=<name>` is preferred over the legacy `verify-*` skill names. Both still work in v4.x for BC. Examples below show the new form first, with the legacy alias in parentheses.
+**NOTE**: The unified entry point `/ccg:verify --gate=<name>` is preferred over the legacy `verify-*` skill names. Both still work for BC. Examples below show the new form first, with the legacy alias in parentheses.
 
 ## Trigger Rules
 

package/templates/scripts/ccgx-call-plugin.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+// =============================================================================
+//  ccgx-call-plugin.mjs                                          1.0.5
+// -----------------------------------------------------------------------------
+//  Pure-Node helper for invoking codex/gemini plugin companions WITHOUT any
+//  shell-escape risk. Replaces the 1.0.4 heredoc-via-Bash pattern.
+//
+//  Why this exists (1.0.5 design after 1.0.4 dogfood):
+//    LLM-constructed Bash commands proved unreliable. Two failure modes hit
+//    in 1.0.4:
+//      1. LLM cargo-culted anti-example code from review.md docs
+//      2. LLM in actual review session still wrote `ls $(...) | head -1`
+//         glob-hack patterns despite placeholder system
+//
+//    Root cause: any design that asks the LLM to construct or substitute parts
+//    of a shell command has X% failure rate. X varies but is never zero.
+//
+//    Fix: collapse the LLM surface to "choose vendor + pass prompt-file path".
+//    All path resolution, flag construction, shell-quote-avoidance are done
+//    internally by Node spawn with array args (no shell).
+//
+//  Usage (LLM workflow):
+//    1. Write prompt body to a temp file (via Write tool):
+//         /tmp/ccg-codex-1234.txt
+//    2. Run helper via Bash:
+//         node ~/.claude/.ccg/scripts/ccgx-call-plugin.mjs codex \
+//              --prompt-file /tmp/ccg-codex-1234.txt
+//    3. Parse the JSON output emitted to stdout
+//
+//  Output schema (always JSON, even on error):
+//    {
+//      "status": "ok" | "error",
+//      "vendor": "codex" | "gemini",
+//      "version": "<plugin version>",
+//      "durationMs": <number>,
+//      "exitCode": <number | null>,
+//      "stdout": "<companion stdout>",
+//      "stderr": "<companion stderr>",
+//      "error": "<error message if status=error, else absent>"
+//    }
+//
+//  CLI args:
+//    <vendor>                Required. 'codex' or 'gemini'.
+//    --prompt-file <path>    Required. Path to file containing prompt body.
+//    --json                  Pass --json to companion (default: true).
+//    --no-json               Disable --json (text output).
+//    --timeout-ms <N>        Kill companion after N ms (default: 600000).
+//    --max-budget-usd <N>    Forwarded to companion (default: 50).
+//
+//  Cross-cutting:
+//    - Pure stdlib (fs, child_process, path, os). No deps.
+//    - Always emits valid JSON to stdout (so LLM can always JSON.parse).
+//    - Plugin path resolution via SSoT (~/.claude/plugins/installed_plugins.json).
+//    - spawn uses array args + windowsHide:true → zero shell escape surface.
+// =============================================================================
+
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir, platform } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// ---------------------------------------------------------------------------
+// Vendor → marketplace key (matches plugin-bash-codegen.ts SSoT lookup)
+// ---------------------------------------------------------------------------
+
+const VENDOR_KEYS = {
+  codex: 'codex@openai-codex',
+  gemini: 'gemini@google-gemini',
+}
+
+// ---------------------------------------------------------------------------
+// Argument parsing — minimal, KISS, no external CLI lib.
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = {
+    vendor: null,
+    promptFile: null,
+    json: true,
+    timeoutMs: 600000,
+    maxBudgetUsd: 50,
+  }
+
+  const positional = []
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i]
+    const next = () => {
+      const v = argv[++i]
+      if (v === undefined) throw new Error(`flag ${arg} requires a value`)
+      return v
+    }
+    switch (arg) {
+      case '--prompt-file':    opts.promptFile = next(); break
+      case '--json':           opts.json = true; break
+      case '--no-json':        opts.json = false; break
+      case '--timeout-ms':     opts.timeoutMs = Number.parseInt(next(), 10); break
+      case '--max-budget-usd': opts.maxBudgetUsd = Number.parseFloat(next()); break
+      case '--help':
+      case '-h':
+        printHelp()
+        process.exit(0)
+      default:
+        if (arg.startsWith('--')) throw new Error(`unknown flag: ${arg}`)
+        positional.push(arg)
+    }
+  }
+
+  if (positional.length === 0) throw new Error('vendor (codex|gemini) is required')
+  if (positional.length > 1) throw new Error(`too many positional args: ${positional.join(' ')}`)
+  opts.vendor = positional[0]
+
+  if (!VENDOR_KEYS[opts.vendor]) {
+    throw new Error(`unknown vendor: ${opts.vendor} (must be 'codex' or 'gemini')`)
+  }
+  if (!opts.promptFile) {
+    throw new Error('--prompt-file is required (path to file containing prompt body)')
+  }
+  return opts
+}
+
+function printHelp() {
+  process.stderr.write(`Usage: ccgx-call-plugin.mjs <vendor> --prompt-file <path> [flags]
+
+Required:
+  <vendor>                'codex' or 'gemini'
+  --prompt-file <path>    File containing prompt body (any content, no escape needed)
+
+Optional:
+  --json                  Pass --json to companion (default: true)
+  --no-json               Disable --json (text output)
+  --timeout-ms <N>        Kill companion after N ms (default: 600000)
+  --max-budget-usd <N>    Per-call cost cap (default: 50)
+
+Outputs JSON to stdout: {status, vendor, version, durationMs, exitCode, stdout, stderr, error?}
+`)
+}
+
+// ---------------------------------------------------------------------------
+// Plugin discovery (mirror of plugin-bash-codegen.ts:discoverCompanion)
+// ---------------------------------------------------------------------------
+
+function discoverCompanion(vendor, homeDir = homedir()) {
+  const ssotPath = join(homeDir, '.claude', 'plugins', 'installed_plugins.json')
+  if (!existsSync(ssotPath)) {
+    return { error: `installed_plugins.json not found at ${ssotPath}` }
+  }
+
+  let raw
+  try {
+    raw = JSON.parse(readFileSync(ssotPath, 'utf-8'))
+  }
+  catch (e) {
+    return { error: `installed_plugins.json parse failed: ${e.message}` }
+  }
+
+  const key = VENDOR_KEYS[vendor]
+  const instances = raw?.plugins?.[key]
+  if (!Array.isArray(instances) || instances.length === 0) {
+    return { error: `plugin ${key} not installed (no entry in installed_plugins.json)` }
+  }
+
+  const inst = instances[0]
+  const installPath = inst?.installPath
+  if (typeof installPath !== 'string' || !installPath) {
+    return { error: `plugin ${key} has no installPath in installed_plugins.json` }
+  }
+
+  const companionPath = join(installPath, 'scripts', `${vendor}-companion.mjs`)
+  if (!existsSync(companionPath)) {
+    return { error: `companion script missing: ${companionPath}` }
+  }
+
+  return {
+    companionPath,
+    version: typeof inst?.version === 'string' ? inst.version : 'unknown',
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Output emission — always JSON, never throws to stdout
+// ---------------------------------------------------------------------------
+
+function emitJson(result) {
+  process.stdout.write(`${JSON.stringify(result)}\n`)
+}
+
+function emitError(vendor, version, error, extra = {}) {
+  emitJson({
+    status: 'error',
+    vendor,
+    version,
+    durationMs: 0,
+    exitCode: null,
+    stdout: '',
+    stderr: '',
+    error,
+    ...extra,
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Main: spawn companion with array args (no shell)
+// ---------------------------------------------------------------------------
+
+async function main(argv) {
+  let opts
+  try {
+    opts = parseArgs(argv)
+  }
+  catch (err) {
+    emitError(null, null, `arg parse: ${err.message}`)
+    process.exit(64) // EX_USAGE
+  }
+
+  // Read prompt body from file (no shell, no escape concerns)
+  let promptBody
+  try {
+    promptBody = readFileSync(opts.promptFile, 'utf-8')
+  }
+  catch (err) {
+    emitError(opts.vendor, null, `prompt file read failed: ${err.message}`)
+    process.exit(66) // EX_NOINPUT
+  }
+
+  // Discover companion via SSoT (no glob, no head -1)
+  const disc = discoverCompanion(opts.vendor)
+  if (disc.error) {
+    emitError(opts.vendor, null, disc.error)
+    process.exit(69) // EX_UNAVAILABLE
+  }
+
+  // Build companion argv as ARRAY — no shell layer ever
+  const companionArgs = [
+    disc.companionPath,
+    'task',
+    '-p',
+    promptBody,
+  ]
+  if (opts.json) companionArgs.push('--json')
+
+  const startedAt = Date.now()
+
+  // spawn 'node' with array args. Node will look up its own executable;
+  // companionPath is passed as a literal arg, no shell interpretation.
+  const child = spawn(process.execPath, companionArgs, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+    env: {
+      ...process.env,
+      // Forward budget cap if companion respects it (codex does)
+      CODEX_MAX_BUDGET_USD: String(opts.maxBudgetUsd),
+      GEMINI_MAX_BUDGET_USD: String(opts.maxBudgetUsd),
+    },
+  })
+
+  let stdoutBuf = ''
+  let stderrBuf = ''
+  child.stdout.on('data', (chunk) => { stdoutBuf += chunk.toString('utf-8') })
+  child.stderr.on('data', (chunk) => { stderrBuf += chunk.toString('utf-8') })
+
+  // Timeout: kill child if exceeds opts.timeoutMs
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    try { child.kill('SIGTERM') } catch { /* ignore */ }
+    setTimeout(() => {
+      try { child.kill('SIGKILL') } catch { /* ignore */ }
+    }, 5000).unref?.()
+  }, opts.timeoutMs)
+
+  const exit = await new Promise((resolve) => {
+    child.once('exit', (code, signal) => resolve({ code, signal }))
+    child.once('error', (err) => resolve({ code: 70, signal: null, errorMsg: err.message }))
+  })
+  clearTimeout(timer)
+
+  const durationMs = Date.now() - startedAt
+  const status = (!timedOut && exit.code === 0) ? 'ok' : 'error'
+  const result = {
+    status,
+    vendor: opts.vendor,
+    version: disc.version,
+    durationMs,
+    exitCode: exit.code,
+    stdout: stdoutBuf,
+    stderr: stderrBuf,
+  }
+  if (timedOut) result.error = `timeout after ${opts.timeoutMs}ms`
+  else if (exit.errorMsg) result.error = `spawn error: ${exit.errorMsg}`
+  else if (exit.code !== 0) result.error = `companion exited with code ${exit.code}`
+
+  emitJson(result)
+  process.exit(status === 'ok' ? 0 : 1)
+}
+
+// ---------------------------------------------------------------------------
+// Entry point — only run main() when invoked as a script (not on import).
+// ---------------------------------------------------------------------------
+
+function isMainModule() {
+  if (!process.argv[1]) return false
+  try {
+    const here = fileURLToPath(import.meta.url)
+    return here === process.argv[1]
+  }
+  catch {
+    return false
+  }
+}
+
+if (isMainModule()) {
+  main(process.argv).catch((err) => {
+    emitError(null, null, `fatal: ${err.stack || err.message}`)
+    process.exit(70)
+  })
+}
+
+// Test surface for unit tests
+export const ccgxCallPluginExports = {
+  parseArgs,
+  discoverCompanion,
+  VENDOR_KEYS,
+}

package/templates/skills/tools/extract-learnings/SKILL.md

@@ -10,8 +10,6 @@ argument-hint: "[--since=30d]"
 
 # 📚 复盘关卡 · 经验萃取
 
-> v4.1-p18：作为 skill 暴露（v3.0 曾有 `/ccg:extract-learnings` 命令规划，v4.0/v4.1 收敛到 skill 化触发）。
-
 从最近的开发活动中萃取**可复用知识**，写入 `.context/learnings/<日期>-extract.md`，避免反复踩同坑。
 
 ## 使用方法
@@ -58,7 +56,7 @@ ls .claude/team-plan/*-report.md 2>/dev/null
 1. ...
 
 ## 决策记录
-- **D1: 用 SessionStart hook 注入 roadmap** — 原因：v4.0 主线零项目记忆痛点
+- **D1: 用 SessionStart hook 注入 roadmap** — 原因：主线零项目记忆痛点
 
 ## 工具陷阱
 - **subagent 不能 spawn 子 agent**（commit a7cdffd 实测）

package/templates/skills/tools/forensics/SKILL.md

@@ -10,8 +10,6 @@ argument-hint: "<file:line> 或 <function-name>"
 
 # 🔬 取证关卡 · 代码考古
 
-> v4.1-p18：作为 skill 暴露（v3.0 曾有 `/ccg:forensics` 规划）。
-
 给定一段"问题代码"或"已知 bug 现场"，反向重建事故时间线：
 
 - 这一段最早什么时候引入？哪个 PR？

package/templates/skills/tools/health/SKILL.md

@@ -10,8 +10,6 @@ argument-hint: "[--repair]"
 
 # 🏥 健康度关卡 · 项目体检
 
-> v4.1-p18：从 `/ccg:health` 命令迁移为 skill。`/ccg:health` 自动生成路由保留。
-
 一次性盘点项目"是不是在烂掉"。不深入业务正确性，只看**工程层面的卫生指标**：依赖陈旧度、已知漏洞、文档与代码同步度、堆积的 TODO、CLAUDE.md 是否还反映现状、测试覆盖率（如可拿到）。输出 markdown 报告，每项打分 + 给出可执行修复建议。
 
 `--repair` 模式：对**安全且确定**的问题（如自动生成的过期文档骨架）询问后修复，绝不擅自动核心代码或依赖。

package/templates/skills/tools/map-codebase/SKILL.md

@@ -10,8 +10,6 @@ argument-hint: "[--fast] [focus-area]"
 
 # 🗺 制图关卡 · 代码库结构图
 
-> v4.1-p18：从 `/ccg:map-codebase` 命令迁移为 skill。`/ccg:map-codebase` 自动生成路由保留。
-
 为陌生项目 / 大型 brownfield 项目快速画一张"地图"：哪些模块、模块间怎么依赖、关键技术栈、入口点在哪。输出三件套：
 
 1. **mermaid 模块依赖图**（可视化）

package/templates/skills/tools/verify-change/SKILL.md

@@ -7,9 +7,9 @@ user-invocable: true
 disable-model-invocation: false
 allowed-tools: Bash, Read, Grep
 argument-hint: [--mode working|staged|committed]
-deprecated_in: v4.0
+deprecated_in: 1.0.0
 replaced_by: /ccg:verify --gate=change
-deprecation_message: v4.0+ 推荐使用 `/ccg:verify --gate=change`。本命令仍可用以保持 BC，将在 v5.0 移除。详见 .ccg-migration/DEPRECATIONS.md
+deprecation_message: 推荐使用 `/ccg:verify --gate=change`。本命令仍可用以保持 BC。详见 .ccg-migration/DEPRECATIONS.md
 ---
 
 # ⚖ 校验关卡 · 变更校验

package/templates/skills/tools/verify-module/SKILL.md

@@ -7,9 +7,9 @@ user-invocable: true
 disable-model-invocation: false
 allowed-tools: Bash, Read, Glob
 argument-hint: <模块路径>
-deprecated_in: v4.0
+deprecated_in: 1.0.0
 replaced_by: /ccg:verify --gate=module
-deprecation_message: v4.0+ 推荐使用 `/ccg:verify --gate=module`。本命令仍可用以保持 BC，将在 v5.0 移除。详见 .ccg-migration/DEPRECATIONS.md
+deprecation_message: 推荐使用 `/ccg:verify --gate=module`。本命令仍可用以保持 BC。详见 .ccg-migration/DEPRECATIONS.md
 ---
 
 # ⚖ 校验关卡 · 模块完整性

package/templates/skills/tools/verify-quality/SKILL.md

@@ -7,9 +7,9 @@ user-invocable: true
 disable-model-invocation: false
 allowed-tools: Bash, Read, Glob
 argument-hint: <扫描路径>
-deprecated_in: v4.0
+deprecated_in: 1.0.0
 replaced_by: /ccg:verify --gate=quality
-deprecation_message: v4.0+ 推荐使用 `/ccg:verify --gate=quality`。本命令仍可用以保持 BC，将在 v5.0 移除。详见 .ccg-migration/DEPRECATIONS.md
+deprecation_message: 推荐使用 `/ccg:verify --gate=quality`。本命令仍可用以保持 BC。详见 .ccg-migration/DEPRECATIONS.md
 ---
 
 # ⚖ 校验关卡 · 代码质量

package/templates/skills/tools/verify-security/SKILL.md

@@ -7,9 +7,9 @@ user-invocable: true
 disable-model-invocation: false
 allowed-tools: Bash, Read, Grep
 argument-hint: <扫描路径>
-deprecated_in: v4.0
+deprecated_in: 1.0.0
 replaced_by: /ccg:verify --gate=security
-deprecation_message: v4.0+ 推荐使用 `/ccg:verify --gate=security`。本命令仍可用以保持 BC，将在 v5.0 移除。详见 .ccg-migration/DEPRECATIONS.md
+deprecation_message: 推荐使用 `/ccg:verify --gate=security`。本命令仍可用以保持 BC。详见 .ccg-migration/DEPRECATIONS.md
 ---
 
 # ⚖ 校验关卡 · 安全校验