Reconcile the release-pipeline canonical (github-release job) - 4 open questions

[ptr727]

Context

PhotoCleaner and PlexCleaner both ship a github-release job (in build-release-task.yml) that diverges from the canonical catalog/snippets/workflows/build-release-task.yml, and the audit flags that job verbatim. Investigating the divergence, plus the PhotoCleaner agent's live-release feedback (PhotoCleaner#14), surfaced four interacting questions. They should be reconciled together before any repo re-vendors the job - a naive re-vendor of the current canonical would drop the prerelease backstop the repos already carry (Q1), which is a regression.

This blocks the github-release re-vendor in the PlexCleaner cleanup (PlexCleaner#880 item B1) and the equivalent PhotoCleaner drift.

Questions

Q1 - Adopt the prerelease backstop. Both repos carry a main-only step ("Verify public release version") that refuses to publish when SemVer2's core segment carries a - (NBGV prerelease mis-versioning). The canonical lacks it, and it looks like a genuine safety improvement. Proposal: adopt it into the canonical, standardized to set -Eeuo pipefail (PlexCleaner uses -euo, PhotoCleaner -Eeuo), and recast the ::error:: message's clause-splicing semicolon.

Q2 - expect_release_assets direction. The canonical parameterizes the download guard, fail_on_unmatched_files, and the asset-cleanup gate via inputs.expect_release_assets, so a no-file-target repo (Docker-only) can relax the guard. Both repos instead hardcode fail_on_unmatched_files: true, always download, and carry terser comments. The parameterization is the more correct design. Proposal: keep it, and the repos re-vendor to adopt it and restore the verbose comments.

Q3 - The SHA-verbatim tension (the real structural issue). The job is declared fidelity: interface, but the contract pins verbatimJobs: ["github-release"], and normalize() masks no action SHAs. So every release repo's live workflow perpetually "differs from the canonical" after any Dependabot action-SHA bump - the check can never stay green across the fleet. Decide one of: (a) mask uses: ...@<sha> action pins in normalize() for verbatim job regions, so SHA-only drift is tolerated while structure is still enforced, or (b) drop the job from verbatimJobs and rely on the interface contract's token checks (required jobs, pattern: / merge-multiple: present, artifact-ids: forbidden). Option (a) keeps byte-fidelity on the orchestration logic while tolerating the one field Dependabot owns, and is likely the right call.

Q4 - Build-success gating (PhotoCleaner finding 5). The job's if: ${{ inputs.github && !inputs.smoke }} does not depend on the build jobs succeeding. The canonical and both repos agree, so this is a pure design question: intentional (a degraded release is still tagged), or should it gate on needs success? No downstream drift either way - decide and document.

Not a question (resolved)

The PhotoCleaner agent's finding 7 - per-runtime publish-<runtime> intermediates reaped only by retention-days: 1 rather than surgically deleted - is not a gap. WORKFLOW.md D5.1 explicitly permits an in-run intermediate to rely on the retention backstop (lines 98, 174, 230, 273). The surgical delete rule applies to the cross-job release-asset-*, which is deleted. No change.

Outcome

Once Q1-Q3 land in the canonical and Q4 is decided and documented, the two repos re-vendor the github-release job once, clean.

[ptr727]

Maintainer direction (decisions)

Q1 - Adopt the backstop, made symmetric and branch-restricted. Enforce the release-version invariant both ways, and restrict which branches may publish:

• main release version core MUST NOT carry a - (it is a release version)
• develop release version core MUST carry a - (it is a prerelease)
• any other branch: refuse - only main and develop may publish

The version check lives in the github-release job. The "only main/develop" whitelist goes earlier, so a stray dispatch on a feature branch is stopped before any publish job runs, not just before the github release. Standardize on set -Eeuo pipefail and recast the ::error:: message's clause-splicing semicolon.

Q2 - Keep the expect_release_assets parameterization. Every release floor is the auto source zip + LICENSE + README. expect_release_assets: true adds built binary assets (guard fail_on_unmatched_files: true enforced), false is the no-binary case (Docker-only). The repos re-vendor to adopt it and restore the verbose comments.

Q3 - Mask action SHAs in normalize() for verbatim job regions. A Dependabot uses: ...@<sha> bump no longer breaks the verbatim check, while the orchestration structure still is enforced.

Q4 - Full publish atomicity. Any enabled build failure blocks ALL publish targets - github release + git tag, docker push, nuget/pypi push - all-or-nothing. Today the github release/tag already gates on every build (via needs, no always() on the path), but docker/nuget/pypi push in their own jobs gated only on validate + version, so a failure in a different build still lets them push. Fix: gate every publish action on all enabled builds succeeding (separate build from publish so the publish phase sits behind the all-builds-green gate), and document it as a WORKFLOW.md guarantee.

Not a question (resolved): finding 7 (per-runtime intermediate cleanup) - D5.1 already permits an in-run intermediate to rely on the retention-days: 1 backstop. No change.

Sequencing

• Q3 is a contained audit change (normalize() SHA masking) - lands on its own.
• Q1 + Q2 + Q4 all touch the release pipeline and will land together in one canonical reconciliation, so the fleet re-vendors the release workflow once. Q4's build/publish split is the architectural piece and gets designed before the PR.
• Downstream repos (PlexCleaner #880 B1, PhotoCleaner) hold the github-release re-vendor until the canonical reconciliation lands.

[ptr727]

Correction and resolution

Reading the full canonical release task (not just the github-release job region I had diffed) corrects this issue's premise:

• Q1 - already implemented. The symmetric backstop is the validate-release entry-gate job in build-release-task.yml (WORKFLOW.md D2.2): main must be a release version, develop must be a prerelease, skipped on smoke. The "only main/develop may publish" whitelist is already enforced in publish-plan-task.yml (D2.3). So there was nothing to add. The repos (PhotoCleaner/PlexCleaner) carry the older pattern - that check as a step inside github-release - which is why the github-release verbatim check flags them. They are behind the canonical, and re-vendoring is an upgrade, not a regression. My earlier "the canonical lacks the backstop" was wrong.
• Q2 - already implemented. expect_release_assets is already an input, gating the asset download and relaxing fail_on_unmatched_files for a no-file-target repo.
• Q3 - done in Neutralize Dependabot action pins in verbatim normalization (#414 Q3) #415. normalize() masks Dependabot action pins in verbatim regions, so a SHA bump no longer drifts the verbatim github-release region.
• Q4 - done in Gate the Docker push on all builds; require validate-release (#414 Q4) #417. Full publish atomicity: build-docker now needs every build (the fleet-fit single-pusher gate), so a build failure blocks the image push, matching github-release. Documented as D4.5. The interface contract now also requires validate-release, to flag the older repos to adopt the entry-gate job.
• Finding 7 (intermediate artifact cleanup) - not a gap, per D5.1's in-run carve-out.

Net: Q1/Q2 were pre-existing, Q3 (#415) and Q4 (#417) land the remainder. Will close once #417 promotes to main.

[ptr727]

Landed on main via #418 (merge b41354b). Q3 (#415) and Q4 (#417) shipped; Q1/Q2 were pre-existing. The release-pipeline canonical is reconciled and the interface contract now requires validate-release. Closing.