ci: staging RC releases + automated back/forward-merge PRs

[jirhiker]

What

Implements the full release flow: staging RCs → production stable releases → hotfixes, with automated branch convergence. Documented in docs/release-flow.md.

feature (jir*) ──PR──▶ staging ──promotion PR──▶ production ──release PR──▶ tag vX.Y.Z ──▶ prod deploy
   │                     │                            ▲                            │
   ▼                     ▼                            │ auto forward-merge PR      ▼ auto back-merge PR
testing svc        staging svc deploy           hotfix/vX.Y.(Z+1)            production → staging
                   + RC release PR              (off tag)                    (syncs staging manifest)
                   → tag vX.Y.Z-rc.N

Changes

• release-please-config.staging.json + .release-please-manifest.staging.json (new): staging cuts vX.Y.Z-rc.N GitHub prereleases. versioning: prerelease so successive merges bump rc.N only. release-type: simple + separate CHANGELOG-rc.md so pyproject.toml is never touched on staging (1.2.0-rc.1 is not PEP 440 valid and would break uv export in CD_staging) and promotion merges don't conflict on version files.
• release-please-config.json: removed stray prerelease: true/prerelease-type: rc (wrong for stable releases).
• release-please.yml: runs on staging too, selecting config/manifest by branch. deploy-production and forward-merge gated with github.ref_name != 'staging' — RC releases never deploy production.
• forward-merge.yml (new): after a stable release, opens production → staging back-merge PR with the staging manifest synced to the released version; after a hotfix release, opens hotfix/vX.Y.Z → production PR. workflow_dispatch fallback for manual runs (used to propagate a hotfix from production to staging). Fails loudly with instructions on merge conflict — never forces.
• hotfix-start.yml: summary text updated (forward-merge PR now automatic).
• docs/release-flow.md (new, force-added — docs/ is gitignored but refine-json-filters-and-virtual-fields.md set precedent): branch roles, lifecycles, version-file ownership, conflict rules, caveats.

Caveats / follow-ups

• FORWARD_MERGE_TOKEN secret recommended: PRs created with default GITHub_TOKEN don't trigger pull_request workflows (no CI on automated PRs). Fine-grained PAT or GitHub App token with contents: write + pull-requests: write. Falls back to GITHUB_TOKEN (close/reopen PR to kick CI).
• Needs a production → staging back-merge first: staging's history doesn't contain the v1.1.0 tag commit yet; staging release-please needs it to bound its commit scan. Merge a production → staging PR (or run the new forward-merge workflow with source_branch=production, tag_name=v1.1.0 once this lands).
• Production-side behavior (deploy gate, forward-merge trigger) goes live only after this reaches production; staging RC behavior is live on merge.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1f163926be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Implements a staged release workflow using release-please: RC prereleases on staging, stable releases on production/hotfix/*, and automated PRs to keep staging/production/hotfix branches converged. Adds documentation describing branch roles and the end-to-end release/hotfix lifecycle.

Changes:

• Add staging-specific release-please config + manifest to cut vX.Y.Z-rc.N prereleases without touching pyproject.toml.
• Update release-please.yml to run on staging and to invoke a new branch-convergence workflow after stable/hotfix releases.
• Add forward-merge.yml reusable workflow to open automated back/forward-merge PRs; add docs describing the full flow.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
release-please-config.staging.json	Adds staging RC prerelease configuration (simple release type + RC changelog).
release-please-config.json	Removes prerelease settings so production releases stay stable.
docs/release-flow.md	Documents the release/promotion/hotfix flow and version-file ownership rules.
.release-please-manifest.staging.json	Introduces independent staging version state for RC computation.
.github/workflows/release-please.yml	Runs release-please on staging and gates deploy/merge automation to non-staging releases.
.github/workflows/hotfix-start.yml	Updates guidance text to reflect the new automated merge PR behavior.
.github/workflows/forward-merge.yml	Adds workflow to open production → staging and hotfix/* → production PRs post-release.