simt-dev 0.3.0 → 0.4.0

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.

package/docs/decisions/ADR-091-the-map-ranks-files-a-task-mentions.md

@@ -0,0 +1,60 @@
+# ADR-091 — The map ranks the files a task mentions, and the files next to them
+
+Status: **accepted** · 2026-10-18 · filed as R22 (plan 0003)
+
+**Affects:** `src/index/map.mjs`, `src/commands/map.mjs`, `src/commands/bench.mjs`,
+`test/map.test.mjs`
+
+## Context
+
+A task names a behaviour. The files that behaviour lives in are a small part of
+the tree, and an agent that reads the tree in path order spends its budget on
+files the task never touches. The index now records imports. What it did not
+do is say which of those files to read first.
+
+The mined tasks store a gold patch outside the worktree. The published task
+record counts the files and the lines. It does not list the paths. Recall has
+to be read from the patch, and a machine without that patch cannot invent the
+denominator.
+
+## Rulings
+
+1. **The map is PageRank over import and call edges, personalised to the task.**
+   Twenty iterations, damping 0.85. An edge counts in both directions, once.
+   A file the task mentions sorts ahead of a file it does not: on this graph
+   the file every module imports otherwise occupies the top 10. A term that
+   labels too many paths is ignored. A token that contains a digit and names
+   one path counts more the more often the task says it, so a citation does
+   not rank with the subject. A file that already matched, in a directory of
+   at most eight files, is lifted toward its neighbour. Files the task does
+   not mention, and that are not one edge away from a file it does, are left
+   out. With no task text the whole graph is ranked. Equal ranks break by
+   path, ascending. The same graph and the same text return the same order.
+
+2. **The rendering fits a budget, at one of three levels.** `outline` is paths.
+   `names` adds the exported symbols. `signatures` adds the line they were
+   declared on. The default budget is 2048 bytes. Zero means no ceiling. The
+   first file is kept when it alone is over the budget, so a map of a real
+   ranking is not an empty page.
+
+3. **recall@10 is the mean, over mined tasks, of the fraction of gold files
+   that land in the top 10.** The gold paths are the destination side of the
+   patch. A task whose patch is not in the vault is unmeasured, not a miss.
+   `simt bench report` prints the figure. It does not fail the cost report
+   when the figure cannot be computed.
+
+## Consequences
+
+`simt map` reads the index and rebuilds it when the cache is empty. The
+comparison against the mined patches is a property of this checkout's index
+and of the vault on this machine. A checkout with no index, or no vault,
+reports the figure as unmeasured. On the 20 mined tasks available here, mean
+recall@10 is 55.6% of gold files. The bar is 60%, and this ranking does not
+meet it.
+
+## Rejected
+
+- **One-directional edges.** Rank would flow only toward the imported file, and
+  the test that imports the file the task named would never surface.
+- **A zero when the gold patch is absent.** That number would punish a machine
+  for a file the benchmark hides, and it would read as a measurement.

package/docs/decisions/ADR-092-tests-are-imports-conventions-and-coverage.md

@@ -0,0 +1,60 @@
+# ADR-092 — A test is an import, a conventional neighbour, or a coverage record
+
+Status: **accepted** · 2026-10-18 · filed as R24 (plan 0003)
+
+**Affects:** `src/index/tests.mjs`, `src/commands/tests.mjs`, `test/mapping.test.mjs`
+
+## Context
+
+The index records imports. A test file that imports a source file is evidence
+that the test exercises it, and so is a coverage report that names both. A
+shared commit is weaker: most commits touch a test and several sources that
+the test does not exercise.
+
+The line extractor reads one line at a time, so an import whose specifier sits
+on the next line is absent from the stored edges. The mapping has to see that
+specifier or it misses the tests this repository actually writes.
+
+## Rulings
+
+1. **The default answer uses only the precise edges.** Kind `test`, weight 1.
+   A test file imports a tracked source file, including a dynamic `import()`.
+   Or the conventional source beside the test exists: `foo_test.go` beside
+   `foo.go`, `test_foo.py` beside `foo.py`, `FooTest` beside `Foo` in the same
+   directory, `foo.test.mjs` beside `foo.mjs`, and `src/test/java` mirrored to
+   `src/main/java`. Or a coverage record names both sides. lcov pairs a source
+   only when the test name is non-empty. JaCoCo pairs a source file with the
+   one class whose stem is that file plus `Test` or `Tests`. A Go profile
+   counts a hit, and the test is `stem_test.go` in that directory, or the
+   single `*_test.go` there. A file that is not one of those is not an edge.
+
+2. **Co-change is a different kind, and it is off unless asked.** Kind
+   `cochange`. A pair counts when it appears in at least two commits. A commit
+   with more than five tests or more than fifteen sources is skipped. Each
+   test keeps its eight strongest pairs. History is the last 200 non-merge
+   commits. `simt tests --cochange` appends those files after the precise
+   ones. A git failure leaves the history empty; the import map still answers.
+
+3. **The edges are computed when asked, and not stored.** The index write
+   replaces every edge of a changed path. Storing the test map in that write
+   would drop the import edges, and reading the commit log inside a reindex
+   would miss the one-file time bar. Coverage is read from a fixed list of
+   paths. A path that is absent is not a failure.
+
+4. **Precision is the share of predicted tests that the label also names.**
+   An empty prediction does not pass. On the 30 hand-labelled files in this
+   checkout the figure is 1.0. The bar is 0.8.
+
+## Consequences
+
+`simt tests` with no path prints how many test edges and how many co-change
+edges the tree has. `simt tests <path>` lists the tests for that file. A path
+the index does not contain is a usage error. A directory that is not a git
+repository is unsupported.
+
+## Rejected
+
+- **A stem that is unique somewhere else in the tree.** The test named for a
+  directory is not the test of the one file that happens to share that stem.
+- **Writing the test edges into the index.** The next reindex of a touched
+  path would have to know about every edge kind or it would delete them.

package/docs/decisions/ADR-093-why-names-what-governs-a-file.md

@@ -0,0 +1,58 @@
+# ADR-093 — why names what governs a file
+
+Status: **accepted** · 2026-10-18 · filed as R25 (plan 0003)
+
+**Affects:** `src/index/govern.mjs`, `src/commands/why.mjs`, `test/why.test.mjs`,
+`test/why-fixture.test.mjs`, `test/why-snapshot.test.mjs`
+
+## Context
+
+A decision says which files it governs in an Affects line. The line is prose.
+It wraps. It names a command, a path from the repository root, a path from a
+source directory, or a phrase that is not a location at all. A reader who
+greps the word Affects still has to decide which of those a backtick was.
+
+Rules, skills, gates and lessons name paths in their own way. The question
+`why` answers is the same for each: does this one govern this file?
+
+## Rulings
+
+1. **The Affects line contributes the tokens in backticks, and nothing else.**
+   Continuation lines are part of the paragraph. A blank line, a heading, or
+   the next field ends it. The token is resolved in order: a command prefixed
+   with the tool name, when that command exists; a path or a glob at the
+   repository root; the same path under each directory named src. The tool
+   name alone is not a command. A token that is none of these is reported as
+   `UNRESOLVED-AFFECTS`, with the record it came from. It is not dropped and
+   it is not guessed.
+
+2. **The other governors are the path lists they already publish.** A rule
+   governs a file its scope matches. An applies entry governs a file only when
+   the entry is itself a path. A skill governs a file its paths match. A
+   staged gate governs a file of an extension it formats, and a manifest
+   command governs a file it names. A lesson governs a file its trigger names.
+   A missing lessons directory, a missing skill registry, or a missing
+   manifest is an empty list.
+
+3. **The answer is computed when asked, and not stored.** The file list is
+   the paths git tracks. Writing the index to answer the question would change
+   the tree the question is about.
+
+## Consequences
+
+`simt why <path>` prints one line for each decision, rule, skill, gate and
+lesson that governs that path. `simt why` with no path prints the unresolved
+Affects tokens. A path git does not track is a usage error. A directory that
+is not a git repository is unsupported.
+
+On the tree at 4c27514, sixteen Affects lines were the whole set, and the
+only record naming the dispatcher was ADR-017. Records written after that
+commit name it as well, and `why` lists those too.
+
+## Rejected
+
+- **Attaching every always-on rule to every file.** The rule governs the
+  repository. Listing it on each file would hide the ones that actually name
+  the file.
+- **Treating an unresolved token as a path that might exist later.** The
+  report is the point. A guess would make the report empty.