# Uživatelský postup výzkumu a vylepšování kódu — CyberBrain26 + Kilo

**Datum:** 2026-10-20  
**Stav:** Aktuální po explicitní allowlist opravě (`orchestrator.md`), 62/62 Gate 0 testů zelených, `ruff` čistý.  
**Autorita:** `.kilo/plans/CyberBrain26cil-031026-v2.md`, `.kilo/context/LESSONS_AND_DECISIONS.md`, `AGENTS.md`, `.kilo/agent/orchestrator.md` (delegační matice).

---

## 1. Vstupní bod — jak začít jakoukoliv práci

```bash
cd /home/oem/CyberBrain26-v4
# 1. Baseline: zelené deterministické brány (Gate 1)
python3 -m pytest -q          # 591 passed / 10.23 s (2026-10-03 měření)
python3 -m ruff check         # All checks passed
python3 -m mypy src/          # 7 známých chyb v embedding_service.py, vector_store.py — nesouvisí s našimi změnami

# 2. Kontrola, že nikdo jiný nepracuje v repu (LESSONS V9)
ps -eo pid,etimes,cmd --sort=start_time | grep -Ei "kilo|claude" | grep -v grep
find . -path ./.git -prune -o -type f -newermt '-15 minutes' -print
```

**Příkaz pro rychlou kontrolu stavu:** `python3 -m pytest -q tests/test_kilo_agent_policy.py` (62 passed / 0.5 s).

---

## 2. Typy úloh a jejich pipeline (dle orchestrátora §Standardní workflow)

| Typ úlohy | Pipeline (sekvence agentů) | Poznámka |
|---|---|---|
| **Nová schopnost / feature** | `deep-research` → `threat-modeler` → `code-reviewer` (návrh) → **schválení vlastníka** → `implementer` (diff → schválení → zápis) → `tester` Gate 2 → `code-reviewer` → `verifier` → `documenter` → `CHANGELOG.md` | Zápis do `src/`, `tests/` vyžaduje schválení |
| **Bezpečnostní změna** | `security-auditor` (první, najdi slabiny) → `threat-modeler` → schválení → `implementer` → `tester` Gate 2 → `security-auditor` (revize) → `verifier` (fail-closed potvrzení) → `documenter` | `security-auditor` spustit dřív než `implementer` |
| **Výzkum / design bez zápisu** | `deep-research` → `threat-modeler` → `pricing-researcher` → `code-reviewer` → předání ownerovi | Nic se nezapisuje do `src/` |
| **Údržba konfigurace / agentů** | `code-reviewer` (revize diffu) → `tester` (validační brány) → `verifier` | Zápis do `.kilo/agent/*.md`, `.kilo/context/**` bez schválení; `.kilo/kilo.jsonc` **vyžaduje schválení** |
| **Peníze a produkt** | `pricing-researcher` (reálné + [SIMULOVANÉ]) → `deep-research` (trh) → předání ownerovi | Žádné rozhodnutí bez vlastníka |
| **Dokumentace a roadmapy** | `documenter` → `verifier` (konzistence s kódem) → `CHANGELOG.md` | |

---

## 3. Jak vytvořit artefakt pro delegaci (povinný formát)

Každému subagentovi předáváš **artefakt**, nikoli volný prompt. Minimální obsah:

```
CÍL: <jedna věta, co se má udělat>
ROZSAH: <konkrétní soubory/adresáře, např. src/cyberbrain26/security_plane/actions.py:242-272>
KRITÉRIA PŘÍJMU: <co musí být splněno, měřitelně>
DECLARED_ACTIONS: <seznam akcí ze slovníku ACTION_SCOPE_REQUIREMENTS>
ZAKÁZANÉ ZMĚNY: <co se nesmí dotknout>
OWNER_ROLE: <jméno jediného vlastníka tohoto kroku, povinné>
TVRZENÍ K OVĚŘENÍ:
  - [OVĚŘENO] <file:line> nebo výstup příkazu
  - [HYPOTÉZA] <co není ověřeno>
```

**Cross-check před spuštěním (povinné):** Ověř každou akci z `DECLARED_ACTIONS` přes `cyberbrain26_check_vocabulary` / `cyberbrain26_list_actions`. Jsou-li MCP nástroje nedostupné (`mcp.cyberbrain26.enabled: false`), použij **offline náhradu** — přečti `src/cyberbrain26/security_plane/actions.py:242-272` (`ACTION_SCOPE_REQUIREMENTS`). Pokud akce chybí → **subagenta nespouštěj**, vrať se k vlastníkovi.

---

## 4. Delegace — explicitní allowlist (nově opraveno)

Orchestrátor má v frontmatteru **explicitní allowlist 10 subagentů** (nikoliv wildcard `{"*": "allow"}`):

```yaml
task:
  "deep-research": allow
  "threat-modeler": allow
  "security-auditor": allow
  "pricing-researcher": allow
  "code-reviewer": allow
  "verifier": allow
  "documenter": allow
  "implementer": allow
  "tester": allow
  "gate3-auditor": allow
```

**Pravidla:**
- `subagent_depth: 1` → žádný subagent nesmí delegovat dál (runtime pojistka).
- `overseer`, `scout` nejsou v allowlistu → **nedelegovatelné** (deny-by-default).
- `implementer` smí delegovat **pouze na `tester`** (explicitní záznam v `AGENT_DELEGATION_ALLOWLIST`).

---

## 5. Brány — co spouštět a kdy

| Brána | Co dělá | Kdy | Příkaz |
|---|---|---|---|
| **Gate 1** | Deterministický baseline **před** změnou: pytest, ruff, mypy, fail-closed test | Před jakoukoliv úpravou kódu/konfigurace | `python3 -m pytest -q && python3 -m ruff check && python3 -m mypy src/` |
| **Gate 2** | Totéž + diff + coverage **po** změně | Po změně, před `code-reviewer`/`verifier` | Stejné + `git diff --stat` |
| **Gate 3** | LLM-as-judge s **jiným** modelem, **až po** Gate 1+2 | Nikdy jako první brána | Spustí `gate3-auditor` (vyžaduje `bash: allow` v Task tool — momentálně nepokryté, stav `NEPROVEDENO`) |

**Důležité:** V Gate 1/2 **nikdy neuváděj** `semgrep` ani „hash audit chainu" — v repu neexistují (LESSONS V8, V17).

---

## 6. Slovník důvodů odmítnutí (používej verbatim)

| Kód | Znamená | Co dál |
|---|---|---|
| `REJECT_UNVERIFIED` | tvrzení bez `file:line` nebo výstupu příkazu | autor dohledá důkaz |
| `REJECT_SCOPE_MISSING` | `declared_actions` mimo `ACTION_SCOPE_REQUIREMENTS` | rozšířit slovník akcí, nebo zúžit úkol |
| `REJECT_CONTEXT_MISMATCH` | výstup neřeší zadání | nový brief, jiný owner |
| `REJECT_GATE_RED` | Gate 1 nebo Gate 2 červená | nejprve opravit bránu |
| `REJECT_SECURITY_FINDING` | `security-auditor`/`threat-modeler` našel nález | mitigace, pak nová revize |
| `REJECT_EXTERNAL_DEPENDENCY` | výstup závisí na tom, co v repu není | změnit zadání |
| `REJECT_HYPOTHESIS_ONLY` | výstup neprošel důkazem, jen odhadem | autor dohledá artefakt |
| `REJECT_SUPERSEDED` | mezitím vznikla novější revize | owner rozhodne, která platí |

---

## 7. Report vlastníkovi (povinný formát na konci každého kroku)

```
Stav: <co je hotové / co visí>
Rozhodnutí potřebuje: <ANO/NE> — <konkrétní volba A/B/C/D>
Agenti: <kdo byl spuštěn a s jakým výsledkem>
Brány: Gate 1 <zelená/červená> / Gate 2 <zelená/červená> / Gate 3 <provedena/ne>
Otevřené body: <rizika, [HYPOTÉZA], co nebylo ověřeno>
```

**Pravidla:**
- Nikdy neprezentuj `[HYPOTÉZA]` jako `[OVĚŘENO]`.
- `[SIMULOVANÉ]` peníze musí být vždy označeno.
- Pokud brána neproběhla, napiš to, ne mlč.
- Vlastník je konečná autorita — jeho slovo má přednost před plánem.

---

## 8. Limity, které nesmíš překročit

- **Fan-out:** max **4 souběžné background subagenty** na krok.
- **Retry:** **nikdy** neposílej znovu krok, který selhal *až po* rozběhnutí kódu (D2 invariant, `retry_blocked` to odmítá).
- **Dead-letter:** práce, která se 2× neopraví, předáš vlastníkovi jako otevřený bod.
- **Jeden krok = jeden soubor nebo jeden adresář.**

---

## 9. Typické chyby a jak se jim vyhnout (LESSONS_AND_DECISIONS.md)

| Vzor | Prevence |
|---|---|
| **V1** Neparseovatelný frontmatter | V `.kilo/agent/*.md` citovat `description` s `: ` uvnitř; helper musí `try/except yaml.YAMLError` |
| **V2** Wildcard zruší test | Nikdy nepoužívej `{"*": "allow"}` v allowlistech; testy musí `assert allowlist and "*" not in allowlist` |
| **V3** `[OVĚŘENO]` bez artefaktu | `[OVĚŘENO]` jen s uloženým `file:line` nebo výstupem příkazu v repu |
| **V4** Stará čísla v dokumentech | K číslu patří **datum + přesný příkaz + kolekce testů** |
| **V5** `git log` není jediný zdroj | Hledej i v `.git/refs/`, `.git/logs/HEAD`, `.git/worktrees/` |
| **V6** Grep jako důkaz neexistence | Dva kroky: (a) kladný grep na funkci, (b) popis proč nález není to ono |
| **V7** Stručné tvrzení silnější než důkaz | Tvrzení o architektuře = tak široké, jak je implementace |
| **V8** Jmenovaná brána bez kroku v CI | Každá jmenovaná brána musí mít krok v `.github/workflows/ci.yml` |
| **V9** Před každou prací prověřit konflikt | `ps -eo ... | grep kilo` + `find -newermt '-15 minutes'` |
| **V10** Izolační tvrzení jen čtením argv | Ověř spuštěním sandboxu (viditelné procesy, síť, `/proc`) |
| **V17** Hash audit chain jako duch | Chain v repu neexistuje → nejmenovat v Gate 1/2; autorovo hlášení nesmí jít do vstupu kontrolora |

---

## 10. Rychlý reference — klíčové soubory

| Soubor | Účel |
|---|---|
| `.kilo/plans/CyberBrain26cil-031026-v2.md` | **Autoritativní plán** (bez `status: superseded`) |
| `.kilo/context/LESSONS_AND_DECISIONS.md` | Vzorce chyb V1–V17 + rozhodnutí vlastníka |
| `.kilo/agent/orchestrator.md` | Delegační matice, workflow, report, pravidla (10 subagentů) |
| `AGENTS.md` | Pravidla orchestrace, delegace, report, security |
| `tests/test_kilo_agent_policy.py` | Gate 0 — 62 deterministických testů politiky |
| `src/cyberbrain26/security_plane/actions.py:242-272` | `ACTION_SCOPE_REQUIREMENTS` (offline slovník pro cross-check) |
| `.kilo/kilo.jsonc` | Globální config: `subagent_depth: 1`, `mcp.cyberbrain26.enabled: false`, permission baseline |

---

## 11. Příklad: přidání nové schopnosti (end-to-end)

1. **Gate 1** — spusť baseline, ulož výstup.
2. **Artefakt pro `deep-research`** — cíl: "zkoumej knihovnu X pro Y", rozsah: `src/...`, declared_actions: `["read", "grep", "webfetch"]`, owner: `orchestrator`.
3. **Cross-check** — ověř akce v `ACTION_SCOPE_REQUIREMENTS`.
4. **Spusť `deep-research`** (background).
5. **Po výstupu** — `threat-modeler` se stejným artefaktem + nálezy z výzkumu.
6. **Schválení vlastníka** — ukaž diff návrhu, počkej na ANO.
7. **`implementer`** — první krok **pouze diff** k odsouhlasení.
8. **Po schválení** — aplikace, `tester` Gate 2, `code-reviewer`, `verifier`.
9. **`documenter`** — aktualizuj docs, `CHANGELOG.md`.
10. **Report vlastníkovi** — formát §7.

---

## 12. Co dělat, když pravidlo selhalo

```
REJECT_UNVERIFIED → nový brief + jiný owner (nikdy nepřepisovat zadání)
REJECT_GATE_RED → oprav bránu dřív než pokračuješ
REJECT_SECURITY_FINDING → mitigace → nová revize
Agent selhal 2× po sobě → orchestrátor přebírá práci sám, označené [OVĚŘENO] jen tam, kde sám naměřil
```

**Základní pravidlo (vlastník 2026-10-04):** Když agenti pracují, **já dělám výzkum nebo jinou práci, která jim pomůže příště**. Nečekám prázdně.

---

## 13. Značky v dokumentech (používej konzistentně)

| Značka | Význam |
|---|---|
| `[OVĚŘENO]` | důkaz `file:line` v repu, nebo výstup příkazu uložený v repu |
| `[VÝZKUM]` | veřejný zdroj s URL a datem přístupu |
| `[NÁVRH]` | navržené, neschválené řešení |
| `[HYPOTÉZA]` | nedomyšleno; bez artefaktu |
| `[SIMULOVANÉ]` | výstup generátoru, ne reálný rozhovor |

**Nikdy nesmíš** prezentovat `[HYPOTÉZA]` nebo `[SIMULOVANÉ]` jako `[OVĚŘENO]`.

---

## 14. Aktuální stav (2026-10-20) — po explicitní allowlist opravě

- **Gate 0:** 62/62 passed (`pokryto: 10/10` allowlist agentů)
- **Lint/Typecheck:** `ruff` clean, `mypy` 7 známých chyb (předdefinované)
- **MCP:** `cyberbrain26: { enabled: false }` — fail-closed, server v repu neexistuje
- **Delegační matice:** 10 subagentů v explicitním allowlistu, `overseer`/`scout` mimo
- **Otevřené body (LESSONS §3):** 16 bodů — nejvýrazně V2 (opraveno), V1, V8, V11–V16

---

*Příloha: tento dokument se ukládá do `.kilo/context/USER_WORKFLOW_RESEARCH_IMPROVEMENT.md` (zápis do `.kilo/context/**` nevyžaduje schválení vlastníka per AGENTS.md). Pro revizi: `code-reviewer` → `tester` → `verifier` → `documenter`.*