simt-dev 0.5.0 → 0.6.2

package/CHANGELOG.md

@@ -6,6 +6,152 @@ All notable changes to this package are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.6.2] — 2026-10-27
+
+### Fixed
+
+The v0.6.1 tag run failed its own tests step: two decision-corpus lists in
+`test/rules.test.mjs` were not moved with ADR-099 (the partial-supersession
+shapes and the leaking-paths count, both designed to move with the corpus).
+Same product as v0.6.1; this tag exists so the release automation is proven by
+a green run rather than described by a red one.
+
+## [0.6.1] — 2026-10-27
+
+### Fixed
+
+The release automation, which the v0.6.0 tag proved broken in two places. The
+tag workflow compared CI-built binaries against locally-built committed
+checksums, but the build is deterministic per host family, not across them —
+the check could never pass, and darwin binaries cannot be finished on ubuntu
+runners for lack of `codesign` anyway. Each target now builds on its native
+runner, the release verifies the served bytes equal the built bytes, and a
+`sync-formula` job re-renders the committed formula from the served bytes
+(ADR-099). The formula description no longer starts with an article, which is
+what failed the Homebrew channel's `brew style` on v0.6.0. No product change.
+
+## [0.6.0] — 2026-10-27
+
+### Added
+
+`simt plugin <claude|gemini|cursor> --out <dir>` generates one of the three
+harness packages from the same tables `agent-hooks install` writes — the hooks
+file, the MCP registration and, for cursor, the kernel rules — each carrying a
+self-contained copy of the runtime so it installs into a clean profile. Dry-run
+unless `--yes`. The Gemini reader row gains its hooks file (`.gemini/settings.json`),
+which extends `agent-hooks install` and `status` to a fifth adapter.
+
+The MCP server answers `prompts/list` and `prompts/get` with two templates:
+`simt-brief` starts a task from the pre-assembled brief packet, and `simt-slice`
+implements one slice of the working plan (the next one whose dependencies are
+complete, or a named one) — reading the repo's rules through `simt://kernel`
+first, testing per the slice's acceptance check, committing locally and pushing
+only on explicit approval. A prompt names the tools; the server stays read-only.
+
+Two fixed resources join `simt://rules/{id}` and `simt://decisions/{adr}`:
+`simt://kernel` serves the collaborating region rendered in kernel mode for
+whatever repository the server runs in — the URI promises the kernel's bytes,
+whatever `mode` the manifest declares — and `simt://plan/next` serves the
+section of the next ready plan slice, listed only while one is ready. A listed
+resource's size is the size its read returns.
+
+The tool descriptions in `tools/list` are cut from 2,783 bytes to 1,949,
+inside the 2 KB budget plan 0003 R41 sets for a cacheable tools list; the
+input and output schemas stay full, per ADR-068.
+
+`harness detect` reports the MCP registration files the loader table records —
+`.mcp.json` (Claude Code), `.codex/config.toml`, `.cursor/mcp.json`,
+`.agents/mcp_config.json`, `.gemini/settings.json`, `.vscode/mcp.json` — as
+`kind: 'mcp'` rows whose provenance is the vendor page each path was read from.
+A row rests on the file existing, never on a directory's presence, and never
+counts toward the no-rule-channel note: a config file doesn't claim one.
+
+The loader table gains the Gemini CLI reader, whose configuration reference the
+table previously recorded as unavailable: it is live again (read 2026-10-26), so
+the row carries the GEMINI.md chain with `.git` boundary markers, the
+`context.fileName` rename (the only documented way this reader picks up
+AGENTS.md), depth-5 `@path` imports, no published cap, and the `mcpServers`
+registration. It stays a facts row — the `gemini-md` pointer remains the one
+rule channel for that reader.
+
+Each release now carries a fourth artefact beside the tarball, the wheel and the
+formula: one single-file executable per target (`darwin-arm64`, `darwin-x64`,
+`linux-x64`), built from the same `files` set with a pinned Node runtime, published to
+the GitHub release with a `.sha256` beside it and a build-provenance attestation. It is
+the channel for a machine that has no toolchain to install one with — the binary lands
+as one file in `.simt/bin/` and carries its own runtime — and its acceptance is
+executable: a Gradle fixture with every directory containing a node removed from `PATH`
+runs `check` and the hook shim from the built bytes.
+
+`simt pack new <name> --source <npm:<package>|git+https://…>` scaffolds a
+versioned pack — `pack.json`, an unmeasured `bench.json`, one stack rule — and
+`simt pack lint [dir]` validates it and states its measured ΔR, rejecting a pack
+with no bench summary under `--require-measured`. `simt pack publish [dir]` lints
+first, publishes an npm-sourced pack idempotently (a live version is skipped),
+and names the tag-and-push for a git-sourced one. The summary binds to every
+byte but itself, so recording a measurement cannot invalidate it.
+
+### Changed
+
+`harness detect`'s "some readers read AGENTS.md" rows no longer say bare "some"
+when the row knows which one: the `readsAgentsMdNote` travels to the text
+output, and `.gemini` graduates from unverified candidate to verified detection
+facts (presence implies Gemini CLI; AGENTS.md only when `context.fileName`
+names it).
+
+The one-line description the three channels publish (npm, PyPI and Homebrew) now
+names the goal plan `0003` is building toward — an intelligence amplifier for AI
+coding agents — instead of the adoption-only story it grew out of.
+
+The per-repository state directory is renamed from `.simt-dev/` to `.simt/`: the
+index, ledger, lessons, bench artifacts, local-model proposals (`distilled/`,
+`reviews/`) and repo-local profiles all live under `.simt/` now. Existing state is
+not migrated — a repository that carries a `.simt-dev/` directory moves it once by
+hand (`mv .simt-dev .simt`); everything in it is cache or ledger, regenerable from
+git. The names this tool writes into files it does not own stay put: the `simt.json`
+manifest, the `simt-dev-check.yml` gate, the user-level config directory and the
+`SIMT_DEV_*` environment variables keep their names.
+
+The skill registry leaves the published set again, as ADR-061 ruled when it
+first left in 0.2.1. It is a catalogue of one workspace's skills — the
+repositories whose bodies it resolves — and an installed copy serving that
+catalogue to an adopting repository is a confident wrong answer: the skills
+it names do not live in the reader's workspace. 0.5.0 carried the registry
+because a fresh install's `simt skills *` and `simt distill` otherwise found
+none; the fix is the honest absence the tiered loader already reports — the
+path it would have read, and the `simt graph lint <path>` remedy — with a
+workspace that owns the registry naming it through `--workspace`,
+`SIMT_DEV_WORKSPACE` or the user config file. Custom skills were never part
+of the registry: they live in each repository, and the disclosure scan
+projects them into AGENTS.md.
+
+The entry point file is renamed from `bin/simt-dev.mjs` to `bin/simt.mjs`,
+matching the command it installs: the command has been `simt` for a long
+time, the package is still `simt-dev`, and the file path was the last place
+that carried the old spelling. `BIN_REL` in `src/name.mjs` is the single
+source of truth, so the generated hook shim and CI workflow pick up the new
+path on their next regeneration; the channels (npm, PyPI, Homebrew), the
+repository's own CI and the test harnesses follow.
+
+The hook shim's remedy and the generated CI workflow now install the release binary
+for a repository without npm, instead of the pinned global npm install (`npm i -g`)
+that needed the npm that repository kind is defined by not having. The remedy is the
+one-line download the binary channel names, with its platform derived from `uname`;
+the CI step verifies the download against the published `.sha256` and runs with no
+`setup-node` step at all — a file that runs without a Node toolchain should not have
+one installed to run it.
+
+The locator resolves `.simt/bin/simt` between `node_modules` and `PATH`, so the bytes
+a repository downloaded are the bytes its gate runs and a machine-wide install cannot
+shadow them. The dispatcher's version check is unchanged and still refuses a stale
+copy, whichever path found it.
+
+Homebrew's formula downloads the release binaries rather than the npm tarball — one
+`url`/`sha256` pair per target, chosen at install time — and no longer declares
+`depends_on "node"`. `scripts/release-formula.mjs` patches each pair by content, and
+the release refuses to publish a formula whose checksums are not the bytes the tagged
+tree builds (ADR-098).
+
 ## [0.5.0] — 2026-10-25
 
 ### An offline distiller that proposes, never projects

package/README.md

@@ -2,7 +2,10 @@
 
 ![simt-dev, the intelligence amplifier for coding agents, and its four claims. One: say less, always — a kernel under 2 KB whose bytes stay stable so the prompt cache survives. Two: answers over exploration — a local code graph and a short task brief. Three: enforce, don't instruct — dual gates, before a tool call and at git time. Four: close the loop — benches and memory. Beneath them, the harnesses it works across and its three channels.](https://raw.githubusercontent.com/QuazarMedia/simt-dev/main/res/59e21e6d-6bf2-4d7d-b6ea-c7349a697d11.jpg)
 
-`simt` adopts a repository for the agents that work in it.
+`simt` adopts a repository for the agents that work in it, and builds an intelligence
+amplifier around them: a brief that answers before the agent explores, gates that
+validate before a tool call, benches that price every rule text, and memory that puts
+a recorded failure to work on the next one.
 
 It reads what the repository actually runs, projects the rules that are not already
 obvious into the files those agents read, and installs only the gates that repository
@@ -20,7 +23,64 @@ Anything that needs a parser grammar, a local model, or another server is a sepa
 package, off until the repository names it, and it proposes rows or text for a person
 to merge. It does not write the projection.
 
-## Today
+## Install
+
+Requires **Node >= 22.20.0** for the npm and PyPI channels; the release binary carries
+its own runtime. The current published release is **0.5.0**. Pin it. The tool writes a
+content digest into the files it generates, and an unpinned upgrade changes them under
+you.
+
+```sh
+npm i -D simt-dev@0.5.0
+
+# or globally
+npm i -g simt-dev@0.5.0
+
+# or once, with no install
+npx -y simt-dev@0.5.0 check
+```
+
+### From PyPI
+
+The wheel carries the same bytes as the npm tarball. It does not fetch them from npm
+at install time.
+
+```sh
+pip install simt-dev
+
+# when this machine has no node
+pip install "simt-dev[node]"
+```
+
+`simt` is the command on both channels. Node is resolved in this order, and the first
+one that answers wins: `SIMT_DEV_NODE`, the node bundled with the `node` extra, then
+`node` on `PATH`.
+
+### From Homebrew
+
+```sh
+brew install QuazarMedia/homebrew-tap/simt-dev
+```
+
+The formula downloads the single-file binary for this machine, which carries its own
+runtime: the command works with no Node installed.
+
+### As a single-file binary
+
+Each release carries one executable per platform — macOS arm64 and x64, Linux x64 —
+beside its `.sha256`. The channel's first release is the version after 0.5.0; pin that,
+and run this from the repository's top level:
+
+```sh
+mkdir -p .simt/bin && os=$(uname -s | tr A-Z a-z) && arch=$(uname -m | sed "s/x86_64/x64/") && curl -fsSL "https://github.com/QuazarMedia/simt-dev/releases/download/v<version>/simt-dev-<version>-$os-$arch" -o .simt/bin/simt && chmod +x .simt/bin/simt
+```
+
+The locator checks `.simt/bin/simt` before `PATH`, so the repository's own copy is the
+one its hooks and its CI run — this is the same command the hook shim prints as its
+remedy. The generated CI workflow downloads the same asset and verifies it against the
+published `.sha256` before running anything.
+
+## What `simt` does
 
 ```sh
 # Adopt, inspect, and maintain a repository
@@ -83,11 +143,15 @@ simt bench report [--compare a b]   # resolved rate, quality, cost, CPI, bootstr
 simt bench ablate --yes             # leave-one-out rule ablation ranked by value per KB
 simt bench probes --yes             # 12 deterministic rule-compliance probes
 simt bench variants --yes           # evaluate simt-variants slots and lock winners in simt-dev.lock.json
+simt pack new <name> --source <spec> # scaffold a versioned pack: pack.json, bench.json, one rule
+simt pack lint [dir] [--require-measured] # validate a pack and state its measured ΔR
+simt pack publish [dir] --yes       # publish an npm-sourced pack (git packs name the tag-and-push)
 simt mcp [--list]                   # serve the 13 read-only tools over stdio JSON-RPC
 ```
 
 `init`, `sync`, `upgrade`, `hooks install`, `agent-hooks install`, `shared install`,
-`skills install`, `plan done`, `lessons review`, `decide` and the `bench` writers print
+`skills install`, `plan done`, `lessons review`, `decide`, `pack new`, `pack publish`
+and the `bench` writers print
 a plan and write nothing without `--yes`. None of them commit or push. `simt index`
 writes its cache without asking: the file is gitignored and `git ls-files` can rebuild it.
 
@@ -209,7 +273,7 @@ returns a JSON object with `task`, `commands`, `files`, `tests`, `decisions`, `s
    `DRIFT` with `simt sync --yes`, and resolve any rule checker or manifest findings.
 2. **Verify execution evidence matches the current tree.** Run `simt evidence` to confirm
    that the tests and gates you plan to cite were recorded against the current
-   `git write-tree` digest in `.simt-dev/ledger.jsonl`. Any file edit invalidates earlier
+   `git write-tree` digest in `.simt/ledger.jsonl`. Any file edit invalidates earlier
    evidence.
 3. **Record decisions, lessons, and tracker state:**
    - If the change alters what the repository or tool believes, scaffold an ADR with
@@ -232,11 +296,11 @@ returns a JSON object with `task`, `commands`, `files`, `tests`, `decisions`, `s
 | Shape | How to configure and run `simt` optimally |
 | --- | --- |
 | **Single-package repository** (Node, TypeScript, Python/`uv`, Go, Rust, JVM/Gradle/Maven, Android, Swift, .NET, Deno, Ruby, Dart, Elixir, Cloudflare Workers, React Web, React Native, ConnectIQ, Container) | Run `simt init --yes`, `simt hooks install --yes`, `simt agent-hooks install --yes`, and `simt index`. Stack profiles and runnable gates are selected from committed manifests and build files (`simt doctor` shows `stack`, `facts`, and `factEvidence`). Set `"mode": "kernel"` and `"budget": { "bytes": 12000 }` in `simt.json` to keep session-start tokens minimal while keeping convention/style rules reachable via `simt rules show <id>`. |
-| **Custom stack or repo-specific house rules** | An ecosystem with no built-in profile is still adopted with `core` rules. Add repo-local profiles in `.simt-dev/profiles/<id>.md` with `simt-id`, `simt-title`, `simt-applies`, and `simt-priority` (`hard`, `command`, `convention`, `style`); local profiles project alongside or shadow central ones. Declare custom gates under `gates.commands` and placeholders under `substitutions` in `simt.json`. |
+| **Custom stack or repo-specific house rules** | An ecosystem with no built-in profile is still adopted with `core` rules. Add repo-local profiles in `.simt/profiles/<id>.md` with `simt-id`, `simt-title`, `simt-applies`, and `simt-priority` (`hard`, `command`, `convention`, `style`); local profiles project alongside or shadow central ones. Declare custom gates under `gates.commands` and placeholders under `substitutions` in `simt.json`. |
 | **Single-language or polyglot monorepo** (`package.json` `workspaces`, `pnpm-workspace.yaml`, `turbo.json`, `Cargo.toml` `[workspace]`, `go.work`, `settings.gradle`, `settings.gradle.kts`) | `simt init --yes` and `simt sync --yes` discover every workspace member and write both the root `AGENTS.md` and nested `<package>/AGENTS.md` projections carrying only the profiles specific to each package. Set `gates.cwd` in `simt.json` for gates that execute inside a sub-package. Measure nested context load with `simt harness loaders --at <package-dir>`, and use `simt gate --changed` to run only tests for modified packages. |
-| **Multi-repository workspace / estate** (sibling checkouts under a workspace directory or `SIMT_DEV_WORKSPACE`) | Run `simt compare` across the workspace root to inspect adoption, drift, pinned SHAs, hook routing, most-violated rules, noisy/slow gates (`NOISY-GATE`), zero-value rules, and proposed ADR drafts. Run `simt tokens --repos` and `simt shared plan`, then `simt shared install --yes` to move rules repeated across repos into user-level harness files (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, etc.). Vendor shared rule packs in `.simt-dev/packs/<name>/` pinned by digest in `simt.json`, and upgrade the entire estate atomically with `simt upgrade --yes`. |
+| **Multi-repository workspace / estate** (sibling checkouts under a workspace directory or `SIMT_DEV_WORKSPACE`) | Run `simt compare` across the workspace root to inspect adoption, drift, pinned SHAs, hook routing, most-violated rules, noisy/slow gates (`NOISY-GATE`), zero-value rules, and proposed ADR drafts. Run `simt tokens --repos` and `simt shared plan`, then `simt shared install --yes` to move rules repeated across repos into user-level harness files (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, etc.). Vendor shared rule packs in `.simt/packs/<name>/` pinned by digest in `simt.json`, and upgrade the entire estate atomically with `simt upgrade --yes`. |
 | **Repositories with external code-graph MCP servers** | Declare external stdio MCP servers under `federation` in `simt.json` (`{ name, command, args, tool, argument, languages, timeoutMs }`). `simt brief "<task>"` and the MCP `federation_query` tool ask each server one bounded structural question and cite the server name in `FEDERATION`. |
-| **Offline or local-model-assisted workflows** (Ollama, `llama-server`, LM Studio, MLX) | By default, `simt` uses zero models and opens zero sockets (`ADR-075`, `ADR-090`). To opt in, add `local: { chat: { url, model }, embed: { url, model } }` in `simt.json` pointing at `http://127.0.0.1:<port>/v1`. Verify with `simt local doctor`, and build/query SQLite vector embeddings with `simt index --embed` and `simt map --embed` (non-loopback URLs are refused without `--allow-remote`). |
+| **Offline or local-model-assisted workflows** (Ollama, `llama-server`, LM Studio, MLX) | By default, `simt` uses zero models and opens zero sockets (`ADR-075`, `ADR-090`). To opt in, add `local: { chat: { url, model }, embed: { url, model } }` in `simt.json` pointing at `http://127.0.0.1:<port>/v1`. Each role accepts an optional `apiKey` (sent as `Authorization: Bearer <key>`) for servers that require a token. Verify with `simt local doctor`, and build/query SQLite vector embeddings with `simt index --embed` and `simt map --embed` (non-loopback URLs are refused without `--allow-remote`). |
 | **Rule, skill, and benchmark maintainers** | Lint skills with `simt graph lint --spec agentskills`, compile and split > 5,000-token skills with `simt skills compile`, and score the resolver with `simt skills eval`. Mine git history tasks with `simt bench mine --yes`, run arms with `simt bench run --yes`, compare arms with `simt bench report --compare bare kernel`, run leave-one-out ablation with `simt bench ablate --yes`, run compliance probes with `simt bench probes --yes`, and lock winning `simt-variants` wordings with `simt bench variants --yes`. |
 
 ## Module and MCP reference
@@ -256,13 +320,9 @@ returns a JSON object with `task`, `commands`, `files`, `tests`, `decisions`, `s
 
 ## Where the plan finishes
 
-Slices `R01`–`R40` are complete and shipped in `0.5.0`. The remaining queued slices
-(`R41`–`R55`) finish packaging and the small ergonomics:
+Slices `R01`–`R45` are complete and shipped in `0.6.0`. The remaining queued slices are the
+small ergonomics:
 
-- **Packaging and declarative harness data (`R41`–`R45`).** MCP 2026-07-28 revision
-  tightening, declarative harness adapter files with provenance, single-command plugin
-  packaging, a single-file binary alongside npm/PyPI/Homebrew, and benchmark-measured rule
-  packs.
 - **The small doors (`R46`–`R55`).** `simt explain <CODE>` for every finding code, safe
   idempotent `simt doctor --fix`, a `< 50 ms` `simt status --line`, a write journal with
   `simt undo`, `--diff` on every writer, shell completions, one cross-harness ignore list
@@ -274,47 +334,6 @@ budgeted summaries with line citations, `simt review` proposes an advisory ADR-0
 verdict over the staged diff, and `simt brief` carries model/effort advice from bench
 history. All remain off until named and propose rather than write projected text.
 
-## Install
-
-Requires **Node >= 22.20.0**. The current published release is **0.5.0**. Pin it.
-The tool writes a content digest into the files it generates, and an unpinned upgrade
-changes them under you.
-
-```sh
-npm i -D simt-dev@0.5.0
-
-# or globally
-npm i -g simt-dev@0.5.0
-
-# or once, with no install
-npx -y simt-dev@0.5.0 check
-```
-
-### From PyPI
-
-The wheel carries the same bytes as the npm tarball. It does not fetch them from npm
-at install time.
-
-```sh
-pip install simt-dev
-
-# when this machine has no node
-pip install "simt-dev[node]"
-```
-
-`simt` is the command on both channels. Node is resolved in this order, and the first
-one that answers wins: `SIMT_DEV_NODE`, the node bundled with the `node` extra, then
-`node` on `PATH`.
-
-### From Homebrew
-
-```sh
-brew install QuazarMedia/homebrew-tap/simt-dev
-```
-
-The formula depends on `node`, so the command works on a machine that has never had
-Node installed.
-
 ## What it writes
 
 | Path | What |
@@ -344,11 +363,11 @@ These are caches, gitignored, and rebuildable. They are not repository content:
 
 | Path | What |
 | --- | --- |
-| `.simt-dev/index.sqlite` | files, symbols, import/call/test/governs/cochange edges, FTS5 `fts` tokens across `code`, `docs`, `skills`, `decisions` and `lessons`, and optional `embeddings` vector blobs. JSON-lines at `.simt-dev/index.jsonl` when this Node cannot open `node:sqlite` with FTS5 |
-| `.simt-dev/ledger.jsonl` | one line per gate or test the dispatcher actually ran, against one git tree, plus normalised failure signatures |
-| `.simt-dev/lessons.jsonl` | deterministic lesson candidates captured from fail-to-fix pairs, reverts, `BLOCK` reviews, and hook denials |
-| `.simt-dev/bench/` | mined tasks (`tasks/`), test patch vault (`vault/`), and benchmark runs (`runs/`) |
-| `.simt-dev/proposals/` | non-authoritative skill description proposals with `{model, promptHash, digest}` provenance |
+| `.simt/index.sqlite` | files, symbols, import/call/test/governs/cochange edges, FTS5 `fts` tokens across `code`, `docs`, `skills`, `decisions` and `lessons`, and optional `embeddings` vector blobs. JSON-lines at `.simt/index.jsonl` when this Node cannot open `node:sqlite` with FTS5 |
+| `.simt/ledger.jsonl` | one line per gate or test the dispatcher actually ran, against one git tree, plus normalised failure signatures |
+| `.simt/lessons.jsonl` | deterministic lesson candidates captured from fail-to-fix pairs, reverts, `BLOCK` reviews, and hook denials |
+| `.simt/bench/` | mined tasks (`tasks/`), test patch vault (`vault/`), and benchmark runs (`runs/`) |
+| `.simt/proposals/` | non-authoritative skill description proposals with `{model, promptHash, digest}` provenance |
 
 `simt shared install --yes` writes a user-level copy of the rules a workspace
 repeats, into the file that harness documents, and records the ids on each

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

@@ -2,6 +2,19 @@
 
 Status: **accepted** · 2026-10-11
 
+> Ruling 7's re-run mechanics are superseded by
+> [ADR-097](ADR-097-the-channels-publish-by-hand-and-the-version-rides-in-as-an-input.md):
+> the two channel jobs moved to a manual `workflow_dispatch` workflow whose `version`
+> input dissolves the branch-vs-tag failure recorded below. The ordering ruling —
+> npm live before either channel publishes — stands.
+
+> Ruling 5's artefact choice and the Homebrew half of ruling 7 are superseded by
+> [ADR-098](ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md): the
+> formula now downloads the release binary, not the npm tarball, and the Homebrew job's
+> precondition is that those assets exist rather than that the npm version is live. The
+> PyPI half of ruling 7 — npm live before the wheel publishes — stands, as does ruling
+> 5's refusal of `std_npm_args`.
+
 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`

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

@@ -1,6 +1,6 @@
 # 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
+Status: **accepted** · 2026-10-12 · affects all repos · ruling 3's no-npm install and remedy superseded by [ADR-098](ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md)
 
 ## Context
 

package/docs/decisions/ADR-097-the-channels-publish-by-hand-and-the-version-rides-in-as-an-input.md

@@ -0,0 +1,71 @@
+# ADR-097 — the channels publish by hand, and the version rides in as an input
+
+Status: **accepted** · 2026-10-25 · ruling 3's Homebrew precondition is superseded by [ADR-098](ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md), which also restates what each channel now waits on
+
+**Affects:** `.github/workflows/publish.yml`,
+`.github/workflows/publish-channels.yml`, `scripts/publish-local.mjs`,
+`docs/decisions/ADR-058-one-tool-three-channels-and-the-order-is-forced.md`
+
+## Context
+
+ADR-058 ruled the three channels and the order between them — npm first, PyPI and
+Homebrew only once the npm version is live — and its ruling 7 also pinned the
+mechanics: the two channel jobs lived inside `publish.yml`, next to the staging job,
+and a maintainer re-ran them through "Re-run failed jobs" once `npm stage approve` had
+landed. The same ruling recorded why no `workflow_dispatch` could replace that:
+on a dispatch, `github.ref_name` is the branch, and the version guard would compare a
+tag against a branch.
+
+Running it that way taught something the ruling did not predict. The channel jobs fail
+on every release **by design** — the stage is not approvable until a human decides, so
+a healthy release hours in is a release whose run is red. A run that is red when
+nothing is wrong is the argument ADR-058 itself used against a gate that is red on the
+day it lands: it teaches the reader to ignore red. And the only supported recovery is
+re-running part of an old run, an action buried in the run page's retry menu rather
+than in anything a maintainer can name.
+
+The branch problem stays, but it points at a different fix. A dispatch cannot carry a
+tag in `ref_name`, but it doesn't have to: the version is one string, it is already
+written in exactly one place (`package.json`), and the maintainer who just approved
+the stage knows it — they typed or copied it to get here.
+
+## Ruling
+
+1. **`publish.yml` owns npm staging and stops there.** The tag workflow keeps the
+   version guard and the staging job, and no longer carries a job designed to sit red
+   for hours. A green publish run means "staged", and nothing in it promises more.
+
+2. **The channels run from `.github/workflows/publish-channels.yml`, a
+   `workflow_dispatch` whose `version` input is the release (e.g. `0.5.0`).** The
+   version is the *input*, not the ref, which is what dissolves the branch-vs-tag
+   failure ADR-058 recorded: the input travels into the guard, and the guard refuses
+   to run unless tag `v<version>` exists on the default branch's history and its
+   checkout's `package.json` agrees with it. A dispatch cannot guess; the input makes
+   guessing impossible.
+
+3. **The ordering ruling is unchanged.** Both channel jobs still begin with the check
+   that `npm view` serves the version (PyPI) and that the tarball is downloadable
+   (Homebrew), and both still name the remedy — `npm stage approve <stage-id>` —
+   when it is not. What moved is who runs the steps and how the version travels;
+   what did not move is that npm is live before either channel publishes.
+
+4. **The channel jobs keep their identity unchanged.** PyPI still publishes with
+   trusted publishing against the `pypi` environment; Homebrew still audits, renders
+   and pushes the formula to the tap. Nothing about the artefacts changed, so ADR-058
+   rulings 1–6 read as written.
+
+## Consequences
+
+A maintainer's release tour is two named actions instead of one retry:
+
+```
+npm stage approve <stage-id>
+gh workflow run publish-channels.yml -f version=<VER>
+```
+
+Red is honest again: a red channel run means a channel defect, and the release page
+carries no run whose expected end state is red. `scripts/publish-local.mjs` keeps its
+role as the not-CI twin — it mirrors `publish.yml` for npm and
+`publish-channels.yml` for the two channels, and its header now says exactly that,
+because a twin of a file whose name no longer holds what it did is a comment that
+misdescribes the artefact (the estate's own rule against decoration that lies).

package/docs/decisions/ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md

@@ -0,0 +1,149 @@
+---
+simt-affects: ["scripts/build-sea.mjs", "src/distribute/release.mjs", "src/locate.mjs", "src/package-version.mjs", "src/hooks/shim.mjs", "src/ci/workflow.mjs", ".github/workflows/publish.yml", ".github/workflows/publish-channels.yml", "Formula/simt-dev.rb", "scripts/release-formula.mjs", "scripts/publish-local.mjs", ".gitignore", "test/binary.test.mjs", "test/ci.test.mjs", "test/packaging.test.mjs"]
+simt-supersedes: [{ adr: "ADR-058", ruling: 5 }, { adr: "ADR-058", ruling: 7, kind: "narrowed" }, { adr: "ADR-059", ruling: 3, kind: "superseded" }, { adr: "ADR-097", ruling: 3, kind: "narrowed" }]
+---
+
+# ADR-098 — The fourth channel is one file, and it needs no toolchain
+
+Status: **accepted** · 2026-10-26 · supersedes ADR-058 ruling 5 · narrows ADR-058 ruling 7 and ADR-097 ruling 3 · supersedes ADR-059 ruling 3 · ruling 3's cross-host byte-identicality narrowed by [ADR-099](ADR-099-the-release-verifies-served-bytes-and-the-formula-mirrors-them.md)
+
+Affects: `scripts/build-sea.mjs`, `src/distribute/release.mjs`, `src/locate.mjs`,
+`src/hooks/shim.mjs`, `src/ci/workflow.mjs`, `.github/workflows/publish.yml`,
+`.github/workflows/publish-channels.yml`, `Formula/simt-dev.rb`,
+`scripts/release-formula.mjs`, `scripts/publish-local.mjs`, `test/binary.test.mjs`
+
+## Context
+
+Review 0002's S35 ruled that no estate repository and no CI runner may be unable to
+obtain this tool, and ADR-059 shipped its first half: the remedy and the consumer CI
+step branch by repository kind. The half that did not ship is the one this record
+settles. For a repository without npm — a Gradle build, a Connect IQ project — every
+channel that existed needed a toolchain the repository does not have: the npm tarball
+needs npm, the wheel needs a Python, and the formula, until this record, declared
+`depends_on "node"` and so installed a command that could not start without one. The CI
+step that stood in for the missing channel ran `npm i -g simt-dev@<v>`, which needs the
+npm the repository kind is defined by not having. The one repository where the gate had
+no toolchain already was also the one where obtaining the tool required installing one.
+
+Two properties of the package made the alternative cheap. It has zero runtime
+dependencies and no build step (ADR-012), so "packaging" is copying ~1.3 MB of text
+around a pinned runtime; and the text reads its own shipped files — `rules/`,
+`templates/`, `docs/decisions/` — relative to `import.meta.url`, so it needs real files
+at real paths, not a module graph. Node's single-executable-application support embeds
+a script in an official node binary, and postject injects that blob into any target's
+copy of one; the missing half was a payload that materializes as a tree.
+
+## Ruling
+
+1. **A fourth artefact is released: one file per target, carrying the same payload the
+   npm tarball ships.** `scripts/build-sea.mjs` collects exactly `package.json`'s
+   `files` set plus `package.json` itself, and wraps it in a pinned official node base
+   at the version `engines` names. The targets are `darwin-arm64`, `darwin-x64` and
+   `linux-x64` — the set the one-line remedy and the consumer CI step can name — and a
+   platform outside it gets a loud 404, never a silent install of nothing. Each asset is
+   published to the GitHub release beside its `.sha256`, with a build-provenance
+   attestation binding the digest to the tag workflow's OIDC identity.
+
+2. **The payload materializes as real files before the tool runs.** The SEA entry is a
+   small CommonJS bootstrap (Node 22's SEA host runs the entry as CJS, whatever the
+   entry's own shape) that writes the embedded file set into
+   `${XDG_CACHE_HOME:-$HOME/.cache}/simt-dev/<node version>/<digest>/` and then imports
+   `bin/simt.mjs` from there. The digest is a hash of the canonical payload, so one
+   directory per payload, written to a staging directory and renamed into place, with a
+   marker file making a second run a no-op. Real files at real paths are what keep every
+   `import.meta.url`-relative read in `src/` working unmodified; a bootstrap that inlined
+   the tool instead would have to re-implement each one.
+
+3. **Determinism is the release contract, and the release checks it.** The same tree
+   builds byte-identical assets on any host: the node base is pinned, the SEA config uses
+   relative paths so no checkout path lands in the blob, and darwin binaries are ad-hoc
+   codesigned with a fixed identifier (without one, codesign derives the identifier from
+   the file path, which is what made two checkouts differ). Because of that, the tag
+   workflow re-builds each asset and fails the release when its checksum is not the one
+   `Formula/simt-dev.rb` in the tagged tree promises — the equality is checked, not
+   assumed.
+
+4. **Homebrew's artefact becomes the binary (supersedes ADR-058 ruling 5).** The formula
+   carries one `url`/`sha256` pair per target, selected by OS and CPU at install time,
+   and no longer declares `depends_on "node"`: the binary is the runtime. The "not
+   `std_npm_args`" half of ADR-058 ruling 5 stands unchanged — the formula still does no
+   build-time fetch of a package manager. `scripts/release-formula.mjs` patches each
+   pair by content, one url and the sha256 line that follows it, and refuses a formula
+   whose layout has drifted rather than patching blind.
+
+5. **The order each channel waits on is what that channel downloads (narrows ADR-058
+   ruling 7 and ADR-097 ruling 3).** PyPI still begins by checking that `npm view` serves
+   the version, because the npm channel is the one a maintainer has to approve by hand.
+   Homebrew now begins by checking that the release assets exist, because the formula
+   downloads those — a formula naming a tag whose binaries were never built installs a
+   404 just as surely as one naming an unapproved npm version. The ordering rule
+   survives; only its second premise moved.
+
+6. **The repository's own copy is checked before `PATH`, and the version pin still
+   decides.** The locator resolves `$SIMT_DEV_BIN`, then `node_modules`, then
+   `.simt/bin/simt`, then `PATH` — so the bytes a repository downloaded are the bytes its
+   gate runs, and a machine-wide install cannot shadow them. The dispatcher's version
+   comparison (ADR-059 rulings 1 and 2) is unchanged and still refuses a stale binary,
+   whatever path it was found by.
+
+7. **A repository without npm installs the binary with one command, and its CI needs no
+   Node (supersedes ADR-059 ruling 3's no-npm remedy).** The remedy the shim prints for
+   such a repository is one line — `curl` the asset for this machine into `.simt/bin` and
+   `chmod` it — with the platform derived at run time from `uname`, because the remedy is
+   committed text that a colleague on another machine will read. The generated consumer
+   workflow downloads the same asset, verifies it against the published `.sha256`, and
+   installs it into `.simt/bin` with no `setup-node` step at all; the install fails loudly
+   rather than letting a gate pass that never started. The remedy stays one line a reader
+   copies (it carries no checksum — the dispatcher re-verifies the version, and the
+   automated CI install is where the published checksum is checked).
+
+## Consequences
+
+- **The acceptance criterion is executable.** A Gradle fixture with every directory
+  containing `node` removed from `PATH` runs the release binary's `check` and its
+  `agent-hook` path, and the rendered hook shim hands over to `.simt/bin/simt` and
+  refuses when it is absent (`test/binary.test.mjs`). The test skips rather than fails on
+  a host that is not a release target or cannot reach `nodejs.org` for the base, because
+  a contributor's suite must still go green (ADR-031).
+- **One `files` list feeds three artefacts.** The npm tarball, the wheel and the binary
+  payload all derive from `package.json`'s `files`, so the parity ADR-058 ruled survives
+  the new artefact instead of being restated in a third place.
+- **The assets are large — one node runtime each.** That is the price of the only channel
+  a repository with no toolchain can use, and it is paid per release, not per install:
+  the payload is materialized once per node version and digest and reused after that.
+- **The formula's committed checksums are the deterministic build of this tree.** Editing
+  anything in the payload changes them, and a release whose build disagrees with the
+  formula fails at tag time — which is the moment the maintainer still has the tree in
+  front of them. The committed values are never a placeholder: they are what the next
+  tag of this tree must hash to.
+- **A repository that never downloads the binary is unaffected.** The locator's new
+  branch is one `[ -x … ]` test that is false when the path is absent, and the npm and
+  wheel channels do not consult it.
+
+## Rejected
+
+- **Bun and Deno `compile`.** Evaluated on their documented behaviour, not measured. The
+  package's `engines` floor is Node 22.20.0, its index is `node:sqlite` (ADR-089), and
+  every latency figure this plan records was taken on that runtime. A binary compiled by
+  another runtime would be the one channel not running the runtime the other three run,
+  so the records would stop describing it, and the estate would have to re-measure per
+  channel to say anything true about it. Node's SEA keeps every channel on the declared
+  runtime, and its base is an official node build — the thing that can be pinned and
+  attested byte-for-byte. If the floor ever moves to another runtime, the bootstrap is
+  the only part that needs rewriting, because the payload is plain files.
+- **A bundler that inlines the tool into one script.** The tool reads `rules/`,
+  `templates/` and its own decision records at run time; a bundle would have to
+  re-implement every `import.meta.url` root computation, and ADR-012's zero-dependency
+  rule leaves no bundler to depend on. The payload here is runtime-agnostic text; only
+  the wrapper is node-specific.
+- **An archive plus a runner script.** Two files is an install step, and the channel
+  exists so that a repository with no toolchain gets one file that runs.
+- **A checksum inside the one-line remedy.** The remedy is text a reader copies out of an
+  error message; adding a second verification command makes it no longer one line. The
+  download is TLS from the release, the dispatcher re-verifies the version the repository
+  pinned, and the automated install — the CI step, which no human is watching — is where
+  the published `.sha256` is checked before anything runs.
+- **`npm i -g simt-dev@<v>` for a repository without npm** (what ADR-059 ruling 3 ruled).
+  The command needs npm, which is the one thing the repository kind is defined by not
+  having; that this was the remedy for the kind it could not serve is the defect S35
+  found.