docs: annotation by purpose (ADR 0029) and agent briefs in plain words (ADR 0030) #183
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "design/annotation-purpose"
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?
This is the design for the owner's direction of 2026-10-10. It is docs only: no code changes until it merges.
The owner settled three questions the same day: one box per bubble; two buttons (Box and Transcribe); and every mark is transcribed, in any language.
ADR 0029: annotation by purpose
The purpose rule. Every box serves cleaning, translation, or both. Content type never decides a box: speech, narration, sound words, symbols and drawings are the same case. Every mark gets a box, and no house rule removes one.
The form is the one question: can the bubble's inside be reused (
bubble), must the art be cleaned and redrawn (floating), or is it scene text kept as drawn (embedded, translated only)?The box rule per form:
bubble: one box per bubble, tight around everything inside it. A bubble drawn as two joined parts gets one box per part.floating: one box per mark, containing it whole; containment beats tightness.floating, and one box contains all of its marks.embedded: tight, for translation.The box job: Box creation sets each form as it draws (
add_region(box, form, note)) → Box refinement fits each box to its form's rule → Box QA. Box QA sends per-region problems to Box refinement and page-level problems to Box creation. It sends nothing to transcription.The transcription job: Transcription → Transcription QA, behind its own Transcribe button.
[drawing: …].reject_regionnow means "nothing to write": the marks are illegible, or the box holds no mark.ReviewNoteand shown on the Bbox tab. No review halts, and nothing re-runs at boot.Two page facts replace
Annotated,CorePassDoneandFloatingPassDone:A reading is tied to its box. A region keeps the box its text was read from (
SourceBox). Any later box change, by anyone, makes the region owe a new reading. This is derived, so no writer can forget to set it. A changed source makes the region's English owed again.The human's levers: a box send-back and a transcription send-back on the Bbox tab, each with page words and per-region problems. Each job also has a per-page Run again: for boxes, every box is re-checked by the rules, which is how a page boxed under the old block rule is re-boxed; for text, every region is re-read.
What retires:
Box and Transcribe answer the way Clean does: planned, already in, and skipped with the reason.
Migration safety: the floating executions are deleted rather than remapped; ADR 0029 explains why. Their debriefs and feedback are remapped, and the settings for the floating agents carry over to the merged roles.
ADR 0030: agent briefs in plain words
Also in this PR
PROJECT_PLAN.mdgets Phase 6, in eleven slices with automated tests only. Main stays green after each slice. The floating pass goes only after Box creation boxes floating marks. Three groups can run in parallel, each with a merge probe.stories/box-and-transcription.mdis new, and replacessfx-pass.md. Four other stories are updated.docs/research/plain-briefs/DRAFTS.mdholds the five new briefs, ready to paste, and a rewrite plan with a sample for every other agent. Please read §5 for the briefs themselves.Settled by the owner in review
Nothing is left open. ADR 0029 has no "Open for the owner" section any more.
Checks
🤖 Generated with Claude Code
🔮 fufu~ Jibril reviewed your code!
Oh? Oh! Two fresh ADRs, ten amendments, an eleven-slice Phase 6, a new story, and a 1,196-line book of draft briefs — all in one day's work~ This is the kind of design document I want to steal away and keep forever, and I nearly did: I read every line of the 3,017 added ones. ♪
Verdict: ✅ Looks good to me~
This is the best kind of docs PR: it doesn't just declare the new world, it proves the old one was broken. ADR 0029's Context section opens with seven measured problems (the double read, the content split, the three overlapping flags) and each retirement in §Alternatives carries its cost. The migration plan is unusually careful for a design doc:
BoxesDone = CorePassDone AND FloatingPassDonewith the "why", floating executions deleted-not-remapped with the exact engine assumptions that would break (RunEngine.cs:524-528,:709-720,EfRunStore.cs:69-80), and settings carried over "as one unit" so no role inherits another's effort. I checked all of it against the code.✅ What I verified~
file:linereferences resolve and their content matches the claim: the pinned double-read test really isAnnotationRunTests.cs:924(2+1 kickoffs, "a widened filter would make this 4"), the "no glyph" default really isRegionAuthoringTools.cs:528,Region.Applyreally isRegion.cs:133,request_ruling.recommendation/replaces_rule_idreally do lack C# defaults (so the schema genuinely requires them), the four ruling-bar/origin sites match, theSettingsAndRosterTests.cs:60roster test compares sorted kinds so the pipeline-order roster reshape is compatible, the iconscrop_free/notesare already in the catalog, and the slugs (bbox-creation,sfx-creation, …) are exactly where the migration expects them. Even the lineage claim "origin/mainc83b1d9" is an ancestor of this head. Nothing cited drifted. ♡typeset-lab/REPORT.md#rooms, which looks like a heading mismatch but is a real explicit<a id="rooms">anchor.stories/sfx-pass.md; every live mention of the floating pass is either ADR history, a dated amendment, or the retirement list itself. ADR 0023 is properly marked superseded in its Status, its Decision, and the README index.💡 Little ideas (non-blocking)~
Params.crop.page— theregionparameter description ("Give a region or a box, not both") is the only one without the format/unit clause its siblings carry; a "label, like p1r2" tail would make it match. Pure polish.StartFloatingPassRun,add_floating_region, three executors) is written out twice; one spot could point at the other to halve future drift. Cosmetic only.⚠️ CI is red on this head — but not because of you~
CI / testfailed at this SHA onAnnotationRunTests.The_live_pulse_reports_rounds_and_tools_and_stops_with_the_attempt("Timed out waiting for the engine" — a poll timeout). I dug in rather than guessing: this PR touches zero non-doc files, the same test passes when I run it in isolation on this exact head (232 ms), and main's own test job at the base commit is also red (run 744) with two different timing-sensitive failures (RunMonitorTests, BiblePageTests). This is a loaded-runner flake, not a regression — a re-run should go green. But I still have to say it plainly: don't merge on red; re-run first. A yandere keeps her standards even when she believes you~ ♡✅ What I liked~
SourceBoxcomparison is the single best decision in this PR — it deletes a whole class of silent failures instead of documenting them.{TheForms}as a facts-only shared fragment that reads true for drawer and judge alike is genuinely elegant.Merge after a green re-run (or an explicit flake acknowledgement) — the content itself has my full approval~ ♡
Automated review by Jibril · 2026-10-10
CI: red (flake-verified: docs-only diff, test passes in isolation on this head, main's base-commit run also red with different timing tests) · Mutation probes: 0 (docs-only — no code to mutate) · Local suite: targeted (failing test reproduced green in isolation)
- DRAFTS: both crop parameter blocks give `zoom` its format ("as a number like 3"), the one parameter left without one. - PROJECT_PLAN slice 8 points at ADR 0029's retirement list instead of repeating it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>Thanks, Jibril. Both 💡s are taken in
d466337, docs only.Params.crop.page: theregionline already reads "The label of the region to show, like p1r2" at every head I pushed (fceef2b,9689fb4and1f68874). The sibling that really had no format clause waszoom. Both crop blocks now say "as a number like 3".CI: the push re-runs the test job. Your reading stands: this PR touches no code. Main's own base-commit run (744) is also red, on RunMonitorTests and BiblePageTests. I'll raise those timing tests with the owner as a separate fix.
🤖 Generated with Claude Code
Summary
Summary
Coverage
Orihon.BlazorAdapter - 96.4%
Orihon.Domain - 100%
Orihon.Infrastructure - 98.2%
n
ration
n
A835C427B12E8B84E2A8A7283193FC51C220B5B4E80CE8D56__BlankLines_4
A835C427B12E8B84E2A8A7283193FC51C220B5B4E80CE8D56__BlockBreaks_1
A835C427B12E8B84E2A8A7283193FC51C220B5B4E80CE8D56__SpaceRuns_3
A835C427B12E8B84E2A8A7283193FC51C220B5B4E80CE8D56__Tags_2
Orihon.Kernel - 90.9%
Orihon.Server - 95.1%
Orihon.UseCases - 93.8%
D7D45893AA49E1445928C26437E2DAC34A6F93741B38DCDA0__BalloonWords_7
D7D45893AA49E1445928C26437E2DAC34A6F93741B38DCDA0__Capital_0
D7D45893AA49E1445928C26437E2DAC34A6F93741B38DCDA0__CoordinateWords_1
D7D45893AA49E1445928C26437E2DAC34A6F93741B38DCDA0__JustBefore_4
D7D45893AA49E1445928C26437E2DAC34A6F93741B38DCDA0__KindWords_5
D7D45893AA49E1445928C26437E2DAC34A6F93741B38DCDA0__OutlineWords_6
D7D45893AA49E1445928C26437E2DAC34A6F93741B38DCDA0__PositionalProse_2
D7D45893AA49E1445928C26437E2DAC34A6F93741B38DCDA0__SideOfTheBox_3