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

{simt_dev-0.3.0 → simt_dev-0.3.1}/.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.3.1}/CHANGELOG.md

@@ -6,6 +6,68 @@ All notable changes to this package are recorded here. The format follows
 
 ## [Unreleased]
 
+## [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 +625,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.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.3.1/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: simt-dev
+Version: 0.3.1
+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` 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.3.1**. 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.3.1
+
+# or globally
+npm i -g simt-dev@0.3.1
+
+# or once, with no install
+npx -y simt-dev@0.3.1 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.
+
+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.1/README.md

@@ -0,0 +1,174 @@
+# simt-dev
+
+`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.3.1**. 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.3.1
+
+# or globally
+npm i -g simt-dev@0.3.1
+
+# or once, with no install
+npx -y simt-dev@0.3.1 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.
+
+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.3.1}/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.3.1}/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`
 

simt_dev-0.3.1/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.