fix(release): require validation for canonical beta PRs (#1032)

Require canonical beta release PRs to provide release-candidate validation evidence before merge, even when release-managed version metadata is already unchanged against main.

Also preserves unrelated PR no-op bypasses for partially inconsistent release states and malformed beta-prefixed maintenance branches.

Author: Soju06

openspec/changes/require-canonical-beta-validation/proposal.md

@@ -0,0 +1,24 @@
+# Require validation for canonical beta PRs
+
+## Problem
+
+The beta publish workflow correctly refuses to create release artifacts when a merged canonical `release/beta-*` PR lacks release-candidate validation evidence. However, the pre-merge `Beta release guard` can pass a canonical beta PR when release-managed metadata is already identical to `main`, because it treats the PR as a no-op diff and skips validation evidence checks.
+
+That leaves a green PR that can be merged, only for publish CD to fail after merge.
+
+## Solution
+
+Treat canonical `release/beta-*` PRs as publish intent whenever the checked-out tree already contains the matching beta version, even if release-managed metadata is unchanged relative to the base branch. Require the same release-candidate evidence before merge that the publish workflow requires after merge.
+
+## Changes
+
+- Update the PR guard to identify canonical beta release PRs before no-op release metadata short-circuiting
+- Require validation evidence for canonical beta PRs even when release-managed version files are unchanged against the base branch
+- Preserve the existing no-op bypass for non-canonical dependency or maintenance edits on beta-version bases
+- Add regression coverage for canonical beta PRs with unchanged metadata and missing evidence
+
+## Out of scope
+
+- Creating or rerunning release tags/artifacts
+- Changing the release-candidate validation checklist labels
+- Changing stable release behavior

openspec/changes/require-canonical-beta-validation/specs/release-management/spec.md

@@ -0,0 +1,22 @@
+## MODIFIED Requirements
+
+### Requirement: Merged beta release PRs publish GitHub prereleases
+
+When a pull request from a `release/beta-*` branch is merged into `main`, the release automation SHALL require `RELEASE_PLEASE_TOKEN` rather than falling back to `GITHUB_TOKEN`, verify that all release-managed version files agree on a beta version, create the matching `vX.Y.Z-beta.N` tag at the merge commit, and publish a GitHub prerelease for that tag. Re-running the workflow after the tag already exists SHALL be safe and SHALL NOT create a second tag. Before merge, the beta release guard SHALL require release-candidate validation evidence for canonical `release/beta-X.Y.Z-beta.N` pull requests whose checked-out tree already contains the matching beta version, even when the release-managed version files are unchanged relative to the base branch.
+
+#### Scenario: beta PR merge publishes a prerelease tag
+
+- **GIVEN** a merged pull request from `release/beta-1.19.0-beta.1`
+- **AND** release-managed files all contain `1.19.0-beta.1`
+- **AND** `RELEASE_PLEASE_TOKEN` is configured
+- **WHEN** the beta publish workflow runs
+- **THEN** it creates tag `v1.19.0-beta.1` at the merge commit
+- **AND** it creates a GitHub prerelease for `v1.19.0-beta.1`
+
+#### Scenario: canonical beta PR with unchanged metadata still requires validation
+
+- **GIVEN** `main` already contains release-managed files set to `1.20.0-beta.3`
+- **AND** a pull request from `release/beta-1.20.0-beta.3` targets `main`
+- **WHEN** the beta release guard evaluates the pull request before merge
+- **THEN** it requires release-candidate validation evidence for the pull request head SHA
+- **AND** it fails while that evidence is missing, even though the release-managed version files are unchanged relative to `main`

openspec/changes/require-canonical-beta-validation/tasks.md

@@ -0,0 +1,8 @@
+# Tasks
+
+- [x] Add regression coverage for a canonical beta PR whose release metadata is unchanged against the base branch but whose validation evidence is missing
+- [x] Update `scripts.guard_beta_release` so canonical beta PRs require validation evidence before no-op metadata short-circuiting
+- [x] Document the release-management requirement delta
+- [x] Run `openspec validate require-canonical-beta-validation --strict`
+- [x] Run targeted guard tests
+- [x] Run lint/type gates for the touched Python code

scripts/guard_beta_release.py

@@ -267,14 +267,26 @@ def guard_pull_request(root: Path, event: dict[str, Any], base_ref: str, head_re
         expected_sha = run_git(root, "rev-parse", "HEAD").stdout.strip()
         body = os.environ.get("BETA_RELEASE_PR_BODY", "")
 
+    current_versions = _canonical_release_versions(read_project_versions(root))
+    release_from_head: ReleaseVersion | None = None
+    if head_ref.startswith("release/beta-"):
+        try:
+            release_from_head = parse_version(head_ref.removeprefix("release/beta-"))
+        except ValueError:
+            release_from_head = None
+    is_canonical_beta_pr = bool(
+        release_from_head is not None
+        and release_from_head.channel == "beta"
+        and all(version == release_from_head.version for version in current_versions.values())
+    )
+
     changed = changed_release_version_files(root, base_ref)
-    if not changed:
+    if not changed and not is_canonical_beta_pr:
         print("No release-managed version files changed; beta release PR guard passed.")
         return
 
-    current_versions = _canonical_release_versions(read_project_versions(root))
     base_versions = _canonical_release_versions(_read_project_versions_at_ref(root, base_ref))
-    if current_versions == base_versions:
+    if current_versions == base_versions and not is_canonical_beta_pr:
         print("No release-managed version files changed; release metadata is unchanged; beta release PR guard passed.")
         return
 

tests/unit/test_guard_beta_release.py

@@ -171,6 +171,77 @@ def test_pr_guard_accepts_dependency_only_release_managed_file_edits(tmp_path: P
     assert "No release-managed version files changed" in result.stdout
 
 
+def test_pr_guard_accepts_noncanonical_noop_on_inconsistent_release_metadata_base(tmp_path: Path) -> None:
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    write_minimal_release_files(repo)
+    (repo / "app" / "__init__.py").write_text('__version__ = "1.20.0-beta.3"\n', encoding="utf-8")
+    git(repo, "init")
+    git(repo, "config", "user.email", "test@example.com")
+    git(repo, "config", "user.name", "Test")
+    git(repo, "add", ".")
+    git(repo, "commit", "-m", "chore: inconsistent partial release state")
+    git(repo, "branch", "-M", "main")
+    (repo / "pyproject.toml").write_text(
+        '[project]\nname = "codex-lb"\nversion = "1.20.0"\ndependencies = ["aiohttp-socks>=0.10.1"]\n',
+        encoding="utf-8",
+    )
+    git(repo, "add", "pyproject.toml")
+    git(repo, "commit", "-m", "deps: add aiohttp socks adapter")
+    sha = git(repo, "rev-parse", "HEAD")
+    branch = "fix/aiohttp-socks-adapter"
+    event = event_file(tmp_path, head_ref=branch, head_sha=sha, body="")
+
+    result = run_guard(
+        Path(__file__).resolve().parents[2],
+        repo,
+        "--base-ref",
+        "HEAD~1",
+        "--head-ref",
+        branch,
+        "--event-path",
+        str(event),
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "No release-managed version files changed" in result.stdout
+
+
+def test_pr_guard_accepts_invalid_beta_prefixed_branch_when_release_metadata_is_unchanged(tmp_path: Path) -> None:
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    write_minimal_release_files(repo, version="1.20.0-beta.3")
+    git(repo, "init")
+    git(repo, "config", "user.email", "test@example.com")
+    git(repo, "config", "user.name", "Test")
+    git(repo, "add", ".")
+    git(repo, "commit", "-m", "chore: release v1.20.0-beta.3")
+    git(repo, "branch", "-M", "main")
+    (repo / "pyproject.toml").write_text(
+        '[project]\nname = "codex-lb"\nversion = "1.20.0-beta.3"\ndependencies = ["aiohttp-socks>=0.10.1"]\n',
+        encoding="utf-8",
+    )
+    git(repo, "add", "pyproject.toml")
+    git(repo, "commit", "-m", "deps: add aiohttp socks adapter")
+    sha = git(repo, "rev-parse", "HEAD")
+    branch = "release/beta-doc-fix"
+    event = event_file(tmp_path, head_ref=branch, head_sha=sha, body="")
+
+    result = run_guard(
+        Path(__file__).resolve().parents[2],
+        repo,
+        "--base-ref",
+        "HEAD~1",
+        "--head-ref",
+        branch,
+        "--event-path",
+        str(event),
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "No release-managed version files changed" in result.stdout
+
+
 def test_pr_guard_rejects_inconsistent_release_managed_beta_metadata(tmp_path: Path) -> None:
     repo = tmp_path / "repo"
     repo.mkdir()
@@ -360,6 +431,38 @@ def test_pr_guard_rejects_canonical_beta_pr_without_validation_evidence(tmp_path
     assert sha in result.stderr
 
 
+def test_pr_guard_rejects_canonical_beta_pr_without_validation_evidence_when_metadata_unchanged(
+    tmp_path: Path,
+) -> None:
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    write_minimal_release_files(repo, version="1.20.0-beta.3")
+    git(repo, "init")
+    git(repo, "config", "user.email", "test@example.com")
+    git(repo, "config", "user.name", "Test")
+    git(repo, "add", ".")
+    git(repo, "commit", "-m", "chore: release v1.20.0-beta.3")
+    git(repo, "branch", "-M", "main")
+    sha = git(repo, "rev-parse", "HEAD")
+    branch = "release/beta-1.20.0-beta.3"
+    event = event_file(tmp_path, head_ref=branch, head_sha=sha, body="## Summary\nRelease beta3")
+
+    result = run_guard(
+        Path(__file__).resolve().parents[2],
+        repo,
+        "--base-ref",
+        "HEAD",
+        "--head-ref",
+        branch,
+        "--event-path",
+        str(event),
+    )
+
+    assert result.returncode == 1
+    assert "release-candidate validation evidence" in result.stderr
+    assert sha in result.stderr
+
+
 def test_pr_guard_accepts_validated_canonical_beta_pr(tmp_path: Path) -> None:
     repo = tmp_path / "repo"
     repo.mkdir()