> 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-session03-legion-enemy-reducer/code-review.md). # Code Review and Repair Report **Session ID**: `phase22-session03-legion-enemy-reducer` **Package**: apps/web **Reviewed**: 2026-07-05 **Base Commit**: 42d1d1230fe00c3e6ce66b3c631eebac53677768 **Scope**: All changes since the base commit (uncommitted work plus mid-session commits) **Result**: RESOLVED ## Review Surface **Files reviewed** (all changes since the base commit): * `.spec_system/state.json` - tracked-modified * `apps/web/src/lib/gameProjection.ts` - tracked-modified; repaired by creview * `apps/web/tests/gameProjection.test.ts` - tracked-modified; repaired by creview * `.spec_system/specs/phase22-session03-legion-enemy-reducer/spec.md` - untracked text artifact * `.spec_system/specs/phase22-session03-legion-enemy-reducer/tasks.md` - untracked text artifact * `.spec_system/specs/phase22-session03-legion-enemy-reducer/implementation-notes.md` - untracked text artifact * `.spec_system/specs/phase22-session03-legion-enemy-reducer/code-review.md` - untracked text artifact created by this review **Inventory commands**: `git status`, `git log --oneline "$BASE"..HEAD`, `git diff "$BASE"`, `git diff --cached "$BASE"`, `git ls-files --others --exclude-standard` ## Findings by Severity ### Critical * None. ### High * None. ### Medium * `apps/web/src/lib/gameProjection.ts:386` - Enemy ID normalization accepted arbitrary printable strings for `task_near_stall` / `task_stalled` / `task_escalation` ids and failed `tool_result.heroId`, so path-like or token-like identifiers could be persisted into `legion.siege`, `legion.wraiths`, and neutral `heroes`, violating the session privacy boundary for broad paths, tokens, and secrets. | Fix: added a safe enemy-token allowlist, sensitive/path marker rejection, deterministic hash fallback prefixes for plan/task/hero refs, parser rejection for raw unsafe persisted keys, and regression tests for unsafe task and hero ids. | Status: FIXED ### Low * None. ## Assumptions and Deliberate Non-Fixes * `.spec_system/state.json` trims the oldest `next_session_history` entry while adding the current planned session. This was left unchanged because `jq '.next_session_history | length' .spec_system/state.json` and `git show 42d1d1230fe00c3e6ce66b3c631eebac53677768:.spec_system/state.json | jq '.next_session_history | length'` both returned `20`, and `references/state-schema.md` documents history trimming to the 20 most recent entries. * The session `spec.md` still says `Status: Not Started` and `Next Steps: implement`. This was left unchanged because targeted inspection of `.spec_system/specs/phase22-session01-projection-contract/spec.md` and `.spec_system/specs/phase22-session02-hero-attention-reducer/spec.md` showed the same convention after implementation and code review; task, implementation, code-review, and validation artifacts carry lifecycle evidence. * Unsafe enemy ID-like refs are hashed instead of dropped. This preserves aggregate enemy pressure while preventing raw paths, token-like strings, and secret-like values from entering projection JSON. * UI product-surface checks are N/A because the review surface changes only a pure reducer module, reducer tests, and spec-system artifacts. ## Behavior Changes * Creview changed unsafe enemy ID-like ref handling: path-like, token-like, secret-like, overlong, or otherwise unsafe plan/task/hero refs now persist as deterministic hash labels such as `plan:`, `task:`, or `hero:` instead of raw strings. Safe existing ids such as `hero-wraith`, `plan-alpha`, and `task-a` are unchanged. ## Evidence Ledger Every row names the exact command or targeted inspection used. | Check | Command or Inspection | Result | Evidence / Blocker | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Project state | `if [ -d ".spec_system/scripts" ]; then bash .spec_system/scripts/analyze-project.sh --json; else bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.18-codex/skills/apex-spec/scripts/analyze-project.sh --json; fi` | PASS | Active session resolved to `phase22-session03-legion-enemy-reducer`; package scope is `apps/web`; monorepo is true. | | Base commit | `git rev-parse --verify --quiet 42d1d1230fe00c3e6ce66b3c631eebac53677768^{commit}` | PASS | Base commit exists locally. | | Inventory | `git status --short --branch`; `git log --oneline "$BASE"..HEAD`; `git diff --name-status "$BASE"`; `git diff --cached --name-status "$BASE"`; `git ls-files --others --exclude-standard` | PASS | Review surface identified 3 tracked modified files, 3 pre-review untracked session artifacts, no staged changes, and no mid-session commits. | | Source context | Targeted inspection of `.spec_system/CONVENTIONS.md`, `.spec_system/CONSIDERATIONS.md`, session `spec.md`, `tasks.md`, `implementation-notes.md`, `README.md`, `docs/README_docs.md`, `docs/development.md`, `docs/privacy-and-security.md`, `apps/README_apps.md`, `apps/web/README_web.md`, `packages/protocol/README_protocol.md`, root `package.json`, `apps/web/package.json`, `biome.jsonc`, `apps/web/tsconfig.json`, and `vitest.config.ts` | PASS | Confirmed npm workspace conventions, Biome format/lint, web TypeScript typecheck, Vitest web project, pure-helper package scope, privacy boundaries, and no UI scope. | | Protocol context | Targeted inspection of `packages/protocol/src/events.ts` and current ID conventions via \`rg -n "heroId | taskId | planId | | Required checklists | Targeted inspection of `references/behavioral-quality-checklist.md`, `references/security-compliance-checklist.md`, and `references/ui-surface-checklist.md` | PASS | Behavioral trust-boundary, contract-alignment, privacy, and UI product-surface categories were applied to the review. | | Reducer review | Targeted inspection of `apps/web/src/lib/gameProjection.ts` plus `git diff --unified=80 "$BASE" -- apps/web/src/lib/gameProjection.ts` | PASS | Found and repaired unsafe enemy-token persistence; final reread found no remaining mutation, replay accumulation, focus-priority, parser-compatibility, or contract-alignment issue. | | Test review | Targeted inspection of `apps/web/tests/gameProjection.test.ts` plus `git diff --unified=80 "$BASE" -- apps/web/tests/gameProjection.test.ts` | PASS | Tests cover dev-health, siege, wraith stacks, replay guards, focus promotion, parser rejection, and raw-sensitive-string exclusions, including the creview-added unsafe ID cases. | | State artifact review | Targeted inspection of `.spec_system/state.json`, `git diff "$BASE" -- .spec_system/state.json`, \`jq '.next\_session\_history | length' .spec\_system/state.json`,` git show 42d1d1230fe00c3e6ce66b3c631eebac53677768:.spec\_system/state.json | jq '.next\_session\_history | | Spec artifact review | Targeted inspection of untracked `spec.md`, `tasks.md`, and `implementation-notes.md` plus prior Phase 22 session specs | PASS | Session artifacts are text, task completion is recorded in `tasks.md` and `implementation-notes.md`, and the unchanged spec lifecycle wording matches local precedent. | | Tests | `npm test -- apps/web/tests/gameProjection.test.ts` | PASS | 1 test file passed; 20 tests passed; 0 failed. | | Type checker | `npm --workspace @factionos/web run typecheck` | PASS | `tsc -b --noEmit` exited 0. | | Linter / Formatter | `npm exec -- biome check apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjection.test.ts` | PASS | 2 files checked; no fixes applied. | | Whitespace | `git diff --check "$BASE"` | PASS | No whitespace errors in the full review diff. | | ASCII | `LC_ALL=C grep -nP '[^\x00-\x7F]' apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjection.test.ts .spec_system/specs/phase22-session03-legion-enemy-reducer/spec.md .spec_system/specs/phase22-session03-legion-enemy-reducer/tasks.md .spec_system/specs/phase22-session03-legion-enemy-reducer/implementation-notes.md .spec_system/specs/phase22-session03-legion-enemy-reducer/code-review.md .spec_system/state.json; test $? -eq 1` | PASS | No non-ASCII bytes found in changed code, session artifacts, review report, or state. | | LF line endings | `rg -nU $'\r' apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjection.test.ts .spec_system/specs/phase22-session03-legion-enemy-reducer .spec_system/state.json; test $? -eq 1` | PASS | No CRLF matches found in changed code, session artifacts, review report, or state. | | Final diff re-read | `git diff "$BASE"` plus untracked text files | PASS | Final reread found no remaining review findings. | ## Summary 1. Reviewed 7 files in the final surface: 3 tracked modified files, 3 pre-review untracked session artifacts, and this `code-review.md` report. 2. Findings by severity: 0 critical, 0 high, 1 medium, 0 low; the medium privacy finding was fixed. 3. The only deliberate non-fixes were expected state history trimming and established spec lifecycle wording. 4. Evidence passed for focused Vitest, web typecheck, Biome check, whitespace, ASCII, LF, and final diff re-read. --- # 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-session03-legion-enemy-reducer/code-review.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.