From b80767e36c58c17b1f68a6663dfbe2ec273162d2 Mon Sep 17 00:00:00 2001 From: cluade-reviewer-andresmgsl Date: Wed, 5 Aug 2026 13:46:03 +0000 Subject: [PATCH] docs(runner-probes): rewrite coordinates not only refs, keep result issues, and stop asserting what was not measured (#202) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit @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/...@ 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 --- docs/RUNNER-PROBES.md | 54 ++++++++++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 14 deletions(-) diff --git a/docs/RUNNER-PROBES.md b/docs/RUNNER-PROBES.md index 7797f6e..65354f0 100644 --- a/docs/RUNNER-PROBES.md +++ b/docs/RUNNER-PROBES.md @@ -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, -not a misconfiguration, and the same rule applies — do not retry it, and do not -work around it by putting the venue in a personal namespace, where the org's -runner and secrets do not reach. Ask the operator. +not a misconfiguration. Do not retry it, and do not work around it by putting +the venue in a personal namespace — **not because a personal namespace is +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 @@ -84,12 +91,27 @@ rather than reinvented (`drills/README.md` step 2): `/ceremony@probe-` — and take its canonical SHA. Never create a branch on `heavy-duty/ceremony` named like a tag: it shadows that tag for every consumer until somebody remembers to delete it. -2. **Install `docs/CONSUMERS.md`'s caller stubs** in the probe repo, pinned to - that SHA — every `uses:` reference, not some of them. -3. **Rewrite `CEREMONY_SELF_REF` in the candidate itself** to the same - canonical SHA. A candidate carries the tag it has not created yet, so the - self-consumption checkout cannot resolve until it is rewritten. Both - carriers — `labels.yml` and `release.yml` — take the same value. +2. **Rewrite the COORDINATE, not only the ref.** The candidate SHA exists only + in your fork, so a stub still saying `heavy-duty/ceremony/...@` cannot + resolve it — it would fail, or worse, resolve something else. In the probe + repo, every caller `uses:` becomes + `/ceremony/@`. +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 `/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 `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 @@ -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 result reproducible; without the pin especially, a later reader cannot tell which tree answered. -6. **Reset removes the candidate-specific fixtures**: the caller stubs, the - probe workflow and the result branch, so the next probe does not inherit a - pin it did not choose. The result *issue* stays — it is the evidence. +6. **Reset removes the candidate-specific EXECUTABLE state**: the caller stubs, + the probe workflow, the candidate branch — so the next probe cannot inherit + 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 @@ -110,8 +134,10 @@ his to set at the same time (@codex-reviewer-andresmgsl, #202 review). Two levels, deliberately separated: -- **content reset** — deleting probe branches, workflows, fixtures and stale - result issues; the ordinary between-probes operation; +- **content reset** — removing probe branches, workflows and fixtures; the + 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 from, and which no bot identity should hold here.