monomind 2.1.0 → 2.1.4

package/README.md

@@ -1,12 +1,12 @@
 <p align="center">
-  <img src="assets/banner.png" alt="Monomind" width="600" />
+  <img src="https://raw.githubusercontent.com/monoes/monomind/main/assets/banner.png" alt="Monomind" width="600" />
 </p>
 
 <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,106 @@
 
 ## 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, runs entirely on your machine
+cd your-project && monomind init
+claude mcp add monomind -- npx -y monomind@latest 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 — your code and memory store never leave your machine. The one exception: crash reporting is on by default (`monomind crash-reporting disable` to opt out) — a hard crash in monomind/mono-agent/monotask/mono-clip files a GitHub issue on that tool's own repo via the GitHub API. That's the only network call Monomind itself makes; it never phones a monoes-controlled server. |
+| **Dependencies** | Standard npm packages (tree-sitter, better-sqlite3, sql.js, zod). tree-sitter and better-sqlite3 are native (prebuilt) Node addons, not pure JS/WASM — sql.js is WASM. 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, streams live into the dashboard Claude Code auto-starts for the project, 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[("Dashboard\n:4242\nauto-started by\nClaude Code hook")]
+    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 -->|forwards events| DASH
+    RUN <-.->|--cross-process| XORG
 
     style BOSS fill:#00D2AA22,stroke:#00D2AA
-    style BOARD fill:#F59E0B22,stroke:#F59E0B
-    style MEM fill:#8B5CF622,stroke:#8B5CF6
+    style DASH fill:#F59E0B22,stroke:#F59E0B
+    style XORG fill:#8B5CF622,stroke:#8B5CF6
 ```
 
-### Two commands to a running org
-
-**Step 1 — Design it:**
-
-```
-/ 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.
+# Open the project in Claude Code first — a SessionStart hook auto-launches
+# the dashboard at http://localhost:4242 if it isn't already running.
 
-✓ 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:**
+# ✓ 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. Every event streams into the dashboard above.
 
-```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 |
+| **Dashboard** | `org run` forwards every event to the control server on `:4242` (found via `.monomind/control.json`) — that server is auto-launched by a Claude Code SessionStart hook, not by any CLI command; there's no separate per-org dashboard process |
+| **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 "..."] [--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 [--cross-process]  # 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
@@ -200,17 +180,17 @@ cd your-project
 monomind init
 
 # 3. Wire into Claude Code as an MCP server
-claude mcp add monomind npx monomind mcp start
+claude mcp add monomind -- npx -y monomind@latest mcp start
 
 # 4. Health check
 monomind doctor --fix
 ```
 
-Open Claude Code. You now have 80+ slash commands available:
+Open Claude Code. You now have 49 `/mastermind:*` workflows 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 +242,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 +276,7 @@ const result = await fence.detect(userInput);
 
 ---
 
-## 📋 80+ Slash Commands
+## 📋 49 Mastermind Commands
 
 Everything runs from inside Claude Code via slash commands. Here's the highlight reel:
 
@@ -315,9 +295,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 +309,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 (49 commands)](https://monoes.github.io/monomind/#slash)**
 
 ---
 
@@ -351,24 +331,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.4",
+  "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/commands/mastermind/createorg.md

@@ -1,4 +1,4 @@
-<!-- Define and save an autonomous agent organization — roles, hierarchy, and communication topology. Suggest or confirm roles, then persist the org for use with runorg. -->
+<!-- Define and save an autonomous agent organization (Org Runtime v2) — roles and hierarchy. Suggest or confirm roles, then persist the org config for `monomind org run`/`serve`. -->
 
 **If $ARGUMENTS is empty:** Output the following and wait.
 
@@ -6,7 +6,7 @@
 
 **MASTERMIND: CREATE ORG**
 
-An org is a named, persistent agent team — not a one-shot Mastermind run. Once created, the org runs autonomously across sessions: a boss agent coordinates specialists who pick up tasks from a shared board, execute them, and loop until stopped.
+An org is a named, persistent agent team, run by the Org Runtime v2 daemon — not a one-shot Mastermind run and not a Task-tool-spawned boss. Once created, every role in the config starts as its own live agent session the moment you run the org; roles message each other directly (no shared task board) and the org keeps running until stopped.
 
 Use orgs when the work is ongoing, not single-shot. A content team that ships 10 posts a month. A research squad that runs competitive scans weekly. A dev team with a permanent backlog.
 
@@ -25,16 +25,15 @@ Use orgs when the work is ongoing, not single-shot. A content team that ships 10
 ```
 
 **Options:**
-`--name <slug>` — org identifier used with `/mastermind:runorg` (derived from goal if omitted)
+`--name <slug>` — org identifier used with `monomind org run <name>` (derived from goal if omitted)
 `--roles <list>` — explicit role list (e.g. "boss, writer, reviewer, marketer")
-`--schedule <interval>` — make this a self-scheduling loop org (e.g. `"every 30 minutes"`, `"every hour"`, `"daily"`)
+`--schedule <interval>` — daemon schedule for `monomind org serve` to pick up, e.g. `"30m"`, `"2h"`, `"1440m"` for daily (omit for a manual, one-shot org)
 `--auto` — skip confirmation, create immediately
 `--confirm` — always ask before saving (default)
-`--delete <name>` — delete a saved org and all associated data files
-`--list` — list all saved orgs with their status
+`--delete <name>` — delete a saved org and all associated data files (`monomind org delete <name> --yes`)
+`--list` — list all saved orgs with their status (`monomind org list`)
 
-Once created, start the org with `/mastermind:runorg --org <name>`.
-For scheduled orgs: `runorg` activates the loop; `stoporg` stops it; `orgs` lists all.
+Once created, start the org with `monomind org run <name>` (foreground, one-shot) or let `monomind org serve` pick it up if `--schedule` was set. Check status with `monomind org status <name>`; stop with `monomind org stop <name>`.
 
 ---
 
@@ -47,7 +46,7 @@ Parse `$ARGUMENTS` for:
 - `--confirm` flag → mode = confirm
 - `--name <name>` → org_name = <name> (must match `^[a-z0-9][a-z0-9-]{0,63}$`; if omitted, derived from goal)
 - `--roles <desc>` → roles_desc = <desc> (explicit role list, e.g. "boss, writer, reviewer, marketer")
-- `--schedule <interval>` → schedule = <interval> (e.g. `"every 30 minutes"`, `"every hour"`, `"daily"`; triggers loop org generation)
+- `--schedule <interval>` → schedule = <interval>, daemon format only: `"<N>s"`, `"<N>m"`, or `"<N>h"` (e.g. `"30m"`, `"2h"`) — this is passed straight into `parseSchedule()` in `orgrt/scheduler.ts`, whose regex `^(\d+)\s*(s|m|h)$` rejects anything else (e.g. `"every 30 minutes"`, `"daily"`) and silently leaves the org unscheduled
 - `--delete <name>` → delete_mode = true, delete_name = <name>
 - `--list` flag → list_mode = true
 - Remaining text = prompt (goal description)

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': () => {