simt-dev 0.2.2 → 0.3.1

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.

package/docs/decisions/ADR-084-a-workspace-carries-its-repeated-rules-once.md

@@ -0,0 +1,100 @@
+# ADR-084 — A workspace carries its repeated rules once, and the region does not read the reader's home
+
+Status: **accepted** · 2026-10-17 · filed as R11 (plan 0003)
+
+**Affects:** `src/projection/shared.mjs`, `src/commands/shared.mjs`, `src/projection/rules.mjs`,
+`src/projection/manifest.mjs`, `src/projection/markers.mjs`, `src/commands/tokens.mjs`,
+`src/commands/index.mjs`
+
+## Context
+
+The same rules are projected into every repository of a workspace, and each repository's
+region carries the full text. The plan asked for the intersection to be installed once, at
+user level, and for a repository to switch to the remainder when its manifest said
+`projection.shared`. It also named home paths for four harnesses, and said CI should keep
+rendering the full region so a teammate without the user file loses nothing in review.
+
+Two of those would not survive contact with the rest of the tool. `projection` is generated:
+`upgrade` replaces it, which is why a repository's own budget already lives beside it rather
+than inside it. And a region that is full in CI and short on a reader's machine is a region
+`check` cannot agree with, because `check` renders the same function the reader gets.
+
+## Rulings
+
+1. **The unit that is shared is a rule, and only a rule every repository renders with the
+   same bytes.** The meter can report a repeated paragraph; it cannot store one, and
+   `simt rules show` prints one rule. A rule one repository does not ship, or renders
+   differently, stays in every region. The comparison is the rendered text, because one
+   repository can drop a line the others keep.
+
+2. **The declaration is `shared` on the manifest, beside `budget` and `mode`.** `level` is
+   `user` and `rules` is the list of ids. It is not a key of `projection`, because that
+   object is replaced on upgrade. A missing key, a level other than `user`, or an empty
+   list means the region carries everything it carried before. A value that is not that
+   shape is an error from the one reader the region, `doctor` and `simt shared` share.
+
+3. **The file that is written is the one the loader table says the harness reads.** The
+   plan named paths. A path the table does not record would be written and never loaded, so
+   a surface with no user-level row, and a pointer surface with no loader row, gets a block
+   to paste and no path. Where the table names a flat user rules directory, the file is
+   `simt.md`. Where a harness reads one of two files and the reader already has a non-empty
+   one, that file is the one written. A cap the table states in tokens is reported, not
+   compared with a byte count, and a copy over its cap is reported rather than refused.
+
+4. **`simt shared plan` writes nothing. `simt shared install` writes only with `--yes`.**
+   The write is the user-level file, keeping whatever prose sits outside the generated
+   region, and the same declaration in every repository that already has a manifest. A
+   repository without one is skipped, with the command that adopts it. A workspace with
+   nothing to share writes neither an empty home file nor a declaration. The regions
+   change on the next `simt sync`, not during the install.
+
+5. **The region is a function of the declaration, not of the reader's home directory.** CI
+   and the reader therefore render the same delta. A teammate without the user file loses
+   the shared rules from the region; `simt doctor` says so — current, stale, absent,
+   unreadable, or no target — and does not fail the gate. The index line names the rule,
+   why it is not in the file, and `simt rules show <id>`. It does not name a home path,
+   because that path is not true on both machines.
+
+6. **One section holds every reason a rule is missing, and its heading names the fact.**
+   Class-deferred, cut to a budget, and carried once are three decisions and one fact for
+   the reader: the rule is not in this file. The heading is `## Rules not in this region`.
+   This narrows ADR-073 ruling 6 and ADR-083 ruling 7, which named that section
+   `## Deferred rules` when a class deferral was the only reason to be in it. The rest of
+   both rulings stands: one section, each line says which reason, and the remedy is the
+   same command.
+
+7. **A repository's own profile or pack is not shareable.** It is policy that repository
+   owns. Putting it in a home file would change one repository by editing a file every
+   sibling reads. Only rules this package ships are candidates, and the shareable set is
+   computed before the declaration drops them, so a second install does not shrink the
+   intersection against an already-reduced list.
+
+8. **`simt tokens` counts the user-level copy once.** `tokens --repos` adds the whole file
+   to the estate total, prose outside the region included, because that prose is also
+   always-on for the reader. A repository on its own counts the same file, so a single
+   root does not look cheaper than the workspace it belongs to.
+
+## Consequences
+
+`simt shared plan` is the default of `simt shared`, for the same reason `simt skills` lists
+before it installs: the read answers what would happen, and the write needs `--yes`.
+
+The plan's accept bar — always-on bytes for the seven-root estate at most 30 KB, and no R
+loss in bench — is **unmeasured**. The tests prove the mechanism on fixtures: identical
+rules leave the region, a divergent rule stays, the reader's own prose survives, and the
+meter counts the copy once. They do not measure the estate, and they do not run the bench.
+
+## Rejected
+
+- **`projection.shared`.** The next upgrade would delete it, and the region would silently
+  grow back.
+- **CI renders the full region while a reader renders the delta.** `check` would report
+  drift on every machine that had installed the copy, or would have to read a home
+  directory the projection is forbidden to depend on.
+- **The union of rules across repositories.** A rule one repository does not ship is that
+  repository's absence, and installing it at user level would give the rule to a reader of
+  a repository that declined it.
+- **Writing the paths the plan named when the loader table records a different file, or
+  none.** A file the harness does not read is a second copy the reader never sees.
+- **An empty shared file for a workspace with nothing to share.** It would look like a
+  decision and contain none.

package/docs/decisions/ADR-085-the-region-ends-with-the-names-it-kept-out.md

@@ -0,0 +1,72 @@
+# ADR-085 — The region ends with the names of what it kept out
+
+Status: **accepted** · 2026-10-18 · filed as R12 (plan 0003)
+
+**Affects:** `src/projection/disclosure.mjs`, `src/projection/rules.mjs`, `src/graph/spec.mjs`,
+`test/disclosure.test.mjs`, `test/scoped.test.mjs`
+
+## Context
+
+A profile that declares a scope already leaves the always-on region when every selected
+surface can load it narrowly, and the region keeps a pointer (ADR-071). A package in a
+monorepo already gets its own region (ADR-066). What a reader still cannot see is an
+installed skill: the body lives in its own file, and a surface with no skill channel never
+mentions the name, so the reader has no reason to open it.
+
+The plan asked for one index at the end of the kernel, one line per scoped rule and per
+skill, carrying the name and the trigger. The accept is that the scoped body is absent
+from what loads at session start and present in the file a matching path loads, checked
+per surface.
+
+## Rulings
+
+1. **The index is the last section of the region, and it is one section.** Its heading is
+   `## Disclosure`. A scoped profile keeps the pointer ADR-071 ruling 7 requires: the
+   patterns, and the files the profile moved to. A skill keeps its name and its
+   description, which is the trigger. A second heading for the second kind would spend
+   region bytes on a distinction the reader acts on the same way — open that thing when
+   the line says to.
+
+2. **A skill contributes nothing but that line.** The body stays in the skill file. The
+   description is read with the same frontmatter reader the skill lint uses, so a folded
+   description is the sentence the author wrote and not the marker in front of it. A
+   skill with no description says so and names `simt skills show`, because a line that
+   invents a trigger would send the reader to the wrong file.
+
+3. **The directories are the four a skill is installed into.** They are the directory
+   `skills install` chooses and the directories a loader row records, which together are
+   four and not a walk of the repository. A symlink to a skill already counted is not a
+   second skill. Two different files that share a name are both listed, with the
+   directory, because keeping one would hide a trigger.
+
+4. **The index is region text, so every selected surface sees the same lines.** A surface
+   that already shows a skill's name and description at session start sees the line
+   twice. The alternative is a region that depends on which surface is reading it, and
+   `check` would then disagree with a reader whose surface has no skill channel. The
+   body is the copy that stays out. ADR-071 ruling 1 still decides the profile itself:
+   it leaves the region only when every selected surface can narrow it.
+
+5. **The index is not a candidate for a budget cut.** Cutting it would remove the only
+   mention of the rules a cut had already removed. It is weighed, because it does cost
+   bytes, and it is kept.
+
+## Consequences
+
+On a surface that can narrow, a fixture's scoped profile is absent from the region and
+present in the file that surface loads when a matching path is in play. On a surface that
+cannot, the profile stays in the region. That is the accept, checked by rendering each
+surface rather than by driving the harness: this tool writes the file, and the harness
+is what opens it.
+
+A repository with no installed skill and no scoped profile gains no section. An empty
+heading would be a line about nothing.
+
+## Rejected
+
+- **Putting the skill body in the region.** That is the cost the index exists to avoid,
+  and it is what a surface with a skill channel already refuses to do.
+- **Omitting the line on a surface that shows skill metadata itself.** The region is one
+  document. A line present for one reader and absent for another is drift.
+- **Truncating a description to keep the line short.** The description is the trigger. A
+  shorter line that no longer says when to open the skill is a line that cannot do its
+  job.

package/docs/decisions/ADR-086-the-stable-prefix-comes-first-and-the-lock-records-both-digests.md

@@ -0,0 +1,69 @@
+# ADR-086 — The stable prefix comes first, and the lock records both digests
+
+Status: **accepted** · 2026-10-18 · filed as R13 (plan 0003)
+
+**Affects:** `src/projection/rules.mjs`, `src/projection/lock.mjs`, `src/commands/sync.mjs`,
+`src/argv.mjs`, `test/lock.test.mjs`, `test/card.test.mjs`
+
+## Context
+
+A reader caches the instruction file. A change in the first bytes throws the rest away,
+including the rules that did not change. The plan asks for the stable content first —
+core, then stack, then what this repository added — and for a lock that fails when the
+output moves and the input did not.
+
+The command card was the first bytes of the region (ADR-077 ruling 1), because the
+commands are what a reader cannot infer. They are also the bytes a repository edit is
+most likely to move: a script change would then invalidate the core that follows them.
+
+The content digest stays in the generated header. It is a digest of what this package
+ships (ADR-032), so a repository edit does not move it, and `check` uses it to tell a
+hand-edit from a version mismatch. Taking it out of the file would make those two
+failures look the same. No date and no absolute path is written into the region.
+
+## Rulings
+
+1. **Shipped rules, then this repository's own bytes.** Core first, then the other
+   profiles this package ships, by id. Then the command card, then profiles the
+   repository added, then the index of what the region does not carry. This narrows
+   ADR-077 ruling 1: the card still leads the repository's own bytes, and it no longer
+   leads the region. The rest of that record stands, including that the card is derived
+   from committed evidence only.
+
+2. **The order inside the shipped prefix is by id, not by directory order.** A directory
+   listing is not a fact about the rules. Two machines rendering one repository produce
+   the same bytes; the test renders one repository twice, which is the half a single
+   process can see. The other half is the same argument ADR-073 ruling 7 makes: the
+   inputs are the files, and nothing in the render reads the clock, the home directory
+   or the network.
+
+3. **`simt-dev.lock.json` records an input digest and an output digest.** The input is
+   the package digest, the detected signals, the manifest keys that change the region,
+   the repository's own profiles and its `package.json` scripts. The output is the
+   region body. `sync --yes` rewrites the lock when it differs. `check` without
+   `--frozen` does not require one, because every repository adopted before this record
+   would otherwise fail a gate it had not been asked to keep.
+
+4. **`check --frozen` fails in two ways, and names which.** No lock, or a lock whose
+   input digest differs, is a stale lock: rewrite it with `sync --yes`. A lock whose
+   input matches and whose output does not is unexplained: the projection changed and
+   nothing it read did. An output change that an input change explains is the stale
+   case, not the unexplained one.
+
+## Consequences
+
+Editing a repository profile leaves the bytes before that profile identical. A frozen
+check on a matching lock passes, a tampered output fails as unexplained, and a changed
+profile fails as a stale lock.
+
+## Rejected
+
+- **Removing the content digest from the header.** The digest does not move when the
+  repository edits a line, and without it a hand-edit and a version mismatch are one
+  finding.
+- **Hashing the whole manifest, or the whole `package.json`.** A comment, or a
+  dependency bump that the projection does not read, would fail the lock for a region
+  that had not changed.
+- **Failing an ordinary `check` when the lock is absent.** The lock is new. The
+  repositories this package already adopted do not have one, and a gate that turned red
+  for that absence would be red everywhere until someone ran `sync`.

package/docs/decisions/ADR-087-a-run-is-evidence-for-one-tree.md

@@ -0,0 +1,67 @@
+# ADR-087 — A run is evidence for one tree
+
+Status: **accepted** · 2026-10-18 · filed as R17 (plan 0003)
+
+**Affects:** `src/ledger/index.mjs`, `src/commands/evidence.mjs`, `src/hooks/dispatcher.mjs`,
+`test/ledger.test.mjs`
+
+## Context
+
+The rule that a test was run is otherwise a sentence in a commit message. Nothing checks
+it, so a message can say the tests passed for a tree they were never run against, and
+for a tree that has been edited since. The plan asks for a ledger, a proof block, and a
+commit-message check that warns unless the repository asks it to block.
+
+The tree has to be named without staging. `git add -A` on the real index would take the
+author's unstaged work into the commit that is about to happen, which is the opposite of
+what a hook is allowed to do.
+
+## Rulings
+
+1. **The tree is everything on disk, taken with a private index.** `git add -A` and
+   `git write-tree` run against a temporary `GIT_INDEX_FILE`, which is deleted
+   afterwards. The repository's own index is not read for this and not written. A file
+   the author left unstaged stays unstaged. The ledger file is left out of that add,
+   because the line is a record of the tree and writing it must not replace the tree
+   it names.
+
+2. **A ledger line records the run, not its output.** The command, the exit code, the
+   duration, a one-line summary, and a digest of the output. The output itself is not
+   stored. The line is appended when the dispatcher actually runs a gate. A gate that
+   does not run leaves no line. A tree that cannot be named leaves no line, and the
+   claim check then finds nothing.
+
+3. **A verification claim is a passing line for this tree.** The phrases are `tests
+   pass`, `tests passed`, `test pass`, `test passed`, and `verified`. `unverified` and
+   `not verified` are not claims. A line with a non-zero exit does not support the
+   claim. Editing any file changes the tree, so the line stops supporting it.
+
+4. **The check warns, and blocks only when the repository says so.** `gates.evidence`
+   set to `block` fails the commit. Unset, or `warn`, prints the warning and exits 0.
+   Any other value is an error, because a misspelt `block` must not become a warning.
+   `simt evidence` prints the lines for the current tree and writes nothing.
+   `simt hooks install --yes` writes a commit-msg shim only when `gates.evidence` is
+   `warn` or `block`. The shim forwards the message file. Unset installs nothing,
+   and removing the setting removes the shim, so a hook the repository did not ask
+   for does not stay behind and replace git's own.
+
+## Consequences
+
+A green run followed by an edit of any file leaves the new tree with no evidence. The
+old line is still in the ledger, and it names the tree it was true for. A commit
+message that claims the tests passed is blocked only in a repository that set
+`gates.evidence` to `block`.
+
+## Rejected
+
+- **Staging with the real index in order to name the tree.** The next commit would
+  contain files the author had not staged.
+- **Storing the command's output in the ledger.** A test log is not evidence the next
+  reader needs, and it is where a secret printed by a failing command would be kept.
+- **Treating any ledger line as proof the tests passed.** A failing run is a line. It
+  is not a pass.
+- **Blocking every repository by default.** The check is new. A repository that has
+  not asked for it gets a warning, which it can read, and its commit still happens.
+- **Adding commit-msg to the dispatcher events.** Those shims do not forward git's
+  arguments, because a pre-push remote would be read as one. The message file is
+  the argument, so the claim check is its own shim.

package/docs/decisions/ADR-088-a-marked-line-is-enforced-by-a-checker.md

@@ -0,0 +1,59 @@
+# ADR-088 — A marked line is enforced by a checker
+
+Status: **accepted** · 2026-10-18 · filed as R19 (plan 0003) · ruling 3 narrowed by ADR-090
+
+**Affects:** `src/kernel/checks.mjs`, `rules/core.md`, `src/commands/sync.mjs`,
+`test/checks.test.mjs`
+
+## Context
+
+A line an agent is trusted to follow is a line the next agent can skip. The file-length
+rule is already two numbers with two meanings, and the check that was supposed to apply
+them was never run. The plan asks for a line to name a checker, for the projection to
+keep the name, and for the checker to be what actually decides.
+
+One of the named checkers, `import-direction`, needs a module graph this tool does not
+have yet. Removing that instruction now would leave a name and no check.
+
+## Rulings
+
+1. **A list item may name one checker.** The marker is `simt-check`, on the item,
+   including the lines wrapped under it. The checkers are `max-file-lines`,
+   `forbid-regex`, `forbidden-path-edit`, `required-file`, and `import-direction`.
+   Anything else is a broken rule. A marker inside a fenced sample is not a checker.
+
+2. **A checker that can run replaces the item with its name.** The projection says
+   `Enforced:` and the checker. The prose does not. `simt check` runs the checker
+   against the rule as written, so the line that left the prompt is the line that
+   still decides. `max-file-lines` reads `limits.fileLines`: over the trigger warns,
+   over the ceiling fails. A path is exempt when `limits.fileLines.generated` names
+   it, or when the file carries the generated-region marker this tool writes, which
+   is this tool naming itself as the generator. The numbers stay 400 and 1000 where
+   a repository has not named its own.
+
+3. **`import-direction` does not replace its item.** The module graph it reads is not
+   built. The instruction stays, the marker does not reach the reader, and `simt check`
+   says the checker is not built. It does not fail the repository for that.
+
+4. **A diff checker reads the change.** `forbid-regex` and `forbidden-path-edit` look
+   at added lines and changed paths, including untracked files. A match already in the
+   last commit is not a new match. A directory that is not a git repository is not a
+   failure of these checkers: there is no tree to name.
+
+## Consequences
+
+The file-length sentence no longer occupies the region. The bytes it occupied are
+smaller by the length of that sentence. Whether agents still comply with the rule is
+unmeasured: the probes were not run.
+
+`simt check` now fails a tracked file past the ceiling in every repository that
+selects the core rules, which is every repository.
+
+## Rejected
+
+- **Dropping `import-direction` before it can run.** The name would say the line is
+  enforced. Nothing would be enforcing it.
+- **Failing `simt check` outside a git repository.** There is no tracked tree to count
+  and no diff to read. A missing repository is not a long file.
+- **Exempting a file because it looks generated.** The repository names the generator.
+  A guess would hide the ceiling from the file that most needs it.

package/docs/decisions/ADR-089-the-local-index-is-a-cache-of-git-blobs.md

@@ -0,0 +1,52 @@
+# ADR-089 — The local index is a cache of git blobs
+
+Status: **accepted** · 2026-10-18 · filed as R20 (plan 0003)
+
+**Affects:** `src/index/store.mjs`, `src/commands/repoindex.mjs`, `test/index.test.mjs`
+
+## Context
+
+Later slices ask which file defines a name, which test covers a change, and which
+decision governs a path. Those questions need a store, and the store has to be
+rebuildable: a cache that cannot be reconstructed from the repository is a second
+source of truth. The plan names `node:sqlite`, with a fallback for a Node that does
+not have it, and it names the blob hash from `git ls-files` as the unit of change.
+
+The floor this package declares is older than the Node that first shipped that module
+as something a program can rely on. A store that only works on the machine that
+happened to build it is not the store the plan describes.
+
+## Rulings
+
+1. **The store is sqlite when this process can open it and create an FTS5 table.**
+   The file is `.simt-dev/index.sqlite`. The tables are the ones the plan names:
+   files, symbols, edges, an FTS5 table, and meta. When the module is absent or FTS5
+   cannot be created, the same file rows are written to `.simt-dev/index.jsonl`.
+   Nothing is added to the dependency set.
+
+2. **A row is keyed by the git blob.** `git ls-files -s` supplies the path and the
+   blob. A path whose blob has not changed is not read again, and its row is not
+   rewritten. A path that left the index leaves the store, and so does anything
+   recorded against that path. Two indexes of the same blobs produce the same file
+   rows. The language comes from the extension, and the package comes from the
+   nearest manifest walking up from the file.
+
+3. **`simt index` rebuilds the cache.** It does not preview, because the file it
+   writes is not repository content. It says when the path is not gitignored. A
+   directory that is not a git repository cannot be indexed.
+
+## Consequences
+
+Reindexing one changed file reads that blob and leaves the others. The symbols and
+edges tables exist and are cleared for a path whose blob changed. Nothing fills them
+until a later slice extracts names from the bytes.
+
+## Rejected
+
+- **Requiring sqlite.** The floor this package already ships does not promise the
+  module. A repository on that floor still gets an index.
+- **Hashing the worktree instead of the blob.** An unstaged edit is not what
+  `git ls-files` reports. The index follows the index, so two machines with the same
+  committed blobs agree.
+- **Treating the cache as a writer that previews.** A preview that does not write
+  leaves the reader with no index. The command's only effect is the cache.

package/docs/decisions/ADR-090-an-optional-adapter-is-off-until-named.md

@@ -0,0 +1,55 @@
+# ADR-090 — An optional adapter is off until a repository names it
+
+Status: **accepted** · 2026-10-18 · filed as R21 (plan 0003)
+
+**Affects:** `src/index/extract.mjs`, `src/index/store.mjs`, `src/index/persist.mjs`,
+`test/extract.test.mjs`
+
+## Context
+
+The index can say which file defines a name only if something reads the blob. A
+structural parser does that more accurately than a scan of lines, and it is also a
+dependency: grammars, a WASM runtime, a package this tool would then require. The
+floor this package ships is zero dependencies. An adapter that is always loaded is
+not optional, and an adapter this package names for one organisation is a name the
+next repository does not have.
+
+The module graph of imports now exists. ADR-088 ruling 3 kept `import-direction` in
+the prose because that graph did not. The graph still does not say which way an
+import is allowed to point.
+
+## Rulings
+
+1. **The built-in extractors are the index.** They read one line at a time and
+   record definitions, exports and imports for the languages a map needs. The same
+   blob produces the same symbol rows and the same import edges. A blob that has
+   not changed is not read again. Recall against a hand-labelled set of exported
+   names, for TypeScript, Kotlin, Python and Go, is at least 90%. A comparison
+   against a structural parser was not run.
+
+2. **An optional adapter is a separate package, and it is off until named.**
+   `index.parsers` is the package name. Absent, nothing is imported. This package
+   does not depend on a parser and does not ship a default name for one. When the
+   named package does not load, the built-in rows are the cache and the index says
+   so. When it loads, its symbols and edges replace the built-in rows for that
+   blob. It writes those rows into the cache. It does not edit a source file.
+
+3. **`import-direction` still does not replace its line.** ADR-088 ruling 3 stands,
+   except for the sentence that the module graph is not built. The edges are
+   recorded. No rule names the direction they must follow, so the instruction stays
+   and `simt check` does not fail a repository for the missing direction.
+
+## Consequences
+
+`simt index` now reports how many symbols and edges the cache holds. Whether the
+line extractor misses a name a parser would have found, on a real repository, is
+unmeasured: the bar above is the labelled fixtures, not a live parser.
+
+## Rejected
+
+- **Depending on a parser, or probing one this package names.** The dependency set
+  would no longer be empty, and a name that only one organisation publishes is not
+  a default for every repository.
+- **Treating the import edges as a direction check.** An edge says that A imports B.
+  It does not say that A was allowed to. Dropping the instruction would report the
+  line as enforced.