# CyberBrain26 V5 — záznam produktových rozhodnutí **Stav:** záznam schválených produktových rozhodnutí. Dokument neobsahuje žádné nové technické tvrzení; odkazuje na stav ověřený v [bezpečnostním listu](../SECURITY_ONE_PAGER.md) a v `PROJECT_STATUS.md`. **První záznam:** 2. října 2026 **Formát:** jedno rozhodnutí = jeden záznam s datem, rozhodnutím, kdo rozhodl, zdůvodněním, dopadem, tím co výslovně nerozhodnuto, a postupem pro revizi. > **Rozsah platnosti.** Záznamy zde platí pro CyberBrain Agent Guard (viz [product brief](PRODUCT_BRIEF_V5.md)). Nic zde nepotvrzuje trh ani bezpečnostní tvrzení. Veškerá bezpečnostní tvrzení zůstávají omezena na to, co je ověřeno v kódu a uvedeno v [bezpečnostním listu](../SECURITY_ONE_PAGER.md); Bubblewrap zde není a nebude popsán jako ochrana proti libovolnému nepřátelskému kódu. --- ## D1 — Podporovaný OS: Ubuntu 24.04 LTS | Položka | Hodnota | |---|---| | **Datum rozhodnutí** | 2. října 2026 | | **Stav** | **Rozhodnuto, čeká na implementaci** (packaging + CI) | | **Rozhodl** | Vlastník projektu (majitel produktu) | | **Oblast** | Podporovaná platforma / Etapa 1 krok 4 roadmapy | | **Nahrazuje otevřenou položku** | `MVP_GAP_ANALYSIS_V5.md` řádek „Installation and supported environment“; `ROADMAP_V5.md` Etapa 1 krok 4 | | **Typ důkazu** | **Rozhodnutí vlastníka před discovery**, ne důkaz z rozhovorů se zákazníky | ### Rozhodnutí První podporovanou linuxovou cílovou platformou CyberBrain Agent Guard je **Ubuntu 24.04 LTS, výhradně**. Ostatní linuxové distribuce a verze nejsou v prvním produktu podporovanou konfigurací. ### Zdůvodnění - Uzavřít Etapu 1 krok 4 („Stanovit jednu podporovanou linuxovou distribuci/verzi a nutné Bubblewrap předpoklady podle rozhovorů“) a odblokovat práci na balení a CI, která bez jedné cílové platformy nemá co ověřovat. - Jedna hostitelská konfigurace znamená jednu testovanou matici pro instalaci, sandbox a diagnostiku, místo množství neověřených kombinací. - Ubuntu LTS je dlouhodobě udržovaná platforma s předvídatelným balíkováním a verzemi kernelu, což odpovídá současnému prototypnímu backendu (`BubblewrapExecutionProvider`, linuxové namespaces). ### **Pozor: rozhodnutí bylo přijato před zákaznickými rozhovory** Toto rozhodnutí **nepochází z evidence rozhovorů**. Bylo učiněno vlastníkem 2. října 2026, tedy předtím, než proběhla jakákoli zákaznická interview (viz [customer discovery plán](CUSTOMER_DISCOVERY_V5.md) — k 2. října 2026 nebyly provedeny žádné rozhovory). Je tedy **vlastnické rozhodnutí, nikoli ověřený zákaznický fakt**. - Je nutné ho znovu potvrdit proti výsledkům 8–12 rozhovorů: jaké OS a verze respondenti skutečně používají na pracovních stanicích, zda odpovídá jejich firemní standardizaci a zda vůbec chtějí instalovat lokální nástroj. - Pokud evidence ukáže jinou dominantní platformu, je nutné toto rozhodnutí revidovat (viz „Jak revidovat“). Změna po implementaci balení je dražší než změna teď, proto evidence discovery zůstává zásadní. - Toto rozhodnutí **neruší** discovery gate pro zbytek MVP scope; pouze uvolňuje packaging/CI práci, která na zvolené platformě nezávisí na výsledku interview. ### Dopady - **Bezpečnost:** Zúžení na jednu hostitelskou konfiguraci zmenšuje počet neověřených kombinací, na kterých se tvrzení o izolaci opírá. Neznamená to bezpečnostní certifikaci ani schválení proti nepřátelskému kódu; zůstává platné prohlášení o rozsahu v `docs/SECURITY_ONE_PAGER.md` §1 a §9. Podporovanou verzi `bwrap` je stále nutné evidovat — verze se v kódu nepinuje ani neověřuje. - **Rozhraní:** `cyberbrain doctor` (příkaz `check`) musí hlásit nesoulad, pokud běží na nepodporované distribuci, a uvést očekávanou platformu; uživatel musí dostat srozumitelnou chybu, ne tiché snížení bezpečnosti. - **Persistence:** Přímý dopad není. Cesty a oprávnění SQLite (`user_data_dir`, `0o700`/`0o600`) jsou platformově nezávislé; instalace a záloha se však musí dokumentovat pro konkrétní cesty Ubuntu 24.04 LTS. - **Kompatibilita:** Zúžení podpory je záměrná kompatibilita inverze — uživatelé na Fedora, Debianu, Archu nebo jiných verzích Ubuntu nejsou podporovaní a musí dostat jasné sdělení místo tiché nepodpory. `ROADMAP_V5.md` Etapa 5 ponechává macOS/Windows a další platformy až na základě potvrzené placené poptávky; toto rozhodnutí Etapu 5 nemění. ### Co výslovně nerozhodnuto - První podporovaný **coding agent / integrace** (Etapa 0 discovery) — stále otevřené. - Konkrétní verze kernelu a verze `bwrap`, která bude podporovaná a ověřená; pinování verze je otevřený bod v `docs/SECURITY_ONE_PAGER.md` §10. - Zda bude kromě CLI existovat jiná podporovaná forma instalace (`.deb`, `pipx`, kontejner) — viz Etapa 4. - Podporované Python verze. Kód vyžaduje `>= 3.11` (`pyproject.toml`); Ubuntu 24.04 LTS standardně nabízí 3.12, ale hostitelská shoda není součástí tohoto rozhodnutí. - Cgroup limity, limity počtu procesů a diskové kvóty — zůstávají otevřené (`ROADMAP_V5.md` Etapa 3 krok 3). ### Jak revidovat Revizi zapíš jako nový záznam `D1-r1` v tomto souboru: nová data, důvod změny, kdo rozhodl a jaké důkazy (výsledky rozhovorů, CI výsledky, incident) rozhodnutí změnily. Do té doby platí D1 jako závazná výchozí konfigurace pro packaging a CI. Toto rozhodnutí zároveň přebíjí instrukci v [V5_FIRST_SPRINT_REPORT.md](V5_FIRST_SPRINT_REPORT.md) §„Current gate“, že se OS cíl „zatím neuzavírá“. --- ## D2 — `cyberbrain run` bude fail-closed | Položka | Hodnota | |---|---| | **Datum rozhodnutí** | 2. října 2026 | | **Stav** | **Schváleno, implementováno** — CLI `run`/`plan` jsou napojeny přes `PtahBridge.execute_step` → `AuthorizedExecutionService` → `ExecutionRefused`; `SQLiteDatabase` je připojena, `--insecure-legacy` neexistuje | | **Rozhodl** | Vlastník projektu (majitel produktu) | | **Oblast** | Bezpečnostní pořadí akce / Etapa 2 P0 roadmapy | | **Navazuje na** | `ROADMAP_V5.md:123` („chybějící schvalovací infrastruktura musí skončit zavřením akce“) | ### Rozhodnutí Příkaz `cyberbrain run` musí být napojen přes `AuthorizedExecutionService` a `PtahBridge` s reálnou `SQLiteDatabase`. Citlivé akce mají skončit **uzavřenou akcí** (`SecurityError`), nikoli tichým průchodem. - **Žádný bypass přepínač.** Nepřidává se `--insecure-legacy` ani žádný jiný přepínač, který by vracel dnešní nechráněné chování. - Fail-closed zůstává i tehdy, když schvalovací infrastruktura není dostupná, vyprší, je zrušená nebo je sandbox nedostupný. ### Zdůvodnění - `ROADMAP_V5.md` Etapa 2 P0 vyžaduje, aby každé podporované volání nástroje prošlo deterministickou autorizací a aby zamítnutí, timeout i chybějící schvalovací infrastruktura skončily zavřením akce. D2 tuto bránu staví do kódu, ne jen do dokumentace. - Dřívější `cyberbrain run` obcházel `CoderAgent` i `AuthorizedExecutionService`: volal `gateway.chat(...)` přímo (`src/cyberbrain26/cli.py:171`), takže v této cestě `PermissionGateway` ani sandbox vůbec nebyly ověřovány (potvrzeno v `docs/SECURITY_ONE_PAGER.md` §10). Tento bypass je nyní **odstraněn** rozhodnutím D2 (směr `run` → `PtahBridge.execute_step` → `AuthorizedExecutionService`) i D3 (odstranění `ModelGateway` z CLI). - `PtahBridge()` se v CLI konstruuje bez databáze (`src/cyberbrain26/cli.py:98,137`) a `ApprovalManager` je pak `None` (`src/cyberbrain26/orchestration/ptah_bridge.py:180-182`). Bez skutečného DB tedy citlivá akce skončí `SecurityError("Approval unavailable for action ...")` — což je požadované chování, ne chyba. ### **Důsledek, který je nutné říct nahlas** **Po implementaci D2 přestane dnešní `cyberbrain run` fungovat pro citlivé akce.** Bude končit chybou a odmítnutím, dokud nebude existovat schválený stav v SQLite. To je záměr: fail-closed znamená, že chybějící schválení zavírá akci. Toto rozhodnutí záměrně odebírá tichý průchod, který dnes existuje. Tentootevřený bod, který D2 neřeší, **byl vyřešen rozhodnutím D3**: `cyberbrain run` už `ModelGateway` nesestavuje ani nevolá; přepínače `--model`/`--lang` byly odstraněny a `run`/`plan` jsou plně model-free. Původní otisk `default_provider="litellm"` s fallbackem na `ollama`/`llama.cpp` (`src/cyberbrain26/cli.py:148-156`) už v kódu neexistuje. Zbývá otevřený pouze library-level `ModelGatewayConfig` (mimo CLI), viz „Co výslovně nerozhodnuto“ a D3. ### Dopady - **Bezpečnost:** kladný dopad v pořadí identita → politika → oprávnění → bezpečnostní kontroly → vyhodnocení → audit. Citlivé akce již neprojdou bez schválení podle `SENSITIVE_ACTIONS`; chybějící sandbox už dnes vyhodí `RuntimeError` před spuštěním procesu a tento stav se nemění. D2 **nepřidává** žádný host fallback ani obejití policy. Neznamená to, že se sandbox stal schválenou ochranou proti nepřátelskému kódu — to zůstává mimo rozsah. - **Rozhraní:** `cyberbrain run` bude vyžadovat dostupnou SQLite databázi a bude produkovat `SecurityError`/jasnou chybu místo tichého průchodu; uživatel bude potřebovat cestu schválení přes `cyberbrain approvals` (`pending`/`show`/`approve`/`deny`/`history`, registrované v `src/cyberbrain26/cli.py:20,25`, kryté `tests/test_product_cli.py`). Chybové výstupy musí být čitelné a nesmějí zveřejňovat secrets. - **Persistence:** `PtahBridge` musí dostat reálnou `SQLiteDatabase` (viz `product/local_store.py`, `ENV_DATA_DIR` / `ENV_DB_PATH`), jinak zůstane queue `MemoryTaskQueue`, `AuditLog(database=None)` a audit, schválení i `tasks` se neuloží. Audit pak není důkazem — audit log je v SQLite vlastněném lokálním operátorem a není kryptograficky neměnný (`docs/SECURITY_ONE_PAGER.md` §5 a §8). - **Kompatibilita:** Záměrná zlomová změna chování existujícího příkazu. Uživatelé, kteří dnes spoléhají na tichý průchod `cyberbrain run`, dostanou odmítnutí; migrace není plánována, protože by vyžadovala právě ten obejití, který D2 zakazuje. Je nutné to sdělit v changelogu a v bezpečnostním listu. `cyberbrain plan` D2 neomezuje. ### Co výslovně nerozhodnuto - Library-level `ModelGatewayConfig` (`default_provider="litellm"`, `prefer_local=False`, fallback na `ollama`/`llama.cpp`) — samostatný otevřený bod mimo CLI. D3 tento gap v CLI uzavřel, ale `ModelGateway` jako knihovna pro ostatní kanály (agenti, API) zůstává otevřený do další revize (`docs/SECURITY_ONE_PAGER.md` §7 a §10). - Prompt egress a jeho zobrazení uživateli před prvním vzdáleným voláním; `PrivacyGateway` není kontrola odchozích promptů (§5, §7). - První vstupní bod pro coding agenta (adaptér existujícího agenta vs. vlastní CLI) — Etapa 0 discovery. - Kryptografické svázání schválení s payloadem, který se spustí (`docs/SECURITY_ONE_PAGER.md` §10, první bod). - Per-task Git worktree, diff review a převzetí změn (Etapa 2 P0). - `AIFirewall` v cestě spuštění a v prompt egressu (§5, §10). ### Jak revidovat Revize vyžaduje vlastníka. Přípustné jsou jen dva směry: (a) doplnit schvalovací infrastrukturu tak, aby akce mohla být povolena standardní cestou, nebo (b) změnit samotné rozhodnutí novým záznamem `D2-r1` s uvedením důvodu a důkazů. **Vratná cesta zpět k tichému průchodu se jako produktové rozhodnutí nepřipouští**; pokud fail-closed brání reálnému pilotu, řeší se to zúžením podporovaného scénáře nebo novým backendem, ne obejitím. --- ## D3 — `cyberbrain run`/`plan` nevolají model; odstraněny `--model`/`--lang` | Položka | Hodnota | |---|---| | **Datum rozhodnutí** | 2. října 2026 | | **Stav** | **Schváleno, implementováno** — `ModelGateway.chat` byl odstraněn z `run` a `plan`; přepínače `--model` a `--lang` nejsou definovány | | **Rozhodl** | Vlastník projektu (majitel produktu) | | **Oblast** | Bezpečnostní pořadí akce / Etapa 2 P0 roadmapy — doplněk k D2 | | **Navazuje na** | D2; `ROADMAP_V5.md` §4 bod 6 („žádné tiché přechody“) | ### Rozhodnutí `cyberbrain run` a `cyberbrain plan` **neobsahují ani nevolají `ModelGateway`** ani jakýkoli jiný modelový backend. `run` doslova nic nevypočítává — každý krok směřuje skrz `PtahBridge.execute_step`, který aplikuje identity → scope → policy → approval a pak spouští deklarovanou akci v sandboxu. `plan` sestavuje pouze paměťový seznam kroků s prázdným `action`. - **Odstraněny přepínače `--model` a `--lang`.** Nepřidává se žádná alternativní volba modelu ani jazyka; pokud roadmapa obsahuje krok bez deklarované `action`, `execute_step` jej odmítne místo spustit implicitní výchozí. - **Viditelný výsledek.** Plány od `plan` mají kroky bez `action`, takže `run` jejich všechny kroky odmítne a explicitně to oznámí. To není chyba ani bug — je záměrným a viditelným důsledkem tohoto rozhodnutí. ### Zdůvodnění - D2 říká, že `run` musí procházet `AuthorizedExecutionService`, aby každý krok měl ověřitelnou identitu, scope a schválení. `ModelGateway.chat` v původní cestě (`src/cyberbrain26/cli.py:171`) **obchodoval mimo tuto bránu**: modelový výstup nemá žádnou akci ani scope v policy systému a proto ho lze autorunovat jako deklarovanou akci. Spouštění modelového textu ve sandboxu by tedy bylo **trusted input → untrusted execution**, což porušuje fail-closed pořadí. - `ROADMAP_V5.md` §4 bod 6 říká „žádné tiché přechody“ mezi backendy. `ModelGateway` s `default_provider="litellm"` a fallbackem na `ollama`/`llama.cpp` (`ModelGatewayConfig`) představoval právě takový tichý přechod. D3 tento gap tím, že modelová cesta ze CLI je odstraněna úplně. - `cyberbrain plan` už nikdy nevyžadoval interaktivní modelování od uživatele; plány jsou deklarativní a lze je psát ručně nebo generovat offline. Online model call v CLI byl zbytečným rizikem. ### **Dopad, který je nutné říct nahlas** **`cyberbrain run` neumí generovat ani upravovat roadmapu ani kroky.** Uživatel musí nejprve spustit `cyberbrain plan` (který vytvoří akčně-prázdné kroky) a potom ručně doplnit `action` do `roadmaps.json`, nebo použít jiný kanál k deklaraci kroků. Bez explicitní `action` každý krok končí `ExecutionRefused`. Záměrně se neukrývá fallback ani implicitní chování. ### Dopady - **Bezpečnost:** kladný. Odebráním modelové cesty z CLI se zavírá jeden z hlavních vstupních vektorů untrusted input → sandbox. `ModelGateway` zůstává jen jako knihovna pro další kanály (agenti, API), nikoliv jako součást `run`/`plan` CLI. - **Rozhraní:** `cyberbrain run` nemá `--model`/`--lang` — příkaz selže při neznámém přepínači místo tichého ignorování. `cyberbrain plan` vyprodukuje roadmapu se kroky, které `run` musí mít `action` doplněnou ručně nebo se vše odmínou. - **Persistence:** přímý dopad není. `SQLiteDatabase` i audit log uchovávají deklarované kroky i výsledky jejich odmítnutí i schválení stejnofaktně. - **Kompatibilita:** zlomová změna. Uživatelé, kteří dříve spoléhali na `--model`/`--lang` nebo implicitní modelové volání během `run`, musí deklarovat akce explicitně. Žádný tichý fallback není plánován. ### Co výslovně nerozhodnuto - Kde a jaký modelový backend použít **mimo CLI** (např. v `CoderAgent`/`Orchestrator` pro interaktivní režim). D3 omezuje pouze `run`/`plan` CLI. - `PrivacyGateway` kontrola odchozích promptů — otevřenýbod v `docs/SECURITY_ONE_PAGER.md` §5 a §7, nerozhodován tímto záznamem. ### Jak revidovat Revidovat jako nový záznam `D3-r1`: jen pokud se rozhodne přidat modelovou cestu zpět do `run`/`plan` CLI (což vyžadovalo by vlastní revizi fail-closed D2 a explicitní bezpečnostní revizi). --- ## Souhrn stavu | ID | Rozhodnutí | Stav | Kdo rozhodl | Implementace | |---|---|---|---|---| | D1 | Podporovaný OS = Ubuntu 24.04 LTS | rozhodnuto, před discovery | vlastník | čeká — packaging + CI | | D2 | `cyberbrain run` fail-closed | schváleno, implementováno | vlastník | implementováno — `AuthorizedExecutionService` + `SQLiteDatabase` + `ExecutionRefused` | | D3 | `run`/`plan` model-free; `--model`/`--lang` odstraněny | schváleno, implementováno | vlastník | implementováno — `ModelGateway.chat` odebrán z CLI | Všechny položky jsou **rozhodnutím vlastníka**, ne ověřenými zákaznickými fakty. Discovery gate (8–12 rozhovorů) zůstává blokující pro zbytek MVP scope; D1 jej nenalamuje, pouze uvolňuje packaging a CI.