# ADR-0002: Deterministycznie tyle, ile się da; model tylko na resztę

- Status: przyjęty
- Data: 2026-08-28

## Kontekst

Migracja SDK to w większości mechaniczne podmiany. Powierzenie ich modelowi kosztuje tokeny,
wydłuża przebieg i wprowadza wariancję tam, gdzie wariancja jest czystą stratą -
nikt nie chce, żeby dwa uruchomienia dawały inny diff dla tej samej zmiany nazwy metody.

## Decyzja

Dzielimy pracę wzdłuż linii "czy da się to zrobić kodem":

1. Wykrycie ekosystemu, plików zależności i komendy testowej - adapter (`adapters/`).
2. Podbicie deklaracji wersji - adapter.
3. Migracja objęta regułami - silnik reguł czytający `*.codemod.yaml` z pakietu APM.
4. Reszta - agent `coder` z LLM.
5. Ocena wyniku - agent `reviewer` **oraz** niezależna kontrola mechaniczna.

Reguły codemod są częścią pakietu APM (leżą obok notatki migracyjnej), więc podlegają
temu samemu przeglądowi i wersjonowaniu co wiedza dla modelu.

## Konsekwencje

**Pozytywne**

- Powstaje tryb `--offline`: ta sama topologia bez modelu. Smoke test całego pipeline'u
  na każdym MR, bez GPU i bez internetu.
- Punkt odniesienia: widać, ile przypadków model faktycznie dołożył ponad reguły.
- Mniejszy koszt i krótszy przebieg dla typowych migracji.

**Negatywne**

- Dwie ścieżki do utrzymania (`RuleBrain`, `LlmBrain`) i wspólny kontrakt między nimi.
- Reguły regexowe mają znane ograniczenia (zmiany strukturalne, wieloliniowe konteksty).
  Świadomie nie budujemy własnego silnika AST - od tego są narzędzia dziedzinowe
  (OpenRewrite, jscodeshift), które można podpiąć jako kolejny adapter.