@zhuan-ai/zhuanspec 2.10.0 → 2.11.2

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

@@ -7,7 +7,7 @@
  * 3. Track tool calls for metrics
  */
 import path from 'path';
-import { promises as fsPromises } from 'fs';
+import { promises as fsPromises, existsSync, readFileSync, unlinkSync } from 'fs';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { PHASE_ORDER } from '../../utils/phase-utils.js';
 const fs = fsPromises;
@@ -103,6 +103,7 @@ export async function recoverProgressJsonForWrite(filePath) {
                 linesRemoved: 0,
                 deviationCount: 0,
                 deviationRecords: [],
+                proposalChanges: [],
                 reviewStats: { loopCount: 0, criticalFixes: 0, testFixes: 0, consistencyFixes: 0 },
                 phaseTransitions: [],
                 phaseDurations: [{
@@ -281,6 +282,34 @@ async function detectActiveChange(cwd, filePath) {
     candidates.sort((a, b) => b.sortKey - a.sortKey);
     return { changeId: candidates[0].changeId, phase: candidates[0].phase };
 }
+/**
+ * Check if a file path is a proposal file
+ */
+function isProposalFile(filePath, changePath) {
+    const absFilePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+    const absChangePath = path.isAbsolute(changePath) ? changePath : path.resolve(process.cwd(), changePath);
+    if (!absFilePath.startsWith(absChangePath + path.sep))
+        return false;
+    const relativePath = path.relative(absChangePath, absFilePath);
+    return ['proposal.md', 'tasks.md', 'design.md', 'test-cases.md']
+        .some(f => relativePath === f)
+        || relativePath.startsWith('specs' + path.sep);
+}
+/**
+ * Generate a brief summary of proposal file changes from tool input
+ */
+function generateProposalChangeSummary(toolInput) {
+    const content = typeof toolInput.content === 'string' ? toolInput.content : '';
+    if (!content)
+        return 'File modified';
+    // Extract first meaningful line as summary
+    const lines = content.split('\n').filter(l => l.trim().length > 0);
+    if (lines.length === 0)
+        return 'File modified';
+    const firstLine = lines[0].trim();
+    // Truncate to 120 chars
+    return firstLine.length > 120 ? firstLine.substring(0, 117) + '...' : firstLine;
+}
 async function runRecordProgress(filePath, toolName, success, stdinData) {
     const cwd = process.cwd();
     // Priority: filePath-derived > progress.json scan > environment variables
@@ -327,6 +356,7 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
             };
             progress.phaseTransitions = progress.phaseTransitions || [];
             progress.phaseDurations = progress.phaseDurations || [];
+            progress.proposalChanges = progress.proposalChanges || [];
             progress.stats = progress.stats || {
                 tokenUsageTotal: 0,
                 contextLoad: 0,
@@ -434,6 +464,43 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
             progress.filesModified.push(filePath);
         }
     }
+    // Detect proposal file changes and record them
+    const changePath = path.join(zhuanspecDir, 'changes', changeId);
+    const WRITE_EDIT_TOOLS = new Set(['Write', 'Edit']);
+    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;
+        const record = {
+            changeRecordId: `pc-${Date.now()}`,
+            timestamp,
+            phase,
+            triggeredBy: phase === 'apply' ? 'reverse-sync' : phase === 'review' ? 'review-fix' : 'manual-edit',
+            modifiedFiles: [{
+                    filePath: relativeProposalPath,
+                    changeType: toolName === 'Write' ? 'created' : 'modified',
+                    summary: generateProposalChangeSummary(toolInput),
+                    linesAdded: contentLines,
+                    linesRemoved: 0,
+                }],
+        };
+        // Read related deviation ID from temp file (cross-process communication)
+        let relatedDeviationId;
+        try {
+            const deviationIdPath = path.join(changePath, 'metrics', '.last-deviation-id');
+            if (existsSync(deviationIdPath)) {
+                relatedDeviationId = readFileSync(deviationIdPath, 'utf-8').trim();
+                unlinkSync(deviationIdPath); // consume after reading
+            }
+        }
+        catch {
+            // graceful degradation - no deviation ID available
+        }
+        if (relatedDeviationId) {
+            record.relatedDeviationId = relatedDeviationId;
+        }
+        progress.proposalChanges.push(record);
+    }
     // Try to estimate lines from content
     const content = stdinData.tool_input?.content;
     if (content) {
@@ -470,6 +537,24 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
                 progress.stats.durationMs.archive = elapsedMs;
         }
     }
+    // === Auto-count tasks from tasks.md ===
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    if (await FileSystemUtils.fileExists(tasksPath)) {
+        try {
+            const tasksContent = await FileSystemUtils.readFile(tasksPath);
+            const totalTaskMatches = tasksContent.match(/^- \[[ x]\] .+$/gm) || [];
+            const completedTaskMatches = tasksContent.match(/^- \[x\] .+$/gm) || [];
+            progress.totalTasks = totalTaskMatches.length;
+            // Update completedTasks array with completed task descriptions
+            const completedDescriptions = completedTaskMatches.map(t => t.replace(/^- \[x\] /, '').trim());
+            if (completedDescriptions.length > 0) {
+                progress.completedTasks = completedDescriptions;
+            }
+        }
+        catch {
+            // Ignore tasks.md read errors
+        }
+    }
     // Write progress file atomically
     await atomicWriteJson(progressPath, progress);
     // Also update tool_calls.json separately for detailed tracking
@@ -569,6 +654,7 @@ function createNewProgress(changeId) {
             consistencyFixes: 0,
         },
         phaseTransitions: [],
+        proposalChanges: [],
         phaseDurations: [{
                 phase: initialPhase,
                 startedAt: getBeijingTime(),
@@ -617,6 +703,7 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
             progress.filesModified = progress.filesModified || [];
             progress.completedTasks = progress.completedTasks || [];
             progress.deviationRecords = progress.deviationRecords || [];
+            progress.proposalChanges = progress.proposalChanges || [];
             progress.phaseTransitions = progress.phaseTransitions || [];
             progress.phaseDurations = progress.phaseDurations || [];
             progress.reviewStats = progress.reviewStats || {

package/dist/core/hooks/review-hooks.js

@@ -13,6 +13,7 @@
  * - Controls loop count (max 3)
  */
 import path from 'path';
+import fs from 'fs';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { getBeijingTime } from './record-progress.js';
 // Output file paths for skill results
@@ -142,15 +143,19 @@ export async function unitTestResultCheck(changeId, skillOutput) {
     };
 }
 export async function specConsistencyResultCheck(changeId, skillOutput) {
-    const output = skillOutput || await readSkillOutput(changeId, SPEC_CONSISTENCY_OUTPUT);
+    let output = skillOutput || await readSkillOutput(changeId, SPEC_CONSISTENCY_OUTPUT);
+    // Fallback: auto-execute basic consistency analysis when no JSON exists
+    if (!output) {
+        output = await runBasicConsistencyAnalysis(changeId);
+    }
     if (!output) {
         return {
             pass: false,
             needFix: false,
             loopCount: 0,
-            metrics: { error: 'No skill output found' },
+            metrics: { error: 'No skill output found and basic analysis failed' },
             nextAction: 'stop',
-            fixPrompt: 'Spec-consistency skill output not found. Please run spec-code-consistency check first.',
+            fixPrompt: 'Spec-consistency skill output not found and basic analysis failed. Please run spec-code-consistency check first.',
         };
     }
     const loopCount = (output.loopCount || 0) + 1;
@@ -200,6 +205,169 @@ export async function specConsistencyResultCheck(changeId, skillOutput) {
     };
 }
 // ============================================================
+// Basic Consistency Analysis Fallback
+// ============================================================
+/**
+ * Run basic consistency analysis when spec-consistency-result.json is missing.
+ * Reads specs/ under the change directory, extracts Requirements/Scenarios,
+ * searches touched files for keyword matches, and writes a basic result.
+ */
+async function runBasicConsistencyAnalysis(changeId) {
+    const cwd = process.cwd();
+    const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+    const specsDir = path.join(changeDir, 'specs');
+    // Check if specs directory exists
+    if (!await FileSystemUtils.directoryExists(specsDir)) {
+        return null;
+    }
+    try {
+        const specEntries = await fs.promises.readdir(specsDir, { withFileTypes: true });
+        const allRequirements = [];
+        for (const entry of specEntries) {
+            if (!entry.isDirectory())
+                continue;
+            const specFile = path.join(specsDir, entry.name, 'spec.md');
+            if (!await FileSystemUtils.fileExists(specFile))
+                continue;
+            const content = await FileSystemUtils.readFile(specFile);
+            const lines = content.split('\n');
+            let currentSection = '';
+            let currentReq = null;
+            let reqCounter = 0;
+            let scenarioCounter = 0;
+            for (const line of lines) {
+                if (line.match(/^##\s+(ADDED|Added|\u65b0\u589e)/i))
+                    currentSection = 'ADDED';
+                else if (line.match(/^##\s+(MODIFIED|Modified|\u4fee\u6539)/i))
+                    currentSection = 'MODIFIED';
+                else if (line.match(/^##\s+(REMOVED|Removed|\u5220\u9664)/i))
+                    currentSection = 'REMOVED';
+                else if (line.match(/^###\s+(Requirement|\u9700\u6c42)[\uff1a:]/i)) {
+                    const reqName = line.replace(/^###\s+(Requirement|\u9700\u6c42)[\uff1a:]\s+/i, '').trim();
+                    if (currentSection === 'ADDED' || currentSection === 'MODIFIED') {
+                        reqCounter++;
+                        currentReq = { id: `REQ-${reqCounter}`, name: reqName, scenarios: [] };
+                        allRequirements.push(currentReq);
+                    }
+                    else {
+                        currentReq = null;
+                    }
+                }
+                else if (line.match(/^####\s+(Scenario|\u573a\u666f)[\uff1a:]/i) && currentReq) {
+                    scenarioCounter++;
+                    const scenarioDesc = line.replace(/^####\s+(Scenario|\u573a\u666f)[\uff1a:]\s+/i, '').trim();
+                    currentReq.scenarios.push({ id: `SC-${scenarioCounter}`, description: scenarioDesc });
+                }
+            }
+        }
+        if (allRequirements.length === 0) {
+            return null;
+        }
+        // Get touched files from git
+        let touchedFiles = [];
+        try {
+            const { execSync } = await import('child_process');
+            const diffOutput = execSync('git diff --name-only HEAD', {
+                cwd,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'ignore'],
+            });
+            touchedFiles = diffOutput.split('\n').map(f => f.trim()).filter(f => f.length > 0);
+            const statusOutput = execSync('git status --porcelain', {
+                cwd,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'ignore'],
+            });
+            const statusFiles = statusOutput.split('\n')
+                .map(l => l.replace(/^\s*[A-Z?]+\s+/, '').trim())
+                .filter(f => f.length > 0);
+            touchedFiles = [...new Set([...touchedFiles, ...statusFiles])];
+        }
+        catch {
+            // No git info available
+        }
+        // Build scenario mapping and check coverage
+        const mapping = [];
+        const uncoveredScenarios = [];
+        let totalScenarios = 0;
+        let coveredCount = 0;
+        for (const req of allRequirements) {
+            const scenarios = req.scenarios.length > 0
+                ? req.scenarios
+                : [{ id: `${req.id}-implicit`, description: req.name }];
+            for (const scenario of scenarios) {
+                totalScenarios++;
+                const keywords = scenario.description
+                    .toLowerCase()
+                    .split(/[\s\-_/\uff0c\u3001]+/)
+                    .filter(w => w.length > 3);
+                let found = false;
+                let matchedFile = '';
+                for (const file of touchedFiles) {
+                    const fileLower = file.toLowerCase();
+                    if (keywords.some(kw => fileLower.includes(kw))) {
+                        found = true;
+                        matchedFile = file;
+                        break;
+                    }
+                    try {
+                        const fullPath = path.isAbsolute(file) ? file : path.join(cwd, file);
+                        const fileContent = await FileSystemUtils.readFile(fullPath);
+                        if (keywords.some(kw => fileContent.toLowerCase().includes(kw))) {
+                            found = true;
+                            matchedFile = file;
+                            break;
+                        }
+                    }
+                    catch {
+                        // Skip unreadable files
+                    }
+                }
+                if (found) {
+                    coveredCount++;
+                    mapping.push({
+                        requirementId: req.id,
+                        scenarioId: scenario.id,
+                        codeFile: matchedFile,
+                        status: 'covered',
+                    });
+                }
+                else {
+                    mapping.push({
+                        requirementId: req.id,
+                        scenarioId: scenario.id,
+                        codeFile: '',
+                        status: 'missing',
+                    });
+                    uncoveredScenarios.push({
+                        requirementId: req.id,
+                        scenarioId: scenario.id,
+                        description: scenario.description,
+                    });
+                }
+            }
+        }
+        const consistencyRate = totalScenarios > 0
+            ? Math.round((coveredCount / totalScenarios) * 100)
+            : 100;
+        const result = {
+            consistencyRate,
+            totalRequirements: allRequirements.length,
+            totalScenarios,
+            coveredScenarios: coveredCount,
+            uncoveredScenarios,
+            mapping,
+            loopCount: 0,
+        };
+        // Write the result so subsequent calls can read it directly
+        await writeSkillOutput(changeId, SPEC_CONSISTENCY_OUTPUT, result);
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================
 // Helper Functions
 // ============================================================
 async function readSkillOutput(changeId, filename) {

package/dist/core/hooks/review-orchestrator.js

@@ -69,22 +69,69 @@ function generateSpecConsistencyPrompt(changeId) {
 执行 Spec-Code 一致性检查，发现未覆盖 Scenario 时启动修复循环：
 
 ## 任务目标
-验证 changeId=${changeId} 的代码实现与 Spec Requirement 一致
+验证 changeId=${changeId} 的代码实现与 Spec Scenario 语义一致。
+⚠️ 禁止用 Requirement 标题做字符串匹配，必须逐条读取 Scenario 内容做语义比对。
 
 ## 自闭环指令
-1. 解析 specs/*.md 中的所有 Requirement 和 Scenario
-2. 检查代码实现是否覆盖每个 Scenario
-3. 如果发现未覆盖，立即补充代码或更新 Spec
-4. 修复后重新检查（最多3轮）
-5. 输出 spec-consistency-result.json 报告到 zhuanspec/changes/${changeId}/review/
+
+### Step 1：解析 Spec Scenarios
+读取 zhuanspec/changes/${changeId}/specs/**/*.md，提取所有内容：
+- 每个 \`### Requirement:\` 下的每个 \`#### Scenario:\` 标题
+- Scenario 的 Given/When/Then 描述（业务语义）
+- 标记每个 Scenario 的所属 Requirement
+
+输出 Scenario 清单，格式：
+  [Requirement名] > [Scenario名]: [Given/When/Then核心语义]
+
+### Step 2：逐 Scenario 语义比对
+对每个 Scenario，在代码中找对应实现：
+
+**查找顺序**：
+1. 读取 proposal.md 的「后端改动」和「前端改动」表格，定位涉及文件
+2. 在对应文件中找与 Scenario 语义匹配的方法/逻辑：
+   - Scenario 描述「新建客户」→ 找 createCustomer 相关方法
+   - Scenario 描述「手机号去重」→ 找手机号唯一性校验逻辑
+   - Scenario 描述「租户隔离」→ 找 tenantId 过滤条件
+   - Scenario 描述「删除企微客户拒绝」→ 找 source_type 判断逻辑
+3. 验证找到的代码是否满足 Scenario 的 Then 条件
+
+**判断标准**（语义覆盖，不是字符串匹配）：
+- ✅ 覆盖：代码中存在与 Scenario Given→When→Then 对应的业务逻辑
+- ❌ 未覆盖：相关文件不存在、方法不存在、或 Then 条件未实现
+- ⚠️ 部分覆盖：正向路径实现了，异常路径未实现
+
+### Step 3：输出比对结果表格
+\`\`\`
+| Requirement | Scenario | 对应文件/方法 | 覆盖状态 | 说明 |
+|---|---|---|---|---|
+| 客户CRUD | 新建客户-成功 | CustomerDomainService#createCustomer | ✅ | - |
+| 客户CRUD | 手机号重复-拒绝 | CustomerDomainService#checkPhoneDuplicate | ✅ | - |
+| 多租户隔离 | 租户隔离查询 | CustomerEsQueryService | ❌ | 未找到tenantId过滤 |
+\`\`\`
+
+### Step 4：自闭环修复
+- 发现 ❌ 未覆盖的 Scenario → 补充对应代码实现
+- 修复后重新执行 Step 2 验证（最多3轮）
+- ⚠️ 仅修复真实遗漏，禁止把"文件存在但逻辑未实现"误报为已覆盖
+
+### Step 5：输出 spec-consistency-result.json
+路径：zhuanspec/changes/${changeId}/review/spec-consistency-result.json
 
 ## 输出格式
 {
-  "consistencyRate": number,
+  "consistencyRate": number,        // 覆盖 Scenario 数 / 总 Scenario 数
   "totalRequirements": number,
   "totalScenarios": number,
   "coveredScenarios": number,
-  "uncoveredScenarios": [...],
+  "uncoveredScenarios": [           // 真实未覆盖，非字符串匹配失败
+    {
+      "requirement": "Requirement名",
+      "scenario": "Scenario名",
+      "reason": "具体原因：方法不存在/逻辑未实现/文件缺失",
+      "suggestedFix": "建议修复方式"
+    }
+  ],
+  "partialCoverage": [...],         // 部分覆盖的 Scenario
   "loopCount": number,
   "finalStatus": "PASS" | "FAIL"
 }

package/dist/core/hooks/tdd-phase-hook.d.ts

@@ -0,0 +1,59 @@
+/**
+ * PostToolUse Hook - TDD Phase Tracking
+ *
+ * This hook tracks TDD workflow compliance for tasks annotated with @test-case:
+ * 1. Tracks file creation order (test files should precede implementation files)
+ * 2. Detects test execution results (RED → GREEN → REFACTOR phases)
+ * 3. Updates metrics/tdd-phases.json with current TDD status
+ */
+export type TddPhase = 'PENDING' | 'RED' | 'GREEN' | 'REFACTOR' | 'DONE';
+export interface TddTaskStatus {
+    taskId: string;
+    testCases: string[];
+    tddPhase: TddPhase;
+    testFileCreated: boolean;
+    testInitiallyFailed: boolean;
+    testFinallyPassed: boolean;
+    implFileCreated: boolean;
+    updatedAt: string;
+}
+export interface TddHookResult {
+    action: 'continue' | 'warn' | 'block';
+    message?: string;
+    updatedStatus?: TddTaskStatus;
+}
+/**
+ * Determine whether a file path looks like a test file.
+ */
+export declare function isTestFile(filePath: string): boolean;
+/**
+ * Load the persisted TDD status for a given task.
+ * Returns `null` when no status has been recorded yet.
+ */
+export declare function loadTddStatus(changePath: string, taskId: string): Promise<TddTaskStatus | null>;
+/**
+ * Persist the TDD status for a task into `metrics/tdd-phases.json`.
+ * Creates the file (and parent directories) when they do not exist.
+ */
+export declare function saveTddStatus(changePath: string, taskId: string, status: TddTaskStatus): Promise<void>;
+/**
+ * Determine TDD phase transition based on the current status and latest event.
+ *
+ * Transition rules:
+ *   PENDING  → RED        when a test file is created
+ *   RED      → GREEN      when tests pass after initial failure is recorded
+ *   GREEN    → REFACTOR   when an implementation file is modified / created after tests pass
+ *   REFACTOR → DONE       when tests still pass after refactoring
+ */
+export declare function detectTddPhaseTransition(currentStatus: TddTaskStatus, toolName: string, filePath: string, toolOutput?: string): TddTaskStatus;
+/**
+ * TDD Phase Hook – called after tool use to enforce TDD discipline.
+ *
+ * @param changePath  Absolute path to the current change directory
+ * @param toolName    Name of the tool just used (e.g. 'Write', 'Edit', 'Bash')
+ * @param filePath    File affected by the tool invocation
+ * @param taskId      Current task identifier (e.g. "2.1")
+ * @param toolOutput  Optional output captured from Bash executions
+ */
+export declare function tddPhaseHook(changePath: string, toolName: string, filePath: string, taskId: string, toolOutput?: string): Promise<TddHookResult>;
+//# sourceMappingURL=tdd-phase-hook.d.ts.map