From 9fc6703e2f2c19488575810d36e1b513c39b90b6 Mon Sep 17 00:00:00 2001 From: oskar Date: Thu, 27 Aug 2026 19:55:57 +0200 Subject: [PATCH] docs(kb): scal decyzje (d)-(f) audytu 08-26 do _meta/conventions.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rekoncyliacja faza 5 etap 1 (kb-m5-faza5-wiki.md §4), krok 2 z 3. Trzy decyzje z kb/audits/wiki-kompilat-recon-2026-08-26.md, już wypracowane i zastosowane w bootstrapie sesyjnym (~/kb-wiki-etap1-sesja-2026-08-27/ _meta/conventions.md §5/§7/§8), scalone tu bez duplikowania tego, co w tym repo już było (6 typów wliczając `meta` i sekcja "Brak danych w KB" — obie już scalone wcześniej, commity 156925c i 3bd2441): (d) Fallback envelope-only w przypisach — `[^envelope_id]` bez `#chunk_id`, gdy dowód nie ma konkretnego chunka albo chunk przestał istnieć po re-chunkingu (`document_chunk.id` niestabilny między przebiegami embeddingu). Dopisane do sekcji "Przypisy inline i cytowanie faktów". (e) Sekcja "Niepewne / sprzeczne" jako nazwana sekcja końca strony (już używana de facto na żywych stronach: pzu.md, warta.md, mbank.md — teraz sformalizowana pisemnie) + polityka aktualizacji "dopisz, nie nadpisuj" przy nowym sprzecznym dowodzie, z wyjątkiem dla jawnych aktualizacji tego samego faktu. Nowa sekcja, między "Sprzeczności między źródłami" a "Wersjonowanie dokumentów źródłowych". (f) Inwariant 7 — izolacja retrievalu kompilacji od source='wiki' (mitygacja self-citation/citogenesis), CC/API-only jako wykonawca kompilacji. Nowa sekcja przed "Integracja z retrievalem". Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01W7AnxL6pbgySpEgcCwAfww --- _meta/conventions.md | 72 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/_meta/conventions.md b/_meta/conventions.md index 22d05d5..fac114b 100644 --- a/_meta/conventions.md +++ b/_meta/conventions.md @@ -74,6 +74,18 @@ Format: `[^#]`. Jeden fakt może mieć więcej n 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 @@ -96,6 +108,40 @@ wersjami, nie literówka**; przy sporze o odszkodowanie decyduje wersja obowiąz 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 @@ -169,6 +215,32 @@ Okresowy lint (ręczny w tej fazie, `_meta/lint-reports/YYYY-MM-DD.md`) sprawdza 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'`