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:
@@ -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.
|
||||
Reference in New Issue
Block a user