Record the Release Gate's Branch-Name Refusal in the D2 Contract

[ptr727]

Summary

Fixes #1531. The release task's validate-release gate refuses, ahead of its smoke exit, any branch input that git check-ref-format --branch rejects (build-release-task.yml:139-142). That refusal landed with the fix for the version step logging the branch unsanitized, and WORKFLOW.md D2 never recorded it, so the contract listed less than the gate asserts at entry. Nothing reachable trips it, since a documented caller passes github.ref_name or github.base_ref || github.ref_name, but D2's validate-at-entry guarantees exist to record exactly what the gate asserts.

• WORKFLOW.md: a new D2.5 states the input (a release task taking a branch input, on any run), the output (the gate runs git check-ref-format --branch over that value and fails when git rejects it, ahead of D2.2's smoke exit, with an error echoing no part of the value), and what it prevents (a :: or ##[ in a caller's value forming a workflow command wherever a later step prints the branch, on a smoke run as much as on a publish).
• The workflow-ci-contract Skill carries section 4 whole as a generated include, so scripts/build_dist.py refreshed d-guarantees.md in the source tree and in both generated distributions.
• reports/canonical-review.json: the whole-unit pass over the two canonical units this change moves.

D2.5 is its own item rather than a clause of D2.2, which keeps each item asserting one thing and leaves D2.1 through D2.4 numbered as the audit reports and publish-release.yml already cite them. The S1, S4, and S10 rows of section 5 are unchanged: each describes a run whose branch value is a real ref name, which the refusal never reaches.

Verification

• python3 scripts/build_dist.py --check: generated skill distributions are current.
• python3 spec/validate.py: 22 cataloged repos classify cleanly.
• python3 scripts/prose_lint.py . --diff HEAD and python3 scripts/repo_gate.py --check eol: clean.
• python3 scripts/docker_lint.py: 7 linters clean, markdownlint over 185 files and editorconfig-checker over 352.
• Local strict review pass over the branch diff, and a carried-content pass over both canonical units, recorded.

🤖 Generated with Claude Code

https://claude.ai/code/session_012u4N7gEcqT9QwTusr1qtUc

Summary by CodeRabbit

• Documentation

  • Added a workflow contract requirement to validate release branch names before proceeding.
  • Invalid branch names are rejected without exposing the submitted value in errors.

• Chores

  • Updated recorded workflow contract review metadata and statuses.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: f4531c5e-14e7-4870-9ba6-3edaed4704fe

📥 Commits

Reviewing files that changed from the base of the PR and between d2a7a17 and a9bcaf7.

⛔ Files ignored due to path filters (3)

• .claude-plugin/fleet-skills/.source-digests/workflow-ci-contract is excluded by !.claude-plugin/fleet-skills/**
• .claude-plugin/fleet-skills/skills/workflow-ci-contract/references/d-guarantees.md is excluded by !.claude-plugin/fleet-skills/**
• .github/skills/workflow-ci-contract/references/d-guarantees.md is excluded by !.github/skills/**

📒 Files selected for processing (3)

• .agents/skills/workflow-ci-contract/references/d-guarantees.md
• WORKFLOW.md
• reports/canonical-review.json

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

---

📝 Walkthrough

Walkthrough

The release workflow contract now requires git check-ref-format --branch validation for branch inputs before the smoke exit. Invalid values must fail without being echoed. Canonical review records now contain refreshed metadata.

Changes

Release branch validation

Layer / File(s)	Summary
Branch validation contract and review records .agents/skills/workflow-ci-contract/references/d-guarantees.md, WORKFLOW.md, reports/canonical-review.json	The D2 contract now requires release gates to validate branch with git check-ref-format --branch on every run, fail before the smoke exit when invalid, and avoid echoing the value. Related canonical review records have refreshed digests, status, commit, and timestamps.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to a9bca

The workflow contract and review metadata are consistent with the validated, non-echoed branch rejection behavior.

🚥 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: documenting the release gate's branch-name refusal in the D2 contract.
Linked Issues check	✅ Passed	Issue #1531 requires D2 to document the release gate's branch validation. WORKFLOW.md adds D2.5 with git check-ref-format --branch, rejection before the smoke exit and build steps, no echo of th…
Out of Scope Changes check	✅ Passed	The changes stay within issue #1531. WORKFLOW.md and generated contract content implement or distribute the required documentation. reports/canonical-review.json records the corresponding contract…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/d2-branch-name-refusal

---

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

[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]

🟢 Approval recommended

The documentation update accurately matches the existing gate behavior (the branch check occurs before the smoke exit and emits no branch content), and the regenerated distributions/ledgers are consistent with the source change.

Pull request overview

This PR updates the workflow behavioral contract to explicitly document the release gate's early refusal of invalid branch inputs (as validated by git check-ref-format --branch), aligning WORKFLOW.md (and its carried skill reference) with the gate's current entry behavior.

Changes:

• Add D2.5 to the D2 contract describing the release gate's branch-name validation and its security motivation (preventing workflow-command injection via later branch logging).
• Refresh the workflow contract copy carried in the workflow CI contract skill reference.
• Update the canonical review ledger entries for the touched canonical units.

File summaries

File	Description
WORKFLOW.md	Documents D2.5: release gate rejects invalid branch values via git check-ref-format --branch.
reports/canonical-review.json	Updates digests and stamps for the canonical units affected by the contract change.
.github/skills/workflow-ci-contract/references/d-guarantees.md	Regenerated skill reference reflecting the new D2.5 guarantee.
.claude-plugin/fleet-skills/skills/workflow-ci-contract/references/d-guarantees.md	Regenerated plugin skill reference reflecting the new D2.5 guarantee.
.claude-plugin/fleet-skills/.source-digests/workflow-ci-contract	Updates the plugin digest stamp for the workflow-ci-contract skill distribution.
.agents/skills/workflow-ci-contract/references/d-guarantees.md	Source-of-truth skill reference updated with D2.5.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.