docs(spec): SPEC-DISTILL-001 §87 — PMAT-704 post-mortem on Bug B wrong turn

[noahgift]

Summary

Documents the root cause of the PMAT-704 cascade fix (PR #1879). Adds §87 to `docs/specifications/aprender-train/distillation-epic-spec.md` explaining that PR #1869 (Bug B / `RealizarQ4KTeacher`) was a wrong turn — the realizar `_cuda` forward path is CPU-bound and unusable as a distillation teacher on Grace Blackwell GB10.

What the §87 amendment covers

• Finding: 7B vocab-aligned 500-step validation hung at step 0 for 1.5 h with GPU at 0% utilization. Switching to cuBLAS (PMAT-704) raised utilization to 96% on the same hardware.
• Full five-whys chain with file/line citations (`crates/aprender-serve/src/gguf/cuda/cuda.rs:18` — the CPU-heavy `forward_cuda` implementation).
• Root cause: conflated the cuMemAlloc 30 GB ceiling (real, fixed by Bug A) with a phantom SIGKILL on the explicit-managed path that was never verified as OOM-killer via dmesg.
• Fix references: PR fix(distill): default Q4K teacher to CudaTrainerTeacher (cuBLAS) — revert Bug B's slow path (PMAT-704) #1879 (PMAT-704) — cuBLAS default; `RealizarQ4KTeacher` demoted to opt-in fallback via `APR_DISTILL_TEACHER_BACKEND=realizar-q4k`.
• Contract changes: new `apr-distill-teacher-backend-selection-v1.yaml`; `cuda-q4k-frozen-teacher-v1.yaml` demoted (not retracted).
• Methodology lesson: cheap-experiment-before-design discipline — a one-line dispatch flip would have rejected Bug B's hypothesis in 5 minutes; the cascade-momentum anti-pattern shipped a multi-PR detour instead.
• Cascade closure table linking PRs feat(cuda): autodetect Grace Blackwell + Q4K frozen-teacher contract (PMAT-701) #1863, fix(distill): RealizarQ4KTeacher — Q4K-native frozen-teacher path (PMAT-701 Bug B) #1869, chore(distill): default to MODEL-1 7B teacher + SPEC-DISTILL-001 §86 (PMAT-701 follow-up) #1871, fix(eval): apr eval no longer reports fake pass@1=1.0 on broken models (PMAT-702) #1874, fix(distill): vocab-align teacher logits for Qwen2.5-Coder 7B → 0.5B KD (PMAT-703) #1877, fix(distill): default Q4K teacher to CudaTrainerTeacher (cuBLAS) — revert Bug B's slow path (PMAT-704) #1879.

Spec versioning

• Version bumped 1.1.0 → 1.3.0
• Both §86 (from PR chore(distill): default to MODEL-1 7B teacher + SPEC-DISTILL-001 §86 (PMAT-701 follow-up) #1871, pending merge) and §87 (this PR) added to changelog
• §87 includes a cross-reference note in case readers see this on a build of main that predates chore(distill): default to MODEL-1 7B teacher + SPEC-DISTILL-001 §86 (PMAT-701 follow-up) #1871

Test plan

• Markdown renders cleanly
• Section ordering matches existing § convention
• CI: `ci / gate` + `workspace-test` green (docs-only PR; should be fast)

🤖 Generated with Claude Code