@zhuan-ai/zhuanspec 2.16.0 → 2.16.3

package/dist/core/hooks/record-progress.js

@@ -9,7 +9,7 @@
 import path from 'path';
 import { promises as fsPromises, existsSync, readFileSync, unlinkSync } from 'fs';
 import { FileSystemUtils } from '../../utils/file-system.js';
-import { PHASE_ORDER } from '../../utils/phase-utils.js';
+import { PHASE_ORDER, PHASE_IDLE_THRESHOLD_MS } from '../../utils/phase-utils.js';
 import { resolveZhuanSpecRoot } from '../../utils/resolve-root.js';
 import { isCodeFile, isTrackedFileForPhase, getOrCreatePhaseBucket, recomputeAccuracyRate, persistAccuracyJson, appendAccuracyDebugLog } from '../metrics/code-accuracy.js';
 import { detectHookHost, sanitizeCodexEnvelope } from '../../utils/hook-host.js';
@@ -112,9 +112,14 @@ export async function recoverProgressJsonForWrite(filePath) {
                 phaseDurations: [{
                         phase: recoveredPhase,
                         startedAt: '',
+                        lastUpdatedAt: '',
                         durationMs: 0,
                         taskCount: 0,
                         completedTaskCount: 0,
+                        wallClockMs: 0,
+                        idleMs: 0,
+                        lastActiveAt: '',
+                        _lastActiveEpoch: 0,
                     }],
                 stats: { tokenUsageTotal: 0, contextLoad: 0, durationMs: { techDesign: 0, propose: 0, apply: 0, review: 0, archive: 0 } },
             };
@@ -162,6 +167,69 @@ export function getBeijingTimeForFilename() {
     const seconds = String(beijingTime.getSeconds()).padStart(2, '0');
     return `${year}-${month}-${day} ${hours}-${minutes}-${seconds}`;
 }
+/**
+ * v2.16+ 活跃耗时累加器
+ *
+ * 每次 PostToolUse 心跳到达时调用，根据 gap = now - lastActiveAt 判断：
+ *   gap < PHASE_IDLE_THRESHOLD_MS → 活跃，累加到 durationMs
+ *   gap >= PHASE_IDLE_THRESHOLD_MS → 空闲，累加到 idleMs 并 push idleSegments
+ *
+ * 同步刷新 wallClockMs、lastActiveAt、lastUpdatedAt。
+ * 返回本次增量便于调用方决定是否刷新 stats。
+ */
+export function tickActivePhaseDuration(entry, nowEpoch = Date.now(), nowTimestamp = getBeijingTime()) {
+    // 初始化可选字段
+    if (entry.idleMs === undefined)
+        entry.idleMs = 0;
+    if (entry.wallClockMs === undefined)
+        entry.wallClockMs = 0;
+    const parse = (s) => {
+        if (!s)
+            return null;
+        const ms = new Date(s.replace(' ', 'T')).getTime();
+        return Number.isFinite(ms) ? ms : null;
+    };
+    // 优先使用毫秒级 epoch（精确），fallback 到秒级字符串解析（兼容老数据）
+    const lastTickStr = entry.lastActiveAt || entry.lastUpdatedAt || entry.startedAt;
+    const lastTickEpoch = entry._lastActiveEpoch ?? parse(lastTickStr);
+    const startEpoch = parse(entry.startedAt);
+    // 无法解析时间 → 仅刷新心跳时间
+    if (lastTickEpoch == null || startEpoch == null) {
+        entry.lastActiveAt = nowTimestamp;
+        entry.lastUpdatedAt = nowTimestamp;
+        entry._lastActiveEpoch = nowEpoch;
+        return { activeDelta: 0, idleDelta: 0 };
+    }
+    const gap = nowEpoch - lastTickEpoch;
+    let activeDelta = 0;
+    let idleDelta = 0;
+    if (gap > 0) {
+        if (gap < PHASE_IDLE_THRESHOLD_MS) {
+            // 活跃：累加到 durationMs
+            activeDelta = gap;
+            entry.durationMs = (entry.durationMs || 0) + gap;
+        }
+        else {
+            // 空闲：累加到 idleMs + 记录段
+            idleDelta = gap;
+            entry.idleMs = (entry.idleMs || 0) + gap;
+            entry.idleSegments = entry.idleSegments || [];
+            entry.idleSegments.push({
+                from: lastTickStr,
+                to: nowTimestamp,
+                durationMs: gap,
+            });
+        }
+    }
+    // 刷新 wallClockMs = now - startedAt
+    const wall = nowEpoch - startEpoch;
+    entry.wallClockMs = wall > 0 ? wall : (entry.wallClockMs || 0);
+    // 刷新心跳（字符串 + epoch 双写，epoch 用于下次 tick 精确计算）
+    entry.lastActiveAt = nowTimestamp;
+    entry.lastUpdatedAt = nowTimestamp;
+    entry._lastActiveEpoch = nowEpoch;
+    return { activeDelta, idleDelta };
+}
 export async function recordProgressHook(options) {
     // Read stdin for Claude Code hook input
     let stdinData = {};
@@ -419,6 +487,20 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
             if (progress.stats.durationMs.techDesign === undefined) {
                 progress.stats.durationMs.techDesign = 0;
             }
+            // v2.16+ 迁移：老 progress.json 的 phaseDurations entry 缺少 wallClockMs/idleMs/lastActiveAt
+            for (const entry of progress.phaseDurations) {
+                if (entry.wallClockMs === undefined) {
+                    // 老版本 durationMs 是墙钟差，复制到 wallClockMs，durationMs 保留作为活跃近似
+                    entry.wallClockMs = entry.durationMs || 0;
+                }
+                if (entry.idleMs === undefined) {
+                    entry.idleMs = 0;
+                }
+                if (!entry.lastActiveAt) {
+                    // 进行中 entry 用 lastUpdatedAt 兆底，已结束用 endedAt
+                    entry.lastActiveAt = entry.endedAt || entry.lastUpdatedAt || entry.startedAt;
+                }
+            }
         }
         else {
             progress = createNewProgress(changeId);
@@ -869,42 +951,34 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
     const contextLoadFromStdIn = Number(stdinData.tool_result?.contextLoad || 0);
     progress.stats.tokenUsageTotal += tokenUsageFromEnv + tokenUsageFromStdIn;
     progress.stats.contextLoad += contextLoadFromEnv + contextLoadFromStdIn;
-    // Calculate duration for current phase from phaseTransitions
-    // Find the last transition to current phase; if none exists (e.g. initial
-    // phase such as techDesign started via initializeProgress without a
-    // transition record), fall back to phaseDurations[].startedAt, then to
-    // progress.startedAt so every phase gets an accurate elapsed time.
-    const transitionsToCurrentPhase = progress.phaseTransitions.filter((t) => t.to === phase);
-    const currentPhaseStart = transitionsToCurrentPhase[transitionsToCurrentPhase.length - 1];
-    let phaseStartTimestamp;
-    if (currentPhaseStart) {
-        phaseStartTimestamp = currentPhaseStart.timestamp;
-    }
-    else {
-        const activePhaseDuration = [...progress.phaseDurations]
-            .reverse()
-            .find(pd => pd.phase === phase && !pd.endedAt);
-        if (activePhaseDuration?.startedAt) {
-            phaseStartTimestamp = activePhaseDuration.startedAt;
-        }
-        else if (progress.startedAt) {
-            phaseStartTimestamp = progress.startedAt;
-        }
-    }
-    if (phaseStartTimestamp) {
-        const startTime = new Date(phaseStartTimestamp.replace(' ', 'T')).getTime();
-        const elapsedMs = Date.now() - startTime;
-        if (Number.isFinite(startTime) && elapsedMs > 0) {
-            if (phase === 'techDesign')
-                progress.stats.durationMs.techDesign = elapsedMs;
-            if (phase === 'propose')
-                progress.stats.durationMs.propose = elapsedMs;
-            if (phase === 'apply')
-                progress.stats.durationMs.apply = elapsedMs;
-            if (phase === 'review')
-                progress.stats.durationMs.review = elapsedMs;
-            if (phase === 'archive')
-                progress.stats.durationMs.archive = elapsedMs;
+    // v2.16+：使用 tickActivePhaseDuration 累加活跃耗时
+    // 在 phaseDurations 中找到当前进行中的 entry，tick 一次心跳
+    const activeEntry = [...progress.phaseDurations]
+        .reverse()
+        .find(pd => pd.phase === phase && !pd.endedAt);
+    if (activeEntry) {
+        const nowEpoch = Date.now();
+        const nowTs = getBeijingTime();
+        tickActivePhaseDuration(activeEntry, nowEpoch, nowTs);
+        // 同步刷新 stats.durationMs（活跃耗时）
+        if (phase === 'techDesign')
+            progress.stats.durationMs.techDesign = activeEntry.durationMs;
+        if (phase === 'propose')
+            progress.stats.durationMs.propose = activeEntry.durationMs;
+        if (phase === 'apply')
+            progress.stats.durationMs.apply = activeEntry.durationMs;
+        if (phase === 'review')
+            progress.stats.durationMs.review = activeEntry.durationMs;
+        if (phase === 'archive')
+            progress.stats.durationMs.archive = activeEntry.durationMs;
+        // 同步 stats 的可选双轨字段
+        if (!progress.stats.wallClockMs)
+            progress.stats.wallClockMs = { techDesign: 0, propose: 0, apply: 0, review: 0, archive: 0 };
+        if (!progress.stats.idleMs)
+            progress.stats.idleMs = { techDesign: 0, propose: 0, apply: 0, review: 0, archive: 0 };
+        if (phase !== 'idle') {
+            progress.stats.wallClockMs[phase] = activeEntry.wallClockMs || 0;
+            progress.stats.idleMs[phase] = activeEntry.idleMs || 0;
         }
     }
     // === Auto-count tasks from tasks.md ===
@@ -1087,9 +1161,14 @@ function createNewProgress(changeId) {
         phaseDurations: [{
                 phase: initialPhase,
                 startedAt: getBeijingTime(),
+                lastUpdatedAt: getBeijingTime(),
                 durationMs: 0,
                 taskCount: 0,
                 completedTaskCount: 0,
+                wallClockMs: 0,
+                idleMs: 0,
+                lastActiveAt: getBeijingTime(),
+                _lastActiveEpoch: Date.now(),
             }],
         stats: {
             tokenUsageTotal: 0,
@@ -1156,16 +1235,16 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
                     timestamp,
                     triggeredBy: 'initializeProgress',
                 });
-                // Update previous phase duration
+                // Update previous phase duration with tick
                 const prevPhaseDuration = progress.phaseDurations.find(pd => pd.phase === previousPhase && !pd.endedAt);
                 if (prevPhaseDuration) {
+                    // 封段前 tick，确保最后活跃时间被累加
+                    const nowEpoch = Date.now();
+                    tickActivePhaseDuration(prevPhaseDuration, nowEpoch, timestamp);
                     prevPhaseDuration.endedAt = timestamp;
-                    const startTime = new Date(prevPhaseDuration.startedAt.replace(' ', 'T')).getTime();
-                    const endTime = new Date(timestamp.replace(' ', 'T')).getTime();
-                    const ms = Number.isFinite(startTime) && endTime > startTime ? endTime - startTime : 0;
-                    prevPhaseDuration.durationMs = ms;
-                    if (previousPhase && previousPhase !== 'idle' && ms > 0 && progress.stats?.durationMs) {
-                        progress.stats.durationMs[previousPhase] = ms;
+                    // 同步 stats
+                    if (previousPhase && previousPhase !== 'idle' && progress.stats?.durationMs) {
+                        progress.stats.durationMs[previousPhase] = prevPhaseDuration.durationMs;
                     }
                 }
                 else if (previousPhase && previousPhase !== 'idle') {
@@ -1181,6 +1260,7 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
                             phase: previousPhase,
                             startedAt: inferredStart,
                             endedAt: timestamp,
+                            lastUpdatedAt: timestamp,
                             durationMs: ms,
                             taskCount: 0,
                             completedTaskCount: 0,
@@ -1194,9 +1274,14 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
                 progress.phaseDurations.push({
                     phase: initialPhase,
                     startedAt: timestamp,
+                    lastUpdatedAt: timestamp,
                     durationMs: 0,
                     taskCount: 0,
                     completedTaskCount: 0,
+                    wallClockMs: 0,
+                    idleMs: 0,
+                    lastActiveAt: timestamp,
+                    _lastActiveEpoch: Date.now(),
                 });
             }
             progress.phase = initialPhase;
@@ -1267,21 +1352,25 @@ function seedInitialPhase(progress, initialPhase, timestamp) {
     progress.phaseDurations = progress.phaseDurations || [];
     const activeEntry = progress.phaseDurations.find(pd => pd.phase === initialPhase && !pd.endedAt);
     if (!activeEntry) {
-        // Close any still-open legacy entry (e.g. the placeholder 'idle' entry created in createNewProgress)
+        // Close any still-open legacy entry with tick
         for (const entry of progress.phaseDurations) {
             if (!entry.endedAt && entry.phase !== initialPhase) {
+                const nowEpoch = Date.now();
+                tickActivePhaseDuration(entry, nowEpoch, timestamp);
                 entry.endedAt = timestamp;
-                const startTime = new Date((entry.startedAt || timestamp).replace(' ', 'T')).getTime();
-                const endTime = new Date(timestamp.replace(' ', 'T')).getTime();
-                entry.durationMs = Number.isFinite(startTime) && endTime > startTime ? endTime - startTime : 0;
             }
         }
         progress.phaseDurations.push({
             phase: initialPhase,
             startedAt: timestamp,
+            lastUpdatedAt: timestamp,
             durationMs: 0,
             taskCount: 0,
             completedTaskCount: 0,
+            wallClockMs: 0,
+            idleMs: 0,
+            lastActiveAt: timestamp,
+            _lastActiveEpoch: Date.now(),
         });
     }
 }

package/dist/core/hooks/summarize.js

@@ -263,40 +263,39 @@ async function runSummarize() {
         && progressData.askedPitfallSaved !== true) {
         pitfallAskPending = true;
         const n = progressData.corrections.length;
-        const previews = progressData.corrections
-            .filter(c => c.event === 'detected')
-            .slice(-3)
-            .map((c, i) => `  ${i + 1}. ${c.promptPreview || '(no preview)'}`)
-            .join('\n');
         pitfallAdditionalContext = [
             '## ⚠️ ZhuanSpec 知识沉淀询问（收尾必做）',
             '',
-            `本轮会话发生过 ${n} 次用户纠偏且尚未沉淀，必须按以下顺序处理（严禁跳步，严禁自行 Write 知识文件）：`,
+            `本轮会话发生过 ${n} 次用户纠偏且尚未沉淀，必须按以下顺序处理（严禁跳步、严禁仅根据最近 N 条摘要拍脑袋决策、严禁自行 Write 知识文件）：`,
             '',
             '### 必须执行的步骤',
             '',
-            `1. **用 askUserQuestion 询问用户**（二选一）：`,
-            '   - header: "踩坑沉淀"',
-            `   - question: "本轮 Apply 阶段发生过 ${n} 次用户纠偏，是否沉淀为项目知识？"`,
-            '   - 选项 1: "是，沉淀"',
-            '   - 选项 2: "否，跳过"',
+            `1. **先生成决策清单（必须）**：运行`,
+            '   ```bash',
+            `   zhuanspec progress list-corrections ${changeId}`,
+            '   ```',
+            '   CLI 会过滤 trivial 确认词（如 "是的/好的/ok"）+ 去重（完全重复 + 子串包含）+ 启发式分类，输出到 `zhuanspec/changes/<change-id>/review/pending-corrections.md`，并在 stdout 给出 **合计 / 有效 / 过滤** 三个计数。',
             '',
-            `2. **用户选"是"**：**必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\`** （或等价的 \`/zhuanspec:knowledge\` slash command 并在交互中选择模式 B）完成沉淀。`,
-            `   - change-id 值为 \`${changeId}\``,
-            '   - **禁止直接 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**，禁止自行判定分类或文件名格式；所有写入由 skill 统一执行。',
-            '   - skill 将自动完成：读取 user_inputs.json（Level 1）或 summary 关键词批量扫描（Level 2）→ 分类决策树 → 去重扫描 → 套用统一 Front Matter → 写入对应分类目录 → 更新 index.md → 标记 resolve-correction。',
+            '2. **用 askUserQuestion 询问用户（三选项，禁止默认）**：',
+            '   - header: "踩坑沉淀"',
+            '   - question: "本轮有 M 条有效纠偏候选（已过滤 trivial / 去重，详见 review/pending-corrections.md），请选择沉淀范围："',
+            '   - 选项 1: "全部沉淀"',
+            '   - 选项 2: "选择性沉淀（请回复编号清单，例如 1,3,5）"',
+            '   - 选项 3: "跳过"',
             '',
-            `3. **用户选"否"**：运行 \`zhuanspec progress resolve-correction ${changeId} --mark-pitfall-saved\` 标记已处理，不写入任何知识文件。`,
+            `3. **用户选 "全部沉淀" 或 "选择性沉淀"**：必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\` （或 \`/zhuanspec:knowledge\` 模式 B）完成沉淀。change-id 值为 \`${changeId}\`。选择性沉淀时把用户回复的编号串以 \`--include <编号串>\` 透传给 skill。`,
+            '   - **禁止直接 Write/Edit 创建 `zhuanspec/knowledge/` 下的任何文件**，禁止自行判定分类或文件名格式；所有写入由 skill 统一执行。',
+            '   - skill 必须以 `pending-corrections.md` 作为商定范围的单一源，禁止从会话记忆里“发挥”额外条目。',
             '',
-            '### 纠偏记录摘要（最近 3 条 promptPreview）',
-            previews || '  (none)',
+            `4. **用户选 "跳过"**：运行 \`zhuanspec progress resolve-correction ${changeId} --mark-pitfall-saved\` 标记已处理，不写入任何知识文件。`,
             '',
             '### 红线提示',
             '- 禁止绕过 skill 直接 Write/Edit 知识文件（等同于绕过质量门禁）。',
+            '- 禁止跳过 list-corrections 一步，仅靠 promptPreview 拍脑袋决策。',
             '- 禁止新建 decisions/ 或三类目录以外的分类。',
             '- skill 模式 B 完成后会自动写入 askedPitfallSaved=true，无需人工重复调用 CLI。',
         ].join('\n');
-        systemMessage += `\n⚠️ 检测到 ${n} 次用户纠偏未沉淀——请按上方说明调 askUserQuestion，用户选是后必须调用 @skill:zhuanspec:knowledge 而非自行 Write。\n`;
+        systemMessage += `\n⚠️ 检测到 ${n} 次用户纠偏未沉淀——请先运行 zhuanspec progress list-corrections ${changeId}，再用 askUserQuestion 三选项决策，用户选「全部/选择性沉淀」后必须调用 @skill:zhuanspec:knowledge 而非自行 Write。\n`;
     }
     // === Task 0 路径 1：Stop 时按核心产出齐备度自动打 phase baseline ===
     // 幂等：已打标则跳过；先到先得（auto-file-complete 优于 auto-stop）

package/dist/core/hooks/user-input-hook.js

@@ -188,7 +188,10 @@ export async function userInputHook(content, responseTimeMs) {
     // Skip slash/bang commands (e.g. /zhuanspec:proposal, /compact, /clear, !ls).
     // 这类 prompt 是命令/workflow 触发，非“用户对 AI 产出的纠偏/濄清/补充”，
     // 不应计入 user_inputs.json，更不应放进纠偏溯源池影响 accuracyRate。
-    const trimmedContent = content.trim();
+    // 注意：Claude Code 在 slash 命令前会注入 NAK(U+0015) 等 C0 控制字符做标记，
+    // 普通 trim() 不会剥控制字符，必须显式剥掉前缀的 C0/DEL 再做正则判定，
+    // 否则像 "\u0015/zhuanspec:proposal" 这种命令会漏过过滤被记成普通用户输入。
+    const trimmedContent = content.trim().replace(/^[\x00-\x1F\x7F]+/, '');
     if (/^[/!][A-Za-z0-9_:/@.\-]+(\s|$)/.test(trimmedContent) || /^\/[\w:\-]+$/.test(trimmedContent)) {
         logDebug(cwd, {
             event: 'skip',

package/dist/core/init.d.ts

@@ -53,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;

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';
@@ -806,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 };
@@ -851,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 {
@@ -868,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 {
@@ -991,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);
@@ -1008,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,
@@ -1139,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) => {
@@ -1178,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;
         }
     }