@cleocode/core 2026.4.31 → 2026.4.35

package/src/memory/patterns.ts

@@ -31,6 +31,12 @@ export interface StorePatternParams {
   mitigation?: string;
   examples?: string[];
   successRate?: number;
+  /**
+   * T549 Wave 1-A: origin of this pattern.
+   * Used to route sourceConfidence at write time.
+   * Values starting with 'auto' map to 'speculative'; otherwise 'agent'.
+   */
+  source?: string;
 }
 
 /** Parameters for searching patterns. */
@@ -110,13 +116,31 @@ export async function storePattern(projectRoot: string, params: StorePatternPara
     };
   }
 
-  // Compute quality score based on type, content richness, and examples.
+  // T549 Wave 1-A: Tier routing for patterns.
+  // Patterns are medium-term procedural entries — they describe how things work.
+  // sourceConfidence routing (spec §4.1 Decision Tree):
+  //   - source starts with 'auto' → 'speculative' (auto-extracted, unconfirmed)
+  //   - otherwise → 'agent' (agent-observed during work)
+  // memoryTier = 'medium' (patterns have more than one observation and are project-scoped)
+  // memoryType = 'procedural' (patterns are always process knowledge)
+  // verified = false (patterns need validation through repetition, not boolean gate)
+  const memoryTier = 'medium' as const;
+  const memoryType = 'procedural' as const;
+  const sourceConfidence = params.source?.startsWith('auto')
+    ? ('speculative' as const)
+    : ('agent' as const);
+  const verified = false;
+
+  // Compute quality score based on type, content richness, examples,
+  // and T549 source multiplier.
   const examplesJson = params.examples ? JSON.stringify(params.examples) : '[]';
   const qualityScore = computePatternQuality({
     type: params.type,
     pattern: params.pattern.trim(),
     context: params.context.trim(),
     examples_json: examplesJson,
+    sourceConfidence,
+    memoryTier,
   });
 
   // Create new entry
@@ -133,6 +157,11 @@ export async function storePattern(projectRoot: string, params: StorePatternPara
     examplesJson,
     extractedAt: now,
     qualityScore,
+    // T549 Wave 1-A: tier/type/confidence assigned at write time
+    memoryTier,
+    memoryType,
+    sourceConfidence,
+    verified,
   };
 
   const saved = await accessor.addPattern(entry);

package/src/memory/quality-scoring.ts

@@ -7,15 +7,79 @@
  * Score formula per CA1 spec Section 3: source reliability * content richness * recency signals.
  * Each helper clamps the result to [0.0, 1.0].
  *
+ * T549 Wave 1-B: source confidence multipliers and memory tier bonuses are applied
+ * on top of the existing base formulas. The base formulas are unchanged; the
+ * multiplier and tier bonus are additive final transforms.
+ *
  * Exported for use in backfill (T530) and future scoring hooks.
  *
- * @task T531
+ * @task T531 T549
  * @epic T523
  */
 
+import type { BrainMemoryTier, BrainSourceConfidence } from '../store/brain-schema.js';
+
 /** Minimum quality score for inclusion in search results. */
 export const QUALITY_SCORE_THRESHOLD = 0.3;
 
+// ============================================================================
+// T549: Source Confidence Multipliers
+// ============================================================================
+
+/**
+ * Quality multiplier per source confidence level (T549 §3.1.5 and §5.3).
+ *
+ * Applied as a final multiplicative transform on top of the existing base score.
+ * Separate from content richness — captures trustworthiness of the source.
+ *
+ * | Level         | Meaning                                 | Multiplier |
+ * |---------------|-----------------------------------------|------------|
+ * | owner         | Owner explicitly stated this fact       | 1.0        |
+ * | task-outcome  | Verified by completed task with result  | 0.90       |
+ * | agent         | Agent-inferred during work (default)    | 0.70       |
+ * | speculative   | Agent hypothesis, not yet corroborated  | 0.40       |
+ */
+const SOURCE_MULTIPLIERS: Record<BrainSourceConfidence, number> = {
+  owner: 1.0,
+  'task-outcome': 0.9,
+  agent: 0.7,
+  speculative: 0.4,
+};
+
+/**
+ * Tier bonus applied after the source multiplier (T549 Wave 1-B).
+ *
+ * Short-term entries get no bonus (they are new and unproven).
+ * Medium-term entries get a small bonus (survived session consolidation).
+ * Long-term entries get a larger bonus (architecturally proven).
+ */
+const TIER_BONUS: Record<BrainMemoryTier, number> = {
+  short: 0.0,
+  medium: 0.05,
+  long: 0.1,
+};
+
+/**
+ * Apply the source confidence multiplier and optional memory tier bonus.
+ *
+ * This is the final transform in every compute function. It multiplies the
+ * raw content-richness score by the source multiplier, then adds the tier
+ * bonus, then clamps to [0.0, 1.0].
+ *
+ * @param rawScore - Score from the base content-richness formula
+ * @param sourceConfidence - Source reliability level (defaults to 'agent')
+ * @param memoryTier - Memory retention tier (defaults to 'short' = no bonus)
+ */
+export function applySourceMultiplier(
+  rawScore: number,
+  sourceConfidence: BrainSourceConfidence = 'agent',
+  memoryTier: BrainMemoryTier = 'short',
+): number {
+  const multiplied = rawScore * SOURCE_MULTIPLIERS[sourceConfidence];
+  const withTierBonus = multiplied + TIER_BONUS[memoryTier];
+  return clamp(withTierBonus);
+}
+
 // ============================================================================
 // Pattern quality
 // ============================================================================
@@ -26,6 +90,10 @@ export interface PatternQualityInput {
   pattern: string;
   context?: string | null;
   examples_json?: string | null;
+  /** T549: source reliability level — applies multiplier on top of base score. */
+  sourceConfidence?: BrainSourceConfidence;
+  /** T549: memory retention tier — applies tier bonus on top of multiplied score. */
+  memoryTier?: BrainMemoryTier;
 }
 
 /**
@@ -39,7 +107,8 @@ export interface PatternQualityInput {
  *   +0.10 if context exceeds 50 chars (contextual detail present)
  *   +0.10 if examples_json contains more than 3 items (empirically validated)
  *
- * Result clamped to [0.0, 1.0].
+ * T549 Wave 1-B: raw score is then multiplied by the source confidence multiplier
+ * and the memory tier bonus is added. Result clamped to [0.0, 1.0].
  */
 export function computePatternQuality(params: PatternQualityInput): number {
   let score = 0.4;
@@ -59,7 +128,7 @@ export function computePatternQuality(params: PatternQualityInput): number {
     }
   }
 
-  return clamp(score);
+  return applySourceMultiplier(score, params.sourceConfidence, params.memoryTier);
 }
 
 // ============================================================================
@@ -72,6 +141,10 @@ export interface LearningQualityInput {
   actionable?: boolean | null;
   insight: string;
   application?: string | null;
+  /** T549: source reliability level — applies multiplier on top of base score. */
+  sourceConfidence?: BrainSourceConfidence;
+  /** T549: memory retention tier — applies tier bonus on top of multiplied score. */
+  memoryTier?: BrainMemoryTier;
 }
 
 /**
@@ -83,7 +156,8 @@ export interface LearningQualityInput {
  *   +0.10 if insight text exceeds 100 chars (detailed insight)
  *   +0.10 if application exceeds 20 chars (concrete application context)
  *
- * Result clamped to [0.0, 1.0].
+ * T549 Wave 1-B: raw score is then multiplied by the source confidence multiplier
+ * and the memory tier bonus is added. Result clamped to [0.0, 1.0].
  */
 export function computeLearningQuality(params: LearningQualityInput): number {
   let score = params.confidence ?? 0.5;
@@ -92,7 +166,7 @@ export function computeLearningQuality(params: LearningQualityInput): number {
   if (params.insight.length > 100) score += 0.1;
   if (params.application && params.application.length > 20) score += 0.1;
 
-  return clamp(score);
+  return applySourceMultiplier(score, params.sourceConfidence, params.memoryTier);
 }
 
 // ============================================================================
@@ -104,6 +178,10 @@ export interface DecisionQualityInput {
   confidence: 'low' | 'medium' | 'high';
   rationale?: string | null;
   contextTaskId?: string | null;
+  /** T549: source reliability level — applies multiplier on top of base score. */
+  sourceConfidence?: BrainSourceConfidence;
+  /** T549: memory retention tier — applies tier bonus on top of multiplied score. */
+  memoryTier?: BrainMemoryTier;
 }
 
 /** Numeric value map from confidence level. */
@@ -121,7 +199,8 @@ const CONFIDENCE_SCORE_MAP: Record<'low' | 'medium' | 'high', number> = {
  *   +0.10 if rationale exceeds 50 chars (substantiated reasoning)
  *   +0.05 if linked to a specific task (anchored in real work)
  *
- * Result clamped to [0.0, 1.0].
+ * T549 Wave 1-B: raw score is then multiplied by the source confidence multiplier
+ * and the memory tier bonus is added. Result clamped to [0.0, 1.0].
  */
 export function computeDecisionQuality(params: DecisionQualityInput): number {
   let score = CONFIDENCE_SCORE_MAP[params.confidence] ?? 0.5;
@@ -129,7 +208,7 @@ export function computeDecisionQuality(params: DecisionQualityInput): number {
   if (params.rationale && params.rationale.length > 50) score += 0.1;
   if (params.contextTaskId) score += 0.05;
 
-  return clamp(score);
+  return applySourceMultiplier(score, params.sourceConfidence, params.memoryTier);
 }
 
 // ============================================================================
@@ -140,6 +219,10 @@ export function computeDecisionQuality(params: DecisionQualityInput): number {
 export interface ObservationQualityInput {
   text: string;
   title?: string | null;
+  /** T549: source reliability level — applies multiplier on top of base score. */
+  sourceConfidence?: BrainSourceConfidence;
+  /** T549: memory retention tier — applies tier bonus on top of multiplied score. */
+  memoryTier?: BrainMemoryTier;
 }
 
 /**
@@ -150,7 +233,8 @@ export interface ObservationQualityInput {
  *   +0.10 if text exceeds 200 chars (rich narrative)
  *   +0.05 if title exceeds 10 chars (meaningful label)
  *
- * Result clamped to [0.0, 1.0].
+ * T549 Wave 1-B: raw score is then multiplied by the source confidence multiplier
+ * and the memory tier bonus is added. Result clamped to [0.0, 1.0].
  */
 export function computeObservationQuality(params: ObservationQualityInput): number {
   let score = 0.6;
@@ -158,7 +242,7 @@ export function computeObservationQuality(params: ObservationQualityInput): numb
   if (params.text && params.text.length > 200) score += 0.1;
   if (params.title && params.title.length > 10) score += 0.05;
 
-  return clamp(score);
+  return applySourceMultiplier(score, params.sourceConfidence, params.memoryTier);
 }
 
 // ============================================================================

package/src/nexus/nexus-bridge.ts

@@ -0,0 +1,444 @@
+/**
+ * Nexus Bridge Generator
+ *
+ * Generates .cleo/nexus-bridge.md from nexus.db content. This file is
+ * the code intelligence equivalent of memory-bridge.md — it summarizes
+ * the codebase graph for agent consumption.
+ *
+ * Content assembly:
+ *   - Index status (file count, node count, relation count, last indexed)
+ *   - Symbol counts by kind (functions, classes, methods, etc.)
+ *   - Relation counts by type (calls, imports, extends, etc.)
+ *   - Top entry points (most outgoing CALLS edges, exported)
+ *   - Functional clusters (communities by symbol count)
+ *   - Code intelligence command reference
+ *
+ * Regeneration triggers:
+ *   - cleo nexus analyze (called after pipeline flush)
+ *   - Manual: cleo nexus refresh-bridge
+ *
+ * @task T551
+ * @epic T549
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Raw row for node kind counts. */
+interface NodeKindCountRow {
+  kind: string;
+  count: number;
+}
+
+/** Raw row for relation type counts. */
+interface RelationTypeCountRow {
+  type: string;
+  count: number;
+}
+
+/** Raw row for top entry points. */
+interface EntryPointRow {
+  name: string | null;
+  file_path: string | null;
+  callees: number;
+  is_exported: number;
+}
+
+/** Raw row for community/cluster nodes. */
+interface CommunityRow {
+  id: string;
+  label: string;
+  meta_json: string | null;
+  indexed_at: string;
+}
+
+/** Raw row for index metadata. */
+interface IndexMetaRow {
+  total_nodes: number;
+  total_relations: number;
+  file_count: number;
+  last_indexed_at: string | null;
+}
+
+// ============================================================================
+// DB helpers
+// ============================================================================
+
+/** Type-safe wrapper for DatabaseSync.prepare().all(). */
+function typedAll<T>(db: DatabaseSync, sql: string, ...params: (string | number | null)[]): T[] {
+  return db.prepare(sql).all(...params) as T[];
+}
+
+/** Type-safe wrapper for DatabaseSync.prepare().get(). */
+function typedGet<T>(
+  db: DatabaseSync,
+  sql: string,
+  ...params: (string | number | null)[]
+): T | undefined {
+  return db.prepare(sql).get(...params) as T | undefined;
+}
+
+// ============================================================================
+// Query helpers
+// ============================================================================
+
+/** Query total node/relation counts and last indexed timestamp. */
+function queryIndexMeta(db: DatabaseSync, projectId: string): IndexMetaRow {
+  try {
+    const nodeMeta = typedGet<{
+      total_nodes: number;
+      file_count: number;
+      last_indexed_at: string | null;
+    }>(
+      db,
+      `SELECT COUNT(*) as total_nodes,
+              COUNT(CASE WHEN kind = 'file' THEN 1 END) as file_count,
+              MAX(indexed_at) as last_indexed_at
+       FROM nexus_nodes
+       WHERE project_id = ?`,
+      projectId,
+    );
+
+    const relMeta = typedGet<{ total_relations: number }>(
+      db,
+      `SELECT COUNT(*) as total_relations
+       FROM nexus_relations
+       WHERE project_id = ?`,
+      projectId,
+    );
+
+    return {
+      total_nodes: nodeMeta?.total_nodes ?? 0,
+      total_relations: relMeta?.total_relations ?? 0,
+      file_count: nodeMeta?.file_count ?? 0,
+      last_indexed_at: nodeMeta?.last_indexed_at ?? null,
+    };
+  } catch {
+    return {
+      total_nodes: 0,
+      total_relations: 0,
+      file_count: 0,
+      last_indexed_at: null,
+    };
+  }
+}
+
+/** Query node counts grouped by kind. */
+function queryNodeKindCounts(db: DatabaseSync, projectId: string): NodeKindCountRow[] {
+  try {
+    return typedAll<NodeKindCountRow>(
+      db,
+      `SELECT kind, COUNT(*) as count
+       FROM nexus_nodes
+       WHERE project_id = ?
+         AND kind NOT IN ('file', 'folder', 'community', 'process')
+       GROUP BY kind
+       ORDER BY count DESC
+       LIMIT 10`,
+      projectId,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Query relation counts grouped by type. */
+function queryRelationTypeCounts(db: DatabaseSync, projectId: string): RelationTypeCountRow[] {
+  try {
+    return typedAll<RelationTypeCountRow>(
+      db,
+      `SELECT type, COUNT(*) as count
+       FROM nexus_relations
+       WHERE project_id = ?
+         AND type NOT IN ('member_of', 'step_in_process', 'entry_point_of')
+       GROUP BY type
+       ORDER BY count DESC
+       LIMIT 8`,
+      projectId,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Query top entry points by outgoing CALLS edge count. */
+function queryTopEntryPoints(db: DatabaseSync, projectId: string, limit = 5): EntryPointRow[] {
+  try {
+    return typedAll<EntryPointRow>(
+      db,
+      `SELECT n.name, n.file_path, COUNT(*) as callees, n.is_exported
+       FROM nexus_relations r
+       JOIN nexus_nodes n ON r.source_id = n.id
+       WHERE r.type = 'calls'
+         AND r.project_id = ?
+         AND n.kind IN ('function', 'method', 'constructor')
+       GROUP BY r.source_id
+       ORDER BY callees DESC
+       LIMIT ?`,
+      projectId,
+      limit,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Query community nodes ordered by member count. */
+function queryCommunities(db: DatabaseSync, projectId: string, limit = 6): CommunityRow[] {
+  try {
+    return typedAll<CommunityRow>(
+      db,
+      `SELECT id, label, meta_json, indexed_at
+       FROM nexus_nodes
+       WHERE project_id = ?
+         AND kind = 'community'
+       ORDER BY indexed_at DESC
+       LIMIT ?`,
+      projectId,
+      limit,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Query count of execution flow (process) nodes. */
+function queryProcessCount(db: DatabaseSync, projectId: string): number {
+  try {
+    const row = typedGet<{ count: number }>(
+      db,
+      `SELECT COUNT(*) as count
+       FROM nexus_nodes
+       WHERE project_id = ?
+         AND kind = 'process'`,
+      projectId,
+    );
+    return row?.count ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+// ============================================================================
+// Content generation
+// ============================================================================
+
+/**
+ * Generate nexus bridge markdown content from nexus.db.
+ * Returns the full markdown string (does not write to disk).
+ *
+ * @param projectId - Project registry ID used to scope nexus.db queries
+ * @param repoPath - Absolute path to the repository root (used for display)
+ * @returns Markdown string summarizing the code intelligence index
+ */
+export async function generateNexusBridgeContent(
+  projectId: string,
+  repoPath: string,
+): Promise<string> {
+  const { getNexusDb, getNexusNativeDb } = await import('../store/nexus-sqlite.js');
+
+  // Ensure DB is initialized
+  await getNexusDb();
+  const nativeDb = getNexusNativeDb();
+
+  if (!nativeDb) {
+    return buildEmptyBridge(repoPath);
+  }
+
+  // Check whether this project has been indexed at all
+  const meta = queryIndexMeta(nativeDb, projectId);
+  if (meta.total_nodes === 0) {
+    return buildEmptyBridge(repoPath);
+  }
+
+  const lines: string[] = [
+    '# CLEO Nexus Bridge — Code Intelligence',
+    '',
+    `> Auto-generated from nexus index. Regenerate with \`cleo nexus analyze\`.`,
+    `> Project: ${repoPath}`,
+    '',
+  ];
+
+  // --- Index Status ---
+  const kindCounts = queryNodeKindCounts(nativeDb, projectId);
+  const relCounts = queryRelationTypeCounts(nativeDb, projectId);
+  const processCount = queryProcessCount(nativeDb, projectId);
+  const communities = queryCommunities(nativeDb, projectId);
+
+  const symbolBreakdown = kindCounts.map((r) => `${r.kind}s: ${r.count}`).join(', ');
+
+  const callsCount = relCounts.find((r) => r.type === 'calls')?.count ?? 0;
+  const importsCount = relCounts.find((r) => r.type === 'imports')?.count ?? 0;
+  const extendsCount = relCounts.find((r) => r.type === 'extends')?.count ?? 0;
+
+  const freshnessLabel = meta.last_indexed_at ? meta.last_indexed_at.slice(0, 10) : 'unknown';
+
+  lines.push('## Index Status');
+  lines.push('');
+  lines.push(`- **Files**: ${meta.file_count.toLocaleString()} indexed`);
+  lines.push(
+    `- **Symbols**: ${meta.total_nodes.toLocaleString()} total${symbolBreakdown ? ` (${symbolBreakdown})` : ''}`,
+  );
+  lines.push(
+    `- **Relations**: ${meta.total_relations.toLocaleString()} total (calls: ${callsCount.toLocaleString()}, imports: ${importsCount.toLocaleString()}, extends: ${extendsCount.toLocaleString()})`,
+  );
+  lines.push(`- **Communities**: ${communities.length} functional clusters`);
+  lines.push(`- **Execution Flows**: ${processCount} traced processes`);
+  lines.push(`- **Last Indexed**: ${meta.last_indexed_at ?? 'never'}`);
+  lines.push(`- **Date**: ${freshnessLabel}`);
+  lines.push('');
+
+  // --- Top Entry Points ---
+  const entryPoints = queryTopEntryPoints(nativeDb, projectId);
+  if (entryPoints.length > 0) {
+    lines.push('## Top Entry Points');
+    lines.push('');
+    entryPoints.forEach((ep, i) => {
+      const name = ep.name ?? '(unknown)';
+      const filePath = ep.file_path ?? '';
+      const displayPath = filePath.length > 60 ? `...${filePath.slice(-57)}` : filePath;
+      lines.push(`${i + 1}. \`${name}\` — ${displayPath} (${ep.callees} callees)`);
+    });
+    lines.push('');
+  }
+
+  // --- Functional Clusters ---
+  if (communities.length > 0) {
+    lines.push('## Functional Clusters');
+    lines.push('');
+    communities.forEach((c, i) => {
+      let symbolCount = 0;
+      let topFolder = '';
+      try {
+        if (c.meta_json) {
+          const meta = JSON.parse(c.meta_json) as Record<string, unknown>;
+          symbolCount = typeof meta['symbolCount'] === 'number' ? meta['symbolCount'] : 0;
+          const folders = meta['topFolders'];
+          if (Array.isArray(folders) && folders.length > 0) {
+            topFolder = String(folders[0]);
+          }
+        }
+      } catch {
+        // ignore parse errors
+      }
+      const symbolsLabel = symbolCount > 0 ? ` (${symbolCount} symbols)` : '';
+      const folderLabel = topFolder ? ` — ${topFolder}` : '';
+      lines.push(`${i + 1}. **${c.label}**${symbolsLabel}${folderLabel}`);
+    });
+    lines.push('');
+  }
+
+  // --- Code Intelligence Commands ---
+  lines.push('## Code Intelligence Commands');
+  lines.push('');
+  lines.push('| Need | Command |');
+  lines.push('|------|---------|');
+  lines.push('| What calls this function? | `cleo nexus context <symbol>` |');
+  lines.push('| What breaks if I change this? | `cleo nexus impact <symbol>` |');
+  lines.push('| What functional areas exist? | `cleo nexus clusters` |');
+  lines.push('| What execution flows exist? | `cleo nexus flows` |');
+  lines.push('| Re-index after code changes | `cleo nexus analyze` |');
+  lines.push('| Index freshness check | `cleo nexus status` |');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Write nexus bridge content to .cleo/nexus-bridge.md.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param projectId - Project registry ID (used to scope nexus.db queries)
+ * @returns Result with path and whether the file was written
+ */
+export async function writeNexusBridge(
+  projectRoot: string,
+  projectId?: string,
+): Promise<{ path: string; written: boolean }> {
+  const cleoDir = join(projectRoot, '.cleo');
+  const bridgePath = join(cleoDir, 'nexus-bridge.md');
+
+  // Derive project ID from path if not provided (matches nexus analyze convention)
+  const resolvedProjectId =
+    projectId ?? Buffer.from(projectRoot).toString('base64url').slice(0, 32);
+
+  try {
+    const content = await generateNexusBridgeContent(resolvedProjectId, projectRoot);
+
+    if (!existsSync(cleoDir)) {
+      mkdirSync(cleoDir, { recursive: true });
+    }
+
+    // Only write if content changed (avoid unnecessary git noise)
+    if (existsSync(bridgePath)) {
+      const existing = readFileSync(bridgePath, 'utf-8');
+      // Compare without the date line since it changes daily
+      const stripDate = (s: string) => s.replace(/^> Date: .*/m, '');
+      if (stripDate(existing) === stripDate(content)) {
+        return { path: bridgePath, written: false };
+      }
+    }
+
+    writeFileSync(bridgePath, content, 'utf-8');
+    return { path: bridgePath, written: true };
+  } catch (err) {
+    console.error(
+      '[CLEO] Failed to write nexus bridge:',
+      err instanceof Error ? err.message : String(err),
+    );
+    return { path: bridgePath, written: false };
+  }
+}
+
+/**
+ * Best-effort nexus bridge refresh. Never throws.
+ * Called after cleo nexus analyze completes.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param projectId - Project registry ID (used to scope nexus.db queries)
+ */
+export async function refreshNexusBridge(projectRoot: string, projectId?: string): Promise<void> {
+  try {
+    await writeNexusBridge(projectRoot, projectId);
+  } catch (err) {
+    console.error(
+      '[CLEO] Nexus bridge refresh failed:',
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/** Build placeholder content when no index data exists. */
+function buildEmptyBridge(repoPath: string): string {
+  return [
+    '# CLEO Nexus Bridge — Code Intelligence',
+    '',
+    `> Auto-generated from nexus index. Regenerate with \`cleo nexus analyze\`.`,
+    `> Project: ${repoPath}`,
+    '',
+    '## Index Status',
+    '',
+    'Not indexed. Run `cleo nexus analyze` to build the code intelligence index.',
+    '',
+    '## Code Intelligence Commands',
+    '',
+    '| Need | Command |',
+    '|------|---------|',
+    '| Build the index | `cleo nexus analyze` |',
+    '| Check index status | `cleo nexus status` |',
+    '| What calls this function? | `cleo nexus context <symbol>` |',
+    '| What breaks if I change this? | `cleo nexus impact <symbol>` |',
+    '| What functional areas exist? | `cleo nexus clusters` |',
+    '| What execution flows exist? | `cleo nexus flows` |',
+    '',
+  ].join('\n');
+}