Merge pull request 'Run a preflight before each fresh worker and put its facts in the worker's prompt' (#302) from item-161 into main

This commit was merged in pull request #302.
This commit is contained in:
2026-10-17 20:16:21 +02:00
29 changed files with 1593 additions and 162 deletions
+3
View File
@@ -17,6 +17,9 @@
!agents/
!agents/*.md
!bin/
!bin/chunk-preflight
!bin/chunk_preflight/
!bin/chunk_preflight/*.py
!bin/claude_code/
!bin/claude_code/*.py
!bin/comprehension_history.py
+1
View File
@@ -14,6 +14,7 @@
- `rule-hook` refuses an Agent call that launches a reviewer, a comprehension seat or the security pass on a rung below the one `loop-claude` names for it, and takes no override: pass the model and effort the refusal names.
- `score-outcomes` lists a project's score anchors: the shipped items its `docs/score-anchors.md` names for each level of L, E and I, each with what its chunk measured. `rules/todo-items.md` has a scorer compare a new item with them, and says how to choose two or three per level. Add the file to each project that merges with merge commits; elsewhere, score by the level descriptions in `rules/todo-items.md`.
- `loop-claude` archives each judge reply it rejects in the chunk's `<sha256>.outcomes.md`, with the reason and the reply as json. Before, such a reply reached only stderr, so a run that exited 1 overnight could not say what the judge had returned. stderr now prints only the reason; the reply is in outcomes.md. If archiving fails, `loop-claude` exits 1.
- `loop-claude` routes each chunk on `todo.md` as the default branch holds it, freshly fetched: merge a `todo.md` edit before the chunk it should route starts. Where `todo.md` holds no item for the next release, the earliest release it has named since the newest tag, no item routes the chunk, and the worker is told that release is finished and ready to cut, or, where no work has landed since the tag, to be planned first. Before routing, `loop-claude` runs the new `bin/chunk-preflight` and quotes what it prints in the worker's first prompt: the chunk's mechanical facts, which `chunk-preflight --help` lists. The preflight also makes the chunk's worktree, `<checkout>-item-<ID>` beside the checkout on the branch `item-<ID>`, or continues the one already there, and leaves an uncommitted figure in that worktree's `docs/reading-cost.md` for the chunk to commit. It stops a fetch, forge CLI or tool after 60 seconds, or after the seconds `CHUNK_PREFLIGHT_TIMEOUT` sets. The prompt also asks the worker to count the item's size again once it has read the code, and to have the item re-scored where its L would change. Expect the worker to start editing sooner.
## 0.1.0
+2 -1
View File
@@ -10,7 +10,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
- **When the next release has no items left and work has landed towards it, it is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix lands, into that release; never start a later release's items or plan a new one.
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that publishes nothing says so once.
- **Read the README's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
- **Read the plan and the decisions only as far as the chunk needs.** Run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes. `AGENTS.md` lists every decision's title. Read the entry under a title in `docs/decisions.md` only where the title leaves open what the chunk or the review needs.
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and the items that may join it; read further only what they leave out. Otherwise run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes. `AGENTS.md` lists every decision's title. Read the entry under a title in `docs/decisions.md` only where the title leaves open what the chunk or the review needs.
- **Work one chunk at a time, and make it as large as one purpose allows.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which four things hold: one PR title states what they achieve together, without listing them; they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need neither a shared purpose nor the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in `todo.md` before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
- **Ask, don't guess.** First check whether the goals already answer the question. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Write every answer once, where it belongs, never only in chat: a goal in `README.md`, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the README, and record as a choice only what the goal leaves open.
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the README's `## Audience`, picks it.
@@ -78,6 +78,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
- When the work has a ticket, read it before starting: verify the change matches it and pull useful context from it.
- PR summary: short and concise. No test plan (it lives in the ticket), no link to the ticket (it's in the title).
- Branch for a ticket: exactly the ticket ID, nothing more. `ABC-123`, never `ABC-123-some-description`.
- Branch for a `todo.md` item without a ticket: `item-<ID>`, in the worktree `<checkout>-item-<ID>` beside the checkout, as `chunk-preflight` makes them.
- Use `gh` on GitHub remotes and `tea` on Gitea remotes (e.g. `gitea.larvit.se`) — same command shape: `tea pr list|create`, `tea issue`, `tea release`, `tea api`. Everything in this section applies to both.
## Handoffs
+2 -1
View File
@@ -82,6 +82,7 @@ Rename `## Unreleased` in `CHANGELOG.md` to the version, commit, tag that commit
Install puts only `loop-claude` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout.
- `chunk-preflight` finds the mechanical facts a chunk starts from and makes its worktree; `loop-claude` runs it before it routes each chunk, and `chunk-preflight --help` lists the facts.
- `judge-replay <model>` replays loop-claude's judge on archived verdicts of the projects run on the model, and prints the lowest rung that, like each rung above it, returns them; `judge-replay --help` states the replay.
- `larv-review <command>` holds larv-review's mechanical rules: the paired ruling's base and vote count, each pass's round count, the scoring run's trigger, and the comprehension history's format and latest places; `larv-review --help` states them.
- `loop-claude <task>` runs a project's next chunk cycle after cycle; `loop-claude --help` states its contract.
@@ -109,7 +110,7 @@ pytest_add_cli_args=-k
Then, in the copy: `uvx --with pytest 'mutmut>=3,<4' run && uvx --with pytest 'mutmut>=3,<4' results`, and `uvx --with pytest 'mutmut>=3,<4' show <mutant>` to see a mutant's change. The config keys are mutmut 3's.
`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; `rank_todo.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge. `judge_replay` and `stability_replay` share `rung_replay/`: the rung search, and the argument, candidate rungs and exits. It reads `loop_claude`'s retry count and models file. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
`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; `rank_todo.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge, and `loop_claude` runs `chunk-preflight` as a process of its own. `judge_replay` and `stability_replay` share `rung_replay/`: the rung search, and the argument, candidate rungs and exits. It reads `loop_claude`'s retry count and models file. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
## Tracking a new file
+10
View File
@@ -0,0 +1,10 @@
#!/usr/bin/env python3
import os
import pathlib
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from chunk_preflight import main
sys.exit(main.main(sys.argv[1:], os.environ))
View File
+102
View File
@@ -0,0 +1,102 @@
"""The lines the preflight prints, stated from what it gathered."""
from todo_table import bundle_candidates, Item, LastCut, unreleased_entries
from failure import Failure
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, PULLS_LIST, Ran, version
from markdown_text import quoted
def render(found: Gathered) -> list[str]:
"""One `- ` line per fact, then the item's tagline and detail, and what each tool printed."""
note = [f"- {found.note}"] if found.note else []
head = [*note, f"- {last_release(found.default, found.cut)}"]
if isinstance(found.item, NoItem):
return [*head, f"- No plan item: {found.item.why} No worktree was made."]
return [*head, *item_lines(found.default, found.item)]
def last_release(default: str, release: LastCut) -> str:
if isinstance(release.tag, Failure):
return f"Last version cut: cannot be read: {release.tag.reason}"
cut = f"Last version cut: {release.tag or 'none'}."
entries = unreleased_entries(release.changelog) if isinstance(release.changelog, str) else None
if entries is not None:
return f"{cut} Unreleased: {counted(entries, 'entry', 'entries')} under CHANGELOG.md → ## Unreleased."
since = f"since {release.tag}" if release.tag else f"on {default}"
commits = f"the commits {since} cannot be counted: {release.commits.reason}" if isinstance(release.commits, Failure) else f"{counted(release.commits, 'commit', 'commits')} {since}"
changelog = f"CHANGELOG.md cannot be read: {release.changelog.reason}" if isinstance(release.changelog, Failure) else "no ## Unreleased in CHANGELOG.md"
return f"{cut} Unreleased: {commits}; {changelog}."
def item_lines(default: str, item: ItemFacts) -> list[str]:
first = item.plan.first
worktree = item.worktree.reason if isinstance(item.worktree, Failure) else f"{item.worktree.path}, {item.worktree.how}"
return [
f"- The earliest release in {default}'s todo.md: {version(first.release)}. Its first item that does not wait: item {first.id}, {levels(first)}.",
f"- Worktree: {worktree}",
f"- Open pull requests from {item.plan.branch}: {pulls_text(item.pulls, item.plan.branch)}",
*bundled(item.plan),
*named_lines(item.named),
f"\nItem {first.id}'s tagline and detail:\n\n{quoted(item.plan.text)}",
*(f"\n{printed(shown, done)}" for shown, done in item.tools),
]
def pulls_text(pulls: tuple[Forge, Ran | Failure] | None, branch: str) -> str:
"""Each open pull request from branch, by its number and URL, or why none can be listed. No title: on a public forge anyone may open one, and its title would reach the worker's prompt."""
if pulls is None:
return "none, as the checkout has no origin remote."
forge, done = pulls
shown = " ".join(PULLS_LIST[forge])
if isinstance(done, Failure):
return f"cannot be listed: `{shown}` {done.reason}"
if done.code:
return f"cannot be listed: `{shown}` exited {done.code}: {done.stderr.strip()}"
return ", ".join(open_pulls(done.stdout, forge, branch)) or "none."
def open_pulls(stdout: str, forge: Forge, branch: str) -> list[str]:
"""Each open pull request from branch in the rows pulls_command printed, as `#<number> <URL>`: gh prints only branch's pull requests, as number and URL; tea prints every pull request, as index, head and URL, under a header row."""
rows = [line.split("\t") for line in stdout.splitlines()]
if forge == "gh":
return [f"#{row[0]} {row[1]}" for row in rows if len(row) == 2]
return [f"#{row[0]} {row[2]}" for row in rows if len(row) == 3 and row[1] == branch]
def bundled(plan: Plan) -> list[str]:
first, candidates = plan.first, bundle_candidates(plan.items, plan.first)
if not candidates:
return [f"- No other item of release {version(first.release)} may join item {first.id}'s chunk."]
listed = [f" - item {item.id}, {levels(item)}, S {item.scores['S']}: {item.tagline}" for item in candidates]
return [f'- The items of release {version(first.release)} that may join the chunk of item {first.id}, where `~/.claude/CLAUDE.md` → "Working loop" lets them share it:', *listed]
def named_lines(named: list[NamedPath] | Failure) -> list[str]:
if isinstance(named, Failure):
return [f"- The files the item names: cannot be listed: {named.reason}"]
if not named:
return ["- The item names no file or folder git tracks."]
return ["- The files and folders the item names:", *(f" - `{path.span}`: {size(path)}" for path in named)]
def size(path: NamedPath) -> str:
if path.lines is None:
return counted(path.files, "file", "files")
if isinstance(path.lines, Failure):
return f"cannot be read: {path.lines.reason}"
return counted(path.lines, "line", "lines")
def printed(shown: str, done: Ran | Failure) -> str:
"""What a tool printed and its exit code, under its command line."""
if isinstance(done, Failure):
return f"`{shown}` {done.reason}"
output = "\n".join(part.strip() for part in (done.stdout, done.stderr) if part.strip())
return f"`{shown}` exited {done.code}, printing:\n\n{quoted(output)}" if output else f"`{shown}` exited {done.code}, printing nothing."
def levels(item: Item) -> str:
return f"L {item.likelihood or 'unscored'}, E + I {item.escape_and_impact or 'unscored'}"
def counted(count: int, one: str, many: str) -> str:
return f"{count} {one if count == 1 else many}"
+150
View File
@@ -0,0 +1,150 @@
"""What the preflight gathers, and the pure choices its steps act on; facts.render states it."""
import dataclasses
import pathlib
import re
import typing
from todo_table import chunk_item, Item, item_details, items, LastCut
from failure import Failure
# 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)
class Ran:
"""A command that ran to its end: its exit code and what it printed."""
code: int
stdout: str
stderr: str
@dataclasses.dataclass(frozen=True)
class Plan:
"""The default branch's todo.md items, and `first`: the item the next chunk takes first."""
items: list[Item]
first: Item
# first's tagline and detail.
text: str
@property
def branch(self) -> str:
"""The branch first's worktree is on."""
return f"item-{self.first.id}"
@dataclasses.dataclass(frozen=True)
class NoItem:
"""Why the plan names no item for the next chunk, as a sentence the worker reads."""
why: str
@dataclasses.dataclass(frozen=True)
class Worktree:
path: pathlib.Path
# How it came to be, as the worker reads it.
how: str
@dataclasses.dataclass(frozen=True)
class NamedPath:
"""A tracked file or folder the item names, with how many tracked files it holds."""
span: str
files: int
# A file's lines, or why they cannot be read; None for a folder.
lines: int | Failure | None
@dataclasses.dataclass(frozen=True)
class ItemFacts:
"""What the preflight found or made for the plan's first item."""
plan: Plan
worktree: Worktree | Failure
# The forge whose CLI listed the open pull requests, and how it ran; None without an origin remote.
pulls: tuple[Forge, Ran | Failure] | None
named: list[NamedPath] | Failure
# Each tool run in the worktree, by its command line, and how it ran; none without a worktree.
tools: list[tuple[str, Ran | Failure]]
@dataclasses.dataclass(frozen=True)
class Gathered:
"""Everything the preflight read and ran, for facts.render to state."""
# The default branch's ref, such as origin/main.
default: str
# Why origin reads as last fetched; None after a fetch.
note: str | None
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 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]
+162
View File
@@ -0,0 +1,162 @@
"""Find the mechanical facts a chunk starts from, and make its worktree, so its worker starts from them.
usage: chunk-preflight
Run it inside a project checkout. loop-claude runs it at the checkout root before each chunk's
first worker, before it routes the chunk, and quotes what it prints in the worker's prompt. It
fetches origin, when the checkout has that remote, and takes origin's default branch, or else the
local main or master. It leaves the checkout as it is, and reads todo.md as the default branch
holds it, the plan loop-claude routes on. It prints:
- the newest v* tag on the default branch, and how many entries the default branch's CHANGELOG.md
holds under ## Unreleased, or else how many commits followed the tag;
- the next release and its first item that does not wait, the item loop-claude routes on, with
its L and E + I. An item waits while it is marked question, or while an item still in todo.md
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; 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 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
item-<ID>. It continues a worktree already on that branch; else it adds one on the local branch,
else on a new branch tracking origin's, else on a new branch off the default branch;
- the open pull requests whose head is the item's branch, each by its number and URL, as gh lists
them on a github.com origin, and else as tea does. No title reaches the output;
- the items of that release that a chunk taking the item may take too: those that are not
questions and that no item outside the chunk blocks;
- each file or folder git tracks that the item's tagline or detail names in backticks, with a
file's lines or a folder's files, and the item's tagline and detail;
- what `rank_todo.py --check todo.md`, `larv-review needs-scoring-run <ID>`, `reading-cost` and
`larv-review places` print in the worktree, each with its exit code. reading-cost appends to the
worktree's docs/reading-cost.md, for the chunk to commit.
A fact it cannot find it says it cannot, and why, and goes on. A fetch, forge CLI or tool still
running after {timeout} seconds, or after the seconds CHUNK_PREFLIGHT_TIMEOUT sets, is stopped; a
stopped fetch reads origin as last fetched. With no item, it makes no worktree and runs none of
those four tools.
Exit 1, saying why, on any argument, on a CHUNK_PREFLIGHT_TIMEOUT that is no number of seconds
above 0, or when git cannot start or finds no checkout or no default branch.
"""
import pathlib
import re
import subprocess
import sys
import typing
from git_repo import commit_exists, default_branch, default_plan, file_at, git, top
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.facts import render
BIN = pathlib.Path(__file__).resolve().parents[1]
# Each tool run in the item's worktree, {item} standing for the item's ID.
TOOLS = (("rank_todo.py", "--check", "todo.md"), ("larv-review", "needs-scoring-run", "{item}"), ("reading-cost",), ("larv-review", "places"))
# Seconds before a fetch, forge CLI or tool is stopped, so a hung one cannot keep the rest from printing; TIMEOUT_SETTING overrides it.
TIMEOUT = 60
TIMEOUT_SETTING = "CHUNK_PREFLIGHT_TIMEOUT"
def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
if argv in (["-h"], ["--help"]):
print(__doc__.strip().format(timeout=TIMEOUT))
return 0
if argv:
print(f"unknown arguments {' '.join(argv)}; usage: chunk-preflight", file=sys.stderr)
return 1
printed = run(env.get(TIMEOUT_SETTING))
if isinstance(printed, Failure):
print(printed.reason, file=sys.stderr)
return 1
print("\n".join(printed))
return 0
def run(setting: str | None) -> list[str] | Failure:
"""The preflight's lines, given what TIMEOUT_SETTING holds; a Failure where that is no number of seconds, or git finds no checkout or no default branch."""
timeout = seconds(setting)
if isinstance(timeout, Failure):
return timeout
root = top()
return root if isinstance(root, Failure) else preflight(pathlib.Path(root), timeout)
def seconds(setting: str | None) -> float | Failure:
"""The timeout setting as seconds, TIMEOUT where unset; a Failure where it is no number above 0."""
if setting is None:
return TIMEOUT
if re.fullmatch(r"[0-9]+(\.[0-9]+)?", setting) and float(setting) > 0:
return float(setting)
return Failure(f"{TIMEOUT_SETTING}={setting!r} is no number of seconds above 0")
def preflight(root: pathlib.Path, timeout: float) -> list[str] | Failure:
"""Gathers the facts step by step, each step taking what the ones before it found, and renders them; a Failure where the checkout has no default branch."""
default = default_branch(stale_ok=True, timeout=timeout)
if isinstance(default, Failure):
return default
ref, note = default
held = default_plan(str(root), ref)
plan = planned(held.todo, held.cut, ref)
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout)
return render(Gathered(ref, note, held.cut, item))
def item_facts(root: pathlib.Path, default: str, plan: Plan, timeout: float) -> ItemFacts:
worktree = item_worktree(root, plan.branch, default)
path = worktree.path if isinstance(worktree, Worktree) else None
return ItemFacts(plan, worktree, pull_listing(root, plan.branch, timeout), named_files(plan.text, path or root), tools_run(plan.first.id, path, timeout) if path else [])
def item_worktree(root: pathlib.Path, branch: str, default: str) -> Worktree | Failure:
"""The worktree on branch, made where none is; a Failure where git cannot make it, or its path holds something else."""
listing = git("worktree", "list", "--porcelain")
if isinstance(listing, Failure):
return listing
if (path := worktree_on(listing, branch)) is not None:
return Worktree(path, f"continued, on the branch {branch}.")
path = root.parent / f"{root.name}-{branch}"
if path.exists():
return Failure(f"none made, since {path} exists and holds no worktree on the branch {branch}")
args, how = worktree_add(branch, path, default, commit_exists(f"refs/heads/{branch}"), commit_exists(f"refs/remotes/origin/{branch}"))
added = git(*args)
return Failure(f"none made: {added.reason}") if isinstance(added, Failure) else Worktree(path, how)
def pull_listing(root: pathlib.Path, branch: str, timeout: float) -> tuple[Forge, Ran | Failure] | None:
url = git("remote", "get-url", "origin")
if isinstance(url, Failure):
return None
forge = forge_of(url)
return forge, ran(pulls_command(forge, branch), root, timeout)
def named_files(text: str, base: pathlib.Path) -> list[NamedPath] | Failure:
tracked = git("-C", str(base), "ls-files")
if isinstance(tracked, Failure):
return tracked
return [NamedPath(span, files, line_count(base / span)) for span, files in named_paths(text, tracked.splitlines())]
def line_count(path: pathlib.Path) -> int | Failure | None:
"""A file's lines, or why they cannot be read; None for a folder."""
if not path.is_file():
return None
try:
return len(path.read_text(encoding="utf-8").splitlines())
except (OSError, UnicodeDecodeError) as failure:
return Failure(str(failure))
def tools_run(item_id: int, worktree: pathlib.Path, timeout: float) -> list[tuple[str, Ran | Failure]]:
commands = [[part.format(item=item_id) for part in tool] for tool in TOOLS]
return [(" ".join(command), ran([sys.executable, str(BIN / command[0]), *command[1:]], worktree, timeout)) for command in commands]
def ran(command: list[str], cwd: pathlib.Path, timeout: float) -> Ran | Failure:
try:
done = subprocess.run(command, capture_output=True, cwd=cwd, encoding="utf-8", errors="replace", stdin=subprocess.DEVNULL, timeout=timeout)
except (OSError, subprocess.TimeoutExpired) as failure:
return Failure(f"could not finish: {failure}")
return Ran(done.returncode, done.stdout, done.stderr)
+499
View File
@@ -0,0 +1,499 @@
import os
import pathlib
import shutil
import subprocess
import sys
import tempfile
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 test_env import isolated_env
from todo_table import LastCut, unreleased_entries
from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
from chunk_preflight.facts import open_pulls, render
BIN = pathlib.Path(__file__).resolve().parents[1]
README = "# Project\n\n## Goals\n\n1. **Achieve:** Work.\n\n## Audience\n\nMe.\n"
# Item 3 is the next release's first item that does not wait; 7 waits only on 3, 5 is a question, 8 waits on 5, 9 is in a later release.
TODO = """# todo
## Scoring
`Score = 100 * V / (2**S + 8)`
`Bar = 0.1`
`Next ID = 10`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 5 | 0.2.0 | | question | **Ask first.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 90.0 |
| 3 | 0.2.0 | | | **Do the next thing.** | 4 | 2 | 3 | 7 | 3 | 1 by 9 | 56.2 |
| 7 | 0.2.0 | 3 | | **Do the thing after.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |
| 8 | 0.2.0 | 5 | | **Do the answered thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |
| 9 | 0.3.0 | | | **Do a later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 90.0 |
## Details
### 3. Do the next thing.
Change `src/app.py`'s `run` and the files under `src`, not `gone.py`.
"""
# The plan once item 3 has shipped: item 7 no longer waits, and its detail names the files.
SHIPPED = TODO.replace("| 3 | 0.2.0 | | | **Do the next thing.** | 4 | 2 | 3 | 7 | 3 | 1 by 9 | 56.2 |\n", "").replace("| 7 | 0.2.0 | 3 |", "| 7 | 0.2.0 | |").replace("### 3. Do the next thing.", "### 7. Do the thing after.")
# The plan once release 0.2.0 has shipped all its items: only release 0.3.0's item 9 is left.
LATER = TODO[:TODO.index("| 5 |")] + "| 9 | 0.3.0 | | | **Do a later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 90.0 |\n"
# An items table that holds no row.
EMPTY = TODO[:TODO.index("| 5 |")]
CHANGELOG = "# Changelog\n\n## Unreleased\n\n- One.\n - A nested line.\n- Two.\n\n## 0.1.0\n\n- Old.\n"
# What the preflight reads of the last release: tag v0.1.0, two entries under ## Unreleased, and 4 commits since the tag.
CUT = LastCut("v0.1.0", CHANGELOG, 4, [])
# Two open pull requests, as `tea pulls list --fields index,head,url --output tsv` prints them; anything else exits 1.
FAKE_TEA = "#!/bin/sh\n[ \"$*\" = 'pulls list --fields index,head,url --output tsv' ] || exit 1\nprintf 'index\\thead\\turl\\n12\\titem-7\\thttps://forge/pulls/12\\n13\\tother\\thttps://forge/pulls/13\\n'\n"
# Item 3's open pull request, as `gh pr list` prints it through the preflight's template; any other arguments exit 1.
FAKE_GH = """#!PYTHON
import sys
if sys.argv[1:] != ["pr", "list", "--head", "item-3", "--json", "number,url", "--template", "{{range .}}{{.number}}\\t{{.url}}\\n{{end}}"]:
sys.exit(1)
print("12\\thttps://github.com/o/r/pull/12")
""".replace("PYTHON", sys.executable)
class Repo:
"""An origin with a tagged release, a clone of it at <temp>/proj, and a fake tea and gh on PATH."""
def __init__(self, test, todo=TODO, origin="origin.git", changelog=CHANGELOG):
temp = tempfile.TemporaryDirectory()
test.addCleanup(temp.cleanup)
self.temp = pathlib.Path(os.path.realpath(temp.name))
self.origin = self.temp / origin
self.root = self.temp / "proj"
self.fake = self.temp / "fake-bin"
self.fake.mkdir()
for name, script in (("gh", FAKE_GH), ("tea", FAKE_TEA)):
(self.fake / name).write_text(script)
(self.fake / name).chmod(0o755)
(self.fake / "git").symlink_to(shutil.which("git"))
self.env = {**isolated_env(), "GIT_CONFIG_GLOBAL": os.devnull, "GIT_CONFIG_NOSYSTEM": "1", "HOME": str(self.temp / "home"), "PATH": str(self.fake), "LOOP_CLAUDE_TRANSCRIPTS": str(self.temp / "archive")}
self.git(self.temp, "init", "--quiet", "--bare", "--initial-branch=main", str(self.origin))
self.git(self.temp, "clone", "--quiet", str(self.origin), str(self.root))
self.write(self.root, "README.md", README)
self.write(self.root, "src/app.py", "def run():\n\treturn 1\n\n")
self.commit(self.root, "start")
self.git(self.root, "tag", "v0.1.0")
self.write(self.root, "CHANGELOG.md", changelog)
if todo:
self.write(self.root, "todo.md", todo)
self.commit(self.root, "plan")
self.git(self.root, "push", "--quiet", "origin", "main", "v0.1.0")
def git(self, cwd, *args):
return subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@example.com", *args], capture_output=True, check=True, cwd=cwd, env=self.env, text=True).stdout
def write(self, root, path, text):
(root / path).parent.mkdir(parents=True, exist_ok=True)
(root / path).write_text(text)
def commit(self, root, title):
self.git(root, "add", "-A")
self.git(root, "commit", "--quiet", "-m", title)
def push_from_elsewhere(self, path, text):
"""Pushes a change to path from another clone, leaving the checkout behind origin."""
other = self.temp / "other"
self.git(self.temp, "clone", "--quiet", str(self.origin), str(other))
self.write(other, path, text)
self.commit(other, "elsewhere")
self.git(other, "push", "--quiet", "origin", "main")
def stub_git(self, arm):
"""Puts a git on PATH that runs arm, a shell case arm, on its arguments, and the real git on any others."""
stub = self.fake / "git"
stub.unlink()
stub.write_text(f'#!/bin/sh\ncase "$*" in\n{arm}\nesac\nexec {shutil.which("git")} "$@"\n')
stub.chmod(0o755)
def preflight(self, **env):
return subprocess.run([sys.executable, str(BIN / "chunk-preflight")], capture_output=True, cwd=self.root, env={**self.env, **env}, text=True, timeout=120)
class ChunkPreflightTool(unittest.TestCase):
def test_reads_the_fetched_default_branchs_plan_and_makes_the_items_worktree_off_it_leaving_the_checkout_as_it_was(self):
repo = Repo(self)
repo.push_from_elsewhere("todo.md", SHIPPED)
# Claude Code rewrites tracked files, such as settings.json, so a checkout behind origin often holds changes.
repo.write(repo.root, "todo.md", TODO + "\nA change of the checkout's own.\n")
head = repo.git(repo.root, "rev-parse", "HEAD")
done = repo.preflight()
self.assertEqual(done.returncode, 0, done.stderr)
self.assertEqual(repo.git(repo.root, "rev-parse", "HEAD"), head)
worktree = repo.temp / "proj-item-7"
self.assertEqual(repo.git(worktree, "rev-parse", "--abbrev-ref", "HEAD").strip(), "item-7")
self.assertEqual(repo.git(worktree, "rev-parse", "HEAD"), repo.git(repo.root, "rev-parse", "origin/main"))
for fact in (
"item 7, L 1, E + I 2",
str(worktree),
"item-7, made off origin/main",
"#12 https://forge/pulls/12",
"`src/app.py`: 3 lines",
"`src`: 1 file",
"`rank_todo.py --check todo.md` exited 0",
"`larv-review needs-scoring-run 7` exited 0",
"`reading-cost` exited 0",
"`larv-review places` exited 0",
f"{worktree}/docs/reading-cost.md",
):
with self.subTest(fact=fact):
self.assertIn(fact, done.stdout)
self.assertNotIn("#13", done.stdout)
self.assertNotIn("`gone.py`:", done.stdout)
def test_names_no_item_and_makes_no_worktree_where_the_release_after_the_last_cut_has_emptied(self):
for changelog, fact in ((CHANGELOG, "finished and ready to cut"), ("# Changelog\n\n## Unreleased\n\n## 0.1.0\n\n- Old.\n", "planned first")):
with self.subTest(fact=fact):
repo = Repo(self, changelog=changelog)
repo.write(repo.root, "todo.md", LATER)
repo.commit(repo.root, "ship 0.2.0")
repo.git(repo.root, "push", "--quiet", "origin", "main")
done = repo.preflight()
self.assertEqual(done.returncode, 0, done.stderr)
self.assertIn(fact, done.stdout)
self.assertNotIn("item 9", done.stdout)
self.assertFalse((repo.temp / "proj-item-9").exists())
def test_weighs_todo_md_at_the_last_cut_and_on_the_default_branch_after_it_alone(self):
"""Each case's plans: before the tag, at it, on a side branch merged after it, and after it, each committed in turn where given."""
cases = (
("a release named only before the cut", TODO, LATER, None, None, "item 9"),
("a release named at the cut", None, TODO, None, LATER, "finished and ready to cut"),
("a release named only on a side branch", None, LATER, TODO, None, "item 9"),
)
for name, before, at, side, after, fact in cases:
with self.subTest(name):
repo = Repo(self, todo="")
for todo, title in ((before, "before"), (at, "at")):
if todo is not None:
repo.write(repo.root, "todo.md", todo)
repo.commit(repo.root, title)
repo.git(repo.root, "tag", "--force", "v0.1.0")
if side is not None:
repo.git(repo.root, "switch", "--quiet", "-c", "side")
# The branch ends on a plan main never held, so the merge changes todo.md.
for todo in (side, LATER + "| 10 | 0.3.0 | | | **Do another later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 90.0 |\n"):
repo.write(repo.root, "todo.md", todo)
repo.commit(repo.root, "side")
repo.git(repo.root, "switch", "--quiet", "main")
repo.git(repo.root, "merge", "--quiet", "--no-ff", "-m", "merge side", "side")
if after is not None:
repo.write(repo.root, "todo.md", after)
repo.commit(repo.root, "after")
repo.git(repo.root, "push", "--quiet", "--force", "origin", "main", "v0.1.0")
done = repo.preflight()
self.assertEqual(done.returncode, 0, done.stderr)
self.assertIn(fact, done.stdout)
def test_continues_the_items_worktree_and_else_its_pushed_branch(self):
repo = Repo(self)
repo.preflight()
worktree = repo.temp / "proj-item-3"
continued = repo.preflight().stdout
self.assertIn(str(worktree), continued)
self.assertIn("continued", continued)
(worktree / "work.txt").write_text("work\n")
repo.git(worktree, "add", "work.txt")
repo.git(worktree, "commit", "--quiet", "-m", "work")
repo.git(worktree, "push", "--quiet", "origin", "item-3")
repo.git(repo.root, "worktree", "remove", "--force", str(worktree))
repo.git(repo.root, "branch", "--quiet", "-D", "item-3")
pushed = repo.preflight().stdout
self.assertIn(str(worktree), pushed)
self.assertIn("made off origin/item-3", pushed)
self.assertTrue((worktree / "work.txt").exists())
def test_makes_no_worktree_where_its_path_holds_something_else_and_runs_no_tool(self):
repo = Repo(self)
(repo.temp / "proj-item-3").mkdir()
done = repo.preflight()
self.assertIn(f"none made, since {repo.temp / 'proj-item-3'} exists", done.stdout)
self.assertNotIn("`reading-cost`", done.stdout)
def test_makes_no_worktree_and_runs_no_tool_where_git_cannot_add_it(self):
repo = Repo(self)
repo.temp.chmod(0o555)
self.addCleanup(repo.temp.chmod, 0o755)
done = repo.preflight()
self.assertEqual(done.returncode, 0, done.stderr)
self.assertIn("Worktree: none made: git worktree add", done.stdout)
self.assertNotIn("`reading-cost`", done.stdout)
self.assertFalse((repo.temp / "proj-item-3").exists())
def test_makes_no_worktree_and_runs_no_tool_where_git_cannot_list_the_worktrees(self):
repo = Repo(self)
repo.stub_git('"worktree list --porcelain") echo "listing broke" >&2; exit 1;;')
done = repo.preflight()
self.assertEqual(done.returncode, 0, done.stderr)
self.assertIn("listing broke", done.stdout)
self.assertNotIn("`reading-cost`", done.stdout)
self.assertFalse((repo.temp / "proj-item-3").exists())
def test_reads_origin_as_last_fetched_where_the_fetch_stalls_and_still_states_the_other_facts(self):
repo = Repo(self)
repo.stub_git(f'"fetch --quiet origin") exec {shutil.which("sleep")} 10;;')
done = repo.preflight(CHUNK_PREFLIGHT_TIMEOUT="1")
self.assertEqual(done.returncode, 0, done.stderr)
self.assertIn("as last fetched", done.stdout)
self.assertIn("item 3, L 4, E + I 5", done.stdout)
self.assertIn("`reading-cost` exited 0", done.stdout)
def test_lists_the_open_pull_requests_with_gh_on_a_github_origin(self):
repo = Repo(self, origin="github.com/o/r.git")
self.assertIn("#12 https://github.com/o/r/pull/12", repo.preflight().stdout)
def test_without_a_plan_states_the_release_facts_and_makes_no_worktree(self):
repo = Repo(self, todo="")
done = repo.preflight()
self.assertEqual(done.returncode, 0, done.stderr)
self.assertIn("v0.1.0", done.stdout)
self.assertIn("no items table", done.stdout)
self.assertFalse((repo.temp / "proj-item-3").exists())
def test_states_its_timeout_in_its_help(self):
done = subprocess.run([sys.executable, str(BIN / "chunk-preflight"), "--help"], capture_output=True, env=isolated_env(), text=True)
self.assertEqual(done.returncode, 0, done.stderr)
self.assertIn(f"after {TIMEOUT} seconds", done.stdout)
def test_exits_1_on_a_timeout_setting_that_is_no_number_of_seconds(self):
done = Repo(self).preflight(CHUNK_PREFLIGHT_TIMEOUT="soon")
self.assertEqual(done.returncode, 1)
self.assertIn("CHUNK_PREFLIGHT_TIMEOUT", done.stderr)
self.assertEqual(done.stdout, "")
def test_exits_1_without_a_default_branch(self):
with tempfile.TemporaryDirectory() as temp:
env = {**isolated_env(), "GIT_CONFIG_GLOBAL": os.devnull, "GIT_CONFIG_NOSYSTEM": "1"}
subprocess.run(["git", "init", "--quiet", "--initial-branch=trunk", temp], check=True, env=env)
done = subprocess.run([sys.executable, str(BIN / "chunk-preflight")], capture_output=True, cwd=temp, env=env, text=True)
self.assertEqual(done.returncode, 1)
self.assertIn("main or master", done.stderr)
self.assertEqual(done.stdout, "")
def test_exits_1_outside_a_checkout(self):
with tempfile.TemporaryDirectory() as temp:
done = subprocess.run([sys.executable, str(BIN / "chunk-preflight")], capture_output=True, cwd=temp, env={**isolated_env(), "GIT_CONFIG_NOSYSTEM": "1"}, text=True)
self.assertEqual(done.returncode, 1)
self.assertIn("git rev-parse --show-toplevel", done.stderr)
def item_facts(todo=TODO, **fields):
"""The facts of todo's next item, its worktree made, with fields given replacing the rest."""
return ItemFacts(**{"plan": planned(todo, CUT, "origin/main"), "worktree": Worktree(pathlib.Path("/c/proj-item-3"), "added on the new branch item-3, made off origin/main."), "pulls": None, "named": [], "tools": [], **fields})
def rendered(item, release=CUT, note=None):
return "\n".join(render(Gathered("origin/main", note, release, item)))
class Render(unittest.TestCase):
def test_states_the_earliest_releases_first_item_its_levels_and_detail_and_each_item_that_may_join_its_chunk(self):
said = rendered(item_facts())
self.assertIn("origin/main's todo.md: 0.2.0", said)
self.assertIn("item 3, L 4, E + I 5", said)
self.assertIn("> Change `src/app.py`'s `run` and the files under `src`, not `gone.py`.", said)
self.assertIn("item 7, L 1, E + I 2, S 1: **Do the thing after.**", said)
self.assertNotIn("item 8,", said)
def test_states_the_items_worktree_or_why_none_was_made(self):
self.assertIn("/c/proj-item-3", rendered(item_facts()))
self.assertIn("none made: path taken", rendered(item_facts(worktree=Failure("none made: path taken"))))
def test_states_that_no_other_item_may_join_the_chunk(self):
said = rendered(item_facts(TODO.replace("| 7 | 0.2.0 | 3 |", "| 7 | 0.2.0 | 5 |")))
self.assertIn("No other item", said)
self.assertNotIn("item 7,", said)
def test_states_an_unscored_level_as_unscored(self):
unscored = TODO.replace("| L | E | I | R | S |", "| R | S |").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|").replace("| 4 | 2 | 3 | 7 | 3 |", "| 7 | 3 |").replace("| 1 | 1 | 1 | 1 | 1 |", "| 1 | 1 |")
self.assertIn("item 3, L unscored, E + I unscored", rendered(item_facts(unscored)))
def test_states_the_unreleased_entries_and_else_the_commits_since_the_last_cut(self):
self.assertIn("v0.1.0. Unreleased: 2 entries", rendered(NoItem("x.")))
self.assertIn("1 entry", rendered(NoItem("x."), LastCut("v0.1.0", "## Unreleased\n\n- One.\n", 4, [])))
without = rendered(NoItem("x."), LastCut("v0.1.0", "# Changelog\n", 4, []))
self.assertIn("4 commits since v0.1.0", without)
self.assertIn("no ## Unreleased", without)
untagged = rendered(NoItem("x."), LastCut(None, "", 1, []))
self.assertIn("cut: none", untagged)
self.assertIn("1 commit on origin/main", untagged)
def test_states_why_the_changelog_and_the_commits_since_the_last_cut_cannot_be_read(self):
said = rendered(NoItem("x."), LastCut("v0.1.0", Failure("changelog unreadable"), Failure("count unreadable"), []))
self.assertIn("changelog unreadable", said)
self.assertIn("cannot be counted: count unreadable", said)
self.assertNotIn("no ## Unreleased", said)
def test_states_why_origin_reads_as_last_fetched_and_nothing_after_a_fetch(self):
self.assertIn("- reading origin as last fetched: fetch stalled", rendered(NoItem("x."), note="reading origin as last fetched: fetch stalled"))
fetched = rendered(NoItem("x."))
self.assertNotIn("last fetched", fetched)
self.assertNotIn("None", fetched)
def test_states_why_there_is_no_plan_item(self):
said = rendered(NoItem("every item waits."))
self.assertIn("every item waits.", said)
self.assertNotIn("Worktree", said)
def test_states_the_open_pull_requests_from_the_items_branch_or_why_none_are_listed(self):
cases = (
(("tea", Ran(0, "index\thead\turl\n12\titem-3\thttps://forge/pulls/12\n", "")), ("#12 https://forge/pulls/12",)),
(("gh", Ran(0, "12\thttps://github.com/o/r/pull/12\n14\thttps://github.com/o/r/pull/14\n", "")), ("#12 https://github.com/o/r/pull/12, #14 https://github.com/o/r/pull/14",)),
(("gh", Ran(0, "", "")), ("item-3: none.",)),
(None, ("item-3: none", "no origin remote")),
(("tea", Ran(1, "", "no login\n")), ("`tea pulls list`", "exited 1", "no login")),
(("gh", Ran(1, "", "not logged in\n")), ("`gh pr list`", "exited 1", "not logged in")),
(("gh", Failure("could not finish: timed out")), ("`gh pr list`", "could not finish: timed out")),
)
for pulls, facts in cases:
with self.subTest(pulls=pulls):
said = rendered(item_facts(pulls=pulls))
for fact in facts:
self.assertIn(fact, said)
def test_states_each_named_files_lines_and_each_named_folders_files(self):
said = rendered(item_facts(named=[NamedPath("src/app.py", 1, 3), NamedPath("src", 2, None), NamedPath("bad.py", 1, Failure("not UTF-8")), NamedPath("one.py", 1, 1), NamedPath("docs", 1, None)]))
self.assertIn("`src/app.py`: 3 lines", said)
self.assertIn("`src`: 2 files", said)
self.assertIn("`bad.py`: cannot be read: not UTF-8", said)
self.assertIn("`one.py`: 1 line\n", said)
self.assertIn("`docs`: 1 file\n", said)
def test_states_that_the_item_names_no_tracked_file_or_why_they_cannot_be_listed(self):
self.assertIn("no file", rendered(item_facts(named=[])))
self.assertIn("ls-files broke", rendered(item_facts(named=Failure("ls-files broke"))))
def test_states_what_each_tool_printed_and_its_exit_code(self):
said = rendered(item_facts(tools=[("rank_todo.py --check todo.md", Ran(0, "ranked\n", "")), ("reading-cost", Ran(1, "", "")), ("larv-review needs-scoring-run 3", Ran(1, "out\n", "err\n")), ("larv-review places", Failure("could not finish: timed out"))]))
self.assertIn("`rank_todo.py --check todo.md` exited 0", said)
self.assertIn("> ranked", said)
self.assertIn("`reading-cost` exited 1, printing nothing", said)
self.assertIn("> out\n> err", said)
self.assertIn("`larv-review places` could not finish: timed out", said)
class OpenPulls(unittest.TestCase):
def test_lists_gh_rows_as_they_come_and_only_teas_rows_from_the_branch(self):
self.assertEqual(open_pulls("12\thttps://github.com/o/r/pull/12\n14\thttps://github.com/o/r/pull/14\n", "gh", "item-3"), ["#12 https://github.com/o/r/pull/12", "#14 https://github.com/o/r/pull/14"])
self.assertEqual(open_pulls("index\thead\turl\n12\titem-3\thttps://forge/pulls/12\n13\tother\thttps://forge/pulls/13\n", "tea", "item-3"), ["#12 https://forge/pulls/12"])
class Plans(unittest.TestCase):
def test_picks_the_earliest_releases_first_item_that_does_not_wait_or_says_why_there_is_none(self):
self.assertEqual(planned(TODO, CUT, "origin/main").first.id, 3)
waits = planned(TODO.replace("| 3 | 0.2.0 | | |", "| 3 | 0.2.0 | | question |"), CUT, "origin/main")
self.assertIn("waits", waits.why)
self.assertIn("0.2.0", waits.why)
self.assertIn("Permission denied", planned(Failure("Permission denied"), CUT, "origin/main").why)
self.assertIn("L 'x'", planned(TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |"), CUT, "origin/main").why)
self.assertIn("details cannot be read", planned(TODO + "```\n", CUT, "origin/main").text)
def test_tells_a_plan_with_no_items_table_from_one_whose_table_holds_no_item(self):
without = planned("", CUT, "origin/main").why
self.assertIn("origin/main", without)
self.assertIn("no items table", without)
empty = planned(EMPTY, LastCut(None, "", 4, []), "origin/main").why
self.assertIn("holds no item", empty)
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):
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"),
)
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
self.assertIn(fact, why)
self.assertIn("v0.1.0", 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)
def test_takes_the_earliest_release_where_no_earlier_one_was_named_since_the_last_cut(self):
self.assertEqual(planned(LATER, LastCut("v0.1.0", "", 4, [LATER]), "origin/main").first.id, 9)
def test_says_the_plan_files_items_under_a_release_already_cut(self):
why = planned(TODO, LastCut("v0.2.0", "", 4, []), "origin/main").why
self.assertIn("release 0.2.0", why)
self.assertIn("v0.2.0", why)
self.assertIn("not after", why)
def test_takes_an_item_without_a_detail_as_its_tagline_alone(self):
self.assertEqual(planned(TODO[:TODO.index("## Details")], CUT, "origin/main").text, "**Do the next thing.**")
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)]),
("`src/`", ["src/app.py", "src/b.py"], [("src", 2)]),
("`src/app.py`, `gone.py` and `run`", ["src/app.py"], [("src/app.py", 1)]),
)
for text, tracked, named in cases:
with self.subTest(text=text):
self.assertEqual(named_paths(text, tracked), named)
def test_adds_the_worktree_on_the_local_branch_else_on_a_new_one_tracking_origins_else_on_a_new_one_off_the_default_branch(self):
path = pathlib.Path("/c/proj-item-3")
self.assertEqual(worktree_add("item-3", path, "origin/main", True, True)[0], ["worktree", "add", "--quiet", "/c/proj-item-3", "item-3"])
self.assertEqual(worktree_add("item-3", path, "origin/main", False, True)[0], ["worktree", "add", "--quiet", "--track", "-b", "item-3", "/c/proj-item-3", "origin/item-3"])
self.assertEqual(worktree_add("item-3", path, "origin/main", False, False)[0], ["worktree", "add", "--quiet", "--no-track", "-b", "item-3", "/c/proj-item-3", "origin/main"])
def test_lists_pull_requests_with_gh_on_a_github_origin_and_with_tea_elsewhere(self):
self.assertEqual(forge_of("git@github.com:o/r.git"), "gh")
self.assertEqual(forge_of("https://gitea.larvit.se/o/r.git"), "tea")
def test_reads_the_timeout_setting_as_seconds_above_0_and_else_takes_the_default(self):
self.assertEqual(seconds(None), TIMEOUT)
self.assertEqual(seconds("2.5"), 2.5)
for setting in ("soon", "0", "-1", "1e3", ""):
with self.subTest(setting=setting):
self.assertIn("CHUNK_PREFLIGHT_TIMEOUT", seconds(setting).reason)
class Running(unittest.TestCase):
def test_says_why_a_command_could_not_finish(self):
with tempfile.TemporaryDirectory() as cwd:
cases = (([str(pathlib.Path(cwd, "missing"))], 60, "missing"), ([sys.executable, "-c", "import time; time.sleep(5)"], 0.2, "0.2"))
for command, timeout, fact in cases:
with self.subTest(fact=fact):
done = ran(command, pathlib.Path(cwd), timeout)
self.assertIsInstance(done, Failure)
self.assertIn(fact, done.reason)
def test_counts_a_files_lines_says_why_they_cannot_be_read_and_counts_none_for_a_folder(self):
with tempfile.TemporaryDirectory() as temp:
folder = pathlib.Path(temp)
(folder / "two.txt").write_text("a\nb\n")
(folder / "latin.txt").write_bytes(b"caf\xe9\n")
(folder / "locked.txt").write_text("a\n")
(folder / "locked.txt").chmod(0)
self.assertEqual(line_count(folder / "two.txt"), 2)
self.assertIn("utf-8", line_count(folder / "latin.txt").reason)
self.assertIn("locked.txt", line_count(folder / "locked.txt").reason)
self.assertIsNone(line_count(folder))
if __name__ == "__main__":
unittest.main()
+82 -23
View File
@@ -1,15 +1,22 @@
"""Run git in the current directory, and read the checkout, its default branch and its files."""
"""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) -> str | Failure:
def git(*args: str, cwd: str | None = None, timeout: float | None = None) -> str | Failure:
"""What git printed, run in cwd, else in the current directory. A Failure where git cannot start, exits non-zero, prints text that is not UTF-8, or still runs after timeout seconds, which stops it."""
try:
ran = subprocess.run(["git", *args], capture_output=True, text=True)
ran = subprocess.run(["git", *args], capture_output=True, cwd=cwd, encoding="utf-8", timeout=timeout)
except UnicodeDecodeError as failure:
return Failure(f"git {' '.join(args)} printed text that is not UTF-8: {failure}")
except (OSError, ValueError) as failure:
return Failure(f"git could not start: {failure}")
except subprocess.TimeoutExpired:
return Failure(f"git {' '.join(args)}: stopped after {timeout} s")
return ran.stdout if ran.returncode == 0 else Failure(f"git {' '.join(args)}: {ran.stderr.strip()}")
@@ -18,28 +25,36 @@ def top() -> str | Failure:
return found if isinstance(found, Failure) else found.strip()
def default_branch(stale_ok: bool) -> tuple[str, str | None] | Failure:
"""The default branch's ref, `origin/<branch>` after a fetch with that remote, else the local main or master, and a note for stderr. With stale_ok, a failed fetch reads origin as last fetched, and the note says so."""
def default_branch(stale_ok: bool, timeout: float | None = None) -> tuple[str, str | None] | Failure:
"""The default branch's ref, as default_ref names it after a fetch where the checkout has an origin remote, and a note on why origin reads as last fetched. With stale_ok, a failed fetch reads origin as last fetched, and the note says so. A call to origin still running after timeout seconds fails."""
remotes = git("remote")
if isinstance(remotes, Failure):
return remotes
fetch = git("fetch", "--quiet", "origin", timeout=timeout) if "origin" in remotes.split() else ""
if isinstance(fetch, Failure) and not stale_ok:
return fetch
ref = default_ref(timeout=timeout)
note = f"reading origin as last fetched: {fetch.reason}" if isinstance(fetch, Failure) else None
return ref if isinstance(ref, Failure) else (ref, note)
def default_ref(cwd: str | None = None, timeout: float | None = None) -> str | Failure:
"""The default branch's ref as last fetched, read in cwd, else in the current directory: `origin/<branch>` with that remote, else the local main or master. Asking origin, where the checkout records no default branch for it, fails after timeout seconds."""
remotes = git("remote", cwd=cwd)
if isinstance(remotes, Failure):
return remotes
if "origin" in remotes.split():
fetch = git("fetch", "--quiet", "origin")
if isinstance(fetch, Failure) and not stale_ok:
return fetch
note = f"reading origin as last fetched: {fetch.reason}" if isinstance(fetch, Failure) else None
default = git("symbolic-ref", "--short", "refs/remotes/origin/HEAD")
named = default.strip() if not isinstance(default, Failure) else origin_head()
return named if isinstance(named, Failure) else (named, note)
recorded = git("symbolic-ref", "--short", "refs/remotes/origin/HEAD", cwd=cwd)
return recorded.strip() if not isinstance(recorded, Failure) else origin_head(cwd, timeout)
for branch in ("main", "master"):
if not isinstance(git("rev-parse", "--quiet", "--verify", f"refs/heads/{branch}"), Failure):
return branch, None
if not isinstance(git("rev-parse", "--quiet", "--verify", f"refs/heads/{branch}", cwd=cwd), Failure):
return branch
return Failure("no origin remote, and no main or master branch to take as the default branch")
def origin_head() -> str | Failure:
def origin_head(cwd: str | None, timeout: float | None) -> str | Failure:
"""The default branch origin names, for a clone made by `git init` and `git remote add`, which records none."""
listed = git("ls-remote", "--symref", "origin", "HEAD")
listed = git("ls-remote", "--symref", "origin", "HEAD", cwd=cwd, timeout=timeout)
if isinstance(listed, Failure):
return listed
if named := re.match(r"ref: refs/heads/(\S+)\tHEAD", listed):
@@ -47,18 +62,62 @@ def origin_head() -> str | Failure:
return Failure("origin names no default branch; set it with `git remote set-head origin --auto`")
def commit_exists(commit: str) -> bool:
return not isinstance(git("rev-parse", "--quiet", "--verify", f"{commit}^{{commit}}"), Failure)
@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 file_at(revision: str, path: str) -> str | Failure:
"""A file's text at a revision, 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):
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, 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", "--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.
tags = git("-c", "versionsort.suffix=-", "tag", "--list", "v*", "--merged", branch, "--sort=-v:refname", cwd=cwd)
return tags if isinstance(tags, Failure) else next(iter(tags.split()), None)
def commits_since(tag: str | None, branch: str, cwd: str | None = None) -> 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)
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 file_at(revision: str, path: str, cwd: str | None = None) -> 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):
return ""
listed = git("ls-tree", "--name-only", revision, "--", path)
listed = git("ls-tree", "--name-only", revision, "--", path, cwd=cwd)
if isinstance(listed, Failure):
return listed
return git("show", f"{revision}:{path}") if listed.strip() else ""
return git("show", f"{revision}:{path}", cwd=cwd) if listed.strip() else ""
def full_history() -> Failure | None:
+6 -8
View File
@@ -1,5 +1,5 @@
from git_repo import commits_since, file_at, full_history, git, newest_release_tag
from failure import Failure
from git_repo import file_at, full_history, git
from comprehension_history import HISTORY, HistoryChange
@@ -24,10 +24,8 @@ def history_changes(default: str) -> list[HistoryChange] | Failure:
def landed_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."""
# Sorts v1.0.0-rc.1 below v1.0.0.
tags = git("-c", "versionsort.suffix=-", "tag", "--list", "v*", "--merged", default, "--sort=-v:refname")
if isinstance(tags, Failure):
return tags
newest = tags.split()[:1]
count = git("rev-list", "--count", f"{newest[0]}..{default}" if newest else default)
return count if isinstance(count, Failure) else int(count) > 0
newest = newest_release_tag(default)
if isinstance(newest, Failure):
return newest
count = commits_since(newest, default)
return count if isinstance(count, Failure) else count > 0
+19 -3
View File
@@ -13,16 +13,32 @@ ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could
REVIEWS: tuple[tuple[str, ReviewKind], ...] = (("each reviewer", "reviewer"), ("each comprehension seat", "seat"), ("the security pass's subagent", "security"))
def fresh(task: str, premises: str, route: Route, anchor: Rung | None) -> str:
def fresh(task: str, premises: str, route: Route, anchor: Rung | None, facts: str) -> str:
"""A chunk's first prompt; facts is preflight_facts' or preflight_failed's text."""
escalated = f"{escalation(route, anchor)}{reruns(route, anchor)}".lstrip()
routed = f"{routed_by(route, anchor)}\n\n" if route.item else (f"{escalated}\n\n" if escalated else "")
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one.\n\n{routed}The chunk's todo.md items, or else the task above, set its scope. The goals below choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n{premises}"
routed = f"{routed_by(route, anchor)}{recount(route)}\n\n" if route.item else (f"{escalated}\n\n" if escalated else "")
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one.\n\n{routed}{facts}\n\nThe chunk's todo.md items, or else the task above, set its scope. The goals below choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n{premises}"
def routed_by(route: Route, anchor: Rung | None) -> str:
return f"loop-claude runs you on {route.rung}, routed by item {route.item}'s L of {route.likelihood}. Name each todo.md item this chunk takes, with its L and E + I, whether or not it is item {route.item}.{review_launches(route, anchor)}{escalation(route, anchor)}{reruns(route, anchor)}"
def recount(route: Route) -> str:
"""Has the worker count the routing item's size again once it knows the code, since the L that routed it was scored before anyone read that code."""
return f" After your first read of the code, count item {route.item}'s size again: the lines, files and components you will change. Where that count would change its L, have a subagent that scores todo.md items re-score it; a re-score whose L picks a rung above yours is escalation trigger 1."
def preflight_facts(printed: str) -> str:
"""What chunk-preflight printed, for the worker to take as found."""
return f"loop-claude ran `~/.claude/bin/chunk-preflight` at the checkout root just before this run. Take what it printed as found rather than finding it again:\n\n{printed}"
def preflight_failed(reason: str) -> str:
"""Has the worker find the facts chunk-preflight would have, its worktree among them."""
return f"loop-claude could not run `~/.claude/bin/chunk-preflight`, so find the chunk's facts yourself. Why it could not run: {reason}"
def review_launches(route: Route, anchor: Rung | None) -> str:
"""Which reviews to launch on a rung other than the worker's, and on which; below the project's rung, anchor, also where to launch a subagent that files or scores todo.md items; then taken_in_launches, the reviewers' rung each higher E + I picks. Empty off the ladder.
+3 -1
View File
@@ -25,6 +25,8 @@ from model_routing import worker_rungs
@dataclasses.dataclass(frozen=True)
class Cycle:
effects: Effects
# What chunk-preflight found, or why it could not run, for a fresh worker's prompt; empty when the session was open as the cycle began.
facts: str
judge_model: str
paths: Paths
premises: str
@@ -101,7 +103,7 @@ def worker_start(cycle: Cycle, answered: QuotedAnswer | None) -> list[str]:
return worker_args(cycle.session, cycle.route.rung, prompts.answered(answered.question, answered.answer), resume=True)
if session_open(cycle.session):
return worker_args(cycle.session, cycle.route.rung, prompts.resumed(cycle.unfinished_evidence, cycle.route, cycle.anchor), resume=True)
return worker_args(cycle.session, cycle.route.rung, prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.anchor), resume=False)
return worker_args(cycle.session, cycle.route.rung, prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.anchor, cycle.facts), resume=False)
def keep_answer(cycle: Cycle, answered: QuotedAnswer) -> Stop | None:
+17 -2
View File
@@ -5,6 +5,9 @@ import sys
import time
import typing
# Seconds before a Python script loop-claude runs is stopped, so a hung one, such as chunk-preflight, cannot hold the loop.
PYTHON_TIMEOUT = 600
class Streaming(typing.Protocol):
"""A started claude whose stream-json lines arrive as it works."""
@@ -24,7 +27,8 @@ class Effects:
local_time: typing.Callable[[float], str]
now: typing.Callable[[], float]
on_terminal: typing.Callable[[], bool]
python: typing.Callable[[list[str]], subprocess.CompletedProcess[str]]
# Runs a Python script in a directory, as run_python does.
python: typing.Callable[[list[str], str], subprocess.CompletedProcess[str]]
sleep: typing.Callable[[float], None]
stream_claude: typing.Callable[[list[str], str, dict[str, str]], Streaming]
@@ -51,7 +55,18 @@ def system_effects() -> Effects:
local_time=lambda seconds: time.strftime("%Y-%m-%d %H:%M %Z", time.localtime(seconds)),
now=time.time,
on_terminal=lambda: sys.stdin.isatty() and sys.stdout.isatty(),
python=lambda args: subprocess.run([sys.executable, *args], capture_output=True, text=True),
python=lambda args, cwd: run_python(args, cwd, PYTHON_TIMEOUT),
sleep=time.sleep,
stream_claude=StreamingClaude,
)
def run_python(args: list[str], cwd: str, timeout: float) -> subprocess.CompletedProcess[str]:
"""Runs a Python script in cwd. One that cannot start, or still runs after timeout seconds and is stopped, reads as exit 1, saying why on stderr."""
command = [sys.executable, *args]
try:
return subprocess.run(command, capture_output=True, cwd=cwd, encoding="utf-8", errors="replace", stdin=subprocess.DEVNULL, timeout=timeout)
except OSError as failure:
return subprocess.CompletedProcess(command, 1, "", f"could not start: {failure}")
except subprocess.TimeoutExpired:
return subprocess.CompletedProcess(command, 1, "", f"stopped after {timeout} s")
+55 -22
View File
@@ -5,8 +5,9 @@ usage: loop-claude <task>
Run it anywhere inside a project checkout whose README.md has ## Goals and ## Audience, the
premises; the task runs at the checkout root. Each cycle a worker runs the task. A chunk's first
worker prompt also quotes the premises, which choose between ways to deliver the chunk's todo.md
items, or else the task, and never widen them. A judge then reads the transcript's end, the premises, and the records: the project's AGENTS.md and docs/decisions.md,
and the human's ~/.claude/CLAUDE.md, ~/.claude/rules/*.md and
items, or else the task, and never widen them. A judge then reads the transcript's end, the
premises, and the records: the project's AGENTS.md and docs/decisions.md, and the human's
~/.claude/CLAUDE.md, ~/.claude/rules/*.md and
~/.claude/skills/larv-review/standards/*.md, where they exist. It rules whether the chunk, the work
of one PR, is finished. A chunk stays unfinished until each answer the human typed in it that a
later chunk could need is recorded: the premises or the records hold it, or the transcript shows the worker
@@ -22,6 +23,12 @@ its session next cycle, and the worker is shown the passage the judge quoted as
The next chunk starts a fresh session.
Cycles continue until an exit below or Ctrl-C. Words: ~/.claude/CLAUDE.md → "Vocabulary".
As a chunk starts, before it is routed, loop-claude runs bin/chunk-preflight (bin/chunk_preflight/),
which finds the chunk's facts and makes its worktree; chunk-preflight --help lists them, and
prompts.preflight_facts in bin/loop_claude/cycle/prompts.py quotes them in the first prompt. A
preflight that fails, or is still running after 600 s and is stopped, leaves the worker to find the
facts itself.
Each project has one session, named "A <key> loop-claude", where <key> is the checkout's path
relative to ~/code, or to / outside it. The session is deleted when its chunk finishes. At every
interrupt, and as every cycle ends, Ctrl-C and a failure included, the session's transcript is
@@ -44,17 +51,22 @@ run, is asked for one. LOOP_CLAUDE_JUDGE_MODEL overrides it for the judge, LOOP_
for the worker and the interrupt; with both set, nothing is asked.
Where that model is on the routing ladder (bin/model_routing/ladder.py), the worker and the
interrupt run on one of the ladder's rungs: a model at an effort. As a chunk starts, todo.md's top
item in the next release that does not wait routes it: an item waits while it is marked question,
or while an item that blocks it is still in the table. The item's L picks the worker's rung,
stepping from the model's cheapest rung by WORKER_STEPS in bin/model_routing/ladder.py, below it
for a low L; without such an item, or with its L, E or I unscored, the chunk runs on the model's
cheapest rung. The
interrupt 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,
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, or any earliest release where no tag names a version. Otherwise no
item routes the chunk. An item waits while it is marked
question, or while an item that blocks it is still in the table. The item's L
picks the worker's rung, stepping from the model's cheapest rung by WORKER_STEPS in
bin/model_routing/ladder.py, below it for a low L; without such an item, or with its L, E or I
unscored, the chunk runs on the model's cheapest rung. The
item's E + I picks the reviewers' rung, stepping up from the cheapest rung by REVIEW_STEPS there,
never below the worker's rung. The worker's first prompt names the rung and the item, and asks the
worker to name each item the chunk takes, with its L and E + I. The prompt names the rung of each
review that runs on a rung other than the worker's: the reviewers' rung for the reviewers, and the
cheapest rung for each comprehension seat and the security pass. It also names the reviewers' rung
worker to name each item the chunk takes, with its L and E + I, and to count the item's size again
once it has read the code (prompts.recount). The prompt names the rung of each review that runs on
a rung other than the worker's: the reviewers' rung for the reviewers, and the cheapest rung for
each comprehension seat and the security pass. It also names the reviewers' rung
each higher E + I picks, so the worker reviews an item it takes in on that rung in the same run.
When the worker runs below the cheapest rung, the prompt has it launch each subagent that files or
scores todo.md items on the rung subagent-rung --plan prints. The prompt after
@@ -147,6 +159,7 @@ 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 loop_claude.effects import Effects
from failure import Failure
from loop_claude.cycle.judge import Finished, Unfinished
@@ -158,12 +171,16 @@ from transcript_archive import outcomes
from loop_claude.paths import Paths
from project_key import project_key
from model_routing.ladder import project_rung, Rung
from loop_claude.cycle import prompts
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from model_routing.route import Route, route_from
from claude_code.session import Session, session_named, transcript_file
from claude_code.session import Session, session_named, session_open, transcript_file
from loop_claude.stop import Stop
# 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 main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, cwd: pathlib.Path, effects: Effects) -> int:
try:
@@ -197,12 +214,14 @@ 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)
anchor = project_rung(models.worker)
root = loop_run.root
loop_run = routed(loop_run, anchor, lambda: archived_route(archive_folder, session), lambda: plan_item(root))
loop_run = routed(loop_run, anchor, lambda: archived_route(archive_folder, session), lambda: plan_item(fetched_plan(root)))
route = loop_run.route or Route(Rung(models.worker))
print(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", flush=True)
verdict = run_cycle(Cycle(anchor=anchor, effects=effects, 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))
verdict = 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))
if isinstance(verdict, Stop):
return verdict
before, loop_run = loop_run.route, after_verdict(loop_run, anchor, verdict)
@@ -247,14 +266,28 @@ def archived_route(archive_folder: pathlib.Path, session: Session) -> Route | No
return route_from(worker) if worker else None
def plan_item(root: str) -> Item | None:
"""The item that routes a chunk; None without one, so the chunk runs on the project's rung."""
try:
item = routed_item(pathlib.Path(root, "todo.md").read_text(encoding="utf-8"))
except FileNotFoundError:
return None
except (OSError, ValueError) as failure:
item = Failure(f"could not read todo.md: {failure}")
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)
if done.returncode:
return prompts.preflight_failed(done.stderr.strip() or f"it exited {done.returncode}")
return prompts.preflight_facts(done.stdout.strip())
def fetched_plan(root: str) -> DefaultPlan | Failure:
"""What the default branch, as chunk-preflight's fetch left it, 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."""
if isinstance(plan, Failure):
item: Item | Failure | None = plan
elif isinstance(plan.todo, Failure):
item = plan.todo
else:
item = routed_item(plan.todo, plan.cut)
if isinstance(item, Failure):
print(f"routing on the project's rung: {item.reason}", file=sys.stderr)
return None
+4 -4
View File
@@ -80,11 +80,11 @@ def fingerprint(launcher: pathlib.Path) -> str:
def exec_if_edited(launcher: pathlib.Path, baseline: str, loop_run: LoopRun, effects: Effects) -> Stop | None:
if fingerprint(launcher) == baseline:
return None
trial = effects.python([str(launcher), "--help"], loop_run.root)
if trial.returncode != 0:
print(f"keeping the running script: {trial.stderr.strip() or f'exit {trial.returncode}'}", file=sys.stderr)
return None
try:
trial = effects.python([str(launcher), "--help"])
if trial.returncode != 0:
print(f"keeping the running script: {trial.stderr.strip() or f'exit {trial.returncode}'}", file=sys.stderr)
return None
effects.execv(sys.executable, [sys.executable, str(launcher), RELOAD_FLAG, json.dumps(dataclasses.asdict(loop_run))])
except OSError as failure:
return Stop(1, f"could not reload loop-claude: {failure.strerror}; rerun loop-claude <task>")
+6 -8
View File
@@ -1,9 +1,9 @@
"""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 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, waiting
from model_routing.route import Route
UNFINISHED_PER_STEP = 2
@@ -13,14 +13,12 @@ ESCALATION_CAP = 2
JUDGE_REPLAYED = ("claude-opus-5-5",)
def routed_item(todo: str) -> Item | Failure | None:
"""The next release's first row that does not wait, as todo_table.waiting says, in the table's order; None when there is none, or it lacks L, E or I."""
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."""
found = items(todo)
if isinstance(found, Failure) or not found:
return found if isinstance(found, Failure) else None
next_release = min(item.release for item in found)
waits = waiting(found)
takes = next((item for item in found if item.release == next_release and item.id not in waits), None)
if isinstance(found, Failure):
return found
_, takes = chunk_item(found or [], cut)
return takes if takes and takes.likelihood and takes.escape_and_impact else None
+46 -6
View File
@@ -190,6 +190,12 @@ class Checkout:
def git(self, *args):
subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@example.com", *args], capture_output=True, check=True, cwd=self.root, env=self.env)
def commit_plan(self, todo):
"""Commits todo as todo.md on the checkout's branch, the default branch routing reads it from."""
(self.root / "todo.md").write_text(todo)
self.git("add", "todo.md")
self.git("commit", "--quiet", "-m", "plan")
def run(self, steps, argv=(TASK,), cwd=None, terminal_input=None, stdout_on_terminal=True, before_typing=None):
for name in ("FAKE_CLAUDE_LOG", "LOOP_TEST_LOG"):
pathlib.Path(self.env[name]).unlink(missing_ok=True)
@@ -318,6 +324,14 @@ class Premises(unittest.TestCase):
self.assertEqual((run.code, run.calls), (1, []))
self.assertEqual(run.stderr.strip(), "could not start git: No such file or directory")
def test_makes_no_worktree_for_a_readme_without_premises(self):
checkout = Checkout(self)
checkout.commit_plan(TODO)
(checkout.root / "README.md").write_text("# Project\n")
run = checkout.run([worker()])
self.assertEqual((run.code, run.calls), (1, []))
self.assertFalse((checkout.home / "code" / "proj-item-4").exists())
def test_names_the_session_by_the_checkout_relative_to_code_or_else_to_the_root(self):
checkout = Checkout(self)
for root in (checkout.temp / "elsewhere", checkout.home / "code"):
@@ -353,6 +367,7 @@ class Cycles(unittest.TestCase):
self.assertEqual(argument(workers[2], "--session-id"), session)
self.assertTrue(argument(workers[0], "-p").startswith(f"{TASK}\n\nContinue any open draft PR"))
self.assertTrue(argument(workers[0], "-p").endswith("The chunk's todo.md items, or else the task above, set its scope. The goals below choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n## Goals\n1. Work.\n\n## Audience\nMe."))
self.assertIn("main or master", argument(workers[0], "-p"))
self.assertNotIn(TASK, argument(workers[1], "-p"))
self.assertIn("Even then, it is finished only once every answer the human typed in it", argument(workers[1], "-p"))
self.assertIn("as the work remaining:\n\n> started\n\n", argument(workers[1], "-p"))
@@ -374,7 +389,7 @@ class Cycles(unittest.TestCase):
def test_routes_the_worker_by_its_items_l_and_steps_it_up_within_the_chunk(self):
checkout = Checkout(self)
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = "claude-opus-5-5"
(checkout.root / "todo.md").write_text(CHEAP)
checkout.commit_plan(CHEAP)
run = checkout.run([
worker(say="one"), judge(evidence="one"),
worker(say="two"), judge(evidence="two"),
@@ -397,10 +412,34 @@ class Cycles(unittest.TestCase):
self.assertIn("<UTC> Verdict: unfinished\n\nEvidence:\n> three\n\nJudge: judge-model\nWorker: claude-opus-5-5 at medium effort, routed by item 4's L of 2 and E + I of 3\n\n<UTC> Stepped up\n\nWorker: claude-opus-5-5 at high effort, routed by item 4's L of 2 and E + I of 3\n", outcomes)
self.assertIn("<UTC> Verdict: finished\n\nEvidence:\n> four\n\nJudge: judge-model\nWorker: claude-opus-5-5 at high effort, routed by item 4's L of 2 and E + I of 3\n", outcomes)
def test_routes_on_and_states_the_same_item_from_the_fetched_default_branch_whatever_the_checkout_holds(self):
checkout = Checkout(self)
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = "claude-opus-5-5"
origin = checkout.temp / "origin.git"
checkout.git("init", "--quiet", "--bare", "--initial-branch=main", str(origin))
checkout.git("symbolic-ref", "HEAD", "refs/heads/main")
checkout.commit_plan(TODO)
checkout.git("remote", "add", "origin", str(origin))
checkout.git("push", "--quiet", "--set-upstream", "origin", "main")
# Item 4 ships elsewhere, and item 6 is next; the checkout is behind origin, and holds a change of its own.
elsewhere = checkout.temp / "elsewhere"
checkout.git("clone", "--quiet", str(origin), str(elsewhere))
(elsewhere / "todo.md").write_text(TODO.replace("| 4 | 0.1.0 |", "| 6 | 0.1.0 |"))
checkout.git("-C", str(elsewhere), "commit", "--quiet", "--all", "-m", "item 4 shipped, plan item 6")
checkout.git("-C", str(elsewhere), "push", "--quiet", "origin", "main")
(checkout.root / "todo.md").write_text(TODO + "\nA change of the checkout's own.\n")
(checkout.root / "sub").mkdir()
run = checkout.run([worker()], cwd=checkout.root / "sub")
self.assertEqual(run.code, 130)
prompt = argument(run.calls[0], "-p")
self.assertIn("routed by item 6's L of 4", prompt)
self.assertIn("item 6, L 4, E + I 5", prompt)
self.assertTrue((checkout.home / "code" / "proj-item-6").is_dir())
def test_steps_the_worker_up_a_rung_when_the_judge_finds_in_the_transcript_the_escalation_trigger_it_cites(self):
checkout = Checkout(self)
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = "claude-opus-5-5"
(checkout.root / "todo.md").write_text(TODO)
checkout.commit_plan(TODO)
run = checkout.run([
worker(say="Stability round 2: a 🔴. Trigger 3 fired; I ask for a higher rung."), judge(evidence="I ask for a higher rung.", escalation="Stability round 2: a 🔴."),
worker(say="Trigger 2 fired; I ask for a higher rung."), judge(evidence="I ask for a higher rung.", escalation="Trigger 2 fired; … a higher rung."),
@@ -422,7 +461,7 @@ class Cycles(unittest.TestCase):
def test_runs_a_cheap_items_worker_below_the_projects_rung_with_its_reviewers_and_judge_on_it(self):
checkout = Checkout(self)
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = checkout.env["LOOP_CLAUDE_JUDGE_MODEL"] = "claude-opus-5-5"
(checkout.root / "todo.md").write_text(CHEAP)
checkout.commit_plan(CHEAP)
run = checkout.run([worker(say="one"), judge(finished=True, evidence="one"), worker(say="next chunk")])
self.assertEqual(run.code, 130)
first = next(call for call in run.calls if call["role"] == "worker")
@@ -435,7 +474,7 @@ class Cycles(unittest.TestCase):
def test_routes_the_judge_and_the_reviewers_on_the_highest_e_plus_i_the_worker_takes_in(self):
checkout = Checkout(self)
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = checkout.env["LOOP_CLAUDE_JUDGE_MODEL"] = "claude-opus-5-5"
(checkout.root / "todo.md").write_text(CHEAP)
checkout.commit_plan(CHEAP)
run = checkout.run([
worker(say="one"), judge(evidence="one", bundled_escape_and_impact=6),
worker(say="two"), judge(finished=True, evidence="two"),
@@ -453,11 +492,12 @@ class Cycles(unittest.TestCase):
def test_a_rerun_resumes_an_open_chunk_on_the_rung_it_last_ran(self):
checkout = Checkout(self)
checkout.env["LOOP_CLAUDE_WORKER_MODEL"] = "claude-opus-5-5"
(checkout.root / "todo.md").write_text(TODO)
checkout.commit_plan(TODO)
run = checkout.run([worker(), judge(), worker(), judge()])
self.assertEqual(run.code, 130)
self.assertEqual(argument(run.calls[-1], "--effort"), "xhigh")
(checkout.root / "todo.md").unlink()
checkout.git("rm", "--quiet", "todo.md")
checkout.git("commit", "--quiet", "-m", "drop the plan")
run = checkout.run([worker()])
self.assertIsNotNone(argument(run.calls[0], "--resume"))
self.assertEqual((argument(run.calls[0], "--model"), argument(run.calls[0], "--effort")), ("claude-opus-5-5", "xhigh"))
+125 -45
View File
@@ -18,12 +18,14 @@ 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 loop_claude.effects import Effects
from git_repo import DefaultPlan
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
@@ -65,7 +67,7 @@ class FakeEffects:
local_time=lambda seconds: f"<{seconds}>",
now=lambda: NOW,
on_terminal=lambda: self.terminal,
python=lambda args: self.answer("python", args),
python=lambda args, cwd: self.answer("python", (args, cwd)),
sleep=lambda seconds: self.calls.append(("sleep", seconds)),
stream_claude=self.stream,
)
@@ -184,8 +186,8 @@ class Cycles(unittest.TestCase):
self.session = session.session_named("A proj loop-claude", self.paths.claude_code_transcripts)
self.archive = project_archive(str(self.home / "code" / "proj"), self.home, {})
def cycle(self, fake, records="", unfinished_evidence=""):
return run.Cycle(anchor=None, effects=fake.effects(), judge_model="judge-model", paths=self.paths, premises="## Goals", project_archive=self.archive, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, task="Do it.", unfinished_evidence=unfinished_evidence)
def cycle(self, fake, records="", unfinished_evidence="", facts="- A preflight fact."):
return run.Cycle(anchor=None, effects=fake.effects(), facts=facts, judge_model="judge-model", paths=self.paths, premises="## Goals", project_archive=self.archive, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, task="Do it.", unfinished_evidence=unfinished_evidence)
def archived_outcomes(self):
return sorted(path.read_text() for path in self.archive.glob("*/*.outcomes.md"))
@@ -196,6 +198,15 @@ class Cycles(unittest.TestCase):
self.assertEqual(self.archived_outcomes(), ["Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: finished\n\nEvidence:\n> working\n\nJudge: judge-model\nWorker: worker-model\n"])
self.assertIsNone(session.transcript_file(self.session))
def test_a_fresh_worker_reads_the_preflights_facts_and_a_resumed_one_does_not(self):
worker = Worker(self.paths.claude_code_transcripts.parent)
fake = FakeEffects(streams=[worker, worker], claude=[judged("unfinished"), judged("finished")])
self.assertEqual(run.run_cycle(self.cycle(fake)), Unfinished("working"))
self.assertEqual(run.run_cycle(self.cycle(fake, unfinished_evidence="working")), Finished("working"))
fresh, resumed = (args[args.index("-p") + 1] for args in fake.made("stream_claude"))
self.assertIn("- A preflight fact.", fresh)
self.assertNotIn("- A preflight fact.", resumed)
def test_a_worker_is_handed_the_projects_rung_its_own_and_its_reviewers_in_its_environment(self):
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished")])
cycle = dataclasses.replace(self.cycle(fake), anchor=Rung("claude-opus-5-5", "medium"), route=Route(Rung("claude-haiku-5-5", "max"), 163, 1, 5))
@@ -558,6 +569,8 @@ class ModelPrompt(unittest.TestCase):
self.assertEqual(model_choice.ask_for_model("proj", pathlib.Path("/m.json"), pathlib.Path(empty), fake.effects()), Stop(2, "the human is needed to pick proj's model, but the input ended"))
# A plan read with no release cut yet.
NO_CUT = LastCut(None, "", 0, [])
TODO = """# todo
## Items
@@ -578,24 +591,32 @@ class Routing(unittest.TestCase):
SONNET = Rung("claude-sonnet-5-5", "high")
def test_routes_on_the_next_releases_top_item_that_waits_on_no_question(self):
self.assertEqual(routing.routed_item(TODO).id, 3)
self.assertIsNone(routing.routed_item(TODO.replace("| | **Do", "| question | **Do")))
self.assertIsNone(routing.routed_item("# todo\n"))
self.assertIsNone(routing.routed_item(TODO[:TODO.index("| 7 |")]))
self.assertEqual(routing.routed_item(TODO, NO_CUT).id, 3)
self.assertIsNone(routing.routed_item(TODO.replace("| | **Do", "| question | **Do"), NO_CUT))
self.assertIsNone(routing.routed_item("# todo\n", NO_CUT))
self.assertIsNone(routing.routed_item(TODO[:TODO.index("| 7 |")], NO_CUT))
old_shape = "## Items\n\n| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|\n| 3 | 0.2.0 | | **Do the next thing.** | 5 | 3 | 6 | 8 | 9 | 1 | 25 |\n"
self.assertIsNone(routing.routed_item(old_shape))
self.assertEqual(routing.routed_item(TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |")), Failure("item 3's L 'x' is not a whole number from 1 to 4"))
self.assertIsNone(routing.routed_item(old_shape, NO_CUT))
self.assertEqual(routing.routed_item(TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |"), NO_CUT), Failure("item 3's L 'x' is not a whole number from 1 to 4"))
def test_routes_on_no_item_where_the_release_after_the_last_cut_has_none(self):
self.assertEqual(routing.routed_item(TODO, LastCut("v0.1.0", "", 3, [TODO])).id, 3)
self.assertIsNone(routing.routed_item(TODO, LastCut("v0.2.0", "", 3, [TODO])))
later_only = TODO[:TODO.index("| 7 |")] + TODO[TODO.index("| 1 | 0.3.0 |"):]
self.assertIsNone(routing.routed_item(later_only, LastCut("v0.1.0", "", 3, [TODO])))
self.assertIsNone(routing.routed_item(later_only, LastCut("v0.1.0", "", 0, [TODO])))
self.assertEqual(routing.routed_item(later_only, LastCut("v0.2.0", "", 3, [later_only])).id, 1)
def test_routes_past_an_item_a_waiting_item_blocks(self):
todo = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n| 7 | 0.2.0 | | question | **Ask first.** | 4 | 3 | 5 | 10 | 1 | 1 by 9 | 30 |\n| 8 | 0.2.0 | 7 | | **Use the answer.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 30 |\n| 9 | 0.2.0 | 8 | | **Build on it.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 30 |\n| 3 | 0.2.0 | | | **Do the next thing.** | 4 | 2 | 3 | 7 | 3 | 1 by 9 | 25 |\n"
self.assertEqual(routing.routed_item(todo).id, 3)
self.assertEqual(routing.routed_item(todo.replace("| question |", "| |")).id, 7)
self.assertEqual(routing.routed_item(todo, NO_CUT).id, 3)
self.assertEqual(routing.routed_item(todo.replace("| question |", "| |"), NO_CUT).id, 7)
first = "| 7 | 0.2.0 | | question | **Ask first.** | 4 | 3 | 5 | 10 | 1 | 1 by 9 | 30 |\n"
self.assertEqual(routing.routed_item(todo.replace(first, "") + first).id, 3)
self.assertEqual(routing.routed_item(todo.replace(first, "") + first, NO_CUT).id, 3)
def test_starts_a_chunk_on_the_rung_its_items_l_picks_below_the_projects_too(self):
self.assertEqual(routing.first_route(self.OPUS, routing.routed_item(TODO)), Route(self.HIGH, 3, 4, 5))
cheap = routing.routed_item(TODO.replace("| 4 | 2 | 3 |", "| 1 | 2 | 3 |"))
self.assertEqual(routing.first_route(self.OPUS, routing.routed_item(TODO, NO_CUT)), Route(self.HIGH, 3, 4, 5))
cheap = routing.routed_item(TODO.replace("| 4 | 2 | 3 |", "| 1 | 2 | 3 |"), NO_CUT)
self.assertEqual(routing.first_route(self.OPUS, cheap), Route(Rung("claude-haiku-5-5", "max"), 3, 1, 5))
self.assertEqual(routing.first_route(self.OPUS, None), Route(self.OPUS))
@@ -670,7 +691,7 @@ class Routing(unittest.TestCase):
def test_routes_nothing_on_an_item_without_e_or_i(self):
without_i = TODO.replace("| E | I | R |", "| E | R |").replace("|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|").replace("| 4 | 3 | 5 | 10 |", "| 4 | 3 | 10 |").replace("| 4 | 2 | 3 | 7 |", "| 4 | 2 | 7 |").replace("| 1 | 1 | 1 | 1 |", "| 1 | 1 | 1 |")
self.assertIsNone(routing.routed_item(without_i))
self.assertIsNone(routing.routed_item(without_i, NO_CUT))
def test_archives_the_route_in_a_line_it_reads_back(self):
route = Route(self.HIGH, 3, 4, 5)
@@ -696,7 +717,7 @@ class Routing(unittest.TestCase):
def test_keeps_a_chunks_route_or_its_archived_one_at_or_above_the_rung_its_item_picks_and_else_routes_afresh(self):
def run_with(route=None):
return main.LoopRun(cycle_number=1, root="/r", task="do it", unfinished_evidence="", route=route)
item = routing.routed_item(TODO)
item = routing.routed_item(TODO, NO_CUT)
archived = Route(self.XHIGH, 3, 4, 5)
def never():
raise AssertionError("not asked")
@@ -712,17 +733,15 @@ class Routing(unittest.TestCase):
class RouteSources(unittest.TestCase):
def test_routes_on_the_plan_item_and_says_why_it_routes_on_the_projects_rung(self):
with tempfile.TemporaryDirectory() as root:
self.assertIsNone(main.plan_item(root))
todo = pathlib.Path(root, "todo.md")
todo.write_text(TODO)
self.assertEqual(main.plan_item(root).id, 3)
for text, said in ((TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |"), "routing on the project's rung: item 3's L 'x' is not a whole number from 1 to 4\n"), (b"\xff", "routing on the project's rung: could not read todo.md: ")):
with self.subTest(said=said):
todo.write_bytes(text if isinstance(text, bytes) else text.encode())
with contextlib.redirect_stderr(io.StringIO()) as stderr:
self.assertIsNone(main.plan_item(root))
self.assertTrue(stderr.getvalue().startswith(said), stderr.getvalue())
self.assertIsNone(main.plan_item(DefaultPlan("", NO_CUT)))
self.assertEqual(main.plan_item(DefaultPlan(TODO, LastCut("v0.1.0", "", 3, [TODO]))).id, 3)
self.assertIsNone(main.plan_item(DefaultPlan(TODO, LastCut("v0.2.0", "", 3, [TODO]))))
unreadable = Failure("git show origin/main:todo.md printed text that is not UTF-8")
for plan, said in ((DefaultPlan(TODO.replace("| 4 | 2 | 3 |", "| x | 2 | 3 |"), NO_CUT), "routing on the project's rung: item 3's L 'x' is not a whole number from 1 to 4\n"), (DefaultPlan(unreadable, NO_CUT), f"routing on the project's rung: {unreadable.reason}\n"), (Failure("no origin remote"), "routing on the project's rung: no origin remote\n")):
with self.subTest(said=said):
with contextlib.redirect_stderr(io.StringIO()) as stderr:
self.assertIsNone(main.plan_item(plan))
self.assertTrue(stderr.getvalue().startswith(said), stderr.getvalue())
def test_resumes_on_the_archived_route_and_says_why_it_routes_afresh(self):
with tempfile.TemporaryDirectory() as home:
@@ -793,35 +812,95 @@ class Steps(unittest.TestCase):
self.assertEqual(main.archived_route(archive, opened), Route(self.OPUS, 3, 3, 4, escape_and_impact_taken_in=6))
class ChunkFacts(unittest.TestCase):
PREFLIGHT = pathlib.Path("/b/chunk-preflight")
def test_runs_the_preflight_at_the_checkout_root_and_quotes_what_it_printed(self):
fake = FakeEffects(python=[ran("- A fact.\n")])
said = main.chunk_facts(self.PREFLIGHT, "/r", fake.effects())
self.assertEqual(fake.made("python"), [(["/b/chunk-preflight"], "/r")])
self.assertIn("\n\n- A fact.", said)
self.assertNotIn("yourself", said)
def test_has_the_worker_find_the_facts_itself_where_the_preflight_failed(self):
for failed, why in ((ran(code=1, stderr="git could not start\n"), "git could not start"), (ran(code=1), "exited 1")):
with self.subTest(why=why):
said = main.chunk_facts(self.PREFLIGHT, "/r", FakeEffects(python=[failed]).effects())
self.assertIn("yourself", said)
self.assertIn(why, said)
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 WorkerArgs(unittest.TestCase):
SCAN = " Run a full scan only from such a subagent, since the scan's agents run on the model that starts them."
SEATS = " Launch each comprehension seat and the security pass's subagent with the Agent tool set to model opus, effort medium, the project's rung."
# What the preflight found, as the fresh prompt quotes it.
FACTS = "- A preflight fact."
def test_names_the_route_in_a_fresh_prompt_only_where_an_item_routed_it(self):
routed = prompts.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None)
self.assertIn("Continue any open draft PR or worktree for the chunk before creating a new one.\n\nloop-claude runs you on m at high effort, routed by item 3's L of 4. Name each todo.md item this chunk takes, with its L and E + I, whether or not it is item 3.\n\nThe chunk's", routed)
unrouted = prompts.fresh("Do it.", "## Goals", Route(Rung("m")), None)
self.assertIn("before creating a new one.\n\nThe chunk's", unrouted)
routed = prompts.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, self.FACTS)
self.assertIn("Continue any open draft PR or worktree for the chunk before creating a new one.\n\nloop-claude runs you on m at high effort, routed by item 3's L of 4. Name each todo.md item this chunk takes, with its L and E + I, whether or not it is item 3.", routed)
unrouted = prompts.fresh("Do it.", "## Goals", Route(Rung("m")), None, self.FACTS)
self.assertIn(f"before creating a new one.\n\n{self.FACTS}\n\nThe chunk's", unrouted)
self.assertNotIn("loop-claude runs you on", unrouted)
def test_has_the_routed_worker_count_its_items_size_again_and_puts_the_facts_before_the_scope(self):
routed = prompts.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, self.FACTS)
self.assertIn("item 3's size again", routed)
self.assertIn("escalation trigger 1", routed)
self.assertIn(f"\n\n{self.FACTS}\n\nThe chunk's", routed)
self.assertNotIn("size again", prompts.fresh("Do it.", "## Goals", Route(Rung("m")), None, self.FACTS))
def test_quotes_what_the_preflight_printed_or_has_the_worker_find_the_facts_itself(self):
self.assertIn("\n\n- A fact.", prompts.preflight_facts("- A fact."))
failed = prompts.preflight_failed("git could not start")
self.assertIn("yourself", failed)
self.assertIn("git could not start", failed)
def test_has_each_fresh_worker_continue_an_open_draft_pr_or_worktree_once_whatever_the_preflight_found(self):
for facts in (prompts.preflight_facts("- A fact."), prompts.preflight_failed("git could not start")):
with self.subTest(facts=facts):
self.assertEqual(prompts.fresh("Do it.", "## Goals", Route(Rung("m")), None, facts).count("Continue any open draft PR or worktree"), 1)
def test_keeps_every_review_on_the_projects_rung_while_the_worker_runs_below_it(self):
opus = Rung("claude-opus-5-5", "medium")
below = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 4), opus)
below = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 4), opus, self.FACTS)
self.assertIn(f"whether or not it is item 3. Launch each reviewer, each comprehension seat and the security pass's subagent with the Agent tool set to model opus, effort medium, the project's rung.{self.SCAN} 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 claude-opus-5-5 <L>` prints. Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model opus, effort high` from 5, `model opus, effort xhigh` from 6, `model opus, effort max` from 7 and `model fable, effort max` from 8. When an escalation trigger", below)
self.assertNotIn("Launch each", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus))
self.assertNotIn("Launch each", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus, self.FACTS))
def test_launches_reviewers_on_the_rung_the_items_e_plus_i_picks_above_the_workers(self):
opus = Rung("claude-opus-5-5", "medium")
level = prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 6), opus)
level = prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 6), opus, self.FACTS)
self.assertIn("whether or not it is item 3. Launch each reviewer with the Agent tool set to model opus, effort xhigh, the rung item 3's E + I of 6 picks. Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort max` from 7 and `model fable, effort max` from 8. When an escalation trigger", level)
below = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 5), opus)
below = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 5), opus, self.FACTS)
self.assertIn(f"whether or not it is item 3. Launch each reviewer with the Agent tool set to model opus, effort high, the rung item 3's E + I of 5 picks.{self.SEATS}{self.SCAN} Your rung is below the project's:", below)
self.assertNotIn("Launch each reviewer", prompts.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 4, 6), opus))
def test_names_the_reviewers_rung_each_higher_e_plus_i_an_item_taken_in_picks(self):
opus = Rung("claude-opus-5-5", "medium")
taking_in = " Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model opus, effort high` from 5, `model opus, effort xhigh` from 6, `model opus, effort max` from 7 and `model fable, effort max` from 8."
self.assertIn(f"whether or not it is item 3.{taking_in} When an escalation trigger", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus))
self.assertIn(f"whether or not it is item 3.{taking_in} When an escalation trigger", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus, self.FACTS))
self.assertIn(" Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort max` from 7 and `model fable, effort max` from 8.", prompts.resumed("", Route(opus, 3, 3, 6), opus))
self.assertIn(" Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort max` from 7 and `model fable, effort max` from 8.", prompts.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 4, 4), opus))
self.assertNotIn("Where an item you take into", prompts.resumed("", Route(opus, 3, 3, 8), opus))
@@ -834,7 +913,7 @@ class WorkerArgs(unittest.TestCase):
def test_keeps_seats_and_the_security_pass_on_the_projects_rung_while_the_worker_runs_above_it(self):
opus = Rung("claude-opus-5-5", "medium")
above = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-opus-5-5", "high"), 3, 4, 4), opus)
above = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-opus-5-5", "high"), 3, 4, 4), opus, self.FACTS)
stepped_up = prompts.resumed("", Route(Rung("claude-opus-5-5", "high"), 3, 3, 4), opus)
self.assertIn(f"{prompts.ANSWERS_RECORDED}. loop-claude runs you on claude-opus-5-5 at high effort.{self.SEATS}{self.SCAN} Where an item you take into the chunk has an E + I of 6 or more, launch each reviewer with the Agent tool set to `model opus, effort xhigh` from 6, `model opus, effort max` from 7 and `model fable, effort max` from 8. When an escalation trigger", stepped_up)
self.assertNotIn("the project's", prompts.resumed("", Route(opus, 3, 3, 4), opus))
@@ -843,7 +922,7 @@ class WorkerArgs(unittest.TestCase):
def test_names_the_rungs_an_escalation_trigger_lets_the_worker_hand_a_task_to_at_most_two_above_its_items(self):
opus = Rung("claude-opus-5-5", "medium")
fresh = prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus)
fresh = prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus, self.FACTS)
self.assertIn("whether or not it is item 3. Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model opus, effort high` from 5, `model opus, effort xhigh` from 6, `model opus, effort max` from 7 and `model fable, effort max` from 8. When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort high`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort xhigh`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", fresh)
self.assertIn(" When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort xhigh`, one rung above yours; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", prompts.resumed("", Route(Rung("claude-opus-5-5", "high"), 3, 3, 4), opus))
self.assertIn(" An escalation trigger in `~/.claude/CLAUDE.md` lets you hand the hard part of a task to a subagent with the Agent tool set to `model opus, effort max`, one rung above yours, only once the human agrees; loop-claude will not resume you higher for a trigger either, so ask the human for that yes. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", prompts.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 3, 4), opus))
@@ -851,12 +930,12 @@ class WorkerArgs(unittest.TestCase):
self.assertIn("hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort max`, one rung above yours;", prompts.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 4, 5), opus))
self.assertNotIn("escalation", prompts.resumed("", Route(Rung("m")), None))
self.assertNotIn("escalation", prompts.resumed("", Route(Rung("claude-opus-5-5", "low"), 3, 3, 4), opus))
self.assertIn("before creating a new one.\n\nWhen an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort high`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort xhigh`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number. Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last such request: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model opus, effort xhigh`. A reviewer", prompts.fresh("Do it.", "## Goals", Route(opus), opus))
self.assertIn("before creating a new one.\n\nWhen an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort high`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort xhigh`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number. Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last such request: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model opus, effort xhigh`. A reviewer", prompts.fresh("Do it.", "## Goals", Route(opus), opus, self.FACTS))
def test_offers_the_worker_a_higher_rung_for_the_rest_of_the_chunk_up_to_the_escalation_cap(self):
opus = Rung("claude-opus-5-5", "medium")
offer = " Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last such request: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model opus, effort xhigh`."
self.assertIn(f"`Escalation trigger <n>:`, n the trigger's number.{offer}", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus))
self.assertIn(f"`Escalation trigger <n>:`, n the trigger's number.{offer}", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus, self.FACTS))
self.assertIn(f"`Escalation trigger <n>:`, n the trigger's number.{offer}", prompts.resumed("", Route(Rung("claude-opus-5-5", "high"), 3, 3, 4), opus))
self.assertNotIn("Where the hard part", prompts.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 3, 4), opus))
@@ -865,19 +944,19 @@ class WorkerArgs(unittest.TestCase):
both = " A reviewer or comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `model opus, effort high`."
self.assertTrue(prompts.resumed("", Route(opus, 3, 3, 4), opus).endswith(both))
self.assertTrue(prompts.resumed("", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 4), opus).endswith(both))
self.assertTrue(prompts.fresh("Do it.", "## Goals", Route(opus), opus).split("\n\nThe chunk's")[0].endswith(both))
self.assertTrue(prompts.fresh("Do it.", "## Goals", Route(opus), opus, self.FACTS).split(f"\n\n{self.FACTS}")[0].endswith(both))
self.assertTrue(prompts.resumed("", Route(Rung("claude-opus-5-5", "high"), 3, 4, 4), opus).endswith(" A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `model opus, effort xhigh`, and a comprehension seat with `model opus, effort high`."))
self.assertTrue(prompts.resumed("", Route(opus, 3, 3, 7), opus).endswith(" A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort max`, and a comprehension seat with `model opus, effort high`."))
self.assertTrue(prompts.resumed("", Route(Rung("claude-fable-5-1", "max"), 3, 4, 8), opus).endswith(" A comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `model opus, effort high`."))
self.assertNotIn("rerun", prompts.resumed("", Route(Rung("m")), None))
self.assertNotIn("rerun", prompts.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None))
self.assertIn(f"{both}\n\nThe chunk's", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus))
self.assertNotIn("rerun", prompts.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, self.FACTS))
self.assertIn(f"{both} After your first read", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus, self.FACTS))
fable = Rung("claude-fable-5-1", "max")
self.assertNotIn("rerun", prompts.resumed("", Route(fable), fable))
def test_opens_a_fresh_session_by_name_and_resumes_an_open_one(self):
opened = session.session_named("A proj loop-claude", pathlib.Path("/h/.claude/projects"))
fresh = worker.worker_args(opened, Rung("m"), prompts.fresh("Do it.", "## Goals\n1. g\n\n## Audience\nme", Route(Rung("m")), None), resume=False)
fresh = worker.worker_args(opened, Rung("m"), prompts.fresh("Do it.", "## Goals\n1. g\n\n## Audience\nme", Route(Rung("m")), None, self.FACTS), resume=False)
self.assertEqual(fresh[fresh.index("--session-id") + 1], str(opened.id))
self.assertEqual(fresh[fresh.index("--name") + 1], "A proj loop-claude")
resumed = worker.worker_args(opened, Rung("m"), prompts.resumed("", Route(Rung("m")), None), resume=True)
@@ -1057,6 +1136,7 @@ class HelpLimits(unittest.TestCase):
self.assertEqual((retry.FAILURES_RUNNING, retry.RETRY_DELAY), (3, 60))
self.assertIn("fails three times running, retried a minute apart", said)
self.assertIn(f"retried {retry.PAST_RESET // 60} minutes after the limit resets, or every {retry.UNKNOWN_RESET_POLL // 60} minutes", said)
self.assertIn(f"still running after {PYTHON_TIMEOUT} s", said)
class ExitContract(unittest.TestCase):
+6 -17
View File
@@ -77,9 +77,9 @@ import re
import sys
import typing
from todo_table import BLOCKED_BY, cells, HEADER_START, Item, items_table, MOVES, OLD_SHAPE, parse_row, 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, risk, Shape, SHAPE, shape_of, Table, table_rows
from failure import Failure
from markdown_text import FENCE, listed, sections
from markdown_text import listed, sections
from file_writes import replace_file
LARGEST_FORMULA = 200
@@ -578,21 +578,10 @@ def render_item(item: Item, value: float, shape: Shape, columns: tuple[str, ...]
def rank_details(text: str, items: list[Item]) -> str | Failure:
section = re.search(r"^## Details\n(.*?)(?=^## |\Z)", text, re.M | re.S)
if section is None:
return text
body = section.group(1)
# A fenced line such as "## Goals" or "### 2. x" would read as a heading and split a detail.
if FENCE.search(body):
return Failure("## Details holds a fenced code block; indent quoted markdown by four spaces instead")
parts = re.split(r"^### (\d+)\. [^\n]*\n", body, flags=re.M)
if parts[0].strip():
return Failure("## Details holds text before its first ### <ID>. heading")
details: dict[int, str] = {}
for id_, detail in zip(parts[1::2], parts[2::2]):
if int(id_) in details:
return Failure(f"## Details holds item {id_} twice")
details[int(id_)] = detail.strip("\n")
section = DETAILS.search(text)
details = item_details(text)
if section is None or isinstance(details, Failure):
return details if isinstance(details, Failure) else text
if unknown := sorted(set(details) - {item.id for item in items}):
return Failure(f"## Details holds item {', '.join(map(str, unknown))}, which the items table does not")
headed = [f"### {item.id}. {item.tagline.strip('*').replace(chr(92) + '|', '|')}\n\n{details[item.id]}\n" for item in items if item.id in details]
+1 -1
View File
@@ -15,5 +15,5 @@ class Types(unittest.TestCase):
self.assertIsNotNone(floor, "README.md's Install names `Python 3.N or newer`")
if shutil.which("uv") is None:
self.fail("uv on PATH fetches mypy; see README.md's Test line")
ran = subprocess.run(["uv", "tool", "run", "--python", "%d.%d" % floor, "mypy==2.3.1", "--cache-dir=/dev/null", "--check-untyped-defs", "--disallow-untyped-defs", "--exclude", "/test_", "-p", "claude_code", "-m", "comprehension_history", "-m", "git_repo", "-p", "judge_replay", "-p", "larv_review", "-p", "loop_claude", "-m", "markdown_text", "-p", "metric_bench", "-m", "project_key", "-m", "rank_todo", "-m", "round_titles", "-p", "reading_cost", "-p", "rule_hook", "-p", "rung_replay", "-p", "score_outcomes", "-p", "stability_replay", "-p", "subagent_rung", "-m", "shell_command", "-m", "statusline", "-m", "todo_table", "-p", "transcript_archive", "-m", "utc_stamp"], capture_output=True, cwd=ROOT / "bin", text=True)
ran = subprocess.run(["uv", "tool", "run", "--python", "%d.%d" % floor, "mypy==2.3.1", "--cache-dir=/dev/null", "--check-untyped-defs", "--disallow-untyped-defs", "--exclude", "/test_", "-p", "chunk_preflight", "-p", "claude_code", "-m", "comprehension_history", "-m", "git_repo", "-p", "judge_replay", "-p", "larv_review", "-p", "loop_claude", "-m", "markdown_text", "-p", "metric_bench", "-m", "project_key", "-m", "rank_todo", "-m", "round_titles", "-p", "reading_cost", "-p", "rule_hook", "-p", "rung_replay", "-p", "score_outcomes", "-p", "stability_replay", "-p", "subagent_rung", "-m", "shell_command", "-m", "statusline", "-m", "todo_table", "-p", "transcript_archive", "-m", "utc_stamp"], capture_output=True, cwd=ROOT / "bin", text=True)
self.assertEqual(ran.returncode, 0, ran.stdout + ran.stderr)
+53
View File
@@ -0,0 +1,53 @@
import contextlib
import pathlib
import subprocess
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from failure import Failure
import git_repo
class Git(unittest.TestCase):
# Each command is a shell alias, so it touches no repository, whatever GIT_DIR the test runs under.
def test_stops_git_still_running_after_the_timeout_and_says_so(self):
done = git_repo.git("-c", "alias.hang=!sleep 5", "hang", timeout=0.2)
self.assertIsInstance(done, Failure)
self.assertIn("hang", done.reason)
self.assertIn("0.2 s", done.reason)
def test_says_git_printed_text_that_is_not_utf_8(self):
done = git_repo.git("-c", "alias.latin=!printf 'caf\\351'", "latin")
self.assertIsInstance(done, Failure)
self.assertIn("latin", done.reason)
self.assertIn("UTF-8", done.reason)
class StalledOrigin(unittest.TestCase):
"""A checkout whose origin, run through git's ext transport, answers nothing for 10 s, and which records no default branch for it."""
def setUp(self):
temp = tempfile.TemporaryDirectory()
self.addCleanup(temp.cleanup)
self.root = temp.name
for args in (("init", "--quiet"), ("config", "protocol.ext.allow", "always"), ("remote", "add", "origin", "ext::sleep 10")):
subprocess.run(["git", *args], capture_output=True, check=True, cwd=self.root)
def test_reading_the_default_branch_fails_after_the_timeout(self):
ref = git_repo.default_ref(self.root, 0.5)
self.assertIsInstance(ref, Failure)
self.assertIn("stopped after 0.5 s", ref.reason)
def test_fetching_the_default_branch_fails_after_the_timeout(self):
with contextlib.chdir(self.root):
found = git_repo.default_branch(stale_ok=True, timeout=0.5)
self.assertIsInstance(found, Failure)
self.assertIn("stopped after 0.5 s", found.reason)
if __name__ == "__main__":
unittest.main()
+54
View File
@@ -111,6 +111,10 @@ class Rank(unittest.TestCase):
self.assertEqual(ranked.notes, [])
self.assertEqual(self.ranked(ranked.text), ranked)
def test_keeps_a_detail_that_opens_with_markdown_quoted_by_four_spaces(self):
quoting = TODO.replace("Fast detail.", " ## Goals\n\nFast detail.")
self.assertIn("### 3. Make it fast, `a | b`.\n\n ## Goals\n\nFast detail.\n", self.ranked(quoting).text)
def test_weighs_each_achieve_goal_by_its_sum_reciprocal_rank(self):
readme = "## Goals\n\n1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
self.assertEqual({goal: round(weight, 4) for goal, weight in rank_todo.goal_weights(rank_todo.readme_goals(readme)).items()}, {"1": 0.5455, "1.1": 0.5455, "1.2": 0.2727, "2": 0.1818})
@@ -342,6 +346,13 @@ class Blockers(unittest.TestCase):
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, 4, 5])
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)
@@ -404,6 +415,49 @@ 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"))
class Main(unittest.TestCase):
def run_main(self, *argv):
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()) as said:
+102 -3
View File
@@ -3,6 +3,7 @@ import re
import typing
from failure import Failure
from markdown_text import FENCE, sections
# Each score a Shape names, and each goal's move, runs from 1 to TOP_SCORE, but for the levels L, E and I, which run from 1 to their LEVELS: ~/.claude/rules/todo-items.md defines each level.
TOP_SCORE = 10
@@ -16,6 +17,12 @@ 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, even once its items moved to a later release, as larv_review/plan.py's emptied counts such a release emptied too.
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)
# Each goal an item names, in its order, with how far the item moves it; None in OLD_SHAPE, whose Goals cell names no move.
Moves = tuple[tuple[str, int | None], ...]
@@ -155,12 +162,104 @@ def items_table(lines: list[str]) -> Table | None | Failure:
return table
def waiting(found: list[Item]) -> set[int]:
"""The IDs of the items that wait: each marked question, or blocked by an item the table still holds. Row order does not change the result."""
held = {item.id for item in found}
def waiting(found: list[Item], done: set[int]) -> set[int]:
"""The IDs of the items that wait: each marked question, or blocked by an item the table still holds and done does not name. Row order does not change the result."""
held = {item.id for item in found} - done
return {item.id for item in found if item.exempt == "question" or held.intersection(item.blocked_by)}
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."""
if not found:
return None
release = min(item.release for item in found)
waits = waiting(found, set())
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; 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 file items under; a text that does not parse names none."""
if isinstance(todos, Failure):
return todos
return {item.release for parsed in map(items, todos) if isinstance(parsed, list) for item in parsed}
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}
# Dropping an item that waits may make another wait on it, so drop until none waits.
while waits := waiting(found, chunk) & chunk:
chunk -= waits
return [item for item in found if item.id in chunk and item.id != first.id]
def item_details(todo: str) -> dict[int, str] | Failure:
"""Each item's detail under ## Details, by ID; empty where todo.md has no such section."""
section = DETAILS.search(todo)
if section is None:
return {}
# A fenced line such as "## Goals" or "### 2. x" would read as a heading and split a detail.
if FENCE.search(section.group(1)):
return Failure("## Details holds a fenced code block; indent quoted markdown by four spaces instead")
parts = re.split(r"^### (\d+)\. [^\n]*\n", section.group(1), flags=re.M)
if parts[0].strip():
return Failure("## Details holds text before its first ### <ID>. heading")
details: dict[int, str] = {}
for id_, detail in zip(parts[1::2], parts[2::2]):
if int(id_) in details:
return Failure(f"## Details holds item {id_} twice")
details[int(id_)] = detail.strip("\n")
return details
def table_rows(lines: list[str], header: str) -> Table | Failure:
if lines.count(header) != 1:
return Failure(f"todo.md needs the table header {header} once")
+43
View File
@@ -2060,3 +2060,46 @@ Inherited architect, decided by:
- Navigation, Self-sufficiency: `bin/loop_claude/cycle/run.py:122` `keep_rejection`: a loop that exits 1 after a rejected judge reply now leads to the archived reply, named like `keep_answer`
- Self-sufficiency, Navigation: `workflow-bench/review_git.py:1` module docstring: explains the rule syntax and what the wrapper checks inline
- Self-sufficiency: `bin/loop_claude/routing.py:84` `judge_rung`: points to `reviewed_on` in place of a plan item
## 2026-10-17T01:10:16Z, PR #302 at f566d1c, against 46b79e7
Ruling: same
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Mid A | better | same | worse | same | same |
| Inherited architect | same | worse | worse | same | worse |
| Maintainability senior | better | same | same | same | same |
| Junior A | same | worse | worse | same | worse |
Mid A, decided by:
- Navigation: `bin/loop_claude/loop/main.py:26` `__doc__`: loop-claude's help names `bin/chunk-preflight`, says it runs before routing and points to `prompts.preflight_facts`, so the worker's starting facts lead straight to the file and function
- Navigation: `bin/todo_table.py:229` `chunk_item`: the next chunk's item is picked in one named function both routing and chunk-preflight use, where 46b79e7 wrote it out inside `routed_item`
- Navigation: `bin/chunk_preflight/main.py:94` `preflight`: the tool splits into main (effects), gathered (data and pure choices) and facts (wording), so a wrong printed line leads to `facts.py` and a wrong worktree choice to `gathered.worktree_add`
- Shape: `bin/todo_table.py:212` `standing`: the items-table parser now also holds release policy (`LastCut`, CHANGELOG counting, a five-state standing, bundling), so its name no longer tells the truth, and the `min(... named | {earliest} ...)` test is the densest reading in the change
- Shape: `bin/git_repo.py:74` `default_plan`: the git wrapper imports the plan model and builds a `LastCut`, so a low-level module depends on a higher-level one
Inherited architect, decided by:
- Locality: `bin/loop_claude/loop/main.py:217` `run_loop`: routing must run after the chunk-preflight subprocess, reading the plan as its fetch left it; only a comment guards that order, and a resumed session skips the preflight, where 46b79e7 read the working tree's todo.md in place
- Locality: `bin/chunk_preflight/main.py:94` `preflight`: some git calls take the checkout explicitly and others rely on the process's working directory, so seeing that they hit one repo needs how loop-claude launches the tool
- Locality, Shape: `bin/git_repo.py:65` `DefaultPlan`: the git plumbing module now knows todo.md and CHANGELOG.md and imports the plan model, so its name no longer says what it holds
- Shape, Locality: `bin/todo_table.py:212` `standing`: the table parser has taken on release policy that depends on todo.md texts back to the last tag; picking the routed item now runs through four modules, and the key test only makes sense beside the three-line `Standing` comment
- Locality: `bin/loop_claude/cycle/run.py:28` `Cycle.facts`: the first prompt names the chunk's item twice, from routing and from the preflight's facts, which agree only because both call `chunk_item` and nothing lands on origin between the two reads
- Shape: `bin/chunk_preflight/gathered.py:1` `gathered`: it mixes dataclasses with plan, worktree, forge and path decisions, and `facts.py` is the renderer, so two names say less than they hold
Maintainability senior, decided by:
- Navigation: `bin/loop_claude/loop/main.py:26` `__doc__`: the new paragraph says the preflight runs before routing and names `bin/chunk_preflight/` and `prompts.preflight_facts`, and the routing paragraph names `todo_table.chunk_item`, so why the worker was told X or routed to item N lands on the right file from --help
- Navigation: `README.md:85` "Tools": the new tool gets one line pointing to its --help, and the import paragraph says loop_claude runs it as a separate process
- Navigation: `bin/todo_table.py:229` `chunk_item`: one function picks for routing and the preflight, where 46b79e7's `routed_item` held its own copy, so a wrong-item symptom leads to one unit
Junior A, decided by:
- Locality: `bin/loop_claude/loop/main.py:217` `run_loop`: routing works only after the preflight, since `fetched_plan` never fetches and counts on the preflight's fetch, which only a comment says; at 46b79e7 `plan_item` read the working tree's todo.md wherever it ran
- Locality, Shape: `bin/git_repo.py:65` `DefaultPlan`: the git module imports `LastCut` from `todo_table` and builds the plan pick's inputs, so its name and docstring no longer cover what it holds
- Shape, Locality: `bin/todo_table.py:199` `landed`: it counts ## Unreleased entries first while `larv_review/git.py`'s `landed_since_release` counts commits only, two meanings of "work has landed"
- Shape, Locality: `bin/todo_table.py:212` `standing`: the table parser grew from 247 to 346 lines and now decides how a release stands through a five-valued literal whose three-line comment must be decoded first, where 46b79e7's `routed_item` stated the pick in six lines
- Locality: `bin/chunk_preflight/main.py:30` `__doc__`: the preflight runs reading-cost in the new worktree, and larv-review's step now depends on whether the prompt shows that, so one action is split across a tool, a prompt and a skill
- Shape: `bin/chunk_preflight/gathered.py:1` `gathered`: the name covers the data but not the pure choices it also holds, and `main.py` imports 12 names from it on one line
+17
View File
@@ -586,3 +586,20 @@ Read most (opens and searches):
- `docs/decisions.md` 2
- `AGENTS.md` 1
- `CHANGELOG.md` 1
## Reading cost, chunk 94d844dc700e, finished 2026-10-16T22:15:37Z
117108 new input tokens before the first commit.
Read most (opens and searches):
- `todo.md` 6
- `bin/loop_claude/test_black_box.py` 5
- `bin/loop_claude/test_loop_claude.py` 5
- `docs/decisions.md` 4
- `CHANGELOG.md` 3
- `bin/routing_figures/measure.py` 2
- `bin/transcript_archive/outcomes.py` 2
- `AGENTS.md` 1
- `README.md` 1
- `bin/loop_claude/cycle/judge.py` 1
+1 -1
View File
@@ -24,7 +24,7 @@ The bar a chunk is reviewed to: ~/.claude/skills/larv-review/standards/quality.m
Follow `~/.claude/CLAUDE.md` → "Git, commits, and PRs". Never commit to the default branch. Commit, push with upstream set, and open a **draft** PR so CI cycles while the review runs. No remote → review locally and say so in the summary.
**Reading cost.** Run `~/.claude/bin/reading-cost` in the chunk's worktree and commit what it appends to `docs/reading-cost.md`; the commit re-enters no pass. Resolve a merge conflict in that file by putting the default branch's figures first and dropping a figure for a chunk the default branch already holds. On `Rising:`, file a plan item titled `**Lower the reading cost of the files a chunk reads most before its first commit.**`, scored per `~/.claude/rules/todo-items.md` with the tool's medians and files as its detail; where the plan already holds it, refresh its detail instead. The item names the next release, or the one after when this chunk ships the next release's last item. On exit 1, repair what its message names and run it again; when the message names no repair, file it as a `question` item, or refresh the question item an earlier run filed, and go on. Leave the plan as it is on any other output. The chunk that ships that item runs the tool with `--reset` instead, so the next rise is measured on chunks that finished after it.
**Reading cost.** Run `~/.claude/bin/reading-cost` in the chunk's worktree, unless loop-claude's prompt shows that `chunk-preflight` already ran it there, and commit what it appends to `docs/reading-cost.md`; the commit re-enters no pass. Resolve a merge conflict in that file by putting the default branch's figures first and dropping a figure for a chunk the default branch already holds. On `Rising:`, file a plan item titled `**Lower the reading cost of the files a chunk reads most before its first commit.**`, scored per `~/.claude/rules/todo-items.md` with the tool's medians and files as its detail; where the plan already holds it, refresh its detail instead. The item names the next release, or the one after when this chunk ships the next release's last item. On exit 1, repair what its message names and run it again; when the message names no repair, file it as a `question` item, or refresh the question item an earlier run filed, and go on. Leave the plan as it is on any other output. The chunk that ships that item runs the tool with `--reset` instead, so the next rise is measured on chunks that finished after it.
## 3. Passes
+22 -16
View File
@@ -6,13 +6,12 @@
`Bar = 0.1`
`Next ID = 175`
`Next ID = 178`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 161 | 0.2.0 | | | **Have loop-claude run a preflight script before each fresh worker and put its findings in the worker's prompt, so the worker no longer spends tool calls finding the chunk's mechanical facts.** | 4 | 2 | 3 | 7 | 6 | 1.1 by 4, 1.4 by 6, 1.5 by 6 | 2.9 |
| 84 | 0.2.0 | | | **Check, at each release's scoring run, that seats in a paired ruling agree more often than two scoring runs on near-identical code do, as the paired-ruling decision assumes.** | 2 | 2 | 2 | 4 | 4 | 1.4 by 5 | 2.3 |
| 168 | 0.2.0 | | | **Have the human answer an interrupt on loop-claude's terminal and resume the worker headless with the answer, opening the interactive session only when they ask for it.** | 4 | 2 | 3 | 7 | 5 | 1.5 by 8 | 1.8 |
| 73 | 0.2.0 | | | **Have each reviewer write its full report to a file and return the worker only its findings' one-line summaries.** | 3 | 2 | 3 | 6 | 5 | 1.4 by 4 | 1.1 |
@@ -35,10 +34,13 @@
| 157 | 0.3.0 | | | **Split `docs/decisions.md` → `todo.md: one table of items …`'s 2026-10-02 paragraph into one paragraph per choice.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 4, 1.4 by 4 | 10.9 |
| 106 | 0.3.0 | | | **Make larv-review's "Do not over-read a clean result" cite a rule that says Renovate or Dependabot owns dependency CVEs, or drop the citation.** | 1 | 2 | 1 | 2 | 1 | 1.1 by 5 | 10.9 |
| 167 | 0.3.0 | | | **Refuse a `/security-review` or `/claude-security` Skill call below the project's rung, as rule-hook refuses such an Agent call.** | 3 | 2 | 3 | 6 | 2 | 1.1 by 4 | 7.3 |
| 176 | 0.3.0 | | | **Give `loop-claude --help`'s routing paragraph sub-headings, such as Routing, Judge rung and Routing figures, so a reader finds a rule without reading 39 lines.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 3, 1.4 by 2 | 7.3 |
| 172 | 0.3.0 | | | **Name the project's rung `project` across `bin/loop_claude`, in place of `anchor`, as `bin/model_routing/ladder.py` names it.** | 2 | 1 | 3 | 4 | 3 | 1.1 by 3, 1.4 by 3 | 6.2 |
| 82 | 0.3.0 | | principle | **Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.** | 2 | 2 | 1 | 3 | 4 | 1.1 by 4, 1.4 by 4 | 5.5 |
| 173 | 0.3.0 | | | **Have rule-hook's `todo-rank-check` run a worktree's own `bin/rank_todo.py` when the worktree is of this repo, so a branch that changes `todo.md`'s shape commits without an override.** | 2 | 1 | 3 | 4 | 2 | 1.1 by 2, 1.4 by 2 | 5.5 |
| 162 | 0.3.0 | | owner | **Script each step that 0.2.0's chunks repeated by hand and a program can compute, filing one item per step, and file this audit again for the next release.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 4, 1.5 by 4 | 4.9 |
| 175 | 0.3.0 | | | **Compare the first five chunks loop-claude starts with `chunk-preflight` against the five before them, and file an item where the preflight did not pay off.** | 1 | 2 | 1 | 2 | 2 | 1.4 by 3, 1.5 by 3 | 4.9 |
| 177 | 0.3.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 |
| 171 | 0.3.0 | | decision | **Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.** | 3 | 2 | 2 | 5 | 4 | 1.2 by 3, 1.4 by 3 | 3.2 |
| 165 | 0.3.0 | | | **Make this repo's tests assert the facts a prompt or help text carries in place of its sentences, and drop the tests that scan source or assert a constant.** | 3 | 2 | 1 | 4 | 5 | 1.1 by 4, 1.4 by 3 | 3.0 |
| 169 | 0.3.0 | | | **Have rule-hook's `todo-rank-check` catch a `todo.md` that the same Bash call edits and then commits.** | 3 | 1 | 3 | 5 | 3 | 1.1 by 2 | 2.7 |
@@ -82,20 +84,6 @@
## Details
### 161. Have loop-claude run a preflight script before each fresh worker and put its findings in the worker's prompt, so the worker no longer spends tool calls finding the chunk's mechanical facts.
In item 140's chunk, the worker spent 5 min 46 s of 30 min, 16 of its 68 messages and 226k of its 491k fresh tokens before its first edit, through 12 Bash and 5 Read calls. About half of those found facts a program computes the same way in every chunk:
- the open PR and worktree for the chunk, the last tag and how many changes are unreleased;
- the next release, the first plan item that does not wait, its L, its E + I and its detail, after `rank_todo.py --check`;
- the items that may bundle with it under `CLAUDE.md` → "Working loop", "Work one chunk at a time, and make it as large as one purpose allows";
- what `larv-review needs-scoring-run`, `reading-cost` and `larv-review places` print;
- a worktree off a freshly fetched `origin/main`.
The preflight also lists the files and components the item's detail names, for the worker to judge the item's size from.
Compute these in one tool and give loop-claude's prompt its output as facts, so the worker reads them rather than finding them. The reading the chunk needs, such as the decision an item changes, stays the worker's. After its first read of the code, the worker counts the item's size again: the lines, files and components it will change. Where that count would change the item's L, a subagent on the project's rung re-scores the item. A re-score whose L picks a rung above the worker's is escalation trigger 1. Measure the next few chunks' time and fresh tokens before the first edit against item 140's figures. The comprehension seats found the prompt assembly in `bin/loop_claude/cycle/prompts.py` hard: put the preflight's facts in a function of their own there.
### 84. Check, at each release's scoring run, that seats in a paired ruling agree more often than two scoring runs on near-identical code do, as the paired-ruling decision assumes.
Raised by the principles audit of PR #228: the `review: the comprehension check records …` entry in `docs/decisions.md` is valid only while that holds, and `docs/comprehension-history.md` keeps every vote, yet nothing reads the agreement rate. Scoring runs on near-identical code are rare now, so compare with those already in the history, such as PR #224's and PR #225's, or make a second run for the check.
@@ -201,6 +189,10 @@ Found by the goals audit of PR #245. `skills/larv-review/SKILL.md` §3 → "Secu
rule-hook checks Agent calls (item 163) but no Skill calls. A worker that invokes `/security-review` in its own context, instead of in a subagent, runs the pass on its own rung, and nothing blocks it. Check Skill calls too: `breaches_of` in bin/rule_hook/main.py takes a Skill call whose skill is `security-review` or `claude-security` as a review launch, and settings.json's PreToolUse matcher gains Skill. Found by the systems-architect's review of PR #295.
### 176. Give `loop-claude --help`'s routing paragraph sub-headings, such as Routing, Judge rung and Routing figures, so a reader finds a rule without reading 39 lines.
Raised by the prose pass of PR #302: the help, the docstring of `bin/loop_claude/loop/main.py`, is 145 lines, and its routing paragraph one block of 39, from the ladder through the judge's rung to the routing figures. A reader looking for one rule, such as when the worker steps up, reads it all. The comprehension seats already found the help hard (`larv-review places`: "loop-claude --help": a 120-line contract with no pointers to the modules it maps onto).
### 172. Name the project's rung `project` across `bin/loop_claude`, in place of `anchor`, as `bin/model_routing/ladder.py` names it.
The architecture pass of PR #296 found one rung under two names: `bin/model_routing/ladder.py` calls it `project`, while `bin/loop_claude/routing.py`, `cycle/prompts.py`, `cycle/run.py`'s `Cycle.anchor` and `loop/main.py` call it `anchor`, and gloss it as "anchor, the project's rung" in docstring after docstring. A reader works out that the two are one rung each time. Make `bin/loop_claude/routing.py`'s `first_route` easier to read.
@@ -219,6 +211,20 @@ lilleman asked, on 2026-10-16, for a standing audit each release, so the loop ke
The chunk that ships this item files a copy of it in the release after the one it audits, rewording "0.2.0" to the release that copy audits, and marks the copy `owner`, so the audit recurs each release until lilleman drops it.
### 175. Compare the first five chunks loop-claude starts with `chunk-preflight` against the five before them, and file an item where the preflight did not pay off.
Item 161 put `chunk-preflight`'s facts into a fresh worker's prompt, so the worker no longer finds them itself. Before that, in item 140's chunk, the worker spent 5 min 46 s of 30 min, 16 of its 68 messages and 226k of its 491k fresh tokens before its first edit, through 12 Bash and 5 Read calls. Measure those figures from loop-claude's archive, as medians over the first five chunks that started with the preflight and the five before them: one chunk is too noisy a baseline, as `docs/decisions.md` → `reading cost: a rise is …` records. Measure the counter-signals beside them: goal 1.4's review rounds and unfinished verdicts, and goal 1.5's 🔴 findings, per chunk, since a worker that reads less may start sooner and need more rounds or let more defects through. Where time or tokens did not fall, or a counter-signal rose, file an item naming the facts the workers still found by hand, or what the preflight got wrong.
### 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.
- `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.
### 171. Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.
Raised by the goals audit of PR #296. `bin/routing_figures/measure.py` groups a chunk's review rounds by the rung its worker started on, and calls for a routing change when a lower rung took more of them. Since PR #296 the reviewers may run above the worker's rung, on the one their item's E + I picks, and no figure groups rounds by it, though the archived worker line names the E + I it follows from. A cheap worker on an item of high E + I gets stronger reviewers, who may raise more rounds, and a call could then blame the worker's rung for them: an interrupt of lilleman that settles nothing (goal 1.2).