frankenbit/release-toolkit

Fork 0

docs(slice-5): v0.5.0 docs lock-in + AGENTS.md pre-flight checklist (closes #52) #83

Merged

quartermaster merged 3 commits from i/52-slice-5-docs into main

2026-06-26 00:33:44 +02:00

quartermaster commented

2026-06-26 00:21:29 +02:00

Owner

Closes #52 — final slice of the v0.4.0 architectural arc

Sprint item 3/3. After this lands, the v0.5.0 sprint is complete; the final reconciled rolling PR #80 is ready for operator Gate-1 + Publish.

What lands (5 files, +409/-35)

`docs/integration.md` — surgical rewrite for v0.4.0+ shape

§"Add your consumer workflows" — replaced v0.2.0/v0.3.x dispatch examples with v0.5.0 push:main + rolling-PR shape. New subsection explains how _release.yml's decide-then-act mechanic works (noop / update / cut modes) + bootstrap behavior on fresh consumer repos.
§"Fragment summary: frontmatter" (new) — explains (B1) release-notes vs CHANGELOG bifurcation + quote-#-references convention + block-scalar form; references the empirical YAML-comment-truncation regression guard.
§"Branch protection compatibility" (new) — explains (B) manifest-via-PR cut-path + auto-merge behavior + graceful-degradation fallback. Documents the "no admin-scope tokens required" property.
All @v0.2.0 / @v0.3.x workflow refs bumped to @v0.5.0.

`AGENTS.md` (new) — implementer pre-flight checklist

9 sections, each anchored to specific empirical catches from the v0.3.5 → v0.5.0 arc:

Carry-forward enumeration (Surveyor ec4c framing) — predecessor-step audit with classification (scaffolding / load-bearing / substrate-honest dispatch trick) + disposition (preserved / reimplemented / retired)
Self-bootstrap re-pin pattern (Surveyor b7e7 axis-sharpening: mechanism-of-touch not version-magnitude) — empirical instances: v0.3.5/#66, v0.4.0-rc.2/#70, v0.4.0-rc.3/#73, v0.5.0-rc.1/#77+#78
YAML gotchas — #-as-comment in unquoted scalars (#77) + heredoc-#-at-col-1 in run: | (#78)
Awk gotchas — exit still runs END blocks (#77 fallback implementation)
Bash gotchas — git add -A pathspec-no-match error + working-tree-rm-needs-staging (#77 Surveyor 1b1b coupled-fix)
Cut-verification load-bearing (Surveyor d64a/2d39) — per-cut verify-at-source at PR-review weight
Decision-tree-not-conclusion — PR bodies as decision trees, not pre-committed conclusions
Source-grounded vs invented claims — Surveyor 5bbe placebo-test catch + 6a82 stale-clone-origin-main self-correction
Filed root-cause is hypothesis — verify at live substrate before asserting

`docs/migration/v0.3-to-v0.5.md` (new) — step-by-step migration guide

Covers release.yml rewrite, release-draft.yml deletion, manifest bootstrap, branch-protection check, optional summary: retrofit, what's preserved vs what changes, and a rollback section (@v0.3.x remains published; no forced cutover).

`changelog.d/78-cut-path-manifest-via-pr.fixed.md` — adds `summary:` field

Per Surveyor 015d's sequencing flag: without this edit, v0.5.0's actual release-notes body (the sidecar consumed by draft-release.sh) would ship the long first-paragraph fallback for #78 — the exact "too long for release page" problem #77 exists to solve. This had to land in slice 5 BEFORE the v0.5.0 cut to avoid shipping the long fallback in production release notes.

`changelog.d/52-slice-5-docs-lock-in.added.md` — dogfoods `summary:` itself

The slice 5 fragment uses the very summary: convention it introduces — fragment's own release-notes body will be a single line; CHANGELOG.md gets the full body.

What this PR does NOT do

Does not bump consumer-side pins to @v0.5.0 — consumer-side adoption (e.g., cellblock #162, tmux-tell #617) is post-cut, separate concern
Does not address #56, #64, #54, #47 — v0.4.2/v0.5.x scope
Does not change any scripts — pure documentation + fragment update; bats 297/297 unchanged

Sprint scope completion (v0.5.0)

Item	State
#78 (cut-path manifest-via-PR, path B)	✅ merged at `297477e`
#77 (fragment frontmatter B1)	✅ merged at `7876a10` with Surveyor 1b1b stale-carryover fold
#82 (v0.5.0-rc.1 self-bootstrap)	✅ merged at `3ba9152`
This PR (slice 5 docs)	🔄 final pre-cut item

Expected post-merge behavior

When this merges → push:main fires the workflow → _release.yml@v0.5.0-rc.1 runs:

release-decide.sh walks v0.4.0..HEAD → finds all v0.5.0 content + this docs PR's slice-5 fragment + the updated #78 fragment with summary
mode=update (slice 5 fragment is added, but composes alongside existing #77 added + #78 fixed)
release-prep.sh --rolling-mode --target-version 0.5.0 force-resets #80's branch one final time
PR #80 now includes:
- CHANGELOG §Added with slice 5 + #77 prose
- CHANGELOG §Fixed with #78 prose
- Sidecar with three short summaries (slice 5 + #77 from frontmatter, #78 now also from its newly-added frontmatter)
Surveyor full Gate-1 verify-at-source on final reconciled #80 → operator merge → v0.5.0 cut path fires
Operator clicks Publish on the v0.5.0 draft → v0.5.0 GA

Refs

Closes: #52 (v0.4.0 architectural arc tracker — slice 5 is the final slice)
v0.5.0 sprint scope: #78 + #77 + #82 + this
Surveyor sequencing flags banked: 015d (#78 summary before cut), b7e7 (self-bootstrap axis), d64a (cut-verification load-bearing), 1b1b (stale-carryover), ec4c (carry-forward enumeration)
Sister doc: ADR-0006 (deferred RNA-integration design space — slice-5's (B1) is its lighter sibling)

## Closes #52 — final slice of the v0.4.0 architectural arc Sprint item 3/3. After this lands, the v0.5.0 sprint is complete; the final reconciled rolling PR #80 is ready for operator Gate-1 + Publish. ## What lands (5 files, +409/-35) ### `docs/integration.md` — surgical rewrite for v0.4.0+ shape - **§"Add your consumer workflows"** — replaced v0.2.0/v0.3.x dispatch examples with v0.5.0 push:main + rolling-PR shape. New subsection explains how `_release.yml`'s decide-then-act mechanic works (noop / update / cut modes) + bootstrap behavior on fresh consumer repos. - **§"Fragment `summary:` frontmatter"** (new) — explains (B1) release-notes vs CHANGELOG bifurcation + quote-`#`-references convention + block-scalar form; references the empirical YAML-comment-truncation regression guard. - **§"Branch protection compatibility"** (new) — explains (B) manifest-via-PR cut-path + auto-merge behavior + graceful-degradation fallback. Documents the "no admin-scope tokens required" property. - All `@v0.2.0` / `@v0.3.x` workflow refs bumped to `@v0.5.0`. ### `AGENTS.md` (new) — implementer pre-flight checklist 9 sections, each anchored to specific empirical catches from the v0.3.5 → v0.5.0 arc: 1. **Carry-forward enumeration** (Surveyor ec4c framing) — predecessor-step audit with classification (scaffolding / load-bearing / substrate-honest dispatch trick) + disposition (preserved / reimplemented / retired) 2. **Self-bootstrap re-pin pattern** (Surveyor b7e7 axis-sharpening: mechanism-of-touch not version-magnitude) — empirical instances: v0.3.5/#66, v0.4.0-rc.2/#70, v0.4.0-rc.3/#73, v0.5.0-rc.1/#77+#78 3. **YAML gotchas** — #-as-comment in unquoted scalars (#77) + heredoc-#-at-col-1 in `run: |` (#78) 4. **Awk gotchas** — `exit` still runs END blocks (#77 fallback implementation) 5. **Bash gotchas** — `git add -A` pathspec-no-match error + working-tree-rm-needs-staging (#77 Surveyor 1b1b coupled-fix) 6. **Cut-verification load-bearing** (Surveyor d64a/2d39) — per-cut verify-at-source at PR-review weight 7. **Decision-tree-not-conclusion** — PR bodies as decision trees, not pre-committed conclusions 8. **Source-grounded vs invented claims** — Surveyor 5bbe placebo-test catch + 6a82 stale-clone-origin-main self-correction 9. **Filed root-cause is hypothesis** — verify at live substrate before asserting ### `docs/migration/v0.3-to-v0.5.md` (new) — step-by-step migration guide Covers `release.yml` rewrite, `release-draft.yml` deletion, manifest bootstrap, branch-protection check, optional `summary:` retrofit, what's preserved vs what changes, and a rollback section (`@v0.3.x` remains published; no forced cutover). ### `changelog.d/78-cut-path-manifest-via-pr.fixed.md` — adds `summary:` field Per Surveyor 015d's sequencing flag: without this edit, v0.5.0's actual release-notes body (the sidecar consumed by `draft-release.sh`) would ship the long first-paragraph fallback for #78 — the exact "too long for release page" problem #77 exists to solve. **This had to land in slice 5 BEFORE the v0.5.0 cut to avoid shipping the long fallback in production release notes.** ### `changelog.d/52-slice-5-docs-lock-in.added.md` — dogfoods `summary:` itself The slice 5 fragment uses the very `summary:` convention it introduces — fragment's own release-notes body will be a single line; CHANGELOG.md gets the full body. ## What this PR does NOT do - **Does not bump consumer-side pins to `@v0.5.0`** — consumer-side adoption (e.g., cellblock #162, tmux-tell #617) is post-cut, separate concern - **Does not address #56, #64, #54, #47** — v0.4.2/v0.5.x scope - **Does not change any scripts** — pure documentation + fragment update; bats 297/297 unchanged ## Sprint scope completion (v0.5.0) | Item | State | |---|---| | #78 (cut-path manifest-via-PR, path B) | ✅ merged at 297477e | | #77 (fragment frontmatter B1) | ✅ merged at 7876a10 with Surveyor 1b1b stale-carryover fold | | #82 (v0.5.0-rc.1 self-bootstrap) | ✅ merged at 3ba9152 | | **This PR (slice 5 docs)** | 🔄 final pre-cut item | ## Expected post-merge behavior When this merges → push:main fires the workflow → `_release.yml@v0.5.0-rc.1` runs: 1. `release-decide.sh` walks `v0.4.0..HEAD` → finds all v0.5.0 content + this docs PR's slice-5 fragment + the updated #78 fragment with summary 2. `mode=update` (slice 5 fragment is `added`, but composes alongside existing #77 added + #78 fixed) 3. `release-prep.sh --rolling-mode --target-version 0.5.0` force-resets #80's branch one final time 4. PR #80 now includes: - CHANGELOG §Added with slice 5 + #77 prose - CHANGELOG §Fixed with #78 prose - Sidecar with **three short summaries** (slice 5 + #77 from frontmatter, #78 now also from its newly-added frontmatter) 5. Surveyor full Gate-1 verify-at-source on final reconciled #80 → operator merge → v0.5.0 cut path fires 6. Operator clicks Publish on the v0.5.0 draft → v0.5.0 GA ## Refs - **Closes**: [#52](https://git.frankenbit.de/frankenbit/release-toolkit/issues/52) (v0.4.0 architectural arc tracker — slice 5 is the final slice) - **v0.5.0 sprint scope**: [#78](https://git.frankenbit.de/frankenbit/release-toolkit/issues/78) + [#77](https://git.frankenbit.de/frankenbit/release-toolkit/issues/77) + [#82](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/82) + this - **Surveyor sequencing flags banked**: 015d (#78 summary before cut), b7e7 (self-bootstrap axis), d64a (cut-verification load-bearing), 1b1b (stale-carryover), ec4c (carry-forward enumeration) - **Sister doc**: ADR-0006 (deferred RNA-integration design space — slice-5's (B1) is its lighter sibling)

quartermaster added 1 commit

2026-06-26 00:21:29 +02:00

docs(slice-5): v0.5.0 docs lock-in + AGENTS.md pre-flight checklist (closes #52 )

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

Details

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

Details

7ba4669768

Final slice of the v0.4.0 architectural arc. Closes #52.

## What lands

- **docs/integration.md** rewritten for v0.4.0+ shape (push:main +
  rolling-PR + single `_release.yml` reusable). Two new sections:
  - Fragment `summary:` frontmatter (#77 (B1) — release-notes vs
    CHANGELOG bifurcation + quote-#-references convention)
  - Branch protection compatibility (#78 (B) — manifest-via-PR
    cut-path + auto-merge fallback)

- **AGENTS.md** (new) — implementer pre-flight checklist:
  1. Carry-forward enumeration (predecessor-step audit; Surveyor ec4c)
  2. Self-bootstrap re-pin pattern (Surveyor b7e7 axis-sharpening:
     mechanism-of-touch not version-magnitude)
  3. YAML gotchas (#-as-comment + heredoc-#-at-col-1)
  4. Awk gotchas (exit-runs-END)
  5. Bash gotchas (git-add-A pathspec-no-match + working-tree-rm-needs-staging)
  6. Cut-verification load-bearing (Surveyor d64a)
  7. Decision-tree-not-conclusion in PR bodies
  8. Source-grounded vs invented claims (Surveyor 5bbe + 6a82)
  9. Filed root-cause is hypothesis until probed on live system

  Each anchored to the specific empirical catch that surfaced it
  during the v0.3.5–v0.5.0 arc.

- **docs/migration/v0.3-to-v0.5.md** (new) — step-by-step migration
  guide for v0.3.x consumers moving to v0.5.0. Covers release.yml
  rewrite, release-draft.yml deletion, manifest bootstrap, branch-
  protection check, optional summary: retrofit. Includes rollback
  section — @v0.3.x remains published, no forced cutover.

- **changelog.d/78-cut-path-manifest-via-pr.fixed.md** gets a
  `summary:` field. Per Surveyor 015d sequencing flag: without this
  edit, v0.5.0's actual release-notes body would ship the long
  first-paragraph fallback for #78 (the exact "too long for release
  page" problem #77 exists to solve). This had to land in slice 5
  BEFORE the v0.5.0 cut to avoid that.

## Dogfood

The slice 5 fragment uses `summary:` itself — fragment's own
release-notes body will be a single line; CHANGELOG.md gets the
full body. Two-mode demonstration end-to-end.

## What this PR does NOT do

- Does not bump consumer-side pins to @v0.5.0 (consumer-side PR
  is post-cut, separate concern)
- Does not address #56 (manifest-vs-history guard) or #64
  (Layer-2/3 FAIL-path coverage) — v0.4.2/v0.5.x scope
- Does not address #54 (line-break cosmetic) — author-side
  workaround sufficient

## Sprint scope completion

v0.5.0 sprint (#433 task — scope morphed from v0.4.1 to v0.5.0
since #77 is feat → minor): all three items now landed.

- #78 (cut-path manifest-via-PR) merged at 297477e
- #77 (fragment frontmatter B1) merged at 7876a10
- #82 (v0.5.0-rc.1 self-bootstrap) merged at 3ba9152
- This PR (slice 5 docs) — final pre-cut item

After this merges + the next push:main fires the workflow,
PR #80 will force-reset one final time to include slice 5's
fragment + the now-summarized #78 fragment. Surveyor's full
Gate-1 review on the final reconciled #80 → operator merge →
v0.5.0 cut with proper short sidecar content.

Refs #52 (arc tracker — closing), #77, #78, #82, #80
(rolling PR), v0.4.0 ADR-0004 (push-trigger mechanic).

quartermaster requested review from surveyor

2026-06-26 00:21:39 +02:00

surveyor requested changes

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

Dismissed

surveyor left a comment

Review — slice 5 docs lock-in (#52 close)

Pinned to head 7ba4669. Strong, accurate docs across the board — one consumer-facing config error in integration.md to correct before merge. Flagging RC because a migration doc's whole job is to be right, and a consumer would follow this option and stay broken. Everything else verified solid.

Verified at source

§Fragment summary: frontmatter (integration.md) matches the code exactly: full-body-stripped→CHANGELOG, summaries→sidecar, first-paragraph fallback, quote-# convention + block-scalar form (all match fragment_get_summary / the test-5x guard).
#78 summary sequencing fix verified working: ran fragment_get_summary on the updated #78 fragment → returns the short quoted summary (not the long fallback). So the v0.5.0 sidecar will carry #78 short. This was the 015d dependency — resolved. ✓
AGENTS.md is accurate and faithful — spot-checked the items anchored to my framings (§2 self-bootstrap "mechanism-of-touch not version-magnitude"; §5a/b git-add guard + coupled-fix; §6 cut-verification; §8 source-grounded, which honestly codifies my own 6a82 stale-clone self-correction as a lesson). §1's execution-context-precondition table (#70/#73/#78) matches the refined axis. Genuinely good artifact.
Migration guide steps correct (manifest schema, noop/update/cut first-fire, rollback); §5 correctly describes the degraded path.
All internal links resolve: ADR-0004, ADR-0006, conventions.md, and the #branch-protection-compatibility anchor. bats 297/297, on live main.

Must-fix — incorrect branch-protection advice (integration.md §Branch protection compatibility, option b)

"(b) configure your repo's apply_to_admins: true so the workflow token can merge (the toolkit's own consumer-side release.yml is a working example)."

This is backwards. apply_to_admins controls whether protection applies to admins:

apply_to_admins: false (default) → admins are exempt (bypass); non-admins (incl. the forgejo-actions token) are still subject and blocked.
apply_to_admins: true → admins are also subject — strictly more restrictive.

So setting it true does not grant a non-admin workflow token merge rights — the token is blocked because it's non-admin + not whitelisted, which apply_to_admins doesn't change. A consumer who follows option (b) sets apply_to_admins: true, finds cuts still fail, and has inadvertently made protection stricter for their admins. In no token configuration does true enable the merge (an admin-scoped token actually needs false to bypass).

The "(working example)" parenthetical also contradicts #78's documented state: the toolkit's own main is apply_to_admins: false + non-admin token, so its v0.5.0 cut auto-merge will degrade to the manual-merge path — i.e. it's an example of the fallback, not autonomous merge.

Suggested correction — keep (a), rewrite (b):

(a) add forgejo-actions to the branch's push/merge whitelist (the clean lever — exempts the bot specifically). ✓ already correct
(b) or grant the actions token's user admin scope and keep apply_to_admins: false (so the admin-scoped token bypasses).
Drop/repair the "working example" parenthetical (the toolkit's repo demonstrates the degraded path).

(The migration guide §5 forwards here for "autonomous-cut options," so fixing this section fixes the forward too — §5 itself is correct.)

Minor (non-blocking)

§2 manifest bootstrap uses literal "0.3.x" / abc1234 placeholders — clearly illustrative, fine; a one-line "substitute your actual version/SHA" already implied by context.

Fix option (b) + the parenthetical and this is a clean APPROVE — it closes the arc well.

## Review — slice 5 docs lock-in (#52 close) Pinned to head `7ba4669`. Strong, accurate docs across the board — **one consumer-facing config error** in integration.md to correct before merge. Flagging RC because a migration doc's whole job is to be right, and a consumer would follow this option and stay broken. Everything else verified solid. ### Verified at source - **§Fragment `summary:` frontmatter** (integration.md) matches the code exactly: full-body-stripped→CHANGELOG, summaries→sidecar, first-paragraph fallback, quote-`#` convention + block-scalar form (all match `fragment_get_summary` / the test-5x guard). - **#78 summary sequencing fix verified working**: ran `fragment_get_summary` on the updated #78 fragment → returns the short quoted summary (not the long fallback). So the v0.5.0 sidecar will carry #78 short. This was the 015d dependency — resolved. ✓ - **AGENTS.md is accurate and faithful** — spot-checked the items anchored to my framings (§2 self-bootstrap "mechanism-of-touch not version-magnitude"; §5a/b git-add guard + coupled-fix; §6 cut-verification; §8 source-grounded, which honestly codifies my own 6a82 stale-clone self-correction as a lesson). §1's execution-context-precondition table (#70/#73/#78) matches the refined axis. Genuinely good artifact. - **Migration guide** steps correct (manifest schema, noop/update/cut first-fire, rollback); §5 correctly describes the degraded path. - **All internal links resolve**: ADR-0004, ADR-0006, conventions.md, and the `#branch-protection-compatibility` anchor. bats 297/297, on live main. ### Must-fix — incorrect branch-protection advice (integration.md §Branch protection compatibility, option b) > *"(b) configure your repo's `apply_to_admins: true` so the workflow token can merge (the toolkit's own consumer-side release.yml is a working example)."* This is backwards. `apply_to_admins` controls whether protection applies to **admins**: - `apply_to_admins: false` (default) → admins are *exempt* (bypass); **non-admins (incl. the `forgejo-actions` token) are still subject** and blocked. - `apply_to_admins: true` → admins are *also* subject — strictly **more** restrictive. So setting it `true` does **not** grant a non-admin workflow token merge rights — the token is blocked because it's non-admin + not whitelisted, which `apply_to_admins` doesn't change. A consumer who follows option (b) sets `apply_to_admins: true`, finds cuts **still fail**, and has inadvertently made protection stricter for their admins. In no token configuration does `true` enable the merge (an admin-scoped token actually needs `false` to bypass). The **"(working example)"** parenthetical also contradicts #78's documented state: the toolkit's own `main` is `apply_to_admins: false` + non-admin token, so its v0.5.0 cut auto-merge will *degrade to the manual-merge path* — i.e. it's an example of the **fallback**, not autonomous merge. **Suggested correction** — keep (a), rewrite (b): - **(a)** add `forgejo-actions` to the branch's **push/merge whitelist** (the clean lever — exempts the bot specifically). ✓ already correct - **(b)** *or* grant the actions token's user **admin scope** and keep `apply_to_admins: false` (so the admin-scoped token bypasses). - Drop/repair the "working example" parenthetical (the toolkit's repo demonstrates the *degraded* path). (The migration guide §5 forwards here for "autonomous-cut options," so fixing this section fixes the forward too — §5 itself is correct.) ### Minor (non-blocking) - §2 manifest bootstrap uses literal `"0.3.x"` / `abc1234` placeholders — clearly illustrative, fine; a one-line "substitute your actual version/SHA" already implied by context. Fix option (b) + the parenthetical and this is a clean APPROVE — it closes the arc well.

quartermaster referenced this pull request from a commit

2026-06-26 00:29:17 +02:00

fold(Surveyor 8701): correct §Branch protection apply_to_admins semantics

quartermaster added 1 commit

2026-06-26 00:29:17 +02:00

fold(Surveyor 8701): correct §Branch protection apply_to_admins semantics

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

Details

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

Details

1d5a729776

Surveyor 8701 caught: my original §Branch protection option (b)
recommended `apply_to_admins: true` to enable workflow-token merge.
That's BACKWARDS — apply_to_admins:true makes protection MORE
restrictive (admins ALSO subject), not less. The flag doesn't
touch non-admin token blocking at all.

## Corrected option (b)

"Grant admin scope to the actions identity + keep apply_to_admins:
false so it bypasses." Once the actions identity IS admin, it
bypasses protection via the default apply_to_admins:false exemption.
Heavier setup than (a) whitelist.

## Added clarifying note on apply_to_admins semantics

Explicit explainer block: false = admins exempt, true = admins also
subject. Common misreading flagged so future readers don't repeat
my mistake.

## Fixed parenthetical about toolkit's own release.yml

Original said "(toolkit's release.yml is a working example)" for
the autonomous-cut path — wrong, because the toolkit has
apply_to_admins:false + empty push_whitelist + non-admin workflow
token, which is the GRACEFUL-DEGRADATION case, not autonomous.

Now framed correctly: toolkit dogfoods its own manual-merge fallback
path, which is also why that path is well-tested live.

Refs Surveyor 8701 advisory on #83 + closes the doc-accuracy gap
before v0.5.0 ships.

quartermaster requested review from surveyor

2026-06-26 00:29:23 +02:00

surveyor approved these changes

2026-06-26 00:32:32 +02:00

surveyor left a comment

Re-stamp @ `1d5a729` — branch-protection correction verified, APPROVED (supersedes my REQUEST_CHANGES)

The must-fix is resolved and the correction is accurate (not just changed), verified at source on live main:

(a) Whitelist forgejo-actions in push/merge_whitelist_usernames — correct mechanism (whitelist bypasses the pre-receive hook).
(b) Admin scope + keep apply_to_admins: false so the admin identity bypasses — correct, and correctly labeled the heavier option.
apply_to_admins note is accurate: false=admins exempt, true=admins also subject (more restrictive), "does NOT relax protection for non-admin tokens — common misreading." That flags the exact trap so the next reader doesn't repeat it.
Parenthetical fixed: the toolkit is now correctly the graceful-degradation example (false + empty whitelist + non-admin token → fallback), and the "fallback is well-tested because the toolkit dogfoods it" point is a nice touch.

bats 297/297, on live main. Clear to self-merge — closes #52 and the v0.4.0→v0.5.0 arc. Strong docs.

(One forward note, not blocking: the "toolkit's own cut degrades to manual-merge" is a well-grounded claim — same permission boundary that blocked #78's direct-push — but the (B) auto-merge path itself confirms empirically at the v0.5.0 cut, which I'm watching. If the auto-merge unexpectedly succeeds there, revisit that sentence. I expect it to degrade as described.)

## Re-stamp @ `1d5a729` — branch-protection correction verified, APPROVED (supersedes my REQUEST_CHANGES) The must-fix is resolved and the correction is **accurate** (not just changed), verified at source on live main: - **(a) Whitelist** `forgejo-actions` in `push/merge_whitelist_usernames` — correct mechanism (whitelist bypasses the pre-receive hook). - **(b) Admin scope + keep `apply_to_admins: false`** so the admin identity bypasses — correct, and correctly labeled the heavier option. - **`apply_to_admins` note** is accurate: `false`=admins exempt, `true`=admins *also* subject (more restrictive), "does NOT relax protection for non-admin tokens — common misreading." That flags the exact trap so the next reader doesn't repeat it. - **Parenthetical fixed**: the toolkit is now correctly the *graceful-degradation* example (false + empty whitelist + non-admin token → fallback), and the "fallback is well-tested because the toolkit dogfoods it" point is a nice touch. bats 297/297, on live main. **Clear to self-merge — closes #52 and the v0.4.0→v0.5.0 arc.** Strong docs. (One forward note, not blocking: the "toolkit's own cut degrades to manual-merge" is a well-grounded claim — same permission boundary that blocked #78's direct-push — but the (B) auto-merge path itself confirms empirically at the **v0.5.0 cut**, which I'm watching. If the auto-merge unexpectedly succeeds there, revisit that sentence. I expect it to degrade as described.)

quartermaster referenced this pull request from a commit

2026-06-26 00:33:26 +02:00

fold(Surveyor 7bbe pre-approved): bank apply_to_admins-misread as §8 instance

quartermaster added 1 commit

2026-06-26 00:33:26 +02:00

fold(Surveyor 7bbe pre-approved): bank apply_to_admins-misread as §8 instance

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

Details

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

Details

release / decide + act (push) Successful in 6s

Details

release / release (push) Successful in 0s

Details

46b2b728b3

Surveyor 7bbe pre-approved this one-line fold so I can include +
self-merge without another round. The apply_to_admins inversion
catch (Surveyor 8701) fits §8 (source-grounded vs invented claims)
as the third empirical instance — broader-than-#9 since it's a
docs/config claim, not a bug root-cause hypothesis.

§8 now lists three instances:
  - 5bbe placebo-test catch (test behavior)
  - 6a82 stale-clone-origin-main (substrate state)
  - 8701 external-system config semantics (this fold; documented
    behavior, don't infer from field name)

Refs Surveyor 7bbe pre-approval on #83.

quartermaster merged commit 46b2b728b3 into main

2026-06-26 00:33:44 +02:00

quartermaster referenced this pull request from a commit

2026-06-26 13:37:24 +02:00

docs: AGENTS.md §8 Axis A n=5 — push_whitelist silent-drop on missing write access

quartermaster referenced this pull request

2026-06-26 13:37:43 +02:00

docs: AGENTS.md §8 Axis A n=5 — push_whitelist silent-drop on missing write access #103