Placeholder the Bare-Tag Pin Example and Gate the Hub on Version Literals

[ptr727]

Summary

• GOVERNANCE.md "Workflow YAML Conventions", Action pinning bullet: the bare-tag example is now the placeholder # X.Y.Z instead of a three-part version, per "Documentation Style Conventions".
• The version-literal pattern and its file set move from spec/audit.py into spec/validate.py, since spec/audit.py already imports validate and the reverse import would be circular. spec/audit.py now aliases them.
• spec/validate.py gains version_literal_errors, which scans the hub's AGENTS.md, GOVERNANCE.md, CODESTYLE.md, and WORKFLOW.md whole, verbatim sections included, so a literal fails the hub's pull request gate instead of merging and carrying. Before this change only the audit's hub run reported it, and that is not a pull request gate.
• Tests: a literal under a heading that spec/files.json declares verbatim is rejected, a placeholder is accepted, and the hub's own four documents are clean. The hub-tree test failed on the old text.

The comments label is here because the moved comment lines count as added in spec/validate.py.

Closes on promotion: #1935

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified the comment format for documenting upstream tags without a v prefix.
• New Features
  • Validation now checks selected guidance documents for version tags, full commit hashes, and qualifying abbreviated hashes, reporting each distinct match per file. Missing documents are skipped.
• Tests
  • Added coverage for version-tag detection, placeholder examples, and clean validation of the guidance documents.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: ptr727/ProjectTemplate/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 781691c9-8745-481c-8b8e-82faec574289

📥 Commits

Reviewing files that changed from the base of the PR and between 6f2cc9a and e362d84.

📒 Files selected for processing (4)

• GOVERNANCE.md
• spec/audit.py
• spec/validate.py
• tests/test_spec_validate.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The validator now scans four instruction documents for three-part versions and commit SHAs, then adds matches to validation errors. The audit module reuses the validator’s scan definitions. The governance example now uses a placeholder format for bare version tags.

Changes

Version Literal Validation

Layer / File(s)	Summary
Version literal scanning and validation spec/validate.py, spec/audit.py, tests/test_spec_validate.py, GOVERNANCE.md	The validator scans selected instruction documents for version and commit literals and adds findings to its errors. The audit module uses the shared scan definitions. Tests cover matched literals, placeholders, and the repository’s instruction documents. The governance example uses # X.Y.Z for tags without a v prefix.

Priority: ⬇️ Low

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

Merge Risk: ⚪ Minimal · up to e362d

The version-literal gate and governance placeholder are ready to merge after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to e362d

The new check is designed to reject version and commit literals before hub changes merge. The reviewed paths show no new privilege or trust-boundary expansion, but repository-level merge enforcement could not be verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — A contributor able to change hub instruction documents can trigger the new validation failure; the reviewed change adds no credential access or execution authority to that input path.

Trust Boundaries and Controls

• observed — The hub-local validation action propagates validator failure through the pull-request workflow. Whether that workflow’s status is required for merging depends on repository settings not available in this review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 3 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes both main changes: replacing the bare-tag pin example with a placeholder and adding version-literal validation to the hub.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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

[codecov]

Codecov Report

❌ Patch coverage is 93.33333% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (develop@6f2cc9a). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
spec/validate.py	92.30%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             develop    #1962   +/-   ##
==========================================
  Coverage           ?   55.41%           
==========================================
  Files              ?       16           
  Lines              ?     7247           
  Branches           ?        0           
==========================================
  Hits               ?     4016           
  Misses             ?     3231           
  Partials           ?        0           

Flag	Coverage Δ
python-3.13	55.41% <93.33%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Copilot review overview

🟢 Approval recommended

The change is narrow, well-covered by new tests, and introduces only a minor documentation clarity nit.

Review effort: Lite
Findings: 1

Open (1)

• Docstring omits commit SHA rejection in version literal check · New

What changed in this PR

This pull request updates the hub’s workflow-pinning guidance to avoid hard-coded version literals, and adds a spec/validate.py gate that rejects three-part versions and commit SHAs in the hub’s core instruction documents so the issue is caught at PR time rather than only during audits.

Changes:

• Updates GOVERNANCE.md “Workflow YAML Conventions” action-pinning example to use a placeholder bare tag format instead of a concrete version.
• Moves version-literal scanning patterns into spec/validate.py and adds version_literal_errors() to enforce the hub’s instruction-document constraint.
• Adds tests covering rejection inside a verbatim section, acceptance of placeholders, and cleanliness of the hub’s own instruction docs.

File	Description
tests/​test_spec_validate.py	Adds targeted tests for the new version/SHA literal gate.
spec/​validate.py	Defines the version/SHA literal regex and enforces it via a new validation error list.
spec/​audit.py	Aliases the moved constants from spec/validate.py to avoid duplication/circular imports.
GOVERNANCE.md	Replaces the concrete bare-tag example with a placeholder pattern in the pinning rule text.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ptr727]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Copilot]

Copilot review overview

🟢 Approval recommended

The documentation change removes the offending literal, the new validation is correctly integrated into the existing spec gate, and tests cover both the rule behavior and the hub’s own documents.

Review effort: Lite
Findings: None

Resolved since last review (1)

• Docstring omits commit SHA rejection in version literal check