docs(tasks): post-remediation sweep — 4 follow-up tasks

Found in the sweep of completed review-001 remediation:
- /publish schema validation fails open on compile error + recompiles
  per request (remediation-introduced, routes.rs:254-268)
- OAI-06 loud-degradation unblocked and still open (HTTP_0 marker)
- HY-06 ExponentialBackoff in public API + COV-02 mTLS success path
  both unblocked post client-config rework
- HY-02/04/11 publish-prep docs gate (104 missing-docs warnings
  re-measured)

Also flagged, not tasked here: WS-12 (alkcall demux 4 GiB discard
alloc) was never actually filed in alkcall's consumer-findings-ledger —
only CF-001 is there. File it when next touching alkcall.

taskgraph: validate clean (42), no cycles
This commit is contained in:
2026-08-30 06:03:29 +00:00
parent 05d6bf8c2c
commit 5d6945cd4b
4 changed files with 251 additions and 0 deletions
@@ -0,0 +1,64 @@
---
id: review-001-missing-docs-sweep
name: missing_docs sweep + publish-prep decisions (HY-02, HY-04, HY-11)
status: pending
depends_on: [review-001-client-config-and-cert-coverage]
scope: moderate
risk: low
impact: project
level: implementation
tags: [infra, review-001, docs, publish-prep]
---
## Description
The pre-crates.io documentation gate, deferred through the remediation
cycle so the API could stabilize first (it now has):
- **HY-02 [major]**: ~104 missing-docs warnings under
`RUSTDOCFLAGS="-W missing_docs" cargo doc --no-deps` (was 110 at
review time; the re-measure is current). Worst offenders were
`openapi_spec.rs` (28), `http_client.rs` (28), `forward.rs` (10),
`server/adapter.rs` (10), `dispatch.rs` (7), `routes.rs` (6); plus
`gateway/mod.rs` / `server/mod.rs` module docs. Sweep and make the
gate pass — better, enforce it (add `-D missing_docs` to
`RUSTDOCFLAGS` in CI or a `#![deny(missing_docs)]`-style lint config
the repo agrees on, so it cannot regress).
- **HY-11**: decide whether `docs/architecture/` (672 KiB) ships in the
published package (the `exclude` list currently keeps it, omits
`docs/reviews/`). If it ships, verify intra-doc links resolve on
docs.rs; if not, confirm ADR references in rustdoc degrade acceptably.
Record the decision in the task summary either way.
- **HY-04**: the `unwrap` inside shipped `test_support`
(`websocket/upgrade.rs:161`, behind the opt-in `test-support` feature)
is documented-as-intentional published API with a panic inside — make
the final call: keep (document on the public item) or restructure to
return `Result`.
Depends on the client task because `http_client.rs` is 28 of the
warnings and that task reshapes the config surface it would document.
## Acceptance Criteria
- [ ] `cargo doc` with `-W missing_docs` (as deny) exits clean — 0 warnings
- [ ] Enforcement landed (CI rustdocflags or lint config) so it stays clean
- [ ] HY-11 decision recorded; `cargo publish --dry-run --allow-dirty` package contents match the decision
- [ ] HY-04 resolved (documented or restructured)
- [ ] `cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check` pass
## References
- docs/reviews/001-initial-implementation-review.md (Part H, HY-02, HY-04, HY-11)
## Notes
> Agent fills during implementation. The `cargo tree -d` and HY-10
> link items: HY-10's ADR-051 placeholder link in
> `src/adapters/from_openapi.rs:12` still resolves to a
> `https://docs.rs/alkhttp` placeholder — fix remaining placeholder/
> relative links opportunistically in this sweep and mark HY-10 fully
> resolved.
## Summary
> Filled on completion.