chore(release): v0.8.0 #116

Merged

alex merged 1 commit from release-prep/rolling into main

2026-06-26 16:53:30 +02:00

release-bot commented

2026-06-26 15:10:06 +02:00

Member

Added

AGENTS.md §8 Axis A grows from n=5 → n=7 across 4 → 5 structurally-distinct surfaces.

Two new empirical instances from the 2026-06-26 path (α) auto-merge investigation:

Instance 6: merge_whitelist-semantic-mis-mapping — joins the config-semantics surface (sibling to instance 2 apply_to_admins). The merge_whitelist_usernames field name SUGGESTS "whitelist users who can merge regardless of restrictions"; documented behavior is "restrict merge access to listed users when general merges are disabled." Inferred-from-name semantic was OPPOSITE of actual semantic. Empirical test confirmed by locking the admin caller out of merging.
Instance 7: self-approval-globally-hardcoded — NEW 5th surface (configurable-vs-hardcoded policy). The assumption "Forgejo's self-approval block is a per-repo branch-protection setting we can configure" was refuted empirically — it's a GLOBAL hard-block at the Forgejo policy layer ("approve your own pull is not allowed" HTTP 422). Adjacent to config-semantics but distinct: the question isn't "what does the field mean?" but "is this configurable AT ALL?"

Pattern strengthening at n=7 — added explicit guidance: after writing to a Forgejo field, READ IT BACK to verify the entry actually stuck + don't assume a behavior is per-repo configurable just because related behaviors are.

Two new calibration notes:

Lifecycle caveat — each instance is an observed-once external-system claim verified at the date noted; future Forgejo upgrades could change behavior. Same re-verify-against-LIVE-substrate discipline that produced them applies to consuming them.
Source-quotation as verification — re-verifying behavior that the source UI/docs EXPLICITLY states is over-applying Axis A. The discipline is verify-at-source for INFERRED claims, not for direct quotes from the live source. Worked instance 2026-06-26: when operator quoted the Forgejo UI text confirming release-bot's whitelist permission, asking for a further empirical probe would have been over-cautious — the UI configuration IS the live source.

This PR was originally scoped as the #112 review-gate tradeoff docs work. Operator's architectural question 2026-06-26 ("why a second PR at all? direct-push the manifest commit by release-bot") surfaced an ADR-0007 candidate that would dissolve the (2)/(3) tradeoff documented in the original PR scope. The §8 banks are useful regardless of ADR-0007's outcome (worked instances of the discipline that hold independently of the manifest-mechanism architecture), so this PR's scope was reduced to just the §8 banks. The integration.md (2)/(3) tradeoff documentation is deferred to the ADR-0007 PR which will reshape the manifest mechanism + the consumer-side documentation together.

ADR-0007 lands (docs/adr/0007-manifest-commit-direct-push.md): the manifest commit lifecycle splits along consumer setup. The PR mechanism introduced in #78 was a workaround for the pre-path-α push-permission gap; with path (α) wired, the cleaner direct-push path becomes the default.

Path (α) — release-bot configured: the workflow direct-pushes the manifest commit to main. No PR is opened. No second-PR click required per cut. Compatible with required_approvals > 0 on substantive PRs (the approval gate applies to PR merges, not whitelisted direct pushes).
Path (γ) — no bot setup: the workflow opens a release-toolkit/manifest-<TAG> PR and attempts auto-merge (existing v0.5.0+ behavior, unchanged). Operator manually merges if branch protection blocks auto-merge.

Detection mechanism: .forgejo/workflows/_release.yml branches on [[ -n "${RELEASE_TOKEN_OVERRIDE:-}" ]] — the same predicate already used by the bash-level token-fallback (${RELEASE_TOKEN_OVERRIDE:-$GITHUB_TOKEN_DEFAULT}). Reusing it for the manifest-mechanism choice keeps the detection coherent across the workflow.

Empirical verification (per AGENTS.md §8 Axis A): claim that push_whitelist_usernames allows direct git push to protected main by listed users was verified via (a) operator quotation of Forgejo UI text ("only whitelisted users will be allowed to push to this branch" — UI render = read-back = authoritative source per the source-quotation calibration), and (b) empirical probe with a temporary release-bot PAT creating + deleting a probe file on main (commits 0bbd6b5 add + ed1a8cf delete, both authored by release-bot@noreply.git.frankenbit.de).

Consequences for sibling trackers:

Closes #112 — the (2)/(3) review-gate tradeoff dissolves under path (α); path (γ) consumers face the existing v0.5.1+ manifest-via-PR behavior (no NEW question).
#113 auto-assign manifest follow-up stays open with reduced scope (γ-only).
#114 configurable publish mode unaffected (Gate-3 is orthogonal).

Preserves: Gate-1 (rolling PR merge) and Gate-3 (publish click) per ADR-0003; push-trigger architecture per ADR-0004; the security-surface-asymmetry rationale from #78 (path (γ) consumers without bot setup still get a working substrate without elevated permissions).

release: ADR-0007 direct-push manifest under path (α); manifest-via-PR for (γ) (closes #112)

### Added **`AGENTS.md` §8 Axis A** grows from n=5 → n=7 across 4 → 5 structurally-distinct surfaces. Two new empirical instances from the 2026-06-26 path (α) auto-merge investigation: - **Instance 6: `merge_whitelist-semantic-mis-mapping`** — joins the config-semantics surface (sibling to instance 2 `apply_to_admins`). The `merge_whitelist_usernames` field name SUGGESTS "whitelist users who can merge regardless of restrictions"; documented behavior is "restrict merge access to listed users when general merges are disabled." Inferred-from-name semantic was OPPOSITE of actual semantic. Empirical test confirmed by locking the admin caller out of merging. - **Instance 7: `self-approval-globally-hardcoded`** — NEW 5th surface (configurable-vs-hardcoded policy). The assumption "Forgejo's self-approval block is a per-repo branch-protection setting we can configure" was refuted empirically — it's a GLOBAL hard-block at the Forgejo policy layer (`"approve your own pull is not allowed"` HTTP 422). Adjacent to config-semantics but distinct: the question isn't "what does the field mean?" but "is this configurable AT ALL?" Pattern strengthening at n=7 — added explicit guidance: **after writing to a Forgejo field, READ IT BACK to verify the entry actually stuck** + **don't assume a behavior is per-repo configurable just because related behaviors are**. Two new calibration notes: - **Lifecycle caveat** — each instance is an observed-once external-system claim verified at the date noted; future Forgejo upgrades could change behavior. Same re-verify-against-LIVE-substrate discipline that produced them applies to consuming them. - **Source-quotation as verification** — re-verifying behavior that the source UI/docs EXPLICITLY states is over-applying Axis A. The discipline is verify-at-source for INFERRED claims, not for direct quotes from the live source. Worked instance 2026-06-26: when operator quoted the Forgejo UI text confirming `release-bot`'s whitelist permission, asking for a further empirical probe would have been over-cautious — the UI configuration IS the live source. This PR was originally scoped as the [#112](https://git.frankenbit.de/frankenbit/release-toolkit/issues/112) review-gate tradeoff docs work. Operator's architectural question 2026-06-26 ("why a second PR at all? direct-push the manifest commit by `release-bot`") surfaced an ADR-0007 candidate that would dissolve the (2)/(3) tradeoff documented in the original PR scope. The §8 banks are useful regardless of ADR-0007's outcome (worked instances of the discipline that hold independently of the manifest-mechanism architecture), so this PR's scope was reduced to just the §8 banks. The integration.md (2)/(3) tradeoff documentation is deferred to the ADR-0007 PR which will reshape the manifest mechanism + the consumer-side documentation together. **ADR-0007 lands** ([docs/adr/0007-manifest-commit-direct-push.md](docs/adr/0007-manifest-commit-direct-push.md)): the manifest commit lifecycle splits along consumer setup. The PR mechanism introduced in [#78](https://git.frankenbit.de/frankenbit/release-toolkit/issues/78) was a workaround for the pre-path-α push-permission gap; with path (α) wired, the cleaner direct-push path becomes the default. - **Path (α) — `release-bot` configured**: the workflow **direct-pushes** the manifest commit to `main`. No PR is opened. No second-PR click required per cut. Compatible with `required_approvals > 0` on substantive PRs (the approval gate applies to PR merges, not whitelisted direct pushes). - **Path (γ) — no bot setup**: the workflow opens a `release-toolkit/manifest-<TAG>` PR and attempts auto-merge (existing v0.5.0+ behavior, **unchanged**). Operator manually merges if branch protection blocks auto-merge. **Detection mechanism**: `.forgejo/workflows/_release.yml` branches on `[[ -n "${RELEASE_TOKEN_OVERRIDE:-}" ]]` — the same predicate already used by the bash-level token-fallback (`${RELEASE_TOKEN_OVERRIDE:-$GITHUB_TOKEN_DEFAULT}`). Reusing it for the manifest-mechanism choice keeps the detection coherent across the workflow. **Empirical verification** (per AGENTS.md §8 Axis A): claim that `push_whitelist_usernames` allows direct `git push` to protected `main` by listed users was verified via (a) operator quotation of Forgejo UI text ("only whitelisted users will be allowed to push to this branch" — UI render = read-back = authoritative source per the source-quotation calibration), and (b) empirical probe with a temporary `release-bot` PAT creating + deleting a probe file on `main` (commits `0bbd6b5` add + `ed1a8cf` delete, both authored by `release-bot@noreply.git.frankenbit.de`). **Consequences for sibling trackers**: - Closes [#112](https://git.frankenbit.de/frankenbit/release-toolkit/issues/112) — the (2)/(3) review-gate tradeoff dissolves under path (α); path (γ) consumers face the existing v0.5.1+ manifest-via-PR behavior (no NEW question). - [#113](https://git.frankenbit.de/frankenbit/release-toolkit/issues/113) auto-assign manifest follow-up stays open with reduced scope (γ-only). - [#114](https://git.frankenbit.de/frankenbit/release-toolkit/issues/114) configurable publish mode unaffected (Gate-3 is orthogonal). **Preserves**: Gate-1 (rolling PR merge) and Gate-3 (publish click) per [ADR-0003](docs/adr/0003-multi-stage-operator-gate.md); push-trigger architecture per [ADR-0004](docs/adr/0004-push-trigger-manifest-rolling-pr.md); the security-surface-asymmetry rationale from [#78](https://git.frankenbit.de/frankenbit/release-toolkit/issues/78) (path (γ) consumers without bot setup still get a working substrate without elevated permissions). - **release**: ADR-0007 direct-push manifest under path (α); manifest-via-PR for (γ) (closes #112)

forgejo-actions force-pushed release-prep/rolling from 7f8f78a7cb

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s

Details

manifest-check / check (pull_request) Successful in 0s

Details

to 7e86f0a64e

2026-06-26 15:18:25 +02:00

Compare