Compare commits
No commits in common. "master" and "task/incident-resolve-fix" have entirely different histories.
master
...
task/incid
|
|
@ -1,34 +1,18 @@
|
|||
---
|
||||
name: kb-publish
|
||||
description: At session close, asks the operator whether to publish the KB site if kb/**/*.md changed this session. Trigger whenever the session is wrapping up (save-session, "kończymy sesję", natural end of task) and this session's own edits, or a merge/diff visible in git, touched files under kb/.
|
||||
description: Reminds the operator to publish the KB site after changes to kb/**/*.md. Trigger whenever this session's own edits, or a merge/diff visible in git, touch files under kb/.
|
||||
---
|
||||
|
||||
## What this skill does
|
||||
|
||||
Trigger point: **session close**, not every response. Session close means the
|
||||
operator signals they're wrapping up — e.g. invoking `save-session`, saying
|
||||
something like "kończymy sesję" / "koniec na dziś" / "wrap up", or the task
|
||||
reaching its natural end with no further work queued. Don't act on this skill
|
||||
mid-session just because a `kb/` file was touched.
|
||||
At the end of your response, if this session touched `kb/**/*.md` — either
|
||||
through your own edits or through a merge/diff you observed in git — append
|
||||
exactly one reminder sentence:
|
||||
|
||||
At that moment, if this session touched `kb/**/*.md` — either through your
|
||||
own edits or through a merge/diff you observed in git — **ask the operator
|
||||
directly**, as a question requiring a yes/no answer, not a passive reminder:
|
||||
> Zmiany w kb/ — pamiętaj odpalić `bash scripts/kb/publish.sh` żeby opublikować.
|
||||
|
||||
> Sesja dotknęła kb/. Zregenerować i zasugerować publikację (`bash scripts/kb/publish.sh`)?
|
||||
|
||||
- If the operator confirms (any affirmative reply): print the ready-to-paste
|
||||
command block so they can copy it straight into their own shell:
|
||||
|
||||
```bash
|
||||
bash scripts/kb/publish.sh
|
||||
```
|
||||
|
||||
Do not run it yourself — see below.
|
||||
- If the operator declines: drop it, nothing more to do.
|
||||
- If the operator doesn't respond or ignores the question (moves on to
|
||||
something else, ends the conversation): do **not** ask again in this
|
||||
session. One ask per session, max.
|
||||
One sentence, no more. Don't repeat it more than once per response, and don't
|
||||
add it if nothing under `kb/` changed.
|
||||
|
||||
## What this skill does NOT do
|
||||
|
||||
|
|
@ -39,4 +23,4 @@ production — that is out of scope for a worktree agent and requires an
|
|||
explicit, direct instruction from the operator in the current turn.
|
||||
|
||||
If the operator explicitly asks you to run it, that instruction stands on its
|
||||
own — this skill only governs the session-close question, not that request.
|
||||
own — this skill only governs the passive reminder, not that request.
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ Agents must never execute destructive actions (restarts, deploys, config changes
|
|||
|
||||
## Event System
|
||||
|
||||
Events are append-only, one JSON file per event, flat under `/opt/homelab/events/<node>/evt-<node>-<unixts>-<type>[-<service>].json`.
|
||||
Events are append-only JSON lines at `/opt/homelab/events/YYYY-MM-DD/<node>/events.jsonl`.
|
||||
|
||||
Emit via `scripts/lib/events.sh` (shell) or `scripts/lib/events.py` (Python).
|
||||
|
||||
|
|
|
|||
|
|
@ -69,139 +69,3 @@ Brak zmian w repo.
|
|||
### Narrative
|
||||
|
||||
> _user-provided summary_
|
||||
|
||||
## Session 23:00
|
||||
|
||||
Deploy control-plane (observer + supervisor) na VPS: stale-resolve 24h +
|
||||
flagi `resolve-requests` (commit `71a7af5`), unikalny `action_id`
|
||||
`container_restart` z bare-id fallbackiem (commit `91db682`), usunięcie
|
||||
gokapi z desired state (commit `74ff3ee`) — zmerdowane do `master` jako
|
||||
`f155999` przez operatora tuż przed sesją. SUPERVISED — checkpoint A po
|
||||
weryfikacji deployu, checkpoint B po teście ścieżki flagi.
|
||||
|
||||
### Commits
|
||||
|
||||
```
|
||||
(brak commitów kodu tej sesji — wyłącznie deploy + test na produkcji;
|
||||
log sesji poniżej dopisany bez pusha)
|
||||
```
|
||||
|
||||
### Files changed
|
||||
|
||||
Brak zmian w repo poza niniejszym logiem.
|
||||
|
||||
### Deploys / operacje na nodach
|
||||
|
||||
**KROK 0 — sanity:** `git pull` na `~/homelab-codex-ws` (SOLARIA, główny
|
||||
checkout) — już aktualny na `03441a1` (na wierzchu mergu `f155999`).
|
||||
`git status`/`diff HEAD` czyste. Wcześniej w tej samej sesji (przed
|
||||
mergem) `git log -1` pokazywał `4fa10f0` — merge jeszcze nie istniał;
|
||||
zatrzymano się i poczekano na operatora zamiast mergować samodzielnie
|
||||
(worktree-aware: merge to wyłącznie krok człowieka).
|
||||
|
||||
**KROK 1 — deploy control-plane (checkpoint A, zatwierdzony):**
|
||||
- Rollback tagi: `control-plane-{executor,observer,operator-ui,supervisor}
|
||||
:rollback-pre-resolvefix` — ten sam wzorzec co `:rollback-pre-dispatchfix`
|
||||
z 08-06.
|
||||
- `git pull origin master` na VPS (`003f83d` → `03441a1`, fast-forward),
|
||||
`docker compose up -d --build --force-recreate`.
|
||||
- `deploy-local.sh`'s auto-chown krok padł: brak TTY dla hasła sudo,
|
||||
`/opt/homelab/backups` i `/opt/homelab/events/solaria/*` są `oskar:oskar`
|
||||
zamiast `aerbot:aerbot` (1000). Sprawdzone: `actions/`, `world/`,
|
||||
`state/`, `config/` (realna ścieżka zapisu control-plane) już poprawnie
|
||||
`aerbot:aerbot 775` — ominięto self-heal, `docker compose` odpalony
|
||||
bezpośrednio bez sudo. Mismatch na `backups/`/`events/solaria/*`
|
||||
pozostawiony nietknięty (follow-up niżej).
|
||||
- Weryfikacja: 4/4 kontenery `healthy`, 0 linii error/traceback/exception
|
||||
od restartu. sha256 `observer.py` (mount `/repo`, żywy) i `supervisor.py`
|
||||
(wypieczony `/app/src`, wymaga `--build`) == repo HEAD, potwierdzone
|
||||
osobno przez `docker exec` w obu kontenerach.
|
||||
- Po 3 cyklach reconcile: `active_incidents: 0`, `world/resolve-requests/`
|
||||
utworzony przez observera (pusty).
|
||||
- `redeploy-vps-gokapi` (pending od 07-09) auto-cancelled po pierwszym
|
||||
cyklu: `cancelled_reason: "service_removed_from_desired_state"` — bez
|
||||
ponownego wygenerowania. `pending/` pozostał czysty (tylko niezwiązane
|
||||
alerty HA z piha).
|
||||
|
||||
**KROK 2 — test ścieżki flagi na LUSTRO (checkpoint B, zatwierdzony):**
|
||||
- `docker stop node-exporter` na LUSTRO → observer otworzył
|
||||
`inc-1787777894-lustro-node-exporter`.
|
||||
- Flaga: `touch world/resolve-requests/<id>` przez zwykłego SSH
|
||||
usera **odrzucony permission denied** — katalog `755 aerbot:aerbot`,
|
||||
brak zapisu grupowego mimo że `oskar` jest w grupie `aerbot`. Obejście:
|
||||
`docker exec control-plane-observer touch ...` (proces w kontenerze
|
||||
działa jako uid 1000 = właściciel katalogu). Follow-up niżej.
|
||||
- Resolve w **1.01 s** od touch (limit ≤10s), `resolved_reason:
|
||||
manual_operator`, flaga skasowana, `service.incident_id` wyczyszczony,
|
||||
log INFO `"Manually resolving incident ... via resolve-request flag"`.
|
||||
- Drift trwał dalej (kontener wciąż stopped) → supervisor wygenerował
|
||||
`container-restart-lustro-node-exporter-1787777887` — **nowy format
|
||||
id z COMMIT 2 potwierdzony na produkcji** — oraz równolegle
|
||||
`redeploy-lustro-node-exporter` (bare id, ścieżka `unhealthy_service`
|
||||
po wyczyszczeniu `incident_id`).
|
||||
- Za decyzją operatora: `POST /action/mutate` na `127.0.0.1:18180`
|
||||
(ten sam endpoint co UI/Telegram) — zatwierdzono restart, odrzucono
|
||||
redeploy jako nadmiarowy.
|
||||
- Executor zdispatchował realnie do LUSTRO; node-agent wykonał
|
||||
`docker restart node-exporter` (log: `"Restarted container
|
||||
'node-exporter' for action container-restart-lustro-node-exporter
|
||||
-1787777887"`), akcja `completed`.
|
||||
- Drift utrzymał się jeszcze chwilę po zatwierdzeniu → drugi, nowy
|
||||
incydent (`inc-1787777955-...`) i druga, odrębna pending akcja
|
||||
(`...-1787777950`, inny suffix `started_at`) — dokładnie oczekiwane
|
||||
zachowanie "różny id przy nowym incydencie". Po powrocie zdrowia
|
||||
auto-cancelled: `cancelled_reason: "drift_resolved_auto"`, bez
|
||||
interwencji.
|
||||
- Stan końcowy: `node-exporter` na LUSTRO `Up`, oba incydenty
|
||||
`resolved`, `active_incidents: 0`, `pending/` czysty, 4/4 kontenery
|
||||
control-plane nadal `healthy`, 0 error-ish linii w logach.
|
||||
|
||||
### Follow-upy
|
||||
|
||||
- **pytest env zepsuty na SOLARII**: `~/.local/bin/pytest` (brak
|
||||
`_pytest`) i `homelab-codex-ws/.venv` (brak `pytest` w ogóle) oba
|
||||
niedziałające; działa wyłącznie `/home/oskar/anaconda3/bin/pytest`
|
||||
(7.4.4). Użyty do pełnego runu przed force-pushem poprawki COMMIT 2
|
||||
(184 passed control-plane, 70 passed node-agent).
|
||||
- **`world/resolve-requests/` permissions**: `755 aerbot:aerbot` zamiast
|
||||
konwencji `775` używanej w `actions/`/`world/`/`state/`/`config/`.
|
||||
Blokuje operatora SSH przed bezpośrednim `touch` flagi resolve —
|
||||
manualna ścieżka z 71a7af5 ("operator drops a file") w praktyni wymaga
|
||||
`docker exec`. Poprawić `chmod 775` / mode przy `os.makedirs` w
|
||||
observer.py.
|
||||
- **`backups/` i `events/solaria/*` ownership**: `oskar:oskar` zamiast
|
||||
`aerbot:aerbot` — nie blokuje funkcjonalnie (czytelne dla "other"), ale
|
||||
psuje self-heal chown w `deploy-local.sh` (próbuje rekurencyjnego sudo
|
||||
chown całego `/opt/homelab` bez TTY/hasła). Do ręcznego wyczyszczenia
|
||||
z hasłem sudo albo do zmiany self-heal na scoped (tylko katalogi
|
||||
control-plane realnie potrzebuje) zamiast całego drzewa.
|
||||
- **CLAUDE.md doc drift**: opisuje `events/YYYY-MM-DD/<node>/events.jsonl`,
|
||||
rzeczywisty layout na VPS to płaskie `events/<node>/evt-*.json` (jeden
|
||||
plik na zdarzenie, bez partycjonowania po dacie). Do poprawienia przy
|
||||
najbliższej okazji.
|
||||
- `redeploy-vps-gokapi` — zamknięty tym deployem (auto-cancelled), nie
|
||||
wymaga już dalszego follow-upu z sesji 16:00.
|
||||
|
||||
### Narrative
|
||||
|
||||
> _user-provided summary_
|
||||
|
||||
## Session 23:06
|
||||
|
||||
### Commits
|
||||
|
||||
```
|
||||
(brak commitów — sesja bez żadnej pracy poza natychmiastowym zamknięciem)
|
||||
```
|
||||
|
||||
### Files changed
|
||||
|
||||
Brak zmian w repo.
|
||||
|
||||
### Deploys
|
||||
|
||||
None recorded
|
||||
|
||||
### Narrative
|
||||
|
||||
> _user-provided summary_
|
||||
|
|
|
|||
|
|
@ -1,59 +0,0 @@
|
|||
---
|
||||
okf: "0.1"
|
||||
type: session-log
|
||||
visibility: private
|
||||
status: active
|
||||
updated: 2026-08-27
|
||||
links:
|
||||
- ../../kb/phases/kb-m5-faza5-wiki.md
|
||||
- ../../kb/phases/kb-m5-faza3.md
|
||||
- ../../kb/audits/wiki-kompilat-recon-2026-08-26.md
|
||||
---
|
||||
|
||||
# Sesja 2026-08-27 — Faza 5: decyzje + Etap 1 + rekonсyliacja (ZAMKNIĘTY)
|
||||
|
||||
## Timeline
|
||||
|
||||
- **Sanity** — automat mailowy zdrowy po nocy (last_success świeży, gmail
|
||||
max(ts) bieżący).
|
||||
- **Formalizacja decyzji** (2df4f1d i wcześniejsze) — pakiet (a)-(h) audytu
|
||||
`wiki-kompilat-recon-2026-08-26.md` ZATWIERDZONY w całości; inwariant 7
|
||||
dopisany do faza3 §8.1 (izolacja retrievalu kompilacji od `source='wiki'`);
|
||||
`check_okf.py` łapie bajty kontrolne (nowy check #12 + testy) — 4 NUL-e
|
||||
usunięte z samego audytu.
|
||||
- **Etap 1** (`task/wiki-etap1`, autonomiczny run CC ~25 min) — bootstrap +
|
||||
3 strony proof (`sprawy/fll-2025-26`, `podmioty/mbank`,
|
||||
`osoby/pawel-cesar-sanjuan-szklarz`). 40 sources + 47 przypisów
|
||||
zweryfikowanych byte-for-byte, zero degradacji. Alias-resolution: 6 er
|
||||
życia Pawła spójnie + 2 fałszywe pozytywy pod `paweld2.eu` wykryte i
|
||||
udokumentowane jako wynik negatywny (kluczowy test mechanizmu PASS).
|
||||
- **ODKRYCIE** — kb-wiki istniało na Forgejo od 2026-07-21 (5 stron: `pzu`,
|
||||
`warta`, `ubezpieczenie-auto`, `fll-2025-26`, `wspólnota`) — proof
|
||||
wykonany w fazie 3 (wątek "Kontynuacja wątku o KB", decyzja D7),
|
||||
nieodnotowany w `kb/` ani w audycie. Recon 08-26 błędnie stwierdził
|
||||
"remote nie istnieje" — sprawdził repo/pilota/bazę, nie odpytał Forgejo
|
||||
bezpośrednio.
|
||||
- **LEKCJA 1**: fakty wykonania muszą lądować w repo (lekcja 6 narty27 w
|
||||
praktyce — zgubiliśmy całe repo na 5 tygodni).
|
||||
- **LEKCJA 2**: recon zasobów zewnętrznych odpytuje źródło wprost, nie
|
||||
wnioskuje z planów.
|
||||
- **Rekonсyliacja** — porównanie dwóch niezależnych kompilacji `fll-2025-26`
|
||||
(lipiec paperless-only vs sierpień paperless+gmail): komplementarne, zero
|
||||
sprzeczności w faktach wspólnych; konwergencja metodologiczna (obie sesje
|
||||
ten sam chunk 277/278, obie odmówiły potwierdzenia nieczytelnego OCR).
|
||||
Scalenie: 21 envelope, 38 par sources, 45 przypisów re-zweryfikowanych;
|
||||
naprawiony wadliwy lipcowy przypis; konwencja "Brak danych w KB"
|
||||
sformalizowana. Potem mbank+paweł przeniesione do kanonicznego repo,
|
||||
konwencje (d)-(f) scalone, walidator w repo. Stan końcowy kb-wiki@Forgejo
|
||||
`a540a99`: 7 stron, lint 74/74 sources + 150/150 inline zielono.
|
||||
- **kb-wiki remote** przepięty HTTPS→SSH (port 222).
|
||||
- **Kandydat Etapu 2** wykryty SQL-em: `podmioty/future-minds` (organizator
|
||||
FLL, 8+ dokumentów).
|
||||
- **Follow-upy bez zmian**: rotacja sekretów (kb-postgres + `TG_TOKEN` —
|
||||
NADAL WISI), fix UID SEARCH, PDF-y, charset, R1/R2 z incydentu 26.08.
|
||||
|
||||
## Stan Fazy 5
|
||||
|
||||
- Etap 1 ✓ (2026-08-27). Next: Etap 2 — skala do 17+1 encji, lint w kodzie,
|
||||
skan charset/NUL, decyzja o integracji `source='wiki'` w retrievalu
|
||||
(inwariant 7 obowiązuje).
|
||||
|
|
@ -1,23 +0,0 @@
|
|||
## Session 13:49
|
||||
|
||||
### Commits
|
||||
a97cec0 merge: task/drobne-fixy (resolve-requests 775, prune out of health-monitor, events doc, redeploy action_id)
|
||||
1dca438 fix(supervisor): apply started_at suffix to redeploy action_id too
|
||||
40d78ce docs: fix events layout drift in CLAUDE.md
|
||||
9a86843 fix(monitor): remove unfiltered docker container prune from health-monitor.sh
|
||||
89f75c3 fix(observer): make world/resolve-requests/ group-writable
|
||||
|
||||
### Files changed
|
||||
CLAUDE.md | 2 +-
|
||||
scripts/monitor/health-monitor.sh | 110 +++------------------
|
||||
scripts/observer/observer.py | 12 +++
|
||||
services/control-plane/src/supervisor.py | 40 ++++----
|
||||
.../control-plane/tests/test_incident_lifecycle.py | 17 ++++
|
||||
.../tests/test_supervisor_action_id_uniqueness.py | 50 +++++++++-
|
||||
6 files changed, 109 insertions(+), 122 deletions(-)
|
||||
|
||||
### Deploys
|
||||
- control-plane → VPS: tagged 4/4 images `:rollback-pre-drobnefixy`, `git pull` (03441a1→a97cec0) + `docker compose up -d --build --force-recreate` (direct, no deploy-local.sh, per 26.08 precedent). Result: 4/4 healthy, zero error/traceback in logs since restart, sha256 of observer.py and supervisor.py match HEAD, `world/resolve-requests/` mode 775 confirmed, incidents.json stable (md5 unchanged) over 3 observer cycles. 30s permission test: flag `test-perms-123` dropped via plain `ssh` as `oskar` (no docker exec) was picked up and deleted in ~5s with `WARNING - Resolve-request flag for unknown incident test-perms-123 — removing flag` — 775 confirmed working in practice.
|
||||
|
||||
### Narrative
|
||||
> _user-provided summary_
|
||||
|
|
@ -1,856 +0,0 @@
|
|||
---
|
||||
okf: "0.1"
|
||||
type: audit
|
||||
visibility: private
|
||||
status: active
|
||||
updated: 2026-08-27
|
||||
as_of: 2026-08-26
|
||||
links:
|
||||
- ../phases/kb-m5-faza3.md
|
||||
- ../phases/kb-m5-faza-mailowa.md
|
||||
- ../services/narty27.md
|
||||
- ../services/kb-query.md
|
||||
- ../services/kb-site.md
|
||||
- ../subsystems/kb-mail-pillar.md
|
||||
- ../subsystems/kb-overview.md
|
||||
- ../subsystems/kb-documents-pillar.md
|
||||
- ../subsystems/recon-multiagent.md
|
||||
- ../decisions/architektura-2026-07-28.md
|
||||
- ../decisions/backlog-aktywne.md
|
||||
- ../incidents/2026-08-26-mail-sync-20-dni-ciszy.md
|
||||
- ../audits/mail-sync-2026-08-06.md
|
||||
- ../runbooks/mail-sync-run.md
|
||||
- ../services/job-mail-imap-sync.md
|
||||
- ../services/pkg-kb-retrieval.md
|
||||
---
|
||||
|
||||
# Recon — wiki-kompilat (faza 5), 2026-08-26
|
||||
|
||||
Read-only recon. Zakres: przygotowanie fazy 5 subsystemu B (KB) — syntezy wiki nad
|
||||
warstwą dowodową RAG/pgvector. Zlecenie: zbadać 9 punktów (lokalizacja, bootstrap
|
||||
encji, tryb kompilatora, format linku dowodowego, anty-propagacja, integracja z
|
||||
kb-query, zależności/kolizje, plan iteracji, decyzje operatora) i wynieść wniosek
|
||||
per punkt. **Nic nie zostało zaimplementowane, zdeployowane ani skommitowane poza
|
||||
tym dokumentem.**
|
||||
|
||||
Dowody: repo (worktree `task/wiki-kompilat-recon`, cięty z mastera @ `4fa10f0`),
|
||||
pilot `~/narty-2027/saalbach-kb` na SOLARII (lokalny odczyt), żywa baza `kb` na
|
||||
PIHA przez `ssh piha 'docker exec kb-postgres psql ...'` (SELECT-y, zero zapisów),
|
||||
`systemctl status` na PIHA dla stanu timerów.
|
||||
|
||||
**Znalezisko nadrzędne, zanim cokolwiek innego:** to nie jest recon od zera.
|
||||
`kb/phases/kb-m5-faza3.md` §8 zawiera **już zatwierdzony przez operatora szkic
|
||||
architektoniczny** wiki-kompilatu (decyzja 2026-07-15, opisana jako „NIE podlega
|
||||
zmianie") plus rozwinięcie wykonawcze (§8.2, 2026-07-17) z konkretnymi
|
||||
rozstrzygnięciami: osobne repo `kb-wiki`, struktura katalogów, format frontmattera
|
||||
z blokiem `sources`, inline-przypisy `[^envelope_id#chunk_id]`, trzypoziomowa
|
||||
kaskada retrievalu `wiki → summary → chunk`, kompilacja przez CC/API, lint
|
||||
okresowy, pętla zwrotna. Zadanie tego reconu — tak jak je czytam — to **zweryfikować
|
||||
te ustalenia w świetle tego, co się wydarzyło od 07-17** (pilot narty27, cała faza
|
||||
mailowa, incydent 20 dni ciszy), dociągnąć luki, których tamten szkic nie
|
||||
rozstrzygał (chunk-id vs re-chunking, self-citation, konkretna lista encji z
|
||||
prawdziwych danych), i złożyć to w plan pierwszego etapu. Poniżej cytuję zamiast
|
||||
odtwarzać, i mówię wprost, gdzie się zgadzam, a gdzie proponuję dociągnięcie.
|
||||
|
||||
---
|
||||
|
||||
## 1. Stan korpusu na dziś (2026-08-26) — czy blokada z faza3 jest zdjęta
|
||||
|
||||
`kb/phases/kb-m5-faza3.md:628`, cytat ze szkicu operatora: *„Pełna wiki po fazie
|
||||
mailowej (przyrostówka) — wcześniej kompilat byłby fotografią przeszłości."*
|
||||
`kb/audits/mail-sync-2026-08-06.md` §7 nazywa to *jedyną znalezioną jawną
|
||||
zależność „X czeka na przyrostówkę" w całym KB*.
|
||||
|
||||
Zmierzone dziś na żywej bazie:
|
||||
|
||||
```sql
|
||||
SELECT source, max(ts)::date AS latest, count(*) FROM envelope GROUP BY 1;
|
||||
```
|
||||
|
||||
| source | latest | count |
|
||||
|---|---|---|
|
||||
| gmail | **2026-08-26** | 227 280 |
|
||||
| fastmail | **2026-08-26** | 105 |
|
||||
| paperless | 2026-07-13 | 191 |
|
||||
|
||||
```sql
|
||||
SELECT count(*) FROM document_chunk WHERE embedding IS NULL AND excluded_reason IS NULL;
|
||||
-- → 0
|
||||
```
|
||||
|
||||
Korpus mailowy sięga **dziś**, nie 2026-06-19 jak w audycie 08-06 — incydent
|
||||
[20 dni ciszy](../incidents/2026-08-26-mail-sync-20-dni-ciszy.md) naprawiony tego
|
||||
samego dnia co to zlecenie domknął przyrostówkę: kursor dogonił IMAP, 548
|
||||
zaległych kopert wchłonięte, zero błędów. `kb-mail-sync.timer` (co godzinę) i
|
||||
`kb-ingest.timer` (co 2h, embed) oba `active (waiting)` na PIHA, żywe od
|
||||
2026-08-06, bez przerwy odkąd monitoring realnie działa (od tego samego
|
||||
incydentu). Embed backlog = **0** — nic nie czeka na wektor.
|
||||
|
||||
**Wniosek: blokada z faza3 jest zdjęta dziś, nie wcześniej.** To jest właściwy
|
||||
moment na ten recon — zrobiony tydzień wcześniej trafiłby na korpus wciąż
|
||||
urwany, a wiki-kompilat skompilowałby na trwałe fotografię z czerwca. Warto
|
||||
odnotować kruchość tego stanu: przyrostówka działa dzięki jednemu `chown` i
|
||||
jednemu `/-/reload`, oba ręczne, oba bez automatyzacji (R1/R2 z incydentu —
|
||||
poprawna własność katalogów przy `sudo`-runach i reload reguł Prometheusa w
|
||||
deployu — zostają otwarte). Faza 5 dziedziczy to ryzyko: gdyby przyrostówka
|
||||
znów ucichła cicho, wiki-kompilat kompilowałby dalej z coraz starszej wody, bez
|
||||
sygnału. Patrz §7 niżej (interakcja z monitoringiem `KbMailSyncStale`).
|
||||
|
||||
**191 kopert paperless** nie rosną od 2026-07-13 — to osobny fakt: paperless nie
|
||||
ma przyrostówki (dokumenty trafiają tam ręcznie), niezwiązany z blokadą mailową.
|
||||
Nie wstrzymuje fazy 5.
|
||||
|
||||
---
|
||||
|
||||
## 2. Punkt 1 — Lokalizacja wiki: `kb/wiki/` w repo vs osobne repo
|
||||
|
||||
### Co już zdecydowano
|
||||
|
||||
`kb-m5-faza3.md` §8.2: *„Repozytorium (rozstrzygnięcie punktu 6 szkicu): osobne
|
||||
repo `kb-wiki` — decyzja 7, uzasadnienie w §2. Klon roboczy na PIHA:
|
||||
`/opt/homelab/data/kb-wiki/`."* — i dalej: *„D7 — rekomendacja: osobne
|
||||
`kb-wiki`"* w podsumowaniu (§12). To jest już podjęta decyzja, nie propozycja.
|
||||
|
||||
### Weryfikacja na wzorcu pilota
|
||||
|
||||
narty27 (`~/narty-2027/saalbach-kb`) **potwierdza ten wzorzec empirycznie**:
|
||||
`kb/services/narty27.md` — *„Content is personal and lives outside the repo… It
|
||||
is never committed — not to this repo, not to any other."* Źródło leży w osobnym
|
||||
lokalnym gicie na SOLARII, poza `homelab-codex`, infra (`services/narty27`)
|
||||
zostaje w `homelab-codex`. Dokładnie ten sam split, jaki faza3 projektuje dla
|
||||
`kb-wiki`: **treść osobno, infrastruktura hostująca w repo.**
|
||||
|
||||
### Rekomendacja: potwierdzam D7 (osobne repo), z jednym doprecyzowaniem
|
||||
|
||||
Zgadzam się z decyzją bez zmian co do kierunku. Powody, które faza3 już podała
|
||||
i które podtrzymuję:
|
||||
|
||||
1. **Cykl życia inny niż kodu infry.** Commity do `kb-wiki` będą częste,
|
||||
drobne, generowane maszynowo (`compile: <strona> ← <envelope_ids>`) —
|
||||
zalałyby historię `homelab-codex-ws`, gdzie commituje operator ręcznie i
|
||||
rzadko (`CLAUDE.md`: *„Primary control node — only node where commits are
|
||||
made"*).
|
||||
2. **Widoczność `visibility` per strona nie mapuje się na model `homelab-codex`.**
|
||||
`check_okf.py` tego repo ma zamkniętą listę `TYPES` i regułę `POINTER_GLOBS`/
|
||||
`EXCLUDE_DIRS` dopasowaną do tego, co tu jest — dodanie setek stron-encji
|
||||
(firmy, osoby, sprawy) do `kb/` zaszumiłoby indeks tego repo i pomieszałoby
|
||||
dwa różne reżimy publikacji (kb-site publikuje `visibility: public` z `kb/`;
|
||||
`kb-wiki` potrzebuje **własnego**, bo część stron — dane osobowe, umowy,
|
||||
ludzie — nigdy nie powinna nawet teoretycznie wpaść w tę samą ścieżkę co
|
||||
dokumentacja infrastruktury).
|
||||
3. **Rozmiar.** Korpus mailowy to 227k+ kopert; nawet skromna kompilacja
|
||||
(setki stron) to inny rząd wielkości commitów niż `homelab-codex-ws` widział
|
||||
kiedykolwiek. Osobne repo izoluje ten wzrost od repo, które operator
|
||||
przegląda i na którym pracują agenty infrastrukturalne.
|
||||
|
||||
**Doprecyzowanie względem faza3:** szkic nie rozstrzyga *dostępu CC w
|
||||
worktree*. `homelab-codex-ws` ma wzorzec `agent.sh new` → worktree per task,
|
||||
każdy dostaje pełne repo `homelab-codex-ws` sklonowane z gita. `kb-wiki` **nie
|
||||
jest** tym repo — sesja kompilująca stronę potrzebuje **dwóch** klonów
|
||||
jednocześnie: `homelab-codex-ws` (żeby czytać `packages/kb-retrieval`, DSN,
|
||||
`.env` na PIHA) i `kb-wiki` (żeby pisać stronę). To nie jest problem dla
|
||||
worktree pojedynczej sesji CC odpalonej ręcznie na PIHA/SOLARII z dwoma
|
||||
katalogami obok siebie — **jest** problemem dla wzorca `scripts/dev/agent.sh
|
||||
new`, który zna tylko jedno repo. Rekomendacja: kompilacja wiki **nie** idzie
|
||||
przez `agent.sh`-owe worktree `homelab-codex-ws` — to osobny tryb pracy
|
||||
(sesja CC z dwoma katalogami roboczymi, jak dziś narty27 na SOLARII), do
|
||||
zapisania w `kb-wiki/_meta/conventions.md`, nie w tym repo.
|
||||
|
||||
### Publish.sh i public/private per strona
|
||||
|
||||
`kb-site` (`services/kb-site/`) publikuje wyłącznie `kb/**/*.md` z
|
||||
`visibility: public`, fail-closed, przez token w URL (`kb-e2a24af3.okit.pl`).
|
||||
`kb-wiki` leżący poza `kb/` **nie wejdzie** do tego pipeline'u automatycznie —
|
||||
i to dobrze, bo strony wiki (dane o ludziach, umowach, finansach) mają zupełnie
|
||||
inny profil ryzyka publikacji niż dokumentacja infrastruktury. Jeśli/kiedy
|
||||
pojawi się potrzeba publicznej (lub choćby LAN-owej) wystawki `kb-wiki`, to
|
||||
osobny generator + osobny serwis (wzorzec `narty27`: nginx + named volume,
|
||||
`exposure: private` domyślnie), **nie** rozszerzenie `gen_pages.py`. Na tym
|
||||
etapie (proof-of-concept, 3–10 stron) nie ma potrzeby stawiać hostingu w ogóle
|
||||
— `git log`/`cat` na PIHA wystarczy do przeglądu.
|
||||
|
||||
---
|
||||
|
||||
## 3. Punkt 2 — Bootstrap: analiza korpusu i lista encji zalążkowych
|
||||
|
||||
### Zapytania i wyniki (żywa baza, 2026-08-26)
|
||||
|
||||
**Wolumen per rok/źródło** (`envelope`, pełne dane w §1 wyżej dla świeżości;
|
||||
poniżej rozkład historyczny):
|
||||
|
||||
```sql
|
||||
SELECT source, date_trunc('year', ts) AS yr, count(*) FROM envelope GROUP BY 1,2 ORDER BY 1,2;
|
||||
```
|
||||
|
||||
Szczyt 2011–2012 (~23k/rok — dawny pracodawcy przez `outbox.pl`), potem
|
||||
stabilne 9–13k/rok 2013–2025. 2 559 kopert `ts`=epoch 1970 (daty nieodzyskane,
|
||||
opisane w `kb-overview.md` backlog).
|
||||
|
||||
**Top nadawcy wśród kopert, które realnie mają zaembedowany, nie-wykluczony
|
||||
chunk** (czyli faktycznie trafiają w wyniki `/search` — to jest właściwe sito
|
||||
pod encje, nie surowy wolumen, który zdominowany jest przez newslettery
|
||||
wykluczone z indeksu):
|
||||
|
||||
```sql
|
||||
SELECT h->'from'->>'name', h->'from'->>'address', count(DISTINCT e.id),
|
||||
min(e.ts)::date, max(e.ts)::date
|
||||
FROM envelope e
|
||||
JOIN jsonb_array_elements(e.entities) h ON h->>'type' = 'headers'
|
||||
WHERE EXISTS (SELECT 1 FROM document_chunk c
|
||||
WHERE c.envelope_id = e.id AND c.embedding IS NOT NULL AND c.excluded_reason IS NULL)
|
||||
GROUP BY 1,2 ORDER BY 3 DESC LIMIT 40;
|
||||
```
|
||||
|
||||
| Nadawca | Adres | Koperty | Zakres |
|
||||
|---|---|---|---|
|
||||
| oskar kapala | oskar.kapala@gmail.com | 10 021 | 2005–2020 |
|
||||
| Oskar Kapala | oskar.kapala@outbox.pl | 6 399 | (epoch)–2014 |
|
||||
| Kasia Lorenc-Kapala | katalia@gmail.com | 3 385 | 2007–2026 |
|
||||
| Oskar Kapala | oskar.kapala@gmail.com | 2 910 | 2010–2026 |
|
||||
| System Synergia | robot2@robot.librus.pl | 2 818 | 2018–2026 |
|
||||
| Allegro | powiadomienia@allegro.pl | 2 170 | 2008–2026 |
|
||||
| Tomasz Anuszewski | tomasz.anuszewski@outbox.pl | 1 913 | 2011–2012 |
|
||||
| Dziennik Bankier.pl (×2 adresy) | …bankier.pl | 1 736 + 1 676 | 2007–2014 |
|
||||
| RSW_TECH_TEAM | rsw_tech_team@outbox.pl | 1 628 | 2011–2012 |
|
||||
| Groupon | info@news.groupon.pl | 1 447 | 2011–2012 |
|
||||
| Miron Mironiuk | m@cosmose.co | 1 126 | 2015–2016 |
|
||||
| kontakt@mbank.pl | | 1 099 | 2005–2026 |
|
||||
| Jan Boboli | jan.boboli@outbox.pl | 969 | 2011–2013 |
|
||||
| Paweł Cesar Sanjuan Szklarz | paweld2@gmail.com, pawel@cosmose.co | 757+555+418+376 | 2005–2024 |
|
||||
| InPost | info@paczkomaty.pl | 722 | 2017–2026 |
|
||||
| Bogumil Jakubiak | B.Jakubiak@icm.edu.pl | 686 | 2004–2009 |
|
||||
| sOKratis Liliana Banaszak | liliana.banaszak@sokratis.pl | 679 | 2009–2026 |
|
||||
| Strava | update.strava.com / strava.com | 591+395 | 2017–2026 |
|
||||
|
||||
**Domeny** (§2, po odsianiu marketingu/newsletterów po heurystyce
|
||||
`noreply|notification|robot|mailer`): `outbox.pl` (39,4k — domena prywatna
|
||||
operatora, alias `oskar.kapala@outbox.pl` + koledzy z tej samej domeny =
|
||||
prawdopodobnie dawny pracodawca/hosting), `gmail.com`, `cosmose.co` (2 982,
|
||||
firma — Miron Mironiuk + Paweł Szklarz), `icm.edu.pl`/`students.mimuw.edu.pl`
|
||||
(uczelnia/ICM UW), `mbank.pl`/`bankier.pl` (finanse), `sokratis.pl`.
|
||||
|
||||
**Paperless — 191 kopert, w większości streszczone** (`document_summary`,
|
||||
162 `claude-haiku-4-5` + 155 `gemma3:12b`, prawie 1:1 pokrycie). Próbka
|
||||
streszczeń pokazuje wyraźne klastry tematyczne:
|
||||
|
||||
| Klaster | Liczba (próbka 40 najnowszych) | Przykład |
|
||||
|---|---|---|
|
||||
| FIRST LEGO League / Fundacja Future Minds | 8 | zgody na wizerunek, karty wyników, harmonogramy |
|
||||
| Regulaminy OLX (pakiety, ochrona kupującego, ads) | 5 | umowa serwisowa |
|
||||
| Revolut (krypto, regulaminy, cennik) | 4 | umowa finansowa |
|
||||
| Spółdzielnia Mieszkaniowa „Przy Metrze" | 2 | RODO, dane kontaktowe |
|
||||
| Ubezpieczenia (PZU OC, itp.) | 2 | polisa |
|
||||
| Wynajem auta (Dollar, Madryt) | 2 | rezerwacja |
|
||||
| Faktura (ZigBee, Oskar Kapała Rozwiązania IT — działalność gospodarcza) | 1 | dowód zakupu |
|
||||
|
||||
### Kryterium kolejności
|
||||
|
||||
Trzy sygnały, w tej kolejności ważności:
|
||||
|
||||
1. **Obecność w indeksowanym (nie-wykluczonym) korpusie** — encja musi mieć
|
||||
realne pokrycie w `document_chunk` z wektorem, inaczej strona kompiluje się
|
||||
z pustki. To jedyny twardy filtr (zastosowany w zapytaniu wyżej).
|
||||
2. **Wielowątkowość źródeł** — encje, które łączą paperless (dokument formalny:
|
||||
umowa, polisa, regulamin) *i* gmail (korespondencja o tej samej sprawie),
|
||||
są lepszymi kandydatami na `sprawy`/`umowy` niż encje widoczne tylko w
|
||||
jednym źródle — bo demonstrują dokładnie to, co ma udowodnić wiki-kompilat
|
||||
(Karpathy-wzorzec: strona syntezuje, nie kopiuje jednego dokumentu).
|
||||
3. **Rozstrzygalność, nie wolumen.** `outbox.pl`/`Tomasz Anuszewski`/`Jan
|
||||
Boboli`/`RSW_TECH_TEAM` mają duży wolumen (2011–2012), ale to zamknięty w
|
||||
czasie epizod (prawdopodobnie dawny pracodawca) — dobry kandydat na
|
||||
`podmiot`, zły na pierwszy PoC, bo wymaga ustalenia kontekstu (kim była ta
|
||||
firma), którego recon nie ma. Odłożone na drugą turę, nie na pierwszą.
|
||||
|
||||
### Proponowana lista 10–20 encji zalążkowych
|
||||
|
||||
| # | Strona | Typ | Uzasadnienie (z danych) |
|
||||
|---|---|---|---|
|
||||
| 1 | `fll-2025-26` | sprawa | 8/40 streszczeń paperless; żywa sprawa (2026), krzyżuje szkołę + fundację + dziecko |
|
||||
| 2 | `future-minds` (fundacja) | podmiot | organizator FLL, NIP w danych, kontakt jawny w treści dokumentów |
|
||||
| 3 | `spoldzielnia-przy-metrze` | podmiot | nieruchomość, RODO + dane kontaktowe, aktywna (bieżąca korespondencja o pożarówce 2026) |
|
||||
| 4 | `revolut` | podmiot | 4 dokumenty regulaminowe w próbce, konto aktywne (kontekst kryptowalut) |
|
||||
| 5 | `mbank` | podmiot | 1 099 kopert 2005–2026, ciągłość 20 lat, kontakt@mbank.pl + dziennik bankier.pl (powiązana marka) |
|
||||
| 6 | `pzu` | podmiot | kandydat wymieniony wprost w szkicu operatora (§8.1 przykład), polisa OC w paperless |
|
||||
| 7 | `cosmose` (firma) | podmiot | 2 982 kopert, dwóch nazwanych korespondentów (Mironiuk, Szklarz) — test cross-osoba w jednym podmiocie |
|
||||
| 8 | `miron-mironiuk` | osoba | 1 126 kopert, jeden zidentyfikowany adres, powiązanie z `cosmose` |
|
||||
| 9 | `pawel-cesar-sanjuan-szklarz` | osoba | 4 warianty adresu/nazwy (757+555+418+376 kopert) — dobry test entity resolution na aliasach tej samej osoby |
|
||||
| 10 | `librus-synergia` | temat | 2 818 kopert 2018–2026, szkoła dzieci, ciągły strumień — test strony-tematu o dużym, jednorodnym źródle |
|
||||
| 11 | `inpost-paczkomaty` | temat | 722+681 (dwa nadawcy tej samej usługi) — test scalania dwóch adresów jednej usługi w jedną stronę |
|
||||
| 12 | `strava` | temat | 591+395, dwa adresy tej samej usługi, 2017–2026 ciągłe |
|
||||
| 13 | `bogumil-jakubiak` | osoba | ICM UW, 2004–2009 — zamknięty epizod, test strony `status: archived` |
|
||||
| 14 | `wynajem-samochodow` (Dollar/Madryt) | temat | rezerwacja 2026, dwa powiązane dokumenty paperless (potwierdzenie różnymi kanałami tej samej rezerwacji) — test dedupu treści |
|
||||
| 15 | `dzialalnosc-gospodarcza` (Oskar Kapała Rozwiązania IT) | podmiot | faktura w paperless, własna działalność — inny rejestr niż korespondencja prywatna |
|
||||
| 16 | `sokratis` | podmiot | 679 kopert 2009–2026, ciągłość 17 lat, nazwany kontakt (Liliana Banaszak) |
|
||||
| 17 | `allegro` | temat | 2 170 kopert 2008–2026 — najdłuższa ciągła relacja handlowa w korpusie |
|
||||
| 18–20 | (druga tura, po pierwszej weryfikacji) | — | `outbox.pl`/dawny pracodawca po ustaleniu kontekstu; `PZU`↔`mbank` cross-link jako pierwszy test grafu `sprawy` łączących dwa `podmioty` |
|
||||
|
||||
17 pozycji zamiast równych 20 — reszta świadomie zostawiona na drugą turę
|
||||
zamiast dopełniana sztucznie (Bogumil Jakubiak/ICM to jedyny archiwalny/
|
||||
zamknięty przypadek na liście — reszta to żywe encje; warto mieć chociaż jeden
|
||||
przykład `status: archived` w PoC, żeby lint (inwariant 3) miał co sprawdzać
|
||||
na obu stanach od pierwszego dnia).
|
||||
|
||||
---
|
||||
|
||||
## 4. Punkt 3 — Tryb kompilatora: batch / pipeline / hybryda
|
||||
|
||||
### Co już zdecydowano
|
||||
|
||||
Faza3 §8.2, inwariant 2: *„Kompilację i lint robi CC/zewnętrzne API… Sesja
|
||||
CC/API dostaje wyniki retrievalu dla encji… pisze/aktualizuje stronę,
|
||||
commituje do kb-wiki."* To opisuje **batch przez sesje CC** — potwierdzone też
|
||||
przez operatora w zleceniu tego reconu („Utrzymanie: CC/API — lokalny model za
|
||||
słaby — rozstrzygnięte"). Nie podważam tego kierunku; on jest już przesądzony.
|
||||
Pytanie, które faza3 zostawia otwarte, to **rytm**: czy kompilacja jest
|
||||
wyłącznie ręcznie wyzwalanym batchem, czy dostaje automatyczny trigger, i jak
|
||||
zamyka się pętla zwrotna (inwariant 4: *„dobre odpowiedzi z zapytań wracają do
|
||||
wiki jako nowe strony"*).
|
||||
|
||||
### Trzy tryby, ocenione pod kątem tego, co ta faza faktycznie robi
|
||||
|
||||
**(A) Czysty batch (sesja CC, ręcznie wyzwalana).** Operator albo agent
|
||||
odpala sesję z listą encji, sesja robi N zapytań do `hybrid_retrieve`/
|
||||
`cascade_retrieve`, pisze/aktualizuje strony, commituje. Koszt: **przewidywalny
|
||||
i widoczny w moment wywołania** — tyle, ile ta jedna sesja zużyje tokenów API.
|
||||
Częstotliwość: kiedy operator zdecyduje (np. raz na kilka sesji roboczych KB).
|
||||
|
||||
**(B) Job z pipeline'em eskalacji (per-query, automatyczny).** Każde
|
||||
zapytanie do `kb-query` /search, które trafia próg (`dist`, heurystyki),
|
||||
eskaluje do API i **automatycznie** zapisuje/aktualizuje stronę wiki z
|
||||
odpowiedzi. To bezpośrednio realizuje pętlę zwrotną (inwariant 4) bez udziału
|
||||
człowieka w każdym pojedynczym zapisie.
|
||||
|
||||
**(C) Hybryda: bootstrap batch, utrzymanie pipeline.** Pierwsza fala stron
|
||||
(PoC, potem szersza kompilacja korpusu) idzie trybem (A) — bo trzeba pokryć
|
||||
setki/tysiące encji z pustego stanu, co jest z natury wsadowe i wymaga
|
||||
przeglądu jakości. Po ustabilizowaniu wiki, dopisywanie/aktualizacja idzie
|
||||
trybem (B), zdarzeniowo, przy okazji zapytań `/search`, które i tak przechodzą
|
||||
przez `kb-query`.
|
||||
|
||||
### Rekomendacja: (C), z (B) odłożonym poza zakres tej fazy
|
||||
|
||||
Uzasadnienie:
|
||||
|
||||
1. **Skala nie pozwala na (B) od startu.** `kb-query` dziś **nie robi syntezy
|
||||
odpowiedzi** — to jawnie zapisane w `kb/services/kb-query.md` (*„This is a
|
||||
search API, not chat: no answer synthesis over results, that's phase 5"*).
|
||||
Automatyczny zapis strony z „dobrej odpowiedzi" wymaga najpierw tej
|
||||
syntezy (LLM nad wynikami retrievalu) — a to jest osobny, jeszcze
|
||||
niezbudowany komponent, w planie `kb-m5-faza-mailowa.md` §11 zapisany jako
|
||||
*„Synteza odpowiedzi + polityka eskalacji | faza 5 | po fazie 3/4"*.
|
||||
Innymi słowy: (B) zakłada istnienie warstwy, którą dopiero ta faza ma
|
||||
zbudować. Zaczynanie od (B) to budowanie pipeline'u nad nieistniejącym
|
||||
sygnałem.
|
||||
2. **Bootstrap wymaga przeglądu, nie automatyzacji.** 17 stron z §3 to
|
||||
pierwsza próba entity resolution na korpusie, który nigdy wcześniej nie był
|
||||
tak czytany — pierwsze przebiegi *będą* mylić się (aliasy tej samej osoby
|
||||
pod różnymi adresami, jak `paweld2@gmail.com` vs `pawel@cosmose.co`, patrz
|
||||
#9). Batch z operatorem czytającym diff przed commitem jest tu właściwym
|
||||
trybem; automatyczny zapis bez przeglądu ryzykuje właśnie to, co inwariant
|
||||
3 (lint) ma łapać *po fakcie* — lepiej łapać *przed* pierwszym zapisem.
|
||||
3. **Koszt.** Batch: koszt jednej sesji, znany z góry (faza3 §11 szacuje
|
||||
kompilację 3–5 stron proof jako „pomijalna" wobec ~1.5–4 USD pilota
|
||||
streszczeń). Pipeline per-query: koszt proporcjonalny do ruchu na
|
||||
`kb-query`, dziś zerowego (serwis bez UI logowania, brak ruchu
|
||||
produkcyjnego opisanego w żadnym audycie) — budowanie licznika kosztów pod
|
||||
ruch, którego jeszcze nie ma, jest przedwczesne.
|
||||
|
||||
**Wniosek: w tej fazie — wyłącznie (A)/(C)-batch.** Pipeline eskalacji (B) to
|
||||
konsekwencja *syntezy odpowiedzi*, która sama jest poza zakresem tego reconu
|
||||
(`kb-m5-faza-mailowa.md` §11) — wpisuję go do §8 (plan iteracji) jako **osobny,
|
||||
późniejszy etap**, nie część pierwszego kroku.
|
||||
|
||||
### Trigger i częstotliwość dla batcha
|
||||
|
||||
Rekomendacja: **ręczny**, przywiązany do sesji roboczych KB, nie do ticku
|
||||
ingestu. Uzasadnienie: `kb-ingest`/`kb-mail-sync` tykają bez nadzoru
|
||||
(systemd timer) właśnie dlatego, że są deterministyczne i tanie (lokalny
|
||||
embed). Kompilacja wiki zużywa API i wymaga jakościowego osądu przy każdym
|
||||
zapisie na tym etapie — sprzeczne z „bez nadzoru". Automatyczny trigger „po
|
||||
ticku ingestu" dodałby niekontrolowany koszt API do procesu, który dziś nie ma
|
||||
żadnego budżetu ani limitu (`packages/kb-retrieval`/`kb-query` nie mają
|
||||
pojęcia o kosztach API — nigdzie w repo nie ma licznika wydatków Anthropica).
|
||||
|
||||
---
|
||||
|
||||
## 5. Punkt 4 — Format linku dowodowego i odporność na re-chunking
|
||||
|
||||
### Co już zdecydowano
|
||||
|
||||
Faza3 §8.2 daje **dokładną składnię**, cytuję w całości bo to bezpośrednia
|
||||
odpowiedź na pytanie zlecenia:
|
||||
|
||||
```markdown
|
||||
---
|
||||
sources:
|
||||
- envelope_id: paperless:119
|
||||
chunks: [4211, 4213] # document_chunk.id
|
||||
- envelope_id: "CABtrY-...@mail.gmail.com"
|
||||
chunks: [] # koperta bez chunków (np. sam manifest/headers)
|
||||
---
|
||||
|
||||
Treść… składka 1 234 zł/rok [^paperless:119#4212].
|
||||
```
|
||||
|
||||
Dwa poziomy: `sources:` we frontmatterze (agregat, dla lintu — sprawdza czy
|
||||
*strona* ma dowody) i inline `[^envelope_id#chunk_id]` przy każdym fakcie
|
||||
liczbowym (dla spot-checku — sprawdza czy *zdanie* ma dowód). To jest już
|
||||
odpowiedź na „envelope_id vs chunk-id": **oba, na dwóch poziomach
|
||||
granularności**, nie albo-albo.
|
||||
|
||||
### Luka, którą faza3 zostawia: `document_chunk.id` (bigint PK) nie jest stabilny
|
||||
|
||||
To jest realny problem, którego szkic nie adresuje wprost. `document_chunk.id`
|
||||
to `bigint GENERATED … nextval(...)` — PK generowany przy insercie. Re-chunking
|
||||
(zmiana `chunk_size`/`chunk_overlap`, zmiana modelu embeddingu, poprawka
|
||||
chunkera) w obecnym pipeline'u (`jobs/mail-body-ingest`, `kb/phases/kb-m5-faza3.md`
|
||||
§1.6, Decyzja 1) **usuwa i wstawia na nowo** wiersze `document_chunk` dla
|
||||
przetwarzanej koperty — nowe `id`. Strona wiki napisana dziś z przypisem
|
||||
`[^paperless:119#4212]` po re-chunkowaniu paperless wskazuje na `id`, który już
|
||||
nie istnieje.
|
||||
|
||||
Sprawdziłem: nie ma w repo żadnego mechanizmu "kotwiczenia" chunka niezależnego
|
||||
od PK (np. hash treści, offset w dokumencie źródłowym). `chunk_index` (kolumna
|
||||
w `document_chunk`) jest stabilniejszy semantycznie (n-ty fragment tej koperty)
|
||||
ale też **nie** jest gwarantowany stabilny — zmiana `chunk_size` przesuwa
|
||||
granice i renumeruje wszystkie chunki tej koperty.
|
||||
|
||||
### Ocena: to nie jest luka krytyczna, bo lint już ją łapie — ale warto dociągnąć degradację
|
||||
|
||||
Inwariant 3 (lint) faza3 §8.2 już projektuje mechanizm wykrywania: *„spot-check
|
||||
N losowych przypisów `[^...]` vs treść chunka w bazie"*. Martwy `chunk_id` po
|
||||
re-chunkingu to dokładnie to, co ten spot-check złapie — `SELECT text FROM
|
||||
document_chunk WHERE id = 4212` zwróci zero wierszy, lint zgłasza to jako
|
||||
znalezisko w `_meta/lint-reports/`. **Mechanizm wykrywający już istnieje w
|
||||
projekcie**, więc rekomendacja to nie „zbuduj nowy system kotwiczenia" tylko
|
||||
**doprecyzowanie zachowania przy trafieniu martwego linku**:
|
||||
|
||||
**Rekomendacja — dwupoziomowy fallback, nie twardy błąd:**
|
||||
|
||||
1. Link **prymarny** to `[^envelope_id#chunk_id]` — precyzyjny, ale kruchy.
|
||||
2. Gdy `chunk_id` nie istnieje (po re-chunkingu), **fallback do
|
||||
`envelope_id`** — dowód wskazuje na kopertę jako całość ("ten fakt pochodzi
|
||||
z tej wiadomości", zamiast "z tego dokładnie fragmentu"). Zdegradowane, ale
|
||||
wciąż audytowalne, bo `envelope_id` **jest** stabilny (`envelope.id` to
|
||||
Message-ID albo `sha256-…`, nigdy nie zmienia się po insercie —
|
||||
`kb-mail-pillar.md` §3, kontrakt zamrożony).
|
||||
3. Lint raportuje **liczbę zdegradowanych przypisów** jako osobną metrykę w
|
||||
`_meta/lint-reports/` (nie tylko listę zerwanych linków) — to jest wczesny
|
||||
sygnał "re-chunking coś ruszył, strony trzeba przejrzeć", zanim ktokolwiek
|
||||
zauważy to ręcznie.
|
||||
4. **Re-chunking = trigger do przeglądu, nie do automatycznej naprawy.**
|
||||
Automatyczne przepisanie `chunk_id` na nowy najbliższy semantycznie chunk
|
||||
wymagałoby ponownego embeddingu i porównania — kosztowne i ryzykowne (może
|
||||
przypisać fakt do złego fragmentu po cichu). Degradacja do `envelope_id` +
|
||||
ręczny przegląd przy najbliższej kompilacji tej strony jest tańsza i
|
||||
bezpieczniejsza.
|
||||
|
||||
Konsekwencja praktyczna: re-chunking całego korpusu mailowego (227k kopert)
|
||||
jest zdarzeniem rzadkim i świadomym (widziane już raz — Decyzja 1 fazy3,
|
||||
`UNIQUE+model`), nie czymś co dzieje się przy okazji. Skala degradacji przy
|
||||
takim zdarzeniu jest więc *skokowa i rzadka*, nie ciągła — fallback +
|
||||
metryka w locie wystarczą, nie trzeba temu poświęcać osobnej infrastruktury.
|
||||
|
||||
---
|
||||
|
||||
## 6. Punkt 5 — Anty-propagacja: datowanie, sprzeczności, aktualizacja
|
||||
|
||||
### Co już zdecydowano
|
||||
|
||||
Frontmatter niesie `compiled_at`/`updated_at` (datowanie na poziomie strony).
|
||||
Inwariant 3: lint okresowy łapie *„sprzeczności między stronami (fakty o tej
|
||||
samej encji)"*. Inwariant 4: pętla zwrotna dopisuje nowe strony/aktualizacje z
|
||||
dobrych odpowiedzi zapytań.
|
||||
|
||||
### Luki, które faza3 nie precyzuje i które zlecenie wprost pyta
|
||||
|
||||
**(1) Sekcja „niepewne/sprzeczne" na poziomie strony.** Dziś nic w
|
||||
projektowanym frontmatterze/strukturze nie ma miejsca na "wiem, że dwa źródła
|
||||
mówią co innego, i to jest w rękopisie widoczne". Lint wykrywa sprzeczność
|
||||
*między stronami* — ale co z sprzecznością *wewnątrz* jednej kompilacji (np.
|
||||
paperless:119 podaje jedną kwotę składki, wcześniejszy mail podaje inną —
|
||||
podwyżka, błąd, czy różne polisy)?
|
||||
|
||||
**Rekomendacja:** sekcja `## Niepewne / sprzeczne` jako **konwencja treści**
|
||||
strony (nie pole frontmattera — to jest proza, nie metadane), umieszczana
|
||||
zawsze na końcu strony, gdy występuje. Format:
|
||||
|
||||
```markdown
|
||||
## Niepewne / sprzeczne
|
||||
|
||||
- Składka OC: [^paperless:24#N] podaje kwotę roczną bez liczby, [^<msg-id>#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.
|
||||
```
|
||||
|
||||
Lint (spot-check) traktuje tę sekcję jako **oczekiwaną**, nie jako defekt —
|
||||
strona bez tej sekcji nie jest "lepsza", strona z niewykrytą sprzecznością w
|
||||
treści głównej (fakt podany jako pewny, gdy dowody się rozjeżdżają) jest
|
||||
gorsza. To jest różnica między *ukrywaniem* niepewności (zły kompilat) a jej
|
||||
*nazwaniem* (dobry kompilat) — i to jest właśnie mechanizm, który ma
|
||||
zapobiegać propagacji błędu: LLM kompilujący wprost pisze "nie wiem", zamiast
|
||||
zgadywać i zamrażać zgadywankę jako fakt.
|
||||
|
||||
**(2) Polityka aktualizacji przy nowym, sprzecznym dowodzie.** Scenariusz ze
|
||||
zlecenia: nowy mail przeczy istniejącej stronie. Dwie opcje:
|
||||
|
||||
- **Nadpisać** stronę nowym stanem (traktować najnowszy dowód jako
|
||||
prawdziwy) — ryzyko: jeśli nowy mail jest błędny/nieaktualny/o innej
|
||||
sprawie, kasuje się poprawną wcześniejszą treść bez śladu.
|
||||
- **Dopisać do „Niepewne/sprzeczne"** i **nie nadpisywać** faktu w treści
|
||||
głównej, dopóki sprzeczność nie zostanie rozstrzygnięta (przez kolejną
|
||||
kompilację z jeszcze jednym dowodem, albo ręcznie przez operatora).
|
||||
|
||||
**Rekomendacja: druga opcja, z jednym wyjątkiem.** Domyślnie *dopisz, nie
|
||||
nadpisuj* — bo strona ma być audytowalnym destylatem, nie najświeższą
|
||||
migawką, a "nowszy mail" nie zawsze znaczy "poprawniejszy" (może być o innej
|
||||
polisie, literówka nadawcy, spam). 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, nie sprzeczny z nim) — to nie jest sprzeczność, to
|
||||
aktualizacja, i idzie do treści głównej z nową datą `updated_at`, a stary fakt
|
||||
przechodzi do sekcji „Historia" (jeśli strona jej potrzebuje) albo po prostu
|
||||
znika, zastąpiony — to jest zwykła kompilacja, nie przypadek antypropagacji.
|
||||
Rozróżnienie "to jest aktualizacja" vs "to jest sprzeczność" robi **sesja
|
||||
kompilująca (CC/API)**, nie automat — zgodnie z inwariantem 2 (kompilacja to
|
||||
zadanie dla modelu, nie dla reguły).
|
||||
|
||||
**(3) Datowanie twierdzeń w treści, nie tylko w frontmatterze.** Rekomendacja
|
||||
dodatkowa: każdy fakt z konkretną datą ważności (cena, status sprawy, "aktualnie
|
||||
w toku") niesie datę **przy fakcie**, nie tylko w `updated_at` strony — bo
|
||||
strona może zbierać fakty z różnych momentów (mail z 2019 o starej umowie +
|
||||
mail z 2026 o nowej), a jedna data na całą stronę zaciera to rozróżnienie.
|
||||
Przykład: *„Składka 1 234 zł/rok (stan na 07.2026) [^paperless:119#4212]."*
|
||||
To jest rozszerzenie konwencji przypisu z §5, nie nowy mechanizm.
|
||||
|
||||
---
|
||||
|
||||
## 7. Punkt 6 — Integracja z kb-query: retrieval, ryzyko sprzężenia
|
||||
|
||||
### Co już zdecydowano
|
||||
|
||||
Inwariant 5 (faza3 §8.1): *„Wiki wchodzi do retrievalu jako dodatkowe źródło…
|
||||
kaskada: wiki → summary → chunk."* §8.2 rozwija: strona wiki = koperta
|
||||
`source='wiki'`, `id='wiki:<ścieżka>'`, chunkowana i embedowana tym samym
|
||||
jobem, **bez nowego schematu bazy** — reużywa istniejący kontrakt koperty.
|
||||
|
||||
### Co to znaczy konkretnie w kodzie dzisiejszego `packages/kb-retrieval`
|
||||
|
||||
Sprawdziłem `retrieval.py`: dziś są trzy tory (`flat`/`cascade`/`hybrid`), z
|
||||
`cascade_retrieve` jako **dwupoziomowym** (`document_summary` → `document_chunk`)
|
||||
i `hybrid_retrieve` jako cascade + równoległy skan `summaryless_sources`
|
||||
(`gmail`, `fastmail`) scalany po `dist`. **Nie ma dziś trzeciego poziomu.**
|
||||
Realizacja inwariantu 5 wymaga:
|
||||
|
||||
1. Nowej tabeli/kolekcji `document_summary`-podobnej dla wiki, **albo**
|
||||
traktowania stron wiki jak paperless — envelope z summary (skoro strony
|
||||
są krótkie, 1–3 chunki, `document_summary` dla całej strony ma sens
|
||||
semantyczny inaczej niż dla 187k-wierszowego newslettera).
|
||||
2. Nowej funkcji `wiki_retrieve` w `kb_retrieval/retrieval.py`, wołanej
|
||||
**przed** `cascade_retrieve`, z wynikiem scalanym analogicznie do
|
||||
`hybrid_retrieve` (ten sam embedder, ten sam cosine space — merge to sort,
|
||||
nie renormalizacja, dokładnie jak dziś).
|
||||
3. Zmiany w `search.py`/`app/main.py` `kb-query`, żeby nowy tryb (`mode`)
|
||||
albo rozszerzenie `hybrid` obejmował wiki — i w `app/links.py`
|
||||
(`build_result`) żeby wynik ze źródła `wiki` miał sensowny `link`
|
||||
(`raw_ref` do pliku w `kb-wiki`, nie URL — bo `kb-wiki` nie jest hostowane
|
||||
publicznie, patrz §2).
|
||||
|
||||
To jest **realna zmiana kodu** w serwisie produkcyjnym (`kb-query`), nie tylko
|
||||
w nowym repo `kb-wiki` — warto to mieć jawnie w planie iteracji (§8), bo
|
||||
inwariant 5 bez tego pozostaje deklaracją, nie działaniem.
|
||||
|
||||
### Ryzyko sprzężenia (self-citation / citogenesis) — luka w szkicu faza3
|
||||
|
||||
Zlecenie pyta wprost o to ryzyko i faza3 **go nie adresuje**. Mechanizm
|
||||
ryzyka: kompilacja strony X czyta wyniki retrievalu (inwariant 2) → jeśli
|
||||
retrieval w tym momencie już przeszukuje `source='wiki'` (inwariant 5, w pełni
|
||||
wdrożony) → strona X może dostać jako "dowód" **inną stronę wiki**, która sama
|
||||
została skompilowana z niepewnych/błędnych przesłanek → błąd się utrwala i
|
||||
**wzmacnia** zamiast zanikać, bo kolejna kompilacja cytuje już nie surowy
|
||||
mail, tylko wcześniejszą (błędną) syntezę, z pozorem niezależnego
|
||||
potwierdzenia. To jest dokładnie mechanizm Wikipedia-citogenesis, przeniesiony
|
||||
na kompilator jednoosobowy.
|
||||
|
||||
**Rekomendacja — rozdzielić dwie ścieżki retrievalu, które dziś inwariant 5
|
||||
zlewa w jedną:**
|
||||
|
||||
1. **Retrieval na potrzeby `/search` (użytkownik, faza 5 synteza
|
||||
odpowiedzi)** — tu wiki **powinna** wchodzić do kaskady (inwariant 5 ma
|
||||
rację: skompilowana wiedza jest cenniejsza niż surowy chunk dla kogoś, kto
|
||||
pyta "co wiem o PZU").
|
||||
2. **Retrieval na potrzeby *kompilacji* nowej/aktualizowanej strony (sesja
|
||||
CC/API pisząca `kb-wiki`)** — tu retrieval **musi** wykluczać
|
||||
`source='wiki'` (parametr `exclude_sources=('wiki',)` w
|
||||
`cascade_retrieve`/`hybrid_retrieve`, jedna linia zmiany analogiczna do
|
||||
dzisiejszego `summaryless_sources`). Kompilacja zawsze czyta wyłącznie
|
||||
warstwę dowodową (mail, paperless — evidence layer z ustaleń wyjściowych
|
||||
operatora), nigdy inne strony wiki jako źródło faktów. Strony **mogą**
|
||||
linkować się nawzajem przez `[[...]]` (graf, nawigacja) — ale to nie jest
|
||||
to samo co "cytowanie jako dowód faktu"; link `[[pzu]]` w treści strony
|
||||
`polisa-oc-auto` to odsyłacz do powiązanej strony, nie przypis źródłowy —
|
||||
przypisy źródłowe (`[^...]`) zawsze wskazują `envelope_id`, nigdy
|
||||
`wiki:...`.
|
||||
|
||||
Ten podział jest tani do wymuszenia (jeden parametr) i eliminuje ryzyko przy
|
||||
źródle, zamiast polegać wyłącznie na lincie żeby je złapać po fakcie.
|
||||
Rekomendacja: dopisać to jako **inwariant 7** przy zatwierdzaniu planu, nie
|
||||
jako implementacyjny szczegół — to jest decyzja architektoniczna tej samej
|
||||
wagi co inwarianty 1–6 z faza3 §8.1.
|
||||
|
||||
---
|
||||
|
||||
## 8. Punkt 7 — Zależności i kolizje
|
||||
|
||||
### Multiagent recon / dyspozytor
|
||||
|
||||
Sprawdzone bezpośrednio w `kb/subsystems/recon-multiagent.md` i potwierdzone
|
||||
przez `kb/audits/mail-sync-2026-08-06.md` §5 (który zrobił dokładnie to samo
|
||||
ćwiczenie dla przyrostówki): **dyspozytor subsystemu B nie istnieje jeszcze w
|
||||
kodzie** — jest zdefiniowany jako *osobny projekt* w
|
||||
`kb/decisions/architektura-2026-07-28.md` (*„B — do-the-work: dyspozytor zadań
|
||||
(agent)… Osobny wysiłek, osobny projekt"*), planowany na PIHA. `kb-query`
|
||||
występuje w reconie multiagentowym wyłącznie jako wiersz inwentarza, poza
|
||||
zakresem control-plane/Telegram.
|
||||
|
||||
**Wniosek: zero zależności blokujących w żadną stronę**, z tym samym
|
||||
zastrzeżeniem, jakie mail-sync-recon już zanotował dla siebie: nowy automat
|
||||
(tu: ewentualny periodyczny lint albo — gdyby kiedyś powstał — pipeline
|
||||
eskalacji z §4) **dokłada się do „shadow set"** bytów poza GitOps-ową detekcją
|
||||
dryfu (`kb-ingest`, `stability-agent`, teraz `kb-mail-sync`, potencjalnie
|
||||
`kb-wiki`-lint). Nie blokuje nic dzisiaj; warto, żeby trafiło świadomie do
|
||||
otwartego pytania nr 5 tamtego reconu, a nie przez przeoczenie — dokładnie tak
|
||||
samo jak zanotował to mail-sync-recon dla siebie.
|
||||
|
||||
**Telegram/approval flow** (`CLAUDE.md` „Action approval flow") dotyczy
|
||||
wyłącznie akcji `container_restart`/`redeploy`/`disk_cleanup`/`alert_only` z
|
||||
control-plane. Kompilacja wiki nie generuje żadnej z tych akcji — nie ma i nie
|
||||
powinno być punktu styku. Jedyny sensowny alert, gdyby faza 5 dostała
|
||||
automatyzację (§4 tryb B, poza zakresem tej fazy), byłby analogiczny do
|
||||
`KbMailSyncStale`: "kompilator/lint nie chodzi", nie coś wymagające approvalu
|
||||
operatora.
|
||||
|
||||
### kb-site publish
|
||||
|
||||
Rozstrzygnięte w §2: `kb-wiki` leży poza `kb/**/*.md`, więc `gen_pages.py`/
|
||||
`publish.sh` **nie widzą go w ogóle** — zero kolizji, bo zero styku. Gdyby w
|
||||
przyszłości ktoś położył treść `kb-wiki` wewnątrz `kb/` (odwrotnie od
|
||||
rekomendacji §2), *wtedy* powstałaby realna kolizja: `gen_pages.py --check`
|
||||
skanuje wygenerowany output pod kątem wycieków (IP, tokeny, ścieżki hosta) —
|
||||
ale nie skanuje pod kątem **danych osobowych** (PESEL, adresy, numery umów),
|
||||
bo nie taki był jego cel. To jest dodatkowy, mocny argument za §2 (osobne
|
||||
repo): trzymanie wiki-encji poza `kb/` eliminuje całą tę klasę ryzyka
|
||||
strukturalnie, zamiast polegać na tym, żeby nikt nigdy nie oznaczył strony o
|
||||
PZU jako `visibility: public` przez pomyłkę.
|
||||
|
||||
### Follow-upy fazy mailowej — czy brudne chunki psują kompilację
|
||||
|
||||
Z `kb/incidents/2026-08-26-mail-sync-20-dni-ciszy.md` §6 (`Nie w zakresie tej
|
||||
naprawy`, bez zmian od 08-06): **charset/mojibake w co najmniej 12 kopertach**
|
||||
oraz **NUL w nagłówkach `jsonb`** pozostają otwarte. Oceniam wpływ na
|
||||
wiki-kompilat:
|
||||
|
||||
- **Skala jest znikoma** — 12 kopert na 227 576 (≈0,005%). Statystycznie
|
||||
prawdopodobieństwo, że pierwsza fala 17 stron z §3 natrafi akurat na jedną
|
||||
z tych 12, jest bliskie zeru (żadna z zidentyfikowanych encji §3 nie
|
||||
pochodzi z okresu/nadawcy powiązanego ze znanymi przypadkami mojibake wg
|
||||
audytu 08-06).
|
||||
- **Mechanizm szkody, gdyby trafiła:** kompilująca sesja CC dostaje chunk z
|
||||
zepsutym kodowaniem jako "dowód" — najgorszy scenariusz to nie błędny fakt
|
||||
(model raczej rozpozna nieczytelny tekst i pominie/zaznaczy niepewność, patrz
|
||||
§6 wyżej), tylko **marnotrawstwo** — chunk wygląda jak szum, model go
|
||||
ignoruje, dowód dla realnego faktu ginie z pola widzenia.
|
||||
- **NUL w `entities` jsonb jest poważniejszy strukturalnie** — jeśli sesja
|
||||
kompilująca odpytuje `entities` bezpośrednio (nie tylko `document_chunk.text`),
|
||||
NUL bajt w jsonb może wywrócić parser po stronie klienta (Pythonowy
|
||||
`json`/`asyncpg` różnie reaguje na `` w zależności od ścieżki). To
|
||||
**nie zostało zweryfikowane w tym reconie** (nie testowałem odczytu takiego
|
||||
wiersza) — flaguję jako `[do weryfikacji]`, nie jako potwierdzony problem.
|
||||
|
||||
**Rekomendacja: nie blokować pierwszego etapu na R1–R3 z §6 incydentu**
|
||||
(charset/NUL) — skala nie uzasadnia opóźnienia PoC. Warto natomiast, żeby
|
||||
lint (inwariant 3) przy pierwszym uruchomieniu zrobił **jednorazowy skan**
|
||||
`document_chunk`/`envelope.entities` pod kątem znaków zastępczych
|
||||
(`<60>`) i `` w źródłach, które faktycznie zasiliły PoC (17 stron
|
||||
§3) — tanie zabezpieczenie, żeby nie odkryć problemu dopiero przy spot-checku
|
||||
tygodnie później.
|
||||
|
||||
---
|
||||
|
||||
## 9. Punkt 8 — Plan iteracji
|
||||
|
||||
Wzorzec: faza mailowa (`kb-m5-faza-mailowa.md` §10 „Plan implementacji" +
|
||||
§12 kryterium ukończenia per krok) i mail-sync-recon (§6 „Podsumowanie i zakres
|
||||
pracy" — tabela kroków z rodzajem zmiany). Stosuję ten sam format: kroki z
|
||||
zależnościami, DoD per krok, pierwszy etap ograniczony do 1–2 sesji.
|
||||
|
||||
### Etap 0 — Zamknięcie decyzji (ten dokument + zatwierdzenie, 0 sesji kodu)
|
||||
|
||||
Operator przyklepuje §11 (Decyzje) poniżej. Bez tego nic dalej nie rusza —
|
||||
identyczny wzorzec jak Decyzje (a)-(g) w mail-sync-recon, które **zatwierdzono
|
||||
w całości** przed implementacją (`kb-m5-faza-mailowa.md` nagłówek statusu).
|
||||
|
||||
### Etap 1 — Szkielet `kb-wiki` + 3 strony proof (**cel: 1 sesja**)
|
||||
|
||||
> **Wykonany 2026-08-27 — z zastrzeżeniem: ten audyt nie wykrył, że proof-of-concept
|
||||
> (5 stron) już istniał od 2026-07-21 na Forgejo (`oskar/kb-wiki`, poza zestawem
|
||||
> dowodów tego reconu). Pełne rozliczenie i rekoncyliacja: `kb/phases/kb-m5-faza5-wiki.md`.**
|
||||
|
||||
Zakres, celowo mniejszy niż faza3 §8.2 (3–5 stron) i mniejszy niż lista z §3
|
||||
(17 encji) — pierwszy etap ma zweryfikować *mechanizm*, nie pokryć korpus:
|
||||
|
||||
| # | Element | DoD |
|
||||
|---|---|---|
|
||||
| 1 | Repo `kb-wiki` (git, poza `homelab-codex-ws`), struktura katalogów wg faza3 §8.2, `_meta/conventions.md` (format frontmattera + inline-przypisów z §5, w tym reguła fallback z §5, sekcja „Niepewne/sprzeczne" z §6, rozdział retrievalu z §7 inwariant 7) | Repo istnieje, `conventions.md` kompletny, czytelny bez kontekstu tej sesji |
|
||||
| 2 | Walidator `kb-wiki/check_okf.py` — wariant lekki, wzorowany na `~/narty-2027/saalbach-kb/check_okf.py` (frontmatter parsowalny + `type` niepuste), rozszerzony o sprawdzenie bloku `sources` (niepusty, każdy `envelope_id` istnieje w bazie — może wymagać `KB_DSN`) | `python3 check_okf.py` PASS na repo z krokiem 3 |
|
||||
| 3 | **3 strony proof**, kompilowane ręcznie sesją CC z wyników `hybrid_retrieve`/`cascade_retrieve` na encjach #1 (`fll-2025-26`), #5 (`mbank`), #9 (`pawel-cesar-sanjuan-szklarz`) z §3 — świadomie zróżnicowane typy (sprawa/podmiot/osoba-z-aliasami) i źródła (paperless/gmail-długi-ciąg/gmail-multi-adres) | Każda strona: frontmatter zgodny z konwencją, ≥1 przypis inline, `sources:` niepuste, przechodzi walidator |
|
||||
| 4 | Ręczny spot-check (inwariant 3, wersja manualna — pełny lint to Etap 2) — operator albo agent czyta 3 strony vs źródłowe chunki, potwierdza brak halucynacji | Zapisany w `_meta/lint-reports/2026-08-XX.md` — pierwszy raport, nawet jeśli ręczny |
|
||||
|
||||
**Dlaczego te trzy, nie 17:** `pawel-cesar-sanjuan-szklarz` (#9) testuje
|
||||
entity resolution na aliasach — jeśli to zawiedzie, cała reszta listy z §3
|
||||
(gdzie kilka pozycji ma podobny problem, np. `cosmose`↔#7/#8) wymaga
|
||||
przeprojektowania konwencji *zanim* zainwestuje się w kolejne 14 stron.
|
||||
Trzy strony, świadomie różne, są tańszym testem niż siedemnaście podobnych.
|
||||
|
||||
### Etap 2 — Lint automatyczny + rozszerzenie do pełnej listy §3 (**2. sesja**)
|
||||
|
||||
Zależy od Etapu 1 (mechanizm zweryfikowany). Zakres:
|
||||
|
||||
1. `kb-wiki/lint.py` — implementacja inwariantu 3 w kodzie (nie ręcznie):
|
||||
linki `[[...]]` do nieistniejących stron, strony-sieroty, spot-check N
|
||||
losowych przypisów (zapytanie do `document_chunk` po `id`, fallback do
|
||||
`envelope_id` z §5 gdy `id` martwy — z metryką degradacji), sprzeczności
|
||||
między stronami (heurystyka: te same encje w `sources:` różnych stron z
|
||||
rozbieżnymi liczbami przy tym samym typie faktu — pełna detekcja
|
||||
semantyczna to zadanie dla CC, nie dla skryptu; skrypt robi tylko
|
||||
pre-filtr kandydatów).
|
||||
2. Rozszerzenie o pozostałe encje z §3 (do 17), plus jednorazowy skan pod
|
||||
kątem `<60>`/`` (§8 „follow-upy fazy mailowej") na źródłach, które
|
||||
faktycznie zasiliły te strony.
|
||||
3. **DoD etapu**: `lint.py` uruchamiany ręcznie (nie timer — zgodnie z §4,
|
||||
automatyzacja poza zakresem), raport w `_meta/lint-reports/`, zero
|
||||
krytycznych znalezisk nierozwiązanych (martwe linki, sieroty) — degradacje
|
||||
chunk-id i sekcje „niepewne" to oczekiwany, nie błędny stan.
|
||||
|
||||
### Poza zakresem pierwszych dwóch etapów (świadomie odłożone)
|
||||
|
||||
| Temat | Gdzie wraca |
|
||||
|---|---|
|
||||
| Integracja `source='wiki'` w `packages/kb-retrieval` (§7, inwariant 5 + 7) | Etap 3 — wymaga działającego korpusu wiki (≥Etap 2) zanim ma sens dodawać go do retrievalu produkcyjnego |
|
||||
| Synteza odpowiedzi (`/search` → odpowiedź w naturalnym języku) | Osobna faza, `kb-m5-faza-mailowa.md` §11 już to tak kotwiczy |
|
||||
| Pipeline eskalacji per-query (tryb B z §4) | Po syntezie odpowiedzi — bez niej nie ma sygnału do eskalacji |
|
||||
| Automatyzacja lintu (timer) | Po Etapie 2, gdy wiadomo ile realnie kosztuje jeden przebieg |
|
||||
| Ewentualny hosting/publikacja `kb-wiki` | Nie zaplanowane — patrz §2, dziś brak potrzeby |
|
||||
| Druga tura encji (#18-20 z §3, `outbox.pl`/dawny pracodawca) | Po ustaleniu kontekstu firmy — osobne mini-śledztwo |
|
||||
|
||||
---
|
||||
|
||||
## 10. Punkt 9 — Decyzje operatora
|
||||
|
||||
> **Status: (a)-(h) ZATWIERDZONE przez operatora w całości 2026-08-27, bez
|
||||
> zmian** — wzorzec identyczny jak decyzje (a)-(g) w `mail-sync-2026-08-06.md`
|
||||
> (zatwierdzone 2026-08-06 w całości, patrz `kb-m5-faza-mailowa.md` nagłówek
|
||||
> statusu).
|
||||
|
||||
Wzorzec (a)-(g) z `kb/audits/mail-sync-2026-08-06.md` §4.
|
||||
|
||||
### (a) Wersja OKF dla `kb-wiki`: pin v0.1 (jak pilot) vs start od razu na v0.2
|
||||
|
||||
**Rekomendacja: pin v0.1, z migracją zaplanowaną, nie natychmiastową.**
|
||||
|
||||
- Pilot narty27 **potwierdził w praktyce**, że pinowanie v0.1 działa i że
|
||||
zmiana jest tania: `docs/sessions/2026-07-31-kb-f4-final-narty27.md` —
|
||||
*„OKF v0.1 działa w praktyce, a pinowanie wersji okazało się słuszne — spec
|
||||
ewoluuje (v0.2: `timestamp` → `generated: {by, at}`, provenance
|
||||
first-class). Przy fazie 5 rozważyć start od razu na v0.2 albo pin v0.1 z
|
||||
zaplanowaną migracją."* To jest bezpośrednia rekomendacja z pilota, cytowana
|
||||
w zleceniu tego reconu.
|
||||
- **Ale**: `kb-wiki` ma silniejszą potrzebę provenance niż narty27 (który jest
|
||||
planowaniem wyjazdu, nie audytowalnym kompilatem nad wrażliwym korpusem).
|
||||
Provenance first-class w v0.2 (`generated: {by, at}`) pokrywa się częściowo
|
||||
z tym, co faza3 §8.2 już projektuje osobno (`compiled_by`/`compiled_at` w
|
||||
`sources`-owym frontmatterze) — czyli **potrzeba, którą v0.2 adresuje,
|
||||
została już zaadresowana lokalną konwencją**, niezależnie od wersji OKF.
|
||||
To osłabia argument "musimy mieć v0.2 od razu", bo pole `compiled_by`
|
||||
robi tę samą robotę.
|
||||
- Decydujący argument za v0.1: **`homelab-codex` samo jest dziś na v0.1**
|
||||
(`scripts/kb/check_okf.py`, `PINNED_OKF = "0.1"`). Gdyby `kb-wiki` (osobne
|
||||
repo, ale koncepcyjnie ta sama rodzina dokumentów co `kb/`) startował na
|
||||
v0.2, powstałyby **dwie różne wersje specyfikacji w tym samym ekosystemie
|
||||
narzędzi** — dwa parsery, dwie reguły walidacji, mylące przy przenoszeniu
|
||||
wzorców między repo (dokładnie to, co uzasadnia rekomendację pilota "pin +
|
||||
zaplanowana migracja" zamiast "zawsze najnowsza wersja"). Spójność z resztą
|
||||
ekosystemu waży więcej niż wyprzedzenie o jedną wersję specyfikacji, którą
|
||||
i tak trzeba będzie kiedyś zmigrować w `kb/` też.
|
||||
- **Migracja zaplanowana**: gdy `homelab-codex`/`kb/` migruje na v0.2 (osobna
|
||||
decyzja, poza zakresem tego reconu), `kb-wiki` migruje w tym samym oknie —
|
||||
jedna zamiana pola (`timestamp`→`generated: {by,at}`), zgodnie z oceną
|
||||
pilota że to tania zmiana.
|
||||
|
||||
### (b) Repo `kb-wiki` — potwierdzenie D7 z faza3
|
||||
|
||||
**Rekomendacja: potwierdzić bez zmian** (§2). Jedyne doprecyzowanie: kompilacja
|
||||
nie idzie przez `agent.sh`-owy worktree — osobny tryb pracy z dwoma klonami
|
||||
obok siebie, do zapisania w `kb-wiki/_meta/conventions.md`.
|
||||
|
||||
### (c) Tryb kompilatora — potwierdzenie batch/hybryda, pipeline eskalacji poza zakres
|
||||
|
||||
**Rekomendacja:** (§4) batch (CC/API, ręczny trigger) dla bootstrapu i
|
||||
utrzymania w tej fazie; pipeline eskalacji per-query (tryb B) świadomie
|
||||
odłożony do momentu, gdy istnieje synteza odpowiedzi w `kb-query` — bez niej
|
||||
nie ma sygnału, który miałby eskalować.
|
||||
|
||||
### (d) Fallback chunk-id → envelope_id przy re-chunkingu
|
||||
|
||||
**Rekomendacja:** (§5) dwupoziomowy link z degradacją do `envelope_id`, lint
|
||||
raportuje liczbę zdegradowanych przypisów jako osobną metrykę, re-chunking
|
||||
traktowany jako trigger do ręcznego przeglądu, nie do automatycznej naprawy.
|
||||
|
||||
### (e) Sekcja „Niepewne/sprzeczne" i polityka aktualizacji — dopisać do konwencji
|
||||
|
||||
**Rekomendacja:** (§6) sekcja jako konwencja treści (nie pole frontmattera),
|
||||
domyślna polityka „dopisz, nie nadpisuj" przy sprzecznym nowym dowodzie,
|
||||
wyjątek dla jawnych aktualizacji tego samego faktu, rozróżnienie robi sesja
|
||||
kompilująca.
|
||||
|
||||
### (f) Inwariant 7 — rozdział retrievalu kompilacji od retrievalu zapytań
|
||||
|
||||
**Rekomendacja:** (§7) dopisać do inwariantów faza3 §8.1 jako inwariant 7:
|
||||
kompilacja strony wiki **nigdy** nie czyta `source='wiki'` jako dowód
|
||||
(`exclude_sources=('wiki',)`), tylko `/search` (warstwa użytkownika, po
|
||||
zbudowaniu syntezy odpowiedzi) widzi wiki w kaskadzie. Mitygacja
|
||||
self-citation/citogenesis przy źródle, nie tylko przez lint po fakcie.
|
||||
|
||||
### (g) Zakres i kolejność Etapu 1 — 3 strony proof, nie 17
|
||||
|
||||
**Rekomendacja:** (§9) Etap 1 = mechanizm (3 strony celowo zróżnicowane:
|
||||
sprawa/podmiot/osoba-z-aliasami), Etap 2 = skala (do 17) + lint w kodzie.
|
||||
Rozszerzenie listy encji (#18-20, `outbox.pl`) odłożone do osobnego
|
||||
mini-śledztwa kontekstu firmy.
|
||||
|
||||
### (h) Follow-upy fazy mailowej (charset/NUL) — nie blokują, jednorazowy skan przy Etapie 2
|
||||
|
||||
**Rekomendacja:** (§8) nie opóźniać PoC na R1–R3 z incydentu 20-dni-ciszy;
|
||||
dopisać jednorazowy skan `<60>`/`` do zakresu Etapu 2 (lint), nie jako
|
||||
osobny, wcześniejszy krok.
|
||||
|
||||
---
|
||||
|
||||
## 11. Podsumowanie
|
||||
|
||||
Korpus mailowy dogonił dziś — blokada z `kb-m5-faza3.md` §8.1 jest zdjęta
|
||||
(§1). Architektura wiki-kompilatu jest w dużej mierze **już zaprojektowana i
|
||||
zatwierdzona** (`kb-m5-faza3.md` §8, decyzja 2026-07-15/17) — ten recon
|
||||
weryfikuje ją na aktualnym stanie repo, dociąga trzy realne luki, których
|
||||
tamten szkic nie adresował (**chunk-id vs re-chunking** §5, **self-citation
|
||||
przy retrievalu kompilacyjnym** §7 — nowy inwariant 7, **sekcja
|
||||
niepewne/sprzeczne** §6), i daje 17-pozycyjną listę encji zalążkowych
|
||||
wyprowadzoną z realnych SELECT-ów na żywym korpusie zamiast z trzech
|
||||
przykładów w szkicu (§3). Rekomendowany pierwszy etap to **3 strony proof w
|
||||
1 sesji** (świadomie mniej niż faza3 §8.2 sugerowała, bo pierwszy test ma
|
||||
zweryfikować mechanizm entity-resolution na trudnym przypadku — aliasach —
|
||||
zanim zainwestuje się w skalę), z jawnym odłożeniem pipeline'u eskalacji i
|
||||
integracji retrievalu produkcyjnego do kolejnych etapów.
|
||||
|
||||
Decyzje: (a)-(h) w §10 — **ZATWIERDZONE przez operatora w całości 2026-08-27,
|
||||
bez zmian.**
|
||||
|
|
@ -3,7 +3,7 @@ okf: "0.1"
|
|||
type: phase
|
||||
visibility: private
|
||||
status: active
|
||||
updated: 2026-08-27
|
||||
updated: 2026-07-17
|
||||
links: []
|
||||
---
|
||||
|
||||
|
|
@ -628,17 +628,6 @@ Adapter i embed są już idempotentne — nowość to wyłącznie orkiestracja i
|
|||
> półprodukt kompilacji) i PO filtrze śmieciowych chunków. Pełna wiki po fazie mailowej
|
||||
> (przyrostówka) — wcześniej kompilat byłby fotografią przeszłości.
|
||||
|
||||
**Inwariant 7 (dodany 2026-08-27 — rozszerzenie, nie zmiana inwariantów 1–6
|
||||
powyżej, które pozostają NIE podlega zmianie):** decyzja (f),
|
||||
`kb/audits/wiki-kompilat-recon-2026-08-26.md` §10, zatwierdzona przez operatora
|
||||
w całości 2026-08-27. Kompilacja strony wiki **nigdy** nie czyta `source='wiki'`
|
||||
jako dowodu (`exclude_sources=('wiki',)` w `cascade_retrieve`/`hybrid_retrieve`) —
|
||||
retrieval na potrzeby kompilacji zawsze wyklucza wiki, czyta wyłącznie warstwę
|
||||
dowodową (mail, paperless). Tylko `/search` (warstwa użytkownika, po zbudowaniu
|
||||
syntezy odpowiedzi — inwariant 5, faza 5) widzi wiki w kaskadzie. Mitygacja
|
||||
self-citation/citogenesis przy źródle retrievalu, nie tylko przez lint (inwariant
|
||||
3) po fakcie — patrz audyt §7 dla pełnego rozumowania.
|
||||
|
||||
### 8.2 Rozwinięcie wykonawcze (szczegóły, decyzje architektoniczne bez zmian)
|
||||
|
||||
**Repozytorium** (rozstrzygnięcie punktu 6 szkicu): osobne repo `kb-wiki` — decyzja 7,
|
||||
|
|
|
|||
|
|
@ -1,322 +0,0 @@
|
|||
---
|
||||
okf: "0.1"
|
||||
type: phase
|
||||
visibility: private
|
||||
status: active
|
||||
updated: 2026-08-27
|
||||
links:
|
||||
- ../audits/wiki-kompilat-recon-2026-08-26.md
|
||||
- kb-m5-faza3.md
|
||||
- kb-m5-faza-mailowa.md
|
||||
---
|
||||
|
||||
# Moduł 5, faza 5 — wiki-kompilat (Etap 1: bootstrap + proof, i **odkrycie rozjazdu**)
|
||||
|
||||
> **Status: Etap 1 wykonany 2026-08-27 — ale w cieniu ważniejszego znaleziska: proof-of-concept
|
||||
> wiki-kompilatu (repo `kb-wiki`, 5 stron) już istniał od **2026-07-21**, na Forgejo
|
||||
> (`https://forgejo.kapala.org/oskar/kb-wiki`), i `kb/audits/wiki-kompilat-recon-2026-08-26.md`
|
||||
> tego nie wykrył. Ta sesja (2026-08-27) zbudowała **niezależny, równoległy** lokalny bootstrap
|
||||
> (`~/kb-wiki-etap1-sesja-2026-08-27/`, 3 strony) nie wiedząc o repo z lipca — dowiedziała się
|
||||
> dopiero przy Części C tego zadania, kiedy próba udokumentowania "remote nie istnieje" (cytat z
|
||||
> polecenia sesji, zgodny z audytem) skłoniła do sprawdzenia Forgejo wprost. **Nic nie zostało
|
||||
> wypchnięte do prawdziwego zdalnego repo** — ta sesja tylko czytała je (`git clone`, pull-only).
|
||||
>
|
||||
> **Rekoncyliacja domknięta 2026-08-27 (operator zdecydował: opcja 1 z §4 —
|
||||
> scalić).** `kb-wiki` ma teraz **7 stron**: 5 lipcowych + `fll-2025-26`
|
||||
> scalone (dwie niezależne kompilacje tej samej encji) + `mbank`/
|
||||
> `pawel-cesar-sanjuan-szklarz` przeniesione bez kolizji. Cztery commity na
|
||||
> `master` **lokalnie, nie pushnięte** — czekają na review operatora przed
|
||||
> pushem do Forgejo. Pełne rozliczenie: §6.
|
||||
|
||||
---
|
||||
|
||||
## 0. Jak doszło do odkrycia (żeby przyszła sesja nie powtórzyła tej samej luki)
|
||||
|
||||
`kb/audits/wiki-kompilat-recon-2026-08-26.md` (2026-08-26, decyzje a-h zatwierdzone
|
||||
2026-08-27) stwierdza wprost w nagłówku: *„Nic nie zostało zaimplementowane,
|
||||
zdeployowane ani skommitowane poza tym dokumentem."* Dowody audytu: worktree
|
||||
`homelab-codex-ws` cięty z mastera, pilot `~/narty-2027/saalbach-kb` (lokalny
|
||||
odczyt), żywa baza `kb` na PIHA (`ssh piha 'docker exec kb-postgres psql...'`),
|
||||
`systemctl status` na PIHA. **Forgejo nie było w tym zestawie dowodów** — audyt nie
|
||||
odpytał API/repo Forgejo, mimo że `CLAUDE.md` i `inventory/topology.yaml` jasno
|
||||
wskazują `git_provider: forgejo` jako miejsce, gdzie `kb-wiki` miało w ogóle
|
||||
powstać (decyzja D7 faza3 §8.2: *„osobne repo kb-wiki"*, bez wskazania konkretnego
|
||||
hosta w chwili pisania szkicu — Forgejo to naturalna, ale niejawna implikacja).
|
||||
|
||||
Zlecenie tej sesji (2026-08-27, Etap 1) powtórzyło za audytem: *„REMOTE NIE
|
||||
ISTNIEJE — nie konfiguruj, nie pushuj; operator założy repo na Forgejo później."*
|
||||
To zdanie okazało się **faktycznie nieprawdziwe** — sprawdzone dopiero przy pisaniu
|
||||
tego dokumentu (Część C zlecenia), zapytaniem GET do `http://100.108.208.3:3000/
|
||||
api/v1/repos/search?q=kb-wiki` (read-only, bez uwierzytelnienia, `private: false`
|
||||
więc odpowiedź jawna) i następnie `git clone` (pull-only, potwierdzone uprawnieniami
|
||||
API: `"push": false, "pull": true`) do katalogu tymczasowego poza tym repo.
|
||||
|
||||
**Wniosek na przyszłość:** *„repo nie istnieje"* w planie/audycie nie jest
|
||||
wystarczające bez sprawdzenia bezpośrednio w systemie, który je hostuje
|
||||
(`inventory/topology.yaml` → `git_provider: forgejo` → Forgejo API/`git ls-remote`),
|
||||
nie tylko w obrębie `homelab-codex-ws` i lokalnych klonów znanych z wcześniejszych
|
||||
sesji. Ten sam błąd metodologiczny mógłby się powtórzyć przy dowolnym innym „osobnym
|
||||
repo" planowanym w dokumentacji, ale nigdy nie zweryfikowanym wprost u hosta.
|
||||
|
||||
---
|
||||
|
||||
## 1. Co faktycznie istnieje w `oskar/kb-wiki` (Forgejo, od 2026-07-21)
|
||||
|
||||
Stan wg `git clone https://forgejo.kapala.org/oskar/kb-wiki.git` (read-only,
|
||||
2026-08-27), 3 commity na `master`:
|
||||
|
||||
```
|
||||
156925c struktura: katalogi, konwencje, README
|
||||
42c7731 compile: pzu, warta, ubezpieczenie-auto-ga431ja-2026, fll-2025-26, wspolnota-mieszkaniowa-targowa-2a ← kaskada retrievalu kb-postgres@PIHA
|
||||
c52f867 lint: pierwszy raport ręczny 2026-07-21
|
||||
```
|
||||
|
||||
Struktura: `README.md`, `INDEX.md` (wielka litera — inaczej niż plik zarezerwowany
|
||||
OKF `index.md`, patrz §3 niżej), `_meta/conventions.md`, `_meta/lint-reports/
|
||||
lint-report-2026-07-21.md`, 5 stron-encji:
|
||||
|
||||
| Strona | Typ | Skrót |
|
||||
|---|---|---|
|
||||
| `podmioty/pzu.md` | podmiot | PZU — OWU Auto/OC, karty produktu, oferta T1531938417 |
|
||||
| `podmioty/warta.md` | podmiot | WARTA — OWU AC Standard/Komfort/Moje Auto |
|
||||
| `sprawy/ubezpieczenie-auto-ga431ja-2026.md` | sprawa | Porównanie ofert PZU/WARTA/InterRisk, Mazda 6 (GA431JA), 06.2026 |
|
||||
| `sprawy/fll-2025-26.md` | sprawa | FLL Challenge UNEARTHED, drużyna #1100, Warszawa II |
|
||||
| `sprawy/wspolnota-mieszkaniowa-targowa-2a.md` | sprawa | Wspólnota Mieszkaniowa Targowa 2A (Pruszków) — zebranie roczne 2026 |
|
||||
|
||||
`osoby/`, `umowy/`, `tematy/` istnieją jako katalogi puste (`.gitkeep`) — **zero
|
||||
stron typu `osoba`** w lipcowym proof-of-concept. To jest jedyna luka pokrycia
|
||||
typów, którą Etap 1 tej sesji (§2) faktycznie domyka, nie duplikuje.
|
||||
|
||||
Jakość: wysoka, metodologicznie zgodna z tym, co audyt 08-26 dopiero rekomendował
|
||||
(sekcja „Niepewne/sprzeczne" jako wzorzec — tam nazwana wprost inaczej, ale ta sama
|
||||
funkcja; degradacja przy uszkodzonym OCR zamiast ślepego zaufania streszczeniu;
|
||||
84/86 wpisów `sources[].chunks` i 73/73 przypisów inline zweryfikowanych wprost w
|
||||
bazie, udokumentowane w `_meta/lint-reports/lint-report-2026-07-21.md`). Pełna
|
||||
treść: `_meta/conventions.md` tamtego repo (różni się od konwencji tej sesji w
|
||||
kilku miejscach nieistotnych merytorycznie — casing `INDEX.md`/`index.md`, typ
|
||||
`meta` vs `temat` dla `conventions.md` — patrz §3).
|
||||
|
||||
**`kb-m5-faza4.md` (linia 17, `docs/sessions/2026-07-21.md`) już to dokumentowały
|
||||
poprawnie** — ten fakt był w repo `homelab-codex-ws` cały czas, czytelny `git log`/
|
||||
`grep -r kb-wiki`. Audyt 08-26 po prostu tego nie sprawdził (§0 wyżej).
|
||||
|
||||
---
|
||||
|
||||
## 2. Co ta sesja (2026-08-27) faktycznie zrobiła — Etap 1 wg zlecenia, **lokalnie, bez wiedzy o §1**
|
||||
|
||||
Zbudowany od zera, niezależnie: `~/kb-wiki-etap1-sesja-2026-08-27/` (przemianowany
|
||||
z `~/kb-wiki/` po odkryciu §1 — żeby nie kolidować ścieżką z przyszłym `git clone`
|
||||
prawdziwego repo). Git lokalny, **6 commitów, nigdy nie pushowany do żadnego
|
||||
remote** (żaden remote nie był skonfigurowany — zgodnie z literą pierwotnego
|
||||
zlecenia, które okazało się oparte na błędnym założeniu z §0).
|
||||
|
||||
3 strony proof, celowo zróżnicowane typy (jak żądał audyt §9 Etap 1):
|
||||
|
||||
| Strona | Typ | Pokrycie względem §1 |
|
||||
|---|---|---|
|
||||
| `sprawy/fll-2025-26.md` | sprawa | **Duplikat tej samej encji** co lipcowe repo — skompilowany niezależnie, z częściowo innym zestawem chunków (uzupełniające, nie identyczne `sources`). Wysoka zgodność wniosków — patrz §4. |
|
||||
| `podmioty/mbank.md` | podmiot | **Nowe pokrycie** — nie istnieje w lipcowym repo (tam tylko PZU/WARTA, ubezpieczyciele) |
|
||||
| `osoby/pawel-cesar-sanjuan-szklarz.md` | osoba | **Domyka lukę** — lipcowe repo ma katalog `osoby/` pusty; to pierwsza strona typu `osoba` w całym projekcie, jedyny dotąd test entity-resolution na aliasach |
|
||||
|
||||
Pełna treść stron, `_meta/conventions.md` tej sesji (napisane niezależnie od
|
||||
lipcowego — patrz różnice §3), `check_okf.py` (walidator, **którego lipcowe repo
|
||||
nie ma jako skomitowanego pliku** — tamta sesja weryfikowała `sources`/przypisy
|
||||
ad hoc, bez zostawienia narzędzia), i `_meta/lint-reports/2026-08-27.md` — wszystko
|
||||
w `~/kb-wiki-etap1-sesja-2026-08-27/`, 6 commitów (`git log --oneline`):
|
||||
struktura+konwencje, walidator, 3× `compile:`, 1× `lint:`.
|
||||
|
||||
DoD audytu §9 Etap 1 (tabela, 4 punkty) — spełnione **lokalnie**, w tym repo
|
||||
równoległym: repo istnieje z konwencjami, walidator działa (zielono, 40 par
|
||||
`sources` + 47 inline przypisów zweryfikowanych wprost w `KB_DSN`), 3 strony
|
||||
proof spełniają inwarianty 1-2, raport lintu ręcznego zapisany.
|
||||
|
||||
**Weryfikacja lint:**
|
||||
```
|
||||
$ python3 check_okf.py # w ~/kb-wiki-etap1-sesja-2026-08-27/
|
||||
ZGODNE z OKF v0.1 (kb-wiki): [...] wszystkie 40 przypisów zweryfikowane w bazie.
|
||||
```
|
||||
|
||||
**`scripts/kb/check_okf.py` z `homelab-codex-ws` uruchomiony na tym samym repo —
|
||||
zgodnie z rozjazdem przewidzianym w zleceniu:**
|
||||
```
|
||||
$ python3 scripts/kb/check_okf.py ~/kb-wiki-etap1-sesja-2026-08-27
|
||||
Zakres: kb, docs/sessions
|
||||
Sprawdzono plików .md: 0
|
||||
BRAK plików w zakresie — nie ma czego walidować.
|
||||
```
|
||||
`SCOPE = ("kb", "docs/sessions")` w tamtym skrypcie jest wpisany na sztywno
|
||||
względem `root` — `kb-wiki` (żadna z dwóch kopii, lipcowa ani ta) nie ma
|
||||
podkatalogu `kb/` ani `docs/sessions/`, więc walidator zawsze zwróci "brak
|
||||
plików" dla tego layoutu. Nie hackowany — to jest realny, ustrukturalny rozjazd
|
||||
(nie błąd w `kb-wiki`), odnotowany tu jako follow-up: albo `scripts/kb/
|
||||
check_okf.py` dostaje parametr `--scope`, albo `kb-wiki` (dowolna wersja) trzyma
|
||||
własny walidator na stałe (rekomendacja tej sesji — już częściowo zrobione, patrz
|
||||
`check_okf.py` w repo tej sesji).
|
||||
|
||||
---
|
||||
|
||||
## 3. Różnice konwencji: lipiec vs ta sesja (nieistotne merytorycznie, warto ujednolicić)
|
||||
|
||||
| Aspekt | Lipiec (`oskar/kb-wiki`, prawdziwe repo) | Ta sesja (lokalne) | Rekomendacja |
|
||||
|---|---|---|---|
|
||||
| Plik nawigacyjny root | `INDEX.md` (duża litera), osobny od OKF-owego `index.md` (nie istnieje w ogóle w lipcowym repo — brak pliku `index.md`) | `index.md` (mała litera, OKF §11 reserved-file, pełni tę samą rolę) | Do rozstrzygnięcia przez operatora — lipcowe repo **nie ma pliku `index.md`** w ogóle, więc formalnie nie przechodzi `check_okf.py` tej sesji (`brak bloku frontmattera` nie wystąpi, bo pliku nie ma, ale reguła "root index.md wymagany" by to złapała, gdyby uruchomić walidator tej sesji na lipcowym repo — nie testowane, bo nie nasze repo do modyfikacji) |
|
||||
| `type` dla `_meta/conventions.md` | `meta` (dodatkowa wartość w słowniku typów) | `temat` (nadużycie istniejącego typu, bo `TYPES` tej sesji nie miało `meta`) | Lipcowe podejście czystsze — warto przyjąć `meta` jako 6. typ przy rekoncyliacji |
|
||||
| Frontmatter `sources` obowiązkowe niepuste | Nie wymuszone narzędziem (ręczna dyscyplina) | Wymuszone w `check_okf.py` (poza `_meta/`) | Zachować regułę tej sesji przy rekoncyliacji — tańsze niż poleganie na dyscyplinie |
|
||||
| Walidator jako plik w repo | Brak (weryfikacja ad hoc, nieskomitowana) | `check_okf.py`, skomitowany, wielokrotnego użytku | Przenieść `check_okf.py` tej sesji do prawdziwego repo przy rekoncyliacji |
|
||||
| Remote skonfigurowany | Tak (Forgejo, `master`) | Nie (lokalny, celowo) | — |
|
||||
|
||||
Żadna z różnic nie jest błędem — obie konwencje są spójne z faza3 §8.2 i audytem
|
||||
08-26 w rzeczach, które się nakładają (format `[^envelope_id#chunk_id]`, fallback,
|
||||
sekcja niepewności, CC/API-only, izolacja retrievalu kompilacji od `source='wiki'`).
|
||||
|
||||
---
|
||||
|
||||
## 4. Rekoncyliacja — do operatora, nie rozstrzygane przez tę sesję
|
||||
|
||||
To jest decyzja o realnych, już opublikowanych danych osobowych (finanse,
|
||||
ubezpieczenia, dziecko na turnieju) w prawdziwym repo — powyżej progu, przy którym
|
||||
ta sesja podejmuje decyzje sama. Opcje, bez rekomendacji wiążącej:
|
||||
|
||||
1. **Scalić nowe strony tej sesji do prawdziwego repo.** `podmioty/mbank.md` i
|
||||
`osoby/pawel-cesar-sanjuan-szklarz.md` nie kolidują z niczym w lipcowym repo —
|
||||
czysty dodatek. `sprawy/fll-2025-26.md` **koliduje** (dwie różne kompilacje tej
|
||||
samej encji) — wymaga porównania treść-po-treści przez operatora albo kolejną
|
||||
sesję CC, nie automatycznego scalenia.
|
||||
2. **Porównanie dwóch niezależnych kompilacji `fll-2025-26` jako test jakości
|
||||
kompilatora.** Obie wersje (lipcowa i ta) zgadzają się merytorycznie w
|
||||
kluczowych punktach: wynik 195 pkt jako jedyny czytelny wprost z chunka
|
||||
(`paperless:119#277`/`#278` — obie sesje trafiły w ten sam chunk niezależnie),
|
||||
pozostałe dwa wyniki (165/230) tylko ze streszczenia, nominacja do Nagrody
|
||||
Sędziów niepotwierdzona wprost w chunku, imiona z formularzy zgód celowo
|
||||
pominięte, nazwisko trenera nieczytelne OCR. Rozbieżność: ta sesja znalazła i
|
||||
zacytowała sprzeczność liczebności drużyny (10 vs 8 osób, z korespondencji
|
||||
gmail — lipcowa wersja jej nie ma, bo nie sięgnęła po te same koperty gmail).
|
||||
Lipcowa wersja znalazła niejednoznaczność sezonu SUBMERGED vs UNEARTHED
|
||||
(`paperless:6`) i konkretne imiona dzieci z nazw plików (metadane, nie treść
|
||||
dokumentu) — ta sesja pominęła `paperless:6` całkowicie i nie sięgnęła po
|
||||
`entities[type=filename]`. **Dwie niezależne kompilacje tej samej encji nie są
|
||||
sprzeczne, są komplementarne** — dobry sygnał, że metoda jest powtarzalna, zły
|
||||
sygnał, że jedna kompilacja pomija realne dowody, które druga znalazła.
|
||||
3. **Zostawić oba repo osobno, jawnie zarchiwizować to jako dwa niezależne
|
||||
przebiegi tej samej fazy.** Najbezpieczniejsze, ale traci szansę na scalenie
|
||||
uzupełniających się dowodów z punktu 2.
|
||||
|
||||
Krok operatora, niezależnie od wyboru z (1)-(3): **`~/kb-wiki-etap1-sesja-2026-08-27/`
|
||||
istnieje lokalnie, nigdy nie pushowany** — do usunięcia/scalenia/zachowania wg
|
||||
decyzji, nie automatycznie.
|
||||
|
||||
---
|
||||
|
||||
## 5. Poza zakresem tej notatki (Etap 2, jeśli operator potwierdzi kontynuację)
|
||||
|
||||
Zależnie od wyniku rekoncyliacji z §4:
|
||||
|
||||
- Skala do pełnej listy 17 encji z audytu §3 (już częściowo pokryta lipcowym repo
|
||||
inną listą — PZU/WARTA/wspólnota/FLL nie pokrywają się z 17-pozycyjną listą
|
||||
audytu poza `fll-2025-26`; wymaga ponownego review, które z 17 są już zrobione
|
||||
pod innymi nazwami).
|
||||
- Lint automatyczny w kodzie (`kb-wiki/lint.py`, inwariant 3 pełny) — żadna z
|
||||
dwóch kopii tego nie ma, obie robiły lint ręcznie.
|
||||
- Jednorazowy skan `<60>`/`\x00` na źródłach, które faktycznie zasiliły PoC (decyzja
|
||||
h) — nie wykonany w żadnej z dwóch kompilacji; oba proof-of-concept **napotkały**
|
||||
uszkodzony OCR organicznie (paperless:119/120 w obu wersjach fll-2025-26,
|
||||
mbank.md ta sesja) bez systematycznego skanu.
|
||||
- Integracja `source='wiki'` w `packages/kb-retrieval` (inwariant 5+7) — poza
|
||||
zakresem obu przebiegów.
|
||||
- Rozjazd `scripts/kb/check_okf.py` (SCOPE sztywny) — patrz §2, nie naprawiony
|
||||
celowo (instrukcja zlecenia: nie hackować).
|
||||
|
||||
---
|
||||
|
||||
## 6. Rekoncyliacja domknięta (2026-08-27, decyzja operatora: opcja 1 z §4)
|
||||
|
||||
Operator zdecydował scalić — bez rozstrzygania punktu 3 z §4 (dwa osobne
|
||||
repo) i bez samego jedynie archiwizowania punktu 2 (test jakości
|
||||
kompilatora, wykonany przy okazji scalenia `fll-2025-26`, patrz niżej).
|
||||
Wykonano w klonie roboczym `~/kb-wiki` (repo prawdziwe, `master`), **cztery
|
||||
commity, lokalnie, świadomie nie pushnięte** — review operatora przed
|
||||
pushem do Forgejo jest krokiem następnym, nie tej sesji.
|
||||
|
||||
### 6.1 `fll-2025-26` — scalenie dwóch niezależnych kompilacji
|
||||
|
||||
Wykonane **przed** tą sesją reconciliation (`kb-wiki` commit `c4127b9`,
|
||||
autor: operator lub wcześniejsza sesja — poza zakresem tego zadania, ta
|
||||
sesja zastała je już na `master` i pushnięte: *"Push zrobiony"*, cytat
|
||||
zlecenia). Wynik zgodny z analizą §4 punkt 2: zero sprzecznych twierdzeń,
|
||||
czysto komplementarne pokrycie (lipiec: 14 kopert paperless; sierpień
|
||||
dodał 6 kopert gmail + `paperless:183`) — 21 kopert finalnie (15 paperless +
|
||||
6 gmail), 38/38 par `sources` + 45/45 przypisów inline zweryfikowanych w
|
||||
bazie przy tamtym scaleniu. Ta sesja **nie modyfikowała** tej strony —
|
||||
tylko zweryfikowała ją ponownie w ramach pełnego lintu repo (§6.4).
|
||||
|
||||
### 6.2 `mbank` i `pawel-cesar-sanjuan-szklarz` — przeniesione bez kolizji
|
||||
|
||||
Zgodnie z §4 punkt 1 ("nie kolidują z niczym w lipcowym repo — czysty
|
||||
dodatek"): skopiowane z `~/kb-wiki-etap1-sesja-2026-08-27/` do `~/kb-wiki`,
|
||||
linki `[[...]]` przepisane ze składni sesyjnej (`[[../katalog/plik]]`) na
|
||||
rzeczywistą konwencję repo (`[[plik]]`, bez katalogu). Treść merytoryczna
|
||||
nietknięta. `INDEX.md` dopisany o oba wpisy. `sprawy/fll-2025-26.md`
|
||||
przestało być sierotą w grafie `[[...]]` (link przychodzący z obu nowych
|
||||
stron, sekcja „Powiązane" — decyzja sesyjna sprzed przeniesienia, nie tej
|
||||
rekoncyliacji: „sprawdzone wprost, zero wspólnego dowodu", link mimo braku
|
||||
dowodu).
|
||||
|
||||
### 6.3 Konwencje: `check_okf.py` przeniesiony, decyzje (d)-(f) scalone
|
||||
|
||||
`check_okf.py` (walidator sesyjny) przeniesiony do `~/kb-wiki` — lipcowy
|
||||
proof-of-concept nie zostawił żadnego skomitowanego narzędzia (§3 tabela,
|
||||
rekomendacja "Przenieść `check_okf.py` tej sesji do prawdziwego repo przy
|
||||
rekoncyliacji" — wykonana dosłownie). Zaadaptowany do rzeczywistego layoutu
|
||||
tego repo: `TYPES` rozszerzone o `meta` (repo miało 6. typ od lipca, sesyjny
|
||||
walidator znał tylko 5), `README.md`/`INDEX.md`/`_meta/lint-reports/*.md`
|
||||
wyjęte z wymogu frontmattera stron-konceptów (istniały bez niego od
|
||||
2026-07-21 — dokumentacja/raporty, nie skompilowane encje).
|
||||
|
||||
Decyzje (d)-(f) audytu 08-26, wypracowane w `_meta/conventions.md` sesji
|
||||
(§5/§7/§8 tamtego pliku), scalone do `_meta/conventions.md` prawdziwego repo
|
||||
— **bez duplikowania** tego, co repo już miało z lipca/wcześniejszej sesji
|
||||
(6 typów wliczając `meta`, sekcja „Brak danych w KB" — obie już scalone,
|
||||
commity `156925c`/`3bd2441`, przed tym zadaniem):
|
||||
|
||||
- **(d) fallback envelope-only** — `[^envelope_id]` bez `#chunk_id`, gdy
|
||||
dowód nie ma konkretnego chunka albo chunk zniknął po re-chunkingu.
|
||||
- **(e) sekcja „Niepewne / sprzeczne"** jako nazwana sekcja końca strony
|
||||
(już używana de facto na żywych stronach, teraz sformalizowana pisemnie) +
|
||||
polityka aktualizacji „dopisz, nie nadpisuj" przy nowym sprzecznym dowodzie.
|
||||
- **(f) inwariant 7** — izolacja retrievalu kompilacji od `source='wiki'`
|
||||
(mitygacja self-citation/citogenesis), CC/API-only jako wykonawca.
|
||||
|
||||
Różnica konwencji z §3 tabeli dotycząca casingu pliku nawigacyjnego
|
||||
(`INDEX.md` vs OKF-owy `index.md`) **pozostaje nierozstrzygnięta** — zgodnie
|
||||
z §3, do operatora, poza zakresem tej rekoncyliacji. `check_okf.py`
|
||||
pragmatycznie traktuje oba pliki root (`README.md`, `INDEX.md`) jako
|
||||
wyjęte z wymogu frontmattera, bez przesądzania, który plik "wygrywa".
|
||||
|
||||
### 6.4 Lint na całości — stan końcowy: 7 stron, zero błędów
|
||||
|
||||
`python3 check_okf.py` w `~/kb-wiki`: **ZGODNE**, 74/74 par `sources`
|
||||
(wszystkie 6 stron-konceptów poza `_meta/`) zweryfikowanych w `KB_DSN`
|
||||
(SELECT-only). Osobny, pełny przebieg (skrypt jednorazowy, nieskomitowany —
|
||||
`check_okf.py` nie parsuje treści Markdown) po **wszystkich** przypisach
|
||||
inline `[^envelope_id#chunk_id]` na **wszystkich** 7 stronach: **150/150**
|
||||
zweryfikowanych, 0 zdegradowanych do fallback. Zero wiszących linków
|
||||
`[[...]]`, zero błędów przypisania chunk→envelope. Pełny raport:
|
||||
`_meta/lint-reports/2026-08-27-rekoncyliacja.md` w `kb-wiki`.
|
||||
|
||||
| Metryka | Wynik |
|
||||
|---|---|
|
||||
| Stron w repo (po rekoncyliacji) | 7 (5 lipiec + `fll-2025-26` scalone + 2 przeniesione) |
|
||||
| `sources:` (agregat frontmatter) zweryfikowane w bazie | 74/74 |
|
||||
| Przypisy inline zweryfikowane w bazie | 150/150 |
|
||||
| Wiszące linki `[[...]]` | 0 |
|
||||
| Przypisy zdegradowane (fallback envelope-only) | 0 |
|
||||
| Commity rekoncyliacji na `kb-wiki:master` | 4, lokalne, **nie pushnięte** |
|
||||
|
||||
### 6.5 Co zostało poza zakresem tej rekoncyliacji
|
||||
|
||||
- `~/kb-wiki-etap1-sesja-2026-08-27/` — pozostawione nietknięte na żądanie
|
||||
operatora ("skasuję sam po weryfikacji"), nie usuwane przez tę sesję.
|
||||
- Push `kb-wiki:master` do Forgejo — czeka na review operatora.
|
||||
- Wszystko z §5 (skala do 17 encji, lint automatyczny w kodzie, skan
|
||||
`<60>`/`\x00` na źródłach, integracja `source='wiki'` w retrievalu, rozjazd
|
||||
`scripts/kb/check_okf.py`) — nadal otwarte, nie ruszone tą rekoncyliacją.
|
||||
|
|
@ -18,8 +18,6 @@ reguły tego repo:
|
|||
10. Wpisy `contradicts` wyglądające jak ścieżka .md też muszą istnieć;
|
||||
pozostałe wpisy to wolny tekst.
|
||||
11. `stub` — o ile obecne — musi być boolem.
|
||||
12. Brak bajtów kontrolnych poza \t \n \r w całym pliku (łapie wklejki NUL/inne
|
||||
binarne śmieci wklejone z zewnętrznych źródeł, np. wyników SELECT-ów).
|
||||
|
||||
Zakres domyślny: kb/ oraz docs/sessions/, z wyłączeniem README-wskaźników
|
||||
(POINTER_GLOBS) — te są nawigacją do kb-doca, nie dokumentami KB, i celowo nie
|
||||
|
|
@ -73,7 +71,6 @@ POINTER_GLOBS = (
|
|||
EXCLUDE_DIRS = ("build",)
|
||||
|
||||
DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
|
||||
CONTROL_CHAR_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
|
||||
|
||||
|
||||
def is_pointer(rel: str) -> bool:
|
||||
|
|
@ -235,17 +232,6 @@ def check_file(path: Path, root: Path) -> list[str]:
|
|||
f"{rel}: `contradicts` wskazuje na nieistniejący plik: {item}"
|
||||
)
|
||||
|
||||
seen_lines: set[int] = set()
|
||||
for m in CONTROL_CHAR_RE.finditer(text):
|
||||
line_no = text.count("\n", 0, m.start()) + 1
|
||||
if line_no in seen_lines:
|
||||
continue
|
||||
seen_lines.add(line_no)
|
||||
errors.append(
|
||||
f"{rel}: bajt kontrolny {ord(m.group()):#04x} w linii {line_no} "
|
||||
"(dozwolone tylko \\t \\n \\r)"
|
||||
)
|
||||
|
||||
return errors
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,62 +0,0 @@
|
|||
"""Tests for check_okf.py — the OKF v0.1 frontmatter validator.
|
||||
|
||||
Covers the control-character check added 2026-08-27: a file that otherwise has
|
||||
valid frontmatter must still fail if its body contains a NUL byte or other
|
||||
control byte outside \\t \\n \\r (the class of bug found in
|
||||
kb/audits/wiki-kompilat-recon-2026-08-26.md — raw bytes pasted in from a psql
|
||||
SELECT over the mail corpus).
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
||||
import check_okf # noqa: E402
|
||||
|
||||
VALID_FRONTMATTER = """---
|
||||
okf: "0.1"
|
||||
type: decision
|
||||
visibility: private
|
||||
status: active
|
||||
updated: 2026-08-27
|
||||
links: []
|
||||
---
|
||||
"""
|
||||
|
||||
|
||||
def _write(tmp_path: Path, body: str) -> Path:
|
||||
p = tmp_path / "doc.md"
|
||||
p.write_text(VALID_FRONTMATTER + body, encoding="utf-8")
|
||||
return p
|
||||
|
||||
|
||||
def test_clean_file_has_no_control_char_errors(tmp_path):
|
||||
path = _write(tmp_path, "# Title\n\nZwykła treść z \t tabulatorem i \r\n końcem linii.\n")
|
||||
errors = check_okf.check_file(path, tmp_path)
|
||||
assert errors == []
|
||||
|
||||
|
||||
def test_nul_byte_in_body_is_flagged(tmp_path):
|
||||
path = _write(tmp_path, "# Title\n\nZawiera bajt NUL: \x00 w tym miejscu.\n")
|
||||
errors = check_okf.check_file(path, tmp_path)
|
||||
assert any("bajt kontrolny" in e and "0x0" in e for e in errors)
|
||||
|
||||
|
||||
def test_control_char_error_reports_correct_line(tmp_path):
|
||||
body = "linia 1\nlinia 2\nzepsuta \x00 linia 3\nlinia 4\n"
|
||||
path = _write(tmp_path, body)
|
||||
errors = check_okf.check_file(path, tmp_path)
|
||||
control_errors = [e for e in errors if "bajt kontrolny" in e]
|
||||
assert len(control_errors) == 1
|
||||
# Frontmatter occupies 7 lines before the body starts.
|
||||
frontmatter_lines = VALID_FRONTMATTER.count("\n")
|
||||
expected_line = frontmatter_lines + 3
|
||||
assert f"w linii {expected_line}" in control_errors[0]
|
||||
|
||||
|
||||
def test_multiple_control_chars_same_line_reported_once(tmp_path):
|
||||
path = _write(tmp_path, "para \x00 z dwoma \x00 bajtami na tej samej linii\n")
|
||||
errors = check_okf.check_file(path, tmp_path)
|
||||
control_errors = [e for e in errors if "bajt kontrolny" in e]
|
||||
assert len(control_errors) == 1
|
||||
|
|
@ -1,17 +1,17 @@
|
|||
#!/usr/bin/env bash
|
||||
# health-monitor.sh - Homelab node health monitor
|
||||
# health-monitor.sh - Homelab node health monitor and safe disk cleanup
|
||||
#
|
||||
# Designed to run standalone on the host (cron or direct) or to be called by
|
||||
# the node-agent Python daemon.
|
||||
# the node-agent Python daemon. All cleanup decisions follow the conservative
|
||||
# policy agreed in the design review:
|
||||
#
|
||||
# Docker cleanup (image/container/build-cache prune) does NOT live here.
|
||||
# node_agent.py (R1) is the sole owner of that cleanup, with a filtered
|
||||
# container prune that respects restart policy and compose ownership —
|
||||
# see kb/incidents/2026-07-30-ollama-solaria-vanish.md. This script used to
|
||||
# carry its own unfiltered `docker container prune -f` (never wired into
|
||||
# cron/systemd on any node, verified 2026-08-06); it was removed rather than
|
||||
# backporting the R1 filter here too, to avoid two independent copies of
|
||||
# cleanup logic drifting apart.
|
||||
# lte_node (chelsty-infra, chelsty-ha) : NO cleanup at all
|
||||
# sd_card (piha, saturn) : dangling images + stopped containers,
|
||||
# rate-limited to once per 24 h
|
||||
# ai_node (solaria) : dangling images + stopped containers
|
||||
# + build cache (NEVER -a)
|
||||
# standard (vps) : dangling images + stopped containers
|
||||
# + build cache
|
||||
#
|
||||
# VPS additionally rotates control-plane filesystem artefacts:
|
||||
# actions/completed + failed > 7 days
|
||||
|
|
@ -43,6 +43,15 @@ DISK_CRIT_PCT=85
|
|||
MEM_WARN_PCT=85
|
||||
MEM_CRIT_PCT=95
|
||||
|
||||
# Rate-limit file for SD-card nodes (max one Docker cleanup per 24 h)
|
||||
CLEANUP_LOCK="${STATE_DIR}/last-docker-cleanup"
|
||||
CLEANUP_INTERVAL=86400 # seconds
|
||||
|
||||
# Node classifications
|
||||
LTE_NODES="chelsty-infra chelsty-ha"
|
||||
SD_CARD_NODES="piha saturn"
|
||||
AI_NODES="solaria"
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
|
@ -51,6 +60,20 @@ log() { echo "$(date -u +%H:%M:%S) [INFO] $*"; }
|
|||
warn() { echo "$(date -u +%H:%M:%S) [WARN] $*" >&2; }
|
||||
err() { echo "$(date -u +%H:%M:%S) [ERROR] $*" >&2; }
|
||||
|
||||
contains() {
|
||||
local word="$1"; shift
|
||||
for w in "$@"; do [[ "$w" == "$word" ]] && return 0; done
|
||||
return 1
|
||||
}
|
||||
|
||||
get_node_type() {
|
||||
# shellcheck disable=SC2086
|
||||
if contains "$NODE_NAME" $LTE_NODES; then echo "lte_node"; return; fi
|
||||
if contains "$NODE_NAME" $SD_CARD_NODES; then echo "sd_card"; return; fi
|
||||
if contains "$NODE_NAME" $AI_NODES; then echo "ai_node"; return; fi
|
||||
echo "standard"
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Event emission
|
||||
# ---------------------------------------------------------------------------
|
||||
|
|
@ -172,6 +195,69 @@ check_containers() {
|
|||
--format "{{.Names}}" 2>/dev/null || true)
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Safe Docker cleanup (per policy)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
_sd_card_rate_ok() {
|
||||
if [[ -f "${CLEANUP_LOCK}" ]]; then
|
||||
local last_ts elapsed
|
||||
last_ts=$(cat "${CLEANUP_LOCK}" 2>/dev/null || echo 0)
|
||||
elapsed=$(( TIMESTAMP - last_ts ))
|
||||
if [[ "${elapsed}" -lt "${CLEANUP_INTERVAL}" ]]; then
|
||||
log "Docker cleanup skipped: last run ${elapsed}s ago (limit ${CLEANUP_INTERVAL}s)"
|
||||
return 1
|
||||
fi
|
||||
fi
|
||||
return 0
|
||||
}
|
||||
|
||||
_mark_cleanup_done() {
|
||||
echo "${TIMESTAMP}" > "${CLEANUP_LOCK}"
|
||||
}
|
||||
|
||||
run_safe_cleanup() {
|
||||
command -v docker &>/dev/null || return
|
||||
local node_type
|
||||
node_type=$(get_node_type)
|
||||
|
||||
case "${node_type}" in
|
||||
lte_node)
|
||||
# NO cleanup on LTE nodes. Any docker operation risks triggering
|
||||
# a pull over a metered/intermittent connection.
|
||||
log "Skipping Docker cleanup: LTE node (${NODE_NAME})"
|
||||
;;
|
||||
|
||||
sd_card)
|
||||
# Dangling images + stopped containers only.
|
||||
# Rate-limited to once per 24 hours to protect SD card write endurance.
|
||||
_sd_card_rate_ok || return
|
||||
log "Running rate-limited Docker cleanup (SD card node)"
|
||||
docker image prune -f >/dev/null 2>&1 || true
|
||||
docker container prune -f >/dev/null 2>&1 || true
|
||||
_mark_cleanup_done
|
||||
;;
|
||||
|
||||
ai_node)
|
||||
# Dangling images + stopped containers + build cache.
|
||||
# NEVER docker image prune -a (would remove Ollama runtime images,
|
||||
# requiring a multi-hour re-pull of model weights).
|
||||
log "Running AI-node Docker cleanup (dangling images + containers + build cache)"
|
||||
docker image prune -f >/dev/null 2>&1 || true
|
||||
docker container prune -f >/dev/null 2>&1 || true
|
||||
docker builder prune -f >/dev/null 2>&1 || true
|
||||
;;
|
||||
|
||||
standard)
|
||||
# VPS and other standard nodes: full safe cleanup.
|
||||
log "Running standard Docker cleanup"
|
||||
docker image prune -f >/dev/null 2>&1 || true
|
||||
docker container prune -f >/dev/null 2>&1 || true
|
||||
docker builder prune -f >/dev/null 2>&1 || true
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# VPS-specific: control-plane filesystem rotation
|
||||
# ---------------------------------------------------------------------------
|
||||
|
|
@ -229,13 +315,15 @@ except Exception:
|
|||
|
||||
mkdir -p "${EVENTS_DIR}/${NODE_NAME}" "${STATE_DIR}"
|
||||
|
||||
log "Health check starting on ${NODE_NAME}"
|
||||
log "Health check starting on ${NODE_NAME} (type=$(get_node_type))"
|
||||
|
||||
disk_pct=$(check_disk || echo 0)
|
||||
mem_pct=$(check_memory || echo 0)
|
||||
cpu_pct=$(check_cpu || echo 0)
|
||||
check_containers
|
||||
|
||||
run_safe_cleanup
|
||||
|
||||
# VPS: also rotate control-plane filesystem artefacts
|
||||
if [[ "${NODE_NAME}" == "vps" ]]; then
|
||||
cleanup_control_plane_fs
|
||||
|
|
|
|||
|
|
@ -141,11 +141,6 @@ FAILED_EVENTS_DIR = STATE_DIR / "observer_failed_events"
|
|||
# "operator drops a file, the owning process consumes it" pattern the actions
|
||||
# pending/approved queue already uses.
|
||||
RESOLVE_REQUESTS_DIR = WORLD_DIR / "resolve-requests"
|
||||
# mkdir(mode=...) is masked by the process umask, so the SSH operator (group
|
||||
# aerbot) cannot drop a flag file into a dir created at the default 0o755 —
|
||||
# same defect/fix as executor.py's INBOX_DIR_MODE (2026-08-06): an explicit,
|
||||
# idempotent os.chmod after mkdir, applied on the same path the dir is used.
|
||||
RESOLVE_REQUESTS_DIR_MODE = 0o775
|
||||
|
||||
# Time-based fallback for incidents that can never receive the service_healthy
|
||||
# event _resolve_incident() waits for (service removed/renamed/decommissioned
|
||||
|
|
@ -282,13 +277,6 @@ class Observer:
|
|||
LOGS_DIR.mkdir(parents=True, exist_ok=True)
|
||||
FAILED_EVENTS_DIR.mkdir(parents=True, exist_ok=True)
|
||||
RESOLVE_REQUESTS_DIR.mkdir(parents=True, exist_ok=True)
|
||||
try:
|
||||
os.chmod(RESOLVE_REQUESTS_DIR, RESOLVE_REQUESTS_DIR_MODE)
|
||||
except OSError as e:
|
||||
logger.warning(
|
||||
f"Could not set mode {oct(RESOLVE_REQUESTS_DIR_MODE)} on "
|
||||
f"{RESOLVE_REQUESTS_DIR}: {e}"
|
||||
)
|
||||
|
||||
def _quarantine_event_file(self, file_path: str, node_dir: str, exc: Exception) -> None:
|
||||
"""Move an unreadable/unprocessable event out of the hot path."""
|
||||
|
|
|
|||
|
|
@ -452,15 +452,13 @@ class Supervisor:
|
|||
|
||||
# Choose action type first so we can build the ID.
|
||||
#
|
||||
# Both container_restart and redeploy IDs carry a suffix so two
|
||||
# DIFFERENT incidents for the same node+service never collide in
|
||||
# cancelled/completed/failed (2026-08-26: a generic
|
||||
# containers_not_running restart and a later ha-diag-agent
|
||||
# shadow-mode restart both used the bare
|
||||
# container_restart IDs carry a suffix so two DIFFERENT incidents for
|
||||
# the same node+service never collide in cancelled/completed/failed
|
||||
# (2026-08-26: a generic containers_not_running restart and a later
|
||||
# ha-diag-agent shadow-mode restart both used the bare
|
||||
# container-restart-piha-homeassistant id and overwrote each other's
|
||||
# history — worked around manually that session, see
|
||||
# docs/sessions/2026-08-26.md). redeploy carries the same latent risk
|
||||
# via the same code path and got the same fix on 2026-08-27.
|
||||
# docs/sessions/2026-08-26.md).
|
||||
#
|
||||
# The suffix is the triggering incident's started_at, NOT time.time()
|
||||
# at generation time: reconcile() calls _generate_recommendation on
|
||||
|
|
@ -484,22 +482,20 @@ class Supervisor:
|
|||
# bare id has no incident to distinguish "same" from "different"
|
||||
# occurrences by, but it is at least stable across calls, which is
|
||||
# what idempotency here actually requires.
|
||||
#
|
||||
# Safe to add the suffix to redeploy ids: verified no code anywhere
|
||||
# else reconstructs `redeploy-{node}-{service}` for an exact-match
|
||||
# lookup. _cancel_resolved_pending_actions matches on the node/service
|
||||
# *fields* inside each pending file, not on the id string; executor.py,
|
||||
# node_agent.py and deploy-runner.sh all treat action_id as an opaque
|
||||
# string read back from the action's own JSON/marker file, never
|
||||
# reconstructed from node+service.
|
||||
action_prefix = "container-restart" if trigger_type in CONTAINER_RESTART_TRIGGERS else "redeploy"
|
||||
if trigger_type in CONTAINER_RESTART_TRIGGERS:
|
||||
incident_id = self.actual_state["services"].get(drift["svc_key"], {}).get("incident_id")
|
||||
incident = self.actual_state["incidents"].get(incident_id, {}) if incident_id else {}
|
||||
started_ts = int(_parse_ts(incident.get("started_at")))
|
||||
if started_ts:
|
||||
action_id = f"{action_prefix}-{node}-{service}-{started_ts}"
|
||||
action_id = f"container-restart-{node}-{service}-{started_ts}"
|
||||
else:
|
||||
action_id = f"{action_prefix}-{node}-{service}"
|
||||
action_id = f"container-restart-{node}-{service}"
|
||||
else:
|
||||
# redeploy IDs stay bare (node-service) — out of scope for this
|
||||
# fix (see commit message: no observed collision here yet), and
|
||||
# _cancel_resolved_pending_actions/_ha_action_recently_completed
|
||||
# do not key off redeploy ids so nothing here depends on it.
|
||||
action_id = f"redeploy-{node}-{service}"
|
||||
|
||||
# Skip if an action for this ID is already live in any active state
|
||||
# (pending → approved → running). This prevents re-creation after
|
||||
|
|
|
|||
|
|
@ -2,7 +2,6 @@
|
|||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
|
@ -916,19 +915,3 @@ def test_resolve_request_flag_for_already_resolved_incident_is_removed(tmp_path)
|
|||
assert obs.world_state["incidents"][inc_id]["status"] == "resolved"
|
||||
assert obs.world_state["incidents"][inc_id]["resolved_reason"] == "manual_operator"
|
||||
assert not flag.exists()
|
||||
|
||||
|
||||
def test_resolve_requests_dir_is_group_writable(tmp_path, monkeypatch):
|
||||
"""world/resolve-requests/ must be group-writable so an SSH operator
|
||||
(group aerbot, not the observer's own user) can drop a resolve flag file
|
||||
without docker exec — mkdir(mode=...) alone is masked by the process
|
||||
umask, same defect/fix as executor.py's INBOX_DIR_MODE (2026-08-06)."""
|
||||
old_umask = os.umask(0o022)
|
||||
try:
|
||||
obs = _make_observer_simple(tmp_path)
|
||||
finally:
|
||||
os.umask(old_umask)
|
||||
import observer.observer as obs_mod
|
||||
|
||||
mode = obs_mod.RESOLVE_REQUESTS_DIR.stat().st_mode & 0o777
|
||||
assert mode == 0o775
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
"""action_id uniqueness for container_restart (2026-08-26) and redeploy
|
||||
(2026-08-27, same latent risk, same fix).
|
||||
"""action_id uniqueness for container_restart (2026-08-26 fix).
|
||||
|
||||
Before this fix, _generate_recommendation() built container_restart action
|
||||
ids as the bare `container-restart-<node>-<service>` — no timestamp, no
|
||||
|
|
@ -173,51 +172,10 @@ def test_fallback_bare_id_stable_across_repeated_calls(sup, tmp_path):
|
|||
assert pending[0].name == "container-restart-piha-paperless.json"
|
||||
|
||||
|
||||
def test_redeploy_action_id_falls_back_to_bare_without_incident(sup, tmp_path):
|
||||
"""Non-container_restart drift (redeploy path) with no linked incident
|
||||
record keeps the pre-fix bare node-service id, same fallback as
|
||||
container_restart."""
|
||||
def test_redeploy_action_id_stays_bare(sup, tmp_path):
|
||||
"""Non-container_restart drift (redeploy path) is out of scope for this
|
||||
fix and keeps its existing bare node-service id."""
|
||||
drift = _drift("piha", "outline", trigger_type="service_unhealthy")
|
||||
sup._generate_recommendation(drift)
|
||||
|
||||
assert (tmp_path / "actions" / "pending" / "redeploy-piha-outline.json").exists()
|
||||
|
||||
|
||||
def test_redeploy_action_id_carries_incident_started_at_suffix(sup, tmp_path):
|
||||
"""Domknięcie COMMIT 2 z task/incident-resolve-fix (2026-08-27): redeploy
|
||||
ids carry the same started_at suffix as container_restart, closing the
|
||||
same latent node+service collision risk."""
|
||||
_seed_incident(sup, "piha", "outline", "inc-3000-piha-outline", started_at=3000)
|
||||
drift = _drift("piha", "outline", trigger_type="service_unhealthy")
|
||||
|
||||
sup._generate_recommendation(drift)
|
||||
|
||||
pending = _pending(tmp_path)
|
||||
assert len(pending) == 1
|
||||
assert pending[0].name == "redeploy-piha-outline-3000.json"
|
||||
|
||||
|
||||
def test_redeploy_new_incident_after_old_completed_gets_different_action_id(sup, tmp_path):
|
||||
"""Same collision scenario as the container_restart case, for redeploy:
|
||||
a second, later incident for the same node/service must not collide
|
||||
with the first incident's already-completed action file."""
|
||||
_seed_incident(sup, "piha", "outline", "inc-3000-piha-outline", started_at=3000)
|
||||
drift = _drift("piha", "outline", trigger_type="service_unhealthy")
|
||||
sup._generate_recommendation(drift)
|
||||
|
||||
first_action_path = tmp_path / "actions" / "pending" / "redeploy-piha-outline-3000.json"
|
||||
assert first_action_path.exists()
|
||||
|
||||
completed_dir = tmp_path / "actions" / "completed"
|
||||
completed_dir.mkdir(parents=True, exist_ok=True)
|
||||
first_action = json.loads(first_action_path.read_text())
|
||||
first_action["status"] = "completed"
|
||||
(completed_dir / first_action_path.name).write_text(json.dumps(first_action))
|
||||
first_action_path.unlink()
|
||||
|
||||
_seed_incident(sup, "piha", "outline", "inc-4000-piha-outline", started_at=4000)
|
||||
sup._generate_recommendation(drift)
|
||||
|
||||
second_action_path = tmp_path / "actions" / "pending" / "redeploy-piha-outline-4000.json"
|
||||
assert second_action_path.exists()
|
||||
assert json.loads((completed_dir / "redeploy-piha-outline-3000.json").read_text())["status"] == "completed"
|
||||
|
|
|
|||
Loading…
Reference in a new issue