docs(649): narrow the base-ref headline to what the checkout actually binds #683

Merged

timothy merged 1 commits from docs/649-narrow-base-ref-headline into main 2026-07-27 18:33:24 +02:00

Conversation 0 Commits 1 Files Changed 1

+16 -6

timothy commented 2026-07-27 18:32:01 +02:00

Owner

Copy Link

Copy Source

Docs only, no behaviour change. Refs #649, #672.

ci.shared-pr-file-enumeration's bold sentence claimed the base-ref checkout means the workflow "cannot be rewritten by that same PR to weaken its own judgment". That is true of the scripts the job executes and false of the workflow itself — Gitea resolves a pull_request workflow definition from the PR's own head, so a PR editing review-verdict.yml runs its rewritten copy, which can delete the checkout outright or simply post review-verdict/h10=success and stop. Branch protection requires the context, not an author, and carries required_approvals: 0 (#672).

Why a caveat further down wasn't enough

The scoping already existed under "What is deliberately NOT claimed". That does not fix this sentence: it is bold, it is the paragraph a reader resolving the record from the catalog lands on, and someone who stops there leaves with the opposite of the truth. A caveat only works if it is reached.

So the headline now states what the checkout actually binds — the scripts, from the already-reviewed base — and a following paragraph gives the head-resolution hole directly, quoting the superseded claim so a reader who remembers it can see it was retracted rather than wonder whether two records disagree. The later paragraph drops its now-duplicated opener and points at the new one.

Why it's worth a PR of its own

Same failure class as the rest of #649 — a claim stronger than the code — reached through prose rather than through a test. This record is the artifact the catalog routes people to for "how does the PR-file enumeration work", so its headline is load-bearing in a way ordinary prose isn't.

Verification

• decisions_validate.py OK — run after committing, since the Decisions-Edit: yes trailer check reads committed history and cannot pass on a working tree.
• Catalog regeneration is a no-op (frontmatter untouched).
• scripts/tests 338 green.

Credit where due: the head-resolution hole and the correction to this record's claim were found and filed by the parallel session as #672; this PR fixes the sentence that misled.

Docs only, no behaviour change. Refs #649, #672. `ci.shared-pr-file-enumeration`'s bold sentence claimed the base-ref checkout means the workflow "cannot be rewritten by that same PR to weaken its own judgment". That is true of the **scripts** the job executes and **false of the workflow itself** — Gitea resolves a `pull_request` workflow definition from the PR's own head, so a PR editing `review-verdict.yml` runs its rewritten copy, which can delete the checkout outright or simply post `review-verdict/h10=success` and stop. Branch protection requires the *context*, not an author, and carries `required_approvals: 0` (#672). ## Why a caveat further down wasn't enough The scoping already existed under "What is deliberately NOT claimed". That does not fix this sentence: it is **bold**, it is the paragraph a reader resolving the record from the catalog lands on, and someone who stops there leaves with the opposite of the truth. A caveat only works if it is reached. So the headline now states what the checkout actually binds — the scripts, from the already-reviewed base — and a following paragraph gives the head-resolution hole directly, **quoting the superseded claim** so a reader who remembers it can see it was retracted rather than wonder whether two records disagree. The later paragraph drops its now-duplicated opener and points at the new one. ## Why it's worth a PR of its own Same failure class as the rest of #649 — a claim stronger than the code — reached through prose rather than through a test. This record is the artifact the catalog routes people to for "how does the PR-file enumeration work", so its headline is load-bearing in a way ordinary prose isn't. ## Verification - `decisions_validate.py` OK — run **after** committing, since the `Decisions-Edit: yes` trailer check reads committed history and cannot pass on a working tree. - Catalog regeneration is a no-op (frontmatter untouched). - `scripts/tests` 338 green. Credit where due: the head-resolution hole and the correction to this record's claim were found and filed by the parallel session as #672; this PR fixes the sentence that misled.

timothy added 1 commit 2026-07-27 18:32:02 +02:00

docs(649): narrow the base-ref headline to what the checkout actually binds ... c794a48462

The record's bold sentence said the base-ref checkout means the workflow "cannot be
rewritten by that same PR to weaken its own judgment". That is true of the SCRIPTS the job
executes and false of the workflow itself: Gitea resolves a `pull_request` workflow
definition from the PR's own head, so a PR editing `review-verdict.yml` runs its rewritten
copy — which can delete the checkout outright, or just post `review-verdict/h10=success`
and stop. Branch protection requires the context, not an author, and carries
`required_approvals: 0` (#672).

The scoping already existed further down, under "What is deliberately NOT claimed". That
is not good enough for this particular sentence: it is bold, it is the paragraph a reader
resolving this record from the catalog lands on, and someone who stops there leaves with
the opposite of the truth. A caveat only works if it is reached.

So the headline now says what the checkout binds (the scripts, from the already-reviewed
base) and a following paragraph states the head-resolution hole directly, with the
superseded claim quoted so a reader who remembers it can see it was retracted rather than
wonder whether two records disagree. The later paragraph loses its duplicated opener and
points at it instead.

Docs only; no behaviour change. Same failure class the rest of #649 kept turning up — a
claim stronger than the code — reached this time through prose rather than a test.

Refs #649, #672

Decisions-Edit: yes

timothy merged commit ac0f65c743 into main 2026-07-27 18:33:24 +02:00

timothy deleted branch docs/649-narrow-base-ref-headline 2026-07-27 18:33:24 +02:00

timothy referenced this issue from a commit 2026-07-27 18:33:26 +02:00

Merge pull request 'docs(649): narrow the base-ref headline to what the checkout actually binds' (#683) from docs/649-narrow-base-ref-headline into main

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

ad-hoc

One-off / ad-hoc work not tracked by a dedicated issue

api

REST API / HTTP endpoints

bug

Something isn't working

ci-cd

Build, test, deploy pipeline

content

Channel content / schedules / playlists

dependencies

Dependency updates (Renovate)

enhancement

New feature or improvement

frontend

ChicoryTV React SPA frontend

in-progress

Claimed by an active session — do not pick up

jellyfin

Jellyfin tuner / IPTV integration

parked

Excluded from automatic queue pickup; work only when explicitly selected

priority: high

priority: low

priority: medium

review

Adversarial review finding

security

Security / vulnerability fix

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

renovate timothy (Timothy)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: timothy/ersatztv#683