feat(standards): all reusable workflows pin the moving stable channel tag

[don-petry]

What

Establish a single, generic org standard for versioning every reusable workflow: callers pin the reusable's moving stable channel tag (uses: …/<name>-reusable.yml@<name>/stable) — never @main (a branch) and never a frozen @vX.Y.Z (a version). Applies to all reusable workflows regardless of which repo hosts them (public or private) or which repo calls them (downstream consumer or the reusable's own self-host duty).

Why

• @main (a branch) has no version boundary — a bad commit is instantly live for every caller; for a self-hosting reusable it lets a broken change gate its own fix (circular dependency, fails closed).
• A frozen @vX.Y.Z is immutable, so rolling out a change means editing every caller — a fan-out PR per release, partial-fleet states, security fixes stuck behind churn.
• The moving stable channel is pinned once and rolled out / back by moving the tag centrally — no caller churn, instant uniform rollback, health-gated promotion, single source of version truth, and it breaks self-host circular dependencies.

Release process (now documented in the standard)

1. Develop & merge to the reusable's main.
2. Cut an immutable <name>/vX.Y.Z (audit + rollback target).
3. Validate on a candidate channel / canary ring.
4. Promote by moving <name>/stable → the validated vX.Y.Z (gated central tag move).
5. Roll back by moving <name>/stable back to the prior vX.Y.Z.

Changes

• standards/ci-standards.md — new generic Reusable workflow versioning — the stable channel standard (policy, benefits, release process, migration); tier-table and action-pinning-policy references genericized to the channel model.
• standards/workflows/dev-lead.yml — reference implementation: pins @dev-lead/stable + agent_ref.
• scripts/compliance-audit.sh — check_dev_lead_stub enforces the channel pin (keeps the audit in sync with the already-migrated dev-lead consumers).

Migration is incremental: a reusable not yet publishing a stable channel keeps its current pin until it migrates, when its callers re-pin once and the audit tightens for that reusable. dev-lead/pr-review are the reference implementation, proven end-to-end in petry-projects/.github-private (release-strategy initiative #495).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Updated CI standards to adopt a moving "stable" channel for reusable-workflow promotion/rollback and clarified exception rules for internal references.

• Tests

  • Strengthened compliance checks to require stable-channel pinning and the matching agent/channel parameter on caller stubs.

• Chores

  • Adjusted workflow wiring to pin caller stubs to the stable channel and align promotion behavior.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6d3251f7-25f1-4363-a36d-92c5a4a4a361

📥 Commits

Reviewing files that changed from the base of the PR and between afe0dab and 10ede4c.

📒 Files selected for processing (2)

• scripts/compliance-audit.sh
• standards/ci-standards.md

---

📝 Walkthrough

Walkthrough

The pull request updates the dev-lead reusable workflow pinning strategy from @main to a moving @dev-lead/stable channel. Standards documentation, the workflow caller, and the compliance audit script are coordinated to require the stable-channel pin and to thread agent_ref: dev-lead/stable.

Changes

Reusable Workflow Stable-Channel Versioning

Layer / File(s)	Summary
Standards and Policy Definition standards/ci-standards.md	Tier 1 workflow stubs now delegate to reusable workflows pinned to a moving stable channel (e.g., .../<name>-reusable.yml@<name>/stable). Internal reusable-workflow exemption from SHA pinning is allowed only when callers target the reusable’s moving stable channel (no @main, no SHA pins). The Dev-Lead caller stub contract is updated to pin dev-lead-reusable.yml to @dev-lead/stable and pass agent_ref: dev-lead/stable.
Workflow Pin Update standards/workflows/dev-lead.yml	The dev-lead job's reusable workflow reference is pinned from @main to @dev-lead/stable, and the job now passes agent_ref: dev-lead/stable; comments document the pinned-channel behavior and centralized promotion mechanism.
Compliance Check Update scripts/compliance-audit.sh	The check_dev_lead_stub() function comment and validations are updated: it now requires the exact uses: line pointing at dev-lead-reusable.yml@dev-lead/stable, requires with: agent_ref: dev-lead/stable, and re-orders the remaining stub-drift checks (making concurrency: the third violation and statuses: read next).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• petry-projects/.github#12: Updates the scripts/compliance-audit.sh dev-lead stub compliance check to align with the new stable-channel pin.
• petry-projects/.github#86: Modifies CI/pinning standards in standards/ci-standards.md for reusable-workflow ref pinning rules.
• petry-projects/.github#89: Updates scripts/compliance-audit.sh to enforce standardized uses: ref/pinning rules for reusable workflow stubs.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: establishing an org-wide standard for reusable workflows to pin the moving stable channel tag, which is the primary objective of all file changes in this PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 feat/ratify-agent-channel-pinning

---

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 and usage tips.}

[gemini-code-assist]

Code Review

This pull request transitions the self-hosted agentic reusables (dev-lead and pr-review) from pinning to @main to using moving per-agent channel tags (e.g., @dev-lead/stable). This standard prevents circular dependencies where a broken change could gate its own fix. The compliance audit script, CI standards documentation, and the dev-lead.yml workflow stub have been updated to reflect this change. Review feedback focuses on improving shell script safety by using printf instead of echo to output decoded content, as well as minor grammatical and phrasing enhancements in the documentation and workflow comments to ensure a professional tone.

[Copilot]

Pull request overview

This PR updates org CI standards and templates to ratify the per-agent moving channel tag model for self-hosted agentic reusable workflows (notably dev-lead), replacing the prior @main pinning guidance.

Changes:

• Updates standards/ci-standards.md to document and standardize the moving channel tag approach (@dev-lead/stable, @pr-review/stable) and the associated agent_ref threading.
• Updates the standards/workflows/dev-lead.yml Tier-1 stub to pin @dev-lead/stable and pass with: agent_ref: dev-lead/stable.
• Updates scripts/compliance-audit.sh so check_dev_lead_stub enforces the new canonical uses: ref (@dev-lead/stable).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
standards/workflows/dev-lead.yml	Updates the canonical dev-lead stub to use the dev-lead/stable channel tag and pass agent_ref consistently.
standards/ci-standards.md	Replaces the prior dev-lead @main exception with the ratified moving per-agent channel tag standard and updates examples/pinning guidance.
scripts/compliance-audit.sh	Aligns the compliance audit’s dev-lead stub pin validation with the new @dev-lead/stable standard.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[don-petry]

Dev-Lead — waiting on PR blockers (intent: fix-reviews)

PR: #440
No changes were committed, but the PR still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews). The retry cron will re-attempt automatically. Next attempt after: 2026-06-10T22:33:04Z

[don-petry]

Dev-Lead — waiting on PR blockers (intent: review-changes)

PR: #440
No changes were committed, but the PR still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews). The retry cron will re-attempt automatically. Next attempt after: 2026-06-11T01:06:46Z

[don-petry]

Note

@don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically.
Next attempt after: 2026-06-11T01:06:46Z

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@scripts/compliance-audit.sh`:
- Around line 836-842: The current check in check_dev_lead_stub only verifies
the reusable `uses:` ref but doesn't confirm the stub provides `with.agent_ref:
dev-lead/stable`; add a second test against the same decoded content to ensure
the stub contains an explicit agent_ref pinned to dev-lead/stable (e.g. grep -qE
for a line like "agent_ref:[[:space:]]*dev-lead/stable" or a "with:" block
containing that key). If the pattern is missing, call add_finding (similar style
to the existing block) with a new error key such as "dev-lead-stub-agent-ref"
and a message instructing to pin `with.agent_ref: dev-lead/stable`. Reference
the existing variable decoded and the function name check_dev_lead_stub when
adding this check.

🪄 Autofix (Beta)

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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6627370a-07fe-46d6-bedf-52b7db8a172d

📥 Commits

Reviewing files that changed from the base of the PR and between fa54c51 and afe0dab.

📒 Files selected for processing (3)

• scripts/compliance-audit.sh
• standards/ci-standards.md
• standards/workflows/dev-lead.yml

[don-petry]

@donpetry-bot please review — the agent_ref enforcement check requested by CodeRabbit is in place (a5463bd) and all required checks are green.

[don-petry]

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

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[donpetry-bot]

@don-petry I'm on it — starting a fresh review now. Results will appear in a few minutes.

[don-petry]

Dev-Lead — waiting on PR blockers (intent: review-changes)

PR: #440
No changes were committed, but the PR still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews). The retry cron will re-attempt automatically. Next attempt after: 2026-06-11T12:39:37Z

[don-petry]

Note

@don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically.
Next attempt after: 2026-06-11T12:39:37Z

[don-petry]

Dev-Lead — fix-reviews (no-changes)

Agent reasoning

Addressed 0 threads:
(no open threads)
Test verification: N/A — no code changes made; all CI checks already passing
Files changed: none
```
No action required. The PR has no open review threads, all CI checks pass, and the only reviewer with a prior change request (coderabbitai) has since approved.

[donpetry-bot]

Automated review — APPROVED ✓

Risk: LOW
Reviewed commit: 10ede4cb578ff700f35395d9553ca3a9ebb405c9
Review mode: triage-approved (single reviewer)

Summary

Standards / docs / audit-only change formalizing the moving <name>/stable channel-tag pinning model for reusable workflows. Reference implementation is the dev-lead.yml template (pins @dev-lead/stable + threads agent_ref: dev-lead/stable), and scripts/compliance-audit.sh is tightened to require both. Triage flagged as low-risk; confirming on the merits.

Linked issue analysis

No linked issue (closingIssuesReferences empty). PR body anchors the work to the ongoing release-strategy initiative (petry-projects/.github-private#495) and explicitly frames dev-lead/pr-review as the already-proven reference implementation being ratified into the org standard. Appropriate for a standards PR.

Findings

No blocking findings.

• standards/ci-standards.md — new "Reusable workflow versioning — the stable channel" section (policy, why-not-@main, why-not-frozen-@vX.Y.Z, benefits, release process, concentric-ring promotion table, migration). Tier-table and Action Pinning Policy / Internal Reusable Workflow References examples are genericized to the channel model and the prior dev-lead @main exception is removed. Consistent throughout — no stale references to the old policy spotted.
• standards/workflows/dev-lead.yml — reference caller stub now pins …/dev-lead-reusable.yml@dev-lead/stable and passes with: agent_ref: dev-lead/stable. Comment cross-links ci-standards.md#dev-lead-agent. Matches what the audit now enforces.
• scripts/compliance-audit.sh (check_dev_lead_stub) — expected pin changed from @main to @dev-lead/stable; new check requires agent_ref: dev-lead/stable in with:; existing concurrency / statuses: read checks renumbered to #3/#4 and their numbered comments updated to match. Defensive nit handled: the two new checks use printf '%s\n' "$decoded" | grep … rather than echo "$decoded" | grep …, avoiding echo backslash/option pitfalls on decoded YAML — a small hardening upgrade over the prior echo-based checks. Regex patterns escape . correctly and anchor with ^[[:space:]]* … ([[:space:]]|$) end markers; the literal / in dev-lead/stable does not need escaping in ERE. ShellCheck CI is green.

CI status

All required checks SUCCESS (Lint, ShellCheck, Agent Security Scan, Secret scan (gitleaks), CodeQL Analyze (actions), SonarCloud, AgentShield, CodeRabbit, dev-lead / dispatch, pr-auto-review / check-and-dispatch). Per-language Dependency-audit jobs SKIPPED — no manifest changes. CodeRabbit's final review state is APPROVED on this SHA. mergeStateStatus: BLOCKED reflects the outstanding petry-projects/org-leads team review request (org policy gate for standards changes), not a CI failure.

---

Reviewed automatically by the PR-review agent (single-reviewer mode: opus 4.7). Reply if you need a human review.