> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/game-design/08-production-roadmap-and-phase-a-spec.md).

# Production Roadmap And Phase A Spec

**Project:** FactionOS — The War Effort **Document role:** Production roadmap / vertical-slice feature spec

## 13. Build Order (fun-per-engineering-hour, descending)

1. **Phase A — "The Legion Awakens":** issue→Blight-camp rendering on the board + wraith-on-error + camp-burn on quest completion, **plus the live skirmisher/ram/gremlin tier** (`test_failure`/`test_pass`, `build_error/fix`, `ts_errors`/`lint_error` events already stream — near-zero data work) and **combat playback** (§5A: mission events strike the linked camp; pure presentation over the existing stream). (Quest Board data + battlefield DOM; highest fun density, mostly presentation.) *Phase A prerequisite:* stand up `gameProjection.ts` (§15/§15A) first — thin at first (camps + legion only), grown per phase, never bypassed. *Buildable spec:* §13A (layers, visuals, SFX, acceptance criteria).
2. **Phase B — "Banners & XP":** mission-complete banner planting, XP/levels/ titles from existing metrics, Battle Report reskin of SessionRollup, **plus the fourth-pass decision/stakes layer** — War Council objectives with the declared-vs-achieved Battle Report ledger (§4B), the War Tide meter (§4), and the class-advantage muster hook (§6A; pure derivation over heroSpecialization × quest tags).
3. **Phase C — "The Living Map":** directory sectors, fog push/reclaim, building levels from cumulative stats.
4. **Phase D — "Loot & Legends":** loot rolls, tome expansion, relics, Hall of Banners, hero quirks, **Named Nemeses** (§10 promotion rule — rides the enemy state Phase A already tracks; relic + title on verified kill).
5. **Phase E — "The Alliance War":** shared front rendering, campaign boss HP bars, faction league.
6. **Phase F — "Seasons & Saga":** prestige cycle, chronicle, Blight Titan.

Each phase is independently shippable and independently fun.

## Generated Asset Handoff

`manifest.md` is the source of truth for production-generated visual assets. The files below are already present and should be checked before generating new art for the corresponding roadmap phase. They are not runtime-wired until the implementing phase records consuming paths, fallbacks, accessibility, cache/mirror behavior, and provenance.

| Roadmap area                        | Already-present generated assets                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Phase A - The Legion Awakens        | Current runtime stays CSS/DOM-first until promotion, but source sheets already exist: `assets/generated/game-design/phase03/live-enemies/live-enemy-effects-sheet.png`, `assets/generated/game-design/phase03/strike-vocabulary/strike-vocabulary-effects-sheet.png`, `assets/generated/game-design/phase03/reduced-motion/reduced-motion-static-badges-sheet.png`. Later siege escalation may reuse `assets/generated/game-design/phase09/siege/siege-set-piece-static.png` as a static twin.                                                                                                 |
| Verb/command/toast ceremony support | `assets/generated/game-design/phase04/town-crier/town-crier-toast-chrome-sheet.png`, `assets/generated/game-design/phase04/command-ceremony/command-ceremony-props-sheet.png`                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Phase B - Banners & XP              | `assets/generated/game-design/phase05/banners-regalia/banners-regalia-sheet.png`, `assets/generated/game-design/phase05/class-icons/class-icons-and-flares-sheet.png`, `assets/generated/game-design/phase06/battle-report/battle-report-frame.png`, `assets/generated/game-design/phase06/war-council/war-council-objective-board.png`, `assets/generated/game-design/phase06/war-tide/war-tide-meter-sheet.png`, `assets/generated/game-design/phase06/dawn-report/dawn-report-recap-backdrop.png`, `assets/generated/game-design/phase06/onboarding/first-ten-minutes-onboarding-sheet.png` |
| Phase C - The Living Map            | `assets/generated/game-design/phase07/territory-map/territory-map-base.png`, `assets/generated/game-design/phase07/home-sector/home-sector-building-dressings.png`                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Phase D - Loot & Legends            | `assets/generated/game-design/phase08/loot/loot-roll-visuals-sheet.png`, `assets/generated/game-design/phase08/tomes/tome-expansion-art-sheet.png`, `assets/generated/game-design/phase08/relics/relic-set-art-sheet.png`, `assets/generated/game-design/phase08/hall-of-banners/hall-of-banners-gallery-backdrop.png`, `assets/generated/game-design/phase08/hero-quirks/hero-quirks-palette-sheet.png`, `assets/generated/game-design/phase08/nemesis/nemesis-presentation-sheet.png`                                                                                                        |
| Phase E - The Alliance War          | `assets/generated/game-design/phase10/alliance-war/alliance-war-visuals-sheet.png`, `assets/generated/game-design/phase09/bosses/null-sovereign-world-boss-standee.png`, `assets/generated/game-design/phase09/bosses/null-sovereign-world-boss-standee-chroma-source.png`, `assets/generated/game-design/phase05/banners-regalia/banners-regalia-sheet.png`                                                                                                                                                                                                                                   |
| Phase F - Seasons & Saga            | `assets/generated/game-design/phase11/seasons-saga/seasons-saga-visuals-sheet.png`, `assets/generated/game-design/phase09/bosses/blight-titan-standee.png`, `assets/generated/game-design/phase09/bosses/blight-titan-standee-chroma-source.png`, `assets/generated/game-design/phase08/hall-of-banners/hall-of-banners-gallery-backdrop.png`, `assets/generated/game-design/phase09/siege/siege-set-piece-static.png`                                                                                                                                                                         |
| War Games and demo hardening        | `assets/generated/game-design/phase12/war-games/war-games-demo-presentation-sheet.png`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

### 13A. Phase A — "The Legion Awakens" to buildable detail (third pass)

**Scope.** Camps, wraiths, live skirmisher tier, combat playback, camp burn-down. Data: `suggestion_update` snapshots + live events already in `events.ts`. State: the §15A projection with only `legion`, `pendingLinks`, `campLinks`, `alertFocus`, `lastEventAt` populated. No territory, XP, or essence yet.

**Board-internal DOM layers** (inside `Battlefield.tsx`; *not* `overlayLayers`, see §15 correction), bottom → top:

1. Board art + existing grid/vignette (shipped).
2. **Camp layer** — camp markers, below hero tokens so heroes read as the foreground army. Each camp is a native `<button>` with an accessible name ("Blight fort: 12 issues in apps/web") — clicking opens the Quest Board filtered to its `issueIds`. Position: stable hash of the camp's dominant directory into the §5B grid cell, same clamp helper as heroes.
3. Hero token layer (shipped, untouched).
4. **Effects layer** — `pointer-events: none`; strike flashes, wraith wisps, combo stages. Concurrency-capped with timer cleanup, mirroring the shipped `CELEBRATION_MAX_CONCURRENT` pattern exactly.
5. **Alert pulse** — the single `alertFocus` ring (§14.6), rendered around whichever DOM node owns the focus.

The existing empty-terrain clear-selection button stays underneath; camps join heroes in the keyboard tab order.

**Visuals (v1 = CSS only, zero new art):**

| Element                    | Motion variant                                                                                                                                    | Reduced-motion / static twin                                       |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Camp / fort / citadel      | CSS tent-cluster silhouette (existing palette), fire flicker, size by tier; HP bar drains on linked strikes                                       | Static marker + numeric HP chip; tier by size only                 |
| Camp kill (quest verified) | Burn-down + existing celebration burst + faction `celebration` bark                                                                               | Marker swaps to "razed" state badge, then fades next scan          |
| Wraith                     | Translucent dark wisp (radial-gradient + blur) hovering near its hero; stack darkens it                                                           | Static wisp icon + stack-count badge                               |
| Skirmisher                 | Small red slash marker at board edge, tooltip = test path; green fade on pass                                                                     | Red badge with count; green check state on pass                    |
| Ram (build\_error)         | Battering ram at keep gate, slow rock; `build_fix` = collapse                                                                                     | Gate shows "cracked" state chip; fix clears it                     |
| Gremlins                   | Count chip on the keep ("⚙ 14"), subtle jitter                                                                                                    | Same chip, no jitter                                               |
| Strikes (linked mission)   | Edit/Write = hammer flash on camp; Bash = fire puff; Read/Grep = tightening scout ring; Task = peon flank spark; ≤400ms each; §14.4 combo merging | Camp HP chip ticks + a "last strike: Edit" micro-badge on the camp |
| Scrying posture (§14.1)    | Slow rune-circle pulse under a silent-but-active hero                                                                                             | Static "channeling" state badge (joins the existing badge set)     |

**SFX plan.** The shipped 25-cue map is `BarkKind` (`idle/active/complete/error/celebration`) × 5 factions — *hero voice*, not world sound. Phase A reuses barks where the hero is the actor: `error` bark on wraith spawn, `celebration` bark + burst on camp kill, `complete` on the linked mission's end. New **world cues** (add to the synthetic-sound-map brief; faction-agnostic): camp-hit thud, camp-collapse, ram-crash, ram-break-triumph, skirmisher red-slash sting, flare attention sting. Until recorded, all six route through the existing oscillator-synth fallback (the same posture already used for unvoiced factions), each subject to the §14.4 rate limiter.

**Acceptance criteria — "is it fun" is testable:**

1. **Glance test:** show a cold viewer the board for 1 second → they can classify the war as *calm / fighting / needs-you* (alertFocus visible).
2. **Cause test:** watching beside a live session, a viewer narrates what the agent is doing from board motion alone (reading vs editing vs running commands) for ≥80% of strikes.
3. **Kill-latency test:** a real failing test spawns its skirmisher ≤5s after the event; fixing it clears the marker ≤5s after the pass; `build_fix` kills the ram on arrival.
4. **Silence test:** 10 event-free minutes → board still passes the glance test, shows scrying/ambient state, and emits zero urgency signals.
5. **Honesty test:** loading a shared replay link or reconnecting changes no persisted projection numbers (§14.9); camp kills require `task_verification`.
6. **Fatigue test:** a 45-minute continuous mission never repeats an identical SFX >N/min and strike visuals merge into combo stages — no strobe, no mute-the-tab impulse (self-report from dogfooding).
7. **Reduced-motion parity:** criteria 1–5 pass with animations disabled, using only the static twins above.
8. **Fun Law 1 audit:** every rendered game element can be clicked/inspected through to its real source (camp → Quest Board issues, skirmisher → test path, wraith → hero error) — no orphan fiction on the board.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/docs/game-design/08-production-roadmap-and-phase-a-spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.