simt-dev 0.7.0 → 0.8.0

package/src/projection/lock.mjs

@@ -17,6 +17,11 @@ import { LOCK_FILE, LOCK_LEGACY } from '../name.mjs';
 import { desiredRegion, provenanceDigest, LOCAL_PROFILE_DIR } from './rules.mjs';
 import { readManifest } from './manifest.mjs';
 
+/** The lock's own format. Bumped only when a reader must interpret an old file
+ *  differently; an absent field means 1, because every lock written before this
+ *  field existed was written by the only format there has been. */
+const LOCK_VERSION = 1;
+
 /** Manifest keys that change what the region contains. Anything else in the file is
  *  the repository's own notes, and hashing it would make a comment fail the lock. */
 const MANIFEST_KEYS = ['mode', 'budget', 'shared', 'surfaces', 'gates'];
@@ -39,7 +44,7 @@ export async function computeLock(root, flags = {}, manifest = undefined) {
   const outputs = createHash('sha256').update(desired.body).digest('hex');
   const hasVariants =
     variants && typeof variants === 'object' && Object.keys(variants).length > 0;
-  return hasVariants ? { inputs, outputs, variants } : { inputs, outputs };
+  return hasVariants ? { version: LOCK_VERSION, inputs, outputs, variants } : { version: LOCK_VERSION, inputs, outputs };
 }
 
 /**
@@ -71,6 +76,11 @@ export async function readLock(root) {
   if (text === null) return { lock: null, error: null };
   try {
     const lock = JSON.parse(text);
+    // Absent means 1; a version this build does not know is a lock it cannot judge,
+    // and reading it anyway would report drift for a format change.
+    if (lock.version !== undefined && (!Number.isInteger(lock.version) || lock.version < 1)) {
+      return { lock: null, error: 'version must be an integer of at least 1' };
+    }
     if (typeof lock?.inputs !== 'string' || typeof lock?.outputs !== 'string') {
       return { lock: null, error: 'must be an object with inputs and outputs' };
     }

package/src/projection/manifest.mjs

@@ -27,37 +27,27 @@ import { getGate } from '../hooks/gates.mjs';
 // Q31: the one Node runner table. This module and the card, capability,
 // dispatcher and CI workflow all spell `<manager> run <script>` from it.
 import { runScript } from '../ecosystem/node-runner.mjs';
+// Q70: the ecosystem records. A new ecosystem is a new file under `ecosystems/`, not a
+// row added to this table. records.mjs imports nothing from this package, so this edge
+// cannot cycle.
+import { ecosystemGateRows } from '../ecosystem/records.mjs';
 
 // Imported as well as re-exported: a bare `export { X as Y } from` binds nothing here,
 // and the manifest name is used a dozen times below in remedy strings that name this
 // file by name.
 import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+import { GENERATED_KEYS_OF, KEYS, loadManifest, manifestPath } from '../manifest/schema.mjs';
 import { CLI } from '../name.mjs';
 import { packageVersion } from '../package-version.mjs';
+import { defaultGates, planGates } from '../gates/index.mjs';
+export { ECOSYSTEMS, defaultGates, gateRunnable, planGates, unrunnableGates } from '../gates/index.mjs';
 export const MANIFEST = MANIFEST_FILE;
 
-export { MANIFEST_LEGACY };
-
-/**
- * The manifest a repository has, which is not necessarily the one this tool would write.
- *
- * The file was renamed from `simt-dev.json` to `simt.json`. Every read site used to say
- * `join(root, MANIFEST)` and would have reported an adopted repository as unadopted the
- * day the constant moved - and "no manifest" means "never adopted", which is the answer
- * that offers to re-adopt a repo that is already done. Fourteen repositories carry the
- * old name on disk.
- *
- * So the old name is read as a fallback and the new one is written. `writeManifest`
- * renames rather than creating a second file, which is how the window closes: the first
- * `simt init` or `simt sync` in an adopted repo retires the old name by moving it.
- */
-export async function manifestPath(root) {
-  const next = join(root, MANIFEST);
-  if (existsSync(next)) return next;
-  const previous = join(root, MANIFEST_LEGACY);
-  return existsSync(previous) ? previous : next;
-}
+// Still exported from here because this is where the manifest lived: every caller that
+// resolved its path through this module keeps working, and the implementation moved.
+export { manifestPath };
 
+export { MANIFEST_LEGACY };
 
 /**
  * The one definition of the file's own comment, exported because `upgrade` rewrites
@@ -75,7 +65,7 @@ export const MANIFEST_COMMENT = {
     `Written and maintained by simt-dev. \`${CLI} sync --yes\` regenerates the projected rules.`,
     `\`${CLI} init\` refreshes the SHA and keeps every key it does not write, so a value you add here survives a re-init.`,
     `\`plans\` is such a key: it selects the tracker template and the directories \`${CLI} plan\` reads.`,
-    'Omit it and the tracker template applies, which reads docs/plans and docs/reviews.',
+    'Omit it and the tracker template applies, which reads docs/plans, docs/research and docs/reviews.',
   ].join(' '),
 };
 
@@ -83,362 +73,14 @@ export const MANIFEST_COMMENT = {
  * Gate names the shared dispatcher knows how to run (step 8). Choosing these from
  * the detected stack rather than asking a human keeps `init` non-interactive.
  */
-const GATES_BY_STACK = [
-  {
-    when: ['gradle', 'kotlin', 'connectiq'],
-    preCommit: ['format', 'lint', 'i18n-completeness'],
-    prePush: ['test'],
-  },
-  {
-    when: ['python'],
-    preCommit: ['format', 'lint', 'i18n-completeness'],
-    prePush: ['test', 'coverage'],
-  },
-  {
-    when: ['node', 'node-web', 'cloudflare-workers', 'typescript'],
-    preCommit: ['format', 'lint'],
-    prePush: ['test', 'typecheck'],
-  },
-];
-
-/** Extra gate implied by a specific tag, applied after the table above. */
-const TAG_GATES = [
-  { tag: 'connectiq', preCommit: ['memory', 'codegen-drift'] },
-  { 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?
- *
- * A declared gate that cannot run is worse than an absent one. Absent, an author sees
- * nothing and knows nothing is being checked; declared-and-unrunnable, the dispatcher
- * fails closed on every commit and the only exit an author can find is `--no-verify`,
- * which teaches the whole team that the gate is theatre. The dispatcher is right to
- * fail closed — the defect is declaring a gate this repo has no way to run.
- *
- * The check mirrors what the dispatcher actually attempts:
- *   - `script` gates  run `<manager> run <script>`, so the script must exist
- *   - `staged` gates  look for each named tool in `node_modules/.bin`, so it must be
- *     installed, not merely declared as a dependency
- *   - `command` gates run whatever the manifest's `gates.commands` declares, so a
- *     command gate with no declared command is unrunnable by definition
- *
- * @param {object} gate an entry from GATES in src/hooks/gates.mjs
- * @param {{scripts?: Record<string,string>, binaries?: string[], commands?: Record<string,string>}} capability
- */
-export function gateRunnable(gate, capability = {}) {
-  if (!gate) return { runnable: false, why: 'unknown gate' };
-  // Only a KNOWN non-npm runner changes the wording. A capability that does not report
-  // its runner (a hand-built one, a caller from an older version) is treated as npm,
-  // because claiming a repo has no package.json is a much worse guess than assuming it.
-  const foreign = isForeignRunner(capability.runner);
-
-  // A declared command satisfies the gate whatever its kind, because that is the
-  // dispatcher's own precedence and the two must never disagree about one manifest.
-  const declared = capability.commands?.[gate.name];
-  if (declared) {
-    return declared.trim() === ''
-      ? { runnable: false, why: `gates.commands["${gate.name}"] is empty` }
-      : { runnable: true, why: `runs: ${declared}` };
-  }
-
-  if (gate.kind === 'builtin') {
-    // The one kind with no external requirement: the implementation ships inside
-    // the binary that is reading this manifest (ADR-100). Saying otherwise would
-    // make `check` report a gate as unrunnable that runs on every commit.
-    return { runnable: true, why: 'runs inside the tool itself; nothing to install' };
-  }
-  if (gate.kind === 'command') {
-    return { runnable: false, why: `no command is declared for it in gates.commands` };
-  }
-  if (gate.kind === 'script') {
-    const script = gate.script ?? gate.name;
-    // Q31: the runnable sentence names the repo's own runner, never a bare npm
-    // assumption — the card, the dispatcher and this check read one resolver.
-    const spell = runScript(capability.runner ?? 'npm', script);
-    if (capability.scripts?.[script]) return { runnable: true, why: `runs: ${spell}` };
-    // Saying "no script in package.json" about a repo with no package.json states a
-    // fact about a file that does not exist and implies a fix that cannot be taken.
-    return {
-      runnable: false,
-      why: foreign
-        ? `this repo runs ${runnerName(capability.runner)}, not npm, so "${spell}" cannot run here`
-        : `no "${script}" script in package.json`,
-    };
-  }
-  // staged: a formatter must actually be installed
-  for (const tool of gate.tools ?? []) {
-    if (!(capability.binaries ?? []).includes(tool)) {
-      return {
-        runnable: false,
-        why: foreign
-          ? `${tool} is not installed, and this repo has no node_modules/.bin to install it into`
-          : `${tool} is not installed in node_modules/.bin`,
-      };
-    }
-  }
-  return { runnable: true, why: `formats staged files with ${(gate.tools ?? []).join(', ')}` };
-}
-
-/**
- * What the reader has to do to make a dropped gate runnable.
- *
- * A drop is a decision the tool made on the repo's behalf, so it owes the reader the
- * undo. Every remedy is one of three real choices — install the tool, add the script,
- * or name the command — because "this repo cannot run format" with no next step reads
- * as simt-dev deciding formatting does not matter here.
- *
- * The two npm-shaped remedies only apply where npm is the runner. In a Gradle, Python or
- * Rust repo the honest undo is the `command` gate: the repo names its own program, which
- * is the same escape hatch ConnectIQ memory budgets already use.
- */
-function gateRemedy(gate, { existing = false, runner = null } = {}) {
-  const name = gate?.name ?? 'the gate';
-  const npmShaped = gate?.kind === 'staged' || gate?.kind === 'script';
-  const foreign = isForeignRunner(runner);
-  // Q31: a missing tool in a Node repo names the repo's own installer —
-  // `pnpm add -D`, not `npm i -D` — and anything elsewhere keeps the honest
-  // undo: name the program under `gates.commands`.
-  const addDev = { npm: 'npm i -D', pnpm: 'pnpm add -D', yarn: 'yarn add -D', bun: 'bun add -d' }[runner] ?? null;
-  const fix =
-    npmShaped && foreign
-      ? `this repo runs ${runnerName(runner)}, not npm; name the program under "gates.commands" in ${MANIFEST_FILE} instead of the npm equivalent`
-      : gate?.kind === 'staged'
-        ? addDev
-          ? `install ${gate.tools.join(', ')} as a dev dependency: ${addDev} ${gate.tools.join(' ')}   (the gate runs from the pinned dependency)`
-          : `install ${gate.tools.join(', ')} as a dev dependency`
-        : gate?.kind === 'script'
-          ? `add a "${gate.script ?? name}" script to package.json`
-          : gate?.kind === 'command'
-            ? `declare the program under "gates.commands" in ${MANIFEST_FILE}`
-            : `remove "${name}" from the gates list in ${MANIFEST_FILE}`;
-  // A re-init never re-adds a gate to a manifest that already has one, so "install the
-  // tool and re-run init" would send the reader round the loop and back to where they
-  // started. On an existing manifest the declaration is the second half of the fix.
-  const second =
-    npmShaped && foreign
-      ? `, or add "${name}" to gates.preCommit or gates.prePush in ${MANIFEST_FILE}`
-      : existing
-        ? `, then add "${name}" to gates.preCommit or gates.prePush in ${MANIFEST_FILE}`
-        : `, then re-run: ${CLI} init --yes`;
-  return `${fix}${second}`;
-}
-
-/**
- * Is this runner one where `npm run` is not how a gate is spelled?
- *
- * `undefined` means "the caller did not report a runner", and every Node manager
- * (`npm`, `pnpm`, `yarn`, `bun`) spells gates as `<manager> run <script>` with
- * scripts living in the same `package.json`. Only a positively identified
- * non-Node runner changes the wording. (Q31: pnpm is Node-shaped, not foreign.)
- */
-function isForeignRunner(runner) {
-  if (runner == null) return false;
-  return !['npm', 'pnpm', 'yarn', 'bun'].includes(runner);
-}
-
-/** How a reader would name the runner in a sentence. */
-function runnerName(runner) {
-  return (
-    {
-      none: 'no recognised runner',
-      gradle: 'Gradle',
-      python: 'Python',
-      npm: 'npm',
-      pnpm: 'pnpm',
-      yarn: 'yarn',
-      bun: 'bun',
-      cargo: 'Cargo',
-      go: 'Go',
-    }[runner] ?? runner
-  );
-}
-
-/**
- * The stack table, filtered by what this repo can actually run.
- *
- * A declared gate that cannot run is worse than an absent one. Absent, an author sees
- * nothing and knows nothing is being checked; declared-and-unrunnable, the dispatcher
- * fails closed on every commit and the only exit an author can find is `--no-verify`,
- * which teaches the whole team that the gate is theatre. The dispatcher is right to
- * fail closed — the defect is declaring a gate this repo has no way to run.
- *
- * The filter mirrors what the dispatcher actually attempts:
- *   - `script` gates  run `npm run <script>`, so the script must exist
- *   - `staged` gates  look for each named tool in `node_modules/.bin`, so it must be
- *     installed, not merely declared as a dependency
- *   - `command` gates run whatever `gates.commands` declares, so a command gate with
- *     no declared command is unrunnable by definition
- *
- * 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, 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, 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,
-    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 {};
-  // A Node runner (npm/pnpm/yarn/bun) 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.
-  // Q31: every Node manager skips seeding — pnpm is not "foreign", it is Node.
-  if (['npm', 'pnpm', 'yarn', 'bun'].includes(capability.runner)) 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;
-}
-
-/**
- * Build a manifest from a fingerprint. Pure, so the whole default surface is
- * testable without a filesystem.
- *
- * When `capability` is supplied, newly proposed gates the repo cannot run are dropped.
- * Gates the repo ALREADY declared are kept regardless: that is the repo's choice to
- * make, and quietly disarming a gate somebody declared on purpose is a worse surprise
- * than a visible one.
- */
 export function buildManifest({ root, stack = [], sha, version, existing = null, capability = null, surfaces = undefined, facts = [] }) {
-  const gates = defaultGates(stack, facts);
-  const limits = defaultLimits(stack);
+  const gates = defaultGates(stack, facts, root);
+  const limits = defaultLimits();
 
   // 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);
+  const planned = planGates(stack, capability, facts, root);
   // 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.
@@ -544,91 +186,11 @@ function withRepoKeys(existing, owned) {
  *
  * @returns {{file: string, status: string, gate: string, detail: string, remedy: string}[]}
  */
-export function unrunnableGates(manifest, capability) {
-  const declared = [
-    ...(manifest?.gates?.preCommit ?? []),
-    ...(manifest?.gates?.prePush ?? []),
-  ];
-  const findings = [];
-  const seen = new Set();
-  // `gates.cwd` names a directory a gate runs in, and a name that is not a declared
-  // gate is as much a landmine as one that cannot run: the entry is inert, the reader
-  // believes the gate runs in the package it names, and nothing anywhere says so. Same
-  // shape as the unknown-gate finding in the dispatcher, so both are repaired the same
-  // way.
-  const cwds = manifest?.gates?.cwd;
-  if (cwds && typeof cwds === 'object' && !Array.isArray(cwds)) {
-    for (const name of Object.keys(cwds).sort()) {
-      if (declared.includes(name)) continue;
-      findings.push({
-        file: MANIFEST,
-        status: 'unknown-gate-cwd',
-        gate: name,
-        detail: `gates.cwd names "${name}", which is not declared in gates.preCommit or gates.prePush, so it is never read`,
-        remedy: `declare "${name}" in gates.preCommit or gates.prePush, or remove gates.cwd["${name}"]`,
-      });
-    }
-  }
-  for (const name of declared) {
-    if (seen.has(name)) continue;
-    seen.add(name);
-    const gate = getGate(name);
-    const verdict = gateRunnable(gate, capability);
-    if (verdict.runnable) continue;
-    findings.push({
-      file: MANIFEST,
-      status: 'unrunnable',
-      gate: name,
-      detail: `declares gate "${name}", which this repo cannot run: ${verdict.why}`,
-      remedy: gateRemedy(gate, { existing: true, runner: capability.runner }),
-    });
-  }
-  return findings;
-}
-
-/** ADR-005: 400 is a review trigger, 1000 a hard ceiling. Generated files exempt. */
 function defaultLimits() {
   return { coverage: null, fileLines: { warn: 400, error: 1000 } };
 }
 
 /** ADR-006: coverage stays null. Set it only if the repo has a real numeric gate. */
-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) => 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 (signals.has(row.tag)) gates.preCommit.push(...row.preCommit);
-  }
-
-  // A repo with no recognised stack still gets a gate list, because a gate that
-  // runs nothing is indistinguishable from a gate that was never installed.
-  if (gates.preCommit.length === 0) gates.preCommit.push('format', 'lint');
-  if (gates.prePush.length === 0) gates.prePush.push('test');
-
-  return { preCommit: dedupe(gates.preCommit), prePush: dedupe(gates.prePush) };
-}
-
-function dedupe(list) {
-  return [...new Set(list)];
-}
 
 /**
  * A repo id is the directory name. Using it rather than a guessed field keeps
@@ -745,7 +307,9 @@ export function declaredShared(manifest) {
   return { level, rules };
 }
 
-export const GENERATED_KEYS = new Set(['$comment', 'projection']);
+// Derived from the table rather than restated: a key this tool writes is a `tool` key
+// marked generated, and a second list here is the drift this module exists to end.
+export const GENERATED_KEYS = GENERATED_KEYS_OF;
 
 // The sub-keys of `projection` this tool writes. `projection` is a generated key, but
 // not wholesale: the repository owns sub-keys this writer does not emit (`place` is the
@@ -892,20 +456,17 @@ export function manifestText(manifest) {
   return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 
-/** @returns {{manifest: object|null, exists: boolean, error: string|null}} */
+/**
+ * The manifest in the shape the callers already read, now answered by the one loader
+ * (review 0003 Q69). `error` is the unreadable-file case only: a manifest with a value
+ * the schema cannot use is still a manifest, and refusing it here would turn every
+ * reader into a second validator.
+ *
+ * @returns {Promise<{manifest: object|null, exists: boolean, error: string|null}>}
+ */
 export async function readManifest(root) {
-  const path = await manifestPath(root);
-  let text;
-  try {
-    text = await readFile(path, 'utf8');
-  } catch {
-    return { manifest: null, exists: false, error: null };
-  }
-  try {
-    return { manifest: JSON.parse(text), exists: true, error: null };
-  } catch (error) {
-    return { manifest: null, exists: true, error: `unparseable: ${error.message}` };
-  }
+  const { manifest, exists, problems } = await loadManifest(root);
+  return { manifest, exists, error: exists && manifest === null ? (problems[0] ?? 'unparseable') : null };
 }
 
 export async function writeManifest(root, manifest, journal = null) {
@@ -921,4 +482,4 @@ export async function writeManifest(root, manifest, journal = null) {
   if (journal) await journaledWriteFile(root, journal, fresh, manifestText(manifest));
   else await writeFile(fresh, manifestText(manifest));
   return fresh;
-}
+}

package/src/projection/mdc.mjs

@@ -29,6 +29,7 @@ import { fileURLToPath } from 'node:url';
 
 import { parse } from './markers.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
+import { parseFrontmatter as splitBlock, stripFrontmatter as stripBlock } from '../text/frontmatter.mjs';
 
 // ROOT is computed here rather than imported: project.mjs is the caller of every
 // function below, so importing it back would create a cycle for the sake of one
@@ -134,9 +135,8 @@ export async function loadMdcRules() {
  *  rather than skipped, because a silently-dropped substitution projects a rule
  *  containing a literal `{{placeholder}}`. */
 function parseSubstitutions(text) {
-  const m = /^---\n([\s\S]*?)\n---/.exec(text);
-  if (!m) return [];
-  const block = m[1];
+  const { front: block } = splitBlock(text);
+  if (block === null) return [];
   if (!/^simt-substitutions:/m.test(block)) return [];
 
   const out = [];
@@ -168,10 +168,10 @@ function parseSubstitutions(text) {
 }
 
 function parseFrontmatter(text) {
-  const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
-  if (!m) return {};
+  const { front } = splitBlock(text);
+  if (front === null) return {};
   const out = {};
-  for (const line of m[1].split('\n')) {
+  for (const line of front.split('\n')) {
     // `simt-substitutions:` opens a nested block this parser cannot represent, so
     // it and its list items are skipped here and read by parseSubstitutions.
     if (/^\s*-\s/.test(line)) continue;
@@ -201,8 +201,7 @@ function unquote(s) {
 }
 
 function stripFrontmatter(text) {
-  return text
-    .replace(/^---\n[\s\S]*?\n---\n*/, '')
+  return stripBlock(text)
     .replace(/^#\s+.*\n+/, '')
     .trim();
 }