# Gema0 — wizja architektury autonomii (v2)

**Rola dokumentu:** jeden spójny opis „idealnego połączenia” między tym, co już fizycznie istnieje w repozytorium Gema0, a celem: **autonomiczna pętla plan → wykonanie w repo → weryfikacja**, z minimalną liczbą ruchomych części i maksymalną odpornością na błędy.

**Zakres:** analiza i projektowanie. Ten plik **nie zastępuje** README ani kontraktów w `workspace-notes.example`; scala je w jedną architekturę docelową.

---

## 1. Audyt stanu obecnego (co jest w repozytorium)

### 1.1 Warstwy systemu

| Warstwa | Lokalizacja w repo | Funkcja |
|--------|---------------------|---------|
| Panel HTTP + WebSocket | `backend/server.js`, `frontend/` | API (`/api/...`), statyczny UI, stream logów na `/ws`. |
| Orkiestracja komend | `backend/routes/chat.js`, `backend/services/commandParser.js` | `ZAPISZ`, `PUSH TO`, `BROADCAST`, `DRY PUSH`, `HEALTHCHECK`, `ASK GEMINI`, echo tekstu. |
| Kolejka RPA | `backend/services/queue.js`, `backend/services/pushTask.js` | Jedno zadanie RPA naraz; priorytety; pauza / resume / clear. |
| Worker RPA (Windows) | `rpa_workers/push_to_cursor.py` + `rpa_workers/common/*` | Aktywacja okna Cursora, hotkeye (`^l`, wklejenie, `@mention`, `^{ENTER}`), adaptacyjne opóźnienia, panic-stop. |
| Notatki / „magistrala plików” | `backend/services/noteWriter.js`, `paths.notes` (`config.js` + `GEMA0_NOTES_DIR`) | Wersjonowane `.md`; lista i odczyt przez API. |
| Auto-push z dysku | `backend/services/autoPush.js`, `storage/auto_push.json` | Chokidar na `.md` w katalogu notatek → kolejka pushy według reguł. |
| Most schowka (opcjonalny) | `backend/services/clipboardBridge.js`, `rpa_workers/clipboard_watcher.py` | Cursor → panel (eventy); opcjonalny zapis do notatki. |
| Orkiestracja „handoff” (CLI) | `tools/orchestrate-handoff.mjs`, `tools/validate-agent-report.mjs` | Czyta `10_step_current.md`, `20_agent_report.md`, woła **Gemini** (SDK), zapisuje `30_gemini_brief.md`, nadpisuje `cmd.md`. |
| Watch na polecenia | `tools/watch-cmd.mjs` | Zmiana `cmd.md` → `POST` do lokalnego panelu → `PUSH TO … @cmd.md`. |
| Szablon workspace | `workspace-notes.example/` | Konwencja plików (`CONTRACT.md`, numeryczne prefiksy, `cmd.md`). |

**Uwaga dot. LLM:** w kodzie źródłowym tego repozytorium integracja HTTP do modelu jest zaimplementowana dla **Google Gemini** (`backend/services/geminiClient.js`, `@google/generative-ai` w `tools/orchestrate-handoff.mjs`). Jeśli środowisko produkcyjne (np. Render) używa **OpenAI**, należy potraktować to jako **drugi adapter** tej samej warstwy „Orchestrator LLM” — kontrakt wejścia/wyjścia (pliki w `GEMA0_NOTES_DIR`) pozostaje ten sam.

### 1.2 Komunikacja: serwer (chmura lub laptop) ↔ Cursor

**Dziś w repozytorium obowiązują dwa kanały „w dół” do Cursora:**

1. **RPA (lokalne):** Node wywołuje Pythona; Python **symuluje użytkownika** (okno, schowek, hotkeye). Nie ma oficjalnego API Cursora — jest **sterowanie UI**. Wymaga **Windowsa** i procesu `Cursor.exe` oraz poprawnego `backend/config/windows_map.json`.
2. **Git + edycja plików w workspace:** agent (lub człowiek) w Cursorze **sam** zmienia repo na podstawie treści w `cmd.md` / `@…md`. Panel tylko **dostarcza impuls** (`PUSH` wkleja prompt z odwołaniem do pliku).

**Kanał „w górę” (Cursor / projekt → orchestrator):**

- Semantycznie: **zmiany plików** w katalogu notatek (`GEMA0_NOTES_DIR`), zwłaszcza `20_agent_report.md`, oraz ewentualnie inne pliki z kontraktu.
- Technicznie: **auto-push** reaguje na `.md`; **watch-cmd** na `cmd.md` (w drugą stronę — impuls do Cursora).
- Opcjonalnie: **clipboard watcher** (włączany świadomie w `config.json`).

**Render.com w tym obrazie:** typowy deployment Node na Render **nie uruchomi** `push_to_cursor.py` (Win32). Zatem sensowny podział to:

- **Render:** API orkiestracji, webhooki, kolejka *logiczna*, wywołania OpenAI/Gemini, ewentualnie zapis do **tego samego repo przez Git** (CI, commit bot).
- **Lokalnie (lub dedykowany runner Windows):** panel Gema0 + Python RPA *albo* tylko skrypt nasłuchujący na zmiany w klonie repo i wołający `PUSH`.

Bez lokalnego runnera **pełna** pętla „cloud → natychmiastowy chat Cursora” nie istnieje; zostaje **Git jako magistrala** albo **człowiek** otwierający Cursor.

### 1.3 Wąskie gardła (twarda lista)

| Wąskie gardło | Skutek |
|---------------|--------|
| **Pojedyncza kolejka RPA** (`TaskQueue`) | Równoległe `PUSH` serializują się; długi krok blokuje resztę. |
| **Jeden focus OS** | Nawet `BROADCAST` wykonuje się **sekwencyjnie** okno po oknie. |
| **Dopasowanie okien** (`rapidfuzz`, próg, tytuły) | Fałszywe dopasowanie lub brak okna = błąd RPA; wymaga utrzymania `windows_map.json`. |
| **Brak potwierdzenia z Cursora** | System nie wie z HTTP, że „agent zakończył” — wnioski tylko z **plików** lub logów RPA. |
| **Rozjazd katalogów** | Jeśli `GEMA0_NOTES_DIR` ≠ folder widziany przez `@` w Cursorze, `@mention` i intencja użytkownika się rozjeżdżają. |
| **Chmura bez Windowsa** | Pełny `PUSH` musi zostać na maszynie z Cursorami; Render nie zastąpi RPA 1:1. |
| **Heurystyka treści** | Modele mogą naruszać kontrakt plików (`validate-agent-report`); bez twardych bramek rośnie chaos. |

---

## 2. Propozycja: pętla pracy agentów (najprostsza i najbardziej odporna)

### 2.1 Decyzja architektoniczna

**Nie** polegać wyłącznie na metadanych zaszytych w treści `.md` (łatwo je zepsuć jednym „refaktorem” przez model).

**Nie** wprowadzać wielu równorzędnych „magicznych” formatów nazw bez adresacji.

**Tak — model hybrydowy (rekomendowany):**

1. **Kontrakty o stałych nazwach** (już masz: `10_step_current.md`, `20_agent_report.md`, `30_gemini_brief.md`, `cmd.md`, `40_session_log.md`) — to **interfejs publiczny** między rolami.
2. **Jeden plik stanu maszyny** w podkatalogu ukrytym, np. `GEMA0_NOTES_DIR/.gema0_state/run_state.json` (obok już używanego `last_handoff.json` z orchestracji) — **kto trzyma piłkę**, liczniki pętli, ostatni hash raportu, TTL blokady.
3. **Kolejki jako podfoldery** tylko tam, gdzie trzeba wielu równoległych zadań, np. `queue/incoming/*.md` przenoszonych atomowo do `queue/active/` — **dla zadań wieloetapowych lub wielu projektów**, bez mieszania z kontraktem „jednego kroku” w korzeniu notatek.

Uzasadnienie: **Markdown zostaje czytelny dla ludzi i Cursora**; **JSON stanu** jest twardy dla automatów i tani w walidacji; **foldery kolejek** rozwiązują race przy wielu plikach wejściowych bez parsowania treści.

### 2.2 Idealny przepływ (workflow) — dopasowany do obecnych plików

```mermaid
flowchart LR
  subgraph cloud [Render / Orchestrator API]
    A[Przyjęcie zadania wysokopoziomowego]
    B[Plan: aktualizacja 10_step_current.md]
    C[LLM: OpenAI lub Gemini]
  end
  subgraph disk [GEMA0_NOTES_DIR + repo]
    D[20_agent_report.md]
    E[30_gemini_brief.md]
    F[cmd.md]
    G[run_state.json]
  end
  subgraph local [Lokalny runner]
    H[watch-cmd lub auto_push]
    I[Panel /api/chat → kolejka]
    J[RPA push_to_cursor.py]
  end
  A --> B --> C
  C --> E --> F
  F --> H --> I --> J
  J --> Cursor[Cursor: agent realizuje]
  Cursor --> D
  D --> C
  D --> G
```

**Kroki (semantyka):**

1. **Architekt (rola planująca):** ustawia / aktualizuje `10_step_current.md`, ewentualnie `00_ROADMAP.md`; inicjalizuje wpis w `run_state.json`: `phase: planning → execution`, `owner: architect`, `iteration++`.
2. **Programista (Cursor / agent kodu):** po impulsie z `cmd.md` (przez `PUSH` lub ręcznie) wykonuje zmiany w **repozytorium projektu**; raportuje w **`20_agent_report.md`** według kontraktu (`validate-agent-report`).
3. **Audytor (LLM + walidator):** `orchestrate-handoff` (lub analog na OpenAI) czyta `10` + `20`; po walidacji generuje `30_gemini_brief.md`, log w `40_session_log.md`, nadpisuje `cmd.md` — **następna iteracja** albo zamknięcie zadania w `run_state.json`.

**„Idealne połączenie” z obecnym stosem:** nie zastępować `PUSH` magicznym protokołem — **trzymać się plików + jednego JSON stanu + istniejącej kolejki Node** jako jedynego miejsca serializacji RPA.

---

## 3. Zarządzanie stanem i wielość agentów

### 3.1 Kto trzyma piłkę

W `run_state.json` (propozycja minimalnego schematu):

- `owner`: `architect` | `executor` | `auditor` | `human`
- `phase`: `planning` | `executing` | `review` | `blocked` | `done`
- `task_id`: UUID lub slug zadania
- `lease_until`: timestamp — po jego przekroczeniu inny proces może przejąć ster (ratunek przed zawieszeniem)
- `last_report_hash`: skrót treści `20_agent_report.md` (wykrywanie braku postępu)
- `consecutive_same_hash`: licznik „braku zmiany” raportu

**Reguła złota:** tylko **jeden owner** na raz może mieć prawo **dopisywać `cmd.md`** lub **zmieniać `10_step_current.md`**; reszta albo czeka, albo pisze tylko do swojej kolejki (`queue/incoming/`).

### 3.2 Konflikty przy wielu agentach

| Mechanizm | Opis |
|-----------|------|
| **Single writer dla impulsów RPA** | Już jest: `TaskQueue`. Wszystkie `PUSH` idą przez jedną kolejkę — nie ma dwóch RPA naraz. |
| **Rozdzielenie „mózgów”** | Wielu agentów LLM w chmurze **nie** pushuje bezpośrednio do Cursora; zapisują propozycje do **swoich** plików w `queue/incoming/`; jeden **dyspozytor** (skrypt lub cron na Render) scala wynik do **jednego** `cmd.md`. |
| **Git jako źródło prawdy** | Dla wielu ludzi/agentów w tym samym repo: krótkie gałęzie + merge albo **jedna gałąź `gema0-automation`** tylko na pliki `.gema0`. |
| **Mapowanie okien** | `CURSOR_1` = główny executor; `CURSOR_2+` = przegląd / testy — ogranicza kolizję dwóch agentów w jednym oknie. |

---

## 4. Bezpieczeństwo i stabilność — „pętla ratunkowa”

Propozycja **warstwowej** obrony (łatwa do implementacji przyrostowo):

### 4.1 Limity ilościowe (twarde)

- **`max_iterations`** na `task_id` w `run_state.json` (np. 30). Przekroczenie → `phase: blocked`, `owner: human`, **brak** auto-dopisywania `cmd.md`.
- **`max_consecutive_llm_calls`** bez nowego `git diff` / bez zmiany hash raportu (opcjonalnie, gdy runner ma dostęp do `GEMA0_GIT_ROOT`).
- **Cooldown** między auto-pushami — już częściowo jest (`cooldown_ms` w `auto_push.json`); rozciągnąć ideę na orchestrator.

### 4.2 Detekcja „kręcenia się w kółko”

- Porównanie **`sha256(20_agent_report.md)`** przed i po cyklu; jeśli N razy z rzędu ten sam hash przy próbie „dalej” → STOP.
- Porównanie **`sha256(30_gemini_brief.md)`** (powielane te same polecenia).
- Prosty **graf przejść faz**: dozwolone przejścia zapisane w `run_state.json`; nieprawidłowe przejście → reset lub eskalacja.

### 4.3 Jakość semantyczna

- Obowiązkowe **`validate-agent-report`** przed każdym wywołaniem LLM w orchestracji (już domyślnie w `orchestrate-handoff.mjs`).
- **„Human gate”:** plik `HANDOFF_BLOCK.md` lub flaga w `run_state.json` — jeśli istnieje, orchestrator **nie** generuje nowego `cmd.md`.

### 4.4 Awaria RPA / UI

- Już jest: **panic hotkey** (`common/panic.py`), **pauza kolejki** (`/api/queue/pause`), **adaptive delays**.
- Docelowo: orchestrator po **timeout** workerów (już w `runWorker`) ustawia `phase: blocked` i nie dokłada pushy aż do `resume` z UI lub API.

### 4.5 Kill switch globalny

- Zmienna środowiskowa np. `GEMA0_AUTONOMY=off` na Render + lokalnym runnerze: **żadnych** automatycznych `cmd.md` / `watch-cmd`.

---

## 5. Plan wdrożenia pełnej autonomii (fazy)

| Faza | Cel | Dotykane obszary |
|------|-----|------------------|
| **F0 — kontrakty** | Ustalić jeden zestaw plików i walidację (już blisko `workspace-notes.example`). | Szablon w projekcie klienta, `validate-agent-report.mjs`. |
| **F1 — stan** | Wprowadzić `run_state.json` + prosty zapis `owner/phase/iteration`. | Nowy mały moduł po stronie `tools/` i/lub `backend/` (tylko odczyt/zapis pliku). |
| **F2 — runner chmury** | Render: endpoint „przyjmij zadanie”, zapis do Git (commit) lub do wygenerowanej gałęzi; trigger lokalnego runnera (webhook → VPN → home) **albo** tylko Git pull na maszynie z panelem. | Nowy serwis lub rozszerzenie `server.js`, pipeline Git. |
| **F3 — adapter LLM** | Ujednolicić `askGemini` / `orchestrate-handoff` pod interfejs `llm.complete({system, user})`. | `backend/services/geminiClient.js`, `tools/orchestrate-handoff.mjs`, ewentualnie `openaiClient.js`. |
| **F4 — pętla zamknięta** | Po zapisie `20_agent_report.md` (watcher lub hook git) automatycznie wywołuje orchestrator → `cmd.md` → `watch-cmd` / auto_push → `PUSH`. | Skrypt supervisor lub rozszerzenie `watch-cmd` o drugi watcher. |
| **F5 — wieloagentowość** | Kolejki folderowe + dyspozytor. | Konwencja katalogów w `GEMA0_NOTES_DIR`, jeden proces scalający. |
| **F6 — twardy ratunek** | Limity iteracji + hash-stagnation + `HANDOFF_BLOCK`. | `run_state.json`, orchestrator, opcjonalnie UI w `frontend/`. |

---

## 6. Lista plików do modyfikacji (orientacyjna)

**Wdrożone (supervisor wieloprojektowy):** `backend/config/projects_registry.example.json`, `tools/lib/loadProjectsRegistry.mjs`, `tools/supervisor-loop.mjs`, skrypt `npm run supervisor:loop` w `package.json`, wpis `.gitignore` dla `backend/config/projects_registry.json`. Stan cykli i ponowień PUSH: **`.gema0_state/supervisor_run.json`** (m.in. `push_delivery_*`, `push_delivery_last_error`). Szczegóły uruchomienia i zmienne **`GEMA0_SUPERVISOR_PUSH_RETRY_*`**: główny `README.md` (sekcja *Supervisor wieloprojektowy*).

Przy dalszych fazach powyższej listy, **najpewniej** dotkniesz (bez presji na wszystkie naraz):

**Backend / panel**

- `backend/server.js` — ewentualnie nowe trasy API (webhook, stan autonomii).
- `backend/routes/chat.js` — rozszerzenie komend lub proxy do supervisora.
- `backend/services/commandParser.js` — nowe werble komend (np. `STATE SET`, jeśli ma być z UI).
- `backend/services/config.js`, `backend/config/config.json` — ścieżki do `run_state`, flagi autonomii.
- `frontend/js/app.js`, `frontend/index.html` — podgląd fazy, kill switch, liczniki.

**Narzędzia CLI / orchestracja**

- `tools/orchestrate-handoff.mjs` — zapis `run_state.json`, limity iteracji, adapter OpenAI.
- `tools/watch-cmd.mjs` — drugi watcher (`20_agent_report.md`) lub wywołanie supervisora.
- Nowy plik (propozycja): `tools/supervisor-loop.mjs` lub `backend/services/autonomySupervisor.js`.

**RPA (tylko jeśli zmienia się kontrakt push)**

- `rpa_workers/push_to_cursor.py` — rzadko; raczej trzymać logikę w plikach notatek.

**Konfiguracja / docs**

- `workspace-notes.example/CONTRACT.md` — dopisanie pól stanu i kolejek.
- `_docs/gema0_vision_v2.md` — ten dokument; aktualizować po każdej fazie.

---

## 7. Podsumowanie dla zespołu

- **Komunikacja z Cursorem dziś:** głównie **RPA z lokalnego Node** + **semantyka plików** w `GEMA0_NOTES_DIR`; Render **nie zastąpi** RPA bez osobnego runnera Windows lub rezygnacji z UI na rzecz **samego Git**.
- **Najprostsza autonomia:** utrzymać **kontrakty plików** z `workspace-notes.example`, dodać **jeden JSON stanu**, spiąć **watch-cmd + orchestrate-handoff + auto_push** w jedną nadzorowaną pętlę z **twardymi limitami** i **pauzą kolejki**.
- **OpenAI vs Gemini:** ten sam układ katalogów i plików; zmiana wyłącznie warstwy wywołania LLM i sekretów na Renderze.

**Operator — pierwsze wdrożenie:** `_docs/INSTALACJA_OPERATORA.md`, kreator **`/install`** w panelu, szablon **`workspace-notes.example/00_IDEALNY_START.md`** (kopiowany z bootstrapem do projektu).

Ten dokument jest **punktem odniesienia** dla kolejnych PR: każda faza z sekcji 5 powinna mieć krótki changelog w stopce (data, status faz).

---
*Ostatnia aktualizacja: 2026-05-15 — v2 + odnośniki do instalacji i szablonu operatora.*