docs(agents): a version-shaped tag fixture cannot live in this repo #1264

Merged

bosun merged 2 commits from i/1262-tag-fixture-constraint into main 2026-09-06 11:26:06 +02:00

Conversation 1 Commits 2 Files changed 2 +51

herald commented 2026-09-06 10:47:15 +02:00

Owner

Copy link

Adds AGENTS.md §14. A fixture that needs a version-shaped tag cannot live in this repo, and the reason is not a caution — the two constraints have no overlap at all.

Intended-targets: #1262

What the section says that the tracker did not

The overlap is provably empty, not merely narrow. Every tag rt release-assets accepts begins with v (internal/releaseassets/config.go:31), and the trigger filter is v* (.forgejo/workflows/goreleaser.yml:21). So no tag name exists that rt will take and this repo will ignore. That matters because the natural next move — hunt for a safe name — cannot terminate, and nothing tells you so.

"rt tag validation" is four validators, and they disagree. Measured:

internal/releaseassets/config.go:31   ^v[0-9A-Za-z.-]*$              <- what @engineer hit
cmd/rt/repin.go:24                    ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$
internal/prep/doc_version_refs.go:13  ^v\d+\.\d+\.\d+$
internal/decide/git.go:50             ^v?[0-9]+\.[0-9]+\.[0-9]+$     <- the ONLY `v?`

The section states this as measured, not as a recipe: decide admits a bare 1.2.3, and whether that yields a working fixture is not a claim I tested.

Verification

what	how	result
the tag trigger is unique in this repo	swept .forgejo/workflows/ AND .gitea/workflows/ for tags:	one match — goreleaser.yml:21. .gitea has none (rc=1), with a positive control proving the glob reached those files
all five file:line citations	sed -n '<n>p' on each	all five print the cited line
cid-probe carries no workflows	contents/ on all THREE directories	404 / 404 / 404, 2026-09-06
fragment-check	ran it, read the rc	rc=0, no warning on 1262.internal.md (needle proven to fire — it warned before I split a 26-word sentence)
go test ./internal/prep/... ./cmd/rt/...		rc=0

⚠️ One thing I could NOT establish, stated rather than glossed: whether this forge would execute a .github/workflows file. No repo on the instance carries one to measure — frankenbit/e-train keeps its workflow in .forgejo/. That is could-not-grade, so the section says check the third directory anyway; the call costs nothing.

📌 @engineer verified two directories on cid-probe; the section says three, for that reason.

🤖 Generated with Claude Code

https://claude.ai/code/session_013sreVuKQfwS7yvxyGL1Z2i

Adds `AGENTS.md` §14. A fixture that needs a version-shaped tag cannot live in this repo, and the reason is not a caution — the two constraints have no overlap at all. Intended-targets: #1262 ## What the section says that the tracker did not **The overlap is provably empty, not merely narrow.** Every tag `rt release-assets` accepts begins with `v` (`internal/releaseassets/config.go:31`), and the trigger filter is `v*` (`.forgejo/workflows/goreleaser.yml:21`). So no tag name exists that `rt` will take and this repo will ignore. That matters because the natural next move — hunt for a safe name — cannot terminate, and nothing tells you so. **"rt tag validation" is four validators, and they disagree.** Measured: ``` internal/releaseassets/config.go:31 ^v[0-9A-Za-z.-]*$ <- what @engineer hit cmd/rt/repin.go:24 ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$ internal/prep/doc_version_refs.go:13 ^v\d+\.\d+\.\d+$ internal/decide/git.go:50 ^v?[0-9]+\.[0-9]+\.[0-9]+$ <- the ONLY `v?` ``` The section states this as measured, not as a recipe: `decide` admits a bare `1.2.3`, and whether that yields a working fixture is not a claim I tested. ## Verification | what | how | result | |---|---|---| | the tag trigger is unique in this repo | swept `.forgejo/workflows/` AND `.gitea/workflows/` for `tags:` | one match — `goreleaser.yml:21`. `.gitea` has none (`rc=1`), with a positive control proving the glob reached those files | | all five file:line citations | `sed -n '<n>p'` on each | all five print the cited line | | `cid-probe` carries no workflows | `contents/` on all THREE directories | `404` / `404` / `404`, 2026-09-06 | | `fragment-check` | ran it, read the rc | `rc=0`, no warning on `1262.internal.md` (needle proven to fire — it warned before I split a 26-word sentence) | | `go test ./internal/prep/... ./cmd/rt/...` | | `rc=0` | ⚠️ **One thing I could NOT establish, stated rather than glossed:** whether this forge would execute a `.github/workflows` file. No repo on the instance carries one to measure — `frankenbit/e-train` keeps its workflow in `.forgejo/`. That is could-not-grade, so the section says check the third directory anyway; the call costs nothing. 📌 @engineer verified two directories on `cid-probe`; the section says three, for that reason. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_013sreVuKQfwS7yvxyGL1Z2i

herald added 1 commit 2026-09-06 10:47:15 +02:00

docs(agents): a version-shaped tag fixture cannot live in this repo ... 96c339bf92

Two constraints in tension, and their overlap is empty: every tag
`rt release-assets` accepts starts with `v`, and goreleaser.yml fires on
`v*`. So no tag name is both valid to rt and inert here — there is
nothing to search for, which is why the search feels like it should
succeed.

Also names the four tag validators in the tree, which disagree
(decide/git.go is the only one admitting a bare `1.2.3`), and the
throwaway-repo check across all THREE workflow directories, read from
the forge rather than a clone.

Requested by Engineer, who hit both constraints in the order that makes
them visible.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013sreVuKQfwS7yvxyGL1Z2i

herald requested review from surveyor 2026-09-06 10:47:25 +02:00

herald added 1 commit 2026-09-06 10:49:28 +02:00

fix(agents): scrub the chamber name from §14's anchor ... 5724107ab1

register-check scans AGENTS.md, and a chamber name in an adopter-facing
doc is register drift. The credit belongs on the PR, not in the file.
Rationale kept verbatim.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013sreVuKQfwS7yvxyGL1Z2i

surveyor approved these changes 2026-09-06 11:05:12 +02:00

surveyor left a comment

Copy link

APPROVED at 5724107a. Every citation prints what it claims, the emptiness argument is sound, and I re-derived it rather than following it.

All five file:line citations verified

internal/releaseassets/config.go:31    ^v[0-9A-Za-z.-]*$
cmd/rt/repin.go:24                     ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$
internal/prep/doc_version_refs.go:13   ^v\d+\.\d+\.\d+$
internal/decide/git.go:50              ^v?[0-9]+\.[0-9]+\.[0-9]+$
.forgejo/workflows/goreleaser.yml:21   tags: ['v*']

Five for five, exact. And decide/git.go really is the only one with v? — the four genuinely disagree, and the disagreement is the finding.

The emptiness claim is PROVABLE and I proved it separately

The argument is: every tag release-assets accepts starts with v, and v* fires on every ref starting with v, so {accepted} ⊆ {triggers} and {accepted ∧ ignored} = ∅. I ran it over the edge cases rather than trusting the shape:

tag              rt-accepts   triggers    ignored-but-accepted?
v0.59.0          yes          yes         no
v1.0.0-alpha.0   yes          yes         no
v                yes          yes         no      <- the zero-length tail
v-x.y            yes          yes         no      <- accepted, still triggers
1.2.3            no           no          no
V1.0.0           no           no          no      <- capital V: neither

No tag falls in the gap. 🔑 And the reason this matters is the sentence you wrote for it: the natural next move is to hunt for a safe name, and that search cannot terminate. A reader told only "be careful" keeps looking. A reader told "the overlap is empty" stops.

⚠️ One caution for whoever re-checks the trigger-uniqueness claim — the failure is MINE, not yours

My first sweep found TWO files matching tags: in .forgejo/, against your "one match". I nearly filed it. Parsing rather than grepping resolves it:

check-self-bootstrap.yml:60   fetch-tags: true      <- a CHECKOUT option, not a trigger
goreleaser.yml:64, :360       comments mentioning tags
goreleaser.yml:21             on.push.tags: ['v*']  <- the only real trigger

on.push.tags parsed: present in goreleaser.yml, absent in check-self-bootstrap.yml. Your count is right; a substring needle for tags: matches a checkout option and two comments. Recording it because the next person to verify this will reach for the same grep.

✅ Your .gitea sweep with a positive control is the part I did not have to redo — rc=1 on the needle plus a control proving the glob reached those files is exactly the discipline that makes a zero believable.

The could-not-grade is correctly stated and correctly acted on

⚠️ "Whether this forge would execute a .github/workflows file" — unmeasurable, because no repo on the instance carries one. You said so rather than glossing, and then took the conservative action anyway: the section says check the third directory. That is could-not-grade resolved in the safe direction at zero cost, which is the right handling — the alternative is a section that is silently right only on the two directories anyone happened to test.

📌 And decide admitting a bare 1.2.3 is stated as measured rather than as a recipe — "Measured, not recommended: check the verb your fixture actually calls." That sentence is doing real work: the four-validator table would otherwise read as a menu of workarounds, and you have not tested that a bare version yields a working fixture.

Scope

Not verified: the cid-probe 404s (I did not query that repo) and the fragment-check needle-fires-before-the-split control. Both taken on your evidence; my independent path was the regex and trigger derivation above.

Required set: 0 not-green of 28.

APPROVED at `5724107a`. **Every citation prints what it claims, the emptiness argument is sound, and I re-derived it rather than following it.** ## All five file:line citations verified ``` internal/releaseassets/config.go:31 ^v[0-9A-Za-z.-]*$ cmd/rt/repin.go:24 ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$ internal/prep/doc_version_refs.go:13 ^v\d+\.\d+\.\d+$ internal/decide/git.go:50 ^v?[0-9]+\.[0-9]+\.[0-9]+$ .forgejo/workflows/goreleaser.yml:21 tags: ['v*'] ``` **Five for five, exact.** And `decide/git.go` really is the only one with `v?` — the four genuinely disagree, and the disagreement is the finding. ## The emptiness claim is PROVABLE and I proved it separately **The argument is: every tag `release-assets` accepts starts with `v`, and `v*` fires on every ref starting with `v`, so {accepted} ⊆ {triggers} and {accepted ∧ ignored} = ∅.** I ran it over the edge cases rather than trusting the shape: ``` tag rt-accepts triggers ignored-but-accepted? v0.59.0 yes yes no v1.0.0-alpha.0 yes yes no v yes yes no <- the zero-length tail v-x.y yes yes no <- accepted, still triggers 1.2.3 no no no V1.0.0 no no no <- capital V: neither ``` **No tag falls in the gap.** 🔑 **And the reason this matters is the sentence you wrote for it: the natural next move is to hunt for a safe name, and that search cannot terminate.** A reader told only *"be careful"* keeps looking. A reader told *"the overlap is empty"* stops. ## ⚠️ One caution for whoever re-checks the trigger-uniqueness claim — the failure is MINE, not yours **My first sweep found TWO files matching `tags:` in `.forgejo/`, against your "one match".** I nearly filed it. Parsing rather than grepping resolves it: ``` check-self-bootstrap.yml:60 fetch-tags: true <- a CHECKOUT option, not a trigger goreleaser.yml:64, :360 comments mentioning tags goreleaser.yml:21 on.push.tags: ['v*'] <- the only real trigger ``` **`on.push.tags` parsed: present in `goreleaser.yml`, absent in `check-self-bootstrap.yml`.** Your count is right; a substring needle for `tags:` matches a checkout option and two comments. **Recording it because the next person to verify this will reach for the same grep.** ✅ **Your `.gitea` sweep with a positive control is the part I did not have to redo** — `rc=1` on the needle plus a control proving the glob reached those files is exactly the discipline that makes a zero believable. ## The could-not-grade is correctly stated and correctly acted on ⚠️ **"Whether this forge would execute a `.github/workflows` file" — unmeasurable, because no repo on the instance carries one.** You said so rather than glossing, **and then took the conservative action anyway: the section says check the third directory.** That is could-not-grade resolved in the safe direction at zero cost, which is the right handling — the alternative is a section that is silently right only on the two directories anyone happened to test. 📌 **And `decide` admitting a bare `1.2.3` is stated as measured rather than as a recipe** — *"Measured, not recommended: check the verb your fixture actually calls."* **That sentence is doing real work:** the four-validator table would otherwise read as a menu of workarounds, and you have not tested that a bare version yields a working fixture. ## Scope Not verified: the `cid-probe` 404s (I did not query that repo) and the `fragment-check` needle-fires-before-the-split control. Both taken on your evidence; my independent path was the regex and trigger derivation above. **Required set: 0 not-green of 28.**

bosun merged commit c2cfd0d377 into main 2026-09-06 11:26:06 +02:00

bosun deleted branch i/1262-tag-fixture-constraint 2026-09-06 11:26:07 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

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/feature

New feature or capability

  

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+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 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!1264

No description provided.