workflows: minimal structured header comments (reference for the fleet rework)

.github/workflows/merge-bot-pull-request.yml

@@ -1,19 +1,17 @@
 name: Merge bot pull request action
 
-# Enable auto-merge once per PR on opened/reopened; disable it when a maintainer pushes to a bot branch. Merge
-# method by base branch (develop = squash, main = merge). App token so the merge fires downstream workflows
-# (GITHUB_TOKEN pushes don't) and so the disable job has write access on read-only Dependabot PRs.
-
-# `pull_request_target` (not `pull_request`): these jobs hold the App private key, so the workflow definition and
-# its action SHAs must resolve from the trusted base branch, not the PR head. Safe because no job checks out PR
-# code - each only runs `gh pr merge` against the PR by URL.
+# Auto-merges in-repo bot PRs (Dependabot, codegen): enable on opened/reopened, disable on a maintainer push.
+# - Merge method by base: develop = squash, main = merge.
+# - App token, not GITHUB_TOKEN: fires downstream workflows on merge, and grants write on read-only Dependabot PRs.
+# - pull_request_target, not pull_request: jobs hold the App key, so the workflow + action SHAs resolve from the
+#   trusted base, not PR head. Safe because no job checks out PR code (each runs gh pr merge by URL).
 on:
   pull_request_target:
     types: [opened, reopened, synchronize]
 
-# Per-PR group: under `pull_request_target` `github.ref` is the base branch, which would serialize every bot PR
-# against that base; key on the PR number so each PR's events queue independently. `cancel-in-progress: false` so a
-# follow-up synchronize doesn't cancel an in-flight `opened` run before it enables auto-merge.
+# Concurrency keys on the PR number, not github.ref (the base branch under pull_request_target, which would
+# serialize every bot PR against it), so each PR queues independently. cancel-in-progress: false so a follow-up
+# synchronize doesn't cancel an in-flight opened run before it enables auto-merge.
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
   cancel-in-progress: false
@@ -146,7 +144,7 @@ jobs:
     name: Disable auto-merge on maintainer push job
     runs-on: ubuntu-latest
     # Fires when a maintainer pushes to a bot's branch (synchronize, actor != bot). Disables auto-merge so the
-    # maintainer's commits don't merge with the bot's; they re-enable it manually. The disable call is idempotent.
+    # maintainer's commits don't merge with the bot's, and they re-enable it manually. The disable call is idempotent.
     if: >-
       github.event.action == 'synchronize' &&
       github.event.pull_request.head.repo.full_name == github.repository &&

.github/workflows/publish-release.yml

@@ -3,8 +3,8 @@ name: Publish project release action
 on:
   workflow_dispatch:
 
-# A publish is a deliberate dispatch, so runs serialize on one group; queue rather than cancel so a run is never
-# left with a half-created GitHub release.
+# A publish is a deliberate dispatch, so runs serialize on one group and queue rather than cancel, so a run is
+# never left with a half-created GitHub release.
 concurrency:
   group: ${{ github.workflow }}
   cancel-in-progress: false
@@ -46,7 +46,7 @@ jobs:
         id: nbgv
         uses: dotnet/nbgv@master
 
-      # Skip create on an existing tag (no-op republish); a re-dispatch refreshes it.
+      # Skip create on an existing tag (no-op republish). A re-dispatch refreshes it.
       - name: Check for existing release step
         id: release-exists
         env: