@tyroneross/navgator 0.2.2 → 0.9.0

package/dist/scanner.js

@@ -2,18 +2,291 @@
  * NavGator Main Scanner
  * Orchestrates all component and connection scanners
  */
+import * as fs from 'fs';
+import * as path from 'path';
 import { glob } from 'glob';
+const DEFAULT_IGNORE_PATTERNS = [
+    '**/node_modules/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/.next/**',
+    '**/__pycache__/**',
+    '**/venv/**',
+    '**/.venv/**',
+    '**/.git/**',
+    '**/.build/**',
+    '**/DerivedData/**',
+    '**/.swiftpm/**',
+    '**/Pods/**',
+    '**/coverage/**',
+    // Saved-webpage asset directories (Mediasite/Confluence/MHTML exports etc.)
+    // contain inert JS that has no runtime role in the project.
+    '**/*_files/**',
+];
+function getIgnorePatterns(root) {
+    const userFile = path.join(root, '.navgatorignore');
+    if (!fs.existsSync(userFile))
+        return DEFAULT_IGNORE_PATTERNS;
+    try {
+        const userPatterns = fs.readFileSync(userFile, 'utf-8')
+            .split('\n')
+            .map(line => line.trim())
+            .filter(line => line && !line.startsWith('#'));
+        return [...DEFAULT_IGNORE_PATTERNS, ...userPatterns];
+    }
+    catch {
+        return DEFAULT_IGNORE_PATTERNS;
+    }
+}
+import { getGitInfo } from './git.js';
+import { enrichFromCache } from './enrich/external-resolver.js';
+import { loadCache, makeLookup } from './enrich/cache.js';
 import { scanNpmPackages, detectNpm } from './scanners/packages/npm.js';
 import { scanPipPackages, detectPip } from './scanners/packages/pip.js';
 import { scanSpmPackages, detectSpm } from './scanners/packages/swift.js';
 import { scanInfrastructure } from './scanners/infrastructure/index.js';
+import { scanPrismaSchema, detectPrisma } from './scanners/infrastructure/prisma-scanner.js';
+import { scanEnvVars, detectEnvFiles } from './scanners/infrastructure/env-scanner.js';
+import { scanQueues, detectQueues } from './scanners/infrastructure/queue-scanner.js';
+import { scanCronJobs, detectCrons } from './scanners/infrastructure/cron-scanner.js';
+import { scanDeployConfig } from './scanners/infrastructure/deploy-scanner.js';
+import { scanPrismaCalls } from './scanners/connections/prisma-calls.js';
+import { scanFieldUsage, canAnalyzeFieldUsage } from './scanners/infrastructure/field-usage-analyzer.js';
+import { scanTypeSpecValidation, canValidateTypeSpec } from './scanners/infrastructure/typespec-validator.js';
 import { scanServiceCalls } from './scanners/connections/service-calls.js';
 import { scanWithAST, scanDatabaseOperations } from './scanners/connections/ast-scanner.js';
 import { scanPrompts, convertToArchitecture, formatPromptsOutput } from './scanners/prompts/index.js';
 import { traceLLMCalls } from './scanners/connections/llm-call-tracer.js';
 import { scanSwiftCode } from './scanners/swift/code-scanner.js';
-import { storeComponents, storeConnections, buildIndex, buildGraph, buildFileMap, buildSummary, savePromptScan, clearStorage, createSnapshot, computeFileHashes, saveHashes, detectFileChanges, formatFileChangeSummary, } from './storage.js';
-import { getConfig, ensureStorageDirectories } from './config.js';
+import { scanImports } from './scanners/connections/import-scanner.js';
+import { storeComponents, storeConnections, migratePerEntityFiles, buildIndex, buildGraph, buildFileMap, buildSummary, savePromptScan, clearStorage, clearForFiles, loadIndex, loadAllComponents, loadAllConnections, loadReverseDeps, runIntegrityCheck, mergeByStableId, atomicWriteJSON, ensureStableIdPublic, buildReverseDepsIndex, buildDerivedManifest, createSnapshot, computeFileHashes, saveHashes, detectFileChanges, formatFileChangeSummary, } from './storage.js';
+import { getConfig, ensureStorageDirectories, getIndexPath, getStoragePath, SCHEMA_VERSION, getComponentsPath, getConnectionsPath } from './config.js';
+import { acquireLock } from './scan-lock.js';
+import { computeArchitectureDiff, classifySignificance, loadLatestSnapshot, buildCurrentSnapshot, saveTimelineEntry, generateTimelineId, } from './diff.js';
+import { registerProject } from './projects.js';
+import { runAudit, updateEwmaForAudit } from './audit/index.js';
+/**
+ * Strip internal scratch fields (prefixed with `__`) before persisting
+ * an AuditReport on a TimelineEntry.
+ */
+function stripInternals(report) {
+    const { ...clean } = report;
+    for (const k of Object.keys(clean)) {
+        if (k.startsWith('__')) {
+            delete clean[k];
+        }
+    }
+    return clean;
+}
+import { classifyAllConnections } from './classify.js';
+import { isSandboxMode } from './sandbox.js';
+import { ensureSafeGitignore } from './gitignore-safety.js';
+// =============================================================================
+// MULTI-STACK ROOT DISCOVERY
+// =============================================================================
+/**
+ * Manifest filenames that mark a directory as the root of a discrete stack.
+ * Order matters: when we walk one level deep we stop at the first match per
+ * subdir, so place the language-canonical manifests first.
+ */
+const STACK_MANIFESTS = [
+    'package.json',
+    'pyproject.toml',
+    'Cargo.toml',
+    'go.mod',
+    'pom.xml',
+    'Gemfile',
+    // Catch-all for .NET — we glob the subdir for `*.csproj` separately
+    // because there's no fixed filename. Handled via discoverStackRoots.
+];
+/**
+ * Walk one level under `root`, return roots to scan. Behavior:
+ *
+ *  - If `root` has any stack manifest, return `[{ path: root, origin: '.' }]`.
+ *    No further walking — single-stack repos behave exactly as before.
+ *  - Else, look at every direct child directory (depth 1). Any child that
+ *    carries a stack manifest is included.
+ *  - When more than one child stack is found, all of them are scanned and
+ *    components get an `origin_root` metadata tag so consumers can group.
+ *
+ * Skips dotfiles, `node_modules`, `dist`, `build`, `__pycache__`, `.venv`,
+ * and anything starting with `.` to avoid scanning vendored or generated dirs.
+ */
+export function discoverStackRoots(root, verbose) {
+    // Uses the module-level `fs`/`path` namespace imports at the top of
+    // the file. ESM-only — no `require()` here.
+    const hasManifest = (dir) => {
+        for (const m of STACK_MANIFESTS) {
+            if (fs.existsSync(path.join(dir, m)))
+                return true;
+        }
+        // .NET — any *.csproj
+        try {
+            const entries = fs.readdirSync(dir);
+            if (entries.some(e => e.endsWith('.csproj')))
+                return true;
+        }
+        catch {
+            // unreadable dir → not a stack root
+        }
+        return false;
+    };
+    if (hasManifest(root)) {
+        return [{ path: root, origin: '.' }];
+    }
+    const skipDirs = new Set([
+        'node_modules', 'dist', 'build', '.git', '.next', '.cache',
+        '__pycache__', '.venv', 'venv', '.tox', 'target', 'vendor',
+        'coverage', '.pytest_cache', '.navgator', '.ibr', '.bookmark',
+        '.claude',
+    ]);
+    let entries;
+    try {
+        entries = fs.readdirSync(root);
+    }
+    catch {
+        return [{ path: root, origin: '.' }];
+    }
+    const found = [];
+    for (const name of entries) {
+        if (name.startsWith('.'))
+            continue;
+        if (skipDirs.has(name))
+            continue;
+        const child = path.join(root, name);
+        let isDir = false;
+        try {
+            isDir = fs.statSync(child).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDir)
+            continue;
+        if (hasManifest(child)) {
+            found.push({ path: child, origin: name });
+        }
+    }
+    if (found.length === 0) {
+        // Nothing one level down either — keep legacy behavior so older
+        // projects don't silently turn into no-ops.
+        if (verbose) {
+            console.log('  - No stack manifest at root or any direct child; scanning root anyway');
+        }
+        return [{ path: root, origin: '.' }];
+    }
+    if (verbose) {
+        console.log(`  - Multi-stack project: ${found.length} subroot(s): ` +
+            found.map(f => f.origin).join(', '));
+    }
+    return found;
+}
+// =============================================================================
+// MODE SELECTION (Run 1 — D2)
+// =============================================================================
+/**
+ * Files whose presence in fileChanges forces a full scan because they alter
+ * the package/dependency graph in ways that ripple through every component.
+ */
+const FULL_SCAN_TRIGGER_FILES = new Set([
+    // Lockfiles / manifests — change the package graph
+    'package.json',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'pyproject.toml',
+    'requirements.txt',
+    'requirements-dev.txt',
+    'requirements-test.txt',
+    'prisma/schema.prisma',
+    'Package.swift',
+    'Package.resolved',
+    // Build / runtime config — change resolution, deploy targets, ignore rules
+    'tsconfig.json',
+    'vercel.json',
+    'fly.toml',
+    'railway.json',
+    '.gitignore',
+]);
+/** Days × ms in one day — used by stale-full check. */
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+/** Cap on consecutive incremental scans before forcing a full scan. */
+const INCREMENTAL_CAP = 20;
+/**
+ * Decide whether to run a full or incremental scan based on the requested
+ * mode, the prior index state, and the file changes since last scan.
+ *
+ * Pure function — no I/O. All inputs precomputed by the caller.
+ *
+ * Policy (for mode='auto'):
+ * 1. No prior index → full / no-prior-state
+ * 2. schema_version mismatch (and not 1.0.0 → 1.1.0 soft-upgrade) → full / schema-mismatch
+ * 3. Any FULL_SCAN_TRIGGER_FILES in changedFiles → full / manifest-changed
+ * 4. now − last_full_scan > 7 days → full / stale-full
+ * 5. incrementals_since_full ≥ 20 → full / incremental-cap
+ * 6. No file changes at all → noop case (caller handles); we still return
+ *    'incremental' here for the no-op flow.
+ * 7. Else → incremental / fast-path
+ */
+export function selectScanMode(fileChanges, index, options, now = Date.now()) {
+    const mode = options.mode ?? (options.clearFirst ? 'full' : options.incremental ? 'incremental' : 'auto');
+    if (mode === 'full') {
+        return { mode: 'full', reason: 'flag-full' };
+    }
+    if (mode === 'incremental') {
+        if (!index) {
+            return { mode: 'full', reason: 'no-prior-state' };
+        }
+        return { mode: 'incremental', reason: 'flag-incremental' };
+    }
+    // mode === 'auto'
+    if (!index) {
+        return { mode: 'full', reason: 'no-prior-state' };
+    }
+    // 1.0.0 → 1.1.0 is a soft upgrade (loadIndex injected defaults).
+    // Any other mismatch demands a full rebuild.
+    const sv = index.schema_version ?? '1.0.0';
+    if (sv !== '1.0.0' && sv !== SCHEMA_VERSION) {
+        return { mode: 'full', reason: 'schema-mismatch' };
+    }
+    // Run 2 — D5: prior scan's audit detected EWMA drift breach.
+    // Force a full + Cochran audit pass on this run.
+    if (index.pending_drift_breach) {
+        return { mode: 'full', reason: 'audit-drift-breach' };
+    }
+    const changed = new Set();
+    if (fileChanges) {
+        for (const f of fileChanges.added)
+            changed.add(f);
+        for (const f of fileChanges.modified)
+            changed.add(f);
+        for (const f of fileChanges.removed)
+            changed.add(f);
+    }
+    for (const trigger of FULL_SCAN_TRIGGER_FILES) {
+        if (changed.has(trigger)) {
+            return { mode: 'full', reason: 'manifest-changed' };
+        }
+    }
+    // New files have no recorded reverse-dep edges yet, so an incremental walk-set
+    // can't find their importers. Cleaner to force a full scan than gymnastics
+    // (Run 1.6 — item #5).
+    if (fileChanges && fileChanges.added.length > 0) {
+        return { mode: 'full', reason: 'new-files' };
+    }
+    const lastFull = index.last_full_scan ?? 0;
+    if (lastFull > 0 && now - lastFull > SEVEN_DAYS_MS) {
+        return { mode: 'full', reason: 'stale-full' };
+    }
+    const incCount = index.incrementals_since_full ?? 0;
+    if (incCount >= INCREMENTAL_CAP) {
+        return { mode: 'full', reason: 'incremental-cap' };
+    }
+    if (changed.size === 0) {
+        return { mode: 'incremental', reason: 'no-changes' };
+    }
+    return { mode: 'incremental', reason: 'fast-path' };
+}
 // =============================================================================
 // MAIN SCANNER
 // =============================================================================
@@ -24,25 +297,105 @@ export async function scan(projectRoot, options = {}) {
     const startTime = Date.now();
     const root = projectRoot || process.cwd();
     const config = getConfig();
+    // R6 footprint fix: CLI/programmatic option overrides config flag.
+    if (options.perEntityFiles !== undefined) {
+        config.perEntityFiles = options.perEntityFiles;
+    }
+    // Sandbox mode: restrict scan behavior
+    if (isSandboxMode()) {
+        options.quick = true;
+        options.prompts = false;
+        options.useAST = false;
+    }
+    // Opt-in branch tracking
+    let gitInfo;
+    if (options.trackBranch) {
+        const info = await getGitInfo(root);
+        if (info) {
+            gitInfo = info;
+            if (options.verbose) {
+                console.log(`Branch tracking: ${info.branch} @ ${info.commit}`);
+            }
+        }
+    }
     if (options.verbose) {
         console.log(`Scanning project: ${root}`);
     }
-    // Clear existing data if requested
-    if (options.clearFirst) {
-        await clearStorage(config, root);
-    }
-    // Ensure storage directories exist
+    // Ensure storage directories exist BEFORE we look at any prior state.
     ensureStorageDirectories(config, root);
     // ==========================================================================
-    // Phase 0: File Discovery & Change Detection
+    // Phase 0.0: Concurrency lock (Run 1.6 — item #4)
     // ==========================================================================
-    const sourceFiles = await glob('**/*.{ts,tsx,js,jsx,py,swift,h,m}', {
-        cwd: root,
-        ignore: ['node_modules/**', 'dist/**', 'build/**', '.next/**', '__pycache__/**', 'venv/**', '.git/**', '.build/**', 'DerivedData/**', '.swiftpm/**', 'Pods/**'],
-    });
-    let fileChanges;
-    if (!options.clearFirst) {
-        fileChanges = await detectFileChanges(sourceFiles, root, config);
+    // Prevent two `navgator scan` processes corrupting each other's
+    // .navgator/architecture/ output. Stale locks (>10 min OR pid gone)
+    // auto-clear. Live contention exits cleanly with code 0.
+    const storeDir = getStoragePath(config, root);
+    const requestedScanType = options.mode ?? (options.clearFirst ? 'full' : options.incremental ? 'incremental' : 'auto');
+    const lock = acquireLock(storeDir, requestedScanType);
+    if (!lock.ok) {
+        console.log(lock.message);
+        const duration = Date.now() - startTime;
+        return {
+            components: [],
+            connections: [],
+            warnings: [],
+            stats: {
+                scan_duration_ms: duration,
+                components_found: 0,
+                connections_found: 0,
+                warnings_count: 0,
+                files_scanned: 0,
+                files_changed: 0,
+            },
+        };
+    }
+    try {
+        // ==========================================================================
+        // Phase 0: File Discovery & Change Detection
+        // ==========================================================================
+        const sourceFiles = await glob('**/*.{ts,tsx,js,jsx,mjs,cjs,py,swift,h,m}', {
+            cwd: root,
+            ignore: getIgnorePatterns(root),
+        });
+        // For change detection, also include manifest files at the project root
+        // (and a few well-known nested ones). selectScanMode consults these to
+        // decide whether to force a full scan. Manifests are NOT scanned by the
+        // per-language scanners — they're tracked here only for change detection.
+        const manifestPatterns = [
+            'package.json',
+            'package-lock.json',
+            'pnpm-lock.yaml',
+            'yarn.lock',
+            'pyproject.toml',
+            'requirements.txt',
+            'requirements-dev.txt',
+            'requirements-test.txt',
+            'prisma/schema.prisma',
+            'Package.swift',
+            'Package.resolved',
+            // Build / runtime config — track so changes trigger full scan
+            'tsconfig.json',
+            'vercel.json',
+            'fly.toml',
+            'railway.json',
+            '.gitignore',
+        ];
+        const manifestFiles = [];
+        for (const m of manifestPatterns) {
+            try {
+                const fs = await import('node:fs');
+                if (fs.existsSync(path.join(root, m)))
+                    manifestFiles.push(m);
+            }
+            catch {
+                // ignore
+            }
+        }
+        const filesForChangeDetection = [...sourceFiles, ...manifestFiles];
+        // Detect file changes using prior hashes BEFORE any clearing.
+        // (Used by mode selection AND timeline summary even on full scans.)
+        let fileChanges;
+        fileChanges = await detectFileChanges(filesForChangeDetection, root, config);
         if (options.verbose) {
             console.log(`File changes: ${formatFileChangeSummary(fileChanges)}`);
             if (fileChanges.added.length > 0 && fileChanges.added.length <= 5) {
@@ -52,272 +405,1314 @@ export async function scan(projectRoot, options = {}) {
                 console.log(`  Modified: ${fileChanges.modified.join(', ')}`);
             }
         }
-    }
-    const allComponents = [];
-    const allConnections = [];
-    const allWarnings = [];
-    let promptScanResultHolder;
-    let projectMetadata;
-    // ==========================================================================
-    // Phase 1: Package Detection
-    // ==========================================================================
-    if (options.verbose) {
-        console.log('Phase 1: Scanning packages...');
-    }
-    // NPM packages
-    if (detectNpm(root)) {
-        if (options.verbose)
-            console.log('  - Detected npm/yarn/pnpm project');
-        const result = await scanNpmPackages(root);
-        allComponents.push(...result.components);
-        allWarnings.push(...result.warnings);
-    }
-    // Python packages
-    if (detectPip(root)) {
-        if (options.verbose)
-            console.log('  - Detected Python project');
-        const result = await scanPipPackages(root);
-        allComponents.push(...result.components);
-        allWarnings.push(...result.warnings);
-    }
-    // Swift/iOS/Mac packages (SPM, CocoaPods)
-    if (detectSpm(root)) {
-        if (options.verbose)
-            console.log('  - Detected Swift/Xcode project');
-        const result = await scanSpmPackages(root);
-        allComponents.push(...result.components);
-        allWarnings.push(...result.warnings);
-    }
-    // ==========================================================================
-    // Phase 2: Infrastructure Detection
-    // ==========================================================================
-    if (options.verbose) {
-        console.log('Phase 2: Scanning infrastructure...');
-    }
-    const infraResult = await scanInfrastructure(root);
-    allComponents.push(...infraResult.components);
-    allWarnings.push(...infraResult.warnings);
-    // ==========================================================================
-    // Phase 3: Connection Detection (unless quick mode)
-    // ==========================================================================
-    if (!options.quick || options.connections) {
+        // ==========================================================================
+        // Phase 0.5: Scan-mode selection (Run 1 — D2)
+        // ==========================================================================
+        const priorIndex = await loadIndex(config, root);
+        const decision = selectScanMode(fileChanges, priorIndex, options);
+        // scanType captures the mode the scan ACTUALLY ran in (after potential
+        // integrity-check promotion). Initialized to the decision; may be promoted
+        // to 'incremental→full' below.
+        //
+        // Run 1.7 — Problem A: when this scan is the recursive re-entry from a
+        // failed integrity check (`_promotedFromIncremental === true`), `decision.mode`
+        // is 'full' (clearFirst forces it), but the user-visible scan_type should
+        // remain 'incremental→full' so timeline + stats consumers see the promotion
+        // evidence (Run 1.6 #3 contract). The actual scan body still runs as full.
+        let scanType = options._promotedFromIncremental ? 'incremental→full' : decision.mode;
+        if (options.verbose) {
+            console.log(`Scan mode: ${decision.mode} (${decision.reason})`);
+        }
+        // Compute walk-set for incremental: changedFiles ∪ reverseDeps
+        const changedSet = new Set();
+        if (fileChanges) {
+            for (const f of fileChanges.added)
+                changedSet.add(f);
+            for (const f of fileChanges.modified)
+                changedSet.add(f);
+            for (const f of fileChanges.removed)
+                changedSet.add(f);
+        }
+        let walkSet = new Set(changedSet);
+        if (decision.mode === 'incremental' && changedSet.size > 0) {
+            const reverseDeps = await loadReverseDeps(changedSet, config, root);
+            for (const f of reverseDeps)
+                walkSet.add(f);
+            if (options.verbose) {
+                console.log(`  Walk-set: ${changedSet.size} changed + ${reverseDeps.size} reverse-deps = ${walkSet.size} files`);
+            }
+        }
+        // Pass walkSet to scanners only on incremental. Full scans pass undefined to
+        // preserve bit-identical output (regression-locked by characterization snapshot).
+        const incWalkSet = decision.mode === 'incremental' ? walkSet : undefined;
+        // ==========================================================================
+        // Phase 0.6: Noop short-circuit (incremental + zero changes)
+        // ==========================================================================
+        if (decision.mode === 'incremental' && decision.reason === 'no-changes') {
+            // Nothing changed since last scan. Bump last_scan, update incrementals_since_full
+            // to 0 (no incremental work was done — but keep it as-is to honor the cap).
+            // Save fresh hashes (idempotent), update index timestamp, record noop timeline entry.
+            if (priorIndex) {
+                priorIndex.last_scan = Date.now();
+                // Note: incrementals_since_full and last_full_scan unchanged on noop.
+                await atomicWriteJSON(getIndexPath(config, root), priorIndex);
+            }
+            const fileHashes = await computeFileHashes(filesForChangeDetection, root);
+            await saveHashes(fileHashes, config, root);
+            const noopTimelineEntry = {
+                id: generateTimelineId(),
+                timestamp: Date.now(),
+                significance: 'patch',
+                triggers: [],
+                diff: {
+                    components: { added: [], removed: [], modified: [] },
+                    connections: { added: [], removed: [] },
+                    stats: {
+                        total_changes: 0,
+                        components_before: priorIndex?.stats.total_components ?? 0,
+                        components_after: priorIndex?.stats.total_components ?? 0,
+                        connections_before: priorIndex?.stats.total_connections ?? 0,
+                        connections_after: priorIndex?.stats.total_connections ?? 0,
+                    },
+                },
+                git: gitInfo,
+                scan_type: 'noop',
+                files_scanned: 0,
+            };
+            await saveTimelineEntry(noopTimelineEntry, config, root);
+            // Load existing components/connections so callers see the unchanged graph.
+            const existingComponents = await loadAllComponents(config, root);
+            const existingConnections = await loadAllConnections(config, root);
+            const duration = Date.now() - startTime;
+            if (options.verbose) {
+                console.log(`Scan complete (noop) in ${duration}ms`);
+            }
+            return {
+                components: existingComponents,
+                connections: existingConnections,
+                warnings: [],
+                fileChanges,
+                timelineEntry: noopTimelineEntry,
+                gitInfo,
+                stats: {
+                    scan_duration_ms: duration,
+                    components_found: existingComponents.length,
+                    connections_found: existingConnections.length,
+                    warnings_count: 0,
+                    files_scanned: 0,
+                    files_changed: 0,
+                },
+            };
+        }
+        // For full scans: clear ALL prior data up front (legacy clearFirst semantics).
+        // For incremental: defer to Phase 4 (clearForFiles + merge).
+        if (decision.mode === 'full' || options.clearFirst) {
+            await clearStorage(config, root);
+            ensureStorageDirectories(config, root);
+        }
+        const allComponents = [];
+        const allConnections = [];
+        const allWarnings = [];
+        let promptScanResultHolder;
+        let projectMetadata;
+        // ==========================================================================
+        // Phase 1: Package Detection
+        // ==========================================================================
         if (options.verbose) {
-            console.log('Phase 3: Scanning connections...');
+            console.log('Phase 1: Scanning packages...');
         }
-        if (options.useAST) {
-            // AST-based scanning (more accurate)
+        // Package scanners run in parallel (independent of each other).
+        //
+        // Multi-stack auto-discovery: if the project root has no stack manifest
+        // of its own, walk one level deep and scan each subdir that does. This
+        // catches the common monorepo-lite shape — a top-level `frontend/` with
+        // package.json + a top-level `backend/` with pyproject.toml — that the
+        // legacy single-root behavior silently missed (it would only scan
+        // whichever side was at the root).
+        //
+        // Pass `singleStack: true` (CLI: --single-stack) to force the legacy
+        // behavior. Each component scanned from a subroot gets its origin tagged
+        // via `metadata.origin_root` so downstream layers can group by stack.
+        {
+            const stackRoots = options.singleStack
+                ? [{ path: root, origin: '.' }]
+                : discoverStackRoots(root, options.verbose === true);
+            const packageTasks = [];
+            for (const sr of stackRoots) {
+                const tagOrigin = (result) => {
+                    // Skip when origin is the root — keeps single-stack output identical.
+                    if (sr.origin === '.')
+                        return;
+                    for (const c of result.components) {
+                        const md = c.metadata ?? {};
+                        c.metadata = { ...md, origin_root: sr.origin };
+                    }
+                };
+                if (detectNpm(sr.path)) {
+                    if (options.verbose) {
+                        console.log(`  - Detected npm/yarn/pnpm project (${sr.origin})`);
+                    }
+                    packageTasks.push(scanNpmPackages(sr.path).then(result => {
+                        tagOrigin(result);
+                        allComponents.push(...result.components);
+                        allWarnings.push(...result.warnings);
+                    }));
+                }
+                if (detectPip(sr.path)) {
+                    if (options.verbose) {
+                        console.log(`  - Detected Python project (${sr.origin})`);
+                    }
+                    packageTasks.push(scanPipPackages(sr.path).then(result => {
+                        tagOrigin(result);
+                        allComponents.push(...result.components);
+                        allWarnings.push(...result.warnings);
+                    }));
+                }
+                if (detectSpm(sr.path)) {
+                    if (options.verbose) {
+                        console.log(`  - Detected Swift/Xcode project (${sr.origin})`);
+                    }
+                    packageTasks.push(scanSpmPackages(sr.path).then(result => {
+                        tagOrigin(result);
+                        allComponents.push(...result.components);
+                        allWarnings.push(...result.warnings);
+                    }));
+                }
+            }
+            await Promise.all(packageTasks);
+        }
+        // ==========================================================================
+        // Phase 2: Infrastructure Detection
+        // ==========================================================================
+        if (options.verbose) {
+            console.log('Phase 2: Scanning infrastructure...');
+        }
+        const infraResult = await scanInfrastructure(root);
+        allComponents.push(...infraResult.components);
+        allWarnings.push(...infraResult.warnings);
+        // Prisma schema → database models + relations
+        if (detectPrisma(root)) {
             if (options.verbose)
-                console.log('  - Running AST analysis (ts-morph)...');
+                console.log('  - Detected Prisma schema');
             try {
-                const astResult = await scanWithAST(root);
-                allComponents.push(...astResult.components);
-                allConnections.push(...astResult.connections);
-                allWarnings.push(...astResult.warnings);
-                // Also scan for database operations
-                if (options.verbose)
-                    console.log('  - Scanning database operations...');
-                const dbResult = await scanDatabaseOperations(root);
-                allComponents.push(...dbResult.components);
-                allConnections.push(...dbResult.connections);
-                allWarnings.push(...dbResult.warnings);
+                const prismaResult = await scanPrismaSchema(root);
+                allComponents.push(...prismaResult.components);
+                allConnections.push(...prismaResult.connections);
+                allWarnings.push(...prismaResult.warnings);
+                if (options.verbose) {
+                    console.log(`    Models: ${prismaResult.components.length}, Relations: ${prismaResult.connections.length}`);
+                }
             }
             catch (error) {
                 allWarnings.push({
                     type: 'parse_error',
-                    message: `AST scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    message: `Prisma scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
                 });
-                // Fall back to regex scanning
-                if (options.verbose)
-                    console.log('  - Falling back to regex scanning...');
-                const serviceResult = await scanServiceCalls(root);
-                allComponents.push(...serviceResult.components);
-                allConnections.push(...serviceResult.connections);
-                allWarnings.push(...serviceResult.warnings);
             }
         }
-        else {
-            // Regex-based scanning (faster but less accurate)
+        // DB field usage analyzer (opt-in via FEATURE FLAG: fieldUsage)
+        let fieldUsageReportResult;
+        if (options.fieldUsage && canAnalyzeFieldUsage(root)) {
             if (options.verbose)
-                console.log('  - Scanning service calls (regex)...');
-            const serviceResult = await scanServiceCalls(root);
-            allComponents.push(...serviceResult.components);
-            allConnections.push(...serviceResult.connections);
-            allWarnings.push(...serviceResult.warnings);
-        }
-        // Swift code analysis (runtime deps, protocols, state, LLM calls)
-        if (detectSpm(root)) {
+                console.log('  - Analyzing DB field usage...');
+            try {
+                const fieldResult = await scanFieldUsage(root, incWalkSet);
+                allComponents.push(...fieldResult.components);
+                allConnections.push(...fieldResult.connections);
+                allWarnings.push(...fieldResult.warnings);
+                fieldUsageReportResult = fieldResult.report;
+                if (options.verbose && fieldResult.report) {
+                    const r = fieldResult.report;
+                    console.log(`    Fields: ${r.totalFields} total, ${r.unusedFields} unused, ${r.writeOnlyFields} write-only`);
+                }
+            }
+            catch (error) {
+                allWarnings.push({
+                    type: 'parse_error',
+                    message: `Field usage analysis failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                });
+            }
+        }
+        // TypeSpec validator (opt-in via FEATURE FLAG: typeSpec)
+        let typeSpecReportResult;
+        if (options.typeSpec && canValidateTypeSpec(root)) {
             if (options.verbose)
-                console.log('  - Scanning Swift code connections...');
+                console.log('  - Validating TypeSpec (Prisma vs TS interfaces)...');
             try {
-                const swiftResult = await scanSwiftCode(root);
-                allComponents.push(...swiftResult.components);
-                allConnections.push(...swiftResult.connections);
-                allWarnings.push(...swiftResult.warnings);
-                projectMetadata = swiftResult.projectMeta;
-                if (options.verbose) {
-                    console.log(`    Swift: ${swiftResult.components.length} components, ${swiftResult.connections.length} connections`);
-                    if (swiftResult.projectMeta.platforms) {
-                        console.log(`    Platforms: ${swiftResult.projectMeta.platforms.join(', ')}`);
+                const tsResult = await scanTypeSpecValidation(root);
+                allWarnings.push(...tsResult.warnings);
+                typeSpecReportResult = tsResult.report;
+                if (options.verbose && tsResult.report) {
+                    const r = tsResult.report;
+                    console.log(`    Interfaces: ${r.modelsWithInterfaces}/${r.modelsChecked} matched, ${r.totalMismatches} mismatches`);
+                }
+            }
+            catch (error) {
+                allWarnings.push({
+                    type: 'parse_error',
+                    message: `TypeSpec validation failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                });
+            }
+        }
+        // Env, queues, and crons are independent — run in parallel
+        {
+            const infraTasks = [];
+            if (detectEnvFiles(root)) {
+                if (options.verbose)
+                    console.log('  - Detected environment files');
+                infraTasks.push(scanEnvVars(root, incWalkSet).then(envResult => {
+                    allComponents.push(...envResult.components);
+                    allConnections.push(...envResult.connections);
+                    allWarnings.push(...envResult.warnings);
+                    if (options.verbose) {
+                        console.log(`    Env vars: ${envResult.components.length}, References: ${envResult.connections.length}`);
                     }
-                    if (swiftResult.projectMeta.architecture_pattern) {
-                        console.log(`    Architecture: ${swiftResult.projectMeta.architecture_pattern}`);
+                }).catch(error => {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Env scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }));
+            }
+            if (detectQueues(root)) {
+                if (options.verbose)
+                    console.log('  - Detected queue system');
+                infraTasks.push(scanQueues(root, incWalkSet).then(queueResult => {
+                    allComponents.push(...queueResult.components);
+                    allConnections.push(...queueResult.connections);
+                    allWarnings.push(...queueResult.warnings);
+                    if (options.verbose) {
+                        console.log(`    Queues: ${queueResult.components.length}, Connections: ${queueResult.connections.length}`);
                     }
+                }).catch(error => {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Queue scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }));
+            }
+            if (detectCrons(root)) {
+                if (options.verbose)
+                    console.log('  - Detected cron jobs');
+                infraTasks.push(scanCronJobs(root, incWalkSet).then(cronResult => {
+                    allComponents.push(...cronResult.components);
+                    allConnections.push(...cronResult.connections);
+                    allWarnings.push(...cronResult.warnings);
+                    if (options.verbose) {
+                        console.log(`    Cron jobs: ${cronResult.components.length}, Route connections: ${cronResult.connections.length}`);
+                    }
+                }).catch(error => {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Cron scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }));
+            }
+            await Promise.all(infraTasks);
+        }
+        // Deployment config → detailed infra metadata
+        if (options.verbose)
+            console.log('  - Scanning deployment config...');
+        try {
+            const deployResult = await scanDeployConfig(root);
+            allComponents.push(...deployResult.components);
+            allConnections.push(...deployResult.connections);
+            allWarnings.push(...deployResult.warnings);
+            if (options.verbose && deployResult.components.length > 0) {
+                console.log(`    Deploy configs: ${deployResult.components.length}, Entry points: ${deployResult.connections.length}`);
+            }
+        }
+        catch (error) {
+            allWarnings.push({
+                type: 'parse_error',
+                message: `Deploy config scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            });
+        }
+        // Prisma call detection: map source files to database models they query
+        const prismaModelComps = allComponents.filter(c => c.type === 'database' && c.tags?.includes('prisma'));
+        if (prismaModelComps.length > 0) {
+            if (options.verbose)
+                console.log('  - Scanning Prisma client calls...');
+            try {
+                const prismaCallResult = await scanPrismaCalls(root, prismaModelComps, incWalkSet);
+                allConnections.push(...prismaCallResult.connections);
+                if (options.verbose && prismaCallResult.connections.length > 0) {
+                    const uniqueModels = new Set(prismaCallResult.connections.map(c => c.description?.split(' queries ')[1]?.split(' ')[0]));
+                    console.log(`    DB queries: ${prismaCallResult.connections.length} file→model connections across ${uniqueModels.size} models`);
                 }
             }
             catch (error) {
                 allWarnings.push({
                     type: 'parse_error',
-                    message: `Swift code scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    message: `Prisma call scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
                 });
             }
         }
-        // AI prompts & LLM call tracing
-        if (options.prompts) {
-            // Step 1: Run anchor-based LLM call tracer (primary detection)
+        // ==========================================================================
+        // Phase 3: Connection Detection (unless quick mode)
+        // ==========================================================================
+        if (!options.quick || options.connections) {
+            if (options.verbose) {
+                console.log('Phase 3: Scanning connections...');
+            }
+            if (options.useAST) {
+                // AST-based scanning (more accurate)
+                if (options.verbose)
+                    console.log('  - Running AST analysis (ts-morph)...');
+                try {
+                    const astResult = await scanWithAST(root, incWalkSet);
+                    allComponents.push(...astResult.components);
+                    allConnections.push(...astResult.connections);
+                    allWarnings.push(...astResult.warnings);
+                    // Also scan for database operations
+                    if (options.verbose)
+                        console.log('  - Scanning database operations...');
+                    const dbResult = await scanDatabaseOperations(root, incWalkSet);
+                    allComponents.push(...dbResult.components);
+                    allConnections.push(...dbResult.connections);
+                    allWarnings.push(...dbResult.warnings);
+                }
+                catch (error) {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `AST scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                    // Fall back to regex scanning
+                    if (options.verbose)
+                        console.log('  - Falling back to regex scanning...');
+                    const serviceResult = await scanServiceCalls(root, incWalkSet);
+                    allComponents.push(...serviceResult.components);
+                    allConnections.push(...serviceResult.connections);
+                    allWarnings.push(...serviceResult.warnings);
+                }
+            }
+            else {
+                // Regex-based scanning (faster but less accurate)
+                if (options.verbose)
+                    console.log('  - Scanning service calls (regex)...');
+                const serviceResult = await scanServiceCalls(root, incWalkSet);
+                allComponents.push(...serviceResult.components);
+                allConnections.push(...serviceResult.connections);
+                allWarnings.push(...serviceResult.warnings);
+            }
+            // File-level import graph (TS/JS local imports)
             if (options.verbose)
-                console.log('  - Running LLM call tracer (anchor-based)...');
-            let traceResult;
+                console.log('  - Scanning file imports...');
             try {
-                traceResult = await traceLLMCalls(root);
-                allComponents.push(...traceResult.scanResult.components);
-                allConnections.push(...traceResult.scanResult.connections);
+                // Collect npm package components so bare imports (`import X from "react"`)
+                // can be resolved to the package component and emitted as `uses-package`
+                // edges. Use config_files filter instead of type filter: packages can be
+                // classified as 'npm' | 'framework' | 'database' | 'service' depending
+                // on FRAMEWORK_SIGNATURES, but all originate from a package.json.
+                const knownPackages = allComponents
+                    .filter(c => c.source.config_files?.some(f => f === 'package.json' || f.endsWith('/package.json')))
+                    .map(c => ({ name: c.name, component_id: c.component_id }));
+                // In incremental mode, restrict the import scan to walk-set files. Falls
+                // back to the full sourceFiles list (bit-identical) on full scans.
+                const importSourceFiles = incWalkSet
+                    ? sourceFiles.filter(f => incWalkSet.has(f))
+                    : sourceFiles;
+                const importResult = await scanImports(root, importSourceFiles, knownPackages);
+                allComponents.push(...importResult.components);
+                allConnections.push(...importResult.connections);
                 if (options.verbose) {
-                    console.log(`    Traced ${traceResult.calls.length} LLM call sites`);
-                    console.log(`    Wrappers: ${traceResult.wrappers.length}`);
-                    const providers = new Map();
-                    for (const call of traceResult.calls) {
-                        const p = call.provider.name;
-                        providers.set(p, (providers.get(p) || 0) + 1);
+                    const usesPkgCount = importResult.connections.filter(c => c.connection_type === 'uses-package').length;
+                    console.log(`    Found ${importResult.components.length} internal modules, ${importResult.connections.length} file-level imports (${usesPkgCount} uses-package)`);
+                }
+                // SCIP overlay (T11): when --scip / NAVGATOR_SCIP=1, run the
+                // compiler-accurate indexer and ADD any cross-file edges the regex
+                // import-scanner missed (re-exports, dynamic imports, type-only refs,
+                // etc.). Existing edges from the regex pass are preserved as-is so
+                // the characterization snapshots stay stable for non-SCIP runs.
+                const scipEnabled = process.env['NAVGATOR_SCIP'] === '1' || options.scip === true;
+                if (scipEnabled) {
+                    try {
+                        const { runScip, crossFileEdges, hasTsConfig } = await import('./parsers/scip-runner.js');
+                        if (!hasTsConfig(root)) {
+                            if (options.verbose)
+                                console.log('    SCIP requested but no tsconfig.json — skipping');
+                        }
+                        else {
+                            if (options.verbose)
+                                console.log('  - Running SCIP indexer (compiler-accurate)...');
+                            const scipResult = await runScip(root, { timeoutMs: 60_000 });
+                            if (!scipResult.ok) {
+                                allWarnings.push({
+                                    type: 'parse_error',
+                                    message: `SCIP indexer failed: ${scipResult.error}`,
+                                });
+                            }
+                            else {
+                                const cross = crossFileEdges(scipResult.edges);
+                                const fileToComponentId = new Map();
+                                for (const c of importResult.components) {
+                                    const f = c.source?.config_files?.[0];
+                                    if (f)
+                                        fileToComponentId.set(f, c.component_id);
+                                }
+                                const existing = new Set(importResult.connections
+                                    .filter((c) => c.connection_type === 'imports')
+                                    .map((c) => `${c.from?.location?.file ?? ''}→${c.code_reference?.file ?? ''}`));
+                                let added = 0;
+                                const now = Date.now();
+                                for (const e of cross) {
+                                    const fromId = fileToComponentId.get(e.from_file);
+                                    const toId = fileToComponentId.get(e.to_file ?? '');
+                                    if (!fromId || !toId)
+                                        continue;
+                                    const key = `${e.from_file}→${e.to_file}`;
+                                    if (existing.has(key))
+                                        continue;
+                                    existing.add(key);
+                                    allConnections.push({
+                                        connection_id: `CONN_imports_scip_${Math.random().toString(36).slice(2, 10)}`,
+                                        from: {
+                                            component_id: fromId,
+                                            location: { file: e.from_file, line: e.from_line + 1 },
+                                        },
+                                        to: { component_id: toId },
+                                        connection_type: 'imports',
+                                        code_reference: {
+                                            file: e.from_file,
+                                            symbol: e.display_name || e.symbol.split('/').pop()?.slice(0, 40) || 'scip-ref',
+                                            symbol_type: e.is_definition ? 'export' : 'import',
+                                            line_start: e.from_line + 1,
+                                        },
+                                        description: 'SCIP-resolved cross-file reference',
+                                        detected_from: 'scip-typescript',
+                                        confidence: 0.99,
+                                        timestamp: now,
+                                        last_verified: now,
+                                    });
+                                    added++;
+                                }
+                                if (options.verbose) {
+                                    console.log(`    SCIP added ${added} cross-file edges (${scipResult.duration_ms}ms, ${scipResult.documents_indexed} docs)`);
+                                }
+                            }
+                        }
                     }
-                    for (const [provider, count] of providers) {
-                        console.log(`      ${provider}: ${count} call sites`);
+                    catch (err) {
+                        allWarnings.push({
+                            type: 'parse_error',
+                            message: `SCIP overlay failed: ${err.message}`,
+                        });
                     }
                 }
             }
             catch (error) {
                 allWarnings.push({
                     type: 'parse_error',
-                    message: `LLM call tracer failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    message: `Import scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
                 });
+            }
+            // Swift code analysis (runtime deps, protocols, state, LLM calls)
+            if (detectSpm(root)) {
                 if (options.verbose)
-                    console.log(`    LLM tracer error: ${error instanceof Error ? error.message : 'Unknown'}`);
+                    console.log('  - Scanning Swift code connections...');
+                try {
+                    const swiftResult = await scanSwiftCode(root, incWalkSet);
+                    allComponents.push(...swiftResult.components);
+                    allConnections.push(...swiftResult.connections);
+                    allWarnings.push(...swiftResult.warnings);
+                    projectMetadata = swiftResult.projectMeta;
+                    if (options.verbose) {
+                        console.log(`    Swift: ${swiftResult.components.length} components, ${swiftResult.connections.length} connections`);
+                        if (swiftResult.projectMeta.platforms) {
+                            console.log(`    Platforms: ${swiftResult.projectMeta.platforms.join(', ')}`);
+                        }
+                        if (swiftResult.projectMeta.architecture_pattern) {
+                            console.log(`    Architecture: ${swiftResult.projectMeta.architecture_pattern}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Swift code scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }
+                // Xcode project analysis (.pbxproj + storyboards)
+                try {
+                    const { findXcodeProject } = await import('./scanners/packages/swift.js');
+                    const pbxprojPath = findXcodeProject(root);
+                    if (pbxprojPath) {
+                        if (options.verbose)
+                            console.log('  - Scanning Xcode project...');
+                        const { parseXcodeProject, mapTargetToComponent, mapSourceMembership } = await import('./scanners/xcode/pbxproj-parser.js');
+                        const xcodeData = parseXcodeProject(pbxprojPath);
+                        const timestamp = Date.now();
+                        for (const target of xcodeData.targets) {
+                            const comp = mapTargetToComponent(target, timestamp);
+                            allComponents.push(comp);
+                            const memberConns = mapSourceMembership(target, comp.component_id, timestamp);
+                            allConnections.push(...memberConns);
+                        }
+                        // Enrich project metadata with Xcode target info
+                        if (projectMetadata) {
+                            projectMetadata.targets = xcodeData.targets.map(t => ({
+                                name: t.name,
+                                type: t.type,
+                                dependencies: t.frameworks,
+                            }));
+                            projectMetadata.xcodeProject = {
+                                path: pbxprojPath,
+                                targets: xcodeData.targets.map(t => ({
+                                    name: t.name,
+                                    type: t.type,
+                                    bundleId: t.bundleId,
+                                })),
+                            };
+                        }
+                        if (options.verbose) {
+                            console.log(`    Xcode: ${xcodeData.targets.length} targets`);
+                        }
+                    }
+                    // Storyboard/XIB scanning
+                    const { scanStoryboards } = await import('./scanners/xcode/storyboard-scanner.js');
+                    const storyboardResult = await scanStoryboards(root);
+                    allComponents.push(...storyboardResult.components);
+                    allConnections.push(...storyboardResult.connections);
+                    if (options.verbose && storyboardResult.components.length > 0) {
+                        console.log(`    Storyboards: ${storyboardResult.components.length} VCs, ${storyboardResult.connections.length} segues`);
+                    }
+                }
+                catch (error) {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `Xcode project scanning failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                }
             }
-            // Step 2: Run regex prompt detector with corroboration (secondary — catches prompt definitions)
-            if (options.verbose)
-                console.log('  - Running prompt detector (corroboration-filtered)...');
-            promptScanResultHolder = await scanPrompts(root, {
-                includeRawContent: true,
-                detectVariables: true,
-                requireAPICallAnchor: true,
-                minCorroborationSignals: 2,
-            });
-            // Attach tracer results to prompt scan data (for web UI)
-            if (traceResult) {
-                promptScanResultHolder.tracedCalls = traceResult.calls;
-                promptScanResultHolder.summary.tracedCallSites = traceResult.calls.length;
-            }
-            // Convert prompt definitions to architecture format
-            const promptArchitecture = convertToArchitecture(promptScanResultHolder.prompts);
-            allComponents.push(...promptArchitecture.components);
-            allConnections.push(...promptArchitecture.connections);
-            allWarnings.push(...promptArchitecture.warnings);
+            // AI prompts & LLM call tracing
+            if (options.prompts) {
+                // Step 1: Run anchor-based LLM call tracer (primary detection)
+                if (options.verbose)
+                    console.log('  - Running LLM call tracer (anchor-based)...');
+                let traceResult;
+                try {
+                    traceResult = await traceLLMCalls(root, incWalkSet);
+                    allComponents.push(...traceResult.scanResult.components);
+                    allConnections.push(...traceResult.scanResult.connections);
+                    if (options.verbose) {
+                        console.log(`    Traced ${traceResult.calls.length} LLM call sites`);
+                        console.log(`    Wrappers: ${traceResult.wrappers.length}`);
+                        const providers = new Map();
+                        for (const call of traceResult.calls) {
+                            const p = call.provider.name;
+                            providers.set(p, (providers.get(p) || 0) + 1);
+                        }
+                        for (const [provider, count] of providers) {
+                            console.log(`      ${provider}: ${count} call sites`);
+                        }
+                    }
+                }
+                catch (error) {
+                    allWarnings.push({
+                        type: 'parse_error',
+                        message: `LLM call tracer failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    });
+                    if (options.verbose)
+                        console.log(`    LLM tracer error: ${error instanceof Error ? error.message : 'Unknown'}`);
+                }
+                // Step 2: Run regex prompt detector with corroboration (secondary — catches prompt definitions)
+                if (options.verbose)
+                    console.log('  - Running prompt detector (corroboration-filtered)...');
+                promptScanResultHolder = await scanPrompts(root, {
+                    includeRawContent: true,
+                    detectVariables: true,
+                    aggressive: true,
+                }, incWalkSet);
+                // Attach tracer results to prompt scan data (for web UI)
+                if (traceResult) {
+                    promptScanResultHolder.tracedCalls = traceResult.calls;
+                    promptScanResultHolder.summary.tracedCallSites = traceResult.calls.length;
+                }
+                // Convert prompt definitions to architecture format
+                const promptArchitecture = convertToArchitecture(promptScanResultHolder.prompts);
+                allComponents.push(...promptArchitecture.components);
+                allConnections.push(...promptArchitecture.connections);
+                allWarnings.push(...promptArchitecture.warnings);
+                if (options.verbose) {
+                    console.log(`    Found ${promptScanResultHolder.prompts.length} prompt definitions`);
+                    if (promptScanResultHolder.summary.byProvider) {
+                        for (const [provider, count] of Object.entries(promptScanResultHolder.summary.byProvider)) {
+                            console.log(`      ${provider}: ${count}`);
+                        }
+                    }
+                }
+            }
+        }
+        // ==========================================================================
+        // Phase 3.5: Semantic Classification
+        // ==========================================================================
+        if (allConnections.length > 0 && allComponents.length > 0) {
             if (options.verbose) {
-                console.log(`    Found ${promptScanResultHolder.prompts.length} prompt definitions`);
-                if (promptScanResultHolder.summary.byProvider) {
-                    for (const [provider, count] of Object.entries(promptScanResultHolder.summary.byProvider)) {
-                        console.log(`      ${provider}: ${count}`);
+                console.log('Phase 3.5: Classifying connections...');
+            }
+            const semantics = classifyAllConnections(allConnections, allComponents);
+            for (const conn of allConnections) {
+                const info = semantics.get(conn.connection_id);
+                if (info) {
+                    conn.semantic = info;
+                }
+            }
+            if (options.verbose) {
+                const byClass = new Map();
+                for (const [, info] of semantics) {
+                    byClass.set(info.classification, (byClass.get(info.classification) || 0) + 1);
+                }
+                for (const [cls, count] of byClass) {
+                    console.log(`  ${cls}: ${count}`);
+                }
+            }
+        }
+        // ==========================================================================
+        // Phase 4: Deduplicate & Store
+        // ==========================================================================
+        if (options.verbose) {
+            console.log('Phase 4: Storing results...');
+        }
+        // Deduplicate components by (type, name, primary-source-file) within current scan.
+        //
+        // Run 1.7 — Problem B: the prior key was `component.name` alone. That
+        // collided cross-type — e.g., the file-level component for `lib/prisma.ts`
+        // (type='component', name='prisma') vs the Prisma DB component
+        // (type='database', name='prisma'). The DB component won on confidence;
+        // the file component was silently dropped. But the import-scanner had
+        // already emitted edges referencing the dropped file component_id —
+        // 410 orphan edges on atomize-ai, which fired the integrity-promote and
+        // truncated the graph (Problem A's loud symptom).
+        //
+        // The fix keys by `${type}|${name}|${first-config-file}`:
+        //   • Different types coexist (was: collided).
+        //   • Same-type same-name from different paths coexist (was: collided —
+        //     `app/proxy.ts` and `proxy.ts` both produce a file-level component
+        //     named `proxy`; both are real, both must be kept). Path
+        //     disambiguation matches Run 1.6 verify #6's stable_id contract for
+        //     the 6 component types where `name` alone isn't unique.
+        //   • Same-type same-name same-file STILL dedupes (the genuine duplicate
+        //     case — AST + regex both detecting the same service call), with
+        //     highest confidence winning. For components with no config_files
+        //     (rare) the key falls back to `${type}|${name}|` and behaves like
+        //     the legacy by-name dedup within that type.
+        const componentMap = new Map();
+        for (const component of allComponents) {
+            const primaryFile = component.source?.config_files?.[0] ?? '';
+            const key = `${component.type}|${component.name}|${primaryFile}`;
+            const existing = componentMap.get(key);
+            if (!existing || component.source.confidence > existing.source.confidence) {
+                componentMap.set(key, component);
+            }
+        }
+        const uniqueComponents = Array.from(componentMap.values());
+        // Deduplicate connections by composite key (within current scan)
+        // Keeps highest confidence when duplicates found (e.g., regex + AST detect same call)
+        const connectionMap = new Map();
+        for (const conn of allConnections) {
+            const key = `${conn.from.component_id}|${conn.to.component_id}|${conn.connection_type}|${conn.code_reference?.file || ''}:${conn.code_reference?.line_start || ''}`;
+            const existing = connectionMap.get(key);
+            if (!existing || conn.confidence > existing.confidence) {
+                connectionMap.set(key, conn);
+            }
+        }
+        const uniqueConnections = Array.from(connectionMap.values());
+        // (C) Resolve FILE: prefixed connection targets to real component IDs
+        // This enables trace to follow imports from route files instead of dead-ending
+        const compByFile = new Map(); // file path → component_id
+        for (const comp of uniqueComponents) {
+            for (const f of comp.source.config_files || []) {
+                compByFile.set(f, comp.component_id);
+            }
+        }
+        for (const conn of uniqueConnections) {
+            if (conn.to.component_id?.startsWith('FILE:')) {
+                const filePath = conn.to.component_id.slice(5);
+                const realId = compByFile.get(filePath);
+                if (realId) {
+                    conn.to.component_id = realId;
+                }
+            }
+            if (conn.from.component_id?.startsWith('FILE:')) {
+                const filePath = conn.from.component_id.slice(5);
+                const realId = compByFile.get(filePath);
+                if (realId) {
+                    conn.from.component_id = realId;
+                }
+            }
+        }
+        // Snapshot previous state before overwriting (for change tracking)
+        // Also load the pre-scan snapshot for diff computation
+        let preScanSnapshot = null;
+        if (!options.clearFirst && decision.mode !== 'full') {
+            try {
+                await createSnapshot('pre-scan', config, root);
+                preScanSnapshot = await loadLatestSnapshot(config, root);
+            }
+            catch {
+                // No previous data to snapshot — first scan
+            }
+        }
+        else if (decision.mode === 'full') {
+            // For full scans, still create a snapshot for diff (if prior data exists)
+            try {
+                preScanSnapshot = await loadLatestSnapshot(config, root);
+            }
+            catch {
+                // First-ever scan, no prior snapshot.
+            }
+        }
+        // ==========================================================================
+        // Phase 4 storage decision (Run 1 — D1 + D2):
+        //   - 'full': clearStorage was already done up front; now store everything fresh.
+        //   - 'incremental': clear ONLY components/connections that originate in the
+        //     walk-set, then merge the freshly-scanned uniqueComponents/Connections
+        //     with the survivors. Run integrity check; on failure, promote to full.
+        // ==========================================================================
+        let finalComponents = uniqueComponents;
+        let finalConnections = uniqueConnections;
+        if (decision.mode === 'incremental' && !options.clearFirst) {
+            // Snapshot the FULL prior on-disk component set BEFORE clearForFiles —
+            // we need it to remap surviving connections from old random component_ids
+            // to the new ones (since stable_id is the join key but connections
+            // reference component_id, which gets a fresh random suffix per scan).
+            const preClearComponents = await loadAllComponents(config, root);
+            // Clear only the touched subset.
+            await clearForFiles(config, root, walkSet);
+            // Load survivors (everything NOT in walk-set, still on disk).
+            const survivingComponents = await loadAllComponents(config, root);
+            const survivingConnections = await loadAllConnections(config, root);
+            // Populate stable_ids on the in-memory uniqueComponents BEFORE merging.
+            // Disk-loaded survivors get stable_ids from loadAllComponents, but
+            // freshly-scanned components don't have them set until storeComponents
+            // runs — and we merge BEFORE store. Without this, every fresh component
+            // looks like a new entry to mergeByStableId (because its key falls back
+            // to its random component_id), breaking dedup.
+            for (const c of uniqueComponents)
+                ensureStableIdPublic(c);
+            // Merge: incoming wins on stable_id collision (component) or composite key (connection).
+            // Components keyed by stable_id (or component_id fallback).
+            finalComponents = mergeByStableId(survivingComponents, uniqueComponents, (c) => c.stable_id ?? c.component_id);
+            // Build a remap: prior_component_id → new_component_id (via stable_id).
+            // Connections from disk reference OLD random component_ids; the freshly
+            // scanned components have NEW random component_ids. Same stable_id ties
+            // them together. Rewrite surviving connection from/to ids so the merged
+            // graph stays consistent.
+            const stableToNewId = new Map();
+            for (const c of finalComponents) {
+                if (c.stable_id)
+                    stableToNewId.set(c.stable_id, c.component_id);
+            }
+            // oldIdToStable: maps every PRIOR-scan component_id (including ones we
+            // just deleted via clearForFiles) to its stable_id. Built from the
+            // pre-clear snapshot so we can resolve connection refs to their new IDs.
+            const oldIdToStable = new Map();
+            for (const c of preClearComponents) {
+                if (c.stable_id)
+                    oldIdToStable.set(c.component_id, c.stable_id);
+            }
+            // Also map fresh components' ids → stable (no remap needed but keeps the
+            // rewrite loop a no-op for these instead of leaving them undefined).
+            for (const c of uniqueComponents) {
+                if (c.stable_id)
+                    oldIdToStable.set(c.component_id, c.stable_id);
+            }
+            function remapId(id) {
+                if (!id)
+                    return id;
+                if (id.startsWith('FILE:'))
+                    return id;
+                const stable = oldIdToStable.get(id);
+                if (stable) {
+                    const newId = stableToNewId.get(stable);
+                    if (newId)
+                        return newId;
+                }
+                return id; // No remap available — leave alone, integrity check may catch
+            }
+            // Rewrite surviving connections to use the latest component_ids.
+            for (const conn of survivingConnections) {
+                if (conn.from?.component_id) {
+                    conn.from.component_id = remapId(conn.from.component_id) ?? conn.from.component_id;
+                }
+                if (conn.to?.component_id) {
+                    conn.to.component_id = remapId(conn.to.component_id) ?? conn.to.component_id;
+                }
+            }
+            // Connections keyed by from|to|type|file:line composite (matches dedup key).
+            const connKey = (c) => `${c.from?.component_id ?? ''}|${c.to?.component_id ?? ''}|${c.connection_type}|${c.code_reference?.file ?? ''}:${c.code_reference?.line_start ?? ''}`;
+            finalConnections = mergeByStableId(survivingConnections, uniqueConnections, connKey);
+            // Integrity check: every connection endpoint must exist; every walk-set
+            // component must reference real source files. On failure → promote to full.
+            const integrity = await runIntegrityCheck(finalComponents, finalConnections, root, walkSet);
+            if (!integrity.ok) {
+                if (options.verbose) {
+                    console.log(`  Integrity check failed (${integrity.issues.length} issues) — promoting to full scan`);
+                    for (const issue of integrity.issues.slice(0, 3)) {
+                        console.log(`    ${issue}`);
                     }
                 }
+                // ============================================================
+                // Run 1.7 — Problem A (recursive re-entry promote)
+                // ============================================================
+                // The pre-Run-1.7 promote reused the in-memory uniqueComponents/
+                // uniqueConnections that were just computed under the walk-set
+                // restriction. After Run 1.5's walk-set plumbing, those are NOT
+                // the full source tree — only the walk-set's slice of it. Reusing
+                // them on promote truncated the graph (atomize-ai: 6,445 → 58
+                // connections, 2,452 → 58 components).
+                //
+                // Fix: release the scan lock and recursively re-enter scan() with
+                // `mode: 'full', clearFirst: true`. The inner scan walks the full
+                // source tree, the lock re-acquires cleanly inside, and its result
+                // is returned verbatim. The internal `_promotedFromIncremental`
+                // flag tells the inner scan to label its timeline entry and stats
+                // `scan_type: 'incremental→full'` — preserving the Run 1.6 #3
+                // evidence-preservation contract.
+                //
+                // We `return` early so the rest of the outer scan's phases
+                // (storage, timeline, manifest, hashes) don't double-run.
+                lock.release();
+                return await scan(root, {
+                    ...options,
+                    mode: 'full',
+                    clearFirst: true,
+                    incremental: false,
+                    _promotedFromIncremental: true,
+                });
+            }
+            // ============================================================
+            // Run 1.7 — orphan-disk-file cleanup on successful incremental merge.
+            // ============================================================
+            // `clearForFiles` only deletes disk files whose `source.config_files`
+            // overlap the walk-set. Components produced by always-full scanners
+            // (npm/pip/swift packages, infra, prisma) don't list user source
+            // files in `config_files` (they list manifests / abs paths), so
+            // their disk files survive `clearForFiles`. After the merge, the
+            // freshly-scanned versions get NEW random `component_id`s and are
+            // written to NEW filenames. The OLD survivor files are now orphans:
+            // unreachable from `finalComponents` but still on disk.
+            //
+            // Pre-Run-1.7 this was masked by the always-failing integrity check
+            // on real projects (`clearStorage` on promote wiped the orphans).
+            // Now that integrity passes (Problem B fix), and the promote is
+            // recursive (Problem A fix), this latent bug surfaces as a doubling
+            // of `npm`/`database`/`config`/`infra` components per incremental.
+            //
+            // Fix: after the merge, walk the components/connections directories
+            // and unlink any file whose ID isn't in `finalComponents` /
+            // `finalConnections`. Idempotent and atomic per-file (unlink errors
+            // are silently swallowed — best-effort, matches the integrity-promote
+            // pattern). Connections also need this since their random IDs aren't
+            // stable across scans either.
+            {
+                const finalComponentIds = new Set(finalComponents.map((c) => c.component_id));
+                const finalConnectionIds = new Set(finalConnections.map((c) => c.connection_id));
+                const fsPromises = (await import('node:fs')).promises;
+                const purgeOrphans = async (dir, keepIds) => {
+                    try {
+                        const files = await fsPromises.readdir(dir);
+                        await Promise.all(files
+                            .filter((f) => f.endsWith('.json'))
+                            .map(async (f) => {
+                            const id = f.slice(0, -'.json'.length);
+                            if (!keepIds.has(id)) {
+                                await fsPromises.unlink(path.join(dir, f)).catch(() => { });
+                            }
+                        }));
+                    }
+                    catch {
+                        // Dir missing or unreadable — non-fatal.
+                    }
+                };
+                await purgeOrphans(getComponentsPath(config, root), finalComponentIds);
+                await purgeOrphans(getConnectionsPath(config, root), finalConnectionIds);
             }
         }
-    }
-    // ==========================================================================
-    // Phase 4: Deduplicate & Store
-    // ==========================================================================
-    if (options.verbose) {
-        console.log('Phase 4: Storing results...');
-    }
-    // Deduplicate components by name (within current scan)
-    const componentMap = new Map();
-    for (const component of allComponents) {
-        const existing = componentMap.get(component.name);
-        if (!existing || component.source.confidence > existing.source.confidence) {
-            componentMap.set(component.name, component);
-        }
-    }
-    const uniqueComponents = Array.from(componentMap.values());
-    // Deduplicate connections by composite key (within current scan)
-    // Keeps highest confidence when duplicates found (e.g., regex + AST detect same call)
-    const connectionMap = new Map();
-    for (const conn of allConnections) {
-        const key = `${conn.from.component_id}|${conn.to.component_id}|${conn.connection_type}|${conn.code_reference?.file || ''}:${conn.code_reference?.line_start || ''}`;
-        const existing = connectionMap.get(key);
-        if (!existing || conn.confidence > existing.confidence) {
-            connectionMap.set(key, conn);
-        }
-    }
-    const uniqueConnections = Array.from(connectionMap.values());
-    // Snapshot previous state before overwriting (for change tracking)
-    if (!options.clearFirst) {
+        // External enrichment (structural axis): stamp boundary nodes (npm/service/
+        // llm/infra/spm/...) with cached canonical identity, latest version, docs, and
+        // a freshness verdict. Offline + sync — reads NavGator's own JSON cache, never
+        // the network, so it cannot slow or fail the scan. The freshness axis (network
+        // re-checks) runs separately via refreshExternal / the external-resolver agent.
         try {
-            await createSnapshot('pre-scan', config, root);
+            const cache = loadCache();
+            enrichFromCache(finalComponents, makeLookup(cache), Date.now());
         }
         catch {
-            // No previous data to snapshot — first scan
+            /* enrichment is best-effort — never block persistence on it */
         }
+        // Store final state (atomic per-file writes — see storage.ts).
+        await storeComponents(finalComponents, config, root);
+        await storeConnections(finalConnections, config, root);
+        // R6 footprint fix: clean up legacy per-entity files when the feature is
+        // disabled (default). Idempotent and best-effort — never blocks the scan.
+        // Surfaces a one-line notice when something actually got cleaned.
+        try {
+            const migrated = await migratePerEntityFiles(config, root);
+            if (options.verbose &&
+                (migrated.componentsRemoved > 0 ||
+                    migrated.connectionsRemoved > 0 ||
+                    migrated.dirsRemoved > 0)) {
+                console.log(`  R6 migration: removed ${migrated.componentsRemoved} legacy component file(s), ${migrated.connectionsRemoved} legacy connection file(s), ${migrated.dirsRemoved} now-empty dir(s)`);
+            }
+        }
+        catch {
+            // Best-effort.
+        }
+        // ==========================================================================
+        // Phase 4.5: SQC Audit (Run 2 — D4)
+        //
+        // Sample the just-stored output, run deterministic verifiers (+ structured
+        // LLM-judge payload in MCP mode), and update per-stratum EWMA state.
+        // Audit failure NEVER fails the scan — only updates the index's EWMA so the
+        // NEXT scan can auto-promote on detected drift.
+        // ==========================================================================
+        let auditReport;
+        if (!options.noAudit) {
+            try {
+                const planOpt = options.auditPlan
+                    ? (options.auditPlan.toUpperCase() === 'AQL'
+                        ? 'AQL'
+                        : options.auditPlan.toUpperCase() === 'SPRT'
+                            ? 'SPRT'
+                            : 'Cochran')
+                    : undefined;
+                const auditOpts = {
+                    plan: planOpt,
+                    isMcpMode: !!options.isMcpMode,
+                    priorEwma: priorIndex?.ewma,
+                    priorAuditCount: priorIndex?.audit_history_count ?? 0,
+                    forceCochran: !!priorIndex?.pending_drift_breach,
+                };
+                const r = await runAudit({ components: finalComponents, connections: finalConnections }, config, root, auditOpts);
+                if (r) {
+                    // Update EWMA snapshot from prior index. We do not write the index here —
+                    // the post-Phase-5 index annotation already runs (line ~1430) and we
+                    // hijack `priorIndex` via the loadIndex/atomicWriteJSON cycle there.
+                    const { ewma, anyBreach } = updateEwmaForAudit(priorIndex?.ewma ?? undefined, r);
+                    if (anyBreach)
+                        r.drift_breach = true;
+                    auditReport = r;
+                    // Stash on a local for the index-annotation block below to consume.
+                    // (We re-read priorIndex after the freshIndex write to merge ewma.)
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    auditReport.__ewma = ewma;
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    auditReport.__anyBreach = anyBreach;
+                }
+            }
+            catch (err) {
+                if (process.env['NAVGATOR_DEBUG']) {
+                    console.error('[audit] skipped due to error:', err.message);
+                }
+            }
+        }
+        // ==========================================================================
+        // Phase 5: Architecture Diff
+        // ==========================================================================
+        let timelineEntry;
+        if (options.verbose) {
+            console.log('Phase 5: Computing architecture diff...');
+        }
+        try {
+            const currentSnapshot = await buildCurrentSnapshot(config, root);
+            const diff = computeArchitectureDiff(preScanSnapshot, currentSnapshot);
+            const { significance, triggers } = classifySignificance(diff);
+            timelineEntry = {
+                id: generateTimelineId(),
+                timestamp: Date.now(),
+                significance,
+                triggers,
+                diff,
+                snapshot_id: currentSnapshot.snapshot_id,
+                git: gitInfo,
+                scan_type: scanType,
+                // Run 1.6 — item #3: report walk-set size for 'incremental' AND for the
+                // legacy in-place 'incremental→full' promote (which kept walkSet
+                // populated), so a silent integrity-promote didn't erase evidence
+                // that an incremental walk-set was attempted.
+                //
+                // Run 1.7 — Problem A: the recursive-re-entry promote runs as a true
+                // full scan (walkSet empty). Reporting `walkSet.size = 0` would be
+                // dishonest — the inner scan really did walk every source file.
+                // Report `sourceFiles.length` in that case. Run 1.6 #3 still holds:
+                // any future in-place promote path (walkSet populated under
+                // 'incremental→full') reports walk-set size.
+                // Use decision.mode (the EFFECTIVE scan mode) instead of scanType
+                // (the user-visible label). On the recursive-re-entry promote (Run 1.7
+                // Problem A), decision.mode='full' even though scanType='incremental→full',
+                // and walkSet may be populated by the still-modified file — but the inner
+                // scan walked the full source tree, so files_scanned must be sourceFiles.length.
+                files_scanned: decision.mode === 'incremental' && walkSet.size > 0
+                    ? walkSet.size
+                    : sourceFiles.length,
+                // Run 2 — D4: audit report (when produced).
+                ...(auditReport ? { audit: stripInternals(auditReport) } : {}),
+            };
+            // Only save timeline entry if there are changes (or first scan)
+            if (diff.stats.total_changes > 0 || !preScanSnapshot) {
+                await saveTimelineEntry(timelineEntry, config, root);
+            }
+            if (options.verbose) {
+                console.log(`  Significance: ${significance}`);
+                console.log(`  Changes: ${diff.stats.total_changes}`);
+                if (triggers.length > 0) {
+                    console.log(`  Triggers: ${triggers.join(', ')}`);
+                }
+            }
+        }
+        catch {
+            // Diff computation is non-critical
+            if (options.verbose) {
+                console.log('  Diff computation skipped (non-critical error)');
+            }
+        }
+        // Build index, graph, file map, and summary.
+        // R6: pass the in-memory final state so derived files don't depend on
+        // per-entity disk reads (which are now opt-in and empty by default).
+        const derivedData = { components: finalComponents, connections: finalConnections };
+        await buildIndex(config, root, projectMetadata, derivedData);
+        await buildGraph(config, root, derivedData);
+        await buildFileMap(config, root, derivedData);
+        // ==========================================================================
+        // Phase 5.4: Derived reverse-deps index + manifest (Run 1.6 — items #8 + #9)
+        // ==========================================================================
+        // The reverse-deps index lets the next incremental scan compute walk-set
+        // expansion from a single file open instead of walking every per-edge JSON.
+        // The manifest lists all derived artifacts with their generated_at stamps.
+        let reverseDepsEdgeCount;
+        try {
+            const result = await buildReverseDepsIndex(finalComponents, finalConnections, config, root);
+            reverseDepsEdgeCount = result.edge_count;
+        }
+        catch (err) {
+            if (process.env['NAVGATOR_DEBUG']) {
+                console.error('[reverse-deps] index build skipped:', err.message);
+            }
+        }
+        try {
+            await buildDerivedManifest(config, root, { reverseDepsEdgeCount });
+        }
+        catch (err) {
+            if (process.env['NAVGATOR_DEBUG']) {
+                console.error('[manifest] write skipped:', err.message);
+            }
+        }
+        // ==========================================================================
+        // Phase 5.5: Annotate index with mode-tracking fields (Run 1 — D2)
+        //   Run AFTER buildIndex so we can annotate the freshly-written index
+        //   without buildIndex needing to know about modes.
+        // ==========================================================================
+        try {
+            const freshIndex = await loadIndex(config, root);
+            if (freshIndex) {
+                if (scanType === 'full' || scanType === 'incremental→full') {
+                    freshIndex.last_full_scan = Date.now();
+                    freshIndex.incrementals_since_full = 0;
+                }
+                else if (scanType === 'incremental') {
+                    // Preserve last_full_scan from prior index; bump counter.
+                    if (priorIndex) {
+                        freshIndex.last_full_scan = priorIndex.last_full_scan ?? priorIndex.last_scan ?? 0;
+                    }
+                    freshIndex.incrementals_since_full = (priorIndex?.incrementals_since_full ?? 0) + 1;
+                }
+                // Always set schema_version to current build's version.
+                freshIndex.schema_version = SCHEMA_VERSION;
+                // Run 2 — D5: persist EWMA + audit history bookkeeping.
+                if (auditReport) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const stash = auditReport;
+                    if (stash.__ewma) {
+                        freshIndex.ewma = stash.__ewma;
+                    }
+                    freshIndex.audit_history_count = (priorIndex?.audit_history_count ?? 0) + 1;
+                    freshIndex.pending_drift_breach = !!stash.__anyBreach;
+                }
+                else if (priorIndex) {
+                    // No audit this run — preserve prior values.
+                    if (priorIndex.ewma)
+                        freshIndex.ewma = priorIndex.ewma;
+                    if (priorIndex.audit_history_count !== undefined) {
+                        freshIndex.audit_history_count = priorIndex.audit_history_count;
+                    }
+                    // Clear pending breach if we just promoted on it.
+                    if (priorIndex.pending_drift_breach && scanType !== 'incremental') {
+                        freshIndex.pending_drift_breach = false;
+                    }
+                    else if (priorIndex.pending_drift_breach !== undefined) {
+                        freshIndex.pending_drift_breach = priorIndex.pending_drift_breach;
+                    }
+                }
+                await atomicWriteJSON(getIndexPath(config, root), freshIndex);
+            }
+        }
+        catch {
+            // Non-fatal: mode-tracking annotation is best-effort.
+        }
+        // Compute graph-wide metrics (PageRank + Louvain communities) → metrics.json,
+        // and back-write per-component scores into component metadata so any consumer
+        // that loads a component sees them. Suppressed for graphs <20 nodes.
+        try {
+            const { computeAndStoreMetrics } = await import('./metrics/pagerank-louvain.js');
+            await computeAndStoreMetrics(config, root, {
+                components: finalComponents,
+                connections: finalConnections,
+            });
+        }
+        catch (err) {
+            // Non-fatal — scan still produces all other artifacts.
+            if (process.env['NAVGATOR_DEBUG']) {
+                console.error('[metrics] PageRank/Louvain skipped:', err.message);
+            }
+        }
+        await buildSummary(config, root, promptScanResultHolder, projectMetadata, timelineEntry, gitInfo, derivedData);
+        // R6: full-shape JSONL writers — the consolidated source of truth when
+        // per-entity files are disabled (the default). These carry the complete
+        // ArchitectureComponent / ArchitectureConnection objects so downstream
+        // loaders never need per-entity files. Always written; cheap (~2MB for
+        // atomize-ai-scale projects vs the 70MB per-entity sprawl).
+        try {
+            const { writeFullComponentsJsonl, writeFullConnectionsJsonl, } = await import('./storage/markdown-view.js');
+            const { getStoragePath: getStoragePathFn } = await import('./config.js');
+            const storeDir = getStoragePathFn(config, root);
+            await writeFullComponentsJsonl(storeDir, finalComponents);
+            await writeFullConnectionsJsonl(storeDir, finalConnections);
+        }
+        catch (err) {
+            if (process.env['NAVGATOR_DEBUG']) {
+                console.error('[full-jsonl] skipped:', err.message);
+            }
+        }
+        // Markdown views + connections.jsonl (T3, trimmed scope).
+        // Derived from in-memory components/connections — JSON remains canonical.
+        // Emits .navgator/architecture/components-md/<type>/<slug>.md (Obsidian-readable,
+        // git-diff-friendly, ripgrep-targetable) and connections.jsonl.
+        // Disable via NAVGATOR_NO_MARKDOWN=1 if downstream tooling chokes.
+        if (process.env['NAVGATOR_NO_MARKDOWN'] !== '1') {
+            try {
+                const { writeComponentMarkdownViews, writeConnectionsJsonl } = await import('./storage/markdown-view.js');
+                const { getStoragePath: getStoragePathFn } = await import('./config.js');
+                const storeDir = getStoragePathFn(config, root);
+                await writeComponentMarkdownViews(storeDir, finalComponents, finalConnections);
+                await writeConnectionsJsonl(storeDir, finalComponents, finalConnections);
+            }
+            catch (err) {
+                if (process.env['NAVGATOR_DEBUG']) {
+                    console.error('[markdown-view] skipped:', err.message);
+                }
+            }
+        }
+        // Git-backed temporal snapshot (T5). Commits the .navgator/ directory to a
+        // NESTED git store at .navgator/.git — invisible to the parent repo
+        // (gitignored). OPT-IN: enable via NAVGATOR_COMMIT=1 or `--commit` scan
+        // flag. Per-scan git subprocess overhead is ~180ms; default is OFF to
+        // preserve the speed criterion.
+        if (process.env['NAVGATOR_COMMIT'] === '1' || options.commit === true) {
+            try {
+                const { commitScan } = await import('./temporal/git-store.js');
+                const { getStoragePath } = await import('./config.js');
+                const storeDir = getStoragePath(config, root);
+                const sha7 = (gitInfo?.commit ?? '').slice(0, 7);
+                const msg = `scan ${new Date().toISOString()}${sha7 ? ` @ ${sha7}` : ''}`;
+                const result = commitScan(storeDir, msg);
+                if (!result.ok && process.env['NAVGATOR_DEBUG']) {
+                    console.error('[temporal] commit failed:', result.error);
+                }
+            }
+            catch (err) {
+                if (process.env['NAVGATOR_DEBUG']) {
+                    console.error('[temporal] skipped:', err.message);
+                }
+            }
+        }
+        // Persist prompt scan results if available
+        if (promptScanResultHolder) {
+            await savePromptScan(promptScanResultHolder, config, root);
+        }
+        // Register project in global registry
+        try {
+            await registerProject(root, {
+                components: finalComponents.length,
+                connections: finalConnections.length,
+                prompts: promptScanResultHolder?.prompts.length ?? 0,
+            }, timelineEntry?.significance, gitInfo);
+        }
+        catch {
+            // Non-critical
+        }
+        // ==========================================================================
+        // Phase 6: Save File Hashes
+        // ==========================================================================
+        if (options.verbose) {
+            console.log('Phase 6: Saving file hashes...');
+        }
+        // Phase 6: hash both source files AND manifests so manifest edits are
+        // detectable on the next scan (selectScanMode uses this to fire 'manifest-changed').
+        const fileHashes = await computeFileHashes(filesForChangeDetection, root);
+        await saveHashes(fileHashes, config, root);
+        const duration = Date.now() - startTime;
+        const filesChanged = fileChanges
+            ? fileChanges.added.length + fileChanges.modified.length + fileChanges.removed.length
+            : sourceFiles.length;
+        if (options.verbose) {
+            console.log(`\nScan complete in ${duration}ms`);
+            console.log(`  Components: ${finalComponents.length}`);
+            console.log(`  Connections: ${finalConnections.length}`);
+            console.log(`  Files scanned: ${sourceFiles.length}`);
+            console.log(`  Files changed: ${filesChanged}`);
+            console.log(`  Warnings: ${allWarnings.length}`);
+        }
+        // Gitignore safety guard: NavGator's per-config-var component files and
+        // NAVSUMMARY docs include parsed hostnames from .env files. They're
+        // regenerated on every scan, so there's no loss from keeping them local.
+        // Auto-add gitignore entries on first scan so hostnames don't drift into
+        // git history. Silent unless it makes a change.
+        try {
+            const guardResult = await ensureSafeGitignore(root);
+            if (guardResult.action === 'added' && options.verbose) {
+                console.log(`  NavGator safety guard: added gitignore block for architecture/components/COMP_config_*.json + NAVSUMMARY*.md`);
+            }
+        }
+        catch {
+            // Non-fatal: scan already completed, gitignore guard is best-effort
+        }
+        return {
+            components: finalComponents,
+            connections: finalConnections,
+            warnings: allWarnings,
+            fileChanges,
+            promptScan: promptScanResultHolder,
+            fieldUsageReport: fieldUsageReportResult,
+            typeSpecReport: typeSpecReportResult,
+            timelineEntry,
+            gitInfo,
+            stats: {
+                scan_duration_ms: duration,
+                components_found: finalComponents.length,
+                connections_found: finalConnections.length,
+                warnings_count: allWarnings.length,
+                // Run 1.6 — item #3 / Run 1.7 — Problem A: walk-set size for incremental
+                // and for an in-place promote (walkSet populated). Recursive-re-entry
+                // promote (walkSet empty) reports actual source-file count.
+                // Use decision.mode (the EFFECTIVE scan mode) instead of scanType
+                // (the user-visible label). On the recursive-re-entry promote (Run 1.7
+                // Problem A), decision.mode='full' even though scanType='incremental→full',
+                // and walkSet may be populated by the still-modified file — but the inner
+                // scan walked the full source tree, so files_scanned must be sourceFiles.length.
+                files_scanned: decision.mode === 'incremental' && walkSet.size > 0
+                    ? walkSet.size
+                    : sourceFiles.length,
+                files_changed: filesChanged,
+                prompts_found: promptScanResultHolder?.prompts.length,
+            },
+        };
     }
-    // Clear old components/connections before storing new ones
-    // This ensures no duplicate accumulation across scans
-    await clearStorage(config, root);
-    ensureStorageDirectories(config, root);
-    // Store components and connections
-    await storeComponents(uniqueComponents, config, root);
-    await storeConnections(uniqueConnections, config, root);
-    // Build index, graph, file map, and summary
-    await buildIndex(config, root, projectMetadata);
-    await buildGraph(config, root);
-    await buildFileMap(config, root);
-    await buildSummary(config, root, promptScanResultHolder, projectMetadata);
-    // Persist prompt scan results if available
-    if (promptScanResultHolder) {
-        await savePromptScan(promptScanResultHolder, config, root);
-    }
-    // ==========================================================================
-    // Phase 5: Save File Hashes
-    // ==========================================================================
-    if (options.verbose) {
-        console.log('Phase 5: Saving file hashes...');
-    }
-    const fileHashes = await computeFileHashes(sourceFiles, root);
-    await saveHashes(fileHashes, config, root);
-    const duration = Date.now() - startTime;
-    const filesChanged = fileChanges
-        ? fileChanges.added.length + fileChanges.modified.length + fileChanges.removed.length
-        : sourceFiles.length;
-    if (options.verbose) {
-        console.log(`\nScan complete in ${duration}ms`);
-        console.log(`  Components: ${uniqueComponents.length}`);
-        console.log(`  Connections: ${uniqueConnections.length}`);
-        console.log(`  Files scanned: ${sourceFiles.length}`);
-        console.log(`  Files changed: ${filesChanged}`);
-        console.log(`  Warnings: ${allWarnings.length}`);
+    finally {
+        // Run 1.6 — item #4: release the scan lock on every exit path
+        // (success, early-return, throw). Idempotent.
+        lock.release();
     }
-    return {
-        components: uniqueComponents,
-        connections: uniqueConnections,
-        warnings: allWarnings,
-        fileChanges,
-        promptScan: promptScanResultHolder,
-        stats: {
-            scan_duration_ms: duration,
-            components_found: uniqueComponents.length,
-            connections_found: allConnections.length,
-            warnings_count: allWarnings.length,
-            files_scanned: sourceFiles.length,
-            files_changed: filesChanged,
-            prompts_found: promptScanResultHolder?.prompts.length,
-        },
-    };
 }
 /**
  * Quick scan - only packages, no code analysis
@@ -355,8 +1750,7 @@ export async function scanPromptsOnly(projectRoot, options = {}) {
     const result = await scanPrompts(root, {
         includeRawContent: true,
         detectVariables: true,
-        requireAPICallAnchor: true,
-        minCorroborationSignals: 2,
+        aggressive: true,
     });
     // Attach tracer data
     if (traceResult) {
@@ -372,6 +1766,88 @@ export async function scanPromptsOnly(projectRoot, options = {}) {
 export { formatPromptsOutput, formatPromptDetail } from './scanners/prompts/index.js';
 // Re-export tracer types
 export { traceLLMCalls } from './scanners/connections/llm-call-tracer.js';
+/**
+ * In-process debounce: tracks the timestamp of the last refresh ATTEMPT
+ * per resolved project root. If a second call arrives while a first is still
+ * in-flight (or was attempted within staleAfterMs), the second call returns
+ * {refreshed:false, reason:'fresh'} without dispatching a second scan.
+ *
+ * This prevents a polling loop on MCP `status` from fanning out N concurrent
+ * incremental scans. The map is module-scoped so it persists across calls
+ * within the same Node.js process lifetime.
+ */
+const _lastRefreshAttemptMs = new Map();
+export async function autoRefreshIfStale(projectRoot, options = {}) {
+    // Resolve opt-in / opt-out. Programmatic > env > default(true).
+    const envOptOut = process.env['NAVGATOR_AUTO_REFRESH'] === 'false';
+    const enabled = options.enabled ?? !envOptOut;
+    if (!enabled) {
+        return { refreshed: false, reason: 'disabled', message: 'auto-refresh disabled' };
+    }
+    const staleAfterMs = (options.staleAfterMinutes ?? 5) * 60 * 1000;
+    const root = projectRoot || process.cwd();
+    // Debounce: if a refresh was attempted for this root within staleAfterMs,
+    // return 'fresh' immediately rather than piling on a second scan.
+    // Stamp BEFORE any async work to close the race window — concurrent callers
+    // see the guard the moment the first call passes it.
+    const lastAttempt = _lastRefreshAttemptMs.get(root) ?? 0;
+    if (Date.now() - lastAttempt < staleAfterMs) {
+        return { refreshed: false, reason: 'fresh', message: 'refresh already in-flight or recently attempted' };
+    }
+    _lastRefreshAttemptMs.set(root, Date.now());
+    try {
+        const { loadIndex } = await import('./storage.js');
+        const config = getConfig();
+        const index = await loadIndex(config, root);
+        if (!index || !index.last_scan) {
+            return {
+                refreshed: false,
+                reason: 'no-index',
+                message: 'no prior scan — run `navgator scan` first',
+            };
+        }
+        const ageMs = Date.now() - index.last_scan;
+        if (ageMs < staleAfterMs) {
+            return {
+                refreshed: false,
+                reason: 'fresh',
+                message: `graph fresh (${Math.round(ageMs / 1000)}s old)`,
+            };
+        }
+        // Stale → run incremental. selectScanMode will pick the right mode
+        // internally; on a "no changes" hit it returns almost immediately.
+        const scanFn = options.scanImpl ?? scan;
+        const result = await scanFn(root, { mode: 'incremental' });
+        const changed = (result.fileChanges?.added.length ?? 0) +
+            (result.fileChanges?.modified.length ?? 0) +
+            (result.fileChanges?.removed.length ?? 0);
+        // Stamp coherence: this incremental scan covered every changed file via
+        // hashes, so the freshness ledger/stamp must be reconciled or the stamp
+        // would lie. Best-effort — never fail the refresh on freshness bookkeeping.
+        try {
+            const { reconcileClean } = await import('./freshness/drainer.js');
+            await reconcileClean(root);
+        }
+        catch {
+            /* freshness subsystem is optional; ignore */
+        }
+        return {
+            refreshed: true,
+            reason: 'stale',
+            filesChanged: changed,
+            message: changed > 0
+                ? `↻ refreshed ${changed} changed file(s)`
+                : '↻ refreshed (no file changes)',
+        };
+    }
+    catch (err) {
+        return {
+            refreshed: false,
+            reason: 'error',
+            message: `auto-refresh failed: ${err instanceof Error ? err.message : 'unknown'}`,
+        };
+    }
+}
 /**
  * Get scan status/summary without running a full scan
  */