simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/docs/decisions/ADR-038-the-gate-filter-belongs-to-every-manifest-writer.md

@@ -0,0 +1,95 @@
+# ADR-038 — The gate filter belongs to every writer of a manifest, not to `init`
+
+Status: **accepted** · 2026-10-08 · amends [ADR-017](ADR-017-a-declared-gate-must-be-runnable.md) ruling 1 · affects every code path that calls `buildManifest`
+
+## Context
+
+ADR-017 ruled that a gate is declared only if the repo can run it, and attributed the
+mechanism to one command: *"`init` filters the stack table's proposals through what the
+repo demonstrably has."* The belief is general. The attribution is what was read, and it
+stayed true only as long as `init` was the sole writer of a manifest.
+
+Review 0002's S27 is what the attribution bought. `recordLocal` in `skills install` writes a
+manifest for a repo that has none, and called `buildManifest` with no capability. Measured
+end to end: a bare Node repo — a `package.json` with no scripts and no `node_modules` — ran
+`skills install api-contract-sync --yes`, and the manifest it was handed declared `format`
+and `lint` on pre-commit and `test` and `typecheck` on pre-push. `check` then reported four
+`UNRUNNABLE` findings and exited 1. After `hooks install`, a real commit ran the pre-commit
+gate, which failed both staged gates with their remedies and blocked. The hook's own exit
+code is not the commit's, so the reader's first evidence is a commit that silently did not
+happen.
+
+Four declared gates the repo cannot run, written by a command whose entire job is to pin
+one skill. ADR-017's own wording names this as the failure: *"declaring one would block
+every commit"*.
+
+The test that should have caught it asserted the opposite of the truth. It checked that
+`gates` was present and that `preCommit` and `prePush` were **non-empty**, and read
+non-empty as correct — so the test about manifests being right passed on a manifest
+declaring four gates nobody could run.
+
+## Ruling
+
+**1. `buildManifest` requires a capability from every caller.** The filtering happens in one
+place, and that place is reached only with the evidence it filters on. A caller that passes
+no `capability` is a caller asking for the defaults, and today it gets them — which is
+correct for a pure function and wrong for a writer. Rather than make the parameter
+mandatory and break the three call sites that legitimately want defaults, the ruling is on
+who writes: **a command that writes a manifest for a repo that has none must probe first**,
+because it is making a promise on that repo's behalf.
+
+**2. A command that writes a manifest declares nothing it cannot prove.** This is ADR-017
+ruling 1 with its attribution removed, and it covers a shape ADR-017 did not anticipate:
+a writer that is not an adoption command. `skills install` is not adopting the repo. It
+pins one file into `.agents/skills/`. Writing a full manifest was already the wrong shape
+for it and was ruled on once already; the record for that ruling said *"a `{localSkills}`
+stub would read as authoritative while omitting `gates`"*, and the fix was to write the full
+canonical shape. The reasoning was right and the conclusion drawn from it was wrong, because
+canonical shape and default gates are different things and only one of them is a fact about
+the file's schema.
+
+**3. A manifest that declares no gates is a valid answer.** A repo with no scripts and no
+formatter gets `preCommit: []` and `prePush: []`. ADR-017's consequences section already
+ruled this — `init` has been writing it — so the only new fact is that a reader of the
+record can now see the invariant is not `init`'s to keep.
+
+**4. The test asserts the manifest is true, not that the field is present.** The new test
+runs `unrunnableGates(manifest, await readCapability(root))` — the function `check` runs,
+with the probe `check` uses — and requires an empty result. It also runs against a fixture
+that *can* run gates and requires them to be there, because a fix that hardcoded two empty
+lists would pass the first half and arm the project with no gates at all.
+
+## Consequences
+
+`test/install.test.mjs`'s existing assertion changed from
+`assert.ok(manifest.gates.preCommit.length > 0 && …)` to
+`assert.deepEqual(manifest.gates, { preCommit: [], prePush: [] })`. That is a test whose
+pass condition was the defect, and it is the fourth in this repository to read presence as
+correctness — the shape ADR-030 exists to catch.
+
+Three mutations were applied and reverted, each caught by its own test: the `capability`
+argument removed; a hand-built empty capability substituted for the probe (caught by the
+capable half, not the bare one); and the capable half's non-empty assertion deleted — which
+the bare half alone did not notice, confirming both halves earn their place.
+
+## Rejected
+
+- **Make `capability` a required argument of `buildManifest`.** Three callers legitimately
+  want the unfiltered defaults, including the tests that exercise `planGates` directly. A
+  signature that cannot be called wrongly is worth having, and the wrong call here is one of
+  two lines in a function whose purpose is obvious from its name; ruling on the caller keeps
+  `buildManifest` a pure function that a test can call with any evidence it likes.
+- **Have `skills install` write a `{localSkills}`-only manifest after all.** That was ruled
+  on and the ruling holds: a partial manifest reads as authoritative while omitting `gates`,
+  and `init` would then have to be run to complete it. Probing is the smaller change.
+- **Let `check` repair it, since `check` already reports the finding.** `check` reports
+  findings; it is not the command a reader runs before `skills install` has already blocked
+  their commits. The landmine has to be defused at the moment it is laid.
+- **Leave ADR-017 as written and put the generalisation only in the code.** The code is
+  where the second writer is, and a record that names `init` is a record a reader trusts to
+  have already covered the case. ADR-017's own context section says nothing else owns the
+  manifest — that was true in 2026-10-06 and this is what made it false.
+- **Amend ADR-017's ruling 1 in place.** ADR-017 is accepted and its context is the evidence
+  for why the gate filter exists at all. Rewriting the sentence would leave no trace that the
+  rule was ever narrower than it reads, which is the same trick the gate list itself was
+  performing on its reader.

simt_dev/vendored/docs/decisions/ADR-039-a-ci-step-runs-a-form-that-can-fail.md

@@ -0,0 +1,101 @@
+# ADR-039 — A gate a CI step runs must have a form that can fail, and a refusal is a failure
+
+Status: **accepted** · 2026-10-08 · affects `ci`, its own workflow copy, and any command a workflow runs
+
+## Context
+
+Review 0002's S23 found three things about `simt-dev ci` and the step this repository's own
+workflow runs. All three reproduced against the shipped binary, and the first is the reason
+this record exists.
+
+**The own gate's own copy is checked by a step that cannot fail.** `.github/workflows/simt-dev-check.yml`
+carries a step named "the gate copy in this repo is current", with the comment *"the drift
+this exception exists to prevent, checked where it would be caught"*, running
+`node bin/simt-dev.mjs ci`. With a hand edit appended to the copy, `ci` printed:
+
+```
+file      .github/workflows/simt-dev-check.yml
+action    refresh
+why       this repository is simt-dev's own, and the gate template has changed since this copy was written
+```
+
+and exited **0**. The step read the drift it was written to catch, printed it, and passed.
+That is the shape this repository's own rules keep warning about — a control that appears to
+hold and does not — except that here the control was the one enforcing the control.
+
+**`ci --json --dry-run` printed nothing.** The JSON branch was guarded by
+`flags.yes !== true && flags.dryRun !== true`, so the one combination a script reaches for
+was the one combination with no document on stdout at all.
+
+**A refusal reported success.** Run in a repository that adopted simt-dev, `ci` explains at
+length that the `.github` file is the repository's own, names `simt-dev init --yes` as the
+remedy, and then emits `{"ok": true, …, "own": false}` and exits **0**. A caller reading `ok`
+is told the request succeeded, one line above a paragraph saying it was refused.
+
+## Ruling
+
+**1. A command whose output a CI step consumes has a form that can fail, and that form is
+what the step runs.** Previewing by default is right for a human at a terminal and wrong for
+a gate: a step has no reader to hand the plan to. `ci --check` exists for that and never
+writes, whatever else it is given — a check that repairs is a second writer, which ADR-036
+is about.
+
+**2. A check that names drift shows the drift.** `--check` prints a unified diff of both
+files. The reader is the author of the template change that made the copy stale, and the
+question they have is "what did I change". The plan now carries both sides of the
+comparison — `source: { text, desired }` — so the verdict and the diff cannot disagree, and
+those two bodies are stripped from the JSON payload, because a document is not the place
+for two copies of a workflow file.
+
+**3. A refusal is `EXIT.UNSUPPORTED` with `ok: false`.** Not because nothing is wrong, but
+because the request cannot be satisfied *in this repository*, which is what the code is
+documented to mean (`output/index.mjs:16`). The prior behaviour also contradicted ADR-035
+directly: it emitted `ok: true` and exited 0 while the text beside it said the opposite, and
+ADR-035 requires the two to agree. This is the first place in the tool where they
+disagreed by design rather than by oversight.
+
+**4. `--json` emits one document in every mode, and `ok` agrees with the exit code.** The
+mode guard was the bug; the invariant is ADR-035's. The test walks the modes rather than
+trusting the guard.
+
+## Consequences
+
+`test/ci.test.mjs` gains a `run()` helper that reports the exit code instead of rejecting.
+`promisify(execFile)` rejects on non-zero, which is right for a helper asserting success and
+useless for every test about a command that must fail — and the code a refusal test needs to
+check is the code inside the rejection.
+
+The existing refusal test asserted exit 0 and carried the reasoning *"the refusal must not
+be an error, because nothing is wrong"*. That reasoning is this record's third ruling
+overturned, so the comment now says why the opposite holds.
+
+The `--check` and `--json` tests run **in this repository on a stale copy**, with a `finally`
+that restores the file, because `isOwnRepo` compares against the package root and no temp
+repo can reach this code. The first version of the JSON test used a fixture and passed with
+the guard restored: the fixture was not the own repository, so every mode took the refusal
+path and printed a perfectly good document — for the wrong reason. A mutation found it.
+
+Four mutations were applied and reverted, each caught by its own test: `--check` returning
+`EXIT.OK`, the refusal returning `EXIT.OK`, the mode guard restored, and the workflow
+template reverted to the bare `ci`.
+
+## Rejected
+
+- **Leave the own gate's step running `ci` and rely on the reader.** The reader is a person
+  who did not make the template change and will not know that the step passed. A gate whose
+  failure is visible only to someone reading logs is a note.
+- **Make `ci` itself exit non-zero on drift, without a `--check`.** That is what the review
+  asked for and it would break ADR-036: previewing by default is the rule every writer
+  follows, and one writer that reports drift is the exception nobody remembers.
+- **Keep the refusal at exit 0 and change only `ok` to false.** Two answers to one question
+  is the defect ADR-035 exists to prevent, and the more surprising half of the two: the
+  shell reads the code, and it was reading success.
+- **Exit `EXIT.FAIL` (1) for the refusal.** It is not a gate that failed; nothing ran. `1`
+  means "a gate failed: drift, policy violation, missing evidence", and a caller deciding
+  whether to re-run on `1` would retry a request that can never succeed in this repository.
+- **Ship the diff as a dependency rather than writing it.** ADR-012 rules the dependency, and
+  the diff here has one reader and one shape: two whole files this tool wrote, differing by
+  lines. A line-level LCS table is a screen and a risk, not a dependency.
+- **Print the whole file rather than eliding context.** The output is the only reason the
+  step is worth having over a bare exit code, and fifty lines of context around one changed
+  step buries it.

simt_dev/vendored/docs/decisions/ADR-040-the-last-writer-that-wrote-by-default-was-not-the-one-named.md

@@ -0,0 +1,158 @@
+# ADR-040 — The last writer that wrote by default was not the one named
+
+Status: **accepted** · 2026-10-08 · affects `simt-dev hooks install`, every remedy naming it, and the shim it installs
+
+## Context
+
+ADR-035 ruled that `writeMode(flags)` decides whether a run may write, "and every mutating
+command reads it. A command that consults `flags.yes` directly is a defect whether or not its
+arithmetic happens to agree today". ADR-036 then took `sync` out of the set of writers that write
+by default. Review 0002's S24 opened by calling `sync` "the only writer that writes by default"
+and named its five siblings as the ones that "all preview first": `init`, `upgrade`, `ci`,
+`hooks install` and `skills install`.
+
+Four of those five were true. One was not.
+
+Measured against the shipped binary, in a fresh repository that declares `lint` and `test`:
+
+```
+$ simt-dev hooks install --root .
+repo     .
+core.hooksPath  created  (unset) -> .simt-hooks
+CREATED   .simt-hooks/pre-commit
+CREATED   .simt-hooks/pre-push
+WROTE    shims and set core.hooksPath
+$ echo $?
+0
+```
+
+`hooks.mjs` read `flags.yes` at line 146 and `flags.dryRun` at line 169 and imported neither
+`writeMode` nor any other write decision. In the ordinary case — no `core.hooksPath`, no foreign
+hook — neither flag was consulted at all and the shims were written.
+
+Six independent sources agree this is a defect rather than an exemption:
+
+1. ADR-035's ruling names the exact pattern as a defect.
+2. The code is the pattern.
+3. S24's premise, which is the finding the rest of Wave 0 was ordered against, was wrong on one
+   of six.
+4. Review 0002's own migration script instructs: "**Route hooks.** `simt-dev hooks install`
+   (plan), then `--yes`." An operator following it would read a plan and get a write, and the
+   `--yes` on the next line would be spent on nothing.
+5. Three **shipped** strings assumed the preview: `init`'s remedy, two `compare` remedies, and
+   the `Reinstall with:` comment inside the shim itself, which is written into every adopting
+   repository.
+6. `contract.test.mjs`'s `WRITERS` table covered `upgrade`, `sync` and `skills install`. It never
+   covered `hooks install`, which is why 586 tests did not notice.
+
+Six is not an accident and it is not a subtle shape. It is what happens when a rule about a set of
+commands is checked by reading the commands one at a time.
+
+The comment `sync.mjs` gained in ADR-036 is part of the evidence. It reads "the odd one out among
+six: `init`, `upgrade`, `ci`, `hooks install` and `skills install` all preview unless told
+otherwise" — a claim about code a different file owns, one commit out of date, which this record
+corrects.
+
+## Ruling
+
+**1. `hooks install` reads `writeMode(flags)`, like every other writer.** `apply` gates the write
+and the `core.hooksPath` assignment together, so there is no half-installed state reachable by a
+flag combination.
+
+**2. The preview exits `EXIT.OK` and names the command that applies it.** A rehearsal is not a
+failure: `upgrade`, `ci` and `skills install` previews all exit 0, and a preview that exits
+non-zero would make `--dry-run` unusable in a script for no gain. This is deliberately **not**
+`sync`'s rule, where a preview that found work exits 1 because plain `sync` is also a check
+(ADR-036). `hooks install` is not a check; `hooks status` is, and it says so through its own exit
+code.
+
+**3. `--yes` is one flag doing two jobs here, and that is not a reason to keep two.** It
+authorises the write *and* it is the consent ADR-018 requires to take over routing git is already
+using. A bare command is refused in the takeover case and merely previews in the ordinary one, so
+the consent is required exactly where it was before and the write is now gated by the same word.
+The BLOCKED text needed no change: it already ended "then re-run with `--yes` to accept".
+
+**4. Every string that names the command moves with it.** `init`'s remedy, both `compare`
+remedies, the shim's own `Reinstall with:` comment, the help synopsis, and the ADR-036 comment
+that misdescribed it. This is ADR-036's own rule — "a writer that writes says so, and the
+instructions naming it move with it" — applied to the second writer rather than the first.
+
+**5. A remedy is a guard, and the guard covers both writers.** `shipped.test.mjs`'s "every remedy
+names a command that does what the remedy claims" now scans `simt-dev hooks install` as well as
+`simt-dev sync`. The assertion had to be rewritten to be worth having: the original required the
+authorising flag immediately after the command, which would have reported `simt-dev hooks install
+--root <path> --yes` — the shape `init` prints — as an offender. It searches the rest of the line
+instead, stopping at the next `simt-dev` so a correct remedy cannot vouch for a bare one later on
+the same line, and it skips comment lines because prose about the tool is not an instruction to
+run it.
+
+**6. An unauthorised run that finds work is either a rehearsal or a refusal, and the exit code is
+the only thing that says which.** This is a change to the `WRITERS` table, not to `hooks install`.
+Asserting only the bytes passes on a command that **refuses** rather than previews, because a
+refusal changes nothing. `hooks install` on a repo with no runnable gate is refused exactly that
+way, and the refusal is correct: a shim with an empty gate list enforces nothing yet merely
+existing replaces whatever git was running. The row therefore carries `stack: 'node'` and the
+table asserts the exit code of every unauthorised run — 0 for a rehearsal, non-zero only for the
+row (`sync`) that is also a check. The old `if (writer.name === 'sync')` special case became a
+`previewFindsWork` column, because a table that encodes one row's name in the loop is a table that
+cannot get a new row right.
+
+The assertion is scoped to the unauthorised form. A rehearsal is a different question:
+`sync --yes --dry-run` reports the work it found exactly as the unauthorised form does (ADR-036),
+and requiring 0 there would fail on behaviour that record deliberately settled. **That was caught
+by a mutation, not by reading it** — the first version asserted the exit code in both modes and
+failed the whole table.
+
+## Consequences
+
+`hooks install` becomes the fourth row in `contract.test.mjs`'s `WRITERS` table, and its
+`verify` fingerprints **both** things it writes: the shim under `.simt-hooks/` and
+`core.hooksPath` inside `.git/config`. The second is not decoration. A preview that set the config
+without writing the shims would leave a repository whose commits are gated by a hook git does not
+run, which is the same silent downgrade ADR-018 exists to prevent — and a shim-only fingerprint
+does not notice it. Removing the config probe makes that mutation pass; that was measured rather
+than assumed.
+
+Six mutations were applied and reverted, each caught by its own test:
+
+| Mutation | Caught by |
+| --- | --- |
+| the `!mode.apply` gate removed — always write | the `WRITERS` row |
+| the preview drops the "apply with:" clause | `hooks install: without --yes it prints the plan and the command that applies it` |
+| `init`'s remedy loses `--yes` | `every remedy names a command that does what the remedy claims` |
+| the shim's `Reinstall with:` loses `--yes` | the same guard, and `the installed shim tells the reader how to reinstall it` |
+| the `WRITERS` row pointed at the python fixture | the new exit assertion — *"hooks install exited 1 instead of previewing"* |
+| the preview half-writes `core.hooksPath` | the `WRITERS` row, and **not** without the config probe |
+
+A seventh mutation is worth recording because it was **not** caught by the new row: `hooks
+install --yes` that never sets `core.hooksPath` passes `contract.test.mjs` entirely, because the
+row only exercises unauthorised and rehearsed runs. Six tests in `hooks.test.mjs` catch it. The
+row does not carry that claim and this record does not claim it does.
+
+Two of the new assertions were wrong before they were right. The exit-code assertion was, as
+above. The `sync` row's own preview also exits 1 in `--dry-run`, which is the same finding seen
+from the other row. Two of two wrong first is not a coincidence worth explaining: a table that
+grows a new column needs each cell written down, and neither cell was.
+
+## Rejected
+
+- **Treat `hooks install` as exempt because ADR-018 already asks for consent.** ADR-018's consent
+  is about *taking over* routing git already uses. In the ordinary case there is nothing to take
+  over, so the consent requirement never fired — and the write happened anyway. An exemption
+  invented to fit a defect is indistinguishable from a decision, which is why this one would have
+  needed a reason and there is not one.
+- **Leave `--yes` as takeover-only and add a second flag for the write.** Two flags for one
+  decision is ADR-035's defect restated: a command reading `flags.a` for one thing and
+  `flags.b` for another is how `upgrade` read `yes` and ignored `dryRun`. The word "yes" is also
+  what the reader expects, and every remedy already says `--yes`.
+- **Make the preview exit 1 when it finds work, matching `sync`.** Defensible, and it would break
+  `hooks install` in the one script shape that uses it: read the plan, then decide. `hooks status`
+  is the command for "is this repo wired up", and it already reports drift through its exit code.
+- **Only add the `WRITERS` row and leave the shipped strings.** The strings are the defect's
+  widest blast radius. A remedy that prints a command which no longer reinstalls is ADR-036's
+  exact failure, one writer later, and `Reinstall with:` lives inside the file that gets installed
+  into every adopting repository.
+- **Rewrite `sync.mjs`'s ADR-036 comment by deleting the sentence.** The sentence is the record of
+  why that change was made. It is amended instead, with the correction stated, because a comment
+  that enumerates which commands follow a rule is a claim about code this file does not own and
+  the next reader has no way to check it cheaply.

simt_dev/vendored/docs/decisions/ADR-041-the-suite-installs-the-package-in-order-to-test-it.md

@@ -0,0 +1,92 @@
+# ADR-041 — The suite installs the package in order to test it
+
+Status: **accepted** · 2026-10-08
+**Affects:** `test/pack.test.mjs` and what the suite may assume about `npm`.
+
+## Context
+
+Every other file in `test/` imports from `../src`. That is what they are for: they are tests of
+units, and a unit test cannot see a file that `package.json` forgot to ship. S01 shipped a
+package whose `files` list and whose runtime reads disagreed, and the suite was green — because
+every test in it was reading the checkout rather than the artefact.
+
+Review 0001 §S20 named five missing test families. Four have since landed: the JSON and
+write-mode contract table (S10), the git-state hook tests (S08), the resolver tests (Wave 1) and
+the MCP parity work in progress. The first family on the list, pack-and-install end to end, was
+still open, and review 0002 §5 says plainly that it "is the one that would have caught S01, S27
+and S35 before they shipped; land it first, with S01". S01 had already been closed. So the row
+that was supposed to be carried by it was never carried at all.
+
+Two facts about this repository make that gap harder to notice than it looks. `test/` may not
+reach outside the checkout (ADR-031), and this package has no dependencies (ADR-012). Together
+those mean the suite has no installed copy of itself to test, and the natural workaround —
+borrowing a formatter from a neighbouring checkout — is the one ADR-031 rules out. Prettier 3.8.1
+is sitting in `../repo-06/node_modules/.bin` and is not available here.
+
+## Ruling
+
+**One.** `test/pack.test.mjs` drives `node_modules/.bin/simt-dev`, installed from a tarball that
+`npm pack` produced from the working tree. Anything a reader of this repository only learns from
+the published package — that the registry resolves out of `node_modules`, that the decisions are
+present to read, that a full adoption survives a commit and a hook — is asserted here and nowhere
+else.
+
+**Two.** The install is `npm install --offline`. That is a constraint on this repository, not a
+setting: the package must install with no network and no warm cache, so `dependencies` and
+`devDependencies` stay empty and adding a build-time or test-time tool to either of them is a
+change to a guarantee rather than a convenience. A suite that fails on a cold runner gets
+skipped on one, and a skipped test and a passing test are the same line of output.
+
+**Three.** The pack test runs `npm pack` against the working tree rather than against a staged
+or committed tree. A mutation test has to be able to change a byte in `src/` and watch this file
+notice, and packing a commit would hide the change it is supposed to catch.
+
+**Four.** This file does not assert that the projected output is formatted, because there is no
+formatter to assert it with. S29's second acceptance half — a packed install whose output passes
+`format:check` — therefore stays open, and the seam it would have caught is asserted
+structurally instead, in `test/markers.test.mjs`. The record is here so that the open half is a
+decision rather than an oversight, and so that whoever makes Prettier reachable does not have to
+rediscover why this file stops where it stops.
+
+## Consequences
+
+Four mutations were made against the four rulings, each reverted immediately, and each was caught
+by the test that claims the behaviour:
+
+| Mutation | Caught by |
+| --- | --- |
+| `"graph"` removed from `package.json` `files` | `the registry the installed tool reads comes out of node_modules`, plus three others |
+| `"docs/decisions"` removed from `files` | `the decisions the tool explains itself with are in the tarball` |
+| `planGates` stops filtering by capability | `a repo that cannot run a gate is not told it has one` |
+| `upgrade` and `hooks install` write without `--yes` | `a packed install survives the whole adoption, and no writer writes unasked` |
+
+The first two are the S01 class and they shipped green for a long time. The third is S27. The
+fourth is ADR-035 and ADR-036, and it is in the list because `hooks install` was found by hand the
+day before, not by any of these tests.
+
+One thing this file deliberately does not assert, having been measured while writing it: the
+`files` list in `package.json` names four directories that do not exist in this repository —
+`skills`, `agents`, `tooling` and `hooks`. npm ignores them without complaint and the tarball is
+complete. An assertion that each entry exists would pass the moment the directories are created
+and say nothing in the meantime, so the fact is recorded here rather than encoded as a check.
+
+## Rejected
+
+**Running the installed binary out of a staged copy of `src/`.** It reproduces the checkout's
+bytes under a different path, which is precisely the state S01 shipped in. A test that cannot
+distinguish the two is worse than no test.
+
+**Adding Prettier as a devDependency so the formatting assertion can be written.** It would
+make the assertion possible and the suite unreliable: `npm install` would need the network on a
+cold runner, and ruling two exists because that is not a cost this repository pays. The
+correct fix is a formatter the suite can already reach, which is a decision somebody should make
+deliberately rather than a side effect of this one.
+
+**Skipping the pack test when `npm` is unavailable.** Every other test in the suite already needs
+node, git and a POSIX shell; npm is in the same class. A conditional skip converts a green run
+into an unverified one, which is the failure this file was written to stop.
+
+**Copying Prettier out of a sibling checkout.** It exists, it works, and ADR-031 rules it out for
+the same reason it rules out reading skill bodies from `../repo-14`: a suite that passes on
+the author's machine and fails on a runner with only this checkout is evidence about the author's
+directory.

simt_dev/vendored/docs/decisions/ADR-042-a-declared-glob-must-match-a-path-built-from-it.md

@@ -0,0 +1,94 @@
+# ADR-042 — A declared glob must match a path built from it
+
+Status: **accepted** · 2026-10-08 · ruling 1 superseded by ADR-053
+**Affects:** `src/resolve/resolve.mjs` and `graph lint`.
+
+## Context
+
+`matchesGlob` rewrote one shape of double star and left the rest to the JavaScript regex engine:
+
+```js
+.replace(/\/\*\*/g, '(?:/.*)?')
+```
+
+A glob that **started** with a double star compiled to an anchored pattern beginning `**`, which is
+not a valid regex. A `try`/`catch` returned `false`, so the failure was indistinguishable from the
+glob not matching — which is what a glob is for. 13 of the registry's 65 globs start that way
+(`**/*.test.ts`, `**/*.kt`, `**/build/**`, and ten more), and path is the heaviest signal the
+resolver has at weight 100. Every one of those skills was unreachable by a diff, and the only
+evidence was a staged `.spec.ts` file producing a selection that did not include the skill for
+writing tests.
+
+Two facts made this durable rather than a slip. The registry is hand-authored, so nothing compiles
+a glob until a real diff happens to contain a matching path. And `graph lint` — the check that
+exists to keep the registry describing reality — asked only whether a path array was **present**.
+`checkStack` had already established the principle one field over: a tag `fingerprint()` cannot emit
+matches nothing, forever, with no error at resolution time, so lint rejects it. A glob that matches
+nothing is the same failure wearing a different field name, and no check asked.
+
+Review 0001 §S02 diagnosed both halves and proposed the segment-by-segment translation. Review 0002
+§4.1 noted that with a raised Node floor this becomes `path.matchesGlob`, which is one line instead
+of twenty. That floor is proposal P8 and S47, still queued; `engines.node` reads `>=20` today and
+using a built-in that needs `>=22.20` would have quietly broken the declared range. So the translation
+is hand-written here and becomes a one-liner when S47 lands.
+
+## Ruling
+
+**One.** A glob is translated segment by segment. A leading double star is any number of leading
+directories, a middle one is any number of middle ones, a trailing one is anything beneath, and a
+bare one is everything. `*` remains confined to a single segment, because that is what makes the
+double star worth translating rather than treating every star alike.
+
+**Two.** A glob that matches nothing is a lint error, not a zero. `graph lint` now builds paths from
+each declared glob and requires the glob to match every one of them. This is the same question the
+resolver asks, asked at authoring time by the only tool in this repository that sees the whole
+registry at once.
+
+**Three.** A check that reads the same generator it is validating cannot catch that generator
+misbehaving. The synthetic expansion is asserted in its own right — a glob claiming any depth must
+be shown a path at depth and a path not at depth — because the registry-wide test otherwise just
+checks fewer paths when the expansion is narrowed, and checks fewer without saying so.
+
+**Four.** `?` is escaped, not read as a single-character wildcard. Nothing in the registry uses it,
+and reading it as a quantifier made `src/a?.ts` match `.ts`. A glob the matcher cannot honour now
+fails ruling two loudly instead of matching the wrong paths.
+
+## Consequences
+
+| Mutation | Caught by |
+| --- | --- |
+| a leading double star translated as a trailing one | `** in each position is anchored the way a path segment is` |
+| the synthetic expansion narrowed to the empty case only | `a double star is expanded both ways, or the check above is a mirror` |
+| `checkGlobs` deleted | `lint: detects a path glob that matches nothing (S02)` |
+| the path signal dropped from `scoreSkill` | `a path signal now reaches the skills that declare a leading **` |
+
+The second mutation is the one worth reading twice. The registry-wide test passed with it — it reads
+the generator it is checking, so narrowing the generator narrows the test in step. Only the lint
+rule noticed, and only because a bare double star then expanded to nothing at all. Ruling three is
+the fix, and it exists because the obvious assertion was not enough.
+
+Measured end to end through the shipped binary: in a Node repo with one staged `src/other.spec.ts`,
+`complete-testing` now resolves with the reason `path:**/*.spec.ts`. Before this record it did not
+resolve at all. `graph lint` over the real registry reports 49 unique globs and 0 unreachable.
+
+## Rejected
+
+**Waiting for S47 and using `path.matchesGlob`.** It is the better implementation and it is one line.
+It is also unavailable under the `engines.node` this package currently declares, and a resolver fix
+that breaks a stated runtime range is a worse defect than the one it removes. When the floor moves,
+this file's ruling one collapses into that call and the rest stands unchanged.
+
+**Catching the bad glob at match time instead of lint time.** A `throw` in `matchesGlob` converts one
+silent zero into a loud crash for whoever happened to stage the right file first — a user, in a
+repository, with no pointer to the hand-authored registry field that caused it. The same fact is
+available to `graph lint`, where the remedy is a file and a line number.
+
+**Extending the glob language to cover brace and character-class patterns.** `matchesGlob` is called
+with `skill.paths` and nothing else; the registry declares no braces and no character classes, and
+every one added is a rule that must hold for every future glob with no second caller to check it
+against. Ruling four turns the gap into a lint error instead, which is the honest description of a
+field the matcher does not implement.
+
+**Testing only the translation, as review 0001's acceptance described.** Unit cases for leading,
+middle, trailing and bare double stars all pass while a declared glob nobody staged still matches
+nothing. The unit tests prove the function; the lint rule is what proves the data.

simt_dev/vendored/docs/decisions/ADR-043-a-keyword-is-a-phrase-and-two-letters-is-a-word.md

@@ -0,0 +1,90 @@
+# ADR-043 — A keyword is a phrase, and two letters is a word
+
+Status: **accepted** · 2026-10-08
+**Affects:** `src/resolve/resolve.mjs` and what `graph lint` rejects.
+
+## Context
+
+Review 0001 §S03, marked P1, reproduced exactly. Two independent filters in `scoreSkill` were
+between a task description and every skill it named.
+
+`tokenize` dropped tokens of length 2 or less. In this domain those are not noise: `d1`, `r2`, `kv`,
+`ci` and `ui` are the vocabulary, and the capability aliases `ui`, `r2`, `kv` and `d1` were dead for
+that reason alone. `tokenize("fix d1 migration")` returned `fix, migration` — the one word that
+identifies the change was removed from the sentence before anything read it.
+
+Keywords were then compared one task token at a time. A multi-word keyword could therefore never
+match, because no single token equals `"durable object"`. Thirteen of the registry's 232 unique
+keywords were unreachable, nine of them multi-word, and `durable object` — declared on
+`durable-objects`, `cloudflare` and `api-security-review` — was dead on all three. Review 0001 §4
+records the symptom: `skills find "durable object"` returned four matches and not one `keyword:`
+reason.
+
+`graph lint` reported the registry clean. It checked that `keywords` was non-empty, which a list of
+words the tokenizer discards satisfies.
+
+## Ruling
+
+**One.** The tokenizer keeps words of length 2. The floor was 3 and it was chosen as a noise filter
+in a domain where the two-letter words are the signal. Lowering it is only half a fix; the noise it
+admits is the subject of S04 and is measured below rather than absorbed here.
+
+**Two.** A declared keyword is matched as a contiguous phrase, not token by token. Adjacency is the
+whole of the rule, so there is no similarity and no model: `"durable storage object"` does not match
+`"durable object"` and `"a durable object"` does.
+
+**Three.** The `keyword:` reason quotes the declaration as written. `keyword:durable object` is a
+string a reader can look up in the registry; `keyword:durable` is a keyword nobody declared.
+
+**Four.** A keyword whose words the tokenizer all discards is a lint error. This is the same
+question `checkGlobs` asks of a path (ADR-042), added for the same reason: a hand-authored field
+costs nothing to declare, so only a check that speaks the resolver's language catches one nobody
+executed.
+
+## Consequences
+
+Both acceptance cases named in review 0001 §S03 are now asserted against the shipped binary rather
+than against a function's return value, because both are claims about what a reader sees:
+`skills find "durable object"` prints `keyword:durable object`, and `skills brief --task "d1
+migration"` prints `keyword:d1`.
+
+Five mutations, each reverted, each caught by the test that claims it:
+
+| Mutation | Caught by |
+| --- | --- |
+| the tokenizer floor put back to 3 | five tests, including both acceptance cases |
+| phrase matching reverted to token equality | `a multi-word keyword matches as a phrase`, plus `skills find` |
+| `hasPhrase` becomes a bag of words | `a phrase needs its words adjacent` |
+| `checkKeywords` deleted | `lint: detects a keyword no task can produce` |
+| the reason names a token rather than the declaration | both phrase tests, plus `skills find` |
+
+### The noise this admits, measured
+
+Keeping two-letter words lets six of them reach the summary signal: `an`, `in`, `on`, `of`, `so`, and
+`or`, which selects eleven skills on its own. That is real and it is S04's finding, which was filed
+against the old floor and is still open.
+
+The measurement that keeps this record honest is the other side of it: `the` selected eleven skills
+and `and` selected twenty-nine **before** this change. A `summary:` hit is weight 8, and any score
+above 0 selects, so the threshold was already low before a single stopword was admitted. S03 adds
+six offenders to a pre-existing problem rather than creating it, and the remedy is the one review
+0001 named — a stopword list and a minimum score — not a longer tokenizer floor. Restoring the floor
+to 3 would hide the problem by making `d1` disappear again.
+
+## Rejected
+
+**Restoring the length-3 floor and declaring the two-letter aliases dead instead.** It would leave the
+suite quieter and `d1` unselectable, which is the defect this record exists to end. The word is in
+the domain; the filter is what was wrong.
+
+**Matching multi-word keywords as an unordered bag of words.** Cheaper, and it matches
+`"durable storage object"`. It also makes `google-services.json` a keyword reachable by any task
+merely mentioning Google, which is not what the declaration means.
+
+**Tokenizing the task and then searching the joined string for the keyword.** Same adjacency, but it
+loses the `start` offset a phrase needs and re-tokenizes a task the caller already tokenized. The
+keyword is a phrase over the same token stream, so the check belongs on the stream.
+
+**Widening `tokenize` to keep single letters as well.** `c`, `x` and `r` appear in skill names as
+initialisms, and every one of them is a stopword or a typo in a task description. Two is the point
+below which a word stops being a word.