@mmerterden/multi-agent-pipeline 20.8.2 → 20.9.0

package/pipeline/scripts/skill-candidates.mjs

@@ -0,0 +1,882 @@
+#!/usr/bin/env node
+/**
+ * skill-candidates.mjs  -  which skills Phase 2 stack skill routing may use for
+ * a repo, and why each candidate is in or out.
+ *
+ * Two sources compete, and the order is the contract
+ * (multi-agent-refs/features/stack-skill-routing.md):
+ *
+ *   1. repo-local skills, `<repo>/.claude/skills/<name>/SKILL.md`
+ *   2. toolkits for the stacks this repo is built with
+ *   3. the always-on toolkits (ai-common-toolkit, ai-analyst-toolkit), and any
+ *      inherited toolkit that marks no stack but ships an index
+ *
+ * The toolkit set starts from the effective enabledPlugins: the user's
+ * settings.json and settings.local.json (under CLAUDE_CONFIG_DIR, else
+ * ~/.claude), then the repo's .claude/settings.json and .claude/settings.local.json;
+ * the later layer wins per plugin. A toolkit inherited from a user layer is then
+ * checked against the repo's detected stacks, because a repo that never ran
+ * /multi-agent:stack inherits whatever the user enabled for some other repo. A
+ * toolkit the repo enabled itself is never filtered: that is an explicit choice.
+ * Managed (enterprise) settings are not read.
+ *
+ * Nothing here names a stack. The stack vocabulary comes from the stack-adapter
+ * table and the alias tables in _stack-routing.mjs, and a toolkit's stacks come
+ * from its own name (`ai-<words>-toolkit`) plus any `stack` / `stacks` /
+ * `keywords` in its plugin.json. A new `ai-<x>-toolkit` whose `<x>` is an
+ * adapter id is filtered correctly with no edit to this file. An inherited
+ * toolkit that marks no stack is kept only in the common role and only when it
+ * ships an index; otherwise it is listed in `unscoped[]` and not routed to,
+ * because nothing ties it to this repo.
+ *
+ * When kept toolkits ship skills of the same name, one owner is chosen per name
+ * and recorded in `overlaps[]` and `decisions[]`: a repo-local skill first, then
+ * the stack role over the common role, then the narrowest enabling scope
+ * (repo-local, repo, user-local, user), then the toolkit name.
+ *
+ * An unattended or autopilot run cannot ask anybody to run /multi-agent:stack,
+ * and must not write `.claude/` inside the repo. So when a detected stack has no
+ * enabled toolkit, such a run reads that toolkit's skills READ-ONLY from a local
+ * marketplace clone (`fallbacks[]`), and an attended run only gets the hint. A
+ * clone that does not carry the toolkit is a recorded gap; neither mode ever
+ * substitutes another stack's toolkit.
+ *
+ * Every path read from a repo or a marketplace clone is checked on its real
+ * path: a SKILL.md or plugin directory that is a symlink out of its root is
+ * rejected.
+ *
+ * Usage:
+ *   node skill-candidates.mjs resolve --dir <repo> [--task-file <path> | --task -]
+ *                                     [--home <dir>] [--state <agent-state.json>]
+ *
+ * The task text is read from a file or from stdin (`--task -`), so ticket text
+ * never has to be pasted into a shell string. `--task "<text>"` still takes a
+ * literal. Prints JSON. Exit 0 on success, 2 on usage.
+ *
+ * @module pipeline/scripts/skill-candidates
+ */
+
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, isAbsolute, join, relative, sep } from "node:path";
+import { homedir } from "node:os";
+
+import {
+  ALWAYS_ON,
+  KNOWN_STACKS,
+  STACK_ARG_ALIAS,
+  STACK_PLUGIN_ALIAS,
+  pluginsForStacks,
+} from "./_stack-routing.mjs";
+import { detectCoarse, loadAdapters, resolveStack, UNKNOWN } from "./_stack-adapter.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { gatesActive, runMode } from "../lib/unattended.mjs";
+
+export const PRECEDENCE = ["repo", "stack", "common"];
+export const REPO_SKILLS_DIR = ".claude/skills";
+export const DEV_PHASE = 2;
+const CLAUDE_MD = ["CLAUDE.md", ".claude/CLAUDE.md"];
+const MAX_TASK_BYTES = 64 * 1024;
+
+/** Enabling scopes, narrowest first. The two user layers are inherited. */
+export const SCOPES = ["repo-local", "repo", "global-local", "global"];
+const INHERITED = new Set(["global", "global-local"]);
+
+/** Every toolkit has its own entry-point skills; a shared name there is no overlap. */
+const META_SKILLS = new Set(["index", "help"]);
+
+const EXPLICIT_ONLY =
+  /only (?:on|upon|when|if) (?:an? |the user )?explicit(?:ly)?(?: (?:request(?:ed)?|ask(?:ed|s)?|invoked|named))?|explicit request only|only when (?:asked|requested) explicitly|never (?:auto(?:matically)?[- ]?(?:load|invoke|run|route)|load (?:it )?automatically)/i;
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function realOrNull(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function inside(root, p) {
+  const rel = relative(root, p);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+/** The host's user config dir: `<home>/.claude` when a home is given, else CLAUDE_CONFIG_DIR or ~/.claude. */
+export function userConfigDir({ home, env = process.env } = {}) {
+  if (home) return join(home, ".claude");
+  return env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+}
+
+// ---------------------------------------------------------------------------
+// Stack vocabulary
+
+function words(id) {
+  return [id, ...id.split("-")].filter(Boolean);
+}
+
+function expand(token) {
+  const out = new Set([token]);
+  for (const s of STACK_ARG_ALIAS[token] || []) out.add(s);
+  for (const [stack, alias] of Object.entries(STACK_PLUGIN_ALIAS)) {
+    if (alias === token) out.add(stack);
+    if (stack === token) out.add(alias);
+  }
+  return [...out];
+}
+
+/** Every word that names a stack somewhere in the pipeline's own data. */
+export function stackVocabulary(doc = loadAdapters()) {
+  const v = new Set(KNOWN_STACKS);
+  for (const [id, a] of Object.entries(doc.adapters)) {
+    if (id === UNKNOWN || a.applicable === false) continue;
+    for (const w of words(id)) v.add(w);
+  }
+  for (const k of Object.keys(STACK_ARG_ALIAS)) v.add(k);
+  for (const a of Object.values(STACK_PLUGIN_ALIAS)) v.add(a);
+  return v;
+}
+
+/** Stack words a toolkit marks, from its name and optional plugin.json metadata. */
+export function toolkitStacks(name, meta = null, vocab = stackVocabulary()) {
+  const core = name
+    .replace(/@.*$/, "")
+    .replace(/^ai-/, "")
+    .replace(/-toolkit$/, "");
+  const raw = core.split("-");
+  for (const k of ["stack", "stacks", "keywords"]) {
+    const val = meta?.[k];
+    for (const x of Array.isArray(val) ? val : val ? [val] : []) {
+      if (typeof x === "string") raw.push(x.toLowerCase());
+    }
+  }
+  const out = new Set();
+  for (const t of raw) for (const e of expand(t)) if (vocab.has(e)) out.add(e);
+  return [...out].sort();
+}
+
+// ---------------------------------------------------------------------------
+// Enabled set
+
+function enabledLayer(path) {
+  const s = readJson(path);
+  const map = s?.enabledPlugins;
+  if (!map || typeof map !== "object" || Array.isArray(map)) return {};
+  return map;
+}
+
+/**
+ * Effective enabledPlugins with the layer each value came from.
+ * @param {string} repo
+ * @param {string} claudeDir  the user config dir (see userConfigDir)
+ * @returns {Map<string, {on: boolean, source: string}>}
+ */
+export function effectiveEnabled(repo, claudeDir) {
+  const layers = [
+    ["global", join(claudeDir, "settings.json")],
+    ["global-local", join(claudeDir, "settings.local.json")],
+    ["repo", join(repo, ".claude", "settings.json")],
+    ["repo-local", join(repo, ".claude", "settings.local.json")],
+  ];
+  const out = new Map();
+  for (const [source, path] of layers) {
+    for (const [key, on] of Object.entries(enabledLayer(path))) {
+      out.set(key, { on: on === true, source });
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Installed plugin metadata
+
+function newestDir(root) {
+  try {
+    const dirs = readdirSync(root, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+    const num = (v) => v.split(".").map((n) => parseInt(n, 10) || 0);
+    dirs.sort((a, b) => {
+      const pa = num(a);
+      const pb = num(b);
+      for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] || 0) - (pb[i] || 0);
+        if (d) return d;
+      }
+      return a.localeCompare(b);
+    });
+    return dirs.at(-1) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function skillsUnder(dir, depth = 3) {
+  const out = [];
+  const walk = (d, left) => {
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const p = join(d, e.name);
+      if (isFile(join(p, "SKILL.md"))) out.push(e.name);
+      else if (left > 1) walk(p, left - 1);
+    }
+  };
+  walk(dir, depth);
+  return out;
+}
+
+/** Version, install path, plugin.json and skill names of an installed plugin. */
+export function installedPlugin(key, claudeDir) {
+  const [name, marketplace] = key.split("@");
+  const pluginsDir = join(claudeDir, "plugins");
+  let installPath = null;
+  let version = null;
+  const rec = readJson(join(pluginsDir, "installed_plugins.json"))?.plugins?.[key];
+  if (Array.isArray(rec) && rec[0]?.installPath) {
+    installPath = rec[0].installPath;
+    version = rec[0].version ?? null;
+  } else if (marketplace) {
+    const root = join(pluginsDir, "cache", marketplace, name);
+    const v = newestDir(root);
+    if (v) {
+      installPath = join(root, v);
+      version = v;
+    }
+  }
+  if (!installPath || !existsSync(installPath)) {
+    return { installPath: null, version, meta: null, skills: null };
+  }
+  const meta = readJson(join(installPath, ".claude-plugin", "plugin.json"));
+  if (meta?.version) version = meta.version;
+  const listed = Array.isArray(meta?.skills) ? meta.skills.map((s) => basename(s)) : null;
+  const skills = listed?.length ? listed : skillsUnder(join(installPath, "skills"));
+  return { installPath, version, meta, skills };
+}
+
+function hasIndex(info) {
+  return Boolean(info.installPath && isFile(join(info.installPath, "skills", "index", "SKILL.md")));
+}
+
+function isToolkit(name, info) {
+  return /-toolkit$/.test(name) || hasIndex(info);
+}
+
+// ---------------------------------------------------------------------------
+// Marketplace clones
+
+function marketplaceLocations(claudeDir) {
+  const pluginsDir = join(claudeDir, "plugins");
+  const out = [];
+  const known = readJson(join(pluginsDir, "known_marketplaces.json"));
+  if (known && typeof known === "object") {
+    for (const [name, v] of Object.entries(known)) {
+      if (typeof v?.installLocation === "string") out.push({ name, root: v.installLocation });
+    }
+  }
+  const dir = join(pluginsDir, "marketplaces");
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const root = join(dir, e.name);
+      if (e.isDirectory() && !out.some((o) => o.root === root)) out.push({ name: e.name, root });
+    }
+  } catch {
+    /* no marketplaces dir */
+  }
+  return out;
+}
+
+/**
+ * The plugin directory a marketplace entry points at, or null when it is a
+ * remote source or resolves outside the clone, on the written path or on the
+ * real path.
+ */
+function sourceDir(root, entry, name) {
+  const src = entry?.source;
+  const rel =
+    typeof src === "string"
+      ? src
+      : typeof src?.path === "string"
+        ? src.path
+        : typeof src?.source === "string" && !/^[a-z]+:/i.test(src.source)
+          ? src.source
+          : `plugins/${name}`;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(rel)) return null;
+  const dir = join(root, rel);
+  if (!inside(root, dir)) return null;
+  const realRoot = realOrNull(root);
+  const realDir = realOrNull(dir);
+  if (!realRoot || !realDir || !inside(realRoot, realDir)) return null;
+  return { dir, realRoot };
+}
+
+/**
+ * A local marketplace clone that carries `name`, found from the host's
+ * known_marketplaces.json, then by scanning <claudeDir>/plugins/marketplaces.
+ * @returns {{marketplace: string, root: string, skillsDir: string, version: string|null,
+ *            index: string|null, skills: string[]}|null}
+ */
+export function findMarketplacePlugin(name, claudeDir) {
+  for (const loc of marketplaceLocations(claudeDir)) {
+    const manifest = readJson(join(loc.root, ".claude-plugin", "marketplace.json"));
+    const entry = (manifest?.plugins || []).find((p) => p?.name === name);
+    const found = sourceDir(loc.root, entry, name);
+    if (!found) continue;
+    const { dir, realRoot } = found;
+    const skillsDir = join(dir, "skills");
+    const realSkills = realOrNull(skillsDir);
+    if (!realSkills || !isDir(realSkills) || !inside(realRoot, realSkills)) continue;
+    const meta = readJson(join(dir, ".claude-plugin", "plugin.json"));
+    const index = join(skillsDir, "index", "SKILL.md");
+    const realIndex = realOrNull(index);
+    return {
+      marketplace: manifest?.name || loc.name,
+      root: dir,
+      skillsDir,
+      version: meta?.version ?? entry?.version ?? null,
+      index: realIndex && inside(realRoot, realIndex) && isFile(realIndex) ? index : null,
+      skills: skillsUnder(skillsDir),
+    };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Repo-local skills
+
+/** Minimal frontmatter reader: `key: value` lines and `|` / `>` block scalars. */
+export function frontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return {};
+  const out = {};
+  const lines = m[1].split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(lines[i]);
+    if (!kv) continue;
+    let val = kv[2].trim();
+    if (/^[|>][-+]?$/.test(val)) {
+      const block = [];
+      while (i + 1 < lines.length && /^\s+\S|^\s*$/.test(lines[i + 1]))
+        block.push(lines[++i].trim());
+      val = block.join(" ").trim();
+    }
+    val = val.replace(/^(["'])(.*)\1$/, "$2");
+    out[kv[1]] = val;
+  }
+  return out;
+}
+
+function claudeMdLines(repo) {
+  const out = [];
+  for (const rel of CLAUDE_MD) {
+    try {
+      for (const line of readFileSync(join(repo, rel), "utf8").split(/\r?\n/)) {
+        out.push({ rel, line });
+      }
+    } catch {
+      /* absent CLAUDE.md is normal */
+    }
+  }
+  return out;
+}
+
+function escapeRe(name) {
+  return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function nameRe(name) {
+  return new RegExp(`(^|[^A-Za-z0-9-])${escapeRe(name)}([^A-Za-z0-9-]|$)`, "i");
+}
+
+/**
+ * How a task names an explicit-only skill: `/name`, `` `name` `` or
+ * "skill <name>". A bare word is not an invocation: `release` must not fire on
+ * "Fix crash in release notes".
+ */
+export function explicitNameRe(name) {
+  const n = escapeRe(name);
+  const end = "(?![A-Za-z0-9-])";
+  return new RegExp(`(?:^|[\\s(])/${n}${end}|\`/?${n}\`|\\bskill[:\\s]+\`?/?${n}${end}`, "i");
+}
+
+/**
+ * `<repo>/.claude/skills/<name>/SKILL.md`, with explicit-only detection. A
+ * skill whose directory or SKILL.md resolves outside the repo is not read; it is
+ * pushed to `rejected` with its reason.
+ * @param {string} repo
+ * @param {{path: string, reason: string}[]} [rejected]
+ */
+export function discoverRepoSkills(repo, rejected = []) {
+  const dir = join(repo, REPO_SKILLS_DIR);
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const root = realOrNull(repo);
+  if (!root) return [];
+  const md = claudeMdLines(repo);
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory() && !(e.isSymbolicLink() && isDir(join(dir, e.name)))) continue;
+    const rel = `${REPO_SKILLS_DIR}/${e.name}/SKILL.md`;
+    const real = realOrNull(join(dir, e.name, "SKILL.md"));
+    if (!real) continue;
+    if (!inside(root, real)) {
+      rejected.push({ path: rel, reason: "SKILL.md resolves outside the repo" });
+      continue;
+    }
+    let text;
+    try {
+      text = readFileSync(real, "utf8");
+    } catch {
+      continue;
+    }
+    const fm = frontmatter(text);
+    const name = fm.name || e.name;
+    const description = fm.description || "";
+    let explicitOnlyReason = null;
+    if (String(fm["disable-model-invocation"]).toLowerCase() === "true") {
+      explicitOnlyReason = "frontmatter disable-model-invocation: true";
+    } else if (EXPLICIT_ONLY.test(description)) {
+      explicitOnlyReason = "description asks for explicit invocation";
+    } else {
+      const re = nameRe(name);
+      const hit = md.find((l) => re.test(l.line) && EXPLICIT_ONLY.test(l.line));
+      if (hit) explicitOnlyReason = `${hit.rel}: "${hit.line.trim().slice(0, 160)}"`;
+    }
+    out.push({
+      name,
+      description,
+      path: rel,
+      explicitOnly: explicitOnlyReason !== null,
+      explicitOnlyReason,
+      shadows: [],
+    });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const STOP = new Set(
+  "the and for with this that from into when then than are was were has have had not but you your our its any all can use using run via per new app"
+    .split(" ")
+    .filter(Boolean),
+);
+
+function stem(w) {
+  return w.replace(/(ing|ed|es|s)$/, "");
+}
+
+function tokens(text) {
+  return new Set(
+    String(text || "")
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((w) => w.length >= 3 && !STOP.has(w))
+      .map(stem),
+  );
+}
+
+/**
+ * Rank repo-local skills against a task by word overlap with name and
+ * description. A skill the task names is always a match; an explicit-only skill
+ * matches ONLY when invoked by name (`/name`, `` `name` ``, "skill <name>").
+ * @returns {{name: string, score: number, reason: string}[]}
+ */
+export function matchRepoSkills(skills, task, { minScore = 2 } = {}) {
+  const want = tokens(task);
+  const out = [];
+  for (const s of skills) {
+    if (s.explicitOnly) {
+      if (explicitNameRe(s.name).test(task)) {
+        out.push({ name: s.name, score: 100, reason: "invoked by name in the task" });
+      }
+      continue;
+    }
+    if (nameRe(s.name).test(task)) {
+      out.push({ name: s.name, score: 100, reason: "named in the task" });
+      continue;
+    }
+    const have = tokens(`${s.name.replace(/-/g, " ")} ${s.description}`);
+    const shared = [...want].filter((w) => have.has(w));
+    if (shared.length >= minScore) {
+      out.push({ name: s.name, score: shared.length, reason: `shares ${shared.join(", ")}` });
+    }
+  }
+  return out.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+}
+
+/** A telemetry.skillCalls[] entry for a skill read from a marketplace fallback. */
+export function marketplaceSkillCall(
+  fallback,
+  skill,
+  { phase = DEV_PHASE, targetFiles = [], timestamp } = {},
+) {
+  const version = fallback.version ?? "unknown";
+  return {
+    skill: `${fallback.toolkit}:${skill}`,
+    source: "marketplace-fallback",
+    toolkit: fallback.toolkit,
+    version,
+    phase,
+    targetFiles,
+    routedBy: `${fallback.toolkit}:index@${version}`,
+    timestamp: timestamp ?? new Date().toISOString(),
+  };
+}
+
+/** A telemetry.skillCalls[] entry for a repo-local skill that was loaded. */
+export function repoSkillCall(name, { phase = DEV_PHASE, targetFiles = [], timestamp } = {}) {
+  return {
+    skill: name,
+    source: "repo",
+    phase,
+    targetFiles,
+    routedBy: `repo:${REPO_SKILLS_DIR}`,
+    timestamp: timestamp ?? new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+
+function detection(repo, doc) {
+  const coarse = detectCoarse(repo);
+  const resolved = resolveStack(repo, { doc, coarse });
+  const adapters = resolved.adapters.map((a) => a.id);
+  const conclusive = coarse.ok && (coarse.stacks.length > 0 || adapters.length > 0);
+  const repoWords = new Set();
+  for (const s of coarse.stacks) for (const e of expand(s)) repoWords.add(e);
+  for (const id of adapters) for (const w of words(id)) repoWords.add(w);
+  return {
+    stacks: coarse.stacks,
+    adapters,
+    why: coarse.why,
+    conclusive,
+    words: [...repoWords].sort(),
+    filter: conclusive
+      ? "inherited toolkits are filtered by the detected stacks"
+      : `no filter: detection inconclusive (${coarse.ok ? coarse.why || "no marker matched" : coarse.why})`,
+  };
+}
+
+function hintsFor(det, kept, doc, manifestPath) {
+  const hints = [];
+  for (const s of det.stacks) {
+    const own = new Set(expand(s));
+    for (const id of det.adapters) {
+      const claimed = doc.adapters[id]?.detection?.stackDetect;
+      if (!claimed || claimed === s) for (const w of words(id)) own.add(w);
+    }
+    const covered = kept.some((t) => !t.alwaysOn && t.stacks.some((w) => own.has(w)));
+    if (covered) continue;
+    const r = pluginsForStacks([s], { manifestPath });
+    const plugin = r.plugins.find((p) => !ALWAYS_ON.includes(p)) ?? null;
+    const dropped = r.dropped.find((p) => !ALWAYS_ON.includes(p)) ?? null;
+    hints.push({
+      stack: s,
+      plugin: plugin ?? dropped,
+      message: plugin
+        ? `stack "${s}" detected but no toolkit for it is enabled: enable ${plugin} with /multi-agent:stack ${s}`
+        : `stack "${s}" detected and the marketplace has no toolkit for it (${dropped})`,
+    });
+  }
+  return hints;
+}
+
+function modeOf(state, env) {
+  if (runMode(state, env).unattended) return "unattended";
+  return gatesActive(state, env) ? "autopilot" : "attended";
+}
+
+/**
+ * Classify one enabled toolkit: kept with a role, excluded, or unscoped.
+ * @returns {{kind: "kept"|"excluded"|"unscoped", role?: string, reason: string}}
+ */
+function classify(entry, det) {
+  const { alwaysOn, source, stacks } = entry;
+  if (alwaysOn) return { kind: "kept", role: "common", reason: "always-on toolkit" };
+  if (!INHERITED.has(source)) {
+    return { kind: "kept", role: "stack", reason: `enabled by the repo (${source} settings)` };
+  }
+  if (!stacks.length) {
+    if (entry.hasIndex) {
+      return {
+        kind: "kept",
+        role: "common",
+        reason:
+          "inherited; its name and plugin.json mark no stack, and it ships an index: common role only",
+      };
+    }
+    return {
+      kind: "unscoped",
+      reason:
+        "inherited; its name and plugin.json mark no stack and it ships no index: not routed to (attended runs may load it only when the user names it)",
+    };
+  }
+  if (!det.conclusive) return { kind: "kept", role: "stack", reason: det.filter };
+  const hit = stacks.filter((w) => det.words.includes(w));
+  if (hit.length) {
+    return { kind: "kept", role: "stack", reason: `matches detected stack (${hit.join(", ")})` };
+  }
+  return {
+    kind: "excluded",
+    reason: `inherited from user settings; marks ${stacks.join(", ")} but the repo is ${
+      det.stacks.join(", ") || det.adapters.join(", ")
+    } (${det.why})`,
+  };
+}
+
+// The toolkits the pipeline itself publishes. On an otherwise even tie they
+// win, so which skill a run binds to never depends on how an outside
+// toolkit's name happens to sort.
+let OWN_TOOLKITS = null;
+function ownToolkits() {
+  if (!OWN_TOOLKITS) {
+    try {
+      OWN_TOOLKITS = new Set(pluginsForStacks(KNOWN_STACKS).plugins);
+    } catch {
+      OWN_TOOLKITS = new Set();
+    }
+  }
+  return OWN_TOOLKITS;
+}
+const isOwn = (t) => ownToolkits().has(t.name);
+
+function ownerOrder(a, b) {
+  const role = PRECEDENCE.indexOf(a.role) - PRECEDENCE.indexOf(b.role);
+  if (role) return role;
+  const scope = SCOPES.indexOf(a.source) - SCOPES.indexOf(b.source);
+  if (scope) return scope;
+  const own = Number(isOwn(b)) - Number(isOwn(a));
+  if (own) return own;
+  return a.name.localeCompare(b.name);
+}
+
+function ruleBetween(w, l) {
+  if (w.role !== l.role) return `${w.role} role over ${l.role} role`;
+  if (w.source !== l.source) {
+    return `narrowest enabling scope (${w.source} settings over ${l.source} settings)`;
+  }
+  if (isOwn(w) !== isOwn(l)) {
+    return `same role and scope (${w.source} settings): the pipeline's own toolkit`;
+  }
+  return `same role and scope (${w.source} settings): first by toolkit name`;
+}
+
+/** One owner per skill name that more than one candidate ships. */
+function overlapsFor(repoSkills, toolkits) {
+  const owners = new Map();
+  for (const t of toolkits) {
+    for (const s of t.skills || []) {
+      if (META_SKILLS.has(s)) continue;
+      if (!owners.has(s)) owners.set(s, []);
+      owners.get(s).push(t);
+    }
+  }
+  const overlaps = [];
+  const decisions = [];
+  for (const s of repoSkills) {
+    const shadowed = owners.get(s.name) || [];
+    for (const t of toolkits) {
+      if (t.skills?.includes(s.name)) s.shadows.push(`${t.name}:${s.name}`);
+    }
+    if (!s.shadows.length) continue;
+    decisions.push(
+      `${s.name}: repo skill ${s.path} wins over ${s.shadows.join(", ")} for this repo`,
+    );
+    if (shadowed.length) {
+      overlaps.push({
+        skill: s.name,
+        winner: "repo",
+        losers: shadowed.map((t) => t.name).sort(),
+        rule: "repo-local skill over any toolkit",
+      });
+    }
+    owners.delete(s.name);
+  }
+  for (const [skill, list] of [...owners].sort(([a], [b]) => a.localeCompare(b))) {
+    if (list.length < 2) continue;
+    const sorted = [...list].sort(ownerOrder);
+    const [w, ...rest] = sorted;
+    const rule = ruleBetween(w, rest[0]);
+    overlaps.push({ skill, winner: w.name, losers: rest.map((t) => t.name), rule });
+    decisions.push(
+      `${skill}: ${w.name}:${skill} wins over ${rest.map((t) => `${t.name}:${skill}`).join(", ")} (${rule})`,
+    );
+  }
+  return { overlaps, decisions };
+}
+
+/**
+ * @param {string} repo
+ * @param {{home?: string, manifestPath?: string, doc?: object,
+ *          env?: Record<string, string|undefined>, state?: object|null}} [opts]
+ */
+export function resolveSkillCandidates(repo, opts = {}) {
+  const env = opts.env ?? process.env;
+  const claudeDir = userConfigDir({ home: opts.home, env });
+  const mode = modeOf(opts.state ?? null, env);
+  const doc = opts.doc ?? loadAdapters();
+  const vocab = stackVocabulary(doc);
+  const det = detection(repo, doc);
+
+  const toolkits = [];
+  const excluded = [];
+  const unscoped = [];
+  const notes = [];
+  for (const [key, { on, source }] of effectiveEnabled(repo, claudeDir)) {
+    if (!on) continue;
+    const [name, marketplace = null] = key.split("@");
+    const info = installedPlugin(key, claudeDir);
+    if (!isToolkit(name, info)) continue;
+    const entry = {
+      name,
+      marketplace,
+      source,
+      alwaysOn: ALWAYS_ON.includes(name),
+      stacks: toolkitStacks(name, info.meta, vocab),
+      version: info.version,
+      installPath: info.installPath,
+      skills: info.skills,
+      hasIndex: hasIndex(info),
+    };
+    const c = classify(entry, det);
+    if (c.kind === "kept") toolkits.push({ ...entry, role: c.role, reason: c.reason });
+    else if (c.kind === "excluded") excluded.push({ ...entry, reason: c.reason });
+    else unscoped.push({ ...entry, reason: c.reason });
+  }
+  for (const n of ALWAYS_ON) {
+    if (!toolkits.some((t) => t.name === n)) {
+      notes.push(`${n} is always-on but not enabled here; /multi-agent:stack enables it`);
+    }
+  }
+
+  const rejectedRepoSkills = [];
+  const repoSkills = discoverRepoSkills(repo, rejectedRepoSkills);
+  const { overlaps, decisions } = overlapsFor(repoSkills, toolkits);
+
+  const hints = det.conclusive ? hintsFor(det, toolkits, doc, opts.manifestPath) : [];
+  const fallbacks = [];
+  if (mode !== "attended") {
+    for (const h of hints) {
+      if (!h.plugin) continue;
+      const found = findMarketplacePlugin(h.plugin, claudeDir);
+      if (!found) {
+        fallbacks.push({
+          stack: h.stack,
+          toolkit: h.plugin,
+          gap: `no marketplace clone carries ${h.plugin}; continuing with the enabled toolkits`,
+        });
+        continue;
+      }
+      fallbacks.push({
+        stack: h.stack,
+        toolkit: h.plugin,
+        ...found,
+        readOnly: true,
+        reportLine: `${h.plugin} is not enabled for this repo; this ${mode} run read its skills read-only from the ${found.marketplace} marketplace clone (version ${found.version ?? "unknown"}). Enable it with /multi-agent:stack ${h.stack}.`,
+      });
+    }
+  }
+
+  return {
+    repo,
+    mode,
+    precedence: PRECEDENCE,
+    detection: det,
+    toolkits,
+    excluded,
+    unscoped,
+    hints,
+    fallbacks,
+    repoSkills,
+    rejectedRepoSkills,
+    overlaps,
+    decisions,
+    notes,
+  };
+}
+
+/**
+ * The task text from `--task-file <path>`, `--task -` (stdin) or `--task <text>`.
+ * @returns {{task?: string, error?: string}}
+ */
+export function readTaskArg(args, { stdin = () => readFileSync(0, "utf8") } = {}) {
+  const at = (flag) => {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+  const file = at("--task-file");
+  const literal = at("--task");
+  let text;
+  try {
+    if (file !== undefined) text = file === "-" ? stdin() : readFileSync(file, "utf8");
+    else if (literal === "-") text = stdin();
+    else text = literal;
+  } catch (e) {
+    return { error: `cannot read --task-file ${file}: ${e.code || e.message}` };
+  }
+  if (text === undefined) return {};
+  return { task: String(text).slice(0, MAX_TASK_BYTES).trim() };
+}
+
+if (invokedDirectly(import.meta.url)) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const arg = (flag) => {
+    const i = rest.indexOf(flag);
+    return i >= 0 ? rest[i + 1] : undefined;
+  };
+  const dir = arg("--dir");
+  if (cmd !== "resolve" || !dir) {
+    console.error(
+      "usage: skill-candidates.mjs resolve --dir <repo> [--task-file <path> | --task -] [--home <dir>] [--state <file>]",
+    );
+    process.exit(2);
+  }
+  const statePath = arg("--state");
+  let state = null;
+  if (statePath) {
+    state = readJson(statePath);
+    if (!state) {
+      console.error(`skill-candidates: cannot read state ${statePath}`);
+      process.exit(2);
+    }
+  }
+  const { task, error } = readTaskArg(rest);
+  if (error) {
+    console.error(`skill-candidates: ${error}`);
+    process.exit(2);
+  }
+  const out = resolveSkillCandidates(dir, { home: arg("--home"), state });
+  if (task) out.repoMatches = matchRepoSkills(out.repoSkills, task);
+  process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+}