fix: qualify fork label coverage

.github/workflows/labels-sweep.yml

@@ -5,8 +5,9 @@ name: labels-sweep
 # (workflow_dispatch plus the hourly cron, which relocated here with the
 # sweep). Issue events and same-repository PR events still yield a sweep within
 # seconds: labels.yml's trigger job dispatches this workflow's caller on those
-# events. Fork-headed PR events carry a read-only token on this Forgejo and
+# events. Fork-headed PR events carry a read-only token on this Forgejo, so
-# wait for the caller's scheduled cadence instead (#241).
+# state, blocker, and handoff reconciliation waits for the caller's scheduled
+# cadence; the sweep does not apply path-derived scope labels (#241).
 #
 # Detached on purpose (#209): every sweep covers every open PR and all
 # sweeps serialize through ONE shared concurrency group, so GitHub's
@@ -25,7 +26,8 @@ name: labels-sweep
 # taxonomy (its `bootstrap` input defaults to "yes"), exactly what
 # dispatching the labels caller did before the split. The trigger job's
 # dispatches carry bootstrap=no — ~20 label upserts per sweep is too chatty
-# for every board event, the same reason cron runs never bootstrapped.
+# for every issue and same-repository PR wake, the same reason cron runs never
+# bootstrapped.
 #
 # This cannot loop: reconciler writes use GITHUB_TOKEN, and GitHub does not
 # create workflow runs from GITHUB_TOKEN-raised events (the trigger's

.github/workflows/labels.yml

@@ -5,11 +5,13 @@ name: labels
 # The caller uses pull_request_target, not pull_request, so same-repository PRs
 # keep the base repository's write token without running PR code. On this
 # Forgejo, unlike GitHub, fork-headed _target runs still receive a read-only
-# token. Those runs therefore attempt no writes and leave labeling to the
+# token. Those runs therefore attempt no writes. The scheduled sweep later
-# scheduled sweep; the explicit fork_head job below records that disposition
+# reconciles state, blockers, and handoff, but it does not apply path-derived
-# as a successful check. Both write paths execute only for same-repository
+# scope labels; consumers that require those labels on fork heads apply them
-# heads. Scope reads changed paths and the path mapping through the API and
+# manually. The explicit fork_head job below records that disposition as a
-# checks out only the ceremony implementation. Keep it that way (#241).
+# successful check. Both write paths execute only for same-repository heads.
+# Scope reads changed paths and the path mapping through the API and checks out
+# only the ceremony implementation. Keep it that way (#241).
 #
 # The reconcile sweep lived here until #209. Riding the PR-triggered run
 # meant every displacement in the sweep's shared concurrency queue recorded
@@ -26,7 +28,8 @@ name: labels
 # the surface that used to run reconcile directly. Same-repository wake latency
 # (#137) remains seconds-scale, while a displaced sweep cancels on the Actions
 # tab, attached to no PR. Fork-headed runs cannot dispatch with their read-only
-# token, so their labels arrive on the scheduled sweep cadence. PR checks show
+# token, so state, blocker, and handoff reconciliation waits for the scheduled
+# sweep; path-derived scope labels are not applied to fork heads. PR checks show
 # scope + trigger for same-repository heads, or fork_head for fork heads.
 #
 # This cannot loop: the trigger's dispatch and the reconciler's label
@@ -115,7 +118,8 @@ jobs:
     # The sweep's instant wake (#209) keeps the whole non-PR event surface and
     # same-repository PRs. Fork-headed PRs are excluded because this Forgejo
     # gives their pull_request_target run a read-only token (#241); fork_head
-    # records the successful deferral to the scheduled sweep instead.
+    # records which reconciliation waits for the sweep and that path-derived
+    # scope labels are not applied there.
     #
     # LOUD on failure — never `|| true`: a red trigger is the
     # misconfiguration alarm. A consumer that bumps the pin without adding
@@ -205,6 +209,9 @@ jobs:
           echo "labels: sweep dispatched — $SWEEP_WORKFLOW on $branch (bootstrap=no)"
 
   fork_head:
+    # This Forgejo keeps pull_request_target read-only for fork heads (#241),
+    # so name the deliberately unsupported scope write as well as the deferred
+    # state machine instead of letting a green no-op promise full labelling.
     if: >-
       github.event_name == 'pull_request_target' &&
       github.event.pull_request.head.repo.full_name != github.repository
@@ -212,4 +219,4 @@ jobs:
     steps:
       - name: explain deferred fork labels
         run: >-
-          echo "labels: fork head has a read-only token; writes deferred to the scheduled sweep cadence"
+          echo "labels: fork head has a read-only token; state, blocker, and handoff reconciliation deferred to the scheduled sweep; path-derived scope labels are not applied to fork heads"

.github/workflows/self-labels-sweep.yml

@@ -11,11 +11,12 @@ on:
   # pull_request_review trigger on the labels caller), blocker:ci-red set or
   # cleared (no check_suite/check_run/workflow_run), a blocker:conflict when
   # ANOTHER PR merges under this one, and the time-based stale / 48h
-  # claim-reclaim, plus every fork-headed PR transition on this Forgejo because
+  # claim-reclaim, plus every state, blocker, and handoff transition for a
-  # its pull_request_target token is read-only (#241). Issue events and
+  # fork-headed PR on this Forgejo because its pull_request_target token is
-  # same-repository PR events carry the rest in seconds, one trigger-job
+  # read-only (#241). The sweep never applies path-derived scope labels. Issue
-  # dispatch away. Hourly trades ≤1h of latency on the scheduled classes
+  # events and same-repository PR events carry the rest in seconds, one
-  # while cutting nominal scheduled sweeps from four an hour to one at
+  # trigger-job dispatch away. Hourly trades ≤1h of latency on the scheduled
+  # classes while cutting nominal scheduled sweeps from four an hour to one at
   # GitHub's 1-minute billing floor. Do not delete the cron: it is their
   # discovery path. If another engine writes some of those transitions, only
   # the classes with no other writer bound the cadence; relax it only as that

.github/workflows/self-labels.yml

@@ -11,7 +11,9 @@ name: labels
 # hourly cron and the manual/bootstrap workflow_dispatch. Issue events and
 # same-repository PR events below still yield a sweep within seconds, one
 # dispatch hop later. Fork-headed PRs carry a read-only token on this Forgejo,
-# so their successful labels run leaves writes to the hourly sweep (#241).
+# so their successful labels run leaves state, blocker, and handoff
+# reconciliation to the hourly sweep; path-derived scope labels are not
+# applied to those heads (#241).
 on:
   # Narrowed (#199) to the actions that carry a queue-state change the hourly
   # cron cannot wait one cadence for — dropping only labeled/unlabeled/assigned/
@@ -30,7 +32,9 @@ on:
   pull_request_target:
     # These carry the head/draft/review facts the sweep derives state:* from.
     # Same-repository heads wake that sweep in seconds; fork heads cannot write
-    # with this Forgejo's read-only token and wait for its scheduled cadence.
+    # with this Forgejo's read-only token, so state, blocker, and handoff
+    # reconciliation waits for the scheduled cadence. The sweep does not apply
+    # path-derived scope labels to those heads (#241).
     # labeled/unlabeled are the same-repository handoff wake — the author's
     # optimistic state:needs-human write, confirmed or corrected here in
     # seconds (#11); synchronize re-derives on every push; review_requested/

changelog.d/241.md

@@ -1,3 +1,3 @@
 ### Fixed
 
-- Fork-headed label runs now stay green without attempting writes their read-only token cannot make, while same-repository heads keep instant labeling (#241).
+- Fork-headed label runs stay green without attempting forbidden writes, while same-repository heads keep instant scope and reconciliation wakes (#241).

docs/CONSUMERS.md

@@ -345,8 +345,10 @@ together at the same pin:
   one of the two documented exemptions from the token's no-retrigger rule,
   so no PAT anywhere in the path and no loop: the sweep dispatches
   nothing). On this Forgejo a fork-headed `pull_request_target` token is
-  read-only, so those two jobs do not run; a successful `fork_head` job names
+  read-only, so those two jobs do not run. A successful `fork_head` job names
-  the deferral, and the scheduled sweep owns their labels.
+  the disposition: the scheduled sweep later reconciles state, blockers, and
+  handoff, while path-derived `scope:*` labels are not applied to fork heads.
+  Apply those scope labels manually when an outside contribution needs them.
 - **`labels-sweep.yml`** — the reconcile sweep: PR state, blockers,
   handoff, stale status, the issue work queue, and the `needs-ruling`
   invariants on both surfaces — the bare-flag check and the 7-day
@@ -360,7 +362,8 @@ together at the same pin:
   Behind its own caller, a displaced sweep cancels on the
   Actions tab, attached to no PR. Same-repository PR checks show `scope` and
   the green `trigger`; fork-headed PRs show the green `fork_head` disposition
-  and wait for the scheduled sweep cadence.
+  and wait for scheduled state, blocker, and handoff reconciliation. The sweep
+  does not supply their path-derived scope labels.
 
 The consumer keeps its path mapping in `.github/labeler.yml` and its
 review panel plus scope taxonomy in `.github/labels.conf`.
@@ -389,7 +392,9 @@ on:
   pull_request_target:
     # These carry the head/draft/review facts state:* derives from. Same-repo
     # heads take the instant write + sweep-dispatch path; this Forgejo gives
-    # fork heads a read-only token, so they wait for the scheduled sweep.
+    # fork heads a read-only token, so state, blocker, and handoff reconciliation
+    # waits for the scheduled sweep; path-derived scope labels require a manual
+    # write when wanted.
     # labeled/unlabeled are the same-repo handoff wake; synchronize re-derives
     # on every push. review_requested/review_request_removed shipped in 0.3.0
     # (ceremony#137) and wake the same-repo sweep when the panel is asked.
@@ -432,9 +437,10 @@ on:
   # wake for a review verdict landing (no
   # pull_request_review trigger on the labels caller), blocker:ci-red
   # set/cleared, blocker:conflict when another PR merges under this one, and
-  # time-based stale / 48h claim-reclaim, plus every fork-headed PR transition
+  # time-based stale / 48h claim-reclaim, plus every state, blocker, and handoff
-  # on this Forgejo. Issue events and same-repo PR
+  # transition for a fork-headed PR on this Forgejo. The sweep never applies
-  # events carry the rest in seconds, one trigger-job dispatch away. Hourly
+  # path-derived scope labels. Issue events and same-repo PR events carry the
+  # rest in seconds, one trigger-job dispatch away. Hourly
   # trades ≤1h of latency on the scheduled classes while cutting nominal
   # sweeps from four an hour to one at GitHub's 1-minute floor. Do not delete
   # the cron: it is their discovery path. If another engine writes some of
@@ -443,9 +449,9 @@ on:
   schedule: [{cron: "0 * * * *"}]
   # A manual full-board sweep. A bare dispatch (input default "yes") also
   # bootstraps the taxonomy on a fresh repo. The labels caller's trigger job
-  # wakes this workflow with bootstrap=no on every issue and same-repo PR event, so the
+  # wakes this workflow with bootstrap=no on every issue and same-repo PR
-  # declared input is part of the contract: a dispatch naming an undeclared
+  # event, so the declared input is part of the contract: a dispatch naming an
-  # input is refused, and the trigger job goes loudly red.
+  # undeclared input is refused, and the trigger job goes loudly red.
   workflow_dispatch:
     inputs:
       bootstrap:
@@ -485,7 +491,8 @@ caller's `actions: write` is different — it is required everywhere, public
 repos included: the trigger job's dispatch is a write. Without it, issue and
 same-repository PR event runs go red at the trigger. Fork-headed PR runs do
 not enter that write path on this Forgejo; they remain green and depend on a
-healthy scheduled sweep.
+healthy scheduled sweep for state, blocker, and handoff reconciliation. That
+sweep does not apply their path-derived scope labels.
 
 **The failure mode to know before bumping**: a consumer that bumps its pin
 to a #209-carrying tag without adding the sweep caller gets a loud red trigger
@@ -548,14 +555,17 @@ carrying the split:
    write. The sweep caller keeps `actions: read`.
 
 Bump without the sweep caller and the trigger job goes red on every issue and
-same-repository PR event; fork-headed PRs stay green but receive no labels
+same-repository PR event. Fork-headed PRs stay green, receive state, blocker,
-without the scheduled sweep. Never split these four edits across PRs.
+and handoff reconciliation only from the scheduled sweep, and never receive
+path-derived scope labels automatically; apply those manually when wanted.
+Never split these four edits across PRs.
 
 `pull_request_target` is intentional: same-repository PRs keep the base
 repository's write token without executing PR code. This Forgejo still gives
-fork-headed `_target` runs a read-only token, so they attempt no writes and
+fork-headed `_target` runs a read-only token, so they attempt no writes. The
-leave labels to the scheduled sweep. The reusable workflows check out only the
+scheduled sweep later reconciles state, blockers, and handoff; it does not
-consumer's base branch and the pinned ceremony implementation.
+apply path-derived scope labels to those heads. The reusable workflows check
+out only the consumer's base branch and the pinned ceremony implementation.
 The #52 ruling invariants ride exactly these triggers — but the caller above
 is no longer the #18 shape, so adopting current triggers is a stub edit, not
 a bare pin bump. `review_requested` and `review_request_removed` on

test/labels-triggers.test.sh

@@ -153,35 +153,30 @@ check "pull_request_target keeps the labeled handoff wake" 0 "labeled" \
 # ---- fork heads carry a read-only token on this Forgejo (#241) --------------
 # Same-repo heads keep the existing immediate scope + sweep-dispatch path. A
 # fork-headed pull_request_target run must attempt no write: both write-capable
-# jobs exclude it, while one successful job explains that the scheduled sweep
+# jobs exclude it, while one successful job explains exactly what the scheduled
-# owns its labels. These read the parsed workflow fields rather than grepping
+# sweep does and does not supply. Compare the whole normalised expressions: a
-# prose, so a comment cannot satisfy the contract.
+# substring guard also accepts a future negation that inverts the gate.
-job_if_contains_all() { # $1 = file, $2 = job, remaining args = predicates
+job_if_expression() { # $1 = file, $2 = job
-  local file="$1" job="$2" expression predicate
+  yq -r ".jobs.$2.if // \"\"" "$1" |
-  shift 2
+    tr '\n' ' ' |
-  expression="$(yq -r ".jobs.$job.if // \"\"" "$file")"
+    awk '{$1=$1; print}'
-  for predicate in "$@"; do
-    grep -qF "$predicate" <<<"$expression" || return 1
-  done
 }
-check "scope writes only for a same-repo PR head" 0 "" \
+check "scope writes only for a same-repo PR head" 0 \
-  job_if_contains_all "$REUSABLE" scope \
+  "github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name == github.repository && github.event.action != 'labeled' && github.event.action != 'unlabeled' && github.event.action != 'review_requested' && github.event.action != 'review_request_removed'" \
-  "github.event.pull_request.head.repo.full_name == github.repository"
+  job_if_expression "$REUSABLE" scope
-check "the sweep trigger preserves non-PR events and excludes fork heads" 0 "" \
+check "the sweep trigger preserves non-PR events and excludes fork heads" 0 \
-  job_if_contains_all "$REUSABLE" trigger \
+  "github.event_name != 'pull_request_target' || github.event.pull_request.head.repo.full_name == github.repository" \
-  "github.event_name != 'pull_request_target'" \
+  job_if_expression "$REUSABLE" trigger
-  "github.event.pull_request.head.repo.full_name == github.repository"
+check "a fork-headed PR selects the successful explanation job" 0 \
-check "a fork-headed PR selects the successful explanation job" 0 "" \
+  "github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name != github.repository" \
-  job_if_contains_all "$REUSABLE" fork_head \
+  job_if_expression "$REUSABLE" fork_head
-  "github.event_name == 'pull_request_target'" \
-  "github.event.pull_request.head.repo.full_name != github.repository"
 
 fork_head_step() {
   yq -r '.jobs.fork_head.steps[] | select(.name == "explain deferred fork labels") | .run' \
     "$REUSABLE" | bash
 }
-check "the fork path names its read-only token and sweep-cadence wake" 0 \
+check "the fork path distinguishes swept state from unsupported scope writes" 0 \
-  "read-only token; writes deferred to the scheduled sweep cadence" \
+  "read-only token; state, blocker, and handoff reconciliation deferred to the scheduled sweep; path-derived scope labels are not applied to fork heads" \
   fork_head_step
 
 summary