@cleocode/core 2026.4.7 → 2026.4.11

package/dist/tasks/task-ops.js

@@ -0,0 +1,1741 @@
+/**
+ * Core task non-CRUD operations - business logic extracted from task-engine.ts.
+ *
+ * These are pure business logic functions that throw on failure and return
+ * data directly (no EngineResult wrapper). The engine layer wraps these
+ * in try/catch to produce EngineResult.
+ *
+ * Covers: next, blockers, tree, deps, relates, relatesAdd, analyze, restore,
+ * unarchive, reorder, reparent, promote, reopen, complexityEstimate, depends,
+ * stats, export, history, lint, batchValidate, import
+ *
+ * @task T4790
+ * @epic T4654
+ */
+import { TASK_STATUSES } from '@cleocode/contracts';
+import { getAccessor } from '../store/data-accessor.js';
+import { getDataPath, readJsonFile as storeReadJsonFile } from '../store/file-utils.js';
+import { canCancel } from './cancel-ops.js';
+import { detectCircularDeps, getBlockedTasks, getLeafBlockers, getReadyTasks, getTransitiveBlockers, validateDependencies, } from './dependency-check.js';
+import { depsReady } from './deps-ready.js';
+// ============================================================================
+// Helpers
+// ============================================================================
+const PRIORITY_SCORE = {
+    critical: 100,
+    high: 75,
+    medium: 50,
+    low: 25,
+};
+async function loadAllTasks(projectRoot) {
+    const accessor = await getAccessor(projectRoot);
+    const { tasks } = await accessor.queryTasks({});
+    return tasks;
+}
+function buildTreeNode(task, childrenMap) {
+    const children = (childrenMap.get(task.id) ?? []).map((child) => buildTreeNode(child, childrenMap));
+    return {
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        type: task.type,
+        children,
+    };
+}
+function buildUpstreamTree(taskId, taskMap, visited = new Set()) {
+    const task = taskMap.get(taskId);
+    if (!task?.depends?.length)
+        return [];
+    const nodes = [];
+    for (const depId of task.depends) {
+        if (visited.has(depId))
+            continue;
+        visited.add(depId);
+        const dep = taskMap.get(depId);
+        if (!dep)
+            continue;
+        nodes.push({
+            id: dep.id,
+            title: dep.title,
+            status: dep.status,
+            type: dep.type,
+            children: buildUpstreamTree(depId, taskMap, visited),
+        });
+    }
+    return nodes;
+}
+function countNodes(nodes) {
+    let count = nodes.length;
+    for (const node of nodes) {
+        count += countNodes(node.children);
+    }
+    return count;
+}
+function measureDependencyDepth(taskId, taskMap, visited = new Set()) {
+    if (visited.has(taskId))
+        return 0;
+    visited.add(taskId);
+    const task = taskMap.get(taskId);
+    if (!task || !task.depends || task.depends.length === 0)
+        return 0;
+    let maxDepth = 0;
+    for (const depId of task.depends) {
+        const depth = 1 + measureDependencyDepth(depId, taskMap, visited);
+        if (depth > maxDepth)
+            maxDepth = depth;
+    }
+    return maxDepth;
+}
+function getHierarchyLimits(projectRoot) {
+    const configPath = getDataPath(projectRoot, 'config.json');
+    const config = storeReadJsonFile(configPath);
+    let maxDepth = 3;
+    let maxSiblings = 0;
+    if (config) {
+        const hierarchy = config.hierarchy;
+        if (hierarchy) {
+            if (typeof hierarchy.maxDepth === 'number')
+                maxDepth = hierarchy.maxDepth;
+            if (typeof hierarchy.maxSiblings === 'number')
+                maxSiblings = hierarchy.maxSiblings;
+        }
+    }
+    return { maxDepth, maxSiblings };
+}
+// ============================================================================
+// taskNext
+// ============================================================================
+/**
+ * Suggest next task to work on based on priority, phase, age, and deps.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param params - Optional scoring configuration
+ * @param params.count - Number of suggestions to return (default: 1)
+ * @param params.explain - When true, include scoring reasons in each suggestion
+ * @returns Ranked suggestions with scores and the total number of eligible candidates
+ *
+ * @remarks
+ * Scoring considers priority weight, current phase alignment, dependency readiness,
+ * task age, and brain success/failure pattern matches. Results are sorted descending by score.
+ *
+ * @example
+ * ```typescript
+ * const { suggestions } = await coreTaskNext('/project', { count: 3, explain: true });
+ * console.log(suggestions[0].id, suggestions[0].score);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskNext(projectRoot, params) {
+    const accessor = await getAccessor(projectRoot);
+    const allTasks = await loadAllTasks(projectRoot);
+    const taskMap = new Map(allTasks.map((t) => [t.id, t]));
+    const projectMeta = await accessor.getMetaValue('project_meta');
+    const currentPhase = projectMeta?.currentPhase ?? null;
+    const candidates = allTasks.filter((t) => t.status === 'pending' && depsReady(t.depends, taskMap));
+    if (candidates.length === 0) {
+        return { suggestions: [], totalCandidates: 0 };
+    }
+    const scored = candidates
+        .map((task) => {
+        const reasons = [];
+        let score = 0;
+        score += PRIORITY_SCORE[task.priority] ?? 50;
+        reasons.push(`priority: ${task.priority} (+${PRIORITY_SCORE[task.priority] ?? 50})`);
+        if (currentPhase && task.phase === currentPhase) {
+            score += 20;
+            reasons.push(`phase alignment: ${currentPhase} (+20)`);
+        }
+        if (depsReady(task.depends, taskMap)) {
+            score += 10;
+            reasons.push('all dependencies satisfied (+10)');
+        }
+        if (task.createdAt) {
+            const ageMs = Date.now() - new Date(task.createdAt).getTime();
+            const ageDays = ageMs / (1000 * 60 * 60 * 24);
+            if (ageDays > 7) {
+                const ageBonus = Math.min(15, Math.floor(ageDays / 7));
+                score += ageBonus;
+                reasons.push(`age: ${Math.floor(ageDays)} days (+${ageBonus})`);
+            }
+        }
+        return { task, score, reasons };
+    })
+        .sort((a, b) => b.score - a.score);
+    // Brain pattern scoring (best-effort)
+    try {
+        const { searchPatterns } = await import('../memory/patterns.js');
+        const [successPatterns, failurePatterns] = await Promise.all([
+            searchPatterns(projectRoot, { type: 'success', limit: 20 }),
+            searchPatterns(projectRoot, { type: 'failure', limit: 20 }),
+        ]);
+        if (successPatterns.length > 0 || failurePatterns.length > 0) {
+            for (const item of scored) {
+                const titleLower = item.task.title.toLowerCase();
+                const labels = (item.task.labels ?? []).map((l) => l.toLowerCase());
+                const matchText = [titleLower, ...labels].join(' ');
+                for (const sp of successPatterns) {
+                    if (matchText.includes(sp.pattern.toLowerCase())) {
+                        item.score += 10;
+                        item.reasons.push(`brain: success pattern match "${sp.pattern}" (+10)`);
+                        break;
+                    }
+                }
+                for (const fp of failurePatterns) {
+                    if (matchText.includes(fp.pattern.toLowerCase())) {
+                        item.score -= 5;
+                        item.reasons.push(`brain: failure pattern match "${fp.pattern}" (-5)`);
+                        break;
+                    }
+                }
+            }
+            scored.sort((a, b) => b.score - a.score);
+        }
+    }
+    catch {
+        // Brain pattern scoring is best-effort
+    }
+    const count = Math.min(params?.count || 1, scored.length);
+    const explain = params?.explain ?? false;
+    const suggestions = scored.slice(0, count).map(({ task, score, reasons }) => ({
+        id: task.id,
+        title: task.title,
+        priority: task.priority,
+        phase: task.phase ?? null,
+        score,
+        ...(explain && { reasons }),
+    }));
+    return { suggestions, totalCandidates: candidates.length };
+}
+// ============================================================================
+// taskBlockers
+// ============================================================================
+/**
+ * Show blocked tasks and analyze blocking chains.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param params - Optional analysis configuration
+ * @param params.analyze - When true, compute transitive blocking chains
+ * @param params.limit - Maximum number of blocked tasks to return (default: 20)
+ * @returns Blocked tasks with optional blocking chains, critical bottleneck tasks, and a summary
+ *
+ * @remarks
+ * Collects both explicitly blocked tasks and dependency-blocked pending tasks.
+ * Critical blockers are the top 5 tasks that appear most frequently in blocking chains.
+ *
+ * @example
+ * ```typescript
+ * const result = await coreTaskBlockers('/project', { analyze: true, limit: 10 });
+ * console.log(result.summary, result.criticalBlockers);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskBlockers(projectRoot, params) {
+    const allTasks = await loadAllTasks(projectRoot);
+    const taskMap = new Map(allTasks.map((t) => [t.id, t]));
+    const analyze = params?.analyze ?? false;
+    const effectiveLimit = params?.limit ?? 20;
+    const blockedTasks = allTasks.filter((t) => t.status === 'blocked');
+    const depBlockedTasks = allTasks.filter((t) => t.status === 'pending' &&
+        t.depends &&
+        t.depends.length > 0 &&
+        t.depends.some((depId) => {
+            const dep = taskMap.get(depId);
+            return dep && dep.status !== 'done' && dep.status !== 'cancelled';
+        }));
+    const tasksAsTask = allTasks;
+    const blockerInfos = [
+        ...blockedTasks.map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            depends: t.depends,
+            blockingChain: analyze ? getTransitiveBlockers(t.id, tasksAsTask) : [],
+        })),
+        ...depBlockedTasks
+            .filter((t) => !blockedTasks.some((bt) => bt.id === t.id))
+            .map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            depends: t.depends,
+            blockingChain: analyze ? getTransitiveBlockers(t.id, tasksAsTask) : [],
+        })),
+    ];
+    const total = blockerInfos.length;
+    const pagedBlockerInfos = blockerInfos.slice(0, effectiveLimit);
+    const blockerCounts = new Map();
+    for (const info of pagedBlockerInfos) {
+        for (const depId of info.blockingChain) {
+            blockerCounts.set(depId, (blockerCounts.get(depId) ?? 0) + 1);
+        }
+    }
+    const criticalBlockers = [...blockerCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([id, count]) => {
+        const task = taskMap.get(id);
+        return { id, title: task?.title ?? 'Unknown', blocksCount: count };
+    });
+    return {
+        blockedTasks: pagedBlockerInfos,
+        criticalBlockers,
+        summary: total === 0 ? 'No blocked tasks found' : `${total} blocked task(s)`,
+        total,
+        limit: effectiveLimit,
+    };
+}
+// ============================================================================
+// taskTree
+// ============================================================================
+/**
+ * Build hierarchy tree for tasks.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - Optional root task ID; when provided, builds the subtree rooted at this task
+ * @returns The tree nodes and total node count
+ *
+ * @remarks
+ * When no taskId is given, returns all root-level tasks with their full subtrees.
+ * When a taskId is given, returns that single task as the root with its descendants.
+ *
+ * @example
+ * ```typescript
+ * const { tree, totalNodes } = await coreTaskTree('/project', 'T042');
+ * console.log(`${totalNodes} nodes in subtree`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskTree(projectRoot, taskId) {
+    const allTasks = await loadAllTasks(projectRoot);
+    if (taskId) {
+        const task = allTasks.find((t) => t.id === taskId);
+        if (!task) {
+            throw new Error(`Task '${taskId}' not found`);
+        }
+    }
+    const childrenMap = new Map();
+    for (const task of allTasks) {
+        const parentKey = task.parentId ?? '__root__';
+        if (!childrenMap.has(parentKey)) {
+            childrenMap.set(parentKey, []);
+        }
+        childrenMap.get(parentKey).push(task);
+    }
+    let roots;
+    if (taskId) {
+        roots = [allTasks.find((t) => t.id === taskId)];
+    }
+    else {
+        roots = childrenMap.get('__root__') ?? [];
+    }
+    const tree = roots.map((root) => buildTreeNode(root, childrenMap));
+    return { tree, totalNodes: countNodes(tree) };
+}
+// ============================================================================
+// taskDeps
+// ============================================================================
+/**
+ * Show dependencies for a task.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The task ID to inspect dependencies for
+ * @returns Upstream and downstream dependencies, unresolved deps, and readiness flag
+ *
+ * @remarks
+ * Returns both the tasks this task depends on (upstream) and the tasks that depend
+ * on it (downstream). Unresolved deps are those not yet done or cancelled.
+ *
+ * @example
+ * ```typescript
+ * const deps = await coreTaskDeps('/project', 'T100');
+ * if (!deps.allDepsReady) console.log('Blocked by:', deps.unresolvedDeps);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskDeps(projectRoot, taskId) {
+    const allTasks = await loadAllTasks(projectRoot);
+    const task = allTasks.find((t) => t.id === taskId);
+    if (!task) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    const taskMap = new Map(allTasks.map((t) => [t.id, t]));
+    const completedIds = new Set(allTasks.filter((t) => t.status === 'done' || t.status === 'cancelled').map((t) => t.id));
+    const dependsOn = (task.depends ?? [])
+        .map((depId) => {
+        const dep = taskMap.get(depId);
+        return dep ? { id: dep.id, title: dep.title, status: dep.status } : null;
+    })
+        .filter((d) => d !== null);
+    const dependedOnBy = allTasks
+        .filter((t) => t.depends?.includes(taskId))
+        .map((t) => ({ id: t.id, title: t.title, status: t.status }));
+    const unresolvedDeps = (task.depends ?? []).filter((depId) => !completedIds.has(depId));
+    return {
+        taskId,
+        dependsOn,
+        dependedOnBy,
+        unresolvedDeps,
+        allDepsReady: unresolvedDeps.length === 0,
+    };
+}
+// ============================================================================
+// taskRelates
+// ============================================================================
+/**
+ * Show task relations.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The task ID to retrieve relations for
+ * @returns The task's relations array and count
+ *
+ * @remarks
+ * Relations are non-dependency links between tasks (e.g. "related-to", "duplicates").
+ * Unlike dependencies, relations do not affect blocking or scheduling.
+ *
+ * @example
+ * ```typescript
+ * const { relations, count } = await coreTaskRelates('/project', 'T050');
+ * console.log(`${count} relations found`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskRelates(projectRoot, taskId) {
+    const allTasks = await loadAllTasks(projectRoot);
+    const task = allTasks.find((t) => t.id === taskId);
+    if (!task) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    const relations = task.relates ?? [];
+    return { taskId, relations, count: relations.length };
+}
+// ============================================================================
+// taskRelatesAdd
+// ============================================================================
+/**
+ * Add a relation between two tasks.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The source task ID
+ * @param relatedId - The target task ID to relate to
+ * @param type - Relation type (e.g. "related-to", "duplicates", "blocks")
+ * @param reason - Optional human-readable reason for the relation
+ * @returns Confirmation of the added relation with source, target, and type
+ *
+ * @remarks
+ * Persists the relation both on the task's `relates` array and in the
+ * `task_relations` table for bidirectional querying.
+ *
+ * @example
+ * ```typescript
+ * const result = await coreTaskRelatesAdd('/project', 'T010', 'T020', 'related-to', 'Shared scope');
+ * console.log(result.added); // true
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskRelatesAdd(projectRoot, taskId, relatedId, type, reason) {
+    const accessor = await getAccessor(projectRoot);
+    const fromTask = await accessor.loadSingleTask(taskId);
+    if (!fromTask) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    const toExists = await accessor.taskExists(relatedId);
+    if (!toExists) {
+        throw new Error(`Task '${relatedId}' not found`);
+    }
+    if (!fromTask.relates) {
+        fromTask.relates = [];
+    }
+    fromTask.relates.push({
+        taskId: relatedId,
+        type,
+        reason: reason || undefined,
+    });
+    fromTask.updatedAt = new Date().toISOString();
+    await accessor.upsertSingleTask(fromTask);
+    // Persist to task_relations table (T5168)
+    await accessor.addRelation(taskId, relatedId, type, reason);
+    return { from: taskId, to: relatedId, type, reason, added: true };
+}
+// ============================================================================
+// taskAnalyze
+// ============================================================================
+/**
+ * Analyze tasks for priority and leverage.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - Optional task or epic ID to scope the analysis; omit for project-wide
+ * @param params - Optional analysis configuration
+ * @param params.tierLimit - Maximum tasks per priority tier in the response (default: 10)
+ * @returns Analysis with recommended next task, bottlenecks, priority tiers, and aggregate metrics
+ *
+ * @remarks
+ * Computes a leverage score per task (how many other tasks it unblocks) and combines
+ * it with priority to produce a ranked recommendation. Bottlenecks are the top 5
+ * incomplete tasks that block the most others.
+ *
+ * @example
+ * ```typescript
+ * const analysis = await coreTaskAnalyze('/project', undefined, { tierLimit: 5 });
+ * if (analysis.recommended) console.log('Work on:', analysis.recommended.id);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskAnalyze(projectRoot, taskId, params) {
+    const allTasks = await loadAllTasks(projectRoot);
+    const effectiveTierLimit = params?.tierLimit ?? 10;
+    const tasks = taskId
+        ? allTasks.filter((t) => t.id === taskId || t.parentId === taskId)
+        : allTasks;
+    const blocksMap = {};
+    for (const task of tasks) {
+        if (task.depends) {
+            for (const dep of task.depends) {
+                if (!blocksMap[dep])
+                    blocksMap[dep] = [];
+                blocksMap[dep].push(task.id);
+            }
+        }
+    }
+    const leverageMap = {};
+    for (const task of tasks) {
+        leverageMap[task.id] = (blocksMap[task.id] ?? []).length;
+    }
+    const actionable = tasks.filter((t) => t.status === 'pending' || t.status === 'active');
+    const blocked = tasks.filter((t) => t.status === 'blocked');
+    const bottlenecks = tasks
+        .filter((t) => (blocksMap[t.id]?.length ?? 0) > 0 && t.status !== 'done')
+        .map((t) => ({ id: t.id, title: t.title, blocksCount: blocksMap[t.id].length }))
+        .sort((a, b) => b.blocksCount - a.blocksCount)
+        .slice(0, 5);
+    const scored = actionable.map((t) => ({
+        id: t.id,
+        title: t.title,
+        leverage: leverageMap[t.id] ?? 0,
+        priority: t.priority,
+    }));
+    scored.sort((a, b) => {
+        const priorityWeight = { critical: 100, high: 50, medium: 20, low: 5 };
+        const aScore = (priorityWeight[a.priority ?? 'medium'] ?? 20) + a.leverage * 10;
+        const bScore = (priorityWeight[b.priority ?? 'medium'] ?? 20) + b.leverage * 10;
+        return bScore - aScore;
+    });
+    const critical = scored.filter((t) => t.priority === 'critical');
+    const high = scored.filter((t) => t.priority === 'high');
+    const normal = scored.filter((t) => t.priority !== 'critical' && t.priority !== 'high');
+    const recommended = scored.length > 0
+        ? {
+            id: scored[0].id,
+            title: scored[0].title,
+            leverage: scored[0].leverage,
+            reason: 'Highest combined priority and leverage score',
+        }
+        : null;
+    const totalLeverage = Object.values(leverageMap).reduce((s, v) => s + v, 0);
+    const avgLeverage = tasks.length > 0 ? Math.round((totalLeverage / tasks.length) * 100) / 100 : 0;
+    return {
+        recommended,
+        bottlenecks,
+        tiers: {
+            critical: critical
+                .slice(0, effectiveTierLimit)
+                .map(({ id, title, leverage }) => ({ id, title, leverage })),
+            high: high
+                .slice(0, effectiveTierLimit)
+                .map(({ id, title, leverage }) => ({ id, title, leverage })),
+            normal: normal
+                .slice(0, effectiveTierLimit)
+                .map(({ id, title, leverage }) => ({ id, title, leverage })),
+        },
+        metrics: {
+            totalTasks: tasks.length,
+            actionable: actionable.length,
+            blocked: blocked.length,
+            avgLeverage,
+        },
+        tierLimit: effectiveTierLimit,
+    };
+}
+// ============================================================================
+// taskRestore
+// ============================================================================
+/**
+ * Restore a cancelled task back to pending.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The cancelled task ID to restore
+ * @param params - Optional restore options
+ * @param params.cascade - When true, also restores cancelled child tasks recursively
+ * @param params.notes - Optional note appended to each restored task's notes array
+ * @returns The task ID, list of restored task IDs, and total count
+ *
+ * @remarks
+ * Only tasks with status "cancelled" can be restored. Restored tasks are set to
+ * "pending" with cancellation metadata cleared. A timestamped note is appended.
+ *
+ * @example
+ * ```typescript
+ * const { restored, count } = await coreTaskRestore('/project', 'T099', { cascade: true });
+ * console.log(`Restored ${count} tasks:`, restored);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskRestore(projectRoot, taskId, params) {
+    const accessor = await getAccessor(projectRoot);
+    const task = await accessor.loadSingleTask(taskId);
+    if (!task) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    if (task.status !== 'cancelled') {
+        throw new Error(`Task '${taskId}' is not cancelled (status: ${task.status}). Only cancelled tasks can be restored.`);
+    }
+    const tasksToRestore = [task];
+    if (params?.cascade) {
+        const findCancelledChildren = async (parentId) => {
+            const children = await accessor.getChildren(parentId);
+            const cancelledChildren = children.filter((t) => t.status === 'cancelled');
+            for (const child of cancelledChildren) {
+                tasksToRestore.push(child);
+                await findCancelledChildren(child.id);
+            }
+        };
+        await findCancelledChildren(taskId);
+    }
+    const now = new Date().toISOString();
+    const restored = [];
+    for (const t of tasksToRestore) {
+        t.status = 'pending';
+        t.cancelledAt = undefined;
+        t.cancellationReason = undefined;
+        t.updatedAt = now;
+        if (!t.notes)
+            t.notes = [];
+        t.notes.push(`[${now}] Restored from cancelled${params?.notes ? ': ' + params.notes : ''}`);
+        restored.push(t.id);
+    }
+    for (const t of tasksToRestore) {
+        await accessor.upsertSingleTask(t);
+    }
+    return { task: taskId, restored, count: restored.length };
+}
+// ============================================================================
+// taskCancel
+// ============================================================================
+/**
+ * Cancel a task (sets status to 'cancelled', a soft terminal state).
+ * Use restore to reverse. Use delete for permanent removal.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The task ID to cancel
+ * @param params - Optional cancel options
+ * @param params.reason - Human-readable cancellation reason stored on the task
+ * @returns Confirmation with cancelled flag and timestamp
+ *
+ * @remarks
+ * Cancellation is a soft terminal state -- the task remains in the database and
+ * can be restored via {@link coreTaskRestore}. Not all statuses are cancellable;
+ * the `canCancel` guard determines eligibility.
+ *
+ * @example
+ * ```typescript
+ * const result = await coreTaskCancel('/project', 'T077', { reason: 'Superseded by T080' });
+ * console.log(result.cancelledAt);
+ * ```
+ *
+ * @task T4529
+ */
+export async function coreTaskCancel(projectRoot, taskId, params) {
+    const accessor = await getAccessor(projectRoot);
+    const task = await accessor.loadSingleTask(taskId);
+    if (!task) {
+        throw new Error(`Task ${taskId} not found`);
+    }
+    const check = canCancel(task);
+    if (!check.allowed) {
+        throw new Error(check.reason);
+    }
+    const cancelledAt = new Date().toISOString();
+    task.status = 'cancelled';
+    task.cancelledAt = cancelledAt;
+    task.cancellationReason = params?.reason ?? undefined;
+    task.updatedAt = cancelledAt;
+    await accessor.upsertSingleTask(task);
+    return { task: taskId, cancelled: true, reason: params?.reason, cancelledAt };
+}
+// ============================================================================
+// taskUnarchive
+// ============================================================================
+/**
+ * Move an archived task back to active tasks.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The archived task ID to unarchive
+ * @param params - Optional unarchive options
+ * @param params.status - Target status for the restored task (default: "pending")
+ * @param params.preserveStatus - When true, keeps the task's original archived status
+ * @returns Confirmation with task ID, title, and resulting status
+ *
+ * @remarks
+ * Removes the task from the archive file and upserts it into the active task store.
+ * Throws if the task already exists in active tasks or is not found in the archive.
+ *
+ * @example
+ * ```typescript
+ * const result = await coreTaskUnarchive('/project', 'T055', { status: 'active' });
+ * console.log(`${result.title} is now ${result.status}`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskUnarchive(projectRoot, taskId, params) {
+    const accessor = await getAccessor(projectRoot);
+    // Check if task already exists in active tasks
+    const existingTask = await accessor.taskExists(taskId);
+    if (existingTask) {
+        throw new Error(`Task '${taskId}' already exists in active tasks`);
+    }
+    const archive = await accessor.loadArchive();
+    if (!archive || !archive.archivedTasks) {
+        throw new Error('No archive file found');
+    }
+    const taskIndex = archive.archivedTasks.findIndex((t) => t.id === taskId);
+    if (taskIndex === -1) {
+        throw new Error(`Task '${taskId}' not found in archive`);
+    }
+    const task = archive.archivedTasks[taskIndex];
+    // Remove archive metadata if present on the raw record
+    if ('_archive' in task) {
+        Reflect.deleteProperty(task, '_archive');
+    }
+    if (!params?.preserveStatus) {
+        const rawStatus = params?.status || 'pending';
+        if (!TASK_STATUSES.includes(rawStatus)) {
+            throw new Error(`Invalid status: ${rawStatus}`);
+        }
+        // rawStatus is validated above as a member of TASK_STATUSES
+        const targetStatus = rawStatus;
+        if (targetStatus !== 'done') {
+            task.completedAt = undefined;
+        }
+    }
+    task.updatedAt = new Date().toISOString();
+    // Fine-grained: upsert the restored task (now active)
+    await accessor.upsertSingleTask(task);
+    return { task: taskId, unarchived: true, title: task.title, status: task.status };
+}
+// ============================================================================
+// taskReorder
+// ============================================================================
+/**
+ * Change task position within its sibling group.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The task ID to reorder
+ * @param position - Target 1-based position within the sibling group
+ * @returns Confirmation with the new position and total sibling count
+ *
+ * @remarks
+ * Reorders by adjusting `position` and `positionVersion` fields on all siblings.
+ * Position is clamped to valid bounds. Uses bulk field updates for efficiency.
+ *
+ * @example
+ * ```typescript
+ * const result = await coreTaskReorder('/project', 'T012', 1);
+ * console.log(`Moved to position ${result.newPosition} of ${result.totalSiblings}`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskReorder(projectRoot, taskId, position) {
+    const accessor = await getAccessor(projectRoot);
+    const task = await accessor.loadSingleTask(taskId);
+    if (!task) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    // Get siblings: tasks with same parentId
+    const parentFilter = task.parentId ? { parentId: task.parentId } : {};
+    const { tasks: siblingCandidates } = await accessor.queryTasks(parentFilter);
+    // For root-level tasks (no parentId), filter to only those without a parentId
+    const allSiblings = task.parentId
+        ? siblingCandidates.sort((a, b) => (a.position ?? 0) - (b.position ?? 0))
+        : siblingCandidates
+            .filter((t) => !t.parentId)
+            .sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+    const currentIndex = allSiblings.findIndex((t) => t.id === taskId);
+    const newIndex = Math.max(0, Math.min(position - 1, allSiblings.length - 1));
+    allSiblings.splice(currentIndex, 1);
+    allSiblings.splice(newIndex, 0, task);
+    // Use bulk SQL for position updates (T025) — updateTaskFields is lighter than upsertSingleTask
+    const now = new Date().toISOString();
+    for (let i = 0; i < allSiblings.length; i++) {
+        const sibling = allSiblings[i];
+        const newPos = i + 1;
+        const newVersion = (sibling.positionVersion ?? 0) + 1;
+        // Only update if position actually changed
+        if (sibling.position !== newPos || sibling.id === taskId) {
+            await accessor.updateTaskFields(sibling.id, {
+                position: newPos,
+                positionVersion: newVersion,
+                updatedAt: now,
+            });
+        }
+        sibling.position = newPos;
+        sibling.positionVersion = newVersion;
+        sibling.updatedAt = now;
+    }
+    return {
+        task: taskId,
+        reordered: true,
+        newPosition: newIndex + 1,
+        totalSiblings: allSiblings.length,
+    };
+}
+// ============================================================================
+// taskReparent
+// ============================================================================
+/**
+ * Move task under a different parent.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The task ID to reparent
+ * @param newParentId - The new parent task ID, or null to promote to root level
+ * @returns Confirmation with old and new parent IDs and optional type change
+ *
+ * @remarks
+ * Validates against circular references, depth limits, and sibling limits from
+ * the project hierarchy config. Automatically adjusts task type based on new depth
+ * (depth 1 = "task", depth >= 2 = "subtask").
+ *
+ * @example
+ * ```typescript
+ * const result = await coreTaskReparent('/project', 'T015', 'T010');
+ * console.log(`Moved from ${result.oldParent} to ${result.newParent}`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskReparent(projectRoot, taskId, newParentId) {
+    const accessor = await getAccessor(projectRoot);
+    const task = await accessor.loadSingleTask(taskId);
+    if (!task) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    const effectiveParentId = newParentId || null;
+    if (!effectiveParentId) {
+        const oldParent = task.parentId ?? null;
+        task.parentId = null;
+        if (task.type === 'subtask')
+            task.type = 'task';
+        task.updatedAt = new Date().toISOString();
+        await accessor.upsertSingleTask(task);
+        return { task: taskId, reparented: true, oldParent, newParent: null, newType: task.type };
+    }
+    const newParent = await accessor.loadSingleTask(effectiveParentId);
+    if (!newParent) {
+        throw new Error(`Parent task '${effectiveParentId}' not found`);
+    }
+    if (newParent.type === 'subtask') {
+        throw new Error(`Cannot parent under subtask '${effectiveParentId}'`);
+    }
+    // Check circular reference using subtree
+    const subtree = await accessor.getSubtree(taskId);
+    if (subtree.some((t) => t.id === effectiveParentId)) {
+        throw new Error(`Moving '${taskId}' under '${effectiveParentId}' would create circular reference`);
+    }
+    // Check depth limit using ancestor chain
+    const ancestors = await accessor.getAncestorChain(effectiveParentId);
+    const parentDepth = ancestors.length;
+    const reparentLimits = getHierarchyLimits(projectRoot);
+    if (parentDepth + 1 >= reparentLimits.maxDepth) {
+        throw new Error(`Move would exceed max depth of ${reparentLimits.maxDepth}`);
+    }
+    // Check sibling limit (0 = unlimited)
+    const children = await accessor.getChildren(effectiveParentId);
+    const siblingCount = children.filter((t) => t.id !== taskId).length;
+    if (reparentLimits.maxSiblings > 0 && siblingCount >= reparentLimits.maxSiblings) {
+        throw new Error(`Cannot add child to ${effectiveParentId}: max siblings (${reparentLimits.maxSiblings}) exceeded`);
+    }
+    const oldParent = task.parentId ?? null;
+    task.parentId = effectiveParentId;
+    const newDepth = parentDepth + 1;
+    if (newDepth === 1)
+        task.type = 'task';
+    else if (newDepth >= 2)
+        task.type = 'subtask';
+    task.updatedAt = new Date().toISOString();
+    await accessor.upsertSingleTask(task);
+    return {
+        task: taskId,
+        reparented: true,
+        oldParent,
+        newParent: effectiveParentId,
+        newType: task.type,
+    };
+}
+// ============================================================================
+// taskPromote
+// ============================================================================
+/**
+ * Promote a subtask to task or task to root.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The task ID to promote
+ * @returns Confirmation with previous parent and whether the type changed
+ *
+ * @remarks
+ * Removes the task's parentId, making it a root-level task. If the task was
+ * a "subtask", its type is changed to "task". No-op if the task is already root-level.
+ *
+ * @example
+ * ```typescript
+ * const result = await coreTaskPromote('/project', 'T025');
+ * if (result.promoted) console.log('Detached from', result.previousParent);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskPromote(projectRoot, taskId) {
+    const accessor = await getAccessor(projectRoot);
+    const task = await accessor.loadSingleTask(taskId);
+    if (!task) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    if (!task.parentId) {
+        return { task: taskId, promoted: false, previousParent: null, typeChanged: false };
+    }
+    const oldParent = task.parentId;
+    task.parentId = null;
+    task.updatedAt = new Date().toISOString();
+    let typeChanged = false;
+    if (task.type === 'subtask') {
+        task.type = 'task';
+        typeChanged = true;
+    }
+    await accessor.upsertSingleTask(task);
+    return { task: taskId, promoted: true, previousParent: oldParent, typeChanged };
+}
+// ============================================================================
+// taskReopen
+// ============================================================================
+/**
+ * Reopen a completed task.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The completed task ID to reopen
+ * @param params - Optional reopen options
+ * @param params.status - Target status after reopening ("pending" or "active", default: "pending")
+ * @param params.reason - Optional reason appended to the task's notes
+ * @returns Confirmation with previous and new status
+ *
+ * @remarks
+ * Only tasks with status "done" can be reopened. Clears the `completedAt` timestamp
+ * and appends a timestamped note recording the reopen event.
+ *
+ * @example
+ * ```typescript
+ * const result = await coreTaskReopen('/project', 'T033', { status: 'active', reason: 'Tests failed' });
+ * console.log(`${result.previousStatus} -> ${result.newStatus}`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskReopen(projectRoot, taskId, params) {
+    const accessor = await getAccessor(projectRoot);
+    const task = await accessor.loadSingleTask(taskId);
+    if (!task) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    if (task.status !== 'done') {
+        throw new Error(`Task '${taskId}' is not completed (status: ${task.status}). Only done tasks can be reopened.`);
+    }
+    const targetStatus = params?.status || 'pending';
+    if (targetStatus !== 'pending' && targetStatus !== 'active') {
+        throw new Error(`Invalid target status: ${targetStatus}. Must be 'pending' or 'active'.`);
+    }
+    const previousStatus = task.status;
+    task.status = targetStatus;
+    task.completedAt = undefined;
+    task.updatedAt = new Date().toISOString();
+    if (!task.notes)
+        task.notes = [];
+    const reason = params?.reason;
+    task.notes.push(`[${task.updatedAt}] Reopened from ${previousStatus}${reason ? ': ' + reason : ''}`);
+    await accessor.upsertSingleTask(task);
+    return { task: taskId, reopened: true, previousStatus, newStatus: targetStatus };
+}
+// ============================================================================
+// taskComplexityEstimate
+// ============================================================================
+/**
+ * Deterministic complexity scoring from task metadata.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param params - Parameters containing the task ID to estimate
+ * @param params.taskId - The task ID to compute complexity for
+ * @returns Complexity size ("small"/"medium"/"large"), numeric score, contributing factors, and metadata counts
+ *
+ * @remarks
+ * Scores are computed from description length, acceptance criteria count, dependency depth,
+ * subtask count, and file reference count. Each factor contributes 0-3 points.
+ * Total score 0-3 = small, 4-7 = medium, 8+ = large.
+ *
+ * @example
+ * ```typescript
+ * const est = await coreTaskComplexityEstimate('/project', { taskId: 'T042' });
+ * console.log(`${est.size} (score: ${est.score})`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskComplexityEstimate(projectRoot, params) {
+    const allTasks = await loadAllTasks(projectRoot);
+    const task = allTasks.find((t) => t.id === params.taskId);
+    if (!task) {
+        throw new Error(`Task '${params.taskId}' not found`);
+    }
+    const factors = [];
+    let score = 0;
+    const descLen = (task.description || '').length;
+    let descScore;
+    let descLabel;
+    if (descLen < 100) {
+        descScore = 1;
+        descLabel = 'short';
+    }
+    else if (descLen < 500) {
+        descScore = 2;
+        descLabel = 'medium';
+    }
+    else {
+        descScore = 3;
+        descLabel = 'long';
+    }
+    score += descScore;
+    factors.push({
+        name: 'descriptionLength',
+        value: descScore,
+        detail: `${descLabel} (${descLen} chars)`,
+    });
+    const acceptanceCount = task.acceptance?.length ?? 0;
+    const acceptanceScore = Math.min(acceptanceCount, 3);
+    score += acceptanceScore;
+    factors.push({
+        name: 'acceptanceCriteria',
+        value: acceptanceScore,
+        detail: `${acceptanceCount} criteria`,
+    });
+    const taskMap = new Map(allTasks.map((t) => [t.id, t]));
+    const dependencyDepth = measureDependencyDepth(params.taskId, taskMap);
+    const depthScore = Math.min(dependencyDepth, 3);
+    score += depthScore;
+    factors.push({ name: 'dependencyDepth', value: depthScore, detail: `depth ${dependencyDepth}` });
+    const subtaskCount = allTasks.filter((t) => t.parentId === params.taskId).length;
+    const subtaskScore = Math.min(subtaskCount, 3);
+    score += subtaskScore;
+    factors.push({ name: 'subtaskCount', value: subtaskScore, detail: `${subtaskCount} subtasks` });
+    const fileCount = task.files?.length ?? 0;
+    const fileScore = Math.min(fileCount, 3);
+    score += fileScore;
+    factors.push({ name: 'fileReferences', value: fileScore, detail: `${fileCount} files` });
+    let size;
+    if (score <= 3)
+        size = 'small';
+    else if (score <= 7)
+        size = 'medium';
+    else
+        size = 'large';
+    return { size, score, factors, dependencyDepth, subtaskCount, fileCount };
+}
+// ============================================================================
+// taskDepsOverview
+// ============================================================================
+/**
+ * Overview of all dependencies across the project.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @returns Project-wide dependency summary including blocked tasks, ready tasks, and validation results
+ *
+ * @remarks
+ * Aggregates dependency data across all tasks to provide a high-level view of
+ * the dependency graph health, including which tasks are blocked and what would unblock them.
+ *
+ * @example
+ * ```typescript
+ * const overview = await coreTaskDepsOverview('/project');
+ * console.log(`${overview.blockedTasks.length} blocked, ${overview.readyTasks.length} ready`);
+ * ```
+ *
+ * @task T5157
+ */
+export async function coreTaskDepsOverview(projectRoot) {
+    const allTasks = await loadAllTasks(projectRoot);
+    const tasksAsTask = allTasks;
+    const tasksWithDeps = allTasks.filter((t) => t.depends && t.depends.length > 0);
+    const blocked = getBlockedTasks(tasksAsTask);
+    const ready = getReadyTasks(tasksAsTask);
+    const validation = validateDependencies(tasksAsTask);
+    return {
+        totalTasks: allTasks.length,
+        tasksWithDeps: tasksWithDeps.length,
+        blockedTasks: blocked.map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            unblockedBy: (t.depends ?? []).filter((depId) => {
+                const dep = allTasks.find((x) => x.id === depId);
+                return dep && dep.status !== 'done' && dep.status !== 'cancelled';
+            }),
+        })),
+        readyTasks: ready
+            .filter((t) => t.status !== 'done' && t.status !== 'cancelled')
+            .map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+        })),
+        validation: {
+            valid: validation.valid,
+            errorCount: validation.errors.length,
+            warningCount: validation.warnings.length,
+        },
+    };
+}
+// ============================================================================
+// taskDepsCycles
+// ============================================================================
+/**
+ * Detect circular dependencies across the project.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @returns Whether cycles exist and the list of detected cycles with their task paths
+ *
+ * @remarks
+ * Iterates through all tasks with dependencies and uses cycle detection to find
+ * circular chains. Each cycle includes the full path (e.g. [A, B, C, A]) and
+ * the tasks involved with their titles.
+ *
+ * @example
+ * ```typescript
+ * const { hasCycles, cycles } = await coreTaskDepsCycles('/project');
+ * if (hasCycles) console.log('Circular deps:', cycles.map(c => c.path.join(' -> ')));
+ * ```
+ *
+ * @task T5157
+ */
+export async function coreTaskDepsCycles(projectRoot) {
+    const allTasks = await loadAllTasks(projectRoot);
+    const tasksAsTask = allTasks;
+    const taskMap = new Map(allTasks.map((t) => [t.id, t]));
+    const visited = new Set();
+    const cycles = [];
+    for (const task of allTasks) {
+        if (visited.has(task.id))
+            continue;
+        if (!task.depends?.length)
+            continue;
+        const cycle = detectCircularDeps(task.id, tasksAsTask);
+        if (cycle.length > 0) {
+            cycles.push({
+                path: cycle,
+                // Deduplicate: detectCircularDeps returns [A,B,C,A] where
+                // last element closes the cycle. Use Set for robustness.
+                tasks: [...new Set(cycle)].map((id) => {
+                    const t = taskMap.get(id);
+                    return { id, title: t?.title ?? 'unknown' };
+                }),
+            });
+            for (const id of cycle) {
+                visited.add(id);
+            }
+        }
+    }
+    return { hasCycles: cycles.length > 0, cycles };
+}
+// ============================================================================
+// taskDepends
+// ============================================================================
+/**
+ * List dependencies for a task in a given direction.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The task ID to inspect
+ * @param direction - Direction to traverse: "upstream" (what this task depends on), "downstream" (what depends on it), or "both"
+ * @param options - Optional display configuration
+ * @param options.tree - When true, includes a recursive upstream dependency tree
+ * @returns Upstream and downstream deps, transitive chain length, leaf blockers, and readiness status
+ *
+ * @remarks
+ * Combines direct dependency lookups with transitive analysis. Leaf blockers are
+ * the deepest unresolved tasks in the dependency chain -- resolving them first
+ * has the most impact on unblocking.
+ *
+ * @example
+ * ```typescript
+ * const deps = await coreTaskDepends('/project', 'T100', 'both', { tree: true });
+ * console.log('Leaf blockers:', deps.leafBlockers.map(b => b.id));
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskDepends(projectRoot, taskId, direction = 'both', options) {
+    const allTasks = await loadAllTasks(projectRoot);
+    const task = allTasks.find((t) => t.id === taskId);
+    if (!task) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    const taskMap = new Map(allTasks.map((t) => [t.id, t]));
+    const upstream = [];
+    if (direction === 'upstream' || direction === 'both') {
+        for (const depId of task.depends ?? []) {
+            const dep = taskMap.get(depId);
+            if (dep) {
+                upstream.push({ id: dep.id, title: dep.title, status: dep.status });
+            }
+        }
+    }
+    const downstream = [];
+    if (direction === 'downstream' || direction === 'both') {
+        for (const t of allTasks) {
+            if (t.depends?.includes(taskId)) {
+                downstream.push({ id: t.id, title: t.title, status: t.status });
+            }
+        }
+    }
+    // Transitive dependency hints
+    const tasksAsTask = allTasks;
+    const transitiveIds = getTransitiveBlockers(taskId, tasksAsTask);
+    const unresolvedChain = transitiveIds.length;
+    const leafIds = getLeafBlockers(taskId, tasksAsTask);
+    const leafBlockers = leafIds.map((id) => {
+        const t = taskMap.get(id);
+        return { id: t.id, title: t.title, status: t.status };
+    });
+    const allDepsReady = unresolvedChain === 0;
+    const hint = unresolvedChain > 0
+        ? `Run 'ct deps show ${taskId} --tree' for full dependency graph`
+        : undefined;
+    // Optional upstream tree
+    let upstreamTree;
+    if (options?.tree) {
+        upstreamTree = buildUpstreamTree(taskId, taskMap);
+    }
+    return {
+        taskId,
+        direction,
+        upstream,
+        downstream,
+        unresolvedChain,
+        leafBlockers,
+        allDepsReady,
+        ...(hint && { hint }),
+        ...(upstreamTree && { upstreamTree }),
+    };
+}
+// ============================================================================
+// taskStats
+// ============================================================================
+/**
+ * Compute task statistics.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param epicId - Optional epic ID to scope stats to that subtree
+ * @returns Status counts, priority distribution, and type distribution
+ *
+ * @remarks
+ * When an epicId is provided, statistics are scoped to that epic and all its
+ * transitive children. Without an epicId, stats cover the entire project.
+ *
+ * @example
+ * ```typescript
+ * const stats = await coreTaskStats('/project', 'T001');
+ * console.log(`${stats.done}/${stats.total} complete`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskStats(projectRoot, epicId) {
+    const allTasks = await loadAllTasks(projectRoot);
+    let tasks = allTasks;
+    if (epicId) {
+        const epicIds = new Set();
+        epicIds.add(epicId);
+        const collectChildren = (parentId) => {
+            for (const t of allTasks) {
+                if (t.parentId === parentId && !epicIds.has(t.id)) {
+                    epicIds.add(t.id);
+                    collectChildren(t.id);
+                }
+            }
+        };
+        collectChildren(epicId);
+        tasks = allTasks.filter((t) => epicIds.has(t.id));
+    }
+    const byStatus = {};
+    const byPriority = {};
+    const byType = {};
+    for (const task of tasks) {
+        byStatus[task.status] = (byStatus[task.status] ?? 0) + 1;
+        byPriority[task.priority] = (byPriority[task.priority] ?? 0) + 1;
+        const taskType = task.type ?? 'task';
+        byType[taskType] = (byType[taskType] ?? 0) + 1;
+    }
+    return {
+        total: tasks.length,
+        pending: byStatus['pending'] ?? 0,
+        active: byStatus['active'] ?? 0,
+        blocked: byStatus['blocked'] ?? 0,
+        done: byStatus['done'] ?? 0,
+        cancelled: byStatus['cancelled'] ?? 0,
+        byPriority,
+        byType,
+    };
+}
+// ============================================================================
+// taskExport
+// ============================================================================
+/**
+ * Export tasks as JSON or CSV.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param params - Optional export configuration
+ * @param params.format - Output format: "json" (default) or "csv"
+ * @param params.status - Filter to only tasks with this status
+ * @param params.parent - Filter to tasks under this parent ID (recursive)
+ * @returns Export payload with format, content/tasks, and task count
+ *
+ * @remarks
+ * CSV output includes columns: id, title, status, priority, type, parentId, createdAt.
+ * JSON output returns the full task objects. Both formats support status and parent filtering.
+ *
+ * @example
+ * ```typescript
+ * const result = await coreTaskExport('/project', { format: 'csv', status: 'done' });
+ * console.log(result.content); // CSV string
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskExport(projectRoot, params) {
+    const allTasks = await loadAllTasks(projectRoot);
+    let tasks = allTasks;
+    if (params?.status) {
+        tasks = tasks.filter((t) => t.status === params.status);
+    }
+    if (params?.parent) {
+        const parentIds = new Set();
+        parentIds.add(params.parent);
+        const collectChildren = (parentId) => {
+            for (const t of allTasks) {
+                if (t.parentId === parentId && !parentIds.has(t.id)) {
+                    parentIds.add(t.id);
+                    collectChildren(t.id);
+                }
+            }
+        };
+        collectChildren(params.parent);
+        tasks = tasks.filter((t) => parentIds.has(t.id));
+    }
+    if (params?.format === 'csv') {
+        const headers = ['id', 'title', 'status', 'priority', 'type', 'parentId', 'createdAt'];
+        const rows = tasks.map((t) => [
+            t.id,
+            `"${(t.title || '').replace(/"/g, '""')}"`,
+            t.status,
+            t.priority,
+            t.type ?? 'task',
+            t.parentId ?? '',
+            t.createdAt,
+        ].join(','));
+        const csv = [headers.join(','), ...rows].join('\n');
+        return { format: 'csv', content: csv, taskCount: tasks.length };
+    }
+    return { format: 'json', tasks, taskCount: tasks.length };
+}
+// ============================================================================
+// taskHistory
+// ============================================================================
+/**
+ * Get task history from the audit log.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - The task ID to retrieve history for
+ * @param limit - Maximum number of history entries to return (default: 100)
+ * @returns Array of audit log entries ordered by timestamp descending
+ *
+ * @remarks
+ * Queries the SQLite audit_log table for all operations on the given task.
+ * Returns an empty array if the database is unavailable or no entries exist.
+ *
+ * @example
+ * ```typescript
+ * const history = await coreTaskHistory('/project', 'T042', 10);
+ * for (const entry of history) console.log(entry.timestamp, entry.operation);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskHistory(projectRoot, taskId, limit) {
+    try {
+        const { getDb } = await import('../store/sqlite.js');
+        const { auditLog } = await import('../store/tasks-schema.js');
+        const { sql } = await import('drizzle-orm');
+        const db = await getDb(projectRoot);
+        const maxRows = limit && limit > 0 ? limit : 100;
+        const rows = await db.all(sql `SELECT * FROM ${auditLog}
+          WHERE ${auditLog.taskId} = ${taskId}
+          ORDER BY ${auditLog.timestamp} DESC
+          LIMIT ${maxRows}`);
+        return rows.map((row) => ({
+            id: row.id,
+            timestamp: row.timestamp,
+            operation: row.operation ?? row.action,
+            action: row.action,
+            taskId: row.task_id,
+            actor: row.actor,
+            details: row.details_json ? JSON.parse(row.details_json) : {},
+            before: row.before_json ? JSON.parse(row.before_json) : undefined,
+            after: row.after_json ? JSON.parse(row.after_json) : undefined,
+            domain: row.domain,
+            sessionId: row.session_id,
+            requestId: row.request_id,
+            durationMs: row.duration_ms,
+            success: row.success === null ? undefined : row.success === 1,
+            source: row.source,
+            gateway: row.gateway,
+            error: row.error_message,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+// ============================================================================
+// taskLint
+// ============================================================================
+/**
+ * Lint tasks for common issues.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskId - Optional task ID to lint; omit to lint all tasks
+ * @returns Array of lint issues with severity, rule name, and descriptive message
+ *
+ * @remarks
+ * Checks for: duplicate IDs, missing titles, missing descriptions, identical
+ * title/description, duplicate descriptions, invalid statuses, future timestamps,
+ * invalid parent references, and invalid dependency references.
+ *
+ * @example
+ * ```typescript
+ * const issues = await coreTaskLint('/project');
+ * const errors = issues.filter(i => i.severity === 'error');
+ * console.log(`${errors.length} errors found`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskLint(projectRoot, taskId) {
+    const allTasks = await loadAllTasks(projectRoot);
+    const tasks = taskId ? allTasks.filter((t) => t.id === taskId) : allTasks;
+    if (taskId && tasks.length === 0) {
+        throw new Error(`Task '${taskId}' not found`);
+    }
+    const issues = [];
+    const allDescriptions = new Set();
+    const allIds = new Set();
+    for (const task of allTasks) {
+        if (allIds.has(task.id)) {
+            issues.push({
+                taskId: task.id,
+                severity: 'error',
+                rule: 'unique-id',
+                message: `Duplicate task ID: ${task.id}`,
+            });
+        }
+        allIds.add(task.id);
+        if (taskId && task.id !== taskId) {
+            if (task.description)
+                allDescriptions.add(task.description.toLowerCase());
+            continue;
+        }
+        if (!task.title || task.title.trim().length === 0) {
+            issues.push({
+                taskId: task.id,
+                severity: 'error',
+                rule: 'title-required',
+                message: 'Task is missing a title',
+            });
+        }
+        if (!task.description || task.description.trim().length === 0) {
+            issues.push({
+                taskId: task.id,
+                severity: 'warning',
+                rule: 'description-required',
+                message: 'Task is missing a description',
+            });
+        }
+        if (task.title && task.description && task.title.trim() === task.description.trim()) {
+            issues.push({
+                taskId: task.id,
+                severity: 'warning',
+                rule: 'title-description-different',
+                message: 'Title and description should not be identical',
+            });
+        }
+        if (task.description) {
+            const descLower = task.description.toLowerCase();
+            if (allDescriptions.has(descLower)) {
+                issues.push({
+                    taskId: task.id,
+                    severity: 'warning',
+                    rule: 'unique-description',
+                    message: 'Duplicate task description found',
+                });
+            }
+            allDescriptions.add(descLower);
+        }
+        if (!TASK_STATUSES.includes(task.status)) {
+            issues.push({
+                taskId: task.id,
+                severity: 'error',
+                rule: 'valid-status',
+                message: `Invalid status: ${task.status}`,
+            });
+        }
+        const now = new Date();
+        if (task.createdAt && new Date(task.createdAt) > now) {
+            issues.push({
+                taskId: task.id,
+                severity: 'warning',
+                rule: 'no-future-timestamps',
+                message: 'createdAt is in the future',
+            });
+        }
+        if (task.parentId && !allTasks.some((t) => t.id === task.parentId)) {
+            issues.push({
+                taskId: task.id,
+                severity: 'error',
+                rule: 'valid-parent',
+                message: `Parent task '${task.parentId}' does not exist`,
+            });
+        }
+        for (const depId of task.depends ?? []) {
+            if (!allTasks.some((t) => t.id === depId)) {
+                issues.push({
+                    taskId: task.id,
+                    severity: 'warning',
+                    rule: 'valid-dependency',
+                    message: `Dependency '${depId}' does not exist`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ============================================================================
+// taskBatchValidate
+// ============================================================================
+/**
+ * Validate multiple tasks at once.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param taskIds - Array of task IDs to validate
+ * @param checkMode - Validation depth: "full" runs all checks, "quick" checks only title/description/status
+ * @returns Per-task validation results and an aggregate summary with error/warning counts
+ *
+ * @remarks
+ * In "full" mode, additional checks include title-description equality, parent existence,
+ * dependency existence, and future timestamp detection. Tasks that are not found are
+ * reported as errors.
+ *
+ * @example
+ * ```typescript
+ * const { summary } = await coreTaskBatchValidate('/project', ['T001', 'T002'], 'full');
+ * console.log(`${summary.validTasks}/${summary.totalTasks} valid`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskBatchValidate(projectRoot, taskIds, checkMode = 'full') {
+    const allTasks = await loadAllTasks(projectRoot);
+    const results = {};
+    let totalErrors = 0;
+    let totalWarnings = 0;
+    for (const id of taskIds) {
+        const task = allTasks.find((t) => t.id === id);
+        if (!task) {
+            results[id] = [{ severity: 'error', rule: 'exists', message: `Task '${id}' not found` }];
+            totalErrors++;
+            continue;
+        }
+        const taskIssues = [];
+        if (!task.title || task.title.trim().length === 0) {
+            taskIssues.push({ severity: 'error', rule: 'title-required', message: 'Missing title' });
+        }
+        if (!task.description || task.description.trim().length === 0) {
+            taskIssues.push({
+                severity: 'warning',
+                rule: 'description-required',
+                message: 'Missing description',
+            });
+        }
+        if (!TASK_STATUSES.includes(task.status)) {
+            taskIssues.push({
+                severity: 'error',
+                rule: 'valid-status',
+                message: `Invalid status: ${task.status}`,
+            });
+        }
+        if (checkMode === 'full') {
+            if (task.title && task.description && task.title.trim() === task.description.trim()) {
+                taskIssues.push({
+                    severity: 'warning',
+                    rule: 'title-description-different',
+                    message: 'Title equals description',
+                });
+            }
+            if (task.parentId && !allTasks.some((t) => t.id === task.parentId)) {
+                taskIssues.push({
+                    severity: 'error',
+                    rule: 'valid-parent',
+                    message: `Parent '${task.parentId}' not found`,
+                });
+            }
+            for (const depId of task.depends ?? []) {
+                if (!allTasks.some((t) => t.id === depId)) {
+                    taskIssues.push({
+                        severity: 'warning',
+                        rule: 'valid-dependency',
+                        message: `Dependency '${depId}' not found`,
+                    });
+                }
+            }
+            const now = new Date();
+            if (task.createdAt && new Date(task.createdAt) > now) {
+                taskIssues.push({
+                    severity: 'warning',
+                    rule: 'no-future-timestamps',
+                    message: 'createdAt in future',
+                });
+            }
+        }
+        results[id] = taskIssues;
+        totalErrors += taskIssues.filter((i) => i.severity === 'error').length;
+        totalWarnings += taskIssues.filter((i) => i.severity === 'warning').length;
+    }
+    const invalidTasks = Object.values(results).filter((issues) => issues.some((i) => i.severity === 'error')).length;
+    return {
+        results,
+        summary: {
+            totalTasks: taskIds.length,
+            validTasks: taskIds.length - invalidTasks,
+            invalidTasks,
+            totalIssues: totalErrors + totalWarnings,
+            errors: totalErrors,
+            warnings: totalWarnings,
+        },
+    };
+}
+// ============================================================================
+// taskImport
+// ============================================================================
+/**
+ * Import tasks from a JSON source string.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root directory
+ * @param source - JSON string containing an array of tasks or an object with a `tasks` array
+ * @param overwrite - When true, overwrites existing tasks with matching IDs; otherwise skips them
+ * @returns Import summary with counts of imported, skipped, errors, and optional ID remap table
+ *
+ * @remarks
+ * When a task ID collides with an existing one and overwrite is false, a new sequential
+ * ID is assigned and recorded in the remapTable. Tasks missing required id or title
+ * fields are skipped with an error message.
+ *
+ * @example
+ * ```typescript
+ * const json = JSON.stringify([{ id: 'T500', title: 'New task', status: 'pending', priority: 'medium' }]);
+ * const result = await coreTaskImport('/project', json, false);
+ * console.log(`Imported ${result.imported}, skipped ${result.skipped}`);
+ * ```
+ *
+ * @task T4790
+ */
+export async function coreTaskImport(projectRoot, source, overwrite) {
+    const accessor = await getAccessor(projectRoot);
+    // Load all existing task IDs using queryTasks (bulk operation needs full ID set)
+    const { tasks: existingTasks } = await accessor.queryTasks({});
+    let importData;
+    try {
+        importData = JSON.parse(source);
+    }
+    catch {
+        throw new Error('Invalid JSON in import source');
+    }
+    let importTasks = [];
+    if (Array.isArray(importData)) {
+        importTasks = importData;
+    }
+    else if (typeof importData === 'object' && importData !== null) {
+        const data = importData;
+        if (Array.isArray(data.tasks)) {
+            importTasks = data.tasks;
+        }
+    }
+    if (importTasks.length === 0) {
+        return { imported: 0, skipped: 0, errors: ['No tasks found in import source'] };
+    }
+    const existingIds = new Set(existingTasks.map((t) => t.id));
+    const allIds = new Set(existingTasks.map((t) => t.id));
+    const errors = [];
+    let imported = 0;
+    let skipped = 0;
+    const remapTable = {};
+    let nextIdNum = 0;
+    for (const t of existingTasks) {
+        const num = parseInt(t.id.replace('T', ''), 10);
+        if (!Number.isNaN(num) && num > nextIdNum)
+            nextIdNum = num;
+    }
+    for (const importTask of importTasks) {
+        if (!importTask.id || !importTask.title) {
+            errors.push(`Skipped task with missing id or title`);
+            skipped++;
+            continue;
+        }
+        if (existingIds.has(importTask.id) && !overwrite) {
+            skipped++;
+            continue;
+        }
+        let newId = importTask.id;
+        if (allIds.has(importTask.id) && !overwrite) {
+            nextIdNum++;
+            newId = `T${String(nextIdNum).padStart(3, '0')}`;
+            remapTable[importTask.id] = newId;
+        }
+        const now = new Date().toISOString();
+        const newTask = {
+            ...importTask,
+            id: newId,
+            createdAt: importTask.createdAt || now,
+            updatedAt: now,
+        };
+        // Use targeted upsert per task instead of bulk saveTaskFile
+        await accessor.upsertSingleTask(newTask);
+        allIds.add(newId);
+        imported++;
+    }
+    return {
+        imported,
+        skipped,
+        errors,
+        ...(Object.keys(remapTable).length > 0 ? { remapTable } : {}),
+    };
+}
+//# sourceMappingURL=task-ops.js.map