simt-dev 0.1.1 → 0.2.1

package/docs/decisions/ADR-058-one-tool-three-channels-and-the-order-is-forced.md

@@ -0,0 +1,148 @@
+# One tool, three channels, and the order is forced
+
+Status: **accepted** · 2026-10-11
+
+Affects: `pyproject.toml`, `python/simt_dev/`, `Formula/simt-dev.rb`,
+`.github/workflows/publish.yml`, `scripts/release-formula.mjs`,
+`scripts/verify-wheel.mjs`, `test/packaging.test.mjs`
+
+## Context
+
+simt-dev is a Node program. It is also a *repository* tool: somebody adopting a
+repository runs `simt init` inside it, and the places people run that from are
+not all Node projects. A python developer in a repository that has no
+`package.json` has no reason to install a package manager to get a command that
+adopts their repository, and a Homebrew user has no reason to install Node to
+install a tool that needs Node.
+
+So the tool is published to three channels:
+
+| Channel | What it installs |
+| --- | --- |
+| npm | a tarball of `.mjs` files |
+| PyPI | a wheel carrying those same files, plus a `simt` entry point |
+| Homebrew | a formula that downloads the npm tarball at install time |
+
+The design constraint that decided all of it: the tool has **zero runtime
+dependencies and no build step**. The whole thing is ~1.3 MB of text. That makes
+the "packaging for a second language" problem a *copying* problem rather than a
+build one, and copying is a problem with a right answer.
+
+## Ruling
+
+1. **The Python wheel carries the tool's own source, byte for byte.** `files` in
+   `package.json` and `force-include` in `pyproject.toml` name the same paths,
+   and `scripts/verify-wheel.mjs` builds both artefacts and hashes every file in
+   both, failing the release when a single byte differs.
+
+   The wheel is not a wrapper around `npm install`. A wrapper would fetch code
+   at install time - unpinned, unsigned by anything the installer can check, and
+   absent the moment somebody runs `pip install` on a train.
+
+2. **The version is one number, read rather than written.**
+   `pyproject.toml` declares `dynamic = ["version"]` and reads it from
+   `package.json` with a regex. A second literal would drift, and the drift
+   would be invisible until somebody ran `pip show` beside `simt --version` and
+   got two answers about which release they are running.
+
+3. **The Python launcher is standard library only, and has no required
+   dependencies.** The `[node]` extra is optional and imports `nodejs_wheel`
+   *inside a `try`, at the point of use* - never at module level - so the
+   default install cannot fail on a package it never asked for.
+
+   ADR-012 rules out runtime dependencies for the npm package. The reasoning
+   transfers without modification: a dependency is a runtime this package cannot
+   verify and its owner cannot patch, and this package exists to be the thing
+   people run in a repository rather than the thing they have to curate.
+
+4. **`simt` is the one command, on every channel.** `bin` in `package.json` and
+   `[project.scripts]` in `pyproject.toml` are asserted equal, and the formula's
+   `test do` block runs it. A second name under the package name would be a
+   convenience that forks the documentation the first time somebody documents
+   one channel and not the other.
+
+5. **Homebrew installs the npm tarball, and does not use `std_npm_args`.**
+   `depends_on "node"` declares the runtime; the entry point's shebang is
+   rewritten to that node rather than left at `#!/usr/bin/env node`, so the
+   command works from a cron job and from a shell that has moved node out of
+   the way, both of which look identical to a broken install.
+
+   `std_npm_args` invokes npm at build time, which needs the registry at build
+   time. This package has nothing to install, so that would add a network fetch
+   to installing the one thing in the estate that provably needs none.
+
+6. **`Formula/simt-dev.rb` is the source of truth, and `scripts/release-formula.mjs`
+   patches two lines in it.** It does not regenerate the formula from a
+   template: a template would mean the bytes a reader sees in this repository
+   are not the bytes a tap serves, which is the defect ADR-023 ruled out for the
+   gate file. The two lines are matched by content, not by line number, because
+   a line number would make the formula a file that cannot be edited - adding a
+   comment above the `sha256` line would silently write the checksum to the
+   wrong place.
+
+7. **The npm version must be live before `publish-pypi` and `publish-brew`
+   succeed, and both jobs say so when it is not.** The order is not a
+   preference. Homebrew downloads from the npm registry at install time, so a
+   formula naming a version that is still in npm's staging area installs a
+   404 - on somebody else's machine, at a tap, from a release this workflow
+   already declared done.
+
+   Those two jobs are the ones a maintainer runs again after
+   `npm stage approve`. "Re-run failed jobs" carries the tag context, which a
+   `workflow_dispatch` does not: on a dispatch, `github.ref_name` is the branch,
+   and the version guard would compare a tag against a branch.
+
+## Consequences
+
+The invariants split in two, and the split is deliberate.
+
+`test/packaging.test.mjs` holds the **static** ones: that `files` and
+`force-include` name the same paths, that the version is not written twice, that
+the command is one name, that the launcher imports nothing outside the standard
+library, that no second build system sits at the repository root. Every one of
+those is checkable from this checkout with no network and no interpreter, which
+is what lets it run in `npm test`.
+
+`scripts/verify-wheel.mjs` holds the one that is not: that the paths, once
+built, contain the same bytes. It runs in the release workflow, where a Python
+and a registry are available by construction.
+
+That split is ADR-031 applied. A test that needed `pip` would not run for the
+next person who clones this repository, and would run differently on the
+machine that wrote it - which is the failure that suite is about.
+
+Two findings from building it are recorded because they are the kind that only
+appear when a check is real:
+
+- The first run of `verify-wheel.mjs` reported `LICENSE` and `README.md` as
+  differences. They are not defects: npm adds both to every tarball, and the
+  wheel carries them as *distribution metadata* rather than as files. The
+  comparison is now scoped to what `files` names, which is the content the tool
+  reads.
+- The first run of that same comparison reported every one of `bin`, `src`,
+  `graph` and `rules` as missing from both, because `files` names **directories**
+  and npm includes them recursively. The expansion happens in the script now,
+  with the reason stated where the code is.
+
+The check was also tampered with deliberately - a wheel-only `README.md` was
+injected into `force-include` and it failed - because a parity check that has
+never failed is not evidence that it works.
+
+## Rejected
+
+- **A Python wrapper that runs `npm install -g simt-dev` on first use.** This is
+  what the unofficial `pyright` package does, and it has the properties it is
+  reputed to have: a download on first run, unpinned, uncacheable, and a failure
+  mode that reads as a broken package rather than as a missing runtime.
+- **Requiring node, with no bundled fallback.** The reader who installs from
+  PyPI is frequently the reader with no node, which is the whole reason the
+  channel exists. The failure message therefore names the `[node]` extra first,
+  because it is the one remedy that is the same command on every platform.
+- **Guessing where node is.** A hardcoded list of `/opt/homebrew/bin/node`,
+  `/usr/local/bin/node` and `~/.nvm/...` is three guesses and a surprise: it
+  prefers a guess over the reader's own `PATH`, and it is already out of date
+  for anyone who installs node differently. `shutil.which` asks the question
+  instead of answering it.
+- **`std_npm_args`.** See ruling 5.
+- **Publishing all three channels simultaneously.** Rejected by the ordering in
+  ruling 7 - Homebrew cannot name a version npm has not released.

package/docs/decisions/ADR-059-the-version-a-repository-runs-is-the-one-it-pinned.md

@@ -0,0 +1,75 @@
+# ADR-059 — The version a repository runs is the one it pinned, and the gate refuses otherwise
+
+Status: **accepted** · 2026-10-12 · affects all repos
+
+## Context
+
+ADR-010 ruled that a tool which is genuinely not a project dependency may be invoked directly,
+**provided its version is pinned**. For a repository with a `package.json`, simt-dev is that
+dependency, and npm does the pinning: it installs the version in `package.json` into
+`node_modules`, and a stale copy is a stale lockfile that `npm ci` reproduces.
+
+For a repository **without** npm — a Gradle build, a Connect IQ project — there is no
+`node_modules` to pin in. simt-dev is a global install, and nothing pins it. The version on
+`PATH` is whatever the last `npm i -g` left there, and it can be anything. The gate that runs
+on commit is the one in that binary. If it is not the version the repository adopted, the gate
+that runs locally is not the one CI runs: a green tick from a check that ran the wrong version
+is the one outcome worse than a red build, because it is a pass that never happened.
+
+The same gap sat in the remedy. The shim and the consumer workflow assumed npm everywhere —
+`npm i -D simt-dev@<v>` and `npm ci`. In a Gradle repository that command installs into a
+`package.json` the repository will never have, so the remedy cannot succeed and the CI step
+cannot start. The install and the remedy each needed to know the kind of repository they were
+in, and neither did.
+
+## Ruling
+
+1. **The manifest records the version a repository adopted.** `projection` carries
+   `version` alongside the existing `simtDevSha`, written at adoption and refreshed by
+   `upgrade`. A node_modules copy is pinned by npm itself, so this field matters only where
+   npm is not the pin — but it is written everywhere, because a manifest that records the
+   version in one shape of repository and not another is two manifests.
+
+2. **The gate compares the running binary against that pin, and refuses on a mismatch.** The
+   comparison is in the dispatcher (a failed `version` gate) and in `check` (a blocking
+   finding), not in the shim's rendered bytes: the dispatcher is where every gate already runs,
+   and a comparison duplicated into bytes a formatter might rewrite would drift from the one
+   that decides. It is placed after the empty-gate check on purpose — a repository that declares
+   no gate has nothing the version could get wrong, and failing it would block commits in repos
+   that deliberately declare none.
+
+3. **The install and the remedy are per kind.** Where a `package.json` exists, simt-dev is pinned
+   as a devDependency and the remedy is `npm i -D simt-dev@<v>`. Where there is no npm, it is a
+   pinned global install and the remedy is `npm i -g simt-dev@<v>` (or `export SIMT_DEV_BIN=…`).
+   The consumer CI workflow makes the same choice by kind — `npm ci` where the package is a
+   declared dependency, the pinned global install otherwise — so the gate that runs in CI is the
+   one the machine remedy names, and a check cannot pass in one place and fail to start in the
+   other.
+
+## Consequences
+
+- A stale global binary can no longer produce a green tick from a check that ran a different gate
+  than CI does. The mismatch is a refusal with the one command that fixes it, and the remedy and
+  the CI step agree on which version to install.
+- A repository adopted before the field existed — a manifest with `simtDevSha` but no
+  `projection.version` — is **skipped, not failed**. There is nothing to compare against, and
+  failing every pre-0.2 repository the moment this check ships would turn the gate red for a
+  reason it cannot fix. `compare` reports that missing field as a stale manifest (ADR-045's
+  defect from the far side), so it is visible and repairable rather than silently absent.
+- The version a repository runs is now an invariant the gate enforces, not a comment: the pin in
+  the manifest and the binary on `PATH` must agree, or the commit does not happen.
+
+## Rejected
+
+- **Shell out to `simt --version` in the shim.** The dispatcher runs from the binary that
+  resolved it, so reading the running package's version is the same answer without a subprocess,
+  and it is correct whether the binary came from `node_modules`, a global install, or a source
+  checkout. A subprocess would answer only for the binary that started it.
+- **Fail a repository with no recorded pin.** There is nothing to compare against; it would make
+  every pre-0.2 repository red on the day this ships, for a mismatch nobody can resolve until
+  they re-adopt. The missing pin is reported as drift, which is the repairable form of the same
+  fact.
+- **Put the check only in the shim's rendered bytes.** The dispatcher is where every gate runs and
+  where `check` already lives, so the comparison belongs in one place. Rendered bytes are read by
+  a formatter and a reviewer; a control that lives in both is two copies of one question, which
+  is the shape this record's siblings keep finding drifting.

package/docs/decisions/ADR-060-a-repository-with-nothing-to-run-is-adopted-and-says-so.md

@@ -0,0 +1,131 @@
+# ADR-060 — A repository with nothing to run is adopted and says so, and a gate is verified where it runs
+
+Status: **accepted** · 2026-10-12 · filed as S36
+**Affects:** `hooks install`, `compare`, the adoption criterion in review 0002
+
+## Context
+
+Review 0002 defined adoption as eight things a repository must have, and gave the estate
+roll-out an acceptance criterion: every repository current, every repository routed, no
+unrunnable gate, and a green CI run in every repository that has CI. Fourteen repositories
+were in scope.
+
+Three of them cannot satisfy the second of those, and the row contradicted itself about it.
+The runbook's own step 4, for one of the three, reads: *"none (no runner). Record that in
+the manifest rather than invent one."* That is an instruction not to route it. The
+acceptance criterion then requires that it be routed. One of the two is wrong, and the row
+could not be closed without settling which.
+
+This stopped being hypothetical when the roll-out ran. The three are:
+
+- **A Gradle module consumed as a submodule.** It has no wrapper of its own — the two
+  repositories that embed it own that — so `./gradlew` cannot be run from it. Its
+  `package.json` declares no scripts at all; it exists to carry one devDependency.
+- **A repository with no `package.json`.** No runner, no scripts, nothing to probe.
+- **A static site with no gate and its own hook.** No `format:check` and no `test` script to
+  declare a gate from, and a Lighthouse pre-push in `.githooks/` that routing would displace.
+
+Each is ungated for a reason that was checked rather than assumed, and each records that
+reason in its own commit message.
+
+ADR-017 already settled the principle in one direction: a gate is declared only if the
+repository can run it. This record settles the other, which fourteen repositories of real
+use never exercised — what a repository that can run nothing looks like once it has adopted
+the tool.
+
+A second thing surfaced at the same moment, and it is not a repository's fault. The roll-out
+pushed to fourteen repositories and GitHub Actions executed no steps: every run completed
+with `failure`, zero steps, and no logs — including a pre-existing lint-and-test workflow
+whose body this work never touched. Actions reports `enabled: true` on all eight
+repositories; the organisation-level setting needs `admin:org` and could not be read. The
+workflow files parse, and the same workflows have run before. The jobs are not starting.
+
+## Ruling
+
+**One. A repository that cannot run a gate is adopted when it says so, and routing is not
+required of it.** `hooksComplete` is not the measure of adoption, and "every repository
+routed" was never achievable. The three carry the evidence in the manifest and in their own
+commit messages: what is missing, and why. That is a stronger artefact than a shim that
+runs nothing — which is what forcing them would have produced, and which the runbook already
+forbade inventing.
+
+**Two. A gate must be runnable, and a shim must not be installed over one that is working.**
+This is ADR-018 as amended, restated because the roll-out made it concrete. The static site's
+pre-push keeps running in `.githooks/` precisely because its manifest declares no `prePush`
+gate and therefore nothing displaces it. Routing a repository that enforces nothing is not
+a smaller change than routing one that does: `core.hooksPath` moves, git reads every hook
+from the one directory, and the gain is zero.
+
+**Three. "Green CI" is verified where CI runs, and is not a property of a repository when it
+does not.** The clause is replaced by two that can be answered: the workflow file is present
+and valid in every repository that has one, and the gate runs locally. Whether GitHub
+executes those workflows is a fact about the account, and a gate that reports a property it
+cannot observe is ADR-039's defect — the step that cannot fail is the one nobody reads.
+
+**Four. The estate's CI runs on pull requests, and delivery does not.** A check that fires on
+a timer is not evidence about a change: by the time it reports, the commit is days old and
+nobody is waiting on it. That is why the weekly runs were removed rather than de-scheduled.
+It is also why the two API-contract workflows were split out of the `ci.yml` files they
+shared: republishing to the edge needs a credential a fork does not have, so it fires on
+merge to `main`, and one workflow cannot carry two triggers once its checks and its delivery
+need different ones. The template moved in one commit and the estate followed the template,
+which is the only way to move fourteen repositories that do not own the file.
+
+**Five. The measure is `check`, and `compare` is what makes it visible at estate scale.**
+ADR-045 made `compare` count a defect it had been hiding. This cycle found the same row
+reporting every repository current while `check` exited non-zero in all of them. Both are now
+driven at one fixture and compared — a parity test, because two copies of one question, each
+asserted separately, is how they drift. That is ADR-052's shape, reached from a different
+direction.
+
+## Consequences
+
+- **The roll-out closes with eleven of fourteen routed, and the three exceptions named in
+  three commit messages** rather than in a dashboard. An audit trail beats a count.
+- **If one of the three gains something to run, it routes in one command** and nothing else
+  about it changes. This is not a permanent exemption; it is the current answer to "can this
+  repository enforce anything", and `compare` re-reads it every run.
+- **The result is stronger than the row asked for.** Every repository's gate exits zero,
+  every manifest records a released version, no rule is loaded twice, no declared gate is
+  unrunnable, and no region sits past a harness's read limit. Three of those were false when
+  the row was written.
+- **The CI clause is recorded as unverified, not met.** Nothing in a repository can make
+  GitHub execute a workflow, and a claim about a green build nobody has seen is the thing
+  this repository's own rules exist to prevent. Re-run the query and the clause comes back.
+
+## Rejected
+
+- **Route the three anyway, with an empty gate list.** `hooks install` already refuses —
+  it prints *"declares no gate it can run, so there is nothing to enforce."* Overriding it
+  means a shim on every commit that dispatches, reads a manifest, and exits having enforced
+  nothing. The cost is a repository that believes it is gated.
+- **Declare a gate to satisfy the count.** That needs a name for a check that does not
+  exist. The Connect IQ repository has the shape of this: seven scripts in `scripts/` that
+  all run, and a gate vocabulary with no name for five of them. Two were declared, where the
+  name matched, and the other five stay manual rather than borrow `test` or `lint` — a gate
+  whose printed name misdescribes the command it runs teaches a reader not to trust the
+  other seven.
+- **Keep the weekly runs because they are "just checks".** They were the most expensive
+  thing in the estate — the Android one booted a headless emulator every Saturday — and the
+  least timely. Where the checks were worth keeping they moved to the pull request that
+  changes the code, and one repository's own test suite refused the push that deleted them,
+  which is the gate working.
+- **Close the row before measuring it.** Every figure in this record comes from a committed
+  build run over the estate, not from the working tree that produced it. That distinction
+  matters here: earlier in this cycle an apparent fourteen-repository defect turned out to be
+  caused by an uncommitted change, and the number would have been reported as a fact about
+  the estate.
+
+## Notes
+
+This record names no repository. The sweep that pseudonymised the estate used stable
+`repo-NN` labels because several older records use repository names as *evidence* — a table
+of how three repositories answer the same question, where "a repository and a repository"
+would destroy the argument. That argument is not present here: every repository in this
+record is identified by what it *is*, which is both publishable and more useful to a reader
+who has none of the files.
+
+`test/shipped.test.mjs` now fails on any estate name in anything this package publishes —
+the records, the changelog, the readme. It is scoped to the published set and asserts that
+scope against `package.json`, in both directions, so a directory added to `files` without
+being guarded fails rather than leaking.

package/docs/decisions/ADR-061-the-skill-registry-is-workspace-data.md

@@ -0,0 +1,113 @@
+# ADR-061 — The skill registry is workspace data, and the package ships none of it
+
+Status: **accepted** · 2026-10-12 · filed as S61
+**Affects:** `graph lint`, `skills list`, `skills show`, `skills resolve`, `skills brief`,
+`src/graph/load.mjs`, `package.json` `files`, the estate-name guard in `test/shipped.test.mjs`
+
+## Context
+
+`graph/skills.graph.json` is published. It is in `files`, so it is in the npm tarball and in
+the wheel, and `REGISTRY_PATH` finds it by resolving from `src/` — which in an installed
+package is inside the package itself:
+
+```js
+export const REGISTRY_PATH = resolve(HERE, '..', '..', 'graph', 'skills.graph.json');
+```
+
+So the registry every one of those commands reads is not the reader's. It is *this* source
+tree's catalogue of the skills that live in sibling repositories of this estate. An adopting
+repository has none of them.
+
+The estate-name guard found the symptom, and the symptom is the smaller half. Widened from
+`.md` to every text extension the package ships, it reported **51 strings in that one file**
+naming eight private repositories. The paths are the larger half and are not names at all:
+every `sources[].path` is `.agents/skills/<id>` or `.cursor/skills/<id>`, and not one of
+them resolves in a repository that is not this workspace. A reader who runs
+`simt skills list` gets skills they do not have, and `simt skills resolve` finds the
+declaration and then looks for a body that was never there. That is the corpus check this
+repository exists to enforce, failing in a file this repository publishes, on a scale the
+name grep was too narrow to see.
+
+Two more facts made the shape of the answer unambiguous rather than a judgement call:
+
+- **The sources are load-bearing, not decoration.** `graph lint` refuses a skill with none
+  ("no sources; every skill must point at the file it came from"), and the same array does
+  byte verification, variant resolution and duplicate detection. Nothing can simply be
+  deleted from it.
+- **There is already a workspace, and it is already resolved here.** `loadRegistry` calls
+  `workspace(flags)` before it validates anything, precisely so the sources can be checked
+  against a root. The registry is read from *inside the installed module* and verified
+  against *the reader's workspace* — a workspace that has nothing to do with it.
+
+So the file is not being shipped with a defect in it. It is a file that describes this
+workspace and is being shipped as though the workspace were universal, which is the one
+condition under which it makes no sense to any reader.
+
+## Rulings
+
+1. **The skill registry is workspace data.** It describes which skill bodies a particular
+   workspace contains, where they are, how big they are, and which stack tags separate the
+   variants. Every one of those is a fact about a workspace and none of them is a fact
+   about the tool.
+2. **The package ships no registry.** `graph` leaves `files`. The file stays in this
+   checkout, because this repository still has to lint and resolve its own skills, and the
+   rule that a tool must not carry its author's portfolio is about what it *publishes*.
+3. **A command reads the workspace's registry, and says so when there is none.** The
+   registry lives in a *member* of the workspace, not in the root: the root is the
+   directory that contains the member repositories, and it holds no `graph/` of its own.
+   When the reader names no path, resolution proceeds in tiers. First, the package root —
+   which is how this checkout finds its own registry; in an installed package `graph` is not
+   in the published set (ruling 2), so it never does. Next, a member of the resolved
+   workspace, when exactly one holds it: a tool installed from node_modules or a formula is
+   configured to find its workspace, and the member that holds the registry is usually the
+   tool's own checkout. More than one holding it means the reader must pick; none means the
+   command reports the workspace has no registry, naming that workspace. And where there is
+   no workspace at all: an honest absence — the command says there is no registry to read,
+   with a remedy that names the ways to point at one — which is the same shape
+   `loadRegistry` already uses for a missing file, and it does not become a new failure
+   mode. An explicitly named path always wins over all of this, and every tier is file
+   existence plus the configured workspace: there is no scoring, so the answer can be
+   explained to whoever asks.
+
+   What must not happen is the current silence: `skills list` in an adopting repository
+   answering with this estate's skills is a confident wrong answer, and a wrong answer from
+   a command whose only job is to list what is here. Nor may the remedy be a dead end: a
+   reader who follows the ways to point at a workspace must get the registry that workspace
+   holds, which is what the member tier exists for.
+4. **The guard keeps widening, and the suite stays red until the file is gone.** The
+   coverage test asserts in both directions that what is guarded is what is published, so
+   removing `graph` from `files` removes it from `SHIPPED_ROOTS` too — the two are one
+   number. Pseudonymising the names was rejected because it would have left the paths, the
+   byte counts and the variant stacks describing this workspace while hiding only the part
+   a grep can see.
+
+## Consequences
+
+- `simt skills list`, `show`, `resolve`, `brief` and `graph lint` in an adopting repository
+  report no registry rather than a foreign one. This is a behaviour change for anyone who
+  ran those commands and got this estate's skills; it was wrong, and the commands now say
+  so instead.
+- A copy of the tool installed from node_modules or a formula, pointed at a workspace that
+  holds a registry in one of its members, reads that member's registry and verifies it
+  against the workspace. This is how this estate keeps using its skills from an installed
+  copy; without it the remedy the absence message prints would be a dead end.
+- Byte verification still works here, because the file is still in this checkout. Nothing
+  about this repository's own use of the tool changes.
+- `test/shipped.test.mjs`'s `SHIPPED_ROOTS` loses `graph`, and the guard still covers
+  `bin`, `src`, `rules` and `docs/decisions`. The estate-name count in that file drops to
+  zero, which is the point.
+- The 51 strings are no longer shipped and the suite stops being red on purpose.
+
+## Rejected
+
+- **Pseudonymise the eight names to `repo-NN`.** It hides the part a grep can see and keeps
+  the part that matters: hundreds of paths that resolve nowhere for the reader, byte counts
+  of bodies they do not have, and variant stacks drawn from stacks they did not write. It
+  would also have required a second registry mapping the pseudonyms back, and that registry
+  is estate data — so it cannot be published either.
+- **Ship the registry with an empty `sources`.** `graph lint` refuses a skill with no
+  sources, so this would have meant shipping a registry that fails its own lint, or
+  shipping a second, weaker lint for adopters.
+- **Keep it, because a reader can ignore it.** The corpus check is not about whether a
+  reader is misled; it is about whether the shipped artefact is actionable by someone with
+  only the receiving repository. This one is not, for every field it has.

package/docs/decisions/ADR-062-a-fresh-adoption-seeds-the-gates-it-can-run.md

@@ -0,0 +1,94 @@
+# ADR-062 — A fresh adoption seeds the canonical gates it can run, and never more
+
+Status: **accepted** · 2026-10-13 · filed as S40
+**Affects:** `simt init`, `src/projection/manifest.mjs` (the `ECOSYSTEMS` table, `defaultGates`),
+`src/hooks/capability.mjs` (the tool probe, the `tools` field), `src/commands/init.mjs`,
+eight new files in `rules/stacks/`
+
+## Context
+
+S40's finding: the eight common ecosystems outside the JavaScript world — Rust, Go, .NET,
+Swift, Deno, Ruby, Dart and Elixir — emit no stack tag. The fingerprint recognises them as
+`has-*` facts, and the only reader of those facts was the Dependabot configuration. So a
+fresh Rust repository received the core essay and a manifest that runs nothing: no profile
+was selected because there was none to select, and no gate was proposed because no row keyed
+on a fact. The asymmetry is the defect — the ecosystems the tool recognises were the ones it
+served least, while the ecosystems that do emit stack tags got the full treatment.
+
+Two existing mechanisms make the fix data-only, per ADR-013:
+
+- **Profiles select on tags or facts.** `simt-applies` already accepts a fact, and the
+  genericity tests already assert that a profile may select on a fact no stack tag names.
+- **Gates are planned by signal.** `planGates` takes the union of stack tags and facts, so a
+  row can key on either; the two never cross-match, because facts are `has-*` and tags are
+  not.
+
+What was missing is one artefact per ecosystem: the profile file — and for gates, a row that
+says what a fresh adoption of one should declare. The second is the harder half, because
+declaring a gate is not free:
+
+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. So the question a seeding design has to answer is not "which
+ecosystem is here" — the marker file answers that — but "can this machine run what the gate
+says it runs". That is ADR-017's probe-before-declare, and it shapes every ruling below.
+
+## Rulings
+
+1. **Every ecosystem the fingerprint names gets a profile.** Eight new stack profiles, each
+   `simt-applies:` on its own fact (the files are named in the Affects line), so one marker
+   file reaches both the region the repository reads and the gates its commits run. Maven's profile (`jvm`) predates
+   this ruling and applies on the same fact, so the table has nine rows and eight new files.
+   An ecosystem arriving later is a profile file and a row: no engine change (ADR-013).
+2. **A fresh adoption seeds the canonical commands, and only where the probe found the
+   tool.** On `init`, when the fingerprint emits an ecosystem fact, the row's commands land in
+   `gates.commands` for each gate it proposes — but only when the probe found `tool`. The
+   probe is the same discipline ADR-017 applies to node tools: a binary on PATH, or a file in
+   the repository when the row says `file` (the Maven wrapper, probed the way `gradlew`
+   already is). A marker says the ecosystem is here; the probe says its program can run. Both
+   must be true for a seed to land. `readCapability` reports the results in a `tools` field
+   next to `binaries`, so the plan can say which seeds fired and which did not.
+3. **A seed is a default, and a default loses to every form of declaration.** A command the
+   repository already declared in `gates.commands` is never re-seeded. An npm runner keeps its
+   own scripts untouched: `package.json` is the repository's own answer to "how do I test and
+   format", and a seed that outranked a script would replace a choice with a default —
+   precisely in the mixed repository (a `package.json` and a `Cargo.toml`) where the script is
+   the deliberate answer. The escape hatch for a repository whose runner differs from the
+   canonical one (a Rails app, a Flutter module) is to declare its own command, and
+   declaration beats seed everywhere.
+4. **Where the probe fails, the gate is dropped with a why and a remedy, never declared.**
+   This is the invariant `planGates` already holds for every proposed gate; seeding inherits
+   it rather than creating an exception to it. A fresh Rust checkout on a machine without
+   cargo gets `dropped gate test: …` with a remedy that names the install, not a gate that
+   blocks its first commit.
+
+## Consequences
+
+- `simt init` on a fresh Rust, Go, .NET, Swift, Deno, Ruby, Dart or Elixir repository declares
+  runnable gates when the toolchain is present — a `seeded` line in the plan output names each
+  command that landed — and drops them with a remedy when it is not.
+- `readCapability` gains the probe and the `tools` field: a PATH lookup, plus an executable
+  check in the repository root for a `file` row.
+- `defaultGates`'s expansion of an ecosystem row tolerates a missing phase key: the Maven row
+  proposes only pre-push, and absence is "none", not a defect.
+- The seed picks one canonical command per gate (`bundle exec rspec`, `dart test`). A
+  repository whose runner differs declares its own; ruling 3 makes that declaration win.
+- Acceptance: one test per ecosystem asserting marker → fact → profile selection; a seeding
+  matrix (every row seeds when the tool can run, every row drops when it cannot, an npm
+  repository takes no seed, a declaration beats a seed); and two end-to-end Rust inits, with
+  and without `cargo` on PATH.
+
+## Rejected
+
+- **Seed on the marker's word alone.** The marker is a file in the repository; the tool is a
+  program on the machine. A repository can have one without the other — a freshly cloned Rust
+  checkout on a machine that has never installed the toolchain is the common case — and
+  seeding there would declare a gate that fails closed on every commit. ADR-017 exists for
+  exactly this.
+- **Seed into an npm repository's scripts.** The scripts are the repository's own answer, and
+  a seed that outranks them replaces a choice with a default. The mixed repository is where
+  this matters most, because there the script and the marker coexist on purpose.
+- **A second gate table or a new engine path for ecosystems.** The fact was already flowing
+  into `planGates`, and the union of tags and facts never cross-matches. What was missing was
+  a row and a file, which is data; the engine that reads it already existed.

package/docs/decisions/ADR-063-the-adoption-escape-hatch-is-opt-in.md

@@ -0,0 +1,69 @@
+# ADR-063 — The adoption escape hatch is opt-in, and the default writes in place
+
+Status: **accepted** · 2026-10-13 · filed after a consumer asked why every adoption branched
+**Affects:** `simt init`, `src/commands/init.mjs` (`establishEscapeHatch` and its call site),
+`src/argv.mjs`, `src/commands/help.mjs`; amends plan 0002 §8.2 item 3
+
+## Context
+
+Plan 0002 §8.2 item 3 ruled: "Create a branch and a `backup-before-simt-dev` tag before the
+first write, always." The tool complied — `simt init --yes` in a git repository tagged the
+pre-adoption commit, checked out a branch named after the tool, and wrote every adoption file
+onto it. The reviewable-diff argument is sound: adoption writes a dozen files into a
+repository the tool does not own, and doing it on a dedicated branch leaves the mainline
+untouched with two named undo paths.
+
+The "always" was the part that failed. Consumers kept reporting the branch switch as a
+surprise: they ran the documented command to adopt their repository, and found themselves on
+a branch they had not chosen, with a tag they had not asked for. Review 0001's S15 fixed the
+silence — the output now names both operations and the command that undoes each — but a
+well-announced surprise is still a surprise. The branch and the tag are an undo path for
+readers who want one; making them unconditional turned a safety feature into a default that
+every consumer has to explain away.
+
+## Rulings
+
+1. **The default adoption writes in place and creates no git object.** `simt init --yes`
+   without the new flag leaves the reader on the branch they were on, tags nothing, and
+   writes the adoption files as uncommitted changes. The reviewable diff survives: `git diff`
+   shows the whole adoption, and discarding it is `git checkout -- .` plus a clean. The run
+   says so in an `in place` line that names the flag which restores the undo path.
+2. **The escape hatch moves behind a flag named for what it gives.** `--backup` is the
+   opt-in: tag the pre-adoption commit as the backup tag and branch onto the adopt branch
+   before the first write, exactly as the tool did before. The name is the promise — a way
+   back to what the repository was — and it already appears in the output the tool prints, so
+   the flag and its effect share one word.
+3. **Whatever a run does to git state is reported, including doing nothing.** Plan 0002's
+   heading over the adoption rules is "Nothing is silent". With the hatch opt-in, the
+   in-place run is a git-state event too — the deliberate absence of one — and it gets a line
+   that says what was not done and how to get it done. The `--backup` run keeps the two lines
+   S15 established: what was tagged, and where the branch came from.
+
+## Consequences
+
+- `simt init --yes` on a git repository no longer moves the reader or writes a tag; consumers
+  who scripted against the old default add `--backup`. This is the one behaviour the change
+  invalidates, and it is named here rather than discovered in a broken pipeline.
+- The `in place` line appears on every real adoption that does not pass the flag, and the
+  help text for `init` and for the flag say what it means.
+- The dry-run path is untouched: it already created no git object, and it still says `apply
+  with: simt init --yes`.
+- Acceptance: the S15 test now runs with the flag and asserts both operations are reported;
+  a new test runs without it and asserts no tag, no branch, the reader stays put, and the
+  in-place line names the flag; the not-a-git-work-tree test runs with the flag, because that
+  is where the best-effort note lives now.
+
+## Rejected
+
+- **Keep "always" and add a flag to opt out.** An opt-out flag fixes the surprise for those
+  who read the help, and it still surprises everyone else — which is every consumer of a tool
+  whose default action is to touch someone's repository. The cost of the wrong default is
+  paid on every adoption; the cost of the right default is one flag on the few that want it.
+- **Two flags, one per operation.** The tag and the branch arrive together in the code and in
+  the undo story: the tag is the reset target, the branch is where the adoption sits while it
+  is reviewed. Splitting them lets a reader build a state the tool has never tested — a branch
+  without a tag to reset to, or a tag with nothing isolated under it.
+- **Move the decision into the dry-run preview.** The dry run shows what would change in the
+  files; git state is not a file, and a preview line for an operation that now does not happen
+  by default would describe the opt-in as if it were the plan. The `in place` line after
+  `--yes` is where the reader learns what the real run did not do.