# Decision records

Every architectural decision, why it was made, and what would reverse it.

!!! info "This is the engineering tier"

    These pages are written for contributors, reviewers and researchers rather
    than for people using YazSes. For the user documentation, start at
    [Home](../../index.md).

**154 documents.**

| Decision | Status |
|---|---|
| [ADR-001: Rust Core + Python Plugins via PyO3](adr-001.md) | Accepted |
| [ADR-002: Dual-Stack STT Routing](adr-002.md) | Accepted |
| [ADR-003: LLM Backend — llama.cpp Default + MLX Apple Silicon Fast Path](adr-003.md) | Accepted |
| [ADR-004: Grammar-Constrained Tool Calls](adr-004.md) | Accepted |
| [ADR-005: InputBackend Protocol](adr-005.md) | Accepted |
| [ADR-006: EditorBridge Protocol](adr-006.md) | Accepted |
| [ADR-007: Personal Memory — sqlite-vec + SQLCipher](adr-007.md) | Accepted |
| [ADR-008: Distribution — cargo-dist + Per-Distro Packagers](adr-008.md) | Accepted |
| [ADR-009: Python Plugin SDK via Embedded PyO3](adr-009.md) | Accepted |
| [ADR-010: Preserve v0.4 JSON-RPC 2.0 IPC Contract](adr-010.md) | Accepted |
| [ADR-011: Zero Telemetry, Offline-Default, Opt-In Cloud](adr-011.md) | Accepted |
| [ADR-012: Opt-In, Local, Encrypted Self-Improvement Loop](adr-012-self-improvement-loop.md) | Accepted |
| [ADR-013 — On-Device LLM Dictation Cleanup (dual-path, parity)](adr-013-llm-cleanup.md) | Accepted |
| [ADR-014 — Held-out validation for `yazses tune` proposals](adr-014-tune-holdout-validation.md) | Accepted |
| [ADR-015 — Dysfluency-Friendly Mode (collapse pass + accessibility preset)](adr-015-dysfluency-friendly-mode.md) | Accepted |
| [ADR-016 — The dependency budget: features pay for themselves](adr-016-dependency-budget.md) | Accepted |
| [ADR-017 — Intel Mac support: build it while it is free, and put the end date in writing](adr-017-intel-mac-support-has-a-deadline.md) | Accepted |
| [ADR-018 — Show the price before charging it; defer third-party plug-ins](adr-018-feature-packs-and-the-plugin-question.md) | Accepted |
| [ADR-019 — The egress inventory: every way data can leave, and the rule for adding one](adr-019-egress-inventory-and-escalation.md) | Accepted |
| [ADR-020 — Agent protocols: which one YazSes needs, and which it must not adopt](adr-020-agent-protocols.md) | Accepted |
| [ADR-021 — The one thing to invest in: carry the cost of an error through the pipeline](adr-021-invest-in-error-cost.md) | Accepted |
| [ADR-v04-001: llama-cpp-python for Tier 2 SLM Intent Routing](adr-v04-001-slm-inference.md) | — |
| [ADR-v04-002: LSP Context Injection for Whisper Decoder Priming](adr-v04-002-lsp-context.md) | — |
| [ADR-v04-003: EMG Backend USB Serial Protocol (YESP)](adr-v04-003-emg-serial.md) | — |
| [ADR-v2-000 — YazSes v2: the Voice-First Interaction Layer (umbrella)](adr-v2-000-interaction-layer.md) | Accepted |
| [ADR-v2-001 — Confidence Ink & Voice Re-pick](adr-v2-001-confidence-ink.md) | Accepted |
| [ADR-v2-002 — Prosody Auto-Formatting (pauses → punctuation, stress → emphasis)](adr-v2-002-prosody-autoformat.md) | Accepted |
| [ADR-v2-003 — Spoken Edit Mode (open-ended interactive dictation)](adr-v2-003-spoken-edit-mode.md) | Accepted |
| [ADR-v2-004 — Context-Primed Dictation & Commanding](adr-v2-004-context-primed-dictation.md) | Accepted |
| [ADR-v2-005 — Spoken Recall & Ambient Scratch](adr-v2-005-spoken-recall.md) | Accepted |
| [ADR-v2-006 — Voice-to-Tool (offline Spoken MCP)](adr-v2-006-spoken-mcp.md) | Accepted |
| [ADR-v2-007 — AT-SPI Voice Pilot (accessibility-tree desktop control)](adr-v2-007-atspi-voice-pilot.md) | Accepted |
| [ADR-v2-008 — True Code-Switch Dictation (make `[polyglot]` real)](adr-v2-008-code-switch.md) | Accepted |
| [ADR-v2-009 — Personal Speech Adapter (on-device personalization)](adr-v2-009-personal-adapter.md) | Accepted |
| [ADR-v2-010 — Gaze-Routed Dictation & Point-and-Speak](adr-v2-010-gaze-routed-dictation.md) | Accepted |
| [ADR-v2-011 — sEMG Command Layer & Modality Role Router](adr-v2-011-semg-modality-router.md) | Accepted |
| [ADR-v2-012 — Accessibility Continuum](adr-v2-012-accessibility-continuum.md) | Accepted |
| [ADR-v2-013 — Glasses↔Desktop Dictation Bridge](adr-v2-013-glasses-desktop-bridge.md) | Accepted |
| [ADR-v2-014 — Real-time Offline Speech Translation](adr-v2-014-speech-translation.md) | Accepted |
| [ADR-v2-015 — Real-time Noise-Suppression Front-End](adr-v2-015-noise-suppression.md) | Accepted |
| [ADR-v2-016 — Predictive Dictation Completion](adr-v2-016-predictive-completion.md) | Accepted |
| [ADR-v2-017 — Emotion / Tone-Aware Formatting](adr-v2-017-tone-aware-formatting.md) | Accepted |
| [ADR-v2-018 — Continuous Voice-Biometric Gate + Anti-Spoof](adr-v2-018-voice-biometric-guard.md) | Accepted |
| [ADR-v2-019 — Ambient Meeting Scribe (streaming diarization)](adr-v2-019-meeting-scribe.md) | Accepted |
| [ADR-v2-020 — Voice-Grounded RAG over Personal Notes](adr-v2-020-voice-grounded-rag.md) | Accepted |
| [ADR-v2-021 — Atypical-Speech Personalization + Adapter Held-Out Gate](adr-v2-021-atypical-speech-adapter.md) | Accepted |
| [ADR-v2-022 — Neural-Codec Ultra-Low-Latency Streaming STT](adr-v2-022-codec-streaming.md) | Accepted |
| [ADR-v2-023 — Silent-Speech / Subvocal (sEMG) Input](adr-v2-023-silent-speech-semg.md) | Accepted |
| [ADR-v2-024 — Pure-Vision Screen Commanding (VLM)](adr-v2-024-vlm-screen-commanding.md) | Accepted |
| [ADR-v2-025 — Hallucination Guard](adr-v2-025-hallucination-guard.md) | Accepted |
| [ADR-v2-026 — Voice Snippets (spoken text expander)](adr-v2-026-voice-snippets.md) | Accepted |
| [ADR-v2-027 — Phonetic Corrector (fix mis-heard names by sound)](adr-v2-027-phonetic-corrector.md) | Accepted |
| [ADR-v2-028 — Multi-User Voiceprint Profiles](adr-v2-028-multiuser-voiceprint-profiles.md) | Accepted |
| [ADR-v2-029 — Semantic Auto-Stop (hands-free tap-and-speak)](adr-v2-029-semantic-autostop.md) | Accepted |
| [ADR-v2-030 — Voice Mouse Grid (pointer control by voice)](adr-v2-030-voice-mouse-grid.md) | Accepted |
| [ADR-v2-031 — Spoken Code Mode](adr-v2-031-spoken-code-mode.md) | Accepted |
| [ADR-v2-032 — Spoken Math → LaTeX](adr-v2-032-spoken-math-latex.md) | Accepted |
| [ADR-v2-033 — Wake-Word Activation](adr-v2-033-wake-word.md) | Accepted |
| [ADR-v2-034 — Vocal-Strain Guard](adr-v2-034-vocal-strain-guard.md) | Accepted |
| [ADR-v2-035 — Speaking Coach (private self-analytics)](adr-v2-035-speaking-coach.md) | Accepted |
| [ADR-v2-036 — Smart-Paste Format Adaptation](adr-v2-036-smart-paste.md) | Accepted |
| [ADR-v2-037 — Audio-Anchored Scrubbing](adr-v2-037-audio-anchored-scrubbing.md) | Accepted |
| [ADR-v2-038 — Dictation Reflow (Voice Outliner)](adr-v2-038-dictation-reflow.md) | Accepted |
| [ADR-v2-039 — Acoustic Context Profiles](adr-v2-039-acoustic-profiles.md) | Accepted |
| [ADR-v2-040 — Mood Ledger (speech-sentiment journal)](adr-v2-040-mood-ledger.md) | Accepted |
| [ADR-v2-041 — Pronunciation Feedback (L2 practice mode)](adr-v2-041-pronunciation-feedback.md) | Accepted |
| [ADR-v2-042 — Personal Read-Back Voice](adr-v2-042-personal-readback-voice.md) | Accepted |
| [ADR-v2-043 — Gesture Chords](adr-v2-043-gesture-chords.md) | Accepted |
| [ADR-v2-044 — Two-Way Live Interpreter](adr-v2-044-two-way-interpreter.md) | Accepted |
| [ADR-v2-045 — Entity Inverse Text Normalization (ITN)](adr-v2-045-entity-itn.md) | Accepted |
| [ADR-v2-046 — Redaction Ink](adr-v2-046-redaction-ink.md) | Accepted |
| [ADR-v2-047 — Field-Aware Dictation](adr-v2-047-field-aware-dictation.md) | Accepted |
| [ADR-v2-048 — Corpus Voiceprint Scrub](adr-v2-048-corpus-voiceprint-scrub.md) | Accepted |
| [ADR-v2-049 — Compose-in-Target-Language](adr-v2-049-compose-target-language.md) | Accepted |
| [ADR-v2-050 — Grammar Repair (minimal-edit GEC)](adr-v2-050-grammar-repair.md) | Accepted |
| [ADR-v2-051 — Screen-Grounded Dictation](adr-v2-051-screen-grounded-dictation.md) | Accepted |
| [ADR-v2-052 — Head-Pointer](adr-v2-052-head-pointer.md) | Accepted |
| [ADR-v2-053 — Silent Lip-Reading Input (VSR)](adr-v2-053-silent-lip-reading.md) | Accepted |
| [ADR-v2-054 — Sign-Language Input (SLR)](adr-v2-054-sign-language-input.md) | Accepted |
| [ADR-v2-055 — Emoji & Symbol by Voice](adr-v2-055-emoji-symbol-voice.md) | Accepted |
| [ADR-v2-056 — Voice Unit Conversion](adr-v2-056-voice-unit-conversion.md) | Accepted |
| [ADR-v2-057 — Spoken Temporal Normalizer](adr-v2-057-temporal-normalizer.md) | Accepted |
| [ADR-v2-058 — Mid-Utterance Self-Repair](adr-v2-058-mid-utterance-self-repair.md) | Accepted |
| [ADR-v2-059 — Spoken Spreadsheet / Table Mode](adr-v2-059-spoken-spreadsheet.md) | Accepted |
| [ADR-v2-060 — Clipboard-History by Voice](adr-v2-060-clipboard-history-voice.md) | Accepted |
| [ADR-v2-061 — Ambient Audio-Event Guard](adr-v2-061-ambient-audio-event-guard.md) | Accepted |
| [ADR-v2-062 — On-Device Condense](adr-v2-062-on-device-condense.md) | Accepted |
| [ADR-v2-063 — Structured Form / Slot-Filling Dictation](adr-v2-063-slot-filling-dictation.md) | Accepted |
| [ADR-v2-064 — Few-Shot Personal Command Spotter](adr-v2-064-few-shot-command-spotter.md) | Accepted |
| [ADR-v2-065 — Terminal Command Safety Gate](adr-v2-065-terminal-command-safety-gate.md) | Accepted |
| [ADR-v2-066 — Spoken Regex Builder](adr-v2-066-spoken-regex-builder.md) | Accepted |
| [ADR-v2-067 — Structured-Markup Dictation](adr-v2-067-structured-markup-dictation.md) | Accepted |
| [ADR-v2-068 — Voice-Driven Document-Wide Find-and-Replace](adr-v2-068-document-find-replace.md) | Accepted |
| [ADR-v2-069 — Hard Contextual Biasing (hotword trie)](adr-v2-069-hard-contextual-biasing.md) | Accepted |
| [ADR-v2-070 — Voice-Controlled Window / Workspace Management](adr-v2-070-voice-window-management.md) | Accepted |
| [ADR-v2-071 — Citation-by-Voice from a local BibTeX/CSL library](adr-v2-071-citation-by-voice.md) | Accepted |
| [ADR-v2-072 — Per-Language Auto Model Switching](adr-v2-072-per-language-model-switching.md) | Accepted |
| [ADR-v2-073 — Adaptive Latency Governor](adr-v2-073-adaptive-latency-governor.md) | Accepted |
| [ADR-v2-074 — Diarized Conversation Capture with Rename-by-Voice](adr-v2-074-diarized-conversation-capture.md) | Accepted |
| [ADR-v2-075 — Phonetic Spelling Mode](adr-v2-075-phonetic-spelling-mode.md) | Accepted |
| [ADR-v2-076 — Voice Git Choreographer (reversibility-gated)](adr-v2-076-voice-git-choreographer.md) | Accepted |
| [ADR-v2-077 — Confidence-Gated Re-Ask](adr-v2-077-confidence-gated-reask.md) | Accepted |
| [ADR-v2-078 — Verbatim ⇄ Autoformat Live Toggle](adr-v2-078-verbatim-autoformat-toggle.md) | Accepted |
| [ADR-v2-079 — Self-Learning Correction Dictionary](adr-v2-079-self-learning-correction-dictionary.md) | Accepted |
| [ADR-v2-080 — Voice Fuzzy File Open](adr-v2-080-voice-fuzzy-file-open.md) | Accepted |
| [ADR-v2-081 — Voice Jump-to-Symbol / Structural Hop](adr-v2-081-voice-jump-to-symbol.md) | Accepted |
| [ADR-v2-082 — Spoken Shell Pipeline Builder (dry-run first)](adr-v2-082-spoken-shell-pipeline-builder.md) | Accepted |
| [ADR-v2-083 — Recording Import (batch transcription)](adr-v2-083-recording-import.md) | Accepted |
| [ADR-v2-084 — Crowd-Proof Dictation (target-speaker extraction)](adr-v2-084-crowd-proof-dictation.md) | Accepted |
| [ADR-v2-085 — Chorded Shortcut Synthesis](adr-v2-085-chorded-shortcut-synthesis.md) | Accepted |
| [ADR-v2-086 — Inline Compute](adr-v2-086-inline-compute.md) | Accepted |
| [ADR-v2-087 — Voice Case & Identifier Transform on Selection](adr-v2-087-voice-case-transform.md) | Accepted |
| [ADR-v2-088 — Auto-Pairing & Wrap-Selection for Code Dictation](adr-v2-088-auto-pairing-wrap.md) | Accepted |
| [ADR-v2-089 — Voice Undo/Redo Timeline](adr-v2-089-voice-undo-redo-timeline.md) | Accepted |
| [ADR-v2-090 — Session Bookmarks & Resume](adr-v2-090-session-bookmarks.md) | Accepted |
| [ADR-v2-091 — Spoken Table → CSV / Field Data Entry](adr-v2-091-spoken-table-csv.md) | Accepted |
| [ADR-v2-092 — Word-Count & Writing-Goal Tracker](adr-v2-092-word-count-goal-tracker.md) | Accepted |
| [ADR-v2-093 — Local Voice Timer & Break Reminder](adr-v2-093-local-voice-timer.md) | Accepted |
| [ADR-v2-094 — Focus-Class Auto-Profile Switching](adr-v2-094-focus-class-auto-profile.md) | Accepted |
| [ADR-v2-095 — Vocal Joystick (continuous non-speech analog control)](adr-v2-095-vocal-joystick.md) | Accepted |
| [ADR-v2-096 — Earcon Feedback Language (non-speech eyes-free state cues)](adr-v2-096-earcon-feedback.md) | Accepted |
| [ADR-v2-097 — Mouth-Sound Switch Access (non-verbal acoustic switches + scanning)](adr-v2-097-mouth-sound-switch-access.md) | Accepted |
| [ADR-v2-098 — Beam-Steered Spatial VAD (2-mic direction-of-arrival gate)](adr-v2-098-spatial-vad.md) | Accepted |
| [ADR-v2-099 — Breath-Paced Dictation](adr-v2-099-breath-paced-dictation.md) | Accepted |
| [ADR-v2-100 — Whisper-Aware Mode](adr-v2-100-whisper-aware-mode.md) | Accepted |
| [ADR-v2-101 — Hesitation-Hold Endpointing](adr-v2-101-hesitation-hold-endpointing.md) | Accepted |
| [ADR-v2-102 — Involuntary-Vocalization Auto-Excision](adr-v2-102-involuntary-vocalization-excision.md) | Accepted |
| [ADR-v2-103 — Pitch-Contour Vocal Gestures](adr-v2-103-pitch-contour-gestures.md) | Accepted |
| [ADR-v2-104 — Prosodic Auto-Punctuation (acoustic, word-free sentence structure)](adr-v2-104-prosodic-auto-punctuation.md) | Accepted |
| [ADR-v2-105 — Vocal Morse (two-tone timing-coded AAC)](adr-v2-105-vocal-morse.md) | Accepted |
| [ADR-v2-106 — Checksum-Validated Data Entry](adr-v2-106-checksum-validated-entry.md) | Accepted |
| [ADR-v2-107 — Diagrams-as-Code by Voice (Mermaid/Graphviz)](adr-v2-107-diagrams-as-code.md) | Accepted |
| [ADR-v2-108 — Interruptible Read-Back Proofreading (barge-in alignment)](adr-v2-108-interruptible-readback-proofreading.md) | Accepted |
| [ADR-v2-109 — Local Style-Consistency Enforcer (Vale-lite)](adr-v2-109-style-consistency-enforcer.md) | Accepted |
| [ADR-v2-110 — Screenplay & Dialogue Auto-Format (Fountain)](adr-v2-110-screenplay-autoformat.md) | Accepted |
| [ADR-v2-111 — Semantic Line Breaks (version-control-friendly prose)](adr-v2-111-semantic-line-breaks.md) | Accepted |
| [ADR-v2-112 — Spoken Spaced-Repetition Capture](adr-v2-112-spoken-spaced-repetition.md) | Accepted |
| [ADR-v2-113 — Suggestion-Mode Dictation (CriticMarkup tracked changes)](adr-v2-113-suggestion-mode-dictation.md) | Accepted |
| [ADR-v2-114 — Acronym / Glossary First-Use Manager](adr-v2-114-acronym-glossary-manager.md) | Accepted |
| [ADR-v2-115 — HatSelect (spoken structural token addressing)](adr-v2-115-hatselect.md) | Accepted |
| [ADR-v2-116 — Romanized → Native-Script Transliteration](adr-v2-116-transliteration.md) | Accepted |
| [ADR-v2-117 — BrailleOut (dictation as Unicode Braille output)](adr-v2-117-brailleout.md) | Accepted |
| [ADR-v2-118 — WordFind (offline reverse dictionary)](adr-v2-118-wordfind.md) | Accepted |
| [ADR-v2-119 — Echo (own-audio replay for a text span)](adr-v2-119-echo.md) | Accepted |
| [ADR-v2-120 — SRPace (screen-reader-paced injection)](adr-v2-120-srpace.md) | Accepted |
| [ADR-v2-121 — LoadGuard (cognitive-load-aware guardrails)](adr-v2-121-loadguard.md) | Accepted |
| [ADR-v2-122 — Diacritize (diacritics restoration)](adr-v2-122-diacritize.md) | Accepted |
| [ADR-v2-123 — SafeGlyph (homoglyph/confusable hazard detection)](adr-v2-123-safeglyph.md) | Accepted |
| [ADR-v2-124 — Spoken Outline (voice-driven outline structuring)](adr-v2-124-outline.md) | Accepted |
| [ADR-v2-125 — Diarized Recording Import (`yazses transcribe <file>`)](adr-v2-125-diarized-recording-import.md) | Proposed |
| [ADR-v2-126 — Cloud Transcription Escalation (design-only, deferred)](adr-v2-126-cloud-escalation.md) | Proposed |
| [ADR-v2-127 — Live Meeting Mode (hands-free capture + hybrid diarization)](adr-v2-127-live-meeting-mode.md) | Proposed |
| [ADR-v2-128 — On-device Meeting Minutes (speaker-aware notes)](adr-v2-128-meeting-minutes-generation.md) | Proposed |
| [ADR-v2-129 — Killer Features 10x: gaze deixis, sotto-voce channel, activation-source seam, pluggable STT](adr-v2-129-killer-features-10x.md) | Accepted |