simt-dev 0.2.0 → 0.2.1

package/src/projection/conflicts.mjs

@@ -11,6 +11,8 @@
 // substring scan reports that file as violating the very rule it is correctly
 // restating. So every match is checked for prohibition context first.
 
+import { POINTERS, SURFACES } from './surfaces.mjs';
+
 /** Files whose text is a hand-written rule surface. Scanned for conflicts only;
  *  generated regions are excluded at read time by the caller.
  *
@@ -18,11 +20,60 @@
  *  worth recording: the estate's three always-on `.mdc` families were the single
  *  worst-drifted content in it, and `simt-dev init` reported `CONFLICTS none detected`
  *  on the repo holding them. A conflict detector that only looks at the filenames
- *  it was written for will quietly miss a whole rule surface added later. */
+ *  it was written for will quietly miss a whole rule surface added later.
+ *
+ *  And then it did. The comment above was written as a lesson and the lesson was not
+ *  taken: the list stayed hand-written, two surfaces were added to `SURFACES`
+ *  afterwards, and `.claude/rules/` and `.agents/rules/` were silently unscanned —
+ *  two of the five surfaces, and both of them read a rule that this tool writes. A
+ *  comment saying "derive this" is not deriving it. So the per-rule directories come
+ *  from `SURFACES` now (see `ruleGlobs`), and this list holds only the files no
+ *  surface declares. */
 export const RULE_FILES = ['AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md'];
 
-/** Rule files discovered by glob rather than by name. */
-export const RULE_GLOBS = ['.cursor/rules/*.mdc', '.github/instructions/*.md'];
+/** Pointer targets, scanned because this tool writes them and they are rule files.
+ *
+ *  `CLAUDE.md` was named by hand in `RULE_FILES` for the whole life of the tool, and
+ *  `GEMINI.md` — which `POINTERS` creates for a repo on the Antigravity surface — was
+ *  not. So one file this tool writes was scanned and the other was not, with nothing
+ *  in the source saying which was which: the difference was an accident of the order
+ *  the two were added. Derived from `POINTERS` now, so it cannot recur. */
+function pointerFiles() {
+  return POINTERS.map((p) => p.path);
+}
+
+/**
+ * The per-rule directories, read out of `SURFACES` rather than written out here.
+ *
+ * One list of surfaces, read by everything that has to know where a surface keeps its
+ * rules. A surface added to `SURFACES` is now scanned for conflicts the moment it
+ * exists, which is the property the hand-written list kept failing to have — and it
+ * could only fail quietly, because a detector that matches nothing reports the same
+ * answer as a repository with no rules.
+ *
+ * `CLAUDE.md` and `GEMINI.md` are here through `RULE_FILES`/`POINTERS` rather than
+ * through this: they are symlinks to the primary region, so they are scanned as
+ * *files*, and `CONTRIBUTING.md` belongs to no surface at all.
+ *
+ * Takes the list as an argument rather than closing over it so the derivation can be
+ * shown on a surface that does not exist. The default is `SURFACES`, so every caller
+ * still reads the one authority; there is no way to pass anything else in production.
+ *
+ * @param {{rule?: string}[]} [surfaces]
+ */
+export function ruleGlobs(surfaces = SURFACES) {
+  return surfaces.filter((s) => typeof s.rule === 'string').map((s) => {
+    const slash = s.rule.lastIndexOf('/');
+    const extension = s.rule.slice(s.rule.lastIndexOf('.'));
+    // The FINAL extension, not the whole tail after `{name}`. Copilot's template is
+    // `{name}.instructions.md`, and matching that whole suffix would be narrower than
+    // the `.md` this file used to list by hand — which is the difference between seeing
+    // a hand-written `reviewer.md` in that directory and reporting the directory as
+    // empty. A file this tool writes always carries its own suffix; a file a person
+    // wrote in the same directory need not, and the person is who this scanner is for.
+    return `${s.rule.slice(0, slash)}/*${extension}`;
+  });
+}
 
 /** Every hand-written rule path in a repo, named or globbed.
  *
@@ -36,8 +87,8 @@ export const RULE_GLOBS = ['.cursor/rules/*.mdc', '.github/instructions/*.md'];
 export async function rulePaths(root) {
   const { readdir } = await import('node:fs/promises');
   const { join } = await import('node:path');
-  const out = RULE_FILES.map((f) => join(root, f));
-  for (const glob of RULE_GLOBS) {
+  const out = [...new Set([...RULE_FILES, ...pointerFiles()])].map((f) => join(root, f));
+  for (const glob of ruleGlobs()) {
     const star = glob.lastIndexOf('*');
     const dir = join(root, glob.slice(0, star));
     const tail = glob.slice(star + 1);

package/src/projection/manifest.mjs

@@ -29,6 +29,7 @@ import { getGate } from '../hooks/gates.mjs';
 // file by name.
 import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
 import { CLI } from '../name.mjs';
+import { packageVersion } from '../package-version.mjs';
 export const MANIFEST = MANIFEST_FILE;
 
 export { MANIFEST_LEGACY };
@@ -98,6 +99,93 @@ const TAG_GATES = [
   { tag: 'hono', preCommit: ['i18n-completeness'] },
 ];
 
+/**
+ * The ecosystems that produce a fact rather than a stack tag, and what a fresh
+ * adoption of one should declare.
+ *
+ * A row proposes gates the way `GATES_BY_STACK` does, and the fact it keys on is
+ * the same signal a profile's `simt-applies` names, so one marker file reaches
+ * both: the region this repo reads and the gates its commits run.
+ *
+ * `commands` is what a FRESH manifest declares for each proposed gate, and it is
+ * written only when the probe in `readCapability` found `tool` where this row says
+ * it lives. A declared gate that cannot run blocks every commit, so a command is
+ * never declared on the faith of a marker file: the marker says the ecosystem is
+ * here, the probe says its program can run (ADR-017). A command the repo already
+ * declared wins over the seed, because a seed is a default and a declaration is a
+ * choice.
+ *
+ * `file` marks a tool that is a file in the repository rather than a binary on
+ * PATH: the Maven wrapper, probed the way this tool already probes `gradlew`.
+ */
+export const ECOSYSTEMS = [
+  {
+    fact: 'has-cargo-toml',
+    tool: 'cargo',
+    preCommit: ['format', 'lint'],
+    prePush: ['test'],
+    commands: { format: 'cargo fmt --check', lint: 'cargo clippy -- -D warnings', test: 'cargo test' },
+  },
+  {
+    fact: 'has-go-mod',
+    tool: 'go',
+    preCommit: ['format', 'lint'],
+    prePush: ['test'],
+    commands: { format: 'test -z "$(gofmt -l .)"', lint: 'go vet ./...', test: 'go test ./...' },
+  },
+  {
+    fact: 'has-nuget',
+    tool: 'dotnet',
+    preCommit: ['format'],
+    prePush: ['test', 'typecheck'],
+    commands: { format: 'dotnet format --verify-no-changes', test: 'dotnet test', typecheck: 'dotnet build -warnaserror' },
+  },
+  {
+    fact: 'has-swift-package',
+    tool: 'swift',
+    preCommit: ['format'],
+    prePush: ['test', 'typecheck'],
+    commands: { format: 'swift format lint -r .', test: 'swift test', typecheck: 'swift build' },
+  },
+  {
+    fact: 'has-deno-config',
+    tool: 'deno',
+    preCommit: ['format', 'lint'],
+    prePush: ['test', 'typecheck'],
+    commands: { format: 'deno fmt --check', lint: 'deno lint', test: 'deno test', typecheck: 'deno check .' },
+  },
+  {
+    fact: 'has-gemfile',
+    tool: 'bundle',
+    preCommit: ['format'],
+    prePush: ['test'],
+    commands: { format: 'bundle exec rubocop', test: 'bundle exec rspec' },
+  },
+  {
+    fact: 'has-pubspec',
+    tool: 'dart',
+    preCommit: ['format', 'lint'],
+    prePush: ['test'],
+    commands: { format: 'dart format --output=none --set-exit-if-changed .', lint: 'dart analyze', test: 'dart test' },
+  },
+  {
+    fact: 'has-mix',
+    tool: 'mix',
+    preCommit: ['format'],
+    prePush: ['test'],
+    commands: { format: 'mix format --check-formatted', test: 'mix test' },
+  },
+  // The wrapper is a file the repository commits, not a program on PATH. A repo with
+  // a pom.xml and no wrapper cannot run `./mvnw -q verify`, so the probe is the file.
+  {
+    fact: 'has-maven-pom',
+    tool: 'mvnw',
+    file: true,
+    prePush: ['test'],
+    commands: { test: './mvnw -q verify' },
+  },
+];
+
 /**
  * Can this repo actually run the gate?
  *
@@ -240,22 +328,68 @@ function runnerName(runner) {
  *   - `command` gates run whatever `gates.commands` declares, so a command gate with
  *     no declared command is unrunnable by definition
  *
- * @returns {{gates: {preCommit: string[], prePush: string[]}, dropped: {gate: string, why: string}[]}}
+ * The seeds are returned alongside the plan because a fresh adoption writes them
+ * into `gates.commands` and the reader is owed the line that says so: a command
+ * that lands in the manifest without appearing in the plan is a silent write.
+ *
+ * @returns {{gates: {preCommit: string[], prePush: string[]}, dropped: {gate: string, why: string}[], commands: Record<string,string>}}
  */
-export function planGates(stack = [], capability = null) {
-  const proposed = defaultGates(stack);
-  if (!capability) return { gates: proposed, dropped: [] };
+export function planGates(stack = [], capability = null, facts = []) {
+  const proposed = defaultGates(stack, facts);
+  if (!capability) return { gates: proposed, dropped: [], commands: {} };
+  const seeds = ecosystemCommands(facts, capability);
+  // A command the repo already declared wins over a seed: the seed is a default,
+  // the declaration is a choice, and a default overwriting a choice is a re-init
+  // that edits the repo's mind.
+  const effective = { ...capability, commands: { ...seeds, ...capability.commands } };
   const dropped = [];
   const runnable = (list) =>
     list.filter((name) => {
       const gate = getGate(name);
-      const verdict = gateRunnable(gate, capability);
+      const verdict = gateRunnable(gate, effective);
       if (!verdict.runnable) {
         dropped.push({ gate: name, why: verdict.why, remedy: gateRemedy(gate, { runner: capability.runner }) });
       }
       return verdict.runnable;
     });
-  return { gates: { preCommit: runnable(proposed.preCommit), prePush: runnable(proposed.prePush) }, dropped };
+  return {
+    gates: { preCommit: runnable(proposed.preCommit), prePush: runnable(proposed.prePush) },
+    dropped,
+    commands: seeds,
+  };
+}
+
+/**
+ * The canonical `gates.commands` a fresh manifest of this repository should carry.
+ *
+ * Two probes, and both must pass before a command is declared: the fact says the
+ * ecosystem is in the repository, and `capability.tools` says its program can run
+ * on this machine. A marker file without a toolchain would otherwise declare a
+ * gate that fails closed on every commit — the defect ADR-017 exists to prevent,
+ * reached from the ecosystem table rather than the stack table.
+ *
+ * Pure, so `planGates` and `buildManifest` answer with one implementation.
+ */
+function ecosystemCommands(facts = [], capability = null) {
+  if (!capability?.tools?.length) return {};
+  // An npm runner already answers "how do I test and format" with its own package.json
+  // scripts, and a seed only wins over those scripts when the repo has not declared a
+  // command of its own — which is exactly the mixed repos (package.json AND Cargo.toml)
+  // where the script is the deliberate answer. Seeding there would replace a choice with
+  // a default; the reader's escape hatch is declaring gates.commands by hand, which a
+  // seed would lose to anyway. Pure ecosystem repos have runner 'cargo'/'go'/... and
+  // seed normally.
+  if (capability.runner === 'npm') return {};
+  const present = new Set(facts);
+  const commands = {};
+  for (const eco of ECOSYSTEMS) {
+    if (!present.has(eco.fact)) continue;
+    if (!capability.tools.includes(eco.tool)) continue;
+    for (const [gate, command] of Object.entries(eco.commands)) {
+      if (!capability.commands?.[gate]) commands[gate] = command;
+    }
+  }
+  return commands;
 }
 
 /**
@@ -267,16 +401,22 @@ export function planGates(stack = [], capability = null) {
  * make, and quietly disarming a gate somebody declared on purpose is a worse surprise
  * than a visible one.
  */
-export function buildManifest({ root, stack = [], sha, existing = null, capability = null, surfaces = undefined }) {
-  const gates = defaultGates(stack);
+export function buildManifest({ root, stack = [], sha, version, existing = null, capability = null, surfaces = undefined, facts = [] }) {
+  const gates = defaultGates(stack, facts);
   const limits = defaultLimits(stack);
 
   // A re-init must never silently weaken a repo's own declaration: existing
   // limits and gates win over defaults, and only the projection stamp is refreshed.
   const limitsFinal = existing?.limits ? { ...limits, ...existing.limits } : limits;
+  const planned = planGates(stack, capability, facts);
+  // The seeds land only on a FRESH manifest. On an existing one the repo's
+  // declaration is the answer, and adding commands under it would be a re-init
+  // writing into a field the reader owns — the same rule as the gates above.
   const gatesFinal = existing?.gates
     ? { ...gates, ...existing.gates }
-    : planGates(stack, capability).gates;
+    : Object.keys(planned.commands).length > 0
+      ? { ...planned.gates, commands: planned.commands }
+      : planned.gates;
 
   return {
     ...MANIFEST_COMMENT,
@@ -303,7 +443,12 @@ export function buildManifest({ root, stack = [], sha, existing = null, capabili
     // because a typo here silently reduces the estate to AGENTS.md, which looks
     // exactly like a working setup.
     surfaces: surfaces ?? existing?.surfaces ?? null,
-    projection: { simtDevSha: sha ?? null },
+    // simtDevSha is the digest of the rule bytes this projection was rendered from;
+    // version is the simt-dev release that produced it. The gate compares the running
+    // binary to version and refuses on a mismatch, which is how a repository without
+    // npm (a global install, pinned only by this field) is held to the release it
+    // adopted. See src/package-version.mjs.
+    projection: { simtDevSha: sha ?? null, version: version ?? null },
   };
 }
 
@@ -348,18 +493,30 @@ function defaultLimits() {
 }
 
 /** ADR-006: coverage stays null. Set it only if the repo has a real numeric gate. */
-function defaultGates(stack) {
-  const tags = new Set(stack);
+function defaultGates(stack, facts = []) {
+  // Tags and facts are one signal set for gate purposes: a row in `GATES_BY_STACK`
+  // keys on a tag, a row in `ECOSYSTEMS` on a fact, and the two never name each
+  // other's vocabulary (facts are `has-*`, tags are not), so one union cannot
+  // cross-match.
+  const signals = new Set([...stack, ...facts]);
   const gates = { preCommit: [], prePush: [] };
 
   for (const row of GATES_BY_STACK) {
-    if (row.when.some((tag) => tags.has(tag))) {
+    if (row.when.some((tag) => signals.has(tag))) {
       gates.preCommit.push(...row.preCommit);
       gates.prePush.push(...row.prePush);
     }
   }
+  for (const row of ECOSYSTEMS) {
+    if (signals.has(row.fact)) {
+      // A row proposes what it has: the Maven row has no preCommit gates, so a
+      // missing key is "none", not a defect. Spreading undefined throws.
+      gates.preCommit.push(...(row.preCommit ?? []));
+      gates.prePush.push(...(row.prePush ?? []));
+    }
+  }
   for (const row of TAG_GATES) {
-    if (tags.has(row.tag)) gates.preCommit.push(...row.preCommit);
+    if (signals.has(row.tag)) gates.preCommit.push(...row.preCommit);
   }
 
   // A repo with no recognised stack still gets a gate list, because a gate that
@@ -388,6 +545,39 @@ function defaultId(root) {
   return name === '' || name === '.' ? 'unnamed-repo' : name;
 }
 
+/**
+ * The fields this tool writes. Everything else in a manifest belongs to the
+ * repository that adopted the tool.
+ *
+ * It is a value rather than an expression inside `manifestDrift` because the question
+ * "is this field ours?" now has two callers that must answer it identically: the gate
+ * that reports one stale, and `sync`, which repairs exactly the fields the gate names.
+ * A second implementation of this set is a repair that fixes a field nothing reports,
+ * or a report about a field nothing repairs - and each half passes its own test,
+ * which is ADR-045's shape reached from the other direction.
+ */
+export const GENERATED_KEYS = new Set(['$comment', 'projection']);
+
+/**
+ * A manifest with this tool's own fields replaced by what this build writes, and
+ * nothing else touched.
+ *
+ * Spread from the repository's manifest rather than from `buildManifest`'s output:
+ * the builder fills a default for every key, so writing its result wholesale would
+ * overwrite `gates` and `limits` in any repository that chose its own. "Content the
+ * repo chose is never compared" is a promise about the repair too, not only about
+ * the report, and a repair is exactly where it would be broken.
+ *
+ * @param {object} manifest the repository's manifest, as parsed
+ * @param {object} expected `buildManifest`'s output, from the call `manifestDrift` made
+ * @returns {object} a new manifest; the argument is not mutated
+ */
+export function withGenerated(manifest, expected) {
+  const patched = { ...manifest };
+  for (const key of GENERATED_KEYS) if (key in expected) patched[key] = expected[key];
+  return patched;
+}
+
 /**
  * Is a generated field of this manifest wrong, or has a formatter taken its bytes?
  *
@@ -408,6 +598,12 @@ function defaultId(root) {
  *    again. `upgrade` reported `current` the whole time, which is correct: the pin
  *    was current. The bytes were not.
  *
+ *    This one is a consequence of routing, not of adoption. Nothing reformatted the
+ *    manifest until the pre-commit gate started running, so every repository that
+ *    adopts the tool and runs a formatter arrives here on its first commit. The
+ *    remedy is therefore "stop the formatter taking it, then `sync`" — and it was
+ *    `init --yes`, which re-runs adoption to change one file's formatting (ADR-050).
+ *
  * Content the repo chose is never compared. A repo that edited `limits.coverage` on
  * purpose is not being told to revert it.
  *
@@ -417,20 +613,34 @@ export async function manifestDrift(root, stack, sha) {
   const { manifest, exists, error } = await readManifest(root);
   if (!exists || error !== null || manifest === null) return null;
 
-  const expected = buildManifest({ root, stack, sha, existing: manifest });
-  const stale = [];
-  for (const key of Object.keys(expected)) {
-    const generated =
-      key === '$comment' ||
-      (key === 'projection' && JSON.stringify(expected.projection) !== JSON.stringify(manifest.projection ?? null));
-    if (generated && JSON.stringify(manifest[key]) !== JSON.stringify(expected[key])) stale.push(key);
-  }
+  const expected = buildManifest({ root, stack, sha, version: packageVersion(), existing: manifest });
+  // `[...GENERATED_KEYS]`, and not `Object.keys(expected)`: the question is which
+  // fields are ours, and the answer is the set above. Iterating the expected object
+  // asks the same question of a different list and can only agree by coincidence.
+  const stale = [...GENERATED_KEYS].filter(
+    (key) => key in expected && JSON.stringify(manifest[key]) !== JSON.stringify(expected[key]),
+  );
   if (stale.length > 0) {
     return {
       file: MANIFEST,
       status: 'stale-generated-field',
       detail: `generated field(s) ${stale.join(', ')} do not match what this simt-dev writes`,
-      remedy: `run: ${CLI} init --yes   (it refreshes the stamp without touching values this repo set)`,
+      // `sync`, and not `init`. `sync` repairs exactly this field set and nothing
+      // else; `init` re-runs adoption - it tags, it branches, it asks every question
+      // again - and two commands must not answer one question with different
+      // instructions (ADR-050).
+      //
+      // The remedy said `init` because for two releases nothing could repair a stale
+      // field, so the only command that could was the only one named. `sync` having
+      // nothing to repair while `check` refused anyway is the one-question-two-answers
+      // defect this repository exists to end, and it was true in all fourteen adopted
+      // repositories at the same moment: measured, not inferred. `check` exited 1 in
+      // every one of them while `sync` printed "already current; nothing written".
+      //
+      // No trailing parenthetical, because `compare` prints this string verbatim as
+      // the remedy on its own row. A remedy that reads well in one command's output
+      // and badly in another's is two answers wearing one string.
+      remedy: `run: ${CLI} sync --yes`,
     };
   }
 
@@ -446,10 +656,22 @@ export async function manifestDrift(root, stack, sha) {
     file: MANIFEST,
     status: 'reformatted',
     detail: 'content is what simt-dev would write, but the bytes differ - another formatter owns this file',
-    remedy: `add ${MANIFEST_FILE} to .prettierignore (a generated file is not prose), then: ${CLI} init --yes`,
+    remedy: `add ${MANIFEST_FILE} to .prettierignore (a generated file is not prose), then: ${CLI} sync --yes`,
   };
 }
 
+/**
+ * The bytes a manifest is written as.
+ *
+ * Exported because two callers now need them and one of them is a preview: a plan
+ * that reports a byte count it computed with a different serialiser than the writer
+ * used reports a number nothing will ever observe. `writeManifest` is the only place
+ * this format is spelled.
+ */
+export function manifestText(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
 /** @returns {{manifest: object|null, exists: boolean, error: string|null}} */
 export async function readManifest(root) {
   const path = await manifestPath(root);
@@ -473,6 +695,6 @@ export async function writeManifest(root, manifest) {
   const previous = join(root, MANIFEST_LEGACY);
   const fresh = join(root, MANIFEST);
   if (existsSync(previous) && !existsSync(fresh)) await rename(previous, fresh);
-  await writeFile(fresh, `${JSON.stringify(manifest, null, 2)}\n`);
+  await writeFile(fresh, manifestText(manifest));
   return fresh;
 }

package/src/projection/mdc.mjs

@@ -24,7 +24,6 @@
 
 import { readFile, readdir } from 'node:fs/promises';
 
-import { frontmatterBlock } from './surfaces.mjs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -45,7 +44,9 @@ const MDC_DIR = join(ROOT, 'rules', 'mdc');
  * defect — which is the failure ADR-016 shipped once, a rule that reached no repo
  * because `applies` was absent, silently and with a test green.
  */
-const KNOWN_KEYS = new Set([
+/** Frontmatter keys this tool reads, ADR-022. Exported so the one authority on the
+ *  tool's own vocabulary is also the one a guard subtracts, rather than a second copy. */
+export const KNOWN_KEYS = new Set([
   'simt-id',
   'simt-target',
   'simt-title',
@@ -300,14 +301,6 @@ function dropOrReplace(text, key, value) {
   return kept.join('\n').replace(/\n{3,}/g, '\n\n');
 }
 
-/** The frontmatter a projected `.mdc` keeps. `alwaysApply` and `description` are
- *  read by the editor before any rule text, so they belong outside the region. */
-export function mdcFrontmatter(rule) {
-  return frontmatterBlock([
-    `description: ${rule.description ?? `Canonical ${rule.id} rule managed by simt-dev`}`,
-    `alwaysApply: ${rule.alwaysApply ? 'true' : 'false'}`,
-  ]);
-}
 
 
 /**
@@ -322,6 +315,4 @@ export function ruleName(rule) {
   if (typeof rule.target !== 'string' || rule.target === '') return null;
   const base = rule.target.slice(rule.target.lastIndexOf('/') + 1);
   return base.replace(/\.mdc$/, '');
-}
-
-export { MDC_DIR, parse as parseRegion };
+}

package/src/projection/project.mjs

@@ -478,7 +478,7 @@ async function regionOpts(root) {
  * A reader that stops at a byte offset never sees a region that ends past it.
  * The finding names the reader, because "the file is long" does not say who stops.
  */
-export function readLimitFindings(text, file) {
+function readLimitFindings(text, file) {
   const state = parse(text);
   if (state.status !== 'ok' || typeof state.endByte !== 'number') return [];
   const findings = [];

package/src/projection/rules.mjs

@@ -57,13 +57,15 @@ const RULES_DIR = join(ROOT, 'rules');
  * unrecoverably. That is the failure this replaces (ADR-032).
  *
  * The digest covers every byte string that leaves the package, and nothing else. That
- * set is `rules/` and `graph/` on disk plus the RENDERED baseline bodies: the shared
+ * set is `rules/` on disk plus the RENDERED baseline bodies: the shared
  * `.editorconfig` and `.gitattributes` blocks are strings a repository receives, so by
  * ADR-015's rule a source is identified by its content rather than by the file it
- * happens to live in, and a body defined in `src/` is a source like any other.
+ * happens to live in, and a body defined in `src/` is a source like any other. The
+ * registry (`graph/`) is workspace data the package no longer ships (ADR-061), so it is
+ * not part of this set even where it exists on disk.
  *
- * It deliberately excludes `src/` as a directory. A refactor that changes no rule, no
- * registry entry and no baseline body produces byte-identical output, and stamping those
+ * It deliberately excludes `src/` as a directory. A refactor that changes no rule and
+ * no baseline body produces byte-identical output, and stamping those
  * consumers would report drift where there is none - which is the estate's own rule that
  * a report must be a fact.
  *
@@ -93,7 +95,7 @@ export async function provenanceDigest() {
  */
 export async function provenanceInputs() {
   const inputs = [];
-  for (const dir of ['rules', 'graph']) {
+  for (const dir of ['rules']) {
     for (const rel of await walk(join(ROOT, dir))) {
       inputs.push({ path: `${dir}/${rel}`, bytes: await readFile(join(ROOT, dir, rel)) });
     }
@@ -125,7 +127,8 @@ export const LOCAL_PROFILE_DIR = '.simt-dev/profiles';
  *  one carries the `simt-` prefix (ADR-022). A profile carrying a bare key would read
  *  as an editor's instruction — Cursor, Copilot and Antigravity all parse a
  *  frontmatter block the same way — and would be silently inert. */
-const PROFILE_KEYS = new Set(['simt-id', 'simt-title', 'simt-applies', 'simt-fallback']);
+/** Frontmatter keys a rule profile declares. See {@link KNOWN_KEYS} on why exported. */
+export const PROFILE_KEYS = new Set(['simt-id', 'simt-title', 'simt-applies', 'simt-fallback']);
 
 /** Report the first thing wrong with a profile's frontmatter, in the order a reader
  *  fixes it: no id to select it by, then a key that will not be read, then a tag the
@@ -293,8 +296,18 @@ async function ruleBodies(root, manifest, flags) {
 
   const declared = await readDeclared(root);
 
+  // Deliberately NOT folded in. This array becomes `mdc.problems`, and `sync` reports it
+  // as "canonical .mdc rule(s) cannot be projected" with the remedy "fix the reported
+  // substitution keys in simt.json". A surface typo is not a rule problem and has no
+  // substitution keys — `surfaces: ["curosr"]` was reported to a reader as though they
+  // had misspelled a key in a block they had never heard of, and the only way to find the
+  // real cause was to run `check`, which already said it plainly. Two surfaces report the
+  // same problem; only one of them names it correctly, and the one that mislabels it is
+  // the one the writer uses.
+  //
+  // Nothing is lost by dropping it here: `plan` returns `surfaceProblems` from this same
+  // `resolveSurfaces` call, and `checkTargets` reads it independently at project.mjs.
   const resolved = resolveSurfaces(manifest, flags ?? {});
-  for (const p of resolved.problems) problems.push(p);
 
   // A manifest key that no shipped rule declares is a typo, or a leftover from a rule
   // that was renamed. Both read as "configured" in the one file a reviewer opens to
@@ -574,7 +587,7 @@ export function render(selected) {
  * so it lands directly under `## Stack: …` instead of under whatever section the
  * previous source ended on.
  */
-export function frameSource(rule, body, kind) {
+function frameSource(rule, body, kind) {
   const text = demoteHeadings(body).trim();
   if (!text) return '';
   const title = sourceTitle(rule, kind);