> 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/specs/phase24-session06-world-cues-and-bark-reuse/code-review.md). # Code Review and Repair Report **Session ID**: `phase24-session06-world-cues-and-bark-reuse` **Package**: apps/web **Reviewed**: 2026-07-08 **Base Commit**: 971f022685f53643def9d1ba5cfb59e9e8367fa2 **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 * `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - untracked * `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/spec.md` - untracked * `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - untracked * `apps/web/src/components/battlefield/Battlefield.tsx` - tracked-modified * `apps/web/src/lib/audioRuntime.ts` - tracked-modified * `apps/web/src/lib/fileVoiceSynth.ts` - tracked-modified * `apps/web/src/lib/sfxAssets.ts` - tracked-modified * `apps/web/src/lib/voiceSynth.ts` - tracked-modified * `apps/web/src/lib/worldCues.ts` - untracked * `apps/web/src/store/useAudioRuntimeStore.ts` - tracked-modified * `apps/web/src/store/useVoiceBarks.ts` - tracked-modified * `apps/web/src/store/useWorldCues.ts` - untracked * `apps/web/tests/Battlefield.test.tsx` - tracked-modified * `apps/web/tests/HeroDetailDrawerComplexity.test.tsx` - tracked-modified * `apps/web/tests/HeroDetailDrawerEfficiency.test.tsx` - tracked-modified * `apps/web/tests/HeroDetailDrawerToolUsage.test.tsx` - tracked-modified * `apps/web/tests/MissionComplexityOverlay.test.tsx` - tracked-modified * `apps/web/tests/ToolUsageOverlay.test.tsx` - tracked-modified * `apps/web/tests/audioRuntime.test.ts` - tracked-modified * `apps/web/tests/fileVoiceSynth.test.ts` - tracked-modified * `apps/web/tests/heroAttribution.test.tsx` - tracked-modified * `apps/web/tests/useWorldCues.test.tsx` - untracked * `apps/web/tests/worldCues.test.ts` - untracked **Inventory commands**: `git status`, `git log --oneline "$BASE"..HEAD`, `git diff "$BASE"`, `git diff --cached "$BASE"`, `git ls-files --others --exclude-standard` No mid-session commits were present. ## Findings by Severity ### Critical * No findings. ### High * `apps/web/tests/HeroDetailDrawerComplexity.test.tsx:36`, `apps/web/tests/HeroDetailDrawerEfficiency.test.tsx:33`, `apps/web/tests/HeroDetailDrawerToolUsage.test.tsx:37`, `apps/web/tests/MissionComplexityOverlay.test.tsx:35`, `apps/web/tests/ToolUsageOverlay.test.tsx:39`, `apps/web/tests/heroAttribution.test.tsx:32` - Full `npm test` failed before collecting these suites because their `../src/lib/voiceSynth` mocks did not define the new `playWorldCue` export consumed by `fileVoiceSynth.ts`. Fix: added `playWorldCue` to all six mocks and reran the failed set plus full `npm test`. Status: FIXED ### Medium * `apps/web/src/store/useWorldCues.ts:42` - `useWorldCues` persisted world cue rate histories even when audio was disabled or volume was zero, and already seen disabled candidates still participated in the next derivation. Six disabled `camp_hit` moments could consume the per-minute budget and suppress the first new eligible cue after the operator enabled audio. Fix: added `WorldCueDerivationOptions.skipKeys` in `apps/web/src/lib/worldCues.ts`, passed the hook's seen-key set before rate decisions, and only stored category histories when playback is eligible. Added regression coverage in `apps/web/tests/useWorldCues.test.tsx`. Status: FIXED ### Low * No findings. ## Assumptions and Deliberate Non-Fixes * `npm test` and the focused Battlefield suite still print React `act(...)` warnings in pre-existing Battlefield live Legion tests. Targeted output attributed the warnings to existing tests, all assertions passed, and the Session 06 world-cue integration added no new warning-only failure. No code change was made for those unrelated warning sites. * The first documented fallback script path for `analyze-project.sh` did not exist in this plugin install. The command was rerun with the actual skill script path, and the passing command is recorded in the Evidence Ledger. ## Behavior Changes * Disabled or zero-volume world cue observations remain marked as seen so old evidence does not autoplay later, but they no longer spend per-category audio rate budget. A new cue observed after explicit audio opt-in can now play as intended. * No product UI, protocol event, server route, storage key, dependency, recorded audio asset, reward path, hosted claim, or trusted-erasure claim was added by the review repairs. ## Evidence Ledger Every row names the exact command or targeted inspection used. | Check | Command or Inspection | Result | Evidence / Blocker | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | Project analysis | `bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.19-codex/skills/apex-spec/scripts/analyze-project.sh --json` | PASS | Reported current session `phase24-session06-world-cues-and-bark-reuse`, monorepo true, active Phase 24, and Session 06 incomplete. | | Review base | `git rev-parse --verify --quiet "971f022685f53643def9d1ba5cfb59e9e8367fa2^{commit}"` | PASS | Base commit resolved to `971f022685f53643def9d1ba5cfb59e9e8367fa2`. | | Inventory | `git status --short --branch`; `git log --oneline "$BASE"..HEAD`; `git diff --name-status "$BASE"`; `git diff --stat "$BASE"`; `git ls-files --others --exclude-standard` | PASS | Found no mid-session commits; reviewed tracked modified files and untracked session/source/test files listed above. | | Source context | Targeted inspection of `.spec_system/CONVENTIONS.md`, `.spec_system/CONSIDERATIONS.md`, session `spec.md`, `tasks.md`, `implementation-notes.md`, `apps/web/README_web.md`, and review checklists | PASS | Confirmed apps/web scope, audio opt-in posture, no-new-media boundary, product-surface discipline, and privacy constraints. | | Finding 1 regression | `npm test -- --run apps/web/tests/useWorldCues.test.tsx` | PASS | 1 file, 5 tests; new disabled-audio rate-budget regression passed. | | Finding 2 regression | `npm test -- --run apps/web/tests/HeroDetailDrawerComplexity.test.tsx apps/web/tests/HeroDetailDrawerEfficiency.test.tsx apps/web/tests/HeroDetailDrawerToolUsage.test.tsx apps/web/tests/MissionComplexityOverlay.test.tsx apps/web/tests/ToolUsageOverlay.test.tsx apps/web/tests/heroAttribution.test.tsx` | PASS | 6 files, 150 tests; voiceSynth mock import failures resolved. | | Focused session tests | `npm test -- --run apps/web/tests/audioRuntime.test.ts apps/web/tests/fileVoiceSynth.test.ts apps/web/tests/worldCues.test.ts apps/web/tests/useWorldCues.test.tsx apps/web/tests/Battlefield.test.tsx` | PASS | 5 files, 74 tests; Battlefield emitted existing `act(...)` warnings but assertions passed. | | Full tests | `npm test` | PASS | 287 test files passed, 1 skipped; 3375 tests passed, 1 skipped. | | Type checker | `npm --workspace apps/web run typecheck` | PASS | `tsc -b --noEmit` completed successfully. | | Formatter | `npm run format:check` | PASS | Biome checked 791 files with no fixes needed. | | Linter | `npm run lint` | PASS | Biome checked 793 files with no fixes needed. | | Whitespace | `git diff --check 971f022685f53643def9d1ba5cfb59e9e8367fa2` | PASS | No whitespace errors. | | ASCII/LF | Shell check over reviewed app, test, and session files with `grep -IlP '[^\x00-\x7F]'` and CRLF scan | PASS | `ASCII_LF_PASS`; no non-ASCII bytes or CRLF line endings found. | | Final diff re-read | `git diff --name-status "$BASE"`; `git diff --stat "$BASE"`; targeted `nl -ba` inspection of untracked files | PASS | Final review surface re-read after repairs; no unresolved findings remained. | ## Summary 1. Reviewed 24 files in the Session 06 surface: session artifacts, world cue derivation/hook/runtime/audio modules, Battlefield wiring, focused tests, and related test mocks exposed by full-suite verification. 2. Findings: 0 critical, 1 high, 1 medium, 0 low. Both findings were fixed with focused coverage and full-suite verification. 3. Deliberately not fixed: pre-existing Battlefield React `act(...)` warnings that do not fail tests and were not introduced by Session 06. 4. Evidence: focused tests, full `npm test`, web typecheck, Biome format check, Biome lint, whitespace, ASCII/LF, and final diff reread all 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/specs/phase24-session06-world-cues-and-bark-reuse/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.