# 11 — Fix priority plan (systematic waves)

> Execute in order unless the user explicitly reprioritizes.  
> Each wave lists **user outcome**, **work**, **depends on**, **proof**.  
> Checkboxes are for agents to update when a wave is done.

---

## Guiding principles

1. **User-visible done** > unit-green alone.
2. Fix **identity + auth** before chasing random WebRTC knobs — many voice/chat bugs are “never identified / wrong id.”
3. **Interview before implement** on each wave (repo rule) unless opted out / handoff already approved.
4. Stay in `toju-app` + targeted `electron`; ask once before `server/` or full `e2e/`.
5. Correct lying docs in the same change (`10`).

---

## Wave 0 — Shared baseline (half day)

- [ ] **0.1** Read `00-README.md`, `01`, `03`, `10`.
- [ ] **0.2** Build a **cross-home repro matrix** (manual or scripted):
  - Same home, same room
  - Different homes, room on home A
  - Different homes, room on foreign B (provision required)
  - DM + call between different homes
- [ ] **0.3** Enable WebRTC/signaling debug logs; capture home id, actor ids, peer keys, signal URLs on failure.
- [ ] **0.4** Confirm whether provision secret exists after fresh login vs after restart (Electron + browser).

**Proof:** Written repro notes attached to the next handoff (short).

---

## Wave 1 — Silent multi-signal auth (P0)

**User outcome:** Never bounced to authorize login just for touching another signal server.

- [ ] **1.1** Interview + implement provision-secret ensure on restore (see `04`, user story options A–D; recommend A).
- [ ] **1.2** Harden `auth_required` / `auth_error` home vs foreign handling (no false `SESSION_EXPIRED`).
- [ ] **1.3** Offline endpoints never navigate authorize (regression test).
- [ ] **1.4** Prove J4 + restart path (`02`).

**Depends on:** Wave 0.  
**Pack:** `04`, story `agents-docs/user-stories/silent-cross-signal-server-auth.md`.

---

## Wave 2 — Presence identify/join integrity (P0)

**User outcome:** When you open a room, others see you; you receive live chat/voice roster.

- [ ] **2.1** Verify `getIdentifyCredentialsForSignalUrl` store fallback on every reconnect path.
- [ ] **2.2** Ensure room connect always identify → join with **actor** id for `sourceUrl`.
- [ ] **2.3** Alias canonicalization / cold-start health wait still correct.
- [ ] **2.4** Prove two-client presence + live `chat_message` after signal restart.

**Depends on:** Wave 1 (foreign rooms).  
**Pack:** `05`, `08`.

---

## Wave 3 — Cross-signal outbound identity (P0)

**User outcome:** Calls ring the real person or show a clear error; DMs stay one thread.

- [ ] **3.1** Implement outbound routable recipient selection + unreachable UX (`09`, lesson L2).
- [ ] **3.2** Implement DM conversation canonicalize + merge (`09`, lesson L3).
- [ ] **3.3** Relabel/fix LESSONS so examples match shipped symbols.
- [ ] **3.4** Prove cross-home call + DM reply visibility.

**Depends on:** Wave 1. Can parallelize lightly with Wave 2 if staffing allows.  
**Pack:** `09`.

---

## Wave 4 — Voice negotiation & routing (P0)

**User outcome:** Bidirectional voice in shared channels, including cross-home users; reconnect either works or errors visibly.

- [ ] **4.1** Per-signal-url local actor id for initiator election + polite peer (`06` failure 1).
- [ ] **4.2** Voice allow-list includes all peer-map aliases.
- [ ] **4.3** After reconnect budget: user-visible failure + retry action.
- [ ] **4.4** Decide TURN product stance (document vs defaults).
- [ ] **4.5** Prove same-home + cross-home voice; takeover; blip recovery.

**Depends on:** Waves 1–2; benefits from 3.  
**Pack:** `06`.

---

## Wave 5 — Data channel recovery honesty (P0/P1)

**User outcome:** Control plane self-heals; chat history catch-up resumes; voice doesn’t mysteriously die without explanation.

- [ ] **5.1** Interview: soft replace (A) vs full rebuild + UX/resync (B) (`07`).
- [ ] **5.2** Implement choice; force inventory/resync on DC reopen.
- [ ] **5.3** Align `realtime/README.md` + `voice-webrtc.md` with code (`10` L1).
- [ ] **5.4** Prove DC force-close recovery + no silent abandon.

**Depends on:** Wave 4 preferred (so voice metrics make sense).  
**Pack:** `07`, `08`.

---

## Wave 6 — Messaging catch-up & attachments (P1)

**User outcome:** Late joiners get history; images/files don’t stick on “Waiting…”.

- [ ] **6.1** Verify/fix inventory trigger on peer + DC repair.
- [ ] **6.2** Re-verify attachment announce/bind re-queue invariants.
- [ ] **6.3** Fix chat README inventory cap (`10` L6).
- [ ] **6.4** Prove late-join history + image sync under reorder stress.

**Depends on:** Waves 2 + 5.  
**Pack:** `08`.

---

## Wave 7 — Doc & contract cleanup (P2, continuous)

- [ ] **7.1** Fix auth domain README paths (`10` L5).
- [ ] **7.2** Deprecate or fix `signaling-contracts.ts` warning banner.
- [ ] **7.3** Sync domain READMEs that oversimplify multi-credential auth.
- [ ] **7.4** Clear or refresh `agents-docs/HANDOFF.md` after each finished wave.

---

## Suggested staffing (multiple agents)

| Agent | Wave |
|-------|------|
| Auth agent | 1 |
| Realtime/signaling agent | 2, 5 |
| Identity/DM/call agent | 3 |
| Voice agent | 4 |
| Chat/attachments agent | 6 |
| Docs agent | 7 (or same PR as each fix) |

Do **not** start Wave 4 “TURN tuning” before Waves 1–3 — it wastes time on NAT while identity is wrong.

---

## Definition of “emergency over”

All of the following true on a two-signal-server manual matrix:

1. No spurious authorize/login while home session valid.
2. Presence mutual in shared rooms.
3. Bidirectional voice same-home and cross-home.
4. Live text + catch-up history.
5. Cross-home DM + call succeed or fail loudly.
6. DC/WS blip recovers or shows retry UI within ~1 minute.
7. Docs for recovery/identity match code (`10` critical lies cleared).