simt-dev 0.2.2 → 0.3.1

package/src/projection/shared.mjs

@@ -0,0 +1,428 @@
+// The shared half of a workspace's rules, and the user-level files that carry it.
+//
+// Review 0002 S38 measured seven repositories carrying 90 KB of always-on rules of
+// which 64 KB — 72% — was a paragraph an earlier root had already loaded. The fix is not
+// a smaller region; it is carrying the repeated half once, in a file every reader in the
+// estate loads before they open a repository.
+//
+// FOUR DECISIONS, each with a cost. All four are settled in ADR-084; they are written out
+// here because the code is where the next change will look.
+//
+//   1. THE SHARED UNIT IS A RULE, NOT A PARAGRAPH. `simt rules show <id>` prints one
+//      rule; a rule split across a user file and a region cannot be read by one command,
+//      and the review's own accept criterion says every rule stays reachable. The meter's
+//      `paragraphs()` is the unit that REPORTS redundancy, not the unit that stores it.
+//
+//   2. A RULE IS SHAREABLE ONLY IF EVERY ROOT IN THE WORKSPACE SHIPS THE SAME BYTES.
+//      Union would put a python rule in front of a java repository; the intersection is
+//      the only set that cannot. Bytes, not ids: a rule two roots render differently —
+//      inferability having dropped a line in one of them — is not shareable, and comparing
+//      the rendered frame is how that is found rather than assumed.
+//
+//   3. THE IDS LIVE IN EACH REPOSITORY'S MANIFEST, not in the shared file and not in the
+//      workspace config. A repository's region must be a pure function of that
+//      repository, or `check` in CI — where nobody has installed anything — disagrees
+//      with the reader's own session. That also means `sync` never reads `$HOME`, which
+//      `harness.mjs`'s comment forbids for anything a projection depends on.
+//
+//   4. THE TARGET LIST IS THE LOADER TABLE'S, not a second list of paths. Plan 0003 R11
+//      named `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md` and `~/.gemini/GEMINI.md`; the
+//      table (`src/projection/loaders.mjs`, every row citing a vendor document) records
+//      `~/.claude/rules/*.md` and `~/.gemini/config/rules/*.md` instead, and records no
+//      user-level file at all for Cursor or Copilot. A path this tool writes to and a
+//      reader's harness never loads buys nothing and costs a directory.
+
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { CLI } from '../name.mjs';
+import { caps, loader } from './loaders.mjs';
+import { composeShared, diff as diffRegion, inject, parse } from './markers.mjs';
+import { byPriorityThenId, desiredRegion, provenanceDigest } from './rules.mjs';
+import { discover } from '../compare/discover.mjs';
+
+/**
+ * The filename this tool claims inside a reader's flat user rules directory.
+ *
+ * `simt` rather than `simt-dev`, for the reason in `src/name.mjs`: a command name appears
+ * in text this tool writes and nowhere else, while the on-disk names stay locked. Naming
+ * the file for the command that wrote it is what lets a reader who finds it in their home
+ * directory tell which tool put it there.
+ */
+const SHARED_BASENAME = 'simt.md';
+
+/**
+ * A path from the loader table, under the reader's home directory.
+ *
+ * The table spells these two ways — `~/.config/opencode/AGENTS.md` and the bare
+ * `.claude/rules` directory — so both are joined onto `homedir()` rather than one being
+ * special-cased. A relative path left alone would resolve against the process's working
+ * directory, which is a repository, and a user-level file written there is a file in
+ * nobody's home directory at all.
+ */
+function inHome(path) {
+  if (process.env.CODEX_HOME !== undefined && process.env.CODEX_HOME !== '' && path.startsWith('~/.codex/')) {
+    return join(process.env.CODEX_HOME, path.slice('~/.codex/'.length));
+  }
+  return path.startsWith('~/') ? join(homedir(), path.slice(2)) : join(homedir(), path);
+}
+
+/**
+ * Is this the file the reader's harness reads in preference to the ones below it?
+ *
+ * A fact about the reader's machine rather than about the table, which is why it is asked
+ * here and nowhere else: Codex reads `AGENTS.override.md` when it is non-empty and
+ * `AGENTS.md` otherwise, and writing an override where the reader has none would shadow
+ * the global file they do have — silently, and for every repository in the estate.
+ */
+async function nonEmptyFile(path) {
+  try {
+    const info = await stat(path);
+    return info.isFile() && info.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The smallest byte cap that applies to the file this tool would write.
+ *
+ * Token budgets are deliberately not compared against bytes: Antigravity's 20,000-token
+ * cap for global plus always-on rules is a real limit the table records, and 20,000
+ * compared against a byte count would be a number with no meaning.
+ */
+function fileCap(row) {
+  return (
+    caps(row)
+      .filter((c) => c.appliesTo === 'a single file' || c.appliesTo === 'the merged chain')
+      .sort((a, b) => a.bytes - b.bytes)[0] ?? null
+  );
+}
+
+/**
+ * Where a surface's rules can be carried once per reader, or `null` when they cannot be.
+ *
+ * Read from the loader table rather than written here, because that is the one place a
+ * path comes with the document that says a harness loads it. Two answers are deliberate:
+ *
+ *   - a surface with no `scope: 'user'` row (Cursor, Copilot) yields `null`. Those
+ *     harnesses keep user rules in their own settings, which is not a file this tool can
+ *     project, so `shared` prints the block for a reader to paste instead of writing
+ *     somewhere that would do nothing.
+ *   - the `pointer` surfaces (`claude-md`, `gemini-md`) have no loader row at all, so they
+ *     yield `null` too. The plan named `~/.claude/CLAUDE.md` and `~/.gemini/GEMINI.md`;
+ *     the table records no such user-level file for either harness, and a guessed path is
+ *     worse than a printed block — the file would be written, and never read.
+ *
+ * Where a harness records more than one global file, the one that is already there wins:
+ * which of them is read is a fact about the reader's machine, and the fallback is written
+ * only when none of them exists.
+ *
+ * @param {string[]} surfaces the surface ids selected across the workspace
+ * @returns {Promise<{surface: string, label: string, path: string|null, why: string,
+ *   cap: {bytes: number, appliesTo: string, why: string}|null}[]>}
+ */
+export async function sharedTargets(surfaces) {
+  const out = [];
+  for (const id of [...surfaces].sort()) {
+    const row = loader(id);
+    if (row === null) {
+      out.push({
+        surface: id,
+        label: id,
+        path: null,
+        cap: null,
+        why: `no user-level instruction file is recorded for ${id}; its user rules are configured in the app, not in a file`,
+      });
+      continue;
+    }
+    const users = row.start.filter((s) => s.scope === 'user' && s.atStart === true);
+    const flat = users.find((u) => u.tree === 'flat');
+    if (flat !== undefined) {
+      out.push({
+        surface: id,
+        label: row.label,
+        // A flat tree names a directory and a glob; the filename inside it is this tool's
+        // to choose, which is why this path is the only one in the module that is not in
+        // the table verbatim. Nothing to choose between here: the reader's own files in
+        // that directory load alongside ours rather than instead of them.
+        path: join(inHome(flat.dir ?? flat.path), SHARED_BASENAME),
+        why: flat.why,
+        cap: fileCap(row),
+      });
+      continue;
+    }
+    const singles = users
+      .filter((u) => u.tree === 'single')
+      .map((u) => ({ ...u, path: inHome(u.path) }));
+    const present = [];
+    for (const candidate of singles) {
+      if (await nonEmptyFile(candidate.path)) present.push(candidate);
+    }
+    const chosen = present[0] ?? singles[singles.length - 1];
+    if (chosen === undefined) {
+      out.push({
+        surface: id,
+        label: id,
+        path: null,
+        cap: fileCap(row),
+        why: `${row.label} keeps user rules in its own settings, not in a file this tool can write`,
+      });
+      continue;
+    }
+    const alternates = singles.filter((u) => u.path !== chosen.path).map((u) => u.path);
+    out.push({
+      surface: id,
+      label: row.label,
+      path: chosen.path,
+      why:
+        alternates.length === 0 || chosen === singles[0]
+          ? chosen.why
+          : `${chosen.why}; written here rather than ${alternates.join(' or ')} because it is the one ${row.label} reads on this machine`,
+      cap: fileCap(row),
+    });
+  }
+  return out;
+}
+
+/**
+ * What every root in a workspace would carry, as `{id: rule}` per root.
+ *
+ * Each root is asked the question it already answers for `sync`, and nothing is read out
+ * of a sibling's tree beyond its own projection: the only reason this module exists is to
+ * compare roots, and it does that by asking each one rather than by reconstructing what
+ * each one would say.
+ *
+ * @returns {Promise<{path: string, desired: object, shareable: Map<string, object>}[]>}
+ */
+export async function sharedCandidates(roots, flags) {
+  const rows = [];
+  for (const path of roots) {
+    const desired = await desiredRegion(path, flags ?? {});
+    rows.push({ path, desired, shareable: new Map(desired.shareable.map((r) => [r.id, r])) });
+  }
+  return rows;
+}
+
+/**
+ * The rules every root carries with identical bytes, plus the ones that nearly qualify.
+ *
+ * `divergent` is not a diagnostic nobody reads: a rule two roots carry differently is
+ * almost always inferability having dropped a line in one of them, and the answer is to
+ * leave it in both regions rather than to teach this module which root was right. The two
+ * reasons are kept apart because they are different facts: a rule one root does not carry
+ * at all, and a rule two roots render differently, need different words in the report —
+ * "differs across 1 repositories" describes neither.
+ *
+ * @param {{shareable: Map<string, object>}[]} rows
+ * @returns {{shared: object[], divergent: {id: string, roots: string[], reason: 'bytes'|'coverage'}[]}}
+ */
+export function intersect(rows) {
+  if (rows.length === 0) return { shared: [], divergent: [] };
+  // The union of every root's ids, not the first root's: a rule only beta selects would
+  // otherwise never be named, and the report would leave a reader guessing whether it
+  // moved or stayed.
+  const ids = [...new Set(rows.flatMap((row) => [...row.shareable.keys()]))].sort();
+  const shared = [];
+  const divergent = [];
+  for (const id of ids) {
+    const carriers = rows.filter((row) => row.shareable.has(id));
+    const rule = carriers[0].shareable.get(id);
+    const same = carriers.every((row) => row.shareable.get(id).rendered === rule.rendered);
+    if (carriers.length === rows.length && same) {
+      // Sorted in the order a region already keeps its rules, so the shared file and a
+      // region's index are read in the same order and neither is sorted twice.
+      shared.push({ id, ...rule });
+      continue;
+    }
+    divergent.push({
+      id,
+      roots: carriers.map((row) => row.path),
+      reason: carriers.length === rows.length ? 'bytes' : 'coverage',
+    });
+  }
+  return { shared: shared.sort((a, b) => byPriorityThenId(a, b)), divergent };
+}
+
+/**
+ * The document the user-level file carries.
+ *
+ * One lead paragraph, and it is the paragraph a reader needs: these rules are here rather
+ * than in a repository, which is why a rule they expect in AGENTS.md is not in it. Below
+ * the lead the frames are byte-identical to what the regions used to carry, which is what
+ * lets a reader — or `check` — compare one copy against the other rather than against a
+ * reconstruction of it.
+ */
+export function sharedBody(rules) {
+  const lead =
+    'The rules every repository in this workspace shares, carried once here rather than in each ' +
+    "repository. A repository's own region carries what is left and names anything here it does " +
+    `not carry. Read one of these from any repository in the workspace with: ${CLI} rules show <id>`;
+  return rules.length === 0 ? lead : `${lead}\n\n${rules.map((r) => r.rendered).join('\n\n')}`;
+}
+
+/** The provenance a copy is stamped with. Same digest `sync` stamps, so one sha answers
+ *  both questions: a copy of the user file written by a different release of these rules
+ *  is stale, and there is nothing else in the comparison that would notice. */
+export async function sharedMeta(rules) {
+  return { sha: await provenanceDigest(), sources: rules.map((r) => r.source) };
+}
+
+/**
+ * Is the copy in the reader's home the bytes this workspace would write today?
+ *
+ * `diff` rather than a string compare, because the file may carry the reader's own prose
+ * above the region and a region that matches is current whether or not the bytes around it
+ * do. A whole-file comparison would report a stale copy for a file this tool only partly
+ * owns, and the reader would be told to run a command that changes nothing.
+ *
+ * @returns {Promise<{state: 'current'|'stale'|'absent'|'unreadable', action?: string,
+ *   region?: string, reason?: string}>}
+ */
+export async function sharedState(path, rules, meta) {
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'absent' };
+    return { state: 'unreadable', reason: error.message };
+  }
+  // A file with no region at all is absent, not stale: the reader has never installed one,
+  // and the remedy for that is the same command with a different sentence.
+  if (parse(text).status === 'absent') return { state: 'absent' };
+  const probe = diffRegion(text, sharedBody(rules), meta, { compose: composeShared });
+  return {
+    state: probe.action === 'unchanged' ? 'current' : 'stale',
+    action: probe.action,
+    region: probe.region,
+    reason: probe.action === 'malformed' ? probe.reason : undefined,
+  };
+}
+
+/**
+ * The write, with the file's current bytes as an argument.
+ *
+ * `inject` rather than `writeFile` for the reason the whole module exists in one line: the
+ * user-level AGENTS.md is the most likely file in a reader's home directory to contain
+ * something they wrote themselves. Only the bytes between the markers are ours.
+ */
+function injectShared(before, rules, meta) {
+  return inject(before, sharedBody(rules), meta, { compose: composeShared });
+}
+
+/**
+ * Write one user-level copy, creating the directory when the table named one.
+ *
+ * Idempotent: the same bytes come back `unchanged` and nothing is written, which is what
+ * lets `install` be run on every machine in an estate without anyone diffing their home
+ * directories afterwards.
+ *
+ * @returns {Promise<{path: string, action: string, created: boolean}>}
+ */
+export async function writeSharedFile(path, rules, meta) {
+  let before = '';
+  try {
+    before = await readFile(path, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const injected = injectShared(before, rules, meta);
+  if (injected.action === 'unchanged') return { path, action: 'unchanged', created: false };
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, injected.text);
+  return { path, action: injected.action, created: before === '' };
+}
+
+/**
+ * Are the rules this repository handed over actually in the reader's copy?
+ *
+ * A subset check rather than equality, and the difference matters: the file carries the
+ * union of what every repository in the workspace declared, so a file with extra rules is
+ * current for this repository while an exact comparison would call it stale and send the
+ * reader to reinstall it on every sibling. What must hold is the direction that costs
+ * something — every rule THIS repository stopped carrying is still there, byte for byte.
+ *
+ * @returns {Promise<{state: 'current'|'stale'|'absent'|'unreadable', missing: string[],
+ *   checked: number, reason?: string}>}
+ */
+export async function sharedCoverage(path, rules) {
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'absent', missing: [], checked: 0 };
+    return { state: 'unreadable', missing: [], checked: 0, reason: error.message };
+  }
+  const parsed = parse(text);
+  if (parsed.status === 'absent') return { state: 'absent', missing: [], checked: 0 };
+  if (parsed.status === 'malformed') {
+    // Reported as unreadable rather than as missing: the rules may be in there, but a file
+    // with two regions cannot be checked, and "run shared install" would not fix it.
+    return { state: 'unreadable', missing: [], checked: 0, reason: parsed.reason };
+  }
+  const missing = rules.filter((r) => !parsed.body.includes(r.rendered)).map((r) => r.id);
+  return {
+    state: missing.length === 0 ? 'current' : 'stale',
+    missing,
+    checked: rules.length,
+    bytes: Buffer.byteLength(parsed.body),
+  };
+}
+
+/**
+ * The bytes the reader pays once for the whole workspace (ADR-084).
+ *
+ * Counted ONCE per file and counted at all, which is the whole reason this exists: a
+ * report that measured seven regions and ignored the file the rules moved into would
+ * show a 72% saving that the reader's context never saw. The accept criterion for R11 is
+ * a number, and a number that leaves out the copy is not the reader's number.
+ *
+ * The whole file is counted, not the span between the markers, because the prose a reader
+ * keeps around the region is also always-on for that reader — and because the alternative
+ * needs a second definition of "generated bytes" to agree with `measureRoot`'s.
+ *
+ * @param {{surfaces: string[], desired?: object}[]} rows as `measureRoot` returns them
+ * @returns {Promise<{bytes: number, files: {path: string, bytes: number, rules: number}[]}>}
+ */
+export async function sharedTotals(rows) {
+  const surfaces = [...new Set(rows.flatMap((row) => row.surfaces ?? []))];
+  const files = [];
+  for (const t of await sharedTargets(surfaces)) {
+    if (t.path === null) continue;
+    let text;
+    try {
+      text = await readFile(t.path, 'utf8');
+    } catch (error) {
+      // ENOENT is the normal state of a reader who has not installed a workspace copy, and
+      // reporting it as a fault would make `tokens` fail over something it is measuring.
+      if (error.code === 'ENOENT') continue;
+      throw error;
+    }
+    const parsed = parse(text);
+    files.push({
+      path: t.path,
+      bytes: Buffer.byteLength(text),
+      rules: parsed.status === 'ok' ? countFrames(parsed.body) : 0,
+    });
+  }
+  return { bytes: files.reduce((n, f) => n + f.bytes, 0), files };
+}
+
+/** One shared rule in a file: `## Stack: <id>`, `## Core` or `## Process: <id>`. */
+function countFrames(body) {
+  return body.split('\n').filter((line) => /^## (Stack: |Core$|Process: )/.test(line)).length;
+}
+
+/**
+ * Every repository under `root`, in `discover`'s order.
+ *
+ * Not re-sorted here, deliberately: that order decides which root owns a shared paragraph
+ * in `tokens --repos`, and ADR-084's accept criterion is measured in that number.
+ *
+ * @returns {Promise<{roots: string[], error: string|null}>}
+ */
+export async function sharedRoots(root) {
+  const found = await discover(root);
+  return { roots: found.repos, error: found.error ?? null };
+}

package/src/projection/surfaces.mjs

@@ -91,13 +91,13 @@ export const SURFACES = [
     id: 'opencode',
     label: 'opencode (AGENTS.md + .agents/skills)',
     readers:
-      'opencode, 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',
+      '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 documents NO per-rule directory: it reads AGENTS.md (walking up to the
-    // git worktree), CLAUDE.md only as a fallback, and .opencode/AGENTS.md in
-    // addition. So `foldRules` — this surface carries every rule inside the one
-    // generated region, and the other rows are how a rule reaches an editor that
+    // 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,
@@ -118,7 +118,7 @@ export const SURFACES = [
       },
     ],
     verified:
-      'opencode docs, "Rules" and "Agent Skills" (read 2026-10-07) — AGENTS.md walked up from cwd to the git worktree; CLAUDE.md used only if no AGENTS.md exists; .opencode/AGENTS.md additionally; skills at .opencode/skills/, .claude/skills/ and .agents/skills/<name>/SKILL.md; skill frontmatter recognises only name, description, license, compatibility, metadata',
+      '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.',
   },
@@ -286,8 +286,12 @@ export const POINTERS = [
     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',
-    note: 'Covers Gemini CLI and gives Antigravity a second, equally-native name for the same file.',
+      '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.',
   },
 ];
 
@@ -399,6 +403,16 @@ export const CANDIDATE_DIRS = [
   { dir: '.continue', harness: 'Continue' },
   { dir: '.amp', harness: 'Amp' },
   { dir: '.goose', harness: 'Goose' },
+  // Home directory, seen only with `harness detect --user`. DeepSeek keeps user data
+  // under ~/.dsh and reads the repository's AGENTS.md; it has no project config
+  // directory and no per-rule file to project (ADR-067).
+  {
+    dir: '.dsh',
+    harness: 'DeepSeek harness',
+    readsAgentsMd: 'all',
+    verified:
+      'DeepSeek harness agent-instructions docs (read 2026-10-14): user data lives at $DSH_HOME or ~/.dsh, and the project chain is AGENTS.md',
+  },
 ];
 
 /**

package/src/projection/targets.mjs

@@ -18,6 +18,7 @@ import { join } from 'node:path';
 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';
 
 /**
  * A managed rule file is a GENERATED FILE, unlike AGENTS.md.
@@ -169,7 +170,7 @@ export async function scopedTargets(root, rules, sha, resolved, notes) {
       alwaysApply: false,
       scope: rule.scope,
     };
-    targets.push(...(await ruleTargets(root, scoped, rule.body, sha, resolved, notes)).targets);
+    targets.push(...(await ruleTargets(root, scoped, foldChecks(rule.body).body, sha, resolved, notes)).targets);
   }
   return { targets };
 }

package/src/toolwords.mjs

@@ -0,0 +1,71 @@
+// The `simt-` names this tool owns, and the records that argue about the prefix itself.
+//
+// Two readers need to tell this tool's own vocabulary from a repository in the estate
+// these records were written about: the decision reader, which redacts the second kind
+// and names it, and the guard on shipped text, which refuses to ship it. Both answered
+// the question with a shape — `simt-` followed by anything but `dev` — and the shape is
+// false about the tool's own names, which the corpus prints. `rules why ADR-073` reported
+// that the ruling surveyed `simt-priority` as a repository, and printed the same word as
+// `a repository: hard | command | convention | style` where the record says
+// `simt-priority: hard | command | convention | style`: a reader with the tool and not
+// the estate got a sentence with no subject, from the command whose whole job is to
+// explain a citation.
+//
+// The words are derived from the modules that own them (ADR-022) rather than listed
+// here, because a second list is a list that drifts and then forgives. Both readers read
+// this one, and a name added to a frontmatter vocabulary reaches both without an edit.
+import { KNOWN_KEYS } from './projection/mdc.mjs';
+import { PROFILE_KEYS } from './projection/rules.mjs';
+import { INFERABLE_MARKER } from './kernel/inferability.mjs';
+import { CHECK_MARKER } from './kernel/checks.mjs';
+
+/**
+ * `simt-` names that belong to this tool and never to a repository.
+ *
+ * The last three are not frontmatter: they are names this tool writes into files it
+ * adopts a repository into — the package, the gate file it puts in `.github`, and the
+ * hooks directory it points `core.hooksPath` at. `simt-dev` itself is here for the same
+ * reason the estate pattern exempts it, and stating it once here is what stops the two
+ * readers from disagreeing about the tool's own name.
+ */
+export const TOOL_WORDS = new Set([
+  ...KNOWN_KEYS,
+  ...PROFILE_KEYS,
+  INFERABLE_MARKER,
+  CHECK_MARKER,
+  'simt-dev',
+  'simt-dev-check',
+  'simt-hooks',
+]);
+
+/**
+ * Records whose subject is the prefix itself, so the prefixed names in them are the
+ * argument rather than a citation.
+ *
+ * Each entry is a file and a reason, never a repository. That distinction is the whole
+ * point: an exemption says "this document discusses the namespace", which is a fact
+ * about this tool and carries nothing about whoever uses it. A vocabulary cannot settle
+ * these two — a hypothetical key in an argument and a repository name are the same shape
+ * — so the file is exempted where the word cannot be.
+ *
+ * The guard fails on a stale entry: each one must still be tripping the rule, so an
+ * exemption that stops being needed is removed rather than kept as a precedent.
+ */
+export const PREFIX_ARGUING = new Map([
+  [
+    'ADR-022-a-key-simt-dev-reads-is-prefixed.md',
+    'is the record arguing for the prefix, using hypothetical keys as examples',
+  ],
+  [
+    'ADR-026-a-config-without-a-region-is-a-file-the-repo-owns.md',
+    'names one prefixed key to record Dependabot rejecting it',
+  ],
+  [
+    'ADR-080-the-tools-own-names-are-not-repositories-and-neither-reader-decides-by-shape.md',
+    'quotes the prefixed names it measured, which are its evidence rather than a citation',
+  ],
+  [
+    'ADR-081-a-tracker-is-read-through-the-repositorys-template.md',
+    'names the plan overlay file the next record withdraws, and that filename has the shape of a repository',
+  ],
+]);

package/templates/plan/tracker.json

@@ -0,0 +1,36 @@
+{
+  "$comment": "Tracker format delivered with the tool. A repository replaces any section with the plans key in simt.json; a section it omits stays as written here. directories are the only places read, and each word is what a dependency uses to name that place (\"review 0002 S41\"). Headers are tried in the order written. Only a state marked satisfies unblocks a slice that depends on it. ready is the state plan next returns. dependency.group matches a wave of rows; wave names that table's columns.",
+  "name": "tracker",
+  "directories": [
+    { "kind": "plans", "word": "plan", "path": "docs/plans" },
+    { "kind": "reviews", "word": "review", "path": "docs/reviews" }
+  ],
+  "id": {
+    "pattern": "^[A-Za-z]{0,4}[- ]?[0-9]{1,4}$",
+    "headers": ["id", "#", "step", "item", "slice", "task"]
+  },
+  "columns": {
+    "state": ["state", "status", "done when"],
+    "depends": ["depends on", "depends", "dependency", "dependencies", "deps", "needs"],
+    "title": ["slice", "deliverable", "title", "summary", "description", "content"],
+    "evidence": ["sha / evidence", "sha/evidence", "evidence", "sha", "notes", "note"]
+  },
+  "states": [
+    { "id": "queued", "write": "Queued", "read": ["queued"] },
+    { "id": "in-progress", "write": "In progress", "read": ["in progress", "in-progress"] },
+    { "id": "complete", "write": "Complete", "read": ["complete", "completed", "done"], "satisfies": true },
+    { "id": "accepted", "write": "Accepted", "read": ["accepted"] }
+  ],
+  "ready": "queued",
+  "dependency": {
+    "empty": ["none", "null", "n/a", "n.a.", "na", "—", "-", "–"],
+    "separators": ",;",
+    "notes": true,
+    "group": "^waves?\\s+(.+)$"
+  },
+  "wave": {
+    "label": ["wave"],
+    "members": ["slices"]
+  },
+  "section": { "depth": 3 }
+}