@vibescope/mcp-server 0.2.9 → 0.3.0

package/src/handlers/tasks.ts

@@ -1,945 +1,1121 @@
-/**
- * Task Handlers (Migrated to API Client)
- *
- * Handles task CRUD and management:
- * - get_task (single task by ID)
- * - search_tasks (text search)
- * - get_tasks_by_priority (priority filter)
- * - get_recent_tasks (by date)
- * - get_task_stats (aggregate counts)
- * - get_next_task
- * - add_task
- * - update_task
- * - complete_task
- * - delete_task
- * - add_task_reference
- * - remove_task_reference
- * - batch_update_tasks
- * - batch_complete_tasks
- * - add_subtask
- * - get_subtasks
- */
-
-import os from 'os';
-import type { Handler, HandlerRegistry } from './types.js';
-import {
-	parseArgs,
-	uuidValidator,
-	taskStatusValidator,
-	priorityValidator,
-	progressValidator,
-	minutesValidator,
-	createEnumValidator,
-	ValidationError,
-} from '../validators.js';
-import { getApiClient } from '../api-client.js';
-
-// Auto-detect machine hostname for worktree tracking
-const MACHINE_HOSTNAME = os.hostname();
-
-// Valid task types
-const VALID_TASK_TYPES = [
-	'frontend', 'backend', 'database', 'feature', 'bugfix',
-	'design', 'mcp', 'testing', 'docs', 'infra', 'other'
-] as const;
-
-// ============================================================================
-// Argument Schemas
-// ============================================================================
-
-const getNextTaskSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const addTaskSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	title: { type: 'string' as const, required: true as const },
-	description: { type: 'string' as const },
-	priority: { type: 'number' as const, default: 3, validate: priorityValidator },
-	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
-	blocking: { type: 'boolean' as const, default: false },
-	task_type: { type: 'string' as const, validate: createEnumValidator(VALID_TASK_TYPES) },
-};
-
-const updateTaskSchema = {
-	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	title: { type: 'string' as const },
-	description: { type: 'string' as const },
-	priority: { type: 'number' as const, validate: priorityValidator },
-	status: { type: 'string' as const, validate: taskStatusValidator },
-	progress_percentage: { type: 'number' as const, validate: progressValidator },
-	progress_note: { type: 'string' as const },
-	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
-	git_branch: { type: 'string' as const },
-	worktree_path: { type: 'string' as const },
-	task_type: { type: 'string' as const, validate: createEnumValidator(VALID_TASK_TYPES) },
-	skip_worktree_requirement: { type: 'boolean' as const, default: false },
-};
-
-const completeTaskSchema = {
-	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	summary: { type: 'string' as const },
-};
-
-const deleteTaskSchema = {
-	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const addTaskReferenceSchema = {
-	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	url: { type: 'string' as const, required: true as const },
-	label: { type: 'string' as const },
-};
-
-const removeTaskReferenceSchema = {
-	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	url: { type: 'string' as const, required: true as const },
-};
-
-const batchUpdateTasksSchema = {
-	updates: { type: 'array' as const, required: true as const },
-};
-
-const batchCompleteTasksSchema = {
-	completions: { type: 'array' as const, required: true as const },
-};
-
-const addSubtaskSchema = {
-	parent_task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	title: { type: 'string' as const, required: true as const },
-	description: { type: 'string' as const },
-	priority: { type: 'number' as const, validate: priorityValidator },
-	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
-};
-
-const getSubtasksSchema = {
-	parent_task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	status: { type: 'string' as const, validate: taskStatusValidator },
-	limit: { type: 'number' as const, default: 20 },
-	offset: { type: 'number' as const, default: 0 },
-};
-
-// ============================================================================
-// New Targeted Task Query Schemas
-// ============================================================================
-
-const getTaskSchema = {
-	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	include_subtasks: { type: 'boolean' as const, default: false },
-	include_milestones: { type: 'boolean' as const, default: false },
-};
-
-const searchTasksSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	query: { type: 'string' as const, required: true as const },
-	status: { type: 'array' as const },
-	limit: { type: 'number' as const, default: 10 },
-	offset: { type: 'number' as const, default: 0 },
-};
-
-const getTasksByPrioritySchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	priority: { type: 'number' as const, validate: priorityValidator },
-	priority_max: { type: 'number' as const, validate: priorityValidator },
-	status: { type: 'string' as const, validate: taskStatusValidator },
-	limit: { type: 'number' as const, default: 10 },
-	offset: { type: 'number' as const, default: 0 },
-};
-
-const getRecentTasksSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	order: { type: 'string' as const, validate: createEnumValidator(['newest', 'oldest']) },
-	status: { type: 'string' as const, validate: taskStatusValidator },
-	limit: { type: 'number' as const, default: 10 },
-	offset: { type: 'number' as const, default: 0 },
-};
-
-const getTaskStatsSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-// ============================================================================
-// Git workflow helpers (used by complete_task response)
-// ============================================================================
-
-interface GitWorkflowConfig {
-	git_workflow: string;
-	git_main_branch: string;
-	git_develop_branch?: string | null;
-	git_auto_branch?: boolean;
-}
-
-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 getTaskCompleteGitInstructions(
-	gitWorkflow: string,
-	gitMainBranch: string,
-	gitDevelopBranch: string | undefined,
-	taskBranch: string | undefined,
-	taskTitle: string,
-	taskId: string
-): GitCompleteInstructions | undefined {
-	if (gitWorkflow === 'none') {
-		return undefined;
-	}
-
-	if (gitWorkflow === 'trunk-based') {
-		return {
-			steps: [`git add .`, `git commit -m "feat: ${taskTitle}"`, `git push origin ${gitMainBranch}`],
-			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.',
-	};
-}
-
-export 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.',
-	};
-}
-
-// ============================================================================
-// Task Handlers - Using API Client
-// ============================================================================
-
-export const getNextTask: Handler = async (args, ctx) => {
-	const { project_id } = parseArgs(args, getNextTaskSchema);
-
-	const api = getApiClient();
-	const response = await api.getNextTask(project_id, ctx.session.currentSessionId || undefined);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to get next task' }, isError: true };
-	}
-
-	const data = response.data;
-	if (!data) {
-		return { result: { task: null, message: 'No response from server' } };
-	}
-
-	// Map API response to handler response format
-	const result: Record<string, unknown> = {};
-
-	if (data.task) {
-		result.task = data.task;
-	} else {
-		result.task = null;
-	}
-
-	if (data.blocking_task) result.blocking_task = true;
-	if (data.deployment_blocks_tasks) {
-		result.deployment_blocks_tasks = true;
-		result.deployment = data.deployment;
-		result.action = data.action;
-	}
-	if (data.awaiting_validation) {
-		result.awaiting_validation = data.awaiting_validation;
-		result.validation_priority = data.validation_priority;
-		result.suggested_activity = data.suggested_activity;
-	}
-	if (data.all_claimed) result.all_claimed = true;
-	if (data.is_subtask) result.is_subtask = true;
-	if (data.suggested_activity) result.suggested_activity = data.suggested_activity;
-	if (data.directive) result.directive = data.directive;
-	if (data.message) result.message = data.message;
-
-	return { result };
-};
-
-export const addTask: Handler = async (args, ctx) => {
-	const { project_id, title, description, priority, estimated_minutes, blocking, task_type } = parseArgs(args, addTaskSchema);
-
-	const api = getApiClient();
-	const response = await api.createTask(project_id, {
-		title,
-		description,
-		priority,
-		estimated_minutes,
-		blocking,
-		session_id: ctx.session.currentSessionId || undefined,
-		task_type,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to add task' }, isError: true };
-	}
-
-	const data = response.data;
-	const result: Record<string, unknown> = {
-		success: true,
-		task_id: data?.task_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, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, worktree_path, task_type, skip_worktree_requirement } = parseArgs(args, updateTaskSchema);
-	const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, worktree_path, task_type };
-
-	// Enforce worktree creation: require git_branch when marking task as in_progress
-	// This ensures multi-agent collaboration works properly with isolated worktrees
-	if (status === 'in_progress' && !git_branch && !skip_worktree_requirement) {
-		return {
-			result: {
-				error: 'worktree_required',
-				message: 'git_branch is required when marking a task as in_progress. Create a worktree first and provide the branch name.',
-				hint: 'Create a worktree with: git worktree add ../PROJECT-task-TASKID -b feature/TASKID-description BASE_BRANCH, then call update_task with both status and git_branch parameters.',
-				worktree_example: {
-					command: `git worktree add ../worktree-${task_id.substring(0, 8)} -b feature/${task_id.substring(0, 8)}-task develop`,
-					then: `update_task(task_id: "${task_id}", status: "in_progress", git_branch: "feature/${task_id.substring(0, 8)}-task")`,
-				},
-				skip_option: 'If this project does not use git branching (trunk-based or no git workflow), pass skip_worktree_requirement: true',
-			},
-		};
-	}
-
-	const api = getApiClient();
-	const response = await api.updateTask(task_id, {
-		...updates,
-		progress_note,
-		session_id: ctx.session.currentSessionId || undefined,
-	});
-
-	if (!response.ok) {
-		// Check for specific error types
-		if (response.error?.includes('agent_task_limit') || response.error?.includes('already has a task')) {
-			return {
-				result: {
-					error: 'agent_task_limit',
-					message: response.error,
-				},
-			};
-		}
-		if (response.error?.includes('task_claimed') || response.error?.includes('being worked on')) {
-			return {
-				result: {
-					error: 'task_claimed',
-					message: response.error,
-				},
-			};
-		}
-		if (response.error?.includes('invalid_status_transition')) {
-			return {
-				result: {
-					error: 'invalid_status_transition',
-					message: response.error,
-				},
-			};
-		}
-		if (response.error?.includes('branch_conflict')) {
-			return {
-				result: {
-					error: 'branch_conflict',
-					message: response.error,
-					conflicting_task_id: (response.data as { conflicting_task_id?: string })?.conflicting_task_id,
-					conflicting_task_title: (response.data as { conflicting_task_title?: string })?.conflicting_task_title,
-				},
-			};
-		}
-		return { result: { error: response.error || 'Failed to update task' }, isError: true };
-	}
-
-	// Build result - include git workflow info when transitioning to in_progress
-	const data = response.data;
-	const result: Record<string, unknown> = { success: true, task_id };
-
-	if (data?.git_workflow) {
-		result.git_workflow = data.git_workflow;
-	}
-	if (data?.worktree_setup) {
-		result.worktree_setup = data.worktree_setup;
-	}
-	if (data?.next_step) {
-		result.next_step = data.next_step;
-	}
-
-	// Add test reminder when starting work on a task
-	if (status === 'in_progress') {
-		result.test_reminder = {
-			message: 'Remember to write tests for this task before marking it complete.',
-			minimum_expectation: 'Basic tests that validate the task requirements are met',
-			ideal: 'Tests that also cover edge cases and error handling',
-			test_patterns: ['*.test.ts', '*.spec.ts', '*.test.js', '*.spec.js', '__tests__/*'],
-			note: 'Validators will check for test file changes during review. Documentation-only or config changes may not require tests.',
-		};
-	}
-
-	return { result };
-};
-
-export const completeTask: Handler = async (args, ctx) => {
-	const { task_id, summary } = parseArgs(args, completeTaskSchema);
-
-	const api = getApiClient();
-	const response = await api.completeTask(task_id, {
-		summary,
-		session_id: ctx.session.currentSessionId || undefined,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to complete task' }, isError: true };
-	}
-
-	const data = response.data;
-	if (!data) {
-		return { result: { error: 'No response data from complete task' }, isError: true };
-	}
-
-	// Build result matching expected format
-	const result: Record<string, unknown> = {
-		success: true,
-		directive: data.directive,
-		auto_continue: data.auto_continue,
-		completed_task_id: data.completed_task_id,
-		next_task: data.next_task,
-	};
-
-	if (data.context) {
-		result.context = data.context;
-	}
-
-	// Pass through warnings (e.g., missing git_branch)
-	if (data.warnings) {
-		result.warnings = data.warnings;
-	}
-
-	// Git workflow instructions are already in API response but we need to fetch
-	// task details if we want to include them (API should return these)
-	result.next_action = data.next_action;
-
-	return { result };
-};
-
-export const deleteTask: Handler = async (args, ctx) => {
-	const { task_id } = parseArgs(args, deleteTaskSchema);
-
-	const api = getApiClient();
-	const response = await api.deleteTask(task_id);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to delete task' }, isError: true };
-	}
-
-	return { result: { success: true, deleted_id: task_id } };
-};
-
-export const addTaskReference: Handler = async (args, ctx) => {
-	const { task_id, url, label } = parseArgs(args, addTaskReferenceSchema);
-
-	const api = getApiClient();
-	const response = await api.addTaskReference(task_id, url, label);
-
-	if (!response.ok) {
-		if (response.error?.includes('already exists')) {
-			return { result: { success: false, error: 'Reference with this URL already exists' } };
-		}
-		return { result: { error: response.error || 'Failed to add reference' }, isError: true };
-	}
-
-	return {
-		result: {
-			success: true,
-			reference: response.data?.reference,
-		},
-	};
-};
-
-export const removeTaskReference: Handler = async (args, ctx) => {
-	const { task_id, url } = parseArgs(args, removeTaskReferenceSchema);
-
-	const api = getApiClient();
-	const response = await api.removeTaskReference(task_id, url);
-
-	if (!response.ok) {
-		if (response.error?.includes('not found')) {
-			return { result: { success: false, error: 'Reference with this URL not found' } };
-		}
-		return { result: { error: response.error || 'Failed to remove reference' }, isError: true };
-	}
-
-	return { result: { success: true } };
-};
-
-export const batchUpdateTasks: Handler = async (args, ctx) => {
-	const { updates } = parseArgs(args, batchUpdateTasksSchema);
-
-	const typedUpdates = updates as Array<{
-		task_id: string;
-		status?: string;
-		progress_percentage?: number;
-		progress_note?: string;
-		priority?: number;
-	}>;
-
-	if (!Array.isArray(typedUpdates) || typedUpdates.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 (typedUpdates.length > 50) {
-		throw new ValidationError('Too many updates. Maximum is 50 per batch.', {
-			field: 'updates',
-			hint: 'Split your updates into smaller batches',
-		});
-	}
-
-	// Individual item validation happens at API level
-	const api = getApiClient();
-	const response = await api.batchUpdateTasks(typedUpdates);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to batch update tasks' }, isError: true };
-	}
-
-	return {
-		result: {
-			success: response.data?.success || false,
-			total: typedUpdates.length,
-			succeeded: response.data?.updated_count || 0,
-		},
-	};
-};
-
-export const batchCompleteTasks: Handler = async (args, ctx) => {
-	const { completions } = parseArgs(args, batchCompleteTasksSchema);
-
-	const typedCompletions = completions as Array<{
-		task_id: string;
-		summary?: string;
-	}>;
-
-	if (!Array.isArray(typedCompletions) || typedCompletions.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 (typedCompletions.length > 50) {
-		throw new ValidationError('Too many completions. Maximum is 50 per batch.', {
-			field: 'completions',
-			hint: 'Split your completions into smaller batches',
-		});
-	}
-
-	// Individual item validation happens at API level
-
-	const api = getApiClient();
-	const response = await api.batchCompleteTasks(typedCompletions);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to batch complete tasks' }, isError: true };
-	}
-
-	const data = response.data;
-	return {
-		result: {
-			success: data?.success || false,
-			total: typedCompletions.length,
-			succeeded: data?.completed_count || 0,
-			failed: typedCompletions.length - (data?.completed_count || 0),
-			next_task: data?.next_task,
-		},
-	};
-};
-
-// ============================================================================
-// Subtask Handlers
-// ============================================================================
-
-export const addSubtask: Handler = async (args, ctx) => {
-	const { parent_task_id, title, description, priority, estimated_minutes } = parseArgs(args, addSubtaskSchema);
-
-	const api = getApiClient();
-	const response = await api.addSubtask(parent_task_id, {
-		title,
-		description,
-		priority,
-		estimated_minutes,
-	}, ctx.session.currentSessionId || undefined);
-
-	if (!response.ok) {
-		if (response.error?.includes('Cannot create subtask of a subtask')) {
-			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.',
-				},
-			};
-		}
-		return { result: { error: response.error || 'Failed to add subtask' }, isError: true };
-	}
-
-	return {
-		result: {
-			success: true,
-			subtask_id: response.data?.subtask_id,
-			parent_task_id: response.data?.parent_task_id,
-		},
-	};
-};
-
-export const getSubtasks: Handler = async (args, ctx) => {
-	const { parent_task_id, status } = parseArgs(args, getSubtasksSchema);
-
-	const api = getApiClient();
-	const response = await api.getSubtasks(parent_task_id, status);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to fetch subtasks' }, isError: true };
-	}
-
-	return {
-		result: {
-			subtasks: response.data?.subtasks || [],
-			stats: response.data?.stats || {
-				total: 0,
-				completed: 0,
-				progress_percentage: 0,
-			},
-		},
-	};
-};
-
-// ============================================================================
-// New Targeted Task Query Handlers
-// ============================================================================
-
-/**
- * Get a single task by ID with optional subtasks and milestones
- */
-export const getTask: Handler = async (args, ctx) => {
-	const { task_id, include_subtasks, include_milestones } = parseArgs(args, getTaskSchema);
-
-	const api = getApiClient();
-	const response = await api.getTaskById(task_id, {
-		include_subtasks,
-		include_milestones,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to fetch task' }, isError: true };
-	}
-
-	const result: Record<string, unknown> = {
-		task: response.data?.task,
-	};
-
-	if (include_subtasks && response.data?.subtasks) {
-		result.subtasks = response.data.subtasks;
-	}
-
-	if (include_milestones && response.data?.milestones) {
-		result.milestones = response.data.milestones;
-	}
-
-	return { result };
-};
-
-/**
- * Search tasks by text query with pagination
- */
-export const searchTasks: Handler = async (args, ctx) => {
-	const { project_id, query, status, limit, offset } = parseArgs(args, searchTasksSchema);
-
-	// Validate query length
-	if (query.length < 2) {
-		return {
-			result: {
-				error: 'query_too_short',
-				message: 'Search query must be at least 2 characters',
-			},
-		};
-	}
-
-	// Cap limit at 20, safe offset
-	const cappedLimit = Math.min(limit ?? 10, 20);
-	const safeOffset = Math.max(0, offset ?? 0);
-
-	const api = getApiClient();
-	const response = await api.searchTasks(project_id, {
-		query,
-		status: status as string[] | undefined,
-		limit: cappedLimit,
-		offset: safeOffset,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to search tasks' }, isError: true };
-	}
-
-	const tasks = response.data?.tasks || [];
-	const totalMatches = response.data?.total_matches || 0;
-
-	return {
-		result: {
-			tasks,
-			total_matches: totalMatches,
-			has_more: safeOffset + tasks.length < totalMatches,
-			offset: safeOffset,
-			limit: cappedLimit,
-		},
-	};
-};
-
-/**
- * Get tasks filtered by priority with pagination
- */
-export const getTasksByPriority: Handler = async (args, ctx) => {
-	const { project_id, priority, priority_max, status, limit, offset } = parseArgs(args, getTasksByPrioritySchema);
-
-	// Cap limit at 20, safe offset
-	const cappedLimit = Math.min(limit ?? 10, 20);
-	const safeOffset = Math.max(0, offset ?? 0);
-
-	const api = getApiClient();
-	const response = await api.getTasksByPriority(project_id, {
-		priority,
-		priority_max,
-		status,
-		limit: cappedLimit,
-		offset: safeOffset,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to fetch tasks by priority' }, isError: true };
-	}
-
-	const tasks = response.data?.tasks || [];
-	const totalCount = response.data?.total_count || 0;
-
-	return {
-		result: {
-			tasks,
-			total_count: totalCount,
-			has_more: safeOffset + tasks.length < totalCount,
-			offset: safeOffset,
-			limit: cappedLimit,
-		},
-	};
-};
-
-/**
- * Get recent tasks (newest or oldest) with pagination
- */
-export const getRecentTasks: Handler = async (args, ctx) => {
-	const { project_id, order, status, limit, offset } = parseArgs(args, getRecentTasksSchema);
-
-	// Cap limit at 20, safe offset
-	const cappedLimit = Math.min(limit ?? 10, 20);
-	const safeOffset = Math.max(0, offset ?? 0);
-
-	const api = getApiClient();
-	const response = await api.getRecentTasks(project_id, {
-		order: order as 'newest' | 'oldest' | undefined,
-		status,
-		limit: cappedLimit,
-		offset: safeOffset,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to fetch recent tasks' }, isError: true };
-	}
-
-	const tasks = response.data?.tasks || [];
-	const totalCount = response.data?.total_count || 0;
-
-	return {
-		result: {
-			tasks,
-			total_count: totalCount,
-			has_more: safeOffset + tasks.length < totalCount,
-			offset: safeOffset,
-			limit: cappedLimit,
-		},
-	};
-};
-
-/**
- * Get task statistics for a project (aggregate counts only, minimal tokens)
- */
-export const getTaskStats: Handler = async (args, ctx) => {
-	const { project_id } = parseArgs(args, getTaskStatsSchema);
-
-	const api = getApiClient();
-	const response = await api.getTaskStats(project_id);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to fetch task stats' }, isError: true };
-	}
-
-	return {
-		result: {
-			total: response.data?.total || 0,
-			by_status: response.data?.by_status || {
-				backlog: 0,
-				pending: 0,
-				in_progress: 0,
-				completed: 0,
-				cancelled: 0,
-			},
-			by_priority: response.data?.by_priority || { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 },
-			awaiting_validation: response.data?.awaiting_validation || 0,
-			oldest_pending_days: response.data?.oldest_pending_days ?? null,
-		},
-	};
-};
-
-// ============================================================================
-// Worktree Cleanup Handlers
-// ============================================================================
-
-const getStaleWorktreesSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	hostname: { type: 'string' as const }, // Machine hostname to filter worktrees
-	limit: { type: 'number' as const, default: 20 },
-	offset: { type: 'number' as const, default: 0 },
-};
-
-const clearWorktreePathSchema = {
-	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-export const getStaleWorktrees: Handler = async (args, ctx) => {
-	const { project_id, hostname: providedHostname, limit, offset } = parseArgs(args, getStaleWorktreesSchema);
-
-	// Use auto-detected hostname if not provided - filters to only worktrees on THIS machine
-	const hostname = providedHostname || MACHINE_HOSTNAME;
-
-	// Cap limit to prevent context bloating
-	const cappedLimit = Math.min(limit ?? 20, 50);
-
-	const api = getApiClient();
-	const response = await api.getStaleWorktrees(project_id, { hostname, limit: cappedLimit, offset });
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to get stale worktrees' }, isError: true };
-	}
-
-	const data = response.data;
-	return {
-		result: {
-			project_id: data?.project_id,
-			project_name: data?.project_name,
-			hostname_filter: data?.hostname_filter,
-			stale_worktrees: data?.stale_worktrees || [],
-			count: data?.count || 0,
-			local_count: data?.local_count || 0,
-			remote_count: data?.remote_count || 0,
-			total_count: data?.total_count || 0,
-			has_more: data?.has_more || false,
-			cleanup_instructions: data?.cleanup_instructions,
-			remote_worktree_note: data?.remote_worktree_note,
-		},
-	};
-};
-
-export const clearWorktreePath: Handler = async (args, ctx) => {
-	const { task_id } = parseArgs(args, clearWorktreePathSchema);
-
-	const api = getApiClient();
-	const response = await api.clearWorktreePath(task_id);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to clear worktree path' }, isError: true };
-	}
-
-	return {
-		result: {
-			success: true,
-			task_id,
-			message: 'Worktree path cleared. The worktree can now be safely removed if not already done.',
-		},
-	};
-};
-
-/**
- * Task handlers registry
- */
-export const taskHandlers: HandlerRegistry = {
-	// Targeted task query endpoints (token-efficient)
-	get_task: getTask,
-	search_tasks: searchTasks,
-	get_tasks_by_priority: getTasksByPriority,
-	get_recent_tasks: getRecentTasks,
-	get_task_stats: getTaskStats,
-	// Core task operations
-	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,
-	// Worktree cleanup handlers
-	get_stale_worktrees: getStaleWorktrees,
-	clear_worktree_path: clearWorktreePath,
-};
+/**
+ * Task Handlers (Migrated to API Client)
+ *
+ * Handles task CRUD and management:
+ * - get_task (single task by ID)
+ * - search_tasks (text search)
+ * - get_tasks_by_priority (priority filter)
+ * - get_recent_tasks (by date)
+ * - get_task_stats (aggregate counts)
+ * - get_next_task
+ * - add_task
+ * - update_task
+ * - complete_task
+ * - delete_task
+ * - release_task
+ * - cancel_task
+ * - add_task_reference
+ * - remove_task_reference
+ * - batch_update_tasks
+ * - batch_complete_tasks
+ * - add_subtask
+ * - get_subtasks
+ */
+
+import os from 'os';
+import type { Handler, HandlerRegistry } from './types.js';
+import {
+	parseArgs,
+	uuidValidator,
+	taskStatusValidator,
+	priorityValidator,
+	progressValidator,
+	minutesValidator,
+	createEnumValidator,
+	ValidationError,
+} from '../validators.js';
+import { getApiClient } from '../api-client.js';
+
+// Auto-detect machine hostname for worktree tracking
+const MACHINE_HOSTNAME = os.hostname();
+
+// Valid task types
+const VALID_TASK_TYPES = [
+	'frontend', 'backend', 'database', 'feature', 'bugfix',
+	'design', 'mcp', 'testing', 'docs', 'infra', 'other'
+] as const;
+
+// ============================================================================
+// Argument Schemas
+// ============================================================================
+
+const getNextTaskSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const addTaskSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	priority: { type: 'number' as const, default: 3, validate: priorityValidator },
+	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
+	blocking: { type: 'boolean' as const, default: false },
+	task_type: { type: 'string' as const, validate: createEnumValidator(VALID_TASK_TYPES) },
+};
+
+const updateTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	description: { type: 'string' as const },
+	priority: { type: 'number' as const, validate: priorityValidator },
+	status: { type: 'string' as const, validate: taskStatusValidator },
+	progress_percentage: { type: 'number' as const, validate: progressValidator },
+	progress_note: { type: 'string' as const },
+	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
+	git_branch: { type: 'string' as const },
+	worktree_path: { type: 'string' as const },
+	task_type: { type: 'string' as const, validate: createEnumValidator(VALID_TASK_TYPES) },
+	skip_worktree_requirement: { type: 'boolean' as const, default: false },
+};
+
+const completeTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	summary: { type: 'string' as const },
+};
+
+const deleteTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const releaseTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	reason: { type: 'string' as const },
+};
+
+// Valid reasons for task cancellation
+const VALID_CANCELLED_REASONS = [
+	'pr_closed', 'superseded', 'user_cancelled', 'validation_failed', 'obsolete', 'blocked'
+] as const;
+
+const cancelTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	cancelled_reason: { type: 'string' as const, validate: createEnumValidator(VALID_CANCELLED_REASONS) },
+	cancellation_note: { type: 'string' as const },
+};
+
+const addTaskReferenceSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	url: { type: 'string' as const, required: true as const },
+	label: { type: 'string' as const },
+};
+
+const removeTaskReferenceSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	url: { type: 'string' as const, required: true as const },
+};
+
+const batchUpdateTasksSchema = {
+	updates: { type: 'array' as const, required: true as const },
+};
+
+const batchCompleteTasksSchema = {
+	completions: { type: 'array' as const, required: true as const },
+};
+
+const addSubtaskSchema = {
+	parent_task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	priority: { type: 'number' as const, validate: priorityValidator },
+	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
+};
+
+const getSubtasksSchema = {
+	parent_task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, validate: taskStatusValidator },
+	limit: { type: 'number' as const, default: 20 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+// ============================================================================
+// New Targeted Task Query Schemas
+// ============================================================================
+
+const getTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	include_subtasks: { type: 'boolean' as const, default: false },
+	include_milestones: { type: 'boolean' as const, default: false },
+};
+
+const searchTasksSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	query: { type: 'string' as const, required: true as const },
+	status: { type: 'array' as const },
+	limit: { type: 'number' as const, default: 10 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const getTasksByPrioritySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	priority: { type: 'number' as const, validate: priorityValidator },
+	priority_max: { type: 'number' as const, validate: priorityValidator },
+	status: { type: 'string' as const, validate: taskStatusValidator },
+	limit: { type: 'number' as const, default: 10 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const getRecentTasksSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	order: { type: 'string' as const, validate: createEnumValidator(['newest', 'oldest']) },
+	status: { type: 'string' as const, validate: taskStatusValidator },
+	limit: { type: 'number' as const, default: 10 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const getTaskStatsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+// ============================================================================
+// Git workflow helpers (used by complete_task response)
+// ============================================================================
+
+interface GitWorkflowConfig {
+	git_workflow: string;
+	git_main_branch: string;
+	git_develop_branch?: string | null;
+	git_auto_branch?: boolean;
+}
+
+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 getTaskCompleteGitInstructions(
+	gitWorkflow: string,
+	gitMainBranch: string,
+	gitDevelopBranch: string | undefined,
+	taskBranch: string | undefined,
+	taskTitle: string,
+	taskId: string
+): GitCompleteInstructions | undefined {
+	if (gitWorkflow === 'none') {
+		return undefined;
+	}
+
+	if (gitWorkflow === 'trunk-based') {
+		return {
+			steps: [`git add .`, `git commit -m "feat: ${taskTitle}"`, `git push origin ${gitMainBranch}`],
+			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.',
+	};
+}
+
+export 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.',
+	};
+}
+
+// ============================================================================
+// Task Handlers - Using API Client
+// ============================================================================
+
+export const getNextTask: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, getNextTaskSchema);
+
+	const api = getApiClient();
+	const response = await api.getNextTask(project_id, ctx.session.currentSessionId || undefined);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get next task' }, isError: true };
+	}
+
+	const data = response.data;
+	if (!data) {
+		return { result: { task: null, message: 'No response from server' } };
+	}
+
+	// Map API response to handler response format
+	const result: Record<string, unknown> = {};
+
+	if (data.task) {
+		result.task = data.task;
+	} else {
+		result.task = null;
+		// Add IDLE_GUIDANCE when no tasks are available
+		result.IDLE_GUIDANCE = {
+			message: 'No tasks available. Follow these steps:',
+			steps: [
+				'1. Call signal_idle() to update dashboard immediately - shows you are available',
+				'2. Start a fallback_activity (code_review, security_review, test_coverage, etc.)',
+				'3. Never ask "what should I do?" - be autonomous',
+			],
+			autonomy_rules: [
+				'Never ask "should I continue?" → Just continue',
+				'Never say "let me know what to do" → Use fallback activities',
+				'When context grows large: /clear → start_work_session (don\'t ask, just do it)',
+			],
+			next_action: `signal_idle() then start_fallback_activity(project_id: "${project_id}", activity: "code_review")`,
+		};
+	}
+
+	if (data.blocking_task) result.blocking_task = true;
+	if (data.deployment_blocks_tasks) {
+		result.deployment_blocks_tasks = true;
+		result.deployment = data.deployment;
+		result.action = data.action;
+	}
+	if (data.awaiting_validation) {
+		result.awaiting_validation = data.awaiting_validation;
+		result.validation_priority = data.validation_priority;
+		result.suggested_activity = data.suggested_activity;
+	}
+	if (data.all_claimed) result.all_claimed = true;
+	if (data.is_subtask) result.is_subtask = true;
+	if (data.suggested_activity) result.suggested_activity = data.suggested_activity;
+	if (data.directive) result.directive = data.directive;
+	if (data.message) result.message = data.message;
+
+	return { result };
+};
+
+export const addTask: Handler = async (args, ctx) => {
+	const { project_id, title, description, priority, estimated_minutes, blocking, task_type } = parseArgs(args, addTaskSchema);
+
+	const api = getApiClient();
+	const response = await api.createTask(project_id, {
+		title,
+		description,
+		priority,
+		estimated_minutes,
+		blocking,
+		session_id: ctx.session.currentSessionId || undefined,
+		task_type,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to add task' }, isError: true };
+	}
+
+	const data = response.data;
+	const result: Record<string, unknown> = {
+		success: true,
+		task_id: data?.task_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, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, worktree_path, task_type, skip_worktree_requirement } = parseArgs(args, updateTaskSchema);
+	const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, worktree_path, task_type };
+
+	// Enforce worktree creation: require git_branch when marking task as in_progress
+	// This ensures multi-agent collaboration works properly with isolated worktrees
+	if (status === 'in_progress' && !git_branch && !skip_worktree_requirement) {
+		return {
+			result: {
+				error: 'worktree_required',
+				message: 'git_branch is required when marking a task as in_progress. Create a worktree first and provide the branch name.',
+				hint: 'Create a worktree with: git worktree add ../PROJECT-task-TASKID -b feature/TASKID-description BASE_BRANCH, then call update_task with both status and git_branch parameters.',
+				worktree_example: {
+					command: `git worktree add ../worktree-${task_id.substring(0, 8)} -b feature/${task_id.substring(0, 8)}-task develop`,
+					then: `update_task(task_id: "${task_id}", status: "in_progress", git_branch: "feature/${task_id.substring(0, 8)}-task")`,
+				},
+				skip_option: 'If this project does not use git branching (trunk-based or no git workflow), pass skip_worktree_requirement: true',
+			},
+		};
+	}
+
+	const api = getApiClient();
+	const response = await api.updateTask(task_id, {
+		...updates,
+		progress_note,
+		session_id: ctx.session.currentSessionId || undefined,
+	});
+
+	if (!response.ok) {
+		// Check for specific error types
+		if (response.error?.includes('agent_task_limit') || response.error?.includes('already has a task')) {
+			return {
+				result: {
+					error: 'agent_task_limit',
+					message: response.error,
+				},
+			};
+		}
+		if (response.error?.includes('task_claimed') || response.error?.includes('task_already_claimed') || response.error?.includes('being worked on') || response.error?.includes('already being worked on')) {
+			const data = response.data as { claimed_by?: string; claimed_session_id?: string; message?: string } | undefined;
+			return {
+				result: {
+					error: 'task_already_claimed',
+					message: data?.message || response.error || 'Task is already claimed by another agent',
+					claimed_by: data?.claimed_by,
+					claimed_session_id: data?.claimed_session_id,
+					suggestion: 'Use get_next_task() to get a different available task, or wait for the claiming agent to finish.',
+				},
+			};
+		}
+		if (response.error?.includes('invalid_status_transition')) {
+			return {
+				result: {
+					error: 'invalid_status_transition',
+					message: response.error,
+				},
+			};
+		}
+		if (response.error?.includes('branch_conflict')) {
+			return {
+				result: {
+					error: 'branch_conflict',
+					message: response.error,
+					conflicting_task_id: (response.data as { conflicting_task_id?: string })?.conflicting_task_id,
+					conflicting_task_title: (response.data as { conflicting_task_title?: string })?.conflicting_task_title,
+				},
+			};
+		}
+		return { result: { error: response.error || 'Failed to update task' }, isError: true };
+	}
+
+	// Build result - include git workflow info when transitioning to in_progress
+	const data = response.data;
+	const result: Record<string, unknown> = { success: true, task_id };
+
+	if (data?.git_workflow) {
+		result.git_workflow = data.git_workflow;
+	}
+	if (data?.worktree_setup) {
+		result.worktree_setup = data.worktree_setup;
+	}
+	if (data?.next_step) {
+		result.next_step = data.next_step;
+	}
+
+	// Add test reminder when starting work on a task
+	if (status === 'in_progress') {
+		result.test_reminder = {
+			message: 'Remember to write tests for this task before marking it complete.',
+			minimum_expectation: 'Basic tests that validate the task requirements are met',
+			ideal: 'Tests that also cover edge cases and error handling',
+			test_patterns: ['*.test.ts', '*.spec.ts', '*.test.js', '*.spec.js', '__tests__/*'],
+			note: 'Validators will check for test file changes during review. Documentation-only or config changes may not require tests.',
+		};
+
+		// Add comprehensive WORKTREE RULES for branching workflows
+		// This reminds agents of the critical workflow order
+		result.WORKTREE_RULES = {
+			mandatory: true,
+			rules: [
+				'1. Create worktree BEFORE any file edits - reading is fine, editing requires worktree first',
+				'2. Naming: ../PROJECT-PERSONA-short-desc (max 24 chars for description)',
+				'3. Command: git worktree add ../PROJECT-PERSONA-desc -b feature/TASKID-desc BASE_BRANCH',
+				'4. Report location: heartbeat(current_worktree_path: "...")',
+				'5. Store path: update_task(task_id, worktree_path: "...")',
+				'6. REBASE before PR: git fetch origin && git rebase origin/BASE_BRANCH && git push --force-with-lease',
+			],
+			rebase_before_pr: {
+				mandatory: true,
+				why: 'Without rebasing, your branch may contain old versions of files that other agents modified. When merged, your old version overwrites their changes.',
+				commands: [
+					'git fetch origin',
+					'git rebase origin/develop  # or origin/main for github-flow',
+					'git push --force-with-lease',
+				],
+			},
+			wrong_order: {
+				violation: 'Edit file → stash → create worktree → pop → commit',
+				why: 'Even if you eventually use a worktree, editing before creating one is a violation',
+			},
+			right_order: {
+				correct: 'Read to understand → create worktree → cd into it → THEN edit',
+				why: 'Worktrees must exist BEFORE any file modifications',
+			},
+		};
+
+		// Add HOTFIX_WORKFLOW guidance when branch name indicates hotfix
+		if (git_branch && git_branch.includes('hotfix/')) {
+			result.HOTFIX_WORKFLOW = {
+				message: 'HOTFIX detected - special workflow applies:',
+				steps: [
+					'1. Create worktree from MAIN (not develop): git worktree add ../PROJECT-PERSONA-hotfix-desc -b hotfix/TASKID-desc main',
+					'2. Work in worktree and make your fix',
+					'3. Commit: git add -A && git commit -m "fix: description"',
+					'4. Push: git push -u origin hotfix/TASKID-desc',
+					'5. Create PR targeting MAIN: gh pr create --base main --title "fix: ..." --body "Hotfix for production"',
+					'6. Remove worktree immediately after PR',
+				],
+				important: 'Hotfixes go to MAIN, not develop. They are later merged to develop separately.',
+				worktree_required: true,
+			};
+		}
+
+		// Guidance for when investigation reveals fix already exists
+		result.FIX_ALREADY_EXISTS_GUIDANCE = {
+			message: 'If investigation reveals the fix already exists but needs deployment:',
+			steps: [
+				'1. Add finding: add_finding(project_id, title: "Fix exists, awaits deployment", category: "other", severity: "info", description: "...", related_task_id: task_id)',
+				'2. Complete task: complete_task(task_id, summary: "Fix already exists in codebase (PR #XXX). Needs deployment.")',
+				'3. Check deployment: check_deployment_status(project_id)',
+				'4. Request deployment if not pending: request_deployment(project_id, notes: "Includes fix for [issue]")',
+			],
+			rationale: 'This prevents tasks from being blocked waiting for deployment when the actual work is done.',
+		};
+	}
+
+	return { result };
+};
+
+export const completeTask: Handler = async (args, ctx) => {
+	const { task_id, summary } = parseArgs(args, completeTaskSchema);
+
+	const api = getApiClient();
+	const response = await api.completeTask(task_id, {
+		summary,
+		session_id: ctx.session.currentSessionId || undefined,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to complete task' }, isError: true };
+	}
+
+	const data = response.data;
+	if (!data) {
+		return { result: { error: 'No response data from complete task' }, isError: true };
+	}
+
+	// Build result matching expected format
+	const result: Record<string, unknown> = {
+		success: true,
+		directive: data.directive,
+		auto_continue: data.auto_continue,
+		completed_task_id: data.completed_task_id,
+		next_task: data.next_task,
+	};
+
+	if (data.context) {
+		result.context = data.context;
+	}
+
+	// Pass through warnings (e.g., missing git_branch)
+	if (data.warnings) {
+		result.warnings = data.warnings;
+	}
+
+	// Git workflow instructions are already in API response but we need to fetch
+	// task details if we want to include them (API should return these)
+	result.next_action = data.next_action;
+
+	// Add mandatory action reminders for complete_task
+	result.MANDATORY_ACTIONS = {
+		message: 'Before marking task complete, ensure you have done the following:',
+		checklist: [
+			'If you made code changes: Commit and push all changes to your branch',
+			'REBASE before PR: git fetch origin && git rebase origin/BASE_BRANCH && git push --force-with-lease',
+			'If project uses PR workflow: Create PR targeting correct branch (develop for git-flow, main for github-flow)',
+			'If using worktree: Remove worktree IMMEDIATELY after PR is created',
+		],
+		sequence: 'Commit → Rebase → Push → PR created → complete_task() → remove worktree → next task',
+		important: 'DO NOT wait for PR review/merge - validation handles that. Complete task immediately after PR.',
+		rebase_warning: 'Always rebase before creating PR to avoid overwriting other agents\' work.',
+	};
+
+	// Add worktree cleanup reminder if worktree was used
+	if (data.context?.worktree_path) {
+		result.worktree_cleanup = {
+			required: true,
+			path: data.context.worktree_path,
+			command: `git worktree remove ${data.context.worktree_path}`,
+			timing: 'Remove immediately after PR is created and complete_task is called',
+		};
+	}
+
+	return { result };
+};
+
+export const deleteTask: Handler = async (args, ctx) => {
+	const { task_id } = parseArgs(args, deleteTaskSchema);
+
+	const api = getApiClient();
+	const response = await api.deleteTask(task_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to delete task' }, isError: true };
+	}
+
+	return { result: { success: true, deleted_id: task_id } };
+};
+
+/**
+ * Release a task back to pending status.
+ * Use when an agent needs to give up a claimed task (context limits, conflicts, user request).
+ */
+export const releaseTask: Handler = async (args, ctx) => {
+	const { task_id, reason } = parseArgs(args, releaseTaskSchema);
+
+	const api = getApiClient();
+	const response = await api.releaseTask(task_id, {
+		reason,
+		session_id: ctx.session.currentSessionId || undefined,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to release task' }, isError: true };
+	}
+
+	return {
+		result: {
+			success: true,
+			task_id,
+			message: response.data?.message || 'Task released and returned to pending status',
+			reason: reason || null,
+			hint: 'The task is now available for other agents to claim. Call get_next_task() to get a new task.',
+		},
+	};
+};
+
+export const cancelTask: Handler = async (args, ctx) => {
+	const { task_id, cancelled_reason, cancellation_note } = parseArgs(args, cancelTaskSchema);
+
+	const api = getApiClient();
+	// Cast cancelled_reason to the expected union type - validation already ensures it's valid
+	const response = await api.cancelTask(task_id, {
+		cancelled_reason: cancelled_reason as 'pr_closed' | 'superseded' | 'user_cancelled' | 'validation_failed' | 'obsolete' | 'blocked' | undefined,
+		cancellation_note,
+		session_id: ctx.session.currentSessionId || undefined,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to cancel task' }, isError: true };
+	}
+
+	return {
+		result: {
+			success: true,
+			task_id,
+			cancelled_reason: cancelled_reason || null,
+			message: response.data?.message || `Task cancelled${cancelled_reason ? ` (${cancelled_reason})` : ''}`,
+		},
+	};
+};
+
+export const addTaskReference: Handler = async (args, ctx) => {
+	const { task_id, url, label } = parseArgs(args, addTaskReferenceSchema);
+
+	const api = getApiClient();
+	const response = await api.addTaskReference(task_id, url, label);
+
+	if (!response.ok) {
+		if (response.error?.includes('already exists')) {
+			return { result: { success: false, error: 'Reference with this URL already exists' } };
+		}
+		return { result: { error: response.error || 'Failed to add reference' }, isError: true };
+	}
+
+	return {
+		result: {
+			success: true,
+			reference: response.data?.reference,
+		},
+	};
+};
+
+export const removeTaskReference: Handler = async (args, ctx) => {
+	const { task_id, url } = parseArgs(args, removeTaskReferenceSchema);
+
+	const api = getApiClient();
+	const response = await api.removeTaskReference(task_id, url);
+
+	if (!response.ok) {
+		if (response.error?.includes('not found')) {
+			return { result: { success: false, error: 'Reference with this URL not found' } };
+		}
+		return { result: { error: response.error || 'Failed to remove reference' }, isError: true };
+	}
+
+	return { result: { success: true } };
+};
+
+export const batchUpdateTasks: Handler = async (args, ctx) => {
+	const { updates } = parseArgs(args, batchUpdateTasksSchema);
+
+	const typedUpdates = updates as Array<{
+		task_id: string;
+		status?: string;
+		progress_percentage?: number;
+		progress_note?: string;
+		priority?: number;
+	}>;
+
+	if (!Array.isArray(typedUpdates) || typedUpdates.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 (typedUpdates.length > 50) {
+		throw new ValidationError('Too many updates. Maximum is 50 per batch.', {
+			field: 'updates',
+			hint: 'Split your updates into smaller batches',
+		});
+	}
+
+	// Individual item validation happens at API level
+	const api = getApiClient();
+	const response = await api.batchUpdateTasks(typedUpdates);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to batch update tasks' }, isError: true };
+	}
+
+	return {
+		result: {
+			success: response.data?.success || false,
+			total: typedUpdates.length,
+			succeeded: response.data?.updated_count || 0,
+		},
+	};
+};
+
+export const batchCompleteTasks: Handler = async (args, ctx) => {
+	const { completions } = parseArgs(args, batchCompleteTasksSchema);
+
+	const typedCompletions = completions as Array<{
+		task_id: string;
+		summary?: string;
+	}>;
+
+	if (!Array.isArray(typedCompletions) || typedCompletions.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 (typedCompletions.length > 50) {
+		throw new ValidationError('Too many completions. Maximum is 50 per batch.', {
+			field: 'completions',
+			hint: 'Split your completions into smaller batches',
+		});
+	}
+
+	// Individual item validation happens at API level
+
+	const api = getApiClient();
+	const response = await api.batchCompleteTasks(typedCompletions);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to batch complete tasks' }, isError: true };
+	}
+
+	const data = response.data;
+	return {
+		result: {
+			success: data?.success || false,
+			total: typedCompletions.length,
+			succeeded: data?.completed_count || 0,
+			failed: typedCompletions.length - (data?.completed_count || 0),
+			next_task: data?.next_task,
+		},
+	};
+};
+
+// ============================================================================
+// Subtask Handlers
+// ============================================================================
+
+export const addSubtask: Handler = async (args, ctx) => {
+	const { parent_task_id, title, description, priority, estimated_minutes } = parseArgs(args, addSubtaskSchema);
+
+	const api = getApiClient();
+	const response = await api.addSubtask(parent_task_id, {
+		title,
+		description,
+		priority,
+		estimated_minutes,
+	}, ctx.session.currentSessionId || undefined);
+
+	if (!response.ok) {
+		if (response.error?.includes('Cannot create subtask of a subtask')) {
+			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.',
+				},
+			};
+		}
+		return { result: { error: response.error || 'Failed to add subtask' }, isError: true };
+	}
+
+	return {
+		result: {
+			success: true,
+			subtask_id: response.data?.subtask_id,
+			parent_task_id: response.data?.parent_task_id,
+		},
+	};
+};
+
+export const getSubtasks: Handler = async (args, ctx) => {
+	const { parent_task_id, status } = parseArgs(args, getSubtasksSchema);
+
+	const api = getApiClient();
+	const response = await api.getSubtasks(parent_task_id, status);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch subtasks' }, isError: true };
+	}
+
+	return {
+		result: {
+			subtasks: response.data?.subtasks || [],
+			stats: response.data?.stats || {
+				total: 0,
+				completed: 0,
+				progress_percentage: 0,
+			},
+		},
+	};
+};
+
+// ============================================================================
+// New Targeted Task Query Handlers
+// ============================================================================
+
+/**
+ * Get a single task by ID with optional subtasks and milestones
+ */
+export const getTask: Handler = async (args, ctx) => {
+	const { task_id, include_subtasks, include_milestones } = parseArgs(args, getTaskSchema);
+
+	const api = getApiClient();
+	const response = await api.getTaskById(task_id, {
+		include_subtasks,
+		include_milestones,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch task' }, isError: true };
+	}
+
+	const result: Record<string, unknown> = {
+		task: response.data?.task,
+	};
+
+	if (include_subtasks && response.data?.subtasks) {
+		result.subtasks = response.data.subtasks;
+	}
+
+	if (include_milestones && response.data?.milestones) {
+		result.milestones = response.data.milestones;
+	}
+
+	return { result };
+};
+
+/**
+ * Search tasks by text query with pagination
+ */
+export const searchTasks: Handler = async (args, ctx) => {
+	const { project_id, query, status, limit, offset } = parseArgs(args, searchTasksSchema);
+
+	// Validate query length
+	if (query.length < 2) {
+		return {
+			result: {
+				error: 'query_too_short',
+				message: 'Search query must be at least 2 characters',
+			},
+		};
+	}
+
+	// Cap limit at 20, safe offset
+	const cappedLimit = Math.min(limit ?? 10, 20);
+	const safeOffset = Math.max(0, offset ?? 0);
+
+	const api = getApiClient();
+	const response = await api.searchTasks(project_id, {
+		query,
+		status: status as string[] | undefined,
+		limit: cappedLimit,
+		offset: safeOffset,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to search tasks' }, isError: true };
+	}
+
+	const tasks = response.data?.tasks || [];
+	const totalMatches = response.data?.total_matches || 0;
+
+	return {
+		result: {
+			tasks,
+			total_matches: totalMatches,
+			has_more: safeOffset + tasks.length < totalMatches,
+			offset: safeOffset,
+			limit: cappedLimit,
+		},
+	};
+};
+
+/**
+ * Get tasks filtered by priority with pagination
+ */
+export const getTasksByPriority: Handler = async (args, ctx) => {
+	const { project_id, priority, priority_max, status, limit, offset } = parseArgs(args, getTasksByPrioritySchema);
+
+	// Cap limit at 20, safe offset
+	const cappedLimit = Math.min(limit ?? 10, 20);
+	const safeOffset = Math.max(0, offset ?? 0);
+
+	const api = getApiClient();
+	const response = await api.getTasksByPriority(project_id, {
+		priority,
+		priority_max,
+		status,
+		limit: cappedLimit,
+		offset: safeOffset,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch tasks by priority' }, isError: true };
+	}
+
+	const tasks = response.data?.tasks || [];
+	const totalCount = response.data?.total_count || 0;
+
+	return {
+		result: {
+			tasks,
+			total_count: totalCount,
+			has_more: safeOffset + tasks.length < totalCount,
+			offset: safeOffset,
+			limit: cappedLimit,
+		},
+	};
+};
+
+/**
+ * Get recent tasks (newest or oldest) with pagination
+ */
+export const getRecentTasks: Handler = async (args, ctx) => {
+	const { project_id, order, status, limit, offset } = parseArgs(args, getRecentTasksSchema);
+
+	// Cap limit at 20, safe offset
+	const cappedLimit = Math.min(limit ?? 10, 20);
+	const safeOffset = Math.max(0, offset ?? 0);
+
+	const api = getApiClient();
+	const response = await api.getRecentTasks(project_id, {
+		order: order as 'newest' | 'oldest' | undefined,
+		status,
+		limit: cappedLimit,
+		offset: safeOffset,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch recent tasks' }, isError: true };
+	}
+
+	const tasks = response.data?.tasks || [];
+	const totalCount = response.data?.total_count || 0;
+
+	return {
+		result: {
+			tasks,
+			total_count: totalCount,
+			has_more: safeOffset + tasks.length < totalCount,
+			offset: safeOffset,
+			limit: cappedLimit,
+		},
+	};
+};
+
+/**
+ * Get task statistics for a project (aggregate counts only, minimal tokens)
+ */
+export const getTaskStats: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, getTaskStatsSchema);
+
+	const api = getApiClient();
+	const response = await api.getTaskStats(project_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch task stats' }, isError: true };
+	}
+
+	return {
+		result: {
+			total: response.data?.total || 0,
+			by_status: response.data?.by_status || {
+				backlog: 0,
+				pending: 0,
+				in_progress: 0,
+				completed: 0,
+				cancelled: 0,
+			},
+			by_priority: response.data?.by_priority || { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 },
+			awaiting_validation: response.data?.awaiting_validation || 0,
+			oldest_pending_days: response.data?.oldest_pending_days ?? null,
+		},
+	};
+};
+
+// ============================================================================
+// Worktree Cleanup Handlers
+// ============================================================================
+
+const getStaleWorktreesSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	hostname: { type: 'string' as const }, // Machine hostname to filter worktrees
+	limit: { type: 'number' as const, default: 20 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const clearWorktreePathSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const getStaleWorktrees: Handler = async (args, ctx) => {
+	const { project_id, hostname: providedHostname, limit, offset } = parseArgs(args, getStaleWorktreesSchema);
+
+	// Use auto-detected hostname if not provided - filters to only worktrees on THIS machine
+	const hostname = providedHostname || MACHINE_HOSTNAME;
+
+	// Cap limit to prevent context bloating
+	const cappedLimit = Math.min(limit ?? 20, 50);
+
+	const api = getApiClient();
+	const response = await api.getStaleWorktrees(project_id, { hostname, limit: cappedLimit, offset });
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get stale worktrees' }, isError: true };
+	}
+
+	const data = response.data;
+	return {
+		result: {
+			project_id: data?.project_id,
+			project_name: data?.project_name,
+			hostname_filter: data?.hostname_filter,
+			stale_worktrees: data?.stale_worktrees || [],
+			count: data?.count || 0,
+			local_count: data?.local_count || 0,
+			remote_count: data?.remote_count || 0,
+			total_count: data?.total_count || 0,
+			has_more: data?.has_more || false,
+			cleanup_instructions: data?.cleanup_instructions,
+			remote_worktree_note: data?.remote_worktree_note,
+		},
+	};
+};
+
+export const clearWorktreePath: Handler = async (args, ctx) => {
+	const { task_id } = parseArgs(args, clearWorktreePathSchema);
+
+	const api = getApiClient();
+	const response = await api.clearWorktreePath(task_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to clear worktree path' }, isError: true };
+	}
+
+	return {
+		result: {
+			success: true,
+			task_id,
+			message: 'Worktree path cleared. The worktree can now be safely removed if not already done.',
+		},
+	};
+};
+
+/**
+ * Task handlers registry
+ */
+export const taskHandlers: HandlerRegistry = {
+	// Targeted task query endpoints (token-efficient)
+	get_task: getTask,
+	search_tasks: searchTasks,
+	get_tasks_by_priority: getTasksByPriority,
+	get_recent_tasks: getRecentTasks,
+	get_task_stats: getTaskStats,
+	// Core task operations
+	get_next_task: getNextTask,
+	add_task: addTask,
+	update_task: updateTask,
+	complete_task: completeTask,
+	delete_task: deleteTask,
+	release_task: releaseTask,
+	cancel_task: cancelTask,
+	add_task_reference: addTaskReference,
+	remove_task_reference: removeTaskReference,
+	batch_update_tasks: batchUpdateTasks,
+	batch_complete_tasks: batchCompleteTasks,
+	// Subtask handlers
+	add_subtask: addSubtask,
+	get_subtasks: getSubtasks,
+	// Worktree cleanup handlers
+	get_stale_worktrees: getStaleWorktrees,
+	clear_worktree_path: clearWorktreePath,
+};