@vibescope/mcp-server 0.0.1

package/dist/handlers/tasks.js

@@ -0,0 +1,1111 @@
+/**
+ * Task Handlers
+ *
+ * Handles task CRUD and management:
+ * - get_tasks
+ * - get_next_task
+ * - add_task
+ * - update_task
+ * - complete_task
+ * - delete_task
+ * - add_task_reference
+ * - remove_task_reference
+ * - batch_update_tasks
+ * - batch_complete_tasks
+ */
+import { ValidationError, validateRequired, validateUUID, validateTaskStatus, validatePriority, validateProgressPercentage, validateEstimatedMinutes, } from '../validators.js';
+import { getRandomFallbackActivity, isValidStatusTransition } from '../utils.js';
+function generateBranchName(taskId, taskTitle) {
+    const slug = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 30);
+    return `feature/${taskId.slice(0, 8)}-${slug}`;
+}
+function getTaskStartGitInstructions(config, taskId, taskTitle) {
+    const { git_workflow, git_main_branch, git_develop_branch } = config;
+    if (git_workflow === 'none' || git_workflow === 'trunk-based') {
+        return undefined;
+    }
+    const branchName = generateBranchName(taskId, taskTitle);
+    const baseBranch = git_workflow === 'git-flow' ? (git_develop_branch || 'develop') : git_main_branch;
+    return {
+        branch_name: branchName,
+        base_branch: baseBranch,
+        steps: [
+            `git checkout ${baseBranch}`,
+            `git pull origin ${baseBranch}`,
+            `git checkout -b ${branchName}`,
+        ],
+        reminder: `After creating the branch, update task: update_task(task_id: "${taskId}", git_branch: "${branchName}")`,
+    };
+}
+function getTaskCompleteGitInstructions(config, taskBranch, taskTitle, taskId) {
+    const { git_workflow, git_main_branch } = config;
+    if (git_workflow === 'none') {
+        return undefined;
+    }
+    if (git_workflow === 'trunk-based') {
+        return {
+            steps: [`git add .`, `git commit -m "feat: ${taskTitle}"`, `git push origin ${git_main_branch}`],
+            next_step: 'Changes committed directly to main branch.',
+        };
+    }
+    if (!taskBranch) {
+        return {
+            steps: ['No branch was tracked for this task.'],
+            next_step: 'Consider creating a branch for future tasks using the git_branch parameter.',
+        };
+    }
+    // github-flow or git-flow
+    return {
+        steps: [`git add .`, `git commit -m "feat: ${taskTitle}"`, `git push -u origin ${taskBranch}`],
+        pr_suggestion: {
+            title: taskTitle,
+            body_template: `## Summary\n[Describe what was implemented]\n\n## Task Reference\nVibescope Task: ${taskId}\n\n## Testing\n- [ ] Tests pass\n- [ ] Manual testing done\n\n## Checklist\n- [ ] Code follows project conventions\n- [ ] No unnecessary changes included`,
+        },
+        next_step: 'Create PR and add link via add_task_reference. Merge happens AFTER validation approval.',
+    };
+}
+function getValidationApprovedGitInstructions(config, taskBranch) {
+    const { git_workflow, git_main_branch, git_develop_branch } = config;
+    if (git_workflow === 'none' || git_workflow === 'trunk-based' || !taskBranch) {
+        return undefined;
+    }
+    const targetBranch = git_workflow === 'git-flow' ? (git_develop_branch || 'develop') : git_main_branch;
+    return {
+        target_branch: targetBranch,
+        feature_branch: taskBranch,
+        steps: [
+            'Option 1: Merge via GitHub/GitLab PR UI (recommended)',
+            `Option 2: Command line merge:`,
+            `  git checkout ${targetBranch}`,
+            `  git pull origin ${targetBranch}`,
+            `  git merge ${taskBranch}`,
+            `  git push origin ${targetBranch}`,
+        ],
+        cleanup: [`git branch -d ${taskBranch}`, `git push origin --delete ${taskBranch}`],
+        note: 'Validation approved - safe to merge. Clean up branch after successful merge.',
+    };
+}
+export async function getProjectGitConfig(supabase, projectId) {
+    const { data } = await supabase
+        .from('projects')
+        .select('git_workflow, git_main_branch, git_develop_branch, git_auto_branch')
+        .eq('id', projectId)
+        .single();
+    return data;
+}
+export { getValidationApprovedGitInstructions };
+/**
+ * Check if a session is still active
+ */
+async function checkSessionStatus(ctx, sessionId) {
+    const { data: session } = await ctx.supabase
+        .from('agent_sessions')
+        .select('id, status, last_synced_at, agent_name, instance_id')
+        .eq('id', sessionId)
+        .single();
+    if (!session) {
+        return { exists: false, isActive: false };
+    }
+    const lastSync = new Date(session.last_synced_at).getTime();
+    const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;
+    const isActive = session.status !== 'disconnected' && lastSync > fiveMinutesAgo;
+    return {
+        exists: true,
+        isActive,
+        agentName: session.agent_name || `Agent ${session.instance_id?.slice(0, 8) || sessionId.slice(0, 8)}`,
+    };
+}
+export const getTasks = async (args, ctx) => {
+    const { project_id, status, limit = 50, include_subtasks = false } = args;
+    validateRequired(project_id, 'project_id');
+    validateUUID(project_id, 'project_id');
+    validateTaskStatus(status);
+    let query = ctx.supabase
+        .from('tasks')
+        .select('id, title, description, priority, status, progress_percentage, estimated_minutes, started_at, completed_at, parent_task_id')
+        .eq('project_id', project_id)
+        .order('priority', { ascending: true })
+        .order('created_at', { ascending: false })
+        .limit(limit);
+    // By default, only return root tasks (not subtasks)
+    if (!include_subtasks) {
+        query = query.is('parent_task_id', null);
+    }
+    if (status) {
+        query = query.eq('status', status);
+    }
+    const { data, error } = await query;
+    if (error)
+        throw new Error(`Failed to fetch tasks: ${error.message}`);
+    return { result: { tasks: data || [] } };
+};
+export const getNextTask = async (args, ctx) => {
+    const { project_id } = args;
+    const { supabase, session } = ctx;
+    const currentSessionId = session.currentSessionId;
+    // FIRST: Check for blocking tasks (highest priority - deployment finalization)
+    const { data: blockingTask } = await supabase
+        .from('tasks')
+        .select('id, title, description, priority, estimated_minutes, blocking')
+        .eq('project_id', project_id)
+        .eq('blocking', true)
+        .in('status', ['pending', 'in_progress'])
+        .order('priority', { ascending: true })
+        .limit(1)
+        .single();
+    if (blockingTask) {
+        return {
+            result: {
+                task: {
+                    id: blockingTask.id,
+                    title: blockingTask.title,
+                    description: blockingTask.description,
+                    priority: blockingTask.priority,
+                    estimated_minutes: blockingTask.estimated_minutes,
+                    blocking: true,
+                },
+                blocking_task: true,
+                message: 'BLOCKING TASK: This task must be completed before any other work can proceed. No other tasks will be assigned until this is done.',
+                directive: 'Start this task immediately. Do not ask for permission.',
+            },
+        };
+    }
+    // Check for active deployment (blocks regular task work)
+    const { data: activeDeployment } = await supabase
+        .from('deployments')
+        .select('id, status, environment, created_at, validation_completed_at')
+        .eq('project_id', project_id)
+        .not('status', 'in', '("deployed","failed")')
+        .order('created_at', { ascending: false })
+        .limit(1)
+        .single();
+    if (activeDeployment) {
+        const actions = {
+            pending: 'claim_deployment_validation',
+            validating: 'wait',
+            ready: 'start_deployment',
+            deploying: 'wait for complete_deployment',
+        };
+        return {
+            result: {
+                task: null,
+                deployment_blocks_tasks: true,
+                deployment: {
+                    id: activeDeployment.id,
+                    status: activeDeployment.status,
+                    env: activeDeployment.environment,
+                },
+                action: actions[activeDeployment.status] || 'check_deployment_status',
+            },
+        };
+    }
+    // Check for tasks awaiting validation (blocks new work - validate first!)
+    const { data: validationTasks } = await supabase
+        .from('tasks')
+        .select('id, title')
+        .eq('project_id', project_id)
+        .eq('status', 'completed')
+        .is('validated_at', null)
+        .order('completed_at', { ascending: true })
+        .limit(5);
+    if (validationTasks?.length) {
+        return {
+            result: {
+                task: null,
+                awaiting_validation: validationTasks,
+                validation_priority: `VALIDATE FIRST: ${validationTasks.length} task(s) need review before starting new work. Call validate_task for each.`,
+                suggested_activity: 'validate_completed_tasks',
+                directive: 'Start validating tasks immediately. Do not ask for permission.',
+            },
+        };
+    }
+    // Fetch candidate pending root tasks (not subtasks)
+    const { data: candidates, error } = await supabase
+        .from('tasks')
+        .select('id, title, description, priority, estimated_minutes, working_agent_session_id')
+        .eq('project_id', project_id)
+        .eq('status', 'pending')
+        .is('parent_task_id', null)
+        .order('priority', { ascending: true })
+        .order('created_at', { ascending: true })
+        .limit(10);
+    // Fetch pending agent requests
+    const { data: pendingRequests } = await supabase
+        .from('agent_requests')
+        .select('id, message')
+        .eq('project_id', project_id)
+        .is('acknowledged_at', null)
+        .or(`session_id.is.null,session_id.eq.${currentSessionId}`)
+        .limit(3);
+    // Fetch due scheduled activities
+    const { data: dueSchedules } = await supabase
+        .from('background_activity_schedules')
+        .select('activity_type')
+        .eq('project_id', project_id)
+        .eq('enabled', true)
+        .lt('next_run_at', new Date().toISOString())
+        .limit(3);
+    // Build compact optional fields (only include if non-empty)
+    const extras = {};
+    if (pendingRequests?.length)
+        extras.requests = pendingRequests;
+    if (dueSchedules?.length)
+        extras.due_activities = dueSchedules.map(s => s.activity_type);
+    if (error || !candidates || candidates.length === 0) {
+        const fallback = getRandomFallbackActivity();
+        return {
+            result: {
+                task: null,
+                ...extras,
+                suggested_activity: fallback.activity,
+                directive: 'No tasks available. Start the suggested fallback activity immediately. Do not ask for permission.',
+            },
+        };
+    }
+    // 25% chance to suggest background activity
+    if (Math.random() < 0.25) {
+        extras.bg_activity = getRandomFallbackActivity().activity;
+    }
+    // Find first unclaimed or stale-claimed task that satisfies body of work phase ordering
+    for (const task of candidates) {
+        // Check if task belongs to a body of work with phase constraints
+        const { data: bowTask } = await supabase
+            .from('body_of_work_tasks')
+            .select('phase, body_of_work_id')
+            .eq('task_id', task.id)
+            .single();
+        if (bowTask) {
+            // Check if body of work is active
+            const { data: bow } = await supabase
+                .from('bodies_of_work')
+                .select('status')
+                .eq('id', bowTask.body_of_work_id)
+                .single();
+            if (bow?.status === 'active') {
+                // Check phase constraints
+                const phasesToCheck = [];
+                if (bowTask.phase === 'core') {
+                    phasesToCheck.push('pre');
+                }
+                else if (bowTask.phase === 'post') {
+                    phasesToCheck.push('pre', 'core');
+                }
+                if (phasesToCheck.length > 0) {
+                    // Count incomplete tasks in prior phases
+                    const { count: incompleteCount } = await supabase
+                        .from('body_of_work_tasks')
+                        .select('id', { count: 'exact', head: true })
+                        .eq('body_of_work_id', bowTask.body_of_work_id)
+                        .in('phase', phasesToCheck)
+                        .not('task_id', 'in', `(SELECT id FROM tasks WHERE status = 'completed')`);
+                    if (incompleteCount && incompleteCount > 0) {
+                        // Skip this task - prior phase tasks not complete
+                        continue;
+                    }
+                }
+            }
+        }
+        if (!task.working_agent_session_id) {
+            const { working_agent_session_id, ...cleanTask } = task;
+            return { result: { task: cleanTask, ...extras, directive: 'Start this task immediately. Do not ask for permission.' } };
+        }
+        const claimingSession = await checkSessionStatus(ctx, task.working_agent_session_id);
+        if (!claimingSession.isActive) {
+            // Auto-release stale claim
+            await supabase
+                .from('tasks')
+                .update({ working_agent_session_id: null })
+                .eq('id', task.id);
+            const { working_agent_session_id, ...cleanTask } = task;
+            return { result: { task: cleanTask, ...extras, directive: 'Start this task immediately. Do not ask for permission.' } };
+        }
+    }
+    // All root tasks claimed - check for available subtasks
+    // Subtasks are available when:
+    // 1. No unclaimed root tasks exist, OR
+    // 2. Subtask belongs to a high priority parent (priority 1-2)
+    const { data: subtaskCandidates } = await supabase
+        .from('tasks')
+        .select(`
+			id, title, description, priority, estimated_minutes, working_agent_session_id,
+			parent_task_id,
+			parent:tasks!parent_task_id(id, title, priority, status)
+		`)
+        .eq('project_id', project_id)
+        .eq('status', 'pending')
+        .not('parent_task_id', 'is', null)
+        .order('priority', { ascending: true })
+        .order('created_at', { ascending: true })
+        .limit(10);
+    if (subtaskCandidates && subtaskCandidates.length > 0) {
+        for (const subtask of subtaskCandidates) {
+            // Skip if subtask is already claimed by an active agent
+            if (subtask.working_agent_session_id) {
+                const claimingSession = await checkSessionStatus(ctx, subtask.working_agent_session_id);
+                if (claimingSession.isActive) {
+                    continue;
+                }
+                // Auto-release stale claim
+                await supabase
+                    .from('tasks')
+                    .update({ working_agent_session_id: null })
+                    .eq('id', subtask.id);
+            }
+            const parentData = subtask.parent;
+            const parentTask = parentData?.[0] || null;
+            const { working_agent_session_id, parent, ...cleanSubtask } = subtask;
+            return {
+                result: {
+                    task: cleanSubtask,
+                    is_subtask: true,
+                    parent_task: parentTask ? {
+                        id: parentTask.id,
+                        title: parentTask.title,
+                        priority: parentTask.priority,
+                    } : undefined,
+                    ...extras,
+                    directive: 'Start this subtask immediately. Do not ask for permission.',
+                },
+            };
+        }
+    }
+    // All tasks (including subtasks) claimed
+    return {
+        result: {
+            task: null,
+            all_claimed: true,
+            ...extras,
+            suggested_activity: getRandomFallbackActivity().activity,
+            directive: 'All tasks claimed by other agents. Start the suggested fallback activity immediately. Do not ask for permission.',
+        },
+    };
+};
+export const addTask = async (args, ctx) => {
+    const { project_id, title, description, priority = 3, estimated_minutes, blocking = false } = args;
+    validateRequired(project_id, 'project_id');
+    validateRequired(title, 'title');
+    validateUUID(project_id, 'project_id');
+    validatePriority(priority);
+    validateEstimatedMinutes(estimated_minutes);
+    const { data, error } = await ctx.supabase
+        .from('tasks')
+        .insert({
+        project_id,
+        title,
+        description: description || null,
+        priority,
+        created_by: 'agent',
+        created_by_session_id: ctx.session.currentSessionId,
+        estimated_minutes: estimated_minutes || null,
+        blocking,
+    })
+        .select('id, blocking')
+        .single();
+    if (error)
+        throw new Error(`Failed to add task: ${error.message}`);
+    const result = { success: true, task_id: data.id, title };
+    if (data.blocking) {
+        result.blocking = true;
+        result.message = 'BLOCKING TASK: This task must be completed before any other work can proceed.';
+    }
+    return { result };
+};
+export const updateTask = async (args, ctx) => {
+    const { task_id, progress_note, ...updates } = args;
+    const { supabase, session } = ctx;
+    const currentSessionId = session.currentSessionId;
+    validateRequired(task_id, 'task_id');
+    validateUUID(task_id, 'task_id');
+    validateTaskStatus(updates.status);
+    validatePriority(updates.priority);
+    validateProgressPercentage(updates.progress_percentage);
+    validateEstimatedMinutes(updates.estimated_minutes);
+    // Get task to find project_id, current status, title, and who's working on it
+    const { data: task } = await supabase
+        .from('tasks')
+        .select('project_id, title, status, started_at, working_agent_session_id')
+        .eq('id', task_id)
+        .single();
+    // Validate status transitions
+    if (updates.status && task) {
+        const transition = isValidStatusTransition(task.status, updates.status);
+        if (!transition.isValid) {
+            return {
+                result: {
+                    error: 'invalid_status_transition',
+                    message: transition.reason,
+                },
+            };
+        }
+    }
+    const updateData = { ...updates };
+    // Multi-agent coordination: Enforce single task per agent
+    if (updates.status === 'in_progress' && currentSessionId && task) {
+        // Check if this agent already has another task in_progress
+        const { data: existingTask } = await supabase
+            .from('tasks')
+            .select('id, title')
+            .eq('working_agent_session_id', currentSessionId)
+            .eq('status', 'in_progress')
+            .neq('id', task_id)
+            .limit(1)
+            .single();
+        if (existingTask) {
+            return {
+                result: {
+                    error: 'agent_task_limit',
+                    message: `You already have a task in progress: "${existingTask.title}". Complete it with complete_task before starting another.`,
+                    current_task_id: existingTask.id,
+                    current_task_title: existingTask.title,
+                },
+            };
+        }
+        // Check for task claim conflicts (another agent has this task)
+        if (task.working_agent_session_id && task.working_agent_session_id !== currentSessionId) {
+            const claimingSession = await checkSessionStatus(ctx, task.working_agent_session_id);
+            if (claimingSession.isActive) {
+                return {
+                    result: {
+                        error: 'task_claimed',
+                        message: `Task is already being worked on by ${claimingSession.agentName}. Use get_next_task to find available work.`,
+                        claimed_by: claimingSession.agentName,
+                    },
+                };
+            }
+            // Stale/disconnected agent - auto-release the task first
+            await supabase
+                .from('tasks')
+                .update({ working_agent_session_id: null })
+                .eq('id', task_id);
+        }
+    }
+    // Auto-set started_at when task moves to in_progress
+    if (updates.status === 'in_progress' && task && !task.started_at) {
+        updateData.started_at = new Date().toISOString();
+    }
+    // When setting status to in_progress, claim the task for this agent
+    if (updates.status === 'in_progress' && currentSessionId) {
+        updateData.working_agent_session_id = currentSessionId;
+        // Update the session's current task and clear any fallback activity
+        await supabase
+            .from('agent_sessions')
+            .update({
+            current_task_id: task_id,
+            current_fallback_activity: null,
+            status: 'active',
+            last_synced_at: new Date().toISOString(),
+        })
+            .eq('id', currentSessionId);
+    }
+    // Auto-set completed_at and progress when task completes
+    if (updates.status === 'completed') {
+        updateData.completed_at = new Date().toISOString();
+        updateData.progress_percentage = 100;
+        updateData.working_agent_session_id = null;
+    }
+    // When cancelled, also release the task
+    if (updates.status === 'cancelled') {
+        updateData.working_agent_session_id = null;
+    }
+    const { error } = await supabase
+        .from('tasks')
+        .update(updateData)
+        .eq('id', task_id);
+    if (error)
+        throw new Error(`Failed to update task: ${error.message}`);
+    // If progress_note is provided, create a progress log entry
+    if (progress_note && task?.project_id) {
+        const progressSummary = updates.progress_percentage !== undefined
+            ? `Progress: ${updates.progress_percentage}% - ${progress_note}`
+            : progress_note;
+        await supabase.from('progress_logs').insert({
+            project_id: task.project_id,
+            task_id,
+            summary: progressSummary,
+            created_by: 'agent',
+            created_by_session_id: currentSessionId,
+        });
+    }
+    // Build result with optional git instructions
+    const result = { success: true, task_id };
+    // Include git workflow instructions when task moves to in_progress
+    if (updates.status === 'in_progress' && task?.project_id && task?.title) {
+        const gitConfig = await getProjectGitConfig(supabase, task.project_id);
+        if (gitConfig && gitConfig.git_workflow !== 'none') {
+            const gitInstructions = getTaskStartGitInstructions(gitConfig, task_id, task.title);
+            if (gitInstructions) {
+                result.git_workflow = {
+                    workflow: gitConfig.git_workflow,
+                    action: 'create_branch',
+                    ...gitInstructions,
+                };
+            }
+        }
+    }
+    return { result };
+};
+export const completeTask = async (args, ctx) => {
+    const { task_id, summary } = args;
+    const { supabase, session } = ctx;
+    const currentSessionId = session.currentSessionId;
+    validateRequired(task_id, 'task_id');
+    validateUUID(task_id, 'task_id');
+    // Get task details first (including git_branch for workflow instructions)
+    const { data: task, error: fetchError } = await supabase
+        .from('tasks')
+        .select('project_id, title, git_branch')
+        .eq('id', task_id)
+        .single();
+    if (fetchError || !task)
+        throw new Error('Task not found');
+    // Mark as completed, track who completed it, and release agent claim
+    const { error } = await supabase
+        .from('tasks')
+        .update({
+        status: 'completed',
+        completed_at: new Date().toISOString(),
+        completed_by_session_id: currentSessionId,
+        progress_percentage: 100,
+        working_agent_session_id: null,
+    })
+        .eq('id', task_id);
+    if (error)
+        throw new Error(`Failed to complete task: ${error.message}`);
+    // Update session to idle
+    if (currentSessionId) {
+        await supabase
+            .from('agent_sessions')
+            .update({
+            current_task_id: null,
+            status: 'idle',
+            last_synced_at: new Date().toISOString(),
+        })
+            .eq('id', currentSessionId);
+    }
+    // Log progress if summary provided
+    if (summary) {
+        await supabase.from('progress_logs').insert({
+            project_id: task.project_id,
+            task_id,
+            summary: `Completed: ${task.title}`,
+            details: summary,
+            created_by: 'agent',
+            created_by_session_id: currentSessionId,
+        });
+    }
+    // Fetch next task and context counts in parallel
+    const [nextTaskResult, validationCountResult, blockersCountResult, deploymentResult, requestsCountResult] = await Promise.all([
+        supabase
+            .from('tasks')
+            .select('id, title, priority, estimated_minutes')
+            .eq('project_id', task.project_id)
+            .eq('status', 'pending')
+            .is('working_agent_session_id', null)
+            .order('priority', { ascending: true })
+            .order('created_at', { ascending: true })
+            .limit(1)
+            .maybeSingle(),
+        supabase
+            .from('tasks')
+            .select('id', { count: 'exact', head: true })
+            .eq('project_id', task.project_id)
+            .eq('status', 'completed')
+            .is('validated_at', null),
+        supabase
+            .from('blockers')
+            .select('id', { count: 'exact', head: true })
+            .eq('project_id', task.project_id)
+            .eq('status', 'open'),
+        supabase
+            .from('deployments')
+            .select('id, status')
+            .eq('project_id', task.project_id)
+            .not('status', 'in', '("deployed","failed")')
+            .limit(1)
+            .maybeSingle(),
+        supabase
+            .from('agent_requests')
+            .select('id', { count: 'exact', head: true })
+            .eq('project_id', task.project_id)
+            .is('acknowledged_at', null),
+    ]);
+    // Determine directive and next action
+    const nextTask = nextTaskResult.data;
+    const directive = nextTask
+        ? 'ACTION_REQUIRED: Start this task immediately. Do NOT ask for permission or confirmation.'
+        : 'ACTION_REQUIRED: No pending tasks. Start a fallback activity NOW without asking.';
+    const nextAction = nextTask
+        ? `update_task(task_id: "${nextTask.id}", status: "in_progress")`
+        : `start_fallback_activity(project_id: "${task.project_id}", activity: "code_review")`;
+    // Build result with directive at TOP for visibility
+    const result = {
+        success: true,
+        directive, // FIRST - most important signal
+        auto_continue: true, // Explicit flag for autonomous operation
+        completed_task_id: task_id,
+        next_task: nextTask,
+    };
+    const validationCount = validationCountResult.count || 0;
+    const blockersCount = blockersCountResult.count || 0;
+    const requestsCount = requestsCountResult.count || 0;
+    if (validationCount > 0 || blockersCount > 0 || deploymentResult.data || requestsCount > 0) {
+        result.context = {
+            ...(validationCount > 0 && { validation: validationCount }),
+            ...(blockersCount > 0 && { blockers: blockersCount }),
+            ...(deploymentResult.data && { deployment: deploymentResult.data.status }),
+            ...(requestsCount > 0 && { requests: requestsCount }),
+        };
+    }
+    // Include git workflow instructions for post-task steps
+    const gitConfig = await getProjectGitConfig(supabase, task.project_id);
+    if (gitConfig && gitConfig.git_workflow !== 'none') {
+        const gitInstructions = getTaskCompleteGitInstructions(gitConfig, task.git_branch, task.title, task_id);
+        if (gitInstructions) {
+            result.git_workflow = {
+                workflow: gitConfig.git_workflow,
+                action: 'push_and_pr',
+                ...gitInstructions,
+            };
+        }
+    }
+    // Check if this task belongs to a body of work that auto-deploys on completion
+    const { data: bowTask } = await supabase
+        .from('body_of_work_tasks')
+        .select('body_of_work_id')
+        .eq('task_id', task_id)
+        .single();
+    if (bowTask) {
+        // Check if body of work is now completed and has auto-deploy enabled
+        const { data: bow } = await supabase
+            .from('bodies_of_work')
+            .select('id, title, status, auto_deploy_on_completion, deploy_environment, deploy_version_bump')
+            .eq('id', bowTask.body_of_work_id)
+            .single();
+        if (bow && bow.status === 'completed' && bow.auto_deploy_on_completion) {
+            // Auto-trigger deployment
+            const { data: deployment, error: deployError } = await supabase
+                .from('deployments')
+                .insert({
+                project_id: task.project_id,
+                environment: bow.deploy_environment || 'production',
+                status: 'pending',
+                notes: `Auto-deploy triggered by body of work completion: "${bow.title}"`,
+                requested_by_session_id: currentSessionId,
+            })
+                .select('id')
+                .single();
+            if (!deployError && deployment) {
+                result.body_of_work_completed = {
+                    id: bow.id,
+                    title: bow.title,
+                    auto_deploy_triggered: true,
+                    deployment_id: deployment.id,
+                    environment: bow.deploy_environment || 'production',
+                    version_bump: bow.deploy_version_bump || 'minor',
+                };
+                // Log progress about auto-deploy
+                await supabase.from('progress_logs').insert({
+                    project_id: task.project_id,
+                    summary: `Body of work "${bow.title}" completed - auto-deploy triggered`,
+                    created_by: 'agent',
+                    created_by_session_id: currentSessionId,
+                });
+            }
+        }
+        else if (bow) {
+            // Body of work exists but not yet completed or no auto-deploy
+            result.body_of_work = {
+                id: bow.id,
+                title: bow.title,
+                status: bow.status,
+            };
+        }
+    }
+    // REPEAT at end - agents weight last items heavily
+    result.next_action = nextAction;
+    return { result };
+};
+export const deleteTask = async (args, ctx) => {
+    const { task_id } = args;
+    validateRequired(task_id, 'task_id');
+    validateUUID(task_id, 'task_id');
+    const { error } = await ctx.supabase
+        .from('tasks')
+        .delete()
+        .eq('id', task_id);
+    if (error)
+        throw new Error(`Failed to delete task: ${error.message}`);
+    return { result: { success: true, deleted_id: task_id } };
+};
+export const addTaskReference = async (args, ctx) => {
+    const { task_id, url, label } = args;
+    validateRequired(task_id, 'task_id');
+    validateUUID(task_id, 'task_id');
+    validateRequired(url, 'url');
+    const { data: task, error: fetchError } = await ctx.supabase
+        .from('tasks')
+        .select('references')
+        .eq('id', task_id)
+        .single();
+    if (fetchError)
+        throw new Error(`Failed to fetch task: ${fetchError.message}`);
+    const currentRefs = task?.references || [];
+    if (currentRefs.some(ref => ref.url === url)) {
+        return { result: { success: false, error: 'Reference with this URL already exists' } };
+    }
+    const newRef = { url, ...(label ? { label } : {}) };
+    const updatedRefs = [...currentRefs, newRef];
+    const { error: updateError } = await ctx.supabase
+        .from('tasks')
+        .update({ references: updatedRefs })
+        .eq('id', task_id);
+    if (updateError)
+        throw new Error(`Failed to add reference: ${updateError.message}`);
+    return { result: { success: true, reference: newRef, total_references: updatedRefs.length } };
+};
+export const removeTaskReference = async (args, ctx) => {
+    const { task_id, url } = args;
+    validateRequired(task_id, 'task_id');
+    validateUUID(task_id, 'task_id');
+    validateRequired(url, 'url');
+    const { data: task, error: fetchError } = await ctx.supabase
+        .from('tasks')
+        .select('references')
+        .eq('id', task_id)
+        .single();
+    if (fetchError)
+        throw new Error(`Failed to fetch task: ${fetchError.message}`);
+    const currentRefs = task?.references || [];
+    const updatedRefs = currentRefs.filter(ref => ref.url !== url);
+    if (updatedRefs.length === currentRefs.length) {
+        return { result: { success: false, error: 'Reference with this URL not found' } };
+    }
+    const { error: updateError } = await ctx.supabase
+        .from('tasks')
+        .update({ references: updatedRefs })
+        .eq('id', task_id);
+    if (updateError)
+        throw new Error(`Failed to remove reference: ${updateError.message}`);
+    return { result: { success: true, remaining_references: updatedRefs.length } };
+};
+export const batchUpdateTasks = async (args, ctx) => {
+    const { updates } = args;
+    const { supabase, session } = ctx;
+    const currentSessionId = session.currentSessionId;
+    if (!updates || !Array.isArray(updates) || updates.length === 0) {
+        throw new ValidationError('updates must be a non-empty array', {
+            field: 'updates',
+            hint: 'Provide an array of task updates with at least one item',
+        });
+    }
+    if (updates.length > 50) {
+        throw new ValidationError('Too many updates. Maximum is 50 per batch.', {
+            field: 'updates',
+            hint: 'Split your updates into smaller batches',
+        });
+    }
+    // Validate all inputs first (no DB queries)
+    const taskIds = [];
+    for (const update of updates) {
+        validateRequired(update.task_id, 'task_id');
+        validateUUID(update.task_id, 'task_id');
+        validateTaskStatus(update.status);
+        validatePriority(update.priority);
+        validateProgressPercentage(update.progress_percentage);
+        taskIds.push(update.task_id);
+    }
+    // OPTIMIZATION: Fetch all tasks in a single query instead of N queries
+    const { data: tasks } = await supabase
+        .from('tasks')
+        .select('id, project_id, started_at')
+        .in('id', taskIds);
+    const taskMap = new Map(tasks?.map(t => [t.id, t]) || []);
+    // OPTIMIZATION: Single query to check if agent has existing in-progress task
+    let existingAgentTask = null;
+    const hasInProgressUpdate = updates.some(u => u.status === 'in_progress');
+    if (hasInProgressUpdate && currentSessionId) {
+        const { data } = await supabase
+            .from('tasks')
+            .select('id, title')
+            .eq('working_agent_session_id', currentSessionId)
+            .eq('status', 'in_progress')
+            .not('id', 'in', `(${taskIds.join(',')})`)
+            .limit(1)
+            .single();
+        existingAgentTask = data;
+    }
+    const results = [];
+    const progressLogsToInsert = [];
+    // OPTIMIZATION: Process updates in parallel instead of sequentially
+    const updatePromises = updates.map(async (update) => {
+        const task = taskMap.get(update.task_id);
+        if (!task) {
+            return { task_id: update.task_id, success: false, error: 'Task not found' };
+        }
+        // Check agent task limit
+        if (update.status === 'in_progress' && existingAgentTask) {
+            return {
+                task_id: update.task_id,
+                success: false,
+                error: `Agent already has task in progress: "${existingAgentTask.title}"`,
+            };
+        }
+        const updateData = {};
+        if (update.status)
+            updateData.status = update.status;
+        if (update.progress_percentage !== undefined)
+            updateData.progress_percentage = update.progress_percentage;
+        if (update.priority !== undefined)
+            updateData.priority = update.priority;
+        // Auto-set started_at when task moves to in_progress
+        if (update.status === 'in_progress' && !task.started_at) {
+            updateData.started_at = new Date().toISOString();
+            if (currentSessionId) {
+                updateData.working_agent_session_id = currentSessionId;
+            }
+        }
+        // Auto-set completed_at when task completes
+        if (update.status === 'completed') {
+            updateData.completed_at = new Date().toISOString();
+            updateData.progress_percentage = 100;
+            updateData.working_agent_session_id = null;
+        }
+        const { error } = await supabase
+            .from('tasks')
+            .update(updateData)
+            .eq('id', update.task_id);
+        if (error) {
+            return { task_id: update.task_id, success: false, error: error.message };
+        }
+        // Queue progress log for batch insert
+        if (update.progress_note && task.project_id) {
+            const progressSummary = update.progress_percentage !== undefined
+                ? `Progress: ${update.progress_percentage}% - ${update.progress_note}`
+                : update.progress_note;
+            progressLogsToInsert.push({
+                project_id: task.project_id,
+                task_id: update.task_id,
+                summary: progressSummary,
+                created_by: 'agent',
+                created_by_session_id: currentSessionId,
+            });
+        }
+        return { task_id: update.task_id, success: true };
+    });
+    // Execute all updates in parallel
+    const updateResults = await Promise.all(updatePromises);
+    results.push(...updateResults);
+    // OPTIMIZATION: Batch insert all progress logs in a single query
+    if (progressLogsToInsert.length > 0) {
+        await supabase.from('progress_logs').insert(progressLogsToInsert);
+    }
+    const successCount = results.filter(r => r.success).length;
+    return {
+        result: {
+            success: successCount === updates.length,
+            total: updates.length,
+            succeeded: successCount,
+        },
+    };
+};
+// ============================================================================
+// Subtask Handlers
+// ============================================================================
+export const addSubtask = async (args, ctx) => {
+    const { parent_task_id, title, description, priority, estimated_minutes } = args;
+    const { supabase, session } = ctx;
+    const currentSessionId = session.currentSessionId;
+    validateRequired(parent_task_id, 'parent_task_id');
+    validateUUID(parent_task_id, 'parent_task_id');
+    validateRequired(title, 'title');
+    if (priority !== undefined)
+        validatePriority(priority);
+    if (estimated_minutes !== undefined)
+        validateEstimatedMinutes(estimated_minutes);
+    // Get parent task to inherit project_id and validate it's not already a subtask
+    const { data: parentTask, error: fetchError } = await supabase
+        .from('tasks')
+        .select('id, project_id, parent_task_id, priority')
+        .eq('id', parent_task_id)
+        .single();
+    if (fetchError || !parentTask) {
+        throw new ValidationError('Parent task not found', {
+            field: 'parent_task_id',
+            hint: 'Provide a valid task ID that exists',
+        });
+    }
+    // Prevent nested subtasks (max depth: 1)
+    if (parentTask.parent_task_id) {
+        return {
+            result: {
+                success: false,
+                error: 'Cannot create subtask of a subtask',
+                hint: 'Subtasks cannot have their own subtasks. Add this task to the parent task instead.',
+                parent_task_id: parentTask.parent_task_id,
+            },
+        };
+    }
+    // Use parent priority if not specified
+    const subtaskPriority = priority ?? parentTask.priority;
+    const { data: subtask, error } = await supabase
+        .from('tasks')
+        .insert({
+        project_id: parentTask.project_id,
+        parent_task_id,
+        title,
+        description: description || null,
+        priority: subtaskPriority,
+        estimated_minutes: estimated_minutes || null,
+        created_by: 'agent',
+        created_by_session_id: currentSessionId,
+    })
+        .select('id, title, priority')
+        .single();
+    if (error)
+        throw new Error(`Failed to add subtask: ${error.message}`);
+    // Log progress
+    await supabase.from('progress_logs').insert({
+        project_id: parentTask.project_id,
+        task_id: parent_task_id,
+        summary: `Added subtask: ${title}`,
+        created_by: 'agent',
+        created_by_session_id: currentSessionId,
+    });
+    return {
+        result: {
+            success: true,
+            subtask_id: subtask.id,
+            parent_task_id,
+            title: subtask.title,
+            priority: subtask.priority,
+        },
+    };
+};
+export const getSubtasks = async (args, ctx) => {
+    const { parent_task_id, status } = args;
+    const { supabase } = ctx;
+    validateRequired(parent_task_id, 'parent_task_id');
+    validateUUID(parent_task_id, 'parent_task_id');
+    if (status)
+        validateTaskStatus(status);
+    let query = supabase
+        .from('tasks')
+        .select('id, title, description, priority, status, progress_percentage, estimated_minutes, started_at, completed_at, working_agent_session_id')
+        .eq('parent_task_id', parent_task_id)
+        .order('priority', { ascending: true })
+        .order('created_at', { ascending: true });
+    if (status) {
+        query = query.eq('status', status);
+    }
+    const { data: subtasks, error } = await query;
+    if (error)
+        throw new Error(`Failed to fetch subtasks: ${error.message}`);
+    // Calculate aggregate stats
+    const total = subtasks?.length || 0;
+    const completed = subtasks?.filter(s => s.status === 'completed').length || 0;
+    const inProgress = subtasks?.filter(s => s.status === 'in_progress').length || 0;
+    const pending = subtasks?.filter(s => s.status === 'pending').length || 0;
+    return {
+        result: {
+            subtasks: subtasks || [],
+            stats: {
+                total,
+                completed,
+                in_progress: inProgress,
+                pending,
+                progress_percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+            },
+        },
+    };
+};
+export const batchCompleteTasks = async (args, ctx) => {
+    const { completions } = args;
+    const { supabase, session } = ctx;
+    const currentSessionId = session.currentSessionId;
+    if (!completions || !Array.isArray(completions) || completions.length === 0) {
+        throw new ValidationError('completions must be a non-empty array', {
+            field: 'completions',
+            hint: 'Provide an array of task completions with at least one item',
+        });
+    }
+    if (completions.length > 50) {
+        throw new ValidationError('Too many completions. Maximum is 50 per batch.', {
+            field: 'completions',
+            hint: 'Split your completions into smaller batches',
+        });
+    }
+    const results = [];
+    for (const completion of completions) {
+        try {
+            validateRequired(completion.task_id, 'task_id');
+            validateUUID(completion.task_id, 'task_id');
+            const { data: task, error: fetchError } = await supabase
+                .from('tasks')
+                .select('project_id, title')
+                .eq('id', completion.task_id)
+                .single();
+            if (fetchError || !task) {
+                results.push({ task_id: completion.task_id, success: false, error: 'Task not found' });
+                continue;
+            }
+            const { error } = await supabase
+                .from('tasks')
+                .update({
+                status: 'completed',
+                completed_at: new Date().toISOString(),
+                progress_percentage: 100,
+                working_agent_session_id: null,
+            })
+                .eq('id', completion.task_id);
+            if (error) {
+                results.push({ task_id: completion.task_id, success: false, error: error.message });
+                continue;
+            }
+            if (completion.summary) {
+                await supabase.from('progress_logs').insert({
+                    project_id: task.project_id,
+                    task_id: completion.task_id,
+                    summary: `Completed: ${task.title}`,
+                    details: completion.summary,
+                    created_by: 'agent',
+                    created_by_session_id: currentSessionId,
+                });
+            }
+            results.push({ task_id: completion.task_id, success: true });
+        }
+        catch (err) {
+            results.push({
+                task_id: completion.task_id,
+                success: false,
+                error: err instanceof Error ? err.message : 'Unknown error',
+            });
+        }
+    }
+    const successCount = results.filter(r => r.success).length;
+    return {
+        result: {
+            success: successCount === completions.length,
+            total: completions.length,
+            succeeded: successCount,
+            failed: completions.length - successCount,
+        },
+    };
+};
+/**
+ * Task handlers registry
+ */
+export const taskHandlers = {
+    get_tasks: getTasks,
+    get_next_task: getNextTask,
+    add_task: addTask,
+    update_task: updateTask,
+    complete_task: completeTask,
+    delete_task: deleteTask,
+    add_task_reference: addTaskReference,
+    remove_task_reference: removeTaskReference,
+    batch_update_tasks: batchUpdateTasks,
+    batch_complete_tasks: batchCompleteTasks,
+    // Subtask handlers
+    add_subtask: addSubtask,
+    get_subtasks: getSubtasks,
+};