Add comprehensive improvement plan and fix documentation drift

[rlarson20]

Summary

This PR adds a detailed, evidence-based improvement plan (dev-docs/IMPROVEMENT_PLAN.md) documenting concrete bugs, design issues, and a prioritized roadmap for the Volta project. It also updates CLAUDE.md to correct documentation drift and clarify feature flag behavior.

Key Changes

New Document: dev-docs/IMPROVEMENT_PLAN.md

• Concrete bugs (P0–P2): Documents 10 verified issues including:
  • P0-1: Use-after-free in Storage GPU cache (invalidate_cpu_cache takes &self but invalidates borrowed slices)
  • P0-2: Silent gradient dropping in GPU backward paths (early returns without CPU fallback)
  • P0-3: bce_with_logits_loss lacks numerical stability despite docstring claims
  • P1-1 through P1-4: Shape handling, device desync on load, non-scalar backward, prefix collision in Sequential
  • P2: Reshape deep-copy, mixed-device ops, arbitrary tensor size caps, Adam panic on GPU gradients
• Design issues (§3): Critiques of three major decisions:
  • indexing_slicing = deny produces silent-skip numerics instead of loud panics
  • GPU backend cost/benefit inverted (untested in CI, contains only UB, doubles complexity)
  • Documentation and repo hygiene drift (stale README/CLAUDE.md, overlapping audit reports)
• Recommended sequence (§5): Phased roadmap prioritizing correctness (Phase 0), GPU/feature cleanup (Phase 1), hygiene (Phase 2), then performance (Phase 3)

Updated: CLAUDE.md

• Added reference to the new improvement plan as the current prioritized roadmap
• Clarified feature flag gotcha: default = ["gpu", "accelerate"] means plain cargo build/test/clippy compile WITH GPU (contradicting README's opt-in framing)
• Fixed stale claim: "No RNN/Transformer layers" → clarified that MultiHeadAttention, TransformerBlock, PositionalEncoding ARE implemented in src/nn/transformer/

Notable Details

• The improvement plan is grounded in specific file/line evidence (e.g., src/storage.rs:246-257 vs 627-631 for the use-after-free)
• Supersedes older audit documents in notes/ where they conflict
• Establishes a clear principle: "Volta's differentiator is verified correctness. Every hour spent on Phase 0/1 defends that claim; features added before then inherit the silent-failure patterns."
• Provides concrete fix options for each bug (e.g., three approaches to P0-1)
• Includes regression test guidance (e.g., force GPU path to fail and assert CPU fallback)

Rationale

The codebase has accumulated correctness issues, silent-failure patterns, and documentation drift that undermine its stated goal of educational clarity and verified correctness. This plan consolidates findings from full-source review into a single, actionable document to guide future work and prevent further drift.

https://claude.ai/code/session_019R5yozqJu6wTXCNgMhNqKt