Answer prose round 1: 0 🔴, 13 🟡 (0 misread); make each docstring say what its function now does, and sort the README's text_files bullet

This commit is contained in:
2026-11-13 03:17:15 +01:00
parent 4b3ac621b8
commit ee241646e7
13 changed files with 17 additions and 19 deletions
+1 -1
View File
@@ -172,13 +172,13 @@ Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by t
- `mattermost_dm/` sends the human a Mattermost DM, for `mattermost-dm` and for loop-claude through `loop_effects`.
- `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read, and the list prices, which `routing_figures` and `transcript_archive` read.
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
- `text_files/` reads a Markdown file's `##` sections, quotes a passage and joins names into a list, stamps times in UTC, and replaces a file in one step, private where it is new.
- `release_plan/` reads `todo.md`'s items table and release versions, says which release is next and whether it is ready to cut (`release_standing.py`), and ranks the plan (`ranking.py`, with its score formula in `formula.py` and its blocker order in `blockers.py`). `goals_file.py` reads the goals file's sections, goals and goal weights, for the ranking and for `loop_claude`'s premises, and `citations.py` holds `todo.md` and `docs/decisions.md` to each other. `plan_file.py` reads, ranks, checks and writes a `todo.md`, for `larv_review`, `rank_todo.py`, `rule_hook` and `todo_item`.
- `repo_checks/` tests the repo itself.
- `review_rules/` holds the larv-review rules that several tools apply: its passes, its review folder, its round commit titles and the comprehension history's format.
- `routing_figures/` measures loop-claude's archive, and each of its projects' default branches, for loop-claude's routing calls.
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the parallel replay runner, the argument reader, the candidate rungs and the exits, and `judge_replay`'s rung search. It reads `loop_claude`'s retry count and models file, and finds that file through `loop_state`'s paths.
- `test_env.py` serves the tests.
- `text_files/` reads a Markdown file's `##` sections, quotes a passage and joins names into a list, stamps times in UTC, and replaces a file in one step, private where it is new.
- `transcript_archive/` stores loop-claude's transcripts. Its `project_key.py` names each project's archive folder, loop-claude session and models-file entry.
## Test
+1 -1
View File
@@ -12,7 +12,7 @@ from project_config.main import located
def owed_scoring_run(default: str, home: pathlib.Path, warn: typing.Callable[[str], None]) -> Failure | None:
"""A Failure saying which scoring runs the chunk owes and has not recorded; None where it owes none.
The chunk owes the runs `plan_reasons` calls, two where it empties a release, else one. It has recorded the scoring runs its committed history holds beyond those at the merge base, so a default branch that has moved on since the branch began doesn't count. A project with no plan owes none. Neither does one whose plan or history is outside the checkout: it says on stderr that it cannot tell. A missing run blocks the merge and a low score never does, which keeps the decision `review: the comprehension check records …`: it bars only scores from blocking.
The chunk owes the runs `plan_reasons` calls, two where it empties a release, else one. It has recorded the scoring runs its committed history holds beyond those at the merge base, so a default branch that has moved on since the branch began doesn't count. A project with no plan owes none. Neither does one whose plan or history is outside the checkout: it warns that it cannot tell. A missing run blocks the merge and a low score never does, which keeps the decision `review: the comprehension check records …`: it bars only scores from blocking.
"""
config = located(None, home)
if isinstance(config, Failure):
+1 -1
View File
@@ -67,7 +67,7 @@ def unanswered_round(titles: list[str], pass_: str) -> int | Failure:
def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -> str | Failure:
"""Writes the branch diff and the places into the review folder, and prints the header that launches pass_'s reviewer in the pass's unanswered round, or its relaunch one rung up where rerun."""
"""Writes the branch diff and the places into the review folder, and returns the header that launches pass_'s reviewer in the pass's unanswered round, or its relaunch one rung up where rerun."""
titles = branch_titles(default)
if isinstance(titles, Failure):
return titles
+1 -1
View File
@@ -1,4 +1,4 @@
"""What counts as a quote, for every check of a passage the judge or the worker quotes: of the transcript, the premises, the records or a human's line."""
"""What counts as a quote: whether a text holds a passage the judge quotes from the transcript, the premises, the records or a human's line."""
def verbatim(quote: str, text: str) -> bool:
+2 -2
View File
@@ -9,13 +9,13 @@ The worker, and the session /talk opens, run on a Route (model_routing/route.py)
A step-up weighs five rungs:
- the project's rung: the cheapest rung of the project's model, from which every L counts;
- the project's rung: the cheapest rung of the project's model, which each L counts up from;
- item_rung: the rung the chunk started on, which the routed item's L picked;
- the route's rung: where the worker runs now, at or above item_rung;
- floor_rung: the lowest rung the worker may run on next, which is the route's rung, raised where an item the worker took in has an L that picks a higher one;
- escalation_cap: ESCALATION_CAP rungs above item_rung, the highest an escalation reaches without the human's yes.
Each verdict then moves the rung by one rule, and the rung never falls. It changes this seldom because a model switch inside a session discards its prompt cache.
Each verdict then moves the rung by one rule, and the rung never falls. The rung changes seldom, since a model switch inside a session discards that session's prompt cache.
| Verdict | The rung goes to | Count of unfinished verdicts | Escalation mark |
|---|---|---|---|
+1 -1
View File
@@ -56,7 +56,7 @@ class Route:
escalated_at: int = 0
def __post_init__(self) -> None:
# Raises on a programming error only, so nothing catches it: a caller builds a route only from levels it checked with fits, or took from an item todo_table.items read, which holds none off its scale.
# Raises on a programming error only, so nothing catches it: a caller builds a route from levels it checked with fits, or from an item todo_table.items read, whose levels are all on their scales.
if not levels_fit(self.item, self.likelihood, self.escape_and_impact, self.escape_and_impact_taken_in):
raise ValueError(f"a route by item {self.item} cannot hold an L of {self.likelihood}, an E + I of {self.escape_and_impact} and an E + I taken in of {self.escape_and_impact_taken_in}")
+1 -3
View File
@@ -1,5 +1,3 @@
"""Holds todo.md and docs/decisions.md to each other: every item a decision cites is in the plan and exempt from the bar, and every item marked decision is cited."""
import re
from failure import Failure
@@ -7,7 +5,7 @@ from release_plan.todo_table import Item
def check_citations(items: list[Item], decisions: str) -> Failure | None:
"""Holds todo.md and docs/decisions.md to each other: a cited item is exempt, a decision row is cited."""
"""Holds todo.md and docs/decisions.md to each other: every item a decision cites is in the plan and exempt from the bar, and every item marked decision is cited."""
cited = set(cited_items(decisions))
if gone := sorted(cited - {item.id for item in items}):
return Failure(f"docs/decisions.md cites \"`todo.md` item {gone[0]}\", which todo.md no longer holds; revise that decision to say what holds now")
+1 -1
View File
@@ -1,4 +1,4 @@
"""The goals file, read once for everyone: its ## Goals and ## Audience sections, the goals ## Goals numbers and marks, and what each goal weighs."""
"""Reads the goals file, for the ranking and for loop-claude's premises: its ## Goals and ## Audience sections, each goal's number and mark, and what each goal weighs."""
import decimal
import re
+1 -1
View File
@@ -1,4 +1,4 @@
"""todo.md on disk: read it with the files ranking reads, at the paths the project's config names, then rank or check it, write it back, and print what ranking reports."""
"""todo.md on disk: read it with the files ranking reads, at the paths the project's config names, then rank or check it, write it back, and give the lines ranking reports."""
import pathlib
from failure import Failure
+1 -1
View File
@@ -1,4 +1,4 @@
"""Rank todo.md's items by the formula it states, weighing the goals as goals_file.py weighs them, and hold them to its bar; rank_todo.py --help states the rules.
"""Rank todo.md's items by the formula it states, with the goal weights goals_file.py gives, and hold them to its bar; rank_todo.py --help states the rules.
"""
import ast
import dataclasses
+1 -1
View File
@@ -89,7 +89,7 @@ def write_cited(moves: Moves) -> str:
# L, E and I are optional, since score_outcomes reads, out of git history, tables from before they replaced C; R too, since rank_todo.py writes it from them.
SHAPE = Shape(("L", "E", "I", "R", "S"), (BLOCKED_BY, "L", "E", "I", "R", "Score"), ("L", "E", "I"), ("R",), MOVES, parse_moves, write_moves)
# The shape from before MOVES replaced A, G and Goals, and L, E and I replaced C, which older todo.md files hold; one from before C joined lacks it.
# It is live, not dead: rank_todo.py still ranks such a table, so no other project's commits stop before it reshapes, until `todo.md` item 156 drops that ranking once no project holds one. score_outcomes keeps reading old tables out of git history after that.
# Live: rank_todo.py ranks a table in this shape, so a project that has not reshaped yet can still commit. `todo.md` item 156 drops that ranking once no project holds such a table; score_outcomes goes on reading old tables out of git history.
OLD_SHAPE = Shape(("R", "S", "C", "A", "G"), (BLOCKED_BY, "C", "Score"), (), (), "Goals", parse_cited, write_cited)
+1 -1
View File
@@ -9,7 +9,7 @@ CAP = 2
# The release review's passes take more, since they may refactor much: `skills/larv-review/SKILL.md` → "Release review".
RELEASE_REVIEW_CAP = 5
CAPS = {"architecture": RELEASE_REVIEW_CAP, "principles": RELEASE_REVIEW_CAP}
# How a round title is spelled, for every text that states it; ROUND and FINDINGS below read it.
# A round title's spelling, for rule-hook's rule texts. ROUND and FINDINGS below parse a title spelled so.
OPENING = "Answer <pass> round <n>:"
COUNTS = "<k> 🔴, <m> 🟡 (<j> misread);"
EXAMPLE = "Answer stability round 1: 1 🔴, 2 🟡 (1 misread); flag a deleted test"
+4 -4
View File
@@ -78,7 +78,7 @@
| 187 | 0.14.0 | | | **Count the tokens a worker spends reading reviewers' reports, so goal 1.4's signal shows whether report files lowered what a review costs the worker's context.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 3 | 1.0 |
| 266 | 0.14.0 | | | **Move the chunks archived under the key `home/lilleman/.claude` to the key `claude-config`, so the routing figures and `score-outcomes` count this repo's chunks as one project.** | 3 | 2 | 2 | 5 | 3 | 1.4 by 3 | 1.0 |
| 181 | 0.14.0 | | principle | **Have the test of a quoted answer's step-up assert the stepped rung's facts as literals, not through `prompts.rungs_held`.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 2 | 0.9 |
| 193 | 0.14.0 | | | **Narrow `readme_goals`'s mark to `Mark` by a typed lookup in place of `typing.cast`, so a mark added to the regex but not the lookup fails at run time, and one added to the lookup but not `Mark` fails mypy.** | 1 | 1 | 3 | 3 | 1 | 1.1 by 2 | 0.9 |
| 193 | 0.14.0 | | | **Narrow `numbered`'s mark to `Mark` by a typed lookup in place of `typing.cast`, so a mark added to the regex but not the lookup fails at run time, and one added to the lookup but not `Mark` fails mypy.** | 1 | 1 | 3 | 3 | 1 | 1.1 by 2 | 0.9 |
| 194 | 0.14.0 | | | **Make `test_waits_out_a_usage_limit_which_ends_a_run_of_failures` expect a usage-limit wait independent of the wall-clock time that passes during the run.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 2 | 0.9 |
| 265 | 0.14.0 | | | **Archive each wait that costs a chunk wall time, for a usage limit, low memory, a failed worker start or a heavy slot, with its start and end stamps, so goal 1.5's hours split waiting from work.** | 3 | 2 | 2 | 5 | 4 | 1.5 by 3 | 0.8 |
| 169 | 0.14.0 | | | **Have rule-hook's `todo-rank-check` catch a `todo.md` that the same Bash call edits and then commits.** | 3 | 1 | 3 | 5 | 3 | 1.1 by 2 | 0.7 |
@@ -358,12 +358,12 @@ Places the seats named, hardest first (`larv-review places`):
- Locality, Self-sufficiency: `bin/loop_claude/routing.py:93` `unfinished_route`, with `escalated_route`: the floor, the cap counted from `item_rung`, the escalation mark, the unfinished count and the E + I taken in are held at once across four files, and why they combine sits in the decision log. Every seat named it; three would least want to change it.
- Shape, Self-sufficiency: `bin/release_plan/release_standing.py:168` `next_release`, with `standing`: `str | None | Failure` fields in `LastCut`, the `BEFORE_FIRST_RELEASE` sentinel and `nothing_cut` meet in the `is_earliest` test, read as truth tables; four tools choose the next release through it.
- Locality: `bin/loop_claude/cycle/run.py:154` `rule`, with `:67` `run_cycle` and `:94` `archived`: archives twice in an order that matters and that nothing enforces, the archive helpers sit in the cycle runner though `loop/close.py` imports them, and `run_cycle` replaces `cycle.route` outside the state machine.
- Shape: `bin/release_plan/ranking.py:56` `rank`, `:160` `weigh`, `:304` `score` and `:315` `weight_of`: every function forks on `SHAPE` versus `OLD_SHAPE`, and the constants' reasons are only "docs/decisions.md records the choice".
- Shape: `bin/release_plan/ranking.py:47` `rank`, `:134` `weigh`, `:229` `score` and `:240` `weight_of`: every function forks on `SHAPE` versus `OLD_SHAPE`, and the constants' reasons are only "docs/decisions.md records the choice".
- Shape: `bin/rule_hook/todo_check.py:22` `todo_breaches`, with `:42` `folder_breaches`: three paths, `held()` beside `located()`, the checkout's own script only under `same_repo`, and a blob hashed by hand.
- Locality, Self-sufficiency: `bin/larv_review/plan.py:66` `plan_reasons` and `bin/larv_review/owed.py:46` `shortfall`: the rule for when a scoring run is due is split between the 155-line help and the code, and the number owed hangs on the wording `EMPTIED_WORDS`.
- Self-sufficiency: `bin/loop_claude/cycle/judge.py:21` `INTERRUPT_RULES`, with `:196` `quotes_checked`: behaviour held in prompt text and schema descriptions the code can't explain, and prompts that quote `CLAUDE.md` wording.
- Self-sufficiency: `skills/larv-review/SKILL.md:82` "Round cap": dense rules that point at `CLAUDE.md`, `review-findings.md` and the rules files, read three times before the code matched.
- Self-sufficiency: `bin/rule_hook/round_cap.py:26` `earlier_titles`: fails open on the unattended path where git cannot list the branch's titles, and the cap's wording is spelt in SKILL.md, `rules.py:61` and `round_titles.py`.
- Self-sufficiency: `bin/rule_hook/round_cap.py:26` `earlier_titles`: fails open on the unattended path where git cannot list the branch's titles, and the round title is spelt by hand in SKILL.md, `larv_review/main.py` and `reviewer_header.py` beside `round_titles.py`.
- Locality, Shape: `bin/chunk_preflight/choices.py:80` `forge_of`: forge identity and forge calls live in two tool packages, so a second forge lands in three.
- Navigation, Shape: `README.md:131` `bin/`: about 63 entries at one level, the shared libraries told apart only by README prose.
- Shape: `bin/loop_claude/loop/reload.py:220` `decoded_route`: one dense guard, and renaming a `LoopRun` field stops a running loop.
@@ -483,7 +483,7 @@ The archive holds 277 chunk folders under `home/lilleman/.claude`, from 2026-09-
`bin/loop_claude/test_loop_claude.py`'s `test_a_quoted_answer_that_cites_an_escalation_trigger_steps_the_worker_up_before_it_resumes_and_archives_the_step` builds its expected prompt from `prompts.rungs_held`, the code under test, so a bug there passes it. The technical principles' test bullet bans that shape. Assert the new rung and one review launch as literals, as the typed answer's step-up test does. Raised by the principles audit of PR #308.
### 193. Narrow `readme_goals`'s mark to `Mark` by a typed lookup in place of `typing.cast`, so a mark added to the regex but not the lookup fails at run time, and one added to the lookup but not `Mark` fails mypy.
### 193. Narrow `numbered`'s mark to `Mark` by a typed lookup in place of `typing.cast`, so a mark added to the regex but not the lookup fails at run time, and one added to the lookup but not `Mark` fails mypy.
Found by review of PR #317. `bin/release_plan/goals_file.py`'s `numbered` writes `typing.cast(Mark, mark or None)`, which asserts the type `goal_weights` branches on without checking it: a mark added to the regex reaches `goal_weights` as a value `Mark` lacks. mypy does not read the regex, so no lookup lets it catch that. Replace the cast with a lookup typed `dict[str, Mark]`, from each mark the regex captures, and `""` for none, to its `Mark` value. A mark added to the regex but not the lookup then raises `KeyError` at run time, and a value added to the lookup but not `Mark` fails mypy.