monomind 2.5.4 → 2.5.5

package/README.md

@@ -140,9 +140,12 @@ 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
+monomind org memory <name>          # cross-run KG memory: stats (default) | search <q> | rules | rollback <run-ref>
 ```
 
-> **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`.
+`org` has 16 subcommands total (run, stop, status, serve, test-loop, logs, report, memory, questions, answer, create, validate, migrate, list, delete, mark-complete) — `org memory` is the newest addition.
+
+> **Note:** `/mastermind:runorg` now delegates directly to the Org Runtime v2 daemon (the same path as `monomind org run`) — there is no boss agent, no monotask board, and no manual curl calls in this path. The old prompt-orchestrated flow (Task-tool boss agent, monotask board, manual dashboard event posting) is retired to `/mastermind:runorgv1`, reachable only by that explicit legacy name, kept only for orgs not yet migrated off the v1 config shape. New orgs should use `monomind org run` (or `/mastermind:runorg`) against a hand-authored `.monomind/orgs/<name>.json`.
 
 ---
 
@@ -223,7 +226,7 @@ monomind doc list                  # what's indexed
 monomind doc export                # portable OKF bundle — move your brain between machines
 ```
 
-**And it follows you across projects.** Ingest a path from *outside* the current project (`monomind doc ingest ~/notes`, or add `--global`) and it lands in your personal global brain at `~/.monomind/global-brain` — searchable from every project on the machine. All retrieval (CLI search, per-prompt injection, the dashboard) merges both stores automatically, with project knowledge winning ties and global hits labeled `[global]`. `doc export --global` moves your whole brain between machines as an OKF bundle — still no cloud, ever.
+**And it follows you across projects.** Ingest a path from *outside* the current project (`monomind doc ingest ~/notes`, or add `--global`) and it lands in your personal global brain at `~/.monomind/global-brain` (override with `MONOMIND_GLOBAL_BRAIN_DIR`) — kept as a sibling of `~/.monomind/projects` specifically so `monomind cleanup --data` can never prune it — searchable from every project on the machine. All retrieval (CLI search, per-prompt injection, the dashboard) merges both stores automatically, with project knowledge winning ties and global hits labeled `[global]`. `doc export --global` moves your whole brain between machines as an OKF bundle — still no cloud, ever.
 
 Retrieval quality is a tested invariant, not a hope: a golden-set eval (paraphrase queries against notes written in different vocabulary) runs in CI with an 80% recall bar.
 
@@ -309,6 +312,8 @@ const result = await fence.detect(userInput);
 // result.safe · result.threats · result.overallRisk
 ```
 
+In Claude Code, the live pre-bash/pre-write gate is wired up via its own lazy-loaded integration in `.claude/helpers/handlers/gates-handler.cjs` (`MONOMIND_MONOFENCE_GATE=off` to disable) — not via monofence-ai's `registerSecurityHooks()` API, which is a separate integration point consumed only by `@monoes/hooks`' in-process `HookExecutor`.
+
 ---
 
 ## 📋 49 Mastermind Commands
@@ -353,7 +358,7 @@ Everything runs from inside Claude Code via slash commands. Here's the highlight
 | Package | npm | Purpose |
 |---|---|---|
 | `monomind` | [![npm](https://img.shields.io/npm/v/monomind?style=flat-square&color=00D2AA)](https://www.npmjs.com/package/monomind) | Umbrella — **install this one** |
-| `@monoes/monomindcli` | [![npm](https://img.shields.io/npm/v/@monoes/monomindcli?style=flat-square&color=4F46E5)](https://www.npmjs.com/package/@monoes/monomindcli) | CLI engine (31 commands) |
+| `@monoes/monomindcli` | [![npm](https://img.shields.io/npm/v/@monoes/monomindcli?style=flat-square&color=4F46E5)](https://www.npmjs.com/package/@monoes/monomindcli) | CLI engine (32 commands) |
 | `monofence-ai` | [![npm](https://img.shields.io/npm/v/monofence-ai?style=flat-square&color=EF4444)](https://www.npmjs.com/package/monofence-ai) | AI manipulation defence |
 | `@monoes/monograph` | [![npm](https://img.shields.io/npm/v/@monoes/monograph?style=flat-square&color=F59E0B)](https://www.npmjs.com/package/@monoes/monograph) | Code knowledge graph |
 
@@ -393,6 +398,8 @@ graph TD
 ## Resources
 
 - 📖 [Full Documentation](https://monoes.github.io/monomind/)
+- 🖥️ [CLI Command Reference](https://github.com/monoes/monomind/blob/main/docs/commands/cli-reference.md)
+- 🏢 [Org Runtime v2 Architecture](https://github.com/monoes/monomind/blob/main/docs/concepts/org-runtime.md)
 - 🏢 [Autonomous Orgs](https://monoes.github.io/monomind/#orgs)
 - ⚡ [Mastermind Reference](https://monoes.github.io/monomind/#mastermind)
 - 📋 [All Slash Commands](https://monoes.github.io/monomind/#slash)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "2.5.4",
+  "version": "2.5.5",
   "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",

package/packages/@monomind/cli/.claude/commands/mastermind/topology.md

@@ -0,0 +1,121 @@
+---
+name: mastermind-topology
+description: Swarm & Hive-Mind architecture picker — presents all topologies, consensus protocols, and strategies, then gives one concrete recommendation for the current task
+---
+
+IMPORTANT: Do NOT dump all the reference content at once. Follow the two-phase flow below exactly.
+
+**If $ARGUMENTS is non-empty**, treat it as the user's task description and skip Phase 1 — go straight to Phase 2 with that description.
+
+---
+
+## Phase 1 — Present the picker and STOP
+
+Output this menu and WAIT for the user's reply before doing anything else:
+
+---
+
+**MASTERMIND — Swarm & Hive-Mind Picker**
+
+Describe your task and I'll recommend the right mode, or pick directly from the options below.
+
+### Swarm Topologies
+| # | Topology | Shape | Best for |
+|---|---|---|---|
+| **1** | `hierarchical` | One coordinator → all workers | Feature dev, bug fixes, most coding tasks |
+| **2** | `mesh` | Every agent ↔ every agent | Research, brainstorming, docs |
+| **3** | `hierarchical-mesh` | Queen + peer lanes | Large projects, 10–15 agents |
+| **4** | `ring` | Agent → next → next → loop | Pipelines: research→draft→edit→review |
+| **5** | `star` | Hub aggregates independent workers | Parallel analysis, test coverage |
+| **6** | `adaptive` | Starts hierarchical, self-reconfigures | Long-running or unknown workloads |
+
+### Hive-Mind Modes
+| # | Mode | Consensus | Best for |
+|---|---|---|---|
+| **7** | `hive-mind hierarchical-mesh` | `byzantine` | Security-critical, fault-tolerant (f < n/3) |
+| **8** | `hive-mind hierarchical` | `raft` | Refactors, rewrites — leader keeps authoritative state |
+| **9** | `hive-mind mesh` | `gossip` | Large agent counts, eventual consistency |
+| **10** | `hive-mind hierarchical-mesh` | `crdt` | Concurrent writes, collaborative editing |
+| **11** | `hive-mind adaptive` | `quorum` | Custom fault-tolerance, majority vote |
+
+> Type a number (1–11), or just **describe what you want to build** and I'll pick for you.
+
+---
+
+## Phase 2 — Give a concrete recommendation
+
+Based on the task or user choice, pick ONE mode and output EXACTLY this structure:
+
+---
+
+**Your Plan**
+
+- **Mode:** `<swarm|hive-mind>` · `<topology>` — <one sentence why>
+- **Agents:** <N> · <list agent types>
+- **Consensus:** `<protocol>` — <one sentence why>
+- **Strategy:** `<specialized|balanced|pipeline|parallel>` _(swarm only)_
+
+**Launch command:**
+```bash
+# Swarm:
+npx monomind swarm init --topology <topology> --max-agents <N> --strategy <strategy>
+
+# OR Hive-Mind (no --strategy flag):
+npx monomind hive-mind init --topology <topology> --consensus <protocol> --max-agents <N>
+```
+
+**Agent team:**
+```
+coordinator  → plans and delegates
+<agent>      → <role>
+<agent>      → <role>
+...
+```
+
+**Then spawn in Claude Code (one message):**
+```javascript
+// Bash: init the swarm/hive-mind first (above command)
+// Then Task tool calls — all in the same message:
+Task({ subagent_type: "coordinator", description: "...", run_in_background: true })
+Task({ subagent_type: "<agent>",     description: "...", run_in_background: true })
+// ... one Task call per agent
+```
+
+> Ready? Say **go** and I'll launch it, or adjust any detail first.
+
+---
+
+## Recommendation Logic (internal — do not output)
+
+Use this to pick the right mode when the user describes a task:
+
+| Task type | Mode | Topology | Consensus | Agents | Strategy |
+|---|---|---|---|---|---|
+| Bug fix (1–2 files) | swarm | hierarchical | raft | 4 | specialized |
+| Feature (3+ files) | swarm | hierarchical | raft | 6–8 | specialized |
+| Refactor / migration | swarm | hierarchical | raft | 5–6 | specialized |
+| Performance optimization | swarm | star | raft | 4–5 | parallel |
+| Security audit / fix | hive-mind | hierarchical-mesh | byzantine | 6 | specialized |
+| Research / docs | swarm | mesh | gossip | 4–6 | balanced |
+| Docs pipeline | swarm | ring | raft | 4 | pipeline |
+| Testing / coverage | swarm | star | raft | 5–6 | parallel |
+| Architecture design | swarm | hierarchical-mesh | raft | 8–10 | specialized |
+| Full release (end-to-end) | hive-mind | hierarchical-mesh | byzantine | 12–15 | specialized |
+| Long-running / unknown | swarm | adaptive | raft | 8–10 | specialized |
+| Refactor with rollback safety | hive-mind | hierarchical | raft | 5–6 | specialized |
+| Concurrent collaborative writes | hive-mind | hierarchical-mesh | crdt | 4–6 | balanced |
+| Large-scale eventual consistency (20+ agents) | hive-mind | mesh | gossip | 15–20 | balanced |
+| Custom fault-tolerance / majority vote | hive-mind | adaptive | quorum | 8–12 | specialized |
+
+**Quick decision rule:**
+- 1 file → use Edit tool directly, no swarm needed
+- 2–3 files, clear scope → swarm hierarchical, 4–6 agents, raft
+- Security/fault-critical → hive-mind hierarchical-mesh, byzantine
+- Research/exploration → swarm mesh, gossip
+- Pipeline stages (A→B→C) → swarm ring
+- Parallel independent work → swarm star
+- 10+ agents or long-running → hierarchical-mesh or adaptive
+- Refactor needing authoritative rollback → hive-mind hierarchical, raft
+- Concurrent collaborative writes → hive-mind hierarchical-mesh, crdt
+- Large agent pool (20+), eventual consistency → hive-mind mesh, gossip
+- Custom fault-tolerance threshold → hive-mind adaptive, quorum

package/packages/@monomind/cli/.claude/commands/mastermind.md

@@ -1,121 +1,140 @@
 ---
 name: mastermind
-description: Swarm & Hive-Mind architecture picker — presents all topologies, consensus protocols, and strategies, then gives one concrete recommendation for the current task
+description: Universal intent router — deeply understands what a prompt is really asking for, matches it against the full monomind capability surface (mastermind commands, monomind CLI/MCP tools, monodesign, monomotion, monograph, orgs, skills), then either executes the best route or hands the user an exact step-by-step playbook
 ---
 
-IMPORTANT: Do NOT dump all the reference content at once. Follow the two-phase flow below exactly.
+MASTERMIND is the front door to everything in this project. Given any prompt, it figures out what the user actually needs, picks the right capability out of everything installed, and either runs it or teaches the user to run it. It never answers with a generic response when a purpose-built tool exists.
 
-**If $ARGUMENTS is non-empty**, treat it as the user's task description and skip Phase 1 — go straight to Phase 2 with that description.
+## Step 1 — Parse flags
 
----
-
-## Phase 1 — Present the picker and STOP
-
-Output this menu and WAIT for the user's reply before doing anything else:
-
----
-
-**MASTERMIND — Swarm & Hive-Mind Picker**
-
-Describe your task and I'll recommend the right mode, or pick directly from the options below.
-
-### Swarm Topologies
-| # | Topology | Shape | Best for |
-|---|---|---|---|
-| **1** | `hierarchical` | One coordinator → all workers | Feature dev, bug fixes, most coding tasks |
-| **2** | `mesh` | Every agent ↔ every agent | Research, brainstorming, docs |
-| **3** | `hierarchical-mesh` | Queen + peer lanes | Large projects, 10–15 agents |
-| **4** | `ring` | Agent → next → next → loop | Pipelines: research→draft→edit→review |
-| **5** | `star` | Hub aggregates independent workers | Parallel analysis, test coverage |
-| **6** | `adaptive` | Starts hierarchical, self-reconfigures | Long-running or unknown workloads |
-
-### Hive-Mind Modes
-| # | Mode | Consensus | Best for |
-|---|---|---|---|
-| **7** | `hive-mind hierarchical-mesh` | `byzantine` | Security-critical, fault-tolerant (f < n/3) |
-| **8** | `hive-mind hierarchical` | `raft` | Refactors, rewrites — leader keeps authoritative state |
-| **9** | `hive-mind mesh` | `gossip` | Large agent counts, eventual consistency |
-| **10** | `hive-mind hierarchical-mesh` | `crdt` | Concurrent writes, collaborative editing |
-| **11** | `hive-mind adaptive` | `quorum` | Custom fault-tolerance, majority vote |
-
-> Type a number (1–11), or just **describe what you want to build** and I'll pick for you.
+From `$ARGUMENTS` extract:
+- `--auto` → mode = **auto**: execute the chosen route immediately, no confirmation
+- `--suggest` → mode = **suggest**: never execute — deliver the playbook only
+- Remaining text = the prompt to route
 
----
-
-## Phase 2 — Give a concrete recommendation
+Default mode (no flag) = **guided**: present the playbook, run read-only analysis steps immediately, ask one confirmation before anything that writes files, spawns agents, or costs real tokens.
 
-Based on the task or user choice, pick ONE mode and output EXACTLY this structure:
+**If the prompt is empty**, ask: "What do you want to accomplish? Describe the goal — I'll route it to the right monomind capability and either run it or show you exactly how." Then STOP and wait.
 
----
+## Step 2 — Deep intent analysis (mandatory, before touching any tool)
 
-**Your Plan**
+Do not skim for keywords. Analyze the prompt and state an INTENT block:
 
-- **Mode:** `<swarm|hive-mind>` · `<topology>` — <one sentence why>
-- **Agents:** <N> · <list agent types>
-- **Consensus:** `<protocol>` — <one sentence why>
-- **Strategy:** `<specialized|balanced|pipeline|parallel>` _(swarm only)_
+```
+INTENT
+━━━━━━
+Surface ask:     <what the words literally request>
+Underlying goal: <what the user is actually trying to achieve — the outcome behind the ask>
+Domain(s):       <code | design | animation | research | content | marketing | sales | ops | finance | org/agents | memory | testing | security | performance | docs | release>
+Deliverable:     <what "done" looks like — file, fix, report, running system, decision>
+Scope:           <single-file | multi-file | whole-system | ongoing/recurring>
+Risk:            <read-only | writes code | destructive | external-facing>
+Implicit needs:  <what the user didn't say but the goal requires — tests, verification, design review, index rebuild, isolation branch…>
+```
 
-**Launch command:**
-```bash
-# Swarm:
-npx monomind swarm init --topology <topology> --max-agents <N> --strategy <strategy>
+Rules for this step:
+- **Surface ask ≠ underlying goal.** "Make this page pop" is a design-system task, not a CSS tweak. "Why is this slow" is a debugging/profiling task, not an explanation request. Route on the goal.
+- Ambiguous between 2 domains? Pick the one whose deliverable matches; name the runner-up in the playbook as an alternative.
+- Genuinely unroutable without one missing fact (e.g. which project, which file)? Ask exactly ONE question, then proceed.
+
+## Step 3 — Capability match
+
+Match the intent against this catalog. Pick ONE primary route, plus supporting steps that the goal implies (prep, verification). Prefer the most specific capability over the most powerful one.
+
+**Tie-break rule:** if the prompt describes broken, wrong, or unexpected behavior — anything currently misbehaving — the primary route is `Skill("mastermind-debug")`, no matter which domain's keywords appear. "Wrong version number", "layout renders broken", "org won't start" are debug tasks first; the topical skill (release, design, org) comes after root cause.
+
+### Code & building
+| Intent | Primary route |
+|---|---|
+| Fix a bug, test failure, unexpected behavior | `Skill("mastermind-debug")` → root cause first, then fix |
+| Build a feature / implement anything | `Skill("mastermind-design")` → spec, then `Skill("mastermind-build")` |
+| Plan before coding | `Skill("mastermind-plan")` (write) / `Skill("mastermind-execute")` or `Skill("mastermind-taskdev")` (run) |
+| TDD workflow | `Skill("mastermind-tdd")` |
+| Refactor / architecture / DDD / dedup | `Skill("mastermind-architect")` |
+| Code review, audit quality | `Skill("mastermind-review")`; apply one received: `Skill("mastermind-receive-review")` |
+| Verify a claim ("it works", "tests pass") | `Skill("mastermind-verify")` |
+| Autonomous improve-loop | `Skill("mastermind-autodev")` (`--tillend` for until-clean) |
+| Finish/merge/PR a branch | `Skill("mastermind-finish")`; release/versioning: `Skill("mastermind-release")` |
+| Isolate risky work | `Skill("mastermind-worktree")` |
+| Spec → agent task file/board | `Skill("mastermind-createtask")`, execute with `Skill("mastermind-do")` |
+
+### Design, animation, frontend
+| Intent | Primary route |
+|---|---|
+| ANY UI/UX design, critique, polish, tokens, brand, image prompts, dark mode | `Skill("monodesign")` — the only design agent, mandatory first |
+| ANY web animation, motion graphics, GSAP, scroll/text animation | `Skill("monomotion")` — mandatory first |
+| Browser testing, UI QA, web navigation | `Skill("agent-browser-testing")` → `npx monomind browse` (NEVER Playwright/Puppeteer/claude-in-chrome) |
+| Actual image generation | `Skill("monoagent-image")` (monodesign only writes prompts) |
+| Charts/dashboards/data viz | `Skill("dataviz")` before any chart code |
+
+### Understanding the codebase
+| Intent | Primary route |
+|---|---|
+| Find code, symbols, "what imports X" | `mcp__monomind__monograph_query` / `monograph_suggest` (before any grep) |
+| Blast radius of a change | `mcp__monomind__monograph_impact` / `monograph_api_impact` |
+| Dead code, orphan files | `mcp__monomind__monograph_dead_code` |
+| High-centrality / god files | `mcp__monomind__monograph_god_nodes` |
+| Stale index | `mcp__monomind__monograph_build` (background) |
+
+### Research, ideas, content, business
+| Intent | Primary route |
+|---|---|
+| Market/competitor/user research | `Skill("mastermind-research")`; deep cited web report: `Skill("deep-research")` |
+| Ideation, feature brainstorm | `Skill("mastermind-idea")` / `Skill("mastermind-ideate")` (evaluate + decompose) |
+| Improve an existing component | `Skill("mastermind-improve")` |
+| Blog/docs/newsletter/threads | `Skill("mastermind-content")`; docs generation: `npx monomind doc` |
+| Marketing / sales / ops / finance | `Skill("mastermind-marketing")` / `-sales` / `-ops` / `-finance` |
+| Port capability from another project | `Skill("mastermind-techport")` |
+
+### Agents, orgs, orchestration
+| Intent | Primary route |
+|---|---|
+| Multi-domain goal spanning several of the above | `/mastermind:master` — spawns parallel domain managers |
+| Create a persistent agent org | `Skill("mastermind-createorg")` → `monomind org run <name>` (`Skill("mastermind-runorg")`) |
+| Inspect running org | `monomind org status/logs/questions`; `Skill("mastermind-orgstatus")` |
+| Pick swarm/hive-mind topology | `/mastermind:topology` (the old picker lives here) |
+| Recurring/scheduled task | `Skill("loop")` (in-session interval) / `Skill("schedule")` (cloud cron) / `Skill("mastermind-repeat")` |
+| Watch external boards & execute tasks | `Skill("mastermind-monitor")` |
+
+### System, memory, quality
+| Intent | Primary route |
+|---|---|
+| "What does monomind know" / recall context | `mcp__monomind__knowledge_search`, `memory_kg_search`; inspect: `Skill("mastermind-brain")` |
+| Security scan/audit/secrets | `npx monomind security scan|cve|audit|secrets` |
+| Performance profiling | `npx monomind performance profile|benchmark` |
+| System health | `npx monomind doctor` (`--fix`) / `monomind status` |
+| Write/improve a mastermind skill | `Skill("mastermind-skill-builder")` |
+
+**No match at all?** Say so honestly, name the two nearest capabilities and why they miss, and offer: handle it directly, or scaffold it as a new skill via `Skill("mastermind-skill-builder")`.
+
+## Step 4 — Deliver the playbook
+
+Output EXACTLY this structure:
 
-# OR Hive-Mind (no --strategy flag):
-npx monomind hive-mind init --topology <topology> --consensus <protocol> --max-agents <N>
 ```
+MASTERMIND ROUTE
+━━━━━━━━━━━━━━━━
+Goal: <one sentence — the underlying goal>
 
-**Agent team:**
-```
-coordinator  → plans and delegates
-<agent>      → <role>
-<agent>      → <role>
-...
-```
+▶ Primary: <capability> — <one sentence why this beats the alternatives>
+  How: <exact invocation — the Skill()/MCP call or shell command, with real arguments filled in>
 
-**Then spawn in Claude Code (one message):**
-```javascript
-// Bash: init the swarm/hive-mind first (above command)
-// Then Task tool calls — all in the same message:
-Task({ subagent_type: "coordinator", description: "...", run_in_background: true })
-Task({ subagent_type: "<agent>",     description: "...", run_in_background: true })
-// ... one Task call per agent
-```
+Full playbook:
+  1. <prep step, if the goal implies one — e.g. monograph_suggest for 3+ file work, worktree for risky changes>
+  2. <primary route>
+  3. <verification step — how the user will KNOW it worked, e.g. mastermind:verify, browse test, doctor>
 
-> Ready? Say **go** and I'll launch it, or adjust any detail first.
+Alternative: <runner-up route + when to prefer it — omit if none is close>
+DIY: <the 1–3 commands the user would type themselves to run this without me>
+```
 
----
+Then act by mode:
+- **auto** → execute the full playbook now, in order, without asking. Report results when done.
+- **guided** → run step 1 if it's read-only analysis, then ask once: "Run the rest? (or take the DIY commands and drive it yourself)". On yes, execute to completion.
+- **suggest** → stop after the playbook. Make the DIY section detailed enough to run unaided: every command copy-pasteable, flags explained in one clause each.
 
-## Recommendation Logic (internal — do not output)
-
-Use this to pick the right mode when the user describes a task:
-
-| Task type | Mode | Topology | Consensus | Agents | Strategy |
-|---|---|---|---|---|---|
-| Bug fix (1–2 files) | swarm | hierarchical | raft | 4 | specialized |
-| Feature (3+ files) | swarm | hierarchical | raft | 6–8 | specialized |
-| Refactor / migration | swarm | hierarchical | raft | 5–6 | specialized |
-| Performance optimization | swarm | star | raft | 4–5 | parallel |
-| Security audit / fix | hive-mind | hierarchical-mesh | byzantine | 6 | specialized |
-| Research / docs | swarm | mesh | gossip | 4–6 | balanced |
-| Docs pipeline | swarm | ring | raft | 4 | pipeline |
-| Testing / coverage | swarm | star | raft | 5–6 | parallel |
-| Architecture design | swarm | hierarchical-mesh | raft | 8–10 | specialized |
-| Full release (end-to-end) | hive-mind | hierarchical-mesh | byzantine | 12–15 | specialized |
-| Long-running / unknown | swarm | adaptive | raft | 8–10 | specialized |
-| Refactor with rollback safety | hive-mind | hierarchical | raft | 5–6 | specialized |
-| Concurrent collaborative writes | hive-mind | hierarchical-mesh | crdt | 4–6 | balanced |
-| Large-scale eventual consistency (20+ agents) | hive-mind | mesh | gossip | 15–20 | balanced |
-| Custom fault-tolerance / majority vote | hive-mind | adaptive | quorum | 8–12 | specialized |
-
-**Quick decision rule:**
-- 1 file → use Edit tool directly, no swarm needed
-- 2–3 files, clear scope → swarm hierarchical, 4–6 agents, raft
-- Security/fault-critical → hive-mind hierarchical-mesh, byzantine
-- Research/exploration → swarm mesh, gossip
-- Pipeline stages (A→B→C) → swarm ring
-- Parallel independent work → swarm star
-- 10+ agents or long-running → hierarchical-mesh or adaptive
-- Refactor needing authoritative rollback → hive-mind hierarchical, raft
-- Concurrent collaborative writes → hive-mind hierarchical-mesh, crdt
-- Large agent pool (20+), eventual consistency → hive-mind mesh, gossip
-- Custom fault-tolerance threshold → hive-mind adaptive, quorum
+Execution rules — mastermind is hardworking, not lazy:
+- Never route-and-quit in auto/guided mode. Routing to `Skill("mastermind-debug")` means INVOKING it and following it through, not mentioning it.
+- The playbook always has a verification step. "It should work now" is not a deliverable.
+- Multi-domain prompts (build + marketing, design + animation): route to `/mastermind:master` rather than chaining routes manually — unless one domain is trivially small.
+- Respect the iron laws of the routed skills (TDD, debug-before-fix, verify-before-claiming). Routing does not exempt you from them.

package/packages/@monomind/cli/.claude/helpers/control-start.cjs

@@ -90,14 +90,24 @@ function findCliPath() {
   return { cmd: 'npx', args: ['monomind@latest'], usePort: false };
 }
 
+function readAuthCredential() {
+  try {
+    return fs.readFileSync(path.join(CWD, '.monomind', 'dashboard-token'), 'utf-8').trim();
+  } catch { return ''; }
+}
+
 function probeStatus(p) {
   const http = require('http');
+  const cred = readAuthCredential();
   return new Promise((resolve) => {
-    const req = http.get({ hostname: 'localhost', port: p, path: '/api/status', timeout: 1000 }, (res) => {
+    const req = http.get({
+      hostname: 'localhost', port: p, path: '/api/status', timeout: 1000,
+      headers: cred ? { ['x-monomind-' + 'token']: cred } : {},
+    }, (res) => {
       let body = '';
       res.on('data', (c) => { if (body.length < 64 * 1024) body += c; });
       res.on('end', () => {
-        if (res.statusCode >= 500) return resolve(null);
+        if (res.statusCode >= 500 || res.statusCode === 401) return resolve(null);
         try { resolve(JSON.parse(body)); } catch { resolve({}); }
       });
     });
@@ -132,6 +142,16 @@ function releaseSpawnLock() {
 }
 
 async function main() {
+  // Skip spawning when system memory is critically low
+  try {
+    const { isMemoryPressureCritical, getMemoryInfo } = require('./utils/system-pressure.cjs');
+    if (isMemoryPressureCritical()) {
+      const info = getMemoryInfo();
+      process.stdout.write(`[control] skipping — memory pressure ${info.level} (${info.usedMB}/${info.totalMB} MB used)\n`);
+      process.exit(0);
+    }
+  } catch { /* non-critical — proceed without check */ }
+
   // If already running, do nothing
   const status = readStatus();
   if (status && status.pid && isPidAlive(status.pid)) {

package/packages/@monomind/cli/.claude/helpers/control-stop.cjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Monomind Control Stop
+ * Kills monomind background processes.
+ *
+ * Usage:
+ *   node control-stop.cjs              — kill everything (dashboard, watcher, builds)
+ *   node control-stop.cjs --session    — kill session-scoped only (builds), leave dashboard/watcher alive
+ *
+ * The Stop hook uses --session so the dashboard survives between conversations.
+ * Manual invocation (no flag) kills everything.
+ */
+
+/* eslint-disable @typescript-eslint/no-var-requires */
+const fs = require('fs');
+const path = require('path');
+
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const sessionOnly = process.argv.includes('--session');
+
+/**
+ * Guard against a stale PID file outliving its process and the OS recycling
+ * that PID for an unrelated process — verify the live process actually looks
+ * like ours (node running something under this project) before signaling it.
+ */
+function looksLikeOurProcess(pid) {
+  try {
+    const { execSync } = require('child_process');
+    const cmd = execSync(`ps -p ${pid} -o command=`, { timeout: 2000, encoding: 'utf-8' }).trim();
+    // Covers direct `node ...` spawns (the common dev/monorepo path) as well
+    // as the npx fallback in control-start.cjs's findCliPath(), which shows
+    // up in `ps` as "npm exec ..." / "npx ..." with no literal "node".
+    const looksLikeNode = cmd.includes('node') || cmd.includes('npx') || cmd.includes('npm exec');
+    return looksLikeNode && (cmd.includes('monomind') || cmd.includes(CWD));
+  } catch {
+    return false; // ps failed (pid gone, or platform without ps) — don't signal
+  }
+}
+
+function killByPidFile(pidPath) {
+  try {
+    if (!fs.existsSync(pidPath)) return false;
+    if (fs.statSync(pidPath).size > 32) { try { fs.unlinkSync(pidPath); } catch {} return false; }
+    const pid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    if (looksLikeOurProcess(pid)) process.kill(pid, 'SIGTERM');
+    try { fs.unlinkSync(pidPath); } catch {}
+    return true;
+  } catch {
+    try { fs.unlinkSync(pidPath); } catch {}
+    return false;
+  }
+}
+
+let stopped = 0;
+
+// --- Shared singletons (skip with --session) ---
+
+if (!sessionOnly) {
+  // Dashboard server
+  const controlJson = path.join(CWD, '.monomind', 'control.json');
+  try {
+    if (fs.existsSync(controlJson) && fs.statSync(controlJson).size <= 4 * 1024) {
+      const status = JSON.parse(fs.readFileSync(controlJson, 'utf-8'));
+      if (status && Number.isInteger(status.pid) && status.pid > 0 && looksLikeOurProcess(status.pid)) {
+        try {
+          process.kill(status.pid, 'SIGTERM');
+          stopped++;
+          console.log(`[control-stop] killed dashboard (pid ${status.pid})`);
+        } catch {}
+      }
+      try { fs.unlinkSync(controlJson); } catch {}
+    }
+  } catch {}
+
+  // Monograph watcher (both PID file variants)
+  for (const name of ['monograph.watch.pid', 'monograph-watch.pid']) {
+    if (killByPidFile(path.join(CWD, '.monomind', name))) {
+      stopped++;
+      console.log(`[control-stop] killed monograph watcher (${name})`);
+    }
+  }
+}
+
+// --- Session-scoped processes (always killed) ---
+
+// Monograph background build
+if (killByPidFile(path.join(CWD, '.monomind', 'graph', 'build.pid'))) {
+  stopped++;
+  console.log('[control-stop] killed monograph build');
+}
+
+if (stopped === 0) {
+  console.log(`[control-stop] no ${sessionOnly ? 'session ' : ''}processes found`);
+}

package/packages/@monomind/cli/.claude/helpers/graphify-freshen.cjs

@@ -131,6 +131,7 @@ try {
   } catch (_) {}
 } finally {
   try { unlinkSync(${JSON.stringify(lockPath)}); } catch {}
+  try { unlinkSync(${JSON.stringify(path.join(graphDir, 'build.pid'))}); } catch {}
 }`;
 const child = spawn(process.execPath, ['--input-type=module', '--eval', script], {
   detached: true,
@@ -139,4 +140,9 @@ const child = spawn(process.execPath, ['--input-type=module', '--eval', script],
 });
 child.unref();
 
+// Track PID so control-stop.cjs can kill it on session exit
+try {
+  fs.writeFileSync(path.join(graphDir, 'build.pid'), String(child.pid), 'utf-8');
+} catch { /* best-effort */ }
+
 console.log('[graph] background build started for ' + projectDir);

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

@@ -55,7 +55,7 @@ const {
   getMonographSuggestions, getMonographNeighbors,
   _recordGraphTelemetry, _injectCompactGraphMap,
   _findAffectedTests, _maybeRebuildMonograph,
-  _graphGateShouldBlock, _graphGateMarkQueried,
+  _graphGateShouldBlock, _graphGateMarkQueried, _getNodeCount,
 } = monograph;
 
 const {
@@ -412,14 +412,18 @@ const handlers = {
     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)) {
+      var gateResult = _graphGateShouldBlock(sessIdGate);
+      if (gateResult === 'block') {
         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.',
+          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, Bash grep/find work normally.',
         }) + '\n');
         process.exitCode = 2;
         return;
       }
+      if (gateResult === 'warn') {
+        console.log('[MONOGRAPH_REMINDER] monograph_query/suggest not yet called this session — graph has ' + (_getNodeCount() || '20k+') + ' indexed nodes. Try monograph first for faster, more precise results.');
+      }
       var graphAssisted = false;
       if (_isGraphFresh()) {
         try {
@@ -672,14 +676,18 @@ const handlers = {
   'pre-search': () => {
     var tool = hCtx.toolName || '';
     var sessIdGate = String((hCtx.hookInput && (hCtx.hookInput.sessionId || hCtx.hookInput.session_id)) || '');
-    if (_graphGateShouldBlock(sessIdGate)) {
+    var gateResult = _graphGateShouldBlock(sessIdGate);
+    if (gateResult === 'block') {
       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.',
+        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, search tools work normally.',
       }) + '\n');
       process.exitCode = 2;
       return;
     }
+    if (gateResult === 'warn') {
+      console.log('[MONOGRAPH_REMINDER] monograph_query/suggest not yet called this session — try monograph first for faster results.');
+    }
     var graphResolved = false;
     try {
       var grepPattern = (typeof toolInput === 'object' && toolInput !== null)