specforge-mcp 0.1.0

package/dist/engine/validator.test.js

@@ -0,0 +1,2371 @@
+// SpecForge — Validator Engine Tests (comprehensive, 98%+ coverage)
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// === Mock modules ===
+vi.mock('node:fs/promises', () => ({
+    readFile: vi.fn(),
+    stat: vi.fn(),
+}));
+vi.mock('glob', () => ({
+    glob: vi.fn(),
+}));
+// Import mocked modules so we can control them
+import { readFile, stat } from 'node:fs/promises';
+import { glob } from 'glob';
+// Import the functions under test AFTER mocking
+import { validateSpec, detectDrift, generateChecklist, generateDoR, generateDoD, } from './validator.js';
+// Cast mocked functions for type-safe usage
+const mockReadFile = vi.mocked(readFile);
+const mockStat = vi.mocked(stat);
+const mockGlob = vi.mocked(glob);
+// === Helpers ===
+function makeEstimation(overrides = {}) {
+    return {
+        devHours: 8,
+        reviewHours: 1.6,
+        recommendedModel: 'mixed',
+        tokensOpus: 10000,
+        tokensSonnet: 20000,
+        apiCostUsd: 0.21,
+        hourlyRate: 65,
+        humanCostUsd: 624,
+        totalCostUsd: 624.21,
+        tokenOptimization: {
+            mode: 'local',
+            reasoning: 'test',
+            estimatedTokens: 15000,
+            savings: '~50%',
+        },
+        ...overrides,
+    };
+}
+function makeSpec(overrides = {}) {
+    return {
+        id: 'SPEC-001',
+        title: 'Test Spec Title',
+        slug: 'test-spec-title',
+        type: 'feature',
+        scope: 'feature',
+        status: 'draft',
+        difficulty: 3,
+        risk: 'medium',
+        projectId: 'proj-1',
+        createdAt: '2025-01-01T00:00:00Z',
+        updatedAt: '2025-01-01T00:00:00Z',
+        huPath: '/tmp/HU.md',
+        fichaTecnicaPath: '/tmp/FICHA-TECNICA.md',
+        estimation: makeEstimation(),
+        actuals: null,
+        target: 'backend',
+        tags: [],
+        dependencies: [],
+        blockedBy: [],
+        gitBranch: '',
+        impactAnalysis: null,
+        ...overrides,
+    };
+}
+// === Setup ===
+beforeEach(() => {
+    vi.clearAllMocks();
+    // Default: readFile throws (file not found)
+    mockReadFile.mockRejectedValue(new Error('ENOENT'));
+    // Default: stat throws (file not found)
+    mockStat.mockRejectedValue(new Error('ENOENT'));
+    // Default: glob returns no files
+    mockGlob.mockResolvedValue([]);
+});
+// ============================================================
+// generateDoR
+// ============================================================
+describe('generateDoR', () => {
+    it('should generate all 10 DoR items with the correct specId', () => {
+        const spec = makeSpec();
+        const result = generateDoR(spec);
+        expect(result.items).toHaveLength(10);
+        expect(result.specId).toBe('SPEC-001');
+    });
+    it('should pass title check when title > 3 chars', () => {
+        const result = generateDoR(makeSpec({ title: 'Valid Title' }));
+        expect(result.items.find((i) => i.id === 'dor-1')?.status).toBe('passed');
+    });
+    it('should fail title check when title <= 3 chars', () => {
+        const result = generateDoR(makeSpec({ title: 'AB' }));
+        expect(result.items.find((i) => i.id === 'dor-1')?.status).toBe('failed');
+    });
+    it('should fail title check for exactly 3 chars', () => {
+        const result = generateDoR(makeSpec({ title: 'ABC' }));
+        expect(result.items.find((i) => i.id === 'dor-1')?.status).toBe('failed');
+    });
+    it('should pass type+scope check when both are non-empty', () => {
+        const result = generateDoR(makeSpec({ type: 'feature', scope: 'feature' }));
+        expect(result.items.find((i) => i.id === 'dor-2')?.status).toBe('passed');
+    });
+    it('should fail type+scope check when type is empty', () => {
+        const result = generateDoR(makeSpec({ type: '' }));
+        expect(result.items.find((i) => i.id === 'dor-2')?.status).toBe('failed');
+    });
+    it('should fail type+scope check when scope is empty', () => {
+        const result = generateDoR(makeSpec({ scope: '' }));
+        expect(result.items.find((i) => i.id === 'dor-2')?.status).toBe('failed');
+    });
+    it('should pass difficulty check for values 1-5', () => {
+        for (const d of [1, 2, 3, 4, 5]) {
+            const result = generateDoR(makeSpec({ difficulty: d }));
+            expect(result.items.find((i) => i.id === 'dor-3')?.status).toBe('passed');
+        }
+    });
+    it('should fail difficulty check for out-of-range values', () => {
+        const result = generateDoR(makeSpec({ difficulty: 0 }));
+        expect(result.items.find((i) => i.id === 'dor-3')?.status).toBe('failed');
+    });
+    it('should fail difficulty check for value above 5', () => {
+        const result = generateDoR(makeSpec({ difficulty: 6 }));
+        expect(result.items.find((i) => i.id === 'dor-3')?.status).toBe('failed');
+    });
+    it('should pass estimation check when devHours > 0', () => {
+        const result = generateDoR(makeSpec({ estimation: makeEstimation({ devHours: 5 }) }));
+        expect(result.items.find((i) => i.id === 'dor-4')?.status).toBe('passed');
+    });
+    it('should fail estimation check when devHours is 0', () => {
+        const result = generateDoR(makeSpec({ estimation: makeEstimation({ devHours: 0 }) }));
+        expect(result.items.find((i) => i.id === 'dor-4')?.status).toBe('failed');
+    });
+    it('should pass HU check when huPath is set', () => {
+        const result = generateDoR(makeSpec({ huPath: '/some/HU.md' }));
+        expect(result.items.find((i) => i.id === 'dor-5')?.status).toBe('passed');
+    });
+    it('should fail HU check when huPath is empty', () => {
+        const result = generateDoR(makeSpec({ huPath: '' }));
+        expect(result.items.find((i) => i.id === 'dor-5')?.status).toBe('failed');
+    });
+    it('should pass ficha check when fichaTecnicaPath is set', () => {
+        const result = generateDoR(makeSpec({ fichaTecnicaPath: '/some/FICHA.md' }));
+        expect(result.items.find((i) => i.id === 'dor-6')?.status).toBe('passed');
+    });
+    it('should fail ficha check when fichaTecnicaPath is empty', () => {
+        const result = generateDoR(makeSpec({ fichaTecnicaPath: '' }));
+        expect(result.items.find((i) => i.id === 'dor-6')?.status).toBe('failed');
+    });
+    it('should always pass dor-7 (dependencies identified)', () => {
+        const result = generateDoR(makeSpec());
+        expect(result.items.find((i) => i.id === 'dor-7')?.status).toBe('passed');
+    });
+    it('should pass blockedBy check when empty', () => {
+        const result = generateDoR(makeSpec({ blockedBy: [] }));
+        expect(result.items.find((i) => i.id === 'dor-8')?.status).toBe('passed');
+    });
+    it('should fail blockedBy check when non-empty', () => {
+        const result = generateDoR(makeSpec({ blockedBy: ['SPEC-002'] }));
+        expect(result.items.find((i) => i.id === 'dor-8')?.status).toBe('failed');
+    });
+    it('should pass risk check when risk is non-empty', () => {
+        const result = generateDoR(makeSpec({ risk: 'high' }));
+        expect(result.items.find((i) => i.id === 'dor-9')?.status).toBe('passed');
+    });
+    it('should fail risk check when risk is empty', () => {
+        const result = generateDoR(makeSpec({ risk: '' }));
+        expect(result.items.find((i) => i.id === 'dor-9')?.status).toBe('failed');
+    });
+    it('should pass target check when target is non-empty', () => {
+        const result = generateDoR(makeSpec({ target: 'frontend' }));
+        expect(result.items.find((i) => i.id === 'dor-10')?.status).toBe('passed');
+    });
+    it('should fail target check when target is empty', () => {
+        const result = generateDoR(makeSpec({ target: '' }));
+        expect(result.items.find((i) => i.id === 'dor-10')?.status).toBe('failed');
+    });
+    it('should mark isReady=true when all required items pass', () => {
+        const result = generateDoR(makeSpec());
+        expect(result.isReady).toBe(true);
+    });
+    it('should mark isReady=false when any required item fails', () => {
+        const result = generateDoR(makeSpec({ huPath: '' }));
+        expect(result.isReady).toBe(false);
+    });
+    it('should calculate passedCount from items', () => {
+        const result = generateDoR(makeSpec());
+        const expected = result.items.filter((i) => i.status === 'passed').length;
+        expect(result.passedCount).toBe(expected);
+    });
+    it('should calculate requiredCount from required items', () => {
+        const result = generateDoR(makeSpec());
+        const expected = result.items.filter((i) => i.required).length;
+        expect(result.requiredCount).toBe(expected);
+    });
+    it('should include a valid generatedAt ISO timestamp', () => {
+        const result = generateDoR(makeSpec());
+        expect(result.generatedAt).toBeDefined();
+        expect(new Date(result.generatedAt).toISOString()).toBe(result.generatedAt);
+    });
+});
+// ============================================================
+// generateDoD
+// ============================================================
+describe('generateDoD', () => {
+    it('should generate all 8 DoD items', () => {
+        const result = generateDoD(makeSpec());
+        expect(result.items).toHaveLength(8);
+        expect(result.specId).toBe('SPEC-001');
+    });
+    it('should mark acceptance criteria passed when score is 100', () => {
+        const validation = {
+            matches: ['a'],
+            missing: [],
+            extra: [],
+            fieldsImplemented: 1,
+            fieldsTotal: 1,
+            score: 100,
+            qualityIssues: [],
+        };
+        const result = generateDoD(makeSpec(), validation);
+        expect(result.items.find((i) => i.id === 'dod-1')?.status).toBe('passed');
+    });
+    it('should mark acceptance criteria failed when score > 0 but < 100', () => {
+        const validation = {
+            matches: ['a'],
+            missing: ['b'],
+            extra: [],
+            fieldsImplemented: 1,
+            fieldsTotal: 2,
+            score: 50,
+            qualityIssues: [],
+        };
+        const result = generateDoD(makeSpec(), validation);
+        expect(result.items.find((i) => i.id === 'dod-1')?.status).toBe('failed');
+    });
+    it('should mark acceptance criteria pending when score is 0', () => {
+        const validation = {
+            matches: [],
+            missing: ['a'],
+            extra: [],
+            fieldsImplemented: 0,
+            fieldsTotal: 1,
+            score: 0,
+            qualityIssues: [],
+        };
+        const result = generateDoD(makeSpec(), validation);
+        expect(result.items.find((i) => i.id === 'dod-1')?.status).toBe('pending');
+    });
+    it('should mark acceptance criteria pending when no validation provided', () => {
+        const result = generateDoD(makeSpec());
+        expect(result.items.find((i) => i.id === 'dod-1')?.status).toBe('pending');
+    });
+    it('should pass quality check when no quality issues', () => {
+        const validation = {
+            matches: [],
+            missing: [],
+            extra: [],
+            fieldsImplemented: 0,
+            fieldsTotal: 0,
+            score: 0,
+            qualityIssues: [],
+        };
+        const result = generateDoD(makeSpec(), validation);
+        expect(result.items.find((i) => i.id === 'dod-2')?.status).toBe('passed');
+    });
+    it('should fail quality check when quality issues exist', () => {
+        const validation = {
+            matches: [],
+            missing: [],
+            extra: [],
+            fieldsImplemented: 0,
+            fieldsTotal: 0,
+            score: 0,
+            qualityIssues: [
+                {
+                    file: 'x.ts',
+                    category: 'clean-code',
+                    severity: 'warning',
+                    rule: 'test',
+                    message: 'msg',
+                    suggestion: 'fix',
+                },
+            ],
+        };
+        const result = generateDoD(makeSpec(), validation);
+        expect(result.items.find((i) => i.id === 'dod-2')?.status).toBe('failed');
+    });
+    it('should pass quality check when no validation (defaults to 0 issues)', () => {
+        const result = generateDoD(makeSpec());
+        expect(result.items.find((i) => i.id === 'dod-2')?.status).toBe('passed');
+    });
+    it('should mark dod-3 (unit tests) as pending always', () => {
+        const result = generateDoD(makeSpec());
+        expect(result.items.find((i) => i.id === 'dod-3')?.status).toBe('pending');
+    });
+    it('should mark dod-4 (code reviewed) as pending always', () => {
+        const result = generateDoD(makeSpec());
+        expect(result.items.find((i) => i.id === 'dod-4')?.status).toBe('pending');
+    });
+    it('should mark dod-5 (documentation) as pending always', () => {
+        const result = generateDoD(makeSpec());
+        expect(result.items.find((i) => i.id === 'dod-5')?.status).toBe('pending');
+    });
+    it('should mark dod-6 (no regressions) as pending always', () => {
+        const result = generateDoD(makeSpec());
+        expect(result.items.find((i) => i.id === 'dod-6')?.status).toBe('pending');
+    });
+    it('should pass spec status check when status is done', () => {
+        const result = generateDoD(makeSpec({ status: 'done' }));
+        expect(result.items.find((i) => i.id === 'dod-7')?.status).toBe('passed');
+    });
+    it('should mark spec status as pending when status is not done', () => {
+        const result = generateDoD(makeSpec({ status: 'implementing' }));
+        expect(result.items.find((i) => i.id === 'dod-7')?.status).toBe('pending');
+    });
+    it('should pass actuals check when actuals exist', () => {
+        const result = generateDoD(makeSpec({
+            actuals: {
+                devHours: 8,
+                reviewHours: 2,
+                tokensOpus: 10000,
+                tokensSonnet: 20000,
+                apiCostUsd: 0.21,
+                humanCostUsd: 650,
+                totalCostUsd: 650.21,
+                completedAt: '2025-01-01T00:00:00Z',
+                notes: 'done',
+            },
+        }));
+        expect(result.items.find((i) => i.id === 'dod-8')?.status).toBe('passed');
+    });
+    it('should mark actuals as pending when actuals is null', () => {
+        const result = generateDoD(makeSpec({ actuals: null }));
+        expect(result.items.find((i) => i.id === 'dod-8')?.status).toBe('pending');
+    });
+    it('should set isDone=false when not all required items are passed', () => {
+        const result = generateDoD(makeSpec({ status: 'draft' }));
+        expect(result.isDone).toBe(false);
+    });
+    it('should set completedAt=null when isDone is false', () => {
+        const result = generateDoD(makeSpec({ status: 'draft' }));
+        expect(result.completedAt).toBeNull();
+    });
+    it('should set isDone=true and completedAt when all required items pass', () => {
+        const validation = {
+            matches: ['a'],
+            missing: [],
+            extra: [],
+            fieldsImplemented: 1,
+            fieldsTotal: 1,
+            score: 100,
+            qualityIssues: [],
+        };
+        const spec = makeSpec({
+            status: 'done',
+            actuals: {
+                devHours: 8,
+                reviewHours: 2,
+                tokensOpus: 10000,
+                tokensSonnet: 20000,
+                apiCostUsd: 0.21,
+                humanCostUsd: 650,
+                totalCostUsd: 650.21,
+                completedAt: '2025-01-01T00:00:00Z',
+                notes: 'done',
+            },
+        });
+        const result = generateDoD(spec, validation);
+        // dod-3 (unit tests), dod-4 (code reviewed), dod-6 (no regressions) are still pending
+        // so isDone will be false unless they are passed
+        // Actually those are required + pending => isDone = false
+        expect(result.isDone).toBe(false);
+        expect(result.completedAt).toBeNull();
+    });
+    it('should calculate passedCount correctly', () => {
+        const result = generateDoD(makeSpec());
+        const expected = result.items.filter((i) => i.status === 'passed').length;
+        expect(result.passedCount).toBe(expected);
+    });
+    it('should calculate requiredCount correctly', () => {
+        const result = generateDoD(makeSpec());
+        const expected = result.items.filter((i) => i.required).length;
+        expect(result.requiredCount).toBe(expected);
+    });
+});
+// ============================================================
+// generateChecklist
+// ============================================================
+describe('generateChecklist', () => {
+    it('should generate checklist items for a backend spec', () => {
+        const result = generateChecklist(makeSpec({ target: 'backend' }));
+        expect(result.items.length).toBeGreaterThan(0);
+        expect(result.specId).toBe('SPEC-001');
+    });
+    it('should include UX items for frontend specs', () => {
+        const result = generateChecklist(makeSpec({ target: 'frontend' }));
+        const uxItems = result.items.filter((i) => i.category === 'ux');
+        expect(uxItems.length).toBe(2);
+    });
+    it('should include UX items for fullstack specs', () => {
+        const result = generateChecklist(makeSpec({ target: 'fullstack' }));
+        const uxItems = result.items.filter((i) => i.category === 'ux');
+        expect(uxItems.length).toBe(2);
+    });
+    it('should NOT include UX items for backend-only specs', () => {
+        const result = generateChecklist(makeSpec({ target: 'backend' }));
+        const uxItems = result.items.filter((i) => i.category === 'ux');
+        expect(uxItems).toHaveLength(0);
+    });
+    it('should NOT include UX items for infrastructure specs', () => {
+        const result = generateChecklist(makeSpec({ target: 'infrastructure' }));
+        const uxItems = result.items.filter((i) => i.category === 'ux');
+        expect(uxItems).toHaveLength(0);
+    });
+    it('should filter by focus categories when provided', () => {
+        const result = generateChecklist(makeSpec({ target: 'fullstack' }), ['security']);
+        expect(result.items.every((i) => i.category === 'security')).toBe(true);
+        expect(result.items.length).toBeGreaterThan(0);
+    });
+    it('should filter by multiple focus categories', () => {
+        const result = generateChecklist(makeSpec({ target: 'frontend' }), ['security', 'ux']);
+        const categories = new Set(result.items.map((i) => i.category));
+        for (const cat of categories) {
+            expect(['security', 'ux']).toContain(cat);
+        }
+    });
+    it('should return all categories when focus is empty array', () => {
+        const result = generateChecklist(makeSpec({ target: 'frontend' }), []);
+        const categories = new Set(result.items.map((i) => i.category));
+        expect(categories.size).toBeGreaterThan(1);
+    });
+    it('should return all categories when no focus provided', () => {
+        const result = generateChecklist(makeSpec({ target: 'frontend' }));
+        const categories = new Set(result.items.map((i) => i.category));
+        expect(categories.size).toBeGreaterThan(1);
+    });
+    it('should return empty items if focus matches nothing', () => {
+        // 'ux' items only exist for frontend/fullstack; backend spec + ux filter => empty
+        // Actually 'ux' won't exist for backend. Let's use a nonexistent category approach:
+        // focus requires items that don't exist
+        const result = generateChecklist(makeSpec({ target: 'backend' }), ['ux']);
+        expect(result.items).toHaveLength(0);
+        expect(result.score).toBe(0);
+    });
+    // validateScopeDifficulty coverage
+    it('should validate trivial scope with difficulty 1 (yes)', () => {
+        const result = generateChecklist(makeSpec({ scope: 'trivial', difficulty: 1 }));
+        expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('yes');
+    });
+    it('should validate trivial scope with difficulty 2 (yes)', () => {
+        const result = generateChecklist(makeSpec({ scope: 'trivial', difficulty: 2 }));
+        expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('yes');
+    });
+    it('should flag trivial scope with difficulty 3 (no)', () => {
+        const result = generateChecklist(makeSpec({ scope: 'trivial', difficulty: 3 }));
+        expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('no');
+    });
+    it('should validate feature scope with difficulty 1-3 (yes)', () => {
+        for (const d of [1, 2, 3]) {
+            const result = generateChecklist(makeSpec({ scope: 'feature', difficulty: d }));
+            expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('yes');
+        }
+    });
+    it('should flag feature scope with difficulty 4 (no)', () => {
+        const result = generateChecklist(makeSpec({ scope: 'feature', difficulty: 4 }));
+        expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('no');
+    });
+    it('should validate cross-module scope with difficulty 2-4 (yes)', () => {
+        for (const d of [2, 3, 4]) {
+            const result = generateChecklist(makeSpec({ scope: 'cross-module', difficulty: d }));
+            expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('yes');
+        }
+    });
+    it('should flag cross-module scope with difficulty 1 (no)', () => {
+        const result = generateChecklist(makeSpec({ scope: 'cross-module', difficulty: 1 }));
+        expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('no');
+    });
+    it('should flag cross-module scope with difficulty 5 (no)', () => {
+        const result = generateChecklist(makeSpec({ scope: 'cross-module', difficulty: 5 }));
+        expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('no');
+    });
+    it('should validate architectural scope with difficulty 3-5 (yes)', () => {
+        for (const d of [3, 4, 5]) {
+            const result = generateChecklist(makeSpec({ scope: 'architectural', difficulty: d }));
+            expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('yes');
+        }
+    });
+    it('should flag architectural scope with difficulty 1 (no)', () => {
+        const result = generateChecklist(makeSpec({ scope: 'architectural', difficulty: 1 }));
+        expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('no');
+    });
+    it('should return yes for unknown scope (always valid)', () => {
+        const result = generateChecklist(makeSpec({ scope: 'unknown-scope' }));
+        expect(result.items.find((i) => i.id === 'cl-cons-1')?.answer).toBe('yes');
+    });
+    // Completeness checks for huPath / fichaTecnicaPath
+    it('should mark cl-comp-1 as pending when huPath exists', () => {
+        const result = generateChecklist(makeSpec({ huPath: '/some/HU.md' }));
+        expect(result.items.find((i) => i.id === 'cl-comp-1')?.answer).toBe('pending');
+    });
+    it('should mark cl-comp-1 as no when huPath is empty', () => {
+        const result = generateChecklist(makeSpec({ huPath: '' }));
+        expect(result.items.find((i) => i.id === 'cl-comp-1')?.answer).toBe('no');
+    });
+    it('should mark cl-comp-2 as pending when fichaTecnicaPath exists', () => {
+        const result = generateChecklist(makeSpec({ fichaTecnicaPath: '/some/FICHA.md' }));
+        expect(result.items.find((i) => i.id === 'cl-comp-2')?.answer).toBe('pending');
+    });
+    it('should mark cl-comp-2 as no when fichaTecnicaPath is empty', () => {
+        const result = generateChecklist(makeSpec({ fichaTecnicaPath: '' }));
+        expect(result.items.find((i) => i.id === 'cl-comp-2')?.answer).toBe('no');
+    });
+    // Feasibility blocker check
+    it('should mark cl-feas-2 as yes when no blockers', () => {
+        const result = generateChecklist(makeSpec({ blockedBy: [] }));
+        expect(result.items.find((i) => i.id === 'cl-feas-2')?.answer).toBe('yes');
+    });
+    it('should mark cl-feas-2 as no when blockers exist', () => {
+        const result = generateChecklist(makeSpec({ blockedBy: ['SPEC-X'] }));
+        expect(result.items.find((i) => i.id === 'cl-feas-2')?.answer).toBe('no');
+    });
+    // Score calculation
+    it('should calculate score correctly', () => {
+        const result = generateChecklist(makeSpec({ scope: 'feature', difficulty: 2, blockedBy: [] }));
+        const passedCount = result.items.filter((i) => i.answer === 'yes').length;
+        const expectedScore = Math.round((passedCount / result.items.length) * 100);
+        expect(result.passedCount).toBe(passedCount);
+        expect(result.score).toBe(expectedScore);
+    });
+    it('should return score 0 when no yes answers', () => {
+        const result = generateChecklist(makeSpec({
+            huPath: '',
+            fichaTecnicaPath: '',
+            blockedBy: ['x'],
+            scope: 'architectural',
+            difficulty: 1,
+            target: 'backend',
+        }));
+        const yesCount = result.items.filter((i) => i.answer === 'yes').length;
+        expect(yesCount).toBe(0);
+        expect(result.score).toBe(0);
+    });
+    it('should include generatedAt ISO timestamp', () => {
+        const result = generateChecklist(makeSpec());
+        expect(result.generatedAt).toBeDefined();
+        expect(new Date(result.generatedAt).toISOString()).toBe(result.generatedAt);
+    });
+});
+// ============================================================
+// validateSpec
+// ============================================================
+describe('validateSpec', () => {
+    const projectPath = '/test/project';
+    it('should return score 0 when no criteria match (no files, HU+ficha unreadable)', async () => {
+        // Both readFile calls will fail (default mock), glob returns nothing
+        const spec = makeSpec({ target: 'backend' });
+        const result = await validateSpec(spec, projectPath);
+        // extractCriteria falls back to metadata-based criteria
+        // checkCriterion won't find anything because no files, no fileContents
+        expect(result.score).toBe(0);
+        expect(result.fieldsTotal).toBeGreaterThan(0);
+        expect(result.missing.length).toBeGreaterThan(0);
+    });
+    it('should return fieldsTotal 0 and score 0 for empty criteria dedup edge', async () => {
+        // Prove that when criteria are generated, we get something
+        const spec = makeSpec({ target: 'backend' });
+        const result = await validateSpec(spec, projectPath);
+        // Default criteria: '"Feature ..." is implemented', 'API endpoints respond correctly', 'No regression in existing tests'
+        expect(result.fieldsTotal).toBe(3);
+    });
+    it('should generate frontend criteria when target is frontend', async () => {
+        const spec = makeSpec({ target: 'frontend' });
+        const result = await validateSpec(spec, projectPath);
+        // criteria: Feature implemented, UI components render correctly, No regression
+        expect(result.fieldsTotal).toBe(3);
+        expect(result.missing).toContain('UI components render correctly');
+    });
+    it('should generate fullstack criteria for both UI and API', async () => {
+        const spec = makeSpec({ target: 'fullstack' });
+        const result = await validateSpec(spec, projectPath);
+        // Feature implemented, UI components render correctly, API endpoints respond correctly, No regression
+        expect(result.fieldsTotal).toBe(4);
+    });
+    it('should generate shared target criteria (only base + regression)', async () => {
+        const spec = makeSpec({ target: 'shared' });
+        const result = await validateSpec(spec, projectPath);
+        // Feature implemented, No regression
+        expect(result.fieldsTotal).toBe(2);
+    });
+    // extractCriteria: extract from HU.md acceptance criteria section
+    it('should extract acceptance criteria from HU.md', async () => {
+        const huContent = [
+            '# User Story',
+            '## Acceptance Criteria',
+            '- The user can log in successfully',
+            '- The user sees a dashboard after login',
+            '## Other Section',
+            'Some text',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const spec = makeSpec();
+        const result = await validateSpec(spec, projectPath);
+        // Extracted: "The user can log in successfully", "The user sees a dashboard after login"
+        expect(result.fieldsTotal).toBe(2);
+    });
+    it('should extract acceptance criteria using Spanish heading', async () => {
+        const huContent = [
+            '# Historia de Usuario',
+            '## Criterios de Aceptaci\u00f3n',
+            '- El usuario puede iniciar sesion correctamente',
+            '## Otra Seccion',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(1);
+        expect(result.missing[0] ?? result.matches[0]).toContain('El usuario puede iniciar sesion correctamente');
+    });
+    it('should extract Given/When/Then patterns from HU.md', async () => {
+        const huContent = [
+            '# User Story',
+            'Given the user is logged in',
+            'When they click the button',
+            'Then they see a confirmation',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        // 3 GWT matches
+        expect(result.fieldsTotal).toBe(3);
+    });
+    it('should extract Spanish GWT patterns (Dado/Cuando/Entonces)', async () => {
+        const huContent = [
+            'Dado que el usuario tiene permisos de admin',
+            'Cuando accede al panel de control exitosamente',
+            'Entonces ve las opciones de administracion completas',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(3);
+    });
+    it('should extract technical requirements from FICHA-TECNICA.md', async () => {
+        const fichaContent = [
+            '# Technical Design',
+            '## Requirements',
+            '- Database schema must support multi-tenancy',
+            '- API must handle 1000 requests per second',
+            '## Implementation',
+            'Details here',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('FICHA')) {
+                return fichaContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(2);
+    });
+    it('should extract from FICHA-TECNICA with "requisitos" heading', async () => {
+        const fichaContent = [
+            '# Ficha Tecnica',
+            '## Requisitos',
+            '- Soporte para multiples idiomas nativo',
+            '## Otro',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('FICHA')) {
+                return fichaContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(1);
+    });
+    it('should extract from FICHA-TECNICA with "technical" heading', async () => {
+        const fichaContent = [
+            '# Spec',
+            '## Technical Details',
+            '- Must use PostgreSQL for persistence layer',
+            '## End',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('FICHA')) {
+                return fichaContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(1);
+    });
+    it('should extract from FICHA-TECNICA with "implementation" heading', async () => {
+        const fichaContent = [
+            '# Spec',
+            '## Implementation Notes',
+            '1. Create the service layer for authentication',
+            '## End',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('FICHA')) {
+                return fichaContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(1);
+    });
+    it('should deduplicate criteria from both files', async () => {
+        const huContent = [
+            '# Story',
+            '## Acceptance Criteria',
+            '- Must implement logging service correctly',
+        ].join('\n');
+        const fichaContent = [
+            '# Tech',
+            '## Requirements',
+            '- Must implement logging service correctly',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('FICHA')) {
+                return fichaContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        // Deduplicated: only 1 criterion
+        expect(result.fieldsTotal).toBe(1);
+    });
+    it('should merge criteria from both HU and FICHA', async () => {
+        const huContent = [
+            '# Story',
+            '## Acceptance Criteria',
+            '- Feature A must work correctly in production',
+        ].join('\n');
+        const fichaContent = [
+            '# Tech',
+            '## Requirements',
+            '- Feature B must be implemented with tests',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('FICHA')) {
+                return fichaContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(2);
+    });
+    // extractSection: sub-heading within captured section (deeper level does NOT break)
+    it('should include sub-heading content within captured section', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Top level criterion is long enough',
+            '### Sub-section Details',
+            '- Sub-section criterion is long enough',
+            '## Next Section At Same Level',
+            '- Should not be captured at all here',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        // Both top-level and sub-section criteria should be captured (sub-heading is deeper)
+        expect(result.fieldsTotal).toBe(2);
+    });
+    // extractSection: heading match that is already capturing but hits deeper heading
+    it('should not break on a deeper heading when already capturing', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- First criterion is definitely long enough',
+            '#### Very Deep Sub-heading',
+            '- Deep criterion is also long enough here',
+            '# Top Level Heading Stops Capture',
+            '- This should not be captured anymore',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(2);
+    });
+    // extractListItems: numbered lists
+    it('should extract numbered list items from spec files', async () => {
+        const huContent = [
+            '# Story',
+            '## Acceptance Criteria',
+            '1. The system must validate user input data',
+            '2) The system must log all access attempts',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(2);
+    });
+    // extractListItems: checkbox lists
+    it('should extract checkbox list items from spec files', async () => {
+        const huContent = [
+            '# Story',
+            '## Acceptance Criteria',
+            '- [x] Completed criterion that already works',
+            '- [ ] Pending criterion that needs implementation',
+            '- [X] Another completed criterion that works',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(3);
+    });
+    // extractListItems: skip short items (<=5 chars)
+    it('should skip trivially short list items (<=5 chars)', async () => {
+        const huContent = [
+            '# Story',
+            '## Acceptance Criteria',
+            '- Yes',
+            '- No',
+            '- A valid criterion that is long enough',
+            '1. Abc',
+            '2. Another valid numbered criterion here',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        // "Yes" (3 chars), "No" (2 chars), "Abc" (3 chars) are skipped
+        expect(result.fieldsTotal).toBe(2);
+    });
+    // extractListItems: different bullet styles
+    it('should extract items with * and + bullet styles', async () => {
+        const huContent = [
+            '# Story',
+            '## Acceptance Criteria',
+            '* Star bullet criterion that is long',
+            '+ Plus bullet criterion that is long',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(2);
+    });
+    // extractSection: heading level boundary
+    it('should stop section extraction when a same-level heading is encountered', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Criterion one is valid here',
+            '## Another Section At Same Level',
+            '- This should NOT be extracted',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(1);
+        expect(result.missing[0] ?? result.matches[0]).toContain('Criterion one is valid here');
+    });
+    // extractSection: higher-level heading stops extraction
+    it('should stop section extraction when a higher-level heading is encountered', async () => {
+        const huContent = [
+            '### Acceptance Criteria',
+            '- Criterion in subsection is valid',
+            '## Higher Level Heading Here',
+            '- Should not be captured here',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(1);
+    });
+    // extractSection: returns null when no matching heading
+    it('should fallback to metadata criteria when no matching section heading', async () => {
+        const huContent = ['# Some Heading', '## Not Related', '- Some item here'].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec({ target: 'backend' }), projectPath);
+        // No section match, no GWT => fallback to metadata criteria
+        expect(result.fieldsTotal).toBe(3); // Feature + API + No regression
+    });
+    // extractSection: empty section (heading exists but no content before next heading)
+    it('should return null for section with no content lines', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '## Next Section Immediately',
+            '- Content in next section here',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec({ target: 'backend' }), projectPath);
+        // Empty AC section => no criteria from it, fallback to metadata
+        expect(result.fieldsTotal).toBe(3);
+    });
+    // scanCodeForSpec: impactAnalysis with affectedFiles
+    it('should scan affected files from impactAnalysis', async () => {
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: ['engine'],
+                affectedFiles: ['src/engine/validator.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('validator.ts')) {
+                return 'export function validateSpec() {}';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        // With affected files and content available, optimistic check passes
+        expect(result.fieldsTotal).toBeGreaterThan(0);
+    });
+    it('should handle impactAnalysis file that doesnt exist', async () => {
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: ['engine'],
+                affectedFiles: ['src/nonexistent.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        // readFile always throws (default)
+        const result = await validateSpec(spec, projectPath);
+        // File doesn't exist, so affectedFiles is empty
+        expect(result.fieldsTotal).toBeGreaterThan(0);
+    });
+    // scanCodeForSpec: gitBranch set (no-op but covers the branch)
+    it('should cover the gitBranch code path', async () => {
+        const spec = makeSpec({ gitBranch: 'feature/test-branch' });
+        const result = await validateSpec(spec, projectPath);
+        expect(result).toBeDefined();
+    });
+    // scanCodeForSpec: glob finds matching files
+    it('should detect unexpected files matching the slug', async () => {
+        mockGlob.mockResolvedValue(['src/test-spec-title.ts']);
+        const spec = makeSpec({ slug: 'test-spec-title' });
+        const result = await validateSpec(spec, projectPath);
+        // The file is unexpected (not in affectedFiles)
+        expect(result.extra).toContain('Unexpected file: src/test-spec-title.ts');
+    });
+    it('should not mark file as unexpected if it is in affectedFiles', async () => {
+        const spec = makeSpec({
+            slug: 'test-spec-title',
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/test-spec-title.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('test-spec-title')) {
+                return 'export const x = 1;';
+            }
+            throw new Error('ENOENT');
+        }));
+        mockGlob.mockResolvedValue(['src/test-spec-title.ts']);
+        const result = await validateSpec(spec, projectPath);
+        expect(result.extra).not.toContain('Unexpected file: src/test-spec-title.ts');
+    });
+    // scanCodeForSpec: glob error
+    it('should handle glob errors gracefully in scanCodeForSpec', async () => {
+        mockGlob.mockRejectedValue(new Error('glob failure'));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result).toBeDefined();
+        expect(result.extra).toHaveLength(0);
+    });
+    // checkCriterion: file existence criteria
+    it('should check file existence for "create file" criterion', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Create file "src/utils.ts" for utilities',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        mockStat.mockResolvedValue({});
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.matches).toContain('Create file "src/utils.ts" for utilities');
+    });
+    it('should mark file criterion as missing when file does not exist', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Add file src/missing.ts for new module',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        // stat throws by default
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.missing).toContain('Add file src/missing.ts for new module');
+    });
+    it('should detect "implement file" pattern for file check', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Implement file config.json for settings',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        mockStat.mockResolvedValue({});
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.matches.length).toBe(1);
+    });
+    // checkCriterion: component/function search in fileContents
+    it('should find component name in affected file contents', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Component UserDashboard must render correctly',
+        ].join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/components/dashboard.tsx'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('dashboard.tsx')) {
+                return 'export function UserDashboard() { return <div/>; }';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        expect(result.matches).toContain('Component UserDashboard must render correctly');
+    });
+    // checkCriterion: component/function search via glob broader search
+    it('should find component via broader glob search when not in fileContents', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Function calculateTotal must work correctly',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('math.ts')) {
+                return 'export function calculateTotal() { return 42; }';
+            }
+            throw new Error('ENOENT');
+        }));
+        // First glob call for scanCodeForSpec slug match, second for component search
+        let callCount = 0;
+        mockGlob.mockImplementation((() => {
+            callCount++;
+            if (callCount === 1) {
+                return [];
+            } // slug match
+            return ['src/math.ts']; // component search
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.matches).toContain('Function calculateTotal must work correctly');
+    });
+    // checkCriterion: component found via broader search but readFile fails
+    it('should handle unreadable files during broader component search', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Class AuthService must be implemented fully',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        let callCount = 0;
+        mockGlob.mockImplementation((() => {
+            callCount++;
+            if (callCount === 1) {
+                return [];
+            }
+            return ['src/auth.ts'];
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        // auth.ts can't be read, so AuthService not found
+        expect(result.missing).toContain('Class AuthService must be implemented fully');
+    });
+    // checkCriterion: glob error during broader search
+    it('should handle glob error during broader component search', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Module PaymentService must handle transactions',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        let callCount = 0;
+        mockGlob.mockImplementation((() => {
+            callCount++;
+            if (callCount === 1) {
+                return [];
+            }
+            throw new Error('glob error');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.missing).toContain('Module PaymentService must handle transactions');
+    });
+    // checkCriterion: component search limits to 50 files
+    it('should limit broader search to first 50 files', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Service TargetService must exist in codebase',
+        ].join('\n');
+        const files = Array.from({ length: 60 }, (_, i) => `src/file${i}.ts`);
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            // Only file59.ts contains "TargetService" (index 59, which is beyond 50 limit)
+            if (p.includes('file59.ts')) {
+                return 'export class TargetService {}';
+            }
+            return 'export const noop = true;';
+        }));
+        let callCount = 0;
+        mockGlob.mockImplementation((() => {
+            callCount++;
+            if (callCount === 1) {
+                return [];
+            }
+            return files;
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        // file59 is at index 59, slice(0,50) excludes it
+        expect(result.missing).toContain('Service TargetService must exist in codebase');
+    });
+    // checkCriterion: service name patterns
+    it('should detect "service" keyword in criterion', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Service EmailHandler must send notifications',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('email.ts')) {
+                return 'class EmailHandler {}';
+            }
+            throw new Error('ENOENT');
+        }));
+        let callCount = 0;
+        mockGlob.mockImplementation((() => {
+            callCount++;
+            if (callCount === 1) {
+                return [];
+            }
+            return ['src/email.ts'];
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.matches).toContain('Service EmailHandler must send notifications');
+    });
+    // checkCriterion: API endpoint criteria
+    it('should find API endpoint criterion in file contents', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Endpoint for users must return user list',
+        ].join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/routes.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('routes.ts')) {
+                return 'app.get("/users", handler);';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        expect(result.matches).toContain('Endpoint for users must return user list');
+    });
+    it('should handle endpoint not found in file contents', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Route for payments must process transactions',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.missing).toContain('Route for payments must process transactions');
+    });
+    it('should detect "api" keyword for endpoint criterion', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- API products should list all products correctly',
+        ].join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/api.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('api.ts')) {
+                return 'router.get("/products", listProducts);';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        expect(result.matches).toContain('API products should list all products correctly');
+    });
+    // checkCriterion: endpoint matched but not in fileContents, falls through to optimistic check
+    it('should pass endpoint criterion via optimistic fallback when affected files exist', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Endpoint for orders must handle all requests',
+        ].join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/handler.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            // handler.ts does NOT contain "orders" - endpoint not found in content
+            if (p.includes('handler.ts')) {
+                return 'export function handleRequest() {}';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        // Endpoint "orders" not found in fileContents, but affectedFiles.length > 0 => optimistic pass
+        expect(result.matches).toContain('Endpoint for orders must handle all requests');
+    });
+    // checkCriterion: fallback optimistic check when affectedFiles > 0
+    it('should optimistically pass criteria when affected files exist', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Some general criterion without specific keywords',
+        ].join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/feature.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('feature.ts')) {
+                return 'export const feature = true;';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        // criterion doesn't match file/component/endpoint patterns but affectedFiles > 0
+        expect(result.matches).toContain('Some general criterion without specific keywords');
+    });
+    // checkCriterion: returns false when nothing matches
+    it('should return false for criterion that matches nothing and no affected files', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Some general criterion without specific patterns',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.missing).toContain('Some general criterion without specific patterns');
+    });
+    // quickQualityCheck: non-code extension skipped
+    it('should not produce quality issues for non-code files', async () => {
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['README.md'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('README.md')) {
+                return '# Readme\nSome content\nconsole.log("test")';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        expect(result.qualityIssues).toHaveLength(0);
+    });
+    // quickQualityCheck: file length > 500
+    it('should flag files with more than 500 lines', async () => {
+        const longContent = Array.from({ length: 501 }, (_, i) => `line ${i}`).join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/big.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('big.ts')) {
+                return longContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        const fileLengthIssue = result.qualityIssues.find((i) => i.rule === 'file-length');
+        expect(fileLengthIssue).toBeDefined();
+        expect(fileLengthIssue?.severity).toBe('warning');
+        expect(fileLengthIssue?.message).toContain('501 lines');
+    });
+    // quickQualityCheck: file length exactly 500 (no issue)
+    it('should NOT flag files with exactly 500 lines', async () => {
+        const content = Array.from({ length: 500 }, (_, i) => `line ${i}`).join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/ok.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('ok.ts')) {
+                return content;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        const fileLengthIssue = result.qualityIssues.find((i) => i.rule === 'file-length');
+        expect(fileLengthIssue).toBeUndefined();
+    });
+    // quickQualityCheck: TODO/FIXME/HACK/XXX
+    it('should flag TODO/FIXME/HACK/XXX markers', async () => {
+        const content = [
+            'const x = 1;',
+            '// TODO: fix this later',
+            '// FIXME: broken logic',
+            '// HACK: workaround',
+            '// XXX: needs review',
+            'const y = 2;',
+        ].join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/dirty.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('dirty.ts')) {
+                return content;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        const pendingWork = result.qualityIssues.filter((i) => i.rule === 'pending-work');
+        expect(pendingWork.length).toBe(4);
+        expect(pendingWork[0]?.severity).toBe('info');
+    });
+    // quickQualityCheck: console.log detection (non-test file)
+    it('should flag console statements in non-test files', async () => {
+        const content = [
+            'function doSomething() {',
+            '  console.log("debug");',
+            '  console.debug("details");',
+            '  console.info("info");',
+            '}',
+        ].join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/service.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('service.ts')) {
+                return content;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        const consoleIssues = result.qualityIssues.filter((i) => i.rule === 'no-console');
+        expect(consoleIssues.length).toBe(3);
+        expect(consoleIssues[0]?.severity).toBe('warning');
+    });
+    // quickQualityCheck: console.log NOT flagged in test files
+    it('should NOT flag console statements in test files', async () => {
+        const content = 'console.log("test output");';
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/service.test.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('service.test.ts')) {
+                return content;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        const consoleIssues = result.qualityIssues.filter((i) => i.rule === 'no-console');
+        expect(consoleIssues).toHaveLength(0);
+    });
+    // quickQualityCheck: console.log NOT flagged in spec files
+    it('should NOT flag console statements in spec files', async () => {
+        const content = 'console.log("spec output");';
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/feature.spec.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('feature.spec.ts')) {
+                return content;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        const consoleIssues = result.qualityIssues.filter((i) => i.rule === 'no-console');
+        expect(consoleIssues).toHaveLength(0);
+    });
+    // quickQualityCheck: readFile error
+    it('should handle readFile errors in quickQualityCheck gracefully', async () => {
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/unreadable.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        // readFile always throws (default behavior)
+        // BUT for scanCodeForSpec, reading impactAnalysis files also throws,
+        // so affectedFiles stays empty. We need a special setup:
+        // scanCodeForSpec reads the file for impactAnalysis => should succeed for that
+        // quickQualityCheck reads the same file => should fail
+        let readCount = 0;
+        mockReadFile.mockImplementation(((path) => {
+            readCount++;
+            const p = String(path);
+            if (p.includes('unreadable.ts')) {
+                if (readCount <= 1) {
+                    return 'const x = 1;';
+                } // scanCodeForSpec succeeds
+                throw new Error('EACCES'); // quickQualityCheck fails
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        // Should not crash, just no quality issues
+        expect(result.qualityIssues).toHaveLength(0);
+    });
+    // quickQualityCheck: various code extensions
+    it('should run quality check on various code extensions', async () => {
+        const extensions = ['.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.java', '.kt', '.rb', '.php'];
+        for (const ext of extensions) {
+            vi.clearAllMocks();
+            mockGlob.mockResolvedValue([]);
+            const filename = `src/file${ext}`;
+            const spec = makeSpec({
+                impactAnalysis: {
+                    affectedModules: [],
+                    affectedFiles: [filename],
+                    breakingChanges: false,
+                    requiresMigration: false,
+                    migrationReversible: false,
+                    requiresFeatureFlag: false,
+                    rollbackPlan: '',
+                    testingStrategy: {
+                        unitTests: [],
+                        integrationTests: [],
+                        e2eTests: [],
+                        manualTests: [],
+                    },
+                    environments: [],
+                },
+            });
+            mockReadFile.mockImplementation(((path) => {
+                const p = String(path);
+                if (p.includes(`file${ext}`)) {
+                    return '// TODO: implement this feature\nconst x = 1;';
+                }
+                throw new Error('ENOENT');
+            }));
+            const result = await validateSpec(spec, projectPath);
+            const todoIssues = result.qualityIssues.filter((i) => i.rule === 'pending-work');
+            expect(todoIssues.length).toBeGreaterThanOrEqual(1);
+        }
+    });
+    // Score calculation
+    it('should calculate score as 100 when all criteria match', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Create file "src/new.ts" for the new feature',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        mockStat.mockResolvedValue({});
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.score).toBe(100);
+        expect(result.fieldsImplemented).toBe(1);
+        expect(result.fieldsTotal).toBe(1);
+    });
+    it('should calculate partial score correctly', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Create file "src/exists.ts" for first feature',
+            '- Create file "src/missing.ts" for second feature',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        mockStat.mockImplementation(((path) => {
+            if (String(path).includes('exists.ts')) {
+                return {};
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.score).toBe(50);
+        expect(result.fieldsImplemented).toBe(1);
+        expect(result.fieldsTotal).toBe(2);
+    });
+    // slug with dashes transforms to pattern
+    it('should transform slug dashes to [-_] pattern for glob', async () => {
+        const spec = makeSpec({ slug: 'my-cool-feature' });
+        mockGlob.mockResolvedValue([]);
+        await validateSpec(spec, projectPath);
+        // Check that glob was called with the pattern transformation
+        expect(mockGlob).toHaveBeenCalledWith(expect.stringContaining('my[-_]cool[-_]feature'), expect.objectContaining({
+            cwd: projectPath,
+            nodir: true,
+            ignore: ['node_modules/**', 'dist/**', 'build/**', '.git/**'],
+            maxDepth: 6,
+        }));
+    });
+});
+// ============================================================
+// detectDrift
+// ============================================================
+describe('detectDrift', () => {
+    const projectPath = '/test/project';
+    it('should return a DriftReport with specId, checkType, and lastChecked', async () => {
+        const result = await detectDrift(makeSpec(), projectPath);
+        expect(result.specId).toBe('SPEC-001');
+        expect(result.checkType).toBe('on-demand');
+        expect(result.lastChecked).toBeDefined();
+        expect(new Date(result.lastChecked).toISOString()).toBe(result.lastChecked);
+    });
+    it('should create drift items from missing criteria', async () => {
+        const result = await detectDrift(makeSpec({ target: 'backend' }), projectPath);
+        // Default spec with no files => all criteria are missing
+        expect(result.drifts.length).toBeGreaterThan(0);
+        for (const drift of result.drifts) {
+            expect(drift.expected).toBe('Implemented');
+            expect(drift.actual).toBe('Missing');
+            expect(drift.autoFixable).toBe(false);
+        }
+    });
+    it('should classify security drift as critical severity', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Security authentication must be enforced properly',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(makeSpec(), projectPath);
+        const secDrift = result.drifts.find((d) => d.specCriterion.includes('Security'));
+        expect(secDrift?.severity).toBe('critical');
+    });
+    it('should classify auth criterion as critical severity', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Auth token validation must work correctly',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(makeSpec(), projectPath);
+        const authDrift = result.drifts.find((d) => d.specCriterion.toLowerCase().includes('auth'));
+        expect(authDrift?.severity).toBe('critical');
+    });
+    it('should classify permission criterion as critical severity', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Permission checks must prevent unauthorized access',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(makeSpec(), projectPath);
+        const permDrift = result.drifts.find((d) => d.specCriterion.toLowerCase().includes('permission'));
+        expect(permDrift?.severity).toBe('critical');
+    });
+    it('should classify error criterion as high severity', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Error handling must be comprehensive everywhere',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(makeSpec(), projectPath);
+        const errDrift = result.drifts.find((d) => d.specCriterion.toLowerCase().includes('error'));
+        expect(errDrift?.severity).toBe('high');
+    });
+    it('should classify validation criterion as high severity', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Validation of all user inputs must happen',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(makeSpec(), projectPath);
+        const valDrift = result.drifts.find((d) => d.specCriterion.toLowerCase().includes('validation'));
+        expect(valDrift?.severity).toBe('high');
+    });
+    it('should classify test criterion as high severity', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Test coverage must meet minimum threshold',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(makeSpec(), projectPath);
+        const testDrift = result.drifts.find((d) => d.specCriterion.toLowerCase().includes('test'));
+        expect(testDrift?.severity).toBe('high');
+    });
+    it('should classify performance criterion as medium severity', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Performance benchmark must meet requirements daily',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(makeSpec(), projectPath);
+        const perfDrift = result.drifts.find((d) => d.specCriterion.toLowerCase().includes('performance'));
+        expect(perfDrift?.severity).toBe('medium');
+    });
+    it('should classify cache criterion as medium severity', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Cache expiry must work across replicas',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(makeSpec(), projectPath);
+        const cacheDrift = result.drifts.find((d) => d.specCriterion.toLowerCase().includes('cache'));
+        expect(cacheDrift?.severity).toBe('medium');
+    });
+    it('should classify optimize criterion as medium severity', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Optimize database queries for large datasets',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(makeSpec(), projectPath);
+        const optDrift = result.drifts.find((d) => d.specCriterion.toLowerCase().includes('optimize'));
+        expect(optDrift?.severity).toBe('medium');
+    });
+    it('should classify generic criterion as low severity', async () => {
+        // The default fallback metadata criterion "Feature ... is implemented" is generic
+        // Use a title without "test"/"error"/"validation"/"security"/"auth"/"performance"/"cache"/"optimize"
+        const result = await detectDrift(makeSpec({ target: 'shared', title: 'User Profile Feature' }), projectPath);
+        // "Feature ... is implemented" => low, "No regression in existing tests" => high (contains "test")
+        const featureDrift = result.drifts.find((d) => d.specCriterion.includes('is implemented'));
+        expect(featureDrift?.severity).toBe('low');
+    });
+    // Quality issues as drift items
+    it('should include quality issues as drift items', async () => {
+        const content = Array.from({ length: 501 }, (_, i) => `line ${i}`).join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/big.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('big.ts')) {
+                return content;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(spec, projectPath);
+        const qualityDrift = result.drifts.find((d) => d.specCriterion === 'file-length');
+        expect(qualityDrift).toBeDefined();
+        expect(qualityDrift?.file).toBe('src/big.ts');
+    });
+    // Quality issue severity mapping
+    it('should map critical quality issue severity to critical drift', async () => {
+        // We need a quality issue with severity "critical" - but quickQualityCheck only produces
+        // 'warning' (file-length, no-console) and 'info' (pending-work).
+        // The severity mapping in detectDrift converts: critical->critical, error->high, else->medium
+        // Since quickQualityCheck can't produce critical/error severity directly, we test through
+        // the existing severities. 'warning' should map to 'medium' and 'info' should map to 'medium'.
+        const content = '// TODO: fix this critical issue later\n';
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/todo.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('todo.ts')) {
+                return content;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(spec, projectPath);
+        const todoDrift = result.drifts.find((d) => d.specCriterion === 'pending-work');
+        expect(todoDrift).toBeDefined();
+        // 'info' severity maps to 'medium' in the ternary chain
+        expect(todoDrift?.severity).toBe('medium');
+    });
+    it('should map warning quality issue severity to medium drift', async () => {
+        const content = Array.from({ length: 501 }, (_, i) => `line ${i}`).join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/large.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('large.ts')) {
+                return content;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await detectDrift(spec, projectPath);
+        const fileLengthDrift = result.drifts.find((d) => d.specCriterion === 'file-length');
+        expect(fileLengthDrift?.severity).toBe('medium');
+        expect(fileLengthDrift?.suggestedFix).toBeDefined();
+    });
+    // Compliance threshold
+    it('should mark as compliant when score >= threshold (default 80)', async () => {
+        // Need a spec where all criteria pass => score 100 >= 80
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Create file "src/exists.ts" for the feature',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        mockStat.mockResolvedValue({});
+        const result = await detectDrift(makeSpec(), projectPath);
+        expect(result.isCompliant).toBe(true);
+        expect(result.driftScore).toBe(100);
+    });
+    it('should mark as non-compliant when score < threshold', async () => {
+        const result = await detectDrift(makeSpec({ target: 'backend' }), projectPath);
+        // All criteria missing => score 0 < 80
+        expect(result.isCompliant).toBe(false);
+    });
+    it('should use custom threshold', async () => {
+        const result = await detectDrift(makeSpec({ target: 'backend' }), projectPath, 'full', 0);
+        // score 0 >= threshold 0
+        expect(result.isCompliant).toBe(true);
+    });
+    it('should accept mode parameter (full)', async () => {
+        const result = await detectDrift(makeSpec(), projectPath, 'full');
+        expect(result).toBeDefined();
+    });
+    it('should accept mode parameter (quick)', async () => {
+        const result = await detectDrift(makeSpec(), projectPath, 'quick');
+        expect(result).toBeDefined();
+    });
+    it('should set driftScore from validation score', async () => {
+        const result = await detectDrift(makeSpec({ target: 'shared' }), projectPath);
+        expect(typeof result.driftScore).toBe('number');
+        expect(result.driftScore).toBeGreaterThanOrEqual(0);
+        expect(result.driftScore).toBeLessThanOrEqual(100);
+    });
+});
+// ============================================================
+// Edge cases and integration scenarios
+// ============================================================
+describe('edge cases', () => {
+    const projectPath = '/test/project';
+    it('should handle spec with both GWT and AC sections combined', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- System handles concurrent requests properly',
+            '',
+            'Given a user is authenticated properly',
+            'When they submit a request to the server',
+            'Then the response returns within millisecond',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        // 1 AC item + 3 GWT items = 4 (deduplicated)
+        expect(result.fieldsTotal).toBe(4);
+    });
+    it('should handle empty HU.md content', async () => {
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return '';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec({ target: 'backend' }), projectPath);
+        // Falls back to metadata criteria
+        expect(result.fieldsTotal).toBe(3);
+    });
+    it('should handle HU content with no list items in AC section', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            'This section has text but no list items.',
+            'Just plain paragraphs without bullets.',
+            '## End',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec({ target: 'backend' }), projectPath);
+        // No list items extracted, no GWT => fallback to metadata criteria
+        expect(result.fieldsTotal).toBe(3);
+    });
+    it('should handle criterion with quoted file name', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            "- Create 'src/config.yaml' for project settings",
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        mockStat.mockResolvedValue({});
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.matches.length).toBe(1);
+    });
+    it('should handle deeply nested heading in extractSection', async () => {
+        const huContent = [
+            '###### Acceptance Criteria',
+            '- Deep nested criterion that should work',
+            '###### Another Deep Section',
+            '- Should not be captured here either',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(1);
+    });
+    it('should handle non-heading lines before first heading', async () => {
+        const huContent = [
+            'Some preamble text that is not a heading',
+            '',
+            '## Acceptance Criteria',
+            '- Valid criterion after preamble content',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(1);
+    });
+    // Endpoint case-insensitive matching
+    it('should match endpoint criterion case-insensitively', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Endpoint for USERS must return all records',
+        ].join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/routes.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('routes.ts')) {
+                return 'app.get("/users", listUsers);';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        // "USERS" in criterion matches "users" in code (case insensitive)
+        expect(result.matches.length).toBe(1);
+    });
+    it('should handle indented list items in spec files', async () => {
+        const huContent = [
+            '## Acceptance Criteria',
+            '  - Indented bullet criterion that is valid',
+            '    - More deeply indented criterion valid',
+        ].join('\n');
+        mockReadFile.mockImplementation(((path) => {
+            if (String(path).includes('HU')) {
+                return huContent;
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(makeSpec(), projectPath);
+        expect(result.fieldsTotal).toBe(2);
+    });
+});
+// ============================================================
+// checkDefinitionOfReady / checkDefinitionOfDone wrappers
+// (These are the generateDoR/generateDoD exports tested above,
+//  but let's also verify they are re-exported if needed)
+// ============================================================
+describe('function export verification', () => {
+    it('validateSpec is exported and callable', () => {
+        expect(typeof validateSpec).toBe('function');
+    });
+    it('detectDrift is exported and callable', () => {
+        expect(typeof detectDrift).toBe('function');
+    });
+    it('generateChecklist is exported and callable', () => {
+        expect(typeof generateChecklist).toBe('function');
+    });
+    it('generateDoR is exported and callable', () => {
+        expect(typeof generateDoR).toBe('function');
+    });
+    it('generateDoD is exported and callable', () => {
+        expect(typeof generateDoD).toBe('function');
+    });
+});
+// ============================================================
+// Additional branch coverage tests
+// ============================================================
+describe('generateDoR — empty target branch', () => {
+    it('should fail target check when target is empty string', () => {
+        const result = generateDoR(makeSpec({ target: '' }));
+        const targetItem = result.items.find((i) => i.id === 'dor-10');
+        expect(targetItem?.status).toBe('failed');
+    });
+});
+describe('generateDoD — completedAt null when not all DoD passed', () => {
+    it('should return completedAt=null when some required items are pending', () => {
+        // Default spec: dod-3 (unit tests), dod-4, dod-5, dod-6 are pending => isDone=false
+        const result = generateDoD(makeSpec({ status: 'implementing' }));
+        expect(result.isDone).toBe(false);
+        expect(result.completedAt).toBeNull();
+    });
+});
+describe('checkCriterion — content.includes(name) in code state', () => {
+    it('should match component name found in fileContents map', async () => {
+        const projectPath = '/test/project';
+        const huContent = [
+            '## Acceptance Criteria',
+            '- Component AuthValidator must work correctly',
+        ].join('\n');
+        const spec = makeSpec({
+            impactAnalysis: {
+                affectedModules: [],
+                affectedFiles: ['src/auth.ts'],
+                breakingChanges: false,
+                requiresMigration: false,
+                migrationReversible: false,
+                requiresFeatureFlag: false,
+                rollbackPlan: '',
+                testingStrategy: {
+                    unitTests: [],
+                    integrationTests: [],
+                    e2eTests: [],
+                    manualTests: [],
+                },
+                environments: [],
+            },
+        });
+        mockReadFile.mockImplementation(((path) => {
+            const p = String(path);
+            if (p.includes('HU')) {
+                return huContent;
+            }
+            if (p.includes('auth.ts')) {
+                return 'export class AuthValidator { validate() {} }';
+            }
+            throw new Error('ENOENT');
+        }));
+        const result = await validateSpec(spec, projectPath);
+        // AuthValidator found in fileContents via content.includes(name)
+        expect(result.matches).toContain('Component AuthValidator must work correctly');
+    });
+});
+//# sourceMappingURL=validator.test.js.map