ccgx-workflow 2.3.1 → 2.4.1

package/dist/index.mjs

@@ -1,7 +1,8 @@
-import { h as collectSkills, j as resolvePluginBashCommand } from './shared/ccgx-workflow.DDYfdCuM.mjs';
-export { k as changeLanguage, G as checkForUpdates, I as collectInvocableSkills, H as compareVersions, m as createDefaultConfig, n as createDefaultRouting, J as generateCommandContent, o as getCcgDir, p as getConfigPath, E as getCurrentVersion, F as getLatestVersion, t as getWorkflowById, q as getWorkflowConfigs, c as i18n, e as init, b as initI18n, y as installAceTool, z as installAceToolRs, K as installSkillCommands, x as installWorkflows, C as migrateToV1_4_0, D as needsMigration, L as parseFrontmatter, a as readCcgConfig, s as showMainMenu, B as uninstallAceTool, A as uninstallWorkflows, u as update, l as writeCcgConfig } from './shared/ccgx-workflow.DDYfdCuM.mjs';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync, readdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { h as collectSkills, j as resolvePluginBashCommand } from './shared/ccgx-workflow.j1spUsik.mjs';
+export { k as changeLanguage, G as checkForUpdates, I as collectInvocableSkills, H as compareVersions, m as createDefaultConfig, n as createDefaultRouting, J as generateCommandContent, o as getCcgDir, p as getConfigPath, E as getCurrentVersion, F as getLatestVersion, t as getWorkflowById, q as getWorkflowConfigs, c as i18n, e as init, b as initI18n, y as installAceTool, z as installAceToolRs, K as installSkillCommands, x as installWorkflows, C as migrateToV1_4_0, D as needsMigration, L as parseFrontmatter, a as readCcgConfig, s as showMainMenu, B as uninstallAceTool, A as uninstallWorkflows, u as update, l as writeCcgConfig } from './shared/ccgx-workflow.j1spUsik.mjs';
+import { mkdirSync, appendFileSync, existsSync, statSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { dirname, resolve } from 'pathe';
+import { join, dirname as dirname$1 } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
 import 'ansis';
@@ -9,12 +10,246 @@ import 'inquirer';
 import 'ora';
 import 'node:util';
 import 'node:url';
-import 'pathe';
 import 'fs-extra';
 import 'smol-toml';
 import 'node:path/posix';
 import 'i18next';
 
+const FIX_LOG_RELATIVE_PATH = ".context/fix-log.jsonl";
+function resolveFixLogPath(workdir) {
+  return resolve(workdir, FIX_LOG_RELATIVE_PATH);
+}
+function appendFixLogEntry(workdir, entry) {
+  validateEntry(entry);
+  const logPath = resolveFixLogPath(workdir);
+  mkdirSync(dirname(logPath), { recursive: true });
+  appendFileSync(logPath, `${JSON.stringify(entry)}
+`, "utf-8");
+}
+function validateEntry(entry) {
+  if (!entry || typeof entry !== "object") {
+    throw new TypeError("fix-log entry must be an object");
+  }
+  const e = entry;
+  if (e.kind !== "review" && e.kind !== "fix") {
+    throw new TypeError(`fix-log entry.kind must be 'review' or 'fix' (got ${String(e.kind)})`);
+  }
+  if (typeof e.ts !== "string" || !e.ts) {
+    throw new TypeError("fix-log entry.ts must be a non-empty ISO string");
+  }
+  if (typeof e.round !== "number" || !Number.isInteger(e.round) || e.round < 1) {
+    throw new TypeError(`fix-log entry.round must be a positive integer (got ${e.round})`);
+  }
+  if (e.kind === "review") {
+    const f = e.findings;
+    if (!f || typeof f !== "object" || typeof f.critical !== "number" || typeof f.warning !== "number" || typeof f.info !== "number") {
+      throw new TypeError("review entry.findings must include numeric critical/warning/info");
+    }
+  }
+  if (e.kind === "fix") {
+    const allowed = /* @__PURE__ */ new Set(["completed", "partial", "escalated", "failed"]);
+    if (typeof e.status !== "string" || !allowed.has(e.status)) {
+      throw new TypeError(`fix entry.status must be one of completed|partial|escalated|failed (got ${String(e.status)})`);
+    }
+    if (!Array.isArray(e.commits)) {
+      throw new TypeError("fix entry.commits must be an array");
+    }
+    for (let i = 0; i < e.commits.length; i++) {
+      if (typeof e.commits[i] !== "string") {
+        throw new TypeError(`fix entry.commits[${i}] must be a string (got ${typeof e.commits[i]})`);
+      }
+    }
+  }
+}
+const MAX_LOG_FILE_BYTES = 5 * 1024 * 1024;
+function readFixLog(workdir) {
+  const logPath = resolveFixLogPath(workdir);
+  if (!existsSync(logPath)) return [];
+  let raw;
+  try {
+    const st = statSync(logPath);
+    if (!st.isFile() || st.size > MAX_LOG_FILE_BYTES) return [];
+    raw = readFileSync(logPath, "utf-8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    try {
+      validateEntry(parsed);
+      out.push(parsed);
+    } catch {
+      continue;
+    }
+  }
+  return out;
+}
+function convergeHistoryFromLog(entries) {
+  const byRound = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    if (e.kind !== "review") continue;
+    byRound.set(e.round, { round: e.round, findings: { ...e.findings } });
+  }
+  return [...byRound.values()].sort((a, b) => a.round - b.round);
+}
+function loadConvergeHistory(workdir) {
+  return convergeHistoryFromLog(readFixLog(workdir));
+}
+
+const MIN_RATIONALE_CHARS = 40;
+const MAX_STATEMENT_CHARS = 200;
+const FILLER_PHRASES = [
+  "\u5199\u597D\u7684\u4EE3\u7801",
+  "\u6CE8\u610F\u5B89\u5168",
+  "\u5C0F\u5FC3",
+  "\u4FDD\u6301\u4EE3\u7801\u6574\u6D01",
+  "\u9075\u5FAA\u6700\u4F73\u5B9E\u8DF5",
+  "\u8BF7\u4ED4\u7EC6\u5BA1\u67E5",
+  "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" },
+  // CJK 关键词在 cross-cutting 之外补一组
+  { kw: /(?:认证|授权|加密|后端|接口|数据库|迁移)/, category: "backend" },
+  { kw: /(?:前端|组件|页面|样式|交互|路由跳转)/, category: "frontend" }
+];
+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) \u2014 break it down`;
+  if (rationale.length < MIN_RATIONALE_CHARS) return `rationale too thin (< ${MIN_RATIONALE_CHARS} chars) \u2014 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 \u2014 add a concrete anchor";
+  }
+  return void 0;
+}
+function safeSlice(s, start, end) {
+  let e = Math.min(end, s.length);
+  if (e > 0 && e < s.length) {
+    const code = s.charCodeAt(e - 1);
+    if (code >= 55296 && code <= 56319) e--;
+  }
+  return s.slice(start, e);
+}
+function extractFromReview(reviewMd, _changeId) {
+  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 = safeSlice(reviewMd, 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 = safeSlice(sugMatch?.[1] ?? header, 0, MAX_STATEMENT_CHARS).trim();
+    const rationale = safeSlice(body, 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 = safeSlice(cm[1].trim(), 0, MAX_STATEMENT_CHARS);
+    const context = safeSlice(lines.slice(Math.max(0, i - 3), Math.min(lines.length, i + 4)).map((l) => l.replace(/^[+\-]\s?/, "")).join("\n"), 0, 400);
+    const rationale = safeSlice(`In ${currentFile}: ${context}`, 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 extractCandidates(input) {
+  const out = [];
+  if (input.reviewMd) out.push(...extractFromReview(input.reviewMd, input.changeId));
+  if (input.gitDiff) out.push(...extractFromDiff(input.gitDiff));
+  return dedupeByStatement(out);
+}
+function dedupeByStatement(candidates) {
+  const seen = /* @__PURE__ */ 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 formatAsMarkdown(approved, meta) {
+  if (approved.length === 0) {
+    return "";
+  }
+  const lines = [];
+  lines.push(`# Spec Evolution \u2014 ${meta.changeId}`);
+  lines.push("");
+  lines.push(`> Captured ${meta.isoDate} during \`/ccg:spec-impl\` archive step.`);
+  lines.push("> User-approved candidates only. Promote to `specs/<capability>/spec.md` via the next `/ccg:spec-research` iteration.");
+  lines.push("");
+  for (const category of ["backend", "frontend", "cross-cutting"]) {
+    const inCat = approved.filter((c) => c.category === category);
+    if (inCat.length === 0) continue;
+    lines.push(`## ${category}`);
+    lines.push("");
+    for (const c of inCat) {
+      lines.push(`- **${c.statement}**`);
+      lines.push(`  - *Why*: ${c.rationale}`);
+      lines.push(`  - *Source*: ${c.source.kind} \u2014 \`${c.source.excerpt.slice(0, 120)}\``);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+
 function phaseDir(workdir, phase) {
   return join(workdir, ".context", sanitizePhase(phase));
 }
@@ -88,7 +323,7 @@ function serializeList(values) {
 }
 function writeContext(workdir, ctx) {
   const target = contextPath(workdir, ctx.phase);
-  mkdirSync(dirname(target), { recursive: true });
+  mkdirSync(dirname$1(target), { recursive: true });
   const frontmatter = [
     "---",
     `phase: ${serializeScalar(ctx.phase)}`,
@@ -141,7 +376,7 @@ function readContext(workdir, phase) {
 }
 function writeSummary(workdir, summary) {
   const target = summaryPath(workdir, summary.phase);
-  mkdirSync(dirname(target), { recursive: true });
+  mkdirSync(dirname$1(target), { recursive: true });
   const frontmatter = [
     "---",
     `phase: ${serializeScalar(summary.phase)}`,
@@ -2025,4 +2260,4 @@ function hasBlockingFindings(report) {
   return report.findings.some((f) => f.severity === "critical");
 }
 
-export { ALL_LAYERS, CONTEXT_BUDGET_THRESHOLD, DESCRIPTION_SOFT_LIMIT, ROUTING_SCHEMA_VERSION, aggregatePlans, auditSkillDescriptions, auditSkillsDirectory, auditTarballContents, batchByMaxConcurrent, bothPluginsInstalled, buildQualityPlan, buildWaves, cascadeSkip, collectSkills, contextPath, decideFromSummaries, detectPlugin, detectPluginAvailability, estimateBriefLength, estimateTokens, extractFrontmatter, criticalFindings as interfaceAuditCriticals, hasBlockingFindings as interfaceAuditHasBlocking, majorFindings as interfaceAuditMajors, isLayer, parseChallengerSummary, parseDependsOn, parseFrontmatterFields, parseInterfaceAuditorReport, parseQualityFlag, parseRoadmap, parseRoleFlag, parseVerifyReport, phaseDir, planChallengerSpawns, planVerifyWave, planWavesForTier, promptFilePath, readContext, readSummary, readSummaryFrontmatter, renderAuditMarkdown, renderPipelineReport, resolveQualityTier, routeSpecialist, runPipelineCheck, runPnpmPack, sampleAll, sampleHookSchema, samplePackageStructure, samplePluginList, sampleSkillList, sanitizePhase, schedule, serializeBriefForPrompt, summarizeGroundTruth, summaryPath, summaryTokenEstimate, synthesizeRevisionFeedback, synthesizeVerifyFeedback, synthesizeVerifyResults, verifyAllCommandsIncluded, writeContext, writeSummary };
+export { ALL_LAYERS, CONTEXT_BUDGET_THRESHOLD, DESCRIPTION_SOFT_LIMIT, FIX_LOG_RELATIVE_PATH, MAX_STATEMENT_CHARS, MIN_RATIONALE_CHARS, ROUTING_SCHEMA_VERSION, aggregatePlans, appendFixLogEntry, auditSkillDescriptions, auditSkillsDirectory, auditTarballContents, batchByMaxConcurrent, bothPluginsInstalled, buildQualityPlan, buildWaves, cascadeSkip, categorizeStatement, checkQuality, collectSkills, contextPath, convergeHistoryFromLog, decideFromSummaries, detectPlugin, detectPluginAvailability, estimateBriefLength, estimateTokens, extractCandidates, extractFrontmatter, formatAsMarkdown, criticalFindings as interfaceAuditCriticals, hasBlockingFindings as interfaceAuditHasBlocking, majorFindings as interfaceAuditMajors, isLayer, loadConvergeHistory, parseChallengerSummary, parseDependsOn, parseFrontmatterFields, parseInterfaceAuditorReport, parseQualityFlag, parseRoadmap, parseRoleFlag, parseVerifyReport, phaseDir, planChallengerSpawns, planVerifyWave, planWavesForTier, promptFilePath, readContext, readFixLog, readSummary, readSummaryFrontmatter, renderAuditMarkdown, renderPipelineReport, resolveFixLogPath, resolveQualityTier, routeSpecialist, runPipelineCheck, runPnpmPack, sampleAll, sampleHookSchema, samplePackageStructure, samplePluginList, sampleSkillList, sanitizePhase, schedule, serializeBriefForPrompt, summarizeGroundTruth, summaryPath, summaryTokenEstimate, synthesizeRevisionFeedback, synthesizeVerifyFeedback, synthesizeVerifyResults, verifyAllCommandsIncluded, writeContext, writeSummary };

package/dist/shared/{ccgx-workflow.DDYfdCuM.mjs → ccgx-workflow.j1spUsik.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.3.1";
+const version = "2.4.1";
 
 function cmd(id, order, category, name, nameEn, description, descriptionEn, cmdOverride) {
   return {
@@ -87,11 +87,20 @@ function getAllCommandIds() {
 const HOOK_FILES = [
   "ccg-context-monitor.js",
   "ccg-statusline.js",
-  "ccg-session-state.cjs"
+  "ccg-session-state.cjs",
+  "ccg-loop-detector.cjs",
+  "ccg-skill-router.cjs",
+  "ccg-stop-gate.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 CCG_SKILL_OVERRIDES = {
+  "codex:rescue": "user-invocable-only",
+  "gemini:rescue": "user-invocable-only"
+};
 function buildHookCommand(hookFilePath) {
   return `node "${hookFilePath}"`;
 }
@@ -129,6 +138,9 @@ async function patchSettingsJson(ctx) {
   const monitorPath = join(hooksDir, "ccg-context-monitor.js");
   const statuslinePath = join(hooksDir, "ccg-statusline.js");
   const sessionStatePath = join(hooksDir, "ccg-session-state.cjs");
+  const loopDetectorPath = join(hooksDir, "ccg-loop-detector.cjs");
+  const skillRouterPath = join(hooksDir, "ccg-skill-router.cjs");
+  const stopGatePath = join(hooksDir, "ccg-stop-gate.cjs");
   let settings = {};
   if (await fs.pathExists(settingsPath)) {
     try {
@@ -182,6 +194,77 @@ async function patchSettingsJson(ctx) {
       modified = true;
     }
   }
+  if (await fs.pathExists(loopDetectorPath)) {
+    if (!settings.hooks) settings.hooks = {};
+    if (!Array.isArray(settings.hooks.UserPromptSubmit)) settings.hooks.UserPromptSubmit = [];
+    const alreadyRegistered = settings.hooks.UserPromptSubmit.some(
+      (entry) => entry?.hooks?.some((h) => typeof h?.command === "string" && h.command.includes("ccg-loop-detector"))
+    );
+    if (!alreadyRegistered) {
+      settings.hooks.UserPromptSubmit.push({
+        matcher: "",
+        hooks: [
+          {
+            type: "command",
+            command: buildHookCommand(loopDetectorPath),
+            timeout: USER_PROMPT_TIMEOUT_SEC
+          }
+        ]
+      });
+      modified = true;
+    }
+  }
+  if (await fs.pathExists(skillRouterPath)) {
+    if (!settings.hooks) settings.hooks = {};
+    if (!Array.isArray(settings.hooks.UserPromptSubmit)) settings.hooks.UserPromptSubmit = [];
+    const alreadyRegistered = settings.hooks.UserPromptSubmit.some(
+      (entry) => entry?.hooks?.some((h) => typeof h?.command === "string" && h.command.includes("ccg-skill-router"))
+    );
+    if (!alreadyRegistered) {
+      settings.hooks.UserPromptSubmit.push({
+        matcher: "",
+        hooks: [
+          {
+            type: "command",
+            command: buildHookCommand(skillRouterPath),
+            timeout: USER_PROMPT_TIMEOUT_SEC
+          }
+        ]
+      });
+      modified = true;
+    }
+  }
+  if (await fs.pathExists(stopGatePath)) {
+    if (!settings.hooks) settings.hooks = {};
+    for (const eventName of ["Stop", "SubagentStop"]) {
+      if (!Array.isArray(settings.hooks[eventName])) settings.hooks[eventName] = [];
+      const alreadyRegistered = settings.hooks[eventName].some(
+        (entry) => entry?.hooks?.some((h) => typeof h?.command === "string" && h.command.includes("ccg-stop-gate"))
+      );
+      if (!alreadyRegistered) {
+        settings.hooks[eventName].push({
+          matcher: "",
+          hooks: [
+            {
+              type: "command",
+              command: buildHookCommand(stopGatePath),
+              timeout: STOP_TIMEOUT_SEC
+            }
+          ]
+        });
+        modified = true;
+      }
+    }
+  }
+  if (typeof settings.skillOverrides !== "object" || settings.skillOverrides === null) {
+    settings.skillOverrides = {};
+  }
+  for (const [skillName, level] of Object.entries(CCG_SKILL_OVERRIDES)) {
+    if (settings.skillOverrides[skillName] !== level) {
+      settings.skillOverrides[skillName] = level;
+      modified = true;
+    }
+  }
   if (await fs.pathExists(statuslinePath)) {
     const existing = settings.statusLine?.command;
     if (!existing) {
@@ -250,6 +333,24 @@ async function uninstallHooks(installDir) {
         modified = true;
       }
     }
+    if (Array.isArray(settings.hooks?.UserPromptSubmit)) {
+      const before = settings.hooks.UserPromptSubmit.length;
+      settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter((entry) => {
+        const hasCcg = entry?.hooks?.some(
+          (h) => typeof h?.command === "string" && (h.command.includes("ccg-loop-detector") || h.command.includes("ccg-skill-router"))
+        );
+        return !hasCcg;
+      });
+      if (settings.hooks.UserPromptSubmit.length !== before) modified = true;
+      if (settings.hooks.UserPromptSubmit.length === 0) {
+        delete settings.hooks.UserPromptSubmit;
+        modified = true;
+      }
+      if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+        modified = true;
+      }
+    }
     if (Array.isArray(settings.hooks?.SessionStart)) {
       const before = settings.hooks.SessionStart.length;
       settings.hooks.SessionStart = settings.hooks.SessionStart.filter((entry) => {
@@ -268,10 +369,42 @@ async function uninstallHooks(installDir) {
         modified = true;
       }
     }
+    for (const eventName of ["Stop", "SubagentStop"]) {
+      if (Array.isArray(settings.hooks?.[eventName])) {
+        const before = settings.hooks[eventName].length;
+        settings.hooks[eventName] = settings.hooks[eventName].filter((entry) => {
+          const hasCcg = entry?.hooks?.some(
+            (h) => typeof h?.command === "string" && h.command.includes("ccg-stop-gate")
+          );
+          return !hasCcg;
+        });
+        if (settings.hooks[eventName].length !== before) modified = true;
+        if (settings.hooks[eventName].length === 0) {
+          delete settings.hooks[eventName];
+          modified = true;
+        }
+        if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+          delete settings.hooks;
+          modified = true;
+        }
+      }
+    }
     if (typeof settings.statusLine?.command === "string" && settings.statusLine.command.includes("ccg-statusline")) {
       delete settings.statusLine;
       modified = true;
     }
+    if (settings.skillOverrides && typeof settings.skillOverrides === "object") {
+      for (const skillName of Object.keys(CCG_SKILL_OVERRIDES)) {
+        if (skillName in settings.skillOverrides) {
+          delete settings.skillOverrides[skillName];
+          modified = true;
+        }
+      }
+      if (Object.keys(settings.skillOverrides).length === 0) {
+        delete settings.skillOverrides;
+        modified = true;
+      }
+    }
     if (modified) {
       try {
         await fs.writeJSON(settingsPath, settings, { spaces: 2 });
@@ -1386,6 +1519,14 @@ async function installShim(ctx) {
         await fs.chmod(destCheckPlugins, 493);
       }
     }
+    const srcSpecSuggestion = join(ctx.templateDir, "scripts", "spec-suggestion.cjs");
+    if (await fs.pathExists(srcSpecSuggestion)) {
+      const destSpecSuggestion = join(scriptDir, "spec-suggestion.cjs");
+      await fs.copy(srcSpecSuggestion, destSpecSuggestion, { overwrite: true });
+      if (process.platform !== "win32") {
+        await fs.chmod(destSpecSuggestion, 493);
+      }
+    }
     if (process.platform === "win32") {
       const cmdMjs = destMjs.replace(/\//g, "\\");
       const cmdPath = join(binDir, "codeagent-wrapper.cmd");
@@ -4221,7 +4362,20 @@ async function readPackageVersion(pkgPath) {
     return null;
   }
 }
+async function readBuildVersion() {
+  try {
+    const mod = await import('../chunks/version-build.mjs');
+    const v = mod?.BUILD_TIME_VERSION;
+    return typeof v === "string" && /^\d+\.\d+\.\d+/.test(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
 async function getCurrentVersion() {
+  const buildVersion = await readBuildVersion();
+  if (buildVersion) {
+    return buildVersion;
+  }
   const relativePkgPath = fileURLToPath(new URL("../../package.json", import.meta.url));
   const relativeVersion = await readPackageVersion(relativePkgPath);
   if (relativeVersion) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccgx-workflow",
-  "version": "2.3.1",
+  "version": "2.4.1",
   "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/review.md

@@ -385,16 +385,19 @@ auto_round: <仅 --auto 模式，当前轮次 1-indexed>
 
 ### 5.4 多轮收敛（仅 `--fix --auto`）
 
-`--auto` 模式下，code-fixer 第 1 轮跑完后：
+`--auto` 模式下，**每完成一轮 review + fix 都把状态持久化到 `.context/fix-log.jsonl`**——这样 `/clear`、session 重启、context 压缩都不会丢历史。轮次推进算法：
 
-1. Read REVIEW-FIX.md，提取本轮 finding 数（critical / warning / info）
-2. 调用收敛判定（参考 `src/utils/code-fixer-worktree.ts:decideConverge`）：
+1. 每轮 review 完成 → 主线 Read REVIEW.md 抽 finding 数 → 调 `appendFixLogEntry(workdir, {kind:'review', ts:<ISO>, round:N, findings:{critical,warning,info}})` 持久化
+2. 每轮 fix 完成 → 同样 `appendFixLogEntry(workdir, {kind:'fix', ts, round:N, status, commits:[<sha7>...]})`
+3. 判定下一步：先 `loadConvergeHistory(workdir)` 从 disk 重建 ConvergeRound[]（**不**用 context 内史，因为可能已丢），再调 `decideConverge(history)`（参考 `src/utils/code-fixer-worktree.ts:decideConverge`）：
    - `converged`（critical+warning=0）→ 完成，输出收敛报告
    - `escalate`（达到 3 轮 cap 或 stall）→ `AskUserQuestion`："继续手动修 / 接受现状 / 回滚全部"
    - `continue` → 重跑阶段 1-4 生成新 REVIEW.md，再 spawn code-fixer，`auto_round` +1
 
 **3 轮上限是 CCG 硬规约**（与 plan-checker / verify-work 一致），**禁止**绕过。
 
+**为什么走 disk 不走 context**：fork 早期版本把 ConvergeRound[] 留在主线 context；用户在 round 2 `/clear` 后继续 `--auto` → 主线见空 history → 当成 round 1 重启 → 永远到不了 escalate cap。fix-log.jsonl 在 disk 上 append-only，跨会话稳如磐石。`.context/fix-log.jsonl` 已加入 `.gitignore`（项目本地审计，不入 repo）。
+
 ### 5.5 闭环修复总结
 
 ```markdown

package/templates/commands/spec-impl.md

@@ -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 -->