diff --git a/CHANGELOG.md b/CHANGELOG.md index fd56429a..64d761d7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +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 `.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, `-item-` beside the checkout on the branch `item-`, or continues the one already there. Before it routes each chunk, `loop-claude` runs it and quotes what it printed in the worker's first prompt. The preflight first fast-forwards the checkout to origin's default branch where the checkout is on that branch and holds no uncommitted change, so the chunk is routed on the plan origin holds. Its facts name 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. +- The new `bin/chunk-preflight` finds a chunk's mechanical facts and makes its worktree, `-item-` beside the checkout on the branch `item-`, or continues the one already there. Before it routes each chunk, `loop-claude` runs it and quotes what it printed in the worker's first prompt. The preflight fetches origin and reads `todo.md` from its default branch, leaving the checkout as it is, and `loop-claude` routes on that same `todo.md`, so an edit to `todo.md` routes a chunk only once the default branch holds it. Its facts name 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. Where `todo.md` holds no item for the release after the newest tag, it names no item, and says that release is finished and ready to cut, or is to be planned first. It stops a fetch, forge CLI or tool still running after 60 seconds, or after the seconds `CHUNK_PREFLIGHT_TIMEOUT` sets. 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 diff --git a/CLAUDE.md b/CLAUDE.md index 6c1f692a..1753de5d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 item's row 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-`, in the worktree `-item-` 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 diff --git a/README.md b/README.md index bad1a399..38ffbad1 100644 --- a/README.md +++ b/README.md @@ -82,7 +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` fast-forwards the checkout, 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. +- `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 ` 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 ` 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 ` runs a project's next chunk cycle after cycle; `loop-claude --help` states its contract. diff --git a/bin/chunk-preflight b/bin/chunk-preflight index 4a0ec9bb..b31d06cc 100755 --- a/bin/chunk-preflight +++ b/bin/chunk-preflight @@ -1,4 +1,5 @@ #!/usr/bin/env python3 +import os import pathlib import sys @@ -6,4 +7,4 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent)) from chunk_preflight import main -sys.exit(main.main(sys.argv[1:])) +sys.exit(main.main(sys.argv[1:], os.environ)) diff --git a/bin/chunk_preflight/facts.py b/bin/chunk_preflight/facts.py index 78bb02dd..76ad7d95 100644 --- a/bin/chunk_preflight/facts.py +++ b/bin/chunk_preflight/facts.py @@ -1,18 +1,17 @@ """The lines the preflight prints, stated from what it gathered.""" from todo_table import bundle_candidates, Item from failure import Failure -from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, Plan, pulls_command, Ran, Release +from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, PULLS_LIST, Ran, Release, version from markdown_text import quoted, sections 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 [] - checkout = f"- The checkout was not fast-forwarded: {found.kept_as_is}" if found.kept_as_is else f"- The checkout was fast-forwarded to {found.default}." - head = [*note, checkout, f"- {last_release(found.default, found.release)}"] - if isinstance(found.item, str): - return [*head, f"- No plan item: {found.item}, so no worktree was made."] - return [*head, *item_lines(found.item)] + head = [*note, f"- {last_release(found.default, found.release)}"] + 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: Release) -> str: @@ -22,9 +21,10 @@ def last_release(default: str, release: Release) -> str: 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." - commits = release.commits.reason if isinstance(release.commits, Failure) else counted(release.commits, "commit", "commits") since = f"since {release.tag}" if release.tag else f"on {default}" - return f"{cut} Unreleased: {commits} {since}, and no ## Unreleased in CHANGELOG.md." + 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 unreleased_entries(changelog: str) -> int | None: @@ -33,11 +33,11 @@ def unreleased_entries(changelog: str) -> int | None: return None if found is None else sum(line.startswith("- ") for line in found[0].splitlines()) -def item_lines(item: ItemFacts) -> list[str]: +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"- Next release, in the checkout's todo.md: {release_name(first)}. Its first item that does not wait: item {first.id}, {levels(first)}.", + 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), @@ -52,7 +52,7 @@ def pulls_text(pulls: tuple[Forge, Ran | Failure] | None, branch: str) -> str: if pulls is None: return "none, as the checkout has no origin remote." forge, done = pulls - shown = " ".join(pulls_command(forge, branch)[:3]) + shown = " ".join(PULLS_LIST[forge]) if isinstance(done, Failure): return f"cannot be listed: `{shown}` {done.reason}" if done.code: @@ -71,9 +71,9 @@ def open_pulls(stdout: str, forge: Forge, branch: str) -> list[str]: 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 {release_name(first)} may join item {first.id}'s chunk."] - listed = [f" - item {item.id}, {levels(item)}, S {item.scores.get('S', 'unscored')}: {item.tagline}" for item in candidates] - return [f'- The items of release {release_name(first)} that may join the chunk of item {first.id}, where `~/.claude/CLAUDE.md` → "Working loop" lets them share it:', *listed] + 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]: @@ -104,9 +104,5 @@ def levels(item: Item) -> str: return f"L {item.likelihood or 'unscored'}, E + I {item.escape_and_impact or 'unscored'}" -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}" diff --git a/bin/chunk_preflight/gathered.py b/bin/chunk_preflight/gathered.py index 248f2a26..83f82a4e 100644 --- a/bin/chunk_preflight/gathered.py +++ b/bin/chunk_preflight/gathered.py @@ -9,6 +9,11 @@ from todo_table import Item, item_details, items, next_item # 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")} +# How the plan's earliest release stands to the version x.y.z the newest tag names. "next": it is x.y.z+1, x.y+1.0 or x+1.0.0, or no tag names a version. "cut": it is x.y.z or earlier. +# Else the release after the tag holds no item: "finished" where commits followed the tag, "unplanned" where none did, and "unknown" where they cannot be counted. +Standing = typing.Literal["next", "cut", "finished", "unplanned", "unknown"] @dataclasses.dataclass(frozen=True) @@ -30,7 +35,7 @@ class Release: @dataclasses.dataclass(frozen=True) class Plan: - """The checkout's todo.md items, and first, the item the next chunk takes first.""" + """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. @@ -42,6 +47,12 @@ class Plan: 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 @@ -77,48 +88,57 @@ class Gathered: default: str # Why origin reads as last fetched; None after a fetch. note: str | None - # Why the checkout was not fast-forwarded to default; None once it was. - kept_as_is: str | None release: Release - # The plan's first item and what was found or made for it; else why there is none. - item: ItemFacts | str + # 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) -> Plan | str: - """The checkout's plan and its first item, as todo_table.next_item picks it; else why there is none.""" +def planned(todo: str | Failure, release: Release, default: str) -> Plan | NoItem: + """The plan in todo, the default branch's todo.md, with the item the next chunk takes first, todo_table.next_item's pick, where standing finds the plan's earliest release next; else why there is none.""" + where = f"{default}'s todo.md" if isinstance(todo, Failure): - return f"the checkout's todo.md cannot be read: {todo.reason}" + return NoItem(f"{where} cannot be read: {todo.reason}.") found = items(todo) if isinstance(found, Failure): - return f"the checkout's todo.md cannot be read: {found.reason}" - listed = found or [] - first = next_item(listed) + 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 = standing(release, earliest) + 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, {release.tag}.") + gap = f"{where} holds no item for the release after the last cut, {release.tag}, and" + if stands == "finished": + return NoItem(f"{gap} commits have 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 commit has landed since, so that release is to be planned first.") + if stands == "unknown": + return NoItem(f"{gap} the commits since it cannot be counted.") + first = next_item(found) if first is None: - return "every item of the checkout's next release waits" if listed else "the checkout holds no todo.md items table" + 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(listed, first, f"{first.tagline}\n\n{detail}".strip()) + return Plan(found, first, f"{first.tagline}\n\n{detail}".strip()) -def held_back(default: str, head: str | Failure, status: str | Failure, behind: str | Failure) -> str | None: - """Why the checkout is not fast-forwarded to default, from its branch, its tracked changes and how many commits it is behind; None where nothing holds it back. +def standing(release: Release, earliest: tuple[int, int, int] | None) -> Standing: + """How the plan's earliest release, None where the plan holds no item, stands to the version the release's tag names, as Standing says.""" + cut = re.fullmatch(r"v([0-9]+)\.([0-9]+)\.([0-9]+)", release.tag) if isinstance(release.tag, str) else None + if cut is None: + return "next" + major, minor, patch = (int(part) for part in cut.groups()) + if earliest in ((major, minor, patch + 1), (major, minor + 1, 0), (major + 1, 0, 0)): + return "next" + if earliest is not None and earliest <= (major, minor, patch): + return "cut" + if isinstance(release.commits, Failure): + return "unknown" + return "finished" if release.commits else "unplanned" - A dirty checkout is never fast-forwarded, as `~/.claude/CLAUDE.md` → "Working with the codebase" asks: its changes are for the human to see, never to carry along. - """ - branch = default.removeprefix("origin/") - if branch == default: - return "it has no origin remote" - if isinstance(head, Failure): - return "it is on no branch" - if head.strip() != branch: - return f"it is on {head.strip()}, not {branch}" - if isinstance(status, Failure): - return f"its status cannot be read: {status.reason}" - if status.strip(): - return "it holds uncommitted changes" - if isinstance(behind, Failure): - return f"how far it is behind {default} cannot be read: {behind.reason}" - return f"it is not behind {default}" if int(behind) == 0 else None + +def version(release: tuple[int, int, int]) -> str: + return ".".join(map(str, release)) def worktree_on(porcelain: str, branch: str) -> pathlib.Path | None: @@ -133,11 +153,11 @@ def worktree_on(porcelain: str, branch: str) -> pathlib.Path | 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"on the branch {branch}, which existed already." + 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"on the new branch {branch}, made off origin/{branch}." + 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"on the new branch {branch}, made off {default}." + 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: @@ -147,12 +167,12 @@ def forge_of(origin_url: str) -> Forge: def pulls_command(forge: Forge, branch: str) -> list[str]: """The command that lists open pull requests, by number, head and URL. gh lists only branch's; tea lists every one, for facts.open_pulls to pick branch's.""" if forge == "gh": - return ["gh", "pr", "list", "--head", branch, "--json", "number,url", "--template", "{{range .}}{{.number}}\t{{.url}}\n{{end}}"] - return ["tea", "pulls", "list", "--fields", "index,head,url", "--output", "tsv"] + 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.rstrip("/") for span in re.findall(r"`([^`\s]+)`", text)) + 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] diff --git a/bin/chunk_preflight/main.py b/bin/chunk_preflight/main.py index ca834673..d78042cd 100644 --- a/bin/chunk_preflight/main.py +++ b/bin/chunk_preflight/main.py @@ -5,14 +5,17 @@ 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, as larv-review does. It fast-forwards the checkout to that branch where the -checkout is on it, behind it and holds no uncommitted change; else it says why not. It then reads -the checkout's own todo.md, the file loop-claude routes on, and prints: +local main or master, as larv-review does. It leaves the checkout as it is: it reads todo.md as +that branch holds it, the plan loop-claude routes on, and 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 todo.md, and that release's first item that does not wait, the item - loop-claude routes on, with its L and E + I; +- the earliest release in todo.md, and that release's first item that does not wait, the item + loop-claude routes on, with its L and E + I. It names that item only where the tag names no + version x.y.z, or the release is x.y.z+1, x.y+1.0 or x+1.0.0. For a later release, or a todo.md + that holds no item, it says the release after the tag holds none: finished and ready to cut where + commits followed the tag, and else to be planned first. For x.y.z or an earlier release, it says + todo.md files items under a release already cut; - the item's worktree: a sibling of the checkout named -item-, on the branch item-. 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; @@ -27,84 +30,97 @@ the checkout's own todo.md, the file loop-claude routes on, and prints: `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 tool or forge CLI still running -after TIMEOUT seconds is stopped. With no item, it makes no worktree and runs none of those four -tools. +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, or when git cannot start or finds no checkout. +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, file_at, git, newest_release_tag, top +from git_repo import commit_exists, commits_since, default_branch, default_branch_todo, file_at, git, newest_release_tag, top from failure import Failure -from chunk_preflight.gathered import Forge, forge_of, Gathered, held_back, ItemFacts, named_paths, NamedPath, Plan, planned, pulls_command, Ran, Release, Worktree, worktree_add, worktree_on +from chunk_preflight.gathered import Forge, forge_of, Gathered, ItemFacts, named_paths, NamedPath, NoItem, Plan, planned, pulls_command, Ran, Release, 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 tool or forge CLI is stopped, so a hung one leaves the facts the others find. +# Seconds before a fetch, forge CLI or tool is stopped, so a hung one leaves the facts the others find; TIMEOUT_SETTING sets others. TIMEOUT = 60 +TIMEOUT_SETTING = "CHUNK_PREFLIGHT_TIMEOUT" -def main(argv: list[str]) -> int: +def main(argv: list[str], env: typing.Mapping[str, str]) -> int: if argv in (["-h"], ["--help"]): - print(__doc__.strip()) + print(__doc__.strip().format(timeout=TIMEOUT)) 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) + printed = run(env.get(TIMEOUT_SETTING)) + if isinstance(printed, Failure): + print(printed.reason, file=sys.stderr) return 1 - print("\n".join(preflight(pathlib.Path(root)))) + print("\n".join(printed)) return 0 -def preflight(root: pathlib.Path) -> list[str]: - """Gathers the facts step by step, each step taking what the ones before it found, and renders them.""" - default = default_branch(stale_ok=True) +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 seconds a TIMEOUT_SETTING of setting gives, TIMEOUT where it is 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 [f"- No default branch: {default.reason}"] + return default ref, note = default - # First, so the plan read next is the fast-forwarded checkout's. - kept_as_is = fast_forward(ref) - plan = planned(text_of(root / "todo.md")) - item = plan if isinstance(plan, str) else item_facts(root, ref, plan) - return render(Gathered(ref, note, kept_as_is, release(ref), item)) + cut = release(ref, root) + plan = planned(default_branch_todo(str(root), timeout), cut, ref) + item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout) + return render(Gathered(ref, note, cut, item)) -def fast_forward(default: str) -> str | None: - """Fast-forwards the checkout to default unless held_back says why not; None once it has.""" - held = held_back(default, git("symbolic-ref", "--quiet", "--short", "HEAD"), git("status", "--porcelain", "--untracked-files=no"), git("rev-list", "--count", f"HEAD..{default}")) - if held is not None: - return held - merged = git("merge", "--ff-only", "--quiet", default) - return merged.reason if isinstance(merged, Failure) else None - - -def release(default: str) -> Release: +def release(default: str, root: pathlib.Path) -> Release: tag = newest_release_tag(default) - commits = git("rev-list", "--count", f"{tag}..{default}" if isinstance(tag, str) else default) - return Release(tag, file_at(default, "CHANGELOG.md"), commits if isinstance(commits, Failure) else int(commits)) + commits = tag if isinstance(tag, Failure) else commits_since(tag, default) + return Release(tag, file_at(default, "CHANGELOG.md", str(root)), commits) -def item_facts(root: pathlib.Path, default: str, plan: Plan) -> ItemFacts: +def item_facts(root: pathlib.Path, default: str, plan: Plan, timeout: float) -> ItemFacts: worktree = item_worktree(root, plan.branch, default) - made = worktree.path if isinstance(worktree, Worktree) else None - return ItemFacts(plan, worktree, pull_listing(root, plan.branch), named_files(plan.text, made or root), tools_run(plan.first.id, made) if made else []) + 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.""" - held = git("worktree", "list", "--porcelain") - if isinstance(held, Failure): - return held - if (path := worktree_on(held, branch)) is not None: - return Worktree(path, f"on the branch {branch}, which it already held.") + 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}") @@ -113,12 +129,12 @@ def item_worktree(root: pathlib.Path, branch: str, default: str) -> Worktree | F return Failure(f"none made: {added.reason}") if isinstance(added, Failure) else Worktree(path, how) -def pull_listing(root: pathlib.Path, branch: str) -> tuple[Forge, Ran | Failure] | None: +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) + return forge, ran(pulls_command(forge, branch), root, timeout) def named_files(text: str, base: pathlib.Path) -> list[NamedPath] | Failure: @@ -132,28 +148,20 @@ 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 - text = text_of(path) - return text if isinstance(text, Failure) else len(text.splitlines()) - - -def tools_run(item_id: int, worktree: pathlib.Path) -> 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)) for command in commands] - - -def text_of(path: pathlib.Path) -> str | Failure: - """A file's text; empty where there is no such file.""" try: - return path.read_text(encoding="utf-8") - except FileNotFoundError: - return "" + return len(path.read_text(encoding="utf-8").splitlines()) except (OSError, UnicodeDecodeError) as failure: return Failure(str(failure)) -def ran(command: list[str], cwd: pathlib.Path) -> Ran | 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, stdin=subprocess.DEVNULL, text=True, timeout=TIMEOUT) + 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) diff --git a/bin/chunk_preflight/test_chunk_preflight.py b/bin/chunk_preflight/test_chunk_preflight.py index d0e1a755..c515ccdb 100644 --- a/bin/chunk_preflight/test_chunk_preflight.py +++ b/bin/chunk_preflight/test_chunk_preflight.py @@ -9,8 +9,9 @@ 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, held_back, ItemFacts, NamedPath, planned, Ran, Release, Worktree, worktree_add +from chunk_preflight.gathered import forge_of, Gathered, ItemFacts, named_paths, NamedPath, NoItem, planned, Ran, Release, standing, Worktree, worktree_add from test_env import isolated_env +from chunk_preflight.main import line_count, ran, seconds, TIMEOUT from chunk_preflight.facts import open_pulls, render, unreleased_entries BIN = pathlib.Path(__file__).resolve().parents[1] @@ -44,26 +45,40 @@ 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 = Release("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 /proj, and a fake tea on PATH.""" + """An origin with a tagged release, a clone of it at /proj, and a fake tea and gh on PATH.""" - def __init__(self, test, todo=TODO): + def __init__(self, test, todo=TODO, origin="origin.git"): temp = tempfile.TemporaryDirectory() test.addCleanup(temp.cleanup) self.temp = pathlib.Path(os.path.realpath(temp.name)) - self.origin = self.temp / "origin.git" + self.origin = self.temp / origin 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.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) @@ -95,24 +110,34 @@ class Repo: self.commit(other, "elsewhere") self.git(other, "push", "--quiet", "origin", "main") - 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) + 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_fast_forwards_the_checkout_reads_its_plan_and_makes_the_items_worktree_off_the_fetched_default_branch(self): + 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"), repo.git(repo.root, "rev-parse", "origin/main")) + 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 ( - "fast-forwarded to origin/main", "item 7, L 1, E + I 2", - f"{worktree}, on the new branch item-7, made off origin/main.", + str(worktree), + "item-7, made off origin/main", "#12 https://forge/pulls/12", "`src/app.py`: 3 lines", "`src`: 1 file", @@ -120,9 +145,10 @@ class ChunkPreflightTool(unittest.TestCase): "`larv-review needs-scoring-run 7` exited 0", "`reading-cost` exited 0", "`larv-review places` exited 0", - f"to {worktree}/docs/reading-cost.md", + f"{worktree}/docs/reading-cost.md", ): - self.assertIn(fact, done.stdout) + with self.subTest(fact=fact): + self.assertIn(fact, done.stdout) self.assertNotIn("#13", done.stdout) self.assertNotIn("`gone.py`:", done.stdout) @@ -130,31 +156,87 @@ class ChunkPreflightTool(unittest.TestCase): 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) + 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") - self.assertIn(f"Worktree: {worktree}, on the new branch item-3, made off origin/item-3.", repo.preflight().stdout) + 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"Worktree: none made, since {repo.temp / 'proj-item-3'} exists", done.stdout) + 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("Last version cut: v0.1.0.", done.stdout) - self.assertIn("No plan item: the checkout holds no todo.md items table, so no worktree was made.", done.stdout) + 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) @@ -162,52 +244,98 @@ class ChunkPreflightTool(unittest.TestCase): self.assertIn("git rev-parse --show-toplevel", done.stderr) -def item_facts(**fields): - """Item 3's facts, its worktree made, with fields given replacing the rest.""" - plan = planned(TODO) - return ItemFacts(**{"plan": plan, "worktree": Worktree(pathlib.Path("/c/proj-item-3"), "on the new branch item-3, made off origin/main."), "pulls": None, "named": [], "tools": [], **fields}) +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=Release("v0.1.0", CHANGELOG, 4), kept_as_is=None): - return "\n".join(render(Gathered("origin/main", None, kept_as_is, release, item))) +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_next_item_its_levels_and_detail_and_each_item_that_may_join_its_chunk(self): + 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("0.2.0", said) + 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_unreleased_entries_and_else_the_commits_since_the_last_cut(self): - self.assertIn("v0.1.0. Unreleased: 2 entries", rendered("no item")) - self.assertIn("v0.1.0. Unreleased: 4 commits since v0.1.0", rendered("no item", Release("v0.1.0", "# Changelog\n", 4))) - self.assertIn("none. Unreleased: 1 commit on origin/main", rendered("no item", Release(None, "", 1))) + 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_whether_the_checkout_was_fast_forwarded_and_why_there_is_no_plan_item(self): - self.assertIn("The checkout was fast-forwarded to origin/main.", rendered("every item waits")) - said = rendered("every item waits", kept_as_is="it holds uncommitted changes") - self.assertIn("The checkout was not fast-forwarded: it holds uncommitted changes", said) - self.assertIn("No plan item: every item waits, so no worktree was made.", said) + 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."), Release("v0.1.0", "## Unreleased\n\n- One.\n", 4))) + without = rendered(NoItem("x."), Release("v0.1.0", "# Changelog\n", 4)) + self.assertIn("4 commits since v0.1.0", without) + self.assertIn("no ## Unreleased", without) + untagged = rendered(NoItem("x."), Release(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."), Release("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): - self.assertIn("Open pull requests from item-3: #12 https://forge/pulls/12\n", rendered(item_facts(pulls=("tea", Ran(0, "index\thead\turl\n12\titem-3\thttps://forge/pulls/12\n", ""))))) - self.assertIn("Open pull requests from item-3: none.", rendered(item_facts(pulls=("gh", Ran(0, "", ""))))) - self.assertIn("Open pull requests from item-3: none, as the checkout has no origin remote.", rendered(item_facts())) - self.assertIn("Open pull requests from item-3: cannot be listed: `tea pulls list` exited 1: no login", rendered(item_facts(pulls=("tea", Ran(1, "", "no login\n"))))) + 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"))])) + 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 places", Failure("could not finish: timed out"))])) - self.assertIn("`rank_todo.py --check todo.md` exited 0, printing:\n\n> ranked", said) - self.assertIn("`reading-cost` exited 1, printing nothing.", said) + 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) @@ -217,18 +345,88 @@ class OpenPulls(unittest.TestCase): 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, Release(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 counted"), + ) + for todo, commits, fact in cases: + with self.subTest(todo=todo, commits=commits): + why = planned(todo, Release("v0.1.0", "", commits), "origin/main").why + self.assertIn(fact, why) + self.assertIn("v0.1.0", why) + + def test_says_the_plan_files_items_under_a_release_already_cut(self): + why = planned(TODO, Release("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 Standing(unittest.TestCase): + def test_takes_the_earliest_release_where_it_is_the_next_patch_minor_or_major_or_no_tag_names_a_version(self): + cases = ( + (Release("v1.2.3", "", 4), (1, 2, 4), "next"), + (Release("v1.2.3", "", 4), (1, 3, 0), "next"), + (Release("v1.2.3", "", 4), (2, 0, 0), "next"), + (Release(None, "", 4), (0, 2, 0), "next"), + (Release(None, "", 4), None, "next"), + (Release("v1.2.3-rc.1", "", 4), (1, 2, 3), "next"), + (Release(Failure("tags unreadable"), "", 4), (0, 2, 0), "next"), + (Release("v1.2.3", "", 4), (1, 2, 3), "cut"), + (Release("v1.2.3", "", 4), (1, 2, 2), "cut"), + (Release("v1.2.3", "", 4), (1, 2, 5), "finished"), + (Release("v1.2.3", "", 4), (1, 3, 1), "finished"), + (Release("v1.2.3", "", 4), (2, 0, 1), "finished"), + (Release("v1.2.3", "", 4), None, "finished"), + (Release("v1.2.3", "", 0), (1, 4, 0), "unplanned"), + (Release("v1.2.3", "", 0), None, "unplanned"), + (Release("v1.2.3", "", Failure("count unreadable")), (1, 4, 0), "unknown"), + ) + for release, earliest, stands in cases: + with self.subTest(release=release, earliest=earliest): + self.assertEqual(standing(release, earliest), stands) + + 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_picks_the_next_releases_first_item_that_does_not_wait_or_says_why_there_is_none(self): - self.assertEqual(planned(TODO).first.id, 3) - self.assertEqual(planned(""), "the checkout holds no todo.md items table") - self.assertEqual(planned(TODO.replace("| 3 | 0.2.0 | | |", "| 3 | 0.2.0 | | question |")), "every item of the checkout's next release waits") - self.assertEqual(planned(Failure("Permission denied")), "the checkout's todo.md cannot be read: Permission denied") - self.assertIn("todo.md's details cannot be read", planned(TODO + "```\n").text) + 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") @@ -240,19 +438,35 @@ class Gathering(unittest.TestCase): 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_fast_forwards_only_a_clean_checkout_on_the_default_branch_that_is_behind_it(self): - cases = ( - (("main", "main\n", "", "2\n"), "it has no origin remote"), - (("origin/main", Failure(""), "", "2\n"), "it is on no branch"), - (("origin/main", "item-5\n", "", "2\n"), "it is on item-5, not main"), - (("origin/main", "main\n", " M todo.md\n", "2\n"), "it holds uncommitted changes"), - (("origin/main", "main\n", "", "0\n"), "it is not behind origin/main"), - (("origin/main", "main\n", Failure("git status: broken"), "2\n"), "its status cannot be read: git status: broken"), - (("origin/main", "main\n", "", "2\n"), None), - ) - for found, why in cases: - with self.subTest(found=found): - self.assertEqual(held_back(*found), why) + 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__": diff --git a/bin/git_repo.py b/bin/git_repo.py index a84eaf22..20bee97c 100644 --- a/bin/git_repo.py +++ b/bin/git_repo.py @@ -1,15 +1,20 @@ -"""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 re import subprocess from failure import Failure -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 +23,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/` 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 for stderr. 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/` 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,6 +60,12 @@ def origin_head() -> str | Failure: return Failure("origin names no default branch; set it with `git remote set-head origin --auto`") +def default_branch_todo(root: str, timeout: float) -> str | Failure: + """todo.md on the default branch as last fetched, read in the checkout at root; empty where that branch holds none. Asking origin, where the checkout records no default branch for it, fails after timeout seconds.""" + ref = default_ref(root, timeout) + return ref if isinstance(ref, Failure) else file_at(ref, "todo.md", root) + + 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. @@ -54,18 +73,24 @@ def newest_release_tag(branch: str) -> str | None | Failure: 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) +def commits_since(tag: str | None, branch: str) -> int | Failure: + """How many commits branch holds after tag, or holds in all where tag is None.""" + count = git("rev-list", "--count", f"{tag}..{branch}" if tag else branch) + return count if isinstance(count, Failure) else int(count) -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 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: diff --git a/bin/larv_review/git.py b/bin/larv_review/git.py index b9c8f839..7053047c 100644 --- a/bin/larv_review/git.py +++ b/bin/larv_review/git.py @@ -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, newest_release_tag from comprehension_history import HISTORY, HistoryChange @@ -27,5 +27,5 @@ def landed_since_release(default: str) -> bool | Failure: 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 + count = commits_since(newest, default) + return count if isinstance(count, Failure) else count > 0 diff --git a/bin/loop_claude/cycle/prompts.py b/bin/loop_claude/cycle/prompts.py index f130248a..b40bb8ba 100644 --- a/bin/loop_claude/cycle/prompts.py +++ b/bin/loop_claude/cycle/prompts.py @@ -17,7 +17,7 @@ def fresh(task: str, premises: str, route: Route, anchor: Rung | None, facts: st """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)}{recount(route)}\n\n" if route.item else (f"{escalated}\n\n" if escalated else "") - return f"{task}\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}" + 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: @@ -35,8 +35,8 @@ def preflight_facts(printed: str) -> str: def preflight_failed(reason: str) -> str: - """Has the worker find the facts chunk-preflight would have, its worktree and open pull request among them.""" - return f"loop-claude could not run `~/.claude/bin/chunk-preflight`, so find the chunk's facts yourself. Continue any open draft PR or worktree for the chunk before creating a new one. Why it could not run: {reason}" + """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: diff --git a/bin/loop_claude/effects.py b/bin/loop_claude/effects.py index 215980c1..760444e9 100644 --- a/bin/loop_claude/effects.py +++ b/bin/loop_claude/effects.py @@ -62,9 +62,11 @@ def system_effects() -> Effects: def run_python(args: list[str], cwd: str, timeout: float) -> subprocess.CompletedProcess[str]: - """Runs a Python script in cwd. One still running after timeout seconds is stopped, and reads as exit 1, saying so on stderr.""" + """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, stdin=subprocess.DEVNULL, text=True, timeout=timeout) + 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") diff --git a/bin/loop_claude/loop/main.py b/bin/loop_claude/loop/main.py index db2aadd9..25d0b542 100644 --- a/bin/loop_claude/loop/main.py +++ b/bin/loop_claude/loop/main.py @@ -6,11 +6,12 @@ Run it anywhere inside a project checkout whose README.md has ## Goals and ## Au 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. As a chunk starts, before it is routed, loop-claude -runs bin/chunk-preflight (bin/chunk_preflight/), which fast-forwards the checkout and finds the -chunk's facts; chunk-preflight --help lists them, and prompts.preflight_facts in -bin/loop_claude/cycle/prompts.py quotes them in the first prompt. 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 +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. 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 @@ -48,13 +49,13 @@ 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, the checkout's -todo.md, read once chunk-preflight has run, routes it, so routing and the preflight's facts name one -item: the next release's top item that does not wait. 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, todo.md on the +default branch, as chunk-preflight has just fetched it, routes it: its earliest release's top item +that does not wait, the item the preflight states where that release is the next. 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, and to count the item's size again @@ -153,6 +154,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_branch_todo from loop_claude.effects import Effects from failure import Failure from loop_claude.cycle.judge import Finished, Unfinished @@ -171,6 +173,9 @@ from model_routing.route import Route, route_from from claude_code.session import Session, session_named, session_open, transcript_file from loop_claude.stop import Stop +# Seconds before routing gives up asking origin for its default branch, which it asks only where the checkout records none, and routes 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: @@ -195,8 +200,6 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc if stop := exec_if_edited(launcher, baseline, loop_run, effects): return stop loop_run = dataclasses.replace(loop_run, cycle_number=loop_run.cycle_number + 1) - # First, so the premises, the records and the plan item routing reads are the checkout's as the preflight fast-forwarded it. - facts = "" if session_open(session) else chunk_facts(launcher.with_name("chunk-preflight"), loop_run.root, effects) premises = read_premises(loop_run.root) if isinstance(premises, Stop): return premises @@ -206,9 +209,11 @@ 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(default_branch_todo(root, ORIGIN_TIMEOUT))) 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, 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)) @@ -258,23 +263,15 @@ def archived_route(archive_folder: pathlib.Path, session: Session) -> Route | No 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.""" - try: - done = effects.python([str(preflight)], root) - except OSError as failure: - return prompts.preflight_failed(str(failure)) + 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 plan_item(root: str) -> Item | None: - """The item that routes a chunk, from the checkout's todo.md: the file chunk-preflight reads, and the pick, todo_table.next_item, it makes. 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 plan_item(todo: str | Failure) -> Item | None: + """The item that routes a chunk, from todo.md as git_repo.default_branch_todo reads it, as chunk-preflight does, so both take todo_table.next_item's pick. None without one, so the chunk runs on the project's rung.""" + item = todo if isinstance(todo, Failure) else routed_item(todo) if isinstance(item, Failure): print(f"routing on the project's rung: {item.reason}", file=sys.stderr) return None diff --git a/bin/loop_claude/loop/reload.py b/bin/loop_claude/loop/reload.py index 404cd9be..87363c54 100644 --- a/bin/loop_claude/loop/reload.py +++ b/bin/loop_claude/loop/reload.py @@ -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"], 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 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 ") diff --git a/bin/loop_claude/test_black_box.py b/bin/loop_claude/test_black_box.py index 1e4f2fb6..42031b5d 100644 --- a/bin/loop_claude/test_black_box.py +++ b/bin/loop_claude/test_black_box.py @@ -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"): @@ -351,9 +365,9 @@ class Cycles(unittest.TestCase): self.assertIsNone(argument(workers[1], "--session-id")) self.assertIsNone(argument(workers[1], "--name")) self.assertEqual(argument(workers[2], "--session-id"), session) - self.assertTrue(argument(workers[0], "-p").startswith(f"{TASK}\n\n")) + 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("\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.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")) @@ -375,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"), @@ -398,34 +412,34 @@ class Cycles(unittest.TestCase): self.assertIn(" 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 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(" 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_fast_forwards_the_checkout_before_routing_so_routing_and_the_preflight_name_the_same_item(self): + 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.root / "todo.md").write_text(TODO) - checkout.git("add", "-A") - checkout.git("commit", "--quiet", "-m", "plan item 4") + 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. + # 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") - run = checkout.run([worker()]) + (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("Its first item that does not wait: item 6,", prompt) - self.assertIn("The checkout was fast-forwarded to origin/main.", 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."), @@ -447,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") @@ -460,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"), @@ -478,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")) diff --git a/bin/loop_claude/test_loop_claude.py b/bin/loop_claude/test_loop_claude.py index 546eb48c..c5329bc0 100644 --- a/bin/loop_claude/test_loop_claude.py +++ b/bin/loop_claude/test_loop_claude.py @@ -18,7 +18,7 @@ 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, run_python +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 @@ -721,17 +721,13 @@ 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("")) + self.assertEqual(main.plan_item(TODO).id, 3) + for todo, 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"), (Failure("git show origin/main:todo.md printed text that is not UTF-8"), "routing on the project's rung: git show origin/main:todo.md printed text that is not UTF-8\n")): + with self.subTest(said=said): + with contextlib.redirect_stderr(io.StringIO()) as stderr: + self.assertIsNone(main.plan_item(todo)) + 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: @@ -810,12 +806,13 @@ class ChunkFacts(unittest.TestCase): 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), "it exited 1"), (OSError(2, "No such file or directory"), "No such file or directory")): + 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("find the chunk's facts yourself", said) + self.assertIn("yourself", said) self.assertIn(why, said) @@ -827,7 +824,18 @@ class PythonEffect(unittest.TestCase): 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("after 0.5 s", done.stderr) + 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): @@ -838,25 +846,29 @@ class WorkerArgs(unittest.TestCase): 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.FACTS) - self.assertIn("Do it.\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) + 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"Do it.\n\n{self.FACTS}\n\nThe chunk's", unrouted) + 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("After your first read of the code, count item 3's size again", routed) + 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_and_continue_an_open_pr_itself(self): - self.assertIn("Take what it printed as found rather than finding it again:\n\n- A fact.", prompts.preflight_facts("- A fact.")) + 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("find the chunk's facts yourself", failed) - self.assertIn("Continue any open draft PR or worktree for the chunk before creating a new one.", failed) + 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, self.FACTS) @@ -904,7 +916,7 @@ 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("Do it.\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 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)) + 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 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") @@ -1110,6 +1122,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): diff --git a/bin/repo_checks/test_types.py b/bin/repo_checks/test_types.py index ec14b846..4271ed85 100644 --- a/bin/repo_checks/test_types.py +++ b/bin/repo_checks/test_types.py @@ -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) diff --git a/bin/test_git_repo.py b/bin/test_git_repo.py new file mode 100644 index 00000000..45c55c1e --- /dev/null +++ b/bin/test_git_repo.py @@ -0,0 +1,28 @@ +import pathlib +import sys +import unittest + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent)) + +from failure import Failure +from git_repo import git + + +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("-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("-c", "alias.latin=!printf 'caf\\351'", "latin") + self.assertIsInstance(done, Failure) + self.assertIn("latin", done.reason) + self.assertIn("UTF-8", done.reason) + + +if __name__ == "__main__": + unittest.main() diff --git a/bin/test_rank_todo.py b/bin/test_rank_todo.py index 311a94f0..ae5d1ef9 100644 --- a/bin/test_rank_todo.py +++ b/bin/test_rank_todo.py @@ -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}) diff --git a/skills/larv-review/SKILL.md b/skills/larv-review/SKILL.md index 70625d6e..17f1cffd 100644 --- a/skills/larv-review/SKILL.md +++ b/skills/larv-review/SKILL.md @@ -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 already shows its output 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 diff --git a/todo.md b/todo.md index 275a4ffb..2d7cb57e 100644 --- a/todo.md +++ b/todo.md @@ -38,7 +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 | +| 175 | 0.3.0 | | | **Compare the first five chunks loop-claude starts with `chunk-preflight` against the five before them, by time and fresh tokens before the first edit and by review rounds and unfinished verdicts, and file an item where the preflight did not pay.** | 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 | @@ -205,9 +205,9 @@ 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. +### 175. Compare the first five chunks loop-claude starts with `chunk-preflight` against the five before them, by time and fresh tokens before the first edit and by review rounds and unfinished verdicts, and file an item where the preflight did not pay. -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. +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 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 goal 1.4's counter-signal beside them, review rounds and unfinished verdicts per chunk, since a worker that reads less may start sooner and need more rounds. Where time or tokens did not fall, or rounds or unfinished verdicts rose, file an item naming the facts the workers still found by hand, or what the preflight got wrong. ### 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.