feat(#3245): gate rustdoc in nix flake check, and clear the workspace

Nothing in the gate read doc-comments: clippy doesn't check intra-doc
links, cargo test doesn't, and no check built docs. So a [`Foo`] pointing
at a renamed, moved or deleted item rendered as plain text and had no
discoverer but a human happening to read the comment.

That matters here more than in most repos, because the convention is to
put a thing's authoritative description in one doc-comment and point at
it from everywhere else -- the design leans on the pointers being real,
and a dangling link is worse than no link since it names something and
sends the reader looking.

Adds `docs-rustdoc` to nix/checks.nix: craneLib.cargoDoc over
--workspace --no-deps --document-private-items, denying six rustdoc
lints. Listed explicitly rather than -D warnings so a new lint appearing
upstream cannot red the build on a class nobody has triaged.

--document-private-items is load-bearing rather than thoroughness for
its own sake: most of this workspace's doc-comments live on private
items and //! module headers, so without it rustdoc checks a small
fraction of the links and the gate sits green while the rot continues.

Then fixes every error it reports, 40 to 0 across nine crates. The
classes differ and so do the fixes:

- public item, wrong scope -> qualify. Node and Node::parent are both
  public; the link failed only because scheduler.rs does not import
  Node. Six sites become [`crate::Node::parent`].
- private item -> downgrade to backticks. Nothing was made public to
  satisfy a lint; changing API surface to appease a doc check would be
  the tail wagging the dog.
- genuinely dead -> [`JobBuilder::insert_into`] names a method that does
  not exist. Insertion is Scheduler::insert_job.
- prose that looks like markup -> argv[0] parsed as a link, and
  <args>/<hex>/<name> parsed as HTML tags.

Note for future fixes: pub(crate) resolves in an intra-doc link, a plain
private fn in a binary crate does not (wait_for_nodes resolved,
connect_hint did not, same crate, same shape).

The check does not ride the clippy/test artifact cache. It takes
cargoArtifacts, but rustdoc needs its own flavour of dependency
metadata, which cargo build does not produce, so a --no-deps docs build
still compiles dependencies it never documents. Measured at 6m47s cold;
that reasoning is recorded in the check's own comment so the next reader
does not re-derive it.

Verified by running the check's exact command against the pre-cleanup
tree first: 40 errors, build failed. A gate that cannot fail is not
evidence, and building it before the cleanup makes that proof free.

hivectl/src/client.rs

@@ -2,7 +2,7 @@
 //! `/run/hyperhive/host.sock`.
 //!
 //! Connect failures are classified into an actionable message before they
-//! reach the operator (see [`connect_hint`]) — the three ways this fails
+//! reach the operator (see `connect_hint`) — the three ways this fails
 //! (not in `hive-admin`, no socket, nobody listening) need three different
 //! fixes, and the raw `Permission denied (os error 13)` names none of them.
 

hivectl/src/dag_progress.rs

@@ -2,11 +2,11 @@
 //!
 //! Split out of `hivectl.rs` (which is already large): everything that
 //! polls the daemon's node queue (`HostRequest::QueueNodes`) and renders
-//! progress lives here. [`wait_for_nodes`] is the entry point the command
+//! progress lives here. [`crate::dag_progress::wait_for_nodes`] is the entry point the command
 //! handlers call; it dispatches to a live `indicatif` animation on a TTY
 //! and a plain line-on-change stream otherwise.
 //!
-//! Consumes `hive-jobq-wire`'s generic [`GraphNode`]/`NodePayload`: a
+//! Consumes `hive-jobq-wire`'s generic `GraphNode`/`NodePayload`: a
 //! node's kind (and, for a root, what submitted it) comes straight off
 //! `payload.label`; node-specific extras (`agent`) ride in
 //! `payload.data`'s opaque kvps — the shape `hive-c0re`'s
@@ -19,7 +19,7 @@
 //! `ids` is always a **batch**, not a single id: a hive-wide op (e.g.
 //! restarting every agent) submits one root per agent, and the whole
 //! batch is polled together in a single `QueueNodes` request per tick —
-//! [`group_by_root`] splits the combined response back into per-root
+//! `group_by_root` splits the combined response back into per-root
 //! groups rather than issuing one round-trip per id.
 
 use std::collections::{BTreeSet, HashMap, HashSet};