@cleocode/core 2026.4.30 → 2026.4.35

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/index.ts

@@ -17,13 +17,19 @@ import './notification-hooks.js';
 import './work-capture-hooks.js';
 import './agent-hooks.js';
 import './context-hooks.js';
+import './watchdog-hooks.js';
+// T549 Wave 5-D/E: Intelligence hooks (best-effort risk detection on task start)
+import './intelligence-hooks.js';
 
 export { handleSubagentStart, handleSubagentStop } from './agent-hooks.js';
 export { handlePostCompact, handlePreCompact } from './context-hooks.js';
 export { handleError } from './error-hooks.js';
 export { handleFileChange } from './file-hooks.js';
+// T549 Wave 5-D/E: Intelligence hook exports
+export { handleTaskStartIntelligence } from './intelligence-hooks.js';
 export { handleSystemNotification } from './notification-hooks.js';
 // Re-export handler functions for explicit use
 export { handleSessionEnd, handleSessionStart } from './session-hooks.js';
 export { handleToolComplete, handleToolStart } from './task-hooks.js';
+export { handleWatchdogStart, handleWatchdogStop } from './watchdog-hooks.js';
 export { handleWorkPromptSubmit, handleWorkResponseComplete } from './work-capture-hooks.js';

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

@@ -0,0 +1,80 @@
+/**
+ * Intelligence Hook Handlers — Wave 5-D/E of T549
+ *
+ * Best-effort intelligence side-effects wired into task lifecycle events.
+ *
+ * On task start → calculate risk; if riskScore exceeds the HIGH threshold
+ * (≥ 0.8), store a warning observation so future agents see it.
+ *
+ * All handlers are fire-and-forget: failures MUST NOT propagate or block the
+ * operation that triggered them.
+ *
+ * @task T549
+ * @epic T549
+ */
+
+import { hooks } from '../registry.js';
+import type { PreToolUsePayload } from '../types.js';
+
+// Risk thresholds — mirror RISK_THRESHOLDS in intelligence/prediction.ts
+const RISK_HIGH = 0.8;
+
+// ============================================================================
+// Task Start — Risk Detection
+// ============================================================================
+
+/**
+ * Handle task start: calculate risk and store a warning observation if the
+ * riskScore is at or above the HIGH threshold (≥ 0.8).
+ *
+ * Uses deferred imports so this module can be imported in environments where
+ * not all transitive dependencies (brain.db, tasks.db) are present.
+ *
+ * Best-effort: any error is silently swallowed.
+ */
+export async function handleTaskStartIntelligence(
+  projectRoot: string,
+  payload: PreToolUsePayload,
+): Promise<void> {
+  try {
+    // Deferred relative imports — avoids circular dependency issues and keeps
+    // this module loadable in environments where brain.db is not initialised.
+    const { getAccessor } = await import('../../store/data-accessor.js');
+    const { getBrainAccessor } = await import('../../store/brain-accessor.js');
+    const { calculateTaskRisk } = await import('../../intelligence/prediction.js');
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+
+    const [accessor, brain] = await Promise.all([
+      getAccessor(projectRoot),
+      getBrainAccessor(projectRoot),
+    ]);
+
+    const risk = await calculateTaskRisk(payload.taskId, accessor, brain);
+
+    if (risk.riskScore >= RISK_HIGH) {
+      const level = risk.riskScore >= 0.95 ? 'critical' : 'high';
+      const factorNames = risk.factors.map((f) => f.name).join(', ');
+      await observeBrain(projectRoot, {
+        text: `Risk alert for ${payload.taskId} (score ${risk.riskScore.toFixed(2)}): ${factorNames}. ${risk.recommendation}`,
+        title: `Task risk: ${level} — ${payload.taskId}`,
+        type: 'discovery',
+        sourceType: 'agent',
+      });
+    }
+  } catch {
+    // Best-effort — never block task start
+  }
+}
+
+// ============================================================================
+// Registration
+// ============================================================================
+
+hooks.register({
+  id: 'intelligence-task-start',
+  event: 'PreToolUse',
+  handler: handleTaskStartIntelligence,
+  // Priority 50: runs after brain-tool-start (100) so the task observation is
+  // already persisted before we assess risk.
+  priority: 50,
+});

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,45 @@
  * 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.
+ * T549 Wave 3-E: Fire-and-forget sleep-time consolidation on session end.
+ *       Runs after backup (priority 5) so brain.db snapshot is captured first.
  */
 
 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');
@@ -131,6 +111,36 @@ export async function handleSessionEndBackup(
   }
 }
 
+/**
+ * Handle SessionEnd — fire-and-forget sleep-time memory consolidation.
+ *
+ * T549 Wave 3-E: Runs the full consolidation pipeline (dedup, quality recompute,
+ * tier promotion, contradiction detection, soft eviction, graph strengthening,
+ * summary generation) in the background after the session backup has completed.
+ *
+ * Uses setImmediate to yield control so the session end flow completes before
+ * consolidation begins. Consolidation errors are caught and logged to console.warn
+ * — they MUST NOT block session end or throw to callers.
+ *
+ * Priority 5 ensures this runs last (after backup at priority 10).
+ */
+export async function handleSessionEndConsolidation(
+  projectRoot: string,
+  _payload: SessionEndPayload,
+): Promise<void> {
+  // Schedule consolidation to run after the current event loop turn.
+  // This ensures the session end response reaches the caller before
+  // consolidation begins, matching the "sleep-time compute" pattern.
+  setImmediate(async () => {
+    try {
+      const { runConsolidation } = await import('../../memory/brain-lifecycle.js');
+      await runConsolidation(projectRoot);
+    } catch (err) {
+      console.warn('[consolidation] Session-end consolidation failed:', err);
+    }
+  });
+}
+
 // Register handlers on module load
 hooks.register({
   id: 'brain-session-start',
@@ -155,3 +165,12 @@ hooks.register({
   handler: handleSessionEndBackup,
   priority: 10,
 });
+
+// Priority 5 runs AFTER backup (priority 10) — consolidation is purely
+// additive and should not delay the backup point-in-time snapshot.
+hooks.register({
+  id: 'consolidation-session-end',
+  event: 'SessionEnd',
+  handler: handleSessionEndConsolidation,
+  priority: 5,
+});

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

@@ -0,0 +1,187 @@
+/**
+ * Watchdog Scheduler Hook Handlers
+ *
+ * Starts a periodic health-check timer when a session begins and stops it when
+ * the session ends. One watchdog per project root, enforced by a module-level
+ * Map keyed on the resolved project root.
+ *
+ * Each 60-second tick:
+ * 1. Detects agents with a stale heartbeat (> STALE_THRESHOLD_MS)
+ * 2. Records each crash as a learning event in brain.db
+ * 3. Attempts recovery (status reset to 'starting') for all crashed agents
+ * 4. Fires the `onPatrol` hook for observability
+ *
+ * Best-effort contract: the watchdog NEVER crashes or throws. Any tick failure
+ * is swallowed so the timer continues. Any error in the start/stop handlers is
+ * also swallowed so it never blocks session operations.
+ *
+ * Gated behind `brain.autoCapture` config — the watchdog does NOT start unless
+ * auto-capture is enabled.
+ *
+ * Auto-registers on module load.
+ *
+ * @task T549
+ * @epic T5149
+ */
+
+import { hooks } from '../registry.js';
+import type { OnPatrolPayload, SessionEndPayload, SessionStartPayload } from '../types.js';
+import { isAutoCaptureEnabled, isMissingBrainSchemaError } from './handler-helpers.js';
+
+// ---------------------------------------------------------------------------
+// Module-level watchdog state
+// ---------------------------------------------------------------------------
+
+/** One active timer per project root (resolved path). */
+const activeWatchdogs = new Map<string, ReturnType<typeof setInterval>>();
+
+/** Interval between watchdog ticks in milliseconds. */
+const WATCHDOG_INTERVAL_MS = 60_000;
+
+// ---------------------------------------------------------------------------
+// Watchdog tick
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute one watchdog patrol tick.
+ *
+ * Steps:
+ * 1. detectCrashedAgents — find and mark stale agents as 'crashed'
+ * 2. processAgentLifecycleEvent — write failure events to brain.db for each
+ * 3. recoverCrashedAgents — reset crashed agents to 'starting'
+ * 4. hooks.dispatch('onPatrol') — emit observability event
+ *
+ * Any thrown error is caught and logged as a warning; the timer continues.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+async function runWatchdogTick(projectRoot: string): Promise<void> {
+  try {
+    const { detectCrashedAgents, STALE_THRESHOLD_MS } = await import(
+      '../../agents/health-monitor.js'
+    );
+    const { recoverCrashedAgents } = await import('../../agents/retry.js');
+    const { processAgentLifecycleEvent } = await import('../../agents/execution-learning.js');
+
+    // Step 1: Detect and mark crashed agents
+    const crashed = await detectCrashedAgents(STALE_THRESHOLD_MS, projectRoot);
+
+    // Step 2: Record each crash as a brain learning event
+    for (const agent of crashed) {
+      try {
+        await processAgentLifecycleEvent(
+          {
+            agentId: agent.id,
+            agentType:
+              (agent.agentType as import('../../agents/agent-schema.js').AgentType) ?? 'custom',
+            taskId: agent.taskId ?? 'unknown',
+            taskType: 'unknown',
+            outcome: 'failure',
+            errorMessage: 'Heartbeat timeout — agent presumed crashed',
+            errorType: 'retriable',
+            sessionId: agent.sessionId ?? undefined,
+          },
+          projectRoot,
+        );
+      } catch (err) {
+        if (!isMissingBrainSchemaError(err)) {
+          console.warn('[watchdog] Failed to record agent crash event:', err);
+        }
+      }
+    }
+
+    // Step 3: Attempt recovery for all crashed agents
+    if (crashed.length > 0) {
+      await recoverCrashedAgents(STALE_THRESHOLD_MS, projectRoot);
+    }
+
+    // Step 4: Fire onPatrol for observability
+    const patrolPayload: OnPatrolPayload = {
+      timestamp: new Date().toISOString(),
+      watcherId: 'health-watchdog',
+      patrolType: 'health',
+      scope: `crashed=${crashed.length}`,
+    };
+    await hooks.dispatch('onPatrol', projectRoot, patrolPayload);
+  } catch (err) {
+    // Best-effort — never crash the watchdog timer
+    console.warn('[watchdog] Tick failed:', err);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle SessionStart — start the watchdog timer for this project root.
+ *
+ * Idempotent: if a watchdog is already running for this root (e.g. a second
+ * session in the same process), the existing timer is reused.
+ *
+ * Gated behind `brain.autoCapture` — watchdog does not start unless auto-capture
+ * is enabled. This aligns with all other brain-capture hooks.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param _payload - SessionStart payload (unused).
+ */
+export async function handleWatchdogStart(
+  projectRoot: string,
+  _payload: SessionStartPayload,
+): Promise<void> {
+  try {
+    if (!(await isAutoCaptureEnabled(projectRoot))) return;
+
+    // Idempotency guard — one watchdog per project root
+    if (activeWatchdogs.has(projectRoot)) return;
+
+    const timer = setInterval(() => {
+      void runWatchdogTick(projectRoot);
+    }, WATCHDOG_INTERVAL_MS);
+
+    activeWatchdogs.set(projectRoot, timer);
+  } catch {
+    // Never block session start on watchdog errors
+  }
+}
+
+/**
+ * Handle SessionEnd — stop the watchdog timer for this project root.
+ *
+ * Safe to call when no watchdog is running (no-op).
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param _payload - SessionEnd payload (unused).
+ */
+export async function handleWatchdogStop(
+  projectRoot: string,
+  _payload: SessionEndPayload,
+): Promise<void> {
+  try {
+    const timer = activeWatchdogs.get(projectRoot);
+    if (timer) {
+      clearInterval(timer);
+      activeWatchdogs.delete(projectRoot);
+    }
+  } catch {
+    // Never block session end on watchdog errors
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-registration
+// ---------------------------------------------------------------------------
+
+hooks.register({
+  id: 'watchdog-session-start',
+  event: 'SessionStart',
+  handler: handleWatchdogStart,
+  priority: 50,
+});
+
+hooks.register({
+  id: 'watchdog-session-end',
+  event: 'SessionEnd',
+  handler: handleWatchdogStop,
+  priority: 50,
+});

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/injection.ts

@@ -16,7 +16,7 @@
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { getAgentsHome, getCleoHome, getCleoTemplatesTildePath } from './paths.js';
@@ -68,6 +68,32 @@ async function removeStaleAgentInjection(projectRoot: string): Promise<boolean>
   return true;
 }
 
+/**
+ * Strip hardcoded `<!-- gitnexus:start -->...<!-- gitnexus:end -->` blocks
+ * from AGENTS.md. These blocks are replaced by the `@.cleo/nexus-bridge.md`
+ * reference which contains auto-generated code intelligence content (T552).
+ *
+ * Also strips any other known vendor marker blocks using the same pattern
+ * (e.g. `<!-- gitnexus:start -->...<!-- gitnexus:end -->`).
+ *
+ * @param filePath - Absolute path to the file to strip
+ * @returns True if the file was modified, false otherwise
+ */
+export async function stripGitNexusBlocks(filePath: string): Promise<boolean> {
+  if (!existsSync(filePath)) return false;
+  const content = await readFile(filePath, 'utf8');
+  // Strip <!-- gitnexus:start --> ... <!-- gitnexus:end --> blocks (case-insensitive markers)
+  const stripped = content.replace(
+    /\n?<!--\s*gitnexus:start\s*-->[\s\S]*?<!--\s*gitnexus:end\s*-->\n?/gi,
+    '',
+  );
+  if (stripped !== content) {
+    await writeFile(filePath, stripped, 'utf8');
+    return true;
+  }
+  return false;
+}
+
 // ── Ensure injection ─────────────────────────────────────────────────
 
 /**
@@ -78,7 +104,7 @@ async function removeStaleAgentInjection(projectRoot: string): Promise<boolean>
  *
  * Target architecture:
  *   CLAUDE.md/GEMINI.md -> @AGENTS.md (via injectAll)
- *   AGENTS.md -> @~/.agents/AGENTS.md + @.cleo/project-context.json + @.cleo/memory-bridge.md
+ *   AGENTS.md -> @~/.agents/AGENTS.md + @.cleo/project-context.json + @.cleo/memory-bridge.md + @.cleo/nexus-bridge.md
  *
  * @task T4682
  */
@@ -114,6 +140,13 @@ export async function ensureInjection(projectRoot: string): Promise<ScaffoldResu
       actions.push('removed deprecated AGENT-INJECTION.md');
     }
 
+    // Step 0b: Strip hardcoded gitnexus blocks from AGENTS.md (T552)
+    // These are replaced by the @.cleo/nexus-bridge.md reference.
+    const removedGitNexus = await stripGitNexusBlocks(join(projectRoot, 'AGENTS.md'));
+    if (removedGitNexus) {
+      actions.push('removed hardcoded gitnexus block from AGENTS.md');
+    }
+
     // Step 1: Inject @AGENTS.md into all provider instruction files
     const injectionContent = buildInjectionContent({ references: ['@AGENTS.md'] });
     const results = await injectAll(providers, projectRoot, 'project', injectionContent);
@@ -140,6 +173,12 @@ export async function ensureInjection(projectRoot: string): Promise<ScaffoldResu
     agentsMdLines.push('@.cleo/memory-bridge.md');
   }
 
+  // Nexus bridge: auto-generated code intelligence summary (T552)
+  const nexusBridgePath = join(projectRoot, '.cleo', 'nexus-bridge.md');
+  if (existsSync(nexusBridgePath)) {
+    agentsMdLines.push('@.cleo/nexus-bridge.md');
+  }
+
   // Contributor project warning (ADR-029): inject dev-channel guidance when
   // this project IS the CLEO source repo, so agents use cleo-dev not @latest.
   const contributorBlock = buildContributorInjectionBlock(projectRoot);