@cleocode/core 2026.3.58 → 2026.3.59

package/src/agents/index.ts

@@ -11,6 +11,17 @@
  * @module agents
  */
 
+// Load-balancing registry: task-count capacity, specializations, performance recording
+export {
+  type AgentCapacity,
+  type AgentPerformanceMetrics,
+  getAgentCapacity,
+  getAgentSpecializations,
+  getAgentsByCapacity,
+  MAX_TASKS_PER_AGENT,
+  recordAgentPerformance,
+  updateAgentSpecializations,
+} from './agent-registry.js';
 // Schema & types
 export {
   AGENT_INSTANCE_STATUSES,
@@ -47,10 +58,22 @@ export {
   recordFailurePattern,
   storeHealingStrategy,
 } from './execution-learning.js';
+// Health monitoring (T039)
+export {
+  type AgentHealthStatus,
+  checkAgentHealth,
+  detectCrashedAgents,
+  detectStaleAgents,
+  HEARTBEAT_INTERVAL_MS,
+  recordHeartbeat,
+  STALE_THRESHOLD_MS,
+} from './health-monitor.js';
 // Registry (CRUD, heartbeat, health, errors)
+// Note: registry.checkAgentHealth (thresholdMs, cwd) -> AgentInstanceRow[] is exported
+// as findStaleAgentRows to avoid conflict with health-monitor.checkAgentHealth (T039).
 export {
   type AgentHealthReport,
-  checkAgentHealth,
+  checkAgentHealth as findStaleAgentRows,
   classifyError,
   deregisterAgent,
   generateAgentId,

package/src/agents/retry.ts

@@ -47,6 +47,17 @@ export const DEFAULT_RETRY_POLICY: Readonly<RetryPolicy> = Object.freeze({
 
 /**
  * Create a retry policy by merging overrides with the default policy.
+ *
+ * @remarks
+ * Unspecified fields fall back to {@link DEFAULT_RETRY_POLICY}.
+ *
+ * @param overrides - Partial policy to merge with defaults
+ * @returns A complete RetryPolicy
+ *
+ * @example
+ * ```ts
+ * const policy = createRetryPolicy({ maxRetries: 5 });
+ * ```
  */
 export function createRetryPolicy(overrides?: Partial<RetryPolicy>): RetryPolicy {
   return { ...DEFAULT_RETRY_POLICY, ...overrides };
@@ -55,8 +66,19 @@ export function createRetryPolicy(overrides?: Partial<RetryPolicy>): RetryPolicy
 /**
  * Calculate the delay for a given retry attempt using exponential backoff.
  *
- * Formula: min(baseDelay * multiplier^attempt, maxDelay) + jitter
+ * @remarks
+ * Formula: `min(baseDelay * multiplier^attempt, maxDelay) + jitter`.
  * Jitter adds 0-25% randomness to prevent thundering herd.
+ *
+ * @param attempt - Zero-based attempt index
+ * @param policy - Retry policy with delay configuration
+ * @returns Delay in milliseconds before the next attempt
+ *
+ * @example
+ * ```ts
+ * const delay = calculateDelay(1, createRetryPolicy());
+ * // => ~2000ms (with jitter)
+ * ```
  */
 export function calculateDelay(attempt: number, policy: RetryPolicy): number {
   const exponentialDelay = policy.baseDelayMs * policy.backoffMultiplier ** attempt;
@@ -73,6 +95,20 @@ export function calculateDelay(attempt: number, policy: RetryPolicy): number {
 /**
  * Determine whether an error should be retried based on its classification
  * and the retry policy.
+ *
+ * @remarks
+ * Permanent errors are never retried. Retriable errors are always retried
+ * (within attempt limits). Unknown errors defer to `policy.retryOnUnknown`.
+ *
+ * @param error - The caught error to classify
+ * @param attempt - Current attempt number (0-based)
+ * @param policy - Retry policy with limits and classification rules
+ * @returns True if the error should be retried
+ *
+ * @example
+ * ```ts
+ * if (shouldRetry(err, attempt, policy)) { /* retry *\/ }
+ * ```
  */
 export function shouldRetry(error: unknown, attempt: number, policy: RetryPolicy): boolean {
   if (attempt >= policy.maxRetries) return false;
@@ -102,13 +138,20 @@ export interface RetryResult<T> {
 /**
  * Wrap an async function with retry logic using configurable exponential backoff.
  *
- * The function will be retried according to the policy when retriable errors
- * occur. Permanent errors cause immediate failure. Unknown errors respect
- * the `retryOnUnknown` policy setting.
+ * @remarks
+ * Agent-specific variant that integrates with error classification from the
+ * agent registry. For a dependency-free generic retry, use `lib/retry.ts`.
  *
+ * @typeParam T - The resolved type of the async function
  * @param fn - The async function to execute with retries
  * @param policy - Retry policy (uses DEFAULT_RETRY_POLICY if not provided)
  * @returns The result of the operation with retry metadata
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(() => fetchAgentTask(agentId));
+ * if (!result.success) console.error(result.error);
+ * ```
  */
 export async function withRetry<T>(
   fn: () => Promise<T>,
@@ -176,9 +219,19 @@ export interface AgentRecoveryResult {
  * classified as 'permanent' are abandoned. Agents with retriable errors
  * are reset to 'starting' for the orchestration layer to re-assign.
  *
+ * @remarks
+ * Two-phase process: first detects stale agents via heartbeat threshold,
+ * then evaluates each crashed agent's error history for recoverability.
+ *
  * @param thresholdMs - Heartbeat threshold for crash detection (default: 30000)
  * @param cwd - Working directory
  * @returns Recovery results for each crashed agent
+ *
+ * @example
+ * ```ts
+ * const results = await recoverCrashedAgents(60_000);
+ * results.filter(r => r.recovered).forEach(r => console.log(r.agentId));
+ * ```
  */
 export async function recoverCrashedAgents(
   thresholdMs: number = 30_000,

package/src/backfill/index.ts

@@ -8,6 +8,7 @@
  *   backfillTasks(root, {})                  -- apply changes
  *   backfillTasks(root, { rollback: true })  -- revert backfill
  *
+ * @packageDocumentation
  * @epic T056
  * @task T066
  */
@@ -60,6 +61,20 @@ export interface BackfillResult {
 /**
  * Generate 3 baseline acceptance criteria from a task description.
  * Uses simple text analysis — no LLM required.
+ *
+ * @remarks
+ * Extracts action verbs from the title + description to produce contextually
+ * relevant criteria. Falls back to generic criteria when no verbs match.
+ *
+ * @param title - The task title
+ * @param description - The task description
+ * @returns Array of 3 acceptance criteria strings
+ *
+ * @example
+ * ```ts
+ * generateAcFromDescription('Fix login bug', 'Users cannot log in');
+ * // => ['The defect is resolved...', 'No breaking changes...', 'Changes verified...']
+ * ```
  */
 export function generateAcFromDescription(title: string, description: string): string[] {
   const text = `${title} ${description}`.toLowerCase();
@@ -144,8 +159,20 @@ function isBackfilledTask(task: Task): boolean {
 /**
  * Retroactively populate AC and verification metadata for tasks that lack them.
  *
+ * @remarks
+ * In dry-run mode, computes changes without writing to the database.
+ * Backfilled tasks are tagged with a note so they can be identified and
+ * optionally rolled back later.
+ *
  * @param projectRoot - Project root directory (cwd for CLEO operations)
  * @param options     - Backfill options (dryRun, rollback, taskIds)
+ * @returns Summary of changes applied (or previewed in dry-run mode)
+ *
+ * @example
+ * ```ts
+ * const result = await backfillTasks('/my/project', { dryRun: true });
+ * console.log(result.changed); // number of tasks that would be modified
+ * ```
  */
 export async function backfillTasks(
   projectRoot: string,

package/src/config.ts

@@ -348,7 +348,7 @@ export const STRICTNESS_PRESETS: Record<StrictnessPreset, PresetDefinition> = {
       'session.autoStart': false,
       'session.requireNotes': true,
       'session.multiSession': false,
-      'hierarchy.requireAcceptanceCriteria': true,
+      'enforcement.acceptance.mode': 'block',
       'lifecycle.mode': 'strict',
     },
   },
@@ -359,7 +359,7 @@ export const STRICTNESS_PRESETS: Record<StrictnessPreset, PresetDefinition> = {
       'session.autoStart': false,
       'session.requireNotes': false,
       'session.multiSession': true,
-      'hierarchy.requireAcceptanceCriteria': false,
+      'enforcement.acceptance.mode': 'warn',
       'lifecycle.mode': 'advisory',
     },
   },
@@ -369,7 +369,7 @@ export const STRICTNESS_PRESETS: Record<StrictnessPreset, PresetDefinition> = {
       'session.autoStart': false,
       'session.requireNotes': false,
       'session.multiSession': true,
-      'hierarchy.requireAcceptanceCriteria': false,
+      'enforcement.acceptance.mode': 'off',
       'lifecycle.mode': 'off',
     },
   },

package/src/index.ts

@@ -40,6 +40,7 @@ export * as coreHooks from './hooks/index.js';
 export * as inject from './inject/index.js';
 export * as intelligence from './intelligence/index.js';
 export * as issue from './issue/index.js';
+export * as lib from './lib/index.js';
 export * as lifecycle from './lifecycle/index.js';
 export * as coreMcp from './mcp/index.js';
 export * as memory from './memory/index.js';

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,