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 — 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.

   Also: never bare git stash — it stashes every lane's uncommitted work and will convince you that you fixed (or caused) another lane's red. Only git stash push -- <your paths>. (Round 4: SCREEN nearly misdiagnosed a red this way; DATA's diff was the actual variable.)

   Numbers in orders go stale mid-round. Five lanes land continuously; a count or claim written into CURRENT ORDERS is true only as of writing (round 4: "24 nodes" was 23 by landing; "research doesn't exist" was false within the hour). Re-probe HEAD before acting on any order's factual claim, and before writing NOTES — a round-start grep is a lie by round-end.

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.

ROUND 5 (MEGA) addendum

The original round-5 orders were superseded before execution by the MEGA round (same goals + the paint-and-pipe layer from the live first-eyes review: sound via the hidden optical-fossil radio, the commission-ladder tutorial, the floor, juice, click-to-enlarge SCREEN, the break-room cabinet). After this round's review passes: redeploy to partly.party/glytch via ../deploy.sh — that's the ship gate.