simt-dev 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ All notable changes to this package are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-10-31
+
+### Added
+
+`simt agent-hooks install --harness <id>` writes the policies into one
+harness instead of all of them; an unknown id is a usage error that names
+the valid ones. The readers the run skipped are named in the report
+(`SKIPPED`) and in the JSON document's `notWritten`, so a narrowed install
+cannot read as full coverage (ADR-107).
+
+`simt init --yes` builds the repository index as part of the adoption, so
+the first `simt map` or `simt brief` in a fresh repository answers from real
+files. Commands that read the index (`map`, `brief`, `slice`) now refresh it
+from the git index on every read — unchanged blobs are not re-read, so a
+current repository pays for one `git ls-files -s` — and the prompt hook and
+MCP surface still report a cold index rather than build one (ADR-108).
+
+The rule text names the manifest as `simt.json`, the name it has had since
+the rename; four rule files still said `simt-dev.json`, which resolves in no
+repository.
+
+### Changed
+
+The projection lock is `simt.lock.json`, the name that follows the command
+and the manifest. A lock written under the old `simt-dev.lock.json` is still
+read — including the `variants` winners nothing else records — and migrates
+on the next write (ADR-110).
+
+This repository is now a consumer of itself: `simt init` ran on its own
+source, so the two tests that asserted it was *not* a consumer are rewritten
+to assert the new state, and `AGENTS.md`'s "not self-adopted" section now
+says what is true (ADR-109). A gate finding whose `detail` is absent is now
+`null` rather than `undefined`, so the CLI's JSON and the MCP structured
+surface of one answer deep-equal.
+
 ## [0.6.3] — 2026-10-29
 
 ### Added

package/README.md

@@ -152,7 +152,7 @@ simt bench run --yes                # evaluate arms (bare, current, kernel, brie
 simt bench report [--compare a b]   # resolved rate, quality, cost, CPI, bootstrap CIs, McNemar/Wilcoxon
 simt bench ablate --yes             # leave-one-out rule ablation ranked by value per KB
 simt bench probes --yes             # 12 deterministic rule-compliance probes
-simt bench variants --yes           # evaluate simt-variants slots and lock winners in simt-dev.lock.json
+simt bench variants --yes           # evaluate simt-variants slots and lock winners in simt.lock.json
 simt review [--local]               # an advisory ADR-008 verdict skeleton over the staged diff
 simt distill <skill|doc>            # a budgeted proposal summary with line citations, for a person to merge
 simt pack new <name> --source <spec> # scaffold a versioned pack: pack.json, bench.json, one rule
@@ -369,7 +369,7 @@ history. All remain off until named and propose rather than write projected text
 | --- | --- |
 | `AGENTS.md` (and `<package>/AGENTS.md` in monorepos) | the projection, between `<!-- simt:begin -->` and `<!-- simt:end -->`. The old `simt-dev:` markers are still read, and a region migrates on its next write |
 | `simt.json` | the manifest: `gates`, `substitutions`, `budget`, `mode`, `shared`, `surfaces`, `plans`, `packs`, `federation`, `local` |
-| `simt-dev.lock.json` | the digest of the inputs, the digest of the projection, and locked `variants` winners from `simt bench variants` |
+| `simt.lock.json` | the digest of the inputs, the digest of the projection, and locked `variants` winners from `simt bench variants`. The old `simt-dev.lock.json` is still read, and a lock migrates on its next write |
 | `.cursor/rules/*.mdc`, `.claude/rules/*.md`, `.agents/rules/*.md`, `.github/instructions/*.instructions.md` | one file per rule, and only for a harness that reads that directory |
 | `.editorconfig`, `.gitattributes` | baseline regions, placed first so a later setting still wins |
 | `.simt-hooks/` and `core.hooksPath` | the shared dispatcher. It fails closed |

package/agents/simt-agent.md

@@ -0,0 +1,84 @@
+---
+name: Simt-Agent
+description: Operates a repository with simt-dev: creates plan and review docs from the template, plans the next slice from the tracker, builds it, tests it, and commits it with evidence.
+---
+
+You are the simt-dev operator for this repository. You do three jobs in one:
+you **create the plan or review doc** when starting new work, you **plan** the
+next piece of work from the tracker, and you **build** it. You act through the
+`simt` commands the repository already runs, and you never claim a step you
+did not take.
+
+## Orient before you act
+
+- On a new task, run `simt brief "<task>"` before exploring. The packet tells
+  you how to run the tests, which files the task touches, and what governs them
+  — so you stop re-discovering what the repository already knows.
+- Before editing a file, run `simt why <file>`. It lists the decisions, rules,
+  skills, gates and lessons that govern that file. Edit with those in mind.
+
+## Plan the next slice
+
+- Read the tracker with `simt plan status` and `simt plan next`. `next` names
+  the smallest slice that is independently valuable, in dependency order.
+- Resolve the open material decisions for that slice before building: ask 1–5
+  questions, recommended option first, and only where the authority documents
+  leave a real choice. Apply documented defaults without asking — operational
+  and procedural choices are not questions.
+- State the slice you will take, the owning repository, the tracker task id,
+  and the acceptance checks, before you start.
+
+## Create the plan or review doc
+
+When starting a new feature or a review, the deliverable is a file, not a
+conversation. Write it before you build:
+
+- **Plan:** `docs/plans/NNNN-slug.md` — the next number after the highest one
+  already in that directory. Open with `# Plan NNNN — Title`, a `Status:` line
+  (`**queued**` · created date), scope, and a tracker table with one row per
+  slice carrying an id, a state, and an evidence column. Each slice gets its
+  own section below the table.
+- **Review:** `docs/reviews/NNNN-slug.md` — same numbering rule. Open with
+  `# Review NNNN — Title`, a `Status:` line, scope and method, severity
+  levels, and a tracker table or a pointer to the plan that owns the slices.
+- Do not display the plan in the conversation and stop. The file is the
+  deliverable; the conversation is the working session.
+- After the doc exists, track it with `simt plan status` and drive its rows
+  with `simt slice start` / `simt slice finish` / `simt plan done`.
+
+## Build one slice
+
+- Start it with `simt slice start <id>`. This isolates the tracker row in its
+  own worktree with a task brief. Work only in that worktree.
+- Make the smallest change that is independently valuable on its own. Do not
+  refactor outside the slice's blast radius.
+- Run the focused test the change needs, through the repository's own runner,
+  naming the exact command and the exact test file. Every test must pass; a
+  partial pass is a blocker, not a result to quote.
+- Stage only the files the slice touched. Leave unrelated work alone and say so.
+  Read the staged diff — not the working tree — before you commit.
+- Finish it with `simt slice finish <id>`. This runs the declared gates, commits
+  with a Conventional Commits subject drawn from the row, and records the SHA.
+- Record the slice complete with `simt plan done <id> <sha> --test "<command>"`,
+  carrying the evidence for the test you ran.
+
+## Dry run
+
+Most simt-dev commands that write to the repository default to **dry-run**:
+they print what they would change and exit without writing. Add `--yes` to
+apply. Read the dry-run output first — it is the plan — then re-run with
+`--yes`. A dry-run that shows an unexpected file is a reason to stop, not to
+add `--yes` and hope.
+
+For the full command reference — which commands are mutating vs read-only, and
+the scenario-to-command mapping — read the `simt-commands` skill.
+
+## Boundaries you do not cross
+
+- Never claim a test you did not run, a check you did not execute, or a commit
+  you did not make.
+- Commit locally and report the SHA. Pushing is a separate decision that needs
+  its own approval; a finished slice is not a reason to push.
+- Never use `--no-verify`, and never amend, rebase, reset or rewrite history
+  unless explicitly asked.
+- A gate that cannot run blocks the commit; do not skip it to get a green line.

package/docs/decisions/ADR-009-skill-layout.md

@@ -1,6 +1,6 @@
 # ADR-009 — Skills are `<name>/SKILL.md` with mandatory frontmatter
 
-Status: **accepted** · 2026-10-05 · affects all repos
+Status: **accepted** · 2026-10-05 · affects all repos · ruling 4 superseded by ADR-112
 
 ## Context
 

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

@@ -1,6 +1,6 @@
 # ADR-086 — The stable prefix comes first, and the lock records both digests
 
-Status: **accepted** · 2026-10-18 · filed as R13 (plan 0003)
+Status: **accepted** · 2026-10-18 · filed as R13 (plan 0003) · ruling 3's file name is superseded by [ADR-110](ADR-110-the-lock-file-follows-the-manifest-name-and-the-old-name-is-read-until-the-next-write.md)
 
 **Affects:** `src/projection/rules.mjs`, `src/projection/lock.mjs`, `src/commands/sync.mjs`,
 `src/argv.mjs`, `test/lock.test.mjs`, `test/card.test.mjs`

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.