@cleocode/core 2026.3.73 → 2026.3.76

package/src/tasks/__tests__/epic-enforcement.test.js

@@ -0,0 +1,669 @@
+/**
+ * Tests for epic lifecycle pipeline enforcement (T062).
+ *
+ * Covers:
+ * - validateEpicCreation: min-5 AC, description required, mode gating
+ * - validateChildStageCeiling: child stage must not exceed epic's stage
+ * - validateEpicStageAdvancement: epic blocked by in-flight children
+ * - findEpicAncestor: correct ancestor traversal
+ * - Integration via addTask / updateTask
+ *
+ * @task T062
+ * @epic T056
+ */
+import { unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { createTestDb } from '../../store/__tests__/test-db-helper.js';
+// Epic enforcement tests NEED enforcement active — temporarily clear VITEST
+const savedVitest = process.env.VITEST;
+beforeAll(() => {
+    delete process.env.VITEST;
+});
+afterAll(() => {
+    if (savedVitest)
+        process.env.VITEST = savedVitest;
+});
+import { addTask } from '../add.js';
+import { EPIC_MIN_AC, findEpicAncestor, getLifecycleMode, validateChildStageCeiling, validateEpicCreation, validateEpicStageAdvancement, } from '../epic-enforcement.js';
+import { updateTask } from '../update.js';
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+/** Config that disables session and acceptance enforcement for test isolation. */
+function makeConfig(lifecycleMode = 'strict') {
+    return JSON.stringify({
+        lifecycle: { mode: lifecycleMode },
+        enforcement: {
+            session: { requiredForMutate: false },
+            acceptance: { mode: 'off' },
+        },
+        verification: { enabled: false },
+    });
+}
+// ---------------------------------------------------------------------------
+// Unit: EPIC_MIN_AC
+// ---------------------------------------------------------------------------
+describe('EPIC_MIN_AC constant', () => {
+    it('is 5', () => {
+        expect(EPIC_MIN_AC).toBe(5);
+    });
+});
+// ---------------------------------------------------------------------------
+// Unit: getLifecycleMode
+// ---------------------------------------------------------------------------
+describe('getLifecycleMode', () => {
+    let env;
+    beforeEach(async () => {
+        env = await createTestDb();
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('returns strict by default when no config', async () => {
+        // Remove the config.json written by createTestDb() so getLifecycleMode
+        // sees no project config and falls back to the 'strict' default.
+        await unlink(join(env.cleoDir, 'config.json'));
+        const mode = await getLifecycleMode(env.tempDir);
+        expect(mode).toBe('strict');
+    });
+    it('returns advisory from config', async () => {
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('advisory'));
+        const mode = await getLifecycleMode(env.tempDir);
+        expect(mode).toBe('advisory');
+    });
+    it('returns off from config', async () => {
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('off'));
+        const mode = await getLifecycleMode(env.tempDir);
+        expect(mode).toBe('off');
+    });
+});
+// ---------------------------------------------------------------------------
+// Unit: validateEpicCreation
+// ---------------------------------------------------------------------------
+describe('validateEpicCreation (strict mode)', () => {
+    let env;
+    beforeEach(async () => {
+        env = await createTestDb();
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('strict'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('accepts when 5 AC items and description are present', async () => {
+        const result = await validateEpicCreation({
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4', 'ac5'],
+            description: 'Some completion criteria',
+        }, env.tempDir);
+        expect(result.valid).toBe(true);
+        expect(result.warning).toBeUndefined();
+    });
+    it('throws when fewer than 5 AC items', async () => {
+        await expect(validateEpicCreation({
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4'],
+            description: 'Some completion criteria',
+        }, env.tempDir)).rejects.toThrow(/5 acceptance criteria/);
+    });
+    it('throws when description is empty', async () => {
+        await expect(validateEpicCreation({
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4', 'ac5'],
+            description: '',
+        }, env.tempDir)).rejects.toThrow(/non-empty description/);
+    });
+    it('throws when both AC count and description are insufficient', async () => {
+        await expect(validateEpicCreation({ acceptance: [], description: '   ' }, env.tempDir)).rejects.toThrow();
+    });
+});
+describe('validateEpicCreation (advisory mode)', () => {
+    let env;
+    beforeEach(async () => {
+        env = await createTestDb();
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('advisory'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('does not throw on violation, returns warning', async () => {
+        const result = await validateEpicCreation({ acceptance: ['ac1'], description: 'OK' }, env.tempDir);
+        expect(result.valid).toBe(true);
+        expect(result.warning).toMatch(/5 acceptance criteria/);
+    });
+});
+describe('validateEpicCreation (off mode)', () => {
+    let env;
+    beforeEach(async () => {
+        env = await createTestDb();
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('off'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('skips all checks and returns valid', async () => {
+        const result = await validateEpicCreation({ acceptance: [], description: '' }, env.tempDir);
+        expect(result.valid).toBe(true);
+        expect(result.warning).toBeUndefined();
+    });
+});
+// ---------------------------------------------------------------------------
+// Unit: validateChildStageCeiling
+// ---------------------------------------------------------------------------
+describe('validateChildStageCeiling (strict)', () => {
+    let env;
+    let accessor;
+    beforeEach(async () => {
+        env = await createTestDb();
+        accessor = env.accessor;
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('strict'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    async function seedEpicAtStage(stage) {
+        const now = new Date().toISOString();
+        await accessor.upsertSingleTask({
+            id: 'T001',
+            title: 'Epic',
+            description: 'Epic description',
+            status: 'pending',
+            priority: 'medium',
+            type: 'epic',
+            pipelineStage: stage,
+            createdAt: now,
+            updatedAt: now,
+        });
+        return 'T001';
+    }
+    it('allows child stage equal to epic stage', async () => {
+        const epicId = await seedEpicAtStage('specification');
+        const result = await validateChildStageCeiling({ childStage: 'specification', epicId }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+    });
+    it('allows child stage below epic stage', async () => {
+        const epicId = await seedEpicAtStage('implementation');
+        const result = await validateChildStageCeiling({ childStage: 'research', epicId }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+    });
+    it('throws when child stage exceeds epic stage', async () => {
+        const epicId = await seedEpicAtStage('research');
+        await expect(validateChildStageCeiling({ childStage: 'implementation', epicId }, accessor, env.tempDir)).rejects.toThrow(/cannot be at pipeline stage/);
+    });
+    it('skips check when epic ID does not exist', async () => {
+        const result = await validateChildStageCeiling({ childStage: 'testing', epicId: 'T999' }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+    });
+});
+describe('validateChildStageCeiling (advisory)', () => {
+    let env;
+    let accessor;
+    beforeEach(async () => {
+        env = await createTestDb();
+        accessor = env.accessor;
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('advisory'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('returns warning instead of throwing', async () => {
+        const now = new Date().toISOString();
+        await accessor.upsertSingleTask({
+            id: 'T001',
+            title: 'Epic',
+            description: 'desc',
+            status: 'pending',
+            priority: 'medium',
+            type: 'epic',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        const result = await validateChildStageCeiling({ childStage: 'testing', epicId: 'T001' }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+        expect(result.warning).toMatch(/cannot be at pipeline stage/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Unit: validateEpicStageAdvancement
+// ---------------------------------------------------------------------------
+describe('validateEpicStageAdvancement (strict)', () => {
+    let env;
+    let accessor;
+    beforeEach(async () => {
+        env = await createTestDb();
+        accessor = env.accessor;
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('strict'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('allows advancement when no children exist', async () => {
+        const result = await validateEpicStageAdvancement({ epicId: 'T001', currentStage: 'research', newStage: 'implementation' }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+    });
+    it('allows advancement when all children are done', async () => {
+        const now = new Date().toISOString();
+        // Seed epic
+        await accessor.upsertSingleTask({
+            id: 'T001',
+            title: 'Epic',
+            description: 'Epic',
+            status: 'pending',
+            priority: 'medium',
+            type: 'epic',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        // Seed done child at research
+        await accessor.upsertSingleTask({
+            id: 'T002',
+            title: 'Child',
+            description: 'Child',
+            status: 'done',
+            priority: 'medium',
+            type: 'task',
+            parentId: 'T001',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        const result = await validateEpicStageAdvancement({ epicId: 'T001', currentStage: 'research', newStage: 'implementation' }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+    });
+    it('throws when child is in-flight at current stage', async () => {
+        const now = new Date().toISOString();
+        await accessor.upsertSingleTask({
+            id: 'T001',
+            title: 'Epic',
+            description: 'Epic',
+            status: 'pending',
+            priority: 'medium',
+            type: 'epic',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        await accessor.upsertSingleTask({
+            id: 'T002',
+            title: 'Child',
+            description: 'Child',
+            status: 'active',
+            priority: 'medium',
+            type: 'task',
+            parentId: 'T001',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        await expect(validateEpicStageAdvancement({ epicId: 'T001', currentStage: 'research', newStage: 'implementation' }, accessor, env.tempDir)).rejects.toThrow(/cannot advance/);
+    });
+    it('ignores children at a different (later) stage', async () => {
+        const now = new Date().toISOString();
+        await accessor.upsertSingleTask({
+            id: 'T001',
+            title: 'Epic',
+            description: 'Epic',
+            status: 'pending',
+            priority: 'medium',
+            type: 'epic',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        // Child is at implementation (not at current stage 'research')
+        await accessor.upsertSingleTask({
+            id: 'T002',
+            title: 'Child',
+            description: 'Child',
+            status: 'active',
+            priority: 'medium',
+            type: 'task',
+            parentId: 'T001',
+            pipelineStage: 'implementation',
+            createdAt: now,
+            updatedAt: now,
+        });
+        const result = await validateEpicStageAdvancement({ epicId: 'T001', currentStage: 'research', newStage: 'implementation' }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+    });
+    it('ignores cancelled children at current stage', async () => {
+        const now = new Date().toISOString();
+        await accessor.upsertSingleTask({
+            id: 'T001',
+            title: 'Epic',
+            description: 'Epic',
+            status: 'pending',
+            priority: 'medium',
+            type: 'epic',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        await accessor.upsertSingleTask({
+            id: 'T002',
+            title: 'Child',
+            description: 'Child',
+            status: 'cancelled',
+            priority: 'medium',
+            type: 'task',
+            parentId: 'T001',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        const result = await validateEpicStageAdvancement({ epicId: 'T001', currentStage: 'research', newStage: 'implementation' }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+    });
+    it('is no-op for same-stage (no advancement)', async () => {
+        const result = await validateEpicStageAdvancement({ epicId: 'T001', currentStage: 'research', newStage: 'research' }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+    });
+});
+describe('validateEpicStageAdvancement (advisory)', () => {
+    let env;
+    let accessor;
+    beforeEach(async () => {
+        env = await createTestDb();
+        accessor = env.accessor;
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('advisory'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('returns warning instead of throwing when blocked', async () => {
+        const now = new Date().toISOString();
+        await accessor.upsertSingleTask({
+            id: 'T001',
+            title: 'Epic',
+            description: 'Epic',
+            status: 'pending',
+            priority: 'medium',
+            type: 'epic',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        await accessor.upsertSingleTask({
+            id: 'T002',
+            title: 'Child',
+            description: 'Child',
+            status: 'pending',
+            priority: 'medium',
+            type: 'task',
+            parentId: 'T001',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        const result = await validateEpicStageAdvancement({ epicId: 'T001', currentStage: 'research', newStage: 'implementation' }, accessor, env.tempDir);
+        expect(result.valid).toBe(true);
+        expect(result.warning).toMatch(/cannot advance/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Unit: findEpicAncestor
+// ---------------------------------------------------------------------------
+describe('findEpicAncestor', () => {
+    let env;
+    let accessor;
+    beforeEach(async () => {
+        env = await createTestDb();
+        accessor = env.accessor;
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('returns null when task has no ancestors', async () => {
+        const result = await findEpicAncestor('T999', accessor);
+        expect(result).toBeNull();
+    });
+    it('finds a direct epic parent', async () => {
+        const now = new Date().toISOString();
+        await accessor.upsertSingleTask({
+            id: 'T001',
+            title: 'Epic',
+            description: 'Epic',
+            status: 'pending',
+            priority: 'medium',
+            type: 'epic',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        await accessor.upsertSingleTask({
+            id: 'T002',
+            title: 'Child',
+            description: 'Child',
+            status: 'pending',
+            priority: 'medium',
+            type: 'task',
+            parentId: 'T001',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        // findEpicAncestor takes the task whose ancestors to walk.
+        // For T002's parent T001, we pass T001 to check its ancestors, OR
+        // we pass T002 to check ancestors of T002 (which includes T001).
+        const epic = await findEpicAncestor('T001', accessor);
+        // T001 has no ancestors (root level), so no epic ancestor
+        expect(epic).toBeNull();
+        // For T002's parent: we already know T001 is the epic, so we pass parentId=T001
+        // and check if T001 itself is an epic — that's handled in add.ts separately.
+        // findEpicAncestor walks ancestors of the supplied ID.
+        const fromChild = await findEpicAncestor('T002', accessor);
+        // T002's ancestor is T001 (epic) — should be found
+        expect(fromChild?.id).toBe('T001');
+    });
+    it('returns null when no epic in ancestor chain', async () => {
+        const now = new Date().toISOString();
+        await accessor.upsertSingleTask({
+            id: 'T001',
+            title: 'Parent task',
+            description: 'desc',
+            status: 'pending',
+            priority: 'medium',
+            type: 'task',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        await accessor.upsertSingleTask({
+            id: 'T002',
+            title: 'Child subtask',
+            description: 'desc',
+            status: 'pending',
+            priority: 'medium',
+            type: 'subtask',
+            parentId: 'T001',
+            pipelineStage: 'research',
+            createdAt: now,
+            updatedAt: now,
+        });
+        const epic = await findEpicAncestor('T002', accessor);
+        expect(epic).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// Integration: addTask epic creation enforcement
+// ---------------------------------------------------------------------------
+describe('addTask epic creation enforcement (strict)', () => {
+    let env;
+    let accessor;
+    beforeEach(async () => {
+        env = await createTestDb();
+        accessor = env.accessor;
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('strict'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('creates an epic when 5 AC and description are provided', async () => {
+        const result = await addTask({
+            title: 'My epic',
+            description: 'Completion criteria: all features shipped',
+            type: 'epic',
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4', 'ac5'],
+        }, env.tempDir, accessor);
+        expect(result.task.type).toBe('epic');
+        expect(result.task.acceptance?.length).toBe(5);
+    });
+    it('blocks epic creation with fewer than 5 AC', async () => {
+        await expect(addTask({
+            title: 'Bad epic',
+            description: 'Completion criteria here',
+            type: 'epic',
+            acceptance: ['ac1', 'ac2', 'ac3'],
+        }, env.tempDir, accessor)).rejects.toThrow(/5 acceptance criteria/);
+    });
+});
+describe('addTask child stage ceiling (strict)', () => {
+    let env;
+    let accessor;
+    beforeEach(async () => {
+        env = await createTestDb();
+        accessor = env.accessor;
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('strict'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('allows child at same stage as epic', async () => {
+        // Create epic at research
+        const epicResult = await addTask({
+            title: 'Epic',
+            description: 'Epic desc',
+            type: 'epic',
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4', 'ac5'],
+            pipelineStage: 'research',
+        }, env.tempDir, accessor);
+        const epicId = epicResult.task.id;
+        const childResult = await addTask({
+            title: 'Child',
+            description: 'Child task',
+            parentId: epicId,
+            pipelineStage: 'research',
+        }, env.tempDir, accessor);
+        expect(childResult.task.pipelineStage).toBe('research');
+    });
+    it('blocks child at stage beyond epic stage', async () => {
+        const epicResult = await addTask({
+            title: 'Epic',
+            description: 'Epic desc',
+            type: 'epic',
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4', 'ac5'],
+            pipelineStage: 'research',
+        }, env.tempDir, accessor);
+        const epicId = epicResult.task.id;
+        await expect(addTask({
+            title: 'Child',
+            description: 'Child task',
+            parentId: epicId,
+            pipelineStage: 'implementation',
+        }, env.tempDir, accessor)).rejects.toThrow(/cannot be at pipeline stage/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Integration: updateTask epic stage advancement gate
+// ---------------------------------------------------------------------------
+describe('updateTask epic stage advancement gate (strict)', () => {
+    let env;
+    let accessor;
+    beforeEach(async () => {
+        env = await createTestDb();
+        accessor = env.accessor;
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('strict'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('allows advancing epic stage when no in-flight children at current stage', async () => {
+        // Create epic at research with 5 AC
+        const epicResult = await addTask({
+            title: 'Epic',
+            description: 'Epic desc',
+            type: 'epic',
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4', 'ac5'],
+            pipelineStage: 'research',
+        }, env.tempDir, accessor);
+        const epicId = epicResult.task.id;
+        // Advance epic to implementation — no children
+        const updateResult = await updateTask({ taskId: epicId, pipelineStage: 'implementation' }, env.tempDir, accessor);
+        expect(updateResult.task.pipelineStage).toBe('implementation');
+    });
+    it('blocks advancing epic when child is in-flight at current stage', async () => {
+        // Create epic at research
+        const epicResult = await addTask({
+            title: 'Epic',
+            description: 'Epic desc',
+            type: 'epic',
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4', 'ac5'],
+            pipelineStage: 'research',
+        }, env.tempDir, accessor);
+        const epicId = epicResult.task.id;
+        // Create in-flight child at research stage
+        await addTask({
+            title: 'Child',
+            description: 'Child task',
+            parentId: epicId,
+            pipelineStage: 'research',
+        }, env.tempDir, accessor);
+        // Attempt to advance epic — should be blocked
+        await expect(updateTask({ taskId: epicId, pipelineStage: 'implementation' }, env.tempDir, accessor)).rejects.toThrow(/cannot advance/);
+    });
+});
+describe('updateTask child stage ceiling on update (strict)', () => {
+    let env;
+    let accessor;
+    beforeEach(async () => {
+        env = await createTestDb();
+        accessor = env.accessor;
+        await writeFile(join(env.cleoDir, 'config.json'), makeConfig('strict'));
+    });
+    afterEach(async () => {
+        await env.cleanup();
+    });
+    it('blocks updating child to a stage beyond epic', async () => {
+        // Create epic at research
+        const epicResult = await addTask({
+            title: 'Epic',
+            description: 'Epic desc',
+            type: 'epic',
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4', 'ac5'],
+            pipelineStage: 'research',
+        }, env.tempDir, accessor);
+        const epicId = epicResult.task.id;
+        // Create child at research
+        const childResult = await addTask({
+            title: 'Child',
+            description: 'Child task',
+            parentId: epicId,
+            pipelineStage: 'research',
+        }, env.tempDir, accessor);
+        const childId = childResult.task.id;
+        // Attempt to update child to implementation (beyond epic's research)
+        await expect(updateTask({ taskId: childId, pipelineStage: 'implementation' }, env.tempDir, accessor)).rejects.toThrow(/cannot be at pipeline stage/);
+    });
+    it('allows updating child to a stage equal to epic', async () => {
+        // Create epic at implementation
+        const epicResult = await addTask({
+            title: 'Epic',
+            description: 'Epic desc',
+            type: 'epic',
+            acceptance: ['ac1', 'ac2', 'ac3', 'ac4', 'ac5'],
+            pipelineStage: 'implementation',
+        }, env.tempDir, accessor);
+        const epicId = epicResult.task.id;
+        // Create child at research
+        const childResult = await addTask({
+            title: 'Child',
+            description: 'Child task',
+            parentId: epicId,
+            pipelineStage: 'research',
+        }, env.tempDir, accessor);
+        const childId = childResult.task.id;
+        // Update child to implementation (same as epic)
+        const updateResult = await updateTask({ taskId: childId, pipelineStage: 'implementation' }, env.tempDir, accessor);
+        expect(updateResult.task.pipelineStage).toBe('implementation');
+    });
+});
+//# sourceMappingURL=epic-enforcement.test.js.map