simt-dev 0.7.1 → 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

@@ -65,8 +65,20 @@ export function repoRoot(cwd) {
  * 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 flags.root ?? positional[0] ?? process.cwd();
+  return namedRoot(flags, positional) ?? process.cwd();
 }
 
 /**

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

@@ -313,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.
@@ -547,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,21 +16,18 @@
 // 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';
@@ -119,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);
     }
   }
@@ -225,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})`,
@@ -443,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 };
   }

package/src/run.mjs

@@ -0,0 +1,98 @@
+// `run(command, input)` - one command, as a result (review 0003 Q63).
+//
+// The CLI prints and returns an exit code; that is right for a terminal and useless for a
+// library, an MCP tool or a harness that wants the answer. Rather than rewrite seventy
+// command modules to return values they do not currently compute, this runs the same
+// handler through the output sink: the handler is unchanged, and what it would have
+// written comes back as data.
+//
+// That is a boundary, not a second implementation. `dispatch` and `run` resolve the same
+// registry, apply the same flag guard rails and call the same function, so a command
+// cannot work in one and not the other - the failure would be invisible in the CLI, which
+// is why `test/run.test.mjs` drives both surfaces.
+//
+// What a caller gets is not a rendering decision made for them: `text` and `documents` are
+// both there when the command produced both, and `renderText`/`renderJson` are the two
+// answers the CLI had. A caller that wants neither reads the fields a command exported
+// (`src/api.mjs`).
+
+import { EXIT, clearWarnings, jsonCommand, jsonFailMode, jsonIndentDefault, maxBytesLimit, warnings, withOutputState, withSink } from './output/index.mjs';
+import { CLI } from './name.mjs';
+import { GLOBAL_FLAGS, resolveCommand } from './commands/index.mjs';
+
+/** `--some-flag` for a flag key the parser handed back as `someFlag`. */
+function spelled(key) {
+  return key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+
+function failure(command, code, message, remedy) {
+  return {
+    command,
+    ok: false,
+    code,
+    text: '',
+    documents: [],
+    notes: [],
+    warnings: [],
+    error: { message, remedy: remedy ?? `run: ${CLI} --help`, exitCode: code },
+  };
+}
+
+/**
+ * Run one command path and answer with what it produced.
+ *
+ * @param {string} command the dispatch key: `status`, `plan next`, `hooks install`
+ * @param {{args?: string[], flags?: object, root?: string}} [input]
+ */
+export async function run(command, { args = [], flags = {}, root } = {}) {
+  const resolved = await resolveCommand(command);
+  if (resolved === null) return failure(command, EXIT.USAGE, `unknown command \`${command}\``);
+
+  // The guard rails the dispatcher applies, applied here for the same reason: a library
+  // caller that passes `--frozen` to `status` must be told, not quietly served a default.
+  for (const key of Object.keys(flags)) {
+    if (GLOBAL_FLAGS.has(key) || resolved.declared.has(spelled(key))) continue;
+    return failure(command, EXIT.USAGE, `--${spelled(key)} is not a flag of \`${command}\``);
+  }
+  for (const [flag, allowed] of Object.entries(resolved.values)) {
+    const value = flags[flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase())];
+    if (value !== undefined && !allowed.includes(value)) {
+      return failure(command, EXIT.USAGE, `--${flag} takes ${allowed.join(', ')}; received ${value}`);
+    }
+  }
+
+  clearWarnings();
+  jsonCommand(command);
+  jsonIndentDefault(flags.pretty === true);
+  maxBytesLimit(flags.maxBytes);
+  jsonFailMode(flags.json === true);
+
+  const effective = root === undefined ? flags : { root, ...flags };
+  const produced = await withOutputState(() => withSink(() => resolved.run(args, effective)));
+  return {
+    command,
+    ok: produced.code === EXIT.OK,
+    code: produced.code,
+    text: produced.text,
+    documents: produced.documents,
+    notes: produced.notes,
+    warnings: warnings(),
+    error: produced.error,
+  };
+}
+
+/** The text the command printed, as one string. Empty when it answered in JSON. */
+export function renderText(result) {
+  return result.text;
+}
+
+/**
+ * The document the command emitted, or null when it answered as text.
+ *
+ * A command that emits a stream (NDJSON) has more than one document and gets an array:
+ * collapsing a stream to its first element is how a caller silently loses rows.
+ */
+export function renderJson(result) {
+  if (result.documents.length === 0) return null;
+  return result.documents.length === 1 ? result.documents[0] : result.documents;
+}

package/src/secrets.mjs

@@ -23,10 +23,7 @@
 //     is documentation, and a gate that blocks it teaches the exact `--no-verify`
 //     habit the dispatcher's fail-closed rule exists to prevent.
 
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-
-const exec = promisify(execFile);
+import { git } from './sys/git.mjs';
 
 /** The length at which a token is worth measuring, and the entropy it must reach. */
 const ENTROPY_MIN_LENGTH = 32;
@@ -294,24 +291,19 @@ export async function scanStaged(root, options = {}) {
     // program that prints nothing, `-diff` in `.gitattributes` and genuinely binary
     // files make git print no text at all, a textconv rewrites the bytes on the way
     // out, `diff.mnemonicPrefix` renames the header prefixes the attribution below
-    // reads, and C-quoting mangles a non-ASCII name. The scan asks git for the staged
-    // bytes with its own flags and ignores what the repository asked for.
-    ({ stdout } = await exec(
-      'git',
-      [
-        '-c', 'core.quotePath=false',
-        'diff',
-        '--cached',
-        '--no-ext-diff',
-        '--no-textconv',
-        '--text',
-        '--unified=0',
-        '--no-color',
-        '--src-prefix=a/',
-        '--dst-prefix=b/',
-      ],
-      { cwd: root, maxBuffer: 32 * 1024 * 1024 },
-    ));
+    // reads. The scan asks git for the staged bytes with its own flags and ignores
+    // what the repository asked for.
+    stdout = await git(root, [
+      'diff',
+      '--cached',
+      '--no-ext-diff',
+      '--no-textconv',
+      '--text',
+      '--unified=0',
+      '--no-color',
+      '--src-prefix=a/',
+      '--dst-prefix=b/',
+    ]);
   } catch (error) {
     const stderr = String(error.stderr ?? '').trim();
     const reason = (stderr || String(error.message ?? error)).split('\n')[0];