Finish an epic: a finishing chunk files each repo's release review, has the human confirm each goal, and closes the epic with its summary

This commit is contained in:
2026-11-18 23:59:53 +01:00
parent 382ac99c41
commit fdb942472d
20 changed files with 514 additions and 63 deletions
+1 -1
View File
@@ -216,7 +216,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. Beside it, `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`. `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, and posts comments.
- `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. Beside it, `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.
- `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 waits for its checks (`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`.
+8
View File
@@ -140,6 +140,14 @@ class EpicStoreContract:
self.assertIsInstance(store.comment("ZZZ-1", "Hello."), Failure)
self.assertEqual([self.comments_on(store, key) for key in (child, task)], [[], []])
def test_closes_the_epic_once_its_summary_is_posted_and_refuses_a_blank_one(self) -> None:
store = self.new_store()
self.assertEqual(store.closed(), False)
self.assertIsInstance(store.close(" \n"), Failure)
self.assertEqual((store.closed(), self.comments_on(store, "ABC-12")), (False, []))
self.assertEqual(store.close("## Shipped\n\nThe import.\n"), None)
self.assertEqual((store.closed(), self.comments_on(store, "ABC-12")), (True, ["## Shipped\n\nThe import."]))
def test_reads_an_issue_without_scores_or_blockers_as_one_with_none(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
+14 -1
View File
@@ -7,11 +7,12 @@ 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 and rank fails with it as the reason. comments holds each issue's comments, by key."""
"""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."""
epic_key: str
issues: list[EpicIssue] = dataclasses.field(default_factory=list)
comments: dict[str, list[str]] = dataclasses.field(default_factory=dict)
fails: str | None = None
done: bool = False
def read(self) -> list[EpicIssue] | Failure:
if self.fails:
@@ -60,6 +61,18 @@ class MemoryEpic:
self.comments.setdefault(key, []).append(text.strip())
return None
def closed(self) -> bool | Failure:
return Failure(self.fails) if self.fails else self.done
def close(self, summary: str) -> None | Failure:
if self.fails:
return Failure(self.fails)
if refused := no_words(summary):
return refused
self.comments.setdefault(self.epic_key, []).append(summary.strip())
self.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]
+38 -3
View File
@@ -5,8 +5,8 @@ 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, ISSUE_KEY, ISSUE_TYPE, project_of, PROPERTY, rank_refusal, scores, searched
from project_config.settings import Epic
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 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
@@ -25,12 +25,13 @@ class Found:
@dataclasses.dataclass(frozen=True)
class JiraEpic:
"""The issues of a Jira epic, read and filed with the credentials env_file holds."""
"""The issues of a Jira epic, read and filed with the credentials env_file holds. finish says how the epic itself closes; None where the machine's settings don't say."""
epic: Epic
env_file: pathlib.Path
http: Http = jira_json
to_markdown: ToMarkdown = adfs_to_markdown
to_adf: ToAdf = markdown_to_adf
finish: Finish | None = None
@property
def epic_key(self) -> str:
@@ -116,6 +117,40 @@ class JiraEpic:
posted = self.http("POST", f"{self.epic.site}/rest/api/3/issue/{key}/comment", authorization, {"body": body})
return Failure(f"cannot comment on {key}: {posted.reason}") if isinstance(posted, Failure) else None
def closed(self) -> bool | Failure:
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
answered = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{self.epic_key}?fields=status", authorization, None)
if isinstance(answered, Failure):
return Failure(f"cannot read {self.epic_key}'s status: {answered.reason}")
try:
category = answered["fields"]["status"]["statusCategory"]["key"] # type: ignore[index]
except (KeyError, TypeError) as failure:
return Failure(f"{self.epic_key}'s status is not in the shape Jira Cloud's REST API version 3 documents: {failure!r}")
return bool(category == "done")
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}`, as config.py's docstring shows")
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
if refused := no_words(summary):
return refused
body = self.to_adf(summary)
if isinstance(body, Failure):
return Failure(f"cannot convert the summary to a Jira comment: {body.reason}")
# Read before the comment is posted, so that an epic that cannot move gets no summary, and a second try posts no second one.
transition = finishing_transition(self.epic.site, self.epic_key, self.finish, authorization, self.http)
if isinstance(transition, Failure):
return transition
posted = self.http("POST", f"{self.epic.site}/rest/api/3/issue/{self.epic_key}/comment", authorization, {"body": body})
if isinstance(posted, Failure):
return Failure(f"cannot comment on {self.epic_key}: {posted.reason}")
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 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:
+7
View File
@@ -64,6 +64,13 @@ class EpicStore(typing.Protocol):
"""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 closed(self) -> bool | Failure:
"""Whether the epic itself is in a status the tracker counts as done."""
def close(self, summary: str) -> None | Failure:
"""Posts summary, markdown, as a comment on the epic, then moves the epic to a status the tracker counts as done. A blank summary is refused, and so is an epic the tracker cannot move so, before anything is posted. Where the move fails after the comment is posted, the Failure says so."""
def unfit(summary: str, labels: tuple[str, ...]) -> Failure | None:
"""Why no tracker can file an issue with this summary and these labels; None where a tracker can file it."""
if not summary.strip() or "\n" in summary:
+55 -2
View File
@@ -9,7 +9,7 @@ import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
from project_config.settings import Epic
from project_config.settings import Epic, Finish
from do_epic.backend.contract import EpicStoreContract
from failure import Failure
from plan_store import jira_epic
@@ -25,6 +25,10 @@ SEARCH = f"{SITE}/rest/api/3/search/jql"
ISSUES = f"{SITE}/rest/api/3/issue"
RANK = f"{SITE}/rest/agile/1.0/issue/rank"
TO_DO = {"name": "To Do", "statusCategory": {"key": "new"}}
DONE = {"name": "Done", "statusCategory": {"key": "done"}}
TRANSITIONS = f"{ISSUES}/ABC-12/transitions"
EPIC_COMMENT = f"{ISSUES}/ABC-12/comment"
EPIC_STATUS = f"{ISSUES}/ABC-12?fields=status"
TYPES = {"issueTypes": [{"id": "10001", "name": "Task", "subtask": False}, {"id": "10003", "name": "Subtask", "subtask": True}]}
@@ -44,6 +48,8 @@ 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 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))
def __call__(self, method: str, url: str, authorization: str, body: object) -> object:
self.calls.append((method, url))
@@ -53,6 +59,18 @@ class FakeJira:
return self.answers[method, url]
if method == "GET" and url == EPIC_URL:
return {"key": "ABC-12"}
if method == "GET" and url == EPIC_STATUS:
return {"key": "ABC-12", "fields": {"status": self.epic_status}}
if method == "GET" and url == TRANSITIONS:
return {"transitions": [] if self.epic_status == DONE else [{"id": "31", "name": "Mark as done", "to": DONE}, {"id": "21", "name": "Start", "to": {"name": "In Progress", "statusCategory": {"key": "indeterminate"}}}]}
if method == "POST" and url == TRANSITIONS:
assert body == {"transition": {"id": "31"}}, body
self.epic_status = DONE
return None
if method == "POST" and url == EPIC_COMMENT:
assert isinstance(body, dict)
self.comments.setdefault("ABC-12", []).append(body["body"])
return {"id": "1"}
if method == "GET" and url == ISSUE_TYPES:
return TYPES
if method == "POST" and url == SEARCH:
@@ -127,7 +145,7 @@ class Case(unittest.TestCase):
self.jira = FakeJira()
def new_store(self) -> JiraEpic:
return JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf)
return JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf, Finish("Mark as done", "Done"))
class JiraEpicContract(Case, EpicStoreContract):
@@ -153,6 +171,41 @@ class JiraEpicContract(Case, EpicStoreContract):
class Jira(Case):
def test_closes_the_epic_by_the_transition_the_settings_name_after_the_summary(self) -> None:
self.assertEqual(self.new_store().close("Shipped."), None)
self.assertEqual(self.jira.calls[-3:], [("GET", TRANSITIONS), ("POST", EPIC_COMMENT), ("POST", TRANSITIONS)])
def test_posts_no_summary_on_an_epic_it_cannot_close(self) -> None:
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("Start", "Done"))
no_such = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf, Finish("Close", "Done"))
unconverted = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, lambda markdown: Failure("adf-codec refused it"), Finish("Mark as done", "Done"))
for store, reason in (
(unnamed, "do-epic's settings name no transition to close an epic by: set `jira-finish-transition` and `jira-finish-status`, as config.py's docstring shows"),
(wrong_status, "ABC-12's transition 'Start' leads to the status 'In Progress', not to 'Done', which `jira-finish-status` names"),
(unconverted, "cannot convert the summary to a Jira comment: adf-codec refused it"),
):
self.assertEqual(store.close("Shipped."), Failure(reason))
refused = no_such.close("Shipped.")
assert isinstance(refused, Failure)
self.assertIn("ABC-12 has no transition 'Close' from its status", refused.reason)
self.jira.answers[("GET", TRANSITIONS)] = Failure("Jira answered 503")
self.assertEqual(self.new_store().close("Shipped."), Failure("cannot read ABC-12's transitions: Jira answered 503"))
self.assertEqual((self.jira.comments, self.jira.epic_status), ({}, TO_DO))
def test_says_what_was_posted_where_the_comment_or_the_move_fails(self) -> None:
self.jira.answers[("POST", EPIC_COMMENT)] = Failure("Jira answered 503")
self.assertEqual(self.new_store().close("Shipped."), Failure("cannot comment on ABC-12: Jira answered 503"))
self.assertEqual(self.jira.epic_status, TO_DO)
del self.jira.answers[("POST", EPIC_COMMENT)]
self.jira.answers[("POST", TRANSITIONS)] = Failure("Jira answered 503")
self.assertEqual(self.new_store().close("Shipped."), Failure("posted the summary on ABC-12, but cannot move ABC-12 by 'Mark as done': Jira answered 503; close the epic in Jira rather than posting the summary again"))
def test_says_why_the_epics_status_cannot_be_read(self) -> None:
for answer, reason in ((Failure("Jira answered 503"), "cannot read ABC-12's status: Jira answered 503"), ({"fields": {}}, "ABC-12's status is not in the shape Jira Cloud's REST API version 3 documents: KeyError('status')"), (["ABC-12"], "ABC-12's status is not in the shape Jira Cloud's REST API version 3 documents: TypeError('list indices must be integers or slices, not str')")):
self.jira.answers[("GET", EPIC_STATUS)] = answer
self.assertEqual(self.new_store().closed(), Failure(reason))
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)]
+11 -4
View File
@@ -13,13 +13,15 @@ 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` say how a finished epic closes, as a project's config says it of a plan item: the name of the workflow transition, such as "Mark as done", and of the status it leads to, such as "Done". Set both or neither; without them do-epic 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
import re
from project_config.settings import anywhere, CONFIG, DO_EPIC, ENV_FILE, LANGUAGE, language_fault, lies_in, parsed, PROJECTS, SITE
from project_config.settings import anywhere, CONFIG, DO_EPIC, ENV_FILE, Finish, JIRA_FINISH, LANGUAGE, language_fault, lies_in, name_of, parsed, PROJECTS, SITE
from failure import Failure
from text_files.markdown_text import listed
from model_routing.ladder_file import read_ladder, SHIPPED
REPO_RULE = "repo-rule.md"
@@ -28,8 +30,8 @@ JIRA_URL = "jira-url"
REPOLESS_MODEL = "repoless-model"
CLONE_FOLDER = "clone-folder"
SETTINGS = (JIRA_URL, ENV_FILE, REPOLESS_MODEL)
OPTIONAL = (CLONE_FOLDER, LANGUAGE)
LISTED = f"The settings are {', '.join(SETTINGS)}, and optionally {' and '.join(OPTIONAL)}."
OPTIONAL = (CLONE_FOLDER, LANGUAGE, *JIRA_FINISH)
LISTED = f"The settings are {', '.join(SETTINGS)}, and optionally {listed(OPTIONAL, 'and')}."
@dataclasses.dataclass(frozen=True)
@@ -42,6 +44,8 @@ class DoEpicConfig:
language: str
repoless_model: str
repo_rule: str
# How a finished epic closes; None where the config doesn't say.
finish: Finish | None = None
def load(home: pathlib.Path, ladder_file: pathlib.Path = SHIPPED) -> DoEpicConfig | Failure:
@@ -73,10 +77,13 @@ def load(home: pathlib.Path, ladder_file: pathlib.Path = SHIPPED) -> DoEpicConfi
*([f"`{ENV_FILE}` is {values[ENV_FILE]!r}, inside a folder of ~/{PROJECTS} or the clone folder, which hold git checkouts"] if env_file and lies_in(env_file, *config_folders, *([clone_folder] if clone_folder else [])) else []),
*([f"`{LANGUAGE}` is {language!r}, {fault}"] if LANGUAGE in values and (fault := language_fault(language)) else []),
*([f"`{REPOLESS_MODEL}` is {model!r}, not a model on the routing ladder: {', '.join(models)}"] if REPOLESS_MODEL in values and model not in models else []),
*(f"`{name}` is {values[name]!r}, not the name Jira shows, such as \"{example}\"" for name, example in zip(JIRA_FINISH, ("Mark as done", "Done")) if name in values and not name_of(values[name])),
*(f"`{name}` is set, so `{other}` must be too" for name, other in (JIRA_FINISH, JIRA_FINISH[::-1]) if name in values and other not in values),
*([rule.reason] if isinstance(rule, Failure) else [f"`{REPO_RULE}` is blank"] if not rule.strip() else []),
]
if faults:
return Failure(f"{folder}: {'; '.join(faults)}. {LISTED}")
# Without a fault, each value above is present and of the type asserted here.
assert clone_folder and env_file and isinstance(url, str) and isinstance(model, str) and isinstance(language, str) and isinstance(rule, str)
return DoEpicConfig(folder, url, env_file, clone_folder, language, model, rule)
finish = [name for setting in JIRA_FINISH if (name := name_of(values.get(setting)))]
return DoEpicConfig(folder, url, env_file, clone_folder, language, model, rule, Finish(*finish) if len(finish) == 2 else None)
+15 -14
View File
@@ -6,7 +6,7 @@ import fcntl
import pathlib
import typing
from do_epic.repo_pick import CLAUDE_LABEL, HUMAN_LABEL, of_label, REPO_PREFIX
from do_epic.repo_pick import CLAUDE_LABEL, HUMAN_LABEL, of_label, REPO_PREFIX, REVIEW_LABEL
from do_epic.epic_record import EpicRecord
from do_epic.backend.protocol import EpicStore
from failure import Failure
@@ -20,7 +20,7 @@ RECORD_DECISION = "--record-decision"
LABELS = f"`{REPO_PREFIX}<name>` for the repo that works it, `{CLAUDE_LABEL}` for work of Claude's that changes no repo, or `{HUMAN_LABEL}` for a task of the human's"
# Under the epic's folder, the file a do-epic holds locked while it appends a decision.
DECISIONS_LOCK = "decisions.lock"
USAGE = f"""do-epic <EPIC-KEY> {FILE} <summary> [{LABEL} <label>] [<<'EOF' detail EOF]
USAGE = f"""do-epic <EPIC-KEY> {FILE} <summary> [{LABEL} <label>]... [<<'EOF' detail EOF]
do-epic <EPIC-KEY> {RECORD_DECISION} <title> <<'EOF' entry EOF"""
HELP = f"""{FILE} files a finding about one of the epic's goals as an open issue of the epic, with the markdown piped in as its description.
{LABEL} is {LABELS}; without one the issue waits until someone labels it.
@@ -49,32 +49,33 @@ def decisions_locked(folder: pathlib.Path) -> typing.Iterator[None]:
yield
def parsed(words: list[str]) -> tuple[str, str, str | None] | None:
"""What the words after the epic's key ask for: the flag, the summary or title, and the label, None without one. None where they aren't spelt as USAGE has them. A word that opens with `--` is no summary, title or label."""
def parsed(words: list[str]) -> tuple[str, str, tuple[str, ...]] | None:
"""What the words after the epic's key ask for: the flag, the summary or title, and each label. None where they aren't spelt as USAGE has them. A word that opens with `--` is no summary, title or label."""
if not words or words[0] not in (FILE, RECORD_DECISION):
return None
label: str | None = None
labels: list[str] = []
rest = words[1:]
if words[0] == FILE and LABEL in rest:
while words[0] == FILE and LABEL in rest:
at = rest.index(LABEL)
if at + 1 >= len(rest):
return None
label, rest = rest[at + 1], rest[:at] + rest[at + 2:]
if len(rest) != 1 or any(word.startswith("--") for word in (*rest, label or "")):
labels.append(rest[at + 1])
rest = rest[:at] + rest[at + 2:]
if len(rest) != 1 or any(word.startswith("--") for word in (*rest, *labels)):
return None
return words[0], rest[0], label
return words[0], rest[0], tuple(labels)
def written(epic: str, flag: str, value: str, label: str | None, store: EpicStore, record: EpicRecord, stdin: typing.TextIO, folder: pathlib.Path) -> str | Failure:
def written(epic: str, flag: str, value: str, labels: tuple[str, ...], store: EpicStore, record: EpicRecord, stdin: typing.TextIO, folder: pathlib.Path) -> str | Failure:
"""Files the finding or records the decision, as flag says, and answers the line to print. folder is the epic's, where the lock for its decisions lies."""
text = piped(stdin)
if flag == FILE:
if label and of_label(label) is None:
return Failure(f"cannot file the finding in the epic {epic}: do-epic doesn't read the label {label!r}; write {LABELS}")
key = store.file(epic, value, text, (label,) if label else ())
if unread := [label for label in labels if of_label(label) is None and label != REVIEW_LABEL]:
return Failure(f"cannot file the finding in the epic {epic}: do-epic doesn't read the label {unread[0]!r}; write {LABELS}")
key = store.file(epic, value, text, labels)
if isinstance(key, Failure):
return Failure(f"cannot file the finding in the epic {epic}: {key.reason}")
return f"Filed {key} in the epic {epic}." + ("" if label else f" It waits until someone labels it: {LABELS}.")
return f"Filed {key} in the epic {epic}." + ("" if any(of_label(label) for label in labels) else f" It waits until someone labels it: {LABELS}.")
try:
with decisions_locked(folder):
added = record.append_decision(value, text)
+88
View File
@@ -0,0 +1,88 @@
"""How an epic ends (docs/decisions.md → `do-epic: drives one Jira epic …` → "Finishing").
Once the epic holds issues and none is open, its finishing chunk runs, in a window named for the epic's key. It has no issue: `task` is its task, which follows the epic's state.
1. While a repo the epic changed lacks a release review, the chunk files one issue per such repo, labelled REVIEW_LABEL, and ends. Each runs as any issue's chunk does, and so do the issues it files.
2. With each repo reviewed, the human confirms each goal. For a goal they don't confirm, the chunk files the set of items they approve, and ends.
3. With every goal confirmed, `do-epic <EPIC-KEY> --close-epic` posts the summary on the epic and closes it.
The chunk starts again each time the epic holds no open issue, until the epic is closed. A repo is reviewed once per epic, as a release is: the issues filed after its review don't bring another."""
import pathlib
import typing
from do_epic import findings
from do_epic.chunk_prompt import DRIVER
from do_epic.backend.protocol import EpicIssue, EpicStore
from do_epic.repo_pick import recorded, Repo, REPO_PREFIX, REVIEW_LABEL
from do_epic.split import finished
from failure import Failure
from text_files.markdown_text import listed
from text_files.piped_text import piped
# Three readers, seated as the human, as a chunk's worker and as one of the client's team, picked it from four, 2-1 over `--close`, which reads as closing the run or one issue.
CLOSE = "--close-epic"
USAGE = f"do-epic <EPIC-KEY> {CLOSE} <<'EOF' summary EOF"
HELP = f"""Once every issue is done, the epic's finishing chunk runs, in a window named for the epic.
It files a release review of each repo the epic changed, as an issue labelled `{REVIEW_LABEL}`, then asks you to confirm each goal.
{CLOSE} posts the markdown piped in on the epic as its summary, then closes the epic. It refuses while an issue is open or a repo lacks its review.
It closes the epic by the transition `jira-finish-transition` names, to the status `jira-finish-status` names."""
def due(issues: list[EpicIssue]) -> bool:
"""Whether the epic's finishing comes next: it holds an issue, and none is open."""
return bool(issues) and not still_open(issues)
def still_open(issues: list[EpicIssue]) -> list[str]:
"""The key of each issue that isn't done; an item split by repo is done once its sub-tasks are."""
return [issue.key for issue in issues if not finished(issues, issue.key)]
def repo_of(issue: EpicIssue) -> str | None:
"""The name of the repo the issue's labels record; None where they record none."""
pick = recorded(issue)
return pick.name if isinstance(pick, Repo) else None
def unreviewed(issues: list[EpicIssue]) -> list[str]:
"""The repos the epic changed that have no release review, sorted. The epic changed a repo where a done issue names it, and a repo has its review once an issue labelled REVIEW_LABEL names it, open or done."""
reviewed = {repo_of(issue) for issue in issues if REVIEW_LABEL in issue.labels}
changed = {repo_of(issue) for issue in issues if issue.done and REVIEW_LABEL not in issue.labels}
return sorted(repo for repo in changed - reviewed if repo is not None)
def task(epic: str, issues: list[EpicIssue], launcher: pathlib.Path, language: str) -> str:
"""The finishing chunk's task, for the epic with the key epic as issues has it. launcher is the do-epic that runs the chunk, and language the one the epic's Jira text is in."""
opening = f"Finish the epic {epic}, which holds no open issue, as one chunk that changes no repo: work in the folder you start in."
if lacking := unreviewed(issues):
return (
f"{opening} Each repo the epic changed takes a release review first, and {listed(lacking, 'and')} {'has' if len(lacking) == 1 else 'have'} none. "
f"File one issue per such repo, with `{launcher} {epic} {findings.FILE} \"<summary>\" {findings.LABEL} {REPO_PREFIX}<name> {findings.LABEL} {REVIEW_LABEL}` and its detail on stdin, both in {language}, the epic's language. "
f"The detail asks for the release review of `~/.claude/skills/larv-review/SKILL.md` → \"Release review\" over the whole repo, as the epic's issues left it, with the epic's key in place of the release: its first commit is empty and titled `Release review of {epic}`. "
"Where filing fails and says the issue may exist, ask the human to look before you file it again. "
f"The chunk is finished once each issue is filed: {DRIVER} works them, and starts this chunk again once the epic holds no open issue."
)
return (
f"{opening} Each repo it changed has had its release review. Three steps remain, in this order.\n\n"
"1. Ask the human to confirm each goal under the description's ## Goals, one goal per question, each with the evidence of what shipped: that an achieve goal is achieved, and that no defect stands against a maintain goal. "
"A goal is met only where the human confirms it: never take one as met from the evidence alone. Don't ask again about a goal a decision in the description records as confirmed.\n"
"2. For a goal the human doesn't confirm, propose a set of items that would meet it, and ask the human to approve the set. File each item they approve. "
f"Then the chunk is finished: {DRIVER} works the items, and starts this chunk again once the epic holds no open issue.\n"
f"3. Once the human has confirmed every goal, write a summary in {language}, the epic's language, for the people who work the epic: what shipped in each repo, and each goal's evidence. "
f"Post it and close the epic with `{launcher} {epic} {CLOSE}`, the summary on stdin. That is the chunk's very last step, and the chunk is finished once it succeeds.\n\n"
f"{findings.instructions(epic, launcher, language)} Record each goal's confirmation as such a decision.\n\n"
"The epic's issues, each done:\n\n" + "\n".join(f"- {issue.key}{f' ({repo})' if (repo := repo_of(issue)) else ''}: {issue.summary}" for issue in issues)
)
def closed(epic: str, store: EpicStore, stdin: typing.TextIO) -> str | Failure:
"""Posts the summary piped in on the epic with the key epic and closes it, and answers the line to print; a Failure, with nothing posted, while the epic isn't ready to close."""
issues = store.read()
if isinstance(issues, Failure):
return Failure(f"cannot close the epic {epic}: {issues.reason}")
if waiting := still_open(issues):
return Failure(f"cannot close the epic {epic}: {listed(waiting, 'and')} {'is' if len(waiting) == 1 else 'are'} open")
if lacking := unreviewed(issues):
return Failure(f"cannot close the epic {epic}: no issue labelled {REVIEW_LABEL} reviews {listed(lacking, 'or')}")
done = store.close(piped(stdin))
return Failure(f"cannot close the epic {epic}: {done.reason}") if isinstance(done, Failure) else f"Posted the summary on the epic {epic} and closed it."
+49 -22
View File
@@ -7,7 +7,7 @@ import sys
import typing
from loop_claude.loop.chunk_start import archived_route, routed
from do_epic import chunk_prompt, findings, scheduler
from do_epic import chunk_prompt, findings, finish, scheduler
from do_epic.repo_pick import ClaudeWork, HumanTask, recorded, Repo
from loop_claude.loop.close import closed_cycle
from loop_claude.project.records import CONSEQUENCE, read_records
@@ -39,6 +39,7 @@ from agent_cycle import tmux
HELP = f"""usage: do-epic <EPIC-KEY>
{findings.USAGE}
{finish.USAGE}
Runs the chunks of one Jira epic, such as ABC-12, each in its own window of the tmux session epic-<EPIC-KEY>.
An open issue of the epic runs as a chunk once it has a label and no issue blocks it.
@@ -46,6 +47,7 @@ The label names the issue's repo, or says the work changes no repo.
As many run at once as the epic's description allows with a line such as `**Max parallel chunks:** 2`, one where it has none.
A repo takes as many chunks as its `parallel-chunks`, and none while loop-claude runs chunks in it.
{findings.HELP}
{finish.HELP}
The Jira site and its credentials are set in ~/.claude-projects/do-epic/config.toml."""
# Under the home folder, where a chunk's cycles are archived, a folder per epic. It is not loop-claude's archive, since that archive's readers, such as judge-replay and the routing figures, read loop-claude's prompts.
ARCHIVE = ".claude/do-epic-transcripts"
@@ -56,7 +58,7 @@ Backend = typing.Callable[[DoEpicConfig, str], tuple[EpicStore, EpicRecord]]
def jira_backend(config: DoEpicConfig, key: str) -> tuple[EpicStore, EpicRecord]:
epic = Epic(config.jira_url, key)
return JiraEpic(epic, config.env_file), EpicRecord(EpicDescription(epic, config.env_file))
return JiraEpic(epic, config.env_file, finish=config.finish), EpicRecord(EpicDescription(epic, config.env_file))
@dataclasses.dataclass(frozen=True)
@@ -96,9 +98,10 @@ def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher:
chunk, words = (argv[1], argv[2:]) if len(argv) >= 2 and argv[0] == scheduler.CHUNK_FLAG else (None, argv)
# 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
if (len(words) != 1 and not writes) or not ISSUE_KEY.fullmatch(words[0]) or (chunk is not None and not ISSUE_KEY.fullmatch(chunk)):
closes = chunk is None and words[1:] == [finish.CLOSE]
if (len(words) != 1 and not writes and not closes) or not ISSUE_KEY.fullmatch(words[0]) or (chunk is not None and not ISSUE_KEY.fullmatch(chunk)):
return Stop(0 if words in (["-h"], ["--help"]) else 1, HELP)
if writes:
if writes or closes:
return epic_written(words[0], writes, paths, backend, stdin)
# Before anything starts: a clone, a claude session or a tmux window.
if reason := tmux.unusable(effects.tmux, chunk_prompt.DRIVER):
@@ -111,12 +114,13 @@ def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher:
return windows_opened(epic) if chunk is None else chunk_run(chunk, epic)
def epic_written(key: str, writes: tuple[str, str, str | None], paths: Paths, backend: Backend, stdin: typing.TextIO) -> Stop:
"""Files a finding in the epic, or records a decision in its description. It needs no tmux, so a chunk's worker may run it anywhere."""
def epic_written(key: str, writes: tuple[str, str, tuple[str, ...]] | None, paths: Paths, backend: Backend, stdin: typing.TextIO) -> Stop:
"""Files a finding in the epic or records a decision in its description, as writes says; closes the epic where writes is None. It needs no tmux, so a chunk's worker may run it anywhere."""
config = load(paths.home)
if isinstance(config, Failure):
return Stop(1, config.reason)
done = findings.written(key, *writes, *backend(config, key), stdin, paths.home / scheduler.STATE / key)
store, record = backend(config, key)
done = findings.written(key, *writes, store, record, stdin, paths.home / scheduler.STATE / key) if writes else finish.closed(key, store, stdin)
return Stop(1, done.reason) if isinstance(done, Failure) else Stop(0, done)
@@ -128,6 +132,8 @@ def windows_opened(epic: EpicRun) -> Stop:
say(f"started {', '.join(started.started)} in the tmux session {epic.session}" if started.started else "started no chunk", epic.effects, stdout=True)
for wait in started.waits:
say(f"{wait.issue} waits: {wait.reason}", epic.effects, stdout=True)
if started.closed:
say(f"the epic {epic.key} is closed", epic.effects, stdout=True)
if not tmux.listed(epic.session, epic.effects.tmux):
return Stop(0, "")
if not epic.effects.on_terminal():
@@ -138,10 +144,13 @@ def windows_opened(epic: EpicRun) -> Stop:
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."""
"""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
closed = finish.due(issues) and epic.store.closed()
if isinstance(closed, Failure):
return closed
cap = epic.record.parallel_chunks()
if isinstance(cap, Failure):
return cap
@@ -155,7 +164,8 @@ def chunks_started(epic: EpicRun, own: str | None) -> scheduler.Started | Failur
seen.append(found.checkout)
return real(found.checkout), found.config.parallel_chunks
return scheduler.start_chunks(scheduler.Epic(epic.key, cap, located, epic.paths.home, epic.launcher, epic.env), issues, own, epic.effects.tmux)
started = scheduler.start_chunks(scheduler.Epic(epic.key, cap, located, epic.paths.home, epic.launcher, epic.env), issues, finish.due(issues) and not closed, own, epic.effects.tmux)
return started if isinstance(started, Failure) else dataclasses.replace(started, closed=closed)
@dataclasses.dataclass(frozen=True)
@@ -187,10 +197,7 @@ def chunk_run(key: str, epic: EpicRun) -> Stop:
pane = epic.env.get("TMUX_PANE")
if not pane:
return Stop(1, f"{scheduler.CHUNK_FLAG} is how do-epic starts itself in a tmux window; run do-epic <EPIC-KEY>")
issue = issue_read(key, epic)
if isinstance(issue, Stop):
return issue
place = chunk_root(issue, epic)
place = chunk_root(key, epic)
if isinstance(place, Stop):
return place
root, in_repo = place
@@ -223,9 +230,12 @@ def issue_read(key: str, epic: EpicRun) -> EpicIssue | Stop:
return found[0] if found else Stop(1, f"{key} is no issue of the epic {epic.key}")
def chunk_root(issue: EpicIssue, epic: EpicRun) -> tuple[str, bool] | Stop:
"""The folder the issue's chunk works in, and whether it is a repo's checkout: the epic's folder holds work without a repo. The chunk keeps both to its end, whatever the issue's labels become. The stop where the labels make the issue no chunk."""
pick = recorded(issue)
def chunk_root(key: str, epic: EpicRun) -> tuple[str, bool] | Stop:
"""The folder the chunk called key works in, and whether it is a repo's checkout: the epic's folder holds work without a repo, as the epic's finishing is. The chunk keeps both to its end, whatever its issue's labels become. The stop where the labels make the issue no chunk."""
issue = None if key == epic.key else issue_read(key, epic)
if isinstance(issue, Stop):
return issue
pick = recorded(issue) if issue else ClaudeWork()
if isinstance(pick, Failure):
return Stop(1, pick.reason)
if isinstance(pick, ClaudeWork):
@@ -233,7 +243,7 @@ def chunk_root(issue: EpicIssue, epic: EpicRun) -> tuple[str, bool] | Stop:
folder.mkdir(parents=True, exist_ok=True)
return str(folder), False
if not isinstance(pick, Repo):
return Stop(1, f"{issue.key} is no chunk: {'it is a human\'s task' if isinstance(pick, HumanTask) else 'no label names its repo'}")
return Stop(1, f"{key} is no chunk: {'it is a human\'s task' if isinstance(pick, HumanTask) else 'no label names its repo'}")
found = locate(pick.name, [], epic.config, epic.paths.home, epic.effects.git)
return Stop(1, found.reason) if isinstance(found, Failure) else (str(real(found.checkout)), True)
@@ -249,9 +259,6 @@ def handed_on(key: str, epic: EpicRun) -> Stop:
def next_cycle(loop_run: LoopRun, loop: Loop, in_repo: bool, epic: EpicRun) -> 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. 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."""
issue = issue_read(loop.window.name, epic)
if isinstance(issue, Stop):
return issue
premises = premises_read(loop.root if in_repo else None, epic)
if isinstance(premises, Failure):
return Stop(1, premises.reason)
@@ -261,6 +268,10 @@ def next_cycle(loop_run: LoopRun, loop: Loop, in_repo: bool, epic: EpicRun) -> C
records = records_read(loop.root if in_repo else None, epic)
if isinstance(records, Failure):
return Stop(1, records.reason)
work = chunk_work(loop.window.name, loop.root if in_repo else None, language or epic.config.language, epic)
if isinstance(work, Stop):
return work
task, routing = work
models = get_or_ask_models(project_key(loop.root, epic.paths.home), epic.paths, epic.env, chunk_prompt.DRIVER, epic.effects) if in_repo else repoless_models(epic)
if isinstance(models, Stop):
return models
@@ -272,9 +283,25 @@ def next_cycle(loop_run: LoopRun, loop: Loop, in_repo: bool, epic: EpicRun) -> C
return Stop(1, ladder.reason)
archive_folder = epic.paths.home / ARCHIVE / epic.key
project = ladder.project_rung(models.worker)
route = routed(loop_run.route, project, models.worker, lambda: archived_route(archive_folder, loop), lambda: RoutingIssue(issue) if "L" in issue.scores else None)
route = routed(loop_run.route, project, models.worker, lambda: archived_route(archive_folder, loop), lambda: routing)
say(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", epic.effects, stdout=True)
return Cycle(config=setup_version(epic.paths.claude_dir, epic.effects.git), effects=epic.effects, facts="", judge=judge_rung(ladder, models.judge), premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=chunk_prompt.task(issue, epic.key, loop.root if in_repo else None, epic.launcher, language or epic.config.language), prompts=chunk_prompt.WORKER, taken_in=lambda entries: TakenIn(), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
return Cycle(config=setup_version(epic.paths.claude_dir, epic.effects.git), effects=epic.effects, facts="", judge=judge_rung(ladder, models.judge), premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=task, prompts=chunk_prompt.WORKER, taken_in=lambda entries: TakenIn(), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
def chunk_work(key: str, checkout: str | None, language: str, epic: EpicRun) -> tuple[str, RoutingIssue | None] | Stop:
"""The task of the chunk called key, and the issue that routes it, None where none has scores: both from the epic's issues, read afresh. The epic's finishing has no issue, and it ends here once the epic holds an open issue again, since working that issue comes first."""
if key != epic.key:
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
issues = epic.store.read()
if isinstance(issues, Failure):
return Stop(1, issues.reason)
if not finish.due(issues):
say(f"the epic {epic.key} holds an open issue again, so its finishing waits", epic.effects, stdout=True)
return handed_on(key, epic)
return finish.task(epic.key, issues, epic.launcher, language), None
def repoless_models(epic: EpicRun) -> Models:
+2
View File
@@ -15,6 +15,8 @@ from claude_code.entries import structured_output
REPO_PREFIX = "repo:"
CLAUDE_LABEL = "do-epic-claude"
HUMAN_LABEL = "do-epic-human"
# Marks the issue that asks for a repo's release review, beside the label that names the repo (finish.py). Three readers, seated as the human, as a chunk's worker and as one of the client's team, picked it 3-0 from four: `release-review` could pass for the team's own release process.
REVIEW_LABEL = "do-epic-release-review"
# A repo's name is a folder name and part of a clone address, so claude's answer or a label a person typed must not hold a slash, a colon or a leading dot.
REPO_NAME = re.compile(r"\w[\w.-]*")
+10 -4
View File
@@ -38,9 +38,11 @@ class Waits:
@dataclasses.dataclass(frozen=True)
class Started:
# The issues whose chunks started.
# The issues whose chunks started, and the epic's key where its finishing did.
started: list[str]
waits: list[Waits]
# Whether the epic is closed, so that not even its finishing starts.
closed: bool = False
@dataclasses.dataclass(frozen=True)
@@ -106,10 +108,12 @@ def refusal(repo: str, room: RepoRoom) -> str | None:
return None
def start_chunks(epic: Epic, issues: list[EpicIssue], own: str | None, run: tmux.Tmux) -> Started | Failure:
"""Starts a do-epic in a new window for each of the epic's chunks that may start now. own is the issue of the chunk that asks, which has finished: it counts as running nowhere, and no stopped chunk starts again. Where own is None, the human's `do-epic <EPIC-KEY>` asks, and each stopped chunk starts again. A Failure says why a window could not start; those before it run."""
def start_chunks(epic: Epic, issues: list[EpicIssue], finishing: bool, own: str | None, run: tmux.Tmux) -> Started | Failure:
"""Starts a do-epic in a new window for each of the epic's chunks that may start now. Where finishing is set, no issue is open, and the chunk is the epic's finishing (finish.py), in a window named for the epic's key. own is the issue of the chunk that asks, which has finished: it counts as running nowhere, and no stopped chunk starts again. Where own is None, the human's `do-epic <EPIC-KEY>` asks, and each stopped chunk starts again. A Failure says why a window could not start; those before it run."""
session = tmux.session_name(tmux.EPIC, epic.key)
found, waits = chunks(issues)
if finishing:
found.append(Chunk(epic.key, None))
started: list[str] = []
try:
with starting(epic.folder):
@@ -134,7 +138,9 @@ def start_chunks(epic: Epic, issues: list[EpicIssue], own: str | None, run: tmux
started.append(chunk.issue)
except OSError as failure:
return Failure(f"cannot lock {failure.filename or epic.folder / LOCK}: {failure.strerror}")
return Started(started, sorted(waits, key=lambda wait: [issue.key for issue in issues].index(wait.issue)))
# The epic's finishing is no issue, and waits last.
order = [*(issue.key for issue in issues), epic.key]
return Started(started, sorted(waits, key=lambda wait: order.index(wait.issue)))
def start_chunk(epic: Epic, chunk: Chunk, own: str | None, windows: list[tmux.Listed], run: tmux.Tmux) -> list[tmux.Listed] | str | Failure:
+9
View File
@@ -7,6 +7,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.config import DoEpicConfig, load
from failure import Failure
from project_config.settings import Finish
SETTINGS = """jira-url = "https://acme.atlassian.net"
env-file = "~/jira.env"
@@ -43,6 +44,14 @@ class ConfigTest(unittest.TestCase):
assert isinstance(found, DoEpicConfig), found
self.assertEqual((found.clone_folder, found.language), (pathlib.Path("/srv/repos"), "Brazilian Portuguese"))
def test_reads_how_a_finished_epic_closes_and_wants_both_names_or_neither(self) -> None:
self.write(SETTINGS + 'jira-finish-transition = "Mark as done"\njira-finish-status = "Done"\n')
found = load(self.home)
assert isinstance(found, DoEpicConfig), found
self.assertEqual(found.finish, Finish("Mark as done", "Done"))
self.write(SETTINGS + 'jira-finish-status = " "\n')
self.assertIn('`jira-finish-status` is \' \', not the name Jira shows, such as "Done"; `jira-finish-status` is set, so `jira-finish-transition` must be too', self.failure())
def test_refuses_while_the_config_is_missing(self) -> None:
self.write(None)
self.assertIn(f"cannot read {self.folder / 'config.toml'}", self.failure())
+7
View File
@@ -83,6 +83,13 @@ class FilingAFinding(FindingsTest):
filed = self.store.issues[-1]
self.assertEqual((code, out, filed.labels, filed.detail), (0, f"Filed {filed.key} in the epic ABC-12.\n", (label,), ""))
def test_a_release_review_takes_its_label_beside_its_repos(self) -> None:
code, out, _, _ = self.run_with(["ABC-12", "--file", "Review api", "--label", "repo:api", "--label", "do-epic-release-review"])
filed = self.store.issues[-1]
self.assertEqual((code, out, filed.labels), (0, f"Filed {filed.key} in the epic ABC-12.\n", ("do-epic-release-review", "repo:api")))
code, out, _, _ = self.run_with(["ABC-12", "--file", "Review api", "--label", "do-epic-release-review"])
self.assertEqual((code, out), (0, f"Filed {self.store.issues[-1].key} in the epic ABC-12. It waits until someone labels it: `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.\n"))
def test_refuses_a_label_the_scheduler_doesnt_read(self) -> None:
for label in ("api", "repo:", "repo:a b"):
with self.subTest(label=label):
+174
View File
@@ -0,0 +1,174 @@
import contextlib
import io
import pathlib
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic import finish
from do_epic.backend.fake import MemoryEpic
from do_epic.epic_record import EpicRecord
from do_epic.test_main import Description, DoEpicTest, MODELS, UNREAD
from do_epic.test_scheduler import issue
from loop_claude.test_loop_claude import FakeEffects, judged, Worker
from loop_state.paths import paths_from
from do_epic import main
LAUNCHER = pathlib.Path("/b/do-epic")
REVIEWED = [issue("ABC-20", "repo:api", done=True), issue("ABC-21", "do-epic-claude", done=True), issue("ABC-30", "repo:api", "do-epic-release-review", done=True)]
class WhenTheFinishingIsDue(DoEpicTest):
def test_is_due_once_the_epic_holds_issues_and_none_is_open(self) -> None:
self.assertIs(finish.due([]), False)
self.assertIs(finish.due([issue("ABC-20", done=True), issue("ABC-21")]), False)
self.assertIs(finish.due([issue("ABC-20", done=True), issue("ABC-21", done=True)]), True)
def test_an_item_split_by_repo_is_done_once_its_sub_tasks_are(self) -> None:
split = [issue("ABC-20", "split-by-repo"), issue("ABC-40", "repo:api", done=True, parent="ABC-20")]
self.assertIs(finish.due(split), True)
self.assertIs(finish.due([*split, issue("ABC-41", "repo:web", parent="ABC-20")]), False)
def test_a_repo_lacks_its_review_while_a_done_issue_names_it_and_no_review_does(self) -> None:
done = [issue("ABC-20", "repo:web", done=True), issue("ABC-21", "repo:api", done=True), issue("ABC-22", "do-epic-claude", done=True), issue("ABC-23", "repo:docs")]
self.assertEqual(finish.unreviewed(done), ["api", "web"])
self.assertEqual(finish.unreviewed([*done, issue("ABC-30", "repo:api", "do-epic-release-review")]), ["web"])
self.assertEqual(finish.unreviewed([issue("ABC-30", "repo:api", "do-epic-release-review", done=True)]), [], "a review alone changes no repo")
class TheFinishingChunksTask(DoEpicTest):
def test_first_asks_for_one_review_issue_per_repo_that_lacks_one(self) -> None:
task = finish.task("ABC-12", [issue("ABC-20", "repo:api", done=True), issue("ABC-21", "repo:web", done=True)], LAUNCHER, "Swedish")
self.assertIn("Finish the epic ABC-12", task)
self.assertIn("api and web", task)
self.assertIn('`/b/do-epic ABC-12 --file "<summary>" --label repo:<name> --label do-epic-release-review`', task)
self.assertIn("`Release review of ABC-12`", task)
self.assertIn("in Swedish", task)
self.assertNotIn("--close-epic", task)
def test_then_has_the_human_confirm_each_goal_before_the_summary_and_the_closing(self) -> None:
task = finish.task("ABC-12", REVIEWED, LAUNCHER, "Swedish")
self.assertIn("Finish the epic ABC-12", task)
self.assertIn("A goal is met only where the human confirms it", task)
self.assertIn("ask the human to approve the set", task)
self.assertIn("`/b/do-epic ABC-12 --close-epic`", task)
self.assertIn("in Swedish", task)
self.assertIn("- ABC-20 (api): Do ABC-20\n- ABC-21: Do ABC-21\n- ABC-30 (api): Do ABC-30", task)
self.assertNotIn("do-epic-release-review`", task)
class ClosingTheEpic(DoEpicTest):
def setUp(self) -> None:
super().setUp()
self.issues = list(REVIEWED)
self.store = MemoryEpic("ABC-12", self.issues)
def backend(self, config: object, key: str) -> tuple[MemoryEpic, EpicRecord]:
self.store.issues = list(self.issues)
return self.store, EpicRecord(Description(self.description)) # type: ignore[arg-type]
def close(self, summary: str = "## Shipped\n\napi: the import.\n") -> tuple[int, str, str]:
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(["ABC-12", "--close-epic"], {}, paths_from(self.home), LAUNCHER, FakeEffects().effects(), self.backend, io.StringIO(summary))
return code, out.getvalue(), err.getvalue()
def test_posts_the_summary_on_the_epic_and_closes_it(self) -> None:
code, out, err = self.close()
self.assertEqual(code, 0, err)
self.assertIn("Posted the summary on the epic ABC-12 and closed it.\n", out)
self.assertEqual(self.store.comments, {"ABC-12": ["## Shipped\n\napi: the import."]})
self.assertIs(self.store.done, True)
def test_refuses_while_an_issue_is_open(self) -> None:
self.issues.append(issue("ABC-31", "repo:api"))
code, _, err = self.close()
self.assertEqual(code, 1)
self.assertIn("cannot close the epic ABC-12: ABC-31 is open\n", err)
self.assertEqual((self.store.comments, self.store.done), ({}, False))
def test_refuses_while_a_repo_the_epic_changed_lacks_its_release_review(self) -> None:
self.issues.append(issue("ABC-31", "repo:web", done=True))
code, _, err = self.close()
self.assertEqual(code, 1)
self.assertIn("cannot close the epic ABC-12: no issue labelled do-epic-release-review reviews web\n", err)
self.assertEqual((self.store.comments, self.store.done), ({}, False))
def test_refuses_a_blank_summary_and_says_why_the_tracker_refused(self) -> None:
code, _, err = self.close(" \n")
self.assertEqual(code, 1)
self.assertIn("cannot close the epic ABC-12: ", err)
self.assertIs(self.store.done, False)
self.store.fails = "Jira answered 401"
code, _, err = self.close()
self.assertEqual(code, 1)
self.assertIn("cannot close the epic ABC-12: Jira answered 401\n", err)
def test_prints_the_help_for_a_closing_spelt_wrong(self) -> None:
for argv in (["ABC-12", "--close-epic", "now"], ["--close-epic", "ABC-12"], ["--close-epic"]):
code, out, err = self.run_main(argv, FakeEffects())
self.assertEqual((code, out), (1, ""), argv)
self.assertIn("usage: do-epic <EPIC-KEY>\n", err)
self.assertIn("do-epic <EPIC-KEY> --close-epic <<'EOF' summary EOF", err)
class TheFinishingChunk(DoEpicTest):
def setUp(self) -> None:
super().setUp()
self.store = MemoryEpic("ABC-12", [])
def backend(self, config: object, key: str) -> tuple[MemoryEpic, EpicRecord]:
self.store.issues = list(self.issues)
return self.store, EpicRecord(Description(self.description)) # type: ignore[arg-type]
def started(self, fake: FakeEffects) -> list[str]:
"""The name of each window do-epic started."""
return [args[args.index("-n") + 1] for args in fake.tmux_calls if args[0] in ("new-session", "new-window")]
def test_starts_in_a_window_named_for_the_epic_once_no_issue_is_open(self) -> None:
self.issues = [issue("ABC-20", "do-epic-claude", done=True)]
fake = FakeEffects(on_terminal=False)
code, out, err = self.run_main(["ABC-12"], fake)
self.assertEqual(code, 0, err)
self.assertIn("started ABC-12 in the tmux session epic-ABC-12\n", out)
self.assertEqual(self.started(fake), ["ABC-12"])
self.assertIn(["/b/do-epic", "--chunk", "ABC-12", "ABC-12"], [args[-4:] for args in fake.tmux_calls])
def test_doesnt_start_while_an_issue_is_open_or_in_an_epic_without_issues(self) -> None:
for issues in ([issue("ABC-20", "do-epic-claude", done=True), issue("ABC-21")], []):
self.issues = issues
fake = FakeEffects(on_terminal=False)
code, out, _ = self.run_main(["ABC-12"], fake)
self.assertEqual((code, self.started(fake)), (0, []))
self.assertIn("started no chunk\n", out)
def test_doesnt_start_in_an_epic_that_is_closed(self) -> None:
self.issues = [issue("ABC-20", "do-epic-claude", done=True)]
self.store.done = True
fake = FakeEffects(on_terminal=False)
code, out, _ = self.run_main(["ABC-12"], fake)
self.assertEqual((code, self.started(fake)), (0, []))
self.assertIn("started no chunk\n", out)
self.assertIn("the epic ABC-12 is closed\n", out)
def test_its_worker_is_handed_the_finishing_task_and_runs_until_the_judge_rules_it_finished(self) -> None:
self.issues = list(REVIEWED)
worker = Worker(paths_from(self.home).claude_code_transcripts.parent)
fake = FakeEffects(streams=[worker], claude=[judged("finished")], git=UNREAD, windows="ABC-12\t0\t@9\n")
code, out, err = self.run_main(["--chunk", "ABC-12", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
self.assertIn("the chunk finished; started no other\n", out)
streamed = " ".join([what for seam, what in fake.calls if seam == "stream_claude"][0])
self.assertIn("Finish the epic ABC-12", streamed)
self.assertIn("`/b/do-epic ABC-12 --close-epic`", streamed)
self.assertIn("From the epic ABC-12's description:\n## Goals\nShip the import.", streamed)
self.assertTrue((self.home / ".local/state/do-epic/ABC-12").is_dir())
def test_ends_before_a_cycle_where_the_epic_holds_an_open_issue_again_and_starts_its_chunk(self) -> None:
self.issues = [*REVIEWED, issue("ABC-31", "do-epic-claude")]
fake = FakeEffects(windows="ABC-12\t0\t@9\n")
code, out, err = self.run_main(["--chunk", "ABC-12", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
self.assertIn("the epic ABC-12 holds an open issue again, so its finishing waits\n", out)
self.assertIn("the chunk finished; started ABC-31\n", out)
self.assertEqual([seam for seam, _ in fake.calls if seam == "stream_claude"], [])
+1 -1
View File
@@ -120,7 +120,7 @@ class ACycleOfAChunkWithoutARepo(DoEpicTest):
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())
place = main.chunk_root(self.issues[1], epic)
place = main.chunk_root("ABC-21", epic)
assert isinstance(place, tuple)
root, in_repo = place
loop = Loop(root=root, session=main.session_named("A ABC-12 do-epic ABC-21", paths.claude_code_transcripts), window=tmux.Window("epic-ABC-12", "ABC-21", "%1"), paths=paths, env=env or {}, launcher=pathlib.Path("/b/do-epic"), effects=fake.effects())
+2 -2
View File
@@ -124,7 +124,7 @@ class StartingAnEpicsChunks(unittest.TestCase):
return Epic("ABC-12", cap, locate, self.home, pathlib.Path("/bin/do-epic"), {"LOOP_CLAUDE_X": "1", "OTHER": "2"})
def start(self, epic: Epic, issues: list[EpicIssue], run: Tmux, own: str | None = None) -> Started:
found = start_chunks(epic, issues, own, run)
found = start_chunks(epic, issues, False, own, run)
assert not isinstance(found, Failure), found
return found
@@ -190,7 +190,7 @@ class StartingAnEpicsChunks(unittest.TestCase):
def test_says_which_lock_it_could_not_take(self) -> None:
(self.home / ".local/state/do-epic").mkdir(parents=True)
(self.home / ".local/state/do-epic/ABC-12").write_text("", encoding="utf-8")
found = start_chunks(self.epic(1, api=1), [issue("ABC-20", "repo:api")], None, Tmux())
found = start_chunks(self.epic(1, api=1), [issue("ABC-20", "repo:api")], False, None, Tmux())
assert isinstance(found, Failure)
self.assertRegex(found.reason, f"^cannot lock {self.home}/.local/state/do-epic/ABC-12: \\w")
+17 -7
View File
@@ -272,15 +272,11 @@ class JiraPlan:
if isinstance(raw, Failure):
return raw
key = f"{project_of(self.epic.key)}-{id_}"
url = f"{self.epic.site}/rest/api/3/issue/{key}/transitions"
offered = self.http("GET", url, authorization, None)
if isinstance(offered, Failure):
return Failure(f"cannot read {key}'s transitions: {offered.reason}")
transition = transition_of(offered, key, self.finish_by)
transition = finishing_transition(self.epic.site, key, self.finish_by, authorization, self.http)
if isinstance(transition, Failure):
return transition
moved = self.http("POST", url, authorization, {"transition": {"id": transition}})
return Failure(f"cannot move {key} by {self.finish_by.transition!r}: {moved.reason}; {PERHAPS_MOVED.format(key=key)}") if isinstance(moved, Failure) else Written(id_)
refused = move_refusal(self.epic.site, key, transition, self.finish_by, authorization, self.http)
return Failure(f"{refused}; {PERHAPS_MOVED.format(key=key)}") if refused else Written(id_)
@dataclasses.dataclass(frozen=True)
@@ -409,6 +405,20 @@ def offer_of(raw: object) -> tuple[str, str, str, str] | None:
return (id_, name, status, key) if isinstance(id_, str) and isinstance(name, str) and isinstance(status, str) and isinstance(key, str) else None
def finishing_transition(site: str, key: str, finish: Finish, authorization: str, http: Http) -> str | Failure:
"""The ID of the transition finish names, as Jira offers it now for the issue named key, an item's or an epic's; or why none of those offered finishes it."""
offered = http("GET", f"{site}/rest/api/3/issue/{key}/transitions", authorization, None)
if isinstance(offered, Failure):
return Failure(f"cannot read {key}'s transitions: {offered.reason}")
return transition_of(offered, key, finish)
def move_refusal(site: str, key: str, transition: str, finish: Finish, authorization: str, http: Http) -> str | None:
"""Moves the issue named key by the transition with the ID transition, which finishing_transition answered for finish. Why Jira did not take the move; None where it did."""
moved = http("POST", f"{site}/rest/api/3/issue/{key}/transitions", authorization, {"transition": {"id": transition}})
return f"cannot move {key} by {finish.transition!r}: {moved.reason}" if isinstance(moved, Failure) else None
def transition_of(offered: object, key: str, finish: Finish) -> str | Failure:
"""The ID of the transition finish names, among those Jira offered for the issue named key, which are the ones its present status has; or why none of them finishes the item."""
raw = offered.get("transitions") if isinstance(offered, dict) else None
+2 -2
View File
@@ -123,7 +123,7 @@ def heading_commit(release: Release, ref: str, changelog: stores.RecordStore, cw
def release_reviewed(tag: str | None, ref: str, cwd: str, titles: templates.Titles, after: Release | None = None, run: Git = git) -> bool | Failure:
"""Whether ref holds a commit titled as a release review opens, `Release review of <release>`: after tag, or anywhere where tag is None.
"""Whether ref holds a commit titled as a release review opens, `Release review of <release>`: after tag, or anywhere where tag is None. A title that names no version, such as an epic's `Release review of ABC-12` (do_epic/finish.py), reviews no release.
titles holds the project's title templates, and each commit title is read as the summary they give. after is the version a branch with no tag counts as cut, or None. Where it is given, a title counts only where its release is later than after.
"""
@@ -132,7 +132,7 @@ def release_reviewed(tag: str | None, ref: str, cwd: str, titles: templates.Titl
return log
summaries = [titles.summary(line) for line in log.splitlines()]
reviews = [summary.removeprefix("Release review of ") for summary in summaries if summary.startswith("Release review of ")]
return any(after is None or ((named := parsed(review)) is not None and named > after) for review in reviews)
return any((named := parsed(review)) is not None and (after is None or named > after) for review in reviews)
def todos_since(tag: str | None | Failure, ref: str, plan: str | None, cwd: str, run: Git = git) -> list[str] | Failure:
@@ -209,6 +209,8 @@ class ChunkItem(unittest.TestCase):
self.addCleanup(subprocess.run, ["rm", "-rf", repo])
run = lambda *args: subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@t", *args], capture_output=True, check=True, cwd=repo, env=isolated_env(), text=True)
run("init", "-q", "-b", "main")
run("commit", "-q", "--allow-empty", "-m", "Release review of ABC-12")
self.assertIs(release_standing.release_reviewed(None, "main", repo, BARE), False, "an epic's review reviews no release")
run("commit", "-q", "--allow-empty", "-m", "Release review of 0.1.0")
run("tag", "v0.1.0")
run("commit", "-q", "--allow-empty", "-m", "Ship item 4")
@@ -217,6 +219,8 @@ class ChunkItem(unittest.TestCase):
run("commit", "-q", "--allow-empty", "-m", "Answer architecture round 1: 0 🔴, 1 🟡 (0 misread); split loader")
self.assertIs(release_standing.release_reviewed("v0.1.0", "main", repo, BARE), True)
self.assertIs(release_standing.release_reviewed(None, "main", repo, BARE), True)
run("commit", "-q", "--allow-empty", "-m", "Release review of ABC-12")
self.assertIs(release_standing.release_reviewed("v0.1.0", "main", repo, BARE), True)
self.assertIsInstance(release_standing.release_reviewed("v9.9.9", "main", repo, BARE), Failure)
self.assertEqual(release_standing.default_plan(repo, "main", plan_in(repo), changelog_of(repo), BARE).cut.reviewed, True)
run("tag", "v0.2.0")