ccgx-workflow 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1774 @@
+import * as i18next from 'i18next';
+
+interface CliOptions {
+    lang?: SupportedLang;
+    force?: boolean;
+    skipPrompt?: boolean;
+    skipMcp?: boolean;
+    frontend?: string;
+    backend?: string;
+    mode?: CollaborationMode;
+    workflows?: string;
+    installDir?: string;
+    /** v4.1-p18: --sync mode, list locally-installed CCG files no longer in templates */
+    sync?: boolean;
+}
+
+type SupportedLang = 'zh-CN' | 'en';
+type ModelType = 'codex' | 'gemini' | 'claude';
+type CollaborationMode = 'parallel' | 'smart' | 'sequential';
+type RoutingStrategy = 'parallel' | 'fallback' | 'round-robin';
+interface ModelRouting {
+    frontend: {
+        models: ModelType[];
+        primary: ModelType;
+        strategy: RoutingStrategy;
+    };
+    backend: {
+        models: ModelType[];
+        primary: ModelType;
+        strategy: RoutingStrategy;
+    };
+    review: {
+        models: ModelType[];
+        strategy: 'parallel';
+    };
+    mode: CollaborationMode;
+    geminiModel?: string;
+}
+interface CcgConfig {
+    general: {
+        version: string;
+        language: SupportedLang;
+        createdAt: string;
+    };
+    routing: ModelRouting;
+    workflows: {
+        installed: string[];
+    };
+    paths: {
+        commands: string;
+        prompts: string;
+        backup: string;
+    };
+    mcp: {
+        provider: string;
+        setup_url: string;
+    };
+    performance?: {
+        liteMode?: boolean;
+        skipImpeccable?: boolean;
+    };
+}
+interface WorkflowConfig {
+    id: string;
+    name: string;
+    nameEn: string;
+    category: string;
+    commands: string[];
+    defaultSelected: boolean;
+    order: number;
+    description?: string;
+    descriptionEn?: string;
+}
+interface InitOptions {
+    lang?: SupportedLang;
+    skipPrompt?: boolean;
+    skipMcp?: boolean;
+    force?: boolean;
+    frontend?: string;
+    backend?: string;
+    mode?: CollaborationMode;
+    workflows?: string;
+    installDir?: string;
+    /** v4.1-p18: --sync mode (read-only diff, prompt user to delete stale files) */
+    sync?: boolean;
+}
+interface InstallResult {
+    success: boolean;
+    installedCommands: string[];
+    installedPrompts: string[];
+    installedSkills?: number;
+    installedSkillCommands?: number;
+    installedRules?: boolean;
+    errors: string[];
+    configPath: string;
+    binPath?: string;
+    binInstalled?: boolean;
+}
+interface AceToolConfig {
+    baseUrl: string;
+    token: string;
+}
+interface FastContextConfig {
+    apiKey?: string;
+    includeSnippets?: boolean;
+}
+
+declare function init(options?: InitOptions): Promise<void>;
+
+declare function showMainMenu(): Promise<void>;
+
+/**
+ * Main update command - checks for updates and installs if available
+ */
+declare function update(): Promise<void>;
+
+declare const i18n: i18next.i18n;
+declare function initI18n(lang?: SupportedLang): Promise<void>;
+declare function changeLanguage(lang: SupportedLang): Promise<void>;
+
+declare function getCcgDir(): string;
+declare function getConfigPath(): string;
+declare function readCcgConfig(): Promise<CcgConfig | null>;
+declare function writeCcgConfig(config: CcgConfig): Promise<void>;
+declare function createDefaultConfig(options: {
+    language: SupportedLang;
+    routing: ModelRouting;
+    installedWorkflows: string[];
+    mcpProvider?: string;
+    liteMode?: boolean;
+    skipImpeccable?: boolean;
+}): CcgConfig;
+declare function createDefaultRouting(): ModelRouting;
+
+declare function getWorkflowConfigs(): WorkflowConfig[];
+declare function getWorkflowById(id: string): WorkflowConfig | undefined;
+
+type McpInstallResult = {
+    success: boolean;
+    message: string;
+    configPath?: string;
+};
+/**
+ * Uninstall ace-tool MCP configuration from ~/.claude.json
+ */
+declare function uninstallAceTool(): Promise<{
+    success: boolean;
+    message: string;
+}>;
+/**
+ * Install and configure ace-tool MCP for Claude Code.
+ */
+declare function installAceTool(config: AceToolConfig): Promise<McpInstallResult>;
+/**
+ * Install and configure ace-tool-rs MCP for Claude Code.
+ * ace-tool-rs is a Rust implementation — more lightweight and faster.
+ */
+declare function installAceToolRs(config: AceToolConfig): Promise<McpInstallResult>;
+
+/**
+ * Skill Registry — SKILL.md frontmatter 驱动的技能发现与命令生成
+ *
+ * 移植自 code-abyss skill-registry.js，TypeScript 化。
+ * 核心功能：
+ * 1. 递归扫描 templates/skills/ 下所有 SKILL.md
+ * 2. 解析 frontmatter 提取 name/description/user-invocable 等元数据
+ * 3. 为 user-invocable=true 的技能自动生成 slash commands
+ */
+type SkillCategory = 'tool' | 'domain' | 'orchestration' | 'impeccable' | 'root';
+type SkillRuntimeType = 'scripted' | 'knowledge';
+interface SkillMeta {
+    /** kebab-case slug, e.g. 'red-team' */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Whether to auto-generate a slash command */
+    userInvocable: boolean;
+    /** Allowed Claude tools for this skill */
+    allowedTools: string[];
+    /** Argument hint shown to user, e.g. '[target]' */
+    argumentHint: string;
+    /** Optional aliases for the skill name */
+    aliases: string[];
+    /** Inferred from directory: tool/domain/orchestration/impeccable/root */
+    category: SkillCategory;
+    /** scripted (has scripts/) or knowledge (no scripts) */
+    runtimeType: SkillRuntimeType;
+    /** Relative path from skills root, e.g. 'domains/security' */
+    relPath: string;
+    /** Absolute path to the SKILL.md file */
+    skillPath: string;
+    /** Absolute path to the script .js file (if scripted) */
+    scriptPath: string | null;
+    /**
+     * v4.1-p19: Context isolation hint.
+     * - `fork`: heavy skills should be loaded in fresh-context subagent (domains/impeccable)
+     * - `inline` (default): lightweight skills loaded in main thread (tools/)
+     */
+    context: 'fork' | 'inline';
+    /**
+     * v4.1-p19: Glob path filters.
+     * Skill is only activated when matching files exist (e.g. *.tsx for frontend skills).
+     * Empty array = always active.
+     */
+    paths: string[];
+}
+/**
+ * Parse YAML frontmatter from a markdown file.
+ * Returns a plain key-value object, or null if no frontmatter found.
+ */
+declare function parseFrontmatter(content: string): Record<string, string> | null;
+/**
+ * Recursively scan a skills directory and collect all valid skill definitions.
+ */
+declare function collectSkills(skillsDir: string): SkillMeta[];
+/**
+ * Collect only user-invocable skills.
+ */
+declare function collectInvocableSkills(skillsDir: string): SkillMeta[];
+/**
+ * Generate slash command content for a user-invocable skill.
+ *
+ * For knowledge skills: instructs Claude to read the SKILL.md and follow its guidance.
+ * For scripted skills: runs the script via run_skill.js.
+ */
+declare function generateCommandContent(skill: SkillMeta, skillsInstallDir: string): string;
+/**
+ * Install auto-generated commands for all user-invocable skills.
+ *
+ * @param skillsTemplateDir - Path to templates/skills/ (source)
+ * @param skillsInstallDir - Path to ~/.claude/skills/ccg/ (installed destination)
+ * @param commandsDir - Path to ~/.claude/commands/ccg/ (command output)
+ * @param existingCommandNames - Set of command names already defined in installer-data.ts (to avoid conflicts)
+ * @returns List of generated command names
+ */
+declare function installSkillCommands(skillsTemplateDir: string, skillsInstallDir: string, commandsDir: string, existingCommandNames: Set<string>, skipCategories?: SkillCategory[]): Promise<string[]>;
+
+declare function installWorkflows(workflowIds: string[], installDir: string, force?: boolean, config?: {
+    routing?: {
+        mode?: string;
+        frontend?: {
+            models?: string[];
+            primary?: string;
+        };
+        backend?: {
+            models?: string[];
+            primary?: string;
+        };
+        review?: {
+            models?: string[];
+        };
+    };
+    liteMode?: boolean;
+    mcpProvider?: string;
+    skipImpeccable?: boolean;
+}): Promise<InstallResult>;
+interface UninstallResult {
+    success: boolean;
+    removedCommands: string[];
+    removedPrompts: string[];
+    removedAgents: string[];
+    removedSkills: string[];
+    removedRules: boolean;
+    removedBin: boolean;
+    errors: string[];
+}
+/**
+ * Uninstall workflows by removing their command files.
+ * @param options.preserveBinary — when true, skip binary removal (used during update)
+ */
+declare function uninstallWorkflows(installDir: string, options?: {
+    preserveBinary?: boolean;
+}): Promise<UninstallResult>;
+
+/**
+ * Migration utilities for v1.4.0
+ * Handles automatic migration from old directory structure to new one
+ */
+interface MigrationResult {
+    success: boolean;
+    migratedFiles: string[];
+    errors: string[];
+    skipped: string[];
+}
+/**
+ * Migrate from v1.3.x to v1.4.0
+ *
+ * Changes:
+ * 1. ~/.ccg/ → ~/.claude/.ccg/
+ * 2. ~/.claude/prompts/ccg/ → ~/.claude/.ccg/prompts/
+ */
+declare function migrateToV1_4_0(): Promise<MigrationResult>;
+/**
+ * Check if migration is needed
+ */
+declare function needsMigration(): Promise<boolean>;
+
+/**
+ * Get current installed version from package.json
+ */
+declare function getCurrentVersion(): Promise<string>;
+/**
+ * Get latest version from npm registry
+ */
+declare function getLatestVersion(packageName?: string): Promise<string | null>;
+/**
+ * Compare two semantic versions
+ * @returns 1 if v1 > v2, -1 if v1 < v2, 0 if equal
+ */
+declare function compareVersions(v1: string, v2: string): number;
+/**
+ * Check if update is available
+ */
+declare function checkForUpdates(): Promise<{
+    hasUpdate: boolean;
+    currentVersion: string;
+    latestVersion: string | null;
+}>;
+
+/**
+ * Phase-scoped context state machine (v4.0 Phase 2).
+ *
+ * Manages `.context/<phase>/{CONTEXT,SUMMARY}.md` files that decouple the
+ * orchestrator (main thread) from builder subagents:
+ *
+ * - CONTEXT.md  — frozen decisions from /ccg:plan, consumed by downstream
+ *                 plan/exec stages. Markdown body is human-readable; YAML
+ *                 frontmatter is machine-readable.
+ * - SUMMARY.md  — machine-readable frontmatter written by /ccg:execute
+ *                 (and team-exec) after each plan completes. The orchestrator
+ *                 reads ONLY the frontmatter (< 200 tokens / phase) instead of
+ *                 piping back the full builder stdout.
+ *
+ * Token budget contract: parsing 5 SUMMARY.md frontmatters MUST stay < 1000
+ * tokens of orchestrator context (the `summaryTokenEstimate` helper makes this
+ * empirically verifiable in unit tests).
+ */
+interface PhaseContext {
+    phase: string;
+    plan: string;
+    goal: string;
+    decisions: string[];
+    constraints: string[];
+    files: string[];
+    createdAt: string;
+}
+interface PhaseSummary {
+    phase: string;
+    plan: string;
+    provides: string[];
+    affects: string[];
+    keyFiles: string[];
+    completed: boolean;
+    completedAt?: string;
+    notes?: string;
+}
+/**
+ * Resolve the directory holding phase-scoped state files.
+ * Convention: `<workdir>/.context/<phase>/`.
+ */
+declare function phaseDir(workdir: string, phase: string): string;
+declare function contextPath(workdir: string, phase: string): string;
+declare function summaryPath(workdir: string, phase: string): string;
+/**
+ * Strip filesystem-hostile characters from a phase id so it can be used as a
+ * directory name on Windows / macOS / Linux. Keeps alphanumerics, dashes,
+ * underscores and dots; collapses everything else to `-`.
+ */
+declare function sanitizePhase(phase: string): string;
+/**
+ * Extract the YAML frontmatter block from a Markdown file. Returns `null` if
+ * the file does not start with `---\n`.
+ */
+declare function extractFrontmatter(content: string): string | null;
+/**
+ * Parse a small subset of YAML — enough for SUMMARY.md frontmatter:
+ *
+ *   key: scalar value
+ *   key: [a, b, c]
+ *   key:
+ *     - a
+ *     - b
+ *
+ * Quoted strings (single or double) are unwrapped. No anchors, no nested maps.
+ * Throws on malformed input — keeps parser small and predictable.
+ */
+declare function parseFrontmatterFields(yaml: string): Record<string, string | string[] | boolean>;
+/**
+ * Write `.context/<phase>/CONTEXT.md` capturing the frozen decisions from
+ * /ccg:plan. The body is plain Markdown so it remains diffable; the
+ * frontmatter is the machine-readable contract.
+ */
+declare function writeContext(workdir: string, ctx: PhaseContext): string;
+declare function readContext(workdir: string, phase: string): PhaseContext | null;
+/**
+ * Write `.context/<phase>/SUMMARY.md`. The orchestrator must be able to make
+ * advance / retry / skip decisions reading ONLY this file's frontmatter.
+ *
+ * Frontmatter fields (acceptance b):
+ *   phase, plan, provides, affects, key-files (key_files), completed,
+ *   completed_at, notes
+ */
+declare function writeSummary(workdir: string, summary: PhaseSummary): string;
+declare function readSummary(workdir: string, phase: string): PhaseSummary | null;
+/**
+ * Read only the frontmatter block of SUMMARY.md without parsing the body.
+ * This is the path orchestrators (autonomous, team-exec) must take to keep
+ * context usage bounded.
+ *
+ * Returns the frontmatter raw text, or `null` if the file does not exist.
+ */
+declare function readSummaryFrontmatter(workdir: string, phase: string): string | null;
+/**
+ * Estimate the orchestrator token cost of reading a frontmatter block.
+ * Conservative heuristic: ceil(chars / 3.5). Not exact tokenization, but
+ * tight enough that test assertions stay valid against real tokenizers.
+ */
+declare function summaryTokenEstimate(frontmatter: string): number;
+
+/**
+ * Wave Scheduler (CCG v4.1 Phase 14).
+ *
+ * `/ccg:autonomous --parallel` 的依赖图调度核心。把扁平的 phase 序列按
+ * `Depends on` 字段拓扑排序成 wave（无依赖 → wave 1，依赖 wave 1 → wave 2，
+ * ...），波内 phase 没有依赖关系可主线一次性并行 spawn `Agent(phase-runner)`。
+ *
+ * 设计原则（与 v4.0 phase-context.ts / debug-session.ts 一致）：
+ *   - 纯函数；不读文件系统、不 spawn 子进程
+ *   - 输入 markdown 字符串 / 结构化对象，输出结构化结果
+ *   - 跨平台：无路径假设
+ *   - 失败用 throw + 明确错误信息（依赖循环 / 引用未知 phase）
+ *
+ * 调用方：
+ *   - `templates/commands/autonomous.md` Step 4.0（解析 roadmap）
+ *   - `templates/commands/autonomous.md` Step 4.2（按 wave 并行 spawn）
+ *
+ * 不做：
+ *   - 不实际 spawn Agent（那是主线 LLM 的职责，本 helper 只决定 wave 划分）
+ *   - 不写 `.ccg/roadmap.md`（autonomous 主线唯一写者）
+ *   - 不读 SUMMARY.md / state.md（与 phase-context / team-exec 协议解耦）
+ */
+type PhaseStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped';
+/**
+ * 单个 phase 的最小结构化记录。从 roadmap.md 的 `## Phase N: <name> (<status>)`
+ * 标题 + `- **Depends on**: ...` 行解析得到。
+ *
+ * `id` 保留为字符串以容纳 "1.5" 这类小数 phase 编号（v3.1 / v4.0 实际场景）。
+ */
+interface RoadmapPhase {
+    /** phase 标识，例如 "1" / "1.5" / "13" */
+    id: string;
+    /** phase 标题（不含 "Phase N: " 前缀和状态括号） */
+    name: string;
+    /** 状态括号内的关键字 */
+    status: PhaseStatus;
+    /** 依赖的 phase id 列表。`(none)` 表示空 */
+    dependsOn: string[];
+}
+/**
+ * Wave 调度结果。`waves[i]` 是第 i+1 wave 内的 phase id 列表（顺序无意义，波内
+ * 可以并行）。`skipped` 是因上游 failed/skipped 而 cascade 标 blocked 的 phase。
+ */
+interface WaveSchedule {
+    /** waves[0] = wave 1（最先跑），waves[1] = wave 2，... */
+    waves: string[][];
+    /** cascade-skip 决策的 phase id 集合 */
+    skipped: string[];
+    /** wave-i phase 数量超过 maxConcurrent 时的批分组：batches[w][b] = wave w 第 b 批 */
+    batches?: string[][][];
+}
+/**
+ * 解析 roadmap.md 文本，抽出每个 phase 的 id / name / status / dependsOn。
+ *
+ * 容错原则：
+ *   - phase 标题正则不匹配的行直接忽略（roadmap.md 含里程碑总结表等噪音）
+ *   - 单个 phase 没有 `- **Depends on**:` 行视为 `(none)`（向后兼容老格式）
+ *   - 同一 phase 出现多次（不该发生）时后者覆盖前者并 throw
+ *
+ * 抛错场景：phase id 重复声明 / 状态值不合法
+ */
+declare function parseRoadmap(content: string): RoadmapPhase[];
+/**
+ * 解析 `Depends on` 字段右侧的内容，支持：
+ *   - `(none)` → []
+ *   - `1` → ["1"]
+ *   - `6, 8` → ["6", "8"]
+ *   - `1-11` → ["1", "2", ..., "11"]（整数范围；不展开 "1-1.5"）
+ *   - 混合："1, 3-5, 8" → ["1", "3", "4", "5", "8"]
+ */
+declare function parseDependsOn(raw: string): string[];
+/**
+ * 把 phase 列表按依赖图拓扑分波。Kahn 算法每轮选出当前没未满足依赖的 phase
+ * 集合作为下一 wave，从图中移除后继续。
+ *
+ * 行为：
+ *   - 引用未知 phase（`Depends on: 99` 而无 Phase 99）→ throw
+ *   - 依赖循环（A → B → A）→ throw（剩余 phase 没人能进 wave）
+ *   - 输入空数组 → 返回空 waves
+ *   - phase 顺序不影响 wave 分组，但同 wave 内 phase 按输入声明顺序保留
+ *
+ * @param phases 解析后的 phase 列表
+ * @returns wave 划分（waves[i] 内 phase 可并行）
+ */
+declare function buildWaves(phases: RoadmapPhase[]): string[][];
+/**
+ * 计算 cascade-skip 集合：当某 phase 状态为 `failed` 或 `skipped` 时，所有
+ * 依赖（直接或间接）该 phase 的 phase 都标 skipped。
+ *
+ * 输入是已 status-标注的 phase 列表（来自 parseRoadmap 或 mock）；返回
+ * **新增**应被 cascade-skip 的 phase id 集合（不重复列出已经 failed/skipped 的）。
+ *
+ * @param phases 全量 phase
+ * @returns 应 cascade-skip 的 phase id 列表（按 phase 输入顺序去重）
+ */
+declare function cascadeSkip(phases: RoadmapPhase[]): string[];
+/**
+ * 把单个 wave 按 maxConcurrent 切分成多个批次（顺序执行批，批内并行）。
+ *
+ * 例：wave = [a, b, c, d, e, f]，maxConcurrent = 2 → batches = [[a,b],[c,d],[e,f]]
+ *
+ * @param wave 单 wave 的 phase 列表
+ * @param maxConcurrent 每批最大并发数（≥ 1）
+ * @returns 批次数组
+ */
+declare function batchByMaxConcurrent(wave: string[], maxConcurrent: number): string[][];
+interface ScheduleOptions {
+    /** 单 wave 最大并发数；省略则不分批 */
+    maxConcurrent?: number;
+    /** 是否仅调度 status=pending 或 in_progress 的 phase（默认 true，跳过 completed） */
+    skipCompleted?: boolean;
+}
+/**
+ * 一站式调度：解析 → cascade skip → 拓扑分波 → 可选批分组。
+ *
+ * 完整 schedule 流程，autonomous Step 4.0 直接调用即可。
+ *
+ * @param phases 已解析的 phase 列表（来自 parseRoadmap）
+ * @param options 调度参数
+ */
+declare function schedule(phases: RoadmapPhase[], options?: ScheduleOptions): WaveSchedule;
+
+/**
+ * Multi-Model Routing — Single Source of Truth (CCG v4.2 Phase 21).
+ *
+ * v4.1 收尾审计揭示 4 个独立路由模块（specialist-router / challenger-orchestrator /
+ * debate-orchestrator / phase-runner）各自定义 layer / model / availability 类型，
+ * 类型并集相同但 export 路径不同，导致：
+ *   - 跨模块 import 时类型不互通（PluginAvailability 重复定义即一例）
+ *   - 任一模块新增 layer 时其他模块不会同步
+ *   - 路由假设无法集中审计
+ *
+ * 本模块作为 SSoT 把 4 个路由共用的核心 union types 全部上提到此处，
+ * 由各路由模块 re-export 给业务消费者。本模块**不实现路由逻辑**，
+ * 只统一类型；逻辑仍在各 router/orchestrator 中。
+ *
+ * 设计原则：
+ *   - 纯类型 + 极少量纯函数辅助；不读文件、不 spawn
+ *   - union string literal 类型（不引入 enum，与 v4.1 风格一致）
+ *   - 各 router 通过 re-export 暴露给 src/index.ts，外部消费者不感知拆分
+ *
+ * 不做：
+ *   - 不替代各 router 的具体路由表（routeSpecialist / planChallengerSpawns / debateStateMachine）
+ *   - 不暴露已退役的 SpecialistLayer / DebateLayer / PhaseType 别名（v4.2 起统一为 Layer）
+ */
+/**
+ * 实施 / 对辩 / challenger / phase-runner 路由共用的 layer union。
+ *
+ * v4.1 历史：specialist-router 用 'backend' | 'frontend' | 'fullstack'，
+ * debate-orchestrator 同；phase-runner 多了 'docs' | 'generic'。v4.2 起统一为
+ * 5 项并集——具体路由模块按需在 switch 里覆盖各自支持的子集。
+ */
+type Layer = 'backend' | 'frontend' | 'fullstack' | 'docs' | 'generic';
+/** 所有合法 Layer 的运行期数组（保持与 type 同步） */
+declare const ALL_LAYERS: readonly Layer[];
+/** 类型守卫：运行期 layer 校验 */
+declare function isLayer(value: unknown): value is Layer;
+/**
+ * CCG 路由可达的底层模型 union。
+ *   - codex / gemini：plugin subagent（Agent: `codex:codex-rescue` / `gemini:gemini-rescue` 双前缀；Skill: `codex:rescue` / `gemini:rescue` 单前缀）
+ *   - claude：主线 Claude，无 external prompt
+ *   - general-purpose：plugin 缺失降级（debate-orchestrator）；CCG 自家 prompt 模板兜底
+ */
+type Model = 'codex' | 'gemini' | 'claude' | 'general-purpose';
+/**
+ * Plugin 可用性。由 plugin-detection 模块在 orchestrator 启动前探测填充。
+ *
+ * 历史：plugin-detection.ts 与 challenger-orchestrator.ts 各定义一份完全相同的
+ * interface 各自 export 给 src/index.ts（`PluginAvailability` +
+ * `PluginDetectionAvailability` 两个名字）。v4.2 起合并为单一定义。
+ */
+interface PluginAvailability {
+    codex: boolean;
+    gemini: boolean;
+}
+/**
+ * 跨 specialist-router / challenger 共用的语义角色 union。
+ *
+ * 历史：specialist-router 用 5 项 (architect|critic|implementer|tester|writer)，
+ * challenger-orchestrator 隐式用 advisor/critic 区分。v4.2 SSoT 收并到
+ * 一个 7 项并集，各路由按需子集消费。
+ *
+ * 角色含义（参考 v4.1 各 module 注释）：
+ *   - architect:    建设性视角（propose/build）
+ *   - critic:       对抗性视角（adversarial review）
+ *   - implementer:  实施代码改动；v4.2 起 specialist-router 不再借用 architect.md
+ *   - tester:       撰写测试
+ *   - writer:       撰写文档 / 文案；主线 Claude 接管多数场景
+ *   - advisor:      challenger 中的 plugin 角色（codex/gemini rescue）
+ *   - verifier:     verify-work 编排里的校验角色（v4.2 P22 预留）
+ */
+type Role = 'architect' | 'critic' | 'implementer' | 'tester' | 'writer' | 'advisor' | 'verifier';
+/**
+ * SSoT 模块版本号。任何 union 调整时 bump，触发依赖模块在 type-check 阶段
+ * 显式 import 此常量做兼容声明（可选；目前未强制）。
+ */
+declare const ROUTING_SCHEMA_VERSION: "4.2.0";
+
+/**
+ * Specialist matrix router (CCG v4.1 Phase 15)
+ *
+ * 6 core commands (`/ccg:plan`, `/ccg:analyze`, `/ccg:debug`, `/ccg:review`,
+ * `/ccg:optimize`, `/ccg:test`) accept an optional `--role=<name>` flag that
+ * selects a specialized prompt file from `templates/prompts/{codex,gemini,
+ * claude}/<role>.md`. Combined with the implicit *layer* derived from file
+ * type (backend / frontend / fullstack), this forms a 5×3 routing matrix.
+ *
+ * This module is the **single source of truth** for the matrix. Command
+ * templates (markdown) reference it conceptually via documentation; tests
+ * pin its behavior so future refactors stay in sync. Templates themselves
+ * remain plain markdown — Claude reads the `--role` flag and picks the
+ * prompt file path documented in the template's "Role-based routing"
+ * section, which in turn is generated to mirror this matrix.
+ *
+ * v4.0 backward compatibility: when `role` is omitted (`null`), callers fall
+ * back to the legacy `{{BACKEND_PRIMARY}} / {{FRONTEND_PRIMARY}}` template
+ * variable routing — i.e. nothing changes for existing users.
+ */
+
+type SpecialistRole = 'architect' | 'critic' | 'implementer' | 'tester' | 'writer';
+/**
+ * Specialist 路由识别的 layer 子集。
+ * SSoT `Layer` 5 项中 specialist-router 仅消费 backend/frontend/fullstack。
+ * docs / generic 在 specialist-router 上下文不适用——由调用方在 v4.0 fallback 路由覆盖。
+ */
+type SpecialistLayer = Extract<Layer, 'backend' | 'frontend' | 'fullstack'>;
+/**
+ * Which underlying model owns a given (role, layer) intersection.
+ * `claude` here means "main thread / no external model spawn".
+ *
+ * v4.2 P21 起继承自 multi-model-routing SSoT 的 Model union（取 codex/gemini/claude 子集）。
+ */
+type SpecialistModel = 'codex' | 'gemini' | 'claude';
+interface SpecialistRoute {
+    /**
+     * Resolved model(s). For `fullstack` × {architect, critic} this is two
+     * models running in parallel (codex + gemini). For other slots a single
+     * model is returned.
+     */
+    models: SpecialistModel[];
+    /**
+     * Path-relative (under `~/.claude/.ccg/prompts/<model>/`) prompt file name
+     * for each model in `models`, in the same order. `null` entries mean the
+     * main thread (Claude) handles the slot directly without an external
+     * prompt file (e.g. `writer × backend`).
+     */
+    promptFiles: (string | null)[];
+    /**
+     * `true` for the `critic` role — caller must inject "adversarial review"
+     * framing (deliberately hunt for flaws / contradict majority view).
+     */
+    adversarial: boolean;
+    /**
+     * `true` when the underlying spec leaves the call site to runner-decided
+     * (e.g. fullstack implementer/tester picks codex OR gemini per file).
+     * Caller falls back to v4.0 layer-based routing in that case.
+     */
+    runnerDecides: boolean;
+}
+/**
+ * Resolve the (role × layer) intersection to one or more model invocations.
+ *
+ * Routing matrix (mirrors phase-15-specialist-matrix acceptance a):
+ *
+ * | Role × Layer  | architect      | critic              | implementer | tester        | writer |
+ * | backend       | codex          | codex (adversarial) | codex       | codex         | claude |
+ * | frontend      | gemini         | gemini (adversarial)| gemini      | gemini        | gemini |
+ * | fullstack     | codex+gemini   | both debate         | runner 决   | runner 决     | claude |
+ */
+declare function routeSpecialist(role: SpecialistRole, layer: SpecialistLayer): SpecialistRoute;
+/**
+ * Parse a `--role=<name>` CLI flag fragment, tolerant of whitespace and
+ * surrounding text. Returns `null` if no recognized role flag is present
+ * (caller should then fall back to v4.0 layer-only routing).
+ */
+declare function parseRoleFlag(args: string): SpecialistRole | null;
+/**
+ * Build the absolute prompt file path that command templates reference.
+ * Returns null entries unchanged (writer × backend → main-thread).
+ */
+declare function promptFilePath(model: SpecialistModel, promptFile: string | null): string | null;
+
+/**
+ * Skill Description Audit (v4.1-p19, ROI #2 / #3)
+ *
+ * Scans templates/skills/**\/SKILL.md and audits the `description` frontmatter
+ * field. Flags descriptions that exceed the 80-character soft limit (descriptions
+ * are loaded into Claude's context budget — long descriptions inflate every
+ * conversation that touches the skill registry).
+ *
+ * Companion to v4.1-p19 skill system optimization:
+ * - C1: this audit script + 80-char soft limit + 1% context budget warning
+ * - C2: `context: fork` frontmatter on heavy skills (domains/, impeccable/)
+ * - C3: `paths` filter on frontend-design skills
+ * - A3: Chinese translation of impeccable descriptions (preserve trigger keywords)
+ */
+
+/** Soft limit for description length (chars). Above this we flag for audit. */
+declare const DESCRIPTION_SOFT_LIMIT = 80;
+/**
+ * 1% context budget threshold (in chars).
+ * Default Claude context window ≈ 200k tokens ≈ 800k chars,
+ * 1% ≈ 8000 chars. If total skill descriptions exceed this,
+ * the registry alone consumes 1%+ of context on every load.
+ */
+declare const CONTEXT_BUDGET_THRESHOLD = 8000;
+interface AuditRow {
+    name: string;
+    category: string;
+    length: number;
+    overLimit: boolean;
+    description: string;
+}
+interface AuditReport {
+    rows: AuditRow[];
+    totalLength: number;
+    overLimitCount: number;
+    budgetExceeded: boolean;
+    budgetThreshold: number;
+}
+/**
+ * Audit a list of skill metadata records, producing per-row length + overall
+ * budget analysis.
+ */
+declare function auditSkillDescriptions(skills: SkillMeta[]): AuditReport;
+/**
+ * Convenience wrapper: scan a skills directory then audit its contents.
+ */
+declare function auditSkillsDirectory(skillsDir: string): AuditReport;
+/**
+ * Render a markdown table of the audit, sorted by length descending so the
+ * worst offenders are at the top.
+ */
+declare function renderAuditMarkdown(report: AuditReport): string;
+
+/**
+ * Challenger Orchestrator (CCG v4.1 Phase 16).
+ *
+ * Critical phase（roadmap.md frontmatter `Critical: true`）在 phase-runner
+ * 实施完成后，由**主线** spawn 一组 challenger agents 做"双视角对辩 + 假设/边界
+ * 审计"，再综合反馈让 implementer 修订一轮。
+ *
+ * v4.0.1 commit a7cdffd 实测证伪 subagent 嵌套 spawn —— 所以这是**主线扁平化**
+ * 编排（spawn implementer → 接 200-token 摘要 → 主线判 Critical → spawn
+ * challenger group → 综合 → spawn implementer 修订），而不是 phase-runner
+ * 内部 spawn challenger。
+ *
+ * 设计原则（与 v4.1 wave-scheduler / specialist-router 一致）：
+ *   - 纯函数；不读文件系统、不 spawn 子进程
+ *   - 输入 phase 元数据 + plugin 可用性，输出结构化 spawn 计划 / 摘要解析 / 决策
+ *   - 跨平台：无路径假设
+ *   - 失败用 throw + 明确错误信息（输入非法 / 类型未知）
+ *
+ * 调用方（概念上）：
+ *   - `templates/commands/autonomous.md` Step 4.4 challenger 分支
+ *
+ * 不做：
+ *   - 不实际 spawn Agent（主线 LLM 的职责，本 helper 只产出 spawn 计划）
+ *   - 不写 roadmap.md / .context/<phase>/SUMMARY.md
+ *   - 不解析 phase-runner 摘要（`phase-runner.ts` 已覆盖）
+ */
+
+/**
+ * Plugin advisor agent type. Maps to Claude Code subagent_type identifiers
+ * for the codex / gemini rescue plugins shipped via the `claude-plugins-*`
+ * marketplace.
+ */
+type PluginAdvisor = 'codex:codex-rescue' | 'gemini:gemini-rescue';
+/**
+ * CCG-built specialist critic agent. These ship with CCG installer
+ * (templates/commands/agents/*.md) so are always available — no plugin
+ * detection required.
+ */
+type SpecialistCritic = 'assumptions-analyzer' | 'nyquist-auditor';
+type ChallengerAgent = PluginAdvisor | SpecialistCritic;
+/**
+ * Severity tier of a finding raised by a challenger.
+ * `critical` — must address before advancing the phase
+ * `major`    — strongly recommended; degrades quality if ignored
+ * `info`     — informational only
+ */
+type FindingSeverity = 'critical' | 'major' | 'info';
+/**
+ * Input describing the phase under challenge.
+ */
+interface ChallengeInput {
+    /** Phase id, e.g. "16" */
+    phaseId: string;
+    /**
+     * Phase layer from roadmap.md `Type` field.
+     *
+     * v4.2 P21 起统一用 multi-model-routing SSoT 的 `Layer`，
+     * 替代历史 phase-runner.ts 自定义的 `PhaseType`（已收并）。
+     */
+    phaseType: Layer;
+    /** Whether `Critical: true` was declared in the phase frontmatter */
+    critical: boolean;
+    /** What plugins the user has installed (detected at orchestrator start) */
+    plugins: PluginAvailability;
+}
+/**
+ * One agent invocation in the spawn plan. Main thread spawns all entries
+ * from `ChallengerPlan.spawns` in a single message (Claude Code engine
+ * runs them in parallel).
+ */
+interface SpawnEntry$1 {
+    agent: ChallengerAgent;
+    /** Adversarial framing flag; `true` for plugin advisors and specialist critics alike */
+    adversarial: true;
+    /** Short rationale for logs / user visibility */
+    rationale: string;
+}
+/**
+ * Final spawn plan returned by `planChallengerSpawns`.
+ * `skipped` means Critical=false → no challengers, advance directly.
+ */
+interface ChallengerPlan {
+    /** Whether challenger phase runs at all */
+    skipped: boolean;
+    /** Reason when `skipped: true` (e.g. "phase not Critical") */
+    skipReason?: string;
+    /** List of agents to spawn in parallel */
+    spawns: SpawnEntry$1[];
+    /** `true` if any plugin was unavailable and orchestrator degraded */
+    degraded: boolean;
+    /** Specific degradation note when `degraded: true` */
+    degradeNote?: string;
+}
+/**
+ * One challenger's ≤200-token summary. Format mirrors phase-runner
+ * summary loosely but is challenger-specific: focus on findings list.
+ *
+ *   STATUS: complete | error
+ *   FINDINGS: [{severity, category, message}, ...]   (JSON-ish, lenient parse)
+ *   NOTES: <≤80 chars>
+ */
+interface ChallengerSummary {
+    agent: ChallengerAgent;
+    status: 'complete' | 'error';
+    findings: Finding[];
+    notes: string;
+    raw: string;
+}
+interface Finding {
+    severity: FindingSeverity;
+    category: string;
+    message: string;
+}
+/**
+ * Decision after collecting all challenger summaries.
+ * `revise` — at least one critical finding → main thread re-spawns
+ *            phase-runner with synthesized feedback (one revision round only)
+ * `advance` — no critical findings → proceed with original implementation
+ * `escalate` — challenger errors prevent decision → AskUserQuestion
+ */
+type ChallengerDecision = 'revise' | 'advance' | 'escalate';
+/**
+ * Build the spawn plan for a Critical phase.
+ *
+ * Routing rules (acceptance c):
+ *
+ *   backend  + Critical=true → codex:codex-rescue + assumptions-analyzer
+ *   frontend + Critical=true → gemini:gemini-rescue + nyquist-auditor
+ *   fullstack+ Critical=true → codex:codex-rescue + gemini:gemini-rescue
+ *                              + assumptions-analyzer + nyquist-auditor
+ *   docs     + Critical=true → assumptions-analyzer (single specialist)
+ *   generic  + Critical=true → assumptions-analyzer (single specialist)
+ *
+ * Critical=false → skip entirely, return `{ skipped: true }`.
+ *
+ * Plugin degradation (acceptance d): if a required plugin is unavailable,
+ * drop that plugin entry and keep specialists. Do NOT fall back to
+ * codeagent-wrapper (avoids re-establishing the dependency v3.0 retired).
+ */
+declare function planChallengerSpawns(input: ChallengeInput): ChallengerPlan;
+/**
+ * Parse a challenger's ≤200-token structured summary.
+ *
+ * Lenient: missing FINDINGS line → empty array; malformed JSON-ish list →
+ * best-effort extraction of `severity:critical|major|info` substrings.
+ *
+ * Throws only when `STATUS` is missing or unrecognized — that signals a
+ * bug in the challenger agent contract, not a bad phase.
+ */
+declare function parseChallengerSummary(agent: ChallengerAgent, text: string): ChallengerSummary;
+/**
+ * Decide what main thread does after collecting all challenger summaries.
+ *
+ *   any critical finding → revise (one revision round; caller enforces cap)
+ *   no critical, all complete → advance
+ *   any error status → escalate (AskUserQuestion)
+ */
+declare function decideFromSummaries(summaries: ChallengerSummary[]): ChallengerDecision;
+/**
+ * Synthesize critical findings across all challengers into a single
+ * feedback block to inject into the implementer's revision prompt.
+ *
+ * Returns a markdown string suitable for embedding in the phase-runner
+ * spawn prompt's `phase_acceptance` extension.
+ */
+declare function synthesizeRevisionFeedback(summaries: ChallengerSummary[]): string;
+
+/**
+ * Plugin Detection (CCG v4.1 Phase 20).
+ *
+ * Detects whether the user has installed Claude Code plugins that CCG's
+ * 6 core commands prefer over `codeagent-wrapper`:
+ *
+ *   - codex@openai-codex (provides `Agent(subagent_type="codex:codex-rescue")` — Agent 双前缀)
+ *   - gemini@google-gemini (provides `Agent(subagent_type="gemini:gemini-rescue")` — Agent 双前缀)
+ *
+ * 命名空间分离（v4.4.1 校正）：
+ *   - Agent(subagent_type=...) 真名 = `codex:codex-rescue` / `gemini:gemini-rescue`（双前缀）
+ *   - Skill(skill=...)         真名 = `codex:rescue` / `gemini:rescue`（单前缀）
+ *
+ * Plugins live under `~/.claude/plugins/<plugin-name>/SKILL.md` (or any
+ * marker file). The detection here is intentionally lightweight: if a
+ * recognizable directory exists with at least one of the plugin's standard
+ * marker files, we treat the plugin as installed. Failures are non-fatal —
+ * detection returns `false` so that callers fallback to `codeagent-wrapper`.
+ *
+ * Design principles:
+ *   - Pure synchronous fs probe; no spawn / network
+ *   - Cross-platform (uses pathe-style `/` joins via `path.join`)
+ *   - Never throws on unexpected errors — those map to "not installed"
+ *
+ * Used by:
+ *   - `templates/commands/{plan,execute,analyze,optimize,test,review}.md`
+ *     preflight (orchestrator inlines this logic in narrative form)
+ *   - `src/utils/challenger-orchestrator.ts` `PluginAvailability` populator
+ *
+ * Not used by:
+ *   - `phase-runner` subagent (engine forbids spawning Agent inside a
+ *     subagent — see commit a7cdffd)
+ */
+
+/**
+ * Plugin slugs CCG cares about for v4.1 codeagent retirement.
+ * Must mirror `PluginAdvisor` in `challenger-orchestrator.ts`.
+ */
+type PluginName = 'codex' | 'gemini';
+/**
+ * Detection result for a single plugin.
+ */
+interface PluginDetectionResult {
+    name: PluginName;
+    installed: boolean;
+    /** Absolute path probed (for diagnostic logging) */
+    probedPath: string;
+    /** Reason when `installed: false` */
+    reason?: 'missing-dir' | 'missing-marker' | 'fs-error';
+}
+/**
+ * Detect a single plugin by name.
+ *
+ * Returns `{ installed: false, reason: ... }` for any failure mode rather
+ * than throwing. Caller logic (template fallback / orchestrator degrade)
+ * only cares about the boolean.
+ *
+ * `homeDir` parameter exists for tests — production callers omit it.
+ */
+declare function detectPlugin(name: PluginName, homeDir?: string): PluginDetectionResult;
+/**
+ * Detect both CCG-relevant plugins in one call. Returns the
+ * `PluginAvailability` shape consumed by challenger-orchestrator.
+ */
+declare function detectPluginAvailability(homeDir?: string): PluginAvailability;
+/**
+ * Convenience: are *both* plugins installed (default route in v4.1)?
+ * When `false`, command templates instruct LLM to fallback to
+ * `codeagent-wrapper` for the missing model only (per-model degrade,
+ * not all-or-nothing).
+ */
+declare function bothPluginsInstalled(homeDir?: string): boolean;
+
+/**
+ * Quality Tier Router (CCG v4.2 Phase 22).
+ *
+ * v4.2 旗舰能力：把 v4.1 单波 phase-runner 调度扩展为**三档分级**：
+ *
+ *   - `--quality=fast`   — v4.1 单波 + 1 路 verify（壁钟 +30%，质量 6.5→7.5）
+ *   - `--quality=triple` — Plan-Critic-Verify 三段式（默认；4 wave；壁钟 +60-90%，质量→8.5）
+ *   - `--quality=debate` — triple + codex↔gemini 多轮对辩（壁钟 +100-150%，质量→9）
+ *
+ * 设计哲学（基于市面 SOTA Plan-Critic-Verify 实测）：
+ *   - Plan 阶段 lateral diversity（codex+gemini+claude 3 路并行）
+ *   - Critic 阶段 angle-based 不是 model-based（assumptions-analyzer + nyquist-auditor）
+ *   - Implementer 单 strong model（一致性 > 多样性，phase-runner 全权 Bash）
+ *   - Verify cross-vendor（codex+gemini 抓 race / commit drift / 半成品）
+ *
+ * 设计原则（与 v4.1 challenger-orchestrator / specialist-router 一致）：
+ *   - 纯函数；不读文件、不 spawn 子进程
+ *   - 输入 quality flag + phase 元数据 + plugin 可用性，输出 wave 计划
+ *   - 失败用 throw + 明确错误信息（非法 tier）
+ *   - 类型全部从 multi-model-routing SSoT 导入
+ *
+ * 调用方：
+ *   - templates/commands/autonomous.md Step 4.0（解析 quality flag → wave 计划）
+ *
+ * 不做：
+ *   - 不实际 spawn Agent（主线 LLM 职责）
+ *   - 不读 plugin 状态（plugin-detection.ts 职责）
+ *   - 不写 roadmap.md / SUMMARY.md
+ */
+
+/** Quality tier 三档 */
+type QualityTier = 'fast' | 'triple' | 'debate';
+/** Wave 类型：plan / critic / impl / verify / debate（仅 debate 模式） */
+type WaveKind = 'plan' | 'critic' | 'impl' | 'verify' | 'debate';
+/**
+ * 单个 spawn entry。复用 challenger-orchestrator 的 SpawnEntry 概念但本模块
+ * 不强依赖那边的 ChallengerAgent union——quality-router 还要 spawn
+ * phase-runner / claude opus 等非 challenger 角色，所以用更宽松的 string union。
+ */
+interface SpawnEntry {
+    /**
+     * 要 spawn 的 subagent_type。
+     *   - phase-runner          — implementer
+     *   - codex:codex-rescue    — plugin advisor / verify (Agent subagent_type, double-prefix)
+     *   - gemini:gemini-rescue  — plugin advisor / verify (Agent subagent_type, double-prefix)
+     *   - assumptions-analyzer  — critic specialist
+     *   - nyquist-auditor       — critic specialist
+     *   - general-purpose       — 降级到 main-thread Claude（含 ccgPromptFile 引用）
+     */
+    agent: string;
+    /** 调用风格：建设性 / 对抗性 / 校验性 */
+    role: 'planner' | 'critic' | 'implementer' | 'verifier' | 'debater';
+    /** 一句话给主线展示的理由 */
+    rationale: string;
+    /** 当 agent='general-purpose' 时引用的 CCG prompt 模板路径（降级路径） */
+    ccgPromptFile?: string;
+    /**
+     * v4.4.2 verify wave 字段透传（来自 verify-orchestrator.VerifySpawnEntry）：
+     * 'bash-direct' 走 Bash 直调 plugin script 跳过 sonnet wrapper（消除 silent
+     * fallback），'agent' 走传统 Agent spawn。仅 verify wave 当前使用，其他 wave
+     * 字段保持 undefined。
+     */
+    invocationMode?: 'agent' | 'bash-direct';
+    /**
+     * v4.4.2: 当 invocationMode='bash-direct' 时，主线 Bash 工具消费的命令模板
+     * （含 `<PROMPT>` 占位）。来自 verify-orchestrator.buildBashDirectCommand。
+     */
+    bashCommand?: string;
+}
+/**
+ * 一个 wave 的执行计划。多 wave 顺序执行；wave 内 spawns 并行。
+ */
+interface WavePlan {
+    kind: WaveKind;
+    /** 1-indexed wave 序号（仅 debate 子 wave 用 round 表达） */
+    index: number;
+    spawns: SpawnEntry[];
+    /** debate 子 wave 才有：当前是第几轮（1..N） */
+    round?: number;
+    /** 该 wave 是否因 plugin 缺失走了降级 */
+    degraded: boolean;
+    /** 降级原因（仅 degraded=true 时填） */
+    degradeNote?: string;
+}
+/** Phase 元数据子集（quality-router 只关心这几个字段） */
+interface PhaseMeta {
+    phaseId: string;
+    /** Layer 字段，参考 phase frontmatter `Type` */
+    phaseType: Layer;
+    /**
+     * Phase 自带 quality override（roadmap.md frontmatter `Quality:` 字段）。
+     * 若设置，优先级高于全局 --quality flag。
+     */
+    quality?: QualityTier;
+    /**
+     * v4.5 P1a: phase-runner CLI subprocess 调用所需的额外字段。
+     * - `workdir`: subprocess 的 cwd（必含 D5 决策；默认空时 helper 会 fallback 到 `<WORKDIR>` 占位符）
+     * - `jobId`: 用于 stream-json 落盘 `.context/jobs/<jobId>/progress.jsonl`
+     * 仅在 `useDirectBashInvocation=true` 路径生效；不影响 verify wave / Agent spawn。
+     */
+    workdir?: string;
+    jobId?: string;
+    /**
+     * v4.5 P1f: phase frontmatter `nested_rescue: true|false` override。
+     * 若设置，优先级高于全局 --nested CLI flag。phase-runner prompt 注入路径
+     * 参见 `resolveNestedRescue()`。
+     */
+    nestedRescue?: boolean;
+}
+/** 解析 --quality=<tier> flag 的输入 */
+interface ResolveInput {
+    /** Raw CLI args 字符串（包含 `--quality=...`），可空 */
+    cliArgs?: string;
+    /** Phase frontmatter `Quality:` 字段（若解析到） */
+    phaseQuality?: QualityTier;
+}
+/** 路由完整结果（含降级摘要） */
+interface QualityPlan {
+    tier: QualityTier;
+    /** 实际使用的 tier（resolveQualityTier 返回值，phase 优先 > flag > 默认） */
+    source: 'phase-override' | 'cli-flag' | 'default';
+    waves: WavePlan[];
+    /** 是否因 plugin 缺失整体降级到更低 tier */
+    degraded: boolean;
+    /** 实际降级到的目标 tier（degraded=true 时填） */
+    degradedTo?: QualityTier;
+    degradeNote?: string;
+}
+/**
+ * 解析 --quality=<tier> CLI flag。容错：未提供或非法值返回 null。
+ */
+declare function parseQualityFlag(args: string | undefined): QualityTier | null;
+/**
+ * 综合 phase override / cli flag / 默认值确定 quality tier。
+ *
+ * 优先级（高 → 低）：
+ *   1. phase frontmatter `Quality:` 字段（roadmap.md 单 phase 覆盖）
+ *   2. `--quality=<tier>` CLI flag
+ *   3. 默认 `triple`
+ */
+declare function resolveQualityTier(input: ResolveInput): {
+    tier: QualityTier;
+    source: 'phase-override' | 'cli-flag' | 'default';
+};
+/** v4.5 P1a: planWavesForTier / buildQualityPlan 选项 */
+interface PlanWavesOptions {
+    /**
+     * v4.5 P1a: 把 impl wave 的 phase-runner spawn 从 Agent sidechain 改为 Bash
+     * 直调 `claude -p --agent ccg/phase-runner ...` OS-level 子进程。同时也会
+     * 把 verify wave 的 plugin spawn 切到 bash-direct（v4.4.2 verify 治理）。
+     *
+     * 默认 false 时：
+     *   - impl wave 走 `Agent(subagent_type="phase-runner")`（v4.0~v4.4 行为）
+     *   - verify wave 走 Agent spawn（v4.4.1 及以前的 sonnet wrapper 路径）
+     *
+     * 默认 true（autonomous Step 4.0+ 启用）时：
+     *   - impl wave 走 Bash 直调，subprocess RSS 与主进程隔离
+     *   - verify wave 走 plugin script 直调，跳过 sonnet wrapper
+     */
+    useDirectBashInvocation?: boolean;
+    /**
+     * v4.5 P1f: 当 `useDirectBashInvocation=true` 时，用 ccg-phase-runner-launcher.mjs
+     * 包装 `claude -p` 调用而非直接裸 spawn。解锁 Phase 2 supervisor 全部能力：
+     * atomic state.json / process-tree kill-tree / cancel.flag 协作 / reconciler。
+     *
+     * autonomous Step 4.2-4.3 默认开启。Test / dev workflow 可关闭走 P1a 裸 spawn 路径。
+     * 默认 false 时保持 P1a 裸 `claude -p` BC（v4.5.0 → v4.5.1 升级路径）。
+     */
+    useLauncherWiring?: boolean;
+}
+/**
+ * 给定 tier + phase + plugin 可用性，返回 wave 计划。
+ *
+ * 降级路径：
+ *   - debate → triple：双 plugin 都缺失（debate 失去对辩多样性意义）
+ *   - triple → fast：双 plugin 都缺失（plan/verify 双方向都降级到 main-thread）
+ *
+ * 注意：单 plugin 缺失不触发整体降级——具体 wave 内走 general-purpose
+ * fallback（degraded: true）；只有双 plugin 都缺时才整体降阶。
+ */
+declare function planWavesForTier(tier: QualityTier, phase: PhaseMeta, plugins: PluginAvailability, options?: PlanWavesOptions): {
+    effectiveTier: QualityTier;
+    waves: WavePlan[];
+    degraded: boolean;
+    degradedTo?: QualityTier;
+    degradeNote?: string;
+};
+/**
+ * One-shot 入口：解析 flag → 算 tier → 构 wave。
+ *
+ * 主线 autonomous Step 4.0 直接调这个，得到完整执行计划。
+ *
+ * v4.5 P1a: `options.useDirectBashInvocation=true` 时 impl wave + verify wave
+ * 都切到 Bash 直调（subprocess RSS 隔离 + verify wave silent fallback 治理）。
+ */
+declare function buildQualityPlan(resolveInput: ResolveInput, phase: PhaseMeta, plugins: PluginAvailability, options?: PlanWavesOptions): QualityPlan;
+
+/**
+ * Plan Aggregator (CCG v4.2 Phase 22).
+ *
+ * triple/debate 模式 plan wave 完成后，汇总 3 路 plan contribution 成
+ * 单一 DesignBrief（共识 / 分歧 / 必决策点），由主线在 impl wave 注入
+ * phase-runner 的 prompt 里。
+ *
+ * 综合算法（P22 起步实现，P23 dogfood 后可调优）：
+ *   1. 把每路 plan 切成 bullet points（按 markdown `-` 或换行）
+ *   2. 共识 = 同样 bullet 出现在 ≥ 2 路（≥ 70% 字面相似度）
+ *   3. 分歧 = 仅 1 路出现 或 不同路给冲突方案
+ *   4. decision_required = 分歧中标"high-stakes"关键词的（架构 / 破坏性 / 安全 / schema / 迁移）
+ *
+ * 设计原则（与 quality-router 一致）：
+ *   - 纯函数；不读文件、不 spawn 子进程
+ *   - 输入 PlanContribution[]，输出 DesignBrief
+ *   - 失败容错：单路解析失败仍用其他 N-1 路（不抛错）
+ *
+ * 调用方：
+ *   - templates/commands/autonomous.md Step 4.x triple/debate 模式 plan wave 后
+ *
+ * 不做：
+ *   - 不解析 phase-runner 摘要（phase-runner.ts 职责）
+ *   - 不做语义级对齐（只做字符级相似度，控制复杂度）
+ */
+
+interface PlanContribution {
+    /** 哪个 model 给出的 plan（codex / gemini / claude / general-purpose 兜底） */
+    model: Model;
+    /** Plan 文本（subagent 摘要里的 PLAN 字段或全文，主线传入哪个由编排决定） */
+    plan: string;
+    /** plan 文本长度（字符），传入计算可缓存；缺省自动算 */
+    length?: number;
+}
+/** 一个分歧主题（topic 一致但选项不同） */
+interface Divergence {
+    topic: string;
+    options: {
+        from: Model;
+        option: string;
+    }[];
+}
+interface DesignBrief {
+    /** ≥ 2 路提到的共识要点 */
+    consensus: string[];
+    /** 各模型间的分歧主题 + 各自方案 */
+    divergences: Divergence[];
+    /**
+     * 必须由主线 / 用户决策的高 stakes 项（含 high-stakes keyword 的分歧主题）
+     * 这是 divergences 的子集（按 topic 引用），不是新内容。
+     */
+    decision_required: string[];
+    /** 解析过程的告警（路解析失败等） */
+    warnings: string[];
+}
+/**
+ * 综合多路 plan 成单一 DesignBrief。
+ *
+ * 容错：单路 plan 解析失败/为空时 warning 记录，用其他路继续。
+ */
+declare function aggregatePlans(contributions: PlanContribution[]): DesignBrief;
+/**
+ * 估算文本的 token 数量（v4.2.1 P24，替代字符长度估算）。
+ *
+ * 按字符类型加权求和：
+ *   - 英文 word（match `[a-zA-Z]+`）：1 word ≈ 1 token，平均 4 char/word → 0.25 token/char
+ *   - 中文 char（match `[一-鿿]`）：1 char ≈ 1 token (GPT/Claude tokenizer 实测)
+ *   - 数字 / 标点 / 空白：0.3 token/char (中性估算)
+ *
+ * 返回 Math.ceil(总和)，避免低估导致超预算。
+ *
+ * 例子：
+ *   - "hello world this is a test" → 6 token (6 word)
+ *   - "这是一个测试" → 6 token (6 中文字)
+ *   - "this is 中文测试" → ~3 word + 4 中文 = ~7 token + 空格 = ~8 token
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * 把 DesignBrief 序列化成 markdown，供 phase-runner prompt 注入。
+ *
+ * 长度上限 ≈ BRIEF_MAX_TOKENS token（v4.2.1 P24 token-aware 截断；旧版按 char 估算
+ * 对纯中文低估 2 倍）。边构建边检查，超过预算则截断尾部并加 `(truncated)` 标记。
+ */
+declare function serializeBriefForPrompt(brief: DesignBrief): string;
+/**
+ * 返回 brief 序列化结果的 token 估算（v4.2.1 P24 用 estimateTokens 替代字符长度）。
+ *
+ * 旧 API 名保持兼容，但语义从 char 数改为 token 估算。
+ */
+declare function estimateBriefLength(brief: DesignBrief): number;
+
+/**
+ * Verify Orchestrator (CCG v4.2 Phase 22; v4.2.1 Phase 24 — SSoT 化).
+ *
+ * fast/triple/debate 模式 verify wave 完成后，综合 verify reports 决定主线
+ * 后续行为（advance / revise / escalate）。
+ *
+ * **SSoT 声明 (v4.2.1 P24)**：本模块的 `planVerifyWave()` 是 **verify wave 路由
+ * 的权威实现**。`quality-router.ts.buildVerifyWave` 必须 import 本函数后做
+ * schema adapter，不得复制实现。任何 verify 路由策略变更只在本文件改。
+ *
+ * 设计原则：
+ *   - 纯函数；不读文件、不 spawn 子进程
+ *   - 输入 verify reports（≤200 token 摘要文本），输出决策枚举
+ *   - 复用 challenger-orchestrator 的 parseFindings 鲁棒化解析
+ *
+ * 调用方：
+ *   - templates/commands/autonomous.md verify wave 完成后
+ *   - quality-router.ts.buildVerifyWave (内部 wrap 成 WavePlan schema)
+ *
+ * 不做：
+ *   - 不实际 spawn verify agent（quality-router 出 spawn 计划，主线 LLM 派发）
+ *   - 不修订 phase（修订由主线再 spawn impl wave 完成）
+ */
+
+/** Verify 模式：单 verify (fast) / 双 verify (triple+debate) */
+type VerifyMode = 'single' | 'dual';
+/** 单条 verify 摘要解析后的结构 */
+interface VerifyReport {
+    /** 哪个 agent 返回的 verify 结果 */
+    agent: string;
+    /** 解析状态 */
+    status: 'complete' | 'error';
+    /** Critical 级别 findings */
+    criticals: Finding[];
+    /** Major 级别 findings（参考用，不阻塞推进） */
+    majors: Finding[];
+    /** Notes 字段 */
+    notes: string;
+    /** 原始文本（debug 用） */
+    raw: string;
+}
+/** 主线决策：advance / revise / escalate（与 challenger 一致） */
+type VerifyDecision = 'advance' | 'revise' | 'escalate';
+/**
+ * 调用方式（v4.4.2 起 verify wave 支持两种）：
+ *   - 'agent'       — Agent(subagent_type=...) plugin spawn（含 sonnet wrapper，silent fallback 风险）
+ *   - 'bash-direct' — Bash 直调 plugin script（codex-companion.mjs / gemini-companion.mjs）跳过 wrapper
+ *
+ * v4.4.2 verify wave 默认切到 'bash-direct' 架构性消除 silent contamination。
+ * 其他用例（impl/autonomous/debate）仍走 'agent' 保 ≤200 token 摘要预算。
+ */
+type VerifyInvocationMode = 'agent' | 'bash-direct';
+/** Verify wave spawn entry（与 quality-router 的 SpawnEntry 子集对齐） */
+interface VerifySpawnEntry {
+    agent: string;
+    rationale: string;
+    /** plugin 缺失走 general-purpose 时引用的 prompt 文件 */
+    ccgPromptFile?: string;
+    /** v4.4.2: 'agent' 走 Agent spawn / 'bash-direct' 走 Bash 直调 plugin script */
+    invocationMode?: VerifyInvocationMode;
+    /**
+     * v4.4.2: 当 invocationMode='bash-direct' 时，模板渲染用的 Bash 命令模板。
+     * 主线 Bash 工具直接执行此命令，stdout 为 plugin 完整 JSON 响应。
+     * Plugin 脚本路径用 glob `~/.claude/plugins/cache/<vendor>/<plugin>/*\/scripts/*-companion.mjs`，
+     * 主线消费时按需 ls 解析具体版本号。
+     */
+    bashCommand?: string;
+}
+/** v4.4.2 planVerifyWave 选项 */
+interface PlanVerifyWaveOptions {
+    /**
+     * 把所有 plugin spawn entry 切成 'bash-direct' 模式（v4.4.2 verify wave 默认 true）。
+     * 仅影响 plugin 路径，general-purpose 降级路径不受影响。
+     */
+    useDirectBashInvocation?: boolean;
+}
+/** Verify wave 计划输出 */
+interface VerifyWavePlan {
+    mode: VerifyMode;
+    spawns: VerifySpawnEntry[];
+    degraded: boolean;
+    degradeNote?: string;
+}
+/**
+ * 给定 quality tier + phase layer + plugin 可用性，构造 verify wave 计划。
+ *
+ *   - fast    → single verify (cross-vendor: layer=frontend → codex；其他 → gemini)
+ *   - triple  → dual verify (codex + gemini 并行)
+ *   - debate  → dual verify
+ *
+ * **SSoT (v4.2.1)**：quality-router.buildVerifyWave 必须 import 此函数 + 走
+ * schema adapter，不得复制路由实现。
+ *
+ * **v4.4.2 (E only)**：`options.useDirectBashInvocation=true` 时所有 plugin
+ * spawn entry 标 invocationMode='bash-direct' + 附 bashCommand，主线模板渲染
+ * 为 Bash 直调跳过 sonnet wrapper（架构性消除 silent contamination）。默认
+ * false 保持向后兼容（v4.4.1 及以前的 Agent spawn 行为）。
+ */
+declare function planVerifyWave(tier: 'fast' | 'triple' | 'debate', layer: Layer, plugins: PluginAvailability, options?: PlanVerifyWaveOptions): VerifyWavePlan;
+/**
+ * 解析单条 verify summary 文本。复用 challenger-orchestrator.parseChallengerSummary
+ * 的鲁棒化 parser（同样的 STATUS / FINDINGS / NOTES schema）。
+ *
+ * 与 challenger 不同点：verify 没有"adversarial"语义，但摘要协议复用同一格式
+ * 简化代码 + 测试。caller 决定调用语义。
+ *
+ * @param agent  调用方传入的 agent 名（quality-router 的 SpawnEntry.agent）
+ * @param text   subagent 返回的 ≤200 token 摘要原文
+ */
+declare function parseVerifyReport(agent: string, text: string): VerifyReport;
+/**
+ * 综合多个 verify reports 给主线决策。
+ *
+ *   - 任一 status='error'                    → escalate (AskUserQuestion)
+ *   - 任一 critical finding                  → revise (主线 spawn 修订轮)
+ *   - 全部 complete + 0 critical             → advance
+ *   - 空报告列表（异常）                      → escalate
+ */
+declare function synthesizeVerifyResults(reports: VerifyReport[]): VerifyDecision;
+/**
+ * 综合 verify reports 中的 critical findings 成单一反馈块，注入修订轮
+ * phase-runner 的 prompt（与 challenger.synthesizeRevisionFeedback 同源）。
+ *
+ * 修订轮要求：仅修复 critical 项，不重做整个 phase。
+ */
+declare function synthesizeVerifyFeedback(reports: VerifyReport[]): string;
+
+/**
+ * Pipeline Check (CCG v4.3 Phase 25).
+ *
+ * 主线 spawn phase-runner 完成 commit 后，强制跑一次端到端 release pipeline 验证：
+ *   1. pnpm pack 看 tarball 能否生成
+ *   2. 解 tarball 列内容
+ *   3. 比对 templates/commands/*.md 实际文件 vs package.json `files` 数组——找漏列
+ *
+ * v4.2.0 release blocker `debate.md` 漏 package.json files 这种事就由这个 helper
+ * 在 commit 后立刻被抓，不必等用户 cold-start。
+ *
+ * 设计原则（与 v4.0 phase-context / debug-session / wave-scheduler 一致）：
+ *   - 纯函数 + 几个 spawn 子进程的入口；不读 ~/.claude/、不写持久状态
+ *   - 输入 workdir 路径，输出结构化 PipelineCheckReport
+ *   - 失败优雅：pnpm 没装 / tar 没装 / 子进程 crash 都返回 ok=false + 错误，不抛
+ *   - Cross-platform：用 child_process.execSync + node:fs + node:path 内建模块
+ *
+ * 调用方（主线）：
+ *   - autonomous.md Step 4.4 phase 完成后（runPipelineCheck → 任何 critical → blocker 路径）
+ *   - 用户手动跑 `node -e "..."` 验证
+ *
+ * 不做：
+ *   - 不实际跑 npm install -g（破坏用户全局环境，留给用户手动）
+ *   - 不修复发现的问题（建议性输出，主线决策）
+ *   - 不读 settings.json / ~/.claude/（那是 ground-truth-sampler 职责，P26）
+ */
+/** 单条错误的分类。category 用于主线决策严重程度。 */
+type PipelineErrorCategory = 'pack-failed' | 'tar-extract-failed' | 'missing-from-tarball' | 'package-json-missing' | 'package-json-invalid';
+/**
+ * 单条错误。message 给主线 / 用户读，detail 是可选 debug 信息。
+ */
+interface PipelineError {
+    category: PipelineErrorCategory;
+    message: string;
+    detail?: string;
+}
+/**
+ * Pipeline check 完整报告。ok=true 才允许 phase 推进。
+ */
+interface PipelineCheckReport {
+    ok: boolean;
+    errors: PipelineError[];
+    warnings: string[];
+    /** tarball 路径（pack 成功时填） */
+    tarballPath?: string;
+    /** tarball 内文件清单（前缀通常是 "package/"） */
+    tarballEntries?: string[];
+    /**
+     * templates/commands/*.md 中存在但 package.json `files` 漏列的文件。
+     * 这是 v4.2.0 debate.md 漏 register 那种事故的最常见 root cause。
+     */
+    missingFromPackageJson: string[];
+}
+/** runPipelineCheck 输入选项 */
+interface PipelineCheckOptions {
+    /** 项目根目录（含 package.json + templates/）。默认 process.cwd() */
+    workdir?: string;
+    /** 是否真跑 `pnpm pack`（默认 true）；false 时跳过仅做 package.json 静态比对 */
+    doPnpmPack?: boolean;
+}
+/**
+ * 跑 `pnpm pack` 在 workdir 下，返回生成的 tarball 绝对路径。
+ *
+ * pnpm pack 输出最后一行是 tarball 文件名（如 "ccg-workflow-4.3.0.tgz"）。
+ * 失败 → throw 给上层 catch。
+ */
+declare function runPnpmPack(workdir: string): string;
+/**
+ * 列 tarball 内所有文件路径（不解压）。tar 工具 cross-platform：
+ * Unix tar / Windows bsdtar / Git Bash tar 都支持 `-tzf`。
+ *
+ * 失败 → throw（多半是 tar 工具不存在）。
+ */
+declare function auditTarballContents(tarballPath: string): string[];
+/**
+ * 比对 `templates/commands/*.md` 实际存在的文件 vs `package.json` `files`
+ * 数组 / tarball 实际打包内容，找出漏列文件。
+ *
+ * 这是 v4.2.0 release blocker `debate.md` 漏 package.json files 那种事故
+ * 的核心检测——`templates/commands/debate.md` 在 git 树里有但 package.json
+ * `files` 数组未列出，导致 npm pack 不打入 tarball。
+ *
+ * 检测分两层：
+ *   1. 实际文件 vs package.json files 静态比对（不需要 tarball）
+ *   2. 实际文件 vs tarball entries 比对（如果 tarball 提供）
+ *
+ * 任一层报漏列即视为问题。
+ */
+declare function verifyAllCommandsIncluded(workdir: string, tarballEntries?: string[]): {
+    packageFiles: string[];
+    actualCommands: string[];
+    missingInPackageJson: string[];
+    missingInTarball: string[];
+};
+/**
+ * 端到端 pipeline check：pack → audit → 漏列检测。
+ *
+ * 主线 spawn phase-runner 完成 commit 后调一次。任一 critical 错误（pack-failed
+ * / missing-from-tarball / package-json-missing）→ ok=false → 主线进 blocker 路径。
+ *
+ * @param opts 配置；workdir 默认 process.cwd()
+ * @returns PipelineCheckReport（不抛错，所有失败模式都进 errors 数组）
+ */
+declare function runPipelineCheck(opts?: PipelineCheckOptions): PipelineCheckReport;
+/**
+ * 把 PipelineCheckReport 渲染为人可读的 markdown，主线给用户展示用。
+ */
+declare function renderPipelineReport(report: PipelineCheckReport): string;
+
+/**
+ * Ground Truth Sampler (CCG v4.3 Phase 26).
+ *
+ * 实时从用户机器**采样**外部接口的真实状态——不是写一份"基于历史快照的猜测"
+ * 文档（CCG 自己都做不到把所有 spec 文档同步），而是每次需要时即时读取真实
+ * 状态：
+ *
+ *   - plugin 列表（~/.claude/plugins/installed_plugins.json）
+ *   - skill 列表（~/.claude/skills/**\/SKILL.md frontmatter）
+ *   - hook event schema（~/.claude/settings.json hooks 段）
+ *   - package.json files vs templates/commands/ 一致性
+ *
+ * 输出到 .context/ground-truth/<ISO timestamp>.json + 软链 latest.json，
+ * phase-runner prompt 强约束 "写涉及外部接口代码前必须 Read latest.json"。
+ *
+ * 解决 v4.2.0 codex:codex-rescue 同型事故：phase-runner 写代码时根本没机会
+ * 凭训练数据猜外部接口名——它必须 Read 真实采样数据。
+ *
+ * 设计原则（与 v4.0 phase-context / v4.3 P25 pipeline-check 一致）：
+ *   - 纯读取；不修改用户机器任何文件（仅读 ~/.claude/* 几个 known path）
+ *   - 失败优雅：缺文件 / 解析失败 / 权限不足都返回空数组，不抛
+ *   - Cross-platform：node:fs + node:os.homedir + node:path 内建模块
+ *   - 输出 schema 自描述（含 sampledAt timestamp + 来源路径）
+ *
+ * 调用方：
+ *   - autonomous.md Step 4.0 启动时 sampleAll + writeGroundTruth
+ *   - phase-runner 的子任务（间接通过 prompt Read latest.json）
+ *   - P28 测试 fixtures 自动生成（基于真采样输出）
+ *
+ * 不做：
+ *   - 不真 spawn plugin 验证（引擎层禁，且开销大）
+ *   - 不修改 settings.json / installed_plugins.json
+ *   - 不下载 marketplace 元数据
+ */
+/**
+ * 单个 plugin 的真实状态摘要。subagentTypeHints 是从 plugin 名/manifest 推断
+ * 的可能 subagent_type（仅启发，不是绝对真值——绝对真值得真 spawn 试，引擎禁）。
+ */
+interface PluginInfo {
+    /** plugin 唯一标识（如 "codex@claude-plugins-official"） */
+    name: string;
+    /** 简单名（"codex" / "gemini"） */
+    shortName: string;
+    /** 安装版本 */
+    version: string;
+    /** 安装绝对路径，可选 */
+    installPath?: string;
+    /**
+     * 经验性 subagent_type 名称提示（基于已知 marketplace 命名规则）：
+     *   - codex@... → "codex:codex-rescue" (Agent), "codex:setup"
+     *   - gemini@... → "gemini:gemini-rescue" (Agent), "gemini:setup"
+     * 命名空间分离（v4.4.1）：Agent subagent_type 双前缀；Skill 单前缀。
+     * 仅供 phase-runner 参考；真值需 user 机器实际 system prompt 验证。
+     */
+    subagentTypeHints?: string[];
+}
+/**
+ * 单个 skill 的真实状态摘要（CCG 安装的 skills/ccg/ 命名空间下）。
+ */
+interface SkillInfo {
+    /** SKILL.md frontmatter `name` 字段 */
+    name: string;
+    /** SKILL.md 绝对路径 */
+    path: string;
+    /** frontmatter `user-invocable` 字段（默认 false） */
+    userInvocable: boolean;
+    /** 推断分类（按目录路径） */
+    category?: 'tool' | 'domain' | 'impeccable' | 'orchestration' | 'unknown';
+}
+/**
+ * 单个 hook event 的真实 schema 摘要（settings.json hooks 段）。
+ */
+interface HookInfo {
+    /** event 名（如 "PostToolUse" / "SessionStart"） */
+    event: string;
+    /** matcher 字段实际类型（用户机器上就是怎么写的） */
+    matcherType: 'string' | 'array' | 'object' | 'null' | 'absent' | 'other';
+    /** 该 event 注册了几个 hook 入口 */
+    hookCount: number;
+    /** 第一个 hook command 字符串前 80 字符（仅 debug 用，不含敏感路径） */
+    firstCommandPreview?: string;
+}
+/**
+ * 项目维度采样：package.json files 跟 templates/commands/ 的一致性快照。
+ */
+interface PackageStructureInfo {
+    /** package.json `files` 数组原文 */
+    packageFiles: string[];
+    /** templates/commands/*.md 实际文件相对路径列表 */
+    templateCommands: string[];
+    /** 实际存在但 packageFiles 漏列的文件（v4.2.0 debate.md 同型事故的检测） */
+    missingFromPackageFiles: string[];
+}
+/**
+ * 完整 ground truth snapshot。所有 sub-section 都可能为空（来源文件不存在时）。
+ */
+interface GroundTruth {
+    /** ISO 8601 采样时间戳 */
+    sampledAt: string;
+    /** ~/.claude/plugins/installed_plugins.json 读出的 plugin 列表 */
+    plugins: PluginInfo[];
+    /** ~/.claude/skills/ccg/**\/SKILL.md 解析的 skill 列表 */
+    skills: SkillInfo[];
+    /** ~/.claude/settings.json hooks 段实际 schema */
+    hooks: HookInfo[];
+    /** 项目维度（仅 sampleAll 传 workdir 时填） */
+    packageStructure?: PackageStructureInfo;
+    /** 采样过程中的非致命警告 */
+    warnings: string[];
+}
+/**
+ * 读 ~/.claude/plugins/installed_plugins.json，返回标准化的 PluginInfo[]。
+ * 文件不存在 → [] + warning；JSON 解析失败 → [] + warning。
+ */
+declare function samplePluginList(homeDir?: string): {
+    plugins: PluginInfo[];
+    warnings: string[];
+};
+/**
+ * 扫 ~/.claude/skills/ccg/**\/SKILL.md，解析 frontmatter 给出 skill 列表。
+ *
+ * 仅读 ccg/ 命名空间，避免读到用户自建或其他 plugin 的 skill。
+ */
+declare function sampleSkillList(homeDir?: string): {
+    skills: SkillInfo[];
+    warnings: string[];
+};
+/**
+ * 读 ~/.claude/settings.json 的 hooks 段，输出每个 event 的真实 schema 摘要。
+ *
+ * 这次 v4.1 P13 SessionStart hook 注册写错（matcher 字段是 string 还是 array）就是
+ * 此采样要解决的——phase-runner 写 hook 集成代码前必须先看这份采样。
+ */
+declare function sampleHookSchema(homeDir?: string): {
+    hooks: HookInfo[];
+    warnings: string[];
+};
+/**
+ * 采样项目 package.json `files` vs templates/commands/ 真实状态。
+ * 跟 P25 pipeline-check.verifyAllCommandsIncluded 同源逻辑，但这里**仅采样**
+ * 不做判定（pipeline-check 才决定 ok/fail）。
+ */
+declare function samplePackageStructure(workdir: string): {
+    info: PackageStructureInfo | null;
+    warnings: string[];
+};
+interface SampleOptions {
+    /** 用户机器 home dir。默认 os.homedir()。仅测试用。 */
+    homeDir?: string;
+    /** 项目根目录。传入则采样项目维度（package.json + templates/） */
+    workdir?: string;
+}
+/**
+ * 一站式采样：plugins / skills / hooks /（可选）packageStructure。
+ *
+ * 不抛错——所有失败都进 warnings 数组让上层决定要不要 escalate。
+ */
+declare function sampleAll(opts?: SampleOptions): GroundTruth;
+/**
+ * 把 GroundTruth 序列化为人可读的简短摘要（≤500 token），phase-runner prompt
+ * 注入用。完整版见 latest.json。
+ */
+declare function summarizeGroundTruth(gt: GroundTruth): string;
+
+/**
+ * Interface Auditor (CCG v4.3 Phase 27).
+ *
+ * 跨 phase 接口审计 verifier specialist。每 phase commit 后由主线在 quality-router
+ * triple/debate 模式的 verify wave 内并行 spawn 一次（与 codex+gemini cross-vendor
+ * verify 并列）。
+ *
+ * 检测 6 类**真实事故型**风险：
+ *
+ *   1. SSoT 违反（critical）— 重复 type / 重复实现（v4.2 P22 重新引入 planVerifyWave 同型）
+ *   2. 半成品（major）— export 但无 import consumer（v4.1 P19 paths 字段无 consumer 同型）
+ *   3. magic string 不在 ground truth（critical）— 硬编码 subagent_type / hook event
+ *      跟 P26 sampler 实采集合不符（v4.2.0 codex:codex-rescue 同型）
+ *   4. commit message vs diff 一致性（major）— 与 P29 hook 协作的事后审
+ *   5. mock 与 ground truth schema 偏差（info/major）— 与 P28 fixtures 协作的线索提供
+ *   6. alien files staged（critical）— `git diff --cached --name-only` 含本 phase 范围
+ *      外文件（v4.4 P34：wave 1 race 检查；与 phase-runner.md "git add 显式列文件"约束配套）
+ *
+ * 设计原则（与 v4.2.1 verify-orchestrator / challenger-orchestrator 一致）：
+ *   - 纯函数：本模块仅提供 parser + 类型 schema；agent 实现逻辑放 prompt 里
+ *   - 复用 challenger-orchestrator.parseFindings 鲁棒化（单/双引号 / json fence /
+ *     balanced-bracket tokenizer 兜底）
+ *   - 输出协议与 challenger / verify summary 同源（STATUS / FINDINGS / NOTES），
+ *     调用方决定语义
+ *
+ * 调用方：
+ *   - templates/commands/autonomous.md Step 4.4 verify wave 综合
+ *   - quality-router.ts.buildVerifyWave (triple/debate spawns 内追加 interface-auditor)
+ *
+ * 不做：
+ *   - 不实际 spawn agent（主线 LLM 派发；本 helper 只产出 schema + 解析）
+ *   - 不读 ground truth 文件（agent prompt 内 Read，本 helper 处理结果摘要）
+ *   - 不实现 5 项检查（agent 自己 grep + Bash 完成，本 helper 仅解析摘要）
+ */
+
+/**
+ * Interface auditor 5 类 finding category 枚举。
+ *
+ * 严格枚举的目的：主线综合 verify 决策时可按 category 分组阈值（譬如 ssot-violation
+ * 永远 critical，mock-drift 永远 info）。
+ */
+type InterfaceAuditCategory = 'ssot-violation' | 'leftover' | 'magic-string-mismatch' | 'commit-diff-drift' | 'mock-drift' | 'alien-files-staged' | 'unknown';
+/**
+ * Interface auditor 单条 finding。比通用 Finding 更紧（category 严格枚举）。
+ */
+interface InterfaceAuditFinding {
+    severity: FindingSeverity;
+    category: InterfaceAuditCategory;
+    message: string;
+}
+/**
+ * Interface auditor ≤200 token 摘要解析后的结构。
+ */
+interface InterfaceAuditReport {
+    /** 解析状态 */
+    status: 'complete' | 'error';
+    /** 5 类检查命中的 finding（含 critical/major/info 三档） */
+    findings: InterfaceAuditFinding[];
+    /** Notes 字段 */
+    notes: string;
+    /** 原始摘要文本（debug 用） */
+    raw: string;
+}
+/**
+ * 解析 interface-auditor agent 返回的 ≤200 token 摘要文本。
+ *
+ * 复用 challenger-orchestrator.parseChallengerSummary 的鲁棒化 parser（同样的
+ * STATUS / FINDINGS / NOTES 协议 + 单引号/双引号/json-fence/嵌套 {} 容错），
+ * 然后把 generic Finding[] 收紧成 InterfaceAuditFinding[]（category 枚举 normalize）。
+ *
+ * 与 verify-orchestrator.parseVerifyReport 不同点：
+ *   - 不区分 criticals / majors（本模块由调用方在 synthesize 时按 severity 分组）
+ *   - category 严格枚举到 InterfaceAuditCategory（unknown 兜底，不丢 finding）
+ *
+ * @param text  agent 返回的 ≤200 token 摘要原文
+ */
+declare function parseInterfaceAuditorReport(text: string): InterfaceAuditReport;
+/**
+ * 取出 critical findings（主线 synthesize 决策：任一 critical → revise）。
+ */
+declare function criticalFindings(report: InterfaceAuditReport): InterfaceAuditFinding[];
+/**
+ * 取出 major findings（参考用，不阻塞推进；与 verify-orchestrator 语义一致）。
+ */
+declare function majorFindings(report: InterfaceAuditReport): InterfaceAuditFinding[];
+/**
+ * 是否含可阻塞推进的 finding（critical）。供主线 synthesize 调用。
+ */
+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 };