simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/docs/decisions/ADR-027-the-one-gitattributes-line-that-is-neither-dangerous-nor-empty.md

@@ -0,0 +1,130 @@
+# ADR-027 — the one gitattributes line that is neither dangerous nor empty
+
+Status: accepted · 2026-10-06
+**Affects:** `src/projection/baselines.mjs` (`GITATTRIBUTES_BODY`, second `BASELINES` row),
+`test/baselines.test.mjs`, `test/surfaces.test.mjs`.
+**Supersedes:** ADR-025 ruling 9, which ruled `.gitattributes` out for now and required this
+record. Settles the `.gitattributes` item in §3.1 row 5 of
+`docs/plans/0001-centralise-agent-rules.md`.
+
+## Context
+
+ADR-025 shipped `.editorconfig` and, in ruling 9, ruled `.gitattributes` out for now. The
+reason was not that the file cannot hold a region — `#` is a comment in gitattributes, so it
+qualifies mechanically. The reason was that ruling 7 had just deferred `end_of_line` on the
+grounds that line endings "are a claim about what belongs in the repository, and that claim
+is made in `.gitattributes`", and every line in a shared `.gitattributes` region changes what
+git does to the working tree. Ruling 9 concluded that such a region "is either dangerous or
+empty", and deferred it to a record of its own.
+
+The estate confirms the first half and not the conclusion. Thirteen of sixteen repositories
+have no `.gitattributes` at all. The three that do disagree about almost everything:
+`repo-05` declares only LFS filters for `.tif` and `.zip`; `repo-07` declares line
+endings plus ConnectIQ binary markers; `repo-11` declares exactly one whitespace
+suppression for hash-locked vendored content. There is no divergence here of the kind a
+baseline fixes by being consistent. There is a file missing.
+
+So the question ADR-025 deferred was the right one and it had a narrower answer than the one
+it expected. It asked whether a *shared* set of attributes exists that is safe across every
+repository. The answer is that almost none does — and that one line survives, and it happens
+to be the line ruling 7 sent this file to make.
+
+## Rulings
+
+1. **`.gitattributes` is a region, not a copy, because git takes the last matching pattern.**
+   The region goes at the top of the file and each repository's own patterns stay beneath it,
+   where they win. This is the same mechanism ADR-025 chose for `.editorconfig` and for the
+   same reason: a repository's LFS filters and binary declarations are per-repository claims,
+   and the shared region must not be able to override them. The position is enforced by a
+   test that compares line offsets, because a region that is merely present but misplaced
+   would silently invert every rule it carries.
+
+2. **The shared body is exactly one line: `* text=auto eol=lf`.** Two halves, and neither
+   is decorative.
+
+3. **`text=auto`, not `text`.** This is the half that makes the line safe, and it is why
+   ruling 9's fear did not materialise. `text` is an instruction: git normalises every path
+   it matches, and it will happily do it to a `.tif`, a `.zip` or a Garmin `.iq` image,
+   because nothing in the pattern says those are binary. `text=auto` is a detection: git
+   sniffs each path and applies normalisation only to files it concludes are text. This is
+   the most common way a repository corrupts its own binaries, and it is invisible until
+   someone diffs an image. `repo-07` had independently arrived at `text=auto eol=lf` on
+   its first line, which is the strongest available evidence that the estate would pick the
+   cautious form if asked — this ruling does not ask, it supplies.
+
+4. **`eol=lf` is the claim ADR-025 ruling 7 sent here, and here it is safe to make.** Ruling
+   7 refused `end_of_line` in `.editorconfig` because it "would change every checkout of
+   every repository on the day it landed, and a repository that wanted CRLF could only opt
+   out by deleting the region — losing the indentation baseline with it". Neither half
+   applies. In `.editorconfig` the key is a property of an editor's save behaviour; in
+   `.gitattributes` it is a property of the working tree, so a repository that wants CRLF
+   adds one line beneath the region and wins, keeping its own indentation settings. And
+   because the region is injected rather than applied, no file is rewritten at the moment it
+   lands: the next checkout normalises, and nothing before that does.
+
+5. **No other attribute is shared.** Not `filter=lfs`, not `binary`, not `-text`, not
+   `linguist-generated`, not `export-ignore`, not `diff=` or `merge=`. Each is a claim about
+   what a specific file *is*, and a wrong attribute is obeyed silently — a `filter=lfs` line
+   for a path that is not in LFS produces checkout failures in thirteen of sixteen
+   repositories, and a `binary` line for a text file produces a diff nobody can read. Ruling
+   9's "dangerous or empty" is accurate about all of them. It was wrong that the file itself
+   had no non-dangerous content.
+
+6. **A test asserts the absence of the dangerous form by name.** `text=auto eol=lf` and
+   `* text eol=lf` differ by one word, that word is the entire safety argument, and a later
+   reader who tidies the line would have no way to know. The assertion is
+   `assert.doesNotMatch(/^\* text eol=lf$/m)`, so the simplification fails as a test rather
+   than as a corrupted binary in someone's repository.
+
+7. **The property is verified against git itself, not against the string.** A test creates a
+   repository, writes the shipped region, commits a text file and a binary one, and asserts
+   through `git check-attr` that `text` resolves to `auto`, `eol` to `lf`, and that no
+   `diff` attribute is set on the binary, plus that the working tree contains no `\r\n`.
+   Reading the rendered bytes back would pass for a line git ignores, and the whole claim is
+   about what git does with it.
+
+## Consequences
+
+`.gitattributes` joins `.editorconfig` as the second baseline, and the row-table guard in
+`test/baselines.test.mjs` — every row carries a real style, a reason and a record number —
+now covers two files instead of one.
+
+Ruling 9's deferral is answered rather than repeated, and the generalisation it reached for
+does not survive contact with the estate: this was not "a shared `.gitattributes` region is
+impossible", it was "no shared region is safe except the one line that does not claim to know
+what any file is". A future baseline for a per-stack attribute would have to arrive as a
+different row with its own record, which is what §3.2's keep-it-local rule asks for anyway.
+
+The repositories with an existing `.gitattributes` are the interesting case and they are not
+in conflict: `repo-05`'s LFS filters, `repo-07`'s binary markers and
+`repo-11`'s whitespace suppression all stay beneath the region and all keep winning,
+because git takes the last match. No repository loses a line it wrote.
+
+This repository adopts neither baseline for itself, and the reason is the same one that keeps
+its `AGENTS.md` hand-written. The region's marker records the simt-dev SHA it was rendered
+from, so a copy committed here would name a commit that stops being `HEAD` the moment it
+lands — `check` would report drift on the next commit and the fix would be a sync that
+chases its own tail. `test/baselines.test.mjs` asserts this rather than leaving it to
+restraint: the failure was made once while writing this very record, which is exactly the
+condition under which a guard earns its place.
+
+## Rejected
+
+- **`* text eol=lf`, the forcing form.** Rejected by ruling 3. It is one word shorter and
+  it is the single most common way to corrupt binaries in a repository that has them, and two
+  repositories here do.
+- **A per-repository table of attributes,** driven by detection the way ADR-026's ecosystem
+  table is. Rejected because the mapping would be a guess: nothing in the tree says whether
+  a `.tif` is LFS-tracked, and `.gitattributes` has no `has-*` fact to hang a decision on.
+  Writing an attribute the repository did not ask for is worse than writing none, because
+  git obeys it without complaint.
+- **Putting `end_of_line = lf` back into `.editorconfig` as well,** on the grounds that two
+  files agreeing is more robust than one. Rejected by ruling 4: the `.editorconfig` copy
+  cannot be overridden without losing the indentation rules, so it would be the claim that
+  cannot be escaped. One place for the claim is better than one place that cannot be
+  overruled.
+- **Shipping `.gitattributes` as a whole-file copy,** on ADR-026's mechanism, since it has
+  no region in the strict sense. Rejected because the mechanism fits a file that cannot
+  merge, and this one can: there is a real region, it composes with existing content by
+  ordering, and taking the file over whole would clobber three repositories' LFS filters.
+  ADR-026's ruling 2 asks whether the grammar holds a region, and here it does.

simt_dev/vendored/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: repo-08'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
+`repo-08`, 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.

simt_dev/vendored/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 `repo-14`, 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.

simt_dev/vendored/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,**
+   `repo-04` and `repo-06`. 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 `repo-14` and `repo-11` 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.

simt_dev/vendored/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 `/home/developer/code/simt`, and the
+   install tests copied skill bodies out of it — `repo-11/.agents/skills/d1-safe-change`,
+   and `singleRepoClone()` out of `repo-14`. 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.