@cleocode/core 2026.4.30 → 2026.4.31

package/src/hooks/handlers/__tests__/session-hooks.test.ts

@@ -1,77 +1,65 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-const observeBrainMock = vi.fn();
+const mocks = vi.hoisted(() => ({
+  maybeRefreshMemoryBridge: vi.fn(),
+  gradeSession: vi.fn(),
+  loadConfig: vi.fn(),
+}));
+
+vi.mock('../memory-bridge-refresh.js', () => ({
+  maybeRefreshMemoryBridge: mocks.maybeRefreshMemoryBridge,
+}));
+
+vi.mock('../../../sessions/session-grade.js', () => ({
+  gradeSession: mocks.gradeSession,
+}));
 
-vi.mock('../../../memory/brain-retrieval.js', () => ({
-  observeBrain: observeBrainMock,
+vi.mock('../../../config.js', () => ({
+  loadConfig: mocks.loadConfig,
 }));
 
 import { handleSessionEnd, handleSessionStart } from '../session-hooks.js';
 
 describe('session hook handlers', () => {
   beforeEach(() => {
-    observeBrainMock.mockReset();
+    mocks.maybeRefreshMemoryBridge.mockReset();
+    mocks.maybeRefreshMemoryBridge.mockResolvedValue(undefined);
+    mocks.gradeSession.mockResolvedValue(undefined);
+    mocks.loadConfig.mockResolvedValue({ brain: { autoCapture: false } });
   });
 
-  it('swallows missing brain schema errors on session start', async () => {
-    observeBrainMock.mockRejectedValue(
-      new Error('SQLITE_ERROR: no such table: brain_observations'),
-    );
+  it('handleSessionStart refreshes the memory bridge', async () => {
+    await handleSessionStart('/tmp/project', {
+      sessionId: 'ses-1',
+      timestamp: '2026-03-04T00:00:00.000Z',
+      name: 'Test Session',
+      scope: 'T5306',
+    });
 
-    await expect(
-      handleSessionStart('/tmp/project', {
-        sessionId: 'ses-1',
-        timestamp: '2026-03-04T00:00:00.000Z',
-        name: 'Test Session',
-        scope: 'T5306',
-      }),
-    ).resolves.toBeUndefined();
+    expect(mocks.maybeRefreshMemoryBridge).toHaveBeenCalledTimes(1);
+    expect(mocks.maybeRefreshMemoryBridge).toHaveBeenCalledWith('/tmp/project');
   });
 
-  it('swallows missing brain schema errors on session end', async () => {
-    observeBrainMock.mockRejectedValue(new Error('no such table: brain_decisions'));
+  it('handleSessionEnd refreshes the memory bridge', async () => {
+    await handleSessionEnd('/tmp/project', {
+      sessionId: 'ses-2',
+      timestamp: '2026-03-04T00:30:00.000Z',
+      duration: 1800,
+      tasksCompleted: ['T5306', 'T5307'],
+    });
+
+    expect(mocks.maybeRefreshMemoryBridge).toHaveBeenCalledTimes(1);
+    expect(mocks.maybeRefreshMemoryBridge).toHaveBeenCalledWith('/tmp/project');
+  });
 
+  it('handleSessionEnd resolves normally with no tasks', async () => {
     await expect(
       handleSessionEnd('/tmp/project', {
-        sessionId: 'ses-1',
+        sessionId: 'ses-3',
         timestamp: '2026-03-04T00:30:00.000Z',
-        duration: 1800,
+        duration: 900,
         tasksCompleted: [],
       }),
     ).resolves.toBeUndefined();
   });
-
-  it('rethrows non-schema errors', async () => {
-    observeBrainMock.mockRejectedValue(new Error('database is locked'));
-
-    await expect(
-      handleSessionStart('/tmp/project', {
-        sessionId: 'ses-1',
-        timestamp: '2026-03-04T00:00:00.000Z',
-        name: 'Test Session',
-        scope: 'T5306',
-      }),
-    ).rejects.toThrow('database is locked');
-  });
-
-  it('records session context when observe succeeds', async () => {
-    observeBrainMock.mockResolvedValue(undefined);
-
-    await handleSessionEnd('/tmp/project', {
-      sessionId: 'ses-2',
-      timestamp: '2026-03-04T00:45:00.000Z',
-      duration: 2700,
-      tasksCompleted: ['T5306', 'T5307'],
-    });
-
-    expect(observeBrainMock).toHaveBeenCalledTimes(1);
-    expect(observeBrainMock).toHaveBeenCalledWith(
-      '/tmp/project',
-      expect.objectContaining({
-        title: 'Session end: ses-2',
-        type: 'change',
-        sourceSessionId: 'ses-2',
-      }),
-    );
-  });
 });

package/src/hooks/handlers/session-hooks.ts

@@ -1,7 +1,7 @@
 /**
  * Session Hook Handlers - Phase 2D of T5237
  *
- * Handlers that capture session lifecycle events to BRAIN via memory.observe.
+ * Handlers that capture session lifecycle events.
  * Auto-registers on module load.
  *
  * T138: Triggers memory bridge refresh on session start and end.
@@ -10,65 +10,43 @@
  * T5158: Auto-snapshots SQLite databases (tasks.db + brain.db) via
  *        VACUUM INTO on SessionEnd to preserve a recovery point now that
  *        the databases are no longer tracked in project git (ADR-013).
+ * T527: Removed duplicate session observeBrain writes — session data already
+ *       lives in the sessions table; writing it again to brain_observations
+ *       was pure noise.
  */
 
 import { hooks } from '../registry.js';
 import type { SessionEndPayload, SessionStartPayload } from '../types.js';
-import { isMissingBrainSchemaError } from './handler-helpers.js';
 import { maybeRefreshMemoryBridge } from './memory-bridge-refresh.js';
 
 /**
- * Handle SessionStart - capture initial session context
+ * Handle SessionStart - refresh memory bridge on session start.
  *
  * T138: Refresh memory bridge on session start.
  * T139: Regenerate bridge with session scope context.
+ * T527: Removed duplicate observeBrain write — session data is already
+ *       persisted in the sessions table.
  */
 export async function handleSessionStart(
   projectRoot: string,
-  payload: SessionStartPayload,
+  _payload: SessionStartPayload,
 ): Promise<void> {
-  const { observeBrain } = await import('../../memory/brain-retrieval.js');
-
-  try {
-    await observeBrain(projectRoot, {
-      text: `Session started: ${payload.name}\nScope: ${JSON.stringify(payload.scope)}\nAgent: ${payload.agent || 'unknown'}`,
-      title: `Session start: ${payload.name}`,
-      type: 'discovery',
-      sourceSessionId: payload.sessionId,
-      sourceType: 'agent',
-    });
-  } catch (err) {
-    if (!isMissingBrainSchemaError(err)) throw err;
-  }
-
   // T138/T139: Refresh memory bridge after session starts (best-effort)
   await maybeRefreshMemoryBridge(projectRoot);
 }
 
 /**
- * Handle SessionEnd - capture session summary
+ * Handle SessionEnd - run post-session tasks and refresh memory bridge.
  *
  * T138: Refresh memory bridge after session ends.
  * T144: Extract transcript observations via cross-provider adapter.
+ * T527: Removed duplicate observeBrain write — session data is already
+ *       persisted in the sessions table.
  */
 export async function handleSessionEnd(
   projectRoot: string,
   payload: SessionEndPayload,
 ): Promise<void> {
-  const { observeBrain } = await import('../../memory/brain-retrieval.js');
-
-  try {
-    await observeBrain(projectRoot, {
-      text: `Session ended: ${payload.sessionId}\nDuration: ${payload.duration}s\nTasks completed: ${payload.tasksCompleted.join(', ') || 'none'}`,
-      title: `Session end: ${payload.sessionId}`,
-      type: 'change',
-      sourceSessionId: payload.sessionId,
-      sourceType: 'agent',
-    });
-  } catch (err) {
-    if (!isMissingBrainSchemaError(err)) throw err;
-  }
-
   // Auto-grade session and feed insights to brain.db (best-effort)
   try {
     const { gradeSession } = await import('../../sessions/session-grade.js');

package/src/index.ts

@@ -299,6 +299,20 @@ export {
   timelineBrain,
 } from './memory/brain-retrieval.js';
 export { searchBrain } from './memory/brain-search.js';
+export type {
+  DecisionQualityInput,
+  LearningQualityInput,
+  ObservationQualityInput,
+  PatternQualityInput,
+} from './memory/quality-scoring.js';
+// Quality scoring (T531) — exported for backfill (T530) and future hooks
+export {
+  computeDecisionQuality,
+  computeLearningQuality,
+  computeObservationQuality,
+  computePatternQuality,
+  QUALITY_SCORE_THRESHOLD,
+} from './memory/quality-scoring.js';
 // Migration (flat re-exports for backward compatibility)
 export {
   compareSemver,

package/src/internal.ts

@@ -22,6 +22,16 @@ export * from './index.js';
 // Extended flat exports (required by @cleocode/cleo)
 // ---------------------------------------------------------------------------
 
+// Code analysis (Smart Explore) — canonical source: @cleocode/nexus
+export {
+  batchParse,
+  isTreeSitterAvailable,
+  parseFile,
+  type SmartSearchOptions,
+  smartOutline,
+  smartSearch,
+  smartUnfold,
+} from '@cleocode/nexus';
 export { exportTasks } from './admin/export.js';
 export { exportTasksPackage } from './admin/export-tasks.js';
 // Admin
@@ -36,17 +46,17 @@ export type { AuditEntry } from './audit.js';
 // Backfill
 export type { BackfillOptions, BackfillResult, BackfillTaskChange } from './backfill/index.js';
 export { backfillTasks, generateAcFromDescription } from './backfill/index.js';
-export type { BootstrapContext, BootstrapOptions } from './bootstrap.js';
+export type {
+  BootstrapContext,
+  BootstrapOptions,
+  BootstrapVerificationResult,
+} from './bootstrap.js';
 // Bootstrap (global setup)
 export {
   bootstrapGlobalCleo,
   installSkillsGlobally,
+  verifyBootstrapComplete,
 } from './bootstrap.js';
-export { smartOutline } from './code/outline.js';
-// Code analysis (Smart Explore)
-export { batchParse, isTreeSitterAvailable, parseFile } from './code/parser.js';
-export { type SmartSearchOptions, 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';
@@ -63,7 +73,6 @@ 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 {
@@ -146,6 +155,8 @@ export {
 } from './lifecycle/index.js';
 export { STAGE_DEFINITIONS } from './lifecycle/stages.js';
 export { instantiateTessera, showTessera } from './lifecycle/tessera-engine.js';
+export type { BrainBackfillResult } from './memory/brain-backfill.js';
+export { backfillBrainGraph } from './memory/brain-backfill.js';
 // Memory — brain lifecycle (temporal decay + consolidation)
 export type { ConsolidationResult, DecayResult } from './memory/brain-lifecycle.js';
 export { applyTemporalDecay, consolidateMemories } from './memory/brain-lifecycle.js';
@@ -159,6 +170,8 @@ export type {
   BrainMaintenanceResult,
 } from './memory/brain-maintenance.js';
 export { runBrainMaintenance } from './memory/brain-maintenance.js';
+export type { PurgeResult } from './memory/brain-purge.js';
+export { purgeBrainNoise } from './memory/brain-purge.js';
 export type {
   PopulateEmbeddingsOptions,
   PopulateEmbeddingsResult,
@@ -174,9 +187,13 @@ export {
   memoryFetch,
   memoryFind,
   memoryGraphAdd,
+  memoryGraphContext,
   memoryGraphNeighbors,
+  memoryGraphRelated,
   memoryGraphRemove,
   memoryGraphShow,
+  memoryGraphStatsFull,
+  memoryGraphTrace,
   memoryLearningFind,
   memoryLearningStats,
   memoryLearningStore,
@@ -193,6 +210,13 @@ export {
   memoryTimeline,
   memoryUnlink,
 } from './memory/engine-compat.js';
+// Memory — graph traversal query functions (T535)
+export type {
+  GraphStats,
+  NodeContext,
+  RelatedNode,
+  TraceNode,
+} from './memory/graph-queries.js';
 // Memory — pipeline manifests
 export {
   pipelineManifestAppend,
@@ -491,6 +515,12 @@ export type { BackupEntry, BackupResult, RestoreResult } from './system/backup.j
 export { listSystemBackups, restoreBackup } from './system/backup.js';
 export type { CleanupResult } from './system/cleanup.js';
 export { cleanupSystem } from './system/cleanup.js';
+// System — dependency registry
+export {
+  checkAllDependencies,
+  checkDependency,
+  getDependencySpecs,
+} from './system/dependencies.js';
 export type { DiagnosticsResult, HealthResult } from './system/health.js';
 export { getSystemDiagnostics, getSystemHealth, startupHealthCheck } from './system/health.js';
 export type {

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

@@ -1,10 +1,11 @@
 /**
  * Tree-sitter language detection and grammar resolution.
  *
- * Maps file extensions to tree-sitter grammar packages for use by
- * the Smart Explore code analysis pipeline.
+ * Maps file extensions to tree-sitter language identifiers used by
+ * the Smart Explore code analysis pipeline (outline, search, unfold).
+ * Grammar loading is handled internally by parser.ts via native Node bindings.
  *
- * @task T148
+ * @task T509
  */
 
 /** Supported tree-sitter language identifiers. */
@@ -60,9 +61,9 @@ const GRAMMAR_PACKAGE_MAP: Record<TreeSitterLanguage, string> = {
 };
 
 /**
- * Detect tree-sitter language from a file path.
+ * Detect tree-sitter language from a file path or file name.
  *
- * @param filePath - Path to a source file
+ * @param filePath - Path to a source file (or bare file name)
  * @returns The detected language, or undefined if unsupported
  */
 export function detectLanguage(filePath: string): TreeSitterLanguage | undefined {
@@ -74,6 +75,9 @@ export function detectLanguage(filePath: string): TreeSitterLanguage | undefined
 /**
  * Get the npm grammar package name for a language.
  *
+ * The package name matches the native Node binding that parser.ts loads
+ * via {@link createRequire}. Useful for diagnostics and install hints.
+ *
  * @param language - A tree-sitter language identifier
  * @returns The npm package name containing the grammar
  */
@@ -81,8 +85,8 @@ export function grammarPackage(language: TreeSitterLanguage): string {
   return GRAMMAR_PACKAGE_MAP[language];
 }
 
-/** All supported file extensions. */
+/** All supported file extensions (without leading dot). */
 export const SUPPORTED_EXTENSIONS = Object.keys(EXTENSION_MAP);
 
-/** All supported languages. */
+/** All supported languages (deduplicated). */
 export const SUPPORTED_LANGUAGES: TreeSitterLanguage[] = [...new Set(Object.values(EXTENSION_MAP))];

package/src/memory/__tests__/auto-extract.test.ts

@@ -1,7 +1,11 @@
 /**
  * Unit tests for auto-extract memory pipeline.
  *
- * All external dependencies are mocked — this tests extraction logic only.
+ * extractTaskCompletionMemory and extractSessionEndMemory are disabled no-ops
+ * per T523 CA1 specification. Tests verify the no-op contract holds.
+ *
+ * @task T526
+ * @epic T523
  */
 
 import type { Task } from '@cleocode/contracts';
@@ -21,7 +25,7 @@ vi.mock('../decisions.js', () => ({
   storeDecision: vi.fn().mockResolvedValue(undefined),
 }));
 
-// Mock getAccessor used inside auto-extract for pattern detection
+// Mock getAccessor — should never be called by disabled functions
 vi.mock('../../store/data-accessor.js', () => ({
   getAccessor: vi.fn(),
 }));
@@ -80,24 +84,16 @@ beforeEach(() => {
 });
 
 describe('extractTaskCompletionMemory', () => {
-  it('creates a learning from completed task', async () => {
+  it('is a no-op — does not write learnings', async () => {
     const task = makeTask({ id: 'T001', title: 'Fix auth bug', description: 'Auth was broken' });
     setupAccessor([task]);
 
     await extractTaskCompletionMemory('/mock/root', task);
 
-    expect(storeLearning).toHaveBeenCalledWith(
-      '/mock/root',
-      expect.objectContaining({
-        insight: `Completed: ${task.title} — ${task.description}`,
-        source: `task-completion:${task.id}`,
-        confidence: 0.7,
-        actionable: true,
-      }),
-    );
+    expect(storeLearning).not.toHaveBeenCalled();
   });
 
-  it('creates dependency learning when task has dependencies', async () => {
+  it('is a no-op — does not write dependency learnings', async () => {
     const task = makeTask({
       id: 'T002',
       title: 'Deploy feature',
@@ -108,28 +104,10 @@ describe('extractTaskCompletionMemory', () => {
 
     await extractTaskCompletionMemory('/mock/root', task);
 
-    const calls = (storeLearning as ReturnType<typeof vi.fn>).mock.calls;
-    const depCall = calls.find((c) =>
-      (c[1] as { insight: string }).insight.includes('depended on'),
-    );
-    expect(depCall).toBeDefined();
-    expect((depCall![1] as { insight: string }).insight).toContain('T001, T003');
-    expect((depCall![1] as { source: string }).source).toBe('task-completion:T002');
-  });
-
-  it('does not create dependency learning when task has no dependencies', async () => {
-    const task = makeTask({ id: 'T003', title: 'Solo task', depends: [] });
-    setupAccessor([task]);
-
-    await extractTaskCompletionMemory('/mock/root', task);
-
-    const depCall = (storeLearning as ReturnType<typeof vi.fn>).mock.calls.find((c) =>
-      (c[1] as { insight: string }).insight.includes('depended on'),
-    );
-    expect(depCall).toBeUndefined();
+    expect(storeLearning).not.toHaveBeenCalled();
   });
 
-  it('stores a pattern when a label appears 3+ times in done tasks', async () => {
+  it('is a no-op — does not write label patterns', async () => {
     const completedTasks = [
       makeTask({ id: 'T010', title: 'A', labels: ['bug'] }),
       makeTask({ id: 'T011', title: 'B', labels: ['bug'] }),
@@ -140,17 +118,11 @@ describe('extractTaskCompletionMemory', () => {
 
     await extractTaskCompletionMemory('/mock/root', trigger);
 
-    expect(storePattern).toHaveBeenCalledWith(
-      '/mock/root',
-      expect.objectContaining({
-        type: 'success',
-        impact: 'medium',
-      }),
-    );
+    expect(storePattern).not.toHaveBeenCalled();
+    expect(getAccessor).not.toHaveBeenCalled();
   });
 
-  it('does not throw on error', async () => {
-    (storeLearning as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('db error'));
+  it('resolves to undefined without throwing', async () => {
     setupAccessor([]);
 
     await expect(
@@ -160,7 +132,7 @@ describe('extractTaskCompletionMemory', () => {
 });
 
 describe('extractSessionEndMemory', () => {
-  it('creates a decision when tasks are completed', async () => {
+  it('is a no-op — does not write a session decision', async () => {
     const tasks = [
       makeTask({ id: 'T001', title: 'Task one' }),
       makeTask({ id: 'T002', title: 'Task two' }),
@@ -169,32 +141,10 @@ describe('extractSessionEndMemory', () => {
 
     await extractSessionEndMemory('/mock/root', session, tasks);
 
-    expect(storeDecision).toHaveBeenCalledWith(
-      '/mock/root',
-      expect.objectContaining({
-        type: 'process',
-        confidence: 'medium',
-      }),
-    );
-    const call = (storeDecision as ReturnType<typeof vi.fn>).mock.calls[0][1] as {
-      decision: string;
-      rationale: string;
-    };
-    expect(call.decision).toContain('S-001');
-    expect(call.decision).toContain('T001');
-    expect(call.decision).toContain('T002');
-    expect(call.rationale).toContain('test scope');
-  });
-
-  it('does not create a decision when no tasks completed', async () => {
-    const session = makeSessionData({ tasksCompleted: [] });
-
-    await extractSessionEndMemory('/mock/root', session, []);
-
     expect(storeDecision).not.toHaveBeenCalled();
   });
 
-  it('creates per-task learnings', async () => {
+  it('is a no-op — does not write per-task learnings', async () => {
     const tasks = [
       makeTask({ id: 'T001', title: 'Task one', description: 'Desc one' }),
       makeTask({ id: 'T002', title: 'Task two', description: 'Desc two' }),
@@ -203,15 +153,10 @@ describe('extractSessionEndMemory', () => {
 
     await extractSessionEndMemory('/mock/root', session, tasks);
 
-    const calls = (storeLearning as ReturnType<typeof vi.fn>).mock.calls;
-    expect(calls.length).toBe(2);
-    calls.forEach((c) => {
-      expect((c[1] as { source: string }).source).toBe('session-end:S-002');
-      expect((c[1] as { confidence: number }).confidence).toBe(0.7);
-    });
+    expect(storeLearning).not.toHaveBeenCalled();
   });
 
-  it('stores a workflow pattern when 2+ tasks share a label', async () => {
+  it('is a no-op — does not write workflow patterns', async () => {
     const tasks = [
       makeTask({ id: 'T001', title: 'A', labels: ['feature'] }),
       makeTask({ id: 'T002', title: 'B', labels: ['feature'] }),
@@ -220,17 +165,10 @@ describe('extractSessionEndMemory', () => {
 
     await extractSessionEndMemory('/mock/root', session, tasks);
 
-    expect(storePattern).toHaveBeenCalledWith(
-      '/mock/root',
-      expect.objectContaining({
-        type: 'workflow',
-        impact: 'medium',
-      }),
-    );
+    expect(storePattern).not.toHaveBeenCalled();
   });
 
-  it('does not throw on error', async () => {
-    (storeDecision as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('db fail'));
+  it('resolves to undefined without throwing', async () => {
     const tasks = [makeTask({ id: 'T001', title: 'X' })];
     const session = makeSessionData({ tasksCompleted: ['T001'] });