gogobee/gogobee_revisit_plan.md

# Revisit / Backtrack Navigation — Design Plan

Lets players walk back to previously visited rooms within an active zone
run to re-harvest, re-fork (e.g. after acquiring a key), or pick up
something they skipped. Forward-only navigation has been the rule since
Phase G; this plan retires that assumption deliberately.

## Goals

- Re-harvest depleted nodes after a long rest (primary use case).
- Allow general exploration freedom — wander back, look around.
- Re-pick a fork after acquiring a key or changing strategy.
- Preserve the existing pacing pressure (threat clock, SU drain) but
  make backtracking *cheaper* than fresh exploration to reflect that
  the route is already known.

## Non-goals

- Teleporting to arbitrary discovered rooms.
- Backtracking during `!expedition run` autopilot (autopilot is
  forward-only by design).
- Re-fighting cleared encounters or re-arming disarmed traps.

## Player-facing surface

- **`!revisit <N>`** — walks one edge from the current node toward a
  previously-visited node. `N` is the 1-indexed room number printed in
  `!map`'s Path strip.
  - Must be in `VisitedNodes`.
  - Must be adjacent to `CurrentNode` via an edge in the zone graph
    (forward or reverse direction; graph edges are directed but we
    allow reverse traversal for revisit).
  - Costs threat and SU at a reduced rate (see Cost Model).
  - No combat re-roll, no trap re-arm in cleared rooms.

- **`!map`** — already shows the numbered Path strip; players read N
  from there.

- **`!zone advance`** post-revisit — unchanged. From any node, picks
  the first outgoing edge (or shows the fork prompt). Re-forking a
  previously-resolved fork node clears the prior choice silently.

## Cost model

> **CORRECTED 2026-07-09 during R1.** The table below originally claimed a
> fresh `!zone advance` costs +2 threat / −1.0 SU. It does not. Verified at
> HEAD: **movement itself is free.** There is no per-room tick anywhere.
> - **Supplies burn per *day*,** not per room — `applyDailyBurn` is called
>   only from `dnd_expedition_cycle.go:108` (the day rollover),
>   `dnd_expedition_extract.go:52`, and region transit. Never from advance.
> - **Threat comes from *combat*,** not from walking:
>   `applyRoomCombatThreatForUser` (+5 normal, +8 elite/boss) fires from the
>   three combat-resolution sites, plus daily drift, harvest noise (+2), and
>   ambient. `zoneCmdAdvance` / `advanceOnce` touch neither clock.
>
> This inverts R2's central premise. A revisited room fires no combat
> (terminal `CombatSession` rows gate re-entry), so backtracking is already
> free — the design problem is not *discounting* a cost, it's that there is
> **no pacing pressure to discount**. Whatever R2 charges is a net-new cost.

| Move | Threat tick | SU tick |
|------|-------------|---------|
| Fresh-room `!zone advance` | **0** (actual) | **0** (actual) |
| Combat resolved in a room | +5, +8 elite/boss | 0 |
| Day rollover | drift (mood-scaled) | −daily burn |
| `!revisit <N>` (one edge) | **TBD — see below** | n/a (no per-move SU exists) |

**DECIDED 2026-07-09 — option (1), +1 threat per revisit edge.** Shipped in
R2 as `revisitThreatCost`. Standalone (non-expedition) zone runs have no
threat clock and so pay nothing. A `revisitSiegeGuard` refuses the move at
threat ≥ 99: siege is one-way sticky, and a player must not be able to strand
their own expedition on a move they made to go pick up a herb.

Options as they were weighed, cheapest first:
1. **Charge +1 threat per revisit edge.** One `applyThreatDelta` call,
   mirrors "harvest noise". Reads as "you stir up attention doubling back."
   Cheap, honest, and it's the only clock revisit can plausibly touch.
2. **Charge nothing.** Backtracking is already free of combat; the real
   cost is the day clock, which a long detour burns anyway. Simplest, and
   arguably correct — the pacing pressure is the multi-day supply budget,
   not the step count.
3. **Charge a fractional day.** Rejected: the day counter is the spine of
   every milestone, digest and anchored event. Don't make it fractional.

Recommend **(1)** at +1: it's the smallest lever that makes a detour a real
choice, and it rides an existing, tested seam.

## State model

The hard problem: `CurrentRoom` is currently derived as
`len(VisitedNodes)-1` (dnd_zone_run.go:377), which assumes
monotonically-growing visit history. Backtracking breaks that.

### Schema changes

- **`VisitedNodes`** — unchanged semantics: ordered set of nodes ever
  entered, first-entry order. Stays append-only when entering a *new*
  node; revisits do not append.
- **`CurrentNode`** — already the source-of-truth for "where am I."
- **`CurrentRoom`** — repurpose from `len(VisitedNodes)-1` to "index of
  CurrentNode within VisitedNodes" (the room's first-entry index, which
  is the path-relative label the player sees).
- **`RoomsTraversed`** (NEW, int column on `dnd_zone_run`) — monotonic
  step counter. Drives threat/SU ticks. Bootstrapped to
  `len(VisitedNodes)` for existing rows.

### Audit pass required

Every read of `r.CurrentRoom` and `len(r.VisitedNodes)` needs to be
classified:

- **"Path index" reads (keep as CurrentRoom)**: display headers
  ("Room 3/7"), encounter ID derivation (`encounterIDForRoom`), enemy
  salt seeds, harvest room keys, status/abandon strings, camp room
  index.
- **"Progress counter" reads (switch to RoomsTraversed)**: threat
  clock ticks, supplies ticks, ambient narration cadence, autopilot
  preflight, fatigue/exhaustion accrual if any.

Concrete callsite list will be produced during implementation; estimate
~10–15 callsites total.

## Fork re-pick

Re-entering a fork node clears its resolved choice in `node_choices`
(or equivalent). Next `!zone advance` shows the fork prompt fresh,
evaluated against current inventory (so a newly-acquired key unlocks
previously-locked edges).

Silent — no warning. Graph-back navigation means the player has
walked back through their previously-chosen path; nothing in
`VisitedNodes` is destroyed; the alternate branch they previously
took is still revisitable. There is no "discard" semantics.

## RoomsCleared semantics

Idempotent — exiting a room a second time doesn't re-append to
`RoomsCleared`. The "advanced past" flag is sticky.

## Preflight checks (rejections)

`!revisit` rejects with a clear DM when:

- Target room is not in `VisitedNodes` ("You haven't been there yet.")
- Target equals `CurrentNode` (no-op)
- Target is not adjacent to `CurrentNode` via any graph edge
  ("Room X isn't directly connected — backtrack one step at a time.")
- Active combat session in current room
  ("Finish the fight first.")
- Threat clock would tick past max (use existing camp-eligibility
  preflight pattern)
- SU would drop below survival floor (same)
- Character is dead / expedition is paused (same gates as `!zone advance`)
- Autopilot run is active

## Rollout phases

Tentative ordering. Each phase ships independently.

### R1 — schema + audit ✅ **DONE 2026-07-09** (branch `n1-restoration`)

Shipped: `rooms_traversed` column + `bootstrapRoomsTraversed` backfill;
`CurrentRoom` re-derived via `pathIndexOf(VisitedNodes, CurrentNode)`;
`appendVisited` / `appendClearedRoom` made set-semantic; `narrationCadence`
routed off `RoomsTraversed`; `advanceZoneRunNode` now returns the moved-to
path index. Tests in `zone_revisit_r1_test.go`. Full suite green. No
player-visible behavior change.

**Audit outcome — the callsite split was smaller than estimated (~10–15).**
Almost every `CurrentRoom` read is a *path index* and correctly stays put:
enemy/trap salts (`pickZoneEnemy`, `pickZoneTrap`, `rollTrapDamage`), loot
RNG seed, `encounterIDForRoom`, harvest room keys, camp `RoomIndex`, map
render, "Room X/Y" headers. Keying those on the node's first-entry index is
exactly what makes a revisited room resolve to *the same room*.

Only two reads were progress-shaped:
- `narrationCadence` → now `RoomsTraversed-1`, so a backtracking player
  draws fresh flavor instead of replaying the lines they read on the way in.
- `nextIdx := run.CurrentRoom + 1` (`dnd_zone_cmd_graph.go`) — not a
  progress read but a latent bug: "+1" only labels correctly while the
  player is at the frontier. `advanceZoneRunNode` now returns the true index.

**Nothing to route off `RoomsTraversed` for threat/SU** — there are no
per-room ticks to route (see the corrected Cost model above). The counter
currently drives narration cadence and stands ready for R2's cost decision.

Two behaviors were hardened in passing, both no-ops under forward-only
navigation but load-bearing the moment R2 lands:
- `VisitedNodes` is an ordered **set** — a re-entered node is not
  re-appended, so room numbers never renumber under the player.
- `RoomsCleared` is **idempotent** — exiting a room twice can't inflate it
  past `TotalRooms` and skew the "N/M rooms" renders.

### R2 — `!revisit` command ✅ **DONE 2026-07-09** (branch `n1-restoration`)

Shipped: `!revisit <N>` (alias `!zone revisit`), `adjacentNodes` reverse-edge
traversal, full preflight, +1 threat, `!map` now prints a **Back to:** strip
of legal targets. Fork re-pick still deferred to R3 — revisit refuses while a
fork prompt is pending, because both `!zone advance` and `!zone go` resolve
`node_choices` without checking which node the player is standing on.

**"No combat/trap re-trigger logic needed" was wrong — and it was an exploit.**
Terminal `CombatSession` rows gate *only* Elite and Boss rooms, at the doorway
check in `advanceOnceWithOpts`. An Exploration room re-enters
`resolveCombatRoom` unconditionally and a Trap room re-arms. Left alone,
`!revisit` would have been an infinite farm: step back one room, `!zone
advance`, repeat for loot and XP. Fixed with a `RoomIsCleared(CurrentRoom)`
early-return at the top of `resolveRoom` — a no-op forward-only, since advance
clears a room only *after* resolving it. Guarded by
`TestRevisitedRoom_DoesNotReResolve` and `TestFreshRoom_StillResolves`.

**Autopilot needed a stopgap, sooner than R5 planned.** Autopilot has no
on/off switch — `tryAutoRun` is ticker-driven for every active expedition on a
2h CAS cooldown. Without intervention the background walker marches the player
straight back out of the room they just revisited, and the whole feature reads
as broken. `grantAutorunGrace` stamps `last_autorun_at` on revisit, buying one
full cooldown window. **R5 still owes the real policy decision** (refuse to
auto-walk from a non-frontier node, vs. walk back to the frontier first).

Tests in `zone_revisit_r2_test.go`. Full suite green.

### R3 — fork re-pick

- On revisit landing into a fork node, clear `node_choices` for that
  node.
- Next advance re-prompts.
- Tests: lock-with-key acquired between two fork visits, alternate
  branch selection, no-change re-pick.

### R4 — UX polish

- DM line on revisit explaining the cost ("You retrace your steps to
  Room 3 (the fork). Threat +1, SU −0.5.").
- Surface `!revisit` in `!help` and `!zone` help blocks.
- Ambient/narration audit: any "you press deeper into the dungeon"
  lines that no longer fit when player is backtracking.

### R5 — autopilot guard

- `!expedition run` refuses to start while at a non-frontier node?
  Or auto-walks back to frontier first? Decide based on R1–R4 feel.
  Likely: refuse with a "use !zone advance to return to the frontier
  first" hint.

## Open questions (lower priority)

- Should there be a small flavor-only narrative beat the first time
  the player backtracks in an expedition? ("TwinBee notes you doubling
  back — there's no shame in it. Sometimes the answer was in a room
  you'd already passed.")
- Does a babysitter's safe-rest affect revisit cost? (Probably not —
  babysitter is a camp upgrade, revisit is movement.)
- Multi-region expeditions — does revisit work across region
  boundaries within the same expedition? (Initial answer: no, only
  within the current zone run; cross-region travel is its own seam.)

## Effort estimate

Comparable to a small Phase pass (G6-sized). Roughly:

- R1: 1 session (schema bump + audit + tests).
- R2: 1 session.
- R3: 0.5 session.
- R4: 0.5 session.
- R5: 0.5 session.

Total: ~3–4 working sessions.