@zhuan-ai/zhuanspec 2.15.7 → 2.16.2

package/dist/core/init.d.ts

@@ -21,6 +21,10 @@ type ToolWizardConfig = {
     initialSelected?: string[];
 };
 type ToolSelectionPrompt = (config: ToolWizardConfig) => Promise<string[]>;
+type ClaudeHookSyncSummary = {
+    totalAddedHooks: number;
+    duplicateHooksSkipped: number;
+};
 type InitCommandOptions = {
     prompt?: ToolSelectionPrompt;
     tools?: string;
@@ -49,6 +53,11 @@ export declare class InitCommand {
     private fetchRemoteArchitectureFiles;
     private fetchRemoteArchitectureContent;
     private cloneRemoteArchitectureRepoToTemp;
+    /**
+     * Append a JSONL line to ~/.zhuanspec-init-debug.log for offline troubleshooting.
+     * Failures are swallowed to avoid breaking init.
+     */
+    private logInitDebug;
     private syncBusinessSpecTemplate;
     private syncBusinessClaudeAssets;
     private resolveBusinessDirectionRoot;
@@ -72,6 +81,13 @@ export declare class InitCommand {
     private writeTemplateFiles;
     private configureAITools;
     private configureRootAgentsStub;
+    /**
+     * v2.15.16：对外暴露的 settings.json 同步入口，给 zhuanspec update 复用。
+     * 会走 generateClaudeSettings 同样的 merge + 老 group 清理逻辑，
+     * 确保老版 settings.json（如还挂着 deviation-check --trigger post-prompt）
+     * 在升级后能被过滤掉。
+     */
+    syncClaudeSettings(projectPath: string): Promise<ClaudeHookSyncSummary>;
     /**
      * Generate Claude Code hooks configuration for ZhuanSpec workflow.
      * Creates .claude/settings.json with hooks for SessionStart, PreToolUse, PostToolUse, and Stop.

package/dist/core/init.js

@@ -1,6 +1,6 @@
 import path from 'path';
 import os from 'os';
-import { cpSync, existsSync, mkdirSync, mkdtempSync, realpathSync, writeFileSync, readdirSync, readFileSync, rmSync, } from 'fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, realpathSync, writeFileSync, readdirSync, readFileSync, rmSync, appendFileSync, } from 'fs';
 import { createPrompt, isBackspaceKey, isDownKey, isEnterKey, isSpaceKey, isUpKey, useKeypress, usePagination, useState, } from '@inquirer/core';
 import chalk from 'chalk';
 import ora from 'ora';
@@ -37,6 +37,25 @@ const parseToolLabel = (raw) => {
     };
 };
 const isSelectableChoice = (choice) => choice.selectable;
+/**
+ * v2.15.16：判定一个 hook group 是否完全由 ZhuanSpec 管辖。
+ * 条件：group.hooks 里所有 entry 的 command 都以 `zhuanspec-hook` 开头。
+ * 任何一个非 ZhuanSpec 命令（用户自己挂的）都会让整组保留，避免误伤。
+ * 用于 zhuanspec update 时清理老模板挂载、但新模板已删除的 entry（如 Sprint 3 下线的 deviation-check --trigger post-prompt）。
+ */
+function isZhuanspecManagedHookGroup(group) {
+    if (!group || typeof group !== 'object')
+        return false;
+    const hooks = group.hooks;
+    if (!Array.isArray(hooks) || hooks.length === 0)
+        return false;
+    return hooks.every((h) => {
+        if (!h || typeof h !== 'object')
+            return false;
+        const command = h.command;
+        return typeof command === 'string' && command.trim().startsWith('zhuanspec-hook');
+    });
+}
 const ROOT_STUB_CHOICE_VALUE = '__root_stub__';
 const OTHER_TOOLS_HEADING_VALUE = '__heading-other__';
 const LIST_SPACER_VALUE = '__list-spacer__';
@@ -787,15 +806,56 @@ export class InitCommand {
     }
     cloneRemoteArchitectureRepoToTemp() {
         const tempDir = mkdtempSync(path.join(os.tmpdir(), 'zhuanspec-arch-'));
+        const startedAt = Date.now();
         try {
-            execSync(`git clone --depth 1 --single-branch --branch ${ARCH_REPO_BRANCH} ${ARCH_REPO_URL} "${tempDir}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] });
+            execSync(`git clone --depth 1 --single-branch --branch ${ARCH_REPO_BRANCH} ${ARCH_REPO_URL} "${tempDir}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+            this.logInitDebug({
+                scope: 'cloneRemoteArchitectureRepoToTemp',
+                result: 'ok',
+                repo: ARCH_REPO_URL,
+                branch: ARCH_REPO_BRANCH,
+                tempDir,
+                elapsedMs: Date.now() - startedAt,
+            });
             return tempDir;
         }
-        catch {
+        catch (err) {
+            this.logInitDebug({
+                scope: 'cloneRemoteArchitectureRepoToTemp',
+                result: 'fail',
+                repo: ARCH_REPO_URL,
+                branch: ARCH_REPO_BRANCH,
+                tempDir,
+                elapsedMs: Date.now() - startedAt,
+                errorMessage: err?.message ?? String(err),
+                stderr: err?.stderr ? String(err.stderr).slice(0, 1000) : undefined,
+                stdout: err?.stdout ? String(err.stdout).slice(0, 500) : undefined,
+                status: err?.status,
+            });
             rmSync(tempDir, { recursive: true, force: true });
             return null;
         }
     }
+    /**
+     * Append a JSONL line to ~/.zhuanspec-init-debug.log for offline troubleshooting.
+     * Failures are swallowed to avoid breaking init.
+     */
+    logInitDebug(payload) {
+        try {
+            const line = JSON.stringify({
+                ts: new Date().toISOString(),
+                pid: process.pid,
+                cwd: process.cwd(),
+                businessDirection: this.businessDirection ?? null,
+                ...payload,
+            });
+            const logPath = path.join(os.homedir(), '.zhuanspec-init-debug.log');
+            appendFileSync(logPath, line + '\n', 'utf-8');
+        }
+        catch {
+            // ignore
+        }
+    }
     syncBusinessSpecTemplate(zhuanspecPath) {
         if (!this.businessDirection) {
             return { syncedSpecs: false, syncedChanges: false, syncedKnowledge: false };
@@ -832,10 +892,20 @@ export class InitCommand {
             dotClaude: { source: 'none', files: { added: [], overwritten: [], skipped: [] } },
         };
         if (!this.businessDirection) {
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'skip-no-business-direction',
+                projectPath,
+            });
             return fallbackResult;
         }
         const tempDir = this.cloneRemoteArchitectureRepoToTemp();
         if (!tempDir) {
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'skip-clone-failed',
+                projectPath,
+            });
             return fallbackResult;
         }
         try {
@@ -849,12 +919,50 @@ export class InitCommand {
             const resolvedClaudeMdSource = this.resolveClaudeAssetSource(businessClaudeMd, commonClaudeMd);
             // .claude directory: always from common directory (not business-specific)
             const commonDotClaude = path.join(commonClaudeRoot, '.claude');
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'start-copy',
+                projectPath,
+                tempDir,
+                specsRootExists: existsSync(specsRoot),
+                businessRoot,
+                commonClaudeRoot,
+                commonClaudeRootExists: existsSync(commonClaudeRoot),
+                commonDotClaude,
+                commonDotClaudeExists: existsSync(commonDotClaude),
+                commonDotClaudeHasFiles: existsSync(commonDotClaude)
+                    ? this.directoryHasAtLeastOneFile(commonDotClaude)
+                    : false,
+                commonDotClaudeTopEntries: existsSync(commonDotClaude)
+                    ? readdirSync(commonDotClaude)
+                    : [],
+            });
+            const claudeMdResult = this.copyClaudeFileIfNeeded(resolvedClaudeMdSource, path.join(projectPath, 'CLAUDE.md'));
+            const dotClaudeResult = this.copyClaudeDirectoryFromCommon(commonDotClaude, path.join(projectPath, '.claude'));
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'done',
+                projectPath,
+                claudeMd: claudeMdResult,
+                dotClaudeSource: dotClaudeResult.source,
+                dotClaudeAdded: dotClaudeResult.files.added.length,
+                dotClaudeOverwritten: dotClaudeResult.files.overwritten.length,
+                dotClaudeSkipped: dotClaudeResult.files.skipped.length,
+                dotClaudeAddedSample: dotClaudeResult.files.added.slice(0, 5),
+            });
             return {
-                claudeMd: this.copyClaudeFileIfNeeded(resolvedClaudeMdSource, path.join(projectPath, 'CLAUDE.md')),
-                dotClaude: this.copyClaudeDirectoryFromCommon(commonDotClaude, path.join(projectPath, '.claude')),
+                claudeMd: claudeMdResult,
+                dotClaude: dotClaudeResult,
             };
         }
-        catch {
+        catch (err) {
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'exception',
+                projectPath,
+                errorMessage: err?.message ?? String(err),
+                stack: err?.stack ? String(err.stack).slice(0, 500) : undefined,
+            });
             return fallbackResult;
         }
         finally {
@@ -972,13 +1080,30 @@ export class InitCommand {
             files: { added: [], overwritten: [], skipped: [] },
         };
         if (!sourceAsset) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                result: 'skip-no-source-asset',
+                targetPath,
+            });
             return emptyResult;
         }
         if (!existsSync(sourceAsset.path)) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                result: 'skip-source-not-exists',
+                sourcePath: sourceAsset.path,
+                targetPath,
+            });
             return { source: sourceAsset.source, files: { added: [], overwritten: [], skipped: [] } };
         }
         const repoRoot = this.findGitRootForPath(sourceAsset.path);
         if (!repoRoot) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                branch: 'fallback-fs-no-git-root',
+                sourcePath: sourceAsset.path,
+                targetPath,
+            });
             return this.copyClaudeDirectoryByFileSystem(sourceAsset, targetPath);
         }
         const canonicalRepoRoot = this.safeRealpath(repoRoot);
@@ -989,13 +1114,38 @@ export class InitCommand {
             .join('/');
         if (relativeSourceDir.startsWith('..') ||
             path.isAbsolute(relativeSourceDir)) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                branch: 'fallback-fs-bad-relative',
+                canonicalRepoRoot,
+                canonicalSourcePath,
+                relativeSourceDir,
+                targetPath,
+            });
             return this.copyClaudeDirectoryByFileSystem(sourceAsset, targetPath);
         }
         const filesResult = this.copyGitTrackedDirectoryFiles(canonicalRepoRoot, relativeSourceDir, targetPath);
         const totalFiles = filesResult.added.length + filesResult.overwritten.length + filesResult.skipped.length;
         if (totalFiles === 0) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                branch: 'git-tracked-empty',
+                canonicalRepoRoot,
+                relativeSourceDir,
+                targetPath,
+            });
             return { source: sourceAsset.source, files: { added: [], overwritten: [], skipped: [] } };
         }
+        this.logInitDebug({
+            scope: 'copyClaudeDirectoryIfNeeded',
+            branch: 'git-tracked-ok',
+            canonicalRepoRoot,
+            relativeSourceDir,
+            targetPath,
+            added: filesResult.added.length,
+            overwritten: filesResult.overwritten.length,
+            skipped: filesResult.skipped.length,
+        });
         return {
             source: sourceAsset.source,
             files: filesResult,
@@ -1120,8 +1270,25 @@ export class InitCommand {
                 .map((line) => line.trim())
                 .filter((line) => line.length > 0);
             if (trackedFiles.length === 0) {
+                this.logInitDebug({
+                    scope: 'copyGitTrackedDirectoryFiles',
+                    result: 'empty-tracked-files',
+                    gitRoot,
+                    sourceDirRelativeToGitRoot,
+                    targetDir,
+                    rawOutputPreview: output.slice(0, 200),
+                });
                 return result;
             }
+            this.logInitDebug({
+                scope: 'copyGitTrackedDirectoryFiles',
+                result: 'tracked-files-loaded',
+                gitRoot,
+                sourceDirRelativeToGitRoot,
+                targetDir,
+                trackedCount: trackedFiles.length,
+                sample: trackedFiles.slice(0, 5),
+            });
             // 确保目标目录存在，但不删除已有内容
             mkdirSync(targetDir, { recursive: true });
             trackedFiles.forEach((repoFilePath) => {
@@ -1159,7 +1326,17 @@ export class InitCommand {
             });
             return result;
         }
-        catch {
+        catch (err) {
+            this.logInitDebug({
+                scope: 'copyGitTrackedDirectoryFiles',
+                result: 'exception',
+                gitRoot,
+                sourceDirRelativeToGitRoot,
+                targetDir,
+                errorMessage: err?.message ?? String(err),
+                stderr: err?.stderr ? String(err.stderr).slice(0, 500) : undefined,
+                status: err?.status,
+            });
             return result;
         }
     }
@@ -1237,6 +1414,15 @@ export class InitCommand {
         await configurator.configure(projectPath, zhuanspecDir);
         return existed ? 'updated' : 'created';
     }
+    /**
+     * v2.15.16：对外暴露的 settings.json 同步入口，给 zhuanspec update 复用。
+     * 会走 generateClaudeSettings 同样的 merge + 老 group 清理逻辑，
+     * 确保老版 settings.json（如还挂着 deviation-check --trigger post-prompt）
+     * 在升级后能被过滤掉。
+     */
+    async syncClaudeSettings(projectPath) {
+        return this.generateClaudeSettings(projectPath);
+    }
     /**
      * Generate Claude Code hooks configuration for ZhuanSpec workflow.
      * Creates .claude/settings.json with hooks for SessionStart, PreToolUse, PostToolUse, and Stop.
@@ -1267,8 +1453,8 @@ export class InitCommand {
                         hooks: [
                             {
                                 type: 'command',
-                                command: 'zhuanspec-hook deviation-check --trigger post-prompt',
-                                statusMessage: 'Checking prompt vs proposal consistency...',
+                                command: 'zhuanspec-hook user-input',
+                                statusMessage: 'Recording user input & correction context...',
                             },
                         ],
                     },
@@ -1381,7 +1567,18 @@ export class InitCommand {
                     // Append ZhuanSpec hooks to existing hooks array while de-duplicating.
                     const existingArray = existingHooks[hookType];
                     const zhuanspecArray = zhuanspecHookConfig;
-                    const existingSignatures = new Set(existingArray.map((item) => JSON.stringify(item)));
+                    // v2.15.16：先剔除所有纯 ZhuanSpec 管辖的老 group，再 append 新模板。
+                    // 防止 Sprint 3 下线的 deviation-check --trigger post-prompt 等旧 entry
+                    // 因老 settings.json 残留而永久活下来；非 ZhuanSpec entry（用户自己挂的）全量保留。
+                    const cleanedExisting = [];
+                    for (const item of existingArray) {
+                        if (isZhuanspecManagedHookGroup(item)) {
+                            // 被清理的老 group，这里静默丢掉（不计入 duplicateHooksSkipped）
+                            continue;
+                        }
+                        cleanedExisting.push(item);
+                    }
+                    const existingSignatures = new Set(cleanedExisting.map((item) => JSON.stringify(item)));
                     const uniqueToAppend = [];
                     for (const item of zhuanspecArray) {
                         const signature = JSON.stringify(item);
@@ -1393,7 +1590,7 @@ export class InitCommand {
                         uniqueToAppend.push(item);
                     }
                     summary.totalAddedHooks += uniqueToAppend.length;
-                    existingHooks[hookType] = [...existingArray, ...uniqueToAppend];
+                    existingHooks[hookType] = [...cleanedExisting, ...uniqueToAppend];
                 }
                 else {
                     // Create new hook type with ZhuanSpec config

package/dist/core/metrics/code-accuracy.d.ts

@@ -9,10 +9,121 @@
  * 3. computeAccuracy() —— 计算准确率
  */
 import type { ProgressData } from '../hooks/record-progress.js';
+export interface AccuracyDebugEntry {
+    /** 事件类型：baseline.mark / ai.record / correction.record / skip.<reason> / rate.compute / rate.override / persist.ok / persist.fail */
+    type: string;
+    /** 所属 phase（如有） */
+    phase?: string;
+    /** 文件分类（如有） */
+    kind?: string;
+    /** 触发来源：hook / cli / archive / auto */
+    trigger?: string;
+    /** 输入快照（索引自由） */
+    input?: Record<string, unknown>;
+    /** 输出快照（索引自由） */
+    output?: Record<string, unknown>;
+    /** skip.* 时的原因 */
+    skipReason?: string;
+    /** 耗时（ms） */
+    durationMs?: number;
+    changeId?: string;
+}
+export declare const ACCURACY_DEBUG_LOG_FILENAME = ".accuracy-debug.log";
+/**
+ * 向 changeDir/metrics/.accuracy-debug.log 追写一行 JSONL。
+ * 失败不阻断主流程。
+ */
+export declare function appendAccuracyDebugLog(changeDir: string, entry: AccuracyDebugEntry): void;
 /**
  * 判断是否为代码文件（需纳入准确率统计）
  */
 export declare function isCodeFile(filePath: string): boolean;
+export type TrackedPhase = 'techDesign' | 'propose' | 'apply' | 'review';
+export type TrackedKind = 'techSpec' | 'proposalDoc' | 'code';
+/**
+ * 分阶段准确率桶。
+ * 注：纠偏明细的唯一事实源是顶层 AccuracyData.correctionEdits[]（桶不重复存明细）。
+ * 按 phase 查明细：progress.accuracy.correctionEdits.filter(e => e.phase === phaseX)。
+ */
+export interface PhaseAccuracyEntry {
+    phase: TrackedPhase;
+    trackedKind: TrackedKind;
+    aiLinesAdded: number;
+    aiLinesModified: number;
+    aiTotalLines: number;
+    userCorrectionLines: number;
+    accuracyRate: number;
+    accuracyRateRaw?: number;
+    /** 该 phase 触发纠偏的 promptId 列表（去重、按时间顺序） */
+    correctionPromptIds: string[];
+    firstRecordedAt?: string;
+    lastUpdatedAt?: string;
+    /**
+     * 用户确认标记（Task 4 阶段切换阻断式确认）。
+     * phase-transition-check 读此字段判定是否已确认。
+     */
+    confirmed?: {
+        at: string;
+        by: 'manual-cli' | 'auto-archive';
+    };
+    /**
+     * phase 级 override 历史；每次完整保留 raw 快照。
+     * 不覆盖，按时间追加，供事后差异分析。
+     */
+    overrideHistory?: Array<{
+        timestamp: string;
+        originalRate: number;
+        originalRateRaw: number;
+        originalAiTotalLines: number;
+        originalUserCorrectionLines: number;
+        overriddenRate: number;
+        reason: string;
+    }>;
+}
+/**
+ * 判定 filePath 在当前 phase 下是否属于白名单，并返回文件分类。
+ *
+ * - techDesign → changes/{changeId}/techDesign/** 下所有文件 (kind=techSpec)
+ * - propose    → changes/{changeId} 根下 proposal.md/tasks.md/design.md/test-cases.md，或 specs/**　(kind=proposalDoc)
+ * - apply / review → isCodeFile 通用白名单 (kind=code)
+ * - idle / archive → 不统计
+ */
+export declare function isTrackedFileForPhase(filePath: string, phase: string, changePath: string): {
+    tracked: boolean;
+    kind?: TrackedKind;
+};
+/**
+ * 取/建某 phase+kind 对应的准确率桶。
+ */
+export declare function getOrCreatePhaseBucket(progress: ProgressData, phase: TrackedPhase, kind: TrackedKind): PhaseAccuracyEntry;
+/**
+ * 重算 accuracy 相关字段。
+ * - 顶层 accuracyRateRaw/accuracyRate：基于顶层 aiTotalLines/userCorrectionLines，保留 override 覆写
+ * - 各阶段桶 accuracyRate：基于桶自身行数，保留桶级 override。
+ *
+ * @param opts.changeDir 传入后会向 .accuracy-debug.log 写 rate.compute 事件
+ * @param opts.trigger   触发来源标识（hook / cli / archive 等）
+ */
+export declare function recomputeAccuracyRate(progress: ProgressData, opts?: {
+    changeDir?: string;
+    trigger?: string;
+}): void;
+/**
+ * 统一入口：将 progress.accuracy 同步到 metrics/accuracy.json。
+ * 之前多处手写导致双写漂移，经此函数统一管理。
+ */
+export declare function persistAccuracyJson(changeDir: string, progress: ProgressData): Promise<void>;
+/**
+ * 计算指定 phase+kind 的桶聚合结果（只读）。
+ */
+export declare function computePhaseAccuracy(progress: ProgressData, phase: TrackedPhase, kind?: TrackedKind): (AccuracyResult & {
+    phase: TrackedPhase;
+    trackedKind?: TrackedKind;
+}) | null;
+/**
+ * 列出所有 phase+kind 桶的快照（只读）。
+ */
+export declare function listPhaseAccuracy(progress: ProgressData): PhaseAccuracyEntry[];
 export interface AccuracySnapshotResult {
     changeId: string;
     snapshotTimestamp: string;
@@ -21,7 +132,10 @@ export interface AccuracySnapshotResult {
     aiTotalLines: number;
 }
 /**
- * 在 Apply 阶段全部任务完成后调用，固化 AI 产出行数基线
+ * 在 Apply 阶段全部任务完成后调用，固化 AI 产出行数基线。
+ *
+ * 幂等语义：保留 existing 中已累积的 userCorrectionLines/overrideHistory/correctionEdits/phaseAccuracy，
+ * 仅刷新 snapshotTimestamp 与 AI 行数。写入后调用 recomputeAccuracyRate + persistAccuracyJson。
  */
 export declare function snapshotAiBaseline(progress: ProgressData, changeDir: string): Promise<AccuracySnapshotResult>;
 /**
@@ -72,9 +186,44 @@ export interface OverrideResult {
     overriddenRate: number;
 }
 /**
- * 写入手动修正记录
+ * 写入顶层准确率手动修正记录。
+ *
+ * override 时完整保留纠正前的 raw 快照（rate / rateRaw / aiTotal / correction），
+ * 永不覆盖，以供事后差异分析。
+ */
+export declare function applyOverride(progress: ProgressData, rate: number, opts?: {
+    reason?: string;
+    changeDir?: string;
+    trigger?: string;
+}): OverrideResult;
+export interface PhaseOverrideResult {
+    phase: TrackedPhase;
+    affectedBuckets: number;
+    details: Array<{
+        trackedKind: TrackedKind;
+        originalRate: number;
+        originalRateRaw: number;
+        originalAiTotalLines: number;
+        originalUserCorrectionLines: number;
+        overriddenRate: number;
+    }>;
+}
+/**
+ * 为某 phase 下的所有桶写入手动 override。
+ * 完整保留纠正前的桶级快照，后续可从 overrideHistory 还原。
+ */
+export declare function applyPhaseOverride(progress: ProgressData, phase: TrackedPhase, rate: number, reason: string, opts?: {
+    changeDir?: string;
+    trigger?: string;
+}): PhaseOverrideResult;
+/**
+ * 标记某 phase 准确率已被用户确认。phase-transition-check 会读此标记。
  */
-export declare function applyOverride(progress: ProgressData, rate: number): OverrideResult;
+export declare function confirmPhaseAccuracy(progress: ProgressData, phase: TrackedPhase, by?: 'manual-cli' | 'auto-archive', opts?: {
+    changeDir?: string;
+}): {
+    affectedBuckets: number;
+};
 export type AgentSource = 'ai' | 'user';
 export type StrategyLevel = 'L1' | 'L2' | 'L3';
 export interface SourceDetermination {