@cleocode/core 2026.3.42 → 2026.3.44

package/src/intelligence/types.ts

@@ -0,0 +1,273 @@
+/**
+ * Type definitions for the CLEO Intelligence dimension.
+ *
+ * Covers quality prediction (risk scoring, validation outcome prediction),
+ * pattern extraction (automatic detection, matching, storage), and
+ * impact analysis (blast radius, change prediction).
+ *
+ * @task Wave3A
+ * @epic T5149
+ * @module intelligence
+ */
+
+import type { BrainLearningRow, BrainPatternRow } from '../store/brain-schema.js';
+
+// ============================================================================
+// Risk Scoring Types
+// ============================================================================
+
+/**
+ * A single factor contributing to a task's overall risk score.
+ *
+ * Each factor has a weight (how much it matters) and a value (current level, 0-1).
+ * The weighted sum of all factors produces the aggregate risk score.
+ */
+export interface RiskFactor {
+  /** Human-readable factor name (e.g., "complexity", "blocking_risk"). */
+  name: string;
+  /** How much this factor contributes to the total score (0-1). */
+  weight: number;
+  /** Current measured value for this factor (0-1, where 1 = highest risk). */
+  value: number;
+  /** Explanation of why this factor has its current value. */
+  description: string;
+}
+
+/**
+ * Complete risk assessment for a single task.
+ *
+ * Returned by {@link calculateTaskRisk}. The `riskScore` is the weighted
+ * aggregate of all {@link RiskFactor} entries in `factors`.
+ */
+export interface RiskAssessment {
+  /** The task ID this assessment applies to. */
+  taskId: string;
+  /** Aggregate risk score (0-1, where 1 = highest risk). */
+  riskScore: number;
+  /** Confidence in the assessment (0-1). Higher when more data is available. */
+  confidence: number;
+  /** Individual risk factors that contributed to the score. */
+  factors: RiskFactor[];
+  /** Human-readable recommendation based on the risk level. */
+  recommendation: string;
+}
+
+/**
+ * Predicted outcome for a lifecycle validation gate.
+ *
+ * Returned by {@link predictValidationOutcome}. Combines historical
+ * pattern data with the task's current state to estimate pass likelihood.
+ */
+export interface ValidationPrediction {
+  /** The task ID being evaluated. */
+  taskId: string;
+  /** The lifecycle stage being predicted (e.g., "specification", "implementation"). */
+  stage: string;
+  /** Probability of passing the gate (0-1). */
+  passLikelihood: number;
+  /** Known blockers that may prevent passing. */
+  blockers: string[];
+  /** Actionable suggestions to improve pass likelihood. */
+  suggestions: string[];
+}
+
+// ============================================================================
+// Pattern Extraction Types
+// ============================================================================
+
+/**
+ * A pattern automatically detected from historical brain/task data.
+ *
+ * Detected patterns may be stored in the existing brain_patterns table
+ * if they meet frequency and confidence thresholds.
+ */
+export interface DetectedPattern {
+  /** Pattern type classification. */
+  type: 'workflow' | 'blocker' | 'success' | 'failure' | 'optimization';
+  /** Human-readable pattern description. */
+  pattern: string;
+  /** Context in which the pattern was observed. */
+  context: string;
+  /** How many times this pattern was observed. */
+  frequency: number;
+  /** Success rate when this pattern appears (0-1, null if unknown). */
+  successRate: number | null;
+  /** Estimated impact level. */
+  impact: 'low' | 'medium' | 'high';
+  /** If this is an anti-pattern, describe the negative behavior. */
+  antiPattern: string | null;
+  /** Recommended mitigation for anti-patterns. */
+  mitigation: string | null;
+  /** Example task IDs or descriptions where this pattern occurred. */
+  examples: string[];
+  /** Confidence in this pattern's validity (0-1). */
+  confidence: number;
+}
+
+/**
+ * Result of matching a task against known patterns from brain_patterns.
+ *
+ * Includes the original pattern row and a relevance score indicating
+ * how strongly the pattern applies to the target task.
+ */
+export interface PatternMatch {
+  /** The matched brain_patterns row. */
+  pattern: BrainPatternRow;
+  /** How relevant this pattern is to the target task (0-1). */
+  relevanceScore: number;
+  /** Why this pattern was matched. */
+  matchReason: string;
+  /** Whether this is an anti-pattern match (warns about potential issues). */
+  isAntiPattern: boolean;
+}
+
+/**
+ * Options for pattern extraction from historical data.
+ */
+export interface PatternExtractionOptions {
+  /** Minimum number of occurrences to consider something a pattern. Default: 2. */
+  minFrequency?: number;
+  /** Minimum confidence threshold (0-1). Default: 0.3. */
+  minConfidence?: number;
+  /** Maximum number of patterns to return. Default: 50. */
+  limit?: number;
+  /** Filter by pattern type. */
+  type?: DetectedPattern['type'];
+}
+
+/**
+ * Result of updating pattern statistics after an outcome.
+ */
+export interface PatternStatsUpdate {
+  /** The pattern ID that was updated. */
+  patternId: string;
+  /** New frequency value. */
+  newFrequency: number;
+  /** New success rate (0-1). */
+  newSuccessRate: number | null;
+  /** Whether the outcome was successful. */
+  outcomeSuccess: boolean;
+}
+
+/**
+ * Summary of applicable learnings for a task, used in prediction.
+ */
+export interface LearningContext {
+  /** Learnings that apply to this task's context. */
+  applicable: BrainLearningRow[];
+  /** Average confidence of applicable learnings. */
+  averageConfidence: number;
+  /** Count of actionable learnings. */
+  actionableCount: number;
+}
+
+// ============================================================================
+// Impact Assessment
+// ============================================================================
+
+/**
+ * Full impact assessment for a task within its dependency graph.
+ *
+ * Captures direct dependents, transitive dependents, lifecycle pipeline
+ * effects, blocked work counts, and critical path membership.
+ */
+export interface ImpactAssessment {
+  /** The task being assessed. */
+  taskId: string;
+
+  /** Tasks that directly depend on this task. */
+  directDependents: string[];
+
+  /** All downstream tasks (direct + transitive). */
+  transitiveDependents: string[];
+
+  /** Epic IDs whose lifecycle pipelines are affected. */
+  affectedPipelines: string[];
+
+  /** Count of tasks that would be blocked if this task is not completed. */
+  blockedWorkCount: number;
+
+  /** Whether this task lies on the project's critical path. */
+  isOnCriticalPath: boolean;
+
+  /** Quantified scope of the impact. */
+  blastRadius: BlastRadius;
+}
+
+// ============================================================================
+// Change Impact
+// ============================================================================
+
+/** The type of change being analyzed. */
+export type ChangeType = 'cancel' | 'block' | 'complete' | 'reprioritize';
+
+/**
+ * Predicted downstream effects of a specific change to a task.
+ *
+ * Models what happens when a task is cancelled, blocked, completed,
+ * or reprioritized -- including cascading status changes and
+ * recommendations.
+ */
+export interface ChangeImpact {
+  /** The task being changed. */
+  taskId: string;
+
+  /** The type of change being analyzed. */
+  changeType: ChangeType;
+
+  /** Tasks affected by this change, with predicted new status. */
+  affectedTasks: AffectedTask[];
+
+  /** Maximum depth of cascading effects in the dependency graph. */
+  cascadeDepth: number;
+
+  /** Human-readable recommendation based on the analysis. */
+  recommendation: string;
+}
+
+/**
+ * A single task affected by a change, with its predicted new state.
+ */
+export interface AffectedTask {
+  /** Task ID. */
+  id: string;
+
+  /** Task title. */
+  title: string;
+
+  /** Current status before the change. */
+  currentStatus: string;
+
+  /** Predicted new status after the change (if it would change). */
+  newStatus?: string;
+
+  /** Why this task is affected. */
+  reason: string;
+}
+
+// ============================================================================
+// Blast Radius
+// ============================================================================
+
+/** Severity classification for blast radius. */
+export type BlastRadiusSeverity = 'isolated' | 'moderate' | 'widespread' | 'critical';
+
+/**
+ * Quantified scope of a task's impact across the project.
+ */
+export interface BlastRadius {
+  /** Number of direct dependents. */
+  directCount: number;
+
+  /** Number of transitive dependents (full downstream tree). */
+  transitiveCount: number;
+
+  /** Number of distinct epics affected. */
+  epicCount: number;
+
+  /** Percentage of the total project impacted (0-100). */
+  projectPercentage: number;
+
+  /** Classification of impact severity. */
+  severity: BlastRadiusSeverity;
+}

package/src/internal.ts

@@ -51,12 +51,47 @@ export type {
   ViolationSeverity,
 } from './compliance/protocol-rules.js';
 export { PROTOCOL_RULES } from './compliance/protocol-rules.js';
+export type { PayloadValidationResult } from './hooks/payload-schemas.js';
+export { validatePayload } from './hooks/payload-schemas.js';
 // Hooks
 export type { HookEvent, ProviderHookEvent } from './hooks/provider-hooks.js';
 export { isProviderHookEvent } from './hooks/types.js';
 
 // Init (additional)
 export { isAutoInitEnabled } from './init.js';
+export {
+  analyzeChangeImpact,
+  analyzeTaskImpact,
+  calculateBlastRadius,
+} from './intelligence/impact.js';
+export {
+  extractPatternsFromHistory,
+  matchPatterns,
+  storeDetectedPattern,
+  updatePatternStats,
+} from './intelligence/patterns.js';
+export {
+  calculateTaskRisk,
+  gatherLearningContext,
+  predictValidationOutcome,
+} from './intelligence/prediction.js';
+// Intelligence — quality prediction and pattern extraction
+export type {
+  AffectedTask,
+  BlastRadius,
+  BlastRadiusSeverity,
+  ChangeImpact,
+  ChangeType,
+  DetectedPattern,
+  ImpactAssessment,
+  LearningContext,
+  PatternExtractionOptions,
+  PatternMatch,
+  PatternStatsUpdate,
+  RiskAssessment,
+  RiskFactor,
+  ValidationPrediction,
+} from './intelligence/types.js';
 
 // Issue
 export { collectDiagnostics } from './issue/diagnostics.js';
@@ -563,6 +598,41 @@ export { coreTaskStats } from './tasks/task-ops.js';
 // Additional flat exports (required by @cleocode/cleo)
 // ---------------------------------------------------------------------------
 
+export type {
+  AgentHealthReport,
+  AgentRecoveryResult,
+  CapacitySummary,
+  ListAgentFilters,
+  RegisterAgentOptions,
+  RetryPolicy,
+  RetryResult,
+  UpdateStatusOptions,
+} from './agents/index.js';
+// Agents — runtime registry, health, retry, capacity
+export {
+  checkAgentHealth,
+  classifyError,
+  createRetryPolicy,
+  DEFAULT_RETRY_POLICY,
+  deregisterAgent,
+  findLeastLoadedAgent,
+  generateAgentId,
+  getAgentErrorHistory,
+  getAgentInstance,
+  getAvailableCapacity,
+  getCapacitySummary,
+  getHealthReport,
+  heartbeat,
+  incrementTasksCompleted,
+  isOverloaded,
+  listAgentInstances,
+  markCrashed,
+  recoverCrashedAgents,
+  registerAgent as registerAgentInstance,
+  updateAgentStatus,
+  updateCapacity,
+  withRetry,
+} from './agents/index.js';
 // Codebase map (additional)
 export { mapCodebase } from './codebase-map/index.js';
 // Compliance (additional)
@@ -574,6 +644,18 @@ export type { BuildConfig } from './config/build-config.js';
 export { BUILD_CONFIG } from './config/build-config.js';
 // Init (additional)
 export { initCoreSkills } from './init.js';
+// Memory — brain row types
+export type {
+  BrainAnchor,
+  BrainConsolidationObservationRow,
+  BrainDecisionNode,
+  BrainFtsRow,
+  BrainIdCheckRow,
+  BrainKnnRow,
+  BrainNarrativeRow,
+  BrainSearchHit,
+  BrainTimelineNeighborRow,
+} from './memory/brain-row-types.js';
 // Memory (additional)
 export { writeMemoryBridge } from './memory/memory-bridge.js';
 export type { SessionMemoryContext } from './memory/session-memory.js';
@@ -620,7 +702,6 @@ export { listLabels, showLabelTasks } from './tasks/labels.js';
 // Tasks — plan, labels, suggests
 export { coreTaskPlan } from './tasks/plan.js';
 export { suggestRelated } from './tasks/relates.js';
-
 // Verification gates — enums/classes
 export { GateStatus, VerificationGate } from './validation/operation-verification-gates.js';
 

package/src/issue/template-parser.ts

@@ -227,12 +227,73 @@ export function cacheTemplates(templates: IssueTemplate[], cwd?: string): void {
 }
 
 /**
- * Validate that required labels exist (informational).
+ * Validate that labels referenced in issue templates are consistent.
+ *
+ * Collects all labels used across templates and checks that each label
+ * appears in at least one template definition. Reports any labels that
+ * are referenced by only one template but not defined as a known label
+ * across the template set. This catches typos and orphaned labels
+ * without requiring GitHub API access.
  */
-export function validateLabelsExist(_templates: IssueTemplate[]): {
+export function validateLabelsExist(templates: IssueTemplate[]): {
   valid: boolean;
   missingLabels: string[];
 } {
-  // Can't actually verify GitHub labels without API, just return the set
-  return { valid: true, missingLabels: [] };
+  if (templates.length === 0) {
+    return { valid: true, missingLabels: [] };
+  }
+
+  // Build a frequency map of all labels across templates
+  const labelFrequency = new Map<string, number>();
+  for (const template of templates) {
+    for (const label of template.labels) {
+      labelFrequency.set(label, (labelFrequency.get(label) ?? 0) + 1);
+    }
+  }
+
+  // Cross-reference: each template's labels should be known across the template set.
+  // A label used by only one template AND not matching any known subcommand is suspicious.
+  const knownSubcommands = new Set(templates.map((t) => t.subcommand));
+  const knownNames = new Set(templates.map((t) => t.name.toLowerCase()));
+  const missingLabels: string[] = [];
+
+  for (const template of templates) {
+    for (const label of template.labels) {
+      // Check if the label is completely unknown: used once, and not matching
+      // any template subcommand or name (which would make it a valid unique label)
+      const freq = labelFrequency.get(label) ?? 0;
+      if (
+        freq === 1 &&
+        !knownSubcommands.has(label) &&
+        !knownNames.has(label.toLowerCase()) &&
+        !WELL_KNOWN_LABELS.has(label)
+      ) {
+        missingLabels.push(label);
+      }
+    }
+  }
+
+  return {
+    valid: missingLabels.length === 0,
+    missingLabels,
+  };
 }
+
+/** Labels that are well-known in GitHub/issue trackers and always valid. */
+const WELL_KNOWN_LABELS = new Set([
+  'bug',
+  'enhancement',
+  'feature',
+  'help',
+  'question',
+  'documentation',
+  'good first issue',
+  'duplicate',
+  'invalid',
+  'wontfix',
+  'priority',
+  'critical',
+  'high',
+  'medium',
+  'low',
+]);

package/src/lifecycle/pipeline.ts

@@ -695,14 +695,14 @@ export async function listPipelines(options: PipelineQueryOptions = {}): Promise
  * Only valid when the pipeline is in the 'release' stage.
  *
  * @param taskId - The task ID
- * @param _reason - Optional completion reason (unused, for API compatibility)
+ * @param reason - Optional completion reason, stored in the final stage's notes
  * @throws {CleoError} If pipeline not found or not in releasable state
  * @returns Promise resolving when complete
  *
  * @task T4800
  * @task T4912 - Implemented SQLite wiring
  */
-export async function completePipeline(taskId: string, _reason?: string): Promise<void> {
+export async function completePipeline(taskId: string, reason?: string): Promise<void> {
   const db = await getDb();
   const now = new Date();
 
@@ -719,14 +719,21 @@ export async function completePipeline(taskId: string, _reason?: string): Promis
 
   const pipeline = pipelineResult[0];
 
-  // Mark current stage (release) as completed
+  // Mark current stage (release) as completed, storing completion reason in notes
   if (pipeline.currentStageId) {
+    const stageUpdate: Record<string, unknown> = {
+      status: 'completed',
+      completedAt: now.toISOString(),
+    };
+
+    if (reason) {
+      stageUpdate.notesJson = JSON.stringify([`Completion reason: ${reason}`]);
+      stageUpdate.metadataJson = JSON.stringify({ completionReason: reason });
+    }
+
     await db
       .update(schema.lifecycleStages)
-      .set({
-        status: 'completed',
-        completedAt: now.toISOString(),
-      })
+      .set(stageUpdate)
       .where(
         and(
           eq(schema.lifecycleStages.pipelineId, pipeline.id),

package/src/lifecycle/state-machine.ts

@@ -713,7 +713,7 @@ export function canSkipStage(stage: Stage): boolean {
  *
  * @task T4800
  */
-export function skipStage(stage: Stage, _reason: string, context: StateMachineContext): StageState {
+export function skipStage(stage: Stage, reason: string, context: StateMachineContext): StageState {
   if (!canSkipStage(stage)) {
     throw new CleoError(ExitCode.LIFECYCLE_TRANSITION_INVALID, `Stage ${stage} cannot be skipped`, {
       fix: `Complete the ${stage} stage or use force flag`,
@@ -729,5 +729,9 @@ export function skipStage(stage: Stage, _reason: string, context: StateMachineCo
     );
   }
 
-  return setStageStatus(stage, 'skipped', context);
+  const updatedState = setStageStatus(stage, 'skipped', context);
+  // Store the skip reason in the stage notes for in-memory context;
+  // the DB-level skip_reason column is set by recordStageProgress in lifecycle/index.ts
+  updatedState.notes = reason;
+  return updatedState;
 }

package/src/memory/brain-lifecycle.ts

@@ -13,6 +13,8 @@
 
 import { createHash } from 'node:crypto';
 import { getBrainAccessor } from '../store/brain-accessor.js';
+import { typedAll } from '../store/typed-query.js';
+import type { BrainConsolidationObservationRow } from './brain-row-types.js';
 
 /** Result from applying temporal decay. */
 export interface DecayResult {
@@ -248,22 +250,14 @@ export async function consolidateMemories(
     .slice(0, 19);
 
   // Fetch old observations that are not already archived
-  const oldObservations = nativeDb
-    .prepare(`
+  const stmt = nativeDb.prepare(`
     SELECT id, type, title, narrative, project, created_at
     FROM brain_observations
     WHERE created_at < ?
       AND narrative NOT LIKE '[ARCHIVED]%'
     ORDER BY created_at DESC
-  `)
-    .all(cutoffDate) as Array<{
-    id: string;
-    type: string;
-    title: string;
-    narrative: string | null;
-    project: string | null;
-    created_at: string;
-  }>;
+  `);
+  const oldObservations = typedAll<BrainConsolidationObservationRow>(stmt, cutoffDate);
 
   if (oldObservations.length < minClusterSize) {
     return { grouped: 0, merged: 0, archived: 0 };

package/src/memory/brain-retrieval.ts

@@ -22,8 +22,14 @@ import type {
   BRAIN_OBSERVATION_SOURCE_TYPES,
   BRAIN_OBSERVATION_TYPES,
 } from '../store/brain-schema.js';
+import { typedAll } from '../store/typed-query.js';
 import { embedText, isEmbeddingAvailable } from './brain-embedding.js';
-import type { BrainAnchor, BrainFtsRow, BrainNarrativeRow } from './brain-row-types.js';
+import type {
+  BrainAnchor,
+  BrainFtsRow,
+  BrainNarrativeRow,
+  BrainTimelineNeighborRow,
+} from './brain-row-types.js';
 import { searchBrain } from './brain-search.js';
 
 // ============================================================================
@@ -305,8 +311,8 @@ export async function timelineBrain(
 
   // UNION ALL across all 4 tables to get chronological neighbors.
   // Excludes the anchor itself.
-  const beforeRows = nativeDb
-    .prepare(`
+  const beforeRows = typedAll<BrainTimelineNeighborRow>(
+    nativeDb.prepare(`
     SELECT id, 'decision' AS type, created_at AS date FROM brain_decisions WHERE created_at < ? AND id != ?
     UNION ALL
     SELECT id, 'pattern' AS type, extracted_at AS date FROM brain_patterns WHERE extracted_at < ? AND id != ?
@@ -316,21 +322,20 @@ export async function timelineBrain(
     SELECT id, 'observation' AS type, created_at AS date FROM brain_observations WHERE created_at < ? AND id != ?
     ORDER BY date DESC
     LIMIT ?
-  `)
-    .all(
-      anchorDate,
-      anchorId,
-      anchorDate,
-      anchorId,
-      anchorDate,
-      anchorId,
-      anchorDate,
-      anchorId,
-      depthBefore,
-    ) as unknown as TimelineNeighbor[];
-
-  const afterRows = nativeDb
-    .prepare(`
+  `),
+    anchorDate,
+    anchorId,
+    anchorDate,
+    anchorId,
+    anchorDate,
+    anchorId,
+    anchorDate,
+    anchorId,
+    depthBefore,
+  );
+
+  const afterRows = typedAll<BrainTimelineNeighborRow>(
+    nativeDb.prepare(`
     SELECT id, 'decision' AS type, created_at AS date FROM brain_decisions WHERE created_at > ? AND id != ?
     UNION ALL
     SELECT id, 'pattern' AS type, extracted_at AS date FROM brain_patterns WHERE extracted_at > ? AND id != ?
@@ -340,18 +345,17 @@ export async function timelineBrain(
     SELECT id, 'observation' AS type, created_at AS date FROM brain_observations WHERE created_at > ? AND id != ?
     ORDER BY date ASC
     LIMIT ?
-  `)
-    .all(
-      anchorDate,
-      anchorId,
-      anchorDate,
-      anchorId,
-      anchorDate,
-      anchorId,
-      anchorDate,
-      anchorId,
-      depthAfter,
-    ) as unknown as TimelineNeighbor[];
+  `),
+    anchorDate,
+    anchorId,
+    anchorDate,
+    anchorId,
+    anchorDate,
+    anchorId,
+    anchorDate,
+    anchorId,
+    depthAfter,
+  );
 
   return {
     anchor: { id: anchorId, type: anchorType, data: anchorData },
@@ -530,11 +534,13 @@ export async function observeBrain(
   const nativeDb = getBrainNativeDb();
   if (nativeDb) {
     const cutoff = new Date(Date.now() - 30000).toISOString().replace('T', ' ').slice(0, 19);
-    const existing = nativeDb
-      .prepare(
+    const existing = typedAll<BrainFtsRow>(
+      nativeDb.prepare(
         'SELECT id, type, created_at FROM brain_observations WHERE content_hash = ? AND created_at > ?',
-      )
-      .all(contentHash, cutoff) as unknown as BrainFtsRow[];
+      ),
+      contentHash,
+      cutoff,
+    );
 
     if (existing.length > 0) {
       return {
@@ -639,15 +645,15 @@ export async function populateEmbeddings(
   let skipped = 0;
 
   // Find observations without embeddings
-  const rows = nativeDb
-    .prepare(`
+  const rows = typedAll<BrainNarrativeRow>(
+    nativeDb.prepare(`
     SELECT o.id, o.narrative, o.title
     FROM brain_observations o
     LEFT JOIN brain_embeddings e ON o.id = e.id
     WHERE e.id IS NULL AND o.narrative IS NOT NULL
     ORDER BY o.created_at DESC
-  `)
-    .all() as unknown as BrainNarrativeRow[];
+  `),
+  );
 
   for (let i = 0; i < rows.length; i += batchSize) {
     const batch = rows.slice(i, i + batchSize);