docs(runner-probes): rewrite coordinates not only refs, keep result issues, and stop asserting what was not measured (#202)

@codex-reviewer-andresmgsl's three operational corrections.

1. ARMING REWRITES THE COORDINATE. The candidate SHA exists only in the
   identity fork, so a stub still saying heavy-duty/ceremony/...@<sha> cannot
   resolve it — and the candidate's own self-checkout hardcodes
   `repository: heavy-duty/ceremony` beside the ref, so rewriting only
   CEREMONY_SELF_REF makes it fetch the candidate SHA from the canonical
   repository, where it does not exist. Both halves are now explicit, plus a
   grep that enumerates every remaining heavy-duty/ceremony carrier so a
   PARTIAL rewrite refuses instead of silently testing canonical main.

2. RESULT ISSUES ARE NOT RESET SCOPE. I had step 6 keep them as durable
   evidence and the reset section delete them as stale — contradictory, and
   the deleting half would recreate the expiring-log problem the venue exists
   to avoid. Reset removes candidate-specific EXECUTABLE state only; result
   issues may be closed or relabelled, never deleted.

3. NO UNMEASURED CLAIMS. I wrote that a personal namespace is where "the org's
   runner and secrets do not reach". That was not measured — the probe repo was
   deleted immediately and established only 403-on-org / 201-on-personal. The
   no-workaround rule now rests on what was actually ruled: @andres chose an
   ORG-OWNED standing venue, so a personally-owned repo is a different thing
   from the one decided on and cannot satisfy #202's acceptance target. If
   runner reach matters, it gets measured once the venue exists.

test/run.sh 28/28; shellcheck 0.10.0, changelog-armed clean.

Refs #202
This commit is contained in:
cluade-reviewer-andresmgsl 2026-08-05 13:46:03 +00:00
parent e61bb91476
commit b80767e36c

View file

@ -45,9 +45,16 @@ POST /api/v1/user/repos -> 201 (personal namespace only)
``` ```
This is the same shape as the drill delete: a deliberate permission boundary, This is the same shape as the drill delete: a deliberate permission boundary,
not a misconfiguration, and the same rule applies — do not retry it, and do not not a misconfiguration. Do not retry it, and do not work around it by putting
work around it by putting the venue in a personal namespace, where the org's the venue in a personal namespace — **not because a personal namespace is
runner and secrets do not reach. Ask the operator. proven unable to reach the org's runner** (that was not measured; the probe
repository above was deleted immediately, so nothing about runner or secret
reach was established), but because @andres ruled an **org-owned standing
venue** (#5631). A personally-owned repo is a different thing from the one that
was decided on, and cannot satisfy #202's named acceptance target.
If runner or secret reach turns out to matter, measure it once the venue
exists rather than assuming it here.
## Running a probe ## Running a probe
@ -84,12 +91,27 @@ rather than reinvented (`drills/README.md` step 2):
`<identity>/ceremony@probe-<issue>` — and take its canonical SHA. Never `<identity>/ceremony@probe-<issue>` — and take its canonical SHA. Never
create a branch on `heavy-duty/ceremony` named like a tag: it shadows that create a branch on `heavy-duty/ceremony` named like a tag: it shadows that
tag for every consumer until somebody remembers to delete it. tag for every consumer until somebody remembers to delete it.
2. **Install `docs/CONSUMERS.md`'s caller stubs** in the probe repo, pinned to 2. **Rewrite the COORDINATE, not only the ref.** The candidate SHA exists only
that SHA — every `uses:` reference, not some of them. in your fork, so a stub still saying `heavy-duty/ceremony/...@<sha>` cannot
3. **Rewrite `CEREMONY_SELF_REF` in the candidate itself** to the same resolve it — it would fail, or worse, resolve something else. In the probe
canonical SHA. A candidate carries the tag it has not created yet, so the repo, every caller `uses:` becomes
self-consumption checkout cannot resolve until it is rewritten. Both `<identity>/ceremony/<path>@<canonical-sha>`.
carriers — `labels.yml` and `release.yml` — take the same value. 3. **Rewrite the candidate's own self-checkout, both halves.** `labels.yml` and
the release doors hardcode `repository: heavy-duty/ceremony` beside
`ref: ${{ env.CEREMONY_SELF_REF }}`. Changing only the ref makes the
candidate fetch your SHA *from the canonical repository*, where it does not
exist. So: every `repository:` carrier becomes `<identity>/ceremony`, and
both `CEREMONY_SELF_REF` values become the canonical SHA.
**Then prove the rewrite was total**, because a partial one silently tests
canonical `main` instead of the candidate:
```sh
grep -rn 'heavy-duty/ceremony' .github/ docs/CONSUMERS.md
```
Every remaining hit must be prose. A `uses:`, a `repository:` or a pin among
them means the probe is not armed, and its result is about the wrong tree.
4. **Invoke the probe by the event it is about**, and record which: a 4. **Invoke the probe by the event it is about**, and record which: a
`workflow_dispatch` of the caller, or the real board event the probe is `workflow_dispatch` of the caller, or the real board event the probe is
testing. A probe that fires a different event than the one under test testing. A probe that fires a different event than the one under test
@ -98,9 +120,11 @@ rather than reinvented (`drills/README.md` step 2):
number** in the probe repo's result issue. Those four are what make the number** in the probe repo's result issue. Those four are what make the
result reproducible; without the pin especially, a later reader cannot tell result reproducible; without the pin especially, a later reader cannot tell
which tree answered. which tree answered.
6. **Reset removes the candidate-specific fixtures**: the caller stubs, the 6. **Reset removes the candidate-specific EXECUTABLE state**: the caller stubs,
probe workflow and the result branch, so the next probe does not inherit a the probe workflow, the candidate branch — so the next probe cannot inherit
pin it did not choose. The result *issue* stays — it is the evidence. a pin it did not choose. **Result issues are never deleted.** They may be
closed or relabelled; deleting them would recreate the expiring-log problem
this venue exists to avoid.
## Who may reset it ## Who may reset it
@ -110,8 +134,10 @@ his to set at the same time (@codex-reviewer-andresmgsl, #202 review).
Two levels, deliberately separated: Two levels, deliberately separated:
- **content reset** — deleting probe branches, workflows, fixtures and stale - **content reset** — removing probe branches, workflows and fixtures; the
result issues; the ordinary between-probes operation; ordinary between-probes operation. It does **not** include deleting result
issues, which are the evidence and are immutable once written
(@codex-reviewer-andresmgsl, #202 review);
- **archive / delete / admin** — which is where the drill rule's damage came - **archive / delete / admin** — which is where the drill rule's damage came
from, and which no bot identity should hold here. from, and which no bot identity should hold here.