monomind 2.1.0 → 2.1.3

package/README.md

@@ -5,8 +5,8 @@
 <h1 align="center">Monomind</h1>
 
 <p align="center">
-  <strong>Hire an AI team. Set a goal. Walk away.</strong><br/>
-  Autonomous Claude Code orchestration with persistent memory, self-coordinating agent orgs, and a codebase knowledge graph.
+  <strong>An open-source MCP server that extends Claude Code with a codebase knowledge graph, persistent memory, and multi-agent coordination.</strong><br/>
+  MIT licensed &middot; Fully local &middot; No data leaves your machine
 </p>
 
 <p align="center">
@@ -30,126 +30,105 @@
 
 ## What is Monomind?
 
-Claude Code is already powerful. Monomind makes it **run itself**.
+Monomind is an **open-source CLI and MCP server** that plugs into Claude Code via the standard [Model Context Protocol](https://modelcontextprotocol.io/). It adds capabilities that Claude Code doesn't ship with out of the box:
 
-Install once. Wire it into Claude Code. Then instead of prompting Claude to do individual tasks, you tell Monomind what outcome you want — and it assembles a team, coordinates the work, and delivers.
+- **Codebase knowledge graph** — tree-sitter parses your code into a SQLite-backed graph of files, functions, classes, and their relationships. Query imports, callers, and blast radius before making changes.
+- **Persistent memory** — a JSON pattern store with episodic recall that survives across sessions. Agents and orgs share context without re-prompting.
+- **Multi-agent coordination** — in-session, spawn ad-hoc agent teams via Claude Code's Task tool; for persistent background work, `monomind org run` starts a real SDK-backed daemon with policy-gated role agents and a live dashboard.
+- **Reusable slash commands** — 30+ development workflows (build, review, debug, TDD, architecture) available as `/mastermind:*` commands inside Claude Code.
 
 ```bash
-# Assemble an AI content team and let it run
-/mastermind:createorg content-team "publish 3 SEO-optimized posts per week"
-/mastermind:runorg --org content-team
-
-# Or run the autonomous code improvement loop
-/mastermind:autodev --tillend --focus security
+npm install -g monomind        # MIT licensed, 0 external API calls
+cd your-project && monomind init
+claude mcp add monomind npx monomind mcp start
 ```
 
-That's it. Come back later.
+### Trust & Security
+
+| Concern | Answer |
+|---|---|
+| **License** | [MIT](LICENSE) — use it however you want |
+| **Data privacy** | Everything runs locally. No telemetry, no phone-home, no external API calls from Monomind itself. Your code stays on your machine. |
+| **Dependencies** | Standard npm packages (tree-sitter, sql.js, zod). No native binaries. No post-install scripts that download code. |
+| **Permissions** | Registers as an MCP server — Claude Code controls what tools are available and prompts you before executing anything sensitive. |
+| **Source** | Fully open. Read every line at [github.com/monoes/monomind](https://github.com/monoes/monomind). |
+| **Maintenance** | Active development, regular releases on npm. |
 
 ---
 
 ## 🏢 Autonomous Organizations
 
-> **This is the headline feature.** Build a persistent AI organization — roles, hierarchy, shared task board — and start it as a background daemon that runs without you.
+> **This is the headline feature.** `monomind org run` starts a persistent, SDK-backed daemon that runs an autonomous agent organization — roles, hierarchy, policy-gated tool access, a live dashboard — until you stop it.
 
 ### The idea
 
-Every business function needs a team. Monomind lets you design that team in one command, then run it forever. The org persists across sessions. It checkpoints, recovers from failures, and coordinates its agents through a shared task board — all automatically.
+Every business function needs a team. Define the org once as a JSON file — goal, roles, who reports to whom, per-role tool/file/budget policy — then run it as a real background daemon backed by the Claude Agent SDK. It persists across sessions, serves a live WebSocket dashboard, and can discover and message other Monomind orgs running on the same machine.
 
 ```mermaid
 flowchart TD
     U(["You"])
-    CO["/mastermind:createorg\nDefine goal + roles"]
-    RO["/mastermind:runorg\nStart daemon"]
-    BOSS["Boss Agent\ncoordinator"]
-    W["Writer\nContent Creator"]
+    DEF["org.json\nGoal + roles + policy"]
+    RUN["monomind org run\nStart SDK daemon"]
+    BOSS["Boss Agent\nAgent SDK session"]
+    W["Writer"]
     S["SEO Specialist"]
     R["Reviewer"]
-    M["Growth Marketer"]
-    BOARD[("Shared\nTask Board")]
-    MEM[("Persistent\nMemory")]
+    DASH[("Live Dashboard\n:4243")]
+    XORG[("Other orgs\ncross-process")]
 
-    U --> CO --> RO --> BOSS
+    U --> DEF --> RUN --> BOSS
     BOSS -->|spawns| W
     BOSS -->|spawns| S
     BOSS -->|spawns| R
-    BOSS -->|spawns| M
-    BOSS <-->|claims + reports| BOARD
-    W <-->|stores output| MEM
-    S <-->|reads context| MEM
+    RUN <-->|serves| DASH
+    RUN <-.->|--cross-process| XORG
 
     style BOSS fill:#00D2AA22,stroke:#00D2AA
-    style BOARD fill:#F59E0B22,stroke:#F59E0B
-    style MEM fill:#8B5CF622,stroke:#8B5CF6
-```
-
-### Two commands to a running org
-
-**Step 1 — Design it:**
-
+    style DASH fill:#F59E0B22,stroke:#F59E0B
+    style XORG fill:#8B5CF622,stroke:#8B5CF6
 ```
-/ mastermind:createorg content-team
-  "Build and publish 3 blog posts per week on AI dev tools"
-
-Deriving roles from goal...
-
-╔ ORG: content-team
-║ TOPOLOGY: star (5 roles)
 
-  boss      → coordinator
-  writer    → Content Creator
-  reviewer  → reviewer
-  marketer  → Growth Hacker
-  seo       → SEO Specialist
+### Run one
 
-Type "go" to save, or describe changes.
-→ go
+```bash
+# .monomind/orgs/<name>.json defines the org: goal, roles, policy.
+# See .monomind/orgs/sample-team.json in a fresh `monomind init` for a working example.
 
-✓ Saved .monomind/orgs/content-team.json
-  → Run: /mastermind:runorg --org content-team
-```
+monomind org run content-team --task "Build and publish 3 blog posts per week"
 
-**Step 2 — Start it:**
+# ✓ Live dashboard: http://localhost:4243
+# ✓ Boss agent (Claude Agent SDK session) spawns, reads the org goal,
+#   assigns work to role agents, coordinates until the task completes
+#   or you stop it.
 
-```bash
-/mastermind:runorg --org content-team
-
-# Boss agent spawns in background
-# Coordinates all roles via shared task board
-# Checkpoints every 30 minutes
-# Loops until you stop it
+monomind org status content-team    # runtime state
+monomind org stop content-team      # request a graceful stop
+monomind org list                   # every org + status
 ```
 
 ### What runs under the hood
 
 | What | How |
 |---|---|
-| **Boss agent** | Coordinator type, no supervisor — owns the goal |
-| **Role agents** | Spawned on demand, specialized by task type |
-| **Task board** | Todo → Doing → Done, shared across all agents |
-| **Memory** | All output stored in an org-scoped memory namespace |
-| **Checkpoint** | State saved every 30 min — survives crashes and restarts |
-| **Governance** | `auto` (free), `board` (approve sensitive), `strict` (approve all external actions) |
-
-### Topology is auto-derived
-
-```mermaid
-graph LR
-    A["1-3 roles"] -->|mesh| B["All-to-all\ndirect comms"]
-    C["4-6 roles"] -->|star| D["Boss to workers\nfan-out"]
-    E["7+ roles"] -->|hierarchical| F["Boss to leads to workers\nmiddle management"]
-```
+| **OrgDaemon** | Hosts one or more orgs in a single process; real Claude Agent SDK sessions per role, not simulated |
+| **PolicyEngine** | Per-role gates on tool access, file read/write scope, web access, token budget — enforced, with a full audit trail |
+| **Live dashboard** | WebSocket-served at `:4243` by default (`--port` to change, `--serve=false` to disable) |
+| **Cross-process comms** | `--cross-process` (default on) lets orgs on different `monomind` processes/projects discover and message each other |
+| **Scheduling** | `monomind org serve` hosts orgs whose definition has a `schedule` field, running them on interval |
 
 ### Org management commands
 
 ```bash
-/mastermind:createorg <name> "<goal>"   # design org from a goal
-/mastermind:runorg --org <name>         # start as background daemon
-/mastermind:orgs                        # list all orgs + status
-/mastermind:orgstatus --org <name>      # detailed status for one org
-/mastermind:stoporg --org <name>        # stop a running org
-/mastermind:approve                     # review pending approval requests
+monomind org run <name> [--task "..."] [--port N] [--cross-process]  # start a daemon
+monomind org stop <name>            # request a running org to stop
+monomind org status [name]          # runtime state for one or all orgs
+monomind org list                   # list every org + status
+monomind org serve [--port N]       # host-only mode, runs scheduled orgs
+monomind org delete <name>          # remove an org
 ```
 
+> **Note:** the older `/mastermind:createorg` + `/mastermind:runorg` prompt-orchestrated flow is deprecated — it has no delivery guarantees or ground-truth event stream. It still runs for orgs not yet migrated, but new orgs should use `monomind org run` directly against a hand-authored `.monomind/orgs/<name>.json`.
+
 ---
 
 ## ⚡ The Autonomous Build Loop
@@ -206,11 +185,11 @@ claude mcp add monomind npx monomind mcp start
 monomind doctor --fix
 ```
 
-Open Claude Code. You now have 80+ slash commands available:
+Open Claude Code. You now have 60+ slash commands available:
 
 ```bash
 /mastermind:autodev --tillend     # start autonomous code loop
-/mastermind:createorg my-team     # create your first AI org
+monomind org run my-team          # run your first AI org (see .monomind/orgs/sample-team.json)
 /mastermind:help                  # show all commands
 ```
 
@@ -262,7 +241,7 @@ Before touching any file, Monomind queries **Monograph** — a SQLite-backed kno
 
 ## 🎣 Hooks & Workers
 
-Monomind wires 22 hook events into Claude Code. Every edit, task, command, and session fires hooks that log patterns, route agents, and train the intelligence system.
+Monomind wires 29 hook subcommands into Claude Code across edit, task, command, and session lifecycle events — logging patterns, routing agents, and feeding the intelligence system.
 
 ```mermaid
 flowchart LR
@@ -296,7 +275,7 @@ const result = await fence.detect(userInput);
 
 ---
 
-## 📋 80+ Slash Commands
+## 📋 60+ Slash Commands
 
 Everything runs from inside Claude Code via slash commands. Here's the highlight reel:
 
@@ -315,9 +294,9 @@ Everything runs from inside Claude Code via slash commands. Here's the highlight
 ### Organizations
 | Command | What it does |
 |---|---|
-| `/mastermind:createorg` | Design an autonomous agent org |
-| `/mastermind:runorg` | Start it as a background daemon |
-| `/mastermind:orgs` | List all orgs + status |
+| `monomind org run <name>` | Start an org as a real SDK-backed daemon |
+| `monomind org status` / `list` | Runtime state for one or all orgs |
+| `monomind org stop <name>` | Request a graceful stop |
 | `/mastermind:approve` | Action pending approval requests |
 
 ### Business Domains
@@ -329,7 +308,7 @@ Everything runs from inside Claude Code via slash commands. Here's the highlight
 | `/mastermind:finance` | Budgets, invoicing, modeling |
 | `/mastermind:ops` | Operations and workflow automation |
 
-**[→ Full reference (80+ commands)](https://monoes.github.io/monomind/#slash)**
+**[→ Full reference (60+ commands)](https://monoes.github.io/monomind/#slash)**
 
 ---
 
@@ -351,24 +330,27 @@ graph TD
     CC["Claude Code"]
     MCP["MCP Server\nmonomind mcp start"]
     D["Background Workers\n(@monomind/hooks, in-process)"]
+    ORG["OrgDaemon\nmonomind org run\nreal SDK sessions"]
 
-    CC <-->|"MCP tools: monograph, memory, swarm"| MCP
+    CC <-->|"MCP tools: monograph, memory"| MCP
     MCP <--> D
 
     D --> ADB[("Memory store\npatterns + episodes")]
     D --> MG[("Monograph\ncode graph")]
-    D --> HK["Hooks\n22 event types"]
-    D --> SW["Swarm\n4 topologies\n3 consensus strategies"]
+    D --> HK["Hooks\n29 subcommands"]
 
-    CC -->|"Task tool - spawns agents"| AG["Agent Swarm\narchitect, coder\ntester, reviewer\nsecurity, perf"]
+    CC -->|"Task tool - spawns agents"| AG["In-session agents\narchitect, coder\ntester, reviewer\nsecurity, perf"]
     AG <-->|reads and writes| ADB
+    ORG -->|"spawns, policy-gated"| RA["Role agents"]
+    ORG <-->|reads and writes| ADB
 
     style CC fill:#00D2AA22,stroke:#00D2AA
     style AG fill:#8B5CF622,stroke:#8B5CF6
     style ADB fill:#F59E0B22,stroke:#F59E0B
+    style ORG fill:#F59E0B22,stroke:#F59E0B
 ```
 
-**Claude Code handles all execution.** MCP tools only coordinate. Your data never leaves your machine.
+**Claude Code's Task tool drives in-session multi-agent work; `monomind org run` drives persistent background orgs.** Your data never leaves your machine.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "monomind",
-  "version": "2.1.0",
-  "description": "Monomind - Power toolkit for Claude Code. Autonomous agent orgs, codebase knowledge graph, keyword-routed specialist prompts, and 80+ slash commands. One init, then walk away.",
+  "version": "2.1.3",
+  "description": "Open-source CLI extension for Claude Code. Adds an MCP server with a codebase knowledge graph, persistent memory, multi-agent coordination, and reusable slash commands. MIT licensed, runs locally, no data leaves your machine.",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -140,7 +140,7 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.0.0",
+    "typescript": "^7.0.2",
     "vite": ">=8.0.16",
     "vitest": "^4.1.4"
   },

package/packages/@monomind/cli/.claude/helpers/handlers/capture-handler.cjs

@@ -41,6 +41,18 @@ function subagentKey(hookInput) {
   return crypto.createHash('md5').update(String(raw)).digest('hex').slice(0, 16);
 }
 
+// Determine subagent success from its result summary — errors/failures/
+// exceptions indicate failure. Shared by the Monograph `success` column and
+// the intelligence.feedback() call below, so both use one definition.
+function deriveSubagentSuccess(summary) {
+  if (!summary) return true;
+  var sumLower = summary.toLowerCase();
+  if (sumLower.includes('error') || sumLower.includes('failed') || sumLower.includes('exception') || sumLower.includes('fatal')) {
+    return false;
+  }
+  return true;
+}
+
 // Delete snap-*.json files older than SNAP_MAX_AGE_MS — orphaned when a
 // SubagentStop never arrived (crash, forced-stop) or was matched to a
 // different snapshot before keyed matching existed.
@@ -345,6 +357,17 @@ async function handleSubagentStop(hookInput) {
     + (session ? ' · sess=' + session : '')
     + (org ? ' · ' + org + '/' + runId : ''));
 
+  // Feed the real per-subagent success/failure signal into the same
+  // intelligence-outcomes.jsonl that session-handler.cjs's SessionEnd
+  // heuristic reads (via outcomesSignal) to veto a commit-based "success".
+  // Without this, that veto path never fires — SubagentStop is the only
+  // remaining event that carries a genuine failure signal, since post-task
+  // (TeammateIdle/TaskCompleted) is dead code (those aren't valid Claude
+  // Code hook events and are stripped from settings.json on init).
+  try {
+    require('../intelligence.cjs').feedback(deriveSubagentSuccess(summary));
+  } catch (e) { /* non-fatal — feedback recording must never block subagent-stop */ }
+
   if (!org && !session) {
     // No active org or session — log to general capture file only
     // P2-26: rotate — was a pure appendFileSync with no cap, unlike
@@ -486,16 +509,7 @@ async function handleSubagentStop(hookInput) {
             tokens_in: totalTin || 0,
             tokens_out: totalTout || 0,
             cost_usd: costUsd || 0,
-            success: (function() {
-              // Determine success from result summary — errors/failures/exceptions indicate failure
-              if (summary) {
-                var sumLower = summary.toLowerCase();
-                if (sumLower.includes('error') || sumLower.includes('failed') || sumLower.includes('exception') || sumLower.includes('fatal')) {
-                  return 0;
-                }
-              }
-              return 1;
-            })(),
+            success: deriveSubagentSuccess(summary) ? 1 : 0,
             duration_ms: snap.ts ? (Date.now() - snap.ts) : 0,
             timestamp: Date.now(),
           });

package/packages/@monomind/cli/.claude/helpers/handlers/gates-handler.cjs

@@ -6,7 +6,7 @@
  * @monomind/guidance package it mirrored has been removed.
  *
  * Gates enforced at runtime:
- *   pre-bash  → destructive-ops  (require-confirmation → block)
+ *   pre-bash  → destructive-ops  (hard block; no confirm-and-proceed path exists)
  *   pre-write → secrets          (block)
  */
 
@@ -60,7 +60,7 @@ function checkDestructive(command) {
       return {
         triggered: true,
         matched: match[0],
-        reason: `Destructive operation detected: "${match[0]}". Confirm this is intentional and document a rollback plan before proceeding.`,
+        reason: `Destructive operation blocked: "${match[0]}". This hook always blocks (Claude Code's PreToolUse protocol has no confirm-and-proceed path) — there is no way to run this exact command after confirming. If it's genuinely intended, use a non-destructive equivalent instead (e.g. move the target aside, or scope the operation more narrowly).`,
       };
     }
   }

package/packages/@monomind/cli/.claude/helpers/handlers/route-handler.cjs

@@ -299,6 +299,35 @@ module.exports = {
             console.log('[CODEBASE] Graph index ' + mapData.graphStaleness.commitsBehind + ' commits behind HEAD — run monograph build');
           }
         }
+        // Graph gate connectivity nudge — the pre-search/pre-bash gate
+        // (utils/monograph.cjs _graphGateShouldBlock) hard-blocks the first
+        // Grep/Glob/bash-grep-or-find call each session until a real
+        // monograph_query/monograph_suggest call fires. If that block was
+        // never followed by a real graph call, the monomind MCP server is
+        // most likely not connected this session (config present but
+        // unapproved/not started) — surface it once so the user can fix the
+        // actual cause instead of the gate silently degrading to a no-op.
+        var graphGateFile = path.join(CWD, '.monomind', 'graph-gate-state.json');
+        var mcpWarnFile = path.join(CWD, '.monomind', 'mcp-not-connected-warned.json');
+        if (fs.existsSync(graphGateFile) && fs.statSync(graphGateFile).size < 4096) {
+          var gateState = JSON.parse(fs.readFileSync(graphGateFile, 'utf-8'));
+          var gateSessId = String((hCtx.hookInput && (hCtx.hookInput.sessionId || hCtx.hookInput.session_id)) || '');
+          if (gateState && gateState.sessionId === gateSessId && gateState.blockedOnce && !gateState.queried) {
+            var alreadyWarnedMcp = false;
+            if (fs.existsSync(mcpWarnFile)) {
+              try {
+                var mcpWarnData = JSON.parse(fs.readFileSync(mcpWarnFile, 'utf-8'));
+                if (mcpWarnData && mcpWarnData.sessionId === gateSessId) alreadyWarnedMcp = true;
+              } catch (e) { /* corrupt — warn again to be safe */ }
+            }
+            if (!alreadyWarnedMcp) {
+              console.log('[MCP] The graph gate blocked a search but no monograph_query/monograph_suggest call followed — the monomind MCP server is likely not connected this session. Run `claude mcp add monomind -- npx monomind@latest mcp start` (then restart), or approve the .mcp.json trust prompt if one is pending.');
+              try {
+                fs.writeFileSync(mcpWarnFile, JSON.stringify({ sessionId: gateSessId, warnedAt: new Date().toISOString() }));
+              } catch (e) { /* non-fatal */ }
+            }
+          }
+        }
         // Deep dive findings (god nodes, high-degree files from background analysis)
         var deepdiveFile = path.join(metricsDir, 'deepdive.json');
         if (fs.existsSync(deepdiveFile) && fs.statSync(deepdiveFile).size < 32768) {

package/packages/@monomind/cli/.claude/helpers/handlers/session-handler.cjs

@@ -41,34 +41,46 @@ module.exports = {
       if (fs.existsSync(lastRoutePath) && (function() { try { return fs.statSync(lastRoutePath).size <= MAX_ROUTE; } catch(_) { return false; } }())) {
         var lastRoute = JSON.parse(fs.readFileSync(lastRoutePath, 'utf-8'));
 
-        // Derive sessionSuccess from git commits (strongest signal: user committed = success)
+        // Derive sessionSuccess. A commit alone is not proof of success — a
+        // session can commit a partial fix and then hit repeated failures —
+        // so recent intelligence-outcomes are checked FIRST and can veto a
+        // commit-based "true" when they show a majority of failures.
         try {
           var execSync = require('child_process').execSync;
-          var recentCommits = execSync('git log --oneline --since="30 minutes ago" 2>/dev/null || true', { cwd: CWD, timeout: 3000, encoding: 'utf-8' }).trim();
-          if (recentCommits.length > 0) {
-            sessionSuccess = true;
+
+          var outcomesSignal = null; // majority success/failure from intelligence-outcomes, if any
+          var outcomesPath = path.join(CWD, '.monomind', 'data', 'intelligence-outcomes.jsonl');
+          var MAX_OUTCOMES = 512 * 1024;
+          if (fs.existsSync(outcomesPath) && (function() { try { return fs.statSync(outcomesPath).size <= MAX_OUTCOMES; } catch(_) { return false; } }())) {
+            var windowMs = 30 * 60 * 1000;
+            var cutoff = Date.now() - windowMs;
+            var outcomeLines = fs.readFileSync(outcomesPath, 'utf-8').trim().split('\n').filter(Boolean);
+            var recent = outcomeLines.map(function(l) {
+              try { return JSON.parse(l); } catch { return null; }
+            }).filter(function(e) { return e && e.ts && e.ts >= cutoff; });
+            if (recent.length > 0) {
+              var failures = recent.filter(function(e) { return e.success === false; }).length;
+              outcomesSignal = failures / recent.length < 0.5;
+            }
+          }
+
+          if (outcomesSignal === false) {
+            // Recent tool/command outcomes were majority failures — this
+            // overrides a commit, since committing doesn't undo those failures.
+            sessionSuccess = false;
           } else {
-            // No commits — check if files were modified (work in progress, not failure)
-            var gitStatus = execSync('git diff --name-only 2>/dev/null || true', { cwd: CWD, timeout: 3000, encoding: 'utf-8' }).trim();
-            // Modified files = probably still working; no changes at all = exploration or failure
-            if (gitStatus.length === 0) {
-              // Fall back to intelligence-outcomes as a weak signal
-              var outcomesPath = path.join(CWD, '.monomind', 'data', 'intelligence-outcomes.jsonl');
-              var MAX_OUTCOMES = 512 * 1024;
-              if (fs.existsSync(outcomesPath) && (function() { try { return fs.statSync(outcomesPath).size <= MAX_OUTCOMES; } catch(_) { return false; } }())) {
-                var windowMs = 30 * 60 * 1000;
-                var cutoff = Date.now() - windowMs;
-                var outcomeLines = fs.readFileSync(outcomesPath, 'utf-8').trim().split('\n').filter(Boolean);
-                var recent = outcomeLines.map(function(l) {
-                  try { return JSON.parse(l); } catch { return null; }
-                }).filter(function(e) { return e && e.ts && e.ts >= cutoff; });
-                if (recent.length > 0) {
-                  var failures = recent.filter(function(e) { return e.success === false; }).length;
-                  sessionSuccess = failures / recent.length < 0.5;
-                }
+            var recentCommits = execSync('git log --oneline --since="30 minutes ago" 2>/dev/null || true', { cwd: CWD, timeout: 3000, encoding: 'utf-8' }).trim();
+            if (recentCommits.length > 0) {
+              sessionSuccess = true;
+            } else {
+              // No commits — check if files were modified (work in progress, not failure)
+              var gitStatus = execSync('git diff --name-only 2>/dev/null || true', { cwd: CWD, timeout: 3000, encoding: 'utf-8' }).trim();
+              // Modified files = probably still working; no changes at all = exploration or failure
+              if (gitStatus.length === 0 && outcomesSignal !== null) {
+                sessionSuccess = outcomesSignal;
               }
+              // else: modified files exist, or no evidence either way (leave null)
             }
-            // else: modified files exist — work in progress, not evidence either way (leave null)
           }
         } catch (e) { /* non-critical — leave null (no evidence) */ }
 

package/packages/@monomind/cli/.claude/helpers/hook-handler.cjs

@@ -55,6 +55,7 @@ const {
   getMonographSuggestions, getMonographNeighbors,
   _recordGraphTelemetry, _injectCompactGraphMap,
   _findAffectedTests, _maybeRebuildMonograph,
+  _graphGateShouldBlock, _graphGateMarkQueried,
 } = monograph;
 
 const {
@@ -409,6 +410,15 @@ const handlers = {
     var isGrep = /\b(?:grep|rg|ag)\b/.test(cmd);
     var isFind = /\b(?:find|fd)\b/.test(cmd) && !isGrep;
     if (isGrep || isFind) {
+      var sessIdGate = String((hCtx.hookInput && (hCtx.hookInput.sessionId || hCtx.hookInput.session_id)) || '');
+      if (_graphGateShouldBlock(sessIdGate)) {
+        process.stderr.write(JSON.stringify({
+          decision: 'block',
+          reason: '[graph-gate] Call mcp__monomind__monograph_query or monograph_suggest before grep/rg/find for code exploration (CLAUDE.md). This blocks once per session — after your first monograph call (or this one warning), Bash grep/find work normally for the rest of the session.',
+        }) + '\n');
+        process.exitCode = 2;
+        return;
+      }
       var graphAssisted = false;
       if (_isGraphFresh()) {
         try {
@@ -659,6 +669,15 @@ const handlers = {
 
   'pre-search': () => {
     var tool = hCtx.toolName || '';
+    var sessIdGate = String((hCtx.hookInput && (hCtx.hookInput.sessionId || hCtx.hookInput.session_id)) || '');
+    if (_graphGateShouldBlock(sessIdGate)) {
+      process.stderr.write(JSON.stringify({
+        decision: 'block',
+        reason: '[graph-gate] Call mcp__monomind__monograph_query or monograph_suggest before ' + (tool || 'Grep/Glob') + ' for code exploration (CLAUDE.md). This blocks once per session — after your first monograph call (or this one warning), search tools work normally for the rest of the session.',
+      }) + '\n');
+      process.exitCode = 2;
+      return;
+    }
     var graphResolved = false;
     try {
       var grepPattern = (typeof toolInput === 'object' && toolInput !== null)
@@ -817,6 +836,8 @@ const handlers = {
   'post-graph-tool': () => {
     // Record monograph MCP tool calls as graph wins
     _recordGraphTelemetry('monograph_call');
+    var sessIdGate = String((hCtx.hookInput && (hCtx.hookInput.sessionId || hCtx.hookInput.session_id)) || '');
+    _graphGateMarkQueried(sessIdGate);
   },
 
   'graph-status': () => {

package/packages/@monomind/cli/.claude/helpers/utils/monograph.cjs

@@ -9,6 +9,25 @@ const { _getRecentEdits } = require('./telemetry.cjs');
 
 const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 
+// @monoes/monograph is "type":"module" with an exports map that has no
+// "require" condition — a bare `require('@monoes/monograph')` (or
+// require() of its package directory) always throws "No exports main
+// defined", regardless of whether the package is actually installed.
+// require()-ing the package's *resolved entry file* directly bypasses the
+// exports-map restriction and works via Node's require(esm) support (this
+// codebase targets Node 20+, which has it). Reads the entry path from the
+// package's own package.json instead of hardcoding "dist/src/index.js" so
+// this survives a future monograph dist-layout change.
+function _resolvePkgEntryFile(pkgDir) {
+  try {
+    var pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
+    var entry = (pkg.exports && pkg.exports['.'] && (pkg.exports['.'].import || pkg.exports['.'].default)) || pkg.main;
+    if (!entry) return null;
+    var full = path.join(pkgDir, entry);
+    return fs.existsSync(full) ? full : null;
+  } catch (e) { return null; }
+}
+
 function _requireMonograph() {
   var candidates = [
     path.join(CWD, 'node_modules/.pnpm/node_modules/@monoes/monograph'),
@@ -16,9 +35,21 @@ function _requireMonograph() {
     path.join(CWD, 'node_modules/@monoes/monograph'),
   ];
   for (var i = 0; i < candidates.length; i++) {
-    try { if (fs.existsSync(candidates[i])) return require(candidates[i]); } catch(e) {}
+    var entry = fs.existsSync(candidates[i]) ? _resolvePkgEntryFile(candidates[i]) : null;
+    if (entry) { try { return require(entry); } catch (e) {} }
+  }
+  // Ancestor-directory search — the equivalent of bare `require('@monoes/
+  // monograph')`'s own node_modules walk, needed since that call form can
+  // never succeed against this package's exports map.
+  var dir = CWD;
+  for (;;) {
+    var pkgDir = path.join(dir, 'node_modules', '@monoes', 'monograph');
+    var entry = fs.existsSync(pkgDir) ? _resolvePkgEntryFile(pkgDir) : null;
+    if (entry) { try { return require(entry); } catch (e) {} break; }
+    var parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
   }
-  try { return require('@monoes/monograph'); } catch(e) {}
   return null;
 }
 
@@ -257,6 +288,44 @@ function _recordGraphTelemetry(event) {
   } catch (e) { /* non-fatal */ }
 }
 
+// ─── Graph gate ─────────────────────────────────────────────────────────────
+// The pre-search/pre-bash heuristic assist above silently resolves Grep/Bash
+// patterns against the graph and counts that as a "graph win" even when the
+// agent never actually called monograph_query — so the graph-usage % can look
+// healthy while zero real monograph_call events ever fire. This gate forces
+// at least one real monograph_query/monograph_suggest call per session before
+// Grep/Glob/bash grep|find are allowed, by hard-blocking (exitCode 2) the
+// first such call each session. Capped at ONE block per session (never a
+// second) so a subagent with no monograph MCP tool access can't deadlock.
+function _graphGateStateFile() {
+  return path.join(CWD, '.monomind', 'graph-gate-state.json');
+}
+
+function _graphGateMarkQueried(sessionId) {
+  if (!sessionId) return;
+  try {
+    fs.mkdirSync(path.join(CWD, '.monomind'), { recursive: true });
+    fs.writeFileSync(_graphGateStateFile(), JSON.stringify({ sessionId: sessionId, queried: true }));
+  } catch (e) { /* non-fatal */ }
+}
+
+function _graphGateShouldBlock(sessionId) {
+  if (!sessionId || !_isGraphFresh()) return false;
+  var f = _graphGateStateFile();
+  var d = {};
+  try { d = JSON.parse(fs.readFileSync(f, 'utf-8')); } catch (e) {}
+  if (typeof d !== 'object' || d === null || d.sessionId !== sessionId) {
+    d = { sessionId: sessionId, queried: false, blockedOnce: false };
+  }
+  if (d.queried || d.blockedOnce) return false;
+  d.blockedOnce = true;
+  try {
+    fs.mkdirSync(path.join(CWD, '.monomind'), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify(d));
+  } catch (e) { return false; }
+  return true;
+}
+
 function _injectCompactGraphMap() {
   try {
     var db = _openMonographDb();
@@ -476,5 +545,7 @@ module.exports = {
   _injectCompactGraphMap,
   _findAffectedTests,
   _maybeRebuildMonograph,
+  _graphGateShouldBlock,
+  _graphGateMarkQueried,
   injectGodNodesContext,
 };