simt-dev 0.2.0 → 0.2.2

package/src/projection/surfaces.mjs

@@ -41,7 +41,11 @@
 //      #19377), and the documented examples are not valid YAML. Every rule
 //      shipped here is always-on, so the key would buy nothing and cost a
 //      silent-failure surface. Absence of frontmatter is documented to load
-//      eagerly, which is exactly what is wanted.
+//      eagerly, which is exactly what is wanted. (S50 ruled on this: a rule
+//      that carries a scope is emitted ONLY for surfaces whose scoping key is
+//      documented and parsed correctly, and Claude is not one of them, which
+//      is why `canScope` below excludes it rather than trusting `documentedKeys`
+//      to carry the reason.)
 //
 //   4. `verified` IS THE POINT OF THE TABLE. A row whose `verified` is null was
 //      not checked against a vendor document, and the row says so where a reader
@@ -57,6 +61,22 @@
  *   - `file`    a wholly generated file; hand-written body text is retired
  *   - `pointer` a symlink to the primary target; carries no content of its own
  *
+ * `readsAgentsMd` is a vendor fact, in three values rather than two:
+ *   - `all`   every reader this row names loads AGENTS.md
+ *   - `some`  some of them do, and `readsAgentsMdNote` says which
+ *   - `none`  none does, so the row is the only channel its readers have
+ *
+ * It is not `readsPrimary`, which asks a different question: that one is about
+ * whether a per-rule file would duplicate text the region already carries, and it is
+ * only meaningful while folding is on. This one is about the FILE, and it is what
+ * decides whether a new harness needs a row at all - a harness that reads AGENTS.md
+ * is supported by the standard surface, whatever else it reads.
+ *
+ * `configDirs` are the directories whose presence implies the harness is in use.
+ * Detection reads them and claims nothing else: a directory a harness may create for
+ * other reasons is a presence, not a proof, and the command says "present", never
+ * "installed".
+ *
  * `ruleFrontmatter` returns the keys that editor reads BEFORE any rule text. A
  * surface that needs none returns '' and the projected file starts at the body.
  */
@@ -82,6 +102,8 @@ export const SURFACES = [
     // guessed path is the failure this table exists to prevent.
     rule: null,
     foldRules: true,
+    readsAgentsMd: 'all',
+    configDirs: ['.opencode'],
     skills: '.agents/skills',
     documentedSkillsPaths: ['.opencode/skills', '.claude/skills', '.agents/skills'],
     // Codex concatenates AGENTS.md from the root down and stops at
@@ -107,6 +129,8 @@ export const SURFACES = [
     primary: null,
     kind: 'file',
     rule: '.cursor/rules/{name}.mdc',
+    readsAgentsMd: 'all',
+    configDirs: ['.cursor'],
     // `documentedKeys` is the set the vendor's own docs name for this surface, and
     // `ruleFrontmatter` must emit nothing outside it. A key invented here would be
     // inert at best; on Antigravity an unrecognised value silently discards the
@@ -129,12 +153,17 @@ export const SURFACES = [
     // value. One body is written for all of them, so a Cursor name must not land
     // in a file Claude Code also reads.
     substitutions: { askTool: 'Use the interactive `AskQuestion` tool' },
-    ruleFrontmatter: (rule) =>
-      [
-        `description: ${rule.description ?? `Canonical ${rule.id} rule managed by simt-dev`}`,
-        `alwaysApply: ${rule.alwaysApply ? 'true' : 'false'}`,
-      ],
-    verified: 'Cursor project rules (.cursor/rules/*.mdc, description + alwaysApply + globs)',
+    ruleFrontmatter: (rule) => [
+      `description: ${rule.description ?? `Canonical ${rule.id} rule managed by simt-dev`}`,
+      // `globs` only appears when the rule declares a scope. Cursor attaches a rule
+      // with no globs on the strength of `alwaysApply` alone, so emitting either
+      // unquoted patterns on an eager rule or no globs at all on a scoped one is
+      // asking for the wrong loading behaviour.
+      ...(rule.scope ? [`globs: ${rule.scope.map((g) => `"${g}"`).join(', ')}`] : []),
+      `alwaysApply: ${rule.alwaysApply ? 'true' : 'false'}`,
+    ],
+    verified:
+      'Cursor project rules (.cursor/rules/*.mdc, description + alwaysApply + globs); alwaysApply: false with globs is "auto-attached when a matching file is in context", and the docs warn that alwaysApply: false with no description is manual @-mention only',
     note: 'The only surface that reads `.mdc`. Every other row here is a plain `.md` or a symlink.',
   },
   {
@@ -144,6 +173,16 @@ export const SURFACES = [
     primary: null,
     kind: 'file',
     rule: '.claude/rules/{name}.md',
+    // `some`, not `none`. It reads AGENTS.md - the same docs say CLAUDE.md is used only
+    // when no AGENTS.md exists - but only on that condition, so a repository that has a
+    // hand-written CLAUDE.md is read by neither. That is why this row still needs its
+    // own channel and a pointer: the fallback is not a channel, it is the absence of
+    // one, and a reader who relied on it would be relying on the reader deleting a
+    // file they wrote.
+    readsAgentsMd: 'some',
+    readsAgentsMdNote:
+      'CLAUDE.md is read first; AGENTS.md is read only when there is no CLAUDE.md, which is why the pointer exists',
+    configDirs: ['.claude'],
     // Intentionally no `paths:`. See decision 3 in the header.
     documentedKeys: ['paths', 'description'],
     ruleFrontmatter: () => [],
@@ -163,6 +202,8 @@ export const SURFACES = [
     primary: null,
     kind: 'file',
     rule: '.agents/rules/{name}.md',
+    readsAgentsMd: 'all',
+    configDirs: ['.agents'],
     // `trigger` is REQUIRED here and an unrecognised value discards the rule with no
     // message, which is why the value is mapped rather than passed through.
     documentedKeys: ['trigger', 'description', 'globs', 'glob'],
@@ -173,10 +214,15 @@ export const SURFACES = [
     // what makes them duplicates rather than a fallback.
     readsPrimary: true,
     ruleFrontmatter: (rule) => [
-      `trigger: ${rule.alwaysApply ? 'always_on' : 'model_decision'}`,
+      // `trigger: glob` carries the patterns, and they are quoted because YAML reads a
+      // value starting with `*` as an alias anchor — the Antigravity docs require it, and
+      // an invalid frontmatter block is discarded with no message at all.
+      `trigger: ${rule.scope ? 'glob' : rule.alwaysApply ? 'always_on' : 'model_decision'}`,
+      ...(rule.scope ? [`globs: ${rule.scope.map((g) => `"${g}"`).join(', ')}`] : []),
       `description: ${rule.description ?? `Canonical ${rule.id} rule managed by simt-dev`}`,
     ],
-    verified: 'Google Antigravity docs, "Rules" — .agents/rules/*.md, YAML frontmatter with trigger: always_on | model_decision | glob | manual; missing or invalid frontmatter silently discards the rule',
+    verified:
+      'Google Antigravity docs, "Rules" — .agents/rules/*.md, YAML frontmatter with trigger: always_on | model_decision | glob | manual; missing or invalid frontmatter silently discards the rule; trigger: glob takes comma-separated globs, which the docs require to be quoted so YAML does not read a leading * as an alias anchor; a 24 KB per-file limit and a 20,000-token budget for always_on rules, with automatic demotion to pointers past it',
     note:
       'This is why frontmatter is mandatory here and why the trigger value is not guessed: an unrecognised trigger means the rule is dropped with no message.',
   },
@@ -187,10 +233,18 @@ export const SURFACES = [
     primary: null,
     kind: 'file',
     rule: '.github/instructions/{name}.instructions.md',
+    // Copilot is why the column is three values and not two. Its CLI reads AGENTS.md
+    // and its editor and code review do not, so the row both needs its own channel and
+    // cannot be described as "reads AGENTS.md" without a reader reading that claim as
+    // "this repo is covered for Copilot", which for two of its three readers it is not.
+    readsAgentsMd: 'some',
+    readsAgentsMdNote:
+      'Copilot CLI reads AGENTS.md; the editor, code review and the cloud agent do not',
+    configDirs: ['.github'],
     documentedKeys: ['applyTo', 'excludeAgent'],
-    ruleFrontmatter: () => ['applyTo: "**"'],
+    ruleFrontmatter: (rule) => [`applyTo: ${rule.scope ? `"${rule.scope.join(',')}"` : '"**"'}`],
     verified:
-      'GitHub docs, "Adding repository custom instructions" — .github/instructions/NAME.instructions.md with applyTo globs; `applyTo: "**"` is the documented example',
+      'GitHub docs, "Adding repository custom instructions" — .github/instructions/NAME.instructions.md with applyTo globs; `applyTo: "**"` is the documented example, and a comma-separated pattern list is how more than one is named',
     // NOT marked readsPrimary, and this row is the reason the flag is per-surface
     // rather than global. The reader is split: Copilot CLI reads AGENTS.md, the
     // editor and code review do not. A per-rule file here is not duplication for two
@@ -277,6 +331,27 @@ export function foldsRules(resolved) {
   return resolved.surfaces.some((s) => s.foldRules === true);
 }
 
+/**
+ * Whether this surface can load a rule only when a matching file is in play.
+ *
+ * Three do, and each for its own documented key: Cursor patterns with `globs` under
+ * `alwaysApply: false`, Copilot with `applyTo`, and Antigravity with `trigger: glob`
+ * plus `globs`. Claude Code does not — its `paths:` key has a documented parser
+ * defect in which quoted values and YAML sequences silently fail to lazy-load — and
+ * opencode cannot, because it has no per-rule file channel at all.
+ *
+ * The question is asked per surface rather than per key because the answer decides
+ * whether a scoped profile may leave the region: a profile written only as a scoped
+ * file would be absent from a reader that cannot scope it, and a rule nobody loads is
+ * worse than a rule that loads eagerly (ADR-071).
+ */
+export function canScope(surface) {
+  return surface.rule !== null && surface.rule !== undefined && SCOPE_KEYS.has(surface.id);
+}
+
+/** Surface ids whose scoping key was read in the vendor's own documentation. */
+const SCOPE_KEYS = new Set(['cursor', 'antigravity', 'copilot']);
+
 /**
  * Surfaces whose reader already loads the primary document, so a per-rule file for
  * them repeats text the region already carries.
@@ -295,6 +370,37 @@ export function readsPrimary(resolved) {
 
 export const SURFACE_IDS = SURFACES.map((s) => s.id);
 
+/**
+ * Config directories whose presence implies a harness is in use, for the ones this
+ * tool has no surface row for.
+ *
+ * Deliberately a list of DIRECTORY NAMES and nothing else. It carries no claim about
+ * what any of these readers loads: the review that proposed the command listed these
+ * harnesses as candidates and explicitly did not re-verify each vendor's current
+ * documentation, and a row built from that list would ship a `verified` field citing
+ * nothing — decoration that misdescribes the artefact, which is the failure this whole
+ * repository exists to prevent. A directory here means "a reader may be configured in
+ * this repository", never "this harness is installed" and never "its rules are not
+ * being loaded".
+ *
+ * `.github` is absent even though the Copilot row carries it: `.github` holds workflows
+ * and issues, so its presence says nothing about whether Copilot is used, and the
+ * Copilot row's own detection is not something this command is for.
+ */
+export const CANDIDATE_DIRS = [
+  { dir: '.gemini', harness: 'Gemini CLI' },
+  { dir: '.windsurf', harness: 'Windsurf' },
+  { dir: '.zed', harness: 'Zed' },
+  { dir: '.kiro', harness: 'Kiro' },
+  { dir: '.cline', harness: 'Cline' },
+  { dir: '.roo', harness: 'Roo Code' },
+  { dir: '.junie', harness: 'Junie' },
+  { dir: '.aider', harness: 'Aider' },
+  { dir: '.continue', harness: 'Continue' },
+  { dir: '.amp', harness: 'Amp' },
+  { dir: '.goose', harness: 'Goose' },
+];
+
 /**
  * Frontmatter keys a surface emits that its own vendor does not document.
  *
@@ -313,10 +419,22 @@ export function undocumentedKeys(surfaceRows = SURFACES) {
   for (const s of surfaceRows) {
     if (!s.ruleFrontmatter) continue;
     const documented = Array.isArray(s.documentedKeys) ? s.documentedKeys : [];
-    for (const line of s.ruleFrontmatter({ id: 'probe', description: 'probe', alwaysApply: true })) {
-      const key = String(line).split(':')[0].trim();
-      if (!documented.includes(key)) {
-        bad.push(`${s.id} emits frontmatter key "${key}"; its vendor documents ${documented.join(', ') || '(nothing)'}`);
+    // Both shapes, because a scoping key is emitted only on the scoped shape: probing
+    // the eager one alone would pass a row that drops `globs` on a scoped rule, and the
+    // rule would then load on nothing.
+    const probes = [
+      { id: 'probe', description: 'probe', alwaysApply: true },
+      { id: 'probe', description: 'probe', alwaysApply: false, scope: ['src/**'] },
+    ];
+    for (const rule of probes) {
+      for (const line of s.ruleFrontmatter(rule)) {
+        const key = String(line).split(':')[0].trim();
+        // One report per key, not per probe: the same invented key appears on both
+        // shapes, and a gate that prints it twice reads as two defects.
+        if (documented.includes(key) || bad.some((b) => b.includes(`key "${key}"`))) continue;
+        bad.push(
+          `${s.id} emits frontmatter key "${key}"; its vendor documents ${documented.join(', ') || '(nothing)'}`,
+        );
       }
     }
   }

package/src/projection/targets.mjs

@@ -64,14 +64,45 @@ export async function ruleTargets(root, rule, body, sha, resolved, notes) {
     }
 
     const mine = s.ruleFrontmatter(rule);
-    const frontmatter = extractFrontmatter(existing) ?? frontmatterBlock(mine);
+    // The frontmatter is re-derived, never inherited (S16).
+    //
+    // Two things were wrong and only the second was visible. The first was
+    // `extractFrontmatter(existing) ?? frontmatterBlock(mine)`, where the file's own
+    // block won whenever the file already had one. The second was this line's
+    // neighbour: when the existing region parsed cleanly, `composed` was the whole
+    // existing file, so `inject` replaced the region between the markers and left the
+    // frontmatter above them exactly as it found it — whatever this tool emitted the
+    // first time it saw this surface, forever. A surface that adds a key, or whose
+    // `alwaysApply` flips, could never reach a repository that had already adopted it,
+    // and no gate could report it: the file agrees with itself, so nothing is stale by
+    // any comparison the tool makes.
+    //
+    // One asymmetry, deliberately: a surface that emits NO frontmatter leaves whatever
+    // is there alone. This tool owns the block it writes and will replace it; deleting a
+    // block it did not write is a different operation, and a surface with no frontmatter
+    // of its own has no opinion about it.
+    const frontmatter = mine.length > 0 ? frontmatterBlock(mine) : extractFrontmatter(existing) ?? '';
     const state = exists ? parse(existing) : { status: 'absent' };
     // A surface that wants no frontmatter must not get a blank line where the
     // frontmatter would have been: Claude's rule files opened with two empty lines
     // before the marker, which is untidy in a file the reader will open, and a
     // difference between surfaces that no check reported.
+    //
+    // Swapped in place rather than stripped and rejoined. My first attempt here was
+    // `${frontmatter}\n${bodyAfterFrontmatter(existing)}`, which looked equivalent and
+    // was not: that helper's trailing `\n*` swallows the blank line between `---` and
+    // the region, so the reconstruction was one newline short of the file and `inject`
+    // reported `updated` on every run forever while writing identical bytes. The file
+    // was right; the verdict never settled, so `check` reported drift no reader could
+    // see and `sync` rewrote a correct file on every invocation. Anything that rebuilds
+    // a file has to reproduce the bytes it did not mean to touch, and the cheapest way
+    // to guarantee that is not to rebuild them.
     const composed =
-      state.status === 'ok' ? existing : frontmatter === '' ? '' : `${frontmatter}\n`;
+      state.status === 'ok'
+        ? swapFrontmatter(existing, frontmatter)
+        : frontmatter === ''
+          ? ''
+          : `${frontmatter}\n`;
     const result = inject(composed, body, { sha, sources: [rule.source] });
 
     // Report the prose being retired rather than letting it vanish into a diff the
@@ -105,6 +136,43 @@ export async function ruleTargets(root, rule, body, sha, resolved, notes) {
   return { targets };
 }
 
+/**
+ * Per-rule files for the profiles that left the region, for the surfaces that can
+ * narrow them.
+ *
+ * A scoped profile is an ordinary rule with a `scope` on it, and that is the whole
+ * reason this is a thin wrapper over {@link ruleTargets} rather than a second
+ * construction: the byte-level concerns — frontmatter re-derived per surface, the
+ * region injected between the markers, the retired-prose note — are already decided
+ * there and must not be decided twice. A second implementation would drift from the
+ * first and the gate would report drift on a clean tree, which is the failure this
+ * module exists to prevent.
+ *
+ * The one thing it adds is the skip: a surface that folds the region carries the whole
+ * region already, so a scoped file is the duplication S12 removed — UNLESS the profile
+ * actually left the region, which is `narrowing`, the caller's answer, and which means
+ * the reader would otherwise get nothing.
+ */
+export async function scopedTargets(root, rules, sha, resolved, notes) {
+  const targets = [];
+  for (const rule of rules) {
+    // `alwaysApply: false` is what asks the surface to attach the file on the patterns
+    // rather than always. Cursor's documented reading of no description plus no globs is
+    // a manual @-mention, so a scoped rule carries its scope and the description it
+    // already had.
+    // `target` is what `ruleName` reads, and a stack profile has none: it is a plain
+    // `python.md`, not an `.mdc` in the rules directory. Without it the file is named
+    // `null.mdc`, which is exactly what the first version of this did.
+    const scoped = {
+      ...rule,
+      target: rule.target ?? `${rule.id}.mdc`,
+      alwaysApply: false,
+      scope: rule.scope,
+    };
+    targets.push(...(await ruleTargets(root, scoped, rule.body, sha, resolved, notes)).targets);
+  }
+  return { targets };
+}
 
 /**
  * Pointer targets: `CLAUDE.md` and `GEMINI.md` as symlinks to `AGENTS.md`.
@@ -201,11 +269,6 @@ export async function pointerState(root, pointer) {
   return { file: pointer.file, state: 'mispointed', link, detail: `points at ${link}` };
 }
 
-export function surfaceFrontmatter(surfaceId, rule) {
-  const s = SURFACES.find((x) => x.id === surfaceId);
-  return s && s.ruleFrontmatter ? s.ruleFrontmatter(rule) : [];
-}
-
 // The per-surface path lives in surfaces.mjs next to the row that justifies it;
 // re-exported so a caller building a target never has to know which module owns
 // path construction as opposed to frontmatter construction.
@@ -216,6 +279,26 @@ export function extractFrontmatter(text) {
   return m ? m[0].trimEnd() : null;
 }
 
+/**
+ * Put `frontmatter` where a frontmatter block already is, and leave every other byte
+ * exactly where it was.
+ *
+ * The block match deliberately stops at the closing `---` and not past it, so the
+ * replacement starts at the newline that follows — the blank line a formatter requires
+ * before an HTML comment survives belongs to the file, not to the block, and consuming
+ * it here is what made `inject` report `updated` forever on files whose bytes never
+ * changed.
+ *
+ * A file with no block gets one above its content. The separator below it is left to
+ * `inject`'s `seam`, which is the one place that knows what the surrounding document
+ * format requires.
+ */
+function swapFrontmatter(text, frontmatter) {
+  if (frontmatter === '') return text;
+  const m = /^---\n[\s\S]*?\n---/.exec(text);
+  return m === null ? `${frontmatter}\n${text}` : `${frontmatter}${text.slice(m[0].length)}`;
+}
+
 function bodyAfterFrontmatter(text) {
   return text.replace(/^---\n[\s\S]*?\n---\n*/, '');
 }

package/src/resolve/eval.mjs

@@ -0,0 +1,64 @@
+// Gold-corpus evaluation: run each case through the resolver and score it.
+//
+// Plan 0002 section 9: "A resolver that is not measured is a resolver that is merely
+// felt." The corpus (test/fixtures/eval-corpus.json) states, for real repository signals
+// and tasks, which skills must come back and which must not. Two callers must never
+// disagree about the score - `simt skills eval` reports it to a reader, and
+// test/eval.test.mjs asserts it in CI - so the arithmetic lives here once (ADR-002).
+
+import { rankSkills, tokenize } from './resolve.mjs';
+
+/** The skill names the resolver selects for one case's declared signals and task. */
+function selectForCase(registry, c) {
+  const context = {
+    repoStack: c.repo?.stack ?? [],
+    paths: c.repo?.paths ?? [],
+    taskTokens: tokenize(c.task ?? ''),
+  };
+  const { selected } = rankSkills(registry.skills, context);
+  return selected.map((e) => e.skill.name);
+}
+
+/** Skill names the corpus cites that the registry does not declare. */
+export function unknownSkills(registry, corpus) {
+  const names = new Set(registry.skills.map((s) => s.name));
+  return [
+    ...new Set(
+      corpus.cases.flatMap((c) => [...(c.select ?? []), ...(c.reject ?? [])]).filter((n) => !names.has(n)),
+    ),
+  ];
+}
+
+/**
+ * Score the whole corpus: per-case detail plus precision and recall.
+ *
+ * `unexpected` is the half of precision that named negatives cannot see: a case whose
+ * truth is "nothing" names only a sample of what must not come back, so for those the
+ * whole selected set is the miss. `clean` is what the exit code rests on; the two
+ * ratios are measurements, and a case can break `clean` while both still read 1.0 -
+ * the first version of this arithmetic scored that case a perfect precision (S19).
+ */
+export function scoreCorpus(registry, corpus) {
+  let expected = 0;
+  let negatives = 0;
+  const cases = corpus.cases.map((c) => {
+    expected += c.select?.length ?? 0;
+    negatives += c.reject?.length ?? 0;
+    const got = new Set(selectForCase(registry, c));
+    const missing = (c.select ?? []).filter((n) => !got.has(n));
+    const wronglySelected = (c.reject ?? []).filter((n) => got.has(n));
+    return {
+      name: c.name,
+      selected: [...got],
+      missing,
+      wronglySelected,
+      unexpected: c.select?.length === 0 ? [...got] : wronglySelected,
+    };
+  });
+  const missed = cases.reduce((n, c) => n + c.missing.length, 0);
+  const wrong = cases.reduce((n, c) => n + c.wronglySelected.length, 0);
+  const recall = expected === 0 ? 1 : (expected - missed) / expected;
+  const precision = negatives === 0 ? 1 : (negatives - wrong) / negatives;
+  const clean = missed === 0 && cases.every((c) => c.unexpected.length === 0);
+  return { cases, expected, missed, negatives, wrong, recall, precision, clean };
+}

package/src/resolve/fingerprint.mjs

@@ -178,6 +178,7 @@ const FACTS = [
   { name: 'has-pubspec', kind: 'file', paths: ['pubspec.yaml'] },
   { name: 'has-swift-package', kind: 'file', paths: ['Package.swift'] },
   { name: 'has-mix', kind: 'file', paths: ['mix.exs'] },
+  { name: 'has-deno-config', kind: 'file', paths: ['deno.json', 'deno.jsonc'] },
   { name: 'has-bun-lock', kind: 'file', paths: ['bun.lock', 'bun.lockb'] },
   // A glob walk skips dot directories, and `.devcontainer` is one. Stat the path.
   { name: 'has-devcontainer', kind: 'path', paths: ['.devcontainer/devcontainer.json'] },

package/src/resolve/near.mjs

@@ -10,7 +10,7 @@
 // suggestion that far away is noise: an agent will install the wrong skill.
 
 /** Levenshtein distance, two-row, with an early exit once the bound is passed. */
-export function editDistance(a, b, max = Infinity) {
+function editDistance(a, b, max = Infinity) {
   if (a === b) return 0;
   if (Math.abs(a.length - b.length) > max) return max + 1;
 
@@ -38,22 +38,41 @@ export function editDistance(a, b, max = Infinity) {
 /**
  * Candidates worth suggesting, nearest first.
  *
- * A substring hit is always included: `skill` is a real answer for a query of
- * `slice-commit`, and the distance test alone would rank it below noise.
+ * Two directions of substring, and they are not the same claim about what was typed.
+ *
+ * **The candidate contains the query** — `slice-commit` for `slice-commmit` — is a
+ * hit: the agent typed a prefix. It scores 1, not 0, because zero edits is what an
+ * exact match means and a prefix is not one. Scoring both 0 sorted `graph` ahead of
+ * `graphs` for the query `graphs`, and an agent that installs the first name in a
+ * "did you mean" list installs the wrong one.
+ *
+ * **The candidate sits inside the query** — `coverage` for `coverage-hunt` — is a hit
+ * only when it is at least half the query. Without that, the rule degenerates: `e` is
+ * a substring of `test`, so `nearMatches('test', ['e'])` returned `e` at distance 0
+ * and the message read `did you mean e?`.
+ *
+ * The bound also shrinks with the query, which is the same failure from the other side.
+ * Three edits is a typo in a name; three edits to a four-character query is a
+ * different string, and offering it violates the rule in the header of this file — "a
+ * suggestion that far away is noise: an agent will install the wrong skill". Under
+ * three characters nothing is a typo, so nothing is offered.
  */
 export function nearMatches(needle, candidates, { max = 3, limit = 3 } = {}) {
   if (!needle) return [];
   const lower = needle.toLowerCase();
+  const bound = Math.max(1, Math.min(max, Math.floor(lower.length / 3)));
 
   const scored = [];
   for (const candidate of candidates) {
     const cl = candidate.toLowerCase();
-    if (cl.includes(lower) || lower.includes(cl)) {
+    if (cl === lower) {
       scored.push({ candidate, distance: 0 });
-      continue;
+    } else if (cl.includes(lower) || (lower.includes(cl) && cl.length * 2 >= lower.length)) {
+      scored.push({ candidate, distance: 1 });
+    } else {
+      const distance = editDistance(lower, cl, bound);
+      if (distance <= bound) scored.push({ candidate, distance });
     }
-    const distance = editDistance(lower, cl, max);
-    if (distance <= max) scored.push({ candidate, distance });
   }
 
   scored.sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate));

package/src/resolve/resolve.mjs

@@ -210,7 +210,7 @@ export function stackCompatible(skill, repoSignals) {
  * agent knows it is standing in that repo, so name the overlapping tag when there
  * is one and say plainly when there is not.
  */
-export function stackReason(skill, repoSignals) {
+function stackReason(skill, repoSignals) {
   if (repoSignals.length === 0) return 'repo signals undetected, not excluded';
   const repo = new Set(repoSignals);
   const overlap = (skill.stack ?? []).filter((tag) => repo.has(tag));

package/src/resolve/source.mjs

@@ -35,7 +35,7 @@ import { measureSkill } from '../graph/load.mjs';
  *
  * @returns {{path: string, how: 'workspace'|'repo'}[]}
  */
-export function candidateLocations(source, { workspaceRoot = null, root = null } = {}) {
+function candidateLocations(source, { workspaceRoot = null, root = null } = {}) {
   const out = [];
   if (workspaceRoot) out.push({ path: join(workspaceRoot, source.repo, source.path), how: 'workspace' });
   if (root) out.push({ path: join(root, source.path), how: 'repo' });

package/src/workspace.mjs

@@ -252,15 +252,6 @@ function absolute(p) {
   return isAbsolute(expanded) ? expanded : resolve(expanded);
 }
 
-/**
- * The workspace, or null. Callers that can degrade use this and report `source: 'none'`;
- * callers that genuinely cannot proceed should use `resolveWorkspace` and fail with its detail.
- */
-export async function workspaceOrNull(flags = {}, options = {}) {
-  const { root, error } = await resolveWorkspace(flags, options);
-  return error ? null : root;
-}
-
 /**
  * The path a multi-repo command should work on: `--root` or the first positional if
  * given, else the resolved workspace, else the current directory.