simt-dev 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,175 @@ All notable changes to this package are recorded here. The format follows
 
 ## [Unreleased]
 
+## [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
+
+`simt distill <skill|doc>` writes a budgeted summary of a skill body or repository
+document with citations to source line ranges (`[L12-L15]`). The default engine is a
+deterministic outline pass with no model and no network; `--local` uses the configured
+local model endpoint from plan 0003 R37. Proposals are cached by content digest in
+`.simt-dev/distilled/<digest>.md` and carry provenance frontmatter (source digest,
+engine, prompt hash, `verified`), so a human merges them into the pack or repository:
+model output never lands in projected or committed text (ADR-090). Every citation is
+verified against the source, and a fabricated one makes the proposal
+`verified: false` with the fault named.
+
+### An advisory critic over the staged diff
+
+`simt review` gathers the brief — the governing decision records and scoped rules for
+the staged files — with no model and no network. `simt review --local` sends that brief
+plus the staged diff to the local model and receives an ADR-008 verdict skeleton
+(`BLOCK`, `APPROVE WITH RESIDUAL RISK` or `APPROVE`) that cites rule ids with an
+`@` marker; a citation to an id that governs nothing is named a fabrication, a
+`BLOCK` carries no weight without a file:line or command finding, and a residual-risk
+approval must list what the critic did not review. Verdicts land as proposals in
+`.simt-dev/reviews/<digest>.md` and stay advisory: they become a gate only when
+`simt bench critic --labels <path>` measures precision of at least 0.8 (with recall
+reported) on at least 30 historical diffs human-labelled in a JSONL file the tool
+consumes but never writes.
+
+### Model and effort advice in the brief header
+
+`simt brief` now carries an `ADVICE` header, such as `small model, no plan mode` or
+`frontier model, plan first`, derived from the estate's own bench history: the brief's
+task kind and estimated file size pick a neighbourhood of similar bench tasks, the
+cheapest model class that actually resolved them sets the tier on a thirds ladder of
+the classes the estate has observed (no vendor names in code), and median tool calls in
+the neighbourhood set the effort. Nothing is selected: a human still names the model.
+With no history the brief says nothing, and with a thin one it prints a caution rather
+than a guess. The advice is advisory until a held-out bench shows a cost cut of at
+least 25% at a resolved-rate loss of at most 2 points, so the unmeasured bar travels
+in every packet the advice appears in.
+
+### Fixed
+
+`package.json` gained the `repository` field npm's provenance verification requires:
+the sigstore bundle is checked against the public source repository, and the missing
+URL rejected the 0.4.0 upload with `E422`.
+
 ## [0.4.0] — 2026-10-20
 
 ### Hybrid retrieval fuses BM25, the code graph, and the resolver
@@ -733,6 +902,7 @@ never ran `simt hooks install` again will find nothing until the dependency is r
 and `simt hooks install --yes` is re-run. That is a real upgrade step and it is called out
 here rather than discovered.
 
+[0.5.0]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.5.0
 [0.4.0]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.4.0
 [0.3.1]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.3.1
 [0.3.0]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.3.0

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,81 +23,21 @@ 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
-
-```sh
-simt init                 # adopt or scaffold; prints a plan; --yes writes
-simt doctor               # what this repo is, and whether its config is healthy
-simt check                # projection drift, the manifest, and declared checkers
-simt sync --yes           # regenerate the projection
-simt upgrade --yes        # move every pin of this tool to this version
-
-simt rules why ADR-042    # the decision behind a rule, and what was rejected
-simt skills brief --task  # a short brief for one task
-simt tokens               # bytes a reader loads at session start
-simt shared plan          # rules a workspace repeats, and what carrying them once saves
-simt harness loaders      # what each harness loads, and what its cap drops
-
-simt hooks install --yes  # the git dispatcher, for gates this repo can run
-simt agent-hooks install --yes   # the same policy before a tool call
-simt evidence             # runs recorded against this tree
-simt index                # files, exports and imports, from git blob hashes
-simt plan next            # the next tracker row that is ready
-
-simt bench report         # resolved rate, quality, cost, across arms
-simt compare              # every sibling checkout that has adopted
-simt mcp                  # the read-only surface, over stdio
-```
-
-`init`, `sync`, `upgrade`, `hooks install`, `agent-hooks install`, `shared install`
-and `plan done` 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.
-
-`check` runs the checkers a rule names. A marked line leaves the projection as
-`Enforced:` and the checker's name. The file-length line warns past 400 lines and
-fails past 1000. `simt evidence check` warns when a commit message claims a passing
-run this tree does not have, and the commit fails when `gates.evidence` is `block`.
-The commit-msg hook is installed only when that setting is `warn` or `block`.
-
-## Where the plan finishes
-
-The work above is the part that runs. The plan still adds the rest of the loop, in
-this order of purpose:
-
-- **Gates on the change.** A check selects the tests that cover the diff, and the
-  tool's own gate output is shortened without dropping a failure line.
-- **Answers instead of exploration.** A ranked map of the repository, the impact of
-  a file or a symbol, the tests that cover a change, and the decisions, rules and
-  skills that govern a path. An external code graph can answer for a language it
-  covers, and the answer names that source.
-- **A brief for the task in front of the agent.** At most 2 KB, pulled at submit or
-  pushed by a hook, built from the map, the tests and the governing records.
-- **A memory that has to earn its place.** A lesson is a candidate when a failing run
-  is followed by a fix. It is recalled on a later task that looks like it, and it
-  expires. Variant wording of a rule ships only when the bench says it won.
-- **Local models, off unless asked.** Distillation and a critic propose. They do not
-  write projected text. With no model configured, nothing opens a socket.
-- **The small doors.** One finding code explained, a safe `doctor` fix, a one-line
-  status, an undo journal, a diff of every planned write, shell completions, one
-  ignore list for every harness plus a secret scan, a worktree per slice, a file
-  lease when two agents would edit the same path, and a pull-request body taken from
-  the evidence.
-
 ## Install
 
-Requires **Node >= 22.20.0**. The current published release is **0.4.0**. Pin it.
-The tool writes a content digest into the files it generates, and an unpinned upgrade
-changes them under you.
+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.4.0
+npm i -D simt-dev@0.5.0
 
 # or globally
-npm i -g simt-dev@0.4.0
+npm i -g simt-dev@0.5.0
 
 # or once, with no install
-npx -y simt-dev@0.4.0 check
+npx -y simt-dev@0.5.0 check
 ```
 
 ### From PyPI
@@ -119,37 +62,312 @@ one that answers wins: `SIMT_DEV_NODE`, the node bundled with the `node` extra,
 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.
+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
+simt init                           # adopt or scaffold; prints a plan; --yes writes
+simt doctor                         # stack, facts, evidence, and config health
+simt check [--frozen]               # projection drift, manifest, lock, and declared checkers
+simt sync [--explain] --yes         # regenerate the projection
+simt upgrade --yes                  # move every consumer in the workspace to this SHA
+
+# Orient on a task and query the local code and governance graph
+simt brief "<task>"                 # one <= 2 KB packet: kind, commands, files, tests, ADRs, skills, lessons
+simt index [--embed]                # files, symbols, edges, FTS5 tokens (+ optional local embeddings)
+simt map --task "<task>"            # hybrid BM25 + PageRank + resolver file ranking (outline|names|signatures)
+simt impact <file|symbol>           # importers, covering tests, governance, and cross-repo consumers
+simt tests <path> [--cochange]      # tests covering a file via imports, naming, coverage, or co-change
+simt gate --changed                 # run only the tests the current diff reaches, with compacted output
+simt why [path]                     # ADRs, rules, skills, gates, and lessons governing a path
+
+# Rules, skills, decisions, and lessons
+simt rules list [--root <path>]     # rule catalogue and what applies to a repository
+simt rules show <id>                # read one rule body (including rules deferred in kernel mode)
+simt rules why <id|ADR-NNN> [--all] # the decision that settled a rule, and whether it still stands
+simt decide "<title>" --yes         # scaffold the next ADR with structured simt-affects / simt-supersedes
+simt lessons list                   # fail-to-fix, revert, review-block, and hook-denial candidates
+simt lessons review <id> --yes      # promote a candidate to docs/lessons/NNNN-<slug>.md
+simt skills index                   # tier-0 catalogue: every skill, one line each
+simt skills brief --task "<task>"   # tier-1 ranked skill selection within budget
+simt skills show <name>             # tier-2 skill body on demand (respects --max-bytes)
+simt skills why <name>              # the signal chain that selected or rejected a skill
+simt skills find <query>            # search skills by capability and keyword
+simt skills install <name> --yes    # pin a skill into the repository
+simt skills compile [<name>]        # compile to Agent Skills layout, split > 5,000-token bodies, report triggers
+simt skills eval [corpus]           # measure resolver precision and recall against a gold corpus
+simt graph lint [--spec agentskills]# verify the skill registry against skills on disk
+
+# Dual gates (git time and agent tool-call time) and execution evidence
+simt hooks install --yes            # install the shared POSIX git hook dispatcher
+simt hooks status                   # what each git event routes to, and whether it is wired
+simt hooks run <event>              # run pre-commit or pre-push gates now, as git would
+simt agent-hooks install --yes      # write pre/post-tool and prompt-submit hooks for active harnesses
+simt agent-hooks status             # what each harness will run, and whether Codex trusts it
+simt agent-hook <event> --harness   # evaluate pre-tool-use, post-tool-use, or prompt-submit
+simt evidence                       # gate and test runs recorded against the current git tree
+simt evidence check <msg-file>      # verify a commit message does not claim unrecorded passing runs
+
+# Plans, context metering, workspace learning, benchmarks, local models, and MCP
+simt plan status                    # count queued, in-progress, complete, and accepted tracker rows
+simt plan next [<id>]               # print the next ready slice section (~1 KB)
+simt plan done <id> [<sha>] --yes   # mark a tracker row complete with its commit SHA and test command
+simt tokens [--repos] [--session]   # measure bytes loaded at session start or split a transcript
+simt harness detect [--user]        # detect configured harnesses at repo and user level
+simt harness loaders [--table]      # what each harness loads, in what order, and where its cap truncates
+simt shared plan                    # rules repeated across a workspace and the bytes saved by sharing
+simt shared install --yes           # write shared rules once at user level and record the repo delta
+simt compare                        # workspace matrix, violated rules, noisy/slow gates, and ADR drafts
+simt local doctor [--allow-remote]  # probe configured OpenAI-compatible local chat and embed endpoints
+simt bench mine --yes               # mine verified fail-to-pass tasks from git history into the vault
+simt bench run --yes                # evaluate arms (bare, current, kernel, brief) in isolated exports
+simt bench report [--compare a b]   # resolved rate, quality, cost, CPI, bootstrap CIs, McNemar/Wilcoxon
+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`, `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.
+
+`check` runs the checkers a rule names (`max-file-lines`, `forbid-regex`,
+`forbidden-path-edit`, `required-file`), verifies structured ADR supersessions
+(`prose-partial-supersession`), and flags expired lessons (`LESSON-EXPIRED`). A marked
+rule line leaves the projection as `Enforced:` and the checker's name. The file-length
+line warns past 400 lines and fails past 1000. `simt evidence check` warns when a commit
+message claims a passing run this tree does not have, and the commit fails when
+`gates.evidence` is `block`.
+
+## Agent playbook: how and when to use each module
+
+An agent working in an adopted repository should use `simt` as its primary orientation,
+retrieval, validation and memory layer rather than scanning the tree by hand. Every
+read-only command supports `--json` (and `--max-bytes <n>`) or can be called over stdio
+through `simt mcp`.
+
+### Decision tree: which command to run when
+
+| Situation | First command | If you need more |
+| --- | --- | --- |
+| New task, no context yet | `simt brief "<task>"` | `simt map --task "<task>"` for broader file ranking |
+| About to edit a file | `simt why <file>` | `simt impact <file>` for blast radius |
+| Need to know what tests to run | `simt tests <file>` | `simt gate --changed` to run them |
+| Rule violation or error | `simt lessons list` | `simt rules why <rule-id>` for the decision |
+| Working from a plan | `simt plan next` | `simt plan done <id> <sha> --yes` when finished |
+| Before committing | `simt check` | `simt evidence` to verify test claims |
+| Repository adoption | `simt init --yes` | `simt doctor` to verify stack detection |
+| Multi-repo workspace | `simt compare` | `simt shared plan` to find deduplication opportunities |
+| Local model available | `simt local doctor` | `simt index --embed` to build vector embeddings |
+
+### 1. Start of task — orient in one call instead of broad exploration
+
+1. **Assemble the task packet first.** Run `simt brief "<task>"` (or call MCP `brief`, or
+   read the packet injected automatically when `agent-hooks install --yes` wired
+   `prompt-submit`). Within `--budget 2048` bytes (pass `--budget 0` for unlimited or
+   `--explain` to see why items were kept or cut), the packet gives:
+   - `TASK`: the classified task kind (`bugfix`, `feature`, `refactor`, `test`, `docs`,
+     `config`) and the evidence behind it.
+   - `COMMANDS`: the exact `build`, `test`, `lint`, `format`, `typecheck`, and focused
+     test templates for this repository.
+   - `LIKELY FILES`: top files ranked by reciprocal-rank fusion (`RRF_K = 40`) across
+     SQLite FTS5 `bm25()`, PageRank graph proximity, and resolver signals.
+   - `TESTS`: the test files mapped to those likely files.
+   - `DECISIONS`, `SKILLS`, `LESSONS`, `CAUTIONS`, and `FEDERATION`: governing ADRs,
+     matched skills, promoted lessons for those paths, active worktree/hook cautions, and
+     any structural answer from a declared external code-graph server.
+2. **Pull the next tracker slice when working from a plan.** Instead of reading a multi-thousand-line
+   plan in `docs/plans/` or `docs/reviews/`, run `simt plan next` (or MCP `plan_next`) to
+   load only the next queued slice (~1 KB) whose dependencies are already `Complete` or
+   `Accepted`.
+
+**When to use `--json` format.** When piping output to other tools or when the agent needs
+structured data, add `--json` to any read-only command. For example, `simt brief "<task>" --json`
+returns a JSON object with `task`, `commands`, `files`, `tests`, `decisions`, `skills`,
+`lessons`, `cautions`, and `federation` fields that can be programmatically consumed.
+
+### 2. Before editing — query the graph, blast radius, and governance
+
+1. **Rank files or symbols at the right granularity.** When `brief`'s file list is too
+   narrow or the task evolves, run `simt map --task "<task>" --level outline` for paths,
+   `--level names` for exported symbols, or `--level signatures` for declaration lines.
+   Pass `--embed` when `local.embed` is configured in `simt.json` and clears the +10-point
+   recall@10 bar.
+2. **Check blast radius before changing a shared file or export.** Run
+   `simt impact <file|symbol>` to see every direct and transitive importer, the tests
+   covering them, the governing rules and ADRs, and any sibling repository in the
+   workspace that imports that symbol.
+3. **Read the governance on a path before changing its behaviour.** Run `simt why <path>`
+   to list every ADR whose `simt-affects` matches the file, every scoped rule, skill,
+   gate, and promoted lesson. Run `simt why` with no path to audit the repository for
+   `UNRESOLVED-AFFECTS` tokens.
+4. **Resolve deferred rules and citations on demand.** When `simt.json` sets
+   `"mode": "kernel"`, only `hard` and `command` rules are loaded at session start;
+   `convention` and `style` rules are listed by ID at the foot of the projection. Fetch a
+   deferred rule with `simt rules show <id>`, and read any cited `ADR-NNN` with
+   `simt rules why ADR-NNN` (or MCP `rules_why`) to see its rulings and whether any ruling
+   was superseded or narrowed.
+5. **Load skills progressively (Tier 0 → Tier 1 → Tier 2).** Never read every skill file
+   upfront:
+   - Tier 0: `simt skills index` (or MCP `skills_index`) lists one line per skill.
+   - Tier 1: `simt skills brief --task "<task>"` (or MCP `skills_brief`) ranks compatible
+     skills within budget (`--plan` emits a fetch plan without bodies).
+   - Tier 2: `simt skills show <name> --max-bytes 8192` (or MCP `skills_show`) loads only
+     the chosen skill's body.
+
+**Optimal retrieval strategy.** For best performance, use this sequence:
+1. `simt brief "<task>"` — gets the most relevant files and tests in one call
+2. If more files are needed, `simt map --task "<task>" --level outline` — broader ranking
+3. If you need to understand a specific file's impact, `simt impact <file>` — blast radius
+4. If you need to understand governance, `simt why <file>` — ADRs and rules
+
+### 3. During implementation — validate incrementally under dual gates
+
+1. **Keep the local index current.** After adding, renaming, or changing exports/imports,
+   run `simt index`. It hashes tracked blobs via `git ls-files --stage` and re-extracts
+   only changed files in under 300 ms.
+2. **Run only the tests your change reaches.** Use `simt tests <path>` to inspect which
+   tests cover a file (via import edges, naming conventions, or coverage records; add
+   `--cochange` to include historical co-change pairs). Run `simt gate --changed` (or
+   `simt gate <path...>`) to execute only the tests reachable from the diff, with gate
+   output compacted so every failure line survives while passing noise is trimmed.
+3. **Respect agent-time hooks and learn from failures.** With `simt agent-hooks install --yes`,
+   `pre-tool-use` blocks unapproved `git push`, history rewrites (`--no-verify`,
+   `--amend`, `reset --hard`, `rebase`), and direct edits to generated regions before the
+   tool executes. When a test or gate fails, `post-tool-use` hashes the normalised first
+   error line against `docs/lessons/*.md` and injects the matching lesson into context.
+
+**Incremental validation workflow.** After each meaningful code change:
+1. Run `simt tests <changed-file>` to see which tests cover your changes
+2. Run `simt gate --changed` to execute only the affected tests
+3. If a test fails, check `simt lessons list` for known issues and their remedies
+4. If the failure is new, fix it and consider promoting the lesson with `simt lessons review <id> --yes`
+
+### 4. Before committing and closing a slice — verify drift, evidence, and memory
+
+1. **Run the repository gate.** Run `simt check` (or MCP `check`). Fix any reported
+   `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/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
+     `simt decide "<title>" [--supersedes ADR-NNN[:<ruling>]] --yes`.
+   - If a failing gate or test was fixed during the session, inspect captured candidates
+     with `simt lessons list` and promote reusable ones with
+     `simt lessons review <id> --yes`.
+   - After committing locally (never push without explicit approval per `ADR-001`), close
+     the tracker slice with `simt plan done <id> <sha> --test "<cmd>" --yes`.
+
+**Pre-commit checklist.** Before committing, run this sequence:
+1. `simt check` — verify no drift and all rules pass
+2. `simt evidence` — confirm test runs are recorded against current tree
+3. `simt lessons list` — check for any unreviewed lesson candidates
+4. `git commit` — commit locally (never push without explicit approval)
+5. `simt plan done <id> <sha> --yes` — close the tracker slice if working from a plan
+
+## Optimal setup for every project, repository, and workspace shape
+
+| 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/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/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`. 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
+
+| Module | CLI commands | Read-only MCP tools | When an agent should use it |
+| --- | --- | --- | --- |
+| **Task Brief** | `simt brief "<task>" [--budget <n>] [--explain]` | `brief` | First call on every task to get task kind, commands, ranked files, tests, ADRs, skills, and lessons in <= 2 KB |
+| **Code Graph & Retrieval** | `simt index [--embed]`, `simt map`, `simt impact`, `simt tests`, `simt gate` | `federation_query` | Before editing to rank files (`map`), trace blast radius (`impact`), or run only diff-affected tests (`gate --changed`) |
+| **Governance & Provenance** | `simt why [path]`, `simt rules list`, `simt rules show <id>`, `simt rules why <id\|ADR-NNN>`, `simt decide` | `rules_list`, `rules_why` | Before touching governed files (`why`), when reading deferred kernel rules (`rules show`), or when checking/scaffolding ADRs (`rules why`, `decide`) |
+| **Skills & Disclosure** | `simt skills index\|brief\|show\|why\|find\|install\|compile\|eval`, `simt graph lint` | `skills_index`, `skills_find`, `skills_brief`, `skills_show`, `skills_why` | When a task requires domain workflows or reference docs without blowing the session token budget |
+| **Memory & Lessons** | `simt lessons list`, `simt lessons review <id> --yes` | — | After fixing a failing test/gate or hitting a hook denial, to inspect or promote reusable failure-to-fix lessons |
+| **Plans & Trackers** | `simt plan status`, `simt plan next [<id>]`, `simt plan done <id> [<sha>] --yes` | `plan_next`, `plan_done` | When executing a phased implementation or review plan row by row |
+| **Adoption & Projection** | `simt init`, `simt doctor`, `simt check [--frozen]`, `simt sync`, `simt upgrade`, `simt ci` | `doctor`, `check` | When adopting a repo, diagnosing stack/config health, or verifying zero drift before commit |
+| **Dual Gates & Evidence** | `simt hooks install\|status\|run`, `simt agent-hooks install\|status`, `simt agent-hook`, `simt evidence [check]` | — | When installing git/agent hooks, running gates manually, or verifying test claims before committing |
+| **Context & Harnesses** | `simt tokens [--repos] [--session]`, `simt harness detect\|loaders`, `simt shared plan\|install` | — | When auditing startup token cost across harnesses (`claude`, `codex`, `cursor`, `opencode`, `antigravity`, `copilot`, `deepseek`) or deduplicating workspace rules |
+| **Workspace & Benchmarks** | `simt compare`, `simt bench mine\|run\|report\|ablate\|probes\|variants`, `simt local doctor` | `compare` | When auditing an entire multi-repo estate, measuring rule uplift/cost, or probing local model endpoints |
+
+## Where the plan finishes
+
+Slices `R01`–`R45` are complete and shipped in `0.6.0`. The remaining queued slices are the
+small ergonomics:
+
+- **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
+  plus a staged-diff secret scan, `simt slice start/finish <ID>` worktrees, file leases
+  for parallel agents, and `simt pr-body` assembled from the evidence ledger.
+
+The local-model slices (`R38`–`R40`) shipped as they lab-written: `simt distill` proposes
+budgeted summaries with line citations, `simt review` proposes an advisory ADR-008
+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.
 
 ## What it writes
 
 | Path | What |
 | --- | --- |
-| `AGENTS.md` | the projection, between `<!-- simt:begin -->` and `<!-- simt:end -->`. The old `simt-dev:` markers are still read, and a region migrates on its next write |
-| `simt.json` | the manifest: gates, substitutions, budget, shared rules, surfaces |
-| `simt-dev.lock.json` | the digest of the inputs and the digest of the projection |
+| `AGENTS.md` (and `<package>/AGENTS.md` in monorepos) | the projection, between `<!-- simt:begin -->` and `<!-- simt:end -->`. The old `simt-dev:` markers are still read, and a region migrates on its next write |
+| `simt.json` | the manifest: `gates`, `substitutions`, `budget`, `mode`, `shared`, `surfaces`, `plans`, `packs`, `federation`, `local` |
+| `simt-dev.lock.json` | the digest of the inputs, the digest of the projection, and locked `variants` winners from `simt bench variants` |
 | `.cursor/rules/*.mdc`, `.claude/rules/*.md`, `.agents/rules/*.md`, `.github/instructions/*.instructions.md` | one file per rule, and only for a harness that reads that directory |
 | `.editorconfig`, `.gitattributes` | baseline regions, placed first so a later setting still wins |
 | `.simt-hooks/` and `core.hooksPath` | the shared dispatcher. It fails closed |
+| `docs/decisions/ADR-NNN-<slug>.md` | numbered decision records scaffolded by `simt decide --yes` with `simt-affects` and `simt-supersedes` frontmatter |
+| `docs/lessons/NNNN-<slug>.md` | reviewed lessons promoted by `simt lessons review <id> --yes` with `simt-trigger`, `simt-evidence`, and `simt-expires` frontmatter |
 
 Text outside the markers is left alone. A regeneration does not revert it.
 
 `simt.json` also carries a `federation` block when the repository names external
-code-graph servers, each with the command that starts it. A brief may then ask one of
-them one structural question for a task and cite the answer's source, and the MCP
-`federation_query` tool asks one on demand, naming the server it asked. The question goes
-to the tool and argument the manifest declared, so no foreign tool is reachable that the
-repository did not name. Nothing is started unless the manifest declared it, and a server
-that does not answer costs the packet a sentence, never the packet.
+code-graph servers, each with the command that starts it, and an optional `local` block
+when the repository names loopback OpenAI-compatible `chat` or `embed` endpoints. A brief
+may then ask a federated server one structural question for a task and cite the answer's
+source, and the MCP `federation_query` tool asks one on demand, naming the server it
+asked. The question goes to the tool and argument the manifest declared, so no foreign
+tool is reachable that the repository did not name. Nothing is started and no socket is
+opened unless the manifest declared it, and a server that does not answer costs the
+packet a sentence, never the packet.
 
 These are caches, gitignored, and rebuildable. They are not repository content:
 
 | Path | What |
 | --- | --- |
-| `.simt-dev/index.sqlite` | files, symbols, import edges. JSON-lines at `.simt-dev/index.jsonl` when this Node cannot open `node:sqlite` with FTS5 |
-| `.simt-dev/ledger.jsonl` | one line per gate the dispatcher actually ran, against one git tree |
-| `.simt-dev/bench/runs/` | benchmark runs |
+| `.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`