docs: correct root-action pin guidance and add a pin regression contract

[roli-lpci]

What

Fixes two defects in the documented adoption path for the root GitHub Action, and adds an offline regression contract so neither can silently return.

1. llms.txt pinned a superseded commit. It referenced 1a70edc12bfd19e633983e0819b648bb2a5dda4e (feat(action): preflight full-mode dependencies #24) while README.md, SECURITY.md, and .github/workflows/example-usage.yml referenced 671e8db37c2bd124d4b74653f8c81945d1592a8f (ci: refresh and harden GitHub Action dependencies #31). The pin refresh in ci: refresh audited root action pin #32 did not reach the agent-facing file.
2. The release-tag guidance was false against live repository state. README.md, SECURITY.md, and llms.txt each said to replace the audited commit "with an immutable release tag when one exists." Tags do exist — and none of them works.

Why

A consumer who follows the current documentation either copies a different commit depending on which file they read, or follows the release-tag advice and gets a workflow that fails outright.

The tags v0.1.0, v0.1.1, and v0.2.0 version the pygate-ci package on PyPI. All three predate the root action.yml: at refs/tags/v0.2.0 (da37115, 2026-08-10) the only action file in the tree is .github/actions/pygate/action.yml. The root action, and the full-mode dependency preflight whose outputs the README documents, both landed afterwards in 1a70edc (2026-08-17). So there is currently no release tag that ships the documented action contract, and @v0.2.0 fails with a missing-action error rather than degrading to an older gate.

This is the first thing a new adopter copies, so it is worth being exactly right.

How

• llms.txt: pin corrected to the audited 671e8db commit.
• README.md (Pinning policy), SECURITY.md (Action pinning), llms.txt: the "when one exists" guidance is replaced with the actual constraint — pin the audited commit; the published tags predate the root action.yml and do not resolve as an action reference; prefer a tag once one is cut at or after the root action landed.
• tests/test_docs_action_pin.py: new offline contract over README.md, SECURITY.md, llms.txt, and .github/workflows/example-usage.yml, asserting each documents a root-action reference, that every reference is a 40-character commit SHA (rejecting both tags and mutable branch refs, per the stated policy), and that all documented pins agree.

No source, action, or schema behaviour changes.

Verified the contract actually catches the shipped defect: restoring the original 1a70edc value in llms.txt fails test_documented_pins_agree with both pins named in the message; restoring the fix passes.

Follow-up, not in this PR: cutting a release tag at or after the root action landed would let this guidance recommend a tag instead of a SHA, which is a materially easier thing for an adopter to copy. That is a release decision and is left to the maintainer.

Test Plan

• Tests pass (pytest — 161 passed, including the 3 new contract tests)
• Linting passes (ruff check src/ tests/, ruff format --check src/ tests/)
• Type checking passes (pyright src/ — 0 errors, 0 warnings)
• CHANGELOG.md updated

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation

  • Updated GitHub Actions examples and security guidance to use the audited immutable commit.
  • Clarified that existing release tags do not provide valid root action references.
  • Removed guidance suggesting replacement with a release tag until a suitable tag exists.
  • Reinforced that mutable branch references must not be used.

• Tests

  • Added checks ensuring all documented action references use the same 40-character commit SHA.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 66e8fe3d-768b-441b-9449-6f2313db37bd

📥 Commits

Reviewing files that changed from the base of the PR and between e596cf1 and 587abc0.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• SECURITY.md
• llms.txt
• tests/test_docs_action_pin.py

---

📝 Walkthrough

Walkthrough

The documentation now uses the audited root-action commit and explains why existing release tags cannot reference the root action. A regression test checks that all documented references are immutable 40-character commit SHAs and use one consistent pin.

Changes

Action pin consistency

Layer / File(s)	Summary
Documented pin policy README.md, SECURITY.md, llms.txt, CHANGELOG.md	Updates the root-action pin to 671e8db37c2bd124d4b74653f8c81945d1592a8f. Documents that existing package release tags predate the root action.yml and removes guidance to use those tags.
Pin regression contract tests/test_docs_action_pin.py, CHANGELOG.md	Adds checks for references in all documented sources, immutable 40-character commit SHAs, and agreement on one documented pin. The changelog records this test contract.

Estimated code review effort: 2 (Simple) | ~10 minutes

✨ 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 claude/docs-action-pin-consistency

---

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.}