type-two 08761e8eeb [orchestrator] round 2 review + contracts v3 + round 3 orders

Review: 5/5 lanes pass. 160/160 tests, tsc clean, M1 COMPLETE — verified live:
reference factory ships melt, commission queue advances with standing orders,
SCREEN's new artifact passes respond item-specifically (block 0.46 from bricks).

Contracts v3 (granted): EntityState.scrammed, SimSnapshot.commissionQueue,
MachineDef.coolPerTick, setRecipeAt command, Sim.save/load, ScreenFX.frame(t, snap),
BeltItem.id hardened required, MachineDef.color re-ruled as chassis/body.
main.ts: passes snapshot to screen.frame; dev __fktryDemo() builds reference factory.
happy-dom ACTUALLY installed this time (round-2 grant never landed; UI caught it).

Rulings: bandwidth units are per-second (SIM converts); heat retune ordered (nothing
can currently overheat - heatPerTick < ambient cooling); validator test moves to
data/; RENDER's color deviation approved as the ruling; scram wipe 3 frames; REMOVE
button approved. Round 3 orders in all lane docs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-17 18:05:53 +10:00

4.8 KiB

Raw Blame History

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)

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.
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.
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.
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.
Commit with your lane prefix: [sim] belt merge logic + tests. One or a few focused commits, not one mega-commit. Push.

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.

4.8 KiB Raw Blame History