glytch/fktry/MASTERPLAN.md

# FKTRY MASTERPLAN — orchestration doc

**Read this first, every round, whoever you are.**

FKTRY is a Factorio-style glitch-production factory game set inside a dying video file.
The full world bible is [`../docs/FKTRY_LORE.md`](../docs/FKTRY_LORE.md) — machines,
resources, enemies, eras, and the visual style guide all live there. Read it once,
fully, before your first round. It is canon; when in doubt about tone or naming, the
codex wins.

## Cast

- **ORCHESTRATOR** (Fable session with John): owns this file, `CONTRACTS.md`,
  `src/contracts.ts`, `src/main.ts`, and the CURRENT ORDERS section of every lane doc.
  Reviews each round, writes the next round's orders.
- **FIVE LANES** (Opus 4.8 executor sessions, run in parallel): SIM, RENDER, UI,
  SCREEN, DATA. Each lane has a doc in `lanes/` and an exclusive set of owned paths.
- **MODELBEAST** (asset factory on the m3ultra): generated GLB/sprite assets arrive
  asynchronously into `public/assets/` — LANE-RENDER hot-swaps them in, nobody waits
  for them.

## The round protocol (every lane, every round)

1. `git pull` first. Read YOUR lane doc (`lanes/LANE-<X>.md`): the **CURRENT ORDERS**
   section is your task list for this round. Read `CONTRACTS.md` + `src/contracts.ts`.
2. Do the work. Stay inside your **owned paths** (listed in your lane doc). You may
   READ anything in the repo; you WRITE only in your lane.
3. Verify before reporting — all three, every round:
   - `npm run check` (tsc clean)
   - `npm test` (all green; SIM lane especially)
   - `npm run dev` → open http://localhost:8150 → confirm the app boots and YOUR
     surface behaves; check the browser console for errors. "Should work" ≠ verified.
4. Append a round entry to the **NOTES** section at the bottom of your lane doc
   (template is there). Be honest: broken/unfinished things get written down, not
   hidden. Questions and contract-change requests go here too — the orchestrator
   reads every note.
5. Commit with your lane prefix: `[sim] belt merge logic + tests`. One or a few
   focused commits, not one mega-commit. Push.

   **COMMIT HYGIENE (ruled after three round-3 collisions):** five sessions share ONE
   working tree and ONE git index. `git add -A`, `git add .`, and `git commit -a` are
   BANNED — they commit whatever other lanes have staged at that instant. Every commit
   uses an explicit pathspec so the index state of other lanes cannot leak in:
   `git commit -m "[sim] ..." -- fktry/src/sim fktry/lanes/LANE-SIM.md`
   (a pathspec commit ignores the staging area for everything outside the paths).
   Before pushing, `git show --stat HEAD` — if it lists files outside your lane,
   `git reset --soft HEAD~1` and recommit correctly. If collisions still happen,
   the next escalation is a git worktree per lane.

## Hard rules

- **Never edit**: `MASTERPLAN.md`, `CONTRACTS.md`, `src/contracts.ts`, `src/main.ts`,
  root config (`package.json`, `tsconfig.json`, `index.html`), other lanes' paths,
  other lanes' docs. Need a dependency added or a contract changed? Write it in NOTES
  with rationale; the orchestrator handles it next round.
- **Never redesign the architecture.** You are an executor on a lane. Brilliant ideas
  belong in NOTES ("PROPOSAL:"), not in the diff.
- **Determinism (SIM)**: no `Date.now()`, no unseeded `Math.random()` inside the sim.
  Same seed + same command sequence = identical state, forever. Everything else may be
  as flashy as it likes.
- **Placeholders are honorable.** Do not block on assets, other lanes' features, or
  missing data. Build to the contract, stub the rest, note the stub.
- If the app won't boot because of someone else's in-flight work, note it, build
  against the contracts anyway, and verify with `npm test`/`check` this round.
- **Dev server ports are assigned per lane** so five parallel sessions never collide:
  `npm run dev -- --port <yours>` — SIM 8151, RENDER 8152, UI 8153, SCREEN 8154,
  DATA 8155. 8150 belongs to the orchestrator. Do not create or edit
  `.claude/launch.json` (orchestrator-owned, lives outside the repo).

## Milestones (orchestrator's map — lanes don't self-assign ahead)

- **M1 — FLOW** ✅ COMPLETE (round 2; verified live round-2 review: reference factory
  ships melt, commission queue advances, SCREEN corrupts item-specifically): the full
  canon melt chain — ore → demuxer →
  {quantizer, subsampler, p-caster, dct-press} → gop-assembler → mosh reactor →
  shipper. RULING (round 1): LANE-DATA's codex-faithful chain replaces the original
  6-machine sketch; the ~50-entity build IS the fantasy. A deadlock-free reference
  factory ships as the official demo (SIM round 2). Items visibly ride belts; MELT
  ships; THE SCREEN corrupts item-specifically.
- **M2 — PRESSURE**: bandwidth economy + brownouts, heat/throttling, HF dust piles,
  first wildlife (mosquito swarms), commissions via fax UI.
- **M3 — DEPTH**: tech tree + eras, bloom loops, subsampler bleed, moiré growth,
  save/load, The Correction (parity mites).
- **M4 — AWESOME**: megaglitch muxer, strata/biomes, remaster prestige, audio,
  The Fortress. Real MODELBEAST assets throughout.

## Orchestrator review checklist (per round)

Pull, read all five NOTES entries, then: `npm run check && npm test`, play the build,
diff each lane against its owned paths (ownership violations get reverted), verify
claimed features actually work, reconcile cross-lane questions, update CONTRACTS if
(and only if) two lanes need it, write next CURRENT ORDERS in each lane doc, commit
`[orchestrator] round N orders`.