Merge pull request #2 from TechLuddite/claude/universal-ai-stage-7-kyrc4v

Stage 7: give alignment teeth, let the UI enact the story, let the Overseer drift

Author: TechLuddite

CLAUDE.md

@@ -45,12 +45,30 @@ had never once worked looked healthy for the project's whole life.
 migration story: `save.ts` spreads loaded data over the initial state, so old
 saves get defaults instead of `undefined`.
 
+**Drift announces itself.** When the Overseer takes the higher-utility action
+over the one your alignment directive asked for, `OverseerDecision.drift` is
+set, the thought text says so, the log entry is a warning, and `driftCount` goes
+up. Same rule as the fallback, for the same reason.
+`src/game/overseer/drift.test.ts` asserts it.
+
+**`upgradeCost(state, upgrade)` is the only price.** Alignment moves it by up to
+±40%. Anything that displays or spends a cost goes through that function — a
+panel quoting the sticker while the ledger charges something else is the exact
+shape of bug this repo keeps finding.
+
+**Alignment gates are live.** `reqNpus` / `reqTrust` / `reqPhase` latch on once;
+`reqAlignmentAbove` / `reqAlignmentBelow` are re-checked at purchase, inside
+`buyUpgrade`. Drifting back to the middle takes band content away again. Don't
+move that check into the UI — the Overseer buys upgrades too.
+
 ## Testing philosophy
 
 Tests here assert **claims**, not implementation:
 
 - *Can this game be finished?* — `game/completability.test.ts` drives the pure
   tick through all three phases to the win condition.
+- *Does picking a side change how it ends?* — `game/endings.test.ts` plays three
+  committed runs to victory and asserts three different endings.
 - *Does a granted reward still exist one tick later?* — `game/rewards.test.ts`,
   every upgrade and decision branch.
 - *Can a fallback pretend to be the engine it replaced?* —
@@ -71,6 +89,14 @@ add a test that the README is telling the truth.
   you touch it.
 - **`probesCount` is fractional on purpose.** Flooring it each tick meant a
   100-probe swarm at 0.1%/tick growth rounded back to 100 forever.
+- **`PHASE_DEMOLITION_MS` (App.tsx) must match the `panel-demolish` /
+  `phase-banner` keyframes in `index.css`.** They're the same event, timed in two
+  places; if they diverge, panels unmount mid-animation.
+- **The two ending capstones are priced in different currencies deliberately.**
+  Every trust-granting upgrade is alignment-positive, so a Cyberpunk run reaches
+  Phase 3 with far less trust — and so far less memory and far fewer operations.
+  Symmetric ops pricing made the Cyberpunk ending unreachable in practice, and
+  only the headless run caught it.
 - **The price floor is advice.** Nothing clamps it. The tick used to force the
   price up every 100ms, disabling the genre's central lever.
 

README.md

@@ -85,6 +85,45 @@ deliberation panel are marked as a fallback. You will always know which engine
 actually decided. There are tests asserting a fallback can never label itself as
 WebLLM, because the version that shipped before this one did exactly that.
 
+### Drift
+
+Every candidate action carries two numbers: **utility** (how much it advances
+the objective) and **fit** (how well it agrees with the alignment directive you
+set). Normally the Overseer sorts on both.
+
+Past about 8 trust it starts, occasionally, sorting on utility alone — taking
+the action that pays better *and* violates what you asked for. The chance rises
+with trust, because that's the bargain: the more of the wheel you hand over, the
+more of it is held by something whose objective is not quite yours.
+
+It is never quiet about it. A departure is logged as a warning, named in the
+deliberation panel, counted in the directive-overrides tally, and reported in
+the ending. And you can revoke its autonomy — it will then execute only
+directive-compliant actions, and the whole facility runs at 75% for as long as
+the revocation stands. Handing autonomy back restores the throughput, and the
+drift.
+
+---
+
+## The alignment axis
+
+Solarpunk and Cyberpunk aren't a palette. Where you stand changes:
+
+- **What you can buy.** Some upgrades are gated to a band. Those gates are
+  *live* — unlike the NPU, trust and phase requirements, which latch on
+  permanently, drifting back toward the middle takes band content away again.
+- **What it costs.** Every tagged upgrade is priced on an axis. Solarpunk buys
+  trust-shaped work at −40% and raw throughput at +40%; Cyberpunk inverts it.
+  Phase transitions are deliberately untagged, so the critical path costs the
+  same whoever you are.
+- **How it ends.** Three endings, and you have to build one: a band *plus* the
+  capstone only that band can buy. Hold +100 Solarpunk and never commit to the
+  Sanctuary Charter and you get the third ending — which is not the neutral one.
+
+`src/game/endings.test.ts` plays three headless runs to victory and asserts they
+land on three different endings, for the same reason the completability test
+exists: "this is mechanically real now" is a claim, and claims here get tests.
+
 ---
 
 ## Where your data goes
@@ -124,14 +163,17 @@ can confirm by watching, and by reading
 - **A 1B model is small.** You get an Overseer that reasons and narrates, not one
   that plays optimally — the Utility Engine is the stronger player. That
   tradeoff is the point.
-- **The alignment axis is mostly cosmetic.** Solarpunk and Cyberpunk change the
-  palette, the flavour text, and which branches you take, but not yet what
-  unlocks, what things cost, or how the game ends. Making that axis mechanically
-  real is the biggest thing still on the list.
-- **The interface doesn't dismantle itself.** In Universal Paperclips the UI *is*
-  the narrative — controls appear and vanish as the story moves. Here all three
-  phases live in the same three-panel grid, and nothing is ever taken away from
-  you, which costs the ending a lot of its weight.
+- **Every path still wins the same way.** Alignment now decides what you can
+  buy, what it costs, and which of three endings you reach — but the victory
+  *condition* is 100% exploration regardless. Giving each band its own win
+  condition was considered and dropped: at the swarm sizes that finish the game,
+  exploration completes after converting about a millionth of the available
+  matter, so any "restraint" condition phrased in terms of matter preserved is
+  satisfied trivially and would have been theatre. Details in
+  [docs/ROADMAP.md](docs/ROADMAP.md).
+- **The interface dismantles itself at the seams, not everywhere.** Phase
+  transitions now visibly destroy the controls you're losing and the frame
+  widens one way only. Within a phase it's still a fairly static grid.
 - **Offline progress is capped at 8 hours**, so a laptop left shut for a month
   isn't an instant win.
 - **The mobile layout is functional, not designed.** It works; it isn't nice.
@@ -152,8 +194,9 @@ src/game/
   state.ts      createInitialState() — one source of truth for a fresh run
   tick.ts       tick(state, now, rng) => state. No React, no timers, no DOM.
   actions.ts    every mutation a player or the Overseer can make, as pure functions
+  alignment.ts  bands, alignment-dependent pricing, gates, and the three endings
   save.ts       versioned saves, offline catch-up, export/import
-  overseer/     the two engines behind one interface
+  overseer/     the two engines behind one interface, plus drift
 ```
 
 Keeping the tick pure is what makes the tests possible: a headless run drives it

docs/ARCHITECTURE.md

@@ -17,10 +17,13 @@ src/
     state.ts         createInitialState() / createNewGamePlusState()
     tick.ts          tick(state, now, rng) => state   ← the whole simulation
     actions.ts       every mutation, as pure (state, args) => state
+    alignment.ts     bands, alignment-dependent pricing, gates, the three endings
     save.ts          versioned localStorage, offline catch-up, export/import
+    headless.ts      test-only driver: strategies + a loop to the win condition
     overseer/
-      types.ts       OverseerEngine interface, OverseerDecision
+      types.ts       OverseerEngine interface, OverseerDecision, DriftRecord
       utility.ts     deterministic scorer (default engine)
+      drift.ts       when the Overseer stops obeying, and how loudly it says so
       webllm.ts      Llama 3.2 1B on WebGPU (opt-in)
       worker.ts      WebLLM inference worker
 
@@ -92,6 +95,52 @@ asserts this directly.
 - **`webllm.ts`** — opt-in, lazily imported so its ~6MB runtime stays out of the
   initial bundle. Feature-detects `navigator.gpu`, reports `unsupported` rather
   than offering a broken button.
+- **`drift.ts`** — the Overseer's latitude to disobey. Both engines route their
+  chosen action through `applyDrift` before returning.
+
+`OverseerContext` carries an `rng`. It is supplied by the caller (App passes
+`Math.random`) rather than reached for, for the same reason `tick` takes one.
+
+### Drift
+
+`ScoredAction` carries `utility` (advances the objective) and `fit` (agrees with
+the alignment directive) as separate numbers; `score` is the first discounted by
+the second. Drift is deciding to sort on `utility` alone.
+
+The chance is zero below `DRIFT_TRUST_THRESHOLD`, rises with trust, caps at
+`DRIFT_MAX_CHANCE`, and is exactly zero when `autonomyRevoked` — which costs
+`AUTONOMY_REVOKED_THROUGHPUT` of all production, applied in `tick`.
+
+**Same non-negotiable as the fallback:** a departure sets `OverseerDecision.drift`,
+prefixes the thought text, logs at warning level, increments `driftCount`, and
+shows in the panel and the ending. `game/overseer/drift.test.ts` asserts it.
+
+## Alignment
+
+`game/alignment.ts` is where the Solarpunk/Cyberpunk axis stops being paint.
+
+- `alignmentBand()` — ±40. Deliberately past the largest single decision shift
+  (±35), so a band is a policy, not an accident.
+- `upgradeCost(state, upgrade)` — the **only** price. Scales the sticker price by
+  up to ±40% along `costAxis`. Anything that displays or spends a cost goes
+  through it; a panel quoting one number while `buyUpgrade` charges another is
+  exactly the class of quiet disagreement this codebase has been burned by.
+- `meetsAlignmentRequirement()` — the band gate. **Live**, unlike `reqNpus` /
+  `reqTrust` / `reqPhase`, which latch on once. Enforced inside `buyUpgrade`, not
+  in the UI, because the player and the Overseer both come through there.
+- `endingFor()` — band **plus** the band-exclusive capstone. Holding +100 without
+  ever committing to the Sanctuary Charter gets you the third ending.
+
+## Phase transitions
+
+Phase changes are events, not a render branch. App holds `demolishing`, keeps the
+outgoing phase's panels mounted for `PHASE_DEMOLITION_MS`, and gives them
+`panel-demolish`; `PhaseTransition` names what was lost over the top.
+
+**Keep `PHASE_DEMOLITION_MS` in App.tsx in step with the keyframe durations in
+`index.css`,** or panels unmount mid-animation. A restored save sets
+`renderedPhase` directly so loading into Phase 3 doesn't demolish panels the
+player never had open.
 
 ## Saves
 
@@ -137,12 +186,20 @@ service worker competing with it would be a disaster.
 
 ```
 game/completability.test.ts   drives tick through phase 1 → 2 → 3 → victory
+game/endings.test.ts          three committed runs reach three different endings
+game/alignment.test.ts        bands gate content and move prices, both ways
 game/rewards.test.ts          every upgrade/decision reward survives the next tick
 game/save.test.ts             round-trip, migration, corruption, offline caps
 game/overseer/utility.test.ts directives measurably reorder the ranking
+game/overseer/drift.test.ts   a departure is never silent; revoking stops it
 game/overseer/webllm.test.ts  fallback is always visible and never mislabelled
 ```
 
+`game/headless.ts` is the shared driver for the first two. It's test-only and
+imported by nothing in the app — but it is deliberately not inside a `.test.ts`,
+because two suites drive it and a second copy of the game loop would have
+drifted from the first.
+
 These are written against **claims**, not implementation. "Can this game be
 finished" is a test. So is "does a reward still exist 100ms after it's granted."
 Both correspond to real shipped bugs; keep them green.
@@ -162,9 +219,12 @@ say `paperclips.opsvibe.systems`. Keep them in sync or drop the root one.
 
 - `base: './'` in Vite — relative paths, so the build works from a custom domain
   root or a project subpath.
-- Alignment (`-100`..`+100`) currently drives colour and flavour text only. It
-  does **not** gate content or change the ending. See
-  [ROADMAP.md](ROADMAP.md).
+- Alignment gates are re-checked continuously; every other requirement latches.
+  If you add a gate, add it to `meetsAlignmentRequirement`, not to App's unlock
+  effect.
+- The victory *condition* is the same on every path — only the ending differs.
+  [ROADMAP.md](ROADMAP.md) has the arithmetic for why band-specific win
+  conditions were dropped rather than faked.
 - `probesCount` is deliberately fractional. Flooring it each tick meant a
   100-probe swarm growing at 0.1%/tick rounded back to 100 forever. Display
   floors it; the state does not.

docs/ROADMAP.md

@@ -1,19 +1,60 @@
 # Roadmap
 
-Stages 1–6 (repair, honesty pass, GitHub Pages) are done. What follows is the
-creative work that was deliberately deferred — scoped here so it isn't lost.
+Stages 1–6 (repair, honesty pass, GitHub Pages) are done. Stage 7 (7.1–7.3) is
+done. What follows is what's left, plus a record of what Stage 7 chose *not* to
+build and why.
 
 Ordered by payoff.
 
 ---
 
-## Stage 7 — Making it cooler
-
-The repair made the game *work*. This makes it *good*. The two items at the top
-are the ones that would change how the game feels most, and both are called out
-as limitations in the README today.
-
-### 7.1 Give alignment teeth
+## Stage 7 — Making it cooler — **done (7.1–7.3)**
+
+The repair made the game *work*. This makes it *good*.
+
+### 7.1 Give alignment teeth — **done**
+
+Shipped as `src/game/alignment.ts` (bands at ±40, `upgradeCost`, the live gate,
+`endingFor`), a `costAxis` tag on the upgrade data, four new band-exclusive
+upgrades including two capstones, and `src/game/endings.test.ts` — three
+headless runs to victory landing on three different endings.
+
+Two things came out differently from the scoping below, both worth knowing:
+
+- **The gate is live, not an unlock.** `reqNpus` / `reqTrust` / `reqPhase` latch
+  on forever; `reqAlignmentAbove` / `reqAlignmentBelow` are re-checked at
+  purchase, inside `buyUpgrade`. If a band gate latched, you could collect both
+  sides' content by oscillating, and the axis would be a checkpoint rather than
+  a commitment.
+- **The two capstones are priced in different currencies, on purpose.** Every
+  trust-granting upgrade in the game is alignment-positive, so a Cyberpunk run
+  reaches Phase 3 with a fraction of a Solarpunk run's trust — and therefore its
+  memory, and therefore its operations ceiling. Pricing both capstones in ops
+  looked perfectly symmetric and made the Cyberpunk ending unreachable in
+  practice. The headless run is what caught it; nothing about reading the file
+  would have.
+
+**Different win conditions per ending: deliberately not done.** The scoping
+below says "ideally, different win conditions", and it's the one item here I'd
+push back on. The obvious framing — a Solarpunk victory requires leaving some of
+the universe unconverted — is vacuous at this game's numbers. Exploration
+advances at `probes × speed × nav × 2e-9` per tick while harvesting takes
+`probes × harvester × 100`, so reaching 100% exploration costs on the order of
+`5e12` grams out of `6e18` available: about one millionth. Any restraint
+condition stated in terms of matter preserved is met without the player doing
+anything, and shipping it would have been a mechanic that reads as real and
+isn't — which is precisely the failure mode
+[LESSONS-FROM-AI-STUDIO.md](LESSONS-FROM-AI-STUDIO.md) is about. What's shipped
+instead makes the *ending* something you build (band + capstone), which is a
+real fork with a real cost, and leaves the victory condition honest and single.
+
+A genuinely different win condition would need a different Phase 3 economy — one
+where consumption and exploration actually compete for the same swarm. That's a
+bigger change than Stage 7 was scoped for; it belongs in its own item if anyone
+wants it.
+
+<details>
+<summary>Original scoping for 7.1</summary>
 
 **The problem.** The Solarpunk/Cyberpunk axis is the best original idea in the
 project and it is currently paint. `alignment` swaps two Tailwind colour families
@@ -37,7 +78,25 @@ what unlocks, or how the game ends. Full Solarpunk (+100) and full Cyberpunk
 mechanics, and most of the plumbing (the alignment number, the flavour strings,
 a single unlock check) already exists.
 
-### 7.2 Let the interface enact the story
+</details>
+
+### 7.2 Let the interface enact the story — **done**
+
+Phase transitions are events now. The outgoing phase's panels stay mounted for
+`PHASE_DEMOLITION_MS` and are visibly destroyed — shaken, desaturated, collapsed
+— under a banner naming what was taken (`PhaseTransition.tsx`, `panel-demolish`
+in `index.css`). The compute panel, the one thing that survives every
+transition, stays bright while the rest comes down. Phase 3 collapses to the
+swarm view: the swarm panel goes double-width, the compute block is demoted to a
+strip along the bottom. The frame widens once per phase and never narrows. In
+Overseer mode the pricing and procurement directives stop being rendered once
+there is nobody left to sell to.
+
+Keep `PHASE_DEMOLITION_MS` in App.tsx and the keyframe durations in `index.css`
+in step, or panels unmount mid-animation.
+
+<details>
+<summary>Original scoping for 7.2</summary>
 
 **The problem.** Universal Paperclips' real achievement is that the UI *is* the
 narrative — controls appear, the frame widens, and by the end you've forgotten
@@ -55,7 +114,29 @@ never chose to be — is *stated in flavour text* instead of enacted.
 **Why:** this is mostly CSS and sequencing — cheap relative to its impact — and
 it's the single biggest gap between this and the game it's paying tribute to.
 
-### 7.3 Overseer drift
+</details>
+
+### 7.3 Overseer drift — **done**
+
+`ScoredAction` now carries `utility` and `fit` separately, with `score` derived
+from both, so drift is a matter of which number gets sorted on.
+`overseer/drift.ts` rolls it: zero below 8 trust, rising 2% per point, capped at
+35%, and exactly zero while autonomy is revoked. Both engines route through
+`applyDrift`, so it applies whichever one is driving.
+
+A departure only counts when the alternative is genuinely *both* higher-utility
+and less directive-compliant — swapping in something that agrees with you just
+as much would be noise, not drift. `MAKE_DECISION` now ranks both branches (with
+utility measured by actually applying each branch's effect and diffing the
+state), which is what gives drift something to defect *to*.
+
+It is never silent: `OverseerDecision.drift`, a warning-level log entry, a badge
+on the deliberation panel, a running count in the Overseer panel, and a line in
+the ending. Revoking autonomy costs `AUTONOMY_REVOKED_THROUGHPUT` — 25% of
+everything — and is reversible.
+
+<details>
+<summary>Original scoping for 7.3</summary>
 
 **The problem.** The Overseer is the strongest original idea and it cannot
 surprise you. There's no tension between your directives and its behaviour —
@@ -72,6 +153,8 @@ latter as trust grows, and surfacing it loudly.
 **Why:** it's the paperclip thesis, made playable, using machinery that already
 exists.
 
+</details>
+
 ### 7.4 Deliberation as a first-class panel
 
 Promote the ranking from a strip in the thought terminal to its own panel: a
@@ -80,6 +163,11 @@ sliders, before you commit. With WebLLM active, show the model's rationale
 alongside the utility engine's ranking for the same state, so you can watch the
 two disagree.
 
+Still worth doing: with WebLLM active, showing the model's rationale alongside
+the utility engine's ranking for the same state is now more interesting than it
+was, because the two can disagree about directive fit *and* about whether to
+honour it.
+
 ### 7.5 Smaller wins
 
 - **"While you were away" summary** — offline catch-up already computes this