# 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).