--- title: Konwencje kb-wiki type: meta status: active tags: [] sources: [] compiled_by: claude-sonnet-5 compiled_at: 2026-07-21 updated_at: 2026-08-27 --- # Konwencje kb-wiki Ten dokument definiuje format stron tej wiki. Rozwinięcie decyzji architektonicznych z `homelab-codex-ws`, `docs/kb/modules/05-faza3-plan.md` §8 (szkic operatora, NIE zmieniamy stamtąd decyzji — tylko doprecyzowujemy wykonanie). To repo jest read-write tylko dla kompilatora (CC/API); baza źródłowa (`kb-postgres@PIHA`) jest zawsze read-only z tej strony. ## Struktura katalogów Typy stron = katalogi; płasko wewnątrz każdego, graf robią linki `[[...]]`, nie hierarchia plików. | Katalog | Zawartość | |---|---| | `podmioty/` | Firmy i instytucje: ubezpieczyciele, banki, urzędy — encje trwałe, nie procesy | | `osoby/` | Tożsamości/aliasy osób fizycznych | | `sprawy/` | Procesy w czasie: sezony, remonty, procesy decyzyjne, porównania ofert | | `umowy/` | Konkretne, zawarte kontrakty/polisy — jeden dokument prawny lub jego wersje | | `tematy/` | Przekrojowe kategorie łączące wiele podmiotów/spraw (np. „ubezpieczenia auto”) | | `_meta/` | Ten plik, raporty lintu | Wybór katalogu dla nowej strony: jeśli encja to firma/instytucja → `podmioty/`; jeśli to coś co się dzieje/działo w czasie (sezon, spór, zakup) → `sprawy/`; jeśli to konkretna umowa prawna → `umowy/`; jeśli łączy wiele podmiotów pod wspólnym parasolem tematycznym → `tematy/`. ## Frontmatter ```yaml --- title: type: podmiot # podmiot | osoba | sprawa | umowa | temat | meta status: active # active | archived tags: [ubezpieczenie] # słownik wspólny z jobs/documents-ingest/tags-vocab.yaml # (homelab-codex-ws) — nie wymyślamy nowego słownika dla wiki sources: - envelope_id: paperless:119 chunks: [4211, 4213] # document_chunk.id (klucz PK), NIE chunk_index - envelope_id: "CABtrY-...@mail.gmail.com" chunks: [] # koperta bez chunków (np. sam manifest) compiled_by: claude-sonnet-5 # model/sesja, która skompilowała/ostatnio zmieniła stronę compiled_at: 2026-07-20 # data pierwszej kompilacji updated_at: 2026-07-20 # data ostatniej zmiany --- ``` `sources` agreguje **wszystkie** koperty, z których cokolwiek na stronie pochodzi — niezależnie od tego, ile razy dana koperta jest cytowana w treści. To jest poziom audytu „skąd strona czerpie w ogóle”; poziom „ten konkretny fakt” robią przypisy inline (niżej). ## Przypisy inline i cytowanie faktów Każdy fakt liczbowy lub identyfikujący (kwota, data, numer polisy/umowy, adres, próg punktowy) dostaje przypis w miejscu użycia: ```markdown składka 1 234 zł/rok [^paperless:119#4212] ``` Format: `[^#]`. Jeden fakt może mieć więcej niż jeden przypis, jeśli potwierdzają go niezależnie różne chunki/koperty — wtedy oba się wypisuje: `[^paperless:14#965][^paperless:22#2081]`. **Fallback envelope-only (decyzja d, audyt 08-26):** `document_chunk.id` jest kruchy — re-chunking (zmiana `chunk_size`/modelu embeddingu) usuwa i wstawia wiersze na nowo, stary `id` przestaje istnieć. Gdy dowód nie ma konkretnego chunka (sam nagłówek koperty) albo chunk już nie istnieje po re-chunkingu, przypis degraduje się do samej koperty: `[^]`, bez `#`. `envelope_id` jest stabilny (Message-ID/`sha256-…`, nigdy nie zmienia się po insercie) — degradacja zostaje audytowalna, tylko mniej precyzyjna. Lint raportuje liczbę zdegradowanych przypisów jako osobną metrykę (sygnał, że re-chunking coś ruszył); re-chunking jest triggerem do ręcznego przeglądu stron, nie do automatycznego remapowania (wymagałby ponownego embeddingu i ryzykowałby przypisanie faktu do złego fragmentu po cichu). Fakty opisowe/narracyjne (np. „PZU oferuje kilka wariantów ubezpieczenia") niosące niską specyficzność mogą dzielić jeden przypis na koniec akapitu zamiast przypisu po każdym zdaniu — przypis jest obowiązkowy per sekcja, nie per zdanie, ale musi dawać się prześledzić do konkretnego chunka. **Zakaz dopowiadania**: jeśli fakt nie występuje w żadnym pobranym chunku/streszczeniu, strona pisze wprost „brak danych w KB" zamiast go zgadywać z wiedzy ogólnej modelu. ## Sprzeczności między źródłami Gdy dwa dokumenty (typowo: dwie wersje tego samego OWU z różnymi datami obowiązywania, albo dwie oferty konkurencyjne) podają różne wartości dla tego samego faktu, strona **nie wybiera cicho jednej wersji**. Sprzeczność jest flagowana jawnie w tekście, z obiema wartościami i obu przypisami, np.: ```markdown Udział własny w AC: 300 zł wg OWU obowiązującego od 21.03.2026 [^paperless:14#871], ale 500 zł wg wcześniejszej wersji OWU [^paperless:17#XXXX] — **rozbieżność między wersjami, nie literówka**; przy sporze o odszkodowanie decyduje wersja obowiązująca w dniu zdarzenia. ``` ## Sekcja „Niepewne / sprzeczne" i polityka aktualizacji (decyzja e, audyt 08-26) Sekcja wyżej pokazuje *jak* flagować sprzeczność w treści. To formalizuje ją jako **nazwaną sekcję na końcu strony** (już używana na żywych stronach: `pzu.md`, `warta.md`, `mbank.md`, ...), gdy sprzeczności nie da się rozstrzygnąć przy kompilacji — nazwa i miejsce ujednolicone, żeby czytelnik/lint wiedział, gdzie szukać: ```markdown ## Niepewne / sprzeczne - Składka OC: [^paperless:24#N] podaje kwotę roczną bez liczby, [^#M] (mail 2025-03) wspomina "1 450 zł" — nie jest jasne, czy to ta sama polisa czy poprzedni rok. **Nie rozstrzygane automatycznie** — do potwierdzenia przy następnej kompilacji tej strony. ``` Kolejność na końcu strony, gdy obie sekcje występują: „Niepewne / sprzeczne" przed „Brak danych w KB" (niżej) — dowody, które się kłócą, nie to samo co brak dowodów w ogóle. Strona bez tej sekcji nie jest „lepsza" — strona z niewykrytą sprzecznością w treści głównej jest gorsza; to mechanizm anty-propagacji (kompilator pisze „nie wiem" zamiast zgadywać i zamrażać zgadywankę jako fakt). **Polityka aktualizacji przy nowym, sprzecznym dowodzie: dopisz, nie nadpisuj.** Domyślnie nowy sprzeczny dowód trafia do „Niepewne/sprzeczne", fakt w treści głównej **nie** jest nadpisywany, dopóki sprzeczność nie zostanie rozstrzygnięta. Wyjątek: gdy nowy dowód jest tego samego typu i **wprost aktualizuje** poprzedni (np. „nowy cennik od 1.09" jawnie zastępujący poprzedni, bez sprzeczności) — to nie jest sprzeczność, to aktualizacja: idzie do treści głównej z nową `updated_at`. Rozróżnienie „aktualizacja" vs „sprzeczność" robi **sesja kompilująca** (CC/API), nie reguła automatyczna. ## Wersjonowanie dokumentów źródłowych Ubezpieczenia i regulaminy w korpusie mają wielokrotne wersje z różnymi datami „obowiązuje od". Strona encji **nie kompiluje jednej płaskiej prawdy** — jeśli źródła mają rozbieżne daty obowiązywania, strona wymienia wersje osobno (np. podsekcja per data) zamiast nadpisywać starszą nowszą bez adnotacji. To był konkretny finding z pilota dedupa (`docs/kb/eval/retrieval-pilot-2026-07-16.md`, `docs/kb/modules/05-faza3-plan.md` §3.2) — dokumenty bywają też **duplikatami binarnymi** (`excluded_reason='duplicate'` w bazie), co jest czymś innym niż kolejna wersja: duplikat pomijamy w kompilacji (baza już to wyklucza z retrievalu), wersję z inną datą obowiązywania — nie. ## Sekcja „Brak danych w KB" (rozszerzenie, faza 5 etap 1 rekoncyliacja, 2026-08-27) „Zakaz dopowiadania" wyżej mówi, że pojedynczy fakt bez pokrycia w źródłach pisze się wprost jako „brak danych w KB" w miejscu użycia. To rozszerzenie formalizuje to jako **osobną sekcję na końcu strony**, odróżnioną od „Niepewne / sprzeczne": - **„Niepewne / sprzeczne"** — dowody **istnieją**, ale się nie zgadzają (dwa chunki, dwie wartości, dwa przypisy). - **„Brak danych w KB"** — zapytano retrievalem o coś istotnego dla tej encji, i **żaden** pobrany chunk/streszczenie tego nie potwierdza. Nie jest to błąd kompilacji — jest to jawne przyznanie granicy tego, co korpus dziś wie, zamiast milczącego pominięcia pytania. Format — krótka lista na końcu strony, po „Niepewne / sprzeczne" (jeśli obie występują): ```markdown ## Brak danych w KB - Nazwisko trenera drużyny (OCR nieczytelny w `paperless:175`). - Wynik końcowy/klasyfikacja drużyny w całym turnieju (KB ma tylko wyniki cząstkowe). ``` Praktyczna wartość: kolejna kompilacja/aktualizacja tej strony (albo lint) wie od razu, czego szukać przy następnym retrievalu, zamiast rekonstruować to z pamięci sesji albo przeczytać stronę i domyślać się, co zostało pominięte a co nigdy nie było sprawdzone. Pierwszy przykład użycia (przed formalizacją tej reguły): `sprawy/fll-2025-26.md`, sekcja „Brak danych w KB", kompilacja 2026-07-21. ## Linkowanie między stronami `[[nazwa-pliku-bez-rozszerzenia]]` — link do innej strony wiki po nazwie pliku (bez katalogu, nazwy plików są unikalne w całym repo). Linkujemy tam, gdzie treść się faktycznie styka (wspólny podmiot, wspólna sprawa, przywoływany dokument) — nie tworzymy linków na wyrost do stron, które jeszcze nie istnieją, chyba że świadomie oznaczamy brakujące pojęcie (patrz niżej), bo taki link psuje inwariant lintu „brak stron-sierot i wiszących linków" dopóki strona docelowa nie powstanie. ## Brakujące pojęcia (przyszłe strony) Jeśli podczas kompilacji natrafiamy na encję wartą osobnej strony, ale poza zakresem bieżącej kompilacji (np. inny ubezpieczyciel wspomniany punktowo, inna sprawa), **nie tworzymy linku `[[...]]`** do niej (byłby wiszący). Zamiast tego kandydatka trafia do listy „brakujące pojęcia" w najbliższym raporcie lintu (`_meta/lint-reports/`), żeby nie zgubić się w wątku. ## Zasady lintu Okresowy lint (ręczny w tej fazie, `_meta/lint-reports/YYYY-MM-DD.md`) sprawdza: 1. **Strony-sieroty** — strona bez żadnego linku przychodzącego z innej strony (poza `INDEX.md`, który z definicji linkuje do wszystkiego). 2. **Wiszące linki** — `[[cel]]` bez odpowiadającego pliku `cel.md` w repo. 3. **Brakujące pojęcia** — encje wspomniane w treści (nie w linku) a nieopisane osobną stroną; kandydaci na przyszłe strony, nie błąd. 4. **Spot-check** — dla losowej próbki przypisów `[^envelope_id#chunk_id]` weryfikacja, że treść chunka w bazie faktycznie potwierdza przywołany fakt. 5. **Sprzeczności międzystronicowe** — ten sam fakt o tej samej encji opisany różnie na dwóch stronach (nie mylić z rozbieżnością międzywersyjną w obrębie jednej strony, która jest już jawnie flagowana w treści per wyżej). ## Kompilacja: CC/API-only i inwariant 7 — izolacja retrievalu (decyzja f, audyt 08-26) Kompilację i lint robi wyłącznie CC/zewnętrzne API (patrz akapit wstępny) — lokalny model za słaby na wielostronicowe operacje syntezy. **Inwariant 7:** retrieval na potrzeby **kompilacji** strony wiki nigdy nie czyta `source='wiki'` jako dowodu — zawsze wyklucza wiki (`exclude_sources=('wiki',)` albo równoważny filtr SQL), czyta wyłącznie warstwę dowodową (mail, paperless). Tylko retrieval na potrzeby `/search` (warstwa użytkownika, po zbudowaniu syntezy odpowiedzi — poza zakresem tej fazy) widzi wiki w kaskadzie. Mitygacja self-citation/citogenesis: bez tego rozdziału kompilacja strony X mogłaby cytować inną stronę wiki (samą skompilowaną z niepewnych przesłanek) jako „dowód", i błąd wzmacniałby się z pozorem niezależnego potwierdzenia. W praktyce (dopóki `source='wiki'` nie istnieje w bazie) retrieval kompilacyjny i tak nie może dziś trafić na wiki — ale każde zapytanie SQL/`cascade_retrieve`/`hybrid_retrieve` użyte przy kompilacji strony musi jawnie nieść ten filtr od pierwszego dnia, nie dopisany post-factum, gdy wiki już będzie źródłem w bazie. Strony **mogą** linkować się nawzajem przez `[[nazwa-strony]]` (graf, nawigacja) — to **nie jest** to samo co cytowanie jako dowód faktu. Przypisy źródłowe (`[^...]`) zawsze wskazują `envelope_id` (warstwa dowodowa), nigdy inną stronę wiki. ## Integracja z retrievalem (poza zakresem tej fazy) Docelowo strony wiki wchodzą do `kb-postgres` jako koperty `source='wiki'` (`id='wiki:/'`), embedowane tym samym pipeline'em co chunki dokumentów — kaskada retrievalu rozszerza się wtedy o trzeci poziom: wiki → streszczenie → chunk. Nie jest to realizowane w tej fazie (proof-of-concept ręcznej kompilacji 3–5 stron) — patrz `docs/kb/modules/05-faza3-plan.md` §8.2 w `homelab-codex-ws` po szczegóły.