tenbo-dashboard 0.10.2 → 0.11.0

package/README.md

@@ -33,6 +33,10 @@ Project overview, principles, and glossary alongside per-layer narratives, inten
 
 Surfaces the things that would otherwise become tech debt nobody mentions: oversized layers (hotspots), code-map references that no longer match real files (doc drift), unreferenced files, coupling violations, dead code. Each finding carries a severity, the file it points at, and a suggested fix.
 
+Some health findings include generated graph evidence such as importers, exports,
+and layer ownership. This evidence is rebuilt from source and `.tenbo/` metadata;
+it is not separate project memory.
+
 ## CLI tools
 
 The same package ships commands the skill uses behind the scenes — also runnable directly:
@@ -46,6 +50,8 @@ npx tenbo-dashboard item link-commit sk-030 7fc09a5
 npx tenbo-dashboard items --status done --verification pending_live --json
 npx tenbo-dashboard next --json
 npx tenbo-dashboard context feature --query "help me build X" --json
+npx tenbo-dashboard impact --json     # Map git changes to affected layers/docs/items
+npx tenbo-dashboard index --json      # Rebuild the derived source index
 npx tenbo-dashboard validate          # Schema + consistency checks
 npx tenbo-dashboard init-check        # Strict completeness check after fresh init
 npx tenbo-dashboard metrics --all     # Recompute scope metrics + health findings

package/bin/tenbo-dashboard.mjs

@@ -49,6 +49,9 @@ const commands = {
   next: 'scripts/next.ts',
   'work-queue': 'scripts/work-queue.ts',
   context: 'scripts/context.ts',
+  impact: 'scripts/impact.ts',
+  index: 'scripts/index.ts',
+  reminder: 'scripts/reminder.ts',
   hook: 'scripts/hook.ts',
 };
 
@@ -97,6 +100,10 @@ ${topLevelItemHelpLines().join('\n')}
                                    [--type <type>] [--json]
   tenbo-dashboard context feature  Fetch agent planning context for a natural-language request
                                    --query "<request>" [--json]
+  tenbo-dashboard impact           Map git changes to affected layers, docs, items,
+                                   and verification checks [--since <ref>] [--json]
+  tenbo-dashboard index            Build or refresh the derived source index [--if-stale] [--json]
+  tenbo-dashboard reminder print   Print advisory session reminder text [--json]
   tenbo-dashboard validate         Run validation rules
   tenbo-dashboard init-check       Strict completeness check for fresh init (errors on missing skeletons, file_count:0, etc)
   tenbo-dashboard next-id <prefix> Allocate next roadmap item ID

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,9 @@
     "bin/",
     "src/",
     "scripts/",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!src/test-setup.ts",
     "index.html",
     "vite.config.ts",
     "tsconfig.json"
@@ -47,7 +50,7 @@
     "@dnd-kit/sortable": "^8.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@parcel/watcher": "^2.5.6",
-    "@vitejs/plugin-react": "^4.3.1",
+    "@vitejs/plugin-react": "^4.7.0",
     "@xyflow/react": "^12.10.2",
     "chokidar": "^3.6.0",
     "dagre": "^0.8.5",
@@ -59,9 +62,9 @@
     "react-markdown": "^9.0.1",
     "remark-gfm": "^4.0.0",
     "ts-morph": "^25",
-    "tsx": "^4.19.0",
+    "tsx": "^4.22.4",
     "typescript": "^5.5.4",
-    "vite": "^5.4.3",
+    "vite": "^6.4.3",
     "yaml": "^2.5.1"
   },
   "devDependencies": {

package/scripts/impact.ts

@@ -0,0 +1,25 @@
+import { resolveImpact } from '../src/api/lib/impact';
+import { hasFlag, readOption } from './cliArgs';
+import { handleCliError, isMain, misuse, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+export function runImpactCli(repoRoot: string, args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  const since = readOption(args, '--since');
+  if (args.includes('--since') && (!since || since.startsWith('--'))) {
+    return misuse('Usage: tenbo impact [--since <ref>] [--json]', json);
+  }
+  try {
+    const payload = resolveImpact(repoRoot, { since });
+    return serialize(
+      payload,
+      json,
+      `${payload.changed_files.length} changed file(s), ${payload.affected_layers.length} affected layer(s)\n`,
+    );
+  } catch (err) {
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runImpactCli(repoRootFromCwd(), process.argv.slice(2)));
+}

package/scripts/index.ts

@@ -0,0 +1,41 @@
+import { buildSourceIndex } from '../src/api/lib/sourceIndex/build';
+import { checkSourceIndexFreshness, readSourceIndex, writeSourceIndex } from '../src/api/lib/sourceIndex/store';
+import { hasFlag } from './cliArgs';
+import { handleCliError, isMain, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+export function runIndexCli(repoRoot: string, args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  const ifStale = hasFlag(args, '--if-stale');
+  try {
+    const existing = readSourceIndex(repoRoot);
+    const before = checkSourceIndexFreshness(repoRoot, existing);
+    if (ifStale && before.status === 'fresh' && existing) {
+      return serialize({
+        ok: true,
+        mode: 'reuse',
+        freshness: before,
+        files: existing.files.length,
+        layers: existing.layers.length,
+        warnings: existing.warnings,
+      }, json, `source index fresh (${existing.files.length} file(s))\n`);
+    }
+
+    const index = buildSourceIndex(repoRoot);
+    writeSourceIndex(repoRoot, index);
+    const freshness = checkSourceIndexFreshness(repoRoot, index);
+    return serialize({
+      ok: true,
+      mode: 'rebuild',
+      freshness,
+      files: index.files.length,
+      layers: index.layers.length,
+      warnings: index.warnings,
+    }, json, `source index rebuilt (${index.files.length} file(s))\n`);
+  } catch (err) {
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runIndexCli(repoRootFromCwd(), process.argv.slice(2)));
+}

package/scripts/reminder.ts

@@ -0,0 +1,24 @@
+import { hasFlag } from './cliArgs';
+import { isMain, misuse, runMain, serialize, type CliResult } from './cliResult';
+
+export function renderSessionReminder(): string {
+  return 'Tenbo context reminder (advisory, does not block): if this repo has .tenbo/, prefer `npx tenbo-dashboard context feature --query "<request>" --json` before broad source search.';
+}
+
+export function runReminderCli(args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  const command = args.find((arg) => !arg.startsWith('--'));
+  if (command !== 'print') {
+    return misuse('Usage: tenbo reminder print [--json]', json);
+  }
+  const payload = {
+    ok: true,
+    mode: 'print',
+    reminder: renderSessionReminder(),
+  };
+  return serialize(payload, json, `${payload.reminder}\n`);
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runReminderCli(process.argv.slice(2)));
+}

package/scripts/sync.ts

@@ -14,6 +14,8 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { findRepoRoot } from '../src/api/lib/repoRoot';
 import { runComputeMetrics } from './compute-metrics';
 import { runInitCheck } from './init-check';
@@ -47,6 +49,58 @@ interface SyncArgs {
   scope?: string; // single-scope refresh; omit to refresh all
 }
 
+export interface IndexRefreshResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+const DEFAULT_INDEX_BUDGET_MS = 3000;
+
+function dashboardBinPath(): string {
+  const here = new URL(import.meta.url);
+  if (here.protocol === 'file:') return fileURLToPath(new URL('../bin/tenbo-dashboard.mjs', here));
+  return path.resolve(process.cwd(), 'bin/tenbo-dashboard.mjs');
+}
+
+type SpawnSyncFn = typeof spawnSync;
+
+export function runIndexRefreshForSync(
+  repoRoot: string,
+  budgetMs = DEFAULT_INDEX_BUDGET_MS,
+  spawn: SpawnSyncFn = spawnSync,
+): IndexRefreshResult {
+  const binPath = dashboardBinPath();
+  const child = spawn(process.execPath, [binPath, 'index', '--if-stale', '--json'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    timeout: budgetMs,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+
+  if (child.error) {
+    const code = (child.error as NodeJS.ErrnoException).code;
+    if (code === 'ETIMEDOUT') {
+      return {
+        exitCode: 0,
+        stdout: child.stdout ?? '',
+        stderr: `sync: source index refresh timed out after ${budgetMs}ms; continuing without fresh index\n`,
+      };
+    }
+    return {
+      exitCode: 1,
+      stdout: child.stdout ?? '',
+      stderr: child.stderr || `${child.error.message}\n`,
+    };
+  }
+
+  return {
+    exitCode: child.status ?? (child.signal ? 1 : 0),
+    stdout: child.stdout ?? '',
+    stderr: child.stderr ?? '',
+  };
+}
+
 export async function runSync(args: SyncArgs): Promise<number> {
   const { repoRoot, scope } = args;
 
@@ -59,7 +113,14 @@ export async function runSync(args: SyncArgs): Promise<number> {
     for (const f of m?.findings ?? []) priorFindingKeys.add(findingKey(id, f));
   }
 
-  // 1. metrics
+  // 1. source index (fail-open; metrics can still refresh without graph findings)
+  const indexResult = runIndexRefreshForSync(repoRoot);
+  if (indexResult.stderr) process.stderr.write(indexResult.stderr);
+  if (indexResult.exitCode !== 0) {
+    process.stderr.write('sync: source index refresh failed-open; continuing without fresh index\n');
+  }
+
+  // 2. metrics
   const metricsCode = await runComputeMetrics({
     repoRoot,
     all: !scope,
@@ -70,7 +131,7 @@ export async function runSync(args: SyncArgs): Promise<number> {
     return 1;
   }
 
-  // 2. init-check
+  // 3. init-check
   const { defects } = runInitCheck(repoRoot);
   if (defects.length > 0) {
     process.stderr.write(`sync: init-check FAILED — ${defects.length} init defect(s):\n`);
@@ -81,7 +142,7 @@ export async function runSync(args: SyncArgs): Promise<number> {
     return 1;
   }
 
-  // 3. validate (re-read state after metrics may have changed scope dirs)
+  // 4. validate (re-read state after metrics may have changed scope dirs)
   const stateAfter = readState(repoRoot);
   const result = validate(stateAfter);
   if (result.errors.length > 0) {
@@ -90,7 +151,7 @@ export async function runSync(args: SyncArgs): Promise<number> {
     return 1;
   }
 
-  // 4. Diff findings: surface NEW critical/warning findings introduced this run.
+  // 5. Diff findings: surface NEW critical/warning findings introduced this run.
   const newFindings: NewFinding[] = [];
   for (const id of targetScopes) {
     const m = readMetrics(path.join(repoRoot, '.tenbo', 'scopes', id, 'metrics.json'));
@@ -107,7 +168,7 @@ export async function runSync(args: SyncArgs): Promise<number> {
     }
   }
 
-  // 5. Summary line + (optional) new-finding lines.
+  // 6. Summary line + (optional) new-finding lines.
   const scopeLabel = scope ? `scope "${scope}"` : `${targetScopes.length} scope(s)`;
   if (newFindings.length === 0) {
     process.stdout.write(`sync: ${scopeLabel} fresh. No new errors, no new warning/critical findings.\n`);

package/src/api/lib/contextResolver.ts

@@ -2,13 +2,21 @@ import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { readLayerContent, readState } from './tenboFs';
 import { comparePriority } from './priority';
+import { checkSourceIndexFreshness, readSourceIndex } from './sourceIndex/store';
+import { querySourceIndex, type SourceEvidenceFile } from './sourceIndex/query';
 import type { Item, Layer, Scope, Status } from '../../types';
 
 export type ContextIntent = 'session' | 'feature' | 'item';
 export type ContextConfidence = 'high' | 'medium' | 'low';
 
 export interface ContextWarning {
-  kind: 'missing_agent_context' | 'stale_agent_context';
+  kind:
+    | 'missing_agent_context'
+    | 'stale_agent_context'
+    | 'missing_source_index'
+    | 'stale_source_index'
+    | 'corrupt_source_index'
+    | 'incompatible_source_index';
   message: string;
   path: string;
   age_days?: number;
@@ -36,6 +44,27 @@ export interface ContextItemEntry {
   score: number;
 }
 
+export type ContextReadPlanKind =
+  | 'product'
+  | 'layer-intent'
+  | 'layer-code-map'
+  | 'roadmap-item'
+  | 'source-file'
+  | 'spec';
+
+export interface ContextReadPlanEntry {
+  path: string;
+  kind: ContextReadPlanKind;
+  reason: string;
+  priority: number;
+}
+
+export interface ContextVerificationEntry {
+  command: string;
+  purpose: string;
+  when: string;
+}
+
 export interface ContextLayerEntry {
   scope: string;
   id: string;
@@ -76,6 +105,8 @@ export interface FeatureContextBundle {
   context: {
     layer_docs: string[];
     files_to_read: string[];
+    read_plan: ContextReadPlanEntry[];
+    verification_plan: ContextVerificationEntry[];
   };
   warnings: ContextWarning[];
 }
@@ -285,6 +316,83 @@ function unique<T>(values: T[]): T[] {
   return Array.from(new Set(values));
 }
 
+function pushReadPlan(
+  entries: ContextReadPlanEntry[],
+  seen: Set<string>,
+  entry: ContextReadPlanEntry,
+) {
+  if (seen.has(entry.path)) return;
+  seen.add(entry.path);
+  entries.push(entry);
+}
+
+function buildReadPlan(args: {
+  layerDocs: string[];
+  activeItems: ScoredItemEntry[];
+  matchingItems: ScoredItemEntry[];
+  sourceEvidence: SourceEvidenceFile[];
+  filesToRead: string[];
+}): ContextReadPlanEntry[] {
+  const entries: ContextReadPlanEntry[] = [];
+  const seen = new Set<string>();
+  pushReadPlan(entries, seen, {
+    path: '.tenbo/overview.md',
+    kind: 'product',
+    reason: 'Product goals and non-goals frame the request',
+    priority: 1,
+  });
+  for (const doc of args.layerDocs) {
+    pushReadPlan(entries, seen, {
+      path: doc,
+      kind: doc.endsWith('/intent.md') ? 'layer-intent' : 'layer-code-map',
+      reason: 'Selected layer context for the request',
+      priority: entries.length + 1,
+    });
+  }
+  for (const source of args.sourceEvidence) {
+    pushReadPlan(entries, seen, {
+      path: source.path,
+      kind: 'source-file',
+      reason: source.reason,
+      priority: entries.length + 1,
+    });
+  }
+  for (const entry of [...args.activeItems, ...args.matchingItems]) {
+    for (const link of entry.item.links ?? []) {
+      pushReadPlan(entries, seen, {
+        path: link,
+        kind: 'spec',
+        reason: `Linked plan/spec for ${entry.item.id}`,
+        priority: entries.length + 1,
+      });
+    }
+  }
+  for (const file of args.filesToRead) {
+    pushReadPlan(entries, seen, {
+      path: file,
+      kind: file.startsWith('.tenbo/') ? 'roadmap-item' : 'source-file',
+      reason: 'Referenced by active or matching roadmap context',
+      priority: entries.length + 1,
+    });
+  }
+  return entries.slice(0, 12).map((entry, index) => ({ ...entry, priority: index + 1 }));
+}
+
+function buildVerificationPlan(): ContextVerificationEntry[] {
+  return [
+    {
+      command: 'node tenbo-dashboard/bin/tenbo-dashboard.mjs validate --json',
+      purpose: 'Check Tenbo roadmap and documentation structure',
+      when: 'after changing .tenbo files',
+    },
+    {
+      command: 'cd tenbo-dashboard && npm test -- --run',
+      purpose: 'Run dashboard and CLI unit tests',
+      when: 'after changing dashboard code',
+    },
+  ];
+}
+
 function confidenceForScore(score: number): ContextConfidence {
   if (score >= 3) return 'high';
   if (score >= 2) return 'medium';
@@ -308,6 +416,24 @@ function scopeCandidates(scopes: Scope[], scoredLayers: ScoredLayer[], matchingI
   }).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
 }
 
+function withSourceScopeScores(candidates: ContextScopeEntry[], sourceScores: Map<string, number>): ContextScopeEntry[] {
+  return candidates
+    .map((candidate) => ({
+      ...candidate,
+      score: candidate.score + (sourceScores.get(candidate.id) ?? 0),
+    }))
+    .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}
+
+function withSourceLayerScores(scoredLayers: ScoredLayer[], sourceScores: Map<string, number>): ScoredLayer[] {
+  return scoredLayers
+    .map((entry) => ({
+      ...entry,
+      score: entry.score + (sourceScores.get(`${entry.scope.id}:${entry.layer.id}`) ?? 0),
+    }))
+    .sort((a, b) => b.score - a.score || a.scope.id.localeCompare(b.scope.id) || a.layer.id.localeCompare(b.layer.id));
+}
+
 function roadmapEntriesForScope(scope: Scope, statuses: readonly Status[]): ScoredItemEntry[] {
   return scope.items
     .filter((item) => statuses.includes(item.status))
@@ -333,24 +459,55 @@ function agentContextWarnings(repoRoot: string, now: Date): ContextWarning[] {
   return [];
 }
 
+function sourceIndexWarning(freshness: ReturnType<typeof checkSourceIndexFreshness>): ContextWarning | null {
+  if (freshness.status === 'fresh') return null;
+  const kindByStatus: Record<string, ContextWarning['kind']> = {
+    missing: 'missing_source_index',
+    stale: 'stale_source_index',
+    corrupt: 'corrupt_source_index',
+    incompatible: 'incompatible_source_index',
+  };
+  const kind = kindByStatus[freshness.status];
+  if (!kind) return null;
+  return {
+    kind,
+    path: '.tenbo/cache/source-index.json',
+    message: freshness.message,
+  };
+}
+
 export function resolveFeatureContext(repoRoot: string, query: string, opts: ResolveOptions = {}): FeatureContextBundle {
   const now = opts.now ?? new Date();
   const state = readState(repoRoot);
   const queryTokens = tokenize(query);
   const goals = parseGoals(state.workspaceContent.overviewMd);
   const nonGoals = parseNonGoals(state.workspaceContent.overviewMd);
+  const sourceIndex = readSourceIndex(repoRoot);
+  const sourceFreshness = checkSourceIndexFreshness(repoRoot, sourceIndex);
+  const sourceQuery = sourceFreshness.status === 'fresh' && sourceIndex
+    ? querySourceIndex(sourceIndex, query)
+    : null;
   const matchingItems = scoreItems(queryTokens, state.scopes);
-  const scoredLayers = scoreLayers(repoRoot, queryTokens, state.scopes, matchingItems);
-  const candidates = scopeCandidates(state.scopes, scoredLayers, matchingItems);
-  const topLayer = scoredLayers[0];
-  const confidence = confidenceForScore(topLayer?.score ?? 0);
+  const scoredLayers = withSourceLayerScores(
+    scoreLayers(repoRoot, queryTokens, state.scopes, matchingItems),
+    sourceQuery?.layerScores ?? new Map(),
+  );
+  const candidates = withSourceScopeScores(
+    scopeCandidates(state.scopes, scoredLayers, matchingItems),
+    sourceQuery?.scopeScores ?? new Map(),
+  );
+  const topScope = candidates[0];
+  const confidence = confidenceForScore(topScope?.score ?? 0);
   const selectedScope = confidence === 'low'
     ? null
-    : state.scopes.find((scope) => scope.id === topLayer.scope.id) ?? null;
+    : state.scopes.find((scope) => scope.id === topScope.id) ?? null;
+  const scopedLayers = selectedScope
+    ? scoredLayers.filter((entry) => entry.scope.id === selectedScope.id && entry.score > 0)
+    : [];
+  const topLayer = scopedLayers[0];
   const selectedLayers = selectedScope
-    ? scoredLayers
-      .filter((entry) => entry.scope.id === selectedScope.id && entry.score > 0)
-      .filter((entry) => entry.score === topLayer.score)
+    ? scopedLayers
+      .filter((entry) => entry.score === topLayer?.score)
       .slice(0, 3)
       .map((entry) => entry.layer.id)
     : [];
@@ -380,6 +537,17 @@ export function resolveFeatureContext(repoRoot: string, query: string, opts: Res
     ...activeItems.flatMap((entry) => entry.item.files_to_read ?? []),
     ...matchingItems.flatMap((entry) => entry.item.files_to_read ?? []),
   ]);
+  const sourceEvidence = (sourceQuery?.files ?? [])
+    .filter((entry) => !selectedScope || entry.scope === selectedScope.id)
+    .filter((entry) => selectedLayers.length === 0 || entry.layers.some((layer) => selectedLayers.includes(layer)));
+  const readPlan = buildReadPlan({
+    layerDocs,
+    activeItems,
+    matchingItems,
+    sourceEvidence,
+    filesToRead,
+  });
+  const sourceWarning = sourceIndexWarning(sourceFreshness);
 
   return {
     ok: true,
@@ -409,7 +577,12 @@ export function resolveFeatureContext(repoRoot: string, query: string, opts: Res
     context: {
       layer_docs: layerDocs,
       files_to_read: filesToRead,
+      read_plan: readPlan,
+      verification_plan: buildVerificationPlan(),
     },
-    warnings: agentContextWarnings(repoRoot, now),
+    warnings: [
+      ...agentContextWarnings(repoRoot, now),
+      ...(sourceWarning ? [sourceWarning] : []),
+    ],
   };
 }

package/src/api/lib/health/collectAll.ts

@@ -1,20 +1,20 @@
 import type { Item, Scope } from '../../../types';
 import type { Finding, Signal } from './types';
 import type { HealthConfig } from './config';
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import path from 'node:path';
 import { resolveLayerFiles } from './layerFiles';
 import { analyzeHotspotFiles } from './hotspotFiles';
 import { analyzeAgingTodos } from './agingTodos';
 import { analyzeDocDrift } from './docDrift';
 import { analyzeTestCoverage } from './testCoverage';
 import { analyzeArchCompliance } from './archCompliance';
-import { buildImportGraph } from './importGraph';
+import { graphFromSourceIndex } from './structuralGraph';
 import type { ImportGraph } from './importGraph';
 import { analyzeDeadCode } from './deadCode';
 import { analyzeCoupling } from './coupling';
 import { analyzeRedundancy } from './redundancy';
 import { analyzeAgingSuperseded } from './agingSuperseded';
+import { checkSourceIndexFreshness, readSourceIndex } from '../sourceIndex/store';
+import type { GraphEvidence } from './types';
 
 interface AnalyzerArgs {
   repoRoot: string;
@@ -39,58 +39,15 @@ const ANALYZERS: Record<Signal, AnalyzerFn | null> = {
   'redundancy':               null, // Phase 4
 };
 
-const SOURCE_EXT_RE = /\.tsx?$/;
-const IGNORED_SOURCE_DIRS = new Set([
-  '.git',
-  '.tenbo',
-  'node_modules',
-  'dist',
-  'build',
-  'coverage',
-  '.next',
-  '.turbo',
-  'out',
-]);
-
-function collectScopeSourceFiles(repoRoot: string, scopePath: string, seedFiles: string[]): string[] {
-  const sourceFiles = new Set(seedFiles.filter(f => SOURCE_EXT_RE.test(f)));
-  const root = path.resolve(repoRoot, scopePath || '.');
-  if (!existsSync(root)) return Array.from(sourceFiles).sort();
-
-  function walk(dir: string) {
-    let entries: string[];
-    try { entries = readdirSync(dir); } catch { return; }
-    for (const entry of entries.sort()) {
-      if (IGNORED_SOURCE_DIRS.has(entry)) continue;
-      const full = path.join(dir, entry);
-      let st;
-      try { st = statSync(full); } catch { continue; }
-      if (st.isDirectory()) {
-        walk(full);
-      } else if (SOURCE_EXT_RE.test(entry) && !entry.endsWith('.d.ts')) {
-        sourceFiles.add(path.relative(repoRoot, full).split(path.sep).join('/'));
-      }
-    }
-  }
-  walk(root);
-  return Array.from(sourceFiles).sort();
-}
-
-function tsConfigForScope(repoRoot: string, scopePath: string): string | undefined {
-  const scoped = path.join(repoRoot, scopePath || '.', 'tsconfig.json');
-  if (existsSync(scoped)) return scoped;
-  const root = path.join(repoRoot, 'tsconfig.json');
-  return existsSync(root) ? root : undefined;
-}
-
 export async function collectAll(repoRoot: string, scope: Scope, config: HealthConfig, allItems?: Map<string, Item>): Promise<Finding[]> {
   const filesByLayer = resolveLayerFiles(repoRoot, scope);
-  const allTsFiles = collectScopeSourceFiles(repoRoot, scope.path, Object.values(filesByLayer).flat());
   let graph: ImportGraph | undefined;
-  try {
-    graph = buildImportGraph(repoRoot, allTsFiles, { tsConfigFilePath: tsConfigForScope(repoRoot, scope.path) });
-  } catch {
-    // No tsconfig or build error — skip import-graph dependent analyzers
+  let graphEvidence: GraphEvidence | undefined;
+  const sourceIndex = readSourceIndex(repoRoot);
+  const indexFreshness = checkSourceIndexFreshness(repoRoot, sourceIndex);
+  if (indexFreshness.status === 'fresh' && sourceIndex) {
+    graph = graphFromSourceIndex(sourceIndex, scope.id);
+    graphEvidence = { mode: 'fresh-index', index_status: indexFreshness.status };
   }
   const out: Finding[] = [];
   for (const layer of scope.layers) {
@@ -100,7 +57,8 @@ export async function collectAll(repoRoot: string, scope: Scope, config: HealthC
       if (!fn) continue;
       if (opted.has(signal)) continue;
       try {
-        out.push(...fn({ repoRoot, scopeId: scope.id, scopePath: scope.path, layerId: layer.id, files, config, graph }));
+        const findings = fn({ repoRoot, scopeId: scope.id, scopePath: scope.path, layerId: layer.id, files, config, graph });
+        out.push(...decorateGraphEvidence(findings, graphEvidence));
       } catch (e) {
         // Analyzer failures don't break the whole report. Log and continue.
         console.error(`[health] analyzer ${signal} failed for layer ${layer.id}:`, e);
@@ -112,7 +70,7 @@ export async function collectAll(repoRoot: string, scope: Scope, config: HealthC
     try {
       const couplingFindings = analyzeCoupling(filesByLayer, graph)
         .filter(f => !(config.ignore.layer_signals[f.layer] ?? []).includes('coupling'));
-      out.push(...couplingFindings);
+      out.push(...decorateGraphEvidence(couplingFindings, graphEvidence));
     } catch (e) {
       console.error('[health] analyzer coupling failed:', e);
     }
@@ -135,3 +93,17 @@ export async function collectAll(repoRoot: string, scope: Scope, config: HealthC
 
   return out;
 }
+
+function decorateGraphEvidence(findings: Finding[], evidence: GraphEvidence | undefined): Finding[] {
+  if (!evidence) return findings;
+  return findings.map((finding) => {
+    if (finding.signal !== 'dead-code' && finding.signal !== 'coupling') return finding;
+    return {
+      ...finding,
+      details: {
+        ...finding.details,
+        graph_evidence: evidence,
+      },
+    } as Finding;
+  });
+}