@cleocode/core 2026.3.58 → 2026.3.60

package/src/intelligence/__tests__/impact.test.ts

@@ -8,13 +8,19 @@
  *   - Blast radius calculation
  *   - Critical path detection
  *   - Edge cases (orphan tasks, circular refs, no deps)
+ *   - predictImpact: free-text change description matching (T043)
  *
  * @module intelligence
  */
 
 import type { DataAccessor, Task } from '@cleocode/contracts';
 import { describe, expect, it } from 'vitest';
-import { analyzeChangeImpact, analyzeTaskImpact, calculateBlastRadius } from '../impact.js';
+import {
+  analyzeChangeImpact,
+  analyzeTaskImpact,
+  calculateBlastRadius,
+  predictImpact,
+} from '../impact.js';
 
 // ============================================================================
 // Test Helpers
@@ -451,3 +457,161 @@ describe('calculateBlastRadius', () => {
     expect(result.transitiveCount).toBe(2);
   });
 });
+
+// ============================================================================
+// predictImpact (T043)
+// ============================================================================
+
+describe('predictImpact', () => {
+  it('returns empty report when no tasks match the change description', async () => {
+    const tasks = [
+      makeTask({ id: 'T001', title: 'Set up CI pipeline', description: 'Configure CI runner' }),
+      makeTask({ id: 'T002', title: 'Write unit tests', description: 'Add test coverage' }),
+    ];
+    const acc = mockAccessor(tasks);
+
+    const result = await predictImpact('authentication login oauth', undefined, acc);
+
+    expect(result.change).toBe('authentication login oauth');
+    expect(result.matchedTasks).toHaveLength(0);
+    expect(result.affectedTasks).toHaveLength(0);
+    expect(result.totalAffected).toBe(0);
+    expect(result.summary).toContain('No tasks matched');
+  });
+
+  it('returns direct match when task title contains change keywords', async () => {
+    const tasks = [
+      makeTask({
+        id: 'T001',
+        title: 'Implement authentication module',
+        description: 'Add JWT auth',
+      }),
+      makeTask({ id: 'T002', title: 'Set up database schema', description: 'Create tables' }),
+    ];
+    const acc = mockAccessor(tasks);
+
+    const result = await predictImpact('authentication module', undefined, acc);
+
+    expect(result.matchedTasks).toHaveLength(1);
+    expect(result.matchedTasks[0]?.id).toBe('T001');
+    expect(result.matchedTasks[0]?.exposure).toBe('direct');
+    expect(result.totalAffected).toBe(1);
+  });
+
+  it('traces downstream dependents from matched seed tasks', async () => {
+    const tasks = [
+      makeTask({ id: 'T001', title: 'authentication service implementation', description: '' }),
+      makeTask({
+        id: 'T002',
+        title: 'User login form',
+        description: 'Depends on auth service',
+        depends: ['T001'],
+      }),
+      makeTask({
+        id: 'T003',
+        title: 'Dashboard access control',
+        description: 'Requires user login',
+        depends: ['T002'],
+      }),
+      makeTask({
+        id: 'T004',
+        title: 'Unrelated database migration',
+        description: 'Schema changes',
+      }),
+    ];
+    const acc = mockAccessor(tasks);
+
+    const result = await predictImpact('authentication service', undefined, acc);
+
+    // T001 is the direct match (seed)
+    expect(result.matchedTasks.map((t) => t.id)).toContain('T001');
+
+    // T002 and T003 should be in affectedTasks as dependents/transitive
+    const ids = result.affectedTasks.map((t) => t.id);
+    expect(ids).toContain('T001');
+    expect(ids).toContain('T002');
+    expect(ids).toContain('T003');
+    // T004 is unrelated and should not appear
+    expect(ids).not.toContain('T004');
+  });
+
+  it('classifies exposure correctly: direct, dependent, transitive', async () => {
+    const tasks = [
+      makeTask({ id: 'T001', title: 'auth login service', description: '' }),
+      makeTask({ id: 'T002', title: 'Session management', description: '', depends: ['T001'] }),
+      makeTask({ id: 'T003', title: 'Profile page', description: '', depends: ['T002'] }),
+    ];
+    const acc = mockAccessor(tasks);
+
+    const result = await predictImpact('auth login', undefined, acc);
+
+    const t1 = result.affectedTasks.find((t) => t.id === 'T001');
+    const t2 = result.affectedTasks.find((t) => t.id === 'T002');
+    const t3 = result.affectedTasks.find((t) => t.id === 'T003');
+
+    expect(t1?.exposure).toBe('direct');
+    expect(t2?.exposure).toBe('dependent');
+    expect(t3?.exposure).toBe('transitive');
+  });
+
+  it('sorts affectedTasks: direct first, then dependent, then transitive', async () => {
+    const tasks = [
+      makeTask({ id: 'T001', title: 'auth service core', description: '' }),
+      makeTask({ id: 'T002', title: 'Login controller', description: '', depends: ['T001'] }),
+      makeTask({ id: 'T003', title: 'Session store', description: '', depends: ['T002'] }),
+    ];
+    const acc = mockAccessor(tasks);
+
+    const result = await predictImpact('auth service', undefined, acc);
+
+    const exposures = result.affectedTasks.map((t) => t.exposure);
+    // direct must come before dependent which must come before transitive
+    const directIdx = exposures.indexOf('direct');
+    const dependentIdx = exposures.indexOf('dependent');
+    const transitiveIdx = exposures.indexOf('transitive');
+
+    if (directIdx !== -1 && dependentIdx !== -1) {
+      expect(directIdx).toBeLessThan(dependentIdx);
+    }
+    if (dependentIdx !== -1 && transitiveIdx !== -1) {
+      expect(dependentIdx).toBeLessThan(transitiveIdx);
+    }
+  });
+
+  it('respects matchLimit parameter', async () => {
+    const tasks = [
+      makeTask({ id: 'T001', title: 'auth module setup', description: '' }),
+      makeTask({ id: 'T002', title: 'auth token generation', description: '' }),
+      makeTask({ id: 'T003', title: 'auth session management', description: '' }),
+    ];
+    const acc = mockAccessor(tasks);
+
+    // Limit to 1 seed
+    const result = await predictImpact('auth', undefined, acc, 1);
+
+    // Only 1 direct match seeded
+    expect(result.matchedTasks).toHaveLength(1);
+  });
+
+  it('produces a meaningful summary string', async () => {
+    const tasks = [
+      makeTask({ id: 'T001', title: 'auth service', description: '' }),
+      makeTask({ id: 'T002', title: 'Login page', description: '', depends: ['T001'] }),
+    ];
+    const acc = mockAccessor(tasks);
+
+    const result = await predictImpact('auth service', undefined, acc);
+
+    expect(result.summary).toContain('auth service');
+    expect(result.summary).toMatch(/\d+ task/);
+  });
+
+  it('downstreamCount is 0 for leaf tasks with no dependents', async () => {
+    const tasks = [makeTask({ id: 'T001', title: 'auth service core', description: '' })];
+    const acc = mockAccessor(tasks);
+
+    const result = await predictImpact('auth service', undefined, acc);
+
+    expect(result.affectedTasks[0]?.downstreamCount).toBe(0);
+  });
+});

package/src/intelligence/impact.ts

@@ -6,6 +6,7 @@
  *   - Task impact assessment (direct + transitive dependents)
  *   - Change impact prediction (cancel, block, complete, reprioritize)
  *   - Blast radius calculation (scope quantification)
+ *   - Free-text impact prediction (predictImpact) — T043
  *
  * @module intelligence
  */
@@ -22,6 +23,8 @@ import type {
   ChangeImpact,
   ChangeType,
   ImpactAssessment,
+  ImpactedTask,
+  ImpactReport,
 } from './types.js';
 
 // ============================================================================
@@ -636,3 +639,203 @@ function generateRecommendation(
       );
   }
 }
+
+// ============================================================================
+// Free-text Impact Prediction (T043)
+// ============================================================================
+
+/**
+ * Score a task against a change description using simple keyword matching.
+ *
+ * Normalises both strings to lowercase and counts overlapping tokens (words).
+ * Returns a score in [0, 1] — 1 meaning every non-trivial token in the change
+ * description was found in the task text.
+ */
+function scoreTaskMatch(change: string, task: Task): number {
+  const STOP_WORDS = new Set([
+    'a',
+    'an',
+    'the',
+    'and',
+    'or',
+    'in',
+    'of',
+    'to',
+    'for',
+    'with',
+    'on',
+    'at',
+    'by',
+    'is',
+    'it',
+    'be',
+    'as',
+    'if',
+    'do',
+    'not',
+  ]);
+
+  const tokenise = (text: string): string[] =>
+    text
+      .toLowerCase()
+      .split(/\W+/)
+      .filter((t) => t.length > 2 && !STOP_WORDS.has(t));
+
+  const changeTokens = new Set(tokenise(change));
+  if (changeTokens.size === 0) return 0;
+
+  const taskText = `${task.title ?? ''} ${task.description ?? ''}`;
+  const taskTokens = new Set(tokenise(taskText));
+
+  let matches = 0;
+  for (const token of changeTokens) {
+    if (taskTokens.has(token)) matches++;
+  }
+
+  return matches / changeTokens.size;
+}
+
+/**
+ * Predict the downstream impact of a free-text change description.
+ *
+ * Uses fuzzy keyword matching to identify candidate tasks that relate to
+ * the change, then walks the reverse dependency graph to enumerate all
+ * downstream tasks that may be affected.
+ *
+ * @remarks
+ * The matching is purely lexical (no embeddings). Tasks are ranked by
+ * how many tokens from the change description appear in their title and
+ * description. The top `matchLimit` (default: 5) matched tasks are used
+ * as seeds for downstream dependency tracing.
+ *
+ * @example
+ * ```ts
+ * import { predictImpact } from '@cleocode/core';
+ *
+ * const report = await predictImpact('Modify authentication flow', process.cwd());
+ * console.log(report.summary);
+ * // "3 tasks matched 'Modify authentication flow'; 7 downstream tasks affected."
+ * for (const task of report.affectedTasks) {
+ *   console.log(`${task.id} (${task.exposure}): ${task.reason}`);
+ * }
+ * ```
+ *
+ * @param change - Free-text description of the proposed change (e.g. "Modify X")
+ * @param cwd - Working directory used to locate the tasks database
+ * @param accessor - Optional pre-created DataAccessor (useful in tests)
+ * @param matchLimit - Maximum number of seed tasks to match (default: 5)
+ * @returns Full impact prediction report
+ */
+export async function predictImpact(
+  change: string,
+  cwd?: string,
+  accessor?: DataAccessor,
+  matchLimit = 5,
+): Promise<ImpactReport> {
+  const acc = accessor ?? (await getAccessor(cwd));
+  const tasks = await loadAllTasks(acc);
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+  const dependentsMap = buildDependentsMap(tasks);
+
+  // --- Step 1: Score every task against the change description ---
+  const scored = tasks
+    .map((t) => ({ task: t, score: scoreTaskMatch(change, t) }))
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  const seeds = scored.slice(0, matchLimit).map(({ task }) => task);
+
+  if (seeds.length === 0) {
+    return {
+      change,
+      matchedTasks: [],
+      affectedTasks: [],
+      totalAffected: 0,
+      summary: `No tasks matched the change description "${change}".`,
+    };
+  }
+
+  // --- Step 2: Collect all affected task IDs via reverse dependency graph ---
+  const directMatchIds = new Set(seeds.map((t) => t.id));
+
+  // Map: taskId -> exposure level
+  const exposureMap = new Map<string, ImpactedTask['exposure']>();
+  for (const id of directMatchIds) {
+    exposureMap.set(id, 'direct');
+  }
+
+  // BFS over dependents for each seed
+  for (const seed of seeds) {
+    const transitive = collectTransitiveDependents(seed.id, dependentsMap);
+    for (const depId of transitive) {
+      if (!exposureMap.has(depId)) {
+        // Determine whether this is a direct dependent of the seed or further out
+        const isDirectDependent = (dependentsMap.get(seed.id) ?? new Set()).has(depId);
+        exposureMap.set(depId, isDirectDependent ? 'dependent' : 'transitive');
+      }
+    }
+  }
+
+  // --- Step 3: Build ImpactedTask list ---
+  const EXPOSURE_ORDER: Record<ImpactedTask['exposure'], number> = {
+    direct: 0,
+    dependent: 1,
+    transitive: 2,
+  };
+
+  const affectedTasks: ImpactedTask[] = [];
+
+  for (const [id, exposure] of exposureMap) {
+    const task = taskMap.get(id);
+    if (!task) continue;
+
+    const downstreamTransitive = collectTransitiveDependents(id, dependentsMap);
+    const downstreamCount = downstreamTransitive.size;
+
+    let reason: string;
+    if (exposure === 'direct') {
+      reason = `Task title/description matched "${change}".`;
+    } else if (exposure === 'dependent') {
+      const seedNames = seeds
+        .filter((s) => (dependentsMap.get(s.id) ?? new Set()).has(id))
+        .map((s) => s.id)
+        .join(', ');
+      reason = `Directly depends on matched task(s): ${seedNames}.`;
+    } else {
+      reason = 'Downstream of a matched task via transitive dependency chain.';
+    }
+
+    affectedTasks.push({
+      id,
+      title: task.title,
+      status: task.status,
+      priority: task.priority,
+      exposure,
+      downstreamCount,
+      reason,
+    });
+  }
+
+  // Sort: exposure order first, then descending downstream count
+  affectedTasks.sort((a, b) => {
+    const expDiff = EXPOSURE_ORDER[a.exposure] - EXPOSURE_ORDER[b.exposure];
+    if (expDiff !== 0) return expDiff;
+    return b.downstreamCount - a.downstreamCount;
+  });
+
+  const matchedTasks = affectedTasks.filter((t) => t.exposure === 'direct');
+  const totalAffected = affectedTasks.length;
+
+  const summary =
+    matchedTasks.length === 0
+      ? `No tasks matched "${change}".`
+      : `${matchedTasks.length} task(s) matched "${change}"; ${totalAffected} total task(s) affected (including downstream).`;
+
+  return {
+    change,
+    matchedTasks,
+    affectedTasks,
+    totalAffected,
+    summary,
+  };
+}

package/src/intelligence/index.ts

@@ -30,6 +30,7 @@ export {
   analyzeChangeImpact,
   analyzeTaskImpact,
   calculateBlastRadius,
+  predictImpact,
 } from './impact.js';
 // Patterns
 export {
@@ -53,6 +54,8 @@ export type {
   ChangeType,
   DetectedPattern,
   ImpactAssessment,
+  ImpactedTask,
+  ImpactReport,
   LearningContext,
   PatternExtractionOptions,
   PatternMatch,

package/src/intelligence/types.ts

@@ -245,6 +245,82 @@ export interface AffectedTask {
   reason: string;
 }
 
+// ============================================================================
+// Impact Prediction (free-text change description)
+// ============================================================================
+
+/**
+ * A single task predicted to be affected by a free-text change description.
+ *
+ * Produced by {@link predictImpact} after matching candidate tasks against
+ * the change description and running downstream dependency analysis.
+ */
+export interface ImpactedTask {
+  /** Task ID. */
+  id: string;
+
+  /** Task title. */
+  title: string;
+
+  /** Current task status. */
+  status: string;
+
+  /** Current task priority. */
+  priority: string;
+
+  /**
+   * Severity estimate for this task's exposure to the change.
+   *
+   * - `direct` — task title/description matched the change description
+   * - `dependent` — task depends on a matched task
+   * - `transitive` — downstream of a dependent via the dependency graph
+   */
+  exposure: 'direct' | 'dependent' | 'transitive';
+
+  /**
+   * Number of downstream tasks that depend on this task.
+   * Higher values indicate higher cascading risk.
+   */
+  downstreamCount: number;
+
+  /** Why this task is predicted to be affected. */
+  reason: string;
+}
+
+/**
+ * Full impact prediction report for a free-text change description.
+ *
+ * Returned by {@link predictImpact}. Combines fuzzy task search with
+ * reverse dependency analysis to enumerate which tasks are at risk.
+ */
+export interface ImpactReport {
+  /** The original free-text change description. */
+  change: string;
+
+  /**
+   * Tasks directly matched by the change description (fuzzy search).
+   * These are the "seed" tasks from which downstream impact is traced.
+   */
+  matchedTasks: ImpactedTask[];
+
+  /**
+   * All tasks predicted to be affected, ordered by exposure severity
+   * (direct first, then dependents, then transitive) and then by
+   * descending downstream count.
+   */
+  affectedTasks: ImpactedTask[];
+
+  /**
+   * Total count of distinct affected tasks (including direct matches).
+   */
+  totalAffected: number;
+
+  /**
+   * Human-readable summary of predicted impact scope.
+   */
+  summary: string;
+}
+
 // ============================================================================
 // Blast Radius
 // ============================================================================

package/src/internal.ts

@@ -66,6 +66,7 @@ export {
   analyzeChangeImpact,
   analyzeTaskImpact,
   calculateBlastRadius,
+  predictImpact,
 } from './intelligence/impact.js';
 export {
   extractPatternsFromHistory,
@@ -87,6 +88,8 @@ export type {
   ChangeType,
   DetectedPattern,
   ImpactAssessment,
+  ImpactedTask,
+  ImpactReport,
   LearningContext,
   PatternExtractionOptions,
   PatternMatch,
@@ -98,6 +101,14 @@ export type {
 
 // Issue
 export { collectDiagnostics } from './issue/diagnostics.js';
+// Lib — shared primitives
+export {
+  computeDelay,
+  type RetryablePredicate,
+  type RetryContext,
+  type RetryOptions,
+  withRetry as withRetryShared,
+} from './lib/retry.js';
 export {
   addChain,
   advanceInstance,
@@ -611,6 +622,7 @@ export type {
   AgentExecutionEvent,
   AgentExecutionOutcome,
   AgentHealthReport,
+  AgentHealthStatus,
   AgentPerformanceSummary,
   AgentRecoveryResult,
   CapacitySummary,
@@ -623,12 +635,17 @@ export type {
 } from './agents/index.js';
 // Agents — runtime registry, health, retry, capacity
 export {
+  // health-monitor functions (T039)
   checkAgentHealth,
+  // registry / capacity / retry
   classifyError,
   createRetryPolicy,
   DEFAULT_RETRY_POLICY,
   deregisterAgent,
+  detectCrashedAgents,
+  detectStaleAgents,
   findLeastLoadedAgent,
+  findStaleAgentRows,
   generateAgentId,
   getAgentErrorHistory,
   getAgentInstance,
@@ -637,6 +654,7 @@ export {
   getCapacitySummary,
   getHealthReport,
   getSelfHealingSuggestions,
+  HEARTBEAT_INTERVAL_MS,
   heartbeat,
   incrementTasksCompleted,
   isOverloaded,
@@ -645,8 +663,10 @@ export {
   processAgentLifecycleEvent,
   recordAgentExecution,
   recordFailurePattern,
+  recordHeartbeat,
   recoverCrashedAgents,
   registerAgent as registerAgentInstance,
+  STALE_THRESHOLD_MS,
   storeHealingStrategy,
   updateAgentStatus,
   updateCapacity,