balantrapu87/amds

Motion Studio SDLC Execution Playbook

Wenn Sie mit der Implementierung einer Funktion oder eines Bugfixes in diesem Repository beauftragt werden, führen Sie diese Schritte genau in der angegebenen Reihenfolge aus:

Schritt 1: Vertragsynchronisation (Spec Gate)

1. Überprüfen Sie engine/schemas.py und remotion/src/types.ts.
2. Fügen Sie Felder hinzu oder ändern Sie sie, um die Funktionsanforderungen zu erfüllen.
3. Stellen Sie sicher, dass die Pydantic-Modelle kompilieren:

   python3 -c "import engine.schemas as s; print('Schemas OK')"
   

   (Hinweis: Falls eine virtuelle Umgebung existiert, rufen Sie sie über .venv/bin/python3 auf).
4. Fahren Sie niemals mit dem Implementierungscode fort, bis die Verträge in beiden Sprachen abgestimmt sind.

Schritt 2: Rotphase (Fehlschlagende Tests erstellen)

1. Schreiben Sie eine neue Testdatei oder einen Testfall unter tests/ (Pytest) oder remotion/src/__tests__/ (Vitest/Jest).
2. Testen Sie die Schema-Validierung, Randfälle und die erwartete serialisierte Ausgabe.
3. Führen Sie den Test aus und bestätigen Sie den Fehlschlag:

   pytest tests/
   # Falls der Frontend-Testrunner in remotion/package.json konfiguriert ist:
   npm --prefix remotion test -- --run
   

4. Notieren Sie die Fehler-Trace. Wenn der Test sofort bestanden wird, schreiben Sie ihn um, um die tatsächliche neue Fähigkeit zu testen. Die Rotphase ist nur zufriedenstellend, wenn die Tests mit den erwarteten Behauptungen fehlschlagen.

Schritt 3: Grünphase (Minimale Implementierung)

1. Schreiben Sie den minimalen Code in engine/ oder remotion/src/, um den fehlgeschlagenen Test zu bestehen.
2. Halten Sie sich in Remotion strikt an das Gesetz des deterministischen Frames:
   • Die Ableitung muss ausschließlich über useCurrentFrame() und useVideoConfig() erfolgen.
   • Verwenden Sie niemals Date.now(), Math.random() oder unbegrenztes requestAnimationFrame().
3. Bewahren Sie die bestehenden Architekturmuster (<Series>, <Sequence>, <ThreeScene>, <KineticScene>).
4. Stellen Sie sicher, dass Vektor-Assets IDs und Klassen gemäß remotion/svgo.config.mjs für das GSAP-Targeting beibehalten.

Schritt 4: Qualitätsgate & Automatisierte Self-Healing-Schleife

Führen Sie den Schleifenzähler (ATTEMPT ∈ {1, 2, 3}). Führen Sie jedes Gateway nacheinander aus, ohne die Exit-Codes zu maskieren (verwenden Sie nicht || true):

# Stufe 1: Statische Typanalyse
python3 -m mypy engine/schemas.py engine/api.py
npm --prefix remotion run build -- --bundle-cache=false

# Stufe 2: Automatisierte Test-Suiten
pytest tests/
# Falls der Frontend-Testrunner in remotion/package.json konfiguriert ist:
npm --prefix remotion test -- --run

# Stufe 3: Headless Chromium Frame-Rasterisierung
(cd remotion && npx remotion still src/index.ts MainComposition /tmp/smoke.png \
  --props='{"scenes":[],"theme":{}}' \
  --gl=angle \
  --overwrite)

Self-Healing- & Rollback-Richtlinie

• Bei Fehlschlag (Versuch 1 oder 2):

  1. Erfassen Sie den genauen Dateipfad, die fehlschlagende Zeilennummer und stderr/Traceback.
  2. Implementieren Sie einen minimalen, zielgerichteten Patch, der strikt den gemeldeten Fehler behebt.
  3. Erhöhen Sie ATTEMPT und starten Sie Stufe 1 neu.

• Bei Fehlschlag (Versuch 3 – Budget erschöpft): Stoppen Sie sofort spekulative Änderungen und stellen Sie nur die geänderten und erstellten Feature-Dateien zurück (führen Sie niemals eine pauschale globale Bereinigung durch):

  # Stufe 4 Erschöpfungs-Fallback: Nur Feature-Code-Bereiche betreffen
  git restore --staged --worktree engine/ remotion/ tests/
  git clean -fd engine/ remotion/ tests/
  rm -f /tmp/smoke.png
  echo "Qualitätsgate nach 3 Versuchen fehlgeschlagen. Ziel-Codepfade auf saubere Basis zurückgesetzt."
  exit 1
  

  (Alternative, um Arbeiten für eine Post-Mortem-Analyse zu bewahren: git stash push -u -m "sdlc-failed-attempt-$(date +%s)" -- engine/ remotion/ tests/)

• Bei Erfolg (Alle Stufen Exit 0): Entfernen Sie flüchtige Artefakte und erstellen Sie den verifizierten Commit:

  rm -f /tmp/smoke.png
  git add engine/ remotion/ tests/
  git commit -m "feat(motion-sdlc): implement verified feature with green test gate"