[lukemaj]

What: npm test now fails when package.json, .claude-plugin/plugin.json, the CHANGELOG.md heading and a v* tag on the commit disagree on the version, or when docs/, case-studies/, skills/ or examples/ change without a CHANGELOG.md change. CHANGELOG.md starts at 0.2.0 with tonight's cleanup.
Why: The version lived in two files with no check that they matched or matched a tag, and nothing recorded what changed for readers.
So what: Luna max review of this head, then the user merges. Tagging v0.2.0 stays with the user (a tag is a release artifact).

Closes #22
Refs #7

Changes

• scripts/check-version-sync.sh: package.json and .claude-plugin/plugin.json must match, CHANGELOG.md must have a ## [X.Y.Z] heading for that version, and every v* tag on HEAD must equal vX.Y.Z. Each failure prints a Fix: line.
• scripts/check-changelog-updated.sh: diffs the working tree against the merge base with origin/$GITHUB_BASE_REF (CI) or origin/main; a reader-visible path without CHANGELOG.md fails. A missing base fails with a fetch fix instead of passing.
• scripts/bump-version.sh X.Y.Z: sets package.json, package-lock.json (via npm version --no-git-tag-version) and plugin.json, then prints the tag command.
• tests/check-version-and-changelog.test.sh: runs both gates on the tree, then self-tests them on a fixture repo (10 cases: mismatch, missing changelog heading, matching and disagreeing tags, untracked, uncommitted and committed docs changes with and without a changelog change, non-reader change, missing base). Failure cases must print a Fix: line.
• .github/workflows/test.yml: fetch-depth: 0 (full history and tags, so the merge base and tags exist in CI's checkout) and runs on v* tag pushes, where the tag check matters.
• AGENTS.md: bump rule (MAJOR / MINOR / PATCH from the drift draft's section 6) and tag step under "Versions and changelog"; Proof lists the new checks; Gate version anchors and CHANGELOG entries in npm test #22 removed from the planned-work list.
• README.md: Make the README, overview, AGENTS.md and loader Skill state the current scope and route by action #14's follow-up. After State the measured activation behavior in the quickstart, mental model, three questions and token economics #12 (merged in docs: activation and budget pages match measured behavior (#12) #28), page 03 names each host's description-listing limit and page 04 covers per-host listing limits and pointer-versus-full-body injection. The README's Question 3 said "the description listing budget" and page 04's blurb said "how SessionStart-hook injection cost compounds"; both now match. Pages 01 and 02 blurbs already matched. Contributing points at CHANGELOG.md.
• CHANGELOG.md: 0.2.0 covers Case study: the AgentsMD routing benchmarks (toolboxmd/agentsmd#164, #174, #182) #6, Correct triggers.md and add the trigger-benchmark method #5, Correct the harness facts for Claude Code, Codex, Grok Build, OpenCode and Gemini CLI #8, Fix wrong facts and undefined sources in the evolution, frontmatter, line-budget and iron-laws pages #9, Make the doc checks run: link check, llms.txt freshness and CI #10, Move TODO.md, the drift-prevention draft and the continuous-learning handoff into Issues #11, State the measured activation behavior in the quickstart, mental model, three questions and token economics #12, Add the routing and harness failure modes to the anti-pattern catalog and the mechanism page #13, Make the README, overview, AGENTS.md and loader Skill state the current scope and route by action #14 and Tool descriptions are activation contracts; deferred loading hides them #4 from their merged PRs (docs: case study of the AgentsMD routing benchmarks (#6) #24, docs: correct triggers.md and add the trigger-benchmark method (#5) #26, docs: correct harness facts for Claude Code, Codex, Grok Build, OpenCode and Gemini CLI (#8) #25, docs: fix wrong facts and undefined sources in four doctrine pages (#9) #16, test: doc link check, llms.txt freshness and CI (#10) #15, Mark the continuous-learning handoff superseded by #18 #23, docs: activation and budget pages match measured behavior (#12) #28, docs: routing and harness anti-patterns and reword-first evidence (#13) #27, docs: state current scope and route the loader Skill by action (#14) #29, docs: tool descriptions are activation contracts; deferred loading hides them (#4) #31). This PR's own changes sit under [Unreleased].

versionctl versus a script

Chose three small scripts over AgentsMD versionctl. versionctl needs a root VERSION file, Python 3.11 and its own code in this repo or fetched in CI (tools/versionctl/README.md at toolboxmd/agentsmd a14d823); it lives in another repository, so CI here would have to vendor or clone it. It does not check that a reader-visible change touched CHANGELOG.md, the gate this Issue needs most. The scripts need only Node and Git, which CI already has. Recorded on #22.

Proof

• npm ci && npm test under Node v22.23.1 at this head: exit 0; OK: build-llms, OK: check-docs-links, OK: check-llms-coverage, OK: check-version-and-changelog, all other scripts pass.
• Each fixture failure case fails and prints Fix:; each pass case passes (output in the test).
• bash scripts/bump-version.sh 0.2.0 on the tree leaves every file unchanged.
• CI on this PR: pending at time of writing.

Elon record

• Requirements and who asked: user, 2026-05-06 drift draft G1-G2 (version anchors agree, changelog required for doc changes); Gate version anchors and CHANGELOG entries in npm test #22 acceptance criteria; planner, 2026-09-29: seed 0.2.0 with the cleanup and fold in Make the README, overview, AGENTS.md and loader Skill state the current scope and route by action #14's README follow-up.
• Deleted: versionctl adoption and a VERSION file; major/minor/patch arithmetic in the bump script (the author picks the level); the draft's root CLAUDE.md and Recent Changes cap; a package-lock.json check (npm writes it with package.json); past-version tags.
• Bottleneck: nothing checked the two version files, and CI's shallow checkout had no base or tags to check against.
• Checked myself: ran npm test and every fixture case; read versionctl's launcher, README and AgentsMD's .version-policy.json; confirmed both version files and the lockfile say 0.2.0 and the repo has no v* tag; read the merged PR bodies and file lists for the changelog entries; compared the README blurbs with pages 01 to 04 after docs: activation and budget pages match measured behavior (#12) #28.

🤖 Generated with Claude Code