> 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-session02-hero-attention-reducer/implementation-notes.md). # Implementation Notes **Session ID**: `phase22-session02-hero-attention-reducer` **Package**: apps/web **Started**: 2026-07-05 00:36 **Last Updated**: 2026-07-05 01:46 *** ## Session Progress | Metric | Value | | ------------------- | --------- | | Tasks Completed | 21 / 21 | | Estimated Remaining | 0 minutes | | Blockers | 0 | *** ## Task Log ### 2026-07-05 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available * [x] Directory structure ready **Notes**: * Project analysis resolved `current_session` to `phase22-session02-hero-attention-reducer`. * Monorepo package scope resolved from `spec.md` and phase stub to `apps/web`. * `check-prereqs.sh --json --env --package apps/web` passed. * Shell reports Node `v24.14.0` and npm `11.16.0`; local spec prereq tooling passes for the available workspace commands. * Behavioral Quality Checklist loaded for this application-code session. * UI product-surface checks are N/A for this pure reducer/test session; no user-facing surface is in scope. *** ### Task T001 - Verify Session 01 Validation Evidence And Dependency Scope **Started**: 2026-07-05 00:36 **Completed**: 2026-07-05 00:36 **Duration**: 1 minute **Notes**: * Confirmed Session 01 is complete and validated before expanding the projection contract. * Verified the current session base commit exists locally. **Files Changed**: * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added session log and T001 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T001 complete. **Verification**: * Command/check: `sed -n '1,260p' .spec_system/specs/phase22-session01-projection-contract/validation.md` * Result: PASS * Evidence: Session 01 validation reports `Result: PASS`, `19/19` tasks complete, focused tests passed, and web typecheck passed. * Command/check: `git rev-parse --verify --quiet 2d9af05a53126c91bf0a54d2ae3d1d0ef6c8b1f1^{commit}` * Result: PASS * Evidence: Base commit resolved to `2d9af05a53126c91bf0a54d2ae3d1d0ef6c8b1f1`. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T002 - Review Current Projection Contract, Guards, And Reducer Seam **Started**: 2026-07-05 00:36 **Completed**: 2026-07-05 00:37 **Duration**: 1 minute **Notes**: * Reviewed the neutral Session 01 projection shape, exact-key guards, persistence helpers, no-op `recomputeAlertFocus`, and no-op `reduceGameProjection`. * Identified required compatibility work: adding `attention` means the parser must normalize old Session 01 persisted shapes before the strict guard. **Files Changed**: * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T002 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T002 complete. **Verification**: * Command/check: `sed -n '1,760p' apps/web/src/lib/gameProjection.ts` * Result: PASS * Evidence: Current reducer shell, guards, projection root keys, and persistence helpers were inspected. * Command/check: `sed -n '1,380p' apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: Existing tests cover neutral shape, parser fallback, persistence helpers, serialization boundary, and no-op reducer behavior. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T003 - Review Protocol Event Shapes For Reducer Inputs **Started**: 2026-07-05 00:37 **Completed**: 2026-07-05 00:38 **Duration**: 1 minute **Notes**: * Reviewed `ServerEvent` variants for hero lifecycle, flares, legacy permissions, guarded actions, and command-center permissions. * Confirmed guarded-action active state is `pending`; terminal states are `approved`, `rejected`, `expired`, `executed`, `failed`, and `unavailable`. * Confirmed command-center permission active states are `requested` and `in_flight`; terminal states are `approved`, `rejected`, `expired`, `stale`, `duplicate`, and `cancelled`. **Files Changed**: * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T003 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T003 complete. **Verification**: * Command/check: `rg -n "internal_hero_spawn|roster_update|hero_dismissed|awaiting_input|input_received|permission_request|permission_response|guarded_action_update|command_center_permission_update" packages/protocol/src/events.ts packages/protocol/src/guardedActions.ts packages/protocol/src/orchestrationCommandCenter.ts apps/web/src/store/useGameStore.ts` * Result: PASS * Evidence: Located all target event variants and current web-store handling. * Command/check: `sed -n '300,480p' packages/protocol/src/events.ts`; `sed -n '2060,2125p' packages/protocol/src/orchestrationCommandCenter.ts` * Result: PASS * Evidence: Inspected exact payload fields for legacy permission/flaring events and command-center permission entries. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T004 - Add Attention Types, Defaults, Guards, And Session 01 Normalization **Started**: 2026-07-05 00:39 **Completed**: 2026-07-05 00:44 **Duration**: 5 minutes **Notes**: * Added a serializable `attention` aggregate for active flare and gate refs. * Kept refs privacy-safe by storing ids, source family, optional hero id, and timestamps only. * Added strict guards and a parser normalization path for Session 01 persisted shapes that do not yet include `attention`. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Added attention types, defaults, guards, root-key validation, and persisted-shape normalization. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T004 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T004 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: targeted inspection of `apps/web/src/lib/gameProjection.ts` * Result: PASS * Evidence: `attention` defaults to empty records, strict guards accept only aggregate ref fields, and old Session 01 roots normalize by adding an empty attention aggregate. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T005 - Add Immutable Hero Projection Helpers **Started**: 2026-07-05 00:44 **Completed**: 2026-07-05 00:47 **Duration**: 3 minutes **Notes**: * Added private helpers for deterministic zero-progress hero projection records. * Derived `quirkSeed` from `sessionId ?? id` through a stable hash so roster source fields are not copied into projection state. * Added roster reconciliation helpers that preserve existing hero aggregates and return the same record reference when no hero is added. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Added hero seed, neutral hero creation, and immutable merge/reconcile helpers. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T005 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T005 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: targeted inspection of `createNeutralHeroProjection`, `withHeroProjection`, and `reconcileHeroProjectionRoster` * Result: PASS * Evidence: Helpers preserve existing records by reference, add only missing zero-progress hero aggregates, and do not copy roster names, cwd, model, metrics, prompt, or position fields. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T006 - Add Alert-Focus Ordering Helpers **Started**: 2026-07-05 00:47 **Completed**: 2026-07-05 00:51 **Duration**: 4 minutes **Notes**: * Implemented `recomputeAlertFocus` as the projection-owned alert priority authority. * Added stable tie-breaks: oldest `openedAt`/`sinceAt` first, then deterministic id ordering within the same tier. * Kept existing Legion fields readable for later reducers and test-seeded state. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Added focus selectors and priority recompute logic. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T006 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T006 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: targeted inspection of `recomputeAlertFocus` * Result: PASS * Evidence: Priority order is `flare > gate > siege > ram > skirmisher > newCamp > null`, with deterministic tie-breaks. * Checkpoint: re-read `.spec_system/specs/phase22-session02-hero-attention-reducer/spec.md` objectives and success criteria. * Result: PASS * Evidence: Work remains scoped to pure `apps/web/src/lib/gameProjection.ts` and tests; no store, UI, persistence scheduling, protocol, or DB work added. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T007 - Add Typed Vitest Event Builders **Started**: 2026-07-05 00:51 **Completed**: 2026-07-05 00:55 **Duration**: 4 minutes **Notes**: * Added typed builders for hero lifecycle, flare, legacy permission, guarded-action, and command-center permission reducer inputs. * Kept sensitive strings in builders so later privacy tests can prove they do not enter serialized projection state. **Files Changed**: * `apps/web/tests/gameProjection.test.ts` - Added typed protocol event builders for upcoming reducer tests. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T007 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T007 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0 with the typed test builders. * Command/check: targeted inspection of `apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: Builders return `Extract` shapes for all Session 02 reducer event families. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T008 - Implement Hero Lifecycle Reduction **Started**: 2026-07-05 00:55 **Completed**: 2026-07-05 00:59 **Duration**: 4 minutes **Notes**: * Added reducer cases for `internal_hero_spawn`, `roster_update`, and `hero_dismissed`. * Reducers add missing zero-progress projection hero records and preserve existing XP, titles, swift-command stats, banners, and kills. * Snapshot reconciliation never deletes heroes omitted from a roster update. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Added hero lifecycle reducer helpers and switch cases. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T008 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T008 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: targeted inspection of hero lifecycle reducer helpers * Result: PASS * Evidence: Only missing aggregate hero records are added; existing hero records and earned fields are preserved by reference. * BQC: Contract alignment and mutation safety checked. * Result: PASS * Evidence: Event cases use `ServerEvent` discriminants and copy-on-write state updates. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T009 - Implement Awaiting-Input Flare Recording **Started**: 2026-07-05 00:59 **Completed**: 2026-07-05 01:03 **Duration**: 4 minutes **Notes**: * Added `awaiting_input` reduction for one active flare per hero. * Prompt/options payloads are ignored and never copied into projection state. * Duplicate active flare events return the original state reference. * Replay mode can add the active flare ref but does not increment `flareCeremony`. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Added flare ceremony helper and `awaiting_input` reducer case. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T009 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T009 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: targeted inspection of `reduceAwaitingInput` * Result: PASS * Evidence: Stored flare fields are `heroId`, `openedAt`, and `updatedAt`; `prompt`, `options`, and response text are not referenced. * BQC: Trust boundary and privacy boundary checked. * Result: PASS * Evidence: External prompt payload is discarded at the reducer boundary. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T010 - Implement Input Clearing And Swift Command Timing **Started**: 2026-07-05 01:03 **Completed**: 2026-07-05 01:07 **Duration**: 4 minutes **Notes**: * Added `input_received` reduction to clear the active flare for the hero. * Non-replay input updates `swiftCommand.count` and rolling `meanMs` from the active flare timing. * Replay input clears active attention without minting swift-command progress. * Input response text is ignored and never copied into projection state. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Added immutable removal helper, swift-command update helper, and `input_received` reducer case. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T010 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T010 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: targeted inspection of `reduceInputReceived` * Result: PASS * Evidence: Active flare is removed, rolling mean uses prior flare `openedAt`, and `ctx.isReplaying` skips hero counter updates. * BQC: Mutation safety and replay no-accumulation checked. * Result: PASS * Evidence: Nested records are copy-on-write and replay mode only reconciles attention. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T011 - Implement Legacy Permission Gate Refs **Started**: 2026-07-05 01:07 **Completed**: 2026-07-05 01:10 **Duration**: 3 minutes **Notes**: * Added `permission_request` gate refs keyed by legacy permission request id. * Added `permission_response` clearing with same-reference no-op behavior when no active gate exists. * Excluded `rationale`, `detail`, and `toolName` from projection storage. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Added legacy permission gate helpers and reducer cases. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T011 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T011 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: targeted inspection of `reducePermissionRequest` and `reducePermissionResponse` * Result: PASS * Evidence: Gate ref stores request id, `legacyPermission` source, `permission` family, optional hero id, and timestamps only. * BQC: Trust boundary and privacy boundary checked. * Result: PASS * Evidence: Raw rationale/detail/tool preview fields are not read into the projection object. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T012 - Implement Guarded-Action Gate Reconciliation **Started**: 2026-07-05 01:10 **Completed**: 2026-07-05 01:15 **Duration**: 5 minutes **Notes**: * Added source-scoped reconciliation for `guarded_action_update`. * Pending proposals become active `guardedAction` gate refs. * Terminal or absent guarded-action proposals clear guarded-action gates without affecting legacy or command-center gates. * Event shape does not expose typed hero references, so no requester string is stored as `heroId`. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Added gate comparison/reconciliation helpers and guarded-action reducer case. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T012 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T012 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: targeted inspection of `reduceGuardedActionUpdate` * Result: PASS * Evidence: Only `pending` proposals are retained; terminal states clear by source reconciliation, and refs store proposal id, source, family, and timestamps. * BQC: Contract alignment checked. * Result: PASS * Evidence: Reducer uses `GuardedActionEventProposal.state` values from the protocol contract and does not infer missing fields. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T013 - Implement Command-Center Permission Gate Reconciliation **Started**: 2026-07-05 01:15 **Completed**: 2026-07-05 01:18 **Duration**: 3 minutes **Notes**: * Added source-scoped reconciliation for `command_center_permission_update`. * `requested` and `in_flight` entries become active command-center permission gate refs. * Approved, rejected, expired, stale, duplicate, and cancelled entries clear through source reconciliation. * Stored refs exclude target labels and raw command-center payload fields. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Added command-center permission reducer case. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T013 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T013 complete. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: targeted inspection of `reduceCommandCenterPermissionUpdate` * Result: PASS * Evidence: Only `requested` and `in_flight` requests are retained; terminal states clear; refs store request id, source, target-kind family, optional hero id for hero targets, and timestamps. * BQC: Contract alignment and error information boundaries checked. * Result: PASS * Evidence: Reducer uses protocol permission states and does not persist target labels, raw payloads, or diagnostic fields. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T014 - Wire Reducer Finalization Through Alert Recompute **Started**: 2026-07-05 01:18 **Completed**: 2026-07-05 01:21 **Duration**: 3 minutes **Notes**: * Verified every implemented reducer case returns the original state reference for ignored, duplicate, or unchanged inputs. * Verified every changed reducer path finalizes through `recomputeAlertFocus`. * Confirmed unknown and `connected` events still return the exact original state reference. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Reused shared finalization across all implemented reducer cases. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T014 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T014 complete. **Verification**: * Command/check: `rg -n "finalizeProjectionUpdate|return state;|case \"(internal_hero_spawn|roster_update|hero_dismissed|awaiting_input|input_received|permission_request|permission_response|guarded_action_update|command_center_permission_update)\"" apps/web/src/lib/gameProjection.ts` * Result: PASS * Evidence: All changed reducer branches have no-op returns before finalization and changed paths call `finalizeProjectionUpdate`. * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * BQC: Mutation safety checked. * Result: PASS * Evidence: Copy-on-write branches preserve exact references on no-op paths and recompute focus from aggregate state on changed paths. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T015 - Add Reducer Purity And Hero Lifecycle Tests **Started**: 2026-07-05 01:21 **Completed**: 2026-07-05 01:26 **Duration**: 5 minutes **Notes**: * Updated the initial projection shape expectation for the new neutral `attention` aggregate. * Added reducer tests for no-op references, frozen-state purity, hero creation, roster reconciliation, dismissal preservation, and source-of-truth exclusion. **Files Changed**: * `apps/web/tests/gameProjection.test.ts` - Added reducer context/deep-freeze helpers and hero lifecycle tests. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T015 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T015 complete. **Verification**: * Command/check: `npm test -- apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: 1 test file passed; 11 tests passed; 0 failed. * BQC: Mutation safety and contract alignment checked. * Result: PASS * Evidence: Test freezes initial state and verifies same-reference no-op behavior plus zero-progress hero creation. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T016 - Add Flare And Swift Command Tests **Started**: 2026-07-05 01:26 **Completed**: 2026-07-05 01:29 **Duration**: 3 minutes **Notes**: * Added tests for flare recording, duplicate flare no-op behavior, input clearing, Swift Command rolling mean, and replay-safe no-accumulation. * Covered prompt and response-text exclusion from serialized projection state. **Files Changed**: * `apps/web/tests/gameProjection.test.ts` - Added flare lifecycle and replay tests. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T016 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T016 complete. **Verification**: * Command/check: `npm test -- apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: 1 test file passed; 12 tests passed; 0 failed. * BQC: Replay no-accumulation and privacy boundary checked. * Result: PASS * Evidence: Tests verify replay clears attention without increasing counters and serialized state excludes raw prompt/response strings. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T017 - Add Gate Source Reconciliation Tests **Started**: 2026-07-05 01:29 **Completed**: 2026-07-05 01:33 **Duration**: 4 minutes **Notes**: * Added tests for legacy permission request/response gates. * Added guarded-action pending/terminal snapshot tests with duplicate terminal no-op coverage. * Added command-center permission requested/terminal snapshot tests with duplicate snapshot no-op coverage. * Covered exclusion of rationale, detail, and command-center target labels from serialized projection state. **Files Changed**: * `apps/web/tests/gameProjection.test.ts` - Added gate reconciliation tests. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T017 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T017 complete. **Verification**: * Command/check: `npm test -- apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: 1 test file passed; 13 tests passed; 0 failed. * BQC: Contract alignment and trust boundary checked. * Result: PASS * Evidence: Tests exercise protocol terminal states and verify raw request/detail/label strings do not serialize. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T018 - Add Alert Focus Priority Tests **Started**: 2026-07-05 01:33 **Completed**: 2026-07-05 01:36 **Duration**: 3 minutes **Notes**: * Added direct `recomputeAlertFocus` tests covering null, new camp, skirmisher, ram, siege, gate, and flare tiers. * Verified same-tier deterministic tie-breaks for camps, skirmishers, gates, flares, and stalled siege tasks. **Files Changed**: * `apps/web/tests/gameProjection.test.ts` - Added alert focus priority tests. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T018 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T018 complete. **Verification**: * Command/check: `npm test -- apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: 1 test file passed; 14 tests passed; 0 failed. * BQC: Contract alignment checked. * Result: PASS * Evidence: Test asserts exact `flare > gate > siege > ram > skirmisher > newCamp > null` behavior. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T019 - Add Parser Compatibility And Serialization Privacy Tests **Started**: 2026-07-05 01:36 **Completed**: 2026-07-05 01:39 **Duration**: 3 minutes **Notes**: * Added parser coverage for Session 01 persisted shapes that lack `attention`. * Added safe attention round-trip coverage. * Added unsafe attention payload rejection for extra raw prompt fields. * Verified serialized reducer output excludes raw prompt, permission rationale, and permission detail text. **Files Changed**: * `apps/web/tests/gameProjection.test.ts` - Added parser compatibility and attention privacy tests. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T019 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T019 complete. **Verification**: * Command/check: `npm test -- apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: 1 test file passed; 16 tests passed; 0 failed. * BQC: Trust boundary and privacy boundary checked. * Result: PASS * Evidence: Parser rejects unsafe extra attention payload fields and tests verify raw prompt/rationale/detail strings are absent from serialized projection state. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T020 - Run Focused Reducer Tests **Started**: 2026-07-05 01:39 **Completed**: 2026-07-05 01:40 **Duration**: 1 minute **Notes**: * Ran the required focused Vitest command after all reducer tests were in place. * No failures required repair. **Files Changed**: * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T020 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T020 complete. **Verification**: * Command/check: `npm test -- apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: 1 test file passed; 16 tests passed; 0 failed. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ### Task T021 - Run Web Typecheck And ASCII/LF Validation **Started**: 2026-07-05 01:40 **Completed**: 2026-07-05 01:45 **Duration**: 5 minutes **Notes**: * Ran the required web typecheck and changed-file ASCII/LF validation. * Initial Biome check required formatting changes; applied `biome check --write` to the two changed code files and reran all checks. * Re-ran the focused reducer tests after formatting. **Files Changed**: * `apps/web/src/lib/gameProjection.ts` - Biome-formatted final reducer implementation. * `apps/web/tests/gameProjection.test.ts` - Biome-formatted final focused tests. * `.spec_system/specs/phase22-session02-hero-attention-reducer/implementation-notes.md` - Added T021 evidence. * `.spec_system/specs/phase22-session02-hero-attention-reducer/tasks.md` - Marked T021 and completion checklist complete. **Verification**: * Command/check: `npm test -- apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: 1 test file passed; 16 tests passed; 0 failed. * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS * Evidence: `tsc -b --noEmit` exited 0. * Command/check: `npm exec -- biome check apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjection.test.ts` * Result: PASS * Evidence: 2 files checked; no fixes applied after formatting. * Command/check: `LC_ALL=C grep -nP '[^\x00-\x7F]' ...` * Result: PASS * Evidence: ASCII PASS for reducer, tests, spec, tasks, and implementation notes. * Command/check: `rg -nU $'\r' ...` * Result: PASS * Evidence: No CRLF matches in reducer, tests, spec, tasks, or implementation notes. * UI product-surface check: N/A - No UI files or routes changed. * UI craft check: N/A - No UI files or routes changed. *** ## Checkpoints ### Checkpoint 1 - After T006 **At**: 2026-07-05 00:51 **Checks**: * `npm --workspace @factionos/web run typecheck` - PASS * Spec objective re-read - PASS; no scope drift. * Next task: T007 (`apps/web/tests/gameProjection.test.ts` event builders). ### Checkpoint 2 - After T014 **At**: 2026-07-05 01:21 **Checks**: * `npm --workspace @factionos/web run typecheck` - PASS * Reducer finalization audit - PASS; all changed reducer paths recompute alert focus and no-op paths return original state. * Spec objective re-read - PASS; no store, UI, protocol, DB, or persistence scheduling scope added. * Next task: T015 (`apps/web/tests/gameProjection.test.ts` reducer purity and hero lifecycle tests). ### Checkpoint 3 - Session Complete **At**: 2026-07-05 01:45 **Checks**: * `npm test -- apps/web/tests/gameProjection.test.ts` - PASS; 16 tests passed. * `npm --workspace @factionos/web run typecheck` - PASS. * `npm exec -- biome check apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjection.test.ts` - PASS. * ASCII and LF scans - PASS for changed code and session artifacts. * Spec objective re-read - PASS; implementation remains pure `apps/web` reducer/test scope. *** ## Design Decisions ### Decision 1: Keep Session 02 Reducer Work In `gameProjection.ts` **Context**: `apps/web/src/lib/gameProjection.ts` is 1320 lines after adding the Session 02 reducer slice. The implement checklist flags large modules for refactor consideration, while this session spec explicitly says to keep all reducer implementation in `apps/web/src/lib/gameProjection.ts` and avoid adding new abstractions outside scope. **Options Considered**: 1. Split guards, attention reducers, and test builders into new modules now - lowers file size but expands session scope and public boundaries before store folding exists. 2. Keep the reducer slice self-contained for this session - follows the spec and preserves one projection authority, but leaves a large module for review. **Chosen**: Option 2. **Rationale**: Session 02 is pure library/test work and later Phase 22 sessions will add more reducer slices. A split should happen with a clear module boundary after `creview` or before additional slices make the ownership boundaries obvious, not as an unrelated refactor inside this implementation task. --- # 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-session02-hero-attention-reducer/implementation-notes.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.