simt-dev 0.3.0__tar.gz → 0.4.0__tar.gz

{simt_dev-0.3.0 → simt_dev-0.4.0}/.gitignore

@@ -12,5 +12,7 @@ dist/
 # Local index, evidence ledger and benchmark run outputs (plan 0003 §4).
 # Task descriptors in .simt-dev/bench/tasks/*.json are committed; runs are not.
 .simt-dev/index.sqlite
+.simt-dev/index.jsonl
 .simt-dev/ledger.jsonl
 .simt-dev/bench/runs/
+.simt-dev/gate/

{simt_dev-0.3.0 → simt_dev-0.4.0}/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

simt_dev-0.4.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: simt-dev
+Version: 0.4.0
+Summary: Shared agent rules, skills and git hooks for a repository: one command adopts a repo, and every gate it declares is probed before it is written.
+Project-URL: Homepage, https://github.com/QuazarMedia/simt-dev
+Project-URL: Repository, https://github.com/QuazarMedia/simt-dev
+Project-URL: Changelog, https://github.com/QuazarMedia/simt-dev/blob/main/CHANGELOG.md
+Author: Said Elimam
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,agents,ai,codex,cursor,git-hooks,llm,rules,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: node
+Requires-Dist: nodejs-wheel-binaries; extra == 'node'
+Description-Content-Type: text/markdown
+
+# simt-dev
+
+![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 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
+npm i -D simt-dev@0.4.0
+
+# or globally
+npm i -g simt-dev@0.4.0
+
+# or once, with no install
+npx -y simt-dev@0.4.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 |
+| --- | --- |
+| `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 |
+
+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.
+
+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 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.
+
+## How a rule is chosen
+
+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 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.
+
+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.
+
+## Platform
+
+**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.
+
+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). Report a vulnerability through
+[SECURITY.md](SECURITY.md).

simt_dev-0.4.0/README.md

@@ -0,0 +1,184 @@
+# simt-dev
+
+![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 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
+npm i -D simt-dev@0.4.0
+
+# or globally
+npm i -g simt-dev@0.4.0
+
+# or once, with no install
+npx -y simt-dev@0.4.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 |
+| --- | --- |
+| `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 |
+
+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.
+
+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 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.
+
+## How a rule is chosen
+
+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 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.
+
+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.
+
+## Platform
+
+**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.
+
+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). Report a vulnerability through
+[SECURITY.md](SECURITY.md).

{simt_dev-0.3.0 → simt_dev-0.4.0}/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`
 

{simt_dev-0.3.0 → simt_dev-0.4.0}/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`