vibe-splain 3.4.0 → 3.4.2

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <strong>◈ VIBE-SPLAIN</strong>
+  <strong>◈ vibe-splain</strong>
   <br />
   <em>Map architectural DNA and behavioral call-chains in complex codebases.</em>
 </p>
@@ -14,13 +14,13 @@
 
 ---
 
-VIBE-SPLAIN is a high-fidelity **static analysis engine** and MCP server. It uses [Tree-Sitter](https://tree-sitter.github.io/tree-sitter/) to extract the structural and behavioral patterns of a codebase—identifying high-gravity components, mapping semantic actions, and tracing call-chains between entrypoints and side effects.
+vibe-splain is a high-fidelity **static analysis engine** and MCP server. It uses [Tree-Sitter](https://tree-sitter.github.io/tree-sitter/) to extract the structural and behavioral patterns of a codebase—identifying high-gravity components, mapping semantic actions, and tracing call-chains between entrypoints and side effects.
 
-While VIBE-SPLAIN is built on a language-agnostic foundation, the current toolset is **highly optimized for TypeScript and JavaScript** (especially Next.js, Prisma, and tRPC environments).
+While vibe-splain is built on a language-agnostic foundation, the current toolset is **highly optimized for TypeScript and JavaScript** (especially Next.js, Prisma, and tRPC environments).
 
 **Zero LLM calls. Zero API keys. Pure static analysis.**
 
-Your coding agent does all the thinking — VIBE-SPLAIN just gives it the right data.
+Your coding agent does all the thinking — vibe-splain just gives it the right data.
 
 ## Install
 
@@ -28,17 +28,17 @@ Your coding agent does all the thinking — VIBE-SPLAIN just gives it the right
 npx vibe-splain install
 ```
 
-That's it. This patches your coding agent's MCP config so it can call VIBE-SPLAIN's tools. Restart your agent.
+That's it. This patches your coding agent's MCP config so it can call vibe-splain's tools. Restart your agent.
 
 ### Running the Analysis
 
-You don't need to write a complex prompt. VIBE-SPLAIN provides a built-in MCP Prompt called `build_dossier` that automatically tells your agent exactly what to do.
+You don't need to write a complex prompt. vibe-splain provides a built-in MCP Prompt called `build_dossier` that automatically tells your agent exactly what to do.
 
 **In Claude Code / Gemini CLI:**
 Type `/prompt build_dossier` and press enter.
 
 **In Cursor / Windsurf:**
-Open the MCP panel or agent chat, select the `build_dossier` prompt from the VIBE-SPLAIN server, and run it.
+Open the MCP panel or agent chat, select the `build_dossier` prompt from the vibe-splain server, and run it.
 
 Your agent will loop through the high-gravity files, analyze each one, and build an **Architectural Dossier** — a structured set of **Decision Cards** explaining the technical rationale of the code.
 
@@ -71,22 +71,27 @@ Your agent will loop through the high-gravity files, analyze each one, and build
 ```
 
 ### Three Levels of Analysis
-
 1. **Level 0 — Semantic Classification**: Maps files to architectural "pillars" (Auth, Payments, Database, etc.) using import-path heuristics and library signatures.
+2. **Level 1 — Structural and Behavioral Gravity**: Core computes `staticGravity` using Tree-Sitter AST analysis based on link density, nesting depth, and mutation counts. **Bundled Adapters** (like Cal.com and n8n) interpret product semantics to add `behavioralLift` for critical dynamic execution paths. Final `gravity` is the combination of static evidence and adapter interpretation.
+3. **Level 2 — Behavioral Traceability**: Tree-Sitter powered call-graph analysis. It maps function-level dependencies and identifies **Critical Functions** (entrypoints, semantic actions, or high-outbound callers).
+
+### Claude Code PreToolUse Hook
 
-2. **Level 1 — Cognitive Complexity**: Tree-Sitter AST analysis computes a complexity score per file based on link density, nesting depth, and mutation counts. Files scoring ≥ 15 are identified as **High-Gravity**.
+`vibe-splain` integrates directly with Claude Code's hook system to prevent AI agents from accidentally breaking your codebase:
 
-3. **Level 2 — Behavioral Traceability**: Tree-Sitter powered call-graph analysis. It maps function-level dependencies and identifies **Critical Functions** (entrypoints, semantic actions, or high-outbound callers) so your agent can trace the exact ripple effect of a code change.
+- **Ultra-Fast Local Gating**: Installs a standalone entrypoint (`dist/hook.js`) that runs in **< 15ms** with zero network calls, avoiding heavy WASM/tree-sitter load overhead.
+- **Hybrid Blast-Radius Logic**: Combines static gravity and substance-based direct dependents to protect important files (e.g. dynamically-loaded execution nodes or central utility modules) even if they lack standard entrypoints.
+- **Developer Friction Suppression**: Automatically demotes generated, minified, or vendored files to a `low` blast-radius, ensuring the agent is never blocked when editing build targets or lockfiles.
+- **Warn-Once session behavior**: If `.vibe-splainer/gate.json` is missing, the hook notifies you exactly once per session to run a project scan, then gracefully gets out of the way.
 
 ## MCP Tools
 
-VIBE-SPLAIN exposes **8 tools** over MCP stdio:
+vibe-splain exposes **8 tools** over MCP stdio:
 
 | Tool | Purpose |
 |------|---------|
 | `scan_project` | **Call first.** Scans the codebase, returns high-gravity files grouped by pillar. Starts file watcher. |
 | `get_file_context` | Returns full source + import graph neighbors for a specific file. |
-| `get_call_chain` | **New.** Traces function-level call chains (upstream/downstream) to map behavior paths. |
 | `write_decision_card` | Persists a Decision Card (narrative + evidence + optional Mermaid diagram). |
 | `get_strategic_overview` | Returns dossier state without evidence snippets (saves tokens). |
 | `inspect_pillar` | Returns all Decision Cards for a pillar with full evidence. |
@@ -98,8 +103,7 @@ VIBE-SPLAIN exposes **8 tools** over MCP stdio:
 ```
 1. scan_project → get high-gravity files
 2. For each file: get_file_context → read source + neighbors
-3. Trace: use get_call_chain to see what calls what
-4. Synthesize: "WHY does this code exist?"
+3. Synthesize: "WHY does this code exist?"
 5. write_decision_card → persist the narrative
 6. Share the file:// UI link with the user
 ```
@@ -107,10 +111,10 @@ VIBE-SPLAIN exposes **8 tools** over MCP stdio:
 ## How It Works
 
 ### Deep Analysis Pipeline
-Unlike simple regex scanners, VIBE-SPLAIN runs a deterministic **13-stage pipeline**—from AST inventory and alias resolution to semantic classification and function-level scoring—to ensure every Decision Card is grounded in actual code paths.
+Unlike simple regex scanners, vibe-splain runs a deterministic **13-stage pipeline**—from AST inventory and alias resolution to semantic classification and function-level scoring—to ensure every Decision Card is grounded in actual code paths.
 
 ### Semantic Rulesets
-VIBE-SPLAIN uses specialized rulesets to understand framework-specific semantics. Current optimizations include:
+vibe-splain uses specialized rulesets to understand framework-specific semantics. Current optimizations include:
 - **Next.js**: Server Actions, `cookies()`, `headers()`, and App Router conventions.
 - **Database**: Prisma model mutations and raw query patterns.
 - **API**: tRPC procedure calls (`mutate`/`query`) and standard `fetch`/`axios` patterns.
@@ -137,9 +141,11 @@ The UI features:
 
 ```
 packages/
-├── brain/           # @vibe-splain/brain — analysis engine
+├── brain/           # @vibe-splain/brain — repo-agnostic analysis core + bundled adapters
 │   └── src/
-│       ├── scanner.ts    # Tree-Sitter AST analysis (L0 + L1 + L2)
+│       ├── pipeline/
+│       │   └── adapters/ # Bundled product adapters (Cal.com, n8n)
+│       ├── scanner.ts    # Tree-Sitter AST analysis (static analysis, graph building)
 │       ├── dossier.ts    # Atomic persistence + UI regeneration
 │       ├── graph.ts      # Import graph read/write
 │       └── watcher.ts    # Chokidar file watcher
@@ -161,7 +167,7 @@ packages/
 
 ### Key Design Decisions
 
-- **No LLM calls**: VIBE-SPLAIN is a pure static analysis tool. The coding agent provides all synthesis.
+- **No LLM calls**: vibe-splain is a pure static analysis tool. The coding agent provides all synthesis.
 - **`async-mutex`**: All dossier writes are guarded by a mutex with atomic tmp+rename.
 - **`startOnLoad: false`**: Mermaid is initialized manually — never auto-scans the DOM.
 - **`base: './'`**: Vite builds with relative paths so the UI works from `file://` URLs.

package/dist/commands/hook.d.ts

@@ -0,0 +1,9 @@
+export interface HookCommandResult {
+    /** JSON to print to stdout, or null to print nothing (defer / exit 0). */
+    stdout: string | null;
+}
+export declare function findProjectRoot(start: string | undefined): string | null;
+/** Pure-ish core: raw stdin string in, hook decision (as a string or null) out. */
+export declare function runHookCommand(rawStdin: string): Promise<HookCommandResult>;
+/** CLI entrypoint: read all of stdin, run the gate, emit the result. */
+export declare function hookPreToolUseCommand(): Promise<void>;

package/dist/commands/hook.js

@@ -0,0 +1,84 @@
+// `vibe-splain hook pretooluse` — the deterministic PreToolUse gate, wired to stdio.
+//
+// Claude Code pipes a JSON describing the tool call about to run onto stdin; we
+// decide whether to escalate and, if so, write hook JSON to stdout. On a safe
+// edit (or any non-edit tool, unscanned repo, etc.) we print nothing and exit 0,
+// deferring to normal permission flow.
+//
+// NOTE on the console.log ban: that rule protects the MCP *server's* stdout.
+// This is a separate, short-lived process whose stdout IS the hook protocol —
+// writing JSON here is correct. Diagnostics still go to stderr.
+import { existsSync, writeFileSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { tmpdir } from 'os';
+import { decidePreToolUse } from '../hook/preToolUse.js';
+// Walk up from `start` looking for the directory that holds a `.vibe-splainer` scan.
+// Returns null if none is found — an unscanned repo means the gate is inert.
+export function findProjectRoot(start) {
+    let dir = start || process.cwd();
+    // Bound the walk so a stray cwd can't traverse the whole filesystem.
+    for (let i = 0; i < 64; i++) {
+        if (existsSync(join(dir, '.vibe-splainer', 'analysis.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Pure-ish core: raw stdin string in, hook decision (as a string or null) out. */
+export async function runHookCommand(rawStdin) {
+    let input;
+    try {
+        input = JSON.parse(rawStdin);
+    }
+    catch {
+        return { stdout: null }; // malformed input → never block the agent
+    }
+    const root = findProjectRoot(input.cwd);
+    const gatePath = root ? join(root, '.vibe-splainer', 'gate.json') : null;
+    const gateExists = gatePath ? existsSync(gatePath) : false;
+    let gateIndex = null;
+    if (gateExists) {
+        try {
+            gateIndex = JSON.parse(readFileSync(gatePath, 'utf8'));
+        }
+        catch { }
+    }
+    const sessionId = input.session_id || 'default';
+    const warnFile = join(tmpdir(), `vibe-splain-warn-${sessionId}`);
+    const warningShown = existsSync(warnFile);
+    const result = decidePreToolUse(input, gateIndex, { warningShown });
+    if (result.action === 'defer')
+        return { stdout: null };
+    if (!gateIndex && result.action === 'emit') {
+        try {
+            writeFileSync(warnFile, '1');
+        }
+        catch { }
+    }
+    return { stdout: JSON.stringify(result.output) };
+}
+/** CLI entrypoint: read all of stdin, run the gate, emit the result. */
+export async function hookPreToolUseCommand() {
+    const raw = await readStdin();
+    const { stdout } = await runHookCommand(raw);
+    if (stdout)
+        process.stdout.write(stdout);
+    // No stdout on defer; exit code stays 0.
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        if (process.stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(data));
+    });
+}
+//# sourceMappingURL=hook.js.map

package/dist/commands/install.d.ts

@@ -1 +1,6 @@
+/**
+ * Idempotently register the vibe-splain PreToolUse hook in a Claude Code settings object.
+ * Pure: takes a config, returns the same object mutated. Safe to run repeatedly.
+ */
+export declare function addPreToolUseHook(config: Record<string, any>, hookPath?: string): Record<string, any>;
 export declare function installCommand(): Promise<void>;

package/dist/commands/install.js

@@ -1,7 +1,8 @@
 import { readFile, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { join } from 'path';
+import { join, dirname } from 'path';
 import { homedir } from 'os';
+import { fileURLToPath } from 'url';
 function expandPath(p) {
     if (p.startsWith('~')) {
         return join(homedir(), p.slice(1));
@@ -24,8 +25,48 @@ const MCP_ENTRY = {
     command: 'npx',
     args: ['-y', 'vibe-splain', 'serve'],
 };
+// Claude Code PreToolUse hook: deterministically gate edits to high-blast-radius
+// files. Hooks are a Claude Code CLI feature (settings.json) — not Desktop/Cursor.
+const HOOK_MATCHER = 'Edit|Write|MultiEdit';
+const DEFAULT_HOOK_COMMAND = 'npx -y vibe-splain hook pretooluse';
+/**
+ * Idempotently register the vibe-splain PreToolUse hook in a Claude Code settings object.
+ * Pure: takes a config, returns the same object mutated. Safe to run repeatedly.
+ */
+export function addPreToolUseHook(config, hookPath) {
+    if (!config.hooks)
+        config.hooks = {};
+    if (!Array.isArray(config.hooks.PreToolUse))
+        config.hooks.PreToolUse = [];
+    const hookCommand = hookPath ? `node "${hookPath}"` : DEFAULT_HOOK_COMMAND;
+    const already = config.hooks.PreToolUse.some((entry) => Array.isArray(entry?.hooks) &&
+        entry.hooks.some((h) => typeof h?.command === 'string' && (h.command.includes('vibe-splain hook pretooluse') || h.command.includes('hook.js'))));
+    if (already) {
+        // Update existing hook command to the resolved hook.js path
+        config.hooks.PreToolUse = config.hooks.PreToolUse.map((entry) => {
+            if (Array.isArray(entry?.hooks)) {
+                return {
+                    ...entry,
+                    hooks: entry.hooks.map((h) => {
+                        if (typeof h?.command === 'string' && (h.command.includes('vibe-splain hook pretooluse') || h.command.includes('hook.js'))) {
+                            return { ...h, command: hookCommand };
+                        }
+                        return h;
+                    })
+                };
+            }
+            return entry;
+        });
+        return config;
+    }
+    config.hooks.PreToolUse.push({
+        matcher: HOOK_MATCHER,
+        hooks: [{ type: 'command', command: hookCommand }],
+    });
+    return config;
+}
 export async function installCommand() {
-    console.error('\n🔧 VIBE-SPLAIN Installer\n');
+    console.error('\n🔧 vibe-splain Installer\n');
     let patchedCount = 0;
     for (const agent of AGENT_CONFIGS) {
         const resolvedPath = expandPath(agent.path);
@@ -43,17 +84,25 @@ export async function installCommand() {
                 console.error(`    ⚠ Could not parse JSON, skipping`);
                 continue;
             }
-            // Check idempotency
-            if (config.mcpServers?.['vibe-splain']) {
+            // Patch config (idempotent: only write when something actually changes,
+            // so existing users still pick up newly-added pieces like the hook).
+            const before = JSON.stringify(config);
+            if (!config.mcpServers)
+                config.mcpServers = {};
+            if (!config.mcpServers['vibe-splain'])
+                config.mcpServers['vibe-splain'] = MCP_ENTRY;
+            // The PreToolUse gate is a Claude Code CLI feature (settings.json hooks).
+            // Only register it there; Desktop/Gemini/Cursor don't run these hooks.
+            if (agent.name === 'Claude Code CLI') {
+                const __dirname = dirname(fileURLToPath(import.meta.url));
+                const hookPath = join(__dirname, '..', 'hook.js');
+                addPreToolUseHook(config, hookPath);
+            }
+            if (JSON.stringify(config) === before) {
                 console.error(`    ✓ Already configured, skipping`);
                 patchedCount++;
                 continue;
             }
-            // Patch config
-            if (!config.mcpServers) {
-                config.mcpServers = {};
-            }
-            config.mcpServers['vibe-splain'] = MCP_ENTRY;
             await writeFile(resolvedPath, JSON.stringify(config, null, 2), 'utf8');
             console.error(`    ✅ Patched successfully`);
             patchedCount++;

package/dist/commands/network.d.ts

@@ -0,0 +1 @@
+export declare function networkPlanCommand(task: string, options: any): Promise<void>;

package/dist/commands/network.js

@@ -0,0 +1,91 @@
+import { join, resolve } from 'path';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { buildExpertNetworkPacket } from '@vibe-splain/brain';
+export async function networkPlanCommand(task, options) {
+    const projectRoot = options.root ? resolve(options.root) : process.cwd();
+    const maxFiles = options.maxFiles ? parseInt(options.maxFiles, 10) : 8;
+    // Try to load scan artifact
+    let scanArtifact = null;
+    const artifactPath = options.scanArtifact
+        ? resolve(options.scanArtifact)
+        : join(projectRoot, '.vibe-splainer', 'analysis.json');
+    try {
+        const raw = await readFile(artifactPath, 'utf8');
+        scanArtifact = JSON.parse(raw);
+    }
+    catch (err) {
+        if (options.scanArtifact) {
+            console.error(`[vibe-splain] Error reading scan artifact at ${artifactPath}:`, err.message);
+        }
+    }
+    // Build the packet
+    const packet = buildExpertNetworkPacket({
+        task,
+        projectRoot,
+        scanArtifact,
+        errorTrace: options.errorTrace,
+        intendedBehavior: options.intendedBehavior,
+        maxFiles
+    });
+    // Save artifacts
+    const networkDir = join(projectRoot, '.vibe-splainer', 'network');
+    const packetsDir = join(networkDir, 'packets');
+    try {
+        await mkdir(packetsDir, { recursive: true });
+        // Save latest
+        const latestPath = join(networkDir, 'latest_packet.json');
+        await writeFile(latestPath, JSON.stringify(packet, null, 2), 'utf8');
+        // Save timestamped
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const timestampedPath = join(packetsDir, `${timestamp}.json`);
+        await writeFile(timestampedPath, JSON.stringify(packet, null, 2), 'utf8');
+        if (options.json) {
+            process.stdout.write(JSON.stringify(packet, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write('────────────────────────────────────────────────────────\n');
+            process.stdout.write(' Vibe-Splain Specialist Network — Task Plan\n');
+            process.stdout.write('────────────────────────────────────────────────────────\n');
+            process.stdout.write(`Task:               "${packet.task}"\n`);
+            process.stdout.write(`Project Root:       ${packet.projectRoot}\n`);
+            process.stdout.write(`Primary Specialist: ${packet.route.primarySpecialist}\n`);
+            process.stdout.write(`Panel:              ${packet.route.panel.join(', ')}\n`);
+            process.stdout.write(`Confidence:         ${packet.route.confidence}\n`);
+            process.stdout.write(`Reason:             ${packet.route.reason}\n`);
+            process.stdout.write('\nSelected Files:\n');
+            if (packet.selectedFiles.length > 0) {
+                packet.selectedFiles.forEach(f => {
+                    process.stdout.write(`  • ${f.path} [blastRadius: ${f.blastRadius}]\n`);
+                    process.stdout.write(`    Reason: ${f.reason}\n`);
+                });
+            }
+            else {
+                process.stdout.write('  (No files selected)\n');
+            }
+            process.stdout.write('\nRisk Warnings:\n');
+            if (packet.riskWarnings.length > 0) {
+                packet.riskWarnings.forEach(w => {
+                    const levelLabel = w.level === 'critical' ? '🔴 CRITICAL' : (w.level === 'warning' ? '🟡 WARNING' : 'ℹ️ INFO');
+                    process.stdout.write(`  • [${levelLabel}] ${w.message}\n`);
+                    process.stdout.write(`    Reason: ${w.reason}\n`);
+                });
+            }
+            else {
+                process.stdout.write('  (No risks identified)\n');
+            }
+            process.stdout.write('\nSmallest Safe Change Policy:\n');
+            process.stdout.write(`  ${packet.smallestSafeChangePolicy.summary}\n`);
+            process.stdout.write('\nSaved Artifacts:\n');
+            process.stdout.write(`  • Latest: ${latestPath}\n`);
+            process.stdout.write(`  • Packet: ${timestampedPath}\n`);
+            process.stdout.write('────────────────────────────────────────────────────────\n');
+        }
+    }
+    catch (err) {
+        console.error('[vibe-splain] Error saving network artifacts:', err.message);
+        if (options.json) {
+            process.stdout.write(JSON.stringify(packet, null, 2) + '\n');
+        }
+    }
+}
+//# sourceMappingURL=network.js.map

package/dist/commands/scan.d.ts

@@ -0,0 +1,13 @@
+interface ScanOptions {
+    root?: string;
+    out?: string;
+    json?: boolean;
+}
+/**
+ * Headless one-shot scan. Reuses the exact MCP scan pipeline (performScan),
+ * relocates the artifact bundle to --out, and prints a summary. The gravity
+ * formula is selected by the ROZE_GRAVITY_V2 env var, never a CLI flag — v2 is
+ * still an experimental candidate (see CONTEXT.md / Phase 0).
+ */
+export declare function scanCommand(options?: ScanOptions): Promise<void>;
+export {};

package/dist/commands/scan.js

@@ -0,0 +1,97 @@
+import { resolve, join, dirname } from 'path';
+import { rm, rename, mkdir, writeFile } from 'fs/promises';
+import { performScan } from '../mcp/tools/scan_project.js';
+/**
+ * Headless one-shot scan. Reuses the exact MCP scan pipeline (performScan),
+ * relocates the artifact bundle to --out, and prints a summary. The gravity
+ * formula is selected by the ROZE_GRAVITY_V2 env var, never a CLI flag — v2 is
+ * still an experimental candidate (see CONTEXT.md / Phase 0).
+ */
+export async function scanCommand(options = {}) {
+    const root = resolve(options.root || '.');
+    const gravityMode = process.env.ROZE_GRAVITY_V2 === '1' ? 'v2_candidate' : 'v1_default';
+    console.error(`[roze] Scanning ${root} (gravity mode: ${gravityMode})...`);
+    const { result, scanId } = await performScan(root);
+    // The pipeline always writes to <root>/.roze. Relocate to --out if different
+    // so v1 and v2 runs can coexist for comparison.
+    const defaultDir = join(root, '.roze');
+    const outDir = resolve(options.out || defaultDir);
+    if (outDir !== defaultDir) {
+        await rm(outDir, { recursive: true, force: true });
+        await mkdir(dirname(outDir), { recursive: true });
+        await rename(defaultDir, outDir);
+    }
+    // Persist the gravity mode so v1/v2 scans are self-identifying.
+    const meta = {
+        gravityMode,
+        scannedAt: new Date().toISOString(),
+        root,
+        scanId,
+        totalFilesScanned: result.totalFilesScanned,
+        realSourceCount: result.realSourceCount,
+        wildCandidateCount: result.wildCandidates.length,
+    };
+    await writeFile(join(outDir, 'scan_meta.json'), JSON.stringify(meta, null, 2));
+    // Build gravity/heat lookups from the scored files for display.
+    const gravityByPath = new Map(result.files.map(f => [f.relativePath, f.gravity]));
+    const heatByPath = new Map(result.files.map(f => [f.relativePath, f.heat]));
+    const topGravity = result.map.topGravity.slice(0, 12).map(p => ({
+        path: p,
+        gravity: Math.round(gravityByPath.get(p) ?? 0),
+    }));
+    const topHeat = result.map.topHeat.slice(0, 12).map(p => ({
+        path: p,
+        heat: Math.round(heatByPath.get(p) ?? 0),
+    }));
+    const wildDiscovery = result.wildCandidates.slice(0, 12).map(f => ({
+        path: f.relativePath,
+        heat: Math.round(f.heat),
+        gravity: Math.round(f.gravity),
+        topSmells: f.smells.filter(s => s.severity >= 3).slice(0, 3).map(s => s.note),
+    }));
+    const specialistMap = result.map.pillars.map(p => ({
+        name: p.name,
+        fileCount: p.memberFiles.length,
+    }));
+    const summary = {
+        gravityMode,
+        root,
+        outDir,
+        dossier: join(outDir, 'dossier.json'),
+        analysis: join(outDir, 'analysis.json'),
+        stack: result.map.stack,
+        totalFilesScanned: result.totalFilesScanned,
+        realSourceCount: result.realSourceCount,
+        topGravity,
+        topHeat,
+        wildDiscovery,
+        specialistMap,
+    };
+    if (options.json) {
+        process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+        return;
+    }
+    const lines = [];
+    lines.push('');
+    lines.push(`roze scan — gravity mode: ${gravityMode}`);
+    lines.push(`  root:  ${root}`);
+    lines.push(`  stack: ${result.map.stack.join(', ') || '(none detected)'}`);
+    lines.push(`  files: ${result.totalFilesScanned} scanned, ${result.realSourceCount} real-source`);
+    lines.push('');
+    lines.push('Top Gravity (Start Here):');
+    topGravity.forEach((f, i) => lines.push(`  ${String(i + 1).padStart(2)}. [${String(f.gravity).padStart(3)}] ${f.path}`));
+    lines.push('');
+    lines.push('Top Heat (Wild Discovery):');
+    topHeat.forEach((f, i) => lines.push(`  ${String(i + 1).padStart(2)}. [${String(f.heat).padStart(3)}] ${f.path}`));
+    lines.push('');
+    lines.push('Specialist Map (pillars):');
+    specialistMap.forEach(p => lines.push(`  - ${p.name} (${p.fileCount} files)`));
+    lines.push('');
+    lines.push(`Artifacts written to: ${outDir}`);
+    lines.push(`  dossier:  ${join(outDir, 'dossier.json')}`);
+    lines.push(`  analysis: ${join(outDir, 'analysis.json')}`);
+    lines.push(`  meta:     ${join(outDir, 'scan_meta.json')} (gravityMode: ${gravityMode})`);
+    lines.push('');
+    process.stdout.write(lines.join('\n'));
+}
+//# sourceMappingURL=scan.js.map

package/dist/export/ExportOrchestrator.js

@@ -1,8 +1,7 @@
-import { readAnalysis, readActionBindings, RecommendationEngine } from '@vibe-splain/brain';
+import { readAnalysis, RecommendationEngine, buildGateIndex } from '@vibe-splain/brain';
 import { ArtifactBundleWriter } from './ArtifactBundleWriter.js';
 import { JsonRenderer } from './renderers/JsonRenderer.js';
 import { HtmlRenderer } from './renderers/HtmlRenderer.js';
-import { DeltaRenderer } from './renderers/DeltaRenderer.js';
 import { AgentMarkdownRenderer } from './renderers/AgentMarkdownRenderer.js';
 import { ValidationRenderer } from './renderers/ValidationRenderer.js';
 import { RawAnalysisRenderer } from './renderers/RawAnalysisRenderer.js';
@@ -20,22 +19,25 @@ export class ExportOrchestrator {
         if (!finalStore) {
             throw new Error('Analysis store not found. Scan the project first.');
         }
-        const bindings = await readActionBindings(this.projectRoot);
         // Aggressive Boilerplate Culling
         for (const p of dossier.pillars) {
             p.decisions = p.decisions.filter(c => !(c.severity === 1 && c.category === 'Convention'));
             p.cardCount = p.decisions.length;
         }
         const viewModel = this.buildViewModel(dossier, finalStore);
-        // Always render JSON, Delta, Validation, and Raw Analysis.
         const artifacts = [];
         artifacts.push(...await new JsonRenderer().render(viewModel, finalStore));
-        artifacts.push(...await new DeltaRenderer().render(viewModel, finalStore));
         artifacts.push(...await new ValidationRenderer().render(viewModel, finalStore));
         artifacts.push(...await new RawAnalysisRenderer().render(viewModel, finalStore));
         if (graph) {
             artifacts.push(...await new GraphRenderer(graph).render(viewModel, finalStore));
         }
+        const gateIndex = buildGateIndex(finalStore);
+        artifacts.push({
+            type: 'gate',
+            path: 'gate.json',
+            content: JSON.stringify(gateIndex, null, 2),
+        });
         // Determine additional formats
         const formats = ['html', 'markdown']; // default
         if (options.format && options.format !== 'json' && options.format !== 'delta') {
@@ -46,7 +48,7 @@ export class ExportOrchestrator {
             artifacts.push(...await new HtmlRenderer().render(viewModel, finalStore));
         }
         if (formats.includes('markdown')) {
-            artifacts.push(...await new AgentMarkdownRenderer(options.budget, bindings).render(viewModel, finalStore));
+            artifacts.push(...await new AgentMarkdownRenderer(options.budget).render(viewModel, finalStore));
         }
         const writer = new ArtifactBundleWriter(this.projectRoot);
         await writer.writeBundle(artifacts);

package/dist/export/renderers/AgentMarkdownRenderer.d.ts

@@ -3,7 +3,6 @@ import type { Renderer } from './Renderer.js';
 import type { Artifact } from '../ArtifactBundleWriter.js';
 export declare class AgentMarkdownRenderer implements Renderer {
     private budget;
-    private bindings;
-    constructor(budget?: number, bindings?: any | null);
+    constructor(budget?: number);
     render(viewModel: DossierViewModel, store: AnalysisStore): Artifact[];
 }

package/dist/export/renderers/AgentMarkdownRenderer.js

@@ -1,9 +1,7 @@
 export class AgentMarkdownRenderer {
     budget;
-    bindings;
-    constructor(budget = 8000, bindings = null) {
+    constructor(budget = 8000) {
         this.budget = budget;
-        this.bindings = bindings;
     }
     render(viewModel, store) {
         let md = `# Architectural Dossier: ${viewModel.projectRoot}\n\n`;
@@ -54,20 +52,6 @@ export class AgentMarkdownRenderer {
                 md += `**Severity**: ${card.severity} | **Category**: ${card.category}\n`;
                 md += `**Narrative**: ${card.narrative}\n`;
             }
-            // Add Function-Level Action Bindings for Tier 1
-            if (this.bindings && this.bindings.files[path]) {
-                const fileBinding = this.bindings.files[path];
-                const criticalFunctions = fileBinding.functions.filter((fn) => fn.semanticActions.length > 0 || fn.isEntrypoint);
-                if (criticalFunctions.length > 0) {
-                    md += `\n**Critical Functions**:\n`;
-                    for (const fn of criticalFunctions) {
-                        md += `- \`${fn.displayName}\` (lines ${fn.startLine}-${fn.endLine})${fn.isEntrypoint ? ' [Entrypoint]' : ''}\n`;
-                        for (const action of fn.semanticActions) {
-                            md += `  - **${action.actionKind}**${action.targetModel ? ` on ${action.targetModel}` : ''}: \`${action.calleeText}\` (line ${action.sourceLine})\n`;
-                        }
-                    }
-                }
-            }
             if (recs.length > 0) {
                 md += `\n**Safe Patch Strategies**:\n`;
                 for (const r of recs) {

package/dist/hook/preToolUse.d.ts

@@ -0,0 +1,30 @@
+import type { EscalationContext } from '@vibe-splain/brain/dist/network/escalation.js';
+import type { GateIndex } from '@vibe-splain/brain/dist/network/gateIndex.js';
+export interface PreToolUseInput {
+    tool_name?: string;
+    tool_input?: {
+        file_path?: string;
+        [k: string]: unknown;
+    };
+    cwd?: string;
+    session_id?: string;
+}
+export interface HookOutput {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'allow' | 'ask';
+        permissionDecisionReason?: string;
+        additionalContext?: string;
+        systemMessage?: string;
+    };
+}
+export type HookResult = {
+    action: 'defer';
+} | {
+    action: 'emit';
+    output: HookOutput;
+};
+export declare function decidePreToolUse(input: PreToolUseInput, gateIndex: GateIndex | null, sessionState?: {
+    warningShown?: boolean;
+}): HookResult;
+export declare function formatEscalation(ctx: EscalationContext): string;