simt-dev 0.0.0-stage → 0.1.0

package/docs/decisions/ADR-049-a-ruling-that-a-later-record-moved-says-so-where-it-is-printed.md

@@ -0,0 +1,153 @@
+# ADR-049 — a ruling that a later record moved says so where it is printed
+
+Status: accepted · 2026-10-09
+**Affects:** `src/decisions/index.mjs`, `src/commands/rules.mjs`, `src/mcp/tools.mjs`,
+`test/rules.test.mjs`. Closes S31 of
+`docs/reviews/0002-full-review-adoption-and-public-release.md`.
+
+## Context
+
+Review 0002 §5 filed S31 with a measurement: `rules why ADR-023` printed the status
+`accepted · 2026-10-06 · ruling 2 superseded by` and then printed ruling 2 — *"It is written
+once and never rewritten"* — as a ruling in force. ADR-024 had superseded exactly that
+ruling. The module header names this as its own failure mode: *"the failure mode of a
+provenance feature that only proves provenance, not currency."*
+
+Two more defects were in the same reader and neither was in the finding.
+
+**The status is a paragraph, and it was read as a line.** `loadDecisions` matched
+`/^Status:\s*(.*)$/m`, which stops at the newline. Four of forty-eight records wrap their
+status over more than one line, and the one that matters is ADR-023: its second and third
+lines are the whole claim — which record superseded ruling 2, and that rulings 3 and 4 were
+narrowed by the same record. The parser saw `ruling 2 superseded by` and stopped, which is
+a sentence with no object.
+
+**A partial supersession could not become a whole one, and the obvious fix makes it do
+exactly that.** `supersededBy` was `/superseded by \[ADR-(\d{3})\]/i` over the status.
+Once the status is the whole paragraph, that pattern matches ADR-023's *"ruling 2
+superseded by [ADR-024](…)"* — and `supersededBy` is the field that makes `rules why`
+answer a record by printing its replacement's rulings and suppressing its own. Five
+rulings in ADR-023 that the status line itself says stand would have been dropped, by the
+field that exists to stop precisely that. Anchoring the match to the start of the status is
+not a detail of the fix; it is the fix.
+
+**Rulings are numbered five different ways and one of them was read.** This is the finding
+that made S31's stated fix impossible as written, and it was not visible until the ruling
+text was measured rather than the status line:
+
+| Family | Records | Example |
+| --- | --- | --- |
+| `1. **bold**` | 17 | ADR-021 |
+| `**1. prose**` | 8 | ADR-034–040 |
+| `**One.**` | 7 | ADR-041–047 |
+| `### 1. Title` | 4 | ADR-013–016 |
+| a bare bullet list | 1 | ADR-009 |
+| unnumbered paragraphs | 11 | ADR-001–012 |
+
+Only the first was recognised. The consequences are not stylistic. ADR-045 declares six
+`**One.**` rulings and printed **one** merged blob of them. ADR-013 printed the literal
+string `### 2.` to an agent as though the record had ruled with it. ADR-015 lists four
+resolution strategies inside `### 2.`, and the first version of the fix read three of them
+as rulings numbered 1, 2 and 3. And a supersession says *"ruling 3"*: a number that cannot
+be located cannot be reported as no longer in force, so annotating a ruling depends on
+knowing what one is.
+
+**`accepted` was one record's spelling, not the document's.** The check was
+`status.includes('**accepted**')`. ADR-001 to ADR-020 write `**accepted**`; ADR-021 onwards
+write `accepted`. Fourteen accepted records read as not accepted. This is S19's finding and
+S31 names the fix; it is the sixth instance in this repository of a check that reads the
+author's habits rather than the artefact.
+
+**A section ended at a heading inside a code block.** `section()` ended a section at the
+next `^## `, and ADR-007's ruling is a document skeleton in a fence whose headings are
+`##`. The record kept only the lead-in — which was still longer than the minimum length,
+so the test asking whether every record yields a ruling passed on a fragment.
+
+## Rulings
+
+1. **`Status:` is a paragraph.** It is read to the first blank line or the first sibling
+   field, whichever comes first, and flattened. A sibling field is a capitalised label and
+   a colon, optionally in emphasis: `Affects:` and `**Affects:**` both end it, and no
+   continuation line in the corpus does. Getting the boundary wrong is not cosmetic in
+   either direction — stopping early truncates the sentence that says what was overturned,
+   and reading on swallows `Affects:`, whose value is a list of paths in a file read inside
+   repositories that own none of them.
+
+2. **Every field is read off the flattened, markdown-free status.** The link form and the
+   bare form are then one spelling, so a record that writes `ADR-046` and one that writes
+   `[ADR-046](…)` are read by the same line rather than by two patterns kept in step.
+
+3. **A record is superseded only when its own status says so first.** `supersededBy` is
+   anchored to the start of the status. See the Context: the unanchored form turns a
+   partial supersession into a total one.
+
+4. **`accepted` is read from the status.** `/^accepted\b/i` on the flattened paragraph, so
+   the record's own wording is what counts and no record's habits are.
+
+5. **A partial supersession is data, not a sentence to be parsed out of prose at print
+   time.** `partial: [{ruling, kind, by}]`, one entry per ruling a later record moved, in
+   three kinds the corpus uses — `superseded`, `narrowed`, `withdrawn`. A ruling a later
+   record names is printed with the fact attached, in place: *(superseded by ADR-024)*.
+   `ruling: null` is a record that says "one ruling" without saying which — a fact about the
+   record, carried rather than guessed at — and `by: null` is "the same record" in a status
+   that has not named one. Neither is resolvable, and neither is silently dropped.
+
+6. **"The same record" resolves to the last record this status named.** ADR-023 uses it for
+   rulings 3 and 4 immediately after naming ADR-024 for ruling 2. Resolving it to nothing
+   would drop two of the three supersessions on the one record this slice is about.
+
+7. **A ruling's identity is its number, and a section has one family.** The family is read
+   off the first line that looks like any of the six, and that family alone opens a ruling
+   for the whole section. One family per section is what keeps a list *inside* a ruling
+   inside it, which is ADR-015's four resolution strategies and ADR-013's four bullets.
+   A blank line does not close a ruling, because a record's parenthetical about its own
+   rulings sits between them. The heading marker and the bullet are structure and do not
+   survive into the text.
+
+8. **A section ends at the next heading, but not at one inside a fenced block.** The fence
+   marker is structure; its contents are not, and ADR-007's ruling is entirely inside one.
+
+9. **`summary.rulingNumbers` is exported.** It is the join between a supersession and the
+   ruling it moves, and nothing else observes it. The `**One.**` ordinal was dropped in
+   testing — one line of code — and **every test passed**, because no record in the estate
+   has both a word-numbered ruling and a partial supersession. That is ADR-042's failure
+   (a declared value nobody executes) inside a fix whose subject is a declared value
+   nobody executes, and the field is exported so the next such mutation has something to
+   fail against.
+
+## Consequences
+
+- `rules why` prints a `partial` line naming every ruling the record lost, because two
+  rulings are printed and a record may have six: ADR-021's overturned ruling is the third,
+  so the annotation cannot reach it and the status line is all that is left. The same fact
+  appears twice by design — once as a line, once on the ruling — because the two print
+  different sets, and one copy could not cover both.
+- The JSON payload gains `partial` and `summary.rulingNumbers`, and `rules_why` over MCP
+  carries `partial`. Both are additive; `ruled` stays a list of strings, because three
+  surfaces read it and the annotation is attached to the text rather than beside it.
+- `supersedes` no longer reports ADR-046 as superseding ADR-021. It supersedes *ruling 3*
+  of ADR-021, which is `partial` on the other record. A whole-record supersession is the
+  rarer case and the one that has always been reported.
+- `accepted` is now true for fourteen records that were false. Nothing in this repository
+  reads the field outside `rules why --json`, where a caller asking "is this in force?" was
+  being told no about records that are.
+
+## Rejected
+
+- **Model the backward direction too — `supersedes ADR-021 ruling 3`,
+  `amends ADR-017 ruling 1`, `refines ADR-013 ruling 1`.** Rejected under ADR-002, with
+  the evidence attached: the same edge appears in both records, the passive side is the one
+  that must not print a ruling as in force, and parsing only the passive side is what makes
+  the anchoring in ruling 3 cheap. The active side is a reader convenience, not a safety
+  property, and it would need the `Affects:` paragraph as well as the status because
+  ADR-024, ADR-026, ADR-027 and ADR-028 all state it there.
+- **Rewrite the forty-eight records to one spelling.** Rejected: the parser reading five
+  shapes is one function; reformatting every record is forty-eight edits to evidence, and
+  the `**accepted**` half of the problem was a one-line fix in the reader.
+- **Number the rulings in ADR-016 so `ruling: null` disappears.** Rejected: ADR-045 says
+  what it narrows, and ADR-016's narrowing targets a bullet in its `Consequences` section
+  rather than one of its six numbered rulings. There is no number to write.
+- **Print every ruling rather than two.** Rejected under ADR-002: it changes the output size
+  of every `rules why` in every repository, and no measured defect needs it. A ruling past
+  the excerpt cannot mislead a reader who is not shown it; the `partial` line is what makes
+  it knowable.

package/docs/decisions/ADR-050-a-byte-count-is-not-a-region-and-updated-is-not-a-change-of-rules.md

@@ -0,0 +1,102 @@
+# ADR-050 — a byte count is not a region, and `updated` is not a change of rules
+
+Status: accepted · 2026-10-09
+**Affects:** `src/upgrade/plan.mjs`, `src/projection/markers.mjs`,
+`src/projection/project.mjs`, `src/projection/targets.mjs`, `src/projection/baselines.mjs`,
+`test/upgrade.test.mjs`, `test/markers.test.mjs`. Closes S26 of
+`docs/reviews/0002-full-review-adoption-and-public-release.md`.
+
+## Context
+
+S26's finding was one line of code: the no-region guard in `upgrade` was
+`list.every((t) => t.action === 'added' && !t.previousBytes)`, and a repository whose
+`AGENTS.md` is hand-written prose has `previousBytes > 0`. Reproduced on a repository built
+the way the estate builds one — `init`, then `AGENTS.md` replaced by hand — and `upgrade`
+wrote a 9 KB region into a repository that had never had one, reporting
+*"pin moved and region restamped (the rules changed)"*. No rule had changed; no region had
+existed.
+
+Two further defects were in the same command, and neither was in the finding.
+
+**The guard as written was not the fix it looked like.** Replacing `previousBytes` with
+"is every region absent" reproduces the same defect, because the estate's version of this
+state leaves the **baselines'** regions in place: `.editorconfig` and `.gitattributes` were
+written by the same `init` and are untouched by the hand-written `AGENTS.md`. A guard
+asking about every target sees two regions, concludes the repository is adopted, and writes
+one. The guard has to ask about the **primary** target, which is the rule `compare` already
+applies — its `region` field is the primary document's, and its problem line for this state
+is *"adopted but AGENTS.md has no generated region"*. Two commands answering "is this
+repository adopted?" differently is the defect S26 and the reason it was easy to write.
+
+**`updated` means two things, and this command reads it to explain itself.** ADR-037 made a
+correct region body behind a wrong seam report as `updated`, so `sync` would repair it. That
+was right, and it gave `action` a second meaning: the body moved, *or* the bytes around it
+did. `upgrade`'s whole purpose is to say why a repository is behind, so with
+`action !== 'unchanged'` as the evidence it reports a formatting repair as a change of
+policy — and sends the reader to diff rules that did not move. Measured, with the pin
+already current in all three:
+
+| State | Reported |
+| --- | --- |
+| body edited by hand | `the rules changed` — correct |
+| seam wrong, body correct | `the rules changed` — **false** |
+| stamp moved, body identical | `the rules were already correct` — right, but only by accident of ordering |
+
+The third row is the second half of the trap. Comparing a whole target — bytes, header and
+all — makes **every** pin bump claim the rules changed, because the region header carries
+the stamp by design.
+
+## Rulings
+
+1. **A region is present or absent; a file is not "small".** `inject` and `diff` return
+   `region` (`absent` | `ok` | `malformed`) and `previousBody` alongside `action`, and every
+   target carries both. `parse` has always known this; `action` cannot express it and
+   `previousBytes` cannot answer it.
+
+2. **Adoption is a question about the primary document.** `upgrade` skips when
+   `AGENTS.md` has no region, whatever the baselines hold. This is `compare`'s rule and
+   `ADR-016`'s rule about display versus gate, applied to a command that was about to write.
+
+3. **The remedy is `simt-dev sync --yes`,** because `sync` does the thing the skip refused
+   to do and nothing else. S26 proposed `simt-dev init`; rejected — `init` re-runs
+   adoption, tags and branches, and the remedy would be doing more than the command it is
+   the remedy for. `compare` already names `sync --yes` here, and two commands must not
+   answer the same question with different instructions.
+
+4. **"The rules changed" is answered by comparing region bodies,** not by reading `action`
+   and not by comparing targets. A target is a change to the rules when its previous body
+   and the body this simt-dev would write differ, ignoring the leading and trailing
+   newlines the region may pick up from the document — the same normalisation `inject`
+   uses to decide `unchanged`.
+
+5. **A repair is named as a repair.** `region repaired; the pin and the rules were already
+   current` distinguishes a seam fix from a change of policy, because the reader's next
+   action differs: one is a formatting commit, the other is a review of what the rules now
+   say.
+
+## Consequences
+
+- `upgrade` exits non-zero on a region-less repository, and `check` already did. They now
+  agree, and the test asserts the exit code rather than tolerating it: a command that names
+  the problem and exits 0 is the ADR-023 failure, and this command was about to start doing
+  it in a new place.
+- Six mutations were applied and reverted, each caught by its own test. Two of them are
+  the finding and its tempting half-measure: falling back to `previousBytes`, and guarding
+  on every target instead of the primary one. Both pass the whole suite if the fixture is a
+  repository whose `AGENTS.md` is *absent* rather than hand-written — which is why the
+  fixture builds the estate's shape instead.
+- `inject`'s and `diff`'s return shape grows two fields. Both are derived from a `parse`
+  that already ran, and no caller reconstructs them.
+
+## Rejected
+
+- **Repairing the region in `upgrade` rather than skipping.** Rejected: `upgrade` moves a
+  pin. Adoption, and the repair of a repository that lost its region, are `init` and `sync`.
+  A command that silently performs them during a version bump is a command nobody can
+  predict — this module's own header says so.
+- **Comparing `previousBody` to `body` including the header,** which would make the stamp a
+  rule change on every pin bump. Rejected: ruling 4's normalisation, and the reason the
+  comparison is body-to-body rather than target-to-target.
+- **Making `region` a field on the plan rather than the target.** Rejected under ADR-002:
+  the target is what every caller already receives, and a second place computing the same
+  fact is how `compare`'s `profiles` ended up declared and never assigned (ADR-045).

package/docs/decisions/ADR-051-a-pointer-is-the-readers-only-route-so-it-is-not-a-convenience.md

@@ -0,0 +1,134 @@
+# ADR-051 — a pointer is the reader's only route, so it is not a convenience
+
+Status: accepted · 2026-10-09
+**Affects:** `src/projection/project.mjs`, `src/projection/targets.mjs`,
+`src/commands/sync.mjs`, `test/surfaces.test.mjs`. Closes S09 of
+`docs/reviews/0002-full-review-adoption-and-public-release.md`.
+
+## Context
+
+`pointer-drift` was in `NON_BLOCKING`, with a comment saying a misaimed `CLAUDE.md` is *"a
+smaller problem than a red gate on every commit: the editors that matter already read
+AGENTS.md, and the pointer is a convenience."* The first half is true and the second half
+is the defect. Reproduced on a repository that had adopted and then had its pointer moved
+to `README.md`:
+
+```
+check     exit 0, three files CURRENT
+compare   problems 0 repos
+CLAUDE.md # readme
+AGENTS.md 13 rule citations, none of them read
+```
+
+Claude Code's own documentation, quoted in this repository's `POINTERS[0].verified`, says
+**"Claude reads CLAUDE.md by default and AGENTS.md only as a fallback."** On a repository
+that selected the `claude` surface, a pointer aimed elsewhere means the reader for whom the
+rules were written is reading something else — and the gate said nothing. This is the same
+shape as ADR-018's *"an unset hooks path is not an absent hook"*: the file exists, so the
+thing that reads it is satisfied, and nothing reports that it is reading the wrong bytes.
+
+The comment's reasoning came from a real observation about a **different** surface.
+DeepSeek's loader renders a drifted *copy* in full beside its twin, which is duplication.
+A *symlink* aimed elsewhere is not duplication — it is a reader looking at the wrong file.
+The old test named DeepSeek and asserted the asymmetry, so the belief was written down and
+the finding it produced was, by construction, unable to see.
+
+A second defect, not in the finding: `pointerState` classified a path as a symlink, a
+regular file, or **absent** — three answers, and a directory matched the third. A directory
+at `CLAUDE.md` is not hypothetical: it is where Claude Code keeps per-project instructions.
+Measured:
+
+```
+check    says nothing at all
+sync     ERROR 1 EEXIST: file already exists, symlink 'AGENTS.md' -> 'CLAUDE.md'
+         REMEDY run: simt-dev doctor
+```
+
+`EEXIST` fires *after* every other target is written, so the run left a half-migrated
+repository, and the remedy it offered reports nothing about a directory. The reason it was
+invisible for as long as it was: the note that would have said so printed
+`POINTER CLAUDE.md: a directory, not a pointer (undefined bytes)`, and `undefined` in a
+report reads as nothing at a glance.
+
+## Rulings
+
+1. **A misaimed pointer blocks `check` when its reader is a surface this repository
+   serves.** The gate is where the exit code lives and where CI runs. A pointer whose
+   surface was not selected is not reported at all: the reader it serves is not reading
+   this repository, and a gate that reddens for it is a gate people learn to ignore.
+
+2. **The finding names the reader.** The remedy is `simt-dev sync --yes (Claude Code reads
+   CLAUDE.md, not AGENTS.md)` — because "run the command" does not tell a reader why this
+   matters, and a warning that has been learned to skip is worse than no warning.
+
+3. **`pointer-unread`, not `pointer-drift`.** The name is the reader's word for it: the
+   pointer is present and unreadable *as the thing it is for*. `pointer-drift` named the
+   defect as staleness, which is a file's problem, and that is how a reader-blindness
+   arrived at a file-scoped non-blocking rule.
+
+4. **`sync` does not block on it and `check` does, and they are two sets.** The remedy is
+   `sync --yes`; a `sync` that refused on this finding would be a gate whose remedy is the
+   command being run, which ADR-025 ruling 6 calls worse than a noisy gate. `check` is the
+   gate CI runs and the one whose exit code a repository acts on, and there the finding is
+   the defect.
+
+   This was the finding of the slice, and it was found by rendering the output rather than
+   by reading the code — the same acceptance `AGENTS.md` sets for rule text. **The first
+   version of this fix kept one `NON_BLOCKING` set** shared by both commands, on the
+   reasoning that the writer's rule was the correct one. So `check` exited 0 on the exact
+   repository this record exists to fix, and a test asserting `check` exited 1 **passed** —
+   on a bare scratch directory that was red for a missing `AGENTS.md`. One set covering both
+   commands is how the defect survived the first time, which is the sentence worth keeping:
+   the rule was written to keep `sync` quiet and quietly quieted `check`'s exit code too.
+
+   Two sets, both asserted, and the relationship between them asserted as well: everything
+   `check` tolerates, `sync` tolerates. The gate is never the laxer one.
+
+5. **A directory is `foreign`, and its measure is entries.** `stat` distinguishes a
+   directory from a file before anything is read, because reading a directory as utf8
+   throws `EISDIR` and the old catch reported that as *absent* — the one answer that hides
+   it. The size reported is what would be lost: bytes for a file, entries for a directory.
+
+6. **`sync` repairs a misaimed pointer, because it is the remedy `check` prints.** The
+   pointer is this tool's own output, it is a symlink so it carries no content, and
+   `symlink()` at an existing path is `EEXIST` — which is what happened, after every other
+   target was written, with `simt-dev doctor` named as the remedy and `doctor` reporting
+   nothing about it. A command whose own remedy crashes on the state it names has no
+   remedy at all. Only a symlink is unlinked; a regular file or a directory never entered
+   the plan, so the repair is keyed on the pointer's **state** and not on the path
+   existing.
+
+## Consequences
+
+- `SYNC_NON_BLOCKING` and `CHECK_NON_BLOCKING` are two exported sets, and both are asserted
+  as sets *and* as a relationship. Three mutations passed the whole suite before that: `check`
+  keeping the finding non-blocking (the defect), `sync` dropping it (the ADR-025 hazard), and
+  the gate reading the writer's set. The text output is identical in all three, which is
+  ADR-035's sentence about promises about a *set* of commands, applied to a set of statuses.
+- Two tests asserted a gate that was red for the wrong reason, and both are fixed the same
+  way: "a pointer this repository does not serve stays a note" and "check blocks a mispointed
+  pointer" checked `check` on a bare scratch directory, which is red for a missing
+  `AGENTS.md`. Both now sync first, so the only thing that can redden the gate is the
+  pointer. ADR-031's shape, one level down — and the second instance is the one that matters,
+  because it was the test written *for this fix* that passed against the defect unfixed.
+- `sync` keeps its note-and-continue for a foreign pointer, and now says what kind of thing
+  is in the way. It repairs a *misaimed* one, and the test asserts that the file the bad
+  link pointed at survives — because the repair is a deletion, and a test that only checked
+  the link now points where it should would pass if `unlink` had removed the wrong thing.
+- The corpus test that encoded the old belief was **replaced, not amended**, and its
+  comment now records what it got wrong and why the observation it was built on does not
+  transfer.
+
+## Rejected
+
+- **Blocking on a misaimed pointer for every repository.** Rejected: `pointerTargets`
+  filters on the selected surfaces, and a repository on `opencode` that has a stray
+  `CLAUDE.md` gains nothing. The scoping is not a compromise; it is the same rule the
+  pointer table already encodes (ADR-021 ruling 1: a pointer belongs to the surface that
+  needs it).
+- **Writing the pointer anyway when it is misaimed.** Rejected: `symlink()` over an
+  existing path is `EEXIST`, and unlinking a path someone may have pointed deliberately is
+  a deletion this tool does not do (ADR-021 ruling 6).
+- **Treating a directory as `pointer-blocked` with a byte count of zero.** Rejected: the
+  count would be a number the reader cannot use, and the report says what is in the way so
+  a person can decide.

package/docs/decisions/ADR-052-a-dependency-is-counted-against-the-budget-and-there-is-one-budget.md

@@ -0,0 +1,101 @@
+# ADR-052 — a dependency is counted against the budget, and there is one budget
+
+Status: accepted · 2026-10-09
+**Affects:** `src/resolve/resolve.mjs`, `src/commands/skills.mjs`, `src/mcp/tools.mjs`,
+`test/resolve.test.mjs`, `test/mcp.test.mjs`. Closes S06 of
+`docs/reviews/0002-full-review-adoption-and-public-release.md`.
+
+## Context
+
+S06 filed two defects. Both reproduced; one of them is a different defect now.
+
+**A dependency overran the budget by 6.7×.** Both budget loops tested
+`entry.via.size > 0` and, if the entry was a dependency, inlined it regardless of size:
+
+```js
+const isDep = entry.via.size > 0;
+if (flags.all || used + skill.bytes <= budget || isDep) {
+```
+
+Measured against the shipped registry:
+
+```
+$ simt-dev skills brief --skill parallel-feature-team --budget 2000
+resolved: parallel-feature-team (1131), slice-commit (5048), complete-testing (7324)
+          = 13,503 bytes against a 2,000-byte budget
+```
+
+Nothing in the output says the budget was exceeded, because the condition that enforced it
+had already been short-circuited. The code's own comment gives the reason — *"a skill that
+is useless without its dependency is worse than a large context, because it silently
+misleads"* — and the premise is correct while the conclusion does not follow from it. A
+missing dependency is fixed by a line in the output; an unbounded budget is not a fix for
+anything.
+
+**The two copies had already drifted.** This is the part that had become worse than filed,
+and it is the shape ADR-035 named: a promise about a *set* of readers holds only while
+something checks the set, and here the set was two loops. `skills brief` tested `deferred`
+first and never inlined one; the MCP tool tested the budget first and then had a nested
+`if (isDep || !entry.skill.deferred)`, which **did** inline a deferred dependency. One
+command inlined a 384 KB body, the other did not, and neither could see the other.
+
+The review's probe #14 evidence is stale and the record should say so: it measured
+`summary:the` selecting four estate skills, which stopped being true when ADR-043 and
+ADR-044 landed. What is *not* stale is the defect — the `isDep` bypass is in the shipped
+code and 6.7× over budget is measured against today's registry, on a path the review never
+used.
+
+## Rulings
+
+1. **Dependencies are counted against the budget.** No entry gets in because of what it
+   is. This is the whole behavioural change and it is one condition.
+
+2. **A group that does not fit is deferred together.** An entry reached through `requires`
+   that misses the budget takes its parents with it, to a fixpoint — because a parent shown
+   without the thing it requires is precisely the misleading state ruling 1's comment was
+   written to avoid. It is now avoided by dropping the parent rather than by ignoring the
+   budget. The direction matters and is the whole of it: a small parent does not earn the
+   right to appear without its dependency.
+
+3. **`deferred` is a pointer, not a budget failure, so it does not propagate.**
+   `deferred` is derived from `deferredThreshold` and means "fetch this with
+   `skills show`". `--all` means take everything, and the pointer to a deferred dependency
+   is what a pointer is for. Only *budget* pressure moves a parent. Conflating the two is
+   how a 384 KB body would end up suppressing an unrelated 300-byte skill.
+
+4. **`selectWithinBudget()` is the whole arithmetic, and there is one of it.** It returns
+   `{ picked, deferred, used }`, and `used` is recomputed from what was actually picked
+   rather than accumulated during the walk — a parent pulled out by ruling 2 must stop
+   counting, because a total that includes a dropped skill reports bytes nobody is paying
+   and the header line prints it.
+
+5. **The two surfaces are compared to each other in a test.** Not "each is correct" —
+   each asserted against the other's output at two budgets. A parity test is the only thing
+   that catches a copy drifting from a copy, and the review's probe for this row caught the
+   drift by reading both.
+
+## Consequences
+
+- `--skill parallel-feature-team --budget 2000` now resolves nothing and names all four
+  deferred skills with `over budget`. At `--budget 20000` it resolves the group whole. The
+  reader can raise the budget or ask for one skill; before, it got 13 KB and no explanation.
+- `skills_brief` over MCP and `skills brief` are now the same function, and the test drives
+  both at 2,000 and 20,000 bytes and compares selected, deferred and bytes.
+- Six mutations were applied and reverted, each caught: dependencies bypassing the budget,
+  the group rule dropped, `deferred` no longer excluded, `deferred` counted against the
+  budget, the total no longer being the bytes paid, and the MCP tool not calling the shared
+  function.
+
+## Rejected
+
+- **Keep the bypass and report the overrun.** Rejected: the output already has a `deferred`
+  list with reasons, and a budget that means "unless" is not a budget. If the estate ever
+  decides a dependency is worth any number of bytes, that is a flag with a name saying so.
+- **Defer only the dependency and leave its parent.** Rejected: that is the state the old
+  comment called *silently misleading*, and it is what ruling 2 exists to stop.
+- **Propagate `deferred` to parents too, for symmetry.** Rejected under ADR-013: the two are
+  different signals from different fields — `bytes` against a budget the caller set, and
+  `deferred` against a threshold the registry declares — and collapsing them makes a size
+  threshold suppress a selection.
+- **Change the default budget or the deferred threshold.** Rejected: nothing here measured a
+  case where the budget, rather than its enforcement, was the problem.

package/docs/decisions/ADR-053-the-node-floor-is-22-20-0.md

@@ -0,0 +1,49 @@
+# ADR-053 — The Node floor is 22.20.0
+
+Status: **accepted** · 2026-10-10
+**Affects:** `package.json`, `src/ci/workflow.mjs`, `src/resolve/resolve.mjs`.
+
+## Context
+
+Node 20 reached end of life on 2026-04-30. `engines.node` still said `>=20`, both workflow
+templates pinned setup-node to `20`, and `matchesGlob` was a hand-written translation because
+`path.matchesGlob` is stable from Node 22.20.0 (and 24.8). ADR-042 recorded that translation
+and said ruling 1 collapses into the built-in when the floor moves. Review 0002 S47 settles
+the floor at `>=22.20.0` and says the own CI runs 22, 24 and 26.
+
+## Ruling
+
+**One.** `engines.node` is `>=22.20.0`. Both workflow templates pin `actions/setup-node` to the
+version that range names, read from `package.json`, so a template cannot name a version the
+package says it does not run on. This repository's own gate also runs Node 24 and Node 26. A
+floor that is only executed at the minimum is a floor in name.
+
+**Two.** `matchesGlob` is `path.matchesGlob`. A trailing double star also matches the directory
+itself: the built-in requires a child, so `migrations` misses `migrations/**`, and that empty
+path is the one `graph lint` builds (ADR-042, ruling 3). A glob containing `?`, `{` or `[`
+matches nothing, so ruling 4 still holds. Ruling 1 of ADR-042 is superseded by this record.
+Rulings 2, 3 and 4 of ADR-042 stand.
+
+**Three.** The runtime line is the same sentence in `package.json`, both templates, this
+record, plan 0002's live Runtime line, and `README.md`. The README states the floor and
+nothing else; the packaging README is S18 and does not get to pick a different floor.
+
+## Rejected
+
+**Waiting for S18's README before raising the floor.** The floor is what CI and the matcher
+run on. A missing README was not a reason to keep declaring a runtime that is end of life.
+
+**Pinning both templates at Node 24 in this record.** S48 owns "templates use 24", the SHA
+pins, and the macOS matrix. This record's adopting template uses the floor so it agrees with
+`engines`. The own gate's extra versions are coverage, not a second floor.
+
+**Letting `path.matchesGlob` implement `?` and braces.** It does, and that is how `src/a?.ts`
+matches `src/aq.ts`. ADR-042 ruling 4 refused that reading because the registry does not use
+it and a glob that matches the wrong paths is worse than a glob lint rejects.
+
+## Consequences
+
+- `compileGlob` is gone. The cases ADR-042's tests lock (`**/*.ts`, a star that does not cross
+  `/`, a bare `**`) are now the built-in's, and the `?` case still fails lint.
+- SHA-pinning `actions/checkout` and `actions/setup-node`, and the macOS runner, stay with S48.
+- The adopting workflow's install step stays with S35.

package/docs/decisions/ADR-054-the-digest-covers-every-byte-that-leaves-the-package.md

@@ -0,0 +1,100 @@
+# ADR-054 — The digest covers every byte that leaves the package, and a cause is read off the body
+
+Status: **accepted** · 2026-10-10 · amends [ADR-032](ADR-032-provenance-is-a-content-digest-not-a-commit.md)
+**Affects:** `src/projection/rules.mjs`, `src/upgrade/plan.mjs`.
+
+## Context
+
+ADR-032 made the stamp a SHA-256 digest of `rules/` and `graph/`, and said why `src/` is
+excluded: a refactor that changes no rule and no registry entry projects byte-identical
+output, and stamping those consumers would report drift where there is none.
+
+That reasoning is right and the boundary was drawn one level too low. ADR-032 excluded a
+*directory*; the shared `.editorconfig` and `.gitattributes` blocks are not in a directory,
+they are two string constants in `src/projection/baselines.mjs` — and every adopting
+repository receives them. By ADR-015's own rule, a source is identified by its content rather
+than by the file it happens to live in, so the body defined in `src/` is a source like any
+other, and excluding `src/` as a path excluded content that leaves the package with it.
+
+The finding arrived sideways, which is the only way this class gets found. Removing the
+inert `[prettier]` block (S30) deleted seven lines from a shipped baseline — the first change
+in this repository that moves bytes out of `src/` without moving the provenance digest.
+Measured on a scratch repository with **only** that baseline body changed:
+
+- `check` reported `DRIFT .editorconfig`, which is correct: the gate compares bytes, and the
+  bytes were wrong.
+- `upgrade` reported the pin as `(unchanged)` and named the cause as
+  *"region restamped; the pin was already current (the rules changed)"*.
+
+Both halves of that sentence are false. The pin was unchanged because the stamp could not see
+the change, and the rules did not change — seven lines of an indentation setting did. The
+first false statement made the second one reachable: with the stamp silent, the only cause
+left to report was the one that was least true.
+
+The severity is the estate's own: a report that names a cause which did not happen sends the
+reader to diff `rules/` when the change is in `.editorconfig`. This is ADR-050's mistake one
+layer up — a field read for the thing it was not — and ADR-036's, where an instruction that
+is false in every repository is worse than one that is missing.
+
+## Ruling
+
+**One. The digest covers every byte string that leaves the package: `rules/` and `graph/` on
+disk, plus the rendered baseline bodies.** The baselines enter keyed by the file each becomes
+in the adopting repository (`baselines/.editorconfig`), not by the module that defines it,
+because the stamp answers what content produced those bytes and `.editorconfig` is the name
+a reader of a generated region recognises. `src/` remains excluded *as a directory*; the
+ruling narrows ADR-032's exclusion from a path to a rule about content. Ruling 1 of ADR-032
+and its "what the digest covers" section are superseded; ADR-032's framing, its framing
+discipline and its other two consequences stand.
+
+**Two. `provenanceInputs()` is exported, and `provenanceDigest()` hashes what it returns.**
+"The digest covers the right things" is a claim about a set, and a set assembled only inside
+the function that hashes it cannot be asserted from outside — the test would have to mutate
+the package to get an answer. Reading the list and hashing it in one place is ADR-042's
+ruling 3 applied to the stamp: the rendering is shared, so narrowing it narrows the test with
+it, and the test passed with the rendering sabotaged is not evidence.
+
+**Three. `upgrade`'s cause is read off the projected body, and the two kinds of content are
+counted apart.** A baseline region is not a rule: `.editorconfig` and `.gitattributes` are
+settings the repository owns. `rulesChanged` and `baselineChanged` are computed separately
+and the sentence names one, both, or neither. The comparison is body to body rather than
+byte to byte, because the region header carries the stamp and folding it in would make every
+pin bump claim a change of policy — which is ADR-050's ruling, and it is why a target whose
+seam moved reads as `updated` with no cause.
+
+**Four. "Neither" is a real answer and is not collapsed into the nearest cause.** A seam
+repair, a stamp-only move and a generated-field move are three different problems that one
+command fixes, and the sentence distinguishing them is the whole reason the command exists.
+
+## Consequences
+
+- **Every adopted repo's stamp moves once more.** A repo pinned at a digest computed without
+  the baselines reports `behind` the first time it runs this version and `simt-dev upgrade`
+  fixes it. That is a pin doing its job, not a regression — the same reading as ADR-032's own
+  first consequence.
+- **`upgrade` can no longer report a cause it cannot see.** The two defects were independent
+  and are now separately guarded: the digest test asserts the baselines are in the hashed set
+  and that changing one changes the value; the planner test asserts a baseline body move
+  produces "a baseline changed" and not "the rules changed".
+- **The planner needed a `kind` it did not have.** Baseline targets already carried
+  `kind: 'baseline'`; rule and primary targets carry none. That is the discriminator, and it
+  is read from the targets `plan` produced rather than recomputed from the file list, so the
+  two cannot disagree about which file is a baseline.
+- **A `src/` refactor still moves nobody.** The exclusion was narrowed from a path to a rule
+  about content, and the test asserts no `src/` entry appears in the hashed set — so the
+  narrowing cannot be re-widened silently by a future import.
+
+## Rejected
+
+- **Hash `src/` as a directory.** The smallest diff and the wrong one: it puts every
+  refactor, comment change and test edit into every consumer's stamp, which is precisely the
+  false report ADR-032 ruled out.
+- **Leave the stamp alone and fix only the wording.** The wording was the visible half. With
+  the pin reporting `(unchanged)` beside a restamped region, `upgrade` would still be
+  describing a move that did not happen — and the reader has no way to tell which line of
+  the output to disbelieve.
+- **Give baselines their own stamp field.** A second identity per repository, and the reader
+  would have to know which of two values to compare against. One stamp, covering everything
+  it stamps.
+- **Call the baseline a "rule" in the message.** Cheaper than a discriminator, and it sends
+  the reader to `rules/` — which is the defect.