@zhuan-ai/zhuanspec 2.11.3 → 2.11.6

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

@@ -44,16 +44,15 @@ const WAVE_HEADER_PATTERN = /^###\s+Wave\s+(\d+)/im;
 export function checkTestCaseInquiryLogged(tasksContent) {
     const result = {
         ruleId: 'test-case-inquiry-logged',
-        ruleName: 'Test case inquiry logged',
+        ruleName: '测试用例询问记录',
         passed: false,
         errors: [],
         warnings: [],
     };
     const sectionMatch = tasksContent.match(TEST_CASE_SOURCE_LOG_PATTERN);
     if (!sectionMatch) {
-        result.errors.push('Missing "## Test Case Source Log" section — the AI must ask the user about test cases ' +
-            'at the start of the proposal phase and record the result here before writing any spec/task content. ' +
-            'Add a section with at least: "用户回答: 提供/跳过" and "TDD 模式: 启用/禁用".');
+        result.errors.push('缺少 "## Test Case Source Log" 章节 — AI 必须在提案阶段开始时询问用户测试用例并记录结果。' +
+            '至少包含："用户回答: 提供/跳过" 和 "TDD 模式: 启用/禁用"。');
         return result;
     }
     const sectionStartIndex = sectionMatch.index + sectionMatch[0].length;
@@ -64,11 +63,11 @@ export function checkTestCaseInquiryLogged(tasksContent) {
     const sectionContent = tasksContent.slice(sectionStartIndex, sectionEndIndex);
     const contentWithoutComments = sectionContent.replace(HTML_COMMENT_PATTERN, '').trim();
     if (!contentWithoutComments) {
-        result.errors.push('"## Test Case Source Log" is empty — record the inquiry outcome (user answer + TDD mode status)');
+        result.errors.push('"## Test Case Source Log" 为空 — 请记录询问结果（用户回答 + TDD 模式状态）');
         return result;
     }
     if (UNRESOLVED_MARKERS.test(contentWithoutComments)) {
-        result.errors.push('"## Test Case Source Log" contains unresolved markers (TODO / TBD / PENDING)');
+        result.errors.push('"## Test Case Source Log" 包含未解决的标记（TODO / TBD / PENDING）');
         return result;
     }
     const hasDeclaredStatus = TDD_MODE_DECLARED_PATTERNS.some(p => p.test(contentWithoutComments));
@@ -77,7 +76,7 @@ export function checkTestCaseInquiryLogged(tasksContent) {
         result.passed = true;
     }
     else {
-        result.errors.push('"## Test Case Source Log" is too brief — include at least the user\'s answer and TDD mode status');
+        result.errors.push('"## Test Case Source Log" 内容过简 — 至少包含用户回答和 TDD 模式状态');
     }
     return result;
 }
@@ -98,7 +97,7 @@ export function checkTestCaseInquiryLogged(tasksContent) {
 export function checkPreClarification(tasksContent) {
     const result = {
         ruleId: 'pre-clarification-completed',
-        ruleName: 'Pre-clarification completed',
+        ruleName: '前置澄清记录',
         passed: false,
         errors: [],
         warnings: [],
@@ -106,7 +105,7 @@ export function checkPreClarification(tasksContent) {
     // Check if section exists
     const sectionMatch = tasksContent.match(PRE_CLARIFICATION_SECTION_PATTERN);
     if (!sectionMatch) {
-        result.errors.push('Pre-Clarification Log section is missing');
+        result.errors.push('Pre-Clarification Log 章节缺失');
         return result;
     }
     // Extract section content (from header to next ## or end)
@@ -120,12 +119,12 @@ export function checkPreClarification(tasksContent) {
     const contentWithoutComments = sectionContent.replace(HTML_COMMENT_PATTERN, '').trim();
     // Check if section is empty
     if (!contentWithoutComments) {
-        result.errors.push('Pre-Clarification Log section is empty or contains only HTML comments');
+        result.errors.push('Pre-Clarification Log 章节为空或仅包含 HTML 注释');
         return result;
     }
     // Check for unresolved markers
     if (UNRESOLVED_MARKERS.test(contentWithoutComments)) {
-        result.errors.push('Pre-Clarification Log contains unresolved markers (TODO, TBD, PENDING, or ?)');
+        result.errors.push('Pre-Clarification Log 包含未解决的标记（TODO、TBD、PENDING 或 ?）');
         return result;
     }
     // Check for valid completion markers or actual content
@@ -135,7 +134,7 @@ export function checkPreClarification(tasksContent) {
         result.passed = true;
     }
     else {
-        result.errors.push('Pre-Clarification Log does not contain valid completion markers or substantive Q&A content');
+        result.errors.push('Pre-Clarification Log 未包含有效的完成标记或实质性问答内容');
     }
     return result;
 }
@@ -152,7 +151,7 @@ export function checkPreClarification(tasksContent) {
 export function checkSkillTagsValid(tasksContent, parsedTasks, knownSkillNames) {
     const result = {
         ruleId: 'skill-tags-valid',
-        ruleName: 'Skill tags valid',
+        ruleName: 'Skill 标签校验',
         passed: false,
         errors: [],
         warnings: [],
@@ -160,7 +159,7 @@ export function checkSkillTagsValid(tasksContent, parsedTasks, knownSkillNames)
     // a. Check Skill Mapping section exists with table data
     const sectionMatch = tasksContent.match(SKILL_MAPPING_SECTION_PATTERN);
     if (!sectionMatch) {
-        result.errors.push('Skill Mapping section not found');
+        result.errors.push('Skill Mapping 章节未找到');
     }
     else {
         // Extract section content (from header to next ## or end)
@@ -183,7 +182,7 @@ export function checkSkillTagsValid(tasksContent, parsedTasks, knownSkillNames)
         });
         // Need at least 2 rows (header + 1 data row)
         if (!dataRows || dataRows.length < 2) {
-            result.errors.push('Skill Mapping table has no data rows');
+            result.errors.push('Skill Mapping 表格无数据行');
         }
     }
     // If no tasks, consider it valid
@@ -196,7 +195,7 @@ export function checkSkillTagsValid(tasksContent, parsedTasks, knownSkillNames)
     for (const task of parsedTasks) {
         // b. Check if task has skill tag
         if (task.skills.length === 0) {
-            result.errors.push(`Task ${task.id}: missing @skill tag`);
+            result.errors.push(`任务 ${task.id}: 缺少 @skill 标签`);
             continue;
         }
         // Validate each skill
@@ -214,7 +213,7 @@ export function checkSkillTagsValid(tasksContent, parsedTasks, knownSkillNames)
                     descLower.includes('verify') ||
                     task.description.length > 30; // Substantial description is acceptable
                 if (!hasReason) {
-                    result.warnings.push(`Task ${task.id}: @skill:none should have a reason in description`);
+                    result.warnings.push(`任务 ${task.id}: @skill:none 应在描述中说明原因`);
                 }
                 continue;
             }
@@ -223,7 +222,7 @@ export function checkSkillTagsValid(tasksContent, parsedTasks, knownSkillNames)
                 const availableSkills = knownSkillNames.length <= 10
                     ? knownSkillNames.join(', ')
                     : `${knownSkillNames.slice(0, 10).join(', ')}... (${knownSkillNames.length} total)`;
-                result.errors.push(`Task ${task.id}: @skill:${skill} is not a known skill. Available skills: ${availableSkills}`);
+                result.errors.push(`任务 ${task.id}: @skill:${skill} 不是已知的 skill。可用 skills: ${availableSkills}`);
             }
         }
     }
@@ -242,7 +241,7 @@ export function checkSkillTagsValid(tasksContent, parsedTasks, knownSkillNames)
 export function checkTaskOrderingByWave(tasksContent, parsedTasks) {
     const result = {
         ruleId: 'task-ordering-by-wave',
-        ruleName: 'Task ordering by wave',
+        ruleName: '任务 Wave 排序校验',
         passed: false,
         errors: [],
         warnings: [],
@@ -263,13 +262,13 @@ export function checkTaskOrderingByWave(tasksContent, parsedTasks) {
         });
     }
     if (waveHeaders.length === 0) {
-        result.errors.push('No Wave headers found in tasks.md. Expected format: "### Wave N"');
+        result.errors.push('tasks.md 中未找到 Wave 头部。期望格式: "### Wave N"');
         return result;
     }
     // Generate execution plan to get actual waves
     const executionPlan = generateExecutionPlan(parsedTasks);
     if (executionPlan.hasCycle) {
-        result.errors.push('Task dependency graph has cycles, cannot validate wave ordering');
+        result.errors.push('任务依赖图存在循环，无法校验 Wave 排序');
         return result;
     }
     // Build a map of task ID to actual wave number
@@ -302,7 +301,7 @@ export function checkTaskOrderingByWave(tasksContent, parsedTasks) {
     let lastWave = 0;
     for (const task of taskPositions) {
         if (task.actualWave < lastWave) {
-            result.errors.push(`Task ${task.id} (wave ${task.actualWave}) appears after tasks of wave ${lastWave}`);
+            result.errors.push(`任务 ${task.id}（Wave ${task.actualWave}）出现在 Wave ${lastWave} 的任务之后`);
         }
         lastWave = Math.max(lastWave, task.actualWave);
     }
@@ -311,18 +310,18 @@ export function checkTaskOrderingByWave(tasksContent, parsedTasks) {
     const declaredWaveNumbers = new Set(waveHeaders.map(h => h.wave));
     for (const declared of declaredWaveNumbers) {
         if (!actualWaveNumbers.has(declared)) {
-            result.warnings.push(`Wave header "### Wave ${declared}" does not match any computed wave`);
+            result.warnings.push(`Wave 头部 "### Wave ${declared}" 与计算得到的 Wave 不匹配`);
         }
     }
     for (const actual of actualWaveNumbers) {
         if (!declaredWaveNumbers.has(actual)) {
-            result.errors.push(`Missing Wave header for computed wave ${actual}`);
+            result.errors.push(`缺少计算得到的 Wave ${actual} 的头部`);
         }
     }
     // Check wave header ordering
     for (let i = 1; i < waveHeaders.length; i++) {
         if (waveHeaders[i].wave <= waveHeaders[i - 1].wave) {
-            result.errors.push(`Wave headers are not in ascending order: Wave ${waveHeaders[i - 1].wave} followed by Wave ${waveHeaders[i].wave}`);
+            result.errors.push(`Wave 头部未按升序排列: Wave ${waveHeaders[i - 1].wave} 后面是 Wave ${waveHeaders[i].wave}`);
         }
     }
     result.passed = result.errors.length === 0;
@@ -341,7 +340,7 @@ export function checkTaskOrderingByWave(tasksContent, parsedTasks) {
 export function checkSubagentDirectives(parsedTasks) {
     const result = {
         ruleId: 'subagent-directives-valid',
-        ruleName: 'Subagent directives valid',
+        ruleName: '子代理指令校验',
         passed: false,
         errors: [],
         warnings: [],
@@ -354,7 +353,7 @@ export function checkSubagentDirectives(parsedTasks) {
     // Generate execution plan
     const executionPlan = generateExecutionPlan(parsedTasks);
     if (executionPlan.hasCycle) {
-        result.errors.push('Task dependency graph has cycles, cannot validate subagent directives');
+        result.errors.push('任务依赖图存在循环，无法校验子代理指令');
         return result;
     }
     if (executionPlan.waves.length === 0) {
@@ -370,24 +369,24 @@ export function checkSubagentDirectives(parsedTasks) {
         // Check subagent_count attribute exists with correct value
         const subagentCountPattern = new RegExp(`<wave[^>]*number="${wave.wave}"[^>]*subagent_count="${taskCount}"`);
         if (!subagentCountPattern.test(xml)) {
-            result.errors.push(`Wave ${wave.wave}: missing or incorrect subagent_count attribute (expected ${taskCount})`);
+            result.errors.push(`Wave ${wave.wave}: 缺少或错误的 subagent_count 属性（期望 ${taskCount}）`);
         }
         // Check execution_mode attribute exists with correct value
         const executionModePattern = new RegExp(`<wave[^>]*number="${wave.wave}"[^>]*execution_mode="${expectedMode}"`);
         if (!executionModePattern.test(xml)) {
-            result.errors.push(`Wave ${wave.wave}: missing or incorrect execution_mode attribute (expected "${expectedMode}")`);
+            result.errors.push(`Wave ${wave.wave}: 缺少或错误的 execution_mode 属性（期望 "${expectedMode}"）`);
         }
     }
     // Validate scheduling_summary section exists
     if (!xml.includes('<scheduling_summary>')) {
-        result.errors.push('Missing <scheduling_summary> section in orchestration_strategy');
+        result.errors.push('编排策略中缺少 <scheduling_summary> 节点');
     }
     else {
         // Validate each wave has a scheduling summary entry
         for (const wave of executionPlan.waves) {
             const waveSummaryPattern = new RegExp(`Wave ${wave.wave} \u2192`);
             if (!waveSummaryPattern.test(xml)) {
-                result.errors.push(`Wave ${wave.wave}: missing scheduling summary entry in <scheduling_summary>`);
+                result.errors.push(`Wave ${wave.wave}: <scheduling_summary> 中缺少调度摘要条目`);
             }
         }
     }
@@ -402,7 +401,7 @@ export function checkSubagentDirectives(parsedTasks) {
 export function checkReviewGateDefined(tasksContent) {
     const result = {
         ruleId: 'review-gate-defined',
-        ruleName: 'Review gate defined',
+        ruleName: 'Review 门禁定义',
         passed: false,
         errors: [],
         warnings: [],
@@ -411,7 +410,7 @@ export function checkReviewGateDefined(tasksContent) {
         /review\s*gate/i.test(tasksContent) ||
         /双轨审查/.test(tasksContent);
     if (!hasReviewGate) {
-        result.errors.push('tasks.md must include a zhuanspec review gate before completion');
+        result.errors.push('tasks.md 必须包含 zhuanspec review 门禁');
         return result;
     }
     result.passed = true;
@@ -428,7 +427,7 @@ export function checkReviewGateDefined(tasksContent) {
 export function checkProposalFormatValid(proposalContent) {
     const result = {
         ruleId: 'proposal-format-valid',
-        ruleName: 'Proposal format valid',
+        ruleName: '提案格式校验',
         passed: false,
         errors: [],
         warnings: [],
@@ -571,7 +570,7 @@ function extractScenarioDimensions(name, description) {
 function checkSpecCodeConsistent(specsDir, repoRoot, phase) {
     const result = {
         ruleId: 'spec-code-consistent',
-        ruleName: 'Spec-Code consistency',
+        ruleName: 'Spec-代码一致性',
         passed: false,
         errors: [],
         warnings: [],
@@ -579,7 +578,7 @@ function checkSpecCodeConsistent(specsDir, repoRoot, phase) {
     // Skip this check in Propose phase
     if (phase === 'propose') {
         result.passed = true;
-        result.warnings.push('SKIPPED (Propose phase) - no code changes to validate');
+        result.warnings.push('跳过（Propose 阶段）— 还没有代码变更可校验');
         return result;
     }
     // If specsDir doesn't exist, skip this check
@@ -756,7 +755,7 @@ function checkSpecCodeConsistent(specsDir, repoRoot, phase) {
 export function checkFileConflicts(parsedTasks) {
     const result = {
         ruleId: 'file-conflict-detection',
-        ruleName: 'File conflict detection',
+        ruleName: '文件冲突检测',
         passed: true,
         errors: [],
         warnings: [],
@@ -784,8 +783,8 @@ export function checkFileConflicts(parsedTasks) {
         for (const [file, taskIds] of fileToTasks) {
             if (taskIds.length >= 2) {
                 result.passed = false;
-                result.errors.push(`File conflict in Wave ${wave}: "${file}" is modified by tasks [${taskIds.join(', ')}]. ` +
-                    `Add @depends to specify execution order or tasks will be serialized automatically.`);
+                result.errors.push(`Wave ${wave} 文件冲突: "${file}" 被任务 [${taskIds.join(', ')}] 同时修改。` +
+                    `请添加 @depends 指定执行顺序，否则任务将自动串行化。`);
             }
         }
     }
@@ -805,7 +804,7 @@ export function checkFileConflicts(parsedTasks) {
 export function checkTestCaseCoverage(tasksContent, hasTestCase = false) {
     const result = {
         ruleId: 'test-case-coverage',
-        ruleName: 'Test case coverage',
+        ruleName: '测试用例覆盖',
         passed: false,
         errors: [],
         warnings: [],
@@ -813,13 +812,13 @@ export function checkTestCaseCoverage(tasksContent, hasTestCase = false) {
     // If no test case mode, skip with warning
     if (!hasTestCase) {
         result.passed = true;
-        result.warnings.push('SKIPPED (no test case mode) - test-case-coverage check only applies when test cases are provided');
+        result.warnings.push('跳过（无测试用例模式）— test-case-coverage 检查仅在提供测试用例时生效');
         return result;
     }
     // Check for Test Case Coverage section (required when hasTestCase=true)
     const testCaseSectionPattern = /^##\s+Test\s+Case\s+Coverage/im;
     if (!testCaseSectionPattern.test(tasksContent)) {
-        result.errors.push('Missing Test Case Coverage section - REQUIRED when test cases are provided (TDD mode or user-provided cases)');
+        result.errors.push('缺少 Test Case Coverage 章节 — 提供测试用例时必须填写（TDD 模式或用户提供）');
         return result;
     }
     // Check for @test-case tags in tasks
@@ -829,7 +828,7 @@ export function checkTestCaseCoverage(tasksContent, hasTestCase = false) {
         result.passed = true;
     }
     else {
-        result.errors.push('No @test-case tags found - REQUIRED when test cases are provided. Link tasks to test cases using @test-case:TC-XXX');
+        result.errors.push('未找到 @test-case 标签 — 提供测试用例时必须使用 @test-case:TC-XXX 关联任务与测试用例');
     }
     // Validate Test Case Coverage table format (four columns required)
     // Expected headers: Task, 测试 Case ID, 测试 Case 文件路径, 覆盖场景
@@ -841,7 +840,7 @@ export function checkTestCaseCoverage(tasksContent, hasTestCase = false) {
         if (headerLine) {
             const columns = headerLine.split('|').filter(col => col.trim() !== '');
             if (columns.length < 4) {
-                result.warnings.push(`Test Case Coverage table should have 4 columns (Task, 测试 Case ID, 测试 Case 文件路径, 覆盖场景), found ${columns.length}`);
+                result.warnings.push(`Test Case Coverage 表格应有 4 列（Task, 测试 Case ID, 测试 Case 文件路径, 覆盖场景），当前 ${columns.length} 列`);
             }
             else {
                 // Check column names contain expected keywords
@@ -851,13 +850,13 @@ export function checkTestCaseCoverage(tasksContent, hasTestCase = false) {
                 const hasPathCol = headerText.includes('文件路径') || headerText.includes('path') || headerText.includes('路径');
                 const hasScenarioCol = headerText.includes('覆盖场景') || headerText.includes('场景') || headerText.includes('scenario');
                 if (!hasTaskCol || !hasTestCaseIdCol || !hasPathCol || !hasScenarioCol) {
-                    result.warnings.push('Test Case Coverage table headers should follow format: Task, 测试 Case ID, 测试 Case 文件路径, 覆盖场景');
+                    result.warnings.push('Test Case Coverage 表格列头格式不匹配，应为: Task, 测试 Case ID, 测试 Case 文件路径, 覆盖场景');
                 }
             }
         }
     }
     else {
-        result.warnings.push('Test Case Coverage table format not detected - ensure table has 4 columns with proper headers');
+        result.warnings.push('Test Case Coverage 表格格式未检测到 — 请确保表格有 4 列且列头正确');
     }
     return result;
 }
@@ -866,30 +865,64 @@ export function checkTestCaseCoverage(tasksContent, hasTestCase = false) {
  *
  * When a tech-spec document exists, validates that the technical spec
  * adequately covers the proposal's requirements.
- * This is a basic framework - full logic will be implemented in Task 7's Skill.
  *
- * Tech spec document lookup order:
- *   1. techDesign/tech-spec.md (standard path)
- *   2. tech-spec.md in the proposal root directory
- *   3. 用户提供本地技术方案路径
+ * Tech spec document lookup order (priority):
+ *   1. 用户通过 --tech-spec 指定的外部路径 (externalTechSpecPath)
+ *   2. techDesign/ 目录下的任意 .md 文件（文件名不限定为 tech-spec.md）
+ *   3. 提案根目录下的任意技术方案相关 .md 文件
  *
  * Checks:
- *   - tech-spec.md file exists and is non-empty
- *   - tech-spec.md contains substantive content (not just placeholder)
+ *   - tech-spec file exists and is non-empty
+ *   - tech-spec contains substantive content (not just placeholder)
+ *   - structural elements (DB tables, APIs, classes, etc.) are covered in proposal files
  */
-export function checkTechSpecCoverage(changeDir) {
+export function checkTechSpecCoverage(changeDir, externalTechSpecPath) {
     const result = {
         ruleId: 'tech-spec-coverage',
-        ruleName: 'Tech Spec Coverage',
+        ruleName: '技术方案覆盖率',
         passed: false,
         errors: [],
         warnings: [],
     };
-    // Look for tech-spec.md from multiple sources
-    const candidatePaths = [
-        join(changeDir, 'techDesign', 'tech-spec.md'), // Standard path
-        join(changeDir, 'tech-spec.md'), // Proposal root directory
-    ];
+    // Look for tech-spec from multiple sources (priority order):
+    //   1. User-specified external path via --tech-spec
+    //   2. Any .md file under techDesign/ directory (filename NOT restricted to tech-spec.md)
+    //   3. Any tech-spec-like .md file in proposal root directory
+    const candidatePaths = [];
+    if (externalTechSpecPath) {
+        // Resolve external path: could be absolute or relative to cwd
+        const resolved = path.isAbsolute(externalTechSpecPath)
+            ? externalTechSpecPath
+            : join(process.cwd(), externalTechSpecPath);
+        candidatePaths.push(resolved);
+    }
+    // Scan techDesign/ directory for any .md files (not just tech-spec.md)
+    const techDesignDir = join(changeDir, 'techDesign');
+    if (existsSync(techDesignDir)) {
+        try {
+            const entries = readdirSync(techDesignDir);
+            for (const entry of entries) {
+                if (entry.endsWith('.md')) {
+                    candidatePaths.push(join(techDesignDir, entry));
+                }
+            }
+        }
+        catch {
+            // Ignore read errors
+        }
+    }
+    // Also check proposal root for any tech-spec-like files
+    try {
+        const rootEntries = readdirSync(changeDir);
+        for (const entry of rootEntries) {
+            if (entry.endsWith('.md') && entry !== 'design.md' && entry !== 'tasks.md' && entry !== 'proposal.md') {
+                candidatePaths.push(join(changeDir, entry));
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
     let techSpecPath = null;
     for (const candidate of candidatePaths) {
         if (existsSync(candidate)) {
@@ -898,9 +931,9 @@ export function checkTechSpecCoverage(changeDir) {
         }
     }
     if (!techSpecPath) {
-        // No tech-spec.md found anywhere — skip check gracefully
+        // No tech-spec found anywhere — skip check gracefully
         result.passed = true;
-        result.warnings.push('No tech-spec.md found (checked techDesign/tech-spec.md and proposal root) — skipping coverage check');
+        result.warnings.push('未找到技术方案文档（已检查外部路径、techDesign/tech-spec.md 和提案根目录）— 跳过覆盖率检查');
         return result;
     }
     let content;
@@ -908,13 +941,13 @@ export function checkTechSpecCoverage(changeDir) {
         content = readFileSync(techSpecPath, 'utf-8');
     }
     catch {
-        result.errors.push(`Failed to read ${path.relative(changeDir, techSpecPath)}`);
+        result.errors.push(`无法读取 ${path.relative(changeDir, techSpecPath)}`);
         return result;
     }
     // Check if content is just the placeholder template
     const stripped = content.replace(/^#.*$/gm, '').replace(/^>.*$/gm, '').replace(/^(created|source):.*$/gm, '').trim();
     if (stripped.length < 50) {
-        result.warnings.push('techDesign/tech-spec.md appears to be a placeholder — populate with actual technical spec content');
+        result.warnings.push('techDesign/tech-spec.md 似乎是占位模板 — 请填充实际技术方案内容');
         result.passed = true;
         return result;
     }
@@ -923,7 +956,7 @@ export function checkTechSpecCoverage(changeDir) {
     const elements = extractTechSpecElements(content);
     const totalElements = elements.length;
     if (totalElements === 0) {
-        result.warnings.push('No structured elements (tables, APIs, classes, configs) detected in tech-spec.md — skipping coverage check');
+        result.warnings.push('tech-spec.md 中未检测到结构化元素（表、API、类、配置）— 跳过覆盖率检查');
         result.passed = true;
         return result;
     }
@@ -1160,7 +1193,7 @@ const TASK_ID_PATTERN = /^\d+\.\d+$/;
 export function checkTaskIdFormat(tasksContent) {
     const result = {
         ruleId: 'task-id-format',
-        ruleName: 'Task ID format',
+        ruleName: '任务 ID 格式',
         passed: false,
         errors: [],
         warnings: [],
@@ -1174,11 +1207,83 @@ export function checkTaskIdFormat(tasksContent) {
         }
     }
     if (invalidIds.length > 0) {
-        result.errors = invalidIds.map(id => `Invalid task ID "${id}": must be N.M format (e.g., 1.1, 2.3)`);
+        result.errors = invalidIds.map(id => `无效任务 ID "${id}": 必须为 N.M 格式（如 1.1, 2.3）`);
     }
     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: '任务复选框格式',
+        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(`检测到旧格式任务: "${header.trim()}"。` +
+                `必须使用复选框格式: "- [ ] N.M 描述" 或 "- [x] N.M 描述"`);
+        }
+    }
+    // 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.errors.push(`任务行缺少复选框: "${trimmed.substring(0, 80)}"。` +
+                    `必须使用复选框格式: "- [ ] N.M 描述" 或 "- [x] N.M 描述"`);
+            }
+        }
+    }
+    // 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 checkbox tasks found - this is an ERROR because all tasks MUST use checkbox format
+        result.errors.push('Wave 头部下未找到复选框格式的任务。' +
+            '所有任务必须使用 GitHub Flavored Markdown 复选框格式: "- [ ] N.M 描述"（待办）或 "- [x] N.M 描述"（已完成）。' +
+            '禁止使用 #### 头部、纯文本或 emoji 标记。');
+    }
+    // 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(`任务使用了 ✅ emoji 但复选框未勾选: "${line.trim().substring(0, 80)}"。` +
+                `请使用 "- [x]" 标记完成，而非 ✅ emoji`);
+        }
+    }
+    result.passed = result.errors.length === 0;
+    return result;
+}
 /**
  * Main entry: Run all strict validation rules
  */
@@ -1194,17 +1299,30 @@ 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) {
         checks.push(checkProposalFormatValid(options.proposalContent));
     }
     // Add tech-spec-coverage rule if any tech spec document exists
+    // Trigger when: techDesign/ directory has any .md files OR external --tech-spec path provided
     if (options?.changeDir) {
-        const hasTechSpec = existsSync(join(options.changeDir, 'techDesign', 'tech-spec.md')) ||
-            existsSync(join(options.changeDir, 'tech-spec.md'));
+        let hasTechSpec = !!options.techSpecPath;
+        if (!hasTechSpec) {
+            const techDesignDir = join(options.changeDir, 'techDesign');
+            if (existsSync(techDesignDir)) {
+                try {
+                    const entries = readdirSync(techDesignDir);
+                    hasTechSpec = entries.some((e) => e.endsWith('.md'));
+                }
+                catch {
+                    // Ignore
+                }
+            }
+        }
         if (hasTechSpec) {
-            checks.push(checkTechSpecCoverage(options.changeDir));
+            checks.push(checkTechSpecCoverage(options.changeDir, options.techSpecPath));
         }
     }
     // Detect current phase for spec-code consistency check

package/dist/core/validation/validator.js

@@ -324,12 +324,33 @@ export class Validator {
                         // No metadata file - assume spec-driven (no test cases)
                     }
                 }
+                // Detect external tech-spec path from @ref tags in tasks.md
+                // Format: @ref:/path/to/tech-spec.md#section or @ref:techDesign/tech-spec.md#section
+                // Note: the tech spec filename is NOT limited to 'tech-spec.md' — any .md file
+                // referenced via @ref that is NOT under the standard techDesign/ directory
+                // is treated as a potential external tech spec document.
+                let techSpecPath;
+                const refMatches = tasksContent.match(/@ref:([^\s#]+)/g);
+                if (refMatches) {
+                    for (const refTag of refMatches) {
+                        const refPath = refTag.replace('@ref:', '');
+                        // Skip standard techDesign/ paths — those are already handled by default lookup
+                        if (refPath.startsWith('techDesign/'))
+                            continue;
+                        // Any external .md file is a potential tech spec (filename is not restricted)
+                        if (refPath.endsWith('.md')) {
+                            techSpecPath = refPath;
+                            break;
+                        }
+                    }
+                }
                 const strictResult = await runStrictValidation(tasksContent, parsedTasks, knownSkillNames, {
                     proposalContent,
                     specsDir,
                     repoRoot,
                     changeDir,
                     hasTestCase,
+                    techSpecPath,
                 });
                 strictChecks = strictResult.checks;
                 // Merge strict errors into main issues

package/dist/utils/task-progress.js

@@ -2,8 +2,8 @@ import { promises as fs } from 'fs';
 import path from 'path';
 const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
 const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
-const TASK_HEADER_PATTERN = /^####\s*(?:Task\s+\d+\.\d+|T\d+)\s*:/;
-const COMPLETED_HEADER_PATTERN = /^####\s*(?:Task\s+\d+\.\d+|T\d+)\s*:.*\u2705\s*$/;
+const TASK_HEADER_PATTERN = /^####\s*(?:Task\s+)?\d+\.\d+[\s:]|^####\s*T\d+\s*:/;
+const COMPLETED_HEADER_PATTERN = /^####\s*(?:Task\s+)?\d+\.\d+[\s:].*\u2705|^####\s*T\d+\s*:.*\u2705\s*$/;
 export function countTasksFromContent(content) {
     const lines = content.split('\n');
     let total = 0;