Sudoku/ROADMAP.md

# Entwicklungsfahrplan

Dieser Fahrplan führt das Projekt vom aktuellen Prototyp zu einem verlässlichen,
erklärbaren Sudoku-Löser. Die Reihenfolge ist absichtlich abhängigkeitsorientiert:
Neue Strategien bauen erst dann auf dem Solver auf, wenn Feldmodell, Änderungen
und Fortschrittserkennung korrekt und getestet sind.

## Zielbild

Das erste stabile Release soll:

- klassische 9x9-Sudokus sicher einlesen und validieren,
- jeden Lösungsschritt deterministisch und nachvollziehbar protokollieren,
- einfache und mittlere Rätsel mit menschlichen Strategien lösen,
- bei Stillstand einen klaren Status statt eines Panic oder Endloslaufs liefern,
- über eine kleine CLI mit Datei, Standard-Eingabe oder direkter Rätselzeichenfolge
  nutzbar sein und
- durch Unit-, Integrations- und Regressionstests abgesichert sein.

Backtracking, DLX und sehr fortgeschrittene menschliche Strategien folgen auf
dieses Kern-Release.

## Phase 0 – Lauffähige und getestete Basis (P0)

Zuerst wird der bestehende Zustand stabilisiert. In dieser Phase werden keine
neuen Lösungsstrategien ergänzt.

- Test-Helfer für kleine Felder und 9x9-Rätsel anlegen.
- Regressionstests für die aktuell bekannten Abstürze und Logikfehler schreiben.
- `Field.ForEachCell` so korrigieren, dass echte Zellen statt Kopien übergeben
  werden.
- `Field.GetCell` gegen negative Indizes und `row == Rows` beziehungsweise
  `column == Columns` absichern.
- die Zahlenausgabe in `Field.String` ohne fehlerhafte int-zu-string-Konvertierung
  implementieren.
- doppelte oder widersprüchliche Änderungen aus überlappenden Zeilen, Spalten
  und Blöcken verhindern; damit auch den Nil-Panic in `LastDigit` beseitigen.
- die beiden Slice-Iterationsfehler in `HiddenSingle` korrigieren: Kandidatenwerte
  statt Indizes auswerten.
- in `Cell.RemoveNumber` die korrekte Aktion `ActionRemoveNumber` protokollieren.
- Nil-Eingaben bei Feld, Zelle, Position und Änderung kontrolliert als Fehler
  behandeln.
- Solver-Fortschritt so erkennen, dass ein Schritt weder fälschlich Stillstand
  meldet noch endlos wiederholt wird.

Abgeschlossen, wenn:

- `go test ./...` und `go vet ./...` erfolgreich sind,
- `go run .` das ausgewählte Beispiel ohne Panic beendet und
- die bekannten Fehler jeweils einen Regressionstest besitzen.

## Phase 1 – Verlässliches Feldmodell (P0)

- `field.Properties` beim Erzeugen prüfen: positive Dimensionen, passende
  Blockaufteilung und exakt passende Zellmatrix.
- Zahlenbereich und Position jeder Zelle prüfen; leere Zellen bleiben als `0`
  repräsentiert.
- `Part.IsSolved` für Zeilen, Spalten und Blöcke implementieren.
- `Field.IsValid` implementieren: keine Duplikate, nur erlaubte Werte und
  konsistente Dimensionen.
- `Field.IsSolved` an Vollständigkeit **und** Validität koppeln.
- Kandidaten-Invarianten festlegen: sortiert, eindeutig, im gültigen Bereich und
  niemals an bereits belegten Zellen.
- Änderungen atomar anwenden und validieren. Ungültige Änderungen sollen einen
  Fehler zurückgeben und das Feld unverändert lassen.
- lesenden Zugriff auf Eigenschaften und Änderungshistorie anbieten, ohne
  interne Slices veränderbar nach außen zu geben.
- allgemeine und 9x9-spezifische Darstellung trennen; `StringNotesForNumber`
  implementieren oder bis zu einem echten Bedarf aus der API entfernen.

Abgeschlossen, wenn gültige, ungültige, unvollständige und gelöste Felder in
Tabellentests eindeutig unterschieden werden und keine Mutation die
Feld-Invarianten umgehen kann.

## Phase 2 – Robuste Parser- und Game-API (P0)

- Parserfehler vereinheitlichen und mit Zeilennummer sowie fehlerhaftem Feld
  anreichern.
- Puzzle-Bank-Datensätze strikt prüfen: Hash, 81 Ziffern, Rating, Whitespace,
  LF/CRLF und leere Zeilen.
- bei einem Parse-Fehler keine teilweise eingelesene Ergebnisliste übernehmen;
  wiederholte `Parse`-Aufrufe dürfen alte Ergebnisse nicht ungewollt anhängen.
- `GetField` so ändern, dass ein ungültiger Index einen Fehler liefert statt
  eines leeren, später abstürzenden Felds.
- die fest kodierte Auswahl `GetField(2)` aus `sudoku.New` entfernen. Das
  ausgewählte Feld soll explizit übergeben oder vom Aufrufer gewählt werden.
- zusätzlich einen einfachen Parser für eine 81-stellige Rätselzeichenfolge
  bereitstellen; er eignet sich für CLI, Tests und externe Nutzung.
- die Ausgangsbelegung bereits beim Erzeugen eines `Game` validieren.

Abgeschlossen, wenn fehlerhafte Eingaben ohne Panic verständliche Fehler liefern
und Parser sowie `Game` keine implizite Rätselauswahl mehr enthalten.

## Phase 3 – Klare Solver-Architektur (P0/P1)

- ein Solver-Interface definieren, das später menschlichen Solver, Backtracking
  und DLX austauschbar macht.
- `Run(int) bool` durch eine aussagekräftige Schritt-API ersetzen, zum Beispiel
  mit den Zuständen `Progress`, `Solved`, `Stuck`, `Invalid` und `Failed`.
- Konfiguration aus den ungenutzten `conf`-Feldern ableiten oder diese entfernen.
- Strategie-Reihenfolge, Wiederholungspunkt und `ApplyNext`/`ApplyAll` eindeutig
  definieren.
- gefundene Änderungen vor dem Anwenden deduplizieren und auf Konflikte prüfen.
- Kandidaten nach jedem Zahlenschritt korrekt und deterministisch aktualisieren.
- Tippfehler in öffentlichen Namen (`InitStragies`, `TriggerdBy`) kontrolliert
  migrieren und alle Aufrufer anpassen.
- Abbruch bei Stillstand, ungültigem Zustand und internem Fehler sauber durch
  `sudoku.Game.Solve` reichen.

Abgeschlossen, wenn derselbe Input stets dieselben Schritte erzeugt und jeder
Solverlauf genau einen überprüfbaren Endzustand besitzt.

## Phase 4 – Menschlicher Basis-Solver (P1)

Die Strategien werden in aufsteigender Komplexität implementiert. Jede Strategie
benötigt positive, negative und Konflikt-/Überlappungstests sowie mindestens ein
komplettes Beispielrätsel.

1. Kandidaten erzeugen und pflegen (`Notes`)
2. `LastDigit`
3. `NakedSingle`
4. `HiddenSingle`
5. `NakedPair` und `NakedTriple`
6. `HiddenPair` und `HiddenTriple`
7. `LockedCandidateT1`, `LockedCandidateT2` und `LockedPair`

Abgeschlossen, wenn die mitgelieferten einfachen und mittleren Beispieldaten
ohne Raten lösbar sind und jeder Schritt seine auslösende Strategie nennt.

## Phase 5 – Erklärbarer Lösungsweg und Undo (P1)

- Änderungen zu fachlichen Schritten gruppieren: eine Schlussfolgerung kann aus
  einer gesetzten Zahl und mehreren entfernten Kandidaten bestehen.
- `GetSolutionPath` mit defensiven Kopien implementieren.
- pro Schritt Strategie, betroffene Zellen, alter/neuer Wert, Begründung und
  optionale Markierungen speichern.
- `Mark` vollständig von außen lesbar und unabhängig von internen
  `Change`-Zeigern gestalten.
- Undo/Redo auf Basis atomarer Schritte implementieren; `prevSolveStep` entweder
  fertigstellen oder bis dahin entfernen.
- menschenlesbare Textausgabe und ein stabiles JSON-Format für Lösungswege
  ergänzen.

Abgeschlossen, wenn ein gelöstes Feld vollständig zum Ausgangszustand
zurückgesetzt und durch Wiederanwenden desselben Pfads identisch rekonstruiert
werden kann.

## Phase 6 – Fortgeschrittene Strategien (P2)

Erst nach stabiler Schritt- und Markierungslogik ergänzen:

1. `XWing`
2. `XYWing`, `XYZWing`, `WXYZWingBasic`
3. `Turbot2StringKite` und `TurbotSkyscraper`
4. `SimpleColoringT1`
5. `EmptyRectangle`
6. `UniqueRectangleT1`, `UniqueRectangleT4`, `UniqueRectangleT7`
7. `XChain`, `XYChain`, `XChainLoop`, `XYChainLoop`
8. `CRP`, nachdem die genaue fachliche Bedeutung und Akzeptanzkriterien
   dokumentiert wurden

Für jede Technik wird zuerst ein isoliertes Testmuster festgelegt. Ein leerer
Typ ohne Verhalten gilt nicht als implementierte Strategie.

## Phase 7 – Vollständige algorithmische Solver (P2)

- Backtracking-Solver mit Minimum-Remaining-Values-Heuristik implementieren.
- optional einen DLX-/Algorithm-X-Solver ergänzen.
- Eindeutigkeit einer Lösung prüfen und die Fälle keine, genau eine oder mehrere
  Lösungen unterscheiden.
- algorithmische Solver als Referenz in Tests verwenden, um Ergebnisse des
  menschlichen Solvers zu validieren.
- explizit konfigurieren, ob ein algorithmischer Solver nur prüft, als Fallback
  dient oder direkt löst.

Abgeschlossen, wenn alle gültigen klassischen 9x9-Rätsel entweder gelöst oder
eindeutig als unlösbar/mehrdeutig klassifiziert werden.

## Phase 8 – Kommandozeile und Bedienbarkeit (P2)

- Flags für Datei, Puzzle-Index, direkte Zeichenfolge und Standard-Eingabe
  hinzufügen.
- Solverart und zugelassene Strategien auswählbar machen.
- Ausgabeoptionen für Ausgangsfeld, Endfeld, Einzelschritte und JSON anbieten.
- konsistente Exit-Codes für Eingabefehler, ungültige Rätsel, Stillstand und
  erfolgreiche Lösung definieren.
- Bibliothekspakete frei von direkter Konsolenausgabe halten; strukturiertes,
  optionales Logging nur an den Anwendungsgrenzen einführen.
- große Puzzle-Bank-Dateien streamen, wenn nur ein Datensatz benötigt wird.

Abgeschlossen, wenn das Programm ohne Quellcodeänderung mit eigenen Rätseln
verwendet werden kann.

## Phase 9 – Qualität, Performance und Release (P2/P3)

- Fuzz-Tests für Parser, Koordinatenzugriffe und Änderungsanwendung ergänzen.
- Integrationssuite über repräsentative einfache, mittlere, schwere, ungültige
  und mehrdeutige Rätsel aufbauen.
- `go test -race ./...` in den Standardprüfungen aufnehmen.
- Benchmarks für Kandidatenberechnung, Strategie-Suche und vollständige Solver
  hinzufügen; erst danach gezielt optimieren.
- CI für Formatierung, Tests, Vet und Race Detector einrichten.
- öffentliche APIs mit GoDoc dokumentieren und Beispiele ergänzen.
- README nach Stabilisierung von den Warnungen befreien, Versionsschema und
  Changelog festlegen und ein erstes Release markieren.

## Empfohlene nächste Arbeitspakete

Diese Tickets bilden die kürzeste Route zu einem stabilen Zwischenstand:

1. Test-Helfer und Feldzugriffs-Tests erstellen.
2. `ForEachCell`, `GetCell` und `Field.String` korrigieren.
3. Change-Aktionen sowie Nil- und Werteprüfung absichern.
4. `LastDigit` deduplizieren und den bekannten Panic per Regressionstest
   beseitigen.
5. `HiddenSingle` korrigieren und vollständig testen.
6. `Part.IsSolved`, `Field.IsValid` und `Field.IsSolved` implementieren.
7. Puzzle-Bank-Parser atomar und indexsicher machen.
8. Solver-Schrittergebnis und Konflikterkennung einführen.
9. die vier Basisstrategien durch End-to-End-Rätseltests absichern.
10. erst danach Paar-/Tripel-Strategien oder neue Bedienfunktionen beginnen.

Nach jedem Arbeitspaket müssen `gofmt`, `go test ./...` und `go vet ./...`
erfolgreich sein. Neue bekannte Baseline-Fehler sollen nicht angesammelt werden.