simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/docs/decisions/ADR-048-a-baseline-carries-only-keys-a-reader-honours.md

@@ -0,0 +1,150 @@
+# ADR-048 — a baseline carries only keys a reader honours
+
+Status: accepted · 2026-10-09 · amends ADR-025 (withdraws ruling 8, corrects its context)
+**Affects:** `src/projection/baselines.mjs`, `test/baselines.test.mjs`,
+`docs/plans/0001-centralise-agent-rules.md`. Closes S30 of
+`docs/reviews/0002-full-review-adoption-and-public-release.md`.
+
+## Context
+
+ADR-025 ruling 8 put `[prettier] singleQuote = true` in the shared `.editorconfig` and
+called it *"the only comment-capable home prettier reads"*. Both halves of that sentence
+are false, for one normative reason and one vendor reason, and neither is visible from
+inside this repository.
+
+**A section header is a glob.** The EditorConfig specification (v0.17.2, *File Format*)
+is explicit: a "Section Header … define[s] globs", and *Glob Expressions* lists `*`,
+`**`, `?`, `[seq]`, `[!seq]` and `{s1,s2,s3}` as the characters that do the matching.
+`[prettier]` therefore matches a file named `prettier`, in a directory of the
+repository or below it. No repository has one. The block matched no file, ever.
+
+**`singleQuote` is not a key anything honours.** The same specification's *Supported
+Pairs* section defines nine keys — `indent_style`, `indent_size`, `tab_width`,
+`end_of_line`, `charset`, `spelling_language`, `trim_trailing_whitespace`,
+`insert_final_newline`, `root` — and `singleQuote` is not among them. That section also
+settles what an undefined key does, and it settles it in the worst possible direction:
+cores "shall accept and report" syntactically valid pairs even when the key is not
+defined, while plugins "shall ignore unrecognized keys". An unknown key is not an error
+to be reported; it is a line that parses and does nothing.
+
+Prettier's own mapping (`src/config/editorconfig/editorconfig-to-prettier.js` on `main`)
+reads exactly six properties: `indent_style`, `indent_size`, `tab_width`,
+`max_line_length`, `quote_type` and `end_of_line`. `singleQuote` is not one of them, and
+neither `quote_type` nor `max_line_length` is a key the specification defines — the
+source labels `quote_type` an "Undocumented feature". Its published documentation
+mentions only `max_line_length`, `indent_size`, `tab_width`, `indent_style` and
+`end_of_line` as the editorconfig properties it reads.
+
+So the region asserted, in a comment, that it was the file that settled the estate's
+`singleQuote` disagreement; the value was in a section that matched nothing, under a key
+that no reader honours. That is the "decoration that misdescribes the artefact" failure
+this repository's own `AGENTS.md` names, and no gate here could see it: `check` compares
+bytes, and the bytes were current.
+
+**This record cites the specification and the vendor's source rather than a local run.**
+That is a change from the review's evidence, which measured Prettier 3.8.3, and it is
+deliberate. ADR-041 rules this package's suite against reaching for a formatter, and the
+npm registry this was written against refuses the fetch (`403`), so a reproduced run was
+not available. The two citations are stronger for the purpose anyway: one is normative and
+one is the mapping Prettier actually runs, whereas a version-pinned run would date the
+moment the question was asked.
+
+## The survey S30 asked for
+
+S30's fix was split in two on purpose: delete the block **now**, and add `quote_type =
+single` **only with an estate survey**. The survey is this section, and it is the reason
+the second half is not taken.
+
+Five of the sixteen repositories run Prettier. Prettier resolves `.editorconfig` first and
+merges the repository's own config over it (`resolve-config.js`: `{ ...editorConfigured,
+...mergeOverrides(...) }`), so a repository that states `singleQuote` is unaffected by
+anything this baseline says, and a repository that states nothing is decided entirely by
+it.
+
+| Repository | Prettier config | States `singleQuote` | Adopting `quote_type = single` |
+| --- | --- | --- | --- |
+| `repo-04` | `.prettierrc` | `true` | no change |
+| `repo-06` | `.prettierrc.json` | `true` | no change |
+| `repo-15` | `.prettierrc.json` | `true` | no change |
+| `repo-11` | `.prettierrc.json` | absent | **every source file reformatted** |
+| `repo-14` | `.prettierrc.json` | absent | **every source file reformatted** |
+
+Two repositories would have every source file rewritten on the day they adopted the
+tool, in a commit whose message says it adopted a rules projection. The measurement is
+the answer to the question S30 deferred: the second half is not taken, and the reason is
+recorded here so the next person does not run the survey again to reach it.
+
+## Rulings
+
+1. **`[prettier] singleQuote = true` is withdrawn.** ADR-025 ruling 8 does not stand; its
+   `printWidth` half is unaffected and was never implemented. This changes no behaviour,
+   because the block was inert — which is why two reviews and the whole suite read past
+   it: the gate compares bytes, and the bytes were what the source said they were.
+
+2. **A baseline section header is a glob over paths, never a name.** A header with no
+   special character matches one filename, and the only filenames a file every
+   repository receives may name are the ones every repository has. A literal travels
+   inside a brace group with the globs it belongs with — `[{*.go,*.proto}]`, which this
+   baseline already does for exactly this reason. `test/baselines.test.mjs` asserts it,
+   because the defect it prevents is a header that parses.
+
+3. **Every key in a baseline is one a reader honours.** The nine keys the specification
+   defines are the whole vocabulary, and the test names them with the section they come
+   from. This is what rules `singleQuote` out by construction rather than by deletion:
+   `quote_type` is excluded by the same test, and the reason it is excluded is written
+   next to it.
+
+4. **`quote_type = single` is not adopted, and the estate survey above is its record.**
+   Not rejected in principle: rejected for now, on a measurement — two of five
+   repositories would be wholly reformatted, and this tool does not reformat a
+   repository on the day it adopts one. The disagreement it would settle is real and is
+   still open (ADR-025's consequences already recorded `singleQuote` as unsettled
+   everywhere else), and it belongs in each repository's own Prettier config, which is
+   the only place that can change a repository's bytes.
+
+## Consequences
+
+- `.editorconfig` loses eleven lines, one of which was the only claim in the file about a
+  tool. Every adopting repository sees a real `.editorconfig` change on its next
+  `sync --yes`, and `check` reports it: the baseline target list is the one `check` and
+  `upgrade` both read, so the repository is correctly classified as behind. What `upgrade`
+  will *not* do is name the cause correctly. Measured on a scratch repository carrying the
+  body this record withdraws and every other byte current:
+
+  ```
+  DRIFT      .editorconfig  region is updated; run: simt-dev sync --yes
+  pin     0cfea39f…6671 (unchanged)
+  region restamped; the pin was already current (the rules changed)
+  ```
+
+  No rule changed. The provenance digest covers `rules/` and `graph/` and deliberately
+  excludes `src/` — the rationale is that "a change that moves a consumer's projection"
+  must move the stamp, and the baseline bodies are content that leaves the package while
+  living in `src/`. `check` is unaffected because it compares bytes, and `upgrade` is
+  affected because it compares the stamp. ADR-032 found this exact false cause once
+  already, for a different reason, and the fix there was to identify the projection by its
+  content rather than by a commit; the same gap survives for the bytes that are not in
+  `rules/`. It is filed as **S53** with this measurement attached rather than fixed here,
+  because widening the digest changes what the stamp means and that is ADR-032's subject
+  (ADR-002).
+
+- Plan 0001 claims the contradiction is settled "in `.editorconfig`'s `[prettier]`
+  section" in two places. Both were true of the file and false of its meaning, so both
+  are amended to point here. Leaving them would leave the plan asserting a mechanism this
+  record has just withdrawn, which is ADR-036's failure one document up.
+
+- `test/baselines.test.mjs` grew a guard rather than an assertion about today's string,
+  because a string assertion passes the day somebody pastes the block back.
+
+## Rejected
+
+- **Keeping the block and correcting only its comment.** Rejected: it would leave a
+  section matching nothing, and the next reader would have to rediscover that a comment
+  admitting it is inert is still inert.
+- **`quote_type = single` under the JS/TS glob, as S30's second half proposed.**
+  Rejected on the survey above. It is recorded as a measurement, not as a plan, because
+  the cost lands on two repositories that did not ask for it.
+- **Widening the digest to cover baseline bodies in this slice.** Rejected under
+  ADR-002: it is a change to what the stamp means, which is ADR-032's subject and
+  deserves its own record. It is filed as S53 with this measurement attached, so the
+  next reader has the evidence rather than the conclusion.

simt_dev/vendored/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.

simt_dev/vendored/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).

simt_dev/vendored/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.

simt_dev/vendored/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.