local pre-commit rustdoc/check gate now fails on 37 pre-existing warnings after #5891 build.warnings migration

[bug-ops]

Description

PR #5891 (commit 2616f7b, closes #5873) migrated the CI lint-warning gate from RUSTFLAGS="-D warnings" to Cargo's native build.warnings = "deny", committed repo-wide via .cargo/config.toml. Because .cargo/config.toml applies to every cargo invocation (CI and local alike) unless overridden per-invocation, and because build.warnings is wider than the old RUSTFLAGS/RUSTDOCFLAGS combination (it independently denies all local-package rustdoc lints, not just rustdoc::broken_intra_doc_links), the migration surfaced 37 pre-existing rustdoc warnings (rustdoc::private_intra_doc_links x31, rustdoc::redundant_explicit_links x6) across 10 crates.

CI's coverage and rustdoc jobs were given a job-local CARGO_BUILD_WARNINGS: "allow" override to restore their exact pre-migration enforcement scope, and CI is green.

However, .claude/rules/branching.md ("Before Every Commit" / "Before Creating a PR") and root .claude/CLAUDE.md ("Build & Test Commands") still mandate running:

RUSTFLAGS="-D warnings" RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" \
  cargo doc --no-deps --workspace --features "desktop,ide,server,chat,pdf,scheduler"

without the CARGO_BUILD_WARNINGS=allow override that CI's rustdoc job now carries. Since .cargo/config.toml's build.warnings = "deny" applies by default to this local invocation too, the documented local command now fails on the 37 pre-existing warnings — none of which are related to whatever change the developer is committing.

The PR body for #5891 explicitly acknowledges this gap was left unresolved on purpose: "a proposed diff for CLAUDE.md/.claude/rules/branching.md pre-commit command lists (dropping the now-redundant RUSTFLAGS="-D warnings" prefix) was drafted during development but intentionally NOT applied in this PR — those are user-owned governance docs requiring separate explicit approval, out of scope for this change." The underlying migration spec (.local/specs/047-cargo-build-warnings-migration/spec.md, SC-004) also flags this as a "should"-level success criterion that was left unmet for the same reason.

This is exactly the "local checks no longer mirror CI exactly" class of divergence that .claude/rules/branching.md itself warns about (stale-fingerprint / false-green risk section), except here it manifests as a false RED: the mandated local gate now fails universally, for reasons unrelated to any individual change, whereas CI passes.

Reproduction Steps

1. On current main (HEAD 2616f7b or later, with .cargo/config.toml present), run the documented local rustdoc gate exactly as written in .claude/rules/branching.md:

   RUSTFLAGS="-D warnings" RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" \
     cargo doc --no-deps -p zeph-sanitizer
   

2. Observe the build fail.

Expected Behavior

The documented local pre-commit/pre-PR command set should pass/fail in lockstep with CI's actual gate mechanism (per CLAUDE.md's own instruction: "Local checks MUST match the CI feature flags and env vars exactly").

Actual Behavior

warning: public documentation for `ShadowEvent` links to private item `GOAL_SUMMARY_MAX_CHARS`
  --> crates/zeph-sanitizer/src/shadow_memory.rs:51:38
...
error: `zeph-sanitizer` (lib doc) generated 2 warnings
error: warnings are denied by `build.warnings` configuration

This reproduces on every one of the 10 crates carrying the 37 pre-existing warnings (zeph-bench, zeph-tui, zeph-channels, zeph-sanitizer, zeph-skills, zeph-tools, zeph-durable, zeph-core, zeph-worktree, zeph-memory per the migration spec's Phase B verification), meaning the mandated "Before Every Commit" rustdoc gate is currently broken for essentially any commit touching the workspace, until a developer independently discovers they need to add CARGO_BUILD_WARNINGS=allow — undocumented anywhere in branching.md or CLAUDE.md.

The cargo clippy --profile ci ... -- -D warnings and cargo check commands in the same files are unaffected in practice (both already deny warnings, so build.warnings=deny is redundant but harmless there); this issue is scoped specifically to the rustdoc gate commands.

Suggested Fix (two independent, non-exclusive options — needs owner approval per governance-doc policy)

1. Fix the 37 pre-existing rustdoc warnings across the 10 listed crates (retiring the need for any override), and/or
2. Update .claude/rules/branching.md and root .claude/CLAUDE.md's rustdoc-gate commands to add CARGO_BUILD_WARNINGS=allow (matching CI's rustdoc/coverage job overrides), so local and CI enforcement scopes match again.

Either resolves the divergence; a PR should not silently pick one without the doc changes being reviewed, since .claude/rules/branching.md and CLAUDE.md are explicitly called out as user-owned governance docs.

Environment

• Version/commit: 2616f7b (PR ci: migrate lint-warning gate from RUSTFLAGS to build.warnings #5891)
• Features: reproduced with cargo doc --no-deps -p zeph-sanitizer (default features); same root cause applies to the full documented workspace command

Logs / Evidence

See Reproduction Steps / Actual Behavior above — directly reproduced in this CI cycle (CI-1280).