ccgx-workflow 2.3.0 → 2.4.1

package/templates/commands/spec-impl.md

@@ -124,7 +124,7 @@ The diff will be reviewed before apply; do not assume it's been applied.
    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 摘要。
    2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → fallback Bash 调用，**保留 Step 4 session resume** 以维持会话上下文。
 
-   **判定**：preflight `Bash` 跑 `ls ~/.claude/plugins/` 看有无 `codex@*` / `gemini@*` 子目录。
+   **判定**：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）。
 
    ⚠️ spec-impl 命令在主线 context 内，**允许** `Agent(...)`——与 subagent "禁止嵌套 spawn" 约束不冲突。
    ⚠️ **plugin 路径无 session resume 能力**：通道 A 不接 Step 4 的 SESSION_ID，review 任务作为独立无状态分析跑（review 是 read-only 审查，无需会话连续性）。
@@ -269,13 +269,77 @@ Return ≤200 token structured summary.
    - If below 80K: Ask user "Continue to next phase?"
    - If approaching 80K: Suggest "Run `/clear` and resume with `/ccg:spec:impl`"
 
-10. **Archive on Completion**
+10. **Spec Evolution (RFC-9) — 归档前的可复用约定提炼**
+
+    在调用 `/opsx:archive` **之前**，从本次 change 的 git diff + REVIEW.md
+    抽取**可复用的、非显而易见的约定**。这是上游 V3 phase-guide.md §8 在
+    fork 的对应实现，借 `src/utils/spec-suggestion.ts` helper 完成：
+
+    a. **采集原料**（在 change 目录跑）：
+       ```bash
+       BASE=$(git merge-base HEAD origin/main 2>/dev/null || git rev-parse HEAD~1)
+       git diff "$BASE"..HEAD > .context/tmp/spec-evo-diff.txt
+       # REVIEW.md 路径由 Step 7 的 review 阶段产出，约定在
+       # openspec/changes/<change-id>/REVIEW.md
+       ```
+
+    b. **调 helper CLI**（installer 安装到 `~/.claude/.ccg/scripts/spec-suggestion.cjs`，
+       零依赖 Node CJS。用户项目无需装 ccgx-workflow npm 包）：
+       ```bash
+       node ~/.claude/.ccg/scripts/spec-suggestion.cjs \
+         --diff .context/tmp/spec-evo-diff.txt \
+         --review openspec/changes/<change-id>/REVIEW.md \
+         --change-id <change-id> \
+         > .context/tmp/spec-evo-candidates.json
+       ```
+       stdout = JSON 数组 `[{statement, rationale, source, category, rejectionReason?}, ...]`
+       exit 0 = 跑完（包括空结果）；exit 1 = 文件读不到 / 参数错。
+
+    c. **解析 + 过滤 + 展示**：主线 Read `.context/tmp/spec-evo-candidates.json`，
+       按 `rejectionReason` 是否非空分两组：
+       - 全部 candidates 为空，或通过质量门的 `!c.rejectionReason` 都为 0 → **直接跳
+         到 Step 11**（无值得提炼，不强凑——这是 RFC-9 硬规约），并在主对话输出一句话：
+         "本次 Spec Evolution 无可复用约定，跳过 SPEC_EVOLUTION.md 创建。"
+       - 至少 1 个通过质量门 → 用 `AskUserQuestion` 列出 candidates（含 rejected 也展示
+         给用户审视，让用户看到 helper 拒了什么、为什么），用户**勾选**要保留的。
+
+    d. **写入**（仅用户勾选的条目）：主线用 Write 工具直接构造 SPEC_EVOLUTION.md
+       内容（按下方模板渲染），写到 `openspec/changes/<change-id>/SPEC_EVOLUTION.md`：
+
+       ```markdown
+       # Spec Evolution — <change-id>
+
+       > Captured <YYYY-MM-DD> during `/ccg:spec-impl` archive step.
+       > User-approved candidates only. Promote to `specs/<capability>/spec.md`
+       > via the next `/ccg:spec-research` iteration.
+
+       ## backend
+       - **<statement>**
+         - *Why*: <rationale>
+         - *Source*: <source.kind> — `<source.excerpt>`
+       ## frontend
+       ...
+       ## cross-cutting
+       ...
+       ```
+
+       按 candidate.category 分 backend / frontend / cross-cutting 三段（缺的段省略）。
+
+       **绝不**自动写入 `openspec/specs/` 主规范。SPEC_EVOLUTION.md 是"本次开发
+       学到的事"的审计文档，随 change 一起归档；提升为 `specs/<capability>/spec.md`
+       里的真正 SHALL 是下一轮 `/ccg:spec-research` 的工作。
+
+    e. **空跳**：通过质量门的 candidate 数 === 0 时**不创建** SPEC_EVOLUTION.md
+       （避免空文件污染归档）。在主对话输出一句话："本次 Spec Evolution 无可复用约定。"
+
+11. **Archive on Completion**
     - When ALL tasks in `tasks.md` are marked `[x]`:
     - Call `/opsx:archive` internally to archive the change:
       ```
       /opsx:archive
       ```
-    - This merges spec deltas to `openspec/specs/` and moves change to archive.
+    - This merges spec deltas to `openspec/specs/` and moves change (including
+      `SPEC_EVOLUTION.md` from Step 10, if any) to `changes/archive/`.
     - **Note**: This is an internal call. If archiving fails, guide the user to re-run `/ccg:spec-impl`.
 
 **Reference**
@@ -288,5 +352,6 @@ Implementation is complete when:
 - [ ] All tasks in `tasks.md` marked `[x]`
 - [ ] All multi-model reviews passed
 - [ ] Side-effect review confirmed no regressions
+- [ ] Spec Evolution step ran (either wrote SPEC_EVOLUTION.md or explicitly reported "no reusable conventions")
 - [ ] Change archived successfully
 <!-- CCG:SPEC:IMPL:END -->

package/templates/commands/spec-plan.md

@@ -32,7 +32,7 @@ description: '多模型分析 → 消除歧义 → 零决策可执行计划'
    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 摘要。
    2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → fallback Bash 调用，行为与 plugin 路径等价。
 
-   **判定**：preflight `Bash` 跑 `ls ~/.claude/plugins/` 看有无 `codex@*` / `gemini@*` 子目录。
+   **判定**：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）。
 
    ⚠️ spec-plan 命令在主线 context 内，**允许** `Agent(...)`——与 subagent "禁止嵌套 spawn" 约束不冲突。
 

package/templates/commands/spec-research.md

@@ -57,7 +57,7 @@ description: '需求 → 约束集（并行探索 + OPSX 提案）'
    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 摘要。
    2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → fallback Bash 调用，行为与 plugin 路径等价。
 
-   **判定**：preflight `Bash` 跑 `ls ~/.claude/plugins/` 看有无 `codex@*` / `gemini@*` 子目录。
+   **判定**：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）。
 
    ⚠️ spec-research 命令在主线 context 内，**允许** `Agent(...)`——与 subagent "禁止嵌套 spawn" 约束不冲突。
 

package/templates/commands/spec-review.md

@@ -33,7 +33,7 @@ description: '双模型交叉审查（独立工具，随时可用）'
    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 摘要。
    2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → fallback Bash 调用，行为与 plugin 路径等价。
 
-   **判定**：preflight `Bash` 跑 `ls ~/.claude/plugins/` 看有无 `codex@*` / `gemini@*` 子目录。
+   **判定**：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）。
 
    ⚠️ spec-review 命令在主线 context 内，**允许** `Agent(...)`——与 subagent "禁止嵌套 spawn" 约束不冲突。
 

package/templates/commands/team.md

@@ -164,7 +164,7 @@ Phase 8: INTEGRATION   → Lead 全量验证 + 报告 + 清理
    1. **优先 plugin spawn**（默认）：装了 `codex@openai-codex` + gemini plugin → 用 `Agent(subagent_type="codex:codex-rescue")` + `Agent(subagent_type="gemini:gemini-rescue")` 并行，主线接 ≤200 token 摘要。
    2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → fallback Bash 调用，行为与 plugin 路径等价。
 
-   **判定**：preflight `Bash` 跑 `ls ~/.claude/plugins/` 看有无 `codex@*` / `gemini@*` 子目录。
+   **判定**：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）。
 
    - **CRITICAL**: 必须在一条消息中同时发起两个并行调用。
 

package/templates/commands/test.md

@@ -47,7 +47,7 @@ CCG 把双模型并行通道从 `Bash(codeagent-wrapper)` **默认切换**为 pl
 1. **优先 plugin spawn**（默认）：装了 `codex@openai-codex` + `gemini@google-gemini` plugin → 用 `Agent(subagent_type="codex:codex-rescue")` + `Agent(subagent_type="gemini:gemini-rescue")` 并行，主线接 ≤200 token 摘要。
 2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → fallback 到 Bash 调用，行为与 plugin 路径等价。
 
-**判定**：preflight `Bash` 跑 `ls ~/.claude/plugins/` 看有无 `codex@*` / `gemini@*` 子目录。helper 见 `src/utils/plugin-detection.ts`。
+**判定**：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）。
 
 ⚠️ Test 命令在主线 context 内，**允许** `Agent(...)`——与 subagent "禁止嵌套 spawn" 约束不冲突。
 

package/templates/commands/workflow.md

@@ -44,7 +44,7 @@ subagent_freshness: required
 1. **优先 plugin spawn**（默认）：plugin 已装 → `Agent(subagent_type="<codex:codex-rescue|gemini:gemini-rescue>")`。session 复用通过 prompt 内 `--resume` flag 表达（subagent 映射为 codex/gemini `--resume-last`，**注意是 last，不是 by-id**）。
 2. **降级 codeagent-wrapper**（BC fallback）：plugin 未装 → Bash 调用，保留 `resume <SESSION_ID>` 显式会话管理。
 
-**判定**：preflight `Bash` 跑 `ls ~/.claude/plugins/` 看有无 `codex@*` / `gemini@*` 子目录。
+**判定**：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）。
 
 ---
 

package/templates/hooks/ccg-loop-detector.cjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// CCG Loop Detector Hook — UserPromptSubmit
+//
+// Detects when the user is stuck describing the same problem turn after turn
+// (typical signs: model gave a wrong answer, user re-phrases the question,
+// model gives a similar wrong answer, repeat). Emits a `LOOP DETECTED` warning
+// into the model's additionalContext along with a break-loop protocol, so the
+// next reply is forced to step back rather than re-attempt the same approach.
+//
+// Why this hook lives in fork-land (not just porting upstream's workflow-state.js):
+//   - Upstream binds loop detection to .ccg/tasks/{id}/task.json — the V3
+//     intent-driven engine that fork does not adopt.
+//   - Fork's task state lives in .ccg/roadmap.md (milestone) + .ccg/state.md
+//     (wave). Those are coarse — they don't change per-turn.
+//   - The actual signal we can read every turn is the user's own prompt.
+//     Repeated near-identical prompts within a short window are a strong loop
+//     indicator regardless of what the orchestrator is doing internally.
+//
+// State file: <workdir>/.ccg/.turns.json   (kept tiny: last 5 turns only)
+//
+// Performance budget: <50 ms hot path. Hook fires every UserPromptSubmit; if
+// anything throws we exit 0 silently so the user message is never blocked.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STATE_FILE = path.join('.ccg', '.turns.json');
+const MAX_TURNS = 5;             // sliding window
+const LOOP_THRESHOLD = 3;        // 3 similar in a row → loop
+// Bound the state-file read. .turns.json holds at most MAX_TURNS rows of
+// fp+ts (~280B each), so anything beyond 64KB is corrupt or malicious.
+// Matches the budget used by ccg-stop-gate.cjs for the same reason.
+const MAX_STATE_FILE_BYTES = 64 * 1024;
+// Threshold tuned for character-bigram Jaccard. Empirically:
+//   "fix login bug"  vs "fix login bug please" → ~0.67
+//   "fix login bug"  vs "fix login bug now"    → ~0.69
+//   "帮我修登录的错误" vs "帮我修一下登录的错误" → ~0.60
+//   unrelated English prompts                  → < 0.15
+//   unrelated CJK prompts                      → < 0.20
+// 0.55 catches re-phrasings of the same ask in both scripts while staying
+// well above the unrelated-pair floor.
+const SIMILARITY_THRESHOLD = 0.55;
+const WINDOW_MS = 10 * 60 * 1000;// ignore matches > 10 min apart
+const PROMPT_FINGERPRINT_LEN = 240;
+
+function readJsonSafe(p) {
+  try {
+    // Bounded read so a corrupt 100MB .turns.json doesn't wedge the prompt path.
+    const st = fs.statSync(p);
+    if (!st.isFile() || st.size > MAX_STATE_FILE_BYTES) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  }
+  catch {
+    return null;
+  }
+}
+
+function writeJsonSafe(p, data) {
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(data), 'utf-8');
+  }
+  catch {
+    // Hook must never fail loudly.
+  }
+}
+
+// Cheap fingerprint: lowercased, whitespace-collapsed, truncated.
+// Long enough to capture meaningful overlap; short enough to keep .turns.json tiny.
+function fingerprint(prompt) {
+  if (typeof prompt !== 'string') return '';
+  return prompt.toLowerCase().replace(/\s+/g, ' ').trim().slice(0, PROMPT_FINGERPRINT_LEN);
+}
+
+// Character-bigram set. Works across scripts:
+//   - English: "fix login bug" → {"fi","ix","x ", " l", ...}
+//   - CJK:     "帮我修登录"     → {"帮我","我修","修登","登录"}
+// Word-level tokenization is a non-starter for CJK (no whitespace separators).
+// Bigrams give us a script-agnostic signal at the cost of a slightly noisier
+// floor (~0.15 for unrelated English, ~0.20 for unrelated CJK) which we
+// absorbed when tuning SIMILARITY_THRESHOLD.
+function bigrams(s) {
+  const out = new Set();
+  if (!s || s.length < 2) return out;
+  for (let i = 0; i < s.length - 1; i++) {
+    out.add(s.slice(i, i + 2));
+  }
+  return out;
+}
+
+function jaccard(a, b) {
+  if (!a || !b) return 0;
+  const A = bigrams(a);
+  const B = bigrams(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let intersection = 0;
+  for (const t of A) if (B.has(t)) intersection++;
+  const union = A.size + B.size - intersection;
+  return intersection / union;
+}
+
+function detectLoop(turns) {
+  if (turns.length < LOOP_THRESHOLD) return null;
+  const recent = turns.slice(-LOOP_THRESHOLD);
+  const oldest = recent[0];
+  const newest = recent[recent.length - 1];
+  if (newest.ts - oldest.ts > WINDOW_MS) return null;
+
+  // Pairwise similarity must clear threshold for every consecutive pair.
+  // This is stricter than "average" — one outlier breaks the loop call,
+  // which is what we want (avoids false-positives on "good question, follow-up").
+  for (let i = 1; i < recent.length; i++) {
+    if (jaccard(recent[i - 1].fp, recent[i].fp) < SIMILARITY_THRESHOLD) {
+      return null;
+    }
+  }
+
+  return {
+    count: recent.length,
+    elapsedSec: Math.round((newest.ts - oldest.ts) / 1000),
+    fingerprint: oldest.fp.slice(0, 80),
+  };
+}
+
+// Compose the additionalContext payload. The 5-step break-loop protocol is
+// adapted from upstream's workflow-state.js but oriented at the user-prompt
+// signal instead of phase+nextAction state.
+function composeWarning(loop) {
+  return [
+    '<ccg-loop-warning>',
+    `⚠️ LOOP DETECTED — same/similar user prompt repeated ${loop.count} turns within ${loop.elapsedSec}s.`,
+    `Sample: "${loop.fingerprint}..."`,
+    '',
+    '🔄 BREAK-LOOP PROTOCOL (apply before answering this turn):',
+    '  1. STOP. Do not re-attempt the previous approach.',
+    '  2. Re-read the user message looking for what you missed (a constraint? a file path? a "no" you treated as "maybe"?).',
+    '  3. State, in one sentence, why your previous answer did not satisfy the user.',
+    '  4. Pick a different approach OR ask one specific clarifying question (not "what do you mean") if you cannot diagnose the miss.',
+    '  5. If you suspect an external blocker (missing creds, broken tool, unsupported feature), say so explicitly — do not loop on it.',
+    '</ccg-loop-warning>',
+  ].join('\n');
+}
+
+function readInput() {
+  // SessionStart / UserPromptSubmit pass JSON on stdin. We only need .prompt
+  // and .cwd. Failing to read is fine — we exit 0 silently.
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf-8');
+  }
+  catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw || '{}');
+  }
+  catch {
+    return null;
+  }
+}
+
+function main() {
+  const input = readInput();
+  if (!input) {
+    process.exit(0);
+    return;
+  }
+
+  const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+  if (!prompt) {
+    process.exit(0);
+    return;
+  }
+
+  // CCG state lives under the project root. Use the cwd Claude Code passed in;
+  // fall back to process.cwd() (which Claude Code sets for the hook anyway).
+  const cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd();
+  const statePath = path.join(cwd, STATE_FILE);
+
+  const fp = fingerprint(prompt);
+  if (!fp) {
+    process.exit(0);
+    return;
+  }
+
+  const existing = readJsonSafe(statePath);
+  // Filter out malformed turn objects (e.g. corrupted via hand edit, partial
+  // write). Without this a missing/non-numeric ts becomes NaN inside detectLoop
+  // and produces silent false negatives instead of just dropping the bad row.
+  const turns = (Array.isArray(existing) ? existing : []).filter(
+    (t) => t && typeof t.fp === 'string' && typeof t.ts === 'number' && Number.isFinite(t.ts),
+  );
+  turns.push({ fp, ts: Date.now() });
+  if (turns.length > MAX_TURNS) {
+    turns.splice(0, turns.length - MAX_TURNS);
+  }
+  writeJsonSafe(statePath, turns);
+
+  const loop = detectLoop(turns);
+  if (!loop) {
+    process.exit(0);
+    return;
+  }
+
+  // Emit the warning. Same envelope shape as other CCG hooks.
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: composeWarning(loop),
+    },
+  }));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+// Exported for unit tests (loaded via createRequire from .ts).
+module.exports = {
+  fingerprint,
+  jaccard,
+  detectLoop,
+  composeWarning,
+  // Constants exported so tests can document the contract.
+  LOOP_THRESHOLD,
+  WINDOW_MS,
+  SIMILARITY_THRESHOLD,
+  MAX_TURNS,
+};

package/templates/hooks/ccg-skill-router.cjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// CCG Skill Router Hook — UserPromptSubmit
+//
+// When the user's message contains domain keywords (e.g. "SQLi", "Kubernetes",
+// "RAG"), inject a short additionalContext that names the relevant skill file
+// the model should Read before answering.
+//
+// Why this is a hook rather than relying on rules/ccg-skill-routing.md alone:
+//   - The rules file is a passive document. The model has to remember to
+//     consult it, and in practice it often answers from training data without
+//     reading the domain skill (false-positives in security/architecture/AI
+//     advice are the typical failure mode).
+//   - This hook runs deterministically on every prompt and surfaces the exact
+//     path inline, so the model doesn't have to find it. Token cost is ~50
+//     per match — much cheaper than the wrong answer it prevents.
+//
+// Design choices that diverge from upstream skill-router.js:
+//   - We DO NOT inject the file content. Upstream slices the first ~120 lines
+//     and ships them in context. That bloats every prompt that matches a
+//     keyword. We just point at the path and let the model Read on demand.
+//   - We DO NOT spawn external models from this hook. Upstream uses keyword
+//     phrases like "用 codex 审查" to autoexecute the codeagent-wrapper.
+//     Fork's plugin-spawn architecture would conflict with that path.
+//
+// Performance budget: <30 ms. Hook fires every UserPromptSubmit.
+
+'use strict';
+
+const fs = require('node:fs');
+
+// Routing table mirrors templates/rules/ccg-skill-routing.md. Keep them in
+// sync — the rules file is for human reference, this hook is what actually
+// fires. Keywords are matched case-insensitively as substrings.
+//
+// Match shape: { keywords: [...], skill: '<relative path under skills/ccg/>', label: '<human-readable>' }
+const ROUTES = [
+  // ── Security ──
+  { keywords: ['pentest', 'red team', '红队', '渗透', 'exploit', 'c2', 'lateral movement', 'privilege escalation', '提权', 'evasion', 'persistence', '免杀', '持久化'],
+    skill: 'domains/security/red-team.md', label: 'Red Team' },
+  { keywords: ['blue team', '蓝队', 'incident response', '应急', 'ioc', 'siem', 'edr', '取证', 'forensics', 'containment'],
+    skill: 'domains/security/blue-team.md', label: 'Blue Team' },
+  { keywords: ['sqli', 'sql injection', 'xss', 'ssrf', 'rce', 'owasp', 'web pentest', 'api security', 'injection'],
+    skill: 'domains/security/pentest.md', label: 'Web Pentest' },
+  { keywords: ['code audit', '代码审计', 'taint analysis', '污点分析', 'sink', 'dangerous function', '危险函数'],
+    skill: 'domains/security/code-audit.md', label: 'Code Audit' },
+  { keywords: ['binary', 'reversing', '逆向', 'pwn', 'fuzzing', 'stack overflow', 'heap overflow', '栈溢出', '堆溢出', 'rop'],
+    skill: 'domains/security/vuln-research.md', label: 'Vuln Research' },
+  { keywords: ['osint', 'threat intelligence', '威胁情报', 'threat modeling', '威胁建模', 'att&ck', 'threat hunting'],
+    skill: 'domains/security/threat-intel.md', label: 'Threat Intel' },
+
+  // ── Architecture ──
+  { keywords: ['api design', 'api 设计', 'rest', 'graphql', 'grpc', 'endpoint', 'versioning'],
+    skill: 'domains/architecture/api-design.md', label: 'API Design' },
+  { keywords: ['caching', '缓存', 'redis', 'memcached', 'cache invalidation', 'cdn'],
+    skill: 'domains/architecture/caching.md', label: 'Caching' },
+  { keywords: ['cloud native', '云原生', 'kubernetes', 'k8s', 'docker', 'microservice', '微服务', 'service mesh'],
+    skill: 'domains/architecture/cloud-native.md', label: 'Cloud Native' },
+  { keywords: ['message queue', '消息队列', 'kafka', 'rabbitmq', 'event driven', 'pub/sub'],
+    skill: 'domains/architecture/message-queue.md', label: 'Message Queue' },
+  { keywords: ['security architecture', '安全架构', 'zero trust', 'defense in depth', 'iam'],
+    skill: 'domains/architecture/security-arch.md', label: 'Security Arch' },
+
+  // ── AI / MLOps ──
+  { keywords: ['rag', 'retrieval augmented', '检索增强', 'vector database', 'embedding', 'chunking'],
+    skill: 'domains/ai/rag-system.md', label: 'RAG System' },
+  { keywords: ['ai agent', 'tool use', 'function calling', 'agent framework', 'orchestration'],
+    skill: 'domains/ai/agent-dev.md', label: 'Agent Dev' },
+  { keywords: ['llm security', 'prompt injection', 'jailbreak', 'guardrail'],
+    skill: 'domains/ai/llm-security.md', label: 'LLM Security' },
+  { keywords: ['prompt engineering', 'model evaluation', 'benchmark', 'fine-tuning'],
+    skill: 'domains/ai/prompt-and-eval.md', label: 'Prompt & Eval' },
+
+  // ── DevOps ──
+  { keywords: ['git workflow', 'branching strategy', 'trunk-based', 'gitflow'],
+    skill: 'domains/devops/git-workflow.md', label: 'Git Workflow' },
+  { keywords: ['testing strategy', 'unit test', 'integration test', 'e2e', 'test pyramid'],
+    skill: 'domains/devops/testing.md', label: 'Testing' },
+  { keywords: ['database migration', 'schema design', 'indexing', 'query optimization'],
+    skill: 'domains/devops/database.md', label: 'Database' },
+  { keywords: ['profiling', 'load test', 'latency', 'throughput', 'performance tuning'],
+    skill: 'domains/devops/performance.md', label: 'Performance' },
+  { keywords: ['observability', 'logging', 'tracing', 'metrics', 'prometheus', 'grafana'],
+    skill: 'domains/devops/observability.md', label: 'Observability' },
+  { keywords: ['devsecops', 'ci security', 'sast', 'dast', 'supply chain'],
+    skill: 'domains/devops/devsecops.md', label: 'DevSecOps' },
+  { keywords: ['cost optimization', 'cloud cost', 'finops', 'right-sizing'],
+    skill: 'domains/devops/cost-optimization.md', label: 'Cost Optimization' },
+
+  // ── Frontend Design (only style packs; basic UI is too noisy to match) ──
+  { keywords: ['claymorphism'], skill: 'domains/frontend-design/claymorphism/SKILL.md', label: 'Claymorphism' },
+  { keywords: ['glassmorphism'], skill: 'domains/frontend-design/glassmorphism/SKILL.md', label: 'Glassmorphism' },
+  { keywords: ['liquid glass'], skill: 'domains/frontend-design/liquid-glass/SKILL.md', label: 'Liquid Glass' },
+  { keywords: ['neubrutalism'], skill: 'domains/frontend-design/neubrutalism/SKILL.md', label: 'Neubrutalism' },
+];
+
+const MAX_INJECTIONS = 2; // cap on matched skills per prompt to keep context tight
+
+// Short keyword cutoff (ASCII). ASCII keywords shorter than this length MUST
+// use a word-boundary regex to avoid catastrophic false positives. Empirically:
+//   'rag'  → "drag/fragment/Bragg"           (3 chars)
+//   'rest' → "restart/rest assured/interest" (4 chars)
+//   'rce'  → "service/source"                (3 chars)
+//   'route' → "rerouted"                     (5 chars but unambiguous as a word)
+// Cutoff = 5 catches all the painful ones while letting actual nouns ('route',
+// 'redis', 'cache', etc.) take the cheap substring path.
+const SHORT_KW_CUTOFF = 5;
+
+// CJK keywords are a different problem space. There is no formal word
+// boundary in CJK writing — '红队' next to '员' produces '红队员' (a real
+// compound noun), but the user query '我想做一次红队演练' also has '红队'
+// next to a CJK char ('次' before, '演' after). A boundary regex anchored on
+// \P{L} would reject BOTH cases identically, killing legitimate matches.
+//
+// We accept the cost: CJK keywords always take the substring path. In
+// practice CJK queries are more topical and less likely to produce ASCII-style
+// homograph collisions, so substring false-positive rate on CJK stays low.
+function hasCjk(s) {
+  return /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u.test(s);
+}
+
+/**
+ * Returns true iff `kw` appears in `prompt` as a stand-alone token (ASCII)
+ * or as a substring (CJK).
+ *
+ * Regex objects are cached per keyword — the hook runs on every
+ * UserPromptSubmit and building these on the hot path would be wasteful.
+ */
+const KW_REGEX_CACHE = new Map();
+function matchKeyword(prompt, kw) {
+  if (!kw) return false;
+  const lowerPrompt = prompt.toLowerCase();
+  const lowerKw = kw.toLowerCase();
+  // CJK short keywords: substring path (boundary makes no sense — see above).
+  // Long keywords (>= cutoff): substring is safe enough.
+  if (hasCjk(lowerKw) || lowerKw.length >= SHORT_KW_CUTOFF) {
+    return lowerPrompt.includes(lowerKw);
+  }
+  // ASCII short keyword: word-boundary regex.
+  let re = KW_REGEX_CACHE.get(lowerKw);
+  if (!re) {
+    // Escape regex metachars in the keyword (handles 'c2', 'pub/sub', etc.).
+    const esc = lowerKw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Boundary = position whose neighboring char is NOT a letter or digit
+    // (Unicode-aware). Start/end of string are also valid boundaries.
+    re = new RegExp(`(?:^|[^\\p{L}\\p{N}])${esc}(?:$|[^\\p{L}\\p{N}])`, 'iu');
+    KW_REGEX_CACHE.set(lowerKw, re);
+  }
+  return re.test(lowerPrompt);
+}
+
+function readInput() {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf-8');
+  }
+  catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw || '{}');
+  }
+  catch {
+    return null;
+  }
+}
+
+function findMatches(prompt) {
+  const text = prompt || '';
+  if (text.length < 5) return [];
+  const seen = new Set();
+  const matches = [];
+  for (const route of ROUTES) {
+    if (seen.has(route.skill)) continue;
+    if (route.keywords.some(kw => matchKeyword(text, kw))) {
+      matches.push(route);
+      seen.add(route.skill);
+      if (matches.length >= MAX_INJECTIONS) break;
+    }
+  }
+  return matches;
+}
+
+function composePointer(matches, skillsBase) {
+  // Output format intentionally short. The model only needs the path; reading
+  // the file is its job, not the hook's.
+  const lines = ['<ccg-domain-routing>'];
+  lines.push('The user\'s prompt mentions a domain that CCG has authoritative reference material for.');
+  lines.push('Read the file(s) below BEFORE answering — do not rely on training-data recall for these topics.');
+  lines.push('');
+  for (const m of matches) {
+    lines.push(`- ${m.label}: ${skillsBase}/${m.skill}`);
+  }
+  lines.push('</ccg-domain-routing>');
+  return lines.join('\n');
+}
+
+function main() {
+  const input = readInput();
+  if (!input) {
+    process.exit(0);
+    return;
+  }
+  const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+  if (!prompt) {
+    process.exit(0);
+    return;
+  }
+
+  const matches = findMatches(prompt);
+  if (matches.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  // Resolve skills directory once. We point at the user-facing install path
+  // (~/.claude/skills/ccg) rather than checking it exists — if the user
+  // uninstalled the skills, the model's Read will fail loudly and we surface
+  // that, which is preferable to silently swallowing the routing.
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+  if (!homeDir) {
+    // Stripped CI container / minimal Docker image with no HOME or USERPROFILE.
+    // Skip the injection entirely — pointing at '/.claude/skills/ccg' would be
+    // worse than nothing (the model would Read a path that cannot exist).
+    process.exit(0);
+    return;
+  }
+  const skillsBase = `${homeDir.replace(/\\/g, '/')}/.claude/skills/ccg`;
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: composePointer(matches, skillsBase),
+    },
+  }));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  findMatches,
+  composePointer,
+  matchKeyword,
+  ROUTES,
+  MAX_INJECTIONS,
+  SHORT_KW_CUTOFF,
+};