create-claude-workspace 1.1.151 → 2.0.0

package/dist/scheduler/tasks/parser.mjs

@@ -0,0 +1,228 @@
+// ─── Pure parser: TODO.md → structured Task[] ───
+// Zero side effects. All I/O happens in the caller.
+// ─── Patterns ───
+const PHASE_HEADING = /^##\s+Phase\s+(\d+)\s*[:\-–—]\s*(.*)$/;
+const TASK_LINE = /^- \[([ x~])\]\s+(.+)$/;
+const ISSUE_MARKER_GH = /<!--\s*#(\d+)\s*-->/;
+const ISSUE_MARKER_CU = /<!--\s*cu:(\S+)\s*-->/;
+const METADATA_LINE = /^\s{2,}- ([A-Za-z][A-Za-z \-]*[A-Za-z]):\s*(.+)$/;
+// ─── Status mapping ───
+function parseCheckbox(char) {
+    if (char === 'x')
+        return 'done';
+    if (char === '~')
+        return 'skipped';
+    return 'todo';
+}
+// ─── Title extraction ───
+function parseTitle(raw) {
+    // Remove bold markers: **Title** — description
+    let title = raw;
+    // Remove issue markers
+    title = title.replace(/<!--.*?-->/g, '').trim();
+    // Remove completion markers: ✅ a1b2c3d (2026-03-05)
+    title = title.replace(/✅\s*\w+\s*\(\d{4}-\d{2}-\d{2}\)\s*$/, '').trim();
+    // Remove strikethrough: ~~**Title**~~ — SKIPPED: ...
+    title = title.replace(/^~~(.+?)~~/, '$1').trim();
+    // Extract just the bold title part: **Title** — description → Title
+    const boldMatch = title.match(/^\*\*(.+?)\*\*/);
+    if (boldMatch)
+        return boldMatch[1].trim();
+    // Fallback: take text before em dash
+    const dashIdx = title.search(/\s[—–-]\s/);
+    if (dashIdx > 0)
+        return title.slice(0, dashIdx).trim();
+    return title.trim();
+}
+// ─── Issue marker extraction ───
+function parseIssueMarker(raw) {
+    const gh = raw.match(ISSUE_MARKER_GH);
+    if (gh)
+        return `#${gh[1]}`;
+    const cu = raw.match(ISSUE_MARKER_CU);
+    if (cu)
+        return `cu:${cu[1]}`;
+    return null;
+}
+function parseType(raw) {
+    const lower = raw.trim().toLowerCase();
+    if (lower === 'frontend')
+        return 'frontend';
+    if (lower === 'backend')
+        return 'backend';
+    if (lower === 'fullstack')
+        return 'fullstack';
+    return 'fullstack';
+}
+function parseComplexity(raw) {
+    const upper = raw.trim().toUpperCase();
+    if (upper === 'S')
+        return 'S';
+    if (upper === 'M')
+        return 'M';
+    if (upper === 'L')
+        return 'L';
+    return 'M';
+}
+function parseDependsOn(raw, phase) {
+    const trimmed = raw.trim();
+    if (trimmed.toLowerCase() === 'nothing' || trimmed === '-' || trimmed === '')
+        return [];
+    return trimmed
+        .split(/[,/]/)
+        .map(dep => dep.trim())
+        .filter(dep => dep.length > 0 && dep.toLowerCase() !== 'nothing');
+}
+function inferChangelogCategory(title, status) {
+    if (status === 'skipped')
+        return 'none';
+    const lower = title.toLowerCase();
+    if (lower.startsWith('fix') || lower.includes('bug'))
+        return 'fixed';
+    if (lower.startsWith('refactor') || lower.startsWith('chore') || lower.startsWith('update config'))
+        return 'none';
+    if (lower.includes('breaking') || lower.includes('remove') || lower.includes('drop'))
+        return 'breaking';
+    if (lower.includes('change') || lower.includes('rename') || lower.includes('migrate'))
+        return 'changed';
+    return 'added';
+}
+// ─── Main parser ───
+export function parseTodoMd(content) {
+    const lines = content.split('\n');
+    const tasks = [];
+    let currentPhase = -1;
+    let pendingTask = null;
+    let pendingMetadata = {};
+    function flushTask() {
+        if (!pendingTask)
+            return;
+        const meta = resolveMetadata(pendingMetadata);
+        const title = parseTitle(pendingTask.raw);
+        const id = `p${pendingTask.phase}-${tasks.filter(t => t.phase === pendingTask.phase).length + 1}`;
+        tasks.push({
+            id,
+            title,
+            phase: pendingTask.phase,
+            type: meta.type,
+            complexity: meta.complexity,
+            status: pendingTask.status,
+            dependsOn: meta.dependsOn,
+            issueMarker: pendingTask.issueMarker,
+            kitUpgrade: meta.kitUpgrade,
+            lineNumber: pendingTask.lineNumber,
+            changelog: inferChangelogCategory(title, pendingTask.status),
+        });
+        pendingTask = null;
+        pendingMetadata = {};
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Phase heading
+        const phaseMatch = line.match(PHASE_HEADING);
+        if (phaseMatch) {
+            flushTask();
+            currentPhase = parseInt(phaseMatch[1], 10);
+            continue;
+        }
+        // Task line
+        const taskMatch = line.match(TASK_LINE);
+        if (taskMatch && currentPhase >= 0) {
+            flushTask();
+            pendingTask = {
+                raw: taskMatch[2],
+                status: parseCheckbox(taskMatch[1]),
+                lineNumber: i + 1,
+                phase: currentPhase,
+                issueMarker: parseIssueMarker(taskMatch[2]),
+            };
+            continue;
+        }
+        // Metadata line (indented sub-item under a task)
+        if (pendingTask) {
+            const metaMatch = line.match(METADATA_LINE);
+            if (metaMatch) {
+                pendingMetadata[metaMatch[1]] = metaMatch[2];
+                continue;
+            }
+            // Non-metadata, non-empty line that isn't a continuation → flush
+            if (line.trim() !== '' && !line.match(/^\s{2,}-\s/) && !line.match(/^\s{4,}/)) {
+                flushTask();
+            }
+        }
+    }
+    // Flush last pending task
+    flushTask();
+    return tasks;
+}
+function resolveMetadata(meta) {
+    return {
+        type: meta['Type'] ? parseType(meta['Type']) : 'fullstack',
+        complexity: meta['Complexity'] ? parseComplexity(meta['Complexity']) : 'M',
+        dependsOn: meta['Depends on'] ? parseDependsOn(meta['Depends on'], 0) : [],
+        kitUpgrade: 'Kit-Upgrade' in meta,
+    };
+}
+// ─── Dependency resolution helpers ───
+/**
+ * Resolves human-readable dependency references ("Phase 0", "Create auth types")
+ * to task IDs. Returns unresolved references as-is for error reporting.
+ */
+export function resolveDependencies(tasks) {
+    const titleToId = new Map();
+    const phaseToIds = new Map();
+    for (const task of tasks) {
+        titleToId.set(task.title.toLowerCase(), task.id);
+        const phaseList = phaseToIds.get(task.phase) ?? [];
+        phaseList.push(task.id);
+        phaseToIds.set(task.phase, phaseList);
+    }
+    const resolved = new Map();
+    for (const task of tasks) {
+        const deps = [];
+        for (const dep of task.dependsOn) {
+            // "Phase N" → all tasks in that phase
+            const phaseRef = dep.match(/^Phase\s+(\d+)$/i);
+            if (phaseRef) {
+                const phaseNum = parseInt(phaseRef[1], 10);
+                const phaseTasks = phaseToIds.get(phaseNum) ?? [];
+                deps.push(...phaseTasks);
+                continue;
+            }
+            // Exact title match (case-insensitive)
+            const byTitle = titleToId.get(dep.toLowerCase());
+            if (byTitle) {
+                deps.push(byTitle);
+                continue;
+            }
+            // Partial title match (contains)
+            let found = false;
+            for (const [title, id] of titleToId) {
+                if (title.includes(dep.toLowerCase()) || dep.toLowerCase().includes(title)) {
+                    deps.push(id);
+                    found = true;
+                    break;
+                }
+            }
+            // Unresolved — keep as-is (error will be caught by task-queue validation)
+            if (!found)
+                deps.push(`unresolved:${dep}`);
+        }
+        resolved.set(task.id, deps);
+    }
+    return resolved;
+}
+/**
+ * Updates a single task's checkbox in TODO.md content.
+ * Returns the updated content string.
+ */
+export function updateTaskCheckbox(content, lineNumber, newStatus) {
+    const lines = content.split('\n');
+    const idx = lineNumber - 1;
+    if (idx < 0 || idx >= lines.length)
+        return content;
+    const line = lines[idx];
+    const checkbox = newStatus === 'done' ? '[x]' : newStatus === 'skipped' ? '[~]' : '[ ]';
+    lines[idx] = line.replace(/\[([ x~])\]/, checkbox);
+    return lines.join('\n');
+}

package/dist/scheduler/tasks/parser.spec.js

@@ -0,0 +1,303 @@
+import { describe, it, expect } from 'vitest';
+import { parseTodoMd, resolveDependencies, updateTaskCheckbox } from './parser.mjs';
+// ─── Test fixtures ───
+const MINIMAL_TODO = `# TODO.md
+
+## Phase 0: Foundation
+
+- [ ] **Set up project scaffolding** — Nx workspace, ESLint, Prettier
+  - Type: fullstack
+  - Complexity: M
+  - Depends on: nothing
+`;
+const FULL_TODO = `# TODO.md
+
+> Auto-generated from PRODUCT.md by technical-planner agent.
+
+## Phase 0: Foundation
+Infrastructure and tooling.
+
+- [x] **Set up Nx workspace** — monorepo scaffolding ✅ a1b2c3d (2026-03-15) <!-- #1 -->
+  - Type: fullstack
+  - Files: \`workspace.json\`, \`nx.json\`
+  - Depends on: nothing
+  - Acceptance: nx build works
+  - Complexity: S
+
+- [~] ~~**Legacy migration tool**~~ — SKIPPED: blocked by missing API
+  - Type: backend
+  - Complexity: M
+  - Depends on: nothing
+
+## Phase 1: User Authentication
+Registration, login, sessions.
+
+- [ ] **Create auth domain types** — User, Session interfaces <!-- #5 -->
+  - Type: backend
+  - Files: \`libs/auth/domain/\`
+  - Depends on: Phase 0
+  - Acceptance: TypeScript compiles
+  - Complexity: S
+
+- [ ] **Implement registration flow** — email, password, DB <!-- #6 -->
+  - Type: fullstack
+  - Files: \`apps/api/src/routes/auth.ts\`, \`apps/frontend/src/pages/register.tsx\`
+  - Depends on: Create auth domain types
+  - Acceptance: User can register
+  - Complexity: M
+
+- [ ] **OAuth integration** — GitHub OAuth provider <!-- #7 -->
+  - Type: backend
+  - Depends on: Phase 0
+  - Complexity: S
+
+## Phase 2: Dashboard
+User dashboard with analytics.
+
+- [ ] **Dashboard layout** — responsive grid <!-- #10 -->
+  - Type: frontend
+  - Depends on: Phase 1
+  - Complexity: L
+
+- [ ] **Upgrade sharp@0.32 → 0.33** — major version, review breaking changes
+  - Type: backend
+  - Depends on: nothing
+  - Complexity: S
+  - Kit-Upgrade: v2.1.0
+`;
+const CLICKUP_TODO = `# TODO.md
+
+## Phase 0: Setup
+
+- [ ] **Init workspace** — scaffold everything <!-- cu:abc123def -->
+  - Type: fullstack
+  - Complexity: S
+  - Depends on: nothing
+`;
+// ─── parseTodoMd ───
+describe('parseTodoMd', () => {
+    it('parses a minimal TODO with one task', () => {
+        const tasks = parseTodoMd(MINIMAL_TODO);
+        expect(tasks).toHaveLength(1);
+        expect(tasks[0]).toMatchObject({
+            id: 'p0-1',
+            title: 'Set up project scaffolding',
+            phase: 0,
+            type: 'fullstack',
+            complexity: 'M',
+            status: 'todo',
+            dependsOn: [],
+            issueMarker: null,
+            kitUpgrade: false,
+        });
+    });
+    it('parses all tasks from a full TODO', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        expect(tasks).toHaveLength(7);
+    });
+    it('parses phase numbers correctly', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        expect(tasks.filter(t => t.phase === 0)).toHaveLength(2);
+        expect(tasks.filter(t => t.phase === 1)).toHaveLength(3);
+        expect(tasks.filter(t => t.phase === 2)).toHaveLength(2);
+    });
+    it('parses checkbox states', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        expect(tasks[0].status).toBe('done');
+        expect(tasks[1].status).toBe('skipped');
+        expect(tasks[2].status).toBe('todo');
+    });
+    it('parses task types', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        expect(tasks[0].type).toBe('fullstack');
+        expect(tasks[1].type).toBe('backend');
+        expect(tasks[2].type).toBe('backend');
+        expect(tasks[3].type).toBe('fullstack');
+    });
+    it('parses complexity levels', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        expect(tasks[0].complexity).toBe('S');
+        expect(tasks[1].complexity).toBe('M');
+        expect(tasks[5].complexity).toBe('L');
+    });
+    it('extracts GitHub issue markers', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        expect(tasks[0].issueMarker).toBe('#1');
+        expect(tasks[2].issueMarker).toBe('#5');
+        expect(tasks[1].issueMarker).toBeNull();
+    });
+    it('extracts ClickUp issue markers', () => {
+        const tasks = parseTodoMd(CLICKUP_TODO);
+        expect(tasks[0].issueMarker).toBe('cu:abc123def');
+    });
+    it('parses raw dependency references', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        // "nothing" → empty
+        expect(tasks[0].dependsOn).toEqual([]);
+        // "Phase 0" → kept as string for resolution
+        expect(tasks[2].dependsOn).toEqual(['Phase 0']);
+        // "Create auth domain types" → kept as string
+        expect(tasks[3].dependsOn).toEqual(['Create auth domain types']);
+    });
+    it('detects kit-upgrade tasks', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        const kitTask = tasks.find(t => t.kitUpgrade);
+        expect(kitTask).toBeDefined();
+        expect(kitTask.title).toBe('Upgrade sharp@0.32 → 0.33');
+    });
+    it('extracts clean titles from bold markdown', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        expect(tasks[0].title).toBe('Set up Nx workspace');
+        expect(tasks[2].title).toBe('Create auth domain types');
+    });
+    it('extracts clean titles from skipped (strikethrough) tasks', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        expect(tasks[1].title).toBe('Legacy migration tool');
+    });
+    it('assigns sequential IDs per phase', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        expect(tasks[0].id).toBe('p0-1');
+        expect(tasks[1].id).toBe('p0-2');
+        expect(tasks[2].id).toBe('p1-1');
+        expect(tasks[3].id).toBe('p1-2');
+        expect(tasks[4].id).toBe('p1-3');
+        expect(tasks[5].id).toBe('p2-1');
+        expect(tasks[6].id).toBe('p2-2');
+    });
+    it('records line numbers for checkbox updates', () => {
+        const tasks = parseTodoMd(MINIMAL_TODO);
+        expect(tasks[0].lineNumber).toBeGreaterThan(0);
+        // Verify the line number points to the actual task line
+        const lines = MINIMAL_TODO.split('\n');
+        expect(lines[tasks[0].lineNumber - 1]).toMatch(/^- \[ \]/);
+    });
+    it('infers changelog category from title', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        // "Set up Nx workspace" (done) → added
+        expect(tasks[0].changelog).toBe('added');
+        // "Legacy migration tool" (skipped) → none
+        expect(tasks[1].changelog).toBe('none');
+    });
+    it('handles empty content', () => {
+        expect(parseTodoMd('')).toEqual([]);
+    });
+    it('handles content with no phases', () => {
+        expect(parseTodoMd('# Just a heading\nSome text.')).toEqual([]);
+    });
+    it('handles tasks without metadata', () => {
+        const noMeta = `## Phase 0: Stuff\n- [ ] **Do something** — a task\n`;
+        const tasks = parseTodoMd(noMeta);
+        expect(tasks).toHaveLength(1);
+        expect(tasks[0].type).toBe('fullstack');
+        expect(tasks[0].complexity).toBe('M');
+    });
+    it('handles multiple depends separated by /', () => {
+        const multiDep = `## Phase 1: X
+- [ ] **Task A** — first
+  - Type: backend
+  - Complexity: S
+  - Depends on: Auth types / Session manager
+`;
+        const tasks = parseTodoMd(multiDep);
+        expect(tasks[0].dependsOn).toEqual(['Auth types', 'Session manager']);
+    });
+    it('handles multiple depends separated by comma', () => {
+        const multiDep = `## Phase 1: X
+- [ ] **Task B** — second
+  - Type: backend
+  - Complexity: S
+  - Depends on: Auth types, Session manager
+`;
+        const tasks = parseTodoMd(multiDep);
+        expect(tasks[0].dependsOn).toEqual(['Auth types', 'Session manager']);
+    });
+});
+// ─── resolveDependencies ───
+describe('resolveDependencies', () => {
+    it('resolves "Phase N" to all tasks in that phase', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        const resolved = resolveDependencies(tasks);
+        // "Create auth domain types" depends on Phase 0 → p0-1, p0-2
+        const authDeps = resolved.get('p1-1');
+        expect(authDeps).toContain('p0-1');
+        expect(authDeps).toContain('p0-2');
+    });
+    it('resolves exact title references', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        const resolved = resolveDependencies(tasks);
+        // "Implement registration flow" depends on "Create auth domain types" → p1-1
+        const regDeps = resolved.get('p1-2');
+        expect(regDeps).toContain('p1-1');
+    });
+    it('resolves partial title matches', () => {
+        const todo = `## Phase 0: Setup
+- [ ] **Create authentication domain types** — interfaces
+  - Type: backend
+  - Complexity: S
+  - Depends on: nothing
+- [ ] **Implement login** — flow
+  - Type: backend
+  - Complexity: M
+  - Depends on: authentication domain
+`;
+        const tasks = parseTodoMd(todo);
+        const resolved = resolveDependencies(tasks);
+        const loginDeps = resolved.get('p0-2');
+        expect(loginDeps).toContain('p0-1');
+    });
+    it('marks unresolvable dependencies', () => {
+        const todo = `## Phase 0: Setup
+- [ ] **Task A** — something
+  - Type: backend
+  - Complexity: S
+  - Depends on: Non-existent task
+`;
+        const tasks = parseTodoMd(todo);
+        const resolved = resolveDependencies(tasks);
+        expect(resolved.get('p0-1')[0]).toBe('unresolved:Non-existent task');
+    });
+    it('returns empty deps for tasks with no dependencies', () => {
+        const tasks = parseTodoMd(MINIMAL_TODO);
+        const resolved = resolveDependencies(tasks);
+        expect(resolved.get('p0-1')).toEqual([]);
+    });
+});
+// ─── updateTaskCheckbox ───
+describe('updateTaskCheckbox', () => {
+    it('marks a todo task as done', () => {
+        const tasks = parseTodoMd(MINIMAL_TODO);
+        const updated = updateTaskCheckbox(MINIMAL_TODO, tasks[0].lineNumber, 'done');
+        expect(updated).toContain('- [x] **Set up project scaffolding**');
+    });
+    it('marks a todo task as skipped', () => {
+        const tasks = parseTodoMd(MINIMAL_TODO);
+        const updated = updateTaskCheckbox(MINIMAL_TODO, tasks[0].lineNumber, 'skipped');
+        expect(updated).toContain('- [~] **Set up project scaffolding**');
+    });
+    it('marks a done task back to todo', () => {
+        const doneTodo = `## Phase 0: X\n- [x] **Done task** — was done\n`;
+        const updated = updateTaskCheckbox(doneTodo, 2, 'todo');
+        expect(updated).toContain('- [ ] **Done task**');
+    });
+    it('returns content unchanged for invalid line number', () => {
+        expect(updateTaskCheckbox(MINIMAL_TODO, 999, 'done')).toBe(MINIMAL_TODO);
+        expect(updateTaskCheckbox(MINIMAL_TODO, 0, 'done')).toBe(MINIMAL_TODO);
+        expect(updateTaskCheckbox(MINIMAL_TODO, -1, 'done')).toBe(MINIMAL_TODO);
+    });
+    it('preserves all other lines', () => {
+        const tasks = parseTodoMd(FULL_TODO);
+        const updated = updateTaskCheckbox(FULL_TODO, tasks[2].lineNumber, 'done');
+        const originalLines = FULL_TODO.split('\n');
+        const updatedLines = updated.split('\n');
+        expect(updatedLines).toHaveLength(originalLines.length);
+        // Only the target line should change
+        for (let i = 0; i < originalLines.length; i++) {
+            if (i === tasks[2].lineNumber - 1) {
+                expect(updatedLines[i]).not.toBe(originalLines[i]);
+            }
+            else {
+                expect(updatedLines[i]).toBe(originalLines[i]);
+            }
+        }
+    });
+});

package/dist/scheduler/tasks/queue.mjs

@@ -0,0 +1,152 @@
+// ─── Dependency resolution and task scheduling ───
+import { resolveDependencies } from './parser.mjs';
+// ─── Build dependency graph ───
+export function buildGraph(tasks) {
+    const resolved = resolveDependencies(tasks);
+    const taskMap = new Map();
+    const depsMap = new Map();
+    for (const task of tasks) {
+        taskMap.set(task.id, task);
+        const deps = resolved.get(task.id) ?? [];
+        // Filter out unresolved deps and self-references
+        depsMap.set(task.id, deps.filter(d => !d.startsWith('unresolved:') && d !== task.id));
+    }
+    return {
+        tasks: taskMap,
+        runnable() {
+            const result = [];
+            for (const task of taskMap.values()) {
+                if (task.status !== 'todo')
+                    continue;
+                const deps = depsMap.get(task.id) ?? [];
+                const allSatisfied = deps.every(depId => {
+                    const dep = taskMap.get(depId);
+                    return dep && (dep.status === 'done' || dep.status === 'skipped');
+                });
+                if (allSatisfied)
+                    result.push(task);
+            }
+            // Kit-upgrade tasks first, then by phase, then by complexity (S before M before L)
+            return result.sort((a, b) => {
+                if (a.kitUpgrade !== b.kitUpgrade)
+                    return a.kitUpgrade ? -1 : 1;
+                if (a.phase !== b.phase)
+                    return a.phase - b.phase;
+                return complexityOrder(a.complexity) - complexityOrder(b.complexity);
+            });
+        },
+        findCycle() {
+            return detectCycle(taskMap, depsMap);
+        },
+    };
+}
+// ─── Parallel batching ───
+/**
+ * Groups runnable tasks that have no mutual dependencies
+ * and can safely run in parallel in separate worktrees.
+ */
+export function getParallelBatches(runnable) {
+    if (runnable.length === 0)
+        return [];
+    if (runnable.length === 1)
+        return [runnable];
+    // Simple strategy: tasks in different phases can't run in parallel
+    // (phase N+1 may depend on phase N results).
+    // Within the same phase, all runnable tasks are independent by definition
+    // (their deps are already satisfied).
+    const byPhase = new Map();
+    for (const task of runnable) {
+        const phase = byPhase.get(task.phase) ?? [];
+        phase.push(task);
+        byPhase.set(task.phase, phase);
+    }
+    // Only return tasks from the lowest phase
+    const lowestPhase = Math.min(...byPhase.keys());
+    const batch = byPhase.get(lowestPhase) ?? [];
+    return batch.length > 0 ? [batch] : [];
+}
+// ─── Cycle detection (DFS) ───
+function detectCycle(tasks, deps) {
+    const visited = new Set();
+    const inStack = new Set();
+    const path = [];
+    function dfs(id) {
+        if (inStack.has(id)) {
+            // Found a cycle — extract it
+            const cycleStart = path.indexOf(id);
+            return [...path.slice(cycleStart), id];
+        }
+        if (visited.has(id))
+            return null;
+        visited.add(id);
+        inStack.add(id);
+        path.push(id);
+        for (const dep of deps.get(id) ?? []) {
+            if (!tasks.has(dep))
+                continue; // Skip unresolvable deps
+            const cycle = dfs(dep);
+            if (cycle)
+                return cycle;
+        }
+        path.pop();
+        inStack.delete(id);
+        return null;
+    }
+    for (const id of tasks.keys()) {
+        const cycle = dfs(id);
+        if (cycle)
+            return cycle;
+    }
+    return null;
+}
+// ─── Helpers ───
+function complexityOrder(c) {
+    if (c === 'S')
+        return 0;
+    if (c === 'M')
+        return 1;
+    return 2; // L
+}
+/**
+ * Returns tasks that are blocked (have unsatisfied deps).
+ */
+export function getBlockedTasks(graph) {
+    const blocked = [];
+    for (const task of graph.tasks.values()) {
+        if (task.status !== 'todo')
+            continue;
+        // If it's todo but not runnable, it's blocked
+        const runnable = graph.runnable();
+        if (!runnable.find(t => t.id === task.id)) {
+            blocked.push(task);
+        }
+    }
+    return blocked;
+}
+/**
+ * Check if all tasks in a phase are done or skipped.
+ */
+export function isPhaseComplete(tasks, phase) {
+    const phaseTasks = tasks.filter(t => t.phase === phase);
+    if (phaseTasks.length === 0)
+        return false;
+    return phaseTasks.every(t => t.status === 'done' || t.status === 'skipped');
+}
+/**
+ * Get the next phase number (lowest phase with remaining todo tasks).
+ */
+export function getNextPhase(tasks) {
+    const phases = [...new Set(tasks.map(t => t.phase))].sort((a, b) => a - b);
+    for (const phase of phases) {
+        if (tasks.some(t => t.phase === phase && t.status === 'todo')) {
+            return phase;
+        }
+    }
+    return null;
+}
+/**
+ * Check if all tasks across all phases are done or skipped.
+ */
+export function isProjectComplete(tasks) {
+    return tasks.length > 0 && tasks.every(t => t.status === 'done' || t.status === 'skipped');
+}