@@ -47,36 +47,60 @@ write_hooks() → UvPyprojectUpdater.write()
 
 ### 1. Filter-/Transform-Funktion (rein, testbar)
 
-`_constraints_to_uv(constraints: list[str]) -> list[str]` im uv-Modul:
-
-1. Über jede Zeile aus `state.constraints` iterieren.
-2. Überspringen: Leerzeilen, `####`-Trennlinien, alle mit `#` beginnenden Kommentarzeilen
-   (das schließt die `# begin/end constraints from ...`-Header **und** die
-   `# <pkg> -> mxdev disabled (...)`-Zeilen ein). Dadurch fallen aus-Source-entwickelte und
-   per Override ersetzte Pakete automatisch raus — korrekt, da diese über `[tool.uv.sources]`
-   bzw. `override-dependencies` kommen.
-3. Verbleibende Zeilen mit `packaging.requirements.Requirement` parsen. Nicht-parsebare
-   Zeilen (z.B. `--hash`, `--index-url`, `-e ...`) verwerfen und auf DEBUG loggen.
-4. **Kein Dedupe, keine Konfliktauflösung** — konsistent mit dem klassischen Pfad
+Leitidee: Das `constraint-dependencies`-Array wird ein **TOML-Spiegel von
+`constraints-mxdev.txt`** — gleiche **Quell-Reihenfolge**, Herkunfts-Kommentare erhalten.
+Specifier-Zeilen werden zu Array-Einträgen, Kommentarzeilen zu Array-internen Kommentaren.
+
+`_constraints_to_uv(constraints: list[str]) -> list[ConstraintItem]` im uv-Modul, wobei
+`ConstraintItem` ein kleines, geordnetes Element ist, das **entweder** einen Kommentar
+**oder** einen Specifier trägt (z.B. `("comment", text)` / `("entry", specifier)`). So bleibt
+die Funktion rein und testbar und der Writer kann Kommentare + Einträge in Reihenfolge
+emittieren.
+
+Pro Zeile aus `state.constraints`, in Original-Reihenfolge:
+
+1. **Specifier-Zeilen** mit `packaging.requirements.Requirement` parsen → als `entry`
+   übernehmen. Environment-Markers (`; python_version >= "3.9"`) bleiben erhalten.
+   Nicht-parsebare „Zeilen, die wie Specifier aussehen" (z.B. `--hash`, `--index-url`,
+   `-e ...`) verwerfen und auf DEBUG loggen.
+2. **Herkunfts-Kommentare** (`# begin constraints from: <url>` / `# end constraints from: <url>`)
+   als `comment` erhalten — sie liefern die Nachvollziehbarkeit, die der txt-Pfad bietet.
+3. **`# <pkg> -> mxdev disabled (...)`-Zeilen** als `comment` erhalten (1:1 wie in
+   `constraints-mxdev.txt`). Sie dokumentieren, *warum* ein Pin hier fehlt (das Paket kommt
+   über `[tool.uv.sources]` bzw. `override-dependencies`). → **Auf Review verifizieren**, ob
+   gewünscht; Alternative wäre, sie wegzulassen.
+4. **Dekorative `####…`-Trennlinien und Leerzeilen** verwerfen (reines visuelles Rauschen;
+   die begin/end-Header liefern die Gruppierung).
+5. **Kein Dedupe, keine Konfliktauflösung** — konsistent mit dem klassischen Pfad
    (`constraints-mxdev.txt` ist reiner Passthrough; pip/uv behandelt Konflikte). Konfligierende
    Versionen desselben Pakets bleiben beide erhalten.
-5. **Alphabetisch sortieren**, case-insensitive nach Paketname (diff-freundlich).
-   Environment-Markers (`; python_version >= "3.9"`) bleiben am Specifier erhalten.
-6. Rückgabe: Liste sortierter Specifier-Strings.
+6. **Keine Sortierung** — Quell-Reihenfolge wird beibehalten (Gruppen-Kohärenz vor
+   Diff-Minimierung).
 
 ### 2. Schreiben nach pyproject.toml
 
 Erweiterung von `_update_pyproject` in [src/mxdev/uv.py](../../../src/mxdev/uv.py):
 
 - Ziel: `[tool.uv] constraint-dependencies` als multiline-Array (analog zum bestehenden
-  `override-dependencies`-Block, `uv.py:152-156`).
+  `override-dependencies`-Block, `uv.py:152-156`), aber mit **Array-internen Kommentaren**
+  in Quell-Reihenfolge.
 - **Ersetzen + Marker:** Das Array wird vollständig von mxdev verwaltet und bei jedem Lauf
-  überschrieben. Kennzeichnung „managed by mxdev“ — bevorzugt als Array-interner Kommentar
-  via tomlkit; falls tomlkit das nicht stabil serialisiert, als Kommentarzeile direkt über
-  dem Array (`# managed by mxdev — do not edit`). **Im Plan zu verifizieren.**
+  überschrieben. Eine `# managed by mxdev — do not edit`-Kommentarzeile als erstes Element.
 - Leeres Filterergebnis → Key nicht schreiben; ein bestehender, mxdev-verwalteter Key wird in
   dem Fall geleert/entfernt, damit kein veralteter Stand stehen bleibt.
 
+### ⚠️ Technisches Hauptrisiko: tomlkit & Array-interne Kommentare
+
+Array-interne Kommentare über viele Zeilen sind die heikelste tomlkit-Stelle. **Früh im Plan
+verifizieren** (kleiner Spike), dass tomlkit interspersed comments in einem multiline-Array
+korrekt **und idempotent** serialisiert (zweiter Lauf = byte-identisch).
+
+Falls tomlkit das nicht sauber round-trippt, **Fallback** (Reihenfolge bleibt erhalten):
+Herkunft als **Inline-Kommentar pro Eintrag** statt als eigene Kommentarzeile, z.B.
+`"Zope==6.0",  # from <url>`. Das unterstützt tomlkit zuverlässig. Die begin/end-Blockheader
+werden dann zu einem Inline-`# from <url>`-Suffix pro Eintrag verdichtet; die disabled-Marker
+entfallen in diesem Fallback.
+
 ### 3. Opt-out
 
 - Default **an**, sobald `[tool.uv] managed = true` (konsistent mit `sources`/`override-dependencies`).
@@ -96,9 +120,11 @@ Erweiterung von `_update_pyproject` in [src/mxdev/uv.py](../../../src/mxdev/uv.p
 ## Tests (TDD)
 
 Reine Funktion `_constraints_to_uv`:
-- Kommentare, `####`-Trenner, `# ... -> mxdev disabled`-Zeilen werden gefiltert.
+- Specifier-Zeilen → `entry`, in **Quell-Reihenfolge** (keine Sortierung).
+- `# begin/end constraints from`-Header → als `comment` erhalten.
+- `# ... -> mxdev disabled`-Zeilen → als `comment` erhalten.
+- `####`-Trenner und Leerzeilen werden verworfen.
 - Nicht-parsebare Zeilen (`--hash`, `-e`, `--index-url`) werden verworfen.
-- Alphabetische Sortierung (case-insensitive).
 - Environment-Markers bleiben erhalten.
 - Konfligierende/doppelte Versionen bleiben beide erhalten (Passthrough).
 
@@ -107,12 +133,13 @@ Hook-Integration:
 - `managed=false`/fehlend → nicht geschrieben.
 - Opt-out-Setting `uv-constraint-dependencies = false` greift.
 - Bestehendes Array wird ersetzt (nicht gemerged).
-- Idempotenz: zweiter Lauf erzeugt identisches Ergebnis.
+- Herkunfts-Kommentare landen in Quell-Reihenfolge im Array.
+- Idempotenz: zweiter Lauf erzeugt **byte-identisches** Ergebnis (deckt das tomlkit-Risiko ab).
 - Leeres Ergebnis → kein/leerer Key.
 
 Ende-zu-Ende:
-- `-c URL`-Kette via httpretty-Fixture (wie in bestehenden Tests) → korrekt aufgelöste,
-  sortierte `constraint-dependencies`.
+- `-c URL`-Kette via httpretty-Fixture (wie in bestehenden Tests) → korrekt aufgelöste
+  `constraint-dependencies` in Quell-Reihenfolge mit Herkunfts-Kommentaren.
 
 ## Bewusst ausgeklammert (YAGNI)
 
@@ -121,3 +148,4 @@ Ende-zu-Ende:
 - Keine separate `uv-constraints = URL`-Konfiguration (die bestehende `requirements-in`-Kette
   ist die einzige Quelle der Wahrheit).
 - Keine Konflikt-/Dedupe-Logik (Konsistenz mit dem klassischen Pfad).
+- Keine alphabetische Sortierung (Quell-Reihenfolge + Gruppen-Header gewählt).