@cleocode/cleo 2026.4.158 → 2026.5.0

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

@@ -0,0 +1,1161 @@
+/**
+ * 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 { MinimalTaskRecord, TaskRecord } from '@cleocode/core';
+import { type CompactTask, type ComplexityFactor, type ImpactReport, type IvtrPhase, type TaskView } from '@cleocode/core/internal';
+import { type EngineResult } from './_error.js';
+export type { MinimalTaskRecord, TaskRecord } from '@cleocode/core';
+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. Also computes the
+ * canonical {@link TaskView} via `computeTaskView` so the `view` field
+ * in the response includes `readyToComplete`, `nextAction`, and
+ * `lifecycleProgress` without a second round-trip.
+ *
+ * The `view` field is `null` when `computeTaskView` cannot load the
+ * task (e.g. freshly created task not yet visible to the native DB
+ * handle). Callers MUST check `result.data.task` for the primary record.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier (e.g. "T001")
+ * @returns EngineResult containing the task record and canonical view
+ *
+ * @example
+ * ```typescript
+ * const result = await taskShow('/project', 'T42');
+ * if (result.success) {
+ *   console.log(result.data.task.title);
+ *   console.log(result.data.view?.nextAction); // 'verify' | 'spawn-worker' | …
+ * }
+ * ```
+ *
+ * @task T4657
+ * @task T943
+ * @epic T4654
+ */
+export declare function taskShow(projectRoot: string, taskId: string): Promise<EngineResult<{
+    task: TaskRecord;
+    view: TaskView | null;
+}>>;
+/**
+ * A single lifecycle stage transition entry returned by taskShowWithHistory.
+ * Maps the `getLifecycleStatus` stage shape into a stable, typed record.
+ *
+ * @task T787
+ * @epic T769
+ */
+export interface LifecycleStageEntry {
+    /** Canonical stage name (e.g. "research", "implementation"). */
+    stage: string;
+    /** Current status of this stage. */
+    status: 'not_started' | 'in_progress' | 'completed' | 'skipped' | 'failed';
+    /** ISO timestamp when the stage was started, or null. */
+    startedAt: string | null;
+    /** ISO timestamp when the stage was completed, or null. */
+    completedAt: string | null;
+    /** Output file path recorded for this stage, or null. */
+    outputFile: string | null;
+}
+/**
+ * Get a single task by ID, optionally including its lifecycle stage history.
+ *
+ * @remarks
+ * When `includeHistory` is `true`, appends a `history` array containing one
+ * {@link LifecycleStageEntry} per RCASD pipeline stage. If the task has no
+ * pipeline record the call never fails — it returns `history: []` instead.
+ *
+ * When `includeHistory` is `false` (or omitted) the return value is identical
+ * to {@link taskShow} and the `history` key is absent from `data`.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier (e.g. "T042")
+ * @param includeHistory - When true, append lifecycle stage array
+ * @returns EngineResult containing the task record and optional history
+ *
+ * @example
+ * ```typescript
+ * const result = await taskShowWithHistory('/project', 'T42', true);
+ * if (result.success) {
+ *   console.log(result.data.task.title);
+ *   console.log(result.data.history); // LifecycleStageEntry[]
+ * }
+ * ```
+ *
+ * @task T787
+ * @epic T769
+ */
+export declare function taskShowWithHistory(projectRoot: string, taskId: string, includeHistory: boolean): Promise<EngineResult<{
+    task: TaskRecord;
+    history?: LifecycleStageEntry[];
+}>>;
+/**
+ * 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;
+    /** Comma-separated extra fields to include (e.g. "labels,acceptance,notes"). @task T092 */
+    fields?: string;
+    /** Return all task fields (same as cleo list output). @task T092 */
+    verbose?: boolean;
+    /** Filter by role axis (T944). */
+    role?: string;
+}): Promise<EngineResult<{
+    results: (MinimalTaskRecord | TaskRecord)[];
+    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;
+    /** Resolve parent by title substring instead of exact ID. @task T090 */
+    parentSearch?: string;
+    /** Task role axis — intent of work (T944). Alias: `kind`. */
+    role?: string;
+    /** Task scope axis — granularity of work (T944). */
+    scope?: string;
+    /** Bug severity (T944). OWNER-WRITE-ONLY. Only valid with role='bug'. */
+    severity?: string;
+}): Promise<EngineResult<{
+    task: TaskRecord;
+    duplicate: boolean;
+    dryRun?: boolean;
+    warnings?: string[];
+}>>;
+/**
+ * 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;
+    /** File paths associated with this task (AC.files). T1014 — parity with add. */
+    files?: string[];
+    /** Pipeline stage transition target (T834 / ADR-051 Decision 4). */
+    pipelineStage?: string;
+    /** Task role axis — intent of work (T944). */
+    role?: string;
+    /** Task scope axis — granularity of work (T944). */
+    scope?: string;
+    /**
+     * Operator-supplied justification required to override the
+     * acceptance-criteria immutability guard at locked pipeline stages.
+     *
+     * @task T1590
+     */
+    reason?: 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.
+ *
+ * After a successful completion, `modified_by` and `session_id` are written back
+ * to the task row via `updateTaskFields` so every completed task carries auditable
+ * provenance (T1222 / CLEO-VALID-27). `modified_by` is sourced from the
+ * `CLEO_AGENT_ID` environment variable (falls back to `"cleo"`). `session_id` is
+ * sourced from the currently-active session returned by `getActiveSession`, falling
+ * back to the `CLEO_SESSION_ID` environment variable, and finally `null`.
+ *
+ * @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');
+ * ```
+ *
+ * @task T1222
+ */
+export declare function taskComplete(projectRoot: string, taskId: string, notes?: string): Promise<EngineResult<{
+    task: TaskRecord;
+    autoCompleted?: string[];
+    unblockedTasks?: Array<{
+        id: string;
+        title: string;
+    }>;
+}>>;
+/**
+ * A single IVTR phase entry returned by taskCompleteStrict and taskShowIvtrHistory.
+ * Surface-safe projection of IvtrPhaseEntry with renamed agentIdentity → agent.
+ *
+ * @task T815
+ * @task T817
+ * @epic T810
+ */
+export interface IvtrHistoryEntry {
+    /** Phase name (implement | validate | test | released). */
+    phase: IvtrPhase;
+    /** Agent identity string, or null if unknown. */
+    agent: string | null;
+    /** ISO timestamp when this phase was started. */
+    startedAt: string;
+    /** ISO timestamp when this phase was completed, or null if still active. */
+    completedAt: string | null;
+    /** Whether this phase passed. null = in-progress. */
+    passed: boolean | null;
+    /** sha256 hashes of evidence attachments for this phase. */
+    evidenceRefs: string[];
+}
+/**
+ * Complete a task with strict IVTR + evidence-staleness enforcement.
+ *
+ * @remarks
+ * Enforcement path (T832 / ADR-051 Decision 3+8):
+ * 1. **Evidence staleness re-check**: every verification.evidence record is
+ *    re-validated.  Hard atoms (commit, files, test-run) must still match
+ *    their recorded sha256 / reachability; tampering after verify → reject
+ *    with {@link E_EVIDENCE_STALE}.
+ * 2. **IVTR enforcement** in strict mode: `ivtr_state.currentPhase` MUST be
+ *    `released`; otherwise reject with {@link E_IVTR_INCOMPLETE}.
+ * 3. **Parent-epic lifecycle gate**: child task completion is blocked while
+ *    the parent epic is still in a planning stage (research/consensus/
+ *    architecture_decision/specification/decomposition).  Rejects with
+ *    {@link E_LIFECYCLE_GATE_FAILED}.
+ *
+ * Unlike v2026.4.77 and earlier, `--force` is no longer accepted.  The
+ * dispatch layer rejects `force` with `E_FLAG_REMOVED` before we reach
+ * here. Emergency bypass lives in `cleo verify` via `CLEO_OWNER_OVERRIDE`.
+ *
+ * @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
+ *
+ * @task T815
+ * @task T832
+ * @adr ADR-051
+ * @epic T810
+ */
+export declare function taskCompleteStrict(projectRoot: string, taskId: string, notes?: string): Promise<EngineResult<{
+    task: TaskRecord;
+    autoCompleted?: string[];
+    unblockedTasks?: Array<{
+        id: string;
+        title: string;
+    }>;
+}>>;
+/**
+ * Retrieve the IVTR phase history for a task.
+ *
+ * @remarks
+ * Reads `tasks.ivtr_state` JSON and extracts the `phaseHistory` array.
+ * Returns an empty `ivtrHistory` array when the task has no IVTR state —
+ * this is not an error condition.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param taskId - Task identifier (e.g. "T042")
+ * @returns EngineResult with ivtrHistory array
+ *
+ * @example
+ * ```typescript
+ * const result = await taskShowIvtrHistory('/project', 'T42');
+ * if (result.success) console.log(result.data.ivtrHistory);
+ * ```
+ *
+ * @task T817
+ * @epic T810
+ */
+export declare function taskShowIvtrHistory(projectRoot: string, taskId: string): Promise<EngineResult<{
+    ivtrHistory: IvtrHistoryEntry[];
+}>>;
+/**
+ * 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, opts?: {
+    taskIds?: string[];
+    includeCancelled?: boolean;
+    dryRun?: boolean;
+}): 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.
+ *
+ * When `withBlockers` is `true` each node is annotated with `blockerChain`
+ * and `leafBlockers` so the formatter can render transitive chain information.
+ *
+ * @param projectRoot  - Absolute path to the project root.
+ * @param taskId       - Optional root task ID for subtree.
+ * @param withBlockers - When `true`, annotate each node with blocker chain data.
+ * @returns EngineResult with the hierarchical tree data.
+ *
+ * @example
+ * ```typescript
+ * const result = await taskTree('/project', 'T1');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With blocker chain annotations
+ * const result = await taskTree('/project', undefined, true);
+ * ```
+ *
+ * @task T4657
+ * @task T4790
+ * @task T1206
+ * @epic T4654
+ */
+export declare function taskTree(projectRoot: string, taskId?: string, withBlockers?: boolean): 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