simt-dev 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,172 @@ All notable changes to this package are recorded here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.2.1] — 2026-10-13
+
+### `init` writes in place; the backup tag and adopt branch are opt-in
+
+`simt init --yes` used to always tag the pre-adoption commit and branch onto a dedicated
+adopt branch before writing. The safety argument was sound, but consumers kept reporting
+the branch switch as a surprise — a well-announced surprise is still a surprise.
+
+The default now writes in place on the branch you already have: nothing is tagged, nothing
+is branched, and the run says so in an `in place` line. The reviewable diff survives —
+`git diff` shows the whole adoption, and discarding it is a checkout and a clean.
+
+The old behaviour moves behind `--backup`: `simt init --yes --backup` tags the pre-adoption
+commit and branches as before, for readers who want the named undo path. ADR-063 records
+the decision and the one behaviour it invalidates: consumers who scripted against the old
+default add `--backup`.
+
+### A fresh adoption seeds the gates it can run — and only those
+
+The eight common ecosystems outside the JavaScript world — Rust, Go, .NET, Swift, Deno,
+Ruby, Dart and Elixir — were recognised by the fingerprint and served by nothing: no
+profile selected them, no gate was proposed for them. A fresh Rust repository received the
+core essay and a manifest that runs nothing, while the ecosystems that emit stack tags got
+the full treatment.
+
+Each now has a profile that selects on its own `has-*` fact, so one marker file reaches
+both the rules the repository reads and the gates its commits run. Maven's profile predates
+this; its row is gates-only, wrapper-first, like `gradlew`.
+
+`simt init` now seeds the canonical commands for a detected ecosystem — `cargo fmt
+--check`, `go vet ./...`, `dotnet test`, and the rest of the table — into the manifest's
+gates, but only where a probe found the tool: a binary on PATH, or a file in the repository
+for the Maven wrapper. A marker says the ecosystem is here; the probe says its program can
+run. A declared gate that cannot run fails closed on every commit, so the seed fires only
+when both are true — and where the probe fails, the gate is dropped with a remedy that
+names the install instead of blocking the first commit.
+
+A seed is a default: a command the repository already declared is never re-seeded, and an
+npm runner keeps its own scripts, because `package.json` is the repository's own answer to
+"how do I test and format". ADR-062 rules the shape of all of it.
+
+### The resolver is measured against a gold corpus
+
+`simt skills eval` scores the skill resolver against a corpus of real tasks × real
+repositories, each case carrying a gold list of the skills it should select and a list
+of the ones it must not. It reports precision and recall, prints a PASS/FAIL line per
+case naming the skills it missed or selected that it should not have, and exits
+non-zero on a regression — so it can be run from CI the way the gate is run.
+
+The scoring lives in `src/resolve/eval.mjs`, which the command and
+`test/eval.test.mjs` both call, so a test cannot drift from what the command measures.
+The corpus lives under `test/` because test data does not ship in the package: an
+installed copy names the path it would have read and says so instead of scoring the
+author's.
+
+### The skill registry is workspace data; the package ships none of it
+
+The npm tarball and the wheel carried `graph/skills.graph.json` — the directory
+of skill sources for one workspace, naming the repositories whose bodies it
+resolves. Every installed copy served that catalogue to readers who have none
+of those skills, and `skills install` pointed at paths that exist only in the
+workspace that wrote them. ADR-061 rules the registry out of the published set:
+it is data about one workspace, not content of the package.
+
+The default registry path now resolves in tiers, and every tier is file
+existence plus configuration — nothing a pull request cannot diff:
+
+1. an explicit path, the positional of `simt graph lint`,
+2. the package's own `graph/skills.graph.json` — present in a source checkout,
+   absent from an installed copy,
+3. the member of a configured workspace that holds one — naming the workspace
+   it came from, and refusing when several members hold one, because picking
+   would be a guess.
+
+An installed copy in a workspace with no registry says so, and names the three
+ways to configure one (`--workspace`, `SIMT_DEV_WORKSPACE`, the user config
+file) instead of failing on a path it does not have. `simt graph lint`'s
+no-registry remedy names the path explicitly, because its default is the
+registry it lints.
+
+The provenance digest stops walking `graph/` for the same reason it no longer
+leaves the package: the digest covers what a published copy ships, and the
+registry is no longer among it.
+
+### No published file may name a repository from this estate
+
+The decision records ship in all three channels — npm, the wheel and the sdist — so a
+private repository name written into one is published to three registries. That happened:
+the records were pseudonymised once, across 28 files, and nothing stopped the next one. The
+sweep's own commit says why, and it is the right reason: the redaction it used runs on the
+way *out*, at print time, and the bytes on disk are what get published.
+
+`test/shipped.test.mjs` now fails on an estate name anywhere in a published file, and
+asserts its own scope against `package.json` in **both** directions — a directory added to
+`files` without being guarded fails, and so does one guarded that nothing publishes, because
+a guard nobody can fail is one somebody eventually deletes. It is scoped to the published
+set rather than a hand-written list for the same reason: the sweep took 28 files to undo by
+hand, and the guard should not need undoing at all.
+
+Names are not removed, they are described. The records that use a repository as *evidence* —
+a table of how three repositories answer the same question — carry stable `repo-NN` labels,
+so the comparison survives. Everything else is better off naming what the repository *is*:
+"a Gradle module with no wrapper", "a repository with no package.json". That reads to
+someone outside the estate without a lookup table they do not have.
+
+The one place estate names remain is `docs/reviews/`, which is not published by either
+channel. A review whose subject is fourteen repositories cannot pseudonymise them without
+becoming a document about `repo-01` that never existed.
+
+### Four shipped strings named a command this package does not install
+
+`0.2.0` installs one binary, `simt`, and `package.json`'s `bin` map says so. Four
+places still said `simt-dev`, which a reader types and is met with `unknown command`:
+
+- the default remedy on every bad invocation, `run: simt-dev --help` — so the advice
+  printed after a bad command could not be followed
+- the usage line, `usage: simt-dev <command>`, sitting above a command list that spelled
+  the same tool `simt`
+- `.github/dependabot.yml`'s header, which said `Yours from here: simt-dev` while the
+  gate beside it said `Yours from here: simt`
+- the hook shim, whose own resolution list said `simt-dev on PATH` directly above the
+  `command -v simt` that does the looking
+
+`test/naming.test.mjs` was supposed to prevent this and did not: its rule required a
+verb after the project name, and none of the four is followed by one. It now also
+catches a flag, a `<placeholder>`, the end of a line, and a program name in a
+resolution list — while still accepting the sentences where the project is the
+subject, which is the spelling that is correct. The two `.github` templates get their
+own assertion, because the fourth of these was not a wrong word in a sentence; it was
+two templates disagreeing with each other in the same position.
+
+### Fixed
+
+- `hooks install` removes a shim whose gate was dropped from the manifest instead of leaving it to run nothing. A repository that removed its last gate was refused outright, with a remedy telling it to put the gate back; only un-routing git was left to the reader. install also no longer chains a hook to itself.
+
+- **Dead exports and duplicated frontmatter, with a test that stops them returning (S21).**
+  Eight functions were exported and called by nothing (`gateKind`, `gateWhy`, `gateAdr`,
+  `resetWorkspace`, `tracksIdentity`, `isTty`, `surfaceFrontmatter`, `workspaceOrNull`),
+  three `__internals` testing seams had no importer, and thirteen more bindings were
+  exported while being used only inside their own file — `isExecutable` among them, which
+  a first pass through this list wrongly recorded as dead and which its own callers
+  proved otherwise. `KNOWN_SUBS` was a hand-kept second copy of the dispatch table, and
+  had already drifted: it carried `doctor`, a bare command the group lookup can never
+  reach. `mdcFrontmatter` was a second construction of frontmatter the writer now derives
+  itself, with a test asserting the copy rather than the behaviour.
+
+- **"Did you mean" offered the shortest fragment first, and a misspelt skill was
+  suggested for a correctly spelled one (S22).** `nearMatches` had no test at all.
+  Both directions of substring scored 0 — the same score as an exact match — so the
+  alphabetical tiebreak decided the order, and `skills graphs` suggested `graph`
+  before `graphs`. Worse, the containment test had no length floor, so `test` matched
+  the candidate `e` and the message read `did you mean e, test-writer?`, which an
+  agent has every reason to install. A prefix now scores 1 rather than 0, a fragment
+  counts only when it is at least half the query, and the edit bound scales with the
+  query's length — three edits is a typo in `slice-commmit` and is most of a
+  four-character query.
+
+- **The conflict scanner skipped two of the five rule surfaces, and one pointer file
+  (S22).** `rulePaths` enumerated filenames by hand, so `.claude/rules/` and
+  `.agents/rules/` — added to the surface table after the list was written — were
+  never scanned, and a hand-written rule contradicting a generated one there was
+  invisible. A conflict detector that only looks where it was pointed looks nowhere
+  new. The scan list is now derived from the surface table and the pointer table.
+
 ## [0.2.0] — 2026-10-11
 
 ### Publishable from PyPI and Homebrew as well as npm
@@ -48,17 +214,17 @@ recommending. It chained on the event *vocabulary* — anything that was not
 `pre-commit` or `pre-push` — when the question worth asking is whether **this
 repository** declares a gate for that event.
 
-The difference is `simt-app`, whose `pre-push` is `git-lfs`. `pre-push` is an
+The difference is a repository whose `pre-push` is `git-lfs`. `pre-push` is an
 event this tool gates in general, so `0.1.0` displaced that hook; and because
-`simt-app` declares no `pre-push` gate there was no shim for the event either, so
-git would have found no `pre-push` hook at all. LFS objects would have stopped
-being uploaded, with nothing to notice it — the exact silent failure chaining
-exists to prevent, reached by fixing the wrong half of it.
+that repository declares no `pre-push` gate there was no shim for the event
+either, so git would have found no `pre-push` hook at all. LFS objects would have
+stopped being uploaded, with nothing to notice it — the exact silent failure
+chaining exists to prevent, reached by fixing the wrong half of it.
 
 `0.1.1` asks the manifest. An event the repo declares a gate for is left to
 `gates.commands`, where the hook runs as a gate and its verdict appears in the
-report; every other foreign hook is chained. That also picks up
-`simt-landing`'s Lighthouse pre-push, which declares no gates at all.
+report; every other foreign hook is chained. That also picks up a static
+site's Lighthouse pre-push, which declares no gates at all.
 *(ADR-018, as amended)*
 
 Upgrade with `npm i -D simt-dev@0.1.1`, then `simt hooks install --yes`. Any

package/README.md

@@ -23,13 +23,13 @@ Requires **Node >= 22.20.0** (the PyPI install can supply it, see below).
 
 ```sh
 # pinned, per repository - what CI and a teammate both get
-npm i -D simt-dev@0.2.0
+npm i -D simt-dev@0.2.1
 
 # or globally, if you would rather not add a dependency
-npm i -g simt-dev@0.2.0
+npm i -g simt-dev@0.2.1
 
 # or with no install at all, for a one-off
-npx -y simt-dev@0.2.0 check
+npx -y simt-dev@0.2.1 check
 ```
 
 ### From PyPI
@@ -81,7 +81,7 @@ simt compare         # what changed across every repository that adopted it
 | Path | What |
 | --- | --- |
 | `AGENTS.md` | the projection, between `<!-- simt:begin -->` and `<!-- simt:end -->` (renamed from `simt-dev:`; the old markers are still read, and a region migrates on its next write) |
-| `simt.json` | your manifest: which gates to declare, which substitutions to fill (renamed from `simt-dev.json`; the old name is still read, and moves on the next write) |
+| `simt.json` | your manifest: which gates to declare, which substitutions to fill |
 | `.cursor/rules/*.mdc`, `.claude/rules/*.md`, `.agents/rules/*.md`, `.github/instructions/*.instructions.md` | one file per rule, written only for the harnesses that read their own directory |
 | `.editorconfig`, `.gitattributes` | baseline regions |
 | `.simt-hooks/` and `core.hooksPath` | the shared dispatcher, fail-closed |

package/docs/decisions/ADR-019-a-declared-command-is-the-runner.md

@@ -72,6 +72,33 @@ One manifest. Three answers. The one I would have shipped if I had only run `che
    every file (`ENOTDIR`) and classified every Gradle repository in the estate as having no
    runner at all — a wrong answer from an evidence reader, which is worse than no answer
    because the caller cannot tell them apart.
+8. **A declared command is a shell command line, not an argv.** *(S17, 2026-10-12)*
+
+   It was split on whitespace and handed to `execFile` as an argv. That made a declaration
+   a repository would plausibly write run the wrong thing rather than fail: a flag whose
+   value contains a space became two arguments, and the quotes in a compound line were
+   passed to the program as literal characters. There was no way to express a quoted
+   argument at all, and nothing said so.
+
+   So `gates.commands[name]` is one line, run through `sh -c`, and everything the
+   repository wrote in it survives — quotes, pipes, `&&`, a path with a space. This is the
+   same line the repository would type into its own shell, which is the only definition of
+   "what this repository means by that" that does not require a parser here.
+
+   **The trust boundary is the repository, and it is not a sandbox.** The line comes from
+   the repository's own manifest, which it can read and change, and it runs on its author's
+   own machine when that author commits. `sh -c` adds no privilege: the same person who
+   wrote the line could run it. What `sh -c` must not do is apply to anything this tool
+   resolved itself — a formatter path out of `node_modules/.bin` stays an argv, because
+   handing it to a shell would change who decided its arguments for no gain. The two
+   sources are separate branches in the dispatcher rather than a flag, so the distinction
+   cannot be forgotten by a caller that does not know it exists.
+
+   **Consequence for a repository that relied on the split.** A declaration with no quotes
+   behaves identically, because whitespace-splitting a shell word that needed no quoting
+   is the same thing the shell does. Every use of `gates.commands` in this estate declares
+   a bare path and is unaffected; the change only makes declarations *possible* that were
+   previously impossible rather than making any of them wrong.
 
 ## Consequences
 

package/docs/decisions/ADR-059-the-version-a-repository-runs-is-the-one-it-pinned.md

@@ -0,0 +1,75 @@
+# ADR-059 — The version a repository runs is the one it pinned, and the gate refuses otherwise
+
+Status: **accepted** · 2026-10-12 · affects all repos
+
+## Context
+
+ADR-010 ruled that a tool which is genuinely not a project dependency may be invoked directly,
+**provided its version is pinned**. For a repository with a `package.json`, simt-dev is that
+dependency, and npm does the pinning: it installs the version in `package.json` into
+`node_modules`, and a stale copy is a stale lockfile that `npm ci` reproduces.
+
+For a repository **without** npm — a Gradle build, a Connect IQ project — there is no
+`node_modules` to pin in. simt-dev is a global install, and nothing pins it. The version on
+`PATH` is whatever the last `npm i -g` left there, and it can be anything. The gate that runs
+on commit is the one in that binary. If it is not the version the repository adopted, the gate
+that runs locally is not the one CI runs: a green tick from a check that ran the wrong version
+is the one outcome worse than a red build, because it is a pass that never happened.
+
+The same gap sat in the remedy. The shim and the consumer workflow assumed npm everywhere —
+`npm i -D simt-dev@<v>` and `npm ci`. In a Gradle repository that command installs into a
+`package.json` the repository will never have, so the remedy cannot succeed and the CI step
+cannot start. The install and the remedy each needed to know the kind of repository they were
+in, and neither did.
+
+## Ruling
+
+1. **The manifest records the version a repository adopted.** `projection` carries
+   `version` alongside the existing `simtDevSha`, written at adoption and refreshed by
+   `upgrade`. A node_modules copy is pinned by npm itself, so this field matters only where
+   npm is not the pin — but it is written everywhere, because a manifest that records the
+   version in one shape of repository and not another is two manifests.
+
+2. **The gate compares the running binary against that pin, and refuses on a mismatch.** The
+   comparison is in the dispatcher (a failed `version` gate) and in `check` (a blocking
+   finding), not in the shim's rendered bytes: the dispatcher is where every gate already runs,
+   and a comparison duplicated into bytes a formatter might rewrite would drift from the one
+   that decides. It is placed after the empty-gate check on purpose — a repository that declares
+   no gate has nothing the version could get wrong, and failing it would block commits in repos
+   that deliberately declare none.
+
+3. **The install and the remedy are per kind.** Where a `package.json` exists, simt-dev is pinned
+   as a devDependency and the remedy is `npm i -D simt-dev@<v>`. Where there is no npm, it is a
+   pinned global install and the remedy is `npm i -g simt-dev@<v>` (or `export SIMT_DEV_BIN=…`).
+   The consumer CI workflow makes the same choice by kind — `npm ci` where the package is a
+   declared dependency, the pinned global install otherwise — so the gate that runs in CI is the
+   one the machine remedy names, and a check cannot pass in one place and fail to start in the
+   other.
+
+## Consequences
+
+- A stale global binary can no longer produce a green tick from a check that ran a different gate
+  than CI does. The mismatch is a refusal with the one command that fixes it, and the remedy and
+  the CI step agree on which version to install.
+- A repository adopted before the field existed — a manifest with `simtDevSha` but no
+  `projection.version` — is **skipped, not failed**. There is nothing to compare against, and
+  failing every pre-0.2 repository the moment this check ships would turn the gate red for a
+  reason it cannot fix. `compare` reports that missing field as a stale manifest (ADR-045's
+  defect from the far side), so it is visible and repairable rather than silently absent.
+- The version a repository runs is now an invariant the gate enforces, not a comment: the pin in
+  the manifest and the binary on `PATH` must agree, or the commit does not happen.
+
+## Rejected
+
+- **Shell out to `simt --version` in the shim.** The dispatcher runs from the binary that
+  resolved it, so reading the running package's version is the same answer without a subprocess,
+  and it is correct whether the binary came from `node_modules`, a global install, or a source
+  checkout. A subprocess would answer only for the binary that started it.
+- **Fail a repository with no recorded pin.** There is nothing to compare against; it would make
+  every pre-0.2 repository red on the day this ships, for a mismatch nobody can resolve until
+  they re-adopt. The missing pin is reported as drift, which is the repairable form of the same
+  fact.
+- **Put the check only in the shim's rendered bytes.** The dispatcher is where every gate runs and
+  where `check` already lives, so the comparison belongs in one place. Rendered bytes are read by
+  a formatter and a reviewer; a control that lives in both is two copies of one question, which
+  is the shape this record's siblings keep finding drifting.

package/docs/decisions/ADR-060-a-repository-with-nothing-to-run-is-adopted-and-says-so.md

@@ -0,0 +1,131 @@
+# ADR-060 — A repository with nothing to run is adopted and says so, and a gate is verified where it runs
+
+Status: **accepted** · 2026-10-12 · filed as S36
+**Affects:** `hooks install`, `compare`, the adoption criterion in review 0002
+
+## Context
+
+Review 0002 defined adoption as eight things a repository must have, and gave the estate
+roll-out an acceptance criterion: every repository current, every repository routed, no
+unrunnable gate, and a green CI run in every repository that has CI. Fourteen repositories
+were in scope.
+
+Three of them cannot satisfy the second of those, and the row contradicted itself about it.
+The runbook's own step 4, for one of the three, reads: *"none (no runner). Record that in
+the manifest rather than invent one."* That is an instruction not to route it. The
+acceptance criterion then requires that it be routed. One of the two is wrong, and the row
+could not be closed without settling which.
+
+This stopped being hypothetical when the roll-out ran. The three are:
+
+- **A Gradle module consumed as a submodule.** It has no wrapper of its own — the two
+  repositories that embed it own that — so `./gradlew` cannot be run from it. Its
+  `package.json` declares no scripts at all; it exists to carry one devDependency.
+- **A repository with no `package.json`.** No runner, no scripts, nothing to probe.
+- **A static site with no gate and its own hook.** No `format:check` and no `test` script to
+  declare a gate from, and a Lighthouse pre-push in `.githooks/` that routing would displace.
+
+Each is ungated for a reason that was checked rather than assumed, and each records that
+reason in its own commit message.
+
+ADR-017 already settled the principle in one direction: a gate is declared only if the
+repository can run it. This record settles the other, which fourteen repositories of real
+use never exercised — what a repository that can run nothing looks like once it has adopted
+the tool.
+
+A second thing surfaced at the same moment, and it is not a repository's fault. The roll-out
+pushed to fourteen repositories and GitHub Actions executed no steps: every run completed
+with `failure`, zero steps, and no logs — including a pre-existing lint-and-test workflow
+whose body this work never touched. Actions reports `enabled: true` on all eight
+repositories; the organisation-level setting needs `admin:org` and could not be read. The
+workflow files parse, and the same workflows have run before. The jobs are not starting.
+
+## Ruling
+
+**One. A repository that cannot run a gate is adopted when it says so, and routing is not
+required of it.** `hooksComplete` is not the measure of adoption, and "every repository
+routed" was never achievable. The three carry the evidence in the manifest and in their own
+commit messages: what is missing, and why. That is a stronger artefact than a shim that
+runs nothing — which is what forcing them would have produced, and which the runbook already
+forbade inventing.
+
+**Two. A gate must be runnable, and a shim must not be installed over one that is working.**
+This is ADR-018 as amended, restated because the roll-out made it concrete. The static site's
+pre-push keeps running in `.githooks/` precisely because its manifest declares no `prePush`
+gate and therefore nothing displaces it. Routing a repository that enforces nothing is not
+a smaller change than routing one that does: `core.hooksPath` moves, git reads every hook
+from the one directory, and the gain is zero.
+
+**Three. "Green CI" is verified where CI runs, and is not a property of a repository when it
+does not.** The clause is replaced by two that can be answered: the workflow file is present
+and valid in every repository that has one, and the gate runs locally. Whether GitHub
+executes those workflows is a fact about the account, and a gate that reports a property it
+cannot observe is ADR-039's defect — the step that cannot fail is the one nobody reads.
+
+**Four. The estate's CI runs on pull requests, and delivery does not.** A check that fires on
+a timer is not evidence about a change: by the time it reports, the commit is days old and
+nobody is waiting on it. That is why the weekly runs were removed rather than de-scheduled.
+It is also why the two API-contract workflows were split out of the `ci.yml` files they
+shared: republishing to the edge needs a credential a fork does not have, so it fires on
+merge to `main`, and one workflow cannot carry two triggers once its checks and its delivery
+need different ones. The template moved in one commit and the estate followed the template,
+which is the only way to move fourteen repositories that do not own the file.
+
+**Five. The measure is `check`, and `compare` is what makes it visible at estate scale.**
+ADR-045 made `compare` count a defect it had been hiding. This cycle found the same row
+reporting every repository current while `check` exited non-zero in all of them. Both are now
+driven at one fixture and compared — a parity test, because two copies of one question, each
+asserted separately, is how they drift. That is ADR-052's shape, reached from a different
+direction.
+
+## Consequences
+
+- **The roll-out closes with eleven of fourteen routed, and the three exceptions named in
+  three commit messages** rather than in a dashboard. An audit trail beats a count.
+- **If one of the three gains something to run, it routes in one command** and nothing else
+  about it changes. This is not a permanent exemption; it is the current answer to "can this
+  repository enforce anything", and `compare` re-reads it every run.
+- **The result is stronger than the row asked for.** Every repository's gate exits zero,
+  every manifest records a released version, no rule is loaded twice, no declared gate is
+  unrunnable, and no region sits past a harness's read limit. Three of those were false when
+  the row was written.
+- **The CI clause is recorded as unverified, not met.** Nothing in a repository can make
+  GitHub execute a workflow, and a claim about a green build nobody has seen is the thing
+  this repository's own rules exist to prevent. Re-run the query and the clause comes back.
+
+## Rejected
+
+- **Route the three anyway, with an empty gate list.** `hooks install` already refuses —
+  it prints *"declares no gate it can run, so there is nothing to enforce."* Overriding it
+  means a shim on every commit that dispatches, reads a manifest, and exits having enforced
+  nothing. The cost is a repository that believes it is gated.
+- **Declare a gate to satisfy the count.** That needs a name for a check that does not
+  exist. The Connect IQ repository has the shape of this: seven scripts in `scripts/` that
+  all run, and a gate vocabulary with no name for five of them. Two were declared, where the
+  name matched, and the other five stay manual rather than borrow `test` or `lint` — a gate
+  whose printed name misdescribes the command it runs teaches a reader not to trust the
+  other seven.
+- **Keep the weekly runs because they are "just checks".** They were the most expensive
+  thing in the estate — the Android one booted a headless emulator every Saturday — and the
+  least timely. Where the checks were worth keeping they moved to the pull request that
+  changes the code, and one repository's own test suite refused the push that deleted them,
+  which is the gate working.
+- **Close the row before measuring it.** Every figure in this record comes from a committed
+  build run over the estate, not from the working tree that produced it. That distinction
+  matters here: earlier in this cycle an apparent fourteen-repository defect turned out to be
+  caused by an uncommitted change, and the number would have been reported as a fact about
+  the estate.
+
+## Notes
+
+This record names no repository. The sweep that pseudonymised the estate used stable
+`repo-NN` labels because several older records use repository names as *evidence* — a table
+of how three repositories answer the same question, where "a repository and a repository"
+would destroy the argument. That argument is not present here: every repository in this
+record is identified by what it *is*, which is both publishable and more useful to a reader
+who has none of the files.
+
+`test/shipped.test.mjs` now fails on any estate name in anything this package publishes —
+the records, the changelog, the readme. It is scoped to the published set and asserts that
+scope against `package.json`, in both directions, so a directory added to `files` without
+being guarded fails rather than leaking.

package/docs/decisions/ADR-061-the-skill-registry-is-workspace-data.md

@@ -0,0 +1,113 @@
+# ADR-061 — The skill registry is workspace data, and the package ships none of it
+
+Status: **accepted** · 2026-10-12 · filed as S61
+**Affects:** `graph lint`, `skills list`, `skills show`, `skills resolve`, `skills brief`,
+`src/graph/load.mjs`, `package.json` `files`, the estate-name guard in `test/shipped.test.mjs`
+
+## Context
+
+`graph/skills.graph.json` is published. It is in `files`, so it is in the npm tarball and in
+the wheel, and `REGISTRY_PATH` finds it by resolving from `src/` — which in an installed
+package is inside the package itself:
+
+```js
+export const REGISTRY_PATH = resolve(HERE, '..', '..', 'graph', 'skills.graph.json');
+```
+
+So the registry every one of those commands reads is not the reader's. It is *this* source
+tree's catalogue of the skills that live in sibling repositories of this estate. An adopting
+repository has none of them.
+
+The estate-name guard found the symptom, and the symptom is the smaller half. Widened from
+`.md` to every text extension the package ships, it reported **51 strings in that one file**
+naming eight private repositories. The paths are the larger half and are not names at all:
+every `sources[].path` is `.agents/skills/<id>` or `.cursor/skills/<id>`, and not one of
+them resolves in a repository that is not this workspace. A reader who runs
+`simt skills list` gets skills they do not have, and `simt skills resolve` finds the
+declaration and then looks for a body that was never there. That is the corpus check this
+repository exists to enforce, failing in a file this repository publishes, on a scale the
+name grep was too narrow to see.
+
+Two more facts made the shape of the answer unambiguous rather than a judgement call:
+
+- **The sources are load-bearing, not decoration.** `graph lint` refuses a skill with none
+  ("no sources; every skill must point at the file it came from"), and the same array does
+  byte verification, variant resolution and duplicate detection. Nothing can simply be
+  deleted from it.
+- **There is already a workspace, and it is already resolved here.** `loadRegistry` calls
+  `workspace(flags)` before it validates anything, precisely so the sources can be checked
+  against a root. The registry is read from *inside the installed module* and verified
+  against *the reader's workspace* — a workspace that has nothing to do with it.
+
+So the file is not being shipped with a defect in it. It is a file that describes this
+workspace and is being shipped as though the workspace were universal, which is the one
+condition under which it makes no sense to any reader.
+
+## Rulings
+
+1. **The skill registry is workspace data.** It describes which skill bodies a particular
+   workspace contains, where they are, how big they are, and which stack tags separate the
+   variants. Every one of those is a fact about a workspace and none of them is a fact
+   about the tool.
+2. **The package ships no registry.** `graph` leaves `files`. The file stays in this
+   checkout, because this repository still has to lint and resolve its own skills, and the
+   rule that a tool must not carry its author's portfolio is about what it *publishes*.
+3. **A command reads the workspace's registry, and says so when there is none.** The
+   registry lives in a *member* of the workspace, not in the root: the root is the
+   directory that contains the member repositories, and it holds no `graph/` of its own.
+   When the reader names no path, resolution proceeds in tiers. First, the package root —
+   which is how this checkout finds its own registry; in an installed package `graph` is not
+   in the published set (ruling 2), so it never does. Next, a member of the resolved
+   workspace, when exactly one holds it: a tool installed from node_modules or a formula is
+   configured to find its workspace, and the member that holds the registry is usually the
+   tool's own checkout. More than one holding it means the reader must pick; none means the
+   command reports the workspace has no registry, naming that workspace. And where there is
+   no workspace at all: an honest absence — the command says there is no registry to read,
+   with a remedy that names the ways to point at one — which is the same shape
+   `loadRegistry` already uses for a missing file, and it does not become a new failure
+   mode. An explicitly named path always wins over all of this, and every tier is file
+   existence plus the configured workspace: there is no scoring, so the answer can be
+   explained to whoever asks.
+
+   What must not happen is the current silence: `skills list` in an adopting repository
+   answering with this estate's skills is a confident wrong answer, and a wrong answer from
+   a command whose only job is to list what is here. Nor may the remedy be a dead end: a
+   reader who follows the ways to point at a workspace must get the registry that workspace
+   holds, which is what the member tier exists for.
+4. **The guard keeps widening, and the suite stays red until the file is gone.** The
+   coverage test asserts in both directions that what is guarded is what is published, so
+   removing `graph` from `files` removes it from `SHIPPED_ROOTS` too — the two are one
+   number. Pseudonymising the names was rejected because it would have left the paths, the
+   byte counts and the variant stacks describing this workspace while hiding only the part
+   a grep can see.
+
+## Consequences
+
+- `simt skills list`, `show`, `resolve`, `brief` and `graph lint` in an adopting repository
+  report no registry rather than a foreign one. This is a behaviour change for anyone who
+  ran those commands and got this estate's skills; it was wrong, and the commands now say
+  so instead.
+- A copy of the tool installed from node_modules or a formula, pointed at a workspace that
+  holds a registry in one of its members, reads that member's registry and verifies it
+  against the workspace. This is how this estate keeps using its skills from an installed
+  copy; without it the remedy the absence message prints would be a dead end.
+- Byte verification still works here, because the file is still in this checkout. Nothing
+  about this repository's own use of the tool changes.
+- `test/shipped.test.mjs`'s `SHIPPED_ROOTS` loses `graph`, and the guard still covers
+  `bin`, `src`, `rules` and `docs/decisions`. The estate-name count in that file drops to
+  zero, which is the point.
+- The 51 strings are no longer shipped and the suite stops being red on purpose.
+
+## Rejected
+
+- **Pseudonymise the eight names to `repo-NN`.** It hides the part a grep can see and keeps
+  the part that matters: hundreds of paths that resolve nowhere for the reader, byte counts
+  of bodies they do not have, and variant stacks drawn from stacks they did not write. It
+  would also have required a second registry mapping the pseudonyms back, and that registry
+  is estate data — so it cannot be published either.
+- **Ship the registry with an empty `sources`.** `graph lint` refuses a skill with no
+  sources, so this would have meant shipping a registry that fails its own lint, or
+  shipping a second, weaker lint for adopters.
+- **Keep it, because a reader can ignore it.** The corpus check is not about whether a
+  reader is misled; it is about whether the shipped artefact is actionable by someone with
+  only the receiving repository. This one is not, for every field it has.