feat(gates): guard README version-badge drift in the docsync gate - #327
Merged
Conversation
The docsync gate only checked the docs/README.md route index, so the stale README shields.io version badge (0.16.0 while package.json was 0.18.0) slipped past forge's own gate. #308 fixed the value and added a standalone vitest guard; this wires the SAME invariant into the docsync GATE so it is enforced mechanically at ship + CI, not just as a unit test. - Add parseBadgeVersion / badgeVersionDrift pure helpers and a badge-vs- package.json check to runDocSync (package.json is the source of truth). The check runs even when there is no docs/README.md route index, and is a no-op when the README carries no badge (no false positives). - Surface badge drift in the MCP gate verdict findings. - Extend tests/gates/docsync.test.mjs with AC-309.1 (drift -> fail) and AC-309.2 (in-sync -> pass), plus helper-level coverage. Closes #309 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SATRHKa6mDHDuirhP6QuwL
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.
What & why
The docsync gate (
plugin/scripts/gates/docsync.mjs) only verified that docs are listed in thedocs/README.mdroute index, so the stale README shields.io version badge (0.16.0whilepackage.jsonwas0.18.0) slipped past forge's own gate. #308 fixed the badge value and added a standalone vitest guard (tests/readme-version.test.mjs); this ticket wires the same invariant into the docsync GATE so it's enforced mechanically at ship + CI, not just as a unit test.Changes
parseBadgeVersion/badgeVersionDriftpure helpers + a badge-vs-package.jsoncheck inrunDocSync(package.json is the source of truth). Runs even when there's nodocs/README.mdroute index, and is a no-op when the README carries no badge (no false positives).server.mjs) surfaces badge drift in its findings.tests/gates/docsync.test.mjsextended with AC-309.1 / AC-309.2 + helper coverage.Acceptance criteria
runDocSync; drift setsres.ok=falsewith a clear message. Verified:AC-309.1test + running the gate against a drifted tree.AC-309.2(pass) andAC-309.1(fail) intests/gates/docsync.test.mjs.Verification
pnpm verify— 579/579 green (53 files).node plugin/scripts/gates/docsync.mjs --base mainon the current tree →doc-sync: clean (52 docs indexed), exit 0 (badge 0.18.0 == package.json 0.18.0), so CI stays green.Closes #309
🤖 Generated with Claude Code