chore: re-vendor the description-cap gate at v2.2.1, and drop dead cross-references - #22
Merged
Merged
Conversation
The vendored copy's header claimed "at v2.2.0" and pointed at an upstream state a reviewer could not obtain: at the time it was written, scripts/check_skill_descriptions.py did not exist on context-police main at all, the v2.2.0 code lived only on the open, unmerged PR #6, and the local copy additionally carried a fix that was sitting UNCOMMITTED in upstream's working tree. Three separate surfaces overstated that provenance, and the file's own docstring told the next contributor to "re-vendor from upstream" -- which would have silently reverted the fix and turned CI red. All of that is resolved by the same act: #6 merged as eedad0f, so the fix is now on upstream main and this is a plain re-vendor from a public commit. The code here was already byte-identical to v2.2.1 (this repo had taken the working-tree fix early); what was stale was the note. The new header is machine-strippable (--8<-- markers) so a parity digest can be pinned mechanically rather than grepped for, and it records what a version number here does and does not mean: 2.2.0/2.2.1 are context-police plugin.json/marketplace versions, NOT git tags. Upstream's newest tag is v2.0.0. upstream commit eedad0f upstream sha256 f210ccd2feb4a3f76289e078bdc5621919ca657026f3d86cc5d7cb1201985fb0 NOTE, since the handoff for this workstream states otherwise: the cap arithmetic did NOT change between v2.2.0 and v2.2.1. `desc_chars - (MAX_DESC_CHARS - 1)` was already in 4dc1a62. The only behavioural delta is find_wrap_corruption(), which no longer reports a bogus BROKEN BY LINE-WRAP on skills written `description: >-`. So no "N chars discarded" figure in this repo moves, and no version bump is warranted -- nothing under a plugin source dir changed. Verified: 38 SKILL.md (25 model-invocable, 13 disabled), gate exit 0 in both the text and --json forms.
Every backticked kebab-case identifier in a See-also / References / Sister-skills
bullet was resolved against every SKILL.md reachable on this machine --
~/.claude/plugins/cache, ~/.claude/skills, and every repo under ~/Documents (475
distinct skill names). The ones below matched nothing anywhere: they point at
sibling skills that were never published, so a reader following them finds
nothing and cannot tell whether the skill is missing or they are.
Deliberately conservative, because the obvious sweep is wrong:
- Scoped to an explicitly vetted list of 32 identifiers, each re-confirmed to
resolve nowhere immediately before deletion -- not to whatever a regex
happened to flag. A first pass keyed on "looks like a skill name" also
deleted bullets containing `the-project-repo` and `the-dashboard-service`,
which are a repo and a Cloud Run service. That pass was thrown away.
- Scoped to cross-reference sections only. In ## Notes and ## Worked example
the bullet is substantive prose that happens to name a skill; deleting it
would remove content, not a pointer. Those are left alone.
- Bullets naming BOTH a live and a dead skill keep the bullet and lose only
the dead name -- e.g. `data-provenance-verifier` survives where
`verify-plan-constants-against-data` beside it did not.
Frontmatter is never touched: 0 descriptions changed, so no plugin version bump
is needed and no cap/coverage figure moves.
Verified: gate exit 0 in both the text and --json forms, no BROKEN BY LINE-WRAP.
wan-huiyan
added a commit
that referenced
this pull request
Aug 5, 2026
…ipped (#24) PR #22 removed 12 dead cross-references from six SKILL.md files under plugins/ -- shipped files -- and bumped nothing. Its own commit body says: "0 descriptions changed, so no version bump and no cap/coverage figure moves." "The gate here is CI-only (not under a plugin source dir), so no version bump." The first sentence is true and irrelevant; the second is false for that commit. No *description* changed, but six shipped SKILL.md bodies did, across three plugins. `claude plugin update` compares versions, saw equal, and did nothing. Verified against the installed copies before writing this: observational-analysis-rigor 1.2.1 4 files still carry the dead refs overnight-multi-issue-implementation 1.2.1 1 file still carries them overnight-review-panel-blocked-reviewer-reads-as-clean 1.0.0 2 files still carry them diff repo/plugins/overnight-multi-issue-implementation/SKILL.md cache/.../overnight-multi-issue-implementation/1.2.1/SKILL.md -> differ So 12 of this session's 32 cross-reference removals are fixed on main and still live for an installed user. This is the exact failure recorded as "THE LESSON THAT ALMOST COST THE WHOLE THING" in the workstream handoff -- a fix with no version bump is undeliverable -- committed by the session that was cleaning up after it. The live-install gate did not catch it and could not: it measures cap and corruption, not repo-vs-install parity. Neither does anything else. observational-analysis-rigor 1.2.1 -> 1.2.2 overnight-multi-issue-implementation 1.2.1 -> 1.2.2 overnight-review-panel-blocked-reviewer-reads-as-clean 1.0.0 -> 1.0.1 No content change in this commit -- versions only, so the already-merged edits can actually reach an install. Gate exit 0; all 8 marketplace entries agree with their plugin.json. Worth a follow-up: a check that every commit touching `plugins/**` also touches that plugin's version, which is the only thing that would have caught this.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
1. Re-vendored the description-cap gate at context-police v2.2.1
The vendored copy's header claimed "at v2.2.0" and pointed at an upstream state a reviewer could not obtain. At the time it was written:
scripts/check_skill_descriptions.pydid not exist on context-policemainat allThree surfaces overstated that provenance, and the file's own docstring told the next contributor to "re-vendor from upstream" — which would have silently reverted the fix and turned CI red.
All of it is resolved by the same act: #6 merged as
eedad0f, so this is now a plain re-vendor from a public commit. The code here was already byte-identical to v2.2.1 (this repo took the working-tree fix early); what was stale was the note.The new header is machine-strippable (
--8<--markers) so a parity digest can be pinned mechanically rather than grepped for, and it records that2.2.0/2.2.1are context-police plugin versions, not git tags — upstream's newest tag isv2.0.0.No version bump: nothing under a plugin source dir changed.
2. Dangling cross-references (second commit)
Every backticked identifier in a See-also / References / Sister-skills bullet was resolved against all 475 skill names reachable on this machine. Dead pointers to never-published siblings are removed.
Deliberately conservative:
the-project-repoandthe-dashboard-service— a repo and a Cloud Run service. That pass was thrown away.## Notesbullets are prose, not pointers.data-provenance-verifiersurvives whereverify-plan-constants-against-databeside it did not.0 descriptions changed, so no version bump and no cap/coverage figure moves.
Checks
38 SKILL.md (25 model-invocable, 13 disabled) · gate exit 0 in both text and
--json🤖 Generated with Claude Code