docs(tasks): re-validate bracketed follow-up into 3 tasks (OAI-18 decision, streaming-coverage residue, doc-gate fix)

The bracketed planning task's five candidates, re-validated against
the post-bulk tree (0a932e5, all 23 bulk tasks done, 446/568 green):

1. OAI-18 -> review-002-fu-oai18-decision: still key-allowlist-only;
   bulk blockers (yaml/path-item) both landed. Task records the
   enforce-vs-scope-the-advert decision framework from review 002.
2. CON-08/CON-09 close() lever: deferred still (documented v1
   contracts unchanged, no consumer pressure) — not tasked.
3. Cross-crate: CF-001..004 all open in alkcall, no alkhttp-side task;
   PRJ-16 guard already documents its defense-in-depth re-scope
   disposition (no work when CF-004 lands).
4. Stale-comment sweep: mostly absorbed by the bulk (SRV-11 comment
   rewritten in-fix); residue = 3 cargo-doc warnings + WsTimeouts
   redundant Default -> review-002-fu-doc-warnings.
5. ADR-045 version audit: clean (1.4.0 + annotations + test pin).

Post-bulk coverage re-pass (95.89% regions, bulk's new code fully
covered: PRJ-16 guard, body cap, router reorder, batch cap, WS
knobs, OAI-11 node budget all exercised) surfaced one unanticipated
residue -> review-002-fu-stream-error-coverage (forward_stream
build-error arm never exercised on a Sub op; PEM read-failure arms;
over-cap poll_write; SSE split-CRLF edge; from_value structural
rejects; WsTimeouts Default).

Bracketed pass itself marked completed (planning consumed).
taskgraph: 69 valid, no cycles; 3 pending.
This commit is contained in:
2026-08-31 05:40:46 +00:00
parent 0a932e5ec3
commit 5acc561eca
4 changed files with 316 additions and 5 deletions
+62
View File
@@ -0,0 +1,62 @@
---
id: review-002-fu-doc-warnings
name: Fix cargo-doc warnings (dispatch intra-doc links, byte_adapter redundant link) — restore the -D warnings doc gate
status: pending
depends_on: []
scope: single
risk: low
impact: project
level: implementation
tags: [infra, review-002, follow-up, docs]
---
## Description
Bracketed follow-up item 4 (stale-doc sweep) resolved to its
residue. Most of the sweep was absorbed by the bulk itself — SRV-11's
router comment was rewritten as part of the fix (adapter.rs now
records the correct axum 0.8 `route_layer` semantics), and the
`deny(missing_docs)` gate held through all 43 commits. What remains is
a small doc-gate regression the bulk introduced; the crate's own
standard (from the review-001 HY-02/HY-10 sweep, commit 91483a7) is
`RUSTDOCFLAGS="-D warnings" cargo doc` fully clean, and it currently
isn't:
- `dispatch.rs:45` + `:46` — broken intra-doc links `[invoke]` and
`[invoke_streaming]` (added by the PRJ-16 guard doc, 207bca4): the
methods exist but the link target doesn't resolve from this scope
(module-level `//!` docs need fully-qualified paths, e.g.
`[`GatewayDispatch::invoke`](crate::gateway::GatewayDispatch::invoke)`
— or plain backticks)
- `byte_adapter.rs:671``redundant explicit link target` on
`[`DEFAULT_WS_WRITE_TIMEOUT`](crate::websocket::DEFAULT_WS_WRITE_TIMEOUT)`
(the label already resolves to the same destination; the coordinator
flagged this one pre-existing/cosmetic)
## Acceptance Criteria
- [ ] `RUSTDOCFLAGS="-D warnings" cargo doc --no-deps` exits clean
(the review-001 HY-02/HY-10 gate restored)
- [ ] The dispatch module doc still reads correctly (the reference to
`invoke`/`invoke_streaming` readable whether linked or backticked)
- [ ] While in the file: spot-check the WS pump/timeout module docs
against the WS-13/WS-18/WS-17 implementations (the sweep intent —
progress-reset semantics, write-timeout, bare-registry defaults)
and fix any statement the bulk's code has overtaken
- [ ] `cargo test`, `cargo clippy --all-targets -- -D warnings`,
`cargo fmt --check` pass
## References
- src/gateway/dispatch.rs:36-52 (the PRJ-16 guard module doc — link source)
- src/websocket/byte_adapter.rs:665-675 (the redundant link), src/websocket/upgrade.rs (bare-registry defaults doc to spot-check)
- tasks/infra/review-001-missing-docs-sweep.md (the doc gate this restores; HY-10 precedent)
- docs/reviews/002-post-remediation-review.md (Unit 4's stale-comment sweep note; bracketed follow-up item 4)
## Notes
Trivial, commit-alone. If the sweep's spot-check (third checklist box)
finds more than a line or two of drift, split it out rather than
widening this commit — the bulk's doc surface was large (ADR-051 §5,
ADR-066 §OAI-13, http-adapters.md's matrix) and deserves its own pass
if anything significant moved.