simt-dev 0.7.0 → 0.8.0

package/src/projection/surfaces.mjs

@@ -53,9 +53,16 @@
 //      unverified assumption into every repo that adopted it, which is the exact
 //      failure this table exists to prevent.
 
+import { harnessPointers, harnessScopeKeys, harnessSurfaces } from '../harness/records.mjs';
+
 /**
  * Surfaces, in the order the writer emits them.
  *
+ * The rows are data records under `harnesses/` (Q71): a surface is a fact about a vendor,
+ * and a new one arrives as a new file, not a table edit (ADR-013). The engine attaches
+ * the one facet a record cannot carry — `ruleFrontmatter`, a function — by id below,
+ * and nothing else.
+ *
  * `kind`:
  *   - `region`  a generated region inside a file the repo may also write by hand
  *   - `file`    a wholly generated file; hand-written body text is retired
@@ -80,180 +87,35 @@
  * `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.
  */
-export const SURFACES = [
-  {
-    // THE STANDARD SURFACE. One repo, one editor, one file — unless the agent or the
-    // repo's owner names another. This row exists because "write a file for every IDE
-    // we know" is not support: it gives a repo that lives in opencode three rule
-    // directories and two symlinks it will never open, and it means every rule change
-    // lands in four places instead of one. ADR-020 wrote all four; ADR-021 writes one
-    // and asks.
-    id: 'opencode',
-    label: 'opencode (AGENTS.md + .agents/skills)',
-    readers:
-      'OpenCode v2, and AGENTS.md is also read natively by Codex, Cursor, Windsurf, Zed, Amp, Jules, Copilot CLI and the DeepSeek harness; Claude Code falls back to it, Antigravity and Gemini CLI accept GEMINI.md as an equal name',
-    primary: 'AGENTS.md',
-    kind: 'region',
-    // OpenCode v2 documents no per-rule directory. It reads AGENTS.md only — every
-    // file from the workspace up to the project root, combined — and it does not fall
-    // back to CLAUDE.md. So `foldRules`: this surface carries every rule inside the
-    // one generated region, and the other rows are how a rule reaches an editor that
-    // cannot read AGENTS.md. Writing .opencode/rules/*.md would be a guess, and a
-    // 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
-    // project_doc_max_bytes. The default is 32 KiB. A region that ends past it is
-    // never read, and nothing else in check notices. Other readers of this file
-    // publish no such limit.
-    readLimits: [
-      {
-        reader: 'Codex',
-        bytes: 32768,
-        verified: 'Codex project_doc_max_bytes defaults to 32 KiB',
-      },
-    ],
-    verified:
-      'OpenCode v2 instructions and skills docs (opencode.ai/v2/docs, read 2026-10-14) — AGENTS.md only, combined from the workspace up to the project root; CLAUDE.md is not a fallback; skills at .opencode/skills/, .claude/skills/ and .agents/skills/<name>/SKILL.md, with the model shown name and description',
-    note:
-      '.agents/skills is one of the three skill locations opencode documents, so the same directory serves the standard surface without a symlink.',
-  },
-  {
-    id: 'cursor',
-    label: 'Cursor rules',
-    readers: 'Cursor',
-    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
-    // rule. The guard lives in test/shipped.test.mjs, and this row is its evidence.
-    documentedKeys: ['description', 'alwaysApply', 'globs'],
-    // ADR-021 ruled that "a Cursor reader getting .mdc files does not serve them",
-    // because Cursor had no documented channel for AGENTS.md. It does, and has:
-    // cursor.com/docs/context/rules calls AGENTS.md "a simple alternative to
-    // .cursor/rules" and documents support in the project root and subdirectories.
-    // So a folded rule reaches a Cursor reader twice - once inside the region, once
-    // in the .mdc - and the second copy is 28 KB of pure repetition across the five
-    // repos that select both surfaces.
-    //
-    // The caveat belongs here rather than in the ADR body, because it is a fact about
-    // a product and products move: a Cursor bug report records AGENTS.md NOT being
-    // read in worktree agents by default, fixed in 3.9. A reader below that version
-    // gets the .mdc copy and a reader above it does not need it.
-    readsPrimary: true,
-    // Filled into a substitution only when every selected surface names the same
-    // 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`}`,
-      // `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.',
-  },
-  {
-    id: 'claude',
-    label: 'Claude Code rules',
-    readers: 'Claude Code',
-    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: () => [],
-    // The claude-md pointer makes CLAUDE.md a symlink to AGENTS.md (ADR-021 ruling 1),
-    // and Claude reads CLAUDE.md in preference to AGENTS.md. So the folded region
-    // arrives through the pointer and a rule file alongside it is the same text twice.
-    readsPrimary: true,
-    substitutions: { askTool: 'Use the interactive `AskUserQuestion` tool' },
-    verified: 'Claude Code, "Organize rules with .claude/rules/" — recursive discovery, symlinks supported, no `paths` loads at session start',
-    note:
-      'CLAUDE.md is a separate pointer surface (see POINTERS). A rule file without frontmatter loads eagerly, which is what an always-on rule wants.',
-  },
-  {
-    id: 'antigravity',
-    label: 'Antigravity workspace rules',
-    readers: 'Antigravity IDE, Antigravity CLI',
-    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'],
-    // The gemini-md pointer's own `verified` cites the same Antigravity docs: "workspace
-    // rules are AGENTS.md or GEMINI.md in the root or any subdirectory". Either name
-    // reaches the reader, so a .agents/rules file repeats text the region already
-    // carries. Both channels are documented as alternatives to each other, which is
-    // what makes them duplicates rather than a fallback.
-    readsPrimary: true,
-    ruleFrontmatter: (rule) => [
-      // `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; 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.',
-  },
-  {
-    id: 'copilot',
-    label: 'GitHub Copilot instructions',
-    readers: 'GitHub Copilot chat, Copilot CLI, Copilot code review, Copilot cloud agent',
-    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: (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, 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
-    // of the three, and dropping it would remove the process rules from a chat that
-    // had no other channel to them.
-    note:
-      'Copilot reads AGENTS.md itself through Copilot CLI, but the editor and code review do not; this is the channel they use.',
-  },
-];
+// `ruleFrontmatter` is the one facet a record cannot carry: it is a function, and JSON
+// carries data. Attached by id, so a surface that needs none (opencode) keeps the row
+// exactly as the record wrote it.
+const RULE_FRONTMATTER = {
+  cursor: (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'}`,
+  ],
+  // Intentionally no `paths:`. See decision 3 in the header.
+  claude: () => [],
+  antigravity: (rule) => [
+    // `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`}`,
+  ],
+  copilot: (rule) => [`applyTo: ${rule.scope ? `"${rule.scope.join(',')}"` : '"**"'}`],
+};
+
+export const SURFACES = harnessSurfaces().map((row) =>
+  RULE_FRONTMATTER[row.id] ? { ...row, ruleFrontmatter: RULE_FRONTMATTER[row.id] } : row,
+);
 
 /**
  * Pointers: files that must exist and must carry no content.
@@ -263,37 +125,7 @@ export const SURFACES = [
  * that fails loudly, whereas a stale copy is a file full of confidently wrong
  * rules that nobody notices for a release.
  */
-export const POINTERS = [
-  {
-    id: 'claude-md',
-    // A pointer belongs to the surface that needs it, never to every repo.
-    // ADR-020 wrote both of these unconditionally, which meant that narrowing to
-    // one surface under ADR-021 still created a CLAUDE.md nobody asked for — the
-    // same over-writing that ruling set out to stop, one file down.
-    surface: 'claude',
-    path: 'CLAUDE.md',
-    to: 'AGENTS.md',
-    readers: 'Claude Code',
-    verified:
-      'Claude Code memory docs: "A symlink also works" — `ln -s AGENTS.md CLAUDE.md`; Claude reads CLAUDE.md by default and AGENTS.md only as a fallback',
-    note:
-      'Claude Code reads CLAUDE.md and ignores AGENTS.md when both exist. A pointer is what makes one file answer for both without a second copy.',
-  },
-  {
-    id: 'gemini-md',
-    surface: 'antigravity',
-    path: 'GEMINI.md',
-    to: 'AGENTS.md',
-    readers: 'Gemini CLI, Antigravity',
-    verified:
-      'Google Antigravity docs, "Rules": workspace rules are AGENTS.md or GEMINI.md in the root or any subdirectory; Copilot CLI also discovers GEMINI.md. ' +
-      'Gemini CLI, read today: its own docs (core memory index, and the configuration reference) say the memory service loads GEMINI.md hierarchically from the working directory up to the project root and the home directory and also into subdirectories, and that `context.fileName` in settings.json "accepts either a single string or an array of strings" naming the context file(s) to load, default undefined',
-    note:
-      'Covers Gemini CLI and gives Antigravity a second, equally-native name for the same file. ' +
-      'A repository can also point Gemini CLI at AGENTS.md itself with `context.fileName: ["AGENTS.md"]` and need no pointer at all, ' +
-      'which is the reason there is no separate Gemini CLI row here: this pointer and a native row would be two ways to hand one reader the same rule.',
-  },
-];
+export const POINTERS = harnessPointers();
 
 /**
  * The global standard: what a repo gets when it has not chosen.
@@ -362,7 +194,7 @@ export function canScope(surface) {
 }
 
 /** Surface ids whose scoping key was read in the vendor's own documentation. */
-const SCOPE_KEYS = new Set(['cursor', 'antigravity', 'copilot']);
+const SCOPE_KEYS = harnessScopeKeys();
 
 /**
  * Surfaces whose reader already loads the primary document, so a per-rule file for
@@ -488,10 +320,11 @@ export function surface(id) {
 
 /** The absolute-ish path a rule takes on a surface, given the rule's bare name. */
 /** Assemble YAML frontmatter lines into a block. Lives here because this is the
- *  lowest module that owns frontmatter: surfaces.mjs imports nothing, so both
- *  the `.mdc` renderer and the per-surface projector can share one implementation
- *  without either importing the other. Two copies of these four lines is the
- *  "third copy of the same logic is a defect" case with a third-copy count of two. */
+ *  lowest module that owns frontmatter: surfaces.mjs imports neither of its consumers
+ *  (its only import is the data records), so both the `.mdc` renderer and the
+ *  per-surface projector can share one implementation without either importing the
+ *  other. Two copies of these four lines is the "third copy of the same logic is a
+ *  defect" case with a third-copy count of two. */
 export function frontmatterBlock(lines) {
   if (lines.length === 0) return '';
   return ['---', ...lines, '---'].join('\n');

package/src/projection/targets.mjs

@@ -19,6 +19,7 @@ import { diff, parse, inject } from './markers.mjs';
 import { ruleName } from './mdc.mjs';
 import { foldsRules, frontmatterBlock, POINTERS, rulePath, SURFACES } from './surfaces.mjs';
 import { foldChecks } from '../kernel/checks.mjs';
+import { frontmatterBlock as extractBlock, stripFrontmatter } from '../text/frontmatter.mjs';
 
 /**
  * A managed rule file is a GENERATED FILE, unlike AGENTS.md.
@@ -276,8 +277,7 @@ export async function pointerState(root, pointer) {
 export { rulePath };
 
 export function extractFrontmatter(text) {
-  const m = /^---\n[\s\S]*?\n---\n?/.exec(text);
-  return m ? m[0].trimEnd() : null;
+  return extractBlock(text);
 }
 
 /**
@@ -296,10 +296,10 @@ export function extractFrontmatter(text) {
  */
 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)}`;
+  const block = extractBlock(text);
+  return block === null ? `${frontmatter}\n${text}` : `${frontmatter}${text.slice(block.length)}`;
 }
 
 function bodyAfterFrontmatter(text) {
-  return text.replace(/^---\n[\s\S]*?\n---\n*/, '');
+  return stripFrontmatter(text);
 }

package/src/repo-root.mjs

@@ -50,6 +50,37 @@ export function repoRoot(cwd) {
   }
 }
 
+/**
+ * The directory a command works on: `--root`, else the first positional when the command
+ * takes one, else the current directory.
+ *
+ * This precedence is a user-visible contract, not an implementation detail: it decides
+ * which directory `--root .` and a bare positional mean, and thirty-four commands had
+ * their own copy of it. The copies drifted - some resolved the answer, some did not; some
+ * read `args[0]`, some `positional[0]` - so the same argv could name two directories
+ * depending on which command read it (review 0003 Q65).
+ *
+ * The answer is returned verbatim, not resolved: a caller that wants an absolute path
+ * says so, and a command that reports the root it was given still reports what the reader
+ * typed. `repoRoot` answers the different question of which repository that directory
+ * belongs to.
+ */
+/**
+ * The root a caller named, or undefined when they named none.
+ *
+ * Absent is not the current directory here. `upgrade` walks a workspace and only limits
+ * itself to one project when the caller said which; collapsing "no root" into cwd made a
+ * bare `simt upgrade` plan a single project instead of the workspace, which is the defect
+ * the two-step resolution exists to prevent.
+ */
+export function namedRoot(flags = {}, positional = []) {
+  return flags.root ?? positional[0];
+}
+
+export function commandRoot(flags = {}, positional = []) {
+  return namedRoot(flags, positional) ?? process.cwd();
+}
+
 /**
  * Whether git on this repository compares paths case-insensitively, which is
  * the one filesystem fact a path comparison must honour: on a case-insensitive

package/src/resolve/eval.mjs

@@ -6,7 +6,8 @@
 // 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';
+import { rankSkills } from './resolve.mjs';
+import { tokenize } from '../text/tokens.mjs';
 
 /** The skill names the resolver selects for one case's declared signals and task. */
 function selectForCase(registry, c) {

package/src/resolve/fingerprint.mjs

@@ -19,10 +19,11 @@
 
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
-import { basename, join } from 'node:path';
+import { join } from 'node:path';
 
 import { matchesGlob } from './resolve.mjs';
 import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+import { loadManifest } from '../manifest/schema.mjs';
 
 /** tag -> human-readable marker(s) that imply it. First match wins per tag. */
 const MARKERS = [
@@ -225,6 +226,12 @@ export async function fingerprint(root) {
   }
   const names = new Set(entries);
 
+  // One walk answers every `glob` fact. Each candidate used to walk the tree again, so
+  // a repository with seven globs paid for seven identical walks - the same directories,
+  // in the same order, for the same answer (review 0003 Q67).
+  let nested = null;
+  const nestedPaths = async () => (nested ??= await listNested(root));
+
   for (const [tag, markers] of MARKERS) {
     const hit = markers.find((m) => names.has(m));
     if (hit) {
@@ -249,7 +256,7 @@ export async function fingerprint(root) {
         break;
       }
       if (fact.kind === 'glob') {
-        const hit = (await findNested(root, candidate))[0];
+        const hit = findNestedIn(await nestedPaths(), candidate)[0];
         if (hit) {
           facts.add(fact.name);
           factEvidence[fact.name] ??= hit;
@@ -306,12 +313,6 @@ export async function fingerprint(root) {
     }
   }
 
-  // two repositories both carry a wear/ module; only one of them is the wearable.
-  if (names.has('wear') && (await isDir(join(root, 'wear')))) {
-    stack.add('wear-os');
-    evidence.push('wear/');
-  }
-
   // Either spelling: a repository that adopted this tool has one of the two on disk,
   // and a fingerprint that missed the manifest would silently lose the repo's own
   // declared stack - which is the one input no amount of marker reading can replace.
@@ -320,9 +321,9 @@ export async function fingerprint(root) {
     : names.has(MANIFEST_LEGACY)
       ? MANIFEST_LEGACY
       : null;
-  const manifest = manifestName === null
-    ? null
-    : await readManifest(join(root, manifestName));
+  // One reader, so a file that does not parse is a missing declaration rather than an
+  // object whose only key is "error" pretending to be this repo manifest (Q69).
+  const manifest = manifestName === null ? null : (await loadManifest(root)).manifest;
 
   const stackList = [...stack].sort();
   const factList = [...facts].sort();
@@ -339,14 +340,6 @@ export async function fingerprint(root) {
   };
 }
 
-async function readManifest(path) {
-  try {
-    return JSON.parse(await readFile(path, 'utf8'));
-  } catch {
-    return { error: `${basename(path)} unparseable` };
-  }
-}
-
 async function isDir(path) {
   try {
     return (await stat(path)).isDirectory();
@@ -364,7 +357,7 @@ async function isDir(path) {
  * are skipped for the reason the extension sample skips them: detection is not a
  * scan of vendored output.
  */
-async function findNested(root, pattern) {
+async function listNested(root) {
   const found = [];
   const walk = async (dir, prefix, depth) => {
     let items;
@@ -378,7 +371,7 @@ async function findNested(root, pattern) {
       const rel = prefix ? `${prefix}/${item.name}` : item.name;
       if (item.isDirectory()) {
         if (depth < GLOB_DEPTH) await walk(join(dir, item.name), rel, depth + 1);
-      } else if (matchesGlob(rel, pattern)) {
+      } else {
         found.push(rel);
       }
     }
@@ -387,6 +380,11 @@ async function findNested(root, pattern) {
   return found.sort();
 }
 
+/** The paths in the one walk that match a shape. */
+function findNestedIn(paths, pattern) {
+  return paths.filter((rel) => matchesGlob(rel, pattern)).sort();
+}
+
 /**
  * Which extensions this repository is written in.
  *
@@ -543,7 +541,6 @@ export const STACK_TAGS = new Set([
   ...MARKERS.map(([tag]) => tag),
   ...EXTENSION_TAGS.values(),
   ...DEP_TAGS.values(),
-  'wear-os', // derived from a wear/ module, not a marker file
 ]);
 
 /** Every fact `fingerprint()` can emit, derived for the same reason as above. */

package/src/resolve/resolve.mjs

@@ -10,6 +10,7 @@
 
 import { matchesGlob as pathMatchesGlob } from 'node:path';
 import { STACK_TAGS } from './fingerprint.mjs';
+import { STOPWORDS, tokenize } from '../text/tokens.mjs';
 
 /** Signal weights. Deliberately few, so the ranking is explainable. */
 const W = {
@@ -30,47 +31,6 @@ const W = {
  */
 export const MIN_SCORE = W.capability;
 
-/**
- * English function words, which appear in every summary this registry has and identify
- * none of them.
- *
- * Applied to the summary signal ONLY. A keyword is an explicit declaration and a name is
- * an identity, so suppressing those would hide something a person wrote on purpose;
- * a summary is prose, and prose is full of words that are there for grammar. Measured:
- * the task "fix a typo in the README" selected four skills on `summary:the` and
- * `summary:in` alone. Hand-authored rather than derived, for the same reason the
- * capability aliases are: a resolver nobody can review is not a resolver.
- */
-const STOPWORDS = new Set([
-  'about', 'after', 'all', 'also', 'and', 'an', 'any', 'are', 'as', 'at', 'be', 'because',
-  'been', 'before', 'being', 'both', 'but', 'by', 'can', 'could', 'did', 'do', 'does', 'each',
-  'for', 'from', 'had', 'has', 'have', 'he', 'her', 'here', 'his', 'how', 'if', 'in', 'into',
-  'is', 'it', 'its', 'just', 'like', 'make', 'many', 'may', 'me', 'more', 'most', 'must', 'my',
-  'no', 'not', 'now', 'of', 'off', 'on', 'one', 'only', 'onto', 'or', 'other', 'our', 'out',
-  'over', 'own', 'per', 'same', 'see', 'set', 'she', 'should', 'so', 'some', 'such', 'than',
-  'that', 'the', 'their', 'them', 'then', 'there', 'these', 'they', 'this', 'those', 'to', 'too',
-  'two', 'under', 'up', 'us', 'use', 'used', 'using', 'very', 'was', 'way', 'we', 'were', 'what',
-  'when', 'where', 'which', 'while', 'who', 'why', 'will', 'with', 'within', 'without', 'would',
-  'you', 'your',
-]);
-
-/**
- * Split a task string into comparable tokens.
- *
- * Length 2 is kept. The floor used to be 3, and it dropped the most specific words in
- * this domain: `d1`, `r2`, `kv`, `ci` are two-letter vocabulary, not noise, and a task
- * saying "fix d1 migration" lost the one word that identified the change. The cost is
- * that six stopwords of two letters (`in on of or an so`) now reach the summary signal,
- * which is S04's finding and not something this change can resolve on its own - the
- * remedy there is a stopword list, not a longer minimum.
- */
-export function tokenize(text) {
-  return String(text ?? '')
-    .toLowerCase()
-    .split(/[^a-z0-9]+/)
-    .filter((t) => t.length > 1);
-}
-
 /**
  * Whether `phrase` occurs in `tokens` as consecutive words.
  *

package/src/review/critic.mjs

@@ -16,23 +16,21 @@
 // earned, the same honesty ADR-076 asked of R38's metric note.
 
 import { readFile, mkdir, writeFile } from 'node:fs/promises';
-import { execFile } from 'node:child_process';
 import { join, resolve } from 'node:path';
-import { promisify } from 'node:util';
 
 import { EXIT, fail } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { readLocalConfig, chatEndpoint } from '../local/config.mjs';
 import { localChat } from '../local/client.mjs';
 import { decisionRecords, loadCorpus, tracked } from '../commands/why.mjs';
-import { decisionHits, scopeHits, sortHits, sourceRoots } from '../index/govern.mjs';
+import { governs, sourceRoots } from '../index/govern.mjs';
 // `digestOf`, `promptHash` and `proposalFrontmatter` landed with R38's engine and
 // the critic is their second real user; sharing them beats a third copy (ADR-002).
 import { digestOf, promptHash, proposalFrontmatter } from '../distill/engine.mjs';
-
-const exec = promisify(execFile);
+import { git } from '../sys/git.mjs';
 
 import { LOCAL_DIR } from '../state.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 // Locked on-disk beneath machine-local state, like the distilled cache (R38) —
 // proposals keyed by content digest, never projected and never committed.
@@ -118,8 +116,7 @@ async function governingItems(root, files, commands = []) {
   const ctx = { files: fileSet, commands: new Set(commands), roots: sourceRoots(files) };
   const items = new Map();
   for (const file of files) {
-    const { hits } = decisionHits(records, file, ctx);
-    for (const hit of sortHits([...hits, ...scopeHits(file, corpus)])) {
+    for (const hit of governs(file, { records, ...corpus, ctx })) {
       if (!items.has(hit.id)) items.set(hit.id, hit);
     }
   }
@@ -216,7 +213,7 @@ export async function reviewTarget(args, flags, { write = true, commands = [] }
   if (args.length > 0) {
     return fail(`unknown review argument ${args[0]}`, EXIT.USAGE, `usage: ${CLI} review [--local]`);
   }
-  const root = resolve(flags.root ?? process.cwd());
+  const root = resolve(commandRoot(flags));
   const listed = await tracked(root);
   if (listed.error) return listed.error;
 
@@ -224,11 +221,11 @@ export async function reviewTarget(args, flags, { write = true, commands = [] }
   let names;
   try {
     const [diff, changed] = await Promise.all([
-      exec('git', ['diff', '--staged'], { cwd: root, maxBuffer: 64 << 20 }),
-      exec('git', ['diff', '--staged', '--name-only'], { cwd: root, maxBuffer: 8 << 20 }),
+      git(root, ['diff', '--staged'], { maxBuffer: 64 << 20 }),
+      git(root, ['diff', '--staged', '--name-only'], { maxBuffer: 8 << 20 }),
     ]);
-    patch = diff.stdout;
-    names = changed.stdout.split('\n').filter(Boolean);
+    patch = diff;
+    names = changed.split('\n').filter(Boolean);
   } catch (error) {
     return fail(
       `could not read the staged diff here (${error.message})`,
@@ -442,7 +439,7 @@ export async function criticBench(root, { labelsPath, flags, commands = [] }) {
 async function peer(root, sha, flags, endpoint, commands) {
   let diff;
   try {
-    diff = (await exec('git', ['show', '--unified=2', sha], { cwd: root, maxBuffer: 64 << 20 })).stdout;
+    diff = await git(root, ['show', '--unified=2', sha], { maxBuffer: 64 << 20 });
   } catch (error) {
     return { failed: true, exitMessage: error.message };
   }