@zhuan-ai/zhuanspec 2.11.19 → 2.12.7

package/dist/cli/index.js

@@ -15,6 +15,7 @@ import { ShowCommand } from '../commands/show.js';
 import { CompletionCommand } from '../commands/completion.js';
 import { ReviewCommand } from '../commands/review.js';
 import { ProgressCommand } from '../commands/progress.js';
+import { AccuracyCommand } from '../commands/accuracy.js';
 import { discoverSkills, formatSkillsList } from '../core/skill-discovery.js';
 import { registerConfigCommand } from '../commands/config.js';
 import { registerArtifactWorkflowCommands } from '../commands/artifact-workflow.js';
@@ -283,6 +284,58 @@ progressCmd
         process.exit(1);
     }
 });
+// Progress resolve-correction subcommand
+progressCmd
+    .command('resolve-correction <change-id>')
+    .description('Clear pending user-correction marker (Apply phase)')
+    .option('--path <path>', 'Chosen resolution path: A|B|C|D')
+    .option('--note <text>', 'Optional note to attach to the correction-log entry')
+    .option('--mark-pitfall-saved', 'Also set askedPitfallSaved=true in progress.json to suppress Stop-hook ask')
+    .action(async (changeId, options) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.resolveCorrection(changeId, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Progress show-correction subcommand
+progressCmd
+    .command('show-correction <change-id>')
+    .description('Show pending-correction status and recent correction-log entries')
+    .option('--tail <n>', 'Show last N log entries (default 10)', (v) => parseInt(v, 10))
+    .action(async (changeId, options) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.showCorrection(changeId, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Accuracy command
+program
+    .command('accuracy [change-name]')
+    .description('Show Initial Code Accuracy Rate for a change')
+    .option('--json', 'Output as JSON')
+    .option('--force', 'Force recompute accuracy')
+    .option('--override <rate>', 'Manually override accuracy rate (0.0~1.0)')
+    .action(async (changeName, options) => {
+    try {
+        const accuracyCommand = new AccuracyCommand();
+        await accuracyCommand.execute(changeName, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
 program
     .command('archive [change-name]')
     .description('Archive a completed change and update main specs')

package/dist/commands/accuracy.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Accuracy Command - Show Initial Code Accuracy Rate
+ *
+ * Usage: zhuanspec accuracy <change-id>
+ * Options: --json, --force, --override <rate>
+ */
+export declare class AccuracyCommand {
+    execute(changeName?: string, options?: {
+        json?: boolean;
+        force?: boolean;
+        override?: string;
+    }): Promise<void>;
+    private selectChangeInteractively;
+}
+//# sourceMappingURL=accuracy.d.ts.map

package/dist/commands/accuracy.js

@@ -0,0 +1,154 @@
+/**
+ * Accuracy Command - Show Initial Code Accuracy Rate
+ *
+ * Usage: zhuanspec accuracy <change-id>
+ * Options: --json, --force, --override <rate>
+ */
+import path from 'path';
+import { promises as fs } from 'fs';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { computeAccuracy, applyOverride, } from '../core/metrics/code-accuracy.js';
+import { atomicWriteJson, recoverProgressJsonForWrite, } from '../core/hooks/record-progress.js';
+export class AccuracyCommand {
+    async execute(changeName, options) {
+        const cwd = process.cwd();
+        if (!changeName) {
+            const selected = await this.selectChangeInteractively();
+            if (!selected) {
+                throw new Error('No change selected. Usage: zhuanspec accuracy <change-id>');
+            }
+            changeName = selected;
+        }
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeName);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeName}' not found`);
+        }
+        const metricsDir = path.join(changeDir, 'metrics');
+        const accuracyPath = path.join(metricsDir, 'accuracy.json');
+        const progressPath = path.join(metricsDir, 'progress.json');
+        // Load progress with recovery support
+        let progress = null;
+        if (await FileSystemUtils.fileExists(progressPath)) {
+            progress = await recoverProgressJsonForWrite(progressPath);
+        }
+        if (!progress || !progress.accuracy?.snapshotTimestamp) {
+            console.log('ℹ️  No accuracy snapshot found for this change.');
+            console.log('   The snapshot is created after the Apply phase completes.');
+            console.log('   Make sure post-apply hook has been executed.');
+            return;
+        }
+        // Handle --override
+        if (options?.override !== undefined) {
+            const overrideRate = parseFloat(options.override);
+            if (isNaN(overrideRate) || overrideRate < 0 || overrideRate > 1) {
+                throw new Error('Override rate must be a number between 0.0 and 1.0');
+            }
+            const result = applyOverride(progress, overrideRate);
+            // Persist to progress.json
+            await atomicWriteJson(progressPath, progress);
+            // Also update accuracy.json
+            if (await FileSystemUtils.fileExists(accuracyPath)) {
+                try {
+                    const accuracyData = JSON.parse(await FileSystemUtils.readFile(accuracyPath));
+                    if (!accuracyData.overrideHistory)
+                        accuracyData.overrideHistory = [];
+                    accuracyData.overrideHistory.push({
+                        timestamp: new Date().toISOString(),
+                        originalRate: result.originalRate,
+                        overriddenRate: result.overriddenRate,
+                        reason: 'CLI --override',
+                    });
+                    accuracyData.accuracyRate = result.overriddenRate;
+                    accuracyData.accuracyRateRaw = result.originalRate;
+                    await atomicWriteJson(accuracyPath, accuracyData);
+                }
+                catch {
+                    // Ignore accuracy.json update errors
+                }
+            }
+            console.log(`✓ Accuracy overridden: ${(result.originalRate * 100).toFixed(1)}% → ${(result.overriddenRate * 100).toFixed(1)}%`);
+            return;
+        }
+        // Compute accuracy
+        const accResult = computeAccuracy(progress);
+        if (options?.json) {
+            console.log(JSON.stringify({
+                changeId: changeName,
+                accuracy: {
+                    rate: accResult.rate,
+                    rateRaw: accResult.rateRaw,
+                    aiTotalLines: accResult.aiTotalLines,
+                    userCorrectionLines: accResult.userCorrectionLines,
+                    overridden: accResult.overridden,
+                },
+                snapshot: progress.accuracy,
+                correctionEdits: progress.accuracy.correctionEdits || [],
+            }, null, 2));
+        }
+        else {
+            console.log('');
+            console.log(`📊 代码首次准确率: ${changeName}`);
+            console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            console.log('');
+            console.log(`  准确率:      ${(accResult.rate * 100).toFixed(1)}%${accResult.overridden ? ' (已手动修正)' : ''}`);
+            if (accResult.overridden) {
+                console.log(`  原始准确率:   ${(accResult.rateRaw * 100).toFixed(1)}%`);
+            }
+            console.log(`  AI产出:      ${accResult.aiTotalLines} 行`);
+            console.log(`  用户纠正:    ${accResult.userCorrectionLines} 行`);
+            if (progress.accuracy.snapshotTimestamp) {
+                console.log(`  快照时间:    ${progress.accuracy.snapshotTimestamp}`);
+            }
+            console.log('');
+            // Show per-file correction details
+            const edits = progress.accuracy.correctionEdits || [];
+            if (edits.length > 0) {
+                console.log('📝 纠正明细:');
+                const byFile = new Map();
+                for (const e of edits) {
+                    const existing = byFile.get(e.filePath) || { lines: 0, count: 0 };
+                    existing.lines += e.editLines;
+                    existing.count += 1;
+                    byFile.set(e.filePath, existing);
+                }
+                for (const [file, stats] of byFile) {
+                    console.log(`  ${file}: ${stats.lines} 行 (${stats.count} 次)`);
+                }
+                console.log('');
+            }
+            console.log(`💡 手动修正: zhuanspec accuracy ${changeName} --override <0.0~1.0>`);
+            console.log('');
+        }
+    }
+    async selectChangeInteractively() {
+        const changesDir = path.join(process.cwd(), 'zhuanspec', 'changes');
+        let entries = [];
+        try {
+            entries = await fs.readdir(changesDir, { withFileTypes: true });
+        }
+        catch {
+            throw new Error("No zhuanspec changes directory found. Run 'zhuanspec init' first.");
+        }
+        const changes = entries
+            .filter((entry) => entry.isDirectory() && entry.name !== 'archive' && !entry.name.startsWith('.'))
+            .map((entry) => entry.name)
+            .sort((a, b) => a.localeCompare(b));
+        if (changes.length === 0) {
+            throw new Error('No active changes found. Create one first.');
+        }
+        if (!process.stdin.isTTY) {
+            throw new Error(`Missing change name. Available changes: ${changes.join(', ')}`);
+        }
+        const { select } = await import('@inquirer/prompts');
+        try {
+            return await select({
+                message: '选择要查看准确率的变更',
+                choices: changes.map((id) => ({ name: id, value: id })),
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=accuracy.js.map

package/dist/commands/progress.d.ts

@@ -34,5 +34,22 @@ export declare class ProgressCommand {
      * Usage: zhuanspec progress set-phase <change-id> <phase>
      */
     setPhase(changeId: string, phase: string): Promise<void>;
+    /**
+     * Resolve pending user-correction: remove `.pending-correction`, append
+     * resolved entry to `.correction-log`, and optionally mark pitfall saved.
+     * Usage: zhuanspec progress resolve-correction <change-id> [--path A|B|C|D] [--note <text>] [--mark-pitfall-saved]
+     */
+    resolveCorrection(changeId: string, options?: {
+        path?: string;
+        note?: string;
+        markPitfallSaved?: boolean;
+    }): Promise<void>;
+    /**
+     * Show current pending correction status and recent correction-log entries.
+     * Usage: zhuanspec progress show-correction <change-id> [--tail <n>]
+     */
+    showCorrection(changeId: string, options?: {
+        tail?: number;
+    }): Promise<void>;
 }
 //# sourceMappingURL=progress.d.ts.map

package/dist/commands/progress.js

@@ -288,7 +288,7 @@ export class ProgressCommand {
         const completedCount = tasks.filter(t => t.status === 'completed').length;
         const totalTasks = tasks.length;
         // Phase index
-        const phases = ['idle', 'propose', 'apply', 'review', 'archive'];
+        const phases = ['idle', 'techDesign', 'propose', 'apply', 'review', 'archive'];
         const phaseIndex = phases.indexOf(phase) + 1;
         // Progress percentage
         const percentage = totalTasks > 0 ? (completedCount / totalTasks) * 100 : 0;
@@ -370,5 +370,132 @@ export class ProgressCommand {
         console.log(`\n✓ Phase set: ${changeId} -> ${normalizedPhase}`);
         console.log(`✓ Progress file: ${progressPath}\n`);
     }
+    /**
+     * Resolve pending user-correction: remove `.pending-correction`, append
+     * resolved entry to `.correction-log`, and optionally mark pitfall saved.
+     * Usage: zhuanspec progress resolve-correction <change-id> [--path A|B|C|D] [--note <text>] [--mark-pitfall-saved]
+     */
+    async resolveCorrection(changeId, options) {
+        const cwd = resolveZhuanSpecRoot();
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        const pendingMarker = path.join(changeDir, '.pending-correction');
+        const logPath = path.join(changeDir, '.correction-log');
+        let hadMarker = false;
+        // Remove pending marker (safe if missing)
+        try {
+            await fs.unlink(pendingMarker);
+            hadMarker = true;
+        }
+        catch {
+            // ignore missing marker
+        }
+        // Append resolved entry to correction-log
+        const entry = {
+            ts: new Date().toISOString(),
+            event: 'resolved',
+            path: options?.path,
+            note: options?.note,
+        };
+        try {
+            await fs.appendFile(logPath, JSON.stringify(entry) + '\n', 'utf-8');
+        }
+        catch {
+            // ignore log append errors
+        }
+        // Optionally mark askedPitfallSaved=true in progress.json
+        if (options?.markPitfallSaved) {
+            const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+            if (await FileSystemUtils.fileExists(progressPath)) {
+                try {
+                    const raw = await FileSystemUtils.readFile(progressPath);
+                    const progress = JSON.parse(raw);
+                    progress.askedPitfallSaved = true;
+                    progress.lastUpdatedAt = new Date().toISOString();
+                    await fs.writeFile(progressPath, JSON.stringify(progress, null, 2), 'utf-8');
+                }
+                catch {
+                    // ignore progress update errors
+                }
+            }
+        }
+        console.log(`\n✓ Correction resolved for change '${changeId}'`);
+        console.log(`  - Pending marker: ${hadMarker ? 'removed' : 'not present'}`);
+        if (options?.path)
+            console.log(`  - Path: ${options.path}`);
+        if (options?.note)
+            console.log(`  - Note: ${options.note}`);
+        if (options?.markPitfallSaved)
+            console.log(`  - askedPitfallSaved: true`);
+        console.log();
+    }
+    /**
+     * Show current pending correction status and recent correction-log entries.
+     * Usage: zhuanspec progress show-correction <change-id> [--tail <n>]
+     */
+    async showCorrection(changeId, options) {
+        const cwd = resolveZhuanSpecRoot();
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        const pendingMarker = path.join(changeDir, '.pending-correction');
+        const logPath = path.join(changeDir, '.correction-log');
+        const tail = options?.tail && options.tail > 0 ? options.tail : 10;
+        console.log(`\nChange: ${changeId}`);
+        console.log('-'.repeat(60));
+        // Pending marker
+        if (await FileSystemUtils.fileExists(pendingMarker)) {
+            try {
+                const raw = await FileSystemUtils.readFile(pendingMarker);
+                const marker = JSON.parse(raw);
+                const ageMin = Math.round((Date.now() - (marker.createdAt || 0)) / 60000);
+                console.log(`Pending correction: YES (age ~${ageMin} min)`);
+                if (marker.prompt) {
+                    const preview = String(marker.prompt).replace(/\s+/g, ' ').slice(0, 160);
+                    console.log(`  Prompt: ${preview}${marker.prompt.length > 160 ? '…' : ''}`);
+                }
+            }
+            catch {
+                console.log('Pending correction: YES (unparseable marker)');
+            }
+        }
+        else {
+            console.log('Pending correction: none');
+        }
+        // Correction log tail
+        if (await FileSystemUtils.fileExists(logPath)) {
+            const content = await FileSystemUtils.readFile(logPath);
+            const lines = content.split('\n').filter(l => l.trim().length > 0);
+            const recent = lines.slice(-tail);
+            console.log(`\nRecent correction-log (last ${recent.length} of ${lines.length}):`);
+            for (const line of recent) {
+                try {
+                    const rec = JSON.parse(line);
+                    console.log(`  [${rec.ts}] ${rec.event}${rec.path ? ` path=${rec.path}` : ''}${rec.promptPreview ? ` — ${String(rec.promptPreview).slice(0, 80)}` : ''}${rec.note ? ` (${rec.note})` : ''}`);
+                }
+                catch {
+                    console.log(`  ${line}`);
+                }
+            }
+        }
+        else {
+            console.log('\nCorrection log: (empty)');
+        }
+        // askedPitfallSaved status
+        const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+        if (await FileSystemUtils.fileExists(progressPath)) {
+            try {
+                const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+                console.log(`\naskedPitfallSaved: ${progress.askedPitfallSaved === true ? 'true' : 'false'}`);
+            }
+            catch {
+                // ignore
+            }
+        }
+        console.log();
+    }
 }
 //# sourceMappingURL=progress.js.map

package/dist/commands/review.js

@@ -2,6 +2,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { setPhase } from '../utils/phase-utils.js';
+import { ensureAccuracySnapshot } from '../core/metrics/code-accuracy.js';
 import { codeReviewResultCheck, unitTestResultCheck, specConsistencyResultCheck, generateReviewReport, } from '../core/hooks/review-hooks.js';
 export class ReviewCommand {
     async execute(changeName, options) {
@@ -60,6 +61,17 @@ export class ReviewCommand {
         catch (err) {
             console.warn(`⚠️ Failed to update progress.phase to 'review': ${err instanceof Error ? err.message : String(err)}`);
         }
+        // Accuracy snapshot 补救：若 apply 未走 post-apply hook（如手动 /zhuanspec:review）导致快照缺失，
+        // 在进入 review 的那一刻以 progress.linesAdded 作为 AI 基线衱5一份，避免首次准确率数据丢失。
+        try {
+            const created = await ensureAccuracySnapshot(changeDir);
+            if (created) {
+                console.log(`ℹ️  Accuracy snapshot 在 review 进入时补打成功（应优先走 post-apply hook，补打为兑底机制）`);
+            }
+        }
+        catch (err) {
+            console.warn(`⚠️ Accuracy snapshot 补打失败（不阻断 review）: ${err instanceof Error ? err.message : String(err)}`);
+        }
         // Read hook results and generate report
         const codeReviewResult = await codeReviewResultCheck(changeName);
         const unitTestResult = await unitTestResultCheck(changeName);
@@ -82,10 +94,27 @@ export class ReviewCommand {
         else {
             console.log(`Review report for ${changeName}`);
             console.log(`Overall: ${overallPass ? 'PASS ✅' : 'FAIL ❌'}`);
-            console.log(`Code Review: ${codeReviewResult.pass ? 'PASS' : 'FAIL'} (critical=${codeReviewResult.metrics.criticalCount ?? 0})`);
-            console.log(`Unit Test: ${unitTestResult.pass ? 'PASS' : 'FAIL'} (coverage=${unitTestResult.metrics.coverage ?? 0}%)`);
             console.log(`Spec-Code: ${specConsistencyResult.pass ? 'PASS' : 'FAIL'} (consistency=${specConsistencyResult.metrics.consistencyRate ?? 0}%)`);
+            console.log(`Unit Test: ${unitTestResult.pass ? 'PASS' : 'FAIL'} (coverage=${unitTestResult.metrics.coverage ?? 0}%)`);
+            console.log(`Code Review: ${codeReviewResult.pass ? 'PASS' : 'FAIL'} (critical=${codeReviewResult.metrics.criticalCount ?? 0})`);
             console.log(`Report: ${path.join('zhuanspec/changes', changeName, 'review/review-report.md')}`);
+            // 历史数据兼容提示：legacy schema 豁免时输出 ⚠️ 警告但不影响 PASS
+            if (codeReviewResult.metrics.legacyBypass) {
+                console.warn(`\n⚠️ [轨道 3 Code Review legacy schema] ${String(codeReviewResult.metrics.legacyReason ?? '')}\n  → 下次请在 \`code-review-result.json\` 中设置 \`"schemaVersion": 2\` 并登记 \`skillReportPath\`。`);
+            }
+            if (unitTestResult.metrics.legacyBypass) {
+                console.warn(`\n⚠️ [轨道 2 Unit Test legacy schema] ${String(unitTestResult.metrics.legacyReason ?? '')}\n  → 下次请在 \`unit-test-result.json\` 中设置 \`"schemaVersion": 2\` 并登记 \`newTestsGenerated\`/\`skipReason\`。`);
+            }
+            // 失败时输出中文 fixPrompt，确保用户明确看到失败原因与修复指引
+            if (!specConsistencyResult.pass && specConsistencyResult.fixPrompt) {
+                console.error(`\n[轨道 1 Spec-Code 失败]${specConsistencyResult.fixPrompt}`);
+            }
+            if (!unitTestResult.pass && unitTestResult.fixPrompt) {
+                console.error(`\n[轨道 2 Unit Test 失败]${unitTestResult.fixPrompt}`);
+            }
+            if (!codeReviewResult.pass && codeReviewResult.fixPrompt) {
+                console.error(`\n[轨道 3 Code Review 失败]${codeReviewResult.fixPrompt}`);
+            }
         }
         process.exitCode = overallPass ? 0 : 1;
     }

package/dist/core/configurators/codex.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Codex root configurator.
+ *
+ * Unlike the Claude configurator (which owns `CLAUDE.md`) the Codex
+ * configurator shares `AGENTS.md` with the standard agents stub. Its main
+ * responsibility is to materialize the project-level Codex integration
+ * artefacts and the matching `trusted_level` entry in the global Codex config:
+ *
+ *   <repo>/.codex/
+ *     config.toml   - ZhuanSpec hooks TOML block (wrapped in markers)
+ *     agents/       - TOML subagents mirrored from .claude/agents/*.md
+ *     skills/       - Project-level Skills mirrored from .claude/skills/
+ *
+ *   ~/.codex/ (or $CODEX_HOME)
+ *     config.toml   - Per-project [projects."…"] trusted_level = "trusted"
+ *                     block (wrapped in TRUST markers keyed by absolute path)
+ *
+ * Codex does **not** load project-scoped hooks/subagents unless the project
+ * is explicitly marked trusted in the global config (see openai/codex#14601),
+ * so we opportunistically write that trust entry during `zhuanspec init`.
+ *
+ * Idempotency:
+ *   - Hooks block is regenerated inside ZHUANSPEC markers on every run.
+ *   - Trust entries are keyed by absolute path; repeated runs no-op.
+ *   - Legacy `.codex/hooks.json` from the 2.12.0 implementation is removed.
+ */
+import { ToolConfigurator } from './base.js';
+export interface CodexConfigureResult {
+    /** Absolute path of `<repo>/.codex/config.toml` that was written. */
+    configTomlPath: string;
+    /** Absolute paths of subagent role TOMLs that were written. */
+    agentsWritten: string[];
+    /** Absolute paths of skill files written under `<repo>/.codex/skills/`. */
+    skillsWritten: string[];
+    /** Absolute path of the global config.toml that received the trust entry. */
+    globalConfigPath: string;
+    /** Whether a new trust entry was added (false = already trusted). */
+    trustEntryAdded: boolean;
+    /**
+     * Absolute path of a legacy global `~/.codex/hooks.json` detected during
+     * configure. Codex warns when hooks are loaded from both `hooks.json` and
+     * `config.toml`; we surface the file here so callers can inform the user.
+     * `null` when no conflicting file was found.
+     */
+    conflictingGlobalHooksJson: string | null;
+    /**
+     * Absolute paths of legacy `~/.codex/prompts/zhuanspec-*.md` files that
+     * were cleaned up. Codex >= 0.117 ignores that directory entirely, so we
+     * opportunistically remove ZhuanSpec-managed prompts from pre-2.12.5
+     * installs to avoid user confusion. Empty when nothing needed removing.
+     */
+    legacyPromptsCleaned: string[];
+}
+export declare class CodexConfigurator implements ToolConfigurator {
+    name: string;
+    /** Codex reads AGENTS.md for project instructions (no dedicated CODEX.md). */
+    configFileName: string;
+    isAvailable: boolean;
+    configure(projectPath: string, _zhuanspecDir: string): Promise<void>;
+    /**
+     * Write:
+     *   1. `.codex/agents/zhuanspec-*.toml` mirrored from `.claude/agents/*.md`
+     *   2. `.codex/skills/*` mirrored from `.claude/skills/` (directory tree)
+     *   3. ZhuanSpec hooks block merged into `.codex/config.toml`
+     *   4. Per-project trust entry appended to `$CODEX_HOME/config.toml`
+     *   5. Remove legacy `.codex/hooks.json` left over from 2.12.0
+     */
+    configureWithSummary(projectPath: string): Promise<CodexConfigureResult>;
+    /**
+     * Mirror `<repo>/.claude/agents/*.md` into `<repo>/.codex/agents/*.toml`.
+     * Returns the full file descriptors (not just paths) so the caller can
+     * register each role under `[agents.<slug>]` in the parent config.toml.
+     */
+    private generateAgents;
+    /**
+     * Mirror `<repo>/.claude/skills/` directory tree into `<repo>/.codex/skills/`.
+     * Uses `fs.copyFile` so that executable bits on scripts (`.sh`, `.py`, etc.)
+     * are preserved. Silently no-ops when `.claude/skills/` is absent.
+     */
+    private mirrorSkills;
+    /**
+     * Merge the ZhuanSpec managed block into `<repo>/.codex/config.toml`. The
+     * block contains two coordinated sections:
+     *
+     *   1. `[agents.<slug>]` registration tables (one per mirrored subagent)
+     *   2. `[[hooks.<Event>]]` default lifecycle hook tables
+     *
+     * User-owned config outside the marker block is preserved verbatim.
+     */
+    private writeProjectConfigToml;
+    /**
+     * Build the `[agents.<slug>]` registration TOML block for all mirrored
+     * subagents. Each table points to the per-role file under `agents/<slug>.toml`.
+     * Returns an empty string when no agents were mirrored (no `.claude/agents`).
+     */
+    private buildAgentsRegistrationBlock;
+    /**
+     * Detect whether a global `~/.codex/hooks.json` coexists with our
+     * project-level `config.toml` hooks. Codex warns (`loading hooks from both
+     * hooks.json and config.toml`) and we cannot safely delete a file the user
+     * owns — instead we return its path so the caller can prompt the user.
+     */
+    private detectGlobalHooksJsonConflict;
+    /**
+     * Append (or keep) a per-project `[projects."<abs>"] trusted_level="trusted"`
+     * entry in `$CODEX_HOME/config.toml`. The block is wrapped in TRUST markers
+     * keyed by absolute path so repeated runs are idempotent and multiple
+     * projects can coexist in the same file.
+     *
+     * Conflict resolution with **unmanaged** native entries:
+     *   Codex CLI's `/trust this workspace` and the legacy 2.12.0 implementation
+     *   both write a plain `[projects."<abs>"]` table without ZHUANSPEC markers.
+     *   If we unconditionally append our marked block, TOML parsing blows up
+     *   with `duplicate key` and Codex refuses to start (observed in the wild).
+     *   The user's explicit native entry always takes precedence: we detect it,
+     *   skip our write, and if our marked block co-exists (legacy duplicate) we
+     *   strip it to restore a parseable config.
+     */
+    private ensureGlobalTrustEntry;
+    /**
+     * Detect whether `[projects."<projectPath>"]` is declared OUTSIDE our
+     * ZHUANSPEC:TRUST markers. Used to avoid producing TOML `duplicate key`
+     * when the user (or legacy 2.12.0) already wrote a native trust entry.
+     */
+    private hasNativeTrustEntry;
+    /** Remove our marker-wrapped trust block for `projectPath` from `content`. */
+    private stripTrustBlock;
+    /** Build a full `# TRUST:START…END` block for the given project path. */
+    private buildTrustBlock;
+    /**
+     * Replace an existing TRUST block for `projectPath` in-place. Used to keep
+     * the block content in sync if the schema ever evolves (currently a no-op
+     * when the block already matches).
+     */
+    private replaceTrustBlock;
+}
+//# sourceMappingURL=codex.d.ts.map