Skip to content

Decision records

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

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.

154 documents.

Decision Status
ADR-001: Rust Core + Python Plugins via PyO3 Accepted
ADR-002: Dual-Stack STT Routing Accepted
ADR-003: LLM Backend — llama.cpp Default + MLX Apple Silicon Fast Path Accepted
ADR-004: Grammar-Constrained Tool Calls Accepted
ADR-005: InputBackend Protocol Accepted
ADR-006: EditorBridge Protocol Accepted
ADR-007: Personal Memory — sqlite-vec + SQLCipher Accepted
ADR-008: Distribution — cargo-dist + Per-Distro Packagers Accepted
ADR-009: Python Plugin SDK via Embedded PyO3 Accepted
ADR-010: Preserve v0.4 JSON-RPC 2.0 IPC Contract Accepted
ADR-011: Zero Telemetry, Offline-Default, Opt-In Cloud Accepted
ADR-012: Opt-In, Local, Encrypted Self-Improvement Loop Accepted
ADR-013 — On-Device LLM Dictation Cleanup (dual-path, parity) Accepted
ADR-014 — Held-out validation for yazses tune proposals Accepted
ADR-015 — Dysfluency-Friendly Mode (collapse pass + accessibility preset) Accepted
ADR-016 — The dependency budget: features pay for themselves Accepted
ADR-017 — Intel Mac support: build it while it is free, and put the end date in writing Accepted
ADR-018 — Show the price before charging it; defer third-party plug-ins Accepted
ADR-019 — The egress inventory: every way data can leave, and the rule for adding one Accepted
ADR-020 — Agent protocols: which one YazSes needs, and which it must not adopt Accepted
ADR-021 — The one thing to invest in: carry the cost of an error through the pipeline Accepted
ADR-v04-001: llama-cpp-python for Tier 2 SLM Intent Routing
ADR-v04-002: LSP Context Injection for Whisper Decoder Priming
ADR-v04-003: EMG Backend USB Serial Protocol (YESP)
ADR-v2-000 — YazSes v2: the Voice-First Interaction Layer (umbrella) Accepted
ADR-v2-001 — Confidence Ink & Voice Re-pick Accepted
ADR-v2-002 — Prosody Auto-Formatting (pauses → punctuation, stress → emphasis) Accepted
ADR-v2-003 — Spoken Edit Mode (open-ended interactive dictation) Accepted
ADR-v2-004 — Context-Primed Dictation & Commanding Accepted
ADR-v2-005 — Spoken Recall & Ambient Scratch Accepted
ADR-v2-006 — Voice-to-Tool (offline Spoken MCP) Accepted
ADR-v2-007 — AT-SPI Voice Pilot (accessibility-tree desktop control) Accepted
ADR-v2-008 — True Code-Switch Dictation (make [polyglot] real) Accepted
ADR-v2-009 — Personal Speech Adapter (on-device personalization) Accepted
ADR-v2-010 — Gaze-Routed Dictation & Point-and-Speak Accepted
ADR-v2-011 — sEMG Command Layer & Modality Role Router Accepted
ADR-v2-012 — Accessibility Continuum Accepted
ADR-v2-013 — Glasses↔Desktop Dictation Bridge Accepted
ADR-v2-014 — Real-time Offline Speech Translation Accepted
ADR-v2-015 — Real-time Noise-Suppression Front-End Accepted
ADR-v2-016 — Predictive Dictation Completion Accepted
ADR-v2-017 — Emotion / Tone-Aware Formatting Accepted
ADR-v2-018 — Continuous Voice-Biometric Gate + Anti-Spoof Accepted
ADR-v2-019 — Ambient Meeting Scribe (streaming diarization) Accepted
ADR-v2-020 — Voice-Grounded RAG over Personal Notes Accepted
ADR-v2-021 — Atypical-Speech Personalization + Adapter Held-Out Gate Accepted
ADR-v2-022 — Neural-Codec Ultra-Low-Latency Streaming STT Accepted
ADR-v2-023 — Silent-Speech / Subvocal (sEMG) Input Accepted
ADR-v2-024 — Pure-Vision Screen Commanding (VLM) Accepted
ADR-v2-025 — Hallucination Guard Accepted
ADR-v2-026 — Voice Snippets (spoken text expander) Accepted
ADR-v2-027 — Phonetic Corrector (fix mis-heard names by sound) Accepted
ADR-v2-028 — Multi-User Voiceprint Profiles Accepted
ADR-v2-029 — Semantic Auto-Stop (hands-free tap-and-speak) Accepted
ADR-v2-030 — Voice Mouse Grid (pointer control by voice) Accepted
ADR-v2-031 — Spoken Code Mode Accepted
ADR-v2-032 — Spoken Math → LaTeX Accepted
ADR-v2-033 — Wake-Word Activation Accepted
ADR-v2-034 — Vocal-Strain Guard Accepted
ADR-v2-035 — Speaking Coach (private self-analytics) Accepted
ADR-v2-036 — Smart-Paste Format Adaptation Accepted
ADR-v2-037 — Audio-Anchored Scrubbing Accepted
ADR-v2-038 — Dictation Reflow (Voice Outliner) Accepted
ADR-v2-039 — Acoustic Context Profiles Accepted
ADR-v2-040 — Mood Ledger (speech-sentiment journal) Accepted
ADR-v2-041 — Pronunciation Feedback (L2 practice mode) Accepted
ADR-v2-042 — Personal Read-Back Voice Accepted
ADR-v2-043 — Gesture Chords Accepted
ADR-v2-044 — Two-Way Live Interpreter Accepted
ADR-v2-045 — Entity Inverse Text Normalization (ITN) Accepted
ADR-v2-046 — Redaction Ink Accepted
ADR-v2-047 — Field-Aware Dictation Accepted
ADR-v2-048 — Corpus Voiceprint Scrub Accepted
ADR-v2-049 — Compose-in-Target-Language Accepted
ADR-v2-050 — Grammar Repair (minimal-edit GEC) Accepted
ADR-v2-051 — Screen-Grounded Dictation Accepted
ADR-v2-052 — Head-Pointer Accepted
ADR-v2-053 — Silent Lip-Reading Input (VSR) Accepted
ADR-v2-054 — Sign-Language Input (SLR) Accepted
ADR-v2-055 — Emoji & Symbol by Voice Accepted
ADR-v2-056 — Voice Unit Conversion Accepted
ADR-v2-057 — Spoken Temporal Normalizer Accepted
ADR-v2-058 — Mid-Utterance Self-Repair Accepted
ADR-v2-059 — Spoken Spreadsheet / Table Mode Accepted
ADR-v2-060 — Clipboard-History by Voice Accepted
ADR-v2-061 — Ambient Audio-Event Guard Accepted
ADR-v2-062 — On-Device Condense Accepted
ADR-v2-063 — Structured Form / Slot-Filling Dictation Accepted
ADR-v2-064 — Few-Shot Personal Command Spotter Accepted
ADR-v2-065 — Terminal Command Safety Gate Accepted
ADR-v2-066 — Spoken Regex Builder Accepted
ADR-v2-067 — Structured-Markup Dictation Accepted
ADR-v2-068 — Voice-Driven Document-Wide Find-and-Replace Accepted
ADR-v2-069 — Hard Contextual Biasing (hotword trie) Accepted
ADR-v2-070 — Voice-Controlled Window / Workspace Management Accepted
ADR-v2-071 — Citation-by-Voice from a local BibTeX/CSL library Accepted
ADR-v2-072 — Per-Language Auto Model Switching Accepted
ADR-v2-073 — Adaptive Latency Governor Accepted
ADR-v2-074 — Diarized Conversation Capture with Rename-by-Voice Accepted
ADR-v2-075 — Phonetic Spelling Mode Accepted
ADR-v2-076 — Voice Git Choreographer (reversibility-gated) Accepted
ADR-v2-077 — Confidence-Gated Re-Ask Accepted
ADR-v2-078 — Verbatim ⇄ Autoformat Live Toggle Accepted
ADR-v2-079 — Self-Learning Correction Dictionary Accepted
ADR-v2-080 — Voice Fuzzy File Open Accepted
ADR-v2-081 — Voice Jump-to-Symbol / Structural Hop Accepted
ADR-v2-082 — Spoken Shell Pipeline Builder (dry-run first) Accepted
ADR-v2-083 — Recording Import (batch transcription) Accepted
ADR-v2-084 — Crowd-Proof Dictation (target-speaker extraction) Accepted
ADR-v2-085 — Chorded Shortcut Synthesis Accepted
ADR-v2-086 — Inline Compute Accepted
ADR-v2-087 — Voice Case & Identifier Transform on Selection Accepted
ADR-v2-088 — Auto-Pairing & Wrap-Selection for Code Dictation Accepted
ADR-v2-089 — Voice Undo/Redo Timeline Accepted
ADR-v2-090 — Session Bookmarks & Resume Accepted
ADR-v2-091 — Spoken Table → CSV / Field Data Entry Accepted
ADR-v2-092 — Word-Count & Writing-Goal Tracker Accepted
ADR-v2-093 — Local Voice Timer & Break Reminder Accepted
ADR-v2-094 — Focus-Class Auto-Profile Switching Accepted
ADR-v2-095 — Vocal Joystick (continuous non-speech analog control) Accepted
ADR-v2-096 — Earcon Feedback Language (non-speech eyes-free state cues) Accepted
ADR-v2-097 — Mouth-Sound Switch Access (non-verbal acoustic switches + scanning) Accepted
ADR-v2-098 — Beam-Steered Spatial VAD (2-mic direction-of-arrival gate) Accepted
ADR-v2-099 — Breath-Paced Dictation Accepted
ADR-v2-100 — Whisper-Aware Mode Accepted
ADR-v2-101 — Hesitation-Hold Endpointing Accepted
ADR-v2-102 — Involuntary-Vocalization Auto-Excision Accepted
ADR-v2-103 — Pitch-Contour Vocal Gestures Accepted
ADR-v2-104 — Prosodic Auto-Punctuation (acoustic, word-free sentence structure) Accepted
ADR-v2-105 — Vocal Morse (two-tone timing-coded AAC) Accepted
ADR-v2-106 — Checksum-Validated Data Entry Accepted
ADR-v2-107 — Diagrams-as-Code by Voice (Mermaid/Graphviz) Accepted
ADR-v2-108 — Interruptible Read-Back Proofreading (barge-in alignment) Accepted
ADR-v2-109 — Local Style-Consistency Enforcer (Vale-lite) Accepted
ADR-v2-110 — Screenplay & Dialogue Auto-Format (Fountain) Accepted
ADR-v2-111 — Semantic Line Breaks (version-control-friendly prose) Accepted
ADR-v2-112 — Spoken Spaced-Repetition Capture Accepted
ADR-v2-113 — Suggestion-Mode Dictation (CriticMarkup tracked changes) Accepted
ADR-v2-114 — Acronym / Glossary First-Use Manager Accepted
ADR-v2-115 — HatSelect (spoken structural token addressing) Accepted
ADR-v2-116 — Romanized → Native-Script Transliteration Accepted
ADR-v2-117 — BrailleOut (dictation as Unicode Braille output) Accepted
ADR-v2-118 — WordFind (offline reverse dictionary) Accepted
ADR-v2-119 — Echo (own-audio replay for a text span) Accepted
ADR-v2-120 — SRPace (screen-reader-paced injection) Accepted
ADR-v2-121 — LoadGuard (cognitive-load-aware guardrails) Accepted
ADR-v2-122 — Diacritize (diacritics restoration) Accepted
ADR-v2-123 — SafeGlyph (homoglyph/confusable hazard detection) Accepted
ADR-v2-124 — Spoken Outline (voice-driven outline structuring) Accepted
ADR-v2-125 — Diarized Recording Import (yazses transcribe <file>) Proposed
ADR-v2-126 — Cloud Transcription Escalation (design-only, deferred) Proposed
ADR-v2-127 — Live Meeting Mode (hands-free capture + hybrid diarization) Proposed
ADR-v2-128 — On-device Meeting Minutes (speaker-aware notes) Proposed
ADR-v2-129 — Killer Features 10x: gaze deixis, sotto-voce channel, activation-source seam, pluggable STT Accepted