@zhuan-ai/zhuanspec 2.2.5 → 2.5.0

package/bin/zhuanspec-hook.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/cli/hooks.js';

package/dist/cli/hooks.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * ZhuanSpec Hooks CLI Entry Point
+ *
+ * This CLI provides hook commands for Claude Code integration:
+ * - init: SessionStart hook - Initialize ZhuanSpec environment
+ * - deviation-check: PreToolUse hook - Check for proposal deviations
+ * - record-progress: PostToolUse hook - Record task progress
+ * - collect-knowledge: PostToolUse hook - Collect knowledge from interactions
+ * - summarize: Stop hook - Summarize session progress
+ * - review-*: Review phase hooks - Check skill outputs and control fix loops
+ */
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/cli/hooks.js

@@ -0,0 +1,465 @@
+#!/usr/bin/env node
+/**
+ * ZhuanSpec Hooks CLI Entry Point
+ *
+ * This CLI provides hook commands for Claude Code integration:
+ * - init: SessionStart hook - Initialize ZhuanSpec environment
+ * - deviation-check: PreToolUse hook - Check for proposal deviations
+ * - record-progress: PostToolUse hook - Record task progress
+ * - collect-knowledge: PostToolUse hook - Collect knowledge from interactions
+ * - summarize: Stop hook - Summarize session progress
+ * - review-*: Review phase hooks - Check skill outputs and control fix loops
+ */
+import { Command } from 'commander';
+import { initHook } from '../core/hooks/init.js';
+import { deviationCheckHook } from '../core/hooks/deviation-check.js';
+import { recordProgressHook, initializeProgress } from '../core/hooks/record-progress.js';
+import { collectKnowledgeHook } from '../core/hooks/collect-knowledge.js';
+import { summarizeHook } from '../core/hooks/summarize.js';
+import { preArchiveHook } from '../core/hooks/pre-archive.js';
+import { postArchiveHook } from '../core/hooks/post-archive.js';
+import { preApplyHook, checkPreApplyConditions } from '../core/hooks/pre-apply.js';
+import { postApplyHook, executePostApply } from '../core/hooks/post-apply.js';
+import { codeReviewResultCheck, unitTestResultCheck, specConsistencyResultCheck, generateReviewReport, } from '../core/hooks/review-hooks.js';
+import path from 'path';
+import { FileSystemUtils } from '../utils/file-system.js';
+const program = new Command();
+program
+    .name('zhuanspec-hook')
+    .description('ZhuanSpec hooks for Claude Code integration')
+    .version('1.0.0');
+// SessionStart hook
+program
+    .command('init')
+    .description('SessionStart hook - Initialize ZhuanSpec environment')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .action(async (options) => {
+    await initHook(options);
+});
+// PreToolUse hook
+program
+    .command('deviation-check')
+    .description('PreToolUse hook - Check for proposal deviations before Write/Edit')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--file <path>', 'File being modified')
+    .option('--tool <name>', 'Tool being used (Write/Edit)')
+    .option('--trigger <type>', 'Trigger type: pre-tool|post-prompt|resume')
+    .option('--prompt <text>', 'Prompt content for post-prompt checks')
+    .action(async (options) => {
+    await deviationCheckHook(options);
+});
+// PostToolUse hook - record progress
+program
+    .command('record-progress')
+    .description('PostToolUse hook - Record task progress after Write/Edit')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--file <path>', 'File that was modified')
+    .option('--tool <name>', 'Tool that was used (Write/Edit)')
+    .option('--success <boolean>', 'Whether the operation succeeded')
+    .action(async (options) => {
+    await recordProgressHook(options);
+});
+// Initialize progress - create progress.json at Propose phase start
+program
+    .command('init-progress')
+    .description('Initialize progress.json for a change at Propose phase start')
+    .option('--change <id>', 'Change ID')
+    .action(async (options) => {
+    if (!options.change) {
+        console.error('Error: --change <id> is required');
+        process.exit(1);
+    }
+    await initializeProgress(options.change);
+    console.log(`✓ Progress initialized for change: ${options.change}`);
+});
+// PostToolUse hook - collect knowledge
+program
+    .command('collect-knowledge')
+    .description('PostToolUse hook - Collect knowledge from interactions')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--file <path>', 'File that was modified')
+    .option('--content <string>', 'Content that was written')
+    .action(async (options) => {
+    await collectKnowledgeHook(options);
+});
+// Stop hook
+program
+    .command('summarize')
+    .description('Stop hook - Summarize session progress')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .action(async (options) => {
+    await summarizeHook(options);
+});
+program
+    .command('pre-archive')
+    .description('Pre-archive quality gate')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--change <id>', 'Change ID to validate before archive')
+    .action(async (options) => {
+    await preArchiveHook(options);
+});
+program
+    .command('post-archive')
+    .description('Post-archive knowledge update')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--archived <id>', 'Archived change ID')
+    .action(async (options) => {
+    await postArchiveHook(options);
+});
+// Pre-Apply hook - quality gate before entering Apply phase
+program
+    .command('pre-apply')
+    .description('Pre-Apply quality gate - validate change readiness before Apply phase')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--change <id>', 'Change ID to validate')
+    .action(async (options) => {
+    await preApplyHook(options);
+});
+// Post-Apply hook - deviation detection and auto-trigger review
+program
+    .command('post-apply')
+    .description('Post-Apply hook - detect deviations and trigger automatic review')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--change <id>', 'Change ID that was applied')
+    .action(async (options) => {
+    await postApplyHook(options);
+});
+// Phase Transition Check - Unified phase transition quality gate
+program
+    .command('phase-transition-check')
+    .description('Check phase transition conditions before moving to next phase')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--from <phase>', 'Current phase: propose|apply|review')
+    .option('--to <phase>', 'Target phase: apply|review|archive')
+    .option('--change <id>', 'Change ID being transitioned')
+    .action(async (options) => {
+    const result = await runPhaseTransitionCheck(options);
+    if (options.json) {
+        console.log(JSON.stringify(result));
+    }
+    else {
+        console.log(result.systemMessage || '');
+        if (!result.continue) {
+            process.exit(1);
+        }
+    }
+});
+// ============================================================
+// Review Phase Hooks - Check skill outputs and control fix loops
+// ============================================================
+// Code Review Result Check - Hook after code-review-expert skill
+program
+    .command('review-code-check')
+    .description('Check code-review-expert skill output and decide fix loop')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--change <id>', 'Change ID being reviewed')
+    .option('--output <json>', 'Skill output JSON (passed via stdin or option)')
+    .action(async (options) => {
+    const result = await codeReviewResultCheck(options.change || '', options.output ? JSON.parse(options.output) : undefined);
+    if (options.json) {
+        console.log(JSON.stringify(result));
+    }
+    else {
+        console.log(`Code Review: ${result.pass ? '✅ PASS' : '❌ FAIL'}`);
+        if (result.fixPrompt) {
+            console.log(result.fixPrompt);
+        }
+        if (!result.pass && result.nextAction === 'stop') {
+            process.exit(1);
+        }
+    }
+});
+// Unit Test Result Check - Hook after generate-mockito-unit-test-skill
+program
+    .command('review-unit-test-check')
+    .description('Check unit test skill output and decide fix loop')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--change <id>', 'Change ID being reviewed')
+    .option('--output <json>', 'Skill output JSON')
+    .action(async (options) => {
+    const result = await unitTestResultCheck(options.change || '', options.output ? JSON.parse(options.output) : undefined);
+    if (options.json) {
+        console.log(JSON.stringify(result));
+    }
+    else {
+        console.log(`Unit Test: ${result.pass ? '✅ PASS' : '❌ FAIL'}`);
+        console.log(`Coverage: ${result.metrics.coverage || 0}%`);
+        if (result.fixPrompt) {
+            console.log(result.fixPrompt);
+        }
+        if (!result.pass && result.nextAction === 'stop') {
+            process.exit(1);
+        }
+    }
+});
+// Spec-Code Consistency Check - Hook after spec-code-consistency check
+program
+    .command('review-spec-check')
+    .description('Check spec-code consistency output and decide fix loop')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--change <id>', 'Change ID being reviewed')
+    .option('--output <json>', 'Skill output JSON')
+    .action(async (options) => {
+    const result = await specConsistencyResultCheck(options.change || '', options.output ? JSON.parse(options.output) : undefined);
+    if (options.json) {
+        console.log(JSON.stringify(result));
+    }
+    else {
+        console.log(`Spec-Code Consistency: ${result.pass ? '✅ PASS' : '❌ FAIL'}`);
+        console.log(`Consistency Rate: ${result.metrics.consistencyRate || 0}%`);
+        if (result.fixPrompt) {
+            console.log(result.fixPrompt);
+        }
+        if (!result.pass && result.nextAction === 'stop') {
+            process.exit(1);
+        }
+    }
+});
+// Generate Review Report - Combine all three check results
+program
+    .command('review-report')
+    .description('Generate review report from all three check results')
+    .option('--json', 'Output as JSON for Claude Code consumption')
+    .option('--change <id>', 'Change ID being reviewed')
+    .action(async (options) => {
+    const changeId = options.change || '';
+    // Run all three checks
+    const codeReviewResult = await codeReviewResultCheck(changeId);
+    const unitTestResult = await unitTestResultCheck(changeId);
+    const specConsistencyResult = await specConsistencyResultCheck(changeId);
+    // Generate report
+    const report = await generateReviewReport(changeId, {
+        codeReview: codeReviewResult,
+        unitTest: unitTestResult,
+        specConsistency: specConsistencyResult,
+    });
+    if (options.json) {
+        console.log(JSON.stringify({
+            changeId,
+            overallPass: codeReviewResult.pass && unitTestResult.pass && specConsistencyResult.pass,
+            codeReview: codeReviewResult,
+            unitTest: unitTestResult,
+            specConsistency: specConsistencyResult,
+            reportPath: `zhuanspec/changes/${changeId}/review-report.md`,
+        }));
+    }
+    else {
+        console.log(report);
+        const overallPass = codeReviewResult.pass && unitTestResult.pass && specConsistencyResult.pass;
+        if (!overallPass) {
+            console.log('\n❌ Review NOT passed. Please fix issues before archiving.');
+            process.exit(1);
+        }
+        else {
+            console.log('\n✅ Review passed. Ready for Phase 4 (Archive).');
+        }
+    }
+});
+// Diagnostic command - inspect hook registration and trigger map
+program
+    .command('status')
+    .description('Show hook registration status and trigger mapping')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    const summary = await collectHookStatus();
+    if (options.json) {
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+    }
+    console.log(`settings: ${summary.settingsPath}`);
+    console.log(`settings exists: ${summary.settingsExists ? 'yes' : 'no'}`);
+    console.log('\n直接注册（Claude 生命周期 hooks）:');
+    if (summary.registeredLifecycleHooks.length === 0) {
+        console.log('- 无');
+    }
+    else {
+        for (const item of summary.registeredLifecycleHooks) {
+            console.log(`- ${item.phase}: ${item.command}`);
+        }
+    }
+    console.log('\n重复注册检测:');
+    if (summary.duplicates.length === 0) {
+        console.log('- 未发现重复');
+    }
+    else {
+        for (const item of summary.duplicates) {
+            console.log(`- ${item.phase}: ${item.command} (x${item.count})`);
+        }
+    }
+    console.log('\n间接触发（阶段门禁与 Review 链路）:');
+    for (const item of summary.phaseCommands) {
+        console.log(`- ${item.command}: ${item.trigger}`);
+    }
+});
+/**
+ * Phase Transition Check - Unified function for phase transition validation
+ */
+async function runPhaseTransitionCheck(options) {
+    const cwd = process.cwd();
+    const changeId = options.change || process.env.ZHUANSPEC_CHANGE_ID || '';
+    const fromPhase = options.from || process.env.ZHUANSPEC_PHASE || 'idle';
+    const toPhase = options.to || '';
+    if (!changeId) {
+        return {
+            continue: false,
+            systemMessage: 'Phase transition check skipped: no change ID provided',
+        };
+    }
+    const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+    // Determine target phase if not specified
+    let targetPhase = toPhase;
+    if (!targetPhase) {
+        switch (fromPhase) {
+            case 'propose':
+                targetPhase = 'apply';
+                break;
+            case 'apply':
+                targetPhase = 'review';
+                break;
+            case 'review':
+                targetPhase = 'archive';
+                break;
+            default:
+                targetPhase = 'apply';
+        }
+    }
+    // Execute appropriate pre-check based on target phase
+    switch (targetPhase) {
+        case 'apply':
+            // Propose → Apply: Run pre-apply checks
+            const preApplyResult = await checkPreApplyConditions(changeDir);
+            if (preApplyResult.continue) {
+                return {
+                    continue: true,
+                    systemMessage: `✓ Phase transition approved: ${fromPhase} → ${targetPhase}\n\nAll pre-apply checks passed. You may now proceed to Apply phase.`,
+                    checks: preApplyResult.checks,
+                };
+            }
+            return {
+                continue: false,
+                systemMessage: `✗ Phase transition blocked: ${fromPhase} → ${targetPhase}\n\n${preApplyResult.systemMessage}`,
+                checks: preApplyResult.checks,
+            };
+        case 'review':
+            // Apply → Review: Run post-apply deviation check
+            const postApplyResult = await executePostApply(changeDir, cwd);
+            if (postApplyResult.hookSpecificOutput?.deviationDetected) {
+                return {
+                    continue: false,
+                    systemMessage: `✗ Phase transition blocked: ${fromPhase} → ${targetPhase}\n\nDeviation detected: ${postApplyResult.hookSpecificOutput.deviationFiles?.length || 0} files outside proposal scope.\nPlease update proposal (Reverse Sync) before proceeding to Review.`,
+                };
+            }
+            return {
+                continue: true,
+                systemMessage: `✓ Phase transition approved: ${fromPhase} → ${targetPhase}\n\nNo deviations detected. Review phase can proceed.`,
+            };
+        case 'archive':
+            // Review → Archive: Check for review completion
+            const metricsDir = path.join(changeDir, 'metrics');
+            const reviewPath = path.join(metricsDir, 'review.json');
+            const testsPath = path.join(metricsDir, 'tests.json');
+            const reportPath = path.join(changeDir, 'review-report.md');
+            const checks = {
+                reviewCompleted: false,
+                testsCompleted: false,
+                reportExists: false,
+            };
+            checks.reviewCompleted = await FileSystemUtils.fileExists(reviewPath);
+            checks.testsCompleted = await FileSystemUtils.fileExists(testsPath);
+            checks.reportExists = await FileSystemUtils.fileExists(reportPath);
+            if (!checks.reviewCompleted || !checks.testsCompleted || !checks.reportExists) {
+                const missing = [];
+                if (!checks.reviewCompleted)
+                    missing.push('review.json');
+                if (!checks.testsCompleted)
+                    missing.push('tests.json');
+                if (!checks.reportExists)
+                    missing.push('review-report.md');
+                return {
+                    continue: false,
+                    systemMessage: `✗ Phase transition blocked: ${fromPhase} → ${targetPhase}\n\nMissing review artifacts:\n${missing.map(m => `- ${m}`).join('\n')}\n\nPlease complete Review phase before archiving.`,
+                    checks,
+                };
+            }
+            return {
+                continue: true,
+                systemMessage: `✓ Phase transition approved: ${fromPhase} → ${targetPhase}\n\nAll review artifacts present. Archive phase can proceed.`,
+                checks,
+            };
+        default:
+            return {
+                continue: false,
+                systemMessage: `Unknown target phase: ${targetPhase}`,
+            };
+    }
+}
+async function collectHookStatus() {
+    const cwd = process.cwd();
+    const settingsPath = path.join(cwd, '.claude', 'settings.json');
+    const settingsExists = await FileSystemUtils.fileExists(settingsPath);
+    const registeredLifecycleHooks = [];
+    const duplicates = [];
+    if (settingsExists) {
+        try {
+            const content = await FileSystemUtils.readFile(settingsPath);
+            const parsed = JSON.parse(content);
+            const hooks = parsed.hooks ?? {};
+            for (const [phase, phaseConfigs] of Object.entries(hooks)) {
+                if (!Array.isArray(phaseConfigs))
+                    continue;
+                const commandCounts = new Map();
+                for (const phaseConfig of phaseConfigs) {
+                    const hooksArray = phaseConfig.hooks;
+                    if (!Array.isArray(hooksArray))
+                        continue;
+                    for (const hookItem of hooksArray) {
+                        const command = hookItem.command;
+                        if (typeof command !== 'string')
+                            continue;
+                        registeredLifecycleHooks.push({ phase, command });
+                        commandCounts.set(command, (commandCounts.get(command) ?? 0) + 1);
+                    }
+                }
+                for (const [command, count] of commandCounts.entries()) {
+                    if (count > 1) {
+                        duplicates.push({ phase, command, count });
+                    }
+                }
+            }
+        }
+        catch {
+            // Keep defaults; command should still provide guidance.
+        }
+    }
+    const phaseCommands = [
+        {
+            command: 'zhuanspec-hook pre-apply',
+            trigger: '由 deviation-check 内部调用 checkPreApplyConditions（Propose → Apply 前门禁）',
+        },
+        {
+            command: 'zhuanspec-hook post-apply',
+            trigger: '由 summarize/executePostApply 间接触发（Apply 完成后偏差检测与 review 触发）',
+        },
+        {
+            command: 'zhuanspec-hook review-code-check',
+            trigger: '由 zhuanspec review 结果链路调用（代码审查结果判定）',
+        },
+        {
+            command: 'zhuanspec-hook review-unit-test-check',
+            trigger: '由 zhuanspec review 结果链路调用（单测结果判定）',
+        },
+        {
+            command: 'zhuanspec-hook review-spec-check',
+            trigger: '由 zhuanspec review 结果链路调用（Spec/Code 一致性判定）',
+        },
+    ];
+    return {
+        settingsPath,
+        settingsExists,
+        registeredLifecycleHooks,
+        duplicates,
+        phaseCommands,
+    };
+}
+program.parse();
+//# sourceMappingURL=hooks.js.map

package/dist/cli/index.js

@@ -13,9 +13,12 @@ import { ChangeCommand } from '../commands/change.js';
 import { ValidateCommand } from '../commands/validate.js';
 import { ShowCommand } from '../commands/show.js';
 import { CompletionCommand } from '../commands/completion.js';
+import { ReviewCommand } from '../commands/review.js';
+import { ProgressCommand } from '../commands/progress.js';
 import { discoverSkills, formatSkillsList } from '../core/skill-discovery.js';
 import { registerConfigCommand } from '../commands/config.js';
 import { registerArtifactWorkflowCommands } from '../commands/artifact-workflow.js';
+import { DesignCommand } from '../commands/design.js';
 const program = new Command();
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
@@ -89,6 +92,36 @@ program
         process.exit(1);
     }
 });
+const registerTechDesignCommand = (commandName, deprecatedAlias = false) => program
+    .command(`${commandName} [change-name]`)
+    .description(deprecatedAlias
+    ? 'DEPRECATED alias of techDesign. Prepare technical design generation request.'
+    : 'Prepare technical design generation request (techDesign phase, independent before proposal by default)')
+    .option('--change <change-id>', 'Optionally bind generated design source to a change')
+    .option('--desc <text>', 'Requirement description used for technical design generation')
+    .option('--dashen-page-id <id>', 'Dashen pageId used as requirement source')
+    .option('--dashen-url <url>', 'Dashen document URL used as requirement source')
+    .option('--output <path>', 'Output path of generated request markdown (default: doc/*技术方案生成请求.md)')
+    .option('--init-template', 'Generate empty design.md template inside a change (legacy mode)')
+    .option('--force', 'Overwrite existing output file or bound design.md')
+    .option('--validate', 'Validate existing design.md for required sections')
+    .option('--auto-fix', 'Auto-fix missing sections when validation fails (use with --validate)')
+    .action(async (changeName, options) => {
+    try {
+        if (deprecatedAlias) {
+            console.error('Warning: "zhuanspec design" is deprecated. Please use "zhuanspec techDesign".');
+        }
+        const designCommand = new DesignCommand();
+        await designCommand.execute(changeName, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+registerTechDesignCommand('techDesign');
+registerTechDesignCommand('design', true);
 program
     .command('list')
     .description('List items (changes by default). Use --specs to list specs.')
@@ -183,6 +216,72 @@ changeCmd
         process.exitCode = 1;
     }
 });
+program
+    .command('review [change-name]')
+    .description('Run ZhuanSpec review and unit test verification')
+    .option('--json', 'Output review report as JSON')
+    .option('--test-command <command>', 'Test command to execute (default: npm test)')
+    .option('--coverage-threshold <n>', 'Coverage threshold percentage (default: 80)')
+    .action(async (changeName, options) => {
+    try {
+        const reviewCommand = new ReviewCommand();
+        await reviewCommand.execute(changeName, 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);
+    }
+});
+const progressCmd = program
+    .command('progress')
+    .description('Display current execution status and progress')
+    .option('--json', 'Output as JSON for programmatic use')
+    .action(async (options) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.execute(options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Progress show subcommand
+progressCmd
+    .command('show <change-id>')
+    .description('Show progress for a specific change')
+    .option('--json', 'Output as JSON for programmatic use')
+    .action(async (changeId, options) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.show(changeId, options);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Progress set-phase subcommand
+progressCmd
+    .command('set-phase <change-id> <phase>')
+    .description('Set phase for a change (e.g., propose, apply, review, archive)')
+    .action(async (changeId, phase) => {
+    try {
+        const progressCommand = new ProgressCommand();
+        await progressCommand.setPhase(changeId, phase);
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
 program
     .command('archive [change-name]')
     .description('Archive a completed change and update main specs')
@@ -252,6 +351,7 @@ program
     .option('--json', 'Output validation results as JSON')
     .option('--concurrency <n>', 'Max concurrent validations (defaults to env OPENSPEC_CONCURRENCY or 6)')
     .option('--no-interactive', 'Disable interactive prompts')
+    .option('--auto-fix', 'Auto-fix validation errors (max 3 attempts)')
     .action(async (itemName, options) => {
     try {
         const validateCommand = new ValidateCommand();