simt-dev 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,176 @@ All notable changes to this package are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-10-20
+
+### Hybrid retrieval fuses BM25, the code graph, and the resolver
+
+`simt index` indexes full-text tokens across `code`, `docs`, `skills`, `decisions` and
+`lessons` into the SQLite FTS5 `fts` table (with an Okapi BM25 fallback when the index is
+JSON-lines). `simt map` and `simt brief` fuse FTS5 `bm25()`, PageRank graph proximity and
+resolver signals with reciprocal-rank fusion (`RRF_K = 40`), raising gold-file recall@10 on
+the 20 mined tasks here from 54.3% to 61.3% (above the 60% bar in ADR-091). With `--embed`
+and a configured `local.embed` endpoint, `simt index` stores `Float32Array` vector blobs in
+the `embeddings` table and `simt map --embed` adds brute-force cosine similarity; embeddings
+stay off by default unless they raise recall@10 by at least 10 percentage points.
+
+### A local model adapter that opens zero sockets until named
+
+`simt local doctor` probes the OpenAI-compatible `local.chat` and `local.embed` endpoints
+declared in `simt.json` (`/v1/models`, `/v1/chat/completions`, `/v1/embeddings` for Ollama,
+`llama-server`, LM Studio and MLX servers) and reports reachability, model presence and
+latency. Non-loopback URLs are refused unless `--allow-remote` is given (ADR-075, ADR-090),
+and when `local` is unset nothing opens a socket.
+
+### Estate learning and ADR drafts across a workspace
+
+`simt compare --learn` aggregates benchmark uplift (`ΔR`, `ΔC`) per rule section across
+adopted sibling repositories, promotes lessons repeated across at least two repositories as
+shared candidates, and flags gates that fail more than 20% of the time as `NOISY-GATE`.
+`simt compare --draft-adr <pattern>` writes a proposed ADR draft under `docs/decisions/`
+carrying `Origin: simt compare --draft-adr` and the workspace evidence behind it.
+
+### Rule text variants have to win on the bench
+
+A rule may declare candidate wordings under `simt-variants:` in its frontmatter (or supply
+them with `--variants-file`). `simt bench variants <rule-id>` evaluates each candidate on
+paired benchmark runs with McNemar on resolved rate and Wilcoxon signed-rank on cost,
+promotes a wording only when `ΔR > 0` (or `ΔR == 0` and `ΔC < 0`) at `p < 0.05`, and records
+the winning variant and its `p`-value in `simt-dev.lock.json`.
+
+### Decision records carry structured supersession frontmatter
+
+`simt decide "<title>"` scaffolds the next numbered ADR in `docs/decisions/` with structured
+frontmatter (`Status`, `Date`, `Supersedes`, `Superseded-by`, `Affects`) and updates the
+records it supersedes when `--supersedes` and `--yes` are given. `simt rules lint` reports
+`PARTIAL-SUPERSEDE` when prose claims to supersede part of an earlier record without
+matching frontmatter links.
+
+### Lessons are captured from failure-to-fix pairs, recalled on match, and expire
+
+When a failing gate or test run in `.simt-dev/ledger.jsonl` is followed by a passing run on
+the same package, `simt lessons` records a deterministic candidate in
+`.simt-dev/lessons-candidates.jsonl`. `simt lessons promote <id> --yes` writes a reviewed
+lesson to `docs/lessons/<id>.md` with `Paths`, `Check`, `Expires` and `ADR` fields, and
+`simt check` reports `LESSON-EXPIRED` once the date passes or the linked ADR is superseded.
+Matching lessons (at most two) are recalled in `simt brief` and by `simt agent-hook
+after-tool` when a tool call fails on the same package or error signature.
+
+### Skills compile to the Agent Skills standard and report their triggers
+
+`simt skills compile` validates and compiles skill sources against the Agent Skills standard
+(frontmatter `name` and `description`, description under 1024 characters, `SKILL.md` body at
+most 500 lines, and on-demand `references/` and `scripts/` links). `simt skills triggers
+"<prompt>"` previews which skills match a task and the score breakdown behind each match.
+
+### A task brief fits in the bytes a prompt can carry
+
+`simt brief "<task>"` assembles what a task needs into one packet: the kind of the task
+and the commands that kind needs, the files the map ranks highest, the tests the index
+knows for them, the decisions that govern them, the skills the resolver selects, the
+lessons that name those paths, and the cautions — dirty files to leave alone, generated
+paths, files no test covers. The packet stays inside `--budget` bytes (2048 by default,
+`0` for all of it), ends with the number of items it had to cut, and prints the same bytes
+on the same tree; `--explain` prints every item with the reason it was kept or dropped.
+The accept figure it was designed against — 20% fewer turns, 15% cheaper than the kernel
+arm at no loss of resolved rate — is unmeasured here, because it needs a bench run and an
+installed agent CLI and neither is on this machine. `simt skills brief` keeps its own
+behaviour for now: retiring it changes two accepted decisions and an MCP output schema,
+and this slice carries no decision to do it.
+
+### The packet arrives without being asked for
+
+A repository that declares a `brief` key in its manifest gets the packet injected as context
+before every prompt: `simt agent-hooks install` writes a `UserPromptSubmit` hook into Claude
+Code's and Codex's own config, and `simt agent-hook prompt-submit --harness <id>` answers in
+that harness's dialect with `hookSpecificOutput.additionalContext`. It never decides and never
+exits 2 — no prompt text, no opt-in, a cold index or an assembly error all print why on stderr
+and exit 0. The injection is capped at 2048 bytes; `brief.bytes` may lower that and may not
+raise it. Cursor and Gemini CLI are not in the table: Cursor's prompt event can only block a
+prompt, and Gemini CLI's replacement is not in the reader table. The pre-tool path pays nothing
+for this — the repository is reached through a dynamic import only a prompt event opens. MCP
+gains a `brief` tool so a client can pull the same packet, assembled by the same code as the
+command.
+
+### A brief can cite a code graph it did not build
+
+A repository may declare a `federation` block in `simt.json` naming external code-graph
+servers, each with the command that starts it and, optionally, the MCP tool to ask, the
+argument the question goes in, the languages it covers and the timeout to wait. `simt brief`
+and the MCP `brief` tool then ask each declared server one structural question for the task
+and add the answer to a `FEDERATION` section that names its source; a `covers <languages>`
+line records what a server claims without yet skipping the index's own extraction of those
+languages. The list is the repository's own committed declaration, the same trust model as
+`gates.commands`, and nothing is started that the manifest did not name. A malformed entry, a
+spawn failure, a protocol error or a timeout all become a caution and the brief still exits
+`0`; a server that never answers is bounded by its own per-server timeout. MCP also gains a
+`federation_query` tool, which asks a named server (or every declared one) one structural
+question on demand and returns the answer with its source; like the brief's fan-out it goes
+only to the tool and argument the manifest declared. The packet delivered at prompt submit
+does not federate — starting someone else's process is not a wait a 300 ms submit may take.
+
+## [0.3.1] — 2026-10-18
+
+### Who a change reaches
+
+`simt impact` takes a tracked path or the name of one export. It lists the files that import it, the tests of that closure, the decisions and rules that govern the file, and the last matching CODEOWNERS line. In a workspace it also lists another repository that references an OpenAPI document or a JSON Schema file this change touches. Each list stops at 64 (ADR-096).
+
+### A gate report keeps the failures and counts the passes
+
+`simt gate` compacts a report it knows how to read: TAP, JUnit XML, pytest's junit file, vitest or jest JSON, and `go test -json`. Failures come first, with the name, the assertion and the location. Passing tests are a count. The raw log path is printed. Anything else is printed unchanged (ADR-095).
+
+### A change runs the tests that import it
+
+`simt gate` selects the test files that import a changed file, directly or through other files, and runs only those with the package's own runner. Paths name the change. `--changed` reads the diff. A clean diff runs nothing. Changing `src/resolve/resolve.mjs` in this checkout selects 51 files, the hand-built list, in about 40 ms. The bar is 5 seconds (ADR-094).
+
+### what governs a file is the decision, rule, skill, gate or lesson that names it
+
+`simt why` reads an Affects line as the tokens in backticks, including a line the paragraph wraps onto. A token that is a command, a path, or a glob is an edge. A token that is none of those is printed as `UNRESOLVED-AFFECTS`. Rules, skills, gates and lessons contribute the path lists they already publish. At `4c27514` every one of the sixteen Affects tokens resolves or is reported, and ADR-017 is the only record that names the dispatcher (ADR-093).
+
+### The tests of a file are its importers, its conventional neighbour, and its coverage
+
+`simt tests` lists the tests that exercise a file. An import counts, including one whose specifier is on the next line and a dynamic `import()`. So does the conventional source beside the test, and a coverage record that names both sides. Files that only share commits are a separate list, added with `--cochange`. On 30 hand-labelled files in this checkout every predicted test is in the label. The bar is 0.8 (ADR-092).
+
+### The map ranks the files a task is likely to touch
+
+`simt map` orders the index by the task's words and by the import and call edges around them. It renders paths, exported names, or signatures, inside a byte budget. `simt bench report` prints recall@10: the mean fraction of a mined task's gold files that land in the top 10. On the 20 mined tasks measured here that figure is 55.6%. The bar is 60% (ADR-091).
+
+### The index names the exports and the imports
+
+`simt index` fills symbols and import edges from the blob it already hashes. The built-in extractors are line-oriented, for the languages a map needs, and on the labelled fixtures they recall at least 90% of the exported names for TypeScript, Kotlin, Python and Go. A structural parser is a separate package named by `index.parsers`; with that key absent, nothing is loaded. It writes cache rows and does not edit the repository. A live comparison against tree-sitter is unmeasured (ADR-090).
+
+### The local index is a cache of git blobs
+
+`simt index` rebuilds `.simt-dev/index.sqlite` from `git ls-files`. A blob that has not changed is not read again, and the same blobs produce the same rows. When this Node cannot open `node:sqlite` with FTS5, the same rows are written to `.simt-dev/index.jsonl` instead (ADR-089).
+
+### A marked line is enforced by a checker
+
+A rule line may name a checker with `simt-check`. The projection keeps `Enforced:` and the checker's name, and `simt check` runs the checker. The file-length line is `max-file-lines`: past 400 lines warns, past 1000 fails, and a path is exempt only when `limits.fileLines.generated` names it. A path under `node_modules` is not counted: a committed dependency is not a file this repository wrote, and counting it failed every install of this package. A file-length warning and a checker that is not built yet are reported and do not fail `check` or `sync`. `import-direction` stays in the prose until the module graph exists. Probe compliance is unmeasured (ADR-088).
+
+### A run is evidence for one tree
+
+`simt evidence` prints the runs recorded against the tree on disk. A gate the dispatcher runs appends a line: the command, the exit, a short summary, and a digest of the output. Editing any file changes the tree, so that line no longer applies. `simt evidence check` warns when a commit message says the tests passed and this tree has no passing line, and fails the commit when `gates.evidence` is `block`. `simt hooks install --yes` writes the commit-msg shim only when that setting is present (ADR-087).
+
+### A workspace carries its repeated rules once
+
+`simt shared plan` names the rules every repository in a workspace renders with the same bytes, and where each harness would load that copy. `simt shared install --yes` writes the copy into the user-level file the harness actually reads, and records the ids on each repository's manifest under `shared`. The next `simt sync` drops those rules from the region and names them, with the command that shows each one. `simt doctor` says when the copy is missing or stale, and does not fail the repository for it. The 30 KB estate bar and the bench comparison are unmeasured (ADR-084).
+
+### The region ends with the names of what it kept out
+
+The generated region ends with a `## Disclosure` section: one line per scoped profile, with the patterns and the files it moved to, and one line per installed skill, with its name and the description that says when to open it. The skill body stays in its file. A surface that cannot narrow a profile still carries that profile in the region (ADR-085).
+
+### The stable prefix comes first
+
+Shipped rules lead the region, and the command card follows them, so an edit this repository makes changes only the tail. `simt sync --yes` writes `simt-dev.lock.json` with an input digest and an output digest. `simt check --frozen` fails when the output moves and the inputs did not, and names a stale lock separately (ADR-086).
+
+### Kernel mode packs to the budget the repository declared
+
+`mode: kernel` reads `budget.bytes`, holds back a reserve for the files that load beside the region, and drops rules least-valuable-first until the region fits. Every cut rule is named, with the command that shows it. `full` mode cuts nothing. A repository whose hard rules already exceed the budget is told so, and those rules stay (ADR-083).
+
+### Vulnerability reports
+
+`SECURITY.md` names the two places a report goes: a GitHub issue on this repository, or `security@simt.space`.
+
 ## [0.3.0] — 2026-10-17
 
 ### The rules and the decisions are readable as MCP resources
@@ -563,6 +733,8 @@ 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.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
 [0.2.2]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.2.2
 [0.2.1]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.2.1

package/README.md

@@ -1,54 +1,117 @@
 # simt-dev
 
-Shared agent rules, skills and git hooks for a repository.
-
-One command adopts a repository: it reads what the repo actually runs, projects the
-matching rules into the files your agent already reads, and installs a pre-commit hook
-that refuses a commit which breaks a gate that repo can genuinely run.
-
-- **Nothing is declared that cannot run.** Every gate is probed against the working tree
-  before it is written. A gate whose tool is absent is dropped, with a remedy naming the
-  package to install — never silently present, never silently absent.
-- **Nothing an agent reads is written twice.** Each rule goes to exactly one place, chosen
-  by what the harness actually reads.
-- **The rules are a projection, not a copy.** They carry markers, so `check` can tell
-  drift from a deliberate edit, and `sync` can regenerate.
-- **The tool explains itself.** `rules why` answers "why did I get told this?" from a
-  numbered record of the decisions behind the rules, with the rejected alternatives
-  attached.
+![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.
+
+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
+can run. Around that projection it keeps the bytes stable, replaces an instruction
+with a check where a check can decide, answers questions about the tree from a local
+index, and records whether a run still applies to the tree on disk.
+
+The aim of the whole design is a higher share of tasks resolved, at a lower cost per
+resolved task. Those targets are hypotheses. A change that touches what an agent reads
+ships with a measurement, or its record says the measurement was not run. `simt rules
+why ADR-NNN` prints the record, including whether it is still in force.
+
+The default path is deterministic: no model, no network, no runtime dependencies.
+Anything that needs a parser grammar, a local model, or another server is a separate
+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 PyPI install can supply it, see below).
+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.
 
 ```sh
-# pinned, per repository - what CI and a teammate both get
-npm i -D simt-dev@0.2.1
+npm i -D simt-dev@0.4.0
 
-# or globally, if you would rather not add a dependency
-npm i -g simt-dev@0.2.1
+# or globally
+npm i -g simt-dev@0.4.0
 
-# or with no install at all, for a one-off
-npx -y simt-dev@0.2.1 check
+# or once, with no install
+npx -y simt-dev@0.4.0 check
 ```
 
 ### From PyPI
 
-The same tool, from the same bytes. The wheel carries the exact contents the npm
-tarball carries — the wheel is not a wrapper around `npm install`, so nothing is
-fetched when you install it.
+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
 
-# and if this machine has no node at all
+# when this machine has no node
 pip install "simt-dev[node]"
 ```
 
-`simt` is the command on both channels. Where node comes from is resolved in
-this order, and the first one that answers wins: `SIMT_DEV_NODE`, the bundled
-node from the `node` extra, then `node` on your `PATH`. If none of them resolve,
-you get a message naming the remedy rather than a placeholder node path.
+`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
 
@@ -56,65 +119,66 @@ you get a message naming the remedy rather than a placeholder node path.
 brew install QuazarMedia/homebrew-tap/simt-dev
 ```
 
-The formula declares its own `node` dependency, so `brew install` gives you a
-working command on a machine that has never had Node.
+The formula depends on `node`, so the command works on a machine that has never had
+Node installed.
 
-Pin the version. The tool writes a content digest into the files it generates, and an
-unpinned upgrade changes them under you.
+## What it writes
 
-## Use
+| 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 |
+| `.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 |
 
-```sh
-simt init            # adopt or scaffold this repository (dry-run; --yes to write)
-simt doctor          # what this repo is, and whether its config is healthy
-simt check           # the gate: projection drift, manifest validity, policy
-simt sync --yes      # regenerate the projection
-simt upgrade --yes   # move every consumer of this tool to this version
-simt rules why ADR-042   # why a rule says what it says, and what was rejected
-simt compare         # what changed across every repository that adopted it
-```
+Text outside the markers is left alone. A regeneration does not revert it.
 
-`init` and `sync` print a plan and write nothing without `--yes`. Neither commits or pushes.
+`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.
 
-## What it writes
+These are caches, gitignored, and rebuildable. They are not repository content:
 
 | Path | What |
 | --- | --- |
-| `AGENTS.md` | the projection, between `<!-- simt:begin -->` and `<!-- simt:end -->` (renamed from `simt-dev:`; the old markers are still read, and a region migrates on its next write) |
-| `simt.json` | your manifest: which gates to declare, which substitutions to fill |
-| `.cursor/rules/*.mdc`, `.claude/rules/*.md`, `.agents/rules/*.md`, `.github/instructions/*.instructions.md` | one file per rule, written only for the harnesses that read their own directory |
-| `.editorconfig`, `.gitattributes` | baseline regions |
-| `.simt-hooks/` and `core.hooksPath` | the shared dispatcher, fail-closed |
+| `.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 |
 
-Anything outside the markers is yours. simt-dev never edits it and never reverts it.
+`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
+repository's manifest. The next `sync` drops those rules from the region and names
+them.
 
-## Platform
+## How a rule is chosen
 
-**macOS and Linux.** The hooks are POSIX `sh`; there is no Windows build and no plan for
-one. `npm i` on Windows fails with npm's `EBADPLATFORM`, which npm will not let a package
-explain — so the answer is here: **use WSL2**, and the gate works normally inside it.
+Detection reads dependency manifests, build files and CI workflows, and ranks rules
+by path, keyword, name, capability and stack. The ranking is a score. A pull request
+can diff it.
 
-A Windows checkout without WSL2 can still read every rule this tool generates, because the
-projection is plain text in `AGENTS.md` and the per-harness rule files. Only the hooks and
-the CI gate need the POSIX host.
+A repository whose ecosystem has no profile yet is still adopted: it gets the core
+rules and no gates, until gate templates exist for it. A hook that would run nothing
+is not installed.
 
-## How the rules are chosen
+Every behaviour that is a choice has a numbered record. `simt rules why <id>` is the
+path from a rule you did not expect to the reason it is there.
 
-Detection reads what the repository runs — its dependency manifests, its build files, its
-CI workflows — and resolves that against a registry of capabilities. Resolution is a
-scored ranking over path, keyword, name, capability and stack: no model, no network, no
-guessing, so a pull request can meaningfully diff the answer.
+## Platform
 
-**Not every ecosystem has a profile yet.** A Go, Rust, .NET, Ruby, Swift, Dart or Elixir
-repository is detected and gets facts, but it is adopted with the core rules and no gates
-until its gate templates are written. A repository with no gates is a repository with an
-agent and no pre-commit hook — better than one with a hook that runs nothing, but not full
-support, and this README will not pretend otherwise.
+**macOS and Linux.** The hooks are POSIX `sh`. There is no Windows build. `npm i` on
+Windows fails with npm's `EBADPLATFORM`, which npm will not let a package explain, so
+the answer is here: **use WSL2**, and the gate works inside it.
 
-Every behaviour that is a choice rather than a detail has a numbered record, and the
-records are readable with `simt rules why <id>`. If the tool ever does something you
-did not expect, that command is the shortest path from the symptom to the reason.
+A Windows checkout without WSL2 can still read the projection. It is plain text. The
+hooks and the CI gate need the POSIX host.
 
 ## Licence
 
-Apache-2.0. See [LICENSE](LICENSE).
+Apache-2.0. See [LICENSE](LICENSE). Report a vulnerability through
+[SECURITY.md](SECURITY.md).

package/docs/decisions/ADR-073-a-kernel-is-a-smaller-projection-the-repository-asks-for.md

@@ -1,6 +1,6 @@
 # ADR-073 — A kernel is a smaller projection the repository asks for, not one it is given
 
-Status: **accepted** · 2026-10-14 · filed as S38 (R07)
+Status: **accepted** · 2026-10-14 · filed as S38 (R07) · ruling 6 narrowed by ADR-084
 **Affects:** `src/projection/manifest.mjs`, `src/projection/rules.mjs`, `src/measure/context.mjs`,
 `rules/core.md`, `rules/stacks/*.md`, `test/kernel.test.mjs`
 

package/docs/decisions/ADR-077-the-command-card-leads-the-region-and-reads-committed-evidence.md

@@ -1,6 +1,6 @@
 # ADR-077 — The command card leads the region, and is derived from committed evidence only
 
-Status: **accepted** · 2026-10-16 · filed as R10 (plan 0003)
+Status: **accepted** · 2026-10-16 · filed as R10 (plan 0003) · ruling 1 narrowed by ADR-086
 **Affects:** `src/kernel/card.mjs`, `src/projection/rules.mjs`, `rules/core.md` (indirectly, as
 the region's first bytes), `test/card.test.mjs`
 

package/docs/decisions/ADR-083-a-budget-is-met-by-cutting-the-kernel-and-hard-is-the-floor.md

@@ -0,0 +1,153 @@
+# ADR-083 — A budget is met by cutting the kernel, and the hard constraints are the floor
+
+Status: **accepted** · 2026-10-17 · filed as R08 (plan 0003) · ruling 7 narrowed by ADR-084
+
+**Affects:** `src/kernel/budget.mjs`, `src/projection/rules.mjs`, `src/projection/manifest.mjs`,
+`src/measure/context.mjs`, `src/projection/project.mjs`, `src/commands/sync.mjs`,
+`test/kernel.test.mjs`, `test/tokens.test.mjs`, `test/surfaces.test.mjs`
+
+## Context
+
+ADR-072 shipped the number: `budget.bytes` at the top level of the manifest, 30 000 bytes by
+default, reported by `simt tokens` and raised by `check`, both non-blocking. It recorded what had
+not landed and why — the packing needed a kernel, and the kernel was R07.
+
+ADR-073 shipped the kernel. A repository declares `mode: kernel`, every rule declares its class
+in its own frontmatter, and the mode packs `hard` and `command` while naming everything else in
+the region with the command that fetches it. R08's accept criterion — the budget is never
+exceeded — is now reachable, and this record is the part that reaches it.
+
+Three facts about the number made the shape of this a decision rather than a loop.
+
+The first is that the budget is one number and the meter bills more than the region. A generated
+rule file is billed whole, a managed skill by its name and description, the region by the span
+between its markers. A repository whose rules live in per-rule files has paid for those files
+whether or not the region fits; packing the region against the whole declared number ships a
+projection that fits on its own and is over the line the moment its rule files are written. On a
+fixture with a Cursor surface, three `.mdc` files billed 6,552 B beside a 15,725 B region.
+
+The second is the region's own span. It is the one number that moves when the projection is
+packed, so a ceiling derived from it would make `sync` rewrite the file it had just written and
+then report drift on a clean tree.
+
+The third is what ADR-072 already ruled and R08's text has not caught up with: the key is
+`budget.bytes`, not `projection.budget.bytes`. The plan is not edited. `projection` is a
+generated key, `upgrade` replaces it wholesale, and a budget written there would disappear on a
+green gate.
+
+## Rulings
+
+1. **One reader for the declared number.** `declaredBudget(manifest)` in `manifest.mjs` is the
+   only place `budget.bytes` is interpreted, and both the packer and `measureRoot` call it. A
+   finite non-negative value is taken as declared, including `0` — "this repository wants an
+   empty projection" is a decision somebody can make — and anything else (a string, `NaN`, a
+   negative) falls back to the review figure, because the one reading that cannot silently
+   produce compliance is the one where a typo is not a ceiling.
+
+2. **Nothing is cut in `full` mode.** ADR-072's finding already tells the reader "nothing was cut:
+   the projection is still in full mode", and a full projection that quietly lost a rule would
+   make the tool lie about itself in its own words. `desiredRegion` returns `budget: null` there,
+   not an empty cut list, so a reader of the field cannot conclude a cut happened when the mode
+   made none possible.
+
+3. **`hard` is the floor.** A priority class exists to say what a reader loses by not having the
+   line, and a byte count is not a reader. The packer skips `hard` instead of cutting it, and the
+   leftover is a distinct fact — `floorHeld` — reported as such: the notes say the kernel is still
+   over after every rule outside the hard class went, and that a hard constraint is not cut to
+   reach a byte count. The levers that remain are the repository's own, which is exactly what
+   ADR-072's kernel wording already tells the reader. One case gets its own sentence: when the
+   reserve alone reaches the declared budget the ceiling is zero or less, which is arithmetically
+   true and unreadable — it does not say that the files loading beside the region already spent
+   the whole budget — so the notes say that, because a reader left to infer it from a subtraction
+   is a reader who demotes a hard rule to fix a number they set too low.
+
+4. **The ceiling is the declared budget minus a reserve, and the region's own span is in
+   neither term.** The reserve is the larger of what the meter already bills outside the region
+   (what is installed) and what this projection is about to write as rule files (what a
+   repository that has not run `sync` yet will pay). Both are lower bounds; the larger is taken
+   because the failure each would otherwise cause is the one that must not happen — under-
+   reserving reports compliance for a projection that is over. The region's span is excluded
+   deliberately, per the second fact above. A folded single-surface repository reserves nothing,
+   which is correct rather than untested: `opencode` reads `AGENTS.md` and writes no rule files,
+   so there is nothing beside the region to pay for.
+
+5. **The cut order is the region's own order reversed, and it is fixed before any cost is
+   computed.** Class, then rule id — the comparator the deferred section already uses, least
+   valuable first. Which class a reader can best afford to lose is declared by the rules
+   themselves (ADR-073 ruling 3); what is left here is arithmetic, so the order is handed in and
+   the module that packs does not second-guess it.
+
+6. **A cut costs what the document then weighs, not the rule's own length.** Three things move
+   when a rule leaves: the provenance header drops a source, the deferred section gains a line
+   naming what left, and both move again as the cut list grows. So each attempt re-renders the
+   region and weighs it — `costs(cut)` returning `Buffer.byteLength(compose(...))`, markers and
+   provenance header included, one byte conservative because the file's trailing newline falls
+   outside the meter's span and conservative is the only direction a ceiling can afford. The loop
+   stops the moment it fits, so a budget never costs a rule it did not have to. This is the
+   command card's `CARD_LIMIT_BYTES` idiom (ADR-077) applied to the region instead of the card.
+
+7. **One list, two reasons.** Class-deferred and budget-cut rules share the region's existing
+   `## Deferred rules` section, and each line says which it was: `deferred in kernel mode` or
+   `cut to fit the declared budget of N bytes`, both naming `simt rules show <id>`. A second
+   heading would spend region bytes on a distinction the reader acts on identically, and a cut
+   line that did not say why would be indistinguishable from a kernel decision nobody made.
+
+8. **`BUDGET-CUT` is a finding, non-blocking in both commands, and carries the numbers a reader
+   needs to judge it.** The detail gives `before → after`, the declared budget, the reserve when
+   it is not zero, and every cut rule by id and class; the remedy is a decision
+   (`raise budget.bytes to <before + reserve>`, the budget that would have admitted the region
+   as it stood — `before` alone would leave the cut in place, because the ceiling it was cut
+   against is the budget less the reserve), not a place to go and look. Non-blocking for ADR-072's
+   reason: the cut is the tool doing what the repository asked, and a gate that failed here would
+   fail a repository for shipping a smaller projection. `sync` prints the same two facts as notes
+   so the cut is never silent from either command.
+
+9. **`simt tokens` keeps no second opinion.** ADR-064 kept the meter to one measurement, and the
+   packer's arithmetic is not substituted for it anywhere: the meter reports the bytes it finds
+   against the declared line, and the end-to-end test judges the cut with the meter's number
+   rather than the packer's. A packer that reports compliance for a projection the meter says is
+   over budget is the failure this arrangement is arranged against, so the test asserts the
+   meter's number even where the packer's own numbers are already visible in the same object.
+
+## Consequences
+
+A repository that declares `mode: kernel` and a budget its rules do not fit gets a smaller
+projection, a list of what left and why, and a note from both `sync` and `check`. The accept
+criterion is checkable end to end rather than asserted: a fixture declares a budget a thousand
+bytes under its own projection, syncs, and `simt tokens` reports `over: false` with the declared
+line intact — and a second fixture, whose rule files are billed beside the region, is cut further
+than the region alone would have needed, which is the only way the reserve can be seen to work.
+
+The costs are accepted rather than avoided. In kernel mode a projection is now measured
+(`measureRoot`) and its rule targets rendered a second time (`ruleTargets`) on every
+`desiredRegion`, where previously the region's bytes were composed once. `measureRoot` is reached
+through `await import` inside `budgetReserve` because `measure/context.mjs` already imports
+`readLimitFindings` from `projection/project.mjs`; a static import from `rules.mjs` would close a
+three-module loop that has to survive being loaded in any order.
+
+Determinism is structural and partly argued. `packToBudget` takes its cost function as an
+argument and reads no clock, no network and no PATH, so the cut set is a function of the rules,
+the classes, the ids and the declared number; the test that renders one repository twice catches
+the failure a test can catch, which is state leaking between calls. Two machines is the claim
+R08 actually makes and no test in this repository can execute it — the argument is the one ADR-073
+ruling 7 already makes.
+
+What has not landed, and is not this slice's to land: R02's evaluation, which is still what would
+justify `kernel` as a default rather than a repository's own choice; and the cross-machine half
+of the accept criterion, which is argued from the code's inputs rather than demonstrated.
+
+## Rejected
+
+- **Cutting in `full` mode.** The mode is a promise about what a reader gets, and the number in
+  ADR-072's finding says nothing was cut; making that sentence untrue to save bytes is the tool
+  misreporting itself.
+- **Cutting `hard` to reach the line.** It would remove the one class whose claim is that its
+  absence is a defect, and report the result as compliance.
+- **A second `## Cut` section beside `## Deferred rules`.** Two headings for one reader-facing
+  fact, and the second one spends bytes to be distinguished from the first.
+- **Subtracting each rule's own length instead of re-rendering.** The provenance header and the
+  deferred line both change when a rule leaves, so the arithmetic would either overshoot or stop
+  short — and it would be a second definition of the region's size next to the meter's.
+- **A binary search or two-pass packer.** The cost function is called once per candidate and the
+  candidate list is the length of the kernel; a cleverer search would add a failure mode to a
+  loop whose whole value is that it is the same computation every time.