Skip to main content
Lineage

The Advisor (Steward / Recommended-Actions Layer)

The Advisor (Steward / Recommended-Actions Layer)

Status: IMPLEMENTED 2026-07-17 (Phase 1 of the vision build path).

Last updated: August 30, 2026

Blood Lineage — The Advisor (Steward / Recommended-Actions Layer)

Status: IMPLEMENTED 2026-07-17 (Phase 1 of the vision build path).

Parent: index.md. Governed by: vision.md § "The advisor: structured complexity for everyone" (the north-star spec this doc implements) and empire-4x-layer.md § "The seven rules every new 4X surface MUST obey" (the voice-memory-load budget every recommendation is bound by). Sibling of pacing.md.

Why this doc exists

vision.md names the advisor as the single highest-leverage Phase-1 addition: a Steward the player can consult at any time who reads live kingdom state and recommends the highest-value next action. It is the structured on-ramp (a newcomer leans on it and plays a solid game) that pairs with the dynamic on-ramp (a player who drives the story themselves — reads factions, times wars, min-maxes — earns more). Firsthand play confirmed the gap directly: what should I do next answered "That command is not available"; recommend an action NLU-fell-back. Onboarding said "recruit units" while recruit 10 warriors replied "You need to create an army first" — an undiscoverable prerequisite that is a large share of the ~60% turn-1–5 churn cliff. This doc is the implementable spec that closes both gaps with one read-and-recommend layer over existing state.

The state signals the advisor reads

All state is read, never mutated. Every signal below already exists on LineageKingdom / LineageWorld / LineageGameMapData — no new fields, tables, or currencies (voice-memory rule 3).

Signal Source Used for
Current turn LineageWorld.getCurrentTurn() Act-aware framing (I/II/III)
Food stockpile vs. consumption; consecutive zero-food turns LineageKingdom.getResourceAmount("food"), getPopulation()/2, getConsecutiveZeroFoodTurns() FOOD_DEFICIT (top-priority crisis)
Idle vs. assigned workers LineageKingdom.getIdleWorkers(), getTotalAssignedWorkers() NEVER_ASSIGNED_WORKERS / IDLE_WORKERS
Armies for this kingdom + their total unit count .getArmiesForKingdom(mapData, kingdomId), LineageArmy.getTotalUnitCount() NO_ARMY / SMALL_ARMY
Owned territory count mapData.getTerritories() filtered by ownerKingdomId NO_TERRITORY / GROW_TERRITORY
War status + rival capital location mapData.areAtWar(kingdomId, rivalId), , kingdom.getCapitalTerritoryId() + mapData.getTerritoryById AT_WAR (points at the reachable enemy capital)
Stability LineageKingdom.getStability() STABILITY_LOW
Current research LineageKingdom.getCurrentResearchId() NO_RESEARCH

No new state is minted. The advisor is purely a read-and-rank layer, which is why it is low-risk (vision.md § Build path, Phase 1 rationale).

The ranking (highest-value next action, capped at 3)

Candidates are evaluated in a single fixed priority order; the first three whose condition is true are spoken. This order encodes the design intent directly:

  1. FOOD_DEFICIT — food stockpile has hit zero for ≥1 turn, or the stockpile is already below one turn's consumption. "On a food deficit it says fix it first" (vision.md, verbatim). Always ranks above onboarding and war — a starving kingdom cannot fight or build.
  2. NEVER_ASSIGNED_WORKERS — idle workers exist and none have ever been assigned. The first rung of the onboarding ladder (naming → workers → army → territory).
  3. NO_ARMY — the kingdom has raised no army. The second onboarding rung.
  4. NO_TERRITORY — the kingdom owns only its capital (≤1 territory). The third onboarding rung.
  5. AT_WAR — the kingdom is at war with a rival whose capital location is known or discoverable. "In a war it points at the reachable enemy capital" — the recommendation names the rival, the compass bearing (reusing the same compass-label logic as the LOCATE command), and offers the LOCATE command as the handoff so the player can always re-ask for the exact bearing.
  6. STABILITY_LOW — stability has fallen below 40. Names the concrete lever (garrison a restless province, build a Temple), mirroring the existing dark-times advisory in .
  7. IDLE_WORKERS — idle workers remain but some are already assigned (a steady-state nudge, not the onboarding-teaching phrasing of #2).
  8. SMALL_ARMY — an army exists but its total unit count is below a "meaningfully defended" floor (15 units). Recommends recruiting more, distinct wording from NO_ARMY so a mid-game kingdom is never told to "create" an army it already has.
  9. NO_RESEARCH — no research is currently underway.
  10. GROW_TERRITORY — the kingdom owns a modest 2–4 territories (past onboarding, still small) — recommends claiming more to grow the economy.
  11. ENHANCE_TERRITORY — always-eligible catchall (owns ≥1 territory) so a late-game kingdom with no other candidate never returns an empty list; recommends enhancing a territory for production.

Onboarding (#2–#4) is evaluated in the exact vision.md sequence — workers, then army, then territory — so a brand-new ruler who has done nothing yet hears all three in that order (capped at 3, so this is also the natural "teach the whole loop" moment for a fresh kingdom). Once any step is completed it drops out of the candidate list on its own (no separate "Act I" gate is needed to suppress it — the state check IS the gate). AT_WAR and STABILITY_LOW naturally never fire before the kingdom exists long enough to be at war or unstable, so they never compete with onboarding in practice.

Act-aware framing (not act-gated ranking)

The candidate ranking above is identical in every Act — a food deficit is always fixed first, a war is always pointed at, regardless of turn number. What changes by Act is the opening frame, read from LineageWorld.getCurrentTurn() against the vision.md Act bands (Act I 1–25, Act II 26–70, Act III 71–~100):

Act Turn band Opening frame
I — Founding 1–25 Teaching tone: "Your steward counsels a new ruler:"
II — Ascendance 26–70 Strategic tone: "Your steward weighs the realm's next move:"
III — Reckoning 71+ Urgent tone: "Your steward counsels haste — the reckoning nears:"

This is a cosmetic framing layer only (one opening clause) — it does not gate which recommendations are considered, so it does not require the full three-act campaign-shape system (vision.md Phase 2) to be built first. It composes cleanly with Phase 2 landing later: the turn-band Act detection here can be swapped for the real Act state without touching the ranking logic.

The safe-but-less-optimal framing (the two-on-ramp promise)

Every advisor response ends with one short, fixed clause making the vision's "two on-ramps" promise explicit and never overstating the steward's counsel as optimal play:

"This is your steward's safe counsel — a ruler who reads the realm and times their own moves may fare even better."

This is the literal implementation of vision.md's "The steward plays safe and solid; the player who ignores it and plays sharp wins bigger and faster. Both are legitimate ways to finish." It is a single clause (not a paragraph) so it never violates the adaptive-length rule, and it is invariant across Acts and recommendation content — the player always knows the advisor is the floor, not the ceiling.

The seven voice-memory rules, applied

Rule How the advisor satisfies it
1. Push the urgent, pull the rest The advisor is 100% pull-on-demand (advise me, what should I do, counsel, what do you recommend, recommend an action) — it never injects itself outside a) an explicit ask or b) the bounded turn 1–3 onboarding hint (below), which replaces an existing static tutorial line rather than adding a new push.
2. Re-readable on request Asking again always re-computes from live state — nothing is cached or must be remembered between asks.
3. Reuse existing numbers Every signal above is an existing field; no new currency, no new menu tree.
4. Cap concurrent decisions at 3 At most 3 recommendations are ever spoken (rankRecommendations truncates to MAX_RECOMMENDATIONS = 3).
5. Adaptive length Each recommendation is one short sentence; the whole response (framing + ≤3 lines + safe-but-less-optimal clause + handoff) stays brief regardless of state complexity.
6. Suppress empty sections A signal with a false condition contributes nothing — there is no "no threats" filler the way the empire screen has (the ranking itself is the suppression).
7. Ends with an actionable handoff Every recommendation renders its own directly-actionable option (e.g. "assign workers", "create army", "locate enemy capital") via the SAME action/key/synonyms the underlying command already uses, plus the standard "take command" / "end turn" navigation — never a text-only dead end.

Onboarding wiring (Act I, the churn-cliff fix)

already shows a turn-1–3 tutorial hint (generateTutorialGuidance). Before this change it was a static, turn-indexed script: turn 3 said "recruit units and claim territory to expand" — the exact undiscoverable-prerequisite bug named in vision.md's firsthand-play notes (recruiting fails with "You need to create an army first" when no army exists yet). generateTutorialGuidance now delegates to , which reuses the SAME ranked-candidate logic as the full advisor screen and returns just the top candidate's one-line text (or null once the player has outgrown all onboarding/crisis signals within the turn ≤3 window, in which case no hint is shown). Because the ranking is state-based, not turn-indexed, it can never again recommend "recruit units" before an army exists — NO_ARMY always ranks ahead of SMALL_ARMY's recruit-more phrasing, and the onboarding sequence is workers → army → territory in that fixed order. This directly targets the ~60% turn-1–5 churn cliff: a brand-new ruler who does nothing but follow the turn 1–3 hints (or explicitly asks the steward at any point) reaches their first assigned workers, first army, and first claimed territory without ever being told to do something the game will then refuse.

NLU

what should I do, advise me, counsel, what do you recommend, recommend an action, and close variants (what should I do next, what do you suggest, give me advice, ask my steward, what now, what next, steward's advice) route to LINEAGE_VIEW with key ADVISOR via a dedicated ADVISOR_PATTERN in (Tier 4), matching the existing VIEW_SCREEN_PATTERN / LineageViewType dispatch convention used by the resource screen, Legacy, Empire, and Chronicle screens. LineageViewType.ADVISOR carries the canonical key plus COUNSEL / STEWARD aliases.

Regression shape (hermetic)

Per hermetic-scenario-tests.md, each test self-seeds its precondition via a command chain (kingdom naming is a forced VALUE_ENTRY, so every chain opens name my kingdom <X>; yes) and asserts STABLE STRUCTURE, never RNG/clock-dependent prose:

State Command chain (abridged) Structural assertion
Fresh kingdom name my kingdom <X>; yes; advise me Renders the 3 onboarding recommendations (workers, army, territory) + the STATUS handoff option
Mid-game ...; assign 10 workers to gold; create army; claim territory; advise me Onboarding items absent (no "create army" recommendation); steady-state recommendations (idle workers / small army / research) + handoff
War ...; declare war; 1; advise me An AT_WAR recommendation naming the war state, plus the handoff

War declaration targets the picker's numeric index (1), never a randomly-generated AI kingdom name, so the test is deterministic across runs regardless of world-init name randomization.