Projektwissen: Git-Vorgaben, Ticketzugriff, Tests und Einstieg

Erster Stand des Repositories AG_QGIS/Projektwissen (bisher Arbeitstitel
"Workspace", ADR 0006). Der lokale Ordner heisst weiter AG_QGIS, weil darin
auch die Plugin-Klone liegen.

Git verbindlich (ADR 0007), aus dem bisherigen Wiki-Konzept entwickelt:
- docs/leitfaden/05_git_arbeitsweise.md mit Kanal-Kette, Branch-Namen und
  Gitea-Branch-Schutz.
- Der Einstiegspunkt eines Fixes richtet sich nach dem Kanal, in dem der
  Fehler sitzt; ein Fix an testing oder stable ist erst mit der
  Rueckfuehrung nach unten abgeschlossen. Das fehlte bisher.
- Der stabile Kanal heisst stable, nicht main: der Release-Workflow in
  Repository:hidden/workflows fuehrt git checkout "$CHANNEL" aus, der
  Branchname muss also dem Kanalnamen entsprechen. Er existiert in keinem
  Plugin-Repo und ist vom Maintainer anzulegen.
- Der Mensch drueckt ab: .claude/settings.json sperrt push, merge, tag.
- scripts/hallo.py und /hallo holen den Stand aller Klone, per
  Fast-Forward wo gefahrlos; nie mergen, stashen oder verwerfen.

Ticketzugriff:
- scripts/gitea.py liest Issues, Kommentare und PRs ueber die oeffentliche
  API, ohne Token, nur GET. Schreibendes nur als Entwurf in entwuerfe/.
- Skill sn-ticket.

Tests (ADR 0009):
- docs/leitfaden/06_tests.md: Testebenen, Testpflicht, und wie eine
  Fachperson beurteilt, ob Tests fachlich sinnvoll sind.
- scripts/testkatalog.py erzeugt docs/tests/testkatalog.md per ast-Parsing,
  ohne Import und ohne QGIS. Befund: nur 100 von 332 Tests haben einen
  Docstring, sn_basis keinen einzigen von 87.
- Vorlage und erste Testkonzept-Seite mit Mermaid. Dabei gefunden und gegen
  origin geprueft: _ermittle_gebietstyp_aus_fbschl hat keinen Test, obwohl
  PR #44/#45 genau diese Funktion tolerant gemacht hat.
- docs/konzept/07_qgis_tests_plan.md: Stufenplan fuer Tests gegen echtes
  QGIS. Dabei aufgefallen: QGIS 3.40 ist seit Januar 2026 End of Life,
  qgis_min steht aber noch darauf.

Werkzeuge (ADR 0008):
- 04_werkzeuge_einrichten.md nur noch Claude Code als CLI und in VS Code.
- .vscode/ entfernt, brauchbare Einstellungen als persoenliche Vorlage.

Ausserdem: README als Einstieg neu aufgebaut, Mermaid-Diagramm in
schnittstellen.md repariert (unmaskierte Klammern, rendert seither nicht).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/entscheidungen/0009-tests-definition-of-done.md

@@ -0,0 +1,43 @@
+# 0009 – Tests sind Teil der Definition of Done, und sie werden für Menschen dokumentiert
+
+Status: vorgeschlagen · Datum: 2026-09-04 · Beteiligte: AG QGIS · Ergänzt 0003
+
+## Kontext
+Entscheidung 0003 machte den Baseline-Lauf vor jedem Pull Request zur Pflicht. Sie verhindert *Rückschritte*,
+verlangt aber keine *neuen* Tests. Bei überwiegend KI-erzeugtem Code ist das zu wenig: Ein Agent kann
+überzeugend erklären, dass etwas funktioniert, ohne dass es funktioniert.
+
+Der am 04.09.2026 erstmals erzeugte Testkatalog zeigt dazu einen zweiten Befund: Von 332 Testfällen haben nur
+100 (30 %) eine Beschreibung — `sn_basis` null von 87, `sn_plan41` einen von 44. Ohne Beschreibung ist von außen
+nicht erkennbar, was ein Test prüft. Damit kann niemand beurteilen, ob die Abdeckung **fachlich** sinnvoll ist,
+und genau das ist bei einer Fachanwendung die entscheidende Frage. Ein grüner Testlauf, dessen Inhalt niemand
+kennt, ist ein Gefühl, kein Nachweis.
+
+## Entscheidung
+1. **Neue Funktionalität ohne Test wird nicht gemergt.** Mindestens ein Test je neuem beobachtbarem Verhalten.
+   Bei einer Fehlerbehebung zuerst der Test, der den Fehler zeigt.
+2. **Jeder Test hat einen deutschen Docstring**, dessen erste Zeile mit `Prüft, dass …` beginnt. Diese Zeile ist
+   für die meisten Leser der einzige Kontakt mit dem Test.
+3. **Der Testkatalog wird erzeugt, nicht gepflegt.** `scripts/testkatalog.py` liest die Testdateien per `ast`
+   (ohne Import, ohne QGIS, ohne Abhängigkeiten) und schreibt `docs/tests/testkatalog.md`. Er wird mitcommittet;
+   `--pruefen` meldet, wenn er veraltet ist.
+4. **Fachlich wichtige Abläufe bekommen eine Testkonzept-Seite** in `docs/tests/` nach
+   `docs/vorlagen/testkonzept.md`: ein Mermaid-Diagramm des fachlichen Ablaufs, eine Tabelle
+   Schritt → deckender Test → bewusst nicht getestet mit Begründung, und die bekannten Lücken.
+   Damit kann eine Fachperson ohne Programmierkenntnisse prüfen, ob die Tests das Richtige prüfen.
+
+Die Docstring-Pflicht gilt für **neue und geänderte** Tests. Die 232 bestehenden Tests ohne Beschreibung werden
+nicht auf einen Schlag nachgezogen; der Abschnitt „Lücken" des Katalogs ist die Arbeitsliste, die nebenbei
+abgearbeitet wird.
+
+## Folgen
+Pull Requests werden etwas größer und etwas langsamer. Dafür wird zum ersten Mal überprüfbar, ob die Testsuite
+fachlich das Richtige abdeckt — bisher war nur bekannt, wie viele Tests grün sind. Der Katalog macht Lücken
+sichtbar, statt sie in Testdateien zu verstecken. Die Testkonzept-Seiten sind zusätzlicher Pflegeaufwand und
+lohnen nur für Abläufe, die fachlich wirklich wichtig sind — nicht für jede Funktion.
+
+## Verworfene Alternativen
+Nur den generierten Katalog (zeigt was getestet wird, aber nicht ob es genügt — genau die Prüfung, um die es
+geht, fiele weg); nur handgeschriebene Testkonzepte (laufen dem Code hinterher, dieselbe Drift, die die
+Wissensbasis sonst vermeidet); Testabdeckung in Prozent als Ziel (misst durchlaufene Zeilen, nicht fachliche
+Vollständigkeit, und verleitet zu Tests ohne Aussage).