A PR whose diff is entirely under docs/ runs zero tests, so a guard whose INPUT
is shipped prose cannot protect the PR lane of the diffs it exists to check. Its
only firing opportunity is after merge, on the shared branch -- which is how next
went red on dacae9273 while the PR that caused it (#3746) was green on every
check.
The docs-lint job in .github/workflows/docs-required.yml -- an ALREADY-REQUIRED
context -- now selects and runs the docs guards that read the specific docs files
the PR changed.
scripts/docs-guard-registry.cjs test file -> the docs paths it reads (63)
scripts/select-docs-guards.cjs pure (changedPaths, registry) -> test files
scripts/lint-docs-guard-registration.cjs drift guard, wired into lint:ci
scripts/ci-test-scope.cjs is NOT touched -- `git diff origin/next --` on it is
empty -- so #764's saving stands and its 21 pinning tests are untouched.
Selection: exact path; trailing-slash directory prefix (boundary-checked --
docs/adrenaline.md does NOT match docs/adr/, which a naive startsWith gets
wrong); and '*' for the 6 entries that walk docs/ generally or read a computed
path. Unknown maps to '*' -- guessing narrow is how a guard silently stops
running. Measured: a typo fix selects 6 of 63; docs/AGENTS.md selects 12;
docs/COMMANDS.md selects 18.
Four things this got wrong first, each found by an independent reviewer or by
probe, and each having been asserted safe in a comment:
1. The registry started as a RULE in ci-test-scope.cjs's RULES, on the theory
that classify()'s !codeChanged normalization made it inert. True for
docs-ONLY diffs; false for MIXED docs+code diffs, where codeChanged is true
and the normalization never runs:
node scripts/ci-test-scope.cjs --files "docs/a.md src/semver.cts"
with the RULE: 25 targeted_tests
origin/next: 3 targeted_tests
Category error: RULES is the scoped lane's input; a docs-guard registry is a
lane manifest for a consumer that never calls classify(). Extracted; pinned
by value.
2. The second attempt was a dedicated workflow with paths: [docs/**]. Such a
workflow never reports on a non-docs PR, so it can never be a required
context without hanging every non-docs PR -- and a non-required check does not
block a merge, so the guard would have been advisory and #3753 unfixed.
docs-required.yml already has no paths: filter, already supplies the required
docs-lint context, already computes docs_changed, and already ran one docs
guard gated on it. Generalizing that step needs no ruleset edit at all.
3. The registry and the drift lint were built from ONE path-segment heuristic, so
both were blind identically -- and blind at the guard that motivated the issue.
The reader-call regex required a character BEFORE its keyword, so a callee
named exactly read( / load( / parse( / doc( / file( / content( could never
match; and only an INLINE path.join(ROOT,'docs','X.md') argument was caught,
missing the two-step-via-variable form -- the MAJORITY spelling -- plus
template literals and concatenation. Detector 1 fired on 14 of ~450 files, so
35 genuine guards sat unregistered while the lint reported 0 violations,
including cursor-reviewer (reads docs/COMMANDS.md, asserts
.includes('--cursor')) and inventory-headings-countfree. The "accepted blind
spot" this shipped with was the common case, not a fringe.
4. With detection fixed the true population is 115 files: 63 genuine guards, 52
incidental. Running all 63 in a REQUIRED check on a one-line typo fix is the
cost #764 exists to avoid -- install.test.cjs is 7840 lines and reads exactly
one docs file, docs/AGENTS.md, for its frontmatter. Dropping it reproduces the
bug; running it for a typo elsewhere is waste. Hence the map.
Then a second review round found six more, all fixed here:
- fragment-single-edit-propagation.install.test.cjs was EXEMPTED as
"overlay fixture only". False: it reads the real docs/registries/eos.json and
asserts on a registry entry name, and reads the real ADR-0001 and asserts its
H1. A docs-only PR touching either would have gone green and red next -- #3753
shipping again, from inside the fix for it. Now registered against both paths,
and all 52 remaining exemptions were re-audited one by one.
- The SUITES-collision guard compared RAW registry keys, but run-tests.cjs strips
a leading `tests/` BEFORE its suite check. So it caught 'all' and missed
'tests/all' -- the only spelling that can actually occur, since every key
carries the prefix. One typo would have run all 824 test files inside the
required job. Now normalized the same way run-tests.cjs normalizes.
- The lint failed OPEN on an unreadable tests dir or candidate file: 0 violations,
ok:true. A guard that cannot read its input must never report success.
- The exemption ratchet gated identity only, so a baselined file that later
STARTED asserting on shipped docs stayed exempt silently -- 52 permanently blind
files. The baseline now fingerprints the docs paths each exempted file
references and fails when that set changes, naming what changed.
- The exemption marker was still honored inside a multi-line template literal in
the header window. The scanner now tracks template-literal and block-comment
state.
- `git diff --name-only | grep '^docs/'` silently dropped C-quoted non-ASCII docs
paths, making docs_changed=false a green zero-guard check. Both call sites now
pass -c core.quotepath=false.
- The run step was gated on hashFiles(), which a force-committed
.docs-guard-tests.txt would satisfy. The step now rm -f's both scratch files
first and gates on an output it sets itself.
Three empty states, deliberately distinct, because conflating them rebuilds
#3753: an empty or malformed registry HARD-FAILS; docs changed with no guard
covering them logs and skips; no docs change is already gated. The middle state
must never be expressed as an empty --files-from, which prints `no tests in suite
"all"` and exits 0 -- a green check that guarded nothing. With the current
registry that state is unreachable, because the six '*' entries always match;
the branch is kept as defensive handling for a future registry and says so.
timeout-minutes: 15 bounds the required job against a hanging fork-supplied test;
it had none. npm ci was added because the job never installed dependencies -- the
previous single-file step got away without it, the registry does not.
docs/contributing/docs-guard-registration.md documents the rule, following its
sibling cross-platform-portability-rules.md, and CONTRIBUTING.md's CI Test
Quality Checks table links to it. It is also load-bearing: without a docs/ file
in the diff this PR would not have triggered its own lane, shipping an
unexercised change to a required check.
One unrelated fix, included because this PR surfaced it and CLAUDE.md forbids
deferring a defect found while working. On this branch's first CI run,
`full test (windows-latest, 24, shard 3/3)` was CANCELLED at exactly 30 minutes;
tests were still passing 0.8s before the cancel, so it is a wall-clock timeout,
not a hang, and a cancelled job reddens `Required tests`.
The cause is not this PR's test file, which costs ~60ms. Shard composition is
unstable: adding ONE file to the unit suite reshuffled 115 of 268 files between
shards, and shard 3 drew a heavier mix. Underneath that is a real pre-existing
defect. tests/ci-test-job-timeout-budget.test.cjs requires every lane's budget to
be >= 1.5x its MEASURED cost -- "a lane that got slower must be re-budgeted, not
excused" -- and its test-full entry recorded 19m from a windows-22 shard. That is
stale. Measured on `next` with none of this PR's changes present: 26m18s (run
32614439702, windows-latest/24 shard 3/3), 23m36s and 23m17s on shard 2/3. So the
lane costs ~26m and the 30-minute cap carried 1.14x headroom, not 1.5x. The gate
had been out of compliance with its own rule; this PR was merely the file
addition that reshuffled shard 3 past the cliff.
Fixed as that file prescribes: measuredMinutes 19 -> 27 with fresh evidence, and
test-full timeout-minutes 30 -> 45. The rule's minimum for 27m is 41; 45 is
deliberately above it because the reshuffle means per-shard worst case moves run
to run, and a budget pinned to the exact minimum would be re-breached by the next
test file anyone adds. Only that one job's timeout changed; test.yml's scope,
matrix and steps are untouched, so #764's saving is unaffected.
Raising that cap let the Windows shard finish (28m45s, inside 45) and uncovered
a real failure the 30-minute cancel had been masking:
`new quick-task branch branches off origin/main (#2916)` died with
`outcome=timed_out exitCode=null`, SIGTERM, at the 15000ms bound.
tests/quick-branching.test.cjs:149 `runStep` runs a `#!/usr/bin/env bash` script
executing MULTIPLE git commands, but was bound to GIT_TIMEOUT_MS (15000) -- the
norm for a SINGLE git plumbing call. tests/helpers/timeouts.cjs already documents
this exact failure and exists to fix it: HOOK_FANOUT_TIMEOUT_MS was created after
PR #3285 recorded "outcome=timed_out exitCode=null at exactly the 15000ms probe
bound while every other lane passed the same commit", and calls that "a bound
sized for the wrong class, not a slow machine". Our failure is that case
verbatim, so both sites move to the class norm rather than to a bigger number.
The same class also failed on `next` itself 21 hours earlier -- run 32608945654,
windows-latest/24 shard 1/3, `plan touching only src/ in a submodule project
keeps worktree isolation ENABLED` -- where tests/worktree-safety.test.cjs:5845
`runGate` fans out to `git config --file .gitmodules` under a hardcoded 30000.
Fixed too, since it is a defect in the tree regardless of which branch surfaced
it.
A survey of the whole tests/ tree found the same class-mismatch at further
bash fan-out sites bound under 60000ms, and the maintainer approved sweeping
them rather than leaving them latent to surface the same way one at a time. 16
fan-out sites across 16 files now use the class norm.
The sweep is class-correctness, not raising numbers until things pass. Sites
were moved ONLY where the bash body demonstrably spawns something (git, node,
npm, a CLI); self-contained shell snippets were left where they are, and are
listed as deliberately unchanged: pure if/printf bodies (copilot-install), pure
array/case builtins (code-review-pipeline-regression:638), a documented
pure-shell gsd_run stub (host-integration), single-process hook calls
(workflow-guard:222/271/302), and a deliberately tight 5000ms fast-check hook
(gsd-write-guard.property). Nothing was lowered. process-seam.test.cjs:513
(literal 300) is untouched on purpose -- it tests timeout BEHAVIOR, so raising
it would destroy what it asserts.
Shared file-level constants were the trap here, and were handled per file rather
than by redefinition: GIT_TIMEOUT_MS has ~15 users in git-base-branch and only 1
is a fan-out; WORKTREE_TIMEOUT_MS has 16 users in worktree.test.cjs and 3 are;
PROBE_TIMEOUT_MS has several in three more files. In each the CALL SITE was
changed and the constant left alone, so no single-plumbing-call site silently
inherited a 60s bound. The one exception is hooks-opt-in.test.cjs, where
HOOK_TIMEOUT_MS has exactly one consumer -- spawnHook, the fan-out itself -- so
redefining it is identical in effect and reads better.
Only two of these sites have actually been observed failing. The rest cite that
shared class and those two run ids rather than inventing evidence of their own.
Co-authored-by: sim <sim@local>
* test(#3211): failing-first coverage for the issue-link follow-up exemption
Adds the regression suite before the policy module exists, so the RED state
is recorded against a real verdict rather than asserted. Covers the reported
gap (a fork test-only follow-up PR cannot satisfy the gate without an inert
closing keyword) and the file-list truncation vector that any diff-shape
exemption must fail closed on.
Refs #3211
* chore(#3211): accept a non-closing issue reference for docs/test-only PRs
The `Issue link required` gate modelled exactly one PR->issue relationship —
"this PR closes that issue" — and its sole exemption additionally required
same-repo identity (#1389), so a fork PR had no exemption path of any kind. A
test-only or docs-only follow-up therefore had to ship a knowingly-inert
`Closes #<already-closed-issue>` to get a green check.
The verdict now lives in scripts/require-issue-link-policy.cjs as a pure,
unit-tested function returning a typed reason. It additionally accepts a
non-closing reference (`Refs #N`, `Follow-up to #N`, ...) but only when every
changed file is under tests/, under docs/, or is a root-level *.md — the same
doc-only shape pre-pr-gate.sh:111 recognizes, minus CHANGELOG.md, which
changeset/lint.cjs classes as user-facing. Source-touching PRs still require a
closing keyword and a PR with no reference at all still hard-fails, so gate
strength is unchanged.
Both constraints the issue names as hard requirements are preserved: the
backmerge exemption keeps its same-repo conjunct, and the failing step's `if:`
stays step-level so the required check reports SUCCESS rather than a
branch-protection-blocking `skipped`.
Also closes a forgery vector found while building this. `gh pr view --json
files` returns at most 100 paths and does not paginate, while the payload's
`changed_files` reports the true total (verified live: PR #3202 returns 100 of
118). A >100-file PR could therefore present a falsely tests-only list. The new
shared helper scripts/lib/pr-changed-files.cjs fails closed when the list
cannot be confirmed complete, and the pre-existing tooling-paths carve-out in
scripts/pr-template-policy.cjs — which relaxed template enforcement on the same
untrustworthy list — now uses it too.
Closes#3211
* fix(#3211): treat the authoritative file count as authority at every list size
Both orthogonal review passes independently found the same blocker.
`fileListIsComplete` only compared the list length against the PR's true
`changed_files` count once the list reached the 100-entry page cap, so any
mechanism that shortened the list BELOW the cap went undetected:
evaluateIssueLink({prBody:"Refs #1", sameRepo:false,
changedFiles:["CONTRIBUTING.md"], changedFilesTotal:3})
-> {ok:true, reason:"ok_followup_reference"}
The concrete exploit was a $GITHUB_OUTPUT heredoc collision. Both this
workflow and pr-template-format.yml wrote the file list with a fixed
terminator (`GSD_EOF` / the even weaker `EOF`), and every path in that value
is attacker-controlled on a fork PR. A file named after the delimiter closes
the value early and drops every path after it, so a fork PR touching src/
could present a list of only its exempt-looking files and take the follow-up
exemption. That is exactly the #1389 property this change is required to
preserve.
Fixed in two independent layers:
1. The total is now the authority at every size, not only at/above the cap.
One rule catches truncation, delimiter collision, and a path containing
a newline, without having to enumerate the mechanisms.
2. Both workflows now use an unguessable random delimiter, per GitHub's
documented guidance for untrusted multiline output.
Also from review: pr-template-format.yml never passed CHANGED_FILES_TOTAL, so
the parameter threaded through evaluatePrTemplate was always undefined in
production and would have permanently blocked the tooling carve-out for any
100+-file PR; its env is now wired. Root-doc exclusion is case-insensitive.
Dropped a no-op `tr '\n' '\n'`.
Refs #3211
* chore(#3211): regenerate install-tree fixtures for the new shared helper
scripts/lib/** ships in the install tree, so adding
scripts/lib/pr-changed-files.cjs drifts all 19 golden fixtures by exactly one
path each. Caught by tests/golden-install-tree.test.cjs (25 failures on the
remote runner), which is the drift detector doing its job — not a defect.
Placement is deliberate: every existing occupant of scripts/lib/ is a CI/dev
helper that already ships (alias-drift-families, allowlist-ratchet, cli-exit,
drift-scan), so a shared helper used by two policy scripts belongs there. The
two policy modules themselves live at the top level of scripts/ and do not
ship.
Regenerated with `npm run gen:install-tree`; the delta is one added path per
fixture and nothing else.
Refs #3211
* fix(#3211): keep the shared CI helper out of the shipped install tree
The remote runner reported 6 failures on the previous head. Two causes.
`scripts/lib/**` is enumerated in `bin/install.js` (GSD_SCRIPTS_LIB_FILES) and
ships to users, and the install suite asserts that enumeration is complete.
Putting the new shared helper there broke four install tests and drifted all 19
golden install-tree fixtures. The right answer is not to add it to the manifest
— it is CI-only tooling used by two scripts that do not ship, so it has no
business in a user's config directory. Moved to `scripts/pr-changed-files.cjs`;
top-level `scripts/` ships only what the installer names explicitly, so nothing
is enumerated and nothing ships. The fixture regeneration from the previous
commit is reverted: the install-tree fixtures are byte-identical to `next`
again, and `bin/` is untouched. That also keeps the diff free of any
user-facing path, so no changeset fragment is required.
The other failure was a stale test, not a regression. The workflow carve-out
suite asserted the backmerge exemption by grepping require-issue-link.yml for
`startsWith(github.head_ref, ...)` and `steps.check.outputs.found`. This change
moved the whole verdict — carve-out included — into the policy module and
renamed the step, so those assertions measured a location the logic no longer
occupies.
Rewritten to lock the property at its new home, and made stronger in the
process: the step-level placement is now verified by PARSING the YAML and
asserting the job carries no `if:` of its own (a job-level `if:` would make the
required check report `skipped` and block branch protection), and the #1389
anti-forgery conjunct is asserted BEHAVIORALLY against evaluateIssueLink for
both sameRepo branches rather than by matching text. The bootstrap fallback
grep is locked too, so the introducing-PR path cannot be silently dropped.
Refs #3211
* fix(#3211): correct the contributor guidance and pin it against the rule
The sticky comment the gate posts still described the qualifying diff shape as
"nothing outside tests/ and docs/". The predicate had since been widened to
also accept root-level *.md, so the guidance was narrower than the rule it
describes — and narrower in the worst direction: a contributor whose PR is
CONTRIBUTING.md plus a test, which is exactly the shape #3211 was filed about,
would have been told they do not qualify while the gate was in fact passing
them. The two failure explanations now name all three accepted shapes and the
CHANGELOG.md exclusion.
This is a shared-rule-across-parallel-surfaces drift: the guidance restates a
rule whose definition lives in EXEMPT_PATH_PREFIXES / isRootLevelDoc /
EXCLUDED_ROOT_DOCS. It was caught by eye, which is not a control. Added the
parity assertion CLAUDE.md prescribes for exactly this: the test parses the
workflow, pulls the github-script body out of the failing step, and asserts it
names every entry of EXEMPT_PATH_PREFIXES and every entry of
EXCLUDED_ROOT_DOCS — derived from the module's exports, never from a second
hardcoded copy — plus the root-level shape and an actionable `Refs #` example.
The test is non-vacuous by construction and by demonstration: it guards against
zero-length iteration and an empty script body, and removing any single
expected token from the real text makes it fail (verified per token, plus the
empty-string case which reports all five missing).
Refs #3211
---------
Co-authored-by: sim <sim@local>
Tom Boucher