@monoes/monomindcli 1.10.54 → 1.10.55

package/.claude/commands/mastermind/understand.md

@@ -0,0 +1,139 @@
+---
+name: mastermind:understand
+description: "Monomind — Run semantic enrichment on the current project's monograph knowledge graph. Uses the active Claude Code session for LLM work — no API key needed."
+---
+
+# /mastermind:understand — Semantic Enrichment
+
+Enriches the current project's monograph knowledge graph with summaries, architectural
+layers, and semantic relationships.
+
+**Designed to run inside Claude Code** — uses YOUR current session for LLM work via
+the Task tool. No `ANTHROPIC_API_KEY` required. The script handles layer detection
+and DB writes; you (Claude) handle per-file summarization.
+
+## Parse Arguments
+
+Parse `$ARGUMENTS` for these flags:
+
+- `--dir <path>`      — project directory (default: cwd)
+- `--db <path>`       — monograph.db path (default: `<dir>/.monomind/monograph.db`)
+- `--full`            — force full re-analysis
+- `--no-llm`          — heuristic-only mode (no per-file summaries)
+- `--layers-only`     — skip per-file analysis, only re-detect layers
+- `--max-files <N>`   — stop after N files (0 = all)
+- `--dry-run`         — show what would happen, don't write
+
+Bare path argument → `--dir`.
+
+---
+
+## Step 1: Locate project, DB, and script
+
+```bash
+DIR="${ARGUMENTS_dir:-$(pwd)}"
+DB="${ARGUMENTS_db:-$DIR/.monomind/monograph.db}"
+
+# Find understand-analyze.mjs (ships with monomind globally)
+GLOBAL_ROOT=$(npm root -g 2>/dev/null)
+SCRIPT="$GLOBAL_ROOT/monomind/packages/@monomind/cli/scripts/understand-analyze.mjs"
+[ ! -f "$SCRIPT" ] && SCRIPT="$GLOBAL_ROOT/@monoes/monomindcli/scripts/understand-analyze.mjs"
+```
+
+If `$DB` does not exist:
+> monograph.db not found at `$DB`. Build it first: `npx monomind monograph build`
+
+If `$SCRIPT` does not exist:
+> understand engine missing. Update: `npm install -g monomind@latest`
+
+In either case, STOP.
+
+---
+
+## Step 2: Run the script in heuristic mode (always — fast and deterministic)
+
+This step is non-negotiable. The script handles:
+- File node discovery from monograph.db
+- Heuristic layer detection from file paths
+- DB writes (community_id + properties)
+- graph.json emission to `.understand/knowledge-graph.json`
+- Auto-shadowing the DB to `/tmp` when it lives on a network FS
+
+```bash
+node "$SCRIPT" --dir "$DIR" --db "$DB" --no-llm
+```
+
+Wait for completion. Capture stdout. Note how many file nodes were found and how
+many layers were detected. Do NOT advise the user about API keys.
+
+---
+
+## Step 3: Per-file summarization (ONLY if `--no-llm` and `--layers-only` are both UNSET)
+
+This is where YOU (the current Claude session) do the LLM work. The script left
+behind a fresh `.understand/knowledge-graph.json` with placeholder summaries.
+
+1. Read `.understand/knowledge-graph.json`. For each node where `properties.fileSummary`
+   is empty or marked `[heuristic]`, do the following:
+   - Use the `Read` tool on `node.file_path` (relative to `$DIR`).
+   - Produce a JSON object: `{ id, fileSummary, tags, complexity, functionSummaries, classSummaries }`
+     where:
+     - `fileSummary`: 1-2 sentences explaining what the file does
+     - `tags`: array of 2-5 short tags
+     - `complexity`: "simple" | "moderate" | "complex"
+     - `functionSummaries`: top-5 functions → 1-sentence each
+     - `classSummaries`: classes → 1-sentence each
+2. Process files in batches of 5 for efficiency. Use `--max-files` to cap if set.
+3. Collect all analyses into an `analyses` array.
+
+If `$ARGUMENTS` includes `--no-llm` or `--layers-only`, SKIP this step entirely.
+
+---
+
+## Step 4: Write analyses back to the DB
+
+Pipe the collected analyses to a small re-import:
+
+```bash
+echo "$ANALYSES_JSON" | node "$SCRIPT" --dir "$DIR" --db "$DB" --import-analyses-stdin
+```
+
+(If your `analyses` array is empty, skip this step.)
+
+---
+
+## Step 5: Report
+
+```
+╔══════════════════════════════════════════════════╗
+║  /mastermind:understand — Enrichment Done           ║
+╠══════════════════════════════════════════════════╣
+║  DB:              .monomind/monograph.db          ║
+║  Files analyzed:  <N>                             ║
+║  LLM summaries:   <N> (via active session)        ║
+║  Layers:          <N>                             ║
+║  graph.json:      .understand/knowledge-graph.json║
+╚══════════════════════════════════════════════════╝
+```
+
+If LLM summaries = 0 (because `--no-llm` was set), say "heuristic-only mode — no per-file summaries written".
+
+Then:
+> Open the Monomind control panel and click **Monograph → GRAPH** to see layers.
+> Each color = one architectural layer (API, Service, Data, UI, etc.).
+>
+> Follow-ups:
+> - `/mastermind:understand --full` — re-run from scratch
+> - `/mastermind:understand --layers-only` — refresh only layers
+> - `/mastermind:understand --no-llm` — heuristic-only mode
+
+---
+
+## Error Handling
+
+- Do NOT prompt the user to set `ANTHROPIC_API_KEY`. LLM work happens in this session.
+- If the script exits non-zero: show stderr and suggest `npm install -g monomind@latest`.
+- If monograph.db has no file nodes: tell the user to run `npx monomind monograph build` first.
+- All errors are non-fatal — report and return cleanly.
+
+To re-run on a schedule: wrap with `/mastermind:repeat`.

package/.claude/commands/mastermind/verify.md

@@ -0,0 +1,22 @@
+---
+name: mastermind-verify
+description: Run the verification gate before claiming any work is complete, fixed, or passing — evidence before assertions always.
+---
+
+**First — extract repeat flags:** Follow the REPEAT PREAMBLE from `_repeat.md`.
+
+Parse `$ARGUMENTS` for `--auto`, `--confirm`, `--project <name>`, and remaining text = claim_or_task.
+
+Load brain context for the `verify` domain (follow `_protocol.md` Brain Load Procedure).
+
+If claim_or_task is empty: ask "What claim or task needs verification?"
+
+Default mode: **auto**.
+
+---
+
+Invoke `Skill("mastermind:verify")` passing: brain_context, claim_or_task, project_name, mode.
+
+After skill returns: follow `_protocol.md` Brain Write Procedure for domain `verify`.
+
+Invoke `Skill("mastermind:_repeat")` now to execute the REPEAT POSTAMBLE. This is a required tool call — do not skip it.

package/.claude/commands/mastermind/worktree.md

@@ -0,0 +1,20 @@
+---
+name: mastermind-worktree
+description: Use when starting feature work that needs isolation from the current workspace or before executing implementation plans — sets up an isolated git worktree
+---
+
+**First — extract repeat flags:** Follow REPEAT PREAMBLE from `_repeat.md`.
+
+Parse `$ARGUMENTS` for `--auto`, `--confirm`, `--project <name>`, and remaining text.
+
+Load brain context (follow `_protocol.md` Brain Load Procedure).
+
+Default mode: **auto**.
+
+---
+
+Invoke `Skill("mastermind:worktree")` passing: brain_context, params, mode.
+
+After skill returns: follow `_protocol.md` Brain Write Procedure.
+
+Invoke `Skill("mastermind:_repeat")` now. Required — do not skip.

package/.claude/helpers/handlers/graph-status-handler.cjs

@@ -27,7 +27,8 @@ module.exports = {
                + (usage.graph_assist_search || 0) + (usage.graph_assist_neighbors || 0);
       var search = (usage.grep_call || 0) + (usage.glob_call || 0)
                  + (usage.bash_grep_call || 0) + (usage.bash_find_call || 0);
-      var pct = (wins + search) > 0 ? Math.round((wins / (wins + search)) * 100) : 0;
+      var total = wins + search + (usage.preresolve_miss || 0);
+      var pct = total > 0 ? Math.round((wins / total) * 100) : 0;
       var saved = usage.dollars_saved || 0;
       console.log('Monograph: ' + n.toLocaleString() + ' nodes · ' + e.toLocaleString() + ' edges');
       console.log('Usage: ' + pct + '% graph · ' + (100 - pct) + '% grep · ' +

package/.claude/helpers/hook-handler.cjs

@@ -267,6 +267,25 @@ const handlers = {
     h.handle(hCtx);
   },
 
+  'pre-bash': () => {
+    // Record bash grep/find calls for graph-vs-grep telemetry
+    var cmd = (hCtx.toolInput && (hCtx.toolInput.command || hCtx.toolInput.cmd)) || '';
+    if (/\bgrep\b/.test(cmd)) _recordGraphTelemetry('bash_grep_call');
+    else if (/\bfind\b/.test(cmd)) _recordGraphTelemetry('bash_find_call');
+  },
+
+  'pre-search': () => {
+    // Record Grep/Glob tool calls for graph-vs-grep telemetry
+    var tool = hCtx.toolName || '';
+    if (tool === 'Grep') _recordGraphTelemetry('grep_call');
+    else if (tool === 'Glob') _recordGraphTelemetry('glob_call');
+  },
+
+  'post-graph-tool': () => {
+    // Record monograph MCP tool calls as graph wins
+    _recordGraphTelemetry('monograph_call');
+  },
+
   'graph-status': () => {
     const h = require('./handlers/graph-status-handler.cjs');
     h.handle(hCtx);

package/.claude/helpers/skill-registry.json

@@ -956,6 +956,29 @@
       "category": "swarm",
       "primaryAgent": "architect"
     },
+    {
+      "skill": "mastermind:autodev",
+      "invoke": "Skill(\"mastermind:autodev\")",
+      "description": "Autonomous research → build → review loop. Researches the project, picks the best improvement idea, builds it, then reviews with mastermind:review --tillend until clean. Repeats N times (e.g. /mastermind:autodev 9 builds 9 improvements). Supports --tillend, --focus, --count.",
+      "keywords": [
+        "autodev",
+        "autonomous",
+        "auto build",
+        "research",
+        "improve",
+        "improvement",
+        "feature",
+        "loop",
+        "build and review",
+        "self-improving",
+        "auto feature",
+        "continuous improvement",
+        "auto improve",
+        "research and build"
+      ],
+      "category": "dev",
+      "primaryAgent": "coder"
+    },
     {
       "skill": "mastermind:monitor",
       "invoke": "Skill(\"mastermind:monitor\")",

package/.claude/helpers/statusline.cjs

@@ -837,7 +837,7 @@ function getGraphUsage() {
                     + (d.graph_assist_search || 0) + (d.graph_assist_neighbors || 0);
     const searches = (d.grep_call || 0) + (d.glob_call || 0)
                    + (d.bash_grep_call || 0) + (d.bash_find_call || 0);
-    const total = graphWins + searches;
+    const total = graphWins + searches + (d.preresolve_miss || 0);
     if (total === 0) return null;
     return { graphWins: graphWins, searches: searches, pct: Math.round((graphWins / total) * 100), dollarsSaved: d.dollars_saved || 0 };
   } catch { return null; }

package/.claude/skills/mastermind/approve.md

@@ -97,7 +97,7 @@ approval=$(jq --arg id "$approval_id" '.approvals[] | select(.id == $id)' "$appr
 agent_id=$(echo "$approval" | jq -r '.agent_id')
 memNs="org:${org_name}"
 npx monomind@latest memory store \
-  --key "${memNs}:approval:${approval_id}" \
+  --key "approval:${approval_id}" \
   --namespace "$memNs" \
   --value '{"status":"approved","approval_id":"'"$approval_id"'","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}'
 
@@ -118,7 +118,7 @@ approval=$(jq --arg id "$approval_id" '.approvals[] | select(.id == $id)' "$appr
 agent_id=$(echo "$approval" | jq -r '.agent_id')
 memNs="org:${org_name}"
 npx monomind@latest memory store \
-  --key "${memNs}:approval:${approval_id}" \
+  --key "approval:${approval_id}" \
   --namespace "$memNs" \
   --value '{"status":"rejected","approval_id":"'"$approval_id"'","reason":"'"${reason:-No reason given}"'","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}'
 
@@ -150,13 +150,21 @@ jq --arg id "$approval_id" \
 
 2. Emit `org:approval:requested` event to dashboard (so the human is notified).
 
-3. Poll memory for the approval decision:
+3. Poll for the approval decision — check the approvals file first (authoritative, updated by both the dashboard UI and `/mastermind:approve`), then fall back to memory:
 ```bash
+approvalsFile=".monomind/orgs/${orgName}-approvals.json"
 while true; do
-  result=$(npx monomind@latest memory search --query "approval:${approval_id}" --namespace "${memNs}" 2>/dev/null)
-  status=$(echo "$result" | jq -r '.[0].value.status // ""' 2>/dev/null)
-  [ "$status" = "approved" ] && break
-  [ "$status" = "rejected" ] && { echo "Action rejected: $(echo $result | jq -r '.[0].value.reason // ""')"; exit 1; }
+  # Check file first — dashboard approve/reject button only updates the file (not memory)
+  file_status=$(jq --arg id "$approval_id" '.approvals[] | select(.id == $id) | .status // ""' "$approvalsFile" 2>/dev/null || echo "")
+  if [ -z "$file_status" ] || [ "$file_status" = '"pending"' ] || [ "$file_status" = "pending" ]; then
+    mem_result=$(npx monomind@latest memory search --query "approval:${approval_id}" --namespace "${memNs}" 2>/dev/null)
+    mem_status=$(echo "$mem_result" | jq -r '.[0].value.status // ""' 2>/dev/null)
+    [ -n "$mem_status" ] && [ "$mem_status" != "pending" ] && file_status="$mem_status"
+  fi
+  # Strip quotes from jq output
+  file_status=$(echo "$file_status" | tr -d '"')
+  [ "$file_status" = "approved" ] && break
+  [ "$file_status" = "rejected" ] && { echo "Action rejected by governance policy — skip this action"; exit 1; }
   sleep 30
 done
 ```