codecentric · ccthmanthey · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/.planning/MILESTONES.md b/.planning/MILESTONES.md
@@ -0,0 +1,32 @@
+# Milestones
+
+## v1.0 Lokale Spracherkennung mit Transformers.js
+
+**Shipped:** 2026-05-08
+**Phases:** 6 (1-6) | **Plans:** 12 | **Requirements:** 34/34
+
+**Delivered:** Browser-based Whisper speech recognition running entirely in the client as a privacy-preserving alternative to cloud transcription, integrated into the c4 GenAI Suite extension system.
+
+**Key Accomplishments:**
+1. Registered transcribe-local NestJS extension with Vite COOP/COEP configuration and full regression verification
+2. Whisper Web Worker with singleton pipeline, WebGPU/WASM auto-detection, and 16kHz audio resampling
+3. Full UI integration: LocalTranscribeButton, DownloadProgressBanner, language dropdown, ChatInput wiring
+4. Production error handling: browser capability gating, mic denial toasts, download failure recovery, empty transcription handling
+5. Polish features: two-layer silence detection (RMS + hallucination filter), recording timer, privacy badge
+6. Code cleanup: JSDoc on all exports, 6 code review bug fixes, ESLint/Prettier compliance
+
+**Stats:**
+- Timeline: 2 days (2026-05-07 to 2026-05-08)
+- Production LOC: 856 (8 files, TypeScript/React)
+- Tests: 176/176 frontend, 225/225 backend, 30/33 E2E
+- Commits: ~90 milestone-scoped
+- Git range: feat(01-01) to style(06)
+- Nyquist: COMPLIANT (5/5 phases)
+- Audit: 34/34 requirements satisfied, 4 non-blocking warnings
+
+**Archives:**
+- `milestones/v1.0-ROADMAP.md`
+- `milestones/v1.0-REQUIREMENTS.md`
+- `milestones/v1.0-MILESTONE-AUDIT.md`
+
+**Tag:** v1.0
diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
@@ -0,0 +1,78 @@
+# Lokale Spracherkennung mit Transformers.js
+
+## What This Is
+
+Eine lokale, datenschutzkonforme Spracherkennung im Frontend der c4 GenAI Suite, die Whisper (whisper-small, quantisiert q8, ~240MB) via Transformers.js direkt im Browser ausfuehrt. Integriert als dritte konfigurierbare Variante im Extension-System neben Web Speech API und Azure Transcribe. Unterstuetzt Deutsch und Englisch, mit Fortschrittsanzeige beim Modell-Download, zweischichtiger Stille-Erkennung, und vollstaendiger Fehlerbehandlung.
+
+## Core Value
+
+Spracherkennung ohne dass Audiodaten den Browser verlassen -- vollstaendige Datenschutzkonformitaet bei gleichzeitiger Beibehaltung der bestehenden Cloud-Optionen.
+
+## Requirements
+
+### Validated
+
+- ✓ Lokale Whisper-Inferenz im Browser via Transformers.js (whisper-small q8 Modell) -- v1.0
+- ✓ Integration als Backend-Extension im bestehenden Extension-System -- v1.0
+- ✓ Aktivierbar pro Assistant ueber die Admin-UI -- v1.0
+- ✓ On-Demand-Download des Whisper-Modells (~240MB) mit Caching im Browser -- v1.0
+- ✓ Fortschrittsanzeige (Progressbar) beim erstmaligen Modell-Download -- v1.0
+- ✓ Sprachauswahl (de/en) ueber Dropdown -- v1.0
+- ✓ Maximale Aufnahmedauer von 2 Minuten -- v1.0
+- ✓ Record-then-Transcribe Implementierung -- v1.0
+- ✓ Bestehende Cloud-Optionen bleiben unveraendert erhalten -- v1.0
+- ✓ Vollstaendige Fehlerbehandlung (Mic-Verweigerung, Browser-Inkompatibilitaet, Download-Fehler, leere Transkription) -- v1.0
+- ✓ Zweischichtige Stille-Erkennung (RMS + Halluzinationsfilter) -- v1.0
+- ✓ Recording-Timer und Privacy-Badge -- v1.0
+
+### Active
+
+- [ ] Echtzeit-Transkription als spaetere Erweiterung (Architektur ist vorbereitet)
+- [ ] Audio-Level-Visualisierung waehrend der Aufnahme
+- [ ] Admin-konfigurierbare Whisper-Modellwahl (tiny/base/small)
+
+### Out of Scope
+
+- Echtzeit-Streaming-Transkription in v1 -- Whisper ist ein Batch-Modell, Chunking fuegt massive Komplexitaet hinzu
+- Modell-Auswahl durch Endnutzer -- fest auf whisper-small q8, kein User-facing UI dafuer
+- Vorab-Bundling des Modells -- wird on-demand geladen, App-Bundle bleibt klein
+- Offline-Faehigkeit -- Erstdownload erfordert Internetverbindung, vollstaendige Offline-Faehigkeit separates Projekt
+- Auto-Send nach Transkription -- Nutzer muss Text vor dem Senden pruefen koennen
+- Multi-Speaker Diarization -- Whisper-small unterstuetzt das nicht, in Chat-Kontext irrelevant
+- Audio-Datei-Upload -- anderes UX-Paradigma, separates Feature
+
+## Context
+
+Shipped v1.0 with 856 LOC production TypeScript/React across 8 files.
+Tech stack: React 19, Vite, Transformers.js (ONNX/WASM/WebGPU), Web Workers, NestJS Extension System.
+Test coverage: 176 frontend tests, 225 backend tests, 30/33 E2E tests (3 pre-existing REIS failures).
+All 34 v1 requirements satisfied and verified via milestone audit cross-reference.
+
+The implementation uses a singleton Whisper pipeline in a dedicated Web Worker with WebGPU auto-detection and WASM fallback. Audio capture via MediaRecorder, resampled to 16kHz mono Float32Array with zero-copy Transferable transfer to the Worker. Two-layer silence detection prevents Whisper hallucination on silent input.
+
+Known non-blocking items from audit: DownloadProgressBanner "Ready!" state is dead code, Worker instantiated for all assistants (not just transcribe-local), error code fallback handler, orphaned `loadFailed` i18n key.
+
+## Constraints
+
+- **Modellgroesse**: whisper-small q8 ist ~240MB -- erfordert einmaligen Download und sinnvolle UX dafuer (Progressbar)
+- **Browser-Kompatibilitaet**: Transformers.js benoetigt Web Worker Support und SharedArrayBuffer (COOP/COEP Headers)
+- **Inferenz-Performance**: Whisper-Inferenz im Browser ist langsamer als serverseitig -- 2-Minuten-Aufnahmelimit haelt das handhabbar
+- **Tech Stack**: Frontend ist React 19 + TypeScript + Vite -- Transformers.js als npm-Dependency integriert
+- **Extension-System**: Folgt dem bestehenden Pattern (Backend-Extension mit Spec + Frontend-Erkennung ueber Extension-Name)
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| whisper-small q8 statt whisper-base | Bessere Genauigkeit bei akzeptabler Modellgroesse (~240MB vs ~140MB), q8 Quantisierung | ✓ Good |
+| Record-then-Transcribe statt Echtzeit | Einfachere Erstimplementierung, Echtzeit architektonisch vorbereitet | ✓ Good |
+| On-Demand-Download statt Bundling | App-Bundle bleibt klein, Modell wird nur bei Bedarf geladen | ✓ Good |
+| 2 Minuten max. Aufnahmedauer | Praktikabel fuer lokale Inferenz, verhindert zu grosse Audiobuffer | ✓ Good |
+| Backend-Extension wie bestehende | Konsistenz mit Extension-System, Admin kann pro Assistant aktivieren | ✓ Good |
+| COOP/COEP credentialless statt require-corp | Vermeidet Breaking Changes bei bestehenden Cross-Origin-Ressourcen | ✓ Good |
+| Singleton Worker Pipeline | Vermeidet Re-Init pro Transkription, holt Modell einmal und haelt es im Speicher | ✓ Good |
+| RMS + Halluzinationsfilter (zweischichtig) | RMS-Check spart Inferenz bei Stille, Halluzinationsfilter faengt bekannte Whisper-Outputs | ✓ Good |
+| Render-phase state derivation | React-idiomatisches Pattern fuer prop-transition-Detection ohne ESLint-Verletzungen | ✓ Good |
+
+---
+*Last updated: 2026-05-08 after v1.0 milestone*
diff --git a/.planning/RETROSPECTIVE.md b/.planning/RETROSPECTIVE.md
@@ -0,0 +1,63 @@
+# Project Retrospective
+
+*A living document updated after each milestone. Lessons feed forward into future planning.*
+
+## Milestone: v1.0 -- Lokale Spracherkennung
+
+**Shipped:** 2026-05-08
+**Phases:** 6 | **Plans:** 12
+
+### What Was Built
+- Browser-based Whisper speech recognition via Transformers.js (whisper-small q8, ~240MB)
+- Full transcription pipeline: Web Worker singleton, audio capture/resampling, model download/caching
+- UI components: LocalTranscribeButton, DownloadProgressBanner, RecordingTimer, PrivacyBadge
+- Production error handling: browser gating, mic denial, download failure, empty transcription, silence detection
+- NestJS backend extension integrated into existing extension system
+- Bilingual support (de/en) with complete i18n and accessibility labels
+
+### What Worked
+- **Vertical slice approach**: Each phase delivered a complete, testable increment. Phase 1 (infrastructure) caught COOP/COEP issues early
+- **Milestone audit before close**: Identified all 12 tech debt items and 21 stale requirement checkboxes that would have been carried silently
+- **Code review as final phase**: Phase 6 code review found and fixed 6 real bugs (null dereferences, promise hangs, division by zero) that tests missed
+- **Extension system pattern**: Following the existing backend extension pattern made registration and admin UI integration straightforward
+- **Two-day timeline**: 6 phases, 12 plans, 856 LOC production code shipped in 2 days with full test coverage
+
+### What Was Inefficient
+- **Documentation tracking**: REQUIREMENTS.md checkboxes and traceability table fell out of sync across phases 2-4. 21 checkboxes showed [ ] for satisfied requirements. The tracking overhead per commit is low but was consistently skipped
+- **SUMMARY frontmatter inconsistency**: Phase 4 and 5 SUMMARYs missing `requirements_completed` field, Phase 3 SUMMARY omitted I18N-01. Frontmatter discipline dropped after Phase 2
+- **ROADMAP progress table stale**: Phase 2 and 3 progress table showed "0/2 Planned" when both were complete. Table was not updated during phase transitions
+
+### Patterns Established
+- **Render-phase state derivation**: Track previous prop in state, compute derived state synchronously during render. Satisfies both react-hooks/set-state-in-effect and react-hooks/refs ESLint rules
+- **Two-layer silence detection**: RMS energy pre-check before inference + hallucination post-filter after inference. Prevents wasted compute and catches known Whisper outputs
+- **Worker singleton pipeline**: Single Transformers.js pipeline instance held in Worker, with promise-based instance caching and reset-on-failure for retry capability
+
+### Key Lessons
+1. **Run code review before milestone close, not after**: Phase 6 code review found 6 bugs in code that had passed all 176 frontend tests. Static analysis and human review catch different classes of bugs than test suites
+2. **Automate requirement tracking or skip it**: Manual checkbox tracking across 34 requirements and 6 phases is high-friction and consistently went stale. Either automate via SUMMARY frontmatter extraction or accept verification-based tracking only
+3. **COOP/COEP credentialless is the safe default**: Using credentialless instead of require-corp avoided breaking existing cross-origin resources while still enabling SharedArrayBuffer
+
+### Cost Observations
+- Model mix: Primarily opus for planning/execution, sonnet for research/review
+- Notable: 2-day end-to-end milestone is fast for 856 LOC with full test coverage. Phase parallelization (waves) kept execution tight
+
+---
+
+## Cross-Milestone Trends
+
+### Process Evolution
+
+| Milestone | Phases | Plans | Key Change |
+|-----------|--------|-------|------------|
+| v1.0 | 6 | 12 | Initial milestone. Established phase/plan/wave pattern |
+
+### Cumulative Quality
+
+| Milestone | Frontend Tests | Backend Tests | E2E Tests | Production LOC |
+|-----------|---------------|---------------|-----------|----------------|
+| v1.0 | 176 | 225 | 30/33 | 856 |
+
+### Top Lessons (Verified Across Milestones)
+
+1. Code review catches bugs that test suites miss -- run before milestone close
+2. Documentation tracking needs automation -- manual checkbox tracking goes stale consistently
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
@@ -0,0 +1,30 @@
+# Roadmap: Lokale Spracherkennung mit Transformers.js
+
+## Milestones
+
+- ✅ **v1.0 Lokale Spracherkennung** -- Phases 1-6 (shipped 2026-05-08)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 Lokale Spracherkennung (Phases 1-6) -- SHIPPED 2026-05-08</summary>
+
+- [x] Phase 1: Infrastructure & Backend Extension (2/2 plans) -- completed 2026-05-07
+- [x] Phase 2: Core Transcription Pipeline (2/2 plans) -- completed 2026-05-07
+- [x] Phase 3: UI Integration (2/2 plans) -- completed 2026-05-07
+- [x] Phase 4: Error Handling (2/2 plans) -- completed 2026-05-08
+- [x] Phase 5: Polish & Refinement (2/2 plans) -- completed 2026-05-08
+- [x] Phase 6: Tech Debt & Documentation Cleanup (2/2 plans) -- completed 2026-05-08
+
+</details>
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Infrastructure & Backend Extension | v1.0 | 2/2 | Complete | 2026-05-07 |
+| 2. Core Transcription Pipeline | v1.0 | 2/2 | Complete | 2026-05-07 |
+| 3. UI Integration | v1.0 | 2/2 | Complete | 2026-05-07 |
+| 4. Error Handling | v1.0 | 2/2 | Complete | 2026-05-08 |
+| 5. Polish & Refinement | v1.0 | 2/2 | Complete | 2026-05-08 |
+| 6. Tech Debt & Documentation Cleanup | v1.0 | 2/2 | Complete | 2026-05-08 |
diff --git a/.planning/STATE.md b/.planning/STATE.md
@@ -0,0 +1,85 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: Lokale Spracherkennung
+status: shipped
+stopped_at: Milestone v1.0 complete
+last_updated: "2026-05-08T22:00:00.000Z"
+last_activity: 2026-05-08
+progress:
+  total_phases: 6
+  completed_phases: 6
+  total_plans: 12
+  completed_plans: 12
+  percent: 100
+---
+
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-05-08)
+
+**Core value:** Spracherkennung ohne dass Audiodaten den Browser verlassen -- vollstaendige Datenschutzkonformitaet bei gleichzeitiger Beibehaltung der bestehenden Cloud-Optionen.
+**Current focus:** Milestone v1.0 shipped. Planning next milestone.
+
+## Current Position
+
+Phase: All complete
+Plan: All complete
+Status: v1.0 shipped
+Last activity: 2026-05-08
+
+Progress: [██████████] 100%
+
+## Performance Metrics
+
+**Velocity:**
+
+- Total plans completed: 12
+- Timeline: 2 days (2026-05-07 to 2026-05-08)
+- Production LOC: 856 (8 files)
+
+**By Phase:**
+
+| Phase | Plans | Completed |
+|-------|-------|-----------|
+| 01 | 2 | 2026-05-07 |
+| 02 | 2 | 2026-05-07 |
+| 03 | 2 | 2026-05-07 |
+| 04 | 2 | 2026-05-08 |
+| 05 | 2 | 2026-05-08 |
+| 06 | 2 | 2026-05-08 |
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+All 9 key decisions from v1.0 milestone rated Good.
+
+### Pending Todos
+
+None.
+
+### Roadmap Evolution
+
+- v1.0 milestone completed and archived to .planning/milestones/
+
+### Blockers/Concerns
+
+None -- all blockers resolved during milestone execution.
+
+## Deferred Items
+
+Items acknowledged and carried forward from milestone close:
+
+| Category | Item | Status | Deferred At |
+|----------|------|--------|-------------|
+| *(none)* | | | |
+
+## Session Continuity
+
+Last session: 2026-05-08
+Stopped at: Milestone v1.0 complete
+Resume: /gsd-new-milestone for next version