@zhuan-ai/zhuanspec 2.11.3 → 2.11.6

package/dist/commands/change.js

@@ -1,5 +1,6 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+import chalk from 'chalk';
 import { JsonConverter } from '../core/converters/json-converter.js';
 import { Validator } from '../core/validation/validator.js';
 import { ChangeParser } from '../core/parsers/change-parser.js';
@@ -211,11 +212,15 @@ export class ChangeCommand {
                 console.log(`Change "${changeName}" is valid`);
             }
             else {
-                console.error(`Change "${changeName}" has issues`);
+                console.error(`变更 "${changeName}" 存在问题`);
                 report.issues.forEach(issue => {
-                    const label = issue.level === 'ERROR' ? 'ERROR' : 'WARNING';
-                    const prefix = issue.level === 'ERROR' ? '✗' : '⚠';
-                    console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+                    const label = issue.level === 'ERROR' ? '错误' : '警告';
+                    if (issue.level === 'ERROR') {
+                        console.error(chalk.red(`✗ [${label}] ${issue.path}: ${issue.message}`));
+                    }
+                    else {
+                        console.error(chalk.yellow(`⚠ [${label}] ${issue.path}: ${issue.message}`));
+                    }
                 });
                 // Next steps footer to guide fixing issues
                 this.printNextSteps();

package/dist/commands/progress.js

@@ -211,12 +211,12 @@ export class ProgressCommand {
                 });
                 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);
+            // Match "Task X.Y" or bare "X.Y" format: #### Task 1.0: description or #### 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('✅');
+                const isCompleted = rawDescription.endsWith('\u2705');
                 const description = isCompleted
                     ? rawDescription.slice(0, -1).trim()
                     : rawDescription;

package/dist/commands/spec.js

@@ -1,3 +1,4 @@
+import chalk from 'chalk';
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { MarkdownParser } from '../core/parsers/markdown-parser.js';
@@ -205,11 +206,18 @@ export function registerSpecCommand(rootProgram) {
                     console.log(`Specification '${specId}' is valid`);
                 }
                 else {
-                    console.error(`Specification '${specId}' has issues`);
+                    console.error(`规范 '${specId}' 存在问题`);
                     report.issues.forEach(issue => {
-                        const label = issue.level === 'ERROR' ? 'ERROR' : issue.level;
-                        const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
-                        console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+                        const label = issue.level === 'ERROR' ? '错误' : issue.level === 'WARNING' ? '警告' : '提示';
+                        if (issue.level === 'ERROR') {
+                            console.error(chalk.red(`✗ [${label}] ${issue.path}: ${issue.message}`));
+                        }
+                        else if (issue.level === 'WARNING') {
+                            console.error(chalk.yellow(`⚠ [${label}] ${issue.path}: ${issue.message}`));
+                        }
+                        else {
+                            console.error(`ℹ [${label}] ${issue.path}: ${issue.message}`);
+                        }
                     });
                 }
             }

package/dist/commands/validate.js

@@ -292,18 +292,25 @@ export class ValidateCommand {
             }
         }
         else {
-            console.error(`${type === 'change' ? 'Change' : 'Specification'} '${id}' has issues`);
+            console.error(`${type === 'change' ? '变更' : '规范'} '${id}' 存在问题`);
             for (const issue of report.issues) {
-                const label = issue.level === 'ERROR' ? 'ERROR' : issue.level;
-                const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
-                console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+                const label = issue.level === 'ERROR' ? '错误' : issue.level === 'WARNING' ? '警告' : '提示';
+                if (issue.level === 'ERROR') {
+                    console.error(chalk.red(`✗ [${label}] ${issue.path}: ${issue.message}`));
+                }
+                else if (issue.level === 'WARNING') {
+                    console.error(chalk.yellow(`⚠ [${label}] ${issue.path}: ${issue.message}`));
+                }
+                else {
+                    console.error(`ℹ [${label}] ${issue.path}: ${issue.message}`);
+                }
             }
             this.printNextSteps(type);
         }
         // Print strict mode checks summary if available
         if (opts?.strict && report.strictChecks && report.strictChecks.length > 0) {
             console.log('');
-            console.log('Strict Mode Checks:');
+            console.log('严格模式检查：');
             for (const check of report.strictChecks) {
                 if (check.passed) {
                     console.log(`  ${chalk.green('✓')} ${check.ruleName}`);
@@ -311,7 +318,9 @@ export class ValidateCommand {
                 else {
                     const firstError = check.errors[0] || check.warnings[0] || '';
                     const errorSuffix = firstError ? ` — ${firstError}` : '';
-                    console.log(`  ${chalk.red('✗')} ${check.ruleName}${errorSuffix}`);
+                    const hasErrors = check.errors.length > 0;
+                    const color = hasErrors ? chalk.red : chalk.yellow;
+                    console.log(`  ${color('✗')} ${check.ruleName}${errorSuffix}`);
                 }
             }
         }

package/dist/core/artifact-graph/instruction-loader.d.ts

@@ -100,7 +100,9 @@ export interface ChangeStatus {
  * @returns The template content
  * @throws TemplateLoadError if the template cannot be loaded
  */
-export declare function loadTemplate(schemaName: string, templatePath: string): string;
+export declare function loadTemplate(schemaName: string, templatePath: string, options?: {
+    changeName?: string;
+}): string;
 /**
  * Loads change context combining graph and completion state.
  *

package/dist/core/artifact-graph/instruction-loader.js

@@ -5,6 +5,8 @@ import { ArtifactGraph } from './graph.js';
 import { detectCompleted } from './state.js';
 import { resolveSchemaForChange } from '../../utils/change-metadata.js';
 import { loadProjectConfig, getEffectiveRules } from '../project-config.js';
+import { getTasksTemplate } from '../templates/tasks-template.js';
+import { getTddTasksTemplate } from '../templates/tdd-tasks-template.js';
 /**
  * Error thrown when loading a template fails.
  */
@@ -24,7 +26,13 @@ export class TemplateLoadError extends Error {
  * @returns The template content
  * @throws TemplateLoadError if the template cannot be loaded
  */
-export function loadTemplate(schemaName, templatePath) {
+export function loadTemplate(schemaName, templatePath, options) {
+    // Prefer TypeScript template functions as single source of truth
+    const tsTemplate = loadFromTypeScriptTemplate(schemaName, templatePath, options);
+    if (tsTemplate !== null) {
+        return tsTemplate;
+    }
+    // Fallback: load from static file
     const schemaDir = getSchemaDir(schemaName);
     if (!schemaDir) {
         throw new TemplateLoadError(`Schema '${schemaName}' not found`, templatePath);
@@ -41,6 +49,23 @@ export function loadTemplate(schemaName, templatePath) {
         throw new TemplateLoadError(`Failed to read template: ${ioError.message}`, fullPath);
     }
 }
+/**
+ * Attempt to load template from TypeScript template functions.
+ * Returns null if no TypeScript template is registered for this schema+template combination.
+ * This ensures TypeScript templates are the single source of truth,
+ * avoiding dual-track desync between .ts functions and static .md files.
+ */
+function loadFromTypeScriptTemplate(schemaName, templatePath, options) {
+    if (templatePath === 'tasks.md') {
+        if (schemaName === 'spec-driven') {
+            return getTasksTemplate({ changeId: options?.changeName || '[change-id]' });
+        }
+        if (schemaName === 'tdd') {
+            return getTddTasksTemplate({ changeId: options?.changeName || '[change-id]' });
+        }
+    }
+    return null;
+}
 /**
  * Loads change context combining graph and completion state.
  *
@@ -82,7 +107,7 @@ export function generateInstructions(context, artifactId) {
     if (!artifact) {
         throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'`);
     }
-    const template = loadTemplate(context.schemaName, artifact.template);
+    const template = loadTemplate(context.schemaName, artifact.template, { changeName: context.changeName });
     const dependencies = getDependencyInfo(artifact, context.graph, context.completed);
     const unlocks = getUnlockedArtifacts(context.graph, artifactId);
     // Load project config for context/rules injection

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

@@ -16,7 +16,7 @@ import fs from 'fs';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { GitRepoDetector } from '../../utils/git-repo-detector.js';
 import { checkPreApplyConditions } from './pre-apply.js';
-import { recordHookTrigger } from './record-progress.js';
+import { recordHookTrigger, detectActiveChange } from './record-progress.js';
 // Pitfall keywords for knowledge collection
 const PITFALL_KEYWORDS = [
     '不对', '错了', '踩坑', '坑', '失败', '问题', 'bug',
@@ -120,9 +120,22 @@ async function readStdin() {
     });
 }
 async function runDeviationCheck(filePath, trigger, promptText, _options) {
-    const phase = process.env.ZHUANSPEC_PHASE || 'idle';
-    const changeId = process.env.ZHUANSPEC_CHANGE_ID || '';
+    // Priority: env vars (set by SessionStart) > filesystem detection (fallback)
+    let phase = process.env.ZHUANSPEC_PHASE || '';
+    let changeId = process.env.ZHUANSPEC_CHANGE_ID || '';
     const currentTask = process.env.ZHUANSPEC_CURRENT_TASK || '';
+    // Fallback: if env vars not set, detect active change from filesystem
+    if (!changeId || phase === 'idle' || !phase) {
+        const cwd = process.cwd();
+        const activeChange = await detectActiveChange(cwd, filePath || undefined);
+        if (activeChange) {
+            changeId = activeChange.changeId;
+            phase = activeChange.phase;
+        }
+        else {
+            phase = phase || 'idle';
+        }
+    }
     // No change bound or idle phase → allow, post-prompt silences itself to avoid noise
     if (!changeId || phase === 'idle') {
         if (trigger === 'post-prompt') {

package/dist/core/hooks/init.js

@@ -76,7 +76,20 @@ export async function initHook(options) {
         await updateClaudeHudCustomLine(output.versionBanner);
     }
     if (options.json) {
-        console.log(JSON.stringify(output));
+        // Output JSON with env at top level for Claude Code hook protocol
+        const jsonOutput = {
+            continue: output.continue,
+            systemMessage: output.systemMessage,
+        };
+        if (output.hookSpecificOutput?.env) {
+            jsonOutput.env = output.hookSpecificOutput.env;
+        }
+        if (output.hookSpecificOutput?.additionalContext) {
+            jsonOutput.hookSpecificOutput = {
+                additionalContext: output.hookSpecificOutput.additionalContext,
+            };
+        }
+        console.log(JSON.stringify(jsonOutput));
     }
     else {
         if (output.systemMessage) {

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/pre-review.js

@@ -36,9 +36,18 @@ async function checkTasksCompletion(changePath) {
     }
     try {
         const content = await FileSystemUtils.readFile(tasksPath);
-        const allTasks = content.match(/^- \[[ x]\] .+$/gm) || [];
-        const uncompletedTasks = content.match(/^- \[ \] .+$/gm) || [];
-        const completedTasks = content.match(/^- \[x\] .+$/gm) || [];
+        // Support checkbox format: - [ ] / - [x]
+        const checkboxAll = content.match(/^- \[[ x]\] .+$/gm) || [];
+        const checkboxUncompleted = content.match(/^- \[ \] .+$/gm) || [];
+        const checkboxCompleted = content.match(/^- \[x\] .+$/gm) || [];
+        // Support header format: #### N.M / #### Task N.M: / #### TN:
+        const headerAll = content.match(/^####\s*(?:Task\s+)?\d+\.\d+[\s:].+$|^####\s*T\d+\s*:.+$/gm) || [];
+        const headerCompleted = headerAll.filter(t => t.includes('\u2705'));
+        const headerUncompleted = headerAll.filter(t => !t.includes('\u2705'));
+        // Use checkbox format if found, otherwise fall back to header format
+        const allTasks = checkboxAll.length > 0 ? checkboxAll : headerAll;
+        const uncompletedTasks = checkboxAll.length > 0 ? checkboxUncompleted : headerUncompleted;
+        const completedTasks = checkboxAll.length > 0 ? checkboxCompleted : headerCompleted;
         if (allTasks.length === 0) {
             return {
                 passed: false,
@@ -86,8 +95,12 @@ async function checkProgressConsistency(changePath) {
         const progressContent = await FileSystemUtils.readFile(progressPath);
         const progress = JSON.parse(progressContent);
         const tasksContent = await FileSystemUtils.readFile(tasksPath);
-        const totalFromTasks = (tasksContent.match(/^- \[[ x]\] .+$/gm) || []).length;
-        const completedFromTasks = (tasksContent.match(/^- \[x\] .+$/gm) || []).length;
+        const checkboxTotal = (tasksContent.match(/^- \[[ x]\] .+$/gm) || []).length;
+        const checkboxCompleted = (tasksContent.match(/^- \[x\] .+$/gm) || []).length;
+        const headerTotal = (tasksContent.match(/^####\s*(?:Task\s+)?\d+\.\d+[\s:].+$|^####\s*T\d+\s*:.+$/gm) || []).length;
+        const headerCompleted = (tasksContent.match(/^####\s*(?:Task\s+)?\d+\.\d+[\s:].+$|^####\s*T\d+\s*:.+$/gm) || []).filter(t => t.includes('\u2705')).length;
+        const totalFromTasks = checkboxTotal > 0 ? checkboxTotal : headerTotal;
+        const completedFromTasks = checkboxTotal > 0 ? checkboxCompleted : headerCompleted;
         const totalFromProgress = progress.totalTasks || 0;
         if (totalFromProgress !== totalFromTasks) {
             return {

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

@@ -213,6 +213,18 @@ export interface ProgressData {
     lastEvent?: string;
 }
 export declare function recordProgressHook(options: RecordProgressOptions): Promise<void>;
+/**
+ * Detect active change from progress.json files.
+ *
+ * Strategy:
+ * 1. Primary — if filePath is under zhuanspec/changes/{changeId}/, extract changeId directly.
+ * 2. Fallback — scan all changes and return the most recently updated one
+ *    (by lastUpdatedAt field; stub files without it fall back to filesystem mtime).
+ */
+export declare function detectActiveChange(cwd: string, filePath?: string): Promise<{
+    changeId: string;
+    phase: Phase;
+} | null>;
 /**
  * Initialize progress.json at phase start
  * This function should be called when a change is created, before any files are written.

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

@@ -219,7 +219,7 @@ function extractMcpTool(toolName) {
  * 2. Fallback — scan all changes and return the most recently updated one
  *    (by lastUpdatedAt field; stub files without it fall back to filesystem mtime).
  */
-async function detectActiveChange(cwd, filePath) {
+export async function detectActiveChange(cwd, filePath) {
     const changesDir = path.join(cwd, 'zhuanspec', 'changes');
     if (!await FileSystemUtils.directoryExists(changesDir)) {
         return null;
@@ -544,7 +544,7 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
             const tasksContent = await FileSystemUtils.readFile(tasksPath);
             // Match checkbox format: - [ ] or - [x], and also #### Task X.Y: format
             const checkboxTasks = tasksContent.match(/^- \[[ x]\] .+$/gm) || [];
-            const taskHeaderTasks = tasksContent.match(/^####\s*Task\s+\d+\.\d+\s*:.+$/gm) || [];
+            const taskHeaderTasks = tasksContent.match(/^####\s*(?:Task\s+)?\d+\.\d+[\s:].+$/gm) || [];
             const legacyHeaderTasks = tasksContent.match(/^####\s*T\d+\s*:.+$/gm) || [];
             const totalTaskMatches = checkboxTasks.length > 0 ? checkboxTasks : (taskHeaderTasks.length > 0 ? taskHeaderTasks : legacyHeaderTasks);
             const completedCheckbox = tasksContent.match(/^- \[x\] .+$/gm) || [];
@@ -552,7 +552,7 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
             const completedTaskMatches = checkboxTasks.length > 0 ? completedCheckbox : completedHeaders;
             progress.totalTasks = totalTaskMatches.length;
             // Update completedTasks array with completed task descriptions
-            const completedDescriptions = completedTaskMatches.map(t => t.replace(/^- \[x\] /, '').replace(/^####\s*(?:Task\s+\d+\.\d+|T\d+)\s*:\s*/, '').replace(/\u2705$/, '').trim());
+            const completedDescriptions = completedTaskMatches.map(t => t.replace(/^- \[x\] /, '').replace(/^####\s*(?:Task\s+)?\d+\.\d+[\s:]\s*/, '').replace(/^####\s*T\d+\s*:\s*/, '').replace(/\u2705$/, '').trim());
             if (completedDescriptions.length > 0) {
                 progress.completedTasks = completedDescriptions;
             }

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

@@ -1254,7 +1254,7 @@ export class InitCommand {
                         hooks: [
                             {
                                 type: 'command',
-                                command: 'zhuanspec-hook init',
+                                command: 'zhuanspec-hook init --json',
                                 statusMessage: 'Initializing ZhuanSpec...',
                             },
                         ],
@@ -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'),
             });
         }
     }