# Arbeitsregeln für MapTools Converter

Diese Datei gilt für das gesamte Repository. Ein Arbeitsblock ist erst abgeschlossen, wenn die nachfolgenden Release- und Sicherheitsnachweise vollständig erzeugt wurden.

## Versionierung und Changelog

- Verwende Semantic Versioning (`MAJOR.MINOR.PATCH`). Die kanonische Version steht in `application/gradle.properties` unter `maptoolsVersion`.
- Erhöhe die Version bei jedem abgeschlossenen Arbeitsblock, der Programmcode, Abhängigkeiten, Build, Paketierung, Sicherheit oder auslieferungsrelevante Dokumentation verändert.
- Pflege jede nachvollziehbare Änderung zuerst in `CHANGELOG.md` unter `Unreleased`. Vor dem Paketieren wird der Eintrag mit Datum unter die neue Version verschoben.
- Verwende mindestens die Kategorien `Added`, `Changed`, `Fixed`, `Security` und `Removed`, soweit sie für die Version zutreffen.
- Überschreibe keine bereits veröffentlichte Version. Release-Ausgaben liegen immer unter `release/<Version>/`.

## Pflichtprüfung am Ende eines Arbeitsblocks

1. Tests und distributable Builds ausführen.
2. Stabile Aktualisierungen für Gradle, Kotlin, Compose, Bibliotheken, Plugins, JDK und IDE anhand der offiziellen Quellen prüfen.
3. Entscheidungen in `security/dependency-review/` dokumentieren. Nicht blind aktualisieren: Kompatibilitätsrisiko, Herkunft, Prüftag und Begründung festhalten.
4. Für Windows x64, Linux x64 und den Quelltext versionierte Pakete erzeugen.
5. Für beide Binärplattformen eine CycloneDX-JSON-SBOM erzeugen und mit OSV-Scanner auf bekannte Schwachstellen prüfen.
6. Release-Manifest und SHA-256-Prüfsummen erzeugen.
7. Erst dann den Arbeitsblock als abgeschlossen melden.

Der vollständige lokale Ablauf unter Windows lautet:

```powershell
./scripts/release-all.ps1
```

Er muss mindestens diese Ausgaben erzeugen:

```text
release/<Version>/
  windows/ArxSilex-MapTools-Converter-<Version>-windows-x64.zip
  linux/ArxSilex-MapTools-Converter-<Version>-linux-x64.tar.gz
  source/ArxSilex-MapTools-Converter-<Version>-src.zip
  security/*.cdx.json
  security/*-osv.json
  security/dependency-updates.json
  security/toolchain.json
  CHANGELOG.md
  release-manifest.json
  SHA256SUMS.txt
```

Wenn Windows, Linux, Quellpaket, Tests, SBOM, CVE-Prüfung oder Prüfsummen fehlen, darf die Arbeit nicht als fertig bezeichnet werden. Ein technischer Blocker ist mit fehlendem Artefakt und reproduzierbarem Fehler zu nennen.

## SBOM- und Schwachstellenregeln

- Verwende CycloneDX JSON in einer verbreiteten, maschinenlesbaren Schema-Version. Die SBOM muss direkte und transitive Laufzeitkomponenten enthalten.
- Lokal eingebundene Binärdateien und die Laufzeit-/Build-Werkzeuge müssen zusätzlich über Hashes beziehungsweise `toolchain.json` nachvollziehbar sein, wenn der Gradle-Generator sie nicht als Komponente erkennt.
- Lege die SBOM neben den zugehörigen Release-Artefakten ab. Bewahre die prüfbaren Arbeitsnachweise unter `security/reports/<Version>/` auf; diese generierten Reports werden nicht in das Quellarchiv aufgenommen.
- Der OSV-Scan ist ein Release-Gate. Bekannte ungeklärte Schwachstellen blockieren den Abschluss.
- Eine Ausnahme benötigt CVE/OSV-ID, betroffene Version und Plattform, Ausnutzbarkeitsanalyse, Gegenmaßnahme, verantwortliche Person, Ablaufdatum und erneute Prüfung. Die leere Vorgabe ist `security/vulnerability-exceptions.json`.
- Geheimnisse, personenbezogene Daten und lokale absolute Pfade gehören weder in SBOM noch in Reports.

## Portabilität

- Gradle-, Kotlin-, Scanner-, Build- und Download-Caches müssen innerhalb des Repositorys oder des Verzeichnisses der ausführbaren Anwendung liegen. Es dürfen keine zusätzlichen MapTools-Dateien in Benutzerprofil, AppData oder systemweiten Verzeichnissen angelegt werden.
- Externe Ausgabeorte sind nur zulässig, wenn der Benutzer sie ausdrücklich gewählt hat.
- Die Release-Skripte dürfen nur projektlokale temporäre Dateien verwenden und müssen sie nach erfolgreichem oder abgebrochenem Lauf entfernen.

## WSL-2 und sichtbare Linux-Arbeit

- Auf diesem Windows-PC ist die WSL-2-Distribution `kali-linux` registriert. Für sämtliche WSL- und Linux-Arbeit darf ausschließlich der Benutzer `codex-dev` verwendet werden. Verwende niemals stillschweigend oder nach einer Besitzerauswertung einen anderen Linux-Benutzer.
- Führe Linux-Befehle grundsätzlich in dieser Form aus:

  ```powershell
  wsl.exe -d kali-linux -u codex-dev -- bash -lc "<Befehl>"
  ```

- Installiere keine neue WSL-Distribution und verwende nicht `bash.exe` ohne explizite Distribution.
- Codex kann unter Windows als isolierter Benutzer `STICHPC\CodexSandboxOffline` laufen, der die benutzergebundene WSL-Registrierung nicht sieht. Falls `WSL_E_DISTRO_NOT_FOUND` erscheint, wiederhole exakt denselben WSL-Aufruf nach einer Ausführungsfreigabe außerhalb der Windows-Sandbox. Frage den Benutzer nach dieser Freigabe, wenn sie erforderlich ist.
- Das Windows-Laufwerk `D:\` ist in WSL unter `/mnt/d/` eingebunden.
- Prüfe vor Gradle-/Compose-Paketierungen mit `test -r`, `test -w` und `test -x`, ob `codex-dev` die benötigten Rechte auf `/mnt/d/Programmieren/Android/newProjects/MapTools-Converter/Linux` besitzt. Fehlende Rechte sind dem Benutzer vor jedem Änderungs- oder Paketierungsversuch zu melden; frage nach Freigabe beziehungsweise einer durch den Benutzer vorgenommenen Rechtekorrektur.
- Der Besitzer der DrvFS-Einbindung ist keine Erlaubnis, diesen Besitzer als Buildbenutzer zu verwenden. `MAPTOOLS_WSL_USER` und `MAPTOOLS_WSL_BUILD_USER` dürfen, sofern gesetzt, ausschließlich `codex-dev` enthalten.
- Verwende weder `sudo` noch einen anderen Benutzer als Umgehung. Speichere, erfrage oder protokolliere niemals ein Passwort. Falls Rechte fehlen, muss der Benutzer sie selbst vergeben.
- Falls `codex-dev` nicht existiert, melde dies und verwende keinen anderen Linux-Benutzer.
- Prüfe den Zugang zuerst mit:

  ```powershell
  wsl.exe -d kali-linux -u codex-dev -- bash -lc 'id; uname -a; printf "Distro=%s\n" "$WSL_DISTRO_NAME"; pwd'
  ```

- Wenn der Benutzer die Eingaben live verfolgen möchte, verwende die tmux-Sitzung `codex-live`. Prüfe sie mit:

  ```powershell
  wsl.exe -d kali-linux -u codex-dev -- tmux has-session -t codex-live
  ```

- Falls die Sitzung fehlt, erstelle sie im Linux-Arbeitsverzeichnis:

  ```powershell
  wsl.exe -d kali-linux -u codex-dev -- tmux new-session -d -s codex-live -c /mnt/d/Programmieren/Android/newProjects/MapTools-Converter/Linux
  ```

- Eine sichtbare Sitzung öffnet der Benutzer mit:

  ```powershell
  wsl.exe -d kali-linux -u codex-dev -- tmux attach-session -t codex-live
  ```

- Sende sichtbar auszuführende Befehle mit:

  ```powershell
  wsl.exe -d kali-linux -u codex-dev -- tmux send-keys -t codex-live '<Befehl>' Enter
  ```

## CRA-Nachweise

Die Struktur unter `security/` unterstützt technische Nachweise für den EU Cyber Resilience Act. Sie ersetzt weder eine rechtliche Bewertung noch die vollständige Konformitätsbewertung. Release-Checkliste, Schwachstellenprozess, SBOM, Prüfberichte und Ausnahmeentscheidungen sind gemeinsam aufzubewahren.
