# Orchestrátor — komplexní implementační plán (sjednocený)

**Datum:** 3. 11. 2026  
**Stav:** Připraveno k implementaci  
**Autoritativní plán:** `.kilo/plans/CyberBrain26cil-031026-v2.md` (beze změny cíle)  
**Nadřazené plány:** `1793713720824-audit-fixes-implementation.md`, `1793714960761-gate3-implementation.md`, `1793689484676-orchestrator-parallel-3layer-execution.md`, `1793689484676-planner-autonomous-execution-plan.md`, `1793806517-r3-gate2-gate3-plan.md`  
**HARDCOREDEEPWEBRESEARCH:** Srovnání s deep-web-research metodikou viz oddíl 3  

---

## 1. Cíl

Jeden sjednocený plán pro Orchestrátora, který:
- Dokončí F2 fázi (minimal complete agent flow) — R1–R5 hotové, Gate 1/2 zelené
- Uvolní Gate 3 (nezávislá verifikace jiným modelem `dolphin-cb26:latest`)
- Zapojí `deep-research` pro rozhodování při nejistotě (HARDCOREDEEPWEBRESEARCH)
- Zachová 3vrstvou delegační strukturu (orchestrátor → subagent → sub-subagent) s `subagent_depth: 3`
- Respektuje konfiguraci indexing/memory/knowledgebase z `.kilo/kilo.jsonc` (1TB disk, Ollama embedding, vektorový store)
- Orchestrátor nikdy sám nekoná (D6 invariant, `orchestrator_never_does_work_itself`)

---

## 2. Současný stav (ověřeno)

| Komponenta | Stav | Důkaz |
|------------|------|-------|
| R1 Embedding API | DOKONČENO | `embedding_service.py:35,55` |
| R2 Test izolace | DOKONČENO | `tests/conftest.py` |
| R3 llama.cpp proxy (port 8080) | DOKONČENO | `llama_cpp_server_proxy.py` běží na 8080 |
| R4 Customer discovery | DOKONČENO | 23 zdroje, 4 segmenty |
| R5 Audit chain HMAC | DOKONČENO | `chain.py` — `compute_event_hash()` |
| Gate 1 | ZELENÁ | 764 passed, ruff clean, mypy clean |
| Gate 2 | ZELENÁ | 763 passed, ruff clean, mypy clean |
| Gate 3 | BLOKOVÁNO | `gate3-auditor` typ není v Task toolu |
| `subagent_depth` | 3 | `.kilo/kilo.jsonc:6` (schváleno vlastníkem) |
| Indexing | enabled | `.kilo/kilo.jsonc:107-123`, model `dolphin-mistral:latest`, dim 102400 |
| MCP cyberbrain26 | enabled: false | `.kilo/kilo.jsonc:105` |

---

## 3. HARDCOREDEEPWEBRESEARCH — srovnání a rozhodnutí

Deep-web-research metodiky (8fázová pipeline, triangulace, synthesis) porovnány s existujícím `deep-research` subagentem:

| HARDCOREDEEPWEBRESEARCH prvek | Existující řešení CyberBrain26 | Rozhodnutí |
|-------------------------------|-------------------------------|------------|
| Webový výzkum (URL, datum přístupu) | `deep-research` subagent, read-only, `bash: deny` | **Zachovat** — URL musí mít datum přístupu a HTTP status |
| Triangulace (vícero nezávislých zdrojů) | Žádná explicitní povinnost | **Přidat** — minimálně 2 nezávislé zdroje pro každé faktické tvrzení |
| Synthesis (syntéza do rozhodnutí) | Orchestrátor syntetizuje výstup `deep-research` | **Zachovat** — orchestrátor je jediný sintetizér |
| [VÝZKUM]/[HYPOTÉZA]/[NEOVĚŘENO] značení | Už definováno v `deep-research.md` | **Zachovat** — tvrdá podmínka |
| `bash` pro ověření URL (`curl`) | `bash: deny` blokuje ověření | **Změnit** na `bash: allow` (read-only `curl`, žádný zápis) — schváleno v `1793700000000-orchestrator-delegation-plan.md` |
| Pravidelný monitoring (periodické cykly) | Žádná scheduled úloha | **Režim na vyžádání** (F3+), ne v tomto plánu |

**Kdy spustit deep-research:** Kdykoli orchestrátor nebo libovolný subagent nemá ověřený důkaz (`file:line` nebo výstup příkazu) pro rozhodovací fakt, nebo narazí na doménu mimo svou chartu.

---

## 4. Delegační matice a 3vrstvá struktura

### Vrstva 1 — Orchestrátor (jediný primární delegátor)
- `mode: primary`, `task: allow` pro 10 subagentů (dle `.kilo/agent/orchestrator.md`)
- Nikdy sám nekoná, vždy deleguje artefát konkrétnímu subagentovi
- Frontmatter v `kilo.jsonc` má přednost před `.md` frontmatterem

### Vrstva 2 — Subagenty (spuštěny orchestrátorem)
- Maximálně 4 souběžné (fan-out limit)
- Každý má `owner_role` — právě jednoho vlastníka
- Vlastní kontext a vlastní `declared_actions`

### Vrstva 3 — Sub-subagenty (spuštěny vrstvou 2)
- Pouze pokud `subagent_depth: 3` povoleno (již je)
- Použito pro deep-verifikaci a cross-checky
- Hard limit hloubky 3, žádná rekurze přes 3 úrovně

### Povinný cross-check před spuštěním subagenta
Ověřit `declared_actions` proti `ACTION_SCOPE_REQUIREMENTS` (`src/cyberbrain26/security_plane/actions.py:242-272`). Pokud akce chybí → subagenta nespouštět, vrátit se k PromptMasterovi/vlastníkovi.

---

## 5. Indexing / Memory / Knowledgebase (konfigurace z kilo.jsonc)

### Indexing (již povoleno)
- `enabled: true`, model `dolphin-mistral:latest`, dim 102400
- Ollama base URL: `http://localhost:11434`
- File extensions: `.json`, `.md`, `.py`, `.pyi`, `.toml`, `.yaml`, `.yml`
- Fyzické úložiště: 1TB disk (`/home/oem/...`), vektorové indexy persisting na disku

### Memory (trvalá paměť)
- `kilo-memory-v1` persistentní bloky (scope: project)
- Ukládá klíčová rozhodnutí, opravy, stav projektů
- `kilo_memory_recall` pro dotazování, `kilo_memory_save` pro ukládání

### Knowledgebase (sémantický index)
- Vektorová databáze přes Ollama embeddings (`qwen3-embedding:0.6b`, dim 1024)
- Sémantické vyhledávání (ne jen klíčová slova)
- Knowledge plane: `src/cyberbrain26/knowledge_plane/` — contracts, repository, vector store, embedding service

### Testovací scénáře (pro ověření fungování)
1. **Memory integrity:** Zapsat token do paměti, restartovat session, ověřit prostřednictvím `kilo_memory_recall`
2. **Sémantické indexování:** Vložit kód s unikátní funkcí, dotazovat se sémanticky blízkým dotazem (bez klíčových slov z kódu), ověřit nálezení
3. **Persistence:** Indexování dat → kill procesu → restart → ověřit, že index je načten z disku
4. **Aktualizace:** Změnit kód → re-indexing → dotaz vrací novou verzi

---

## 6. Pořadí kroků (pro implementační agenta)

### Fáze A — Gate 1 (před jakoukoli změnou, již splněno)
1. `tester` spustí `pytest -q`, `ruff check`, `mypy src/cyberbrain26` — zelená baseline (764 passed)
2. `security-auditor` ověří fail-closed řetězec (identity → policy → permission → approval → sandbox → audit)

### Fáze B — Gate 2 (již splněno, potvrdit)
3. `tester` spustí `pytest -q`, `ruff check`, `mypy src/cyberbrain26` — zelená po změnách (763 passed)
4. `code-reviewer` zkontroluje diffy všech audit fixů (R1–R10 z `1793713720824-audit-fixes-implementation.md`)
5. Receipt kontrola: `git status --porcelain`, `grep -c` na klíčové řádky, `cat -A` na whitespace

### Fáze C — Gate 3 (hlavní úkol tohoto plánu)
6. **Vyřešit `gate3-auditor` typ** (blokátor):
   - Přidat `gate3-auditor` do Task tool subagent typů (platformová změna mimo tento repo)
   - Pokud není možné: oznámit vlastníka, Gate 3 = `NEPROVEDENO` s odůvodněním
   - Alternativa: použít jiného agenta s `bash: allow` pro výběrový pytest běh (ale porušuje Gate 3 definici LLM-as-judge s jiným modelem)

7. **Připravit Gate 3 artefakt** (orchestrátor):
   - Cíl jednou větou
   - Přesný rozsah (soubory/adresáře, mimo `security_plane/`, `execution_plane/`, `pilot/`, `knowledge_plane/`)
   - Kritéria přijetí
   - `declared_actions` pro cross-check
   - Co se NESMÍ měnit
   - `owner_role` — právě jeden vlastník
   - Tvrzení k ověření — jedno tvrzení = jeden řádek, formát `[OVĚŘENO]`/[HYPOTÉZA]

8. **Spustit Gate 3** (orchestrátor → `gate3-auditor`, `background: true`):
   - `gate3-auditor` spustí `pytest` pro zadané vlastnosti
   - Zapíše doslovný výstup (poslední řádek pytestu)
   - Vydá verdikt: `PASS` | `FAIL` | `REJECT_UNVERIFIED`
   - Každé tvrzení: `[OVĚŘENO]` s `file:line`, nebo `[NEOVĚŘENO]`
   - Není povoleno: analyzovat kód, vracet šablonu, odhadovat

9. **Report vlastníkovi** (orchestrátor):
   - Stav: `provedena` / `ne` s odůvodněním
   - Formát dle `orchestrator.md`: Stav, Rozhodnutí potřebuje, Agenti, Brány, Otevřené body
   - Značení: `[OVĚŘENO]` / `[HYPOTÉZA]` / `[SIMULOVANÉ]`

### Fáze D — Deep-research integrace (během celého plánu)
10. Kdykoli agent nemá ověřený důkaz: spustit `deep-research` s anglickým dotazem + kritérii + český závěr
11. Výstup: URL + datum přístupu, [VÝZKUM]/[HYPOTÉZA]/[NEOVĚŘENO]
12. Orchestrátor vybere nejvhodnější postup na základě výzkumu

---

## 7. Validace (kritéria přijetí)

| Brána | Kritérium | Jak ověřit |
|-------|-----------|------------|
| Gate 1 | Všechny quality gates zelené | `pytest -q` + `ruff check` + `mypy` exit code 0 |
| Gate 1 | Fail-closed bezpečnostní řetězec | `ExecutionRefused` / `SecurityError` na chybějící schválení |
| Gate 2 | Zelená po změnách | Stejné příkazy po aplikaci diffů |
| Gate 2 | Diffy schváleny | `code-reviewer` potvrdí diffy |
| Gate 2 | Receipt kontrola | Jeden příkaz potvrdí všechny body receiptu |
| Gate 3 | Nezávislá verifikace | `gate3-auditor` verdikt PASS/FAIL/REJECT_UNVERIFIED |
| Gate 3 | Jiný model než vývoj | `dolphin-cb26:latest` místo `phi3.5:latest` |
| Gate 3 | Výstup je doslovný | `pytest` výstup bez šablon, bez placeholderů |
| Deep-research | Každé tvrzení má URL + datum | Ruční kontrola výstupu `deep-research` |
| Indexing | Vektorový store funguje | Sémantický dotaz vrátí relevantní kód |
| Memory | Paměť přetrvává přes session | `kilo_memory_recall` najde uložený token |

---

## 8. Rizika a pojistky

| Riziko | Původ | Mitigace |
|--------|-------|----------|
| `gate3-auditor` typ nepřidán | Platformová limita, mimo tento repo | Oznámit vlastníka, Gate 3 = `NEPROVEDENO` |
| `subagent_depth: 3` porušuje D6 | Vlastník explícitně schválil | Maximální povolená hloubka 3, není unbounded |
| `deep-research` s `bash` může spustit nebezpečný příkaz | Omezení na read-only `curl` | Žádný zápis, žádná exekuce, `edit: deny` zůstává |
| Tři vrstvy vytvoří hlubokou rekurzi | Hard limit 3 úrovně, fan-out max 4, `doom_loop: deny` | Vynuceno v `kilo.jsonc` |
| LLM-as-judge bias | Jeden model nemusí rozpoznat špatnou práci | Jeden rozpor s výstupem příkazu = `REJECT_UNVERIFIED` |
| gate3-auditor poruší chartu | Vrací šablonu nebo placeholder | Orchestrátor odmítne výsledek, vrátí k vlastníkovi |
| Tvrzení bez `file:line` | Agent behauptuje bez důkazu | `REJECT_UNVERIFIED` |

---

## 9. Otevřená rozhodnutí (potřebuje vlastníka)

1. **Gate 3 agent typ:** Je možné přidat `gate3-auditor` do Task tool subagent typů? Pokud ne, jaká je alternativní cesta?
2. **Model pro Gate 3:** Potvrzuje se použití `dolphin-cb26:latest` pro Gate 3 LLM-as-judge?
3. **Vlastnosti pro Gate 3:** Má vlastník konkrétní seznam vlastností (P1–Pn), nebo má orchestrátor připravit návrh?
4. **deep-research bash:** Schvaluje se změna `bash: deny` → `bash: allow` (pouze read-only `curl`) pro ověření URL?

---

## 10. Další krok

Plán je připraven k implementaci. Implementační agent (orchestrátor nebo implementer s `bash`/`edit` oprávněními) začne Fází A → B → C dle delegační matice v `.kilo/agent/orchestrator.md`. Nejprve zajistit schválení vlastníka pro otevřená rozhodnutí (oddíl 9).