Track template-convergence review findings

[ptr727]

Context

Codex re-reviewed the current template-alignment PR heads across the scoped repos after the downstream agents marked them ready for review. This issue is a hub checklist for findings that remain after that pass, plus template/generalization questions that should be decided upstream before downstreams converge again.

Reviewed alignment PR heads:

• ProjectTemplate PR Template convergence barrier: absorb pins, generic release + docker-readme, carry-whole-file #207 template-convergence at 0527b6236bc5075a60e33e92ade46984372f9fec
• Utilities PR Make carried template docs repo-agnostic; codify the no-cross-reference rule #344 chore/sync-template at e3621ef86ce50f39d4af86a4536215ad789e7723
• PlexCleaner PR Delete a Conflicting Sudo Timestamp Drop-In on Confirm #764 chore/sync-template at 98c719d591ab05faddfae4137753efea135012d3
• ESPHome-NonRoot PR Develop ruleset strict "branches up to date" flag stalls bot auto-merge when sibling PR lands mid-CI #82 chore/sync-template at 43d2d6a8e1dd9ceefbfec76bac8cd286a44227da
• VSCode-Server-DotNetCore PR Develop #49 chore/sync-template at 9b5b927226fc828add938054d69b230e63083e53
• KiCadLibrary PR Refactor merge conditions and enhance documentation #39 chore/sync-template at a0bdba0a1fd890c3877fb3166163f93286b3e3f4
• LanguageTags PR Harden merge gate + prerelease guard, and de-prose comments (#188, #189) #190 chore/sync-template at cfa8dcb4a18d4d1c457825633b4dc09978d6f3e9
• NxWitness PR Promote the config-repo convergence hub fixes to main (#447) #448 chore/sync-template at cdda57be4904c8c024d7acf6a8c71f1aa6b9d08c
• homeassistant-purpleair PR Update codegen files #149 chore/sync-template at 35d67dfcc24bb9b91fd228bbf9bcfc075cd71b61

Validation run: actionlint via rhysd/actionlint:latest was clean across all listed alignment branches.

Downstream fixes still needed

• PlexCleaner: merge-bot workflow is still on the old shape.

  • Current file: PlexCleaner/.github/workflows/merge-bot-pull-request.yml lines 3-9 still use pull_request, group: ${{ github.workflow }}-${{ github.ref }}, and cancel-in-progress: true.
  • It also lacks the template's opened/reopened-only merge guard and disable-auto-merge-on-maintainer-push job.
  • Suggested correction: carry/adapt the current ProjectTemplate merge-bot-pull-request.yml shape: pull_request_target, per-PR concurrency on ${{ github.event.pull_request.number }}, cancel-in-progress: false, opened/reopened guards, and maintainer-push disable logic. Keep only the repo's genuine target set.

• Utilities: publish artifacts are not cleaned up.

  • Current file: Utilities/.github/workflows/build-nugetlibrary-task.yml uploads release-asset-${{ inputs.branch }}-nugetlibrary, but Utilities/.github/workflows/publish-release.yml has no terminal cleanup-artifacts job.
  • Suggested correction: add the template terminal cleanup job to publish-release.yml with needs covering setup, publish, and date-badge, if: ${{ always() && needs.setup.outputs.publish == 'true' }}, permissions: actions: write, and best-effort REST deletion.

• PlexCleaner: publish artifacts are not cleaned up.

  • Current files: PlexCleaner/.github/workflows/build-executable-task.yml uploads both matrix build artifacts and release-asset-${{ inputs.branch }}-executable; build-toolversions-task.yml uploads versions-*; but PlexCleaner/.github/workflows/publish-release.yml has no terminal cleanup-artifacts job.
  • Suggested correction: add the template terminal cleanup job with needs covering setup, publish, tool-versions, docker-readme, and date-badge, gated by always() && needs.setup.outputs.publish == 'true'.

• homeassistant-purpleair: BYOB action is still tag-pinned and the comment is stale.

  • Current file: homeassistant-purpleair/.github/workflows/build-datebadge-task.yml lines 35-38 says BYOB is not SHA-pinnable and uses RubbaBoy/BYOB@v1.
  • Current template pins it as RubbaBoy/BYOB@a4919104bc0ec7cfd7f113e42c405cc45246f2a4 # v1.
  • Suggested correction: replace the floating tag with the template SHA pin and remove the stale comment.

Template/generalization questions

• Clarify whether action pinning applies to repo-owned build-layer leaves.

  • ProjectTemplate AGENTS.md says every action must be SHA-pinned except dotnet/nbgv@master.
  • NxWitness documents build-docker-task.yml, build-base-images-task.yml, and test-release-task.yml as repo-owned build-layer leaves whose action versions remain tag-owned and Dependabot-managed. Those files currently contain actions/checkout@v7, docker/setup-qemu-action@v4, docker/setup-buildx-action@v4, docker/login-action@v4, docker/build-push-action@v7, and actions/setup-dotnet@v5.
  • Suggested upstream decision: either require SHA pinning in repo-owned build leaves too, or document a narrow exception/ownership rule so downstream agents stop flagging this as drift.

• Clarify Docker cache policy for multi-image repos.

  • ProjectTemplate AGENTS.md says Docker layer cache should use registry tags, not type=gha, to avoid the 10 GB Actions cache.
  • NxWitness uses type=gha in its multi-image build leaves, including PR-scoped caches and per-image branch caches. It also uses one registry cache line for shared base images.
  • Suggested upstream decision: either migrate NxWitness to registry-backed per-image caches, or add a documented exception/general pattern for multi-image repos where registry cache tags are impractical or too expensive.

• Remove stale CODESTYLE droppable-section wording from downstream instructions.

  • Current ProjectTemplate CODESTYLE.md says the file is carried whole and unused language sections are inert.
  • Some downstream AGENTS text still says language sections are droppable or instructs re-syncing then dropping unused language sections. Examples found: Utilities, PlexCleaner, KiCadLibrary, VSCode-Server-DotNetCore.
  • Suggested correction: converge downstream AGENTS text on the current carry-whole-file model, or update the template if droppable language sections are still meant to be supported.

Notes

• This issue intentionally separates downstream fixes from upstream policy questions. If a policy question is resolved upstream, downstreams should reapply the template decision rather than maintaining private exceptions.
• No file changes were made by Codex during this review pass.

[ptr727]

All items addressed on the alignment branches; actionlint clean on every changed workflow, markdownlint clean on changed docs.

Downstream fixes

• PlexCleaner merge-bot -> current shape. pull_request_target, per-PR concurrency on github.event.pull_request.number, cancel-in-progress: false, opened/reopened guard, and the disable-auto-merge-on-maintainer-push job; pruned merge-codegen/merge-upstream-version (this repo has neither mechanism). Also corrected the now-stale AGENTS Branching Model description (maintainer push now disables auto-merge). — PlexCleaner 7e9e2f3
• Utilities publish-release cleanup. Added the terminal cleanup-artifacts job (needs: [setup, publish, date-badge]). — Utilities dec3a82
• PlexCleaner publish-release cleanup. Added it (needs: [setup, publish, tool-versions, docker-readme, date-badge]). — PlexCleaner d873e03
• homeassistant BYOB. SHA-pinned RubbaBoy/BYOB@a4919104... # v1; removed the false "not SHA-pinnable" comment. — homeassistant c0a6116

Template/generalization decisions (resolved upstream)

• Action pinning in build-layer leaves -> SHA-pin everywhere. NxWitness build leaves SHA-pinned (checkout v7.0.0, setup-dotnet v5.3.0, docker setup-qemu v4.1.0 / setup-buildx v4.1.0 / login v4.2.0 / build-push v7.2.0). Template AGENTS clarified the rule covers repo-owned build leaves (Dependabot still bumps SHA pins). — NxWitness 67b3d9b, template dd9dbec
• Docker cache for multi-image -> migrate to registry caches. build-docker-task + build-base-images-task now use type=registry buildcache tags (docker.io/ptr727/<repo>:buildcache-<branch>, plus the base tag + inline) instead of type=gha; all best-effort (ignore-error=true). Template AGENTS clarified the per-image multi-image pattern. — NxWitness 472f4a7, template dd9dbec
• Stale CODESTYLE droppable-section wording -> carry-whole. Converged the downstream AGENTS text. — Utilities 859f19e, PlexCleaner 8ed3d24, KiCadLibrary 5d0de37, VSCode-Server 9eaf92d