133 lines
6.6 KiB
Markdown
133 lines
6.6 KiB
Markdown
# Reflect skill — review 2026-09-02
|
||
|
||
Stav: nálezy review, opravy navrženy, čekají na schválení implementace
|
||
Datum: 2026-09-02
|
||
|
||
Review prošlo celý skill: SKILL.md, README.md, `reflect_apply.py`, `reflect_auto.py`,
|
||
`reflect_distill.py` a všech 168 testů (prošly, 1.1 s). Celkový verdikt: nadprůměrně
|
||
dobře napsaný — „záruky v kódu, ne v promptu" je proveden důsledně, testy kódují
|
||
racionalu u každého assertu. Níže jsou problémy v pořadí závažnosti + návrh opravy
|
||
u každého.
|
||
|
||
## 1. Fold přeloženého open nálezu zahodí drafted patch a skip count (bug)
|
||
|
||
`merge_findings` (reflect_auto.py ~522) dědí `regression_of` a `history`, ale ne
|
||
`patch`, `patch_drafted_at` ani `skipped`. Jakmile noční běh znovu spatří stejný
|
||
`open` pattern, `supersede` starý záznam zahodí a nový vzniká bez těchto polí.
|
||
|
||
Následky:
|
||
|
||
- patch složený při review přes `--set-patch` (agent ho pracně ověřil proti
|
||
souboru) zmizí; SKILL.md krok 2 tvrdí „`patch_drafted_at` says an earlier
|
||
review drafted it" — po jedné noci to neplatí
|
||
- „deferred 2× already" z kroku 3 se vynuluje — nález se předkládá donebezedne
|
||
bez viditelné historie odkladů, i když ho uživatel už několikrát odložil
|
||
- audit log (`DRAFTED`, `SKIPPED`) ukazuje práci, na kterou store už neodkazuje
|
||
|
||
**Fix:** v `merge_findings` při foldu open/watch předchozího záznamu přenést:
|
||
|
||
```python
|
||
if previous and previous["status"] == STATUS_OPEN:
|
||
if previous.get("patch") and not item.get("patch"):
|
||
# drafted during a review, verified against the file — do not throw it away
|
||
patch = previous["patch"] # do Finding(...)
|
||
patch_drafted_at = previous.get("patch_drafted_at")
|
||
skipped = previous.get("skipped") # deferral history survives the fold
|
||
```
|
||
|
||
Pole `patch_drafted_at` a `skipped` je potřeba přidat do `Finding` dataclass a
|
||
`to_json()` (podmíněně jako ostatní volitelná pole). Nový patch z analýzy má
|
||
přednost před starým draftem; jinak se drží draft z review. Testy: fold open
|
||
nálezu s `skipped={count:2}` a drafted patchem → nový záznam obojí nese;
|
||
nový patch z modelu draft nepřepisuje, ale nahrazuje.
|
||
|
||
## 2. `reflect_apply.py` nechrání vlastní store jako cíl patche (designová mezera)
|
||
|
||
`_resolve_target` odmítne cestu mimo workspace, ale klidně aplikuje patch na
|
||
`reflect/findings.jsonl`, `reflect/state.json` nebo `log/reflect.log`. Celá
|
||
filozofie skillu je „do audit trail píše jen reflect_apply" — ale reflect_apply
|
||
sám může patchem přepsat audit trail (typicky změnit `rejected` záznam zpět na
|
||
`open`, což oživí zamítnutý vzor). Stane se to „se schválením uživatele", které
|
||
v diffu snadno přehlédne, že jde o store.
|
||
|
||
**Fix:** explicitní blocklist v `check_patch` / `_resolve_target`
|
||
(reflect_apply.py):
|
||
|
||
```python
|
||
PROTECTED = ("reflect/", "log/reflect.log")
|
||
|
||
def _resolve_target(workspace, relative):
|
||
target = (workspace / relative).resolve()
|
||
if not target.is_relative_to(workspace.resolve()):
|
||
raise ApplyError(f"{relative} resolves outside the workspace")
|
||
if target == (workspace / FINDINGS_REL).resolve() or \
|
||
any(target.is_relative_to(workspace / prefix) for prefix in PROTECTED):
|
||
raise ApplyError(f"{relative} is part of the reflect store — not a patch target")
|
||
...
|
||
```
|
||
|
||
Důvod zdůvodnit v chybové hlášce („the audit trail is never a patch target").
|
||
Pozn.: `set_patch` tím kryje i draft, nejen apply. Test: patch s
|
||
`file: reflect/findings.jsonl` → exit 2, store netčen.
|
||
|
||
## 3. Vakuózní assert v testu (test_reflect_auto.py)
|
||
|
||
`test_first_run_has_no_trend_to_show` tvrdí `"(minule" not in report`, ale
|
||
`_rate_line` generuje anglické „(previous run …)". Assert nikdy nemůže selhat,
|
||
test tedy nic nehlídá.
|
||
|
||
**Fix:** `assert "(previous" not in report`. Jednořádková změna.
|
||
|
||
## 4. Noise prefix `"cli"` chytá i `client*` (případné falešné vyřazení)
|
||
|
||
`key.startswith(NOISE_PREFIXES)` — session `client_xyz` (nebo cokoli začínající
|
||
„cli") se tiše vyřadí z analýzy. Prefix-match na krátkých prefixech je
|
||
přístřelen. Podobně base64 session jména obsahující `-`/`_` (jsou v urlsafe
|
||
abecedě) se nedekódují kvůli heuristice `"_" in stem or "-" in stem` —
|
||
legitimní stará session se pak chytne prefixem, nebo naopak neprojde.
|
||
|
||
**Fix:** noise match na hranici klíče: session klíče mají tvar
|
||
`<prefix>_<rest>` resp. base64 bez `_`, takže matchovat
|
||
`key == prefix or key.startswith(prefix + "_")`. Případně (jednodušeji)
|
||
přejmenovat prefix na `cli_` v NOISE_PREFIXES, protože reálné machinery session
|
||
jsou `cli_<…>`. Test: `client_abc` prochází, `cli_kimi-ollama-test` ne.
|
||
|
||
## Menší
|
||
|
||
### 5. Git fingerprint se nekontroluje při LLM error cestě
|
||
|
||
`_resolve_findings`: fingerprint se porovná jen po úspěšném tahu. Když tah
|
||
skončí LLM errorem a agent v tu chvíli něco zapsal, guard se neprojeví a
|
||
run pokračuje. Riziko je teoretické (error odpověď znamená, že k zápisu
|
||
s nejvyšší pravděpodobností nedošlo), ale guard je zadarmadlo dokončit.
|
||
|
||
**Fix:** porovnat fingerprint i na začátku error větve
|
||
(`if result.stop_reason == "error" or result.error:`) — stejná kontrola,
|
||
stejná hláška.
|
||
|
||
### 6. `MIN_MESSAGES=5` počítá i tool výsledky
|
||
|
||
`distill_session` inkrementuje `message_count` pro user, assistant i tool
|
||
role. Session s 1 user zprávou a 2 tool cally (celkem 5 záznamů) projde
|
||
prahem, přestože je to jeden dotaz — nižší signál, ne rovnou chyba.
|
||
|
||
**Fix (volitelné):** počítat jen user + assistant zprávy
|
||
(`message_count += 1` jen v těch dvou větvích). Tool results počítat jako
|
||
součást tahu, ne jako zprávu. Existující testy `message_count == 6` adaptovat.
|
||
|
||
### 7. Neatomičnost mezi `git commit` patche a `_save(findings)`
|
||
|
||
Crash mezi commitem patche a zápisem store zanechá soubor patched, ale store
|
||
`open` (bez audit linky). Re-apply se správně odmítne na chybějícím `old_text`,
|
||
ale audit stopa pro ten commit chybí. U single-user workspace akceptovatelné;
|
||
zmiňuju pro úplnost. Plná atomicita (např. save-first-then-commit s rollbackem
|
||
store) nedoporučuju — přidá složitost pro okrajový scénář. Spíš uvážit
|
||
pořadí: nejdřív `_save` + audit, pak commit; pak crash zanechá `applied`
|
||
záznam bez commitu, což reflektuje hlášku `git revert` — ale zase commit
|
||
refusu zanechá store applied bez commitu. Trade-off, nechává rozhodnutí
|
||
na implementaci.
|
||
|
||
## Pořadí implementace
|
||
|
||
1 → 2 → 3 → 5 → 4 → (6, 7 volitelné). Položky 1–3 jsou přímé rozpory se
|
||
zárukami deklarovanými v README („Záruky"), 5 a 4 jsou levné tvrdnutí guardů. |