simt-dev 0.6.3 → 0.7.0

package/src/decisions/index.mjs

@@ -14,13 +14,20 @@
 // such, because "no decision behind this" is exactly what a reviewer needs to
 // see and exactly what an empty output would hide.
 
-import { readFile, readdir } from 'node:fs/promises';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MANIFEST_FILE } from '../name.mjs';
 import { CLI } from '../name.mjs';
 import { PREFIX_ARGUING, TOOL_WORDS } from '../toolwords.mjs';
+import { LOCAL_DIR } from '../state.mjs';
+import { packageVersion } from '../package-version.mjs';
+// Q55: read lazily (see commandVerbs). The registry imports the `decide`
+// command, which imports this module, so touching COMMANDS during module
+// evaluation would read an initialising binding on one of the two load
+// orders. Every use below happens at runtime, when both sides are loaded.
+import { COMMANDS } from '../commands/index.mjs';
 import { PARTIAL_CLAUSE, parseDecisionFrontmatter, splitFrontmatter } from '../memory/decide.mjs';
 import { affectsTokens } from '../index/govern.mjs';
 
@@ -82,7 +89,16 @@ export function redactInternalPaths(text) {
   return String(text ?? '').replace(internalPathPattern(), 'a file in this tool');
 }
 
-const ADR_IN_TEXT = /\bADR-(\d{3})\b/g;
+// Q55: four digits and more are real record numbers, not a typo. The old `\d{3}`
+// silently dropped every citation past ADR-999, and lexical sorting put ADR-1000
+// before ADR-999 in every listing that trusted string order.
+const ADR_IN_TEXT = /\bADR-(\d{3,})\b/g;
+
+/** Numeric sort for record ids: ADR-1000 follows ADR-999, not ADR-100. */
+function compareAdrIds(a, b) {
+  const num = (id) => Number(id.replace(/^ADR-/i, ''));
+  return num(a) - num(b) || (a < b ? -1 : a > b ? 1 : 0);
+}
 
 /**
  * A line that begins one of the record's other front-matter fields.
@@ -159,7 +175,7 @@ export function citations(text) {
   for (const match of String(text ?? '').matchAll(ADR_IN_TEXT)) {
     found.add(`ADR-${match[1]}`);
   }
-  return [...found].sort();
+  return [...found].sort(compareAdrIds);
 }
 
 /**
@@ -252,7 +268,11 @@ export function parseDecision(file, text, { all = false } = {}) {
 export async function loadDecisions({ all = false, dir = DECISIONS_DIR } = {}) {
   let names;
   try {
-    names = (await readdir(dir)).filter((n) => /^ADR-\d{3,}-.*\.md$/.test(n)).sort();
+    // Numeric, so the first record `byId` keeps under a duplicate is deterministic
+    // (lint flags the collision; the load does not guess between two files).
+    names = (await readdir(dir))
+      .filter((n) => /^ADR-\d{3,}-.*\.md$/i.test(n))
+      .sort((a, b) => compareAdrIds(adrIdOf(a) ?? a, adrIdOf(b) ?? b));
   } catch (error) {
     return { ok: false, decisions: [], errors: [`${dir}: unreadable (${error.message})`] };
   }
@@ -300,11 +320,72 @@ export async function loadDecisions({ all = false, dir = DECISIONS_DIR } = {}) {
   return { ok: errors.length === 0, decisions, errors };
 }
 
+/** The record id a filename claims, or null when it claims none. */
+function adrIdOf(file) {
+  return /^ADR-(\d{3,})/i.exec(file)?.[0]?.toUpperCase() ?? null;
+}
+
 /** Index by id, for a lookup per cited ADR. */
 export function byId(decisions) {
   return new Map(decisions.map((d) => [d.id, d]));
 }
 
+/** The command verbs a record may quote, derived from the dispatch registry. */
+export function decisionVerbs() {
+  return commandVerbs();
+}
+
+/** One file's cache identity: name, size and mtime. Any write changes one of them. */
+async function fileSignature(dir, name) {
+  const st = await stat(join(dir, name));
+  return { name, size: st.size, mtimeMs: st.mtimeMs };
+}
+
+/**
+ * Load the records, reusing a machine-local cache when the tree is unchanged.
+ *
+ * Every call used to re-parse every record (`rules why` 44 ms; part of
+ * `resources/list` 771 ms). The cache lives under `.simt/local/` — machine
+ * state, never committed — and is keyed on the directory, the `all` flag, the
+ * running version and one signature per file, so an edit, an add or an upgrade
+ * all miss honestly. Best-effort throughout: any cache failure loads fresh.
+ *
+ * @param {{root: string, dir: string, all?: boolean}} input `dir` is absolute;
+ *   callers resolve it with `decisionsDir(root)` (or the package directory for
+ *   shipped records) so this loader never guesses whose records these are.
+ */
+export async function loadDecisionsCached({ root, dir, all = false } = {}) {
+  const cachePath = root ? join(root, LOCAL_DIR, 'decisions.index.json') : null;
+  let files = null;
+  try {
+    const names = (await readdir(dir)).filter((n) => /^ADR-\d{3,}-.*\.md$/i.test(n));
+    files = [];
+    for (const name of names) files.push(await fileSignature(dir, name));
+    files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  } catch {
+    return loadDecisions({ all, dir });
+  }
+  const key = { v: 1, tool: packageVersion(), dir, all, files };
+  if (cachePath) {
+    try {
+      const cached = JSON.parse(await readFile(cachePath, 'utf8'));
+      if (JSON.stringify(cached.key) === JSON.stringify(key)) return cached.result;
+    } catch {
+      // A missing or corrupt cache is a miss, never an error.
+    }
+  }
+  const fresh = await loadDecisions({ all, dir });
+  if (cachePath) {
+    try {
+      await mkdir(join(root, LOCAL_DIR), { recursive: true });
+      await writeFile(cachePath, JSON.stringify({ key, result: fresh }), 'utf8');
+    } catch {
+      // A read-only checkout keeps working uncached.
+    }
+  }
+  return fresh;
+}
+
 /**
  * What the decision actually says, in the reader's terms.
  *
@@ -506,7 +587,7 @@ const section = (name) => {
     // A record whose subject is the prefix is arguing rather than citing, so it names none.
     writtenAgainst: PREFIX_ARGUING.has(file)
       ? []
-      : [...new Set((text.match(ESTATE) ?? []).filter((name) => !TOOL_WORDS.has(name)))].sort(),
+      : [...new Set((text.match(ESTATE) ?? []).filter((name) => !TOOL_WORDS.has(name.toLowerCase())))].sort(),
   };
 }
 
@@ -545,8 +626,11 @@ const section = (name) => {
  * them - which is what this file used to do. Detection of those now depends on a name
  * never being written into shipped text, rather than on a check.
  */
-export const ESTATE_NAME =
-  /\b(?:simt-(?!dev\b)[\w-]+|repo-\d{2})\b/;
+// Q55: one shape, two flags. The estate-name pattern used to be written out twice
+// (`ESTATE_NAME` and `ESTATE`), so a shape fixed in one kept matching in the other.
+const ESTATE_SOURCE = '\\b(?:simt-(?!dev\\b)[\\w-]+|repo-\\d{2})\\b';
+
+export const ESTATE_NAME = new RegExp(ESTATE_SOURCE);
 
 /** Replace estate repository names with a phrase a reader who does not have them can use. */
 export function redactEstate(text) {
@@ -554,7 +638,7 @@ export function redactEstate(text) {
     // The tool's own names are left where they are. Redacting them turned a ruling about
     // `simt-priority` into a sentence about `a repository`, which is how a reader learned
     // that the record had surveyed something and not what it said (ADR-080).
-    TOOL_WORDS.has(name) ? name : 'a repository',
+    TOOL_WORDS.has(name.toLowerCase()) ? name : 'a repository',
   );
 }
 
@@ -575,10 +659,24 @@ export function redactEstate(text) {
  * Only a real verb follows, which is what keeps `simt-dev.json`, `simt-dev-check.yml` and
  * `simt-dev's` untouched - those are the project's artefacts and the project keeps its name.
  */
-const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|agent-hook|agent-hooks|mcp|rules|skills|graph|tokens|harness|bench|shared|evidence|index|map|tests|why|gate|impact|lessons|decide|brief|plan|--[a-z-]+)';
+// Q55: the verbs a record may quote are the commands this binary dispatches,
+// not a hand list. The list used to miss `pack`, `plugin` and `lease`, so a record
+// quoting one read as prose instead of a runnable command.
+let verbAlternation = null;
+function commandVerbs() {
+  if (verbAlternation === null) {
+    const words = new Set();
+    for (const path of COMMANDS) {
+      const first = path.split(' ')[0];
+      if (first) words.add(first.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    }
+    verbAlternation = `(?:${[...words].sort().join('|')}|--[a-z-]+)`;
+  }
+  return verbAlternation;
+}
 
 function redactCommand(text) {
-  return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${VERB})\\b`, 'g'), `${CLI} `);
+  return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${commandVerbs()})\\b`, 'g'), `${CLI} `);
 }
 
 /**
@@ -590,7 +688,7 @@ function redactCommand(text) {
  * enumerating the names here put the portfolio in every adopting repository. The records
  * themselves now carry `repo-NN` labels, so that is what this matches in practice.
  */
-const ESTATE = /\b(?:simt-(?!dev\b)[\w-]+|repo-\d{2})\b/gi;
+const ESTATE = new RegExp(ESTATE_SOURCE, 'gi');
 
 /** Trim to whole sentences within a budget, never leaving a stub fragment. */
 function sentence(text, limit = 260) {

package/src/distill/distill.mjs

@@ -34,7 +34,9 @@ import {
 } from './engine.mjs';
 
 export const DEFAULT_BUDGET = 2048;
-const DISTILL_DIR = '.simt/distilled';
+import { LOCAL_DIR } from '../state.mjs';
+
+const DISTILL_DIR = join(LOCAL_DIR, 'distilled');
 
 /**
  * The row's acceptance metric, stated where a caller reads results (ADR-076):

package/src/ecosystem/node-runner.mjs

@@ -0,0 +1,144 @@
+// The one Node runner resolver every consumer reads (review 0003 Q31).
+//
+// Before this, four tables answered "how does this repo run a script" and
+// disagreed: the card printed `npm run`, the dispatcher spawned `npm run`,
+// the manifest remedies named `npm run`, and CI installed with `npm ci` — in a
+// repository whose lockfile and `packageManager` said pnpm. A pnpm adoption
+// then failed on its first pull request, and a docs-only or Go repo got
+// remedies proposing npm gates it could never run.
+//
+// One data table, one resolver, every consumer. The table is records, not
+// code, so the Q70 ecosystem work can adopt it without a second answer: a
+// future `ecosystems/<id>.json` row carries the same fields and this resolver
+// stays the shape of the lookup.
+//
+// Precedence is committed evidence first. A lockfile on disk names the manager
+// the repo actually installs with; `packageManager` names the one it declares.
+// Where the two disagree `checkToolchain` already reports `mismatched`, and the
+// runner follows the lockfile — the install step must restore the tree CI
+// checks out, not the field. With no lockfile the declared field wins over the
+// npm default, so a fresh `pnpm init` names pnpm before its first install.
+
+export const NODE_MANAGERS = [
+  {
+    id: 'pnpm',
+    lockfiles: ['pnpm-lock.yaml'],
+    fact: 'has-pnpm-lock',
+    run: 'pnpm',
+    install: 'pnpm install --frozen-lockfile',
+    installFallback: 'pnpm install',
+    addDev: 'pnpm add -D',
+    silent: true,
+    setupNode: true,
+  },
+  {
+    id: 'yarn',
+    lockfiles: ['yarn.lock'],
+    fact: 'has-yarn-lock',
+    run: 'yarn',
+    install: 'yarn install --frozen-lockfile',
+    installFallback: 'yarn install',
+    addDev: 'yarn add -D',
+    silent: true,
+    setupNode: true,
+  },
+  {
+    id: 'bun',
+    lockfiles: ['bun.lock', 'bun.lockb'],
+    fact: 'has-bun-lock',
+    run: 'bun',
+    install: 'bun install --frozen-lockfile',
+    installFallback: 'bun install',
+    addDev: 'bun add -d',
+    silent: false,
+    setupNode: false,
+  },
+  {
+    id: 'npm',
+    lockfiles: ['package-lock.json'],
+    fact: 'has-package-lock',
+    run: 'npm',
+    install: 'npm ci',
+    installFallback: 'npm install',
+    addDev: 'npm i -D',
+    silent: true,
+    setupNode: true,
+  },
+];
+
+const BY_ID = new Map(NODE_MANAGERS.map((row) => [row.id, row]));
+const BY_LOCKFILE = new Map();
+for (const row of NODE_MANAGERS) {
+  for (const file of row.lockfiles) BY_LOCKFILE.set(file, row);
+}
+const BY_FACT = new Map(NODE_MANAGERS.map((row) => [row.fact, row]));
+
+/** The npm row. Exported so callers never spell a default twice. */
+export function npmManager() {
+  return BY_ID.get('npm');
+}
+
+/**
+ * Name the manager a `packageManager` field declares, or null.
+ *
+ * `packageManager` is `manager@version`; only the manager names the runner.
+ * Unknown managers and non-strings are null, never a guess.
+ */
+export function managerFromPackageField(value) {
+  if (typeof value !== 'string') return null;
+  const id = value.split('@')[0].trim();
+  return BY_ID.has(id) ? id : null;
+}
+
+/**
+ * Resolve the one Node runner for a repository.
+ *
+ * @param {{facts?: string[]|Set<string>, lockfiles?: string[], packageManager?: string|null}} input
+ * @returns {object} the NODE_MANAGERS row that owns this repo
+ */
+export function resolveNodeRunner({ facts = [], lockfiles = [], packageManager = null } = {}) {
+  const present = facts instanceof Set ? facts : new Set(facts);
+  for (const row of NODE_MANAGERS) {
+    if (present.has(row.fact)) return row;
+    for (const file of row.lockfiles) {
+      if (lockfiles.includes(file)) return row;
+    }
+  }
+  const declared = managerFromPackageField(packageManager);
+  if (declared) return BY_ID.get(declared);
+  return npmManager();
+}
+
+/** Whether this runner id spells gates as `<run> run <script>`. */
+export function isNodeRunner(runner) {
+  return BY_ID.has(runner);
+}
+
+/** The command that runs one script: `pnpm run lint`, `bun run lint`. */
+export function runScript(manager, script) {
+  const id = typeof manager === 'string' ? manager : manager?.id ?? 'npm';
+  const run = BY_ID.get(id)?.run ?? 'npm';
+  return `${run} run ${script}`;
+}
+
+/** The argv the dispatcher spawns for one script gate. */
+export function runScriptArgv(manager, script) {
+  const id = typeof manager === 'string' ? manager : manager?.id ?? 'npm';
+  const row = BY_ID.get(id) ?? npmManager();
+  if (row.silent) return [row.run, 'run', '--silent', script];
+  return [row.run, 'run', script];
+}
+
+/** Install step for CI: the frozen command plus its fallback. */
+export function installCommands(manager) {
+  const row = typeof manager === 'string' ? (BY_ID.get(manager) ?? npmManager()) : (manager ?? npmManager());
+  return { install: row.install, fallback: row.installFallback, setupNode: row.setupNode };
+}
+
+/** Look up a manager record by lockfile name, fact, or id. */
+export function lookupNodeManager({ lockfile = null, fact = null, id = null } = {}) {
+  if (id && BY_ID.has(id)) return BY_ID.get(id);
+  if (lockfile && BY_LOCKFILE.has(lockfile)) return BY_LOCKFILE.get(lockfile);
+  if (fact && BY_FACT.has(fact)) return BY_FACT.get(fact);
+  return null;
+}

package/src/explain.mjs

@@ -59,8 +59,8 @@ export const EXPLAIN_CODES = {
   },
   'file-lines': {
     what: 'A file exceeds the 1000-line hard ceiling: it fails the gate.',
-    why: 'ADR-005: 400 lines is a review trigger, 1000 is a hard ceiling, and generated files are exempt. The ceiling is a default a repository can narrow, never a number an agent negotiates at write time.',
-    fix: 'Split the file, or narrow the ceiling deliberately in the rule that declares it — not by editing the generated line.',
+    why: 'ADR-005: 400 lines is a review trigger, 1000 is a hard ceiling, and excluded files are exempt. The ceiling is a default a repository can narrow, never a number an agent negotiates at write time.',
+    fix: 'Split the file, or name it in limits.fileLines.exclude — not by editing the generated line.',
     example: 'A 1240-line module with no exemption: FILE-LINES names the file and the count.',
   },
   'file-lines-warn': {
@@ -94,10 +94,10 @@ export const EXPLAIN_CODES = {
     example: 'gates.cwd.test set to "../shared" in a monorepo member.',
   },
   inconsistent: {
-    what: 'The TypeScript base config disagrees with this tool\u2019s floor in a way no flag explains: the project\u2019s tsconfig and the shipped base describe different compilers.',
-    why: 'ADR-025 and ADR-026: the base file is owned here and pointed at there, so a disagreement is a real fork in what the typechecker enforces — not a formatting choice. A repo that edited the owned bytes is not drift, but a repo whose config contradicts them is.',
-    fix: 'Re-align the project tsconfig with the shipped base, or record why the fork is deliberate.',
-    example: 'A project tsconfig setting strict false under a base that requires it.',
+    what: 'The project\u2019s tsconfig spells `moduleResolution` in a form the TypeScript parser accepts but the documentation does not, so it compiles and quietly disagrees with every repository that spells it the documented way.',
+    why: 'The parser is case-insensitive, which is the whole reason a workspace drifts on this key: both spellings work, so nothing ever said the other one did not. Consistency with the documentation is the only spelling checkable in one repository at a time \u2014 consistency with the other repositories would need a workspace, and `check` runs in a repository on its own.',
+    fix: 'Use the documented spelling the finding names; it compiles identically.',
+    example: '"moduleResolution": "Bundler" where the documentation writes "bundler".',
   },
   inert: {
     what: 'The TypeScript base config is present but inert: nothing in the repository reads it, so it constrains no file.',
@@ -117,6 +117,12 @@ export const EXPLAIN_CODES = {
     fix: 'Fix the simt-supersedes entry to [{ adr: "ADR-NNN", ruling: N }], with a real record and ruling number.',
     example: 'simt-supersedes: [{ adr: "ADR-999", ruling: 1 }] when no ADR-999 exists.',
   },
+  'duplicate-decision-id': {
+    what: 'Two decision records claim one number: the index only sees the first, so the second is a record no provenance answer can reach.',
+    why: 'Review 0003 Q55: byId keeps one silently, and a reader of the other gets a decision the tooling cannot resolve. Failing names both files while the collision is still a rename, not a rewrite of history.',
+    fix: 'Renumber the newer record to a free number, then rerun the check.',
+    example: 'ADR-002-first.md and ADR-002-second.md: DUPLICATE-DECISION-ID names both.',
+  },
   'lock-absent': {
     what: 'No lock is recorded: the projection was never locked, so there is nothing `--frozen` can compare against.',
     why: 'ADR-086: the lock is the byte-identical contract across machines, and `--frozen` without one would compare the projection against nothing and call it current. Reported only under --frozen, because a repository that never locked is not drift.',
@@ -243,6 +249,12 @@ export const EXPLAIN_CODES = {
     fix: 'Read the detail (it carries the OS error): fix permissions, remove the broken link, then re-run.',
     example: 'AGENTS.md unreadable (EACCES): UNREADABLE with the errno, not ABSENT.',
   },
+  unresolvable: {
+    what: 'The checked-in gate workflow cannot resolve simt-dev by any path its locator tries: no pinned devDependency, no release binary, no simt on PATH.',
+    why: 'Review 0003 Q31: a green tick from a check that never ran is the one outcome worse than a red one. The workflow installs whatever the repo pins, so a repo that pins nothing gates nothing — reported here instead of failing open in CI.',
+    fix: 'Run the install the finding names (the repo manager\u2019s add-dev command) so CI restores the pinned dependency.',
+    example: 'A pnpm repo whose workflow says npm ci with no simt-dev dependency: UNRESOLVABLE names pnpm add -D.',
+  },
   unrunnable: {
     what: 'A declared gate cannot run here: the command it needs is not on PATH, or its runner is missing.',
     why: 'ADR-017: a gate that cannot run fails closed on every commit once hooks are installed — after the reader committed, which is the wrong order. check reports it before anyone installs anything, with the probe result that proved it.',

package/src/graph/load.mjs

@@ -154,10 +154,15 @@ export async function loadRegistry(path = null, flags = {}) {
   // errors are facts about ABSENCE - no registry here, or more than one and the reader must
   // pick - and are reported as such. A named path that is missing is a different fact: the
   // reader pointed at a file that is not there, and it names that path.
-  let where = path;
+  //
+  // Resolution order for the registry itself (review 0003 Q37): positional path,
+  // then `--registry`, then `SIMT_REGISTRY`, then the default tiers above.
+  const explicit =
+    path ?? flags?.registry ?? process.env.SIMT_REGISTRY ?? process.env.SIMT_DEV_REGISTRY ?? null;
+  let where = explicit;
   let resolveErrors = null;
   let resolvedWorkspace = null;
-  if (path === null) {
+  if (explicit === null) {
     const found = await defaultRegistry(flags);
     where = found.where;
     resolveErrors = found.errors;
@@ -181,7 +186,7 @@ export async function loadRegistry(path = null, flags = {}) {
     registry = JSON.parse(await readFile(where, 'utf8'));
   } catch (error) {
     const message =
-      path === null && error.code === 'ENOENT'
+      explicit === null && error.code === 'ENOENT'
         ? `no skill registry at ${where}; create one there, or name it explicitly`
         : `${where}: unreadable or invalid JSON (${error.message})`;
     return {
@@ -260,6 +265,11 @@ export async function loadRegistry(path = null, flags = {}) {
  * broken registry rather than a wrong pointer, which is exactly backwards.
  */
 function holdsAnyRepo(registry, root) {
+  // Every repo the registry names, vendored or not: the question is whether this
+  // directory is a workspace at all. Filtering out vendored sources made the check
+  // unsatisfiable the moment the last non-vendored skill left the registry - an
+  // all-vendored registry names repos just the same, and a home folder holds none
+  // of them.
   const named = new Set(
     (registry.skills ?? []).flatMap((s) => (s.sources ?? []).map((x) => x.repo)).filter(Boolean),
   );
@@ -282,14 +292,20 @@ export function lintRegistry(registry) {
   const threshold = registry.deferredThreshold ?? 20000;
 
   // --- shape -----------------------------------------------------------------
+  // Every check below assumes arrays of objects. A registry that fails the shape
+  // is already fully described by the shape error; continuing past it only
+  // trades one true error for a crash (`for..of` over `undefined`) or a pile of
+  // secondary noise, so the lint stops here (review 0003 Q35).
   if (!Array.isArray(registry.capabilities) || capabilities.size === 0) {
     err('capabilities: missing or empty');
   }
   if (!Array.isArray(registry.skills) || skills.length === 0) {
     err('skills: missing or empty');
+  }
+  if (errors.length > 0) {
     return { sync: errors, warnings, index };
   }
-  for (const c of registry.capabilities) {
+  for (const c of registry.capabilities ?? []) {
     if (!c.id || !c.summary) err(`capability ${c.id ?? '<no id>'}: needs id and summary`);
   }
 
@@ -449,22 +465,22 @@ function checkRequires(at, skill, index, err) {
     if (!index.has(dep)) err(`${at}: requires unknown skill "${dep}"`);
     if (dep === skill.name) err(`${at}: requires itself`);
   }
-  // Cycle detection over `requires`. Depth is bounded by node count, so an
-  // accidental cycle terminates rather than hanging the lint.
-  const seen = new Set([skill.name]);
-  let frontier = skill.requires ?? [];
-  while (frontier.length > 0) {
-    const next = [];
-    for (const dep of frontier) {
-      if (seen.has(dep)) {
-        err(`requires cycle: ${[...seen].join(' -> ')} -> ${dep}`);
+  // Cycle detection over `requires`, depth-first with a recursion stack. The old
+  // breadth-first walk shared one `seen` set across branches, so a diamond
+  // (a requires b and c; both require d) reported d's second visit as a cycle.
+  // Only a dependency already on the current path is a cycle; a node reached
+  // through two branches is sharing, not looping (review 0003 Q35).
+  const visit = (name, path) => {
+    const stack = [...path, name];
+    for (const dep of index.get(name)?.requires ?? []) {
+      if (stack.includes(dep)) {
+        err(`requires cycle: ${[...stack, dep].join(' -> ')}`);
         return;
       }
-      seen.add(dep);
-      next.push(...(index.get(dep)?.requires ?? []));
+      visit(dep, stack);
     }
-    frontier = next;
-  }
+  };
+  visit(skill.name, []);
 }
 
 function checkAlias(at, skill, index, err) {
@@ -570,6 +586,10 @@ async function lintSourcesOnDisk(registry, workspaceRoot) {
   const warnings = [];
 
   for (const skill of registry.skills ?? []) {
+    // A vendored skill ships with the package; its source is the package root,
+    // not a workspace member. Verifying it against the workspace filesystem is
+    // the wrong check (the path will not exist there by design).
+    if (skill.vendored) continue;
     for (const source of skill.sources ?? []) {
       const at = `${skill.name}: ${source.repo}/${source.path}`;
       if (!source.repo || !source.path) continue;
@@ -644,8 +664,7 @@ export async function measureSkill(full) {
     hasEntry = false;
   }
   if (!hasEntry) {
-    const md = files === 1 ? '' : '';
-    throw Object.assign(new Error(`${full} has no SKILL.md entry point${md}`), { code: 'NO_SKILL_MD' });
+    throw Object.assign(new Error(`${full} has no SKILL.md entry point`), { code: 'NO_SKILL_MD' });
   }
 
   return { bytes, files, flat: false };

package/src/hooks/capability.mjs

@@ -22,6 +22,7 @@ import { constants as fsConstants } from 'node:fs';
 import { access, readdir, readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { ECOSYSTEMS, manifestPath } from '../projection/manifest.mjs';
+import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
 
 /** Binaries the shared dispatcher shells out to directly, rather than via a script. */
 const BIN_DIR = join('node_modules', '.bin');
@@ -104,10 +105,22 @@ async function probeTool(root, eco) {
 export async function readCapability(root) {
   const capability = { scripts: {}, binaries: [], commands: {}, tools: [], runner: null, error: null };
 
+  // Q31: a package.json names a Node repo, but not which manager it installs
+  // with. The lockfile on disk wins over the `packageManager` field (the field
+  // can disagree; `checkToolchain` reports that), and the field wins over the
+  // npm default — so a `packageManager: pnpm@9` repo resolves pnpm before its
+  // first install, and every consumer below reads the same answer.
+  let packageManager = null;
   try {
     const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
     capability.scripts = manifest.scripts ?? {};
-    capability.runner = 'npm';
+    packageManager = typeof manifest.packageManager === 'string' ? manifest.packageManager : null;
+    const lockfiles = [];
+    for (const file of ['pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb', 'package-lock.json']) {
+      if (await fileExists(join(root, file))) lockfiles.push(file);
+    }
+    capability.runner = resolveNodeRunner({ lockfiles, packageManager }).id;
+    capability.packageManager = packageManager;
   } catch (error) {
     // A repo with no manifest is a normal shape — a Python or Gradle repo has no
     // package.json at all — so this is reported, never thrown. The gate filter treats