# Kontrakt GEMA-0 — State Amnesia v2

> Źródło prawdy dla agenta i orkiestratora. Odchylenie = scope creep + przepalanie tokenów.

## Zasada nadrzędna: Bezwzględna Amnezja Stanu

Żaden plik iteracyjny nie akumuluje historii. Każda iteracja zaczyna się od **czystego stanu**.

## Zasady operacyjne (praktyka)

1. **Źródło prawdy o produkcie** — `00_master_plan.md` to zwięzły kontekst dla supervisora; **nie zastępuje** README, ADR ani dyskusji w issue/PR w repozytorium. Długoterminowe decyzje i pełna narracja żyją w **git + issue/PR**, nie w `20_agent_report.md`.
2. **Krok `10` atomowy** — jeden wykonywalny wynik na iterację. Jeśli zakres się rozlewa, architekt **dzieli pracę** na kolejne `STEP-…` zamiast poszerzać jeden krok lub kontrakt raportu.
3. **`20` wyłącznie delta** — w `## Zrobione` i `## Zmienione pliki` tylko to, co powstało w **bieżącej** iteracji; bez streszczeń całego projektu i bez powtórki historii z poprzednich tur (historia jest w commitach).
4. **Orkiestracja Gemini — opcjonalna** — `npm run validate:handoff` może kończyć prostą ścieżkę (np. sam commit). `npm run orchestrate:handoff` uruchamiaj, gdy potrzebujesz **oceny**, **propozycji następnego kroku** lub automatycznego wypełnienia `30_gemini_brief.md` / `cmd.md` w pętli z panelem; pomiń, gdy i tak zamykasz pracę bez supervisora.
5. **Bez dublowania historii** — nie przenoś pełnego dziennika dyskusji do plików nadpisywanych; krótki chronologiczny ślad orchestracji zostawia wyłącznie `40_session_log.md` (append).

## Pliki i reguły

### `00_master_plan.md` — globalny kontekst (READ-ONCE)

- Czytany **jednorazowo** przez Supervisora przy starcie sesji.
- Zawiera: cel projektu, stack, ograniczenia, kamienie milowe.
- Uzupełniaj rzadko; na stałe reguły techniczne i uzasadnienia preferuj w repo (README, ADR, kod).
- **NIE** dołączany do każdej iteracji — agent widzi tylko `10_step_current.md`.

### `10_step_current.md` — mikro-krok (NADPISYWANY)

- **Jeden** aktywny krok z `ID` w formacie `STEP-…`.
- Pola: `## Co zrobić`, `## Gotowe gdy`.
- Zero historii, zero ogólników, zero kontekstu projektu.
- Architekt nadpisuje cały plik przy zmianie kroku.
- **Automatyzacja:** przy `GEMA0_ORCHESTRATE_WRITE_NEXT_10=true` polecenie `npm run orchestrate:handoff` (`tools/orchestrate-handoff.mjs`) może nadpisać `10` nowym `STEP-…` tuż po zapisie `30_gemini_brief.md` (raport `20` dotyczy poprzedniego kroku do czasu kolejnej pracy agenta — `validate:handoff` może wtedy zgłaszać rozjazd ID do momentu nadpisania `20`).
- Zakres kroku musi dać się domknąć w jednej sensownej turze agenta; w razie przerostu — **nowy** `STEP-…`, nie „super-krok”.

### `20_agent_report.md` — raport delta (NADPISYWANY)

- Agent **nadpisuje cały plik** po każdej iteracji. Zakaz dopisywania.
- Treść sekcji = **wyłącznie skutek tej iteracji** względem `10` (patrz „Zasady operacyjne”).
- Pole `**Krok:**` z tym samym `STEP-…` co w `10_step_current.md`.
- Dokładnie **trzy** sekcje `##`:

| Sekcja | Treść |
|--------|-------|
| `## Zrobione` | Lista zrealizowanych zmian (min. jeden punkt). |
| `## Zmienione pliki` | `ścieżka/plik` — co zmieniono. |
| `## Blokady` | Blokery lub dosłownie `brak`. |

- **Zakaz** sekcji: Kontekst, Poza zakresem, Proponowany następny krok, Checklist.
- Maksymalna zwięzłość — każdy zbędny token to koszt.

### `cmd.md` — komenda maszynowa (NADPISYWANY)

- Format: pary `[AKCJA]` + `[CEL]`. Jedna para na linię.
- **Zakaz** uprzejmości, narracji, komentarzy. Tylko surowe instrukcje.
- Po `orchestrate:handoff` — nadpisuje orchestrator (Gemini). Przy pracy **bez** orchestracji architekt może nadpisać `cmd.md` ręcznie w tym samym formacie.

### `30_gemini_brief.md` — feedback supervisora (NADPISYWANY)

- Generowany automatycznie przez `npm run orchestrate:handoff`.
- Trzy sekcje: `## Ocena`, `## Następny krok`, `## Komenda`.
- Nie edytuj ręcznie.

### `40_session_log.md` — dziennik (APPEND)

- Jedyny plik z trybem append. Krótkie wpisy czasowe z orchestracji.

## Walidacja

`npm run validate:handoff` sprawdza:

1. `10_step_current.md` — niepusty, zawiera `STEP-…`.
2. `20_agent_report.md` — ma dokładne nagłówki `## Zrobione`, `## Zmienione pliki`, `## Blokady` z treścią.
3. Spójność `STEP-…` między krokiem a raportem.

## Bypass (wyjątki)

```bash
npm run orchestrate:handoff -- --no-validate
```

Lub `GEMA0_ORCHESTRATE_NO_VALIDATE=true`. Używaj rzadko.

**Pełna pętla bez ręcznego `10`:** w `gema0/.env` ustaw `GEMA0_ORCHESTRATE_WRITE_NEXT_10=true` — po walidacji `10+20` orchestrator wywoła Gemini drugi raz i zapisze nowy `10_step_current.md` (nowe `STEP-…`). Opcjonalnie `GEMA0_ORCHESTRATE_MEGA_STEP=true` — dłuższy brief i rozbudowany następny krok (test obciążeniowy modelu).