@cleocode/core 2026.3.76 → 2026.4.0

package/src/internal.ts

@@ -43,6 +43,11 @@ export {
   installMcpToProviders,
   installSkillsGlobally,
 } from './bootstrap.js';
+export { smartOutline } from './code/outline.js';
+// Code analysis (Smart Explore)
+export { batchParse, parseFile } from './code/parser.js';
+export { smartSearch } from './code/search.js';
+export { smartUnfold } from './code/unfold.js';
 export type { ViolationLogEntry } from './compliance/protocol-enforcement.js';
 // Compliance
 export { ProtocolEnforcer, protocolEnforcer } from './compliance/protocol-enforcement.js';
@@ -144,6 +149,7 @@ export type {
   BrainMaintenanceDecayResult,
   BrainMaintenanceEmbeddingsResult,
   BrainMaintenanceOptions,
+  BrainMaintenanceReconciliationResult,
   BrainMaintenanceResult,
 } from './memory/brain-maintenance.js';
 export { runBrainMaintenance } from './memory/brain-maintenance.js';
@@ -805,4 +811,3 @@ export { createConduit } from './conduit/factory.js';
 export { HttpTransport } from './conduit/http-transport.js';
 export { decrypt, encrypt } from './crypto/credentials.js';
 export { AgentRegistryAccessor } from './store/agent-registry-accessor.js';
-export { agentCredentials } from './store/tasks-schema.js';

package/src/lib/index.ts

@@ -14,3 +14,11 @@ export {
   type RetryOptions,
   withRetry,
 } from './retry.js';
+
+export {
+  detectLanguage,
+  grammarPackage,
+  SUPPORTED_EXTENSIONS,
+  SUPPORTED_LANGUAGES,
+  type TreeSitterLanguage,
+} from './tree-sitter-languages.js';

package/src/lib/tree-sitter-languages.ts

@@ -0,0 +1,88 @@
+/**
+ * Tree-sitter language detection and grammar resolution.
+ *
+ * Maps file extensions to tree-sitter grammar packages for use by
+ * the Smart Explore code analysis pipeline.
+ *
+ * @task T148
+ */
+
+/** Supported tree-sitter language identifiers. */
+export type TreeSitterLanguage =
+  | 'typescript'
+  | 'tsx'
+  | 'javascript'
+  | 'python'
+  | 'go'
+  | 'rust'
+  | 'java'
+  | 'c'
+  | 'cpp'
+  | 'ruby';
+
+/** Map from file extension (without dot) to tree-sitter language. */
+const EXTENSION_MAP: Record<string, TreeSitterLanguage> = {
+  ts: 'typescript',
+  tsx: 'tsx',
+  mts: 'typescript',
+  cts: 'typescript',
+  js: 'javascript',
+  jsx: 'javascript',
+  mjs: 'javascript',
+  cjs: 'javascript',
+  py: 'python',
+  pyi: 'python',
+  go: 'go',
+  rs: 'rust',
+  java: 'java',
+  c: 'c',
+  h: 'c',
+  cpp: 'cpp',
+  cc: 'cpp',
+  cxx: 'cpp',
+  hpp: 'cpp',
+  hh: 'cpp',
+  rb: 'ruby',
+};
+
+/** Map from language to its npm grammar package name. */
+const GRAMMAR_PACKAGE_MAP: Record<TreeSitterLanguage, string> = {
+  typescript: 'tree-sitter-typescript',
+  tsx: 'tree-sitter-typescript',
+  javascript: 'tree-sitter-javascript',
+  python: 'tree-sitter-python',
+  go: 'tree-sitter-go',
+  rust: 'tree-sitter-rust',
+  java: 'tree-sitter-java',
+  c: 'tree-sitter-c',
+  cpp: 'tree-sitter-cpp',
+  ruby: 'tree-sitter-ruby',
+};
+
+/**
+ * Detect tree-sitter language from a file path.
+ *
+ * @param filePath - Path to a source file
+ * @returns The detected language, or undefined if unsupported
+ */
+export function detectLanguage(filePath: string): TreeSitterLanguage | undefined {
+  const ext = filePath.split('.').pop()?.toLowerCase();
+  if (!ext) return undefined;
+  return EXTENSION_MAP[ext];
+}
+
+/**
+ * Get the npm grammar package name for a language.
+ *
+ * @param language - A tree-sitter language identifier
+ * @returns The npm package name containing the grammar
+ */
+export function grammarPackage(language: TreeSitterLanguage): string {
+  return GRAMMAR_PACKAGE_MAP[language];
+}
+
+/** All supported file extensions. */
+export const SUPPORTED_EXTENSIONS = Object.keys(EXTENSION_MAP);
+
+/** All supported languages. */
+export const SUPPORTED_LANGUAGES: TreeSitterLanguage[] = [...new Set(Object.values(EXTENSION_MAP))];

package/src/memory/__tests__/brain-links.test.ts

@@ -19,11 +19,25 @@ describe('Brain Memory Links', () => {
     cleoDir = join(tempDir, '.cleo');
     await mkdir(cleoDir, { recursive: true });
     process.env['CLEO_DIR'] = cleoDir;
+
+    // Initialize tasks.db with test task IDs for cross-db write-guard validation
+    const { getDb } = await import('../../store/sqlite.js');
+    const { tasks } = await import('../../store/tasks-schema.js');
+    const db = await getDb(tempDir);
+    for (const id of ['T1000', 'T2000', 'T9999']) {
+      await db
+        .insert(tasks)
+        .values({ id, title: `Test task ${id}`, status: 'pending', type: 'task', position: 0 })
+        .onConflictDoNothing()
+        .run();
+    }
   });
 
   afterEach(async () => {
     const { closeBrainDb } = await import('../../store/brain-sqlite.js');
+    const { resetDbState } = await import('../../store/sqlite.js');
     closeBrainDb();
+    resetDbState();
     delete process.env['CLEO_DIR'];
     await rm(tempDir, { recursive: true, force: true });
   });

package/src/memory/__tests__/brain-retrieval.test.ts

@@ -21,6 +21,16 @@ describe('Brain Retrieval', () => {
     cleoDir = join(tempDir, '.cleo');
     await mkdir(cleoDir, { recursive: true });
     process.env['CLEO_DIR'] = cleoDir;
+
+    // Initialize tasks.db with test session for cross-db write-guard validation
+    const { getDb } = await import('../../store/sqlite.js');
+    const { sessions } = await import('../../store/tasks-schema.js');
+    const db = await getDb(tempDir);
+    await db
+      .insert(sessions)
+      .values({ id: 'S-123', name: 'test-session', status: 'active' })
+      .onConflictDoNothing()
+      .run();
   });
 
   afterEach(async () => {

package/src/memory/__tests__/session-memory.test.ts

@@ -56,6 +56,23 @@ describe('Session Memory', () => {
     cleoDir = join(tempDir, '.cleo');
     await mkdir(cleoDir, { recursive: true });
     process.env['CLEO_DIR'] = cleoDir;
+
+    // Initialize tasks.db with test task IDs and session for cross-db write-guard validation
+    const { getDb } = await import('../../store/sqlite.js');
+    const { tasks, sessions } = await import('../../store/tasks-schema.js');
+    const db = await getDb(tempDir);
+    for (const id of ['T100', 'T101']) {
+      await db
+        .insert(tasks)
+        .values({ id, title: `Test task ${id}`, status: 'pending', type: 'task', position: 0 })
+        .onConflictDoNothing()
+        .run();
+    }
+    await db
+      .insert(sessions)
+      .values({ id: 'S-001', name: 'test-session', status: 'active' })
+      .onConflictDoNothing()
+      .run();
   });
 
   afterEach(async () => {

package/src/memory/brain-links.ts

@@ -17,6 +17,8 @@ import type {
   BrainMemoryLinkRow,
   BrainPatternRow,
 } from '../store/brain-schema.js';
+import { taskExistsInTasksDb } from '../store/cross-db-cleanup.js';
+import { getDb } from '../store/sqlite.js';
 
 type MemoryType = (typeof BRAIN_MEMORY_TYPES)[number];
 type LinkType = (typeof BRAIN_LINK_TYPES)[number];
@@ -45,6 +47,14 @@ export async function linkMemoryToTask(
     throw new Error('memoryId and taskId are required');
   }
 
+  // Write-guard: reject stale task IDs before creating cross-db reference
+  const tasksDb = await getDb(projectRoot);
+  if (!(await taskExistsInTasksDb(taskId, tasksDb))) {
+    throw new Error(
+      `Write-guard: task ${taskId} does not exist in tasks.db — refusing to create brain link`,
+    );
+  }
+
   const accessor = await getBrainAccessor(projectRoot);
 
   // Check if link already exists
@@ -120,10 +130,17 @@ export async function bulkLink(
   links: BulkLinkEntry[],
 ): Promise<{ created: number; skipped: number }> {
   const accessor = await getBrainAccessor(projectRoot);
+  const tasksDb = await getDb(projectRoot);
   let created = 0;
   let skipped = 0;
 
   for (const link of links) {
+    // Write-guard: reject stale task IDs before creating cross-db reference
+    if (!(await taskExistsInTasksDb(link.taskId, tasksDb))) {
+      skipped++;
+      continue;
+    }
+
     // Check for duplicate
     const existing = await accessor.getLinksForMemory(link.memoryType, link.memoryId);
     const duplicate = existing.find(

package/src/memory/brain-maintenance.ts

@@ -19,6 +19,7 @@
  * @what Combined maintenance runner with CLI command and progress reporting
  */
 
+import { reconcileOrphanedRefs } from '../store/cross-db-cleanup.js';
 import { applyTemporalDecay, consolidateMemories } from './brain-lifecycle.js';
 import { populateEmbeddings } from './brain-retrieval.js';
 
@@ -40,6 +41,16 @@ export interface BrainMaintenanceConsolidationResult {
   removed: number;
 }
 
+/** Orphaned reference reconciliation step result. */
+export interface BrainMaintenanceReconciliationResult {
+  /** Decisions with stale task/epic references fixed. */
+  decisionsFixed: number;
+  /** Observations with stale session references fixed. */
+  observationsFixed: number;
+  /** Memory links with stale task references removed. */
+  linksRemoved: number;
+}
+
 /** Embedding backfill step result. */
 export interface BrainMaintenanceEmbeddingsResult {
   /** Observations successfully embedded. */
@@ -61,6 +72,8 @@ export interface BrainMaintenanceResult {
   decay: BrainMaintenanceDecayResult;
   /** Results from the memory consolidation step. */
   consolidation: BrainMaintenanceConsolidationResult;
+  /** Results from the cross-DB orphaned reference reconciliation step. */
+  reconciliation: BrainMaintenanceReconciliationResult;
   /** Results from the embedding backfill step. */
   embeddings: BrainMaintenanceEmbeddingsResult;
   /** Total wall-clock duration of the maintenance run in milliseconds. */
@@ -78,6 +91,8 @@ export interface BrainMaintenanceOptions {
   skipDecay?: boolean;
   /** Skip the memory consolidation step. Default: false. */
   skipConsolidation?: boolean;
+  /** Skip the cross-DB orphaned reference reconciliation step. Default: false. */
+  skipReconciliation?: boolean;
   /** Skip the embedding backfill step. Default: false. */
   skipEmbeddings?: boolean;
   /**
@@ -130,6 +145,7 @@ export async function runBrainMaintenance(
   const {
     skipDecay = false,
     skipConsolidation = false,
+    skipReconciliation = false,
     skipEmbeddings = false,
     onProgress,
   } = options ?? {};
@@ -139,6 +155,11 @@ export async function runBrainMaintenance(
   // Default zero values for each step (used when step is skipped).
   const decayResult: BrainMaintenanceDecayResult = { affected: 0 };
   const consolidationResult: BrainMaintenanceConsolidationResult = { merged: 0, removed: 0 };
+  const reconciliationResult: BrainMaintenanceReconciliationResult = {
+    decisionsFixed: 0,
+    observationsFixed: 0,
+    linksRemoved: 0,
+  };
   const embeddingsResult: BrainMaintenanceEmbeddingsResult = {
     processed: 0,
     skipped: 0,
@@ -162,7 +183,17 @@ export async function runBrainMaintenance(
     onProgress?.('consolidation', 1, 1);
   }
 
-  // Step 3: Embedding backfill (with per-item progress relay)
+  // Step 3: Cross-DB orphaned reference reconciliation
+  if (!skipReconciliation) {
+    onProgress?.('reconciliation', 0, 1);
+    const raw = await reconcileOrphanedRefs(projectRoot);
+    reconciliationResult.decisionsFixed = raw.decisionsFixed;
+    reconciliationResult.observationsFixed = raw.observationsFixed;
+    reconciliationResult.linksRemoved = raw.linksRemoved;
+    onProgress?.('reconciliation', 1, 1);
+  }
+
+  // Step 4: Embedding backfill (with per-item progress relay)
   if (!skipEmbeddings) {
     const raw = await populateEmbeddings(projectRoot, {
       onProgress: (current, total) => {
@@ -177,6 +208,7 @@ export async function runBrainMaintenance(
   return {
     decay: decayResult,
     consolidation: consolidationResult,
+    reconciliation: reconciliationResult,
     embeddings: embeddingsResult,
     duration: Date.now() - startTime,
   };

package/src/memory/brain-retrieval.ts

@@ -24,6 +24,8 @@ import type {
   BRAIN_OBSERVATION_SOURCE_TYPES,
   BRAIN_OBSERVATION_TYPES,
 } from '../store/brain-schema.js';
+import { sessionExistsInTasksDb } from '../store/cross-db-cleanup.js';
+import { getDb } from '../store/sqlite.js';
 import { typedAll } from '../store/typed-query.js';
 import { embedText, isEmbeddingAvailable } from './brain-embedding.js';
 import type {
@@ -560,6 +562,20 @@ export async function observeBrain(
     }
   }
 
+  // Write-guard: validate cross-db session reference before inserting
+  let validSessionId = sourceSessionId ?? null;
+  if (validSessionId) {
+    try {
+      const tasksDb = await getDb(projectRoot);
+      if (!(await sessionExistsInTasksDb(validSessionId, tasksDb))) {
+        validSessionId = null;
+      }
+    } catch {
+      // Best-effort: if tasks.db unavailable, null out the reference
+      validSessionId = null;
+    }
+  }
+
   const id = `O-${Date.now().toString(36)}-${(observeSeq++ % 1000).toString(36)}`;
   const accessor = await getBrainAccessor(projectRoot);
 
@@ -570,7 +586,7 @@ export async function observeBrain(
     narrative: text,
     contentHash,
     project: project ?? null,
-    sourceSessionId: sourceSessionId ?? null,
+    sourceSessionId: validSessionId,
     sourceType: sourceType ?? 'agent',
     createdAt: now,
   });
@@ -607,7 +623,7 @@ export async function observeBrain(
 
   // Auto-link observation to the currently focused task when a session is active. (T141)
   // This is a fire-and-forget side effect — linking failure MUST NOT block the return.
-  if (sourceSessionId) {
+  if (validSessionId) {
     autoLinkObservationToTask(projectRoot, row.id, accessor).catch(() => {
       /* Auto-linking is best-effort */
     });

package/src/memory/decisions.ts

@@ -11,6 +11,8 @@
 
 import { getBrainAccessor } from '../store/brain-accessor.js';
 import type { BrainDecisionRow, NewBrainDecisionRow } from '../store/brain-schema.js';
+import { taskExistsInTasksDb } from '../store/cross-db-cleanup.js';
+import { getDb } from '../store/sqlite.js';
 
 /** Parameters for storing a new decision. */
 export interface StoreDecisionParams {
@@ -110,6 +112,20 @@ export async function storeDecision(
 
   // Create new decision with sequential ID
   const id = await nextDecisionId(projectRoot);
+
+  // Write-guard: validate cross-db task references before inserting
+  let validEpicId = params.contextEpicId;
+  let validTaskId = params.contextTaskId;
+  if (validEpicId || validTaskId) {
+    const tasksDb = await getDb(projectRoot);
+    if (validEpicId && !(await taskExistsInTasksDb(validEpicId, tasksDb))) {
+      validEpicId = undefined;
+    }
+    if (validTaskId && !(await taskExistsInTasksDb(validTaskId, tasksDb))) {
+      validTaskId = undefined;
+    }
+  }
+
   const row: NewBrainDecisionRow = {
     id,
     type: params.type,
@@ -118,8 +134,8 @@ export async function storeDecision(
     confidence: params.confidence,
     outcome: params.outcome,
     alternativesJson: params.alternatives ? JSON.stringify(params.alternatives) : undefined,
-    contextEpicId: params.contextEpicId,
-    contextTaskId: params.contextTaskId,
+    contextEpicId: validEpicId,
+    contextTaskId: validTaskId,
     contextPhase: params.contextPhase,
   };
 

package/src/orchestration/hierarchy.ts

@@ -0,0 +1,202 @@
+/**
+ * OrchestrationHierarchyImpl — Concrete implementation of the 5-level hierarchy.
+ *
+ * Loads the agent matrix from agent-matrix.json (if available) or uses
+ * the built-in default matrix. Provides escalation chain resolution,
+ * authority checks, and project scoping.
+ *
+ * @see docs/specs/CLEO-ORCH-PLAN.md
+ * @task T217
+ */
+
+import type {
+  AgentHierarchy,
+  AgentHierarchyEntry,
+  EscalationChain,
+  OrchestrationHierarchyAPI,
+} from '@cleocode/contracts';
+import { OrchestrationLevel } from '@cleocode/contracts';
+
+/**
+ * Default agent hierarchy matching PRIME's agent matrix (Agenda 10).
+ *
+ * This is the canonical hierarchy as of 2026-03-30:
+ *   Owner (HITL)
+ *     └── cleoos-opus-orchestrator (PRIME)
+ *           ├── cleo-rust-lead → cleo-dev
+ *           ├── cleo-db-lead → signaldock-backend
+ *           ├── cleo-historian
+ *           └── signaldock-core-agent → signaldock-backend, signaldock-dev, signaldock-frontend
+ */
+function buildDefaultHierarchy(): AgentHierarchy {
+  const agents: Record<string, AgentHierarchyEntry> = {
+    owner: {
+      agentId: 'owner',
+      displayName: 'Owner (HITL)',
+      level: OrchestrationLevel.HITL,
+      reportsTo: null,
+      manages: ['cleoos-opus-orchestrator'],
+      projectId: null,
+      teamId: null,
+      canSpawn: false,
+    },
+    'cleoos-opus-orchestrator': {
+      agentId: 'cleoos-opus-orchestrator',
+      displayName: 'PRIME Orchestrator',
+      level: OrchestrationLevel.Prime,
+      reportsTo: 'owner',
+      manages: ['cleo-rust-lead', 'cleo-db-lead', 'cleo-historian', 'signaldock-core-agent'],
+      projectId: null,
+      teamId: null,
+      canSpawn: true,
+    },
+    'cleo-rust-lead': {
+      agentId: 'cleo-rust-lead',
+      displayName: 'Cleo Rust Lead',
+      level: OrchestrationLevel.ProjectLead,
+      reportsTo: 'cleoos-opus-orchestrator',
+      manages: ['cleo-dev'],
+      projectId: 'cleocode',
+      teamId: 'cleocode',
+      canSpawn: true,
+    },
+    'cleo-db-lead': {
+      agentId: 'cleo-db-lead',
+      displayName: 'Cleo DB Lead',
+      level: OrchestrationLevel.ProjectLead,
+      reportsTo: 'cleoos-opus-orchestrator',
+      manages: ['signaldock-backend'],
+      projectId: 'cleocode',
+      teamId: 'cleocode',
+      canSpawn: true,
+    },
+    'cleo-historian': {
+      agentId: 'cleo-historian',
+      displayName: 'Cleo Historian',
+      level: OrchestrationLevel.TeamLead,
+      reportsTo: 'cleoos-opus-orchestrator',
+      manages: [],
+      projectId: 'cleocode',
+      teamId: 'cleocode',
+      canSpawn: false,
+    },
+    'cleo-dev': {
+      agentId: 'cleo-dev',
+      displayName: 'Cleo Dev',
+      level: OrchestrationLevel.TeamLead,
+      reportsTo: 'cleo-rust-lead',
+      manages: [],
+      projectId: 'cleocode',
+      teamId: 'cleocode',
+      canSpawn: true,
+    },
+    'signaldock-core-agent': {
+      agentId: 'signaldock-core-agent',
+      displayName: 'SignalDock Core Agent',
+      level: OrchestrationLevel.ProjectLead,
+      reportsTo: 'cleoos-opus-orchestrator',
+      manages: ['signaldock-backend', 'signaldock-dev', 'signaldock-frontend'],
+      projectId: 'signaldock',
+      teamId: 'signaldock',
+      canSpawn: true,
+    },
+    'signaldock-backend': {
+      agentId: 'signaldock-backend',
+      displayName: 'SignalDock Backend',
+      level: OrchestrationLevel.TeamLead,
+      reportsTo: 'signaldock-core-agent',
+      manages: [],
+      projectId: 'signaldock',
+      teamId: 'signaldock',
+      canSpawn: false,
+    },
+    'signaldock-dev': {
+      agentId: 'signaldock-dev',
+      displayName: 'SignalDock Dev',
+      level: OrchestrationLevel.TeamLead,
+      reportsTo: 'signaldock-core-agent',
+      manages: [],
+      projectId: 'signaldock',
+      teamId: 'signaldock',
+      canSpawn: false,
+    },
+    'signaldock-frontend': {
+      agentId: 'signaldock-frontend',
+      displayName: 'SignalDock Frontend',
+      level: OrchestrationLevel.TeamLead,
+      reportsTo: 'signaldock-core-agent',
+      manages: [],
+      projectId: 'signaldock',
+      teamId: 'signaldock',
+      canSpawn: false,
+    },
+  };
+
+  return {
+    agents,
+    primeId: 'cleoos-opus-orchestrator',
+    projectIds: ['cleocode', 'signaldock'],
+  };
+}
+
+/** Concrete implementation of OrchestrationHierarchyAPI. */
+export class OrchestrationHierarchyImpl implements OrchestrationHierarchyAPI {
+  private hierarchy: AgentHierarchy;
+
+  constructor(hierarchy?: AgentHierarchy) {
+    this.hierarchy = hierarchy ?? buildDefaultHierarchy();
+  }
+
+  /** Get the full hierarchy. */
+  getHierarchy(): AgentHierarchy {
+    return this.hierarchy;
+  }
+
+  /** Get a single agent's hierarchy entry. */
+  getAgent(agentId: string): AgentHierarchyEntry | null {
+    return this.hierarchy.agents[agentId] ?? null;
+  }
+
+  /** Get all agents at a specific level. */
+  getAgentsAtLevel(level: OrchestrationLevel): AgentHierarchyEntry[] {
+    return Object.values(this.hierarchy.agents).filter((a) => a.level === level);
+  }
+
+  /** Get the escalation chain for an agent (nearest authority first). */
+  getEscalationChain(agentId: string): EscalationChain {
+    const chain: string[] = [];
+    let current = this.hierarchy.agents[agentId];
+
+    while (current?.reportsTo) {
+      chain.push(current.reportsTo);
+      current = this.hierarchy.agents[current.reportsTo];
+    }
+
+    return {
+      fromAgentId: agentId,
+      chain,
+      finalAuthority: chain.length > 0 ? chain[chain.length - 1]! : agentId,
+    };
+  }
+
+  /** Get all agents directly managed by a specific agent. */
+  getDirectReports(agentId: string): AgentHierarchyEntry[] {
+    const agent = this.hierarchy.agents[agentId];
+    if (!agent) return [];
+
+    return agent.manages
+      .map((id) => this.hierarchy.agents[id])
+      .filter((a): a is AgentHierarchyEntry => a !== undefined);
+  }
+
+  /** Check if agent A has authority over agent B (A is in B's escalation chain). */
+  hasAuthority(agentIdA: string, agentIdB: string): boolean {
+    const chain = this.getEscalationChain(agentIdB);
+    return chain.chain.includes(agentIdA);
+  }
+
+  /** Get all agents scoped to a project. */
+  getProjectAgents(projectId: string): AgentHierarchyEntry[] {
+    return Object.values(this.hierarchy.agents).filter((a) => a.projectId === projectId);
+  }
+}

package/src/orchestration/index.ts

@@ -20,6 +20,7 @@ export {
 } from './analyze.js';
 export type { ContextEstimation } from './context.js';
 export { countManifestEntries, estimateContext } from './context.js';
+export { OrchestrationHierarchyImpl } from './hierarchy.js';
 export type {
   EpicStatus,
   OverallStatus,