Files
foxhunt/docs
jgrusewski d243a6f080 docs(sp14): spec v2 — critical review corrections
8 corrections from code-anchored critical review at HEAD eaf4adcb9:

1. Direction Q-head emits K=3 (Short/Flat/Long), not K=4. Aux head
   emits K=2 (down/up). Gate 2 q_disagreement now uses K=3↔K=2 mapping
   with Flat masking. Verified against gpu_dqn_trainer.rs:2438.

2. Forward launch order constraint added: aux forward must complete
   before direction Q-head forward (new serial dep). Cited
   pearl_canary_input_freshness_launch_order.

3. Adaptive sigmoid k formula fixed: v1 had unreachable k_max=50
   because formula caps k ≤ k_base. v2 uses max(..., k_min) with
   k_max = k_base implicit.

4. α_grad rate limiter promoted from nice-to-have to v1. Schmitt
   state-flip introduces sigmoid discontinuity. β=0.9 EMA smoothing
   added; new ALPHA_GRAD_SMOOTHED_INDEX slot.

5. q_disagreement_baseline drop: v1 had adaptive baseline as long-EMA
   (feedback loop risk). v2 uses structural 0.5 (analytic K=3-with-
   Flat-masked random alignment). Drop BASELINE_INDEX slot.

6. Backward gradient scaling clarified: α_grad scales dL/dx (input
   gradient flowing back to aux), NOT dL/dW (Q-head's weight grad).
   Q-head learns to use the wire freely; gate only controls upstream
   flow.

7. 4 hard rules added: feedback_no_hiding,
   feedback_no_htod_htoh_only_mapped_pinned,
   feedback_kill_runs_on_anomaly_quickly,
   pearl_canary_input_freshness_launch_order.

8. Smoke A2 explicit kill criteria table added (8 triggers).

Net ISV slot count unchanged (11), composition shifted: dropped
BASELINE, added SMOOTHED. Total impl cost ~1150 LOC (was ~1060).

Verified against current code:
  - TARGET_DIR_ACC_INDEX=372, AUX_DIR_ACC_SHORT_EMA_INDEX=373,
    AUX_DIR_PREDICTION_INDEX=375 (sp13_isv_slots.rs)
  - set_aux_weight clamp(0.05, 0.3) at gpu_dqn_trainer.rs:14722
    (confirms Bug 3 from Smoke A diagnostic)
  - mag_concat_qdir precedent at experience_kernels.cu:4560
    (direction-conditioning pattern; SP14's wire is the analog)
  - state_reset_registry pattern at lines 913-922 (canonical
    template for new EMA fold-reset entries)
  - branch_0_size = 3 in production config (the K=3 finding)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 17:11:04 +02:00
..