ci: documentation-only changes skip CI

[erikdarlingdata]

What changes at PR time

A documentation-only pull request (every changed file on the docs allowlist: markdown, LICENSE, CITATION.cff, .gitignore, .gitattributes, docs/, Screenshots/, and now llms.txt) no longer:

• runs .NET setup or a package restore in the build job (unchanged from before — that fast path already existed),
• builds or runs the Lite suite because it touched README.md or Lite/README.md (that trigger is removed),
• runs the Darling whole-tree guards in darling-tree-guards (new: the job now reads the build job's own fast-path decision and skips).

A code pull request still runs everything it ran before — the fast path only engages when every changed file is documentation, and this PR's own diff (build.yml, a .cs file) proves that: it is not docs-only, so it runs the full set below.

A push or merge_group to dev/main also takes the fast path now when the change is docs-only. Previously those events forced the restore back on unconditionally as "cheap insurance." Nothing that restore validates — lock files, Directory.Packages.props, global.json — is reachable from a change that is entirely on the docs allowlist: all of those sit on the root filter, which vetoes the fast path via the existing "any lit area vetoes it" guard. So the insurance bought nothing on a docs-only push specifically, and this PR removes the push/merge_group carve-out.

Where it's still caught

LiteRuntimePrerequisiteDocsTests, LlmsTxtCollectorCensusTests, and ReadmeDerivedCountPinTests (the pins that read these docs against the built artifacts) run on every code pull request — because those always build Lite/Darling — and in the nightly. A stale doc landing through a docs-only PR is caught at the next code PR or by the next nightly run, not at PR time. This is the trade Erik accepted ("i don't want docs changes going through ci").

Changes

• docs filter: added llms.txt (the exact root path, not **/*.txt — Darling/Darling.Tests/McpToolsListBudget/*.txt and Lite's copy are test inputs, not docs).
• lite filter (build job) and lite_shard filter (Lite matrix job, kept byte-equal by CrossAppGuardCiGateTests.TheShardJobsFilters_AreByteForByteCopiesOfTheBuildJobs): removed README.md and Lite/README.md. Rewrote the #2489 comment to say what changed and why.
• build job: added a docs-fastpath output (steps.fastpath.outputs.engaged) alongside the existing darling-tests output, so darling-tree-guards can tell "skipped because docs-only" apart from "skipped because the area filters didn't fire for another reason."
• darling-tree-guards: new gate arm — when docs-fastpath == 'true', skip with a notice, checked before the existing darling-tests == 'skipped' arm.
• Classify change for the docs fast path: removed the push/merge_group early-exit that forced engaged=false; rewrote the comment block above it to explain why (see "What changes" above).
• Lite.Tests/LiteRuntimePrerequisiteDocsTests.cs: updated the stale doc-comment note about the two READMEs being named in the lite filter — it's a comment only, the test itself does not parse build.yml's filters.

Not changed

• LockedModeRestoreCoverageTests.cs, CommentFilterAdoptionTests.cs, DocCommentHygieneTests.cs, ReadmeDerivedCountPinTests.cs — read, none of them assert on the exact filter-list contents this PR touches (only on darling-tree-guards' own gating wiring, which the TheDarlingSuite_RunsWhereTheAreaFiltersDoNotReach pin still holds because the new docs-fastpath arm sits before the existing skipped arm and doesn't touch the needs.build.outputs.darling-tests / BackstopRunLine wiring that test pins).
• The seconds-long non-build workflows (claude-review, description-drift, check-branches, Claude review guard) — explicitly out of scope per the brief.

Verification

• dotnet build Darling/Darling.Tests/Darling.Tests.csproj -c Release -p:EnableWindowsTargeting=true — succeeded, 0 warnings/errors.
• dotnet build Lite.Tests/Lite.Tests.csproj -c Release — succeeded (execution is Windows-only CI, not run here per lane rig rules).
• Targeted classes on this Mac (WindowsDesktop stripped from the test runtimeconfig, restored after): CrossAppGuardCiGateTests, LockedModeRestoreCoverageTests, CommentFilterAdoptionTests, DocCommentHygieneTests, ReadmeDerivedCountPinTests — all green (111 total, 0 failed).
• Full Darling.Tests suite once, DARLING_TEST_PG unset: Total: 13585, Failed: 214, Skipped: 723. All 214 failures are the known Mac baseline (Microsoft.WindowsDesktop.App/PresentationFramework unavailable on macOS — AgTopologyCardsTests, ViewerDrillDownTests, etc.), none new.
• Not verified here: the actual measured CI job times and the DOCS FAST PATH ENGAGED notice on a live run. Per the brief, a throwaway docs-only probe PR proves this on GitHub Actions directly (Windows runners aren't available locally). That probe PR is tracked separately and will be closed, never merged, after its checks are read.
• Not verified here: Lite.Tests execution (WPF, Windows-only). CI proves it on this PR's own diff since it touches Lite.Tests/LiteRuntimePrerequisiteDocsTests.cs.

Coordination note

Another lane (issue-4160) is editing this same build.yml in the Darling PG test job (the throwaway-cluster step). This PR does not touch that job. Before any further push here, origin/dev will be merged in (not rebased) to pick up that lane's changes.

CHANGELOG entry

N/A — maintainer ruling / CI wiring only, no user-facing change. Per lane rules, this PR carries no CHANGELOG entry and CHANGELOG.md is not edited.

Update: probe PR status at handoff (context-wall, ~20 min)

Probe PR: #4164 (ci/docs-skip-ci-probe, based on ci/docs-skip-ci, retargeted to dev after an initial base-branch mistake). At the 20-minute context wall, check-branches and description-drift had reported success on it, but the Build workflow itself had not yet appeared in the run list for that PR/SHA — unclear whether it is still queued behind the shared Windows runner pool or something is wrong. Not yet verified: the DOCS FAST PATH ENGAGED notice, that build/Darling PostgreSQL tests/Lite tests (result) all report success, and the measured job times. Whoever picks this up next should re-check gh pr checks 4164 and gh run list --workflow=build.yml filtered to that PR before trusting the fast path live, then close #4164 without merging.

This PR (#4163) itself is unaffected by that gap: its own local verification (build + targeted/full Darling.Tests run) stands as reported above.

Coordinator verification

• Diff read:
  • llms.txt (the exact root path) is added to the docs allowlist.
  • README.md and Lite/README.md are out of both lite filters, which stay byte-equal.
  • The docs-fastpath job output comes from the classify step's own decision, and darling-tree-guards skips on it.
  • The push/merge_group forced restore is removed for docs-only changes only; a code change still restores. release is untouched.
• This PR's own CI passes every job (it touches build.yml, so it runs the full set).
• Probe: probe: docs-only fast path check (throwaway, will be closed) #4164 was closed unmerged. Retargeted to dev, it carried this PR's build.yml diff, so it wasn't docs-only. The probe runs after this merges: a README-only PR against dev, which must show DOCS FAST PATH ENGAGED, the three required checks reporting success, and about a minute in total.
• What stops guarding at PR time: LiteRuntimePrerequisiteDocsTests, LlmsTxtCollectorCensusTests and the README count pins, on a docs-only PR. They still run on every code PR and in the nightly.

[erikdarlingdata]

Probe result. #4165, a one-line README.md change against dev after this merged, was closed unmerged.

• The fast path engages: build took 19 s (it was about 214 s on the README-only README: Darling runs on Linux and monitors PostgreSQL #4158).
• Lite shards: 16–25 s each, down from 250–280 s.
• Darling whole-tree guards: 17 s, down from about 320 s. It was skipped on the docs fast path.
• Darling PG shards: 17–19 s.
• The three required contexts all REPORT success: build, Darling PostgreSQL tests and Lite tests (result). None is stuck on "expected".
• Wall time: about 2 minutes from the first check to the last, including runner queueing.