@zhuan-ai/zhuanspec 2.16.0 → 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';
@@ -329,6 +330,23 @@ progressCmd
         process.exit(1);
     }
 });
+// Progress list-corrections subcommand (review-step0 踩坑沉淀决策清单)
+progressCmd
+    .command('list-corrections <change-id>')
+    .description('Render pending correction candidates (filter trivial acks + dedup) for review-step0 decision making')
+    .option('--out <path>', 'Output file path (default: zhuanspec/changes/<id>/review/pending-corrections.md)')
+    .option('--json', 'Print result as JSON to stdout instead of writing markdown file')
+    .action(async (changeId, options) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.listCorrections(changeId, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
 // Progress mark-baseline subcommand (Task 0 手动路径)
 progressCmd
     .command('mark-baseline <change-id> <phase>')
@@ -507,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.d.ts

@@ -68,6 +68,18 @@ export declare class ProgressCommand {
     showCorrection(changeId: string, options?: {
         tail?: number;
     }): Promise<void>;
+    /**
+     * List pending correction candidates with trivial-ack filtering and dedup.
+     * Usage: zhuanspec progress list-corrections <change-id> [--out <path>] [--json]
+     *
+     * 默认会把 markdown 清单写到 `zhuanspec/changes/<id>/review/pending-corrections.md`，
+     * 供 review 阶段「踩坑沉淀」步骤的 askUserQuestion 三选项决策使用。
+     * `--json` 模式只走 stdout JSON，不写文件，便于 skill / 测试程序消费。
+     */
+    listCorrections(changeId: string, options?: {
+        out?: string;
+        json?: boolean;
+    }): Promise<void>;
     /**
      * Mark phase baseline manually.
      * Usage: zhuanspec progress mark-baseline <change-id> <phase> [--force]

package/dist/commands/progress.js

@@ -13,6 +13,7 @@ import { PHASE_ORDER } from '../utils/phase-utils.js';
 import { initializeProgress, atomicWriteJson, getBeijingTime } from '../core/hooks/record-progress.js';
 import { recomputeAccuracyRate, persistAccuracyJson, getOrCreatePhaseBucket, applyPhaseOverride, confirmPhaseAccuracy, appendAccuracyDebugLog, } from '../core/metrics/code-accuracy.js';
 import { resolveZhuanSpecRoot } from '../utils/resolve-root.js';
+import { selectCorrectionCandidates, renderPendingCorrectionsMarkdown, } from '../core/corrections/select-candidates.js';
 export class ProgressCommand {
     /**
      * Recover damaged progress.json using three-tier fallback strategy
@@ -294,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;
@@ -318,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('');
@@ -468,7 +481,10 @@ export class ProgressCommand {
                     promptIndex: markerMeta.phaseInputIndex,
                     promptSnippet: markerMeta.promptSnippet,
                 };
-                progress.lastUpdatedAt = now.toISOString();
+                // v2.15.16：与 phaseDurations.startedAt / lastUpdatedAt 等字段对齐，统一使用北京时间
+                // naive 字符串。correctionContext.resolvedAt / expiresAt 仍保留 ISOString —— 它们
+                // 走 30min TTL（new Date(expiresAt) < Date.now()）比较，ISO 解析更稳健。
+                progress.lastUpdatedAt = getBeijingTime();
                 await fs.writeFile(progressPath, JSON.stringify(progress, null, 2), 'utf-8');
             }
         }
@@ -483,7 +499,8 @@ export class ProgressCommand {
                     const raw = await FileSystemUtils.readFile(progressPath);
                     const progress = JSON.parse(raw);
                     progress.askedPitfallSaved = true;
-                    progress.lastUpdatedAt = new Date().toISOString();
+                    // v2.15.16：统一北京时间格式
+                    progress.lastUpdatedAt = getBeijingTime();
                     await fs.writeFile(progressPath, JSON.stringify(progress, null, 2), 'utf-8');
                 }
                 catch {
@@ -575,6 +592,42 @@ export class ProgressCommand {
         }
         console.log();
     }
+    /**
+     * List pending correction candidates with trivial-ack filtering and dedup.
+     * Usage: zhuanspec progress list-corrections <change-id> [--out <path>] [--json]
+     *
+     * 默认会把 markdown 清单写到 `zhuanspec/changes/<id>/review/pending-corrections.md`，
+     * 供 review 阶段「踩坑沉淀」步骤的 askUserQuestion 三选项决策使用。
+     * `--json` 模式只走 stdout JSON，不写文件，便于 skill / 测试程序消费。
+     */
+    async listCorrections(changeId, options) {
+        const cwd = resolveZhuanSpecRoot();
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        const result = await selectCorrectionCandidates(cwd, changeId);
+        if (options?.json) {
+            // stdout JSON 模式：用于程序化消费（不写文件）
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const markdown = renderPendingCorrectionsMarkdown(result);
+        const outPath = options?.out
+            ? (path.isAbsolute(options.out) ? options.out : path.join(cwd, options.out))
+            : path.join(changeDir, 'review', 'pending-corrections.md');
+        await fs.mkdir(path.dirname(outPath), { recursive: true });
+        await fs.writeFile(outPath, markdown, 'utf-8');
+        const rel = path.relative(cwd, outPath) || outPath;
+        console.log(`\n✓ Pending corrections written to: ${rel}`);
+        console.log(`  - 数据源: ${result.level === 1 ? 'Level 1 (correctionSignal)' : result.level === 2 ? 'Level 2 (summary 关键词)' : '无'}`);
+        console.log(`  - 原始条目: ${result.totalRaw}`);
+        console.log(`  - 有效候选: ${result.candidates.length}`);
+        console.log(`  - 已过滤: ${result.dropped.length}`);
+        if (result.notice)
+            console.log(`  - 提示: ${result.notice}`);
+        console.log('');
+    }
     /**
      * Mark phase baseline manually.
      * Usage: zhuanspec progress mark-baseline <change-id> <phase> [--force]

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/corrections/select-candidates.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pending corrections candidate selection.
+ *
+ * 责任：把 `zhuanspec/changes/<id>/metrics/user_inputs.json` 里的纠偏 prompt 加工成
+ * "可读、去毛刺、去重、带建议分类" 的候选清单，给 review 阶段的踩坑沉淀决策使用。
+ *
+ * 不写文件、不改 progress.json，只做"读 + 计算 + 返回结构"。
+ */
+export type CandidateCategory = 'troubleshooting' | 'best-practices' | 'implicit-conventions';
+export type CandidateSourceLevel = 1 | 2;
+export interface CorrectionCandidate {
+    /** 1-based 序号，对应"用户回复编号清单"的编号 */
+    index: number;
+    /** 关联的 user_inputs.json.inputId */
+    inputId?: string;
+    timestamp?: string;
+    phase?: string;
+    /** 优先 fullPrompt，没有就 summary，再没有就空字符串 */
+    text: string;
+    /** 截断展示用的预览（≤ 200 字） */
+    preview: string;
+    /** 命中的纠偏关键词（取 USER_CORRECTION_KEYWORDS / REQUIREMENT_CHANGE_KEYWORDS） */
+    matchedKeywords: string[];
+    isRequirementChange: boolean;
+    /** 启发式建议分类（用户/skill 仍可改） */
+    suggestedCategory: CandidateCategory;
+    /** 拟用文件名（不含目录前缀） */
+    suggestedFilename: string;
+}
+export interface DroppedCandidate {
+    /** drop 后保留的原始序号（按出现顺序，1-based）——用于在 markdown 里展示 */
+    rawIndex: number;
+    inputId?: string;
+    timestamp?: string;
+    reason: 'empty' | 'trivial-acknowledgement' | 'too-short-no-keyword' | 'duplicate-of' | 'subset-of';
+    /** 当 reason 为 duplicate-of / subset-of 时，指向被引用的有效候选编号 */
+    refIndex?: number;
+    preview: string;
+}
+export interface CandidateSelectionResult {
+    changeId: string;
+    /** 数据源层级（1: user_inputs 带 correctionSignal；2: 关键词推断） */
+    level: CandidateSourceLevel | null;
+    totalRaw: number;
+    candidates: CorrectionCandidate[];
+    dropped: DroppedCandidate[];
+    /** 数据完整性提示——读不到 user_inputs.json 时给空候选 + 错误说明 */
+    notice?: string;
+}
+/**
+ * 从 change 目录抽取并加工纠偏候选。
+ */
+export declare function selectCorrectionCandidates(cwd: string, changeId: string): Promise<CandidateSelectionResult>;
+/**
+ * 把候选结果渲染成 markdown，用于落到 review/pending-corrections.md。
+ */
+export declare function renderPendingCorrectionsMarkdown(result: CandidateSelectionResult): string;
+//# sourceMappingURL=select-candidates.d.ts.map