vibe-splain 3.4.0 → 3.4.2

package/dist/mcp/server.js

@@ -11,17 +11,16 @@ import { handleGetStrategicOverview, getStrategicOverviewTool } from './tools/ge
 import { handleInspectPillar, inspectPillarTool } from './tools/inspect_pillar.js';
 import { handleGetWildDiscoveries, getWildDiscoveriesTool } from './tools/get_wild_discoveries.js';
 import { handleMarkStale, markStaleTool } from './tools/mark_stale.js';
-import { handleGetCallChain, getCallChainTool } from './tools/get_call_chain.js';
 import { handleGetFileSkeleton, getFileSkeletonTool } from './tools/get_file_skeleton.js';
 import { handleReadFile, readFileTool } from './tools/read_file.js';
-import { handleApplyPatch, applyPatchTool } from './tools/apply_patch.js';
 import { handleCreateWorkOrder, createWorkOrderTool, handleSpawnWorker, spawnWorkerTool } from './tools/work_orders.js';
-import { handleSubmitReceipt, submitReceiptTool } from './tools/submit_receipt.js';
 import { handleSetSessionScope, setSessionScopeTool } from './tools/set_session_scope.js';
 import { handleYieldForScopeExpansion, yieldForScopeExpansionTool } from './tools/yield_for_scope_expansion.js';
 import { handleGetStartHere, getStartHereTool } from './tools/hydration/get_start_here.js';
 import { handleGetProjectSummary, getProjectSummaryTool } from './tools/hydration/get_project_summary.js';
 import { handleGetEvidenceSlice, getEvidenceSliceTool } from './tools/hydration/get_evidence_slice.js';
+import { handlePrepareTaskContext, prepareTaskContextTool } from './tools/prepareTaskContext.js';
+import { handleExplainSpecialistScope, explainSpecialistScopeTool } from './tools/explainSpecialistScope.js';
 // ⚠️ CRITICAL: Never use console.log() anywhere in this codebase.
 // stdout is owned by the MCP SDK for protocol messages.
 // Use console.error() for all diagnostic output.
@@ -30,7 +29,6 @@ const ALL_TOOLS = [
     getProjectMapTool,
     setProjectBriefTool,
     getFileContextTool,
-    getCallChainTool,
     writeDecisionCardTool,
     getStrategicOverviewTool,
     inspectPillarTool,
@@ -42,21 +40,21 @@ const ALL_TOOLS = [
     getStartHereTool,
     getProjectSummaryTool,
     getEvidenceSliceTool,
-    // Phase 3: Delegation & Proof
+    // Phase 3: Worker Delegation
     createWorkOrderTool,
     spawnWorkerTool,
-    applyPatchTool,
-    submitReceiptTool,
     // Phase 4: Scope & Escalation
     setSessionScopeTool,
     yieldForScopeExpansionTool,
+    // Specialist Network v0
+    prepareTaskContextTool,
+    explainSpecialistScopeTool,
 ];
 const TOOL_HANDLERS = {
     scan_project: handleScanProject,
     get_project_map: handleGetProjectMap,
     set_project_brief: handleSetProjectBrief,
     get_file_context: handleGetFileContext,
-    get_call_chain: handleGetCallChain,
     write_decision_card: handleWriteDecisionCard,
     get_strategic_overview: handleGetStrategicOverview,
     inspect_pillar: handleInspectPillar,
@@ -71,11 +69,12 @@ const TOOL_HANDLERS = {
     // Phase 3
     create_work_order: handleCreateWorkOrder,
     spawn_worker: handleSpawnWorker,
-    apply_patch: handleApplyPatch,
-    submit_receipt: handleSubmitReceipt,
     // Phase 4
     set_session_scope: handleSetSessionScope,
     yield_for_scope_expansion: handleYieldForScopeExpansion,
+    // Specialist Network v0
+    vibe_prepare_task_context: handlePrepareTaskContext,
+    vibe_explain_specialist_scope: handleExplainSpecialistScope,
 };
 export async function startMCPServer(options = {}) {
     // Initialize Tree-Sitter WASM once at startup

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

@@ -0,0 +1,15 @@
+export declare const explainSpecialistScopeTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            specialist_id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleExplainSpecialistScope(args: Record<string, unknown>, options?: any): Promise<unknown>;

package/dist/mcp/tools/explainSpecialistScope.js

@@ -0,0 +1,30 @@
+import { getSpecialistProfile, isSpecialistId } from '@vibe-splain/brain';
+export const explainSpecialistScopeTool = {
+    name: 'vibe_explain_specialist_scope',
+    description: 'Explains the jurisdiction scope card and profile definitions for a given specialist ID.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            specialist_id: {
+                type: 'string',
+                description: 'Specialist ID to explain (control_flow | data_transform | integration_contracts | generic_repo)',
+            }
+        },
+        required: ['specialist_id'],
+    },
+};
+export async function handleExplainSpecialistScope(args, options = {}) {
+    const specialistId = args.specialist_id;
+    if (!specialistId)
+        throw new Error('specialist_id is required');
+    if (!isSpecialistId(specialistId)) {
+        throw new Error(`Invalid specialist ID: "${specialistId}". Must be one of: control_flow, data_transform, integration_contracts, generic_repo.`);
+    }
+    console.error(`[vibe-splain] Fetching scope profile for specialist: "${specialistId}"`);
+    const profile = getSpecialistProfile(specialistId);
+    return {
+        ok: true,
+        profile
+    };
+}
+//# sourceMappingURL=explainSpecialistScope.js.map

package/dist/mcp/tools/hydration/get_evidence_slice.js

@@ -27,8 +27,7 @@ export async function handleGetEvidenceSlice(args) {
     // 1. Verify pointer, lifetime, hash
     const { content, row } = await hydratePointer(projectRoot, pointerId);
     const rawText = content.toString('utf8');
-    // 2. Scope enforcement for file-type artifacts: if a Worker scope is active,
-    //    file_read and file_skeleton blobs embed the source filePath — enforce it.
+    // Scope enforcement: if a Worker scope is active, enforce it for file-type artifacts
     const scope = SessionScope.get();
     if (scope && (row.artifactName === 'file_read' || row.artifactName === 'file_skeleton')) {
         try {
@@ -38,7 +37,6 @@ export async function handleGetEvidenceSlice(args) {
             }
         }
         catch (e) {
-            // If it's a ScopeViolation, re-throw; JSON parse failures are ignored.
             if (e.name === 'ScopeViolation')
                 throw e;
         }

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

@@ -0,0 +1,38 @@
+export declare const prepareTaskContextTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            task: {
+                type: string;
+                description: string;
+            };
+            files: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            error_trace: {
+                type: string;
+                description: string;
+            };
+            intended_behavior: {
+                type: string;
+                description: string;
+            };
+            max_files: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handlePrepareTaskContext(args: Record<string, unknown>, options?: any): Promise<unknown>;

package/dist/mcp/tools/prepareTaskContext.js

@@ -0,0 +1,93 @@
+import { join } from 'path';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { buildExpertNetworkPacket } from '@vibe-splain/brain';
+export const prepareTaskContextTool = {
+    name: 'vibe_prepare_task_context',
+    description: 'Prepares the ExpertNetworkPacket for a given task, selecting relevant files, routing to a specialist panel, analyzing risk warnings, and slicing scopes without running model inference.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: {
+                type: 'string',
+                description: 'Absolute path to the project root directory',
+            },
+            task: {
+                type: 'string',
+                description: 'Description of the task or issue to resolve',
+            },
+            files: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional list of files to explicitly focus on',
+            },
+            error_trace: {
+                type: 'string',
+                description: 'Optional error stack trace or exception output',
+            },
+            intended_behavior: {
+                type: 'string',
+                description: 'Optional description of the intended behavior',
+            },
+            max_files: {
+                type: 'number',
+                description: 'Optional maximum files to select',
+            }
+        },
+        required: ['projectRoot', 'task'],
+    },
+};
+export async function handlePrepareTaskContext(args, options = {}) {
+    const projectRoot = args.projectRoot;
+    const task = args.task;
+    const files = args.files;
+    const errorTrace = args.error_trace;
+    const intendedBehavior = args.intended_behavior;
+    const maxFiles = args.max_files;
+    if (!projectRoot)
+        throw new Error('projectRoot is required');
+    if (!task)
+        throw new Error('task is required');
+    console.error(`[vibe-splain] Preparing task context for task: "${task}"`);
+    // Try to load scan artifact
+    let scanArtifact = null;
+    const artifactPath = join(projectRoot, '.vibe-splainer', 'analysis.json');
+    try {
+        const raw = await readFile(artifactPath, 'utf8');
+        scanArtifact = JSON.parse(raw);
+    }
+    catch (err) {
+        console.error(`[vibe-splain] No scan artifact found at ${artifactPath}, proceeding with fallback routing.`);
+    }
+    // Build the packet
+    const packet = buildExpertNetworkPacket({
+        task,
+        projectRoot,
+        scanArtifact,
+        files,
+        errorTrace,
+        intendedBehavior,
+        maxFiles
+    });
+    // Save network packet locally
+    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');
+        console.error(`[vibe-splain] Network packets saved under ${networkDir}`);
+    }
+    catch (err) {
+        console.error('[vibe-splain] Failed to save network packets locally:', err.message);
+    }
+    return {
+        ok: true,
+        packet
+    };
+}
+//# sourceMappingURL=prepareTaskContext.js.map

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

@@ -1,3 +1,5 @@
+import { scanProject } from '@vibe-splain/brain';
+import type { Dossier } from '@vibe-splain/brain';
 export declare const scanProjectTool: {
     name: string;
     description: string;
@@ -12,4 +14,17 @@ export declare const scanProjectTool: {
         required: string[];
     };
 };
+/**
+ * Shared scan core: run the brain pipeline, build the dossier, and write the
+ * artifact bundle. Both the MCP `scan_project` tool and the headless CLI `scan`
+ * command call this — there is exactly one scan path. Side-effects beyond
+ * artifact writing (e.g. the staleness watcher) are the caller's concern.
+ */
+export interface ScanRun {
+    result: Awaited<ReturnType<typeof scanProject>>;
+    dossier: Dossier;
+    scanId: string;
+    manifestPointer: unknown;
+}
+export declare function performScan(projectRoot: string, options?: any): Promise<ScanRun>;
 export declare function handleScanProject(args: Record<string, unknown>, options?: any): Promise<unknown>;

package/dist/mcp/tools/scan_project.js

@@ -15,11 +15,7 @@ export const scanProjectTool = {
         required: ['projectRoot'],
     },
 };
-export async function handleScanProject(args, options = {}) {
-    const projectRoot = args.projectRoot;
-    if (!projectRoot)
-        throw new Error('projectRoot is required');
-    console.error(`[vibe-splain] Scanning project: ${projectRoot}`);
+export async function performScan(projectRoot, options = {}) {
     const result = await scanProject(projectRoot);
     // Preserve any existing cards; replace the structural map every scan.
     const existing = await readDossier(projectRoot);
@@ -54,17 +50,25 @@ export async function handleScanProject(args, options = {}) {
         budget: options.budget ? parseInt(options.budget, 10) : undefined,
         scope: options.scope,
     }, result.store, result.graph, scanId);
-    // Watch the real-source files for staleness.
-    await startWatcher(projectRoot, result.files.map(f => f.path));
+    return { result, dossier, scanId, manifestPointer };
+}
+export async function handleScanProject(args, options = {}) {
+    const projectRoot = args.projectRoot;
+    if (!projectRoot)
+        throw new Error('projectRoot is required');
+    console.error(`[vibe-splain] Scanning project: ${projectRoot}`);
+    const { result, scanId, manifestPointer } = await performScan(projectRoot, options);
+    // Watch the real-source files for staleness. MCP serve mode keeps this alive
+    // for the session; headless callers pass watch:false so the persistent
+    // chokidar watcher never pins the event loop open and the process can exit.
+    if (options.watch !== false) {
+        await 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.`);
     const validation = result.validation ?? { passed: true, errors: 0, warnings: 0, reportPath: '.vibe-splainer/validation_report.json' };
-    let statusMsg = 'Scan complete.';
-    if (!validation.passed) {
-        statusMsg = `SCAN QUALITY WARNING: ${validation.errors} errors and ${validation.warnings} warnings found in validation report. Delta Engine automation may be blocked.`;
-    }
     return {
         ok: true,
-        message: statusMsg,
+        message: 'Scan complete.',
         scanId,
         manifestPointer,
         validation: result.fullValidationReport || {
@@ -75,7 +79,6 @@ export async function handleScanProject(args, options = {}) {
         },
         artifacts: {
             analysis: '.vibe-splainer/analysis.json',
-            deltaTargets: '.vibe-splainer/delta_targets.json',
             dossier: '.vibe-splainer/dossier.json',
             graph: '.vibe-splainer/graph.json',
             html: '.vibe-splainer/ui/index.html',