Merge pull request 'Move the next chunk's pick into one module, so git_repo only runs git and todo_table only parses the plan' (#316) from item-177 into main

This commit was merged in pull request #316.
This commit is contained in:
2026-10-18 11:10:19 +02:00
22 changed files with 413 additions and 300 deletions
+1
View File
@@ -18,6 +18,7 @@
!agents/*.md
!bin/
!bin/chunk-preflight
!bin/chunk_pick.py
!bin/chunk_preflight/
!bin/chunk_preflight/*.py
!bin/claude_code/
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- `chunk-preflight` names the release it finds finished and ready to cut, or to be planned first, wherever todo.md has named that release since the last cut.
- Each reviewer under `agents/` now writes its full report to a file that larv-review names in the reviewer's prompt, in a folder per chunk under `~/.local/state/larv-review/`. It returns only its verdict and one line per finding, so a review takes less of the worker's context. The worker reads a finding's full entry before it fixes or answers a 🔴 or 🟡. Each reviewer now holds Write. `rule-hook` refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`; no override waives this rule. Each chunk's folder stays after the merge, so `stability-replay` can replay a round that reads an earlier round's report. It replays on a copy of the folder.
- `loop-claude` asks an interrupt's question on its own terminal and resumes the worker headless with your one-line answer, so the loop no longer waits for you to leave a claude session. Type `/talk` instead to open the worker's session in claude, as every interrupt did before, to read the diff or discuss first. A release ready to cut opens that session at once. Pressing Enter on an empty answer stops the loop, exit 2. Keys typed before the question shows are dropped, and a pasted answer keeps only its first line; type `/talk` for a longer one. The judge counts that answer as yours, like one typed in claude: the chunk stays open until the answer is recorded, where a later chunk could need it.
- `todo.md` may mark a renamed release in a `## Renamed` section, one line per rename, such as `- 0.2.1 renamed to 0.3.0`. `chunk-preflight` and `loop-claude` then skip that release when they pick the next one, and larv-review's scoring-run trigger calls no run for it. Without the mark, a release named since the last tag whose items all moved to other releases reads as finished: `chunk-preflight` says it is ready to cut and the loop stops for you, and the trigger calls a scoring run. `rank_todo.py` fails on a `## Renamed` line of another shape, and on an item filed under a release it marks. Before you move a machine to this release, add the line to the `todo.md` of every project that renamed a release since its last tag, or its loop stops for that release's cut.
+141
View File
@@ -0,0 +1,141 @@
"""The next chunk's pick: the item the chunk takes first, weighed against the last release cut, and what the default branch holds for the pick."""
import dataclasses
import re
from git_repo import commits_since, file_at, git, newest_release_tag
from failure import Failure
from todo_table import Item, items, next_item, renames
from markdown_text import sections
@dataclasses.dataclass(frozen=True)
class LastCut:
"""What the default branch holds about its last release, which chunk_item weighs the plan against."""
# The newest v* tag, None where the branch has none.
tag: str | None | Failure
# CHANGELOG.md's text, empty where the branch holds none.
changelog: str | Failure
# How many commits follow the tag, or make up the branch where it has none.
commits: int | Failure
# todo.md's text at the tag and at each later commit that changed it, oldest first, as named_releases reads them; empty without a tag.
todos_since: list[str] | Failure
@dataclasses.dataclass(frozen=True)
class Next:
"""The plan's earliest release is the next release: the earliest after the last cut that todo.md has named since that cut. Without a cut, the plan's earliest release is the next."""
# None where the plan holds no item.
release: tuple[int, int, int] | None
# The item the next chunk takes first, next_item's pick; None where every item waits or the plan holds none.
item: Item | None
@dataclasses.dataclass(frozen=True)
class Cut:
"""The plan's earliest release is the last cut's version or earlier."""
release: tuple[int, int, int]
@dataclasses.dataclass(frozen=True)
class Finished:
"""The next release holds no item, and changes are unreleased."""
# The next release, None where todo.md has named none since the cut.
release: tuple[int, int, int] | None
@dataclasses.dataclass(frozen=True)
class Unplanned:
"""The next release holds no item, and no change is unreleased."""
# The next release, None where todo.md has named none since the cut.
release: tuple[int, int, int] | None
@dataclasses.dataclass(frozen=True)
class Unknown:
"""todo.md's texts since the cut, or the changes since it, cannot be read."""
# How the plan stands to the last cut, the version x.y.z the newest v* tag names, with the item the next chunk takes first where there is one.
Pick = Next | Cut | Finished | Unplanned | Unknown
@dataclasses.dataclass(frozen=True)
class DefaultPlan:
"""What the default branch, as last fetched, holds for chunk_item."""
# todo.md's text, empty where the branch holds none.
todo: str | Failure
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_release_tag(ref, root)
commits = tag if isinstance(tag, Failure) else commits_since(tag, ref, root)
return DefaultPlan(file_at(ref, "todo.md", root), LastCut(tag, file_at(ref, "CHANGELOG.md", root), commits, todos_since(tag, ref, root)))
def todos_since(tag: str | None | Failure, ref: str, cwd: str) -> 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 not isinstance(tag, str):
return []
changed = git("log", "--first-parent", "--reverse", "--format=%H", f"{tag}..{ref}", "--", "todo.md", cwd=cwd)
if isinstance(changed, Failure):
return changed
texts = []
for commit in [tag, *changed.split()]:
text = file_at(commit, "todo.md", cwd)
if isinstance(text, Failure):
return text
texts.append(text)
return texts
def chunk_item(found: list[Item], cut: LastCut) -> Pick:
"""The pick from todo.md's items, weighed against the last cut. Routing and chunk-preflight both pick with it, so they name one item."""
return standing(cut.tag, unreleased_changes(cut), min((item.release for item in found), default=None), next_item(found), named_releases(cut.todos_since))
def standing(tag: str | None | Failure, changes: int | Failure, earliest: tuple[int, int, int] | None, first: Item | None, named: set[tuple[int, int, int]] | Failure) -> Pick:
"""How the plan stands to tag, the newest v* tag.
earliest is the plan's earliest release, None where the plan holds no item, and first is next_item's pick. changes counts the unreleased changes. named holds each release todo.md named since the tag.
"""
tagged = re.fullmatch(r"v([0-9]+)\.([0-9]+)\.([0-9]+)", tag) if isinstance(tag, str) else None
if tagged is None:
return Next(earliest, first)
cut_version = tuple(int(part) for part in tagged.groups())
if earliest is not None and earliest <= cut_version:
return Cut(earliest)
if isinstance(named, Failure):
return Unknown()
first_named = min((release for release in named if release > cut_version), default=None)
if earliest is not None and (first_named is None or earliest <= first_named):
return Next(earliest, first)
if isinstance(changes, Failure):
return Unknown()
return Finished(first_named) if changes else Unplanned(first_named)
def unreleased_changes(cut: LastCut) -> int | Failure:
"""How many changes are unreleased, as `~/.claude/CLAUDE.md` → "Working loop" counts them: the entries under ## Unreleased, or the commits since the tag where CHANGELOG.md has no such section or cannot be read."""
entries = unreleased_entries(cut.changelog) if isinstance(cut.changelog, str) else None
return cut.commits if entries is None else entries
def unreleased_entries(changelog: str) -> int | None:
"""How many top-level `- ` entries CHANGELOG.md holds under ## Unreleased; None without that section."""
found = sections(changelog).get("Unreleased")
return None if found is None else sum(line.startswith("- ") for line in found[0].splitlines())
def named_releases(todos: list[str] | Failure) -> set[tuple[int, int, int]] | Failure:
"""Each release the todo.md texts, oldest first, file items under. A release leaves the set when a text marks it renamed, and returns when a later text files items under it again. A text whose items or marks do not parse names none, except the newest: where its marks do not parse, it returns that Failure, since the release they should have excluded would read as finished."""
if isinstance(todos, Failure):
return todos
if todos and isinstance(newest := renames(todos[-1]), Failure):
return newest
named: set[tuple[int, int, int]] = set()
for text in todos:
plan, marked = items(text), renames(text)
if isinstance(plan, list) and isinstance(marked, set):
named = (named - marked) | {item.release for item in plan}
return named
+76
View File
@@ -0,0 +1,76 @@
"""The pure choices the preflight's steps act on."""
import pathlib
import re
from chunk_pick import chunk_item, Cut, Finished, LastCut, Unknown, Unplanned
from failure import Failure
from chunk_preflight.gathered import Forge, NoItem, Plan
from todo_table import item_details, items, version
# The command each forge's CLI lists pull requests with; pulls_command adds the flags that pick their rows and fields.
PULLS_LIST: dict[Forge, tuple[str, ...]] = {"gh": ("gh", "pr", "list"), "tea": ("tea", "pulls", "list")}
def planned(todo: str | Failure, cut: LastCut, default: str) -> Plan | NoItem:
"""The plan in todo, the default branch's todo.md, with the item the next chunk takes first, chunk_pick.chunk_item's pick; else why there is none."""
where = f"{default}'s todo.md"
if isinstance(todo, Failure):
return NoItem(f"{where} cannot be read: {todo.reason}.")
found = items(todo)
if isinstance(found, Failure):
return NoItem(f"{where} cannot be read: {found.reason}.")
if found is None:
return NoItem(f"{where} holds no items table.")
pick = chunk_item(found, cut)
if isinstance(pick, Cut):
return NoItem(f"{where} files items under release {version(pick.release)}, which is not after the last cut, {cut.tag}; ask the human which release they belong to.")
if isinstance(pick, Unknown):
return NoItem(f"{where} may hold no item for the next release after the last cut, {cut.tag}: todo.md's texts since then, or the count of changes since then, cannot be read. Find the next release yourself.")
if isinstance(pick, Finished | Unplanned):
upcoming = f"release {version(pick.release)}, the next after the last cut, {cut.tag}" if pick.release else f"the next release after the last cut, {cut.tag}"
if isinstance(pick, Finished):
return NoItem(f"{where} holds no item for {upcoming}, and changes are unreleased, so that release is finished and ready to cut. The working loop stops here. If todo.md renamed that release instead, add `- <old release> renamed to <new release>` to todo.md's `## Renamed` section.")
return NoItem(f"{where} holds no item for {upcoming}, and no change is unreleased, so that release is to be planned first.")
first = pick.item
if first is None:
return NoItem(f"every item of release {version(pick.release)} in {where} waits." if pick.release is not None else f"{where}'s items table holds no item.")
details = item_details(todo)
detail = details.get(first.id, "") if isinstance(details, dict) else f"(todo.md's details cannot be read: {details.reason})"
return Plan(found, first, f"{first.tagline}\n\n{detail}".strip())
def worktree_on(porcelain: str, branch: str) -> pathlib.Path | None:
"""The worktree on branch, in what `git worktree list --porcelain` printed; None where none is."""
for block in porcelain.split("\n\n"):
fields = dict(line.partition(" ")[::2] for line in block.splitlines())
if fields.get("branch") == f"refs/heads/{branch}":
return pathlib.Path(fields["worktree"])
return None
def worktree_add(branch: str, path: pathlib.Path, default: str, local: bool, pushed: bool) -> tuple[list[str], str]:
"""The git arguments that add branch's worktree at path, and how it comes to be: on the local branch, else on a new one tracking origin's, else on a new one off default."""
if local:
return ["worktree", "add", "--quiet", str(path), branch], f"added on the branch {branch}, which existed already."
if pushed:
return ["worktree", "add", "--quiet", "--track", "-b", branch, str(path), f"origin/{branch}"], f"added on the new branch {branch}, made off origin/{branch}."
# --no-track: tracking the default branch would point a bare `git push` at it.
return ["worktree", "add", "--quiet", "--no-track", "-b", branch, str(path), default], f"added on the new branch {branch}, made off {default}."
def forge_of(origin_url: str) -> Forge:
return "gh" if "github.com" in origin_url else "tea"
def pulls_command(forge: Forge, branch: str) -> list[str]:
"""The command that lists open pull requests: gh only branch's, by number and URL; tea every one, by index, head and URL, for facts.open_pulls to pick branch's."""
if forge == "gh":
return [*PULLS_LIST["gh"], "--head", branch, "--json", "number,url", "--template", "{{range .}}{{.number}}\t{{.url}}\n{{end}}"]
return [*PULLS_LIST["tea"], "--fields", "index,head,url", "--output", "tsv"]
def named_paths(text: str, tracked: list[str]) -> list[tuple[str, int]]:
"""Each backticked span in text, in order and once, that names a tracked file or folder, with how many of the tracked files it holds: 1 for a file."""
spans = dict.fromkeys(span.removesuffix("/") for span in re.findall(r"`([^`\s]+)`", text))
held = ((span, sum(path == span or path.startswith(f"{span}/") for path in tracked)) for span in spans)
return [(span, count) for span, count in held if count]
+4 -2
View File
@@ -1,7 +1,9 @@
"""The lines the preflight prints, stated from what it gathered."""
from todo_table import bundle_candidates, Item, LastCut, unreleased_entries
from todo_table import bundle_candidates, Item, version
from failure import Failure
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, PULLS_LIST, Ran, version
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran
from chunk_pick import LastCut, unreleased_entries
from chunk_preflight.choices import PULLS_LIST
from markdown_text import quoted
+3 -74
View File
@@ -1,16 +1,14 @@
"""What the preflight gathers, and the pure choices its steps act on; facts.render states it."""
"""What the preflight gathers, which facts.render states."""
import dataclasses
import pathlib
import re
import typing
from todo_table import chunk_item, Item, item_details, items, LastCut
from failure import Failure
from todo_table import Item
from chunk_pick import LastCut
# The CLI that lists a forge's pull requests: gh for a github.com origin, tea for any other.
Forge = typing.Literal["gh", "tea"]
# The command each forge's CLI lists pull requests with; pulls_command adds the flags that pick their rows and fields.
PULLS_LIST: dict[Forge, tuple[str, ...]] = {"gh": ("gh", "pr", "list"), "tea": ("tea", "pulls", "list")}
@dataclasses.dataclass(frozen=True)
@@ -79,72 +77,3 @@ class Gathered:
cut: LastCut
# What was found or made for the plan's first item; else why the plan names none.
item: ItemFacts | NoItem
def planned(todo: str | Failure, cut: LastCut, default: str) -> Plan | NoItem:
"""The plan in todo, the default branch's todo.md, with the item the next chunk takes first, todo_table.chunk_item's pick; else why there is none."""
where = f"{default}'s todo.md"
if isinstance(todo, Failure):
return NoItem(f"{where} cannot be read: {todo.reason}.")
found = items(todo)
if isinstance(found, Failure):
return NoItem(f"{where} cannot be read: {found.reason}.")
if found is None:
return NoItem(f"{where} holds no items table.")
earliest = min((item.release for item in found), default=None)
stands, first = chunk_item(found, cut)
if earliest is not None and stands == "cut":
return NoItem(f"{where} files items under release {version(earliest)}, which is not after the last cut, {cut.tag}; ask the human which release they belong to.")
gap = f"{where} holds no item for the next release after the last cut, {cut.tag}, and"
if stands == "finished":
return NoItem(f"{gap} work has landed since, so that release is finished and ready to cut, and the working loop stops here. If todo.md renamed that release instead, add `- <old release> renamed to <new release>` to todo.md's `## Renamed` section.")
if stands == "unplanned":
return NoItem(f"{gap} no work has landed since, so that release is to be planned first.")
if stands == "unknown":
return NoItem(f"{where} may hold no item for the next release after the last cut, {cut.tag}: todo.md's texts since then, or the count of work landed since then, cannot be read. Find the next release yourself.")
if first is None:
return NoItem(f"every item of release {version(earliest)} in {where} waits." if earliest is not None else f"{where}'s items table holds no item.")
details = item_details(todo)
detail = details.get(first.id, "") if isinstance(details, dict) else f"(todo.md's details cannot be read: {details.reason})"
return Plan(found, first, f"{first.tagline}\n\n{detail}".strip())
def version(release: tuple[int, int, int]) -> str:
return ".".join(map(str, release))
def worktree_on(porcelain: str, branch: str) -> pathlib.Path | None:
"""The worktree on branch, in what `git worktree list --porcelain` printed; None where none is."""
for block in porcelain.split("\n\n"):
fields = dict(line.partition(" ")[::2] for line in block.splitlines())
if fields.get("branch") == f"refs/heads/{branch}":
return pathlib.Path(fields["worktree"])
return None
def worktree_add(branch: str, path: pathlib.Path, default: str, local: bool, pushed: bool) -> tuple[list[str], str]:
"""The git arguments that add branch's worktree at path, and how it comes to be: on the local branch, else on a new one tracking origin's, else on a new one off default."""
if local:
return ["worktree", "add", "--quiet", str(path), branch], f"added on the branch {branch}, which existed already."
if pushed:
return ["worktree", "add", "--quiet", "--track", "-b", branch, str(path), f"origin/{branch}"], f"added on the new branch {branch}, made off origin/{branch}."
# --no-track: tracking the default branch would point a bare `git push` at it.
return ["worktree", "add", "--quiet", "--no-track", "-b", branch, str(path), default], f"added on the new branch {branch}, made off {default}."
def forge_of(origin_url: str) -> Forge:
return "gh" if "github.com" in origin_url else "tea"
def pulls_command(forge: Forge, branch: str) -> list[str]:
"""The command that lists open pull requests: gh only branch's, by number and URL; tea every one, by index, head and URL, for facts.open_pulls to pick branch's."""
if forge == "gh":
return [*PULLS_LIST["gh"], "--head", branch, "--json", "number,url", "--template", "{{range .}}{{.number}}\t{{.url}}\n{{end}}"]
return [*PULLS_LIST["tea"], "--fields", "index,head,url", "--output", "tsv"]
def named_paths(text: str, tracked: list[str]) -> list[tuple[str, int]]:
"""Each backticked span in text, in order and once, that names a tracked file or folder, with how many of the tracked files it holds: 1 for a file."""
spans = dict.fromkeys(span.removesuffix("/") for span in re.findall(r"`([^`\s]+)`", text))
held = ((span, sum(path == span or path.startswith(f"{span}/") for path in tracked)) for span in spans)
return [(span, count) for span, count in held if count]
+7 -4
View File
@@ -15,8 +15,9 @@ holds it, the plan loop-claude routes on. It prints:
blocks it. Where the newest tag names a version x.y.z, the next release is the earliest after
x.y.z that todo.md has named at that tag or since, less a release its ## Renamed section marks
renamed. Otherwise it is todo.md's earliest release.
Where the next release holds no item, it says so: finished and ready to cut where work landed
since the tag (the ## Unreleased entries, or else the commits), and else to be planned first.
Where the next release holds no item, it says so, naming it where todo.md named it since the tag:
finished and ready to cut where changes are unreleased (the ## Unreleased entries, or else the
commits since the tag), and else to be planned first.
Where todo.md's earliest release is x.y.z or earlier, it says todo.md files items under a release
already cut;
- the item's worktree: a sibling of the checkout named <checkout>-item-<ID>, on the branch
@@ -46,9 +47,11 @@ import subprocess
import sys
import typing
from git_repo import commit_exists, default_branch, default_plan, file_at, git, top
from git_repo import commit_exists, default_branch, file_at, git, top
from chunk_pick import default_plan
from failure import Failure
from chunk_preflight.gathered import Forge, forge_of, Gathered, ItemFacts, named_paths, NamedPath, NoItem, Plan, planned, pulls_command, Ran, Worktree, worktree_add, worktree_on
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran, Worktree
from chunk_preflight.choices import forge_of, named_paths, planned, pulls_command, worktree_add, worktree_on
from chunk_preflight.facts import render
BIN = pathlib.Path(__file__).resolve().parents[1]
+15 -16
View File
@@ -9,9 +9,10 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
from chunk_preflight.gathered import forge_of, Gathered, ItemFacts, named_paths, NamedPath, NoItem, planned, Ran, Worktree, worktree_add
from chunk_preflight.choices import forge_of, named_paths, planned, worktree_add
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, NoItem, Ran, Worktree
from test_env import isolated_env
from todo_table import LastCut, unreleased_entries
from chunk_pick import LastCut
from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
from chunk_preflight.facts import open_pulls, render
@@ -421,18 +422,21 @@ class Plans(unittest.TestCase):
self.assertNotIn("no items table", empty)
def test_finds_the_release_after_the_last_cut_finished_or_to_be_planned_where_the_plan_holds_no_item_for_it(self):
named = "release 0.2.0, the next after the last cut, v0.1.0"
unnamed = "the next release after the last cut, v0.1.0"
cases = (
(LATER, 4, "finished and ready to cut"),
(LATER, 0, "planned first"),
(EMPTY, 4, "finished and ready to cut"),
(EMPTY, 0, "planned first"),
(LATER, Failure("count unreadable"), "cannot be read"),
(LATER, 4, [TODO], "finished and ready to cut", named),
(LATER, 0, [TODO], "planned first", named),
(EMPTY, 4, [TODO], "finished and ready to cut", named),
(EMPTY, 0, [TODO], "planned first", named),
(EMPTY, 4, [EMPTY], "finished and ready to cut", unnamed),
(LATER, Failure("count unreadable"), [TODO], "cannot be read", unnamed),
)
for todo, commits, fact in cases:
with self.subTest(todo=todo, commits=commits):
why = planned(todo, LastCut("v0.1.0", "", commits, [TODO]), "origin/main").why
for todo, commits, todos, fact, release in cases:
with self.subTest(todo=todo, commits=commits, todos=todos):
why = planned(todo, LastCut("v0.1.0", "", commits, todos), "origin/main").why
self.assertIn(fact, why)
self.assertIn("v0.1.0", why)
self.assertIn(release, why)
def test_says_what_todo_md_named_since_the_last_cut_cannot_be_read(self):
self.assertIn("cannot be read", planned(LATER, LastCut("v0.1.0", "", 4, Failure("log unreadable")), "origin/main").why)
@@ -451,11 +455,6 @@ class Plans(unittest.TestCase):
class Gathering(unittest.TestCase):
def test_counts_the_top_level_entries_under_unreleased(self):
self.assertEqual(unreleased_entries(CHANGELOG), 2)
self.assertEqual(unreleased_entries("# Changelog\n\n## Unreleased\n\n## 0.1.0\n\n- Old.\n"), 0)
self.assertIsNone(unreleased_entries("# Changelog\n\n## 0.1.0\n\n- Old.\n"))
def test_names_each_tracked_file_or_folder_a_backticked_span_names_once_with_its_files(self):
cases = (
("`src/` and `src`", ["src/app.py", "srcfoo/x.py"], [("src", 1)]),
-33
View File
@@ -1,10 +1,8 @@
"""Run git, in the current directory or a given one, and read the checkout, its default branch and its files."""
import dataclasses
import re
import subprocess
from failure import Failure
from todo_table import LastCut
def git(*args: str, cwd: str | None = None, timeout: float | None = None) -> str | Failure:
@@ -62,37 +60,6 @@ def origin_head(cwd: str | None, timeout: float | None) -> str | Failure:
return Failure("origin names no default branch; set it with `git remote set-head origin --auto`")
@dataclasses.dataclass(frozen=True)
class DefaultPlan:
"""What the default branch, as last fetched, holds for picking the next chunk's item: todo_table.chunk_item's inputs."""
# todo.md's text, empty where the branch holds none.
todo: str | Failure
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_release_tag(ref, root)
commits = tag if isinstance(tag, Failure) else commits_since(tag, ref, root)
return DefaultPlan(file_at(ref, "todo.md", root), LastCut(tag, file_at(ref, "CHANGELOG.md", root), commits, todos_since(tag, ref, root)))
def todos_since(tag: str | None | Failure, ref: str, cwd: str) -> list[str] | Failure:
"""todo.md's text at tag and at each later commit on ref that changed it, oldest first, read in cwd; empty where there is no tag. A pull request's own commits do not count, only the merge that landed it: --first-parent."""
if not isinstance(tag, str):
return []
changed = git("log", "--first-parent", "--reverse", "--format=%H", f"{tag}..{ref}", "--", "todo.md", cwd=cwd)
if isinstance(changed, Failure):
return changed
texts = []
for commit in [tag, *changed.split()]:
text = file_at(commit, "todo.md", cwd)
if isinstance(text, Failure):
return text
texts.append(text)
return texts
def newest_release_tag(branch: str, cwd: str | None = None) -> str | None | Failure:
"""The newest `v*` tag merged into branch, read in cwd, else in the current directory; None when it has none."""
# Sorts v1.0.0-rc.1 below v1.0.0.
+1 -1
View File
@@ -22,7 +22,7 @@ def history_changes(default: str) -> list[HistoryChange] | Failure:
return changes
def landed_since_release(default: str) -> bool | Failure:
def committed_since_release(default: str) -> bool | Failure:
"""Whether the default branch holds a commit after its newest `v*` tag, or any commit when it has none."""
newest = newest_release_tag(default)
if isinstance(newest, Failure):
+4 -4
View File
@@ -1,9 +1,9 @@
import pathlib
from larv_review.git import committed_since_release
from failure import Failure
from git_repo import file_at, top
from todo_table import Item, items, renames
from larv_review.git import landed_since_release
from todo_table import Item, items, renames, version
def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], landed: bool, renamed: set[tuple[int, int, int]]) -> list[str] | Failure:
@@ -20,7 +20,7 @@ def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], lan
for release in emptied(before, after, shipped, renamed):
if any(item.release == release for item in shipped) or (release == next_release and landed):
# SKILL.md → "Second run" keys on this wording.
reasons.append(f"leaves release {'.'.join(map(str, release))} with no plan item")
reasons.append(f"leaves release {version(release)} with no plan item")
return reasons
@@ -55,7 +55,7 @@ def plan_reasons(default: str, ids: list[int]) -> list[str] | Failure:
renamed = renames(after)
if isinstance(renamed, Failure):
return Failure(f"the checkout's todo.md: {renamed.reason}")
landed = landed_since_release(default)
landed = committed_since_release(default)
if isinstance(landed, Failure):
return landed
return scoring_run_due(planned, chunk, ids, landed, renamed)
+1 -1
View File
@@ -71,7 +71,7 @@ class Reply:
finished: bool = dataclasses.field(metadata={"description": "Whether the chunk is finished."})
interrupt: bool = dataclasses.field(metadata={"description": "Whether the human must now be interrupted."})
question: str = dataclasses.field(metadata={"description": "With interrupt true, the single question to put to the human. With a quoted answer, the agent's question that the answer field answers. Empty otherwise."})
# True opens claude's session at once, in place of the one-line answer (run.ask). The judge decides it, since loop-claude computes the plan's standing (todo_table.chunk_item) only when it routes a chunk on the ladder afresh: it would miss a release ready to cut in a resumed chunk or off the ladder. A wrong ruling costs the human one typed /talk, or answering in claude, which stops the loop if they leave it with nothing typed.
# True opens claude's session at once, in place of the one-line answer (run.ask). The judge decides it, since loop-claude computes the plan's standing (chunk_pick.chunk_item) only when it routes a chunk on the ladder afresh: it would miss a release ready to cut in a resumed chunk or off the ladder. A wrong ruling costs the human one typed /talk, or answering in claude, which stops the loop if they leave it with nothing typed.
release_ready: bool = dataclasses.field(metadata={"description": "With interrupt true, whether the question is about a release ready to cut, which only the human may publish. False otherwise."})
+14 -8
View File
@@ -59,7 +59,7 @@ for the worker and the session /talk opens; with both set, nothing is asked.
Where that model is on the routing ladder (bin/model_routing/ladder.py), the worker and the
session /talk opens run on one of the ladder's rungs: a model at an effort. As a chunk starts, it is routed
on the item chunk-preflight names, read from todo.md on the default branch as the preflight just
fetched it (todo_table.chunk_item). That item is the earliest release's top item that does not wait,
fetched it (chunk_pick.chunk_item). That item is the earliest release's top item that does not wait,
but only where that release is the next one: the earliest after the newest vX.Y.Z tag that todo.md
has named at that tag or since, skipping a release its ## Renamed section marks renamed, or, where
no tag names a version, the earliest release. Otherwise no item routes the chunk. An item waits
@@ -169,7 +169,8 @@ from loop_claude.loop.routing_check import check_routing
from loop_claude.project.checkout import checkout_root
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 git_repo import default_plan, default_ref, DefaultPlan
from chunk_pick import default_plan, DefaultPlan
from git_repo import default_ref
from loop_claude.effects import Effects
from failure import Failure
from loop_claude.cycle.judge import Finished, Unfinished
@@ -224,11 +225,10 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
models = get_or_ask_models(key, paths, env, effects)
if isinstance(models, Stop):
return models
# Before routing, which reads the plan as the preflight's fetch left it; after the reads above, so a loop that stops on one makes no worktree.
facts = "" if session_open(session) else chunk_facts(launcher.with_name("chunk-preflight"), loop_run.root, effects)
# After the reads above, so a loop that stops on one makes no worktree.
facts, item = chunk_start(session, launcher.with_name("chunk-preflight"), loop_run.root, effects)
anchor = project_rung(models.worker)
root = loop_run.root
loop_run = routed(loop_run, anchor, lambda: archived_route(archive_folder, session), lambda: plan_item(fetched_plan(root)))
loop_run = routed(loop_run, anchor, lambda: archived_route(archive_folder, session), item)
route = loop_run.route or Route(Rung(models.worker))
print(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", flush=True)
concluded = run_cycle(Cycle(anchor=anchor, effects=effects, facts=facts, judge_model=models.judge, paths=paths, premises=premises, project_archive=archive_folder, records=records, root=loop_run.root, route=route, session=session, task=loop_run.task, unfinished_evidence=loop_run.unfinished_evidence))
@@ -278,6 +278,12 @@ def archived_route(archive_folder: pathlib.Path, session: Session) -> Route | No
return route_from(worker) if worker else None
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))
def chunk_facts(preflight: pathlib.Path, root: str, effects: Effects) -> str:
"""What chunk-preflight printed at the checkout root, for a fresh worker's prompt, or why it could not run."""
done = effects.python([str(preflight)], root)
@@ -287,13 +293,13 @@ def chunk_facts(preflight: pathlib.Path, root: str, effects: Effects) -> str:
def fetched_plan(root: str) -> DefaultPlan | Failure:
"""What the default branch, as chunk-preflight's fetch left it, holds for routing."""
"""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)
def plan_item(plan: DefaultPlan | Failure) -> Item | None:
"""The item that routes a chunk, todo_table.chunk_item's pick from the default branch; None without one, so the chunk runs on the project's rung."""
"""The item that routes a chunk, chunk_pick.chunk_item's pick from the default branch; None without one, so the chunk runs on the project's rung."""
if isinstance(plan, Failure):
item: Item | Failure | None = plan
elif isinstance(plan.todo, Failure):
+5 -3
View File
@@ -1,9 +1,10 @@
"""Which ladder rung a chunk's worker and judge run on: docs/decisions.md → `routing:`."""
import dataclasses
from todo_table import chunk_item, Item, items, LastCut
from chunk_pick import chunk_item, LastCut, Next
from model_routing.ladder import climbed, highest, LADDER, position, project_rung, review_floor, Rung, stepped_up, worker_rung
from failure import Failure
from todo_table import Item, items
from model_routing.route import Route
UNFINISHED_PER_STEP = 2
@@ -14,11 +15,12 @@ JUDGE_REPLAYED = ("claude-opus-5-5",)
def routed_item(todo: str, cut: LastCut) -> Item | Failure | None:
"""The item todo_table.chunk_item picks from todo.md, weighed against the last cut; None when there is none, or it lacks L, E or I."""
"""The item chunk_pick.chunk_item picks from todo.md, weighed against the last cut; None when there is none, or it lacks L, E or I."""
found = items(todo)
if isinstance(found, Failure):
return found
_, takes = chunk_item(found or [], cut)
pick = chunk_item(found or [], cut)
takes = pick.item if isinstance(pick, Next) else None
return takes if takes and takes.likelihood and takes.escape_and_impact else None
+14 -2
View File
@@ -18,14 +18,13 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from routing_figures import archive
from loop_claude.project import checkout, model_choice, records
from git_repo import DefaultPlan
from chunk_pick import DefaultPlan, LastCut
from loop_claude.effects import Effects, PYTHON_TIMEOUT, run_python
from claude_code import entries, reply, session
from failure import Failure
from loop_claude.cycle.judge import Finished, Interrupt, QuotedAnswer, Unfinished, verdict_from
from loop_claude.cycle import interrupt, judge, prompts, retry, run, states, worker
from model_routing.ladder import LADDER, Rung
from todo_table import LastCut
from claude_code.reply import Limited
from loop_claude.loop import main, reload, routing_check
from transcript_archive import outcomes, write
@@ -961,6 +960,19 @@ class ChunkFacts(unittest.TestCase):
self.assertIn("yourself", said)
self.assertIn(why, said)
def test_runs_the_preflight_only_where_the_session_is_not_open(self):
with tempfile.TemporaryDirectory() as home:
opened = session.session_named("A proj loop-claude", pathlib.Path(home, "projects"))
fresh = FakeEffects(python=[ran("- A fact.\n")])
facts, _ = main.chunk_start(opened, self.PREFLIGHT, "/r", fresh.effects())
self.assertEqual((fresh.made("python"), "- A fact." in facts), ([(["/b/chunk-preflight"], "/r")], True))
transcript = pathlib.Path(home, "projects", "-fake", f"{opened.id}.jsonl")
transcript.parent.mkdir(parents=True)
transcript.write_text("")
resumed = FakeEffects()
facts, _ = main.chunk_start(opened, self.PREFLIGHT, "/r", resumed.effects())
self.assertEqual((resumed.made("python"), facts), ([], ""))
class PythonEffect(unittest.TestCase):
def test_runs_a_script_in_the_given_directory(self):
+4 -8
View File
@@ -81,7 +81,7 @@ import re
import sys
import typing
from todo_table import BLOCKED_BY, cells, DETAILS, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, Shape, SHAPE, shape_of, Table, table_rows
from todo_table import BLOCKED_BY, cells, DETAILS, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, Shape, SHAPE, shape_of, Table, table_rows, version
from failure import Failure
from markdown_text import listed, sections
from file_writes import replace_file
@@ -208,7 +208,7 @@ def rank(text: str, readme: str, decisions: str) -> Ranked | Failure:
if isinstance(marked := renames(text), Failure):
return marked
if live := next((item for item in items if item.release in marked), None):
return Failure(f"todo.md marks release {release_name(live)} renamed but files item {live.id} under it; drop the mark or move the item")
return Failure(f"todo.md marks release {version(live.release)} renamed but files item {live.id} under it; drop the mark or move the item")
scored = ordered(items, scoring)
if isinstance(scored, Failure):
return scored
@@ -367,7 +367,7 @@ def blockers_first(scored: list[tuple[Item, float]]) -> list[tuple[Item, float]]
for item, _ in scored:
for blocker in item.blocked_by:
if blocker in held and held[blocker][0].release > item.release:
later, earlier = release_name(held[blocker][0]), release_name(item)
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")
result: list[tuple[Item, float]] = []
for item, _ in scored:
@@ -396,10 +396,6 @@ def place(id_: int, held: dict[int, tuple[Item, float]], position: dict[int, int
return [*added, (dataclasses.replace(item, blocked_by=tuple(sorted(blockers))), value)]
def release_name(item: Item) -> str:
return ".".join(str(part) for part in item.release)
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))
@@ -581,7 +577,7 @@ def parse_item(row: str, scoring: Scoring, table: Table) -> Item | Failure:
def render_item(item: Item, value: float, shape: Shape, columns: tuple[str, ...]) -> str:
"""The item's row, each cell under its column."""
written = {"ID": str(item.id), "Release": release_name(item), BLOCKED_BY: ", ".join(map(str, item.blocked_by)), "Exempt": item.exempt, "Item": item.tagline, **{name: str(score) for name, score in item.scores.items()}, shape.goals_column: shape.write_goals(item.moves), "Score": f"{value:.1f}"}
written = {"ID": str(item.id), "Release": version(item.release), BLOCKED_BY: ", ".join(map(str, item.blocked_by)), "Exempt": item.exempt, "Item": item.tagline, **{name: str(score) for name, score in item.scores.items()}, shape.goals_column: shape.write_goals(item.moves), "Score": f"{value:.1f}"}
return "| " + " | ".join(written[column] for column in columns) + " |"
+84
View File
@@ -0,0 +1,84 @@
import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
import chunk_pick
from failure import Failure
import todo_table
class Standing(unittest.TestCase):
def test_takes_the_earliest_release_where_it_is_the_earliest_named_since_the_last_cut_and_names_the_next_release(self):
cases = (
("v1.2.3", 4, (1, 2, 4), set(), chunk_pick.Next((1, 2, 4), None)),
("v1.2.3", 4, (1, 3, 0), {(1, 3, 0)}, chunk_pick.Next((1, 3, 0), None)),
("v1.2.3", 4, (1, 2, 4), {(1, 3, 0)}, chunk_pick.Next((1, 2, 4), None)),
("v1.2.3", 4, (1, 3, 0), {(1, 2, 3), (1, 3, 0)}, chunk_pick.Next((1, 3, 0), None)),
("v0.2.0", 4, (0, 4, 0), set(), chunk_pick.Next((0, 4, 0), None)),
(None, 4, (0, 2, 0), set(), chunk_pick.Next((0, 2, 0), None)),
(None, 4, None, set(), chunk_pick.Next(None, None)),
("v1.2.3-rc.1", 4, (1, 2, 3), set(), chunk_pick.Next((1, 2, 3), None)),
(Failure("tags unreadable"), 4, (0, 2, 0), set(), chunk_pick.Next((0, 2, 0), None)),
("v1.2.3", 4, (1, 2, 3), set(), chunk_pick.Cut((1, 2, 3))),
("v1.2.3", 4, (1, 2, 2), {(1, 2, 4)}, chunk_pick.Cut((1, 2, 2))),
("v1.2.3", 4, (1, 3, 0), {(1, 2, 4), (1, 3, 0)}, chunk_pick.Finished((1, 2, 4))),
("v0.9.2", 4, (1, 0, 0), {(0, 9, 3)}, chunk_pick.Finished((0, 9, 3))),
("v1.2.3", 4, (1, 4, 0), {(1, 2, 2), (1, 3, 0)}, chunk_pick.Finished((1, 3, 0))),
("v1.2.3", 4, None, {(1, 3, 0)}, chunk_pick.Finished((1, 3, 0))),
("v1.2.3", 4, None, set(), chunk_pick.Finished(None)),
("v1.2.3", 0, (1, 3, 0), {(1, 2, 4)}, chunk_pick.Unplanned((1, 2, 4))),
("v1.2.3", 0, None, set(), chunk_pick.Unplanned(None)),
("v1.2.3", Failure("count unreadable"), None, set(), chunk_pick.Unknown()),
("v1.2.3", 4, (1, 3, 0), Failure("log unreadable"), chunk_pick.Unknown()),
("v1.2.3", 4, (1, 2, 3), Failure("log unreadable"), chunk_pick.Cut((1, 2, 3))),
)
for tag, landed, earliest, named, stands in cases:
with self.subTest(tag=tag, landed=landed, earliest=earliest, named=named):
self.assertEqual(chunk_pick.standing(tag, landed, earliest, None, named), stands)
def test_takes_the_first_item_only_where_the_earliest_release_is_next(self):
first = todo_table.Item(1, (1, 2, 4), "", "**Do 1.**", {}, (), ())
self.assertEqual(chunk_pick.standing("v1.2.3", 4, (1, 2, 4), first, set()), chunk_pick.Next((1, 2, 4), first))
self.assertEqual(chunk_pick.standing("v1.2.3", 4, (1, 2, 3), first, set()), chunk_pick.Cut((1, 2, 3)))
def test_counts_the_changes_unreleased_since_the_last_cut_by_unreleased_entries_and_else_by_commits(self):
changelog = "# Changelog\n\n## Unreleased\n\n- One.\n - A nested line.\n- Two.\n\n## 0.1.0\n\n- Old.\n"
self.assertEqual(chunk_pick.unreleased_changes(chunk_pick.LastCut("v0.1.0", changelog, 5, [])), 2)
self.assertEqual(chunk_pick.unreleased_changes(chunk_pick.LastCut("v0.1.0", "# Changelog\n\n## Unreleased\n\n## 0.1.0\n", 5, [])), 0)
self.assertEqual(chunk_pick.unreleased_changes(chunk_pick.LastCut("v0.1.0", "# Changelog\n\n## 0.1.0\n", 5, [])), 5)
self.assertEqual(chunk_pick.unreleased_changes(chunk_pick.LastCut("v0.1.0", Failure("unreadable"), 5, [])), 5)
def test_counts_the_top_level_entries_under_unreleased(self):
self.assertEqual(chunk_pick.unreleased_entries("# Changelog\n\n## Unreleased\n\n- One.\n - A nested line.\n- Two.\n\n## 0.1.0\n\n- Old.\n"), 2)
self.assertEqual(chunk_pick.unreleased_entries("# Changelog\n\n## Unreleased\n\n## 0.1.0\n\n- Old.\n"), 0)
self.assertIsNone(chunk_pick.unreleased_entries("# Changelog\n\n## 0.1.0\n\n- Old.\n"))
def test_names_each_release_a_todo_md_since_the_last_cut_filed_items_under(self):
row = "| {id} | {release} | | | **Do {id}.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
header = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
texts = [header + row.format(id=1, release="0.2.0"), "", "not a table | x |", header + row.format(id=2, release="0.3.0")]
self.assertEqual(chunk_pick.named_releases(texts), {(0, 2, 0), (0, 3, 0)})
self.assertEqual(chunk_pick.named_releases(Failure("log unreadable")), Failure("log unreadable"))
def test_leaves_out_a_release_the_plan_marks_renamed_and_keeps_one_whose_items_moved_unmarked(self):
row = "| {id} | {release} | | | **Do {id}.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
header = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
plan = lambda *rows, renamed=(): header + "".join(row.format(id=id_, release=release) for id_, release in rows) + ("\n## Renamed\n\n" + "".join(f"- {old} renamed to {new}\n" for old, new in renamed) if renamed else "")
cases = (
("renamed", [plan((1, "0.2.1")), plan((1, "0.3.0"), renamed=[("0.2.1", "0.3.0")])], {(0, 3, 0)}),
("deferred: its items moved without a mark", [plan((1, "0.2.1"), (2, "0.3.0")), plan((1, "0.3.0"), (2, "0.3.0"))], {(0, 2, 1), (0, 3, 0)}),
("renamed in a change that also dropped one of its items", [plan((1, "0.2.1"), (3, "0.2.1")), plan((1, "0.3.0"), renamed=[("0.2.1", "0.3.0")])], {(0, 3, 0)}),
("the plan shifted one minor", [plan((1, "0.2.1"), (2, "0.3.0")), plan((1, "0.3.0"), (2, "0.4.0"), renamed=[("0.2.1", "0.3.0"), ("0.3.0", "0.4.0")])], {(0, 3, 0), (0, 4, 0)}),
("the mark stays in later plans", [plan((1, "0.2.1")), plan((1, "0.3.0"), renamed=[("0.2.1", "0.3.0")]), plan((1, "0.3.0"), (2, "0.3.0"), renamed=[("0.2.1", "0.3.0")])], {(0, 3, 0)}),
("renamed, then named again", [plan((1, "0.2.1")), plan((1, "0.3.0"), renamed=[("0.2.1", "0.3.0")]), plan((1, "0.3.0"), (3, "0.2.1"), renamed=[("0.2.1", "0.3.0")])], {(0, 2, 1), (0, 3, 0)}),
("an older plan's mark that does not parse", [plan((1, "0.2.1")), plan((1, "0.3.0")) + "\n## Renamed\n\nsoon\n", plan((1, "0.3.0"))], {(0, 2, 1), (0, 3, 0)}),
)
for name, texts, named in cases:
with self.subTest(name):
self.assertEqual(chunk_pick.named_releases(texts), named)
def test_fails_to_name_releases_when_the_newest_plan_marks_one_in_a_form_it_cannot_read(self):
plan = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n| 1 | 0.3.0 | | | **Do 1.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
self.assertIsInstance(chunk_pick.named_releases([plan, plan + "\n## Renamed\n\nsoon\n"]), Failure)
+1 -62
View File
@@ -415,65 +415,7 @@ class Blockers(unittest.TestCase):
self.assertEqual(todo_table.items(f"## Items\n\n{header}"), Failure(f"the table under {header} has no |---| divider line"))
class Standing(unittest.TestCase):
def test_takes_the_earliest_release_where_it_is_the_earliest_named_since_the_last_cut(self):
cases = (
("v1.2.3", 4, (1, 2, 4), set(), "next"),
("v1.2.3", 4, (1, 3, 0), {(1, 3, 0)}, "next"),
("v1.2.3", 4, (1, 3, 0), {(1, 2, 3), (1, 3, 0)}, "next"),
("v0.2.0", 4, (0, 4, 0), set(), "next"),
(None, 4, (0, 2, 0), set(), "next"),
(None, 4, None, set(), "next"),
("v1.2.3-rc.1", 4, (1, 2, 3), set(), "next"),
(Failure("tags unreadable"), 4, (0, 2, 0), set(), "next"),
("v1.2.3", 4, (1, 2, 3), set(), "cut"),
("v1.2.3", 4, (1, 2, 2), {(1, 2, 4)}, "cut"),
("v1.2.3", 4, (1, 3, 0), {(1, 2, 4), (1, 3, 0)}, "finished"),
("v0.9.2", 4, (1, 0, 0), {(0, 9, 3)}, "finished"),
("v1.2.3", 4, (1, 4, 0), {(1, 2, 2), (1, 3, 0)}, "finished"),
("v1.2.3", 4, None, {(1, 3, 0)}, "finished"),
("v1.2.3", 4, None, set(), "finished"),
("v1.2.3", 0, (1, 3, 0), {(1, 2, 4)}, "unplanned"),
("v1.2.3", 0, None, set(), "unplanned"),
("v1.2.3", Failure("count unreadable"), None, set(), "unknown"),
("v1.2.3", 4, (1, 3, 0), Failure("log unreadable"), "unknown"),
("v1.2.3", 4, (1, 2, 3), Failure("log unreadable"), "cut"),
)
for tag, landed, earliest, named, stands in cases:
with self.subTest(tag=tag, landed=landed, earliest=earliest, named=named):
self.assertEqual(todo_table.standing(tag, landed, earliest, named), stands)
def test_counts_work_landed_since_the_last_cut_by_unreleased_entries_and_else_by_commits(self):
changelog = "# Changelog\n\n## Unreleased\n\n- One.\n - A nested line.\n- Two.\n\n## 0.1.0\n\n- Old.\n"
self.assertEqual(todo_table.landed(todo_table.LastCut("v0.1.0", changelog, 5, [])), 2)
self.assertEqual(todo_table.landed(todo_table.LastCut("v0.1.0", "# Changelog\n\n## Unreleased\n\n## 0.1.0\n", 5, [])), 0)
self.assertEqual(todo_table.landed(todo_table.LastCut("v0.1.0", "# Changelog\n\n## 0.1.0\n", 5, [])), 5)
self.assertEqual(todo_table.landed(todo_table.LastCut("v0.1.0", Failure("unreadable"), 5, [])), 5)
def test_names_each_release_a_todo_md_since_the_last_cut_filed_items_under(self):
row = "| {id} | {release} | | | **Do {id}.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
header = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
texts = [header + row.format(id=1, release="0.2.0"), "", "not a table | x |", header + row.format(id=2, release="0.3.0")]
self.assertEqual(todo_table.named_releases(texts), {(0, 2, 0), (0, 3, 0)})
self.assertEqual(todo_table.named_releases(Failure("log unreadable")), Failure("log unreadable"))
def test_leaves_out_a_release_the_plan_marks_renamed_and_keeps_one_whose_items_moved_unmarked(self):
row = "| {id} | {release} | | | **Do {id}.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
header = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
plan = lambda *rows, renamed=(): header + "".join(row.format(id=id_, release=release) for id_, release in rows) + ("\n## Renamed\n\n" + "".join(f"- {old} renamed to {new}\n" for old, new in renamed) if renamed else "")
cases = (
("renamed", [plan((1, "0.2.1")), plan((1, "0.3.0"), renamed=[("0.2.1", "0.3.0")])], {(0, 3, 0)}),
("deferred: its items moved without a mark", [plan((1, "0.2.1"), (2, "0.3.0")), plan((1, "0.3.0"), (2, "0.3.0"))], {(0, 2, 1), (0, 3, 0)}),
("renamed in a change that also dropped one of its items", [plan((1, "0.2.1"), (3, "0.2.1")), plan((1, "0.3.0"), renamed=[("0.2.1", "0.3.0")])], {(0, 3, 0)}),
("the plan shifted one minor", [plan((1, "0.2.1"), (2, "0.3.0")), plan((1, "0.3.0"), (2, "0.4.0"), renamed=[("0.2.1", "0.3.0"), ("0.3.0", "0.4.0")])], {(0, 3, 0), (0, 4, 0)}),
("the mark stays in later plans", [plan((1, "0.2.1")), plan((1, "0.3.0"), renamed=[("0.2.1", "0.3.0")]), plan((1, "0.3.0"), (2, "0.3.0"), renamed=[("0.2.1", "0.3.0")])], {(0, 3, 0)}),
("renamed, then named again", [plan((1, "0.2.1")), plan((1, "0.3.0"), renamed=[("0.2.1", "0.3.0")]), plan((1, "0.3.0"), (3, "0.2.1"), renamed=[("0.2.1", "0.3.0")])], {(0, 2, 1), (0, 3, 0)}),
("an older plan's mark that does not parse", [plan((1, "0.2.1")), plan((1, "0.3.0")) + "\n## Renamed\n\nsoon\n", plan((1, "0.3.0"))], {(0, 2, 1), (0, 3, 0)}),
)
for name, texts, named in cases:
with self.subTest(name):
self.assertEqual(todo_table.named_releases(texts), named)
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())
self.assertEqual(todo_table.renames("## Renamed\n\n- 0.2.1 renamed to 0.3.0\n- 0.3.0 renamed to 0.4.0\n\n## Details\n"), {(0, 2, 1), (0, 3, 0)})
@@ -495,9 +437,6 @@ class Standing(unittest.TestCase):
self.assertIsInstance(live, Failure)
self.assertIn("marks release 0.2.0 renamed but files item 1 under it", live.reason)
def test_fails_to_name_releases_when_the_newest_plan_marks_one_in_a_form_it_cannot_read(self):
plan = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n| 1 | 0.3.0 | | | **Do 1.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
self.assertIsInstance(todo_table.named_releases([plan, plan + "\n## Renamed\n\nsoon\n"]), Failure)
class Main(unittest.TestCase):
+6 -67
View File
@@ -17,10 +17,6 @@ BLOCKED_BY = "Blocked by"
MOVES = "Moves"
# How the items table's header opens, which tells it from any other table in todo.md.
HEADER_START = "| ID | Release |"
# How the plan's earliest release stands to the version x.y.z the newest tag names, the last cut. "next": it is the earliest release after x.y.z that todo.md has named at that tag or since, or no tag names a version, or the tag cannot be read. "cut": it is x.y.z or earlier.
# Else the next release, the earliest named since the cut, holds no item: "finished" where work landed since the cut, and "unplanned" where none did. "unknown": todo.md's texts since the cut, or the count of work landed since it, cannot be read.
# A release named since the cut stays the next until a tag cuts it, unless todo.md marks it renamed (`renames`); larv_review/plan.py's `emptied` skips the same releases.
Standing = typing.Literal["next", "cut", "finished", "unplanned", "unknown"]
# todo.md's ## Details section, its body the first group.
DETAILS = re.compile(r"^## Details\n(.*?)(?=^## |\Z)", re.M | re.S)
# A release's version, such as 0.2.1.
@@ -173,7 +169,7 @@ def waiting(found: list[Item], done: set[int]) -> set[int]:
def next_item(found: list[Item]) -> Item | None:
"""The earliest release's first row that does not wait, as waiting says, in the table's order; chunk_item takes it as the next chunk's first item where its release is the next."""
"""The earliest release's first row that does not wait, as waiting says, in the table's order; chunk_pick.chunk_item takes it as the next chunk's first item where its release is the next."""
if not found:
return None
release = min(item.release for item in found)
@@ -181,45 +177,6 @@ def next_item(found: list[Item]) -> Item | None:
return next((item for item in found if item.release == release and item.id not in waits), None)
@dataclasses.dataclass(frozen=True)
class LastCut:
"""What the default branch holds about its last release, which chunk_item weighs the plan against."""
# The newest v* tag, None where the branch has none.
tag: str | None | Failure
# CHANGELOG.md's text, empty where the branch holds none.
changelog: str | Failure
# How many commits follow the tag, or make up the branch where it has none.
commits: int | Failure
# todo.md's text at the tag and at each later commit that changed it, oldest first; empty without a tag.
todos_since: list[str] | Failure
def unreleased_entries(changelog: str) -> int | None:
"""How many top-level `- ` entries CHANGELOG.md holds under ## Unreleased; None without that section."""
found = sections(changelog).get("Unreleased")
return None if found is None else sum(line.startswith("- ") for line in found[0].splitlines())
def landed(cut: LastCut) -> int | Failure:
"""How much work has landed since the last cut: the entries under ## Unreleased, or the commits since the tag where CHANGELOG.md has no such section, as `~/.claude/CLAUDE.md` → "Working loop" counts unreleased changes."""
entries = unreleased_entries(cut.changelog) if isinstance(cut.changelog, str) else None
return cut.commits if entries is None else entries
def named_releases(todos: list[str] | Failure) -> set[tuple[int, int, int]] | Failure:
"""Each release the todo.md texts, oldest first, file items under. A release leaves the set when a text marks it renamed, and returns when a later text files items under it again. A text whose items or marks do not parse names none, except the newest: its marks failing to parse fails the whole, since the release they should have excluded would read as finished."""
if isinstance(todos, Failure):
return todos
if todos and isinstance(newest := renames(todos[-1]), Failure):
return newest
named: set[tuple[int, int, int]] = set()
for text in todos:
plan, marked = items(text), renames(text)
if isinstance(plan, list) and isinstance(marked, set):
named = (named - marked) | {item.release for item in plan}
return named
def renames(todo: str) -> set[tuple[int, int, int]] | Failure:
"""Each release todo.md's ## Renamed section says was renamed, as `- 0.2.1 renamed to 0.3.0`, so never finished; the tools read only the old release. `docs/decisions.md` → `todo.md: one table …` gives the rule and the spelling's pick."""
marked: set[tuple[int, int, int]] = set()
@@ -234,29 +191,6 @@ def renames(todo: str) -> set[tuple[int, int, int]] | Failure:
return marked
def standing(tag: str | None | Failure, landed: int | Failure, earliest: tuple[int, int, int] | None, named: set[tuple[int, int, int]] | Failure) -> Standing:
"""How the plan's earliest release, None where the plan holds no item, stands to the newest v* tag, as Standing says. named holds each release todo.md named since that tag, and landed the work landed since it."""
cut = re.fullmatch(r"v([0-9]+)\.([0-9]+)\.([0-9]+)", tag) if isinstance(tag, str) else None
if cut is None:
return "next"
version = tuple(int(part) for part in cut.groups())
if earliest is not None and earliest <= version:
return "cut"
if isinstance(named, Failure):
return "unknown"
if earliest is not None and earliest == min(release for release in named | {earliest} if release > version):
return "next"
if isinstance(landed, Failure):
return "unknown"
return "finished" if landed else "unplanned"
def chunk_item(found: list[Item], cut: LastCut) -> tuple[Standing, Item | None]:
"""The item the next chunk takes first, next_item's pick, where standing finds the plan's earliest release the next; else None. Routing and chunk-preflight both pick with it, so they name one item. It returns the standing too, so a caller can say why there is none."""
stands = standing(cut.tag, landed(cut), min((item.release for item in found), default=None), named_releases(cut.todos_since))
return stands, next_item(found) if stands == "next" else None
def bundle_candidates(found: list[Item], first: Item) -> list[Item]:
"""The items of first's release, in the table's order, that a chunk taking first may take too: those that do not wait once the chunk's own items count as done."""
chunk = {item.id for item in found if item.release == first.release}
@@ -332,6 +266,11 @@ def release_of(version: str) -> tuple[int, int, int]:
return major, minor, patch
def version(release: tuple[int, int, int]) -> str:
"""The version a release names, such as 0.2.1: release_of's inverse."""
return ".".join(map(str, release))
def check_cells(row: str, named: dict[str, str]) -> Failure | None:
"""Holds the row's ID, Release, Exempt and Item cells to the format: why one breaks it, None when none does."""
id_, release, exempt, tagline = named["ID"], named["Release"], named["Exempt"], named["Item"]
+25
View File
@@ -2182,3 +2182,28 @@ Inherited architect, decided by:
- Locality, Overall: `bin/todo_table.py:223` `renames`: the answer sits in the file read, where `renamed` replayed the plan's history
- Locality: `bin/larv_review/plan.py:27` `emptied`: renamed is a parameter, no hidden second derivation
- Navigation, Self-sufficiency: `bin/chunk_preflight/gathered.py:100` `planned`: the stop names the fix and where it goes
## 2026-10-18T09:10:02Z, PR #316 at 3eb3217, against 6e0fda4
Ruling: better
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Mid A | better | better | better | same | better |
| Inherited architect | better | better | better | same | better |
Mid A, decided by:
- Navigation, Locality, Shape: `bin/chunk_pick.py:92` `chunk_item`: returns one of five dataclasses, each carrying its release, where 6e0fda4's `(Standing, Item | None)` tuple made `planned` recompute the earliest release; the pick lives in one module named for it
- Shape, Navigation: `bin/git_repo.py:1` `git_repo`: the git wrapper no longer imports the plan model or builds todo.md objects; `default_plan` and `todos_since` sit beside the logic that reads them
- Shape, Locality: `bin/chunk_pick.py:97` `standing`: names `first_named` and states the rule plainly, where 6e0fda4's `min(... named | {earliest} ...)` had to be decoded
- Shape: `bin/chunk_preflight/choices.py:1` `choices`: the pure decisions left `gathered.py`, so each module's name tells what it holds
- Locality, Navigation: `bin/todo_table.py:269` `version`: one release formatter beside `release_of`, where 6e0fda4 had three
- Shape: `bin/chunk_pick.py:118` `unreleased_changes`: with `committed_since_release`, the names say what is counted, where "landed" hid it
Inherited architect, decided by:
- Navigation, Locality: `bin/chunk_pick.py:97` `standing`: "preflight says a release is ready to cut and it isn't" now lands in one module, where 6e0fda4 spread it over a table parser, a git wrapper importing it, and the preflight's wording
- Locality, Shape: `bin/chunk_preflight/choices.py:24` `planned`: each pick variant carries its release, so the messages read straight off it, where 6e0fda4 paired a recomputed `earliest` with a string by hand
- Shape: `bin/chunk_preflight/gathered.py:1` `gathered`: data only, with the choices in `choices.py`, though `facts.py` imports `PULLS_LIST` from the decision module
- Shape: `bin/chunk_pick.py:118` `unreleased_changes`: with `committed_since_release` and one `version`, the names say what they count
+4
View File
@@ -653,3 +653,7 @@ Read most (opens and searches):
Read most (opens and searches):
- `rules/decisions.md` 1
## Reading cost, chunk d905b642140f, finished 2026-10-18T08:20:12Z
187066 new input tokens before the first commit.
+2 -15
View File
@@ -12,7 +12,6 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 177 | 0.2.0 | | | **Move the next chunk's pick, from `LastCut` and `standing` to `chunk_item` and `default_plan`, into one module named for it, so `git_repo` only runs git and `todo_table` only parses the plan.** | 3 | 1 | 3 | 5 | 4 | 1.1 by 4 | 3.6 |
| 188 | 0.2.0 | | | **Weigh each achieve goal only a little less than the one above it, so a goal far down a project's list still counts almost as much as its first.** | 2 | 2 | 3 | 5 | 3 | 1.2 by 4 | 3.6 |
| 180 | 0.2.0 | | | **Accept an escalation quote only from transcript entries after the worker's last step-up, so a trigger that fires after an interrupt or a quoted answer stepped the worker steps it again.** | 3 | 2 | 3 | 6 | 5 | 1.1 by 4 | 2.2 |
| 189 | 0.2.0 | | | **State one achieve goal for the health of a project's code in `~/.claude`, which every project's ranking weighs, most while its comprehension panel's overall is under 7.0, unless its README voids it.** | 4 | 2 | 3 | 7 | 6 | 1.1 by 6 | 1.8 |
@@ -91,18 +90,6 @@
## Details
### 177. Move the next chunk's pick, from `LastCut` and `standing` to `chunk_item` and `default_plan`, into one module named for it, so `git_repo` only runs git and `todo_table` only parses the plan.
Raised by PR #302's paired ruling, where two of four seats read the project as worse at these places. Item 161 put the pick in `bin/todo_table.py` (`Standing`, `LastCut`, `unreleased_entries`, `landed`, `named_releases`, `standing`, `chunk_item`) and its reader in `bin/git_repo.py` (`DefaultPlan`, `default_plan`, `todos_since`), so the git module now imports the plan model and the table parser decides how a release stands. Make each of those places easier to read:
- `bin/git_repo.py` → `DefaultPlan`: the git module knows todo.md and CHANGELOG.md.
- `bin/todo_table.py` → `standing`: a five-state literal whose three-line comment must be decoded first, and whose `named` set comes from `named_releases`' fold over the `## Renamed` marks, read separately.
- `bin/git_repo.py` → `todos_since`: it promises the texts oldest first, an order `named_releases` needs, stated again in `LastCut`'s comment; let the pick's module own that order.
- `bin/todo_table.py` → `landed`: it counts ## Unreleased entries first, while `bin/larv_review/git.py` → `landed_since_release` counts commits only, two meanings of "work has landed"; give them one meaning or two names.
- `bin/loop_claude/loop/main.py` → `run_loop`: routing reads the plan as chunk-preflight's fetch left it, an order only a comment states.
- `bin/chunk_preflight/gathered.py`: the name covers the data, not the pure choices it also holds.
- `bin/chunk_preflight/gathered.py` → `planned`: the "finished and ready to cut" message cannot name the release that finished, which `standing` works out, so the human has to find it; let the pick's module return that release and the message name it.
### 188. Weigh each achieve goal only a little less than the one above it, so a goal far down a project's list still counts almost as much as its first.
Today `rank_todo.py` gives the goal ranked k of n its sum-reciprocal weight, (1/k) / (1 + 1/2 + … + 1/n). The fifth goal weighs a fifth of the first, and in a project with twelve achieve goals the last weighs a twelfth. lilleman, 2026-10-18: goals should matter almost as much as each other, each a tiny bit less than the one above it. Pick a weight that falls by a small step per rank, such as a geometric step close to 1, and show what it gives for 5 and for 15 achieve goals. Revise the decision entry of 2026-10-16, PR #283, that names the sum-reciprocal weight, and `rank_todo.py --help`. A maintain goal restored by a defect keeps weighing as the heaviest achieve goal.
@@ -396,7 +383,7 @@ Replaces item 62, which release 0.3.0's items split. PR #257's scoring run put L
Shape is the lowest dimension, so this item moves goal 1.1 by 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
PR #257's scoring run put Shape at 6.25, the lowest dimension. `bin/` holds about 30 entries: 6 launchers, 6 tool packages, 3 shared packages and 13 root modules. Two root modules are tools (`rank_todo.py`, `statusline.py`) and 11 are shared libraries, and nothing in the layout tells them apart; only README's import-root paragraph maps them. Candidate packages: git running and parsing, the todo table with `rank_todo.py`'s formula language and goal weighing, and the comprehension history with round titles. `rank_todo.py` keeps its path, which every project's rules name. The `.gitignore` allowlist and README follow the move.
PR #257's scoring run put Shape at 6.25, the lowest dimension. `bin/` holds about 30 entries: 6 launchers, 6 tool packages, 3 shared packages and 15 root modules. Two root modules are tools (`rank_todo.py`, `statusline.py`) and 13 are shared libraries, and nothing in the layout tells them apart; only README's import-root paragraph maps them. Candidate packages: git running and parsing, the todo table with `rank_todo.py`'s formula language and goal weighing, and the comprehension history with round titles. `rank_todo.py` keeps its path, which every project's rules name. The `.gitignore` allowlist and README follow the move.
### 156. Drop `rank_todo.py`'s ranking of an old-shape table once no project under `~/code` holds one.
@@ -404,7 +391,7 @@ While `rank_todo.py` ranks two shapes, projects follow two sets of scoring rules
### 155. Lower the reading cost of the files a chunk reads most before its first commit.
`bin/reading-cost` on 2026-10-17: the median of the last 5 chunks is 117,108 new input tokens before their first commit, up from 107,738 for the 5 before them. Read most over the last 5, by opens and searches: `bin/loop_claude/test_loop_claude.py` 14, `todo.md` 11, `bin/loop_claude/test_black_box.py` 10, `bin/rank_todo.py` 6, `CHANGELOG.md` 5, `README.md` 5, `docs/decisions.md` 4, `.gitignore` 3, `bin/loop_claude/routing.py` 2, `bin/markdown_text.py` 2. The chunk that ships this item runs `bin/reading-cost --reset`.
`bin/reading-cost` on 2026-10-18: the median of the last 5 chunks is 133,110 new input tokens before their first commit, up from 107,738 for the 5 before them. Read most over the last 5, by opens and searches: `todo.md` 4, `rules/todo-items.md` 2, `rules/decisions.md` 1. The chunk that ships this item runs `bin/reading-cost --reset`.
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.