ccgx-workflow 2.3.1 → 2.4.1

package/dist/chunks/version-build.mjs

@@ -0,0 +1,3 @@
+const BUILD_TIME_VERSION = "2.4.1";
+
+export { BUILD_TIME_VERSION };

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import cac from 'cac';
 import ansis from 'ansis';
-import { d as diagnoseMcpConfig, i as isWindows, r as readClaudeCodeConfig, f as fixWindowsMcpConfig, w as writeClaudeCodeConfig, a as readCcgConfig, b as initI18n, c as i18n, s as showMainMenu, e as init, g as configMcp, v as version } from './shared/ccgx-workflow.DDYfdCuM.mjs';
+import { d as diagnoseMcpConfig, i as isWindows, r as readClaudeCodeConfig, f as fixWindowsMcpConfig, w as writeClaudeCodeConfig, a as readCcgConfig, b as initI18n, c as i18n, s as showMainMenu, e as init, g as configMcp, v as version } from './shared/ccgx-workflow.j1spUsik.mjs';
 import { execSync } from 'node:child_process';
 import 'inquirer';
 import 'ora';

package/dist/index.d.mts

@@ -296,7 +296,17 @@ declare function migrateToV1_4_0(): Promise<MigrationResult>;
 declare function needsMigration(): Promise<boolean>;
 
 /**
- * Get current installed version from package.json
+ * Get current installed version.
+ *
+ * Resolution order:
+ *   1. BUILD_TIME_VERSION — baked into the bundle by unbuild. This is the
+ *      authoritative source for shipped binaries because it does not depend on
+ *      filesystem layout. Fixes the Windows-npx 0.0.0 → false migration bug.
+ *   2. relative package.json — used in dev (tsx) where step 1 is a placeholder.
+ *   3. walked-up package.json — last-resort for unusual runtime layouts.
+ *   4. npm_package_version env var — when run as an npm script.
+ *   5. '0.0.0' — only when everything above failed; callers must treat this as
+ *      "unknown" and skip version-gated branches (e.g. migration).
  */
 declare function getCurrentVersion(): Promise<string>;
 /**
@@ -317,6 +327,230 @@ declare function checkForUpdates(): Promise<{
     latestVersion: string | null;
 }>;
 
+/**
+ * 单轮收敛状态。
+ */
+interface ConvergeRound {
+    /** 第几轮（1-indexed） */
+    round: number;
+    /** 本轮 review 发现的 finding 数（按严重度分） */
+    findings: {
+        critical: number;
+        warning: number;
+        info: number;
+    };
+}
+
+/**
+ * Ralph Loop fix-log persistence (RFC-8 follow-up to fork v2.3.1).
+ *
+ * Context: fork already implements the Ralph Loop core (multi-round
+ * `--fix --auto` with `decideConverge()` + AUTO_CONVERGE_CAP=3 + stall
+ * detection + 4-step transactional cleanup). The only gap is **persistence**
+ * of the per-round ConvergeRound history.
+ *
+ * Today the main thread holds the history in conversation context. A `/clear`
+ * mid-loop, a session crash, or a long-running session that gets context-
+ * compacted all silently drop the history. `decideConverge` then sees an
+ * empty `history[]` on the next round and starts over — re-trying from
+ * round 1 instead of recognizing this is round 3 and escalating.
+ *
+ * Fix: append-only JSONL log at `.context/fix-log.jsonl`. The log survives
+ * `/clear` and session restarts; main-thread code reads it back to
+ * reconstruct the ConvergeRound[] before calling `decideConverge`.
+ *
+ * Design choices:
+ *   - JSONL (one JSON object per line) instead of one big JSON file. Append
+ *     is a single fs.appendFileSync call → atomic on POSIX and Windows
+ *     (single write() syscall, no read-modify-write race between writers).
+ *   - Two entry kinds: 'review' (records finding counts) and 'fix' (records
+ *     commits and status). `convergeHistoryFromLog` only consumes 'review'
+ *     entries because that is what `decideConverge` cares about.
+ *   - No mutex / file lock. Append-only + single-writer-per-task. If two
+ *     concurrent `/ccg:review --fix --auto` runs ever happen against the
+ *     same workdir they'll interleave lines but each line is still a valid
+ *     ConvergeRound — readers tolerate that.
+ *   - Tolerant parsing: a malformed line is skipped, not throwed on. The
+ *     log is advisory; a corrupt entry must not break the loop.
+ */
+
+/**
+ * Relative path inside the project where the JSONL log lives. Same
+ * `.context/` directory the sentinel + jobs/ live in.
+ */
+declare const FIX_LOG_RELATIVE_PATH = ".context/fix-log.jsonl";
+/**
+ * Per-round finding counts. Mirrors ConvergeRound.findings.
+ */
+interface FindingCounts {
+    critical: number;
+    warning: number;
+    info: number;
+}
+/**
+ * 'review' entries record a review-phase outcome (used to feed decideConverge).
+ * 'fix' entries record the corresponding code-fixer run (commits, status).
+ */
+type FixLogEntryKind = 'review' | 'fix';
+interface ReviewLogEntry {
+    kind: 'review';
+    /** ISO 8601 timestamp. */
+    ts: string;
+    /** 1-indexed round number, matches code-fixer's `auto_round`. */
+    round: number;
+    /** Counts produced by the review pass. */
+    findings: FindingCounts;
+    /** Optional free-form note (≤120 chars), e.g. "after second adversarial review". */
+    note?: string;
+}
+interface FixLogEntry {
+    kind: 'fix';
+    ts: string;
+    round: number;
+    /** Outcome of the code-fixer run for this round. */
+    status: 'completed' | 'partial' | 'escalated' | 'failed';
+    /** Atomic commits the fixer produced this round (sha7 strings). */
+    commits: string[];
+    note?: string;
+}
+type FixLogRecord = ReviewLogEntry | FixLogEntry;
+/**
+ * Absolute path of the fix-log for a given project workdir.
+ */
+declare function resolveFixLogPath(workdir: string): string;
+/**
+ * Atomically append a single record to `.context/fix-log.jsonl`. Creates the
+ * parent directory if missing. Single appendFileSync call → atomic at the
+ * fs syscall layer; no read-modify-write race for concurrent writers.
+ *
+ * Caller is responsible for picking the right `ts` and `round`. We do not
+ * generate timestamps here because tests want them to be deterministic.
+ */
+declare function appendFixLogEntry(workdir: string, entry: FixLogRecord): void;
+/**
+ * Read all valid entries from `.context/fix-log.jsonl`. Missing file → [].
+ * Malformed lines are skipped silently (the log is advisory; one corrupt
+ * line from an interrupted write must not break the loop).
+ */
+declare function readFixLog(workdir: string): FixLogRecord[];
+/**
+ * Project the log down to the ConvergeRound[] history that decideConverge
+ * consumes. Only 'review' entries contribute; 'fix' entries are for audit.
+ *
+ * Rounds are returned in append order. If the same `round` appears twice
+ * (e.g. user re-ran round 2 after editing files manually) the LAST entry
+ * wins — that matches what a human reviewer of the log file would expect.
+ */
+declare function convergeHistoryFromLog(entries: readonly FixLogRecord[]): ConvergeRound[];
+/**
+ * One-call helper for the main thread: read the on-disk log and return the
+ * ConvergeRound[] history ready to hand to decideConverge.
+ *
+ * Use this whenever the main thread might have lost in-context history
+ * (after `/clear`, session restart, or context compaction).
+ */
+declare function loadConvergeHistory(workdir: string): ConvergeRound[];
+
+/**
+ * Spec Evolution candidate extractor (RFC-9).
+ *
+ * fork走 OpenSpec (OPSX) 路线：所有规范变更通过 `changes/<id>/` proposals 进入
+ * `openspec/specs/` 主规范。本 helper 只负责一件事——在 `/ccg:spec-impl` 归档
+ * **前**，从本次 change 的 git diff + REVIEW.md 里抽出**可复用的、非显而易见的
+ * 约定**，让用户决定要不要让它们沉淀下去。
+ *
+ * 关键设计决策：
+ *
+ *  1. **纯函数，不读 fs，不调网络**。输入是已 collected 的文本 (diff + review)，
+ *     输出是候选条目数组。spec-impl.md 主线负责 IO 和用户确认。
+ *
+ *  2. **不直接写 OpenSpec deltas**。Deltas 是研究阶段产物；本 helper 抽的是
+ *     "实施阶段发现的坑"，与 deltas 异源。写入路径推荐
+ *     `changes/<change-id>/SPEC_EVOLUTION.md`，archive 时随 change 归档。
+ *
+ *  3. **强质量门**。模型很容易输出"写好的代码"、"注意安全"这种空洞条目，所有
+ *     候选必须含**具体文件路径或 API 名**，且长度 ≥ MIN_RATIONALE_CHARS。
+ *     不合格的候选被 `rejectionReason` 标出，让 spec-impl.md 主线在确认 UI 里
+ *     展示给用户审视（不是默默丢弃——用户可能想看到 helper 拒了什么）。
+ *
+ *  4. **绝不**自动写入。导出 `formatAsMarkdown` 让主线渲染，但用户确认前
+ *     主线必须用 `AskUserQuestion` 列出 candidates 让用户勾选。
+ *
+ * 上游 V3 phase-guide.md §8 的 5 步流程（提炼 → 分类 → 草拟 → 展示 → 写入）
+ * 在 fork 的对应实现是：
+ *   - helper.extractCandidates → 提炼 + 分类（一次完成）
+ *   - helper.formatAsMarkdown  → 草拟
+ *   - spec-impl.md AskUserQuestion → 展示给用户
+ *   - spec-impl.md Write/Edit → 写入（仅用户勾选的条目）
+ */
+/**
+ * 候选 spec 条目分类。OpenSpec 推荐 capability 维度，本 helper 用粗粒度三档：
+ *   - backend:       涉及 server / api / db / auth / 后端业务逻辑
+ *   - frontend:      涉及 UI / component / route / state management / 浏览器
+ *   - cross-cutting: 工程基建 / 跨层 / 构建 / 测试 / CI / 配置
+ *
+ * 调用方（spec-impl.md）可在用户确认时把这三档映射到 OpenSpec 的具体 capability
+ * 路径（例如 `specs/auth/spec.md`、`specs/ui-shell/spec.md`）。
+ */
+type SpecCategory = 'backend' | 'frontend' | 'cross-cutting';
+interface SpecCandidate {
+    /** 一行 ≤ 120 字的约束陈述（"X 必须 Y" 句式优先）。 */
+    statement: string;
+    /** 为什么要这样（≥ MIN_RATIONALE_CHARS 字符，引用具体文件/API）。 */
+    rationale: string;
+    /** 提炼来源：哪一行 diff / REVIEW.md finding。 */
+    source: {
+        kind: 'diff' | 'review';
+        excerpt: string;
+    };
+    /** 推荐归档分类（spec-impl.md 主线决定最终 capability 映射）。 */
+    category: SpecCategory;
+    /** 拒绝原因（如果质量门没过）。通过的为 undefined。 */
+    rejectionReason?: string;
+}
+interface ExtractInput {
+    /** `git diff <base>..HEAD` 文本。可空（极小 change 走纯 review 路径）。 */
+    gitDiff?: string;
+    /** REVIEW.md 全文。可空（无 review 阶段或 fix 全 critical=0 跳过）。 */
+    reviewMd?: string;
+    /** Change id（仅用于 source 引用，不参与提炼）。 */
+    changeId?: string;
+}
+/** rationale 必须够长——拒绝"写好的代码"、"注意安全"等空洞条目。 */
+declare const MIN_RATIONALE_CHARS = 40;
+/** statement 上限——太长就不是约定，是设计文档。 */
+declare const MAX_STATEMENT_CHARS = 200;
+declare function categorizeStatement(statement: string, rationale: string): SpecCategory;
+/**
+ * Returns the rejection reason or undefined if the candidate passes the gate.
+ * Designed to be human-readable — these strings are shown back to the user in
+ * spec-impl.md's confirmation UI so they understand why helper filtered things.
+ */
+declare function checkQuality(statement: string, rationale: string): string | undefined;
+/**
+ * Main entry. Returns all candidates (passed + rejected) so spec-impl.md can
+ * show the user the full picture. Caller filters by `!c.rejectionReason` when
+ * building the confirmation choices.
+ */
+declare function extractCandidates(input: ExtractInput): SpecCandidate[];
+/**
+ * Render the user-approved candidates as Markdown suitable for
+ * `changes/<change-id>/SPEC_EVOLUTION.md`.
+ *
+ * Output format is intentionally NOT OpenSpec delta syntax — this file is an
+ * audit trail of "things we learned implementing this change", not a binding
+ * spec proposal. Promoting a SPEC_EVOLUTION entry to an actual SHALL in
+ * `specs/<capability>/spec.md` is a separate, deliberate step the user takes
+ * later (via `/ccg:spec-research` for the next iteration).
+ *
+ * Includes the change-id and ISO date in the heading so an archived
+ * SPEC_EVOLUTION.md is self-describing.
+ */
+declare function formatAsMarkdown(approved: readonly SpecCandidate[], meta: {
+    changeId: string;
+    isoDate: string;
+}): string;
+
 /**
  * Phase-scoped context state machine (v4.0 Phase 2).
  *
@@ -1770,5 +2004,5 @@ declare function majorFindings(report: InterfaceAuditReport): InterfaceAuditFind
  */
 declare function hasBlockingFindings(report: InterfaceAuditReport): boolean;
 
-export { ALL_LAYERS, CONTEXT_BUDGET_THRESHOLD, DESCRIPTION_SOFT_LIMIT, ROUTING_SCHEMA_VERSION, aggregatePlans, auditSkillDescriptions, auditSkillsDirectory, auditTarballContents, batchByMaxConcurrent, bothPluginsInstalled, buildQualityPlan, buildWaves, cascadeSkip, changeLanguage, checkForUpdates, collectInvocableSkills, collectSkills, compareVersions, contextPath, createDefaultConfig, createDefaultRouting, decideFromSummaries, detectPlugin, detectPluginAvailability, estimateBriefLength, estimateTokens, extractFrontmatter, generateCommandContent, getCcgDir, getConfigPath, getCurrentVersion, getLatestVersion, getWorkflowById, getWorkflowConfigs, i18n, init, initI18n, installAceTool, installAceToolRs, installSkillCommands, installWorkflows, criticalFindings as interfaceAuditCriticals, hasBlockingFindings as interfaceAuditHasBlocking, majorFindings as interfaceAuditMajors, isLayer, migrateToV1_4_0, needsMigration, parseChallengerSummary, parseDependsOn, parseFrontmatter, parseFrontmatterFields, parseInterfaceAuditorReport, parseQualityFlag, parseRoadmap, parseRoleFlag, parseVerifyReport, phaseDir, planChallengerSpawns, planVerifyWave, planWavesForTier, promptFilePath, readCcgConfig, readContext, readSummary, readSummaryFrontmatter, renderAuditMarkdown, renderPipelineReport, resolveQualityTier, routeSpecialist, runPipelineCheck, runPnpmPack, sampleAll, sampleHookSchema, samplePackageStructure, samplePluginList, sampleSkillList, sanitizePhase, schedule, serializeBriefForPrompt, showMainMenu, summarizeGroundTruth, summaryPath, summaryTokenEstimate, synthesizeRevisionFeedback, synthesizeVerifyFeedback, synthesizeVerifyResults, uninstallAceTool, uninstallWorkflows, update, verifyAllCommandsIncluded, writeCcgConfig, writeContext, writeSummary };
-export type { AceToolConfig, AuditReport, AuditRow, CcgConfig, ChallengeInput, ChallengerAgent, ChallengerDecision, ChallengerPlan, ChallengerSummary, CliOptions, CollaborationMode, DesignBrief, Divergence, FastContextConfig, Finding, FindingSeverity, GroundTruth, PluginInfo as GroundTruthPluginInfo, SkillInfo as GroundTruthSkillInfo, HookInfo, InitOptions, InstallResult, InterfaceAuditCategory, InterfaceAuditFinding, InterfaceAuditReport, Layer, Model, ModelRouting, ModelType, PackageStructureInfo, PhaseContext, PhaseMeta, PhaseStatus, PhaseSummary, PipelineCheckOptions, PipelineCheckReport, PipelineError, PipelineErrorCategory, PlanContribution, PlanVerifyWaveOptions, PluginAdvisor, PluginAvailability, PluginAvailability as PluginDetectionAvailability, PluginDetectionResult, PluginName, QualityPlan, SpawnEntry as QualitySpawnEntry, QualityTier, WavePlan as QualityWavePlan, ResolveInput, RoadmapPhase, Role, PluginAvailability as RoutingPluginAvailability, RoutingStrategy, SampleOptions, ScheduleOptions, SkillCategory, SkillMeta, SkillRuntimeType, SpawnEntry$1 as SpawnEntry, SpecialistCritic, SpecialistLayer, SpecialistModel, SpecialistRole, SpecialistRoute, SupportedLang, VerifyDecision, VerifyInvocationMode, VerifyMode, VerifyReport, VerifySpawnEntry, VerifyWavePlan, WaveKind, WaveSchedule, WorkflowConfig };
+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, changeLanguage, checkForUpdates, checkQuality, collectInvocableSkills, collectSkills, compareVersions, contextPath, convergeHistoryFromLog, createDefaultConfig, createDefaultRouting, decideFromSummaries, detectPlugin, detectPluginAvailability, estimateBriefLength, estimateTokens, extractCandidates, extractFrontmatter, formatAsMarkdown, generateCommandContent, getCcgDir, getConfigPath, getCurrentVersion, getLatestVersion, getWorkflowById, getWorkflowConfigs, i18n, init, initI18n, installAceTool, installAceToolRs, installSkillCommands, installWorkflows, criticalFindings as interfaceAuditCriticals, hasBlockingFindings as interfaceAuditHasBlocking, majorFindings as interfaceAuditMajors, isLayer, loadConvergeHistory, migrateToV1_4_0, needsMigration, parseChallengerSummary, parseDependsOn, parseFrontmatter, parseFrontmatterFields, parseInterfaceAuditorReport, parseQualityFlag, parseRoadmap, parseRoleFlag, parseVerifyReport, phaseDir, planChallengerSpawns, planVerifyWave, planWavesForTier, promptFilePath, readCcgConfig, readContext, readFixLog, readSummary, readSummaryFrontmatter, renderAuditMarkdown, renderPipelineReport, resolveFixLogPath, resolveQualityTier, routeSpecialist, runPipelineCheck, runPnpmPack, sampleAll, sampleHookSchema, samplePackageStructure, samplePluginList, sampleSkillList, sanitizePhase, schedule, serializeBriefForPrompt, showMainMenu, summarizeGroundTruth, summaryPath, summaryTokenEstimate, synthesizeRevisionFeedback, synthesizeVerifyFeedback, synthesizeVerifyResults, uninstallAceTool, uninstallWorkflows, update, verifyAllCommandsIncluded, writeCcgConfig, writeContext, writeSummary };
+export type { AceToolConfig, AuditReport, AuditRow, CcgConfig, ChallengeInput, ChallengerAgent, ChallengerDecision, ChallengerPlan, ChallengerSummary, CliOptions, CollaborationMode, DesignBrief, Divergence, ExtractInput, FastContextConfig, Finding, FindingCounts, FindingSeverity, FixLogEntry, FixLogEntryKind, FixLogRecord, GroundTruth, PluginInfo as GroundTruthPluginInfo, SkillInfo as GroundTruthSkillInfo, HookInfo, InitOptions, InstallResult, InterfaceAuditCategory, InterfaceAuditFinding, InterfaceAuditReport, Layer, Model, ModelRouting, ModelType, PackageStructureInfo, PhaseContext, PhaseMeta, PhaseStatus, PhaseSummary, PipelineCheckOptions, PipelineCheckReport, PipelineError, PipelineErrorCategory, PlanContribution, PlanVerifyWaveOptions, PluginAdvisor, PluginAvailability, PluginAvailability as PluginDetectionAvailability, PluginDetectionResult, PluginName, QualityPlan, SpawnEntry as QualitySpawnEntry, QualityTier, WavePlan as QualityWavePlan, ResolveInput, ReviewLogEntry, RoadmapPhase, Role, PluginAvailability as RoutingPluginAvailability, RoutingStrategy, SampleOptions, ScheduleOptions, SkillCategory, SkillMeta, SkillRuntimeType, SpawnEntry$1 as SpawnEntry, SpecCandidate, SpecCategory, SpecialistCritic, SpecialistLayer, SpecialistModel, SpecialistRole, SpecialistRoute, SupportedLang, VerifyDecision, VerifyInvocationMode, VerifyMode, VerifyReport, VerifySpawnEntry, VerifyWavePlan, WaveKind, WaveSchedule, WorkflowConfig };

package/dist/index.d.ts

@@ -296,7 +296,17 @@ declare function migrateToV1_4_0(): Promise<MigrationResult>;
 declare function needsMigration(): Promise<boolean>;
 
 /**
- * Get current installed version from package.json
+ * Get current installed version.
+ *
+ * Resolution order:
+ *   1. BUILD_TIME_VERSION — baked into the bundle by unbuild. This is the
+ *      authoritative source for shipped binaries because it does not depend on
+ *      filesystem layout. Fixes the Windows-npx 0.0.0 → false migration bug.
+ *   2. relative package.json — used in dev (tsx) where step 1 is a placeholder.
+ *   3. walked-up package.json — last-resort for unusual runtime layouts.
+ *   4. npm_package_version env var — when run as an npm script.
+ *   5. '0.0.0' — only when everything above failed; callers must treat this as
+ *      "unknown" and skip version-gated branches (e.g. migration).
  */
 declare function getCurrentVersion(): Promise<string>;
 /**
@@ -317,6 +327,230 @@ declare function checkForUpdates(): Promise<{
     latestVersion: string | null;
 }>;
 
+/**
+ * 单轮收敛状态。
+ */
+interface ConvergeRound {
+    /** 第几轮（1-indexed） */
+    round: number;
+    /** 本轮 review 发现的 finding 数（按严重度分） */
+    findings: {
+        critical: number;
+        warning: number;
+        info: number;
+    };
+}
+
+/**
+ * Ralph Loop fix-log persistence (RFC-8 follow-up to fork v2.3.1).
+ *
+ * Context: fork already implements the Ralph Loop core (multi-round
+ * `--fix --auto` with `decideConverge()` + AUTO_CONVERGE_CAP=3 + stall
+ * detection + 4-step transactional cleanup). The only gap is **persistence**
+ * of the per-round ConvergeRound history.
+ *
+ * Today the main thread holds the history in conversation context. A `/clear`
+ * mid-loop, a session crash, or a long-running session that gets context-
+ * compacted all silently drop the history. `decideConverge` then sees an
+ * empty `history[]` on the next round and starts over — re-trying from
+ * round 1 instead of recognizing this is round 3 and escalating.
+ *
+ * Fix: append-only JSONL log at `.context/fix-log.jsonl`. The log survives
+ * `/clear` and session restarts; main-thread code reads it back to
+ * reconstruct the ConvergeRound[] before calling `decideConverge`.
+ *
+ * Design choices:
+ *   - JSONL (one JSON object per line) instead of one big JSON file. Append
+ *     is a single fs.appendFileSync call → atomic on POSIX and Windows
+ *     (single write() syscall, no read-modify-write race between writers).
+ *   - Two entry kinds: 'review' (records finding counts) and 'fix' (records
+ *     commits and status). `convergeHistoryFromLog` only consumes 'review'
+ *     entries because that is what `decideConverge` cares about.
+ *   - No mutex / file lock. Append-only + single-writer-per-task. If two
+ *     concurrent `/ccg:review --fix --auto` runs ever happen against the
+ *     same workdir they'll interleave lines but each line is still a valid
+ *     ConvergeRound — readers tolerate that.
+ *   - Tolerant parsing: a malformed line is skipped, not throwed on. The
+ *     log is advisory; a corrupt entry must not break the loop.
+ */
+
+/**
+ * Relative path inside the project where the JSONL log lives. Same
+ * `.context/` directory the sentinel + jobs/ live in.
+ */
+declare const FIX_LOG_RELATIVE_PATH = ".context/fix-log.jsonl";
+/**
+ * Per-round finding counts. Mirrors ConvergeRound.findings.
+ */
+interface FindingCounts {
+    critical: number;
+    warning: number;
+    info: number;
+}
+/**
+ * 'review' entries record a review-phase outcome (used to feed decideConverge).
+ * 'fix' entries record the corresponding code-fixer run (commits, status).
+ */
+type FixLogEntryKind = 'review' | 'fix';
+interface ReviewLogEntry {
+    kind: 'review';
+    /** ISO 8601 timestamp. */
+    ts: string;
+    /** 1-indexed round number, matches code-fixer's `auto_round`. */
+    round: number;
+    /** Counts produced by the review pass. */
+    findings: FindingCounts;
+    /** Optional free-form note (≤120 chars), e.g. "after second adversarial review". */
+    note?: string;
+}
+interface FixLogEntry {
+    kind: 'fix';
+    ts: string;
+    round: number;
+    /** Outcome of the code-fixer run for this round. */
+    status: 'completed' | 'partial' | 'escalated' | 'failed';
+    /** Atomic commits the fixer produced this round (sha7 strings). */
+    commits: string[];
+    note?: string;
+}
+type FixLogRecord = ReviewLogEntry | FixLogEntry;
+/**
+ * Absolute path of the fix-log for a given project workdir.
+ */
+declare function resolveFixLogPath(workdir: string): string;
+/**
+ * Atomically append a single record to `.context/fix-log.jsonl`. Creates the
+ * parent directory if missing. Single appendFileSync call → atomic at the
+ * fs syscall layer; no read-modify-write race for concurrent writers.
+ *
+ * Caller is responsible for picking the right `ts` and `round`. We do not
+ * generate timestamps here because tests want them to be deterministic.
+ */
+declare function appendFixLogEntry(workdir: string, entry: FixLogRecord): void;
+/**
+ * Read all valid entries from `.context/fix-log.jsonl`. Missing file → [].
+ * Malformed lines are skipped silently (the log is advisory; one corrupt
+ * line from an interrupted write must not break the loop).
+ */
+declare function readFixLog(workdir: string): FixLogRecord[];
+/**
+ * Project the log down to the ConvergeRound[] history that decideConverge
+ * consumes. Only 'review' entries contribute; 'fix' entries are for audit.
+ *
+ * Rounds are returned in append order. If the same `round` appears twice
+ * (e.g. user re-ran round 2 after editing files manually) the LAST entry
+ * wins — that matches what a human reviewer of the log file would expect.
+ */
+declare function convergeHistoryFromLog(entries: readonly FixLogRecord[]): ConvergeRound[];
+/**
+ * One-call helper for the main thread: read the on-disk log and return the
+ * ConvergeRound[] history ready to hand to decideConverge.
+ *
+ * Use this whenever the main thread might have lost in-context history
+ * (after `/clear`, session restart, or context compaction).
+ */
+declare function loadConvergeHistory(workdir: string): ConvergeRound[];
+
+/**
+ * Spec Evolution candidate extractor (RFC-9).
+ *
+ * fork走 OpenSpec (OPSX) 路线：所有规范变更通过 `changes/<id>/` proposals 进入
+ * `openspec/specs/` 主规范。本 helper 只负责一件事——在 `/ccg:spec-impl` 归档
+ * **前**，从本次 change 的 git diff + REVIEW.md 里抽出**可复用的、非显而易见的
+ * 约定**，让用户决定要不要让它们沉淀下去。
+ *
+ * 关键设计决策：
+ *
+ *  1. **纯函数，不读 fs，不调网络**。输入是已 collected 的文本 (diff + review)，
+ *     输出是候选条目数组。spec-impl.md 主线负责 IO 和用户确认。
+ *
+ *  2. **不直接写 OpenSpec deltas**。Deltas 是研究阶段产物；本 helper 抽的是
+ *     "实施阶段发现的坑"，与 deltas 异源。写入路径推荐
+ *     `changes/<change-id>/SPEC_EVOLUTION.md`，archive 时随 change 归档。
+ *
+ *  3. **强质量门**。模型很容易输出"写好的代码"、"注意安全"这种空洞条目，所有
+ *     候选必须含**具体文件路径或 API 名**，且长度 ≥ MIN_RATIONALE_CHARS。
+ *     不合格的候选被 `rejectionReason` 标出，让 spec-impl.md 主线在确认 UI 里
+ *     展示给用户审视（不是默默丢弃——用户可能想看到 helper 拒了什么）。
+ *
+ *  4. **绝不**自动写入。导出 `formatAsMarkdown` 让主线渲染，但用户确认前
+ *     主线必须用 `AskUserQuestion` 列出 candidates 让用户勾选。
+ *
+ * 上游 V3 phase-guide.md §8 的 5 步流程（提炼 → 分类 → 草拟 → 展示 → 写入）
+ * 在 fork 的对应实现是：
+ *   - helper.extractCandidates → 提炼 + 分类（一次完成）
+ *   - helper.formatAsMarkdown  → 草拟
+ *   - spec-impl.md AskUserQuestion → 展示给用户
+ *   - spec-impl.md Write/Edit → 写入（仅用户勾选的条目）
+ */
+/**
+ * 候选 spec 条目分类。OpenSpec 推荐 capability 维度，本 helper 用粗粒度三档：
+ *   - backend:       涉及 server / api / db / auth / 后端业务逻辑
+ *   - frontend:      涉及 UI / component / route / state management / 浏览器
+ *   - cross-cutting: 工程基建 / 跨层 / 构建 / 测试 / CI / 配置
+ *
+ * 调用方（spec-impl.md）可在用户确认时把这三档映射到 OpenSpec 的具体 capability
+ * 路径（例如 `specs/auth/spec.md`、`specs/ui-shell/spec.md`）。
+ */
+type SpecCategory = 'backend' | 'frontend' | 'cross-cutting';
+interface SpecCandidate {
+    /** 一行 ≤ 120 字的约束陈述（"X 必须 Y" 句式优先）。 */
+    statement: string;
+    /** 为什么要这样（≥ MIN_RATIONALE_CHARS 字符，引用具体文件/API）。 */
+    rationale: string;
+    /** 提炼来源：哪一行 diff / REVIEW.md finding。 */
+    source: {
+        kind: 'diff' | 'review';
+        excerpt: string;
+    };
+    /** 推荐归档分类（spec-impl.md 主线决定最终 capability 映射）。 */
+    category: SpecCategory;
+    /** 拒绝原因（如果质量门没过）。通过的为 undefined。 */
+    rejectionReason?: string;
+}
+interface ExtractInput {
+    /** `git diff <base>..HEAD` 文本。可空（极小 change 走纯 review 路径）。 */
+    gitDiff?: string;
+    /** REVIEW.md 全文。可空（无 review 阶段或 fix 全 critical=0 跳过）。 */
+    reviewMd?: string;
+    /** Change id（仅用于 source 引用，不参与提炼）。 */
+    changeId?: string;
+}
+/** rationale 必须够长——拒绝"写好的代码"、"注意安全"等空洞条目。 */
+declare const MIN_RATIONALE_CHARS = 40;
+/** statement 上限——太长就不是约定，是设计文档。 */
+declare const MAX_STATEMENT_CHARS = 200;
+declare function categorizeStatement(statement: string, rationale: string): SpecCategory;
+/**
+ * Returns the rejection reason or undefined if the candidate passes the gate.
+ * Designed to be human-readable — these strings are shown back to the user in
+ * spec-impl.md's confirmation UI so they understand why helper filtered things.
+ */
+declare function checkQuality(statement: string, rationale: string): string | undefined;
+/**
+ * Main entry. Returns all candidates (passed + rejected) so spec-impl.md can
+ * show the user the full picture. Caller filters by `!c.rejectionReason` when
+ * building the confirmation choices.
+ */
+declare function extractCandidates(input: ExtractInput): SpecCandidate[];
+/**
+ * Render the user-approved candidates as Markdown suitable for
+ * `changes/<change-id>/SPEC_EVOLUTION.md`.
+ *
+ * Output format is intentionally NOT OpenSpec delta syntax — this file is an
+ * audit trail of "things we learned implementing this change", not a binding
+ * spec proposal. Promoting a SPEC_EVOLUTION entry to an actual SHALL in
+ * `specs/<capability>/spec.md` is a separate, deliberate step the user takes
+ * later (via `/ccg:spec-research` for the next iteration).
+ *
+ * Includes the change-id and ISO date in the heading so an archived
+ * SPEC_EVOLUTION.md is self-describing.
+ */
+declare function formatAsMarkdown(approved: readonly SpecCandidate[], meta: {
+    changeId: string;
+    isoDate: string;
+}): string;
+
 /**
  * Phase-scoped context state machine (v4.0 Phase 2).
  *
@@ -1770,5 +2004,5 @@ declare function majorFindings(report: InterfaceAuditReport): InterfaceAuditFind
  */
 declare function hasBlockingFindings(report: InterfaceAuditReport): boolean;
 
-export { ALL_LAYERS, CONTEXT_BUDGET_THRESHOLD, DESCRIPTION_SOFT_LIMIT, ROUTING_SCHEMA_VERSION, aggregatePlans, auditSkillDescriptions, auditSkillsDirectory, auditTarballContents, batchByMaxConcurrent, bothPluginsInstalled, buildQualityPlan, buildWaves, cascadeSkip, changeLanguage, checkForUpdates, collectInvocableSkills, collectSkills, compareVersions, contextPath, createDefaultConfig, createDefaultRouting, decideFromSummaries, detectPlugin, detectPluginAvailability, estimateBriefLength, estimateTokens, extractFrontmatter, generateCommandContent, getCcgDir, getConfigPath, getCurrentVersion, getLatestVersion, getWorkflowById, getWorkflowConfigs, i18n, init, initI18n, installAceTool, installAceToolRs, installSkillCommands, installWorkflows, criticalFindings as interfaceAuditCriticals, hasBlockingFindings as interfaceAuditHasBlocking, majorFindings as interfaceAuditMajors, isLayer, migrateToV1_4_0, needsMigration, parseChallengerSummary, parseDependsOn, parseFrontmatter, parseFrontmatterFields, parseInterfaceAuditorReport, parseQualityFlag, parseRoadmap, parseRoleFlag, parseVerifyReport, phaseDir, planChallengerSpawns, planVerifyWave, planWavesForTier, promptFilePath, readCcgConfig, readContext, readSummary, readSummaryFrontmatter, renderAuditMarkdown, renderPipelineReport, resolveQualityTier, routeSpecialist, runPipelineCheck, runPnpmPack, sampleAll, sampleHookSchema, samplePackageStructure, samplePluginList, sampleSkillList, sanitizePhase, schedule, serializeBriefForPrompt, showMainMenu, summarizeGroundTruth, summaryPath, summaryTokenEstimate, synthesizeRevisionFeedback, synthesizeVerifyFeedback, synthesizeVerifyResults, uninstallAceTool, uninstallWorkflows, update, verifyAllCommandsIncluded, writeCcgConfig, writeContext, writeSummary };
-export type { AceToolConfig, AuditReport, AuditRow, CcgConfig, ChallengeInput, ChallengerAgent, ChallengerDecision, ChallengerPlan, ChallengerSummary, CliOptions, CollaborationMode, DesignBrief, Divergence, FastContextConfig, Finding, FindingSeverity, GroundTruth, PluginInfo as GroundTruthPluginInfo, SkillInfo as GroundTruthSkillInfo, HookInfo, InitOptions, InstallResult, InterfaceAuditCategory, InterfaceAuditFinding, InterfaceAuditReport, Layer, Model, ModelRouting, ModelType, PackageStructureInfo, PhaseContext, PhaseMeta, PhaseStatus, PhaseSummary, PipelineCheckOptions, PipelineCheckReport, PipelineError, PipelineErrorCategory, PlanContribution, PlanVerifyWaveOptions, PluginAdvisor, PluginAvailability, PluginAvailability as PluginDetectionAvailability, PluginDetectionResult, PluginName, QualityPlan, SpawnEntry as QualitySpawnEntry, QualityTier, WavePlan as QualityWavePlan, ResolveInput, RoadmapPhase, Role, PluginAvailability as RoutingPluginAvailability, RoutingStrategy, SampleOptions, ScheduleOptions, SkillCategory, SkillMeta, SkillRuntimeType, SpawnEntry$1 as SpawnEntry, SpecialistCritic, SpecialistLayer, SpecialistModel, SpecialistRole, SpecialistRoute, SupportedLang, VerifyDecision, VerifyInvocationMode, VerifyMode, VerifyReport, VerifySpawnEntry, VerifyWavePlan, WaveKind, WaveSchedule, WorkflowConfig };
+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, changeLanguage, checkForUpdates, checkQuality, collectInvocableSkills, collectSkills, compareVersions, contextPath, convergeHistoryFromLog, createDefaultConfig, createDefaultRouting, decideFromSummaries, detectPlugin, detectPluginAvailability, estimateBriefLength, estimateTokens, extractCandidates, extractFrontmatter, formatAsMarkdown, generateCommandContent, getCcgDir, getConfigPath, getCurrentVersion, getLatestVersion, getWorkflowById, getWorkflowConfigs, i18n, init, initI18n, installAceTool, installAceToolRs, installSkillCommands, installWorkflows, criticalFindings as interfaceAuditCriticals, hasBlockingFindings as interfaceAuditHasBlocking, majorFindings as interfaceAuditMajors, isLayer, loadConvergeHistory, migrateToV1_4_0, needsMigration, parseChallengerSummary, parseDependsOn, parseFrontmatter, parseFrontmatterFields, parseInterfaceAuditorReport, parseQualityFlag, parseRoadmap, parseRoleFlag, parseVerifyReport, phaseDir, planChallengerSpawns, planVerifyWave, planWavesForTier, promptFilePath, readCcgConfig, readContext, readFixLog, readSummary, readSummaryFrontmatter, renderAuditMarkdown, renderPipelineReport, resolveFixLogPath, resolveQualityTier, routeSpecialist, runPipelineCheck, runPnpmPack, sampleAll, sampleHookSchema, samplePackageStructure, samplePluginList, sampleSkillList, sanitizePhase, schedule, serializeBriefForPrompt, showMainMenu, summarizeGroundTruth, summaryPath, summaryTokenEstimate, synthesizeRevisionFeedback, synthesizeVerifyFeedback, synthesizeVerifyResults, uninstallAceTool, uninstallWorkflows, update, verifyAllCommandsIncluded, writeCcgConfig, writeContext, writeSummary };
+export type { AceToolConfig, AuditReport, AuditRow, CcgConfig, ChallengeInput, ChallengerAgent, ChallengerDecision, ChallengerPlan, ChallengerSummary, CliOptions, CollaborationMode, DesignBrief, Divergence, ExtractInput, FastContextConfig, Finding, FindingCounts, FindingSeverity, FixLogEntry, FixLogEntryKind, FixLogRecord, GroundTruth, PluginInfo as GroundTruthPluginInfo, SkillInfo as GroundTruthSkillInfo, HookInfo, InitOptions, InstallResult, InterfaceAuditCategory, InterfaceAuditFinding, InterfaceAuditReport, Layer, Model, ModelRouting, ModelType, PackageStructureInfo, PhaseContext, PhaseMeta, PhaseStatus, PhaseSummary, PipelineCheckOptions, PipelineCheckReport, PipelineError, PipelineErrorCategory, PlanContribution, PlanVerifyWaveOptions, PluginAdvisor, PluginAvailability, PluginAvailability as PluginDetectionAvailability, PluginDetectionResult, PluginName, QualityPlan, SpawnEntry as QualitySpawnEntry, QualityTier, WavePlan as QualityWavePlan, ResolveInput, ReviewLogEntry, RoadmapPhase, Role, PluginAvailability as RoutingPluginAvailability, RoutingStrategy, SampleOptions, ScheduleOptions, SkillCategory, SkillMeta, SkillRuntimeType, SpawnEntry$1 as SpawnEntry, SpecCandidate, SpecCategory, SpecialistCritic, SpecialistLayer, SpecialistModel, SpecialistRole, SpecialistRoute, SupportedLang, VerifyDecision, VerifyInvocationMode, VerifyMode, VerifyReport, VerifySpawnEntry, VerifyWavePlan, WaveKind, WaveSchedule, WorkflowConfig };