Doku- & Doku-Vorgaben-Review (Stand v0.150.0, 2026-09-26)
Zielgruppen: Business/Management (Kernaussage + Maßnahmenplan) · IT-Dev/Doku-Pfleger (Befunde mit Datei:Zeile/Beleg). Gegenstand: Nicht die App, sondern die Dokumentation selbst — Inhalt, Struktur und die Doku-Vorgaben (CLAUDE.md-Leitprinzip „Dokumentation als Meisterwerk": pyramidal · zielgruppen-gerecht · visuell · konsistent). Schwester-Review zur App:
UX-Prozess-Review-2026-09.md(parallel auf v0.128.0 aufgefrischt). Methode: Re-Audit über 12 Minor-Versionen (v0.116.1 → v0.128.0). Zwei Achsen: (1) Doku↔Doku-Konsistenz (Stand-Stempel-/Testzahl-Sweep über alle Einstiegs-Docs, ID-System, MED-OP-Status, Landkarte) inkl.scripts/check-doc-consistency.sh; (2) Doku↔Code-Abdeckung — stimmen Feldnamen/Enums/Routen und ist das seit v0.116.1 Gebaute (durchlaufender Timer + Web-Push · „Akte" → „Mandant"-Rename · Kunden-Self-Service- Portal S1/S2 · Onboarding-Grunddaten datensparsam + 3-Schritte-Stepper · Ablage-Spiegel · e2e/Playwright- Suite) dokumentiert und nichts Totes beschrieben. Bezugspunkt & Gültigkeit (MED-D-97): v0.128.0 · Commit(Commit wird beim Merge gestempelt)· 2026-09-12. Löst das v0.116.1-Audit (MED-D-259) ab. Vor-BacklogMED-OP-DOKU-9(B49–B52): B49 teilweise erledigt (MED-D-264), B50 weitgehend rekonziliert, B51/B52 verifiziert offen → weitergetragen. Neu abgeleitet: B53–B54 →MED-OP-DOKU-10(Doku-Welle 8). Nächster Doku-Audit gemäß Stale-Regel (agents.md§6.7).
0. Refresh v0.150.0 (2026-09-26, MED-OP-REVIEW-1, MED-D-370) — Delta-Audit v0.138.0 → v0.150.0
Bezugspunkt: v0.150.0 · Commit 96f4227 (Basis main) + PR #370 · 2026-09-26 · 12 Minor-Versionen seit v0.138.0
(Stale-Regel ausgelöst). Geprüft: MED-D-312 … MED-D-337 und MED-D-359 (Log-Fragmente; Portal-Ausbau, Mail-Versand, Einfachheits-Audit U/K/I/M,
Begriffsentscheidung "Kunde"/"Mandat", Kundenseiten-Hilfe, Kundenportal-Aufgabenliste, interne Oberfläche,
Unterschrift nur über den Assistenten).
Kernaussage: Die schnellen Logs sind lückenlos und der Stand-Stempel stimmt überall. Die Drift liegt wieder in den Kopien: Testzahlen, die an drei Stellen von Hand abgeschrieben waren, eine Architektur-Doku, die ein neues Portal-Verhalten nicht kannte, und neue UI-Begriffe ohne Glossar-Eintrag. Alle fünf neuen Befunde (B56–B60) und die drei Alt-Befunde B51, B52, B54 sind in diesem Refresh behoben — der Doku-Backlog (MED-OP-DOKU-9/10) ist leer.
| Achse | Verdikt |
|---|---|
Stand-Stempel README · HANDOFF §2 · CLAUDE · MVP-Scope · Feature-Liste · Lastenheft · Management-Summary · Sanity · Test-Übersicht = 0.150.0 (= server/src/version.ts) | ✅ |
| ID-Lückenlosigkeit MED-D-312…336 in Decision-Log + CHANGELOG + HANDOFF §2 | 🟡 → ✅ (B60: MED-D-321 fehlte in HANDOFF §2, nachgetragen) |
Testzahl kanonisch Test-Uebersicht.md (799 Vitest / 65 · 49 E2E / 18) | 🟡 → ✅ (B56) |
| Doku↔Code neue Flächen: Kontakt-Fußzeile (Deploy.md §7f ✅), Unterschrift-Einweg (Unterschriften.md ✅, MED-D-337), Portal-Aufgabenliste (B57) | 🟡 → ✅ |
| Glossar neue sichtbare Begriffe (MED-D-330 ✅ "Kunde"/"Mandat"; MED-D-334 "Vollständigkeit", "Unterschrift-Stufe") | 🟡 → ✅ (B58) |
Landkarte docs/README.md führt alle Doku-Dateien | 🟡 → ✅ (B59: Audit-Docs fehlten) |
| Alt-Befunde B51 (Unterschriften.md "nicht live verifiziert") | ✅ behoben (Kern live verifiziert MED-D-238/239) |
B52 produkt/Design-Entscheidungen-Kunde.md (Stand 0.99.12) | ✅ behoben (Nutzer-Auftrag "B52 und B54 fixen"): Stand-Stempel 0.150.0 und Status je AD am Code nachgeprüft — AD-005/008/009/010 von 🟡 auf ✅ (MED-D-246/223/247/248–257), AD-002/006/014 um die jüngeren Umsetzungen ergänzt; Kernaussage + Legende angepasst ("gebaut", Live-Betrieb der Signatur = OP-SIGN-1) |
B54 Dokumentenverwaltung-NextCloud.md ohne Ablage-Spiegel (MED-D-288) | ✅ behoben: neuer Abschnitt "Ablage-Spiegel in der Oberfläche" (Kernaussage, Mermaid-Fluss erwartet → Spiegel, Regeln, Begriffe, Abgrenzung zu MED-OP-FILES-1) |
| # | Befund | Beleg | Maßnahme (dieser Refresh) |
|---|---|---|---|
| B56 | Testzahl an drei Stellen von Hand kopiert und veraltet | README.md:51 (692/57), MVP-Scope.md:28 (778/63), Management-Summary.md:29 (793 + 33) | durch Verweis auf die kanonische Quelle Test-Uebersicht.md ersetzt — beseitigt die Ursache, nicht nur die Zahl |
| B57 | Portal-Architektur-Doku kennt die Aufgabenliste (MED-D-333) nicht | Kunden-Self-Service-Portal.md ohne MED-D-333 | Absatz "Eine To-do-Liste" ergänzt (Ableitung, Token-Strecken, Keep-alive, Mail-Texte) |
| B58 | Neue UI-Begriffe ohne Glossar | Glossar ohne "Vollständigkeit"/"Unterschrift-Stufe" | beide in glossar.mjs (mit Alias "Aktenreife" bzw. "eIDAS-Niveau") + neu generiert (44 Begriffe) |
| B59 | Landkarte ohne die Meisterwerk-Audits | docs/README.md §betrieb | zwei Zeilen (App-/Doku-Audit, je aktuelle + ältere Ausgabe) |
| B60 | MED-D-321 fehlt in HANDOFF §2 | Decision-Log + CHANGELOG ja, HANDOFF nein | Nachtrag in HANDOFF §2 |
Wurzelursache (wie in den Vorrunden): Werte, die sich je PR ändern, dürfen nur an einer Stelle stehen;
überall sonst ein Verweis (G-2). Die Versions-Stempelung ist per Skript abgesichert, die Testzahl-Kopien waren es
nicht. Empfehlung (kein neuer OP, Teil von MED-OP-REVIEW-1): bei neuen Doku-Stellen keine Zahlen abschreiben,
sondern auf Test-Uebersicht.md verweisen.
0a. Refresh v0.138.0 (2026-09-23, MED-OP-REVIEW-1) — Delta-Audit v0.128.0 → v0.138.0 (historisch)
Kernaussage des Refreshs: die Doku-Disziplin hält über die Slices MED-D-289…311 — Stand-Stempel, Testzahl und IDs sind konsistent; eine in dieser Runde selbst eingeführte OP-Registrierungs-Lücke wurde sofort geschlossen (B55).
| Achse | Verdikt |
|---|---|
Stand-Stempel aller Einstiegs-Docs (README/MVP-Scope/Management-Summary/Test-Uebersicht/Sanity/Feature-Liste/Lastenheft/CLAUDE) = 0.138.0 | ✅ (Doku-Check grün) |
Testzahl 746 / 61 in Test-Uebersicht = kanonisch, in Management-Summary rekonziliert | ✅ |
| ID-Lückenlosigkeit MED-D-289…311 in Decision-Log + CHANGELOG + HANDOFF §2 geloggt | ✅ |
| Doku↔Code der neuen Flächen dokumentiert: Portal-Go-Live (MED-D-310) + Login-Härtung (MED-D-311) in Decision-Log/CHANGELOG/HANDOFF, Deploy.md §7e (Runbook: MailChannels-Secret/DKIM, TURNSTILE, Access-Bypass), RISK-33 (Restrisiko 9→4), Kunden-Besprechungspunkte (MED-KB-13 ✅), Kunden-Self-Service-Portal.md (S5) | ✅ |
| B55 (neu, niedrig → in dieser Runde behoben): MED-OP-PORTAL-2/3 wurden in MED-D-310/311 referenziert, standen aber nicht in der HANDOFF-§4-OP-Liste → jetzt als §4-Zeilen registriert (PORTAL-2 offen, PORTAL-3 ✅) | ✅ geschlossen |
Backlog weitergetragen: MED-OP-DOKU-9 (B51/B52), MED-OP-DOKU-10 (B53/B54) bleiben offen. Der Vollaudit
unten bleibt als historische Bezugsrunde v0.128.0 stehen (Historie in-file). Im v0.128.0→v0.138.0-Delta
kein neuer Doku↔Code-Widerspruch offen (die Alt-Findungen B51/B52/B54 laufen unverändert weiter).
1. Kernaussage (historische Bezugsrunde v0.128.0 — aktueller Stand s. §0 oben, Vorrunde §0a)
Hinweis (MED-D-312): Der folgende Abschnitt ist die historische Vollaudit-Runde vom 2026-09-12 (Bezugspunkt v0.128.0; die dort genannten
0.127.1/692/57sind der damalige Stand, nicht der aktuelle). Der Refresh §0a ist der Delta-Audit zum Bezugspunkt v0.138.0 / 746 Tests, mit dem damaligen Ist-Stand0.138.1/ 752 Vitest (dokumentiert in der damaligenHANDOFF.md§2 +docs/betrieb/Test-Uebersicht.md). Der jüngste Refresh v0.150.0 steht in §0.
Die mechanische Doku-Disziplin ist über 12 Minor-Versionen makellos — alle Einstiegs-Docs tragen
konsistent 0.127.1 (dieser PR stempelt auf 0.128.0), die Testzahl 692/57 rekonziliert überall, die IDs
MED-D-260…288 sind lückenlos geloggt —, und der große „Akte" → „Mandant"-Rename ist Doku↔Doku sauber
durchgezogen; die Drift sitzt punktuell in zwei Stellen: die e2e/Playwright-Suite dieses PR (MED-D-289) ist
noch nicht als eigene Test-Spur geführt, und die maßgebliche NextCloud-Doku bildet den Ablage-Spiegel
(MED-D-288) nicht ab. Das ist dieselbe Wurzelursache, die die Doku-Audits wiederkehrend flaggen (schnelle
Logs aktuell, langsame Rahmen-Docs veralten) — diesmal deutlich kleiner als zuvor.
Doku↔Doku (stark): Der Stand-Stempel-Sweep ist sauber — README · HANDOFF §2 · MVP-Scope ·
Feature-Liste · Lastenheft · Management-Summary · Sanity-Checkliste · Test-Übersicht · CLAUDE.md
nennen alle 0.127.1 (deckungsgleich mit server/src/version.ts:4); die Stempelung auf 0.128.0 gehört zu
diesem PR (MED-D-289) und ist zum Prüfzeitpunkt in Arbeit — kein Defekt. Die Testzahl 692/57
rekonziliert an allen Pflichtstellen (inkl. der „Was läuft wo?"-Tabellenzeile, Test-Uebersicht.md:66); die
Decision-IDs MED-D-260…288 sind durchgängig in CHANGELOG/Decision-Log/Feature-Liste geführt; der
„Akte" → „Mandant"-Rename (MED-D-277/278) ist über 20 Docs + Glossar-Quelle sauber durchgezogen (Grammatik,
Eigennamen bewusst behalten). check-doc-consistency.sh meldet nur die zwei erwarteten „Audit veraltet"-
Warnungen — genau die, die dieser Refresh auflöst.
Doku↔Code (die kleine Drift):
Dokumentenverwaltung-NextCloud.mdbildet MED-D-288 nicht ab (B54, niedrig-mittel): die maßgebliche DMS-Architektur-Doku kennt die neue Ablage-Reiter-Semantik (Hauptliste = nurnextcloudPfad-gesetzte Dokumente; erwartete in einer Disclosure) nicht — sie steht nur in Feature-Liste/HANDOFF.MED-OP-FILES-1(:245) rahmt die Live-Spiegelung als offen, aber die visuelle Spiegel-Semantik (MED-D-288, Option A) fehlt.B53(im selben PR erledigt): die e2e/Playwright-Suite (MED-D-289) ist inTest-Uebersicht.mdjetzt als eigene Test-Spur geführt — Kopfzeile (692/57Vitest +9/4Playwright), „E2E lokal"-Blockquote und der CI-Pipeline-JobClient (e2e). Ursprünglich als Doku-Pflege-Befund geführt, mit der Test-Übersicht- Aktualisierung dieses PR direkt geschlossen (CodeRabbit #327).
Vor-Backlog MED-OP-DOKU-9: B51 + B52 verifiziert offen (s. §3.1); B49/B50 überwiegend erledigt.
Bewertung je Dimension (10 = Meisterwerk; ↑/↓ ggü. v0.116.1):
| Dimension | v0.116.1 | v0.128.0 | Begründung |
|---|---|---|---|
| Doku↔Doku-Konsistenz (Stempel, IDs, Zahlen) | 9 | 9,5 | Stempel/Testzahlen/IDs makellos rekonziliert (0.127.1, 692/57 überall); der große „Akte" → „Mandant"-Rename ist Doku↔Doku sauber durchgezogen (MED-D-278) |
| Doku↔Code-Abdeckung | 8 | 8,5 | Erholung: B49 (Fremdformulare) weitgehend nachgezogen (MED-D-264), Portal S1/S2 + Grunddaten + Weltmodell dokumentiert, e2e-Test-Spur im selben PR ergänzt (B53 ✅); Rest-Drift: NextCloud-Doku ohne MED-D-288 (B54); B51 (Unterschriften.md „nicht live verifiziert") offen |
| Pyramidal / Zielgruppen | 9 | 9 | unverändert stark (BLUF durchgängig, Lesepfade gepflegt) |
| Visualisierung (Mermaid/Tabellen) | 9 | 9 | unverändert (Hash-Ketten-/Bankkonto-/Weltmodell-/Timer-Segment-Diagramme stehen; Portal-Slice-Tabelle) |
2. Was gehalten wurde (bewahren)
- Stand-Stempel-Disziplin über 12 Minor makellos: alle 9 Einstiegs-Docs auf
0.127.1, deckungsgleich mitserver/src/version.ts:4(APP_VERSION = '0.127.1') —README·HANDOFF:17·MVP-Scope:26·Feature-Liste:4·Lastenheft:9·Management-Summary:5/26/115·Sanity-Checkliste:1·Test-Uebersicht:3·CLAUDE.md:183. - Testzahl
692/57an allen Pflichtstellen rekonziliert — inkl. der „Was läuft wo?"-Tabellenzeile (Test-Uebersicht.md:66). - ID-Abdeckung lückenlos: MED-D-260…288 durchgängig in CHANGELOG/Decision-Log/Feature-Liste.
- „Akte" → „Mandant"-Rename Doku↔Doku sauber (MED-D-277/278): 20 Docs + generierte Glossar-Quelle
angeglichen (grammatik-korrekt), Eigennamen (
Aktenreife,Akteur, Programmname „Akten-Cockpit-Redesign", Dateinamen) bewusst behalten, append-only Historie unangetastet (G-4). - Doku↔Code an den neuen Stellen sauber: Kunden-Self-Service-Portal S1/S2 (
Kunden-Self-Service-Portal.md:157-158: S2 als ✅ gebaut, Endpunkte + Flags deckungsgleich mitportal-service.ts), durchlaufender Timer + Web-Push (Zeiterfassung-Segmente-und-Push.md, MED-D-275/276), Onboarding-Grunddaten datensparsam (Weltmodell- Wertobjekte Kontakt/Steuer/Steuerberater, Lastenheft R1-F44–F49, MED-D-284), Onboarding-3-Schritte-Stepper (Feature-Liste:37). - Mechanischer Check grün außer den zwei erwarteten Audit-Staleness-Warnungen (kein Konflikt-Marker, kein
version.ts↔Doku-Mismatch, keine Log-Hygiene-Flags).
3. Befunde
3.1 Status Vor-Backlog MED-OP-DOKU-9 (B49–B52)
| # | Befund | Beleg (v0.128.0 verifiziert) | Status |
|---|---|---|---|
| B49 | Fremdformulare.md beschreibt gebautes MED-OP-FORM-6 als „nicht bauen" | Fremdformulare.md:147-148 (§ „teilweise gebaut" + dokumenttyp/MED-D-257 beschrieben, MED-D-264) + Runbook §9 | teilweise erledigt — Rest: §6/§7 (:97 „bewusst zurückgestellt") + FremdformularVorlage-Feldspec noch nicht durchgängig |
| B50 | HANDOFF §4 MED-OP-FORM-5/6 widerspricht §2 + Feature-Liste | HANDOFF.md:833 (MED-OP-FORM-5-Eintrag zeigt Weg A/B/AD-009 jetzt als ✅ gebaut) | weitgehend rekonziliert (Tracker :893 führt es noch als offen — Bagatelle) |
| B51 | Unterschriften.md nennt den DocuSign-Adapter „nicht live verifiziert" trotz MED-D-238/239 | Unterschriften.md:7 („noch nicht live verifiziert") + :200 („gebaut, aber nicht live verifiziert") | offen |
| B52 | Design-Entscheidungen-Kunde.md mit stalem Stand-Stempel 0.99.12 | Design-Entscheidungen-Kunde.md:6 (Stand: Version 0.99.12) | offen |
3.2 Neue Befunde (der nächste Backlog → MED-OP-DOKU-10, Doku-Welle 8)
Die Nummerierung setzt die Doku-Spur fort (letzter Doku-Audit schloss B49–B52; der App/UX-Track läuft getrennt bis B45). Neu: B53–B54. Beide niedrig–mittel, kein Blocker.
B53 — e2e/Playwright-Suite (MED-D-289) als eigene Test-Spur in Test-Uebersicht.md — ✅ im selben PR erledigt (war: mittel; Doku↔Code)
Ursprünglicher Befund: Test-Uebersicht.md führte nur Server-Vitest (692/57), Client-Build und die
Doku-Checks — keine e2e/Playwright-Lane. Erledigt mit diesem PR (CodeRabbit #327): die Kopfzeile nennt
jetzt 692/57 Vitest + 9/4 Playwright, es gibt die „E2E lokal"-Blockquote (npm run e2e:ci) und der
CI-Pipeline-Abschnitt listet den Job Client (e2e) (gated wie client-build, Teil des CI Gate). Die
Vitest-Zahl 692 bleibt unberührt (Playwright zählt separat). Kein offener Rest.
B54 — Dokumentenverwaltung-NextCloud.md bildet den Ablage-Spiegel (MED-D-288) nicht ab (niedrig-mittel; Doku↔Code)
Die maßgebliche DMS-Architektur-Doku beschreibt die Ablage-/NextCloud-Integration, kennt aber die neue
Ablage-Reiter-Semantik aus MED-D-288 nicht: Hauptliste = nur tatsächlich abgelegte Dokumente (Referenzen
mit gesetztem nextcloudPfad), erwartete/provisionierte Referenzen in einer ausklappbaren Unterliste
(.md-erwartet). Der Punkt steht nur in Feature-Liste.md:17 + HANDOFF; MED-OP-FILES-1 in der Doku
(Dokumentenverwaltung-NextCloud.md:245) rahmt die Live-Spiegelung als offen (→ MED-KB-4), erwähnt aber
die bereits gebaute visuelle Spiegel-Semantik (Option A) nicht. Fix: einen kurzen Abschnitt/Verweis
ergänzen (visuelle Spiegel-Semantik gebaut MED-D-288; echte Live-Spiegelung bleibt MED-OP-FILES-1).
4. Maßnahmenplan
Doku-Welle 8 (MED-OP-DOKU-10) + Rest-Vormeile — die Rahmen-Docs hinter den Log-Docs nachziehen.
Reihenfolge nach Wirkung: B53 ✅ (e2e-Test-Spur in Test-Uebersicht.md — mit diesem PR erledigt) →
B51 (Unterschriften.md OP-SIGN-1-Rest auf Prod-QES/AVV/PandaDoc verengen —
höchster echter Doku↔Code-Widerspruch, seit v0.116.1 offen) → B54 (NextCloud-Doku um MED-D-288 ergänzen) →
B52 (Design-Entscheidungen-Kunde.md re-stempeln nach Inhalts-Stichprobe) → B49-Rest (§6/§7 :97 +
FremdformularVorlage-Feldspec) → B50 (Tracker-Bagatelle glätten). Danach ist die Doku↔Code-Achse wieder
deckungsgleich mit dem Live-Stand. Die mechanische Achse (Stempel/Zahlen/IDs) ist bereits sauber und braucht
nur die laufende Je-PR-Pflege (inkl. der 0.128.0-Stempelung in diesem PR). Nächster Doku-Audit gemäß
Stale-Regel.
Dieses Audit ist ein Zeitdokument (MED-OP-REVIEW-1 / agents.md §6.7): Bezugspunkt v0.128.0 · Commit
(Commit wird beim Merge gestempelt) · 2026-09-12. Befunde werden als MED-OP-DOKU-9 (Rest B49/B51/B52) +
MED-OP-DOKU-10 (neu B53/B54) in den Backlog überführt, nicht im Audit abgearbeitet. Keine Versionsänderung
durch diesen Refresh (die 0.128.0-Stempelung gehört zum Feature-PR MED-D-289).