simt-dev 0.2.0 → 0.2.2

package/src/commands/sync.mjs

@@ -16,16 +16,18 @@
 //     three `.mdc` rules would let a reader believe a repo is fully current when
 //     only the file they happened to open is.
 
-import { mkdir, symlink, unlink, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { mkdir, readFile, stat, symlink, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { plan, checkTargets, checkTarget, provenanceDigest, loadRules, select, pointerTargets, pointerState } from '../projection/project.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { manifestDrift, readManifest, unrunnableGates } from '../projection/manifest.mjs';
+import { manifestDrift, readManifest, unrunnableGates, buildManifest, writeManifest, withGenerated, manifestText } from '../projection/manifest.mjs';
 import { readCapability } from '../hooks/capability.mjs';
 import { surfacesLine } from '../projection/surfaces.mjs';
 import { CLI } from '../name.mjs';
-import { MANIFEST_FILE } from '../name.mjs';
+import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+import { assertVersionPin, packageVersion } from '../package-version.mjs';
+import { resolvePacks } from '../packs.mjs';
 
 /** Findings `sync` reports and does not fail on.
  *
@@ -47,7 +49,7 @@ import { MANIFEST_FILE } from '../name.mjs';
  *  people learn to ignore. A *foreign* one — a real file or a real directory where the
  *  pointer belongs — is reported loudly with what is in the way, because that one is a
  *  decision somebody has to make. */
-export const SYNC_NON_BLOCKING = new Set(['pointer-unread', 'orphaned']);
+export const SYNC_NON_BLOCKING = new Set(['pointer-unread', 'orphaned', 'pack-unpinned', 'budget']);
 
 /**
  * Findings `check` reports and does not fail on.
@@ -67,7 +69,20 @@ export const SYNC_NON_BLOCKING = new Set(['pointer-unread', 'orphaned']);
  *
  *  `orphaned` stays non-blocking in both. Nothing can satisfy it, in either command.
  */
-export const CHECK_NON_BLOCKING = new Set(['orphaned']);
+// `pack-unpinned` is here and `pack-digest-mismatch` is not, which is the whole
+// judgement. An unpinned pack still renders its rules correctly; what is missing
+// is the record of which bytes were declared, and failing a gate over a field the
+// tool does not require would fail every repository that vendored a pack and
+// pinned it later. A pack whose bytes do not match its pin renders a region
+// nobody can account for, so that one blocks.
+//
+// `budget` is here for the opposite reason, and it is a ruling rather than a patch
+// (ADR-072). An over-budget finding says the projection is bigger than this repository
+// said it would be, and the remedy is a decision about which rules to narrow — not a
+// missing file. Nothing is cut: the projection is still in full mode, so a gate that
+// failed here would be failing a repository for exceeding a ceiling it set itself,
+// with no way to fix it except lowering the number it wrote down.
+export const CHECK_NON_BLOCKING = new Set(['orphaned', 'pack-unpinned', 'budget']);
 
 export async function syncCommand(positional, flags) {
   const root = flags.root ?? positional[0] ?? process.cwd();
@@ -76,6 +91,28 @@ export async function syncCommand(positional, flags) {
 
   const result = await plan(root, flags);
 
+  // Before the rule branch, and named for what it is. An unknown surface id is a
+  // misspelling in the manifest's `surfaces` list; reporting it as an unprojectable
+  // `.mdc` rule sent the reader to a `simt-substitutions` block that has nothing to do
+  // with the thing they typed. `check` reported the same problem correctly the whole
+  // time, so this was a writer disagreeing with the gate about the same manifest.
+  if (result.surfaceProblems.length > 0) {
+    if (isJson(flags)) {
+      emitJson({
+        ok: false,
+        command: 'sync',
+        root,
+        error: result.surfaceProblems[0],
+        problems: result.surfaceProblems,
+      });
+    }
+    for (const p of result.surfaceProblems) note(`PROBLEM ${p}`);
+    return fail(
+      `${result.surfaceProblems.length} surface(s) cannot be resolved (${result.surfaceProblems[0]})`,
+      EXIT.FAIL,
+      `fix the surface ids in the "surfaces" list of ${MANIFEST_FILE}, or remove the unknown one`,
+    );
+  }
 
   // A `.mdc` rule that cannot render is a defect in this build, not in the repo,
   // and projecting the rest would leave a family half-retired.
@@ -162,6 +199,40 @@ export async function syncCommand(positional, flags) {
   const changed = result.targets.filter((t) => t.action !== 'unchanged');
   const pointersAdded = pointerPlan.map((p) => p.path);
 
+  // The manifest is the second file this tool writes into a repository it does not own,
+  // and for two releases it was the only generated file with no path back to correct:
+  // `check` refused on a stale generated field and named `init --yes`, while `sync` -
+  // the command whose whole job is regenerating what this tool owns - reported
+  // "already current; nothing written". Both statements were true of the same
+  // repository, and all fourteen adopted repositories were in that state at once.
+  //
+  // One reason and one place, so `check`'s remedy and this plan cannot drift: the
+  // field set is `GENERATED_KEYS`, and the values come from the same `buildManifest`
+  // call `manifestDrift` compares against. A repair built from a second copy of
+  // either would pass its own test and leave the gate still red.
+  //
+  // `reformatted` is repaired too, and only when the repository has said the file is
+  // not prose: `simt.json` listed in `.prettierignore` is the repo stating that no
+  // formatter will take these bytes back.
+  //
+  // Without that condition there are two wrong answers. Repairing unconditionally
+  // means every `format` run rewrites a file the commit just wrote - a permanently
+  // dirty working tree. Never repairing means `init --yes` is the only way to put the
+  // bytes back, and `init` re-runs adoption: it tags, it switches branch, it asks every
+  // question again, to fix one file's formatting (ADR-050). The first repo routed in
+  // the estate roll-out hit this on its first commit, so both answers were live.
+  const manifestPlan = await planManifestRepair(root, result.stack, result.targets[0].sha);
+  if (manifestPlan) {
+    targets.push({
+      file: manifestPlan.file,
+      surface: 'manifest',
+      action: 'updated',
+      bytes: Buffer.byteLength(manifestPlan.text),
+      previousBytes: manifestPlan.previousBytes,
+    });
+  }
+  const manifestChanged = manifestPlan !== null;
+
   // Writes happen BEFORE output in every mode. An earlier build emitted `--json`
   // first and returned, so `upgrade --yes --json` reported a plan and changed
   // nothing — the exact combination automation reaches for.
@@ -178,6 +249,13 @@ export async function syncCommand(positional, flags) {
   // A comment that enumerates which commands follow a rule is a claim about code
   // this file does not own, and it was one commit out of date before anyone ran it.
   if (mode.apply) {
+    // The manifest first, with the rest: a gate that refuses on a stale stamp should
+    // not be able to read a half-finished write, and the manifest is the file every
+    // other write in this run is described by.
+    if (manifestPlan) {
+      await writeManifest(root, manifestPlan.manifest);
+      note(`wrote    ${manifestPlan.file} (generated field(s) ${manifestPlan.stale.join(', ')})`);
+    }
     for (const t of changed) {
       // Three of the four rule surfaces live in directories that do not exist yet in a
       // repository that has only ever been written to by hand. `init` grew its own
@@ -210,7 +288,7 @@ export async function syncCommand(positional, flags) {
         // `ok` follows the exit code, which now reports drift for a previewing run
         // too. Leaving it `true` here would break the invariant ADR-035 sets for
         // every command, and the contract table asserts it for this one.
-        ok: changed.length === 0 && pointersAdded.length === 0 ? true : mode.apply,
+        ok: changed.length === 0 && pointersAdded.length === 0 && !manifestChanged ? true : mode.apply,
         command: checkOnly ? 'sync --check' : 'sync',
         root,
         stack: result.stack,
@@ -220,7 +298,7 @@ export async function syncCommand(positional, flags) {
         sha: result.targets[0].sha,
         targets,
         pointers: pointersAdded,
-        written: mode.apply ? changed.length + pointersAdded.length : 0,
+        written: mode.apply ? changed.length + pointersAdded.length + (manifestChanged ? 1 : 0) : 0,
         dryRun: !mode.apply,
       },
       {},
@@ -233,12 +311,15 @@ export async function syncCommand(positional, flags) {
       surfacesLine({ ids: result.surfaces, source: result.surfaceSource }, 10),
       `sha       ${result.targets[0].sha}`,
       '',
-      ...result.targets.map(
+      // `targets`, not `result.targets`: the plan is the thing being reported, and a
+      // line the JSON payload carries but the text one drops is the reader of the
+      // terminal output finding out from the exit code what they were already told.
+      ...targets.map(
         (t) => `${t.file}  ${t.action}  ${t.previousBytes} -> ${t.bytes} bytes`,
       ),
       ...pointerPlan.map((p) => `${p.file}  added  pointer -> ${p.to}`),
     ];
-    if (changed.length === 0 && pointerPlan.length === 0) lines.push('already current; nothing written');
+    if (changed.length === 0 && pointerPlan.length === 0 && !manifestChanged) lines.push('already current; nothing written');
     else if (checkOnly) lines.push('would write; rerun without --check');
     else if (!mode.apply) {
       // The preview names the command that writes it. A preview that reports what
@@ -247,26 +328,128 @@ export async function syncCommand(positional, flags) {
       lines.push(
         flags.dryRun === true
           ? 'dry-run; nothing written'
-          : `would write ${changed.length + pointersAdded.length} file(s); apply with: ${CLI} sync --yes`,
+          : `would write ${changed.length + pointersAdded.length + (manifestChanged ? 1 : 0)} file(s); apply with: ${CLI} sync --yes`,
       );
     }
     emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
   }
 
-  if (checkOnly) return changed.length === 0 && pointerPlan.length === 0 ? EXIT.OK : EXIT.FAIL;
+  const idle = changed.length === 0 && pointerPlan.length === 0 && !manifestChanged;
+  if (checkOnly) return idle ? EXIT.OK : EXIT.FAIL;
   // A preview that found work is not a success: `simt-dev sync --yes` with no flags is a
   // check that also prints the plan, and a check that exits 0 while reporting drift
   // is the one-question-two-answers shape ADR-035 rules out. This is what lets a
   // caller run `sync` in place of `sync --check` and get the same verdict.
   if (!mode.apply) {
     if (flags.dryRun === true) note('dry-run  no files written');
-    return changed.length === 0 && pointerPlan.length === 0 ? EXIT.OK : EXIT.FAIL;
+    return idle ? EXIT.OK : EXIT.FAIL;
   }
   return EXIT.OK;
 }
 
-export async function checkCommand(positional, flags) {
-  const root = flags.root ?? positional[0] ?? process.cwd();
+/**
+ * The manifest repair `sync` would make, or null when there is nothing to repair.
+ *
+ * Returns the parsed manifest to hand to `writeManifest` as well as the bytes, so the
+ * writer keeps owning the legacy-name move and the preview keeps showing the real
+ * count. `sha` is the same digest the regions were rendered from: the stamp and the
+ * text it describes have to agree, or the next `check` finds a region carrying a pin
+ * the manifest does not claim.
+ *
+ * @returns {Promise<{file: string, manifest: object, text: string,
+ *                    stale: string[], previousBytes: number}|null>}
+ */
+async function planManifestRepair(root, stack, sha) {
+  const drift = await manifestDrift(root, stack, sha);
+  if (drift === null) return null;
+  // A `reformatted` manifest is repaired only once the repository has declared that no
+  // formatter will take these bytes back. The declaration is read rather than assumed
+  // because a repo that runs no formatter should not need a `.prettierignore` to repair
+  // a manifest some other tool rewrote, and one that does must be believed only when it
+  // has said so.
+  if (drift.status === 'reformatted' && !(await formatterIgnoresManifest(root))) return null;
+
+  const { manifest } = await readManifest(root);
+  if (manifest === null) return null;
+  const expected = buildManifest({ root, stack, sha, version: packageVersion(), existing: manifest });
+  const patched = withGenerated(manifest, expected);
+  const stale = Object.keys(expected).filter(
+    (key) => JSON.stringify(manifest[key]) !== JSON.stringify(patched[key]),
+  );
+  return {
+    file: MANIFEST_FILE,
+    manifest: patched,
+    text: manifestText(patched),
+    stale,
+    previousBytes: Buffer.byteLength(manifestText(manifest)),
+  };
+}
+
+/**
+ * Whether this repository's `.prettierignore` excludes the manifest.
+ *
+ * Lines, `#` comments and blanks only. A glob is not evaluated: the question this
+ * answers is "did somebody deliberately write this file's name down", and an exact
+ * match is the only reading of that which cannot be wrong. A repository that ignores
+ * `*.json` has said something broader, and the honest answer there is that this tool
+ * cannot tell - so it declines to repair, which is the state that was already correct.
+ */
+async function formatterIgnoresManifest(root) {
+  // ENOENT only. A catch that answers "no" to every error is a catch that turns a
+  // typo in this function into a repository silently keeping its pre-commit gate's
+  // formatting — which is how the first version of it failed: `join` was not imported,
+  // the ReferenceError was swallowed, and every repository read as having declared
+  // nothing. Absence is absence; anything else is a fault worth seeing.
+  let text;
+  try {
+    text = await readFile(join(root, '.prettierignore'), 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return false;
+  }
+  return text
+    .split('\n')
+    .map((line) => line.trim())
+    .some((line) => line !== '' && !line.startsWith('#') && (line === MANIFEST_FILE || line === MANIFEST_LEGACY));
+}
+
+/**
+ * `gates.cwd` entries that do not resolve to a directory inside the repository.
+ *
+ * Reported here, not only where the gate runs: the dispatcher fails closed on the same
+ * condition, so a reader finds out on their next commit — after writing a commit, which
+ * is the wrong order. The finding names the gate and the path, and says which of the two
+ * things is wrong, because "no such directory" and "outside the repository" are repaired
+ * by different edits.
+ *
+ * @returns {Promise<{file: string, status: string, gate: string, detail: string, remedy: string}[]>}
+ */
+async function gateCwdFindings(root, manifest) {
+  const cwds = manifest?.gates?.cwd;
+  if (!cwds || typeof cwds !== 'object' || Array.isArray(cwds)) return [];
+  const declared = [...(manifest?.gates?.preCommit ?? []), ...(manifest?.gates?.prePush ?? [])];
+  const findings = [];
+  for (const name of Object.keys(cwds).sort()) {
+    if (!declared.includes(name)) continue;
+    const dir = String(cwds[name]);
+    const resolved = resolve(root, dir);
+    const inside = resolved === root || resolved.startsWith(`${root}${sep}`);
+    const isDir = inside && ((await stat(resolved).catch(() => null))?.isDirectory() ?? false);
+    if (isDir) continue;
+    findings.push({
+      file: MANIFEST_FILE,
+      status: inside ? 'gate-cwd-missing' : 'gate-cwd-outside',
+      gate: name,
+      detail: inside
+        ? `gates.cwd["${name}"] is ${dir}, which is not a directory in this repository`
+        : `gates.cwd["${name}"] is ${dir}, which resolves outside the repository`,
+      remedy: `point gates.cwd["${name}"] at a directory in this repository, or remove it to run the gate at the root`,
+    });
+  }
+  return findings;
+}
+
+export async function checkCommand(positional, flags) {  const root = flags.root ?? positional[0] ?? process.cwd();
   const findings = await checkTargets(root, flags);
   const rules = await loadRules(root);
 
@@ -288,7 +471,22 @@ export async function checkCommand(positional, flags) {
   // before anyone installs anything rather than after.
   const { manifest } = await readManifest(root);
   if (manifest) {
+    // The gate runs from whatever binary resolved it. For a repository without npm that
+    // is a global install, and the only thing that knows which version it should be is
+    // the pin the repo recorded at adoption. A stale binary would run a different gate
+    // than CI does, so the mismatch fails the gate rather than warning.
+    const mismatch = assertVersionPin(manifest);
+    if (mismatch) {
+      findings.push({ file: MANIFEST_FILE, status: 'version-mismatch', detail: mismatch, remedy: `run: ${CLI} upgrade --yes` });
+    }
     findings.push(...unrunnableGates(manifest, await readCapability(root)));
+    findings.push(...(await gateCwdFindings(root, manifest)));
+    // A pack the repository declares but cannot produce is reported here rather
+    // than when a rule happens to be missing, because that is the failure mode
+    // this guards: the region still renders, it renders SHORT, and `check` would
+    // pass. A reader whose rules were quietly halved is worse off than one whose
+    // gate is red, so this is a blocking finding, not a note.
+    findings.push(...(await resolvePacks(root)).findings);
     // A manifest a formatter has rewritten is not wrong, and not editable-away by
     // hand either: the next `init` puts simt-dev's own bytes back and the formatter
     // takes them away again. Reporting it here is what stops that being a surprise

package/src/commands/tokens.mjs

@@ -0,0 +1,138 @@
+// simt-dev tokens - what a reader loads, counted.
+//
+// Review 0002 S38 put the estate's always-on context at 90 KB per turn, 72% of it a
+// paragraph an earlier root had already loaded, and could only say so by reading seven
+// repositories by hand. This command is that reading, and it is the figure plan 0003's
+// later slices are measured against: the context budget (S38 P7), the kernel split
+// (R07) and the workspace dedupe (R11) all need a number that moves when the
+// projection moves, or they are opinions.
+//
+// Three decisions keep the figure honest:
+//
+//   1. It is a READ. No write, no git object, no lock - the same ruling `compare`
+//      follows. An agent running this to orient itself must not be able to change what
+//      the next run will measure.
+//   2. It exits 0. A measurement is not a verdict: a repository over budget is a fact
+//      about the repository, and a command that went red for it would train people to
+//      ignore the number it exists to print. The only failure is being pointed at a
+//      directory that holds no repository to measure.
+//   3. It counts bytes and calls the tokens an approximation every time it prints one.
+//      See src/measure/context.mjs for what that costs and why.
+
+import { resolve } from 'node:path';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { discover } from '../compare/discover.mjs';
+import { targetRoot } from '../workspace.mjs';
+import {
+  ALWAYS_ON_BUDGET_BYTES,
+  BYTES_PER_TOKEN,
+  annotate,
+  measureRoot,
+  mcpTools,
+  totals,
+} from '../measure/context.mjs';
+
+/** `1234567`, never `1,234,567`. `toLocaleString` output depends on the locale, and
+ *  this command exists so two machines produce two numbers a pull request can diff. */
+function plain(n) {
+  return String(n);
+}
+
+function files(n) {
+  return n === 1 ? '1 file' : `${plain(n)} files`;
+}
+
+export async function tokensCommand(positional, flags) {
+  // `targetRoot` owns the precedence, so `tokens`, `compare` and `upgrade` cannot
+  // disagree about which directory was named (ADR-014).
+  const target = await targetRoot(flags, positional);
+  const root = resolve(target.root);
+
+  const found = await discover(root);
+  if (flags.repos) {
+    if (found.error) {
+      return fail(`${root}: ${found.error}`, EXIT.CONFIG, 'pass --root <path>');
+    }
+    if (found.repos.length === 0) {
+      return fail(
+        `${root} contains no git repositories`,
+        EXIT.CONFIG,
+        `point --root at the directory holding the repositories, or at one repository without --repos`,
+      );
+    }
+    // `discover` sorts, and the order decides which root owns a shared paragraph. A
+    // second sort here would move duplicate bytes between roots and make the workspace
+    // figure irreproducible.
+  } else if (found.shape === 'workspace') {
+    return fail(
+      `${root} holds repositories rather than being one`,
+      EXIT.CONFIG,
+      `measure one with: ${CLI} tokens --root <path>, or every repository under it with: ${CLI} tokens --repos --root ${root}`,
+    );
+  }
+  const roots = flags.repos ? found.repos : [root];
+
+  const rows = [];
+  for (const path of roots) rows.push(await measureRoot(path));
+  annotate(rows);
+
+  const summary = totals(rows);
+  const mcp = mcpTools();
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'tokens',
+      root,
+      mode: flags.repos ? 'repositories' : 'repository',
+      source: target.source,
+      budget: { bytes: ALWAYS_ON_BUDGET_BYTES, bytesPerToken: BYTES_PER_TOKEN },
+      mcp,
+      roots: rows.map(({ documents, ...row }) => row),
+      totals: summary,
+    });
+    return EXIT.OK;
+  }
+
+  const lines = [];
+  if (flags.repos) {
+    lines.push(`tokens   ${root}  ${plain(summary.roots)} repositories  (${target.source})`);
+    for (const row of rows) {
+      const budget = row.budget.over ? `  over budget by ${plain(row.budget.overBy)} B` : '';
+      lines.push(
+        `${row.name}  generated ${plain(row.generatedBytes)} B  duplicate ${plain(row.redundancy.duplicateBytes)} B  unique ${plain(row.redundancy.uniqueBytes)} B${budget}`,
+      );
+      for (const finding of row.findings) lines.push(`note     ${row.name}: ${finding}`);
+    }
+    const share =
+      summary.generatedBytes === 0 ? 0 : Math.round((summary.duplicateBytes / summary.generatedBytes) * 100);
+    lines.push(
+      `totals   generated ${plain(summary.generatedBytes)} B  duplicate ${plain(summary.duplicateBytes)} B (${plain(share)}% of generated)  unique ${plain(summary.uniqueBytes)} B  repeat ${plain(summary.repeatBytes)} B  ~${plain(summary.tokens)} tokens`,
+    );
+  } else {
+    const row = rows[0];
+    lines.push(`tokens   ${row.path}`);
+    lines.push(`state    ${row.adoption}  surfaces ${row.surfaces.length === 0 ? '(AGENTS.md only)' : row.surfaces.join(', ')}`);
+    for (const channel of row.channels) {
+      lines.push(
+        `${channel.channel.padEnd(9)}${files(channel.files)}  ${plain(channel.generatedBytes)} B generated  ${plain(channel.readerBytes)} B read`,
+      );
+    }
+    const verdict = row.budget.over ? `over by ${plain(row.budget.overBy)} B` : 'within budget';
+    lines.push(
+      `always-on ${plain(row.generatedBytes)} B generated  ~${plain(row.generatedTokens)} tokens  budget ${plain(row.budget.bytes)} B  ${verdict}`,
+    );
+    lines.push(
+      `redundant ${plain(row.redundancy.duplicateBytes)} B repeats an earlier repository  ${plain(row.redundancy.repeatBytes)} B repeats an earlier document here  ${plain(row.redundancy.uniqueBytes)} B unique of ${plain(row.redundancy.blockBytes)} B counted in blocks`,
+    );
+    for (const finding of row.findings) lines.push(`note     ${finding}`);
+  }
+  lines.push(
+    `mcp      tools/list ${plain(mcp.bytes)} B of ${plain(mcp.tools)} tools  (the same for every repository, so it is not in any total)`,
+  );
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/compare/hooksstate.mjs

@@ -11,8 +11,9 @@ import { readFile, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { promisify } from 'node:util';
 
-import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, fileFor, renderShim } from '../hooks/shim.mjs';
+import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderShim } from '../hooks/shim.mjs';
 import { foreignHooks, resolveHooksDir } from '../hooks/where.mjs';
+import { packageVersion, hasNpm } from '../package-version.mjs';
 
 const exec = promisify(execFile);
 
@@ -30,7 +31,7 @@ const exec = promisify(execFile);
  * @param {string} path
  * @returns {Promise<{event:string, target:string}|null>}
  */
-export async function readChainedShim(path) {
+async function readChainedShim(path) {
   let content;
   try {
     content = await readFile(path, 'utf8');
@@ -49,6 +50,54 @@ async function isChainedShim(path) {
   return (await readChainedShim(path)) !== null;
 }
 
+/**
+ * Whether this file is a dispatcher shim this tool wrote, whatever version wrote it.
+ *
+ * Content, on the same argument as {@link readChainedShim}: the name is what git calls
+ * it and the path is where this tool happens to put its own, and neither of those is a
+ * statement about authorship. The banner is.
+ */
+async function isOurShim(path) {
+  try {
+    return (await readFile(path, 'utf8')).includes(SHIM_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/** Git event -> manifest gate list. Exported because the report prints from it too. */
+export const GATE_KEY = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
+
+/** Gates this manifest declares for an event. */
+export function gateCount(manifest, event) {
+  return (manifest?.gates?.[GATE_KEY[event]] ?? []).length;
+}
+
+/**
+ * Whether a missing shim for this event is a defect.
+ *
+ * A repo that declares no gate for an event has no reason to want a shim for it, so
+ * its absence is the correct end state. A repo with NO manifest is different: we do
+ * not know what it wants, so we cannot rule the shim out - absence of knowledge is
+ * not a decision.
+ *
+ * It lives here, not in the command that first needed it, because there are two
+ * callers and they were answering differently. `hooks install` asked this question;
+ * `compare` did not ask it at all and defaulted to "yes, a shim is wanted for every
+ * event", so a repository declaring only `prePush` gates was reported as
+ * `hooksComplete: false` for the pre-commit shim it correctly has no reason to write.
+ * Four estate repositories were in that state and no amount of running `hooks install`
+ * could clear it.
+ *
+ * @param {object|null} manifest the repository's manifest
+ * @param {boolean} exists whether a manifest was found at all
+ * @param {string} event
+ */
+export function wantsShim(manifest, exists, event) {
+  if (!exists) return true;
+  return gateCount(manifest, event) > 0;
+}
+
 /** `core.hooksPath`, or null when unset or the repo is not a git repo. */
 export async function readHooksPath(root) {
   try {
@@ -64,27 +113,40 @@ export async function readHooksPath(root) {
  * One shim's state. A shim that differs from what this simt-dev generates is
  * `stale`: the gates it enforces are from another version, so it cannot be
  * assumed to know about a gate added since.
+ *
+ * `ours` is reported rather than inferred from `stale`, because the two answer different
+ * questions and only one is the one `hooks install` has to ask. A shim this tool wrote can be
+ * current (identical bytes), or from an earlier release (stale), or a shell it left behind for
+ * an event with no gates - also stale, and the one thing here that is obsolete rather than out
+ * of date. A file a person wrote by hand is stale too, and it is the one thing install must
+ * never delete. Authorship is only on the file, which is the same argument {@link isOurShim}
+ * already records for the same reason.
+ *
+ * `root` is the repository the shim belongs to: the remedy a shim prints depends on
+ * the repo's kind (a devDependency where package.json exists, a pinned global install
+ * where there is none), so the comparison must render the shim the way THIS repo got it,
+ * or a non-npm repository would read as stale the moment this tool ships.
  */
-export async function describeShim(path) {
+async function describeShim(path, root) {
   let content;
   try {
     content = await readFile(path, 'utf8');
   } catch {
-    return { present: false, executable: false, stale: false };
+    return { present: false, executable: false, stale: false, ours: false };
   }
   let info;
   try {
     info = await stat(path);
   } catch {
-    return { present: false, executable: false, stale: false };
+    return { present: false, executable: false, stale: false, ours: false };
   }
   let stale = true;
   try {
-    stale = content !== renderShim(basename(path));
+    stale = content !== renderShim(basename(path), { npm: await hasNpm(root), version: packageVersion() });
   } catch {
     stale = true;
   }
-  return { present: true, executable: (info.mode & 0o111) !== 0, stale };
+  return { present: true, executable: (info.mode & 0o111) !== 0, stale, ours: content.includes(SHIM_MARKER) };
 }
 
 /**
@@ -100,7 +162,7 @@ export async function readHooksState(root, options = {}) {
   const current = await readHooksPath(root);
   const installed = [];
   for (const event of EVENTS) {
-    installed.push({ event, ...(await describeShim(join(root, fileFor(event)))) });
+    installed.push({ event, ...(await describeShim(join(root, fileFor(event)), root)) });
   }
 
   // What git runs right now, which is not the same question as "is a simt-dev
@@ -112,8 +174,10 @@ export async function readHooksState(root, options = {}) {
   // hand-written one. Only the bytes can.
   const foreign = [];
   const chained = [];
+  const staleOurs = [];
   for (const hook of live) {
-    if (EVENTS.includes(hook.event) && !(await describeShim(hook.path)).stale) continue;
+    const shim = EVENTS.includes(hook.event) ? await describeShim(hook.path, root) : { stale: true };
+    if (!shim.stale) continue;
     // A chained shim is ours too, and its name says nothing: `post-commit` is what the
     // repository called its own hook, and the shim exists under that name precisely so
     // git finds it. Reading it as foreign would make every re-install refuse with "this
@@ -124,6 +188,25 @@ export async function readHooksState(root, options = {}) {
       chained.push({ ...chain, path: hook.path });
       continue;
     }
+    // And so is a dispatcher shim from an EARLIER version of this tool, which is the
+    // ordinary state of every repository adopted before the last release.
+    //
+    // Reading it as foreign was wrong twice over. `compare` reported "not a simt-dev
+    // shim" about a file simt-dev wrote, and `hooks install --yes` then printed "stopped
+    // running <event> ... declare it in simt.json gates.commands to have the dispatcher
+    // run it" — advice that, followed, makes the dispatcher run the dispatcher. The file
+    // was also described as "still on disk, untouched" in the same breath as the install
+    // overwrote it. Both statements were false and both pointed a reader at a worse
+    // configuration; nine estate repositories were in exactly this state.
+    //
+    // What it actually needs is refreshing, which `installed` already reports as `stale`
+    // and `compare` already reports as "differs from this simt-dev; reinstall". Keeping
+    // it out of `foreign` also stops the takeover guard asking for consent the
+    // repository has already given: it routed through this tool once.
+    if (await isOurShim(hook.path)) {
+      staleOurs.push(hook);
+      continue;
+    }
     foreign.push(hook);
   }
 
@@ -146,6 +229,10 @@ export async function readHooksState(root, options = {}) {
     complete: current === HOOKS_DIR && problems.length === 0,
     installed,
     foreign,
+    // Dispatcher shims this tool wrote in an earlier version. Reported so a reader can
+    // tell an out-of-date shim - which `hooks install` refreshes - from one this tool
+    // has never heard of, which only a human may decide to replace.
+    staleOurs,
     // The chained shims this repo is already running, read back off disk. `install`
     // re-renders them from here so a second run keeps maintaining them rather than
     // quietly forgetting them; without this field the set of things install maintains