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/vorlagen/AGENTS.repo.md

@@ -0,0 +1,21 @@
+# <paketname> (Repository <Repo-Name>)
+
+Teil des AG_QGIS-Projektwissens. Übergeordnete Regeln, Modulkarte, Schnittstellen, Fallstricke und Skills liegen im
+Workspace: `../AGENTS.md` und `../docs/` (wenn dieses Repo als Unterordner des Workspace geklont ist).
+Einzelklon? Projektwissen holen: https://entwicklung.flurneuordnung-sachsen.de/AG_QGIS/Projektwissen
+
+## Rolle
+<Ein bis drei Sätze: Was tut dieses Plugin, wovon hängt es ab, wer hängt davon ab.>
+
+## Aufbau
+<Ordner mit Einzeiler; große Dateien (> 600 Zeilen) mit Zeilenzahl nennen.>
+
+## Zusätzliche Regeln
+<Nur, was über den Workspace hinausgeht.>
+
+## Tests
+`python ../scripts/run_tests.py <paketname> --baseline` (Mock-Modus). In QGIS: `tests/test_qgis.bat` (Windows).
+
+## Release
+Version `JJ.M.N`, Tag `v<Version>-u` (unstable) / `-t` (testing) auf dem Kopf des Kanal-Branches. `metadata.txt` nicht
+von Hand pflegen (wird aus `.gitea/templates/metadata.template` erzeugt). `changelog.txt`: neue Einträge oben vor dem ersten `---`.

docs/vorlagen/CLAUDE.repo.md

@@ -0,0 +1,3 @@
+@AGENTS.md
+
+Beim Arbeiten im Workspace (`../AGENTS.md` vorhanden) gelten dessen Regeln und Skills zusätzlich.

docs/vorlagen/gitea_workflow_tests.yaml

@@ -0,0 +1,51 @@
+# Vorlage für .gitea/workflows/tests.yaml in Plugin_SN_Basis, Plugin_SN_Plan41, Plugin_SN_Verfahrensgebiet.
+# Führt die Mock-Modus-Tests bei Push/PR auf unstable und testing aus.
+# Voraussetzung: Gitea-Runner mit Label alpine-latest (wie beim Release-Workflow), Projektwissen-Repo öffentlich lesbar.
+# Der Lauf klont das Projektwissen und die abhängigen Plugin-Repos (unstable) und testet den aktuellen Checkout dieses Repos.
+
+name: Tests (Mock-Modus)
+run-name: "Tests | ${{ github.ref_name }}"
+
+on:
+  push:
+    branches: [unstable, testing]
+  pull_request:
+    branches: [unstable, testing]
+
+jobs:
+  mock-tests:
+    runs-on: alpine-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Abhängigkeiten installieren
+        shell: sh
+        run: apk add --no-cache bash git python3 py3-openpyxl
+
+      - name: Workspace und Repos holen
+        env:
+          GITEA: ${{ vars.RELEASE_URL }}          # z. B. entwicklung.flurneuordnung-sachsen.de
+        run: |
+          git clone --depth 1 "https://${GITEA}/AG_QGIS/Projektwissen.git" ws
+          cd ws
+          for r in Plugin_SN_Basis Plugin_SN_Plan41 Plugin_SN_Verfahrensgebiet; do
+            git clone --depth 1 --branch unstable "https://${GITEA}/AG_QGIS/$r.git" "$r"
+          done
+          # Dieses Repo im geprüften Stand einsetzen
+          NAME="${GITHUB_REPOSITORY##*/}"
+          rm -rf "$NAME"
+          git clone "https://${GITEA}/${GITHUB_REPOSITORY}.git" "$NAME"
+          cd "$NAME" && git checkout "${GITHUB_SHA}" && cd ..
+
+      - name: Tests mit Baseline
+        run: |
+          cd ws
+          NAME="${GITHUB_REPOSITORY##*/}"
+          PAKET=$(python3 - "$NAME" <<'PY'
+          import sys, tomllib
+          m = tomllib.load(open("workspace.toml", "rb"))
+          print(next(r["paket"] for r in m["repos"] if r["name"] == sys.argv[1]))
+          PY
+          )
+          python3 scripts/run_tests.py "$PAKET" --baseline

docs/vorlagen/issue.md

@@ -0,0 +1,19 @@
+## Ziel
+<Was soll am Ende möglich sein? Ein Satz aus Nutzersicht.>
+
+## Betroffen
+Plugin: sn_basis | sn_verfahrensgebiet | sn_plan41 | sn_widmung
+Module/Dateien (falls bekannt):
+Berührt Schnittstellen (`docs/architektur/schnittstellen.md`)? nein | ja: <welche>
+
+## Fachlicher Hintergrund
+<Begriffe, Regeln, Beispieldaten (keine echten Verfahrensdaten). Verweise auf Glossar.>
+
+## Abnahmekriterien
+- [ ] <beobachtbares Verhalten 1>
+- [ ] <beobachtbares Verhalten 2>
+- [ ] Mock-Test vorhanden, `run_tests.py --baseline` ohne NEU ROT
+- [ ] QGIS-Test: <nötig / nicht nötig>
+
+## Nicht Teil dieses Issues
+<Abgrenzung, damit der Agent nicht abschweift.>

docs/vorlagen/pull_request.md

@@ -0,0 +1,18 @@
+## Was
+<Zwei Sätze. Issue: #…>
+
+## Wie geprüft
+- `python scripts/run_tests.py <paket> --baseline`: <Ergebniszeile>
+- QGIS-Test: <QGIS-Version, Ablauf, Ergebnis> | nicht nötig, weil …
+
+## Änderungen an Verträgen
+keine | <welche, mit Verweis auf Issue und `schnittstellen.md`-Anpassung>
+
+## Übergabenotiz
+<nach docs/vorlagen/uebergabe.md>
+
+## Checkliste
+- [ ] Nur Änderungen zum Issue
+- [ ] Keine direkten Qt/QGIS-Importe, keine Debug-`print`
+- [ ] `changelog.txt` ergänzt
+- [ ] Wissensbasis nachgezogen (oder „nichts Neues“)

docs/vorlagen/testkonzept.md

@@ -0,0 +1,65 @@
+<!--
+Vorlage für eine Testkonzept-Seite unter docs/tests/<ablauf>.md.
+Zweck: Eine Fachperson soll ohne Blick in den Quelltext beurteilen können, ob die Tests
+fachlich das Richtige prüfen. Deshalb: fachliche Sprache, keine Klassennamen im Diagramm.
+Erläuterung: docs/leitfaden/06_tests.md Abschnitt 7.
+Diesen Kommentar beim Ausfüllen entfernen.
+-->
+
+# Testkonzept: <Name des fachlichen Ablaufs>
+
+Plugin: `sn_<paket>` · Stand: <TT.MM.JJJJ> · Pflege: bei jeder Änderung an diesem Ablauf
+
+## Worum es fachlich geht
+
+<Zwei bis vier Sätze aus Sicht der Sachbearbeitung: Was macht der Anwender, was soll dabei herauskommen,
+warum ist das wichtig. Keine Dateinamen, keine Funktionsnamen.>
+
+## Der Ablauf
+
+```mermaid
+flowchart TD
+    A["1 <Was der Anwender tut>"] --> B["2 <Was das Plugin daraufhin tut>"]
+    B --> C{"<Fachliche Entscheidung>"}
+    C -->|"<Fall a>"| D["3a <Ergebnis>"]
+    C -->|"<Fall b>"| E["3b <Ergebnis>"]
+    D --> F["4 <Endzustand>"]
+    E --> F
+```
+
+## Was geprüft wird
+
+| # | Schritt | Wird geprüft durch | Ebene |
+|---|---|---|---|
+| 1 | <Schritt aus dem Diagramm> | `test_<name>` in `tests/test_<modul>.py` | Mock |
+| 2 | <Schritt> | `test_<name>` | Mock |
+| 3a | <Fall a> | `test_<name>` | Mock |
+| 3b | <Fall b> | — | — |
+| 4 | <Endzustand> | manueller Test in QGIS | manuell |
+
+Ebene: `Mock` (ohne QGIS, Sekunden) · `QGIS` (gegen echtes QGIS) · `manuell` (Mensch in QGIS).
+Erläuterung der Ebenen: `docs/leitfaden/06_tests.md` Abschnitt 2.
+
+## Fachliche Sonderfälle
+
+Die Fälle, die in der Praxis wirklich vorkommen — hier entscheidet sich, ob die Suite etwas taugt.
+
+| Sonderfall | Kommt vor bei | Wird geprüft durch |
+|---|---|---|
+| <z. B. leerer Export> | <Situation in der Praxis> | `test_<name>` |
+| <z. B. abweichender Feldname> | <Situation> | `test_<name>` |
+| <z. B. Datensatz aus dem Nachbarlandkreis> | <Situation> | — |
+
+## Bewusst nicht getestet
+
+| Was | Warum | Wie stattdessen abgesichert |
+|---|---|---|
+| <Aspekt> | <nachvollziehbarer Grund — „zu aufwendig" ist keiner> | <manueller Test, Review, anderer Test> |
+
+## Bekannte Lücken
+
+| Lücke | Auswirkung | Issue |
+|---|---|---|
+| <Was fehlt> | <Was im schlimmsten Fall unbemerkt bleibt> | #<nr> |
+
+<Keine Lücken bekannt? Dann hier „Derzeit keine bekannten Lücken." und das Datum der letzten Durchsicht.>

docs/vorlagen/uebergabe.md

@@ -0,0 +1,10 @@
+## Übergabenotiz
+
+**Aufgabe:** <Issue-Link und Ziel in einem Satz>
+**Stand:** fertig | in Arbeit | blockiert – <wo genau>
+**Geändert:** <Dateien mit Kurzgrund, keine Diffs>
+**Nachweis:** `run_tests.py <paket> --baseline`: <Ergebniszeile>; QGIS-Test: <was, womit, Ergebnis | nicht nötig, weil …>
+**Entscheidungen/Annahmen:** <fachliche Annahmen, die jemand bestätigen sollte>
+**Offen / nächste Schritte:** <konkret, in Reihenfolge>
+**Wissensbasis:** <Einträge in fallstricke/schnittstellen/modulkarte/STATUS | „nichts Neues“>
+**Kontext für die nächste Sitzung:** <die zwei bis drei Dateien/Abschnitte, mit denen es weitergeht>