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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user