fix(kyberforge): unblock the scaffold and finish the #125 and ADR-0022 edits

Three related half-applied changes from #130, each leaving the corpus in a state its own
documentation contradicts.

Why:
- `assets/templates/SKILL.md` shipped `metadata:` fully commented out, and `new-skill.sh` only
  substitutes SKILL_NAME. Every scaffolded skill therefore lacked the `metadata.version` ADR-0022
  made mandatory and was blocked at first commit by the very hook this PR added. The commented
  example also read `"1.0"` — neither the `0.1.0` new-skill seed nor valid semver.
- `agent-audit/references/scope-project-user.md` still joined `disable-model-invocation` and
  `user-invocable` with a slash — #125's defect verbatim — while pointing the reader at the file
  this PR had just corrected to say the opposite.
- ADR-0022 required the "when present" bump conditional dropped and `metadata.version` moved into
  create.md's required list. It was dropped from SKILL.md but left in README.md, and the field was
  edited in place under a heading that still authorises removing it entirely.

Implementation notes:
- The template emits `metadata: version: "0.1.0"` live, captioned as required, with the optional
  keys left commented. `new-skill.bats` gains a case asserting a live key and three-part semver, so
  this cannot regress.
- `description-quality.md` now asserts only what the vendored Copilot research supports: two fields
  with opposite defaults, and the retired `infer` replaced by the pair rather than by either alone.
  The unsupported negative it previously stated as fact is gone.
- The `1.0.0` retrofit seed is stated in improve.md and retrofit.md, which the retrofit flow
  actually reads — create.md, where it lived, is unreachable from that path. The compression item
  moved out of the file-churn checklist, whose preamble excluded the wording-only change it covers.
- Executable git commands in these three skills now carry the ADR-0023 rtk prefix.

Refs: #125, #127
ADR: 0022, 0023
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
This commit is contained in:
2026-09-09 05:15:23 +00:00
parent 175ea89c0a
commit 3811f5481b
11 changed files with 81 additions and 32 deletions

View File

@@ -105,16 +105,37 @@ them for you. After every retrofit that adds, removes or renames a file:
zero.
- [ ] Re-run `/skill-audit` and confirm its `### Provenance` dimension does not report the new
file as missing `source_keys`.
- [ ] **Compression must not add authority the source text didn't have.** The bullet above is
about a `sources.md` entry going *stale* — Contributing files left uncited after content
moves. This is a distinct failure: a compression or rewrite pass that upgrades an honest
hedge in a Description into an unsupported confident claim, without the underlying source
having changed at all — "no forge-specific content drawn directly from it beyond that"
quietly becoming "Grounds Step 2's dispatch table." Nothing in `/skill-audit`'s structural
checks catches this; a bash script can verify an entry is internally consistent, never
whether the claim is *true*. If a retrofit strengthens or otherwise changes the wording of a
provenance claim, re-read the upstream research doc first and confirm the stronger wording
is actually still true before committing it.
## Compression must not add authority the source text didn't have
This one is **not** part of the checklist above, and deliberately so: it fires on a wording change
with no file change at all, so a retrofit that adds and removes nothing still owes it.
The `sources.md` bullet above is about an entry going *stale* — Contributing files left uncited
after content moves. This is a distinct failure: a compression or rewrite pass that upgrades an
honest hedge in a Description into an unsupported confident claim, without the underlying source
having changed at all — "no forge-specific content drawn directly from it beyond that" quietly
becoming "Grounds Step 2's dispatch table."
`/skill-audit`'s provenance script does now notice this class: it diffs each slug's `Description`
and `Contributing files` text against a base ref and raises an **INFO** when the wording changed.
That is a prompt, not a verdict — it reports only *that* the claim moved, never whether the new
claim is true, because a bash script can verify an entry is internally consistent and nothing more.
Answering it is this flow's job: if a retrofit strengthens or otherwise changes the wording of a
provenance claim, re-read the upstream research doc first and confirm the stronger wording is
actually still true before committing it.
## Versioning a retrofitted skill
`SKILL.md` Step 4 says to bump the **patch** version on improve, which presumes there is a version
to bump. A pre-ADR-0020 skill often carries none — `metadata.version` only became mandatory under
ADR-0022, and this flow is exactly where those skills surface.
A skill with no `metadata.version` is **seeded at `"1.0.0"`, not bumped**. `"0.1.0"` is reserved
for a skill created new by the create flow: it means "created and never yet revised", which
understates a skill that has been through retrofit and audit passes without tracking a version.
Add the field in this retrofit — the `skill-frontmatter` pre-commit hook blocks the commit without
it.
## Worked example — a description retrofit