simt-dev 0.1.1 → 0.2.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?
  *
@@ -397,7 +587,7 @@ function defaultId(root) {
  * 1. A STALE GENERATED FIELD. `buildManifest` emits `$comment` and
  *    `projection.simtDevSha`; the repo owns everything else. `upgrade` spreads the
  *    existing manifest and refreshes only the SHA, so a field added to the writer
- *    after a repo was adopted never appears — simt-space had been projecting for
+ *    after a repo was adopted never appears — one repository had been projecting for
  *    several versions with no `surfaces` key, and nothing said so. Every parse-based
  *    comparison passes, because the file is valid and the values in it are all true.
  *
@@ -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/markers.mjs

@@ -217,7 +217,7 @@ export function compose(body, { sha, sources = [] } = {}, style) {
   );
   const trimmed = body.replace(/\n+$/, '');
   // Two lines here exist only because a real repo proved they are needed. A
-  // formatter that runs on commit - simt-space has one, and three of the estate's
+  // formatter that runs on commit - several repositories have one, and three of the
   // other repos do too - rewrote the region on the very first commit: it inserted a
   // blank line after the header comment and added the trailing newline. Both edits
   // are things prettier considers correct, and either one alone makes `check`
@@ -226,7 +226,7 @@ export function compose(body, { sha, sources = [] } = {}, style) {
   // projection emits the formatter's shape in the first place. The blank line before
   // END is the same class: prettier treats an HTML comment after a paragraph as a
   // new block and inserts the separating blank line itself, which made
-  // simt-blog's `format:check` fail on a file whose generated region was correct.
+  // a `format:check` fail on a file whose generated region was correct.
   const out =
     trimmed === ''
       ? [s.begin, ...header, s.end]
@@ -293,7 +293,7 @@ export function inject(text, body, meta, opts = {}) {
     // terminates the region with one; adding a second left every adopted file
     // ending in a blank line. Nothing in this tool noticed, because `check`
     // compares region bodies and the byte after END is not part of the region —
-    // but bunnyland-server's own `git diff --check` gate did, and it is a gate
+    // but a repository's own `git diff --check` gate did, and it is a gate
     // that repo runs before every commit. The `updated` branch below has always
     // been correct for exactly this reason.
     //

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',
@@ -201,7 +202,7 @@ function stripFrontmatter(text) {
  *
  * An empty-string default is a deliberate "this repo has nothing to add here"
  * and the line it sits on is DROPPED. That is how `preview-postflight` reaches
- * `simt-social-media` without printing an empty bullet, and how a repo with no
+ * a repository without printing an empty bullet, and how a repo with no
  * production-domain note gets a clean document instead of a blank one.
  *
  * A placeholder with neither a declared nor a default value is a defect: the
@@ -218,7 +219,7 @@ export function renderMdc(rule, declared = {}) {
 
     if (has && provided === '') {
       // A repo declared this key and declared it empty: the line it sits on is
-      // removed. This is how preview-postflight reaches simt-social-media without
+      // removed. This is how preview-postflight reaches a repository without
       // printing a blank bullet.
       body = dropOrReplace(body, sub.key, '');
       continue;
@@ -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);

package/src/projection/surfaces.mjs

@@ -17,7 +17,7 @@
 //
 //   1. A POINTER IS NOT A COPY. `CLAUDE.md` and `GEMINI.md` are symlinks to
 //      `AGENTS.md`. A copy is the corpus's one true content duplicate
-//      (bunnyland-server's `CLAUDE.md` is byte-identical to its `AGENTS.md`), and
+//      (one repository's `CLAUDE.md` is byte-identical to its `AGENTS.md`), and
 //      the DeepSeek harness explicitly rejects loading both in one directory
 //      because "repositories in transition commonly duplicate guidance" — and
 //      *its* dedup is content-based, so a symlink collapses to one while a
@@ -32,7 +32,7 @@
 //      mode bit. So those get machine-written copies — and because every byte is
 //      derived from `rules/mdc/*.mdc` and `simt-dev check` compares each against
 //      that same derivation, they are not duplication, they are a build output.
-//      The difference from bunnyland's duplicate is that nobody can hand-edit one
+//      The difference from that duplicate is that nobody can hand-edit one
 //      and have it survive a sync.
 //
 //   3. AN ALWAYS-ON RULE EMITS NO SCOPING FRONTMATTER. Claude Code's `paths:` key

package/src/projection/targets.mjs

@@ -64,14 +64,45 @@ export async function ruleTargets(root, rule, body, sha, resolved, notes) {
     }
 
     const mine = s.ruleFrontmatter(rule);
-    const frontmatter = extractFrontmatter(existing) ?? frontmatterBlock(mine);
+    // The frontmatter is re-derived, never inherited (S16).
+    //
+    // Two things were wrong and only the second was visible. The first was
+    // `extractFrontmatter(existing) ?? frontmatterBlock(mine)`, where the file's own
+    // block won whenever the file already had one. The second was this line's
+    // neighbour: when the existing region parsed cleanly, `composed` was the whole
+    // existing file, so `inject` replaced the region between the markers and left the
+    // frontmatter above them exactly as it found it — whatever this tool emitted the
+    // first time it saw this surface, forever. A surface that adds a key, or whose
+    // `alwaysApply` flips, could never reach a repository that had already adopted it,
+    // and no gate could report it: the file agrees with itself, so nothing is stale by
+    // any comparison the tool makes.
+    //
+    // One asymmetry, deliberately: a surface that emits NO frontmatter leaves whatever
+    // is there alone. This tool owns the block it writes and will replace it; deleting a
+    // block it did not write is a different operation, and a surface with no frontmatter
+    // of its own has no opinion about it.
+    const frontmatter = mine.length > 0 ? frontmatterBlock(mine) : extractFrontmatter(existing) ?? '';
     const state = exists ? parse(existing) : { status: 'absent' };
     // A surface that wants no frontmatter must not get a blank line where the
     // frontmatter would have been: Claude's rule files opened with two empty lines
     // before the marker, which is untidy in a file the reader will open, and a
     // difference between surfaces that no check reported.
+    //
+    // Swapped in place rather than stripped and rejoined. My first attempt here was
+    // `${frontmatter}\n${bodyAfterFrontmatter(existing)}`, which looked equivalent and
+    // was not: that helper's trailing `\n*` swallows the blank line between `---` and
+    // the region, so the reconstruction was one newline short of the file and `inject`
+    // reported `updated` on every run forever while writing identical bytes. The file
+    // was right; the verdict never settled, so `check` reported drift no reader could
+    // see and `sync` rewrote a correct file on every invocation. Anything that rebuilds
+    // a file has to reproduce the bytes it did not mean to touch, and the cheapest way
+    // to guarantee that is not to rebuild them.
     const composed =
-      state.status === 'ok' ? existing : frontmatter === '' ? '' : `${frontmatter}\n`;
+      state.status === 'ok'
+        ? swapFrontmatter(existing, frontmatter)
+        : frontmatter === ''
+          ? ''
+          : `${frontmatter}\n`;
     const result = inject(composed, body, { sha, sources: [rule.source] });
 
     // Report the prose being retired rather than letting it vanish into a diff the
@@ -201,11 +232,6 @@ export async function pointerState(root, pointer) {
   return { file: pointer.file, state: 'mispointed', link, detail: `points at ${link}` };
 }
 
-export function surfaceFrontmatter(surfaceId, rule) {
-  const s = SURFACES.find((x) => x.id === surfaceId);
-  return s && s.ruleFrontmatter ? s.ruleFrontmatter(rule) : [];
-}
-
 // The per-surface path lives in surfaces.mjs next to the row that justifies it;
 // re-exported so a caller building a target never has to know which module owns
 // path construction as opposed to frontmatter construction.
@@ -216,6 +242,26 @@ export function extractFrontmatter(text) {
   return m ? m[0].trimEnd() : null;
 }
 
+/**
+ * Put `frontmatter` where a frontmatter block already is, and leave every other byte
+ * exactly where it was.
+ *
+ * The block match deliberately stops at the closing `---` and not past it, so the
+ * replacement starts at the newline that follows — the blank line a formatter requires
+ * before an HTML comment survives belongs to the file, not to the block, and consuming
+ * it here is what made `inject` report `updated` forever on files whose bytes never
+ * changed.
+ *
+ * A file with no block gets one above its content. The separator below it is left to
+ * `inject`'s `seam`, which is the one place that knows what the surrounding document
+ * format requires.
+ */
+function swapFrontmatter(text, frontmatter) {
+  if (frontmatter === '') return text;
+  const m = /^---\n[\s\S]*?\n---/.exec(text);
+  return m === null ? `${frontmatter}\n${text}` : `${frontmatter}${text.slice(m[0].length)}`;
+}
+
 function bodyAfterFrontmatter(text) {
   return text.replace(/^---\n[\s\S]*?\n---\n*/, '');
 }