@zhuan-ai/zhuanspec 2.15.7 → 2.16.0

package/dist/commands/progress.js

@@ -10,7 +10,8 @@ import path from 'path';
 import { promises as fs } from 'fs';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { PHASE_ORDER } from '../utils/phase-utils.js';
-import { initializeProgress } from '../core/hooks/record-progress.js';
+import { initializeProgress, atomicWriteJson, getBeijingTime } from '../core/hooks/record-progress.js';
+import { recomputeAccuracyRate, persistAccuracyJson, getOrCreatePhaseBucket, applyPhaseOverride, confirmPhaseAccuracy, appendAccuracyDebugLog, } from '../core/metrics/code-accuracy.js';
 import { resolveZhuanSpecRoot } from '../utils/resolve-root.js';
 export class ProgressCommand {
     /**
@@ -385,6 +386,19 @@ export class ProgressCommand {
      * 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]
+     *
+     * @deprecated v2.15.16 Sprint 3 起，`.correction-log` 已从事实源中下线，新 change
+     * 的纠偏信号由 user-input-hook 直接写入 `user_inputs.json` 的 correctionSignal /
+     * postBaseline / resolution 字段并由 review/knowledge 链路消费。
+     *
+     * 本命令仅保留给 v2.15.14 及更早版本创建的老 change 做手动兼容：
+     *   - 仍会删除 `.pending-correction` marker（新旧 change 都需要）
+     *   - 仍会 append 一条 resolved 记录到 `.correction-log`（仅老 change 会读）
+     *   - 仍会写 `progress.correctionContext` 用于后续 resolveCorrection 窗口（30 min）
+     *
+     * 下一个 minor 版本计划迁移：writer 切换到 user_inputs.json.resolution，
+     * 届时本命令将退化为一次性提示 + marker 清理。
+     * TODO(Sprint 3.2)：迁移到 user_inputs.json.resolution 字段
      */
     async resolveCorrection(changeId, options) {
         const cwd = resolveZhuanSpecRoot();
@@ -393,8 +407,24 @@ export class ProgressCommand {
             throw new Error(`Change '${changeId}' not found`);
         }
         const pendingMarker = path.join(changeDir, '.pending-correction');
+        // TODO(Sprint 3.2)：.correction-log 已于 v2.15.16 下线，此处仅用于老 change 兼容
         const logPath = path.join(changeDir, '.correction-log');
         let hadMarker = false;
+        // Task 6：先读 marker（可能包含 promptId/phaseInputIndex/promptSnippet）再删除
+        let markerMeta = {};
+        try {
+            const markerRaw = await FileSystemUtils.readFile(pendingMarker);
+            const parsed = JSON.parse(markerRaw);
+            markerMeta = {
+                promptId: parsed.promptId,
+                phaseInputIndex: parsed.phaseInputIndex,
+                promptSnippet: parsed.promptSnippet,
+                reason: parsed.reason,
+            };
+        }
+        catch {
+            // marker 不存在或解析失败均不阻断
+        }
         // Remove pending marker (safe if missing)
         try {
             await fs.unlink(pendingMarker);
@@ -404,6 +434,7 @@ export class ProgressCommand {
             // ignore missing marker
         }
         // Append resolved entry to correction-log
+        // TODO(Sprint 3.2)：迁移到 user_inputs.json.resolution 字段，届时删除此块
         const entry = {
             ts: new Date().toISOString(),
             event: 'resolved',
@@ -431,6 +462,11 @@ export class ProgressCommand {
                     path: options?.path || 'A',
                     expiresAt: new Date(now.getTime() + 30 * 60 * 1000).toISOString(),
                     phase: progress.phase || 'apply',
+                    // Task 6：三路径 triggeredBy 回填——从 marker 或 user_inputs.json 最新一条拼接元数据
+                    source: 'correction-keyword',
+                    promptId: markerMeta.promptId,
+                    promptIndex: markerMeta.phaseInputIndex,
+                    promptSnippet: markerMeta.promptSnippet,
                 };
                 progress.lastUpdatedAt = now.toISOString();
                 await fs.writeFile(progressPath, JSON.stringify(progress, null, 2), 'utf-8');
@@ -464,6 +500,10 @@ export class ProgressCommand {
         if (options?.markPitfallSaved)
             console.log(`  - askedPitfallSaved: true`);
         console.log();
+        // v2.15.16 Sprint 3：友好提示——新 change 无需调用此命令
+        console.log('\x1b[90m[deprecated] 此命令仅用于 v2.15.14 及更早版本的老 change 兼容。\n' +
+            '            新 change 的纠偏状态已由 user-input-hook 自动写入 user_inputs.json，\n' +
+            '            无需手动 resolve。\x1b[0m\n');
     }
     /**
      * Show current pending correction status and recent correction-log entries.
@@ -500,6 +540,7 @@ export class ProgressCommand {
             console.log('Pending correction: none');
         }
         // Correction log tail
+        // TODO(Sprint 3.2)：.correction-log 已下线，此段仅展示老 change 历史记录
         if (await FileSystemUtils.fileExists(logPath)) {
             const content = await FileSystemUtils.readFile(logPath);
             const lines = content.split('\n').filter(l => l.trim().length > 0);
@@ -517,6 +558,9 @@ export class ProgressCommand {
         }
         else {
             console.log('\nCorrection log: (empty)');
+            // v2.15.16 Sprint 3：新 change 不再写 .correction-log，提示正确的查询渠道
+            console.log('\x1b[90m  提示：自 v2.15.16 起，纠偏事件由 user-input-hook 写入 user_inputs.json。\n' +
+                '        查看当前 change 纠偏汇总请看：zhuanspec/changes/<id>/user_inputs.json\x1b[0m');
         }
         // askedPitfallSaved status
         const progressPath = path.join(changeDir, 'metrics', 'progress.json');
@@ -531,5 +575,266 @@ export class ProgressCommand {
         }
         console.log();
     }
+    /**
+     * Mark phase baseline manually.
+     * Usage: zhuanspec progress mark-baseline <change-id> <phase> [--force]
+     *
+     * 仅允许 techDesign / propose / apply / review 四个 phase；
+     * 若已有 markedAt 且未指定 --force，则报告不改；
+     * 否则写入 markedBy='manual-cli' 并 atomicWriteJson 保存。
+     */
+    async markBaseline(changeId, phase, options) {
+        const ALLOWED = ['techDesign', 'propose', 'apply', 'review'];
+        const normalized = ALLOWED.find(p => p.toLowerCase() === phase.toLowerCase());
+        if (!normalized) {
+            throw new Error(`Invalid phase for mark-baseline: ${phase}. Allowed: ${ALLOWED.join(', ')}`);
+        }
+        const cwd = resolveZhuanSpecRoot();
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+        if (!await FileSystemUtils.fileExists(progressPath)) {
+            throw new Error(`progress.json not found: ${progressPath}`);
+        }
+        const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        progress.phaseBaselines = progress.phaseBaselines || {};
+        const existing = progress.phaseBaselines[normalized];
+        if (existing?.markedAt && !options?.force) {
+            console.log(`\nℹ️  Phase baseline already marked: ${normalized} @ ${existing.markedAt} (by ${existing.markedBy}). Use --force to overwrite.\n`);
+            return;
+        }
+        const now = getBeijingTime();
+        const entry = {
+            markedAt: now,
+            markedBy: 'manual-cli',
+            firstStopAt: existing?.firstStopAt,
+        };
+        progress.phaseBaselines[normalized] = entry;
+        progress.lastUpdatedAt = now;
+        await atomicWriteJson(progressPath, progress);
+        // 埋点：baseline.mark
+        appendAccuracyDebugLog(changeDir, {
+            type: 'baseline.mark',
+            phase: normalized,
+            trigger: 'manual-cli',
+            changeId,
+            input: { force: !!options?.force },
+            output: {
+                markedBy: 'manual-cli',
+                existed: !!existing?.markedAt,
+                markedAt: now,
+            },
+        });
+        console.log(`\n✓ Phase baseline marked: ${changeId} / ${normalized} @ ${now} (by manual-cli${existing?.markedAt ? ', force-overwrote' : ''})\n`);
+    }
+    /**
+     * Recompute phaseAccuracy buckets and accuracyRate from scratch.
+     * Usage: zhuanspec progress recompute <change-id>
+     *
+     * 流程：
+     *   1. 清空 accuracy.phaseAccuracy
+     *   2. 遍历 accuracy.correctionEdits，按 (phase, trackedKind) 累加到桶 userCorrectionLines
+     *   3. 将非纠偏的 AI 记录按 edit.phase + edit.trackedKind 累加到桶 aiLinesAdded / aiTotalLines
+     *   4. recomputeAccuracyRate + persistAccuracyJson
+     *
+     * 设计说明：历史 correctionEdits 中 source==='user' 的 edit 即为纠偏，
+     * source==='ai' 的 edit 则视为 AI 新增行数；顶层聚合字段保持不变。
+     */
+    async recompute(changeId) {
+        const cwd = resolveZhuanSpecRoot();
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+        if (!await FileSystemUtils.fileExists(progressPath)) {
+            throw new Error(`progress.json not found: ${progressPath}`);
+        }
+        const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        if (!progress.accuracy) {
+            console.log(`\nℹ️  No accuracy data to recompute for '${changeId}'.\n`);
+            return;
+        }
+        const edits = progress.accuracy.correctionEdits || [];
+        // 步骤 1：清空桶
+        progress.accuracy.phaseAccuracy = [];
+        let rebuiltBucketEntries = 0;
+        const ALLOWED_PHASES = ['techDesign', 'propose', 'apply', 'review'];
+        for (const edit of edits) {
+            const ph = edit.phase;
+            const kind = edit.trackedKind;
+            if (!ph || !kind || !ALLOWED_PHASES.includes(ph))
+                continue;
+            const bucket = getOrCreatePhaseBucket(progress, ph, kind);
+            const lines = edit.editLines || 0;
+            if (edit.source === 'user') {
+                bucket.userCorrectionLines += lines;
+                const promptId = edit.triggeredBy?.promptId;
+                if (promptId && !bucket.correctionPromptIds.includes(promptId)) {
+                    bucket.correctionPromptIds.push(promptId);
+                }
+            }
+            else if (edit.source === 'ai') {
+                bucket.aiLinesAdded += lines;
+                bucket.aiTotalLines += lines;
+            }
+            bucket.lastUpdatedAt = edit.timestamp || bucket.lastUpdatedAt;
+            rebuiltBucketEntries++;
+        }
+        recomputeAccuracyRate(progress, { changeDir, trigger: 'cli-recompute' });
+        progress.lastUpdatedAt = getBeijingTime();
+        await atomicWriteJson(progressPath, progress);
+        await persistAccuracyJson(changeDir, progress);
+        const buckets = progress.accuracy.phaseAccuracy || [];
+        console.log(`\n✓ Recomputed accuracy for '${changeId}'`);
+        console.log(`  - correctionEdits processed: ${edits.length} (accepted=${rebuiltBucketEntries})`);
+        console.log(`  - phaseAccuracy buckets: ${buckets.length}`);
+        for (const b of buckets) {
+            console.log(`    [${b.phase}/${b.trackedKind}] aiTotal=${b.aiTotalLines} correction=${b.userCorrectionLines} rate=${(b.accuracyRate * 100).toFixed(2)}%`);
+        }
+        const topRate = (progress.accuracy.accuracyRate ?? 1) * 100;
+        console.log(`  - top-level accuracyRate: ${topRate.toFixed(2)}%\n`);
+    }
+    /**
+     * Override accuracy rate for a specific phase.
+     * Usage: zhuanspec progress override-phase <change-id> <phase> --rate <0..1> --reason <text>
+     *
+     * 完整保留纠正前的桶级快照（rate/raw/aiTotal/correction）到 overrideHistory，
+     * 供事后差异分析 "raw vs overridden delta" 反向驱动改进。
+     */
+    async overridePhase(changeId, phase, options) {
+        const ALLOWED = ['techDesign', 'propose', 'apply', 'review'];
+        const normalized = ALLOWED.find(p => p.toLowerCase() === phase.toLowerCase());
+        if (!normalized) {
+            throw new Error(`Invalid phase for override-phase: ${phase}. Allowed: ${ALLOWED.join(', ')}`);
+        }
+        const rate = parseFloat(options.rate);
+        if (Number.isNaN(rate) || rate < 0 || rate > 1) {
+            throw new Error('Rate must be a number between 0.0 and 1.0');
+        }
+        const reason = (options.reason ?? '').trim();
+        if (!reason) {
+            throw new Error('Missing --reason (required for audit trail)');
+        }
+        const cwd = resolveZhuanSpecRoot();
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+        if (!await FileSystemUtils.fileExists(progressPath)) {
+            throw new Error(`progress.json not found: ${progressPath}`);
+        }
+        const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        const buckets = progress.accuracy?.phaseAccuracy?.filter(b => b.phase === normalized) ?? [];
+        if (buckets.length === 0) {
+            throw new Error(`No phaseAccuracy bucket for ${changeId}/${normalized}. Historical data or phase has no tracked edits yet.`);
+        }
+        const result = applyPhaseOverride(progress, normalized, rate, reason, {
+            changeDir,
+            trigger: 'manual-cli',
+        });
+        progress.lastUpdatedAt = getBeijingTime();
+        await atomicWriteJson(progressPath, progress);
+        await persistAccuracyJson(changeDir, progress);
+        console.log(`\n✓ Phase accuracy overridden: ${changeId} / ${normalized}`);
+        console.log(`  - Affected buckets: ${result.affectedBuckets}`);
+        for (const d of result.details) {
+            console.log(`    [${normalized}/${d.trackedKind}] raw=${(d.originalRateRaw * 100).toFixed(2)}% -> overridden=${(d.overriddenRate * 100).toFixed(2)}% (aiTotal=${d.originalAiTotalLines}, correction=${d.originalUserCorrectionLines})`);
+        }
+        console.log(`  - Reason: ${reason}\n`);
+    }
+    /**
+     * Mark a phase's accuracy as confirmed by user.
+     * Usage: zhuanspec progress confirm-phase <change-id> <phase>
+     *
+     * 对该 phase 的所有桶写入 confirmed: { at, by: 'manual-cli' }，
+     * 后续 phase-transition-check 判定时会读此标记放行。
+     */
+    async confirmPhase(changeId, phase) {
+        const ALLOWED = ['techDesign', 'propose', 'apply', 'review'];
+        const normalized = ALLOWED.find(p => p.toLowerCase() === phase.toLowerCase());
+        if (!normalized) {
+            throw new Error(`Invalid phase for confirm-phase: ${phase}. Allowed: ${ALLOWED.join(', ')}`);
+        }
+        const cwd = resolveZhuanSpecRoot();
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+        if (!await FileSystemUtils.fileExists(progressPath)) {
+            throw new Error(`progress.json not found: ${progressPath}`);
+        }
+        const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        const buckets = progress.accuracy?.phaseAccuracy?.filter(b => b.phase === normalized) ?? [];
+        if (buckets.length === 0) {
+            throw new Error(`No phaseAccuracy bucket for ${changeId}/${normalized}. Nothing to confirm.`);
+        }
+        const result = confirmPhaseAccuracy(progress, normalized, 'manual-cli', { changeDir });
+        progress.lastUpdatedAt = getBeijingTime();
+        await atomicWriteJson(progressPath, progress);
+        await persistAccuracyJson(changeDir, progress);
+        console.log(`\n✓ Phase accuracy confirmed: ${changeId} / ${normalized} (buckets=${result.affectedBuckets}, by=manual-cli)\n`);
+    }
+    /**
+     * Show per-bucket snapshot for a specific phase (read-only).
+     * Usage: zhuanspec progress show-phase-accuracy <change-id> <phase>
+     *
+     * 用于 phase-transition-check 阻断后 AI 先查看数据，再调 AskUserQuestion 纠正。
+     */
+    async showPhaseAccuracy(changeId, phase, options) {
+        const ALLOWED = ['techDesign', 'propose', 'apply', 'review'];
+        const normalized = ALLOWED.find(p => p.toLowerCase() === phase.toLowerCase());
+        if (!normalized) {
+            throw new Error(`Invalid phase: ${phase}. Allowed: ${ALLOWED.join(', ')}`);
+        }
+        const cwd = resolveZhuanSpecRoot();
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+        if (!await FileSystemUtils.fileExists(progressPath)) {
+            throw new Error(`progress.json not found: ${progressPath}`);
+        }
+        const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        const buckets = progress.accuracy?.phaseAccuracy?.filter(b => b.phase === normalized) ?? [];
+        if (options?.json) {
+            console.log(JSON.stringify({
+                changeId,
+                phase: normalized,
+                buckets,
+                legacy: buckets.length === 0,
+            }, null, 2));
+            return;
+        }
+        console.log(`\n📊 Phase accuracy: ${changeId} / ${normalized}`);
+        console.log('─'.repeat(60));
+        if (buckets.length === 0) {
+            console.log('  —（历史数据，无 phaseAccuracy 桶）');
+            console.log();
+            return;
+        }
+        for (const b of buckets) {
+            const raw = ((b.accuracyRateRaw ?? b.accuracyRate) * 100).toFixed(2);
+            const show = ((b.accuracyRate ?? 1) * 100).toFixed(2);
+            const overrideCount = b.overrideHistory?.length ?? 0;
+            const confirmed = b.confirmed ? `✓ ${b.confirmed.by}@${b.confirmed.at}` : '✗ 未确认';
+            console.log(`  [${b.phase}/${b.trackedKind}]`);
+            console.log(`    AI产出:       ${b.aiTotalLines} 行 (added=${b.aiLinesAdded}, modified=${b.aiLinesModified})`);
+            console.log(`    用户纠偏:     ${b.userCorrectionLines} 行 (prompts=${b.correctionPromptIds.length})`);
+            console.log(`    raw/展示:     ${raw}% / ${show}%`);
+            console.log(`    override次数: ${overrideCount}`);
+            console.log(`    confirmed:    ${confirmed}`);
+            if (overrideCount > 0 && b.overrideHistory) {
+                const last = b.overrideHistory[overrideCount - 1];
+                console.log(`    最近 reason:   ${last.reason} (${last.timestamp})`);
+            }
+        }
+        console.log();
+    }
 }
 //# sourceMappingURL=progress.js.map

package/dist/core/archive.js

@@ -165,6 +165,34 @@ export class ArchiveCommand {
         }
         // Single source of truth for archive gate: preArchiveHook (review/tests/spec-code consistency)
         await preArchiveHook({ change: changeName, json: false });
+        // === Task 5: 归档前 auto-confirm 未确认的分阶段准确率桶 ===
+        // 预期效果：archive 不可逆前，对所有 phaseAccuracy 桶写入 confirmed: { at, by: 'auto-archive' }
+        // 历史数据（无 phaseAccuracy 或空）自然跳过；失败不阻断归档主流程
+        try {
+            const { confirmPhaseAccuracy } = await import('./metrics/code-accuracy.js');
+            const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+            try {
+                await fs.access(progressPath);
+                const progressRaw = await fs.readFile(progressPath, 'utf-8');
+                const progress = JSON.parse(progressRaw);
+                const buckets = progress?.accuracy?.phaseAccuracy ?? [];
+                const pending = buckets.filter((b) => !b.confirmed);
+                if (pending.length > 0) {
+                    const phases = Array.from(new Set(pending.map((b) => b.phase)));
+                    for (const ph of phases) {
+                        confirmPhaseAccuracy(progress, ph, 'auto-archive', { changeDir });
+                    }
+                    await fs.writeFile(progressPath, JSON.stringify(progress, null, 2), 'utf-8');
+                    console.log(chalk.gray(`已自动确认 ${pending.length} 个分阶段准确率桶（by: auto-archive）`));
+                }
+            }
+            catch {
+                // progress.json 不存在或解析失败→历史数据/空变更，安全跳过
+            }
+        }
+        catch {
+            // 模块导入异常或其他非预期错误，不阻断归档
+        }
         // Handle spec updates unless skipSpecs flag is set
         if (options.skipSpecs) {
             console.log('跳过规范更新（已提供 --skip-specs 标志）。');

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

@@ -13,12 +13,22 @@
  *
  *   ~/.codex/ (or $CODEX_HOME)
  *     config.toml   - Per-project [projects."…"] trusted_level = "trusted"
- *                     block (wrapped in TRUST markers keyed by absolute path)
+ *                     block (wrapped in TRUST markers keyed by absolute path).
+ *                     Also receives [hooks.state."<abs>:<event>:<i>:<j>"]
+ *                     entries grafted from other already-trusted projects,
+ *                     wrapped in HOOK_STATE markers keyed by config.toml 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`.
  *
+ * Codex CLI >= 0.129 additionally requires each hook's content hash to be
+ * pre-approved (openai/codex#20321) or the user sees "N hooks need review".
+ * The `trusted_hash` in `[hooks.state.<key>]` depends only on normalised hook
+ * *content* (event + matcher + command), not on the key path, so we clone a
+ * previously approved hash to the current project's key to skip the manual
+ * review prompt in fresh workspaces.
+ *
  * Idempotency:
  *   - Hooks block is regenerated inside ZHUANSPEC markers on every run.
  *   - Trust entries are keyed by absolute path; repeated runs no-op.
@@ -50,6 +60,24 @@ export interface CodexConfigureResult {
      * installs to avoid user confusion. Empty when nothing needed removing.
      */
     legacyPromptsCleaned: string[];
+    /**
+     * Summary of per-hook content-trust seeding in `~/.codex/config.toml`.
+     * Codex CLI >= 0.129 requires every hook handler's SHA-256 fingerprint to
+     * be pre-approved via the TUI; we clone hashes from already-trusted
+     * projects so freshly initialised workspaces skip the `/hooks` review.
+     */
+    hookTrust: CodexHookTrustResult;
+}
+/** Outcome of the `ensureHookTrustSeed` pass. */
+export interface CodexHookTrustResult {
+    /** Slot suffixes (`<event>:<group>:<handler>`) whose trusted_hash was grafted. */
+    written: string[];
+    /** Slot suffixes without any seed hash in the global config — user must approve once. */
+    skippedNoSeed: string[];
+    /** Slot suffixes already owned by a pre-existing, unmanaged `[hooks.state]` entry. */
+    skippedNative: string[];
+    /** True iff at least one seed hash was found (for any slot) in the global config. */
+    seedAvailable: boolean;
 }
 export declare class CodexConfigurator implements ToolConfigurator {
     name: string;
@@ -133,5 +161,31 @@ export declare class CodexConfigurator implements ToolConfigurator {
      * when the block already matches).
      */
     private replaceTrustBlock;
+    /**
+     * Graft `[hooks.state."<key>"] trusted_hash = "sha256:..."` entries for the
+     * current project from any other project that the user has already approved
+     * via Codex's `/hooks` TUI. The grafted block is wrapped in HOOK_STATE
+     * markers keyed by `configTomlPath` so it stays idempotent across runs and
+     * coexists with HOOK_STATE blocks for sibling projects in the same file.
+     *
+     * Strategy:
+     *   - Strip our own existing block first to avoid self-referencing seeds.
+     *   - Scan remaining `[hooks.state."<path>:<event>:<grp>:<hdl>"]` tables;
+     *     index their `trusted_hash` by the `<event>:<grp>:<hdl>` suffix so the
+     *     same logical hook in any other project can serve as a seed.
+     *   - For each ZhuanSpec default slot:
+     *       * If a native (unmanaged) entry already owns the same key in this
+     *         project, skip to avoid TOML duplicate-key errors.
+     *       * Else if a seed exists, emit a managed entry pointing the user's
+     *         project key at the known-good hash.
+     *       * Else record the slot in `skippedNoSeed` so callers can surface a
+     *         "please approve once in Codex" hint.
+     *
+     * Failures are non-fatal: any unexpected error is swallowed and reported
+     * via an empty result with `seedAvailable=false`, since hook trust is a
+     * UX optimisation — missing it just means the user sees the regular
+     * Codex review prompt.
+     */
+    private ensureHookTrustSeed;
 }
 //# sourceMappingURL=codex.d.ts.map