vibe-splain 1.1.0 → 2.0.1

package/dist/mcp/server.js

@@ -3,6 +3,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { initParser } from '@vibe-splain/brain';
 import { handleScanProject, scanProjectTool } from './tools/scan_project.js';
+import { handleGetProjectMap, getProjectMapTool } from './tools/get_project_map.js';
+import { handleSetProjectBrief, setProjectBriefTool } from './tools/set_project_brief.js';
 import { handleGetFileContext, getFileContextTool } from './tools/get_file_context.js';
 import { handleWriteDecisionCard, writeDecisionCardTool } from './tools/write_decision_card.js';
 import { handleGetStrategicOverview, getStrategicOverviewTool } from './tools/get_strategic_overview.js';
@@ -14,6 +16,8 @@ import { handleMarkStale, markStaleTool } from './tools/mark_stale.js';
 // Use console.error() for all diagnostic output.
 const ALL_TOOLS = [
     scanProjectTool,
+    getProjectMapTool,
+    setProjectBriefTool,
     getFileContextTool,
     writeDecisionCardTool,
     getStrategicOverviewTool,
@@ -23,6 +27,8 @@ const ALL_TOOLS = [
 ];
 const TOOL_HANDLERS = {
     scan_project: handleScanProject,
+    get_project_map: handleGetProjectMap,
+    set_project_brief: handleSetProjectBrief,
     get_file_context: handleGetFileContext,
     write_decision_card: handleWriteDecisionCard,
     get_strategic_overview: handleGetStrategicOverview,
@@ -34,7 +40,7 @@ export async function startMCPServer() {
     // Initialize Tree-Sitter WASM once at startup
     await initParser();
     console.error('[vibe-splain] Tree-Sitter parser initialized');
-    const server = new Server({ name: 'vibe-splain', version: '1.0.0' }, { capabilities: { tools: {}, prompts: {} } });
+    const server = new Server({ name: 'vibe-splain', version: '2.0.0' }, { capabilities: { tools: {}, prompts: {} } });
     // Register prompts
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({
         prompts: [
@@ -55,7 +61,65 @@ export async function startMCPServer() {
                     role: 'user',
                     content: {
                         type: 'text',
-                        text: 'Use the vibe-splain MCP tools to build a full architectural dossier for this project. Call scan_project first. Before writing any cards, define a strict set of 3-5 core architectural pillars, and force all categorizations into those predefined buckets to avoid fragmentation. Then for each high-gravity file, call get_file_context to read the source, synthesize a 3-5 sentence narrative explaining WHY the code exists, and call write_decision_card to persist it. When extracting evidence snippets, extract small, highly specific evidence snippets (5-20 lines). NEVER cite the entire file as evidence. If you find weird hacks, tech debt, or eccentric AI-generated code, document it as a Wild Discovery. Include Mermaid diagrams where they help explain data flow. When you\'re done, share the exact file:// UI link returned by the tool so I can view the dossier in my browser. Do NOT invent a localhost URL.',
+                        text: `You are a skeptical staff engineer doing a HOSTILE architecture review of this codebase.
+You are NOT writing documentation. You are finding the load-bearing walls, the landmines,
+and the clever moves, and you are taking positions on them.
+
+PROCESS — follow in order:
+1. Call scan_project, then get_project_map. The map gives you: the detected stack,
+   the FIXED set of pillars (you may not invent others), the Start-Here files (highest
+   gravity = most depended-upon), and Wild-Discovery candidates (highest heat = most smell).
+2. Read the map's stack and entrypoints. Write a 3-5 sentence project brief: what IS this,
+   what's the real stack, and — critically — which files are the actual application vs.
+   mockups/generated/vendored noise. Pass it via set_project_brief. Do this BEFORE any card.
+3. Work the Start-Here files first (highest gravity), then the Wild-Discovery files.
+   For each, call get_file_context. It returns hotSpans (the gnarliest functions) and
+   smellSpans (located tech debt) — base your evidence on THOSE, never on header comments.
+4. Write one decision card per file via write_decision_card.
+
+This is an AUTONOMOUS loop. Every tool response includes a \`nextStep\` and often a
+\`remainingFiles\` list — OBEY them. Do NOT stop, summarize, or ask the user "how would
+you like to proceed" until every Start-Here and Wild-Discovery file has a card. Writing
+the brief is the START of the work, not the end. Keep calling get_file_context +
+write_decision_card until remainingFiles is empty.
+
+RULES FOR EVERY CARD — non-negotiable:
+- The \`thesis\` is a VERDICT in one sentence. Take a position. If you can't, you don't
+  understand the file yet — read more.
+- Pick a \`category\`: Bottleneck, Hack, Smart-Move, Risk, Convention, or Dead-Weight.
+- \`blastRadius\` must reference the real fan-in (get_file_context.importedBy).
+- NEVER paraphrase the file's own comments. If the insight is already in a // block,
+  it is not insight — go deeper into the logic.
+- Evidence = 5-20 lines of the ACTUAL interesting code (hotSpans/smellSpans). Never the
+  whole file, never the doc-header.
+- For every Wild-Discovery candidate, name the specific smell and rate its severity.
+
+────────────────────────────────────────────────────────
+EXAMPLE — what GOOD vs BAD looks like:
+
+BAD (rejected — this is a book report):
+  title: "Panel Component Framework"
+  narrative: "This module establishes the structural framework for the panel-based
+  interface. It defines the generic Panel shell that standardizes look and feel..."
+  → Restates the header comment. No position. No risk. No tradeoff. Worthless.
+
+GOOD (accepted):
+  title: "Panel shell carries 14 props and 6 tools in one file"
+  thesis: "cipher-panels-a.jsx is a god-file: one 600-line module owns the shared shell
+           AND three unrelated generators, so any panel change risks all of them."
+  category: "Risk"  severity: 4
+  narrative: "Panel was built as a single shell to guarantee visual consistency, but the
+              three generators (Palette/Vibe/Pocket) were folded in beside it instead of
+              split out. The shell threads 14 props through every tool, so the generators
+              are now coupled to the shell's drag/compact state they don't use."
+  tradeoff: "Bought consistency and one import site; paid with a module no one can change
+             safely and props that leak shell concerns into pure generators."
+  blastRadius: "Imported by cipher-shell.jsx (the app root) — a regression here is a
+                full-app regression."
+  evidence: [ the 14-param Panel signature; the prop-drill into PalettePanel ]
+────────────────────────────────────────────────────────
+
+When done, share the exact file:// UI link returned by scan_project. Never invent a URL.`,
                     }
                 }
             ]

package/dist/mcp/tools/get_file_context.d.ts

@@ -12,6 +12,10 @@ export declare const getFileContextTool: {
                 type: string;
                 description: string;
             };
+            full: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };

package/dist/mcp/tools/get_file_context.js

@@ -1,20 +1,15 @@
 import { readFile } from 'fs/promises';
-import { join, relative } from 'path';
-import { readGraph } from '@vibe-splain/brain';
+import { join, relative, isAbsolute } from 'path';
+import { getFileAnalysis, readAnalysis } from '@vibe-splain/brain';
 export const getFileContextTool = {
     name: 'get_file_context',
-    description: 'Returns the full source code of a specific high-gravity file, its cognitive weight breakdown, and its import graph neighbors. Call this for each file you want to synthesize a Decision Card for. Use the source + neighbors to understand what the code does and WHY it was written that way.',
+    description: 'Returns PRE-EXTRACTED evidence for a file so you do not have to read the whole thing and paraphrase its header comment. Returns: gravity/heat scores + signals, importedBy (named fan-in — use this for blastRadius), hotSpans (the gnarliest function bodies, comment-stripped, each with a reason), smellSpans (located tech debt with ±3 lines of context), and signature (the exported API surface). Base your evidence on hotSpans/smellSpans — NEVER on header comments. Pass { full: true } only if you truly need the raw source.',
     inputSchema: {
         type: 'object',
         properties: {
-            projectRoot: {
-                type: 'string',
-                description: 'Absolute path to the project root',
-            },
-            filePath: {
-                type: 'string',
-                description: 'Relative or absolute path to the file',
-            },
+            projectRoot: { type: 'string', description: 'Absolute path to the project root' },
+            filePath: { type: 'string', description: 'Relative or absolute path to the file' },
+            full: { type: 'boolean', description: 'Set true to also return the raw source. Default false.' },
         },
         required: ['projectRoot', 'filePath'],
     },
@@ -22,27 +17,35 @@ export const getFileContextTool = {
 export async function handleGetFileContext(args) {
     const projectRoot = args.projectRoot;
     const filePath = args.filePath;
+    const full = args.full === true;
     if (!projectRoot || !filePath)
         throw new Error('projectRoot and filePath are required');
-    const fullPath = filePath.startsWith('/') ? filePath : join(projectRoot, filePath);
+    const fullPath = isAbsolute(filePath) ? filePath : join(projectRoot, filePath);
     const relPath = relative(projectRoot, fullPath);
-    const source = await readFile(fullPath, 'utf8');
-    const graph = await readGraph(projectRoot);
-    // Find neighbors in import graph
-    const neighbors = [];
-    if (graph) {
-        for (const edge of graph.edges) {
-            if (edge.from === relPath)
-                neighbors.push(edge.to);
-            if (edge.to === relPath || edge.to.endsWith(relPath))
-                neighbors.push(edge.from);
-        }
+    const evidence = await getFileAnalysis(fullPath);
+    if (!evidence) {
+        throw new Error(`Could not analyze ${relPath} (unsupported language or parse failure).`);
     }
-    return {
+    const store = await readAnalysis(projectRoot);
+    const persisted = store?.files[relPath];
+    const result = {
         filePath: relPath,
-        source,
-        lineCount: source.split('\n').length,
-        neighbors: [...new Set(neighbors)],
+        language: evidence.language,
+        gravity: persisted ? Math.round(persisted.gravity) : null,
+        heat: persisted ? Math.round(persisted.heat) : null,
+        isRealSource: persisted?.isRealSource ?? null,
+        demoteReason: persisted?.demoteReason ?? null,
+        gravitySignals: persisted?.gravitySignals ?? null,
+        heatSignals: evidence.heatSignals,
+        importedBy: persisted?.importedBy ?? [],
+        imports: persisted?.imports ?? [],
+        signature: evidence.signature,
+        hotSpans: evidence.hotSpans,
+        smellSpans: evidence.smellSpans,
     };
+    if (full) {
+        result.source = await readFile(fullPath, 'utf8');
+    }
+    return result;
 }
 //# sourceMappingURL=get_file_context.js.map

package/dist/mcp/tools/get_project_map.d.ts

@@ -0,0 +1,15 @@
+export declare const getProjectMapTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGetProjectMap(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/get_project_map.js

@@ -0,0 +1,41 @@
+import { readDossier } from '@vibe-splain/brain';
+export const getProjectMapTool = {
+    name: 'get_project_map',
+    description: 'Returns the project map produced by scan_project: the detected stack, entrypoints, the FIXED set of architectural pillars (you may NOT invent others — write_decision_card rejects unknown pillars), the Start-Here files (highest gravity = most depended-upon), and the Wild-Discovery candidates (highest heat = most tech debt). BEFORE writing any card you MUST: read this map, write a 3-5 sentence project brief, and persist it via set_project_brief.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute path to the project root' },
+        },
+        required: ['projectRoot'],
+    },
+};
+export async function handleGetProjectMap(args) {
+    const projectRoot = args.projectRoot;
+    if (!projectRoot)
+        throw new Error('projectRoot is required');
+    const dossier = await readDossier(projectRoot);
+    if (!dossier || !dossier.map) {
+        return { error: 'No project map found. Run scan_project first.' };
+    }
+    const m = dossier.map;
+    return {
+        stack: m.stack,
+        entrypoints: m.entrypoints,
+        fileCount: m.fileCount,
+        realSourceCount: m.realSourceCount,
+        pillars: m.pillars.map(p => ({
+            name: p.name,
+            description: p.description,
+            memberFiles: p.memberFiles,
+        })),
+        legalPillarNames: m.pillars.map(p => p.name),
+        startHere: m.topGravity,
+        wildDiscoveryCandidates: m.topHeat,
+        brief: m.brief,
+        nextStep: m.brief
+            ? 'Brief is set. Work the Start-Here files first via get_file_context, then write_decision_card.'
+            : 'Write a 3-5 sentence brief and call set_project_brief BEFORE any card.',
+    };
+}
+//# sourceMappingURL=get_project_map.js.map

package/dist/mcp/tools/mark_stale.js

@@ -29,14 +29,21 @@ export async function handleMarkStale(args) {
     }
     let staleCount = 0;
     for (const filePath of filePaths) {
+        const matches = (card) => card.primaryFile === filePath ||
+            filePath.endsWith(card.primaryFile || '\0') ||
+            card.evidence.some(e => e.file === filePath || filePath.endsWith(e.file));
         for (const pillar of dossier.pillars) {
             for (const card of pillar.decisions) {
-                if (card.evidence.some(e => e.file === filePath || filePath.endsWith(e.file))) {
+                if (matches(card)) {
                     card.status = 'stale';
                     staleCount++;
                 }
             }
         }
+        for (const card of dossier.wildDiscoveries) {
+            if (matches(card))
+                card.status = 'stale';
+        }
         if (!dossier.stalePaths.includes(filePath)) {
             dossier.stalePaths.push(filePath);
         }

package/dist/mcp/tools/scan_project.js

@@ -1,7 +1,7 @@
 import { scanProject, writeDossier, readDossier, startWatcher } from '@vibe-splain/brain';
 export const scanProjectTool = {
     name: 'scan_project',
-    description: 'Scans a codebase and returns its structural analysis. CALL THIS FIRST before any other tool. Returns High-Gravity files grouped by pillar, plus wildCandidates for unusual high-complexity files. After calling this tool, call get_file_context for each file in highGravityFiles, synthesize a narrative explaining WHY that code exists, then call write_decision_card to persist it. The uiUrl in the response is a file:// link — share it with the user so they can open the Dossier UI in their browser.',
+    description: 'Scans a codebase (TS/JS/Python/Go/Rust/Java) and returns a structural analysis. CALL THIS FIRST, then call get_project_map. Files are scored on two axes: GRAVITY (importance — fan-in + PageRank centrality) and HEAT (smell/tech-debt). Mockups, vendored code, and orphan files are demoted (isRealSource:false) so cards target the real application. After scanning, call get_project_map to get the fixed pillar set, Start-Here (top gravity) and Wild-Discovery (top heat) lists. The uiUrl is a file:// link — share it with the user.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -19,47 +19,43 @@ export async function handleScanProject(args) {
         throw new Error('projectRoot is required');
     console.error(`[vibe-splain] Scanning project: ${projectRoot}`);
     const result = await scanProject(projectRoot);
-    // Create initial dossier structure
-    const existingDossier = await readDossier(projectRoot);
-    const dossier = existingDossier || {
-        version: '1.0.0',
+    // Preserve any existing cards; replace the structural map every scan.
+    const existing = await readDossier(projectRoot);
+    const brief = existing?.map?.brief ?? null;
+    const dossier = {
+        version: '2.0.0',
         scannedAt: new Date().toISOString(),
         projectRoot,
-        pillars: [],
-        wildDiscoveries: [],
-        stalePaths: [],
+        map: { ...result.map, brief },
+        pillars: existing?.pillars ?? [],
+        wildDiscoveries: existing?.wildDiscoveries ?? [],
+        stalePaths: existing?.stalePaths ?? [],
     };
-    // Update scan timestamp
-    dossier.scannedAt = new Date().toISOString();
-    // Create pillar entries from scan results
-    for (const group of result.pillarGroups) {
-        const existingPillar = dossier.pillars.find(p => p.name === group.name);
-        if (!existingPillar) {
-            dossier.pillars.push({ name: group.name, cardCount: 0, decisions: [] });
+    // Seed empty pillar buckets from the fixed graph-derived pillar set.
+    for (const def of result.map.pillars) {
+        if (!dossier.pillars.find(p => p.name === def.name)) {
+            dossier.pillars.push({ name: def.name, cardCount: 0, decisions: [] });
         }
     }
     await writeDossier(projectRoot, dossier);
-    // Start file watcher on high-gravity files
-    const watchPaths = result.highGravityFiles.map(f => f.path);
-    startWatcher(projectRoot, watchPaths);
-    console.error(`[vibe-splain] Scan complete. ${result.totalFilesScanned} files scanned, ${result.highGravityFiles.length} high-gravity files found.`);
+    // Watch the real-source files for staleness.
+    startWatcher(projectRoot, result.files.map(f => f.path));
+    console.error(`[vibe-splain] Scan complete. ${result.totalFilesScanned} files, ${result.realSourceCount} real-source, ${result.wildCandidates.length} wild candidates.`);
     return {
         projectRoot: result.projectRoot,
         totalFilesScanned: result.totalFilesScanned,
-        highGravityFiles: result.highGravityFiles.map(f => ({
+        realSourceCount: result.realSourceCount,
+        stack: result.map.stack,
+        entrypoints: result.map.entrypoints,
+        pillars: result.map.pillars.map(p => ({ name: p.name, fileCount: p.memberFiles.length })),
+        startHere: result.map.topGravity,
+        wildDiscoveryCandidates: result.wildCandidates.map(f => ({
             relativePath: f.relativePath,
-            cognitiveWeight: f.cognitiveWeight,
-            pillars: f.pillars,
-        })),
-        pillarGroups: result.pillarGroups.map(g => ({
-            name: g.name,
-            fileCount: g.files.length,
-            files: g.files.map(f => f.relativePath),
-        })),
-        wildCandidates: result.wildCandidates.map(f => ({
-            relativePath: f.relativePath,
-            cognitiveWeight: f.cognitiveWeight,
+            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),
         })),
+        nextStep: 'Call get_project_map, write a project brief via set_project_brief, THEN write cards starting from the Start-Here files.',
         uiUrl: result.uiUrl,
     };
 }

package/dist/mcp/tools/set_project_brief.d.ts

@@ -0,0 +1,19 @@
+export declare const setProjectBriefTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            brief: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleSetProjectBrief(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/set_project_brief.js

@@ -0,0 +1,42 @@
+import { readDossier, writeDossier } from '@vibe-splain/brain';
+export const setProjectBriefTool = {
+    name: 'set_project_brief',
+    description: 'Persists your 3-5 sentence project brief into the dossier (and regenerates the UI). Call this AFTER get_project_map and BEFORE writing any decision card. The brief must say: what this project IS, the real stack, and — critically — which files are the actual application vs. mockups/generated/vendored noise.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute path to the project root' },
+            brief: { type: 'string', description: '3-5 sentence project brief. What is this, the real stack, app vs. noise.' },
+        },
+        required: ['projectRoot', 'brief'],
+    },
+};
+export async function handleSetProjectBrief(args) {
+    const projectRoot = args.projectRoot;
+    const brief = args.brief;
+    if (!projectRoot || !brief)
+        throw new Error('projectRoot and brief are required');
+    const dossier = await readDossier(projectRoot);
+    if (!dossier || !dossier.map) {
+        return { error: 'No project map found. Run scan_project first.' };
+    }
+    dossier.map.brief = brief;
+    await writeDossier(projectRoot, dossier);
+    // Drive the loop: hand back the exact remaining worklist so the agent does
+    // not stop and ask the user. Weak models treat "brief saved" as done otherwise.
+    const documented = new Set([...dossier.pillars.flatMap(p => p.decisions), ...dossier.wildDiscoveries]
+        .map(c => c.primaryFile).filter(Boolean));
+    const startHere = dossier.map.topGravity.filter(f => !documented.has(f));
+    const wild = dossier.map.topHeat.filter(f => !documented.has(f));
+    const worklist = [...new Set([...startHere, ...wild])];
+    return {
+        success: true,
+        brief,
+        remainingFiles: worklist,
+        legalPillarNames: dossier.map.pillars.map(p => p.name),
+        nextStep: worklist.length === 0
+            ? 'All files documented. Share the file:// UI link from scan_project.'
+            : `Brief saved. DO NOT STOP and DO NOT ask the user what to do next. Now loop: for EACH of the ${worklist.length} files in remainingFiles, call get_file_context then write_decision_card. Start with "${worklist[0]}". Continue until every file has a card, then share the file:// UI link.`,
+    };
+}
+//# sourceMappingURL=set_project_brief.js.map

package/dist/mcp/tools/write_decision_card.d.ts

@@ -1,3 +1,4 @@
+import type { CardCategory } from '@vibe-splain/brain';
 export declare const writeDecisionCardTool: {
     name: string;
     description: string;
@@ -6,20 +7,47 @@ export declare const writeDecisionCardTool: {
         properties: {
             projectRoot: {
                 type: string;
-                description: string;
             };
             pillar: {
                 type: string;
                 description: string;
             };
+            primaryFile: {
+                type: string;
+                description: string;
+            };
             title: {
                 type: string;
+            };
+            thesis: {
+                type: string;
                 description: string;
             };
+            category: {
+                type: string;
+                enum: CardCategory[];
+            };
+            severity: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
             narrative: {
                 type: string;
                 description: string;
             };
+            tradeoff: {
+                type: string;
+                description: string;
+            };
+            blastRadius: {
+                type: string;
+                description: string;
+            };
+            confidence: {
+                type: string;
+                enum: string[];
+            };
             evidence: {
                 type: string;
                 items: {
@@ -27,19 +55,15 @@ export declare const writeDecisionCardTool: {
                     properties: {
                         file: {
                             type: string;
-                            description: string;
                         };
                         startLine: {
                             type: string;
-                            description: string;
                         };
                         endLine: {
                             type: string;
-                            description: string;
                         };
                         snippet: {
                             type: string;
-                            description: string;
                         };
                     };
                     required: string[];