# Mapa planów: architecture v5 ↔ V10 APEX ↔ legacy

**Status:** ŹRÓDŁO PRAWDY dla relacji między planami (2026-05-20)  
**Wersja projektu:** `10.0.0`

Ten dokument **naprawia rozjazd** powstały 2026-05-18/19: równolegle powstały **architecture v5** (protokół plików) i **V10 APEX masterplan** (kod w `backend/`) — bez wspólnego indeksu. Od teraz:

| Plan | Rola | Gdzie |
|------|------|--------|
| **architecture v5** | **Idealny protokół plików i faz fabryki** (strategic + assembly) | [legacy/…/architecture_v5.md](../legacy/v2_monolith/examples/toy-projekt-gema0/.gema0/docs/architecture_v5.md) |
| **V10 APEX** | **Implementacja warstwy ASSEMBLY w kodzie** (misja HTTP, rój, sędzia, graft) | `backend/`, [00_GEMA0_ULTIMATE_MASTERPLAN.md](00_GEMA0_ULTIMATE_MASTERPLAN.md) |
| **State Amnesia** | Pętla Cursor / panel / supervisor (pliki `10`…`40`) | [legacy/…/CONTRACT.md](../legacy/v2_monolith/workspace-notes.example/CONTRACT.md) |
| **Endgame RPA** | Wizja długoterminowa (Cursor loop, multi-model) — **archiwum** | [legacy/_docs-archive/gema0_ultimate_architecture.md](../legacy/_docs-archive/gema0_ultimate_architecture.md) |

**Zasada dla agentów:** v5 opisuje **co i gdzie na dysku**; V10 masterplan opisuje **jak działa silnik** w `backend/`. Nie traktuj masterplanu jako zamiennika v5 ani odwrotnie.

---

## Diagram: trzy tory (nie jeden plan)

```mermaid
flowchart TB
  subgraph v5 [Tor C — architecture v5]
    STR[".gema0/strategic/"]
    ASM[".gema0/assembly/job_id/"]
    OH5["orchestrate-handoff.mjs legacy"]
    STR --> ASM --> OH5
  end

  subgraph sa [Tory A/B — State Amnesia]
    F10["10_step_current.md"]
    F20["20_agent_report.md"]
    SUP["supervisor + PUSH Cursor"]
    F10 --> F20 --> SUP
  end

  subgraph v10 [V10 APEX — aktywny kod]
    API["POST /api/mission"]
    ORC["backend/core/orchestrator.mjs"]
    EVT["events.ndjson → WebSocket → UI"]
    API --> ORC --> EVT
  end

  v5 -.->|"ASSEMBLY_LOOP → kod V10"| v10
  sa -.->|"osobna pętla, legacy"| v5
```

Lekcja `toy-projekt-gema0` opisuje to jawnie: [START.md](../legacy/v2_monolith/examples/toy-projekt-gema0/START.md) (tory A / B / C).

---

## Hierarchia prawdy

1. **Zapis i transformacja plików (fabryka)** → **architecture v5**  
2. **Działający silnik misji (JS, API, UI)** → **V10** (`backend/`, `frontend/sequencer-ui/`)  
3. **Panel RPA + automatyczny handoff do Cursora** → **legacy v2_monolith** (nie rozwijać jako V10)  
4. **Roadmapa checkboxów UI/backend** → [00_GEMA0_ULTIMATE_MASTERPLAN.md](00_GEMA0_ULTIMATE_MASTERPLAN.md) — **podlega** mapie v5↔V10 z tego pliku

---

## Mapowanie 1:1 — fazy v5 → kod V10

| Faza v5 | Opis (v5) | V10 — moduł / plik | Stan |
|---------|-----------|-------------------|------|
| `AWAITING_MANIFEST` | Czeka na intake użytkownika | Brak — misja startuje z `POST /api/mission` lub `test_first_run.mjs` | 🔧 brak warstwy strategic |
| `BLUEPRINTING` | Architekt → `strategic/` | Brak — `oraclePrompt` ręcznie w JSON misji | 🔧 brak Tree-sitter / auto Oracle |
| `ASSEMBLY_LOOP` | Tani model wypełnia szkielet | `shotgunSwarm.mjs` + `orchestrator.mjs` | ✅ |
| `MECHANICAL_VERIFY` | `verify_cmd` z `30_mechanical_gate.json` | `phantomVM.mjs` + opcjonalnie `traceExpectations` | ⚠️ częściowo (Phantom, nie JSON gate) |
| `SEMANTIC_AUDIT` | Drogi model + `git diff` | Brak | 🔧 |
| `COMMITTED` | Zapis do `DECISIONS.md` | `graftFunctionBody` zapisuje plik; brak `DECISIONS.md` | ⚠️ częściowo |

**Orchestrator v5:** `legacy/v2_monolith/tools/orchestrate-handoff.mjs` (State Amnesia + opcjonalnie pilot).  
**Orchestrator V10:** `backend/core/orchestrator.mjs` — **osobny proces**, bez importów z `legacy/`.

---

## Mapowanie 2 — pliki v5 → odpowiednik V10

| Plik / koncept v5 | Ścieżka wzorcowa (legacy) | Odpowiednik V10 |
|-------------------|---------------------------|-----------------|
| `10_skeleton_target.md` | `assembly/PILOT-001/10_skeleton_target.md` | `extractFunctionSkeleton()` w `ast_grafter.mjs` — szkielet z **pliku `.js`**, nie z `.md` |
| `20_agent_report.md` | `assembly/…/20_agent_report.md` | Zdarzenia `AGENT_FAILED` / log błędu w `events.ndjson`; brak pliku raportu |
| `30_mechanical_gate.json` | `assembly/PILOT-001/30_mechanical_gate.json` | `validationArgs` + `traceExpectations` w body misji; Phantom zamiast `execa verify_cmd` |
| `40_auditor_verdict.md` | `assembly/…/40_auditor_verdict.md` | Brak |
| `.lock` | `assembly/PILOT-001/.lock` | Kolejka misji w `server.mjs` (FIFO) — częściowy odpowiednik |
| `00_manifest.md` … `02_blueprint.md` | `.gema0/strategic/` | Brak — planowane pod przyszły Oracle |
| `DECISIONS.md` | `strategic/DECISIONS.md` | Brak |

Przykład bramki v5 (`verify_cmd: npm test`):  
`legacy/v2_monolith/examples/toy-projekt-gema0/.gema0/assembly/PILOT-001/30_mechanical_gate.json`

Przykład bramki V10 (ślad I/O):

```json
"traceExpectations": {
  "calls": [{ "path": "api.charge", "argMatch": { "tenant_id": "PROJECT-A" } }]
}
```

Źródło: [examples/first-test/README.md](../examples/first-test/README.md), `backend/core/test_first_run.mjs`.

---

## Co się pomieszało (historia — nie powtarzać)

| Błąd | Fakt |
|------|------|
| „v5 usunięto z gita” | **Przeniesiono** do `legacy/v2_monolith/examples/toy-projekt-gema0/` (commit `0c0c098`) |
| Jeden plan GEMA-0 | Są **trzy tory** + **V10 jako silnik** — patrz diagram wyżej |
| Masterplan = v5 | Masterplan dodaje **Tree-sitter, NLE, APEX** — to warstwa **implementacji**, nie zastępuje topologii `.gema0/` z v5 |
| Jeden orchestrator | **Dwa:** `orchestrate-handoff.mjs` (legacy) i `orchestrator.mjs` (V10) — mostu jeszcze nie ma |

---

## Granice (co gdzie rozwijać)

| Obszar | Rozwijaj w | Nie mieszaj z |
|--------|------------|---------------|
| Silnik misji, Phantom, Swarm, graft | `backend/` | import z `legacy/` |
| UI NLE, WebSocket | `frontend/sequencer-ui/` | panel HTML monolitu |
| Protokół plików v5 (dokumentacja + pilot) | `legacy/…/toy-projekt-gema0/.gema0/` | nie przenoś do root bez decyzji właściciela |
| State Amnesia, supervisor, PUSH | `legacy/v2_monolith/` | `backend/server.mjs` V10 |

---

## Kierunek zbieżności (roadmapa techniczna, nie zobowiązanie)

Kolejność sensowna, jeśli V10 ma **dogonić** v5 bez psucia tego, co działa:

1. **Adapter `30_mechanical_gate.json`** — odczyt gate z folderu assembly → Phantom + opcjonalnie `execa(verify_cmd)`  
2. **Most assembly → misja** — watcher lub CLI: pliki `10_skeleton` + gate → `POST /api/mission`  
3. **`SEMANTIC_AUDIT`** — moduł diff + opcjonalny LLM przed `COMMITTED`  
4. **Warstwa `strategic/`** — auto Oracle (Tree-sitter lub tańszy ekstraktor sygnatur)  
5. **Zapis `20_agent_report.md` / `40_auditor_verdict.md`** z eventów misji (opcjonalnie, dla zgodności z v5)

Szczegóły checkboxów UI/backend: [00_GEMA0_ULTIMATE_MASTERPLAN.md](00_GEMA0_ULTIMATE_MASTERPLAN.md), [AGENT_LOG.md](AGENT_LOG.md).

---

## Indeks ścieżek (szybkie linki)

| Dokument | Ścieżka |
|----------|---------|
| **architecture v5** (ideal plików) | `legacy/v2_monolith/examples/toy-projekt-gema0/.gema0/docs/architecture_v5.md` |
| Pilot assembly PILOT-001 | `legacy/v2_monolith/examples/toy-projekt-gema0/.gema0/assembly/PILOT-001/` |
| strategic/ (manifest, blueprint) | `legacy/v2_monolith/examples/toy-projekt-gema0/.gema0/strategic/` |
| Trzy tory lekcji | `legacy/v2_monolith/examples/toy-projekt-gema0/START.md` |
| State Amnesia CONTRACT | `legacy/v2_monolith/workspace-notes.example/CONTRACT.md` |
| V10 masterplan | `_docs/00_GEMA0_ULTIMATE_MASTERPLAN.md` |
| UI NLE | `_docs/02_WIZJA_FRONTEND_NLE_SEQUENCER.md` |
| Pierwszy test E2E V10 | `examples/first-test/README.md` |
| Legacy monolit | `legacy/v2_monolith/README_ARCHIWUM.md` |
| Endgame (archiwum) | `legacy/_docs-archive/gema0_ultimate_architecture.md` |
| **Planowanie Red Team V7–V9 (odtworzone)** | `_docs/archive/PLANOWANIE_PRZED_V10/` |

---

*Czytaj ten plik na początku sesji, gdy zadanie dotyczy fabryki plików, v5, legacy lub spójności dokumentacji.*