@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/core/hooks/deviation-check.js

@@ -0,0 +1,403 @@
+/**
+ * PreToolUse Hook - Deviation Check
+ *
+ * This hook runs before Write/Edit operations to check if the modification
+ * is within the approved proposal scope. It implements the "Reverse Sync" iron law.
+ *
+ * Logic:
+ * 1. If ZHUANSPEC_PHASE is 'idle' or no change bound → allow (normal workflow)
+ * 2. If ZHUANSPEC_PHASE is 'propose' → block (no code changes in propose phase)
+ * 3. If ZHUANSPEC_PHASE is 'apply' → check if file is in proposal scope:
+ *    - In scope → allow
+ *    - Out of scope → block with deviation handling options
+ */
+import path from 'path';
+import { execSync } from 'child_process';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { checkPreApplyConditions } from './pre-apply.js';
+import { recordHookTrigger } from './record-progress.js';
+// Pitfall keywords for knowledge collection
+const PITFALL_KEYWORDS = [
+    '不对', '错了', '踩坑', '坑', '失败', '问题', 'bug',
+    '错误', '异常', '不工作', '不生效', '没想到',
+    '注意', '小心', '避免', '陷阱', '教训',
+    'wrong', 'error', 'fail', 'bug', 'issue', 'pitfall',
+];
+// Best practice keywords for knowledge collection
+const BEST_PRACTICE_KEYWORDS = [
+    '最佳实践', '推荐做法', '最佳做法', '建议', '经验',
+    '成功经验', '最佳方案', '最佳选择', '正确做法',
+    'best practice', 'recommended', 'recommendation',
+];
+// Implicit convention keywords for knowledge collection
+const IMPLICIT_CONVENTION_KEYWORDS = [
+    '隐式约定', '默认规则', '约定', '习惯', '惯例',
+    '默认行为', '默认配置', '默认值', '隐式规则',
+    'implicit convention', 'default behavior', 'convention',
+];
+// User correction keywords for deviation detection trigger
+const USER_CORRECTION_KEYWORDS = [
+    '不对', '错了', '这里应该是', '应该是', '不是这样',
+    '这里不对', '改一下', '需要修改', '修改提案',
+    'wrong', 'should be', 'not right', 'need to fix',
+];
+export async function deviationCheckHook(options) {
+    const startTime = Date.now();
+    const toolName = options.tool || 'Write';
+    // Read stdin for Claude Code hook input
+    let stdinData = {};
+    try {
+        const stdinContent = await readStdin();
+        if (stdinContent) {
+            stdinData = JSON.parse(stdinContent);
+        }
+    }
+    catch {
+        // Ignore parse errors
+    }
+    // Get file path from stdin or options
+    const filePath = stdinData.tool_input?.file_path
+        || options.file
+        || '';
+    const promptText = stdinData?.prompt
+        || options.prompt
+        || '';
+    const trigger = options.trigger || 'pre-tool';
+    const output = await runDeviationCheck(filePath, trigger, promptText, options);
+    const durationMs = Date.now() - startTime;
+    // Record hook trigger
+    await recordHookTrigger('deviation-check', 'PreToolUse', output.continue, {
+        toolName,
+        filePath,
+        message: output.systemMessage,
+        durationMs,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else {
+        if (output.systemMessage) {
+            console.log(output.systemMessage);
+        }
+        if (!output.continue) {
+            // Exit with non-zero to block the operation
+            process.exit(1);
+        }
+    }
+}
+async function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => data += chunk);
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(null));
+    });
+}
+async function runDeviationCheck(filePath, trigger, promptText, _options) {
+    const phase = process.env.ZHUANSPEC_PHASE || 'idle';
+    const changeId = process.env.ZHUANSPEC_CHANGE_ID || '';
+    const currentTask = process.env.ZHUANSPEC_CURRENT_TASK || '';
+    // No change bound or idle phase → allow normal workflow
+    if (!changeId || phase === 'idle') {
+        return {
+            continue: true,
+            systemMessage: '✓ No active ZhuanSpec change, normal workflow allowed',
+        };
+    }
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+    const proposalPath = path.join(changeDir, 'proposal.md');
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    // Resume check: when session is resumed in apply phase, do a one-time deviation scan.
+    if (phase === 'apply' && trigger === 'resume') {
+        const estimatedFiles = await parseEstimatedChanges(proposalPath);
+        const gitDiffFiles = await parseGitChangedFiles(cwd);
+        const outOfScope = gitDiffFiles.filter((file) => {
+            if (file.includes('zhuanspec/'))
+                return false;
+            const normalized = normalizePath(file);
+            return !estimatedFiles.map(normalizePath).some((scope) => normalized.includes(scope) || scope.includes(normalized));
+        });
+        if (outOfScope.length > 0) {
+            return {
+                continue: false,
+                stopReason: 'Resume deviation detected',
+                systemMessage: `⚠️ RESUME DEVIATION: 检测到 ${outOfScope.length} 个提案范围外改动，请先执行 Reverse Sync（更新 proposal/tasks）再继续 Apply。`,
+                hookSpecificOutput: {
+                    additionalContext: `Out-of-scope files: ${outOfScope.join(', ')}`,
+                    options: ['更新提案后继续实施', '取消本次恢复并重新评估'],
+                },
+            };
+        }
+        return {
+            continue: true,
+            systemMessage: '✓ Resume deviation check passed',
+        };
+    }
+    // Post-prompt check: catch "additional request after apply/interruption" and force reverse-sync first.
+    if (phase === 'apply' && trigger === 'post-prompt') {
+        // Check for user correction keywords
+        const correctionKeywordFound = USER_CORRECTION_KEYWORDS.some(keyword => promptText.toLowerCase().includes(keyword.toLowerCase()));
+        if (correctionKeywordFound) {
+            // User correction detected - trigger deviation handling
+            return {
+                continue: false,
+                stopReason: 'User correction detected in Apply phase',
+                systemMessage: `⚠️ DEVIATION TRIGGER: 检测到用户纠正关键词，当前阶段为 ${phase}
+请按偏离修正流程处理：
+1. 先修改 spec 文件
+2. 用户确认后再修改代码
+3. 用户确认无误后触发知识沉淀`,
+                hookSpecificOutput: {
+                    additionalContext: `User input: ${promptText.slice(0, 200)}`,
+                    options: [
+                        '修改 Spec 文件',
+                        '直接修改代码（跳过 Spec）',
+                        '取消修改',
+                    ],
+                },
+            };
+        }
+        const extraRequestPattern = /(另外|额外|顺便|再加|同时|also|additionally|by the way|one more)/i;
+        const editIntentPattern = /(修改|改|新增|删除|重构|optimi[sz]e|add|change|edit|update|refactor|remove)/i;
+        if (extraRequestPattern.test(promptText) && editIntentPattern.test(promptText)) {
+            return {
+                continue: false,
+                stopReason: 'Post-prompt additional requirement detected',
+                systemMessage: '⚠️ 检测到 Apply 阶段追加需求，请先更新 proposal/tasks（Reverse Sync）后再实施。',
+                hookSpecificOutput: {
+                    additionalContext: `Prompt: ${promptText.slice(0, 300)}`,
+                    options: ['更新提案后继续实施', '标记为Bug修复豁免', '取消追加需求'],
+                },
+            };
+        }
+        return {
+            continue: true,
+            systemMessage: '✓ Post-prompt deviation check passed',
+        };
+    }
+    // Propose phase → block all code modifications (Iron Law 1: No Spec No Code)
+    // But check if we can transition to Apply phase
+    if (phase === 'propose') {
+        // Allow proposal file modifications
+        if (filePath.includes('zhuanspec/changes/') || filePath.includes('zhuanspec/specs/')) {
+            return {
+                continue: true,
+                systemMessage: '✓ Proposal file modification allowed in propose phase',
+            };
+        }
+        // Check if this is a code file that might trigger Apply phase transition
+        const isCodeFile = !filePath.includes('zhuanspec/') &&
+            /\.(java|ts|tsx|js|jsx|py|go|rs|sql|kt|scala|c|cpp|cs)$/i.test(filePath);
+        if (isCodeFile && changeId && trigger === 'pre-tool') {
+            // Try to run pre-apply check to see if we can transition to Apply phase
+            const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+            const preApplyResult = await checkPreApplyConditions(changeDir);
+            if (preApplyResult.continue) {
+                // Pre-apply passed - allow code modification and suggest phase transition
+                return {
+                    continue: true,
+                    systemMessage: `✓ PRE-APPLY CHECK PASSED. Ready to transition to Apply phase.\n\nAll proposal requirements met:\n- proposal.md exists ✓\n- tasks.md exists ✓\n- specs directory non-empty ✓\n- validate --strict passed ✓\n- Plan approved ✓\n\nYou may now proceed with implementation. Consider updating ZHUANSPEC_PHASE to 'apply'.`,
+                };
+            }
+            // Pre-apply failed - block and show what's missing
+            const checks = preApplyResult.checks;
+            const missingItems = [];
+            if (!checks?.proposalExists)
+                missingItems.push('proposal.md');
+            if (!checks?.tasksExists)
+                missingItems.push('tasks.md');
+            if (!checks?.specsExists)
+                missingItems.push('specs directory (non-empty)');
+            if (!checks?.validationPassed)
+                missingItems.push('validate --strict passing');
+            if (!checks?.approved)
+                missingItems.push('.approved file (Plan approval)');
+            return {
+                continue: false,
+                stopReason: 'Pre-apply check failed: Cannot transition to Apply phase',
+                systemMessage: `⚠️ BLOCKED: Cannot modify "${filePath}" - Pre-apply check failed\n\nMissing requirements:\n${missingItems.map(m => `- ${m}`).join('\n')}\n\nPlease complete Propose phase requirements before implementing code.`,
+                hookSpecificOutput: {
+                    additionalContext: 'ZhuanSpec Iron Law 1: No Spec No Code - Complete proposal before implementation.',
+                },
+            };
+        }
+        // Block other non-code file modifications in propose phase
+        return {
+            continue: false,
+            stopReason: 'Propose phase: No code modifications allowed (No Spec No Code)',
+            systemMessage: `⚠️ BLOCKED: Propose phase - Cannot modify "${filePath}"\nOnly proposal files (zhuanspec/changes/, zhuanspec/specs/) can be modified.\nPlease wait for proposal approval before implementing.`,
+            hookSpecificOutput: {
+                additionalContext: 'ZhuanSpec Iron Law 1: No Spec No Code - Implementation cannot proceed until proposal is approved.',
+            },
+        };
+    }
+    // Apply phase → check deviation
+    if (phase === 'apply') {
+        let estimatedFiles = [];
+        let currentTaskFiles = [];
+        // Parse proposal for estimated changes
+        if (await FileSystemUtils.fileExists(proposalPath)) {
+            estimatedFiles = await parseEstimatedChanges(proposalPath);
+        }
+        // Parse tasks for current task scope
+        if (await FileSystemUtils.fileExists(tasksPath)) {
+            currentTaskFiles = await parseCurrentTaskFiles(tasksPath, currentTask);
+        }
+        // Normalize paths for comparison
+        const normalizedTarget = normalizePath(filePath);
+        const normalizedEstimated = estimatedFiles.map(normalizePath);
+        const normalizedCurrentTask = currentTaskFiles.map(normalizePath);
+        // Check if file is in scope
+        const inEstimatedScope = normalizedEstimated.some(f => normalizedTarget.includes(f) || f.includes(normalizedTarget));
+        const inCurrentTaskScope = normalizedCurrentTask.some(f => normalizedTarget.includes(f) || f.includes(normalizedTarget));
+        if (inEstimatedScope || inCurrentTaskScope) {
+            return {
+                continue: true,
+                systemMessage: `✓ File "${filePath}" is within proposal scope`,
+            };
+        }
+        // File is out of scope → deviation detected
+        const deviationId = `dev-${Date.now()}`;
+        return {
+            continue: false,
+            stopReason: 'Deviation detected: File not in approved proposal scope',
+            systemMessage: `⚠️ DEVIATION DETECTED: "${filePath}" is not in the approved proposal scope.\n\nProposal scope: [${estimatedFiles.join(', ') || 'not specified'}]\nCurrent task scope: [${currentTaskFiles.join(', ') || 'not specified'}]\n\nPlease choose how to handle this deviation:`,
+            hookSpecificOutput: {
+                deviationId,
+                additionalContext: `
+Deviation detected for file: ${filePath}
+
+Options:
+1. 更新提案后继续实施 - Update proposal to include this file, then continue
+2. 此修改是Bug修复 - Mark as bug fix (exempt from proposal flow)
+3. 取消修改 - Cancel this modification
+4. 其他 - Other (provide explanation)
+
+ZhuanSpec Iron Law 3: Reverse Sync - When deviation is found, update proposal first.
+`,
+                options: [
+                    '更新提案后继续实施',
+                    '此修改是Bug修复',
+                    '取消修改',
+                    '其他',
+                ],
+            },
+        };
+    }
+    // Default: allow
+    return {
+        continue: true,
+    };
+}
+async function parseGitChangedFiles(repoRoot) {
+    try {
+        const output = execSync('git diff --name-only', {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        });
+        return output.split('\n').map((line) => line.trim()).filter(Boolean);
+    }
+    catch {
+        // fall through
+    }
+    try {
+        const status = execSync('git status --porcelain', {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        });
+        return status
+            .split('\n')
+            .map((line) => line.replace(/^\s*[A-Z?]+\s+/, '').trim())
+            .filter(Boolean);
+    }
+    catch {
+        // ignore
+    }
+    return [];
+}
+async function parseEstimatedChanges(proposalPath) {
+    try {
+        const content = await FileSystemUtils.readFile(proposalPath);
+        const files = [];
+        // Look for "影响范围" or "Affected code" sections
+        const lines = content.split('\n');
+        let inAffectedSection = false;
+        for (const line of lines) {
+            if (line.includes('影响范围') || line.includes('Affected code') || line.includes('Affected files')) {
+                inAffectedSection = true;
+                continue;
+            }
+            if (inAffectedSection && line.startsWith('##')) {
+                // End of section
+                inAffectedSection = false;
+            }
+            if (inAffectedSection && line.trim().startsWith('-')) {
+                // Extract file path from bullet point
+                const match = line.match(/-\s*(.+)/);
+                if (match) {
+                    files.push(match[1].trim());
+                }
+            }
+        }
+        return files;
+    }
+    catch {
+        return [];
+    }
+}
+async function parseCurrentTaskFiles(tasksPath, currentTask) {
+    if (!currentTask) {
+        return [];
+    }
+    try {
+        const content = await FileSystemUtils.readFile(tasksPath);
+        const files = [];
+        // Find the current task section
+        const lines = content.split('\n');
+        let inCurrentTask = false;
+        for (const line of lines) {
+            // Match task line: - [ ] X.Y description or - [x] X.Y description
+            const taskMatch = line.match(/-\s*\[[x ]\]\s*(\d+\.\d+)\s*(.+)/);
+            if (taskMatch) {
+                const taskId = taskMatch[1];
+                if (taskId === currentTask) {
+                    inCurrentTask = true;
+                    // Extract files mentioned in task description
+                    const description = taskMatch[2];
+                    // Look for file patterns in description
+                    const filePatterns = description.match(/[a-zA-Z0-9_\-/]+\.(java|ts|tsx|js|jsx|py|go|rs|md|yaml|json|sql)/g);
+                    if (filePatterns) {
+                        files.push(...filePatterns);
+                    }
+                }
+                else {
+                    inCurrentTask = false;
+                }
+            }
+            // Also check for file mentions within task details
+            if (inCurrentTask) {
+                const filePatterns = line.match(/[a-zA-Z0-9_\-/]+\.(java|ts|tsx|js|jsx|py|go|rs|md|yaml|json|sql)/g);
+                if (filePatterns) {
+                    files.push(...filePatterns);
+                }
+            }
+        }
+        return files;
+    }
+    catch {
+        return [];
+    }
+}
+function normalizePath(p) {
+    return p
+        .replace(/\\/g, '/')
+        .replace(/^\.\/|^\/+/, '')
+        .toLowerCase();
+}
+export { PITFALL_KEYWORDS, USER_CORRECTION_KEYWORDS, BEST_PRACTICE_KEYWORDS, IMPLICIT_CONVENTION_KEYWORDS };
+//# sourceMappingURL=deviation-check.js.map

package/dist/core/hooks/deviation-handler.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Deviation Handler - 偏离修正流程处理
+ *
+ * 当用户在 Apply 阶段输入纠正关键词时触发偏离修正流程：
+ * 1. 先修改 spec 文件，同步用户确认
+ * 2. 用户确认后修改代码，完成后验证
+ * 3. 用户确认无误后触发知识沉淀
+ */
+export interface DeviationContext {
+    changeId: string;
+    phase: string;
+    userInput: string;
+    detectedKeywords: string[];
+}
+export interface DeviationAction {
+    type: 'modify-spec' | 'modify-code' | 'knowledge-collect' | 'cancel';
+    targetFile?: string;
+    content?: string;
+}
+/**
+ * Handle deviation correction flow
+ *
+ * @param context - Deviation context with changeId, phase, userInput
+ * @returns Action recommendation for the AI
+ */
+export declare function handleDeviation(context: DeviationContext): Promise<DeviationAction>;
+/**
+ * Complete deviation handling after user confirms
+ *
+ * @param deviationId - The deviation ID to mark as resolved
+ * @param specChanged - List of spec files that were changed
+ * @param codeChanged - List of code files that were changed
+ */
+export declare function completeDeviation(deviationId: string, changeId: string, specChanged: string[], codeChanged: string[]): Promise<void>;
+/**
+ * Trigger knowledge collection after deviation is resolved
+ *
+ * @param changeId - The change ID
+ * @param knowledgeContent - Knowledge content to write
+ */
+export declare function triggerKnowledgeCollection(changeId: string, knowledgeContent: string): Promise<void>;
+export { USER_CORRECTION_KEYWORDS } from './deviation-check.js';
+//# sourceMappingURL=deviation-handler.d.ts.map

package/dist/core/hooks/deviation-handler.js

@@ -0,0 +1,98 @@
+/**
+ * Deviation Handler - 偏离修正流程处理
+ *
+ * 当用户在 Apply 阶段输入纠正关键词时触发偏离修正流程：
+ * 1. 先修改 spec 文件，同步用户确认
+ * 2. 用户确认后修改代码，完成后验证
+ * 3. 用户确认无误后触发知识沉淀
+ */
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { getBeijingTime } from './record-progress.js';
+/**
+ * Handle deviation correction flow
+ *
+ * @param context - Deviation context with changeId, phase, userInput
+ * @returns Action recommendation for the AI
+ */
+export async function handleDeviation(context) {
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const changeDir = path.join(zhuanspecDir, 'changes', context.changeId);
+    const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+    // Record deviation in progress.json
+    const deviationId = `dev-${Date.now()}`;
+    const deviationRecord = {
+        deviationId,
+        detectedAt: getBeijingTime(),
+        triggerType: 'user-input',
+        userInput: context.userInput.slice(0, 500),
+        specChanged: [],
+        codeChanged: [],
+        resolvedAt: undefined,
+    };
+    // Update progress.json with deviation record
+    if (await FileSystemUtils.fileExists(progressPath)) {
+        const progressData = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        progressData.deviationRecords = progressData.deviationRecords || [];
+        progressData.deviationRecords.push(deviationRecord);
+        progressData.deviationCount = (progressData.deviationCount || 0) + 1;
+        await FileSystemUtils.writeFile(progressPath, JSON.stringify(progressData, null, 2));
+    }
+    // Step 1: Modify spec file first
+    return {
+        type: 'modify-spec',
+        targetFile: 'specs/',
+    };
+}
+/**
+ * Complete deviation handling after user confirms
+ *
+ * @param deviationId - The deviation ID to mark as resolved
+ * @param specChanged - List of spec files that were changed
+ * @param codeChanged - List of code files that were changed
+ */
+export async function completeDeviation(deviationId, changeId, specChanged, codeChanged) {
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+    const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+    if (await FileSystemUtils.fileExists(progressPath)) {
+        const progressData = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        const deviation = progressData.deviationRecords?.find((d) => d.deviationId === deviationId);
+        if (deviation) {
+            deviation.specChanged = specChanged;
+            deviation.codeChanged = codeChanged;
+            deviation.resolvedAt = getBeijingTime();
+            await FileSystemUtils.writeFile(progressPath, JSON.stringify(progressData, null, 2));
+        }
+    }
+}
+/**
+ * Trigger knowledge collection after deviation is resolved
+ *
+ * @param changeId - The change ID
+ * @param knowledgeContent - Knowledge content to write
+ */
+export async function triggerKnowledgeCollection(changeId, knowledgeContent) {
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const knowledgePath = path.join(zhuanspecDir, 'knowledge', 'best-practices');
+    // Write knowledge file
+    const knowledgeFile = path.join(knowledgePath, `deviation-${changeId}.md`);
+    await FileSystemUtils.createDirectory(knowledgePath);
+    await FileSystemUtils.writeFile(knowledgeFile, knowledgeContent);
+    // Update knowledge index
+    const indexPath = path.join(zhuanspecDir, 'knowledge', 'index.md');
+    if (await FileSystemUtils.fileExists(indexPath)) {
+        let indexContent = await FileSystemUtils.readFile(indexPath);
+        // Add new entry under Best Practices section
+        const entry = `- [偏离处理经验](best-practices/deviation-${changeId}.md) — 偏离修正流程沉淀`;
+        if (!indexContent.includes(entry)) {
+            indexContent = indexContent.replace('## Best Practices\n', `## Best Practices\n${entry}\n`);
+            await FileSystemUtils.writeFile(indexPath, indexContent);
+        }
+    }
+}
+export { USER_CORRECTION_KEYWORDS } from './deviation-check.js';
+//# sourceMappingURL=deviation-handler.js.map

package/dist/core/hooks/init.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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
+ */
+interface InitHookOptions {
+    json?: boolean;
+}
+export declare function initHook(options: InitHookOptions): Promise<void>;
+export {};
+//# sourceMappingURL=init.d.ts.map