> 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/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase24-session06-world-cues-and-bark-reuse` **Package**: apps/web **Started**: 2026-07-08 18:14 **Last Updated**: 2026-07-08 18:52

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 20 / 20 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

### Task T020 - Run focused tests, typecheck, ASCII, and LF checks

**Started**: 2026-07-08 18:48 **Completed**: 2026-07-08 18:52 **Duration**: 4 minutes

**Notes**:

* Ran the focused Session 06 test bundle, web typecheck, root Biome format check, and ASCII/LF checks.
* Fixed a TypeScript narrowing issue for optional world cue adapter playback and formatted two touched files with Biome.
* Replaced pre-existing non-ASCII section symbols in touched `sfxAssets.ts` comments with ASCII wording.

**Files Changed**:

* `apps/web/src/lib/audioRuntime.ts` - narrowed optional world cue adapter method before invocation.
* `apps/web/src/lib/sfxAssets.ts` - ASCII comment cleanup and Biome formatting.
* `apps/web/src/store/useVoiceBarks.ts` - Biome formatting.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T020 and completion checklist complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded final gate evidence.

**Verification**:

* Command/check: `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`
  * Result: PASS - 5 files, 73 tests.
  * Evidence: Focused audio/runtime/cue/hook/Battlefield suite passed after the final fixes. Battlefield tests still emit React act warnings in existing live Legion tests, but all assertions pass.
* Command/check: `npm --workspace apps/web run typecheck`
  * Result: PASS - `tsc -b --noEmit` completed successfully.
  * Evidence: Initial optional world adapter narrowing failure was fixed and rerun passed.
* Command/check: `npm run format:check`
  * Result: PASS - Biome checked 791 files with no fixes needed.
  * Evidence: Touched formatting issues were fixed with `npx biome format --write apps/web/src/lib/sfxAssets.ts apps/web/src/store/useVoiceBarks.ts`.
* Command/check: ASCII/LF shell check over touched app/test/session files
  * Result: PASS - `ASCII_LF_PASS`.
  * Evidence: No non-ASCII bytes or CRLF line endings found in the checked touched files.
* UI product-surface check: PASS - Battlefield integration adds no visible debug, diagnostic, or world-cue UI.
* UI craft check: PASS - no layout or visual treatment changed.

***

### Task T019 - Add Battlefield event-to-cue integration coverage

**Started**: 2026-07-08 18:46 **Completed**: 2026-07-08 18:48 **Duration**: 2 minutes

**Notes**:

* Added Battlefield integration coverage that enables mocked audio, seeds a linked combat event plus live skirmisher/focus anchors, and verifies world cue routing.
* Confirmed the integration adds no visible world-cue/debug/diagnostic UI and preserves the existing combat playback visual.

**Files Changed**:

* `apps/web/tests/Battlefield.test.tsx` - added event-to-cue routing coverage and audio runtime mock reset.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T019 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/Battlefield.test.tsx`
  * Result: PASS - 1 file, 36 tests.
  * Evidence: New integration observes `camp_hit`, `ram_break_triumph`, and `skirmisher_red_slash` world cue requests, no debug/diagnostic/world-cue copy appears in the Battlefield DOM, and combat playback strike output remains rendered. The file still emits React act warnings in existing live Legion tests, but all assertions pass.
* UI product-surface check: PASS - no new visible diagnostic surface is rendered.
* UI craft check: PASS - no layout or visual treatment changed.

***

### Task T018 - Extend file synth tests

**Started**: 2026-07-08 18:44 **Completed**: 2026-07-08 18:46 **Duration**: 2 minutes

**Notes**:

* Added file-backed adapter coverage for world cue file-first routing and world synth fallback.
* Existing bark file-first, bark fallback, support delegation, and manifest tests remain passing.

**Files Changed**:

* `apps/web/tests/fileVoiceSynth.test.ts` - added world file-first and fallback tests.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T018 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/fileVoiceSynth.test.ts`
  * Result: PASS - 1 file, 10 tests.
  * Evidence: A mapped world cue URL plays via `playUrl` before synth; a blocked/missing world file falls back to `playWorldCue`; existing bark tests still pass.
* UI product-surface check: N/A - adapter tests only.
* UI craft check: N/A - adapter tests only.

***

### Task T017 - Extend audio runtime tests

**Started**: 2026-07-08 18:42 **Completed**: 2026-07-08 18:44 **Duration**: 2 minutes

**Notes**:

* Extended runtime coverage for world cue validation, muted volume, unsupported state, playing state, duplicate cue guard behavior, and redacted failure details.

**Files Changed**:

* `apps/web/tests/audioRuntime.test.ts` - added world cue runtime matrix coverage.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T017 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/audioRuntime.test.ts`
  * Result: PASS - 1 file, 16 tests.
  * Evidence: World cue requests validate, play, mute at zero volume, stop before unsupported playback, redact unknown failures, and respect duplicate cue guard release by prefix.
* UI product-surface check: N/A - runtime tests only.
* UI craft check: N/A - runtime tests only.

***

### Task T016 - Write useWorldCues hook tests

**Started**: 2026-07-08 18:40 **Completed**: 2026-07-08 18:42 **Duration**: 2 minutes

**Notes**:

* Added hook tests for runtime world cue calls, disabled-audio no replay, duplicate rerender prevention, cleanup prefixes, and hero actor bark reuse.

**Files Changed**:

* `apps/web/tests/useWorldCues.test.tsx` - expanded hook coverage and runtime mocks.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T016 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/useWorldCues.test.tsx`
  * Result: PASS - 1 file, 4 tests.
  * Evidence: `playWorldCue` receives `camp_hit`, actor barks reuse bark runtime requests, rerender does not duplicate calls, disabled audio does not replay stale cues, and unmount clears `world-cue:` plus `hero-actor:` prefixes.
* UI product-surface check: N/A - hook tests only.
* UI craft check: N/A - hook tests only.

***

### Task T015 - Write pure world cue tests

**Started**: 2026-07-08 18:38 **Completed**: 2026-07-08 18:40 **Duration**: 2 minutes

**Notes**:

* Expanded pure coverage for all six world cues, actor bark reuse, category budgets, replay/future rejection, unlinked events, and safe labels.

**Files Changed**:

* `apps/web/tests/worldCues.test.ts` - added world cue, actor bark, rejection, and privacy fixtures.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T015 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/worldCues.test.ts`
  * Result: PASS - 1 file, 7 tests.
  * Evidence: All six `WorldCueKind` values derive from real anchors; actor bark candidates cover `error`, `celebration`, and `complete`; replayed, future, and unlinked inputs derive no candidates; unsafe labels and raw paths are absent from serialized candidates.
* UI product-surface check: N/A - pure tests only.
* UI craft check: N/A - pure tests only.

***

### Task T014 - Confirm no diagnostics or write path

**Started**: 2026-07-08 18:36 **Completed**: 2026-07-08 18:38 **Duration**: 2 minutes

**Notes**:

* Confirmed Battlefield wiring adds only a hook import, replay selector, and hook invocation.
* Confirmed the cue hook and pure helper do not add JSX, user-facing diagnostic copy, storage calls, projection mutation, protocol events, or server calls.

**Files Changed**:

* `apps/web/src/components/battlefield/Battlefield.tsx` - inspected hook-only integration.
* `apps/web/src/store/useWorldCues.ts` - inspected transient ref/runtime-only behavior.
* `apps/web/src/lib/worldCues.ts` - inspected pure derivation-only behavior.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T014 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `rg -n "useWorldCues|world-cue|hero-actor|localStorage|sessionStorage|applyEvent|setState|fetch\\(|WebSocket|debug|diagnostic|protocol|server|storage" apps/web/src/components/battlefield/Battlefield.tsx apps/web/src/store/useWorldCues.ts apps/web/src/lib/worldCues.ts`
  * Result: PASS - matches are limited to imports, hook call, cue prefixes, cleanup prefixes, type-only protocol imports, and pre-existing Battlefield asset state.
  * Evidence: No new storage, fetch, WebSocket, projection write, debug, diagnostic, protocol event, or server path appeared.
* Command/check: `npm test -- --run apps/web/tests/useWorldCues.test.tsx apps/web/tests/worldCues.test.ts`
  * Result: PASS - 2 files, 5 tests.
  * Evidence: Pure and hook behaviors remain passing after Battlefield wiring.
* UI product-surface check: PASS - no rendered UI or diagnostics were added.
* UI craft check: PASS - no layout or visual treatment changed.

***

### Task T013 - Preserve no-autoplay and unsupported/replay/unlinked boundaries

**Started**: 2026-07-08 18:34 **Completed**: 2026-07-08 18:36 **Duration**: 2 minutes

**Notes**:

* `useWorldCues` skips playback when audio is disabled or volume is zero, while still marking observed cues as seen so old cues do not autoplay later.
* Replayed inputs derive no candidates, unsupported playback remains handled by the runtime, and unlinked completion events are rejected by pure derivation.

**Files Changed**:

* `apps/web/src/store/useWorldCues.ts` - already enforces disabled/zero-volume skip and replay pass-through.
* `apps/web/tests/useWorldCues.test.tsx` - added no-replay-after-disabled-audio regression coverage.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T013 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/useWorldCues.test.tsx`
  * Result: PASS - 1 file, 2 tests.
  * Evidence: A camp-hit candidate observed while audio is disabled does not call `playWorldCue`, and enabling audio with the same evidence still does not replay it.
* BQC Fixes:
  * State freshness on re-entry: seen-key tracking prevents stale disabled-audio evidence from firing after settings change (`apps/web/src/store/useWorldCues.ts`).
* UI product-surface check: N/A - no rendered UI changed.
* UI craft check: N/A - no layout or visual treatment changed.

***

### Task T012 - Wire useWorldCues into Battlefield

**Started**: 2026-07-08 18:32 **Completed**: 2026-07-08 18:34 **Duration**: 2 minutes

**Notes**:

* Wired `useWorldCues` into `Battlefield.tsx` using the existing combat playback, live legion, alert focus, event log, projection, visible heroes, missions, and replay state.
* Kept the hook presentation-owned and transient; no projection, storage, protocol, server, or DOM write path was added.

**Files Changed**:

* `apps/web/src/components/battlefield/Battlefield.tsx` - imported and invoked `useWorldCues`.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T012 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: Targeted inspection of `apps/web/src/components/battlefield/Battlefield.tsx`
  * Result: PASS - hook receives `combatPlayback`, `liveLegion`, `scryingAndAlertFocus`, `eventLog`, `gameProjection`, `visibleHeroes`, `missionsById`, `combatPlaybackNowMs`, and replay state.
  * Evidence: No JSX, UI labels, storage calls, protocol calls, or server calls were added with the hook wiring.
* UI product-surface check: PASS - no rendered product surface was added or changed; the hook has no DOM output.
* UI craft check: PASS - no layout or visual treatment changed.

***

### Task T011 - Implement useWorldCues hook

**Started**: 2026-07-08 18:30 **Completed**: 2026-07-08 18:32 **Duration**: 2 minutes

**Notes**:

* Added a presentation-owned hook that derives candidates, owns seen keys, threads category histories, retains transient camp links for completion barks, and skips playback when audio is disabled or volume is zero.
* The hook routes world cues through `playWorldCue` and actor barks through `buildHeroBarkRequest`, then clears world and actor cue scopes on unmount.

**Files Changed**:

* `apps/web/src/store/useWorldCues.ts` - implemented hook, transient refs, retained link cap, duplicate checks, and cleanup.
* `apps/web/tests/useWorldCues.test.tsx` - added a real hook mount smoke test.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T011 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/useWorldCues.test.tsx`
  * Result: PASS - 1 file, 1 test.
  * Evidence: The real hook mounts and unmounts with valid empty cue input.
* BQC Fixes:
  * Resource cleanup: unmount clears seen keys, histories, retained links, and runtime cue prefixes (`apps/web/src/store/useWorldCues.ts`).
  * Duplicate action prevention: seen keys plus runtime in-flight cue checks prevent repeat calls on rerender (`apps/web/src/store/useWorldCues.ts`).
* UI product-surface check: N/A - no rendered Battlefield UI changed.
* UI craft check: N/A - no layout or visual treatment changed.

***

### Task T010 - Reuse hero-bark request semantics

**Started**: 2026-07-08 18:28 **Completed**: 2026-07-08 18:30 **Duration**: 2 minutes

**Notes**:

* Extracted `buildHeroBarkRequest` from the existing voice-bark hook.
* Existing hero state transitions and new actor moments can now share the same runtime request shape, safe label bound, audio opt-in flag, and volume handling.

**Files Changed**:

* `apps/web/src/store/useVoiceBarks.ts` - added `buildHeroBarkRequest` and routed state-transition barks through it.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T010 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/SettingsAudio.test.tsx`
  * Result: PASS - 1 file, 7 tests.
  * Evidence: Existing audio opt-in surface still passes after request helper extraction.
* BQC Fixes:
  * Error information boundaries: helper bounds and redacts unsafe bark labels before they reach runtime result state (`apps/web/src/store/useVoiceBarks.ts`).
* UI product-surface check: N/A - no rendered Battlefield UI changed.
* UI craft check: N/A - no layout or visual treatment changed.

***

### Task T009 - Apply per-category cue histories

**Started**: 2026-07-08 18:26 **Completed**: 2026-07-08 18:28 **Duration**: 2 minutes

**Notes**:

* Threaded category histories through `shouldPlayCue` for all materialized world and hero-bark candidates.
* Returned denied candidates with `allowed: false` so visuals and derivation remain authoritative while audio is suppressed.

**Files Changed**:

* `apps/web/src/lib/worldCues.ts` - applies `shouldPlayCue` and returns updated per-category histories.
* `apps/web/tests/worldCues.test.ts` - added regression coverage for category-budget suppression.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T009 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/worldCues.test.ts`
  * Result: PASS - 1 file, 3 tests.
  * Evidence: Seven camp-hit candidates are still derived, but only the first six are `allowed`; the `world:camp_hit` history remains capped at six entries.
* BQC Fixes:
  * Contract alignment: the pure result separates candidate presence from audio allowance so visual presentation is not coupled to audio playback (`apps/web/src/lib/worldCues.ts`).
* UI product-surface check: N/A - no rendered UI changed.
* UI craft check: N/A - no rendered UI changed.

***

### Task T008 - Implement pure cue candidate derivation

**Started**: 2026-07-08 18:24 **Completed**: 2026-07-08 18:26 **Duration**: 2 minutes

**Notes**:

* Replaced the scaffold with a pure derivation model for world cues and hero-actor bark candidates.
* Derived camp hit/collapse from combat playback, ram/skirmisher from live legion presentation, build-fix triumph from real events, and flare attention from projection-owned focus.
* Added replay, future, stale, duplicate, malformed-input, safe-label, and hashed cue-id boundaries.

**Files Changed**:

* `apps/web/src/lib/worldCues.ts` - implemented pure cue derivation and candidate materialization.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T008 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/worldCues.test.ts`
  * Result: PASS - 1 file, 2 tests.
  * Evidence: Current scaffold tests import the full pure module successfully and malformed input returns explicit `invalid_input` without throwing.
* BQC Fixes:
  * Trust boundary enforcement: `deriveWorldCueCandidates` validates the required input shape before inspecting nested presentation state (`apps/web/src/lib/worldCues.ts`).
  * Error information boundaries: cue IDs are hashed and labels are bounded/generic so raw event paths, prompts, and secrets do not become candidate output (`apps/web/src/lib/worldCues.ts`).
* UI product-surface check: N/A - no rendered UI changed.
* UI craft check: N/A - no rendered UI changed.

***

### Task T007 - Expose world cue playback through the runtime store

**Started**: 2026-07-08 18:22 **Completed**: 2026-07-08 18:24 **Duration**: 2 minutes

**Notes**:

* Added a typed `playWorldCue` store action that uses the same in-flight cue guard as existing bark playback.
* Refactored store cue playback into a shared guarded runner so duplicate protection, result recording, delayed release, and cleanup behavior stay aligned.

**Files Changed**:

* `apps/web/src/store/useAudioRuntimeStore.ts` - added `playWorldCue` and shared guarded cue runner.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T007 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/SettingsAudio.test.tsx`
  * Result: PASS - 1 file, 7 tests.
  * Evidence: Existing Settings audio surface and store action shape still work after adding `playWorldCue`.
* UI product-surface check: N/A - no rendered Battlefield UI changed; Settings audio regression retained existing product-facing copy.
* UI craft check: N/A - no layout or visual treatment changed.

***

### Task T006 - Add runtime world cue validation and playback mapping

**Started**: 2026-07-08 18:21 **Completed**: 2026-07-08 18:22 **Duration**: 1 minute

**Notes**:

* Added `cueType: "world"` runtime requests with manifest-backed kind validation.
* Routed valid world requests to adapter `playWorldCue` while preserving muted, unsupported, failed, and redacted failure behavior.

**Files Changed**:

* `apps/web/src/lib/audioRuntime.ts` - added world runtime request types, validation, playback dispatch, and stable world cue failure reason.
* `apps/web/tests/audioRuntime.test.ts` - added world request schema, muted, playback, and redaction coverage.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T006 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/audioRuntime.test.ts`
  * Result: PASS - 1 file, 14 tests.
  * Evidence: World requests validate, call `playWorldCue`, suppress volume-zero playback as muted, and redact unknown failure reasons.
* UI product-surface check: N/A - no rendered UI changed.
* UI craft check: N/A - no rendered UI changed.

***

### Task T005 - Extend file-backed adapter for world cues

**Started**: 2026-07-08 18:20 **Completed**: 2026-07-08 18:21 **Duration**: 1 minute

**Notes**:

* Added world cue URL resolution to the file-backed adapter.
* Kept bark adapter stubs backward-compatible by making the world synth method optional on the shared adapter contract.

**Files Changed**:

* `apps/web/src/lib/fileVoiceSynth.ts` - added `resolveWorldUrl`, `playWorldCue`, and synth fallback routing.
* `apps/web/src/lib/audioRuntime.ts` - extended `VoiceSynthAdapter` with optional world cue playback support.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T005 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/fileVoiceSynth.test.ts`
  * Result: PASS - 1 file, 8 tests.
  * Evidence: Existing file-first bark routing, synth fallback, support delegation, and manifest behavior remain passing.
* UI product-surface check: N/A - no rendered UI changed.
* UI craft check: N/A - no rendered UI changed.

***

### Task T004 - Add synth world cue recipes

**Started**: 2026-07-08 18:18 **Completed**: 2026-07-08 18:20 **Duration**: 2 minutes

**Notes**:

* Added deterministic synth recipes for all six world cue kinds.
* Extracted shared recipe playback so world cues inherit the existing AudioContext resume, locked, blocked, failed, and cleanup behavior.

**Files Changed**:

* `apps/web/src/lib/voiceSynth.ts` - added `WORLD_STYLE`, `playWorldCue`, and shared `playRecipe`.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T004 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: Targeted inspection of `apps/web/src/lib/voiceSynth.ts`
  * Result: PASS - `WORLD_STYLE` covers every `WorldCueKind` and `playWorldCue` delegates to the same cleanup-safe playback path as `playBark`.
  * Evidence: Six keys are defined: `camp_hit`, `camp_collapse`, `ram_crash`, `ram_break_triumph`, `skirmisher_red_slash`, and `flare_attention`.
* Command/check: `npm test -- --run apps/web/tests/fileVoiceSynth.test.ts apps/web/tests/worldCues.test.ts`
  * Result: PASS - last run in T003, 2 files, 10 tests after manifest/type wiring.
  * Evidence: Existing bark imports remained valid after the synth refactor.
* UI product-surface check: N/A - no rendered UI changed.
* UI craft check: N/A - no rendered UI changed.

***

### Task T003 - Extend SFX manifest with world cue lookup

**Started**: 2026-07-08 18:16 **Completed**: 2026-07-08 18:18 **Duration**: 2 minutes

**Notes**:

* Added manifest-owned `WorldCueKind` vocabulary and an explicit `SFX_FILES.world` bucket.
* Added `pickWorldSfxUrl` so world cues use the same file-first lookup semantics as faction barks.
* Kept the world bucket empty to preserve the no-new-recorded-asset boundary.

**Files Changed**:

* `apps/web/src/lib/sfxAssets.ts` - added world cue types, empty world manifest, lookup helper, and kind guard.
* `apps/web/src/lib/worldCues.ts` - re-exported the manifest-owned world cue vocabulary.
* `apps/web/tests/fileVoiceSynth.test.ts` - added manifest coverage for the empty world bucket.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T003 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `npm test -- --run apps/web/tests/fileVoiceSynth.test.ts apps/web/tests/worldCues.test.ts`
  * Result: PASS - 2 files, 10 tests.
  * Evidence: Existing faction file lookups still pass; world bucket coverage reports `SFX_FILES.world` as empty and `pickWorldSfxUrl("camp_hit")` as `null`.
* UI product-surface check: N/A - no rendered UI changed.
* UI craft check: N/A - no rendered UI changed.

***

### Task T002 - Create world-cue source and test scaffolds

**Started**: 2026-07-08 18:15 **Completed**: 2026-07-08 18:16 **Duration**: 1 minute

**Notes**:

* Added the six Phase 24 world cue kinds and initial pure derivation result contracts.
* Added focused test file paths for pure world cue coverage and hook coverage.

**Files Changed**:

* `apps/web/src/lib/worldCues.ts` - created world cue type vocabulary and initial input guard.
* `apps/web/tests/worldCues.test.ts` - added initial cue-kind and malformed-input coverage.
* `apps/web/tests/useWorldCues.test.tsx` - added hook coverage scaffold.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T002 complete.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: Targeted inspection of `apps/web/src/lib/worldCues.ts`
  * Result: PASS - source file exports all six required cue kinds and returns a safe invalid-input error.
  * Evidence: `WORLD_CUE_KINDS` contains `camp_hit`, `camp_collapse`, `ram_crash`, `ram_break_triumph`, `skirmisher_red_slash`, and `flare_attention`.
* Command/check: Targeted inspection of `apps/web/tests/worldCues.test.ts` and `apps/web/tests/useWorldCues.test.tsx`
  * Result: PASS - focused test paths exist for later pure and hook coverage.
  * Evidence: Both test files import under `apps/web/tests`.
* UI product-surface check: N/A - no rendered UI changed.
* UI craft check: N/A - no rendered UI changed.

***

## Task Log

### 2026-07-08 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed
* [x] Tools available
* [x] Directory structure ready

***

### Task T001 - Verify prerequisites and no-new-asset boundary

**Started**: 2026-07-08 18:12 **Completed**: 2026-07-08 18:14 **Duration**: 2 minutes

**Notes**:

* Confirmed active session `phase24-session06-world-cues-and-bark-reuse` and package `apps/web`.
* Read Session 04/05 implementation summaries, web package guidance, local-first/media ADRs, UX requirements, BQC, and UI surface checklist.
* Confirmed this session must add typed cue routing and synth fallback only; no recorded audio files or promoted media assets are in scope.

**Files Changed**:

* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/implementation-notes.md` - created progress log.
* `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/tasks.md` - marked T001 complete.

**Verification**:

* Command/check: `bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.19-codex/skills/apex-spec/scripts/analyze-project.sh --json`
  * Result: PASS - active session and `apps/web` package candidate resolved.
  * Evidence: Output reported current session, existing session directory, monorepo packages, and Session 06 incomplete.
* Command/check: `bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.19-codex/skills/apex-spec/scripts/check-prereqs.sh --json --env --package apps/web`
  * Result: PASS - spec system, jq, git, package directory, package manifest, and npm workspace manager available.
  * Evidence: `overall: pass`, npm `11.16.0`, package `apps/web`.
* Command/check: Targeted inspection of Session 04/05 summaries, `apps/web/README_web.md`, `docs/adr/0001-local-first-npm-workspace.md`, and `docs/adr/0004-quarantined-media-intake.md`
  * Result: PASS - existing playback/focus surfaces and no-new-media boundary confirmed.
  * Evidence: Session 04/05 summaries show presentation-only layers; ADR 0004 blocks direct promotion of unaudited media.
* UI product-surface check: N/A - prerequisite verification changed only spec artifacts.
* UI craft check: N/A - no rendered UI changed.

***


---

# 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/implementation-notes.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.