@monoes/monomindcli 2.16.1 → 2.16.3

package/.claude/commands/pair/modes.md

@@ -64,7 +64,7 @@ Write failing tests, then implement just enough to pass, then refactor.
 
 **Invoke the TDD skill for full workflow:**
 ```
-Skill("superpowers:test-driven-development")
+Skill("mastermind-debug")   # Phase 4: failing test first, then Red-Green-Refactor
 ```
 
 ---
@@ -81,7 +81,7 @@ Work through existing code with Claude as reviewer.
 
 **Invoke the review skill:**
 ```
-Skill("superpowers:requesting-code-review")
+Skill("mastermind-review")
 ```
 
 ---
@@ -95,7 +95,7 @@ Systematic debugging as a pair.
 
 **Invoke the debugging skill:**
 ```
-Skill("superpowers:systematic-debugging")
+Skill("mastermind-debug")
 ```
 
 ---

package/.claude/helpers/build-skill-registry.cjs

@@ -15,16 +15,33 @@
  * /graphify, was itself a phantom). Generating from the live tree is the only
  * way this file stays true.
  *
- * Scope is deliberately project-local (.claude/commands, .claude/skills).
- * User-global plugin skills (~/.claude/plugins) are intentionally excluded —
- * this file is committed and shipped, so machine-specific entries would make
- * it wrong for everyone else.
+ * Scope: the PROJECT's own trees (.claude/commands, .claude/skills), the
+ * user's ~/.claude/skills (source 'user'; project wins a name clash), and the
+ * Org skill library (`orgSkills`, via org-skill-index.cjs). The file is
+ * generated per machine (init, upgrade, SessionStart, `monomind pick`) and is
+ * never committed — a shipped snapshot listed skills a project did not have.
+ * README/overview/reference docs, `_`-prefixed includes and helper-only
+ * skills (HELPER_ONLY, or frontmatter `type: helper`) are not entries.
+ * Frontmatter `pick: low` marks an admin/meta entry (org management pages,
+ * examples, the picker itself): it stays in the index, recorded as
+ * `pick: 'low'`, and the pickers rank it below equally matching entries so
+ * generic task words ("review", "settings") do not surface it.
  *
  * Usage:  node .claude/helpers/build-skill-registry.cjs [projectRoot]
  */
 
 var fs = require('fs');
+var os = require('os');
 var path = require('path');
+var orgIndex = require('./org-skill-index.cjs');
+
+/** Protocol pieces other skills include; never invoked on their own. */
+var HELPER_ONLY = new Set([
+  'mastermind-agent-select', 'mastermind-delegation', 'mastermind-intake',
+  'mastermind-protocol', 'mastermind-repeat', '_repeat', '_taskfile',
+]);
+/** Documentation pages that live beside commands but are not commands. */
+var DOC_NAMES = new Set(['readme', 'overview', 'reference', 'references']);
 
 // Words that carry no routing signal — dropped from derived keywords.
 var STOPWORDS = new Set([
@@ -149,6 +166,22 @@ function isJunk(basename) {
   return basename.startsWith('._') || basename.startsWith('_');
 }
 
+/** Docs and helper-only pieces: README/overview/reference pages (or anything
+ *  under a references/ dir), HELPER_ONLY names, and `type: helper` frontmatter. */
+function isNotACandidate(parts, fm) {
+  for (var i = 0; i < parts.length; i++) {
+    if (DOC_NAMES.has(parts[i].toLowerCase())) return true;
+  }
+  if (HELPER_ONLY.has(parts[parts.length - 1])) return true;
+  return String(fm.type || '').toLowerCase() === 'helper';
+}
+
+/** `pick: low` frontmatter, recorded on the entry; nothing otherwise. */
+function applyPick(entry, fm) {
+  if (String(fm.pick || '').trim().toLowerCase() === 'low') entry.pick = 'low';
+  return entry;
+}
+
 function walkMarkdown(dir, out) {
   var entries;
   try {
@@ -184,11 +217,12 @@ function scanCommands(root) {
     try { text = fs.readFileSync(file, 'utf-8'); } catch (e) { continue; }
     var fm = readFrontmatter(text);
     if (String(fm['user-invocable']).toLowerCase() === 'false') continue;
+    if (isNotACandidate(parts, fm)) continue;
 
     var name = fm.name || parts[parts.length - 1];
     var description = fm.description || readLeadingComment(text) || readFirstHeading(text);
     var nameTerms = deriveNameTerms(name, invokeName);
-    out.push({
+    out.push(applyPick({
       skill: invokeName,
       invoke: '/' + invokeName,
       kind: 'command',
@@ -197,7 +231,7 @@ function scanCommands(root) {
       keywords: deriveKeywords(description, nameTerms),
       category: group,
       source: '.claude/commands/' + rel,
-    });
+    }, fm));
   }
   return out;
 }
@@ -219,9 +253,9 @@ function readCatalogMarker(text, dir) {
   return { id: id, jev: !!m && m[1] === id && m[2] === 'yes' };
 }
 
-/** Scan .claude/skills/<name>/SKILL.md -> Skill() entries. */
-function scanSkills(root) {
-  var base = path.join(root, '.claude', 'skills');
+/** Scan <base>/<name>/SKILL.md -> Skill() entries. `label` is the source
+ *  path prefix written into each entry ('.claude/skills' or '~/.claude/skills'). */
+function scanSkillDir(base, label, origin) {
   if (!fs.existsSync(base)) return [];
   var dirs;
   try {
@@ -232,7 +266,7 @@ function scanSkills(root) {
   var out = [];
   for (var i = 0; i < dirs.length; i++) {
     var d = dirs[i];
-    if (!d.isDirectory() || isJunk(d.name)) continue;
+    if (!(d.isDirectory() || d.isSymbolicLink()) || isJunk(d.name)) continue;
     var skillFile = path.join(base, d.name, 'SKILL.md');
     if (!fs.existsSync(skillFile)) continue;
 
@@ -240,6 +274,7 @@ function scanSkills(root) {
     try { text = fs.readFileSync(skillFile, 'utf-8'); } catch (e) { continue; }
     var fm = readFrontmatter(text);
     if (String(fm['user-invocable']).toLowerCase() === 'false') continue;
+    if (isNotACandidate([d.name], fm)) continue;
 
     var name = fm.name || d.name;
     var description = fm.description || readLeadingComment(text) || readFirstHeading(text);
@@ -252,8 +287,10 @@ function scanSkills(root) {
       nameTerms: nameTerms,
       keywords: deriveKeywords(description, nameTerms),
       category: 'skill',
-      source: '.claude/skills/' + d.name + '/SKILL.md',
+      source: label + '/' + d.name + '/SKILL.md',
     };
+    if (origin) entry.origin = origin;
+    applyPick(entry, fm);
     var catalog = readCatalogMarker(text, d.name);
     if (catalog) entry.catalog = catalog;
     out.push(entry);
@@ -261,15 +298,49 @@ function scanSkills(root) {
   return out;
 }
 
-function build(root) {
-  var entries = scanCommands(root).concat(scanSkills(root));
+/** Project skills, then the user's ~/.claude/skills for names the project lacks. */
+function scanSkills(root, opts) {
+  var project = scanSkillDir(path.join(root, '.claude', 'skills'), '.claude/skills');
+  if (opts && opts.user === false) return project;
+  var taken = new Set(project.map(function (e) { return e.skill; }));
+  var user = scanSkillDir(path.join(homeDir(opts), '.claude', 'skills'), '~/.claude/skills', 'user')
+    .filter(function (e) { return !taken.has(e.skill); });
+  return project.concat(user);
+}
+
+function homeDir(opts) {
+  return (opts && opts.home) || os.homedir();
+}
+
+function indexPath(root) {
+  return path.join(root, '.claude', 'helpers', 'skill-registry.json');
+}
+
+function readIndex(root) {
+  try {
+    return JSON.parse(fs.readFileSync(indexPath(root), 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * The index for `root`. opts: { home, env, user (false = skip ~/.claude/skills),
+ * bundledDir (the CLI's org-skills dir; else the one the last build recorded) }.
+ */
+function build(root, opts) {
+  opts = Object.assign({}, opts);
+  var prev = readIndex(root);
+  var prevMeta = (prev && prev._meta) || {};
+  if (!opts.bundledDir && typeof prevMeta.bundledOrgSkillsDir === 'string') opts.bundledDir = prevMeta.bundledOrgSkillsDir;
+  var entries = scanCommands(root).concat(scanSkills(root, opts));
+  var orgSkills = orgIndex.scanOrgSkills(root, opts);
+  var bundled = orgIndex.bundledOrgSkillsDir(root, opts);
 
   // Preserve hand-tuned keywords for entries that still resolve by the same
   // key, so manual curation isn't blown away on every regeneration.
-  var registryPath = path.join(root, '.claude', 'helpers', 'skill-registry.json');
   var curated = {};
   try {
-    var prev = JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
     var prevList = (prev && prev.skills) || [];
     for (var i = 0; i < prevList.length; i++) {
       var p = prevList[i];
@@ -296,9 +367,9 @@ function build(root) {
     _meta: {
       version: '2.0.0',
       description:
-        'Auto-generated index of project-local slash commands (.claude/commands) and ' +
-        'skills (.claude/skills). Read by router.cjs matchSkills() to suggest a skill ' +
-        'for a routed task.',
+        'Auto-generated index of the project\'s slash commands (.claude/commands) and ' +
+        'skills (.claude/skills), the user\'s ~/.claude/skills, and the Org skill library ' +
+        '(orgSkills). Read by router.cjs matchSkills() and jev-catalog.cjs.',
       generatedBy: '.claude/helpers/build-skill-registry.cjs',
       regenerate: 'node .claude/helpers/build-skill-registry.cjs',
       note:
@@ -306,30 +377,113 @@ function build(root) {
         'an entry, add a "curatedKeywords" array to it; those survive regeneration and ' +
         'take precedence over derived ones.',
       scope:
-        'Project-local only. User-global plugin skills (~/.claude/plugins) are excluded ' +
-        'on purpose — this file is committed, so machine-specific entries would be wrong ' +
-        'for other checkouts.',
+        'Generated per machine — never commit it. Regenerated by init, upgrade, ' +
+        'SessionStart and `monomind pick` when a source tree is newer than this file.',
+      bundledOrgSkillsDir: bundled,
       counts: {
         commands: entries.filter(function (e) { return e.kind === 'command'; }).length,
         skills: entries.filter(function (e) { return e.kind === 'skill'; }).length,
+        user: entries.filter(function (e) { return e.origin === 'user'; }).length,
+        orgSkills: orgSkills.length,
         total: entries.length,
       },
     },
     skills: entries,
+    orgSkills: orgSkills,
   };
 }
 
-function main() {
-  var root = process.argv[2] || process.env.CLAUDE_PROJECT_DIR || process.cwd();
-  var registry = build(root);
-  var outPath = path.join(root, '.claude', 'helpers', 'skill-registry.json');
+/** Writes build(root, opts) to .claude/helpers/skill-registry.json atomically
+ *  — except an index with no commands or skills never replaces one that has
+ *  some (a build from the wrong directory must not wipe the project's index;
+ *  the agent registry has the same guard). */
+function write(root, opts) {
+  var registry = build(root, opts);
+  var prev = readIndex(root);
+  if (registry.skills.length === 0 && prev && Array.isArray(prev.skills) && prev.skills.length > 0) return registry;
+  var outPath = indexPath(root);
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
   var tmp = outPath + '.' + process.pid + '.tmp';
   fs.writeFileSync(tmp, JSON.stringify(registry, null, 2) + '\n', 'utf-8');
   fs.renameSync(tmp, outPath);
+  return registry;
+}
+
+/** Newest mtime of a skills root: the dir, each skill dir and its SKILL.md. */
+function skillTreeMtime(base) {
+  var newest = mtime(base);
+  var names;
+  try { names = fs.readdirSync(base); } catch (e) { return newest; }
+  names.forEach(function (n) {
+    newest = Math.max(newest, mtime(path.join(base, n)), mtime(path.join(base, n, 'SKILL.md')));
+  });
+  return newest;
+}
+
+function mtime(p) {
+  try { return fs.statSync(p).mtimeMs; } catch (e) { return 0; }
+}
+
+/** Newest mtime across every source the index is built from (a cheap stat
+ *  scan; the shipped org library counts by its directory only). */
+function sourcesMtime(root, opts) {
+  var newest = Math.max(
+    skillTreeMtime(path.join(root, '.claude', 'skills')),
+    mtime(path.join(root, '.monomind', 'catalog', 'state.json')),
+    mtime(__filename),
+    mtime(require.resolve('./org-skill-index.cjs'))
+  );
+  walkMarkdown(path.join(root, '.claude', 'commands'), []).forEach(function (f) {
+    newest = Math.max(newest, mtime(f), mtime(path.dirname(f)));
+  });
+  if (!opts || opts.user !== false) newest = Math.max(newest, skillTreeMtime(path.join(homeDir(opts), '.claude', 'skills')));
+  orgIndex.orgSkillRoots(root, opts).forEach(function (r) {
+    newest = Math.max(newest, r.origin === 'bundled' ? mtime(r.dir) : skillTreeMtime(r.dir));
+  });
+  return newest;
+}
+
+/** True when the index is missing or older than one of its sources. */
+function isStale(root, opts) {
+  var at = mtime(indexPath(root));
+  return at === 0 || sourcesMtime(root, opts) >= at;
+}
+
+/** The index for `root`, rebuilt and written first when stale. */
+function ensure(root, opts) {
+  if (isStale(root, opts)) return write(root, opts);
+  return readIndex(root) || write(root, opts);
+}
+
+/** The nearest directory at or above `cwd` holding `.claude` or `.monomind`,
+ *  never the home directory itself (its ~/.claude is user config) and never
+ *  above the git root. Null when there is none — mirrors findProjectRoot in
+ *  src/agents/registry-freshness.ts. */
+function findProjectRoot(cwd, home) {
+  var stopAt = path.resolve(home || os.homedir());
+  var dir = path.resolve(cwd);
+  for (;;) {
+    if (dir === stopAt) return null;
+    if (fs.existsSync(path.join(dir, '.claude')) || fs.existsSync(path.join(dir, '.monomind'))) return dir;
+    if (fs.existsSync(path.join(dir, '.git'))) return null;
+    var parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function main() {
+  var root = process.argv[2] || process.env.CLAUDE_PROJECT_DIR || findProjectRoot(process.cwd());
+  if (!root) {
+    process.stderr.write('skill-registry.json: no project found at or above ' + process.cwd() + '; nothing written\n');
+    return;
+  }
+  var registry = write(root);
   process.stdout.write(
     'skill-registry.json: ' + registry._meta.counts.total + ' entries (' +
     registry._meta.counts.commands + ' commands, ' +
-    registry._meta.counts.skills + ' skills)\n'
+    registry._meta.counts.skills + ' skills, ' +
+    registry._meta.counts.orgSkills + ' org skills)\n'
   );
 }
 
@@ -337,6 +491,12 @@ if (require.main === module) main();
 
 module.exports = {
   build: build,
+  write: write,
+  isStale: isStale,
+  ensure: ensure,
+  indexPath: indexPath,
+  findProjectRoot: findProjectRoot,
+  HELPER_ONLY: HELPER_ONLY,
   readFrontmatter: readFrontmatter,
   deriveNameTerms: deriveNameTerms,
   deriveKeywords: deriveKeywords,

package/.claude/helpers/handlers/agent-start-handler.cjs

@@ -86,6 +86,9 @@ module.exports = {
           agentType: agentType,
           description: agentDesc.substring(0, 120),
           dispatchedAt: new Date().toISOString(),
+          // Concurrent sessions share this file; the route handler only
+          // de-duplicates against its own session's dispatch.
+          sessionId: String(hookInput.session_id || hookInput.sessionId || '').slice(0, 128) || null,
         }),
         'utf-8'
       );

package/.claude/helpers/handlers/capture-handler.cjs

@@ -418,27 +418,33 @@ async function handleSubagentStop(hookInput) {
   // actual routing decision (this subagent spawn), not one per session —
   // keeps the "Routing Learning" signal live regardless of session length,
   // instead of it going silently stale for anyone running persistent orgs.
+  // suggestedAgent is the RECOMMENDATION (this Claude session's latest
+  // [PICK]); actualAgent is the subagent that really ran. They used to be the
+  // same field, so every spawn read as its own recommendation.
   try {
-    var _agentSlug = String(agentType || '').trim().toLowerCase().replace(/\s+/g, '-');
+    var _actualAgent = String(hookInput.agent_type || hookInput.subagent_type || agentType || '').slice(0, 128);
+    var _agentSlug = _actualAgent.trim().toLowerCase().replace(/\s+/g, '-');
     if (_agentSlug && _agentSlug !== 'ai-selecting' && _agentSlug !== 'unknown') {
+      var _pickCore = require('./pick-core.cjs');
+      var _route = _pickCore.readSessionRoute(CWD, hookInput.session_id || hookInput.sessionId);
       var _rfEntry = {
         timestamp: new Date().toISOString(),
-        suggestedAgent: _agentSlug,
+        actualAgent: _actualAgent,
         sessionId: String(session || snap.session || hookInput.sessionId || hookInput.session_id || '').slice(0, 128),
         intelligenceFeedback: _subagentSuccess,
       };
-      // Best-effort confidence from the routing decision that led to this
-      // spawn — may not correspond exactly to THIS subagent if another
-      // routing decision overwrote last-route.json in between (same
-      // imprecision session-handler.cjs's session-level entries already had).
-      try {
-        var _lastRoutePath = path.join(CWD, '.monomind', 'last-route.json');
-        var _MAX_ROUTE = 64 * 1024;
-        if (fs.existsSync(_lastRoutePath) && fs.statSync(_lastRoutePath).size <= _MAX_ROUTE) {
-          var _lastRoute = JSON.parse(fs.readFileSync(_lastRoutePath, 'utf-8'));
-          if (typeof _lastRoute.confidence === 'number') _rfEntry.confidence = _lastRoute.confidence;
-        }
-      } catch (_) {}
+      // Tells apart two same-type subagents that stop in the same millisecond.
+      if (hookInput.agent_id) _rfEntry.agentId = String(hookInput.agent_id).slice(0, 128);
+      if (_route && _route.routeId && _route.agent) {
+        _rfEntry.suggestedAgent = String(_route.agent).trim().toLowerCase().replace(/\s+/g, '-');
+        _rfEntry.followed = _actualAgent === _route.agent || _actualAgent === _route.agentSlug;
+      }
+      if (_route && typeof _route.confidence === 'number') _rfEntry.confidence = _route.confidence;
+      if (_route && _route.routeId) {
+        _rfEntry.routeId = _route.routeId;
+        // Join this subagent's outcome onto the route that preceded it.
+        _pickCore.joinOutcome(CWD, _route.routeId, { agentActuallyUsed: _actualAgent, subagentSuccess: _subagentSuccess });
+      }
       appendJsonlWithRotation(
         path.join(CWD, '.monomind', 'routing-feedback.jsonl'),
         JSON.stringify(_rfEntry),
@@ -446,6 +452,8 @@ async function handleSubagentStop(hookInput) {
       );
     }
   } catch (e) { /* non-fatal — feedback recording must never block subagent-stop */ }
+  // Fold the new adherence/outcome lines into pick-stats.json (the ranking prior).
+  try { require('../pick-stats.cjs').update(CWD); } catch (e) { /* non-fatal */ }
 
   if (!org && !session) {
     // No active org or session — log to general capture file only

package/.claude/helpers/handlers/edit-handler.cjs

@@ -5,7 +5,7 @@
 
 const path = require('path');
 const fs = require('fs');
-const { claimLock } = require('../utils/fs-helpers.cjs');
+const { claimRebuildLock, startRebuild } = require('../utils/monograph-resolve.cjs');
 
 module.exports = {
   handle: async function(hCtx) {
@@ -59,7 +59,7 @@ module.exports = {
       var securityPatterns = /\b(auth|security|crypto|secret|credential|token|password|\.env|permission|acl|rbac|jwt|oauth|session|cookie)\b/;
       if (securityPatterns.test(editFile) || editFile.includes('/security/') || editFile.includes('/auth/')) {
         console.log('[SECURITY_EDIT] Security-sensitive file modified: ' + path.basename(editFile));
-        console.log('[SECURITY_EDIT] INSTRUCTION: Consider running a security review. Invoke Skill("code-review:code-review") with security focus, or run: npx monomind security scan --path "' + editFile + '"');
+        console.log('[SECURITY_EDIT] INSTRUCTION: Consider running a security review. Invoke Skill("security-review"), or run: npx monomind security scan --path "' + editFile + '"');
       }
     } catch (e) { /* non-fatal */ }
 
@@ -102,18 +102,20 @@ module.exports = {
         // check and spawns its own rebuild + ua-enrich child (see the
         // 896-orphan-process incident fixed in control-start.cjs). claimLock
         // mirrors that same TOCTOU-safe stale-lock-breaking pattern.
-        if (claimLock(lockFile, COOLDOWN_MS)) {
+        // #328: the rebuild child now owns the lock (its PID replaces ours)
+        // and removes it when done, so a running rebuild blocks a second one
+        // and a lock left by an exited process is stale after the cooldown.
+        if (claimRebuildLock(lockFile, COOLDOWN_MS, 10 * 60 * 1000)) {
           var { spawn: spawnRebuild } = require('child_process');
-          var rebuildScript = "import { buildAsync } from '@monoes/monograph'; await buildAsync(" + JSON.stringify(CWD) + ");";
-          var graphDir = path.join(CWD, '.monomind', 'graph');
-          var logPath = path.join(graphDir, 'build.log');
-          var logFd;
-          try { logFd = fs.openSync(logPath, 'a'); } catch(e) { logFd = 'ignore'; }
-          var child = spawnRebuild(process.execPath, ['--input-type=module', '--eval', rebuildScript], {
-            detached: true, stdio: ['ignore', logFd, logFd], cwd: CWD,
-          });
-          child.unref();
-          console.log('[MONOGRAPH] Incremental rebuild triggered for ' + path.basename(editedFile2));
+          // Resolves @monoes/monograph to an absolute path (project, global
+          // npm, npx cache) and imports it by file URL — a bare-specifier
+          // import only finds a project-local install. Falls back to
+          // `monomind monograph build`; with neither, it records one deduped
+          // failure line instead of an ERR_MODULE_NOT_FOUND per edit.
+          var rebuild = startRebuild(CWD, { lockPath: lockFile });
+          if (rebuild.mode !== 'none') {
+            console.log('[MONOGRAPH] Incremental rebuild triggered for ' + path.basename(editedFile2));
+          }
 
           // Option C: fire ua-enrich.mjs in background after monograph rebuild
           var uaEnrichScript = path.join(CWD, 'scripts', 'ua-enrich.mjs');