# Protokół pracy agenta (Cursor / AI)

**Wersja protokołu:** 1.0  
**Wersja projektu:** `10.0.0` — zawsze sprawdź `package.json` przed sesją; jeśli się różni od wpisu w `AGENT_LOG.md`, zaktualizuj nagłówek logu.

---

## 0. Pliki tylko dla właściciela (człowieka)

Katalog **`_docs/DLA_WLASCICIELA/`** — **NIE czytaj** na starcie sesji ani przy zwykłych zadaniach.  
Tam są instrukcje git/backup dla Damiana, nie dla agenta. Wyjątek: użytkownik poda konkretną ścieżkę.

Na koniec dużej sesji możesz dopisać **krótki** blok (≤8 linii) na górę `DLA_WLASCICIELA/02_DZIENNIK_ZMIAN.md` z timestampem `YYYY-MM-DD HH:MM` — bez powielania całego `AGENT_LOG.md`.

---

## 1. Start sesji (przed edycją plików)

1. Przeczytaj [_docs/README.md](README.md) — sekcja **„Dla agenta”** (nie czytaj mapy „Dla właściciela”).
2. Przeczytaj **tylko najnowszy wpis** w [AGENT_LOG.md](AGENT_LOG.md) — nie skanuj całej historii.
3. Otwórz [00_GEMA0_ULTIMATE_MASTERPLAN.md](00_GEMA0_ULTIMATE_MASTERPLAN.md) (backend) lub [02_WIZJA_FRONTEND_NLE_SEQUENCER.md](02_WIZJA_FRONTEND_NLE_SEQUENCER.md) (frontend) — tylko jeśli zadanie dotyczy tej warstwy.
4. **Nie implementuj** treści z [01_WIZJA_FRONTEND_MATRIX_DIVE.md](01_WIZJA_FRONTEND_MATRIX_DIVE.md) — to archiwum odrzuconej wizji WebGPU.

Pracujesz nad **legacy v2** (`legacy/v2_monolith/`)? Dodatkowo: [../legacy/v2_monolith/README_ARCHIWUM.md](../legacy/v2_monolith/README_ARCHIWUM.md) i stary [../legacy/PROCES_ZMIANY_I_RAPORT.md](../legacy/PROCES_ZMIANY_I_RAPORT.md).

---

## 2. Koniec sesji (obowiązkowe po zmianach w repo)

### A. Dziennik — zawsze pierwsze

Dopisz **nowy wpis na samej górze** [AGENT_LOG.md](AGENT_LOG.md) (pod linią `<!-- NOWE WPISY PONIŻEJ -->`).

Użyj szablonu z tego pliku. Wpis musi zawierać:

- datę i wersję projektu,
- zakres (backend / frontend / docs / legacy),
- listę zmienionych plików,
- co zrobiono (1–3 zdania),
- **co zauważyłeś, a nie naprawiłeś** (sekcja „Otwarte / do poprawy” — nawet jeśli pusta: wpisz „brak”).

### B. Checkboxy w planie — tylko gdy faktycznie ukończyłeś krok

| Obszar | Plik |
|--------|------|
| Fazy 0–4, moduły APEX | [00_GEMA0_ULTIMATE_MASTERPLAN.md](00_GEMA0_ULTIMATE_MASTERPLAN.md) |
| Frontend NLE (F1, F2, …) | [02_WIZJA_FRONTEND_NLE_SEQUENCER.md](02_WIZJA_FRONTEND_NLE_SEQUENCER.md) |

Odhacz `[x]` **tylko** to, co w tej sesji dowiodłeś w kodzie lub testach. Nie zgaduj na podstawie starych opisów.

### C. README root — tylko przy zmianie uruchomienia

Jeśli zmieniły się komendy npm, porty, env lub kształt API → zaktualizuj [../README.md](../README.md).

### D. Sesja bez zmian w plikach

Jedna linia na górze `AGENT_LOG.md`:

```markdown
### YYYY-MM-DD — tylko konsultacja
- **Wersja:** 10.0.0
- **Zakres:** doradztwo / przegląd
- **Pliki:** brak
- **Uwagi:** (opcjonalnie)
```

---

## 3. Czego agent NIE robi bez pytania właściciela

- Nie podbija wersji w `package.json` bez wyraźnej prośby.
- Nie przenosi ani nie kasuje plików w `_docs/` poza protokołem (nowe wpisy → `AGENT_LOG.md`).
- Nie commituje `.env` ani kluczy API.
- Nie wymyśla nowych faz produktowych — jeśli brakuje planu, opisz lukę w `AGENT_LOG.md` → „Otwarte / do poprawy” i zapytaj człowieka.

---

## 4. Git — jedno miejsce (`main`)

Skrót dla agenta: **[04_GIT_JEDNO_MAIN.md](04_GIT_JEDNO_MAIN.md)**.  
Instrukcje dla właściciela: **`DLA_WLASCICIELA/`** — nie czytaj.

Skrót:

- Aktywny kod V10: gałąź **`main`**, katalog root (`backend/`, `frontend/sequencer-ui/`, `_docs/`).
- Po sesji z zmianami: `git status` → `git add -A` → **`git commit`** → **`git push origin main`**.
- Samo `git add` (staged) **nie** wystarczy — bez commita inna maszyna widzi starą wersję.
- Agent **nie** commituje bez prośby właściciela — ale **musi** przypomnieć, jeśli `git status` nie jest clean / jest `ahead` bez push.

---

## 5. Krótki checklist (skopiuj mentalnie)

```
[ ] Przeczytałem ostatni wpis AGENT_LOG.md
[ ] Jestem na gałęzi main (git branch)
[ ] Wersja z package.json zgodna z logiem
[ ] Po pracy: wpis w AGENT_LOG.md (z sekcją „Otwarte”)
[ ] Checkboxy w masterplanie / wizji UI — tylko jeśli dotyczy i ukończone
[ ] README — tylko jeśli zmieniło się uruchomienie
[ ] Git: commit + push na main (albo przypomnienie właścicielowi)
```