Answer architecture round 1: 0 🔴, 4 🟡 (0 misread); move the shared loop state out of loop_claude, split ranking and routing, give the reviewer rung one rule
CI / tests (pull_request) Successful in 2m14s

This commit is contained in:
2026-11-10 22:03:16 +01:00
parent 8a80d452f2
commit 70a1b95086
70 changed files with 748 additions and 625 deletions
+5
View File
@@ -53,9 +53,14 @@
!bin/loop_claude/
!bin/loop_claude/**/
!bin/loop_claude/**/*.py
!bin/loop_effects/
!bin/loop_effects/*.py
!bin/loop-inbox
!bin/loop_inbox/
!bin/loop_inbox/*.py
!bin/loop_state/
!bin/loop_state/**/
!bin/loop_state/**/*.py
!bin/machine_load/
!bin/machine_load/*.py
!bin/metric-bench
+6 -5
View File
@@ -113,25 +113,26 @@ Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by t
- `subagent-rung [--plan] <model> <L>` prints the Agent tool's model and effort for a subagent's task, picked by its L from the project's model, and with `--plan` never below the project's rung; `subagent-rung --help` states the rule.
- `todo-item add …` files an item in a project's `todo.md`, taking `Next ID` as the item's ID, and `todo-item finish <ID>` removes a finished item and adds the bullet passed with `--changelog` to `CHANGELOG.md`; both rank the file, and `todo-item --help` states the flags.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py` and `failure.py`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `branch_chunks/`, `claude_code/`, `command_lines/`, `git_cli/`, `machine_load/`, `model_routing/`, `records/`, `release_plan/`, `review_rules/`, `rung_replay/` and `transcript_archive/` serve more than one tool.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py` and `failure.py`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `branch_chunks/`, `claude_code/`, `command_lines/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `model_routing/`, `records/`, `release_plan/`, `review_rules/`, `rung_replay/` and `transcript_archive/` serve more than one tool.
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
- `chunk_pr` imports `deploy_release`'s forge calls, and `forge_of` as `deploy_release` does.
- `deploy_release` imports `chunk_preflight`'s `forge_of`, which tells a GitHub origin from a Gitea one, and `release_plan`'s `release_standing`.
- `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.
- `judge_replay` imports `loop_claude`'s judge, verdicts, premises and records.
- `loop_claude` runs `chunk-preflight` as a process of its own.
- `loop_inbox` imports `loop_claude`'s question files (`waiting/`), the files a running loop lists itself in (`running_loops.py`, `session_lock.py`), its effects and paths, and `hand_over.py`, which opens claude for `/talk`. A change to any of them changes loop-inbox too.
- `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_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.
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
- `records/` 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`, which `larv_review`, `rank_todo.py`, `rule_hook` and `todo_item` import).
- `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`). `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 rung search, the argument reader, the candidate rungs and the exits. It reads `loop_claude`'s retry count and models file.
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the rung search, the argument reader, the candidate rungs and the exits. 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.
- `transcript_archive/` stores loop-claude's transcripts. Its `project_key.py` names each project's archive folder, loop-claude session and models-file entry.
+5 -5
View File
@@ -1,10 +1,10 @@
from branch_chunks.fixes import blamed, fixing_changes, FixingChange, removed_work, Traced, with_fixes
from branch_chunks.cut import BranchChunk, cut_branch, LOG, plan_revisions, shipped_by
from failure import Failure
from git_cli.git_repo import Run, text_at
from git_cli.git_repo import Git, text_at
def branch_chunks(default: str, run: Run) -> list[BranchChunk] | Failure:
def branch_chunks(default: str, run: Git) -> list[BranchChunk] | Failure:
"""Each chunk on the default branch's first-parent line, newest first, with the todo.md items it shipped and the later chunks that fixed code it shipped.
run must run git in the checkout's top: the diff names each path from the top, while blame and a pathspec read a path from the current directory."""
@@ -23,7 +23,7 @@ def branch_chunks(default: str, run: Run) -> list[BranchChunk] | Failure:
return traced if isinstance(traced, Failure) else with_fixes(branch, shipped, traced)
def plans_at(revisions: list[str], run: Run) -> dict[str, str] | Failure:
def plans_at(revisions: list[str], run: Git) -> dict[str, str] | Failure:
"""todo.md's text at each revision, empty where the revision holds none."""
plans = {}
for revision in revisions:
@@ -34,7 +34,7 @@ def plans_at(revisions: list[str], run: Run) -> dict[str, str] | Failure:
return plans
def traces(changes: list[FixingChange], run: Run) -> list[Traced] | Failure:
def traces(changes: list[FixingChange], run: Git) -> list[Traced] | Failure:
"""The commits traced_to traces for each change."""
found = []
for change in changes:
@@ -45,7 +45,7 @@ def traces(changes: list[FixingChange], run: Run) -> list[Traced] | Failure:
return found
def traced_to(before: str, tip: str, run: Run) -> set[str] | Failure:
def traced_to(before: str, tip: str, run: Git) -> set[str] | Failure:
"""The commits that last changed each line of a chunk's work that the change from before to tip removes or rewrites."""
# The prefixes and options keep the checkout's diff config out of the output. Only hunk headers, paths and commits are read, so a file's text that is not UTF-8 is replaced.
diff = run("diff", "-U0", "--inter-hunk-context=0", "-M", "--no-color", "--no-ext-diff", "--no-textconv", "--ignore-submodules", "--src-prefix=a/", "--dst-prefix=b/", before, tip, errors="replace")
+9 -12
View File
@@ -46,14 +46,11 @@ def git(*args: str, cwd: str | None = None, timeout: float | None = None, guarde
class Git(typing.Protocol):
"""Runs git as `git` does."""
"""Runs git as `git` does: git itself, Effects.git, or a functools.partial of either that binds the checkout."""
def __call__(self, *args: str, cwd: str | None = None, timeout: float | None = None, guarded: bool = False, errors: str = "strict") -> str | Failure: ...
# Runs git with the given arguments, in the checkout and with the options its caller bound, as functools.partial(git, cwd=...) does.
Run = typing.Callable[..., str | Failure]
def top() -> str | Failure:
found = git("rev-parse", "--show-toplevel")
@@ -109,24 +106,24 @@ def origin_head(cwd: str | None, timeout: float | None, run: Git) -> str | Failu
return Failure("origin names no default branch; set it with `git remote set-head origin --auto`")
def commits_since(tag: str | None, branch: str, cwd: str | None = None) -> int | Failure:
def commits_since(tag: str | None, branch: str, cwd: str | None = None, run: Git = git) -> int | Failure:
"""How many commits branch holds after tag, or holds in all where tag is None; read in cwd, else in the current directory."""
count = git("rev-list", "--count", f"{tag}..{branch}" if tag else branch, cwd=cwd)
count = run("rev-list", "--count", f"{tag}..{branch}" if tag else branch, cwd=cwd)
return count if isinstance(count, Failure) else int(count)
def commit_exists(commit: str, cwd: str | None = None) -> bool:
return not isinstance(git("rev-parse", "--quiet", "--verify", f"{commit}^{{commit}}", cwd=cwd), Failure)
def commit_exists(commit: str, cwd: str | None = None, run: Git = git) -> bool:
return not isinstance(run("rev-parse", "--quiet", "--verify", f"{commit}^{{commit}}", cwd=cwd), Failure)
def file_at(revision: str, path: str, cwd: str | None = None) -> str | Failure:
def file_at(revision: str, path: str, cwd: str | None = None, run: Git = git) -> str | Failure:
"""A file's text at a revision, read in cwd, else in the current directory; empty where the revision is not a commit, such as a root commit's parent, or holds no such file."""
if not commit_exists(revision, cwd):
if not commit_exists(revision, cwd, run):
return ""
return text_at(revision, path, functools.partial(git, cwd=cwd))
return text_at(revision, path, functools.partial(run, cwd=cwd))
def text_at(revision: str, path: str, run: Run) -> str | Failure:
def text_at(revision: str, path: str, run: Git) -> str | Failure:
"""A file's text at a commit, as run reads it; empty where the commit holds no such file. ls-tree reads path from the directory run runs in, and show from the checkout's top."""
listed = run("ls-tree", "--name-only", revision, "--", path)
if isinstance(listed, Failure):
+1 -1
View File
@@ -6,6 +6,6 @@ import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from judge_replay import main
from loop_claude.effects import system_effects
from loop_effects.effects import system_effects
sys.exit(main.main(sys.argv[1:], os.environ, pathlib.Path.home(), system_effects()))
+1 -1
View File
@@ -32,7 +32,7 @@ from rung_replay.command import arguments_or_exit, down_from, failed, limited_ex
from loop_claude.cycle.judge import Brief, judge_once
from judge_replay.replay import Case, case_from, Kind, report, reproduced, sample, verdict_kind
from transcript_archive.project_key import checkout_of
from loop_claude.effects import Effects
from loop_effects.effects import Effects
from failure import Failure
from rung_replay.search import first_reply, replayed
from claude_code.reply import Limited
+1 -1
View File
@@ -11,7 +11,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from transcript_archive.outcomes import ANSWERED, FINISHED, INTERRUPTED, UNFINISHED
from judge_replay.replay import Case, case_from, report, reproduced, sample, verdict_kind
from loop_claude.effects import Effects
from loop_effects.effects import Effects
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from judge_replay import main
+2 -2
View File
@@ -10,7 +10,7 @@ from larv_review.ruling import counted, overall, ruling, split, surplus, votes
from failure import Failure
from larv_review.seats import FIRST_SEATS, scores, seats_file, SeatsFile
from larv_review.scoring import floor_step, means, under_floor
from release_plan import ranking
from release_plan import plan_file
from records.file_writes import replace_file
@@ -70,7 +70,7 @@ def rerank() -> Failure | None:
if isinstance(checkout, Failure):
return checkout
todo = pathlib.Path(checkout, "todo.md")
ranked = ranking.rank_file(todo)
ranked = plan_file.rank_file(todo)
if isinstance(ranked, Failure):
return Failure(f"recorded the run, but rank_todo.py cannot rank {todo}: {ranked.reason}. Fix what that names, then run rank_todo.py on {todo}, not record-scoring again")
if ranked.under_bar:
+2 -1
View File
@@ -6,7 +6,8 @@ import sys
LAUNCHER = pathlib.Path(__file__).resolve()
sys.path.insert(0, str(LAUNCHER.parent))
from loop_claude import effects, paths
from loop_effects import effects
from loop_claude.loop import main
from loop_state import paths
sys.exit(main.main(sys.argv[1:], os.environ, paths.paths_from(pathlib.Path.home()), LAUNCHER, pathlib.Path.cwd(), effects.system_effects()))
+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, project/ reads a checkout's files, and waiting/ shows a question to loop-inbox. Each module at this level is imported by more than one package, and loop-inbox imports several. 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. 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.
"""
+6 -6
View File
@@ -4,14 +4,14 @@ import sys
import typing
import uuid
from loop_claude.waiting.answers import Answer, answered, claude_ended, ClaudeOpening, Typed
from loop_claude.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal
from loop_claude.hand_over import claude_args, ClaudeCommand, hand_over
from loop_claude.effects import Effects, POLL_SECONDS, say
from loop_state.waiting.answers import Answer, answered, claude_ended, ClaudeOpening, Typed
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal
from loop_state.hand_over import claude_args, ClaudeCommand, hand_over
from loop_effects.effects import Effects, POLL_SECONDS, say
from failure import Failure
from claude_code.transcript import human_turns, read_transcript
from loop_claude.waiting.listing import listed, shown
from loop_claude.waiting.talk import make_way, TALK
from loop_state.waiting.listing import listed, shown
from loop_state.waiting.talk import make_way, TALK
from loop_claude.stop import needs_human, needs_terminal, Stop
from model_routing.ladder import Rung
+1 -1
View File
@@ -5,7 +5,7 @@ import typing
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS, ANSWERS_RECORDED, typed_answer
from claude_code.reply import claude_reply, Limited
from loop_claude.effects import Effects
from loop_effects.effects import Effects
from claude_code.entries import Entry, structured_output
from loop_claude import escalation_mark
from failure import Failure
+5 -5
View File
@@ -61,7 +61,7 @@ def review_launches(route: Route, project: Rung | None) -> list[str]:
if project is None:
return []
choice = chosen(project, route)
return [*shared_launches(choice, route, project), *scan_launch(choice, route), *planning_launch(route, project), *taken_in_launches(choice), *markdown_launch(choice, project)]
return [*shared_launches(choice, route, project), *scan_launch(choice, route), *planning_launch(route, project), *taken_in_launches(choice), *markdown_launch(choice)]
def scan_launch(choice: ReviewChoice, route: Route) -> list[str]:
@@ -74,13 +74,13 @@ def planning_launch(route: Route, project: Rung) -> list[str]:
return [f"Your rung is below the project's: launch each subagent that files or scores todo.md items on the rung `~/.claude/bin/subagent-rung --plan {project.model} <L>` prints."] if position(route.rung) < position(project) else []
def markdown_launch(choice: ReviewChoice, project: Rung) -> list[str]:
"""Where the reviewers run above the project's rung, the sentence that a branch changing only Markdown no agent follows reviews on the project's rung, as rule-hook's reviewer-rung allows. 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 position(choice.reviewers) <= position(project):
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.`"""
if choice.markdown_only == choice.reviewers:
return []
files = ", ".join(f"`{name}`" for name in INSTRUCTION_FILES)
folders = listed([f"`{folder}/`" for folder in INSTRUCTION_FOLDERS], "or")
return [f"Where your branch changes only Markdown, none of it {files} or under {folders}, launch {EACH_REVIEWER} on the project's rung instead, with the Agent tool set to {project.agent_args()}."]
return [f"Where your branch changes only Markdown, none of it {files} or under {folders}, launch {EACH_REVIEWER} on the project's rung instead, with the Agent tool set to {choice.markdown_only.agent_args()}."]
def shared_launches(choice: ReviewChoice, route: Route, project: Rung) -> list[str]:
+1 -1
View File
@@ -1,6 +1,6 @@
import typing
from loop_claude.effects import Effects, say
from loop_effects.effects import Effects, say
from failure import Failure
from claude_code.reply import Limited
from loop_claude.stop import Stop
+11 -6
View File
@@ -7,7 +7,7 @@ from transcript_archive.write import archive
from loop_claude.cycle.worker import AUTO_COMPACT_WINDOW, COMPACT_WINDOW, run_worker, worker_args
from loop_claude.cycle.judge import Brief, judge, Rejected
from claude_code.session import delete_session, Session, session_open, transcript_file
from loop_claude.effects import Effects, say
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from loop_claude.cycle.interrupt import interrupt, Talked, WorkerSession
@@ -86,10 +86,15 @@ def stopped(cycle: Cycle, stop: Stop, why: str) -> Stop:
def archived_stop(project_archive: pathlib.Path, session: Session, task: str, route: Route, stop: Stop, why: str, effects: Effects) -> Stop:
"""stop, once archived with the route the worker holds. A failed archive exits 1 whatever the stop; when the stop was this archive failing, its reason is said once."""
path = transcript_file(session)
failure = archive(project_archive, path, task, outcomes.stopped(route.worker_line(), why), effects.now(), lambda text: say(text, effects)) if path else None
failure = archived(project_archive, path, task, outcomes.stopped(route.worker_line(), why), effects) if path else None
return Stop(1, f"{failure.reason}\n{stop.reason}".rstrip()) if failure and failure.reason != stop.reason else stop
def archived(project_archive: pathlib.Path, transcript_path: str, task: str, outcome: str, effects: Effects) -> Failure | None:
"""transcript_archive.write.archive, stamped now and saying its notes through effects. A cycle and close.py, which has no Cycle, both archive through it."""
return archive(project_archive, transcript_path, task, outcome, effects.now(), lambda text: say(text, effects))
def judge_of(cycle: Cycle) -> Rung:
"""The judge's rung, which the archive names beside each verdict."""
return judge_rung(cycle.judge_model, cycle.route)
@@ -163,7 +168,7 @@ def ruling_outcome(cycle: Cycle, ruling: Interrupt | QuotedAnswer, quoted_answer
def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> Stop | None:
"""Archives a judge reply loop-claude rejected, so the archive shows what the judge returned before a retry or an exit 1."""
if unkept := archive(cycle.project_archive, transcript_path, cycle.task, outcomes.rejected(rejected.reason, rejected.reply, str(judge_of(cycle)), rejected.cost), cycle.effects.now(), lambda text: say(text, cycle.effects)):
if unkept := archived(cycle.project_archive, transcript_path, cycle.task, outcomes.rejected(rejected.reason, rejected.reply, str(judge_of(cycle)), rejected.cost), cycle.effects):
return Stop(1, unkept.reason)
return None
@@ -183,7 +188,7 @@ def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) ->
def archive_stepped(cycle: Cycle, transcript_path: str, outcome: str, step_up: StepUp | None) -> Failure | None:
"""Archives the outcome of a ruling, then the step-up it made, if it made one. The first failure is returned."""
if failure := archive(cycle.project_archive, transcript_path, cycle.task, outcome, cycle.effects.now(), lambda text: say(text, cycle.effects)):
if failure := archived(cycle.project_archive, transcript_path, cycle.task, outcome, cycle.effects):
return failure
return archived_step(cycle.project_archive, transcript_path, cycle.task, step_up, cycle.effects)
@@ -192,7 +197,7 @@ def archived_step(project_archive: pathlib.Path, transcript_path: str, task: str
"""Archives a step-up, if there is one, as the worker line it steps to. The outcome archived before it names the route the worker ran on until then, so the figures charge each stretch of work to its own rung. Both a ruling within a cycle and an unfinished verdict between cycles archive their step-up here."""
if step_up is None:
return None
return archive(project_archive, transcript_path, task, outcomes.stepped_up(step_up.after.worker_line()), effects.now(), lambda text: say(text, effects))
return archived(project_archive, transcript_path, task, outcomes.stepped_up(step_up.after.worker_line()), effects)
def question_for(ruling: Interrupt | QuotedAnswer) -> str:
@@ -203,7 +208,7 @@ def question_for(ruling: Interrupt | QuotedAnswer) -> str:
def close(cycle: Cycle, transcript_path: str, verdict: Finished | Unfinished) -> Archived | Stop:
outcome = outcomes.finished(cycle.route.worker_line(), verdict.evidence, str(judge_of(cycle)), verdict.judge_cost) if isinstance(verdict, Finished) else outcomes.unfinished(cycle.route.worker_line(), verdict.evidence, str(judge_of(cycle)), verdict.escalation, verdict.judge_cost)
if failure := archive(cycle.project_archive, transcript_path, cycle.task, outcome, cycle.effects.now(), lambda text: say(text, cycle.effects)):
if failure := archived(cycle.project_archive, transcript_path, cycle.task, outcome, cycle.effects):
return Stop(1, failure.reason)
if isinstance(verdict, Finished) and (failure := delete_session(cycle.session)):
return Stop(1, failure.reason)
+1 -1
View File
@@ -1,5 +1,5 @@
from claude_code.entries import AssistantTurn, ends_stream, entry_from, hit_limit, json_object, limit_said, rejected_until
from loop_claude.effects import Effects, say
from loop_effects.effects import Effects, say
from failure import Failure
from claude_code.reply import Limited
from claude_code.transcript import part_line
+11 -11
View File
@@ -4,7 +4,7 @@ import typing
from release_plan.release_standing import default_plan, DefaultPlan
from git_cli.git_repo import default_ref, file_at
from loop_claude.effects import Effects, say
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.routing import first_route, kept, routed_item
from release_plan.todo_table import Item
@@ -13,22 +13,22 @@ from loop_claude.cycle import prompts
from model_routing.route import Route, route_from
from model_routing.ladder import Rung
from claude_code.session import Session, session_open, transcript_file
from loop_claude.running_loops import Show, taken_items
from loop_state.running_loops import Show, taken_items
# Seconds routing waits for origin to name its default branch, asked only where the checkout records none; past them, the chunk runs on the project's rung.
ORIGIN_TIMEOUT = 60
def shown_items(show: Show, root: str, routed: int) -> typing.Callable[[tuple[int, ...]], None]:
def shown_items(show: Show, root: str, routed: int, effects: Effects) -> typing.Callable[[tuple[int, ...]], None]:
"""A function that lists in loop-inbox the items a chunk takes, given the IDs the judge found taken in. routed is the item the chunk was routed on, 0 for none. shown_items reads todo.md once, as the cycle starts, and the function shows those taglines."""
todo = fetched_todo(root)
todo = fetched_todo(root, effects)
return lambda taken_in: show(taken_items(todo, routed, taken_in))
def fetched_todo(root: str) -> str | Failure:
def fetched_todo(root: str, effects: Effects) -> str | Failure:
"""todo.md on the default branch, as last fetched. fetched_plan reads it too, but also the release tag, CHANGELOG.md and each todo.md since the tag, which the listing doesn't need."""
ref = default_ref(root, ORIGIN_TIMEOUT)
return ref if isinstance(ref, Failure) else file_at(ref, "todo.md", root)
ref = default_ref(root, ORIGIN_TIMEOUT, run=effects.git)
return ref if isinstance(ref, Failure) else file_at(ref, "todo.md", root, effects.git)
def routed(route: Route | None, project: Rung | None, model: str, archived: typing.Callable[[], Route | None], item: typing.Callable[[], Item | None]) -> Route:
@@ -58,7 +58,7 @@ def archived_route(archive_folder: pathlib.Path, session: Session, effects: Effe
def chunk_start(session: Session, preflight: pathlib.Path, root: str, effects: Effects) -> tuple[str, typing.Callable[[], Item | None]]:
"""The facts for a fresh worker's prompt, empty where the session is open, and the reader of the item that routes the chunk. The reader reads the default branch as last fetched: for a fresh chunk, by the preflight that runs first; for an open session, which runs none, by whatever fetched last."""
facts = "" if session_open(session) else chunk_facts(preflight, root, effects)
return facts, lambda: plan_item(fetched_plan(root), effects)
return facts, lambda: plan_item(fetched_plan(root, effects), effects)
def chunk_facts(preflight: pathlib.Path, root: str, effects: Effects) -> str:
@@ -69,10 +69,10 @@ def chunk_facts(preflight: pathlib.Path, root: str, effects: Effects) -> str:
return prompts.preflight_facts(done.stdout.strip())
def fetched_plan(root: str) -> DefaultPlan | Failure:
def fetched_plan(root: str, effects: Effects) -> DefaultPlan | Failure:
"""What the default branch, as last fetched, holds for routing."""
ref = default_ref(root, ORIGIN_TIMEOUT)
return ref if isinstance(ref, Failure) else default_plan(root, ref)
ref = default_ref(root, ORIGIN_TIMEOUT, run=effects.git)
return ref if isinstance(ref, Failure) else default_plan(root, ref, effects.git)
def plan_item(plan: DefaultPlan | Failure, effects: Effects) -> Item | None:
+1 -1
View File
@@ -3,7 +3,7 @@ import dataclasses
import pathlib
from loop_claude.cycle.run import archived_step, archived_stop, Concluded
from loop_claude.effects import Effects
from loop_effects.effects import Effects
from loop_claude.verdicts import Finished
from loop_claude.loop.reload import LoopRun
from loop_claude.stop import needs_human, Stop
+4 -4
View File
@@ -9,12 +9,12 @@ from loop_claude.project.checkout import checkout_root
from loop_claude.loop.close import closed_cycle
from loop_claude.cycle.run import Cycle, run_cycle
from loop_claude.loop.reload import decode_handed, exec_if_edited, fingerprint, LoopRun, RELOAD_FLAG
from loop_claude.effects import Effects, say
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.project.model_choice import get_or_ask_models
from loop_claude.loop.usage import HELP
from loop_claude.running_loops import Listed, shown_running
from loop_claude.paths import Paths
from loop_state.running_loops import Listed, shown_running
from loop_state.paths import Paths
from transcript_archive.project_key import project_key
from model_routing.ladder import project_rung
from loop_claude.project.premises import read_premises
@@ -78,7 +78,7 @@ def next_cycle(loop_run: LoopRun, session: Session, listed: Listed, paths: Paths
project = project_rung(models.worker)
route = routed(loop_run.route, project, models.worker, lambda: archived_route(archive_folder, session, effects), item)
say(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", effects, stdout=True)
show_taken_in = shown_items(listed.show, loop_run.root, route.item)
show_taken_in = shown_items(listed.show, loop_run.root, route.item, effects)
show_taken_in(loop_run.items_taken_in)
return Cycle(effects=effects, facts=facts, judge_model=models.judge, premises=premises, project=project, project_archive=archive_folder, questions=listed.folder, records=records, root=loop_run.root, route=route, session=session, show_taken_in=show_taken_in, task=loop_run.task, unfinished_evidence=loop_run.unfinished_evidence)
+10 -14
View File
@@ -5,9 +5,8 @@ import pathlib
import sys
import typing
from loop_claude.effects import Effects, say
from model_routing.route import Route
from model_routing.ladder import Rung
from loop_effects.effects import Effects, say
from model_routing.route import Route, route_of
from loop_claude.stop import Stop
RELOAD_FLAG = "--reloaded"
@@ -67,23 +66,20 @@ def decoded_ids(value: object) -> tuple[int, ...]:
return tuple(exactly(int)(each) for each in value)
def decoded_rung(value: object) -> Rung:
return Rung(**decoded_fields(value, {"model": exactly(str), "effort": exactly(str)}, "model"))
def decoded_route(value: object) -> Route | None:
"""The Route the JSON holds; None for null, or for a route holding a key Route.RETIRED names, so the chunk routes afresh."""
if value is None or (isinstance(value, dict) and value.keys() & Route.RETIRED):
"""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."""
if value is None:
return None
fields = decoded_fields(value, ROUTE_FIELDS, "rung")
if not Route.fits(fields):
if not isinstance(value, dict) or not isinstance(value.get("rung"), dict) or not value["rung"].keys() <= {"model", "effort"} or value.keys() & {"model", "effort"}:
raise Unreadable
return Route(**fields)
route = route_of({**{name: field for name, field in value.items() if name not in ("rung", "unfinished")}, **value["rung"]})
if route is None:
raise Unreadable
return dataclasses.replace(route, unfinished=exactly(int)(value.get("unfinished", 0)))
# One decoder per field of LoopRun and of Route, which tests hold to those dataclasses' fields: a field missing here stops a loop at the reload after it joined.
# One decoder per field of LoopRun, which a test holds to the dataclass's fields: a field missing here stops a loop at the reload after it joined.
LOOP_RUN_FIELDS = {"cycle_number": exactly(int), "root": exactly(str), "task": exactly(str), "unfinished_evidence": exactly(str), "route": decoded_route, "unfinished_run": exactly(int), "items_taken_in": decoded_ids}
ROUTE_FIELDS = {"rung": decoded_rung, **{name: exactly(int) for name in ("item", "likelihood", "escape_and_impact", "unfinished", "escape_and_impact_taken_in", "escalated_at")}}
def fingerprint(launcher: pathlib.Path) -> str:
+5 -5
View File
@@ -2,13 +2,13 @@
import pathlib
from routing_figures import archive
from loop_claude.waiting.ask import Ask, OpenOnTerminal
from loop_state.waiting.ask import Ask, OpenOnTerminal
from routing_figures.calls import Call, calls, totals
from loop_claude.hand_over import claude_args, ClaudeCommand, hand_over
from loop_claude.effects import Effects, say
from loop_state.hand_over import claude_args, ClaudeCommand, hand_over
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.waiting.listing import listed
from loop_claude.paths import Paths
from loop_state.waiting.listing import listed
from loop_state.paths import Paths
from routing_figures.render import render
from model_routing.ladder import Rung
from routing_figures import state
+1 -1
View File
@@ -35,7 +35,7 @@ A release ready to cut opens that session on the terminal at once, since only th
loop-inbox lists it too. While claude is open, Ctrl-C reaches it alone, and the loop goes on.
While it runs, loop-claude also lists itself in loop-inbox, with the todo.md items its chunk takes,
as bin/loop_claude/running_loops.py describes.
as bin/loop_state/running_loops.py describes.
As a chunk starts, before it is routed, loop-claude runs bin/chunk-preflight --worktree and quotes
what it prints in the first prompt (prompts.preflight_facts in bin/loop_claude/cycle/prompts.py);
+1 -1
View File
@@ -2,7 +2,7 @@ import pathlib
from failure import Failure
from loop_claude.effects import Effects
from loop_effects.effects import Effects
from loop_claude.stop import Stop
+2 -2
View File
@@ -5,10 +5,10 @@ import sys
import typing
from claude_code.model_catalog import catalog_models
from loop_claude.effects import Effects, say
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.stop import needs_human, needs_terminal, Stop
from loop_claude.paths import Paths
from loop_state.paths import Paths
from records.file_writes import replace_json
+38 -14
View File
@@ -4,7 +4,7 @@ The worker, and the session /talk opens, run on a Route (model_routing/route.py)
- Start. routed_item finds the plan item that routes a fresh chunk, if there is one with L, E and I scored; first_route picks the worker's rung from its L, or the project's rung without an item.
- Rerun. kept decides whether a rerun resumes the route its archive last names.
- Step-up. next_route raises the route after an unfinished verdict, or an interrupt or a quoted answer that carries an escalation; escalation_cap bounds an escalation, and loop_claude/escalation_mark.py states the escalation mark's rule. step_up names the change where it changes the worker line, which the archive records.
- Step-up. next_route raises the route after an unfinished verdict (unfinished_route), or an interrupt or a quoted answer that carries an escalation (escalated_route); escalation_cap bounds an escalation, and loop_claude/escalation_mark.py states the escalation mark's rule. step_up names the change where it changes the worker line, which the archive records.
- Judge. judge_rung picks the rung of the judge of a JUDGE_REPLAYED model.
"""
import dataclasses
@@ -82,25 +82,49 @@ class StepUp:
def next_route(project: Rung | None, route: Route, verdict: Unfinished | Interrupt | QuotedAnswer) -> Route:
"""The route the worker runs on after the judge's verdict. Off the ladder, project is None, and the route holds.
The rung never falls. It first rises to floor_rung, which the verdict's highest L taken in may raise. From there it steps one rung up on an escalation while below escalation_cap, and moves the mark, as loop_claude/escalation_mark.py says.
An unfinished verdict also counts towards UNFINISHED_PER_STEP, and the second such verdict steps the rung once, keeping the mark; where both fall on one verdict, it steps once. Last, it takes in the verdict's highest E + I, as Route.taking_in does.
An interrupt or a quoted answer without an escalation leaves the route as it is, since neither is an unfinished verdict.
"""
"""The route the worker runs on after the judge's verdict. Off the ladder, project is None, and the route holds. The rung never falls."""
if project is None:
return route
if isinstance(verdict, Unfinished):
return unfinished_route(project, route, verdict)
return escalated_route(project, route, verdict)
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.
"""
mark = escalation_mark.moved_to(verdict)
floor = floor_rung(project, route, verdict.taken_in.highest_likelihood)
escalated_at = route.escalated_at if mark is None else mark
escalates = mark is not None and position(floor) < position(escalation_cap(project, route))
if isinstance(verdict, Unfinished):
counted = route.unfinished + 1
after = one_rung_up(route, floor, escalated_at) if counted >= UNFINISHED_PER_STEP or escalates else dataclasses.replace(route, rung=floor, unfinished=counted)
return after.taking_in(verdict.taken_in.highest_escape_and_impact)
counted = route.unfinished + 1
if steps(counted, mark is not None and below_cap(project, route, floor)):
after = one_rung_up(route, floor, route.escalated_at if mark is None else mark)
else:
after = dataclasses.replace(route, rung=floor, unfinished=counted)
return after.taking_in(verdict.taken_in.highest_escape_and_impact)
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.
"""
mark = escalation_mark.moved_to(verdict)
if mark is None:
return route
return one_rung_up(route, floor, escalated_at) if escalates else dataclasses.replace(route, rung=floor)
floor = floor_rung(project, route, verdict.taken_in.highest_likelihood)
return one_rung_up(route, floor, mark) if below_cap(project, route, floor) else dataclasses.replace(route, rung=floor)
def steps(counted: int, escalates: bool) -> bool:
"""Whether an unfinished verdict steps the rung: it is the UNFINISHED_PER_STEP-th since the last step, or it escalates below escalation_cap. Where both hold, the rung still steps once."""
return counted >= UNFINISHED_PER_STEP or escalates
def below_cap(project: Rung, route: Route, floor: Rung) -> bool:
"""Whether an escalation from floor may step the rung: floor lies below escalation_cap."""
return position(floor) < position(escalation_cap(project, route))
def step_up(before: Route, after: Route) -> StepUp | None:
+3 -3
View File
@@ -18,9 +18,9 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from test_env import isolated_env
from loop_claude.waiting.answers import send, Typed
from loop_claude import session_lock
from loop_claude.waiting.listing import waiting
from loop_state.waiting.answers import send, Typed
from loop_state import session_lock
from loop_state.waiting.listing import waiting
BIN = pathlib.Path(__file__).resolve().parents[1]
TASK = "Do the next chunk."
+9 -133
View File
@@ -1,18 +1,15 @@
import ast
import contextlib
import dataclasses
import errno
import io
import json
import os
import pathlib
import shutil
import signal
import stat
import subprocess
import sys
import tempfile
import time
import unittest
import unittest.mock
import uuid
@@ -20,31 +17,32 @@ import uuid
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from routing_figures import archive, state
from loop_claude.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal
from routing_figures.calls import Call
from loop_claude.project import checkout, model_choice, records
from loop_claude.loop import chunk_start, close
from loop_claude.waiting.answers import ClaudeEnded, ClaudeOpening, send, Typed
from loop_state.waiting.answers import ClaudeEnded, ClaudeOpening, send, Typed
from release_plan.release_standing import DefaultPlan, LastCut
from loop_claude.effects import Effects, POLL_SECONDS, PYTHON_TIMEOUT, run_python, say, system_effects
from loop_effects.effects import Effects, POLL_SECONDS, PYTHON_TIMEOUT
from claude_code import entries, reply, session
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, TakenIn, Unfinished
from loop_claude import hand_over, paths, routing, running_loops, session_lock
from loop_state import hand_over, paths, running_loops, session_lock
from loop_claude.cycle import interrupt, judge, prompts, retry, run, states, worker
from model_routing.ladder import LADDER, Rung
from claude_code.reply import Limited
from loop_claude.loop import main, reload, routing_check, usage
from loop_claude.waiting.talk import make_way
from loop_state.waiting.talk import make_way
from machine_load import memory
from transcript_archive import outcomes, write
from transcript_archive.location import project_archive
from model_routing.route import Route, route_from, WorkerLine
from loop_claude import routing
from loop_claude.stop import Stop
from loop_claude.running_loops import Taken
from loop_state.running_loops import Taken
from records.utc_stamp import utc
from loop_claude.cycle.judge import verdict_from
from loop_claude.waiting.listing import waiting
from loop_state.waiting.listing import waiting
# How the archive records a worker that runs off the ladder.
OFF_LADDER = '{"model": "worker-model"}'
@@ -637,39 +635,6 @@ class Retried(unittest.TestCase):
self.assertEqual(said.getvalue(), f"{STAMP} the judge hit a usage limit (You've hit your session limit); retrying at <{NOW + 3720}>\n")
class Said(unittest.TestCase):
def test_opens_a_line_with_the_local_time_of_the_effects_clock(self):
with contextlib.redirect_stderr(io.StringIO()) as stderr, contextlib.redirect_stdout(io.StringIO()) as stdout:
say("hello", FakeEffects().effects())
self.assertEqual((stderr.getvalue(), stdout.getvalue()), (f"{STAMP} hello\n", ""))
def test_stamps_only_the_first_line_of_a_question_after_its_blank_line(self):
with contextlib.redirect_stderr(io.StringIO()) as stderr:
say("\nWhich one?\n\nA or B?", FakeEffects().effects())
self.assertEqual(stderr.getvalue(), f"\n{STAMP} Which one?\n\nA or B?\n")
def test_says_on_stdout_where_asked(self):
with contextlib.redirect_stderr(io.StringIO()) as stderr, contextlib.redirect_stdout(io.StringIO()) as stdout:
say("\n=== cycle 2 ===", FakeEffects().effects(), stdout=True)
self.assertEqual((stderr.getvalue(), stdout.getvalue()), ("", f"\n{STAMP} === cycle 2 ===\n"))
def test_keeps_the_indent_of_the_first_line_after_the_time(self):
with contextlib.redirect_stderr(io.StringIO()) as stderr:
say("\n indented", FakeEffects().effects())
self.assertEqual(stderr.getvalue(), f"\n{STAMP} indented\n")
def test_flushes_so_piped_lines_arrive_when_said(self):
flushes = []
class Counting(io.StringIO):
def flush(self):
flushes.append(self.getvalue())
with contextlib.redirect_stderr(Counting()):
say("hello", FakeEffects().effects())
self.assertEqual(flushes, [f"{STAMP} hello\n"])
class Limits(unittest.TestCase):
def test_the_worker_reports_the_latest_reset_its_stream_names(self):
rejected = [{"type": "rate_limit_event", "rate_limit_info": {"status": "rejected", "resetsAt": resets_at}} for resets_at in (NOW + 60, NOW + 600)]
@@ -1340,90 +1305,6 @@ class ChunkFacts(unittest.TestCase):
self.assertEqual((resumed.made("python"), facts), ([], ""))
class LocalTime(unittest.TestCase):
def test_renders_seconds_in_the_machines_zone(self):
# A POSIX zone two hours ahead of UTC, so a time in UTC would read 14:13:20. Cleanups run last in, first out: the zone is restored before time.tzset makes the clock read it again.
self.addCleanup(time.tzset)
zone = unittest.mock.patch.dict(os.environ, {"TZ": "XXX-2"})
zone.start()
self.addCleanup(zone.stop)
time.tzset()
self.assertEqual(system_effects().local_time(NOW), "2026-09-21 16:13:20")
class Alive(unittest.TestCase):
def test_a_process_that_runs_is_alive_and_one_that_ended_is_not(self):
ended = subprocess.Popen([sys.executable, "-c", "pass"])
ended.wait()
# Unless this process runs as root, it may not signal pid 1, which still runs.
self.assertEqual([system_effects().alive(pid) for pid in (os.getpid(), ended.pid, 1)], [True, False, True])
class SessionLock(unittest.TestCase):
def setUp(self):
self.folder = pathlib.Path(tempfile.mkdtemp())
self.addCleanup(shutil.rmtree, self.folder)
self.path = session_lock.lock_file(self.folder, "s1")
def test_a_held_lock_refuses_a_second_taker_and_reads_as_running_until_let_go(self):
self.assertFalse(session_lock.running(self.folder, "s1"))
with session_lock.held(self.folder, "s1") as first:
self.assertIsNone(first)
with session_lock.held(self.folder, "s1") as second:
self.assertEqual(second, Failure(f"another process holds {self.path}"))
self.assertTrue(session_lock.running(self.folder, "s1"))
self.assertFalse(session_lock.running(self.folder, "s1"))
def test_a_lock_that_cannot_be_opened_is_a_failure_and_no_loop_running(self):
self.path.mkdir()
with session_lock.held(self.folder, "s1") as unlocked:
self.assertEqual(unlocked, Failure(f"cannot open {self.path}: Is a directory"))
self.assertFalse(session_lock.running(self.folder, "s1"))
def test_a_lock_the_kernel_refuses_is_a_failure_and_no_loop_running(self):
self.path.touch()
with unittest.mock.patch("fcntl.flock", side_effect=OSError(errno.ENOLCK, "No locks available")):
with session_lock.held(self.folder, "s1") as unlocked:
self.assertEqual(unlocked, Failure(f"cannot lock {self.path}: No locks available"))
self.assertFalse(session_lock.running(self.folder, "s1"))
class ClaudeOnTerminal(unittest.TestCase):
def test_leaves_ctrl_c_to_claude_while_it_runs_and_returns_its_exit_code(self):
caught = []
self.addCleanup(signal.signal, signal.SIGINT, signal.signal(signal.SIGINT, lambda number, frame: caught.append(number)))
before = signal.getsignal(signal.SIGINT)
with tempfile.TemporaryDirectory() as folder:
claude = pathlib.Path(folder, "claude")
# A Ctrl-C on the terminal reaches every process in its foreground. kill returns once the signal is pending in the test's process, before claude exits and claude_on_terminal returns.
claude.write_text(f"#!{sys.executable}\nimport os, signal, sys\nos.kill(os.getppid(), signal.SIGINT)\nsys.exit(3)\n")
claude.chmod(0o755)
code = system_effects().claude_on_terminal([], folder, {"PATH": folder})
self.assertEqual((code, caught, signal.getsignal(signal.SIGINT)), (3, [], before))
class PythonEffect(unittest.TestCase):
def test_runs_a_script_in_the_given_directory(self):
with tempfile.TemporaryDirectory() as cwd:
self.assertEqual(run_python(["-c", "import os; print(os.getcwd())"], cwd, 60).stdout.strip(), os.path.realpath(cwd))
def test_stops_a_script_still_running_after_the_timeout_and_reads_it_as_exit_1(self):
done = run_python(["-c", "import threading; threading.Event().wait()"], "/", 0.5)
self.assertEqual(done.returncode, 1)
self.assertIn("0.5 s", done.stderr)
def test_reads_output_that_is_not_utf_8_with_each_bad_byte_replaced(self):
with tempfile.TemporaryDirectory() as cwd:
self.assertEqual(run_python(["-c", "import sys; sys.stdout.buffer.write(b'caf\\xe9')"], cwd, 60).stdout, "caf�")
def test_reads_a_script_that_cannot_start_as_exit_1_saying_why(self):
with tempfile.TemporaryDirectory() as temp:
gone = str(pathlib.Path(temp, "gone"))
done = run_python(["-c", "pass"], gone, 60)
self.assertEqual(done.returncode, 1)
self.assertIn(gone, done.stderr)
class TypedAnswers(unittest.TestCase):
def test_splits_the_prompt_handing_over_the_answer_into_the_answer_on_the_line_after_its_marker_and_the_rest_and_no_other_prompt(self):
route = Route(Rung("worker-model"))
@@ -1803,11 +1684,10 @@ class LoopRuns(unittest.TestCase):
state = main.LoopRun(cycle_number=2, root="/r", task="do it", unfinished_evidence="old", route=Route(Rung("claude-opus-5-5", "high"), 3, 4, 5, 1, 7, 9), unfinished_run=2, items_taken_in=(12, 14))
self.assertEqual(reload.decode_handed(json.dumps(dataclasses.asdict(state))), state)
self.assertEqual(set(reload.LOOP_RUN_FIELDS), {field.name for field in dataclasses.fields(main.LoopRun)})
self.assertEqual(set(reload.ROUTE_FIELDS), {field.name for field in dataclasses.fields(Route)})
def test_rejects_a_field_of_another_type_or_an_unknown_field(self):
state = dataclasses.asdict(main.LoopRun(cycle_number=2, root="/r", task="do it", unfinished_evidence="", route=Route(Rung("claude-opus-5-5", "high"), 3, 4, 5, 1, 7, 9), unfinished_run=2))
for path, wrong in ((("unfinished_run",), "2"), (("unfinished_run",), True), (("route", "unfinished"), 1.0), (("route", "escalated_at"), "9"), (("route", "item"), True), (("route", "rung"), "claude-opus-5-5"), (("route", "rung", "model"), None), (("route",), "r"), (("route", "extra"), 1)):
for path, wrong in ((("unfinished_run",), "2"), (("unfinished_run",), True), (("route", "unfinished"), 1.0), (("route", "escalated_at"), "9"), (("route", "item"), True), (("route", "rung"), "claude-opus-5-5"), (("route", "rung", "model"), None), (("route",), "r"), (("route", "extra"), 1), (("route", "model"), "claude-opus-5-5")):
with self.subTest(path=path, wrong=wrong):
handed = json.loads(json.dumps(state))
target = handed
@@ -1858,10 +1738,6 @@ class LoopRuns(unittest.TestCase):
handed["route"]["escape_and_impact_taken_in"] = taken_in
self.assertIsNone(reload.decode_handed(json.dumps(handed)))
def test_drops_a_route_an_older_loop_claude_handed_under_r_plus_c_so_the_chunk_routes_afresh(self):
older = {"cycle_number": 3, "root": "/r", "task": "do it", "unfinished_evidence": "", "route": {"rung": {"model": "claude-opus-5-5", "effort": "high"}, "item": 3, "risk_and_complexity": 11, "unfinished": 1}}
self.assertEqual(reload.decode_handed(json.dumps(older)), main.LoopRun(3, "/r", "do it", ""))
def test_decodes_a_state_from_before_a_field_with_a_default_joined_it(self):
self.assertEqual(reload.decode_handed(json.dumps({"cycle_number": 3, "root": "/r", "task": "do it", "unfinished_evidence": ""})), main.LoopRun(3, "/r", "do it", ""))
+1
View File
@@ -0,0 +1 @@
"""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,4 +1,7 @@
"""The effects loop-claude reaches the world through, such as its terminal, clock, processes, git and the machine's memory. loop-inbox runs on them too, so a change here, such as to how input reads a line, changes both tools."""
"""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.
"""
import dataclasses
import os
import select
+117
View File
@@ -0,0 +1,117 @@
import contextlib
import dataclasses
import io
import os
import pathlib
import signal
import subprocess
import sys
import tempfile
import time
import unittest
import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from loop_effects.effects import run_python, say, system_effects
NOW = 1790000000
# How a line said at NOW opens, with clocked's local_time.
STAMP = f"<{NOW}>"
def clocked():
"""The system's effects on a clock stopped at NOW, which renders a time as <seconds>."""
return dataclasses.replace(system_effects(), local_time=lambda seconds: f"<{seconds}>", now=lambda: NOW)
class Said(unittest.TestCase):
def test_opens_a_line_with_the_local_time_of_the_effects_clock(self):
with contextlib.redirect_stderr(io.StringIO()) as stderr, contextlib.redirect_stdout(io.StringIO()) as stdout:
say("hello", clocked())
self.assertEqual((stderr.getvalue(), stdout.getvalue()), (f"{STAMP} hello\n", ""))
def test_stamps_only_the_first_line_of_a_question_after_its_blank_line(self):
with contextlib.redirect_stderr(io.StringIO()) as stderr:
say("\nWhich one?\n\nA or B?", clocked())
self.assertEqual(stderr.getvalue(), f"\n{STAMP} Which one?\n\nA or B?\n")
def test_says_on_stdout_where_asked(self):
with contextlib.redirect_stderr(io.StringIO()) as stderr, contextlib.redirect_stdout(io.StringIO()) as stdout:
say("\n=== cycle 2 ===", clocked(), stdout=True)
self.assertEqual((stderr.getvalue(), stdout.getvalue()), ("", f"\n{STAMP} === cycle 2 ===\n"))
def test_keeps_the_indent_of_the_first_line_after_the_time(self):
with contextlib.redirect_stderr(io.StringIO()) as stderr:
say("\n indented", clocked())
self.assertEqual(stderr.getvalue(), f"\n{STAMP} indented\n")
def test_flushes_so_piped_lines_arrive_when_said(self):
flushes = []
class Counting(io.StringIO):
def flush(self):
flushes.append(self.getvalue())
with contextlib.redirect_stderr(Counting()):
say("hello", clocked())
self.assertEqual(flushes, [f"{STAMP} hello\n"])
class LocalTime(unittest.TestCase):
def test_renders_seconds_in_the_machines_zone(self):
# A POSIX zone two hours ahead of UTC, so a time in UTC would read 14:13:20. Cleanups run last in, first out: the zone is restored before time.tzset makes the clock read it again.
self.addCleanup(time.tzset)
zone = unittest.mock.patch.dict(os.environ, {"TZ": "XXX-2"})
zone.start()
self.addCleanup(zone.stop)
time.tzset()
self.assertEqual(system_effects().local_time(NOW), "2026-09-21 16:13:20")
class Alive(unittest.TestCase):
def test_a_process_that_runs_is_alive_and_one_that_ended_is_not(self):
ended = subprocess.Popen([sys.executable, "-c", "pass"])
ended.wait()
# Unless this process runs as root, it may not signal pid 1, which still runs.
self.assertEqual([system_effects().alive(pid) for pid in (os.getpid(), ended.pid, 1)], [True, False, True])
class ClaudeOnTerminal(unittest.TestCase):
def test_leaves_ctrl_c_to_claude_while_it_runs_and_returns_its_exit_code(self):
caught = []
self.addCleanup(signal.signal, signal.SIGINT, signal.signal(signal.SIGINT, lambda number, frame: caught.append(number)))
before = signal.getsignal(signal.SIGINT)
with tempfile.TemporaryDirectory() as folder:
claude = pathlib.Path(folder, "claude")
# A Ctrl-C on the terminal reaches every process in its foreground. kill returns once the signal is pending in the test's process, before claude exits and claude_on_terminal returns.
claude.write_text(f"#!{sys.executable}\nimport os, signal, sys\nos.kill(os.getppid(), signal.SIGINT)\nsys.exit(3)\n")
claude.chmod(0o755)
code = system_effects().claude_on_terminal([], folder, {"PATH": folder})
self.assertEqual((code, caught, signal.getsignal(signal.SIGINT)), (3, [], before))
class PythonEffect(unittest.TestCase):
def test_runs_a_script_in_the_given_directory(self):
with tempfile.TemporaryDirectory() as cwd:
self.assertEqual(run_python(["-c", "import os; print(os.getcwd())"], cwd, 60).stdout.strip(), os.path.realpath(cwd))
def test_stops_a_script_still_running_after_the_timeout_and_reads_it_as_exit_1(self):
done = run_python(["-c", "import threading; threading.Event().wait()"], "/", 0.5)
self.assertEqual(done.returncode, 1)
self.assertIn("0.5 s", done.stderr)
def test_reads_output_that_is_not_utf_8_with_each_bad_byte_replaced(self):
with tempfile.TemporaryDirectory() as cwd:
self.assertEqual(run_python(["-c", "import sys; sys.stdout.buffer.write(b'caf\\xe9')"], cwd, 60).stdout, "caf�")
def test_reads_a_script_that_cannot_start_as_exit_1_saying_why(self):
with tempfile.TemporaryDirectory() as temp:
gone = str(pathlib.Path(temp, "gone"))
done = run_python(["-c", "pass"], gone, 60)
self.assertEqual(done.returncode, 1)
self.assertIn(gone, done.stderr)
+3 -3
View File
@@ -10,9 +10,9 @@ import dataclasses
import textwrap
import typing
from loop_claude.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal
from loop_claude.running_loops import RunningLoop, Taken
from loop_claude.waiting.talk import TALK
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal
from loop_state.running_loops import RunningLoop, Taken
from loop_state.waiting.talk import TALK
ENTER = "enter"
BACKSPACE = "backspace"
+11 -11
View File
@@ -26,8 +26,8 @@ above where it waits for an answer, and a line per todo.md item its chunk takes,
tagline on the default branch. A loop whose process is gone drops off this list too.
The loops' questions are files in ~/.local/state/loop-claude, read and written as
bin/loop_claude/waiting/ describes; the running loops are files beside them, as
bin/loop_claude/running_loops.py describes.
bin/loop_state/waiting/ describes; the running loops are files beside them, as
bin/loop_state/running_loops.py describes.
Exit 2 when stdin or stdout is not a terminal, or on an unknown argument.
"""
@@ -39,16 +39,16 @@ import sys
import typing
from loop_inbox.inbox import Answering, answering_lines, BACKSPACE, ENTER, ESCAPE, fitted, Listing, listing_lines, Open, pressed, Quit, Screen, Send
from loop_claude.waiting.ask import Ask, Asking, read_ask
from loop_claude.waiting.listing import ask_file, drop_ended, waiting
from loop_claude.waiting.talk import claim_talk, MAKE_WAY_SECONDS
from loop_claude.waiting.answers import ClaudeEnded, send, Typed
from loop_claude.running_loops import drop_ended_loops, running_loops
from loop_claude.effects import Effects, system_effects
from loop_state.waiting.ask import Ask, Asking, read_ask
from loop_state.waiting.listing import ask_file, drop_ended, waiting
from loop_state.waiting.talk import claim_talk, MAKE_WAY_SECONDS
from loop_state.waiting.answers import ClaudeEnded, send, Typed
from loop_state.running_loops import drop_ended_loops, running_loops
from loop_effects.effects import Effects, system_effects
from failure import Failure
from loop_claude.hand_over import hand_over
from loop_claude.paths import Paths, paths_from
from loop_claude.session_lock import running
from loop_state.hand_over import hand_over
from loop_state.paths import Paths, paths_from
from loop_state.session_lock import running
USAGE = "usage: loop-inbox"
# Milliseconds between refreshes of the list while no key is pressed.
+9 -9
View File
@@ -12,18 +12,18 @@ import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from loop_claude.waiting.answers import answered, claude_ended, ClaudeEnded, ClaudeOpening, send, Typed
from loop_state.waiting.answers import answered, claude_ended, ClaudeEnded, ClaudeOpening, send, Typed
from loop_inbox.inbox import Answering, BACKSPACE, ENTER, ESCAPE, Listing, Open, Quit, Send
from loop_claude.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal, read_ask
from loop_claude.waiting.listing import ask_file, drop_ended, listed, publish, waiting, withdraw
from loop_claude.waiting.talk import claim_talk, MAKE_WAY_SECONDS
from loop_claude.hand_over import ClaudeCommand
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, OpenOnTerminal, read_ask
from loop_state.waiting.listing import ask_file, drop_ended, listed, publish, waiting, withdraw
from loop_state.waiting.talk import claim_talk, MAKE_WAY_SECONDS
from loop_state.hand_over import ClaudeCommand
from failure import Failure
from loop_inbox import inbox, main
from loop_claude.paths import paths_from
from loop_claude import running_loops, session_lock
from loop_claude.running_loops import RunningLoop, Taken
from loop_claude.effects import system_effects
from loop_state.paths import paths_from
from loop_state import running_loops, session_lock
from loop_state.running_loops import RunningLoop, Taken
from loop_effects.effects import system_effects
ASKING = Asking(ClaudeCommand(["--resume", "s"], "/c", {}))
# The pid of this loop-inbox.
+4
View File
@@ -0,0 +1,4 @@
"""The files loop-claude and loop-inbox share: a running loop lists itself (running_loops.py, session_lock.py) and its question (waiting/), and both read the same paths (paths.py) and open claude for the human the same way (hand_over.py).
A change here changes both tools. It imports nothing from loop_claude/.
"""
@@ -1,7 +1,7 @@
"""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."""
import dataclasses
from loop_claude.effects import Effects
from loop_effects.effects import Effects
from failure import Failure
from model_routing.ladder import Rung
@@ -11,7 +11,7 @@ class Paths:
home: pathlib.Path
model_catalog: pathlib.Path
models_file: pathlib.Path
# Where a loop shows its interrupt to loop-inbox (bin/loop_claude/waiting/).
# Where a loop shows its interrupt to loop-inbox (bin/loop_state/waiting/).
waiting: pathlib.Path
@@ -6,8 +6,6 @@ branch as last fetched. The items are the one the chunk was routed on, then thos
worker took in, each listed once. loop-inbox lists a loop, and its question (waiting/), only while the loop holds its
lock. So a killed loop drops off the list, though its files stay until loop-inbox removes them: <session>.running
through drop_ended_loops here, and the question through waiting.listing.drop_ended.
This module, waiting/ and session_lock.py hold loop-claude's state, which loop-inbox reads. They stay in loop_claude/ because they import its effects.py and hand_over.py: a package of their own would import loop_claude, and loop_claude would import it, a cycle.
"""
import contextlib
import dataclasses
@@ -16,8 +14,8 @@ import pathlib
import shutil
import typing
from loop_claude.effects import Effects, say
from loop_claude.session_lock import ended, held, running
from loop_effects.effects import Effects, say
from loop_state.session_lock import ended, held, running
from failure import Failure
from release_plan.todo_table import items
from records.file_writes import replace_json
+41
View File
@@ -0,0 +1,41 @@
import errno
import pathlib
import shutil
import sys
import tempfile
import unittest
import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
from loop_state import session_lock
class SessionLock(unittest.TestCase):
def setUp(self):
self.folder = pathlib.Path(tempfile.mkdtemp())
self.addCleanup(shutil.rmtree, self.folder)
self.path = session_lock.lock_file(self.folder, "s1")
def test_a_held_lock_refuses_a_second_taker_and_reads_as_running_until_let_go(self):
self.assertFalse(session_lock.running(self.folder, "s1"))
with session_lock.held(self.folder, "s1") as first:
self.assertIsNone(first)
with session_lock.held(self.folder, "s1") as second:
self.assertEqual(second, Failure(f"another process holds {self.path}"))
self.assertTrue(session_lock.running(self.folder, "s1"))
self.assertFalse(session_lock.running(self.folder, "s1"))
def test_a_lock_that_cannot_be_opened_is_a_failure_and_no_loop_running(self):
self.path.mkdir()
with session_lock.held(self.folder, "s1") as unlocked:
self.assertEqual(unlocked, Failure(f"cannot open {self.path}: Is a directory"))
self.assertFalse(session_lock.running(self.folder, "s1"))
def test_a_lock_the_kernel_refuses_is_a_failure_and_no_loop_running(self):
self.path.touch()
with unittest.mock.patch("fcntl.flock", side_effect=OSError(errno.ENOLCK, "No locks available")):
with session_lock.held(self.folder, "s1") as unlocked:
self.assertEqual(unlocked, Failure(f"cannot lock {self.path}: No locks available"))
self.assertFalse(session_lock.running(self.folder, "s1"))
@@ -5,7 +5,7 @@ import dataclasses
import json
import pathlib
from loop_claude.waiting.ask import Ask, tagged
from loop_state.waiting.ask import Ask, tagged
from failure import Failure
from records.file_writes import replace_json
@@ -6,7 +6,7 @@ import json
import pathlib
import typing
from loop_claude.hand_over import ClaudeCommand
from loop_state.hand_over import ClaudeCommand
from records.utc_stamp import seconds, utc
if typing.TYPE_CHECKING:
@@ -3,10 +3,10 @@ import contextlib
import pathlib
import typing
from loop_claude.waiting.answers import answer_file
from loop_claude.waiting.ask import Ask, ask_fields, read_ask
from loop_claude.effects import Effects, say
from loop_claude.session_lock import ended, running
from loop_state.waiting.answers import answer_file
from loop_state.waiting.ask import Ask, ask_fields, read_ask
from loop_effects.effects import Effects, say
from loop_state.session_lock import ended, running
from failure import Failure
from records.file_writes import make_private, replace_json
@@ -9,10 +9,10 @@ import dataclasses
import pathlib
import typing
from loop_claude.waiting.ask import Ask, Asking, OpenInInbox, read_ask
from loop_claude.waiting.listing import ask_file, shown
from loop_claude.waiting.answers import ClaudeEnded, ClaudeOpening, send
from loop_claude.effects import Effects, POLL_SECONDS
from loop_state.waiting.ask import Ask, Asking, OpenInInbox, read_ask
from loop_state.waiting.listing import ask_file, shown
from loop_state.waiting.answers import ClaudeEnded, ClaudeOpening, send
from loop_effects.effects import Effects, POLL_SECONDS
from failure import Failure
# Seconds loop-inbox waits for a loop to make way for its claude: ten of the loop's looks, so a loop slow for a moment still makes way.
+9 -6
View File
@@ -92,17 +92,20 @@ def stepped_up(rung: Rung) -> Rung:
return climbed(rung, 1)
def review_rung(project: Rung, worker: Rung, escape_and_impact: int, kind: ReviewKind) -> Rung:
"""The rung a review of this kind runs on in a chunk whose worker runs on worker and whose item has that E + I.
def review_rung(project: Rung, worker: Rung, escape_and_impact: int, kind: ReviewKind, markdown_only: bool = False) -> Rung:
"""The rung a review of this kind runs on in a chunk whose worker runs on worker and whose item has that E + I; markdown_only where the branch changes only Markdown no agent follows.
A pass's reviewer runs on reviewers_rung; no replay has qualified a lower rung for any pass, docs/decisions.md → `routing: a review pass runs below the project's rung only on a rung that a replay …`. A seat and the security pass run on the project's rung, so the seats score every chunk on one rung, and the security pass spends no more than the project chose.
"""
return project if kind in ("seat", "security") else reviewers_rung(project, worker, escape_and_impact)
return project if kind in ("seat", "security") else reviewers_rung(project, worker, escape_and_impact, markdown_only)
def reviewers_rung(project: Rung, worker: Rung, escape_and_impact: int) -> Rung:
"""The rung of each pass's reviewer: the higher of the worker's rung and review_floor's."""
return highest(worker, review_floor(project, escape_and_impact))
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".
"""
return project if markdown_only else highest(worker, review_floor(project, escape_and_impact))
def highest(*rungs: Rung) -> Rung:
+5 -3
View File
@@ -2,13 +2,15 @@
import dataclasses
from model_routing.route import HIGHEST_ESCAPE_AND_IMPACT, Route
from model_routing.ladder import reviewers_rung, Rung
from model_routing.ladder import review_rung, reviewers_rung, Rung
@dataclasses.dataclass(frozen=True)
class ReviewChoice:
# The rung of each pass's reviewer.
reviewers: Rung
# The rung of each pass's reviewer where the branch changes only Markdown no agent follows.
markdown_only: Rung
seat: Rung
security: Rung
# Each rung a higher E + I than the route's picks for the reviewers, with the lowest E + I that picks it, in rising order.
@@ -22,5 +24,5 @@ def chosen(project: Rung, route: Route) -> ReviewChoice:
for escape_and_impact in range(route.reviewed_on() + 1, HIGHEST_ESCAPE_AND_IMPACT + 1):
if (rung := reviewers_rung(project, route.rung, escape_and_impact)) != reviewers:
higher.setdefault(rung, escape_and_impact)
# A seat and the security pass run on the project's rung, as ladder.review_rung says.
return ReviewChoice(reviewers, project, project, higher)
markdown_only = reviewers_rung(project, route.rung, route.reviewed_on(), markdown_only=True)
return ReviewChoice(reviewers, markdown_only, review_rung(project, route.rung, route.reviewed_on(), "seat"), review_rung(project, route.rung, route.reviewed_on(), "security"), higher)
+10 -13
View File
@@ -38,8 +38,6 @@ class Route:
unfinished counts the unfinished verdicts towards the next one-rung step; a reload hands it over with the rung.
"""
# Each field below but rung and unfinished is a key of the archive's worker lines, so renaming one makes the lines already archived unreadable, and their chunks route afresh.
# The fields a loop-claude from before L and E + I replaced R + C hands on reload; the reloaded script drops such a route, and the chunk routes afresh.
RETIRED: typing.ClassVar[frozenset[str]] = frozenset({"risk_and_complexity"})
rung: Rung
item: int = 0
likelihood: int = 0
@@ -51,7 +49,7 @@ class Route:
escalated_at: int = 0
def __post_init__(self) -> None:
# Raises on a programming error only, so nothing catches it: route_from and the reload decoder check fits before they build a route.
# Raises on a programming error only, so nothing catches it: route_of checks fits before it builds a route.
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}")
@@ -80,19 +78,18 @@ WORKER_LINE_FIELDS = tuple(field.name for field in dataclasses.fields(Route) if
def route_from(worker: str) -> Route | None:
"""The route an archived worker line names; None for a line Route.worker_line could not have written, such as text that isn't JSON."""
fields = json_fields(worker)
if fields is None or not Route.fits(fields):
return None
return Route(Rung(fields["model"], fields.get("effort", "")), **{name: fields.get(name, 0) for name in WORKER_LINE_FIELDS})
def json_fields(line: str) -> dict[str, typing.Any] | None:
"""The fields of a line Route.worker_line wrote; None for any other text."""
try:
fields = json.loads(line)
fields = json.loads(worker)
except ValueError:
return None
return route_of(fields)
def route_of(fields: object) -> Route | None:
"""The route these fields of a worker line name, with an unfinished count of 0; None for fields Route.worker_line could not have written. A reload decodes its route through it too (loop_claude/loop/reload.py), so Route has one decoder."""
if not (isinstance(fields, dict) and isinstance(fields.get("model"), str) and isinstance(fields.get("effort", ""), str) and fields.keys() <= {"model", "effort", *WORKER_LINE_FIELDS}):
return None
# type(), not isinstance(): JSON true is no integer.
return fields if all(type(fields.get(name, 0)) is int and fields.get(name, 0) >= 0 for name in WORKER_LINE_FIELDS) else None
if not all(type(fields.get(name, 0)) is int and fields.get(name, 0) >= 0 for name in WORKER_LINE_FIELDS) or not Route.fits(fields):
return None
return Route(Rung(fields["model"], fields.get("effort", "")), **{name: fields.get(name, 0) for name in WORKER_LINE_FIELDS})
+4
View File
@@ -103,3 +103,7 @@ class Ladder(unittest.TestCase):
def test_keeps_the_seats_and_the_security_pass_on_the_projects_rung_whatever_the_worker_or_e_plus_i(self):
self.assertEqual([review_rung(OPUS, LADDER[-1], 8, kind) for kind in (*REVIEWERS, "seat", "security")], [LADDER[-1]] * len(REVIEWERS) + [OPUS, OPUS])
def test_puts_every_review_of_a_branch_changing_only_markdown_no_agent_follows_on_the_projects_rung(self):
self.assertEqual([review_rung(OPUS, LADDER[-1], 8, kind, markdown_only=True) for kind in (*REVIEWERS, "seat", "security")], [OPUS] * (len(REVIEWERS) + 2))
self.assertEqual(review_rung(OPUS, LADDER[0], 4, "stability", markdown_only=True), OPUS)
+4
View File
@@ -11,3 +11,7 @@ FABLE = Rung("claude-fable-5-1", "max")
class Chosen(unittest.TestCase):
def test_names_no_higher_rung_on_the_top_one(self):
self.assertEqual(chosen(OPUS, Route(FABLE, 3, 4, 5)).higher, {})
def test_reviews_a_branch_changing_only_markdown_on_the_projects_rung_and_the_seats_and_security_pass_there_always(self):
choice = chosen(OPUS, Route(FABLE, 3, 4, 5))
self.assertEqual((choice.reviewers, choice.markdown_only, choice.seat, choice.security), (FABLE, OPUS, OPUS, OPUS))
+3 -3
View File
@@ -89,7 +89,7 @@ import pathlib
import sys
from failure import Failure
from release_plan import ranking
from release_plan import plan_file
def main(argv: list[str]) -> int:
@@ -101,11 +101,11 @@ def main(argv: list[str]) -> int:
return fail(args)
check, todo = args
if check:
failures = ranking.check_failures(todo)
failures = plan_file.check_failures(todo)
for line in failures:
print(line, file=sys.stderr)
return 1 if failures else 0
ranked = ranking.rank_file(todo)
ranked = plan_file.rank_file(todo)
if isinstance(ranked, Failure):
return fail(ranked)
return 1 if ranked.under_bar else 0
+53
View File
@@ -0,0 +1,53 @@
"""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."""
import dataclasses
import graphlib
from failure import Failure
from release_plan.todo_table import Item
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."""
held = {item.id: (item, value) for item, value in scored}
position = {item.id: index for index, (item, _) in enumerate(scored)}
for item, _ in scored:
for blocker in item.blocked_by:
if blocker in held and held[blocker][0].release > item.release:
later, earlier = version(held[blocker][0].release), version(item.release)
return Failure(f"item {item.id}, in release {earlier}, is blocked by item {blocker}, in later release {later}; move item {blocker} to release {earlier} or earlier, or item {item.id} to release {later} or later")
if loop := blocking_loop(held):
return Failure(f"items {', '.join(map(str, loop[:-1]))} and {loop[-1]} block each other in a loop; drop one of the blockers")
placed: set[int] = set()
return [entry for item, _ in scored for entry in place(item.id, held, position, placed)]
def blocking_loop(held: dict[int, tuple[Item, float]]) -> list[int] | None:
"""The IDs of items that block each other in a loop, sorted; None where there is no loop."""
graph = {id_: {blocker for blocker in item.blocked_by if blocker in held} for id_, (item, _) in held.items()}
try:
graphlib.TopologicalSorter(graph).prepare()
except graphlib.CycleError as cycle:
return sorted(set(cycle.args[1]))
return 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."""
if id_ in placed:
return []
placed.add(id_)
item, value = held[id_]
blockers = sorted((blocker for blocker in set(item.blocked_by) if blocker in held), key=position.__getitem__)
before = [entry for blocker in blockers for entry in place(blocker, held, position, placed)]
return [*before, (dataclasses.replace(item, blocked_by=tuple(sorted(blockers))), value)]
def blocked_through(id_: int, items: list[Item]) -> set[int]:
"""The IDs of the items id_ blocks, and of those they block in turn."""
found: set[int] = set()
reached = {id_}
while reached:
reached = {other.id for other in items if reached.intersection(other.blocked_by)} - found
found |= reached
return found
+65
View File
@@ -0,0 +1,65 @@
"""The formula todo.md states its score in: arithmetic over an item's scores, parsed so that it can hold nothing else, and evaluated to a float."""
import ast
import math
from failure import Failure
# The most parts and characters a formula may hold.
LARGEST_FORMULA = 200
LONGEST_FORMULA = 4 * LARGEST_FORMULA
OPERATORS = (ast.Add, ast.BinOp, ast.Div, ast.Expression, ast.Load, ast.Mult, ast.Pow, ast.Sub, ast.UAdd, ast.UnaryOp, ast.USub)
def parse_formula(source: str | Failure, variables: tuple[str, ...]) -> ast.Expression | Failure:
if isinstance(source, Failure):
return source
# Deep nesting makes the parser itself run out of memory before LARGEST_FORMULA can count the parts.
if len(source) > LONGEST_FORMULA:
return Failure(f"the formula {source[:40]!r}... holds more than {LONGEST_FORMULA} characters")
try:
tree = ast.parse(source, mode="eval")
except (SyntaxError, ValueError):
return Failure(f"the formula {source!r} does not parse")
nodes = list(ast.walk(tree))
if len(nodes) > LARGEST_FORMULA:
return Failure(f"the formula {source!r} holds more than {LARGEST_FORMULA} parts")
for node in nodes:
numeric = isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool) and abs(node.value) < 1e300
if not (isinstance(node, OPERATORS) or numeric or (isinstance(node, ast.Name) and node.id in variables)):
return Failure(f"the formula {source!r} may hold only numbers, {', '.join(variables)}, + - * / ** and parentheses")
return tree
def evaluate(node: ast.AST, values: dict[str, float]) -> float:
"""Evaluates a tree parse_formula accepted; a division by zero, and a power that overflows or has no real value, give nan."""
match node:
case ast.Expression(body):
return evaluate(body, values)
case ast.Constant(value) if isinstance(value, (int, float)):
return float(value)
case ast.Name(name):
return values[name]
case ast.UnaryOp(ast.USub(), operand):
return -evaluate(operand, values)
case ast.UnaryOp(ast.UAdd(), operand):
return evaluate(operand, values)
case ast.BinOp(left, ast.Add(), right):
return evaluate(left, values) + evaluate(right, values)
case ast.BinOp(left, ast.Sub(), right):
return evaluate(left, values) - evaluate(right, values)
case ast.BinOp(left, ast.Mult(), right):
return evaluate(left, values) * evaluate(right, values)
case ast.BinOp(left, ast.Div(), right):
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
try:
return math.pow(base, exponent)
except (OverflowError, ValueError):
return math.nan
return math.nan
+62
View File
@@ -0,0 +1,62 @@
"""todo.md on disk: read it with the files beside it that ranking reads, rank it, write it back, and print what ranking reports."""
import pathlib
import sys
from failure import Failure
from review_rules.comprehension_history import HISTORY
from release_plan.ranking import rank, Ranked
from records.file_writes import replace_file
def rank_file(todo: pathlib.Path) -> Ranked | Failure:
"""Rank todo in place: rank what read_all reads, write todo where that changed it, and print the notes and under-bar lines on stderr."""
texts = read_all(todo)
if isinstance(texts, Failure):
return texts
ranked = rank(*texts)
if isinstance(ranked, Failure):
return ranked
if ranked.text != texts[0] and (unwritten := write(todo, ranked.text)):
return unwritten
print_report(todo, ranked)
return ranked
def print_report(todo: pathlib.Path, ranked: Ranked) -> None:
"""Print ranking's notes and under-bar lines on stderr, each prefixed with todo's path."""
for line in ranked.notes + ranked.under_bar:
print(f"{todo}: {line}", file=sys.stderr)
def check_failures(todo: pathlib.Path) -> list[str]:
"""Why --check fails on todo, empty when it passes."""
texts = read_all(todo)
if isinstance(texts, Failure):
return [texts.reason]
ranked = rank(*texts)
if isinstance(ranked, Failure):
return [ranked.reason]
unranked = [] if ranked.text == texts[0] else [f"{todo}: not ranked; run rank_todo.py on it"]
return unranked + [f"{todo}: {line}" for line in ranked.under_bar]
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."""
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:
texts.append(path.read_text(encoding="utf-8"))
except FileNotFoundError:
if missing:
return Failure(f"{path}: not found; {missing}")
texts.append("")
except OSError as failure:
return Failure(f"{path}: {failure.strerror}")
except UnicodeDecodeError:
return Failure(f"{path}: not UTF-8")
return texts[0], texts[1], texts[2], texts[3]
def write(path: pathlib.Path, text: str) -> Failure | None:
unwritten = replace_file(path.resolve(), text.encode("utf-8"))
return Failure(f"{path}: {unwritten.reason}") if unwritten else None
+7 -159
View File
@@ -1,19 +1,20 @@
"""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."""
"""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
import decimal
import graphlib
import math
import pathlib
import re
import sys
import typing
from release_plan.todo_table import BLOCKED_BY, cells, CODE_HEALTH, DETAILS, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, Shape, SHAPE, shape_of, Table, table_rows
from release_plan.blockers import blocked_through, blockers_first
from release_plan.formula import evaluate, parse_formula
from failure import Failure
from review_rules.comprehension_history import FLOOR, HISTORY, latest_overall
from review_rules.comprehension_history import FLOOR, latest_overall
from records.markdown_text import listed, sections
from records.file_writes import replace_file
from release_plan.release import version
# What each achieve goal weighs of the one above it; docs/decisions.md records the choice.
@@ -26,9 +27,6 @@ MAINTAIN_WEIGHT = 0.5
VOID = re.compile(r"^\*\*Void:\*\* (.*)$", re.M)
# A docs/decisions.md title opting the project out of the comprehension check, as larv-review's SKILL.md → "Opt-out" spells it.
OPTED_OUT = re.compile(r"^## review opt-out:.*\bcomprehension check\b", re.M)
LARGEST_FORMULA = 200
LONGEST_FORMULA = 4 * LARGEST_FORMULA
OPERATORS = (ast.Add, ast.BinOp, ast.Div, ast.Expression, ast.Load, ast.Mult, ast.Pow, ast.Sub, ast.UAdd, ast.UnaryOp, ast.USub)
WEIGHTS_HEADER = "| Goal | W |"
# The Exempt reasons that rank ahead of the rest of their release, in this order: a question first, since its answer may change other items, then a security finding.
FIRST = {"question": 0, "security": 1}
@@ -57,55 +55,6 @@ class Ranked:
notes: list[str]
def rank_file(todo: pathlib.Path) -> Ranked | Failure:
"""Rank todo in place: rank what read_all reads, write todo where that changed it, and print the notes and under-bar lines on stderr."""
texts = read_all(todo)
if isinstance(texts, Failure):
return texts
ranked = rank(*texts)
if isinstance(ranked, Failure):
return ranked
if ranked.text != texts[0] and (unwritten := write(todo, ranked.text)):
return unwritten
for line in ranked.notes + ranked.under_bar:
print(f"{todo}: {line}", file=sys.stderr)
return ranked
def check_failures(todo: pathlib.Path) -> list[str]:
"""Why --check fails on todo, empty when it passes."""
texts = read_all(todo)
if isinstance(texts, Failure):
return [texts.reason]
ranked = rank(*texts)
if isinstance(ranked, Failure):
return [ranked.reason]
unranked = [] if ranked.text == texts[0] else [f"{todo}: not ranked; run rank_todo.py on it"]
return unranked + [f"{todo}: {line}" for line in ranked.under_bar]
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."""
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:
texts.append(path.read_text(encoding="utf-8"))
except FileNotFoundError:
if missing:
return Failure(f"{path}: not found; {missing}")
texts.append("")
except OSError as failure:
return Failure(f"{path}: {failure.strerror}")
except UnicodeDecodeError:
return Failure(f"{path}: not UTF-8")
return texts[0], texts[1], texts[2], texts[3]
def write(path: pathlib.Path, text: str) -> Failure | None:
unwritten = replace_file(path.resolve(), text.encode("utf-8"))
return Failure(f"{path}: {unwritten.reason}") if unwritten else None
def rank(text: str, readme: str, decisions: str, history: str) -> Ranked | Failure:
lines = text.split("\n")
table = read_table(lines)
@@ -156,16 +105,6 @@ def notes(items: list[Item], scoring: Scoring) -> list[str]:
return unweighed + dropped
def blocked_through(id_: int, items: list[Item]) -> set[int]:
"""The IDs of the items id_ blocks, and of those they block in turn."""
found: set[int] = set()
reached = {id_}
while reached:
reached = {other.id for other in items if reached.intersection(other.blocked_by)} - found
found |= reached
return found
def ordered(items: list[Item], scoring: Scoring) -> list[tuple[Item, float]] | Failure:
"""Each item with its score, by release, then questions and security findings first, then by score from highest, then by ID; then each blocker above every item it blocks."""
by_score = []
@@ -298,42 +237,6 @@ def outside_items(lines: list[str], table: Table) -> Failure | None:
return None
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."""
held = {item.id: (item, value) for item, value in scored}
position = {item.id: index for index, (item, _) in enumerate(scored)}
for item, _ in scored:
for blocker in item.blocked_by:
if blocker in held and held[blocker][0].release > item.release:
later, earlier = version(held[blocker][0].release), version(item.release)
return Failure(f"item {item.id}, in release {earlier}, is blocked by item {blocker}, in later release {later}; move item {blocker} to release {earlier} or earlier, or item {item.id} to release {later} or later")
if loop := blocking_loop(held):
return Failure(f"items {', '.join(map(str, loop[:-1]))} and {loop[-1]} block each other in a loop; drop one of the blockers")
placed: set[int] = set()
return [entry for item, _ in scored for entry in place(item.id, held, position, placed)]
def blocking_loop(held: dict[int, tuple[Item, float]]) -> list[int] | None:
"""The IDs of items that block each other in a loop, sorted; None where there is no loop."""
graph = {id_: {blocker for blocker in item.blocked_by if blocker in held} for id_, (item, _) in held.items()}
try:
graphlib.TopologicalSorter(graph).prepare()
except graphlib.CycleError as cycle:
return sorted(set(cycle.args[1]))
return 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."""
if id_ in placed:
return []
placed.add(id_)
item, value = held[id_]
blockers = sorted((blocker for blocker in set(item.blocked_by) if blocker in held), key=position.__getitem__)
before = [entry for blocker in blockers for entry in place(blocker, held, position, placed)]
return [*before, (dataclasses.replace(item, blocked_by=tuple(sorted(blockers))), value)]
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."""
cited = set(cited_items(decisions))
@@ -390,61 +293,6 @@ def stated(text: str, name: str) -> str | Failure:
return found[0]
def parse_formula(source: str | Failure, variables: tuple[str, ...]) -> ast.Expression | Failure:
if isinstance(source, Failure):
return source
# Deep nesting makes the parser itself run out of memory before LARGEST_FORMULA can count the parts.
if len(source) > LONGEST_FORMULA:
return Failure(f"the formula {source[:40]!r}... holds more than {LONGEST_FORMULA} characters")
try:
tree = ast.parse(source, mode="eval")
except (SyntaxError, ValueError):
return Failure(f"the formula {source!r} does not parse")
nodes = list(ast.walk(tree))
if len(nodes) > LARGEST_FORMULA:
return Failure(f"the formula {source!r} holds more than {LARGEST_FORMULA} parts")
for node in nodes:
numeric = isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool) and abs(node.value) < 1e300
if not (isinstance(node, OPERATORS) or numeric or (isinstance(node, ast.Name) and node.id in variables)):
return Failure(f"the formula {source!r} may hold only numbers, {', '.join(variables)}, + - * / ** and parentheses")
return tree
def evaluate(node: ast.AST, values: dict[str, float]) -> float:
"""Evaluates a tree parse_formula accepted; a division by zero, and a power that overflows or has no real value, give nan."""
match node:
case ast.Expression(body):
return evaluate(body, values)
case ast.Constant(value) if isinstance(value, (int, float)):
return float(value)
case ast.Name(name):
return values[name]
case ast.UnaryOp(ast.USub(), operand):
return -evaluate(operand, values)
case ast.UnaryOp(ast.UAdd(), operand):
return evaluate(operand, values)
case ast.BinOp(left, ast.Add(), right):
return evaluate(left, values) + evaluate(right, values)
case ast.BinOp(left, ast.Sub(), right):
return evaluate(left, values) - evaluate(right, values)
case ast.BinOp(left, ast.Mult(), right):
return evaluate(left, values) * evaluate(right, values)
case ast.BinOp(left, ast.Div(), right):
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
try:
return math.pow(base, exponent)
except (OverflowError, ValueError):
return math.nan
return math.nan
def goal_term(shape: Shape) -> str:
"""The name of the formula's goal term, which score builds: W in OLD_SHAPE, V in the current shape."""
return "W" if shape is OLD_SHAPE else "V"
+2 -2
View File
@@ -45,9 +45,9 @@ def dated_heading_pattern(release: Release) -> str:
return "^## " + re.escape(version(release)) + " - " + "-".join("[0-9]" * digits for digits in DATE_DIGITS) + "$"
def newest_tag(cwd: str | None = None, merged_into: str | None = None) -> str | None | Failure:
def newest_tag(cwd: str | None = None, merged_into: str | None = None, run: git_repo.Git = git_repo.git) -> str | None | Failure:
"""The newest `v*` tag, read in cwd, else in the current directory, and merged into merged_into where it is given; None when there is none."""
# Sorts v1.0.0-rc.1 below v1.0.0.
merged = ["--merged", merged_into] if merged_into else []
tags = git_repo.git("-c", "versionsort.suffix=-", "tag", "--list", "v*", *merged, "--sort=-v:refname", cwd=cwd)
tags = run("-c", "versionsort.suffix=-", "tag", "--list", "v*", *merged, "--sort=-v:refname", cwd=cwd)
return tags if isinstance(tags, Failure) else next(iter(tags.split()), None)
+16 -16
View File
@@ -1,7 +1,7 @@
"""How the plan stands to the last release cut: the next release, whether work has landed towards it, and whether it is to be planned, reviewed or cut; and, from that standing, the item the next chunk takes first, with what the default branch holds for the pick."""
import dataclasses
from git_cli.git_repo import commits_since, file_at, git
from git_cli.git_repo import commits_since, file_at, git, Git
from release_plan.release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged
from failure import Failure
from release_plan.todo_table import Item, items, next_item, renames
@@ -90,46 +90,46 @@ class DefaultPlan:
cut: LastCut
def default_plan(root: str, ref: str) -> DefaultPlan:
"""What ref, the default branch as last fetched, holds for the pick, read in the checkout at root."""
tag = newest_tag(root, merged_into=ref)
changelog = file_at(ref, "CHANGELOG.md", root)
def default_plan(root: str, ref: str, run: Git = git) -> DefaultPlan:
"""What ref, the default branch as last fetched, holds for the pick, read in the checkout at root through run."""
tag = newest_tag(root, merged_into=ref, run=run)
changelog = file_at(ref, "CHANGELOG.md", root, run)
after = dated_cut(tag, changelog)
since = tag if after is None else heading_commit(after, ref, root)
commits = since if isinstance(since, Failure) else commits_since(since, ref, root)
reviewed = tag if isinstance(tag, Failure) else release_reviewed(tag, ref, root, after)
return DefaultPlan(file_at(ref, "todo.md", root), LastCut(tag, changelog, commits, todos_since(tag, ref, root), reviewed))
since = tag if after is None else heading_commit(after, ref, root, run)
commits = since if isinstance(since, Failure) else commits_since(since, ref, root, run)
reviewed = tag if isinstance(tag, Failure) else release_reviewed(tag, ref, root, after, run)
return DefaultPlan(file_at(ref, "todo.md", root, run), LastCut(tag, changelog, commits, todos_since(tag, ref, root, run), reviewed))
def heading_commit(release: Release, ref: str, cwd: str) -> str | None | Failure:
def heading_commit(release: Release, ref: str, cwd: str, run: Git = git) -> str | None | Failure:
"""The oldest commit on ref that added release's dated heading to CHANGELOG.md, which a branch with no tag counts the unreleased commits from; None where git finds none."""
# -G matches the heading line itself, so a changelog entry that quotes the heading doesn't count.
added = git("log", "--reverse", "--format=%H", "-G", dated_heading_pattern(release), ref, "--", "CHANGELOG.md", cwd=cwd)
added = run("log", "--reverse", "--format=%H", "-G", dated_heading_pattern(release), ref, "--", "CHANGELOG.md", cwd=cwd)
return added if isinstance(added, Failure) else next(iter(added.split()), None)
def release_reviewed(tag: str | None, ref: str, cwd: str, after: Release | None = None) -> bool | Failure:
def release_reviewed(tag: str | None, ref: str, cwd: str, after: Release | None = None, run: Git = git) -> bool | Failure:
"""Whether ref holds a commit titled as a release review opens, `Release review of <release>`: after tag, or anywhere where tag is None.
after is the version a branch with no tag counts as cut, or None. Where it is given, a title counts only where its release is later than after.
"""
titles = git("log", "--format=%s", f"{tag}..{ref}" if tag else ref, cwd=cwd)
titles = run("log", "--format=%s", f"{tag}..{ref}" if tag else ref, cwd=cwd)
if isinstance(titles, Failure):
return titles
reviews = [title.removeprefix("Release review of ") for title in titles.splitlines() if title.startswith("Release review of ")]
return any(after is None or ((named := parsed(review)) is not None and named > after) for review in reviews)
def todos_since(tag: str | None | Failure, ref: str, cwd: str) -> list[str] | Failure:
def todos_since(tag: str | None | Failure, ref: str, cwd: str, run: Git = git) -> list[str] | Failure:
"""LastCut.todos_since, read from ref in cwd. A pull request's own commits do not count, only the merge that landed it: --first-parent."""
if isinstance(tag, Failure):
return []
changed = git("log", "--first-parent", "--reverse", "--format=%H", f"{tag}..{ref}" if tag else ref, "--", "todo.md", cwd=cwd)
changed = run("log", "--first-parent", "--reverse", "--format=%H", f"{tag}..{ref}" if tag else ref, "--", "todo.md", cwd=cwd)
if isinstance(changed, Failure):
return changed
texts = []
for commit in [*([tag] if tag else []), *changed.split()]:
text = file_at(commit, "todo.md", cwd)
text = file_at(commit, "todo.md", cwd, run)
if isinstance(text, Failure):
return text
texts.append(text)
+115
View File
@@ -0,0 +1,115 @@
import pathlib
import re
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from release_plan.test_ranking import DECISIONS, README, TODO
from failure import Failure
from release_plan import ranking, todo_table
class Blockers(unittest.TestCase):
def ranked(self, todo):
return ranking.rank(todo, README, DECISIONS, "")
def test_ranks_each_blocker_just_above_the_first_item_it_blocks(self):
ranked = self.ranked(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5, 2 |"))
self.assertIn("""| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 3 | 3 | 5 | 9 | 2 | 2.1 by 1 | 12.3 |
| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 | 3.1 |
| 5 | 0.1.0 | | decision | **Move the writes out.** | 1 | 1 | 4 | 5 | 5 | 2.1 by 1 | 1.5 |
| 3 | 0.1.0 | 2, 5 | | **Make it fast, `a \\| b`.** | 2 | 1 | 2 | 3 | 7 | 2.1 by 8, 1 by 6 | 5.5 |
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 228.4 |
""", ranked.text)
self.assertEqual(self.ranked(ranked.text), ranked)
def test_ranks_an_items_blockers_in_score_order(self):
rows = [line.split(" | ")[0] for line in self.ranked(TODO.replace("| 4 | 0.1.0 | |", "| 4 | 0.1.0 | 2, 3 |")).text.splitlines() if re.match(r"\| \d \| 0\.\d\.0 \|", line)]
self.assertEqual(rows, ["| 3", "| 2", "| 4", "| 5", "| 1"])
def test_ranks_a_blocker_above_its_blockers_blocker_and_takes_one_in_an_earlier_release_as_it_is(self):
chained = TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5 |").replace("| 5 | 0.1.0 | |", "| 5 | 0.1.0 | 2 |").replace("| 1 | 0.2.0 | |", "| 1 | 0.2.0 | 3 |")
rows = [line.split(" | ")[0] for line in self.ranked(chained).text.splitlines() if re.match(r"\| \d \| 0\.\d\.0 \|", line)]
self.assertEqual(rows, ["| 4", "| 2", "| 5", "| 3", "| 1"])
def test_bundles_with_the_next_item_each_item_of_its_release_that_no_question_or_item_outside_the_chunk_blocks(self):
# Item 2 is the next item. Item 5 is a question, 3 waits on 5, and 4 waits on 3; item 1 is in a later release.
waits = todo_table.items(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5 |").replace("| 4 | 0.1.0 | | security |", "| 4 | 0.1.0 | 3 | security |").replace("| 5 | 0.1.0 | | decision |", "| 5 | 0.1.0 | | question |"))
self.assertEqual(todo_table.bundle_candidates(waits, todo_table.next_item(waits)), [])
answered = todo_table.items(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5 |").replace("| 4 | 0.1.0 | | security |", "| 4 | 0.1.0 | 3 | security |"))
self.assertEqual([item.id for item in todo_table.bundle_candidates(answered, todo_table.next_item(answered))], [3, 5])
def test_ships_an_item_above_r_5_alone(self):
# Item 4 has R 9: it joins no chunk, and none joins it. Item 5, at R 5, still joins.
found = todo_table.items(TODO)
self.assertNotIn(4, [item.id for item in todo_table.bundle_candidates(found, todo_table.next_item(found))])
self.assertIn(5, [item.id for item in todo_table.bundle_candidates(found, todo_table.next_item(found))])
self.assertEqual(todo_table.bundle_candidates(found, next(item for item in found if item.id == 4)), [])
# At R 6, item 3 ships alone too.
riskier = todo_table.items(TODO.replace("| 2 | 1 | 2 | 3 | 7 |", "| 3 | 2 | 3 | 6 | 7 |"))
self.assertNotIn(3, [item.id for item in todo_table.bundle_candidates(riskier, todo_table.next_item(riskier))])
# Before rank_todo.py fills its R cell, item 3's L 3, E 2 and I 3 still make R 6.
unranked = todo_table.items(TODO.replace("| 2 | 1 | 2 | 3 | 7 |", "| 3 | 2 | 3 | | 7 |"))
self.assertNotIn(3, [item.id for item in todo_table.bundle_candidates(unranked, todo_table.next_item(unranked))])
def test_drops_a_blocker_the_table_no_longer_holds_as_finished(self):
finished = TODO.replace("| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 3 | 3 | 5 | 9 | 2 | 2.1 by 1 | 0 |\n", "").replace("| 2 | 0.1.0 | |", "| 2 | 0.1.0 | 4 |")
ranked = self.ranked(finished)
self.assertIn("| 2 | 0.1.0 | | | **Tighten the tests.**", ranked.text)
self.assertEqual(ranked.notes, ["item 2: dropped 4 from its Blocked by; the table no longer holds it"])
self.assertEqual(self.ranked(ranked.text).notes, [])
def test_refuses_a_blocker_in_a_later_release_a_loop_and_an_id_past_next_id(self):
cases = {
"| 3 | 0.1.0 | 1 |": "item 3, in release 0.1.0, is blocked by item 1, in later release 0.2.0; move item 1 to release 0.1.0 or earlier, or item 3 to release 0.2.0 or later",
"| 3 | 0.1.0 | 3 |": "item 3 is blocked by itself; drop 3 from its Blocked by",
"| 3 | 0.1.0 | 9 |": "item 3 is blocked by item 9, which is not under Next ID 6; name an item the table holds or held",
"| 3 | 0.1.0 | 6 |": "item 3 is blocked by item 6, which is not under Next ID 6; name an item the table holds or held",
}
for cell, reason in cases.items():
with self.subTest(cell=cell):
self.assertEqual(self.ranked(TODO.replace("| 3 | 0.1.0 | |", cell)), Failure(reason))
looped = TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 2 |").replace("| 2 | 0.1.0 | |", "| 2 | 0.1.0 | 5 |").replace("| 5 | 0.1.0 | |", "| 5 | 0.1.0 | 3 |")
self.assertEqual(self.ranked(looped), Failure("items 2, 3 and 5 block each other in a loop; drop one of the blockers"))
self.assertEqual(self.ranked(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 2 and 5 |")), Failure("item 3's Blocked by '2 and 5' is not empty or IDs separated by \", \""))
def test_adds_the_column_to_a_table_without_it(self):
without = TODO.replace("| Blocked by ", "").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|")
without = re.sub(r"\| (\d) \| (0\.[12]\.0) \| \| ", r"| \1 | \2 | ", without)
self.assertEqual(self.ranked(without), self.ranked(TODO))
unscored = TODO.replace(" | Score |", " |").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|").replace(" | 0 |\n", " |\n")
self.assertEqual(self.ranked(unscored), self.ranked(TODO))
def test_refuses_a_column_it_does_not_know_rather_than_drop_it_and_one_an_older_shape_held(self):
extra = TODO.replace("| Moves | Score |\n|---|", "| Moves | Score | Later |\n|---|---|").replace(" | 0 |\n", " | 0 | x |\n")
self.assertEqual(self.ranked(extra), Failure("todo.md's items table has the column Later, which this rank_todo.py does not know; the columns it knows are ID, Release, Blocked by, Exempt, Item, L, E, I, R, S, Moves, Score. Rename it, or move this machine to the release that added it"))
self.assertEqual([item.id for item in todo_table.items(extra)], [1, 2, 3, 4, 5])
with_c = TODO.replace("| S | Moves |", "| S | C | Moves |").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|---|---|")
with_c = re.sub(r"(\*\* \| \d+ \| \d+ \| \d+ \| \d+ \| \d+) \|", r"\1 | 3 |", with_c)
self.assertEqual(self.ranked(with_c), Failure("todo.md's items table has C, a column of an older shape; drop it, as rank_todo.py --help shows"))
def test_refuses_text_under_items_beside_the_table(self):
last = TODO.split("\n## Details")[0] + "\n"
self.assertIsInstance(self.ranked(last), ranking.Ranked)
beside = Failure("## Items holds text beside its table; an order goes in the scores or the Blocked by column, and a note in the item's detail")
for ordered in (TODO.replace("## Items\n\n", "## Items\n\nRelease 0.1.0 takes item 5 first.\n\n"), TODO.replace("## Items\n\n", "## Items\nTake item 5 first.\n\n"), TODO.replace("| 2.1 by 1 | 0 |\n\n## Details", "| 2.1 by 1 | 0 |\n\nTake item 5 first.\n\n## Details"), last + "\nTake item 5 first.\n"):
with self.subTest(ordered=ordered[-60:]):
self.assertEqual(self.ranked(ordered), beside)
def test_refuses_an_items_table_outside_items_a_second_one_and_a_repeated_column(self):
self.assertEqual(self.ranked(TODO.replace("## Items\n", "## Plan\n")).reason, "todo.md is not in the scored-table format; rank_todo.py --help shows a valid one")
outside = TODO.replace("## Items\n\n", "## Items\n\n## Rows\n\n")
self.assertEqual(self.ranked(outside).reason, "the items table sits under ## Rows, not ## Items; move it under ## Items")
table = TODO[TODO.index("| ID | Release |"):TODO.index("\n\n## Details")] + "\n"
above = table + "\n" + TODO.replace(table, "")
self.assertEqual(self.ranked(above).reason, "the items table sits under no ## heading; move it under ## Items")
header = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
self.assertEqual(todo_table.items(TODO + "\n" + header.replace("| Score |", "| Later |")), Failure("todo.md holds 2 tables whose header opens | ID | Release |; keep one items table"))
repeated = TODO.replace("| Moves | Score |\n|---|", "| Moves | Score | Exempt |\n|---|---|").replace(" | 0 |\n", " | 0 | x |\n")
self.assertEqual(todo_table.items(repeated), Failure("todo.md's items table names the column Exempt twice; keep one"))
def test_reads_an_empty_table_and_fails_on_a_header_with_no_divider(self):
header = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |"
self.assertEqual(todo_table.items(f"## Items\n\n{header}\n|---|---|---|---|---|---|---|---|---|---|---|---|\n\n## Details\n"), [])
self.assertEqual(todo_table.items(f"## Items\n\n{header}"), Failure(f"the table under {header} has no |---| divider line"))
+24
View File
@@ -0,0 +1,24 @@
import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from release_plan.test_ranking import DECISIONS, README, TODO
from failure import Failure
from release_plan import ranking
class Formula(unittest.TestCase):
def ranked(self, todo):
return ranking.rank(todo, README, DECISIONS, "")
def test_refuses_a_formula_that_is_more_than_arithmetic_over_the_scores(self):
for formula in ("__import__('os')", "R.real", "X + 1", "C + 1", "A + V", "G + V", "W * V", "R ^ 2", "R +", "R / (S - 2)", "R\x00", "1" * 400, " + ".join(["R"] * 300), "-" * 100000 + "R", "10 ** 10 ** 10", "(-8) ** (1 / 3)", "0 ** -1"):
with self.subTest(formula=formula):
self.assertIsInstance(self.ranked(TODO.replace("100 * V / 2**S", formula)), Failure)
self.assertIn("| 1 by 9 | 2.0 |", self.ranked(TODO.replace("100 * V / 2**S", "R + S / S")).text)
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "1 ** (1 / (S - S))")), Failure("the formula gives item 1 no finite score"))
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "(1 / (S - S)) ** 0")), Failure("the formula gives item 1 no finite score"))
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "W")), Failure("the formula 'W' may hold only numbers, E, I, L, R, S, V, + - * / ** and parentheses"))
self.assertEqual(self.ranked(TODO.replace("2.1 by 8, 1 by 6", "2.1: 8, 1: 6")), Failure("item 3's Moves '2.1: 8, 1: 6' is not empty or goals such as `1.1 by 8, code health by 5`, each moved by a whole number from 1 to 10"))
+2 -117
View File
@@ -9,7 +9,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
from release_plan import ranking
from release_plan import plan_file, ranking
from repo_checks import ROOT
from release_plan import todo_table
@@ -207,16 +207,6 @@ class Rank(unittest.TestCase):
weighted = TODO.replace("## Items\n", "| Goal | W |\n|---|---|\n| 1 | 1.00 |\n\n## Items\n")
self.assertEqual(self.ranked(weighted), Failure("todo.md holds a goal weights table beside a Moves column; drop the table, since rank_todo.py weighs the goals itself, as its --help says"))
def test_refuses_a_formula_that_is_more_than_arithmetic_over_the_scores(self):
for formula in ("__import__('os')", "R.real", "X + 1", "C + 1", "A + V", "G + V", "W * V", "R ^ 2", "R +", "R / (S - 2)", "R\x00", "1" * 400, " + ".join(["R"] * 300), "-" * 100000 + "R", "10 ** 10 ** 10", "(-8) ** (1 / 3)", "0 ** -1"):
with self.subTest(formula=formula):
self.assertIsInstance(self.ranked(TODO.replace("100 * V / 2**S", formula)), Failure)
self.assertIn("| 1 by 9 | 2.0 |", self.ranked(TODO.replace("100 * V / 2**S", "R + S / S")).text)
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "1 ** (1 / (S - S))")), Failure("the formula gives item 1 no finite score"))
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "(1 / (S - S)) ** 0")), Failure("the formula gives item 1 no finite score"))
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "W")), Failure("the formula 'W' may hold only numbers, E, I, L, R, S, V, + - * / ** and parentheses"))
self.assertEqual(self.ranked(TODO.replace("2.1 by 8, 1 by 6", "2.1: 8, 1: 6")), Failure("item 3's Moves '2.1: 8, 1: 6' is not empty or goals such as `1.1 by 8, code health by 5`, each moved by a whole number from 1 to 10"))
def test_refuses_a_file_off_the_format(self):
row = "| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 | 0 |"
broken = {
@@ -351,7 +341,7 @@ class CodeHealth(unittest.TestCase):
pathlib.Path(temp, "docs").mkdir()
pathlib.Path(temp, "docs", "comprehension-history.md").write_text(SCORED.format(overall="7.00"))
with contextlib.redirect_stderr(io.StringIO()):
ranked = ranking.rank_file(todo)
ranked = plan_file.rank_file(todo)
self.assertIsInstance(ranked, ranking.Ranked)
self.assertEqual(ranked.under_bar, [])
self.assertIn("| code health by 1 | 25.4 |", todo.read_text())
@@ -451,111 +441,6 @@ class OldShape(unittest.TestCase):
self.assertEqual(self.ranked(OLD_SHAPE.replace("| G | Goals |", "| G | Goal |")), Failure("todo.md's items table has no Goals column; rank_todo.py --help shows a valid one"))
class Blockers(unittest.TestCase):
def ranked(self, todo):
return ranking.rank(todo, README, DECISIONS, "")
def test_ranks_each_blocker_just_above_the_first_item_it_blocks(self):
ranked = self.ranked(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5, 2 |"))
self.assertIn("""| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 3 | 3 | 5 | 9 | 2 | 2.1 by 1 | 12.3 |
| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 | 3.1 |
| 5 | 0.1.0 | | decision | **Move the writes out.** | 1 | 1 | 4 | 5 | 5 | 2.1 by 1 | 1.5 |
| 3 | 0.1.0 | 2, 5 | | **Make it fast, `a \\| b`.** | 2 | 1 | 2 | 3 | 7 | 2.1 by 8, 1 by 6 | 5.5 |
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 228.4 |
""", ranked.text)
self.assertEqual(self.ranked(ranked.text), ranked)
def test_ranks_an_items_blockers_in_score_order(self):
rows = [line.split(" | ")[0] for line in self.ranked(TODO.replace("| 4 | 0.1.0 | |", "| 4 | 0.1.0 | 2, 3 |")).text.splitlines() if re.match(r"\| \d \| 0\.\d\.0 \|", line)]
self.assertEqual(rows, ["| 3", "| 2", "| 4", "| 5", "| 1"])
def test_ranks_a_blocker_above_its_blockers_blocker_and_takes_one_in_an_earlier_release_as_it_is(self):
chained = TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5 |").replace("| 5 | 0.1.0 | |", "| 5 | 0.1.0 | 2 |").replace("| 1 | 0.2.0 | |", "| 1 | 0.2.0 | 3 |")
rows = [line.split(" | ")[0] for line in self.ranked(chained).text.splitlines() if re.match(r"\| \d \| 0\.\d\.0 \|", line)]
self.assertEqual(rows, ["| 4", "| 2", "| 5", "| 3", "| 1"])
def test_bundles_with_the_next_item_each_item_of_its_release_that_no_question_or_item_outside_the_chunk_blocks(self):
# Item 2 is the next item. Item 5 is a question, 3 waits on 5, and 4 waits on 3; item 1 is in a later release.
waits = todo_table.items(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5 |").replace("| 4 | 0.1.0 | | security |", "| 4 | 0.1.0 | 3 | security |").replace("| 5 | 0.1.0 | | decision |", "| 5 | 0.1.0 | | question |"))
self.assertEqual(todo_table.bundle_candidates(waits, todo_table.next_item(waits)), [])
answered = todo_table.items(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5 |").replace("| 4 | 0.1.0 | | security |", "| 4 | 0.1.0 | 3 | security |"))
self.assertEqual([item.id for item in todo_table.bundle_candidates(answered, todo_table.next_item(answered))], [3, 5])
def test_ships_an_item_above_r_5_alone(self):
# Item 4 has R 9: it joins no chunk, and none joins it. Item 5, at R 5, still joins.
found = todo_table.items(TODO)
self.assertNotIn(4, [item.id for item in todo_table.bundle_candidates(found, todo_table.next_item(found))])
self.assertIn(5, [item.id for item in todo_table.bundle_candidates(found, todo_table.next_item(found))])
self.assertEqual(todo_table.bundle_candidates(found, next(item for item in found if item.id == 4)), [])
# At R 6, item 3 ships alone too.
riskier = todo_table.items(TODO.replace("| 2 | 1 | 2 | 3 | 7 |", "| 3 | 2 | 3 | 6 | 7 |"))
self.assertNotIn(3, [item.id for item in todo_table.bundle_candidates(riskier, todo_table.next_item(riskier))])
# Before rank_todo.py fills its R cell, item 3's L 3, E 2 and I 3 still make R 6.
unranked = todo_table.items(TODO.replace("| 2 | 1 | 2 | 3 | 7 |", "| 3 | 2 | 3 | | 7 |"))
self.assertNotIn(3, [item.id for item in todo_table.bundle_candidates(unranked, todo_table.next_item(unranked))])
def test_drops_a_blocker_the_table_no_longer_holds_as_finished(self):
finished = TODO.replace("| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 3 | 3 | 5 | 9 | 2 | 2.1 by 1 | 0 |\n", "").replace("| 2 | 0.1.0 | |", "| 2 | 0.1.0 | 4 |")
ranked = self.ranked(finished)
self.assertIn("| 2 | 0.1.0 | | | **Tighten the tests.**", ranked.text)
self.assertEqual(ranked.notes, ["item 2: dropped 4 from its Blocked by; the table no longer holds it"])
self.assertEqual(self.ranked(ranked.text).notes, [])
def test_refuses_a_blocker_in_a_later_release_a_loop_and_an_id_past_next_id(self):
cases = {
"| 3 | 0.1.0 | 1 |": "item 3, in release 0.1.0, is blocked by item 1, in later release 0.2.0; move item 1 to release 0.1.0 or earlier, or item 3 to release 0.2.0 or later",
"| 3 | 0.1.0 | 3 |": "item 3 is blocked by itself; drop 3 from its Blocked by",
"| 3 | 0.1.0 | 9 |": "item 3 is blocked by item 9, which is not under Next ID 6; name an item the table holds or held",
"| 3 | 0.1.0 | 6 |": "item 3 is blocked by item 6, which is not under Next ID 6; name an item the table holds or held",
}
for cell, reason in cases.items():
with self.subTest(cell=cell):
self.assertEqual(self.ranked(TODO.replace("| 3 | 0.1.0 | |", cell)), Failure(reason))
looped = TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 2 |").replace("| 2 | 0.1.0 | |", "| 2 | 0.1.0 | 5 |").replace("| 5 | 0.1.0 | |", "| 5 | 0.1.0 | 3 |")
self.assertEqual(self.ranked(looped), Failure("items 2, 3 and 5 block each other in a loop; drop one of the blockers"))
self.assertEqual(self.ranked(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 2 and 5 |")), Failure("item 3's Blocked by '2 and 5' is not empty or IDs separated by \", \""))
def test_adds_the_column_to_a_table_without_it(self):
without = TODO.replace("| Blocked by ", "").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|")
without = re.sub(r"\| (\d) \| (0\.[12]\.0) \| \| ", r"| \1 | \2 | ", without)
self.assertEqual(self.ranked(without), self.ranked(TODO))
unscored = TODO.replace(" | Score |", " |").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|").replace(" | 0 |\n", " |\n")
self.assertEqual(self.ranked(unscored), self.ranked(TODO))
def test_refuses_a_column_it_does_not_know_rather_than_drop_it_and_one_an_older_shape_held(self):
extra = TODO.replace("| Moves | Score |\n|---|", "| Moves | Score | Later |\n|---|---|").replace(" | 0 |\n", " | 0 | x |\n")
self.assertEqual(self.ranked(extra), Failure("todo.md's items table has the column Later, which this rank_todo.py does not know; the columns it knows are ID, Release, Blocked by, Exempt, Item, L, E, I, R, S, Moves, Score. Rename it, or move this machine to the release that added it"))
self.assertEqual([item.id for item in todo_table.items(extra)], [1, 2, 3, 4, 5])
with_c = TODO.replace("| S | Moves |", "| S | C | Moves |").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|---|---|")
with_c = re.sub(r"(\*\* \| \d+ \| \d+ \| \d+ \| \d+ \| \d+) \|", r"\1 | 3 |", with_c)
self.assertEqual(self.ranked(with_c), Failure("todo.md's items table has C, a column of an older shape; drop it, as rank_todo.py --help shows"))
def test_refuses_text_under_items_beside_the_table(self):
last = TODO.split("\n## Details")[0] + "\n"
self.assertIsInstance(self.ranked(last), ranking.Ranked)
beside = Failure("## Items holds text beside its table; an order goes in the scores or the Blocked by column, and a note in the item's detail")
for ordered in (TODO.replace("## Items\n\n", "## Items\n\nRelease 0.1.0 takes item 5 first.\n\n"), TODO.replace("## Items\n\n", "## Items\nTake item 5 first.\n\n"), TODO.replace("| 2.1 by 1 | 0 |\n\n## Details", "| 2.1 by 1 | 0 |\n\nTake item 5 first.\n\n## Details"), last + "\nTake item 5 first.\n"):
with self.subTest(ordered=ordered[-60:]):
self.assertEqual(self.ranked(ordered), beside)
def test_refuses_an_items_table_outside_items_a_second_one_and_a_repeated_column(self):
self.assertEqual(self.ranked(TODO.replace("## Items\n", "## Plan\n")).reason, "todo.md is not in the scored-table format; rank_todo.py --help shows a valid one")
outside = TODO.replace("## Items\n\n", "## Items\n\n## Rows\n\n")
self.assertEqual(self.ranked(outside).reason, "the items table sits under ## Rows, not ## Items; move it under ## Items")
table = TODO[TODO.index("| ID | Release |"):TODO.index("\n\n## Details")] + "\n"
above = table + "\n" + TODO.replace(table, "")
self.assertEqual(self.ranked(above).reason, "the items table sits under no ## heading; move it under ## Items")
header = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
self.assertEqual(todo_table.items(TODO + "\n" + header.replace("| Score |", "| Later |")), Failure("todo.md holds 2 tables whose header opens | ID | Release |; keep one items table"))
repeated = TODO.replace("| Moves | Score |\n|---|", "| Moves | Score | Exempt |\n|---|---|").replace(" | 0 |\n", " | 0 | x |\n")
self.assertEqual(todo_table.items(repeated), Failure("todo.md's items table names the column Exempt twice; keep one"))
def test_reads_an_empty_table_and_fails_on_a_header_with_no_divider(self):
header = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |"
self.assertEqual(todo_table.items(f"## Items\n\n{header}\n|---|---|---|---|---|---|---|---|---|---|---|---|\n\n## Details\n"), [])
self.assertEqual(todo_table.items(f"## Items\n\n{header}"), Failure(f"the table under {header} has no |---| divider line"))
class Renamed(unittest.TestCase):
def test_reads_the_releases_the_renamed_section_names(self):
self.assertEqual(todo_table.renames("## Items\n\n## Details\n"), set())
+1 -1
View File
@@ -6,6 +6,6 @@ import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from review_replay import main
from loop_claude.effects import system_effects
from loop_effects.effects import system_effects
sys.exit(main.main(sys.argv[1:], os.environ, pathlib.Path.home(), system_effects()))
+1 -1
View File
@@ -43,7 +43,7 @@ from rung_replay.command import arguments_or_exit, down_from, failed, limited_ex
from review_replay.rounds import authored_by, lost_inputs, report, reviewed_path, Round, round_from, sample, stamp_seconds
from transcript_archive.project_key import checkout_of
from claude_code.reply import claude_reply, Limited
from loop_claude.effects import Effects
from loop_effects.effects import Effects
from failure import Failure
from rung_replay.search import first_reply, replayed
from claude_code.transcript import first_timestamped_line, read_transcript
+1 -1
View File
@@ -15,7 +15,7 @@ import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from review_replay.rounds import authored_by, lost_inputs, recorded_findings, report, reviewed_path, Round, round_from, sample, stamp_seconds
from loop_claude.effects import Effects, system_effects
from loop_effects.effects import Effects, system_effects
from claude_code.entries import entry_from
from failure import Failure
from review_replay import main
+1 -4
View File
@@ -29,10 +29,7 @@ def reviewer_breaches(call: Call, environ: typing.Mapping[str, str]) -> list[Bre
kind = review_kind(call.given)
if kind is None or project is None or worker is None:
return []
required = review_rung(project, worker, escape_and_impact, kind)
# A branch that changes only Markdown no agent follows holds no code or config for a reviewer on a higher rung to catch a defect in: skills/larv-review/SKILL.md → "Markdown only".
if kind in REVIEWERS and position(required) > position(project) and markdown_only(call.cwd):
required = project
required = review_rung(project, worker, escape_and_impact, kind, markdown_only(call.cwd))
named = named_rung(call.given, worker)
if position(named) >= position(required):
return []
+2 -2
View File
@@ -6,7 +6,7 @@ import sys
from rule_hook.rules import Breach
from failure import Failure
from rule_hook.git import guarded_git
from release_plan import ranking
from release_plan import plan_file
# The checkout this hook runs from: bin/rule_hook/ sits two folders below it.
@@ -27,7 +27,7 @@ def check_failures(top: str, todo: pathlib.Path, own: pathlib.Path) -> list[str]
"""Why rank_todo.py --check fails on todo. A checkout of the repo the hook runs from checks with its own bin/rank_todo.py, so a branch that changes the table's shape is held to its own rules. Any other checkout checks with the hook's ranking: running its script would run its code before every commit."""
script = pathlib.Path(top) / "bin" / "rank_todo.py"
if not script.is_file() or not same_repo(top, own):
return ranking.check_failures(todo)
return plan_file.check_failures(todo)
try:
ran = subprocess.run([sys.executable, str(script), "--check", str(todo)], capture_output=True, cwd=top, text=True, timeout=OWN_CHECK_SECONDS)
except subprocess.TimeoutExpired:
+1 -1
View File
@@ -6,7 +6,7 @@ import typing
from failure import Failure
from model_routing.ladder import LADDER, position, Rung
from claude_code.reply import Limited
from loop_claude.paths import paths_from
from loop_state.paths import paths_from
from loop_claude.project.model_choice import read_models_file
# What a tool reads from its arguments, such as the project's rung of the model they name.
+8 -13
View File
@@ -30,7 +30,7 @@ import typing
from todo_item.edits import added, finished, with_bullet
from release_plan.todo_table import BLOCKED_BY, MOVES
from failure import Failure
from release_plan import ranking
from release_plan import plan_file, ranking
# Each score flag, as --l or --L, and the column it fills.
LETTERS = ("L", "E", "I", "S")
@@ -70,7 +70,7 @@ def parser() -> argparse.ArgumentParser:
def add(args: argparse.Namespace, folder: pathlib.Path, stdin: typing.TextIO) -> str | Failure:
todo = folder / "todo.md"
texts = ranking.read_all(todo)
texts = plan_file.read_all(todo)
if isinstance(texts, Failure):
return texts
named = {"Release": args.release, BLOCKED_BY: args.blocked_by, "Exempt": args.exempt, "Item": args.tagline, MOVES: args.moves}
@@ -84,9 +84,9 @@ def add(args: argparse.Namespace, folder: pathlib.Path, stdin: typing.TextIO) ->
return Failure(f"not filed: {ranked.reason}")
if under := [line for line in ranked.under_bar if line.startswith(f"item {id_} ")]:
return Failure(f"not filed: {under[0]}")
if unwritten := ranking.write(todo, ranked.text):
if unwritten := plan_file.write(todo, ranked.text):
return unwritten
report(todo, ranked)
plan_file.print_report(todo, ranked)
return f"Filed item {id_}."
@@ -96,11 +96,11 @@ def finish(args: argparse.Namespace, folder: pathlib.Path) -> str | Failure:
if isinstance(texts, Failure):
return Failure(f"not finished: {texts.reason}")
ranked, news = texts
if unwritten := ranking.write(todo, ranked.text):
if unwritten := plan_file.write(todo, ranked.text):
return Failure(f"not finished: {unwritten.reason}")
if news is not None and (unwritten := ranking.write(changelog, news)):
if news is not None and (unwritten := plan_file.write(changelog, news)):
return Failure(f"{unwritten.reason}; todo.md no longer holds item {args.id}, so add its bullet by hand")
report(todo, ranked)
plan_file.print_report(todo, ranked)
return f"Finished item {args.id}."
@@ -108,7 +108,7 @@ def finish_texts(args: argparse.Namespace, todo: pathlib.Path, changelog: pathli
"""What finish writes: todo ranked without item args.id, and changelog's new text, None where finish leaves it as is."""
if changelog.exists() and args.changelog is None and not args.no_changelog:
return Failure("CHANGELOG.md exists beside todo.md; pass --changelog <bullet>, or --no-changelog where the repo publishes nothing")
texts = ranking.read_all(todo)
texts = plan_file.read_all(todo)
if isinstance(texts, Failure):
return texts
text = finished(texts[0], args.id)
@@ -127,8 +127,3 @@ def finish_texts(args: argparse.Namespace, todo: pathlib.Path, changelog: pathli
return Failure(f"{changelog}: not UTF-8")
return news if isinstance(news, Failure) else (ranked, news)
def report(todo: pathlib.Path, ranked: ranking.Ranked) -> None:
"""Print ranking's notes and under-bar lines on stderr, each prefixed with todo.md's path, as rank_todo.py does."""
for line in ranked.notes + ranked.under_bar:
print(f"{todo}: {line}", file=sys.stderr)
+2 -2
View File
@@ -10,7 +10,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from release_plan.test_ranking import DECISIONS, README, TODO
from todo_item import edits, main
from failure import Failure
from release_plan import ranking
from release_plan import plan_file, ranking
ADD = ["add", "--release", "0.1.0", "--l", "1", "--e", "1", "--i", "1", "--s", "1", "--moves", "1 by 9", "Count the `a | b` runs."]
CHANGELOG = "# Changelog\n\n## Unreleased\n\n- Older news.\n\n## 0.1.0\n\n- First.\n"
@@ -50,7 +50,7 @@ class TodoItem(unittest.TestCase):
return raised.exception.code
def assert_ranked(self):
self.assertEqual(ranking.check_failures(self.todo), [])
self.assertEqual(plan_file.check_failures(self.todo), [])
def details(self):
text = self.todo.read_text()
+1 -1
View File
@@ -113,7 +113,7 @@ Valid while cache reads cost a twentieth of input and Claude Code's compaction k
## loop-inbox: a loop-claude lists itself while it runs, and its waiting question, as files per session under `~/.local/state/loop-claude/`, and takes the first answer, from its terminal or from loop-inbox, that names that question
2026-10-28, lilleman, todo item 243. Serves goal 1. With several loops running, each asked on its own terminal, and the human searched the terminals for the ones that waited. loop-inbox lists every loop's interrupts, the routing calls included, oldest first, and the human answers each one there. A loop asking for its project's model, as on a project's first run, asks on its terminal only: the human has just started it there, and no worker session exists yet. `bin/loop_claude/waiting/` holds the protocol:
2026-10-28, lilleman, todo item 243. Serves goal 1. With several loops running, each asked on its own terminal, and the human searched the terminals for the ones that waited. loop-inbox lists every loop's interrupts, the routing calls included, oldest first, and the human answers each one there. A loop asking for its project's model, as on a project's first run, asks on its terminal only: the human has just started it there, and no worker session exists yet. `bin/loop_state/waiting/` holds the protocol:
- An answer reaching the wrong loop is the worst failure. Each answer names the question it answers by a fresh id, so an answer meant for an earlier question, or sent as the terminal answered, never answers a later one.
- `/talk` from loop-inbox waits for the loop to stop reading its terminal before claude opens, so only one claude holds the worker's session.
- While claude is open for a question, as for a release ready to cut, the routing calls or a `/talk`, loop-inbox lists the loop and where claude is open, but takes no answer for it.
+1 -1
View File
@@ -8,7 +8,7 @@ from review_replay.rounds import lost_inputs, Round
from review_rules.review_folder import REPORTS, review_folder
from review_replay import main as rm
from model_routing.ladder import Rung
from loop_claude.effects import system_effects
from loop_effects.effects import system_effects
HERE = pathlib.Path(__file__).resolve().parent
HOME = pathlib.Path.home()
+1 -1
View File
@@ -240,7 +240,7 @@ The principles pass of PR #301 found that only `routed_by` in `bin/loop_claude/c
### 197. Let the human edit what they type at loop-claude's terminal questions with the arrow keys, so Left moves the cursor in place of printing `^[[D`.
`bin/loop_claude/effects.py` hands loop-claude Python's builtin `input`, and nothing under `bin/` imports `readline`, so the terminal gets no line editing: fixing a typo means erasing back to it. loop-claude asks two questions at its terminal. `effects.input` reads the pick of the project's model, in `project/model_choice.py`'s `ask_for_model`. `effects.input_or` reads the interrupt's answer, in `cycle/interrupt.py`'s `first_answer`, straight from stdin, since it also watches loop-inbox. Importing `readline` in `effects.py` gives `input` line editing, at two costs; `input_or` would also need to read through `input` while it watches. It moves the prompt from stderr to stdout, while the question above it stays on stderr. `test_black_box.py` waits for the prompt on stderr. `readline`'s bracketed paste takes a pasted block whole, so an answer can hold several lines. `prompts.typed_answer` ends the answer at its first blank line, so the judge would read the rest of such a paste as loop-claude's words. The product-owner review of PR #308 raised the interrupt's case. lilleman, 2026-10-18: "Not super-important, but a bit irritating."
`bin/loop_effects/effects.py` hands loop-claude Python's builtin `input`, and nothing under `bin/` imports `readline`, so the terminal gets no line editing: fixing a typo means erasing back to it. loop-claude asks two questions at its terminal. `effects.input` reads the pick of the project's model, in `project/model_choice.py`'s `ask_for_model`. `effects.input_or` reads the interrupt's answer, in `cycle/interrupt.py`'s `first_answer`, straight from stdin, since it also watches loop-inbox. Importing `readline` in `effects.py` gives `input` line editing, at two costs; `input_or` would also need to read through `input` while it watches. It moves the prompt from stderr to stdout, while the question above it stays on stderr. `test_black_box.py` waits for the prompt on stderr. `readline`'s bracketed paste takes a pasted block whole, so an answer can hold several lines. `prompts.typed_answer` ends the answer at its first blank line, so the judge would read the rest of such a paste as loop-claude's words. The product-owner review of PR #308 raised the interrupt's case. lilleman, 2026-10-18: "Not super-important, but a bit irritating."
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.