gogobee/gogobee_expedition_difficulty.md

# Expedition Difficulty Tuning Pass

Started 2026-05-15, after the Phase D audit close-out. Sibling to the
class-balance pass (`gogobee_class_balance.md`) — same Monte-Carlo
philosophy, different target metric.

**Class balance answers** "is my class viable?" (parity between classes
vs. the same monster tier).
**This pass answers** "is the dungeon fair?" (does a tier-appropriate
character complete a tier-N expedition at the expected rate?).

Same combat engine (`simulateCombatWithRNG`), orthogonal knobs.

---

## Method

**Sim harness, not telemetry-first.** A new
`internal/plugin/dnd_expedition_balance.go` will run thousands of
seeded expeditions through the real autopilot / threat / encounter /
combat code and report:

- completion %
- death %
- median days-to-extract
- median threat at extract
- supply curve (% expeditions that hit Rationing / Severe / Starvation)
- combat-encounter count per run
- coin/XP earned

The harness produces these per (zone, player-level) cell; the
regression test asserts the per-tier completion band.

**Tier target band** (steered by [[feedback_difficulty_target]]
"relatively easy but not too easy", and reflecting that expeditions are
multi-day commitments players plan around — losing one should sting but
not feel arbitrary):

| Tier | Target completion % | Acceptable band |
|------|--------------------:|-----------------|
| T1   | 80%                 | 70–90%          |
| T2   | 72%                 | 62–82%          |
| T3   | 65%                 | 55–75%          |
| T4   | 55%                 | 45–65%          |
| T5   | 45%                 | 35–55%          |

Bands are ±10pp around the centerline. Sim is asserted against the band,
not the centerline (no overfit). Player-level for each cell = "tier
appropriate" per the class-balance kit ladder: T1 → L1-4, T2 → L3-7,
T3 → L5-10, T4 → L7-15, T5 → L10-20 (median level per tier).

**Out of scope:**

- Per-encounter combat parity (covered by `gogobee_class_balance.md`).
- Arena difficulty (separate system, separate balance).
- Live telemetry tables — deferred; sim is the primary truth source for
  this pass. We can add counters later if the sim diverges from
  observed live numbers.

---

## Phases

Each phase ≈ 1 session, ships green + committed.

### Phase 0 — sim harness spike

Build the minimum harness:

- New file `internal/plugin/dnd_expedition_balance.go` exposing
  `simulateExpeditionWithRNG(profile, seed)` → result struct.
- **Critical de-risk: replay the autopilot deterministically.** The
  ticker is wall-clock driven (`dnd_expedition_cycle.go:38,56` at
  06:00 / 21:00 UTC; `expedition_ambient.go:22` every 3h). Harness
  must inject a virtual clock or call the per-phase advance functions
  directly (`deliverBriefing`, `deliverRecap`, ambient nudge, harvest
  autopilot) in tight loop, bypassing the goroutine ticker. **Settle
  the clock-injection seam in Phase 0** — if this is messy, the whole
  pass collapses.
- DB-touching layers stubbed/in-memory (same trick as class-balance
  Phase 0).
- Sanity test: one cell — e.g. T2 zone at L5 Fighter — runs to
  completion or death deterministically, returns sensible numbers,
  100 trials in <10s.

**Exit:** `TestExpeditionBalance_Phase0_Spike` green; commit.

### Phase 1 — full matrix measurement

- Build the cell list: every zone × tier-appropriate-level. Per the
  exploration map, expeditions span zones tagged T1–T5; we measure
  every zone at its centerline level.
- 200 trials/cell (same density as class-balance Phase 1).
- Matrix log: per-cell completion%, death%, median days, median
  extract-threat, supply-curve histogram.
- Per-tier mean + spread diagnostic across zones (analogue of the
  class-balance per-(level,tier) spread diagnostic).
- `TestClassBalance_Phase1_FullMatrix`-style permanent test, but only
  gating on harness-broken pathologies for now (0% completion anywhere
  at T1, 100% completion at T5).

**Exit:** matrix numbers logged; commit with "Phase 1 baseline" note.

### Phase 2b — wounded-entrant nick clamp (shipped)

`clampSurpriseNick(rawNick, hpCurrent, hpMax)` in
`dnd_expedition_combat.go`: at full HP the raw nick stands; when
wounded the nick is capped at `max(1, hpCurrent/5)` so a single nick
on a low-HP fighter can't shave more than ~20% of remaining HP. The
existing "nick can't KO" guard is preserved.

Motivation came from the post-2a tier-lethality trace
(`TestExpeditionBalance_Phase2_TierLethality`): every tier had a
fingerprint where an over-tier elite left the fighter at 25-50% HP +
retreat, then the next standard's surprise nick (3-7 HP, often
exceeding the fighter's headroom) pre-empted the combat engine
entirely. Capping the wounded-entrant nick separates that cascade
from genuine elite-one-shot deaths so Phase 2c can tune the elites
with a clean read.

Matrix delta vs Phase 2a baseline is small (median encs +0.1-0.2
per cell) — completion% still 0% across every tier — but the
tier-lethality trace stretched substantively: T1 trial 0 went 5 → 8
encs / 5 → 7 days; T3 trial 1 ran 18 → 10 encs but visibly survived
multiple chained interrupts at low HP that pre-2b would have ended
on the nick alone. The remaining deaths are now legible as elite
one-shot fights on fresh entries (Hobgoblin Warchief, Green Hag,
Roper, Young Red Dragon) — that's the Phase 2c roster signal.

**Tuning surface:** the `/5` divisor in `clampSurpriseNick` is the
wounded-fighter lethality knob.

### Phase 2 lever sweep (shipped) — negative result

Before adding Phase 2c, the two surfaced knobs (`retreatThreatBump`,
`clampSurpriseNick` divisor) got swept across a full 3×4 grid
(bump ∈ {2, 5, 10} × divisor ∈ {3, 5, 8, 12}) at 200 trials/cell
across every zone in the matrix. Wired via
`expeditionBalanceProfile.{RetreatThreatBumpOverride,
SurpriseNickDivisorOverride}` threaded into `expeditionHarness`;
the live caller (`runHarvestInterrupt`) is untouched.

Sweep file: `TestExpeditionBalance_Phase2_LeverSweep` in
`expedition_balance_test.go`. `-short` skips.

**Outcome:** every one of the 24,000 trial-cells reports 0.0%
completion / ~100% death. The two knobs are inert on the headline
metric — even the gentlest combo (b=2, d=12) cannot lift any tier
off the floor. Median days-to-end stays at 2–3 across the grid
with median 2.6–7.3 encounters before death.

**Read:** confirms the post-2b tier-lethality trace — deaths are
fresh-entry elite one-shots (Warchief @ HP19/20, Hag @ HP41, Roper,
Young Red Dragon), not chained-interrupt cascades. The two levers
target the cascade path that's now mostly resolved; they have no
remaining death-fraction to convert. Phase 2c (roster dilution) is
justified rather than premature.

### Phase 2c — roster gate (shipped)

Promoted one mid-tier alt to `IsElite: true` in every zone whose elite
pool was a single SpawnWeight=1 boss (`internal/plugin/dnd_zone.go`).
The boss stays in the pool; weighted dilution means the InterruptElite
bracket no longer auto-picks the over-tier boss. `pickZoneEnemy` also
excludes the promoted entry from the standard pool, lowering standard
encounter difficulty by removing one mid-difficulty option from
non-elite brackets (acceptable: each zone still has 3-4 standard
entries left). Crypt-Valdris was already dual-elite (wight + flameskull)
and was left alone.

| zone               | promoted alt          | boss (untouched)   |
|--------------------|-----------------------|--------------------|
| goblin_warrens     | worg (SW=3)           | hobgoblin_warchief |
| forest_shadows     | owlbear (SW=4)        | green_hag          |
| sunken_temple      | aboleth_thrall (SW=3) | water_elemental    |
| manor_blackspire   | vampire_spawn (SW=3)  | revenant           |
| underforge         | salamander (SW=3) + fire_elemental (SW=3) | helmed_horror |
| underdark          | drow_elite_warrior (SW=4) | roper          |
| feywild_crossing   | night_hag (SW=3)      | fomorian           |
| dragons_lair       | dragonborn_cultist (SW=3) | young_red_dragon |
| abyss_portal       | hezrou (SW=4)         | marilith           |

**Phase 1 matrix delta (200 trials/cell, Fighter, tier centerline):**
goblin_warrens 0% → **3.0%** completion (first non-zero T1 reading
since Phase 0); sunken_temple 0% → 0.5%; dragons_lair death% **100% →
60%** with 40% now starve (fighter survives the elite-spawn path long
enough to run out of supplies — different failure mode); underdark
death% 100% → 90% (10% starve); feywild_crossing 100% → 92% death
(8% starve). T3 manor_blackspire / underforge still 100% death — the
remaining death pressure there is the post-2b chained-standard path,
not the elite roll.

Tier-lethality trace cross-check (`Phase2_TierLethality`) shows the
new alt-elites actually spawning and being winnable: underdark trial
1 now opens with `Drow Elite Warrior` (won), reaches the Roper at
turn 6, retreats, then dies on a Hook Horror nick — a substantively
longer arc than the pre-2c fresh-entry Roper one-shot. Dragons_lair
trials similarly show `Dragonborn Cultist` as a winnable elite stop
before the dragon roll lands.

Stat-block tuning of the bosses themselves is off-limits per the
Phase 3 constraint (bestiary is shared across systems).

### Phase 3 — global lever tuning

Tune the knobs that affect every zone uniformly:

- **Daily threat drift** (`dnd_expedition_threat.go:87` — base +3/day).
- **Threat band thresholds** (Quiet/Stirring/Alert/Hostile/Siege —
  `dnd_expedition_threat.go:70-82`).
- **Supply burn multipliers** (`dnd_expedition_supplies.go:43-56` —
  T1×1 → T5×3).
- **Surprise-round damage floor** (`dnd_expedition_combat.go:184`).
- **Encounter bracket thresholds** (`dnd_expedition_combat.go:39-44`
  None/Noise/Standard/Elite/Patrol).
- **Camp mods** (`dnd_expedition_night.go:85-92`).

Goal: every tier centerline lands within ±5pp of target. Bands stay
±10pp.

#### Phase 3-A — elite-bracket + drift sweep (shipped)

Wired two harness overrides
(`EliteInterruptThresholdOverride`, `ThreatDriftBaseOverride`) and
swept a 3×3 grid (elite ∈ {17, 19, 23} × drift ∈ {1, 3, 5}) over
the Phase 1 matrix. Test: `TestExpeditionBalance_Phase3_GlobalLeverSweep`.

**Strong partial positive.** The elite-bracket threshold is the
dominant lever for T1–T3; threat drift is a small modulator on top.

| (elite, drift) | T1 mean | T2 mean | T3 mean | T4 mean | T5 mean |
|----------------|--------:|--------:|--------:|--------:|--------:|
| 17, 1 (more elites) | 0.5% | 0.0% | 0.0% | 0.0% | 0.0% |
| 19, 3 (live)        | 3.0% | 0.2% | 0.0% | 0.0% | 0.0% |
| 23, 1 (rare elites) | **24.0%** | **7.2%** | **1.8%** | 0.0% | 0.0% |
| 23, 3               | 16.5% | 4.0% | 2.0% | 0.0% | 0.0% |
| 23, 5               | 11.8% | 3.2% | 0.2% | 0.0% | 0.0% |

Best cell at e=23/d=1: goblin_warrens 40.5%, sunken_temple 14.5%.
Still well below the T1 70-90% / T2 62-82% target bands — the lever
moves the needle in the right direction but cannot land any tier
on-band alone.

**T4/T5 fingerprint changed but didn't lift.** At e=23 the dragons_lair
death-fraction drops from ~60% → 24% but starvation climbs to 75% —
the fighter now survives elites long enough to run out of supplies.
T4 (underdark/feywild) likewise sees death drop and starvation rise.
Indicates a second lever is needed for the higher tiers: either
standard-fight survivability (surprise-nick floor / standard roster
density) or supply margin.

**Next:** Phase 3-B sweeps surprise-round nick and supply-burn knobs
on top of e=23/d=1 to push T1-T3 toward target band and lift T4-T5
off the floor.

#### Phase 3-B — nick-floor + supply-burn sweep (shipped)

Wired two more harness overrides (`SurpriseNickFloorOverride`,
`SupplyBurnRatePctOverride`) and swept a 3×3 grid (floor ∈ {0, 1, tier
(=live)} × burn% ∈ {50, 75, 100 (=live)}) on top of the Phase 3-A best
cell (e=23, d=1). Test: `TestExpeditionBalance_Phase3B_NickSupplySweep`.

**Strong partial positive for T5 supply margin; nick-floor lever inert.**

Tier-mean completion (Fighter, centerline level, 10 zones × 200 trials):

| (floor, burn%) | T1 mean | T2  | T3  | T4   | T5   |
|----------------|--------:|----:|----:|-----:|-----:|
| 0,    50       | 20.8%   | 5.0%| 3.8%| 7.5% | 29.5%|
| 0,    75       | 26.5%   | 6.0%| 2.8%| 9.0% | 0.0% |
| 0,   100       | 25.8%   | 5.0%| 3.0%| 0.0% | 0.0% |
| 1,    50       | 25.5%   | 6.5%| 1.8%| 8.5% | 27.8%|
| 1,    75       | 28.5%   | 6.2%| 4.0%|11.5% | 0.0% |
| 1,   100       | 26.8%   | 7.5%| 2.5%| 0.0% | 0.0% |
| tier, 50       | 26.8%   | 6.2%| 2.5%| 7.8% | 27.5%|
| tier, 75 (live floor) | **29.5%** | **7.8%** | 3.0% | **12.8%** | 0.0% |
| tier,100 (live)| 28.5%   | 6.8%| 3.0%| 0.0% | 0.0% |

Three readings:

1. **Supply burn is the T5 unlock.** dragons_lair completes ~55% at
   burn=50 (versus 0% at burn=75/100) — the fighter survives elites
   but starves en route. burn=75 isn't enough margin; burn=50
   converts the starvation-out into a completion.
2. **Supply burn is the T4 modulator.** underdark/feywild step from
   0% (burn=100) → 12% (burn=75) → 8% (burn=50). The burn=75 peak is
   the sweet spot; halving further leaves the fighter alive *into*
   more elite fights, where it dies in combat instead.
3. **Nick-floor lever is inert.** Across all burn levels, dropping
   the surprise-round floor from `tier` → `1` → `0` moves T1-T3
   means by at most ~3pp. The wounded-clamp (Phase 2b,
   `clampSurpriseNick`) already eats the chip-damage budget on
   repeat entries; the raw floor only matters on the first fresh-HP
   swing, which the engine recovers from. **Recommendation: discard
   this lever from the live-tuning candidate list.**

**T2-T3 wall persists.** Even at the best (floor=tier, burn=75) cell:
T2 reads 7.8% (target 62-82%) and T3 reads 3.0% (target 54-74%).
forest_shadows T2, manor_blackspire T3, and abyss_portal T5 sit at
~0% across every combo — these are zone-specific outliers, not
addressable by any global lever. **Phase 4 (per-zone outlier pass)
is the next move.**

**Next:** Phase 4 walks the matrix zone-by-zone. The shipped Phase 3
sweep already names the worst offenders (forest_shadows T2,
manor_blackspire T3, abyss_portal T5, crypt_valdris T1); each needs a
diagnostic trace (boss stat-block, roster mix, supply DC) to pick the
right per-zone tool from `Phase 4`'s list. Optional: revisit shipping
the burn=75 global if Phase 4 outlier fixes leave T4 still stuck.

### Phase 4 — per-zone outlier pass

After globals settle, the matrix names outlier zones — tiers where
one zone reads dramatically off-band while sibling zones are fine.
Per-zone tools:

- `SpawnWeight` / `IsElite` flags in zone rosters (`dnd_zone.go:100`).
- Boss stat tuning in zone definitions.
- Resource DCs (affects harvest interrupt roll).
- Per-zone loot table density (downstream economy impact — flag if
  significant).

Constraint: do not touch monster stat blocks (those belong to the
bestiary, shared across systems). Tune the roster + zone-level knobs,
not the monsters themselves.

#### Phase 4-A — outlier diagnostic (shipped)

Added a structured per-fight trace hook (`traceFightStruct` +
`harnessFightTrace`) alongside the existing string `traceFight`;
both fire from the same `runHarnessFight` site so the human log and
the structured aggregate stay in sync. Test:
`TestExpeditionBalance_Phase4A_OutlierDiagnostic`. For each of the
four outlier zones it pairs against the healthy sibling at the same
tier (goblin_warrens, sunken_temple, underforge, dragons_lair),
running 200 trials each on the Phase 3-B best cell (e=23, d=1,
burn=50) and reporting per-monster appearances / win-rate / avg HP
loss / kill attribution + day-of-end histogram.

Findings — each outlier had one or two miscategorised entries that
Phase 2c's single-boss-elite dilution sweep had skipped:

- **crypt_valdris**: dual-killer elite pool (Wight 99k, Flameskull
  68k); Phase 2c had skipped this zone as "already dual-elite," but
  both elites are over-tier for T1.
- **forest_shadows**: standard pool too lethal — Displacer Beast
  (38% win, 53k) + Bandit Captain (57% win, 48k).
- **manor_blackspire**: Wraith on standard slot (45hp loss per win,
  85k).
- **abyss_portal**: Nalfeshnee mis-classified standard (CR-13, 2.8%
  win, 86k) + Vrock standard at 43hp loss per win.

#### Phase 4-B — roster re-classification (shipped)

Per-zone roster tweaks based on Phase 4-A's attribution. No monster
stat-block touches.

- crypt_valdris: dropped flameskull (lives in underforge T3);
  promoted specter to IsElite SW=3 as the soft dilutor.
- forest_shadows: promoted Displacer Beast + Bandit Captain to
  IsElite; Owlbear SW 4→2 so the 4-elite pool dilutes evenly.
- manor_blackspire: promoted Wraith to IsElite (joins
  Spawn+Revenant).
- abyss_portal: promoted Nalfeshnee + Vrock to IsElite (collapses
  standard pool to Quasit alone, ≥99% win).

Outlier-vs-sibling completion (Phase 3-B best cell, 200 trials):

| Zone | Before | After | Sibling |
|------|-------:|------:|--------:|
| crypt_valdris T1   |  8.5% | **46.0%** | 45.0% |
| forest_shadows T2  |  0.0% |  **7.5%** | 13.0% |
| manor_blackspire T3|  0.5% | **14.5%** |  3.0% |
| abyss_portal T5    |  0.0% | **25.0%** | 57.5% |

Phase 3-B tier mean (b=50, f=tier) before → after:
  T1 26.8% → 44.0% (+17pp), T2 6.2% → 10.0% (+4),
  T3 2.5% →  8.5% (+6),  T4 unchanged, T5 27.5% → 41.0% (+14).

**Exit (partial):** the four off-band outliers are no longer
outliers — every per-zone cell is within the spread of its tier
siblings. The Phase 4 plan's stricter exit ("all per-zone cells
within target band") is **not** met: T2/T3/T5 sibling pairs still
sit below band (T2 7-13% vs 62-82%; T3 3-14% vs 54-74%; T5 25-57%
vs 36-56%). That gap is tier-wide, not zone-specific — both zones at
each problem tier underperform together — so no further per-zone
tool will close it. Phase 5 (or a follow-up tier-wide pass) needs to
take over.

**Next:** Phase 5. Candidate moves are tier-wide: revisit player
gear-tier mapping at T2/T3 (the centerline level vs gear ladder, see
`phase1TierCenterline`), reconsider the elite-bracket threshold
per-tier instead of global, or ship `burn=75` as the new live global
since Phase 4-B already converted T4 to playable at b=50.

### Phase 5 — optional MAD / second-order

If post-Phase-3 the bands hold but feel wrong subjectively
(e.g. "median days too short", "no expedition ever hits Siege"), add a
secondary assertion on median-days-to-extract or extract-threat. Phase
3 may also surface a request to expose a difficulty knob to operators
(env var or admin command); scope that here if it comes up.

---

## Open questions

- Should the babysit perk be on or off in the sim? Pick one and
  document; both as separate cells doubles matrix size for diminishing
  insight. Default proposed: **off**, since it's a discovery-mechanic
  buff ([[feedback_npc_buffs_are_secret]]) — players who find it earn
  extra margin, not the baseline.
- Pardon proc (33% @ chat 20+): include in sim, but at a fixed
  chat-level assumption (chat 15 = no pardon, since most fresh runs
  haven't hit the threshold). Decide in Phase 0.
- Sovereign reprieve: skip in sim — it's gated on full set equipped
  and is a one-shot per cooldown. End-game-only; not part of the
  baseline difficulty.
- Multi-region zones (E4): does the sim need to walk all regions in
  one expedition, or pick one region per run? Probably full walk for
  realism. Settle in Phase 0.
- DM mood: starts at 50; drifts via combat outcomes. Let it drift
  naturally in the sim, do not pin.

---

## Deliverables checklist

- [ ] `internal/plugin/dnd_expedition_balance.go` (sim harness)
- [ ] `TestExpeditionBalance_Phase0_Spike`
- [ ] `TestExpeditionBalance_Phase1_FullMatrix` (becomes the permanent
      regression gate after Phase 2 tightens it)
- [ ] Tuning commits per phase
- [ ] One-line update to `MEMORY.md` + project memory pointer