fix(docs): pin README version badge to SKILLS_VERSION with a floor checker

[PrzemekGalarowicz]

Summary

• Fixes the README version badge, which had read version-1.0.0 through the entire 2.x line while SKILLS_VERSION reached 2.5.1 — it now shows pharn-2.5.1 and the CHANGELOG header explicitly names the two version tracks (SKILLS_VERSION = product surface vs package.json 1.0.0 = foundation tag).
• Adds .dev/floor/check-version-badge.mjs, a deterministic apparatus checker that locates the badge by its shields URL pattern and asserts it equals SKILLS_VERSION (fail-closed on absent, malformed, or duplicate badges; named refusal for hyphen-bearing pre-release versions).
• Wires the checker into npm run check (check:badge) and CI as its own step — CI runs each script individually and never npm run check, so check-only wiring would leave it unrun on every PR.

No SKILLS_VERSION bump: all touched paths are repo-meta or build apparatus (.dev/), outside the bump-triggering set.

Test plan

• node .dev/floor/check-version-badge.mjs . exits 0 on this repo
• node --test .dev/floor/check-version-badge.test.mjs — agreement, drift, absent/malformed/duplicate badge, hyphen refusal, precedence, and package.json/ci.yml pin tests
• npm run check:badge passes
• npm run check passes
• node pharn/floor/validate.mjs . → GREEN

Follow-up (not in scope)

• .claude/commands/pharn-dev-verify.md:100 still claims its gate set is "exactly" npm run check when it is a strict subset (docs:check, check:markers, and now check:badge are outside it). Recorded in GRILL/CHANGELOG; deferred as verify-gate-map-claim.

Made with Cursor

Summary by CodeRabbit

• Documentation

  • Updated the README version badge to display the current SKILLS_VERSION (2.5.1).
  • Clarified versioning conventions and documented the new badge validation process.

• Bug Fixes

  • Added validation to detect missing, duplicated, malformed, unsupported, or mismatched version badges.
  • Improved failure handling with clear remediation guidance.

• Tests

  • Added coverage for badge drift, invalid inputs, ambiguous badges, and integration with project checks.

• Chores

  • Integrated badge validation into the standard check command and continuous integration workflow.

[coderabbitai]

Warning

Review limit reached

@PrzemekGalarowicz, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 34 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fea07c98-fea4-43ba-8fda-f890a3ef5569

📥 Commits

Reviewing files that changed from the base of the PR and between e83806c and 593032c.

📒 Files selected for processing (3)

• .dev/features/version-badge-pin/PLAN.md
• .dev/floor/check-version-badge.mjs
• .dev/floor/check-version-badge.test.mjs

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch version-badge-pin

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.dev/floor/check-version-badge.mjs:
- Around line 4-6: Correct the byte-equality claims to describe JavaScript
string equality between the extracted badge value and the trimmed, validated
SKILLS_VERSION value. Update the comment in .dev/floor/check-version-badge.mjs
lines 4-6, replace “compared as bytes” with the actual string-validation
behavior in .dev/features/version-badge-pin/PLAN.md lines 75-77, and make the
same clarification in .dev/features/version-badge-pin/VERIFY.md lines 75-76.
- Around line 133-175: Escape every untrusted version and badge value before
interpolating it into findings or stdout, using the existing escaping helper
where available. Update the unsupported, ambiguous, enum-error, and drift
messages around findBadgeValues, isCleanScalar, and finding while preserving
their current behavior. Add a mutant test asserting output contains no raw ESC
character when a README badge includes \x1b.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 49c4bd83-bef4-458c-82e4-47a1ebe4e15c

📥 Commits

Reviewing files that changed from the base of the PR and between 91afd74 and e83806c.

📒 Files selected for processing (15)

• .dev/features/version-badge-pin/GRILL.md
• .dev/features/version-badge-pin/PLAN.md
• .dev/features/version-badge-pin/REGRESSION.md
• .dev/features/version-badge-pin/REVIEW.md
• .dev/features/version-badge-pin/SHIP.md
• .dev/features/version-badge-pin/VERIFY.md
• .dev/features/version-badge-pin/regression-report.json
• .dev/features/version-badge-pin/verify-report.json
• .dev/floor/check-version-badge.mjs
• .dev/floor/check-version-badge.test.mjs
• .github/workflows/ci.yml
• CHANGELOG.md
• CLAUDE.md
• README.md
• package.json