self-verify: catch a dead eager @-include #99

New issue

Closed

opened 2026-08-10 14:49:00 +00:00 by john · 1 comment

john commented

2026-08-10 14:49:00 +00:00

Owner

Problem

skills/cad-verify/SKILL.md:29 eagerly @-includes cadence-core/templates/UAT.md — 5,792 B on turn one and every turn after — and nothing ever reads it. verify.md never names the template; all eight of its "UAT.md" mentions are the runtime artifact .planning/phases/<N>/UAT.md.

That is a class, not an incident. An @-included surface that nothing in the including skill's reachable prose ever names is mechanically detectable, and right now nothing would catch the next one. CHANGELOG.md:475 shows this particular include was actively justified at a point when it was already dead, so the failure mode is not "someone forgot" — it is "the claim was never checkable".

Change

Add a self-verify check: for every @${CLAUDE_PLUGIN_ROOT}/<path> include in a skills/*/SKILL.md, the included surface must be named by something in that command's reachable prose (the SKILL.md itself or the workflow it includes), or carry an explicit stated exemption.

Same species as check 3 (paths exist) and check 6 (agent skills: resolve): the include claims a consumer, and this checks the claim.

Design notes

The resident-weight.mjs eager/reachable split already computes the file set this needs; reuse it rather than re-walking.
Distinguish "included but never named" (this check) from "named but no longer included" (check 13's register). They are opposite directions and both need to hold.
Beware the file whose workflow IS the surface: cad-help's workflow is COMMANDS.md, which is the legitimate shape the dead UAT include was wrongly compared to. That case must pass.

Acceptance

The check fires on skills/cad-verify/SKILL.md:29 before #3 lands, and is silent after.
cad-help's COMMANDS.md include passes.
node cadence-core/bin/self-verify.mjs returns ok:true on a clean tree.

## Problem `skills/cad-verify/SKILL.md:29` eagerly `@`-includes `cadence-core/templates/UAT.md` — 5,792 B on turn one and every turn after — and nothing ever reads it. `verify.md` never names the template; all eight of its "UAT.md" mentions are the runtime artifact `.planning/phases/<N>/UAT.md`. That is a class, not an incident. An `@`-included surface that nothing in the including skill's reachable prose ever names is mechanically detectable, and right now nothing would catch the next one. `CHANGELOG.md:475` shows this particular include was actively justified at a point when it was already dead, so the failure mode is not "someone forgot" — it is "the claim was never checkable". ## Change Add a self-verify check: for every `@${CLAUDE_PLUGIN_ROOT}/<path>` include in a `skills/*/SKILL.md`, the included surface must be named by something in that command's reachable prose (the SKILL.md itself or the workflow it includes), or carry an explicit stated exemption. Same species as check 3 (paths exist) and check 6 (agent `skills:` resolve): the include claims a consumer, and this checks the claim. ## Design notes - The `resident-weight.mjs` eager/reachable split already computes the file set this needs; reuse it rather than re-walking. - Distinguish "included but never named" (this check) from "named but no longer included" (check 13's register). They are opposite directions and both need to hold. - Beware the file whose workflow IS the surface: `cad-help`'s workflow is `COMMANDS.md`, which is the legitimate shape the dead UAT include was wrongly compared to. That case must pass. ## Acceptance - The check fires on `skills/cad-verify/SKILL.md:29` before #3 lands, and is silent after. - `cad-help`'s COMMANDS.md include passes. - `node cadence-core/bin/self-verify.mjs` returns `ok:true` on a clean tree.

john added this to the v2.6.2 milestone

2026-08-10 14:49:00 +00:00

john commented

2026-08-12 15:10:39 +00:00

Author

Owner

Shipped as the include-consumers self-verify check (lib/include-consumers.mjs + include-consumers.test.mjs, waiver register included). Fires on a dead eager include, silent on cad-help's COMMANDS.md shape.

john closed this issue

2026-08-12 15:10:39 +00:00

john referenced this issue

2026-08-12 15:10:40 +00:00

cad-verify: delete the dead templates/UAT.md eager include (-5,792 B) #100