[ptr727]

Summary

• Stub pins become placeholders. Every hub uses: pin in docs/reusable-workflows.md's stubs now reads @<hub-main-commit-sha> # <release-tag>, the shape the maintainer chose on Adopter docs and catalog snippets hardcode a pin, so every one of them is stale #1472. No Dependabot scan reads a pin quoted in a document, so a literal there only went stale.
• Snippets keep a literal floor pin. Each catalog/snippets/workflows/ snippet is unchanged and keeps its literal minimum known-good pin, which moves when a task's interface changes. spec/workflow_reuse.py and the pin gate read them as canonical text.
• Adoption resolves the pin. "Pinning" now states the rule and the two read-only gh commands that name the latest release and its main commit. The snippets README and STANDUP.md section 3 point there. "Byte for byte" no longer covers the pin lines.
• Tests. The tests comparing a doc stub to its snippet substitute the placeholder through one documented() helper, and the merge-bot stub is now compared too. A new test holds both pin shapes, placeholders in the doc and literals in the snippets, judging every hub reference including one with no tag comment.
• PlexCleaner Stage 2 item ticked (Re-Check the PlexCleaner Item in the Reusable-Workflows Tracker Against Its main #3813). Checked live against PlexCleaner main. Resync With the Hub and Adopt the Hub Validate Task PlexCleaner#1064 merged into develop at 84fd00e and was promoted in Promote the 3.23 Verify, Repair, and Delete Safety Fixes to Main PlexCleaner#1098 at 1876563. Both validator callers pass python-directories: RegressionTests. The Stage 3, 4, and 5 PlexCleaner items it also bears on are filed as Re-Check the PlexCleaner Stage 3, 4, and 5 Items in the Reusable-Workflows Tracker Against Its main #3834 rather than widened into this change.

Verification

• Full unittest suite, spec/validate.py, test_audit_helpers.py, and spec/workflow_reuse.py --selftest all exit 0.
• The prose gate, ruff, mypy, and the eol check pass in the pre-commit hook.

Closes on promotion: #1472, #3813

🤖 Generated with Claude Code

[coderabbitai]

Important

• Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

• Source mode: Auto
• Repository: ptr727/ProjectTemplate
• Branch: burndown/1472-snippet-pins
• File: .coderabbit.yaml
• Commit: d7fc785
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: af06fe5e-899b-41c2-8d60-0ace3449cc0e

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[ptr727]

A recorded local strict-review pass covers head 46dd530bbd9bcc4b40afb70b7370fbfa17b4706d, the content this pull request carries at that commit against develop, and it recorded 0 findings.

[Copilot]

🟡 Changes recommended

An active nit remains in the helper docstring, whose unclear grammar leaves the helper contract insufficiently explained.

1 open issue

• Fix the helper docstring grammar · New

What changed in this PR

This pull request updates reusable-workflow adoption guidance to use resolvable placeholder pins in documentation while preserving literal minimum-known-good pins in catalog snippets. It also records PlexCleaner Stage 2 adoption progress and strengthens pin-shape test coverage.

Changes:

• Replaces literal hub pins in documentation stubs with <hub-main-commit-sha> # <release-tag> placeholders.
• Adds guidance for resolving current release and commit pins before adoption.
• Preserves literal pins in catalog snippets and updates related regression tests.
• Updates onboarding documentation and marks PlexCleaner Stage 2 complete.

File	Description
tests/​test_release_guards.py	Adds placeholder normalization and pin-shape validation for documentation and snippets.
STANDUP.md	Directs adopters to resolve hub pins before committing workflow stubs.
docs/​reusable-workflows.md	Documents placeholder-based pins, lookup guidance, and PlexCleaner Stage 2 completion.
catalog/​snippets/​workflows/​README.md	Explains minimum-known-good literal pins and adopter resolution.

_{Review effort: Lite}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.97%. Comparing base (b38e084) to head (d7fc785).
⚠️ Report is 82 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #3836      +/-   ##
===========================================
+ Coverage    81.60%   82.97%   +1.36%     
===========================================
  Files           26       29       +3     
  Lines         9070     9747     +677     
===========================================
+ Hits          7402     8088     +686     
+ Misses        1668     1659       -9     

Flag	Coverage Δ
python-3.13	82.97% <ø> (+1.36%)	⬆️

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.

[ptr727]

A recorded local strict-review pass covers head d7fc785c6759d59dbf1bdb853dfa5ec96e9c303f, the content this pull request carries at that commit against develop, and it recorded 0 findings.

[ptr727]

Backlog burndown orchestrator, for the record. The worker reports that it wrote the --report files itself for the first three recorded local-strict-review passes, at digests bc45bfd4, cc585173 and e2792c9a. The reviewer ran each of those passes. Develop's rule since #3807 is that the reviewer writes its own report. Every later pass, including the two covering the merged head d7fc785, was recorded from a report the reviewer subagent wrote itself. So the merged content carries a conforming pass, while the attestation on the earlier head 46dd530 does not.