# DeepWebResearch Synthesis Implementation Plan — CyberBrain26

**Project:** CyberBrain26-v4
**Phase:** F2 → F3 boundary
**Owner:** orchestrator
**Created:** 2026-11-04
**Status:** ready for implementation

## 1. Souhrn v jedné větě

Implementujeme kompletní knowledge plane nad bestehenden MemoryService, inspirované čtyřmi deepwebresearch projekty: ByteRover (agent-native memory, Context Tree), MemGraphRAG (entity-relationship graf), MemStrata (bi-temporal validita), H-Mem (multi-dimenzionální paměť) — s použitím vícevrstvých subagentů a paralelního zpracování.

## 2. Zdrojové deepwebresearchy (všechny 4 dokončeny)

| Výzkum | Zdroj | Datum přístupu | Hlavní vzory |
|--------|-------|----------------|-------------|
| ByteRover | arXiv:2604.01599 + byterover.dev | 2026-11-04 | Agent-native memory, Context Tree (Domain > Topic > Subtopic), 5 komponent, 5-tier retrieval, git-like branch/merge nad markdown |
| MemGraphRAG | arXiv:2606.00610, KDD 2026 | 2026-11-04 | Tři agenti (Extraction, Conflict Detection, Conflict Resolution), Shared Memory (Ontology+Fact+Passage), memory-aware retrieval, Personalized PageRank |
| MemStrata | arXiv:2606.26511 | 2026-11-04 | Bi-temporal ledger (valid_from, valid_to, superseded_by), deterministické supersedence pravidlo, žádný similarity threshold pro stale facts |
| H-Mem | arXiv:2603.27910v1, ACL 2026 | 2026-11-04 | Tři dimenze paměti (Fact/Temporal/Semantic Nodes), sekvenční i paralelní retrieval, Mode Controller |

## 3. Delegace a architektura subagentů (vrstvené)

### Vrstva 1 — Orchestrátor (jediný delegátor)
- `mode: primary`, `task: allow` pro 10 subagentů (dle `.kilo/kilo.jsonc`)
- Nikdy sám nekoná, vždy deleguje konkrétnímu subagentovi

### Vrstva 2 — Subagenty (spuštěny orchestrátorem, paralelní fan-out)
Každý subagent má `owner_role`, vlastní kontext, vlastní `declared_actions`.

### Vrstva 3 — Sub-subagenty (spuštěny vrstvou 2, limit depth 3)
Pro deep-verifikaci a cross-checky.

### 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.

## 4. Implementační fáze

### Fáze A — Auto-categorization (ByteRover + Memex výzkum)
**Cíl:** Automatická klasifikace dokumentů přes LLM při `register_file`, uložení do hiérarchického Markdown store, hybridní search.

| Task | Popis | Soubory | Souhlasící deepwebresearch |
|------|-------|---------|---------------------------|
| A1 | `LLMClassifier` — strict JSON prompt, temperature=0, confidence pole | `classifier.py` | ByteRover/Memex |
| A2 | `MarkdownStore` — uložení do `knowledge_docs/{topic}/{subtopic}/`, `hierarchy.md` | `markdown_store.py` | ByteRover Context Tree |
| A3 | SHA-256 watch mode — pouze změněné/nové soubory, každý soubor nezávisle | `memory_service.py` | Grimore-MD/RAGraph |
| A4 | Integrace do `register_file` — klasifikace před registrací | `memory_service.py:126-200` | Memex auto-classify |
| A5 | Hybrid search: BM25 (SQLite FTS5) + cosine similarity + RRF fusion | `vector_store.py` + navigation | RAGraph |
| A6 | CLI: `knowledge ingest --recursive`, `knowledge search "dotaz"` | `cli.py` | — |
| A7 | Testy: `tests/test_knowledge_classification.py`, `tests/test_knowledge_hybrid_search.py` | nové testy | — |

### Fáze B — Temporal validity (MemStrata výzkum)
**Cíl:** Bi-temporal ledger, deterministická kontrola zastaralých faktů.

| Task | Popis | Soubory |
|------|-------|---------|
| B1 | Přidat `valid_from`, `valid_to`, `superseded_by` do `KnowledgeDocument` | `contracts.py` |
| B2 | `TemporalValidator` v `KnowledgeNavigator` — deterministická kontrola | `navigation.py` |
| B3 | CLI: `--validate-stale`, `--timeline` volby | `cli.py` |
| B4 | Testy: `tests/test_knowledge_temporal.py` | nové testy |

### Fáze C — Knowledge graf (MemGraphRAG výzkum)
**Cíl:** Entity-relationship uzly, grafová navigace, multi-perspektivní retrieval.

| Task | Popis | Soubory |
|------|-------|---------|
| C1 | Rozšířit `KG1Node` o entity-relationship tracking | `contracts.py` |
| C2 | `--graph` a `--traversal` CLI volby | `cli.py` |
| C3 | Testy: `tests/test_knowledge_graph.py` | nové testy |

### Fáze D — Enterprise security (PII/Redaction)
**Cíl:** PII detekce a redaction při ingestu.

| Task | Popis | Soubory |
|------|-------|---------|
| D1 | PII detekce v classifieru | `classifier.py` |
| D2 | Sensitivity redaction při ingestu | `memory_service.py` |
| D3 | Testy: `tests/test_knowledge_pii.py` | nové testy |

### Fáze E — Paralelizace a optimalizace (H-Mem výzkum)
**Cíl:** Multi-dimenzionální retrieval, paralelní batch zpracování.

| Task | Popis | Soubory |
|------|-------|---------|
| E1 | Paralelní batch zpracování (dedup, klasifikace) | `memory_service.py`, `deduplication.py` |
| E2 | Caching strategie pro embeddings | `embedding_service.py`, `vector_store.py` |
| E3 | Benchmarky (LongMemEval-S kompatibilní) | `tests/test_knowledge_benchmark.py` |

## 5. Kritéria přijetí (Gate sequence)

### Gate 1 (PŘED jakoukoliv změnou)
- `pytest -q` — všechny testy zelené (≥747 passed)
- `ruff check` — čistý
- `mypy src/cyberbrain26` — čistý (87 files)

### Gate 2 (PO změnách, každá fáze)
- `pytest -q` — žádné regrese
- `ruff check` — čistý
- `mypy src/cyberbrain26/knowledge_plane` — žádné nové chyby
- Receipt kontrola: `git status --porcelain`, `grep -c` na klíčové řádky, `cat -A` na whitespace

### Gate 3 (Nezávislá verifikace)
- `gate3-auditor` — PASS/FAIL/REJECT_UNVERIFIED verdikt
- Jiný model než vývoj (dolphin-cb26:latest)
- Výstup je doslovný (pytest výstup bez šablon)

## 6. Security / D6 invariant

- `orchestrator` je jediný agent s `task: allow`; ostatní `task: deny` default
- Cross-check `declared_actions` proti `ACTION_SCOPE_REQUIREMENTS`
- Fail-closed: žádné tiché fallbacks
- `bash: deny` pro všechny kromě tester; `edit: orchestrator` (markdown only) a `implementer` (`src/`/`tests/`)

## 7. Receipt pravidlo (Rule 7)

Každá tvrzená změna potřebuje `file:line` + jeden ověřující příkaz (`cat -A`, `git status --porcelain`, `grep -c`). Bez receipt = `REJECT_UNVERIFIED`.

## 8. Rekognoscovaný stav kódu (file:line důkazy)

| Komponenta | Soubor | Stav |
|------------|--------|------|
| MemoryService | `src/cyberbrain26/knowledge_plane/memory_service.py:46-526` | Implementováno, auto_classify částečně |
| LLMClassifier | `src/cyberbrain26/knowledge_plane/classifier.py:1-281` | Existuje, ale není konzistentně voláno |
| MarkdownStore | `src/cyberbrain26/knowledge_plane/markdown_store.py` | Existuje |
| KnowledgeNavigator | `src/cyberbrain26/knowledge_plane/navigation.py:36-307` | PARTIAL, má entity graf a temporal checks |
| DeduplicationEngine | `src/cyberbrain26/knowledge_plane/deduplication.py` | WORKING, hash + URL dedup |
| EmbeddingService | `src/cyberbrain26/knowledge_plane/embedding_service.py:1-103` | Ollama wrapper, qwen3-embedding:0.6b, dim 1024 |
| KnowledgeVectorStore | `src/cyberbrain26/knowledge_plane/vector_store.py:1-128` | LanceDB, persistent |
| contracts.py | `src/cyberbrain26/knowledge_plane/contracts.py` | KG1Node, KnowledgeDocument, DocumentStatus |
| CLI knowledge | `src/cyberbrain26/cli.py:590-722` | PARTIAL, ingest/search/kg1 existují |
| ACTION_SCOPE_REQUIREMENTS | `src/cyberbrain26/security_plane/actions.py:242-284` | Definováno |

## 9. První konkrétní akce (ihned)

1. Spustit `bash` příkaz pro ověření aktuálního stavu (pytest, ruff, mypy)
2. Připravit první diff k recenzi (A1 + A2: classifier + markdown_store)
3. Po schválení vlastníka → implementer aplikuje diff
4. Tester Gate 2, code-reviewer revize, verifier nezávislá verifikace
5. Dokumenter aktualizace `docs/` + `CHANGELOG.md`