feat: add CW-026 Local Voice plugin

2026-07-27 00:33:25 +08:00
commit 5d680928b9
29 changed files with 2697 additions and 0 deletions
@@ -0,0 +1,62 @@
+# Donna integration contract
+
+Donna remains responsible for collecting organizational information, deciding
+priority, selecting a character, and writing the final canonical script. Local
+Voice is an optional audio dependency responsible for rendering and validating
+that script.
+
+## Invocation
+
+Donna supplies:
+
+- voice profile ID;
+- canonical Markdown or Ryan-labelled dialogue;
+- absolute output path;
+- pronunciation overrides when needed;
+- optional delivery, role, signature-asset, and pause metadata.
+
+Donna then asks Local Voice to:
+
+1. run `doctor` if runtime health is unknown;
+2. build or validate the render plan;
+3. render with `--resume`;
+4. return the final audio and QA-report paths.
+
+## Required behavior
+
+- Do not send Markdown headings, numbered section titles, speaker labels, or
+  stage directions as spoken text.
+- Keep greetings and closings as short standalone paragraphs so Local Voice can
+  preserve native tempo.
+- Keep substantive paragraphs to complete sentence groups of roughly 20–42
+  words unless a profile specifies otherwise.
+- Use canonical `text` for the written brief and `tts_text` only for local
+  pronunciation corrections.
+- Do not silently fall back to ElevenLabs. If Local Voice fails, Donna should
+  report the failure and apply the caller's configured fallback policy.
+- Attach or link the final audio alongside the full written organizational
+  brief; the audio is a quick summary, not the sole record.
+
+## Character mapping
+
+| Donna character | Local Voice profile |
+|---|---|
+| Production Donna | `donna` |
+| Chris Engineer | `chris-engineer` |
+| Grandpa Bomber | `grandpa-bomber` |
+| Pitch Meeting | `ryan-pitch-meeting` |
+| Val Holiday | `val-holiday` |
+
+## Example handoff
+
+```json
+{
+  "voice": "val-holiday",
+  "script": "/absolute/path/val-brief.md",
+  "output": "/absolute/path/val-brief.mp3",
+  "fallback": "report-and-return-text"
+}
+```
+
+Local Voice returns the final audio path, QA report path, duration, and
+segment-level completeness and cadence results.