From e8c123ced054cacabff3be378f4256c2bea117f2 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sun, 22 Nov 2026 16:30:21 +0100 Subject: [PATCH] Record the comprehension check: scoring run at 16d9b3a0, overall 6.13, Locality lowest at 5.63; refresh floor item 300 --- docs/comprehension-history.md | 35 +++++++++++++++++++++++++++++++++++ todo.md | 35 +++++++++++++++-------------------- 2 files changed, 50 insertions(+), 20 deletions(-) diff --git a/docs/comprehension-history.md b/docs/comprehension-history.md index 24dd2685..cf57a115 100644 --- a/docs/comprehension-history.md +++ b/docs/comprehension-history.md @@ -4228,3 +4228,38 @@ Inherited architect, decided by: - Locality: `bin/plan/todo_table.py:110` `Item.awaits_merge`: a field nothing in its own package sets; waiting reads it, so it depends on a caller three packages out having run the marking. - Locality: `bin/loop_claude/loop/chunk_windows.py:161` `chunks_to_start`: the stop condition is split across two packages, and one half is a string's truthiness. - Locality: `bin/do_epic/scheduler.py:96` `open_blockers`: four functions gained a defaulted `unblocking`, so a caller that forgets it silently gets the old behaviour. + +## 2026-11-22T15:29:07Z, item-503 at 16d9b3a0 + +| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | +|---|---|---|---|---|---| +| Junior A | 6 | 5 | 5.5 | 5 | 5.5 | +| Mid A | 7 | 5.5 | 6 | 5 | 6 | +| Maintainability senior | 7 | 5.5 | 6 | 6 | 6 | +| Inherited architect | 7 | 6.5 | 6 | 7.5 | 7 | +| Mean | 6.75 | 5.63 | 5.88 | 5.88 | 6.13 | + +Junior A, hardest first: + +- Navigation, Overall: `bin/agent_cycle/run.py:102` `archived`: cites a close.py that doesn't exist, which cost a search +- Locality, Shape, Overall: `bin/do_epic/main.py:538` `handed_on`: five-way branch over outcome, automation and merged-status config +- Locality: `bin/do_epic/scheduler.py:172` `start_chunks`: chunk state is rebuilt from tmux window names no module owns +- Self-sufficiency: `bin/agent_cycle/run.py:32` `Cycle`: the why of its 17 fields sits in docs/decisions.md + +Mid A, hardest first: + +- Locality, Overall: `bin/chunk_pr/main.py:587` `levelled_and_finished`: step order is load-bearing and unmarked +- Shape, Overall: `bin/do_epic/main.py:539` `handed_on`: five branches over three configuration facts +- Self-sufficiency: `bin/larv_review/main.py:1` module docstring: the rules for votes and owed runs live only in a 167-line help text + +Maintainability senior, hardest first: + +- Locality, Overall: `bin/do_epic/main.py:379` `parked_through`: starts other chunks from what reads like a wait +- Locality: `bin/agent_cycle/tmux.py:92` `as_listed`: chunk state shared across processes in window names +- Shape: `bin/plan/ranking.py:239` `score`: the OLD_SHAPE fork doubles the paths through ranking + +Inherited architect, would restructure first: + +- Navigation, Shape, Overall: `README.md:234` "Packages under bin/": about 85 entries at one level, six packages missing from the list +- Locality: `bin/rule_hook/main.py:94` `breaches_of`: the round cap binds at commit time, not at reviewer launch +- Shape: `bin/chunk_pr/main.py:167` `step`: seven subcommands and inline forge branches in one 764-line module diff --git a/todo.md b/todo.md index d68a490a..7d153958 100644 --- a/todo.md +++ b/todo.md @@ -55,7 +55,7 @@ | 499 | 0.23.0 | | defect | **Stop `todo-item add` and `edit` from waiting on a stdin that stays open without data, so a call without a heredoc ends at once.** | 2 | 2 | 2 | 4 | 2 | 1.5 by 3, 1.4 by 2 | 1.9 | | 445 | 0.23.0 | | | **Refuse a plan that holds an item a `Finish item ` commit already removed, so a merge resolution cannot bring a finished item back.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3, 1.1 by 2 | 1.8 | | 171 | 0.23.0 | | decision | **Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.** | 3 | 2 | 2 | 5 | 4 | 1.2 by 3, 1.4 by 3 | 1.8 | -| 300 | 0.23.0 | | owner | **Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Locality and Self-sufficiency first; today the scoring run at a357cc7b scored Navigation 7.00, Locality 6.00, Shape 6.13, Self-sufficiency 6.00 and Overall 6.38.** | 4 | 2 | 3 | 7 | 8 | code health by 8 | 1.7 | +| 300 | 0.23.0 | | owner | **Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Locality first, then Shape and Self-sufficiency; today the scoring run at 16d9b3a0 scored Navigation 6.75, Locality 5.63, Shape 5.88, Self-sufficiency 5.88 and Overall 6.13.** | 4 | 2 | 3 | 7 | 8 | code health by 8 | 1.7 | | 264 | 0.23.0 | | | **Report the comprehension seats and the escalated subagents as subagent types of their own in `routing-figures.md`, with their dollars.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 5 | 1.7 | | 323 | 0.23.0 | | | **Count a release review as landed once its pull request has merged, whatever its commits are titled.** | 3 | 2 | 3 | 6 | 3 | 1.4 by 3, 1.5 by 2 | 1.7 | | 342 | 0.23.0 | | | **Research the tooling agents read, search and run commands with once more, and file an item for each tool that cuts tokens a replay shows keep quality.** | 1 | 2 | 1 | 2 | 3 | 1.4 by 3, 1.5 by 2 | 1.7 | @@ -368,30 +368,25 @@ Have the gate, or `rank_todo.py --check` where it runs in a checkout, refuse a p Raised by the goals audit of PR #296. `bin/routing_figures/calls.py` groups a chunk's review rounds by the rung its worker started on, and calls for a routing change when a lower rung took more of them. Since PR #296 the reviewers may run above the worker's rung, on the one their item's E + I picks, and no figure groups rounds by it, though the archived worker line names the E + I it follows from. A cheap worker on an item of high E + I gets stronger reviewers, who may raise more rounds, and a call could then blame the worker's rung for them: an interrupt of lilleman that settles nothing (goal 1.2). -### 300. Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Locality and Self-sufficiency first; today the scoring run at a357cc7b scored Navigation 7.00, Locality 6.00, Shape 6.13, Self-sufficiency 6.00 and Overall 6.38. +### 300. Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Locality first, then Shape and Self-sufficiency; today the scoring run at 16d9b3a0 scored Navigation 6.75, Locality 5.63, Shape 5.88, Self-sufficiency 5.88 and Overall 6.13. -Filed by the comprehension check of PR #473 at 13d1550 (`larv-review record-scoring`), which printed `Floor:` and `Next:`, and refreshed from the run of PR #646 at a357cc7b. The lowest means are Locality and Self-sufficiency, both 6.00. Locality: do-epic's parking and scheduling carry order-dependent state across loop turns, state files and flocks, and no code enforces the order. Self-sufficiency: the why of thresholds and orderings sits behind `docs/decisions.md → …` pointers, 109 of them in 79 modules, and the review rules live in prose that several code sites repeat. Refresh this item's places and aim from the newest run before the chunk starts; do not file a second floor item. +Filed by the comprehension check of PR #473 at 13d1550 (`larv-review record-scoring`), which printed `Floor:` and `Next:`, and refreshed from the run of item 503's chunk at 16d9b3a0. The lowest mean is Locality, at 5.63; Shape and Self-sufficiency follow, both at 5.88. Locality: do-epic and chunk-pr run order-dependent steps and share chunk state through tmux window names (`handed_on`, `parked_through`, `start_chunks`, `levelled_and_finished`), and no code enforces the order. Shape: `bin/do_epic/main.py` and `bin/chunk_pr/main.py` are hubs of about 700 and 764 lines, and the OLD_SHAPE fork in `bin/plan/ranking.py` doubles the paths through ranking. Self-sufficiency: the why behind code sits behind `docs/decisions.md → …` pointers, 82 of them in 64 modules. Refresh this item's places and aim from the newest run before the chunk starts; do not file a second floor item. Aim: one ambitious refactor of the areas below, sized so every mean reaches 7.0 on the chunk's own scoring run. Where a place is already easier to read when the chunk starts, drop it. -Places the seats named, hardest first (`larv-review places`), Locality and Self-sufficiency first: +Places the seats named, hardest first (`larv-review places`), Locality first: -- Locality, Shape: `bin/do_epic/main.py:287` `parked_through`, with `:354` `resumed_news` and `:241` `chunk_run`: a three-step park and resume order, the `told`, `finished` and `news` flags and a poll that carries five locals across turns. The docstring gives the order, but no code enforces it and no comment states the loop's invariant. Three seats named it hardest; all three would least want to change it. -- Locality, Self-sufficiency: `bin/agent_cycle/routing.py:115` `unfinished_route`, with `:131` `escalated_route`: five rungs, a count, the escalation mark and the cap held at once. The module table resolves the what, but the why of each threshold is only in the decision log. Three seats named it. -- Locality: `bin/do_epic/scheduler.py:144` `start_chunks`: four overlapping sets feed a five-branch chain, counted under nested locks shared with loop-claude. Two seats named it. -- Locality, Shape: `bin/rule_hook/round_cap.py:10` `round_cap_breaches`, with `bin/review_rules/round_titles.py:33` `round_counts`, `bin/larv_review/reviewer_header.py:75` `unanswered_round` and `skills/larv-review/SKILL.md:89` "Round cap": the cap lives in four places across three packages, none owns the whole invariant, and the rules exist a third time in the help at `bin/larv_review/main.py:1`. Three seats named it. -- Shape, Self-sufficiency: `bin/project_config/settings.py:187` `load`: about twenty comprehension clauses in one `faults` list encode the rules that link settings; named predicates would make each findable. Two seats named it. -- Locality, Shape: `bin/chunk_pr/main.py:314` `merged`, with `:447` `levelled_and_finished`: a queue loop whose variables carry a string or a Failure, and a scoring-run check the name doesn't suggest. Two seats named it. -- Locality: `bin/plan/ranking.py:239` `score`, with `:144` `weigh`: the old and new table shapes run through the whole module. Two seats named it. -- Locality: `bin/agent_cycle/judge.py:76` `TASK_HEADING`, with `bin/model_routing/route.py:47` and `bin/loop_claude/loop/reload.py:36` `decode_handed`: archive and handover formats that a reworded heading or a renamed field breaks, guarded only by comments. Three seats named one of them. -- Shape: `bin/agent_cycle/judge.py:237` `quotes_checked`, with `bin/agent_cycle/run.py:150` `rule`: checks that quietly turn one verdict type into another, and one function that runs the judge, steps up and orders the archive writes. -- Locality: `bin/larv_review/plan.py:21` `Emptied`: a `str` subclass whose type carries meaning, lost by any code that rebuilds the string. -- Shape: `bin/do_epic/gates.py:42` `gate`: a long ordered chain where a missing value means something different on each line. -- Shape: `bin/agent_cycle/stuck_workers.py:52` `Watch.check`: the condition at line 59 mixes `or` and `and` without parentheses over state mutated out of sight. -- Self-sufficiency: `bin/agent_cycle/verdicts.py:41` and `bin/agent_cycle/run.py:103`: comments that cite `cycle.judge.re_ask_checked` and `close.py`, neither of which exists; `bin/agent_cycle/judge.py:116` `Rejected` names loop-claude in a module do-epic shares. -- Navigation, Shape: `README.md:225` "Packages under bin/": 84 entries in alphabetical prose with no grouping by layer, two bullets run together at `:239`, and 40 packages whose `__init__.py` is empty. -- Shape: `bin/loop_claude/loop/reload.py:18` `LoopRun`: loop-claude's core run state in a module named for self-reloading; `Run`, `ChunkRun` and `LoopRun` are one concept in three types. -- Locality: `reviewer-merge-trials/driver.py:4`: a frozen trial imports live code under `bin/`, so a refactor there breaks a record. +- Locality, Shape: `bin/do_epic/main.py:538` `handed_on`: a five-way branch over the outcome, the automation and the merged-status config. Two seats named it. +- Locality: `bin/do_epic/main.py:379` `parked_through`: starts other chunks from what reads like a wait. +- Locality: `bin/chunk_pr/main.py:587` `levelled_and_finished`: its step order is load-bearing and nothing marks it. +- Locality: `bin/do_epic/scheduler.py:172` `start_chunks`, with `bin/agent_cycle/tmux.py:92` `as_listed`: chunk state is rebuilt from tmux window names, shared across processes, which no module owns. Two seats named it. +- Locality: `bin/rule_hook/main.py:94` `breaches_of`: the round cap binds at commit time, not when a reviewer is launched. +- Navigation, Shape: `README.md:234` "Packages under bin/": about 85 entries at one level, and six packages missing from the list. +- Shape: `bin/chunk_pr/main.py:167` `step`: seven subcommands and inline forge branches in one 764-line module. +- Shape: `bin/plan/ranking.py:239` `score`: the OLD_SHAPE fork doubles the paths through ranking. +- Self-sufficiency: `bin/agent_cycle/run.py:32` `Cycle`: the why of its 17 fields sits in `docs/decisions.md`. +- Self-sufficiency: `bin/larv_review/main.py:1` module docstring: the rules for votes and owed runs live only in a 167-line help text. +- Navigation: `bin/agent_cycle/run.py:102` `archived`: cites a `close.py` that doesn't exist, which cost a seat a search. ### 264. Report the comprehension seats and the escalated subagents as subagent types of their own in `routing-figures.md`, with their dollars.