gate: rustdoc private-link errors surface one dependency layer at a time — try `--keep-going` on doc-warnings

[macanderson]

Problem

make doc-warnings (RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps, Makefile line ~220) and the CI cargo doc -D warnings step abort scheduling new units once one crate fails to document. A dependent crate's check (rmeta) succeeds, so its own doc errors exist but are never reached — they surface only in the NEXT run, after the first layer is fixed.

This bit on 2026-08-06: main went red with two private-intra-doc-link errors in crates/stella-core/src/loop_detect.rs (from #1775). Four parallel unbreak PRs were opened (#1822, #1823, #1829, #1830); the first three fixed only the visible stella-core layer and went red again on two more errors the abort had masked — TRIAGE_STRUCTURE_CHARS in crates/stella-pipeline/src/triage.rs and diff_accountable_mutator in crates/stella-pipeline/src/witness/warrant.rs. Only #1830 (which fixed both crates) unbroke main.

Proposed fix

Add --keep-going to the doc-warnings target and the matching CI step. Documenting a dependent crate needs only its dependencies' rmeta (from Checking), not their successful doc output, so --keep-going should let every workspace crate's doc unit run and report ALL private-link errors in one pass. (Hypothesis — verify it, see below.)

Verify

1. On a scratch branch, reintroduce a private intra-doc link in a public doc comment in stella-core AND one in stella-pipeline (e.g. revert the relevant hunks of docs(stella-core,stella-pipeline): unbreak main — drop rustdoc links to private items #1830).
2. Run RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --keep-going and confirm BOTH crates' errors appear in a single run, and the exit code is nonzero.
3. If the hypothesis fails (dependent doc units genuinely wait on dep doc units), close this with that finding recorded.

Constraints

• doc-warnings honours CARGO_SCOPE (Pre-push gate and CI run the full workspace for a single-crate diff #1135) — keep that working.
• The Makefile gate block in AGENTS.md/CONTRIBUTING.md is guarded by gate-parity (scripts/check-gate-parity.sh); a flag change inside a step should not trip it, but run make gate-parity to confirm.
• CI's required job (.github/workflows/ci.yml) has its own doc step — change both in the same PR.

Done when

A PR that breaks rustdoc in two crates at different dependency depths shows both errors in one doc-warnings run, locally and in CI.

[macanderson]

Triage 2026-08-06: P2 — gate ergonomics, not a live defect: the abort-at-first-crate behavior cost four parallel unbreak PRs a wasted CI round each today, but nothing lands wrong because of it. Plan: as specced in the body — the --keep-going hypothesis is cheap to verify on a scratch branch (step 1-2 of Verify); if it holds, one PR changes the Makefile doc-warnings target and the ci.yml doc step together and runs make gate-parity. Next step for a fresh agent: the scratch-branch experiment.

[macanderson]

Two more instances today, both of which broke main and blocked every open PR — this is now the recurring cause it predicted:

1. crates/stella-cli/src/daemon/boot.rs:59 — [SkipReason::NoResumePoint], where SkipReason is pub(super) and so invisible to a plain cargo doc. Fixed in fix(stella-pipeline,stella-cli): unbreak main — clippy arg count and a dangling boot.rs doc link #1985.
2. crates/stella-protocol/src/event.rs:545 — [CompactionRewrite], not in scope in event.rs (the field beside it spells crate::CompactionRewrite). From fix(stella-core,stella-store): journal compaction rewrites so 'context sent' shows the bytes the model received (#1667) #1979; fixed in fix(stella-pipeline,scripts): unbreak main — two unbreak PRs fixed the same three things, plus the file-size ratchet blocking every PR #2008.

The layering this issue is about is exactly what made them sequential. Instance 1 was in stella-cli, the last crate documented. Once #1985 fixed it, the very next CI run failed on instance 2 in stella-protocol, the first — a link that had been dangling the whole time, invisible behind the earlier failure. Two separate red-main episodes and two separate unbreak PRs for defects that co-existed and could have been reported together. That is the cost --keep-going would have avoided, measured.

A second, cheaper observation from the same episode: neither instance is reachable from make guards-fast or cargo clippy — doc-warnings only runs at the make check/make gate tier. Anyone verifying an unbreak with the fast rungs (a reasonable thing to do when main is red and you want to push a fix quickly) cannot see this class of break at all. If --keep-going lands, it is worth saying so explicitly in the guard's output, so a fast-rung run does not read as a clean bill of health.

Both fixes took the same shape — spell the link with the path the surrounding code already uses — which suggests the convention is worth writing down wherever this is fixed.