09-roadmap.md · non-normative

09 — Implementation Roadmap

This document sequences the work described by the specification set into buildable phases with explicit exit criteria. It is the only document in the set that is not a specification of the product: it makes no normative claims about behaviour, carries no requirement IDs of its own, and where it conflicts with any other specification, that document wins. Its purpose is to answer "what gets built first, and how do we know a phase is done?"

Status: Draft v0.2 · Owner: unassigned · Depends on: docs/design/00-direction.md, docs/design/01-decision-turn-model.md, and the specification set — 00-overview.md, 01-game-rules.md, 02-units-and-industry.md, 03-architecture.md, 04-ui-ux.md, 05-multiplayer.md, 06-ai.md, 07-modding-content.md, 08-services-platform.md, 10-turn-model.md, 11-combat.md, 12-economy.md, 13-command.md, 14-victory.md

What changed in v0.2. The v0.1 plan was sequenced around reproducing another game: a golden-master corpus as the first deliverable, reference data as a Phase 0 gate, four inherited unit sets spread across three phases, and a definition of "done" that ended with a veteran being unable to name a rule that behaved differently. That premise is withdrawn (docs/design/00-direction.md). The plan is now sequenced around a different and harder problem: the design is original, seven rules documents deep, and has never been played. Verification against an oracle is replaced by verification against the specification plus playtesting, which now gets a phase of its own. The AI is promoted from a late add-on to the product pillar the owner asked for. Phase numbers after 2 have shifted; §2.9 maps the old numbers to the new ones.

1. Sequencing principles

  1. Determinism is a Phase 0 gate, and it is closed. The fixed-point representation, the determinism harness, the lint rules and the cross-platform CI job all existed before the first line of rules code. This is done (§2.1), and it is listed first because it is the only principle that could not have been applied later.
  2. Get to a played game as early as the design allows. There is no external oracle any more. Every constant in the rules documents is a first guess, argued in prose and never tested against a person. The plan is therefore optimised for time to first played game, not for time to feature-complete: Phase 1 builds the smallest rules surface that is genuinely a game, which the design conveniently already identifies — Industry tier 1, described in 02-units-and-industry.md §8.1 as "the complete simple game."
  3. The turn machine is built first and never stubbed. Orders, the Cascade and the Reckoning (10-turn-model.md TM-020) are the spine every other system keys off. Initiative order, activation semantics and "resolve against the world as it is at that instant" cannot be approximated in Phase 1 and corrected in Phase 2, because every rule in every other document is written against them.
  4. The order vocabulary is rules code, not a convenience layer. 13-command.md is core: its Postures and Sanctions reach the simulation through the order log (CM-2040) and changing one is a versioned rules change that breaks stored replays (CM-2060, CM-2070). It ships in Phase 1 with the turn machine. Deferring it is the single most expensive mistake available in this plan; see the first row of §4.
  5. The core is never bypassed. No phase adds a shortcut where UI, netcode, or AI mutates state directly. If a phase needs behaviour the core lacks, the core gets it.
  6. Every phase ships something playable. Each phase ends with a build a person can play, even if that build is a CLI in Phase 1.
  7. Content is data from day one. The shipped roster is authored in the shipping JSON format (02-units-and-industry.md US-700, US-1340) and loaded through the same content path a custom set will use, in Phase 1, not hardcoded and migrated later.
  8. Verification is the safety net, not review. The implementation is largely AI-authored. With no original to check against, the anchors are the requirement IDs themselves: every requirement maps to at least one named test, plus property tests (03-architecture.md AR-950), the cross-platform replay job (AR-960), and the worked test vectors the rules documents already nominate (14-victory.md VC-3310 is the model — a document naming its own reproducible computations).
  9. Instrument before tuning. Each rules document nominates the metrics that would show it was wrong (10-turn-model.md TM-1440, 02-units-and-industry.md §14, 14-victory.md VC-3300). Those emitters are built with the systems they measure, not retrofitted when balance becomes urgent.
  10. The AI is a pillar, not a phase-three afterthought. The owner has named advanced AI opponents as the headline advancement. Most play of a game of this shape is one person against AI seats, so a client with no credible opponent is not a playable build in the way that matters. A baseline opponent therefore lands in Phase 2, and the AI proper gets a full phase of its own ahead of multiplayer.
  11. One client, six platforms. The browser build is the primary delivery target; the desktop and mobile apps are the same web client packaged, not a second implementation.

2. Phase plan

2.1 Phase 0 — Foundations · all but the rights decision

Done, and verifiable in the repository.

Not done.

Void, and named so a reader of v0.1 can see they were dropped rather than forgotten.

Exit: rights path chosen; the browser leg green in the determinism matrix; no document in docs/spec/ claiming to reproduce, match, or be faithful to another game, and no (EDCE p. N) citation anywhere in the set.

Status: three of four met. Only the rights decision is outstanding, and it is the owner's, not an engineer's. The browser leg is green across Chromium, Firefox and WebKit; the documentation sweep is complete and verified mechanically — pnpm check-spec passes across the set, and the only occurrences of the forbidden citation pattern anywhere in docs/spec/ are in this document, quoting the rule that forbids it. The completed items are not re-gated.

2.2 Phase 1 — The turn machine, the core, and the first played game

Build @everylastcity/core up to the smallest rules surface that is a game, and get a person to play it. The order below is a build order, not a list.

Milestone P0 — first game played by a human, in the CLI, hot seat, tier 1. This is the earliest point at which anything in the design can be falsified, and it sits deliberately inside Phase 1 rather than at its end. From P0 onward, playtesting is a continuous track (§2.4), not a later stage.

Exit: a full tier-1 game is playable end-to-end in the CLI and has been played to a decided finish by people who did not write it; identical replay hashes across the AR-960 platform matrix, browser included; every requirement ID maps to a named test and the gaps are listed rather than absorbed; the stance-fallback rate is emitted per game; the measured V8 numbers are recorded against the (restated) AR-760 budgets with any shortfall named.

2.3 Phase 2 — The client, the full rules surface, and an opponent

Make it a game people want to look at, finish the rules, and give the solo player someone to play.

Exit: a person who has never seen the design plays a tier-1 game to a finish without reading anything and can say what they were deciding; a full four-tier game runs to a decided end against Constraint Floor opponents; accessibility audit passes; 60 fps in the browser on the reference hardware (03-architecture.md AR-700) at the performance fixture's map size, with the Tauri desktop and mobile packages of the same build inside AR-700's device allowances; the Cascade playback of a 150-unit turn is watchable and skippable.

2.4 Phase 3 — Playtest and the tuning pass

This phase is new in v0.2, and it exists because the premise changed. When the plan was to reproduce another game, balance was inherited: the numbers had been played by other people for decades and the job was to match them. Now every number is ours and none has been played. Seven interlocking systems — the Cascade, the order vocabulary, Clash and rout, Integration and Cadre, the Industry ladder, Tracks and the Vigil — have never run together in the same game. That is not a risk to be mitigated at the end; it is the largest single unknown in the project and it gets time on the schedule.

The rules documents already asked for this in their own voices. 02-units-and-industry.md US-2230 requires the design's known hard edges to be "revisited after the first full playtest." US-2220 names two failures no metric will catch. TM-1440 makes the stance-fallback rate the fastest diagnostic in the design and puts a band on it. VC-3300 defines thirteen acceptance metrics with targets and makes a metric outside its target a release blocker. Every rules document ends with open questions that say, in effect, settle this with a build. This phase is where those obligations are paid.

Exit: the VC-3300 metrics computed and inside their targets, or explicitly and publicly revised; the stance-fallback rate under TM-1440's 8 percent band across a corpus of real games; the alarm table of 02-units-and-industry.md §14 clear; every open question listed above closed by a build with the evidence recorded; a written list of every constant changed during the window and why. A metric that cannot be brought inside its band exits this phase as a named design defect, not as a silently widened target.

2.5 Phase 4 — The AI proper

The headline feature, and the largest engineering ambition in the project after the turn model.

Exit: the mid-tier AI beats a competent human less than half the time but more than never on a standard map; every tier beats the tier below it at a clear margin over a large round-robin; zero Constraint Floor violations at any tier, as a build gate rather than a metric with a band; the farm runs a nightly batch with zero desyncs and no illegal orders; and the human-survey row nobody can automate — did the opponent do anything that surprised you? — comes back yes more often than not.

2.6 Phase 5 — Multiplayer

Connect people. Async is the primary mode and this turn model is unusually kind to it: one submission per player per turn, whenever each player happens to sit down, rather than a network round-trip per unit (docs/design/01-decision-turn-model.md, "What decided it").

Exit: an async game survives a week of real play across three time zones and two platforms; a self-hosted instance runs the same test suite green; fog enforcement holds against a client modified to ask for hidden state; an eight-player Cascade resolves and plays back inside its budget.

2.7 Phase 6 — Openness

Hand the game to its community. The design already made this cheap: a custom unit set is a single JSON document using the closed flag vocabulary, with no scripting of any kind (US-2050, US-2060), and its content hash is in the canonical game hash so a version skew desyncs loudly rather than silently (US-2090, US-2100).

Exit: a third-party author, given only the public docs, ships a custom unit set and a map generator that other players install in-game and use in a multiplayer match without desync.

2.8 Phase 7 — Long tail

Exit: the VC-3300 metrics recomputed on live data with the deltas from Phase 3 explained; no Track, Charter or unit outside its balance band on population data.

2.9 Old phase numbers

For readers of v0.1 and for any document that cites a phase by number: old Phase 3 (AI) is now Phase 4, old Phase 4 (multiplayer) is Phase 5, old Phase 5 (modding) is Phase 6, and old Phase 6 (the Enhanced set and long tail) is Phase 7 with its unit-set content removed — there is one shipped set, and the Industry ladder rather than a fourth content pack carries the complexity curve. Phase 3 is new.

3. Dependency structure

Phase 0  fixed-point ✓ · determinism CI ✓ · lint gate ✓ · browser leg ✓ · doc sweep ✓ · rights
   │
Phase 1  turn machine + order vocabulary + core rules (tier 1) + CLI ──── Milestone P0
   │
Phase 2  Client · full rules surface · Constraint Floor opponent
   │
Phase 3  Playtest & tuning ◄──── the farm needs Phase 2's opponent
   │                              (continuous from P0; a dedicated window here)
   ├──────────────┐
Phase 4  AI    Phase 5  Multiplayer
   └──────┬───────┘
          │
     Phase 6  Modding & workshop
          │
     Phase 7  Stats, polish, second tuning pass

Phases 4 and 5 can run concurrently once Phase 3's tuning has settled the constants both are built against; neither depends on the other, and the ordering shown reflects the owner's stated priority rather than a technical dependency. Phase 3 is drawn as a phase because it needs dedicated time, but it begins at Milestone P0 and never stops.

4. Risk register

Risk Impact Mitigation
The conditional-order vocabulary ships thin, and the turn model collapses into blind WEGO. Named in docs/design/01-decision-turn-model.md as the single biggest execution risk in the design, and it is a scheduling risk as much as a design one: the vocabulary is the easiest thing in the plan to defer, because it looks like a UX convenience and is actually the load-bearing element The central design decision was wrong. Committing orders before seeing them becomes a gamble rather than a skill, players correctly report the game feels like guessing, and the fix is a rework of the spine rather than an addition to it Ship the six Postures (CM-330) and four Sanctions (CM-570) in Phase 1 alongside the turn machine, not in the client phase (§1.4). Instrument the stance-fallback rate (TM-1440) from the first playable build and treat its 8 percent band as a gate, not a dashboard — it is a direct proxy for "is the player's intent surviving contact with the turn," it responds immediately to changes in the vocabulary, and if it is unhealthy nothing else about the model matters. Note the asymmetry that makes early investment cheap and late investment expensive: command-layer behaviour is core and versioned, so every later change to a Posture algorithm or a Sanction test breaks stored replays (CM-2060, CM-2070)
AI ambition exceeds what a small team can build. The owner has named advanced AI as the headline feature, which is exactly the condition under which an over-promised AI ships weak and the failure is invisible to the team until players find it in week one The pillar the product is sold on is the thing players complain about; and because the failure is a plausible-looking opponent rather than a crashing one, it survives internal review Build in confidence order, not ambition order: the Constraint Floor in Phase 2, because it is arithmetic against closed integer specifications and is where opponents in this genre visibly fail; the search layer only after its plan-ranking falsification test passes (§2.5), with a named fallback — greedy plus local search over a good candidate set — that is still a competent opponent. Keep the AI a client rather than core, so its orders enter the order log and improving it never invalidates a save. Make "zero Constraint Floor violations at every difficulty tier" a build gate. State the honest ceiling in public — beat most players, lose to experts — rather than letting marketing set it
Seven interlocking new systems, 1,754 requirements, never playtested together. Nothing in the design has been played. Every constant is a first guess, and the systems couple: Industry feeds the economy, the economy prices combat losses, combat feeds Tracks, Tracks set the tempo the command layer is sized for The failure is not a bug. It is a game that is coherent on paper and unpleasant to play, discovered late, when the constants are baked into fixtures, saves and player expectations Phase 3, with dedicated time and exit criteria (§2.4). Milestone P0 as early as the design allows, on the smallest rules surface that is a game. Instrument before tuning (§1.9) so the first balance conversation has numbers in it. Freeze schemas and requirement IDs, not constants, and mark the knobs in advance. Treat each rules document's "what could go wrong" section as a work item rather than as reflection
The design's own open questions are load-bearing and unsettled. Each rules document ends with questions its author could not close by argument — the movement metric, the Yard's granularity, how much initiative to disclose, Vigil defaults. Several change how the game feels, not merely how it computes Answering them by argument produces a defensible wrong answer; answering them late produces a rework across documents that already cite each other They are chartered to Phase 3 and closed with a build (§2.4). Where a question can be settled by a cheap experiment, the experiment is the deliverable, not the memo
Committing before seeing loses players who came for the interactive feel. An honest cost the turn model decision names rather than hides Bounce on first session; reviews describing the game as "you don't get to play, you submit forms" Instant Cascade with optional step-through in solo and two-player games, and no Orders deadline unless one is asked for, per the decision document's first amendment. Treat playback quality as a Phase 2 feature (§2.3), because the playback is the compensation. Measure first-session abandonment during Phase 3, and treat a bad number as a presentation problem to solve rather than a model to relitigate
The determinism rules are a discipline, and disciplines decay. TypeScript has one number type; nothing in the language stops a plain * on two plain numbers from entering rules math a year in The violation is invisible at review — one correct-looking expression — and surfaces later as a rare desync, or a replay that diverges at turn 300 with no obvious cause Already mechanised rather than discouraged: the branded Fixed/Int types, the lint bans, and the cross-platform hash-agreement job, all in place from Phase 0. What remains is upkeep — nightly re-replay so a violation surfaces within days rather than inside a player's save, and an audit of every eslint-disable in the core at each release, because the real leak is suppression rather than absence
V8 performance on large-map turn resolution against budgets written for AOT-compiled native code The AR-760 budgets may be missed at the upper map tiers, and the miss lands hardest on the target with the least headroom — the browser tab, which is the primary one Re-baseline in Phase 1 while state layout can still change; typed arrays and structure-of-arrays state, no allocation on hot paths, monomorphic call sites, simulation in a worker. Note that the turn model helps here: the Cascade is computed once per turn rather than interactively, and playback is decoupled from computation. If a budget still cannot be met, the fallbacks in order are: relax the budget and publish the new number; cap the top map tier on the weakest targets; and only last, a WASM kernel for one isolated hot path — acceptable only behind a bit-identical differential test, since a second implementation of anything is itself a determinism risk. The AR-760 fixture must first be restated in terms of the current design
The implementation is largely AI-authored The dominant failure mode is not a crash but a plausible-looking rule that is subtly wrong: code that reads correctly, survives a casual review, and computes the wrong number in one branch. Volume makes it worse — more code is produced than anyone will read closely. The withdrawal of the fidelity premise makes this worse, not better: there is no longer an external oracle that would have caught a wrong constant Anchor verification to the requirement IDs, which are now the only authority: every requirement maps to at least one named test, plus the worked test vectors the documents nominate (VC-3310 is the pattern), property tests (AR-950), determinism CI (AR-960), coverage gate and fuzzing (AR-990). Spend scarce human review on spec-to-test correspondence — does this test assert what the requirement actually says — because that is precisely what a reviewer skimming plausible code will not catch. Prefer loud failure to defensive defaults; a silent fallback hides the mistake until it reaches a save file
Scope: fifteen documents describe more than a small team can build Nothing ships Phases 1–3 plus hot seat and a Constraint Floor opponent is a legitimate product; everything after is additive. The ordering above is chosen so that the cut line falls in a defensible place at the end of every phase
Rights and naming unresolved at ship time Cannot publish, though development is unaffected Much smaller under clean-room than under the withdrawn premise (§2.1), but still a Phase 0 exit item and still the owner's decision

Retired with the fidelity premise, named here so a reader of v0.1 can see they were dropped deliberately rather than forgotten: the drain and combat-mod formulas may not be recoverable from the original — there is no original and both systems are specified in 11-combat.md and 12-economy.md as original design; reference data may be unavailable — no reference data is needed or wanted; and the Enhanced set's special cases resist data-driven modelling — there is no Enhanced set, and the closed eighteen-flag vocabulary of 02-units-and-industry.md §3 with its ban on branching by unit id (US-060) is the structural answer to that whole class of problem.

Retired earlier by the stack change, and still retired: Godot C# on iOS cannot host WASM plugins — the plugin host is now the platform's own WASM engine, present in every browser and in Node; and browser delivery is unreachable — the browser is the primary build rather than a second client that would have had to be written twice.

5. What "done" means for the project

The v0.1 answer was that a veteran could play the game they remembered and not point to a rule that behaved differently. That is no longer a goal; it was never the owner's goal, and it is a ceiling rather than a target. The replacement is harder to measure and worth more:

Open questions

  1. Team size and shape is unstated. The phases are sequenced by dependency, not staffed. A one-person effort would likely cut Phases 6–7 and ship 1–5; a two-person effort probably has to choose between Phase 4's AI and Phase 5's multiplayer rather than doing both. This plan does not make that choice and cannot.
  2. Where does the AI specification live? Settled: 06-ai.md. It has been rewritten from the four AI design documents and carries 218 AI-prefixed requirements specifying the Staff — the layered architecture, the fairness constraints, the six Ranks, the personality roster and the self-play pipeline. It keeps its original number, so every existing citation of it still resolves. Phase 4 has a normative document to point at.
  3. Who owns the telemetry contract? Phase 3 depends on metrics nominated across five documents (TM-1440, 02-units-and-industry.md §14, 11-combat.md, 12-economy.md, VC-3300) and no document currently owns the emission, aggregation and retention of them. 08-services-platform.md is the natural home. Until someone owns it, Phase 3's exit criteria have no implementation.
  4. Is a public beta warranted, and when? Without an external oracle, outside play is worth more than it was — but a beta of an untuned game teaches the wrong lesson and an audience can only be burned once. The current instinct is a closed playtest during Phase 3 and a public one only after its exit criteria are met, but that is a judgement about audience, not engineering.
  5. Does the AI ship before, alongside, or after multiplayer? §2.9 puts AI first on the owner's stated priority. The counter-argument is that async multiplayer is unusually cheap under this turn model and would put real humans in front of the design sooner, which is exactly what a never-playtested design most needs.
  6. How much tuning budget is spent before first outside play, and who decides a metric is "close enough"? VC-3300 makes an out-of-band metric a release blocker; someone has to be allowed to revise a target publicly rather than quietly, and the plan does not say who.
  7. Does the farm need to exist before Phase 3, and who pays for the compute? The farm is the only instrument that produces thousands of games, it is what VC-3290's CI check and most of VC-3300 assume, and it has an ongoing cost nobody has budgeted.
  8. Do the AR-760 and AR-770 budgets survive V8 at the upper map tiers? Related: does the answer differ between the browser build and the Tauri builds, and is a tier cap that applies only in-browser acceptable given that the browser is the primary target? The fixture itself must be restated before the question can be answered, since as written it specifies content that no longer exists.
  9. Where do the human review gates sit, given that most code is AI-authored? Reviewing every diff neither scales nor catches the failure that matters; reviewing spec-to-test correspondence might. §1.8 asserts the principle and staffs nothing.
  10. Do the Tauri packages ship alongside the browser build at the end of Phase 2, or one phase later once store presence is being handled anyway?

Closed since v0.1: which fixed-point representation — signed Q16.16, one global scale, chosen and implemented (§2.1), and largely moot besides, since most of the rules surface specifies integer-only arithmetic (US-030 and the economy and turn-model documents throughout). Whether the browser client is a second implementation — it is not; one web client, packaged by Tauri 2. Whether iOS can host WASM plugins — the platform's own WASM engine hosts them. Whether Phase 0 VERIFY resolution needs cooperation from a rights holder — void with the premise; there is nothing to verify against and nothing to ask for.