simt-dev 0.6.2 → 0.7.0

package/docs/decisions/ADR-102-the-two-queued-review-rows-are-closed-by-ruling.md

@@ -0,0 +1,49 @@
+---
+simt-affects: ["docs/reviews/0002-full-review-adoption-and-public-release.md"]
+simt-supersedes: []
+---
+
+# ADR-102 — the two rows review 0002 left queued are closed by ruling
+
+Status: **accepted** · 2026-10-28
+
+## Context
+
+Review 0002's §3 tracker is the only tracker of slice state, and two rows in it
+still read Queued while everything around them shipped: S38 (workspace token
+cost) and S39 (estate policy as a pack). Both rows' evidence cells are
+palimpsests — notes from three different landings disagreeing about what is
+still open — so reading them as a work list sends the next reader to build what
+is already built. Closing plan 0001 meant the same audit, and ADR-033 is the
+precedent: rows closed by saying what shipped, what was refused by ruling, and
+where the remainder lives, not by authoring what they asked for.
+
+## Ruling
+
+1. **S38 is Complete.** The instrument shipped (`simt tokens`, ADR-064), the
+   declaration shipped (`budget.bytes` beside `limits` and `gates`, ADR-072),
+   and the gate raises it as a finding through one `budgetFinding` read from
+   one place by both `tokens` and `check` — the "still open" clause the row's
+   first note ends on. Kernel-line packing shipped with it (R07's `mode:
+   kernel`, R08's budget compilation). Blocking enforcement is refused, not
+   outstanding: a gate that fails a repository for exceeding a ceiling it set
+   itself, when nothing was cut, has no repair except lowering the declared
+   number (ADR-072). The one genuine remainder is the kernel-default
+   compliance study, and it is owned by plan 0003 R07's own note, not by this
+   row — the study gates making `kernel` the default, which no row asks to
+   decide here.
+
+2. **S39 is Complete.** The mechanism shipped (packs vendored and digest-pinned,
+   ADR-065; measured ΔR, plan 0003 R45). P4's pack-carries-the-registry line was
+   superseded by ADR-061, which made the registry workspace data, so there is
+   no registry-carrying pack to build. The remaining half — moving estate
+   policy into a pack — is the estate's own commit: no estate content may enter
+   this repository, and a row that waits on another repository's commit is
+   closed by recording whose commit it waits on.
+
+## Consequences
+
+- The §3 tracker reads Complete on both rows, with this record as the evidence,
+  so the next audit starts from rulings rather than from mid-flight notes.
+- A reader asking for a blocking budget gate or a registry-carrying pack gets
+  the refusal and its reason instead of an open row that looks like a promise.

package/docs/decisions/ADR-103-co-projected-duplicates-merge-down.md

@@ -0,0 +1,74 @@
+---
+simt-affects: ["rules/stacks/jvm.md", "rules/stacks/android.md", "rules/stacks/react-web.md", "rules/stacks/react-native.md", "rules/stacks/cloudflare-workers.md", "rules/stacks/container.md", "rules/mdc/preview-postflight.mdc"]
+simt-supersedes: []
+---
+
+# ADR-103 — duplicates stand alone, fingerprints generalize, references spell out
+
+Status: **accepted** · 2026-10-28
+
+## Context
+
+Twenty-four rule files ship: one core, nineteen stack profiles, four process
+rule files. An audit of all of them found three kinds of defect and one thing
+that looks like a defect but is not:
+
+1. **Verbatim duplicates inside one projection.** An Android repository selects
+   both `jvm` (gradle) and `android` (manifest), so it received the gradlew
+   invocation, the Spotless entrypoint, the `:core:domain` direction rule and
+   the assert-behaviour testing paragraph twice, in two sections of one region.
+2. **Estate fingerprints.** Literal module paths (`:core:domain`), a custom
+   check name (`checkOverlayModalPolicy`), an allowlisted surface (`core:ui`),
+   a string-resource prefix (`cd_`), product nouns (`block`, `reveal`),
+   an Arabic-only mirroring rule, a locale-parity claim about the estate's
+   tests, a privacy-probe list naming the estate's data categories, and a
+   preview-postflight file whose defaults name the estate's env vars, Firebase
+   identity and Google-only policy.
+3. **Two dangling references.** `react-web` named "the full strictness set
+   listed in the Workers profile", which a browser-only repository never
+   receives; `react-native` said "see that profile", pointing at a profile a
+   native-only repository never receives. Both fail the receiving-repo test:
+   a reader who has only their own repository cannot act on them.
+4. **Not a defect: duplicates across mutually exclusive profiles.**
+   `react-web` and `react-native`, `go` and `rust`, `deno` and `node` repeat
+   maxims, but no repository receives both sides. Merging them needs an
+   include mechanism profiles do not have, and a pointer to a non-projected
+   profile is defect 3 again. Each profile stands alone.
+
+## Ruling
+
+1. **Co-projected duplicates stay duplicated: the merge was attempted and
+   refused by a render test.** `android` pointed at the `jvm` section for
+   invocation, formatting and the shared suffixes — and a manifest-only
+   fixture (an `AndroidManifest.xml` with no root Gradle file) selected
+   `android` without `jvm`, leaving the pointers dangling. Gradle at the root
+   is usual, not guaranteed, and a rule that is present only usually is
+   silently absent exactly when its reader needs it. So `android` stays
+   self-contained and the standing jvm/android overlaps are recorded rather
+   than merged: merging them needs a profile-implication mechanism profiles
+   do not have, and that mechanism needs its own record. No hard-priority
+   lines move, so kernel bytes do not move either way.
+2. **Fingerprints generalize in place; no profile is removed and no id is
+   renamed.** `:core:domain` becomes the core domain module; the modal rule
+   keeps the public M3 names and loses the estate check and surface; `cd_`
+   becomes a content description; `block`/`reveal` become the generic nouns;
+   mirroring covers RTL locales, not Arabic alone; the locale-parity sentence
+   and the product data categories go; preview-postflight's env vars, Firebase
+   identity and Google-only defaults become neutral wording with the slots
+   repos already declare. `rules list`, the catalogue and selection behaviour
+   are unchanged.
+3. **The two dangling references are spelled out.** `react-web` inlines the
+   strictness flags; `react-native` names browser rules instead of pointing at
+   them.
+
+## Consequences
+
+- Regions change only where a fingerprint generalized or a dangling reference
+  was spelled out; `android` is byte-comparable to before modulo the
+  generalizations. `mdc.test.mjs`'s build-config test follows the renamed
+  default; its intent (the union survives) is unchanged.
+- A repository that opted into preview-postflight on the estate defaults sees
+  neutral wording and declares its own provider values through the slots that
+  already exist.
+- Mutually exclusive duplicates stay duplicated on purpose. A future include
+  mechanism needs its own record; this one refuses to invent it by pointer.

package/docs/decisions/ADR-104-the-pre-tool-use-policy-reads-the-command-the-way-a-shell-reads-it.md

@@ -0,0 +1,76 @@
+---
+simt-affects: ["src/agenthooks/shell.mjs", "src/agenthooks/policy.mjs", "src/agenthooks/decide.mjs"]
+simt-supersedes: []
+---
+
+# ADR-104 — the pre-tool-use policy reads the command the way a shell reads it
+
+Status: **accepted** · 2026-10-28
+
+## Context
+
+The two command policies — push (ADR-001) and rewrite (ADR-017) — matched the
+payload's command string with a regular expression. Review 0003 (Q01) verified
+against the shipped binary that an agent routes around both of them: `git -C .
+push`, `git --no-pager push`, `sh -c 'git push'`, `$(git push)`, `(git push)`,
+`git push;echo ok`, the alias `git p`, `git send-pack`, `git commit -n`,
+`--amen`, `--no-verif`, `git reset --har`, `git -C . commit --amend`,
+`git pull --rebase`, and with `SIMT_ALLOW=push`, `git push -fu` and
+`git push origin +main`. Three acts no policy named at all: `git -c
+core.hooksPath=/dev/null commit`, `git config core.hooksPath …` and
+`rm -rf .simt-hooks` — the repository's gates going away without a policy ever
+seeing them. And two false positives: `echo --no-verify` and `grep -r "git
+rebase" docs` were denied because a flag or a phrase sat in a command that was
+not git.
+
+Every bypass is the same act spelled another way, and a policy that reads text
+cannot tell them apart. The decision is made on the act.
+
+## Ruling
+
+1. **The command is normalised before a policy matches it.**
+   `src/agenthooks/shell.mjs` tokenises the command the way POSIX sh tokenises
+   it — quotes, escapes, `; && || | &`, newlines, subshells, `$()` and
+   backticks — descends into the wrappers a shell executes for you (`sh|bash|
+   zsh|dash -c`, `eval`, `env`, `command`, `exec`, `xargs`, `nice`, `time`,
+   `sudo`), and reduces every git invocation to the fact a policy can read:
+   which subcommand, with which options, in which repository. Long options are
+   resolved by git's unique-prefix rule (`--amen` is `--amend`), short clusters
+   are expanded (`-fu` is `-f -u`), and a leading `+` on a refspec is force.
+   The policies match that fact, not the text.
+2. **A command the tokenizer cannot read is judged by the row's regex, never by
+   nothing.** Unbalanced quotes and an unclosed `$()` mark the command as
+   unparseable, and the pre-normaliser regex runs on it, so a parse failure
+   weakens nothing. Facts that were never normalised — a test that hands
+   `decide` a bare command string — take the same path. The push and rewrite
+   ids and messages are unchanged, so an adopted repository reads the same
+   denial it read before.
+3. **A third command policy, `hooks-disable`, names the act the other two
+   cannot:** removing or rerouting the git hooks a repository's gates run in —
+   `git -c core.hooksPath=…`, `git config … core.hooksPath`, and `rm` of the
+   hooks directory. It carries no regex fallback because it did not exist
+   before this ruling: a command that cannot be tokenised is judged exactly as
+   it was judged before the row was written.
+4. **The author's aliases are resolved with one `git config --get-regexp
+   '^alias\.'` per command, and only when a fact's subcommand is not one git
+   ships.** A value that starts with `!` is a shell command and is read the
+   way any other command string is; an alias that resolves to nothing the
+   table can read is left as-is, which is the same position the pre-lookup
+   policy found it in. A git that is missing or cannot answer yields no
+   aliases, and the facts stand where the pre-lookup policy would have left
+   them.
+
+## Consequences
+
+- The false positives go with the text: `echo --no-verify` and `grep -r "git
+  rebase" docs` carry no git fact, so the rewrite policy does not fire on
+  them.
+- Every force spelling — `--force`, `-f` in a cluster, `+refspec` — is both a
+  push and a rewrite, so lifting `push` no longer carries a force-push
+  through, in any of the spellings the regex let past.
+- The decision stays pure and fast: normalisation is a fact-gathering step in
+  `factsFor`, and `decide` reads facts. The latency test, which measures
+  `decide` over prebuilt facts, is unchanged.
+- A command that names only builtin subcommands pays nothing for the lookup;
+  one that names an alias pays a single `git config` spawn with a one-second
+  ceiling.

package/docs/decisions/ADR-105-the-json-ceiling-shrinks-arrays-and-never-cuts-bytes.md

@@ -0,0 +1,44 @@
+---
+simt-affects: ["src/output/index.mjs"]
+simt-supersedes: []
+---
+
+# ADR-105 — the JSON ceiling shrinks arrays and never cuts bytes
+
+Status: **accepted** · 2026-10-29 · filed as review 0003 Q10
+
+## Context
+
+ADR-070 ruling 5 gave `emitJson` the byte ceiling: a document over `--max-bytes`
+was cut at the byte count with a `TRUNCATED` line after it, the same announcement
+the text renderer prints. Compact JSON has no newlines, so the cut landed
+mid-token and the command exited 0: `why --json --max-bytes 120` answered with a
+document no parser accepts and a status that called it a success.
+
+## Ruling
+
+1. **JSON is never byte-truncated.** `emitJson` shrinks the payload to fit: the
+   longest arrays empty first, and the document carries
+   `truncated: { field, omitted, limit }` (or `fields: [{ field, omitted }]`
+   when several lists shrank) naming exactly which list lost how many items.
+2. **A ceiling no trimming can fit is a `MAX_BYTES` error envelope, not a cut.**
+   `{ ok: false, error: { code: 'MAX_BYTES', message, remedy } }` with
+   `truncated: { omitted, limit }`, still one parseable document. The remedy
+   reads `rerun with --max-bytes 0 for the whole document` — the same ceiling
+   the text renderer names, in the same words.
+3. **The text ceiling is unchanged.** `emit` still cuts lines and announces the
+   omitted bytes; prose has line boundaries worth cutting at, JSON does not.
+
+## Consequences
+
+- Every `--json --max-bytes` answer parses, trimmed or enveloped. A reader can
+  trust that a document on stdout is the whole answer when no `truncated` key
+  rides with it.
+- `truncated` is additive: readers that ignore unknown fields see today's shape
+  with shorter lists, so no schema bump.
+
+## Rejected
+
+- **Cutting at a newline for JSON too.** Compact output has none and pretty
+  output's newlines are indentation, not item boundaries; either cut still
+  breaks the parse the caller was promised.

package/docs/decisions/ADR-106-the-harness-hook-runs-through-a-repo-shim.md

@@ -0,0 +1,46 @@
+---
+simt-affects: ["src/agenthooks/shim.mjs", "src/agenthooks/render.mjs", "src/commands/agenthook.mjs"]
+simt-supersedes: []
+---
+
+# ADR-106 — the harness hook runs through a repo shim, and `failClosed` only with it
+
+Status: **accepted** · 2026-10-29
+
+## Context
+
+Review 0003 (Q21) verified by code-read that every harness config named the
+bare `simt` binary. A devDependency install puts `simt` in
+`node_modules/.bin`, not on a harness's PATH, so that entry runs nothing on
+Claude — a non-2 exit is silent: no enforcement — and blocks every tool call
+on Cursor, whose entry sets `failClosed: true`. The install wrote a command
+that worked only on machines that happened to have the binary on PATH, which
+are exactly the machines that least need the hook.
+
+## Ruling
+
+1. **Every harness config names the repo shim, never the binary.**
+   `agent-hooks install` writes `.simt-hooks/agent-hook` beside the git shims,
+   rendered with the same `renderLocator` block from `src/locate.mjs`, and
+   every entry's command is `<shim> <event> --harness <id>`. The shim takes its
+   arguments through (`agent-hook "$@"`), so one file serves every event and
+   every harness, and `--harness` stays explicit rather than detected.
+2. **`failClosed` is set only because the command is the shim.** Cursor keeps
+   `failClosed: true` on entries that point at the shim. It is never set on a
+   bare-PATH binary: that combination blocks every tool call on the machines
+   where the binary is not installed, which is exactly the machines the shim
+   exists for.
+3. **A shim that cannot resolve refuses.** When no binary is reachable the shim
+   exits 1 with a remedy, the way the git shims do. On Claude that is still a
+   non-2 exit — silent, no enforcement — and that limitation is accepted and
+   stated here rather than hidden: the shim fixes the machines where `simt`
+   is installed but not on PATH, not the machines where it is absent.
+
+## Consequences
+
+- `ours()` recognises both spellings, so an install over a pre-shim config
+  migrates the entry in place instead of stacking a second one.
+- The shim is journaled with the configs, so `undo` removes or restores it
+  with the run that wrote it.
+- A hand-written bare-`simt` entry is the author's, not this tool's: `status`
+  does not claim it, and `install` replaces it.

package/docs/decisions/ADR-107-an-install-can-name-one-harness-and-the-skipped-ones-are-named.md

@@ -0,0 +1,51 @@
+---
+simt-affects: ["src/commands/agenthook.mjs", "src/commands/help.mjs", "test/agenthooks.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-107 — an install can be narrowed to one harness, and the skipped ones are named
+
+Status: **accepted** · 2026-10-30
+
+## Context
+
+`agent-hooks install` wrote every harness that documents a hooks file. A
+repository whose agents run in one of them received entries in the others'
+files as well — files no agent there reads, which a later `status` then
+reports PRESENT while nothing in that harness enforces anything. For a
+one-harness repository the install wrote more files than it needed to, and
+there was no way to ask for fewer.
+
+ADR-079 ruling 11 settled that the readers this tool does not write are
+*named* in the report — a command that writes four files and stays silent
+about the fifth reads as covering it. A narrowed install creates a third
+category that ruling did not anticipate: readers this tool *can* write and
+did not.
+
+## Ruling
+
+1. **`agent-hooks install --harness <id>` writes that one reader.** The id is
+   validated against the adapter table before anything is planned, and an
+   unknown id is a usage error that names the valid ids — the same validation
+   `agent-hook` applies, with the same remedy. The shim is written as before:
+   every config points at it, and a one-harness install would leave a config
+   pointing at a shim that is not there.
+2. **The skipped adapters are named in both surfaces.** The text report
+   prints a `SKIPPED` line per skipped reader with a note that says how to
+   write them all, and the JSON document carries them in `notWritten` with
+   `state: "skipped"`. A narrowed install that stays silent about the readers
+   it left alone is the failure ADR-079 ruling 11 ruled out for the full one.
+3. **`status` is unchanged.** It reports what each harness *will* run, and a
+   file that was never written is `ABSENT` there — the true answer. The
+   narrowing is a choice the install made, and the install's report is where
+   that choice is recorded.
+
+## Consequences
+
+- A repository that installs for one harness and later adds a second runs
+  install again — with the new id, or without any — and the merge creates the
+  entry in the new file while the files it already wrote come back
+  `UNCHANGED`. Nothing about a narrowed install has to be undone.
+- The prompt opt-in hint prints only when the selected harness can receive a
+  packet; a narrowed install to a harness with no prompt event does not ask
+  for an opt-in it cannot use.

package/docs/decisions/ADR-108-an-adoption-builds-the-index-and-a-command-refreshes-it-on-read.md

@@ -0,0 +1,59 @@
+---
+simt-affects: ["src/commands/init.mjs", "src/commands/map.mjs", "test/init.test.mjs", "test/map.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-108 — an adoption builds the index, and a command that reads it refreshes it on read
+
+Status: **accepted** · 2026-10-30
+
+## Context
+
+The index is a cache of git blobs (ADR-089): gitignored, rebuildable from
+`git ls-files -s`, and the data source for `simt map`, `simt brief` and
+`simt slice`. Two states of that cache were wrong for an adopted repository.
+
+First, `simt init` adopted a repository and left the index unbuilt. The
+first `simt map` in a fresh adoption paid for a walk of the whole tree, and
+the prompt-submit hook delivered a cold index — "the index is empty" — until
+somebody happened to run `simt index`. An adoption that promises the tool
+works in that repository should leave it able to answer.
+
+Second, once built, the cache went stale silently. `loadGraph` rebuilt only
+when the index was *empty*, so a file added after the build was invisible to
+every command that reads the index, with no way to tell from their output
+that they were answering from an old tree.
+
+## Ruling
+
+1. **`init` builds the index in the apply phase**, after the manifest is
+   written — `reindex` reads it for the declared parsers, so the manifest has
+   to exist first. The plan names the file it will build, and the JSON
+   document carries the result. A failure is a *note*, not a failed adoption:
+   the index is a cache, and an adopted repository whose index build failed
+   is better than one that refused to be adopted for it. The next read
+   rebuilds what the apply could not.
+2. **A command that reads the index refreshes it on read.** `loadGraph` with
+   `build` (the default) reindexes from the git index before it reads. The
+   refresh is incremental — a blob that has not changed is not re-read — so
+   the cost of a current repository is one `git ls-files -s`, not a walk of
+   the tree. The callers that build are commands a person typed: `map`,
+   `brief`, `slice`.
+3. **The `build: false` callers are unchanged.** The prompt-submit hook (R29)
+   and the MCP surface report a cold index rather than build one: a delivered
+   packet that walked the whole repository would make a person's first prompt
+   in a fresh clone wait, and a prompt that takes a minute to appear is how a
+   hook gets uninstalled.
+
+## Consequences
+
+- Amends ADR-091's consequence that "`simt map` reads the index and rebuilds
+  it when the cache is empty": the refresh now happens on every read, not
+  only on an empty one.
+- In an adopted repository the prompt hook can deliver a packet from the
+  *first* prompt: `init` has already built the index, so R29's "the first
+  prompt gets nothing, the second gets the packet" no longer applies to a
+  repository that was adopted rather than cloned.
+- `simt why` is unchanged: it deliberately does not write the cache to answer
+  a question, because writing a cache to answer a question would change the
+  tree.

package/docs/decisions/ADR-109-simt-dev-is-its-own-consumer-and-the-guards-that-kept-it-from-being-one-are-retired.md

@@ -0,0 +1,47 @@
+---
+simt-affects: ["AGENTS.md", "rules/core.md", "rules/stacks/node.md", "rules/stacks/python.md", "rules/stacks/connectiq.md", "src/projection/project.mjs", "test/baselines.test.mjs", "test/upgrade.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-109 — simt-dev is its own consumer, and the guards that kept it from being one are retired
+
+Status: **accepted** · 2026-10-30
+
+## Context
+
+This repository ran `simt init` on itself, and the suite still believed the
+opposite. Two tests asserted that simt-dev is *not* a consumer of itself — no
+manifest, no region — and `AGENTS.md` explained why self-adoption was
+impossible: the region's stamp records a SHA, so every commit would make the
+file stale.
+
+That explanation is no longer true. The `simt:sha=` stamp is a digest of the
+rule *content* — `rules/` and the baselines — not of this repository's HEAD.
+A commit here does not move it, so `check` stays green until the rule text
+itself changes, and `simt sync --yes` re-renders it when that happens.
+
+## Ruling
+
+1. **This repository is a consumer of itself.** `simt.json` declares its
+   gates, and the generated region in `AGENTS.md` carries the rules it
+   projects. The two tests that asserted the opposite are rewritten to assert
+   the new state: the baselines exist with the region first, and an `upgrade`
+   from its own source is a no-op that moves no stamp.
+2. **The rule text names the manifest by the name that resolves in every
+   repository.** Four rule files said `simt-dev.json`, the pre-rename name;
+   ADR-056 reads both and writes the new one, so a reader in any repository
+   finds only `simt.json`. The text now says `simt.json`.
+3. **A gate finding whose `detail` is absent is `null`, not `undefined`.** A
+   key with an `undefined` value survives into the structured MCP surface but
+   is dropped by `JSON.stringify`, so the two surfaces of one answer no longer
+   deep-equal. The four constructions of a region verdict now share one helper
+   that emits `null`.
+
+## Consequences
+
+- The suite's view of this repository is the adopted one: `check` here is
+  green until the rule content changes, and the baselines test asserts the
+  region-first placement that keeps a hand-written setting below it winning
+  (ADR-025).
+- `AGENTS.md`'s hand-written section now says what is true: the repository
+  adopts itself, and the stamp is a content digest.

package/docs/decisions/ADR-110-the-lock-file-follows-the-manifest-name-and-the-old-name-is-read-until-the-next-write.md

@@ -0,0 +1,43 @@
+---
+simt-affects: ["src/name.mjs", "src/projection/lock.mjs", "src/kernel/variants.mjs", "src/commands/sync.mjs", "src/commands/help.mjs", "src/bench/variants.mjs", "test/lock.test.mjs", "test/variants.test.mjs"]
+simt-supersedes: [{ adr: "ADR-086", ruling: 3, kind: "superseded" }]
+---
+
+# ADR-110 — the lock is `simt.lock.json`, and the old name is read until the next write
+
+Status: **accepted** · 2026-10-30 · supersedes ADR-086 ruling 3's file name
+
+## Context
+
+The lock followed the command's old name: `simt-dev.lock.json`. The command
+is `simt`, the manifest is `simt.json`, and the lock was the one remaining
+file that still carried the pre-rename spelling.
+
+A rename cannot be a bare move. A lock written by a pre-rename run may hold
+`variants` winners that nothing else records — the bench evidence for a
+locked rule text — so a reader that only knows the new name would silently
+unlock those decisions.
+
+## Ruling
+
+1. **The lock is `simt.lock.json`.** The old name is a read-only fallback:
+   a reader tries the new name first and falls back to the old one, and a
+   write always lands under the new name, which is how a legacy lock
+   migrates. The fallback is for absence, not for damage: a permission
+   failure on the new name does not fall back, and a file that exists but
+   does not parse is reported, not repaired by an older file. This is the
+   same read-both/write-new pattern as the manifest rename (ADR-056).
+2. **The name lives in one place.** `src/name.mjs` owns both names, the way
+   it owns the manifest's. The kernel and the projection each carried a
+   private copy — the kernel cannot import the projection, because the
+   projection imports the kernel — and two constants for one file is how a
+   rename ships half-done.
+
+## Consequences
+
+- A repository whose lock predates the rename keeps its locked variant
+  winners: `simt check --frozen` and the projection read them from the old
+  file, and the next `simt sync --yes` or `simt bench variants --yes` writes
+  them back under the new name.
+- ADR-086's ruling 3 stands for what the lock records — an input digest and
+  an output digest; the file name it named is superseded.

package/docs/decisions/ADR-111-the-tool-ships-one-agent-rendered-per-harness-and-installs-it-with-init-and-a-command.md

@@ -0,0 +1,75 @@
+---
+simt-affects: ["agents/simt-agent.md", "src/agents/render.mjs", "src/commands/agent.mjs", "src/commands/init.mjs", "src/projection/loaders.mjs", "src/toolwords.mjs", "test/agents.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-111 — the tool ships one agent, rendered per harness, and installs it with init and a command
+
+Status: **accepted** · 2026-10-30
+
+## Context
+
+The rules this tool projects tell an agent *what* to obey; nothing told it
+*how to act* through the tool. The plan for that was two agents — a planner
+and a builder — but the two jobs are one job in practice: read the tracker,
+take the next slice, build it, test it, commit it. Two files that both say
+"run the simt commands" are two copies of the same logic, and the second copy
+is where the next divergence grows.
+
+Six harnesses read a subagent and no two agree on the file. Five write a
+markdown file with YAML frontmatter and a body that becomes the system
+prompt; Codex writes a TOML file whose `developer_instructions` holds the
+same body. The path, the extension, the frontmatter keys and the document
+shape are all different, and none of them is the same fact.
+
+A hooks entry is a config key the tool merges into a file it does not own.
+An agent is a file the tool owns whole: there is nothing to merge, and the
+only question is whether the bytes on disk are the bytes the tool would write
+now.
+
+## Ruling
+
+1. **The tool ships one agent, `Simt-Agent`.** Its body is the system prompt
+   and it encodes how to act with simt-dev across the whole slice lifecycle —
+   orient (`simt brief`, `simt why`), plan (`simt plan status`, `simt plan
+   next`), build (`simt slice start`, the focused test, `simt slice finish`,
+   `simt plan done`) and the boundaries that hold everywhere. Planning and
+   building are one agent because they are one job.
+2. **The source of truth is one file, `agents/simt-agent.md`.** Neutral
+   frontmatter (`name`, `description`) plus a harness-agnostic body. The
+   renderer strips that frontmatter and re-emits the keys each harness
+   documents, so the body — the part that says how to act — is written once
+   and cannot drift between harnesses. The `simt-agent` stem is a name this
+   tool owns, and it is derived into the tool-word set from the module that
+   owns it, the way the other prefixed names are.
+3. **An agent is a file the tool owns whole, so the install is a byte
+   comparison.** `rendered` produces the text and reports `created`,
+   `unchanged` or `updated`. There is no parse that can fail and no partial
+   state, which is what makes the command shorter than `agent-hooks install`.
+4. **It is installed per harness, and the readers it does not write are
+   named.** Six harnesses document an agents file and receive one; the two
+   that document none are reported `NO FILE` with the reason, the way
+   ADR-079 ruling 11 requires. `--harness <id>` narrows the install to one
+   reader and names the skipped ones (ADR-107), and `status` reports
+   present, absent, drift, and the readers with no file.
+5. **It is written by `simt init` and by a separate `simt agents install`.**
+   `init` plans the agent files with the rest of the adoption and writes them
+   in the apply path, journaled the same way, so `undo` restores them with the
+   rest. The separate command exists for a repository that is already adopted
+   and wants only the agent, and for a narrowed install. Both call the same
+   `planAgents` and `writeAgentPlan`, so a dry run and a run describe the same
+   set of files.
+
+## Consequences
+
+- A repository that is adopted and later upgrades the tool's agent body runs
+  `simt agents install --yes` (or re-runs `init`) and the files come back
+  `updated` with the new body; the frontmatter each harness documents is
+  re-emitted from the same source, so it cannot drift.
+- The agent body names only commands a consumer repository runs — `simt
+  brief`, `simt why`, `simt plan`, `simt slice` — so every byte in it is
+  actionable in the receiving repository, the rule this repository exists to
+  enforce.
+- `agents/` is published with the package: the tool reads its own agent body
+  from the installed copy, and a tarball without it would install cleanly and
+  then fail on the one command that writes the agent.

package/docs/decisions/ADR-112-the-registry-is-what-simt-dev-ships-and-a-repo-owns-its-own-skills.md

@@ -0,0 +1,81 @@
+---
+simt-affects: ["graph/skills.graph.json", "src/resolve/local.mjs", "src/commands/skills.mjs", "src/projection/disclosure.mjs", "src/resolve/body.mjs"]
+simt-supersedes: [{ adr: "ADR-009", ruling: 4 }]
+---
+
+# ADR-112 — the registry is what simt-dev ships, and a repo owns its own skills
+
+Status: **accepted** · 2026-10-31 · filed as S4 (plan 0005) · supersedes ADR-009 ruling 4
+
+## Context
+
+ADR-009 settled the layout: a skill is `<name>/SKILL.md` with mandatory `name`
+and `description` frontmatter, and body size and reference count are declared in
+`graph/skills.graph.json`, "so the registry stays the single source of truth for
+resolution metadata". The layout half of that ruling was about one estate's
+thirty-nine skills, and the metadata half assumed the estate was the universe: a
+skill not in the graph is a skill that does not exist.
+
+Plan 0005 broke that assumption in two slices. S2 removed the thirty-one
+repo-specific entries from the graph, leaving the eight skills this tool ships —
+`simt-commands` and seven vendored stack skills. A graph that describes one
+estate and is read by everyone was ADR-061's finding; a graph that is one
+estate's whole skill population is a stronger claim ADR-061 did not make, and S2
+made it false. S3 then gave the repo's own skill directories standing in the
+resolver: `skills find`, `brief`, `show` and `why` answer for a skill the
+registry never declared, synthesising its node from the file — name and summary
+from frontmatter, size from the file, body from the path (commit 7d44071).
+
+A reader of ADR-009 acting on the metadata sentence concludes that a skill absent
+from the graph has no resolution metadata, and therefore cannot resolve. That
+conclusion is now false in every repo that keeps its own skills, and a record
+that says what the tool no longer believes is the failure this directory exists
+to prevent.
+
+## Ruling
+
+1. **The graph is a catalogue of what simt-dev ships, not the sole home of
+   skills.** Membership in `graph/skills.graph.json` is a statement about the
+   package, not about existence. A skill a repository installed in its own skill
+   directories exists and resolves with no entry in the graph.
+2. **A repo's skill directories are a first-class source of resolution.**
+   Presence is the eligibility signal — a skill the repo installed is about the
+   repo, and the stack it belongs to is the stack the repo has. Frontmatter
+   supplies the name and the summary; the file supplies the body and the size.
+   This is the mechanism S3 shipped; the ruling records it so the reader learns
+   what the tool believes without reading the plan.
+3. **Where a name is in both, the registry entry is canonical.** The graph entry
+   and the local file are one skill — the file is the installed copy of what the
+   graph declares — and keeping both would rank one skill twice. The graph wins
+   the dedupe; the local node is dropped, not merged.
+
+## Consequences
+
+- ADR-009's layout ruling stands and is load-bearing: discovery reads `name` and
+  `description` from frontmatter, so a local skill without them is invisible,
+  which is the defect class ADR-009 exists to prevent. What moves is the metadata
+  sentence: a local skill's resolution metadata is synthesised from the
+  filesystem, not read from the graph, so the graph is no longer the single
+  source of truth for it.
+- `skills find`, `brief`, `show` and `why` answer for names the registry never
+  declared. The NOT SELECTED block no longer points a reader at a `skills show
+  <name>` that 404s for a name the graph does not carry.
+- Nothing in the shipped bytes changes. ADR-061 stands as written: the registry
+  is workspace data, the package ships none of it, and a command that finds no
+  registry says so. This record settles the half ADR-061 left open — who is
+  allowed to have skills the catalogue does not name — without touching its
+  rulings.
+- `skills index` keeps reporting the catalogue only: it is the tier-0 view of
+  what this tool ships, and local skills surface where a repo is the context,
+  which is `find` and `brief`.
+
+## Rejected
+
+- **Rewrite ADR-009 in place.** The supersession rule this directory opens with
+  is a new record and an edited status line, never a rewritten ruling. ADR-009's
+  audit data — the forty-six frontmatter tallies that found the flat file — is
+  evidence its own ruling relies on, the same shape that kept ADR-011 standing
+  when ADR-012 reversed it.
+- **Annotate ADR-009 without a record.** The supersession is a claim about what
+  the tool believes, and a claim without a record is a ruling nobody can cite.
+  The annotation points at ADR-112; ADR-112 carries the argument.