.github/workflows/labels-sweep.yml

@@ -3,11 +3,9 @@ name: labels-sweep
 # jobs that rode labels.yml until #209. Triggers and permissions live in the
 # caller; docs/CONSUMERS.md carries the complete caller stub
 # (workflow_dispatch plus the hourly cron, which relocated here with the
-# sweep). Issue events and same-repository PR events still yield a sweep within
+# sweep). Board events still yield a sweep within seconds: labels.yml's
-# seconds: labels.yml's trigger job dispatches this workflow's caller on those
+# trigger job dispatches this workflow's caller on every event it used to
-# events. Fork-headed PR events carry a read-only token on this Forgejo, so
+# run reconcile on.
-# 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
@@ -26,8 +24,7 @@ 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 issue and same-repository PR wake, the same reason cron runs never
+# for every board event, the same reason cron runs never bootstrapped.
-# 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

@@ -2,16 +2,12 @@ name: labels
 # Reusable half of the labels automation. Triggers and permissions live in
 # the caller; docs/CONSUMERS.md carries the complete caller stub.
 #
-# The caller uses pull_request_target, not pull_request, so same-repository PRs
+# The caller uses pull_request_target, not pull_request: every PR in this
-# keep the base repository's write token without running PR code. On this
+# family arrives from a fork, where pull_request runs with a READ-ONLY token
-# Forgejo, unlike GitHub, fork-headed _target runs still receive a read-only
+# and cannot label anything. _target is safe in this workflow because no PR
-# token. Those runs therefore attempt no writes. The scheduled sweep later
+# code is ever checked out or executed — scope reads changed paths and the
-# reconciles state, blockers, and handoff, but it does not apply path-derived
+# path mapping via the API and checks out only the ceremony implementation.
-# scope labels; consumers that require those labels on fork heads apply them
+# Keep it that way.
-# manually. The explicit fork_head job below records that disposition as a
-# 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
@@ -23,14 +19,10 @@ name: labels
 # one `review_requested` event per panelist per request, so every review
 # round displaces runs and the rate scales with panel size. The
 # sweep now lives in labels-sweep.yml behind its own caller, and the
-# trigger job below is its instant wake: it fires on every issue event and
+# trigger job below is its wake: it fires on every event this caller
-# same-repository PR event this caller subscribes to, preserving that part of
+# subscribes — the exact surface that used to run reconcile directly — so
-# the surface that used to run reconcile directly. Same-repository wake latency
+# the wake latency (#137) is unchanged, while a displaced sweep cancels on
-# (#137) remains seconds-scale, while a displaced sweep cancels on the Actions
+# the Actions tab, attached to no PR. PR checks show scope + trigger only.
-# tab, attached to no PR. Fork-headed runs cannot dispatch with their read-only
-# 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
 # writes both use GITHUB_TOKEN. GitHub does not create workflow runs from
@@ -68,7 +60,6 @@ jobs:
     # scope run is clobbered.
     if: >-
       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' &&
@@ -115,12 +106,15 @@ jobs:
           CONFIG_REF: ${{ github.sha }}
 
   trigger:
-    # The sweep's instant wake (#209) keeps the whole non-PR event surface and
+    # The sweep's wake (#209). No `if:`: reconcile carried none, so the
-    # same-repository PRs. Fork-headed PRs are excluded because this Forgejo
+    # trigger keeps the whole event surface the caller subscribes —
-    # gives their pull_request_target run a read-only token (#241); fork_head
+    # workflow_dispatch of the labels caller itself included. That cannot
-    # records which reconciliation waits for the sweep and that path-derived
+    # double-fire bootstrap: this dispatch always carries bootstrap=no, so
-    # scope labels are not applied there. Non-PR events include workflow_dispatch:
+    # a dispatched labels caller yields one plain sweep, and the taxonomy
-    # excluding it would make a dispatched labels caller silently do nothing.
+    # bootstrap fires solely on a manual dispatch of the sweep caller
+    # (whose input defaults to "yes"). Excluding workflow_dispatch here
+    # would instead make a dispatched labels caller do nothing at all —
+    # a silent no-op run is worse than a redundant sweep.
     #
     # LOUD on failure — never `|| true`: a red trigger is the
     # misconfiguration alarm. A consumer that bumps the pin without adding
@@ -128,9 +122,6 @@ jobs:
     # `bootstrap` input (unexpected input), or without `actions: write`
     # on this caller (permission denied) fails HERE, visibly on the PR,
     # instead of silently never sweeping again.
-    if: >-
-      github.event_name != 'pull_request_target' ||
-      github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
       - name: dispatch the sweep
@@ -208,16 +199,3 @@ jobs:
             exit 1
           fi
           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
-    runs-on: ubuntu-latest
-    steps:
-      - name: explain deferred fork labels
-        run: >-
-          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

@@ -7,16 +7,13 @@ name: labels-sweep
 on:
   # The consumer owns this cadence (#203). Hourly is the recommended default
   # when no other engine drives board state: the cron is then the sweep's ONLY
-  # wake for a review verdict landing (there is no
+  # wake for four transition classes — a review verdict landing (there is no
   # 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 state, blocker, and handoff transition for a
+  # claim-reclaim. The labels caller's events carry the rest in seconds, one
-  # fork-headed PR on this Forgejo because its pull_request_target token is
+  # trigger-job dispatch away. Hourly trades ≤1h of latency on those four
-  # read-only (#241). The sweep never applies path-derived scope labels. Issue
+  # while cutting nominal scheduled sweeps from four an hour to one at
-  # events and same-repository PR events carry the rest in seconds, one
-  # 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
@@ -25,9 +22,8 @@ on:
   # A manual full-board sweep. A bare dispatch (input default "yes") also
   # bootstraps the taxonomy on a fresh repo — what dispatching the labels
   # caller did before #209. The reusable's trigger job wakes this workflow
-  # with bootstrap=no on every issue and same-repository PR event — an
+  # with bootstrap=no on every board event — an event-woken sweep must not
-  # event-woken sweep must not re-upsert ~20 labels each time — so declaring
+  # re-upsert ~20 labels each time — so declaring this input is part of the
-  # this input is part of the
   # caller contract: a dispatch naming an undeclared input is refused, and
   # the trigger job goes loudly red.
   workflow_dispatch:

.github/workflows/self-labels.yml

@@ -8,12 +8,8 @@ name: labels
 # Since #209 this caller carries the PR/issue event surface only. The
 # reconcile sweep no longer rides these runs — the reusable's trigger job
 # dispatches the sweep caller (self-labels-sweep.yml here), which owns the
-# hourly cron and the manual/bootstrap workflow_dispatch. Issue events and
+# hourly cron and the manual/bootstrap workflow_dispatch. A board event
-# same-repository PR events below still yield a sweep within seconds, one
+# below still yields a sweep within seconds, one dispatch hop later.
-# dispatch hop later. Fork-headed PRs carry a read-only token on this Forgejo,
-# 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,16 +26,14 @@ on:
   issues:
     types: [opened, closed, edited, reopened]
   pull_request_target:
-    # These carry the head/draft/review facts the sweep derives state:* from.
+    # Every PR arrives from a fork, so these carry the head/draft/review facts
-    # Same-repository heads wake that sweep in seconds; fork heads cannot write
+    # the sweep derives state:* from. labeled/unlabeled are the handoff wake —
-    # with this Forgejo's read-only token, so state, blocker, and handoff
+    # the author's optimistic state:needs-human write, confirmed or corrected
-    # reconciliation waits for the scheduled cadence. The sweep does not apply
+    # here in seconds (#11); synchronize re-derives on every push;
-    # path-derived scope labels to those heads (#241).
+    # review_requested/review_request_removed wake the sweep that clears (or
-    # labeled/unlabeled are the same-repository handoff wake — the author's
+    # restores) blocker:unrequested — without them the one event that makes
-    # optimistic state:needs-human write, confirmed or corrected here in
+    # the label false could not clear it, and a quiet repo wore the red flag
-    # seconds (#11); synchronize re-derives on every push; review_requested/
+    # until the advisory cron (#137).
-    # review_request_removed clear (or restore) blocker:unrequested on that
-    # same instant path (#137).
     types: [opened, reopened, ready_for_review, converted_to_draft, synchronize, labeled, unlabeled, review_requested, review_request_removed]
 permissions:
   contents: read

LABELS.md

@@ -27,10 +27,8 @@ and the reconciler recomputes it from GitHub's own facts.
 `state:needs-human` means exactly one thing — a human could merge this now —
 so it requires zero blockers and head-current approvals; anything less and
 the reconciler takes it back. The author sets it at handoff (the one
-hand-set state). On a same-repository head, the `labeled` event fires the
+hand-set state); the `labeled` event fires the sweep that validates the
-sweep that validates the write within seconds; on a fork head whose
+write within seconds.
-`pull_request_target` token is read-only, validation waits for the scheduled
-sweep cadence (#241).
 
 ## PR blockers — what is in the way? (facts, as many as apply)
 

changelog.d/241.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- Fork-headed label runs stay green without attempting forbidden writes, while same-repository heads keep instant scope and reconciliation wakes (#241).

docs/CONSUMERS.md

@@ -337,18 +337,14 @@ The labels automation is two reusable workflows since #209, adopted
 together at the same pin:
 
 - **`labels.yml`** — the event-facing half, called on PR and issue events.
-  Same-repository PRs keep two write-capable jobs: additive path-based
+  Two jobs: additive path-based `scope:*` labels, and a few-seconds
-  `scope:*` labels, and a few-seconds `trigger` job that wakes the sweep by
+  `trigger` job that wakes the sweep by dispatching the consumer's sweep
-  dispatching the consumer's sweep caller (a REST `POST` to the forge's own
+  caller (a REST `POST` to the forge's own
   `${GITHUB_API_URL}/repos/{owner}/{repo}/actions/workflows/{file}/dispatches`,
   plain `GITHUB_TOKEN` — `workflow_dispatch` is
   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
+  nothing).
-  read-only, so those two jobs do not run. A successful `fork_head` job names
-  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,10 +356,8 @@ together at the same pin:
   as fake red CI that GitHub refuses to rerun (crew#250: `gh run rerun`
   and its `--failed`/`--job` forms all decline a queue-displaced run).
   Behind its own caller, a displaced sweep cancels on the
-  Actions tab, attached to no PR. Same-repository PR checks show `scope` and
+  Actions tab, attached to no PR; PR checks show `scope` and the green
-  the green `trigger`; fork-headed PRs show the green `fork_head` disposition
+  `trigger` only.
-  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`.
@@ -390,14 +384,11 @@ The complete event-facing caller is:
 name: labels
 on:
   pull_request_target:
-    # These carry the head/draft/review facts state:* derives from. Same-repo
+    # Fork PRs; these carry the head/draft/review facts state:* derives from.
-    # heads take the instant write + sweep-dispatch path; this Forgejo gives
+    # labeled/unlabeled are the handoff wake (state:needs-human confirmed here);
-    # fork heads a read-only token, so state, blocker, and handoff reconciliation
+    # synchronize re-derives on every push. review_requested/review_request_removed
-    # waits for the scheduled sweep; path-derived scope labels require a manual
+    # (shipped in 0.3.0, ceremony#137) wake the sweep that clears
-    # write when wanted.
+    # blocker:unrequested when the panel is asked.
-    # 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.
     types: [opened, reopened, ready_for_review, converted_to_draft, synchronize, labeled, unlabeled, review_requested, review_request_removed]
   # Available at 0.2.0 and later (the first tag carrying ceremony#32); a
   # consumer pinned to 0.1.0 omits this block.
@@ -434,24 +425,22 @@ name: labels-sweep
 on:
   # The consumer owns this cadence (#203). Hourly is the recommended default
   # when no other engine drives board state: the cron is then the sweep's only
-  # wake for a review verdict landing (the labels caller has no
+  # wake for four transition classes — a review verdict landing (no
-  # pull_request_review trigger), blocker:ci-red
+  # 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 state, blocker, and handoff
+  # time-based stale / 48h claim-reclaim. The labels caller's events carry the
-  # transition for a fork-headed PR on this Forgejo. The sweep never applies
-  # 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
+  # latency on those four while cutting nominal scheduled sweeps from four an
-  # sweeps from four an hour to one at GitHub's 1-minute floor. Do not delete
+  # hour to one at GitHub's 1-minute floor. Do not delete the cron: it is their
-  # the cron: it is their discovery path. If another engine writes some of
+  # discovery path. If another engine writes some of those transitions, only
-  # those transitions, only the classes with no other writer bound the cadence;
+  # the classes with no other writer bound the cadence; relax it only as that
-  # relax it only as that list shrinks.
+  # list shrinks.
   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
+  # wakes this workflow with bootstrap=no on every board event, so the
-  # event, so the declared input is part of the contract: a dispatch naming an
+  # declared input is part of the contract: a dispatch naming an undeclared
-  # undeclared input is refused, and the trigger job goes loudly red.
+  # input is refused, and the trigger job goes loudly red.
   workflow_dispatch:
     inputs:
       bootstrap:
@@ -488,22 +477,17 @@ repositories allow check data to be read regardless, but a private consumer
 needs the explicit reads above; without them the failure appears as an empty
 `state:*` axis on the board rather than a red workflow run. The labels
 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
+repos included: the trigger job's dispatch is a write, and without it every
-same-repository PR event runs go red at the trigger. Fork-headed PR runs do
+event run goes red at the trigger.
-not enter that write path on this Forgejo; they remain green and depend on a
-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
+to a #209-carrying tag without adding the sweep caller keeps green-looking
-on every issue and same-repository PR event (workflow-not-found; likewise on a
+silence nowhere — the trigger job goes **red on every PR and issue event**
-sweep caller missing its `bootstrap` input, or a labels caller missing
+(workflow-not-found; likewise on a sweep caller missing its `bootstrap`
-`actions: write`). Fork-headed PR runs deliberately skip that trigger and stay
+input, or a labels caller missing `actions: write`), and event-woken sweeps
-green, so their correctness is proven by the sweep caller's presence and its
+stop until the caller lands. That loudness is deliberate: never read
-latest scheduled run, not by the PR check alone. Never read a green
+silence, or a green `scope` alone, as health. Make the adoption one atomic
-`fork_head` disposition as evidence that the scheduled sweep exists. Make the
+PR — pin bump, sweep caller file, `actions: write` line together.
-adoption one atomic PR — pin bump, sweep caller file, and `actions: write` line
-together.
 
 The `issues:` trigger is available at `0.2.0` and later — `0.2.0` is the
 first tag carrying ceremony#32. A consumer pinned to `0.1.0` omits it. Adopt
@@ -554,25 +538,20 @@ carrying the split:
    `actions: read` today (crew does); the trigger job's dispatch is a
    write. The sweep caller keeps `actions: read`.
 
-Bump without the sweep caller and the trigger job goes red on every issue and
+Bump without the sweep caller and the trigger job goes red on every PR
-same-repository PR event. Fork-headed PRs stay green, receive state, blocker,
+and issue event — the loud failure mode above — so never split these
-and handoff reconciliation only from the scheduled sweep, and never receive
+four edits across PRs.
-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
+`pull_request_target` is intentional: fork PRs need the base repository's
-repository's write token without executing PR code. This Forgejo still gives
+token to write labels. The reusable workflows execute no PR code. They check
-fork-headed `_target` runs a read-only token, so they attempt no writes. The
-scheduled sweep later reconciles state, blockers, and handoff; it does not
-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
-`pull_request_target:` shipped in `0.3.0` (ceremony#137). It clears
+`pull_request_target:` shipped in `0.3.0` (ceremony#137) — the wake that
-`blocker:unrequested` the moment the panel is asked on a same-repository head;
+clears `blocker:unrequested` the moment the panel is asked, without which a
-fork heads wait for the sweep cadence on this Forgejo. A consumer picks the
+quiet repo wears that flag until the backstop cron; a consumer picks them up
-events up by pinning `0.3.0` or later, never through mixed refs.
+by pinning `0.3.0` or later, never through mixed refs.
 
 `.github/labels.conf` has one mandatory panel setting, one mandatory
 `triage-actors` setting, zero or more optional per-author panel rows, and

test/labels-triggers.test.sh

@@ -150,33 +150,4 @@ done
 check "pull_request_target keeps the labeled handoff wake" 0 "labeled" \
   trigger_types "$SELF" pull_request_target
 
-# ---- 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 exactly what the scheduled
-# sweep does and does not supply. Require each full normalised expression to
-# appear intact, so deleting or inverting one of its clauses fails the guard.
-job_if_expression() { # $1 = file, $2 = job
-  yq -r ".jobs.$2.if // \"\"" "$1" |
-    tr '\n' ' ' |
-    awk '{$1=$1; print}'
-}
-check "scope writes only for a same-repo PR head" 0 \
-  "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'" \
-  job_if_expression "$REUSABLE" scope
-check "the sweep trigger preserves non-PR events and excludes fork heads" 0 \
-  "github.event_name != 'pull_request_target' || github.event.pull_request.head.repo.full_name == github.repository" \
-  job_if_expression "$REUSABLE" trigger
-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_expression "$REUSABLE" fork_head
-
-fork_head_step() {
-  yq -r '.jobs.fork_head.steps[] | select(.name == "explain deferred fork labels") | .run' \
-    "$REUSABLE" | bash
-}
-check "the fork path distinguishes swept state from unsupported scope writes" 0 \
-  "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