Pass over an item whose pull request awaits a person's merge, and hold a sentence about several named things to each
CI / tests (pull_request) Failing after 3m42s

This commit is contained in:
Lilleman
2026-11-19 21:54:43 +01:00
parent 06a1398196
commit 00975177ad
22 changed files with 312 additions and 27 deletions
+1 -1
View File
@@ -119,7 +119,7 @@ A legacy project with no container setup sets `tooling-on-host = true`, so the l
A project whose pull requests need a human's approval sets `wait-for-approval = true` in its config. `chunk-pr merge` then waits, once the checks have passed, until GitHub reports the pull request approved as its branch protection requires, and merges it. It refuses on Gitea, where a reviewer requested changes and where the protection requires no review. While it waits, other chunks merge. It stops where a reviewer's comment waits for an answer, on an approved pull request too; answer it and run it again. It gives up after 90 minutes without an approval; run it again once the pull request is approved. Left out, the setting is false.
A project whose team merges its pull requests itself sets `merge = "human"`. `chunk-pr merge` then brings the branch level with origin's default branch, finishes the chunk's plan items, waits for the checks and marks the pull request ready, but leaves the merge to a person. A plan or changelog kept in the checkout is finished on the branch, so it lands with that merge; one kept in Jira, or in the config's folder, is finished at once. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. Left out, the setting is `"chunk"`: the chunk merges.
A project whose team merges its pull requests itself sets `merge = "human"`. `chunk-pr merge` then brings the branch level with origin's default branch, finishes the chunk's plan items, waits for the checks and marks the pull request ready, but leaves the merge to a person. A plan or changelog kept in the checkout is finished on the branch, so it lands with that merge; one kept in Jira, or in the config's folder, is finished at once. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. loop-claude starts no chunk from an item such a pull request finishes. Once every item left in the release waits and one waits for a merge, the loop stops and names the pull requests to merge. The first chunk after a merge runs `chunk-pr clean` in the worktree the merged one left. Nobody works on a pull request that awaits your merge: to have a reviewer's comment answered, turn it back into a draft, and a chunk takes its item up again. Left out, the setting is `"chunk"`: the chunk merges.
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows: the plan, the working rules in an `AGENTS.md` I write for the agents, the records, and the goals and audience, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits in the checkout's history, so four things are not supported for it yet. `score-outcomes` and loop-claude's routing figures count a project's chunks only where `todo.md`, `docs/comprehension-history.md` and `docs/reading-cost.md` are at those paths in the checkout; otherwise each says so, and the loop goes on. For a plan or a comprehension history outside the checkout, `larv-review` says it cannot tell whether a scoring run is owed, and for such a history it cannot find a paired ruling's base. For a plan outside the checkout, chunk-preflight and loop-claude don't see a release whose last item has shipped, and say that its release review and its cut are yours to call. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
+1
View File
@@ -476,6 +476,7 @@ def finished(run: Run, branch: str, finish: list[str], config: ProjectConfig) ->
if isinstance(finishing, Failure):
return finishing
title = templates.title_of(config.commit_title, config.branch, branch, finish[0], f"Finish item {finish[0]} in the plan")
# Under `merge = "human"` a plan or changelog outside the checkout is finished here, before the person merges, since no run follows that merge; where they close the pull request unmerged, they file the item again.
# A plan in Jira, or a changelog on a Confluence page, is no file to commit.
records = [record for record in (config.plan_file, config.paths.get("changelog")) if record is not None and record.is_file()]
return committed(run, title, records)
+7 -5
View File
@@ -9,11 +9,13 @@ PULLS_LIST: dict[Forge, tuple[str, ...]] = {"gh": ("gh", "pr", "list"), "tea": (
def worktree_on(porcelain: str, branch: str) -> pathlib.Path | None:
"""The worktree on branch, in what `git worktree list --porcelain` printed; None where none is."""
for block in porcelain.split("\n\n"):
fields = dict(line.partition(" ")[::2] for line in block.splitlines())
if fields.get("branch") == f"refs/heads/{branch}":
return pathlib.Path(fields["worktree"])
return None
return next((path for path, on, _ in worktrees(porcelain) if on == branch), None)
def worktrees(porcelain: str) -> list[tuple[pathlib.Path, str, str]]:
"""Each worktree on a branch, in what `git worktree list --porcelain` printed: its path, its branch and its head commit."""
blocks = [dict(line.partition(" ")[::2] for line in block.splitlines()) for block in porcelain.split("\n\n")]
return [(pathlib.Path(fields["worktree"]), fields["branch"].removeprefix("refs/heads/"), fields.get("HEAD", "")) for fields in blocks if fields.get("branch", "").startswith("refs/heads/")]
def worktree_add(branch: str, path: pathlib.Path, default: str, local: bool, pushed: bool) -> tuple[list[str], str]:
+11 -1
View File
@@ -19,7 +19,7 @@ def render(found: Gathered) -> list[str]:
"""One `- ` line per fact, then the item's tagline and detail, the detail of each item that may join its chunk, and what each tool printed."""
note = [f"- {found.note}"] if found.note else []
unseen = [f"- {UNSEEN_RELEASES}"] if found.plan_outside else []
head = [*note, f"- {last_release(found.default, found.cut)}", *unseen]
head = [*note, f"- {last_release(found.default, found.cut)}", *unseen, *merge_lines(found)]
paths = f"- The project's config puts its files and plan at: {'; '.join(f'{setting} {path}' for setting, path in found.places.items())}."
texts = f"- The project's config sets: {'; '.join(f'{setting} {text}' for setting, text in found.texts.items())}."
if isinstance(found.item, NoItem):
@@ -28,6 +28,16 @@ def render(found: Gathered) -> list[str]:
return [*head, *lines[:2], paths, texts, *lines[2:]]
def merge_lines(found: Gathered) -> list[str]:
"""What `merge = "human"` leaves for the worker to know: each worktree a merged pull request left, the items passed over since their pull request awaits a person's merge, and why those could not be read."""
left = [f"- The worktree {worktree.path}, on the branch {worktree.branch}, is left from pull request #{worktree.pull}, which has merged: run `~/.claude/bin/chunk-pr clean` in it as this chunk's first step." for worktree in found.left]
items = found.item.plan.items if isinstance(found.item, ItemFacts) else []
passed = [f"item {item.id}, by pull request {item.awaits_merge}" for item in items if item.awaits_merge]
over = [f"- Passed over, since each is finished on a branch whose pull request is ready and awaits a person's merge: {'; '.join(passed)}. No chunk takes one."] if passed else []
unread = [f"- The pull requests that await a person's merge cannot be read, so no item is passed over for one: {found.merges_unread.reason}"] if found.merges_unread else []
return [*left, *over, *unread]
def last_release(default: str, release: LastCut) -> str:
if isinstance(release.tag, Failure):
return f"Last version cut: cannot be read: {release.tag.reason}"
+12
View File
@@ -44,6 +44,14 @@ class ItemFacts:
tools: list[tuple[str, Ran | Failure]]
@dataclasses.dataclass(frozen=True)
class LeftWorktree:
"""A worktree on a branch whose pull request, of this number, has merged."""
path: pathlib.Path
branch: str
pull: str
@dataclasses.dataclass(frozen=True)
class Gathered:
"""Everything the preflight read and ran, for facts.render to state."""
@@ -62,3 +70,7 @@ class Gathered:
plan_outside: bool
# The language and the templates the project's config names, by their settings.
texts: dict[str, str]
# Why the pull requests that await a person's merge could not be read; None where they were read, or the chunk merges its own.
merges_unread: Failure | None = None
# Each other worktree whose pull request a person has merged, which `chunk-pr clean` is still to remove.
left: tuple[LeftWorktree, ...] = ()
+31 -5
View File
@@ -16,6 +16,11 @@ and prints that the release reviews and the cuts are the human's to call. It pri
newest version CHANGELOG.md heads `## X.Y.Z - YYYY-MM-DD`; an undated heading doesn't count.
Then how many entries the default branch's CHANGELOG.md holds under ## Unreleased, or else how
many commits followed the cut: the tag, or the commit that added that heading;
- under `merge = "human"` (`project-config --help`), each other worktree whose pull request has
merged, for the worker to run `chunk-pr clean` in, and each item passed over: one that an open
pull request, no draft, finished on its branch, where the checkout holds the plan. Such an item
waits until a person merges. Where every item left in the release waits and one awaits a merge,
it names those pull requests and says the working loop stops there;
- the next release and its first item that does not wait, the item loop-claude routes on, with its L
and E + I; with --item <ID>, the plan item of that ID instead, which loop-claude names in a window
named for an item. An item waits while it is marked question, or while an item still in todo.md
@@ -78,14 +83,15 @@ import typing
from git_cli.git_repo import commit_exists, default_branch, file_at, git, top
from failure import Failure
from forge.commands import Forge, forge_of
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, Ran, Worktree
from forge.commands import Forge, forge_of, Run
from chunk_preflight.gathered import Gathered, ItemFacts, LeftWorktree, NamedPath, Ran, Worktree
from chunk_preflight.facts import JOINING_DETAILS, render
from project_config.main import located
from forge.pulls import merged_pull
from plan.named_paths import named_paths
from release_plan.next_chunk import NextChunk, NoItem, plan_name, planned
from release_plan.release_standing import project_plan
from chunk_preflight.choices import pulls_command, worktree_add, worktree_on
from chunk_preflight.choices import pulls_command, worktree_add, worktree_on, worktrees
BIN = pathlib.Path(__file__).resolve().parents[1]
# Each tool run in the item's worktree, {item} standing for the item's ID.
@@ -143,12 +149,13 @@ def preflight(root: pathlib.Path, timeout: float, make: bool, item_id: int | Non
if isinstance(config, Failure):
return config
outside = None if config.tracked("plan") else config.plan_label
held = project_plan(config, ref, str(root))
forge_run = forge_runner(root, timeout)
held = project_plan(config, ref, str(root), forge_run=forge_run)
plan = planned(held.plan, held.cut, ref, config.branch, outside, item_id)
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout, make)
# A `checkout:` path lands in the worktree the chunk works in.
made = located(str(item.worktree.path), pathlib.Path.home()) if isinstance(item, ItemFacts) and isinstance(item.worktree, Worktree) else config
return render(Gathered(ref, note, held.cut, item, plan_name(ref, outside), (config if isinstance(made, Failure) else made).places, outside is not None, config.texts))
return render(Gathered(ref, note, held.cut, item, plan_name(ref, outside), (config if isinstance(made, Failure) else made).places, outside is not None, config.texts, held.merges_unread, left_worktrees(root, forge_run) if config.merge == "human" else ()))
def item_facts(root: pathlib.Path, default: str, plan: NextChunk, timeout: float, make: bool) -> ItemFacts:
@@ -173,6 +180,25 @@ 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 left_worktrees(root: pathlib.Path, forge_run: Run) -> tuple[LeftWorktree, ...]:
"""Each worktree beside the checkout whose branch's pull request has merged at the worktree's head: under `merge = "human"` a person merges after the chunk's run has ended, so its worker never ran `chunk-pr clean`. A worktree whose forge can't be asked counts as not left."""
listing, url = git("worktree", "list", "--porcelain"), git("remote", "get-url", "origin")
if isinstance(listing, Failure) or isinstance(url, Failure):
return ()
merged = [(path, branch, merged_pull(forge_of(url), branch, head, forge_run)) for path, branch, head in worktrees(listing) if path != root]
return tuple(LeftWorktree(path, branch, pull) for path, branch, pull in merged if isinstance(pull, str))
def forge_runner(root: pathlib.Path, timeout: float) -> Run:
"""Runs the forge's CLI at root, stopped after timeout seconds: what it printed, or a Failure with why it failed."""
def run(command: list[str]) -> str | Failure:
done = ran(command, root, timeout)
if isinstance(done, Failure):
return Failure(f"`{' '.join(command[:3])}` {done.reason}")
return Failure(f"`{' '.join(command[:3])}` exited {done.code}: {done.stderr.strip()}") if done.code else done.stdout
return run
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):
+39 -1
View File
@@ -12,10 +12,11 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from project_config.templates import BRANCH
from release_plan.next_chunk import CarriedOver, NoItem
from failure import Failure
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, Ran, Worktree
from chunk_preflight.gathered import Gathered, ItemFacts, LeftWorktree, NamedPath, Ran, Worktree
from test_env import isolated_env
from release_plan.release_standing import LastCut, UNSEEN_RELEASES
from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
from release_plan.awaiting_merge import marked
from release_plan import next_chunk
from chunk_preflight.facts import open_pulls, render
from plan_store.todo_md import plan_of
@@ -135,6 +136,34 @@ class Repo:
class ChunkPreflightTool(unittest.TestCase):
def test_passes_over_an_item_whose_pull_request_awaits_a_persons_merge_and_names_a_worktree_a_merged_one_left(self):
repo = Repo(self, origin="github.com/o/r.git")
config = repo.temp / "home" / ".claude-projects" / "proj" / "config.toml"
config.write_text(config.read_text() + 'merge = "human"\n')
repo.git(repo.root, "worktree", "add", "--quiet", "-b", "item-3", str(repo.temp / "proj-item-3"), "main")
repo.write(repo.temp / "proj-item-3", "todo.md", TODO.replace("| 3 | 0.2.0 | | | **Do the next thing.** | 2 | 2 | 3 | 5 | 3 | 1 by 9 | 56.2 |\n", ""))
repo.commit(repo.temp / "proj-item-3", "Finish item 3 in the plan")
ready = repo.git(repo.temp / "proj-item-3", "rev-parse", "HEAD").strip()
repo.git(repo.root, "worktree", "add", "--quiet", "-b", "item-2", str(repo.temp / "proj-item-2"), "main")
left = repo.git(repo.temp / "proj-item-2", "rev-parse", "HEAD").strip()
(repo.fake / "gh").write_text(f"""#!{sys.executable}
import sys
args = sys.argv[1:]
if args[:4] == ["pr", "list", "--limit", "100"]:
print("12\\thttps://github.com/o/r/pull/12\\t{ready}\\tfalse\\tfalse")
elif args[:6] == ["pr", "list", "--head", "item-2", "--state", "merged"]:
print("11\\t{left}\\tfalse")
""")
done = repo.preflight()
self.assertEqual(done.returncode, 0, done.stderr)
self.assertIn(f"- The worktree {repo.temp}/proj-item-2, on the branch item-2, is left from pull request #11, which has merged: run `~/.claude/bin/chunk-pr clean` in it as this chunk's first step.\n", done.stdout)
self.assertNotIn("proj-item-3, on the branch", done.stdout, "an open pull request leaves no worktree to clean")
self.assertIn("No plan item: every item of release 0.2.0 in origin/main's todo.md waits. Under `merge = \"human\"`, a person's merge is awaited of pull request #12 https://github.com/o/r/pull/12, which finishes item 3. The working loop stops here until one is merged.", done.stdout)
(repo.fake / "gh").write_text("#!/bin/sh\necho 'not logged in' >&2\nexit 1\n")
unread = repo.preflight()
self.assertIn("- The pull requests that await a person's merge cannot be read, so no item is passed over for one: `gh pr list` exited 1: not logged in\n", unread.stdout)
self.assertIn("Its first item that does not wait: item 3,", unread.stdout)
def test_reads_a_plan_outside_the_checkout_as_it_stands_and_names_where_the_config_puts_each_file(self):
repo = Repo(self)
folder = repo.temp / "home" / ".claude-projects" / "proj"
@@ -408,6 +437,15 @@ def rendered(item, release=CUT, note=None):
class Render(unittest.TestCase):
def test_states_what_a_persons_merge_leaves_only_where_there_is_something(self):
self.assertNotIn("merge", rendered(item_facts()))
found = gathered(NoItem("the plan holds none."))
left = dataclasses.replace(found, left=(LeftWorktree(pathlib.Path("/c/proj-item-2"), "item-2", "11"),), merges_unread=Failure("`gh pr list` exited 1: no"))
passed = "\n".join(render(gathered(item_facts(marked(plan_of(TODO), {7: "#12 https://github.com/o/r/pull/12"})))))
self.assertIn("\n- Passed over, since each is finished on a branch whose pull request is ready and awaits a person's merge: item 7, by pull request #12 https://github.com/o/r/pull/12. No chunk takes one.\n", passed)
self.assertIn("- No other item of release 0.2.0 may join item 3's chunk.", passed)
self.assertEqual(render(left)[1:3], ["- The worktree /c/proj-item-2, on the branch item-2, is left from pull request #11, which has merged: run `~/.claude/bin/chunk-pr clean` in it as this chunk's first step.", "- The pull requests that await a person's merge cannot be read, so no item is passed over for one: `gh pr list` exited 1: no"])
def test_states_the_earliest_releases_first_item_its_levels_and_detail_and_each_item_that_may_join_its_chunk(self):
said = rendered(item_facts())
self.assertIn("origin/main's todo.md: 0.2.0", said)
+31
View File
@@ -2,10 +2,12 @@
import dataclasses
import fnmatch
import json
import re
import typing
from failure import Failure
from forge.commands import Forge, gitea, Run
from forge.reviews import GITEA_DRAFT
# How long checks_passed waits between two reads: of the head commit's status on Gitea, or of gh's watch while it reports no checks.
POLL_SECONDS = 10
@@ -44,6 +46,35 @@ def pull_at(forge: Forge, branch: str, head: str, state: typing.Literal["open",
return Failure(f"tea api listed pull requests in a shape that can't be read: {str(pulls)[:200]}")
@dataclasses.dataclass(frozen=True)
class ReadyPull:
"""An open pull request from one of origin's own branches that is no draft."""
number: str
url: str
# The commit ID of its head.
head: str
def ready_pulls(forge: Forge, run: Run) -> list[ReadyPull] | Failure:
"""Each open pull request from origin's own branches that is no draft, which Gitea tells by its title (GITEA_DRAFT). A row whose number or head is no number or commit ID is left out, since callers pass them to git."""
if forge == "gh":
# 100 is the most GitHub's API lists a page; gh lists 30 unless told.
listed = run(["gh", "pr", "list", "--limit", "100", "--json", "number,url,headRefOid,isDraft,isCrossRepository", "--template", "{{range .}}{{.number}}\t{{.url}}\t{{.headRefOid}}\t{{.isDraft}}\t{{.isCrossRepository}}\n{{end}}"])
if isinstance(listed, Failure):
return listed
rows = [line.split("\t") for line in listed.splitlines()]
found = [ReadyPull(*row[:3]) for row in rows if row[3:] == ["false", "false"]]
else:
pulls = gitea(run, "repos/{owner}/{repo}/pulls?state=open&limit=50")
if isinstance(pulls, Failure):
return pulls
try:
found = [ReadyPull(str(pull["number"]), pull["html_url"], pull["head"]["sha"]) for pull in pulls if pull["head"]["repo"]["full_name"] == pull["base"]["repo"]["full_name"] and not pull["title"].upper().startswith(GITEA_DRAFT)]
except (AttributeError, KeyError, TypeError):
return Failure(f"tea api listed pull requests in a shape that can't be read: {str(pulls)[:200]}")
return [pull for pull in found if pull.number.isascii() and pull.number.isdigit() and isinstance(pull.head, str) and re.fullmatch(r"[0-9a-f]{40,64}", pull.head)]
def required_checks(forge: Forge, base: str, run: Run) -> set[str] | Failure:
"""The checks, or glob patterns of checks, that the forge's protection of the branch base requires before a merge. None on GitHub, where gh's watch covers them.
+26 -1
View File
@@ -1,4 +1,5 @@
import itertools
import json
import pathlib
import sys
import typing
@@ -6,7 +7,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from forge.pulls import CheckFailed, checks_now, checks_passed, open_pull, Pending, POLL_SECONDS, required_checks, WAIT_SECONDS
from forge.pulls import CheckFailed, checks_now, checks_passed, open_pull, Pending, POLL_SECONDS, ready_pulls, ReadyPull, required_checks, WAIT_SECONDS
from failure import Failure
from forge.commands import forge_of, gitea, url_beside
@@ -138,3 +139,27 @@ class ChecksPassed(unittest.TestCase):
if __name__ == "__main__":
unittest.main()
SHA = "a" * 40
GITEA_PULL = {"number": 7, "html_url": "https://gitea.example/o/r/pulls/7", "title": "Do 7", "head": {"sha": SHA, "repo": {"full_name": "o/r"}}, "base": {"repo": {"full_name": "o/r"}}}
class ReadyPulls(unittest.TestCase):
def test_lists_on_gh_each_open_pull_request_from_origins_own_branches_that_is_no_draft(self):
commands: list[list[str]] = []
listed = f"7\thttps://github.com/o/r/pull/7\t{SHA}\tfalse\tfalse\n8\thttps://github.com/o/r/pull/8\t{SHA}\ttrue\tfalse\n9\thttps://github.com/o/r/pull/9\t{SHA}\tfalse\ttrue\n"
self.assertEqual(ready_pulls("gh", lambda command: commands.append(command) or listed), [ReadyPull("7", "https://github.com/o/r/pull/7", SHA)])
self.assertEqual(commands[0][:5], ["gh", "pr", "list", "--limit", "100"])
def test_leaves_out_on_gh_a_row_whose_head_is_no_commit_id(self):
self.assertEqual(ready_pulls("gh", lambda command: "7\thttps://github.com/o/r/pull/7\t--upload-pack=x\tfalse\tfalse\n"), [])
def test_lists_on_tea_each_open_pull_request_from_origins_own_branches_whose_title_marks_no_draft(self):
fork = {**GITEA_PULL, "number": 8, "head": {"sha": SHA, "repo": {"full_name": "other/r"}}}
draft = {**GITEA_PULL, "number": 9, "title": "wip: Do 9"}
self.assertEqual(ready_pulls("tea", lambda command: json.dumps([GITEA_PULL, fork, draft])), [ReadyPull("7", "https://gitea.example/o/r/pulls/7", SHA)])
def test_fails_where_the_forge_cannot_list_them(self):
self.assertEqual(ready_pulls("gh", lambda command: Failure("gh: no network")).reason, "gh: no network")
self.assertEqual(ready_pulls("tea", lambda command: LONG).reason, f"tea api listed pull requests in a shape that can't be read: {LONG[:200]}")
+2 -2
View File
@@ -145,7 +145,7 @@ class Main(unittest.TestCase):
result = reply(Rung(args[args.index("--model") + 1], args[args.index("--effort") + 1]), "said Verdict: interrupt" in prompt.rsplit("latest last:", 1)[-1])
return subprocess.CompletedProcess(args, 0, json.dumps(result), "")
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, replace_file=unused, sleep=unused, stream_claude=unused, timer=unused, tmux=unused, tmux_on_terminal=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, forge=unused, git=unused, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, replace_file=unused, sleep=unused, stream_claude=unused, timer=unused, tmux=unused, tmux_on_terminal=unused)
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, {}, self.home, effects)
@@ -387,7 +387,7 @@ class JudgeArchivedRuns(unittest.TestCase):
cwds.append(cwd)
return subprocess.CompletedProcess(args, 0, json.dumps({"type": "result", "structured_output": output, "total_cost_usd": 0.25}), "")
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, replace_file=unused, sleep=unused, stream_claude=unused, timer=unused, tmux=unused, tmux_on_terminal=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, forge=unused, git=unused, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, replace_file=unused, sleep=unused, stream_claude=unused, timer=unused, tmux=unused, tmux_on_terminal=unused)
grounds = grounds_of(prompt, self.ENTRIES)
return (grounds if isinstance(grounds, Failure) else judge_archived("/code/p", prompt, grounds, len(self.ENTRIES), REFERENCE, LOOP_CLAUDE, effects)), cwds
+1 -1
View File
@@ -49,7 +49,7 @@ def fetched_plan(loop: Loop, announce: bool = True) -> DefaultPlan | Failure:
if announce and config.tracked("plan") is None:
say(UNSEEN_RELEASES, loop.effects)
ref = default_ref(loop.root, ORIGIN_TIMEOUT, run=loop.effects.git)
return ref if isinstance(ref, Failure) else project_plan(config, ref, loop.root, loop.effects.git)
return ref if isinstance(ref, Failure) else project_plan(config, ref, loop.root, loop.effects.git, loop.effects.forge(loop.root))
def plan_item(plan: DefaultPlan | Failure, window_item: int | None, effects: Effects) -> Item | None:
+1 -1
View File
@@ -104,7 +104,7 @@ def next_plan(root: str, home: pathlib.Path, effects: Effects) -> NextChunk | No
ref = default_ref(root, FETCH_TIMEOUT, run=effects.git)
if isinstance(ref, Failure):
return ref
held = project_plan(config, ref, root, effects.git)
held = project_plan(config, ref, root, effects.git, effects.forge(root))
return planned(held.plan, held.cut, ref, config.branch, None if config.tracked("plan") else config.plan_label)
+19
View File
@@ -79,6 +79,25 @@ class RouteSources(unittest.TestCase):
held = chunk_start.fetched_plan(a_loop(effects, root=root, paths=paths.paths_from(folder.parents[1])))
self.assertEqual(held.cut.changelog, "what origin/main:CHANGELOG.md holds\n")
def test_passes_over_an_item_whose_pull_request_awaits_a_persons_merge_as_the_loops_forge_lists_them(self):
head = "a" * 40
finished = TODO.replace("| 3 | 0.2.0 | | **Do the next thing.** | 4 | 2 | 3 | 7 | 3 | 1 by 9 | 25 |\n", "")
def git(*args, **options):
if args[:2] == ("remote", "get-url"):
return "https://github.com/o/r\n"
answers = {"remote": "origin\n", "symbolic-ref": "origin/main\n", "merge-base": "base\n", "show": finished if args[-1] == f"{head}:todo.md" else TODO}
return answers.get(args[0], "1\n")
with tempfile.TemporaryDirectory() as root:
folder = configured(self, pathlib.Path(root))
(folder / "config.toml").write_text((folder / "config.toml").read_text() + 'merge = "human"\n')
fake = FakeEffects(forge=[f"12\thttps://github.com/o/r/pull/12\t{head}\tfalse\tfalse\n"])
held = chunk_start.fetched_plan(a_loop(dataclasses.replace(fake.effects(), git=git), root=root, paths=paths.paths_from(folder.parents[1])))
self.assertEqual([(item.id, item.awaits_merge) for item in held.plan.items], [(7, ""), (3, "#12 https://github.com/o/r/pull/12"), (1, "")])
self.assertEqual(fake.made("forge")[0][:3], ["gh", "pr", "list"])
self.assertIsNone(chunk_start.plan_item(held, None, fake.effects()), "items 7 and 3 wait, so no item of the next release routes the chunk")
def test_reads_a_plan_outside_the_checkout_as_it_stands_and_stops_without_a_config(self):
with tempfile.TemporaryDirectory() as root:
folder = configured(self, pathlib.Path(root))
+3 -2
View File
@@ -29,7 +29,7 @@ def human(content: typing.Any) -> dict[str, typing.Any]:
class FakeEffects:
"""Effects that record each call and answer from a script, one answer per call."""
def __init__(self, claude: typing.Iterable[typing.Any] = (), on_terminal_claude: typing.Iterable[typing.Any] = (), git: typing.Iterable[typing.Any] = (), inputs: typing.Iterable[typing.Any] = (), python: typing.Iterable[typing.Any] = (), streams: typing.Iterable[typing.Any] = (), on_terminal: bool = True, free_memory: typing.Iterable[memory.Memory | None] = (), dm_failures: typing.Iterable[Failure | None] = (), tmux_version: str = "tmux 3.2", windows: str | None = None, owner: str = "/r") -> None:
def __init__(self, claude: typing.Iterable[typing.Any] = (), on_terminal_claude: typing.Iterable[typing.Any] = (), git: typing.Iterable[typing.Any] = (), forge: typing.Iterable[typing.Any] = (), inputs: typing.Iterable[typing.Any] = (), python: typing.Iterable[typing.Any] = (), streams: typing.Iterable[typing.Any] = (), on_terminal: bool = True, free_memory: typing.Iterable[memory.Memory | None] = (), dm_failures: typing.Iterable[Failure | None] = (), tmux_version: str = "tmux 3.2", windows: str | None = None, owner: str = "/r") -> None:
self.calls: list[tuple[str, typing.Any]] = []
# Each tmux command run. They stay out of self.calls, as the DMs do. tmux prints `windows` for list-windows, or without them finds no session.
self.tmux_calls: list[list[str]] = []
@@ -42,7 +42,7 @@ class FakeEffects:
# The directory each DM named, in the order of self.dms; None where it named none.
self.dm_directories: list[str | None] = []
self.dm_failures = list(dm_failures)
self.scripts: dict[str, list[typing.Any]] = {"claude": list(claude), "claude_on_terminal": list(on_terminal_claude), "git": list(git), "input": list(inputs), "python": list(python), "stream_claude": list(streams)}
self.scripts: dict[str, list[typing.Any]] = {"claude": list(claude), "claude_on_terminal": list(on_terminal_claude), "forge": list(forge), "git": list(git), "input": list(inputs), "python": list(python), "stream_claude": list(streams)}
# Without a script, every read finds all memory available.
self.free_memory = list(free_memory)
self.terminal = on_terminal
@@ -62,6 +62,7 @@ class FakeEffects:
discard_typed=lambda: self.calls.append(("discard_typed", None)),
dm=self.dm,
execv=self.execv,
forge=lambda cwd: lambda command: self.answer("forge", command),
git=lambda *args, cwd=None, timeout=None, guarded=False, errors="strict": self.answer("git", list(args)),
input=lambda prompt: self.answer("input", prompt),
local_time=lambda seconds: f"<{seconds}>",
+4
View File
@@ -21,6 +21,7 @@ from git_cli import git_repo
from machine_load.memory import Memory, read_memory
from project_config.settings import Notifier
from text_files.file_writes import replace_file
from forge.commands import Run, runner
from machine_load.slots import slot_folder
# Seconds before a Python script loop-claude runs is stopped, so a hung one, such as chunk-preflight, cannot hold the loop.
@@ -54,6 +55,8 @@ class Effects:
# Sends the human a direct message through the notifier the project's config names, as `notify` does, for the project whose checkout holds the given directory, else the current directory; a Failure where it could not.
dm: typing.Callable[[str, str | None], Failure | None]
execv: typing.Callable[[str, list[str]], None]
# Runs the CLI of a checkout's forge in that checkout, as forge.commands.runner does.
forge: typing.Callable[[str], Run]
git: git_repo.Git
input: typing.Callable[[str], str]
# A date and time in the machine's zone, as `2026-10-28 11:46:01`. lilleman chose this spelling and local time over UTC on 2026-10-28, since the human reads these on their own clock.
@@ -120,6 +123,7 @@ def system_effects(home: pathlib.Path, env: typing.Mapping[str, str], backends:
discard_typed=lambda: termios.tcflush(sys.stdin, termios.TCIFLUSH),
dm=lambda text, directory: notify(text, directory, home, backends),
execv=os.execv,
forge=runner,
git=git_repo.git,
input=input,
local_time=lambda seconds: time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(seconds)),
+4 -2
View File
@@ -107,6 +107,8 @@ class Item:
blocked_by: tuple[int, ...]
# Empty where the item has none, and where a reader took only the table.
detail: str = ""
# The pull request, as `#<number> <URL>`, whose merge by a person the item awaits, finished on that branch only; empty where it awaits none, and where the reader asked no forge. release_plan.awaiting_merge sets it.
awaits_merge: str = ""
@property
def likelihood(self) -> int:
@@ -181,9 +183,9 @@ def items_table(lines: list[str]) -> Table | None | Failure:
def waiting(found: list[Item], done: set[int]) -> set[int]:
"""The IDs of the items that wait: each marked question, or blocked by an item the table still holds and done does not name. Row order does not change the result."""
"""The IDs of the items that wait: each marked question, each that awaits a person's merge of its pull request, and each blocked by an item the table still holds and done does not name. Row order does not change the result."""
held = {item.id for item in found} - done
return {item.id for item in found if item.exempt == "question" or held.intersection(item.blocked_by)}
return {item.id for item in found if item.exempt == "question" or item.awaits_merge or held.intersection(item.blocked_by)}
def next_item(found: list[Item]) -> Item | None:
+30
View File
@@ -0,0 +1,30 @@
"""The plan items whose chunk left its pull request ready for a person's merge, under `merge = "human"`. The chunk finished them on its branch only, so the default branch's plan holds each until that merge, and no chunk may start from one."""
import dataclasses
from failure import Failure
from forge.commands import Forge, Run
from forge.pulls import ready_pulls
from git_cli.git_repo import Git, git
from plan_store import stores
from plan_store.plans import Plan, PlanStore
def awaiting(ref: str, plan: PlanStore, root: str, forge: Forge, forge_run: Run, run: Git = git) -> dict[int, str] | Failure:
"""Each plan item, by ID, that awaits a person's merge, with its pull request as `#<number> <URL>`: an item the plan held where the pull request's branch left ref, the default branch, and no longer holds at its head. A pull request whose head the checkout hasn't fetched, or whose plan can't be read, names none."""
pulls = ready_pulls(forge, forge_run)
if isinstance(pulls, Failure):
return pulls
found: dict[int, str] = {}
for pull in pulls:
base = run("merge-base", ref, pull.head, cwd=root)
if isinstance(base, Failure):
continue
before, after = stores.held_at(base.strip(), plan, root, run), stores.held_at(pull.head, plan, root, run)
if isinstance(before, Plan) and isinstance(after, Plan):
found.update(dict.fromkeys({item.id for item in before.items} - {item.id for item in after.items}, f"#{pull.number} {pull.url}"))
return found
def marked(plan: Plan, awaited: dict[int, str]) -> Plan:
"""plan with each item awaited names marked as awaiting its pull request's merge, so it waits."""
return dataclasses.replace(plan, items=[dataclasses.replace(item, awaits_merge=awaited.get(item.id, "")) for item in plan.items])
+14 -1
View File
@@ -4,6 +4,7 @@ import dataclasses
from release_plan.release_standing import Cut, dated_cut, LastCut, picked, ReadyToCut, ReviewDue, standing_of, Unknown, Unplanned
from failure import Failure
from plan.todo_table import Item, NoItemsTable
from text_files.markdown_text import listed
from plan_store.plans import Plan
from plan.release import Release, version
from project_config import templates
@@ -81,7 +82,7 @@ def planned(read: Plan | Failure, cut: LastCut, default: str, branch: str, outsi
return NoItem(f"{where} holds no item for {upcoming}, and no change is unreleased, so that release is to be planned first.")
first = pick.item
if first is None:
return NoItem(f"every item of release {version(pick.release)} in {where} waits." if pick.release is not None else f"{where}'s items table holds no item.")
return NoItem(f"every item of release {version(pick.release)} in {where} waits.{awaited_merges(weighed.carried, pick.release)}" if pick.release is not None else f"{where}'s items table holds no item.")
held = weighed.carried
# Every carried item takes one release, the next.
over = CarriedOver(next(item.release for item in held if item.id == weighed.moved[0]), weighed.moved) if weighed.moved else None
@@ -90,3 +91,15 @@ def planned(read: Plan | Failure, cut: LastCut, default: str, branch: str, outsi
if first is None:
return NoItem(f"{where} holds no item {item_id}, the one --item names; it may have shipped.")
return NextChunk(held, first, f"{first.tagline}\n\n{first.detail}".strip(), branch, over, item_id is not None)
def awaited_merges(found: list[Item], release: Release) -> str:
"""The sentences that stop the working loop where items of release await a person's merge, naming each pull request with the items it finishes; empty where none does."""
pulls: dict[str, list[str]] = {}
for item in found:
if item.release == release and item.awaits_merge:
pulls.setdefault(item.awaits_merge, []).append(str(item.id))
if not pulls:
return ""
named = listed([f"{pull}, which finishes item{'s' if len(ids) > 1 else ''} {listed(ids, 'and')}" for pull, ids in pulls.items()], "and")
return f" Under `merge = \"human\"`, a person's merge is awaited of pull request {named}. The working loop stops here until one is merged."
+16 -3
View File
@@ -1,9 +1,11 @@
"""How the plan stands to the last release cut: the next release, whether work has landed towards it, and whether it is to be planned, reviewed or cut; and, from that standing, the item the next chunk takes first, with what the default branch holds for the pick."""
import dataclasses
from release_plan.awaiting_merge import awaiting, marked
from git_cli.git_repo import commits_since, file_at, git, Git
from plan.release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged, UNRELEASED_TITLE
from failure import Failure
from forge.commands import forge_of, Run
from plan.todo_table import Item, items, next_item, renames
from plan_store.plans import Plan
from plan_store import stores as plan_stores, plans
@@ -95,11 +97,22 @@ class DefaultPlan:
# The plan, a NoItemsTable where the branch holds none.
plan: Plan | Failure
cut: LastCut
# Why the pull requests that await a person's merge could not be read, so the plan passes over none of their items; None where they were read or not asked for.
merges_unread: Failure | None = None
def project_plan(config: ProjectConfig, ref: str, root: str, run: Git = git) -> DefaultPlan:
"""default_plan for the project config describes: its plan, its changelog and its title templates."""
return default_plan(root, ref, plan_stores.store(config), stores.store(config, "changelog"), config.titles, run)
def project_plan(config: ProjectConfig, ref: str, root: str, run: Git = git, forge_run: Run | None = None) -> DefaultPlan:
"""default_plan for the project config describes: its plan, its changelog and its title templates. With forge_run, which runs the forge's CLI in the checkout, and under `merge = "human"`, the plan's items that await a person's merge are marked so, as awaiting_merge says, and so wait."""
plan = plan_stores.store(config)
held = default_plan(root, ref, plan, stores.store(config, "changelog"), config.titles, run)
# A plan no commit holds is finished at once (chunk-pr merge --finish), so none of its items awaits a merge.
if forge_run is None or config.merge != "human" or plan.tracked is None or not isinstance(held.plan, Plan):
return held
origin = run("remote", "get-url", "origin", cwd=root)
awaited = origin if isinstance(origin, Failure) else awaiting(ref, plan, root, forge_of(origin), forge_run, run)
if isinstance(awaited, Failure):
return dataclasses.replace(held, merges_unread=awaited)
return dataclasses.replace(held, plan=marked(held.plan, awaited))
def default_plan(root: str, ref: str, plan: plans.PlanStore, changelog: stores.RecordStore, titles: templates.Titles, run: Git = git) -> DefaultPlan:
+57
View File
@@ -7,6 +7,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from release_plan import awaiting_merge
from project_config.templates import BARE, Titles
from project_config.settings import DEFAULT_FLOOR, ProjectConfig, SETTINGS
from failure import Failure
@@ -393,3 +394,59 @@ class NextChunk(unittest.TestCase):
planned = next_chunk.planned(Plan([later, carried, next_one]), release_standing.LastCut("v0.2.0", "", 4, []), "origin/main", "item-{id}")
assert isinstance(planned, next_chunk.NextChunk), planned
self.assertEqual(planned.carried, next_chunk.CarriedOver((0, 3, 0), (5,)))
class AwaitingMerge(unittest.TestCase):
"""A repo whose branch item-1 finished item 1 of three, and whose default branch has since filed item 4."""
def setUp(self):
self.repo = tempfile.mkdtemp()
self.addCleanup(subprocess.run, ["rm", "-rf", self.repo])
run = lambda *args: subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@t", *args], capture_output=True, check=True, cwd=self.repo, env=isolated_env(), text=True).stdout.strip()
rows = lambda *ids: HEADER + "".join(ROW.format(id=id_, release="0.1.0") for id_ in ids)
run("init", "-q", "-b", "main")
run("remote", "add", "origin", "https://github.com/o/r")
pathlib.Path(self.repo, "todo.md").write_text(rows(1, 2, 3))
run("add", "todo.md")
run("commit", "-q", "-m", "Plan")
run("checkout", "-q", "-b", "item-1")
pathlib.Path(self.repo, "todo.md").write_text(rows(2, 3))
run("commit", "-q", "-a", "-m", "Finish item 1 in the plan")
self.head = run("rev-parse", "HEAD")
run("checkout", "-q", "main")
pathlib.Path(self.repo, "todo.md").write_text(rows(1, 2, 3, 4))
run("commit", "-q", "-a", "-m", "File item 4")
self.listed = f"7\thttps://github.com/o/r/pull/7\t{self.head}\tfalse\tfalse\n"
paths = {setting: pathlib.Path(self.repo, setting) for setting in SETTINGS} | {"plan": pathlib.Path(self.repo, "todo.md"), "changelog": pathlib.Path(self.repo, "CHANGELOG.md")}
self.config = ProjectConfig("acme", pathlib.Path(self.repo, "folder"), pathlib.Path(self.repo), paths, merge="human")
def test_names_the_items_a_ready_pull_request_finished_on_its_branch(self):
self.assertEqual(awaiting_merge.awaiting("main", plan_in(self.repo), self.repo, "gh", lambda command: self.listed), {1: "#7 https://github.com/o/r/pull/7"}, "item 4, filed after the branch left main, is not finished on it")
def test_names_none_for_a_pull_request_whose_head_the_checkout_lacks_and_fails_where_the_forge_does(self):
unfetched = f"7\thttps://github.com/o/r/pull/7\t{'b' * 40}\tfalse\tfalse\n"
self.assertEqual(awaiting_merge.awaiting("main", plan_in(self.repo), self.repo, "gh", lambda command: unfetched), {})
self.assertEqual(awaiting_merge.awaiting("main", plan_in(self.repo), self.repo, "gh", lambda command: Failure("gh: no network")).reason, "gh: no network")
def test_the_projects_plan_passes_over_an_item_that_awaits_a_persons_merge(self):
held = release_standing.project_plan(self.config, "main", self.repo, forge_run=lambda command: self.listed)
self.assertEqual([(item.id, item.awaits_merge) for item in held.plan.items], [(1, "#7 https://github.com/o/r/pull/7"), (2, ""), (3, ""), (4, "")])
self.assertIsNone(held.merges_unread)
self.assertEqual(release_standing.chunk_item(held.plan.items, held.cut).item.id, 2)
self.assertEqual([item.id for item in todo_table.bundle_candidates(held.plan.items, held.plan.items[1])], [3, 4])
def test_the_projects_plan_asks_no_forge_where_the_chunk_merges_or_no_forge_is_given(self):
asked: list[list[str]] = []
chunk = release_standing.project_plan(dataclasses.replace(self.config, merge="chunk"), "main", self.repo, forge_run=lambda command: asked.append(command) or self.listed)
self.assertEqual((asked, [item.awaits_merge for item in chunk.plan.items]), ([], [""] * 4))
self.assertEqual([item.awaits_merge for item in release_standing.project_plan(self.config, "main", self.repo).plan.items], [""] * 4)
def test_the_projects_plan_says_why_where_the_forge_cannot_list_the_pull_requests(self):
held = release_standing.project_plan(self.config, "main", self.repo, forge_run=lambda command: Failure("gh: no network"))
self.assertEqual(([item.awaits_merge for item in held.plan.items], held.merges_unread.reason), ([""] * 4, "gh: no network"))
def test_says_which_pull_requests_await_a_merge_where_every_item_left_waits(self):
held = release_standing.project_plan(self.config, "main", self.repo, forge_run=lambda command: self.listed)
items = [dataclasses.replace(item, awaits_merge="#8 https://github.com/o/r/pull/8" if item.id != 1 else item.awaits_merge) for item in held.plan.items]
none = next_chunk.planned(Plan(items), held.cut, "main", "item-{id}")
self.assertEqual(none.why, "every item of release 0.1.0 in main's todo.md waits. Under `merge = \"human\"`, a person's merge is awaited of pull request #7 https://github.com/o/r/pull/7, which finishes item 1 and #8 https://github.com/o/r/pull/8, which finishes items 2, 3 and 4. The working loop stops here until one is merged.")
+1 -1
View File
@@ -269,7 +269,7 @@ class Main(unittest.TestCase):
result = result if "api_error_status" in result else {"type": "result", "structured_output": {"found": [n + 1 for n in result["found"]]}}
return subprocess.CompletedProcess(args, 0, json.dumps(result), "")
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=system_effects(pathlib.Path.home(), os.environ).git, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, replace_file=unused, sleep=unused, stream_claude=unused, timer=unused, tmux=unused, tmux_on_terminal=unused)
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, forge=unused, git=system_effects(pathlib.Path.home(), os.environ).git, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, replace_file=unused, sleep=unused, stream_claude=unused, timer=unused, tmux=unused, tmux_on_terminal=unused)
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, env, self.home, effects, **self.limits)
+1
View File
@@ -12,3 +12,4 @@ Everything written — chat, commit messages, comments, docs, code — is in **E
- **Write the thing, not an introduction to it.** A sentence announcing what follows, or flagging that it deserves attention, doesn't carry anything — if it matters, it is in what follows. A bare label is fine. BANNED: `Here's the new audience text, which is the part that needs your eye:`, `One thing I changed that deserves your attention.`, `One judgment call I'd flag rather than bury.`, `Three things came along that would otherwise have been left false.` GOOD: `New audience text:`, or the list alone.
- **Write negations as people say them.** After a verb, or after its preposition, write `doesn't <verb> anything` or `anyone`, never `<verb> nothing` or `no one`; each breach is a 🟡. BANNED: `stops nothing`, `depends on no one`, `so answering in time costs nothing`. GOOD: `doesn't stop anything`, `doesn't depend on anyone`, `so answering in time doesn't cost anything`.
- **No contrastive tail.** `X rather than Y`, `not Y but X`, `instead of Y`: state X and stop. The rejected alternative is noise unless naming it stops a reader choosing Y. BANNED: `verified in CI rather than asserted`. GOOD: `verified in CI`.
- **A sentence about several named things holds for each.** Where a sentence gives one property to several named tables, fields or flags, check the property in each one's source. Where it fails for one, split the sentence. BANNED, where only `users` has the column: `Each row of users and groups has a name`. GOOD: `Each row of users has a name. A row of groups has only an id`.