Iterations (append-only)

Iteration 1: initial first draft

Focus: bootstrap the project. Folder structure, git, first-draft GDD and art bible, palette, tracking files.

Changes

• GDD.md, full first draft:
  • 5 pillars, each with what it rules out.
  • Core loops.
  • World grid and island profile formulas.
  • Time structure (24-minute Nights, 3 Watches, an 8-Night moon cycle).
  • Player rules: no health; the hearth sanctuary.
  • Systems in full:
    • 6 primals plus Taint and 24 compounds with seeded recipe pools.
    • Research actions with costs.
    • 25+ machines and 8 lamps with numbers.
    • 4 golem tiers.
    • The flux integer-gas sim spec with pass order and conservation.
    • Two-channel light.
    • 4 void entities plus the Visitor, with a V formula and fairness rules.
    • Warp with gifts, costs and 6 hallucination tells.
    • Buoyancy (a log equilibrium normalized per seed), tide, crystal charge, taps.
    • Integrity and tilt.
    • Water and a weather Markov table.
    • Flora and fauna with mutation; wisps and wisp roads; Wick.
  • A 10 × 10 interaction matrix and 5 feedback loops.
  • 5 strata with pacing.
  • 3 accumulator endings plus Foundered, and endless modes.
  • 16 key decisions, a progression table, replay vectors, and 6 keepers.
  • The first-hour table, UI and lenses, audio, the tuning table, risks, and a cut list.
  • Build handoff: TS/WebGL2 architecture, schemas, M0–M5 with M1 acceptance, and 12 automated tests.
• ART_BIBLE.md, full first draft:
  • 480 × 270 internal resolution with 8 px tiles, a sprite size table, and camera rules.
  • A 64-color palette (8 ramps) with rules.
  • Essence colors; depth zones and warp remaps.
  • Palette-locked LUT lighting (spec plus build algorithm plus the WebGL2 pipeline).
  • Environment and parallax, strata looks, and character frames.
  • The machine and pipe visual language and pilot lights.
  • Flux, mutation and warp visuals.
  • UI and custom fonts.
  • Animation rules.
  • The full asset list (A01–A38, B01–B18, C01–C17, D01–D18) and the lanternforge tool spec with a prompt template.
• docs/art/palette.hex: the canonical 64-color palette.
• DECISIONS.md: D01–D24. OPEN_QUESTIONS.md: Q1–Q9.

Sims: none yet. The tuning table marks every value with the sim that must confirm it (S01–S09).

Mockups: m01_palette_swatch.png (generated with m01_palette_swatch.py, stdlib only).

• All 8 ramps are monotonic in OKLab L. Ranges: NIGHT 0.12–0.48, SKY 0.33–0.96, EMBER 0.19–0.92, GLIM 0.21–0.96, FLUX 0.17–0.82, EARTH 0.18–0.85, STONE 0.18–0.75, LIFE 0.18–0.72.
• In the vignette, warm window, cool wisps and violet haze separate clearly on indigo. The moon halo and sky dither read well at 4×.
• Weakness: the vignette is crude and doesn't test the LUT (that's m02).

Known weaknesses (for upcoming iterations)

• No emergence, balance or research evidence.
• M1 is large, and there's no scope review yet.
• Worldgen beyond the profile, entity pathing details, controls, UI flows and the save format are underspecified.
• No reference image.

Scores: 1:3 · 2:3 · 3:2 · 4:3 · 5:3 · 6:3 · 7:2 · 8:3 · 9:2 · 10:3 · 11:3 · 12:2 · 13:2

Next focus: #3 Emergence (S01 flux and S09 coupled loops).

Owner input (between i1 and i2, not an iteration)

The owner confirmed every OPEN_QUESTIONS assumption (Q1–Q9) and asked to skip audio for now.

Changes

• GDD §16 is marked DEFERRED, and audio is removed from M5.
• New GDD §15.6 visual-first rule. Every audio-dependent cue was converted to a visual one: lamp strain, darkness whispers, the Visitor telegraph, cracks and collapse, the Crucible success, and whisperer statements (now shown as handwriting and copied to the Ledger as unverified claims).
• The ART_BIBLE effects list no longer mentions sound.
• DECISIONS D25 (audio deferred) and D26 (the brief is the canonical mood reference).
• OPEN_QUESTIONS: all answered.

Scores are unchanged, and the next focus is still #3 Emergence.

Iteration 2: #3 Emergence

Focus: prove or break the flux claims with simulation, then test the coupled feedback loops.

Sims

• sims/fluxcore.py: a reference flux engine that follows GDD §6.3 in pass order, with integer transfers and an exact ledger. S01 and S09 both use it.
• S01 (flux tuning):
  • The i1 parameters passed 1 of 5 written targets. Absorption at 10%/s per face swallowed airborne flux. With 1 unit = 1 mote, floor() froze small cells. Emission was 9× too low for any room to foul.
  • Fixes: millimote units and per-mille rates, plus an emission-scale × g × absorb sweep (18 combinations). The chosen set meets 5 of 5: 1 AE = 3 motes/s, g = 60‰, absorb = 2‰.
  • Revised T1 and T2 (logged as D28): the soil floor buffers one machine, which is now a feature.
  • Validation:
    • Broken shed tinged at 6.5 min; 3 AE fouls a dark shed at 9.5 min.
    • Wisp Lantern holds 6 AE (peak 14 motes) and loses its wisp at 7 AE in 3.3 min.
    • Pooling: 34% of an outdoor source reaches a cavern 12 tiles down.
    • Wind redistributes the same source: 36% into the pond, or 31% off the island.
    • Rain: 4 min leaves 4% of sky-exposed airborne flux vs 18% with no rain.
    • Runoff moves 21% of a hillside garden's flux into the pond in one Watch.
• S09 (coupled probe): a 64 × 72 slice running flux, lamps with strain and wisp-flee, the pond and wisps, Markov weather, runoff, the reservoir, crop mutation, crystal charge → A_eq, vents, scrubbers and V.
  • E1: tipping point at 13 AE on 12 AE of lanterns (collapse at 43 min; at 14+ AE in 2–3 min). Hysteresis: after one Night at 16 AE, cutting back to 8 AE stays collapsed (pond 1,569, 4 crops turned) while a steady 8 AE stays clean.
  • E2: venting gives garden-soil jumps exactly at rain fronts (minutes 24, 48, 64) and the pond fouls at the first front. The scrubber was dominant (fixed below).
  • E3: the same 8-AE overload fails by site: uphill floods the slope (109 gleaner cells); downhill fouls the pond in 5 min; deep taints crystal (−44 fathoms, no mining).
  • E4: 24 random near-limit bases: 11 stable, 7 pond-first, 6 lamp-first failures, from 1 to 68 min.
  • E5: lamp placement changes door leakage 2.5×.
• The first S09 run exposed a binary lamp model (clear-all within budget), which made placement irrelevant. Replaced by proportional, light-weighted suppression (D34) and re-run.

Changes

• GDD §6.3 rewritten to the simulated spec: units, AE, thresholds, pass list with ‰ rates, emission table, measured timings, proportional suppression and strain, reservoir, and a "what the sims proved" table.
• Machine, lamp and golem tables converted to AE. Spawn thresholds tiered (D28).
• Plant hollow threshold set to 250 (D32): i1's 400 was unreachable.
• GDD §7 loops rewritten with evidence. V formula rescaled.
• M1 flux scope trimmed to the core passes.
• ART_BIBLE: trace-haze band, poisoned clouds.
• DECISIONS D27–D37.

Critique (five reviewers)

• Systems designer: the emergence is real (path dependence, site-dependent failure modes, delayed displaced consequences). Concern: collapse is a cliff at about 8% overload. Mitigation: the flicker band at ≥ 0.8 plus graded haze below capacity. Roots and acting entities remain unmodelled (S07, roots probe).
• New player: the rain return is delayed about 24 min, so the cause is invisible. Fixed: violet-tinted clouds proportional to R, plus a Log line on each deposit (D36). Hysteresis could feel unfair; GDD §7 now states the recovery path (scrub, time, re-catch wisps).
• Optimizer: the scrubber was dominant (zero contamination, 67k motes captured cheaply). Fixed (D35): 10 AE, 1 Ember per 2 Taint, and stored Taint counts toward V. Crystal-lamp spam was too cheap. Fixed (D37): 1 shard per Watch. Hiding factories deep is countered by crystal taint (E3).
• Art director: lamp-held factories now show 3–14 motes of haze, below the visual bands. Fixed: a "trace" particle band (10–49) so working factories breathe. The flux-lens renders in S01 and S09 read clearly at a glance.
• Scope critic: 10 flux passes is a lot for M1. Fixed: M1 ships passes 1–5, 8 and rain scrub. Wind, off-island loss, the reservoir and runoff wait for M2.

Scores: 1:3 · 2:3 · 3:4 · 4:3 · 5:3 · 6:3 · 7:2 · 8:3 · 9:2 · 10:3 · 11:3 · 12:2 · 13:2

Next focus: #7 Research (S05 solver).

Iteration 3: #7 Research

Focus: is research a satisfying deduction puzzle that replays, or brute force in a costume?

Sim: S05 (sims/S05_research.py). It implements the GDD §6.1 generator (pools, pair uniqueness, backtracking) and simulates players: guessing, uniqueness-aware, Prism-using, clue-using, and Separator-using. Over 200–400 seeds it measures failed tests, flux, warp, the aha share and seed overlap.

• The i1 design breaks without visible pools. The synthesis-only compounds (Vigil, Animus, Fetter, Dawn, Kindred) can't be Prism-scanned, so they cost 40–74 failed tests each (about 87k motes in total). Fix (D38): each compound's Correspondence (pool) is shown on first sight.
• With pools shown and 3 options, it's too easy and too similar. Seed overlap is 34%, and the full Prism is an answer key (73% free). Fixes: 4-option pools with deliberate overlaps (D40), and a Prism that shows one ancestry colour per scan (D39).
• Final design:
  • Guessing: 24.3 failed tests and 10.9k flux.
  • Thinking with scans: 12.4 failed tests, 6.6k flux and 28 T + 14 P warp.
  • Thinking plus clues: 10.5 failed tests and 6.5 P warp.
  • Aha share 69%. p90 / median = 16 / 12.
  • Seed overlap 25%, 400/400 distinct graphs, gate primal needs vary by seed.
• Targets: R1, R2, R4 and R5 pass. R3 (≥ 30 brute-force fails) failed as written, being an arbitrary absolute bar. It was reframed as brute force costing ≥ 1.5× the flux of thinking (1.64×), and the original miss is recorded in the results file.

Changes

• GDD §6.1:
  • 4th pool option for all 24 compounds; overlap rationale.
  • Generation and variety numbers.
  • The Correspondence-on-sight rule.
  • Research actions with i2-scaled flux.
  • The partial Prism with a permanent-warp cost for deep scans.
  • The S05 frontier table, where the difficulty lives, and a seed-7 worked example.
  • A new first-chain note: Ansel's clue strikes Ember+Breath.
• GDD §15.4: Ledger with essence pages, candidate fact markers, the Correspondence board, and the pair grid moved to M5.
• GDD §12 replay numbers; the Lost Ledger charter is now the hidden-pool hard mode; risk table and tuning rows updated.
• DECISIONS D38–D40.

Critique

• Systems designer: a genuine information puzzle with three currencies. Pair-uniqueness doesn't reduce failed tests on its own, because re-testing another compound's recipe is a success. It saves time and drams and creates cross-identifications. Accepted.
• New player: the first chain is 3 candidates with 1 failure on average, and each failure teaches flux. The board grows only with seen compounds, so it's never 24 × 4 at once.
• Optimizer: the partial Prism was still nearly free in temporary warp. Fixed: deep scans cost permanent warp (6.5–14 P per game). Arranger "listening rooms" (dark, fouled jar shelves) are kept as a risky, intended emergent strategy.
• Art director: the board needs ink lines and 7 × 7 glyphs plus colour bands, all achievable with A29 (code glyphs) and parchment UI. Prism bands are 1 px colour stripes per primal.
• Scope critic: the pair grid moves to M5. M1 needs only Glass and the primal pages.

Scores: 1:3 · 2:3 · 3:4 · 4:3 · 5:3 · 6:3 · 7:4 · 8:3 · 9:3 · 10:3 · 11:3 · 12:2 · 13:2

Next focus: #12 Scope.

Iteration 4: #12 Scope

Focus: make the scope measurable, cut to a core, and pin down the first slice.

Sim: S10 (sims/S10_scope.py), a scope audit. It parses the real asset list (ART_BIBLE §10.2) per milestone and method, and runs an assumption-labelled effort model.

• Finding: loose "M1–M4" tags put 176 of 226 assets in M1, including all 24 machines, 60 icons, pipes and 31 glyphs.
• After splitting the rows: M1 has 79 assets (36 code, 11 procedural, 32 AI, 16 of them icons from one sheet), M2 98, M3 32, M4 19.
• Effort: about 33 kLOC for 1.0 (M0 3.2, M1 12.0, M2 6.6, M3 4.8, M4 3.6, M5 2.4). That's within the 25–45 kLOC band for comparable 2D tile sims.
• The audit also caught a parser artifact ("5×7" read as ×7): it now requires whitespace before a multiplier.

Changes

• GDD §19 rewritten:
  • 1.0 core: 21 machines, 6 lamps, 3 golems, 4 entities.
  • Post-1.0 layers.
  • Outright cuts: Lure, Root Graft, Glowfruit Lamp.
  • Milestone size table.
  • The exact M1 manifest, with a system table, a not-in list, and a note that the full first hour becomes playable at M2.
  • M1 checkpoints M1.1 / M1.2 / M1.3, each deployed when green.
  • The AI-art-as-owner-step process.
• GDD tables purged of cut items. The Visitor, Mist, Gale and the Root golem are marked as layers. M1 contents point at the manifest. M1 acceptance 4 is tied to the owner's AI asset.
• ART_BIBLE §10.2 rewritten with exactly one milestone per row and a list of cuts.
• DECISIONS D41–D43. OPEN_QUESTIONS Q10 (owner action: generate the AI Alembic).

Critique

• Systems designer: do the cuts lose emergence? The Lure duplicated light placement, the Graft duplicated stakes plus flux feeding (light already steers roots), and the Visitor's spike is partly kept by the Deep-watch ×1.5 entity rate. Dimmers are kept deliberately as the only pressure on light itself.
• New player: M1 can't reach §14's fossil-hand hook (bedrock under 12 rows of soil). That's stated explicitly: the 10-minute acceptance test is M1's bar, and the full first hour is M2.
• Optimizer: no new exploits from scoping. Cutting the Lure removes a cheap entity-control tool, which keeps light as the only wall (P1).
• Art director: acceptance 1–3 (palette, mood histogram, reference match) can pass with placeholders; only acceptance 4 needs the real AI asset. Placeholders are flagged in the debug overlay so they're never mistaken for final art.
• Scope critic: M0+M1 is 46% of the code. The Ledger's Correspondence board moves to M2 (M1 has essence pages only), trimming M1 UI. The LUT renderer stays: it is the look and the acceptance test.

Scores: 1:3 · 2:3 · 3:4 · 4:3 · 5:3 · 6:3 · 7:4 · 8:3 · 9:3 · 10:3 · 11:3 · 12:4 · 13:2

Next focus: #13 Build-ready.

Iteration 5: #13 Build-ready

Focus: remove the questions a developer would ask before starting M0/M1.

Evidence: canonical data + validator.

• docs/data/make_data.py emits 13 JSON files: 31 essences (with pools and palette colours), 35 items, 19 recipes, 19 tiles, 31 machines, 7 lamps, 3 golems, 11 tools, 4 entities, 5 strata, 7 LUT zones, and all tuning params.
• validate.py checks:
  • referential integrity and the pool tier rules (Taint only in Fetter and Abyss);
  • the synthesis-only set matches GDD §6.1.2;
  • every essence has a use;
  • flux params equal the S01 tuned set and AE = escale/3;
  • the S05 generator succeeds on 500 seeds with these pools.
• Result: 176 records, 0 problems.
• Building the data surfaced:
  • 5 malformed recipe refs (fixed);
  • missing homes for the Clarity Lens, Stethoscope and Echo Bell (a new tools.json);
  • Kindred had no use (added the Kindred Font, which blesses a water body for the Mend ending);
  • a stale Hand Mortar flux value (1 → 9);
  • jump velocity 196 → 180 (3 tiles, not 3.75).

Changes

• GDD §20.3 rewritten: the data exists; TS interfaces match the JSON exactly; reference implementations named.
• New GDD §20.6–20.12:
  • 20.6 world generation in 10 deterministic steps (M1 subset named);
  • 20.7 controls;
  • 20.8 UI flows (adding the essence satchel and the desk panel);
  • 20.9 entity navigation (passability per kind, flow fields, retreat, middens);
  • 20.10 save format (header plus RLE/deflate typed arrays, recomputed fields, migrations);
  • 20.11 player physics;
  • 20.12 M1 object state machines (hearth, lamps, wisp lantern, desk, alembic with fuel rules, chest, jar, gleaner, wisps, Wick).
• Tests 13 (data validation) and 14 (TS ↔ reference parity) added. The M1 manifest now lists data and prefabs.

Critique

• Systems designer: M2+ machine behaviours are parameters plus table prose, not state machines. Acceptable, since M1's are complete and each later milestone can add its own §20.12 block. Recorded as the main remaining gap.
• New player: the controls follow genre convention (Terraria-like), with right-click to interact and tooltips that don't need hover.
• Optimizer: solid fuel (log = 4 Ember-equivalents) vs distilling (2 Ember + Growth 2 + Loam 1) gives a small fuel-or-research choice. Fine.
• Art director: prefabs are tile maps, so the house is built from the same procedural tiles as everything else and stays cohesive.
• Scope critic: hidden M1 work surfaced (prefab authoring, the satchel UI) and added to the manifest.

Scores: 1:3 · 2:3 · 3:4 · 4:3 · 5:3 · 6:3 · 7:4 · 8:3 · 9:3 · 10:3 · 11:3 · 12:4 · 13:4

Next focus: #1 First hour (S06 pacing).