@zhuan-ai/zhuanspec 2.0.0 → 2.1.0

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

@@ -0,0 +1,287 @@
+/**
+ * Strict Validation Rules
+ *
+ * Implementation of three strict validation rules for `zhuanspec validate --strict`:
+ * 1. pre-clarification-completed: Check Pre-Clarification Log section
+ * 2. skill-tags-valid: Validate @skill tags against known skills
+ * 3. task-ordering-by-wave: Verify task ordering follows wave structure
+ */
+import { generateExecutionPlan } from '../task-graph/execution-planner.js';
+// Patterns for detecting unresolved markers
+const UNRESOLVED_MARKERS = /\b(TODO|TBD|PENDING|\?)\b/i;
+const HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
+const PRE_CLARIFICATION_SECTION_PATTERN = /^##\s+Pre-Clarification\s+Log\s*$/im;
+const VALID_COMPLETION_MARKERS = [
+    /no\s+clarification\s+needed/i,
+    /status:\s*completed/i,
+];
+// Skill mapping section header pattern
+const SKILL_MAPPING_SECTION_PATTERN = /^##\s+Skill\s+Mapping\s*$/im;
+// Table data row pattern (starts with |, not a separator row like |---|---|)
+const TABLE_DATA_ROW_PATTERN = /^\|(?![-:|\s]+\|$)[^\n]+\|/gm;
+const SKILL_TAG_PATTERN = /@skill:([^\s@]+)/g;
+// Wave header pattern
+const WAVE_HEADER_PATTERN = /^###\s+Wave\s+(\d+)/im;
+/**
+ * Rule 1: pre-clarification-completed
+ *
+ * Checks that tasks.md has a valid "## Pre-Clarification Log" section.
+ * Valid content includes:
+ *   - Actual Q&A record text
+ *   - "No clarification needed"
+ *   - "Status: COMPLETED"
+ * Invalid:
+ *   - Section missing
+ *   - Section empty (whitespace only)
+ *   - Only HTML comments
+ *   - Contains "TODO", "TBD", "PENDING", "?" unresolved markers
+ */
+export function checkPreClarification(tasksContent) {
+    const result = {
+        ruleId: 'pre-clarification-completed',
+        ruleName: 'Pre-clarification completed',
+        passed: false,
+        errors: [],
+        warnings: [],
+    };
+    // Check if section exists
+    const sectionMatch = tasksContent.match(PRE_CLARIFICATION_SECTION_PATTERN);
+    if (!sectionMatch) {
+        result.errors.push('Pre-Clarification Log section is missing');
+        return result;
+    }
+    // Extract section content (from header to next ## or end)
+    const sectionStartIndex = sectionMatch.index + sectionMatch[0].length;
+    const nextSectionMatch = tasksContent.slice(sectionStartIndex).match(/^##\s+/m);
+    const sectionEndIndex = nextSectionMatch
+        ? sectionStartIndex + nextSectionMatch.index
+        : tasksContent.length;
+    let sectionContent = tasksContent.slice(sectionStartIndex, sectionEndIndex);
+    // Remove HTML comments for content analysis
+    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');
+        return result;
+    }
+    // Check for unresolved markers
+    if (UNRESOLVED_MARKERS.test(contentWithoutComments)) {
+        result.errors.push('Pre-Clarification Log contains unresolved markers (TODO, TBD, PENDING, or ?)');
+        return result;
+    }
+    // Check for valid completion markers or actual content
+    const hasValidCompletionMarker = VALID_COMPLETION_MARKERS.some(pattern => pattern.test(contentWithoutComments));
+    const hasSubstantiveContent = contentWithoutComments.length > 20; // More than just a few words
+    if (hasValidCompletionMarker || hasSubstantiveContent) {
+        result.passed = true;
+    }
+    else {
+        result.errors.push('Pre-Clarification Log does not contain valid completion markers or substantive Q&A content');
+    }
+    return result;
+}
+/**
+ * Rule 2: skill-tags-valid
+ *
+ * Validates:
+ *   a. Skill Mapping table exists with at least one data row
+ *   b. Each task has @skill:xxx tag or @skill:none
+ *   c. @skill:none tasks should have a reason in description
+ *   d. All @skill:xxx names must exist in knownSkillNames
+ *   e. Comma-separated multi-skills are validated individually
+ */
+export function checkSkillTagsValid(tasksContent, parsedTasks, knownSkillNames) {
+    const result = {
+        ruleId: 'skill-tags-valid',
+        ruleName: 'Skill tags valid',
+        passed: false,
+        errors: [],
+        warnings: [],
+    };
+    // a. Check Skill Mapping section exists with table data
+    const sectionMatch = tasksContent.match(SKILL_MAPPING_SECTION_PATTERN);
+    if (!sectionMatch) {
+        result.warnings.push('Skill Mapping section not found');
+    }
+    else {
+        // Extract section content (from header to next ## or end)
+        const sectionStartIndex = sectionMatch.index + sectionMatch[0].length;
+        const nextSectionMatch = tasksContent.slice(sectionStartIndex).match(/^##\s+/m);
+        const sectionEndIndex = nextSectionMatch
+            ? sectionStartIndex + nextSectionMatch.index
+            : tasksContent.length;
+        const sectionContent = tasksContent.slice(sectionStartIndex, sectionEndIndex);
+        // Check for table data rows (lines starting with | that are not separator rows)
+        const tableRows = sectionContent.match(TABLE_DATA_ROW_PATTERN);
+        // Filter out header rows and separator rows
+        const dataRows = tableRows?.filter(row => {
+            const trimmed = row.trim();
+            // Skip separator rows like |---|---| or |:---|---:|
+            if (/^\|[-:\s|]+\|$/.test(trimmed))
+                return false;
+            // Skip header rows (first non-separator row is header)
+            return true;
+        });
+        // Need at least 2 rows (header + 1 data row)
+        if (!dataRows || dataRows.length < 2) {
+            result.warnings.push('Skill Mapping table has no data rows');
+        }
+    }
+    // If no tasks, consider it valid
+    if (parsedTasks.length === 0) {
+        result.passed = true;
+        return result;
+    }
+    // b, c, d, e. Validate each task's skill tags
+    const knownSkillSet = new Set(knownSkillNames.map(s => s.toLowerCase()));
+    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`);
+            continue;
+        }
+        // Validate each skill
+        for (const skill of task.skills) {
+            const skillLower = skill.toLowerCase();
+            // c. @skill:none should have a reason
+            if (skillLower === 'none') {
+                // Check if description mentions why no skill needed
+                const descLower = task.description.toLowerCase();
+                const hasReason = descLower.includes('manual') ||
+                    descLower.includes('review') ||
+                    descLower.includes('document') ||
+                    descLower.includes('config') ||
+                    descLower.includes('test') ||
+                    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`);
+                }
+                continue;
+            }
+            // d. Validate skill exists in known skills
+            if (knownSkillNames.length > 0 && !knownSkillSet.has(skillLower)) {
+                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}`);
+            }
+        }
+    }
+    // Passed if no errors
+    result.passed = result.errors.length === 0;
+    return result;
+}
+/**
+ * Rule 3: task-ordering-by-wave
+ *
+ * Validates:
+ *   - Tasks are ordered by wave (wave 1 tasks before wave 2, etc.)
+ *   - Wave headers "### Wave N" match actual computed wave numbers
+ *   - Tasks.md must have Wave headers
+ */
+export function checkTaskOrderingByWave(tasksContent, parsedTasks) {
+    const result = {
+        ruleId: 'task-ordering-by-wave',
+        ruleName: 'Task ordering by wave',
+        passed: false,
+        errors: [],
+        warnings: [],
+    };
+    // If no tasks, consider it valid
+    if (parsedTasks.length === 0) {
+        result.passed = true;
+        return result;
+    }
+    // Check for wave headers
+    const waveHeaders = [];
+    const waveHeaderRegex = /^###\s+Wave\s+(\d+)/gim;
+    let match;
+    while ((match = waveHeaderRegex.exec(tasksContent)) !== null) {
+        waveHeaders.push({
+            wave: parseInt(match[1], 10),
+            position: match.index,
+        });
+    }
+    if (waveHeaders.length === 0) {
+        result.errors.push('No Wave headers found in tasks.md. Expected format: "### 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');
+        return result;
+    }
+    // Build a map of task ID to actual wave number
+    const taskToWave = new Map();
+    for (const wave of executionPlan.waves) {
+        for (const task of wave.tasks) {
+            taskToWave.set(task.id, wave.wave);
+        }
+    }
+    // Find task positions in content
+    const taskPositions = [];
+    for (const task of parsedTasks) {
+        // Find task line in content
+        const taskPattern = new RegExp(`-\\s+\\[[ xX]\\]\\s+${task.id.replace('.', '\\.')}\\s`, 'gm');
+        const taskMatch = taskPattern.exec(tasksContent);
+        if (taskMatch) {
+            const actualWave = taskToWave.get(task.id);
+            if (actualWave !== undefined) {
+                taskPositions.push({
+                    id: task.id,
+                    position: taskMatch.index,
+                    actualWave,
+                });
+            }
+        }
+    }
+    // Sort by position in file
+    taskPositions.sort((a, b) => a.position - b.position);
+    // Check ordering: all tasks of wave N should appear before tasks of wave N+1
+    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}`);
+        }
+        lastWave = Math.max(lastWave, task.actualWave);
+    }
+    // Validate wave headers match actual wave numbers
+    const actualWaveNumbers = new Set(executionPlan.waves.map(w => w.wave));
+    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`);
+        }
+    }
+    for (const actual of actualWaveNumbers) {
+        if (!declaredWaveNumbers.has(actual)) {
+            result.errors.push(`Missing Wave header for computed 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.passed = result.errors.length === 0;
+    return result;
+}
+/**
+ * Main entry: Run all strict validation rules
+ */
+export async function runStrictValidation(tasksContent, parsedTasks, knownSkillNames) {
+    const checks = [
+        checkPreClarification(tasksContent),
+        checkSkillTagsValid(tasksContent, parsedTasks, knownSkillNames),
+        checkTaskOrderingByWave(tasksContent, parsedTasks),
+    ];
+    const allPassed = checks.every(check => check.passed);
+    return {
+        checks,
+        allPassed,
+    };
+}
+//# sourceMappingURL=strict-rules.js.map

package/dist/core/validation/types.d.ts

@@ -6,6 +6,13 @@ export interface ValidationIssue {
     line?: number;
     column?: number;
 }
+export interface StrictCheckSummary {
+    ruleId: string;
+    ruleName: string;
+    passed: boolean;
+    errors: string[];
+    warnings: string[];
+}
 export interface ValidationReport {
     valid: boolean;
     issues: ValidationIssue[];
@@ -14,5 +21,8 @@ export interface ValidationReport {
         warnings: number;
         info: number;
     };
+    strictChecks?: StrictCheckSummary[];
+    /** Mermaid diagram content if task graph analysis succeeded */
+    mermaidDiagram?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/core/validation/validator.d.ts

@@ -29,5 +29,10 @@ export declare class Validator {
     private containsShallOrMust;
     private countScenarios;
     private formatSectionList;
+    /**
+     * Find project root directory by walking up from changeDir.
+     * Looks for common project markers like package.json, .git, or skills directory.
+     */
+    private findProjectRoot;
 }
 //# sourceMappingURL=validator.d.ts.map

package/dist/core/validation/validator.js

@@ -6,6 +6,12 @@ import { ChangeParser } from '../parsers/change-parser.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
 import { parseDeltaSpec, normalizeRequirementName } from '../parsers/requirement-blocks.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
+import { runStrictValidation } from './strict-rules.js';
+import { discoverSkills } from '../skill-discovery.js';
+import { existsSync } from 'fs';
+import { parseTasks } from '../task-graph/task-parser.js';
+import { generateExecutionPlan } from '../task-graph/execution-planner.js';
+import { renderMermaidDiagram } from '../task-graph/mermaid-renderer.js';
 export class Validator {
     strictMode;
     constructor(strictMode = false) {
@@ -253,7 +259,84 @@ export class Validator {
         if (totalDeltas === 0) {
             issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
         }
-        return this.createReport(issues);
+        // Strict mode validation for tasks.md
+        let strictChecks;
+        if (this.strictMode) {
+            const tasksFile = path.join(changeDir, 'tasks.md');
+            let tasksContent;
+            try {
+                tasksContent = await fs.readFile(tasksFile, 'utf-8');
+            }
+            catch {
+                // tasks.md not found - skip strict validation for tasks
+            }
+            if (tasksContent) {
+                const parsedTasks = parseTasks(tasksContent);
+                // Get known skill names
+                let knownSkillNames = [];
+                try {
+                    const projectRoot = this.findProjectRoot(changeDir);
+                    const skills = discoverSkills(projectRoot);
+                    knownSkillNames = skills.map(s => s.name);
+                }
+                catch {
+                    // skill discovery failed - add warning and continue without skill name validation
+                    issues.push({
+                        level: 'WARNING',
+                        path: 'tasks.md',
+                        message: 'Could not discover skills for strict validation — skill name check skipped',
+                    });
+                }
+                // Run strict validation
+                const strictResult = await runStrictValidation(tasksContent, parsedTasks, knownSkillNames);
+                strictChecks = strictResult.checks;
+                // Merge strict errors into main issues
+                for (const check of strictResult.checks) {
+                    for (const error of check.errors) {
+                        issues.push({
+                            level: 'ERROR',
+                            path: 'tasks.md',
+                            message: `[${check.ruleName}] ${error}`,
+                        });
+                    }
+                    for (const warning of check.warnings) {
+                        issues.push({
+                            level: 'WARNING',
+                            path: 'tasks.md',
+                            message: `[${check.ruleName}] ${warning}`,
+                        });
+                    }
+                }
+            }
+        }
+        // Generate Mermaid diagram if tasks.md exists and has tasks
+        let mermaidDiagram;
+        const tasksFile = path.join(changeDir, 'tasks.md');
+        let tasksContentForMermaid;
+        try {
+            tasksContentForMermaid = await fs.readFile(tasksFile, 'utf-8');
+        }
+        catch {
+            // tasks.md not found - skip Mermaid generation
+        }
+        if (tasksContentForMermaid) {
+            const parsedTasksForMermaid = parseTasks(tasksContentForMermaid);
+            if (parsedTasksForMermaid.length > 0) {
+                const executionPlan = generateExecutionPlan(parsedTasksForMermaid);
+                // Only generate Mermaid diagram if execution plan is valid (no cycles)
+                if (!executionPlan.hasCycle && executionPlan.waves.length > 0) {
+                    mermaidDiagram = renderMermaidDiagram(executionPlan, parsedTasksForMermaid);
+                }
+            }
+        }
+        const report = this.createReport(issues);
+        if (strictChecks) {
+            report.strictChecks = strictChecks;
+        }
+        if (mermaidDiagram) {
+            report.mermaidDiagram = mermaidDiagram;
+        }
+        return report;
     }
     convertZodErrors(error) {
         return error.issues.map(err => {
@@ -405,5 +488,24 @@ export class Validator {
         const last = sections[sections.length - 1];
         return `${head.join(', ')} and ${last}`;
     }
+    /**
+     * Find project root directory by walking up from changeDir.
+     * Looks for common project markers like package.json, .git, or skills directory.
+     */
+    findProjectRoot(changeDir) {
+        let current = path.resolve(changeDir);
+        const root = path.parse(current).root;
+        while (current !== root) {
+            // Check for project root markers
+            if (existsSync(path.join(current, 'package.json')) ||
+                existsSync(path.join(current, '.git')) ||
+                existsSync(path.join(current, 'skills'))) {
+                return current;
+            }
+            current = path.dirname(current);
+        }
+        // Fallback to process.cwd() if no markers found
+        return process.cwd();
+    }
 }
 //# sourceMappingURL=validator.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -38,6 +38,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": "pnpm run build",
+    "prepublishOnly": "pnpm 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"
   },
@@ -59,23 +79,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"
   }
-}
+}