Add the Staged Rollout Tracker and the Merge-Bot Caller Snippet

[ptr727]

What

• docs/reusable-workflows.md gains a Rollout section replacing the prose "Migration Phases": six stages (0 design and merge-bot task, 1 merge-bot adoption, 2 gates, 3 pure functions, 4 release chain and Docker core, 5 type-specific), each with hub, release, and per-repo adoption checkboxes. Items are ticked only with the evidence that closed them (PR, commit, tag, run URL), and the section opens with how a session resumes from it: read it first, take the first unchecked item in an open stage, verify against the tree, work in a worktree, tick in the same PR. Stage 0 is ticked with Host the Merge-Bot in the Hub and Measure Fleet Workflow Reuse #744, Promote develop to main After the Hub-Hosted Merge-Bot and the PhotoCleaner Report #746, and release 2.0.338, apart from the two live-proof items that wait on the next Dependabot PRs.
• catalog/snippets/workflows/merge-bot-pull-request.yml: the caller stub, now that 2.0.338 on 20616e0 carries merge-bot-task.yml. The pin resolves under repo_gate.py check_sha_pin. The doc's stub carries the same pin, and the catalog README gains the row.
• TODO.md: the cluster names the Rollout section as the state tracker and drops the snippet entry it just shipped.

Why

The plan lived as prose and as TODO entries, and nothing in git said which stage was done, so a cold session had no first unchecked item to take. Only git persists.

Verification

prose_lint (CI rule list), actionlint, markdownlint, repo_gate.py (the new pin resolved against GitHub), unit tests, audit self-test, build_dist --check.

[Copilot]

Pull request overview

This PR adds durable, git-tracked rollout state for the hub-hosted reusable-workflows migration and publishes the first downstream-facing catalog snippet for adopting the hub merge-bot task (now that a released hub pin exists).

Changes:

• Replace the prior “Migration Phases” prose with a checkbox-based “Rollout” tracker (stages 0-5) in docs/reusable-workflows.md, including evidence pointers per completed item.
• Add the merge-bot caller stub snippet to catalog/snippets/workflows/ and register it in the snippets README.
• Update TODO.md to treat the doc’s Rollout section as the canonical staged tracker and remove the now-shipped snippet TODO entry.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
TODO.md	Points readers to the new Rollout tracker as the authoritative staged state record.
docs/reusable-workflows.md	Introduces the staged Rollout tracker and updates merge-bot adoption guidance to a released pin.
catalog/snippets/workflows/README.md	Adds the merge-bot caller stub row to the snippets catalog index.
catalog/snippets/workflows/merge-bot-pull-request.yml	Adds the downstream caller stub snippet pinned to hub release 2.0.338.

Suppressed comments (1)

docs/reusable-workflows.md:215

• The Merge-Bot caller stub example enables a with: block with repo-specific values (ha-version-bump/, delete-branch: true). Since the surrounding text says the with: block is only needed for some repos, leaving it enabled by default makes the copy/paste stub incorrect for most adopters. Consider shipping the with: block as a commented-out template instead.

    uses: ptr727/ProjectTemplate/.github/workflows/merge-bot-task.yml@20616e0a70613ad8727d567990f5d0e082f5275c # 2.0.338
    secrets:
      CODEGEN_APP_CLIENT_ID: ${{ secrets.CODEGEN_APP_CLIENT_ID }}
      CODEGEN_APP_PRIVATE_KEY: ${{ secrets.CODEGEN_APP_PRIVATE_KEY }}
    # Only where the repo has a tracker outside the built-in pairs, or keeps auto-delete off and wants bot branches gone.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ptr727]

Answering the suppressed finding, "Suppressed comments (1)", from the round on ef6d605: docs/reusable-workflows.md:215, "The Merge-Bot caller stub example enables a with: block with repo-specific values ... leaving it enabled by default makes the copy/paste stub incorrect for most adopters". Fixed in 2f6ed9f: the stub in the doc no longer carries the with: block, it is byte-identical to the catalog snippet, and the ha-version-bump/ example is a separate fenced block described as what a repo appends when it needs either input.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

TODO.md:252

• This TODO entry still refers to "the phases" being in docs/reusable-workflows.md, but that doc now replaces "Migration Phases" with a staged "Rollout" section. Updating the terminology here avoids pointing readers at a heading that no longer exists.

One pull request per phase moving a standard workflow out of every repo and into the hub as a `workflow_call` task, with a downstream caller stub and a composite-action hook for what is genuinely repo-specific. The design, the hook contract, the pin policy and the phases are in [`docs/reusable-workflows.md`][reusable-workflows-doc], and the burn-down is [`reports/workflow-reuse.md`][workflow-reuse-report], regenerated by `python3 spec/workflow_reuse.py --report`. The merge-bot phase shipped with the design, so this cluster starts at the gates. The stage-by-stage completion state, one checkbox per hub change and per adopting repo with the evidence that closed it, is that doc's "Rollout" section, and a session resumes from there rather than from here.

docs/reusable-workflows.md:114

• Stage 0 item says it is closed "in the pull request that added this section", but the Rollout intro says each checked item should record concrete evidence (PR number, commit, tag, or run URL). This wording is not durable once the PR merges and does not meet that evidence standard; update the item to cite the PR number (and optionally the merge commit) that introduced the snippet/section.

- [x] The catalog caller snippet `catalog/snippets/workflows/merge-bot-pull-request.yml`, pinned to `20616e0` `# 2.0.338`, in the pull request that added this section.

[ptr727]

Answering the two suppressed findings, "Suppressed comments (2)", from the round on 2f6ed9f.

• TODO.md:252, "This TODO entry still refers to the phases being in docs/reusable-workflows.md, but that doc now replaces Migration Phases with a staged Rollout section". Fixed in 6eb723f: the cluster says stage and staged rollout throughout.
• docs/reusable-workflows.md:114, "Stage 0 item says it is closed in the pull request that added this section ... does not meet that evidence standard". Fixed in 6eb723f: the item now cites Add the Staged Rollout Tracker and the Merge-Bot Caller Snippet #748.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/reusable-workflows.md:138

• Stage 1 claims adoption tracking is "one checkbox per repo" (and Stage 1 is the per-repo work list), but this checklist item combines five repos into a single checkbox. That makes it impossible to record adoption evidence and completion state per repo, which is the stated purpose of the rollout tracker.

- [ ] AudioCleaner, DevKitCIoT, EspDinIoT, Financial-Modeling, HolidayLights carry no merge-bot today and take the stub on their next standup or resync, since the manifest applies it to every repo.

TODO.md:254

• This paragraph switches terminology from "phase" to "stage", but the last sentence still says "stub each phase introduces". That inconsistency makes the tracker harder to follow and is likely a leftover from the rename.

**State** `ready` for the gates, `blocked` on the gates for everything after. **Touches** the hub's `.github/workflows/`, [`spec/files.json`][files], [`catalog/snippets/workflows/`][workflows], and [`WORKFLOW.md`][workflow] where a guarantee names a copied job. **Cost** one hub edit per stage plus an adoption per repo on its next visit, and no re-vendor beyond the stub each phase introduces.

[ptr727]

Answering the two suppressed findings, "Suppressed comments (2)", from the round on 6eb723f.

• docs/reusable-workflows.md:138, "this checklist item combines five repos into a single checkbox". Fixed in 9d74ef8: AudioCleaner, DevKitCIoT, EspDinIoT, Financial-Modeling and HolidayLights each have their own checkbox.
• TODO.md:254, "the last sentence still says stub each phase introduces". Fixed in 9d74ef8: it reads stage, and no phase wording remains in the file.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/reusable-workflows.md:108

• The rollout tracker says "A stage has three parts" (Hub/Release/Adoption), but Stage 0 is immediately tracked with additional checkboxes (catalog snippet + two run-URL proofs). This reads as a contradiction and makes it harder to understand the intended structure of the checklist.

A stage has three parts. **Hub** is the hub pull request that ships the task and its stub. **Release** is the promotion and release that gives the task a pinnable `main` commit, since a downstream stub pins a released tag and nothing can adopt before one exists. **Adoption** is one checkbox per repo, ticked when that repo's ground-truth branch carries the stub and the audit reports no `interface` finding on the file. The exit metric per stage comes from [reports/workflow-reuse.md][workflow-reuse-report]: downstream copies of the stage's files fall to zero, callers rise to the number of repos that need the workflow, and downstream workflow lines fall from 10,964 toward the stubs plus the genuinely repo-specific hooks. Regenerate that report in the pull request that ticks a stage's last adoption, so the number and the tick land together.

TODO.md:252

• This paragraph says "The merge-bot stage shipped with the design", but the rollout doc now has both Stage 0 (merge-bot task) and Stage 1 (merge-bot adoption). Using "stage" here is ambiguous and can be misread as saying merge-bot adoption is already shipped.

One pull request per stage moving a standard workflow out of every repo and into the hub as a `workflow_call` task, with a downstream caller stub and a composite-action hook for what is genuinely repo-specific. The design, the hook contract, the pin policy and the staged rollout are in [`docs/reusable-workflows.md`][reusable-workflows-doc], and the burn-down is [`reports/workflow-reuse.md`][workflow-reuse-report], regenerated by `python3 spec/workflow_reuse.py --report`. The merge-bot stage shipped with the design, so this cluster starts at the gates. The stage-by-stage completion state, one checkbox per hub change and per adopting repo with the evidence that closed it, is that doc's "Rollout" section, and a session resumes from there rather than from here.

[ptr727]

Answering the two suppressed findings, "Suppressed comments (2)", from the round on 9d74ef8.

• docs/reusable-workflows.md:108, "The rollout tracker says A stage has three parts ... but Stage 0 is immediately tracked with additional checkboxes". Fixed in b5a8f35: the intro names the fourth kind, a proof item ticked with a run URL, states that the catalog snippet belongs to the hub items, and says stage 0 is the merge-bot's hub, release and proof items while stage 1 is its adoption.
• TODO.md:252, "The merge-bot stage shipped with the design ... can be misread as saying merge-bot adoption is already shipped". Fixed in b5a8f35: it reads that the task shipped and its adoption is a sweep.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/reusable-workflows.md:116

• The Stage 0 proof item’s fallback guidance is internally inconsistent with how GitHub Actions permissions work: setting permissions: {} “per callee job” cannot help if the failure is caused by an overly-restrictive caller grant. A more actionable sequence is to first drop the caller’s explicit empty permissions (use the default grant), and only then add the minimal scope needed (typically contents: read).

- [ ] The first Dependabot pull request against hub `develop` after `f33fa7e` merges through `merge-bot-task.yml`, proving the callee reads the caller's `pull_request_target` payload, the explicit `secrets:` map, App-token minting in a callee, and `permissions: {}` at the caller. Tick with the run URL. If it fails, the fallback order is `permissions: {}` per callee job, then `contents: read`.
- [ ] The first Dependabot pull request against hub `main` after `20616e0` merges with `--merge`. Tick with the run URL.

[ptr727]

Answering the suppressed finding, "Suppressed comments (1)", from the round on b5a8f35: docs/reusable-workflows.md:116, "setting permissions: {} per callee job cannot help if the failure is caused by an overly-restrictive caller grant". Fixed in 2cf5a57: the fallback is stated at the caller, replace permissions: {} with contents: read and widen only to what the failing run names, since a callee cannot widen what its caller grants. The same stale fallback in "What a Pilot Proves" is removed.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/reusable-workflows.md:114

• The Stage 0 checklist records the merge-bot release commit as a short SHA (20616e0), but the caller stub/snippet pin uses the full 40-character SHA. For this tracker (meant to be durable evidence), it would be clearer and less ambiguous to record the full SHA here as well, and keep the tag comment grouped with it.

- [x] Promoted to `main` in #746 (`20616e0`) and released as `2.0.338`, the first tag carrying `merge-bot-task.yml`.
- [x] The catalog caller snippet `catalog/snippets/workflows/merge-bot-pull-request.yml`, pinned to `20616e0` `# 2.0.338`, in #748, the pull request that added this section.

[ptr727]

Answering the suppressed finding, "Suppressed comments (1)", from the round on 2cf5a57: docs/reusable-workflows.md:114, "record the full SHA here as well, and keep the tag comment grouped with it". Fixed in 1aa853b: the snippet item records the pin as the full 40-character SHA with its tag comment, exactly as the stub carries it. The promotion item keeps the short SHA beside its pull request number, since #746 is the durable reference there.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.