Document pentest hardening follow-ups

Author: eldryoth

CHANGELOG.md

@@ -149,6 +149,8 @@
 - Updated the roadmap to make `v0.10` an audit-preparation milestone, add
   `v0.11` verification hardening, add `v0.12` stabilization rehearsal, and keep
   `v1.0` gated on evidence instead of schedule.
+- Documented the high-assurance stack-frame cleanup boundary and added focused
+  `decode_chunk` bit-packing verification to the pre-`v1.0` roadmap.
 
 ## 0.8.0 - 2026-05-16
 

README.md

@@ -436,6 +436,13 @@ stack-backed buffers. It returns the backing array and visible length, so
 redacted formatting and drop-time cleanup no longer apply to the returned
 array.
 
+Stack-backed buffers clear their backing arrays when dropped, but they cannot
+clear historical stack-frame copies made by the compiler, caller code, panic
+machinery, or operating system crash capture. For highly sensitive payloads,
+prefer the clear-tail APIs as soon as the value is no longer needed, keep
+secret lifetimes short, and combine crate-level cleanup with process policies
+for core dumps, swap, and crash reporting.
+
 When an owned heap buffer is acceptable but accidental logging is not, use
 `encode_secret` and `decode_secret`:
 

docs/PLAN.md

@@ -486,6 +486,9 @@ weakened or broken.
 - Expand or finalize proof harnesses for length helpers, slice encode/decode
   bounds, in-place decode bounds, clear-tail cleanup behavior, and
   constant-time-oriented validate/decode agreement.
+- Add focused formal-verification coverage for the `decode_chunk` bit-packing
+  logic so overflow and output-bound behavior are checked across all possible
+  decoded 6-bit input combinations.
 - Complete the panic-free public API audit for non-test scalar code. Document
   every remaining bounded internal index with proof, tests, or a local
   invariant in code or policy docs.

docs/SECURITY_CONTROLS.md

@@ -30,6 +30,9 @@ The caller still owns:
 - avoiding accidental copies of secrets before wrapping them in `SecretBuffer`
 - treating stack-buffer `into_exposed_array` calls as boundaries where redacted
   formatting and drop-time cleanup intentionally stop for the returned arrays
+- understanding that stack-backed buffers can clear their own backing arrays
+  but cannot clear historical stack-frame copies made by compiler spills,
+  caller code, panic machinery, crash handlers, or operating system capture
 - treating `SecretBuffer::into_exposed_vec` as a boundary where redacted
   formatting and drop-time cleanup intentionally stop
 - process-wide memory hygiene such as core-dump policy, swap policy, crash
@@ -59,9 +62,12 @@ profiles are strict about the configured line ending and non-final line width.
 
 Cleanup APIs are best-effort initialized-byte cleanup. They are implemented
 without runtime dependencies and without unsafe code in scalar paths. They do
-not claim formal zeroization against compiler behavior, allocator spare
-capacity, copies made outside the wrapper, core dumps, swap, or arbitrary
-process memory disclosure vulnerabilities.
+not claim formal zeroization against compiler behavior, historical stack-frame
+copies, allocator internals, copies made outside the wrapper, core dumps, swap,
+or arbitrary process memory disclosure vulnerabilities. For high-assurance
+secret handling, use the clear-tail APIs promptly and pair them with operating
+system and deployment controls that reduce crash dumps, swap, and broad memory
+disclosure exposure.
 
 ### Side-Channel Posture