Answer prose round 1: 0 🔴, 9 🟡 (0 misread); docstrings say what the code does, and each fact sits in one place

This commit is contained in:
2026-11-10 22:32:49 +01:00
parent f2fef1d32d
commit 998e295ef9
17 changed files with 19 additions and 22 deletions
+1 -1
View File
@@ -122,7 +122,7 @@ Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by t
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
- `judge_replay` imports `loop_claude`'s judge, verdicts, premises and records.
- `loop_claude` runs `chunk-preflight` as a process of its own.
- `loop_effects/` holds `Effects`, each process, terminal, clock and git call a tool makes, injected so its tests can script them. loop-claude, loop-inbox, both replay tools and `reviewer-merge-trials`' driver use it.
- `loop_effects/` holds `Effects`: the processes, terminal, clock and git a tool reaches, injected so its tests can script them. loop-claude, loop-inbox, both replay tools and `reviewer-merge-trials`' driver use it.
- `loop_state/` holds the files loop-claude and loop-inbox share: the question files (`waiting/`), the files a running loop lists itself in (`running_loops.py`, `session_lock.py`), their paths, and `hand_over.py`, which opens claude for `/talk`. A change to any of them changes both tools.
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for.
- `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read.
+1 -1
View File
@@ -1,4 +1,4 @@
"""loop-claude: headless claude cycles, judged, that interrupt the human only for a decision that is theirs (loop/usage.py's help).
Its packages hold one concern each: cycle/ runs a cycle, loop/ runs the cycles, and project/ reads a checkout's files. The files it shares with loop-inbox live in bin/loop_state/, and its effects in bin/loop_effects/. Each module at this level is imported by more than one package. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
Its packages hold one concern each: cycle/ runs a cycle, loop/ runs the cycles, and project/ reads a checkout's files. The files it shares with loop-inbox live in bin/loop_state/, and its effects in bin/loop_effects/. Each module at this level is imported by more than one package, or by a module at this level that is. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
"""
+1 -1
View File
@@ -75,7 +75,7 @@ def planning_launch(route: Route, project: Rung) -> list[str]:
def markdown_launch(choice: ReviewChoice) -> list[str]:
"""Where a branch changing only Markdown no agent follows reviews on another rung than the reviewers', the sentence naming that rung, choice.markdown_only, which rule-hook's reviewer-rung holds a launch to too. On an Opus 5.5 project it ends: `launch each reviewer on the project's rung instead, with the Agent tool set to model opus, effort medium.`"""
"""The sentence that names choice.markdown_only, the rung a reviewer runs on where the branch changes only Markdown no agent follows. It is empty where that rung is the reviewers'. rule-hook's reviewer-rung holds a launch to the same rung. On an Opus 5.5 project it ends: `launch each reviewer on the project's rung instead, with the Agent tool set to model opus, effort medium.`"""
if choice.markdown_only == choice.reviewers:
return []
files = ", ".join(f"`{name}`" for name in INSTRUCTION_FILES)
+1 -1
View File
@@ -44,7 +44,7 @@ def routed(route: Route | None, project: Rung | None, model: str, archived: typi
def archived_route(archive_folder: pathlib.Path, loop: Loop) -> Route | None:
"""The route the latest verdict archived for the loop's open chunk names; None for a chunk not yet judged."""
"""The route named by the latest verdict archived for the loop's open chunk; None for a chunk not yet judged."""
transcript = transcript_file(loop.session)
worker = latest_worker(archive_folder, transcript) if transcript else None
if isinstance(worker, Failure):
+1 -1
View File
@@ -68,7 +68,7 @@ def decoded_ids(value: object) -> tuple[int, ...]:
def decoded_route(value: object) -> Route | None:
"""The Route the JSON holds; None for null. dataclasses.asdict wrote it: a worker line's fields, but with the rung nested and the unfinished count beside them, so route_of decodes it once flattened."""
"""The Route the JSON holds; None for null. dataclasses.asdict wrote it as a worker line's fields, with the rung nested and the unfinished count added. route_of reads it once the rung's model and effort are lifted to the top and the count is set aside."""
if value is None:
return None
if not isinstance(value, dict) or not isinstance(value.get("rung"), dict) or not value["rung"].keys() <= {"model", "effort"} or value.keys() & {"model", "effort"}:
+1 -1
View File
@@ -10,7 +10,7 @@ from claude_code.session import Session
@dataclasses.dataclass(frozen=True)
class Loop:
"""One run of loop-claude, as it stays from its first cycle to its last; run_loop builds it once."""
"""What stays the same through one run of loop-claude; run_loop builds it once per process, so a reload builds it afresh."""
# The checkout the loop runs in. LoopRun.root names it too, since a reload hands it on there.
root: str
# The worker's session, under whose id loop-inbox lists the loop and its questions.
+2 -2
View File
@@ -93,7 +93,7 @@ def next_route(project: Rung | None, route: Route, verdict: Unfinished | Interru
def unfinished_route(project: Rung, route: Route, verdict: Unfinished) -> Route:
"""The route after an unfinished verdict. The rung rises to floor_rung, which the verdict's highest L taken in may raise.
The verdict counts towards UNFINISHED_PER_STEP. Where steps holds, the rung steps once from the floor, and the mark moves only where the verdict escalates. Last, the route takes in the verdict's highest E + I, as Route.taking_in does.
The verdict counts towards UNFINISHED_PER_STEP. Where steps says so, the rung steps once from the floor, and the mark moves only where the verdict escalates. Last, the route takes in the verdict's highest E + I, as Route.taking_in does.
"""
mark = escalation_mark.moved_to(verdict)
floor = floor_rung(project, route, verdict.taken_in.highest_likelihood)
@@ -108,7 +108,7 @@ def unfinished_route(project: Rung, route: Route, verdict: Unfinished) -> Route:
def escalated_route(project: Rung, route: Route, verdict: Interrupt | QuotedAnswer) -> Route:
"""The route after an interrupt or a quoted answer. Without an escalation it holds, since neither is an unfinished verdict.
With one, the rung rises to floor_rung, which the verdict's highest L taken in may raise. It steps one rung up from there while below escalation_cap, and the mark moves, as loop_claude/escalation_mark.py says.
With one, the rung rises to floor_rung, which the verdict's highest L taken in may raise. Where floor_rung lies below escalation_cap, the rung steps one up from it and the mark moves, as loop_claude/escalation_mark.py says; at the cap the rung stays on floor_rung and the mark holds.
"""
mark = escalation_mark.moved_to(verdict)
if mark is None:
-1
View File
@@ -1 +0,0 @@
"""The shell seam several tools share: effects.py's Effects, each process, terminal, clock and git call a tool makes, injected so its tests can script them."""
+1 -1
View File
@@ -1,6 +1,6 @@
"""The effects a tool reaches the world through, such as its terminal, clock, processes, git and the machine's memory.
loop-claude, loop-inbox, judge-replay, review-replay and reviewer-merge-trials/driver.py all run on them, so a change here, such as to how input reads a line, changes each of them.
A change here, such as to how input reads a line, changes every tool that runs on them.
"""
import dataclasses
import os
+1 -1
View File
@@ -1,4 +1,4 @@
"""Opens claude on the terminal for the human. It sits outside cycle/, since loop-inbox's /talk and the loop's routing calls open claude too."""
"""Opens claude on the terminal for the human."""
import dataclasses
from loop_effects.effects import Effects
+1 -1
View File
@@ -103,7 +103,7 @@ def review_rung(project: Rung, worker: Rung, escape_and_impact: int, kind: Revie
def reviewers_rung(project: Rung, worker: Rung, escape_and_impact: int, markdown_only: bool = False) -> Rung:
"""The rung of each pass's reviewer: the higher of the worker's rung and review_floor's, which is never below the project's.
Where markdown_only, the branch changes only Markdown no agent follows, and holds no code or config for a reviewer on a higher rung to catch a defect in, so the reviewer runs on the project's rung: skills/larv-review/SKILL.md → "Markdown only".
markdown_only means the branch changes only Markdown no agent follows. Such a branch holds no code or config for a higher rung to catch a defect in, so its reviewer runs on the project's rung: skills/larv-review/SKILL.md → "Markdown only".
"""
return project if markdown_only else highest(worker, review_floor(project, escape_and_impact))
+3 -3
View File
@@ -1,4 +1,4 @@
"""The order blockers impose on the ranked items: each blocker above every item it blocks, and no blocker in a later release or in a loop."""
"""The order blockers impose on the ranked items: each blocker above every item it blocks, no blocker in a later release than an item it blocks, and no blockers in a loop."""
import dataclasses
import graphlib
@@ -8,7 +8,7 @@ from release_plan.release import version
def blockers_first(scored: list[tuple[Item, float]]) -> list[tuple[Item, float]] | Failure:
"""scored, each blocker that ranks below an item it blocks moved up to just above the first such item; a blocker the table no longer holds was finished or deleted, and is dropped."""
"""scored, each blocker that ranks below an item it blocks moved up to just above the first such item; a blocker the table no longer holds was finished or deleted, and is dropped from the Blocked by cells."""
held = {item.id: (item, value) for item, value in scored}
position = {item.id: index for index, (item, _) in enumerate(scored)}
for item, _ in scored:
@@ -33,7 +33,7 @@ def blocking_loop(held: dict[int, tuple[Item, float]]) -> list[int] | None:
def place(id_: int, held: dict[int, tuple[Item, float]], position: dict[int, int], placed: set[int]) -> list[tuple[Item, float]]:
"""The item id_, unless placed holds it, preceded by those of its blockers placed doesn't hold yet, each in score order, and theirs before them. Each item it returns joins placed. blocking_loop has ruled out a loop."""
"""id_'s item, preceded by each of its blockers not yet in placed, in score order, each of them preceded in turn by its own blockers; empty where placed already holds id_. Each item returned joins placed. blocking_loop has ruled out a loop, so the recursion ends."""
if id_ in placed:
return []
placed.add(id_)
+1 -1
View File
@@ -53,11 +53,11 @@ def evaluate(node: ast.AST, values: dict[str, float]) -> float:
divisor = evaluate(right, values)
return evaluate(left, values) / divisor if divisor else math.nan
case ast.BinOp(left, ast.Pow(), right):
# math.pow raises on a negative base with a fractional exponent, zero to a negative power, and overflow; one catch covers all three.
base, exponent = evaluate(left, values), evaluate(right, values)
# A nan from a zero divisor stays nan, though math.pow(1, nan) and math.pow(nan, 0) give 1.
if math.isnan(base) or math.isnan(exponent):
return math.nan
# math.pow raises on a negative base with a fractional exponent, zero to a negative power, and overflow; one catch covers all three.
try:
return math.pow(base, exponent)
except (OverflowError, ValueError):
+2 -2
View File
@@ -1,4 +1,4 @@
"""todo.md on disk: read it with the files beside it that ranking reads, rank it, write it back, and print what ranking reports."""
"""todo.md on disk: read it with the project files ranking reads, then rank or check it, write it back, and print what ranking reports."""
import pathlib
import sys
@@ -41,7 +41,7 @@ def check_failures(todo: pathlib.Path) -> list[str]:
def read_all(todo: pathlib.Path) -> tuple[str, str, str, str] | Failure:
"""todo.md, the README.md beside it, and its docs/decisions.md and docs/comprehension-history.md, each empty when there is none."""
"""todo.md, the README.md beside it, and its docs/decisions.md and docs/comprehension-history.md. The last two are empty when missing; a missing todo.md or README.md is a Failure."""
texts = []
for path, missing in ((todo, "every project keeps a todo.md beside its README.md, and rank_todo.py --help shows one"), (todo.parent / "README.md", "rank_todo.py weighs goals from the README.md beside todo.md"), (todo.parent / "docs" / "decisions.md", None), (todo.parent / HISTORY, None)):
try:
-2
View File
@@ -1,6 +1,4 @@
"""Rank todo.md's items by the formula it states, weighing code health first and then README.md's achieve goals by their position, and hold them to its bar; rank_todo.py --help states the rules.
formula.py holds the formula's language, blockers.py the order blockers impose, and plan_file.py reads and writes todo.md on disk.
"""
import ast
import dataclasses
+1 -1
View File
@@ -39,7 +39,7 @@ def in_bin(module: str) -> bool:
class TrialsImports(unittest.TestCase):
"""docs/decisions.md says to rerun the trials' scripts when a new model joins the ladder or a reviewer changes, so a refactor of bin/ must not break what they import."""
"""docs/decisions.md says to rerun the trials' scripts when a new model joins the ladder or a reviewer's definition changes, so a refactor of bin/ must not break what they import."""
def test_each_name_a_trials_script_imports_from_bin_exists(self):
scripts = sorted(TRIALS.glob("*.py"))
+1 -1
View File
@@ -172,7 +172,7 @@ Each match and new-finding count costs about $0.30 on Opus 5.5 at medium.
## How to rerun
Run every script from this folder, on the host's Python. They import review-replay from this checkout's `bin/`, and `bin/repo_checks/test_trials_imports.py` checks that every name they import from it still exists; the trials ran against commit 82eb8ff, and candidate 4 against 0442074, where review-replay was unchanged.
Run every script from this folder, on the host's Python. They import from this checkout's `bin/`, and `bin/repo_checks/test_trials_imports.py` checks that every name they import from it still exists. The trials ran against commit 82eb8ff, and candidate 4 against 0442074, where review-replay was unchanged.
The scripts name the candidates `wave3` (candidate 1), `release` (candidate 2) and `pair` (candidate 4).
To replay on another model, change two places: `collect.py` keeps only projects on `claude-opus-5-5`, and `driver.py`'s `RUNG` is Opus 5.5 at medium.