Initialize project governance and baseline structure

Stoned.AI — live-streamed human + AI conversation show, both sides voiced
via local Kokoro TTS. Governance docs 00-09, README, .gitignore.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-04-12 21:55:46 +00:00
commit fcd93ee0af
12 changed files with 740 additions and 0 deletions

56
docs/05-RISK-REGISTER.md Normal file
View File

@@ -0,0 +1,56 @@
# Risk Register
## Risks
### Risk 1
- Risk: `pykokoro` is installed in Arena's virtualenv only. Stoned.AI may not be able to import it without installing Arena as a dependency or duplicating the virtualenv.
- Impact: High — TTS is a core feature. Without it the project cannot function.
- Likelihood: Medium — the Arena install script installs `pykokoro` into a project-local venv, not system-wide.
- Mitigation: Add `pykokoro` as a direct dependency in `pyproject.toml`. Install into a fresh project-local venv. Verify the import works independently before proceeding with the TTS layer.
- Owner: Implementation model (Phase 1).
- Trigger: `import pykokoro` fails in the Stoned.AI venv.
### Risk 2
- Risk: OBS Studio browser source does not auto-play audio without user interaction, blocked by browser autoplay policy.
- Impact: High — audio playback in the broadcast view is a core feature.
- Likelihood: Medium — OBS uses Chromium internally and has its own audio handling. This is a known issue for some browser source setups.
- Mitigation: Test OBS audio capture during Phase 4 before marking the phase complete. If autoplay is blocked, investigate OBS browser source audio settings (`Enable JavaScript`, `Allow Plugins`, global audio device assignment in OBS scene settings).
- Owner: Jason (manual verification) with implementation support.
- Trigger: Audio does not play in OBS browser source during Phase 4 testing.
### Risk 3
- Risk: Kokoro synthesis is slow on CPU (no GPU on `svc-ai`), causing noticeable latency between turn submission and audio playback.
- Impact: Medium — does not break functionality but degrades the live stream experience.
- Likelihood: Medium — Kokoro is rated CPU-viable but synthesis time varies by voice and text length.
- Mitigation: Gate the next card rendering until audio is ready (already the Arena pattern). Keep host messages and AI responses concise. If latency is unacceptable, investigate Piper TTS as a faster CPU fallback.
- Owner: Implementation model (Phase 2), Jason (evaluation).
- Trigger: Synthesis takes more than 5 seconds for a typical 23 sentence response.
### Risk 4
- Risk: AI backend CLI output format changes (Codex or Gemini banner updates) causing the cleaning engine to miss noise or strip dialogue.
- Impact: Medium — visible noise in the conversation feed degrades the stream.
- Likelihood: Low — CLI tools update occasionally, but not frequently.
- Mitigation: Maintain a robust `clean.py` based on Arena's proven patterns. Add a debug mode flag that shows raw output for troubleshooting.
- Owner: Implementation model.
- Trigger: Conversation feed shows CLI banner lines or token counts.
### Risk 5
- Risk: The host and broadcast views share an SSE stream. If the broadcast view reconnects (e.g. OBS browser source refresh), it may miss turns that occurred during the gap.
- Impact: Low — the broadcast feed would fall behind but would recover on the next turn.
- Likelihood: Low — OBS browser sources are generally stable once connected.
- Mitigation: On SSE reconnect, replay the current session's conversation history as catch-up events before resuming the live stream. This is optional for the initial build.
- Owner: Implementation model (Phase 2, optional enhancement).
- Trigger: OBS browser source shows an incomplete conversation after a refresh.
## Signature
- Document role: governing
- Created by: Claude (supervisor)
- Created at: 2026-04-12
- Revision status: initial
- Future revision rule: this document may be revised only by the user or by an explicitly authorized supervisor revision