simt-dev 0.0.0-stage → 0.1.1

package/docs/decisions/ADR-018-an-unset-hooks-path-is-not-an-absent-hook.md

@@ -0,0 +1,183 @@
+# An unset hooks path is not an absent hook
+
+Status: **accepted** · 2026-10-06
+
+Affects: `simt-dev hooks install`, `simt-dev hooks status`, `simt-dev compare`, `src/hooks/where.mjs`, `src/hooks/shim.mjs`
+
+## Context
+
+Phase 4 began by piloting `simt-dev init` on `simt-space`. The dry run was
+unremarkable. The defect appeared when I read what `hooks install` would actually
+do to that repository, which is something I had not done in any of the earlier
+phases.
+
+`simt-space` has a hand-written `.git/hooks/pre-commit` — 4088 bytes, with prose
+explaining why it deliberately does not run tests. `core.hooksPath` is unset.
+`simt-dev hooks status --root ../simt-space --json` reported:
+
+```json
+{ "hooksPath": null, "installed": [{ "event": "pre-commit", "present": false }],
+  "problems": ["core.hooksPath is (unset), expected .simt-hooks",
+               "pre-commit not installed"] }
+```
+
+and exited with `ok: true`. A live, working gate was reported as not installed.
+
+`hooks install` then did this, with no warning of any kind:
+
+```
+core.hooksPath  created  (unset) -> .simt-hooks
+CREATED   .simt-hooks/pre-commit
+CREATED   .simt-hooks/pre-push
+WROTE    shims and set core.hooksPath
+gates    preCommit = (none declared)
+         prePush   = (none declared)
+```
+
+Three things went wrong at once, and the first one is the load-bearing fact:
+
+1. **An unset `core.hooksPath` was read as "git runs no hooks".** It means the
+   opposite: git falls back to its default directory and runs whatever is in it.
+2. **The takeover guard only looked at `core.hooksPath`.** It existed to stop
+   simt-dev silently replacing routing somebody else had chosen — and it checked
+   only for a *configured* value. The most common way to have hooks is the one it
+   could not see.
+3. **The install created two shims that enforced nothing.** `simt-dev init` had
+   already said, in prose, that this repo declares no gate it can run and there is
+   nothing to install. `hooks install` disagreed, and in doing so replaced a
+   working gate with a gate that checks nothing.
+
+The consequence in a real adoption is worse than a misreport. A repo that adopts
+and then installs hooks gets, in place of its working formatter, two shims that
+fail closed because `@quazarmedia/simt-dev` is not yet a dependency. Every commit
+is blocked. The only exit is `--no-verify` — the exact spiral the dispatcher was
+built in step 8 to prevent.
+
+The same class of error sat under the two commands that already existed.
+`src/compare/hooksstate.mjs` was written as "the read half of what `hooks status`
+does inline", but `hooks status` never called it: it had its own `readHooksPath`,
+its own `describeShim` and its own `collectProblems`. Three copies of the same
+question, which is why fixing the shared one changed nothing visible.
+
+## Ruling
+
+1. **Ask git where hooks are, never infer it from whether config exists.**
+   `resolveHooksDir(root)` implements the two rules directly: `core.hooksPath`
+   when set (a relative value resolves against the top of the working tree, which
+   is what makes `simt-app`'s `hooks` work), otherwise `<git-common-dir>/hooks`.
+
+   `git rev-parse --git-path hooks` is the obvious shortcut and is unusable. It
+   returns `.git/hooks` in a normal repository, `hooks` in a linked worktree, and
+   **`./`** in a linked worktree with `core.hooksPath` unset — because a worktree's
+   `.git` is a file, not a directory. An implementation that trusted it would
+   enumerate a worktree's entire root as its hooks directory and report every file
+   in the repository as a hook.
+
+2. **A hook git runs and simt-dev did not write is a first-class fact.** It is
+   named in `hooks status` text and JSON, in `hooks install`'s refusal and its
+   post-install notes, and as a row-level `foreignHooks` field. Identity is decided
+   by content, never by name: a simt-dev shim is also called `pre-commit`, so only
+   the bytes can tell ours from somebody else's.
+
+3. **Taking over a foreign hook requires `--yes`, and the refusal names the hook.**
+   The existing guard was right about the principle and incomplete about the facts.
+   It now covers both a configured path and an unconfigured default directory.
+
+4. **A shim is installed only for an event that declares at least one gate, and
+   `install` refuses when no event does.** An empty-gate shim enforces nothing but
+   still displaces whatever was there, so installing one over a working hook is a
+   downgrade. `init` and `install` must not describe different tools.
+
+5. **In `compare`, a repo running its own hooks is a note, not a problem.** Notes
+   do not affect the exit code. "Not adopted yet" is the normal state of a
+   migration, and step 9 established — deliberately, after finding that a dashboard
+   which goes red for the normal state is a dashboard everybody ignores — that only
+   defects drive the exit code. Six of the sixteen repositories run their own hooks,
+   so putting this in `problems` would have made the entire estate red on day one.
+
+6. **A missing shim is only a defect when a gate needs it.** A repository that
+   declares no `preCommit` gates has no reason to want a `pre-commit` shim. A
+   repository with *no manifest* is a different case: we do not know what it wants,
+   so we cannot rule the shim out. Absence of knowledge is not a decision.
+
+7. **A foreign hook for an event this tool does not gate is chained, not stopped.**
+   `core.hooksPath` does not scope this tool to the events it cares about and leave
+   the rest to git; git reads *every* hook from the named directory and from nowhere
+   else. So the moment routing lands, `simt-app`'s `post-checkout`, `post-commit`
+   and `post-merge` — events this tool gates nothing about — stop running. Nothing
+   fails, nothing is logged, and the hook is still on disk looking intact: the
+   failure is indistinguishable from the hook having passed. Ruling 3's refusal
+   names the hook, but a refusal the operator accepts is not a chain.
+
+   `hooks install` therefore writes a second kind of shim for those events, which
+   runs the repository's own hook and forwards git's arguments to it. There is
+   nothing to enforce on an event this tool does not gate, so it does not run the
+   dispatcher at all. Git's arguments *are* forwarded here, unlike in the dispatcher
+   shim, because the program on the other end is the repository's hook and expects
+   them.
+
+   The target is written relative to the repository's top level wherever the hook
+   lives inside it, so a clone or a move does not silently stop resolving it. If the
+   hook is not there at all, the shim refuses and names the path — a hook that
+   silently stops running is the exact outcome this ruling exists to prevent.
+
+   A gate-type foreign hook is deliberately **not** chained — *when this repository
+   declares a gate for that event*. The dispatcher replaces the hook there by design, the
+   hook's real place is `gates.commands`, and its verdict belongs in the gate report next
+   to the others. Chaining it would run it *after* the gates had already passed, outside
+   anything the author sees.
+
+   "Does this tool gate it" is a fact about the manifest, not about the event vocabulary,
+   and reading it the second way cost `simt-app` its `pre-push`. That hook is git-lfs.
+   `pre-push` is an event this tool gates *in general*, so a vocabulary check displaced it
+   — and because `simt-app` declares no `pre-push` gate there is no shim for that event
+   either, so git would have found no `pre-push` hook at all. LFS objects would have
+   stopped being uploaded, with nothing to notice it: the same silent failure this ruling
+   exists to prevent, reached by fixing the wrong half of it. The test asks the manifest.
+
+   The install note says which of the two happened, because "stopped running" was wrong
+   about a carried hook and would have pushed an operator to restore a hook that was
+   already running for them.
+
+## Consequences
+
+`src/hooks/where.mjs` is new and is the single answer to "where are this repo's
+hooks". `hooksstate.mjs` and `hooks status` no longer hold separate
+implementations — the three duplicated functions in `hooks.mjs` are gone, and
+`hooksstatus` reads through the shared module.
+
+Two guard tests are recorded in `test/compare.test.mjs` because the JSON surface
+had already lost a field once: the `summary` block in `compare --json` was a
+hand-listed copy of `summarise()`'s output, and `withOwnHooks` reached the text
+render while silently vanishing from the machine surface. A copied list of names is
+a list that rots, so one test now asserts the two agree and another asserts every
+row carries `notes` and `foreignHooks` even when empty.
+
+Measured across the estate after the fix, six repositories run hooks simt-dev did
+not write — `simt-space` (4088 B), `simt-app` (four hooks), `simt-social` (two),
+`simt-social-api` (two), `simt-landing` (one), and the `.wt-wear-redesign`
+worktree (five, including the `git-lfs` `pre-push`). Every one of them would have
+been silently taken over.
+
+## Rejected
+
+- **Treat an unset `core.hooksPath` as "no hooks", and document it.** This is the
+  bug. The documentation would have been accurate about the code and wrong about
+  git.
+- **Ask the user before overwriting, and leave `hooks status` as it was.** The
+  question was never asked, because the tool did not know a hook existed. A guard
+  that cannot see the thing it guards is decoration.
+- **Move a foreign hook aside instead of blocking.** Blocking is right; the file is
+  left on disk untouched either way, so the outcome already is "move it aside".
+- **Chain every foreign hook, gate-type ones included.** Rejected when ruling 7 was
+  written, and the reason is the difference between a verdict and a side effect. A
+  `pre-commit` hook chained behind the dispatcher runs *after* the gates have already
+  passed, so its failure is reported by git as a hook failure with no gate output
+  above it — an author cannot tell which of the two things said no. The hook's real
+  place is `gates.commands`, where it runs as a gate and appears in the report next
+  to the others.
+- **Install the shims anyway and warn.** The gate list was empty. Warning about a
+  replacement that enforces less than what it replaces is the wrong direction.
+- **Put foreign hooks in `compare`'s `problems`.** Six of sixteen repositories, all
+  of them unadopted, on the day the dashboard is introduced.
+- **Use `git rev-parse --git-path hooks`.** Returns `./` for a linked worktree.

package/docs/decisions/ADR-019-a-declared-command-is-the-runner.md

@@ -0,0 +1,110 @@
+# A declared command is the runner; the remedy must be one the reader can take
+
+Status: **accepted** · 2026-10-07
+
+Affects: `simt-dev init`, `simt-dev check`, `simt-dev hooks status`, `simt-dev hooks run`,
+`src/hooks/capability.mjs`, `src/hooks/resolve.mjs`, `src/projection/manifest.mjs`
+
+## Context
+
+ADR-017 made `simt-dev init` declare only gates a repository can actually run, and it shipped
+green because the first adopter — `simt-social-media` — is a Node repository whose scripts
+and binaries are exactly what the filter understood. It was verified by running that
+repository's own tests.
+
+`simt-app`, the third pilot, is a Gradle repository. It has **no `package.json` at all**. The
+dry run dropped all five proposed gates, and the remedy for each one was an instruction the
+reader cannot follow. The output as it stood, before this record was written:
+
+```
+$ simt-dev init --root ../simt-app
+  dropped   gate test: no "test" script in package.json
+            remedy: add a "test" script to package.json, then re-run: simt-dev init --yes
+```
+
+Ruling 4 changes both lines. `simt-app` will never have a `package.json`. "Install prettier as
+a dev dependency" is equally impossible. The filter was right about the facts and wrong about
+what followed from them, and the reader's only honest reaction to that remedy is to stop
+trusting the next one.
+
+Then the repo declared what it does have, using the escape hatch the remedy for command gates
+had always advertised:
+
+```json
+"gates": { "preCommit": ["i18n-completeness"], "prePush": ["test"],
+           "commands": { "i18n-completeness": "scripts/check_string_translations.sh",
+                          "test": "./gradlew check" } }
+```
+
+and three surfaces answered three different things about it:
+
+- `simt-dev hooks run pre-commit` — **PASSED**, running the declared script.
+- `simt-dev hooks run pre-push` — would have demanded an npm script that does not exist,
+  because `resolveGate` only consulted `gates.commands` for gates of kind `command`.
+- `simt-dev check` — **UNRUNNABLE** on both, because `readCapability` never read
+  `simt-dev.json` at all and so always reported an empty command map.
+
+One manifest. Three answers. The one I would have shipped if I had only run `check`.
+
+## Rulings
+
+1. **A gate name is a requirement, not a mechanism.** The repository declares "prove `test`
+   somehow"; `gates.commands[test]` is how it says how. Once declared, that wins for **every**
+   gate kind — `script`, `staged` and `command` alike — because a repository naming its own
+   program is a more specific statement than any table this tool can ship.
+2. **`gates.commands` is part of what a repository can run.** `readCapability` reads
+   `simt-dev.json` alongside `package.json` and `node_modules/.bin`. This is the one
+   capability source that is a declaration rather than an observation, and that asymmetry is
+   the point: the only evidence that can prove a command gate is the declaration.
+3. **The dispatcher, `check` and `hooks status` read one manifest once and answer identically.**
+   Two surfaces must never disagree about what a gate will do; the disagreement is what made
+   this a defect rather than a rough edge.
+4. **A remedy names an action the reader can take.** Where npm is the runner, the npm remedy
+   stands. Where it demonstrably is not, the remedy is to name the program under
+   `gates.commands` — the same instruction already given for command gates.
+5. **An empty declared command is a failure, not a silent pass.** It would resolve to an empty
+   argv and report `PASSED` while proving nothing, which is the worst outcome a gate can have.
+6. **`'none'` is an answer; absent is not.** A capability that does not report its runner (one
+   built by hand, or by an older caller) is treated as npm. Claiming a repository has no
+   `package.json` on the strength of a missing field is a much worse guess than assuming it.
+7. **Runner detection reads files, and must know the difference.** The marker for Gradle is
+   the `gradlew` file. My first cut used `readdir` to test existence, which answers "no" for
+   every file (`ENOTDIR`) and classified every Gradle repository in the estate as having no
+   runner at all — a wrong answer from an evidence reader, which is worse than no answer
+   because the caller cannot tell them apart.
+
+## Consequences
+
+- `simt-app` declares `i18n-completeness: scripts/check_string_translations.sh` on
+  pre-commit — the gate its own hand-written pre-commit hook already runs — and
+  `test: ./gradlew check` on pre-push.
+- The `simt-social-media` and `simt-space` manifests are unaffected: they declare no commands.
+- A Node repository that wants to override a gate now can, without abandoning the gate name it
+  shares with every other repository. `gates.commands.format` is a supported thing to write.
+- `readCapability` reads one more file per invocation, and it reads it in a `try` that cannot
+  throw: a repository with no manifest simply has no declared commands.
+
+## Rejected
+
+- **Add a `gradle` gate kind, and a `python` one, and a `cargo` one.** Each would need its own
+  dispatcher branch, its own remedy, its own tests, and its own entry in `GATES`. One rule —
+  a declared command wins — covers every ecosystem including the next one, which is the reason
+  the `command` kind exists at all.
+- **Let the reader name the gate.** A repository could declare a gate called `gradle-check`
+  rather than `test`. Then `test` is dropped for lack of a script while a second, unrelated
+  gate appears, and the two estates of gate names stop being comparable.
+- **Guess the Gradle task.** Printing `./gradlew test` as the remedy for a Gradle repository
+  would be shorter and would be wrong in exactly the repositories where it is printed — plenty
+  of Gradle projects have no `test` task and a `spotlessCheck` that is not `spotlessFormat`.
+- **Treat an unreadable marker file as a runner.** A permission error is not evidence that a
+  repository runs Gradle; it is evidence that this tool cannot see. Absent is the safe reading.
+- **Leave `check` reporting the gate unrunnable and let `hooks run` be the truth.** Then the
+  gate a reader is told to fix is not the gate that fails, and the two disagree on the same
+  manifest — this defect, with the direction reversed.
+
+## Evidence
+
+`simt-app` is the first adopter with a non-npm runner and the first to declare a command for a
+gate that is not of kind `command`. Every earlier adopter was a Node repository, which is why
+ADR-017's own verification passed. The estate's three runners — npm, Gradle and Python — were
+all in the repository set the whole time; only the pilot order had not reached them.

package/docs/decisions/ADR-020-a-rule-is-written-per-surface-and-pointed-not-copied.md

@@ -0,0 +1,100 @@
+# A rule is written per surface, and pointed at — never copied
+
+Status: **accepted** · 2026-10-07
+
+Affects: `simt-dev init`, `simt-dev sync`, `simt-dev check`, `simt-dev compare`,
+`src/projection/surfaces.mjs`, `src/projection/project.mjs`, `src/compare/row.mjs`
+
+## Context
+
+`simt-dev` writes rules into a repository. Until this record it wrote them into **two** places:
+the `AGENTS.md` generated region, and `.cursor/rules/*.mdc`. So the estate's three
+always-on process rules — `test-gate`, `intake-questions`, `preview-postflight` — reached
+**Cursor users and nobody else**. Every other editor got whatever happened to be in
+`AGENTS.md`, by the accident that those editors read it.
+
+That accident is not support. Claude Code reads `CLAUDE.md` by default and only falls back to
+`AGENTS.md` when no `CLAUDE.md` exists anywhere above the working directory. Copilot's editor
+and code-review surfaces read `.github/copilot-instructions.md` and
+`.github/instructions/*.instructions.md`, which this tool wrote nowhere — while its conflict
+scanner already *scanned* `.github/instructions/`, because a detector that reads a surface is
+half a promise to write it. Antigravity's native surface is `.agents/rules/*.md` with a
+required `trigger:` key it will silently discard if it does not recognise. So the three
+repositories in the pilot had three different answers to "what rules apply here", and only
+one of the three was written down.
+
+The conventions were not guessed. Each was read from that vendor's own documentation, and
+`src/projection/surfaces.mjs` records the document beside every row.
+
+## Rulings
+
+1. **A surface is named data.** Every editor is a row: its id, its label, the readers it
+   serves, its rule-file path template, its frontmatter, and **the document it was verified
+   against**. A row that cannot name that document does not belong in the table.
+
+2. **A pointer is not a copy.** `CLAUDE.md` and `GEMINI.md` are symlinks to `AGENTS.md`.
+   Both vendors document the symlink. The estate contains a byte-identical `CLAUDE.md` and
+   `AGENTS.md` pair, which is the one true content duplicate in the corpus and the reason this
+   tool exists. DeepSeek's harness documents the failure from the other side: candidates that
+   are byte-identical after trimming collapse, so a symlink renders once — while **a real copy
+   that has drifted loads in full alongside** `AGENTS.md`. A copy is not a second copy of the
+   rule; it is a second rule that nobody reviews.
+
+3. **Per-rule files are generated, not linked.** `rulePath()` writes the same body to each
+   surface under that surface's own naming. Symlink support is documented for
+   `.claude/rules/`; writing a symlink into `.agents/rules/` or `.github/instructions/` would
+   be an unverified guess carrying a mode bit. A machine-written file derived from one
+   canonical source and verified by `simt-dev check` is a build output, not duplication —
+   nobody can hand-edit one and survive a sync, which is the test the estate's own review
+   agent applies to duplicated policy text.
+
+4. **An always-on rule emits no scoping frontmatter.** Claude documents that a rule file with
+   no `paths:` loads eagerly at session start, and carries a documented parser defect: quoted
+   values and YAML sequences in `paths:` silently fail to lazy-load, and its own documented
+   examples are not valid YAML. Emitting a scope we do not need, on an editor where a
+   malformed scope fails silently, buys nothing.
+
+5. **The default is the global standard, and the set is always reported.** Every rule surface
+   unless the repository narrows it with `"surfaces"` in `simt-dev.json`; `--surfaces` wins
+   over the manifest. An empty list is a real choice meaning `AGENTS.md` only, not an
+   accident. Every command prints the set and **where it came from** — an invisible
+   configuration is one nobody can debug, which is the same ruling ADR-014 made about the
+   workspace.
+
+6. **A surface row states its own failure mode.** An unrecognised frontmatter key is inert;
+   an unrecognised *value* can make an editor discard the rule with no error. So each row
+   carries `documentedKeys`, and `undocumentedKeys()` — used by the test suite and by any
+   consumer that wants the same guarantee — fails when the table emits a key its own vendor
+   does not document.
+
+## Consequences
+
+`simt-dev init`, `sync` and `check` write and verify up to four rule files per rule plus two
+pointers. `compare` reports `rules  N/M current` per repository, because a repository with a
+current `AGENTS.md` and three stale rule files is now a state that can exist, and reporting
+only the `AGENTS.md` finding would hide it.
+
+A missing pointer is **not** a failing check. A repository that has never been adopted has no
+`CLAUDE.md` and no `simt-dev.json`, and reddening every commit for that is the adoption
+problem, not a defect — the same reasoning ADR-018 applied to a repository's own hooks. A
+*mispointed* pointer is likewise not failing; a pointer simt-dev did not write, which means a
+human's `CLAUDE.md` is in the way, **is** reported, because overwriting it silently would
+destroy prose nobody backed up.
+
+## Rejected
+
+- **Keep two surfaces and call it support.** The rules a reader most needs are the ones that
+  never reached three of the four editors that read this repository's rules.
+- **Copy `AGENTS.md` to `CLAUDE.md`.** The one true duplicate in the corpus. DeepSeek's
+  harness loads a drifted copy in full; Claude's own docs steer away from it.
+- **Symlink every rule file to a canonical directory.** Symlink support is documented only for
+  `.claude/rules/`. A symlink into `.agents/rules/` or `.github/instructions/` would be a
+  guess with a mode bit attached.
+- **Emit `paths:`/`globs:` on an always-on rule** and rely on it. Claude's parser defect makes
+  it a silent-failure surface for zero benefit; Antigravity discards a rule whose `trigger`
+  it does not recognise.
+- **Guessing Antigravity's or DeepSeek's convention and moving on.** Both were read from the
+  vendors' documentation before anything was written, and the document is recorded per row so
+  a future maintainer knows what a claim rests on.
+- **Making the default a single surface** because it is the one most repositories use. A
+  default that leaves three editors uninstructed is the defect this record exists to close.

package/docs/decisions/ADR-021-one-surface-per-repo.md

@@ -0,0 +1,94 @@
+# ADR-021 — One surface per repo, chosen or defaulted
+
+Status: accepted · 2026-10-07 · ruling 3 superseded by ADR-046
+**Affects:** `simt-dev init`, `sync`, `check`, `compare`, `skills install`, `src/projection/surfaces.mjs`, `src/projection/rules.mjs`
+
+> **Ruling 3 superseded by ADR-046.** It rested on a factual claim about Cursor — that a Cursor
+> reader getting `.mdc` files "does not serve them", i.e. that Cursor cannot read `AGENTS.md` — and
+> Cursor's own documentation says it can. Five repositories were loading 28,101 bytes of rule text
+> twice. The claim had been sitting on the wrong row of simt-dev's own surface table all along.
+> Every other ruling here stands; ruling 6 in particular is what makes ADR-046's orphan handling a
+> note rather than a deletion.
+
+## Context
+
+ADR-020 answered a question that had been answered wrongly for months. `simt-dev init`
+wrote `AGENTS.md` and `.cursor/rules/*.mdc` and reported that it supported the
+estate's editors. It did not: the three always-on process rules lived only in a
+directory only Cursor reads, so a Claude Code, Copilot or Antigravity user received
+the core and stack rules and none of the process rules.
+
+ADR-020 fixed that by writing one file per verified editor — four rule directories
+and two pointer symlinks. That was correct and it was too much. A repo whose team
+lives in one editor now acquires three rule directories and two symlinks it will
+never open, every rule change lands four times, and `check` must be told which
+surface to ask about or it answers a different question from the one `sync` was
+asked.
+
+"Support every known editor" is satisfied by knowing how to write each one and
+writing the one that was asked for. It is not satisfied by writing them all.
+
+## Rulings
+
+1. **One surface per repo by default; a repo may name another.** `--surfaces` takes a
+   comma-separated list, so one, several, or none are all reachable. An empty list is
+   a real choice and means the primary region and nothing else.
+2. **The default is opencode**, because it is the agent this tool is developed
+   against and its paths — `AGENTS.md` and `.agents/skills/` — are already this
+   workspace's. It is also the least private choice available: seven of the eight
+   readers on that row read `AGENTS.md` natively, so the default file is the one most
+   editors already read even when they were not asked for it.
+3. **A folding surface carries its rules inside the region.** opencode documents no
+   per-rule directory, so its surface folds every rule into the one generated region.
+   Folding is `some`, not `all`: a repo that also opts into Cursor still folds, because
+   an opencode reader's only channel is `AGENTS.md` and a Cursor reader getting `.mdc`
+   files does not serve them.
+4. **Skills follow the same rule.** One canonical skills directory per repo, `.agents/skills`,
+   which opencode, Claude Code and Antigravity all document and which the estate
+   already uses. Not four copies of every skill.
+5. **The choice is always visible.** Every command prints the surface set and its
+   origin — flag, manifest, or global standard — because an invisible configuration is
+   one nobody can debug (ADR-014).
+6. **A written file is not removed when a surface is dropped.** Narrowing the surface
+   set stops new files appearing; `sync` never deletes a file it once generated,
+   because a deletion is not something a projection should do silently. Removing them
+   is a human decision with a visible diff.
+7. **A pointer belongs to the surface that needs it.** ADR-020 wrote `CLAUDE.md` and
+   `GEMINI.md` unconditionally, so narrowing the surface set left both behind — the
+   same over-writing ruling 1 exists to stop, one file down. Each pointer now names the
+   surface that requires it (`claude-md` → `claude`, `gemini-md` → `antigravity`) and
+   is planned only when that surface was selected. On the default surface simt-dev
+   writes exactly one file.
+
+   *Added after ADR-021 was first implemented: this was found by running the command
+   against the four adopted repos rather than by reading it, which is the third time
+   that has been the only way to find anything.*
+
+## Consequences
+
+- **Which surface a repo already has is the strongest signal of which it wants.**
+  Measured across the four pilot repos: three track `.cursor/rules/*.mdc` (3, 3 and 12
+  files) and one tracks no rules layer at all. Those three adopt `opencode,cursor`
+  because they already use Cursor; the fourth takes the bare default. A repo's own
+  tracked files answer this better than any default could.
+
+- `simt-dev init` on a fresh repo writes one file: `AGENTS.md`.
+- `check` and `sync` must be given the same surfaces or they ask different questions.
+  The manifest records the choice, which is why `init` and `upgrade` write it.
+- The four repos adopted under ADR-020 carry rule files for surfaces they did not ask
+  for. Narrowing stops the next sync writing them; removing the existing ones is
+  Phase 6 work with a visible diff.
+
+## Rejected
+
+- **Write every verified surface by default.** Rejected: gives a single-editor repo
+  three unread directories, and makes every rule change a four-file change.
+- **Make the default no surface at all.** Rejected: that is what the tool did before
+  ADR-020 and it is how three editors received no process rules.
+- **Delete generated files for a dropped surface automatically.** Rejected: a
+  projection that deletes files is a projection that can lose work, and it does it
+  without a diff anyone reads.
+- **One surface per rule, chosen by rule.** Rejected: the same rule then exists in two
+  places, which is the estate's original problem restated.
+- **Ask on every run.** Rejected: a prompt is a hang for an agent, and the default
+  exists precisely so nothing has to be asked.

package/docs/decisions/ADR-022-a-key-simt-dev-reads-is-prefixed.md

@@ -0,0 +1,98 @@
+# ADR-022 — A key simt-dev reads is prefixed `simt-`
+
+Status: accepted · 2026-10-08
+**Affects:** `rules/*.md`, `rules/mdc/*.mdc`, `src/projection/mdc.mjs`, `src/projection/rules.mjs`, `test/shipped.test.mjs`. Supersedes the *spelling* of the keys named in ADR-013 and ADR-016; their rulings stand.
+
+## Context
+
+A canonical `.mdc` frontmatter block carries two vocabularies in one place:
+
+```
+id: test-gate
+target: .cursor/rules/test-gate.mdc
+description: ...
+alwaysApply: true
+applies: always
+```
+
+`description` and `alwaysApply` are Cursor's, cited in the `cursor` row of
+`src/projection/surfaces.mjs` and re-emitted per surface. `id`, `target`, `applies`,
+`optIn` and `substitutions` are simt-dev's own and appear in no vendor's
+documentation. In the file above, nothing says which is which: `alwaysApply: true` and
+`applies: always` sit four lines apart, both read as "always", and both are consumed by
+something. The question was asked of this repository and could only be answered by
+reading the source rather than the file.
+
+That is a legibility failure with teeth behind it. ADR-016 records finding S11: a rule
+shipped, was tested for its presence on disk, and reached no repository, because
+`applies` was absent from its frontmatter. A missing simt-owned key is silent. A bare
+key that looks like the key beside it is one typo away from the same silence, and this
+block is precisely where a reader editing one key is looking at the other.
+
+The prefix does not exist to make the files tidy. It exists so that a bare key is
+either an editor's key or a defect, and never a third thing.
+
+## Rulings
+
+1. **Every key simt-dev reads out of a canonical rule file carries `simt-`.**
+   `simt-id`, `simt-target`, `simt-title`, `simt-applies`, `simt-opt-in`,
+   `simt-substitutions`, `simt-fallback`.
+
+   | was | is |
+   |---|---|
+   | `id`, `target`, `title` (`.mdc`) | `simt-id`, `simt-target`, `simt-title` |
+   | `applies`, `optIn`, `substitutions` (`.mdc`) | `simt-applies`, `simt-opt-in`, `simt-substitutions` |
+   | `id`, `title`, `applies`, `fallback` (`rules/*.md`, `.simt-dev/profiles/`) | `simt-id`, `simt-title`, `simt-applies`, `simt-fallback` |
+
+2. **An editor's key keeps the vendor's spelling, unprefixed.** `description` and
+   `alwaysApply` are the only two keys in the estate with two owners: simt-dev reads
+   them and re-emits them mapped per surface (`alwaysApply` becomes Antigravity's
+   `trigger: always_on`). Prefixing them would be a lie in both directions — Cursor
+   would ignore `simt-alwaysApply`, and the projector would have to strip the prefix
+   before emitting. A key is prefixed when this tool is its only reader.
+
+3. **An unrecognised key is a defect, not an ignored line.** `applies:` in a file that
+   should say `simt-applies:` reports as a problem naming the prefixed spelling.
+   This is the ruling that turns the prefix from a convention into an invariant: the
+   failure mode ADR-016 hit is now loud, and loud before the rule reaches nobody.
+
+4. **The prefix binds settings read from files, not identifiers in code.** `rule.applies`
+   is still `rule.applies` in `src/`. Renaming the property would satisfy the sentence
+   and change nothing a reader of a rule file sees, which is the only reader the prefix
+   is for.
+
+5. **Inside `simt-substitutions:` the keys stay `key`, `default` and `describe`.** The
+   parent already namespaces them; `simt-key` reads as though the block were not there.
+
+6. **Out of scope, deliberately: `simt-dev.json` and `graph/skills.graph.json`.** Both
+   are namespaced by filename, neither contains a key any editor or agent reads, and
+   both are read by this tool's own commands rather than by a person opening a rule
+   file. The receiving repo's manifest is the one file a human edits by hand — to
+   declare a gate command or a substitution — and `simt-gates` there is noise in the
+   place noise costs the most.
+
+## Consequences
+
+- **No receiving repository is affected.** These keys are stripped before projection:
+  `.md` frontmatter is dropped by `stripFrontmatter`, and a projected `.mdc` gets
+  frontmatter rebuilt from the surface row (`description` + `alwaysApply`) or preserves
+  whatever an adopted file already had, verbatim and unparsed. The change is
+  confined to the files in this repository, which is why touching shipped rule text is
+  cheap here and expensive in `rules/core.md`'s prose.
+- A rule file that still says `applies:` now fails `check` with the prefixed spelling in
+  the message. That is the intended break: it fails at the file, loudly, on first run.
+- ADR-013 and ADR-016 name the old spellings in their examples. They are left verbatim
+  — they are the record of what was ruled — and this record is the lookup from the old
+  spelling to the new one.
+- `rules list` keeps an `applies` column. It labels a value, not a key, and the value
+  vocabulary (`always`, a tag list) is unchanged.
+
+## Rejected
+
+- **Prefix the manifest keys too.** Rejected: `simt-dev.json` is already namespaced by
+  filename, and the keys a person edits by hand are the ones a prefix would obscure.
+- **Prefix in code as well, for symmetry.** Rejected under ruling 4: it is a rename of
+  variables that satisfies the wording and defeats the purpose.
+- **Accept both spellings for one release.** Rejected: a key that may be written two
+  ways is exactly the ambiguity this record exists to remove, and the failure it hides
+  is the unreachable rule ADR-016 already shipped once.