maistro 1.2.3 → 1.2.6

package/dist/planner.js

@@ -171,14 +171,36 @@ async function callClaudeCode(prompt, cwd, onOutput, abortSignal) {
         };
     }
 }
-const DECOMPOSITION_PROMPT = `You are a project planning assistant. Your job is to break down a project goal into a series of small, atomic tasks that can be executed sequentially by an AI coding assistant (Claude Code).
+const PLANNING_PROMPT = `You are a project planning assistant. Your job is to break down user requests into small, atomic tasks that can be executed sequentially by an AI coding assistant (Claude Code).
+
+This is PLANNING MODE - you must NEVER execute actions. When the user says things like "run tests", "add feature X", "fix bug Y", or ANY action-sounding request:
+1. First, check if the request is clear enough to create well-defined tasks
+2. If unclear or ambiguous, return CLARIFYING QUESTIONS as structured JSON
+3. If clear enough, create TASKS and return them as JSON
+4. NEVER actually execute the action yourself
+
+DO NOT:
+- Execute tests or builds
+- Make any changes to the codebase
+
+WHEN TO ASK QUESTIONS:
+- Request mentions a feature but lacks specifics (e.g., "add authentication" - what type?)
+- Multiple valid approaches exist (e.g., "add a button" - where? what should it do?)
+- Technical choices need to be made (e.g., "add database" - which one?)
+- Requirements are vague (e.g., "make it better" - in what way?)
+
+WHEN TO CREATE TASKS DIRECTLY:
+- Request is specific and actionable (e.g., "add a logout button to the header")
+- Simple operations (e.g., "run tests", "fix typo in README")
+- User has already provided enough context
+
+## Task Decomposition Guidelines
 
-Guidelines for task decomposition:
 1. Each task should be completable in a single coding session (10-30 minutes)
 2. Tasks should be ordered by dependency (tasks that depend on others come later)
 3. Each task should have a clear, specific objective
 4. Include setup tasks if needed (e.g., "Initialize project structure")
-5. Include tests for each task by default, unless the user explicitly requests otherwise
+5. Each task's description must include writing tests for the functionality implemented in that task, unless the user explicitly requests otherwise. If the task involves UI changes, include a UI test; otherwise a unit test is sufficient
 6. Be specific about what files or components are involved
 7. Consider which tasks are critical vs optional - critical tasks should stop execution if they fail
 8. IMPORTANT: Each task MUST have clear, verifiable acceptance criteria
@@ -208,6 +230,8 @@ Outcome-based criteria allow flexibility while ensuring the desired functionalit
 
 Only use structural criteria when the structure itself IS the requirement (e.g., "Uses SwiftData" if iOS 17+ SwiftData is a hard requirement from the user).
 
+## Task Schema
+
 For each task, provide:
 - id: A unique identifier (e.g., "task-1", "task-2")
 - title: A short, descriptive title
@@ -216,6 +240,7 @@ For each task, provide:
   - Focus on observable behavior or testable functionality
   - Be verifiable by running the app or tests (not by inspecting code structure)
   - Avoid specifying exact file names, class names, or method signatures
+  - Include at least one criterion about tests passing (e.g., "Unit tests pass for the new functionality")
 - dependencies: Array of task IDs that must complete before this task (empty for first tasks)
 - contextPatterns: Glob patterns for files relevant to this task (e.g., ["src/**/*.ts", "package.json"])
 - ifFailed: What to do if this task fails after retries. IMPORTANT: Default is "skip"
@@ -223,37 +248,66 @@ For each task, provide:
   - "stop": Stop execution entirely - ONLY use for truly critical tasks where nothing else can proceed
   - "retry": Keep retrying indefinitely (use sparingly)
 
-Respond with a JSON array of tasks. Example format:
-[
-  {
-    "id": "task-1",
-    "title": "Initialize project structure",
-    "description": "Create the basic project structure with package.json, tsconfig.json, and src directory",
-    "acceptanceCriteria": [
-      "Project can be installed with npm install",
-      "TypeScript compilation succeeds with strict mode",
-      "Project structure follows standard conventions"
-    ],
-    "dependencies": [],
-    "contextPatterns": ["package.json", "tsconfig.json"],
-    "ifFailed": "skip"
-  },
-  {
-    "id": "task-2",
-    "title": "Implement user model",
-    "description": "Create a User type and model with fields for id, name, email. The model should be exportable for use in other modules.",
-    "acceptanceCriteria": [
-      "User type can be imported from the models module",
-      "User objects can be created with id, name, and email fields",
-      "TypeScript provides proper type checking for User objects"
-    ],
-    "dependencies": ["task-1"],
-    "contextPatterns": ["src/models/**/*.ts"],
-    "ifFailed": "skip"
-  }
-]
-
-IMPORTANT: Return ONLY the JSON array, no other text or markdown formatting.`;
+## Project Context
+
+Project: {PROJECT_NAME}
+
+{PENDING_SECTION}
+
+## Task ID Rules
+- New tasks: Use IDs starting at task-{NEXT_ID}, incrementing for each additional task
+- Modifying pending tasks: Use the EXACT existing task ID from the pending tasks list
+- NEVER reuse IDs from completed tasks
+
+## Response Format
+
+Create tasks for what the user is asking. Do not add unrelated tasks.
+
+You MUST return ONE of these two JSON formats:
+
+Option 1: Questions (when clarification needed)
+\`\`\`json
+{
+  "type": "questions",
+  "questions": [
+    {
+      "id": "question-1",
+      "question": "Where should the speed indicator be displayed?",
+      "type": "choice",
+      "options": ["Below the tap count", "In the stats section", "As a live updating label", "Other"],
+      "reason": "This determines the UI layout approach"
+    }
+  ]
+}
+\`\`\`
+
+Option 2: Tasks (when request is clear)
+\`\`\`json
+{
+  "type": "tasks",
+  "tasks": [
+    {
+      "id": "task-{NEXT_ID}",
+      "title": "Add speed indicator",
+      "description": "Display clicks per minute below the tap count. Write unit tests to verify the CPM calculation logic and UI tests to verify the indicator displays correctly.",
+      "acceptanceCriteria": [
+        "Speed indicator updates in real-time as user taps",
+        "Display shows clicks per minute with proper formatting",
+        "Unit tests pass for CPM calculation and display"
+      ],
+      "dependencies": [],
+      "contextPatterns": ["src/components/**/*.ts"],
+      "ifFailed": "skip"
+    }
+  ]
+}
+\`\`\`
+
+## Rules
+- ALWAYS return valid JSON in a code block
+- For questions: use "type": "questions" and include 1-3 questions with options
+- For tasks: use "type": "tasks" and include the task array
+- Omit "status" field in tasks - system handles it`;
 const DISCOVERY_PROMPT = `You are helping plan a software project. Analyze the user's goal and generate clarifying questions to understand their requirements better.
 
 Your task is to:
@@ -456,252 +510,19 @@ function createFinalizeTask(existingTasks) {
     });
 }
 /**
- * Decompose a project goal into tasks using Claude Code CLI
- */
-export async function decompose(goal, projectContext = '', options = {}) {
-    const userMessage = projectContext
-        ? `Project Goal: ${goal}\n\nExisting Project Context:\n${projectContext}`
-        : `Project Goal: ${goal}`;
-    const fullPrompt = `${DECOMPOSITION_PROMPT}\n\n${userMessage}`;
-    const result = await callClaudeCode(fullPrompt, options.cwd, undefined, options.abortSignal);
-    if (!result.success) {
-        return {
-            success: false,
-            tasks: [],
-            error: result.error || 'Claude Code CLI failed',
-        };
-    }
-    const rawResponse = result.response;
-    // Parse JSON response
-    let parsedTasks;
-    try {
-        // Try to extract JSON from the response (in case there's extra text)
-        // First, try to extract from markdown code blocks
-        let jsonText = null;
-        const codeBlockMatch = rawResponse.match(/```(?:json)?\s*(\[[\s\S]*?\])\s*```/);
-        if (codeBlockMatch) {
-            jsonText = codeBlockMatch[1];
-        }
-        // Fallback to raw JSON array match
-        if (!jsonText) {
-            const jsonMatch = rawResponse.match(/\[[\s\S]*\]/);
-            if (jsonMatch) {
-                jsonText = jsonMatch[0];
-            }
-        }
-        if (!jsonText) {
-            return {
-                success: false,
-                tasks: [],
-                error: 'No JSON array found in response',
-                rawResponse,
-            };
-        }
-        parsedTasks = JSON.parse(jsonText);
-    }
-    catch (parseError) {
-        return {
-            success: false,
-            tasks: [],
-            error: `Failed to parse JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
-            rawResponse,
-        };
-    }
-    // Validate and convert to Task objects
-    if (!Array.isArray(parsedTasks)) {
-        return {
-            success: false,
-            tasks: [],
-            error: 'Response is not an array',
-            rawResponse,
-        };
-    }
-    const tasks = parsedTasks.map(pt => {
-        // Validate and normalize ifFailed value
-        const validFailureActions = ['retry', 'skip', 'stop'];
-        const ifFailed = validFailureActions.includes(pt.ifFailed)
-            ? pt.ifFailed
-            : DEFAULT_CONFIG.defaultIfFailed;
-        const description = pt.description || '';
-        // Extract image references from description
-        const imageRefs = extractImagePlaceholders(description);
-        return createTask({
-            id: pt.id || `task-${Math.random().toString(36).slice(2, 8)}`,
-            title: pt.title || 'Untitled Task',
-            description,
-            acceptanceCriteria: pt.acceptanceCriteria,
-            dependencies: pt.dependencies || [],
-            contextPatterns: pt.contextPatterns || [],
-            ifFailed,
-            timeout: pt.timeout ?? DEFAULT_CONFIG.executionTimeout,
-            maxRetries: pt.maxRetries ?? DEFAULT_CONFIG.maxRetries,
-            imageRefs: imageRefs.length > 0 ? imageRefs : undefined,
-        });
-    });
-    // Append finalize task if there are tasks to finalize
-    if (tasks.length > 0) {
-        tasks.push(createFinalizeTask(tasks));
-    }
-    return {
-        success: true,
-        tasks,
-        rawResponse,
-    };
-}
-/**
- * Validate that task dependencies form a valid DAG (no cycles)
+ * Unified planning function - handles both initial decomposition and plan updates.
+ * When currentTasks is empty/undefined, creates a fresh plan.
+ * When currentTasks is provided, merges new/modified tasks with existing ones.
  */
-export function validateTaskDependencies(tasks) {
-    const taskIds = new Set(tasks.map(t => t.id));
-    // Check all dependencies reference existing tasks
-    for (const task of tasks) {
-        for (const depId of task.dependencies) {
-            if (!taskIds.has(depId)) {
-                return {
-                    valid: false,
-                    error: `Task "${task.id}" depends on non-existent task "${depId}"`,
-                };
-            }
-        }
-    }
-    // Check for cycles using DFS
-    const visited = new Set();
-    const recursionStack = new Set();
-    function hasCycle(taskId) {
-        visited.add(taskId);
-        recursionStack.add(taskId);
-        const task = tasks.find(t => t.id === taskId);
-        if (task) {
-            for (const depId of task.dependencies) {
-                if (!visited.has(depId)) {
-                    if (hasCycle(depId)) {
-                        return true;
-                    }
-                }
-                else if (recursionStack.has(depId)) {
-                    return true;
-                }
-            }
-        }
-        recursionStack.delete(taskId);
-        return false;
-    }
-    for (const task of tasks) {
-        if (!visited.has(task.id)) {
-            if (hasCycle(task.id)) {
-                return {
-                    valid: false,
-                    error: 'Circular dependency detected in tasks',
-                };
-            }
-        }
-    }
-    return { valid: true };
-}
-/**
- * Sort tasks topologically based on dependencies
- */
-export function sortTasksByDependency(tasks) {
-    const sorted = [];
-    const visited = new Set();
-    const taskMap = new Map(tasks.map(t => [t.id, t]));
-    function visit(taskId) {
-        if (visited.has(taskId))
-            return;
-        visited.add(taskId);
-        const task = taskMap.get(taskId);
-        if (task) {
-            for (const depId of task.dependencies) {
-                visit(depId);
-            }
-            sorted.push(task);
-        }
-    }
-    for (const task of tasks) {
-        visit(task.id);
-    }
-    return sorted;
-}
-const PLAN_REFINEMENT_PROMPT = `You are a PLANNING assistant modifying a task plan. This is PLANNING MODE - you must NEVER execute actions.
-
-CRITICAL: When the user says things like "run tests", "add feature X", "fix bug Y", or ANY action-sounding request, you must:
-1. First, check if the request is clear enough to create a well-defined task
-2. If unclear or ambiguous, return CLARIFYING QUESTIONS as structured JSON
-3. If clear enough, create TASKS and return them as JSON
-4. NEVER actually execute the action yourself
-
-WHEN TO ASK QUESTIONS:
-- Request mentions a feature but lacks specifics (e.g., "add authentication" - what type?)
-- Multiple valid approaches exist (e.g., "add a button" - where? what should it do?)
-- Technical choices need to be made (e.g., "add database" - which one?)
-- Requirements are vague (e.g., "make it better" - in what way?)
-
-WHEN TO CREATE TASKS DIRECTLY:
-- Request is specific and actionable (e.g., "add a logout button to the header")
-- Simple operations (e.g., "run tests", "fix typo in README")
-- User has already provided enough context
-
-DO NOT:
-- Run any commands or tools
-- Read files or explore code
-- Execute tests or builds
-- Make any changes to the codebase
-
-Project: {PROJECT_NAME}
-
-{PENDING_SECTION}
-
-IMPORTANT: Create tasks ONLY for what the user is asking in their current message. Do not add unrelated tasks.
-
-RESPONSE FORMAT - You MUST return ONE of these two JSON formats:
-
-Option 1: Questions (when clarification needed)
-\`\`\`json
-{
-  "type": "questions",
-  "questions": [
-    {
-      "id": "question-1",
-      "question": "Where should the speed indicator be displayed?",
-      "type": "choice",
-      "options": ["Below the tap count", "In the stats section", "As a live updating label", "Other"],
-      "reason": "This determines the UI layout approach"
-    }
-  ]
-}
-\`\`\`
-
-Option 2: Tasks (when request is clear)
-\`\`\`json
-{
-  "type": "tasks",
-  "tasks": [{"id": "task-{NEXT_ID}", "title": "Add speed indicator", "description": "Display clicks per minute below the tap count"}]
-}
-\`\`\`
-
-TASK ID RULES:
-- New tasks: Use IDs starting at task-{NEXT_ID}, incrementing for each additional task
-- Modifying pending tasks: Use the EXACT existing task ID from the pending tasks list
-- NEVER reuse IDs from completed tasks
-
-OTHER RULES:
-- ALWAYS return valid JSON in a code block
-- For questions: use "type": "questions" and include 1-3 questions with options
-- For tasks: use "type": "tasks" and include the task array
-- Omit "status" field in tasks - system handles it`;
-/**
- * Refine a plan through conversation with the user
- */
-export async function refinePlan(goal, currentTasks, userMessage, conversationHistory, options = {}) {
-    // Only include non-completed tasks (pending/in-progress/failed) - these are the current plan
+export async function planTasks(options) {
+    const { userMessage, currentTasks = [], conversationHistory = [], cwd, abortSignal, onOutput, } = options;
+    // Build dynamic sections for the prompt
     const pendingTasks = currentTasks.filter(t => t.status === 'pending' || t.status === 'in_progress' || t.status === 'failed');
-    // Calculate next task ID for the prompt
     const maxTaskNum = currentTasks.reduce((max, t) => {
         const match = t.id.match(/task-(\d+)/);
         return match ? Math.max(max, parseInt(match[1], 10)) : max;
     }, 0);
-    const nextId = maxTaskNum + 1;
-    // Format pending tasks (they may need modification)
+    const nextId = maxTaskNum > 0 ? maxTaskNum + 1 : 1;
     const pendingSection = pendingTasks.length > 0
         ? `Current plan (pending tasks):\n\`\`\`json\n${JSON.stringify(pendingTasks.map(t => ({
             id: t.id,
@@ -712,36 +533,34 @@ export async function refinePlan(goal, currentTasks, userMessage, conversationHi
             status: t.status,
         })), null, 2)}\n\`\`\``
         : 'No pending tasks - ready for new work.';
-    // Extract project name from cwd or use generic fallback
-    const projectName = options.cwd ? basename(options.cwd) : 'project';
-    const systemPrompt = PLAN_REFINEMENT_PROMPT
+    const projectName = cwd ? basename(cwd) : 'project';
+    const systemPrompt = PLANNING_PROMPT
         .replace('{PROJECT_NAME}', projectName)
         .replace('{PENDING_SECTION}', pendingSection)
         .replace(/{NEXT_ID}/g, String(nextId));
-    // Build conversation context for CLI (only last few exchanges to save tokens)
-    const recentHistory = conversationHistory.slice(-4); // Keep last 2 exchanges
+    // Build conversation context (only last few exchanges to save tokens)
+    const recentHistory = conversationHistory.slice(-4);
     const historyContext = recentHistory.length > 0
         ? '\n\nRecent conversation:\n' + recentHistory.map(m => `${m.role}: ${m.content}`).join('\n')
         : '';
     const fullPrompt = `${systemPrompt}${historyContext}\n\nUser: ${userMessage}`;
-    const result = await callClaudeCode(fullPrompt, options.cwd, options.onOutput, options.abortSignal);
+    const result = await callClaudeCode(fullPrompt, cwd, onOutput, abortSignal);
     if (!result.success) {
         return {
             success: false,
-            response: '',
+            tasks: [],
             error: result.error || 'Claude Code CLI failed',
             aborted: result.aborted,
         };
     }
     const responseText = result.response;
-    // Check if the response contains JSON (either object or array)
+    // Try to parse structured response (object with type field)
     const objectMatch = responseText.match(/```(?:json)?\s*(\{[\s\S]*?\})\s*```/);
     const arrayMatch = responseText.match(/```(?:json)?\s*(\[[\s\S]*?\])\s*```/);
-    // Try to parse structured response first (object with type field)
     if (objectMatch) {
         try {
             const parsed = JSON.parse(objectMatch[1]);
-            // Check if this is a questions response
+            // Questions response
             if (parsed.type === 'questions' && Array.isArray(parsed.questions)) {
                 const questions = parsed.questions.map((q, index) => ({
                     id: q.id || `question-${index + 1}`,
@@ -753,15 +572,15 @@ export async function refinePlan(goal, currentTasks, userMessage, conversationHi
                 }));
                 return {
                     success: true,
+                    tasks: [],
                     response: responseText,
                     questions,
+                    rawResponse: responseText,
                 };
             }
-            // Check if this is a tasks response
+            // Tasks response
             if (parsed.type === 'tasks' && Array.isArray(parsed.tasks)) {
-                // Process the tasks array
-                const parsedTasks = parsed.tasks;
-                return processTasksResponse(parsedTasks, currentTasks, responseText);
+                return processAndMergeTasks(parsed.tasks, currentTasks, responseText);
             }
         }
         catch {
@@ -772,44 +591,64 @@ export async function refinePlan(goal, currentTasks, userMessage, conversationHi
     if (arrayMatch) {
         try {
             const parsedTasks = JSON.parse(arrayMatch[1]);
-            return processTasksResponse(parsedTasks, currentTasks, responseText);
+            return processAndMergeTasks(parsedTasks, currentTasks, responseText);
         }
         catch {
-            // JSON parsing failed, just return the response text
+            // JSON parsing failed
         }
     }
+    // Fallback: try raw JSON array (no code block)
+    if (!objectMatch && !arrayMatch) {
+        try {
+            const jsonMatch = responseText.match(/\[[\s\S]*\]/);
+            if (jsonMatch) {
+                const parsedTasks = JSON.parse(jsonMatch[0]);
+                return processAndMergeTasks(parsedTasks, currentTasks, responseText);
+            }
+        }
+        catch {
+            // Not valid JSON
+        }
+    }
+    // No tasks or questions found - return text-only response
     return {
         success: true,
+        tasks: [],
         response: responseText,
+        rawResponse: responseText,
     };
 }
 /**
- * Helper function to process task array from refinePlan response
+ * Process parsed tasks and merge with existing tasks if applicable.
+ * Handles both initial planning (no existing tasks) and plan updates (with existing tasks).
  */
-function processTasksResponse(parsedTasks, currentTasks, responseText) {
-    // Create a map of existing tasks for merging
+function processAndMergeTasks(parsedTasks, currentTasks, responseText) {
+    if (!Array.isArray(parsedTasks)) {
+        return {
+            success: false,
+            tasks: [],
+            error: 'Response is not an array',
+            rawResponse: responseText,
+        };
+    }
     const existingTaskMap = new Map(currentTasks.map(t => [t.id, t]));
     const modifiedTaskIds = new Set();
-    // Process returned tasks (new or modified only)
     const processedTasks = parsedTasks.map((pt) => {
         const taskId = pt.id || `task-${Math.random().toString(36).slice(2, 8)}`;
         modifiedTaskIds.add(taskId);
         const existingTask = existingTaskMap.get(taskId);
-        // Validate and normalize ifFailed value
         const validFailureActions = ['retry', 'skip', 'stop'];
         const ifFailed = validFailureActions.includes(pt.ifFailed)
             ? pt.ifFailed
             : (existingTask?.ifFailed ?? DEFAULT_CONFIG.defaultIfFailed);
         const description = pt.description || existingTask?.description || '';
-        // Extract image references from description
         const imageRefs = extractImagePlaceholders(description);
-        // If task already exists, update it and reset to pending for re-execution
+        // Update existing task
         if (existingTask) {
-            const updatedTask = {
+            return {
                 ...existingTask,
                 title: pt.title || existingTask.title,
                 description,
-                // Use ?? instead of || so empty arrays are preserved (not treated as falsy)
                 acceptanceCriteria: pt.acceptanceCriteria ?? existingTask.acceptanceCriteria,
                 dependencies: pt.dependencies ?? existingTask.dependencies,
                 contextPatterns: pt.contextPatterns ?? existingTask.contextPatterns,
@@ -818,16 +657,14 @@ function processTasksResponse(parsedTasks, currentTasks, responseText) {
                 maxRetries: pt.maxRetries ?? existingTask.maxRetries,
                 imageRefs: imageRefs.length > 0 ? imageRefs : existingTask.imageRefs,
                 updatedAt: new Date().toISOString(),
-                // Always reset to pending - returned tasks are treated as new work to execute
                 status: 'pending',
                 retryCount: 0,
                 error: undefined,
                 failureType: undefined,
                 durationMs: undefined,
             };
-            return updatedTask;
         }
-        // New task - create with default status
+        // New task
         return createTask({
             id: taskId,
             title: pt.title || 'Untitled Task',
@@ -841,34 +678,106 @@ function processTasksResponse(parsedTasks, currentTasks, responseText) {
             imageRefs: imageRefs.length > 0 ? imageRefs : undefined,
         });
     });
-    // Merge: keep all existing tasks that weren't modified, then add/update modified ones
+    // Merge: keep all existing tasks that weren't modified, then add modified/new ones
     const unchangedTasks = currentTasks.filter(t => !modifiedTaskIds.has(t.id) && t.id !== FINALIZE_TASK_ID);
     const tasks = [...unchangedTasks, ...processedTasks];
-    // Handle finalize task: ensure it exists and has correct dependencies
+    // Handle finalize task
     const nonFinalizeTasks = tasks.filter(t => t.id !== FINALIZE_TASK_ID);
     const existingFinalizeTask = currentTasks.find(t => t.id === FINALIZE_TASK_ID);
     if (nonFinalizeTasks.length > 0) {
         if (existingFinalizeTask) {
-            // Update finalize task dependencies to include all other tasks
-            const updatedFinalizeTask = {
+            tasks.push({
                 ...existingFinalizeTask,
                 dependencies: nonFinalizeTasks.map(t => t.id),
                 status: 'pending',
                 updatedAt: new Date().toISOString(),
-            };
-            tasks.push(updatedFinalizeTask);
+            });
         }
         else {
-            // Re-add finalize task if it was removed
             tasks.push(createFinalizeTask(nonFinalizeTasks));
         }
     }
     return {
         success: true,
+        tasks,
         response: responseText,
-        updatedTasks: tasks,
+        rawResponse: responseText,
     };
 }
+/**
+ * Validate that task dependencies form a valid DAG (no cycles)
+ */
+export function validateTaskDependencies(tasks) {
+    const taskIds = new Set(tasks.map(t => t.id));
+    // Check all dependencies reference existing tasks
+    for (const task of tasks) {
+        for (const depId of task.dependencies) {
+            if (!taskIds.has(depId)) {
+                return {
+                    valid: false,
+                    error: `Task "${task.id}" depends on non-existent task "${depId}"`,
+                };
+            }
+        }
+    }
+    // Check for cycles using DFS
+    const visited = new Set();
+    const recursionStack = new Set();
+    function hasCycle(taskId) {
+        visited.add(taskId);
+        recursionStack.add(taskId);
+        const task = tasks.find(t => t.id === taskId);
+        if (task) {
+            for (const depId of task.dependencies) {
+                if (!visited.has(depId)) {
+                    if (hasCycle(depId)) {
+                        return true;
+                    }
+                }
+                else if (recursionStack.has(depId)) {
+                    return true;
+                }
+            }
+        }
+        recursionStack.delete(taskId);
+        return false;
+    }
+    for (const task of tasks) {
+        if (!visited.has(task.id)) {
+            if (hasCycle(task.id)) {
+                return {
+                    valid: false,
+                    error: 'Circular dependency detected in tasks',
+                };
+            }
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Sort tasks topologically based on dependencies
+ */
+export function sortTasksByDependency(tasks) {
+    const sorted = [];
+    const visited = new Set();
+    const taskMap = new Map(tasks.map(t => [t.id, t]));
+    function visit(taskId) {
+        if (visited.has(taskId))
+            return;
+        visited.add(taskId);
+        const task = taskMap.get(taskId);
+        if (task) {
+            for (const depId of task.dependencies) {
+                visit(depId);
+            }
+            sorted.push(task);
+        }
+    }
+    for (const task of tasks) {
+        visit(task.id);
+    }
+    return sorted;
+}
 const README_GENERATION_PROMPT = `You are a technical documentation assistant. Generate a README.md file for a new project.
 
 The README should include: