@zhuan-ai/zhuanspec 2.9.5 → 2.11.2

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

@@ -25,7 +25,7 @@ function generateCodeReviewPrompt(changeId) {
 1. 执行 code-review-expert skill 进行代码审查
 2. 如果发现 Critical 问题，立即修复
 3. 修复后重新检查（最多3轮）
-4. 输出 code-review-result.json 报告到 zhuanspec/.skill-outputs/${changeId}/
+4. 输出 code-review-result.json 报告到 zhuanspec/changes/${changeId}/review/
 
 ## 输出格式
 {
@@ -50,7 +50,7 @@ function generateUnitTestPrompt(changeId) {
 2. 运行单测，检查通过率和覆盖率
 3. 如果失败或不达标，立即修复
 4. 修复后重新测试（最多3轮）
-5. 输出 unit-test-result.json 报告到 zhuanspec/.skill-outputs/${changeId}/
+5. 输出 unit-test-result.json 报告到 zhuanspec/changes/${changeId}/review/
 
 ## 输出格式
 {
@@ -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/.skill-outputs/${changeId}/
+
+### 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"
 }
@@ -100,7 +147,7 @@ export async function orchestrateReview(options) {
     const { changeId } = options;
     // Ensure output directory exists
     const cwd = process.cwd();
-    const outputDir = path.join(cwd, 'zhuanspec', '.skill-outputs', changeId);
+    const outputDir = path.join(cwd, 'zhuanspec', 'changes', changeId, 'review');
     await FileSystemUtils.createDirectory(outputDir);
     return {
         codeReviewPrompt: generateCodeReviewPrompt(changeId),

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

package/dist/core/hooks/tdd-phase-hook.js

@@ -0,0 +1,313 @@
+/**
+ * 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
+ */
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { atomicWriteJson } from './record-progress.js';
+// ---------------------------------------------------------------------------
+// Test-file detection patterns
+// ---------------------------------------------------------------------------
+/** Common test-file naming patterns across languages */
+const TEST_FILE_PATTERNS = [
+    /Test\.java$/, // Java – JUnit / TestNG
+    /Tests?\.cs$/, // C# – xUnit / NUnit
+    /\.test\.[jt]sx?$/, // JS/TS – Jest / Vitest
+    /\.spec\.[jt]sx?$/, // JS/TS – Jasmine / Mocha / Vitest
+    /_test\.go$/, // Go
+    /_test\.py$/, // Python – pytest
+    /test_.*\.py$/, // Python – unittest
+    /Spec\.(?:scala|kt)$/, // Scala / Kotlin – ScalaTest / Kotest
+];
+// ---------------------------------------------------------------------------
+// Test-result detection patterns (for Bash output)
+// ---------------------------------------------------------------------------
+const TEST_FAILURE_PATTERNS = [
+    /FAIL(?:ED|URE)?/i,
+    /Tests?\s+failed/i,
+    /BUILD FAILURE/i,
+    /AssertionError/i,
+    /AssertError/i,
+    /FAILURES!/,
+    /failures:\s*[1-9]/i,
+    /errors:\s*[1-9]/i,
+    /TEST.*FAIL/i,
+];
+const TEST_SUCCESS_PATTERNS = [
+    /PASS(?:ED)?/i,
+    /Tests?\s+passed/i,
+    /BUILD SUCCESS/i,
+    /All tests passed/i,
+    /Tests:\s+\d+ passed,\s+\d+ total/i,
+    /OK \(\d+ tests?\)/i,
+    /\d+ passing/i,
+    /failures:\s*0.*errors:\s*0/i,
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Return the path to the TDD phases JSON inside a change directory.
+ */
+function tddPhasesPath(changePath) {
+    return path.join(changePath, 'metrics', 'tdd-phases.json');
+}
+/**
+ * Determine whether a file path looks like a test file.
+ */
+export function isTestFile(filePath) {
+    const basename = path.basename(filePath);
+    return TEST_FILE_PATTERNS.some((pattern) => pattern.test(basename));
+}
+/**
+ * Load the persisted TDD status for a given task.
+ * Returns `null` when no status has been recorded yet.
+ */
+export async function loadTddStatus(changePath, taskId) {
+    const jsonPath = tddPhasesPath(changePath);
+    if (!(await FileSystemUtils.fileExists(jsonPath))) {
+        return null;
+    }
+    try {
+        const content = await FileSystemUtils.readFile(jsonPath);
+        const data = JSON.parse(content);
+        return data.tasks?.[taskId] ?? null;
+    }
+    catch {
+        // Corrupted or unreadable – treat as absent
+        return 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 async function saveTddStatus(changePath, taskId, status) {
+    const jsonPath = tddPhasesPath(changePath);
+    let data = { tasks: {}, lastUpdated: '' };
+    if (await FileSystemUtils.fileExists(jsonPath)) {
+        try {
+            const content = await FileSystemUtils.readFile(jsonPath);
+            data = JSON.parse(content);
+        }
+        catch {
+            // Start fresh when the file is corrupted
+        }
+    }
+    data.tasks[taskId] = status;
+    data.lastUpdated = new Date().toISOString();
+    // Ensure the metrics directory exists
+    const metricsDir = path.dirname(jsonPath);
+    await FileSystemUtils.createDirectory(metricsDir);
+    await atomicWriteJson(jsonPath, data);
+}
+/**
+ * Detect whether a Bash tool invocation contains test-execution output
+ * and whether the tests passed or failed.
+ *
+ * Returns `'pass'`, `'fail'`, or `null` (when unable to determine).
+ */
+function detectTestResult(toolOutput) {
+    if (!toolOutput)
+        return null;
+    const hasFail = TEST_FAILURE_PATTERNS.some((p) => p.test(toolOutput));
+    const hasPass = TEST_SUCCESS_PATTERNS.some((p) => p.test(toolOutput));
+    // Failure takes precedence when both signals are present (e.g. "1 passed, 1 failed")
+    if (hasFail)
+        return 'fail';
+    if (hasPass)
+        return 'pass';
+    return null;
+}
+/**
+ * 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 function detectTddPhaseTransition(currentStatus, toolName, filePath, toolOutput) {
+    const status = { ...currentStatus, updatedAt: new Date().toISOString() };
+    const fileIsTest = isTestFile(filePath);
+    // Track file creation
+    if (fileIsTest) {
+        status.testFileCreated = true;
+    }
+    else if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+        status.implFileCreated = true;
+    }
+    // Detect test execution results (only relevant when toolName is Bash)
+    if (toolName === 'Bash') {
+        const result = detectTestResult(toolOutput);
+        switch (status.tddPhase) {
+            case 'PENDING':
+                // If tests are already running and they fail → move to RED
+                if (result === 'fail') {
+                    status.testInitiallyFailed = true;
+                    status.tddPhase = 'RED';
+                }
+                // If a test file was just created, also transition to RED
+                if (status.testFileCreated && status.tddPhase === 'PENDING') {
+                    status.tddPhase = 'RED';
+                }
+                break;
+            case 'RED':
+                if (result === 'fail') {
+                    status.testInitiallyFailed = true;
+                }
+                if (result === 'pass' && status.testInitiallyFailed) {
+                    status.testFinallyPassed = true;
+                    status.tddPhase = 'GREEN';
+                }
+                break;
+            case 'GREEN':
+                // After GREEN, any passing test run during refactor moves to REFACTOR
+                if (result === 'pass') {
+                    status.tddPhase = 'REFACTOR';
+                }
+                break;
+            case 'REFACTOR':
+                // Stays in REFACTOR; transition to DONE is handled externally
+                // when the task is marked complete.
+                if (result === 'pass') {
+                    status.tddPhase = 'DONE';
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    // Also transition PENDING → RED when a test file is created (non-Bash tool)
+    if (status.tddPhase === 'PENDING' && status.testFileCreated) {
+        status.tddPhase = 'RED';
+    }
+    return status;
+}
+/**
+ * Check whether the given task line from tasks.md contains a @test-case annotation.
+ * Returns the list of referenced TC identifiers, or an empty array.
+ */
+function parseTestCaseAnnotations(taskLine) {
+    const match = taskLine.match(/@test-case[:\s]+([^\n]+)/i);
+    if (!match)
+        return [];
+    return match[1]
+        .split(/[,\s]+/)
+        .map((tc) => tc.trim())
+        .filter(Boolean);
+}
+/**
+ * Read tasks.md and locate the line that corresponds to the given taskId.
+ * Returns `null` when the task is not found.
+ */
+async function findTaskLine(changePath, taskId) {
+    const tasksPath = path.join(changePath, 'tasks.md');
+    if (!(await FileSystemUtils.fileExists(tasksPath))) {
+        return null;
+    }
+    const content = await FileSystemUtils.readFile(tasksPath);
+    const lines = content.split('\n');
+    // Normalise taskId for comparison (e.g. "2.1" should match "2.1")
+    const normalised = taskId.trim();
+    for (let idx = 0; idx < lines.length; idx++) {
+        const line = lines[idx];
+        // Match checkbox task lines: "- [ ] 2.1 ..." or "- [x] 2.1 ..."
+        const taskMatch = line.match(/^-\s+\[[ x]\]\s+(\S+)/);
+        if (taskMatch && taskMatch[1] === normalised) {
+            let fullBlock = line;
+            for (let i = idx + 1; i < lines.length; i++) {
+                if (/^\s{2,}/.test(lines[i]) && !/^-\s+\[/.test(lines[i].trim())) {
+                    fullBlock += '\n' + lines[i];
+                }
+                else {
+                    break;
+                }
+            }
+            return fullBlock;
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Main hook entry point
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function tddPhaseHook(changePath, toolName, filePath, taskId, toolOutput) {
+    // 1. Determine whether this task is a TDD task (@test-case annotated)
+    const taskLine = await findTaskLine(changePath, taskId);
+    if (!taskLine) {
+        return { action: 'continue' };
+    }
+    const testCases = parseTestCaseAnnotations(taskLine);
+    if (testCases.length === 0) {
+        // Not a TDD task – nothing to enforce
+        return { action: 'continue' };
+    }
+    // 2. Load or initialise TDD status
+    let status = await loadTddStatus(changePath, taskId);
+    if (!status) {
+        status = {
+            taskId,
+            testCases,
+            tddPhase: 'PENDING',
+            testFileCreated: false,
+            testInitiallyFailed: false,
+            testFinallyPassed: false,
+            implFileCreated: false,
+            updatedAt: new Date().toISOString(),
+        };
+    }
+    // 3. Check file creation order: test file should be created before impl file
+    if (!isTestFile(filePath) && !status.testFileCreated) {
+        if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+            // Implementation file created/modified before any test file exists
+            status.implFileCreated = true;
+            status.updatedAt = new Date().toISOString();
+            await saveTddStatus(changePath, taskId, status);
+            return {
+                action: 'warn',
+                message: `TDD violation: Implementation file "${path.basename(filePath)}" ` +
+                    `created before test file. In TDD, write tests first (RED phase).`,
+                updatedStatus: status,
+            };
+        }
+    }
+    // 4. Detect phase transitions & test results
+    const previousPhase = status.tddPhase;
+    status = detectTddPhaseTransition(status, toolName, filePath, toolOutput);
+    // 5. Enforce GREEN-phase constraint: tests must pass
+    if (previousPhase === 'GREEN' && toolName === 'Bash') {
+        const result = detectTestResult(toolOutput);
+        if (result === 'fail') {
+            await saveTddStatus(changePath, taskId, status);
+            return {
+                action: 'block',
+                message: 'TDD violation: Tests must pass in GREEN phase. ' +
+                    'Fix the implementation until all tests pass before proceeding.',
+                updatedStatus: status,
+            };
+        }
+    }
+    // 6. Persist updated status
+    await saveTddStatus(changePath, taskId, status);
+    // 7. Return result
+    return {
+        action: 'continue',
+        updatedStatus: status,
+    };
+}
+//# sourceMappingURL=tdd-phase-hook.js.map

package/dist/core/init.d.ts

@@ -83,6 +83,7 @@ export declare class InitCommand {
     private displayWorkflowDiagram;
     private formatToolNames;
     private renderBanner;
+    private ensureClaudeHud;
     private startSpinner;
 }
 export {};

package/dist/core/init.js

@@ -353,6 +353,8 @@ export class InitCommand {
             symbol: PALETTE.white('▌'),
             text: PALETTE.white('AI 工具已配置'),
         });
+        // Step 4: Ensure claude-hud is installed (for version display in statusLine)
+        await this.ensureClaudeHud();
         // Success message
         this.displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode, toolConfigResult.rootStubStatus, toolConfigResult.claudeHookSummary);
     }
@@ -1258,6 +1260,17 @@ export class InitCommand {
                         ],
                     },
                 ],
+                UserPromptSubmit: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'zhuanspec-hook deviation-check --trigger post-prompt',
+                                statusMessage: 'Checking prompt vs proposal consistency...',
+                            },
+                        ],
+                    },
+                ],
                 PreToolUse: [
                     {
                         matcher: 'Write|Edit',
@@ -1280,10 +1293,15 @@ export class InitCommand {
                                 statusMessage: '📝 Recording progress...',
                                 async: false,
                             },
+                        ],
+                    },
+                    {
+                        matcher: 'Write|Edit',
+                        hooks: [
                             {
                                 type: 'command',
-                                command: 'zhuanspec-hook collect-knowledge',
-                                statusMessage: '📚 Collecting knowledge...',
+                                command: 'zhuanspec-hook collect-knowledge --json',
+                                statusMessage: '💡 Checking for knowledge to capture...',
                                 async: false,
                             },
                         ],
@@ -1526,6 +1544,31 @@ export class InitCommand {
         console.log(PALETTE.white('Welcome to ZhuanSpec!'));
         console.log();
     }
+    async ensureClaudeHud() {
+        const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(process.env.HOME || '~', '.claude');
+        const hudConfigPath = path.join(configDir, 'plugins', 'claude-hud', 'config.json');
+        if (existsSync(hudConfigPath)) {
+            return;
+        }
+        const spinner = this.startSpinner('正在安装 claude-hud（用于版本信息展示）...');
+        try {
+            execSync('claude plugin install claude-hud', {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 30000,
+            });
+            spinner.stopAndPersist({
+                symbol: PALETTE.white('▌'),
+                text: PALETTE.white('claude-hud 安装完成'),
+            });
+        }
+        catch {
+            spinner.stopAndPersist({
+                symbol: PALETTE.midGray('▌'),
+                text: PALETTE.midGray('claude-hud 安装失败，可手动执行: claude mcp install claude-hud'),
+            });
+        }
+    }
     startSpinner(text) {
         return ora({
             text,