spec: hunker

Epic: hunker · Status: exploring · Type: first tracer Graduation lineage: deliberate seed of the MUD-LLM-roguelike (agent-mud).

Fun-test (the one thing this proves)

"The world handed me a specific problem, I improvised a solution from the exact stuff on my screen, and it judged me fairly — it said no when it should have."

The tracer's soul is the adjudicator (open-input survival improvisation). The Director exists only to hand you interesting problems. If improvising against the valley feels alive and earned, the LLM-world bet is proven. If everything is rubber-stamped, or every clever idea gets a limp "you can't do that," it dies cheaply — which is the win.

What the LLM does that scripting can't

• Adjudicator (the star). You type freeform intent ("lash pine boughs over the north gap", "smoke the venison so it keeps"). The LLM checks feasibility against your actual resources and proposes an outcome + difficulty. A decision tree can't cover open input against specific world state.
• Director (delivery). Each dawn it reads full state + history and authors the day — weather, overnight changes, and what's coming — pacing threats and calling back on your neglect. Not a random table.

The honest engine / LLM split

Engine owns hard truth (this is what stops "yes-and to everything"):

• Meters: Health, Hunger, Warmth, Home integrity.
• Resources as integers: wood, food, water, stone/ore.
• Tile grid, movement, action points, breach points, death conditions.
• All dice. The engine rolls; the LLM never does.

LLM contract: player_text + state_json → { narration, proposed_deltas, difficulty }. The engine validates each delta against rules + resources, rolls where difficulty applies, and applies only what's legal. The LLM never mutates state directly. (Same contract for Director dawn output: { weather, environment_deltas, framing_narration, threat_plan }.)

The world

Two connected maps (the smallest honest version of "rooms" for the MUD lineage).

Exterior — the valley (~20×14, boxed by mountain + forest; no teleport)

Zones give traversal meaning against limited daylight:

• Home (center, multi-tile, own integrity stat).
• Farm plots near home (harvest wild in slice 1; planted stages later).
• Woods (wood), ore/rock outcrop at the mountain base (forge feedstock).
• Stream + fishing spot (water/fish), berry bush (food).
• Tree line — where sieges emerge. Pass — where cold rolls in.

Interior — the home (~8×7, cozy, move around)

Breach points: door + 2 windows, each with integrity. On siege nights threats cross the valley, attack the weakest breach, and if it breaks they're inside — you fight on the interior tiles you spent the day making cozy. Everything that saves you is something you improvised earlier.

Stations (LLM adjudication surfaces)

Station	Loop	Slice
Hearth 🔥	cook / preserve / boil	slice 1
Forge 🔨	smelt, craft, repair, build defenses	slice 1
Bed 🛏	sleep to pass night / recover (can't defend asleep)	slice 1
Storage 📦	inventory (engine truth)	slice 1
Research desk 📚	study, brew, ward the home (magic defense)	slice 2

Day loop (four beats)

1. Dawn — Director speaks. Authors weather, overnight changes, omens/threats.
2. Day — you act (limited action points). Move the grid, gather, tend, and improvise freeform actions adjudicated against real stock. Daylight = AP; crossing the valley costs real time, so route planning is the roguelike scarcity.
3. Dusk — resolution. Quiet night, or storm/siege. Prep resolves against hard stats; you may retreat inside and bar the door.
4. Overnight — the world ticks. Hunger rises, warmth burns wood, crops advance, snow accumulates. Loop.

Locked decisions (from interrogation)

• Input: hybrid. Tap to move and gather known nodes (engine verbs, no LLM); type freeform only for improvised/creative actions (LLM adjudicates). Keeps the LLM where the fun-test lives and keeps routine play fast + cheap on a phone.
• Siege: abstract. Breaches/traps/wards vs threat strength, resolved with a few adjudicated improvised interventions — no tile-by-tile monster combat. Threat archetypes for the tracer: frost-wolves (target the weakest breach) and a blizzard (drains warmth, blocks tiles).
• Models: multi-provider, per-role. LLM access goes through a provider abstraction (fake / Anthropic / Ollama) with a launcher UI to pick and assign models per role. Default: Haiku for all roles (fast + cheap); switch a role to Sonnet in the picker for an expensive/high-quality run. See ../adr/model-providers.md. This env has no API key, so all LLM behavior is built + tested against the fake adapter; real adapters are verified on the dev machine.
• Movement/AP: free within a zone, 1 AP to cross into a new zone; ~5 AP/day (tunable). Route planning is the roguelike scarcity.

Game shape

Finite goal: survive until the thaw (~7–10 in-game days ≈ one short real session). Completable, so the fun-test has a clean start and end. (Endless days-survived score is a later option, not the tracer.)

Milestones & slices

Named by ELI5 tag; no numeric ordering. Build order below is the dependency spine, not a fixed sequence — independent slices in a wave can launch agentically. One slice = one PR (or one commit within the milestone PR).

Milestone first-thaw — the first playable run

Definition of done: a full run you can survive to the thaw on your phone — go out, gather, improvise a defense, get sieged, and either die or reach the thaw — enough to judge the fun-test.

Wave 1 — foundation

• switchboard — shared web launcher + prototype switch selector + the content- manifest seam + thin server, phone-reachable over Tailscale; registers hunker. Includes a seedable RNG and a fake-LLM harness so everything after is testable.

Wave 2 — world skeleton (no LLM)

• the-grid — valley as a CSS grid of tile divs from engine state; move your avatar; day/night tint.
• four-walls — cozy home interior as a second map; door transition in/out; door + 2 windows as breach points with integrity.
• day-clock — dawn→day→dusk→overnight cycle; meters + resources tick; death conditions; scripted placeholder weather.

Wave 3 — the soul (LLM)

• try-anything — the adjudicator: freeform input → {narration, deltas, difficulty} → engine validates against real stock, rolls, applies.
• hearth-and-forge — hearth (cook/preserve) and forge (smelt/craft/repair/ build-defense) as adjudication surfaces.

Wave 4 — the world pushes back

• dawn-teller — the Director authors each day's weather/changes/omens/threat plan from full state + history.
• night-siege — threats cross the valley, hit the weakest breach, break in, interior fight, resolved against the defenses you improvised earlier.

Wave 5 — close the loop

• till-the-thaw — win/lose framing (survive N days), run-end screen, tuning, and the fun-test playtest pass → log the lesson (fun-proven / not-fun-shelved). The playtest + fun judgment is a human step.

Includes the thumb-feel pass — the game is judged on a phone, so the fun-test playtest must not be lost to friction. Checklist (phone Safari over Tailscale, one-handed):

• [ ] Tap targets (tiles, buttons) comfortably hit with a thumb — no misses on adjacent tiles.
• [ ] No pinch-zoom or horizontal scroll anywhere; page fits the viewport.
• [ ] The text input stays visible above the software keyboard while typing.
• [ ] Something visibly pends while the adjudicator/Director thinks — no dead air after Send.
• [ ] The newest log line is always in view without hunting; log readable at arm's length.
• [ ] Primary actions (text input, Send, Rest) live in the bottom half of the screen — one-thumb reach.
• [ ] A full run start-to-thaw played one-handed without wanting a desk.

Milestone green-again — past the tracer (backlog, only if fun-proven)

research desk / magic wards, planted-crop stages, more threat archetypes, more stations. Same engine + manifest; no new architecture.

Out of scope (guard against creep)

Multiple regions / teleport (that's the production game), procedural world gen, multiplayer, art, progression/meta. If it isn't needed to feel the fun-test, it waits.

Open questions

• Exact daylight-AP budget and valley crossing cost (tune for route tension).
• Whether magic-research (research desk) pulls forward into slice 1 — held to slice 2 by default to keep the first fun-test clean.