drift-dependency-update

name	drift-dependency-update
description	Dependency-Update-Workflow für das Drift-Repo. Verwenden bei: uv.lock aktualisieren, pyproject.toml Abhängigkeit hinzufügen/upgraden/entfernen, Lockfile synchronisieren, Typecheck und Tests gegen neue Version, Commit mit korrektem chore:-Typ. Keywords: uv lock, uv sync, uv add, dependency, pyproject.toml, lockfile, uv.lock, upgrade, security patch, chore commit.
argument-hint	Name und Version der zu ändernden Abhängigkeit — z.B. 'pydantic auf >=2.7 upgraden' oder 'tree-sitter-typescript neu hinzufügen'

Drift Dependency Update

Workflow für alle Änderungen an pyproject.toml-Abhängigkeiten im Drift-Repo. Deckt: neue Abhängigkeit hinzufügen, bestehende upgraden/einschränken, Abhängigkeit entfernen.

KRITISCH: pyproject.toml und uv.lock sind unlösbar gekoppelt. Beide Dateien müssen im selben Commit landen. Das Pre-Push-Gate 5 blockiert jeden Push, bei dem pyproject.toml geändert, uv.lock aber nicht committet wurde.

---

Wann verwenden

• pyproject.toml-Abhängigkeit soll geändert, hinzugefügt oder entfernt werden
• uv.lock soll mit aktuellen Constraints synchronisiert werden
• Security-Patch für eine direkte oder transitive Abhängigkeit
• CI schlägt fehl mit „Lockfile not synchronized" oder ähnlichem

---

Technischer Kontext

Dependency-Gruppen in [project.optional-dependencies]:

Gruppe	Zweck
typescript	tree-sitter, tree-sitter-typescript
embeddings	sentence-transformers, faiss-cpu, numpy
markdown	mistune
mcp	mcp[cli]
watch	watchfiles
dev	Alle Test- / Lint- / Release-Werkzeuge
all	Metagruppe, die alle einschließt

Lokale Venv-Aktivierung (Windows):

.\.venv\Scripts\Activate.ps1

Wichtige uv-Befehle:

Aufgabe	Befehl
Neue Abhängigkeit hinzufügen (schreibt auch pyproject.toml)	uv add <paket>
Abhängigkeit in optionale Gruppe hinzufügen	uv add --optional <gruppe> <paket>
Abhängigkeit entfernen	uv remove <paket>
Lockfile neu erzeugen (nach manuellem pyproject.toml-Edit)	uv lock
Einzelnes Paket im Lock upgraden	uv lock --upgrade-package <paket>
Alle Transitivs upgraden (innerhalb Constraints)	uv lock --upgrade
Devenv installieren/aktualisieren	uv sync --all-extras

---

Schritt-für-Schritt-Workflow

Schritt 0 — Policy Gate

### Drift Policy Gate
- Trivialtask: JA
- Zulässig: JA → rein mechanisch, ohne Verhaltens-, Policy-, Architektur- oder Signaleffekt

Dependency-Updates sind chore:-Commits. Sie lösen kein feat:/fix:-Gate aus und erfordern kein CHANGELOG-Update. Ausnahme: Ein Upgrade behebt einen produktiven Bug → dann fix:.

Schritt 1 — Abhängigkeit klassifizieren

Vor der Änderung klären:

• Nur pyproject.toml (Versions-Constraint ändern): direkt editieren → dann uv lock.
• Neue Abhängigkeit hinzufügen: uv add <paket> bevorzugen — schreibt pyproject.toml und uv.lock atomar.
• Security-Patch für transitive Abhängigkeit (nicht in pyproject.toml): uv lock --upgrade-package <paket> + kein pyproject.toml-Edit nötig.
• Abhängigkeit entfernen: uv remove <paket>.

Schritt 2 — Lockfile synchronisieren

Nach jedem manuellen Edit von pyproject.toml:

uv lock

Prüfen, ob keine Konflikte ausgegeben werden. Bei Konflikten Constraint in pyproject.toml anpassen und erneut ausführen.

Schritt 3 — Devenv aktualisieren

uv sync --all-extras

Stellt sicher, dass das lokale Venv die neuen Versionen enthält, bevor Tests laufen.

Schritt 4 — Typecheck

.\.venv\Scripts\python.exe -m mypy src/drift --ignore-missing-imports

Schlägt der Typecheck durch inkompatible API-Änderungen fehl, Constraint in pyproject.toml einschränken oder Typ-Fehler beheben.

Schritt 5 — Quick-Tests

.\.venv\Scripts\python.exe -m pytest tests/ --ignore=tests/test_smoke_real_repos.py -m "not slow" -q -n auto --dist=loadscope

Bei Testfehlern durch API-Änderungen der aktualisierten Bibliothek:

1. Prüfen, ob es einen Workaround im Drift-Code gibt.
2. Constraint ggf. zurücksetzen (<neue_version).
3. Issue gegen die Bibliothek vorbereiten, falls es ein echter Bug ist.

Schritt 6 — Beide Artefakte committen

PFLICHT: pyproject.toml und uv.lock immer gemeinsam in einem Commit.

git add pyproject.toml uv.lock
git status --short   # Sicherheitscheck: keine unerwünschten Dateien
git commit -m "chore: update <paket> to <version>"

Commit-Typ-Regeln:

Situation	Commit-Typ
Routine-Upgrade, kein Bug-Fix	chore:
Upgrade behebt produktiven Drift-Bug	fix:
Neue optionale Funktionalität ermöglicht	feat:
Breaking change in Abhängigkeit, Drift-API bricht	BREAKING:

Schritt 7 — Pre-Push-Gate-Check (vor dem Push)

Gate 4 (Version Bump) feuert, wenn pyproject.toml geändert wurde:

• PSR bumpt die Version nicht für chore:-Commits → Gate würde blockieren.
• Lösung für chore:-nur-Dependency-Pushes:

DRIFT_SKIP_VERSION_BUMP=1 git push

Bei fix: oder feat:-Commits ist kein Bypass nötig — PSR erstellt einen Version-Bump-Commit in CI.

---

Häufige Fehler (und Korrekturen)

Fehler	Korrekte Vorgehensweise
pip install <paket> anstatt uv add	Immer uv add oder uv sync — pip umgeht den Lock
Nur pyproject.toml committen, uv.lock vergessen	git add pyproject.toml uv.lock immer zusammen
uv lock vergessen nach manuellem pyproject.toml-Edit	Step 2 ist Pflicht nach jedem manuellen Edit
fix: statt chore: für routinemäßiges Upgrade	Nur fix: wenn der Upgrade einen echten Bug in drift-analyzer behebt
Version-Bump-Gate blockiert chore:-Push	DRIFT_SKIP_VERSION_BUMP=1 git push
Tests gegen alte gecachte Pakete	uv sync --all-extras vor Tests (Schritt 3)

---

Checkliste (Kurzform)

[ ] Art der Änderung klassifiziert (add / upgrade / remove / security-patch)
[ ] pyproject.toml bearbeitet (oder uv add/remove genutzt)
[ ] uv lock ausgeführt — keine Konflikte
[ ] uv sync --all-extras ausgeführt
[ ] mypy src/drift — sauber
[ ] pytest quick suite — grün
[ ] git add pyproject.toml uv.lock (beide!)
[ ] Commit-Typ korrekt (chore: / fix: / feat:)
[ ] DRIFT_SKIP_VERSION_BUMP=1 wenn chore:-Push