ccgx-workflow 2.3.0 → 2.4.1

package/templates/hooks/ccg-stop-gate.cjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// CCG Stop Gate Hook — Stop / SubagentStop
+//
+// When Claude is about to end its turn, check whether there are still
+// active background tasks the user expects to finish. Emit a warning into
+// additionalContext so the model does not falsely claim "done" while:
+//   - a CCG job (.context/jobs/<id>/state.json) is still queued/running
+//   - Claude Code's own harness reports background_tasks (added in 2.1.145)
+//
+// Why this matters: fork's async trio (status/result/cancel) and
+// phase-runner-launcher wrap codex/gemini calls in long-lived OS subprocesses.
+// Without this hook, the main thread frequently said "✅ complete" while a
+// launcher was still mid-task. Users had to keep checking /ccg:status.
+//
+// Design choices:
+//   - Warn, never block. Setting `decision: "block"` would force the model to
+//     keep working, which is the wrong tool when the user explicitly said
+//     "stop" or when the model finished its main answer and the background
+//     task is fire-and-forget. We surface the info; the model decides.
+//   - Source-of-truth merge: harness-reported background_tasks ∪ CCG jobs.
+//     The two sets overlap heavily but neither is a superset. Harness sees
+//     bash run_in_background processes; CCG sees its own job registry.
+//   - Bounded scan: list the .context/jobs/ directory but never read a file
+//     bigger than 64 KB. Performance must not regress.
+//
+// Performance budget: <100 ms even with many jobs. Hook runs on every Stop.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const JOBS_SUBDIR = path.join('.context', 'jobs');
+const ACTIVE_STATUSES = new Set(['queued', 'running']);
+const MAX_STATE_FILE_BYTES = 64 * 1024;
+const MAX_REPORT_JOBS = 5; // truncate to keep additionalContext tight
+
+function readInput() {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf-8');
+  }
+  catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw || '{}');
+  }
+  catch {
+    return null;
+  }
+}
+
+function readJobState(stateFile) {
+  try {
+    const stat = fs.statSync(stateFile);
+    if (!stat.isFile() || stat.size > MAX_STATE_FILE_BYTES) return null;
+    const raw = fs.readFileSync(stateFile, 'utf-8');
+    return JSON.parse(raw);
+  }
+  catch {
+    return null;
+  }
+}
+
+// Returns array of { jobId, status, phase, summary, sourcedFrom: 'ccg-jobs' }.
+function scanCcgJobs(cwd) {
+  const jobsDir = path.join(cwd, JOBS_SUBDIR);
+  let entries;
+  try {
+    entries = fs.readdirSync(jobsDir, { withFileTypes: true });
+  }
+  catch {
+    return [];
+  }
+  const active = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const jobId = entry.name;
+    const state = readJobState(path.join(jobsDir, jobId, 'state.json'));
+    if (!state || typeof state.status !== 'string') continue;
+    if (!ACTIVE_STATUSES.has(state.status)) continue;
+    active.push({
+      jobId,
+      status: state.status,
+      phase: typeof state.phase === 'string' ? state.phase : null,
+      summary: typeof state.summary === 'string' ? state.summary.slice(0, 120) : null,
+      sourcedFrom: 'ccg-jobs',
+    });
+  }
+  return active;
+}
+
+// Normalize harness-supplied background_tasks (field shape added in CC 2.1.145).
+// Shape is best-effort: we accept either an array of strings (task ids) or an
+// array of objects with at minimum a `task_id` or `id` field.
+function normalizeHarnessTasks(input) {
+  const raw = input && input.background_tasks;
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const item of raw) {
+    if (typeof item === 'string') {
+      out.push({ jobId: item, status: 'unknown', phase: null, summary: null, sourcedFrom: 'harness' });
+    }
+    else if (item && typeof item === 'object') {
+      const jobId = item.task_id || item.id || item.name || '(unnamed)';
+      const status = typeof item.status === 'string' ? item.status : 'unknown';
+      out.push({
+        jobId,
+        status,
+        phase: typeof item.phase === 'string' ? item.phase : null,
+        summary: typeof item.description === 'string' ? item.description.slice(0, 120) : null,
+        sourcedFrom: 'harness',
+      });
+    }
+  }
+  return out;
+}
+
+function mergeTasks(ccgJobs, harnessTasks) {
+  // Dedupe by jobId across the two sources (CCG jobs win on conflict because
+  // their status is authoritative — harness only knows "active").
+  const seen = new Set();
+  const merged = [];
+  for (const j of ccgJobs) {
+    seen.add(j.jobId);
+    merged.push(j);
+  }
+  for (const h of harnessTasks) {
+    if (seen.has(h.jobId)) continue;
+    merged.push(h);
+  }
+  return merged;
+}
+
+function composeWarning(eventName, tasks) {
+  const limited = tasks.slice(0, MAX_REPORT_JOBS);
+  const omitted = tasks.length - limited.length;
+  const lines = ['<ccg-stop-gate>'];
+  lines.push(`⚠️ ${tasks.length} background task(s) still active at ${eventName}.`);
+  lines.push('Do not declare the user-facing work "complete" until these settle.');
+  lines.push('Options: tell the user "background X is still running, check /ccg:status <id>", or wait and re-summarize.');
+  lines.push('');
+  for (const t of limited) {
+    const phase = t.phase ? ` phase=${t.phase}` : '';
+    const summary = t.summary ? ` — ${t.summary}` : '';
+    lines.push(`- ${t.jobId} [${t.status}, ${t.sourcedFrom}]${phase}${summary}`);
+  }
+  if (omitted > 0) {
+    lines.push(`- ... ${omitted} more (truncated)`);
+  }
+  lines.push('</ccg-stop-gate>');
+  return lines.join('\n');
+}
+
+function detectEvent(input) {
+  // Claude Code Stop/SubagentStop payloads carry the event name in
+  // `hook_event_name`. Default to 'Stop' if absent — the model treats the two
+  // identically, this only affects the echoed hookEventName field in our
+  // response envelope.
+  if (input && typeof input.hook_event_name === 'string') {
+    if (input.hook_event_name === 'SubagentStop') return 'SubagentStop';
+  }
+  return 'Stop';
+}
+
+function main() {
+  const input = readInput();
+  const cwd = (input && typeof input.cwd === 'string' && input.cwd) ? input.cwd : process.cwd();
+  const eventName = detectEvent(input);
+
+  const ccgJobs = scanCcgJobs(cwd);
+  const harnessTasks = normalizeHarnessTasks(input);
+  const merged = mergeTasks(ccgJobs, harnessTasks);
+
+  if (merged.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: composeWarning(eventName, merged),
+    },
+  }));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  scanCcgJobs,
+  normalizeHarnessTasks,
+  mergeTasks,
+  composeWarning,
+  detectEvent,
+  ACTIVE_STATUSES,
+  MAX_REPORT_JOBS,
+};

package/templates/scripts/check-plugins.cjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// CCG plugin detection helper (v2.3.1+)
+//
+// Reads Claude Code's authoritative plugin registry at
+// ~/.claude/plugins/installed_plugins.json and reports whether the
+// codex and gemini plugins required by ccgx Channel A (plugin spawn)
+// are registered.
+//
+// Exit codes:
+//   0 = both plugins ok (use Channel A)
+//   1 = at least one missing (use Channel B / wrapper BC fallback)
+//   2 = registry missing or unparsable (use Channel B)
+//
+// stdout (single line JSON):
+//   {"codex": "<version>"|null, "gemini": "<version>"|null, "error"?: "<msg>"}
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const registryPath = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+
+function emit(payload, exitCode) {
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(exitCode);
+}
+
+try {
+  if (!fs.existsSync(registryPath)) {
+    emit({ codex: null, gemini: null, error: 'registry-missing' }, 2);
+  }
+
+  const raw = fs.readFileSync(registryPath, 'utf8');
+  const data = JSON.parse(raw);
+  const plugins = (data && data.plugins) || {};
+
+  const codexKey = Object.keys(plugins).find((k) => k.startsWith('codex@'));
+  const geminiKey = Object.keys(plugins).find((k) => k.startsWith('gemini@'));
+
+  const codexEntry = codexKey ? plugins[codexKey] : null;
+  const geminiEntry = geminiKey ? plugins[geminiKey] : null;
+
+  const codex = Array.isArray(codexEntry) && codexEntry[0] ? (codexEntry[0].version || 'unknown') : null;
+  const gemini = Array.isArray(geminiEntry) && geminiEntry[0] ? (geminiEntry[0].version || 'unknown') : null;
+
+  emit({ codex, gemini }, codex && gemini ? 0 : 1);
+} catch (e) {
+  emit({ codex: null, gemini: null, error: String(e && e.message || e) }, 2);
+}

package/templates/scripts/spec-suggestion.cjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+// CCG Spec Suggestion CLI — RFC-9 F2 follow-up.
+//
+// Standalone Node CJS reimplementation of src/utils/spec-suggestion.ts. The
+// TS version lives in CCG's own dist and is great for the `ccgx-workflow`
+// package consumers; but `/ccg:spec-impl` runs in the USER's project, which
+// generally has no dependency on ccgx-workflow. The model can't `import` a
+// helper that isn't installed.
+//
+// installer.ts copies this file to ~/.claude/.ccg/scripts/spec-suggestion.cjs
+// (alongside check-plugins.cjs and friends). The spec-impl.md step calls:
+//
+//   node ~/.claude/.ccg/scripts/spec-suggestion.cjs \
+//     --diff <path-to-diff>   \
+//     --review <path-to-review-md> \
+//     --change-id <id>
+//
+// stdout = JSON array of candidates (same shape as TS SpecCandidate[]).
+// exit 0 = ran (including empty result).
+// exit 1 = bad args / read failure / internal error.
+//
+// Logic must stay in lockstep with src/utils/spec-suggestion.ts. The shared
+// test cases in __tests__/specSuggestionCjs.test.ts pin both implementations
+// against the same fixtures.
+
+'use strict';
+
+const fs = require('node:fs');
+
+// ─────────────────────────────────────────────────────────────────
+// Constants (must mirror spec-suggestion.ts)
+// ─────────────────────────────────────────────────────────────────
+const MIN_RATIONALE_CHARS = 40;
+const MAX_STATEMENT_CHARS = 200;
+
+const FILLER_PHRASES = [
+  '写好的代码',
+  '注意安全',
+  '小心',
+  '保持代码整洁',
+  '遵循最佳实践',
+  '请仔细审查',
+  'best practice',
+  'be careful',
+  'write good code',
+  'clean code',
+  'follow best practices',
+];
+
+const SPECIFIC_REFERENCE_PATTERN = /(?:[a-zA-Z0-9_-]+\.[a-zA-Z]{1,8}\b|\w+\/\w+|\b[A-Z][a-zA-Z0-9]{2,}\b|`[^`]+`)/;
+
+const CATEGORY_HINTS = [
+  { kw: /\b(api|endpoint|route|router|middleware|jwt|oauth|session|cookie|sql|schema|migration|database|orm|prisma|drizzle|knex|graphql|grpc|kafka|redis)\b/i, category: 'backend' },
+  { kw: /\b(component|hook|jsx|tsx|css|tailwind|store|reducer|redux|zustand|pinia|router\.(get|push)|route|svelte|vue|react)\b/i, category: 'frontend' },
+  { kw: /(?:认证|授权|加密|后端|接口|数据库|迁移)/, category: 'backend' },
+  { kw: /(?:前端|组件|页面|样式|交互|路由跳转)/, category: 'frontend' },
+];
+
+// ─────────────────────────────────────────────────────────────────
+// Pure helpers
+// ─────────────────────────────────────────────────────────────────
+
+function categorizeStatement(statement, rationale) {
+  const haystack = `${statement} ${rationale}`;
+  for (const hint of CATEGORY_HINTS) {
+    if (hint.kw.test(haystack)) return hint.category;
+  }
+  return 'cross-cutting';
+}
+
+function checkQuality(statement, rationale) {
+  if (!statement || statement.length < 10) return 'statement too short (< 10 chars)';
+  if (statement.length > MAX_STATEMENT_CHARS) return `statement too long (> ${MAX_STATEMENT_CHARS} chars) — break it down`;
+  if (rationale.length < MIN_RATIONALE_CHARS) return `rationale too thin (< ${MIN_RATIONALE_CHARS} chars) — explain *why*`;
+  const lower = `${statement} ${rationale}`.toLowerCase();
+  for (const filler of FILLER_PHRASES) {
+    if (lower.includes(filler.toLowerCase())) return `filler phrase detected: "${filler}"`;
+  }
+  if (!SPECIFIC_REFERENCE_PATTERN.test(`${statement} ${rationale}`)) {
+    return 'no specific file / API / command reference — add a concrete anchor';
+  }
+  return undefined;
+}
+
+function extractFromReview(reviewMd) {
+  const out = [];
+  const findingRe = /^[#\-*\s]*(?:Finding\s+)?[CW]-?\d+\b[^\n]*(?:Critical|Warning|critical|warning)[^\n]*$/gm;
+  let match;
+  while ((match = findingRe.exec(reviewMd)) !== null) {
+    const start = match.index;
+    const tail = reviewMd.slice(start, start + 1200);
+    const lines = tail.split('\n').slice(0, 12);
+    const header = lines[0].trim();
+    const body = lines.slice(1).join(' ').replace(/\s+/g, ' ').trim();
+    const sugMatch = body.match(/(?:建议[：:]|Suggested(?:\s+fix)?[：:]|应当?[：:]|Must[：:]|Should[：:])\s*([^\.。;；]+)/i);
+    const statement = (sugMatch && sugMatch[1] ? sugMatch[1] : header).slice(0, MAX_STATEMENT_CHARS).trim();
+    const rationale = body.slice(0, 400).trim();
+    const category = categorizeStatement(statement, rationale);
+    out.push({
+      statement,
+      rationale,
+      source: { kind: 'review', excerpt: header },
+      category,
+      rejectionReason: checkQuality(statement, rationale),
+    });
+  }
+  return out;
+}
+
+function extractFromDiff(gitDiff) {
+  const out = [];
+  const lines = gitDiff.split('\n');
+  let currentFile = '';
+  const fileRe = /^\+\+\+ b\/(.+)$/;
+  const constraintRe = /^\+\s*(?:\/\/|#|--|\*)\s*(?:MUST|必须|invariant|约束|不变量|注意[:：])\s*(.+)/i;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fm = line.match(fileRe);
+    if (fm) {
+      currentFile = fm[1];
+      continue;
+    }
+    const cm = line.match(constraintRe);
+    if (!cm) continue;
+    const statement = cm[1].trim().slice(0, MAX_STATEMENT_CHARS);
+    const context = lines.slice(Math.max(0, i - 3), Math.min(lines.length, i + 4))
+      .map(l => l.replace(/^[+\-]\s?/, ''))
+      .join('\n').slice(0, 400);
+    const rationale = `In ${currentFile}: ${context}`.slice(0, 400);
+    const category = categorizeStatement(statement, rationale);
+    out.push({
+      statement,
+      rationale,
+      source: { kind: 'diff', excerpt: `${currentFile} (${cm[0].slice(0, 80)}...)` },
+      category,
+      rejectionReason: checkQuality(statement, rationale),
+    });
+  }
+  return out;
+}
+
+function dedupeByStatement(candidates) {
+  const seen = new Set();
+  const out = [];
+  for (const c of candidates) {
+    const key = c.statement.toLowerCase().replace(/\s+/g, ' ').trim();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(c);
+  }
+  return out;
+}
+
+function extractCandidates(input) {
+  const out = [];
+  if (input.reviewMd) out.push(...extractFromReview(input.reviewMd));
+  if (input.gitDiff) out.push(...extractFromDiff(input.gitDiff));
+  return dedupeByStatement(out);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// CLI
+// ─────────────────────────────────────────────────────────────────
+
+const MAX_INPUT_BYTES = 5 * 1024 * 1024; // 5MB cap per input file
+
+function readBoundedFile(path) {
+  // Defensive: a 1GB diff file would otherwise blow process memory. Real diffs
+  // for a single change rarely exceed 200KB; 5MB is generous.
+  try {
+    const stat = fs.statSync(path);
+    if (!stat.isFile()) return null;
+    if (stat.size > MAX_INPUT_BYTES) {
+      process.stderr.write(`spec-suggestion: ${path} exceeds ${MAX_INPUT_BYTES} bytes (${stat.size}) — refusing\n`);
+      return null;
+    }
+    return fs.readFileSync(path, 'utf-8');
+  }
+  catch (err) {
+    process.stderr.write(`spec-suggestion: cannot read ${path}: ${err.message}\n`);
+    return null;
+  }
+}
+
+function parseArgs(argv) {
+  // Minimal flag parser — keep deps zero. Recognized:
+  //   --diff <path>        path to git diff file
+  //   --review <path>      path to REVIEW.md
+  //   --change-id <id>     optional change identifier (passed through, not used)
+  //   --help               print usage
+  const out = { diff: null, review: null, changeId: null, help: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') {
+      out.help = true;
+    }
+    else if (a === '--diff' && i + 1 < argv.length) {
+      out.diff = argv[++i];
+    }
+    else if (a === '--review' && i + 1 < argv.length) {
+      out.review = argv[++i];
+    }
+    else if (a === '--change-id' && i + 1 < argv.length) {
+      out.changeId = argv[++i];
+    }
+    else {
+      process.stderr.write(`spec-suggestion: unknown arg: ${a}\n`);
+      out.help = true;
+    }
+  }
+  return out;
+}
+
+function printUsage() {
+  process.stderr.write([
+    'Usage: node spec-suggestion.cjs --diff <path> --review <path> [--change-id <id>]',
+    '',
+    'Extracts spec-evolution candidates from a git diff + REVIEW.md and prints',
+    'a JSON array to stdout. Used by /ccg:spec-impl Step 10 (RFC-9).',
+    '',
+    'At least one of --diff or --review must be provided.',
+  ].join('\n') + '\n');
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help || (!args.diff && !args.review)) {
+    printUsage();
+    return 1;
+  }
+
+  const gitDiff = args.diff ? readBoundedFile(args.diff) : '';
+  const reviewMd = args.review ? readBoundedFile(args.review) : '';
+
+  // If both paths were given but neither readable, fail loud. If only one was
+  // given and unreadable, also fail (the user expected it to be there).
+  if (args.diff && gitDiff === null) return 1;
+  if (args.review && reviewMd === null) return 1;
+
+  const candidates = extractCandidates({
+    gitDiff: gitDiff || undefined,
+    reviewMd: reviewMd || undefined,
+    changeId: args.changeId || undefined,
+  });
+
+  process.stdout.write(JSON.stringify(candidates, null, 2) + '\n');
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = {
+  extractCandidates,
+  extractFromReview,
+  extractFromDiff,
+  categorizeStatement,
+  checkQuality,
+  dedupeByStatement,
+  parseArgs,
+  main,
+  MIN_RATIONALE_CHARS,
+  MAX_STATEMENT_CHARS,
+  MAX_INPUT_BYTES,
+};