feat: initial commit

2026-08-29 13:17:59 +02:00
commit 142f5f5759
91 changed files with 6155 additions and 0 deletions
@@ -0,0 +1,45 @@
+# ADR-0001: APM jako łańcuch dostaw kontekstu agentowego
+
+- Status: przyjęty
+- Data: 2026-08-28
+
+## Kontekst
+
+Prompty, skille i guardraile dla agentów mają wszystkie cechy zależności: są współdzielone
+między repozytoriami, zmieniają się w czasie, mają właścicieli i wpływają na wynik.
+Trzymane jako pliki w repozytorium silnika stają się nierozróżnialne od kodu: nie da się ich
+niezależnie wersjonować, nie da się powiedzieć "ten przebieg użył wiedzy migracyjnej w wersji 1.2.0".
+
+## Decyzja
+
+Kontekst agentowy dostarczamy pakietami APM (Microsoft Agent Package Manager):
+`apm.yml` deklaruje zależności, `apm install` rozwiązuje je do `apm_modules/`,
+`apm.lock.yaml` pinuje commity i hashe, `apm-policy.yml` ogranicza dopuszczalne źródła
+i prymitywy, `apm audit` wykrywa dryf.
+
+Silnik (Python + agno) czyta prymitywy z `.apm/` oraz `apm_modules/` i kompiluje je
+do obiektów agno. Prymitywy lokalne mają pierwszeństwo przed zainstalowanymi.
+
+## Konsekwencje
+
+**Pozytywne**
+
+- Zespół właściciela SDK dostarcza wiedzę migracyjną jako pakiet, bez dostępu do silnika.
+- Hash lockfile'a w manifeście przebiegu odpowiada na pytanie "co dokładnie wiedział model".
+- Polityka instalacyjna jest egzekwowana w CI, a nie w regulaminie.
+
+**Negatywne**
+
+- Dodatkowa zależność narzędziowa (APM CLI) w obrazie runnera.
+- Potrzebny wewnętrzny rejestr pakietów (w praktyce: repozytoria GitLaba) i dyscyplina tagowania.
+- Ryzyko rozjazdu między wersją silnika a formatem prymitywów - łagodzone testem
+  `test_apm_context.py`, który waliduje kontekst przy każdym MR.
+
+## Rozważane alternatywy
+
+- **Prompty w repozytorium silnika.** Najprostsze, ale uniemożliwia niezależne wersjonowanie
+  wiedzy dziedzinowej i rozmywa własność.
+- **Baza wektorowa z dokumentacją migracji.** Nieodtwarzalne: dwa przebiegi na tym samym commicie
+  mogą dostać inny kontekst. Odpada w środowisku wymagającym audytu.
+- **Własny format pakietu.** Koszt utrzymania bez zysku; APM daje lockfile, politykę i skanowanie
+  ukrytego Unicode z pudełka, opierając się na otwartych standardach (AGENTS.md, Agent Skills, MCP).