@zhuan-ai/zhuanspec 2.11.3 → 2.11.4

package/dist/core/hooks/notify-milestone.js

@@ -122,16 +122,42 @@ function parseTasks(content) {
             currentWave = parseInt(waveMatch[1], 10);
             continue;
         }
-        // Match task lines: - [ ] X.Y description or - [x] X.Y description
-        const taskMatch = line.match(/^-\s*\[([x ])\]\s*(\d+\.\d+)\s*(.+)/);
-        if (taskMatch) {
-            const statusChar = taskMatch[1];
-            const taskId = taskMatch[2];
+        // Match new format task lines: - [ ] X.Y description or - [x] X.Y description
+        const newFormatMatch = line.match(/^-\s*\[([x ])\]\s*(\d+\.\d+)\s*(.+)/);
+        if (newFormatMatch) {
+            const statusChar = newFormatMatch[1];
+            const taskId = newFormatMatch[2];
             tasks.push({
                 taskId,
                 status: statusChar === 'x' ? 'completed' : 'pending',
                 wave: currentWave,
             });
+            continue;
+        }
+        // Match legacy format task headers: #### T1: description or #### T2: description
+        const legacyMatch = line.match(/^####\s*(T\d+)\s*:\s*(.+)$/);
+        if (legacyMatch) {
+            const taskId = legacyMatch[1];
+            const rawDescription = legacyMatch[2].trim();
+            const isCompleted = rawDescription.endsWith('✅');
+            tasks.push({
+                taskId,
+                status: isCompleted ? 'completed' : 'pending',
+                wave: currentWave,
+            });
+            continue;
+        }
+        // Match "Task X.Y" format: #### Task 1.0: description or #### Task 1.1: description
+        const taskXYMatch = line.match(/^####\s*Task\s+(\d+\.\d+)\s*:\s*(.+)$/i);
+        if (taskXYMatch) {
+            const taskId = taskXYMatch[1];
+            const rawDescription = taskXYMatch[2].trim();
+            const isCompleted = rawDescription.endsWith('✅');
+            tasks.push({
+                taskId,
+                status: isCompleted ? 'completed' : 'pending',
+                wave: currentWave,
+            });
         }
     }
     return tasks;

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

@@ -420,11 +420,12 @@ function formatConsistencyFixPrompt(output, loopCount) {
 
 ${uncoveredList}
 
-请选择修复方向：
-1. 添加代码实现以覆盖这些 Scenario
-2. 或更新 Spec 描述以反映当前实现状态
+⚠️ 铁律：Spec is Truth — 文档与代码冲突时，错的一定是代码。
+🚫 禁止修改 Spec 文件内容（包括 Requirement 名称、Scenario 描述、Given/When/Then 条件）。
 
-然后重新运行 spec-code-consistency 检查。
+请通过以下方式修复：
+1. 补充或修改代码实现，使其满足上述 Scenario 描述的业务诉求
+2. 修复后重新运行 spec-code-consistency 检查验证覆盖情况
 `;
 }
 // ============================================================

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

@@ -45,6 +45,12 @@ function generateUnitTestPrompt(changeId) {
 ## 任务目标
 为 changeId=${changeId} 的代码变更生成并验证单元测试
 
+## TDD 模式感知
+在生成单测前，检查 Apply 阶段是否已有 TDD 生成的测试文件：
+- 读取 zhuanspec/changes/${changeId}/tasks.md，查看是否有已完成的 @test-case 任务
+- 若存在 TDD 已生成的测试，识别已有测试做增量补全
+- 若不存在 TDD 测试，按正常流程全量生成单测
+
 ## 自闭环指令
 1. 执行 generate-mockito-unit-test skill 生成单测
 2. 运行单测，检查通过率和覆盖率
@@ -111,6 +117,9 @@ function generateSpecConsistencyPrompt(changeId) {
 
 ### Step 4：自闭环修复
 - 发现 ❌ 未覆盖的 Scenario → 补充对应代码实现
+- ⚠️ **铁律：Spec is Truth** — 文档与代码冲突时，错的一定是代码
+- 🚫 **绝对禁止修改 Spec 文件**（包括 Requirement 名称、Scenario 标题、Given/When/Then 描述）
+- 只能通过新增或修改代码来满足 Spec 描述的业务诉求
 - 修复后重新执行 Step 2 验证（最多3轮）
 - ⚠️ 仅修复真实遗漏，禁止把"文件存在但逻辑未实现"误报为已覆盖
 

package/dist/core/init.js

@@ -1552,6 +1552,18 @@ export class InitCommand {
         }
         const spinner = this.startSpinner('正在安装 claude-hud（用于版本信息展示）...');
         try {
+            // Step 1: Add the claude-hud marketplace (skip if already added)
+            try {
+                execSync('claude plugin marketplace add jarrodwatts/claude-hud', {
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                    timeout: 30000,
+                });
+            }
+            catch {
+                // Marketplace may already be added, ignore error and proceed
+            }
+            // Step 2: Install the plugin from the marketplace
             execSync('claude plugin install claude-hud', {
                 encoding: 'utf-8',
                 stdio: ['pipe', 'pipe', 'pipe'],
@@ -1565,7 +1577,7 @@ export class InitCommand {
         catch {
             spinner.stopAndPersist({
                 symbol: PALETTE.midGray('▌'),
-                text: PALETTE.midGray('claude-hud 安装失败，可手动执行: claude mcp install claude-hud'),
+                text: PALETTE.midGray('claude-hud 安装失败，可手动执行: claude plugin marketplace add jarrodwatts/claude-hud && claude plugin install claude-hud'),
             });
         }
     }

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

@@ -293,8 +293,8 @@ const applySteps = `**步骤**
    4. 如果 Skill 异常或超时，跳过 Skill 继续实施
 
    - **阶段职责（按 Agent 类型区分）**：
-     * **applyAgent（普通模式）**：不生成单元测试文件，单测生成与验证统一在 Review 阶段执行
-     * **tddApplyAgent（TDD 模式，任务有 \`@test-case\` 标注）**：基于 test-cases.md 先写测试再实现代码
+     * **applyAgent（普通模式）**：专注代码实现，不生成单元测试文件
+     * **tddApplyAgent（TDD 模式，任务有 \`@test-case\` 标注）**：基于 test-cases.md 先写测试再写实现，执行 Red-Green-Refactor 循环（详见 tdd-apply-agent.md）
 4. **确认完成** - 在更新状态之前确保 \`tasks.md\` 中的每个项目都已完成。
 5. **更新清单** - 所有工作完成后，将每个任务设置为 \`- [x]\`，以便列表反映实际情况。
 6. **处理 Subagent 状态报告**（Wave 并行执行时）：
@@ -303,7 +303,7 @@ const applySteps = `**步骤**
    - **DONE_WITH_CONCERNS**：转发进度汇报 → 记录 concerns 并评估是否需要修复
    - **BLOCKED**：转发进度汇报 → 评估 blocker 类型并决定处理策略（提供上下文/换更强模型/拆分任务）
    - **NEEDS_CONTEXT**：转发进度汇报 → 提供缺失信息并重新启动 subagent
-   - 所有任务报告文件均保存在 \`changes/<change-id>/reports/\` 目录，可告知用户按 task-id 查阅
+   - 所有任务报告文件均保存在 \`zhuanspec/changes/<change-id>/reports/\` 目录，可告知用户按 task-id 查阅
 7. **Wave 完成后集成验证**（Wave 并行执行时）：
    每个 Wave 全部任务完成后，编排 Agent 自动执行以下检查：
 
@@ -337,8 +337,8 @@ const applySteps = `**步骤**
 9. **触发审查门禁** - 所有任务完成后选项式提问用户是否进入 Review 阶段`;
 const applyGuardrails = `${baseGuardrails}\n- **Wave 并行执行**：当 tasks.md 包含 \`@depends\` 时，按 Wave 编号串行执行，Wave 内任务通过 Agent tool 并行启动 subagent。
 - **Agent 类型选择**：根据任务 \`@test-case\` 标注选择 subagent 类型：
-  * 无 \`@test-case\` 标注 → \`applyAgent\`（普通模式，单测在 Review 阶段）
-  * 有 \`@test-case:TC-XXX\` 标注 → \`tddApplyAgent\`（TDD 模式，Apply 阶段执行测试用例）
+  * 无 \`@test-case\` 标注 → \`applyAgent\`（普通模式）
+  * 有 \`@test-case:TC-XXX\` 标注 → \`tddApplyAgent\`（TDD 模式，先写测试再写实现，详见 tdd-apply-agent.md）
 - **Rules 和 Knowledge 注入**：编排 Agent MUST 在每个 subagent prompt 中注入 Rules（根据 @skill）和 Knowledge（踩坑警告、最佳实践）。
 - **偏差处理**：PreToolUse Hook 检测到提案范围外修改时弹出选项式交互（更新提案/Bug修复豁免/取消）。3次偏差后强制更新提案。`;
 const applyReferences = `**参考**
@@ -436,27 +436,28 @@ const reviewSteps = `**步骤**
    - **轨道 A：Code Review 轨**
      - 使用 Skill 工具调用 \`code-review-expert\` skill
      - 输出 \`code-review-report.md\`，记录 Critical/Important 问题
-     - skill 完成后，**AI 将结果写入** \`changes/<id>/review/code-review-result.json\`，格式：
+     - skill 完成后，**AI 将结果写入** \`zhuanspec/changes/<id>/review/code-review-result.json\`，格式：
        \`\`\`json
        { "criticalCount": 0, "importantCount": 0, "infoCount": 0, "issues": [], "sonarStatus": "skip", "loopCount": 0 }
        \`\`\`
    - **轨道 B：Unit Test 轨（Skill）**
      - 使用 Skill 工具调用 \`generate-mockito-unit-test\`
-     - 对缺失场景补齐单测并执行测试命令，输出单测结果
-     - skill 完成后，**AI 将结果写入** \`changes/<id>/review/unit-test-result.json\`，格式：
+     - 检查 Apply 阶段是否已有 TDD 生成的测试，若有则识别已有测试做增量补全，若无则全量生成
+     - 运行全部单测并执行测试命令，输出单测结果
+     - skill 完成后，**AI 将结果写入** \`zhuanspec/changes/<id>/review/unit-test-result.json\`，格式：
        \`\`\`json
        { "testPassed": true, "passRate": 100, "coverage": 85, "coverageThreshold": 80, "newTestsGenerated": [], "failedTests": [], "loopCount": 0 }
        \`\`\`
    - **轨道 C：Spec-Code 一致性轨**
      - 运行 \`zhuanspec validate <change-id> --strict\`
      - 确认 \`spec-code-consistent\` 规则通过
-     - validate 完成后，**AI 将结果写入** \`changes/<id>/review/spec-consistency-result.json\`，格式：
+     - validate 完成后，**AI 将结果写入** \`zhuanspec/changes/<id>/review/spec-consistency-result.json\`，格式：
        \`\`\`json
        { "consistencyRate": 100, "totalRequirements": 0, "totalScenarios": 0, "coveredScenarios": 0, "uncoveredScenarios": [], "mapping": [], "loopCount": 0 }
        \`\`\`
 3. **汇总执行 CLI Review**：
    - 运行 \`zhuanspec review <change-id>\`
-   - CLI 读取三个 JSON，生成 \`changes/<id>/review/review-report.md\`
+   - CLI 读取三个 JSON，生成 \`zhuanspec/changes/<id>/review/review-report.md\`
    - 如果 skill JSON 未写入，CLI 将打印缺失文件列表并退出
 4. **审查结果处理**：
    - **PASS**：三轨全部通过（CR=PASS、UT=PASS、Spec-Code=PASS）且 Critical=0，可以继续归档
@@ -469,9 +470,9 @@ const reviewSteps = `**步骤**
    - 提示可以使用 \`/zhuanspec:archive\` 进行归档`;
 const reviewReferences = `**参考**
 - 使用 \`zhuanspec review --help\` 查看完整选项
-- 审查报告文件均位于 \`changes/<id>/review/\` 目录下：\`code-review-result.json\`、\`unit-test-result.json\`、\`spec-consistency-result.json\`、\`review-report.md\`
+- 审查报告文件均位于 \`zhuanspec/changes/<id>/review/\` 目录下：\`code-review-result.json\`、\`unit-test-result.json\`、\`spec-consistency-result.json\`、\`review-report.md\`
 - 单元测试覆盖率阈值默认 80%，可通过 \`--coverage-threshold\` 调整
-- \`code-review-expert\` Skill 结果由 AI 写入 \`changes/<id>/review/code-review-result.json\`，\`generate-mockito-unit-test\` Skill 结果由 AI 写入 \`changes/<id>/review/unit-test-result.json\``;
+- \`code-review-expert\` Skill 结果由 AI 写入 \`zhuanspec/changes/<id>/review/code-review-result.json\`，\`generate-mockito-unit-test\` Skill 结果由 AI 写入 \`zhuanspec/changes/<id>/review/unit-test-result.json\``;
 const knowledgeGuardrails = `${baseGuardrails}\n- **知识管理阶段**：knowledge 命令用于管理项目级知识库（最佳实践、陷阱、隐式约定）。
 - **跨变更积累**：知识不绑定单个变更，是长期积累的项目资产。
 - **职责分离**：

package/dist/core/templates/tasks-template.js

@@ -169,6 +169,7 @@ Wave assignment logic:
 - Wave 2: @depends:1.x → depends on Wave 1
 - Wave 3: @depends:2.x → depends on Wave 2
 
+
 ## File Conflict Analysis
 
 <!-- 当多个任务修改同一文件时，在此声明冲突并指定隔离策略 -->

package/dist/core/validation/strict-rules.d.ts

@@ -150,6 +150,15 @@ export declare function checkTestCaseCoverage(tasksContent: string, hasTestCase?
  */
 export declare function checkTechSpecCoverage(changeDir: string): StrictCheckResult;
 export declare function checkTaskIdFormat(tasksContent: string): StrictCheckResult;
+/**
+ * Rule: task-checkbox-format
+ *
+ * Validates that all tasks under Wave headers use standard GitHub Flavored Markdown
+ * checkbox format: `- [ ] N.M description` or `- [x] N.M description`.
+ * Rejects legacy formats like `#### Task N.M:` headers or `✅` emoji as completion marker.
+ * This ensures automated progress tracking (parseTasks, record-progress, review gate) works correctly.
+ */
+export declare function checkTaskCheckboxFormat(tasksContent: string): StrictCheckResult;
 /**
  * Main entry: Run all strict validation rules
  */

package/dist/core/validation/strict-rules.js

@@ -1179,6 +1179,76 @@ export function checkTaskIdFormat(tasksContent) {
     result.passed = invalidIds.length === 0;
     return result;
 }
+/**
+ * Rule: task-checkbox-format
+ *
+ * Validates that all tasks under Wave headers use standard GitHub Flavored Markdown
+ * checkbox format: `- [ ] N.M description` or `- [x] N.M description`.
+ * Rejects legacy formats like `#### Task N.M:` headers or `✅` emoji as completion marker.
+ * This ensures automated progress tracking (parseTasks, record-progress, review gate) works correctly.
+ */
+export function checkTaskCheckboxFormat(tasksContent) {
+    const result = {
+        ruleId: 'task-checkbox-format',
+        ruleName: 'Task checkbox format',
+        passed: false,
+        errors: [],
+        warnings: [],
+    };
+    // 1. Check for legacy #### Task headers (should not be used)
+    const legacyTaskHeaders = tasksContent.match(/^####\s*(?:Task\s+\d+\.\d+|T\d+)\s*:.+$/gm) || [];
+    if (legacyTaskHeaders.length > 0) {
+        for (const header of legacyTaskHeaders) {
+            result.errors.push(`Legacy task format detected: "${header.trim()}". ` +
+                `Must use checkbox format: "- [ ] N.M description" or "- [x] N.M description"`);
+        }
+    }
+    // 2. Find all lines under Wave headers that look like tasks but don't use checkbox format
+    const lines = tasksContent.split('\n');
+    let inWaveSection = false;
+    for (const line of lines) {
+        // Detect Wave header
+        if (/^###\s+Wave\s+\d+/i.test(line)) {
+            inWaveSection = true;
+            continue;
+        }
+        // Detect next non-Wave section header (## or ### not Wave)
+        if (/^#{2,3}\s+(?!Wave\s+\d+)/i.test(line)) {
+            inWaveSection = false;
+            continue;
+        }
+        if (!inWaveSection)
+            continue;
+        // Skip empty lines, comments, and non-list lines
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('<!--') || !trimmed.startsWith('-'))
+            continue;
+        // Line starts with - but is NOT a valid checkbox format
+        if (/^-\s+(?!\[[ xX]\])\S/.test(trimmed)) {
+            // Only flag lines that look like task items (have N.M id or substantial content)
+            if (/^-\s+\d+\.\d+\s/.test(trimmed) || /^-\s+[A-Z]/.test(trimmed)) {
+                result.warnings.push(`Task line without checkbox: "${trimmed.substring(0, 80)}". ` +
+                    `Expected format: "- [ ] N.M description"`);
+            }
+        }
+    }
+    // 3. Verify checkbox tasks exist (at least one task under Wave headers)
+    const checkboxTasks = tasksContent.match(/^-\s+\[[ xX]\]\s+\d+\.\d+\s+.+$/gm) || [];
+    if (checkboxTasks.length === 0 && legacyTaskHeaders.length === 0) {
+        // No tasks at all - just a warning, not an error (template might be empty)
+        result.warnings.push('No tasks found in checkbox format under Wave headers');
+    }
+    // 4. Check that completed tasks use [x] not ✅ emoji on checkbox lines
+    const checkboxWithEmoji = tasksContent.match(/^-\s+\[[ ]\]\s+.+\u2705\s*$/gm) || [];
+    if (checkboxWithEmoji.length > 0) {
+        for (const line of checkboxWithEmoji) {
+            result.warnings.push(`Task uses ✅ emoji but checkbox is unchecked: "${line.trim().substring(0, 80)}". ` +
+                `Use "- [x]" to mark completion instead of ✅ emoji`);
+        }
+    }
+    result.passed = result.errors.length === 0;
+    return result;
+}
 /**
  * Main entry: Run all strict validation rules
  */
@@ -1194,6 +1264,7 @@ export async function runStrictValidation(tasksContent, parsedTasks, knownSkillN
         checkFileConflicts(parsedTasks),
         checkTestCaseCoverage(tasksContent, hasTestCase),
         checkTaskIdFormat(tasksContent),
+        checkTaskCheckboxFormat(tasksContent),
     ];
     // Add new rules if parameters are provided
     if (options?.proposalContent) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.11.3",
+  "version": "2.11.4",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -39,6 +39,26 @@
     "!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"
   },
@@ -60,23 +80,5 @@
     "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"
   }
-}
+}