docs(skill): the skill drifted behind the engine in the commit that banned it

v0.10.0 canonized "a new check is not shipped until its row exists" and
shipped with SKILL.md still saying "the two network calls" — after the
third had been added — and with no mention of VERIFY-COMMAND at all. The
invariant was violated one file over, in the same commit that wrote it.

Three corrections, and one is a trap worth naming: the remedy for
VERIFY-MISSING is to document the command that already exists, after
running it. Writing `npm test` into a README because the finding
mentioned it, with no scripts.test behind it, turns a WARN about missing
documentation into a false claim on the first screen — a worse defect
than the one being fixed, and one this gate can never catch, because it
runs nothing. VERIFY-NONE needs no action at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LwZeAZ8cHmGZofM9dryuT9
This commit is contained in:
Kjell Tore Guttormsen 2026-08-12 23:28:06 +02:00
commit 009c911f9e

View file

@ -26,9 +26,11 @@ the script cannot encode.
node "${CLAUDE_PLUGIN_ROOT}/scripts/repo-standard-check.mjs" --dir "$PWD"
Findings are `ERROR` (blocks), `WARN` (look, then decide), `SKIP` (not judged —
in one of two ways, see below), `OK`. Exit 1 on any ERROR. Add `--offline` to skip the two
network calls, `--json` for machine output, `--refresh` to compare the bundled
register against the live org listing.
in one of two ways, see below), `OK`. Exit 1 on any ERROR. Add `--offline` to skip the three
API calls — the org listing, the catalog manifest, and the repo's releases —
`--json` for machine output, `--refresh` to compare the bundled register against
the live org listing. Refs are read over the git protocol instead and cost
nothing against that budget.
**Never report a `SKIP` as a pass.** A SKIP means the gate did not judge the
thing. Say which, and say which KIND — since 0.8.0 there are two, and they are
@ -45,7 +47,8 @@ not interchangeable:
The inverse error is reporting an `OK` as an un-run check. A check that ran and
found **no subject** is a verdict, not a skip: `VERSION-NONE` ("no version
claimed anywhere") and `LANGUAGE` ("no running prose to judge") are `OK` and
claimed anywhere"), `VERIFY-NONE` ("nothing runnable, so no verification command
is owed") and `LANGUAGE` ("no running prose to judge") are `OK` and
carry no action. `VERSION-NONE` was `VERSION-UNAVAILABLE`/`notRun` before 0.9.0
— if you see the old code, the engine is stale; see the version note below.
@ -156,6 +159,22 @@ command that runs the whole suite from a clean clone, stated in the README along
with the fact that nothing runs it automatically. Verifiability is the goal; CI
is one mechanism for it, and it is not available here.
Since 0.10.0 that substitute is measured rather than assumed. `VERIFY-MISSING`
(`WARN`) means the repository has something runnable — a `scripts.test` entry, or
tracked executable test files — and its README shows no command in a code block.
Fixing it has exactly one honest move: **document the command that already
exists, after running it yourself.** Writing `npm test` into a README because
the finding mentioned it, without a `scripts.test` to back it, converts a `WARN`
about missing documentation into a false claim on the first screen — a worse
defect than the one you were sent to fix, and one this gate cannot catch,
because it never runs anything. A green `VERIFY-COMMAND` means *documented*,
never *passing*.
`VERIFY-NONE` needs no action at all. A repository of prose, output styles or
domain packs owes no command, and adding a hollow test script to clear a finding
that was never against it is the anti-pattern in its purest form.
## Diagrams — capability is not justification
Mermaid renders in a README on this forge. That was verified on the live