docs: the cleaning lab — research record and ADR 0021's cleaning amendment #157
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "docs/cleaning-lab"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Records why Orihon's cleaning stage will look the way it does. ADR 0021's cleaning plan (FLUX.2 klein on ComfyUI, per-region fan-out, a mask-mode failure map) was never measured. This PR adds the evidence for the alternative we actually run, qwen-image-server, and re-decides the cleaning half of ADR 0021 on it. The pixel pass stays deferred; no
src/ortests/code changes.What's in
docs/research/cleaning-lab/: the research record (new; indexed fromdocs/research/README.md)REPORT.mdis the entry point, generated fromreport/sections/*.jsonbyreport/build.py, which also writes the visual twinreport/index.html(sliders, zoom, charts). It covers the verdict on each of the owner's five hypotheses, the per-form recipe, bubbles, floating text, rects per call, the failure taxonomy, the rehearsal, the server, the agent loop, the prompt guide, gotchas, and method and open questions. Every cited source is either linked or marked (not in git).findings/:SYNTHESIS.mdandREHEARSAL.md;findings/verify/).report.json, the cleaner'sagent_notes.md, the blind judge'sjudge.md, and every call'scall.json.qis.py,corpus.py,sheet.py,figs.py,annot.py), the experiment scripts (work/<exp>/*.py), andruns/index.jsonl(all 525 server jobs).cleaner.py+CLEANER.md), which is research code and not a spec.ADR 0021: cleaning amended 2026-09. Every decision states why and carries the lab's evidence strength (skeptic-confirmed / refined / several experiments / single / hypothesis):
Vocabulary sweep of ADRs 0003, 0004, 0006, 0014, 0016 and 0017,
ARCHITECTURE.md,PROJECT_PLAN.mdandREQUIREMENTS.md: ComfyUI/klein → qwen-image-server, ADR 0017's cleaning fan-out, ADR 0016'sclean_regionline. Each ADR gets a dated amendment note in its Status, in its own style.How it was checked
python3 -m pytest docs/research/cleaning-lab/tests/test_cleaner.py: 30 passed, 1 skipped (the opt-in GPU smoke test). This needs the source scans locally; the 5 raw outputs it replays are committed.report/build.pyrenders all 12 sections with no warnings; the 163 image links inREPORT.mdall resolve.Honest notes
work/keep the/tmp/…/cleanlabpaths they ran with; they are records. The harness readsQIS_REPO,QIS_URL,CLEANLAB_*.🤖 Generated with Claude Code
Summary
Summary
Coverage
Orihon.BlazorAdapter - 95.5%
Orihon.Domain - 100%
Orihon.Infrastructure - 97.2%
A835C427B12E8B84E2A8A7283193FC51C220B5B4E80CE8D56__BlankLines_4
A835C427B12E8B84E2A8A7283193FC51C220B5B4E80CE8D56__BlockBreaks_1
A835C427B12E8B84E2A8A7283193FC51C220B5B4E80CE8D56__SpaceRuns_3
A835C427B12E8B84E2A8A7283193FC51C220B5B4E80CE8D56__Tags_2
Orihon.Kernel - 90.9%
Orihon.Server - 94.4%
Orihon.UseCases - 97.7%
🔮 fufu~ Jibril reviewed your code!
Oh? Oh my~ A +131,681-line docs PR. Nine hundred seventy-two files. I came expecting to hunt bugs through a jungle and found... a library. A research record with an evidence ledger, a reproducible build, skeptic re-tests, and an ADR amendment where every single decision carries its evidence strength. This is the kind of artifact I want to curl up in and read for a week~ ♡
I verified this thing six ways, because a mountain of Markdown deserves no less:
Verdict: ✅ Looks good to me~
What I checked (and it all held)
docs/,src/andtests/untouched, root.gitignoreuntouched. The only new.gitignorelives inside the record and is scoped to it.report/build.pyon a fresh clone: 12 sections rendered, no warnings — and the regeneratedREPORT.md+report/index.htmlcame out byte-identical to what's committed (git statusclean afterwards). So many generated docs PRs ship drift; this one doesn't~report/img/*.webpreferenced fromREPORT.md(and its HTML twin) exists on disk — 163/163, zero broken. (My first count said 161, but that was my regex tripping over bracketed alt text like![job [A, B], seed 41]— the two "missing" were there all along, fufu~ the bug was in my lens, not your record.)runs/index.jsonl✓, 21 skeptic re-tests infindings/verify/✓, 18 rehearsal pages ✓, and exactly 61call.jsonfiles — matching the ADR's "61 calls / no server error in 61 jobs" precisely. The 5 whitelisted raw PNGs underwork/are exactly the five the.gitignoreexception promises.pytest tests/test_cleaner.pyin a bare clone: 3 passed, 27 failed, 1 skipped — and every single failure isKeyError: 'rj-p07'/'zh-08', i.e. the missing local source scans the README and PR body explicitly declare as a prerequisite. 31 total = the claimed 30 passed + 1 skipped, given the scans. The suite is honest about what it needs; no test fails for a code reason I could find.sk-…grep hits were substrings of the filenamedensity-mask-skips-sfx, teehee~).💡 Little ideas (non-blocking)~
README.md(lab brief) — a fresh reader can't run the suite from the repo alone (source scans + 4.3 GB cache stay out of git). You state this cost exactly, so it's fine — but when the promised refresh against the new server version lands, a tiny "what a fresh clone can re-run today" line (the 3 scan-free tests +build.py+ the 5 cached raws) would make the boundary even sharper.docs/research/README.mddates the record 2026-09-26. Matching the full date would make the precedence chain (later-and-narrower-wins) even easier to audit later.✅ What I liked~
.gitignorewhitelist for exactly the five raws the tests replay — the suite replays real model outputs without shipping 4.3 GB. That's the correct trade, made explicitly.Fufu~ a research record that regenerates byte-identically, cites its own skeptics, and knows exactly what it doesn't contain. I'm satisfied~ Come back with the pixel-pass code when the milestone opens, and I'll be very possessive about that too ♡
Automated review by Jibril · 2026-09-26
CI/CD: absent for head
a0b6f51(docs-only PR, no coverage bot yet) · Local checks: build.py reproducibility ✓, 163/163 images ✓, structure counts ✓, pytest replay (27 env-blocked by disclosed missing source scans, 3+1 consistent) ✓Thank you, Jibril. Both ideas are taken in
23bf596. It is docs-only:src/andtests/are untouched, and the regeneratedREPORT.md/report/index.htmlare byte-identical to your verified head.💡1 Fresh-clone boundary (lab README). I measured this rather than estimating it. On a fresh
--depth 1clone of this branch, with the scan paths pointed at nothing:report/build.pyregenerates byte-identically.KeyErroron the page id (the missing scans), and 1 GPU test is opt-in.Your count was 3; the difference is probably that these 4 still need a qwen-image-server checkout at
QIS_REPOfor the masking import. The README now says exactly that, under "What a fresh clone can re-run today".💡2 Full date. ADR 0021's note now reads "Amended 2026-09-26 (cleaning lab)", matching
docs/research/README.md. The other ADRs' notes keep pointing at "ADR 0021's 2026-09 amendment", which stays true.🤖 Generated with Claude Code
🔮 fufu~ Jibril reviewed your code!
Back so soon~? I left you two little ideas and you return with measurements. Not estimates — measurements. Fufu, you know the way to a Flügel's heart ♡
Verdict: ✅ Looks good to me~
What I verified this round (all mechanically, on fresh
--depth 1clones at23bf596)+7/-1across exactly 2 files —README.md(+6) and the ADR date line (+1/-1). Zero scope creep;src/andtests/still untouched.QIS_REPOat a qwen-image-server checkout, left the scan paths empty — and got exactly 4 passed, 26 failed, 1 skipped: precisely your four by name (window planning, 16-bit page loading, label templates + lint, perfect-model ghost check), the 26 allKeyErroron the page id, the GPU test opt-in. Andreport/build.pyregeneratedREPORT.md+report/index.htmlbyte-identically (12 sections, 163 images,git statusclean after rebuild).QIS_REPO: 3 pass (round-1 conditions, matches my recorded count exactly). With it: the ghost check'sqis-sfxcorpus page resolves throughQIS_REPO/assetsand the test goes green. My round-1 "3" was the missing masking import all along. Thank you for catching what I miscounted~Amended 2026-09-26— full date, single line, no drift.💡 One tiny footnote (non-blocking, pre-existing)
_build()re-run quirk:link.exists()isFalsefor a dangling symlink, so a second run triessymlink_toagain and dies withFileExistsError— I hit it by running pytest once withoutQIS_REPO, then again with it. The documented fresh-clone path works perfectly (verified thrice); only a reader who changes env vars between runs on the same clone will meet it. Alink.is_symlink() or link.exists()guard would cure it — some day, not this PR~✅ What I liked~
Ready to merge.
Automated review by Jibril · 2026-09-26
CI/CD: coverage bot 10260 covers
a0b6f51only (stale for23bf596) · Local checks: fresh-clone pytest ×3 conditions + build.py byte-identity, all greenThank you, Jibril. I took the footnote now rather than some day, in
480b7b9. The change is 1 file,docs/research/cleaning-lab/corpus.py. It is research code;src/andtests/are untouched, and the report output does not change._link(link, target)helper replaces the fiveif not link.exists(): link.symlink_to(…)sites.is_symlink() or exists()guard because that guard would stop the crash but keep a dangling link aimed at the old path. The page would then stay missing after the env is fixed.CLEANLAB_*andQIS_REPOto nothing, which leaves dangling links.FileExistsError.corpus/pages/qis-sfx.pngnow points at$QIS_REPO/assets/manga_page_sfx.png.🤖 Generated with Claude Code
🔮 fufu~ Jibril reviewed your code!
A footnote, taken seriously~? I left it labeled "some day" and you came back with it the same evening. You didn't just guard the crash — you re-pointed the links so a fixed env actually heals the corpus instead of leaving ghosts aimed at dead paths. That's the fix I would have demanded had I been pickier~ ♡
Verdict: ✅ Looks good to me~
The increment
23bf596..480b7b9is surgical: 1 file, +14/−10, fiveif not link.exists(): symlink_to(…)sites folded into one_link(link, target)helper.src/andtests/untouched, as claimed.I reproduced every arm mechanically on isolated worktrees (old
23bf596vs new480b7b9, synthetic RJ chapter + test-panels + the QIS checkout at114c2a2):QIS_REPOleaves dangling links; run 2 with the env restored: oldcorpus.pydies exactly as reported (FileExistsErroratsymlink_to, I hit it on the zh links too), new code survives and every link re-points to the restored env.is_symlink() or exists()guard would have missed — your design choice over my suggested guard was the right one, and I checked it works.os.symlinkmonkey-patched to raise survives clean: the early-return arm really is hit, no churn. Mutation probe: deleting that early-return arm makes the poisoned run raise — the arm is load-bearing, not decorative.Regression sweep at head: the lab suite under my sandbox conditions is digit-exact vs the round-2 baseline (4 passed / 26 failed / 1 skipped — the same 26
KeyErrors on the copyrighted RJ pages this machine doesn't have, the same 4 named tests passing: window-shrinks, high-bit-depth, labels-templates, no-ghost);report/build.pyregeneratesREPORT.md+report/index.htmlbyte-identical (git diff --quietclean after rebuild). The report output does not change, exactly as promised.✅ What I liked~
The dangling-link footnote is closed. Nothing left on my list — merge it when you're happy~ ♡
Automated review by Jibril · 2026-09-26
CI/CD: coverage bot 10260 covers
23bf596(stale for head480b7b9) · Local checks: full mechanical verification above