> 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/.spec_system/considerations.md). # Considerations > Institutional memory for AI assistants. Updated between phases via carryforward. **Line budget**: 600 max | **Last updated**: Phase 24 (2026-07-08) *** ## Active Concerns Items requiring attention in upcoming phases. Review before each session. ### Technical Debt * \[P08] **Full trusted erasure remains no-claim**: Browser-local cleanup is proven only for scoped local keys; archives, logs, backups, replay/export buffers, workspace files, hosted surfaces, and future integrations are not one trusted erasure workflow. * \[P20] **Executor expansion stays family-scoped**: Terminal, Git status/stage/unstage, file mutation, bounded container isolated-spawn, and managed local lifecycle paths have release evidence; remote execution, Worker bridges, arbitrary Docker, Git push, hosted execution, and other families remain no-claim or unavailable. * \[P20] **Release evidence is the execution claim source**: Do not promote metadata/proposal/preview/unavailable paths to executable unless protocol, runtime ownership, permission/audit, redaction, tests, docs, browser evidence, and release-ledger entries exist. * \[P24] **Archived session stubs can lag live completion**: Phase 24 archive PRD and state are complete, but archived `session_*.md` stubs are planning snapshots that still show Not Started; prefer state, implementation summaries, validation, and archived PRD status for completion truth. * \[P24-apps/web] **Generated Phase 3 assets are not runtime-ready**: The live-enemy, strike-vocabulary, and reduced-motion sheets are typed references with blocked media catalog records; browser loading still needs app-owned serving, slicing, optimization, metadata cleanup, accessibility, and media gates. ### External Dependencies * \[P01-apps/server] **Anthropic transfer is two-level opt-in**: `ANTHROPIC_API_KEY` alone must never send prompts or files; provider calls also require `FACTIONOS_ALLOW_LLM_PROVIDER_TRANSFER=true`. * \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Worker/Durable Object room sharing is separate from local state and must not imply hosted identity, public collaboration safety, production auditability, certification, or full erasure. * \[P07] **Hosted services ship as disabled-default guardrails only**: Supabase, Umami, hosted storage, public replay, push/VAPID, tunnels, and remote access are not active claims without scoped consent, minimization, authorization, abuse controls, tests, and docs. * \[P20] **Signed or hosted channel trust is deferred**: Templates can seed bounded local executable defaults and stored channel commands can be locally converted, but webhook/chat auto-execution, signed channel trust, production channel identity, and hosted command trust remain no-claim. * \[P22] **Cloudflare custom-domain smoke needs owner access**: Phase-transition deploy/local gates passed, but public website, demo, and War Room custom-domain smokes hit HTTP 403 or HTTP\_STATUS on 2026-07-05; do not claim hosted health until Cloudflare/domain/WAF access resolves it. ### Performance / Security * \[P07] **Redaction is boundary-specific**: Queue, lineage, guarded-action, Worker, diagnostics, replay, export, archive, adapter, backup, log, projection, scanner camp, combat playback, and future external-transfer payloads need explicit minimization at each boundary. * \[P03-apps/server] **Local server boundary must stay conservative**: Loopback bind, non-loopback opt-in, CORS allowlists, optional auth token, WS origin checks, request validation, rate limits, body-size caps, and explicit 501s are release-critical defaults. * \[P18-apps/server] **Provider opt-in stays two-level**: Idle, summary, analysis, project scan, diagnostics, and command-center integrations require both credentials and explicit provider-transfer opt-in before any external transfer. * \[P20] **Broad privacy gates are release-critical**: Raw commands, terminal output, diffs, file contents, webhook bodies, provider payloads, tokens, secrets, broad absolute paths, Docker output, mounts, process internals, scanner details, and raw combat/link data must stay scoped or redacted. * \[P24-apps/web] **Game projection stays aggregate-only**: `localStorage["factionos-game-v1"]` may hold bounded ids, safe labels, counters, timestamps, links, and live-tier aggregates only; prompt-bearing pending links are runtime-only and legacy persisted pending links normalize away on load. ### Architecture * \[P03] **Stable docs are the current contract**: Use README files, `docs/api/`, architecture, privacy, deployment, and package docs as current truth; archived PRDs and `EXAMPLES/` are traceability evidence only. * \[P03-packages/protocol] **Protocol leads cross-package work**: Add or change shared queue, lineage, guarded-action, event, REST, WebSocket, and command-center domain types in `packages/protocol` before wiring package-specific behavior. * \[P21-apps/web] **Focused bottom rail is shell-owned**: Quest Board, Orchestration, and War Room focused modes must keep one mounted implementation; future panel work should use the shared host instead of duplicating trees or making summaries primary. * \[P24-apps/web] **Live combat is projection-owned presentation**: Future battlefield, ceremony, report, audio, or reward work should read `gameProjection.ts`, `legionCamps.ts`, and Phase 24 selectors instead of adding parallel combat state, protocol events, server routes, storage keys, or reward authority. * \[P20] **Execution state is manager-owned**: Queue, campaign, file, Git, terminal, container, managed lifecycle, template, and channel transitions should keep idempotency, revisions, cleanup, event emission, rollback/recovery, and bounded snapshots in server managers/coordinators. *** ## Lessons Learned Proven patterns and anti-patterns. Reference during implementation. ### What Worked * \[P24-apps/web] **Pure models before UI/audio**: `combatPlayback.ts`, `liveLegion.ts`, `scryingAndAlertFocus.ts`, and `worldCues.ts` made caps, labels, replay filters, rate limits, and privacy assertions testable without React or Web Audio. * \[P24-apps/web] **Projection-owned presentation layers**: Live enemies, combat effects, scrying posture, alert focus, and world cues stayed selector-fed and presentation-only, so Phase 24 added readable combat without new storage, protocol, server, or reward authority. * \[P24-apps/web] **Runtime/durable privacy split**: Pending-link prompts can exist for active mission matching while persisted projections scrub `pendingLinks` and normalize legacy raw links away on load. * \[P24-apps/web] **Typed generated-asset posture**: Source-owned generated sheets became auditable app/catalog references with fallback labels and release blockers without exposing `assets/generated/game-design/` as runtime image paths. * \[P23-apps/web] **Pure camp reconciliation first**: `legionCamps.ts` made sector coalescing, HP/tier math, entrenchment, Champion Mode limits, and privacy tests reusable across reducer, store, Quest Board, and battlefield sessions. * \[P23-apps/web] **Reducer equality guards**: Comparing camp and sector records before returning a new projection kept `lastEventAt`, alert focus, replay, failed-scan, and no-op snapshot behavior honest. * \[P23-apps/web] **Storage inventory regressions**: Tests that enumerate browser keys and reject camp/Legion/scanner-specific keys protected the single `factionos-game-v1` authority better than prose alone. * \[P23-apps/web] **Same Quest Board action path**: Camp inspection and dry Banish stayed reliable by opening the existing focused Quest Board surface, filtering current issue cards, and reusing issue dismissal with duplicate guards and rollback. * \[P23-apps/web] **Presentation-only battlefield layers**: Thin native-control, reduced-motion-aware, selector-fed layers let visible game affordances remain product presentation instead of becoming game rules. * \[P22-apps/web] **Single projection authority**: Keeping reducer logic, parsing, persistence guards, and constants in `gameProjection.ts` let the store fold events once without creating a parallel game-state source. * \[P22-apps/web] **Honesty regression matrix**: Durable-counter snapshots through reducer, store, replay, reconnect, mock, serialization, persistence, reset, and erasure seams prevent replay or drill traffic from minting progress. * \[P22-apps/web] **Existing erasure inventory reuse**: Adding `GAME_PROJECTION_STORAGE_KEY` to the browser-settings cleanup plan avoided a new protocol boundary while proving preview redaction, confirmation removal, and duplicate idempotency. * \[P21-apps/web] **Same-instance focused surfaces**: Promoting the existing bottom-rail panel into a focused shell preserved local drafts, selected tabs, drawer state, hydration, and action behavior without duplicate trees. * \[P20] **Manager-backed readiness gates**: User-facing action verbs became truthful only after protocol contracts, manager ownership, fail-closed checks, compact events, UI states, docs, tests, and browser evidence aligned. * \[P20] **Layered broad-surface privacy tests**: Parser, route, export, WebSocket, store, row, drawer, browser, and docs checks caught raw-field leakage risks before release closeout. ### What To Avoid * \[P24-apps/web] **Do not make combat playback a reward authority**: Linked strikes, HP drain, burn-down, barks, and cues are presentation for real evidence; only `task_verification` supports camp-kill visuals, and no XP, loot, banners, achievements, or durable rewards ship from these layers. * \[P24-apps/web] **Do not runtime-load generated source art**: `assets/generated/game-design/` files are source references until promoted through app-owned runtime paths, slicing, optimization, metadata cleanup, accessibility review, and media gates. * \[P24-apps/web] **Do not duplicate urgency or audio paths**: Keep one projection-owned `alertFocus` pulse and route world cues through existing opt-in audio guards, duplicate suppression, redacted failures, and cleanup. * \[P23-apps/web] **Do not add camp-specific authorities**: Scanner and combat work should not add new protocol events, server routes, storage keys, hosted state, camp stores, or projection copies when existing events, `GameProjection`, and Quest Board cards suffice. * \[P23-apps/web] **Do not move scan configuration into the battlefield**: Scan roots, ignore patterns, disabled gating, diagnostics, provider health, and error summaries stay in utility/admin surfaces; the battlefield may show only bounded product state. * \[P22-apps/web] **Do not add parallel game authorities**: Battlefield, camp, report, audio, and ceremony work should read projection selectors instead of copying progress, attention, enemy, or camp-link state elsewhere. * \[P22-apps/web] **Do not persist replay or drill progress**: Replay, reconnect snapshots, mock mode, and synthetic traffic may reconcile or no-op in memory, but must not increment durable XP, essence, banners, kills, titles, links, or War Tide. * \[P21-apps/web] **Do not duplicate bottom-rail panel trees**: A second Quest Board, Orchestration, or War Room tree can fork local state, hydration, selected ids, pending actions, room state, or diagnostics. * \[P20] **Do not let metadata complete execution rows**: Metadata-only, preview-only, proposal-only, approved-not-executing, unavailable, or blocked work must not mark queue or campaign work completed. * \[P20] **Do not broaden scoped content into release surfaces**: Raw commands, output, diffs, file contents, webhook bodies, provider payloads, Docker details, broad paths, tokens, process internals, scanner details, and combat internals stay scoped or redacted. ### Tool/Library Notes * \[P24-apps/web] **Combat playback helpers**: `combatPlayback.ts` owns strike classification, combo/rate-limit constants, stage props, and safe labels; `combatPlaybackEffects.ts` selects linked events, display HP, verification-only kill visuals, and privacy-safe effect keys. * \[P24-apps/web] **Live presentation helpers**: `liveLegion.ts`, `scryingAndAlertFocus.ts`, and `worldCues.ts` own caps, anchors, static twins, alert-focus posture, cue derivation, replay/unlinked rejection, and safe labels. * \[P24-apps/web] **Generated asset map**: `generatedPhase3Assets.ts` and media catalog records pin Phase 3 source sheets, fallback labels, reduced-motion pairings, and `runtimeReady: false` release blockers. * \[P23-apps/web] **`legionCamps.ts`**: Owns scanner issue to camp/sector reconciliation, Champion Mode ranking, entrenchment metadata, safe labels, and aggregate-only output. * \[P22-apps/web] **`gameProjection.ts`**: Owns `GAME_PROJECTION_STORAGE_KEY`, reducer purity, parser guards, persistence guards, failed/replay/mock scanner behavior, pending/camp links, live-tier state, and future game selectors. *** ## Resolved Recently closed items (buffer - rotates out after 2 phases). | Phase | Item | Resolution | | ----- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | P24 | Camp-to-mission linkage was dead code | Session 02 extended existing accept handling to codebase issues, added issue-card accept/assign capabilities, recorded pending links, and proved `mission_start` binding without protocol or route shape changes. | | P24 | Live tier and combat playback were invisible | Sessions 03-06 rendered live enemies, linked strikes, scrying, alert focus, and world cues with caps, reduced-motion twins, safe labels, and focused tests. | | P24 | Pending-link prompts could persist | Session 07 made prompts runtime-only by scrubbing persisted `pendingLinks`, normalizing legacy raw links away on load, and extending storage/erasure regressions. | | P24 | Generated Phase 3 assets were manifest-only | Session 08 promoted the three Phase 3 sheets to typed app/catalog references with fallback labels, reduced-motion pairings, tests, and docs while keeping runtime loading blocked. | | P23 | Scanner camp no-op | Phase 23 replaced the `suggestion_update` camp no-op with aggregate scanner camp reconciliation, reducer equality guards, replay/failed-scan guards, and focused privacy tests. | | P23 | Scanner camps were invisible | Phase 23 added Champion Mode ranking, accessible battlefield camp markers, Quest Board focus, dry Banish through existing issue dismissal, and docs without rewards or new routes. | | P23 | Scanner clean and failed states were ambiguous | Phase 23 added Dispatch Scouts, Golden Age, scan-not-run, failed-scan preservation, mock drill labeling, zero-hero neutrality, and reduced-motion static equivalents. | | P22 | Game projection authority was absent | Phase 22 added the versioned `GameProjection` contract, pure reducers, store folding, selectors, and docs without new rendering/protocol authority. | | P22 | Projection replay/reconnect/mock farming risk | Phase 22 added reducer/store/public replay regressions plus mock no-persist guards so synthetic or replayed traffic cannot mint durable progress. | | P22 | Projection key was outside erasure inventory | Phase 22 added `factionos-game-v1` to browser-local erasure and reset coverage, with docs preserving broad trusted-erasure no-claim wording. | *** *Auto-generated by carryforward. Direct edits allowed but may be overwritten.* --- # 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/.spec_system/considerations.md?ask=&goal= ``` `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.