13 — Command at Scale

This document specifies how a player commands an empire of hundreds of units without spending the turn on clerical work: the order stack every unit carries, the six Postures that state a unit's standing job, the four Sanctions that let a player pre-decide what a unit may do on its own, Formations and Groups as command objects above the unit, Postings, Consignments and Requisitions that route production to the front without per-city clicks, the interruption model that governs what happens when a plan meets the world, and the Dispatch that surfaces the handful of units genuinely needing a person out of the hundreds that do not. It also fixes the boundary the whole subsystem exists to defend: which decisions belong to the player and which are arithmetic the game must stop charging the player to perform. Under the turn model of 10-turn-model.md an order is a policy evaluated at activation, not a recorded script; this document defines that policy vocabulary. It is therefore not a convenience layer — it is the mechanism that makes committing orders before seeing the turn a skill rather than a gamble, and it is named in docs/design/01-decision-turn-model.md as the single largest execution risk in the design.

Status: Draft v0.2 · Owner: unassigned · Depends on: docs/design/00-direction.md, docs/design/01-decision-turn-model.md, 10-turn-model.md (turn structure, initiative, activation order, Stance, reactions), the units specification (classes, movement, vision, strength), the combat specification (odds prediction, withdrawal, capture), the economy specification (production, supply, repair), 03-architecture.md (determinism, integer and Q16.16 arithmetic, seeded PRNG, canonical hashing), 04-ui-ux.md (client presentation)

Naming note, binding on this document only. Two vocabularies in this spec set both wanted the word posture. This document uses Posture for a unit's standing job (Hold, Garrison, Screen, Survey, March, Attach) and Stance for the per-turn tactical setting owned by 10-turn-model.md that sets a unit's initiative modifier and reaction capacity (March, Advance, Hold, Entrench). Where 10-turn-model.md names that setting differently, its name governs and every occurrence of "Stance" here refers to it. The source proposal also used Initiative for a Sanction; this document names that Sanction Leash, because Initiative is already the turn model's activation score and one word cannot carry both meanings.

1. The agency principle, and what it binds

Everything in this document descends from one line. It is stated first because it is the test every later requirement must pass, and because a subsystem that automates without a principle automates whatever was easiest to code.

A decision belongs to the player when two competent players would reasonably choose differently. Anything on which all competent players would agree is arithmetic, and making a player perform arithmetic is not depth — it is a tax on their time that the game collects and spends on nothing.

CM-010 The agency principle above MUST govern every automated decision in the simulation core. A behaviour that decides something on which two competent players holding the same information would reasonably differ MUST NOT be automated unconditionally; it MUST either be raised to the player as an Attention Event (§11) or be placed behind a Sanction (§5) that the player set in advance.

CM-020 Every automated decision MUST be classifiable into exactly one of three ledgers, and the classification MUST be recorded in the design record for that behaviour:

Rationale: the ledger classification is what makes the principle enforceable instead of decorative. Without it, "should this be automatic?" is settled per feature by whoever is writing that feature, and the answer drifts toward whatever the engine finds convenient. With it, adding an automated behaviour requires naming its ledger, and a Commitment-ledger entry that someone wants automatic must first be argued into the Sanctioned ledger — which forces the dial, the visibility, and the log entry that make delegation reversible.

CM-030 No automated behaviour MAY take an irreversible action that no Sanction authorises. For the purposes of this requirement the irreversible actions are exactly: initiating an attack; entering a tile in a way that changes a city's or work's ownership; abandoning a Garrison post; disbanding a unit; expending a limited-use capability; and unloading a carried unit onto a tile from which it has no legal move. Each MUST map to a named Sanction value in §5 or to an explicit player Task in §3.

CM-040 Automation MUST NOT silently stop. A unit that has made no progress against its Posture for two consecutive turns MUST raise a Stalled Attention Event (§11.3); a unit that is Idle MUST raise an Idle Attention Event on the turn it becomes Idle and every turn thereafter until it has a Posture.

Rationale: the worst automation failure is not a unit that dies, it is a unit that quietly does nothing for thirty turns while the player believes it is working. That failure is invisible, compounding, and destroys trust in the whole system the moment it is discovered — after which the player hand-orders everything and the subsystem has cost interface surface and delivered nothing.

CM-050 A player who commands every unit by hand MUST NOT be mechanically disadvantaged relative to a player who automates the same units to the same effect, and a player who automates MUST NOT be mechanically disadvantaged relative to one who hand-orders identically. Specifically: automation MUST NOT confer any combat, movement, vision, production, or information bonus, and MUST NOT cost a unit tempo that a hand-issued equivalent order would not cost (see Banked Movement, CM-1600).

Rationale: these are the two halves of the same contract and both must hold. If automation is stronger, agency is gone and the game plays itself. If automation is weaker, it is a trap, and a single bad outcome teaches the player never to use it again. Every default and every threshold in this document is calibrated against this requirement, and the Banked Movement rule exists solely because without it an automated unit that pauses to ask permission loses a turn a hand-ordered unit would not.

CM-060 Formations, Groups, Doctrines, Postings and Requisitions MUST NOT confer any combat, movement, vision, or production bonus of any kind. Their only benefit MUST be the reduction in orders issued and the role behaviours they express.

Rationale: the moment an aggregation confers a fighting advantage it stops being an offer and becomes a tax — every player must use it, and the choice evaporates. The command layer's value is that it saves clicks; if it also had to be used to win, we would have replaced micromanagement with mandatory bureaucracy.

CM-070 The command layer MUST be usable at any depth: a player MUST be able to issue every order by hand for the whole game, and the Dispatch (§11), Command View (§12) and audit trail (§12.3) MUST remain fully functional for such a player.

CM-080 A newly produced unit MUST require zero player input between its creation and the first genuinely open decision affecting it. Every unit MUST come into existence with a complete order stack derived from its producing city's Consignment (§8) and its type's default Doctrine (§6), and MUST NOT raise an Attention Event on its birth turn merely for existing.

CM-090 The number of Attention Events presented to a player per turn MUST NOT grow with the player's unit count. This is a measurable acceptance criterion: across a benchmark corpus the median count of presented items MUST be ≤ 5 and the 95th percentile ≤ 12, at every unit count from 20 to 400, with a regression slope against unit count statistically indistinguishable from zero.

2. Determinism, knowledge, and what automation may see

CM-100 All command-layer logic — Posture evaluation, Sanction tests, formation projection, reinforcement allocation, interruption handling, and every tie-break in this document — MUST live in the simulation core and MUST be identical for every player, every client, and every AI seat. A client MUST NOT be able to make its player's units decide better. Rationale: presentation quality is fair competition, like a better minimap; decision quality is not. If a better client made units fight better, the game is pay-to-win by build.

CM-110 The command layer MUST NOT draw from the seeded PRNG. Every automated choice MUST be a total, deterministic function of the acting player's knowledge view (CM-130) and the unit's committed order stack. Only combat resolution consumes randomness. Rationale: replay exactness aside, randomness in automation makes it feel capricious — a player who cannot predict what their own screen will do cannot delegate to it.

CM-120 The command layer MUST NOT use floating-point arithmetic, wall-clock time, entity allocation order, hash-map iteration order, or object identity in any decision. All scores, thresholds and probabilities MUST be integers, expressed per-mille where fractional (03-architecture.md AR-080 and the per-mille convention it establishes for Int). Where a ratio comparison is needed it MUST be performed by cross-multiplication rather than division.

CM-130 Automation MUST decide using only the knowledge view of the unit's owner: currently visible tiles and units, last-known observations with their observation age, last-known strength and composition estimates, and revealed terrain. It MUST NOT read the true world state for any tile or unit the owner cannot presently see and has not previously observed.

Rationale: fog-honest automation is the single largest guarantee in this document. It costs real competence — an automated column will sometimes walk into something a thoughtful player could have inferred — and that is the correct price. Automation that reads the true board is a wallhack the player did not ask for, it makes every automated success suspect, and it makes hand-ordering strictly worse, which violates CM-050 from the other direction. The visible consequence is that expert players will hand-order at the decisive point. That is the design working, not failing.

CM-140 For routing, an unrevealed tile MUST be treated as passable at an assumed movement cost equal to the cheapest cost the unit's movement class pays on any terrain it may enter, and as containing no enemy unit.

Rationale: this answers "what does a unit know about a multi-turn route through fog". Pessimistic routing (treating unknown as impassable) produces units that refuse to cross unexplored ground, which is exactly the behaviour a player would never choose. Optimistic routing produces units that set out and discover the truth, which is what a player does — and the Blocked handling in §9 catches the failure cleanly, suspending rather than destroying the order.

CM-150 Where a decision requires a combat prediction, the command layer MUST use the same deterministic predictor the client shows a player before a manual attack, evaluated over the knowledge view, returning an integer per-mille win probability in [0, 1000] together with an estimated flag.

CM-160 The predictor MUST set estimated = true whenever the knowledge view lacks a current observation of the target's strength, and in that case MUST return a conservative value of 400‰. An Engagement Sanction of Favourable MUST NOT authorise an attack on an estimated prediction unless the unit's engageOnEstimates flag is set (default false). Engagement Free MUST ignore this restriction.

Rationale: 400 is below every offered preset, so the default behaviour of a unit that cannot see what it is attacking is not to attack. This is the cheapest possible guard against the most common automation disaster — a column that assaults a stale contact marker — and it costs nothing when the player does have eyes on the target. The flag exists because a raiding force deliberately operating blind is a legitimate style.

CM-170 Every tie in every command-layer selection MUST be resolved by an explicit, totally-ordered tie-break chain terminating in a value guaranteed unique. The terminal tie-breaks are:

CM-180 Order-stack contents, Postures, Sanction values, Doctrines, Formation and Group membership and orders, Postings, Consignments, Requisition rows and their allocation counters MUST be part of authoritative game state and MUST contribute to the canonical state hash. Attention Events, Dispatch ordering, adaptive player weights, snooze timers and Command View settings MUST NOT contribute to the canonical state hash.

Rationale: the split is what lets the ranking of attention improve over the product's life without invalidating a single saved game. What a unit will do is the game; which of those things you are shown first is the interface.

CM-190 Attention Events MUST nonetheless be emitted by the core, deterministically, and MUST be covered by a separate versioned advisory stream hash so that a divergence in what players are told is detectable in CI without coupling it to the rules hash.

3. The order stack

CM-200 Every unit MUST carry an order stack exactly three levels deep:

[2] Reflex    — pushed by the engine: Withdraw, Replenish, Regroup, Return to Post, Take Cover
[1] Task      — pushed by the player: a one-off instruction with an end condition
[0] Posture   — the standing order; the unit's job

CM-210 A unit MUST execute the topmost non-empty level of its stack at each activation. When a level's completion condition is met, or the level is cancelled, that level MUST be popped and the unit MUST resume the level below at its next evaluation within the same activation, without consuming an additional activation.

CM-220 Popping a level MUST NOT alter or clear the levels beneath it. A unit interrupted while executing a Posture MUST resume that Posture, with all its parameters intact, when the interrupting level pops.

Rationale: this is the single most important structural decision in the document. In the traditional model an interruption destroys the order and leaves a blank order-demanding object — at precisely the moment the player is busiest, which is why interruptions feel like punishment. Here a unit that withdraws under fire pops the Withdraw reflex when it is safe and goes back to screening the line it was screening, with no input at all. Suspension rather than destruction is what turns three hundred units into thirteen command objects.

CM-230 The stack depth MUST remain three. A behaviour that appears to need a fourth level MUST be expressed by projection (CM-880) or by an end condition on an existing level. Rationale: a deeper stack cannot be explained on a unit panel, and a player who cannot read the stack cannot audit the automation, which is the whole basis of trust here.

CM-240 The Posture level MUST NOT be empty except when the unit is deliberately Idle (CM-540). Setting a Posture MUST replace the previous Posture rather than stacking on it.

CM-250 A Task MUST carry: an action (move to, attack, garrison, load, unload, join formation, execute a named Posture once), a target or route, an explicit end condition, an optional pressHome flag, and an optional Stance override. A Task without an end condition MUST be rejected at submission.

CM-260 A Task MUST pop when its end condition is met, when it becomes permanently impossible (§9), or when the player cancels it. Task end conditions MUST be drawn from: onArrival, onTargetDestroyed, afterNTurns(n) with n in [1, 50], whileEnemyVisibleWithin(k) with k in [1, 16], and untilCancelled.

CM-270 An explicit player Task MUST be treated as its own authorisation for the action it names: the Engagement Sanction MUST NOT block an Attack Task, and the Seize Sanction MUST NOT block a Task that names a city as its destination.

CM-280 The Risk Sanction MUST continue to apply during a Task unless the Task sets pressHome = true, which MUST suppress Risk-driven Reflexes for the duration of that Task only.

Rationale: ordering an attack should not mean ordering a unit to die in it — a player's standing instruction about self-preservation is exactly the kind of thing they set once and expect to hold. But an assault that must go in regardless is a real order and the vocabulary must be able to say it. One boolean buys both, and its default (off) is the safe one.

CM-290 A Reflex MUST be pushed only by the engine, never by the player, and only for the causes enumerated in CM-1400. Exactly one Reflex MAY occupy the level at a time.

CM-300 When a second Reflex becomes eligible while one is active, the higher-priority Reflex MUST replace the active one and the replaced Reflex MUST be discarded, not queued. Reflex priority MUST be, highest first: Withdraw, Replenish, Regroup, ReturnToPost, TakeCover.

Rationale: survival outranks sustainment; a unit that cannot sustain itself cannot usefully hold formation; cohesion outranks returning to a post because the formation is the more immediate obligation; cover is last because it is the weakest and most easily re-derived. Discarding rather than queueing keeps the level at depth one and keeps the panel readable — and a discarded reflex whose cause still holds will simply be re-pushed at the next activation.

CM-310 Every unit MUST carry a Fallback Posture: a complete Posture-plus-Sanctions tuple, set once per unit, defaulting to Hold / Engagement Defend / Leash 0 / Risk Prudent(334) / Seize Never. The Fallback Posture MUST be adopted whenever an order becomes Impossible (§9) and MUST be shown on the unit panel.

Rationale: it is the answer to "what do I do when I no longer know what to do", chosen by the player in advance. It means an order that becomes impossible never produces surprising behaviour, and it means an absent player's units do something coherent instead of freezing.

CM-320 The complete order stack, including the Fallback Posture and all Sanction values, MUST be inspectable on the unit panel in plain language at all times, and MUST be editable at any level without disturbing the others.

4. Postures

CM-330 The Posture vocabulary MUST consist of exactly six Postures plus the Idle state. Adding a seventh Posture is a rules change requiring a commandLogicVersion bump (CM-2130).

Rationale: six, not twenty. Each is one sentence a player can hold in their head, and between them they cover every job a unit actually has in this game. A larger vocabulary would look richer and would be used less, because a player who cannot remember what the eleventh Posture does will not choose it. Richness lives in the Sanctions, which are four orthogonal dials rather than a longer list — four dials over six Postures is 6 × 4 axes of expression, which is far more than twenty named behaviours and far easier to learn.

CM-340 A Posture MUST be an order-policy in the sense of 10-turn-model.md: stored on the unit, evaluated when the Cascade reaches that unit, against the world as it then is, and persisting across turns until it completes or the player changes it. A Posture MUST NOT be stored as a recorded sequence of steps.

CM-350 Posture assignment MUST be validated at submission and rejected with a named, localisable reason when statically illegal — a Screen line shorter than two tiles, an empty Survey region, a Garrison target that is not a city or work, a March with zero waypoints, an Attach to a formation at its span limit, or a Posture the unit's class may not hold. An order that is legal at submission and unachievable at activation MUST NOT be treated as an error (§9).

CM-360 Every unit class MUST be able to hold Hold, March and Attach. Garrison MUST require the ability to occupy the target city or work. Screen MUST require a movement allowance of at least 1. The units specification owns any further per-class restriction.

4.1 Hold

CM-370 Under Hold a unit MUST remain on its assigned tile, MUST NOT voluntarily leave it, and MUST defend it. The assigned tile is the tile it occupied when Hold was issued, or the tile named in the order.

CM-380 A Hold unit that is displaced by a Reflex, a retreat, or an external effect MUST push a ReturnToPost Reflex, and MUST be permitted to move to its assigned tile regardless of its Leash value.

Rationale: the Leash constrains where a unit may choose to go, not where it may go back to. A Leash of 0 that forbade a displaced garrison from walking home would make the tightest setting the most fragile one, which is precisely backwards.

CM-390 A Hold unit MUST derive Stance Hold, or Stance Entrench when it has occupied its assigned tile without moving for at least one complete turn and its Engagement is Never or Defend.

Rationale: entrenching costs initiative and buys defence and a reaction, which is exactly the trade a unit whose job is to stay put should take — and the one-turn delay makes it a consequence of having actually held rather than a free bonus for declaring an intention.

4.2 Garrison

CM-400 Under Garrison a unit MUST occupy the named city or work, MUST defend it, MUST return to it by the cheapest route when displaced (via ReturnToPost, permitted regardless of Leash), and MUST accept repair or resupply while stationary and undamaged-elsewhere-idle if the economy specification offers it at that place.

CM-410 A Garrison unit MUST NOT abandon its place under any Sanction. Abandoning a garrison is a Commitment-ledger action (CM-020) and MUST require an explicit player Task or a Posture change.

CM-420 A Garrison unit whose place is captured or destroyed MUST treat the order as Impossible (§9) and adopt its Fallback Posture.

CM-430 Garrison MUST derive Stance Hold while in place and Stance Advance while returning to place.

4.3 Screen

CM-440 A Screen order MUST carry a line: an ordered list of 2 to 64 tiles defining a frontage. The tiles need not be contiguous and need not be passable to the screening unit.

CM-450 A line tile MUST be considered covered at an instant if it lies within the vision radius of any unit belonging to the screening unit's owner, evaluated at that unit's position as of that instant in the Cascade.

CM-460 At each activation a screening unit MUST select its destination as follows, using only integer arithmetic:

1. Build the candidate set: tiles the unit can legally reach within its remaining movement allowance this activation, that lie within Leash tiles (Chebyshev) of the nearest line tile, and that it may legally occupy under stacking rules. The unit's current tile is always a candidate.
2. Exclude candidates that the Risk Sanction forbids (CM-680).
3. Truncate the candidate set to at most 256 entries, ordered by ascending movement cost then ascending tile index (CM-2180).
4. Score each candidate as the number of line tiles that would be covered from it and are not already covered by another friendly unit at that instant.
5. Select the highest score; ties break by lowest movement cost to reach, then by lowest tile index.
6. Apply hysteresis: the unit MUST relocate only if the selected candidate's score is at least 2 greater than the score of its current tile. Otherwise it MUST remain in place.

CM-470 When no candidate covers any line tile, a screening unit MUST move along the cheapest route toward the lowest-indexed uncovered line tile, spending at most its remaining allowance, and MUST NOT be considered stalled while the remaining route cost is decreasing.

Rationale for the whole of §4.3: a Screen is a coverage goal, not a patrol route, and that is what makes it degrade gracefully. Several units on the same line spread out for free, because a tile a comrade already covers scores nothing extra; when one dies the survivors re-spread to cover the gap without being told. The hysteresis threshold of 2 is the load-bearing number: at 1, units shuffle one square sideways every turn as fog moves, which looks broken even when it is optimal, and shuffling costs the reaction a Hold stance would have given them. At 3 or more the line responds too slowly to a genuine gap. Two is one more tile of coverage than the noise floor and one less than a real gap.

CM-480 Screen MUST derive Stance Hold when the unit did not relocate at its previous activation, and Stance Advance otherwise. Rationale: a screen that has settled is exactly the thing that should hold a reaction, and paying the initiative cost for it is the correct trade; a screen still finding its position cannot also be watching.

4.4 Survey

CM-490 A Survey order MUST carry a region: a set of 1 to 4096 tiles.

CM-500 At each activation a surveying unit MUST select its destination as follows:

1. Build and truncate the candidate set as in CM-460 steps 1–3, substituting the region for the line and using Leash measured from the region boundary.
2. Exclude any candidate within one turn's known movement of a visible enemy the unit does not beat at its avoidance threshold, where the avoidance threshold is the unit's Favourable per-mille value if Engagement is Favourable, 700‰ if Engagement is Never or Defend, and avoidance is disabled entirely if Engagement is Free.
3. Score each candidate as the count of currently-unrevealed region tiles that standing there would reveal.
4. Prefer the candidate maximising revealed tiles per movement point, compared by cross-multiplication: candidate A beats B when scoreA × (costB + 1) > scoreB × (costA + 1). Ties break by lower cost, then by lowest tile index.

CM-510 A Survey MUST raise an Arrived interruption when the region contains no reachable unrevealed tile.

CM-520 Survey MUST derive Stance March. Rationale: coverage per turn is the entire job, the unit is deliberately not fighting, and a scout that keeps a reaction it will never profitably spend has bought nothing with the initiative it gave up.

4.5 March and Ferry

CM-530 A March order MUST carry: an ordered list of 1 to 16 waypoints; a cached route; a follow-on order (a complete Posture tuple, or Fallback, or Attach to a named formation); and a loop mode of Once, Shuttle, or Circuit. Shuttle and Circuit together constitute the Ferry variant.

CM-535 A Ferry unit with carrying capacity MUST, on reaching a terminal waypoint, first unload every carried unit whose destination is that waypoint, then load waiting units bound along the route up to its remaining capacity, in ascending creation sequence number. Loading and unloading on a stated route is Execution-ledger work (CM-020) and MUST require no player input.

CM-540 A unit with an empty Posture level MUST be Idle. Idle MUST NOT be reachable except by the player explicitly clearing a Posture, MUST NOT be a resting state, and MUST raise an Idle Attention Event every turn until a Posture is set. Rationale: there is to be no way to have a quietly forgotten unit. Idle is deliberately uncomfortable.

CM-550 March MUST derive Stance March when the unit's Engagement is Never or Defend, and Stance Advance when it is Favourable or Free. Rationale: a column that is authorised to fight on the way must be able to fight on the way, and Stance March forfeits that; a column that is not authorised to fight should buy the movement and initiative instead.

CM-560 A player MUST be able to override any unit's derived Stance for a turn as an annotation on the Task level, and the override MUST be shown on the unit panel with the derived value it replaced.

5. Sanctions

CM-570 Every Posture MUST carry exactly four Sanctions — Engagement, Leash, Risk, Seize — which MUST be displayed in plain language on the unit panel whenever the unit is selected, and MUST be editable individually without changing the Posture.

Rationale: this is the whole answer to "the game played itself". It did not: the player wrote the rule and the game applied it. When a Sanction produces a bad outcome the player does not lose faith in automation, they tighten one enum — because they can see exactly which clause fired and what the numbers were. Delegation becomes gradual and reversible instead of a binary leap of faith, and that is the difference between an automation feature players use and one they abandon after the first disaster.

5.1 Engagement — when may this unit start a fight?

CM-580 Engagement MUST take one of four values:

CM-590 Favourable(N) MUST accept any integer N in [1, 999]. The default MUST be 700. The offered presets MUST be Trade 600, Even-handed 700, Careful 850.

Rationale for 700: a unit that fights ten sanctioned engagements at 700‰ wins seven and loses three. That is a good trade for a cheap screening unit and a bad one for something expensive, which is exactly why the number lives on the unit rather than in a global setting. It is also high enough that a player watching automation win seven fights in a row does not conclude the automation is reckless, and low enough that a screen actually picks off stragglers rather than standing inert — the failure mode at 850 as a default would be a screen that never fights, which reads as broken.

CM-600 An automated attack MUST record the predicted per-mille value and the threshold that permitted it, in the form "Attacked at 743‰ predicted; sanctioned at ≥700‰" (CM-2020).

CM-610 When more than one target satisfies Engagement in the same activation, the target MUST be selected by: (1) highest predicted per-mille; (2) a target inside the unit's assigned geometry over one outside it; (3) lowest target creation sequence number.

CM-620 Engagement Never MUST cause the unit to prefer, among otherwise-equal candidate destinations, the one maximising the Chebyshev distance to the nearest visible enemy.

5.2 Leash — how far may it leave its assigned geometry?

CM-630 Leash MUST be an integer Chebyshev radius in [0, 64], measured from the unit's assigned geometry: its assigned tile for Hold and Garrison, the nearest line tile for Screen, the region boundary for Survey, the cached route for March, and the Command Reference Point for Attach.

CM-640 The offered presets MUST be Tight 0, Local 4, Loose 12, and the player MUST be able to type any integer in range.

Rationale: 4 is roughly two turns of movement for a typical ground unit, which lets one screening unit cover a nine-tile frontage from its centre; 12 is three times that and is a scout's leash — far enough to follow a promising direction, short enough that the unit is still recognisably where you put it. Tight 0 exists so that "stay exactly there" is expressible without inventing a Posture for it.

CM-650 A Leash MUST constrain voluntary movement only. ReturnToPost, Regroup, and Withdraw Reflexes MUST be permitted to exceed it, and the excess MUST be shown on the unit panel while it persists.

5.3 Risk — when does it break off and preserve itself?

CM-660 Risk MUST take one of three values:

CM-670 Prudent(N) MUST accept any integer N in [1, 999]. The default 334 expresses "reduced to a third of strength or less".

CM-680 Threat radius MUST be defined, for a visible enemy e, as the last-known movement allowance of e clamped to [1, 6]. Where no movement allowance is known, the threat radius MUST be 2.

Rationale: threat is "can it reach me before I act again", which is the enemy's movement, not an arbitrary constant. Clamping at 6 keeps a single very fast unit from making a whole theatre nervous; the fallback of 2 is one more than adjacency and is the conservative default for an unidentified contact.

CM-690 For Cautious, "does not beat" MUST use the unit's Engagement per-mille value when Engagement is Favourable, and 700‰ when Engagement is Never or Defend. Cautious with Engagement Free MUST apply only the Prudent(N) test.

Rationale: Screen pairs Favourable with Cautious by default, and that pairing is the whole behaviour of a screening force — pick off stragglers, evade columns. Neither dial produces it alone.

5.4 Seize — may it take an undefended city it walks past?

CM-700 Seize MUST take one of three values:

CM-710 The default for Survey and March MUST be Undefended; for Hold, Garrison and Screen it MUST be Never.

Rationale: this is the one default sitting on the permissive side of the line, and CM-050 is the reason. If the default were Never, an automating player would watch an empty city and lose it while waiting to be asked — which makes automation measurably worse than hand-play and poisons the whole system. Capturing a genuinely undefended city is a case where all competent players agree, so by CM-010 it is arithmetic. It remains a Sanction nonetheless: visible, revocable, logged. The principle is preserved; only its default differs. The honest cost is that fog-honesty means "undefended in the knowledge view" is sometimes wrong, and a unit will occasionally walk into a garrison it could not see. That is the price of CM-130 and it is the right price.

CM-720 Seize: Free MUST NOT authorise an attack that Engagement forbids. The two Sanctions MUST both be satisfied.

CM-730 After a sanctioned capture the capturing unit MUST push a Task Garrison <place> until relieved, MUST raise a CityTaken Attention Event offering release it back to its Posture and requisition a garrison, and the capture MUST insert a shortfall entry for one garrison-capable unit into the Requisition of the Posting the unit is posted to, if any.

Rationale: leaving a captured city empty loses it, so the unit must hold. Permanently converting a scout into a garrison is a Commitment-ledger decision, so the player must be asked. Raising a Requisition entry converts the nag into a request production can actually satisfy, which is the difference between an item that resolves itself and one that sits in the Dispatch forever.

5.5 Defaults, presets, and precedence

CM-740 Posture defaults MUST be exactly:

Rationale: Garrison is Expendable because a garrison that runs away is not a garrison — the one place where "never withdraw" is the correct default, because the alternative loses the thing being garrisoned. March's Leash of 2 rather than 4 keeps a column recognisably on its route; a marching unit that wanders four tiles for an opportunity is a column that arrives late.

CM-750 Three named presets MUST be offered, applied as transforms over the Posture defaults rather than as absolute tuples:

Rationale: four dials over six Postures is real learnability cost. Presets are the progressive-disclosure answer: a new player picks one of three words, an experienced player opens the dials. Expressing presets as transforms rather than absolutes preserves the Posture-specific reasoning behind each default — Careful applied to a Garrison must not quietly make it withdraw.

CM-760 Sanction precedence MUST be, strongest first: an explicit per-unit override; a Formation projection (CM-880); the unit type's default Doctrine; the Posture default. The effective value and the level that supplied it MUST both be shown on the unit panel.

6. Doctrines

CM-770 A Doctrine MUST be a named, player-created bundle of: a Posture template, all four Sanction values, an optional Formation role, and an optional Stance override. Doctrines MUST be part of authoritative game state (CM-180).

CM-780 A Doctrine MUST be applicable in one action to a unit, to a multi-unit selection, to a Formation, or as the default for a unit type.

CM-790 Every unit type MUST have a default Doctrine, settable in one panel, applied automatically at unit creation.

CM-800 Editing a Doctrine MUST NOT retroactively change units already created under it. The editor MUST offer an explicit apply to the N units currently on this Doctrine action stating N.

Rationale: silently retasking three hundred units because a dial moved is exactly the kind of unsanctioned mass action CM-030 forbids, and it is the fastest possible way to destroy trust in the system. Making the retroactive apply explicit and counted costs one click and makes the consequence legible before it happens.

CM-810 A Doctrine MUST NOT be able to express a Posture parameter that is unit-specific — a specific Screen line, Survey region, or March route. A Doctrine's Posture template MUST supply those from the Posting (§8) or leave the unit Idle if none is available.

CM-820 Deleting a Doctrine MUST NOT alter any unit currently running it; such units MUST retain their current effective values as per-unit overrides.

CM-830 The client MUST show, for every Doctrine, the count of units currently running it and a one-action selection of those units.

7. Formations and Groups

7.1 Definition

CM-840 A Formation MUST be a named set of units with one designated commander and one order stack, and MUST be a command relationship only: members MUST retain their own tiles, movement, vision, combat resolution and losses. No super-unit representation may exist.

Rationale: no doom-stack. Positioning still matters, and losing a formation is a series of events a player can watch and react to rather than one catastrophic roll. It is also why CM-060 can forbid a combat bonus without gutting the feature — the benefit is one order instead of eight, and that is enough.

CM-850 A Formation MUST have a span of control of 8 members. Adding a ninth MUST be rejected at submission with a named reason and an offer to split the Formation or promote it into a Group.

Rationale: eight rows is a formation panel readable without scrolling, and span-of-control practice across every real hierarchy clusters between three and nine. If the units specification later gives some unit types a command rating, span becomes per-commander data and 8 becomes the default when it does not.

CM-860 A Group MUST command up to 5 Formations and MUST NOT contain units directly. Nesting MUST be exactly two echelons: units in Formations, Formations in Groups. A Group MUST NOT contain a Group.

Rationale: two echelons cover 40 units per Group and 400 units in ten Groups, which is past the top of the expected late-game range. A third level cannot be navigated at speed, and the whole point is that the empire is never more than about ten top-level objects.

CM-870 A Formation MUST be able to hold Postures Hold, Screen, Survey, March (including Ferry loop modes) and Attach. Garrison MUST be unit-only. A Group MUST be able to hold Hold, Screen and March.

7.2 Projection

CM-880 A unit whose Posture is Attach MUST derive its effective Posture-level order by projection: the Formation's entire order stack collapses to a single projected order occupying the member's Posture level. The member's Task and Reflex levels MUST remain available and MUST outrank the projection.

Rationale: this keeps the stack at three (CM-230) while letting a formation member simultaneously carry a formation intent, a personal order, and a reflex. It also produces the behaviour a player expects without being told: an order given directly to a unit overrides its formation's, and a reflex overrides both.

CM-890 Projection MUST assign each member a per-role order according to the following table:

CM-900 Role slot counts MUST be constrained: Main ≥ 1, Van ≤ 2, Rear ≤ 2, Flank ≤ 4, Train ≤ 4, total ≤ 8. A Formation created without an explicit assignment MUST place every member in Main.

CM-910 The Van role MUST force Engagement Defend and Risk Cautious on its members regardless of Doctrine, and this MUST be shown on those units' panels as a role override.

Rationale: the vanguard is there to find things, not to fight them. A Van that engages is a Van that is dead before it has reported, and the whole value of the role is the report.

CM-920 Offsets in CM-890 MUST be resolved to concrete tiles deterministically: the offset direction is the direction of the next route segment (for March) or the Formation's stored facing (for Hold and Screen); the target tile is the cheapest legal tile at the stated offset; ties break by lowest tile index.

CM-930 A Formation MUST store a facing: one of the eight movement directions, defaulting to the direction of the Formation's most recent movement and settable by the player.

7.3 The Command Reference Point and Intent Freshness

CM-940 A Formation MUST have exactly one commander, a designated member. On the commander's death, succession MUST pass to the surviving member with the lowest creation sequence number whose role is not Train; if every survivor is Train, to the lowest creation sequence number among them.

Rationale: sequence number is unique, so succession is total and needs no further tie-break; and an older commander is a more responsive one under CM-960, so the rule that is easiest to compute is also the one that produces the better formation.

CM-950 The Command Reference Point (CRP) MUST be the commander's tile as of the commander's last completed activation. Cohesion, offsets, and Leash for Attach MUST all be measured from the CRP.

CM-960 A Formation member MUST execute the Formation's intent as of the commander's last completed activation. Concretely: the engine MUST snapshot the Formation's projected intent and CRP at each commander activation; a member activating after the commander in the current Cascade MUST read this turn's snapshot, and a member activating before it MUST read the previous snapshot.

CM-970 A Formation created or re-ordered during an Orders phase MUST have its snapshot taken at commit time with the current turn's epoch, so that every member is responsive on the Formation's first turn.

CM-980 Where the commander died before activating in the current Cascade, members MUST continue to read the last snapshot taken by the dead commander until the successor completes an activation.

CM-990 The Formation panel MUST state, at all times and in words, whether the Formation is Responsive (commander activates before the majority of members) or One turn behind (it does not), together with the reason.

Rationale: command lag falls out of the initiative ordering for free and is elegant enough to adopt deliberately — putting an old unit in charge makes a Formation responsive; promoting a freshly built unit to command makes it sluggish; losing a veteran commander has a felt cost beyond the unit. It is fully deterministic, costs nothing to compute, and explains itself in one sentence. Its one risk is that it is invisible unless the UI says so, at which point a lovely rule becomes a bug report. Hence the MUST on the panel.

7.4 Pace and cohesion

CM-1000 A Formation MUST have a Pace of Concentrated or Dispersed, defaulting to Concentrated.

CM-1010 Under Concentrated, a member whose Chebyshev distance from the CRP exceeds the Formation's cohesion radius MUST be pushed a Regroup Reflex. The cohesion radius MUST default to 3 and be settable in [1, 8].

CM-1020 Under Dispersed, cohesion MUST NOT be enforced and Regroup MUST NOT be pushed for cohesion reasons.

Rationale: this is the classic operational trade — concentration versus tempo — expressed as one toggle. Concentrated advances at the speed of its slowest member and arrives as a fist; Dispersed arrives piecemeal but its fastest elements arrive far sooner. It means the command layer adds a decision rather than only removing clicks, which is the difference between a strategy feature and an accessibility feature.

CM-1030 A Regroup Reflex MUST move the unit along the cheapest route toward the CRP and MUST pop when the unit is within the cohesion radius.

CM-1040 A member that cannot reach the cohesion radius within two turns of movement MUST raise a FormationStrung Attention Event once per occurrence, deduplicated by Formation.

7.5 Under-strength Formations

CM-1050 A Formation on Screen MUST be considered under-strength when, after every member has activated, the count of uncovered line tiles u and the line length L satisfy u × 4 > L.

CM-1060 An under-strength Screen MUST NOT fail. It MUST provide partial coverage per CM-460, MUST raise a single sticky FormationUnderStrength Attention Event, and MUST insert a shortfall entry into the Requisition (§8.4) of the Posting the Formation is posted to, if any.

Rationale: the alternative answers are both worse. Failing the order strands the formation. Raising a fresh item every turn is a nag the player learns to dismiss, which trains them to dismiss the category. Converting the shortfall into a Requisition entry means production reacts and the item resolves itself, which is the only outcome that respects the player's time.

7.6 Group behaviour

CM-1070 A Group's order MUST project to its member Formations exactly as a Formation's projects to its units, using the same five roles applied at Formation granularity.

CM-1080 A Group's CRP MUST be the CRP of its commanding Formation, and Intent Freshness (CM-960) MUST apply at both echelons independently. A Group order therefore MAY be up to two commander activations stale at a unit, and the Formation panel MUST say so when it is.

CM-1090 Disbanding a Formation MUST set every member's Posture to the Formation's projected order at the moment of disbanding, converted to a per-unit Posture with the member's effective Sanctions. It MUST NOT leave members Idle.

CM-1100 Removing a unit from a Formation MUST set that unit's Posture to its projected order at the moment of removal, by the same conversion.

CM-1110 A Formation whose membership falls to zero MUST be deleted, and its Posting reference (if any) MUST be retargeted per CM-1230.

CM-1120 A unit MUST belong to at most one Formation, and a Formation to at most one Group.

8. Postings, Consignments, and Requisitions

This is the largest single source of clicks in the traditional model and the one with the least decision content in it. It is also where genuine operational-level command lives: choosing the force structure is the decision, and turning that structure into build orders is arithmetic.

8.1 Postings

CM-1130 A Posting MUST carry: an id, a player-set name, an anchor (a tile or a Formation reference), a default arrival Doctrine or Posture, an integer weight in [1, 10], a Requisition table (§8.4), and a surplus rule.

CM-1140 Every unit MUST carry a postedTo field naming a Posting or none. It MUST be set at creation from the producing city's Consignment, MUST persist through arrival, and MUST change only by explicit player action or by CM-1230.

Rationale: Posting membership must be a stored fact, not a geometric inference. Inferring it from proximity would make a front's strength wobble as units moved, which makes Requisition shortfalls oscillate and production thrash — and a stored field is one integer per unit and exactly reproducible.

CM-1150 The client MUST warn, without blocking, when a player creates a 13th Posting, and MUST offer a review of existing Postings.

Rationale: a player with fifteen Postings has rebuilt the micromanagement problem one level up. Twelve is comfortable headroom over the ten top-level command objects a person can hold; the warning is a nudge, not a rule, because a hard cap on how a player organises their own empire is exactly the patronising design this document rejects elsewhere.

8.2 Consignments

CM-1160 Every city MUST carry a Consignment: a Posting id, Auto, or Manual. The default for a starting city MUST be Auto. A newly captured city MUST default to Auto.

Rationale: capturing a city should not generate clerical work (CM-080). Auto routes its output through the scheduler, which is the answer a player would give if asked, so we do not ask.

CM-1170 A unit produced in a city consigned to Posting P MUST be created with postedTo = P, a Posture of March to P's anchor, and a follow-on order taken from P's default Doctrine or Posture. This MUST require zero player input.

CM-1180 A unit produced in a Manual city MUST be created with its type's default Doctrine and postedTo = none, and MUST NOT be Idle.

8.3 The allocation scheduler

CM-1190 When a city's Consignment is Auto, the destination Posting MUST be chosen by the following deterministic integer scheduler. Let E be the set of eligible Postings — those whose Requisition has a shortfall greater than zero — and W the sum of their weights. For each allocation, in order:

1. For each Posting p ∈ E, counter[p] += weight[p].
2. For each Posting q ∉ E, clamp counter[q] to at most W.
3. Select the Posting in E with the greatest counter; ties break by lowest Posting id.
4. counter[winner] -= W.

CM-1200 Worked example, normative as a test vector. Postings Northern (weight 3, id 1) and Home (weight 1, id 2), both eligible, counters starting at zero:

Four units delivered 3:1, counters returned to zero, and the pattern repeats exactly.

Rationale: this is a deficit round-robin and it produces a stable interleave — three north, one home, interleaved — rather than three units north followed by one home. Integer, exact, replayable, and it degrades sensibly when weights change mid-game because the counters carry the accumulated debt.

CM-1210 Counters MUST be authoritative game state (CM-180). A Posting created mid-game MUST start at counter zero; a deleted Posting's counter MUST be discarded.

Rationale for the clamp in CM-1190 step 2: without it, a Posting that is ineligible for twenty allocations accumulates twenty rounds of credit and then absorbs the next several units in a burst the player did not ask for. Clamping to the current eligible weight sum bounds the catch-up to a single allocation, which is the intended "you were owed one".

CM-1220 When E is empty, the producing city's surplus rule MUST apply. The surplus rule MUST be one of ReserveAtSource (the unit adopts its type Doctrine and Postures Garrison on the producing city), OverflowTo(P) (allocated to P regardless of shortfall), or HoldProduction (the city's production queue pauses and raises a ProductionIdle Attention Event). The default MUST be ReserveAtSource.

CM-1230 A Posting anchored on a Formation MUST re-target its arrival destination only when that Formation's CRP has moved more than 5 tiles (Chebyshev) from the last target used. If the anchor Formation is deleted, the Posting's anchor MUST become the last target tile and a PostingAnchorLost Attention Event MUST be raised.

Rationale: without hysteresis a reinforcement stream chases a mobile army in circles and never arrives — the classic failure of "reinforce the front" automation. Five tiles is roughly two turns of movement for the formation being chased, so the stream re-aims about as often as the front meaningfully moves and no more.

8.4 Requisitions

CM-1240 A Requisition MUST be an ordered table of rows, each carrying a unit-class key and an integer target count in [0, 99].

CM-1250 For each row the shortfall MUST be computed as target − (present + inTransit + committed), where present counts units with postedTo = P that have completed their arrival March, inTransit counts units with postedTo = P that have not, and committed counts in-progress production items in cities consigned to P whose output matches the row.

Rationale: counting in-transit and in-production units is what stops Requisition thrash. A front that is four short and has four on the road is not short, and a system that thought it was would build four more and then four more again.

CM-1260 A city consigned to Posting P MUST select its next build item as the buildable unit class matching the row with the greatest shortfall; ties break by lowest row index. Where no row's shortfall is buildable at that city, the city MUST fall through to the next row it can build, then to the surplus rule.

CM-1270 A production item already in progress MUST NOT be cancelled or retargeted because a shortfall changed. Rationale: a front oscillating between shortfall and surplus would otherwise make cities flip production every turn and complete nothing.

CM-1280 Editing a Requisition MUST NOT require touching any city, and MUST take effect at the next build selection in every consigned city.

CM-1290 The Requisition panel MUST display, per row, target, present, inTransit, committed and shortfall as integers.

CM-1300 The command layer MUST NOT impose any cap, tax, upkeep, or efficiency penalty that scales with the number of units, Formations, Groups, Postings or orders a player commands.

Rationale: command capacity is a tempting place to hide the anti-snowball brake the design direction asks for, and it is the wrong place. A brake there punishes the player for automating, which violates CM-050 and makes the whole subsystem a trap. Whatever visible brake the game needs belongs in logistics, upkeep, or territorial strain, where the player can see it and plan around it.

8.5 Templates

CM-1310 A city MUST support a production Template: a named, saved, ordered build list with an optional repeat flag, assignable to a city and to multiple cities at once.

CM-1320 Templates and Requisitions MUST coexist: a city with a Template MUST follow the Template; a city consigned to a Posting without a Template MUST follow CM-1260. A city MUST NOT be governed by both simultaneously.

CM-1330 The client MUST show, for every city, which of Template, Requisition, or manual queue is currently governing its production, in one word.

9. The interruption model

Automation is only as good as its behaviour when the plan breaks.

CM-1340 The engine MUST recognise exactly six interruption classes, with the behaviour and attention consequences in the table below. Each MUST be evaluated at the acting unit's activation, in the order listed.

CM-1350 Contact radius MUST be the acting unit's vision radius.

CM-1360 A contact MUST be considered to block the order when the enemy occupies a tile on the cached route within the unit's remaining movement, occupies a Screen line tile the unit was moving to cover, occupies the unit's Garrison place, or occupies a Survey candidate that scored highest.

CM-1370 An Opportunity MUST be detected only for the following, and the engine MUST NOT invent further categories without a commandLogicVersion bump:

CM-1380 Every Opportunity Attention Event MUST carry a precomputed candidate order that the player may accept verbatim in one action; accepting MUST push that order as a Task.

CM-1390 An interruption MUST NOT clear any level of the order stack except as CM-1340 states. Blocked in particular MUST suspend rather than cancel, so that clearing the obstruction lets the original order resume untouched.

9.1 Reflexes

CM-1400 The Reflex set MUST be exactly:

CM-1410 TakeCover tile selection MUST break ties by lowest movement cost, then lowest tile index, and MUST use the defensive value the combat specification defines for that unit class on that terrain.

CM-1420 A Reflex MUST NOT initiate an attack. Rationale: a reflex is the engine acting without the player having said anything about this situation; initiating combat there would be exactly the unsanctioned irreversible action CM-030 forbids.

9.2 Progress and the stall detector

CM-1430 The engine MUST evaluate progress for every unit at every activation, per the following definitions, and MUST record the result:

CM-1440 A unit that is not progressing for two consecutive turns MUST raise a Stalled Attention Event. The event MUST name the level that is not progressing and the specific reason.

CM-1450 A unit whose last activation was a no-op because its Posture is satisfied — a Hold unit standing on its tile, a settled Screen — MUST be recorded as progressing and MUST NOT raise Stalled.

CM-1460 Stall detection MUST be instrumented independently of the Attention Event: the engine MUST expose a per-turn count of units with no progress for ≥ 3 turns, for telemetry and for CI regression. Rationale: the guard itself can have bugs, and this failure mode is invisible without measurement.

10. Route policy and Banked Movement

CM-1470 A March MUST carry a cached route. The route MUST be recomputed at activation only when the cached next two tiles have become invalid — impassable, occupied beyond stacking, or outside the map.

Rationale: recomputing every activation is both wasteful and visually unstable; a unit whose path is recomputed constantly appears to change its mind, which reads as broken even when each recomputation is optimal.

CM-1480 Newly revealed terrain offering a cheaper route MUST trigger a reroute only when the improvement clears 25%, by the integer test newCost × 4 ≤ oldCost × 3.

Rationale: without hysteresis units oscillate as fog lifts. Twenty-five per cent is large enough that only a genuinely better route wins and small enough that a real road discovered halfway is taken.

CM-1490 A route MUST be recomputed at most once per activation. A second failure in the same activation MUST raise Blocked.

CM-1500 When no route to the next waypoint exists at all, the March MUST raise Blocked, MUST advance as far as the best partial route allows, and MUST remain suspended rather than cancelled.

CM-1510 Route cost comparison and path tie-breaking MUST use integer terrain costs and MUST break ties by lowest tile index, consistent with 03-architecture.md AR-750.

CM-1520 Waypoints MUST be consumed in order. A waypoint that becomes permanently unreachable — outside the map, or on terrain the unit's class may never enter — MUST be dropped with a Blocked event naming it; a waypoint that is temporarily unreachable MUST NOT be dropped.

CM-1530 A March route passing through unrevealed terrain MUST be planned under CM-140 and MUST be replanned on contact with the truth under CM-1480 and CM-1500.

CM-1540 The remaining route MUST be displayable on the map for any selected unit, including the portion planned through unrevealed terrain, which MUST be visually distinguished as provisional.

10.1 Banked Movement

CM-1550 A unit that halts on an Opportunity or a Blocked interruption with unspent movement MUST bank that unspent movement.

CM-1560 Banked movement MUST be added to the unit's normal allowance at its next activation only, MUST be capped at the unit's normal allowance (so a unit may spend at most twice its allowance in one activation), MUST NOT accumulate across more than one turn, and MUST be discarded unused at the end of that next activation.

CM-1570 Banked movement MUST NOT be granted for any other interruption class, and MUST NOT be granted twice for the same halt.

CM-1580 Banked movement MUST NOT alter the unit's Stance, initiative, reaction capacity, or exposure to opponents' reactions.

CM-1590 The unit panel and the Opportunity card MUST state the banked amount in movement points.

CM-1600 Rationale, stated normatively because the requirement above exists only to serve it: without banked movement, an automated unit that pauses to ask permission arrives one turn later than a hand-ordered unit that did not need to ask, and automation becomes a measurable tempo disadvantage — which fails CM-050 and, with it, the whole subsystem. The source design placed this as an out-of-order re-activation within the same turn; under Orders and the Cascade there is no player input during resolution, so the same guarantee is delivered by banking the movement forward. The unit reaches the same tile on the same turn it would have reached had it not stopped to ask, and no mid-Cascade prompt is required. The cap at one extra allowance bounds the effect to exactly the turn that was lost.

11. Attention Events and the Dispatch

With three hundred units, showing the player the five that need a decision is the more important half of this design.

11.1 Split of responsibility

CM-1610 The simulation core MUST emit Attention Events deterministically, each carrying: a class, a cause key (CM-1700), the affected entities, the integer terms S, T and A (§11.4), a plain-language summary, and an ordered list of offered resolutions.

CM-1620 The client MUST compute the presented ranking, apply the adaptive player weight P, deduplicate, bound, and present. The core MUST NOT compute P and MUST NOT order the Dispatch.

CM-1630 Automation logic MUST NOT depend on Attention Events in any way. A player who never opens the Dispatch MUST get identical unit behaviour to one who reads every item.

11.2 Properties of the Dispatch

CM-1640 The Dispatch MUST show at most 7 items, player-settable in [3, 15]. Everything below the cut MUST collapse into a one-line digest with per-class counts. Rationale: a list of forty alerts conveys the same information as no list.

CM-1650 Every presented item MUST carry at least one one-action resolution and a snooze. An item with no available action MUST NOT be presented as an item; it MUST be a digest line.

CM-1660 Items MUST be ranked by the integer Urgency score U = S + T + A + P, ties broken by lowest affected-unit creation sequence number.

CM-1670 Items MUST be sticky: an item MUST persist across turns until it is resolved, snoozed, or its underlying condition ceases to hold. A new turn MUST NOT clear the Dispatch.

CM-1680 An item whose condition ceases to hold MUST be retired and MUST appear once in the digest as retired, naming what happened.

CM-1690 Snoozing MUST suppress the item's cause key for a player-set number of turns, default 5, range [1, 20]. A snoozed cause MUST re-raise immediately if its S term increases by 30 or more since the snooze.

Rationale: the escalation override is what makes snooze safe. Without it, a player who snoozes "enemy scouts near the river" also snoozes the army that follows them.

11.3 Deduplication and the event catalogue

CM-1700 Every Attention Event MUST carry a cause key of (class, causeEntityId, causeTileClusterId). Items with equal cause keys MUST merge into one presented item.

CM-1710 A merged item's S, T and A MUST each be the maximum across its members, never the sum, and its affected-entity list MUST be the union.

Rationale: ten units contacted by one enemy column are one item — "enemy column of 6 at Ash Ford; 10 of your units in contact" — not ten. Taking the maximum rather than the sum is what stops deduplication from re-inflating the very thing it merged, which would defeat the purpose and put the merged item at the top of the list purely for being numerous.

CM-1720 The Attention Event classes MUST be exactly the following, with the stated default terms:

CM-1730 Opportunity S values MUST be: free city in reach 70; weak city adjacent 50; overwhelming odds 30; repair in reach 25.

11.4 The Urgency terms

CM-1740 S — Stake, in [0, 100] — MUST measure what is at risk or on offer, per CM-1720 and CM-1730. A city that may be lost MUST outrank a city that may be taken. Rationale: the loss is certain to matter and the gain may still be there next turn.

CM-1750 T — Tempo, in [0, 60] — MUST be assigned by when the matter resolves: 60 this turn, 40 next turn, 20 within three turns, 5 beyond that.

Rationale: tempo deliberately outweighs a large distant stake. A distant item will resurface; a decision that expires this turn will not.

CM-1760 A — Agency, in [0, 40] — MUST be computed from the number and kind of resolutions the item offers: 40 when it offers two or more resolutions whose immediate effects differ in kind (move, fight, abandon, build, produce); 20 when it offers exactly one non-trivial resolution; 5 when its only resolutions are acknowledge and snooze. The per-class values in CM-1720 are the normative defaults derived by this rule.

Rationale: Agency is the anti-noise term, and defining it by the offered resolutions rather than by an estimate of how much the outcome matters makes it objective and computable. It correctly demotes items where automation would have done the right thing anyway, because those items have nothing to offer but acknowledgement.

CM-1770 P — Player weight, in [−30, +30], default 0 — MUST be a per-class adjustment held client-side.

CM-1780 P MUST adapt: dismissing or snoozing a class three times without acting MUST decrement its P by 10, floor −30; acting on a class immediately three times MUST increment its P by 5, ceiling +30. The counters MUST reset whenever P changes.

CM-1790 Classes marked non-adaptable in CM-1720 MUST be exempt from CM-1780 entirely. Rationale: the game must never learn to stop telling you your capital is about to fall.

CM-1800 Adaptation MUST be enabled by default, MUST be disableable with a single setting, and every current P value MUST be visible in a settings panel with a per-class and a global reset.

Rationale: learned weights are powerful and slightly sinister, and the honest objection is that the game should not decide what you care about. The floor at −30 answers it directly — a class is demoted, never silenced — and the exemption protects the case where being wrong is unrecoverable. Default-on rather than opt-in because a feature whose entire value is that it quietly reduces noise is a feature nobody will ever go and switch on, and the visible panel plus reset makes the decision reversible the moment a player disagrees with it.

11.5 Worked ranking, normative as a test vector

CM-1810 The following ranking MUST be reproduced exactly by a conforming implementation given the stated terms:

Rationale: note where the idle scout lands. It is the item a traditional "cycle to next unit needing orders" key would present first, because it has the lowest unit index and is loudly demanding attention. Four integer terms correctly put it last.

11.6 The turn-end gate

CM-1820 Ending a turn with unresolved items above an urgency threshold MUST produce a warning and never a block, naming the count and the threshold: "3 items above urgency 120 unresolved — end turn anyway?"

CM-1830 The threshold MUST default to 120, MUST be settable, and MUST be disableable. Rationale: blocking is patronising; not warning is negligent.

CM-1840 The turn-end warning MUST be suppressible for the remainder of a game in one action, and that state MUST be per-player client state.

11.7 Multiplayer considerations

CM-1850 Attention Events MUST be generated per player from that player's fog-filtered view only, and MUST NOT reveal any entity, tile, or fact the player could not otherwise observe.

CM-1860 The Dispatch MUST NOT be an information channel: an item's existence, class, or terms MUST NOT be inferable by an opponent, and the client MUST NOT emit any network traffic whose timing or volume varies with Dispatch content.

CM-1870 Deduplication by cause key and the Agency term MUST be the only mitigations required against attention-flooding by an opponent generating many cheap contacts. Rationale: flooding a player's attention with cheap probes is a real vector and probably an emergent tactic; it may well be a legitimate one. It is worth watching rather than pre-emptively patched, and the two structural mitigations already blunt it.

12. Presentation contracts and audit

12.1 Command View

CM-1880 The client MUST provide a Command View zoom level at which individual unit icons are replaced by Formation and Group markers, each rendering a Posture glyph, a strength bar, an arrow showing current intent, and any Dispatch pins in that area.

CM-1890 Every Dispatch item MUST pin to a map location. Hovering an item MUST move the camera to it; resolving an item MUST return the camera to where it was.

CM-1900 Command View MUST be usable to issue every Formation, Group, and Posting order without leaving it.

Rationale: on a very large map individual unit icons are meaningless, and this is not a nicety — it is the only zoom level at which a late-game empire is legible at all. It is also the tie that keeps the Dispatch from becoming a list a player reads instead of looking at the map.

12.2 Next intended action

CM-1910 Every unit under a Posture MUST display one plain-language line stating its next intended action and its Engagement clause, for example: "Will move 4 tiles toward Rill Ford; will not engage."

CM-1920 The next-intended-action line MUST be a pure function of the unit's committed order stack and the owner's knowledge view. It MUST NOT simulate opponents and MUST NOT predict combat outcomes beyond the predictor of CM-150.

CM-1930 Where the line cannot be computed — an order whose next step depends on a contact not yet made — it MUST say so explicitly rather than being blank.

12.3 The audit trail

CM-1940 Every automated action MUST emit a CommandDecisionRecord carrying: the unit id, the turn and activation index, a snapshot of the order stack, the Sanction clause that permitted the action, every integer input to the decision (predicted per-mille, candidate scores, thresholds, movement costs), the chosen option, and the runner-up option with its score.

CM-1950 A CommandDecisionRecord MUST be retrievable from the UI for any automated action for at least the 20 most recent turns, and MUST be retained for the whole game in a replay.

CM-1960 The record MUST be renderable as one sentence naming the clause and the numbers, in the form of CM-600.

Rationale: this is a trust feature for players and, not incidentally, the best debugging tool the team will have. It is what converts a bad automated outcome from "the automation is broken, I will never use it again" into "the threshold was too low, I will raise it" — which is the difference between a subsystem players adopt and one they abandon.

CM-1970 CommandDecisionRecords MUST NOT contribute to the canonical state hash and MUST be reproducible from a replay rather than stored in the order log.

12.4 Progressive disclosure

CM-1980 On first exposure the client MUST present Sanctions only as the three named presets of CM-750, and MUST reveal the four individual dials at a disclosure tier the player can also enable immediately.

CM-1990 Formations, Groups, Postings and Requisitions MUST each be independently disclosable, and the game MUST be fully playable with none of them enabled.

CM-2000 Where automation declines an action, the message MUST teach the reason in numbers — "stopped because sanctioned at ≥700‰; predicted 610‰" — rather than stating that it stopped.

13. Absent players, persistence, and versioning

CM-2010 In absent-player mode — a correspondence turn nobody attended, a disconnected live player, or an explicit away setting — automated units MUST resolve normally, units with no Posture MUST adopt their Fallback Posture for that turn only, and Dispatch items MUST persist to the player's next session rather than being consumed.

CM-2020 A unit that adopted its Fallback Posture under CM-2010 MUST NOT have its stored Posture changed, and MUST raise no Attention Event for having done so beyond a single per-turn digest line.

CM-2030 Order stacks, Sanctions, Doctrines, Formations, Groups, Postings, Consignments, Requisitions and allocation counters MUST survive save, load, replay, and a switch between play modes without alteration.

CM-2040 All of the above MUST be expressible as ordinary orders in the authoritative order log. The command layer MUST NOT introduce any state that reaches the simulation by a path other than the order log.

CM-2050 Automation behaviour MUST be versioned with the ruleset by an integer commandLogicVersion recorded in the replay header and in every save.

CM-2060 Any change to a Posture algorithm, a Sanction test, a tie-break, a threshold, a default, the Reflex set, the interruption table, or the allocation scheduler MUST bump commandLogicVersion.

CM-2070 A replay whose recorded commandLogicVersion differs from the build's MUST be replayed under the recorded version where that version is available, and MUST be reported as incompatible rather than replayed approximately where it is not.

Rationale: because automation must be deterministic and core-side, changing how a Screen picks its tile is a balance change and it breaks replay compatibility. That is the price of automation that cannot cheat, and the versioning is how we pay it honestly instead of discovering it as a desync three releases later.

CM-2080 Attention Event generation MUST be versioned separately by an advisoryVersion, and a change to advisoryVersion alone MUST NOT invalidate a replay.

14. Performance and scale bounds

CM-2090 Command-layer evaluation for one unit's activation MUST complete within a bounded candidate set: Screen, Survey, TakeCover and Withdraw MUST each evaluate at most 256 candidate tiles, selected by ascending movement cost then ascending tile index and truncated at that bound.

Rationale: an unbounded search over a leash radius on a very large map is the one place this subsystem could quietly become the frame budget. Truncating a deterministically-ordered list keeps the bound and keeps the determinism, and 256 tiles is more than a Leash of 12 can reach for any movement allowance in the expected roster.

CM-2100 The command layer MUST resolve 400 units' activations, including all Posture evaluation, Sanction tests, projection and interruption handling, within 50 ms on the project's reference hardware, excluding pathfinding, which is bounded by 03-architecture.md AR-750.

CM-2110 Route caching MUST be the default: an activation that does not invalidate its cached next two tiles MUST perform no pathfinding.

CM-2120 Requisition shortfall computation MUST be incremental: a unit's creation, arrival, death, or re-posting MUST update the affected rows in constant time rather than triggering a scan.

CM-2130 The Dispatch MUST rank and present within 16 ms for up to 200 concurrent live Attention Events.

15. Contracts on other documents

These are obligations this specification places on subsystems it does not own. They are recorded here so that a change on either side is detectable.

CM-2140 10-turn-model.md MUST provide: a unit's activation index within the current Cascade, readable during that Cascade, so that Intent Freshness (CM-960) can distinguish members activating before and after their commander; the creation sequence number as a totally-ordered tiebreak available to both core and client; and a definition of Stance whose values the derivations in §4 can target. It MUST also guarantee that a unit under a Posture occupies its activation slot, resolves, and yields without any player prompt.

CM-2150 The combat specification MUST provide the deterministic per-mille win predictor of CM-150 and CM-160, evaluated over a fog-limited knowledge view, identical to the value shown to a player before a manual attack; a per-terrain defensive value for CM-1410; and a capture-probability prediction for CM-1370.

CM-2160 Where the combat specification allows co-ordinated attacks to combine, the combination MUST key off physical adjacency and timing, never off Formation or Group membership, so that a hand-ordered set of units achieves an identical result. Rationale: this is what lets CM-060 forbid a formation combat bonus without forbidding combined arms.

CM-2170 The units specification MUST provide, per class: movement allowance and movement class, vision radius, current and maximum strength, whether the class may occupy a city, and optionally a command rating which, where present, replaces the default span of 8 in CM-850.

CM-2180 The economy specification MUST provide: a city production queue that does not cancel a committed in-progress item (CM-1270); critical and restore thresholds for supply, fuel and ammunition for the Replenish Reflex; repair and resupply site locations; and unit cost for the S terms in CM-1720.

CM-2190 The economy specification, and not this one, MUST own any visible anti-snowball brake the design requires. CM-1300 forbids placing it in command capacity.

CM-2200 04-ui-ux.md MUST own the presentation of the Command View (CM-1880), the unit and Formation panels, the Dispatch surface, and the progressive-disclosure tiers of §12.4, implementing the content requirements this document states.

Open questions

1. Is the Screen coverage heuristic good enough? CM-460 is defined precisely enough to build, but whether it feels like a screen — whether units spread the way a player would place them — is unknowable without playing it. This is the highest-risk piece of automation logic in the document, and the hysteresis constant of 2 and the 256-candidate truncation are the two values most likely to need retuning.

2. Does Seize: Undefended defaulting on cause regret? CM-710 argues that all competent players take a free city, so it is arithmetic. But capturing reveals your position and creates a garrison obligation, and CM-730 makes that obligation concrete. If playtest shows players routinely turning it off, the default is wrong and the Opportunity card plus Banked Movement is the better answer on its own.

3. Is adaptive P right as a default? CM-1800 decides default-on with a floor, an exemption, and a visible reset. The opposing case — that a game quietly learning what you care about is unwelcome regardless of guardrails — is not refuted by anything here, only guarded against. The measurement that would settle it is whether players who leave adaptation on dismiss fewer items over a hundred turns than those who turn it off.

4. Is a soft warning at 13 Postings the right cap? CM-1150 warns and never blocks. It is possible that the real answer is not a cap at all but a Posting hierarchy, which this document has deliberately refused on the same grounds as the two-echelon limit.

5. How large should the conditional vocabulary become? The Task end conditions of CM-260 are five, and the Postures six. The turn-model design flags conditional expressiveness as the design's largest execution risk. This document's bet is that Sanctions carry the conditionality that would otherwise need a condition grammar. If playtest shows players trying to express conditions that no Posture-plus-Sanction combination reaches, the answer is a sixth and seventh Task end condition rather than a general expression language, because a general grammar cannot be shown on a unit panel and CM-320 requires that it can.

6. Should a Formation be able to hold Garrison? CM-870 says no, on the grounds that a formation garrisoning several places is a Posting with extra steps. A player defending a cluster of four cities with one command object may disagree.

7. What is the right retention for CommandDecisionRecords outside a replay? CM-1950 says 20 turns. That is a memory decision as much as a design one, and the number should be revisited once the record's actual size is known.

8. Does the Van role's forced Defend/Cautious (CM-910) need an escape? A player who wants an aggressive vanguard currently cannot have one without removing the role. The counter-argument is that an aggressive vanguard is simply a Main element placed forward, which the vocabulary already expresses.