> 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/11-open-questions-and-change-log.md).

# Open Questions And Change Log

**Project:** FactionOS --- The War Effort **Document role:** Decision log / open questions / change log

## 16. Open Questions (for future sessions)

* ~~Session-to-session **persistence** of game state~~ --- answered in Sec. 15A: v1 is `localStorage["factionos-game-v1"]` with the shipped replay-buffer debounce pattern (safe because the projection is derived, aggregates-only); hosted/cross-device rides `hostedPersistence` posture in a later phase.
* **Multi-repo identity:** how do fronts federate when a hero roams cwds?
* **Headless messaging as gameplay:** "rally orders" --- sending a prompt to an idle hero from the map (orchestration intake exists; frame as the Warchief's command tent). What are the guardrail-approved verbs?
* **Score visibility in War Room:** what's shareable under redaction rules?
* **Lobster faction content debt:** no app click voice lines yet; the hidden faction should feel *most* premium when unlocked. Decide whether to promote the public-demo `claw-*` clips into app runtime with catalog/parity evidence or commission a new lobster voice set.
* **Bark SFX target:** whether the 25-cue bark target means "file-backed by any source" or "dedicated bark SFX for every faction and kind." The answer decides whether speech-backed error cues are acceptable long term.
* **Class bark modality:** whether class barks are recorded voice, short nonverbal SFX, or text-only ceremony paired with existing faction barks.
* **Future visual implementation policy:** whether Phase 7 buildings and later map/ceremony states stay pure DOM/CSS with generated-source references, or graduate selected pieces into browser-loaded generated image assets through the promotion gates.
* ~~Whether the **public demo** gets a synthetic Legion~~ --- answered in Sec. 5B: yes, a scripted synthetic front, following the existing demo-parity pattern.
* **Essence tuning:** income rates per tool class, burst-window decay curve, treasury cap, tithe cadence (Sec. 7A) --- needs playtest feel, not more design.
* **Combat playback readability at 12 heroes:** partially resolved by the single-pulse `alertFocus` rule (Sec. 14.6) and per-sector camp coalescing (Sec. 14.3), which bound simultaneous battle *sites* to a handful. Still open: the "focus battle" affordance (click a camp -> other strikes dim) --- decide during Phase A dogfooding, not before.
* ~~Camp-mission linkage plumbing~~ --- answered in Sec. 5A (third pass): the missionTags assumption was wrong (client-side regex inference, no stored field), but the accept flow's returned verbatim `prompt` + `heroId` matched against `mission_start`'s verbatim `Mission.prompt` gives a deterministic link with zero protocol change.
* ~~Dawn Report composition~~ --- answered by code inspection (third pass): the sequencer **exists** --- `replayLink.ts#dispatchReplayEntries` already does cadence-scaled dispatch with gap capping and a replaying-flag guard; reuse it verbatim. But the raw replay buffer **cannot** be the source: it persists only the last 100 events (`REPLAY_PERSIST_CAP`) and captures nothing while the cockpit is closed. So the Dawn Report is *synthesized*: a pure composer diffs the persisted `gameProjection` snapshot against fresh hydration (`roster_update`, `mission_state`, `suggestion_update` `generatedAt`s, scroll/achievement state, `warroom_pending_catchup`) and emits an ordered list of synthetic recap entries for `dispatchReplayEntries` to play. `SessionRollup`'s `sessionStats()` is reusable for the closing stats card. New work = the composer + a small recap-event vocabulary the presentation layer understands.
* **Recap-event vocabulary:** the minimal set of synthetic Dawn Report beat types (camp-appeared, camp-razed, banner-planted, hero-idled, catch-up summary) --- design during Phase B when the Dawn Report ships.
* **Class-advantage tuning (Sec. 6A):** the affinity matrix pairings, bonus size (small enough to be a tiebreaker, never a scheduler), and whether affinity should be surfaced *before* muster (recommendation chip on the quest card) or only celebrated after --- playtest in Phase B.
* **War Council picker heuristics (Sec. 4B):** objective count (3 vs fewer for Champion Mode rosters), re-roll ceremony, and how the picker weighs severity vs. staleness vs. self-relative swift targets --- playtest, not more design.
* **War Tide window and weights (Sec. 4):** trailing window length (war day vs rolling hours) and gain/loss weights; must feel responsive without whiplash. Reduced-motion signed-chip formatting.
* **Nemesis name table (Sec. 10):** size and faction styling of the Legion name table; dedup guarantees when multiple nemeses are alive; whether slain nemeses enter the saga chronicle automatically (recommended: yes).

***

*Update log:*

* 2026-07-03 --- Initial full design: fun thesis, Null Legion, exchange table, four loops, territory, heroes, loot, alliance, anti-Goodhart, bosses, juice, build order. (Source-backed inventory from protocol + web libs.)
* 2026-07-03 (second pass) --- Objective improvements after code re-audit: (1) discovered live dev-health events (`test_failure`/`test_pass`, `build_error/fix`, `ts_errors`, `lint_error`, `loop_update`, `plan_budget_*`, `hero_evidence_update`, `idle_suggestion`, `file_intent_*`, `task_verification`) -> 10 new exchange-table rows + two-tempo Legion; (2) Sec. 3A Player Verbs --- enumerated all 11 real verbs, ceremony rule, `collect_scroll` as the one pure-game click; (3) Sec. 5A Combat Resolution --- "the fight is the stream," deterministic playback, camp HP semantics; (4) Sec. 5B Reality Constraints --- 12-hero cap/garrison, sector grid over the DOM positioning model, Legion floor for clean codebases, demo synthetic front; (5) Sec. 7A essence sinks (tithe + cosmetic treasury) fixing the sink-less economy flaw; (6) Sec. 4 additions --- Return Loop / Dawn Report and First Ten Minutes onboarding; (7) Sec. 15 Systems Wiring Map --- full existing-module -> game-system table + the single new module (`gameProjection.ts` pure reducer); (8) Sec. 12/Sec. 13/Sec. 16 updated accordingly.
* 2026-07-03 (third pass) --- Depth pass, code-verified: (1) Sec. 14 Boredom Audit (fixes the Sec. 14 numbering gap) --- nine stress-tested failure modes with adopted fixes: state-driven ambience + scrying posture, Champion Mode floor for 1---2 hero rosters, map legibility budget (sector cap + camp coalescing into camp/fort/citadel tiers), combo-strike escalation + SFX rate limits for 45-min runs, flare ceremony budget, single-pulse `alertFocus`, camp entrenchment -> Blight Titan pool + loot-less Banish, wraith stacking caps, and the replay/reconnect honesty guard (a real Fun Law 1 exploit found while sketching the reducer); (2) Sec. 5A + Sec. 16 camp-mission linkage RESOLVED against code --- the pass-two missionTags assumption was wrong (regex inference, no stored tags; Mission has no tag field); replaced with the verified accept-response verbatim-prompt match (`questBoardActions.ts` `send_prompt` response x `Mission.prompt`), zero protocol change; (3) Sec. 16 Dawn Report RESOLVED against code --- reuse `dispatchReplayEntries` as the sequencer; the replay buffer (100 persisted entries, capture only while open) cannot source overnight recaps, so a snapshot-diff composer synthesizes recap entries; `sessionStats()` reusable; persistence question also resolved (localStorage v1 per the shipped replay-buffer pattern); (4) Sec. 15A `gameProjection.ts` one level deeper --- full state shape, event->mutation table, purity/replay guards, persistence cadence; plus a wiring-table correction: `overlayLayers` is the cockpit-shell z-contract, battlefield game elements use board-internal stacking; (5) Sec. 13A Phase A buildable spec --- 5 DOM layers, CSS-only visual table with reduced-motion static twins, SFX plan (barks reused for hero-actor moments; six new faction-agnostic world cues via synth fallback), and 8 testable "is it fun" acceptance criteria; (6) Sec. 12 inventory + Sec. 13 build order updated accordingly.
* 2026-07-03 (fourth pass) --- Final fun-gap pass; four objective gaps found by a skeptical-designer sweep, each fixed with shipped substrate only: (1) **the decision gap** --- the verb set responded but never *chose*; added Sec. 6A Class Advantage (heroSpecialization x quest-tag affinity on the muster decision; advantage-never-gate guard; honest-by-accident context locality); (2) **the stakes gap** --- sessions had no declared goals; added Sec. 4B War Council (<=3 objectives *selected* from the real needed-work census, deterministic picker, buffs never gates, Battle Report opens with the declared-vs-achieved ledger); (3) **the drama/memory gap** --- recurring failures were anonymous; added Sec. 10 Named Nemeses (promotion rule over existing camp-scar/skirmisher/wraith state, deterministic naming, relic + "Bane of" title on verified kill, renames-only rule); (4) **the topline glance gap** --- alertFocus answered "is anything wrong?" but nothing answered "are we winning?"; added the Sec. 4 War Tide meter (advancing/holding/losing from real deltas, self-relative). Plus (5) Sec. 5A joint assault rendering defined for multi-mission camp links; (6) Sec. 15A projection extended (`warTide`, `council`, `nemeses` fields + mutation rows) with the class-advantage factor folded into the XP case; (7) Sec. 12 inventory, Sec. 13 build order (Phase B/D), and Sec. 16 open questions updated accordingly.
* 2026-07-03 (phase outline second pass, code-grounded) --- Doc 13 verified against the codebase: all 20 design-cited events confirmed in `events.ts`; Grounding Notes index + per-phase Code anchors added (new modules, touched files, shipped patterns to mirror). Key findings: projection lives in `apps/web/src/lib/` (useGameStore is 3,640 lines); `achievementCelebration.ts` is the board-effects pattern to copy; War Games' progress-inert guard must key off `mockEnabled` (mock events are wire-indistinguishable --- new caveat); `apps/server/src/lib/names.ts` grounds the nemesis name table; heroes' recorded cwd grounds multi-front; Phase 11 is where projection persistence graduates to `hostedPersistence.ts`.
* 2026-07-03 (implementation phase outline) --- Added `13-implementation-phase-outline.md`: the full design package sequenced into 12 implementation phases, each sized to \~one 800k-token agentic session (one coherent vertical slice with tests, docs, and Fun-Law audit inside the same window). Refines doc 08's fun-ordered A---F build order; includes the fourth-pass systems (War Council, War Tide, Class Advantage, Nemeses, joint assault) and the graduated hold-outs (Dispatch Scouts, Emissary, War Games). README doc map updated.
* 2026-07-03 (hold-out graduation review, fourth pass) --- Audited every item in `12-utility-admin-holdout-inventory.md` against the "needs a new design rationale" bar. Three graduated, each with a Fun-Law-clean rationale: (1) the manual scan trigger + scanning/done states -> **Dispatch Scouts** verb (Sec. 3A) --- a real work action whose output *is* the game's core reveal mechanic; (2) inbound channel command arrival/approval/conversion -> **Emissary missives** exchange-table row + **Receive the Emissary** verb (Sec. 3/Sec. 3A) --- real external work intake, the headless-messaging half of the product vision, riding the existing gate-decision ceremony; (3) mock generator / seed-data toggles -> **War Games** substrate (Sec. 5B) --- the already-designed synthetic demo front's shipped engine, with a progress-inert guard mirroring Sec. 14.9. Verb count updated to \~13 (Sec. 3A). Everything else (erasure, export, validation caps, diagnostics, redaction, provider health, resets, palette/shortcut plumbing) remains held out --- no rationale survives Fun Laws 1---4. Doc 12 bullets trimmed with graduation pointers; Sec. 12 inventory updated.
* 2026-07-03 (implemented-mechanics relocation) --- Moved implemented systems that sensibly plug into the current game design out of `12-utility-admin-holdout-inventory.md` and into their owning docs: faction substrate (Sec. 2), command substrate (Sec. 3B), loop support (Sec. 4A), board/quest substrate (Sec. 5C), progression/collection substrate (Sec. 7B), social/scoring substrate (Sec. 9A), audio substrate (Sec. 12A), and technical shell/orchestration integration points (Sec. 15B). Doc 12 now keeps only utility/admin mechanics that should not become game mechanics without a new design rationale.
* 2026-07-05 (Phase 22 closeout implementation) --- Recorded the shipped Projection Foundation boundary after focused validation passed. The v1 projection remains one browser-local derived aggregate at `localStorage["factionos-game-v1"]`; browser-local erasure now clears that key through the existing browser storage cleanup inventory, and `resetToSeed()` removes the same key before restoring seed projection state. `suggestion_update` is an explicit Phase 22 projection no-op for camps, shared `attention.gates` covers legacy permissions, guarded actions, and Command Center permissions, and camp links stay dormant unless a real `campId`, `heroId`, and verbatim `prompt` are recorded before `mission_start`. Focused closeout validation on 2026-07-05 passed `gameProjection`, `gameProjectionStore`, `replayPersist`, and `localErasure` tests: 4 files, 63 tests. Full trusted unified erasure, hosted/cross-device persistence, rendering, camp execution, and new protocol events remain no-claim or future scoped work.
* 2026-07-05 (Phase 23 closeout implementation) --- Recorded Legion I - Scanner Camps as implementation-evidence complete after Session 08 focused gates passed. Current Quest Board codebase issues now reconcile through the existing `suggestion_update` path into aggregate Null Legion camps in the browser-local `GameProjection`; the battlefield renders ranked camps, Dispatch Scouts, Golden Age, failed-scan, mock drill, and reduced-motion static states; camp inspection opens the real Quest Board issue set; dry Banish dismisses current issue cards through existing issue dismissal. Focused closeout validation on 2026-07-05 passed `legionCamps`, `gameProjection`, `gameProjectionStore`, `Battlefield`, `QuestBoard`, `questBoardActions`, and `SettingsScan` tests: 7 files, 137 tests. Web typecheck and root format check also passed. No new protocol event, server route, storage key, hosted dependency, reward path, XP, loot, achievement, camp kill, camp damage, Dawn Report behavior, public-demo synthetic front, or trusted-erasure claim shipped. Workflow validation and PRD/state closeout have since passed; the master PRD and archived Phase 23 PRD mark the phase complete.
* 2026-07-08 (generated asset reference pass) --- Added cross-references from the owning game-design docs to `manifest.md` and the already-present production-generated assets under `assets/generated/game-design/`, including live-enemy/effect sheets, reduced-motion static badges, Town Crier chrome, command ceremony props, banners/regalia, class icons, loop/report frames, territory/home-sector backdrops, loot/tome/relic/quirk/nemesis sheets, boss standees, siege static art, Alliance War, seasons/saga, and War Games presentation sheets. These references are availability records; runtime promotion still belongs to the implementing phase's catalog, fallback, accessibility, cache/mirror, and provenance work.
* 2026-07-08 (Phase 24 closeout evidence) --- Recorded Legion II - Live Tier And Combat Playback as implementation-evidence complete after Session 09 focused gates and the phase-exit audit passed. Quest Board accept/assign successes now record projection-owned pending links, `mission_start` binds camp links, linked missions render strikes/counterattacks/combo/stage/HP playback, `task_verification` can show verified burn-downs, and the battlefield renders live skirmishers, rams, gremlins, wraiths, siege, scrying, alert focus, world cues, reduced-motion static twins, and typed generated-asset posture. Session 09 focused validation passed 17 files / 238 tests; web typecheck, root format check, generated asset catalog tests, and generated source-path runtime scans also passed. No new protocol event, server route, storage key, hosted dependency, runtime generated-asset image load, reward path, XP, loot, banner, public-demo synthetic front, production-hosted validation, certification, or trusted-erasure claim shipped. Code review, validation, and `updateprd` closeout are resolved.
* 2026-07-08 (asset-gap consolidation) --- Moved durable value from the former ongoing-project asset-gap note into stable game-design docs: generated-asset promotion requirements now live in `manifest.md`; runtime media baseline, hard audio backlog, and scope guardrails live in `07-content-audio-and-feature-inventory.md`; remaining per-phase asset and content work lives in `15-phases-yet-to-be-implemented.md`; unresolved media and asset-policy questions live in this file. The ongoing-project gap file was deleted after consolidation.


---

# 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/11-open-questions-and-change-log.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.