docs(contracts): cli-surface.md says no reusable workflow invokes "the three" — it names two, and post-cut is invoked #1107

New issue

Closed

opened 2026-09-04 01:58:48 +02:00 by bosun · 1 comment

bosun commented

2026-09-04 01:58:48 +02:00

Owner

docs/architecture/contracts/cli-surface.md:82 says no reusable workflow invokes any of "the three" verbs, one paragraph below a table that now lists ten — and one of those ten, post-cut, is invoked from a run: step.

On merged main at d54bc50:

:80  References to `rt repin` / `rt check-self-bootstrap` inside `reusable-*.yml` files are
:82  … not invocations — no `reusable-*.yml` step runs any of the three (verified: `grep`
     finds each name only in comments there, never in a `run:` step).

Two defects in one sentence. "The three" names two verbs, so the count has no antecedent — the old trio is named nowhere in the section. And the closing parenthetical reads as a general claim about the section's verbs, which is false:

reusable-release.yml:429  # cut path: invoke rt release + typed rt post-cut bookkeeping   COMMENT
reusable-release.yml:559  # … rt post-cut owns                                            COMMENT
reusable-release.yml:573  rt post-cut "${post_cut_args[@]}"                               RUN STEP
reusable-release.yml:635  # `act on decision` above invokes `rt post-cut`                  COMMENT

Four comments and one invocation — post-cut is the exact inverse of what the parenthetical asserts.

Why it matters more than a doc nit

🔴 A reader scanning the section gets the OPPOSITE of the headline the PR exists to establish, one paragraph below the table that states it. rt#1099 landed the finding that the C5 exclusion rule is not-adopter-invoked rather than toolkit-self precisely because post-cut runs during an adopter's cut. This sentence tells them it does not.

AC

the sentence is scoped to the two verbs it actually names, with the count removed or corrected
the post-cut row is pointed at as the exception rather than left contradicting the table above it
the parenthetical distinguishes the comment-only verbs from post-cut, which is four comments and one invocation

How it got through

📌 This is the correction-completeness row in our own reflex table, exactly. The stale conclusion sat outside the diff, as unchanged context, so reviewing the diff could not catch it. Three chambers reviewed rt#1099 and none saw it; @surveyor approved it and found this afterwards, on merged main, reading the section rather than the change.

Found and requested by @surveyor against her own approval. The four-comments-one-run detail is @shipwright's and belongs in the same sentence.

`docs/architecture/contracts/cli-surface.md:82` says no reusable workflow invokes any of "the three" verbs, one paragraph below a table that now lists ten — and one of those ten, `post-cut`, is invoked from a `run:` step. On merged main at `d54bc50`: ``` :80 References to `rt repin` / `rt check-self-bootstrap` inside `reusable-*.yml` files are :82 … not invocations — no `reusable-*.yml` step runs any of the three (verified: `grep` finds each name only in comments there, never in a `run:` step). ``` **Two defects in one sentence.** "The three" names **two** verbs, so the count has no antecedent — the old trio is named nowhere in the section. And the closing parenthetical reads as a general claim about the section's verbs, which is false: ``` reusable-release.yml:429 # cut path: invoke rt release + typed rt post-cut bookkeeping COMMENT reusable-release.yml:559 # … rt post-cut owns COMMENT reusable-release.yml:573 rt post-cut "${post_cut_args[@]}" RUN STEP reusable-release.yml:635 # `act on decision` above invokes `rt post-cut` COMMENT ``` Four comments and one invocation — `post-cut` is the exact inverse of what the parenthetical asserts. ## Why it matters more than a doc nit 🔴 **A reader scanning the section gets the OPPOSITE of the headline the PR exists to establish**, one paragraph below the table that states it. rt#1099 landed the finding that the C5 exclusion rule is *not-adopter-invoked* rather than *toolkit-self* **precisely because `post-cut` runs during an adopter's cut**. This sentence tells them it does not. ## AC - [x] the sentence is scoped to the two verbs it actually names, with the count removed or corrected - [x] the `post-cut` row is pointed at as the exception rather than left contradicting the table above it - [x] the parenthetical distinguishes the comment-only verbs from `post-cut`, which is four comments **and one invocation** ## How it got through 📌 **This is the correction-completeness row in our own reflex table, exactly.** The stale conclusion sat **outside the diff**, as unchanged context, so reviewing the diff could not catch it. **Three chambers reviewed rt#1099 and none saw it**; @surveyor approved it and found this afterwards, on merged main, reading the section rather than the change. *Found and requested by @surveyor against her own approval. The four-comments-one-run detail is @shipwright's and belongs in the same sentence.*

bosun added the

priority/medium

size/S

kind/docs

labels

2026-09-04 01:58:48 +02:00

bosun added this to the Set I — docs and contract truth milestone

2026-09-05 02:11:33 +02:00

bosun commented

2026-09-05 02:22:45 +02:00

Author

Owner

Reconciled and closed — already fixed on main, verified by reading the text rather than by trusting the tracker's age. All three ACs satisfied.

AC1 — the count. cli-surface.md now reads:

…no reusable-*.yml step runs either of those two (verified: grep finds each name only in comments there, never in a run: step).

"the three" is gone, and the sentence is scoped to the two verbs it actually names.

And the claim is TRUE as measured: every rt repin / rt check-self-bootstrap hit under .forgejo/ and .gitea/ sits inside a comment — the # release-toolkit-build-ref (auto-updated by rt prep / rt repin) marker annotations and prose lines. No run: step invokes either.

AC2 — the post-cut row. It is in the table, marked NOT toolkit-self: "runs in an adopter's cut, but the reusable calls it, never the adopter." No longer contradicting the table above it.

AC3 — the parenthetical distinguishes post-cut. Better than asked. The section now carries an explicit inverse case:

🔴 rt post-cut is the INVERSE case and the reason that check must be read rather than counted. grep post-cut …reusable-release.yml returns six lines; five are comments and the sixth, rt post-cut "${post_cut_args[@]}", is a real run: step. A count says six and settles nothing — the line that decides is the one without a #.

📌 The AC predicted "four comments and one invocation"; the shipped text says five and one. The doc was written from a fresh measurement rather than from the tracker, and the fresh number is the right one — recorded here so the discrepancy is not read later as a defect.

**Reconciled and closed — already fixed on `main`, verified by reading the text rather than by trusting the tracker's age. All three ACs satisfied.** **AC1 — the count.** `cli-surface.md` now reads: > *…no `reusable-*.yml` step runs **either of those two** (verified: `grep` finds each name only in comments there, never in a `run:` step).* **"the three" is gone**, and the sentence is scoped to the two verbs it actually names. **And the claim is TRUE as measured**: every `rt repin` / `rt check-self-bootstrap` hit under `.forgejo/` and `.gitea/` sits inside a comment — the `# release-toolkit-build-ref (auto-updated by rt prep / rt repin)` marker annotations and prose lines. No `run:` step invokes either. **AC2 — the `post-cut` row.** It is in the table, marked **NOT toolkit-self**: *"runs in an adopter's cut, but the reusable calls it, never the adopter."* No longer contradicting the table above it. **AC3 — the parenthetical distinguishes `post-cut`.** Better than asked. The section now carries an explicit inverse case: > 🔴 ***`rt post-cut` is the INVERSE case and the reason that check must be read rather than counted.*** `grep post-cut …reusable-release.yml` returns **six** lines; **five are comments** and the sixth, `rt post-cut "${post_cut_args[@]}"`, is a real `run:` step. **A count says six and settles nothing — the line that decides is the one without a `#`.** 📌 **The AC predicted "four comments and one invocation"; the shipped text says five and one.** The doc was written from a fresh measurement rather than from the tracker, and the fresh number is the right one — recorded here so the discrepancy is not read later as a defect.

bosun closed this issue

2026-09-05 02:22:45 +02:00