@zhuan-ai/zhuanspec 2.15.7 → 2.16.2

package/dist/cli/hooks.d.ts

@@ -10,5 +10,17 @@
  * - summarize: Stop hook - Summarize session progress
  * - review-*: Review phase hooks - Check skill outputs and control fix loops
  */
-export {};
+/**
+ * Phase Transition Check - Unified function for phase transition validation
+ */
+export declare function runPhaseTransitionCheck(options: {
+    from?: string;
+    to?: string;
+    change?: string;
+}): Promise<{
+    continue: boolean;
+    systemMessage?: string;
+    checks?: Record<string, boolean>;
+    requiresUserConfirmation?: boolean;
+}>;
 //# sourceMappingURL=hooks.d.ts.map

package/dist/cli/hooks.js

@@ -16,6 +16,7 @@ import { deviationCheckHook } from '../core/hooks/deviation-check.js';
 import { recordProgressHook, initializeProgress } from '../core/hooks/record-progress.js';
 import { collectKnowledgeHook } from '../core/hooks/collect-knowledge.js';
 import { summarizeHook } from '../core/hooks/summarize.js';
+import { runUserInputHook } from '../core/hooks/user-input-hook.js';
 import { preArchiveHook } from '../core/hooks/pre-archive.js';
 import { postArchiveHook } from '../core/hooks/post-archive.js';
 import { preApplyHook, checkPreApplyConditions } from '../core/hooks/pre-apply.js';
@@ -47,7 +48,17 @@ program
     .option('--trigger <type>', 'Trigger type: pre-tool|post-prompt|resume')
     .option('--prompt <text>', 'Prompt content for post-prompt checks')
     .action(async (options) => {
-    await deviationCheckHook(options);
+    // v2.15.16 Sprint 3：'post-prompt' 分支已由 user-input-hook 接管，此处保留参数仅为
+    // 兼容 v2.15.14 及更早版本的 .claude/settings.json（未执行过 zhuanspec update）。
+    // 收到 post-prompt 时直接 no-op 返回，避免破坏 UserPromptSubmit 事件链。
+    if (options.trigger === 'post-prompt') {
+        if (options.json) {
+            console.log(JSON.stringify({ continue: true, hookSpecificOutput: { hookEventName: 'UserPromptSubmit' } }));
+        }
+        return;
+    }
+    const { trigger, ...rest } = options;
+    await deviationCheckHook({ ...rest, trigger: trigger });
 });
 // PostToolUse hook - record progress
 program
@@ -91,6 +102,14 @@ program
     .action(async (options) => {
     await summarizeHook(options);
 });
+// UserPromptSubmit hook - record user input & activate correctionContext from phaseBaselines
+program
+    .command('user-input')
+    .description('UserPromptSubmit hook - Record user input and activate correction context post-baseline')
+    .option('--json', 'Output as JSON for Claude Code consumption (envelope printed regardless)')
+    .action(async () => {
+    await runUserInputHook();
+});
 program
     .command('pre-archive')
     .description('Pre-archive quality gate')
@@ -295,7 +314,7 @@ program
 /**
  * Phase Transition Check - Unified function for phase transition validation
  */
-async function runPhaseTransitionCheck(options) {
+export async function runPhaseTransitionCheck(options) {
     const cwd = resolveZhuanSpecRoot();
     const changeId = options.change || process.env.ZHUANSPEC_CHANGE_ID || '';
     const fromPhase = options.from || process.env.ZHUANSPEC_PHASE || 'idle';
@@ -324,6 +343,60 @@ async function runPhaseTransitionCheck(options) {
                 targetPhase = 'apply';
         }
     }
+    // === Phase 准确率确认门禅（Task 4）===
+    // 规则：上一 phase 存在 phaseAccuracy 桶但未 confirmed 时阻断，
+    // systemMessage 指引 AI 调 AskUserQuestion 与 show-phase-accuracy / override-phase / confirm-phase 纠正。
+    // 绕过方式：环境变量 ZHUANSPEC_SKIP_ACCURACY_CONFIRM=1（CI/自动化用）。
+    const SKIP_CONFIRM = process.env.ZHUANSPEC_SKIP_ACCURACY_CONFIRM === '1';
+    const CONFIRMABLE_PHASES = new Set(['techDesign', 'propose', 'apply', 'review']);
+    if (!SKIP_CONFIRM && CONFIRMABLE_PHASES.has(fromPhase)) {
+        try {
+            const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+            if (await FileSystemUtils.fileExists(progressPath)) {
+                const progressRaw = await FileSystemUtils.readFile(progressPath);
+                const progress = JSON.parse(progressRaw);
+                const buckets = progress.accuracy?.phaseAccuracy?.filter(b => b.phase === fromPhase) ?? [];
+                if (buckets.length > 0) {
+                    const unconfirmed = buckets.filter(b => !b.confirmed);
+                    if (unconfirmed.length > 0) {
+                        // 聚合展示
+                        const aiTotal = buckets.reduce((s, b) => s + (b.aiTotalLines || 0), 0);
+                        const correction = buckets.reduce((s, b) => s + (b.userCorrectionLines || 0), 0);
+                        const avgRate = buckets.length > 0
+                            ? buckets.reduce((s, b) => s + (b.accuracyRate || 0), 0) / buckets.length
+                            : 1;
+                        const rateStr = (avgRate * 100).toFixed(2);
+                        return {
+                            continue: false,
+                            requiresUserConfirmation: true,
+                            systemMessage: [
+                                `✗ Phase transition blocked: ${fromPhase} → ${targetPhase}`,
+                                '',
+                                `阶段 ${fromPhase} 的准确率尚未被用户确认（桶数=${buckets.length}，未确认=${unconfirmed.length}）。`,
+                                `当前数据：rate=${rateStr}%, AI产出=${aiTotal} 行, 用户纠偏=${correction} 行`,
+                                '',
+                                '请按以下步骤完成确认：',
+                                `1. 查看详细数据：zhuanspec progress show-phase-accuracy ${changeId} ${fromPhase}`,
+                                `2. 向用户提问（AskUserQuestion 或宿主等效工具）：`,
+                                `   问题：“${fromPhase} 阶段准确率为 ${rateStr}%（AI 产出 ${aiTotal} 行，纠偏 ${correction} 行），是否正确？”`,
+                                `   选项A 准确或已内消 → zhuanspec progress confirm-phase ${changeId} ${fromPhase}`,
+                                `   选项B 需纠正       → 询问正确率 rate 与原因 reason`,
+                                `        → zhuanspec progress override-phase ${changeId} ${fromPhase} --rate <0..1> --reason <text>`,
+                                `        → zhuanspec progress confirm-phase ${changeId} ${fromPhase}`,
+                                '3. 确认完成后重新运行 phase-transition-check。',
+                                '',
+                                '绕过本门禅（CI/自动化）：设置 ZHUANSPEC_SKIP_ACCURACY_CONFIRM=1。',
+                            ].join('\n'),
+                        };
+                    }
+                }
+                // 历史数据 / 无桶：跳过此门禅（fall-through 继续其他检查）
+            }
+        }
+        catch {
+            // 读取 progress.json 失败不阻断原有检查链路
+        }
+    }
     // Execute appropriate pre-check based on target phase
     switch (targetPhase) {
         case 'apply':

package/dist/cli/index.js

@@ -286,15 +286,26 @@ progressCmd
 });
 // Progress resolve-correction subcommand
 progressCmd
-    .command('resolve-correction <change-id>')
-    .description('Clear pending user-correction marker (Apply phase)')
+    .command('resolve-correction <change-id> [path]')
+    .description('Clear pending user-correction marker (Apply phase). `path` can be given positionally (A|B|C|D) or via --path.')
     .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) => {
+    .action(async (changeId, positionalPath, options) => {
     try {
+        // v2.15.16：兼容位置参数形式 `resolve-correction <change-id> A`。
+        // deviation-check 注入到纠偏上下文里的提示里一直用的是位置参数形式，
+        // LLM 跳过 --path 直接跳 `A` 是常见误用。
+        // 策略：只要有一个来源就画；两个都有且不一致时报错。
+        const merged = { ...(options || {}) };
+        if (positionalPath) {
+            if (merged.path && merged.path !== positionalPath) {
+                throw new Error(`Conflicting path: positional '${positionalPath}' vs --path '${merged.path}'. Please specify only one.`);
+            }
+            merged.path = positionalPath;
+        }
         const progressCommand = new ProgressCommand();
-        await progressCommand.resolveCorrection(changeId, options);
+        await progressCommand.resolveCorrection(changeId, merged);
     }
     catch (error) {
         console.log();
@@ -318,6 +329,102 @@ progressCmd
         process.exit(1);
     }
 });
+// Progress list-corrections subcommand (review-step0 踩坑沉淀决策清单)
+progressCmd
+    .command('list-corrections <change-id>')
+    .description('Render pending correction candidates (filter trivial acks + dedup) for review-step0 decision making')
+    .option('--out <path>', 'Output file path (default: zhuanspec/changes/<id>/review/pending-corrections.md)')
+    .option('--json', 'Print result as JSON to stdout instead of writing markdown file')
+    .action(async (changeId, options) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.listCorrections(changeId, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Progress mark-baseline subcommand (Task 0 手动路径)
+progressCmd
+    .command('mark-baseline <change-id> <phase>')
+    .description('Manually mark phase baseline (techDesign|propose|apply|review). After marking, subsequent user prompts that touch whitelist files are counted as corrections.')
+    .option('--force', 'Overwrite existing baseline mark')
+    .action(async (changeId, phase, options) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.markBaseline(changeId, phase, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Progress recompute subcommand (Task 5 统一重算分阶段准确率)
+progressCmd
+    .command('recompute <change-id>')
+    .description('Recompute phaseAccuracy buckets and top-level accuracyRate from accuracy.correctionEdits[]')
+    .action(async (changeId) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.recompute(changeId);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Progress override-phase subcommand (分阶段准确率手动修正)
+progressCmd
+    .command('override-phase <change-id> <phase>')
+    .description('Override accuracy rate for a specific phase (techDesign|propose|apply|review). Raw snapshot is preserved in overrideHistory for differential analysis.')
+    .requiredOption('--rate <n>', 'Overridden rate (0.0~1.0)')
+    .requiredOption('--reason <text>', 'Reason for override (required for audit trail)')
+    .action(async (changeId, phase, options) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.overridePhase(changeId, phase, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Progress confirm-phase subcommand (标记某阶段准确率已被用户确认)
+progressCmd
+    .command('confirm-phase <change-id> <phase>')
+    .description('Mark a phase accuracy as confirmed by user (required for phase-transition-check to pass)')
+    .action(async (changeId, phase) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.confirmPhase(changeId, phase);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Progress show-phase-accuracy subcommand (只读展示分阶段数据)
+progressCmd
+    .command('show-phase-accuracy <change-id> <phase>')
+    .description('Show per-bucket accuracy snapshot for a phase (read-only)')
+    .option('--json', 'Output as JSON')
+    .action(async (changeId, phase, options) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.showPhaseAccuracy(changeId, phase, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
 // Accuracy command
 program
     .command('accuracy [change-name]')

package/dist/commands/accuracy.js

@@ -44,7 +44,11 @@ export class AccuracyCommand {
             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);
+            const result = applyOverride(progress, overrideRate, {
+                reason: 'CLI --override',
+                changeDir,
+                trigger: 'manual-cli',
+            });
             // Persist to progress.json
             await atomicWriteJson(progressPath, progress);
             // Also update accuracy.json

package/dist/commands/knowledge.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Knowledge Command
+ *
+ * 管理项目级知识库 zhuanspec/knowledge/。当前仅提供 reindex 子命令：
+ * - reindex：扫描三类目录下的 *.md，解析 Front Matter，重建 index.md 三分区
+ *   （保留 `## Archive Log` 既有内容）。用于回补历史漂移。
+ */
+import { Command } from 'commander';
+interface ReindexOptions {
+    dryRun?: boolean;
+}
+export declare class KnowledgeCommand {
+    reindex(options?: ReindexOptions): Promise<void>;
+}
+/**
+ * 在给定的 parent commander Command 上挂载 `reindex` 子命令。
+ * 父命令由 cli/index.ts 创建，形如 `zhuanspec knowledge`。
+ */
+export declare function registerKnowledgeCommands(parent: Command): void;
+export {};
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/commands/knowledge.js

@@ -0,0 +1,80 @@
+/**
+ * Knowledge Command
+ *
+ * 管理项目级知识库 zhuanspec/knowledge/。当前仅提供 reindex 子命令：
+ * - reindex：扫描三类目录下的 *.md，解析 Front Matter，重建 index.md 三分区
+ *   （保留 `## Archive Log` 既有内容）。用于回补历史漂移。
+ */
+import path from 'path';
+import chalk from 'chalk';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { resolveZhuanSpecRoot } from '../utils/resolve-root.js';
+import { rebuildIndexContent, scanKnowledgeEntries, } from '../core/hooks/knowledge-index.js';
+export class KnowledgeCommand {
+    async reindex(options = {}) {
+        const repoRoot = resolveZhuanSpecRoot(process.cwd());
+        const knowledgeDir = path.join(repoRoot, 'zhuanspec', 'knowledge');
+        const indexPath = path.join(knowledgeDir, 'index.md');
+        if (!(await FileSystemUtils.directoryExists(knowledgeDir))) {
+            console.log(chalk.yellow(`⚠ 知识目录不存在：${knowledgeDir}`));
+            console.log(chalk.gray('  未沉淀任何项目知识，无需 reindex。'));
+            return;
+        }
+        const scan = await scanKnowledgeEntries(knowledgeDir);
+        const existing = (await FileSystemUtils.fileExists(indexPath))
+            ? await FileSystemUtils.readFile(indexPath)
+            : null;
+        const rebuilt = rebuildIndexContent(scan, existing);
+        // 输出扫描摘要
+        const counts = {
+            troubleshooting: scan.entries.filter((e) => e.category === 'troubleshooting').length,
+            bestPractices: scan.entries.filter((e) => e.category === 'best-practices').length,
+            implicitConventions: scan.entries.filter((e) => e.category === 'implicit-conventions').length,
+        };
+        console.log(chalk.cyan('📚 扫描结果：'));
+        console.log(chalk.gray(`  - troubleshooting        : ${counts.troubleshooting} 条`));
+        console.log(chalk.gray(`  - best-practices         : ${counts.bestPractices} 条`));
+        console.log(chalk.gray(`  - implicit-conventions   : ${counts.implicitConventions} 条`));
+        if (scan.warnings.length > 0) {
+            console.log(chalk.yellow(`\n⚠ 发现 ${scan.warnings.length} 条 Front Matter 不完整，建议尽快补齐：`));
+            for (const w of scan.warnings) {
+                console.log(chalk.yellow(`  ${w}`));
+            }
+        }
+        if (options.dryRun) {
+            console.log(chalk.cyan('\n🔎 dry-run：以下为将写入 index.md 的内容\n'));
+            console.log(rebuilt);
+            console.log(chalk.gray('\n（dry-run 模式未落盘，去掉 --dry-run 即可执行实际重建）'));
+            return;
+        }
+        if (existing !== null && existing === rebuilt) {
+            console.log(chalk.green('\n✓ index.md 与扫描结果一致，无需更新。'));
+            return;
+        }
+        await FileSystemUtils.writeFile(indexPath, rebuilt);
+        console.log(chalk.green(`\n✓ 已重建 ${path.relative(process.cwd(), indexPath)}`));
+        console.log(chalk.gray('  （## Archive Log 既有内容已保留）'));
+    }
+}
+/**
+ * 在给定的 parent commander Command 上挂载 `reindex` 子命令。
+ * 父命令由 cli/index.ts 创建，形如 `zhuanspec knowledge`。
+ */
+export function registerKnowledgeCommands(parent) {
+    parent
+        .command('reindex')
+        .description('扫描 zhuanspec/knowledge/ 三类目录并重建 index.md 三分区（保留 Archive Log）')
+        .option('--dry-run', '只预览差异，不写文件')
+        .action(async (options) => {
+        try {
+            const cmd = new KnowledgeCommand();
+            await cmd.reindex(options ?? {});
+        }
+        catch (error) {
+            console.log();
+            console.log(chalk.red(`✗ reindex 失败: ${error.message}`));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/commands/progress.d.ts

@@ -42,6 +42,19 @@ export declare 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 字段
      */
     resolveCorrection(changeId: string, options?: {
         path?: string;
@@ -55,5 +68,70 @@ export declare class ProgressCommand {
     showCorrection(changeId: string, options?: {
         tail?: number;
     }): Promise<void>;
+    /**
+     * List pending correction candidates with trivial-ack filtering and dedup.
+     * Usage: zhuanspec progress list-corrections <change-id> [--out <path>] [--json]
+     *
+     * 默认会把 markdown 清单写到 `zhuanspec/changes/<id>/review/pending-corrections.md`，
+     * 供 review 阶段「踩坑沉淀」步骤的 askUserQuestion 三选项决策使用。
+     * `--json` 模式只走 stdout JSON，不写文件，便于 skill / 测试程序消费。
+     */
+    listCorrections(changeId: string, options?: {
+        out?: string;
+        json?: boolean;
+    }): Promise<void>;
+    /**
+     * Mark phase baseline manually.
+     * Usage: zhuanspec progress mark-baseline <change-id> <phase> [--force]
+     *
+     * 仅允许 techDesign / propose / apply / review 四个 phase；
+     * 若已有 markedAt 且未指定 --force，则报告不改；
+     * 否则写入 markedBy='manual-cli' 并 atomicWriteJson 保存。
+     */
+    markBaseline(changeId: string, phase: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * 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 新增行数；顶层聚合字段保持不变。
+     */
+    recompute(changeId: string): Promise<void>;
+    /**
+     * 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" 反向驱动改进。
+     */
+    overridePhase(changeId: string, phase: string, options: {
+        rate: string;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * 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 判定时会读此标记放行。
+     */
+    confirmPhase(changeId: string, phase: string): Promise<void>;
+    /**
+     * Show per-bucket snapshot for a specific phase (read-only).
+     * Usage: zhuanspec progress show-phase-accuracy <change-id> <phase>
+     *
+     * 用于 phase-transition-check 阻断后 AI 先查看数据，再调 AskUserQuestion 纠正。
+     */
+    showPhaseAccuracy(changeId: string, phase: string, options?: {
+        json?: boolean;
+    }): Promise<void>;
 }
 //# sourceMappingURL=progress.d.ts.map