@cleocode/cleo 2026.4.10 → 2026.4.11

package/dist/dispatch/engines/task-engine.js

@@ -0,0 +1,1387 @@
+/**
+ * Task Engine
+ *
+ * Native TypeScript implementation of core task CRUD operations.
+ * Uses StoreProvider (via getStore()) for task/session data access,
+ * falling back to direct JSON for config and specialized operations.
+ *
+ * CRUD operations (show, list, find, exists, create, update, complete, delete, archive)
+ * delegate to src/core/tasks/*.
+ *
+ * Non-CRUD operations delegate to src/core/tasks/task-ops.ts.
+ *
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+// validation-rules.js still used by other engines; core modules handle their own validation
+// Core module imports for accessor-based operations
+import { addTask as coreAddTask, archiveTasks as coreArchiveTasks, completeTask as coreCompleteTask, deleteTask as coreDeleteTask, findTasks as coreFindTasks, listTasks as coreListTasks, showTask as coreShowTask, coreTaskAnalyze, coreTaskBatchValidate, coreTaskBlockers, coreTaskCancel, coreTaskComplexityEstimate, coreTaskDepends, coreTaskDeps, coreTaskDepsCycles, coreTaskDepsOverview, coreTaskExport, coreTaskHistory, coreTaskImport, coreTaskLint, coreTaskNext, coreTaskPromote, coreTaskRelates, coreTaskRelatesAdd, coreTaskReopen, coreTaskReorder, coreTaskReparent, coreTaskRestore, coreTaskStats, coreTaskTree, coreTaskUnarchive, updateTask as coreUpdateTask, getAccessor, predictImpact, toCompact, } from '@cleocode/core/internal';
+import { engineError } from './_error.js';
+const TASK_COMPLETE_EXIT_TO_ENGINE_CODE = {
+    4: 'E_NOT_FOUND',
+    5: 'E_DEPENDENCY_ERROR',
+    6: 'E_VALIDATION_FAILED',
+    16: 'E_HAS_CHILDREN',
+    17: 'E_TASK_COMPLETED',
+    40: 'E_VERIFICATION_INIT_FAILED',
+    44: 'E_MAX_ROUNDS_EXCEEDED',
+    45: 'E_GATE_DEPENDENCY',
+    80: 'E_LIFECYCLE_GATE_FAILED',
+};
+/**
+ * Convert a core Task to a TaskRecord for backward compatibility.
+ * TaskRecord has string-typed status/priority; Task has union types.
+ *
+ * @task T4657
+ * @epic T4654
+ */
+function taskToRecord(task) {
+    // Task union-typed fields (status, priority, origin, etc.) widen to string in TaskRecord.
+    // Some fields have structural mismatches (blockedBy: string vs string[], etc.)
+    // so we explicitly map each field rather than relying on spread.
+    return {
+        id: task.id,
+        title: task.title,
+        description: task.description ?? '',
+        status: task.status,
+        priority: task.priority,
+        type: task.type,
+        phase: task.phase,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt ?? null,
+        completedAt: task.completedAt ?? null,
+        cancelledAt: task.cancelledAt ?? null,
+        parentId: task.parentId,
+        position: task.position,
+        positionVersion: task.positionVersion,
+        depends: task.depends,
+        relates: task.relates,
+        files: task.files,
+        acceptance: task.acceptance,
+        notes: task.notes,
+        labels: task.labels,
+        size: task.size ?? null,
+        epicLifecycle: task.epicLifecycle ?? null,
+        noAutoComplete: task.noAutoComplete ?? null,
+        verification: task.verification ? { ...task.verification } : null,
+        origin: task.origin ?? null,
+        cancellationReason: task.cancellationReason,
+        blockedBy: task.blockedBy ? [task.blockedBy] : undefined,
+        pipelineStage: task.pipelineStage ?? null,
+    };
+}
+/**
+ * Convert an array of core Tasks to TaskRecords.
+ *
+ * @task T4657
+ * @epic T4654
+ */
+function tasksToRecords(tasks) {
+    return tasks.map(taskToRecord);
+}
+// loadTaskFile and saveTaskFile removed — all operations now use DataAccessor.
+// Config reads (hierarchy limits, phase meta) still use readJsonFile directly
+// since they are NOT domain data (they don't go through the accessor).
+// Priority normalization moved to core/tasks/add.ts (normalizePriority)
+// ===== Query Operations =====
+/**
+ * Get a single task by ID.
+ *
+ * @remarks
+ * Fetches the full task record from the data accessor and converts it
+ * to the backward-compatible TaskRecord format.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier (e.g. "T001")
+ * @returns EngineResult containing the task record
+ *
+ * @example
+ * ```typescript
+ * const result = await taskShow('/project', 'T42');
+ * if (result.success) console.log(result.data.task.title);
+ * ```
+ *
+ * @task T4657
+ * @epic T4654
+ */
+export async function taskShow(projectRoot, taskId) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const detail = await coreShowTask(taskId, projectRoot, accessor);
+        return { success: true, data: { task: taskToRecord(detail) } };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 4 /* NOT_FOUND */) {
+            return engineError('E_NOT_FOUND', err.message || `Task '${taskId}' not found`);
+        }
+        if (code === 2 /* INVALID_INPUT */) {
+            return engineError('E_INVALID_INPUT', err.message || 'Invalid input');
+        }
+        return engineError('E_NOT_INITIALIZED', err.message || 'Task database not initialized');
+    }
+}
+/**
+ * List tasks with optional filters.
+ *
+ * @remarks
+ * Supports filtering by parent, status, priority, type, phase, and label.
+ * When `compact` is true, returns lightweight CompactTask records.
+ * Results are paginated via `limit` and `offset` parameters.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param params - Optional filter, pagination, and format parameters
+ * @returns EngineResult with task array, total count, and filtered count
+ *
+ * @example
+ * ```typescript
+ * const result = await taskList('/project', { status: 'active', limit: 10 });
+ * ```
+ *
+ * @task T4657
+ * @epic T4654
+ */
+export async function taskList(projectRoot, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await coreListTasks({
+            parentId: params?.parent ?? undefined,
+            status: params?.status,
+            priority: params?.priority,
+            type: params?.type,
+            phase: params?.phase,
+            label: params?.label,
+            children: params?.children,
+            limit: params?.limit,
+            offset: params?.offset,
+        }, projectRoot, accessor);
+        const tasks = params?.compact
+            ? result.tasks.map((t) => toCompact(t))
+            : tasksToRecords(result.tasks);
+        if (params?.compact) {
+            return {
+                success: true,
+                data: { tasks, total: result.total, filtered: result.filtered },
+                page: result.page,
+            };
+        }
+        return {
+            success: true,
+            data: { tasks, total: result.total, filtered: result.filtered },
+            page: result.page,
+        };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 4)
+            return engineError('E_NOT_FOUND', err.message || 'Task not found');
+        if (code === 2)
+            return engineError('E_INVALID_INPUT', err.message || 'Invalid input');
+        return engineError('E_NOT_INITIALIZED', err.message || 'Task database not initialized');
+    }
+}
+/**
+ * Fuzzy search tasks by title/description/ID.
+ *
+ * @remarks
+ * Returns minimal task records to keep context consumption low.
+ * Supports exact matching, status filtering, and archive inclusion.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param query - Search string to match against title, description, or ID
+ * @param limit - Maximum number of results (defaults to 20)
+ * @param options - Additional search options
+ * @returns EngineResult with matching tasks and total count
+ *
+ * @example
+ * ```typescript
+ * const result = await taskFind('/project', 'authentication', 10);
+ * ```
+ *
+ * @task T4657
+ * @epic T4654
+ */
+export async function taskFind(projectRoot, query, limit, options) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const findResult = await coreFindTasks({
+            query,
+            id: options?.id,
+            exact: options?.exact,
+            status: options?.status,
+            includeArchive: options?.includeArchive,
+            limit: limit ?? 20,
+            offset: options?.offset,
+        }, projectRoot, accessor);
+        const results = findResult.results.map((r) => ({
+            id: r.id,
+            title: r.title,
+            status: r.status,
+            priority: r.priority,
+            parentId: r.parentId,
+        }));
+        return { success: true, data: { results, total: results.length } };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 4)
+            return engineError('E_NOT_FOUND', err.message || 'Task not found');
+        if (code === 2)
+            return engineError('E_INVALID_INPUT', err.message || 'Invalid input');
+        return engineError('E_NOT_INITIALIZED', err.message || 'Task database not initialized');
+    }
+}
+/**
+ * Check if a task exists.
+ *
+ * @remarks
+ * Returns `{ exists: true }` if the task is found, `{ exists: false }` otherwise.
+ * Never fails -- catches all errors and returns false.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to check
+ * @returns EngineResult with exists flag and the queried taskId
+ *
+ * @example
+ * ```typescript
+ * const result = await taskExists('/project', 'T42');
+ * if (result.success && result.data.exists) { console.log('exists'); }
+ * ```
+ *
+ *
+@task
+T4657
+ * @epic T4654
+ */
+export async function taskExists(projectRoot, taskId) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const exists = await accessor.taskExists(taskId);
+        return { success: true, data: { exists, taskId } };
+    }
+    catch {
+        return { success: true, data: { exists: false, taskId } };
+    }
+}
+// ===== Mutate Operations =====
+/**
+ * Create a new task.
+ *
+ * @remarks
+ * Validates hierarchy depth, sibling limits, parent type, and circular
+ * references before creating the task. Supports dry-run mode for preview.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param params - Task creation parameters
+ * @returns EngineResult with the created task record and duplicate flag
+ *
+ * @example
+ * ```typescript
+ * const result = await taskCreate('/project', {
+ *   title: 'Implement auth',
+ *   description: 'Add JWT-based authentication',
+ *   priority: 'high',
+ * });
+ * ```
+ */
+export async function taskCreate(projectRoot, params) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await coreAddTask({
+            title: params.title,
+            description: params.description,
+            parentId: params.parent || null,
+            depends: params.depends,
+            priority: params.priority || 'medium',
+            labels: params.labels,
+            type: params.type || undefined,
+            phase: params.phase,
+            size: params.size,
+            acceptance: params.acceptance,
+            notes: params.notes,
+            files: params.files,
+            dryRun: params.dryRun,
+        }, projectRoot, accessor);
+        return {
+            success: true,
+            data: {
+                task: taskToRecord(result.task),
+                duplicate: result.duplicate ?? false,
+                dryRun: params.dryRun,
+            },
+        };
+    }
+    catch (err) {
+        const cleoErr = err;
+        // Map CleoError exit codes to engine error codes (see src/types/exit-codes.ts)
+        if (cleoErr.code === 10 /* PARENT_NOT_FOUND */) {
+            return engineError('E_PARENT_NOT_FOUND', cleoErr.message ?? 'Parent task not found');
+        }
+        if (cleoErr.code === 11 /* DEPTH_EXCEEDED */) {
+            return engineError('E_DEPTH_EXCEEDED', cleoErr.message ?? 'Max hierarchy depth exceeded');
+        }
+        if (cleoErr.code === 12 /* SIBLING_LIMIT */) {
+            return engineError('E_SIBLING_LIMIT', cleoErr.message ?? 'Max siblings exceeded');
+        }
+        if (cleoErr.code === 13 /* INVALID_PARENT_TYPE */) {
+            return engineError('E_INVALID_PARENT', cleoErr.message ?? 'Invalid parent type');
+        }
+        if (cleoErr.code === 14 /* CIRCULAR_REFERENCE */) {
+            return engineError('E_CIRCULAR_REFERENCE', cleoErr.message ?? 'Circular reference detected');
+        }
+        if (cleoErr.code === 6 /* VALIDATION_ERROR */ || cleoErr.code === 2 /* INVALID_INPUT */) {
+            return engineError('E_VALIDATION_FAILED', cleoErr.message ?? 'Validation failed');
+        }
+        if (cleoErr.code === 4 /* NOT_FOUND */) {
+            return engineError('E_NOT_FOUND', cleoErr.message ?? 'Task not found');
+        }
+        return engineError('E_NOT_INITIALIZED', cleoErr.message ?? 'Task database not initialized');
+    }
+}
+/**
+ * Update a task's fields.
+ *
+ * @remarks
+ * Supports atomic label and dependency operations via addLabels/removeLabels
+ * and addDepends/removeDepends. Returns the updated task and a list of
+ * changed fields.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to update
+ * @param updates - Fields to update (only provided fields are changed)
+ * @returns EngineResult with the updated task record and list of changes
+ *
+ * @example
+ * ```typescript
+ * const result = await taskUpdate('/project', 'T42', { status: 'active' });
+ * ```
+ */
+export async function taskUpdate(projectRoot, taskId, updates) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await coreUpdateTask({
+            taskId,
+            title: updates.title,
+            description: updates.description,
+            status: updates.status,
+            priority: updates.priority,
+            notes: updates.notes,
+            labels: updates.labels,
+            addLabels: updates.addLabels,
+            removeLabels: updates.removeLabels,
+            depends: updates.depends,
+            addDepends: updates.addDepends,
+            removeDepends: updates.removeDepends,
+            acceptance: updates.acceptance,
+            parentId: updates.parent,
+            type: updates.type,
+            size: updates.size,
+        }, projectRoot, accessor);
+        return { success: true, data: { task: taskToRecord(result.task), changes: result.changes } };
+    }
+    catch (err) {
+        const cleoErr = err;
+        if (cleoErr.code === 4 /* NOT_FOUND */) {
+            return engineError('E_NOT_FOUND', cleoErr.message ?? `Task '${taskId}' not found`);
+        }
+        if (cleoErr.code === 6 /* VALIDATION_ERROR */ || cleoErr.code === 2 /* INVALID_INPUT */) {
+            return engineError('E_VALIDATION_FAILED', cleoErr.message ?? 'Validation failed');
+        }
+        if (cleoErr.code === 102 /* NO_CHANGE */) {
+            return engineError('E_NO_CHANGE', cleoErr.message ?? 'No changes specified');
+        }
+        return engineError('E_NOT_INITIALIZED', cleoErr.message ?? 'Task database not initialized');
+    }
+}
+/**
+ * Complete a task (set status to done).
+ *
+ * @remarks
+ * May trigger auto-completion of parent tasks and unblocking of dependent
+ * tasks. Maps core exit codes to engine error codes for structured error reporting.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to complete
+ * @param notes - Optional completion notes
+ * @returns EngineResult with the completed task, auto-completed parents, and unblocked tasks
+ *
+ * @example
+ * ```typescript
+ * const result = await taskComplete('/project', 'T42', 'All tests passing');
+ * ```
+ */
+export async function taskComplete(projectRoot, taskId, notes) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await coreCompleteTask({ taskId, notes }, projectRoot, accessor);
+        return {
+            success: true,
+            data: {
+                task: result.task,
+                ...(result.autoCompleted && { autoCompleted: result.autoCompleted }),
+                ...(result.unblockedTasks && { unblockedTasks: result.unblockedTasks }),
+            },
+        };
+    }
+    catch (err) {
+        const cleoErr = err;
+        const message = cleoErr.message ?? 'Failed to complete task';
+        if (typeof cleoErr.code === 'number') {
+            const mappedCode = TASK_COMPLETE_EXIT_TO_ENGINE_CODE[cleoErr.code];
+            if (mappedCode) {
+                return engineError(mappedCode, message);
+            }
+        }
+        return engineError('E_INTERNAL', message);
+    }
+}
+/**
+ * Delete a task.
+ *
+ * @remarks
+ * When `force` is true, cascade-deletes child tasks. Otherwise, returns
+ * E_HAS_CHILDREN if the task has children.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to delete
+ * @param force - When true, enables cascade deletion of children
+ * @returns EngineResult with the deleted task and optional cascade info
+ *
+ * @example
+ * ```typescript
+ * const result = await taskDelete('/project', 'T42', true);
+ * ```
+ */
+export async function taskDelete(projectRoot, taskId, force) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await coreDeleteTask({
+            taskId,
+            force: force ?? false,
+            cascade: force ?? false,
+        }, projectRoot, accessor);
+        return {
+            success: true,
+            data: {
+                deletedTask: taskToRecord(result.deletedTask),
+                deleted: true,
+                cascadeDeleted: result.cascadeDeleted,
+            },
+        };
+    }
+    catch (err) {
+        const cleoErr = err;
+        if (cleoErr.code === 4 /* NOT_FOUND */) {
+            return engineError('E_NOT_FOUND', cleoErr.message ?? `Task '${taskId}' not found`);
+        }
+        if (cleoErr.code === 16 /* HAS_CHILDREN */) {
+            return engineError('E_HAS_CHILDREN', cleoErr.message ?? `Task '${taskId}' has children`);
+        }
+        return engineError('E_NOT_INITIALIZED', cleoErr.message ?? 'Task database not initialized');
+    }
+}
+/**
+ * Archive completed tasks.
+ * Moves done/cancelled tasks from active task data to archive.
+ *
+ * @remarks
+ * Archives a specific task by ID, or all tasks completed before a given date.
+ * Archived tasks are no longer returned by default queries.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Optional specific task ID to archive
+ * @param before - Optional ISO date string; archives tasks completed before this date
+ * @returns EngineResult with count and list of archived task IDs
+ *
+ * @example
+ * ```typescript
+ * const result = await taskArchive('/project', undefined, '2026-01-01');
+ * ```
+ */
+export async function taskArchive(projectRoot, taskId, before) {
+    try {
+        const accessor = await getAccessor(projectRoot);
+        const result = await coreArchiveTasks({
+            taskIds: taskId ? [taskId] : undefined,
+            before,
+        }, projectRoot, accessor);
+        return {
+            success: true,
+            data: {
+                archivedCount: result.archived.length,
+                archivedTasks: result.archived.map((id) => ({ id })),
+            },
+        };
+    }
+    catch (err) {
+        const cleoErr = err;
+        if (cleoErr.code === 4 /* NOT_FOUND */) {
+            return engineError('E_NOT_FOUND', cleoErr.message ?? 'Task not found');
+        }
+        return engineError('E_NOT_INITIALIZED', cleoErr.message ?? 'Task database not initialized');
+    }
+}
+// ===== Non-CRUD Operations (delegated to core/tasks/task-ops.ts) =====
+/**
+ * Suggest next task to work on based on priority, phase alignment, age, and dependency readiness.
+ *
+ * @remarks
+ * Scores all pending tasks and returns ranked suggestions. When `explain`
+ * is true, includes per-task scoring reasons in the response.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param params - Optional count limit and explain flag
+ * @returns EngineResult with scored suggestions and total candidate count
+ *
+ * @example
+ * ```typescript
+ * const result = await taskNext('/project', { count: 3, explain: true });
+ * ```
+ *
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskNext(projectRoot, params) {
+    try {
+        const result = await coreTaskNext(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Show blocked tasks and analyze blocking chains.
+ *
+ * @remarks
+ * Identifies all blocked tasks, traces their blocking chains, and highlights
+ * critical blockers (tasks that block the most other tasks).
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param params - Optional analysis and limit parameters
+ * @returns EngineResult with blocked tasks, critical blockers, and summary
+ *
+ * @example
+ * ```typescript
+ * const result = await taskBlockers('/project', { analyze: true });
+ * ```
+ *
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskBlockers(projectRoot, params) {
+    try {
+        const result = await coreTaskBlockers(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Build hierarchy tree.
+ *
+ * @remarks
+ * Returns a tree structure of tasks rooted at the given task ID, or
+ * the full project tree when no task ID is specified.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Optional root task ID for subtree
+ * @returns EngineResult with the hierarchical tree data
+ *
+ * @example
+ * ```typescript
+ * const result = await taskTree('/project', 'T1');
+ * ```
+ *
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskTree(projectRoot, taskId) {
+    try {
+        const result = await coreTaskTree(projectRoot, taskId);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Show dependencies for a task - both what it depends on and what depends on it.
+ *
+ * @remarks
+ * Returns bidirectional dependency information including unresolved deps
+ * and a ready flag indicating whether all dependencies are satisfied.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to inspect
+ * @returns EngineResult with dependency information in both directions
+ *
+ * @example
+ * ```typescript
+ * const result = await taskDeps('/project', 'T42');
+ * ```
+ *
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskDeps(projectRoot, taskId) {
+    try {
+        const result = await coreTaskDeps(projectRoot, taskId);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Show task relations (existing relates entries).
+ *
+ * @remarks
+ * Lists all `relates` entries for a given task, including the relationship
+ * type and optional reason.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to inspect
+ * @returns EngineResult with relations array and count
+ *
+ * @example
+ * ```typescript
+ * const result = await taskRelates('/project', 'T42');
+ * ```
+ *
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskRelates(projectRoot, taskId) {
+    try {
+        const result = await coreTaskRelates(projectRoot, taskId);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_GENERAL', `Failed to read task relations: ${message}`);
+    }
+}
+/**
+ * Add a relation between two tasks.
+ *
+ * @remarks
+ * Valid relation types: related, blocks, duplicates, absorbs, fixes, extends, supersedes.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Source task identifier
+ * @param relatedId - Target task identifier
+ * @param type - Relation type (e.g. "blocks", "related")
+ * @param reason - Optional explanation for the relation
+ * @returns EngineResult confirming the relation was added
+ *
+ * @example
+ * ```typescript
+ * const result = await taskRelatesAdd('/project', 'T42', 'T43', 'blocks', 'Needs auth first');
+ * ```
+ *
+ * @task T4790
+ */
+export async function taskRelatesAdd(projectRoot, taskId, relatedId, type, reason) {
+    try {
+        const result = await coreTaskRelatesAdd(projectRoot, taskId, relatedId, type, reason);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        if (message.includes('Invalid relation type')) {
+            return engineError('E_VALIDATION', message, {
+                fix: 'Use a valid relation type: related, blocks, duplicates, absorbs, fixes, extends, supersedes',
+            });
+        }
+        return engineError('E_GENERAL', `Failed to update task relations: ${message}`);
+    }
+}
+/**
+ * Analyze a task for description quality, missing fields, and dependency health.
+ *
+ * @remarks
+ * When no task ID is provided, analyzes all tasks to identify bottlenecks,
+ * leverage opportunities, and overall project health metrics.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Optional specific task to analyze
+ * @param params - Optional analysis parameters
+ * @returns EngineResult with recommended task, bottlenecks, tiers, and metrics
+ *
+ * @example
+ * ```typescript
+ * const result = await taskAnalyze('/project');
+ * ```
+ *
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskAnalyze(projectRoot, taskId, params) {
+    try {
+        const result = await coreTaskAnalyze(projectRoot, taskId, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_GENERAL', `Task analysis failed: ${message}`);
+    }
+}
+/**
+ * Predict downstream impact of a free-text change description.
+ *
+ * Delegates to {@link predictImpact} from the intelligence module.
+ * Uses keyword matching against task titles/descriptions, then traces
+ * the reverse dependency graph for transitive effects.
+ *
+ * @remarks
+ * The impact report includes directly affected tasks, transitively
+ * affected tasks (through the dependency graph), and a severity assessment.
+ *
+ * @param projectRoot - Project root directory
+ * @param change - Free-text description of the proposed change
+ * @param matchLimit - Maximum seed tasks to match (default: 5)
+ * @returns Impact prediction report
+ *
+ * @example
+ * ```typescript
+ * const result = await taskImpact('/project', 'Refactor authentication module');
+ * ```
+ *
+ * @task T043
+ */
+export async function taskImpact(projectRoot, change, matchLimit) {
+    try {
+        const result = await predictImpact(change, projectRoot, undefined, matchLimit);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return engineError('E_GENERAL', `Impact prediction failed: ${message}`);
+    }
+}
+/**
+ * Restore a cancelled task back to pending.
+ *
+ * @remarks
+ * When cascade is true, also restores cancelled children.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to restore
+ * @param params - Optional cascade and notes options
+ * @returns EngineResult with restored task IDs and count
+ *
+ * @example
+ * ```typescript
+ * const result = await taskRestore('/project', 'T42', { cascade: true });
+ * ```
+ *
+ * @task T4790
+ */
+export async function taskRestore(projectRoot, taskId, params) {
+    try {
+        const result = await coreTaskRestore(projectRoot, taskId, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        if (message.includes('not cancelled')) {
+            return engineError('E_INVALID_INPUT', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Failed to restore task');
+    }
+}
+/**
+ * Move an archived task back to active task data with status 'done' (or specified status).
+ *
+ * @remarks
+ * By default restores with status 'done'. Use `preserveStatus` to keep
+ * the original status, or `status` to set a specific status.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Archived task identifier to restore
+ * @param params - Optional status override parameters
+ * @returns EngineResult with the unarchived task info
+ *
+ * @example
+ * ```typescript
+ * const result = await taskUnarchive('/project', 'T42', { status: 'pending' });
+ * ```
+ *
+ * @task T4790
+ */
+export async function taskUnarchive(projectRoot, taskId, params) {
+    try {
+        const result = await coreTaskUnarchive(projectRoot, taskId, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        if (message.includes('already exists')) {
+            return engineError('E_ID_COLLISION', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Failed to unarchive task');
+    }
+}
+/**
+ * Change task position within its sibling group.
+ *
+ * @remarks
+ * Reorders a task to the specified zero-based position among its siblings.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to reorder
+ * @param position - Target zero-based position
+ * @returns EngineResult with new position and total siblings
+ *
+ * @example
+ * ```typescript
+ * const result = await taskReorder('/project', 'T42', 0); // move to first
+ * ```
+ *
+ * @task T4790
+ */
+export async function taskReorder(projectRoot, taskId, position) {
+    try {
+        const result = await coreTaskReorder(projectRoot, taskId, position);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Failed to reorder task');
+    }
+}
+/**
+ * Move task under a different parent.
+ *
+ * @remarks
+ * Pass null as `newParentId` to promote the task to a root-level task.
+ * Validates hierarchy depth and circular reference constraints.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to move
+ * @param newParentId - New parent task ID, or null for root
+ * @returns EngineResult with old and new parent information
+ *
+ * @example
+ * ```typescript
+ * const result = await taskReparent('/project', 'T42', 'T1');
+ * ```
+ *
+ * @task T4790
+ */
+export async function taskReparent(projectRoot, taskId, newParentId) {
+    try {
+        const result = await coreTaskReparent(projectRoot, taskId, newParentId);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            const code = message.includes('Parent') ? 'E_PARENT_NOT_FOUND' : 'E_NOT_FOUND';
+            return engineError(code, message);
+        }
+        if (message.includes('subtask')) {
+            return engineError('E_INVALID_PARENT_TYPE', message);
+        }
+        if (message.includes('circular')) {
+            return engineError('E_CIRCULAR_REFERENCE', message);
+        }
+        if (message.includes('depth')) {
+            return engineError('E_DEPTH_EXCEEDED', message);
+        }
+        if (message.includes('siblings')) {
+            return engineError('E_SIBLING_LIMIT', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Failed to reparent task');
+    }
+}
+/**
+ * Promote a subtask to task or task to root (remove parent).
+ *
+ * @remarks
+ * Removes the parent reference and may change the task type from subtask to task.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to promote
+ * @returns EngineResult with promotion details
+ *
+ * @example
+ * ```typescript
+ * const result = await taskPromote('/project', 'T42');
+ * ```
+ *
+ * @task T4790
+ */
+export async function taskPromote(projectRoot, taskId) {
+    try {
+        const result = await coreTaskPromote(projectRoot, taskId);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Failed to promote task');
+    }
+}
+/**
+ * Reopen a completed task (set status back to pending).
+ *
+ * @remarks
+ * Only works on tasks with status 'done'. Optionally sets a different
+ * target status and records a reason for reopening.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to reopen
+ * @param params - Optional target status and reason
+ * @returns EngineResult with reopen details including previous and new status
+ *
+ * @example
+ * ```typescript
+ * const result = await taskReopen('/project', 'T42', { reason: 'Tests regressed' });
+ * ```
+ *
+ * @task T4790
+ */
+export async function taskReopen(projectRoot, taskId, params) {
+    try {
+        const result = await coreTaskReopen(projectRoot, taskId, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        if (message.includes('not completed')) {
+            return engineError('E_INVALID_INPUT', message);
+        }
+        if (message.includes('Invalid target')) {
+            return engineError('E_INVALID_INPUT', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Failed to reopen task');
+    }
+}
+/**
+ * Cancel a task (soft terminal state -- reversible via restore).
+ *
+ * @remarks
+ * Sets the task status to cancelled with an optional reason. The task can
+ * be restored later via {@link taskRestore}.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier to cancel
+ * @param reason - Optional cancellation reason
+ * @returns EngineResult with cancellation details
+ *
+ * @example
+ * ```typescript
+ * const result = await taskCancel('/project', 'T42', 'No longer needed');
+ * ```
+ *
+ * @task T4529
+ */
+export async function taskCancel(projectRoot, taskId, reason) {
+    try {
+        const result = await coreTaskCancel(projectRoot, taskId, { reason });
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found'))
+            return engineError('E_NOT_FOUND', message);
+        if (message.includes('already cancelled') || message.includes('completed'))
+            return engineError('E_INVALID_INPUT', message);
+        return engineError('E_INTERNAL', message);
+    }
+}
+/**
+ * Deterministic complexity scoring from task metadata.
+ *
+ * @remarks
+ * Produces a size estimate (small/medium/large) based on dependency depth,
+ * subtask count, file count, and other structural factors.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param params - Parameters including the task ID to estimate
+ * @returns EngineResult with size, score, factors, and structural metrics
+ *
+ * @example
+ * ```typescript
+ * const result = await taskComplexityEstimate('/project', { taskId: 'T42' });
+ * ```
+ *
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskComplexityEstimate(projectRoot, params) {
+    try {
+        const result = await coreTaskComplexityEstimate(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * List dependencies for a task in a given direction.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskDepends(projectRoot, taskId, direction = 'both', tree) {
+    try {
+        const result = await coreTaskDepends(projectRoot, taskId, direction, tree ? { tree } : undefined);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Overview of all dependencies across the project.
+ * @task T5157
+ */
+export async function taskDepsOverview(projectRoot) {
+    try {
+        const result = await coreTaskDepsOverview(projectRoot);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return engineError('E_NOT_INITIALIZED', message);
+    }
+}
+/**
+ * Detect circular dependencies across the project.
+ * @task T5157
+ */
+export async function taskDepsCycles(projectRoot) {
+    try {
+        const result = await coreTaskDepsCycles(projectRoot);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return engineError('E_NOT_INITIALIZED', message);
+    }
+}
+/**
+ * Compute task statistics, optionally scoped to an epic.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskStats(projectRoot, epicId) {
+    try {
+        const result = await coreTaskStats(projectRoot, epicId);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Export tasks as JSON or CSV.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskExport(projectRoot, params) {
+    try {
+        const result = await coreTaskExport(projectRoot, params);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Get task history from the log file.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskHistory(projectRoot, taskId, limit) {
+    try {
+        const result = await coreTaskHistory(projectRoot, taskId, limit);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Failed to read task history');
+    }
+}
+/**
+ * Lint tasks for common issues.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskLint(projectRoot, taskId) {
+    try {
+        const result = await coreTaskLint(projectRoot, taskId);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Validate multiple tasks at once.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export async function taskBatchValidate(projectRoot, taskIds, checkMode = 'full') {
+    try {
+        const result = await coreTaskBatchValidate(projectRoot, taskIds, checkMode);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Import tasks from a JSON source string or export package.
+ * @task T4790
+ */
+export async function taskImport(projectRoot, source, overwrite) {
+    try {
+        const result = await coreTaskImport(projectRoot, source, overwrite);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('Invalid JSON')) {
+            return engineError('E_INVALID_INPUT', message);
+        }
+        return engineError('E_NOT_INITIALIZED', 'Failed to import tasks');
+    }
+}
+/**
+ * Compute a ranked plan: in-progress epics, ready tasks, blockers, bugs.
+ * @task T4815
+ */
+export async function taskPlan(projectRoot) {
+    const { coreTaskPlan } = await import('@cleocode/core/internal');
+    try {
+        const result = await coreTaskPlan(projectRoot);
+        return { success: true, data: result };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Find related tasks using semantic search or keyword matching.
+ * @task T5672
+ */
+export async function taskRelatesFind(projectRoot, taskId, params) {
+    try {
+        const { suggestRelated, discoverRelated } = await import('@cleocode/core/internal');
+        const accessor = await getAccessor(projectRoot);
+        const mode = params?.mode ?? 'suggest';
+        let result;
+        if (mode === 'discover') {
+            result = await discoverRelated(taskId, undefined, accessor);
+        }
+        else {
+            const threshold = params?.threshold ?? 50;
+            result = await suggestRelated(taskId, { threshold }, accessor);
+        }
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found')) {
+            return engineError('E_NOT_FOUND', message);
+        }
+        return engineError('E_INTERNAL', message);
+    }
+}
+/**
+ * List all labels used in tasks.
+ * @task T5672
+ */
+export async function taskLabelList(projectRoot) {
+    try {
+        const { listLabels } = await import('@cleocode/core/internal');
+        const accessor = await getAccessor(projectRoot);
+        const labels = await listLabels(projectRoot, accessor);
+        return { success: true, data: { labels, count: labels.length } };
+    }
+    catch {
+        return engineError('E_NOT_INITIALIZED', 'Task database not initialized');
+    }
+}
+/**
+ * Show tasks associated with a label.
+ * @task T5672
+ */
+export async function taskLabelShow(projectRoot, label) {
+    try {
+        const { showLabelTasks } = await import('@cleocode/core/internal');
+        const accessor = await getAccessor(projectRoot);
+        const result = await showLabelTasks(label, projectRoot, accessor);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return engineError('E_INTERNAL', message);
+    }
+}
+// ---------------------------------------------------------------------------
+// Sync sub-domain (provider-agnostic task reconciliation)
+// ---------------------------------------------------------------------------
+/**
+ * Reconcile external tasks with CLEO as SSoT.
+ */
+export async function taskSyncReconcile(projectRoot, params) {
+    try {
+        const { reconcile } = await import('@cleocode/core/internal');
+        const accessor = await getAccessor(projectRoot);
+        const result = await reconcile(params.externalTasks, {
+            providerId: params.providerId,
+            cwd: projectRoot,
+            dryRun: params.dryRun,
+            conflictPolicy: params.conflictPolicy,
+            defaultPhase: params.defaultPhase,
+            defaultLabels: params.defaultLabels,
+        }, accessor);
+        return { success: true, data: result };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return engineError('E_INTERNAL', message);
+    }
+}
+/**
+ * List external task links by provider or task ID.
+ */
+export async function taskSyncLinks(projectRoot, params) {
+    try {
+        const { getLinksByProvider, getLinksByTaskId } = await import('@cleocode/core/internal');
+        if (params?.taskId) {
+            const links = await getLinksByTaskId(params.taskId, projectRoot);
+            return { success: true, data: { links, count: links.length } };
+        }
+        if (params?.providerId) {
+            const links = await getLinksByProvider(params.providerId, projectRoot);
+            return { success: true, data: { links, count: links.length } };
+        }
+        return engineError('E_INVALID_INPUT', 'Either providerId or taskId is required');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return engineError('E_INTERNAL', message);
+    }
+}
+/**
+ * Remove all external task links for a provider.
+ */
+export async function taskSyncLinksRemove(projectRoot, providerId) {
+    try {
+        const { removeLinksByProvider } = await import('@cleocode/core/internal');
+        const removed = await removeLinksByProvider(providerId, projectRoot);
+        return { success: true, data: { providerId, removed } };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return engineError('E_INTERNAL', message);
+    }
+}
+/**
+ * Atomically claim a task for an agent.
+ *
+ * Fails if the task is already claimed by a different agent.
+ * No-op if the task is already claimed by the same agent (idempotent).
+ */
+export async function taskClaim(projectRoot, taskId, agentId) {
+    try {
+        if (!taskId)
+            return engineError('E_INVALID_INPUT', 'taskId is required');
+        if (!agentId)
+            return engineError('E_INVALID_INPUT', 'agentId is required');
+        const acc = await getAccessor(projectRoot);
+        await acc.claimTask(taskId, agentId);
+        return { success: true, data: { taskId, agentId } };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found'))
+            return engineError('E_NOT_FOUND', message);
+        if (message.includes('already claimed'))
+            return engineError('E_CONFLICT', message);
+        return engineError('E_INTERNAL', message);
+    }
+}
+/**
+ * Release an agent's claim on a task, setting assignee to null.
+ *
+ * No-op if the task is not currently claimed.
+ */
+export async function taskUnclaim(projectRoot, taskId) {
+    try {
+        if (!taskId)
+            return engineError('E_INVALID_INPUT', 'taskId is required');
+        const acc = await getAccessor(projectRoot);
+        await acc.unclaimTask(taskId);
+        return { success: true, data: { taskId } };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('not found'))
+            return engineError('E_NOT_FOUND', message);
+        return engineError('E_INTERNAL', message);
+    }
+}
+//# sourceMappingURL=task-engine.js.map