simt-dev 0.0.0-stage → 0.1.0

package/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.

package/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.

package/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 `../simt-blog/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 `../simt-social`: 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.

package/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.

package/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.

package/docs/decisions/ADR-044-compatibility-is-not-evidence.md

@@ -0,0 +1,116 @@
+# ADR-044 — Compatibility is not evidence, and a resolver nobody measured is merely felt
+
+Status: **accepted** · 2026-10-08 · affects what `skills brief` and `skills find` return
+
+## Context
+
+Review 0001 §S04, marked P1, reproduced exactly through the shipped binary. Two facts, both
+measured in a Workers fixture before anything was changed:
+
+- `skills brief --task "fix d1 migration"` resolved 29 914 bytes against a 20 480-byte budget and
+  reported `(budget capped)`. The tail was `complete-testing` and `slice-commit`, selected on
+  `stack:node+cloudflare-workers` alone.
+- `skills brief --task "fix a typo in the README"` resolved four skills, every one of them on
+  `summary:the` or `summary:in`, and filled the budget with bodies about launch galaxies.
+
+The mechanism is one line. Stack overlap is 15 a tag, any score above zero selects, and the stack
+gate already ran. Compatibility is a **precondition**, so a score made of nothing but compatibility is
+not a weak match — it is no match, reported as one. Meanwhile `summary` is weight 8 and clears a
+threshold of zero, so a word of shared English was enough to select anything.
+
+The review asked for three things: make stack a tiebreaker, add a stopword list with a minimum score
+of 25, and add a gold corpus. It also noted that plan 0002 §11 step 5 claims an `eval` corpus
+"passes" and is marked **done**. There is no `skills eval` command and there was no corpus. Every
+ranking change in this repository had been argued from examples.
+
+## Ruling
+
+**One.** A score may select only with evidence. `scoreSkill` returns `evidence` — the score without
+its stack contribution — and the threshold is applied to that, never to the total. Both halves matter:
+stack is 15 a tag, so a repo matching three of a skill's tags is 45 on its own, and a threshold that
+counted stack would wave it through.
+
+**Two.** `MIN_SCORE` is `W.capability`, 25. Below it the only available signals are `summary` at 8 and
+`stack` at 15, and neither is a statement about the task. "Only a capability-strength signal or better
+selects" is the rule the review states and the number it gives.
+
+**Three.** Stopwords are suppressed in the summary signal only. A keyword is an explicit declaration
+and a name is an identity, so hiding those would suppress something a person wrote on purpose; a
+summary is prose, and prose carries words that are there for grammar. `do not push` is a declared
+keyword and stays reachable.
+
+**Four.** The rejection says why. `NOT SELECTED` is the block an agent uses to override, so a
+rejection that cannot be acted on is the same defect as a bad selection.
+
+**Five.** One place decides, and three commands call it: `rankSkills`, `skills find`, and the MCP
+`skills_find` tool. They each ranked on `score > 0` independently, and an assertion that one of them
+kept that rule would have passed the entire suite — see the fourth mutation below.
+
+## Consequences
+
+The two acceptance cases in review 0001 §S04 now hold, and both are asserted against the shipped
+binary: `fix d1 migration` selects `d1-safe-change` and not `api-contract-sync`, and a task of
+stopwords resolves nothing and says why. The budget no longer caps on either.
+
+The gold corpus is `test/fixtures/eval-corpus.json`, ten cases across four ecosystems, run by
+`test/eval.test.mjs`. It states `select` (must return) and `reject` (must not), and asserts that
+every skill it names still exists in the registry — a corpus citing a renamed skill otherwise passes
+by comparing two lists that no longer overlap.
+
+Five mutations, each reverted, each caught by the test that claims it:
+
+| Mutation | Caught by |
+| --- | --- |
+| the minimum score dropped | two corpus cases, the weak-signal test, and the shipped-binary test |
+| stack counted toward the threshold again | two corpus cases and the weak-signal test |
+| stopwords not applied to the summary signal | both stopword tests |
+| `skills find` reverted to `score > 0` | **nothing** — see below |
+| the stopword list emptied | both stopword tests |
+
+The fourth is the one worth keeping. Reverting `skills find` to its own weaker rule passed all 621
+tests at the time, because it was the third command to be moved and no test covered the third. It is
+ADR-035's lesson exactly: a promise about a set of commands is only true while something checks the
+set. The test that now catches it queries `secrets`, chosen because that word lands strictly between
+0 and `MIN_SCORE` for exactly one skill (`wrangler`, at 8 via its summary), so the two rules give
+visibly different answers — 3 matches against 4.
+
+The first version of the precision metric was also wrong and was caught by the corpus itself. It
+scored precision against `select + reject`, so a case where the resolver selected a skill neither
+list named scored a perfect 1.0. That is not precision, it is agreement with whatever was written
+down. Precision is now measured two ways and both must hold: every named negative stays unselected,
+and every case whose answer is "nothing" returns nothing at all.
+
+### What the corpus found that the review did not predict
+
+The `regenerate the openapi contract` case failed on the first run, against my own expectation: I had
+written that `web-feature-slice` and `api-feature-slice` should not be selected. The resolver was
+right and the corpus was wrong. `web-feature-slice` and `add-country-galaxy` both declare capability
+`contract`, and `api-feature-slice` declares keyword `openapi` — so each carries a capability-strength
+signal, which is exactly what ruling two admits. A hand-authored gold set is an opinion written down,
+and this one had been written without checking the registry.
+
+That leaves a real question this record does not answer: whether `contract` is the right capability
+for a skill that registers a country. Changing `graph/skills.graph.json` changes
+`provenanceDigest()`, which stamps every consumer repository, so the answer is not a question this
+slice may decide by editing one line of data.
+
+## Rejected
+
+**Making the minimum score a `--min-score` flag.** It would let a user recover the old behaviour and
+it would put the default in a place nobody reads. The old behaviour is not a preference some
+repositories want; it is the reason `NOT SELECTED` was empty and the budget was full of bodies.
+
+**Thresholding on the total score instead of on evidence.** Simpler, and wrong: it fails for exactly
+the repos this tool serves. A repo matching three tags is the common case, not the edge.
+
+**Removing the stack signal from the score entirely.** It orders candidates, which is a tiebreaker's
+job, and removing it would make two equally-evidenced skills order by name alone.
+
+**Putting the corpus under `graph/`, beside the registry.** `provenanceDigest()` walks `rules/` and
+`graph/`, so a corpus file there changes the content digest and forces every consumer repository to
+be restamped. A test corpus is not worth a migration, and the digest would move invisibly.
+
+**Building the `skills eval` command this record could have built.** Plan 0002 §9 lists it. It is a
+new product surface with its own flags, JSON contract and help text, and its absence is a defect in
+the plan rather than in the tool. The corpus and the runner are what S04 asked for; the command is
+recorded below as still owed.