simt-dev 0.2.2 → 0.3.1

package/docs/decisions/ADR-076-a-change-to-what-agents-read-is-measured.md

@@ -0,0 +1,70 @@
+# ADR-076 — A change to what agents read is measured before it ships, or labelled unmeasured in its record
+
+Status: **accepted** · 2026-10-15 · filed as D1 (R01)
+**Affects:** `src/bench/mine.mjs`, `src/commands/bench.mjs`, `src/commands/index.mjs`, `src/commands/help.mjs`, `test/bench.test.mjs`
+
+## Context
+
+Every rule and profile projected by this package enters an agent's context window on every
+turn, yet nothing in the repository could say whether a paragraph improved resolution,
+increased token cost, or did neither. Controlled studies on repository context files show
+that unmeasured instructions routinely raise inference cost by 20% or more without moving
+task resolution when they repeat facts the repository already proves.
+
+Without a repository-native task suite and a rule requiring evidence, changes to projected
+context are judged by how plausible the prose sounds to a reviewer rather than by what an
+agent does with it. And a task suite whose verification tests sit inside the agent's
+worktree is trivial to game: an agent can read or weaken the test it is being graded by.
+
+## Rulings
+
+1. **A change to projected context is measured against the benchmark suite before it ships,
+   or its decision record states `unmeasured` and why.** Context changes include core
+   rules, stack profiles, process rules, kernel compilation, command cards and brief
+   assembly. When a slice cannot be run through the benchmark (for example, before the
+   runner is wired or when a rule governs an external release gate), the decision record
+   must carry the explicit label `unmeasured` rather than implying an empirical win.
+
+2. **Benchmark tasks are mined deterministically from non-merge git history.** `simt bench mine`
+   walks non-merge commits with a parent, selects commits that modify both test paths and
+   implementation paths, splits each commit into `test.patch` (test files) and `gold.patch`
+   (implementation files), and assigns the deterministic identifier `t-<shortSha>-01`.
+
+3. **Every mined task is validated twice in an isolated worktree before acceptance.** At
+   the parent commit `BASE`:
+   - `BASE` plus `test.patch` must fail (`RED`) on two consecutive runs with the same
+     failing and passing test identifiers;
+   - `BASE` plus `test.patch` plus `gold.patch` must pass (`GOLD`) on two consecutive runs
+     with zero failing tests and the same passing test identifiers;
+   - any commit whose test outcome differs between the two runs is discarded as flaky.
+
+4. **Test identifiers are extracted from runner-native machine output, never from human
+   console summaries.** The miner parses TAP (`node --test --test-reporter=tap`), Vitest
+   JSON (`--reporter=json`), JUnit XML (Gradle, Maven and `pytest --junitxml`) and Go JSON
+   event streams (`go test -json`) to record exact `f2p` (`FAIL_TO_PASS`) and `p2p`
+   (`PASS_TO_PASS`) test identifiers.
+
+5. **Hidden test patches live in a verifier vault outside every worktree.** Task metadata
+   is written to the adopting repository's benchmark task directory so the suite
+   membership is versioned and reviewable, while `test.patch` and `gold.patch` are written
+   to the user's cache vault (`~/.cache/simt-dev/vault/<repo-id>/<id>/`, or the platform
+   cache equivalent) so an agent running inside a task workspace cannot inspect the
+   verifier test diff or the oracle fix.
+
+## Consequences
+
+`simt bench mine --yes` mines a deterministic, flake-filtered task suite from a
+repository's own commits without network access or model calls. Re-running the miner over
+the same commit history produces byte-identical task JSON files and vault patches.
+
+## Rejected
+
+- **Keeping `test.patch` inside the repository's committed task directory.** An agent
+  evaluated in a checkout of the repository could read the hidden test expectations or the
+  oracle patch directly from disk.
+- **Accepting any commit that touches a test file without running `RED` and `GOLD` twice.**
+  Refactors, formatting commits and flaky tests touch test files without failing on `BASE`,
+  producing tasks where a no-op agent scores 100% or a valid fix fails at random.
+- **Scraping human-formatted test summaries with regular expressions.** Console summaries
+  vary by locale, terminal width and runner version, and do not name individual
+  `FAIL_TO_PASS` test cases needed to grade partial regressions.

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

@@ -0,0 +1,91 @@
+# 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) · 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`
+
+## Context
+
+Plan 0003 R10 asks for the highest-value, non-inferable bytes: the exact commands for *this*
+repository, at the top of the region, in a block of at most 600 B, "derived from gates and
+runner detection alone, so it needs no index". A reader who has the rules has the same rules
+every other repository has; what they cannot infer is that *their* tests run under
+`./gradlew :app:testDebugUnitTest` and not `npm test`.
+
+Two things the plan leaves open, and both are the kind an implementer gets wrong once:
+
+1. **Which modes carry the card.** R07's kernel is a smaller projection a repository asks
+   for (ADR-073), and R10 says "at the top of the kernel". Read literally, the card would
+   appear only for the repositories that opted into kernel mode — that is, only for the
+   readers who already measured that they can do without guidance. The reader who kept
+   `full` is the one who has the commands nowhere.
+
+2. **What evidence the card may read.** "Runner detection" has two possible meanings here.
+   `readCapability` answers "can this machine run it" by probing PATH and `node_modules`,
+   and that answer is machine-specific. But the projected region is required to be
+   byte-identical on two machines (plan 0003 P4 and R13): the whole reason the tool has no
+   model and no network is that a pull request can meaningfully diff a projection. A card
+   that named whichever linter happened to be installed would differ between a laptop and
+   CI for no reason a diff could explain, and `check` would flake on a clean tree.
+
+## Rulings
+
+1. **The card leads the region in both modes.** `full` and `kernel` differ in which *rules*
+   are packed (ADR-073 ruling 5); neither withholds the commands. The card is bytes the
+   reader most needs and the rules never carry, so it is above even the core, and it is not
+   a rule the kernel can defer.
+
+2. **It is derived from committed evidence only.** Three sources, in precedence order: the
+   manifest's declared `gates.commands`, the repository's own `package.json` scripts, and
+   the marker facts that name its ecosystem. It never reads PATH or `node_modules`.
+   Runnability is a property of the machine; a command is a property of the repository, and
+   only the second belongs in bytes that leave it.
+
+3. **The ecosystem table is the single source, and the gate list cannot disagree with it.**
+   The fallback for a marker that has no declared command is the same `ECOSYSTEMS` table
+   `manifest.mjs` seeds gates from. Two tables would eventually name two different test
+   commands for one repository, which is the drift this tool exists to remove. Python is the
+   one ecosystem the table does not seed, because its runner varies (uv, poetry, tox, nox); the
+   card still names the command a committed lockfile proves — `uv run -m pytest`, never
+   `uv run pytest`, because the uv profile is explicit that the console entrypoint can run a
+   different copy of the package than the one under test.
+
+4. **A template is labelled as a template, per path kind.** The focused-test entries carry
+   `{file}`, `{pkg}`, `{Test}` and `{class}` placeholders and are labelled by the kind of
+   path they apply to, so a reader never pastes a brace into a shell. Which test a given
+   `{file}` maps to is R24's refinement, not R10's.
+
+5. **The ceiling is 600 B, enforced by dropping whole lines, never silently.** Lines drop in
+   a stated order — `format`, `typecheck`, `lint`, `build`, then focused templates from the
+   last — and `test` is never among them, because a card that dropped the test command would
+   have dropped the command it exists to carry. Every drop is named in the projection notes;
+   a card that lost a command in silence is a card the reader cannot tell is incomplete.
+
+6. **It is computed in `desiredRegion`, the one place the region is computed.** `plan` and
+   `checkTarget` therefore cannot hold two opinions about the same card, which is the same
+   property that keeps a clean tree from reporting drift (the comment on `desiredRegion`).
+
+## Consequences
+
+Every adopted repository's region gains the card on the next `sync`, in both modes. That is
+the point of the slice: the bytes were absent everywhere, and the ones added are the ones a
+reader can act on. The card is derived, so it moves only when the repository's own commands
+move — a new `package.json` script, a declared command, or a marker file appearing.
+
+What is not here: which test a `{file}` should be mapped to (R24), the inferability filter
+that would drop a card line the repository already states (R09), and the cost measurement
+that would say whether the card earns its bytes (R02, R27). This ruling is what makes those
+measurable rather than what concludes them.
+
+## Rejected
+
+- **Kernel mode only.** It withholds the card from the readers who kept the larger
+  projection, which is all of them until R02 has run.
+- **Probing PATH or `node_modules`** so the card shows only commands that will run here. The
+  answer would not survive a second machine, and the region is required to.
+- **Writing the commands as rule text.** The commands are data about one repository; a rule
+  is the same in every repository, and a rule that stated one repository's test command would
+  be wrong in every other.
+- **Letting the card grow past 600 B, or trimming it silently.** An unbounded card is a
+  second copy of the rules, and a silently short one is a reader who trusts a card that is
+  missing a command.

package/docs/decisions/ADR-078-a-line-the-repository-already-proves-does-not-ship.md

@@ -0,0 +1,117 @@
+# ADR-078 — A line the repository already proves does not ship, and the author says so
+
+Status: **accepted** · 2026-10-16 · filed as R09 (plan 0003)
+**Affects:** `src/kernel/inferability.mjs`, `src/projection/rules.mjs`, `src/kernel/card.mjs`
+(the verb vocabulary), `src/argv.mjs`, `src/commands/help.mjs`, `test/inferability.test.mjs`,
+`test/shipped.test.mjs` (the estate-name guard's allowlist of the tool's own words)
+
+## Context
+
+Plan 0003 R09 asks for an inferability filter: a rule line may declare
+`simt-inferable-when: <fact expression>`, and when the repository already proves the
+expression the line is dropped — "use `./gradlew`" when the wrapper is the only runner and
+the card names it, "use pnpm" when only `pnpm-lock.yaml` exists. The basis is that content
+the repository already states does not help its reader.
+
+ADR-077 built the card that names this repository's commands and left R09 open as the filter
+"that would drop a card line the repository already states". What the plan leaves open is
+the part that decides whether the mechanism is usable or a trap:
+
+1. **Who may drop a line.** An inferability filter that guesses is a filter that deletes
+   rules a reader needed. "The repository has a `.editorconfig`, so the indentation rule is
+   inferable" is exactly the reasoning that is right most of the time and silent when it is
+   wrong.
+
+2. **What evidence may be read.** The same choice ADR-077 ruling 2 had to make, and the same
+   answer applies: the projected region is required to be byte-identical on two machines
+   (plan 0003 P4, R13), so evidence read off the machine cannot decide what leaves.
+
+3. **What a removal costs the author.** A line that leaves a projection with no trace is the
+   mistake ADR-073 rejected for deferred rules. But a `## Dropped` section would spend region
+   bytes on lines the reader is being told not to read, which is the opposite of the slice's
+   purpose.
+
+## Rulings
+
+1. **A line leaves only when its author says it may.** The mechanism is opt-in per block, by
+   a marker the rule author writes — `<!-- simt-inferable-when: <expression> -->`. Nothing is
+   dropped by inference alone. The tool checks a claim; it does not make one.
+
+2. **The unit is the blank-line-delimited block, and the marker never reaches the region.**
+   A wrapped bullet is marked once and leaves whole, rather than leaving half a sentence
+   behind. The comment is stripped from the region whether or not the line is dropped:
+   `simt-` vocabulary is for the rule's author, not for its reader.
+
+3. **The expression is a conjunction of positive terms over a closed vocabulary.** A term is
+   a fact or stack tag in `KNOWN_TAGS`, a `card:<verb>` for one of the card's five verbs, or
+   a `gate:<name>` the repository declares. There is no negation: every reason a line is
+   redundant is a positive proof the repository offers, and a grammar for a case nobody has
+   is a grammar nobody can be taught. A term outside the vocabulary is a defect, reported
+   through the same field as a broken frontmatter key, so `check` and `rules list` need no
+   second path to a broken rule.
+
+4. **The proofs are committed bytes only.** The repository's own facts and stack, the gates
+   its manifest declares, and the verbs its card names. Never PATH and never `node_modules`,
+   for the reason ADR-077 ruling 2 already settled: a proof read off the machine would make
+   the region differ between a laptop and CI for no reason a diff could explain.
+
+5. **The filter is about the repository's evidence, not about the mode.** It runs in both
+   `full` and `kernel`, for the same reason the card does (ADR-077 ruling 1): inferability is
+   a property of what the repository commits, and inferability of the mode would withhold the
+   saving from every reader who kept the larger projection.
+
+6. **Never silent, and never a heading.** By default a removal is reported as one count in
+   the projection notes, with the command that names each one: `--explain` prints every
+   removal and the evidence behind it. A count is enough to act on; the per-line detail is
+   what an author needs, and a reader is not an author.
+
+7. **The vocabulary has one definition.** `card.mjs` exports the five verbs the card can
+   name, and the filter validates `card:<verb>` against that same list. A copy of the list in
+   the filter would let the card name a verb the filter called unknown.
+
+## Consequences
+
+The region of a repository whose rules carry no marker does not move a byte: the filter
+returns the body by identity when there is nothing marked, so this ruling cannot drift a
+repository that did not ask for it. Where a marker is written — in a repository's own
+`.simt-dev/profiles`, or in a pack — the marked line leaves the region on the next `sync`,
+and `sync --explain` names it and the evidence.
+
+**What has not landed: no shipped rule carries a marker.** `rules/stacks/go.md` states
+"`go build ./...`, `go test ./...` are the entrypoints; `go vet ./...` runs with them" and
+`rules/stacks/uv.md` states "`uv run -m pytest`; **never** `uv run pytest`" — both duplicate a
+card line, and neither is *wholly* inferable, because each also carries a reason the card does
+not state. Dropping them would lose the reason. Marking shipped rule text is therefore a
+content pass with its own blast radius (a change to shipped rule text changes every repository
+at once), not a step of this slice; the mechanism ships first so that pass can be measured.
+
+A marker stays visible in `simt rules show <id>`, which prints the rule's own text. That is
+deliberate: it is the author's annotation, and it is the reason a line they can see in the
+file is absent from the region. It is not region text, and it never reaches one.
+
+`--explain` is a `sync` flag and not a `check` flag, because `sync` is the command that prints
+projection notes and the preview a reader reads before writing. The JSON payload of `sync`
+does not carry notes, so this adds no contract.
+
+One visible oddity, stated because the reader will meet it: `simt rules why ADR-078` prints
+`simt-inferable-when` as a repository this record surveyed, because the decisions reader
+treats every `simt-` word outside its allowlist as one. That is a defect in the reader rather
+than in this ruling — ADR-073 carries the identical one for `simt-priority` — and it is not
+fixed here.
+
+## Rejected
+
+- **Dropping a line the tool judges inferable without a marker.** It is the failure the slice
+  exists to avoid: a rule deleted by a heuristic with no way for the author to see the
+  heuristic was wrong.
+- **A marker on every physical line.** A wrapped bullet is one sentence across two lines;
+  marking lines would let a removal leave half of one behind.
+- **Negation, parentheses or disjunction in the expression.** No shipped reason for a removal
+  is negative, and a grammar with a case nobody uses is a grammar nobody can be taught.
+- **Letting the filter run in `kernel` mode only.** It would withhold a saving from the
+  readers who kept the larger projection, which is all of them until R02 has run.
+- **A `## Dropped` section in the region.** It spends bytes on lines the reader is told not
+  to read, and it moves the rule set for a reason that is not about the reader.
+- **Marking shipped rules now.** No shipped line is wholly inferable, so it would delete
+  rationales to save bytes that the card already saves, and it would change every
+  repository's region in a slice about a mechanism.

package/docs/decisions/ADR-079-the-rules-are-enforced-at-the-tool-call-from-one-policy-table.md

@@ -0,0 +1,162 @@
+# ADR-079 — The rules are enforced at the tool call, from one policy table every harness renders
+
+Status: **accepted** · 2026-10-16 · filed as R15 (plan 0003)
+
+Affects: `src/agenthooks/policy.mjs`, `src/agenthooks/decide.mjs`, `src/agenthooks/render.mjs`,
+`src/commands/agenthook.mjs`, `src/commands/index.mjs`, `src/commands/help.mjs`,
+`bin/simt-dev.mjs`, `test/agenthooks.test.mjs`
+
+## Context
+
+The rules this tool projects reach an agent as text, and text is advice. Three of them are
+broken by habit rather than by disagreement — a `git push`, a `--no-verify`, an edit inside a
+region that is regenerated — and the reader breaking one is an agent that never sees the
+commit that would have caught it. R15 turns those three into a decision at the tool call.
+
+Four harnesses document a pre-tool hook that receives JSON on stdin and answers with a
+decision (each page read 2026-10-16):
+
+| Reader | File | What it does with a decision |
+| --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `hookSpecificOutput.permissionDecision: "deny"`, exit 2 also blocks |
+| Cursor | `.cursor/hooks.json` | `{"permission": "deny"}`; exit 2 blocks; a permission hook blocks on invalid JSON even when `failClosed` is false |
+| Codex | `.codex/hooks.json` | the same `hookSpecificOutput` shape as Claude Code, or the older `{"decision": "block"}` |
+| Antigravity | `.agents/hooks.json` | `{"decision": "deny", "reason"}`; the page documents no exit code |
+
+They agree on the mechanism and on nothing else. The path differs; Antigravity's file is keyed
+by a hook *name* rather than by event; the event is `PreToolUse` or `preToolUse`; the tool name
+for a shell call is `Bash`, `Shell`, `Bash` or `run_command`; the command sits in
+`tool_input.command` for three of them and in `toolCall.args.CommandLine` for the fourth; the
+write tool is `Edit`/`Write`, `apply_patch` (whose paths are inside the patch text),
+`Write`/`Edit`, and `write_to_file`/`replace_file_content`; and the decision document is four
+different shapes.
+
+The plan was written on 2026-10-06 and named `.gemini/settings.json`. The reader table R14
+shipped already carries the correction — the Antigravity page documents
+`<workspace>/.agents/hooks.json` — so this record follows the table and not the plan. The table
+is also the source of the four config paths here: a second list of the same paths is the copy
+ADR-035 exists to prevent.
+
+Measured on this machine (node v26, twenty runs each, every figure from a node parent that
+pays the same fork the harness pays): `node -e 0` costs **85.4 ms** at p50 and **91.9 ms** at
+p95, so the runtime's own start is 92% of the plan's budget before a line of this tool runs.
+Loading the reader table adds 2.8 ms at p50 and the region detector 4.9 ms; the whole hook
+path is **97.4 ms p50 / 101.6 ms p95**, down from 127.6 / 139.0 before `bin/` dispatched
+`agent-hook` without loading the registry.
+
+So the plan's criterion of a p95 under 100 ms is **not met end to end**, and a sample of
+twenty straddling the line is a claim about this machine rather than about the tool. What
+this slice owns is the part above the runtime, and that part is stated exactly: the decision
+is **0.0023 ms** at p95, and the entry point loads no manifest, no fingerprint, no workspace
+and no command registry — the two modules it takes from `src/projection/` (`markers.mjs` to
+ask whether a file already holds a region, `loaders.mjs` for the reader table's paths) are
+leaves that read nothing at import.
+
+## Rulings
+
+**1. One policy table, and one renderer per harness.** `policy.mjs` holds the rows and matches
+them against *facts* — a shell command string, and the files a write touches — so a policy never
+knows which harness asked. Each renderer owns one harness's payload-to-facts mapping, its
+configuration shape and its decision document. The table is data; the dialects are code.
+
+**2. Three policies ship: `push` (ADR-001), `rewrite` (ADR-017) and `generated` (ADR-036).**
+Each names the record it enforces and the override that lifts it, in the message the reader
+sees. `push` quotes the projected rule that cites ADR-001; `rewrite` cites the record whose
+own Context is the `--no-verify` spiral a broken gate teaches; `generated` cites the record
+that made the region note ("Do not edit by hand") ship into every consumer repository, and its
+message names the command that regenerates.
+
+**3. Every matching policy is reported, not the first.** `git push --force` matches two, and
+the denial carries both messages and both records. A first-match rule would let
+`SIMT_ALLOW=push` carry a force-push through on an override that never mentioned rewriting
+history, which is the one thing an override must not do.
+
+**4. `SIMT_ALLOW` lifts exactly the policies it names, and says so.** A lifted policy is
+reported as lifted, so a session that granted something can be read back out of its own output.
+A name that is not a policy is reported as unknown and changes no decision: a typo in an
+override must not silently disable a policy, and it must not block either.
+
+**5. Exit 2 means "block", and only a denial uses it.** A usage error — a missing `--harness`,
+an unknown event — exits 1. Every harness reads 2 as a refusal, so a configuration mistake that
+exited 2 would block every tool call in the session, which is a worse failure than the one the
+hook is there to prevent.
+
+**6. No facts is not a violation.** An unrecognised payload, an empty stdin or unparseable JSON
+produces no decision: exit 0, nothing on stdout. A hook that blocked on a payload it did not
+understand would turn every tool call into a wall, and the harness's own permission model still
+applies. This is the deliberate direction of the failure, and it is why the facts a policy
+needs are read from named fields rather than guessed.
+
+**7. A missing hook is a state; an unreadable config is a defect.** `agent-hooks status` exits 0
+when a harness has no entry and 1 when its config cannot be read, or parses to something that is
+not an object. A harness's settings file is the harness's file, kept for reasons that have
+nothing to do with this tool, so not being in it is a choice; a file this tool cannot parse is
+one it must not write into, in either surface.
+
+**8. `agent-hook` has no envelope of its own.** Its stdout is the dialect of the harness that
+called it — no `ok`, no `schemaVersion`. It is the one command whose contract is four
+documents instead of one, and the reason a JSON contract test does not enumerate it.
+
+**9. The entry point loads neither the registry nor anything that reads the repository.** `bin/simt-dev.mjs`
+dispatches the exact spelling the renderers write, and only that: `--help` still imports the
+registry, so help remains the single list of commands. Nothing above the decision resolves a
+manifest, fingerprints a tree or walks a workspace, because all three would put the cost of
+answering "what is this repository" on every tool call. The two modules the path does take
+from `src/projection/` are leaves that read nothing at import, and the test asserts the
+modules that would read the repository are absent from the import list rather than asserting
+a duration.
+
+**10. Install merges, and identifies its own entry by the command it wrote.** Every other key
+and every foreign handler survives; the entry is found by the command string, because JSON has
+no comment to carry a marker. A config this tool cannot parse is left alone and reported, and
+nothing else is written for that run.
+
+**11. The readers this tool does not write are named.** `agent-hooks status` and `install`
+report Copilot and the DeepSeek harness as "no hooks file is documented" and OpenCode as
+"not ours" (its hooks are plugins), with the table's own note. A command that writes four files
+and stays silent about the fifth reader in the repository reads as "that one is covered too".
+
+## Consequences
+
+**What has not landed.** Three policies the plan lists are not here: formatting and linting a
+file after an edit, refusing reads of secrets (`.env*`, `*.pem`, `*.keystore`), and the Stop
+policy that blocks once when code changed with no ledger entry for the tree — the last waits on
+R17, the evidence ledger. Plan section 16 step 5 scopes this slice to exactly the three that
+shipped. A policy that cannot name its evidence cannot name its remedy, which is why the
+ledger one waits.
+
+**The acceptance criterion's headless run has not been run, and cannot be from here.** R15's
+accept says a headless Claude Code session on probe R05 shows the block. The probes and their
+graders exist and the decision was verified per harness against fixtures; the run itself needs
+a harness, and none is installed on this machine (`claude`, `codex`, `cursor-agent`, `gemini`
+and `aider` are all absent from `PATH`, which is the check that says so rather than a memory of
+one). So this record does not claim it, and the plan's note for the row names it as the one
+piece of R15's accept that is outstanding.
+
+**One field was inferred rather than read.** Cursor's page was read to line 1087 of 1490, which
+does not include its write tool's input key, so its adapter reads `file_path ?? path`. If Cursor
+names it otherwise, a generated-region edit through that harness is not caught — the failure is
+silent, which is why it is written down here rather than left in a comment.
+
+**Codex's trust step is printed, not performed.** Codex records trust against the hook's current
+hash, so a hook nobody has trusted stays inert: `install` names the `/hooks` review and
+`status` repeats it. Nothing this tool can do from a shell substitutes for it.
+
+**The hook name Antigravity keys on is `simt-dev-policies`.** Antigravity's file is a map of
+named hooks, so the entry needs a name; the project name is the one string already exempt from
+the estate-name guard.
+
+## Rejected
+
+- **One shared config written for every harness.** They disagree on the path, the top-level
+  shape, the event name, the matcher, the tool name, the command field, the write tool and the
+  decision document. A shared file would be a fifth dialect none of them reads.
+- **Blocking on a payload the hook did not understand.** Fail-closed is the dispatcher's rule for
+  a gate it was asked to run; it is the wrong rule for a hook that runs on every tool call.
+- **Exit 2 for a usage error.** It means "block" to every harness.
+- **A `stop` policy that blocks without a ledger.** The evidence it would need is R17's.
+- **An `ok`/`schemaVersion` envelope on `agent-hook`.** The harness parses its own dialect.
+- **Reading the manifest for the policy decision.** The rules are the tool's, not the
+  repository's gates; a hook that required adoption would not run in a repository that has not
+  been adopted, which is where the rules matter most.
+- **Guessing a payload shape it cannot recognise.** See ruling 6.

package/docs/decisions/ADR-080-the-tools-own-names-are-not-repositories-and-neither-reader-decides-by-shape.md

@@ -0,0 +1,99 @@
+# ADR-080 — The tool's own names are not repositories, and neither reader decides by shape
+
+Status: **accepted** · 2026-10-16 · settles what `rules why` calls a repository
+
+## Context
+
+`ESTATE_NAME` matched `simt-<anything>` that was not `simt-dev`, on the reasoning that
+every other name sharing the prefix is a repository in the estate these records were
+written in. The reasoning is sound about the estate and false about this tool, which
+prints its own prefixed names in its own records: `simt-priority`, `simt-applies`,
+`simt-inferable-when`, `simt-hooks`.
+
+Measured over the corpus before anything changed, 21 of the 33 records that named
+anything named a name of ours, across 9 records; 7 of those named nothing else:
+
+```
+ADR-018  simt-hooks              ADR-047  simt-applies
+ADR-022  simt-alwaysApply, simt-applies, simt-fallback, simt-gates, simt-id,
+         simt-key, simt-opt-in, simt-owned, simt-substitutions, simt-target, simt-title
+ADR-026  simt-package-ecosystem  ADR-056  simt-hooks
+ADR-040  simt-hooks              ADR-062  simt-applies
+ADR-073  simt-priority           ADR-078  simt-inferable-when, simt-priority
+```
+
+Two harms, and the second is the one that matters. `writtenAgainst` listed them under a
+heading that says the record was written against those repositories, which is a false
+claim about evidence — the one thing a decision record is for. Worse, `redactEstate`
+replaced them in the prose, so a reader opening a record through `rules why` read
+`` `a repository: hard | command | convention | style` `` where the record says
+`simt-priority: hard | command | convention | style`. The command whose whole job is to
+explain a citation printed a sentence with no subject.
+
+The answer was already in this repository and in the wrong half of it: the shipped-text
+guard derived `TOOL_OWN_WORDS` from `mdc.mjs` and `rules.mjs`, exactly to avoid calling
+`simt-priority` a repository. The reader of the same corpus did not, so the guard passed
+while the command that ships the corpus misdescribed it. ADR-079's own record is the third
+instance of the shape: `simt-inferable-when` was reported as a surveyed repository.
+
+## Rulings
+
+**1. The tool's own prefixed names live in `src/toolwords.mjs`, derived from the modules
+that own them.** `KNOWN_KEYS` from `mdc.mjs`, `PROFILE_KEYS` from `rules.mjs`, the
+inferability marker from `kernel/inferability.mjs`, and the three names this tool writes
+on disk (`simt-dev`, `simt-dev-check`, `simt-hooks`). Derived, not listed (ADR-022): a
+second copy of a vocabulary is a copy that drifts and then forgives.
+
+**2. Both readers read that one list.** The decision reader and the shipped-text guard
+answer the same question — is this a repository or a name of ours? — and answering it
+twice is how the two answers came apart. `test/shipped.test.mjs` now imports
+`TOOL_WORDS` instead of deriving its own.
+
+**3. A record whose subject is the prefix names no repository.** `PREFIX_ARGUING` maps
+two files (ADR-022, ADR-026) to the reason each spells the prefix, and both readers use
+it. A vocabulary cannot settle these: a hypothetical key in an argument and a repository
+name are the same shape. The guard's staleness test is unchanged — an exemption that
+stops being needed still fails.
+
+**4. Redaction keeps the tool's names and replaces the estate's.**
+`redactEstate('simt-priority')` is `simt-priority`; `redactEstate` of an estate-shaped
+name is `a repository`. The rule is about what the reader cannot act on, and a key of the
+tool they are running is not that.
+
+**5. Detection stays shape-based and strict.** `test/leaks.mjs` keeps `ESTATE_NAME` and
+does not consult the vocabulary. Detection may be stricter than rendering without harm: a
+word of ours that a surface never should have shipped still fails, and ADR-080 adds no
+false negative. This asymmetry is deliberate and is the reason the list did not become a
+filter inside the pattern.
+
+**6. `writtenAgainst` still names the estate.** 26 of 80 records list `repo-NN` labels and
+keep listing them, every label one of those; the field's purpose is unchanged and the
+reader still learns which parts of a record are not about them.
+
+## Consequences
+
+- 21 misdescribed reads are gone and no record names a name of ours; `simt rules why ADR-073 --json` reports
+  `writtenAgainst: []` and the record is served with `simt-priority` intact.
+- `src/toolwords.mjs` imports `mdc.mjs`, `rules.mjs` and `kernel/inferability.mjs`, so the
+  decision reader loads the projection stack. `rules why` is interactive and pays ~5 ms;
+  no import in that chain has import-time side effects, which is what makes it safe to add
+  to a module the MCP server also loads.
+- The guard gained an import and lost a derivation. Its own comment about where the
+  vocabulary comes from is now in `src/`, next to what it describes.
+- An estate repository whose name does not begin `simt-` is still undetectable, as
+  `ESTATE_NAME` says, and this record does not change that.
+
+## Rejected
+
+- **Keeping the shape and documenting the exception.** The defect was not the pattern's
+  comment; it was that the pattern was the only definition.
+- **Exempting the words instead of the records.** ADR-022's `simt-gates` and a repository
+  sharing that shape are indistinguishable, so a word list would either over-exempt a
+  repository or under-exempt the argument.
+- **A second list inside `src/decisions/index.mjs`.** The guard already had one, and the
+  two drifting apart is the defect this record is about.
+- **Filtering inside `ESTATE_NAME` itself with a lookahead built from the vocabulary.**
+  Detection and rendering want different answers on purpose (ruling 5), and a shared
+  pattern would have silently coupled them.
+- **Renaming `writtenAgainst` to something vaguer.** The field is right; the shape it
+  matched was wrong.

package/docs/decisions/ADR-081-a-tracker-is-read-through-the-repositorys-template.md

@@ -0,0 +1,36 @@
+# ADR-081 — A tracker is read through the repository's template
+
+Status: **accepted** · 2026-10-16 · rulings 1 and 2 superseded by ADR-082
+
+## Context
+
+`plan next` has to open the directory a repository actually keeps its plans in, and it has to
+recognise the columns that repository actually writes. Both were fixed: `docs/plans`,
+`docs/reviews`, a column named State, and the word `review` in a dependency. That is this
+package's own layout. A reader whose plans live somewhere else, or whose tracker says Done
+in a column named Progress, would be told they had no plan.
+
+The selection cannot live in the manifest. `init` rewrites that file from the fields it owns,
+and a repository that has not adopted the tool has no manifest. A plan template has to work
+in both, and it has to survive a re-init.
+
+## Rulings
+
+1. **The format is a template, and the one delivered with the tool is named simt-dev.** It
+   reads `docs/plans` and `docs/reviews`, binds columns by the headers it lists, and treats
+   `done` as complete. A repository that writes nothing gets that template.
+2. **A repository replaces it with `simt-plan.json` at its root.** The file overlays the
+   delivered template: a section it names replaces that section, and a section it omits stays.
+   Directories, column headers, state words, which of those words unblocks a dependency, and
+   the words a dependency uses to name another document are all in that file.
+3. **A template that cannot be read is an error.** Falling back to the delivered template
+   would index the wrong directories and could mark the wrong row done. A directory path has
+   to stay inside the repository.
+4. **`plan done` still previews unless `--yes`.** The template decides which word is written
+   for the completed state. It does not decide that a row may change unseen.
+
+## Consequences
+
+- `simt plan status` names the template and the directories it read.
+- Changing the delivered template changes what every repository without `simt-plan.json` is
+  indexed as. The file is the format; the parser does not keep a second copy of the headers.

package/docs/decisions/ADR-082-the-tracker-override-is-a-manifest-key.md

@@ -0,0 +1,35 @@
+# ADR-082 — The tracker override is a manifest key, and init keeps what it did not write
+
+Status: **accepted** · 2026-10-16 · supersedes ADR-081 rulings 1 and 2
+
+## Context
+
+ADR-081 put the tracker format in a file named for this package, and put a repository's
+override in a second file at the root. The name collided with the package and with the
+manifest's old filename. The second file existed because `init` rebuilt the manifest from
+the keys it knew and dropped the rest, so a `plans` key would not have survived a re-init.
+
+A repository that has adopted already has one config file. A second one, present only when
+the tracker differs from the delivered format, is a file most readers will not know to open.
+
+## Rulings
+
+1. **The delivered template is named `tracker`.** It is `templates/plan/tracker.json`. It
+   reads `docs/plans` and `docs/reviews`. A repository that sets nothing gets that template.
+2. **A repository overrides it with the `plans` key of its manifest.** The key overlays the
+   delivered template. A section it names replaces that section, and a section it omits
+   stays. The manifest's own comment says so, because that comment is the text a reader of
+   the file sees.
+3. **`init` keeps every key it does not write.** Owned keys still refresh, in the order the
+   writer emits them. A key absent from that object is copied after them, in the order the
+   file had those keys. That is what makes ruling 2 survivable: a re-init no longer deletes
+   `plans`, or any other key a repository added.
+
+## Consequences
+
+- `simt plan` reads `plans` from `simt.json`, and from `simt-dev.json` while that name is
+  still the manifest on disk.
+- A manifest written by `init` carries the explanation of `plans` in its comment. The
+  comment is generated, so the next `init` or `sync` refreshes it.
+- ADR-081 rulings 3 and 4 stand: a template that cannot be read is an error, and `plan done`
+  still previews unless `--yes`.