> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase36-session07-adaptive-stinger-pack/spec.md). # Session Specification **Session ID**: `phase36-session07-adaptive-stinger-pack` **Phase**: 36 - AI Rogue Audio Asset Finishing **Status**: Not Started **Created**: 2026-06-28 *** ## 1. Session Overview This session replaces the provisional adaptive-audio markers from Session 06 with dedicated short stinger assets for combat start, low HP pressure, boss reveal, objective unlock, final defense, victory transition, and defeat transition. The work keeps the existing adaptive request IDs and renderer derivation contract, then updates the audio profile mapping so real stinger files play through the bounded cooldown and music/theme ducking path that is already in place. This is next because the analyzer reports Phase 36 Sessions 01 through 06 as complete, and Session 08 depends on Session 07 before final validation and documentation closeout. Session 06 deliberately shipped no new stinger assets; it handed this session the asset generation, provenance, runtime mapping, and browser proof work behind the same adaptive request IDs. The product outcome is restrained, readable audio punctuation for high-value state changes in real AI Rogue gameplay. The stingers must support tactical and run-state comprehension without masking core SFX, adding long music layers, changing deterministic simulation behavior, or exposing diagnostic UI on the normal Play surface. *** ## 2. Objectives 1. Generate, optimize, commit, and document seven dedicated adaptive stinger SFX assets. 2. Map the existing adaptive request IDs to dedicated cue IDs while preserving cooldowns, ducking, mute, volume, autoplay unlock, and silent fallback. 3. Update focused unit, adapter, and browser proof coverage so each intended gameplay state triggers the correct stinger path once. 4. Record runtime review evidence for repeated triggers, volume interaction, decode/load failure recovery, and product-facing Play UI cleanliness. *** ## 3. Prerequisites ### Required Sessions * [x] `phase36-session01-current-audio-balance-audit` - Provides browser-path proof, baseline balance caveats, and the decision that adaptive stingers remain conditional and restrained. * [x] `phase36-session02-enemy-audio-metadata` - Provides typed event metadata and the presentation-only audio routing precedent. * [x] `phase36-session03-enemy-and-boss-sfx-pack` - Provides enemy and boss identity cues plus the SFX generation/provenance workflow. * [x] `phase36-session04-theme-audio-routing-contract` - Provides the theme ambience lane and the bus contract that adaptive ducking must preserve. * [x] `phase36-session05-sector-theme-audio-pack` - Provides committed theme ambience assets and browser proof across desktop/mobile. * [x] `phase36-session06-adaptive-music-engine-expansion` - Provides adaptive request IDs, cooldowns, ducking, renderer derivation, fallback behavior, and the explicit Session 07 handoff. * [x] `phase35-session10-final-release-gate` - Provides production-default, local-only, public-demo, privacy, no-remote, asset, and quality-gate constraints. ### Required Tools Or Knowledge * Bun 1.3.14 project scripts. * `ELEVENLABS_API_KEY` available locally for the existing `scripts/generate-ai-rogue-audio-sfx.ts` SFX pipeline, or already approved local raw masters under the gitignored `tmp/elevenlabs/` scratch path. * `ffmpeg` and `ffprobe` for Ogg Opus conversion and metadata probing. * Existing adaptive profiles in `src/extensions/ai-rogue/runtime/audio.ts`. * Existing renderer derivation in `src/extensions/ai-rogue/runtime/renderer-audio-adapter.ts`. * Existing browser proof in `tests/e2e/ai-rogue-runtime.spec.ts`. * AI Rogue audio docs in `docs/extensions/ai-rogue/game-feel.md`. ### Environment Requirements * Run from the repository root. * Keep raw generated files in gitignored scratch directories only. * Commit only optimized runtime Ogg Opus files and provenance metadata. * Preserve ASCII-only text files and Unix LF line endings. * Preserve no remote game-content loading, hosted writes, collectors, analytics, public-demo bridge calls, save migrations, or runtime dependency additions. *** ## 4. Scope ### In Scope (MVP) * AI Rogue gameplay has dedicated adaptive stingers for combat start, low HP, boss reveal, objective unlock, final defense, victory transition, and defeat transition. * New stingers are short, focused, mono 48 kHz Ogg Opus SFX under `src/assets/ai-rogue/audio/sfx/`, each below the 200 KB committed SFX cap. * New cue IDs and file basenames are added behind the existing adaptive request IDs without changing simulation RNG, replay, save data, or game balance. * `AI_ROGUE_ADAPTIVE_AUDIO_PROFILES` maps request IDs to dedicated stinger cues and keeps bounded cooldown, ducking, cue volume, and fallback behavior. * Renderer duplicate-suppression behavior is adjusted so Session 06 avoided duplicate provisional cues, while Session 07 dedicated stingers play once when appropriate. * Provenance records prompts, request settings, render metadata, and raw response metadata beside the committed SFX files. * Focused tests cover cue mapping, fallback, cooldowns, duplicate-trigger prevention, and adapter derivation for all seven stinger moments. * Browser proof fetches and starts all seven dedicated stingers on desktop and mobile, verifies silent fallback, and keeps adaptive implementation details out of normal product copy. * Documentation records the implemented stinger pack, asset policy fit, and remaining human acoustic listening scope for Session 08. ### Out Of Scope (Deferred) * Adding long music layers, sidechain/compressor dependencies, or a separate adaptive-audio volume preference - Reason: Session 06 selected bounded ducking through the existing music and theme ambience lanes. * Replacing title, depth, victory, defeat, theme ambience, heartbeat, enemy, boss, protocol, objective, or UI-click assets unrelated to adaptive stingers * Reason: this session only adds dedicated high-value stingers. * Changing simulation decisions, RNG, replay behavior, save contracts, persisted preferences, progression, economy, enemy balance, or route state - Reason: adaptive audio remains presentation-only. * Adding product-facing debug surfaces for adaptive audio - Reason: proof belongs in tests, browser instrumentation, and implementation notes. * Final full-pack acoustic sign-off - Reason: Session 08 owns final audio validation and documentation closeout after this stinger pack ships. * Visual asset finishing - Reason: Phase 37 owns visual asset work. *** ## 5. Technical Approach ### Architecture Use the existing direct Web Audio engine and adaptive request contract from Session 06. Add dedicated SFX cue IDs and file basenames for the seven stingers, then point `AI_ROGUE_ADAPTIVE_AUDIO_PROFILES` at those cues. Keep the adaptive request IDs stable so renderer call sites, cooldown keys, and browser proof shape remain familiar. Extend `scripts/generate-ai-rogue-audio-sfx.ts` with seven stinger cue definitions and reuse its current ElevenLabs -> ffmpeg -> ffprobe workflow. Raw MP3 responses stay in `tmp/elevenlabs/ai-rogue-sfx/raw/`; committed assets stay in `src/assets/ai-rogue/audio/sfx/`; provenance stays in `src/assets/ai-rogue/audio/sfx/provenance.json`. Keep renderer derivation in `renderer-audio-adapter.ts`, where prior/current snapshot and result events already meet. Because Session 06 suppressed provisional duplicate cues for events that already emitted the same old one shot, update that suppression so dedicated Session 07 stingers can play once through the adaptive profile while cooldowns prevent clutter. ### Design Patterns * Existing request IDs: Preserve `combat_start`, `low_hp`, `boss_reveal`, `objective_unlock`, `final_defense`, `victory_transition`, and `defeat_transition`. * Dedicated cue IDs: Add stinger-specific SFX IDs rather than reusing generic gameplay cues. * Presentation-only routing: Keep adaptive derivation in the renderer adapter and out of simulation state changes. * Cooldown-first playback: Every stinger uses the existing request cooldowns and ducking envelope to prevent repeated-trigger clutter. * Silent-safe media: Missing URLs, failed fetches, failed decodes, unavailable Web Audio, mute, volume changes, and route disposal remain no-throw paths. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------ | -------------------------------------------- | ---------- | | `src/assets/ai-rogue/audio/sfx/58_stinger_combat_start.ogg` | Dedicated combat-start adaptive stinger. | binary | | `src/assets/ai-rogue/audio/sfx/59_stinger_low_hp.ogg` | Dedicated low-HP pressure adaptive stinger. | binary | | `src/assets/ai-rogue/audio/sfx/60_stinger_boss_reveal.ogg` | Dedicated boss-reveal adaptive stinger. | binary | | `src/assets/ai-rogue/audio/sfx/61_stinger_objective_unlock.ogg` | Dedicated objective-unlock adaptive stinger. | binary | | `src/assets/ai-rogue/audio/sfx/62_stinger_final_defense.ogg` | Dedicated final-defense adaptive stinger. | binary | | `src/assets/ai-rogue/audio/sfx/63_stinger_victory_transition.ogg` | Dedicated victory-transition stinger. | binary | | `src/assets/ai-rogue/audio/sfx/64_stinger_defeat_transition.ogg` | Dedicated defeat-transition stinger. | binary | | `.spec_system/specs/phase36-session07-adaptive-stinger-pack/implementation-notes.md` | Record implementation choices and evidence. | \~180 | ### Files To Modify | File | Changes | Est. Lines | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | | `scripts/generate-ai-rogue-audio-sfx.ts` | Add seven adaptive stinger cue definitions and generation labels. | \~120 | | `src/extensions/ai-rogue/runtime/types-simulation.ts` | Add dedicated stinger cue IDs to the audio cue contract. | \~15 | | `src/extensions/ai-rogue/runtime/audio.ts` | Map adaptive profiles to dedicated stinger cues, tune volumes, and preserve fallback. | \~70 | | `src/extensions/ai-rogue/runtime/renderer-audio-adapter.ts` | Allow dedicated stingers to play once where Session 06 suppressed provisional cues. | \~45 | | `src/extensions/ai-rogue/runtime/__tests__/audio.test.ts` | Cover dedicated stinger fetches, cooldowns, ducking, mute/volume, fallback, and dispose. | \~130 | | `src/extensions/ai-rogue/runtime/__tests__/renderer-audio-adapter.test.ts` | Cover adapter routing and duplicate-trigger prevention for all seven moments. | \~90 | | `tests/e2e/ai-rogue-runtime.spec.ts` | Update desktop/mobile browser audio proof to assert dedicated stinger URLs. | \~45 | | `src/assets/ai-rogue/audio/sfx/provenance.json` | Add prompts, request settings, render metadata, and raw-response metadata for stingers. | \~240 | | `docs/extensions/ai-rogue/game-feel.md` | Document the implemented dedicated stinger pack and review caveats. | \~80 | | `docs/extensions/ai-rogue/README.md` | Update the current AI Rogue audio summary to mention dedicated adaptive stingers. | \~20 | | `.spec_system/PRD/phase_36/session_07_adaptive_stinger_pack.md` | Record delivered files, validation evidence, and Session 08 handoff notes. | \~70 | | `.spec_system/specs/phase36-session07-adaptive-stinger-pack/tasks.md` | Track implementation progress during the session. | \~90 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Each adaptive request ID maps to a dedicated stinger cue and committed Ogg Opus file. * [ ] Combat start, low HP entry, boss reveal, objective unlock, final defense, victory transition, and defeat transition can trigger the intended stinger from real renderer/runtime paths. * [ ] Repeated triggers respect cooldowns and do not stack stingers or volume spikes. * [ ] Master mute, music volume, SFX volume, autoplay unlock, theme ambience, depth music, terminal music, heartbeat, lazy decode, and silent fallback still work. * [ ] Missing asset URLs, failed fetches, failed decodes, unavailable Web Audio, and route disposal recover safely without throwing. * [ ] Product outcome is proven end to end: stingers play during real gameplay state changes, repeated triggers are controlled, and browser review confirms they support rather than mask gameplay. ### Testing Requirements * [ ] Focused audio engine tests pass. * [ ] Focused renderer audio adapter tests pass. * [ ] Focused combat/protocol/objective tests pass if stinger routing changes event fixture expectations. * [ ] Desktop and mobile browser audio proof fetches and starts all seven dedicated stinger assets. * [ ] `bash scripts/check-asset-sizes.sh` passes. * [ ] Runtime review records repeated-trigger behavior and volume interaction. ### Non-Functional Requirements * [ ] Every committed stinger asset is below 200 KB and has provenance. * [ ] No new dependency, lockfile change, settings field, save migration, collector, analytics path, hosted write, public-demo bridge call, worker, WebGPU-only behavior, or remote game-content loading is introduced. * [ ] Adaptive stingers remain presentation-only and do not affect simulation RNG, replay, save data, scoring, economy, or gameplay balance. * [ ] Normal user-facing Play UI uses product-facing copy only. ### Quality Gates * [ ] All touched text files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * Dedicated stingers should be SFX assets, not music assets: Session 07 asks for short stingers, the media policy defines game SFX as mono Ogg Opus under the 200 KB cap, and the existing SFX generator/provenance workflow already supports one-shot cue generation. * Stable adaptive request IDs should remain unchanged: Session 06 explicitly handed Session 07 the task of replacing provisional cue mapping behind the same request IDs, so planning can proceed without changing renderer intent names. * Stinger file numbering should continue after the existing SFX pack at 58-64: the committed SFX directory currently contains numbered files 01-57, and continuing the sequence keeps provenance and browser proof easy to inspect. ### Conflict Resolutions * Some completed Phase 36 stubs still contain stale unchecked or "Not Started" text, while the analyzer JSON and Phase 36 PRD progress tracker mark Sessions 01-06 complete. The analyzer is authoritative for workflow state, and the Phase 36 PRD independently confirms 6/8 sessions completed, so Session 07 is the next executable session. ### Key Considerations * Stingers must be restrained because Session 01 kept final acoustic fatigue review in Session 08 and warned against intrusive adaptive audio. * Existing objective, final-defense, victory, and defeat event cues already play one-shots; Session 07 must avoid replaying old provisional duplicates while still allowing dedicated adaptive stingers to play once. * Runtime proof can verify fetch, decode path, source start, cooldown, mute, fallback, and UI cleanliness, but final acoustic listening remains Session 08 scope. ### Potential Challenges * Generation credentials may be unavailable: reuse the existing script and record the exact generation prerequisite that prevented asset creation if neither `ELEVENLABS_API_KEY` nor approved local raw masters are available during `implement`. * Stingers may mask core SFX: keep durations short, volumes conservative, and use browser review notes to reduce or defer any cue that reads as clutter. * Objective/final/victory/defeat paths may double-punctuate: update adapter expectations and tests so dedicated stingers fire once through cooldowns, with old duplicate provisional behavior removed. ### Relevant Considerations * \[P34-P35] **AI Rogue is production default-enabled**: Preserve the production default and keep `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` as the explicit disable path. * \[P31-P35] **Public-demo and AI Rogue gates stay bundled**: Asset-size, no-remote, private-runtime, browser, Pages/public-demo, and playthrough gates remain relevant after media/runtime changes. * \[P30/P34-P35] **Visibility gates catch real issues**: Pair focused tests with browser proof and asset-size validation before widening confidence. * \[P30/P32/P34-P35] **Do not widen AI Rogue capabilities without review**: Avoid collectors, WebGPU-specific requirements, workers, remote loading, hosted writes, analytics, or expanded content. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Duplicate-trigger clutter when low HP, boss reveal, objective, final defense, or terminal transitions repeat. * Asset load/decode failure causing runtime exceptions instead of silent fallback. * Product Play UI exposing implementation terms such as adaptive audio, ducking, sidechain, or diagnostics. *** ## 9. Testing Strategy ### Unit Tests * Extend `src/extensions/ai-rogue/runtime/__tests__/audio.test.ts` to prove each adaptive request fetches a dedicated stinger URL, honors cooldowns, uses ducking, respects mute/volume, and remains safe on missing Web Audio, failed fetch, failed decode, and disposal. * Extend `src/extensions/ai-rogue/runtime/__tests__/renderer-audio-adapter.test.ts` to prove the seven gameplay moments route through adaptive requests once and do not repeat without state transitions. ### Integration Tests * Update `tests/e2e/ai-rogue-runtime.spec.ts` so desktop and mobile browser proof asserts all seven new stinger basenames are fetched and source-started. * Run focused combat/protocol/objective tests if implementation changes event fixture assumptions around objective, final defense, victory, or defeat. ### Runtime Verification * Start AI Rogue in a browser, unlock audio, trigger or instrument the seven adaptive request paths, verify no page errors or failed Ogg requests, and confirm normal Play UI does not expose implementation/debug copy. * Review repeated triggers and volume interaction for low HP, boss reveal, final defense, victory, and defeat. ### Edge Cases * AudioContext missing or construction fails. * Stinger URL missing from Vite glob. * Fetch or decode failure for one stinger. * Route disposal while stinger decode is pending. * Objective/final/victory/defeat event already emitted core one-shot SFX. * Re-entering low HP or boss-visible state without a real transition. * Mute, music volume, and SFX volume changed before and after request. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase36-session01-current-audio-balance-audit`, `phase36-session02-enemy-audio-metadata`, `phase36-session03-enemy-and-boss-sfx-pack`, `phase36-session04-theme-audio-routing-contract`, `phase36-session05-sector-theme-audio-pack`, `phase36-session06-adaptive-music-engine-expansion` * Depended by: `phase36-session08-final-audio-validation-and-docs` *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # 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://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase36-session07-adaptive-stinger-pack/spec.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.