@cleocode/cleo 2026.4.9 → 2026.4.11

package/dist/dispatch/engines/task-engine.d.ts

@@ -0,0 +1,1055 @@
+/**
+ * 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
+ */
+import { type CompactTask, type ComplexityFactor, type ImpactReport } from '@cleocode/core/internal';
+import { type EngineResult } from './_error.js';
+/**
+ * Task object as stored in task data.
+ */
+export interface TaskRecord {
+    /** Unique task identifier (e.g. "T001"). */
+    id: string;
+    /** Short summary of the task. */
+    title: string;
+    /** Full task description. */
+    description: string;
+    /** Current status (pending, active, blocked, done, cancelled). */
+    status: string;
+    /** Priority level (critical, high, medium, low). */
+    priority: string;
+    /** Task type (task, epic, milestone, bug). */
+    type?: string;
+    /** Project phase this task belongs to. */
+    phase?: string;
+    /** ISO timestamp when the task was created. */
+    createdAt: string;
+    /** ISO timestamp of the last update, or null. */
+    updatedAt: string | null;
+    /** ISO timestamp when the task was completed, or null. */
+    completedAt?: string | null;
+    /** ISO timestamp when the task was cancelled, or null. */
+    cancelledAt?: string | null;
+    /** Parent task ID for hierarchical nesting, or null for root tasks. */
+    parentId?: string | null;
+    /** Ordering position among siblings. */
+    position?: number | null;
+    /** Optimistic concurrency version for position updates. */
+    positionVersion?: number;
+    /** Task IDs this task depends on (must complete first). */
+    depends?: string[];
+    /** Related tasks with relationship type and optional reason. */
+    relates?: Array<{
+        /** Related task ID. */
+        taskId: string;
+        /** Relationship type (e.g. "related-to", "blocks"). */
+        type: string;
+        /** Optional explanation for the relationship. */
+        reason?: string;
+    }>;
+    /** File paths associated with this task. */
+    files?: string[];
+    /** Acceptance criteria lines. */
+    acceptance?: string[];
+    /** Free-form notes. */
+    notes?: string[];
+    /** Classification labels. */
+    labels?: string[];
+    /** Complexity sizing (small, medium, large). */
+    size?: string | null;
+    /** Epic lifecycle state for epic-type tasks. */
+    epicLifecycle?: string | null;
+    /** When true, prevents auto-completion on child task completion. */
+    noAutoComplete?: boolean | null;
+    /** Verification gate state and round tracking. */
+    verification?: import('@cleocode/contracts').TaskVerification | null;
+    /** How the task was created (manual, decomposition, import). */
+    origin?: string | null;
+    /** Agent or user who created the task. */
+    createdBy?: string | null;
+    /** Agent or user who validated the task. */
+    validatedBy?: string | null;
+    /** Agent or user who tested the task. */
+    testedBy?: string | null;
+    /** Current lifecycle governance state. */
+    lifecycleState?: string | null;
+    /** History of lifecycle validation transitions. */
+    validationHistory?: Array<Record<string, unknown>>;
+    /** Task IDs that are blocking this task. */
+    blockedBy?: string[];
+    /** Reason provided when the task was cancelled. */
+    cancellationReason?: string;
+    /** RCASD-IVTR+C pipeline stage (T060). */
+    pipelineStage?: string | null;
+}
+/**
+ * Minimal task representation for find results.
+ *
+ * @remarks
+ * Used by `taskFind` to return lightweight task records that minimize
+ * context consumption for agent discovery operations.
+ */
+export interface MinimalTaskRecord {
+    /** Unique task identifier. */
+    id: string;
+    /** Short summary of the task. */
+    title: string;
+    /** Current status. */
+    status: string;
+    /** Priority level. */
+    priority: string;
+    /** Parent task ID, or null for root tasks. */
+    parentId?: string | null;
+}
+export type { CompactTask } from '@cleocode/core/internal';
+export type { EngineResult } from './_error.js';
+/**
+ * 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 declare function taskShow(projectRoot: string, taskId: string): Promise<EngineResult<{
+    task: TaskRecord;
+}>>;
+/**
+ * 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 declare function taskList(projectRoot: string, params?: {
+    parent?: string;
+    status?: string;
+    priority?: string;
+    type?: string;
+    phase?: string;
+    label?: string;
+    children?: boolean;
+    limit?: number;
+    offset?: number;
+    compact?: boolean;
+}): Promise<EngineResult<{
+    tasks: TaskRecord[] | CompactTask[];
+    total: number;
+    filtered: number;
+}>>;
+/**
+ * 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 declare function taskFind(projectRoot: string, query: string, limit?: number, options?: {
+    id?: string;
+    exact?: boolean;
+    status?: string;
+    includeArchive?: boolean;
+    offset?: number;
+}): Promise<EngineResult<{
+    results: MinimalTaskRecord[];
+    total: number;
+}>>;
+/**
+ * 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 declare function taskExists(projectRoot: string, taskId: string): Promise<EngineResult<{
+    exists: boolean;
+    taskId: string;
+}>>;
+/**
+ * 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 declare function taskCreate(projectRoot: string, params: {
+    title: string;
+    description: string;
+    parent?: string;
+    depends?: string[];
+    priority?: string;
+    labels?: string[];
+    type?: string;
+    phase?: string;
+    size?: string;
+    acceptance?: string[];
+    notes?: string;
+    files?: string[];
+    dryRun?: boolean;
+}): Promise<EngineResult<{
+    task: TaskRecord;
+    duplicate: boolean;
+    dryRun?: boolean;
+}>>;
+/**
+ * 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 declare function taskUpdate(projectRoot: string, taskId: string, updates: {
+    title?: string;
+    description?: string;
+    status?: string;
+    priority?: string;
+    notes?: string;
+    labels?: string[];
+    addLabels?: string[];
+    removeLabels?: string[];
+    depends?: string[];
+    addDepends?: string[];
+    removeDepends?: string[];
+    acceptance?: string[];
+    parent?: string | null;
+    type?: string;
+    size?: string;
+}): Promise<EngineResult<{
+    task: TaskRecord;
+    changes?: string[];
+}>>;
+/**
+ * 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 declare function taskComplete(projectRoot: string, taskId: string, notes?: string): Promise<EngineResult<{
+    task: TaskRecord;
+    autoCompleted?: string[];
+    unblockedTasks?: Array<{
+        id: string;
+        title: string;
+    }>;
+}>>;
+/**
+ * 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 declare function taskDelete(projectRoot: string, taskId: string, force?: boolean): Promise<EngineResult<{
+    deletedTask: TaskRecord;
+    deleted: boolean;
+    cascadeDeleted?: string[];
+}>>;
+/**
+ * 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 declare function taskArchive(projectRoot: string, taskId?: string, before?: string): Promise<EngineResult<{
+    archivedCount: number;
+    archivedTasks: Array<{
+        id: string;
+    }>;
+}>>;
+/**
+ * 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 declare function taskNext(projectRoot: string, params?: {
+    count?: number;
+    explain?: boolean;
+}): Promise<EngineResult<{
+    suggestions: Array<{
+        id: string;
+        title: string;
+        priority: string;
+        phase: string | null;
+        score: number;
+        reasons?: string[];
+    }>;
+    totalCandidates: number;
+}>>;
+/**
+ * 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 declare function taskBlockers(projectRoot: string, params?: {
+    analyze?: boolean;
+    limit?: number;
+}): Promise<EngineResult<{
+    blockedTasks: Array<{
+        id: string;
+        title: string;
+        status: string;
+        depends?: string[];
+        blockingChain: string[];
+    }>;
+    criticalBlockers: Array<{
+        id: string;
+        title: string;
+        blocksCount: number;
+    }>;
+    summary: string;
+    total: number;
+    limit: number;
+}>>;
+/**
+ * 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 declare function taskTree(projectRoot: string, taskId?: string): Promise<EngineResult>;
+/**
+ * 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 declare function taskDeps(projectRoot: string, taskId: string): Promise<EngineResult<{
+    taskId: string;
+    dependsOn: Array<{
+        id: string;
+        title: string;
+        status: string;
+    }>;
+    dependedOnBy: Array<{
+        id: string;
+        title: string;
+        status: string;
+    }>;
+    unresolvedDeps: string[];
+    allDepsReady: boolean;
+}>>;
+/**
+ * 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 declare function taskRelates(projectRoot: string, taskId: string): Promise<EngineResult<{
+    taskId: string;
+    relations: Array<{
+        taskId: string;
+        type: string;
+        reason?: string;
+    }>;
+    count: number;
+}>>;
+/**
+ * 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 declare function taskRelatesAdd(projectRoot: string, taskId: string, relatedId: string, type: string, reason?: string): Promise<EngineResult<{
+    from: string;
+    to: string;
+    type: string;
+    added: boolean;
+}>>;
+/**
+ * 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 declare function taskAnalyze(projectRoot: string, taskId?: string, params?: {
+    tierLimit?: number;
+}): Promise<EngineResult<{
+    recommended: {
+        id: string;
+        title: string;
+        leverage: number;
+        reason: string;
+    } | null;
+    bottlenecks: Array<{
+        id: string;
+        title: string;
+        blocksCount: number;
+    }>;
+    tiers: {
+        critical: Array<{
+            id: string;
+            title: string;
+            leverage: number;
+        }>;
+        high: Array<{
+            id: string;
+            title: string;
+            leverage: number;
+        }>;
+        normal: Array<{
+            id: string;
+            title: string;
+            leverage: number;
+        }>;
+    };
+    metrics: {
+        totalTasks: number;
+        actionable: number;
+        blocked: number;
+        avgLeverage: number;
+    };
+    tierLimit: number;
+}>>;
+/**
+ * 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 declare function taskImpact(projectRoot: string, change: string, matchLimit?: number): Promise<EngineResult<ImpactReport>>;
+/**
+ * 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 declare function taskRestore(projectRoot: string, taskId: string, params?: {
+    cascade?: boolean;
+    notes?: string;
+}): Promise<EngineResult<{
+    task: string;
+    restored: string[];
+    count: number;
+}>>;
+/**
+ * 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 declare function taskUnarchive(projectRoot: string, taskId: string, params?: {
+    status?: string;
+    preserveStatus?: boolean;
+}): Promise<EngineResult<{
+    task: string;
+    unarchived: boolean;
+    title: string;
+    status: string;
+}>>;
+/**
+ * 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 declare function taskReorder(projectRoot: string, taskId: string, position: number): Promise<EngineResult<{
+    task: string;
+    reordered: boolean;
+    newPosition: number;
+    totalSiblings: number;
+}>>;
+/**
+ * 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 declare function taskReparent(projectRoot: string, taskId: string, newParentId: string | null): Promise<EngineResult<{
+    task: string;
+    reparented: boolean;
+    oldParent: string | null;
+    newParent: string | null;
+    newType?: string;
+}>>;
+/**
+ * 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 declare function taskPromote(projectRoot: string, taskId: string): Promise<EngineResult<{
+    task: string;
+    promoted: boolean;
+    previousParent: string | null;
+    typeChanged: boolean;
+}>>;
+/**
+ * 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 declare function taskReopen(projectRoot: string, taskId: string, params?: {
+    status?: string;
+    reason?: string;
+}): Promise<EngineResult<{
+    task: string;
+    reopened: boolean;
+    previousStatus: string;
+    newStatus: string;
+}>>;
+/**
+ * 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 declare function taskCancel(projectRoot: string, taskId: string, reason?: string): Promise<EngineResult<{
+    task: string;
+    cancelled: boolean;
+    reason?: string;
+    cancelledAt: string;
+}>>;
+/**
+ * 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 declare function taskComplexityEstimate(projectRoot: string, params: {
+    taskId: string;
+}): Promise<EngineResult<{
+    size: 'small' | 'medium' | 'large';
+    score: number;
+    factors: ComplexityFactor[];
+    dependencyDepth: number;
+    subtaskCount: number;
+    fileCount: number;
+}>>;
+/**
+ * List dependencies for a task in a given direction.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export declare function taskDepends(projectRoot: string, taskId: string, direction?: 'upstream' | 'downstream' | 'both', tree?: boolean): Promise<EngineResult>;
+/**
+ * Overview of all dependencies across the project.
+ * @task T5157
+ */
+export declare function taskDepsOverview(projectRoot: string): Promise<EngineResult<{
+    totalTasks: number;
+    tasksWithDeps: number;
+    blockedTasks: Array<{
+        id: string;
+        title: string;
+        status: string;
+        unblockedBy: string[];
+    }>;
+    readyTasks: Array<{
+        id: string;
+        title: string;
+        status: string;
+    }>;
+    validation: {
+        valid: boolean;
+        errorCount: number;
+        warningCount: number;
+    };
+}>>;
+/**
+ * Detect circular dependencies across the project.
+ * @task T5157
+ */
+export declare function taskDepsCycles(projectRoot: string): Promise<EngineResult<{
+    hasCycles: boolean;
+    cycles: Array<{
+        path: string[];
+        tasks: Array<{
+            id: string;
+            title: string;
+        }>;
+    }>;
+}>>;
+/**
+ * Compute task statistics, optionally scoped to an epic.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export declare function taskStats(projectRoot: string, epicId?: string): Promise<EngineResult<{
+    total: number;
+    pending: number;
+    active: number;
+    blocked: number;
+    done: number;
+    cancelled: number;
+    byPriority: Record<string, number>;
+    byType: Record<string, number>;
+}>>;
+/**
+ * Export tasks as JSON or CSV.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export declare function taskExport(projectRoot: string, params?: {
+    format?: 'json' | 'csv';
+    status?: string;
+    parent?: string;
+}): Promise<EngineResult<unknown>>;
+/**
+ * Get task history from the log file.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export declare function taskHistory(projectRoot: string, taskId: string, limit?: number): Promise<EngineResult<Array<Record<string, unknown>>>>;
+/**
+ * Lint tasks for common issues.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export declare function taskLint(projectRoot: string, taskId?: string): Promise<EngineResult<Array<{
+    taskId: string;
+    severity: 'error' | 'warning';
+    rule: string;
+    message: string;
+}>>>;
+/**
+ * Validate multiple tasks at once.
+ * @task T4657
+ * @task T4790
+ * @epic T4654
+ */
+export declare function taskBatchValidate(projectRoot: string, taskIds: string[], checkMode?: 'full' | 'quick'): Promise<EngineResult<{
+    results: Record<string, Array<{
+        severity: 'error' | 'warning';
+        rule: string;
+        message: string;
+    }>>;
+    summary: {
+        totalTasks: number;
+        validTasks: number;
+        invalidTasks: number;
+        totalIssues: number;
+        errors: number;
+        warnings: number;
+    };
+}>>;
+/**
+ * Import tasks from a JSON source string or export package.
+ * @task T4790
+ */
+export declare function taskImport(projectRoot: string, source: string, overwrite?: boolean): Promise<EngineResult<{
+    imported: number;
+    skipped: number;
+    errors: string[];
+    remapTable?: Record<string, string>;
+}>>;
+/**
+ * Compute a ranked plan: in-progress epics, ready tasks, blockers, bugs.
+ * @task T4815
+ */
+export declare function taskPlan(projectRoot: string): Promise<EngineResult>;
+/**
+ * Find related tasks using semantic search or keyword matching.
+ * @task T5672
+ */
+export declare function taskRelatesFind(projectRoot: string, taskId: string, params?: {
+    mode?: 'suggest' | 'discover';
+    threshold?: number;
+}): Promise<EngineResult<Record<string, unknown>>>;
+/**
+ * List all labels used in tasks.
+ * @task T5672
+ */
+export declare function taskLabelList(projectRoot: string): Promise<EngineResult<{
+    labels: unknown[];
+    count: number;
+}>>;
+/**
+ * Show tasks associated with a label.
+ * @task T5672
+ */
+export declare function taskLabelShow(projectRoot: string, label: string): Promise<EngineResult<Record<string, unknown>>>;
+/**
+ * Reconcile external tasks with CLEO as SSoT.
+ */
+export declare function taskSyncReconcile(projectRoot: string, params: {
+    providerId: string;
+    externalTasks: Array<import('@cleocode/contracts').ExternalTask>;
+    dryRun?: boolean;
+    conflictPolicy?: string;
+    defaultPhase?: string;
+    defaultLabels?: string[];
+}): Promise<EngineResult<import('@cleocode/contracts').ReconcileResult>>;
+/**
+ * List external task links by provider or task ID.
+ */
+export declare function taskSyncLinks(projectRoot: string, params?: {
+    providerId?: string;
+    taskId?: string;
+}): Promise<EngineResult<{
+    links: import('@cleocode/contracts').ExternalTaskLink[];
+    count: number;
+}>>;
+/**
+ * Remove all external task links for a provider.
+ */
+export declare function taskSyncLinksRemove(projectRoot: string, providerId: string): Promise<EngineResult<{
+    providerId: string;
+    removed: number;
+}>>;
+/**
+ * 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 declare function taskClaim(projectRoot: string, taskId: string, agentId: string): Promise<EngineResult<{
+    taskId: string;
+    agentId: string;
+}>>;
+/**
+ * Release an agent's claim on a task, setting assignee to null.
+ *
+ * No-op if the task is not currently claimed.
+ */
+export declare function taskUnclaim(projectRoot: string, taskId: string): Promise<EngineResult<{
+    taskId: string;
+}>>;
+//# sourceMappingURL=task-engine.d.ts.map