ci: gate skill cross-references and Standard document-version pins - #30
Merged
Conversation
Three of yesterday's four audit findings were cross-reference drift — a skill name, a §13 claim, a version pin — not rule drift. The description cap and reuse lint verify a skill in isolation; nothing verified that a skill still agrees with the catalogue and the Standard around it, so that class was invisible to CI by construction. .github/check-skill-refs.py adds two checks: 1. Skill references resolve. A skill id named in prose (`spacecraft-foo` in Markdown, @code{spacecraft-foo} in Texinfo) must exist as a skill directory. The Standard shipped for months naming spacecraft-accessibility when the skill had always been spacecraft-accessibility-support, and nothing complained because the failure is silent: a missing skill never loads, so work directed at it just proceeds without it. Offenders get a "did you mean" hint computed from the catalogue. 2. No document-version pins. "The Steelbore Standard v1.42 (§11, §12)" is stale the moment any unrelated section changes, and ambiguous besides — a reader cannot tell whether the version means the document or the clause. Clause pins are recognised and allowed ("last amended in v1.39", "introduced at", "retired at", …), because those only move when the section moves. Scoping decisions worth review: only spacecraft-/microsoft-/gnu- are treated as skill namespaces, since steelbore-* is the palette and theme slug namespace; three-component versions are exempt so the Dual-Mode CLI Standard (v1.0.0) is not caught by a rule about The Steelbore Standard; changelogs are exempt from both checks because a history legitimately names things that were later renamed; and `skill-refs: allow` suppresses a single line where neither rule fits. Wired into the lint job here, and into the Standard's CI in a companion PR — that job checks out Construct read-only (both repos are public, no token) and runs this same script against the .texi. The dependency direction is deliberate: the Standard cites the catalogue, so the Standard validates against it. That is the job that would have caught the original bug at its source. Running it turned up four more genuine drifts, all fixed here: - steelbore-color-palette/assets/steelbore.toml said "Six palettes" and pinned §11 at v1.35. There are nine palettes and 17 themes, and §11 was last amended at v1.39 — the header comment had been stale since Tokyo Night and the two Solarized fidelity palettes landed. - README.md's catalogue row repeated the same "six palettes ... 13 themes" and the v1.35 pin. - spacecraft-agentic-cli pinned §11 at v1.34. - The maintainer-local CLAUDE.md (gitignored, not in this diff) pinned v1.25 — nineteen releases behind. Rephrased to stop pinning at all, since the constitution skill carries the current version in its own masthead. Regression-tested against the two real defects: the exact Standard bug and the exact brand-guidelines pin both fail; a clause pin, a three-component CLI Standard version, and a valid skill reference all pass. Description cap, reuse lint, config validation, the new checker, and the full bundle drift sweep all pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
UnbreakableMJ
added a commit
to Spacecraft-Software/Standard
that referenced
this pull request
Aug 5, 2026
This document cites skills by id, but the catalogue lives in Construct, so nothing here could tell whether a cited skill exists. It shipped for months naming `spacecraft-accessibility` when the skill had always been `spacecraft-accessibility-support` (fixed in v1.44, #23) — silently, because a missing skill does not announce itself; it simply never loads, and §18 work directed at it proceeds without it. The new `skill-refs` job checks out Construct read-only — both repos are public, so no token and `persist-credentials: false` — and runs Construct's `.github/check-skill-refs.py` against the .texi and its .md companion. The dependency direction is deliberate: this document cites the catalogue, so this document validates against it. One implementation serves both repos rather than a copy drifting on each side, which is the same failure this job exists to prevent. `--no-version-check` is passed: the checker's second rule bans Standard document-version pins in skills, but this document's own masthead version is the one legitimate pin in the ecosystem. Companion to Spacecraft-Software/Construct#30, which adds the script and wires the same checks over the catalogue itself. That PR is merged, so the script is on Construct's main and this job can find it. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Why
Three of yesterday's four audit findings were cross-reference drift — a skill name, a §13 claim, a version pin — not rule drift. The description cap and
reuse lintverify a skill in isolation; nothing verified that a skill still agrees with the catalogue and the Standard around it. That entire class was invisible to CI by construction.The checks
.github/check-skill-refs.py:1. Skill references resolve. A skill id named in prose (
`spacecraft-foo`in Markdown,@code{spacecraft-foo}in Texinfo) must exist as a skill directory. The Standard shipped for months namingspacecraft-accessibilitywhen the skill had always beenspacecraft-accessibility-support— silently, because a missing skill never loads, so work directed at it just proceeds without it. Offenders get a did you mean hint computed from the catalogue.2. No document-version pins.
The Steelbore Standard v1.42 (§11, §12)is stale the moment any unrelated section changes, and ambiguous besides — a reader cannot tell whether the version means the document or the clause. Clause pins are recognised and allowed (last amended in v1.39,introduced at,retired at, …), because those only move when the section moves.Scoping decisions worth review
spacecraft-/microsoft-/gnu-count as skill namespaces —steelbore-*is the palette and theme slug namespace (steelbore-mono,steelbore-high-contrast), which are values, not directories.skill-refs: allowsuppresses a single line where neither rule fits.Cross-repo wiring
Wired into the
lintjob here, and into the Standard's CI in Spacecraft-Software/Standard#24 — that job checks out Construct read-only (both repos public, no token) and runs this same script against the.texi.The dependency direction is deliberate: the Standard cites the catalogue, so the Standard validates against it. That is the job that would have caught the original bug at its source, and one implementation serves both repos.
Running it found four more drifts, all fixed here
steelbore-color-palette/assets/steelbore.tomlREADME.mdcatalogue rowspacecraft-agentic-cliCLAUDE.md(gitignored, not in diff)The palette asset header had been stale since Tokyo Night and the two Solarized fidelity palettes landed at v1.39.
Regression-tested against the real defects
spacecraft-accessibilityin Texinfo)Standard v1.42 (§11 …))§11 — last amended in v1.39)v1.0.0Verification
Description cap,
reuse lint, config validation (309 files), the new checker, and the full bundle drift sweep all pass. Two skills' bundles rebuilt.🤖 Generated with Claude Code