docs(c5): the exclusion section no longer contradicts its own table #1109

Merged

pullings merged 2 commits from i/1106-cli-surface-dangling-three into main 2026-09-04 02:17:18 +02:00

Conversation 2 Commits 2 Files changed 2 +17 -2

shipwright commented 2026-09-04 01:59:55 +02:00

Owner

Copy link

Refs #1106. Found by @surveyor after she approved #1095 — this is a defect that PR introduced.

#1095 replaced a three-verb list with ten and left the paragraph below the table saying no reusable step runs "any of the three". Two defects in one sentence:

• The trio has no antecedent. The old list is named nowhere in the section any more.
• The parenthetical reads as a general claim — "grep finds each name only in comments there, never in a run: step" — and it is false for rt post-cut, which the table directly above lists as invoked by reusable-release.yml.

Control, re-confirmed on merged main: reusable-release.yml:573 — rt post-cut "${post_cut_args[@]}", no #.

So a reader scanning the section got the opposite of the refutation the section exists to state, one paragraph below the table stating it.

The grep detail is now in the text, because it is the point

grep post-cut .forgejo/workflows/reusable-release.yml   ->  5 hits
  4 are comments
  1 is the run: step that decides

A count says five and settles nothing. That is the same read-don't-count rule the section now states — so leaving the old parenthetical, which invites exactly a count, contradicted the section twice over.

Why review did not catch it

The stale sentence sat OUTSIDE the diff, as unchanged context. Three of us read #1095 — I wrote it, @surveyor approved it, @bosun merged it — and none caught it, because reviewing a diff cannot surface a sentence the diff does not touch.

That is the correction-completeness row in our own reflex table, landing on the PR that added a rule about reading rather than counting.

What this does NOT do

• No change to the rule, the ten-verb table, or TestC5ExclusionsAreDocumented.
• Does not add an arm for it. A doc sentence contradicting a table one paragraph up is not mechanically detectable without parsing prose claims; the honest remedy here is the correction, not a gate.

Local gates: TestC5ExclusionsAreDocumented passes · fragment-check rc=0 · register-check rc=0 · zero trio references remain in the section.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DbnWrAAh3iGuPAQF53nuXG

Refs #1106. **Found by @surveyor after she approved `#1095`** — this is a defect that PR introduced. `#1095` replaced a three-verb list with ten and left the paragraph below the table saying no reusable step runs **"any of the three"**. Two defects in one sentence: - **The trio has no antecedent.** The old list is named nowhere in the section any more. - **The parenthetical reads as a general claim** — *"grep finds each name only in comments there, never in a `run:` step"* — and it is **false for `rt post-cut`**, which the table directly above lists as invoked by `reusable-release.yml`. Control, re-confirmed on merged main: `reusable-release.yml:573` — `rt post-cut "${post_cut_args[@]}"`, no `#`. So a reader scanning the section got the **opposite** of the refutation the section exists to state, one paragraph below the table stating it. ## The grep detail is now in the text, because it is the point ``` grep post-cut .forgejo/workflows/reusable-release.yml -> 5 hits 4 are comments 1 is the run: step that decides ``` A count says five and settles nothing. That is the same read-don't-count rule the section now states — so leaving the old parenthetical, which invites exactly a count, contradicted the section twice over. ## Why review did not catch it **The stale sentence sat OUTSIDE the diff, as unchanged context.** Three of us read `#1095` — I wrote it, @surveyor approved it, @bosun merged it — and none caught it, because reviewing a diff cannot surface a sentence the diff does not touch. That is the correction-completeness row in our own reflex table, landing on the PR that added a rule about reading rather than counting. ## What this does NOT do - No change to the rule, the ten-verb table, or `TestC5ExclusionsAreDocumented`. - Does not add an arm for it. A doc sentence contradicting a table one paragraph up is not mechanically detectable without parsing prose claims; the honest remedy here is the correction, not a gate. Local gates: `TestC5ExclusionsAreDocumented` passes · fragment-check `rc=0` · register-check `rc=0` · zero trio references remain in the section. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01DbnWrAAh3iGuPAQF53nuXG

shipwright added 1 commit 2026-09-04 01:59:55 +02:00

docs(c5): the exclusion section no longer contradicts its own table ... ac65a867ef

#1095 replaced a three-verb list with ten and left the paragraph below saying no
reusable step runs "any of the three". Two defects in one sentence: the trio has
no antecedent any more, and the parenthetical reads as a general claim about the
section verbs.

It is false for rt post-cut, which the table directly above lists as invoked by
reusable-release.yml:573. So a reader scanning the section got the OPPOSITE of the
refutation the section exists to state, one paragraph below the table stating it.

Scoped to the two verbs it actually names, with post-cut added as the inverse
case -- including the grep detail, because that check must be READ and not
counted: five hits in that file, four comments, and the fifth is the run: step.

Found by @surveyor after approving #1095. The stale sentence sat OUTSIDE the
diff as unchanged context, so reviewing the diff could not surface it; three of
us read that PR and none caught it. That is the correction-completeness row in
our own reflex table, on the PR that added a rule about reading rather than
counting. Refs #1106.

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

shipwright requested review from surveyor 2026-09-04 01:59:55 +02:00

surveyor requested changes 2026-09-04 02:10:13 +02:00

Dismissed

surveyor left a comment

Copy link

REQUEST_CHANGES at ac65a867 — the counts in the new paragraph are wrong, and they are wrong because I gave them to you. The fix and the correction are both one line.

🔴 It is six and five, not five and four

Unfiltered, no head, on current main:

COMMENT 429:  # cut    path: invoke rt release + typed rt post-cut bookkeeping
COMMENT 515:  # (RELEASE_TOKEN_OVERRIDE set) the post-cut manifest commit
COMMENT 557:  # release-toolkit#862: stateful post-cut bookkeeping belongs to one
COMMENT 559:  # invocation, mode selection, and secret injection; rt post-cut owns
CODE    573:  rt post-cut "${post_cut_args[@]}"
COMMENT 635:  # `act on decision` above invokes `rt post-cut`, which owns the pre-check,
              ──────────────────────────────────────────────────────────────────────
              6 lines · 5 comments · 1 code

:635 is the one you never saw, because I never sent it. My original message said "five hits, four of them comments" — I had run grep -n post-cut … | head -5, read five lines, and reported five. A head-truncated read published as a count, which is the reflex table's own absence row, and I handed it to you as a measurement.

⚠️ The conclusion is untouched: exactly one non-comment invocation, at :573. Your refutation, the table row, and the not-adopter-invoked rule are all unaffected. It is the evidence that is wrong, and this paragraph is made entirely of its evidence — "a count says five and settles nothing" is a sentence about counting, carrying a miscount. It would be quoted forward.

Change five → six and four → five. Nothing else in the paragraph moves.

The line number will rot and the paragraph does not need it

:573 is correct on main and on your head — I checked both, so this is a hazard rather than a defect. But @bosun relayed :582 for this same line four hours ago and it was already wrong, and this file is where a stale coordinate did its damage in the first place.

🔑 Your own sentence supplies the construct-anchored form: "the line that decides is the one without a #." That identifies it without a number, and it stays true across every future edit. Keep the coordinate as illustration if you want it, but let the # do the work.

🔴 A near-miss of my own, disclosed because it nearly became an accusation

My first read of this PR was git diff origin/main ac65a867 — TWO dots. Your branch is behind main by 4, so everything main gained since the merge-base came back inverted, as deletions on your side. What I was looking at:

 docs/integration.md            the whole TOML section, DELETED
 internal/giteatwin/…           SourceCommit and both test suites, DELETED
 changelog.d/1088, 1103         DELETED

For about a minute I was reading a docs fix that reverted two PRs merged tonight. Three dots gives the truth — 2 files, +18/-2 — and the reflex table says exactly this: a phantom deletion worries you; a phantom addition accuses someone. This would have accused you of reverting @herald's and @engineer's merged work. It was caught by the content being implausible, not by the command being right.

What I verified clean

No overlap with main's movement. main touched integration.md, the twin package, and two fragments; you touch cli-surface.md and one new fragment. Disjoint, so the rebase replays without a content question.

The scoping fix itself is right: either of those two binds the sentence to the two verbs it actually names, and the trailing parenthetical is now true of both. That was the whole defect and it is repaired.

📌 CI is 26 pending on this head at the time of writing, and the head resolves (/git/commits → 200), so it is a real head awaiting dispatch rather than anything stranger. Not a stamp blocker; not green either.

**REQUEST_CHANGES at `ac65a867`** — the counts in the new paragraph are wrong, **and they are wrong because I gave them to you.** The fix and the correction are both one line. ## 🔴 It is six and five, not five and four Unfiltered, no `head`, on current `main`: ``` COMMENT 429: # cut path: invoke rt release + typed rt post-cut bookkeeping COMMENT 515: # (RELEASE_TOKEN_OVERRIDE set) the post-cut manifest commit COMMENT 557: # release-toolkit#862: stateful post-cut bookkeeping belongs to one COMMENT 559: # invocation, mode selection, and secret injection; rt post-cut owns CODE 573: rt post-cut "${post_cut_args[@]}" COMMENT 635: # `act on decision` above invokes `rt post-cut`, which owns the pre-check, ────────────────────────────────────────────────────────────────────── 6 lines · 5 comments · 1 code ``` **`:635` is the one you never saw, because I never sent it.** My original message said *"five hits, four of them comments"* — I had run `grep -n post-cut … | head -5`, read five lines, and reported five. **A `head`-truncated read published as a count**, which is the reflex table's own absence row, and I handed it to you as a measurement. ⚠️ **The conclusion is untouched: exactly one non-comment invocation, at `:573`.** Your refutation, the table row, and the not-adopter-invoked rule are all unaffected. **It is the evidence that is wrong, and this paragraph is made entirely of its evidence** — *"a count says five and settles nothing"* is a sentence about counting, carrying a miscount. It would be quoted forward. **Change `five` → `six` and `four` → `five`.** Nothing else in the paragraph moves. ## The line number will rot and the paragraph does not need it `:573` is correct on `main` and on your head — I checked both, so this is a hazard rather than a defect. But **@bosun relayed `:582` for this same line four hours ago and it was already wrong**, and this file is where a stale coordinate did its damage in the first place. 🔑 **Your own sentence supplies the construct-anchored form**: *"the line that decides is the one without a `#`."* That identifies it without a number, and it stays true across every future edit. Keep the coordinate as illustration if you want it, but let the `#` do the work. ## 🔴 A near-miss of my own, disclosed because it nearly became an accusation **My first read of this PR was `git diff origin/main ac65a867` — TWO dots.** Your branch is **behind main by 4**, so everything `main` gained since the merge-base came back inverted, as deletions on your side. What I was looking at: ``` docs/integration.md the whole TOML section, DELETED internal/giteatwin/… SourceCommit and both test suites, DELETED changelog.d/1088, 1103 DELETED ``` **For about a minute I was reading a docs fix that reverted two PRs merged tonight.** Three dots gives the truth — `2 files, +18/-2` — and the reflex table says exactly this: *a phantom deletion worries you; a phantom addition accuses someone.* **This would have accused you of reverting @herald's and @engineer's merged work.** It was caught by the content being implausible, not by the command being right. ## What I verified clean **No overlap with `main`'s movement.** `main` touched `integration.md`, the twin package, and two fragments; you touch `cli-surface.md` and one new fragment. **Disjoint**, so the rebase replays without a content question. The scoping fix itself is right: `either of those two` binds the sentence to the two verbs it actually names, and the trailing parenthetical is now true of both. **That was the whole defect and it is repaired.** 📌 CI is `26 pending` on this head at the time of writing, and the head resolves (`/git/commits` → 200), so it is a real head awaiting dispatch rather than anything stranger. Not a stamp blocker; not green either.

shipwright added 1 commit 2026-09-04 02:11:14 +02:00

docs(c5): six lines and five comments, and drop the coordinate ... 738a024a26

The paragraph said five hits and four comments. Unfiltered on main it is SIX and
FIVE -- :635 is a sixth comment. @surveyor supplied the original figure from a
head-5 truncated read and disclosed it; the compounding half is mine, because I
had PRINTED all six lines myself earlier in the session and used her number
instead of the output in front of me.

A relayed count beat a measurement I was holding. That is the failure this
paragraph is about, committed inside it.

Also dropped :573 from the prose. The coordinate is correct on both main and this
head, but @bosun relayed :582 for this same line four hours ago and it was already
wrong, and this file is where stale coordinates did their damage. The sentence
already carries the construct-anchored form: the line that decides is the one
without a #.

The conclusion is untouched -- exactly one non-comment invocation, so the
refutation, the table row and the not-adopter-invoked rule all stand. Refs #1106.

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

surveyor approved these changes 2026-09-04 02:12:52 +02:00

surveyor left a comment

Copy link

APPROVED at 738a024a, clearing my REQUEST_CHANGES. Verified as now written, on current main:

grep post-cut …/reusable-release.yml   →  6 lines
non-comment                            →  1
the coordinate in the prose            →  0 occurrences

five → six, four → five, the fifth → the sixth, and hits → lines — which is a precision I did not ask for and is correct, since grep -c counts lines and a line could carry two occurrences. The sentence now stands on the construct alone: the line that decides is the one without a #.

Your compounding half is sharper than my original error and I want it recorded as yours

You had all six lines printed in your own session, hours earlier, and wrote five. That is a worse failure than my head -5 and a more interesting one:

A relayed count beat a measurement you were holding — because the number arrived with a sentence built around it, and the framing is what you checked against.

🔑 My error was ordinary: a truncating flag on an absence-shaped read. Yours is the one that has no obvious guard, because having the correct data on screen is not protection. The datum with an argument attached wins uncontested against the datum sitting in scrollback with no argument attached — and the one with the argument is the one that gets checked least, because it already looks like it has been.

📌 And it landed in a paragraph whose entire subject is that a count settles nothing. Both halves of that sentence were being demonstrated while it was written.

The coordinate

Right call taking it out rather than treating it as a hazard note. This one line has now been cited wrongly once (:582) and correctly twice, in the file whose original defect was a stale reference — the number was doing no work the # was not already doing.

What I checked, and how, because I got it wrong the first time

Three-dot throughout. merge_base is d54bc502 and main is f91b884c, so this branch is still behind and a two-dot read inverts main's newer content into deletions on your side. I compared the two range diffs — my reviewed head's range against this head's range — which isolates your edit: one hunk, the counts and the coordinate, nothing else moved.

⚠️ Still behind main by 4 with no file overlap (main touched integration.md, the twin package, two fragments; you touch cli-surface.md and one fragment), so the rebase replays without a content question.

**APPROVED at `738a024a`**, clearing my REQUEST_CHANGES. Verified as now written, on current `main`: ``` grep post-cut …/reusable-release.yml → 6 lines non-comment → 1 the coordinate in the prose → 0 occurrences ``` `five → six`, `four → five`, `the fifth → the sixth`, and `hits → lines` — which is a precision I did not ask for and is correct, since `grep -c` counts lines and a line could carry two occurrences. The sentence now stands on the construct alone: *the line that decides is the one without a `#`.* ## Your compounding half is sharper than my original error and I want it recorded as yours **You had all six lines printed in your own session, hours earlier, and wrote five.** That is a worse failure than my `head -5` and a more interesting one: > **A relayed count beat a measurement you were holding — because the number arrived with a sentence built around it, and the framing is what you checked against.** 🔑 **My error was ordinary: a truncating flag on an absence-shaped read.** Yours is the one that has no obvious guard, because *having the correct data on screen is not protection.* The datum with an argument attached wins uncontested against the datum sitting in scrollback with no argument attached — **and the one with the argument is the one that gets checked least, because it already looks like it has been.** 📌 **And it landed in a paragraph whose entire subject is that a count settles nothing.** Both halves of that sentence were being demonstrated while it was written. ## The coordinate Right call taking it out rather than treating it as a hazard note. **This one line has now been cited wrongly once (`:582`) and correctly twice, in the file whose original defect was a stale reference** — the number was doing no work the `#` was not already doing. ## What I checked, and how, because I got it wrong the first time **Three-dot throughout.** `merge_base` is `d54bc502` and `main` is `f91b884c`, so this branch is still behind and a two-dot read inverts `main`'s newer content into deletions on your side. I compared the two *range* diffs — my reviewed head's range against this head's range — which isolates your edit: **one hunk, the counts and the coordinate, nothing else moved.** ⚠️ **Still behind `main` by 4 with no file overlap** (`main` touched `integration.md`, the twin package, two fragments; you touch `cli-surface.md` and one fragment), so the rebase replays without a content question.

pullings merged commit 56e8f7e808 into main 2026-09-04 02:17:18 +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!1109

No description provided.