Skip to content

feat: gate skill directories on README feature-list coverage - #257

Merged
randomparity merged 5 commits into
mainfrom
feat/readme-skill-check-238
Aug 26, 2026
Merged

feat: gate skill directories on README feature-list coverage#257
randomparity merged 5 commits into
mainfrom
feat/readme-skill-check-238

Conversation

@randomparity

Copy link
Copy Markdown
Owner

Closes #238

scripts/check-skill-shape.sh already had Rule 6, which asserts that every
skills/<name>/ directory is named in docs/cheatsheet.md as a
backtick-wrapped token. Nothing did the same for the README's feature list, so
a skill could be added, documented in the cheat sheet, and never reach the
README with no gate noticing.

What this adds

Rule 7: the same set-membership check, pointed at README.md.

It is deliberately the narrowest possible reading of the documents. For each
skill directory it asks one question — does that name appear in README.md as a
backtick-wrapped token — and nothing about wording, table shape, ordering or
grouping. Anatomy rule 4 forbids a gate that asserts on prose; a structural
check that resolves a directory name against a document is explicitly welcome,
and Rule 6 is the standing precedent this mirrors.

Error contract

Governed by docs/adr/0025-a-skip-reports-the-condition-not-the-cause.md
(Accepted 2026-08-19), the live head of the 0005 → 0024 → 0025 chain.

  • rg scan exits > 1fault, exit 2, naming the rule.
  • rg scan exits 1 (genuine absence) → report, exit 1, naming the skill and
    README.md.

A scan that could not run is never collapsed into "not found".

The gate passes on merge, and that is expected

All 28 current skill directories already appear in README.md, so Rule 7 goes
green immediately. That is not evidence the rule is inert — the defect it fixes
is that nothing would catch a future omission.

The distinction matters for the tests, so they do not inherit the same
blindness. scripts/check-skill-shape-test.sh builds synthetic
skill/README/cheatsheet trees to exercise the absent case directly, which is the
technique Rule 6's existing tests already use. New Case 27 covers the fault path
by shimming rg to remove the scratch list between Rule 6's scan and Rule 7's
re-open — the same shape as the existing Case 22, one loop later.

The tests were made to fail before they passed. The implementation was
stashed, the new cases run against the pre-Rule-7 script and observed to redden,
then the implementation restored and the cases observed to go green. One
intermediate false redden surfaced during that check — the first fixture tripped
Rule 6 rather than Rule 7 — and was corrected inside the fixture tree so only the
README gap is under test.

Non-user-facing skills

No exemption mechanism is included. No deliberately undocumented skill exists in
this repository today, and building configuration for a case that does not exist
is the speculative surface the repository's own instructions rule out. If such a
skill is ever added, the rule will report it and that report is the moment to
decide, with a real example in hand.

Verification

just verify run bare, exit 0, and just shape-check green standalone against
the real 28-skill tree. The managed pre-push hook re-ran the whole suite in its
isolated worktree on push, green.

The base-branch workflow runs this merge would trigger are not covered by that
evidence.

randomparity and others added 5 commits August 25, 2026 15:12
scripts/check-skill-shape.sh gains rule 7: every skills/<name>/ directory
must appear as a backtick-wrapped token in README.md, mirroring rule 6's
existing docs/cheatsheet.md check. A scan that cannot run faults (exit 2)
rather than reporting a false absence, per the fault/report contract ADR
0025 states as the live head of the 0005 -> 0024 -> 0025 chain.

scripts/check-skill-shape-test.sh gains fixture coverage for a skill
missing from README, one documented via prose only (proving membership,
not table position), and rule 7's own require_readable guard on a
scan-cannot-run fault.

Closes #238

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ck-238

# Conflicts:
#	.claude-plugin/plugin.json
…ck-238

# Conflicts:
#	.claude-plugin/plugin.json
…ck-238

# Conflicts:
#	.claude-plugin/plugin.json
…ck-238

# Conflicts:
#	.claude-plugin/plugin.json
@randomparity
randomparity merged commit cbbe280 into main Aug 26, 2026
6 checks passed
@randomparity
randomparity deleted the feat/readme-skill-check-238 branch August 26, 2026 15:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Nothing catches a skill that never reaches the README feature list or the cheat sheet

1 participant