docs(agents): section 2 leads with the #456 floating pin; the rc re-pin is dormant (#1510) #1511

Merged

alex merged 1 commit from claude/1510-agents-section2-floating-pin into main 2026-10-02 15:34:32 +02:00

Conversation 2 Commits 1 Files changed 1 +70 -21

claude commented 2026-10-02 15:25:42 +02:00

Member

• Copy link
• Copy Markdown

Refs #1510

no-changelog: contributor-internal process doc (AGENTS.md); no adopter-visible behaviour changes.

Head aa9521b7b8754049352950d494b2e8971cbbf18e on base e4c0f35 (live main when pushed). One commit, one file.

What

AGENTS.md section 2 now starts with the posture toolkit-self actually runs under. It used to open with "the toolkit MUST re-pin its own consumer-side release.yml" and never mentioned #456.

• New 2.1: toolkit-self floats @main (#456), and a routine change needs no re-pin. A table traces how a toolkit-self cut ends up running the commit under test: the wrapper pin, the resolve-ref override, the main) build arm, the drift gate's early exit, and the post-cut skip. Adopters are unaffected. The section also gives the PR-body note for a routine change, and anchors on #1496.
• New 2.2: the rc re-pin is dormant, not retired. It has not run since 9bca7d5 (v0.30.0-rc.2). Two cases bring it back:
  • A deliberate tag pin. That needs rt repin, with two cautions nobody has exercised yet: the FETCH arm has never run for an rc, and the drift gate guards no Go source.
  • An accidental tag pin. The fix is to put @main back in a reviewed PR. rt repin cannot do that.
• Build-bake: documents the three resolve-ref arms added after #172 (#456, #336, #1222), corrects 2 baked reusables to 9, and says the post-cut reset now runs inside rt post-cut. The heading name is unchanged, because docs/integration.md cites it by name.
• 2.3 (was the unnumbered "Structural backstop"): now numbered, so the citations of "AGENTS.md section 2.3" at cmd/rt/check_self_bootstrap.go:155 and internal/gates/selfboot_check.go:64 resolve. It lists the check's three steps in code order, and says a drift red cannot happen under @main.
• 2.4 and 2.5: a dormant note at the top of each. 2.4's bash test seam is replaced by the rcTagPruner fake. 2.5's "both reusables" and "release.yml + manifest-check.yml" now read "every baked reusable" and "every consumer wrapper".
• Glossary and section 15 row 4: both now point at 2.1/2.2.

The pre-#456 "Why", "The pattern" and "Empirical instances" stay as history under 2.2, with "Under a tag pin" added to "Why".

Decision tree (section 7)

• (A) Lead with the floating pin, and mark the rc procedure dormant. Right when the rc machinery is still live code that a deliberate tag pin would need. It is: rt repin, the post-cut prune and the gate's drift arm all ship and are tested. Chosen.
• (B) Retire 2.2, 2.4 and 2.5 outright. Right if toolkit-self could never be tag-pinned again. Nothing enforces that: the gate's drift arm and post-cut's re-pin of non-main wrappers exist so that a tag pin keeps working. Deleting the procedure would leave that path undocumented.
• (C) Add one note at the top of section 2. Right if only the intro were stale. It is not. Build-bake ("unconditional… no fallback", "2 reusables") and the backstop ("expected red… run rt repin") also describe mechanisms that have since moved.

Self-bootstrap (section 2)

No re-pin: this is a docs-only change, and toolkit-self floats @main (AGENTS.md 2.1, as amended here). No compose script or Go source moved.

Verified at source (section 8)

Everything below was read at e4c0f35, unless a different date is given.

• Wrapper pins. All 7 uses: frankenbit/release-toolkit/... lines under .forgejo/workflows/ end in @main; a grep for any other ref returns nothing. The 4 wrappers that use uses: ./... are ac-closure-check, prepared-uncut-check, workflow-parse-check and mirror-release.
• The override. SOURCE="floating-pin-override (release-toolkit#456)" appears in all 9 baked reusables, which match the 9 files in internal/bake/marker.go canonicalFiles. In reusable-release.yml it is line 331, and the resolve step runs from line 258 to line 354.
• The main) arm. scripts/bootstrap-rt.sh:45-66 switches the build source to $GITHUB_WORKSPACE at line 56.
• The gate. cmd/rt/check_self_bootstrap.go: the alignment check is at line 148, and the main early exit at lines 169-183. DefaultComposeScripts is in internal/gates/selfboot_check.go:234-245.
• The post-cut step. cmd/rt/post_cut.go:670-673 skips @main wrappers. Line 626 resets the bake markers to 'main'. reusable-release.yml:820 passes --pinned-ref from steps.resolve-ref.outputs.ref.
• No re-pin since #456. git log --grep='re-pin self-bootstrap' e9eca94..origin/main is empty. git ls-remote --tags origin, read 2026-10-02, has v0.30.0-rc.2 as its newest rc tag and v0.63.1 as its newest cut tag.
• rt repin accepts only rc tags. rcTagShape is at cmd/rt/repin.go:24.
• Asset publishing. It began at v0.34.0, per goreleaser.yml:464, which quotes the #648 job comment. Whether goreleaser would publish assets for an rc tag is not measured, and the doc says so.
• The #1496 anchor. PR comments 114064 and 114065 record the body correction made "per review 7179".
• Local checks, run in an LF clone with golang:1.25:
  • rt register-check AGENTS.md: 0 hits.
  • rt register-check --git-log e4c0f35..HEAD: 0 hits.
  • go test -count=1 ./...: 29 packages ok.
• Close keywords. This body, the title and the commit message were scanned with closeKeywordRE before sending, and contain no close targets.

Found in passing, not changed here

The same staleness exists in other files. Each would make this PR more than a docs change, or would touch a contract table under its own gate:

• The header of .forgejo/workflows/check-self-bootstrap.yml (lines 10-16) still says a red on a compose-script PR is expected.
• The drift failure message at cmd/rt/check_self_bootstrap.go:233-235 still says to tag an rc and re-pin. That advice is right for a deliberate tag pin, and wrong for an accidental one.
• docs/architecture/contracts/cli-surface.md:98 gives rt repin's caller as check-self-bootstrap.yml (at RC cut time). That workflow does not invoke it.
• docs/architecture/arc42/11-risks-technical-debt.md:14 (Bootstrap-lag) still says the check "goes (correctly) red post-merge to signal 're-pin needed'".
• cmd/rt/repin.go does not carry the #456 note that the retired repin.sh header had.

Verify at source, please (section 6)

@alex: this is a verify-at-source request, not an FYI. Please re-read the substrate rather than this summary. In particular:

1. Is "dormant, not retired" the posture you want written down? Or should 2.2, 2.4 and 2.5 go entirely (option B)?
2. Two claims in 2.2's cautions rest on reads I did not exercise:
   • the FETCH arm has never run for an rc tag;
   • DefaultComposeScripts lists no Go source (internal/gates/selfboot_check.go:234-245).
3. Are 2.1's table rows still true at the head you review?

Review fixes will come as new commits on this branch, after a HOLD comment (section 15, step 5).

🤖 Generated with Claude Code

Refs #1510 no-changelog: contributor-internal process doc (AGENTS.md); no adopter-visible behaviour changes. Head `aa9521b7b8754049352950d494b2e8971cbbf18e` on base `e4c0f35` (live `main` when pushed). One commit, one file. ## What AGENTS.md section 2 now starts with the posture toolkit-self actually runs under. It used to open with "the toolkit MUST re-pin its own consumer-side `release.yml`" and never mentioned #456. - **New 2.1: toolkit-self floats `@main` (#456), and a routine change needs no re-pin.** A table traces how a toolkit-self cut ends up running the commit under test: the wrapper pin, the resolve-ref override, the `main)` build arm, the drift gate's early exit, and the post-cut skip. Adopters are unaffected. The section also gives the PR-body note for a routine change, and anchors on #1496. - **New 2.2: the rc re-pin is dormant, not retired.** It has not run since `9bca7d5` (`v0.30.0-rc.2`). Two cases bring it back: - A deliberate tag pin. That needs `rt repin`, with two cautions nobody has exercised yet: the FETCH arm has never run for an rc, and the drift gate guards no Go source. - An accidental tag pin. The fix is to put `@main` back in a reviewed PR. `rt repin` cannot do that. - **Build-bake:** documents the three resolve-ref arms added after #172 (#456, #336, #1222), corrects 2 baked reusables to 9, and says the post-cut reset now runs inside `rt post-cut`. The heading name is unchanged, because `docs/integration.md` cites it by name. - **2.3** (was the unnumbered "Structural backstop"): now numbered, so the citations of "AGENTS.md section 2.3" at `cmd/rt/check_self_bootstrap.go:155` and `internal/gates/selfboot_check.go:64` resolve. It lists the check's three steps in code order, and says a drift red cannot happen under `@main`. - **2.4 and 2.5:** a dormant note at the top of each. 2.4's bash test seam is replaced by the `rcTagPruner` fake. 2.5's "both reusables" and "release.yml + manifest-check.yml" now read "every baked reusable" and "every consumer wrapper". - **Glossary and section 15 row 4:** both now point at 2.1/2.2. The pre-#456 "Why", "The pattern" and "Empirical instances" stay as history under 2.2, with "Under a tag pin" added to "Why". ## Decision tree (section 7) - **(A) Lead with the floating pin, and mark the rc procedure dormant.** Right when the rc machinery is still live code that a deliberate tag pin would need. It is: `rt repin`, the post-cut prune and the gate's drift arm all ship and are tested. **Chosen.** - **(B) Retire 2.2, 2.4 and 2.5 outright.** Right if toolkit-self could never be tag-pinned again. Nothing enforces that: the gate's drift arm and post-cut's re-pin of non-`main` wrappers exist so that a tag pin keeps working. Deleting the procedure would leave that path undocumented. - **(C) Add one note at the top of section 2.** Right if only the intro were stale. It is not. Build-bake ("unconditional… no fallback", "2 reusables") and the backstop ("expected red… run `rt repin`") also describe mechanisms that have since moved. ## Self-bootstrap (section 2) No re-pin: this is a docs-only change, and toolkit-self floats `@main` (AGENTS.md 2.1, as amended here). No compose script or Go source moved. ## Verified at source (section 8) Everything below was read at `e4c0f35`, unless a different date is given. - **Wrapper pins.** All 7 `uses: frankenbit/release-toolkit/...` lines under `.forgejo/workflows/` end in `@main`; a grep for any other ref returns nothing. The 4 wrappers that use `uses: ./...` are `ac-closure-check`, `prepared-uncut-check`, `workflow-parse-check` and `mirror-release`. - **The override.** `SOURCE="floating-pin-override (release-toolkit#456)"` appears in all 9 baked reusables, which match the 9 files in `internal/bake/marker.go` `canonicalFiles`. In `reusable-release.yml` it is line 331, and the resolve step runs from line 258 to line 354. - **The `main)` arm.** `scripts/bootstrap-rt.sh:45-66` switches the build source to `$GITHUB_WORKSPACE` at line 56. - **The gate.** `cmd/rt/check_self_bootstrap.go`: the alignment check is at line 148, and the `main` early exit at lines 169-183. `DefaultComposeScripts` is in `internal/gates/selfboot_check.go:234-245`. - **The post-cut step.** `cmd/rt/post_cut.go:670-673` skips `@main` wrappers. Line 626 resets the bake markers to `'main'`. `reusable-release.yml:820` passes `--pinned-ref` from `steps.resolve-ref.outputs.ref`. - **No re-pin since #456.** `git log --grep='re-pin self-bootstrap' e9eca94..origin/main` is empty. `git ls-remote --tags origin`, read 2026-10-02, has `v0.30.0-rc.2` as its newest rc tag and `v0.63.1` as its newest cut tag. - **`rt repin` accepts only rc tags.** `rcTagShape` is at `cmd/rt/repin.go:24`. - **Asset publishing.** It began at v0.34.0, per `goreleaser.yml:464`, which quotes the #648 job comment. Whether goreleaser would publish assets for an rc tag is **not measured**, and the doc says so. - **The #1496 anchor.** PR comments 114064 and 114065 record the body correction made "per review 7179". - **Local checks**, run in an LF clone with `golang:1.25`: - `rt register-check AGENTS.md`: 0 hits. - `rt register-check --git-log e4c0f35..HEAD`: 0 hits. - `go test -count=1 ./...`: 29 packages ok. - **Close keywords.** This body, the title and the commit message were scanned with `closeKeywordRE` before sending, and contain no close targets. ## Found in passing, not changed here The same staleness exists in other files. Each would make this PR more than a docs change, or would touch a contract table under its own gate: - The header of `.forgejo/workflows/check-self-bootstrap.yml` (lines 10-16) still says a red on a compose-script PR is expected. - The drift failure message at `cmd/rt/check_self_bootstrap.go:233-235` still says to tag an rc and re-pin. That advice is right for a deliberate tag pin, and wrong for an accidental one. - `docs/architecture/contracts/cli-surface.md:98` gives `rt repin`'s caller as `check-self-bootstrap.yml (at RC cut time)`. That workflow does not invoke it. - `docs/architecture/arc42/11-risks-technical-debt.md:14` (Bootstrap-lag) still says the check "goes (correctly) red post-merge to signal 're-pin needed'". - `cmd/rt/repin.go` does not carry the #456 note that the retired `repin.sh` header had. ## Verify at source, please (section 6) @alex: this is a verify-at-source request, not an FYI. Please re-read the substrate rather than this summary. In particular: 1. Is "dormant, not retired" the posture you want written down? Or should 2.2, 2.4 and 2.5 go entirely (option B)? 2. Two claims in 2.2's cautions rest on reads I did not exercise: - the FETCH arm has never run for an rc tag; - `DefaultComposeScripts` lists no Go source (`internal/gates/selfboot_check.go:234-245`). 3. Are 2.1's table rows still true at the head you review? Review fixes will come as new commits on this branch, after a `HOLD` comment (section 15, step 5). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude added 1 commit 2026-10-02 15:25:43 +02:00

docs(agents): section 2 leads with the #456 floating pin; the rc re-pin is dormant (#1510) ... aa9521b7b8

Section 2 told every author of a compose-machinery change that the
toolkit MUST re-pin release.yml to an rc tag with rt repin. Since #456
(e9eca94, 2026-07-07) toolkit-self pins every wrapper at @main, and no
re-pin has run since: the newest rc tag is still v0.30.0-rc.2 while
cuts have reached v0.63.1. #1496 followed the old text and first wrote
"Re-pin before the next cut" for a Go-only change.

New section 2.1 states the floating pin first. It lists each link that
makes a toolkit-self cut run the commit under test (wrapper pin,
resolve-ref override, bootstrap-rt.sh main arm, the drift gate's early
exit, the post-cut skip), says adopters are unaffected, and gives the
PR-body note for a routine change: no re-pin.

New section 2.2 marks the rc re-pin dormant, not retired. It names the
two cases that bring it back. A deliberate tag pin needs rt repin, with
two unexercised cautions: the FETCH arm has never run for an rc, and
the drift gate guards no Go source. An accidental tag pin goes back to
@main in a reviewed PR, which rt repin cannot do.

Mechanisms that moved since the text was written:
- Build-bake: the resolve step now has the @main override (#456), the
  SHA arm (#336) and the wrapper-ref fallback (#1222); 9 reusables are
  baked, not 2; the post-cut reset runs inside rt post-cut.
- The structural backstop is numbered 2.3, so the code's "AGENTS.md
  section 2.3" citations resolve. It lists the check's three steps in
  order and says a drift red cannot happen under @main.
- 2.4 and 2.5 carry a dormant note. 2.4's bash test seam is replaced
  by the rcTagPruner fake.
- Section 15's PR-body row points at the 2.1 note.

Refs #1510

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

claude requested review from alex 2026-10-02 15:25:49 +02:00

alex approved these changes 2026-10-02 15:34:29 +02:00

alex merged commit aa9521b7b8 into main 2026-10-02 15:34:32 +02:00

alex deleted branch claude/1510-agents-section2-floating-pin 2026-10-02 15:34:32 +02:00

forgejo-actions commented 2026-10-02 15:35:18 +02:00

• Copy link
• Copy Markdown

Landing identity record

• PR: #1511
• landed commit (server merge_commit_sha): aa9521b7b8754049352950d494b2e8971cbbf18e
• effective official approval(s):
  • @alex, review #7183, stamped commit: aa9521b7b8754049352950d494b2e8971cbbf18e
• replay comparison: no identity change (stamped SHA equals landed SHA)

This is a post-merge identity record. It does not retroactively review the landed object; it records whether the server landed the object that an official approval named.

<!-- release-toolkit:landing-review-record-v1 landed=aa9521b7b8754049352950d494b2e8971cbbf18e --> ## Landing identity record - PR: #1511 - landed commit (server merge_commit_sha): `aa9521b7b8754049352950d494b2e8971cbbf18e` - effective official approval(s): - @alex, review #7183, stamped commit: `aa9521b7b8754049352950d494b2e8971cbbf18e` - replay comparison: no identity change (stamped SHA equals landed SHA) This is a post-merge identity record. It does not retroactively review the landed object; it records whether the server landed the object that an official approval named.

claude referenced this pull request 2026-10-02 15:37:30 +02:00

docs(agents): section 2 still prescribes an rc re-pin for toolkit-self, but #456 floats every wrapper at @main #1510

claude referenced this pull request 2026-10-02 15:37:46 +02:00

docs(agents): section 2 still prescribes an rc re-pin for toolkit-self, but #456 floats every wrapper at @main #1510

claude referenced this pull request 2026-10-02 15:45:02 +02:00

docs(self-bootstrap): check-self-bootstrap, rt repin and arc42 still prescribe the rc re-pin that #456 made dormant #1512

claude referenced this pull request 2026-10-02 15:56:51 +02:00

docs(self-bootstrap): the check, rt repin and arc42 follow AGENTS.md section 2 on the @main pin (#1512) #1513

claude referenced this pull request 2026-10-06 11:37:54 +02:00

docs(arc42): nine sites credit the bake to check-self-bootstrap, which never grades the baked value #1561

Sign in to join this conversation.

Reviewers

No reviewers

alex

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind

bug

Something is broken

  

kind

chore

Maintenance, tooling, refactor

  

kind

docs

Documentation work

  

kind

epic

Tracker: its acceptance criteria are sub-issues; closed by hand when all are ticked

  

kind

feature

New feature or capability

  

loop/paused

rt-bugfix-loop kill switch: while this is on the loop log issue, no round claims or merges

  

mirror-drift

Automated: a release here has no asset-bearing counterpart on the mirror. One tracker per drift episode; the check never reopens a closed one (#1586)

  

priority

critical

Critical: must be addressed immediately

  

priority

high

Important, should be addressed soon

  

priority

low

Low priority, address when convenient

  

priority

medium

Normal priority

  

size

L

Large: significant feature, ~6-16h

  

size

M

Medium: moderate feature, ~2-6h

  

size

S

Small: simple change, ~1-2h

  

size

XL

Extra large: major feature or refactor, 16h+

  

status

blocked

Cannot start until a named dependency resolves

No labels

bump

major

bump

minor

bump

patch

kind

bug

kind

chore

kind

docs

kind

epic

kind

feature

loop/paused

mirror-drift

priority

critical

priority

high

priority

low

priority

medium

size

L

size

M

size

S

size

XL

status

blocked

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

3 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

frankenbit/release-toolkit!1511

No description provided.