@cleocode/core 2026.3.57 → 2026.3.58

package/dist/tasks/graph-rag.js

@@ -0,0 +1,328 @@
+/**
+ * Semantic relationship discovery for CLEO tasks.
+ * Discovers related tasks via shared labels, description keywords, files, and hierarchy.
+ * Ported from lib/tasks/graph-rag.sh
+ *
+ * @epic T4454
+ * @task T4529
+ */
+/** Common English stopwords for text comparison. */
+const STOPWORDS = new Set([
+    'a',
+    'an',
+    'the',
+    'and',
+    'or',
+    'but',
+    'in',
+    'on',
+    'at',
+    'to',
+    'for',
+    'of',
+    'with',
+    'by',
+    'from',
+    'as',
+    'is',
+    'was',
+    'are',
+    'were',
+    'be',
+    'been',
+    'being',
+    'have',
+    'has',
+    'had',
+    'do',
+    'does',
+    'did',
+    'will',
+    'would',
+    'could',
+    'should',
+    'may',
+    'might',
+    'must',
+    'shall',
+    'can',
+    'this',
+    'that',
+    'these',
+    'those',
+    'i',
+    'you',
+    'he',
+    'she',
+    'it',
+    'we',
+    'they',
+    'what',
+    'which',
+    'who',
+    'when',
+    'where',
+    'why',
+    'how',
+    'all',
+    'each',
+    'every',
+    'both',
+    'few',
+    'more',
+    'most',
+    'other',
+    'some',
+    'such',
+    'no',
+    'nor',
+    'not',
+    'only',
+    'own',
+    'same',
+    'so',
+    'than',
+    'too',
+    'very',
+    'just',
+    'also',
+    'now',
+    'then',
+    'here',
+    'there',
+    'if',
+    'else',
+    'any',
+]);
+/**
+ * Tokenize text: lowercase, remove punctuation, split, remove stopwords.
+ */
+function tokenize(text) {
+    const tokens = text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 0 && !STOPWORDS.has(t));
+    return new Set(tokens);
+}
+/**
+ * Calculate Jaccard similarity between two sets.
+ */
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const item of a) {
+        if (b.has(item))
+            intersection++;
+    }
+    const union = new Set([...a, ...b]).size;
+    if (union === 0)
+        return 0;
+    return intersection / union;
+}
+/**
+ * Discover related tasks by shared labels.
+ */
+export function discoverByLabels(taskId, tasks) {
+    const source = tasks.find((t) => t.id === taskId);
+    if (!source?.labels?.length)
+        return [];
+    const sourceLabels = new Set(source.labels);
+    const results = [];
+    for (const task of tasks) {
+        if (task.id === taskId)
+            continue;
+        if (!task.labels?.length)
+            continue;
+        const taskLabels = new Set(task.labels);
+        const shared = [...sourceLabels].filter((l) => taskLabels.has(l));
+        if (shared.length === 0)
+            continue;
+        const allLabels = new Set([...sourceLabels, ...taskLabels]);
+        const score = shared.length / allLabels.size;
+        results.push({
+            taskId: task.id,
+            type: 'relates-to',
+            reason: `${shared.length} shared label(s): ${shared.join(', ')}`,
+            score: Math.round(score * 100) / 100,
+        });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}
+/**
+ * Discover related tasks by description similarity (keyword-based Jaccard).
+ */
+export function discoverByDescription(taskId, tasks) {
+    const source = tasks.find((t) => t.id === taskId);
+    if (!source)
+        return [];
+    const sourceText = `${source.title ?? ''} ${source.description ?? ''}`;
+    const sourceTokens = tokenize(sourceText);
+    if (sourceTokens.size === 0)
+        return [];
+    const results = [];
+    for (const task of tasks) {
+        if (task.id === taskId)
+            continue;
+        const text = `${task.title ?? ''} ${task.description ?? ''}`;
+        const tokens = tokenize(text);
+        if (tokens.size === 0)
+            continue;
+        const score = jaccardSimilarity(sourceTokens, tokens);
+        if (score <= 0)
+            continue;
+        let sharedCount = 0;
+        for (const t of sourceTokens) {
+            if (tokens.has(t))
+                sharedCount++;
+        }
+        results.push({
+            taskId: task.id,
+            type: 'relates-to',
+            reason: `${sharedCount} shared keyword(s)`,
+            score: Math.round(score * 100) / 100,
+        });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}
+/**
+ * Discover related tasks by shared files.
+ */
+export function discoverByFiles(taskId, tasks) {
+    const source = tasks.find((t) => t.id === taskId);
+    if (!source?.files?.length)
+        return [];
+    const sourceFiles = new Set(source.files);
+    const results = [];
+    for (const task of tasks) {
+        if (task.id === taskId)
+            continue;
+        if (!task.files?.length)
+            continue;
+        const taskFiles = new Set(task.files);
+        const shared = [...sourceFiles].filter((f) => taskFiles.has(f));
+        if (shared.length === 0)
+            continue;
+        const allFiles = new Set([...sourceFiles, ...taskFiles]);
+        const score = shared.length / allFiles.size;
+        const preview = shared.slice(0, 3).join(', ');
+        const suffix = shared.length > 3 ? '...' : '';
+        results.push({
+            taskId: task.id,
+            type: 'relates-to',
+            reason: `${shared.length} shared file(s): ${preview}${suffix}`,
+            score: Math.round(score * 100) / 100,
+        });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}
+/**
+ * Discover related tasks by hierarchical proximity (siblings and cousins).
+ */
+export function discoverByHierarchy(taskId, tasks, options) {
+    const { siblingBoost = 0.15, cousinBoost = 0.08 } = options ?? {};
+    const source = tasks.find((t) => t.id === taskId);
+    if (!source)
+        return [];
+    const results = [];
+    // Find siblings (same parent)
+    if (source.parentId) {
+        const siblings = tasks.filter((t) => t.parentId === source.parentId && t.id !== taskId);
+        for (const sib of siblings) {
+            results.push({
+                taskId: sib.id,
+                type: 'relates-to',
+                reason: `sibling (shared parent ${source.parentId})`,
+                score: siblingBoost,
+                _hierarchyBoost: siblingBoost,
+                _relationship: 'sibling',
+            });
+        }
+        // Find cousins (same grandparent, different parent)
+        const parent = tasks.find((t) => t.id === source.parentId);
+        if (parent?.parentId) {
+            const auntsUncles = tasks.filter((t) => t.parentId === parent.parentId && t.id !== source.parentId);
+            const auntUncleIds = new Set(auntsUncles.map((t) => t.id));
+            const cousins = tasks.filter((t) => t.parentId && auntUncleIds.has(t.parentId));
+            for (const cousin of cousins) {
+                results.push({
+                    taskId: cousin.id,
+                    type: 'relates-to',
+                    reason: `cousin (shared grandparent ${parent.parentId})`,
+                    score: cousinBoost,
+                    _hierarchyBoost: cousinBoost,
+                    _relationship: 'cousin',
+                });
+            }
+        }
+    }
+    return results.sort((a, b) => b.score - a.score);
+}
+/**
+ * Discover related tasks using all methods combined.
+ */
+export function discoverRelatedTasks(taskId, tasks, method = 'auto') {
+    const task = tasks.find((t) => t.id === taskId);
+    if (!task)
+        return [];
+    switch (method) {
+        case 'labels':
+            return discoverByLabels(taskId, tasks);
+        case 'description':
+            return discoverByDescription(taskId, tasks);
+        case 'files':
+            return discoverByFiles(taskId, tasks);
+        case 'hierarchy':
+            return discoverByHierarchy(taskId, tasks);
+        default: {
+            const labels = discoverByLabels(taskId, tasks);
+            const description = discoverByDescription(taskId, tasks);
+            const files = discoverByFiles(taskId, tasks);
+            const hierarchy = discoverByHierarchy(taskId, tasks);
+            // Merge: group by taskId, apply hierarchy boost
+            const combined = new Map();
+            // Add base results (take highest score per taskId)
+            for (const match of [...labels, ...description, ...files]) {
+                const existing = combined.get(match.taskId);
+                if (!existing || match.score > existing.score) {
+                    combined.set(match.taskId, { ...match });
+                }
+            }
+            // Apply hierarchy boosts
+            for (const hMatch of hierarchy) {
+                const existing = combined.get(hMatch.taskId);
+                if (existing) {
+                    existing.score = Math.min(existing.score + (hMatch._hierarchyBoost ?? 0), 1.0);
+                    existing._hierarchyBoost = hMatch._hierarchyBoost;
+                    existing._relationship = hMatch._relationship;
+                }
+                else {
+                    // Task only found via hierarchy
+                    combined.set(hMatch.taskId, { ...hMatch });
+                }
+            }
+            return [...combined.values()].sort((a, b) => b.score - a.score);
+        }
+    }
+}
+/**
+ * Suggest relates entries filtered by threshold.
+ */
+export function suggestRelates(taskId, tasks, threshold = 0.5) {
+    const task = tasks.find((t) => t.id === taskId);
+    if (!task)
+        return [];
+    const all = discoverRelatedTasks(taskId, tasks, 'auto');
+    // Exclude already-related tasks
+    const existingRelates = new Set();
+    // Tasks may have a `relates` field (not in the type but used at runtime)
+    const taskAny = task;
+    if (taskAny.relates) {
+        for (const r of taskAny.relates) {
+            existingRelates.add(r.taskId);
+        }
+    }
+    return all.filter((m) => m.score >= threshold && !existingRelates.has(m.taskId));
+}
+//# sourceMappingURL=graph-rag.js.map

package/dist/tasks/graph-rag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-rag.js","sourceRoot":"","sources":["../../src/tasks/graph-rag.ts"],"names":[],"mappings":"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"}

package/dist/tasks/hierarchy-policy.js

@@ -0,0 +1,149 @@
+/**
+ * Unified hierarchy policy resolution and validation.
+ * Single source of truth for all hierarchy enforcement paths.
+ *
+ * @epic T4454
+ * @task T5001
+ */
+import { getChildren, getDepth, wouldCreateCircle } from './hierarchy.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const ENFORCEMENT_PROFILES = {
+    'llm-agent-first': { maxSiblings: 0, maxActiveSiblings: 0, maxDepth: 3, countDoneInLimit: false },
+    'human-cognitive': { maxSiblings: 7, maxActiveSiblings: 3, maxDepth: 3, countDoneInLimit: false },
+};
+// ---------------------------------------------------------------------------
+// Policy resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a full HierarchyPolicy from config, starting with a profile preset
+ * and overriding with any explicitly set config.hierarchy fields.
+ */
+export function resolveHierarchyPolicy(config) {
+    const hierarchy = config.hierarchy;
+    const profileName = hierarchy?.enforcementProfile ?? 'llm-agent-first';
+    const preset = ENFORCEMENT_PROFILES[profileName] ?? ENFORCEMENT_PROFILES['llm-agent-first'];
+    const resolved = {
+        enforcementProfile: profileName in ENFORCEMENT_PROFILES ? profileName : 'custom',
+        maxDepth: preset.maxDepth,
+        maxSiblings: preset.maxSiblings,
+        maxActiveSiblings: preset.maxActiveSiblings,
+        countDoneInLimit: preset.countDoneInLimit,
+    };
+    // Override with explicit config values when present
+    if (hierarchy) {
+        if (typeof hierarchy.maxDepth === 'number') {
+            resolved.maxDepth = hierarchy.maxDepth;
+        }
+        if (typeof hierarchy.maxSiblings === 'number') {
+            resolved.maxSiblings = hierarchy.maxSiblings;
+        }
+        if (typeof hierarchy.maxActiveSiblings === 'number') {
+            resolved.maxActiveSiblings = hierarchy.maxActiveSiblings;
+        }
+        if (typeof hierarchy.countDoneInLimit === 'boolean') {
+            resolved.countDoneInLimit = hierarchy.countDoneInLimit;
+        }
+    }
+    return resolved;
+}
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+/**
+ * Assert that a parent task exists in the task list.
+ * Returns an error result if not found, null if OK.
+ */
+export function assertParentExists(parentId, tasks) {
+    const parent = tasks.find((t) => t.id === parentId);
+    if (!parent) {
+        return {
+            valid: false,
+            error: { code: 'E_PARENT_NOT_FOUND', message: `Parent task ${parentId} not found` },
+        };
+    }
+    return null;
+}
+/**
+ * Assert that re-parenting would not create a cycle.
+ * Returns an error result if a cycle is detected, null if OK.
+ */
+export function assertNoCycle(taskId, newParentId, tasks) {
+    if (wouldCreateCircle(taskId, newParentId, tasks)) {
+        return {
+            valid: false,
+            error: {
+                code: 'E_CIRCULAR_REFERENCE',
+                message: `Setting parent to ${newParentId} would create a circular reference for task ${taskId}`,
+            },
+        };
+    }
+    return null;
+}
+/**
+ * Count active (non-done, non-cancelled, non-archived) children of a parent.
+ */
+export function countActiveChildren(parentId, tasks) {
+    const activeStatuses = new Set(['pending', 'active', 'blocked']);
+    return tasks.filter((t) => t.parentId === parentId && activeStatuses.has(t.status)).length;
+}
+// ---------------------------------------------------------------------------
+// Primary validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate whether a new task can be placed under the given parent
+ * according to the resolved hierarchy policy.
+ */
+export function validateHierarchyPlacement(parentId, tasks, policy) {
+    // Root placement is always allowed
+    if (parentId === null) {
+        return { valid: true };
+    }
+    // Parent must exist
+    const parentError = assertParentExists(parentId, tasks);
+    if (parentError)
+        return parentError;
+    // Depth check
+    const parentDepth = getDepth(parentId, tasks);
+    if (parentDepth + 1 >= policy.maxDepth) {
+        return {
+            valid: false,
+            error: {
+                code: 'E_DEPTH_EXCEEDED',
+                message: `Maximum nesting depth ${policy.maxDepth} would be exceeded`,
+            },
+        };
+    }
+    // Sibling limit (0 = unlimited)
+    if (policy.maxSiblings > 0) {
+        const children = getChildren(parentId, tasks);
+        const counted = policy.countDoneInLimit
+            ? children.length
+            : children.filter((t) => t.status !== 'done').length;
+        if (counted >= policy.maxSiblings) {
+            return {
+                valid: false,
+                error: {
+                    code: 'E_SIBLING_LIMIT',
+                    message: `Parent ${parentId} already has ${counted} children (limit: ${policy.maxSiblings})`,
+                },
+            };
+        }
+    }
+    // Active sibling limit
+    if (policy.maxActiveSiblings > 0) {
+        const activeCount = countActiveChildren(parentId, tasks);
+        if (activeCount >= policy.maxActiveSiblings) {
+            return {
+                valid: false,
+                error: {
+                    code: 'E_ACTIVE_SIBLING_LIMIT',
+                    message: `Parent ${parentId} already has ${activeCount} active children (limit: ${policy.maxActiveSiblings})`,
+                },
+            };
+        }
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=hierarchy-policy.js.map

package/dist/tasks/hierarchy-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchy-policy.js","sourceRoot":"","sources":["../../src/tasks/hierarchy-policy.ts"],"names":[],"mappings":"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"}

package/dist/tasks/hierarchy.js

@@ -0,0 +1,185 @@
+/**
+ * Task hierarchy operations - parent/child tree traversal and validation.
+ * Ported from lib/tasks/hierarchy.sh
+ *
+ * @epic T4454
+ * @task T4529
+ */
+/**
+ * Get direct children of a task.
+ */
+export function getChildren(taskId, tasks) {
+    return tasks.filter((t) => t.parentId === taskId);
+}
+/**
+ * Get direct child IDs.
+ */
+export function getChildIds(taskId, tasks) {
+    return getChildren(taskId, tasks).map((t) => t.id);
+}
+/**
+ * Get all descendants of a task (recursive).
+ */
+export function getDescendants(taskId, tasks) {
+    const result = [];
+    const queue = [taskId];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        const children = getChildren(current, tasks);
+        for (const child of children) {
+            result.push(child);
+            queue.push(child.id);
+        }
+    }
+    return result;
+}
+/**
+ * Get all descendant IDs (flat list).
+ */
+export function getDescendantIds(taskId, tasks) {
+    return getDescendants(taskId, tasks).map((t) => t.id);
+}
+/**
+ * Get the parent chain (ancestors) from a task up to the root.
+ * Returns ordered from immediate parent to root.
+ */
+export function getParentChain(taskId, tasks) {
+    const chain = [];
+    const taskMap = new Map(tasks.map((t) => [t.id, t]));
+    let current = taskMap.get(taskId);
+    const visited = new Set();
+    while (current?.parentId) {
+        if (visited.has(current.parentId))
+            break; // circular reference guard
+        visited.add(current.parentId);
+        const parent = taskMap.get(current.parentId);
+        if (!parent)
+            break;
+        chain.push(parent);
+        current = parent;
+    }
+    return chain;
+}
+/**
+ * Get the parent chain as IDs.
+ */
+export function getParentChainIds(taskId, tasks) {
+    return getParentChain(taskId, tasks).map((t) => t.id);
+}
+/**
+ * Calculate depth of a task in the hierarchy (0-based).
+ * Root tasks have depth 0, their children depth 1, etc.
+ */
+export function getDepth(taskId, tasks) {
+    return getParentChain(taskId, tasks).length;
+}
+/**
+ * Get the root ancestor of a task.
+ */
+export function getRootAncestor(taskId, tasks) {
+    const chain = getParentChain(taskId, tasks);
+    return chain.length > 0 ? chain[chain.length - 1] : null;
+}
+/**
+ * Check if a task is an ancestor of another.
+ */
+export function isAncestorOf(ancestorId, descendantId, tasks) {
+    const chain = getParentChainIds(descendantId, tasks);
+    return chain.includes(ancestorId);
+}
+/**
+ * Check if a task is a descendant of another.
+ */
+export function isDescendantOf(descendantId, ancestorId, tasks) {
+    return isAncestorOf(ancestorId, descendantId, tasks);
+}
+/**
+ * Get sibling tasks (same parent).
+ */
+export function getSiblings(taskId, tasks) {
+    const task = tasks.find((t) => t.id === taskId);
+    if (!task)
+        return [];
+    if (task.parentId) {
+        return tasks.filter((t) => t.parentId === task.parentId && t.id !== taskId);
+    }
+    // Root-level siblings: tasks with no parent, excluding self
+    return tasks.filter((t) => !t.parentId && t.id !== taskId);
+}
+export function validateHierarchy(parentId, tasks, policy) {
+    if (!parentId) {
+        return { valid: true };
+    }
+    const parent = tasks.find((t) => t.id === parentId);
+    if (!parent) {
+        return {
+            valid: false,
+            error: { code: 'E_PARENT_NOT_FOUND', message: `Parent task ${parentId} not found` },
+        };
+    }
+    // Check depth
+    const parentDepth = getDepth(parentId, tasks);
+    if (parentDepth + 1 >= (policy?.maxDepth ?? 3)) {
+        return {
+            valid: false,
+            error: {
+                code: 'E_DEPTH_EXCEEDED',
+                message: `Maximum nesting depth ${policy?.maxDepth ?? 3} would be exceeded`,
+            },
+        };
+    }
+    // Check sibling limit
+    const existingChildren = getChildren(parentId, tasks);
+    const maxSiblings = policy?.maxSiblings ?? 0;
+    if (maxSiblings > 0 && existingChildren.length >= maxSiblings) {
+        return {
+            valid: false,
+            error: {
+                code: 'E_SIBLING_LIMIT',
+                message: `Parent ${parentId} already has ${maxSiblings} children (max)`,
+            },
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Detect circular reference if parentId were set.
+ */
+export function wouldCreateCircle(taskId, newParentId, tasks) {
+    if (taskId === newParentId)
+        return true;
+    const descendants = getDescendantIds(taskId, tasks);
+    return descendants.includes(newParentId);
+}
+export function buildTree(tasks) {
+    const childrenMap = new Map();
+    for (const task of tasks) {
+        const parentKey = task.parentId ?? null;
+        if (!childrenMap.has(parentKey)) {
+            childrenMap.set(parentKey, []);
+        }
+        childrenMap.get(parentKey).push(task);
+    }
+    function buildNode(task) {
+        const children = (childrenMap.get(task.id) ?? []).map(buildNode);
+        return { task, children };
+    }
+    const roots = childrenMap.get(null) ?? [];
+    return roots.map(buildNode);
+}
+/**
+ * Flatten a tree back to a list (depth-first).
+ */
+export function flattenTree(nodes) {
+    const result = [];
+    for (const node of nodes) {
+        result.push(node.task);
+        result.push(...flattenTree(node.children));
+    }
+    return result;
+}
+//# sourceMappingURL=hierarchy.js.map