Guard Src Drift Commands

---
name: guard-src-drift-commands
description: "Drift-generierter Guard fuer `src/drift/commands`. Aktiv bei Signalen: EDS, PFS. Konfidenz: 0.89. Verwende diesen Skill wenn du Aenderungen an `src/drift/commands` planst oder wiederholte Drift-Findings (EDS, PFS) fuer dieses Modul bearbeitest."
argument-hint: "Beschreibe welchen CLI-Befehl (analyze, verify, serve, calibrate...) du veraenderst und warum."
---

# Guard: `src/drift/commands`

`src/drift/commands` enthaelt die CLI-Command-Handler. Jeder Subbefehl (`analyze`, `verify`, `serve`, `calibrate`, ...) hat eine eigene Datei. EDS entsteht wenn Commands direkt in `pipeline.py` oder `Analyzer()` einsteigen. PFS entsteht wenn Commands inkonsistente Argument-Parsing- oder Output-Handling-Muster verwenden.

**Konfidenz: 0.89** — EDS und PFS treten regelmaessig auf, oft nach Features die Shortcuts einbauen.

## When To Use

- Du fuegest einen neuen CLI-Subbefehl hinzu
- Du aenderst wie ein bestehender Befehl Argumente verarbeitet oder Ergebnisse ausgibt
- Du aenderst wie Exit-Codes gesetzt werden
- Drift meldet EDS oder PFS fuer eine Datei in `src/drift/commands/`

**Nicht benutzen** fuer Aenderungen an der CLI-Definition in `cli.py` — das ist ein anderer Scope.

## Warum dieses Modul kritisch ist

| Signal | Ursache in `commands/` |
|--------|------------------------|
| **EDS** | Command-Handler die direkt `pipeline.run()`, `Analyzer()` oder `scoring/`-Module aufrufen — Command sollte ausschliesslich die entsprechende `api/`-Funktion aufrufen |
| **PFS** | Inkonsistente Exit-Code-Logik: manche Commands nutzen `sys.exit(1)`, andere `raise SystemExit`, andere geben `1` zurueck |

## Core Rules

1. **Commands delegieren an `api/`** — ein Command-Handler tut folgendes: Argumente lesen → `api.function(...)` aufrufen → Ergebnis mit `output/` rendern → Exit-Code setzen. Kein direkter Aufruf von `pipeline.py` oder `Analyzer()`.

2. **Konsistente Exit-Code-Konvention** — `0` = Erfolg, `1` = Findings ueber Threshold, `2` = Konfigurationsfehler, `3` = interne Fehler. Kein eigenes Exit-Code-Schema in einem neuen Command.

3. **Output-Formatierung nicht im Command-Handler** — der Command-Handler uebergibt das Ergebnis an einen Formatter aus `output/`. Kein `print(json.dumps(...))` direkt im Command.

4. **`--format`-Flag konsistent** — alle Commands die Ausgabe erzeugen, unterstuetzen dasselbe `--format`-Flag mit denselben Werten (`rich`, `json`, `markdown`). PFS steigt wenn ein neuer Command andere Werte einfuehrt.

5. **Fehlerbehandlung uniform** — Commands fangen `DriftError` und schreiben in stderr, nicht stdout. Ein neuer Command der Fehler in stdout schreibt bricht tooling-pipelines.

## Review Checklist

- [ ] Command ruft `api.function()` auf, nicht `pipeline.py` direkt
- [ ] Exit-Code folgt der 0/1/2/3-Konvention
- [ ] Output geht durch Formatter aus `output/`, kein direktes `print`
- [ ] `--format`-Flag hat dieselben Werte wie andere Commands
- [ ] Fehler gehen nach stderr, nicht stdout
- [ ] `drift nudge` zeigt `safe_to_commit: true`
- [ ] Keine neuen EDS/PFS-Findings in `src/drift/commands/`

## References

- [src/drift/cli.py](../../../src/drift/cli.py) — CLI-Einstiegspunkt und Command-Registrierung
- [src/drift/api/](../../../src/drift/api/) — Alle aufrufbaren API-Funktionen
- [src/drift/output/](../../../src/drift/output/) — Output-Formatter
- [DEVELOPER.md](../../DEVELOPER.md)