docs: retire the META.md guidance ADR-0022 overruled, bump touched plugins

Why: ADR-0022 made `metadata.version` mandatory in SKILL.md frontmatter, but three documents still
instructed the opposite — that `version:`, `source:`, `references:` and `when:` belong in a separate
META.md. That recommendation was never implemented: META.md exists exactly once in this repo, inside
a vendored third-party research example, and all 39 skills now contradict it. A stale instruction
that outranks nothing is worse than no instruction, because an author following it undoes the ADR.

Implementation notes:
- Two LESSONS.md entries deleted outright — their entire payload was the rejected fix. Two kept and
  rewritten: the copy-fill entry loses only its META-TEMPLATE clause, and the `model:` entry keeps
  the provider-extension fact and the invocation-time boundary rule, which stand on their own.
- One factual error corrected in passing: the `extracted` slug entry claimed provenance is recorded
  in META.md. It lives in `references/sources.md` keyed by `source_keys:`, verified against
  validate-provenance.sh.
- Both docs/notes files gain `metadata.version` in their required-field lists. Deleting the stale
  paragraph while leaving those lists silent would have re-created the gap.
- `bin/write-docs` carried `metadata.version: "1.0"` — the only non-semver value in the corpus, and
  the result of relocating its old top-level `version:` without normalising it. Now `1.0.0`.
  ADR-0022 records the relocation it previously omitted, which issue #127 had asked it to decide.

Impact: patch bumps for the four plugins whose `.apm/` content changed — bin, git, gitea,
kyberforge. core and lint are untouched and stay put. Root apm.yml's `executables.allow` key and
marketplace package versions move in lockstep; the marketplace release version is unchanged.

Refs: #127
ADR: 0022
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:41 +00:00
parent 3811f5481b
commit a3e721e937
10 changed files with 38 additions and 40 deletions

View File

@@ -43,6 +43,13 @@ per-plugin choice.
- **The one outlier in the other direction, `git-commits`, keeps its existing value** (`0.1.3`) —
it already had real tracked history under the old conditional rule, and this decision does not
reset skills that were already compliant.
- **`bin/write-docs`'s top-level `version:` moves into `metadata:`, normalized to `1.0.0`.** It is
the one skill that carried a version outside the `metadata:` block, which is why the table above
counts `bin` as 0 — a top-level `version:` is not `metadata.version`, and nothing reads it. #127
raised it alongside the split because "does a skill carry a version" and "where does it live" are
the same question. Its value (`1.0`) is not semver and carries no more real history than the 27
unversioned skills, so it is relocated and reset to the same `1.0.0` seed rather than preserved
like `git-commits`'s tracked `0.1.3`.
- **`skill-frontmatter`'s pre-commit hook gains the check.** It already fails a SKILL.md missing
`name:` or `description:`; a missing `metadata.version` is now the same class of failure, not a
style nit an audit might or might not catch.
@@ -62,9 +69,10 @@ it discards real revision signal for no gain.
## Consequences
27 SKILL.md files gain `metadata.version: "1.0.0"`. `skill-author`'s `create.md` moves the field from
"Optional frontmatter" to the required list, citing this ADR. `skill-author`'s own SKILL.md drops the
"with `metadata.version` present" conditional in its bump-rule line, since presence is no longer in
question. `.pre-commit-config.yaml`'s `skill-frontmatter` hook is extended to require the field,
closing the gap #113 and #118 both named in the same audit pass: a stated rule with nothing enforcing
it drifts the same way an unstated one does.
27 SKILL.md files gain `metadata.version: "1.0.0"`, and a 28th — `bin/write-docs` — reaches the same
value by relocating its top-level `version: "1.0"` into `metadata:`. `skill-author`'s `create.md`
moves the field from "Optional frontmatter" to the required list, citing this ADR. `skill-author`'s
own SKILL.md drops the "with `metadata.version` present" conditional in its bump-rule line, since
presence is no longer in question. `.pre-commit-config.yaml`'s `skill-frontmatter` hook is extended
to require the field, closing the gap #113 and #118 both named in the same audit pass: a stated rule
with nothing enforcing it drifts the same way an unstated one does.