@papyruslabsai/seshat-mcp 0.17.0 → 0.19.0

package/dist/index.js

@@ -278,6 +278,30 @@ const TOOLS = [
         },
         annotations: READ_ONLY_OPEN,
     },
+    {
+        name: 'get_hotspots',
+        title: 'Get Hotspots',
+        description: 'Project-level change-history orientation: the most-changed entities (and what kind of change dominates each), low-survival thrash spots where changes don\'t stick, heavily-depended-on entities that haven\'t changed all window (interface freeze), and directories with no recent changes. Call it after list_modules when orienting in a codebase — it answers "where does development actually happen, and where does it fail?" from commit history rather than current structure. Complements get_lineage (one entity\'s story) with the project-wide map.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+            },
+        },
+        annotations: READ_ONLY_OPEN,
+    },
+    {
+        name: 'get_co_change_clusters',
+        title: 'Get Co-Change Clusters',
+        description: 'The codebase\'s hidden modules: groups of symbols that historically change together (≥3 shared commits, sweep commits excluded), computed from real commit history. Clusters that span multiple directories reveal coupling the file tree doesn\'t show. Call it when planning a change or splitting work across agents — touching one member of a cluster usually means touching the rest, even when no static dependency connects them. Correlation evidence, honestly framed; complements get_blast_radius (static reach) with empirical reach.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+            },
+        },
+        annotations: READ_ONLY_OPEN,
+    },
     {
         name: 'list_modules',
         title: 'List Modules',

package/dist/tools/diff.d.ts

@@ -21,4 +21,8 @@ export declare function conflictMatrix(args: {
         expand_blast_radius?: boolean;
     }>;
     project?: string;
-}, loader: ProjectLoader): unknown;
+}, loader: ProjectLoader, extras?: {
+    /** Lineage-backed co-change provider: given entity ids, returns a map of
+     *  sorted-pair keys (`${idA}
${idB}`) → shared commit counts. */
+    fetchCoChanges?: (entityIds: string[]) => Promise<Map<string, number>>;
+}): Promise<unknown>;

package/dist/tools/diff.js

@@ -280,6 +280,11 @@ const CONFLICT_WEIGHTS = {
     epsilon: 0.23, // ε — shared call-graph neighborhood
     delta: 0.14, // δ — shared data contracts (tables)
     files: 0.11, // χ-adjacent — shared files
+    // Historical co-change from the lineage record (entity_transitions):
+    // entities that changed together in past commits are coupled IN PRACTICE,
+    // whatever static analysis says. Weight provisional — revisit once
+    // corpus-wide lineage allows an entropy-style calibration.
+    history: 0.10,
 };
 function jaccard(a, b) {
     if (a.size === 0 && b.size === 0)
@@ -297,7 +302,27 @@ function intersect(a, b) {
             out.push(x);
     return out;
 }
-function classifyConflictTier(taskA, taskB) {
+/** Co-change pairs between two tasks, from a pre-fetched pair→count map keyed `${idA}
${idB}` (sorted). */
+function coChangePairs(taskA, taskB, coChange) {
+    if (!coChange || coChange.size === 0)
+        return [];
+    const out = [];
+    for (const a of taskA.entityIds) {
+        for (const b of taskB.entityIds) {
+            if (a === b)
+                continue;
+            const key = a < b ? `${a}
${b}` : `${b}
${a}`;
+            const n = coChange.get(key);
+            if (n && n >= 2)
+                out.push({ a, b, sharedCommits: n });
+        }
+    }
+    return out.sort((x, y) => y.sharedCommits - x.sharedCommits);
+}
+// ≥ this many shared commits between a cross-task entity pair = coupled in
+// practice, escalate to Tier 2 even when statically disjoint everywhere.
+const CO_CHANGE_TIER2_THRESHOLD = 3;
+function classifyConflictTier(taskA, taskB, coChange = null) {
     const sharedEntities = intersect(taskA.entityIds, taskB.entityIds);
     const sharedFiles = intersect(taskA.files, taskB.files);
     const sharedNeighbors = intersect(taskA.neighbors, taskB.neighbors);
@@ -319,16 +344,20 @@ function classifyConflictTier(taskA, taskB) {
     }
     const writeWrite = sharedTables.filter(t => t.taskA === 'write' && t.taskB === 'write');
     const readWrite = sharedTables.filter(t => t.taskA !== t.taskB);
+    // Historical co-change (lineage evidence)
+    const sharedHistory = coChangePairs(taskA, taskB, coChange);
+    const maxShared = sharedHistory[0]?.sharedCommits || 0;
     // Entropy-weighted evidence score in [0,1]
     const tablesA = new Set([...taskA.tablesRead, ...taskA.tablesWritten]);
     const tablesB = new Set([...taskB.tablesRead, ...taskB.tablesWritten]);
     const w = CONFLICT_WEIGHTS;
-    const totalW = w.symbols + w.epsilon + w.delta + w.files;
+    const totalW = w.symbols + w.epsilon + w.delta + w.files + w.history;
     const conflictScore = Math.round(((w.symbols * jaccard(taskA.entityIds, taskB.entityIds) +
         w.epsilon * jaccard(taskA.neighbors, taskB.neighbors) +
         w.delta * jaccard(tablesA, tablesB) +
-        w.files * jaccard(taskA.files, taskB.files)) / totalW) * 1000) / 1000;
-    const base = { conflictScore, sharedFiles, sharedEntities, sharedTables, sharedNeighbors };
+        w.files * jaccard(taskA.files, taskB.files) +
+        w.history * Math.min(1, maxShared / 5)) / totalW) * 1000) / 1000;
+    const base = { conflictScore, sharedFiles, sharedEntities, sharedTables, sharedNeighbors, sharedHistory };
     // Tier 3 — must sequence
     if (sharedEntities.length > 0) {
         return {
@@ -369,6 +398,16 @@ function classifyConflictTier(taskA, taskB) {
                 `(e.g. ${sharedNeighbors.slice(0, 3).join(', ')}) — review the shared interface before parallelizing`,
         };
     }
+    if (maxShared >= CO_CHANGE_TIER2_THRESHOLD) {
+        const top = sharedHistory[0];
+        return {
+            ...base,
+            tier: 2,
+            reason: `historical co-change — ${top.a.split('#').pop()} and ${top.b.split('#').pop()} changed together ` +
+                `in ${top.sharedCommits} past commits (${sharedHistory.length} coupled pair${sharedHistory.length === 1 ? '' : 's'} total); ` +
+                'statically disjoint but coupled in practice — review for an implicit shared contract before parallelizing',
+        };
+    }
     if (conflictScore > 0) {
         return {
             ...base,
@@ -444,7 +483,7 @@ function buildExecutionPlan(taskIds, tier3Edges) {
     };
 }
 // ─── Tool: conflict_matrix ────────────────────────────────────────
-export function conflictMatrix(args, loader) {
+export async function conflictMatrix(args, loader, extras = {}) {
     const projErr = validateProject(args.project, loader);
     if (projErr)
         return { error: projErr };
@@ -510,12 +549,23 @@ export function conflictMatrix(args, loader) {
     }
     // Pairwise comparison
     const matrix = [];
+    // Lineage-backed co-change evidence, fetched once for all tasks' entities
+    let coChange = null;
+    if (extras.fetchCoChanges) {
+        try {
+            const allIds = [...new Set(resolvedTasks.flatMap(t => [...t.entityIds]))];
+            coChange = await extras.fetchCoChanges(allIds);
+        }
+        catch {
+            warnings.push('co-change history unavailable for this run (lineage lookup failed) — tiers computed from static evidence only');
+        }
+    }
     const tier3Edges = [];
     for (let i = 0; i < resolvedTasks.length; i++) {
         for (let j = i + 1; j < resolvedTasks.length; j++) {
             const taskA = resolvedTasks[i];
             const taskB = resolvedTasks[j];
-            const result = classifyConflictTier(taskA, taskB);
+            const result = classifyConflictTier(taskA, taskB, coChange);
             const entry = {
                 taskA: taskA.id,
                 taskB: taskB.id,
@@ -531,6 +581,8 @@ export function conflictMatrix(args, loader) {
                 entry.sharedTables = result.sharedTables;
             if (result.sharedNeighbors.length > 0)
                 entry.sharedNeighbors = result.sharedNeighbors.slice(0, 10);
+            if (result.sharedHistory && result.sharedHistory.length > 0)
+                entry.sharedHistory = result.sharedHistory.slice(0, 10);
             matrix.push(entry);
             if (result.tier === 3) {
                 tier3Edges.push([taskA.id, taskB.id]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Semantic MCP server — exposes a codebase's structure, dependencies, and constraints as queryable tools",
   "type": "module",
   "bin": {