Files
foxhunt/docs/superpowers/specs
jgrusewski d8666a232f docs(sp4): fix all 11 review findings — spec is now source of truth
Resolved every issue from the critical self-review:

1. Param-group count: 7 → 8 throughout. Slot total: 36 → 40 (8 groups × 3
   per-group families = 24 + 16 single = 40). IQL high-tau and low-tau
   are 2 distinct param groups (separate buffers + Adam states), not
   one. The "(Resolved during implementation)" hand-wave deleted.

2. Reset semantics section rewritten — no longer references Xavier-
   derived bootstraps. Sentinel 0 per Pearl A; Wiener-state triples
   reset to 0 alongside ISV slots (160 reset entries total).

3-4. Weight decay and L1 lambda hardcoded α/bootstrap removed. Both
     now follow universal Pearls A+D contract (sentinel-detect +
     Wiener adaptive). For L1, the natural curriculum (λ ramps as
     gradient differentiates) emerges from the signal itself, no
     "Bootstrap = 0.0" constant needed.

5. ε naming collision resolved: ε_div = 1e-8 (Pearl D division-safety),
   ε_clamp_floor = 1.0 (Pearl A consumer cold-start floor). Distinct
   names, distinct purposes.

6. Per-signal kernel signature updated: removed stale `ema_alpha` arg,
   added `wiener_state` pointer + `wiener_state_offset` + uniform
   `alpha_meta` (structural meta-EMA constant).

7. Pearl C engagement counter race fixed. Replaced `clamp_engage_buf
   [group] += 1` (race) with proper register-then-tree-reduce pattern
   mirroring `dqn_grad_norm_kernel`. Per-thread register counter →
   block-shared tree-reduce → single block-leader writes to
   `clamp_engage_per_block_buf[engage_buf_offset + blockIdx.x]`.
   Host sums across blocks. No atomicAdd, consistent with feedback.

8. Pearl D state buffer allocation spelled out: `wiener_state_buf:
   MappedF32Buffer` of size 141 floats (47 slots × 3), per
   `feedback_no_htod_htoh_only_mapped_pinned`. Reset-registry entries:
   40 + 40×3 (new bound slots + Wiener triples) + 7×3 (retrofit
   existing producers' Wiener states) = 181 reset entries.

9. `grad_norm_slow_ema` retirement spelled out in Layer C: removed
   entirely (sole consumer Mech 6 migrates to ISV[GRAD_CLIP_BOUND]).
   Also documented Q_ABS_REF=16 and H_S2_RMS_EMA=96 transition to
   "monitoring-only ISV" — producers stay running, only the orphaned
   Mech 1/2/5/6/9/10 consumer reads removed.

10. Histogram bin range fixed: linear-spaced bins from 0 to step_max
    (avoids log(0) singularity from earlier log-spaced design).
    Linear is also better for p99: top-of-distribution gets ~0.4%
    resolution per bin. Degenerate "step_max == 0" branch handles
    all-zero signals gracefully (skip ISV update, leave previous bound).

11. Pearl D-subsumes-Pearl-A claim CORRECTED: mathematically wrong.
    At t=0, Pearl D's formula yields `x_mean[0] = 0`, not `x[0]`.
    Pearl A's first-observation replacement requires an explicit
    sentinel-detection branch in the producer. Both pearls are
    necessary and complementary; they are not hierarchical.

Slot count math now consistent: 1 target_q + 4 atom_pos +
3×8 per-group + 1 grad_clip + 1 h_s2 + 8 wd_rate + 1 l1_lambda = 40.
Producer count: 15 fused (1 + 4 + 8 + 1 + 1).

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