ci: at most one open PR may modify a declared single-writer path (#9598)

* ci: at most one open PR may modify a declared single-writer path

Two PRs reached green independently shipping one physical change: both
rewrote the objectui pin from the same old sha to the same new sha and
both added the same generated changeset -- a byte-identical hunk under
two card numbers. The first entered the merge queue; the second was
green and one flip from enqueueing behind it.

The card-keyed Duplicate Fix Guard answered correctly and is untouched:
the two PRs claimed two genuinely different, independently filed cards.
The duplication existed only in the diff. This adds the second question
and the two gates run side by side.

The key is a declared list, not repo-wide diff intersection, and that is
measured rather than assumed. Over the 300 most recent PRs, pairs whose
open windows overlapped and which shared a changed path: 68 for the
repo-wide key (top collisions: the lock file 33, one plugin manifest 21,
the root manifest 15), 0 for the declared list. A repo-wide key would be
~68 false accusations per 300 PRs, each naming two authors who did
nothing wrong.

Cost is bounded by asking the cheap question first: the gate lists this
PR's own files, intersects with the declared list, and returns after one
paginated call when the intersection is empty. 1 of those 300 PRs
touched a listed path, so the branch that walks other open PRs runs on
~0.3% of runs.

First come, first served, unchanged from the sibling gate: the earlier
PR keeps its claim and the later one goes red naming it by number, URL
and branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja

* test: the wiring permission assertions must read executable lines only

Found by this gate's own ablation sweep. Revoking `contents: read` from
the guard workflow -- which would kill the job in its checkout step,
before the gate judges anything -- left the self-test GREEN, because the
comment explaining why that scope is needed contains those same two
words and the assertion scanned the whole file.

A phantom check: green because of the prose describing the thing it was
meant to verify. Both permission assertions now scan the comment-stripped
workflow, as the package-manager assertion beside them already did, and
the ablation reddens with the string still present in the file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.github/workflows/lint.yml

@@ -224,6 +224,29 @@ jobs:
       - name: Part-of closing-keyword guard self-test
         run: pnpm check:partof-closing-keyword
 
+      # Single-claim path guard self-test (#9402). Same split as the step above
+      # and for the same reason: the guard is a PR-scoped blocking check in its
+      # own workflow, because its question is about OTHER open PRs and needs a
+      # pull request plus an API read that this job has neither of. What runs
+      # HERE is the half that needs no PR — the verdict layer, the exit-code
+      # contract, the short-circuit that makes the gate affordable, and the
+      # declared path list's own invariants.
+      #
+      # That last one is the reason this step is worth its second: the declared
+      # list IS the key, so the realistic way this gate turns into noise is a
+      # careless append to it. The self-test rejects an entry with no stated
+      # reason, rejects a duplicate, and pins that the three measured
+      # high-collision paths (the lock file, the root manifest, one plugin
+      # manifest — 33, 15 and 21 concurrent pairs in 300 PRs) stay OUT of it.
+      #
+      # It also pins the WIRING (the guard workflow still invokes the script,
+      # still subscribes to `synchronize` — without which a claim added in a
+      # second commit is never judged — and still passes the token), so
+      # unwiring the gate reddens here rather than going quiet.
+      # Dependency-free, reads two files; ~0.1s.
+      - name: Single-claim path guard self-test
+        run: pnpm check:single-claim-paths
+
       # PM half-state sweeper self-test (#8528). `scripts/pm/check-half-states.mjs`
       # carried a 79-case --self-test — the H1..H7 predicates, the seat-sticker
       # parser, the transport classifier and its measured container classes —

.github/workflows/single-claim-path-guard.yml

@@ -0,0 +1,107 @@
+# Two PRs reached green independently while shipping ONE physical change: both
+# rewrote the objectui pin from the same old sha to the same new sha and both
+# added the same generated changeset — a byte-identical hunk under two card
+# numbers. The first entered the merge queue; the second was green and one flip
+# from enqueueing behind it, where it would have conflicted on both files.
+#
+# The repo's Duplicate Fix Guard is not broken and is not touched by this file.
+# It asks whether two open PRs claim the same CARD, and it answered correctly:
+# these claimed two genuinely different, independently filed cards, neither a
+# duplicate of the other as written. The duplication existed only in the diff.
+# This workflow adds the second question — do two open PRs write the same
+# at-most-one-writer path — and the two gates run side by side.
+#
+# The rule, the declared path list, the measured false-positive rates that
+# forced a declared list instead of repo-wide diff intersection, and the wording
+# of the failure all live in `scripts/check-single-claim-paths.mjs`; that header
+# is authoritative and this file is the invocation.
+#
+# Sibling shape, deliberately copied rather than reinvented: the Part-of
+# Closing-Keyword Guard is this repo's other single-script PR-scoped blocking
+# check, and this takes its job shape, its runtime pin and its trigger set.
+name: Single-Claim Path Guard
+
+# `synchronize` is the load-bearing one here, and that is the difference from
+# the two body-scoped guards this otherwise copies. Their whole input is the PR
+# body, so `edited` is what they need; this one's input is the PR's CHANGED
+# FILES, which move on every push. A PR that adds a claim on a listed path in
+# its second commit must be judged on that commit, and one that drops the path
+# again must be able to go green without being closed and reopened.
+#
+# `edited` is kept anyway and is not decoration: the failure text tells a reader
+# to close one of the two PRs, and closing the earlier one must let the later
+# one recover. That recovery arrives as an event on the SURVIVING PR only if it
+# is touched — so `edited` is the cheap, no-push way back to green, exactly as
+# in the sibling guards.
+#
+# No `merge_group:` trigger, and not by oversight: a merge-queue event carries
+# no pull request, so this check has nothing to judge there. That also keeps it
+# out of the required-context registry, whose entries must report on queue
+# builds. Branch protection is a settings change no agent seat can make; this
+# publishes a check run, and whether it becomes REQUIRED carries a maintainer
+# ruling. The Duplicate Fix Guard sits in exactly the same position.
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+# Read-only, and that is the whole grant. This gate reports; it never closes a
+# PR, comments, or edits a body. The one incident where a duplicate PR was
+# closed, it was closed by a human who spotted by eye what no gate could see —
+# and a gate that closed PRs by itself would be a far more expensive mistake
+# than the one it prevents.
+#
+# `contents: read` is not optional padding: naming a `permissions:` block at all
+# sets every scope NOT listed to `none`, and this job checks the repo out to get
+# at the script. With only the pull-requests scope here the job dies in the
+# checkout step, before the gate ever runs — a gate that is red for a reason
+# that has nothing to do with what it checks.
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: single-claim-path-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  single-claim-path:
+    name: No other open PR may claim the same single-writer path
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      # Pinned to the same major and spelling as every other setup-node in this
+      # repo, for the measured reason recorded in the sibling guard's header:
+      # a setup-node major whose package-manager-cache default is on reads
+      # `packageManager` out of package.json and shells out to pnpm to find its
+      # store, killing the job in the SETUP step with "Unable to locate
+      # executable file: pnpm" — before the script runs, and naming a tool the
+      # workflow source never mentions. This job installs no package manager on
+      # purpose: the script is dependency-free and imports nothing.
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+
+      # Everything reaches the script through `env:`, never through `${{ }}`
+      # inside the `run:` line. Nothing here is attacker-controlled text today
+      # — a PR number is a number — but the spelling is the one the sibling
+      # guard's self-test pins, and keeping both gates identical on this point
+      # is what stops a later edit from introducing the unsafe form by analogy.
+      #
+      # `PR_NUMBER` is also the witness that separates a real verdict from an
+      # unwired run: with it absent the script exits 2 and says it judged
+      # nothing, rather than exiting 0 and reading as "no violations".
+      #
+      # The token is required, not optional: this gate's question is about OTHER
+      # open PRs, which cannot be answered from the event payload. The read is
+      # short-circuited on the cheap side — when this PR touches none of the
+      # declared paths, which is ~99.7% of runs by measurement, the job makes a
+      # single API call and stops.
+      - name: At most one open PR may modify a declared single-writer path
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: node scripts/check-single-claim-paths.mjs

package.json

@@ -54,6 +54,7 @@
     "check:pm-half-states": "node scripts/pm/check-half-states.mjs --self-test",
     "check:pm-governed-merges": "node scripts/pm/check-governed-merges.mjs --self-test",
     "check:partof-closing-keyword": "node scripts/check-partof-closing-keyword.mjs --self-test",
+    "check:single-claim-paths": "node scripts/check-single-claim-paths.mjs --self-test",
     "check:adr-anchors": "node scripts/check-adr-anchors.mjs --self-test && node scripts/check-adr-anchors.mjs",
     "check:adr-links": "node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs",
     "check:platform-checklist": "node scripts/checklist-select.mjs --self-test && node scripts/check-platform-checklist.mjs",