Run a preflight before each fresh worker and put its facts in the worker's prompt

This commit is contained in:
2026-10-17 00:29:24 +02:00
parent 46b79e7803
commit f9615cb3b0
22 changed files with 532 additions and 76 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.
- The new `bin/chunk-preflight` finds a chunk's mechanical facts and makes its worktree, `<checkout>-item-<ID>` beside the checkout on the branch `item-<ID>`, or continues the one already there. Before each chunk's first worker, `loop-claude` runs it and quotes what it printed in the worker's prompt. It names the last release and the unreleased changes, the next item with its L, E + I and detail, the items that may join its chunk, the files the item names, the open pull requests, and what `rank_todo.py --check`, `larv-review needs-scoring-run`, `reading-cost` and `larv-review places` print. Expect the worker to start editing sooner, and `docs/reading-cost.md` to hold an uncommitted figure in the new worktree for the chunk to commit. 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.
## 0.1.0
+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 each chunk's first worker, 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
+9
View File
@@ -0,0 +1,9 @@
#!/usr/bin/env python3
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:]))
View File
+26
View File
@@ -0,0 +1,26 @@
import re
from markdown_text import sections
from todo_table import Item
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 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: no question, and none blocked by an item outside first and these."""
candidates = {item.id for item in found if item.release == first.release and item.id != first.id and item.exempt != "question"}
held = {item.id for item in found}
while blocked := {item.id for item in found if item.id in candidates and (held & set(item.blocked_by)) - candidates - {first.id}}:
candidates -= blocked
return [item for item in found if item.id in candidates]
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.rstrip("/") 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]
+179
View File
@@ -0,0 +1,179 @@
"""Find the mechanical facts a chunk starts from, and make its worktree, so its worker reads them rather than finding them.
usage: chunk-preflight
Run it inside a project checkout. loop-claude runs it at the checkout root before each fresh worker,
and quotes what it prints in the worker's prompt. It fetches origin, when the checkout has that
remote, and reads origin's default branch, or else the local main or master, as larv-review does.
It then 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 in the default branch's todo.md, and that release's first item that does not
wait, as loop-claude routes on, with its L and E + I;
- 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, as gh lists them on a github.com origin, and else as tea does;
- the items of that release that a chunk taking the item may take too: none is a question, and no
item outside them and the item blocks one;
- 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. With no item, it makes no worktree
and runs none of those four tools.
Exit 1, saying why, on any argument, or when git cannot start or finds no checkout.
"""
import pathlib
import subprocess
import sys
from chunk_preflight.facts import bundle_candidates, named_paths, unreleased_entries
from failure import Failure
from git_repo import commit_exists, default_branch, file_at, git, newest_release_tag, top
from markdown_text import quoted
from todo_table import Item, item_details, items, next_item
BIN = pathlib.Path(__file__).resolve().parents[1]
# A tool or forge CLI still running after this many seconds is stopped, so a hung one cannot hold the loop.
TIMEOUT = 300
def main(argv: list[str]) -> int:
if argv in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if argv:
print(f"unknown arguments {' '.join(argv)}; usage: chunk-preflight", file=sys.stderr)
return 1
root = top()
if isinstance(root, Failure):
print(root.reason, file=sys.stderr)
return 1
print("\n".join(preflight(pathlib.Path(root))))
return 0
def preflight(root: pathlib.Path) -> list[str]:
branch = default_branch(stale_ok=True)
if isinstance(branch, Failure):
return [f"- No default branch: {branch.reason}"]
default, note = branch
found = [f"- {note}"] if note else []
found.append(f"- {last_release(default)}")
todo = file_at(default, "todo.md")
planned = todo if isinstance(todo, Failure) else items(todo)
if isinstance(planned, Failure):
return [*found, f"- No plan item: {default}'s todo.md: {planned.reason}", *pull_requests(root)]
first = next_item(planned or [])
if first is None:
why = f"every item of {default}'s next release waits" if planned else f"{default} holds no todo.md items table"
return [*found, f"- No plan item: {why}, so no worktree was made.", *pull_requests(root)]
assert isinstance(todo, str) and planned
found.append(f"- Next release: {release_name(first)}. Its first item that does not wait: item {first.id}, L {first.likelihood or 'unscored'}, E + I {first.escape_and_impact or 'unscored'}.")
worktree = item_worktree(root, f"item-{first.id}", default)
found.append(f"- Worktree: {worktree.reason}" if isinstance(worktree, Failure) else f"- Worktree: {worktree[0]}, {worktree[1]}")
found += pull_requests(root)
found += bundled(planned, first)
details = item_details(todo)
detail = details.get(first.id, "") if isinstance(details, dict) else f"(todo.md's details cannot be read: {details.reason})"
text = f"{first.tagline}\n\n{detail}".strip()
found += named(text, worktree[0] if isinstance(worktree, tuple) else root)
found.append(f"\nItem {first.id}'s tagline and detail:\n\n{quoted(text)}")
if isinstance(worktree, tuple):
for args in (("rank_todo.py", "--check", "todo.md"), ("larv-review", "needs-scoring-run", str(first.id)), ("reading-cost",), ("larv-review", "places")):
found.append(f"\n{printed(args, [sys.executable, str(BIN / args[0]), *args[1:]], worktree[0])}")
return found
def last_release(default: str) -> str:
tag = newest_release_tag(default)
if isinstance(tag, Failure):
return f"Last version cut: cannot be read: {tag.reason}"
changelog = file_at(default, "CHANGELOG.md")
entries = unreleased_entries(changelog) if isinstance(changelog, str) else None
if entries is not None:
return f"Last version cut: {tag or 'none'}. Unreleased: {counted(entries, 'entry', 'entries')} under CHANGELOG.md → ## Unreleased."
commits = git("rev-list", "--count", f"{tag}..{default}" if tag else default)
since = f"since {tag}" if tag else f"on {default}"
return f"Last version cut: {tag or 'none'}. Unreleased: {commits.reason if isinstance(commits, Failure) else counted(int(commits), 'commit', 'commits')} {since}, and no ## Unreleased in CHANGELOG.md."
def item_worktree(root: pathlib.Path, branch: str, default: str) -> tuple[pathlib.Path, str] | Failure:
"""The worktree on branch, and how it came to be; a Failure where git cannot make it, or its path holds something else."""
held = git("worktree", "list", "--porcelain")
if isinstance(held, Failure):
return held
for block in held.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"]), f"on the branch {branch}, which it already held."
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}")
if commit_exists(f"refs/heads/{branch}"):
added, how = git("worktree", "add", "--quiet", str(path), branch), f"on the branch {branch}, which existed already."
elif commit_exists(f"refs/remotes/origin/{branch}"):
added, how = git("worktree", "add", "--quiet", "--track", "-b", branch, str(path), f"origin/{branch}"), f"on the new branch {branch}, made off origin/{branch}."
else:
# --no-track: tracking the default branch would point a bare `git push` at it.
added, how = git("worktree", "add", "--quiet", "--no-track", "-b", branch, str(path), default), f"on the new branch {branch}, made off {default}."
return Failure(f"none made: {added.reason}") if isinstance(added, Failure) else (path, how)
def pull_requests(root: pathlib.Path) -> list[str]:
url = git("remote", "get-url", "origin")
if isinstance(url, Failure):
return ["- Open pull requests: none, as the checkout has no origin remote."]
command = ["gh", "pr", "list"] if "github.com" in url else ["tea", "pulls", "list", "--fields", "index,title,head,state", "--output", "tsv"]
return [f"- Open pull requests: {printed(tuple(command), command, root)}"]
def bundled(planned: list[Item], first: Item) -> list[str]:
candidates = bundle_candidates(planned, first)
if not candidates:
return [f"- No other item of release {release_name(first)} may join item {first.id}'s chunk."]
listed = [f" - item {item.id}, L {item.likelihood or 'unscored'}, E + I {item.escape_and_impact or 'unscored'}, S {item.scores.get('S', 'unscored')}: {item.tagline}" for item in candidates]
return [f"- The items of release {release_name(first)} that item {first.id}'s chunk may take too, where `~/.claude/CLAUDE.md` → \"Working loop\" lets them share it:", *listed]
def named(text: str, base: pathlib.Path) -> list[str]:
tracked = git("-C", str(base), "ls-files")
if isinstance(tracked, Failure):
return [f"- The files the item names: cannot be listed: {tracked.reason}"]
paths = named_paths(text, tracked.splitlines())
if not paths:
return ["- The item names no file or folder git tracks."]
return ["- The files and folders the item names:", *(f" - `{span}`: {size(base / span, count)}" for span, count in paths)]
def size(path: pathlib.Path, files: int) -> str:
if not path.is_file():
return counted(files, "file", "files")
try:
return counted(len(path.read_text(encoding="utf-8").splitlines()), "line", "lines")
except (OSError, UnicodeDecodeError) as failure:
return f"cannot be read: {failure}"
def printed(shown: tuple[str, ...], command: list[str], cwd: pathlib.Path) -> str:
"""What command printed, run in cwd, and its exit code, under its name as shown."""
name = f"`{' '.join(shown)}`"
try:
done = subprocess.run(command, capture_output=True, cwd=cwd, stdin=subprocess.DEVNULL, text=True, timeout=TIMEOUT)
except (OSError, subprocess.TimeoutExpired) as failure:
return f"{name} could not finish: {failure}"
output = "\n".join(part.strip() for part in (done.stdout, done.stderr) if part.strip())
return f"{name} exited {done.returncode}, printing:\n\n{quoted(output)}" if output else f"{name} exited {done.returncode}, printing nothing."
def release_name(item: Item) -> str:
return ".".join(map(str, item.release))
def counted(count: int, one: str, many: str) -> str:
return f"{count} {one if count == 1 else many}"
+162
View File
@@ -0,0 +1,162 @@
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 chunk_preflight import facts
from test_env import isolated_env
from todo_table import items
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`.
"""
CHANGELOG = "# Changelog\n\n## Unreleased\n\n- One.\n - A nested line.\n- Two.\n\n## 0.1.0\n\n- Old.\n"
# Prints its arguments, then two open pull requests, as `tea pulls list --output tsv` does.
FAKE_TEA = "#!/bin/sh\necho \"tea $*\"\nprintf 'index\\ttitle\\thead\\tstate\\n12\\tWIP: the next thing\\titem-3\\topen\\n'\n"
class Repo:
"""An origin with a tagged release, a clone of it at <temp>/proj, and a fake tea on PATH."""
def __init__(self, test, todo=TODO):
temp = tempfile.TemporaryDirectory()
test.addCleanup(temp.cleanup)
self.temp = pathlib.Path(os.path.realpath(temp.name))
self.origin = self.temp / "origin.git"
self.root = self.temp / "proj"
fake = self.temp / "fake-bin"
fake.mkdir()
(fake / "tea").write_text(FAKE_TEA)
(fake / "tea").chmod(0o755)
(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(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("README.md", README)
self.write("src/app.py", "def run():\n\treturn 1\n\n")
self.commit("start")
self.git(self.root, "tag", "v0.1.0")
self.write("CHANGELOG.md", CHANGELOG)
if todo:
self.write("todo.md", todo)
self.commit("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, path, text):
(self.root / path).parent.mkdir(parents=True, exist_ok=True)
(self.root / path).write_text(text)
def commit(self, title):
self.git(self.root, "add", "-A")
self.git(self.root, "commit", "--quiet", "-m", title)
def preflight(self):
return subprocess.run([sys.executable, str(BIN / "chunk-preflight")], capture_output=True, cwd=self.root, env=self.env, text=True, timeout=120)
class ChunkPreflightTool(unittest.TestCase):
def test_makes_the_items_worktree_off_the_fetched_default_branch_and_states_the_chunks_facts(self):
repo = Repo(self)
done = repo.preflight()
self.assertEqual(done.returncode, 0, done.stderr)
worktree = repo.temp / "proj-item-3"
self.assertEqual(repo.git(worktree, "rev-parse", "--abbrev-ref", "HEAD").strip(), "item-3")
self.assertEqual(repo.git(worktree, "rev-parse", "HEAD"), repo.git(repo.root, "rev-parse", "origin/main"))
for fact in (
"Last version cut: v0.1.0. Unreleased: 2 entries under CHANGELOG.md → ## Unreleased.",
"Next release: 0.2.0. Its first item that does not wait: item 3, L 4, E + I 5.",
f"Worktree: {worktree}, on the new branch item-3, made off origin/main.",
"- item 7, L 1, E + I 2, S 1: **Do the thing after.**",
"- `src/app.py`: 3 lines",
"- `src`: 1 file",
"Change `src/app.py`'s `run` and the files under `src`, not `gone.py`.",
"tea pulls list --fields index,title,head,state --output tsv",
"12\tWIP: the next thing\titem-3\topen",
"`rank_todo.py --check todo.md` exited 0",
"`larv-review needs-scoring-run 3` exited 0",
"`reading-cost` exited 0",
"`larv-review places` exited 0",
):
self.assertIn(fact, done.stdout)
self.assertNotIn("item 5,", done.stdout)
self.assertNotIn("item 8,", done.stdout)
self.assertNotIn("item 9,", done.stdout)
self.assertNotIn("`gone.py`:", done.stdout)
self.assertIn(f"to {worktree}/docs/reading-cost.md", 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"
self.assertIn(f"Worktree: {worktree}, on the branch item-3, which it already held.", repo.preflight().stdout)
(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")
self.assertIn(f"Worktree: {worktree}, on the new branch item-3, made off origin/item-3.", repo.preflight().stdout)
self.assertTrue((worktree / "work.txt").exists())
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("Last version cut: v0.1.0.", done.stdout)
self.assertIn("No plan item: origin/main holds no todo.md items table, so no worktree was made.", done.stdout)
self.assertFalse((repo.temp / "proj-item-3").exists())
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)
class Facts(unittest.TestCase):
def test_counts_the_top_level_entries_under_unreleased(self):
self.assertEqual(facts.unreleased_entries(CHANGELOG), 2)
self.assertEqual(facts.unreleased_entries("# Changelog\n\n## Unreleased\n\n## 0.1.0\n\n- Old.\n"), 0)
self.assertIsNone(facts.unreleased_entries("# Changelog\n\n## 0.1.0\n\n- Old.\n"))
def test_bundles_an_item_blocked_only_by_items_the_chunk_may_take(self):
found = items(TODO.replace("| 9 | 0.3.0 | |", "| 9 | 0.2.0 | 7 |"))
self.assertEqual([item.id for item in facts.bundle_candidates(found, found[1])], [7, 9])
if __name__ == "__main__":
unittest.main()
+7
View File
@@ -47,6 +47,13 @@ def origin_head() -> str | Failure:
return Failure("origin names no default branch; set it with `git remote set-head origin --auto`")
def newest_release_tag(branch: str) -> str | None | Failure:
"""The newest `v*` tag merged into branch, 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")
return tags if isinstance(tags, Failure) else next(iter(tags.split()), None)
def commit_exists(commit: str) -> bool:
return not isinstance(git("rev-parse", "--quiet", "--verify", f"{commit}^{{commit}}"), Failure)
+1 -1
View File
@@ -114,7 +114,7 @@ class Main(unittest.TestCase):
result = reply(Rung(args[args.index("--model") + 1], args[args.index("--effort") + 1]), "said Verdict: interrupt" in prompt.rsplit("latest last:", 1)[-1])
return subprocess.CompletedProcess(args, 0, json.dumps(result), "")
effects = Effects(claude=claude, claude_on_terminal=unused, execv=unused, git=unused, input=unused, local_time=unused, now=unused, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, execv=unused, git=unused, input=unused, local_time=unused, now=unused, on_terminal=unused, preflight=unused, python=unused, sleep=unused, stream_claude=unused)
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, {}, self.home, effects)
+5 -7
View File
@@ -1,5 +1,5 @@
from failure import Failure
from git_repo import file_at, full_history, git
from git_repo import file_at, full_history, git, newest_release_tag
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)
newest = newest_release_tag(default)
if isinstance(newest, Failure):
return newest
count = git("rev-list", "--count", f"{newest}..{default}" if newest else default)
return count if isinstance(count, Failure) else int(count) > 0
+13 -3
View File
@@ -13,14 +13,24 @@ 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, or empty."""
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}"
found = f"{facts}\n\n" if facts else ""
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one.\n\n{routed}{found}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}"
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)}"
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)} 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:
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:
return f"loop-claude could not run `~/.claude/bin/chunk-preflight`, so find the chunk's facts yourself: {reason}"
def review_launches(route: Route, anchor: Rung | None) -> str:
+15 -3
View File
@@ -84,8 +84,9 @@ def work(cycle: Cycle, answered: QuotedAnswer | None) -> WorkerRan | Stop:
print(f"\n=== {prompts.QUOTE_SOURCES} answered: {answered.question} ===\n{answered.answer}", flush=True)
if stop := keep_answer(cycle, answered):
return stop
facts = preflight(cycle) if answered is None and not session_open(cycle.session) else ""
# worker_start runs inside the lambda: a failed attempt may have opened the session.
if stop := retried("worker", lambda: run_worker(cycle.root, worker_start(cycle, answered), worker_environment(cycle), cycle.effects), cycle.effects):
if stop := retried("worker", lambda: run_worker(cycle.root, worker_start(cycle, answered, facts), worker_environment(cycle), cycle.effects), cycle.effects):
return stop
path = transcript_file(cycle.session)
return WorkerRan(path) if path is not None else Stop(1, f"claude left no transcript for session {cycle.session.id}")
@@ -96,12 +97,23 @@ def worker_environment(cycle: Cycle) -> dict[str, str]:
return worker_rungs.environment(cycle.anchor, cycle.route)
def worker_start(cycle: Cycle, answered: QuotedAnswer | None) -> list[str]:
def preflight(cycle: Cycle) -> str:
"""The facts chunk-preflight printed for a fresh worker, or why it could not run them; run once per chunk start, outside the worker's retries."""
try:
done = cycle.effects.preflight(cycle.root)
except OSError as failure:
return prompts.preflight_failed(str(failure))
if done.returncode:
return prompts.preflight_failed(done.stderr.strip() or f"it exited {done.returncode}")
return prompts.preflight_facts(done.stdout.strip())
def worker_start(cycle: Cycle, answered: QuotedAnswer | None, facts: str) -> list[str]:
if answered is not None:
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, facts), resume=False)
def keep_answer(cycle: Cycle, answered: QuotedAnswer) -> Stop | None:
+6
View File
@@ -1,10 +1,13 @@
import dataclasses
import os
import pathlib
import subprocess
import sys
import time
import typing
PREFLIGHT = pathlib.Path(__file__).resolve().parents[1] / "chunk-preflight"
class Streaming(typing.Protocol):
"""A started claude whose stream-json lines arrive as it works."""
@@ -24,6 +27,8 @@ class Effects:
local_time: typing.Callable[[float], str]
now: typing.Callable[[], float]
on_terminal: typing.Callable[[], bool]
# Runs chunk-preflight in the given directory.
preflight: typing.Callable[[str], subprocess.CompletedProcess[str]]
python: typing.Callable[[list[str]], subprocess.CompletedProcess[str]]
sleep: typing.Callable[[float], None]
stream_claude: typing.Callable[[list[str], str, dict[str, str]], Streaming]
@@ -51,6 +56,7 @@ 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(),
preflight=lambda cwd: subprocess.run([sys.executable, str(PREFLIGHT)], capture_output=True, cwd=cwd, stdin=subprocess.DEVNULL, text=True),
python=lambda args: subprocess.run([sys.executable, *args], capture_output=True, text=True),
sleep=time.sleep,
stream_claude=StreamingClaude,
+5 -2
View File
@@ -5,7 +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,
items, or else the task, and never widen them. Before that first worker, loop-claude runs
bin/chunk-preflight at the checkout root, which finds the chunk's mechanical facts and makes its
worktree; the prompt quotes what it printed, or why it could not run. 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
@@ -52,7 +54,8 @@ for a low L; without such an item, or with its L, E or I unscored, the chunk run
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
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: a re-score whose L picks a higher rung is an escalation trigger. 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.
+5 -7
View File
@@ -3,7 +3,7 @@ import dataclasses
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 todo_table import Item, items, next_item
from model_routing.route import Route
UNFINISHED_PER_STEP = 2
@@ -14,13 +14,11 @@ 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."""
"""The item todo_table.next_item names; 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 = next_item(found or [])
return takes if takes and takes.likelihood and takes.escape_and_impact else None
+1
View File
@@ -353,6 +353,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("`~/.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- No default branch: no origin remote, and no main or master branch to take as the default branch\n\nThe chunk's", 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"))
+48 -18
View File
@@ -48,9 +48,9 @@ def human(content):
class FakeEffects:
"""Effects that record each call and answer from a script, one answer per call."""
def __init__(self, claude=(), on_terminal_claude=(), git=(), inputs=(), python=(), streams=(), on_terminal=True):
def __init__(self, claude=(), on_terminal_claude=(), git=(), inputs=(), preflight=(), python=(), streams=(), on_terminal=True):
self.calls = []
self.scripts = {"claude": list(claude), "claude_on_terminal": list(on_terminal_claude), "git": list(git), "input": list(inputs), "python": list(python), "stream_claude": list(streams)}
self.scripts = {"claude": list(claude), "claude_on_terminal": list(on_terminal_claude), "git": list(git), "input": list(inputs), "preflight": list(preflight), "python": list(python), "stream_claude": list(streams)}
self.terminal = on_terminal
self.worker_environments = []
self.terminal_environments = []
@@ -65,6 +65,7 @@ class FakeEffects:
local_time=lambda seconds: f"<{seconds}>",
now=lambda: NOW,
on_terminal=lambda: self.terminal,
preflight=self.preflight,
python=lambda args: self.answer("python", args),
sleep=lambda seconds: self.calls.append(("sleep", seconds)),
stream_claude=self.stream,
@@ -74,6 +75,13 @@ class FakeEffects:
self.terminal_environments.append(env)
return self.answer("claude_on_terminal", args)
def preflight(self, cwd):
"""Answers from the script while it lasts, and else with one fact, since most cycles start a fresh worker."""
if self.scripts["preflight"]:
return self.answer("preflight", cwd)
self.calls.append(("preflight", cwd))
return ran("- A preflight fact.")
def stream(self, args, cwd, env):
self.worker_environments.append(env)
return self.answer("stream_claude", args)
@@ -196,6 +204,24 @@ 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_what_the_preflight_printed_at_the_checkout_root_and_a_resumed_one_runs_none(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"))
self.assertEqual(fake.made("preflight"), [str(self.home)])
fresh, resumed = (args[args.index("-p") + 1] for args in fake.made("stream_claude"))
self.assertIn("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- A preflight fact.", fresh)
self.assertNotIn("chunk-preflight", resumed)
def test_a_fresh_worker_finds_the_facts_itself_where_the_preflight_fails(self):
for failed, why in ((ran(code=1, stderr="git could not start\n"), "git could not start"), (OSError(2, "No such file or directory"), "[Errno 2] No such file or directory")):
with self.subTest(why=why):
fake = FakeEffects(preflight=[failed], streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished")])
self.assertEqual(run.run_cycle(self.cycle(fake)), Finished("working"))
args = fake.made("stream_claude")[0]
self.assertIn(f"loop-claude could not run `~/.claude/bin/chunk-preflight`, so find the chunk's facts yourself: {why}", args[args.index("-p") + 1])
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))
@@ -798,30 +824,34 @@ class WorkerArgs(unittest.TestCase):
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."
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)
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. After your first read", routed)
unrouted = prompts.fresh("Do it.", "## Goals", Route(Rung("m")), None, "")
self.assertIn("before creating a new one.\n\nThe chunk's", unrouted)
self.assertNotIn("loop-claude runs you on", unrouted)
def test_puts_the_preflights_facts_before_the_scope_and_asks_the_worker_to_count_the_items_size_again(self):
fresh = prompts.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, prompts.preflight_facts("- A fact."))
self.assertIn("whether or not it is item 3. After your first read of the code, count item 3'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.\n\nloop-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- A fact.\n\nThe chunk's", fresh)
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.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, ""))
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.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.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.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 +864,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, "")
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 +873,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.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 +881,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, ""))
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.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 +895,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, "").split("\n\nThe chunk's")[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.assertIn(f"{both} After your first read", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 3, 4), opus, ""))
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, ""), 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)
+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]
@@ -213,7 +213,7 @@ class Main(unittest.TestCase):
result = result if "api_error_status" in result else {"type": "result", "structured_output": {"found": [n + 1 for n in result["found"]]}}
return subprocess.CompletedProcess(args, 0, json.dumps(result), "")
effects = Effects(claude=claude, claude_on_terminal=unused, execv=unused, git=system_effects().git, input=unused, local_time=unused, now=unused, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, execv=unused, git=system_effects().git, input=unused, local_time=unused, now=unused, on_terminal=unused, preflight=unused, python=unused, sleep=unused, stream_claude=unused)
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, {}, self.home, effects)
+31
View File
@@ -3,6 +3,7 @@ import re
import typing
from failure import Failure
from markdown_text import FENCE
# 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,8 @@ 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 |"
# 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], ...]
@@ -161,6 +164,34 @@ def waiting(found: list[Item]) -> set[int]:
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: the item the next chunk takes first."""
if not found:
return None
release = min(item.release for item in found)
waits = waiting(found)
return next((item for item in found if item.release == release and item.id not in waits), None)
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")
+6 -16
View File
@@ -6,13 +6,12 @@
`Bar = 0.1`
`Next ID = 175`
`Next ID = 176`
## 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 |
@@ -39,6 +38,7 @@
| 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 time and fresh tokens before the first edit in the first five chunks loop-claude starts with `chunk-preflight` against item 140's, and file an item where they did not fall.** | 1 | 2 | 1 | 2 | 2 | 1.4 by 3, 1.5 by 3 | 4.9 |
| 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 +82,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.
@@ -219,6 +205,10 @@ 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 time and fresh tokens before the first edit in the first five chunks loop-claude starts with `chunk-preflight` against item 140's, and file an item where they did not fall.
Item 161 put `chunk-preflight`'s facts into a fresh worker's prompt, so the worker no longer finds them itself. In item 140's chunk, before it, 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 the same figures from loop-claude's archive for the first five chunks that started with the preflight. Where their median did not fall, file an item naming the facts the workers still found by hand.
### 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).