Skip to content

feat(ci): enforce skill identity and version rules (3/4) - #128

Draft
miscreantmoogly wants to merge 3 commits into
validate-skills/2-packagefrom
validate-skills/3-versions
Draft

miscreantmoogly wants to merge 3 commits into
validate-skills/2-packagefrom
validate-skills/3-versions

Conversation

@miscreantmoogly

@miscreantmoogly miscreantmoogly commented Oct 8, 2026 •

Copy link
Copy Markdown

Stacked PR 3 of 4. Based on #127; review and merge in order. This diff shows only this PR's changes.

Description

With --base-ref, each skill is compared with its merge-base copy.

Identity:

  • A skill folder can't be removed or renamed; deprecate it instead.
  • Emergency removal. For malicious content or a legal or security request, a folder may be deleted when the same PR lists the skill in skill-rules/removed-skills.json, with a reason, the approving maintainer and the date. A listed skill's folder must be gone.
  • A path removed earlier in main's first-parent history can't be reused. Today that's eks-operation-review.

Versions:

  • A change to any published file needs a higher metadata.version. A published version is immutable.
  • The version goes up one step at a time: from 3.4.0 to 3.4.1, 3.5.0 or 4.0.0, never 79.5.0. It never goes down.
  • A new skill starts at 1.0.0.
  • A bump without a CHANGELOG.md change is a warning.
  • A base copy still on a two-part version, such as 2.6, is compared as 2.6.0.

Content hash. SHA-256 over sorted <path>\0<file sha256>\n records of the published files. A golden fixture in conformance-cases.json pins it, so any other implementation can prove it computes the same hash.

Type of change

  • Documentation or infrastructure change

Testing

  • 130 tests pass. On throwaway repos they show:
    • removal and rename fail, and an emergency removal listed in removed-skills.json passes;
    • reusing a retired path fails, including a folder renamed away on main;
    • a path that only existed on a merged branch is not retired;
    • a content change without a bump fails, and passes once bumped;
    • the comparison uses the merge base, not the base tip;
    • a changed hash function stops the check through the golden fixture.
  • Conformance cases cover one-step bumps, skipped and far jumps, a new skill's first version, and emergency removal.
  • --base-ref origin/main: 34 skills, 0 errors. The two version fixes from feat(ci): validate skill frontmatter on pull requests (1/4) #126 are single steps.

@ams-thakkar

Copy link
Copy Markdown
Contributor

Holding this one, and #125 likewise: @aadimch and @miscreantmoogly have each built the same check independently, and the two are not compatible as they stand — most pointedly, metadata.deprecated is specified oppositely (quoted "true" here, unquoted true in #125), and each documents its own form in CONTRIBUTING.md.

I have asked the two of you to agree on which set to keep.

With --base-ref, each skill is compared with its merge-base copy. A skill
folder can't be removed or renamed, and a path removed earlier in main's
first-parent history can't be reused. A change to any published file needs a
higher metadata.version, the version never goes down, and a bump without a
CHANGELOG.md change is a warning.

The content hash is SHA-256 over sorted <path>NUL<file sha256>LF records of
the published files, pinned by a golden fixture in conformance-cases.json that any
other implementation can share. History cases join the conformance corpus.
git log reports a rename as R, not D, so --diff-filter=D missed a folder
renamed on main and a later pull request could reuse its path. Turn rename
detection off for the retired-path scan.
A version now goes up one step at a time, to the next patch, minor or major
release, so a typo can't jump a skill to a version that can never come
down. A new skill starts at 1.0.0. README.md is no longer published, so a
README-only change needs no bump.

A skill folder may be deleted only in an emergency: the pull request also
lists the skill in skill-rules/removed-skills.json with a reason, the
approving maintainer and a date. A listed skill's folder must be gone, and
its path stays retired.
@miscreantmoogly
miscreantmoogly force-pushed the validate-skills/3-versions branch from c58bf3a to 1a2191f Compare October 9, 2026 17:35
@miscreantmoogly
miscreantmoogly added this pull request to stack #134 October 9, 2026 20:09

This branch has not been deployed

No deployments
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.

2 participants