@vibescope/mcp-server 0.0.1

package/src/handlers/tasks.ts

@@ -0,0 +1,1393 @@
+/**
+ * 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 type { Handler, HandlerRegistry, HandlerContext } from './types.js';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import {
+	ValidationError,
+	validateRequired,
+	validateUUID,
+	validateTaskStatus,
+	validatePriority,
+	validateProgressPercentage,
+	validateEstimatedMinutes,
+} from '../validators.js';
+import { getRandomFallbackActivity, isValidStatusTransition } from '../utils.js';
+
+/**
+ * Git workflow instructions generator
+ */
+interface GitWorkflowConfig {
+	git_workflow: string;
+	git_main_branch: string;
+	git_develop_branch?: string;
+	git_auto_branch?: boolean;
+}
+
+// Enhanced return types for git instructions
+interface GitStartInstructions {
+	branch_name: string;
+	base_branch: string;
+	steps: string[];
+	reminder: string;
+}
+
+interface GitCompleteInstructions {
+	steps: string[];
+	pr_suggestion?: {
+		title: string;
+		body_template: string;
+	};
+	next_step: string;
+}
+
+interface GitMergeInstructions {
+	target_branch: string;
+	feature_branch: string;
+	steps: string[];
+	cleanup: string[];
+	note: string;
+}
+
+function generateBranchName(taskId: string, taskTitle: string): string {
+	const slug = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 30);
+	return `feature/${taskId.slice(0, 8)}-${slug}`;
+}
+
+function getTaskStartGitInstructions(
+	config: GitWorkflowConfig,
+	taskId: string,
+	taskTitle: string
+): GitStartInstructions | undefined {
+	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: GitWorkflowConfig,
+	taskBranch: string | undefined,
+	taskTitle: string,
+	taskId: string
+): GitCompleteInstructions | undefined {
+	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: GitWorkflowConfig,
+	taskBranch: string | undefined
+): GitMergeInstructions | undefined {
+	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: SupabaseClient, projectId: string): Promise<GitWorkflowConfig | null> {
+	const { data } = await supabase
+		.from('projects')
+		.select('git_workflow, git_main_branch, git_develop_branch, git_auto_branch')
+		.eq('id', projectId)
+		.single();
+
+	return data as GitWorkflowConfig | null;
+}
+
+export { getValidationApprovedGitInstructions };
+
+/**
+ * Check if a session is still active
+ */
+async function checkSessionStatus(
+	ctx: HandlerContext,
+	sessionId: string
+): Promise<{ exists: boolean; isActive: boolean; agentName?: string }> {
+	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: Handler = async (args, ctx) => {
+	const { project_id, status, limit = 50, include_subtasks = false } = args as {
+		project_id: string;
+		status?: string;
+		limit?: number;
+		include_subtasks?: boolean;
+	};
+
+	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: Handler = async (args, ctx) => {
+	const { project_id } = args as { project_id: string };
+	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: Record<string, string> = {
+			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: Record<string, unknown> = {};
+	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: string[] = [];
+				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 as { id: string; title: string; priority: number; status: string }[] | null;
+			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: Handler = async (args, ctx) => {
+	const { project_id, title, description, priority = 3, estimated_minutes, blocking = false } = args as {
+		project_id: string;
+		title: string;
+		description?: string;
+		priority?: number;
+		estimated_minutes?: number;
+		blocking?: boolean;
+	};
+
+	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: Record<string, unknown> = { 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: Handler = async (args, ctx) => {
+	const { task_id, progress_note, ...updates } = args as {
+		task_id: string;
+		title?: string;
+		description?: string;
+		priority?: number;
+		status?: string;
+		progress_percentage?: number;
+		progress_note?: string;
+		estimated_minutes?: number;
+		git_branch?: string;
+	};
+
+	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: Record<string, unknown> = { ...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: Record<string, unknown> = { 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: Handler = async (args, ctx) => {
+	const { task_id, summary } = args as {
+		task_id: string;
+		summary?: string;
+	};
+
+	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: Record<string, unknown> = {
+		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: Handler = async (args, ctx) => {
+	const { task_id } = args as { task_id: string };
+
+	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: Handler = async (args, ctx) => {
+	const { task_id, url, label } = args as { task_id: string; url: string; label?: string };
+
+	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 as { url: string; label?: string }[]) || [];
+
+	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: Handler = async (args, ctx) => {
+	const { task_id, url } = args as { task_id: string; url: string };
+
+	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 as { url: string; label?: string }[]) || [];
+	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: Handler = async (args, ctx) => {
+	const { updates } = args as {
+		updates: Array<{
+			task_id: string;
+			status?: string;
+			progress_percentage?: number;
+			progress_note?: string;
+			priority?: number;
+		}>;
+	};
+
+	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: string[] = [];
+	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: { id: string; title: string } | null = 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: Array<{ task_id: string; success: boolean; error?: string }> = [];
+	const progressLogsToInsert: Array<{
+		project_id: string;
+		task_id: string;
+		summary: string;
+		created_by: string;
+		created_by_session_id: string | null;
+	}> = [];
+
+	// 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: Record<string, unknown> = {};
+		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: Handler = async (args, ctx) => {
+	const { parent_task_id, title, description, priority, estimated_minutes } = args as {
+		parent_task_id: string;
+		title: string;
+		description?: string;
+		priority?: number;
+		estimated_minutes?: number;
+	};
+
+	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: Handler = async (args, ctx) => {
+	const { parent_task_id, status } = args as {
+		parent_task_id: string;
+		status?: string;
+	};
+
+	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: Handler = async (args, ctx) => {
+	const { completions } = args as {
+		completions: Array<{
+			task_id: string;
+			summary?: string;
+		}>;
+	};
+
+	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: Array<{ task_id: string; success: boolean; error?: string }> = [];
+
+	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: HandlerRegistry = {
+	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,
+};