alkgen/tasks/implementation/review-wave-3.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
review-wave-3	Wave 3 gate: the release review	completed	w3-release-readiness	narrow	low	phase	review

Description

The wave-3 gate: the release gate, a pure review over the readiness task and everything before it (waves 1 and 2 plus their gates). It closes green only when the crate is honestly shippable: the published artifacts say what the code does, the package carries what it should and nothing it should not, and the freeze inventory records the one-way surfaces the publish creates.

Acceptance Criteria

• README checked against the shipped code line by line: every claim matches the actual surface; no stale framing, no overclaim (the engine-owned-set absence stated plainly)
• CHANGELOG checked against the actual 0.1.0 surface
• rustdoc + doctests verified: cargo doc --no-deps warning-free, examples compile-checked and consistent with the README
• package posture verified: cargo package --list against the package policy (no SDD/plans/research/tasks payload; the architecture docs present), dry-run clean
• freeze inventory reviewed: every listed surface is real (each one traceable to code or a pinned test), the #[non_exhaustive] decision reviewed against ADR-001/008 and the wave-1 interpretation record, the evolution policy written
• conventions audit re-run (no unwrap/expect/panics in non-test src, no unsafe, no async, no filesystem, no em dashes in prose surfaces)
• full verification set re-run clean on the final readiness tree
• gate verdict recorded in Notes: publish unblocked, or blockers listed

References

• docs/plans/implementation.md (wave 3, the release-gate bullet)
• docs/architecture/ (the whole index; the gate reads the release artifacts against the recorded decisions)
• tasks/implementation/w3-release-readiness.md
• tasks/implementation/review-wave-2.md (the gate this follows)

Notes

Gate verdict: GREEN. The publish is unblocked. No blockers, no findings; one observation dispositioned as data (below). The crate is honestly shippable.

Gate review performed 2026-11-07 over the wave-3 readiness commits (4f17221, a7ebd28, ee4053e, 1b2c979) by reading the README, the CHANGELOG, src/lib.rs, src/error.rs, Cargo.toml, and the readiness task's freeze inventory against the shipped code and the architecture docs line by line.

README vs shipped code (line by line): every claim traces. Strict mode always on (src/registry.rs:47, no parameter); one-registry-per- set and partial-name rejection (registry.rs:164 bookkeeping resolve); &str registration with no filesystem path (registration signatures); typed errors with the two-variant enum and source-chain detail (src/error.rs); helper purity as a documented convention (registry.rs:87-91); determinism and no hash-order leak (registry.rs:116-119, pinned by tests); two sinks with the no-atomicity statement (registry.rs:137-142, stated by the battery's write-sink row); EscapePolicy::Html/NoOp with the {{& }} opt-out (src/escape.rs). The usage block, the integration-posture section (A build-script with the emit-layer banner, B for alkforge with the caching rationale, C render-to-compile), and the "what 0.1.0 does not ship" section (no engine-owned sets, bast-codegen gating nothing, the ADR-008 fixture posture) match emit.md, ADR-008, ADR-010, and targets.md. The README usage block is mirrored by the crate docs' doctests so the two cannot drift apart silently; doctests run in the suite.

CHANGELOG vs the 0.1.0 surface: every Added item matches the actual API (verified against src/ and the frozen inventory); the Guarantees section matches the standing conformance rows; the evolution-policy paragraph matches the landed doc comment.

Rustdoc + doctests: cargo doc --no-deps warning-free on the final tree; the two usage doctests pass in cargo test (53 total: 19 lib + 13 conformance + 7 code_proof + 4 ssr_proof + 5 code_fixtures + 3 ssr_fixtures + 2 doctests), identical under --all-features (the ADR-009 coincide holds; reminder (c) remains correctly unassigned since bast-codegen still gates nothing).

Package posture: re-verified on the committed tree: cargo package --list shows exactly 48 files (src, tests + fixtures, the architecture docs, README, CHANGELOG, both licenses, manifests); no AGENTS.md, .opencode/, docs/research/, docs/sdd_process.md, docs/reviews/, docs/plans/, or tasks/. Dry-run clean with the package compile verification passing (48 files, 199.6KiB).

Freeze inventory reviewed: every listed surface traces to code or a pinned test (public API signatures vs src/registry.rs/ error.rs/escape.rs; strict-mode and determinism rows vs tests/conformance.rs and the wave-1 unit tests; purity vs the conventions audit below; the handlebars 6.4 surface vs the battery's recorded substrate observations; the preserve_order context posture vs the code proof). The #[non_exhaustive] decision reviewed against ADR-001/008 and the wave-1 interpretation record: adopted on Error for the right reason (additive evolution documented, non-breaking match sites, posture landed at the freeze itself), declined on EscapePolicy with a defensible rationale (ADR-005 fixes the set at two; construction, not matching, is the consumer interaction). The decision landed in src/error.rs as a doc comment, so it travels with the published API.

Conventions audit (re-run by the gate): zero unwrap/expect/ panic/unsafe/async/filesystem in non-test src (all hits are inside #[cfg(test)] modules or doctests, permitted); doc comments on all public items, no inline // comments in src; the standing em-dash grep shows zero hits across src/, docs/, README.md, CHANGELOG.md, tasks/, tests/, AGENTS.md, Cargo.toml.

Verification set (re-run by the gate on the final tree): cargo test --all-features (53 passing, default-feature run identical), cargo clippy --all-targets --all-features -- -D warnings (clean), cargo fmt --check (clean), cargo doc --no-deps (warning-free), cargo build --target wasm32-unknown-unknown --release (clean), taskgraph validate (21 tasks valid), the ADR-002 tree inspection (handlebars v6.4.4 default only, no dir_source, no script_helper).

One observation, dispositioned as data: the README says "no CLI in v1, by design" citing ADR-010's library-only rule; the architecture docs are the design record the README points to, and the phrase "by design" is the honest summary of a recorded decision, not an overclaim. No change required.

Summary

Wave-3 gate passed green. The release artifacts (README, CHANGELOG, crate docs, package list) say exactly what the shipped code does; the freeze inventory is real and traceable, with the carried #[non_exhaustive] reminder dispositioned explicitly; conventions and the full verification set are clean on the final tree, including the wasm release build and the handlebars feature inspection. The crate is honestly shippable; w3-publish is unblocked.