TODO.md

@@ -12,7 +12,7 @@
   Damage/death-save UI already gated on HP=0 so row buttons stay usable.
 - Affects: `shared/turn.js` `nextTurn` (filters `isActive`), `applyHpChange`
   (sets isActive=false on death), `computeTurnOrderAfterRemoval`.
-- Characterization tests (`Combat.characterization.test.js`) lock CURRENT
+- Characterization tests (`src/tests/Combat.characterization.test.js`) lock CURRENT
   (buggy) behavior — those tests must be UPDATED to desired behavior, not
   preserved. Red desired-test first, then fix.
 
@@ -25,18 +25,22 @@
 ## Confirmed bugs (tests written, NOT fixed)
 
 ### BUG-1: addParticipant + pause/resume corrupts turn rotation
-- Audit: 32/100 rounds violate rotation when `addParticipant` + other state
+- Audit: 128 violations / 100 rounds, 4 symptom faces.
-  changes fire while paused.
+- Symptom chain (one bug family):
+  1. pause blocks nextTurn advance → totalTurns stays frozen (e.g. 120)
+  2. addParticipant re-adds same `r${totalTurns}` id (BUG-2: no dedup)
+  3. togglePause resume rebuilds turnOrderIds → dup id appears x2
+  4. nextTurn gets stuck on dup id → rotation breaks
+  5. eventually nextTurn throws 'Encounter not running'
+- Symptom counts (audit-state.js, 100 rounds):
+  62x turnOrder-no-dup, 52x rotation-dupes, 14x nextTurn-throws
 - Repro in replay round 10+: current stuck on one participant forever,
   nextTurn returns same id, round never advances.
-- Clean minimal repro (turn.pause-add.test.js) PASSES = combo needs more
+- Clean minimal repro (shared/tests/turn.pause-add.test.js) PASSES = combo
-  state than one add+pause. Audit is authoritative repro.
+  needs more state than single add+pause. Audit authoritative repro.
-- Togglepause resume rebuilds turnOrderIds via sort but leaves
+- Clean subsystems (zero violations): HP bounds, isActive, deathSave
-  currentTurnParticipantId stale. After enough adds/toggles the stale
+  range, conditions, removeParticipant orphans.
-  pointer lands wrong → nextTurn repeats.
+- Real repro = `node scripts/audit-state.js` (or audit-rotation.js).
-- Test: `shared/turn.pause-add.test.js` (3 tests, all green currently —
-  document when bug DOES NOT trigger. Audit catches it.)
-- Real repro = run `scripts/audit-rotation.js` with all ops enabled.
 
 ### BUG-2: addParticipant allows duplicate id
 - `addParticipant(enc, dup)` appends same id to participants[] twice.
@@ -44,13 +48,14 @@
   nextTurn stuck repeating that id.
 - Reachable in normal app? App uses crypto.randomUUID (fresh ids) so
   unlikely. But no guard exists — defensive bug.
-- Test: `shared/turn.characterization.test.js` 'addParticipant rejects
+- Test: `shared/tests/turn.characterization.test.js` 'addParticipant rejects
-  duplicate id' — RED currently (validates current allow-dup behavior).
+  duplicate id' — test.skip currently (validates current allow-dup behavior).
 
 ## Pipeline
 - [ ] Red test: dead participant still in turnOrderIds, turn still advances to them
 - [ ] Fix `shared/turn.js`: don't drop dead from turn order
 - [ ] Update characterization tests to desired (not preserved) behavior
+  (src/tests/Combat.characterization.test.js, etc)
 - [ ] JUMP_TURN_TO red test
 - [ ] JUMP_TURN_TO impl (shared + UI button)
 - [ ] M5 docker-compose