@yemi33/minions 0.1.2145 → 0.1.2147

package/docs/completion-reports.md

@@ -84,6 +84,39 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
 | `pending` | string | Any remaining work, or `none`. |
 | `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |
+| `meta.review` | object | Optional, review tasks only. Records project-local review-skill outcome — see [Review skill outcomes](#review-skill-outcomes). |
+
+## Review skill outcomes
+
+W-mq16xtdx001a347e. Review playbook renders a `## Project review skills` block at dispatch time when the target project ships `.claude/skills/*` or `.claude/commands/*` with `review` / `swarm` in the name or description (or when `.github/copilot-instructions.md` / `CLAUDE.md` mention a canonical `/…review…` slash-command). When the agent acts on that block, it records the outcome under `meta.review` so later evaluation can compare skill-driven reviews vs. first-principles reviews.
+
+All `meta.review` fields are optional and backward-compatible — older agents that never set them stay valid.
+
+```json
+{
+  "status": "success",
+  "verdict": "approved",
+  "pr": "https://github.com/owner/repo/pull/123",
+  "meta": {
+    "review": {
+      "skillInvoked": {
+        "name": "/review-swarm",
+        "path": ".claude/commands/review-swarm.md",
+        "kind": "command"
+      },
+      "skillFindings": 4
+    }
+  }
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `meta.review.skillInvoked` | object | The project review skill the agent actually ran. Shape: `{name, path, kind}` where `kind` is one of `skill`, `command`, `slash-command` (mirrors the discovery layer in `engine/discover-review-skills.js`). Omit when no skill was invoked. |
+| `meta.review.skillFindings` | number | Count of findings the invoked skill returned. Used later to measure skill quality and the value-add of first-principles review on top. Omit when no skill was invoked. |
+| `meta.review.skillSkipped` | object | Set when a project review skill was available but the agent intentionally chose not to run it (trivial diff, out-of-scope diff, meta-review of the skill itself, etc.). Shape: `{name, reason}`. Mirror the skip rationale into the `Automated checks` section of the PR comment so a human reviewer sees the reasoning. |
+
+Dispatchers can suppress the block entirely by setting `meta.skipProjectReviewSkills: true` on the review work item — the playbook then renders identically to the pre-W-mq16xtdx 8-step contract. Use this for meta-reviews of the review skill itself; the engine still accepts `meta.review.skillSkipped` in the report regardless.
 
 ## `failure_class` enum
 

package/engine/cleanup.js

@@ -634,6 +634,15 @@ async function runCleanup(config, verbose = false) {
         if (registered.has(full)) continue;
         let stat; try { stat = fs.statSync(full); } catch { continue; }
         if (stat.mtimeMs >= _twoHoursAgo) continue;
+        // W-mq5rwwss000f30a7 — even an "orphan" dir (one git doesn't know
+        // about) may still host a live agent if dispatch persistence ran
+        // before `git worktree add` finished. Skip when a live dispatch
+        // claims it.
+        if (shared.isWorktreePathLive(full)) {
+          log('info', `Cleanup: skip orphan worktree dir ${full} — live dispatch claims it`);
+          shared._writeWorktreeSkipLiveInboxNote(full, 'cleanup.orphanWorktreeDirSweep');
+          continue;
+        }
         try {
           fs.rmSync(full, { recursive: true, force: true });
           cleaned.orphanWorktreeDirs++;

package/engine/cli.js

@@ -163,18 +163,30 @@ function handleCommand(cmd, args) {
     //
     // `minions work --help` used to create ghost work items with title='--help'
     // because the bare-string `title` was truthy and bypassed the `!title`
-    // usage check. The fix lives in per-command guards (`_isHelpArg` /
-    // `looksLikeFlagOrHelp`) on `work`/`spawn`/`plan`/`complete`, which print
-    // command-specific `Usage:` output. `pr` and `bridge` handle help inline.
+    // usage check. Same class of bug exists in `spawn`/`plan`/`complete` —
+    // every command that takes a positional arg and tests it with `if (!arg)`.
     //
-    // For other commands (start/stop/status/etc.), fall back to printing the
-    // global command list — they take no positional args so `--help` is
-    // otherwise harmless. Commands with per-command help handling are excluded
-    // so their `Usage:` text is what the user sees.
-    const COMMANDS_WITH_OWN_HELP = new Set(['pr', 'bridge', 'work', 'spawn', 'plan', 'complete']);
-    if (!COMMANDS_WITH_OWN_HELP.has(cmd) && isHelpToken(args && args[0])) {
-      console.log('Commands:');
-      for (const line of formatCliCommandHelpLines()) console.log(line);
+    // Intercept here so a single guard covers the whole command set. `pr` and
+    // `bridge` already handle `help`/`--help`/`-h` inline (see their own
+    // first-arg branches), so let them route through unchanged.
+    //
+    // W-mq60aco9: print the *per-command* usage (matching the convention from
+    // PR #3054 which added per-positional `Usage:` for work/spawn/plan/complete).
+    // Previously this branch printed the global `Commands:` list and short-
+    // circuited the per-command guards — so `minions work --help` advertised
+    // the wrong help text. Fall back to the global list only for commands
+    // missing from CLI_COMMAND_DOCS. The per-command `_isHelpArg` guards in
+    // work/spawn/plan/complete remain as defense-in-depth for any caller that
+    // bypasses handleCommand.
+    if (cmd !== 'pr' && cmd !== 'bridge' && isHelpToken(args && args[0])) {
+      const doc = CLI_COMMAND_DOCS[cmd];
+      if (doc) {
+        console.log(`Usage: minions ${cmd}${doc.args ? ' ' + doc.args : ''}`);
+        if (doc.summary) console.log(`  ${doc.summary}`);
+      } else {
+        console.log('Commands:');
+        for (const line of formatCliCommandHelpLines()) console.log(line);
+      }
       return;
     }
     return commands[cmd](...args);

package/engine/discover-review-skills.js

@@ -0,0 +1,279 @@
+/**
+ * engine/discover-review-skills.js — W-mq16xtdx001a347e
+ *
+ * Cheap, bounded filesystem walk that surfaces project-local review tooling
+ * (skills, slash-commands, copilot-instructions slash-command mentions) so
+ * Minions review dispatches reliably steer agents toward the right skill
+ * instead of reviewing every PR from first principles.
+ *
+ * Walk surfaces:
+ *   - .claude/skills/*\/SKILL.md          — name/description frontmatter
+ *   - .claude/commands/*.md                — filename + first heading
+ *   - .github/copilot-instructions.md      — slash-command mentions (top N bytes)
+ *   - CLAUDE.md                            — slash-command mentions (top N bytes)
+ *
+ * Returns a deduplicated array of:
+ *   { kind: 'skill'|'command'|'slash-command', name, path, oneLineDescription }
+ *
+ * Contract:
+ *   - Worktree missing / unreadable → returns [] (never throws)
+ *   - Single bounded readdir per surface (no recursive grep)
+ *   - File-count + walltime budget caps the walk in pathological repos
+ *   - Pure: no engine state mutations, no logging beyond debug
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Heuristic match — "review", "swarm", or the explicit constellation-review id.
+// Word-bounded so we don't match arbitrary substrings like "previewer" or
+// "swarmm" inside unrelated names.
+const KEYWORD_RE = /\b(review|review-swarm|swarm|code-review|pr-review|constellation-review)\b/i;
+
+// Slash-command extractor — pulls `/foo-review`, `/review-swarm`, etc. out of
+// markdown prose. Anchored so `/path/to/file` doesn't match (must look like a
+// slash-command token: leading `/` immediately followed by an id with no `/`).
+const SLASH_COMMAND_RE = /(?<![A-Za-z0-9/_-])\/([a-z][a-z0-9-]*)(?![A-Za-z0-9/])/g;
+
+const DEFAULTS = {
+  maxFilesPerSurface: 50,    // hard cap on skill packs / command files we'll read
+  maxBytesPerFile: 8 * 1024, // only need frontmatter + first heading
+  docsScanMaxBytes: 32 * 1024, // CLAUDE.md / copilot-instructions.md top window
+  walltimeMs: 250,           // bail rather than block dispatch on pathological FS
+};
+
+function _now() { return Date.now(); }
+
+function _safeReadHead(filePath, maxBytes) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(maxBytes);
+    const n = fs.readSync(fd, buf, 0, maxBytes, 0);
+    return buf.slice(0, n).toString('utf8');
+  } catch { return ''; }
+  finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* ignore */ } } }
+}
+
+function _parseFrontmatter(content) {
+  const m = String(content || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const lm = line.match(/^([\w-]+):\s*(.*)$/);
+    if (!lm) continue;
+    out[lm[1].toLowerCase()] = lm[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+function _firstHeading(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(/^#+\s+(.+?)\s*$/);
+    if (m) return m[1].trim();
+  }
+  return '';
+}
+
+function _firstNonEmptyLine(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  for (const line of lines) {
+    const t = line.trim();
+    if (t && !t.startsWith('---') && !t.startsWith('#')) return t;
+  }
+  return '';
+}
+
+function _truncate(s, max) {
+  const text = String(s || '').trim();
+  if (text.length <= max) return text;
+  return text.slice(0, max - 1).trim() + '…';
+}
+
+function _discoverSkills(projectPath, opts, deadline) {
+  const out = [];
+  const skillsDir = path.join(projectPath, '.claude', 'skills');
+  let entries;
+  try { entries = fs.readdirSync(skillsDir, { withFileTypes: true }); } catch { return out; }
+  let scanned = 0;
+  for (const ent of entries) {
+    if (scanned >= opts.maxFilesPerSurface) break;
+    if (_now() > deadline) break;
+    if (!ent.isDirectory()) continue;
+    const skillPath = path.join(skillsDir, ent.name, 'SKILL.md');
+    let stat;
+    try { stat = fs.statSync(skillPath); } catch { continue; }
+    if (!stat.isFile()) continue;
+    scanned += 1;
+    const head = _safeReadHead(skillPath, opts.maxBytesPerFile);
+    if (!head) continue;
+    const fm = _parseFrontmatter(head);
+    const name = fm.name || ent.name;
+    const desc = fm.description || '';
+    const hay = `${name} ${desc}`;
+    if (!KEYWORD_RE.test(hay)) continue;
+    out.push({
+      kind: 'skill',
+      name: String(name),
+      path: path.relative(projectPath, skillPath).split(path.sep).join('/'),
+      oneLineDescription: _truncate(desc || _firstHeading(head) || name, 200),
+    });
+  }
+  return out;
+}
+
+function _discoverCommands(projectPath, opts, deadline) {
+  const out = [];
+  const cmdDir = path.join(projectPath, '.claude', 'commands');
+  let entries;
+  try { entries = fs.readdirSync(cmdDir, { withFileTypes: true }); } catch { return out; }
+  let scanned = 0;
+  for (const ent of entries) {
+    if (scanned >= opts.maxFilesPerSurface) break;
+    if (_now() > deadline) break;
+    if (!ent.isFile()) continue;
+    if (!/\.md$/i.test(ent.name)) continue;
+    scanned += 1;
+    const base = ent.name.replace(/\.md$/i, '');
+    const cmdPath = path.join(cmdDir, ent.name);
+    const head = _safeReadHead(cmdPath, opts.maxBytesPerFile);
+    const heading = _firstHeading(head);
+    const hay = `${base} ${heading}`;
+    if (!KEYWORD_RE.test(hay)) continue;
+    out.push({
+      kind: 'command',
+      name: `/${base}`,
+      path: path.relative(projectPath, cmdPath).split(path.sep).join('/'),
+      oneLineDescription: _truncate(heading || _firstNonEmptyLine(head) || base, 200),
+    });
+  }
+  return out;
+}
+
+function _extractSlashCommandsFromDoc(content) {
+  const found = new Map();
+  const text = String(content || '');
+  let m;
+  SLASH_COMMAND_RE.lastIndex = 0;
+  while ((m = SLASH_COMMAND_RE.exec(text)) !== null) {
+    const id = m[1];
+    if (!KEYWORD_RE.test(id)) continue;
+    if (!found.has(id)) found.set(id, m.index);
+  }
+  return [...found.keys()];
+}
+
+function _discoverDocSlashCommands(projectPath, opts, deadline, alreadySeen) {
+  const out = [];
+  const docPaths = [
+    path.join(projectPath, '.github', 'copilot-instructions.md'),
+    path.join(projectPath, 'CLAUDE.md'),
+  ];
+  for (const docPath of docPaths) {
+    if (_now() > deadline) break;
+    let stat;
+    try { stat = fs.statSync(docPath); } catch { continue; }
+    if (!stat.isFile()) continue;
+    const head = _safeReadHead(docPath, opts.docsScanMaxBytes);
+    if (!head) continue;
+    const ids = _extractSlashCommandsFromDoc(head);
+    const relDoc = path.relative(projectPath, docPath).split(path.sep).join('/');
+    for (const id of ids) {
+      const fullName = `/${id}`;
+      if (alreadySeen.has(fullName)) continue;
+      alreadySeen.add(fullName);
+      out.push({
+        kind: 'slash-command',
+        name: fullName,
+        path: relDoc,
+        oneLineDescription: `Documented review entrypoint in ${relDoc}`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.projectPath — absolute path to the project worktree / checkout
+ * @param {object} [args.opts] — override defaults (mostly for tests)
+ * @returns {Array<{kind:string,name:string,path:string,oneLineDescription:string}>}
+ */
+function discoverReviewSkills(args) {
+  const projectPath = args && args.projectPath;
+  if (!projectPath || typeof projectPath !== 'string') return [];
+  try { if (!fs.statSync(projectPath).isDirectory()) return []; } catch { return []; }
+
+  const opts = Object.assign({}, DEFAULTS, args.opts || {});
+  const deadline = _now() + Math.max(1, opts.walltimeMs);
+
+  const seenKey = new Set(); // dedupe across surfaces by `${kind}:${name}`
+  const seenSlash = new Set();
+  const all = [];
+
+  for (const entry of _discoverSkills(projectPath, opts, deadline)) {
+    const key = `skill:${entry.name}`;
+    if (seenKey.has(key)) continue;
+    seenKey.add(key);
+    all.push(entry);
+  }
+
+  for (const entry of _discoverCommands(projectPath, opts, deadline)) {
+    const key = `command:${entry.name}`;
+    if (seenKey.has(key)) continue;
+    seenKey.add(key);
+    seenSlash.add(entry.name); // /foo from .claude/commands subsumes doc-mention
+    all.push(entry);
+  }
+
+  for (const entry of _discoverDocSlashCommands(projectPath, opts, deadline, seenSlash)) {
+    const key = `slash-command:${entry.name}`;
+    if (seenKey.has(key)) continue;
+    seenKey.add(key);
+    all.push(entry);
+  }
+
+  return all;
+}
+
+/**
+ * Format a discovery result list as a Markdown block ready to splice into the
+ * review playbook. Returns empty string when the list is empty so the caller
+ * can no-op cleanly (no stray header, no blank padding lines).
+ *
+ * @param {Array} entries — output of discoverReviewSkills()
+ * @returns {string}
+ */
+function renderReviewSkillsBlock(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return '';
+  const lines = [];
+  lines.push('## Project review skills (prefer these when applicable)');
+  lines.push('');
+  lines.push("This project ships purpose-built review tooling. When the diff under review is within scope of one of these skills, INVOKE IT FIRST and use its findings as the primary signal — your verdict can then be anchored to what the skill returned plus any gaps you spot on top.");
+  lines.push('');
+  for (const e of entries) {
+    const kindHint = e.kind === 'skill' ? `skill: \`${e.name}\``
+      : e.kind === 'command' ? `\`${e.name}\``
+      : `\`${e.name}\``;
+    const pathHint = e.path ? ` (\`${e.path}\`)` : '';
+    const desc = e.oneLineDescription ? ` — ${e.oneLineDescription}` : '';
+    lines.push(`- ${kindHint}${pathHint}${desc}`);
+  }
+  lines.push('');
+  lines.push("Record the skill outcome in your completion report's `meta.review` block (`skillInvoked` or `skillSkipped` — see `docs/completion-reports.md`) so the engine can later measure skill-vs-first-principles signal.");
+  return lines.join('\n');
+}
+
+module.exports = {
+  discoverReviewSkills,
+  renderReviewSkillsBlock,
+  // exported for tests
+  _internal: {
+    KEYWORD_RE,
+    SLASH_COMMAND_RE,
+    DEFAULTS,
+    _parseFrontmatter,
+    _extractSlashCommandsFromDoc,
+  },
+};

package/engine/playbook.js

@@ -301,6 +301,12 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   // PR-context vars on non-PR tasks (implement/explore/etc.)
   'pr_id', 'pr_number', 'pr_title', 'pr_branch', 'pr_author', 'pr_url',
   'reviewer',
+  // W-mq16xtdx001a347e — review dispatches inject this block (or empty string
+  // when discovery finds no project-local review skills). Optional because
+  // non-review playbooks never reference it and review-against-skill-less
+  // projects legitimately resolve it to ''.
+  'project_review_skills_block',
+  'skip_project_review_skills',
   // P-e6b3c2d8 — QA Session template vars. session_id / target_kind /
   // flows_raw / managed_spawn_name are required (declared in
   // PLAYBOOK_REQUIRED_VARS['qa-session-setup']); these target_* sub-fields
@@ -689,6 +695,31 @@ function renderPlaybook(type, vars) {
     } catch (e) { log('warn', `managed-spawn live-processes inject failed: ${e.message}`); }
   }
 
+  // W-mq16xtdx001a347e — review dispatches: discover project-local review
+  // tooling (.claude/skills, .claude/commands, copilot-instructions slash-
+  // command mentions) and render a "Project review skills" block near the top
+  // of the playbook. Default-ON for `review` type; suppressed when the
+  // dispatcher passes `meta.skipProjectReviewSkills` (threaded as
+  // vars.skip_project_review_skills). Renders empty string when discovery
+  // returns no matches so first-principles reviewers see no stray header.
+  if (type === 'review' && !vars.skip_project_review_skills) {
+    try {
+      const discover = require('./discover-review-skills');
+      const projectPath = matchedProject?.localPath || '';
+      if (projectPath) {
+        const entries = discover.discoverReviewSkills({ projectPath });
+        vars.project_review_skills_block = discover.renderReviewSkillsBlock(entries);
+      } else {
+        vars.project_review_skills_block = '';
+      }
+    } catch (e) {
+      log('warn', `discover-review-skills failed: ${e.message}`);
+      vars.project_review_skills_block = '';
+    }
+  } else {
+    vars.project_review_skills_block = '';
+  }
+
   // W-mpeiwz6k0005bf34-c — opt-in qa-validate context block. Injected only
   // when the dispatcher set vars.qa_run_id (truthy) from the work item's
   // `meta.qaRunId`. Mirrors the managed_spawn hint pattern: the playbook is
@@ -1098,6 +1129,10 @@ function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabe
   const vars = {
     ...buildBaseVars(agentId, config, project),
     branch_name: extraVars?.pr_branch || '',
+    // W-mq16xtdx001a347e — honor meta.skipProjectReviewSkills on PR-built
+    // dispatches (auto re-reviews, conflict-fix follow-ups, etc.). Default
+    // OFF: review dispatches surface the project-local review skills block.
+    skip_project_review_skills: !!(meta && meta.skipProjectReviewSkills),
     ...extraVars,
     task_id: dispatchId,
   };