@zhuan-ai/zhuanspec 2.8.0 → 2.10.0

package/dist/core/hooks/collect-knowledge.js

@@ -1,17 +1,15 @@
 /**
  * PostToolUse Hook - Collect Knowledge
  *
- * This hook runs after Write/Edit operations to:
- * 1. Detect pitfall keywords in content or conversation
- * 2. Extract and save troubleshooting knowledge
- * 3. Record implicit conventions discovered
+ * Fires after Write/Edit in Apply phase. Injects a lightweight prompt
+ * into Claude's context so the LLM can decide (with user confirmation)
+ * whether the change is worth capturing as project knowledge.
+ *
+ * Design principle: no keyword matching, no auto-save — the LLM decides.
  */
 import path from 'path';
 import { FileSystemUtils } from '../../utils/file-system.js';
-import { PITFALL_KEYWORDS, BEST_PRACTICE_KEYWORDS, IMPLICIT_CONVENTION_KEYWORDS } from './deviation-check.js';
-import { getBeijingTime, getBeijingTimeForFilename } from './record-progress.js';
 export async function collectKnowledgeHook(options) {
-    // Read stdin for Claude Code hook input
     let stdinData = {};
     try {
         const stdinContent = await readStdin();
@@ -22,22 +20,12 @@ export async function collectKnowledgeHook(options) {
     catch {
         // Ignore parse errors
     }
-    // Get content from stdin or options
-    const content = stdinData.tool_input?.content
-        || options.content
-        || '';
     const filePath = stdinData.tool_input?.file_path
         || options.file
         || '';
-    const output = await runCollectKnowledge(content, filePath);
-    if (options.json) {
-        console.log(JSON.stringify(output));
-    }
-    else {
-        if (output.systemMessage) {
-            console.log(output.systemMessage);
-        }
-    }
+    const output = await runCollectKnowledge(filePath);
+    // Always output JSON — additionalContext must reach Claude Code
+    console.log(JSON.stringify(output));
 }
 async function readStdin() {
     return new Promise((resolve) => {
@@ -48,156 +36,60 @@ async function readStdin() {
         process.stdin.on('error', () => resolve(null));
     });
 }
-async function runCollectKnowledge(content, filePath) {
+export async function runCollectKnowledge(filePath) {
     const phase = process.env.ZHUANSPEC_PHASE || 'idle';
     const changeId = process.env.ZHUANSPEC_CHANGE_ID || '';
-    // No active change → nothing to collect
-    if (!changeId || phase === 'idle') {
-        return {
-            continue: true,
-        };
+    // Only apply and archive phases trigger knowledge capture
+    // archive is the most important moment — end-of-change reflection
+    const isActivePhase = phase === 'apply' || phase === 'archive';
+    if (!changeId || !isActivePhase) {
+        return { continue: true };
     }
-    const cwd = process.cwd();
-    const zhuanspecDir = path.join(cwd, 'zhuanspec');
-    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
-    const knowledgeDir = path.join(changeDir, 'knowledge');
-    const troubleshootingDir = path.join(knowledgeDir, 'troubleshooting');
-    const bestPracticesDir = path.join(knowledgeDir, 'best-practices');
-    const implicitConventionsDir = path.join(knowledgeDir, 'implicit-conventions');
-    // Check for all keyword types
-    const contentLower = content.toLowerCase();
-    const detectedPitfalls = PITFALL_KEYWORDS.filter(kw => contentLower.includes(kw.toLowerCase()));
-    const detectedBestPractices = BEST_PRACTICE_KEYWORDS.filter(kw => contentLower.includes(kw.toLowerCase()));
-    const detectedImplicitConventions = IMPLICIT_CONVENTION_KEYWORDS.filter(kw => contentLower.includes(kw.toLowerCase()));
-    // If no keywords detected, return early
-    if (detectedPitfalls.length === 0 && detectedBestPractices.length === 0 && detectedImplicitConventions.length === 0) {
-        return {
-            continue: true,
-        };
-    }
-    // Create directories as needed
-    await FileSystemUtils.createDirectory(knowledgeDir);
-    const collectedTypes = [];
-    let totalEntries = 0;
-    // Process pitfalls
-    if (detectedPitfalls.length > 0) {
-        await FileSystemUtils.createDirectory(troubleshootingDir);
-        const pitfall = extractKnowledgeContext(content, filePath, detectedPitfalls, 'troubleshooting');
-        const timestamp = getBeijingTimeForFilename();
-        const filename = `pitfall-${timestamp}.md`;
-        const pitfallPath = path.join(troubleshootingDir, filename);
-        await FileSystemUtils.writeFile(pitfallPath, formatKnowledgeRecord(pitfall));
-        updateKnowledgeIndex(knowledgeDir, 'troubleshooting', pitfall.title, filename);
-        collectedTypes.push('pitfall');
-        totalEntries++;
-    }
-    // Process best practices
-    if (detectedBestPractices.length > 0) {
-        await FileSystemUtils.createDirectory(bestPracticesDir);
-        const bestPractice = extractKnowledgeContext(content, filePath, detectedBestPractices, 'best_practice');
-        const timestamp = getBeijingTimeForFilename();
-        const filename = `best-practice-${timestamp}.md`;
-        const bpPath = path.join(bestPracticesDir, filename);
-        await FileSystemUtils.writeFile(bpPath, formatKnowledgeRecord(bestPractice));
-        updateKnowledgeIndex(knowledgeDir, 'best-practices', bestPractice.title, filename);
-        collectedTypes.push('best practice');
-        totalEntries++;
-    }
-    // Process implicit conventions
-    if (detectedImplicitConventions.length > 0) {
-        await FileSystemUtils.createDirectory(implicitConventionsDir);
-        const implicitConvention = extractKnowledgeContext(content, filePath, detectedImplicitConventions, 'implicit_contract');
-        const timestamp = getBeijingTimeForFilename();
-        const filename = `implicit-convention-${timestamp}.md`;
-        const icPath = path.join(implicitConventionsDir, filename);
-        await FileSystemUtils.writeFile(icPath, formatKnowledgeRecord(implicitConvention));
-        updateKnowledgeIndex(knowledgeDir, 'implicit-conventions', implicitConvention.title, filename);
-        collectedTypes.push('implicit convention');
-        totalEntries++;
+    // Only skip writes to knowledge/ itself to prevent capture loops
+    // Archive phase writes to zhuanspec/changes/archive/... should still trigger
+    if (filePath.includes('zhuanspec/knowledge/')) {
+        return { continue: true };
     }
+    const cwd = process.cwd();
+    const knowledgeDir = path.join(cwd, 'zhuanspec', 'knowledge');
+    const hasKnowledge = await FileSystemUtils.directoryExists(knowledgeDir);
+    const knowledgeRef = hasKnowledge
+        ? '参考 `zhuanspec/knowledge/` 下已有文件的格式'
+        : '保存到 `zhuanspec/knowledge/troubleshooting/`、`best-practices/` 或 `implicit-conventions/` 对应目录';
+    // Phase-specific capture focus to avoid duplicate entries across apply and archive
+    const phaseGuide = phase === 'archive'
+        ? [
+            '**当前处于归档阶段** — 重点捕获整个变更过程的回顾性总结：',
+            '- 贯穿整个实施过程的模式或规律',
+            '- 事后才意识到的设计决策或取舍',
+            '- apply 阶段**未曾记录**的新洞察',
+            '',
+            '⚠️ **去重要求**：保存前先读取 `zhuanspec/knowledge/` 下已有文件，',
+            '若本次内容与已有记录高度重叠，跳过或仅追加补充内容，不要重复新建文件。',
+        ]
+        : [
+            '**当前处于实施阶段** — 重点捕获即时发现的问题：',
+            '- 修复了一个非显而易见的 bug 或绕过了一个坑',
+            '- 发现了一个隐式约定或框架默认行为',
+            '- 总结了一个值得复用的最佳实践',
+            '',
+            '⚠️ **去重要求**：保存前先读取 `zhuanspec/knowledge/` 下已有文件，',
+            '若已有同类记录，跳过或追加到已有文件，不要重复新建。',
+        ];
+    const additionalContext = [
+        `💡 **知识沉淀提示**（针对刚才对 \`${filePath || '该文件'}\` 的改动）`,
+        '',
+        ...phaseGuide,
+        '',
+        '询问方式：',
+        '> "这次改动是否值得记录为项目知识？（回复是/否）"',
+        '',
+        `用户确认后，用 Write 工具写入知识文件，${knowledgeRef}。`,
+        '如果本次只是常规代码修改，忽略此提示即可。',
+    ].join('\n');
     return {
         continue: true,
-        systemMessage: `📝 Knowledge detected and recorded: ${collectedTypes.join(', ')}`,
-        hookSpecificOutput: {
-            knowledgeCollected: `${totalEntries} entries`,
-            pitfallDetected: detectedPitfalls.length > 0,
-        },
+        hookSpecificOutput: { additionalContext },
     };
 }
-async function updateKnowledgeIndex(knowledgeDir, section, title, filename) {
-    const indexPath = path.join(knowledgeDir, 'index.md');
-    const subdir = section === 'troubleshooting' ? 'troubleshooting' :
-        section === 'best-practices' ? 'best-practices' :
-            'implicit-conventions';
-    const indexEntry = `\n- [${title}](${subdir}/${filename}) - ${getBeijingTime()}\n`;
-    if (await FileSystemUtils.fileExists(indexPath)) {
-        const existingIndex = await FileSystemUtils.readFile(indexPath);
-        // Find section or create it
-        const sectionHeader = `## ${section}`;
-        if (existingIndex.includes(sectionHeader)) {
-            // Append to existing section
-            const updated = existingIndex.replace(sectionHeader, `${sectionHeader}${indexEntry}`);
-            await FileSystemUtils.writeFile(indexPath, updated);
-        }
-        else {
-            // Add new section
-            await FileSystemUtils.writeFile(indexPath, `${existingIndex}\n\n${sectionHeader}${indexEntry}`);
-        }
-    }
-    else {
-        await FileSystemUtils.writeFile(indexPath, `# Knowledge Index\n\n## troubleshooting\n\n## best-practices\n\n## implicit-conventions\n${indexEntry}`);
-    }
-}
-function extractKnowledgeContext(content, filePath, keywords, type) {
-    // Extract relevant context around keywords
-    const lines = content.split('\n');
-    const relevantLines = [];
-    for (let i = 0; i < lines.length; i++) {
-        const lineLower = lines[i].toLowerCase();
-        if (keywords.some(kw => lineLower.includes(kw.toLowerCase()))) {
-            // Include surrounding context (3 lines before and after)
-            const start = Math.max(0, i - 3);
-            const end = Math.min(lines.length, i + 4);
-            for (let j = start; j < end; j++) {
-                relevantLines.push(lines[j]);
-            }
-            relevantLines.push('---');
-        }
-    }
-    // Generate title from first keyword found
-    const firstKeyword = keywords[0];
-    const typeLabel = type === 'troubleshooting' ? 'Issue' :
-        type === 'best_practice' ? 'Best Practice' :
-            'Convention';
-    const title = `${typeLabel}: ${firstKeyword} in ${filePath}`;
-    return {
-        type,
-        title,
-        content: relevantLines.join('\n'),
-        source: filePath,
-        timestamp: getBeijingTime(),
-        tags: keywords,
-    };
-}
-function formatKnowledgeRecord(entry) {
-    return `# ${entry.title}
-
-**Type**: ${entry.type}
-**Source**: ${entry.source}
-**Timestamp**: ${entry.timestamp}
-**Tags**: ${entry.tags.join(', ')}
-
-## Context
-
-${entry.content}
-
-## Resolution
-
-[To be filled when resolved]
-
-## Lessons Learned
-
-[To be extracted after resolution]
-`;
-}
 //# sourceMappingURL=collect-knowledge.js.map

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

@@ -35,11 +35,33 @@ const IMPLICIT_CONVENTION_KEYWORDS = [
     '默认行为', '默认配置', '默认值', '隐式规则',
     'implicit convention', 'default behavior', 'convention',
 ];
-// User correction keywords for deviation detection trigger
+// User correction/pitfall keywords — bilingual, flexible matching
 const USER_CORRECTION_KEYWORDS = [
-    '不对', '错了', '这里应该是', '应该是', '不是这样',
-    '这里不对', '改一下', '需要修改', '修改提案',
-    'wrong', 'should be', 'not right', 'need to fix',
+    // 中文纠错
+    '不对', '错了', '不是', '有问题', '有个问题', '这里有问题',
+    '这样不行', '不行', '有bug', '有Bug', '踩坑', '坑了',
+    '应该是', '应该改', '需要修改', '修改一下', '改一下',
+    '不应该', '这里错了', '你理解错了', '理解错误', '理解有误',
+    '不是这个意思', '不是这样的', '重做', '重新来', '逻辑不对',
+    '实现不对', '方向错了', '写错了', '搞错了',
+    // English corrections
+    'wrong', 'incorrect', "that's wrong", "you're wrong", 'not right',
+    'should be', 'should have been', "that's not", 'no no', 'wait no',
+    'fix this', 'this is wrong', 'this is incorrect', 'mistake', 'mistaken',
+    'broken', 'not working', "doesn't work", "doesn't seem right",
+    'pitfall', 'gotcha', 'issue here', 'problem here',
+    'actually no', 'actually wrong', 'you misunderstood', 'misunderstood',
+    'not what i meant', 'not what i wanted', 'redo this', 'redo that',
+];
+// Edit intent keywords — bilingual, for Apply phase scope check
+const EDIT_INTENT_KEYWORDS = [
+    // 中文
+    '修改', '改', '新增', '添加', '增加', '删除', '移除', '重构',
+    '优化', '更新', '替换', '重写', '实现', '完成', '做一下',
+    // English
+    'add', 'change', 'edit', 'update', 'refactor', 'remove', 'delete',
+    'replace', 'rewrite', 'implement', 'fix', 'create', 'write',
+    'modify', 'revise', 'adjust',
 ];
 export async function deviationCheckHook(options) {
     const startTime = Date.now();
@@ -65,14 +87,16 @@ export async function deviationCheckHook(options) {
     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, {
+    const hookEvent = trigger === 'post-prompt' ? 'UserPromptSubmit' : 'PreToolUse';
+    await recordHookTrigger('deviation-check', hookEvent, output.continue, {
         toolName,
         filePath,
         message: output.systemMessage,
         durationMs,
     });
-    if (options.json) {
+    // post-prompt always outputs JSON so Claude Code can read additionalContext
+    const useJson = options.json || trigger === 'post-prompt';
+    if (useJson) {
         console.log(JSON.stringify(output));
     }
     else {
@@ -98,12 +122,15 @@ 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
+    // No change bound or idle phase → allow, post-prompt silences itself to avoid noise
     if (!changeId || phase === 'idle') {
-        return {
-            continue: true,
-            systemMessage: '✓ No active ZhuanSpec change, normal workflow allowed',
-        };
+        if (trigger === 'post-prompt') {
+            return { continue: true };
+        }
+        const msg = !changeId
+            ? '✓ 当前无绑定变更，正常工作流'
+            : `✓ 变更 [${changeId}] 处于 idle 阶段，正常工作流`;
+        return { continue: true, systemMessage: msg };
     }
     const cwd = process.cwd();
     const zhuanspecDir = path.join(cwd, 'zhuanspec');
@@ -136,46 +163,51 @@ async function runDeviationCheck(filePath, trigger, promptText, _options) {
             systemMessage: '✓ Resume deviation check passed',
         };
     }
-    // Post-prompt check: catch "additional request after apply/interruption" and force reverse-sync first.
+    // Post-prompt check: inject proposal context for 2-dimension consistency check in Apply phase.
     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）',
-                        '取消修改',
-                    ],
-                },
-            };
+        // Skip if no proposal exists
+        if (!await FileSystemUtils.fileExists(proposalPath)) {
+            return { continue: true };
         }
-        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修复豁免', '取消追加需求'],
-                },
-            };
+        const lowerPrompt = promptText.toLowerCase();
+        // Detect correction/pitfall keywords
+        const correctionFound = USER_CORRECTION_KEYWORDS.some(kw => lowerPrompt.includes(kw.toLowerCase()));
+        // Detect edit intent
+        const hasEditIntent = EDIT_INTENT_KEYWORDS.some(kw => lowerPrompt.includes(kw.toLowerCase()));
+        // No action needed if purely read-only and no correction signal
+        if (!hasEditIntent && !correctionFound) {
+            return { continue: true };
+        }
+        // Load proposal for context injection
+        const proposalContent = await FileSystemUtils.readFile(proposalPath);
+        const proposalSummary = extractProposalSummary(proposalContent, 1500);
+        const reverseSyncFiles = [
+            '`proposal.md`（更新变更原因/影响范围）',
+            '`tasks.md`（新增或调整对应任务）',
+            '`specs/*/spec.md`（更新受影响的 spec 需求条目）',
+            '`design.md`（如存在，更新技术设计决策）',
+        ].join('、');
+        let additionalContext = '## ⚠️ ZhuanSpec Apply 阶段一致性检测\n\n';
+        additionalContext += `**当前变更提案摘要：**\n${proposalSummary}\n\n`;
+        additionalContext += `**处理以下用户请求前，请先做两维度一致性检测：**\n\n`;
+        additionalContext += `- **维度1（范围）**：用户请求涉及的文件/功能是否在提案中明确提及？\n`;
+        additionalContext += `  - 在提案范围内 → 正常实施\n`;
+        additionalContext += `  - **超出提案范围** → 先告知用户，执行 Reverse Sync：依次更新 ${reverseSyncFiles}，经用户确认后再实施代码\n\n`;
+        additionalContext += `- **维度2（逻辑一致性）**：用户请求的逻辑调整是否与提案设计意图一致？\n`;
+        additionalContext += `  - 一致 → 正常实施\n`;
+        additionalContext += `  - **逻辑有偏差** → 说明偏差点，同样执行 Reverse Sync 更新所有相关提案文件（${reverseSyncFiles}），经用户确认后再实施\n\n`;
+        if (correctionFound) {
+            additionalContext += `**⚠️ 检测到纠错关键词** — 用户可能遇到了问题/踩坑\n`;
+            additionalContext += `修复完成后，请主动询问用户：\n`;
+            additionalContext += `> "这个问题是否值得记录为踩坑经验，防止下次再犯？（回复是/否）"\n`;
+            additionalContext += `若用户确认，将问题描述和解决方案整理后保存到 \`zhuanspec/knowledge/troubleshooting/\` 目录下的新 .md 文件中。\n\n`;
         }
         return {
             continue: true,
-            systemMessage: '✓ Post-prompt deviation check passed',
+            systemMessage: `✓ ZhuanSpec: Apply 阶段一致性检测已注入上下文${correctionFound ? '（含踩坑沉淀提示）' : ''}`,
+            hookSpecificOutput: {
+                additionalContext,
+            },
         };
     }
     // Propose phase → block all code modifications (Iron Law 1: No Spec No Code)
@@ -287,6 +319,10 @@ ZhuanSpec Iron Law 3: Reverse Sync - When deviation is found, update proposal fi
             },
         };
     }
+    // post-prompt in non-apply phases (propose/techDesign/review/...) → silently allow
+    if (trigger === 'post-prompt') {
+        return { continue: true };
+    }
     // Default: allow
     return {
         continue: true,
@@ -295,25 +331,36 @@ ZhuanSpec Iron Law 3: Reverse Sync - When deviation is found, update proposal fi
 async function parseEstimatedChanges(proposalPath) {
     try {
         const content = await FileSystemUtils.readFile(proposalPath);
+        const seen = new Set();
         const files = [];
-        // Look for "影响范围" or "Affected code" sections
+        const addFile = (raw) => {
+            const cleaned = raw.replace(/[`'"*[\]()]/g, '').trim();
+            if (cleaned.length > 2 && !seen.has(cleaned)) {
+                seen.add(cleaned);
+                files.push(cleaned);
+            }
+        };
+        // Scan entire proposal for file paths with known extensions
+        const filePattern = /(?:^|[\s`'"([\]|])([a-zA-Z0-9_\-./]+\.(?:ts|tsx|js|jsx|java|py|go|rs|md|json|yaml|yml|sql|kt|scala|c|cpp|cs|sh|xml|html|css|scss|vue|svelte))(?:[\s`'")\]|,]|$)/gm;
+        let m;
+        while ((m = filePattern.exec(content)) !== null) {
+            addFile(m[1]);
+        }
+        // Also collect bullet-point entries under 影响范围/Affected/Impact 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')) {
+            if (/影响范围|Affected code|Affected files|Impact/i.test(line) && line.startsWith('#')) {
                 inAffectedSection = true;
                 continue;
             }
-            if (inAffectedSection && line.startsWith('##')) {
-                // End of section
+            if (inAffectedSection && line.startsWith('#')) {
                 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());
-                }
+                if (match)
+                    addFile(match[1].trim());
             }
         }
         return files;
@@ -322,6 +369,21 @@ async function parseEstimatedChanges(proposalPath) {
         return [];
     }
 }
+function extractProposalSummary(content, maxLength) {
+    const patterns = [
+        /^## (?:Summary|摘要|Overview|概述)[\s\S]*?(?=\n## |\n# |$)/im,
+        /^## (?:What Changes|变更内容|Changes|修改内容)[\s\S]*?(?=\n## |\n# |$)/im,
+        /^## (?:Impact|影响范围|Affected)[\s\S]*?(?=\n## |\n# |$)/im,
+    ];
+    const sections = [];
+    for (const pattern of patterns) {
+        const match = content.match(pattern);
+        if (match)
+            sections.push(match[0].trim());
+    }
+    const combined = sections.length > 0 ? sections.join('\n\n') : content;
+    return combined.length > maxLength ? combined.substring(0, maxLength) + '...' : combined;
+}
 async function parseCurrentTaskFiles(tasksPath, currentTask) {
     if (!currentTask) {
         return [];

package/dist/core/hooks/init.js

@@ -8,9 +8,34 @@
  */
 import path from 'path';
 import fs from 'fs';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { fileURLToPath } from 'url';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { initializeProgress, recordHookTrigger, getBeijingTime } from './record-progress.js';
 import { getCurrentPhase, getPhaseFromProgress } from '../../utils/phase-utils.js';
+const execAsync = promisify(exec);
+async function checkVersionUpdate() {
+    try {
+        const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'package.json');
+        const pkgContent = JSON.parse(await fs.promises.readFile(pkgPath, 'utf-8'));
+        const current = pkgContent.version;
+        const { stdout } = await execAsync('npm view @zhuan-ai/zhuanspec version', { timeout: 5000 });
+        const latest = stdout.trim();
+        if (!latest || !current)
+            return null;
+        const parse = (v) => v.replace(/^v/, '').split('-')[0].split('.').map(Number);
+        const [cM, cm, cp] = parse(current);
+        const [lM, lm, lp] = parse(latest);
+        const isOutdated = lM !== cM ? lM > cM : lm !== cm ? lm > cm : lp > cp;
+        if (!isOutdated)
+            return `✓ ZhuanSpec v${current} 已是最新版本，开始 happy coding 吧~`;
+        return `⚠️  ZhuanSpec 版本过旧！\n    当前版本: v${current}  →  最新版本: v${latest}\n    请执行: 1) npm i -g @zhuan-ai/zhuanspec  2) zhuanspec init（同步最新模板到本项目）`;
+    }
+    catch {
+        return null;
+    }
+}
 export async function initHook(options) {
     const startTime = Date.now();
     const output = await runInitHook(options);
@@ -226,9 +251,13 @@ async function runInitHook(_options) {
         additionalContext += `Found ${rulesFiles.length} rule files in .claude/rules: ${rulesFiles.join(', ')}\n`;
         additionalContext += `(These are loaded automatically by Claude Code system)\n\n`;
     }
+    const versionBanner = await checkVersionUpdate();
+    const finalMessage = versionBanner
+        ? versionBanner + '\n' + (systemMessage || '✓ ZhuanSpec session initialized')
+        : (systemMessage || '✓ ZhuanSpec session initialized');
     return {
         continue: true,
-        systemMessage: systemMessage || '✓ ZhuanSpec session initialized',
+        systemMessage: finalMessage,
         hookSpecificOutput: {
             additionalContext: additionalContext || undefined,
             env: {

package/dist/core/hooks/pre-archive.js

@@ -17,29 +17,28 @@ async function runPreArchiveHook(changeId) {
         return { continue: false, stopReason: 'missing-change', systemMessage: 'Missing --change for pre-archive check' };
     }
     const changeDir = path.join(process.cwd(), 'zhuanspec', 'changes', changeId);
-    const reviewPath = path.join(changeDir, 'metrics', 'review.json');
-    const testsPath = path.join(changeDir, 'metrics', 'tests.json');
-    const reviewReportPath = path.join(changeDir, 'review-report.md');
-    if (!(await FileSystemUtils.fileExists(reviewPath)) ||
-        !(await FileSystemUtils.fileExists(testsPath)) ||
+    const reviewDir = path.join(changeDir, 'review');
+    const codeReviewPath = path.join(reviewDir, 'code-review-result.json');
+    const unitTestPath = path.join(reviewDir, 'unit-test-result.json');
+    const reviewReportPath = path.join(reviewDir, 'review-report.md');
+    if (!(await FileSystemUtils.fileExists(codeReviewPath)) ||
+        !(await FileSystemUtils.fileExists(unitTestPath)) ||
         !(await FileSystemUtils.fileExists(reviewReportPath))) {
         return {
             continue: false,
             stopReason: 'review-or-tests-missing',
-            systemMessage: 'Pre-archive check failed: missing review.json/tests.json/review-report.md',
+            systemMessage: 'Pre-archive check failed: missing changes/<id>/review/code-review-result.json, unit-test-result.json, or review-report.md',
         };
     }
-    const review = JSON.parse(await FileSystemUtils.readFile(reviewPath));
-    const tests = JSON.parse(await FileSystemUtils.readFile(testsPath));
-    const reviewPassed = Boolean(review.passed);
-    const testPassed = Number(tests.failed ?? 1) === 0;
-    const specConsistencyPassed = review?.checks?.specCompliance === true;
-    const critical = Number(review?.summary?.critical ?? 0);
-    if (!reviewPassed || !testPassed || critical > 0 || !specConsistencyPassed) {
+    const codeReview = JSON.parse(await FileSystemUtils.readFile(codeReviewPath));
+    const unitTest = JSON.parse(await FileSystemUtils.readFile(unitTestPath));
+    const critical = Number(codeReview?.criticalCount ?? 0);
+    const testPassed = Boolean(unitTest?.testPassed);
+    if (critical > 0 || !testPassed) {
         return {
             continue: false,
             stopReason: 'quality-gate-failed',
-            systemMessage: `Pre-archive check failed: review=${reviewPassed}, tests=${testPassed}, specConsistency=${specConsistencyPassed}, critical=${critical}`,
+            systemMessage: `Pre-archive check failed: critical=${critical}, testPassed=${testPassed}`,
         };
     }
     return {