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:
parent
e00ed3340c
commit
009c911f9e
1 changed files with 23 additions and 4 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue