@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/core/hooks/init.js

@@ -0,0 +1,244 @@
+/**
+ * SessionStart Hook - Initialize ZhuanSpec environment
+ *
+ * This hook runs when Claude Code starts a new session:
+ * 1. Loads project.md and knowledge/ files
+ * 2. Sets environment variables for phase tracking
+ * 3. Retrieves relevant implicit conventions and change patterns
+ */
+import path from 'path';
+import fs from 'fs';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { initializeProgress, recordHookTrigger, getBeijingTime } from './record-progress.js';
+import { getCurrentPhase, getPhaseFromProgress } from '../../utils/phase-utils.js';
+export async function initHook(options) {
+    const startTime = Date.now();
+    const output = await runInitHook(options);
+    const durationMs = Date.now() - startTime;
+    // Record hook trigger
+    await recordHookTrigger('init', 'SessionStart', true, {
+        message: output.systemMessage,
+        durationMs,
+    });
+    // Write debug log to confirm hook execution
+    const cwd = process.cwd();
+    const debugLogPath = path.join(cwd, 'zhuanspec', '.hook-debug.log');
+    const timestamp = getBeijingTime();
+    const logEntry = `[${timestamp}] init-hook executed\n`;
+    try {
+        await fs.promises.appendFile(debugLogPath, logEntry);
+    }
+    catch {
+        // Ignore write errors
+    }
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else {
+        if (output.systemMessage) {
+            console.log(output.systemMessage);
+        }
+    }
+}
+async function runInitHook(_options) {
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    // Check if ZhuanSpec is initialized in this project
+    if (!await FileSystemUtils.directoryExists(zhuanspecDir)) {
+        return {
+            continue: true,
+            systemMessage: 'ℹ ZhuanSpec not initialized in this project. Run `zhuanspec init` to start.',
+        };
+    }
+    // Load project.md if exists
+    const projectMdPath = path.join(zhuanspecDir, 'project.md');
+    let projectContext = '';
+    if (await FileSystemUtils.fileExists(projectMdPath)) {
+        try {
+            projectContext = await FileSystemUtils.readFile(projectMdPath);
+        }
+        catch {
+            // Ignore read errors
+        }
+    }
+    // Load knowledge files if exist
+    const knowledgeDir = path.join(zhuanspecDir, 'knowledge');
+    const knowledgeFiles = [];
+    if (await FileSystemUtils.directoryExists(knowledgeDir)) {
+        try {
+            // Load index.md
+            const indexPath = path.join(knowledgeDir, 'index.md');
+            if (await FileSystemUtils.fileExists(indexPath)) {
+                const content = await FileSystemUtils.readFile(indexPath);
+                knowledgeFiles.push(`### index.md\n${content.substring(0, 500)}...`);
+            }
+            // Load from troubleshooting subdirectory
+            const troubleshootingDir = path.join(knowledgeDir, 'troubleshooting');
+            if (await FileSystemUtils.directoryExists(troubleshootingDir)) {
+                const entries = await fs.promises.readdir(troubleshootingDir);
+                for (const entry of entries) {
+                    if (entry.endsWith('.md')) {
+                        const filePath = path.join(troubleshootingDir, entry);
+                        const content = await FileSystemUtils.readFile(filePath);
+                        knowledgeFiles.push(`### troubleshooting/${entry}\n${content.substring(0, 500)}...`);
+                    }
+                }
+            }
+            // Load from best-practices subdirectory
+            const bestPracticesDir = path.join(knowledgeDir, 'best-practices');
+            if (await FileSystemUtils.directoryExists(bestPracticesDir)) {
+                const entries = await fs.promises.readdir(bestPracticesDir);
+                for (const entry of entries) {
+                    if (entry.endsWith('.md')) {
+                        const filePath = path.join(bestPracticesDir, entry);
+                        const content = await FileSystemUtils.readFile(filePath);
+                        knowledgeFiles.push(`### best-practices/${entry}\n${content.substring(0, 500)}...`);
+                    }
+                }
+            }
+            // Load from implicit-conventions subdirectory
+            const implicitConventionsDir = path.join(knowledgeDir, 'implicit-conventions');
+            if (await FileSystemUtils.directoryExists(implicitConventionsDir)) {
+                const entries = await fs.promises.readdir(implicitConventionsDir);
+                for (const entry of entries) {
+                    if (entry.endsWith('.md')) {
+                        const filePath = path.join(implicitConventionsDir, entry);
+                        const content = await FileSystemUtils.readFile(filePath);
+                        knowledgeFiles.push(`### implicit-conventions/${entry}\n${content.substring(0, 500)}...`);
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore read errors
+        }
+    }
+    // Check for .claude/rules files (project-level)
+    const claudeRulesDir = path.join(cwd, '.claude', 'rules');
+    let rulesFiles = [];
+    try {
+        if (await FileSystemUtils.directoryExists(claudeRulesDir)) {
+            const entries = await fs.promises.readdir(claudeRulesDir);
+            rulesFiles = entries.filter(e => e.endsWith('.md') &&
+                !e.startsWith('.'));
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    // Check for active changes
+    const changesDir = path.join(zhuanspecDir, 'changes');
+    let activeChanges = [];
+    try {
+        if (await FileSystemUtils.directoryExists(changesDir)) {
+            const entries = await fs.promises.readdir(changesDir);
+            activeChanges = entries.filter(e => !e.startsWith('.') &&
+                !e.startsWith('archive') &&
+                e !== 'archive');
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    // Determine current phase based on active changes
+    // Priority: progress.json phase > marker files > directory existence
+    let phase = 'idle';
+    let changeId = '';
+    let currentTask = '';
+    if (activeChanges.length > 0) {
+        for (const change of activeChanges) {
+            const changeDir = path.join(changesDir, change);
+            // 1. Priority: read phase from progress.json
+            const progressPhase = await getPhaseFromProgress(changeDir);
+            if (progressPhase) {
+                phase = progressPhase;
+                changeId = change;
+            }
+            else {
+                // 2. Fallback: comprehensive phase detection
+                phase = await getCurrentPhase(changeDir);
+                changeId = change;
+            }
+            // Read currentTask from progress.json (for all phases)
+            const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+            const legacyProgressPath = path.join(changeDir, 'progress.json');
+            const effectiveProgressPath = (await FileSystemUtils.fileExists(progressPath))
+                ? progressPath
+                : legacyProgressPath;
+            if (await FileSystemUtils.fileExists(effectiveProgressPath)) {
+                try {
+                    const progressContent = await FileSystemUtils.readFile(effectiveProgressPath);
+                    const progress = JSON.parse(progressContent);
+                    currentTask = progress.currentTask || '';
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            }
+            // Found active change, exit loop
+            if (phase !== 'idle')
+                break;
+        }
+    }
+    // Initialize metrics folder for propose/techDesign phase
+    if ((phase === 'propose' || phase === 'techDesign') && changeId) {
+        try {
+            await initializeProgress(changeId, phase);
+        }
+        catch {
+            // Ignore initialization errors
+        }
+    }
+    // Build system message
+    let systemMessage = '';
+    if (projectContext) {
+        systemMessage += `✓ Loaded project.md (${projectContext.length} chars)\n`;
+    }
+    if (knowledgeFiles.length > 0) {
+        systemMessage += `✓ Loaded ${knowledgeFiles.length} knowledge files\n`;
+    }
+    if (rulesFiles.length > 0) {
+        systemMessage += `✓ Found ${rulesFiles.length} rules files in .claude/rules\n`;
+    }
+    if (activeChanges.length > 0) {
+        systemMessage += `✓ Found ${activeChanges.length} active changes\n`;
+        if (phase !== 'idle') {
+            systemMessage += `✓ Current phase: ${phase}`;
+            if (phase === 'propose') {
+                systemMessage += ` (auto-trigger-apply-after-approval)`;
+            }
+            else if (phase === 'techDesign') {
+                systemMessage += ` (run /zhuanspec:proposal to continue)`;
+            }
+            systemMessage += `\n`;
+        }
+    }
+    // Build additional context for Claude
+    let additionalContext = '';
+    if (projectContext.length > 0) {
+        additionalContext += `## Project Context (from project.md)\n${projectContext.substring(0, 2000)}\n\n`;
+    }
+    if (knowledgeFiles.length > 0) {
+        additionalContext += `## Knowledge Files\n${knowledgeFiles.join('\n\n')}\n\n`;
+    }
+    if (rulesFiles.length > 0) {
+        additionalContext += `## Rules Files Detected\n`;
+        additionalContext += `Found ${rulesFiles.length} rule files in .claude/rules: ${rulesFiles.join(', ')}\n`;
+        additionalContext += `(These are loaded automatically by Claude Code system)\n\n`;
+    }
+    return {
+        continue: true,
+        systemMessage: systemMessage || '✓ ZhuanSpec session initialized',
+        hookSpecificOutput: {
+            additionalContext: additionalContext || undefined,
+            env: {
+                ZHUANSPEC_PHASE: phase,
+                ZHUANSPEC_CHANGE_ID: changeId,
+                ZHUANSPEC_CURRENT_TASK: currentTask,
+                ZHUANSPEC_CURRENT_NODE: phase,
+                ZHUANSPEC_RESUME_DEVIATION_CHECK: phase === 'apply' ? 'true' : 'false',
+            },
+        },
+    };
+}
+//# sourceMappingURL=init.js.map

package/dist/core/hooks/notify-milestone.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Notification Hook - Push Milestone Notifications
+ *
+ * This hook runs on Notification events to push milestone messages:
+ * 1. Phase transitions (e.g., propose → apply)
+ * 2. Wave completions
+ * 3. All tasks completion
+ */
+interface NotifyMilestoneOptions {
+    json?: boolean;
+}
+export declare function notifyMilestoneHook(options: NotifyMilestoneOptions): Promise<void>;
+export {};
+//# sourceMappingURL=notify-milestone.d.ts.map

package/dist/core/hooks/notify-milestone.js

@@ -0,0 +1,170 @@
+/**
+ * Notification Hook - Push Milestone Notifications
+ *
+ * This hook runs on Notification events to push milestone messages:
+ * 1. Phase transitions (e.g., propose → apply)
+ * 2. Wave completions
+ * 3. All tasks completion
+ */
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+export async function notifyMilestoneHook(options) {
+    const output = await runNotifyMilestone();
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else {
+        if (output.systemMessage) {
+            console.log(output.systemMessage);
+        }
+    }
+}
+async function runNotifyMilestone() {
+    const phase = process.env.ZHUANSPEC_PHASE || 'idle';
+    const changeId = process.env.ZHUANSPEC_CHANGE_ID || '';
+    // No active change → nothing to notify
+    if (!changeId || phase === 'idle') {
+        return {
+            continue: true,
+        };
+    }
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+    const metricsDir = path.join(changeDir, 'metrics');
+    // Read progress.json for phase transition info
+    const progressPath = path.join(metricsDir, 'progress.json');
+    let progress = null;
+    if (await FileSystemUtils.fileExists(progressPath)) {
+        try {
+            progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        }
+        catch {
+            // Ignore parse errors
+        }
+    }
+    // Read tasks.md for wave status
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    let waves = [];
+    if (await FileSystemUtils.fileExists(tasksPath)) {
+        const tasksContent = await FileSystemUtils.readFile(tasksPath);
+        const tasks = parseTasks(tasksContent);
+        waves = computeWaves(tasks);
+    }
+    // Check for milestones
+    // 1. Phase transition milestone
+    if (progress?.phaseTransitions && progress.phaseTransitions.length > 0) {
+        const latestTransition = progress.phaseTransitions[progress.phaseTransitions.length - 1];
+        const transitionAge = Date.now() - new Date(latestTransition.timestamp).getTime();
+        // Only notify if transition happened within last 60 seconds
+        if (transitionAge < 60000) {
+            return {
+                continue: true,
+                systemMessage: `🎯 里程碑: 阶段切换\n从: ${latestTransition.from} → 到: ${latestTransition.to}\n变更: ${changeId}`,
+                hookSpecificOutput: {
+                    milestoneType: 'phase_transition',
+                    milestoneData: {
+                        fromPhase: latestTransition.from,
+                        toPhase: latestTransition.to,
+                        changeId,
+                    },
+                },
+            };
+        }
+    }
+    // 2. Wave completion milestone
+    for (const wave of waves) {
+        if (wave.status === 'completed') {
+            // Check if this wave was just completed (by checking if next wave is in_progress)
+            const nextWave = waves.find(w => w.waveId === wave.waveId + 1);
+            if (nextWave && nextWave.status === 'in_progress') {
+                const completedTaskIds = wave.completedTasks.map(t => t.taskId).join(', ');
+                return {
+                    continue: true,
+                    systemMessage: `🎯 里程碑: Wave ${wave.waveId} 完成\n已完成任务: ${completedTaskIds}\n下一个 Wave: Wave ${nextWave.waveId}`,
+                    hookSpecificOutput: {
+                        milestoneType: 'wave_completion',
+                        milestoneData: {
+                            waveId: wave.waveId,
+                        },
+                    },
+                };
+            }
+        }
+    }
+    // 3. All tasks completion milestone
+    const allCompleted = waves.length > 0 && waves.every(w => w.status === 'completed');
+    if (allCompleted) {
+        return {
+            continue: true,
+            systemMessage: `🎯 里程碑: 全部任务完成\n变更: ${changeId}\n状态: Ready for Review`,
+            hookSpecificOutput: {
+                milestoneType: 'all_tasks_complete',
+                milestoneData: {
+                    changeId,
+                },
+            },
+        };
+    }
+    // No milestone to report
+    return {
+        continue: true,
+    };
+}
+function parseTasks(content) {
+    const tasks = [];
+    const lines = content.split('\n');
+    let currentWave = 0;
+    for (const line of lines) {
+        // Match wave headers: ### Wave 1, ### Wave 2, etc.
+        const waveMatch = line.match(/^###\s*Wave\s*(\d+)/i);
+        if (waveMatch) {
+            currentWave = parseInt(waveMatch[1], 10);
+            continue;
+        }
+        // Match task lines: - [ ] X.Y description or - [x] X.Y description
+        const taskMatch = line.match(/^-\s*\[([x ])\]\s*(\d+\.\d+)\s*(.+)/);
+        if (taskMatch) {
+            const statusChar = taskMatch[1];
+            const taskId = taskMatch[2];
+            tasks.push({
+                taskId,
+                status: statusChar === 'x' ? 'completed' : 'pending',
+                wave: currentWave,
+            });
+        }
+    }
+    return tasks;
+}
+function computeWaves(tasks) {
+    const wavesMap = new Map();
+    for (const task of tasks) {
+        if (!wavesMap.has(task.wave)) {
+            wavesMap.set(task.wave, {
+                waveId: task.wave,
+                tasks: [],
+                completedTasks: [],
+                status: 'pending',
+            });
+        }
+        const wave = wavesMap.get(task.wave);
+        wave.tasks.push(task);
+        if (task.status === 'completed') {
+            wave.completedTasks.push(task);
+        }
+    }
+    // Determine wave status
+    for (const [, wave] of wavesMap) {
+        if (wave.completedTasks.length === wave.tasks.length) {
+            wave.status = 'completed';
+        }
+        else if (wave.completedTasks.length > 0) {
+            wave.status = 'in_progress';
+        }
+        else {
+            wave.status = 'pending';
+        }
+    }
+    return Array.from(wavesMap.values()).sort((a, b) => a.waveId - b.waveId);
+}
+//# sourceMappingURL=notify-milestone.js.map

package/dist/core/hooks/post-apply.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Post-Apply Hook
+ *
+ * Actions after Apply phase completes:
+ * 1. Reverse Sync deviation detection
+ * 2. Auto-trigger Review if no deviation
+ * 3. Update progress.json
+ */
+interface PostApplyOptions {
+    json?: boolean;
+    change?: string;
+}
+interface HookOutput {
+    continue: boolean;
+    systemMessage?: string;
+    hookSpecificOutput?: {
+        reviewTriggered?: boolean;
+        deviationDetected?: boolean;
+        deviationFiles?: string[];
+    };
+}
+export declare function postApplyHook(options: PostApplyOptions): Promise<void>;
+/**
+ * Execute post-apply actions: deviation detection and review triggering.
+ * This function is exported for use by other hooks (e.g., summarize).
+ */
+export declare function executePostApply(changeDir: string, repoRoot: string): Promise<HookOutput>;
+export {};
+//# sourceMappingURL=post-apply.d.ts.map

package/dist/core/hooks/post-apply.js

@@ -0,0 +1,173 @@
+/**
+ * Post-Apply Hook
+ *
+ * Actions after Apply phase completes:
+ * 1. Reverse Sync deviation detection
+ * 2. Auto-trigger Review if no deviation
+ * 3. Update progress.json
+ */
+import path from 'path';
+import { execSync } from 'child_process';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { getBeijingTime } from './record-progress.js';
+export async function postApplyHook(options) {
+    const output = await runPostApplyHook(options.change || '');
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else if (output.systemMessage) {
+        console.log(output.systemMessage);
+    }
+}
+async function runPostApplyHook(changeId) {
+    if (!changeId) {
+        return {
+            continue: true,
+            systemMessage: 'Post-apply hook skipped: no change provided',
+        };
+    }
+    const repoRoot = process.cwd();
+    const changeDir = path.join(repoRoot, 'zhuanspec', 'changes', changeId);
+    return await executePostApply(changeDir, repoRoot);
+}
+/**
+ * Execute post-apply actions: deviation detection and review triggering.
+ * This function is exported for use by other hooks (e.g., summarize).
+ */
+export async function executePostApply(changeDir, repoRoot) {
+    // 1. Reverse Sync deviation detection
+    const deviationResult = await detectDeviation(changeDir, repoRoot);
+    // 2. Auto-trigger Review if no deviation
+    if (!deviationResult.detected) {
+        try {
+            console.log('Post-apply: Triggering automatic review...');
+            execSync(`zhuanspec review`, {
+                cwd: repoRoot,
+                encoding: 'utf-8',
+                stdio: 'inherit',
+            });
+            // 3. Update progress.json
+            await updateProgressJson(changeDir, 'review_triggered');
+            return {
+                continue: true,
+                systemMessage: 'Post-apply: Review triggered automatically',
+                hookSpecificOutput: {
+                    reviewTriggered: true,
+                    deviationDetected: false,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                continue: true,
+                systemMessage: 'Post-apply: Review trigger failed (manual review required)',
+                hookSpecificOutput: {
+                    reviewTriggered: false,
+                    deviationDetected: false,
+                },
+            };
+        }
+    }
+    // Deviation detected - skip review
+    return {
+        continue: true,
+        systemMessage: `Post-apply: Deviation detected (${deviationResult.files?.length || 0} files outside scope), review skipped`,
+        hookSpecificOutput: {
+            reviewTriggered: false,
+            deviationDetected: true,
+            deviationFiles: deviationResult.files,
+        },
+    };
+}
+/**
+ * Detect deviation by comparing proposal scope with actual git diff
+ */
+async function detectDeviation(changeDir, repoRoot) {
+    // Parse estimated files from proposal
+    const proposalPath = path.join(changeDir, 'proposal.md');
+    let estimatedFiles = [];
+    try {
+        const proposalContent = await FileSystemUtils.readFile(proposalPath);
+        // Extract affected files from "影响范围" section
+        const impactMatch = proposalContent.match(/##\s+(影响范围|Impact)[\s\S]*?(?=##|$)/i);
+        if (impactMatch) {
+            const impactSection = impactMatch[0];
+            // Parse file references
+            const fileMatches = impactSection.matchAll(/[`']([^`']+\.(?:java|ts|js|py|go|rs|xml|yaml|json|md))[`']/gi);
+            estimatedFiles = Array.from(fileMatches, m => m[1]);
+        }
+    }
+    catch {
+        // Cannot read proposal
+    }
+    // Get actual changed files
+    let actualFiles = [];
+    try {
+        const output = execSync('git diff --name-only HEAD~1 HEAD', {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        });
+        actualFiles = output.trim().split('\n').filter(Boolean);
+    }
+    catch {
+        // Try git status for uncommitted changes
+        try {
+            const statusOutput = execSync('git status --porcelain', {
+                cwd: repoRoot,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'ignore'],
+            });
+            actualFiles = statusOutput
+                .trim()
+                .split('\n')
+                .map(line => line.replace(/^\s*[A-Z?]+\s+/, '').trim())
+                .filter(Boolean);
+        }
+        catch {
+            // No git info available
+            return { detected: false };
+        }
+    }
+    // Find files outside proposal scope (excluding zhuanspec internal files)
+    const outOfScopeFiles = [];
+    for (const file of actualFiles) {
+        if (file.includes('zhuanspec/'))
+            continue; // Allow internal changes
+        const inScope = estimatedFiles.some(estimated => file.includes(estimated) || estimated.includes(file));
+        if (!inScope && estimatedFiles.length > 0) {
+            outOfScopeFiles.push(file);
+        }
+    }
+    return {
+        detected: outOfScopeFiles.length > 0,
+        files: outOfScopeFiles,
+    };
+}
+/**
+ * Update progress.json to track phase transitions
+ */
+async function updateProgressJson(changeDir, event) {
+    const metricsDir = path.join(changeDir, 'metrics');
+    const progressPath = path.join(metricsDir, 'progress.json');
+    await FileSystemUtils.createDirectory(metricsDir);
+    let progress = {};
+    try {
+        if (await FileSystemUtils.fileExists(progressPath)) {
+            const content = await FileSystemUtils.readFile(progressPath);
+            progress = JSON.parse(content);
+        }
+    }
+    catch {
+        progress = {};
+    }
+    progress.lastEvent = event;
+    progress.lastUpdatedAt = getBeijingTime();
+    progress.events = progress.events || [];
+    progress.events.push({
+        event,
+        timestamp: getBeijingTime(),
+    });
+    await FileSystemUtils.writeFile(progressPath, JSON.stringify(progress, null, 2));
+}
+//# sourceMappingURL=post-apply.js.map

package/dist/core/hooks/post-archive.d.ts

@@ -0,0 +1,7 @@
+interface PostArchiveOptions {
+    json?: boolean;
+    archived?: string;
+}
+export declare function postArchiveHook(options: PostArchiveOptions): Promise<void>;
+export {};
+//# sourceMappingURL=post-archive.d.ts.map