simt-dev 0.0.0-stage → 0.1.1

package/docs/decisions/ADR-028-a-base-file-is-a-floor-so-the-disagreement-it-cannot-repair-becomes-a-check.md

@@ -0,0 +1,131 @@
+# ADR-028 — a base file is a floor, so the disagreement it cannot repair becomes a check
+
+Status: accepted · 2026-10-07
+**Affects:** `src/tsconfig.mjs`, `src/commands/init.mjs`, `src/projection/project.mjs`,
+`test/tsconfig.test.mjs`. **Narrows:** ADR-026 ruling 2 (ownership does not depend on
+content being mergeable) by applying it to a file whose mechanism is `extends` rather than
+a copied byte range. Settles the `tsconfig.base.json` item of §3.1 row 5 and row 7 of
+`docs/plans/0001-centralise-agent-rules.md`.
+
+## Context
+
+Row 5 promised eight baselines and named two problems among them that are not about a file
+being missing: simt-goto's seven absent strictness flags, and `moduleResolution` spelled
+inconsistently across the workspace. ADR-025 ruled `tsconfig.base.json` out of the region
+mechanism because JSON has no comments, and its consequences promised that "the next fix is
+three more JSON files and therefore a different mechanism". ADR-026 supplied that mechanism
+by saying ownership does not depend on mergeability.
+
+What ADR-026 could not foresee is that this particular file inherits rather than copies,
+and inheritance has a property that changes the design from the inside: **a child overrides
+every key its parent sets.** `tsconfig.base.json` is not a shared copy of a config, it is a
+floor that a child may decline to stand on.
+
+That one fact decides the whole record, so it is worth being concrete about what it means.
+A base file can repair a repository that is *missing* a flag. It is structurally incapable
+of repairing one that spells a flag *differently*, because the child wins and the base is
+inert for that key. Both of row 5's problems are of that kind or the other: the seven
+missing flags are repairable by a base file, and the `moduleResolution` disagreement is not
+repairable by any file at all.
+
+The disagreement is also not really about disagreement. Three repositories write
+`"Bundler"` and one writes `"bundler"`; TypeScript's parser is case-insensitive, so all four
+compile and all four work. node.md:38 asks for it "spelled consistently across every repo in
+the workspace", and the only spelling that can be checked in a repository on its own is the
+one an external document uses.
+
+## Rulings
+
+1. **`tsconfig.base.json` is a whole file `init` writes once, and `check` never compares.**
+   ADR-026's ownership rule unchanged. There is no refresh path, deliberately: ADR-026 gave
+   simt-dev's own `.github` files a refresh because this repository authors the template,
+   and this repository has no more use for a current copy of a base file than it has for a
+   current copy of `.editorconfig`. A refresh path here would be a mechanism for making this
+   repository's own gate green by rewriting the file the gate is judging.
+
+2. **The floor is exactly the intersection of what the estate already wrote** — twelve
+   `compilerOptions` keys, asserted by name in a test rather than by count. It is not a set
+   of values anybody here has argued for; it is what four repositories independently wrote,
+   and the outlier repository is the one with the gap.
+
+3. **A key nobody can override safely is not in the floor.** `noEmit` is the sharp case:
+   node.md:36 wants it for any project that bundles elsewhere, inheritance makes it
+   inheritable, and a child can set `false`. It is still absent, because a base that hands
+   `noEmit` to a repository nobody looked at is a build that stops emitting, and the two
+   repositories here that bundle elsewhere did not ask for it. `target`, `lib`, `module`,
+   `include`, `exclude`, `paths`, `jsx` and `types` are absent for the same reason in the
+   other direction: `lib` is DOM+DOM.Iterable in two repositories and DOM+WebWorker in the
+   other two, and a floor that chose would silence one of them.
+4. **The test asserts those absences by name.** A future "harmless" addition that breaks a
+   repository's build must fail in this repository's suite rather than in somebody's CI.
+
+5. **`moduleResolution` is a check, not a key.** Shipping it in the floor would change
+   nothing — every repository sets it, so the child overrides the base — which is exactly
+   the definition of a line that looks configured and configures nothing.
+
+6. **A base file that nothing extends is reported as inert**, and the finding names the line
+   to add. The symptom is a strictness floor sitting in a repository looking adopted because
+   the file is right there, with a `tsc` run contradicting it. Nothing else surfaces this.
+
+7. **The file's own bytes cannot explain themselves, so `init` says the thing for it.** JSON
+   has no comments, so a shipped file with no header owes its reader nothing about who wrote
+   it or what to do next. This is the one place AGENTS.md's "every byte that leaves must be
+   readable and actionable" cannot be met inside the file, and the obligation is met by
+   `init` printing the `extends` line it requires and by ruling 6's finding.
+
+8. **`tsconfig.json` is read as JSONC, and a parse failure produces no finding.** tsc strips
+   comments before reading its own config, so a commented `tsconfig.json` is normal rather
+   than a mistake, and `JSON.parse` would throw on it. A gate that throws on a file it did
+   not write shows a reader a stack trace where the answer was one line, and `tsc` already
+   reports the malformed file better than this tool could.
+
+9. **The reader is a scanner, not a regex, for one reason:** `//` occurs inside every URL,
+   and the commonest string near a tsconfig is a URL. A regex strips the rest of the line
+   and then reports a parse error on a file that is perfectly valid. A test pins that case.
+
+10. **A repository with no TypeScript is offered nothing.** A base file in a JavaScript
+    repository is a file that claims to be an authority and is read by nothing. Detection is
+    `fingerprint`'s existing `typescript` tag, so no new fact is declared (ADR-013).
+
+11. **`simt-dev check` reports absence and the two inherited-from-nowhere problems, and never
+    the contents.** The bytes belong to the repository from the first commit, and a finding
+    that compared them would describe somebody's work as an error.
+
+## Consequences
+
+A TypeScript repository now gets twelve flags it did not have, and one of them — the floor
+arriving through `extends` — is a behaviour change that can surface real type errors in
+`simt-goto`, which is the point of the record and also the reason adoption is one commit
+with a `tsc` run rather than a silent upgrade. A base file is a floor, and a repository
+that had not been standing on one is the case where raising it finds something.
+
+`check` gains two findings that need no workspace to evaluate, which is what makes them
+usable: a repository can be checked alone, and the estate-wide agreement that
+node.md:38 asks for is expressed as agreement with an external document rather than with
+each other.
+
+What this does **not** settle: whether the two repositories that bundle elsewhere should
+declare `noEmit`. It is a fact about a build, it is not derivable from anything this tool
+reads, and neither repository asked. It stays a per-repo decision with no gate, and the
+reason is written here so the omission is not later read as an oversight.
+
+## Rejected
+
+- **`moduleResolution` in the floor, with a check as well.** Rejected by ruling 5: the key
+  would be inert in every repository in the estate, and a line in a config that no
+  repository's resolution depends on is decoration.
+- **A check that the estate agrees, by comparing across a workspace.** Rejected because
+  `check` runs in one repository, and a cross-repository finding needs a workspace, a
+  resolution order, and a rule for what happens when a repo is checked before the others
+  exist. Agreement with the documented spelling gets the same guarantee from something that
+  is already there.
+- **A `noEmit` finding for Cloudflare Workers projects,** which `fingerprint` can identify.
+  Rejected on the evidence rather than on taste: the finding would read a repository's root
+  `tsconfig.json` and conclude that the whole project never emits, which is false of any
+  repository that keeps a library in a sub-package with its own config. Two of two candidate
+  repositories in the estate would satisfy it, which is exactly the situation where a check
+  that has only ever been right looks correct.
+- **Comment-stripping by regex, including trailing commas.** Rejected by rulings 8 and 9.
+- **A region inside the JSON**, as a string key naming the real config. Rejected by
+  ADR-025's grammar argument, and doubly here: the value would be a string where TypeScript
+  expects an object, so the file would have to be rewritten by whatever read it.

package/docs/decisions/ADR-029-the-pins-a-repository-declares-are-its-own.md

@@ -0,0 +1,120 @@
+# ADR-029 — the pins a repository declares are its own, so a check reports them and never writes them
+
+Status: accepted · 2026-10-07
+**Affects:** `src/toolchain.mjs`, `src/projection/project.mjs`, `test/toolchain.test.mjs`.
+**Settles:** the `packageManager`/`engines`/`.nvmrc` items of §3.1 row 5 of
+`docs/plans/0001-centralise-agent-rules.md`. **Extends:** ADR-026 ruling 9 (absence and
+disagreement are reportable; content is not) to a file this tool authors no part of.
+
+## Context
+
+Row 5 promised to resolve "no `packageManager`" and "3 disagreeing nvmrc". Reading the
+estate before writing anything turned the second of those into a different problem, and
+the difference is the whole record.
+
+Nine node repositories commit `package-lock.json`. None declares `packageManager`. That is
+one real defect, stated by `rules/stacks/node.md` in four consecutive claims and enforced by
+nothing: one `packageManager` matching the lockfile, a floor in `engines.node`, a `.nvmrc`
+that agrees with both, and `engines` stated at all.
+
+The `.nvmrc` claim does not survive contact. Three repositories have one, and each agrees
+with its own `engines` exactly — `24.19.0` against `>=24.19`, `22.21.1` against `>=22`,
+`22.22.0` against `>=22`. What the plan called three disagreeing files are three
+*repositories* choosing different node majors, which is a per-repository decision each of
+them has a reason for. There is no defect. A check that reported it would produce a finding
+with no remedy, and a gate whose findings cannot be acted on is the failure this package
+exists to prevent — so the check does not exist, and `test/toolchain.test.mjs` asserts its
+absence out loud so a later reader does not add it back as a completeness improvement.
+
+That left one defect, and it has a property none of the shipped baselines has: **there is no
+correct value to write.** A strictness flag has one right answer. A node floor has as many as
+the team has reasons for, and `package-lock.json` carries a lockfile format number, not the
+npm version that produced it. A tool that picked one would be embedding a locally-observed
+version into every repository in the estate, which is the thing ADR-001's determinism rule
+exists to prevent.
+
+## Rulings
+
+1. **A pin is reported, never written.** `simt-dev init` writes no `packageManager`, no
+   `engines` and no `.nvmrc`. ADR-026's ruling 9 already said a check reports absence rather
+   than contents; this extends it to a file where simt-dev has no content to report *on*,
+   because the correct content is not derivable from anything in the tree.
+
+2. **The remedy is a command run where the answer exists.** `npm pkg set
+   packageManager=npm@$(npm --version)` fills in the version from the machine that has it,
+   and the tool ships no version of its own. This is the first remedy in the package that is
+   a command rather than an edit, and it is the shape the answer forces: the tool can name the
+   field and the manager, and only the reader can name the version.
+
+3. **A lockfile is the evidence that a manager was chosen.** A node repository with no
+   lockfile is not asked to declare a manager, because there is nothing to declare one
+   *about*. Every check is gated on `has-lockfile`'s evidence rather than on `package.json`
+   existing.
+
+4. **Two lockfiles are the absence of a package manager,** reported as such and never
+   resolved by picking the alphabetically-first one. That resolution would be a guess about
+   which of two committed artefacts is the mistake, and it would be wrong half the time.
+
+5. **`engines.node` absent is reported as a floor nobody enforces.** This is `node.md`'s own
+   phrasing — "a version floor nobody enforces is a comment" — promoted from a rule to a
+   gate. Four repositories in the estate declare neither `engines` nor a `.nvmrc`.
+
+6. **A `.nvmrc` the declared floor forbids is the one contradiction worth reporting**, because
+   the floor is a promise about what is supported and the pin is the instance of it, so the
+   pin is what has to move. The remedy names both values rather than choosing between them:
+   which one is wrong is a decision about intent, not about syntax.
+
+7. **A range this tool cannot evaluate produces no finding.** `lts/*`, `22.x` and anything
+   else outside a named subset reads as unknown, and an unknown is silence. The alternative is
+   an approximate reading reported with the same confidence as an exact one, and a reader who
+   cannot tell which findings were guesses stops trusting the ones that were right.
+
+8. **The subset is written down and tested as a subset:** `>=`, `>`, `<`, `<=`, `^`, `~`,
+   bare `22` and `22.1`, space-separated conjunctions and `||` disjunctions. A bare `22` means
+   every 22, as npm reads it, so a pin of `22.9.9` against a floor of `22` is satisfied —
+   reading either as one exact version would report a matching pin as a contradiction.
+
+9. **This check reads and never writes, and a test says so.** The gate that judges a
+   repository must not be able to green itself by editing what it judges. ADR-024 drew that
+   line for the `.github` files; this is the same line drawn for a check with no file of its
+   own.
+
+## Consequences
+
+Three findings go live where nine repositories will see them: `undeclared` fires in every
+node repository in the estate, `unfloored` in four, and `contradiction` in none. That is the
+intended effect — row 5 asked for these to be resolved and nothing in this package will
+resolve them, because it cannot. A repository that adopts simt-dev and runs `check` gets a
+red gate with three commands that each end in a value only the reader can supply, which is the
+honest version of "resolves this defect".
+
+The remedy strings are also the first place this package asks a reader to run a shell
+substitution, and that is worth stating plainly: a version detected on the machine running
+`check` is not the version the repository should record, so the remedy does not embed one.
+
+What this settles and what it does not: `packageManager`, `engines.node` and `.nvmrc` are now
+gated for **agreement**, not normalised. A shared value for any of them was never derivable
+and is not attempted. What remains unwritten in row 5 is commitlint — which no rule file
+mentions and no package in the estate installs — and the ESLint block, whose four
+configurations are not variants of one configuration. This paragraph named those two and
+stopped. ADR-030 answers what they are: not mechanisms awaiting code, but policy questions
+nobody has been asked, and it is the record to read next for either.
+
+## Rejected
+
+- **A shipped `.nvmrc` or an `engines` value in a shared baseline.** Rejected as
+  unrulable: the value is per-repository and the tool can only guess it. Shipping `22` would
+  break `simt-social`, which pins 24.
+- **Reporting cross-repository node divergence as a finding.** Rejected by the Context. The
+  plan's premise was wrong and the correction is recorded here so it is not re-derived from
+  the plan text.
+- **Writing `engines.node` from the `.nvmrc` already present, or the reverse.** This is the
+  one baseline case where simt-dev could derive a value from another value in the same repo,
+  and it is rejected: the two disagree in four of the estate's repositories' worth of
+  intent, and picking the winner would make one file's absence silently decide the other's
+  value. The contradiction is reported with both values and the reader resolves it.
+- **A full semver implementation,** for the reason in ruling 7. `22.x`, ranges with prerelease
+  tags, and `>=22 <23 || >=24` shaped exclusions read as unknown.
+- **Deriving the npm version from `package-lock.json`.** It is not there; the file records
+  `lockfileVersion`, a format number. Reading a version from anywhere else would make the
+  remedy depend on a file that is not evidence for it.

package/docs/decisions/ADR-030-what-a-plan-does-not-ship-is-a-decision-with-a-record.md

@@ -0,0 +1,114 @@
+# ADR-030 — what a plan does not ship is a decision with a record, not a silence
+
+Status: accepted · 2026-10-07
+**Affects:** `docs/plans/0001-centralise-agent-rules.md` §3.1 row 5 and row 7. Ships no
+code. **Refuses:** the commitlint baseline and the shared ESLint block named in row 5 and
+row 7, and records why in the plan itself rather than leaving the rows to imply that two
+mechanisms are merely unwritten.
+
+## Context
+
+Row 5 asks for eight baselines and row 7 asks `init` to scaffold them. Five have shipped:
+`.editorconfig` (ADR-025), `.gitattributes` (ADR-027), `tsconfig.base.json` (ADR-028), and
+the `packageManager`/`engines`/`.nvmrc` checks (ADR-029), alongside Dependabot (ADR-026).
+Six of the eight are now ruled on one way or another.
+
+Two are not, and the reason they are not is not the reason the first six took. Each of the
+first six hit a **mechanism** question — a region or not, a floor or a check, a value to
+write or none to derive — and each question had an answer once somebody wrote down what the
+format actually permits. The remaining two have no mechanism question to answer yet, because
+nobody has decided whether the thing should exist.
+
+That is the gap this record closes. AGENTS.md's first rule is that every byte leaving this
+repository must be actionable for a reader holding only the receiving repository, and the
+plan is a byte that leaves. A row that reads "still missing" tells the reader a mechanism is
+outstanding. For these two, what is outstanding is a policy decision, and a reader who
+trusted the row would go looking for the file to write.
+
+The two were also miscounted, which is a separate failure and the reason the plan needed
+correcting at all.
+
+## Rulings
+
+1. **A baseline that is not shipped is recorded in the row that asked for it,** with the
+   reason, so the plan never implies an unfinished mechanism where the real state is an
+   unmade decision. An honest row and a silent row differ in what the next person does, and
+   the silent one is the more expensive.
+
+2. **A convention asked for in prose is not a tool requirement.** `slice-commit.mdc:27`
+   says "Conventional Commits, imperative subject, no trailing period", and gives an example.
+   `commitlint` appears nowhere in `rules/` — zero matches across the directory, verified
+   rather than assumed. What the estate mandates is a message shape; what the plan named is a
+   linter that enforces it. Shipping the linter is a policy ruling about how strictly the
+   shape is held, and nothing in the rules says how strictly.
+
+3. **No rule file mentions commitlint, and no `package.json` in the workspace installs
+   it.** Both are `grep` claims and both are written as claims: `grep -ri commitlint rules/`
+   returns nothing, and `grep -l commitlint */package.json` returns nothing. That is the
+   whole of the evidence, deliberately — a count of how many repositories were checked would
+   be decoration, and one already in this estate disagrees with itself about what it counts.
+   So there is no existing disagreement to repair, no config to inherit, and no repo
+   currently failing a gate over it. Row 5's other items each had at least one of those.
+
+4. **`eslint-config-prettier` is installed in exactly one of the four configurations,** and
+   the fight is in exactly the two that use `stylisticTypeChecked` without it. The plan said
+   "3 of 5 configs"; the estate has four configs and two conflicts, in one shape that is
+   detectable by reading the file. Corrected in the row.
+
+5. **Two of the four configurations are plain JavaScript with no TypeScript in them,**
+   `simt-api` and `simt-blog`. A "shared 6-rule ESLint block" cannot describe all four,
+   because two of them have no rules to share — they differ in `ignores` and per-file
+   `globals`, which are per-repository facts about paths.
+
+6. **Flat config has no cross-repository include.** Bringing a shared block into a repo
+   requires either publishing it as an npm package or editing the repo's own
+   `eslint.config.mjs` to import and spread a local file. This package is a CLI with zero
+   runtime dependencies (ADR-012); becoming a registry is not a mechanism decision this row
+   may make on its own.
+
+7. **The fix for the two conflicts is one dependency each,** and it is not a shared block.
+   Installing `eslint-config-prettier` in `simt-social` and `simt-social-api` and spreading
+   it last in the config array resolves both. That is a command per repository, run by the
+   repositories, and simt-dev has no business writing it.
+
+8. **The `.nvmrc` claim in row 5 was wrong and is corrected there.** Three repositories
+   disagree, and each one's `.nvmrc` agrees exactly with its own `engines.node`. What differs
+   is three legitimate per-repository choices. ADR-029 rules the cross-repository check out
+   and asserts the silence in a test.
+
+## Consequences
+
+Row 5 ships five of its eight items, and now says so in a way that separates the two kinds
+of remainder. Row 7 stops reading as though commitlint and the ESLint block are waiting on
+code.
+
+Neither refusal forecloses the decision. Both are one record away from being built, and this
+record is what a later one would read first: it says what the mechanism would have to be
+(ruling 6), what the state of the estate is (rulings 3 and 4), and what the cheapest correct
+fix is today (ruling 7). Nothing here needs to be undone to start them.
+
+The estate consequence of this record is one line changed in a plan and one rule about what
+a plan row owes its reader. That is a smaller change than the five baselines that preceded
+it, and it is the change that makes the other five legible: a reader of row 5 can now tell
+the difference between what was built, what was ruled out, and what nobody has decided.
+
+## Rejected
+
+- **Shipping a `.commitlintrc.json` anyway,** on the grounds that the mechanism is settled
+  and only the file is missing. Rejected by ruling 2: the file is a decision about
+  enforcement strength, and writing it would answer that question by accident. A rule that
+  says "no trailing period" and a commitlint config that rejects one are not the same
+  commitment, and only one of them has been asked for.
+- **A `commitlint` check** reporting a malformed subject, as a lighter alternative. Rejected
+  for the same reason as the rest of ADR-029: a check for a convention nobody has adopted
+  turns silence into a failure, and this is a plan item rather than a rule requirement.
+- **A shared ESLint block as a local file each repo imports.** Rejected by ruling 6 for the
+  published case, and for the local case because a file only two of four configs could use
+  is not the shared block row 5 describes.
+- **Deleting the `stylisticTypeChecked` entry from the two configs.** This would resolve the
+  conflict, and it is rejected as simt-dev's business: it is an edit to a rule set a team
+  chose, in a repository that has not asked, and its loss is that the stylistic rules were
+  there for a reason nobody has written down.
+- **Rewriting row 5 to drop the two items,** on the grounds that the plan should only list
+  what will be done. Rejected by ruling 1. A plan that quietly forgets is not honest; it is
+  just a document nobody can audit.

package/docs/decisions/ADR-031-the-suite-stages-the-environment-it-needs.md

@@ -0,0 +1,129 @@
+# ADR-031 — the suite stages the environment it needs, because a test that inherits the author's directory is not evidence
+
+Status: accepted · 2026-10-08
+**Affects:** `test/fixture.mjs`, `test/install.test.mjs`, `test/hooks.test.mjs`,
+`test/upgrade.test.mjs`, `test/workspace.test.mjs`. **Extends:** ADR-003 (test breadth)
+and the AGENTS.md rule that the tool must be run the way a consumer runs it. **Relates to:**
+ADR-015 (a source is content, not a location) — this is the same claim applied to the tests
+that consume a source.
+
+## Context
+
+`simt-dev own gate` had been red on every push to `main` since the first baseline commit
+landed. Not intermittently: 22 of 543 tests failed on runs `37476671363` through
+`37642437221`, and the same 22 failed on all four. Locally the suite was 542/543 green.
+
+Three separate causes, none of them recent:
+
+1. **`test/install.test.mjs:17` read the estate off the author's disk.**
+   `const WORKSPACE = resolve(HERE, '..', '..')` is `/Users/said.elimam/code/simt`, and the
+   install tests copied skill bodies out of it — `simt-social-api/.agents/skills/d1-safe-change`,
+   and `singleRepoClone()` out of `simt-social`. On a runner the checkout is
+   `/home/runner/work/simt-dev/simt-dev`, so `../..` is `/home/runner/work/simt-dev`,
+   which contains this repository and nothing else. The bodies were not there,
+   `skills install` exited 3, and nineteen tests asserted on a refusal they never asked for.
+   This is the third time this repository has made this mistake. AGENTS.md already names the
+   first two: "workspace resolution that only worked in the checkout, and content lookup that
+   only worked with a workspace." The rule was written down and the suite broke it anyway,
+   which is worth recording plainly — a written rule does not prevent the failure, only a
+   fixture that cannot express it.
+
+2. **Three `git commit` calls carried no identity.** `hooks.test.mjs:502` and `:587` and
+   `upgrade.test.mjs:310` ran bare `git commit`, which dies with `Author identity unknown`
+   on any machine without a configured identity. Two other files in the same suite
+   (`compare.test.mjs:57`, `init.test.mjs:177`) passed `-c user.email=…`. The suite was
+   half right in a way that only shows up on a runner.
+
+3. **Two tests asserted the checkout's own directory name.**
+   `PACKAGE_ROOT is the package directory, not its parent` asserted
+   `PACKAGE_ROOT.endsWith('/simt-dev')`, and `CLI: doctor reports which source answered`
+   asserted the label `(heuristic: sibling of this package)`. Both pass when the directory is
+   called `simt-dev` and fail when it is called anything else, which is a fact about the
+   folder rather than about the code. Neither failed in CI, because CI's directory *is*
+   called `simt-dev`. They were found only by running the suite from a copy named `repo`.
+
+Causes 1 and 2 explain all 22 failures. Cause 3 explains none of them and is the most
+instructive, because it is a test that passes for the wrong reason.
+
+## Rulings
+
+1. **The suite builds its own environment; it never reads the author's.** A test that
+   resolves a body, a workspace, or a git identity from anything outside the checkout is
+   defective even when it passes. `test/fixture.mjs` is the single place that constructs
+   them, so the assumption is stated once instead of being re-derived in each file.
+
+2. **Bodies are generated from the registry, not copied from a sibling.** A declared source
+   is a *size* and a *location*; `locateSource` compares `measureSkill(path).bytes` against
+   the declared number and nothing else. So `skillWorkspace()` walks
+   `graph/skills.graph.json`, and writes a body of exactly the declared length for every
+   one of the 45 declared sources. Two consequences follow and both are deliberate: a source
+   added to the registry is staged without a second edit, and a declared size that changes
+   cannot leave the fixture staging the old one. Copying real bodies instead would have
+   reintroduced the dependency this record exists to remove, and would have made the suite
+   fail whenever an unrelated repository edited a skill.
+
+3. **Byte-exactness is a contract, not a detail.** A body one byte short is refused with
+   `exists but is not the declared body`, so a fixture that pads approximately turns the
+   tests green into tests that assert a refusal. Verified: removing one byte from the padding
+   fails 19 of the 31 install tests.
+
+4. **Only the stack signals that select something are staged.** The two repos whose names
+   appear in a variant-bearing skill's `sources` carry the dependencies and the
+   `vite.config.ts` that make `fingerprint` emit `react` + `node-web` against `hono` —
+   `node-web` comes from a config file, not from `package.json`, so a fixture that only
+   writes dependencies silently fails to select the `web` variant. Repos the registry names
+   for single-body sources are staged neutral, because nothing is ever chosen by signal from
+   them. Inventing stacks for them would be decoration, and would risk
+   `every variant-bearing skill resolves to exactly one variant per real repo` passing for a
+   reason nobody can reconstruct.
+
+5. **`git` is invoked through one helper that always carries an identity**, on the command
+   line rather than in a config file, so the suite can neither read nor write the developer's
+   git configuration. `commit.gpgsign=false` for the same reason: a developer with signing
+   configured must not be the only person whose tests pass.
+
+6. **A test that asserts a location-derived fact asserts the location.** Ruling 1 makes the
+   checkout's path and name unavailable as evidence. `PACKAGE_ROOT` is now checked
+   structurally — the package's own `package.json` and `bin/simt-dev.mjs` are inside it, and
+   they are not one level up. `doctor reports which source answered` no longer asserts
+   *which* source; it empties the config and disables the workspace so the answer is the
+   same on every machine. The sibling heuristic keeps its own coverage where it belongs, in
+   the `resolveWorkspace` unit tests.
+
+## Consequences
+
+The suite now passes from any checkout: verified at an arbitrary path under a directory named
+`fork-of-simt-dev`, with no sibling repositories present, 542/542. It passed there before this
+record only if the directory happened to be named `simt-dev`.
+
+The fixture stages bytes that satisfy the registry, not a copy of anybody's documentation.
+Ten of the estate's skills ship a `references/` directory that `skillWorkspace()` does not
+reproduce, because `measureSkill` sums the directory and a single padded `SKILL.md` satisfies
+every check except the one test that asserts a reference file arrives — and that split is
+declared for the one skill whose test needs it. If a future test asserts a layout, the split
+goes in `FILE_SPLITS` rather than the fixture growing a copy of the estate.
+
+The cost is that `test/install.test.mjs` no longer proves anything about the *real*
+`d1-safe-change`. It proved it never: what it verified was that a body of the declared size is
+copied verbatim, and the declared size came from the registry either way. What it did prove,
+accidentally, was that this checkout's siblings are intact — which is not a property of the
+tool.
+
+## Rejected
+
+- **Cloning the estate into CI so the existing tests pass.** Fastest, and it leaves the
+  defect exactly where it is. The suite would still be unable to detect that the tool only
+  works with a workspace, which is the failure AGENTS.md says has already happened twice.
+- **Pointing the install tests at this repository's own skill bytes.** Would make the tests
+  pass, but `skills install` exists to move a body *between* repositories, so a test whose
+  source and destination are the same repository is not exercising the command.
+- **Committing the real bodies as fixture files under `test/`.** Deterministic, and it would
+  have avoided the padding code entirely. Rejected: it copies other repositories' work into
+  this one and creates a second thing to update whenever a body changes, which is a
+  synchronisation problem rather than a test.
+- **Setting a global `SIMT_DEV_WORKSPACE` for the whole suite.** Ruling 1 makes each test
+  name the environment it needs; a default would let a test inherit a workspace without
+  having asked for one, which is the same class of defect one level up.
+- **Fixing only the 22 CI failures.** Causes 1 and 2 are all the runner can see. Cause 3 was
+  found by running the suite from a directory with a different name, and would have stayed
+  invisible to anyone who only ever ran it in place.

package/docs/decisions/ADR-032-provenance-is-a-content-digest-not-a-commit.md

@@ -0,0 +1,141 @@
+# ADR-032 — provenance is a digest of the content that leaves this package, not a commit id
+
+Status: accepted · 2026-10-08 · ruling 1 narrowed by ADR-054
+**Affects:** `src/projection/rules.mjs`, `src/projection/markers.mjs`, `test/upgrade.test.mjs`,
+`test/install.test.mjs`, `test/project.test.mjs`. **Implements:** proposal P1 in
+`docs/reviews/0002-full-review-adoption-and-public-release.md` §10. **Relates to:**
+ADR-031 (a test that inherits the author's directory is not evidence) — the same defect found
+one layer down, in the tool rather than the suite — and ADR-015 (a source is content, not a
+location), which already argued that a declared skill's identity is its bytes.
+
+## Context
+
+Two tests in `test/upgrade.test.mjs` failed in any copy of this repository that had no `.git`:
+a `git archive` export, a tarball, and — the case that matters — the published npm package.
+
+The proximate cause was `headSha()`, which ran `git rev-parse --short=7 HEAD` in the package
+root and returned the string `unknown` when git could not answer. That fallback was only the
+second of two ways the stamp was wrong, and the quieter one.
+
+**The first way: the stamp recorded the reader's own repository.** `git rev-parse` run inside
+`node_modules/` walks *up* until it finds a `.git`, so for anyone who installed this package
+into a repository — the entire audience for it — the tool stamped the consumer's HEAD. Not a
+near miss: the correct-looking answer to the wrong question. A consumer's HEAD changes on
+every commit they make, including commits that touch nothing this tool projects, so:
+
+- the stamp changed under a region that had not changed, and `check` reported `DRIFT` on all
+  three generated files plus `STALE-GENERATED-FIELD` on the manifest — **after an unrelated
+  commit**, and **exit 1**. A gate that is red on every commit trains people to ignore it,
+  which is the failure mode this tool exists to prevent;
+- `upgrade` reported `state behind`, `pin f9036cd -> f3014d5`, and the cause it named —
+  *"pin moved and region restamped (the rules changed)"* — was false. A pin that moves because
+  the consumer typed a commit message has not detected anything about the rules;
+- no fallback could ever have caught this, because git succeeded and returned a plausible sha.
+
+Review 0002 recorded this as probe #2 and slice S01 and it was correctly read there as
+"provenance stamp comes from the consumer's git, not simt-dev". It reproduced exactly.
+
+**The second way: where git could not answer, `unknown` was treated as a value.** The old
+comment defended the fallback — "a region stamped with an honest `unknown` is visibly
+unverified while one stamped with a wrong answer is not" — and the defence is sound in
+isolation. It is defeated by the fact that `unknown` was then compared and written like any
+other string:
+
+- `files` in `package.json` does not list `.git`, and npm never packs one. **`npm pack`
+  produces 98 entries and no `.git`**, so a tarball or a copy extracted outside a repository
+  got `unknown`.
+- The marker grammar reads `simt-dev:sha=([0-9a-f]{7,40})`. `unknown` does not match, so
+  `parse()` returned `sha: undefined` for a region the tool had just written. **The tool could
+  not read back its own stamp**, and `check` reported `recordedSha: null` for a file that
+  plainly carried one.
+- `planUpgrade` computed `pinBehind = base.pinnedSha !== sha`. With `sha === 'unknown'` this
+  is true for every real pin, so `upgrade` called a repo pinned at `2614462` `behind`, again
+  naming the false cause above. `upgrade --yes` then wrote `unknown` into both the region's
+  stamp and the manifest pin, and the original pin was unrecoverable.
+
+So the identity was never the identity of this tool. It was either the reader's repository or
+a sentinel the tool could not parse — and the review's probe found the first while the test
+suite, written by someone reading a checkout, could not see it.
+
+## Ruling
+
+**Provenance is a SHA-256 digest of the content that leaves this package, truncated to 40 hex
+characters. It is not a commit id, and there is no fallback.** (Which content, precisely, was
+narrowed after this record was written — see ADR-054.)
+
+Three consequences, each of which is the point:
+
+1. **The identity exists wherever the content does, and depends on nothing outside the
+   package.** `rules/` and `graph/` are in the published tarball, so the digest is computable
+   from a checkout, a tarball and an `npm install` alike — one value, no environment to be in.
+   This also ends the walk-up: with no `git` invoked at all, there is no ancestor repository
+   for the stamp to be borrowed from, so a consumer's own commits can no longer move a pin.
+   Verified by the review's own probe, against a package installed inside a repo that then
+   commits an unrelated file: before, `check` reported `DRIFT` on three files plus
+   `STALE-GENERATED-FIELD` and exited 1; after, three `CURRENT` lines and exit 0.
+2. **A stamp the tool cannot read is a defect, not a degraded mode.** `compose()` now throws
+   unless `sha` matches `[0-9a-f]{7,40}`. The write and the read share one grammar by
+   construction, so the failure this record describes cannot be reintroduced by adding a
+   fallback.
+3. **`unknown` is gone, not guarded.** There is no sentinel to compare against, so the
+   comparison that destroyed the pin has nothing to misread. A repo stamped by a version of
+   simt-dev older than this record still carries `unknown`, or a consumer commit's sha, and
+   `upgrade` now repairs it to the digest — the same path as any other stale pin.
+
+### What the digest covers, and what it deliberately excludes
+
+> **Superseded by ADR-054.** The exclusion below is drawn around a *directory*, and the
+> shared `.editorconfig` and `.gitattributes` bodies are not in one — they are constants in
+> `src/`, and they are content every adopting repository receives. `src/` as a path is still
+> excluded; the exclusion is now a rule about content rather than about a location.
+
+`rules/` and `graph/` are the bytes whose change moves a consumer's projection: the shared
+rules, the per-ecosystem profiles, the Cursor rule files, and the skill registry. `src/` is
+excluded deliberately. A refactor that changes no rule and no registry entry produces
+byte-identical regions; stamping those consumers would report drift where there is none, and
+the estate's own rule is that a report must be a fact.
+
+This is the same reasoning as ADR-015: a skill is identified by its bytes, so a projection is
+identified by the bytes it projects.
+
+Entries are hashed in sorted path order, each framed as `path:length:` before its bytes. The
+ordering makes the value independent of `readdir` order — determinism is a feature of this
+tool, not a limitation. The framing means two different renames cannot collide into one
+digest, which is why this is not a hash of concatenated text.
+
+## Consequences
+
+- **Every adopted repo's stamp moves once.** A consumer stamped at a commit sha will report
+  `behind` the first time it runs this version, and `simt-dev upgrade` fixes it. That is the
+  intended reading of a pin, not a regression.
+- **The two `.git`-less test failures are fixed at the source for one of them.** The stale
+  `.mdc` test failed only because it could not find a sha to rewind; it now passes. The other
+  (`upgrade --root` at the package root) is a *test* defect and is fixed as one — see below.
+- **`test/upgrade.test.mjs` no longer asserts a property of the author's checkout.** It had
+  asserted `summary.repos === 1`, which is only reachable when this checkout happens to be a
+  git repo. A `.git`-less package root is a directory holding no repositories, which
+  `discover` correctly refuses with exit 3 and a remedy. Both answers are right, so the
+  invariant is now stated directly: simt-dev is not a consumer of itself, so no
+  `simt-dev.json` appears. Both halves are non-vacuous — planting a manifest fails the first,
+  and forcing the no-manifest case to write one fails the second.
+- **S01 is discharged.** Its proposal is P1; this record implements it, so the slice can move
+  to Complete against this SHA rather than waiting on a second implementation of the same idea.
+
+## Rejected
+
+- **Guard the sentinel instead of removing it.** Treat `unknown` as non-comparable: refuse to
+  move a pin to or from it, and say so. Smaller diff, and it leaves the tool writing a stamp
+  its own parser rejects for every npm consumer. It fixes the data loss and not the lie, and
+  it does nothing at all about the walk-up, which was never a sentinel — git succeeded.
+- **Resolve the repository explicitly** — pass `--git-dir`, or run `git rev-parse` with
+  `GIT_CEILING_DIRECTORIES`, so the stamp names this package and never an ancestor. This is
+  the smallest change that fixes the walk-up, and it is still wrong: in a tarball there is no
+  repository to name, so it restores the `unknown` fallback and with it the pin destruction.
+  It also keeps the identity meaning "which commit of simt-dev", which is a fact about a
+  history a consumer does not have and cannot verify. The ruling is that the stamp answers
+  *what content produced these bytes*, not *which commit was checked out at the time*.
+- **Stamp the package version.** `version` is present in the tarball. But it is `0.0.0` here
+  and rises only at release, so it cannot distinguish two working trees that project
+  differently — which is the case `check` and `upgrade` exist for.
+- **Hash the whole package.** Includes `src/`, with the consequence above, and hashes files
+  the consumer never receives.