From 40fc4e596b2c58afcac08d3392c4560547e9f99b Mon Sep 17 00:00:00 2001
From: david raistrick <1108844+keen99@users.noreply.github.com>
Date: Mon, 29 Jun 2026 16:22:38 -0400
Subject: [PATCH] TODO: BUG-1 symptom chain (4 faces, 1 root cause), fix test
 paths

---
 TODO.md | 31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/TODO.md b/TODO.md
index db2dbe1..64d7e9a 100644
--- a/TODO.md
+++ b/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
-  changes fire while paused.
+- Audit: 128 violations / 100 rounds, 4 symptom faces.
+- 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
-  state than one add+pause. Audit is authoritative repro.
-- Togglepause resume rebuilds turnOrderIds via sort but leaves
-  currentTurnParticipantId stale. After enough adds/toggles the stale
-  pointer lands wrong → nextTurn repeats.
-- 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.
+- Clean minimal repro (shared/tests/turn.pause-add.test.js) PASSES = combo
+  needs more state than single add+pause. Audit authoritative repro.
+- Clean subsystems (zero violations): HP bounds, isActive, deathSave
+  range, conditions, removeParticipant orphans.
+- Real repro = `node scripts/audit-state.js` (or audit-rotation.js).
 
 ### 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
-  duplicate id' — RED currently (validates current allow-dup behavior).
+- Test: `shared/tests/turn.characterization.test.js` 'addParticipant rejects
+  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