ci(#4472): docs-only PRs skip the Rust-only fat sections; required checks still report

[noahgift]

Refs #4472. This PR does not close the issue; the live docs-only proof lands after it.

What changes

A new change-class job runs scripts/ci_change_class.sh once per run, after the classifier's own case table (--self-test, 14 rows) passes.

The docs class requires every path in the diff to be:

• added or modified (A or M), and
• a *.md file, and
• outside .github/, and
• not compiled into any crate. A file counts as compiled in when a .rs file names it in include_str!, include! or include_bytes! (resolved against that file's own directory, with multi-line includes handled), or a build.rs names it. An env!/concat! literal is matched by basename.

Everything else is full. That covers any other diff, any non-PR event, and a classifier that fails. Every consumer tests == 'docs', so a failure always runs the full set.

	class=docs	full (unchanged)
x86-main	vendored-schemas, guard-tree, guard-cargo, pr-review-shadow, pr-review-sign	all sections
determinism (ARM64)	skipped	runs
mac-check	skipped	runs
workspace-test shards + Σ	unchanged: they run, and their tier still runs the tree readers (readme_contract …)	unchanged
ci / gate	runs, and requires x86-main plus guard-tree and guard-cargo = success. Prints sov.gate: not-triggered: docs-only change (<reason>)	unchanged sov.gate rule
gate	runs, and requires WT, guard-tree and guard-cargo = success. Prints sov.gate and determinism-compare as not-triggered: docs-only change, by name	unchanged

All three required checks (ci / gate, workspace-test, gate) still run and still report on every PR. A section is absent only when the classifier said docs, and the verdict log names it.

Why the skipped sections can be skipped. sov.* (test, lint, coverage, bench, security, provenance), mutants, determinism and provable-ladder all compile or run Rust. A Markdown file that no crate compiles in cannot change their result. The include rule exists because crates/aprender-review-experiment/src/prereg.rs include_str!s and sha-pins docs/specifications/review-experiment-protocol.md and docs/audits/rex-001/analysis-plan.md. Those two files classify full on the real tree.

Red/green proof

1. Classifier case table: 14/14. A mutation (removing the no-match fix for build.rs) turns it red at 2/14.

2. Merge-ref emulation on this commit (--event pull_request, with HEAD^1..HEAD as on a PR's merge ref):

   • README.md + book/src/introduction.md → class=docs
   • README.md + src/lib.rs → class=full (src/lib.rs: not a Markdown file)

3. Verdict-branch guard, wired into guard-tree-steps: scripts/check_ci_gate_docs_class_rule.sh runs the real gate and ci / gate step scripts from ci.yml over 18 rows. Docs is accepted only from a change-class job that succeeded.

   • docs with guard-tree failed → RED
   • docs with workspace-test failed → RED
   • docs with empty results → RED
   • full with docs-shaped results → RED
   • empty class (the classifier failed) → RED
   • a docs output from a failed change-class job → RED
   • docs with everything ok → GREEN
   • full with everything ok → GREEN

   Its --self-test plants three wrong rules, and each one turns the table RED:

   • trusting the output without checking the job result;
   • excusing every section on a docs run;
   • ci / gate trusting x86-main's job result alone.

4. This PR's own run is the docs+code arm. It touches ci.yml and a .sh, so it must classify full and run every section.

5. Live docs-only arm: after merge, a docs-only probe PR's run IDs will be posted on CI has no smart segmentation for docs-only PRs — full fat job + mandatory pr-review quorum run regardless of change type #4472. ci.yml only triggers for PRs against main, so it cannot run before then.

Guards

All of these are green:

• guard_tree_job_test 8/8
• check_ci_gate_mutants_{rule,table_rule,cuda_rule}
• check_receipt_gate_base_owned
• check_workflow_env_defined
• check_ci_fat_secrets_plumbed
• check_guards_are_wired
• check_no_hosted_runners
• check_guard_steps_isolated
• ci_gpu_touched_test 27/27
• fat_driver self-test 60/60
• actionlint (no new findings)

guard_tree_job_test.sh row 5 ("x86-main dropped from gate.needs") was already RED on main. Its sed stopped matching once gate.needs grew past determinism], so the mutant was never applied. The anchor is fixed here.

Notes

• This supersedes ci(#3668): docs-only PRs skip guard-cargo/determinism, fail-closed (PR-2b of #4588 split) #4639 (Docs-only PRs still spend ~45 min in guard-cargo (25) and guard-tree (15): gate them on a single docs_only decision so a roadmap PR's CI is < 10 min #3668). ci(#3668): docs-only PRs skip guard-cargo/determinism, fail-closed (PR-2b of #4588 split) #4639 skipped guard-cargo by moving three of its guards into guard-tree. Here guard-cargo keeps running on docs PRs, which is stricter. Two things from reviewing it are adopted in ci(#4472): docs-only PRs skip the Rust-only fat sections; required checks still report #4717's own terms: the classifier job must have succeeded, and the gate block is executed by a guard. No commit of ci(#3668): docs-only PRs skip guard-cargo/determinism, fail-closed (PR-2b of #4588 split) #4639 is moved. Its scope differed: it covered docs/roadmaps/** and docs/audits/** in any format, including roadmap YAML. This PR's docs class is Markdown only, so a roadmap-YAML-only PR still runs the full set. Widening the class to cover that is a follow-up.

• fold(pr-review-ci): #4503 + #4533 + #4517 — diff classifier/docs tier, FLOW-003 v2.1, fork attest #4605 (scripts/ci/diff_class.sh, the pr-review quorum docs tier) is separate. It decides the quorum tier, not the fat-job segmentation, and making the quorum lighter is out of scope here. Its classifier treats docs/** as docs and so misses the two include_str! files above. That has been flagged to its owner, and the plan is to fold the include rule in so only one classifier remains.

• Mutants. While the MUTANTS-RATCHET early exit stands (MUT-RATCHET: mutants gate → ratchet mode (debt file shrink-only), C187/C188 #4646), mutants are report-only. When fix(ci): RESTORE mutants gate rules after 0.70 (#4646) #4648 restores the pull_request mutants rule, a docs PR's missing mutants section reads RED, which fails closed. fix(ci): RESTORE mutants gate rules after 0.70 (#4646) #4648 will need a docs case.

Agent: aprender-w4472

🤖 Generated with Claude Code

[noahgift]

Auto-merge disarmed by the cop: this changes what ci / gate accepts (docs-only skip), and a gate change waits for the operator's sign-off (C297). It is a row in the 0.70.2 sign-off batch. It re-arms on a signed yes.

[noahgift]

OPERATOR, verbatim: "yes, sign off #4717". Gate change signed off; auto-merge re-armed by the cop.

[github-actions]

§13.11 rung 1 — quorum shadow verdict

S13-SHADOW pr=4717 head=d7a6b3caadfef35a145e4bc1d55b1be9804c7d52 verdict=REFUSE class=Q1 arm_rc=1

Shadow mode: this records a verdict and merges nothing. A refusal
to arm is not a block (§13 adds zero rows to §7) — the pull request is
exactly as green as it was.

[noahgift]

Superseded to clear the open-PR queue; the branch is kept, and aprender-w4472 reopens this when main's T43 change-class table allows the docs-only rule.