klypix-mcp 1.59.0 → 1.61.0

package/README.md

@@ -79,7 +79,7 @@ npx klypix-mcp conformance
 
 It runs in a temporary fixture and touches nothing else. It checks tool discovery, task memory,
 truthful peer reporting, overlap surfacing, proactive logging, and in-band delivery of a peer note.
-It verifies 12 required coordination behaviours — not the 19 tools, and not the retrieval engine.
+It verifies 12 required coordination behaviours — not the 21 tools, and not the retrieval engine.
 
 ---
 
@@ -437,7 +437,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 
 ---
 
-## The 19 verbs
+## The 21 verbs
 
 | Tool | What it does |
 |---|---|
@@ -452,7 +452,9 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `brain_message` | Session-to-session coordination notes (24h TTL, never written into the brain) |
 | `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing |
 | `brain_connect` | Find and draw related-but-unlinked cards |
-| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context, with exact-path review proposals; Graphify artifacts are supported but never installed or run locally |
+| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context, with exact-path review proposals; external artifacts (e.g. Graphify) are supported but never installed or run locally |
+| `project_map_scan` | KLYPIX's own zero-install scanner: gitignore-aware file inventory + file-level import edges (relative, tsconfig-alias, and monorepo-workspace imports resolved) written to `klypix-map/graph.json` — which then serves `project_map_context` automatically |
+| `project_map_drift` | Read-only drift report: brain cards whose referenced files are gone or moved (with rename candidates), plus a headline when the checkout itself is behind its origin default branch |
 | `canvas_view` | Returns the board as a structured render spec plus a text summary, and declares an MCP Apps (SEP-1865) UI resource |
 | `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |
 | `search_canvases` | Search across canvases by name and content |

package/bin/klypix-install.mjs

@@ -293,7 +293,7 @@ try {
     // canvas-view-app.html is the canvas_view MCP App UI — staged raw (an HTML
     // file must never get a JS-comment banner) beside the flat server, which
     // resolves it via its ./canvas-view-app.html candidate path.
-    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'finding-routing.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'finding-routing.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
     for (const [src, dst] of [

package/bin/klypix-project-map.mjs

@@ -2,7 +2,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { discoverProjectGraph } from '../src/project-graph.mjs';
+import { discoverProjectGraph, scanNativeProjectMap, checkBrainDrift, brainDriftMarkdown } from '../src/project-graph.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const template = path.resolve(here, '..', 'examples', 'github', 'klypix-project-map.yml');
@@ -22,8 +22,11 @@ function usage() {
     'KLYPIX Project Map',
     '',
     '  klypix-project-map status [project]',
+    '  klypix-project-map scan [project]      native no-install map: file inventory + import edges -> klypix-map/graph.json',
+    '  klypix-project-map drift [project]     check brain cards\' file references against the repo\'s real files (read-only)',
     '  klypix-project-map setup-github [project] [--force]',
     '',
+    'scan writes only its own artifact (klypix-map/graph.json) inside the project; drift writes nothing.',
     'setup-github installs a read-only, pinned GitHub Actions workflow. It never installs or runs a provider on your computer.',
   ].join('\n'));
 }
@@ -42,6 +45,19 @@ try {
     console.log(`GitHub workflow: ${fs.existsSync(workflow) ? 'installed' : 'not installed'}`);
     process.exit(0);
   }
+  if (command === 'scan') {
+    const result = scanNativeProjectMap({ project: root });
+    console.log(`Project: ${result.projectRoot}`);
+    console.log(`Artifact: ${result.artifactRelative} (${result.viaGit ? 'gitignore-aware' : 'walk fallback'}${result.truncated ? ', TRUNCATED at file cap' : ''})`);
+    console.log(`Files: ${result.counts.files.toLocaleString()} | parsed code files: ${result.counts.parsedCodeFiles.toLocaleString()} | import edges: ${result.counts.importEdges.toLocaleString()}`);
+    console.log(`Workspace packages: ${result.counts.workspacePackages} | external packages: ${result.counts.externalPackages} | minified skipped: ${result.counts.skippedMinified}`);
+    process.exit(0);
+  }
+  if (command === 'drift') {
+    const result = await checkBrainDrift({ project: root });
+    console.log(brainDriftMarkdown(result));
+    process.exit(result.status === 'ready' ? 0 : 1);
+  }
   if (command !== 'setup-github') {
     usage();
     process.exit(1);

package/bin/klypix-worker.mjs

@@ -30,7 +30,7 @@ import {
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
   opBrainTaskContext,
 } from '../src/klypix-core.mjs';
-import { compareProjectGraphResults, projectGraphContextMarkdown, queryProjectGraph, suggestProjectGraphBrainLinks } from '../src/project-graph.mjs';
+import { compareProjectGraphResults, projectGraphContextMarkdown, queryProjectGraph, suggestProjectGraphBrainLinks, scanNativeProjectMap, checkBrainDrift, brainDriftMarkdown } from '../src/project-graph.mjs';
 import { auditProject, compactAgentsBrief, linkProject, mcpServerEntry } from '../src/agent-rules.mjs';
 import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS } from '../src/mcp-presence.mjs';
 import {
@@ -348,6 +348,39 @@ server.registerTool('project_map_context', {
   });
 });
 
+server.registerTool('project_map_scan', {
+  title: 'Scan the project natively - no-install file inventory + import map',
+  description: 'KLYPIX\'s own zero-install scanner: walks the repo (gitignore-aware, junk dirs like browser profiles and build output excluded), extracts FILE-LEVEL import edges for the JS/TS family (relative, tsconfig-alias, and monorepo-workspace imports resolved), and writes klypix-map/graph.json inside the project — the only thing it ever writes. The artifact then serves project_map_context automatically when no Graphify artifact exists. It deliberately does not build a per-symbol AST graph; deeper external artifacts remain importable through the same door.',
+  annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema: {
+    project: z.string().optional().describe('Absolute project root. Defaults to this MCP connection\'s configured project/vault.'),
+  },
+}, async ({ project }) => {
+  const root = typeof project === 'string' && project.trim() ? path.resolve(project.trim()) : path.resolve(mcpPresence.vault);
+  const result = scanNativeProjectMap({ project: root });
+  return toContent({
+    blocks: [{ kind: 'text', text: `Native project map written to \`${result.artifactRelative}\` (${result.viaGit ? 'gitignore-aware' : 'walk fallback'}${result.truncated ? '; TRUNCATED at the file cap' : ''}).\nFiles: ${result.counts.files.toLocaleString()}; parsed code files: ${result.counts.parsedCodeFiles.toLocaleString()}; import edges: ${result.counts.importEdges.toLocaleString()}; workspace packages: ${result.counts.workspacePackages}; minified skipped: ${result.counts.skippedMinified}.` }],
+    structured: result,
+  });
+});
+
+server.registerTool('project_map_drift', {
+  title: 'Check brain cards against the repo\'s real files (drift report)',
+  description: 'Read-only drift check: every brain card that references THIS project\'s files is verified against the working tree. Reports cards whose referenced files are gone or moved (with rename candidates by unique basename), and headlines when the checkout itself is behind its origin default branch — in that state a "missing" file may simply not be in this checkout. Slash-joined name enumerations and other-project paths are recognized and skipped, not reported as drift. Nothing is written; fix cards with a CORRECTION marker or by editing them in KLYPIX.',
+  annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema: {
+    project: z.string().optional().describe('Absolute project root. Defaults to this MCP connection\'s configured project/vault.'),
+    brain: z.string().optional().describe('Optional brain filename/path inside the project. Defaults to brain.klypix / brain.any.'),
+  },
+}, async ({ project, brain }) => {
+  const root = typeof project === 'string' && project.trim() ? path.resolve(project.trim()) : path.resolve(mcpPresence.vault);
+  const result = await checkBrainDrift({ project: root, brain });
+  return toContent({
+    blocks: [{ kind: 'text', text: brainDriftMarkdown(result) }],
+    structured: result,
+  });
+});
+
 server.registerTool('brain_challenge', {
   title: 'Challenge a decision against the brain (argue back with receipts)',
   description: 'BEFORE committing to a significant decision, ask the brain to ARGUE BACK: prior decisions that deterministically contradict the claim (correction-cue / opposite-polarity evidence — never mere topical similarity), 🛠 standing rules that dispute it, approaches tried before and REVERSED (with the correction/successor as the receipt), and open questions it collides with. Candidates, not verdicts — silence means "no deterministic contradiction signal", not verified consistency. Cards captured by a DIFFERENT agent are flagged so you coordinate instead of overriding. Dismiss a confirmed-false pair (after capturing the claim) with brain_connect pairs + relationship:"not_contradiction". Defaults to the project brain ("brain").',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.59.0",
+  "version": "1.61.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",

package/src/project-graph.mjs

@@ -1,11 +1,16 @@
-// Provider-neutral, read-only project-graph adapter.
+// Provider-neutral project-graph adapter, plus KLYPIX's own native scanner.
 //
-// Graphify is the first supported producer, but callers only see the stable
-// KLYPIX shape below. Generated graph artifacts remain disposable local cache:
-// this module never runs Graphify, edits source, or writes into brain.klypix.
+// Graphify is the first supported external producer, but callers only see the
+// stable KLYPIX shape below. Since 1.61.0 the module can also PRODUCE a map
+// itself — scanNativeProjectMap walks the repo and extracts file-level import
+// edges with zero third-party installs, writing only into its own artifact
+// dir (klypix-map/). Nothing here ever runs Graphify, edits source files, or
+// writes into brain.klypix.
 
 import fs from 'fs';
 import path from 'path';
+import { spawnSync } from 'child_process';
+import { parseKlypix } from './klypix-format.mjs';
 
 export const PROJECT_GRAPH_SCHEMA_VERSION = 2;
 export const DEFAULT_PROJECT_GRAPH = 'graphify-out/graph.json';
@@ -184,7 +189,16 @@ function cacheLimitBytes() {
 
 export function discoverProjectGraph({ project, graphPath } = {}) {
   const projectRoot = realRoot(project);
-  const filePath = resolveInsideProject(projectRoot, graphPath, DEFAULT_PROJECT_GRAPH);
+  // No explicit path: prefer the Graphify artifact for continuity, but fall
+  // back to KLYPIX's own native artifact so a no-install scan serves
+  // project_map_context with zero configuration.
+  let effectivePath = graphPath;
+  if (!graphPath) {
+    const graphifyDefault = path.resolve(projectRoot, DEFAULT_PROJECT_GRAPH);
+    const nativeDefault = path.resolve(projectRoot, NATIVE_MAP_ARTIFACT);
+    if (!fs.existsSync(graphifyDefault) && fs.existsSync(nativeDefault)) effectivePath = NATIVE_MAP_ARTIFACT;
+  }
+  const filePath = resolveInsideProject(projectRoot, effectivePath, DEFAULT_PROJECT_GRAPH);
   const artifactDir = path.dirname(filePath);
   const htmlPath = resolveInsideProject(projectRoot, path.join(artifactDir, 'graph.html'), DEFAULT_PROJECT_GRAPH_HTML);
   const reportPath = resolveInsideProject(projectRoot, path.join(artifactDir, 'GRAPH_REPORT.md'), DEFAULT_PROJECT_GRAPH_REPORT);
@@ -437,3 +451,449 @@ export function projectGraphContextMarkdown(result) {
 export function clearProjectGraphCache() {
   cache = null;
 }
+
+// ---------------------------------------------------------------------------
+// Native project map — the no-install scanner.
+//
+// Extracts exactly what the 2026-08-06 value evaluation proved useful: the
+// full file inventory plus FILE-LEVEL import edges (who imports whom). It
+// deliberately does NOT rebuild a per-symbol AST graph — that depth belongs to
+// external providers like Graphify, importable through the same artifact door.
+
+export const NATIVE_MAP_ARTIFACT = 'klypix-map/graph.json';
+
+const SCAN_MAX_FILES = 20_000;
+const SCAN_MAX_PARSE_BYTES = 2 * 1024 * 1024;
+const CODE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts']);
+const INVENTORY_EXTENSIONS = new Set([
+  ...CODE_EXTENSIONS,
+  '.json', '.md', '.mdx', '.yml', '.yaml', '.toml', '.css', '.scss', '.html', '.sql',
+  '.py', '.rs', '.go', '.swift', '.kt', '.java', '.rb', '.sh', '.ps1', '.vue', '.svelte',
+]);
+// Junk that polluted the 2026-08-06 field graph (browser profiles, worktrees,
+// build output) — excluded even when a repo forgets to gitignore it.
+const SCAN_EXCLUDED_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'dist-electron', 'build', 'release', 'out', 'coverage',
+  '.next', '.turbo', '.cache', 'tmp', '.worktrees', '.codex-artifacts', '.codex-tmp',
+  'graphify-out', 'klypix-map', '__pycache__', '.venv', 'venv',
+]);
+
+function runGit(root, args) {
+  try {
+    const result = spawnSync('git', args, { cwd: root, encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0) return null;
+    return result.stdout;
+  } catch { return null; }
+}
+
+function excludedByDir(rel) {
+  return rel.split('/').some(segment => SCAN_EXCLUDED_DIRS.has(segment.toLocaleLowerCase('en-US')));
+}
+
+function walkInventoryFallback(root) {
+  const out = [];
+  const queue = ['.'];
+  while (queue.length && out.length < SCAN_MAX_FILES) {
+    const relDir = queue.shift();
+    let entries;
+    try { entries = fs.readdirSync(path.join(root, relDir), { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const rel = relDir === '.' ? entry.name : `${relDir}/${entry.name}`;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        if (!SCAN_EXCLUDED_DIRS.has(entry.name.toLocaleLowerCase('en-US'))) queue.push(rel);
+      } else if (entry.isFile()) {
+        out.push(rel);
+        if (out.length >= SCAN_MAX_FILES) break;
+      }
+    }
+  }
+  return out;
+}
+
+function listScanInventory(root) {
+  // git ls-files (tracked + untracked-not-ignored) honors .gitignore and is the
+  // authoritative "what belongs to this project" answer; the manual walk is the
+  // no-git fallback. Both still pass the junk-dir filter — field evidence
+  // showed repos forget to ignore browser profiles and build drops.
+  const gitOut = runGit(root, ['ls-files', '--cached', '--others', '--exclude-standard', '-z']);
+  const rawList = gitOut != null
+    ? gitOut.split('\0').filter(Boolean).map(entry => entry.replace(/\\/g, '/'))
+    : walkInventoryFallback(root);
+  const files = [];
+  let truncated = false;
+  for (const rel of rawList) {
+    if (excludedByDir(rel)) continue;
+    const extension = path.extname(rel).toLocaleLowerCase('en-US');
+    if (!INVENTORY_EXTENSIONS.has(extension)) continue;
+    if (files.length >= SCAN_MAX_FILES) { truncated = true; break; }
+    files.push(rel);
+  }
+  files.sort();
+  return { files, truncated, viaGit: gitOut != null };
+}
+
+function looksMinified(root, rel, sizeBytes) {
+  const base = path.basename(rel).toLocaleLowerCase('en-US');
+  if (base.includes('.min.')) return true;
+  if (sizeBytes < 50 * 1024) return false;
+  try {
+    const fd = fs.openSync(path.join(root, rel), 'r');
+    const buf = Buffer.alloc(4096);
+    const read = fs.readSync(fd, buf, 0, 4096, 0);
+    fs.closeSync(fd);
+    const sample = buf.toString('utf8', 0, read);
+    const firstNewline = sample.indexOf('\n');
+    return firstNewline === -1 || firstNewline > 2000;
+  } catch { return false; }
+}
+
+const IMPORT_PATTERNS = [
+  /(?:^|[^\w$.])import\s+(?:[\w$*{},\s]+?from\s+)?['"]([^'"\n]+)['"]/gm,
+  /(?:^|[^\w$.])export\s+[\w$*{},\s]*?from\s+['"]([^'"\n]+)['"]/gm,
+  /(?:^|[^\w$.])require\(\s*['"]([^'"\n]+)['"]\s*\)/g,
+  /(?:^|[^\w$.])import\(\s*['"]([^'"\n]+)['"]\s*\)/g,
+];
+
+function extractImportSpecifiers(source) {
+  const specifiers = new Set();
+  for (const pattern of IMPORT_PATTERNS) {
+    pattern.lastIndex = 0;
+    for (const match of source.matchAll(pattern)) specifiers.add(match[1]);
+  }
+  return [...specifiers];
+}
+
+const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json'];
+
+function tryResolveFile(candidate, fileSet) {
+  const normal = candidate.replace(/\\/g, '/').replace(/\/{2,}/g, '/').replace(/^\.\//, '');
+  if (fileSet.has(normal)) return normal;
+  for (const extension of RESOLVE_EXTENSIONS) {
+    if (fileSet.has(normal + extension)) return normal + extension;
+  }
+  for (const extension of RESOLVE_EXTENSIONS) {
+    if (fileSet.has(`${normal}/index${extension}`)) return `${normal}/index${extension}`;
+  }
+  return null;
+}
+
+function collectWorkspacePackages(root, files) {
+  const packages = new Map();
+  for (const rel of files) {
+    if (path.basename(rel) !== 'package.json') continue;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+      const name = typeof parsed?.name === 'string' ? parsed.name.trim() : '';
+      if (name && !packages.has(name)) packages.set(name, path.dirname(rel).replace(/^\.$/, ''));
+    } catch { /* unparseable package.json is not an error for the scan */ }
+  }
+  return packages;
+}
+
+// Per-package alias scopes: in a monorepo every package can carry its own
+// tsconfig `paths` (typically `@/*` -> `./src/*`), scoped to files under that
+// package's directory. A root-only reading resolved 0 of a field repo's 56
+// `@/lib/utils` importers; nearest-tsconfig scoping resolves them all.
+function collectTsconfigAliasScopes(root, files) {
+  const scopes = [];
+  for (const rel of files) {
+    if (path.basename(rel) !== 'tsconfig.json') continue;
+    const dir = path.dirname(rel).replace(/^\.$/, '');
+    try {
+      const raw = fs.readFileSync(path.join(root, rel), 'utf8')
+        .replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
+        .replace(/,\s*([}\]])/g, '$1');
+      const parsed = JSON.parse(raw);
+      const paths = parsed?.compilerOptions?.paths || {};
+      const baseUrl = String(parsed?.compilerOptions?.baseUrl || '.').replace(/^\.\//, '').replace(/^\.$/, '');
+      const aliases = [];
+      for (const [pattern, targets] of Object.entries(paths)) {
+        if (!pattern.endsWith('/*') || !Array.isArray(targets) || !targets.length) continue;
+        const target = String(targets[0]);
+        if (!target.endsWith('/*')) continue;
+        const prefix = pattern.slice(0, -1);
+        const replacement = [dir, baseUrl, target.slice(0, -1).replace(/^\.\//, '')]
+          .filter(Boolean).join('/').replace(/\/{2,}/g, '/');
+        aliases.push({ prefix, replacement });
+      }
+      if (aliases.length) scopes.push({ dir, aliases });
+    } catch { /* unparseable tsconfig — that scope stays alias-free */ }
+  }
+  // Longest directory first so the nearest enclosing tsconfig wins.
+  scopes.sort((a, b) => b.dir.length - a.dir.length);
+  return scopes;
+}
+
+function aliasesForFile(fromRel, scopes) {
+  const normal = fromRel.replace(/\\/g, '/');
+  for (const scope of scopes) {
+    if (!scope.dir || normal.startsWith(`${scope.dir}/`)) return scope.aliases;
+  }
+  return [];
+}
+
+function resolveImport(fromRel, specifier, fileSet, workspaces, aliasScopes) {
+  if (!specifier || specifier.startsWith('node:') || specifier.startsWith('data:')) return null;
+  if (specifier.startsWith('.')) {
+    const joined = path.posix.join(path.posix.dirname(fromRel.replace(/\\/g, '/')), specifier);
+    if (joined.startsWith('..')) return null;
+    return tryResolveFile(joined, fileSet);
+  }
+  for (const alias of aliasesForFile(fromRel, aliasScopes)) {
+    if (specifier.startsWith(alias.prefix)) {
+      return tryResolveFile(`${alias.replacement}${specifier.slice(alias.prefix.length)}`, fileSet);
+    }
+  }
+  for (const [name, dir] of workspaces) {
+    if (specifier === name) {
+      return tryResolveFile(`${dir}/src/index`, fileSet)
+        || tryResolveFile(`${dir}/index`, fileSet)
+        || (fileSet.has(`${dir}/package.json`) ? `${dir}/package.json` : null);
+    }
+    if (specifier.startsWith(`${name}/`)) {
+      const sub = `${dir}/${specifier.slice(name.length + 1)}`;
+      return tryResolveFile(sub, fileSet) || tryResolveFile(`${dir}/src/${specifier.slice(name.length + 1)}`, fileSet);
+    }
+  }
+  return null;
+}
+
+/**
+ * Scan the project natively: full file inventory + file-level import edges.
+ * Writes klypix-map/graph.json (NetworkX node-link, the same shape external
+ * providers use) unless write:false. The artifact is disposable local cache.
+ */
+export function scanNativeProjectMap({ project, write = true } = {}) {
+  const projectRoot = realRoot(project);
+  const inventory = listScanInventory(projectRoot);
+  const fileSet = new Set(inventory.files);
+  const workspaces = collectWorkspacePackages(projectRoot, inventory.files);
+  const aliasScopes = collectTsconfigAliasScopes(projectRoot, inventory.files);
+
+  const links = [];
+  const externals = new Map();
+  let parsedFiles = 0;
+  let skippedMinified = 0;
+  for (const rel of inventory.files) {
+    if (!CODE_EXTENSIONS.has(path.extname(rel).toLocaleLowerCase('en-US'))) continue;
+    let stat;
+    try { stat = fs.statSync(path.join(projectRoot, rel)); } catch { continue; }
+    if (stat.size > SCAN_MAX_PARSE_BYTES) continue;
+    if (looksMinified(projectRoot, rel, stat.size)) { skippedMinified++; continue; }
+    let source;
+    try { source = fs.readFileSync(path.join(projectRoot, rel), 'utf8'); } catch { continue; }
+    parsedFiles++;
+    for (const specifier of extractImportSpecifiers(source)) {
+      const resolved = resolveImport(rel, specifier, fileSet, workspaces, aliasScopes);
+      if (resolved && resolved !== rel) {
+        links.push({ source: rel, target: resolved, relation: 'imports', confidence: 'EXTRACTED' });
+      } else if (!resolved && !specifier.startsWith('.')) {
+        const packageName = specifier.startsWith('@')
+          ? specifier.split('/').slice(0, 2).join('/')
+          : specifier.split('/')[0];
+        externals.set(packageName, (externals.get(packageName) || 0) + 1);
+      }
+    }
+  }
+
+  const nodes = inventory.files.map(rel => ({
+    id: rel,
+    label: path.basename(rel),
+    file_type: 'code',
+    source_file: rel,
+  }));
+  const artifact = {
+    directed: true,
+    multigraph: false,
+    graph: {
+      generator: 'klypix-native-map',
+      schema_version: 1,
+      generated_at: new Date().toISOString(),
+      via_git: inventory.viaGit,
+      truncated: inventory.truncated,
+      external_packages: [...externals.entries()].sort((a, b) => b[1] - a[1]).slice(0, 40)
+        .map(([name, count]) => ({ name, imports: count })),
+    },
+    nodes,
+    links,
+  };
+
+  let artifactPath = null;
+  if (write) {
+    const dir = path.join(projectRoot, path.dirname(NATIVE_MAP_ARTIFACT));
+    fs.mkdirSync(dir, { recursive: true });
+    artifactPath = path.join(projectRoot, ...NATIVE_MAP_ARTIFACT.split('/'));
+    const temporary = `${artifactPath}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(artifact));
+    fs.renameSync(temporary, artifactPath);
+    clearProjectGraphCache();
+  }
+
+  return {
+    status: 'ready',
+    projectRoot,
+    artifactPath,
+    artifactRelative: write ? NATIVE_MAP_ARTIFACT : null,
+    counts: {
+      files: inventory.files.length,
+      parsedCodeFiles: parsedFiles,
+      importEdges: links.length,
+      workspacePackages: workspaces.size,
+      externalPackages: externals.size,
+      skippedMinified,
+    },
+    truncated: inventory.truncated,
+    viaGit: inventory.viaGit,
+    graph: write ? null : artifact,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Brain drift — check brain cards' file references against repo reality.
+//
+// Field-derived false-positive taxonomy (2026-08-06 adversarial run) is baked
+// in: slash-joined enumerations are rejected, refs that resolve nowhere near
+// this project are treated as another repo's mentions and skipped, and a
+// checkout that is behind its origin default branch is reported as its own
+// headline instead of blaming the cards.
+
+const DRIFT_REF_PATTERN = /[A-Za-z0-9_@](?:[A-Za-z0-9_.@-]|[\\/])*\.[A-Za-z0-9]{1,8}/g;
+const DRIFT_TAG_PATTERN = /#file-([a-z0-9-]+)/g;
+
+function slugifyStem(basename) {
+  return basename.replace(/\.[^.]+$/, '').toLocaleLowerCase('en-US')
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+function isEnumerationToken(token) {
+  // "AGENTS.md/.cursor/.windsurf" — a NON-final segment carrying a file
+  // extension means this is a prose list of names, not one path.
+  const segments = token.split('/');
+  return segments.slice(0, -1).some(segment => /\.[A-Za-z0-9]{1,8}$/.test(segment) && segment !== '.' && segment !== '..');
+}
+
+function driftRefsFromText(text) {
+  const refs = new Set();
+  for (const match of String(text || '').matchAll(DRIFT_REF_PATTERN)) {
+    const token = match[0].replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!token.includes('/')) continue;
+    if (/^[A-Za-z]:\//.test(token) || token.startsWith('http') || token.startsWith('//')) continue;
+    if (isEnumerationToken(token)) continue;
+    refs.add(token);
+  }
+  return [...refs];
+}
+
+function checkoutStaleness(root) {
+  const head = runGit(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const defaultRef = runGit(root, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+  const target = (defaultRef || '').trim() || ['origin/main', 'origin/master']
+    .find(ref => runGit(root, ['rev-parse', '--verify', '--quiet', ref]) != null);
+  if (!target) return null;
+  const behindRaw = runGit(root, ['rev-list', '--count', `HEAD..${target}`]);
+  const behind = Number((behindRaw || '').trim());
+  if (!Number.isFinite(behind)) return null;
+  return { branch: (head || '').trim() || null, comparedTo: target, behind };
+}
+
+/**
+ * Check every text card in the project brain against the repo's real files.
+ * Read-only: never writes to the brain or the repo.
+ */
+export async function checkBrainDrift({ project, brain } = {}) {
+  const projectRoot = realRoot(project);
+  const brainPath = brain
+    ? path.resolve(projectRoot, brain)
+    : ['brain.klypix', 'brain.any'].map(name => path.join(projectRoot, name)).find(file => fs.existsSync(file));
+  if (!brainPath || !fs.existsSync(brainPath)) {
+    return { status: 'no-brain', projectRoot, brainPath: brainPath || null, cards: [], summary: null, staleCheckout: null };
+  }
+  const parsed = await parseKlypix(fs.readFileSync(brainPath));
+  const cards = Array.isArray(parsed?.struct?.cards) ? parsed.struct.cards : [];
+
+  const inventory = listScanInventory(projectRoot);
+  const fileSet = new Set(inventory.files);
+  const byBasename = new Map();
+  const bySlug = new Map();
+  const rootEntries = new Set(fs.readdirSync(projectRoot).map(entry => entry.toLocaleLowerCase('en-US')));
+  for (const file of inventory.files) {
+    const basename = path.basename(file).toLocaleLowerCase('en-US');
+    byBasename.set(basename, [...(byBasename.get(basename) || []), file]);
+    const slug = slugifyStem(basename);
+    if (slug) bySlug.set(slug, [...(bySlug.get(slug) || []), file]);
+  }
+
+  const drifted = [];
+  let cardsWithRefs = 0;
+  let refsOk = 0;
+  let refsChecked = 0;
+  for (const card of cards) {
+    const text = card?.text || '';
+    if (!text) continue;
+    const findings = [];
+    const refs = driftRefsFromText(text);
+    let sawCheckable = false;
+    for (const ref of refs) {
+      const lower = ref.toLocaleLowerCase('en-US');
+      const firstSegment = lower.split('/')[0];
+      const inRepoShape = fileSet.has(ref) || fileSet.has(lower) || rootEntries.has(firstSegment);
+      if (!inRepoShape) continue; // likely another project's path — not our claim to judge
+      sawCheckable = true;
+      refsChecked++;
+      if (fileSet.has(ref) || fileSet.has(lower) || fs.existsSync(path.join(projectRoot, ref))) { refsOk++; continue; }
+      const movedTo = (byBasename.get(path.basename(lower)) || []).slice(0, 3);
+      findings.push({ ref, status: movedTo.length ? 'moved' : 'missing', movedTo });
+    }
+    for (const match of text.matchAll(DRIFT_TAG_PATTERN)) {
+      const candidates = bySlug.get(match[1]);
+      if (candidates?.length === 1) { sawCheckable = true; refsChecked++; refsOk++; }
+    }
+    if (sawCheckable) cardsWithRefs++;
+    if (findings.length) {
+      drifted.push({
+        id: card.id || null,
+        area: card.area || null,
+        preview: shortString(text, 120),
+        findings,
+      });
+    }
+  }
+
+  return {
+    status: 'ready',
+    projectRoot,
+    brainPath,
+    staleCheckout: checkoutStaleness(projectRoot),
+    summary: {
+      cards: cards.length,
+      cardsWithCheckableRefs: cardsWithRefs,
+      refsChecked,
+      refsOk,
+      driftedCards: drifted.length,
+    },
+    cards: drifted,
+  };
+}
+
+export function brainDriftMarkdown(result) {
+  if (result.status === 'no-brain') {
+    return '# Brain drift\n\nNo brain.klypix found in this project — nothing to check.';
+  }
+  const lines = ['# Brain drift — cards vs the repo\'s real files'];
+  const stale = result.staleCheckout;
+  if (stale && stale.behind > 0) {
+    lines.push(`⚠️ **This checkout is ${stale.behind} commit(s) behind \`${stale.comparedTo}\`** (branch \`${stale.branch || '?'}\`, as of the last fetch). Files reported missing below may simply not be in THIS checkout — pull before trusting the card verdicts.`);
+  }
+  const s = result.summary;
+  lines.push(`Checked ${s.cards} card(s); ${s.cardsWithCheckableRefs} referenced this repo's files (${s.refsChecked} reference(s), ${s.refsOk} still valid). **${s.driftedCards} card(s) reference files that are gone or moved.**`);
+  for (const card of result.cards.slice(0, 40)) {
+    lines.push(`- ${card.area ? `[${card.area}] ` : ''}${card.preview}`);
+    for (const finding of card.findings.slice(0, 4)) {
+      lines.push(`  - \`${finding.ref}\` — ${finding.status}${finding.movedTo.length ? `; probably now: ${finding.movedTo.map(f => `\`${f}\``).join(', ')}` : ''}`);
+    }
+  }
+  if (result.cards.length > 40) lines.push(`…and ${result.cards.length - 40} more drifted card(s).`);
+  lines.push('_Read-only report. Fix cards with a CORRECTION marker or edit them in KLYPIX; nothing was changed automatically._');
+  return lines.join('\n');
+}