simt-dev 0.3.0 → 0.4.0

package/src/commands/gate.mjs

@@ -0,0 +1,165 @@
+// `simt gate` runs the tests a change reaches (R16, ADR-094).
+//
+// Paths name the change. `--changed` reads the diff instead. The tests are the
+// ones that import a changed file, directly or through other files, and the
+// runner is the one the package already uses. Nothing else runs. A report
+// this tool knows how to read is compacted; the raw log is kept.
+
+import { execFile } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { detectTestRunner } from '../bench/mine.mjs';
+import { compactOutput } from '../index/compact.mjs';
+import { readImportEdges, selectTests } from '../index/gate.mjs';
+import { packageOf } from '../index/store.mjs';
+
+const exec = promisify(execFile);
+
+export async function gateCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+  const listed = await tracked(root);
+  if (listed.error) return listed.error;
+  let changed = args.filter(Boolean);
+  if (flags.changed === true) {
+    const diff = await changedFiles(root);
+    if (diff.error) return diff.error;
+    changed = [...new Set([...changed, ...diff.files])].sort();
+  }
+  if (changed.length === 0) {
+    if (flags.changed === true) {
+      if (isJson(flags)) {
+        emitJson({ ok: true, command: 'gate', root, selected: [], code: 0 }, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+      } else {
+        emit('selected  0', { maxBytes: flags.maxBytes ?? 0 });
+      }
+      return EXIT.OK;
+    }
+    return fail(`nothing changed`, EXIT.USAGE, `pass a path, or ${CLI} gate --changed`);
+  }
+  const files = new Set(listed.files);
+  for (const file of changed) files.add(file);
+  const selected = selectTests(changed, await readImportEdges(root, files));
+  if (selected.length === 0) {
+    const payload = { ok: true, command: 'gate', root, selected, code: 0 };
+    if (isJson(flags)) {
+      emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+      return EXIT.OK;
+    }
+    emit('selected  0', { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  return runSelected(root, flags, selected);
+}
+
+async function runSelected(root, flags, selected) {
+  const cache = new Map();
+  const groups = new Map();
+  for (const file of selected) {
+    const pkg = await packageOf(root, file, cache);
+    const list = groups.get(pkg);
+    if (list) list.push(file);
+    else groups.set(pkg, [file]);
+  }
+  const runs = [];
+  let code = 0;
+  const text = [];
+  const rawParts = [];
+  for (const [pkg, files] of [...groups.entries()].sort((a, b) => cmp(a[0], b[0]))) {
+    const relative = files.map((file) => (pkg && file.startsWith(`${pkg}/`) ? file.slice(pkg.length + 1) : file));
+    const cwd = join(root, pkg);
+    const runner = await detectTestRunner(cwd, relative);
+    if (!runner) {
+      return fail(
+        `no runner for ${files.length} test${files.length === 1 ? '' : 's'} in ${pkg || 'this repository'}`,
+        EXIT.UNSUPPORTED,
+        'declare a package manifest the test runner can see',
+      );
+    }
+    const built = runner.buildExec(cwd);
+    text.push(`selected  ${files.length}`, ...files, '', runner.displayCmd);
+    // A parent `node --test` puts NODE_TEST_CONTEXT in the environment. Left
+    // there, the child reports to that parent and exits 0 whether or not it failed.
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+      if (key.startsWith('NODE_TEST')) delete env[key];
+    }
+    const result = await exec(built.cmd, built.args, { cwd, env, maxBuffer: 32 << 20 }).then(
+      (out) => ({ code: 0, stdout: out.stdout, stderr: out.stderr }),
+      (error) => ({
+        code: typeof error.code === 'number' ? error.code : 1,
+        stdout: error.stdout ?? '',
+        stderr: error.stderr ?? '',
+      }),
+    );
+    if (result.code !== 0) code = result.code;
+    const stdout = String(result.stdout ?? '');
+    const stderr = String(result.stderr ?? '');
+    const body = stderr ? `${stdout}\n${stderr}` : stdout;
+    rawParts.push(body);
+    const compact = compactOutput(body);
+    runs.push({ package: pkg, command: runner.displayCmd, code: result.code, stdout, stderr });
+    text.push(compact ?? body);
+  }
+  const raw = await writeRaw(root, rawParts.join('\n'));
+  if (raw) text.push('', `raw  ${raw}`);
+  const payload = { ok: code === 0, command: 'gate', root, selected, code, raw, runs };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return code === 0 ? EXIT.OK : EXIT.FAIL;
+  }
+  emit(text.filter((line) => line !== undefined).join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return code === 0 ? EXIT.OK : EXIT.FAIL;
+}
+
+async function writeRaw(root, body) {
+  try {
+    const dir = join(root, '.simt-dev', 'gate');
+    await mkdir(dir, { recursive: true });
+    const name = `gate-${Date.now()}.log`;
+    await writeFile(join(dir, name), body);
+    return `.simt-dev/gate/${name}`;
+  } catch {
+    return '';
+  }
+}
+
+async function tracked(root) {
+  try {
+    const { stdout } = await exec('git', ['ls-files'], { cwd: root, maxBuffer: 16 << 20 });
+    return { files: stdout.split('\n').filter(Boolean) };
+  } catch (error) {
+    return {
+      error: fail(
+        `could not read the change (${error.message})`,
+        EXIT.UNSUPPORTED,
+        'run this inside a git repository',
+      ),
+    };
+  }
+}
+
+async function changedFiles(root) {
+  try {
+    const { stdout } = await exec('git', ['diff', '--name-only', 'HEAD'], { cwd: root, maxBuffer: 8 << 20 });
+    const untracked = await exec('git', ['ls-files', '--others', '--exclude-standard'], { cwd: root, maxBuffer: 8 << 20 });
+    return { files: [...new Set([...stdout.split('\n'), ...untracked.stdout.split('\n')].filter(Boolean))].sort() };
+  } catch (error) {
+    return {
+      error: fail(
+        `could not read the diff (${error.message})`,
+        EXIT.UNSUPPORTED,
+        'run this inside a git repository that has a commit',
+      ),
+    };
+  }
+}
+
+function cmp(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}

package/src/commands/help.mjs

@@ -16,6 +16,12 @@ ${CLI} upgrade                move every consumer to this simt-dev SHA, as one s
                            (dry-run unless --yes; moves a pin only - it never
                            adopts or repairs a repo; never commits or pushes)
 
+${CLI} brief "<task>"         one packet for a task: the kind, the commands, the
+                           likely files, the tests and the decisions that govern
+                           them, inside --budget bytes (default 2048; 0 is
+                           unlimited). Says how many items it cut; --explain
+                           says why each was kept or dropped
+
 ${CLI} skills index           tier-0 catalog: every skill, one line each
 ${CLI} skills brief --task    tier-1 pre-assembled brief  <- the common case
 ${CLI} skills show <name>     tier-2 body (respects --max-bytes)
@@ -28,6 +34,9 @@ ${CLI} skills eval [corpus]   measure the resolver against a gold corpus
 ${CLI} skills install <name>  pin a skill into the repo as a local override
                            (dry-run unless --yes; a multi-variant skill needs
                            --variant or --from rather than a guess)
+${CLI} skills compile [<name>] compile a skill to Agent Skills standard, flag bodies
+                           over 5000 tokens with a split plan, and report per-skill
+                           trigger recall and precision from R02 transcripts
 
 ${CLI} rules list             the rule catalogue (--root marks what applies to a repo)
 ${CLI} rules show <id>        one rule body
@@ -39,7 +48,8 @@ ${CLI} hooks install [--yes]   install the shared dispatcher; report what it wou
 ${CLI} hooks status            what each git event routes to, and whether it is wired
 ${CLI} hooks run <event>       run one event's gates now, as git would
                            (pre-commit, pre-push, post-merge, ...)
-${CLI} agent-hook <event>      the entry point a harness calls before a tool call
+${CLI} agent-hook <event>      the entry point a harness calls: pre-tool-use decides,
+                            prompt-submit delivers the packet as prompt context
                            (reads one JSON payload on stdin and answers in that
                             harness's dialect; exit 2 blocks; needs --harness)
 ${CLI} agent-hooks install     write this repo's policies into the harnesses that
@@ -61,6 +71,46 @@ ${CLI} ci                     simt-dev's own .github files: create or refresh th
 ${CLI} compare                org-wide matrix across every sibling repo
                            (read-only; exits non-zero on defects, not on
                            repos that have not adopted yet)
+${CLI} index                   rebuild the local file index from git blob hashes
+${CLI} why [path]            what governs a file: a decision whose Affects line names
+                           it, a rule whose scope matches it, a skill, a gate
+                           or a lesson. With no path, the Affects tokens this
+                           tree cannot resolve (UNRESOLVED-AFFECTS)
+${CLI} tests [path]          the tests that exercise a file: an import, the conventional
+                           source beside the test, or a coverage record that
+                           names both (--cochange adds files that only share
+                           commits, and only those)
+${CLI} gate [path...]        the tests a change reaches, and only those
+                           (--changed reads the diff instead of the paths)
+${CLI} impact <file|symbol>  who a change reaches: importers, their tests,
+                           what governs it, and a contract another repository references
+${CLI} map [--task "<text>"] [--level outline|names|signatures]
+                           the files this task is most likely to touch, within
+                           --budget bytes (default 2048; 0 is unlimited). outline
+                           is paths, names adds exports, signatures adds the line.
+                           --recall reports gold-file recall@10 on mined tasks
+${CLI} evidence                the runs recorded against the tree on disk
+${CLI} evidence check <file>   a commit message that claims a run this tree does not
+                           have: a warning, or a block when gates.evidence is "block"
+${CLI} lessons list            deterministic lesson candidates in .simt-dev/lessons.jsonl
+                           and promoted lessons in docs/lessons/*.md
+${CLI} lessons review [<id>]   promote a lesson candidate to docs/lessons/NNNN-<slug>.md
+                           (dry-run unless --yes; writes Appendix A frontmatter)
+${CLI} decide [<title>]        scaffold an ADR with the next free number, a Status: line,
+                           a rulings skeleton, and structured simt-affects +
+                           simt-supersedes frontmatter (dry-run unless --yes;
+                           --check lints ADRs for prose-only partial supersessions)
+${CLI} local doctor            probe configured local model endpoints (chat and embed)
+                           (reads local in ${MANIFEST_FILE}; opens no socket when
+                           unset; refuses non-loopback URLs without --allow-remote)
+${CLI} shared plan            what a workspace's repeated rules cost to carry
+                           once: the shared set, its bytes, and every path that would be written
+                           (read-only; touches nothing, not even your home directory)
+${CLI} shared install [--yes] carry those rules once per reader, at user level,
+                           and declare the delta in each repo's manifest (dry-run unless
+                           --yes; copies land in files the vendors' own docs name, and a reader
+                           with no such file gets the block printed to paste; ${CLI} doctor
+                           reports a copy that is missing or stale)
 ${CLI} tokens [--repos]       what a reader loads at session start, in bytes
                            (read-only; exits 0 whatever it finds, because a
                            measurement is not a verdict; --repos measures every
@@ -88,6 +138,9 @@ ${CLI} bench ablate [--yes]    leave-one-out ablation across core, profile and p
 ${CLI} bench probes [--yes]    12 synthetic rule-compliance probes with deterministic graders
                             (dry-run unless --yes; grades git state, transcript and ledger,
                             and reports compliance per arm)
+${CLI} bench variants [--yes]  evaluate simt-variants rule slots on the canary suite and lock
+                            winning variants in simt-dev.lock.json (dry-run unless --yes;
+                            re-opens when model or harness changes)
 ${CLI} mcp                    the read-only surface as MCP tools over stdio
                            (--list prints it without reading stdin; init, sync,
                            upgrade and the installers stay CLI-only by design)`;
@@ -95,7 +148,8 @@ ${CLI} mcp                    the read-only surface as MCP tools over stdio
 const FLAGS = `--json                 structured output (compact; one document, one line)
 --pretty                indent --json for a human
 --max-bytes <n>         hard ceiling on emitted bytes (0 = unlimited, default 0)
---budget <n>            context budget for skills brief (default 20480)
+--budget <n>            context budget for a brief (default 2048)
+                        (skills brief keeps its own default of 20480)
 --plan                  emit a fetch plan instead of inlining skill bodies
 --skill <name>          force a skill into the brief (repeatable)
 --task "<text>"         the task text used for capability resolution
@@ -110,8 +164,11 @@ const FLAGS = `--json                 structured output (compact; one document,
 --dry-run               report what would change, change nothing
 --yes                   assume yes; required in automation, never prompts
 --check                 report drift and write nothing (sync, ci)
+--frozen                check: the lock must match this projection; an output
+                        change no input change explains fails the gate
 --explain               sync: name each line dropped as already inferable, with
-                        the fact behind it
+                        the fact behind it; brief: name every item and why it
+                        was kept or cut, with its section's value
 --all                   ignore a cap: every ruling of a record, or the skills budget
 --variant <id>          which body of a multi-variant skill to use
 --from <repo/path>      install from a declared source by name
@@ -145,6 +202,11 @@ const FLAGS = `--json                 structured output (compact; one document,
 --compare <a> <b>       bench report: compare two arms with deltas and p-values
 --test <cmd>            plan done: the test command that closes the row
 --state <name>          plan done: target state (default: Complete)
+--level <name>          map: detail level (outline, names, signatures)
+--supersedes <spec>     decide: superseded ADR or ruling (ADR-NNN or ADR-NNN:<ruling>[:<kind>]; repeatable)
+--allow-remote          local doctor: allow non-loopback model URLs (refused by default)
+--embed                 index / map / brief: compute or query optional local vector embeddings
+                        (off by default unless recall@10 gains at least 10 points)
 --help                  this text
 --version               the version, and the SHA it was built from`;
 

package/src/commands/hooks.mjs

@@ -19,7 +19,7 @@ import { promisify } from 'node:util';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { MANIFEST, readManifest } from '../projection/manifest.mjs';
-import { EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, fileFor, renderChainedShim, renderShim } from '../hooks/shim.mjs';
+import { EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderChainedShim, renderEvidenceShim, renderShim } from '../hooks/shim.mjs';
 import { GATE_KEY, gateCount, readHooksPath, readHooksState, wantsShim } from '../compare/hooksstate.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { knownGates } from '../hooks/resolve.mjs';
@@ -222,11 +222,29 @@ async function installHooks(root, flags) {
     (i) => i.present && i.ours && !wanted.includes(i.event) && !chained.some((c) => c.event === i.event),
   );
 
+  // The claim check is not one of EVENTS. Those shims do not forward git's
+  // arguments, and commit-msg's only argument is the message. It is installed
+  // when the repository sets gates.evidence, and removed when that setting goes,
+  // because a shim that stays after the setting left still replaces git's own hook.
+  const evidenceDeclared = manifest?.gates?.evidence === 'warn' || manifest?.gates?.evidence === 'block';
+  const evidenceFile = fileFor('commit-msg');
+  const evidenceExisting = await readIfExists(join(root, evidenceFile));
+  const evidenceSource = evidenceDeclared ? renderEvidenceShim({ npm, version }) : null;
+  const evidenceOurs = evidenceExisting !== null && evidenceExisting.includes(SHIM_MARKER);
+  if (!evidenceDeclared && evidenceOurs) obsolete.push({ event: 'commit-msg' });
+  // A foreign commit-msg would otherwise be chained onto the same path. The chain
+  // is written after this shim, so it would replace the claim check and the check
+  // would never run. The repository's hook stays on disk and the note says it stopped.
+  if (evidenceDeclared) {
+    const at = chained.findIndex((c) => c.event === 'commit-msg');
+    if (at !== -1) chained.splice(at, 1);
+  }
+
   // Nothing to write and nothing to take away is the only refusal. It sits after
   // `obsolete` because a repository whose last gate just left the manifest has
   // something to take away, and blocking that one left no way out except undoing
   // the change by hand - see the note on `obsolete`.
-  if (wanted.length === 0 && obsolete.length === 0) {
+  if (wanted.length === 0 && obsolete.length === 0 && !evidenceDeclared) {
     if (isJson(flags)) {
       emitJson({ ok: false, command: 'hooks install', root, nothingToEnforce: true, filesWritten: false });
       return EXIT.FAIL;
@@ -276,10 +294,20 @@ async function installHooks(root, flags) {
       // Named in the plan because the reader approving this write is about to lose a
       // file, and "REMOVED pre-push" does not say why - which is the difference between
       // agreeing with it and discovering later that a gate had been dropped by accident.
-      note: `no gate for ${h.event} in ${MANIFEST_FILE}; the shim enforced nothing`,
+      note:
+        h.event === 'commit-msg'
+          ? `gates.evidence is unset, so the claim check stopped`
+          : `no gate for ${h.event} in ${MANIFEST_FILE}; the shim enforced nothing`,
+    });
+  }
+  if (evidenceSource) {
+    plan.push({
+      file: evidenceFile,
+      action: evidenceExisting === evidenceSource ? 'unchanged' : evidenceExisting === null ? 'created' : 'updated',
+      note: 'commit-msg checks a verification claim against the ledger',
     });
   }
-  const routed = wanted.length > 0 || chained.length > 0;
+  const routed = wanted.length > 0 || chained.length > 0 || evidenceDeclared;
 
   // The routing this install leaves behind, which is not always `wants`. A repository
   // that removed its last gate has no shims to route to, and leaving `core.hooksPath`
@@ -362,6 +390,12 @@ async function installHooks(root, flags) {
   for (const h of obsolete) {
     await rm(join(root, fileFor(h.event)));
   }
+  // After the chain loop, so a chained commit-msg cannot replace the claim check.
+  if (evidenceSource) {
+    const path = join(root, evidenceFile);
+    await writeFile(path, evidenceSource);
+    await chmod(path, 0o755);
+  }
 
   // `core.hooksPath` tells git to read ONE directory for EVERY event, so leaving it
   // pointing at a directory of no shims stops the repository's own hooks - the ones in
@@ -385,6 +419,10 @@ async function installHooks(root, flags) {
       notes.push(
         `chained ${f.event}: ${fileFor(f.event)} runs ${f.path} (${f.bytes} bytes), so it keeps running`,
       );
+    } else if (f.event === 'commit-msg' && evidenceDeclared) {
+      notes.push(
+        `stopped running commit-msg at ${f.path} (${f.bytes} bytes); the claim check replaced it, and the file is still on disk, untouched`,
+      );
     } else if (leftRunning.some((c) => c.event === f.event)) {
       // A third case, and the one that was misreported: a hook this tool could not chain
       // because the shim would have had to run itself. Nothing overwrote it, so it still
@@ -403,7 +441,9 @@ async function installHooks(root, flags) {
   }
   for (const h of obsolete) {
     notes.push(
-      `removed ${fileFor(h.event)}: ${MANIFEST_FILE} declares no ${h.event} gate, so the shim enforced nothing and still replaced git's own hook`,
+      h.event === 'commit-msg'
+        ? `removed ${fileFor(h.event)}: ${MANIFEST_FILE} no longer sets gates.evidence, so the claim check stopped replacing git's own commit-msg`
+        : `removed ${fileFor(h.event)}: ${MANIFEST_FILE} declares no ${h.event} gate, so the shim enforced nothing and still replaced git's own hook`,
     );
   }
   if (leaves === null && current !== null) {

package/src/commands/impact.mjs

@@ -0,0 +1,205 @@
+// `simt impact` reports who a file or an export reaches (R23, ADR-096).
+//
+// Importers, the tests that cover them, the decisions and rules that govern
+// the file, the CODEOWNERS line, and — when a workspace is configured —
+// another repository that references a contract this change touches.
+
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { discover } from '../compare/discover.mjs';
+import { extract } from '../index/extract.mjs';
+import { importEdges, readEntries } from '../index/gate.mjs';
+import {
+  contractReferences,
+  dependents,
+  filesExporting,
+  isContractPath,
+  ownersOf,
+  relatedContracts,
+} from '../index/impact.mjs';
+import { decisionHits, scopeHits, sortHits, sourceRoots } from '../index/govern.mjs';
+import { decisionRecords, ruleScopes } from './why.mjs';
+import { resolveWorkspace } from '../workspace.mjs';
+
+const exec = promisify(execFile);
+const TEXT_EXT = new Set(['js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx', 'json', 'yaml', 'yml', 'md', 'toml', 'xml', 'py', 'go', 'kt', 'java', 'rs']);
+const READ_CAP = 256 * 1024;
+const FILE_CAP = 2000;
+
+export async function impactCommand(args, flags, commands = []) {
+  if (args.length > 1) return fail(`unknown impact argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} impact <file|symbol>`);
+  const target = args[0];
+  if (!target) return fail(`a file or a symbol is required`, EXIT.USAGE, `run: ${CLI} impact <file|symbol>`);
+  const root = flags.root ?? process.cwd();
+  const listed = await tracked(root);
+  if (listed.error) return listed.error;
+  const files = new Set(listed.files);
+  const entries = await readEntries(root, files);
+  const imports = importEdges(entries);
+  const symbols = entries.flatMap((entry) => (entry.lang ? extract(entry.path, entry.text, entry.lang).symbols : []));
+  const resolved = resolveTarget(target, files, symbols);
+  if (resolved.error) return resolved.error;
+  const reach = dependents(resolved.file, imports);
+  const governs = await governance(root, resolved.file, files, commands);
+  const owners = await readOwners(root, resolved.file);
+  const contracts = await contractsFor(root, listed.files, resolved, reach.importers);
+  const consumers = await consumersFor(root, flags, basename(root), contracts);
+  const truncated = reach.truncated || consumers.truncated;
+  const payload = {
+    ok: true,
+    command: 'impact',
+    root,
+    file: resolved.file,
+    symbol: resolved.symbol,
+    importers: reach.importers,
+    tests: reach.tests,
+    governs,
+    owners,
+    consumers: consumers.references,
+    truncated,
+  };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  emit(render(payload), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+function resolveTarget(target, files, symbols) {
+  if (files.has(target)) return { file: target, symbol: '' };
+  const exported = filesExporting(target, symbols);
+  if (exported.length === 1) return { file: exported[0], symbol: target };
+  if (exported.length === 0) {
+    return { error: fail(`not a file or an export: ${target}`, EXIT.USAGE, `pass a path git tracks, or the name of one export`) };
+  }
+  return {
+    error: fail(
+      `${target} is exported by ${exported.join(', ')}`,
+      EXIT.USAGE,
+      `pass the path of the export you mean`,
+    ),
+  };
+}
+
+async function governance(root, file, files, commands) {
+  const records = await decisionRecords(root);
+  const rules = await ruleScopes(root);
+  const ctx = { files, commands: new Set(commands), roots: sourceRoots(files) };
+  const { hits } = decisionHits(records, file, ctx);
+  return sortHits([...hits, ...scopeHits(file, { rules })]);
+}
+
+async function readOwners(root, file) {
+  for (const path of ['.github/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS']) {
+    try {
+      return ownersOf(await readFile(join(root, path), 'utf8'), file);
+    } catch {
+      // The next location may hold the file. GitHub reads the first that exists.
+    }
+  }
+  return [];
+}
+
+async function contractsFor(root, files, resolved, importers) {
+  const contracts = [];
+  for (const path of files) {
+    if (!isContractPath(path) && !mightSniff(path)) continue;
+    let text = '';
+    try {
+      text = await readFile(join(root, path), 'utf8');
+    } catch {
+      continue;
+    }
+    if (!isContractPath(path) && !sniffs(text)) continue;
+    contracts.push({ path, text });
+  }
+  return relatedContracts(contracts, { file: resolved.file, symbol: resolved.symbol, importers });
+}
+
+async function consumersFor(root, flags, repoName, contracts) {
+  if (contracts.length === 0) return { references: [], truncated: false };
+  const workspace = await resolveWorkspace(flags);
+  if (!workspace.root) return { references: [], truncated: false };
+  const found = await discover(workspace.root);
+  if (found.shape !== 'workspace') return { references: [], truncated: false };
+  const here = resolve(root);
+  const files = [];
+  let truncated = false;
+  for (const repo of found.repos) {
+    if (resolve(repo) === here) continue;
+    const listed = await tracked(repo);
+    if (listed.error) continue;
+    const name = basename(repo);
+    let read = 0;
+    for (const path of listed.files) {
+      if (!textExt(path)) continue;
+      if (read >= FILE_CAP) {
+        truncated = true;
+        break;
+      }
+      read += 1;
+      try {
+        const text = await readFile(join(repo, path), 'utf8');
+        if (text.length > READ_CAP) continue;
+        files.push({ repo: name, path, text });
+      } catch {
+        // A file git lists and the worktree no longer has is not a consumer.
+      }
+    }
+  }
+  const refs = contractReferences(contracts, repoName, files);
+  return { references: refs.references, truncated: truncated || refs.truncated };
+}
+
+function render(payload) {
+  const lines = [`file      ${payload.file}`];
+  if (payload.symbol) lines.push(`symbol    ${payload.symbol}`);
+  for (const path of payload.importers) lines.push(`importer  ${path}`);
+  for (const path of payload.tests) lines.push(`test      ${path}`);
+  for (const hit of payload.governs) lines.push(`${hit.kind.padEnd(10)}${hit.id}  ${hit.detail}`);
+  for (const owner of payload.owners) lines.push(`owner     ${owner}`);
+  for (const consumer of payload.consumers) lines.push(`consumer  ${consumer.repo}/${consumer.path}  ${consumer.contract}`);
+  if (payload.truncated) lines.push('truncated  1');
+  return lines.join('\n');
+}
+
+function mightSniff(file) {
+  const base = file.slice(file.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return false;
+  const ext = base.slice(dot + 1).toLowerCase();
+  return ext === 'json' || ext === 'yaml' || ext === 'yml';
+}
+
+function sniffs(text) {
+  const head = text.slice(0, 500);
+  return head.includes('"openapi"') || head.includes('"$schema"');
+}
+
+function textExt(file) {
+  const base = file.slice(file.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return false;
+  return TEXT_EXT.has(base.slice(dot + 1).toLowerCase());
+}
+
+async function tracked(root) {
+  try {
+    const { stdout } = await exec('git', ['ls-files'], { cwd: root, maxBuffer: 16 << 20 });
+    return { files: stdout.split('\n').filter(Boolean) };
+  } catch (error) {
+    return {
+      error: fail(
+        `could not read the tree (${error.message})`,
+        EXIT.UNSUPPORTED,
+        'run this inside a git repository',
+      ),
+    };
+  }
+}