docs(672): make the self-test gap discoverable (signals + section pointer)

Re-review of the round-2 head returned MERGEABLE with one LOW: the record's `signals:` field did not mention the self-test gap. That field is the semantic discovery surface -- it is what the MemPalace mirror matches on -- so the most operationally dangerous property of this change ("a gate edit goes live only on merge, having never run") was unreachable by anyone searching for it. Someone asking "how do I test a change to review-verdict.yml" would have found nothing. Adds three signal phrases and points the record's one-line reference at a section rather than at a ~1050-line file. No behaviour change; frontmatter and prose only. Verified the frontmatter still parses under PyYAML rather than the validator's hand parser, per #674 -- an apostrophe in a single-quoted scalar is exactly what that hand parser cannot see. Refs: #672 Decisions-Edit: yes
2026-07-28 23:17:14 +02:00
parent 20b7171fba
commit ceef16081d
1 changed files with 2 additions and 2 deletions
@@ -6,7 +6,7 @@ since: '2026-07-28'
 supersedes: none
 superseded-by: none
 rule: 'The workflow that writes the branch-protection-required `review-verdict/h10` status triggers on `pull_request_target` with `branches: [main]`, never on plain `pull_request`. Gitea resolves a `pull_request` workflow DEFINITION from the PR''s own head commit, so under that trigger a PR editing `.gitea/workflows/review-verdict.yml` ran its own rewritten copy and could post `h10=success` for itself; `pull_request_target` resolves the definition from the base instead. The `branches: [main]` filter is part of the rule, not a refinement of it: base resolution only relocates the rewrite from the head to the base, so without the filter a PR opened into an attacker-pushed base branch runs that branch''s gate. `pull_request_target` is safe HERE only because this job never checks out or executes head-supplied code — it checks out `base.sha` and runs only that tree''s scripts (`ci.shared-pr-file-enumeration`); reintroducing a head checkout under this trigger would be worse than the bug it fixed. This closes the rewrite route through THIS workflow and does NOT close the class: Gitea injects a write-capable `GITEA_TOKEN` into EVERY job, so any ref-resolved workflow — and a collaborator''s own API token, since branch protection binds the context and not its issuer — can still forge `review-verdict/h10`. Tracked in #697; the exemption path has its own separate defects in #698.'
-signals: 'workflow definition resolved from head, PR rewrites the gate that judges it, self-approve a required status check, pull_request_target vs pull_request, gate trigger branches filter, attacker-supplied base branch, required_approvals 0 does not bind an author, forged commit status inherited by sha · paths: `.gitea/workflows/review-verdict.yml`, `scripts/tests/test_pr_changed_files.py` · issues: #672, #663, #649, #622'
+signals: 'workflow definition resolved from head, PR rewrites the gate that judges it, self-approve a required status check, pull_request_target vs pull_request, gate trigger branches filter, attacker-supplied base branch, how to test a change to review-verdict.yml, workflow not exercised by its own PR, gate edit goes live only on merge, required_approvals 0 does not bind an author, forged commit status inherited by sha · paths: `.gitea/workflows/review-verdict.yml`, `scripts/tests/test_pr_changed_files.py` · issues: #672, #663, #649, #622'
 mechanics: '`on: pull_request_target: {branches: [main], types: [opened, reopened, synchronize, ready_for_review]}`; asserted by `test_the_workflow_trigger_is_pull_request_TARGET_scoped_to_main` in `scripts/tests/test_pr_changed_files.py`; the job''s own context is renamed to `... (pull_request_target)` and must stay OUT of branch protection''s required list'
 ---

@@ -60,7 +60,7 @@ status-authority isolation: the sibling guard added here catches only plain-text
 context.

 **The gate is no longer exercised by its own PR** — base resolution cuts both ways, so an edit here
-goes live only on merge, repo-wide, untested. How to verify one safely is in `docs/ci-cd.md`.
+goes live only on merge, repo-wide, untested. Verify one safely per `docs/ci-cd.md` → Review-verdict gate.

 **Residual.** The job's own context is renamed to `... (pull_request_target)`, safe only because it
 was never one of branch protection's required contexts (the two `docker-build.yml` contexts plus