8dd4616580
Supersedes unexecuted round-5 orders. Folds in the live first-eyes review findings (silence, void floor, onboarding cliff, quiet payoffs) + John's hidden-radio idea. Contracts v6: AudioFX (THE SPEAKER - all Web Audio synthesis, no asset files), RelicState + excavate + relicFound (the optical-fossil hidden pipe: find it and the game grows a tuner - FKTRY FM, Correction propaganda subtitled by THE SCREEN's chyron, a shortwave numbers station reading hidden-seam coordinates, dead air). main.ts wires audio + first-gesture unlock; src/audio stub awaits LANE-SCREEN. Lane orders: SIM = wildlife + seams-become-real + the relic + research time; RENDER = the floor (seam glints, strata whispers), relic shimmer (no signposting), juice, break-room cabinet -> match.html; UI = mercy toast, tuner dock, SCREEN click-to-enlarge, camera hints; SCREEN = era feed + THE SPEAKER (3 audio layers, 4 stations, spectral verification); DATA = the commission-ladder tutorial, stations.json broadcast schedule, seams.json final. Ship gate: after review, redeploy partly.party/glytch. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
113 lines
6.5 KiB
Markdown
113 lines
6.5 KiB
Markdown
# 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.
|
|
|
|
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.
|