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.