@zhuan-ai/zhuanspec 2.15.1 → 2.15.7

package/dist/cli/index.js

@@ -272,7 +272,7 @@ progressCmd
 // Progress set-phase subcommand
 progressCmd
     .command('set-phase <change-id> <phase>')
-    .description('Set phase for a change (e.g., propose, apply, review, archive)')
+    .description('Set phase for a change (idle, techDesign, propose, apply, review, archive). Workflow-entry phases (idle/techDesign/propose) auto-create the change directory if missing.')
     .action(async (changeId, phase) => {
     try {
         const progressCommand = new ProgressCommand();

package/dist/commands/accuracy.js

@@ -31,10 +31,11 @@ export class AccuracyCommand {
         if (await FileSystemUtils.fileExists(progressPath)) {
             progress = await recoverProgressJsonForWrite(progressPath);
         }
-        if (!progress || !progress.accuracy?.snapshotTimestamp) {
-            console.log('ℹ️  No accuracy snapshot found for this change.');
-            console.log('   The snapshot is created after the Apply phase completes.');
-            console.log('   Make sure post-apply hook has been executed.');
+        // 兼容新旧路径：旧路径有 snapshotTimestamp，新路径有 linesAdded
+        if (!progress || (!progress.accuracy?.snapshotTimestamp && !(progress.linesAdded > 0))) {
+            console.log('ℹ️  No accuracy data found for this change.');
+            console.log('   Accuracy data is accumulated during the Apply phase.');
+            console.log('   Make sure the apply phase has produced code changes.');
             return;
         }
         // Handle --override
@@ -81,8 +82,8 @@ export class AccuracyCommand {
                     userCorrectionLines: accResult.userCorrectionLines,
                     overridden: accResult.overridden,
                 },
-                snapshot: progress.accuracy,
-                correctionEdits: progress.accuracy.correctionEdits || [],
+                snapshot: progress.accuracy ?? null,
+                correctionEdits: progress.accuracy?.correctionEdits || [],
             }, null, 2));
         }
         else {
@@ -96,12 +97,12 @@ export class AccuracyCommand {
             }
             console.log(`  AI产出:      ${accResult.aiTotalLines} 行`);
             console.log(`  用户纠正:    ${accResult.userCorrectionLines} 行`);
-            if (progress.accuracy.snapshotTimestamp) {
+            if (progress.accuracy?.snapshotTimestamp) {
                 console.log(`  快照时间:    ${progress.accuracy.snapshotTimestamp}`);
             }
             console.log('');
             // Show per-file correction details
-            const edits = progress.accuracy.correctionEdits || [];
+            const edits = progress.accuracy?.correctionEdits || [];
             if (edits.length > 0) {
                 console.log('📝 纠正明细:');
                 const byFile = new Map();

package/dist/commands/progress.d.ts

@@ -32,6 +32,10 @@ export declare class ProgressCommand {
     /**
      * Set phase for a change
      * Usage: zhuanspec progress set-phase <change-id> <phase>
+     *
+     * Workflow-entry phases (idle/techDesign/propose) auto-create the change
+     * directory if it does not exist; later phases (apply/review/archive)
+     * require the directory to already exist to avoid typo-creating ghost dirs.
      */
     setPhase(changeId: string, phase: string): Promise<void>;
     /**

package/dist/commands/progress.js

@@ -350,19 +350,30 @@ export class ProgressCommand {
     /**
      * Set phase for a change
      * Usage: zhuanspec progress set-phase <change-id> <phase>
+     *
+     * Workflow-entry phases (idle/techDesign/propose) auto-create the change
+     * directory if it does not exist; later phases (apply/review/archive)
+     * require the directory to already exist to avoid typo-creating ghost dirs.
      */
     async setPhase(changeId, phase) {
+        // Validate phase first (fail fast on user typos so we don't surface
+        // misleading "Change not found" errors when the real issue is the phase name).
+        // Match case-insensitively but keep the canonical casing from PHASE_ORDER
+        // (e.g. user input 'techdesign' / 'TECHDESIGN' / 'techDesign' all map to 'techDesign').
+        const normalizedPhase = PHASE_ORDER.find(p => p.toLowerCase() === phase.toLowerCase());
+        if (!normalizedPhase) {
+            throw new Error(`Invalid phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+        }
         const cwd = resolveZhuanSpecRoot();
         const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
-        if (!await FileSystemUtils.directoryExists(changeDir)) {
+        const dirExists = await FileSystemUtils.directoryExists(changeDir);
+        // Workflow-entry phases may create the change directory; later phases must not.
+        const ENTRY_PHASES = ['idle', 'techDesign', 'propose'];
+        if (!dirExists && !ENTRY_PHASES.includes(normalizedPhase)) {
             throw new Error(`Change '${changeId}' not found`);
         }
-        // Validate phase
-        const normalizedPhase = phase.toLowerCase();
-        if (!PHASE_ORDER.includes(normalizedPhase)) {
-            throw new Error(`Invalid phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
-        }
-        // Update progress.json
+        // Update progress.json (initializeProgress creates metrics/ recursively,
+        // which also creates the change directory itself when missing).
         await initializeProgress(changeId, normalizedPhase);
         // Read and display result
         const progressPath = path.join(changeDir, 'metrics', 'progress.json');
@@ -405,6 +416,29 @@ export class ProgressCommand {
         catch {
             // ignore log append errors
         }
+        // Write correctionContext to progress.json (替代 snapshot 的精准归因标记)
+        // 此后 record-progress(post-tool) 检测到 correctionContext.active=true 时，
+        // 代码变更行数不再累加到 linesAdded，改为累加到 accuracy.userCorrectionLines
+        try {
+            const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+            if (await FileSystemUtils.fileExists(progressPath)) {
+                const raw = await FileSystemUtils.readFile(progressPath);
+                const progress = JSON.parse(raw);
+                const now = new Date();
+                progress.correctionContext = {
+                    active: true,
+                    resolvedAt: now.toISOString(),
+                    path: options?.path || 'A',
+                    expiresAt: new Date(now.getTime() + 30 * 60 * 1000).toISOString(),
+                    phase: progress.phase || 'apply',
+                };
+                progress.lastUpdatedAt = now.toISOString();
+                await fs.writeFile(progressPath, JSON.stringify(progress, null, 2), 'utf-8');
+            }
+        }
+        catch {
+            // gracef衰退化 — correctionContext 写入失败不阻断主流程
+        }
         // Optionally mark askedPitfallSaved=true in progress.json
         if (options?.markPitfallSaved) {
             const progressPath = path.join(changeDir, 'metrics', 'progress.json');

package/dist/commands/review.js

@@ -61,8 +61,10 @@ export class ReviewCommand {
         catch (err) {
             console.warn(`⚠️ Failed to update progress.phase to 'review': ${err instanceof Error ? err.message : String(err)}`);
         }
-        // Accuracy snapshot 补救：若 apply 未走 post-apply hook（如手动 /zhuanspec:review）导致快照缺失，
-        // 在进入 review 的那一刻以 progress.linesAdded 作为 AI 基线衱5一份，避免首次准确率数据丢失。
+        // Accuracy snapshot 兜底补救：若 apply 未走 post-apply hook（如手动 /zhuanspec:review）
+        // 导致快照缺失，在进入 review 的那一刻以 progress.linesAdded 作为 AI 基线补一份。
+        // NOTE: correctionContext 精准归因上线后，新 change 不再依赖此快照；
+        // 保留仅用于向后兼容已有 snapshotTimestamp 的旧 change 数据。
         try {
             const created = await ensureAccuracySnapshot(changeDir);
             if (created) {

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

@@ -62,8 +62,8 @@ export async function runCollectKnowledge(filePath) {
     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/` 对应目录';
+        ? '参考 `zhuanspec/knowledge/` 下已有文件的格式（统一 Front Matter + 三类分目录）'
+        : '将写入 `zhuanspec/knowledge/troubleshooting/`、`best-practices/` 或 `implicit-conventions/` 对应目录（仅此三类）';
     // Phase-specific capture focus to avoid duplicate entries across apply and archive
     const phaseGuide = phase === 'archive'
         ? [
@@ -92,7 +92,8 @@ export async function runCollectKnowledge(filePath) {
         '询问方式：',
         '> "这次改动是否值得记录为项目知识？（回复是/否）"',
         '',
-        `用户确认后，用 Write 工具写入知识文件，${knowledgeRef}。`,
+        `用户确认后，**必须调用 \`@skill:zhuanspec:knowledge\` （模式 A）** 完成写入，由 skill 统一完成分类决策树、去重扫描、Front Matter 模板套用、index.md 更新。`,
+        `**禁止绕过 skill 直接 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**；${knowledgeRef}。`,
         '如果本次只是常规代码修改，忽略此提示即可。',
     ].join('\n');
     return {

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

@@ -60,6 +60,13 @@ const USER_CORRECTION_KEYWORDS = [
     'not what i meant', 'not what i wanted', 'redo this', 'redo that',
     // 补强：严谨性/边界/精度相关（英文）
     'not rigorous', 'edge case', 'loses precision', 'not precise',
+    // 补强：建议/优化类（语气较委婉的纠偏，避免单字"应该"/"优化"误触发）
+    '应该用', '应该按', '应该先', '应该走', '本应', '其实应该',
+    '优化一下', '优化下', '这里能优化', '需要优化', '可以优化',
+    '这块优化', '这段优化', '能不能优化',
+    // English（建议/优化类）
+    'should use', 'should follow', 'optimize this', 'needs optimization',
+    'can be optimized', 'better to',
 ];
 // Edit intent keywords — bilingual, for Apply phase scope check
 const EDIT_INTENT_KEYWORDS = [

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

@@ -50,6 +50,8 @@ export async function executePostApply(changeDir, repoRoot) {
     if (!deviationResult.detected) {
         try {
             // 2a. Snapshot AI baseline before review triggers (accuracy metric)
+            // NOTE: 此快照调用对新的 correctionContext 机制已非必须（精准归因由 resolve-correction
+            // → correctionContext → record-progress 三角完成），保留仅用于向后兼容旧 change 数据。
             await triggerAccuracySnapshot(changeDir);
             console.log('Post-apply: Triggering automatic review...');
             execSync(`zhuanspec review`, {

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

@@ -31,12 +31,11 @@ async function runPostArchiveHook(archivedChange) {
     else {
         await FileSystemUtils.writeFile(indexPath, `# Knowledge Index\n\n## Archive Log\n${line}\n`);
     }
-    // 2. Collect change knowledge (extract decisions, best practices, implicit conventions)
+    // 2. Collect change knowledge (extract best practices, implicit conventions)
+    // 注意：知识库只保留三类目录 troubleshooting / best-practices / implicit-conventions，
+    // 原“决策类”内容合并进 best-practices；踩坑类走 zhuanspec:knowledge skill 单独沉淀。
     console.log(chalk.gray('  → 提取设计文档中的知识记录...'));
     const knowledgeResult = await collectChangeKnowledge(zhuanspecDir, archivedChange, knowledgeDir);
-    if (knowledgeResult.decisions > 0) {
-        console.log(chalk.gray(`    - 决策记录：${knowledgeResult.decisions} 条`));
-    }
     if (knowledgeResult.bestPractices > 0) {
         console.log(chalk.gray(`    - 最佳实践：${knowledgeResult.bestPractices} 条`));
     }
@@ -49,13 +48,12 @@ async function runPostArchiveHook(archivedChange) {
     if (tempFilesCleaned > 0) {
         console.log(chalk.gray(`    - 已清理：${tempFilesCleaned} 个`));
     }
-    const totalEntries = knowledgeResult.decisions + knowledgeResult.bestPractices + knowledgeResult.implicitConventions;
+    const totalEntries = knowledgeResult.bestPractices + knowledgeResult.implicitConventions;
     console.log(chalk.green(`✅ 知识收集完成：共 ${totalEntries} 条记录`));
     return {
         continue: true,
-        systemMessage: `Post-archive: knowledge updated for ${archivedChange}, ${knowledgeResult.decisions} decisions, ${knowledgeResult.bestPractices} best practices, ${knowledgeResult.implicitConventions} implicit conventions, ${tempFilesCleaned} temp files cleaned`,
+        systemMessage: `Post-archive: knowledge updated for ${archivedChange}, ${knowledgeResult.bestPractices} best practices, ${knowledgeResult.implicitConventions} implicit conventions, ${tempFilesCleaned} temp files cleaned`,
         hookSpecificOutput: {
-            decisionsCollected: knowledgeResult.decisions,
             bestPracticesCollected: knowledgeResult.bestPractices,
             implicitConventionsCollected: knowledgeResult.implicitConventions,
             tempFilesCleaned,
@@ -68,7 +66,6 @@ async function runPostArchiveHook(archivedChange) {
  */
 async function collectChangeKnowledge(zhuanspecDir, archivedChange, knowledgeDir) {
     const result = {
-        decisions: 0,
         bestPractices: 0,
         implicitConventions: 0,
     };
@@ -115,21 +112,19 @@ async function collectChangeKnowledge(zhuanspecDir, archivedChange, knowledgeDir
         return result;
     }
     try {
-        // Create knowledge subdirectories
-        const decisionsDir = path.join(knowledgeDir, 'decisions');
+        // Create knowledge subdirectories（仅三类：best-practices / implicit-conventions / troubleshooting；
+        // troubleshooting 由 zhuanspec:knowledge skill 单独写入，此处不做归档提取）
         const bestPracticesDir = path.join(knowledgeDir, 'best-practices');
         const implicitConventionsDir = path.join(knowledgeDir, 'implicit-conventions');
-        await FileSystemUtils.createDirectory(decisionsDir);
         await FileSystemUtils.createDirectory(bestPracticesDir);
         await FileSystemUtils.createDirectory(implicitConventionsDir);
         // Define regex patterns for each knowledge type (Chinese and English)
+        // 原“决策类”关键字统一归入 best-practices
         const patterns = {
-            decisions: /^##\s+(决策|Decision|技术决策|架构决策)[\s\S]*?(?=^##[^#]|$)/gm,
-            bestPractices: /^##\s+(最佳实践|Best\s+Practice|Best\s+Practices|推荐做法|建议|注意事项)[\s\S]*?(?=^##[^#]|$)/gm,
+            bestPractices: /^##\s+(最佳实践|Best\s+Practice|Best\s+Practices|推荐做法|建议|注意事项|决策|Decision|技术决策|架构决策)[\s\S]*?(?=^##[^#]|$)/gm,
             implicitConventions: /^##\s+(隐式约定|Implicit\s+Convention|默认行为|约定|惯例|约定事项)[\s\S]*?(?=^##[^#]|$)/gm,
         };
         const targetDirs = {
-            decisions: decisionsDir,
             bestPractices: bestPracticesDir,
             implicitConventions: implicitConventionsDir,
         };
@@ -147,9 +142,7 @@ async function collectChangeKnowledge(zhuanspecDir, archivedChange, knowledgeDir
                 const timestamp = getBeijingTimeForFilename();
                 const fileName = `${archivedChange}-${type}-${timestamp}.md`;
                 const filePath = path.join(targetDirs[type], fileName);
-                const typeLabel = type === 'decisions' ? 'Decision Records' :
-                    type === 'bestPractices' ? 'Best Practices' :
-                        'Implicit Conventions';
+                const typeLabel = type === 'bestPractices' ? 'Best Practices' : 'Implicit Conventions';
                 const doc = `# ${typeLabel} from ${archivedChange}
 
 Extracted on: ${getBeijingTime()}

package/dist/core/hooks/record-progress.d.ts

@@ -204,10 +204,30 @@ export interface CorrectionEditRecord {
     filePath: string;
     editLines: number;
     source: 'ai' | 'user';
-    strategy: 'L1' | 'L2' | 'L3';
+    strategy: 'L1' | 'L2' | 'L3' | 'correction-context';
     agentType?: string;
     timestamp: string;
 }
+/**
+ * 纠偏上下文标记 — 替代 accuracy snapshot 的精准归因机制。
+ *
+ * 由 resolve-correction CLI 在用户选择纠偏路径后写入 progress.json，
+ * 由 record-progress(post-tool) 在每次 Write/Edit 时消费：
+ *   active=true → 行数进 userCorrectionLines（不进 linesAdded）
+ *
+ * 自动过期：
+ *   - TTL 30 分钟（expiresAt）
+ *   - 或 phase 切换时清除
+ *
+ * 设计意图：用"事中标记"替代"事后快照"，消除对 apply→review 时机依赖。
+ */
+export interface CorrectionContext {
+    active: boolean;
+    resolvedAt: string;
+    path: 'A' | 'B' | 'C' | 'D';
+    expiresAt: string;
+    phase: string;
+}
 export interface ProgressData {
     changeId: string;
     sessionId: string;
@@ -250,6 +270,7 @@ export interface ProgressData {
     }>;
     lastEvent?: string;
     accuracy?: AccuracyData;
+    correctionContext?: CorrectionContext;
 }
 export declare function recordProgressHook(options: RecordProgressOptions): Promise<void>;
 /**

package/dist/core/hooks/record-progress.js

@@ -11,7 +11,7 @@ import { promises as fsPromises, existsSync, readFileSync, unlinkSync } from 'fs
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { PHASE_ORDER } from '../../utils/phase-utils.js';
 import { resolveZhuanSpecRoot } from '../../utils/resolve-root.js';
-import { isCodeFile, determineEditSource, accumulateUserCorrection } from '../metrics/code-accuracy.js';
+import { isCodeFile } from '../metrics/code-accuracy.js';
 import { detectHookHost, sanitizeCodexEnvelope } from '../../utils/hook-host.js';
 const fs = fsPromises;
 /**
@@ -313,13 +313,23 @@ function isProposalFile(filePath, changePath) {
 }
 /**
  * Generate a brief summary of proposal file changes from tool input
+ * 兑底不同工具的字段名：
+ *   Write → content（完整文件内容）
+ *   Edit  → new_string（替换后的片段）
+ *   MultiEdit → edits[0].new_string（取首项作为摘要）
  */
 function generateProposalChangeSummary(toolInput) {
     const content = typeof toolInput.content === 'string' ? toolInput.content : '';
-    if (!content)
+    const newString = typeof toolInput.new_string === 'string' ? toolInput.new_string : '';
+    const edits = Array.isArray(toolInput.edits)
+        ? toolInput.edits
+        : [];
+    const firstEditNewString = edits.length > 0 && typeof edits[0]?.new_string === 'string' ? edits[0].new_string : '';
+    const text = content || newString || firstEditNewString;
+    if (!text)
         return 'File modified';
     // Extract first meaningful line as summary
-    const lines = content.split('\n').filter(l => l.trim().length > 0);
+    const lines = text.split('\n').filter(l => l.trim().length > 0);
     if (lines.length === 0)
         return 'File modified';
     const firstLine = lines[0].trim();
@@ -380,6 +390,19 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
                 if (progress.accuracy.userCorrectionLines === undefined)
                     progress.accuracy.userCorrectionLines = 0;
             }
+            // Correction context recovery: check TTL expiration
+            if (progress.correctionContext) {
+                if (progress.correctionContext.active && progress.correctionContext.expiresAt) {
+                    const expiresAt = new Date(progress.correctionContext.expiresAt).getTime();
+                    if (Date.now() > expiresAt) {
+                        progress.correctionContext.active = false;
+                    }
+                }
+                // Auto-clear on phase change (context belongs to the phase it was created in)
+                if (progress.correctionContext.active && progress.correctionContext.phase !== progress.phase) {
+                    progress.correctionContext.active = false;
+                }
+            }
             progress.stats = progress.stats || {
                 tokenUsageTotal: 0,
                 contextLoad: 0,
@@ -483,7 +506,7 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
     progress.currentNode = process.env.ZHUANSPEC_CURRENT_NODE || phase;
     progress.currentTask = currentTask || progress.currentTask;
     progress.toolCalls.push(toolCall);
-    const WRITE_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit']);
+    const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
     if (filePath && WRITE_TOOLS.has(toolName) && !progress.filesModified.includes(filePath)) {
         // Exclude ZhuanSpec internal files (spec/metrics/doc files inside zhuanspec/ dir)
         const absFilePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
@@ -494,11 +517,27 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
     }
     // Detect proposal file changes and record them
     const changePath = path.join(zhuanspecDir, 'changes', changeId);
-    const WRITE_EDIT_TOOLS = new Set(['Write', 'Edit']);
+    const WRITE_EDIT_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
     if (filePath && WRITE_EDIT_TOOLS.has(toolName) && isProposalFile(filePath, changePath)) {
         const relativeProposalPath = path.relative(changePath, path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath));
-        const linesContent = typeof toolInput.content === 'string' ? toolInput.content : '';
-        const contentLines = linesContent ? linesContent.split('\n').length : 0;
+        // 提案文件变更行数：按工具类型取不同字段，避免 Edit/MultiEdit 全记为 0
+        let contentLines = 0;
+        if (toolName === 'Write') {
+            const c = typeof toolInput.content === 'string' ? toolInput.content : '';
+            contentLines = c ? c.split('\n').length : 0;
+        }
+        else if (toolName === 'Edit') {
+            const ns = typeof toolInput.new_string === 'string' ? toolInput.new_string : '';
+            const os = typeof toolInput.old_string === 'string' ? toolInput.old_string : '';
+            contentLines = Math.max(ns ? ns.split('\n').length : 0, os ? os.split('\n').length : 0);
+        }
+        else if (toolName === 'MultiEdit' && Array.isArray(toolInput.edits)) {
+            for (const ed of toolInput.edits) {
+                const ns = ed?.new_string ? ed.new_string.split('\n').length : 0;
+                const os = ed?.old_string ? ed.old_string.split('\n').length : 0;
+                contentLines += Math.max(ns, os);
+            }
+        }
         const record = {
             changeRecordId: `pc-${Date.now()}`,
             timestamp,
@@ -529,27 +568,125 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
         }
         progress.proposalChanges.push(record);
     }
-    // Try to estimate lines from content
-    // 仅统计代码白名单文件，避免 .md/.json/.yml 等非代码文件污染 linesAdded。
-    // accuracy 快照基线 (snapshotAiBaseline) 直接读 progress.linesAdded，因此必须在累计阶段就过滤。
-    const content = stdinData.tool_input?.content;
+    // === 行数分账：correctionContext 精准归因（替代 snapshot 机制） ===
+    // 核心逻辑：
+    //   correctionContext.active=true  → 纠偏上下文内，行数进 userCorrectionLines
+    //   correctionContext.active=false → 正常 AI 产出，行数进 linesAdded
+    //
+    // 兑底：.pending-correction 文件存在也视同“纠偏中”，解决并行 Bash(resolve-correction)
+    // 与 Edit 的竞态（Edit 先完成时 correctionContext 尚未写入）。
+    const pendingMarkerPath = path.join(changeDir, '.pending-correction');
+    const pendingExists = existsSync(pendingMarkerPath);
+    // 不同工具的变更文本字段不同：
+    //   Write → tool_input.content（完整文件内容）
+    //   Edit  → tool_input.new_string 与 tool_input.old_string
+    //   MultiEdit → tool_input.edits[] 每项含 old_string / new_string
+    const toolInputContent = stdinData.tool_input?.content;
+    const toolInputNewString = stdinData.tool_input?.new_string;
+    const toolInputOldString = stdinData.tool_input?.old_string;
+    const toolInputEdits = stdinData.tool_input?.edits;
+    // 按工具类型计算本次变更涉及的行数
+    let changeLines = 0;
+    let contentSource = 'none';
+    if (toolName === 'Write') {
+        if (toolInputContent) {
+            changeLines = toolInputContent.split('\n').length;
+            contentSource = 'content';
+        }
+    }
+    else if (toolName === 'Edit') {
+        const newLines = toolInputNewString ? toolInputNewString.split('\n').length : 0;
+        const oldLines = toolInputOldString ? toolInputOldString.split('\n').length : 0;
+        // 取 max(new, old)：体现本次编辑触及的代码量，兼容纯新增/纯删除/替换
+        changeLines = Math.max(newLines, oldLines);
+        contentSource = (toolInputNewString || toolInputOldString) ? 'new_string' : 'none';
+    }
+    else if (toolName === 'MultiEdit' && Array.isArray(toolInputEdits)) {
+        for (const edit of toolInputEdits) {
+            const newLines = edit?.new_string ? edit.new_string.split('\n').length : 0;
+            const oldLines = edit?.old_string ? edit.old_string.split('\n').length : 0;
+            changeLines += Math.max(newLines, oldLines);
+        }
+        contentSource = toolInputEdits.length > 0 ? 'edits[]' : 'none';
+    }
     let estimatedLines = 0;
-    if (content && filePath && isCodeFile(filePath)) {
-        const lines = content.split('\n').length;
-        if (toolName === 'Write') {
-            progress.linesAdded += lines;
-            estimatedLines = lines;
+    const inCorrectionContext = !!(progress.correctionContext?.active) || pendingExists;
+    // === 调试日志：在 changeDir 下写 .correction-debug.log，方便排查“为什么没记录上” ===
+    const correctionDebugLog = (branch, addedTo, delta) => {
+        try {
+            const debugPath = path.join(changeDir, '.correction-debug.log');
+            const ccActive = !!(progress.correctionContext?.active);
+            const ccPath = progress.correctionContext?.path;
+            const ccExpiresAt = progress.correctionContext?.expiresAt;
+            const ccPhase = progress.correctionContext?.phase;
+            const isCode = !!(filePath && isCodeFile(filePath));
+            const entry = {
+                ts: getBeijingTime(),
+                tool: toolName,
+                file: filePath || null,
+                isCodeFile: isCode,
+                contentSource,
+                changeLines,
+                pendingExists,
+                correctionContext: progress.correctionContext
+                    ? { active: ccActive, path: ccPath, expiresAt: ccExpiresAt, phase: ccPhase, currentPhase: progress.phase }
+                    : null,
+                inCorrectionContext,
+                branch,
+                addedTo,
+                delta,
+                accuracy: {
+                    userCorrectionLines: progress.accuracy?.userCorrectionLines ?? 0,
+                    linesAdded: progress.linesAdded,
+                },
+            };
+            void fs.appendFile(debugPath, JSON.stringify(entry) + '\n', 'utf-8').catch(() => { });
         }
-        else if (toolName === 'Edit') {
-            progress.linesAdded += 1;
-            estimatedLines = 1;
+        catch {
+            // 日志失败不阻断主流程
+        }
+    };
+    if (changeLines > 0 && filePath && isCodeFile(filePath)) {
+        estimatedLines = changeLines;
+        if (inCorrectionContext) {
+            // 纠偏上下文：行数计入 userCorrectionLines，不进 linesAdded
+            if (!progress.accuracy) {
+                progress.accuracy = {
+                    aiLinesAdded: 0, aiLinesModified: 0, aiTotalLines: 0,
+                    userCorrectionLines: 0, accuracyRate: 1.0,
+                    correctionEdits: [],
+                };
+            }
+            progress.accuracy.userCorrectionLines = (progress.accuracy.userCorrectionLines || 0) + changeLines;
+            progress.accuracy.correctionEdits = progress.accuracy.correctionEdits || [];
+            progress.accuracy.correctionEdits.push({
+                filePath,
+                editLines: changeLines,
+                source: 'user',
+                strategy: 'correction-context',
+                agentType: progress.correctionContext?.path,
+                timestamp,
+            });
+            correctionDebugLog(`${toolName}/correction`, 'userCorrectionLines', changeLines);
+        }
+        else {
+            // 正常 AI 产出
+            progress.linesAdded += changeLines;
+            correctionDebugLog(`${toolName}/normal`, 'linesAdded', changeLines);
         }
     }
-    // Accuracy tracking: accumulate user correction lines after snapshot
-    const snapshotExists = !!(progress.accuracy?.snapshotTimestamp);
-    if (isCodeFile(filePath) && snapshotExists && WRITE_EDIT_TOOLS.has(toolName) && estimatedLines > 0) {
-        const result = determineEditSource(phase, snapshotExists, stdinData);
-        accumulateUserCorrection(progress, estimatedLines, filePath, result.source, result.strategy, result.agentType);
+    else {
+        // 未进入计量分支：记录原因（非代码文件 / 字段缺失 / 非写入工具）
+        if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+            const reason = !filePath
+                ? 'no-file-path'
+                : !isCodeFile(filePath)
+                    ? 'non-code-file'
+                    : changeLines === 0
+                        ? `empty-${contentSource}`
+                        : 'unknown';
+            correctionDebugLog(`skipped/${reason}`, 'skipped', 0);
+        }
     }
     const tokenUsageFromEnv = Number(process.env.ZHUANSPEC_TOKEN_USAGE || 0);
     const contextLoadFromEnv = Number(process.env.ZHUANSPEC_CONTEXT_LOAD || 0);

package/dist/core/hooks/summarize.js

@@ -245,18 +245,34 @@ async function runSummarize() {
             .map((c, i) => `  ${i + 1}. ${c.promptPreview || '(no preview)'}`)
             .join('\n');
         pitfallAdditionalContext = [
-            '## ⚠️ ZhuanSpec 沉淀询问（收尾必做）',
+            '## ⚠️ ZhuanSpec 知识沉淀询问（收尾必做）',
             '',
-            `本轮会话发生过 ${n} 次用户纠偏，请在收尾响应中**必须**调用 \`askUserQuestion\` 以二选一方式询问用户：`,
-            '  - 是，沉淀到 `zhuanspec/knowledge/troubleshooting/<timestamp>-<slug>.md`',
-            '  - 否，本次不沉淀',
+            `本轮会话发生过 ${n} 次用户纠偏且尚未沉淀，必须按以下顺序处理（严禁跳步，严禁自行 Write 知识文件）：`,
             '',
-            '**纠偏记录摘要（最近 3 条）：**',
+            '### 必须执行的步骤',
+            '',
+            `1. **用 askUserQuestion 询问用户**（二选一）：`,
+            '   - header: "踩坑沉淀"',
+            `   - question: "本轮 Apply 阶段发生过 ${n} 次用户纠偏，是否沉淀为项目知识？"`,
+            '   - 选项 1: "是，沉淀"',
+            '   - 选项 2: "否，跳过"',
+            '',
+            `2. **用户选"是"**：**必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\`** （或等价的 \`/zhuanspec:knowledge\` slash command 并在交互中选择模式 B）完成沉淀。`,
+            `   - change-id 值为 \`${changeId}\``,
+            '   - **禁止直接 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**，禁止自行判定分类或文件名格式；所有写入由 skill 统一执行。',
+            '   - skill 将自动完成：读取 .correction-log → 分类决策树 → 去重扫描 → 套用统一 Front Matter → 写入对应分类目录 → 更新 index.md → 标记 resolve-correction。',
+            '',
+            `3. **用户选"否"**：运行 \`zhuanspec progress resolve-correction ${changeId} --mark-pitfall-saved\` 标记已处理，不写入任何知识文件。`,
+            '',
+            '### 纠偏记录摘要（最近 3 条 promptPreview）',
             previews || '  (none)',
             '',
-            '用户回答后，请将结果记到 progress.json 的 `askedPitfallSaved` 字段（可通过 CLI 或直接写入），避免重复询问。',
+            '### 红线提示',
+            '- 禁止绕过 skill 直接 Write/Edit 知识文件（等同于绕过质量门禁）。',
+            '- 禁止新建 decisions/ 或三类目录以外的分类。',
+            '- skill 模式 B 完成后会自动写入 askedPitfallSaved=true，无需人工重复调用 CLI。',
         ].join('\n');
-        systemMessage += `\n⚠️ 检测到 ${n} 次用户纠偏未沉淀，请按下方指令调用 askUserQuestion。\n`;
+        systemMessage += `\n⚠️ 检测到 ${n} 次用户纠偏未沉淀——请按上方说明调 askUserQuestion，用户选是后必须调用 @skill:zhuanspec:knowledge 而非自行 Write。\n`;
     }
     return {
         continue: true,

package/dist/core/init.js

@@ -564,17 +564,19 @@ export class InitCommand {
         if (!(await FileSystemUtils.fileExists(indexPath))) {
             const knowledgeIndexContent = `# Knowledge Index
 
+本项目知识库仅保留三类目录：踩坑、最佳实践、隐式约定。所有写入必须经 \`@skill:zhuanspec:knowledge\` 统一完成。
+
 ## Troubleshooting
 
-<!-- Entries will be added by collect-knowledge hook -->
+<!-- 踩坑 / bug / 错误做法 / 陷阱规避，由 zhuanspec:knowledge skill 统一写入 -->
 
 ## Best Practices
 
-<!-- Project-specific best practices -->
+<!-- 可复用的最佳实践 / 设计决策落地，由 zhuanspec:knowledge skill 统一写入 -->
 
 ## Implicit Conventions
 
-<!-- Conventions discovered during implementation -->
+<!-- 隐式约定 / 默认行为 / 团队惯例，由 zhuanspec:knowledge skill 统一写入 -->
 `;
             await FileSystemUtils.writeFile(indexPath, knowledgeIndexContent);
         }

package/dist/core/metrics/code-accuracy.d.ts

@@ -37,15 +37,18 @@ export declare function snapshotAiBaseline(progress: ProgressData, changeDir: st
  */
 export declare function ensureAccuracySnapshot(changeDir: string): Promise<boolean>;
 /**
- * 快照后用户纠正行数累计
+ * 用户纠正行数累计（legacy——新代码优先用 record-progress.ts 内联的 correctionContext 逻辑）。
+ *
+ * 保留此函数用于向后兼容（旧 post-apply/review 路径仍可调用）。
+ *
  * @param progress - progress.json 数据
  * @param editLines - 本次 Edit 操作的变更行数
  * @param filePath - 文件路径（用于过滤）
  * @param source - 'ai' | 'user'
- * @param strategy - 判定策略 'L1' | 'L2' | 'L3'
+ * @param strategy - 判定策略 'L1' | 'L2' | 'L3' | 'correction-context'
  * @param agentType - 可选 agent 类型
  */
-export declare function accumulateUserCorrection(progress: ProgressData, editLines: number, filePath: string, source: 'ai' | 'user', strategy: 'L1' | 'L2' | 'L3', agentType?: string): void;
+export declare function accumulateUserCorrection(progress: ProgressData, editLines: number, filePath: string, source: 'ai' | 'user', strategy: 'L1' | 'L2' | 'L3' | 'correction-context', agentType?: string): void;
 export interface AccuracyResult {
     rate: number;
     rateRaw: number;
@@ -54,8 +57,14 @@ export interface AccuracyResult {
     overridden: boolean;
 }
 /**
- * 计算首次代码准确率
- * rate = 1 - (userCorrectionLines / aiTotalLines)，clamp 到 [0, 1]
+ * 计算首次代码准确率。
+ *
+ * 新的精准归因模型（基于 correctionContext）：
+ *   aiTotalLines = progress.linesAdded（正常 AI 产出，不含纠偏行数）
+ *   userCorrectionLines = progress.accuracy.userCorrectionLines（纠偏上下文内累计）
+ *   rate = 1 - (userCorrectionLines / aiTotalLines)，clamp 到 [0, 1]
+ *
+ * 向后兼容：若 accuracy 中存在 snapshot 基线（旧数据），优先用旧字段计算。
  */
 export declare function computeAccuracy(progress: ProgressData): AccuracyResult;
 export interface OverrideResult {

package/dist/core/metrics/code-accuracy.js

@@ -51,12 +51,13 @@ export async function snapshotAiBaseline(progress, changeDir) {
         aiLinesAdded,
         aiLinesModified,
         aiTotalLines,
-        userCorrectionLines: 0,
-        accuracyRate: 1.0, // 初始为100%，快照时无纠正
+        // 保留已有纠正数据（correctionContext 机制可能在快照前已累积），而非硬编码为 0
+        userCorrectionLines: progress.accuracy?.userCorrectionLines || 0,
+        accuracyRate: 1.0,
         accuracyRateRaw: undefined,
         lastComputedAt: undefined,
-        overrideHistory: [],
-        correctionEdits: [],
+        overrideHistory: progress.accuracy?.overrideHistory || [],
+        correctionEdits: progress.accuracy?.correctionEdits || [],
     };
     progress.accuracy = accuracy;
     // 写入独立的 accuracy.json
@@ -113,22 +114,36 @@ export async function ensureAccuracySnapshot(changeDir) {
 // 用户纠正行数累计
 // ============================================================
 /**
- * 快照后用户纠正行数累计
+ * 用户纠正行数累计（legacy——新代码优先用 record-progress.ts 内联的 correctionContext 逻辑）。
+ *
+ * 保留此函数用于向后兼容（旧 post-apply/review 路径仍可调用）。
+ *
  * @param progress - progress.json 数据
  * @param editLines - 本次 Edit 操作的变更行数
  * @param filePath - 文件路径（用于过滤）
  * @param source - 'ai' | 'user'
- * @param strategy - 判定策略 'L1' | 'L2' | 'L3'
+ * @param strategy - 判定策略 'L1' | 'L2' | 'L3' | 'correction-context'
  * @param agentType - 可选 agent 类型
  */
 export function accumulateUserCorrection(progress, editLines, filePath, source, strategy, agentType) {
-    // 快照不存在 → 不累计纠正
-    if (!progress.accuracy?.snapshotTimestamp)
+    // 新路径：correctionContext 存在时直接允许
+    const isCorrectionContext = !!(progress.correctionContext?.active);
+    const isLegacySnapshot = !!(progress.accuracy?.snapshotTimestamp);
+    // 既无快照也无 correctionContext → 不累计纠正
+    if (!isCorrectionContext && !isLegacySnapshot)
         return;
     // 非代码文件 → 不累计纠正
     if (!isCodeFile(filePath))
         return;
-    // 仅 source=user 且快照已建立才累计
+    // 确保 accuracy 结构存在
+    if (!progress.accuracy) {
+        progress.accuracy = {
+            aiLinesAdded: 0, aiLinesModified: 0, aiTotalLines: 0,
+            userCorrectionLines: 0, accuracyRate: 1.0,
+            correctionEdits: [],
+        };
+    }
+    // 仅 source=user 时累计
     if (source === 'user') {
         if (progress.accuracy.userCorrectionLines === undefined) {
             progress.accuracy.userCorrectionLines = 0;
@@ -150,20 +165,37 @@ export function accumulateUserCorrection(progress, editLines, filePath, source,
     progress.accuracy.correctionEdits.push(record);
 }
 /**
- * 计算首次代码准确率
- * rate = 1 - (userCorrectionLines / aiTotalLines)，clamp 到 [0, 1]
+ * 计算首次代码准确率。
+ *
+ * 新的精准归因模型（基于 correctionContext）：
+ *   aiTotalLines = progress.linesAdded（正常 AI 产出，不含纠偏行数）
+ *   userCorrectionLines = progress.accuracy.userCorrectionLines（纠偏上下文内累计）
+ *   rate = 1 - (userCorrectionLines / aiTotalLines)，clamp 到 [0, 1]
+ *
+ * 向后兼容：若 accuracy 中存在 snapshot 基线（旧数据），优先用旧字段计算。
  */
 export function computeAccuracy(progress) {
     const accuracy = progress.accuracy;
-    if (!accuracy) {
-        return { rate: 1.0, rateRaw: 1.0, aiTotalLines: 0, userCorrectionLines: 0, overridden: false };
+    // 向后兼容：旧快照/旧数据路径（有 aiTotalLines 数据即可走旧路径）
+    if (accuracy?.aiTotalLines && accuracy.aiTotalLines > 0) {
+        const aiTotal = accuracy.aiTotalLines || 0;
+        const correction = accuracy.userCorrectionLines || 0;
+        const rateRaw = aiTotal > 0
+            ? Math.max(0, Math.min(1, 1 - correction / aiTotal))
+            : 1.0;
+        const hasOverride = !!(accuracy.overrideHistory && accuracy.overrideHistory.length > 0);
+        const rate = hasOverride
+            ? accuracy.overrideHistory[accuracy.overrideHistory.length - 1].overriddenRate
+            : rateRaw;
+        return { rate, rateRaw, aiTotalLines: aiTotal, userCorrectionLines: correction, overridden: hasOverride };
     }
-    const aiTotal = accuracy.aiTotalLines || 0;
-    const correction = accuracy.userCorrectionLines || 0;
+    // 新路径：基于 correctionContext 的精准归因
+    const aiTotal = progress.linesAdded || 0;
+    const correction = accuracy?.userCorrectionLines || 0;
     const rateRaw = aiTotal > 0
         ? Math.max(0, Math.min(1, 1 - correction / aiTotal))
         : 1.0;
-    const hasOverride = !!(accuracy.overrideHistory && accuracy.overrideHistory.length > 0);
+    const hasOverride = !!(accuracy?.overrideHistory && accuracy.overrideHistory.length > 0);
     const rate = hasOverride
         ? accuracy.overrideHistory[accuracy.overrideHistory.length - 1].overriddenRate
         : rateRaw;

package/dist/core/templates/slash-command-templates.js

@@ -584,7 +584,9 @@ ${baseGuardrails}
   * 条件 2：任务类型是否适合 TDD？判定依据是**是否存在可测试行为**，与技术栈/前后端无关。适合（后端业务逻辑/接口实现/复杂查询，以及前端组件交互/Hooks/表单校验/utils/services 等可测行为）→ \`tddApplyAgent\`；不适合（DDL/配置/DTO/ES索引/Mapper XML/前端纯静态展示）→ 降级为 \`applyAgent\`
   * 决策记录必须注入 subagent prompt 并写入任务报告（Agent 类型/标注情况/任务类型/TDD 适用性）
 - **Rules 和 Knowledge 注入**：编排 Agent MUST 在每个 subagent prompt 中注入 Rules（根据 @skill）和 Knowledge（踩坑警告、最佳实践）。
-- **偏差处理**：PreToolUse Hook 检测到提案范围外修改时弹出选项式交互（更新提案/Bug修复豁免/取消）。3次偏差后强制更新提案。`;
+- **偏差处理**：PreToolUse Hook 检测到提案范围外修改时弹出选项式交互（更新提案/Bug修复豁免/取消）。3次偏差后强制更新提案。
+- **⚠️ 纠偏处理（红线，禁止委派 subagent）**：当 \`progress.json\` 中 \`correctionContext.active === true\` 时，主 agent **必须亲自处理所有代码修改**，**严禁**将纠偏任务分发给 subagent（applyAgent/tddApplyAgent）。原因：(1) 纠偏代码修改必须走主 agent 的 PostToolUse hook 才能正确计入 \`userCorrectionLines\`；(2) subagent 无法感知纠偏上下文，可能扩大修改范围。违反此约束将导致准确率数据丢失。
+- **correctionContext 写入时序**：\`resolve-correction\` CLI 写入 \`correctionContext\` 后，主 agent 必须在**修改任何代码之前**确认标记已写入（检查 progress.json 中 \`correctionContext.active === true\`），确保后续的 PostToolUse hook 能将修改行数路由到 \`userCorrectionLines\`。`;
 const applyReferences = `**参考**
 - 如果在实施过程中需要提案的额外上下文，请使用 \`zhuanspec show <id> --json --deltas-only\`。`;
 const archiveSteps = `**前置检查**：
@@ -754,6 +756,26 @@ const reviewGuardrails = `${baseGuardrails}\n- **门禁审查阶段**：review
   - 轨道 4 产物 \`closure-check-result.json\` 必须由 AI 实际扫描代码后写入，禁止伪造 \`overallStatus = PASS\`。
 - **Schema 版本**：新生成的 \`code-review-result.json\` / \`unit-test-result.json\` / \`closure-check-result.json\` 必须包含 \`"schemaVersion": 2\` 字段以启用 Skill 真实性硬校验；缺失或 < 2 时 CLI 会按历史数据豁免并打 ⚠️ 警告，禁止借 legacy 通道规避校验。`;
 const reviewSteps = `**步骤**
+0. **⚠️ 纠偏沉淀优先检查（Phase 切换前强制执行）**：
+   - 读取 \`zhuanspec/changes/<change-id>/metrics/progress.json\`，检查以下两个字段：
+     - \`corrections\` 数组是否存在且有元素（\`length > 0\`）
+     - \`askedPitfallSaved\` 字段是否为 \`true\`
+   - **如果满足条件（corrections 非空 且 askedPitfallSaved !== true）**：
+     - **立即调用 \`AskUserQuestion\` 工具**，以二选一方式询问用户：
+       \`\`\`
+       header: "踩坑沉淀"
+       question: "本轮 Apply 阶段发生过 N 次用户纠偏（N 为 corrections 数组的实际长度，请列出最近 3 条 promptPreview 摘要），是否沉淀为项目知识？"
+       选项 1: "是，沉淀"
+       选项 2: "否，跳过"
+       \`\`\`
+     - **用户选择"是"时**：
+       1. **必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\`**（或等价的 \`/zhuanspec:knowledge\` slash command 并在交互中选择模式 B）来完成沉淀
+       2. 本 skill 将自动完成：读取 \`.correction-log\` → 分类决策树归入 \`troubleshooting/\` / \`best-practices/\` / \`implicit-conventions/\` → 去重扫描 → 套用统一 Front Matter → 写入知识文件 → 更新 \`knowledge/index.md\` → 运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\`
+       3. **红线**：**禁止主 agent 自行使用 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**，禁止自行判定分类或文件名格式；禁止新建 \`decisions/\` 或三类目录以外的分类。
+     - **用户选择"否"时**：
+       - 运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\` 标记已处理，不写入任何知识文件
+   - **如果不满足条件（无纠偏或已沉淀）**：直接进入下一步
+
 1. **切换 Phase 到 review（第一步，必须立即执行）**：
    - 如果此提示已包含特定的变更 ID，请使用该值；否则运行 \`zhuanspec list\` 显示活跃变更并询问用户要审查哪个
    - **必须立即运行**：\`zhuanspec progress set-phase <change-id> review\`
@@ -858,62 +880,125 @@ const reviewReferences = `**参考**
 - \`generate-mockito-unit-test\` Skill 结果由 AI 写入 \`unit-test-result.json\`（必须登记 \`newTestsGenerated\` 或 \`skipReason\`）
 - \`code-review-expert\` Skill 结果由 AI 写入 \`code-review-result.json\`（必须登记 \`skillReportPath\`，指向 Skill 生成的 \`doc/code-review-*.md\` 报告）
 - 轨道 4 闭环检查结果由 AI 写入 \`closure-check-result.json\`，要求 \`overallStatus = PASS\` 且 \`skeletonCodeCount = 0\``;
-const knowledgeGuardrails = `${baseGuardrails}\n- **知识管理阶段**：knowledge 命令用于管理项目级知识库（最佳实践、陷阱、隐式约定）。
+const knowledgeGuardrails = `${baseGuardrails}
+- **知识管理阶段**：knowledge 命令用于管理项目级知识库。**只保留三类目录**：\`troubleshooting/\`（踩坑/bug/错误做法）、\`best-practices/\`（可复用的最佳实践、设计决策落地）、\`implicit-conventions/\`（隐式约定、默认行为、团队惯例）。**禁止新建其他分类目录**（如 decisions/、architecture/ 等）。
 - **跨变更积累**：知识不绑定单个变更，是长期积累的项目资产。
+- **入口收口（红线）**：所有写入 \`zhuanspec/knowledge/\` 的动作都必须通过本 skill 完成。
+  - Stop hook / review 步骤 0 检出 \`corrections.length > 0 && askedPitfallSaved !== true\` 且用户确认沉淀时，主 agent **只能调用本 skill（模式 B）** 来写入，严禁直接使用 Write/Edit 创建 knowledge 文件，严禁跳过分类决策树，严禁自拟文件名格式。
+  - PostToolUse collect-knowledge hook 的提示同理——用户确认后必须调用本 skill，而非自由 Write。
+  - 违反此红线等同于绕过质量门禁。
+- **Front Matter 强制**：每篇知识文件必须包含统一前置元信息（发现时间 / 来源变更 / 关键词 / 来源 / 背景 / 问题 / 解决方案 / 相关代码），与项目参考样例 \`zhuanspec/knowledge/best-practices/oms-call-pattern.md\` 格式一致。
 - **职责分离**：
-  - **CLI 自动提取**：归档时自动从变更目录（proposal.md、tasks.md、design.md、specs/*.md）提取结构化知识
-  - **AI 手动补充**：从本次会话记忆中补充无法自动提取的知识（如隐式约定发现、对话中的关键决策）`;
+  - **CLI 自动提取**（归档阶段 post-archive）：从变更目录 design.md/proposal.md/tasks.md/specs 抽取结构化知识。CLI 的"决策类"输出归并到 \`best-practices/\`，不再写入 \`decisions/\`。
+  - **AI 手动补充**（本 skill 模式 A）：从会话记忆中补充无法自动提取的知识。
+  - **纠偏沉淀**（本 skill 模式 B）：对接 apply 阶段 \`.correction-log\` 的纠偏记录。`;
 const knowledgeSteps = `**步骤**
-1. **选择操作类型**：
-   - 查看：列出当前知识库内容
-   - 添加：从会话记忆手动添加新的知识条目（CLI 无法自动提取的内容）
-   - 搜索：按关键词搜索相关知识
-
-2. **查看知识库**：
-   - 运行 \`ls zhuanspec/knowledge/\` 查看目录结构
-   - 阅读 \`zhuanspec/knowledge/index.md\` 查看索引
-   - 使用 \`cat zhuanspec/knowledge/decisions/*.md\` 查看决策记录
-   - 使用 \`cat zhuanspec/knowledge/best-practices/*.md\` 查看最佳实践
-
-3. **从会话添加知识条目**（手动补充 CLI 无法自动提取的内容）：
-   - 选择分类目录（decisions/best-practices/implicit-conventions）
-   - 基于本次会话中的发现，使用模板创建条目：
-     \`\`\`markdown
-     # [标题]
 
-     **发现时间**: [YYYY-MM-DD]
-     **来源变更**: [change-id]（可选）
-     **关键词**: [关键词列表]
-     **来源**: 会话记忆（AI 补充）
+本 skill 支持两种模式，触发方式不同、流程不同：
+- **模式 A（manual）**：用户手动触发 \`/zhuanspec:knowledge\`，或显式传参 \`--mode=manual\`；用于查看、搜索、从会话记忆补充知识。
+- **模式 B（correction）**：由 Stop hook / review 步骤 0 / PostToolUse collect-knowledge hook 引导调用，或显式传参 \`--correction <change-id>\` / \`--mode=correction\`；用于将 apply 阶段的纠偏记录规范化沉淀为踩坑/约定/最佳实践。
 
-     ## 背景
+## 通用资产：分类决策树（两种模式共用）
 
-     [发现该知识点的背景描述 - 来自本次对话]
+对每条待沉淀内容，按以下决策树**逐项**判定分类（必须显式回答三问）：
+1. 这是"做错了/踩坑/bug/错误做法/需要规避的陷阱"吗？→ \`troubleshooting/\`
+2. 这是"某个默认行为 / 隐式约定 / 框架默认值 / 团队未明文但必须遵守的惯例"吗？→ \`implicit-conventions/\`
+3. 这是"可复用的最佳实践 / 成功经验 / 设计决策落地方案（如异步调用模式、批量处理范式）"吗？→ \`best-practices/\`
 
-     ## 问题/经验
+同一条内容若同时命中多类，按"踩坑 > 约定 > 最佳实践"优先级归入**更靠前**的一类。禁止新建 decisions/ 或其他目录。
 
-     [具体问题或经验描述 - CLI 无法自动提取的内容]
+## 通用资产：统一 Front Matter 模板（两种模式共用）
 
-     ## 解决方案/建议
+\`\`\`markdown
+# <简短主题>
 
-     [解决方案或最佳实践建议]
+**发现时间**: <YYYY-MM-DD>
+**来源变更**: <change-id 或留空>
+**关键词**: <逗号分隔 5-10 个检索关键词>
+**来源**: <"用户纠偏" | "会话记忆（AI 补充）" | "技术方案对比" | 具体来源描述>
 
-     ## 相关代码
+## 背景
 
-     - \`[相关文件路径]\` - [说明]
-     \`\`\`
-   - **优先补充**：
-     - 对话中发现但未写入文档的隐式约定
-     - 调试过程中发现的陷阱
-     - 团队特有的最佳实践
-
-4. **搜索知识**：
-   - 使用 \`rg "[关键词]" zhuanspec/knowledge/\` 进行搜索
-   - 结合变更上下文进行知识推荐`;
+<为什么出现、在什么场景下发现>
+
+## 问题 / 经验
+
+<具体问题描述 或 可复用经验的触发条件>
+
+## 解决方案 / 建议
+
+<正确做法 / 最佳模式 / 规避方式；给出错误示例 vs 正确示例（代码块）更佳>
+
+## 相关代码
+
+- \`<相对路径>\` - <说明>
+\`\`\`
+
+文件命名：\`<YYYYMMDD>-<kebab-slug>.md\`；slug 由主题生成（例：\`20260506-apply-enum-hardcoding.md\`），不得使用随机字符串。
+
+---
+
+## 模式 A：手动补充 / 查看 / 搜索
+
+1. **选择子操作**：查看 / 搜索 / 添加（三选一）。
+2. **查看**：
+   - \`ls zhuanspec/knowledge/\` 查看三类目录
+   - \`cat zhuanspec/knowledge/index.md\` 查看索引
+   - \`cat zhuanspec/knowledge/best-practices/*.md\` / \`troubleshooting/\` / \`implicit-conventions/\` 查看具体条目
+3. **搜索**：
+   - \`rg "<关键词>" zhuanspec/knowledge/\`
+   - 结合 \`index.md\` 关键词段快速锁定
+4. **从会话添加**：
+   - 先按**分类决策树**判定归属目录；**禁止**凭习惯写到 decisions/
+   - 先 \`rg "<主关键词>" zhuanspec/knowledge/<category>/\` 做去重扫描：若命中高度相似条目 → 在已有文件追加 \`## 追加：<日期>\` 章节，不新建文件
+   - 否则新建 \`zhuanspec/knowledge/<category>/<YYYYMMDD>-<kebab-slug>.md\`，严格套用上面的 Front Matter 模板
+   - **同步更新** \`zhuanspec/knowledge/index.md\`：在对应分区（\`## Troubleshooting\` / \`## Best Practices\` / \`## Implicit Conventions\`）追加一行 \`- [<标题>](<category>/<文件名>) — <关键词摘要>\`
+
+---
+
+## 模式 B：纠偏沉淀（Apply 阶段收尾 / Review 步骤 0 / PostToolUse 触发）
+
+1. **确认 change-id**：
+   - 优先使用入参 \`--correction <change-id>\`
+   - 否则读取 \`zhuanspec/changes/*/metrics/progress.json\`，定位 \`corrections.length > 0 && askedPitfallSaved !== true\` 的 change-id
+   - 同时存在多个时，调用 \`askUserQuestion\` 让用户二选一，严禁随意选择
+2. **读取原始纠偏记录**（两份必须都读）：
+   - \`zhuanspec/changes/<change-id>/.correction-log\`（JSONL，每行含 \`ts\` / \`event\` / \`promptPreview\` / \`reason?\`）
+   - \`zhuanspec/changes/<change-id>/metrics/progress.json\` 的 \`corrections\` 数组
+3. **用户二次确认（强制）**：
+   - 将最近 3 条 promptPreview 摘要打印给用户
+   - 调 \`askUserQuestion\`：\`是，沉淀 / 否，跳过\`
+   - 用户选"否"时，直接跳到步骤 7 只做 resolve-correction --mark-pitfall-saved，不写入任何文件
+4. **逐条分类**：对每条 correction 走上面的「分类决策树」，得到 \`<category>\`。
+5. **去重扫描**：对每条（含其关键词）先执行 \`rg "<主关键词>" zhuanspec/knowledge/<category>/\`：
+   - 命中相似条目 → 在已有文件追加 \`## 追加：<日期> — <change-id>\` 章节
+   - 未命中 → 新建 \`zhuanspec/knowledge/<category>/<YYYYMMDD>-<kebab-slug>.md\`
+6. **写入文件**（严格使用统一 Front Matter 模板）：
+   - \`**来源**\` 字段固定写 \`用户纠偏（change: <change-id>）\`
+   - \`**来源变更**\` 字段固定写 \`<change-id>\`
+   - \`## 背景\` / \`## 问题 / 经验\` / \`## 解决方案 / 建议\` 必须基于 \`.correction-log\` 原始 promptPreview 与当次会话上下文还原，**禁止编造**
+   - 同步更新 \`zhuanspec/knowledge/index.md\` 对应分区
+7. **标记已处理（强制收尾，无论步骤 3 用户选是/否）**：
+   - 运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\`
+   - 确认 \`progress.json.askedPitfallSaved === true\`，避免下次 Stop hook 重复询问
+8. **输出摘要**：列出本轮新建 / 追加的知识文件路径 + index.md 更新行；报告 \`<change-id>\` 的纠偏沉淀已完成。
+
+---
+
+## 硬约束回顾
+- 所有写入 knowledge 目录的动作只能经本 skill 完成；禁止主 agent 或其他流程自行 Write。
+- 只能写入三类目录之一，禁止新建 decisions/。
+- 文件名、Front Matter、index.md 更新三者缺一不可。
+- 模式 B 必须以 \`resolve-correction --mark-pitfall-saved\` 收尾。`;
 const knowledgeReferences = `**参考**
-- CLI 归档时自动从变更目录提取结构化知识（design.md 中的决策、proposal.md 中的注意事项等）
-- 本 skill 用于从会话记忆中补充无法自动提取的知识
-- 知识库目录结构：decisions（决策记录）、best-practices（最佳实践）、implicit-conventions（隐式约定）`;
+- 参考样例（格式基准）：项目 \`zhuanspec/knowledge/best-practices/oms-call-pattern.md\`、\`zhuanspec/knowledge/troubleshooting/20260506-apply-pitfalls.md\`、\`zhuanspec/knowledge/implicit-conventions/outbound-cis-inventory-lock.md\`
+- 知识库目录结构（仅此三类）：
+  - \`troubleshooting/\` — 踩坑、bug、错误做法、陷阱规避
+  - \`best-practices/\` — 可复用的最佳实践、设计决策落地
+  - \`implicit-conventions/\` — 隐式约定、默认行为、团队惯例
+- CLI 归档时自动从变更目录提取知识（post-archive hook）；所有"决策类"输出归入 \`best-practices/\`
+- 模式 B 依赖文件：\`zhuanspec/changes/<change-id>/.correction-log\`（JSONL）、\`metrics/progress.json.corrections\`
+- 模式 B 收尾命令：\`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\``;
 export const slashCommandBodies = {
     proposal: [proposalGuardrails, proposalOutputFormat, proposalSteps, proposalReferences].join('\n\n'),
     design: [designGuardrails, designSteps, designReferences].join('\n\n'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.15.1",
+  "version": "2.15.7",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -39,26 +39,6 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
-  "scripts": {
-    "lint": "eslint src/",
-    "build": "node build.js",
-    "dev": "tsc --watch",
-    "dev:cli": "pnpm build && node bin/zhuanspec.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage",
-    "test:postinstall": "node scripts/postinstall.js",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run build",
-    "postinstall": "node scripts/postinstall.js",
-    "check:pack-version": "node scripts/pack-version-check.mjs",
-    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
-    "release": "pnpm run release:ci",
-    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
-    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
-    "changeset": "changeset"
-  },
   "engines": {
     "node": ">=20.19.0"
   },
@@ -80,5 +60,23 @@
     "ora": "^8.2.0",
     "yaml": "^2.8.2",
     "zod": "^4.0.17"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/zhuanspec.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
   }
-}
+}