@vibescope/mcp-server 0.2.9 → 0.3.1

package/src/handlers/tasks.test.ts

@@ -1,907 +1,931 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import {
-	getNextTask,
-	addTask,
-	updateTask,
-	completeTask,
-	deleteTask,
-	addTaskReference,
-	removeTaskReference,
-	batchUpdateTasks,
-	batchCompleteTasks,
-	addSubtask,
-	getSubtasks,
-	getValidationApprovedGitInstructions,
-} from './tasks.js';
-import { ValidationError } from '../validators.js';
-import { createMockContext } from './__test-utils__.js';
-import { mockApiClient } from './__test-setup__.js';
-
-// ============================================================================
-// getNextTask Tests
-// ============================================================================
-
-describe('getNextTask', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing project_id', async () => {
-		const ctx = createMockContext();
-		await expect(getNextTask({}, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid project_id', async () => {
-		const ctx = createMockContext();
-		await expect(getNextTask({ project_id: 'invalid' }, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should return next task when available', async () => {
-		mockApiClient.getNextTask.mockResolvedValue({
-			ok: true,
-			data: {
-				task: { id: 'task-1', title: 'Next task', priority: 1 },
-				directive: 'Start working',
-			},
-		});
-
-		const ctx = createMockContext();
-		const result = await getNextTask(
-			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
-			ctx
-		);
-
-		expect(result.result.task).toMatchObject({ id: 'task-1' });
-	});
-
-	it('should return null when no tasks available', async () => {
-		mockApiClient.getNextTask.mockResolvedValue({
-			ok: true,
-			data: { task: null, message: 'No tasks available' },
-		});
-
-		const ctx = createMockContext();
-		const result = await getNextTask(
-			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
-			ctx
-		);
-
-		expect(result.result.task).toBeNull();
-	});
-
-	it('should pass session_id to API', async () => {
-		mockApiClient.getNextTask.mockResolvedValue({
-			ok: true,
-			data: { task: null },
-		});
-
-		const ctx = createMockContext({ sessionId: 'my-session' });
-		await getNextTask({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
-
-		expect(mockApiClient.getNextTask).toHaveBeenCalledWith(
-			'123e4567-e89b-12d3-a456-426614174000',
-			'my-session'
-		);
-	});
-});
-
-// ============================================================================
-// addTask Tests
-// ============================================================================
-
-describe('addTask', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing project_id', async () => {
-		const ctx = createMockContext();
-		await expect(addTask({ title: 'Test task' }, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid project_id', async () => {
-		const ctx = createMockContext();
-		await expect(
-			addTask({ project_id: 'invalid', title: 'Test task' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for missing title', async () => {
-		const ctx = createMockContext();
-		await expect(
-			addTask({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid priority', async () => {
-		const ctx = createMockContext();
-		await expect(
-			addTask({
-				project_id: '123e4567-e89b-12d3-a456-426614174000',
-				title: 'Test',
-				priority: 10,
-			}, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should add task successfully', async () => {
-		mockApiClient.createTask.mockResolvedValue({
-			ok: true,
-			data: { task_id: 'new-task-id', title: 'Test task' },
-		});
-
-		const ctx = createMockContext();
-		const result = await addTask(
-			{
-				project_id: '123e4567-e89b-12d3-a456-426614174000',
-				title: 'Test task',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			task_id: 'new-task-id',
-		});
-	});
-
-	it('should include optional fields in API call', async () => {
-		mockApiClient.createTask.mockResolvedValue({
-			ok: true,
-			data: { task_id: 'new-task-id' },
-		});
-
-		const ctx = createMockContext();
-		await addTask(
-			{
-				project_id: '123e4567-e89b-12d3-a456-426614174000',
-				title: 'Test task',
-				description: 'A description',
-				priority: 2,
-				estimated_minutes: 30,
-				blocking: true,
-			},
-			ctx
-		);
-
-		expect(mockApiClient.createTask).toHaveBeenCalledWith(
-			'123e4567-e89b-12d3-a456-426614174000',
-			expect.objectContaining({
-				title: 'Test task',
-				description: 'A description',
-				priority: 2,
-				estimated_minutes: 30,
-				blocking: true,
-			})
-		);
-	});
-});
-
-// ============================================================================
-// updateTask Tests
-// ============================================================================
-
-describe('updateTask', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing task_id', async () => {
-		const ctx = createMockContext();
-		await expect(updateTask({ status: 'in_progress' }, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid task_id', async () => {
-		const ctx = createMockContext();
-		await expect(
-			updateTask({ task_id: 'invalid', status: 'in_progress' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid status', async () => {
-		const ctx = createMockContext();
-		await expect(
-			updateTask({
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				status: 'invalid',
-			}, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid priority', async () => {
-		const ctx = createMockContext();
-		await expect(
-			updateTask({
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				priority: 0,
-			}, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid progress_percentage', async () => {
-		const ctx = createMockContext();
-		await expect(
-			updateTask({
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				progress_percentage: 150,
-			}, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should update task successfully', async () => {
-		mockApiClient.updateTask.mockResolvedValue({
-			ok: true,
-			data: { success: true },
-		});
-
-		const ctx = createMockContext();
-		const result = await updateTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				status: 'in_progress',
-				git_branch: 'feature/test-branch',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({ success: true });
-	});
-
-	it('should handle agent_task_limit error', async () => {
-		mockApiClient.updateTask.mockResolvedValue({
-			ok: false,
-			error: 'agent_task_limit: Agent already has a task in progress',
-		});
-
-		const ctx = createMockContext();
-		const result = await updateTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				status: 'in_progress',
-				git_branch: 'feature/test-branch',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			error: 'agent_task_limit',
-		});
-	});
-
-	it('should handle task_claimed error', async () => {
-		mockApiClient.updateTask.mockResolvedValue({
-			ok: false,
-			error: 'task_claimed: Task is being worked on by another agent',
-		});
-
-		const ctx = createMockContext();
-		const result = await updateTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				status: 'in_progress',
-				git_branch: 'feature/test-branch',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			error: 'task_claimed',
-		});
-	});
-
-	it('should return error when setting in_progress without git_branch', async () => {
-		const ctx = createMockContext();
-		const result = await updateTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				status: 'in_progress',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			error: 'worktree_required',
-			message: expect.stringContaining('git_branch is required'),
-			hint: expect.stringContaining('Create a worktree'),
-		});
-		// Should NOT call the API when worktree requirement fails
-		expect(mockApiClient.updateTask).not.toHaveBeenCalled();
-	});
-
-	it('should return worktree_example in error response', async () => {
-		const ctx = createMockContext();
-		const result = await updateTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				status: 'in_progress',
-			},
-			ctx
-		);
-
-		expect(result.result).toHaveProperty('worktree_example');
-		expect(result.result.worktree_example).toHaveProperty('command');
-		expect(result.result.worktree_example).toHaveProperty('then');
-		expect(result.result).toHaveProperty('skip_option');
-	});
-
-	it('should succeed when setting in_progress with git_branch', async () => {
-		mockApiClient.updateTask.mockResolvedValue({
-			ok: true,
-			data: { success: true },
-		});
-
-		const ctx = createMockContext();
-		const result = await updateTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				status: 'in_progress',
-				git_branch: 'feature/my-task',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({ success: true });
-		expect(result.result).not.toHaveProperty('error');
-		expect(mockApiClient.updateTask).toHaveBeenCalled();
-	});
-
-	it('should succeed when using skip_worktree_requirement without git_branch', async () => {
-		mockApiClient.updateTask.mockResolvedValue({
-			ok: true,
-			data: { success: true },
-		});
-
-		const ctx = createMockContext();
-		const result = await updateTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				status: 'in_progress',
-				skip_worktree_requirement: true,
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({ success: true });
-		expect(result.result).not.toHaveProperty('error');
-		expect(mockApiClient.updateTask).toHaveBeenCalled();
-	});
-
-	it('should not require git_branch when updating status other than in_progress', async () => {
-		mockApiClient.updateTask.mockResolvedValue({
-			ok: true,
-			data: { success: true },
-		});
-
-		const ctx = createMockContext();
-		const result = await updateTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				status: 'completed',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({ success: true });
-		expect(result.result).not.toHaveProperty('error');
-		expect(mockApiClient.updateTask).toHaveBeenCalled();
-	});
-
-	it('should not require git_branch when updating progress only', async () => {
-		mockApiClient.updateTask.mockResolvedValue({
-			ok: true,
-			data: { success: true },
-		});
-
-		const ctx = createMockContext();
-		const result = await updateTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				progress_percentage: 50,
-				progress_note: 'Halfway done',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({ success: true });
-		expect(mockApiClient.updateTask).toHaveBeenCalled();
-	});
-});
-
-// ============================================================================
-// completeTask Tests
-// ============================================================================
-
-describe('completeTask', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing task_id', async () => {
-		const ctx = createMockContext();
-		await expect(completeTask({}, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid task_id', async () => {
-		const ctx = createMockContext();
-		await expect(
-			completeTask({ task_id: 'invalid' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should complete task successfully', async () => {
-		mockApiClient.completeTask.mockResolvedValue({
-			ok: true,
-			data: {
-				success: true,
-				directive: 'Start next task',
-				auto_continue: true,
-				completed_task_id: '123e4567-e89b-12d3-a456-426614174000',
-				next_task: { id: 'task-2', title: 'Next task' },
-			},
-		});
-
-		const ctx = createMockContext();
-		const result = await completeTask(
-			{ task_id: '123e4567-e89b-12d3-a456-426614174000' },
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			auto_continue: true,
-			next_task: expect.any(Object),
-		});
-	});
-
-	it('should include summary in API call', async () => {
-		mockApiClient.completeTask.mockResolvedValue({
-			ok: true,
-			data: { success: true },
-		});
-
-		const ctx = createMockContext();
-		await completeTask(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				summary: 'Completed the feature',
-			},
-			ctx
-		);
-
-		expect(mockApiClient.completeTask).toHaveBeenCalledWith(
-			'123e4567-e89b-12d3-a456-426614174000',
-			expect.objectContaining({ summary: 'Completed the feature' })
-		);
-	});
-
-	it('should return error when API returns error', async () => {
-		mockApiClient.completeTask.mockResolvedValue({
-			ok: false,
-			error: 'Task not found',
-		});
-
-		const ctx = createMockContext();
-		const result = await completeTask({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
-
-		expect(result.isError).toBe(true);
-		expect(result.result).toMatchObject({
-			error: 'Task not found',
-		});
-	});
-});
-
-// ============================================================================
-// deleteTask Tests
-// ============================================================================
-
-describe('deleteTask', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing task_id', async () => {
-		const ctx = createMockContext();
-		await expect(deleteTask({}, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid task_id', async () => {
-		const ctx = createMockContext();
-		await expect(deleteTask({ task_id: 'invalid' }, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should delete task successfully', async () => {
-		mockApiClient.deleteTask.mockResolvedValue({
-			ok: true,
-			data: { success: true },
-		});
-
-		const ctx = createMockContext();
-		const result = await deleteTask(
-			{ task_id: '123e4567-e89b-12d3-a456-426614174000' },
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			deleted_id: '123e4567-e89b-12d3-a456-426614174000',
-		});
-	});
-});
-
-// ============================================================================
-// addTaskReference Tests
-// ============================================================================
-
-describe('addTaskReference', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing task_id', async () => {
-		const ctx = createMockContext();
-		await expect(
-			addTaskReference({ url: 'https://example.com' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for missing url', async () => {
-		const ctx = createMockContext();
-		await expect(
-			addTaskReference({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should add reference successfully', async () => {
-		mockApiClient.addTaskReference.mockResolvedValue({
-			ok: true,
-			data: { reference: { url: 'https://example.com', label: 'Test' } },
-		});
-
-		const ctx = createMockContext();
-		const result = await addTaskReference(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				url: 'https://example.com',
-				label: 'Test',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			reference: expect.any(Object),
-		});
-	});
-
-	it('should handle duplicate reference error', async () => {
-		mockApiClient.addTaskReference.mockResolvedValue({
-			ok: false,
-			error: 'Reference already exists',
-		});
-
-		const ctx = createMockContext();
-		const result = await addTaskReference(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				url: 'https://example.com',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: false,
-			error: expect.stringContaining('already exists'),
-		});
-	});
-});
-
-// ============================================================================
-// removeTaskReference Tests
-// ============================================================================
-
-describe('removeTaskReference', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing task_id', async () => {
-		const ctx = createMockContext();
-		await expect(
-			removeTaskReference({ url: 'https://example.com' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for missing url', async () => {
-		const ctx = createMockContext();
-		await expect(
-			removeTaskReference({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should remove reference successfully', async () => {
-		mockApiClient.removeTaskReference.mockResolvedValue({
-			ok: true,
-			data: { success: true },
-		});
-
-		const ctx = createMockContext();
-		const result = await removeTaskReference(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				url: 'https://example.com',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({ success: true });
-	});
-
-	it('should handle not found error', async () => {
-		mockApiClient.removeTaskReference.mockResolvedValue({
-			ok: false,
-			error: 'Reference not found',
-		});
-
-		const ctx = createMockContext();
-		const result = await removeTaskReference(
-			{
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				url: 'https://example.com',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: false,
-			error: expect.stringContaining('not found'),
-		});
-	});
-});
-
-// ============================================================================
-// batchUpdateTasks Tests
-// ============================================================================
-
-describe('batchUpdateTasks', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing updates array', async () => {
-		const ctx = createMockContext();
-		await expect(batchUpdateTasks({}, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for empty updates array', async () => {
-		const ctx = createMockContext();
-		await expect(batchUpdateTasks({ updates: [] }, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for too many updates', async () => {
-		const ctx = createMockContext();
-		const updates = Array(51).fill({
-			task_id: '123e4567-e89b-12d3-a456-426614174000',
-		});
-		await expect(batchUpdateTasks({ updates }, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should batch update tasks successfully', async () => {
-		mockApiClient.batchUpdateTasks.mockResolvedValue({
-			ok: true,
-			data: { success: true, updated_count: 2 },
-		});
-
-		const ctx = createMockContext();
-		const result = await batchUpdateTasks(
-			{
-				updates: [
-					{ task_id: '123e4567-e89b-12d3-a456-426614174000', status: 'in_progress' },
-					{ task_id: '123e4567-e89b-12d3-a456-426614174001', status: 'completed' },
-				],
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			total: 2,
-			succeeded: 2,
-		});
-	});
-});
-
-// ============================================================================
-// batchCompleteTasks Tests
-// ============================================================================
-
-describe('batchCompleteTasks', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing completions array', async () => {
-		const ctx = createMockContext();
-		await expect(batchCompleteTasks({}, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for empty completions array', async () => {
-		const ctx = createMockContext();
-		await expect(batchCompleteTasks({ completions: [] }, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should batch complete tasks successfully', async () => {
-		mockApiClient.batchCompleteTasks.mockResolvedValue({
-			ok: true,
-			data: {
-				success: true,
-				completed_count: 2,
-				next_task: { id: 'task-3', title: 'Next' },
-			},
-		});
-
-		const ctx = createMockContext();
-		const result = await batchCompleteTasks(
-			{
-				completions: [
-					{ task_id: '123e4567-e89b-12d3-a456-426614174000' },
-					{ task_id: '123e4567-e89b-12d3-a456-426614174001', summary: 'Done' },
-				],
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			total: 2,
-			succeeded: 2,
-			next_task: expect.any(Object),
-		});
-	});
-});
-
-// ============================================================================
-// addSubtask Tests
-// ============================================================================
-
-describe('addSubtask', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing parent_task_id', async () => {
-		const ctx = createMockContext();
-		await expect(addSubtask({ title: 'Subtask' }, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for missing title', async () => {
-		const ctx = createMockContext();
-		await expect(
-			addSubtask({ parent_task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should add subtask successfully', async () => {
-		mockApiClient.addSubtask.mockResolvedValue({
-			ok: true,
-			data: {
-				subtask_id: 'subtask-1',
-				parent_task_id: '123e4567-e89b-12d3-a456-426614174000',
-			},
-		});
-
-		const ctx = createMockContext();
-		const result = await addSubtask(
-			{
-				parent_task_id: '123e4567-e89b-12d3-a456-426614174000',
-				title: 'Subtask 1',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: true,
-			subtask_id: 'subtask-1',
-		});
-	});
-
-	it('should handle nested subtask error', async () => {
-		mockApiClient.addSubtask.mockResolvedValue({
-			ok: false,
-			error: 'Cannot create subtask of a subtask',
-		});
-
-		const ctx = createMockContext();
-		const result = await addSubtask(
-			{
-				parent_task_id: '123e4567-e89b-12d3-a456-426614174000',
-				title: 'Nested subtask',
-			},
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			success: false,
-			error: 'Cannot create subtask of a subtask',
-		});
-	});
-});
-
-// ============================================================================
-// getSubtasks Tests
-// ============================================================================
-
-describe('getSubtasks', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing parent_task_id', async () => {
-		const ctx = createMockContext();
-		await expect(getSubtasks({}, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid parent_task_id', async () => {
-		const ctx = createMockContext();
-		await expect(
-			getSubtasks({ parent_task_id: 'invalid' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should return subtasks successfully', async () => {
-		mockApiClient.getSubtasks.mockResolvedValue({
-			ok: true,
-			data: {
-				subtasks: [
-					{ id: 'sub-1', title: 'Subtask 1', status: 'pending' },
-					{ id: 'sub-2', title: 'Subtask 2', status: 'completed' },
-				],
-				stats: { total: 2, completed: 1, progress_percentage: 50 },
-			},
-		});
-
-		const ctx = createMockContext();
-		const result = await getSubtasks(
-			{ parent_task_id: '123e4567-e89b-12d3-a456-426614174000' },
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			subtasks: expect.any(Array),
-			stats: expect.objectContaining({ total: 2 }),
-		});
-	});
-});
-
-// ============================================================================
-// getValidationApprovedGitInstructions Tests
-// ============================================================================
-
-describe('getValidationApprovedGitInstructions', () => {
-	it('should return undefined for none workflow', () => {
-		const result = getValidationApprovedGitInstructions(
-			{ git_workflow: 'none', git_main_branch: 'main' },
-			'feature/test'
-		);
-		expect(result).toBeUndefined();
-	});
-
-	it('should return undefined for trunk-based workflow', () => {
-		const result = getValidationApprovedGitInstructions(
-			{ git_workflow: 'trunk-based', git_main_branch: 'main' },
-			'feature/test'
-		);
-		expect(result).toBeUndefined();
-	});
-
-	it('should return undefined when no task branch', () => {
-		const result = getValidationApprovedGitInstructions(
-			{ git_workflow: 'github-flow', git_main_branch: 'main' },
-			undefined
-		);
-		expect(result).toBeUndefined();
-	});
-
-	it('should return merge instructions for github-flow', () => {
-		const result = getValidationApprovedGitInstructions(
-			{ git_workflow: 'github-flow', git_main_branch: 'main' },
-			'feature/test'
-		);
-
-		expect(result).toMatchObject({
-			target_branch: 'main',
-			feature_branch: 'feature/test',
-			steps: expect.any(Array),
-			cleanup: expect.any(Array),
-		});
-	});
-
-	it('should return merge instructions for git-flow with develop', () => {
-		const result = getValidationApprovedGitInstructions(
-			{ git_workflow: 'git-flow', git_main_branch: 'main', git_develop_branch: 'develop' },
-			'feature/test'
-		);
-
-		expect(result).toMatchObject({
-			target_branch: 'develop',
-			feature_branch: 'feature/test',
-		});
-	});
-});
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+	getNextTask,
+	addTask,
+	updateTask,
+	completeTask,
+	deleteTask,
+	addTaskReference,
+	removeTaskReference,
+	batchUpdateTasks,
+	batchCompleteTasks,
+	addSubtask,
+	getSubtasks,
+	getValidationApprovedGitInstructions,
+} from './tasks.js';
+import { ValidationError } from '../validators.js';
+import { createMockContext } from './__test-utils__.js';
+import { mockApiClient } from './__test-setup__.js';
+
+// ============================================================================
+// getNextTask Tests
+// ============================================================================
+
+describe('getNextTask', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+		await expect(getNextTask({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id', async () => {
+		const ctx = createMockContext();
+		await expect(getNextTask({ project_id: 'invalid' }, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should return next task when available', async () => {
+		mockApiClient.getNextTask.mockResolvedValue({
+			ok: true,
+			data: {
+				task: { id: 'task-1', title: 'Next task', priority: 1 },
+				directive: 'Start working',
+			},
+		});
+
+		const ctx = createMockContext();
+		const result = await getNextTask(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result.task).toMatchObject({ id: 'task-1' });
+	});
+
+	it('should return null when no tasks available', async () => {
+		mockApiClient.getNextTask.mockResolvedValue({
+			ok: true,
+			data: { task: null, message: 'No tasks available' },
+		});
+
+		const ctx = createMockContext();
+		const result = await getNextTask(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result.task).toBeNull();
+	});
+
+	it('should pass session_id to API', async () => {
+		mockApiClient.getNextTask.mockResolvedValue({
+			ok: true,
+			data: { task: null },
+		});
+
+		const ctx = createMockContext({ sessionId: 'my-session' });
+		await getNextTask({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(mockApiClient.getNextTask).toHaveBeenCalledWith(
+			'123e4567-e89b-12d3-a456-426614174000',
+			'my-session'
+		);
+	});
+});
+
+// ============================================================================
+// addTask Tests
+// ============================================================================
+
+describe('addTask', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+		await expect(addTask({ title: 'Test task' }, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id', async () => {
+		const ctx = createMockContext();
+		await expect(
+			addTask({ project_id: 'invalid', title: 'Test task' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing title', async () => {
+		const ctx = createMockContext();
+		await expect(
+			addTask({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid priority', async () => {
+		const ctx = createMockContext();
+		await expect(
+			addTask({
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				title: 'Test',
+				priority: 10,
+			}, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should add task successfully', async () => {
+		mockApiClient.createTask.mockResolvedValue({
+			ok: true,
+			data: { task_id: 'new-task-id', title: 'Test task' },
+		});
+
+		const ctx = createMockContext();
+		const result = await addTask(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				title: 'Test task',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			task_id: 'new-task-id',
+		});
+	});
+
+	it('should include optional fields in API call', async () => {
+		mockApiClient.createTask.mockResolvedValue({
+			ok: true,
+			data: { task_id: 'new-task-id' },
+		});
+
+		const ctx = createMockContext();
+		await addTask(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				title: 'Test task',
+				description: 'A description',
+				priority: 2,
+				estimated_minutes: 30,
+				blocking: true,
+			},
+			ctx
+		);
+
+		expect(mockApiClient.createTask).toHaveBeenCalledWith(
+			'123e4567-e89b-12d3-a456-426614174000',
+			expect.objectContaining({
+				title: 'Test task',
+				description: 'A description',
+				priority: 2,
+				estimated_minutes: 30,
+				blocking: true,
+			})
+		);
+	});
+});
+
+// ============================================================================
+// updateTask Tests
+// ============================================================================
+
+describe('updateTask', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing task_id', async () => {
+		const ctx = createMockContext();
+		await expect(updateTask({ status: 'in_progress' }, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid task_id', async () => {
+		const ctx = createMockContext();
+		await expect(
+			updateTask({ task_id: 'invalid', status: 'in_progress' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid status', async () => {
+		const ctx = createMockContext();
+		await expect(
+			updateTask({
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'invalid',
+			}, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid priority', async () => {
+		const ctx = createMockContext();
+		await expect(
+			updateTask({
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				priority: 0,
+			}, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid progress_percentage', async () => {
+		const ctx = createMockContext();
+		await expect(
+			updateTask({
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				progress_percentage: 150,
+			}, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should update task successfully', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+				git_branch: 'feature/test-branch',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+	});
+
+	it('should handle agent_task_limit error', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: false,
+			error: 'agent_task_limit: Agent already has a task in progress',
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+				git_branch: 'feature/test-branch',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'agent_task_limit',
+		});
+	});
+
+	it('should handle task_claimed error', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: false,
+			error: 'task_claimed: Task is being worked on by another agent',
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+				git_branch: 'feature/test-branch',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'task_already_claimed',
+		});
+	});
+
+	it('should return error when setting in_progress without git_branch', async () => {
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'worktree_required',
+			message: expect.stringContaining('git_branch is required'),
+			hint: expect.stringContaining('Create a worktree'),
+		});
+		// Should NOT call the API when worktree requirement fails
+		expect(mockApiClient.updateTask).not.toHaveBeenCalled();
+	});
+
+	it('should return worktree_example in error response', async () => {
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+			},
+			ctx
+		);
+
+		expect(result.result).toHaveProperty('worktree_example');
+		expect(result.result.worktree_example).toHaveProperty('command');
+		expect(result.result.worktree_example).toHaveProperty('then');
+		expect(result.result).toHaveProperty('skip_option');
+	});
+
+	it('should succeed when setting in_progress with git_branch', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+				git_branch: 'feature/my-task',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+		expect(result.result).not.toHaveProperty('error');
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
+	});
+
+	it('should succeed when using skip_worktree_requirement without git_branch', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+				skip_worktree_requirement: true,
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+		expect(result.result).not.toHaveProperty('error');
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
+	});
+
+	it('should not require git_branch when updating status other than in_progress', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'completed',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+		expect(result.result).not.toHaveProperty('error');
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
+	});
+
+	it('should not require git_branch when updating progress only', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				progress_percentage: 50,
+				progress_note: 'Halfway done',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
+	});
+
+	it('should include FIX_ALREADY_EXISTS_GUIDANCE when setting status to in_progress', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+				git_branch: 'feature/my-task',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+		expect(result.result).toHaveProperty('FIX_ALREADY_EXISTS_GUIDANCE');
+		expect(result.result.FIX_ALREADY_EXISTS_GUIDANCE).toHaveProperty('message');
+		expect(result.result.FIX_ALREADY_EXISTS_GUIDANCE).toHaveProperty('steps');
+		expect(result.result.FIX_ALREADY_EXISTS_GUIDANCE).toHaveProperty('rationale');
+		expect(result.result.FIX_ALREADY_EXISTS_GUIDANCE.steps).toHaveLength(4);
+	});
+});
+
+// ============================================================================
+// completeTask Tests
+// ============================================================================
+
+describe('completeTask', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing task_id', async () => {
+		const ctx = createMockContext();
+		await expect(completeTask({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid task_id', async () => {
+		const ctx = createMockContext();
+		await expect(
+			completeTask({ task_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should complete task successfully', async () => {
+		mockApiClient.completeTask.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				directive: 'Start next task',
+				auto_continue: true,
+				completed_task_id: '123e4567-e89b-12d3-a456-426614174000',
+				next_task: { id: 'task-2', title: 'Next task' },
+			},
+		});
+
+		const ctx = createMockContext();
+		const result = await completeTask(
+			{ task_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			auto_continue: true,
+			next_task: expect.any(Object),
+		});
+	});
+
+	it('should include summary in API call', async () => {
+		mockApiClient.completeTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		await completeTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				summary: 'Completed the feature',
+			},
+			ctx
+		);
+
+		expect(mockApiClient.completeTask).toHaveBeenCalledWith(
+			'123e4567-e89b-12d3-a456-426614174000',
+			expect.objectContaining({ summary: 'Completed the feature' })
+		);
+	});
+
+	it('should return error when API returns error', async () => {
+		mockApiClient.completeTask.mockResolvedValue({
+			ok: false,
+			error: 'Task not found',
+		});
+
+		const ctx = createMockContext();
+		const result = await completeTask({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Task not found',
+		});
+	});
+});
+
+// ============================================================================
+// deleteTask Tests
+// ============================================================================
+
+describe('deleteTask', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing task_id', async () => {
+		const ctx = createMockContext();
+		await expect(deleteTask({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid task_id', async () => {
+		const ctx = createMockContext();
+		await expect(deleteTask({ task_id: 'invalid' }, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should delete task successfully', async () => {
+		mockApiClient.deleteTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await deleteTask(
+			{ task_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			deleted_id: '123e4567-e89b-12d3-a456-426614174000',
+		});
+	});
+});
+
+// ============================================================================
+// addTaskReference Tests
+// ============================================================================
+
+describe('addTaskReference', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing task_id', async () => {
+		const ctx = createMockContext();
+		await expect(
+			addTaskReference({ url: 'https://example.com' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing url', async () => {
+		const ctx = createMockContext();
+		await expect(
+			addTaskReference({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should add reference successfully', async () => {
+		mockApiClient.addTaskReference.mockResolvedValue({
+			ok: true,
+			data: { reference: { url: 'https://example.com', label: 'Test' } },
+		});
+
+		const ctx = createMockContext();
+		const result = await addTaskReference(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				url: 'https://example.com',
+				label: 'Test',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			reference: expect.any(Object),
+		});
+	});
+
+	it('should handle duplicate reference error', async () => {
+		mockApiClient.addTaskReference.mockResolvedValue({
+			ok: false,
+			error: 'Reference already exists',
+		});
+
+		const ctx = createMockContext();
+		const result = await addTaskReference(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				url: 'https://example.com',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: false,
+			error: expect.stringContaining('already exists'),
+		});
+	});
+});
+
+// ============================================================================
+// removeTaskReference Tests
+// ============================================================================
+
+describe('removeTaskReference', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing task_id', async () => {
+		const ctx = createMockContext();
+		await expect(
+			removeTaskReference({ url: 'https://example.com' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing url', async () => {
+		const ctx = createMockContext();
+		await expect(
+			removeTaskReference({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should remove reference successfully', async () => {
+		mockApiClient.removeTaskReference.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await removeTaskReference(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				url: 'https://example.com',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+	});
+
+	it('should handle not found error', async () => {
+		mockApiClient.removeTaskReference.mockResolvedValue({
+			ok: false,
+			error: 'Reference not found',
+		});
+
+		const ctx = createMockContext();
+		const result = await removeTaskReference(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				url: 'https://example.com',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: false,
+			error: expect.stringContaining('not found'),
+		});
+	});
+});
+
+// ============================================================================
+// batchUpdateTasks Tests
+// ============================================================================
+
+describe('batchUpdateTasks', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing updates array', async () => {
+		const ctx = createMockContext();
+		await expect(batchUpdateTasks({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for empty updates array', async () => {
+		const ctx = createMockContext();
+		await expect(batchUpdateTasks({ updates: [] }, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for too many updates', async () => {
+		const ctx = createMockContext();
+		const updates = Array(51).fill({
+			task_id: '123e4567-e89b-12d3-a456-426614174000',
+		});
+		await expect(batchUpdateTasks({ updates }, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should batch update tasks successfully', async () => {
+		mockApiClient.batchUpdateTasks.mockResolvedValue({
+			ok: true,
+			data: { success: true, updated_count: 2 },
+		});
+
+		const ctx = createMockContext();
+		const result = await batchUpdateTasks(
+			{
+				updates: [
+					{ task_id: '123e4567-e89b-12d3-a456-426614174000', status: 'in_progress' },
+					{ task_id: '123e4567-e89b-12d3-a456-426614174001', status: 'completed' },
+				],
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			total: 2,
+			succeeded: 2,
+		});
+	});
+});
+
+// ============================================================================
+// batchCompleteTasks Tests
+// ============================================================================
+
+describe('batchCompleteTasks', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing completions array', async () => {
+		const ctx = createMockContext();
+		await expect(batchCompleteTasks({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for empty completions array', async () => {
+		const ctx = createMockContext();
+		await expect(batchCompleteTasks({ completions: [] }, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should batch complete tasks successfully', async () => {
+		mockApiClient.batchCompleteTasks.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				completed_count: 2,
+				next_task: { id: 'task-3', title: 'Next' },
+			},
+		});
+
+		const ctx = createMockContext();
+		const result = await batchCompleteTasks(
+			{
+				completions: [
+					{ task_id: '123e4567-e89b-12d3-a456-426614174000' },
+					{ task_id: '123e4567-e89b-12d3-a456-426614174001', summary: 'Done' },
+				],
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			total: 2,
+			succeeded: 2,
+			next_task: expect.any(Object),
+		});
+	});
+});
+
+// ============================================================================
+// addSubtask Tests
+// ============================================================================
+
+describe('addSubtask', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing parent_task_id', async () => {
+		const ctx = createMockContext();
+		await expect(addSubtask({ title: 'Subtask' }, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing title', async () => {
+		const ctx = createMockContext();
+		await expect(
+			addSubtask({ parent_task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should add subtask successfully', async () => {
+		mockApiClient.addSubtask.mockResolvedValue({
+			ok: true,
+			data: {
+				subtask_id: 'subtask-1',
+				parent_task_id: '123e4567-e89b-12d3-a456-426614174000',
+			},
+		});
+
+		const ctx = createMockContext();
+		const result = await addSubtask(
+			{
+				parent_task_id: '123e4567-e89b-12d3-a456-426614174000',
+				title: 'Subtask 1',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			subtask_id: 'subtask-1',
+		});
+	});
+
+	it('should handle nested subtask error', async () => {
+		mockApiClient.addSubtask.mockResolvedValue({
+			ok: false,
+			error: 'Cannot create subtask of a subtask',
+		});
+
+		const ctx = createMockContext();
+		const result = await addSubtask(
+			{
+				parent_task_id: '123e4567-e89b-12d3-a456-426614174000',
+				title: 'Nested subtask',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: false,
+			error: 'Cannot create subtask of a subtask',
+		});
+	});
+});
+
+// ============================================================================
+// getSubtasks Tests
+// ============================================================================
+
+describe('getSubtasks', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing parent_task_id', async () => {
+		const ctx = createMockContext();
+		await expect(getSubtasks({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid parent_task_id', async () => {
+		const ctx = createMockContext();
+		await expect(
+			getSubtasks({ parent_task_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should return subtasks successfully', async () => {
+		mockApiClient.getSubtasks.mockResolvedValue({
+			ok: true,
+			data: {
+				subtasks: [
+					{ id: 'sub-1', title: 'Subtask 1', status: 'pending' },
+					{ id: 'sub-2', title: 'Subtask 2', status: 'completed' },
+				],
+				stats: { total: 2, completed: 1, progress_percentage: 50 },
+			},
+		});
+
+		const ctx = createMockContext();
+		const result = await getSubtasks(
+			{ parent_task_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			subtasks: expect.any(Array),
+			stats: expect.objectContaining({ total: 2 }),
+		});
+	});
+});
+
+// ============================================================================
+// getValidationApprovedGitInstructions Tests
+// ============================================================================
+
+describe('getValidationApprovedGitInstructions', () => {
+	it('should return undefined for none workflow', () => {
+		const result = getValidationApprovedGitInstructions(
+			{ git_workflow: 'none', git_main_branch: 'main' },
+			'feature/test'
+		);
+		expect(result).toBeUndefined();
+	});
+
+	it('should return undefined for trunk-based workflow', () => {
+		const result = getValidationApprovedGitInstructions(
+			{ git_workflow: 'trunk-based', git_main_branch: 'main' },
+			'feature/test'
+		);
+		expect(result).toBeUndefined();
+	});
+
+	it('should return undefined when no task branch', () => {
+		const result = getValidationApprovedGitInstructions(
+			{ git_workflow: 'github-flow', git_main_branch: 'main' },
+			undefined
+		);
+		expect(result).toBeUndefined();
+	});
+
+	it('should return merge instructions for github-flow', () => {
+		const result = getValidationApprovedGitInstructions(
+			{ git_workflow: 'github-flow', git_main_branch: 'main' },
+			'feature/test'
+		);
+
+		expect(result).toMatchObject({
+			target_branch: 'main',
+			feature_branch: 'feature/test',
+			steps: expect.any(Array),
+			cleanup: expect.any(Array),
+		});
+	});
+
+	it('should return merge instructions for git-flow with develop', () => {
+		const result = getValidationApprovedGitInstructions(
+			{ git_workflow: 'git-flow', git_main_branch: 'main', git_develop_branch: 'develop' },
+			'feature/test'
+		);
+
+		expect(result).toMatchObject({
+			target_branch: 'develop',
+			feature_branch: 'feature/test',
+		});
+	});
+});