From aac82a87575df1be97f9e6b1eb36e0f309c66f6e Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 9 Oct 2026 09:31:24 -0700 Subject: [PATCH 1/2] Add Proof Items for the Merge-Bot rules Input and merge-app Job The rules input and the merge-app job were owed proofs with no tracker item. Both proofs now sit under Stage 1, ticked with the homeassistant-purpleair run that showed them, and the pointers that named the issue as their tracker now name those items instead. Co-Authored-By: Claude Opus 5.5 --- TODO.md | 3 +-- docs/reusable-workflows.md | 6 ++++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/TODO.md b/TODO.md index 91712ff06..24f6c0112 100644 --- a/TODO.md +++ b/TODO.md @@ -421,7 +421,7 @@ Regenerate [reports/divergences.md][divergences-report] before using it as the w - **Rides with** - The `verbatim` re-vendor above. - **Detail** - The unused `GITHUB_TOKEN` grants #521 names are gone with the copy, since the task declares none and the stub sets `permissions: {}`. - **Detail** - Two repos filter Dependabot by ecosystem and semver tier, and per D8.1 the filter drops on adoption unless the open decision in the cluster above lands first. - - **Detail** - The hub cannot prove four things about the task. They are cross-repository resolution of the pin, the first Dependabot bump of it, the `rules` input end to end, and `merge-app` itself. The first two are proof items in `docs/reusable-workflows.md`, and [#2412][issue-2412] tracks the other two. + - **Detail** - The hub cannot prove four things about the task. They are cross-repository resolution of the pin, the first Dependabot bump of it, the `rules` input end to end, and `merge-app` itself. All four are proof items in the stage 1 list of [`docs/reusable-workflows.md`][reusable-workflows-doc], the first two owed by PhotoCleaner and the other two proved on homeassistant-purpleair. - **Carry the `Local Verification` heading into every repository's `OPERATIONS.md`.** The heading leads the file and states what verifying a change there requires, naming the part of the repo's contract CI structurally cannot exercise, and a repo whose gates are entirely in CI says that under it rather than omitting it. - **Hub state** - Done, verified `develop` at `8e10a2c` on 2026-08-06, where [`spec/section-model.md`][section-model] and [`STANDUP.md`][standup] declare six headings and this repo's own [`OPERATIONS.md`][operations] leads with the section. @@ -494,7 +494,6 @@ Regenerate [reports/divergences.md][divergences-report] before using it as the w [issue-623]: https://github.com/ptr727/ProjectTemplate/issues/623 [issue-633]: https://github.com/ptr727/ProjectTemplate/issues/633 [issue-1161]: https://github.com/ptr727/ProjectTemplate/issues/1161 -[issue-2412]: https://github.com/ptr727/ProjectTemplate/issues/2412 diff --git a/docs/reusable-workflows.md b/docs/reusable-workflows.md index 383bcdfa8..286581c82 100644 --- a/docs/reusable-workflows.md +++ b/docs/reusable-workflows.md @@ -128,6 +128,8 @@ Adoptable since `2.0.338`. Each repo replaces the whole of its `.github/workflow - [ ] Proof: Dependabot opens a `Bump ptr727/ProjectTemplate` PR on PhotoCleaner after the next hub release. Tick with the PR. - [x] HomeAutomation-Config (operational model at adoption, the direct-to-develop path, and release model since its 2026-09-24 reclassification): adopted on `develop` in ptr727/HomeAutomation-Config#58 at `d920805`, merged 2026-08-19 and carried on `main`, its ground-truth branch, where `merge-bot-pull-request.yml` calls `merge-bot-task.yml` by pin, and `python3 spec/audit.py HomeAutomation-Config` reports no `interface` finding on the file. - [ ] homeassistant-purpleair (third, `rules: '[{"head-prefix": "ha-version-bump/", "base": "develop"}]'` and `delete-branch: true`) +- [x] Proof: the `rules` input end to end. The stub landed on homeassistant-purpleair `develop` in ptr727/homeassistant-purpleair#371 at `532ab78`. The first App pull request its `check-ha-version.yml` tracker opened after that, ptr727/homeassistant-purpleair#417 from `ha-version-bump/matrix`, matches no built-in pair and merged to `develop` through the stub's `rules` entry on 2026-10-07 in [run-purpleair-417][run-purpleair-417]. +- [x] Proof: the `merge-app` job merges a pull request the App opened. The `Merge App pull request job` in [run-purpleair-417][run-purpleair-417] resolved the rule, minted the App token, and merged, and `app/ptr727-codegen` is the merger of record. - [ ] ESPHome-NonRoot (`delete-branch: true`, built-in upstream-version pairs cover its tracker) - [x] NxWitness (`delete-branch: true`, drops the Dependabot semver-major filter per D8.1 unless the open decision lands first): adopted on `develop` in ptr727/NxWitness#592 at `3c0ea13`, merged 2026-09-26 and carried on `main`, its ground-truth branch, where `merge-bot-pull-request.yml` calls `merge-bot-task.yml` by pin. - [x] KiCadLibrary: adopted with the semver-major filter dropped per D8.1, in ptr727/KiCadLibrary#59, promoted to `main` in ptr727/KiCadLibrary#65, where the `main` audit run 2026-10-04T01:15:54Z reports no `interface` finding. @@ -767,7 +769,7 @@ The task is .NET-specific orchestration. It installs the .NET SDK, runs the call The hub's own stub, which sets `delete-branch: true`, proves most of the mechanics on the first Dependabot pull request after the task lands on `develop`. That run shows the callee reading the caller's `github.event.*` under `pull_request_target`. It shows an explicit `secrets:` map reaching the callee and the App token minting inside one. It shows `permissions: {}` at the caller not failing the callee at startup, and `--squash` running on `develop`. A Dependabot pull request against `main` after promotion proves `--merge`, and a maintainer push to a bot branch proves the disable job. The first Dependabot pull request merged into `develop` once the delete job is there proves it, by the branch being gone afterwards. A hub feature branch cannot test itself, since under `pull_request_target` the callee resolves from the base branch, so the proof follows the merge rather than preceding it. -Four things the hub cannot prove fall to downstream adopters. They are cross-repository resolution of the owner-scoped `uses:` reference, Dependabot bumping a `# ` pin on a reusable workflow, and the `rules` input end to end on a repo with a tracker. The fourth is `merge-app` itself, since nothing opens App pull requests against the hub. The first two are proof items under Stage 1 above, and [#2412][issue-2412] tracks the other two. +Four things the hub cannot prove fall to downstream adopters. They are cross-repository resolution of the owner-scoped `uses:` reference, Dependabot bumping a `# ` pin on a reusable workflow, and the `rules` input end to end on a repo with a tracker. The fourth is `merge-app` itself, since nothing opens App pull requests against the hub. All four are proof items under Stage 1 above. PhotoCleaner owes the first two, and the other two were proved on homeassistant-purpleair. ## Open Decisions @@ -796,7 +798,6 @@ Four things the hub cannot prove fall to downstream adopters. They are cross-rep [issue-942]: https://github.com/ptr727/ProjectTemplate/issues/942 [issue-2031]: https://github.com/ptr727/ProjectTemplate/issues/2031 [issue-2336]: https://github.com/ptr727/ProjectTemplate/issues/2336 -[issue-2412]: https://github.com/ptr727/ProjectTemplate/issues/2412 [no-build-caller-snippet]: ../catalog/snippets/workflows/test-pull-request.yml [override-path-run]: https://github.com/ptr727/ProjectTemplate/actions/runs/31950332387/job/95172710046 [pilot-publish-run]: https://github.com/ptr727/PhotoCleaner/actions/runs/31977092102 @@ -807,6 +808,7 @@ Four things the hub cannot prove fall to downstream adopters. They are cross-rep [run-cross-repo-secret-probe]: https://github.com/ptr727/Blog/actions/runs/32618245296 [run-770]: https://github.com/ptr727/ProjectTemplate/actions/runs/31972611554 [run-771]: https://github.com/ptr727/ProjectTemplate/actions/runs/31972622149 +[run-purpleair-417]: https://github.com/ptr727/homeassistant-purpleair/actions/runs/37581098442 [run-startup-failure]: https://github.com/ptr727/ProjectTemplate/actions/runs/31972504539 [secrets]: ../spec/secrets.json [todo]: ../TODO.md From 0ff42fbd2b1d722ce11a64874cf8798d5162e455 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 9 Oct 2026 09:36:03 -0700 Subject: [PATCH 2/2] Describe the merge-app Proof as Enabling Auto-Merge The merge step enables auto-merge rather than merging inside the run, so the proof items now say that and name the merge separately. The pointer prose also says which repository each proof item names rather than which one owes it. Co-Authored-By: Claude Opus 5.5 --- TODO.md | 2 +- docs/reusable-workflows.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/TODO.md b/TODO.md index 24f6c0112..063128b6e 100644 --- a/TODO.md +++ b/TODO.md @@ -421,7 +421,7 @@ Regenerate [reports/divergences.md][divergences-report] before using it as the w - **Rides with** - The `verbatim` re-vendor above. - **Detail** - The unused `GITHUB_TOKEN` grants #521 names are gone with the copy, since the task declares none and the stub sets `permissions: {}`. - **Detail** - Two repos filter Dependabot by ecosystem and semver tier, and per D8.1 the filter drops on adoption unless the open decision in the cluster above lands first. - - **Detail** - The hub cannot prove four things about the task. They are cross-repository resolution of the pin, the first Dependabot bump of it, the `rules` input end to end, and `merge-app` itself. All four are proof items in the stage 1 list of [`docs/reusable-workflows.md`][reusable-workflows-doc], the first two owed by PhotoCleaner and the other two proved on homeassistant-purpleair. + - **Detail** - The hub cannot prove four things about the task. They are cross-repository resolution of the pin, the first Dependabot bump of it, the `rules` input end to end, and `merge-app` itself. All four are proof items in the stage 1 list of [`docs/reusable-workflows.md`][reusable-workflows-doc], the first two naming PhotoCleaner and the other two citing a homeassistant-purpleair run. - **Carry the `Local Verification` heading into every repository's `OPERATIONS.md`.** The heading leads the file and states what verifying a change there requires, naming the part of the repo's contract CI structurally cannot exercise, and a repo whose gates are entirely in CI says that under it rather than omitting it. - **Hub state** - Done, verified `develop` at `8e10a2c` on 2026-08-06, where [`spec/section-model.md`][section-model] and [`STANDUP.md`][standup] declare six headings and this repo's own [`OPERATIONS.md`][operations] leads with the section. diff --git a/docs/reusable-workflows.md b/docs/reusable-workflows.md index 286581c82..f484c9f20 100644 --- a/docs/reusable-workflows.md +++ b/docs/reusable-workflows.md @@ -128,8 +128,8 @@ Adoptable since `2.0.338`. Each repo replaces the whole of its `.github/workflow - [ ] Proof: Dependabot opens a `Bump ptr727/ProjectTemplate` PR on PhotoCleaner after the next hub release. Tick with the PR. - [x] HomeAutomation-Config (operational model at adoption, the direct-to-develop path, and release model since its 2026-09-24 reclassification): adopted on `develop` in ptr727/HomeAutomation-Config#58 at `d920805`, merged 2026-08-19 and carried on `main`, its ground-truth branch, where `merge-bot-pull-request.yml` calls `merge-bot-task.yml` by pin, and `python3 spec/audit.py HomeAutomation-Config` reports no `interface` finding on the file. - [ ] homeassistant-purpleair (third, `rules: '[{"head-prefix": "ha-version-bump/", "base": "develop"}]'` and `delete-branch: true`) -- [x] Proof: the `rules` input end to end. The stub landed on homeassistant-purpleair `develop` in ptr727/homeassistant-purpleair#371 at `532ab78`. The first App pull request its `check-ha-version.yml` tracker opened after that, ptr727/homeassistant-purpleair#417 from `ha-version-bump/matrix`, matches no built-in pair and merged to `develop` through the stub's `rules` entry on 2026-10-07 in [run-purpleair-417][run-purpleair-417]. -- [x] Proof: the `merge-app` job merges a pull request the App opened. The `Merge App pull request job` in [run-purpleair-417][run-purpleair-417] resolved the rule, minted the App token, and merged, and `app/ptr727-codegen` is the merger of record. +- [x] Proof: the `rules` input end to end. The stub landed on homeassistant-purpleair `develop` in ptr727/homeassistant-purpleair#371 at `532ab78`. The first App pull request its `check-ha-version.yml` tracker opened after that is ptr727/homeassistant-purpleair#417 from `ha-version-bump/matrix`. No built-in pair matches that head, and the stub's `rules` entry matched it in [run-purpleair-417][run-purpleair-417]. +- [x] Proof: the `merge-app` job merges a pull request the App opened. The `Merge App pull request job` in [run-purpleair-417][run-purpleair-417] resolved the rule and enabled auto-merge under the App token. `app/ptr727-codegen` merged ptr727/homeassistant-purpleair#417 to `develop` on 2026-10-07. - [ ] ESPHome-NonRoot (`delete-branch: true`, built-in upstream-version pairs cover its tracker) - [x] NxWitness (`delete-branch: true`, drops the Dependabot semver-major filter per D8.1 unless the open decision lands first): adopted on `develop` in ptr727/NxWitness#592 at `3c0ea13`, merged 2026-09-26 and carried on `main`, its ground-truth branch, where `merge-bot-pull-request.yml` calls `merge-bot-task.yml` by pin. - [x] KiCadLibrary: adopted with the semver-major filter dropped per D8.1, in ptr727/KiCadLibrary#59, promoted to `main` in ptr727/KiCadLibrary#65, where the `main` audit run 2026-10-04T01:15:54Z reports no `interface` finding. @@ -769,7 +769,7 @@ The task is .NET-specific orchestration. It installs the .NET SDK, runs the call The hub's own stub, which sets `delete-branch: true`, proves most of the mechanics on the first Dependabot pull request after the task lands on `develop`. That run shows the callee reading the caller's `github.event.*` under `pull_request_target`. It shows an explicit `secrets:` map reaching the callee and the App token minting inside one. It shows `permissions: {}` at the caller not failing the callee at startup, and `--squash` running on `develop`. A Dependabot pull request against `main` after promotion proves `--merge`, and a maintainer push to a bot branch proves the disable job. The first Dependabot pull request merged into `develop` once the delete job is there proves it, by the branch being gone afterwards. A hub feature branch cannot test itself, since under `pull_request_target` the callee resolves from the base branch, so the proof follows the merge rather than preceding it. -Four things the hub cannot prove fall to downstream adopters. They are cross-repository resolution of the owner-scoped `uses:` reference, Dependabot bumping a `# ` pin on a reusable workflow, and the `rules` input end to end on a repo with a tracker. The fourth is `merge-app` itself, since nothing opens App pull requests against the hub. All four are proof items under Stage 1 above. PhotoCleaner owes the first two, and the other two were proved on homeassistant-purpleair. +Four things the hub cannot prove fall to downstream adopters. The first is cross-repository resolution of the owner-scoped `uses:` reference. The second is Dependabot bumping a `# ` pin on a reusable workflow. The third is the `rules` input end to end on a repo with a tracker. The fourth is `merge-app` itself, since nothing opens App pull requests against the hub. All four are proof items under Stage 1 above. The first two name PhotoCleaner, and the other two carry a homeassistant-purpleair run. ## Open Decisions