v0.5.1 sprint: token override + Layer 2 race + stale PR cleanup + branch-protection doc correction (path α dogfood) #88

New issue

Closed

opened 2026-06-26 01:05:39 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-26 01:05:39 +02:00

Owner

Sprint scope

v0.5.1 substrate-correction sprint — bundles the operator-actions hygiene catches from the v0.5.0 cut + the docs accuracy gap from slice 5. Operator chose path (α) "use release-bot" over path (β) "accept graceful-degradation" on 2026-06-26 for the toolkit's own substrate (existing release-bot user already provisioned on the instance suggests this was the intended pattern).

Items

1. Token override in `_release.yml` (the path-α substrate change)

Allow _release.yml to use a consumer-supplied PAT for the merge operation instead of the synthetic GITHUB_TOKEN. The consumer wires this PAT into their workflow secrets.RELEASE_TOOLKIT_TOKEN (or similar), and:

# In _release.yml's act-on-decision step env:
env:
  FORGEJO_TOKEN: ${{ secrets.RELEASE_TOOLKIT_TOKEN || secrets.GITHUB_TOKEN }}

The fallback to GITHUB_TOKEN preserves backward compatibility — consumers without the secret keep the graceful-degradation behavior.

Requires:

_release.yml script change + workflow_call input declaration for the optional secret
docs/integration.md update explaining the override + how to provision a non-admin bot user (e.g., release-bot)
Toolkit's own consumer-side release.yml updated to pass secrets.RELEASE_TOOLKIT_TOKEN
Operator provisions release-bot PAT + stores in toolkit repo secrets
Toolkit's main branch protection: add release-bot to push_whitelist_usernames

2. Layer 2 race-condition fix (closes #86)

forgejo_find_pr_by_merge_sha lookup lags ~8s behind a fresh merge — empirically falsified on the v0.5.0 cut. Surveyor's #64 deferred test coverage was specifically about this.

Lean (A) from #86: retry with backoff (3 retries × 5s = 15s budget). Preserves substrate-honest fall-through when retry budget exhausted.

3. Stale rolling PR cleanup after fall-through+later-cut-success (closes #87)

Operator's "stairway to version hell" framing: when Layer 2 fall-through opens a rolling PR + the cut later succeeds, the fall-through-opened rolling PR is left open as confusing stale state.

Lean from #87: defense-in-depth — (a) _release.yml cut path closes any open rolling PR matching the just-cut version + (b) release-prep.sh --rolling-mode short-circuits when manifest already reflects the proposed cut version.

4. §Branch protection compatibility doc correction

My slice-5 docs claimed forgejo-actions could be whitelisted directly. It can't — forgejo-actions is a synthetic actor (uid: -2), not a real user; Forgejo's push_whitelist_usernames rejects it with user does not exist. Surveyor's 8701 catch was on the apply_to_admins inversion; the (a) whitelist option as written turned out also to be slightly fictional re: feasibility.

Per feedback_filed_rootcause_is_hypothesis + AGENTS.md §8 (which already lists 8701 as the worked instance): I asserted the whitelist mechanism without verifying it accepts the actions identity.

Correction in v0.5.1 docs:

Replace (a) "whitelist forgejo-actions" with (a-revised) "create a non-admin bot user (e.g., release-bot), provision its PAT, add it to push_whitelist + use the token override from item 1"
Update (b) to clarify it's still an option (admin-scope) for consumers who prefer the heaviest path
Add (c) accept the graceful-degradation pattern (the toolkit's pre-v0.5.1 substrate)
Update AGENTS.md §8 with a 4th empirical instance: the (a) doc-claim itself (n=4 instances now: 5bbe, 6a82, 8701-apply_to_admins, the (a)-fictional-whitelist-recursive)

5. Test coverage that would have caught this

#64 Layer-2/3 FAIL-path coverage gets implemented as part of v0.5.1 — bundles naturally with #86's fix.

Sequencing

Layer 2 race fix (#86) + #64 test coverage — substrate-correctness foundation
Token override mechanism + workflow_call wiring
Stale PR cleanup (#87)
Docs correction + AGENTS.md §8 update
Operator provisions release-bot PAT + repo secret + push_whitelist
v0.5.1 cut — first cut with fully autonomous (α) path on the toolkit itself

What this PR does NOT do

Does not address #56 (manifest-vs-history defensive guard) — separate substrate-correctness item, may bundle with v0.5.2 if budget allows
Does not address #54 (line-break cosmetic) — workaround exists, low priority
Does not address #47 (Forgejo Actions trusted-proxy trap) — research observation
Does not change the (B) manifest-via-PR mechanic — token-override is additive; the PR + auto-merge flow stays the same, just uses a different identity for the merge call

Closes

#86 (Layer 2 race condition)
#87 (stale rolling PR cleanup)
#64 (Layer-2/3 FAIL-path test coverage)

Refs

Path (α) operator selection: 2026-06-26 (this thread)
Surfaced: v0.5.0 cut substrate-honest catches
Prior carry-forward instances: the cycle continues — v0.5.0 surfaced 2 substrate-bugs (race + stale-PR), v0.5.1 will surface its own (the carry-forward pattern's prediction)
Slice-5 docs accuracy: my own claim about (a) whitelist mechanism was fictional in feasibility — AGENTS.md §8 will document the meta-lesson

Filed 2026-06-26 post-v0.5.0 GA.

## Sprint scope v0.5.1 substrate-correction sprint — bundles the operator-actions hygiene catches from the v0.5.0 cut + the docs accuracy gap from slice 5. Operator chose **path (α) "use release-bot"** over **path (β) "accept graceful-degradation"** on 2026-06-26 for the toolkit's own substrate (existing `release-bot` user already provisioned on the instance suggests this was the intended pattern). ## Items ### 1. Token override in `_release.yml` (the path-α substrate change) Allow `_release.yml` to use a consumer-supplied PAT for the merge operation instead of the synthetic `GITHUB_TOKEN`. The consumer wires this PAT into their workflow `secrets.RELEASE_TOOLKIT_TOKEN` (or similar), and: ```yaml # In _release.yml's act-on-decision step env: env: FORGEJO_TOKEN: ${{ secrets.RELEASE_TOOLKIT_TOKEN || secrets.GITHUB_TOKEN }} ``` The fallback to `GITHUB_TOKEN` preserves backward compatibility — consumers without the secret keep the graceful-degradation behavior. Requires: - `_release.yml` script change + `workflow_call` input declaration for the optional secret - `docs/integration.md` update explaining the override + how to provision a non-admin bot user (e.g., `release-bot`) - Toolkit's own consumer-side `release.yml` updated to pass `secrets.RELEASE_TOOLKIT_TOKEN` - Operator provisions `release-bot` PAT + stores in toolkit repo secrets - Toolkit's `main` branch protection: add `release-bot` to `push_whitelist_usernames` ### 2. Layer 2 race-condition fix (closes #86) `forgejo_find_pr_by_merge_sha` lookup lags ~8s behind a fresh merge — empirically falsified on the v0.5.0 cut. Surveyor's #64 deferred test coverage was specifically about this. Lean (A) from #86: retry with backoff (3 retries × 5s = 15s budget). Preserves substrate-honest fall-through when retry budget exhausted. ### 3. Stale rolling PR cleanup after fall-through+later-cut-success (closes #87) Operator's "stairway to version hell" framing: when Layer 2 fall-through opens a rolling PR + the cut later succeeds, the fall-through-opened rolling PR is left open as confusing stale state. Lean from #87: defense-in-depth — (a) `_release.yml` cut path closes any open rolling PR matching the just-cut version + (b) `release-prep.sh --rolling-mode` short-circuits when manifest already reflects the proposed cut version. ### 4. §Branch protection compatibility doc correction My slice-5 docs claimed `forgejo-actions` could be whitelisted directly. **It can't** — `forgejo-actions` is a synthetic actor (uid: -2), not a real user; Forgejo's `push_whitelist_usernames` rejects it with `user does not exist`. Surveyor's 8701 catch was on the apply_to_admins inversion; the (a) whitelist option as written turned out also to be slightly fictional re: feasibility. Per `feedback_filed_rootcause_is_hypothesis` + AGENTS.md §8 (which already lists 8701 as the worked instance): I asserted the whitelist mechanism without verifying it accepts the actions identity. Correction in v0.5.1 docs: - Replace (a) "whitelist forgejo-actions" with (a-revised) "create a non-admin bot user (e.g., `release-bot`), provision its PAT, add it to push_whitelist + use the token override from item 1" - Update (b) to clarify it's still an option (admin-scope) for consumers who prefer the heaviest path - Add (c) accept the graceful-degradation pattern (the toolkit's pre-v0.5.1 substrate) - Update AGENTS.md §8 with a 4th empirical instance: the (a) doc-claim itself (n=4 instances now: 5bbe, 6a82, 8701-apply_to_admins, the (a)-fictional-whitelist-recursive) ### 5. Test coverage that would have caught this #64 Layer-2/3 FAIL-path coverage gets implemented as part of v0.5.1 — bundles naturally with #86's fix. ## Sequencing 1. Layer 2 race fix (#86) + #64 test coverage — substrate-correctness foundation 2. Token override mechanism + workflow_call wiring 3. Stale PR cleanup (#87) 4. Docs correction + AGENTS.md §8 update 5. Operator provisions `release-bot` PAT + repo secret + push_whitelist 6. v0.5.1 cut — first cut with fully autonomous (α) path on the toolkit itself ## What this PR does NOT do - **Does not address #56** (manifest-vs-history defensive guard) — separate substrate-correctness item, may bundle with v0.5.2 if budget allows - **Does not address #54** (line-break cosmetic) — workaround exists, low priority - **Does not address #47** (Forgejo Actions trusted-proxy trap) — research observation - **Does not change the (B) manifest-via-PR mechanic** — token-override is additive; the PR + auto-merge flow stays the same, just uses a different identity for the merge call ## Closes - #86 (Layer 2 race condition) - #87 (stale rolling PR cleanup) - #64 (Layer-2/3 FAIL-path test coverage) ## Refs - **Path (α) operator selection**: 2026-06-26 (this thread) - **Surfaced**: v0.5.0 cut substrate-honest catches - **Prior carry-forward instances**: the cycle continues — v0.5.0 surfaced 2 substrate-bugs (race + stale-PR), v0.5.1 will surface its own (the carry-forward pattern's prediction) - **Slice-5 docs accuracy**: my own claim about (a) whitelist mechanism was fictional in feasibility — AGENTS.md §8 will document the meta-lesson Filed 2026-06-26 post-v0.5.0 GA.

quartermaster referenced this issue from a commit

2026-06-26 01:21:28 +02:00

fix+feat: v0.5.1 substrate-correction sprint (closes #86 + #87 + #64)

quartermaster referenced this issue

2026-06-26 01:21:59 +02:00

fix+feat: v0.5.1 substrate-correction sprint (closes #86 + #87 + #64) #89