> 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/archive/sessions/phase22-session01-projection-contract/tasks.md).

# Task Checklist

**Session ID**: `phase22-session01-projection-contract` **Total Tasks**: 19 **Estimated Duration**: 3-4 hours **Created**: 2026-07-04

***

Legend: `[x]` completed; `[ ]` pending; `[P]` parallelizable; `[SNNMM]` session ref; `TNNN` task ID.

***

## Setup (2 tasks)

* [x] T001 \[S2201] Verify Session 01 scope, dependencies, and out-of-scope boundaries against the Phase 22 PRD and stub (`.spec_system/PRD/phase_22/session_01_projection_contract.md`)
* [x] T002 \[S2201] Create the projection module scaffold with constants, type-only protocol import, context exports, and no UI/store imports (`apps/web/src/lib/gameProjection.ts`)

***

## Foundation (6 tasks)

* [x] T003 \[S2201] Define serializable projection aliases and nested interfaces for sectors, legion, links, heroes, essence, buildings, War Tide, council, nemeses, alert focus, season, flare ceremony, and root state (`apps/web/src/lib/gameProjection.ts`)
* [x] T004 \[S2201] Implement deterministic timestamp, season id, and neutral nested-state factory helpers (`apps/web/src/lib/gameProjection.ts`)
* [x] T005 \[S2201] Implement `createInitialGameProjection(now?)` with the complete neutral v1 shape and injected-time behavior (`apps/web/src/lib/gameProjection.ts`)
* [x] T006 \[S2201] Implement `reduceGameProjection` as a pure same-reference no-op shell for `connected` and unknown events with no broad event folding (`apps/web/src/lib/gameProjection.ts`)
* [x] T007 \[S2201] Define runtime guards for safe persisted v1 root shape with schema-validated input and explicit fallback behavior (`apps/web/src/lib/gameProjection.ts`)
* [x] T008 \[S2201] Add focused test builders for fixed timestamps, storage doubles, and representative server events (`apps/web/tests/gameProjection.test.ts`)

***

## Implementation (4 tasks)

* [x] T009 \[S2201] Implement `parsePersistedGameProjection(input, now?)` with fresh fallback for null, malformed, wrong-version, and unsafe persisted input (`apps/web/src/lib/gameProjection.ts`)
* [x] T010 \[S2201] Implement `loadPersistedGameProjection(storage?, now?)` with null, unavailable, and throwing-storage handling (`apps/web/src/lib/gameProjection.ts`)
* [x] T011 \[S2201] Implement `persistGameProjection(state, storage?)` with JSON serialization, null storage handling, and swallowed quota/stringify failures (`apps/web/src/lib/gameProjection.ts`)
* [x] T012 \[S2201] Implement `shouldPersistGameProjection(ctx)` with replay and mock/drill write guards (`apps/web/src/lib/gameProjection.ts`)

***

## Testing (7 tasks)

* [x] T013 \[S2201] Test the full initial projection shape, empty records, zeroed counters, null focus fields, deterministic timestamps, and deterministic `season:YYYY-MM-DD` id (`apps/web/tests/gameProjection.test.ts`)
* [x] T014 \[S2201] Test malformed, missing, non-object, wrong-version, and unsafe persisted inputs return a fresh valid projection (`apps/web/tests/gameProjection.test.ts`)
* [x] T015 \[S2201] Test load and persist helpers for valid round trip, null storage, missing storage key, throwing `getItem`, throwing `setItem`, and JSON stringify failures (`apps/web/tests/gameProjection.test.ts`)
* [x] T016 \[S2201] Test JSON serialization excludes selected faction, scrolls, achievements, War Room membership, settings, Notice Board messages, visible hero slots, replay entries, toasts, animation state, audio state, raw prompts, broad paths, terminal output, file contents, provider payloads, tokens, and secrets (`apps/web/tests/gameProjection.test.ts`)
* [x] T017 \[S2201] Test `shouldPersistGameProjection` denies writes while replaying or mock-enabled and allows real non-replay projection writes (`apps/web/tests/gameProjection.test.ts`)
* [x] T018 \[S2201] Run focused automated validation command (`npm test -- apps/web/tests/gameProjection.test.ts`)
* [x] T019 \[S2201] Run type and encoding validation commands (`npm --workspace @factionos/web run typecheck`; ASCII/LF check for `apps/web/src/lib/gameProjection.ts` and `apps/web/tests/gameProjection.test.ts`)

***

## Completion Checklist

* [x] All tasks marked `[x]`
* [x] All tests and checks passing
* [x] All files ASCII-encoded with LF line endings
* [x] implementation-notes.md updated
* [x] Ready for `creview` (next step in the implement -> creview -> validate sequence)

***

## Next Steps

Run the `implement` workflow step.


---

# 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/archive/sessions/phase22-session01-projection-contract/tasks.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.