monomind 1.11.0 → 1.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "description": "Monomind - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",
@@ -127,4 +127,4 @@
     "access": "public",
     "tag": "latest"
   }
-}
+}

package/packages/@monomind/cli/dist/src/commands/hooks.js

@@ -1424,7 +1424,16 @@ const preTaskCommand = {
                 output.writeln(output.bold('Recommendations'));
                 output.printList(result.recommendations);
             }
-            // Enhanced model routing module was never shipped — no recommendation to add.
+            // Monograph graph-first reminder — always surface before the agent starts grepping
+            if (description) {
+                output.writeln();
+                output.writeln(output.bold('[MONOGRAPH] Graph-first protocol:'));
+                output.printList([
+                    `mcp__monomind__monograph_suggest task="${description.slice(0, 80)}" — get relevant nodes ranked by task`,
+                    'mcp__monomind__monograph_query   — BM25 lookup before any grep/find via Bash',
+                    'mcp__monomind__monograph_impact  — blast radius before editing shared code',
+                ]);
+            }
             return { success: true, data: result };
         }
         catch (error) {

package/packages/@monomind/cli/dist/src/init/claudemd-generator.js

@@ -17,7 +17,9 @@ function behavioralRules() {
 - NEVER save working files, text/mds, or tests to the root folder
 - Never continuously check status after spawning a swarm — wait for results
 - ALWAYS read a file before editing it
-- NEVER commit secrets, credentials, or .env files`;
+- NEVER commit secrets, credentials, or .env files
+- ALWAYS call \`mcp__monomind__monograph_query\` BEFORE running grep/rg/find via Bash for code exploration — only fall back to Bash grep if monograph returns 0 results or the DB does not exist
+- When starting any task that touches 3+ files: call \`mcp__monomind__monograph_suggest\` first to get relevant nodes ranked by task relevance`;
 }
 function codingPrinciples() {
     return `## Coding Principles
@@ -365,28 +367,50 @@ MONOMIND_MEMORY_PATH=./data/memory
 \`\`\``;
 }
 function graphifySection() {
-    return `## Knowledge Graph (Monograph)
-
-Built into monomind since v1.8.0 — no separate install needed. Pure TypeScript, no Python required.
-
-### MCP Tools (prefix: \`mcp__monomind__\`)
-
-| Tool | Description |
-|------|-------------|
-| \`monograph_build\` | Build or refresh knowledge graph from codebase |
-| \`monograph_report\` | Generate GRAPH_REPORT.md with community breakdown |
-| \`monograph_suggest\` | Get refactoring/architecture suggestions from graph |
-| \`monograph_health\` | Check graph quality score and experiment status |
-
-### How It Works
-
-1. **AST extraction** — parses TypeScript/JS/Python/Go/Rust into nodes + edges
-2. **Community detection** — Louvain algorithm finds logical clusters
-3. **Quality metric** — \`graphQuality = avgCohesion × ln(1 + avgDegree)\`
-4. **Experiment loop** — tracks BASELINE/KEEP/DISCARD in \`results.tsv\`
-5. **BFD chunking** — efficient Anthropic API calls via bin-packing
-
-> If monograph tools are not available, run \`npx monomind@latest init --force\` then restart Claude Code.`;
+    return `## Knowledge Graph — Monograph (Use Before Codebase Exploration)
+
+Built into monomind — no separate install. Pure TypeScript, parses TS/JS/Python/Go/Rust/C/C++/Java/Ruby/Swift into a SQLite graph with BM25 full-text search.
+
+### MANDATORY: Graph-First, Grep-Last
+
+**Before ANY grep/rg/find via Bash for code navigation:**
+1. Call \`mcp__monomind__monograph_query\` first — returns file path + line number
+2. Only fall back to Bash grep if monograph returns 0 results or reports DB missing
+
+**When starting any task touching 3+ files:**
+1. \`mcp__monomind__monograph_suggest\` — relevant nodes ranked by task description
+2. \`mcp__monomind__monograph_context\` — 360° view of a symbol (callers, callees, imports)
+3. \`mcp__monomind__monograph_impact\` — blast radius before changing anything
+
+**If graph is empty:** call \`mcp__monomind__monograph_build\` (runs in background; proceed with grep while it builds).
+
+### Available Tools (prefix: \`mcp__monomind__\`)
+
+| Tool | Use when |
+|------|----------|
+| \`monograph_suggest\` | **Start every multi-file task** — ranked by task relevance |
+| \`monograph_query\` | **Primary code lookup** — BM25 search, returns file + line |
+| \`monograph_context\` | 360° symbol view: callers, callees, imports, community |
+| \`monograph_impact\` | Blast radius before a change — transitive callers + risk score |
+| \`monograph_build\` | Build/rebuild the index (codeOnly:true for code-only) |
+| \`monograph_god_nodes\` | High-centrality files — find the most connected internal nodes |
+| \`monograph_detect_changes\` | Git diff → affected symbols since base branch |
+| \`monograph_rename\` | Dry-run multi-file rename — all reference sites, never writes |
+| \`monograph_route_map\` | List all HTTP routes with handler info |
+| \`monograph_api_impact\` | Blast radius of an API route |
+| \`monograph_cypher\` | Single-hop MATCH query over the graph |
+| \`monograph_staleness\` | Git commits since last index build |
+| \`monograph_stats\` | Node/edge/community counts |
+| \`monograph_health\` | Index freshness vs current HEAD |
+| \`monograph_shortest_path\` | Shortest dependency path between two symbols |
+| \`monograph_community\` | All nodes in a community cluster |
+| \`monograph_export\` | Export graph: json, svg, graphml, cypher, obsidian |
+| \`monograph_augment\` | Graph-RAG context block for AI prompts |
+| \`monograph_doctor\` | Platform diagnostics (Node version, DB health) |
+| \`monograph_list_repos\` | Global registry of indexed repos |
+
+### Skip monograph for
+Single-file edits, doc/config changes, quick fixes where you already know the exact file.`;
 }
 function setupAndBoundary() {
     return `## Quick Setup

package/packages/@monomind/cli/dist/src/mcp-tools/monograph-compat.d.ts

@@ -198,6 +198,7 @@ export declare function getSchemaResource(db: Db): {
 export declare function getGraphResource(db: Db): {
     nodes: unknown[];
     edges: unknown[];
+    capturedAt: string;
 };
 export declare function getMonographCypher(db: Db, query: string): {
     rows: Record<string, unknown>[];

package/packages/@monomind/cli/dist/src/mcp-tools/monograph-compat.js

@@ -229,12 +229,14 @@ export function detectMonographChanges(db, opts, repoPath) {
     const affectedSymbols = [];
     const seenIds = new Set();
     for (const rel of changedFiles) {
-        const abs = join(repoPath, rel);
-        const nodes = getNodesForFile(db, abs);
+        // DB stores relative paths; try both relative and absolute to be safe
+        const nodes = getNodesForFile(db, rel).length > 0
+            ? getNodesForFile(db, rel)
+            : getNodesForFile(db, join(repoPath, rel));
         for (const n of nodes) {
             if (!seenIds.has(n.id)) {
                 seenIds.add(n.id);
-                affectedSymbols.push({ id: n.id, name: n.name, label: n.label, filePath: n.filePath ?? abs });
+                affectedSymbols.push({ id: n.id, name: n.name, label: n.label, filePath: n.filePath ?? rel });
             }
         }
     }
@@ -351,7 +353,8 @@ export async function getMonographStaleness(repoPath) {
     if (existsSync(dbPath)) {
         const db = openDb(dbPath);
         try {
-            const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get();
+            // monomind's indexer writes ua_last_commit; published monograph@1.1.0 writes lastCommit
+            const meta = db.prepare("SELECT value FROM index_meta WHERE key IN ('ua_last_commit','lastCommit') LIMIT 1").get();
             lastCommit = meta?.value ?? null;
         }
         finally {
@@ -379,7 +382,7 @@ export async function getMonographStaleness(repoPath) {
         catch { /* skip */ }
         if (commitsBehind > 0) {
             try {
-                firstDivergingCommitTime = execSync(`git show -s --format=%cI ${lastCommit}..HEAD -- | head -1`, {
+                firstDivergingCommitTime = execSync(`git log -1 --format=%cI ${lastCommit}..HEAD`, {
                     cwd: repoPath, encoding: 'utf-8',
                 }).trim() || undefined;
             }
@@ -503,19 +506,17 @@ export function getSchemaResource(db) {
 }
 // 10d. getGraphResource
 export function getGraphResource(db) {
-    let nodes = [];
-    let edges = [];
     try {
         const snap = snapshotFromDb(db);
-        // snapshotFromDb returns a graphology graph; export via raw SQL for a stable shape
-        nodes = db.prepare('SELECT * FROM nodes LIMIT 2000').all();
-        edges = db.prepare('SELECT * FROM edges LIMIT 10000').all();
+        return {
+            nodes: snap.nodes.slice(0, 2000),
+            edges: snap.edges.slice(0, 10000),
+            capturedAt: snap.capturedAt,
+        };
     }
     catch {
-        nodes = db.prepare('SELECT * FROM nodes LIMIT 2000').all();
-        edges = db.prepare('SELECT * FROM edges LIMIT 10000').all();
+        return { nodes: [], edges: [], capturedAt: new Date().toISOString() };
     }
-    return { nodes, edges };
 }
 // ─── Tier 2: Best-effort / correctly-shaped degradation ───────────────────────
 // 11. getMonographCypher — minimal single-hop MATCH evaluator
@@ -694,7 +695,25 @@ export async function injectAiContext(opts) {
     const { repoPath, targets = ['claude', 'agents-md'] } = opts;
     const SENTINEL_START = '<!-- monograph:start -->';
     const SENTINEL_END = '<!-- monograph:end -->';
-    const block = `${SENTINEL_START}\n## Monograph Knowledge Graph\n\nMonograph provides code intelligence via graph-based search.\nTools: monograph_query, monograph_context, monograph_impact, monograph_route_map, monograph_cypher.\n${SENTINEL_END}`;
+    const block = `${SENTINEL_START}
+## Knowledge Graph — Monograph (Use Before Codebase Exploration)
+
+**MANDATORY: Graph-First, Grep-Last.**
+Before ANY grep/rg/find via Bash for code navigation, call \`mcp__monomind__monograph_query\` first.
+Only fall back to Bash grep if monograph returns 0 results or the DB is missing.
+
+When starting any task touching 3+ files:
+1. \`mcp__monomind__monograph_suggest\` — relevant nodes ranked by task description
+2. \`mcp__monomind__monograph_context\` — 360° view of a symbol (callers, callees, imports)
+3. \`mcp__monomind__monograph_impact\` — blast radius before changing anything
+
+Key tools: monograph_query (BM25 search, file+line), monograph_context (symbol 360°),
+monograph_impact (blast radius), monograph_detect_changes (git diff → symbols),
+monograph_rename (dry-run multi-file rename), monograph_route_map (HTTP routes),
+monograph_cypher (single-hop graph query), monograph_augment (graph-RAG context).
+
+If graph is empty: call monograph_build (codeOnly:true) and proceed with grep while it builds.
+${SENTINEL_END}`;
     const updated = [];
     const fileMaps = {
         'claude': join(repoPath, 'CLAUDE.md'),
@@ -901,7 +920,7 @@ export async function getGroupList(configPath) {
             try {
                 const db = openDb(dbPath);
                 nodeCount = countNodes(db);
-                const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'indexedAt'").get();
+                const meta = db.prepare("SELECT value FROM index_meta WHERE key IN ('ua_analyzed_at','indexedAt') LIMIT 1").get();
                 indexedAt = meta?.value ?? null;
                 closeDb(db);
             }
@@ -1028,12 +1047,12 @@ export async function getGroupStatus(configPath) {
             const db = openDb(dbPath);
             const nc = countNodes(db);
             const contracts = db.prepare("SELECT COUNT(*) as n FROM nodes WHERE label = 'Route'").get();
-            const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get();
+            const meta = db.prepare("SELECT value FROM index_meta WHERE key IN ('ua_last_commit','lastCommit') LIMIT 1").get();
             closeDb(db);
             groups.push({
                 name,
                 indexed: nc > 0,
-                stale: false, // we'd need git to detect; default false
+                stale: false, // git-based staleness check requires repoPath; default false
                 contractCount: contracts?.n ?? 0,
                 ...(meta?.value ? { lastSync: meta.value } : {}),
             });
@@ -1055,9 +1074,9 @@ export async function serveMonograph(opts) {
     if (_httpServer) {
         return { status: 'already_running', url: _serverUrl ?? `http://localhost:${port}` };
     }
-    const nodes = opts.db.prepare('SELECT * FROM nodes LIMIT 500').all();
-    const edges = opts.db.prepare('SELECT * FROM edges LIMIT 3000').all();
-    const html = toHtml(nodes, edges);
+    // snapshotFromDb returns camelCase nodes/edges as toHtml expects (filePath, communityId, sourceId, targetId)
+    const snap = snapshotFromDb(opts.db);
+    const html = toHtml(snap.nodes.slice(0, 500), snap.edges.slice(0, 3000));
     _httpServer = createServer((req, res) => {
         res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
         res.end(html);

package/packages/@monomind/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monomindcli",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "type": "module",
   "description": "Monomind CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -113,4 +113,4 @@
     "access": "public",
     "tag": "latest"
   }
-}
+}