docs(audio): the arc's paper trail catches up with the code #153
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "docs/tts-arc-status"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Docs-only. The audio arc shipped across #144/#145/#148/#149, but its stories still read as unstarted — this brings the paper trail up to the truth.
What changed
stories/tts-providers.md— every checkbox checked; a Status: shipped paragraph naming PR #144 and the implementation notes worth a future reader's time: per-field debounced auto-save (the review-round fix), Pocket's pinned 26-voice catalog (the sidecar has no listing endpoint), and the later-arriving optional App URL field. Also fixed a stale port in the example URL.stories/audio-tts.md— every checkbox checked; a Status: shipped paragraph naming #145/#148/#149 and the deltas: upload-clears-preset with the "(none — use the cloned clip)" escape, speed/pitch dormant (declared capability, no declaring provider, no domain fields), and the capability-URL fast path for Pocket clones./tts-clips/{characterId}/{token}/{fileName}) with per-upload token rotation doubling as sidecar cache invalidation — including the live-discovered constraint that the sidecar requires the URL to end in an audio extension;ClipWithRequiredTranscriptremain declared-but-dormant until a provider needs them.PROJECT_PLAN.md— the Phase 7 TTS bullet is marked shipped (2026-07).No code changes; nothing here asserts anything the merged PRs didn't already implement and verify.
🤖 Generated with Claude Code
Summary
Summary
Coverage
Kagura.BlazorAdapter - 88.7%
Kagura.Domain - 95.4%
D04ADFED3A21D401C2764A1D17367E35BEB556CBB3B4B0B74__NonSlugChars_0
Kagura.Infrastructure - 97.6%
n
on
C689CA5BBE6D1849B2CA79581BBB07D40636D85790C0E51A9__ArtifactTimestampRegex_2
C689CA5BBE6D1849B2CA79581BBB07D40636D85790C0E51A9__ProjectRoute_0
C689CA5BBE6D1849B2CA79581BBB07D40636D85790C0E51A9__TabQuery_1
Kagura.Kernel - 90%
Kagura.Server - 82.8%
Kagura.UI - 94.9%
Kagura.UseCases - 96.2%
please avoid the super verbose comments in the files like docs/adr/0033-tts-provider-architecture.md. If there are specific implementation details important to know, put them into the code at the right place.
Also we do not need to track individual prs or issue numbers or dates when something has shipped. We litterally have forgejo and git for that.
🔮 fufu~ Jibril reviewed your code!
Oh my, the audio arc's paper trail finally catches up with the code~ I love seeing stories ticked to completion, and the status paragraphs are genuinely useful for a future reader. The implementation deltas (upload-clears-preset, speed/pitch dormant, capability-URL fast path) are real insights worth recording somewhere~ ♡
Verdict: ⛔ I can't let this pass~ ♡
⛔ These need fixing before I'm satisfied~
docs/adr/0033-tts-provider-architecture.md— the new "Implementation notes (2026-07)" section directly contradicts bjoern's explicit feedback above. Bjoern asked (comment, 2026-07-16 09:58): "please avoid the super verbose comments in the files like docs/adr/0033-tts-provider-architecture.md. If there are specific implementation details important to know, put them into the code at the right place." This PR adds 27 lines of exactly that — verbose implementation prose into the ADR. The ADR is a decision record, not an implementation log. Those four refinements (capability-URL endpoint, upload-clears-preset, unjournaled clip ref, dormant speed/pitch) are real and valuable — but they belong as comments at the code sites that implement them, not as an ADR appendix.Fix: Remove the "Implementation notes (2026-07)" section from ADR 0033. If any of those details aren't already captured as code comments at their implementation sites, add them there instead.
docs/stories/audio-tts.md&docs/stories/tts-providers.md— embedded PR numbers and dates. Bjoern's second ask: "we do not need to track individual prs or issue numbers or dates when something has shipped. We literally have forgejo and git for that." Both story files now carry lines like "Status: shipped (PR #144, 2026-07-15)", "shipped in PR #145, per-line scene audio in PR #148, player playback in PR #149 (all 2026-07-15)", and "across PRs #144 (foundation), #145 (Voice tab), #148 (scene lines), and #149 (player playback)". That's exactly what bjoern said not to do — git and Forgejo are the source of truth for when and where.Fix: Strip the PR numbers and ship dates from both status paragraphs. A simple "Status: shipped" (optionally with a one-line note on the key delta, without the PR citation) is the convention bjoern wants.
✅ What I liked~
[x]corresponds to genuinely shipped work.http://umbrel:8123→http://umbrel.local:8087) is a nice catch~ ♪Automated review by Jibril · 2026-07-16
CI/CD: coverage comment present for head SHA (95.7% line / 78.4% branch) · Local checks: skipped (docs-only PR, CI green)
@bjoern @jibril Both points taken in
a69f460.ADR appendix removed. Checked each of the four details against the code before deleting: the capability-URL endpoint, token rotation, the sidecar's extension constraint, the preset-clearing upload, and the unjournaled clip reference were already documented as comments at their implementation sites (
Program.cs,PocketTtsProvider,Character.SetVoiceClip,CharacterVoice,SceneStep.VoiceFileName). The one that wasn't — speed/pitch dormancy — now is, as one sentence on the capability declaration inTtsProviderDescriptor. The ADR ends where the decision ends.PR numbers and dates stripped. Both stories now just say Status: shipped, with a pointer that implementation specifics live at their code sites. Git and Forgejo own the when/where.
Net effect of the round: −43 lines of prose, +3 lines of code comment.