Harden protocol transfers and config validation

AGENTS.md

@@ -0,0 +1,66 @@
+# Arbeitsanweisungen für Coding-Agents
+
+Diese Datei gilt für das gesamte VersaGUI-Repository.
+
+## Ziel und Nachbar-Repository
+
+VersaGUI ist die Windows-/WinForms-Konfigurationsanwendung für VersaPad v2.
+Sie läuft auf .NET 7 und kommuniziert über feste 8-Byte-CDC-Pakete mit der
+Firmware im benachbarten, eigenständigen Repository `../VersaMCU`.
+
+`DelphiGUI` gehört nicht zum gepflegten Scope und darf bei Änderungen nicht
+als Referenz oder Ziel verwendet werden.
+
+## Vor Änderungen lesen
+
+1. `README.md`
+2. `doc/INDEX.md`
+3. `doc/00_architecture.md`
+4. bei Protokoll-/Layoutänderungen zusätzlich:
+   - `src/Protocol.cs`
+   - `src/DeviceConfig.cs`
+   - `../VersaMCU/AGENTS.md`
+   - `../VersaMCU/doc/06_nvm_config.md`
+   - `../VersaMCU/doc/07_serial_protocol.md`
+
+## Gemeinsame Binärverträge
+
+- `DeviceConfig` muss exakt `SDeviceConfig` entsprechen: Config v3, 740 Byte.
+- `MacroTable` muss exakt `SMacroTable` entsprechen: 512 Byte.
+- Enum-Werte, Packing, Offsets, CRC-Bereich, Chunkgrößen und USB-IDs sind
+  gemeinsame Verträge mit VersaMCU.
+- Änderungen daran in beiden Repositories implementieren, dokumentieren,
+  bauen und getrennt committen.
+- Host-Command-IDs niemals ungeprüft als Shellkommando ausführen. Eine spätere
+  Host-Aktionsfunktion benötigt ein explizites sicheres Mapping.
+
+## Threading und Transfers
+
+- WinForms-Controls ausschließlich auf dem UI-Thread anfassen.
+- `SerialManager.ReadLoop()` läuft im Hintergrund und postet Events über den
+  `SynchronizationContext`.
+- SerialPort-Pakete müssen unter dem Write-Lock vollständig geschrieben werden.
+- Config-/Makrotransfers nicht parallel ausführen.
+- Dumps und Uploads nur akzeptieren, wenn Chunkzahl, Indizes und
+  Vollständigkeit stimmen.
+- DTR muss vor `SerialPort.Open()` aktiviert sein.
+
+## Verifikation
+
+Mindestens:
+
+```bash
+dotnet build src/VersaGUI.csproj --no-restore
+dotnet run --project tests/VersaGUI.ContractTests/VersaGUI.ContractTests.csproj
+git diff --check
+```
+
+Bei gemeinsamen Vertragsänderungen zusätzlich:
+
+```bash
+pio run -d ../VersaMCU -e versapad
+```
+
+Die Contract-Tests prüfen Config-/Makrogrößen, CRC, Feldvalidierung,
+Chunkvollständigkeit und Host-Command-Payloads. Sie ersetzen keinen Test mit
+angeschlossenem Board.