CRITICAL: Documentation describes non-existent NEW architecture (IAudioStrategy)

[danieljsinclair]

Issue Type

Bug - Critical documentation-reality mismatch

Severity

Critical - Documentation describes architecture that doesn't exist in the codebase

Problem Statement

The documentation claims Phase 6 of the audio module refactoring is "COMPLETED" with a NEW architecture featuring:

• IAudioStrategy interface
• IAudioHardwareProvider interface
• strategies/ folder with SyncPullStrategy, ThreadedStrategy
• hardware/ folder with MacAudioHardware, WindowsAudioHardware
• utils/ folder with AudioUtils containing FillSilence

NONE of these files or interfaces exist in the actual codebase.

Current Reality

The actual codebase uses the OLD architecture:

• src/audio/modes/ with SyncPullMode, ThreadedMode
• src/audio/renderers/ with SyncPullRenderer, ThreadedRenderer
• src/audio/factories/ with AudioModeFactory, AudioRendererFactory
• src/audio/utils/ exists but contains different utilities

Evidence

1. Git log analysis (Feb-Apr 2026): Shows "pull model" implementation in commit cec0a18, NO commits for Phase 6 consolidation
2. File structure: strategies/ and hardware/ folders don't exist
3. Code search: No references to IAudioStrategy or IAudioHardwareProvider anywhere in codebase

Impact

• Misleading documentation causes confusion for developers
• Impossible to follow documented architecture patterns
• Wastes developer time searching for non-existent components
• Creates cognitive dissonance between documentation and reality

Files Affected

• docs/AUDIO_MODULE_ARCHITECTURE.md - Claims NEW architecture is implemented
• docs/ARCHITECTURE_TODO.md - Marks Phase 6 as "COMPLETED"
• Possibly other documentation files

Recommended Action

1. Immediate: Update documentation to reflect ACTUAL architecture (pull model with modes/renderers/factories)
2. Decision needed: Either:
   • Implement the NEW architecture as documented (major refactoring effort)
   • Revert documentation to accurately describe the OLD/pull model architecture
   • Update Phase 6 status to "NOT STARTED" and clarify current state

Acceptance Criteria

• Documentation accurately describes the ACTUAL architecture in the codebase
• No references to non-existent interfaces or folders
• Phase 6 status accurately reflects implementation status
• All diagrams and examples match real code structure

Related Issues

• #75 - Documentation review and cleanup
• #76 - Comprehensive CLI architecture audit

References

• Architecture audit findings from Task #76
• Git log showing pull model implementation (commit cec0a18)