Merge origin/main into item-414
CI / tests (pull_request) Successful in 5m11s

This commit is contained in:
2026-11-19 03:31:12 +01:00
22 changed files with 536 additions and 118 deletions
+3
View File
@@ -2,6 +2,9 @@
## Unreleased
- do-epic tells an epic chunk's worker how its repo ships the change: a bullet under the repo's changelog where the repo publishes something, none where its plan is in Jira, and no `--finish` for `chunk-pr merge`.
- `do-epic <EPIC-KEY> --status` says which chunk asks you a question, and since when each parked chunk has awaited its gate.
- do-epic moves a chunk's issue to done in Jira when the chunk finishes, and the split item it belongs to once its last sub-task is done, so no finished chunk starts again and the chunks it blocks start. It moves them by the transition `jira-finish-transition` and `jira-finish-status` name, so set both; without them a finishing chunk stops with that reason.
- Describe do-epic in the README: its entry under Tools, and its machine settings and `repo-rule.md` under Set up a project.
- do-epic finishes an epic: once none of its issues is open, a finishing chunk files a release review of each repo the epic changed, as an issue labelled `do-epic-release-review`, and asks you to confirm each goal. `do-epic <EPIC-KEY> --close-epic` then posts the summary piped in as a comment on the epic and closes it in Jira, by the transition `jira-finish-transition` names, to the status `jira-finish-status` names.
- do-epic parks a chunk whose pull request waits on its checks, an approval or a new review: the chunk frees its place for the next one, its tmux window says what it awaits, and its worker goes on when the gate opens or a reviewer comments, even after a reboot. `do-epic <EPIC-KEY> --status` prints what each open issue does.
+2 -2
View File
@@ -152,7 +152,7 @@ The last line prints each setting's path once the config is complete.
`do-epic` keeps its settings per machine, not per project, in `~/.claude-projects/do-epic/`, two files for every epic:
- `config.toml` sets `jira-url`, the site, such as `https://acme.atlassian.net`; `env-file`, the file holding `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, a path that starts with `/` or `~/`, outside the clone folder and every folder of `~/.claude-projects`; and `repoless-model`, the model that works an item with no repo. It may also set `clone-folder`, where a missing repo is cloned, `~/code` if left out; `language`, the language of Jira text, English if left out; and `jira-finish-transition` with `jira-finish-status`, which name the workflow transition that closes a finished epic and the status it leads to, such as `"Mark as done"` and `"Done"`. Set both or neither: without them do-epic closes no epic.
- `config.toml` sets `jira-url`, the site, such as `https://acme.atlassian.net`; `env-file`, the file holding `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, a path that starts with `/` or `~/`, outside the clone folder and every folder of `~/.claude-projects`; and `repoless-model`, the model that works an item with no repo. It may also set `clone-folder`, where a missing repo is cloned, `~/code` if left out; `language`, the language of Jira text, English if left out; and `jira-finish-transition` with `jira-finish-status`, which name the workflow transition that moves a finished chunk's issue, and closes a finished epic, and the status it leads to, such as `"Mark as done"` and `"Done"`. Set both or neither: without them do-epic moves no issue to done and closes no epic, and a chunk that finishes stops with that reason.
- `repo-rule.md` is prose that says how to tell an item's repo, such as "a label that equals a repo's name names that repo". It may not be blank. do-epic doesn't read it yet: until it picks each item's repo from the rule, an issue runs once a label `repo:<name>` records its repo, `do-epic-claude` marks work of Claude's that changes no repo, and `do-epic-human` a task of yours.
Each repo an epic changes has a project config of its own, as in the rest of this section. `do-epic` fails and names each setting or file that is missing or invalid.
@@ -224,7 +224,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
- `deploy_release` imports `release_plan`'s `release_standing`.
- `do_epic/` holds `do-epic`, the tool that drives one Jira epic. `main.py` starts the epic's chunks and runs one chunk's cycles in its window, through `agent_cycle`. `scheduler.py` says which issues run now: as many as the epic's cap and each repo's `parallel-chunks` allow, and none in a repo where loop-claude runs chunks. `gates.py` reads once whether a chunk's pull request waits on its checks, an approval or a new review, and `parked.py` keeps each chunk that does in a state file, so it takes no running slot while it waits and goes on waiting after a reboot. `chunk_prompt.py` words what a chunk's worker reads. Through `findings.py` that worker files a finding as an issue of the epic, with `--file`, and appends a decision to its description, with `--record-decision`. `finish.py` ends an epic that holds no open issue: its finishing chunk files a release review of each repo the epic changed, has the human confirm each goal, and with `--close-epic` posts the summary on the epic and closes it. `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section, language line and cap line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `split.py` has claude predict from the code which repos an item changes, and files a sub-task per repo under it where there are several. `ranking.py` orders an epic's items by score over one chain of goals, the epic's, then code health, then the item's repo's, through `plan`'s ranking, and re-ranks the tracker's backlog to that order through `backend/`. `backend/` reads, files and ranks the epic's issues, adds the labels `repo_pick.py` and `split.py` record, posts comments, and closes the epic.
- `do_epic/` holds `do-epic`, the tool that drives one Jira epic. `main.py` starts the epic's chunks and runs one chunk's cycles in its window, through `agent_cycle`. `scheduler.py` says which issues run now: as many as the epic's cap and each repo's `parallel-chunks` allow, and none in a repo where loop-claude runs chunks. `gates.py` reads once whether a chunk's pull request waits on its checks, an approval or a new review, and `parked.py` keeps each chunk that does in a state file, so it takes no running slot while it waits and goes on waiting after a reboot. `chunk_prompt.py` words what a chunk's worker reads. Through `findings.py` that worker files a finding as an issue of the epic, with `--file`, and appends a decision to its description, with `--record-decision`. `finish.py` ends an epic that holds no open issue: its finishing chunk files a release review of each repo the epic changed, has the human confirm each goal, and with `--close-epic` posts the summary on the epic and closes it. `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section, language line and cap line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `split.py` has claude predict from the code which repos an item changes, and files a sub-task per repo under it where there are several. `ranking.py` orders an epic's items by score over one chain of goals, the epic's, then code health, then the item's repo's, through `plan`'s ranking, and re-ranks the tracker's backlog to that order through `backend/`. `backend/` reads, files and ranks the epic's issues, adds the labels `repo_pick.py` and `split.py` record, posts comments, moves a finished chunk's issue to done, and closes the epic.
- `forge/` tells a GitHub origin from a Gitea one, names a repo beside an origin's and runs that forge's CLI (`commands.py`), and finds a pull request and reads its checks, once or until they settle (`pulls.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release`, `do_epic` and `larv_review`.
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
- `judge_replay` imports `agent_cycle`'s judge and verdicts, and `loop_claude`'s premises, records and `ANSWER_DESTINATIONS`.
+3 -1
View File
@@ -51,6 +51,8 @@ class Listed:
dead: bool
# What its name says its parked chunk awaits, as the words after PARKED; empty for a chunk that isn't parked.
awaits: str = ""
# Whether its name ended in WAITS: its loop asks the human something.
asks: bool = False
@property
def parked(self) -> bool:
@@ -90,7 +92,7 @@ def listed(session: str, run: Tmux) -> list[Listed]:
def as_listed(shown: str, id: str, pane_dead: str) -> Listed:
"""The window tmux shows under the name shown, with the ID id and `#{pane_dead}` as pane_dead."""
name, _, awaits = shown.removesuffix(WAITS).partition(PARKED)
return Listed(name, id, pane_dead == "1", awaits)
return Listed(name, id, pane_dead == "1", awaits, shown.endswith(WAITS))
def everywhere(run: Tmux) -> list[Placed]:
+24
View File
@@ -9,6 +9,7 @@ from failure import Failure
class EpicStoreContract:
assertEqual: typing.Callable[..., None]
assertIsInstance: typing.Callable[..., None]
assertIsNone: typing.Callable[..., None]
subTest: typing.Callable[..., typing.ContextManager[None]]
def new_store(self) -> EpicStore:
@@ -124,6 +125,29 @@ class EpicStoreContract:
self.assertIsInstance(store.add_label("ZZZ-1", "repo:log"), Failure)
self.assertEqual([issue.labels for issue in self.issues(store)], [(), ()])
def test_finishes_a_child_issue_so_it_reads_as_done_and_leaves_one_that_is_done_as_it_is(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
other = self.filed(store, store.epic_key, "Ship the later thing.")
closed = self.filed(store, store.epic_key, "Close the old thing.")
self.close(store, closed, "Done")
self.assertEqual([store.finish_issue(key), store.finish_issue(closed)], [None, None])
self.assertEqual({issue.key: issue.done for issue in self.issues(store)}, {key: True, other: False, closed: True})
def test_finishes_a_sub_task_of_a_child_issue_and_leaves_its_parent_open(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
task = self.filed(store, child, "Count them in the api.")
self.assertIsNone(store.finish_issue(task))
self.assertEqual({issue.key: issue.done for issue in self.issues(store)}, {child: False, task: True})
def test_refuses_to_finish_an_issue_outside_the_epic(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
self.assertIsInstance(store.finish_issue("ZZZ-1"), Failure)
self.assertIsInstance(store.finish_issue("not a key"), Failure)
self.assertEqual([issue.done for issue in self.issues(store)], [False])
def test_posts_comments_on_a_child_issue_in_order(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
+12 -1
View File
@@ -7,7 +7,7 @@ from failure import Failure
@dataclasses.dataclass
class MemoryEpic:
"""An epic whose issues rank in the order filed, until one is ranked. Where fails is set, every read, filing, label, comment, rank and closing fails with it as the reason. comments holds each issue's comments, and the epic's, by key. done says whether the epic is closed."""
"""An epic whose issues rank in the order filed, until one is ranked. Where fails is set, every read, filing, label, comment, rank, issue finish and closing fails with it as the reason. comments holds each issue's comments, and the epic's, by key. done says whether the epic is closed."""
epic_key: str
issues: list[EpicIssue] = dataclasses.field(default_factory=list)
comments: dict[str, list[str]] = dataclasses.field(default_factory=dict)
@@ -73,6 +73,17 @@ class MemoryEpic:
self.done = True
return None
def finish_issue(self, key: str) -> None | Failure:
if self.fails:
return Failure(self.fails)
children = {issue.key for issue in self.issues if issue.parent == self.epic_key}
child = next((issue for issue in self.issues if issue.key == key and (issue.parent == self.epic_key or issue.parent in children)), None)
if child is None:
return no_child(self.epic_key, key, "finished")
if not child.done:
self.change(key, status="Done", done=True)
return None
def change(self, key: str, **fields: object) -> None:
"""Changes the issue named key as a person would in the tracker, such as assignee="Ada Lovelace"."""
self.issues = [dataclasses.replace(issue, **fields) if issue.key == key else issue for issue in self.issues] # type: ignore[arg-type]
+37 -5
View File
@@ -5,7 +5,7 @@ import typing
from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused
from atlassian.client import basic_auth, Http, jira_json, ToAdf, ToMarkdown
from plan_store.jira_epic import blocked_by_links, FILED_BY, finishing_transition, ISSUE_KEY, ISSUE_TYPE, move_refusal, project_of, PROPERTY, rank_refusal, scores, searched
from plan_store.jira_epic import blocked_by_links, DONE, FILED_BY, finishing_transition, ISSUE_KEY, ISSUE_TYPE, move_refusal, PERHAPS_MOVED, project_of, PROPERTY, rank_refusal, scores, searched
from project_config.settings import Epic, Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION
from do_epic.backend.protocol import EpicIssue, no_child, no_parent, no_words, unfit, unfit_label
from failure import Failure
@@ -13,6 +13,7 @@ from failure import Failure
FIELDS = ["summary", "description", "labels", "assignee", "status", "parent", "issuelinks"]
# How many child issues one search for sub-tasks names, which keeps its JQL well inside the length Jira takes.
PARENTS_PER_SEARCH = 50
NO_FINISH = "do-epic's settings name no transition to {to} by: set `{transition}` and `{status}` in ~/.claude-projects/do-epic/config.toml, to the names Jira shows, such as \"Mark as done\" and \"Done\""
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under {parent} before filing it again"
@@ -132,7 +133,7 @@ class JiraEpic:
def close(self, summary: str) -> None | Failure:
if self.finish is None:
return Failure(f"do-epic's settings name no transition to close an epic by: set `{JIRA_FINISH_TRANSITION}` and `{JIRA_FINISH_STATUS}` in ~/.claude-projects/do-epic/config.toml, to the names Jira shows, such as \"Mark as done\" and \"Done\"")
return Failure(NO_FINISH.format(to="close an epic", transition=JIRA_FINISH_TRANSITION, status=JIRA_FINISH_STATUS))
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
@@ -151,6 +152,30 @@ class JiraEpic:
refused_move = move_refusal(self.epic.site, self.epic_key, transition, self.finish, authorization, self.http)
return Failure(f"posted the summary on {self.epic_key}, but {refused_move}; close the epic in Jira rather than posting the summary again") if refused_move else None
def finish_issue(self, key: str) -> None | Failure:
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
placed = self.placed(key, authorization, "to finish it")
if isinstance(placed, Failure):
return placed
above, done = placed
# A sub-task is no child of the epic but its parent is, so a sub-task's parent is read too.
grand = self.parent_of(above, authorization, "to finish its sub-task") if above not in (None, self.epic_key) else None
if isinstance(grand, Failure):
return grand
if above is None or (above != self.epic_key and grand != self.epic_key):
return no_child(self.epic_key, key, "finished")
if done:
return None
if self.finish is None:
return Failure(NO_FINISH.format(to="finish an issue", transition=JIRA_FINISH_TRANSITION, status=JIRA_FINISH_STATUS))
transition = finishing_transition(self.epic.site, key, self.finish, authorization, self.http)
if isinstance(transition, Failure):
return transition
refused = move_refusal(self.epic.site, key, transition, self.finish, authorization, self.http)
return Failure(f"{refused}; {PERHAPS_MOVED.format(key=key)}") if refused else None
def not_a_parent(self, parent: str, authorization: str) -> Failure | None:
"""Why nothing can be filed under parent; None where it is the epic or one of its child issues."""
if parent == self.epic_key:
@@ -160,15 +185,22 @@ class JiraEpic:
def parent_of(self, key: str, authorization: str, why: str) -> str | None | Failure:
"""The key of key's parent issue; None where key isn't an issue key or has no parent. A failed read says "cannot read <key> <why>"."""
placed = self.placed(key, authorization, why)
return placed if isinstance(placed, Failure) else placed[0]
def placed(self, key: str, authorization: str, why: str) -> tuple[str | None, bool] | Failure:
"""The key of key's parent issue, None where key isn't an issue key or has no parent, and whether key's own status is a done one. A failed read says "cannot read <key> <why>"."""
if not ISSUE_KEY.fullmatch(key):
return None
return None, False
# A search may not show an issue filed a moment ago, so the issue is asked for by its key.
answered = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{key}?fields=parent", authorization, None)
answered = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{key}?fields=parent,status", authorization, None)
if isinstance(answered, Failure):
return Failure(f"cannot read {key} {why}: {answered.reason}")
fields = answered.get("fields") if isinstance(answered, dict) else None
above = fields.get("parent") if isinstance(fields, dict) else None
return above.get("key") if isinstance(above, dict) and isinstance(above.get("key"), str) else None
status = fields.get("status") if isinstance(fields, dict) else None
category = status.get("statusCategory") if isinstance(status, dict) else None
return (above.get("key") if isinstance(above, dict) and isinstance(above.get("key"), str) else None), isinstance(category, dict) and category.get("key") == DONE
def found(self, authorization: str) -> list[Found] | Failure:
"""Each child issue, each followed by its sub-tasks."""
+3
View File
@@ -63,6 +63,9 @@ class EpicStore(typing.Protocol):
def comment(self, key: str, text: str) -> None | Failure:
"""Posts text, markdown, as a comment on the epic's child issue named key, for the people who work the epic to read. A sub-task, an issue outside the epic, or an empty or blank text is refused."""
def finish_issue(self, key: str) -> None | Failure:
"""Moves the epic's child issue named key, or a sub-task of one, to a done status, so that read answers it as done; one already done stays as it is. An issue outside the epic is refused. A Failure says why the move could not be made: the issue's workflow gives no way to a done status, gives several the backend cannot choose between, or refuses the move."""
def closed(self) -> bool | Failure:
"""Whether the epic itself is in a status the tracker counts as done."""
+14
View File
@@ -51,5 +51,19 @@ class Ranking(unittest.TestCase):
self.assertEqual(store.rank(str(child), "ZZZ-1"), Failure(f"ZZZ-1 is not one of the child issues of the epic ABC-12, so {child} is not ranked"))
class Finishing(unittest.TestCase):
def test_finishes_an_issue_to_the_status_done(self) -> None:
store = MemoryEpic("ABC-12")
key = store.file("ABC-12", "Count the runs.", "", ())
self.assertIsNone(store.finish_issue(str(key)))
self.assertEqual([(issue.status, issue.done) for issue in store.issues], [("Done", True)])
def test_refuses_to_finish_an_issue_outside_the_epic_saying_so(self) -> None:
self.assertEqual(MemoryEpic("ABC-12").finish_issue("ZZZ-1"), Failure("ZZZ-1 is not one of the child issues of the epic ABC-12, so it cannot be finished"))
def test_fails_to_finish_with_the_reason_given(self) -> None:
self.assertEqual(MemoryEpic("ABC-12", fails="Jira is down").finish_issue("ABC-100"), Failure("Jira is down"))
if __name__ == "__main__":
unittest.main()
+89 -7
View File
@@ -48,6 +48,10 @@ class FakeJira:
answers: dict[tuple[str, str], object] = dataclasses.field(default_factory=dict)
calls: list[tuple[str, str]] = dataclasses.field(default_factory=list)
comments: dict[str, list[object]] = dataclasses.field(default_factory=dict)
# The ID of each transition made.
transitioned: list[str] = dataclasses.field(default_factory=list)
# The transitions Jira offers an issue that isn't done.
workflow: list[dict[str, object]] = dataclasses.field(default_factory=lambda: [{"id": "31", "name": "Mark as done", "to": DONE}])
# The epic's own status, which the transition "Mark as done" moves to DONE.
epic_status: dict[str, object] = dataclasses.field(default_factory=lambda: dict(TO_DO))
@@ -75,8 +79,16 @@ class FakeJira:
return TYPES
if method == "POST" and url == SEARCH:
return self.page(body)
if method == "GET" and (held := next((issue for issue in self.issues if url == f"{ISSUES}/{issue['key']}?fields=parent"), None)):
return {"key": held["key"], "fields": {"parent": held["fields"]["parent"]}} # type: ignore[index]
if method == "GET" and (held := next((issue for issue in self.issues if url.startswith(f"{ISSUES}/{issue['key']}?fields=")), None)):
asked = url.partition("?fields=")[2].split(",")
return {"key": held["key"], "fields": {name: held["fields"][name] for name in asked}} # type: ignore[index]
if method == "GET" and (held := next((issue for issue in self.issues if url == f"{ISSUES}/{issue['key']}/transitions"), None)):
return {"transitions": [] if held["fields"]["status"] == DONE else self.workflow} # type: ignore[index]
if method == "POST" and (held := next((issue for issue in self.issues if url == f"{ISSUES}/{issue['key']}/transitions"), None)):
assert isinstance(body, dict)
held["fields"]["status"] = DONE # type: ignore[index]
self.transitioned.append(body["transition"]["id"])
return None
if method == "POST" and url == ISSUES:
return self.created(body)
if method == "PUT" and url == RANK:
@@ -206,6 +218,76 @@ class Jira(Case):
self.jira.answers[("GET", EPIC_STATUS)] = answer
self.assertEqual(self.new_store().closed(), Failure(reason))
def test_finishes_an_issue_by_the_transition_the_settings_name(self) -> None:
store = self.new_store()
key = store.file("ABC-12", "Count the runs.", "", ())
self.jira.workflow = [{"id": "11", "name": "Start", "to": {"name": "In Progress", "statusCategory": {"key": "indeterminate"}}}, {"id": "31", "name": "Mark as done", "to": DONE}]
self.assertIsNone(store.finish_issue(key))
self.assertEqual(self.jira.calls[-1], ("POST", f"{ISSUES}/{key}/transitions"))
self.assertEqual((self.jira.transitioned, self.jira.issues[0]["fields"]["status"]), (["31"], DONE)) # type: ignore[index]
def test_finishes_by_the_named_transition_where_several_lead_to_a_done_status(self) -> None:
key = self.new_store().file("ABC-12", "Count the runs.", "", ())
self.jira.workflow = [{"id": "31", "name": "Resolve", "to": DONE}, {"id": "41", "name": "Close", "to": {"name": "Closed", "statusCategory": {"key": "done"}}}]
self.assertIsNone(JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf, Finish("Close", "Closed")).finish_issue(key))
self.assertEqual(self.jira.transitioned, ["41"])
def test_leaves_an_issue_that_is_done_without_asking_for_its_transitions(self) -> None:
store = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf)
key = self.new_store().file("ABC-12", "Count the runs.", "", ())
self.jira.change(key, status=DONE)
self.assertIsNone(store.finish_issue(key))
self.assertNotIn(("GET", f"{ISSUES}/{key}/transitions"), self.jira.calls)
def test_a_finish_names_why_no_move_finishes_the_issue(self) -> None:
key = self.new_store().file("ABC-12", "Count the runs.", "", ())
unnamed = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf)
wrong_status = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf, Finish("Mark as done", "Closed"))
no_such = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf, Finish("Close", "Done"))
self.assertEqual(unnamed.finish_issue(key), Failure("do-epic's settings name no transition to finish an issue by: set `jira-finish-transition` and `jira-finish-status` in ~/.claude-projects/do-epic/config.toml, to the names Jira shows, such as \"Mark as done\" and \"Done\""))
self.assertEqual(wrong_status.finish_issue(key), Failure(f"{key}'s transition 'Mark as done' leads to the status 'Done', not to 'Closed', which `jira-finish-status` names"))
refused = no_such.finish_issue(key)
assert isinstance(refused, Failure)
self.assertIn(f"{key} has no transition 'Close' from its status", refused.reason)
self.assertEqual((self.jira.transitioned, self.jira.issues[0]["fields"]["status"]), ([], TO_DO)) # type: ignore[index]
def test_refuses_to_finish_a_sub_task_of_an_issue_that_is_no_child_of_the_epic_or_an_issue_without_a_parent(self) -> None:
store = self.new_store()
for key, parent in (("ABC-50", "ABC-60"), ("ABC-60", "ABC-61"), ("ABC-61", None)):
fields = {"summary": "Other.", "description": None, "labels": [], "assignee": None, "status": TO_DO, "parent": {"key": parent} if parent else None, "issuelinks": []}
self.jira.issues.append({"key": key, "fields": fields})
for key in ("ABC-50", "ABC-61"):
with self.subTest(key=key):
self.assertEqual(store.finish_issue(key), Failure(f"{key} is not one of the child issues of the epic ABC-12, so it cannot be finished"))
self.assertNotIn("POST", [method for method, _ in self.jira.calls])
def test_a_finish_jira_refuses_says_so_and_that_the_issue_may_have_moved(self) -> None:
store = self.new_store()
key = store.file("ABC-12", "Count the runs.", "", ())
self.jira.answers[("POST", f"{ISSUES}/{key}/transitions")] = Failure("Jira answered 400: Resolution is required")
self.assertEqual(store.finish_issue(key), Failure(f"cannot move {key} by 'Mark as done': Jira answered 400: Resolution is required; unless Jira refused the request, the issue may have moved: look at {key} before finishing the item again"))
def test_a_finish_whose_transitions_jira_cannot_give_or_gives_in_another_shape_fails(self) -> None:
store = self.new_store()
key = store.file("ABC-12", "Count the runs.", "", ())
url = ("GET", f"{ISSUES}/{key}/transitions")
self.jira.answers[url] = Failure("Jira answered 503")
self.assertEqual(store.finish_issue(key), Failure(f"cannot read {key}'s transitions: Jira answered 503"))
for answer in ({"transitions": [{"id": 31}]}, ["Mark as done"], {"transitions": 5}):
with self.subTest(answer=answer):
self.jira.answers[url] = answer
self.assertEqual(store.finish_issue(key), Failure(f"Jira answered {key}'s transitions in a shape other than the one it documents"))
def test_a_finish_whose_issue_or_parent_jira_cannot_read_says_which(self) -> None:
store = self.new_store()
child = store.file("ABC-12", "Count the runs.", "", ())
task = store.file(child, "Count them in the api.", "", ())
self.jira.answers[("GET", f"{ISSUES}/{task}?fields=parent,status")] = Failure("Jira answered 503")
self.assertEqual(store.finish_issue(task), Failure(f"cannot read {task} to finish it: Jira answered 503"))
del self.jira.answers[("GET", f"{ISSUES}/{task}?fields=parent,status")]
self.jira.answers[("GET", f"{ISSUES}/{child}?fields=parent,status")] = Failure("Jira answered 503")
self.assertEqual(store.finish_issue(task), Failure(f"cannot read {child} to finish its sub-task: Jira answered 503"))
def test_reads_the_sub_tasks_of_more_children_than_one_search_names(self) -> None:
store = self.new_store()
children = [store.file("ABC-12", f"Item {n}.", "", ()) for n in range(60)]
@@ -276,11 +358,11 @@ class Jira(Case):
self.assertEqual(store.read(), Failure("the search for ABC-12's child issues did not end within 1 pages"))
def test_refuses_to_file_under_another_epics_child_or_an_issue_it_cannot_read(self) -> None:
self.jira.issues.append({"key": "ABC-5", "fields": {"parent": {"key": "ABC-1"}}})
self.jira.issues.append({"key": "ABC-5", "fields": {"parent": {"key": "ABC-1"}, "status": TO_DO}})
store = self.new_store()
self.assertEqual(store.file("ABC-5", "Count more.", "", ()), Failure("ABC-5 is neither the epic ABC-12 nor one of its child issues, so nothing can be filed under it"))
self.assertEqual(store.file("ABC-77", "Count more.", "", ()), Failure(f"cannot read ABC-77 to file under it: Jira answered 404 for GET {ISSUES}/ABC-77?fields=parent"))
self.jira.answers[("GET", f"{ISSUES}/ABC-78?fields=parent")] = ["ABC-12"]
self.assertEqual(store.file("ABC-77", "Count more.", "", ()), Failure(f"cannot read ABC-77 to file under it: Jira answered 404 for GET {ISSUES}/ABC-77?fields=parent,status"))
self.jira.answers[("GET", f"{ISSUES}/ABC-78?fields=parent,status")] = ["ABC-12"]
self.assertEqual(store.file("ABC-78", "Count more.", "", ()), Failure("ABC-78 is neither the epic ABC-12 nor one of its child issues, so nothing can be filed under it"))
self.assertEqual([call for call in self.jira.calls if call[0] == "POST" and call[1] == ISSUES], [])
@@ -305,14 +387,14 @@ class Jira(Case):
def test_an_issue_jira_cannot_read_is_not_commented_on(self) -> None:
store = self.new_store()
key = store.file("ABC-12", "Count the runs.", "", ())
self.jira.answers[("GET", f"{ISSUES}/{key}?fields=parent")] = Failure("Jira answered 500")
self.jira.answers[("GET", f"{ISSUES}/{key}?fields=parent,status")] = Failure("Jira answered 500")
self.assertEqual(store.comment(str(key), "Hello."), Failure(f"cannot read {key} to comment on it: Jira answered 500"))
self.assertNotIn(("POST", f"{ISSUES}/{key}/comment"), self.jira.calls)
def test_an_issue_jira_cannot_read_is_not_labelled(self) -> None:
store = self.new_store()
key = store.file("ABC-12", "Count the runs.", "", ())
self.jira.answers[("GET", f"{ISSUES}/{key}?fields=parent")] = Failure("Jira answered 500")
self.jira.answers[("GET", f"{ISSUES}/{key}?fields=parent,status")] = Failure("Jira answered 500")
self.assertEqual(store.add_label(str(key), "repo:log"), Failure(f"cannot read {key} to label it: Jira answered 500"))
self.assertNotIn(("PUT", f"{ISSUES}/{key}"), self.jira.calls)
+14 -3
View File
@@ -6,6 +6,7 @@ from do_epic import findings
from loop_claude.project.records import HUMAN_RULE_NAMES, RECORD_FILES
from text_files.markdown_text import listed
import pathlib
from project_config.settings import ProjectConfig
from model_routing.ladder import ProjectRung
from loop_claude.cycle import prompts
from model_routing.route import Route
@@ -15,10 +16,20 @@ from agent_cycle.worker_prompts import WorkerPrompts
DRIVER = "do-epic"
def task(issue: EpicIssue, epic: str, checkout: str | None, launcher: pathlib.Path, language: str) -> str:
"""The task of the chunk that works issue, of the epic with the key epic: in checkout, or without a repo where it is None. launcher is the do-epic that runs the chunk, and language the one the epic's Jira text is in."""
def shipping(config: ProjectConfig) -> str:
"""How a chunk in the repo that config names ships its change. An epic's issue isn't an item of the repo's plan, so `chunk-pr merge --finish`, which adds a finished item's changelog bullet, doesn't apply: the worker writes the bullet itself, where the repo publishes something others consume (docs/decisions.md → `do-epic: drives one Jira epic …`, "Releases")."""
opening = "The issue isn't an item of the repo's plan, so run `chunk-pr merge` without `--finish`."
if config.epic:
return f"{opening} The repo's plan is a Jira epic, and the history of its issues serves as the changelog, so leave the changelog as it is."
changelog = config.paths["changelog"].relative_to(config.top) if "changelog" in config.paths and config.paths["changelog"].is_relative_to(config.top) else config.places["changelog"]
return f"{opening} Where the repo publishes something others consume, add one bullet to `## Unreleased` in `{changelog}` that tells the repo's consumers what changed; otherwise leave the changelog as it is."
def task(issue: EpicIssue, epic: str, checkout: str | None, launcher: pathlib.Path, language: str, config: ProjectConfig | None) -> str:
"""The task of the chunk that works issue, of the epic with the key epic: in checkout, or without a repo where it is None. launcher is the do-epic that runs the chunk, language the one the epic's Jira text is in, and config the project config of the repo's checkout, None without a repo."""
shipped = shipping(config) if config else ""
where = f"in the checkout {checkout}, on the branch {issue.key}" if checkout else "which changes no repo: work in the folder you start in"
return f"Work the Jira issue {issue.key} of the epic {epic} as one chunk, {where}. {findings.instructions(epic, launcher, language)} Its summary: {issue.summary}" + (f"\n\nIts description:\n\n{issue.detail}" if issue.detail else "")
return f"Work the Jira issue {issue.key} of the epic {epic} as one chunk, {where}. {" ".join(filter(None, [findings.instructions(epic, launcher, language), shipped]))} Its summary: {issue.summary}" + (f"\n\nIts description:\n\n{issue.detail}" if issue.detail else "")
CODE_HEALTH = '~/.claude/CLAUDE.md → "Shared goal"'
+1 -1
View File
@@ -13,7 +13,7 @@ One pair per machine, the same for every epic (docs/decisions.md → `do-epic: d
- `repoless-model` is the model that works an epic item with no repo: a model on the routing ladder, `model_routing/routing-ladder.json`.
- `clone-folder` is the folder a missing repo is cloned into: a path that starts with / or ~/. `~/code` where left out.
- `language` is the default language of Jira text, by its English name. English where left out.
- `jira-finish-transition` and `jira-finish-status` name the workflow transition that closes a finished epic, such as "Mark as done", and the status it leads to, such as "Done". A project's config names a plan item's the same way. Set both or neither; without them do-epic closes no epic.
- `jira-finish-transition` and `jira-finish-status` name the workflow transition that moves a finished chunk's issue and closes a finished epic, such as "Mark as done", and the status it leads to, such as "Done". A project's config names a plan item's the same way. Set both or neither; without them do-epic moves no issue to done and closes no epic.
- `repo-rule.md` is prose that says how to tell an item's repo, and mustn't be blank."""
import dataclasses
import pathlib
+42 -16
View File
@@ -9,9 +9,10 @@ import sys
import typing
from loop_claude.loop.chunk_start import archived_route, routed
from do_epic import chunk_prompt, findings, finish, gates, human_tasks, parked, scheduler
from do_epic import chunk_prompt, findings, finish, gates, human_tasks, parked, scheduler, split, status
from do_epic.repo_pick import ClaudeWork, HumanTask, recorded, Repo
from loop_claude.loop.close import closed_cycle
from project_config.main import located as config_located
from loop_claude.project.records import CONSEQUENCE, read_records
from agent_cycle.run import Cycle, run_cycle
from do_epic.config import DoEpicConfig, load
@@ -54,7 +55,7 @@ A chunk whose worker ends its run while its pull request waits on its checks, an
is parked: it frees its place for the next chunk, and its window's name says what it awaits. Its worker goes
on once the checks pass, the approval comes or a reviewer comments, and a place is free; until one is, the
name says `awaits a slot`. A parked chunk survives a reboot: run do-epic <EPIC-KEY> again to go on polling.
--status starts no chunk: it prints each open issue with whether its chunk runs, or why it waits.
--status doesn't start any chunk. It prints a line per open issue: that its chunk runs or asks you a question, or why it waits, such as the gate a parked chunk awaits and since when.
{findings.HELP}
{finish.HELP}
The Jira site and its credentials are set in ~/.claude-projects/do-epic/config.toml."""
@@ -111,8 +112,8 @@ def main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher:
def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, effects: Effects, backend: Backend, stdin: typing.TextIO, forge_at: typing.Callable[[str], Run]) -> Stop:
chunk, words = (argv[1], argv[2:]) if len(argv) >= 2 and argv[0] == scheduler.CHUNK_FLAG else (None, argv)
status = chunk is None and words[1:] == [STATUS_FLAG]
words = words[:1] if status else words
status_asked = chunk is None and words[1:] == [STATUS_FLAG]
words = words[:1] if status_asked else words
# What the words after the epic's key write into the epic, where they are a filing or a decision.
writes = findings.parsed(words[1:]) if chunk is None else None
closes = chunk is None and words[1:] == [finish.CLOSE]
@@ -128,7 +129,7 @@ def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher:
return Stop(1, config.reason)
store, record = backend(config, words[0])
epic = EpicRun(words[0], config, store, record, paths, env, launcher, effects, forge_at)
if status:
if status_asked:
return status_printed(epic)
return windows_opened(epic) if chunk is None else chunk_run(chunk, epic)
@@ -136,7 +137,7 @@ def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher:
def status_printed(epic: EpicRun) -> Stop:
"""What `do-epic <EPIC-KEY> --status` does: prints a line per open issue, and doesn't start anything."""
issues = epic.store.read()
lines = issues if isinstance(issues, Failure) else scheduler.status(epic.key, epic.paths.home, issues, epic.effects.tmux)
lines = issues if isinstance(issues, Failure) else status.lines(epic.key, epic.paths.home, issues, epic.effects.tmux)
return Stop(1, lines.reason) if isinstance(lines, Failure) else Stop(0, "\n".join(lines) or f"the epic {epic.key} has no open issue")
@@ -152,7 +153,8 @@ def epic_written(key: str, writes: tuple[str, str, tuple[str, ...]] | None, path
def windows_opened(epic: EpicRun) -> Stop:
"""What the do-epic the human runs does: starts each chunk that may start now, says why each other open issue waits, then puts the epic's session on the terminal until the human detaches."""
started = chunks_started(epic, None)
issues = epic.store.read()
started = issues if isinstance(issues, Failure) else chunks_started(epic, issues, None)
if isinstance(started, Failure):
return Stop(1, started.reason)
say(f"started {', '.join(started.started)} in the tmux session {epic.session}" if started.started else "started no chunk", epic.effects, stdout=True)
@@ -169,11 +171,8 @@ def windows_opened(epic: EpicRun) -> Stop:
return Stop(1, f"`tmux {' '.join(shown)}` failed; the chunks go on in the tmux session") if epic.effects.tmux_on_terminal(shown) else Stop(0, "")
def chunks_started(epic: EpicRun, own: str | None) -> scheduler.Started | Failure:
"""scheduler.start_chunks on the epic's issues and cap, read afresh; own is the issue of the chunk that asks. Where no issue is open, the chunk to start is the epic's finishing, unless the epic is closed."""
issues = epic.store.read()
if isinstance(issues, Failure):
return issues
def chunks_started(epic: EpicRun, issues: list[EpicIssue], own: str | None) -> scheduler.Started | Failure:
"""scheduler.start_chunks on the epic's issues, as read, and its cap, read afresh; own is the issue of the chunk that asks. Where no issue is open, the chunk to start is the epic's finishing, unless the epic is closed."""
closed = finish.due(issues) and epic.store.closed()
if isinstance(closed, Failure):
return closed
@@ -309,7 +308,8 @@ def parked_through(repo: str, loop: Loop, epic: EpicRun, starts: bool) -> str |
shown = awaits
if on is None:
# Once the window shows as parked, so the chunks that start count it as running nowhere.
started = chunks_started(epic, key)
issues = epic.store.read()
started = issues if isinstance(issues, Failure) else chunks_started(epic, issues, key)
say(f"could not start the next chunk: {started.reason}" if isinstance(started, Failure) else f"started {', '.join(started.started) or 'no other'}", epic.effects, stdout=True)
on = now.on if isinstance(now, gates.Gate) else on
if stays is not None and stays != said:
@@ -355,14 +355,37 @@ def chunk_root(key: str, issue: EpicIssue | None, epic: EpicRun) -> tuple[str, s
def handed_on(key: str, epic: EpicRun) -> Stop:
"""The stop of a do-epic whose chunk finished, once it has started each chunk that may start now. Its window closes as it exits."""
started = chunks_started(epic, key)
"""The stop of a do-epic whose chunk finished. It first moves the chunk's issue to done (the epic's finishing has none), and its split item too where that was the last of the item's sub-tasks, so that no finished chunk starts again and what they block may start, then starts each chunk that may start now. Its window closes as it exits."""
# The epic's finishing has no issue to move: the epic is closed by `--close-epic`.
moved = None if key == epic.key else epic.store.finish_issue(key)
if isinstance(moved, Failure):
return Stop(1, f"the chunk finished, but its issue could not move to done: {moved.reason}; once it is done in Jira, run `do-epic {epic.key}` to start the chunks it blocks")
issues = epic.store.read()
if isinstance(issues, Failure):
return Stop(1, f"the chunk finished, but the next could not start: {issues.reason}")
# A search may not show the move yet, so the issue counts as done here whatever the read says.
issues = [dataclasses.replace(each, done=True) if each.key == key else each for each in issues]
closed = split_items_closed(epic, issues)
if isinstance(closed, Stop):
return closed
started = chunks_started(epic, closed, key)
if isinstance(started, Failure):
return Stop(1, f"the chunk finished, but the next could not start: {started.reason}")
say(f"the chunk finished; started {', '.join(started.started) or 'no other'}", epic.effects, stdout=True)
return Stop(0, "")
def split_items_closed(epic: EpicRun, issues: list[EpicIssue]) -> list[EpicIssue] | Stop:
"""The issues, with each item split by repo whose sub-tasks are all done moved to done in the tracker and read as done; the stop where one cannot move. Its last sub-task to finish closes it, and one an earlier run left open closes with it."""
for item in issues:
if split.SPLIT_LABEL in item.labels and not item.done and split.finished(issues, item.key):
moved = epic.store.finish_issue(item.key)
if isinstance(moved, Failure):
return Stop(1, f"the chunk finished, but its split item {item.key} could not move to done: {moved.reason}; once it is done in Jira, run `do-epic {epic.key}` to start the chunks it blocks")
issues = [dataclasses.replace(each, done=True) if each.key == item.key else each for each in issues]
return issues
def next_cycle(loop_run: LoopRun, loop: Loop, in_repo: bool, epic: EpicRun, news: str = "") -> Cycle | Stop:
"""The cycle loop_run runs next, from the issue, the premises, the records, the models and the routing ladder read afresh; the stop where one of them cannot be read. news is what `parked_through` tells the worker of a chunk that was parked, and opens its prompt. A chunk in a repo routes on that repo's model and ladder, and one without a repo on the machine setting `repoless-model` and the shipped ladder."""
premises = premises_read(loop.root if in_repo else None, epic)
@@ -400,7 +423,10 @@ def chunk_work(key: str, checkout: str | None, language: str, epic: EpicRun) ->
issue = issue_read(key, epic)
if isinstance(issue, Stop):
return issue
return chunk_prompt.task(issue, epic.key, checkout, epic.launcher, language), RoutingIssue(issue) if "L" in issue.scores else None
config = config_located(checkout, epic.paths.home) if checkout else None
if isinstance(config, Failure):
return Stop(1, config.reason)
return chunk_prompt.task(issue, epic.key, checkout, epic.launcher, language, config), RoutingIssue(issue) if "L" in issue.scores else None
issues = epic.store.read()
if isinstance(issues, Failure):
return Stop(1, issues.reason)
-20
View File
@@ -223,23 +223,3 @@ def resume(epic: Epic, repo: str, window: tmux.Window, run: tmux.Tmux) -> str |
return None
except OSError as failure:
return f"cannot lock {failure.filename or epic.folder / LOCK}: {failure.strerror}"
def status(key: str, home: pathlib.Path, issues: list[EpicIssue], run: tmux.Tmux) -> list[str] | Failure:
"""A line per open issue of the epic called key, in the tracker's rank order: that its chunk runs, or why it waits. It doesn't start anything and checks no limit, so the line of a chunk that has yet to start doesn't say which limit holds it back."""
found, waits = chunks(issues)
parked = parked_chunks(home / STATE / key)
if isinstance(parked, Failure):
return parked
windows = tmux.listed(tmux.session_name(tmux.EPIC, key), run)
live = {window.name: window for window in windows if not window.dead}
again = f"run `do-epic {key}` to start it again"
reasons = {wait.issue: wait.reason for wait in waits}
for chunk in found:
if chunk.issue in parked:
reasons[chunk.issue] = parked[chunk.issue].waits(live[chunk.issue].awaits) if chunk.issue in live else f"{parked[chunk.issue].waits('')}, and its window stopped; {again}"
elif chunk.human and chunk.issue in live:
reasons[chunk.issue] = HUMAN_WAIT
elif chunk.issue not in live:
reasons[chunk.issue] = f"its window stopped; {again}" if chunk.issue in {window.name for window in windows} else f"it has not started; `do-epic {key}` starts it" + ("" if chunk.human else " once the epic and its repo have room")
return [f"{issue.key} waits: {reasons[issue.key]}" if issue.key in reasons else f"{issue.key} runs" for issue in issues if issue.key in reasons or issue.key in live]
+50
View File
@@ -0,0 +1,50 @@
"""What `do-epic <EPIC-KEY> --status` prints: a line per open issue of the epic (docs/decisions.md → `do-epic: drives one Jira epic …`)."""
import datetime
import pathlib
from do_epic.scheduler import chunks, HUMAN_WAIT, STATE
from do_epic.backend.protocol import EpicIssue
from failure import Failure
from do_epic.parked import file_of, Parked, parked_chunks, SLOT
from agent_cycle import tmux
def since(folder: pathlib.Path, chunk: Parked) -> str:
"""`, since <time>`: when the chunk's pull request began to await the gate its file records, to the minute in UTC, since the machine may be one the human reaches over ssh. The file is written once per gate. Empty where the file cannot be read."""
try:
return f", since {datetime.datetime.fromtimestamp(file_of(folder, chunk.issue).stat().st_mtime, datetime.timezone.utc).strftime('%Y-%m-%d %H:%M')} UTC"
except OSError:
return ""
def lines(key: str, home: pathlib.Path, issues: list[EpicIssue], run: tmux.Tmux) -> list[str] | Failure:
"""A line per open issue of the epic called key, in the tracker's rank order: that its chunk runs or asks the human, or why it waits. It doesn't start anything or check any limit, so the line of a chunk that has yet to start doesn't say which limit holds it back."""
found, waits = chunks(issues)
folder = home / STATE / key
parked = parked_chunks(folder)
if isinstance(parked, Failure):
return parked
session = tmux.session_name(tmux.EPIC, key)
windows = tmux.listed(session, run)
live = {window.name: window for window in windows if not window.dead}
again = f"run `do-epic {key}` to start it again"
reasons = {wait.issue: wait.reason for wait in waits}
for chunk in found:
if chunk.issue in parked:
shown = live[chunk.issue].awaits if chunk.issue in live else ""
# Past its gate, a chunk that awaits a slot has no time the file knows: the file's is when its gate began.
when = "" if shown == SLOT else since(folder, parked[chunk.issue])
stopped = "" if chunk.issue in live else f", and its window stopped; {again}"
reasons[chunk.issue] = parked[chunk.issue].waits(shown) + when + stopped
elif chunk.human and chunk.issue in live:
reasons[chunk.issue] = HUMAN_WAIT
elif chunk.issue not in live:
reasons[chunk.issue] = f"its window stopped; {again}" if chunk.issue in {window.name for window in windows} else f"it has not started; `do-epic {key}` starts it" + ("" if chunk.human else " once the epic and its repo have room")
return [line(issue.key, reasons, live, session) for issue in issues if issue.key in reasons or issue.key in live]
def line(issue: str, reasons: dict[str, str], live: dict[str, tmux.Listed], session: str) -> str:
"""The status line of issue, whose chunk has a live window or a reason not to run."""
if issue in reasons:
return f"{issue} waits: {reasons[issue]}"
return f"{issue} asks you: answer its question in the tmux window {session}:{issue}" if live[issue].asks else f"{issue} runs"
+118 -18
View File
@@ -13,6 +13,8 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic import chunk_prompt, main
from project_config.test_project_config import configured
from do_epic.config import DoEpicConfig
from project_config.settings import Epic, Finish
from do_epic.backend.protocol import EpicIssue
from do_epic.epic_record import EpicRecord
from agent_cycle import escalation_mark, judge, tmux
@@ -77,6 +79,12 @@ class DoEpicTest(unittest.TestCase):
self.issues = [issue("ABC-20", "repo:api")]
return folder
def epic_run(self, fake: FakeEffects, env: dict[str, str] | None = None) -> main.EpicRun:
config = main.load(self.home)
assert not isinstance(config, Failure)
store, record = self.backend(config, "ABC-12")
return main.EpicRun("ABC-12", config, store, record, paths_from(self.home), env or {}, pathlib.Path("/b/do-epic"), fake.effects())
def run_main(self, argv: list[str], fake: FakeEffects, env: dict[str, str] | None = None) -> tuple[int, str, str]:
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
@@ -84,6 +92,14 @@ class DoEpicTest(unittest.TestCase):
return code, out.getvalue(), err.getvalue()
class TheJiraBackend(unittest.TestCase):
def test_reads_the_epic_with_the_credentials_and_the_finish_the_config_names(self) -> None:
config = DoEpicConfig(pathlib.Path("/c"), "https://acme.atlassian.net", pathlib.Path("/h/jira.env"), pathlib.Path("/h/code"), "English", "claude-opus-5-5", "rule", Finish("Mark as done", "Done"))
store, record = main.jira_backend(config, "ABC-12")
self.assertEqual((store.epic, store.env_file, store.finish), (Epic("https://acme.atlassian.net", "ABC-12"), pathlib.Path("/h/jira.env"), Finish("Mark as done", "Done"))) # type: ignore[attr-defined]
self.assertEqual((record.description.epic, record.description.env_file), (store.epic, store.env_file)) # type: ignore[attr-defined]
class TheLauncher(unittest.TestCase):
def test_the_repo_ships_a_do_epic_that_prints_its_help(self) -> None:
launcher = pathlib.Path(__file__).resolve().parents[1] / "do-epic"
@@ -139,10 +155,7 @@ class ACycleOfAChunkWithoutARepo(DoEpicTest):
def cycle(self, env: dict[str, str] | None = None) -> main.Cycle:
fake = FakeEffects(git=[Failure("no git"), Failure("no git")])
paths = paths_from(self.home)
config = main.load(self.home)
assert not isinstance(config, Failure)
store, record = self.backend(config, "ABC-12")
epic = main.EpicRun("ABC-12", config, store, record, paths, env or {}, pathlib.Path("/b/do-epic"), fake.effects())
epic = self.epic_run(fake, env)
place = main.chunk_root("ABC-21", self.issues[1], epic)
assert isinstance(place, tuple)
root, repo = place
@@ -207,6 +220,14 @@ class TheHumansRun(DoEpicTest):
code, _, err = self.run_main(["ABC-12"], fake, {"TMUX": "/tmp/tmux"})
self.assertEqual((code, err.split(" ", 1)[1]), (1, "`tmux switch-client -t =epic-ABC-12` failed; the chunks go on in the tmux session\n"))
def test_stops_with_the_reason_where_the_epics_issues_cannot_be_read(self) -> None:
store = MemoryEpic("ABC-12", fails="Jira answered 503")
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
code, out, err = self.run_main(["ABC-12"], FakeEffects(on_terminal=False))
self.assertEqual(code, 1)
self.assertIn("Jira answered 503\n", err)
self.assertNotIn("started", out)
def test_off_a_terminal_it_says_how_to_see_the_chunks(self) -> None:
code, out, err = self.run_main(["ABC-12"], FakeEffects(on_terminal=False, windows="ABC-21\t0\t@9\n"))
self.assertEqual((code, err), (0, ""))
@@ -320,6 +341,67 @@ class AChunksRun(DoEpicTest):
self.assertEqual(code, 2, out)
self.assertIn("the judge ruled it unfinished 6 cycles running; finish the chunk yourself, or rerun do-epic to give it 6 more cycles", err + out)
def test_a_finished_chunk_moves_its_issue_to_done_before_the_chunk_it_blocks_starts(self) -> None:
store = MemoryEpic("ABC-12", [self.issues[0], self.issues[1], issue("ABC-22", "do-epic-claude", blockers=("ABC-21",))])
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD, windows="ABC-21\t0\t@9\n")
code, out, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
self.assertEqual({each.key: each.done for each in store.issues}, {"ABC-20": False, "ABC-21": True, "ABC-22": False})
self.assertIn("the chunk finished; started ABC-22\n", out)
def test_a_finished_chunk_counts_as_done_though_the_search_still_shows_its_issue_open(self) -> None:
issues = [self.issues[0], self.issues[1], issue("ABC-22", "do-epic-claude", blockers=("ABC-21",))]
store = MemoryEpic("ABC-12", issues)
store.read = lambda: list(issues) # type: ignore[method-assign]
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD, windows="ABC-21\t0\t@9\n")
code, out, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
self.assertIn("the chunk finished; started ABC-22\n", out)
def test_the_last_sub_task_of_a_split_item_to_finish_moves_the_item_to_done_and_starts_what_it_blocks(self) -> None:
parent = issue("ABC-21", "split-by-repo")
tasks = [issue("ABC-23", "do-epic-claude", parent="ABC-21"), issue("ABC-24", "do-epic-claude", parent="ABC-21", done=True)]
store = MemoryEpic("ABC-12", [self.issues[0], parent, *tasks, issue("ABC-22", "do-epic-claude", blockers=("ABC-21",))])
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD, windows="ABC-23\t0\t@9\n")
code, out, err = self.run_main(["--chunk", "ABC-23", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
self.assertEqual({each.key: each.done for each in store.issues}, {"ABC-20": False, "ABC-21": True, "ABC-23": True, "ABC-24": True, "ABC-22": False})
self.assertIn("the chunk finished; started ABC-22\n", out)
def test_a_sub_task_that_leaves_another_open_leaves_its_split_item_open(self) -> None:
parent = issue("ABC-21", "split-by-repo")
store = MemoryEpic("ABC-12", [self.issues[0], parent, issue("ABC-23", "do-epic-claude", parent="ABC-21"), issue("ABC-24", "do-epic-claude", parent="ABC-21")])
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD, windows="ABC-23\t0\t@9\n")
code, _, err = self.run_main(["--chunk", "ABC-23", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
self.assertEqual({each.key: each.done for each in store.issues if each.key in ("ABC-21", "ABC-23", "ABC-24")}, {"ABC-21": False, "ABC-23": True, "ABC-24": False})
def test_a_split_item_that_jira_will_not_move_to_done_stops_with_the_reason(self) -> None:
parent = issue("ABC-21", "split-by-repo")
store = MemoryEpic("ABC-12", [self.issues[0], parent, issue("ABC-23", "do-epic-claude", parent="ABC-21")])
finish = store.finish_issue
store.finish_issue = lambda key: Failure("no way to done") if key == "ABC-21" else finish(key) # type: ignore[method-assign]
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD, windows="ABC-23\t0\t@9\n")
code, out, err = self.run_main(["--chunk", "ABC-23", "ABC-12"], fake, MODELS)
self.assertEqual(code, 1)
self.assertIn("the chunk finished, but its split item ABC-21 could not move to done: no way to done; once it is done in Jira, run `do-epic ABC-12` to start the chunks it blocks\n", err)
self.assertNotIn("started", out)
def test_a_chunk_whose_issue_jira_will_not_move_to_done_stops_with_the_reason_and_starts_no_other(self) -> None:
store = MemoryEpic("ABC-12", list(self.issues))
store.finish_issue = lambda key: Failure("ABC-21's status has no transition to a done status") # type: ignore[method-assign]
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD)
code, out, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], fake, MODELS)
self.assertEqual(code, 1)
self.assertIn("the chunk finished, but its issue could not move to done: ABC-21's status has no transition to a done status; once it is done in Jira, run `do-epic ABC-12` to start the chunks it blocks\n", err)
self.assertNotIn("started", out)
def test_a_finished_chunk_says_why_the_next_could_not_start(self) -> None:
store = MemoryEpic("ABC-12", list(self.issues))
reads = iter([self.issues, self.issues, Failure("Jira answered 503")])
@@ -330,6 +412,12 @@ class AChunksRun(DoEpicTest):
self.assertEqual(code, 1)
self.assertIn("the chunk finished, but the next could not start: Jira answered 503\n", err)
def test_a_chunk_in_a_folder_no_project_config_names_stops_with_gits_reason(self) -> None:
stopped = main.chunk_work("ABC-21", str(self.home), "English", self.epic_run(FakeEffects()))
assert isinstance(stopped, main.Stop)
self.assertEqual(stopped.code, 1)
self.assertIn("rev-parse", stopped.reason) # git's reason, since no project config can be found without a checkout
def test_a_chunk_in_a_repo_works_in_its_checkout_on_the_repos_premises_and_records(self) -> None:
checkout = self.home / "code" / "api"
configured(self, checkout, home=self.home)
@@ -345,7 +433,9 @@ class AChunksRun(DoEpicTest):
self.assertIn("Ship the import.", prompt)
self.assertIn("The repo's goals, which rank after the epic's and after code health, are from", prompt)
self.assertIn("Serve the API.", prompt)
self.assertIn("the chunk finished; started no other\n", out)
self.assertIn("without `--finish`", prompt)
self.assertIn("add one bullet to `## Unreleased` in `CHANGELOG.md`", prompt)
self.assertIn("the chunk finished; started ABC-12\n", out)
judge_prompt = [what[1] for seam, what in fake.calls if seam == "claude"][0]
self.assertIn("The records: the epic's scoring and decisions, then the repo's working rules and decisions, then the human's rules for every project:\nFrom the epic ABC-12's description, ## Decisions:\nKeep the v1 endpoints.\n\nFrom AGENTS.md:\nSquash every merge.", judge_prompt)
self.assertIn("writing it into the epic's description under ## Decisions, the repo's goals file's Goals or Audience, AGENTS.md, docs/decisions.md, the repo's plan or a comment", judge_prompt)
@@ -563,6 +653,26 @@ class AChunkWhosePullRequestWaitsOnAGate(DoEpicTest):
self.assertFalse(self.file.exists())
self.assertEqual(len(prompts), 2)
def test_a_chunk_parks_and_resumes_though_the_epics_issues_cannot_be_read(self) -> None:
self.forges = [awaiting(), awaiting(decision="APPROVED")]
store = MemoryEpic("ABC-12", list(self.issues))
read = store.read
unreadable = [False]
worker = self.worker()
def unreadable_after(*args: object) -> object:
unreadable[0] = True
return worker(*args) # type: ignore[arg-type]
store.read = lambda: Failure("Jira answered 502") if unreadable[0] else read() # type: ignore[method-assign]
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
fake = FakeEffects(streams=[unreadable_after, self.worker()], claude=[judged("finished"), judged("finished")], git=UNREAD, windows=PARKED_WINDOW)
fake.effects = lambda made=fake.effects(): dataclasses.replace(made, sleep=lambda seconds: unreadable.__setitem__(0, False)) # type: ignore[method-assign]
code, out, err, prompts = self.parked_run(fake)
self.assertEqual(code, 0, err)
self.assertIn("parked: pull request #7 awaits an approval\ncould not start the next chunk: Jira answered 502\n", out)
self.assertFalse(self.file.exists())
self.assertEqual(len(prompts), 2)
def test_a_forge_that_cannot_be_read_parks_no_chunk_and_unparks_none(self) -> None:
self.forges = [awaiting(fails="gh pr checks")]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD)
@@ -606,23 +716,13 @@ class AChunkWhosePullRequestWaitsOnAGate(DoEpicTest):
class TheStatus(DoEpicTest):
def test_prints_what_each_open_issue_does_and_starts_nothing(self) -> None:
self.issues = [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api"), issue("ABC-22", "repo:api"), issue("ABC-23", "repo:api", blockers=("ABC-20",)), issue("ABC-24", "repo:api"), issue("ABC-25", "repo:api", done=True), issue("ABC-26", "repo:api"), issue("ABC-27")]
folder = self.home / ".local/state/do-epic/ABC-12"
parked.park(folder, parked.Parked("ABC-20", "/code/api-ABC-20", "7", "s", "an approval"))
parked.park(folder, parked.Parked("ABC-26", "/code/api-ABC-26", "9", "s", "its checks"))
parked.park(folder, parked.Parked("ABC-28", "/code/api-ABC-28", "11", "s", "an approval"))
self.issues.insert(7, issue("ABC-28", "repo:api"))
fake = FakeEffects(windows="ABC-20 awaits an approval\t0\t@1\nABC-21 ?\t0\t@2\nABC-22\t1\t@3\nABC-28 awaits a slot\t0\t@4\n")
self.issues = [issue("ABC-21", "repo:api"), issue("ABC-24", "repo:api"), issue("ABC-27")]
fake = FakeEffects(windows="ABC-21 ?\t0\t@2\n")
code, out, err = self.run_main(["ABC-12", "--status"], fake)
self.assertEqual((code, err), (0, ""))
self.assertEqual(out.replace("<1790000000> ", "").splitlines(), [
"ABC-20 waits: it is parked: its pull request #7 awaits an approval",
"ABC-21 runs",
"ABC-22 waits: its window stopped; run `do-epic ABC-12` to start it again",
"ABC-23 waits: ABC-20 blocks it",
"ABC-21 asks you: answer its question in the tmux window epic-ABC-12:ABC-21",
"ABC-24 waits: it has not started; `do-epic ABC-12` starts it once the epic and its repo have room",
"ABC-26 waits: it is parked: its pull request #9 awaits its checks, and its window stopped; run `do-epic ABC-12` to start it again",
"ABC-28 waits: it is parked: its worker has work again on pull request #11 and awaits a slot",
"ABC-27 waits: no label names its repo",
])
self.assertEqual({args[0] for args in fake.tmux_calls}, {"-V", "list-windows"})
+31 -2
View File
@@ -15,6 +15,7 @@ from do_epic.epic_record import parallel_chunks_in
from loop_claude.cycle import prompts
from model_routing.route import Route
from model_routing.ladder import Rung
from project_config import settings
from agent_cycle import tmux
@@ -314,6 +315,9 @@ class StartingAnEpicsChunks(unittest.TestCase):
self.assertRegex(found.reason, f"^cannot lock {self.home}/.local/state/do-epic/ABC-12: \\w")
CONFIG = settings.ProjectConfig("api", pathlib.Path("/c/api"), pathlib.Path("/code/api"), {"changelog": pathlib.Path("/code/api/CHANGELOG.md")}, epic=settings.Epic("https://acme.atlassian.net", "API-1"))
class TheFirstPrompt(unittest.TestCase):
def test_the_task_names_the_checkout_and_branch_and_quotes_a_description_only_where_there_is_one(self) -> None:
labels = "`repo:<name>` for the repo that works it, `do-epic-claude` for work of Claude's that changes no repo, or `do-epic-human` for a task of the human's"
@@ -322,7 +326,32 @@ class TheFirstPrompt(unittest.TestCase):
"Where filing fails and says the issue may exist, ask the human to look before you file it again. File a finding about a repo's goals by that repo's rules. Where unsure which, ask the human. "
"Record a decision that governs the epic, such as an answer the human typed, with `/b/do-epic ABC-12 --record-decision \"<title>\"` and its text on stdin. Write the issue and the decision in Swedish, the epic's language."
)
self.assertEqual(chunk_prompt.task(issue("ABC-20"), "ABC-12", "/code/api", pathlib.Path("/b/do-epic"), "Swedish"), f"Work the Jira issue ABC-20 of the epic ABC-12 as one chunk, in the checkout /code/api, on the branch ABC-20. {told} Its summary: Do ABC-20")
task = chunk_prompt.task(issue("ABC-20"), "ABC-12", "/code/api", pathlib.Path("/b/do-epic"), "Swedish", CONFIG)
self.assertTrue(task.startswith(f"Work the Jira issue ABC-20 of the epic ABC-12 as one chunk, in the checkout /code/api, on the branch ABC-20. {told} "))
self.assertTrue(task.endswith(" Its summary: Do ABC-20"))
def test_a_chunk_without_a_repo_is_told_nothing_of_shipping(self) -> None:
task = chunk_prompt.task(issue("ABC-20"), "ABC-12", None, pathlib.Path("/b/do-epic"), "Swedish", None)
self.assertTrue(task.endswith("Swedish, the epic's language. Its summary: Do ABC-20"))
self.assertNotIn("--finish", task)
def test_a_repo_with_a_plan_file_is_told_to_add_a_bullet_to_its_changelog_where_it_publishes(self) -> None:
config = settings.ProjectConfig("api", pathlib.Path("/c/api"), pathlib.Path("/code/api"), {"changelog": pathlib.Path("/code/api/CHANGELOG.md")})
told = chunk_prompt.shipping(config)
self.assertTrue(told.startswith("The issue isn't an item of the repo's plan, so run `chunk-pr merge` without `--finish`."))
self.assertIn("Where the repo publishes something others consume, add one bullet to `## Unreleased` in `CHANGELOG.md`", told)
def test_a_changelog_outside_the_checkout_or_on_a_page_is_named_as_the_config_spells_it(self) -> None:
config = settings.ProjectConfig("api", pathlib.Path("/c/api"), pathlib.Path("/code/api"), {"changelog": pathlib.Path("/c/api/CHANGELOG.md")})
self.assertIn("in `/c/api/CHANGELOG.md`", chunk_prompt.shipping(config))
paged = settings.ProjectConfig("api", pathlib.Path("/c/api"), pathlib.Path("/code/api"), {}, pages={"changelog": settings.Page("https://acme.atlassian.net", "7", "confluence:https://acme.atlassian.net/wiki/pages/7")})
self.assertIn("in `confluence:https://acme.atlassian.net/wiki/pages/7`", chunk_prompt.shipping(paged))
def test_a_repo_with_its_plan_in_jira_is_told_to_leave_the_changelog_as_it_is(self) -> None:
told = chunk_prompt.shipping(CONFIG)
self.assertTrue(told.startswith("The issue isn't an item of the repo's plan, so run `chunk-pr merge` without `--finish`."))
self.assertIn("leave the changelog as it is", told)
self.assertNotIn("## Unreleased", told)
def test_an_answer_the_judge_quoted_names_the_epics_description_first(self) -> None:
self.assertTrue(chunk_prompt.WORKER.answered("Q", "A", Route(Rung("off-the-ladder")), None, False).startswith("Your question: Q\n\nthe epic's description, "))
@@ -339,7 +368,7 @@ class TheFirstPrompt(unittest.TestCase):
class WindowsAcrossSessions(unittest.TestCase):
def test_lists_each_window_with_its_session_and_root(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20 ?", False, "/code/api"), ("loop-api", "item-3", True, ""))
self.assertEqual(tmux.everywhere(run), [tmux.Placed("epic-ABC-12", tmux.Listed("ABC-20", "@0", False), "/code/api"), tmux.Placed("loop-api", tmux.Listed("item-3", "@1", True), "")])
self.assertEqual(tmux.everywhere(run), [tmux.Placed("epic-ABC-12", tmux.Listed("ABC-20", "@0", False, asks=True), "/code/api"), tmux.Placed("loop-api", tmux.Listed("item-3", "@1", True), "")])
self.assertEqual(run.calls, [["list-windows", "-a", "-F", f"#{{session_name}}\t#{{window_name}}\t#{{pane_dead}}\t#{{window_id}}\t#{{{tmux.ROOT}}}"]])
def test_without_a_tmux_server_there_are_none(self) -> None:
+72
View File
@@ -0,0 +1,72 @@
import os
import pathlib
import tempfile
import unittest
from failure import Failure
from do_epic.test_scheduler import issue, Tmux
from do_epic import parked, status
from do_epic.scheduler import STATE
SINCE = 1_700_000_000
# SINCE as the status prints it.
SINCE_ON = "2023-11-14 22:13 UTC"
EPIC = "epic-ABC-12"
class TheStatusLines(unittest.TestCase):
def setUp(self) -> None:
self.home = pathlib.Path(tempfile.mkdtemp())
self.folder = self.home / STATE / "ABC-12"
def park(self, key: str, on: str) -> None:
parked.park(self.folder, parked.Parked(key, f"/code/api-{key}", "7", "s", on))
os.utime(parked.file_of(self.folder, key), (SINCE, SINCE))
def lines(self, issues: list, *windows: tuple[str, str, bool, str]) -> list[str] | Failure:
return status.lines("ABC-12", self.home, issues, Tmux(*windows))
def test_a_chunk_that_asks_says_where_to_answer_and_one_that_works_runs(self) -> None:
found = self.lines([issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api")], (EPIC, "ABC-20 ?", False, ""), (EPIC, "ABC-21", False, ""))
self.assertEqual(found, ["ABC-20 asks you: answer its question in the tmux window epic-ABC-12:ABC-20", "ABC-21 runs"])
def test_a_parked_chunk_says_what_it_awaits_and_since_when(self) -> None:
self.park("ABC-20", "an approval")
self.assertEqual(self.lines([issue("ABC-20", "repo:api")], (EPIC, "ABC-20 awaits its checks", False, "")), [f"ABC-20 waits: it is parked: its pull request #7 awaits its checks, since {SINCE_ON}"])
def test_a_parked_chunk_that_awaits_a_slot_gives_no_time_since_its_gate_began(self) -> None:
self.park("ABC-20", "an approval")
self.assertEqual(self.lines([issue("ABC-20", "repo:api")], (EPIC, "ABC-20 awaits a slot", False, "")), ["ABC-20 waits: it is parked: its worker has work again on pull request #7 and awaits a slot"])
def test_a_parked_chunk_without_a_window_says_since_when_and_how_to_start_it_again(self) -> None:
self.park("ABC-20", "an approval")
self.assertEqual(self.lines([issue("ABC-20", "repo:api")]), [f"ABC-20 waits: it is parked: its pull request #7 awaits an approval, since {SINCE_ON}, and its window stopped; run `do-epic ABC-12` to start it again"])
def test_a_stopped_chunk_and_one_not_started_say_so(self) -> None:
found = self.lines([issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api")], (EPIC, "ABC-20", True, ""))
self.assertEqual(found, ["ABC-20 waits: its window stopped; run `do-epic ABC-12` to start it again", "ABC-21 waits: it has not started; `do-epic ABC-12` starts it once the epic and its repo have room"])
def test_a_human_task_and_a_blocked_issue_say_why_they_wait(self) -> None:
found = self.lines([issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api", blockers=("ABC-20",)), issue("ABC-22", "do-epic-human")], (EPIC, "ABC-20", False, ""))
self.assertEqual(found, ["ABC-20 runs", "ABC-21 waits: ABC-20 blocks it", "ABC-22 waits: it is a human's task"])
def test_a_parked_chunk_that_cannot_be_read_is_a_failure(self) -> None:
(self.folder / parked.FOLDER).mkdir(parents=True)
(self.folder / parked.FOLDER / "ABC-20.json").write_text("{", encoding="utf-8")
self.assertIsInstance(self.lines([issue("ABC-20", "repo:api")]), Failure)
class TheTimeSinceParking(unittest.TestCase):
def test_is_the_time_of_the_chunks_file_to_the_minute(self) -> None:
folder = pathlib.Path(tempfile.mkdtemp())
chunk = parked.Parked("ABC-20", "/code/api", "7", "s", "an approval")
parked.park(folder, chunk)
os.utime(parked.file_of(folder, "ABC-20"), (SINCE, SINCE))
self.assertEqual(status.since(folder, chunk), f", since {SINCE_ON}")
def test_is_empty_where_the_chunks_file_is_gone(self) -> None:
self.assertEqual(status.since(pathlib.Path(tempfile.mkdtemp()), parked.Parked("ABC-20", "/code/api", "7", "s", "an approval")), "")
if __name__ == "__main__":
unittest.main()
+1 -1
View File
@@ -1322,7 +1322,7 @@ class TmuxCommands(unittest.TestCase):
def test_lists_the_windows_without_the_waiting_mark(self):
fake = FakeEffects(windows="item-372 ?\t0\t@1\nitem-380\t1\t@2\nno-item\t0\t@5\n")
self.assertEqual(tmux.listed("loop-proj", fake.tmux), [tmux.Listed("item-372", "@1", False), tmux.Listed("item-380", "@2", True), tmux.Listed("no-item", "@5", False)])
self.assertEqual(tmux.listed("loop-proj", fake.tmux), [tmux.Listed("item-372", "@1", False, asks=True), tmux.Listed("item-380", "@2", True), tmux.Listed("no-item", "@5", False)])
self.assertEqual(fake.tmux_calls, [["list-windows", "-t", "=loop-proj", "-F", "#{window_name}\t#{pane_dead}\t#{window_id}"]])
self.assertEqual(tmux.listed("loop-proj", FakeEffects().tmux), [])
failed = lambda args: subprocess.CompletedProcess(args, 1, "item-1\t0\t@1\n", "no server")
+2 -1
View File
@@ -220,8 +220,9 @@ class ToolProcess(unittest.TestCase):
def test_an_interrupt_reaches_the_tool_before_the_run_kills_it(self):
# A container's CLI, such as docker compose, stops its container on the SIGINT it is passed, and can't once killed.
# The loop ends by itself after about 40 seconds: under mutmut, the interrupt doesn't reach this shell, and a shell that looped for ever hung the run.
with tempfile.TemporaryDirectory() as folder:
self.interrupted(folder, "trap 'echo > stopped; exit 130' INT; echo $$ > started; while :; do sleep 0.1; done;")
self.interrupted(folder, "trap 'echo > stopped; exit 130' INT; echo $$ > started; n=0; while [ $n -lt 400 ]; do sleep 0.1; n=$((n+1)); done;")
self.assertTrue(pathlib.Path(folder, "stopped").is_file())
def test_an_interrupted_tool_that_ignores_sigint_is_killed_after_the_grace_period(self):
+1 -1
View File
@@ -150,7 +150,7 @@ Valid while `~/.claude` is a checkout of this repo.
- **Items live only in the epic.** A repo's own plan never mirrors them. Where `repo-rule.md` leaves an item's repo unclear, do-epic asks. An item without a repo is either Claude's work, done without a PR, or a human task; where the item doesn't say which, do-epic asks.
- **One item, several repos.** do-epic splits such an item when it plans it, into one Jira sub-task per repo, each labelled for its repo. The parent tracks the whole change. A person's issue is split too, with a comment for the team.
- **Ranking.** Score, then Blocked by, in one weight chain: the epic's achieve goals, then code health, then the repo's goals. Where the epic and a repo disagree, the epic wins. do-epic re-ranks Jira's backlog to match, and people's issues keep their rank.
- **Releases.** An epic item has no release. It ships into its repo's unreleased work: a bullet under `CHANGELOG.md` → `## Unreleased`, or nothing where the repo's plan is in Jira.
- **Releases.** An epic item has no release. It ships into its repo's unreleased work: where the repo publishes something others consume, a bullet under `CHANGELOG.md` → `## Unreleased`, or nothing where the repo's plan is in Jira. The issue is no item of the repo's plan, so the chunk's worker writes the bullet in its branch and runs `chunk-pr merge` without `--finish`.
- **Repos.** A repo's name is its main checkout's folder name, and a project config names that checkout. A missing checkout is cloned from the host of the epic's other repos; where unsure, do-epic asks. Unsure means the other repos don't all sit under one host and owner (the same host spelt as https and as ssh counts as two), an origin can't be read or isn't an https, ssh or scp-style address, the folder to clone into holds something else, or the clone fails. A repo no config names is cloned into the clone folder, and the human is asked to write its config. Each chunk uses its repo's model, routing, and language for commits and PRs. Jira text is in the epic's language, or else the machine's default.
- **Running.** The epic caps the chunks running at once, and each repo's `parallel-chunks` still applies. do-epic and loop-claude never run chunks in the same repo at once. The cap is a line of the epic's description, `**Max parallel chunks:** 2`, and 1 without it, as `parallel-chunks` is. A repo's `parallel-chunks` counts the chunks of every epic in its checkout. Each window is named for its issue's key, and a tmux window option, `@chunk-root`, names the folder its chunk works in, which is how loop-claude sees do-epic's chunks in a checkout. do-epic and loop-claude each hold the checkout's `starting` lock from checking the checkout's chunks to starting a window there. A chunk without a repo works in `~/.local/state/do-epic/<EPIC-KEY>/`. do-epic archives its cycles under `~/.claude/do-epic-transcripts/`, not in loop-claude's archive, whose readers parse loop-claude's prompts. An open issue runs once a label records its repo; until do-epic picks repos itself, an issue without one waits, and `do-epic <EPIC-KEY>` says so.
- **Long gates.** A chunk whose PR waits on a gate, such as a human approval, parks. It keeps its worktree, PR and session, and its state is in a file that survives a reboot. A parked chunk takes no running slot, and the items it blocks wait. do-epic polls the forge and resumes the chunk's session when the gate passes or a reviewer comments. It fixes reasonable feedback, replies to the rest, and changes the setup so review would have caught it. `do-epic <key> --status` and the tmux window names show what each chunk waits on. A gate is a pull request's pending checks or, on GitHub, the approval its branch protection requires; a draft waits on neither, since its worker has yet to mark it ready. On Gitea a draft is a pull request whose title opens with `WIP:` or `[WIP]`, Gitea's default `WORK_IN_PROGRESS_PREFIXES`. Changes a reviewer requested resume the chunk only while that review was made on the pull request's head commit and the pull request's author has not commented or replied after it; once the worker pushed or replied, the chunk parks on a new review, since GitHub keeps the decision until the reviewer reviews again. The chunk's window reads the forge once a minute, which no forge's rate limit notices. A chunk resumes only into a free slot, under the limits a starting chunk meets, and stays parked until then. `do-epic <key>` starts a parked chunk's window again whatever the limits, since the chunk stays parked. do-epic sets `CHUNK_PR_PARKS=1` for each worker, so `chunk-pr merge` fails at once where the pull request awaits an approval, and the worker's run doesn't hold a slot while the pull request waits.
+17
View File
@@ -2969,3 +2969,20 @@ Read most (opens and searches):
- `bin/do_epic/config.py` 1
- `bin/do_epic/repo_pick.py` 1
- `docs/decisions.md` 1
## Reading cost, chunk e4c3a22f3b31, finished 2026-11-19T01:15:27Z
106760 new input tokens before the first commit.
Read most (opens and searches):
- `bin/do_epic/test_main.py` 7
- `bin/do_epic/main.py` 4
- `README.md` 3
- `bin/do_epic/backend/contract.py` 3
- `bin/do_epic/backend/test_jira.py` 3
- `CHANGELOG.md` 2
- `bin/do_epic/backend/jira.py` 2
- `bin/do_epic/backend/test_fake.py` 2
- `bin/do_epic/chunk_prompt.py` 2
- `bin/plan_store/jira_epic.py` 2
-39
View File
@@ -12,13 +12,9 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 441 | 0.12.0 | | | **Move an epic's issue to done in Jira when its chunk finishes, so no finished chunk starts again and what it blocks starts.** | 2 | 2 | 2 | 4 | 3 | 1 by 6 | 2.3 |
| 416 | 0.12.0 | | | **Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.** | 1 | 1 | 1 | 1 | 2 | 1 by 5 | 2.1 |
| 420 | 0.12.0 | | | **End a worker that printed its final result and lingers, by killing the background shells it left, after a few minutes, and print each kill with its evidence on loop-claude's terminal.** | 2 | 2 | 2 | 4 | 3 | 1.5 by 6 | 2.0 |
| 412 | 0.12.0 | | | **Print each chunk of an epic, running, parked with its gate and since when, or stopped, each human task and each open interrupt with `do-epic <key> --status`, and name a parked chunk's gate in its tmux window's name.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 414 | 0.12.0 | | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 417 | 0.12.0 | | | **Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 440 | 0.12.0 | | | **End the shell that the interrupt test of `mutate-changes` starts within a minute, so a mutation run of this repo never waits on it for ever.** | 1 | 1 | 2 | 2 | 2 | 1 by 4 | 1.7 |
| 442 | 0.12.0 | | | **Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 310 | 0.12.0 | | | **Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.** | 3 | 2 | 3 | 6 | 4 | 1.4 by 3 | 0.9 |
| 422 | 0.12.0 | 420 | | **Check every 5 minutes whether a tmux window of the loop looks stuck by other signs than a lingering worker, investigate it with a headless claude, and kill only the process the investigation names.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 4 | 0.8 |
@@ -74,25 +70,6 @@
## Details
### 441. Move an epic's issue to done in Jira when its chunk finishes, so no finished chunk starts again and what it blocks starts.
A chunk that finishes leaves its issue open, since `EpicStore` has no way to close one. `scheduler.start_chunks` then counts the issue as a chunk to start: the finished chunk passes over its own issue, but the next chunk that finishes, or the next `do-epic <EPIC-KEY>`, starts it afresh, and an issue it blocks never starts. Both reviewers of item 410's chunk asked about it. Close the issue from `main.handed_on`, before it starts the next chunks, for a chunk in a repo and one without; a Jira workflow that refuses the move stops the chunk with the reason.
Touches:
- `bin/do_epic/backend/protocol.py`: `EpicStore`
- `bin/do_epic/backend/jira.py`: `JiraEpic`
- `bin/do_epic/backend/fake.py`: `MemoryEpic`
- `bin/do_epic/main.py`: `handed_on` (small)
### 416. Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.
An epic item has no release (`docs/decisions.md` → `do-epic: drives one Jira epic …`). do-epic runs `chunk-pr merge --finish` in the repo's checkout, and picks the flag by the repo's plan type.
Touches:
- `bin/do_epic/main.py`
### 420. End a worker that printed its final result and lingers, by killing the background shells it left, after a few minutes, and print each kill with its evidence on loop-claude's terminal.
On 2026-11-18 the worker of the item 402 chunk merged its pull request at about 11:47, printed its summary and then waited 95 minutes: it had started `until [ -s /tmp/merge-402.log ] && ! pgrep -f "chunk-pr merg"; do sleep 15; done` in the background, and `pgrep -f` matched the loop's own command line, so the condition never held. Its `claude -p` stayed alive ("Waiting for background work to finish"), `loop-claude` waited for it to exit, and the window's slot started no new chunk until the human found it and killed the shell.
@@ -109,15 +86,6 @@ Touches:
- `bin/loop_claude/loop/lingering_workers.py`
- `README.md`: `## Tools` (small)
### 412. Print each chunk of an epic, running, parked with its gate and since when, or stopped, each human task and each open interrupt with `do-epic <key> --status`, and name a parked chunk's gate in its tmux window's name.
A plain `do-epic <key>` resumes all of them, as after a reboot (`docs/decisions.md` → `do-epic: drives one Jira epic …`). The window suffix generalises the interrupt's " ?".
Touches:
- `bin/agent_cycle/tmux.py`: `WAITS`, `mark` (small)
- `bin/do_epic/status.py`
### 414. DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.
do-epic leaves the issue as the team filed it (`docs/decisions.md` → `do-epic: drives one Jira epic …`).
@@ -139,13 +107,6 @@ Touches:
- `bin/do-epic-e2e`
- `bin/do_epic/e2e/`
### 440. End the shell that the interrupt test of `mutate-changes` starts within a minute, so a mutation run of this repo never waits on it for ever.
Today a `mutate-changes` run on this repo can wait for ever: mutmut runs `bin/mutate_changes/test_mutate_changes.py` → `test_an_interrupt_reaches_the_tool_before_the_run_kills_it` inside its own process, where the test's SIGINT doesn't reach the `sh -c "trap … while :; do sleep 0.1; done"` it started. The shell then loops for good as mutmut's child, and mutmut waits for it. Three runs of two chunks hung this way on 2026-11-18, one for over two hours, each holding a heavy slot until someone killed the shell. Give the helper shell a deadline of its own, so it ends where no signal arrives, or leave the test out of what mutmut runs.
Touches:
- `bin/mutate_changes/test_mutate_changes.py`: `test_an_interrupt_reaches_the_tool_before_the_run_kills_it` (small)
### 442. Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.
Today `do-epic <EPIC-KEY>` starts only an issue whose label already records its repo, and prints that every other one waits (`bin/do_epic/scheduler.py` → `chunks`). `split.split`, `repo_pick.picked` and `ranking` exist and nothing calls them. Each is a headless claude call on a rung: route it on `repoless-model`'s rung of the shipped ladder. An `Unclear` pick is an interrupt on the terminal of the `do-epic <EPIC-KEY>` the human runs. A chunk that finishes starts the next chunks without planning again, so no window waits on a question.