gitadmin/foxhunt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(sp17-3.3): Phase 3 close-out — canonical HEALTH_DIAG line + pearl

Browse Source 
Phase 3.3 finalises the SP17 dueling-Q diagnostic chain. Canonical
HEALTH_DIAG line (already emitted by Phase 3.2 commit b6b17d46b) matches
the plan's exact format spec at line 1064-1066:

  HEALTH_DIAG[N]: dueling [v_share=(d=X m=Y o=Z u=W)]
                          [a_var=(d=A m=B o=C u=D)] [clip=K]

Reader parsing table added to audit doc, Phase 4 smoke gate criteria
documented:
  - a_var > 0.01 per branch throughout (regression detector)
  - v_share ∈ [0.3, 0.7] per branch (balanced dueling)
  - clip ∈ [0.5, 5.0] (magnitude scale healthy)

Memory pearl `pearl_sp4_histogram_warp_tile_undercount` filed
(MEMORY.md updated separately as it's a user-private file outside the
worktree). Documents the SP17 Phase 3.2 test-data trap discovered
during the advantage_clip_bound oracle test: `sp4_histogram_p99`'s
documented "1/(256×32) loss for typical signals" qualifies on signal
distribution; lockstep-uniform synthetic patterns violate the
assumption. Fix is per-element jitter in test data — NOT atomicAdd
(which would violate `feedback_no_atomicadd`). Real |A_centered| in
production is continuous, so the issue is test-only.

Phase 3 commit chain (atomic per `feedback_no_partial_refactor`):
  - 1e70cd5e5 Phase 3.1: A_var_ema + 1 GPU oracle test
  - b6b17d46b Phase 3.2: V_share + advantage_clip_bound + 2 GPU oracles
  - this commit: closeout audit doc

13/13 SP17 GPU oracle tests pass on RTX 3050 Ti in 2.4s.

Phase 3 is observability-only — NO consumer path is modified. The clip
bound is producer-tracked but NOT yet wired as an actual clip on any
kernel; that's Phase 5 follow-up.

Plan: docs/superpowers/plans/2026-05-08-sp17-dueling-q-network.md
      Phase 3.3.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
jgrusewski
2026-05-08 23:04:41 +02:00
parent b6b17d46bb
commit 0c57a5a31f
1 changed files with 38 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/dqn-wire-up-audit.md
View File

@@ -2,6 +2,44 @@
**Status:** Populated during Plan 1 Task 6 (A.5 orphan audit). Updated on every commit per Invariant 7.
## 2026-05-08 — SP17 Phase 3.3: Phase 3 close-out + memory pearl
Phase 3.3 finalises the SP17 dueling-Q diagnostic chain:
**Canonical HEALTH_DIAG line format** (per-epoch, alongside `v_a_means`):
```
HEALTH_DIAG[N]: dueling [v_share=(d=X m=Y o=Z u=W)] [a_var=(d=A m=B o=C u=D)] [clip=K]
```
The 9 ISV slots [474..483) are emitted in this single line, matching the plan's exact format spec at line 1064-1066. Reader parsing pattern:
| Field | Slot | Meaning | Health interpretation |
|---|---|---|---|
| `v_share=(d= ...)` | 478..482 | Per-branch `\|E[V]\| / (\|E[V]\| + \|E[A_centered, picked]\|)` | ≈0.5 = healthy split; →1.0 with a_var→0 = pre-SP17 V-dominated regression |
| `a_var=(d= ...)` | 474..478 | Per-branch `Var_a(A_centered)` over actions | >0 = policy discriminates; →0 = "all actions equivalent, V dominates" |
| `clip=K` | 482 | Adaptive `p99(\|A_centered\|) × 1.5` | Settles in [0.5, 5.0] for healthy training; outside = degenerate distribution |
**Phase 4 smoke gate** (Plan Phase 4): the L40S 5-epoch smoke checks
- `a_var > 0.01` per branch throughout (regression detector)
- `v_share ∈ [0.3, 0.7]` per branch (balanced dueling)
- `clip ∈ [0.5, 5.0]` (magnitude scale healthy)
**Memory pearl**: `pearl_sp4_histogram_warp_tile_undercount.md` documents the test-data trap discovered in Phase 3.2's GPU oracle test for `advantage_clip_bound`. The kernel uses non-atomic per-warp tile binning per `feedback_no_atomicadd`; the documented "1/(256×32) loss" qualifies "for uniformly distributed signals". Lockstep-uniform synthetic test data violates that assumption and undercounts dramatically. Fix: add per-element jitter to test data. Real `|A_centered|` in production is continuous so the issue is test-only.
**Phase 3 commit chain** (atomic per Phase per `feedback_no_partial_refactor`):
| Commit | Phase | Producer | LOC | Tests |
|---|---|---|---|---|
| `1e70cd5e5` | 3.1 | A_var_ema (4 branches) | +649 | 1 GPU oracle (Var matches closed-form) |
| `b6b17d46b` | 3.2 | V_share + advantage_clip_bound | +1208 | 2 GPU oracles (V_share closed-form, p99 × safety) |
All 13 SP17 GPU oracle tests pass on RTX 3050 Ti in 2.4s.
**Atomicity envelope**: Phase 3 is observability-only. NO consumer path is modified — no kernel reads V_share, a_var, or clip_bound to alter behaviour. The clip bound is producer-tracked but NOT yet wired as an actual clip on any kernel; that's Phase 5 follow-up. The Phase 1 mean-zero contract (commits `eabcf8d52` through `6f53d676f`) is what makes `A_centered` a meaningful signal; this Phase observes it.
**Plan**: `docs/superpowers/plans/2026-05-08-sp17-dueling-q-network.md` Phase 3.
## 2026-05-08 — SP17 Phase 3.2: V_share + advantage_clip_bound producers (additive observability)
Phase 3.2 lands the remaining two SP17 dueling-Q diagnostic producers atomically with kernel + launcher + Rust wrapper + extended HEALTH_DIAG emit + GPU oracle tests per `feedback_wire_everything_up`.