3bd24414bd
Przejęte z rekoncyliacji fll-2025-26 (faza 5, etap 1, 2026-08-27) — dwie niezależne kompilacje tej samej strony (2026-07-21 i 2026-08-27) zgodnie używały tego wzorca, ale tylko lipcowa wersja miała go jako nazwaną sekcję. Formalizacja: "Niepewne/sprzeczne" = dowody się kłócą; "Brak danych w KB" = zapytano, zero dowodu w żadną stronę — jawna granica wiedzy korpusu, nie błąd kompilacji.
180 lines
8.6 KiB
Markdown
180 lines
8.6 KiB
Markdown
---
|
||
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: <nazwa strony, czytelna>
|
||
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: `[^<envelope_id>#<document_chunk.id>]`. 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]`.
|
||
|
||
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.
|
||
```
|
||
|
||
## 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).
|
||
|
||
## Integracja z retrievalem (poza zakresem tej fazy)
|
||
|
||
Docelowo strony wiki wchodzą do `kb-postgres` jako koperty `source='wiki'`
|
||
(`id='wiki:<katalog>/<plik>'`), 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.
|