@zhuan-ai/zhuanspec 2.16.2 → 2.16.3

package/dist/cli/index.js

@@ -11,6 +11,7 @@ import { ViewCommand } from '../core/view.js';
 import { registerSpecCommand } from '../commands/spec.js';
 import { ChangeCommand } from '../commands/change.js';
 import { ValidateCommand } from '../commands/validate.js';
+import { ValidateReportsCommand } from '../commands/validate-reports.js';
 import { ShowCommand } from '../commands/show.js';
 import { CompletionCommand } from '../commands/completion.js';
 import { ReviewCommand } from '../commands/review.js';
@@ -524,6 +525,25 @@ program
         process.exit(1);
     }
 });
+// Top-level validate-reports command
+program
+    .command('validate-reports <change-id>')
+    .description('Validate Apply-phase task reports against apply-agent / tdd-apply-agent templates')
+    .option('--json', 'Output validation summary as JSON')
+    .action(async (changeId, options) => {
+    try {
+        const cmd = new ValidateReportsCommand();
+        await cmd.execute(changeId, options);
+        if (typeof process.exitCode === 'number' && process.exitCode !== 0) {
+            process.exit(process.exitCode);
+        }
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
 // Top-level show command
 program
     .command('show [item-name]')

package/dist/commands/progress.js

@@ -295,9 +295,13 @@ export class ProgressCommand {
         // Progress percentage
         const percentage = totalTasks > 0 ? (completedCount / totalTasks) * 100 : 0;
         const progressBar = this.generateProgressBar(percentage, 12);
-        // Duration
+        // Duration (active time)
         const durationMs = progress?.stats?.durationMs?.[phase] || 0;
         const durationMin = Math.round(durationMs / 60000);
+        const wallClockMs = progress?.stats?.wallClockMs?.[phase] || 0;
+        const wallClockMin = Math.round(wallClockMs / 60000);
+        const idleMs = progress?.stats?.idleMs?.[phase] || 0;
+        const idleMin = Math.round(idleMs / 60000);
         const estimatedRemaining = totalTasks > 0 && completedCount > 0
             ? Math.round((durationMin / completedCount) * (totalTasks - completedCount))
             : 0;
@@ -319,8 +323,16 @@ export class ProgressCommand {
             console.log('');
         }
         // Duration info
-        if (durationMin > 0) {
-            console.log(`耗时: ${durationMin}m | 预计剩余: ~${estimatedRemaining}m`);
+        if (durationMin > 0 || wallClockMin > 0) {
+            const parts = [];
+            parts.push(`活跃: ${durationMin}m`);
+            if (idleMin > 0)
+                parts.push(`空闲: ${idleMin}m`);
+            if (wallClockMin > 0)
+                parts.push(`墙钟: ${wallClockMin}m`);
+            if (estimatedRemaining > 0)
+                parts.push(`预计剩余: ~${estimatedRemaining}m`);
+            console.log(parts.join(' | '));
         }
         console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
         console.log('');

package/dist/commands/validate-reports.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `zhuanspec validate-reports <change-id>` — 校验某个 change 下所有
+ * Apply 任务报告是否符合 apply-agent.md / tdd-apply-agent.md 模板。
+ *
+ * 设计要点：
+ * - 仅做静态文本/章节检测，不读取代码，零外部依赖。
+ * - JSON 输出与人类可读输出双通道，便于 hooks/CI 程序化消费。
+ * - 退出码：所有报告通过且无缺失 → 0；否则 1。
+ */
+interface ExecuteOptions {
+    json?: boolean;
+}
+export declare class ValidateReportsCommand {
+    execute(changeId: string | undefined, options?: ExecuteOptions): Promise<void>;
+}
+export {};
+//# sourceMappingURL=validate-reports.d.ts.map

package/dist/commands/validate-reports.js

@@ -0,0 +1,76 @@
+/**
+ * `zhuanspec validate-reports <change-id>` — 校验某个 change 下所有
+ * Apply 任务报告是否符合 apply-agent.md / tdd-apply-agent.md 模板。
+ *
+ * 设计要点：
+ * - 仅做静态文本/章节检测，不读取代码，零外部依赖。
+ * - JSON 输出与人类可读输出双通道，便于 hooks/CI 程序化消费。
+ * - 退出码：所有报告通过且无缺失 → 0；否则 1。
+ */
+import path from 'path';
+import chalk from 'chalk';
+import { promises as fs } from 'fs';
+import { validateTaskReports, } from '../core/validation/report-schema.js';
+export class ValidateReportsCommand {
+    async execute(changeId, options = {}) {
+        if (!changeId) {
+            console.error('Usage: zhuanspec validate-reports <change-id> [--json]');
+            process.exitCode = 1;
+            return;
+        }
+        const changeDir = path.join(process.cwd(), 'zhuanspec', 'changes', changeId);
+        try {
+            await fs.access(changeDir);
+        }
+        catch {
+            console.error(`未找到 change 目录：${changeDir}`);
+            process.exitCode = 1;
+            return;
+        }
+        const summary = await validateTaskReports(changeDir);
+        if (options.json) {
+            console.log(JSON.stringify(summary, null, 2));
+        }
+        else {
+            printHumanReadable(summary);
+        }
+        process.exitCode = summary.valid ? 0 : 1;
+    }
+}
+function printHumanReadable(summary) {
+    const { changeId, totalReports, passedReports, failedReports, missingReports } = summary;
+    console.log(`Change: ${changeId}`);
+    console.log(`Reports: total=${totalReports} passed=${passedReports} failed=${failedReports} missing=${missingReports.length}`);
+    console.log('');
+    for (const report of summary.reports) {
+        if (report.valid) {
+            console.log(`  ${chalk.green('✓')} task-${report.taskId}-report.md (${report.declaredAgentType})`);
+            continue;
+        }
+        console.log(`  ${chalk.red('✗')} task-${report.taskId}-report.md (declared=${report.declaredAgentType}, expected=${report.expectedAgentType})`);
+        for (const issue of report.issues) {
+            const tag = issue.level === 'ERROR' ? chalk.red('ERROR') : chalk.yellow('WARN');
+            console.log(`      [${tag}] ${issue.message}`);
+        }
+    }
+    if (missingReports.length > 0) {
+        console.log('');
+        console.log(chalk.red(`缺失报告（tasks.md 列出但 reports/ 中未找到）：`));
+        for (const taskId of missingReports) {
+            console.log(`  - task ${taskId}`);
+        }
+    }
+    console.log('');
+    if (summary.valid) {
+        console.log(chalk.green('All task reports conform to schema.'));
+    }
+    else {
+        console.log(chalk.red('Some task reports do NOT conform to schema. See errors above.'));
+        console.log('');
+        console.log('Hints:');
+        console.log('  - 缺章节通常意味着报告由主 agent 直写而非 subagent 产出');
+        console.log('  - 重新通过 Agent tool / spawn_agent 启动 subagent 重跑对应任务');
+        console.log('  - 如果是合理降级，请在 "Agent 选择决策" 中显式写 "TDD 适用性: 不适合（降级原因：...）"');
+    }
+}
+//# sourceMappingURL=validate-reports.js.map

package/dist/core/hooks/record-progress.d.ts

@@ -32,6 +32,20 @@ export declare function getBeijingTime(): string;
  * Returns format: "2026-04-21 18-35-22" (文件名安全格式)
  */
 export declare function getBeijingTimeForFilename(): string;
+/**
+ * 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 declare function tickActivePhaseDuration(entry: PhaseDurationRecord, nowEpoch?: number, nowTimestamp?: string): {
+    activeDelta: number;
+    idleDelta: number;
+};
 interface RecordProgressOptions {
     json?: boolean;
     file?: string;
@@ -143,6 +157,14 @@ interface ClarificationRecord {
 }
 /**
  * Phase duration record for tracking time spent in each phase
+ *
+ * v2.16+：字段语义反转
+ *   - durationMs：覆盖为“活跃耗时”（剔除空闲段，PHASE_IDLE_THRESHOLD_MS 内累加），
+ *     业务主指标，与上报/采集口径保持一致。
+ *   - wallClockMs：原 durationMs 的语义（endedAt|lastUpdatedAt - startedAt 墙钟差），
+ *     仅作审计/调试参考，迁移期老 progress.json 会把老的 durationMs 复制到此字段。
+ *   - idleMs / idleSegments：活跃耗时之外被剔除的空闲明细（可观测）。
+ *   - lastActiveAt：最后一次 hook 心跳的北京时间字符串，下次心跳到达时计算 gap。
  */
 export interface PhaseDurationRecord {
     phase: Phase;
@@ -152,6 +174,15 @@ export interface PhaseDurationRecord {
     durationMs: number;
     taskCount: number;
     completedTaskCount: number;
+    wallClockMs?: number;
+    idleMs?: number;
+    lastActiveAt?: string;
+    _lastActiveEpoch?: number;
+    idleSegments?: Array<{
+        from: string;
+        to: string;
+        durationMs: number;
+    }>;
 }
 /**
  * Proposal change record for tracking modifications to proposal files
@@ -322,6 +353,20 @@ export interface ProgressData {
             review: number;
             archive: number;
         };
+        wallClockMs?: {
+            techDesign: number;
+            propose: number;
+            apply: number;
+            review: number;
+            archive: number;
+        };
+        idleMs?: {
+            techDesign: number;
+            propose: number;
+            apply: number;
+            review: number;
+            archive: number;
+        };
     };
     proposalChanges: ProposalChangeRecord[];
     corrections?: CorrectionRecord[];

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';
@@ -116,6 +116,10 @@ export async function recoverProgressJsonForWrite(filePath) {
                         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 } },
             };
@@ -163,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 = {};
@@ -420,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);
@@ -870,51 +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.15.16：同步刷新活跃段的 phaseDurations 记录，进行中也能从单条直接读出
-            // 实时 durationMs / lastUpdatedAt。endedAt 仍仅在 phase 切换时填。
-            const activeEntry = [...progress.phaseDurations]
-                .reverse()
-                .find(pd => pd.phase === phase && !pd.endedAt);
-            if (activeEntry) {
-                activeEntry.durationMs = elapsedMs;
-                activeEntry.lastUpdatedAt = getBeijingTime();
-            }
+    // 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 ===
@@ -1101,6 +1165,10 @@ function createNewProgress(changeId) {
                 durationMs: 0,
                 taskCount: 0,
                 completedTaskCount: 0,
+                wallClockMs: 0,
+                idleMs: 0,
+                lastActiveAt: getBeijingTime(),
+                _lastActiveEpoch: Date.now(),
             }],
         stats: {
             tokenUsageTotal: 0,
@@ -1167,17 +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;
-                    prevPhaseDuration.lastUpdatedAt = 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') {
@@ -1211,6 +1278,10 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
                     durationMs: 0,
                     taskCount: 0,
                     completedTaskCount: 0,
+                    wallClockMs: 0,
+                    idleMs: 0,
+                    lastActiveAt: timestamp,
+                    _lastActiveEpoch: Date.now(),
                 });
             }
             progress.phase = initialPhase;
@@ -1281,14 +1352,12 @@ 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;
-                entry.lastUpdatedAt = 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({
@@ -1298,6 +1367,10 @@ function seedInitialPhase(progress, initialPhase, timestamp) {
             durationMs: 0,
             taskCount: 0,
             completedTaskCount: 0,
+            wallClockMs: 0,
+            idleMs: 0,
+            lastActiveAt: timestamp,
+            _lastActiveEpoch: Date.now(),
         });
     }
 }

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/templates/slash-command-templates.js

@@ -432,6 +432,9 @@ const applySteps = `**步骤**
    - 阅读 \`changes/<id>/proposal.md\`、\`design.md\`（如果存在）和 \`tasks.md\` 以确认范围和验收标准。
 2. **Wave 并行执行（默认且唯一执行模式）**
    - **执行模型**：按 Wave 编号串行，Wave 内任务并行启动 subagent。
+   - **⚠️ 每个 Wave 启动前 MUST 重读核心机制（防长任务指令衰减）**：在为新 Wave 启动 subagent 前，编排 Agent **必须**在自己的输出里**逐字复述**以下两句话，作为执行前置自检（缺失即流程故障）：
+     1. "本 Wave 的每个任务 MUST 通过 Agent tool / spawn_agent 启动 subagent，禁止主线程串行手写代码或手写报告。"
+     2. "任务报告必须由 subagent 生成，且必须符合 .claude/agents/tdd-apply-agent.md 或 apply-agent.md 的模板章节。"
    - **并行度限制**：每个 Wave 内最多同时启动 3 个 subagent。超过 3 个任务时，按批次（batch）执行，每批最多 3 个并行 subagent，批次间串行等待。
    - **Subagent 调用 @skill 后的行为**（任务标注 \`@skill:<skill-name>\` 时）：
      1. 执行 @skill 标注的 Skill
@@ -512,6 +515,15 @@ const applySteps = `**步骤**
    - 同 Wave 所有任务（含阻塞任务）全部处理完成后 → 进入集成测试阶段
 
    **B. 集成测试阶段（MANDATORY，同 Wave 所有任务处理完成后）**：
+   B0. **任务报告 schema 校验（MANDATORY GATE，最先执行，不得跳过）**：
+      - 运行 \`zhuanspec validate-reports <change-id> --json\` 校验本 Wave 所有 \`reports/task-*.md\`
+      - 检查内容（基于 \`.claude/agents/tdd-apply-agent.md\` / \`apply-agent.md\` 模板）：
+        * 公共字段：\`## 状态报告\` / Status / Task ID / Report File / \`### Agent 选择决策\` / Agent 类型
+        * tddApplyAgent 报告必须有：TDD Phase / \`### 上下文就绪摘要\` / \`### 验收点映射表\` / \`#### Verify RED\` / \`#### Verify GREEN\` / \`#### Mock Gate\` / \`### 测试运行结果\` / \`### Self-Review 发现\` / \`### Issues/Concerns\`
+        * applyAgent 报告必须有：\`### 实施内容\` / \`### 修改文件\` / \`### Self-Review 发现\` / \`### Issues/Concerns\`
+        * 交叉对账：tasks.md 中带 \`@test-case:TC-XXX\` 的任务，报告必须为 tddApplyAgent，否则必须显式声明 "TDD 适用性: 不适合（降级原因：...）"
+      - 任意报告校验失败 → **该任务强制视为 BLOCKED**，按 B5 流程以 Execution Mode = RETRY 重新 spawn subagent 产出合规报告；禁止跳过本步直接进入 B1
+      - 校验失败的根因通常是：编排 Agent 在主线程手写代码 + 手写偷工报告，没有真的 spawn subagent。修复方式：通过 Agent tool / spawn_agent 重新下发任务
    B1. **编译检查**：运行项目编译命令，确保无编译错误
       - Java: \`mvn compile -q\` / \`gradle compileJava\`
       - TypeScript: \`tsc --noEmit\`
@@ -588,6 +600,7 @@ const applySteps = `**步骤**
    B6. **生成集成测试报告（MANDATORY，不得跳过）**：
       - 报告路径：\`changes/<change-id>/reports/wave-{N}-integration-report.md\`
       - 记录所有任务执行结果、编译检查结果、阻塞任务重试结果
+      - **MUST 记录 B0 报告 schema 校验结果**（通过/失败任务列表，失败时附 \`validate-reports --json\` 输出）
       - **MUST 包含 Concerns 追踪章节**，列出所有 DONE_WITH_CONCERNS 和 BLOCKED 任务及其疑虑
       - **MUST 包含 \`## 🔁 待重试任务清单\` 段**（即使为空也要写 \`— 无需重跑\`），与 B4.1 第五步、B5 重试结果汇总一致
       - 整体状态：所有检查通过且无未解决的阻塞任务 → PASS
@@ -713,6 +726,7 @@ const archiveReferences = `**参考**
   - **AI 手动**（archive 命令前）：调用 \`zhuanspec:knowledge\` skill 从会话记忆补充隐式约定、调试发现等。**必须在 \`zhuanspec archive\` 命令之前**调用，否则补充内容仅落本地、不会进入远端推送
 - 会话分析 (\`session-analytics\`)：记录本次会话的效率指标，用于改进工作流。`;
 const designGuardrails = `${baseGuardrails}\n- **独立设计阶段**：techDesign 命令用于在 proposal 之前生成技术设计请求文档，不依赖变更提案。设计文档可作为后续提案的输入。
+- **Skill 调用连续性（红线）**：在 techDesign 流程中调用任何辅助类 Skill（如 \`@skill:load-project-knowledge\`）后，**必须立即推进到下一编号步骤**，禁止把 Skill 的输出当作流程终态，禁止停顿等待用户输入“继续/下一步”等确认词。只有在显式标注的 AskUserQuestion 步骤（如开发范围确认、需求来源确认、外部依赖确认）才允许暂停等待用户。
 - **需求澄清优先**：在生成设计请求前，必须确认需求来源（大神页面、需求描述文本等）。
 - **开发范围前置确认（硬约束）**：在调用技术方案 Skill 前，**必须**先通过 AskUserQuestion 确认开发范围是“仅后端开发”还是“全栈开发”，根据答复选择对应 Skill（仅后端=\`generate-tech-spec-md-skill\`，全栈=\`generate-fullstack-tech-spec-skill\`），禁止默认或跳过此确认环节。
 - **Skill 可用性前置检查（硬约束）**：在实际调用技术方案 Skill 前，**必须**先校验目标 Skill 是否已安装且可用；**若不可用，立即中断流程**并提示用户到 Skill 市场安装对应 Skill，禁止以人工编写/其他 Skill 代替。
@@ -722,8 +736,13 @@ const designGuardrails = `${baseGuardrails}\n- **独立设计阶段**：techDesi
 - **禁止创建提案文件**：禁止创建 .tech-design、design.md、proposal.md、tasks.md、specs/ 等。
 - **Proposal 复用**：proposal 阶段通过 progress.json 的 phase 字段识别 techDesign 目录。`;
 const designSteps = `**步骤**
-0. **检查知识库并生成 change-id**：
+0. **检查知识库、加载项目知识并生成 change-id**：
    - 运行 \`rg "[需求关键词]" zhuanspec/knowledge/\` 搜索相关陷阱和最佳实践，避免重复踩坑。阅读 \`zhuanspec/knowledge/index.md\` 了解项目级知识摘要。
+   - **加载项目知识（必选）**：调用 \`@skill:load-project-knowledge\` 进行渐进式加载：
+     * 输入：domain（当前项目）、keywords（从需求描述提取的核心关键词）
+     * 获取：matched_services（涉及的服务列表）、search_priority（检索优先路径）、architecture_constraints（架构约束）
+     * 使用：后续技术方案设计需引用 matched_services 作为服务定位，方案设计需检查 architecture_constraints
+     * ⚠️ **连续性约束（红线）**：\`load-project-knowledge\` 完成并输出 matched_services 表后，**必须立即继续执行下面的“生成 change-id”子步骤以及步骤 1（Phase 初始化）**，禁止停顿等待用户输入“继续”。该 Skill 只是辅助加载，不是流程门禁。
    - **生成 change-id**（与 proposal 阶段命名规则一致）：
      * 从用户需求描述中提取核心动词和关键词
      * 格式：动词开头 + kebab-case 关词组合

package/dist/core/templates/tasks-template.js

@@ -191,18 +191,24 @@ Answer: <!-- user answer -->
 
 ### Wave 1（底层：DAO / 外部 Assemble）
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent 执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 1: Tasks with no dependencies, 层归属限定 dao/assemble/ddl/config -->
 
 - [ ] 1.1 <!-- Task description --> @layer:dao @skill:none <!-- 纯配置变更或手动操作 -->
 
 ### Wave 2（中间层：Domain / Application）
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent 执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 2: Tasks depending on Wave 1, 层归属限定 domain/application -->
 
 - [ ] 2.1 <!-- Task description --> @depends:1.1 @layer:domain @skill:none <!-- 无需特定 skill -->
 
 ### Wave 3（顶层：SCF / MQ / 定时任务 / 前端）
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent 执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 3: Tasks depending on Wave 2, 层归属限定 entry-scf/entry-mq-*/entry-job/fe -->
 
 - [ ] 3.1 <!-- Task description --> @depends:2.1 @layer:entry-scf @skill:none <!-- 无需特定 skill -->

package/dist/core/templates/tdd-tasks-template.js

@@ -153,6 +153,8 @@ Answer: <!-- user answer -->
 
 ### Wave 2
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent（优先 tddApplyAgent）执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 2: Red Phase - Write failing tests that define expected behavior -->
 <!-- 先写测试，测试应当初始失败 — 证明测试确实在验证有意义的行为 -->
 <!-- 每个测试任务必须使用类型A/B模板，明确测试文件路径、测试方法签名、断言内容 -->
@@ -162,6 +164,8 @@ Answer: <!-- user answer -->
 
 ### Wave 3
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent（优先 tddApplyAgent）执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 3: Green Phase - Write minimal code to make tests pass -->
 <!-- 编写最少代码使测试通过，每个任务必须使用类型A（新增）或类型B（修改）模板 -->
 
@@ -170,6 +174,8 @@ Answer: <!-- user answer -->
 
 ### Wave 4
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent（优先 tddApplyAgent）执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 4: Refactor Phase - Clean up code while keeping tests green -->
 <!-- 在保持测试通过的前提下重构，每个任务使用类型B模板标明修改位置 -->
 
@@ -178,6 +184,8 @@ Answer: <!-- user answer -->
 
 ### Wave 5
 
+> ⚠️ **MUST (subagent gate)**: 本 Wave 每个任务必须通过 Agent tool / spawn_agent 启动 subagent 执行；主线程直接施工产生的报告会被 B0 schema 校验（\`zhuanspec validate-reports <change-id>\`）拦截并触发 RETRY。
+
 <!-- Wave 5: Documentation - Document the implemented feature -->
 
 - [ ] 5.1 <!-- 更新 API 文档 --> @depends:4.2 @skill:none <!-- justification: documentation task -->

package/dist/core/validation/report-schema.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Apply 阶段任务报告 schema 校验。
+ *
+ * 背景：编排 Agent 在长任务尾部容易"指令衰减"，跳过 Agent tool / spawn_agent
+ * 的 subagent 调用，自己在主线程顺手把任务做掉再补一份偷工的报告。这种偷工
+ * 报告会缺失 tdd-apply-agent.md / apply-agent.md 模板里强制的章节
+ * （TDD Phase / Verify RED / Verify GREEN / Mock Gate / Skill 调用记录 ...）。
+ *
+ * 本模块对 `zhuanspec/changes/<id>/reports/task-*.md` 做轻量结构校验：
+ * - 必备公共字段：`## 状态报告` / Status / Task ID / Report File / Agent 选择决策 / Agent 类型
+ * - 当 Agent 类型 = `tddApplyAgent`：再校验 TDD Phase / 上下文就绪摘要 /
+ *   验收点映射表 / TDD 执行过程（Verify RED + Verify GREEN）/ 测试运行结果 /
+ *   Self-Review 发现 / Issues
+ * - 当 Agent 类型 = `applyAgent`：校验实施内容 / 修改文件 / Self-Review 发现 / Issues
+ *
+ * 与 tasks.md 交叉对账：若任务在 tasks.md 里带 `@test-case:TC-XXX`，则该任务的
+ * 报告原则上必须由 `tddApplyAgent` 产出（除非报告里显式声明降级原因，对应
+ * apply-agent.md 中的"降级使用 applyAgent"路径）。
+ */
+export type ReportAgentType = 'tddApplyAgent' | 'applyAgent' | 'unknown';
+export interface ReportIssue {
+    level: 'ERROR' | 'WARNING';
+    taskId: string;
+    message: string;
+}
+export interface SingleReportResult {
+    /** Task id parsed from filename, e.g. "1.1". */
+    taskId: string;
+    /** Absolute path to the report file. */
+    filePath: string;
+    /** Agent type declared inside report, or 'unknown' when absent. */
+    declaredAgentType: ReportAgentType;
+    /** Agent type expected from tasks.md (`@test-case` ⇒ tddApplyAgent). */
+    expectedAgentType: ReportAgentType;
+    /** Whether the report has a downgrade justification (i.e. claims "降级"/"不适合 TDD"). */
+    hasDowngradeJustification: boolean;
+    /** Section / field names that were required but not found. */
+    missing: string[];
+    /** Issues collected for this report. */
+    issues: ReportIssue[];
+    /** Whether the report passes schema validation. */
+    valid: boolean;
+}
+export interface ReportSchemaSummary {
+    changeId: string;
+    reportsDir: string;
+    /** Total reports inspected. */
+    totalReports: number;
+    /** Reports passing all schema checks. */
+    passedReports: number;
+    /** Reports failing schema checks. */
+    failedReports: number;
+    /** Tasks in tasks.md that have no report file at all. */
+    missingReports: string[];
+    /** Per-report results. */
+    reports: SingleReportResult[];
+    /** Overall validity (no ERROR-level issues + no missing reports). */
+    valid: boolean;
+}
+/**
+ * Inspect a single report file. Pure string-level checks — no side effects.
+ *
+ * @param taskId  The task id (derived from filename).
+ * @param content The raw markdown content of the report file.
+ * @param expected The agent type expected from tasks.md (default 'unknown').
+ */
+export declare function checkReportContent(taskId: string, filePath: string, content: string, expected: ReportAgentType): SingleReportResult;
+/**
+ * Validate all task reports under `<changeDir>/reports/`.
+ * Cross-checks against `<changeDir>/tasks.md` to detect missing reports and
+ * agent-type mismatches.
+ */
+export declare function validateTaskReports(changeDir: string): Promise<ReportSchemaSummary>;
+//# sourceMappingURL=report-schema.d.ts.map

package/dist/core/validation/report-schema.js

@@ -0,0 +1,254 @@
+/**
+ * Apply 阶段任务报告 schema 校验。
+ *
+ * 背景：编排 Agent 在长任务尾部容易"指令衰减"，跳过 Agent tool / spawn_agent
+ * 的 subagent 调用，自己在主线程顺手把任务做掉再补一份偷工的报告。这种偷工
+ * 报告会缺失 tdd-apply-agent.md / apply-agent.md 模板里强制的章节
+ * （TDD Phase / Verify RED / Verify GREEN / Mock Gate / Skill 调用记录 ...）。
+ *
+ * 本模块对 `zhuanspec/changes/<id>/reports/task-*.md` 做轻量结构校验：
+ * - 必备公共字段：`## 状态报告` / Status / Task ID / Report File / Agent 选择决策 / Agent 类型
+ * - 当 Agent 类型 = `tddApplyAgent`：再校验 TDD Phase / 上下文就绪摘要 /
+ *   验收点映射表 / TDD 执行过程（Verify RED + Verify GREEN）/ 测试运行结果 /
+ *   Self-Review 发现 / Issues
+ * - 当 Agent 类型 = `applyAgent`：校验实施内容 / 修改文件 / Self-Review 发现 / Issues
+ *
+ * 与 tasks.md 交叉对账：若任务在 tasks.md 里带 `@test-case:TC-XXX`，则该任务的
+ * 报告原则上必须由 `tddApplyAgent` 产出（除非报告里显式声明降级原因，对应
+ * apply-agent.md 中的"降级使用 applyAgent"路径）。
+ */
+import path from 'path';
+import { promises as fs } from 'fs';
+/** Common required fields for ANY task report (applyAgent or tddApplyAgent). */
+const COMMON_REQUIRED = [
+    '## 状态报告',
+    'Status',
+    'Task ID',
+    'Report File',
+    '### Agent 选择决策',
+    'Agent 类型',
+];
+/** Additional required sections when declaredAgentType === 'tddApplyAgent'. */
+const TDD_REQUIRED = [
+    'Wave',
+    'Execution Mode',
+    'TDD Phase',
+    '### 上下文就绪摘要',
+    '### Skill 调用记录',
+    '### 验收点映射表',
+    '### TDD 执行过程',
+    '#### Verify RED',
+    '#### Verify GREEN',
+    '#### Mock Gate',
+    '### 测试内容',
+    '### 测试运行结果',
+    '### Self-Review 发现',
+    '### Issues/Concerns',
+];
+/** Additional required sections when declaredAgentType === 'applyAgent'. */
+const APPLY_REQUIRED = [
+    '### 实施内容',
+    '### 修改文件',
+    '### Self-Review 发现',
+    '### Issues/Concerns',
+];
+const TASK_REPORT_FILE_RE = /^task-(\d+\.\d+(?:[a-z])?)-report\.md$/i;
+const AGENT_TYPE_LINE_RE = /\*\*Agent\s+类型\*\*\s*[:：]\s*([A-Za-z]+)/;
+const TASK_LINE_RE = /^-\s+\[[ xX]\]\s+(\d+\.\d+)\s+/;
+/**
+ * Inspect a single report file. Pure string-level checks — no side effects.
+ *
+ * @param taskId  The task id (derived from filename).
+ * @param content The raw markdown content of the report file.
+ * @param expected The agent type expected from tasks.md (default 'unknown').
+ */
+export function checkReportContent(taskId, filePath, content, expected) {
+    const declaredAgentType = detectAgentType(content);
+    const hasDowngradeJustification = /降级|不适合\s*TDD|TDD\s*适用性\s*[:：]\s*不适合/.test(content);
+    const missing = [];
+    const issues = [];
+    // 1) Common required fields/sections.
+    for (const token of COMMON_REQUIRED) {
+        if (!content.includes(token))
+            missing.push(token);
+    }
+    // 2) Type-specific required sections.
+    const typeRequired = declaredAgentType === 'tddApplyAgent'
+        ? TDD_REQUIRED
+        : declaredAgentType === 'applyAgent'
+            ? APPLY_REQUIRED
+            : [];
+    for (const token of typeRequired) {
+        if (!content.includes(token))
+            missing.push(token);
+    }
+    // 3) Aggregate ERROR-level issues from missing sections.
+    if (missing.length > 0) {
+        issues.push({
+            level: 'ERROR',
+            taskId,
+            message: `报告缺失必需章节/字段：${missing.join(', ')}`,
+        });
+    }
+    // 4) Cross-check against expected agent type.
+    if (expected === 'tddApplyAgent' &&
+        declaredAgentType === 'applyAgent' &&
+        !hasDowngradeJustification) {
+        issues.push({
+            level: 'ERROR',
+            taskId,
+            message: 'tasks.md 标注 @test-case 应使用 tddApplyAgent；报告声明 applyAgent 但未给出降级理由（"TDD 适用性: 不适合(...)"）',
+        });
+    }
+    if (declaredAgentType === 'unknown') {
+        issues.push({
+            level: 'ERROR',
+            taskId,
+            message: '报告未声明 Agent 类型（缺失 "Agent 类型: applyAgent | tddApplyAgent"）',
+        });
+    }
+    // 5) Heuristic: tddApplyAgent must show real test command output evidence.
+    if (declaredAgentType === 'tddApplyAgent') {
+        const hasTestEvidence = /mvn\s+test|npm\s+(?:test|run\s+test)|pnpm\s+test|yarn\s+test|gradle\s+test|vitest|jest/i.test(content);
+        if (!hasTestEvidence) {
+            issues.push({
+                level: 'ERROR',
+                taskId,
+                message: 'tddApplyAgent 报告缺少测试运行证据（未发现 mvn test / npm test / vitest / jest 等命令痕迹）',
+            });
+        }
+    }
+    const valid = issues.every((issue) => issue.level !== 'ERROR');
+    return {
+        taskId,
+        filePath,
+        declaredAgentType,
+        expectedAgentType: expected,
+        hasDowngradeJustification,
+        missing,
+        issues,
+        valid,
+    };
+}
+/**
+ * Validate all task reports under `<changeDir>/reports/`.
+ * Cross-checks against `<changeDir>/tasks.md` to detect missing reports and
+ * agent-type mismatches.
+ */
+export async function validateTaskReports(changeDir) {
+    const changeId = path.basename(changeDir);
+    const reportsDir = path.join(changeDir, 'reports');
+    // Read tasks.md to figure out the expected task list and agent type per task.
+    const expectedByTaskId = await parseExpectedAgentTypes(path.join(changeDir, 'tasks.md'));
+    let entries = [];
+    try {
+        entries = await fs.readdir(reportsDir);
+    }
+    catch {
+        // No reports directory at all — report every expected task as missing.
+        return {
+            changeId,
+            reportsDir,
+            totalReports: 0,
+            passedReports: 0,
+            failedReports: 0,
+            missingReports: Array.from(expectedByTaskId.keys()),
+            reports: [],
+            valid: expectedByTaskId.size === 0,
+        };
+    }
+    const reportFiles = entries
+        .filter((e) => TASK_REPORT_FILE_RE.test(e))
+        .sort();
+    const seenTaskIds = new Set();
+    const results = [];
+    for (const file of reportFiles) {
+        const match = file.match(TASK_REPORT_FILE_RE);
+        if (!match)
+            continue;
+        const taskId = match[1];
+        seenTaskIds.add(taskId);
+        const filePath = path.join(reportsDir, file);
+        let content;
+        try {
+            content = await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            results.push({
+                taskId,
+                filePath,
+                declaredAgentType: 'unknown',
+                expectedAgentType: expectedByTaskId.get(taskId) ?? 'unknown',
+                hasDowngradeJustification: false,
+                missing: ['<file unreadable>'],
+                issues: [
+                    {
+                        level: 'ERROR',
+                        taskId,
+                        message: '报告文件无法读取',
+                    },
+                ],
+                valid: false,
+            });
+            continue;
+        }
+        const expected = expectedByTaskId.get(taskId) ?? 'unknown';
+        results.push(checkReportContent(taskId, filePath, content, expected));
+    }
+    // Tasks declared in tasks.md but never produced a report.
+    const missingReports = [];
+    for (const taskId of expectedByTaskId.keys()) {
+        if (!seenTaskIds.has(taskId))
+            missingReports.push(taskId);
+    }
+    const passedReports = results.filter((r) => r.valid).length;
+    const failedReports = results.length - passedReports;
+    return {
+        changeId,
+        reportsDir,
+        totalReports: results.length,
+        passedReports,
+        failedReports,
+        missingReports,
+        reports: results,
+        valid: failedReports === 0 && missingReports.length === 0,
+    };
+}
+/** Detect declared agent type from a report's body. */
+function detectAgentType(content) {
+    const m = content.match(AGENT_TYPE_LINE_RE);
+    if (!m)
+        return 'unknown';
+    const v = m[1].trim();
+    if (v === 'tddApplyAgent')
+        return 'tddApplyAgent';
+    if (v === 'applyAgent')
+        return 'applyAgent';
+    return 'unknown';
+}
+/**
+ * Parse `tasks.md` to determine the expected agent type for each task.
+ * Tasks tagged with `@test-case:TC-XXX` are expected to use `tddApplyAgent`;
+ * everything else defaults to `applyAgent`.
+ */
+async function parseExpectedAgentTypes(tasksFile) {
+    const result = new Map();
+    let content;
+    try {
+        content = await fs.readFile(tasksFile, 'utf-8');
+    }
+    catch {
+        return result;
+    }
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+        const m = line.match(TASK_LINE_RE);
+        if (!m)
+            continue;
+        const taskId = m[1];
+        const hasTestCase = /@test-case\s*:/.test(line);
+        result.set(taskId, hasTestCase ? 'tddApplyAgent' : 'applyAgent');
+    }
+    return result;
+}
+//# sourceMappingURL=report-schema.js.map

package/dist/utils/phase-utils.d.ts

@@ -9,6 +9,19 @@
  */
 export type Phase = 'idle' | 'techDesign' | 'propose' | 'apply' | 'review' | 'archive';
 export declare const PHASE_ORDER: Phase[];
+/**
+ * v2.16+：阶段“活跃耗时”计算的空闲阈值。
+ *
+ * 设计背景：原本 progress.json 中的 phaseDurations[].durationMs / stats.durationMs 都是
+ * 墙钟差，中断/午休/过夜/AskUserQuestion 长时间挂起都会被当成阶段耗时。
+ * 从 v2.16 起，相邻两次 record-progress 心跳间隔 < PHASE_IDLE_THRESHOLD_MS 才计入
+ * 活跃耗时（durationMs）；超过阈值的 gap 被归类为空闲，计入 idleMs / idleSegments，
+ * 不计入 durationMs。
+ *
+ * 30 分钟阈值是取舍结果：避免误伤正常的本地阅读 / 思考 / 短暂离开，只剔除
+ * 明显的长时间中断、过夜、确认久未响应等场景。
+ */
+export declare const PHASE_IDLE_THRESHOLD_MS: number;
 export declare const PHASE_MARKERS: Partial<Record<Phase, string>>;
 /**
  * Set phase in progress.json with full data preservation

package/dist/utils/phase-utils.js

@@ -9,8 +9,21 @@
  */
 import path from 'path';
 import { FileSystemUtils } from './file-system.js';
-import { recoverProgressJsonForWrite, getBeijingTime, atomicWriteJson, } from '../core/hooks/record-progress.js';
+import { recoverProgressJsonForWrite, getBeijingTime, atomicWriteJson, tickActivePhaseDuration, } from '../core/hooks/record-progress.js';
 export const PHASE_ORDER = ['idle', 'techDesign', 'propose', 'apply', 'review', 'archive'];
+/**
+ * v2.16+：阶段“活跃耗时”计算的空闲阈值。
+ *
+ * 设计背景：原本 progress.json 中的 phaseDurations[].durationMs / stats.durationMs 都是
+ * 墙钟差，中断/午休/过夜/AskUserQuestion 长时间挂起都会被当成阶段耗时。
+ * 从 v2.16 起，相邻两次 record-progress 心跳间隔 < PHASE_IDLE_THRESHOLD_MS 才计入
+ * 活跃耗时（durationMs）；超过阈值的 gap 被归类为空闲，计入 idleMs / idleSegments，
+ * 不计入 durationMs。
+ *
+ * 30 分钟阈值是取舍结果：避免误伤正常的本地阅读 / 思考 / 短暂离开，只剔除
+ * 明显的长时间中断、过夜、确认久未响应等场景。
+ */
+export const PHASE_IDLE_THRESHOLD_MS = 30 * 60 * 1000;
 export const PHASE_MARKERS = {
     techDesign: '.tech-design',
     apply: '.approved',
@@ -83,6 +96,10 @@ export async function setPhase(changeDir, phase) {
                         durationMs: 0,
                         taskCount: 0,
                         completedTaskCount: 0,
+                        wallClockMs: 0,
+                        idleMs: 0,
+                        lastActiveAt: timestamp,
+                        _lastActiveEpoch: Date.now(),
                     }],
                 proposalChanges: [],
                 stats: { tokenUsageTotal: 0, contextLoad: 0, durationMs: { techDesign: 0, propose: 0, apply: 0, review: 0, archive: 0 } },
@@ -119,6 +136,10 @@ export async function setPhase(changeDir, phase) {
                     durationMs: 0,
                     taskCount: 0,
                     completedTaskCount: 0,
+                    wallClockMs: 0,
+                    idleMs: 0,
+                    lastActiveAt: timestamp,
+                    _lastActiveEpoch: Date.now(),
                 }],
             proposalChanges: [],
             stats: { tokenUsageTotal: 0, contextLoad: 0, durationMs: { techDesign: 0, propose: 0, apply: 0, review: 0, archive: 0 } },
@@ -135,6 +156,10 @@ export async function setPhase(changeDir, phase) {
             durationMs: 0,
             taskCount: 0,
             completedTaskCount: 0,
+            wallClockMs: 0,
+            idleMs: 0,
+            lastActiveAt: timestamp,
+            _lastActiveEpoch: Date.now(),
         });
     }
     if (previousPhase !== phase) {
@@ -144,14 +169,13 @@ export async function setPhase(changeDir, phase) {
             timestamp,
             triggeredBy: 'setPhase',
         });
-        // Update phaseDurations: fill endedAt for previous phase
+        // Update phaseDurations: close previous phase 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;
-            prevPhaseDuration.lastUpdatedAt = timestamp;
-            const startTime = new Date(prevPhaseDuration.startedAt).getTime();
-            const endTime = new Date(timestamp).getTime();
-            prevPhaseDuration.durationMs = endTime > startTime ? endTime - startTime : 0;
         }
         // Add new phase duration record
         progress.phaseDurations.push({
@@ -161,6 +185,10 @@ export async function setPhase(changeDir, phase) {
             durationMs: 0,
             taskCount: 0,
             completedTaskCount: 0,
+            wallClockMs: 0,
+            idleMs: 0,
+            lastActiveAt: timestamp,
+            _lastActiveEpoch: Date.now(),
         });
     }
     progress.phase = phase;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.16.2",
+  "version": "2.16.3",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -74,6 +74,7 @@
   "dependencies": {
     "@inquirer/core": "^10.2.2",
     "@inquirer/prompts": "^7.8.0",
+    "@rollup/rollup-darwin-x64": "^4.60.4",
     "chalk": "^5.5.0",
     "commander": "^14.0.0",
     "fast-glob": "^3.3.3",