> 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/code-review.md). # Code Review and Repair Report **Session ID**: `phase22-session01-projection-contract` **Package**: apps/web **Reviewed**: 2026-07-05 **Base Commit**: 47f67eb86007df0d3fd829db4baa485fa7cdbbaf **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/PRD/phase_22/PRD_phase_22.md` - tracked-modified; Phase 22 source-of-truth condensation and session split. * `.spec_system/state.json` - tracked-modified; current session activation plus Session 22 history entry. * `.spec_system/specs/phase20-session01-truthful-capability-baseline/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session01-truthful-capability-baseline/`. * `.spec_system/specs/phase20-session02-queue-terminal-execution/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session02-queue-terminal-execution/`. * `.spec_system/specs/phase20-session03-queue-git-execution/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session03-queue-git-execution/`. * `.spec_system/specs/phase20-session04-campaign-executable-dispatch/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session04-campaign-executable-dispatch/`. * `.spec_system/specs/phase20-session05-campaign-dag-recovery/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session05-campaign-dag-recovery/`. * `.spec_system/specs/phase20-session06-file-mutation-core/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session06-file-mutation-core/`. * `.spec_system/specs/phase20-session07-file-executor-integration/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session07-file-executor-integration/`. * `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session08-managed-agent-lifecycle-control/`. * `.spec_system/specs/phase20-session09-container-dispatch-decision/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session09-container-dispatch-decision/`. * `.spec_system/specs/phase20-session10-templates-and-channel-intake/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session10-templates-and-channel-intake/`. * `.spec_system/specs/phase20-session11-release-evidence-and-event-privacy/*` - tracked-deleted; archived exact copies exist under `.spec_system/archive/sessions/phase20-session11-release-evidence-and-event-privacy/`. * `.spec_system/archive/sessions/phase20-session01-truthful-capability-baseline/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session02-queue-terminal-execution/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session03-queue-git-execution/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session04-campaign-executable-dispatch/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session05-campaign-dag-recovery/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session06-file-mutation-core/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session07-file-executor-integration/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session08-managed-agent-lifecycle-control/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session09-container-dispatch-decision/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session10-templates-and-channel-intake/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/archive/sessions/phase20-session11-release-evidence-and-event-privacy/{IMPLEMENTATION_SUMMARY.md,code-review.md,implementation-notes.md,release-evidence.md,security-compliance.md,spec.md,tasks.md,validation.md}` - untracked archive relocation. * `.spec_system/specs/phase22-session01-projection-contract/spec.md` - untracked current session spec. * `.spec_system/specs/phase22-session01-projection-contract/tasks.md` - untracked current session tasks. * `.spec_system/specs/phase22-session01-projection-contract/implementation-notes.md` - untracked implementation notes. * `apps/web/src/lib/gameProjection.ts` - untracked new runtime module. * `apps/web/tests/gameProjection.test.ts` - untracked focused tests. * `.spec_system/specs/phase22-session01-projection-contract/code-review.md` - generated by this creview command. **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:472` - Persisted projection validation accepted extra fixed nested keys under `essence.burst` and `buildings`, which could retain untrusted data in a supposedly versioned aggregate snapshot. | Fix: Added exact-key validation for fixed nested records and regression cases for extra `selectedFaction` and `rawPrompts` nested keys. | Status: FIXED ### Low * `.spec_system/state.json:477` - Session planning changed `next_session_history` by dropping older Phase 19, Phase 20, and early Phase 21 history entries while adding the Phase 22 planning entry. | Fix: Restored the base history and appended the new Phase 22 planning entry, leaving `current_session` set to this active session. | Status: FIXED ## Assumptions and Deliberate Non-Fixes * The Phase 20 live-spec deletions were treated as archive relocation, not content deletion, because `git show "$BASE:$old" | cmp -s - "$path"` passed for every untracked archive copy. * The condensed Phase 22 PRD was left unchanged because direct inspection confirmed it still defines the Projection Foundation scope, session list, `GameProjection` shape, storage key, no-UI boundary, persistence/honesty requirements, and Session 01 implementation surface. * The `pendingLinks.prompt` field was left in the public type because the Phase 22 PRD explicitly defines that field for later camp-link matching; Session 01 does not record pending links, and the no-op reducer cannot persist a prompt. ## Behavior Changes * Invalid persisted projection snapshots with extra fixed nested keys under `buildings` or `essence.burst` now fail closed to a fresh projection instead of being accepted. ## Evidence Ledger Every row names the exact command or targeted inspection used. | Check | Command or Inspection | Result | Evidence / Blocker | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Project state | `bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.18-codex/skills/apex-spec/scripts/analyze-project.sh --json` | PASS | Current session is `phase22-session01-projection-contract`; monorepo true; package candidates include `apps/web`; session files exist. | | Base commit | `git rev-parse --verify --quiet "47f67eb86007df0d3fd829db4baa485fa7cdbbaf^{commit}"` | PASS | Resolved base commit `47f67eb86007df0d3fd829db4baa485fa7cdbbaf`. | | Inventory | `git status`; `git log --oneline "$BASE"..HEAD`; `git diff "$BASE"`; `git diff --cached "$BASE"`; `git ls-files --others --exclude-standard` | PASS | No mid-session commits; no staged diff; tracked and untracked surfaces inventoried. | | Archive relocation | \`git show "$BASE:$old" | cmp -s - "$path"`for every`.spec\_system/archive/sessions/phase20-\*\` untracked file | PASS | | Session context | `sed -n '1,260p' .spec_system/specs/phase22-session01-projection-contract/spec.md`; `tasks.md`; `implementation-notes.md` | PASS | Tasks are 19/19 complete; implementation limited to `gameProjection.ts`, focused tests, and spec artifacts before review repairs. | | Local conventions | `.spec_system/CONVENTIONS.md`, `.spec_system/CONSIDERATIONS.md`, `README.md`, `docs/README_docs.md`, `apps/web/README_web.md`, `package.json`, `apps/web/package.json`, `biome.jsonc`, `apps/web/tsconfig.json`, `vitest.config.ts` | PASS | Confirmed npm workspaces, Biome, TypeScript, Vitest, pure helper location, privacy boundaries, and no UI surface for this session. | | Focused tests | `npm test -- apps/web/tests/gameProjection.test.ts` | PASS | 1 test file passed; 10 tests passed. | | Web type checker | `npm --workspace @factionos/web run typecheck` | PASS | `tsc -b --noEmit` exited 0. | | Workspace type checker | `npm run typecheck --workspaces --if-present` | PASS | Adapters, server, warroom, web, protocol, and public-website typechecks exited 0. | | Formatter | `npm run format:check` | PASS | 773 files checked; no fixes applied. | | Linter | `npm run lint` | PASS | 775 files checked; no fixes applied. | | Changed-file Biome check | `npm exec -- biome check apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjection.test.ts` | PASS | 2 files checked; no fixes applied. | | ASCII | `LC_ALL=C grep -nP '[^\x00-\x7F]' apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjection.test.ts .spec_system/specs/phase22-session01-projection-contract/spec.md .spec_system/specs/phase22-session01-projection-contract/tasks.md .spec_system/specs/phase22-session01-projection-contract/implementation-notes.md` | PASS | Command printed `ASCII PASS`. | | LF | `rg -nU $'\r' apps/web/src/lib/gameProjection.ts apps/web/tests/gameProjection.test.ts .spec_system/specs/phase22-session01-projection-contract/spec.md .spec_system/specs/phase22-session01-projection-contract/tasks.md .spec_system/specs/phase22-session01-projection-contract/implementation-notes.md` | PASS | Command printed `LF PASS`. | | Whitespace | `git diff --check` | PASS | No whitespace errors. | | Final diff re-read | `git diff "$BASE"` plus `git ls-files --others --exclude-standard`, `nl -ba apps/web/src/lib/gameProjection.ts`, `nl -ba apps/web/tests/gameProjection.test.ts`, and archive-copy `cmp` loop | PASS | No remaining review findings after fixes. | ## Summary 1. Reviewed all changes since base commit `47f67eb86007df0d3fd829db4baa485fa7cdbbaf`: 80 tracked paths plus 83 pre-report untracked paths, including 78 exact archive copies, 3 session files, and 2 new web files. 2. Findings: 0 Critical, 0 High, 1 Medium, 1 Low. Both were fixed. 3. Deliberate non-fixes: Phase 20 archive relocation was exact; Phase 22 PRD condensation still carries the required source contract; `pendingLinks.prompt` remains because it is explicitly in the PRD and Session 01 does not populate it. 4. Evidence: focused Vitest, web and workspace typechecks, root format/lint, changed-file Biome, ASCII, LF, whitespace, archive-copy verification, and final diff re-read passed. --- # 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/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.