Let do-epic --file take --blocked-by and --parent, so a change a repo ships as two pull requests gets an issue for each #638

Merged
lilleman merged 9 commits from item-455 into main 2026-11-19 17:16:10 +01:00
15 changed files with 217 additions and 58 deletions
+4
View File
@@ -1,5 +1,9 @@
# Changelog
## Unreleased
- do-epic --file takes --blocked-by <KEY> and --parent <KEY>, so a chunk files the next pull request of a change as an issue that waits for the one before it; a chunk's first prompt says when to use them.
## 0.12.0
- loop-claude asks a headless claude whether a worker that went quiet before its result is stuck, and prints the verdict and appends it to stuck-workers.md, without killing anything.
+22
View File
@@ -91,6 +91,28 @@ class EpicStoreContract:
self.assertEqual(store.file(task, "Count more.", "", ()), Failure(f"{task} is neither the epic {store.epic_key} nor one of its child issues, so nothing can be filed under it"))
self.assertEqual(len(self.issues(store)), 2)
def test_files_an_issue_blocked_by_a_child_issue_or_a_sub_task_of_the_epic(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Pin the behaviour.")
task = self.filed(store, child, "Pin it in the api.")
second = store.file(store.epic_key, "Change the behaviour.", "", (), child)
third = store.file(child, "Change it in the api.", "", (), task)
assert isinstance(second, str) and isinstance(third, str), (second, third)
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual((read[second].blockers, read[third].blockers, read[third].parent), ((child,), (task,), child))
def test_refuses_to_file_blocked_by_an_issue_outside_the_epic(self) -> None:
store = self.new_store()
for blocker in ("ZZZ-1", "not a key"):
with self.subTest(blocker=blocker):
self.assertIsInstance(store.file(store.epic_key, "Count more.", "", (), blocker), Failure)
self.assertEqual(self.issues(store), [])
def test_refuses_to_file_blocked_by_the_epic_itself(self) -> None:
store = self.new_store()
self.assertIsInstance(store.file(store.epic_key, "Count more.", "", (), store.epic_key), Failure)
self.assertEqual(self.issues(store), [])
def test_refuses_to_file_under_an_issue_outside_the_epic(self) -> None:
store = self.new_store()
for parent in ("ZZZ-1", "not a key"):
+7 -4
View File
@@ -1,7 +1,7 @@
"""An epic held in memory, for do-epic's tests, held to contract.py like every backend."""
import dataclasses
from do_epic.backend.protocol import EpicIssue, no_child, no_parent, no_words, unfit, unfit_label
from do_epic.backend.protocol import EpicIssue, no_blocker, no_child, no_parent, no_words, unfit, unfit_label
from failure import Failure
@@ -19,15 +19,18 @@ class MemoryEpic:
return Failure(self.fails)
return [issue for child in self.issues if child.parent == self.epic_key for issue in (child, *(task for task in self.issues if task.parent == child.key))]
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...]) -> str | Failure:
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...], blocked_by: str | None = None) -> str | Failure:
if self.fails:
return Failure(self.fails)
if refused := unfit(summary, labels):
return refused
if parent != self.epic_key and parent not in {issue.key for issue in self.issues if issue.parent == self.epic_key}:
children = {issue.key for issue in self.issues if issue.parent == self.epic_key}
if parent != self.epic_key and parent not in children:
return no_parent(self.epic_key, parent)
if blocked_by is not None and blocked_by not in {issue.key for issue in self.issues if issue.parent == self.epic_key or issue.parent in children}:
return no_blocker(self.epic_key, blocked_by)
key = f"{self.epic_key.rpartition('-')[0]}-{len(self.issues) + 100}"
self.issues.append(EpicIssue(key, summary, detail.strip(), tuple(sorted(labels)), None, "To Do", False, parent, by_loop=True))
self.issues.append(EpicIssue(key, summary, detail.strip(), tuple(sorted(labels)), None, "To Do", False, parent, blockers=(blocked_by,) if blocked_by else (), by_loop=True))
return key
def add_label(self, key: str, label: str) -> None | Failure:
+19 -5
View File
@@ -5,11 +5,11 @@ 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 BLOCKS, FILED_BY, ISSUE_TYPE, PROPERTY, scores
from atlassian.jira import DONE, entry_of, finishing_transition, ISSUE_KEY, MAX_PAGES, move_refusal, PERHAPS_FILED, PERHAPS_MOVED, project_of, rank_refusal, searched, SHAPE, status_category, unshaped
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 do_epic.backend.protocol import EpicIssue, no_blocker, no_child, no_parent, no_words, unfit, unfit_label
from failure import Failure
from plan_store.jira_epic import FILED_BY, ISSUE_TYPE, PROPERTY, scores
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.
@@ -57,11 +57,11 @@ class JiraEpic:
details = {each.issue.key: text.strip() for each, text in zip(described, texts)}
return [dataclasses.replace(each.issue, detail=details.get(each.issue.key, "")) for each in found]
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...]) -> str | Failure:
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...], blocked_by: str | None = None) -> str | Failure:
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
if refused := unfit(summary, labels) or self.not_a_parent(parent, authorization):
if refused := unfit(summary, labels) or self.not_a_parent(parent, authorization) or (self.not_a_blocker(blocked_by, authorization) if blocked_by is not None else None):
return refused
fields: dict[str, typing.Any] = {"project": {"key": project_of(parent)}, "parent": {"key": parent}, "summary": summary, "labels": list(labels)}
# Marks the issue as the loop's, as plan_store marks the items it files.
@@ -74,7 +74,11 @@ class JiraEpic:
if isinstance(description, Failure):
return Failure(f"cannot convert the detail to a Jira description: {description.reason}")
fields["description"] = description
created = self.http("POST", f"{self.epic.site}/rest/api/3/issue", authorization, {"fields": fields | {"issuetype": kind}, "properties": properties})
body: dict[str, typing.Any] = {"fields": fields | {"issuetype": kind}, "properties": properties}
if blocked_by is not None:
# Linked as it is created, so no issue is left filed and unblocked. The inward issue blocks the new one.
body["update"] = {"issuelinks": [{"add": {"type": {"name": BLOCKS}, "inwardIssue": {"key": blocked_by}}}]}
created = self.http("POST", f"{self.epic.site}/rest/api/3/issue", authorization, body)
if isinstance(created, Failure):
return Failure(f"cannot file the issue under {parent}: {created.reason}; {PERHAPS_FILED.format(under=parent)}")
key = created.get("key") if isinstance(created, dict) else None
@@ -184,6 +188,16 @@ class JiraEpic:
above = self.parent_of(parent, authorization, "to file under it")
return above if isinstance(above, Failure) else None if above == self.epic_key else no_parent(self.epic_key, parent)
def not_a_blocker(self, blocker: str, authorization: str) -> Failure | None:
"""Why nothing can be filed blocked by blocker; None where it is a child issue of the epic or a sub-task of one."""
above = self.parent_of(blocker, authorization, "to file blocked by it")
if isinstance(above, Failure):
return above
if above == self.epic_key:
return None
grand = None if above is None else self.parent_of(above, authorization, "to file blocked by it")
return grand if isinstance(grand, Failure) else None if grand == self.epic_key else no_blocker(self.epic_key, blocker)
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)
+7 -2
View File
@@ -51,8 +51,8 @@ class EpicStore(typing.Protocol):
def read(self) -> list[EpicIssue] | Failure:
"""Each child issue, open or done, in the tracker's rank order, each followed by its sub-tasks in theirs."""
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...]) -> str | Failure:
"""Files an open issue under parent, marked as filed by the loop, and answers its key: a child issue where parent is the epic, a sub-task where parent is one of its child issues. detail is markdown, and may be empty."""
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...], blocked_by: str | None = None) -> str | Failure:
"""Files an open issue under parent, marked as filed by the loop, and answers its key: a child issue where parent is the epic, a sub-task where parent is one of its child issues. detail is markdown, and may be empty. Where blocked_by names an issue, a child issue of the epic or a sub-task of one, the new issue is blocked by it; any other issue is refused before anything is filed."""
def add_label(self, key: str, label: str) -> None | Failure:
"""Adds label to the epic's child issue named key, leaving its other labels as they are; adding one it already has leaves the labels as they are. A sub-task, or an issue outside the epic, is refused."""
@@ -93,6 +93,11 @@ def no_parent(epic_key: str, parent: str) -> Failure:
return Failure(f"{parent} is neither the epic {epic_key} nor one of its child issues, so nothing can be filed under it")
def no_blocker(epic_key: str, blocker: str) -> Failure:
"""What every backend says when asked to file an issue blocked by blocker, which is neither a child issue of the epic nor a sub-task of one."""
return Failure(f"{blocker} is neither a child issue of the epic {epic_key} nor a sub-task of one, so it cannot block a new issue")
def no_child(epic_key: str, key: str, done_to_it: str) -> Failure:
"""What every backend says when asked to change key, which is not one of the epic's child issues; done_to_it is the past participle of what was asked, such as "labelled"."""
return Failure(f"{key} is not one of the child issues of the epic {epic_key}, so it cannot be {done_to_it}")
+9
View File
@@ -4,6 +4,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
from do_epic.backend.protocol import EpicIssue, no_blocker
from do_epic.backend.contract import EpicStoreContract
from failure import Failure
from plan_store import jira_epic
@@ -44,6 +45,14 @@ class Failing(unittest.TestCase):
self.assertEqual((store.read(), store.file("ABC-12", "Count the runs.", "", ()), store.add_label("ABC-100", "api"), store.comment("ABC-100", "Hello."), store.rank("ABC-100", "ABC-101")), (down,) * 5)
class Blocking(unittest.TestCase):
def test_refuses_a_blocker_that_is_an_issue_of_another_epic(self) -> None:
store = MemoryEpic("ABC-12")
store.issues.append(EpicIssue("ABC-50", "Elsewhere", "", (), None, "To Do", False, "ABC-99"))
self.assertEqual(store.file("ABC-12", "Count more.", "", (), "ABC-50"), no_blocker("ABC-12", "ABC-50"))
self.assertEqual(len(store.issues), 1)
class Ranking(unittest.TestCase):
def test_refuses_to_rank_beside_an_issue_that_isnt_a_child_of_the_epic(self) -> None:
store = MemoryEpic("ABC-12")
+12 -1
View File
@@ -120,7 +120,9 @@ class FakeJira:
if fields["project"] != {"key": "ABC"} or kind is None or fields["issuetype"] != kind:
return Failure("Jira answered 400: the project, parent or issue type is not valid")
key = f"ABC-{len(self.issues) + 100}"
self.issues.append({"key": key, "fields": {"summary": fields["summary"], "description": fields.get("description"), "labels": fields["labels"], "assignee": None, "status": TO_DO, "parent": {"key": parent}, "issuelinks": []}, "properties": {entry["key"]: entry["value"] for entry in body["properties"]}})
# The links Jira makes as it creates the issue: the inward issue blocks the new one, which then reads "is blocked by" it.
links = [{"id": "1", "type": {"inward": "is blocked by", "outward": "blocks"}, "inwardIssue": add["add"]["inwardIssue"]} for add in body.get("update", {}).get("issuelinks", []) if add["add"]["type"] == {"name": "Blocks"}]
self.issues.append({"key": key, "fields": {"summary": fields["summary"], "description": fields.get("description"), "labels": fields["labels"], "assignee": None, "status": TO_DO, "parent": {"key": parent}, "issuelinks": links}, "properties": {entry["key"]: entry["value"] for entry in body["properties"]}})
return {"id": "1", "key": key}
def ranked(self, body: object) -> object:
@@ -364,6 +366,15 @@ class Jira(Case):
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], [])
def test_refuses_to_file_blocked_by_a_sub_task_of_another_epics_child_or_an_issue_it_cannot_read(self) -> None:
self.jira.issues.extend([{"key": "ABC-6", "fields": {"parent": {"key": "ABC-7"}, "status": TO_DO}}, {"key": "ABC-5", "fields": {"parent": {"key": "ABC-6"}, "status": TO_DO}}])
store = self.new_store()
self.assertEqual(store.file("ABC-12", "Count more.", "", (), "ABC-5"), Failure("ABC-5 is neither a child issue of the epic ABC-12 nor a sub-task of one, so it cannot block a new issue"))
self.assertEqual(store.file("ABC-12", "Count more.", "", (), "ABC-77"), Failure(f"cannot read ABC-77 to file blocked by it: Jira answered 404 for GET {ISSUES}/ABC-77?fields=parent,status"))
self.jira.answers[("GET", f"{ISSUES}/ABC-6?fields=parent,status")] = Failure("Jira answered 503")
self.assertEqual(store.file("ABC-12", "Count more.", "", (), "ABC-5"), Failure("cannot read ABC-6 to file blocked by it: Jira answered 503"))
self.assertEqual([call for call in self.jira.calls if call[0] == "POST" and call[1] == ISSUES], [])
def test_a_label_jira_refuses_is_not_added(self) -> None:
store = self.new_store()
key = store.file("ABC-12", "Count the runs.", "", ())
+1 -1
View File
@@ -30,7 +30,7 @@ def task(issue: EpicIssue, epic: str, checkout: str | None, launcher: pathlib.Pa
"""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}. {" ".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 "")
return f"Work the Jira issue {issue.key} of the epic {epic} as one chunk, {where}. {" ".join(filter(None, [findings.instructions(epic, launcher, language, issue), shipped]))} Its summary: {issue.summary}" + (f"\n\nIts description:\n\n{issue.detail}" if issue.detail else "")
CODE_HEALTH = '~/.claude/CLAUDE.md → "Shared goal"'
+11
View File
@@ -80,6 +80,7 @@ def run(sandbox: Sandbox, epic_key: str, launcher: pathlib.Path, env: typing.Map
return report
items_filed(report, store, epic_key)
finding_filed(report, machine, store, epic_key)
follow_up_filed(report, machine, store, epic_key)
decision_recorded(report, machine, record.section, epic_key)
closed(report, machine, store, epic_key)
return report
@@ -111,6 +112,16 @@ def finding_filed(report: Report, machine: DoEpic, store: EpicStore, epic_key: s
report.check(len(found) == 1 and found[0].labels == (CLAUDE_LABEL,) and found[0].detail == "Why the finding matters." and found[0].by_loop, f"the finding is an issue of the epic with its label, its detail and the loop's mark (found {found})")
def follow_up_filed(report: Report, machine: DoEpic, store: EpicStore, epic_key: str) -> None:
"""Files a follow-up finding that waits for the first finding, and checks that Jira reads the link in that direction."""
first = next((issue.key for issue in read(report, store, "before the follow-up") if issue.summary == "Sandbox finding"), "")
done = machine.do_epic(epic_key, findings.FILE, "Sandbox follow-up finding", findings.LABEL, CLAUDE_LABEL, findings.BLOCKED_BY, first, stdin="Waits for the first finding.\n")
report.check(done.returncode == 0 and f"It is blocked by {first}." in done.stdout, f"`do-epic {findings.FILE} {findings.BLOCKED_BY}` files the follow-up and says it is blocked (exit {done.returncode}: {done.stdout.strip() or done.stderr.strip()})")
issues = read(report, store, "after the follow-up")
waiting = [issue for issue in issues if issue.summary == "Sandbox follow-up finding"]
report.check(len(waiting) == 1 and waiting[0].blockers == (first,) and not any(issue.blockers for issue in issues if issue.key == first), f"the follow-up is blocked by the first finding, not the other way round (found {[(issue.key, issue.blockers) for issue in issues if issue.key == first or issue.summary == 'Sandbox follow-up finding']})")
def decision_recorded(report: Report, machine: DoEpic, section: typing.Callable[[str], str | Failure], epic_key: str) -> None:
done = machine.do_epic(epic_key, findings.RECORD_DECISION, "Sandbox decision", stdin="The text of the decision.\n")
report.check(done.returncode == 0 and "Recorded the decision" in done.stdout, f"`do-epic {findings.RECORD_DECISION}` records the decision and says so (exit {done.returncode}: {done.stdout.strip() or done.stderr.strip()})")
+43
View File
@@ -108,6 +108,49 @@ class FindingFiledTest(unittest.TestCase):
self.assertIn("files the finding and says so", report.broke[0])
class FollowUpFiledTest(unittest.TestCase):
def store(self) -> MemoryEpic:
store = MemoryEpic(EPIC)
store.file(EPIC, "Sandbox finding", "", (CLAUDE_LABEL,))
return store
def following(self, store: MemoryEpic, flipped: bool = False) -> typing.Callable[[], subprocess.CompletedProcess[str]]:
def answer() -> subprocess.CompletedProcess[str]:
key = store.file(EPIC, "Sandbox follow-up finding", "", (CLAUDE_LABEL,), None if flipped else "SBX-100")
if flipped:
store.change("SBX-100", blockers=(str(key),))
return done(0, "Filed SBX-101 in the epic SBX-1. It is blocked by SBX-100.")
return answer
def test_holds_where_the_follow_up_is_blocked_by_the_first_finding(self) -> None:
store = self.store()
machine = Scripted([self.following(store)])
report = scenario.Report()
scenario.follow_up_filed(report, machine, store, EPIC)
self.assertEqual((report.broke, len(report.held)), ([], 2))
self.assertEqual(machine.calls, [((EPIC, findings.FILE, "Sandbox follow-up finding", findings.LABEL, CLAUDE_LABEL, findings.BLOCKED_BY, "SBX-100"), "Waits for the first finding.\n")])
def test_breaks_where_the_link_points_the_wrong_way(self) -> None:
store = self.store()
report = scenario.Report()
scenario.follow_up_filed(report, Scripted([self.following(store, flipped=True)]), store, EPIC)
self.assertEqual(len(report.broke), 1)
self.assertIn("not the other way round", report.broke[0])
def test_breaks_where_do_epic_exits_cleanly_but_says_nothing_of_the_blocker(self) -> None:
store = self.store()
report = scenario.Report()
scenario.follow_up_filed(report, Scripted([lambda: (self.following(store)(), done(0, "Filed SBX-101 in the epic SBX-1."))[1]]), store, EPIC)
self.assertEqual(len(report.broke), 1)
self.assertIn("says it is blocked", report.broke[0])
def test_breaks_where_do_epic_fails_and_files_nothing(self) -> None:
report = scenario.Report()
scenario.follow_up_filed(report, Scripted([lambda: done(1, err="no")]), self.store(), EPIC)
self.assertEqual(len(report.broke), 2)
self.assertIn("exit 1: no", report.broke[0])
class DecisionRecordedTest(unittest.TestCase):
SECTIONS: typing.ClassVar[dict[str, str | Failure]] = {"Decisions": "### Sandbox decision\nThe text of the decision.", "Goals": "1. Prove do-epic's commands work."}
+44 -21
View File
@@ -2,13 +2,14 @@
A finding about one of the epic's goals is filed in the epic, and one about a repo's goals by that repo's rules (docs/decisions.md → `do-epic: drives one Jira epic …` → "Findings"). A decision that governs the epic goes under the description's ## Decisions, where the judge of each later chunk reads it."""
import contextlib
import dataclasses
import fcntl
import pathlib
import typing
from do_epic.repo_pick import CLAUDE_LABEL, HUMAN_LABEL, of_label, REPO_PREFIX, REVIEW_LABEL
from do_epic.backend.protocol import EpicIssue, EpicStore
from do_epic.epic_record import EpicRecord
from do_epic.backend.protocol import EpicStore
from failure import Failure
from text_files.markdown_text import listed
from text_files.piped_text import piped
@@ -16,29 +17,39 @@ from text_files.piped_text import piped
# Three readers, seated as the human and as a chunk's worker, picked each spelling from four: `<EPIC-KEY> --file` over `--file <EPIC-KEY>`, `add` and `--finding`, and `--record-decision` over `--decision` and `--decide`.
FILE = "--file"
LABEL = "--label"
BLOCKED_BY = "--blocked-by"
PARENT = "--parent"
RECORD_DECISION = "--record-decision"
# The labels that say where an issue is worked, as do-epic's scheduler reads them.
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>]... [{BLOCKED_BY} <KEY>] [{PARENT} <KEY>] [<<'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.
A finding about a repo's own goals goes into that repo's plan instead.
{LABEL} is {LABELS}; without one, the next `do-epic <EPIC-KEY>` you run picks where the issue is worked.
A second {LABEL}, `{REVIEW_LABEL}`, marks the issue as a repo's release review, which the epic's finishing files.
A finding about a repo's own goals goes into that repo's plan instead.
{BLOCKED_BY} <KEY> makes the new issue wait for the issue <KEY>, which is a child issue of the epic or a sub-task of one.
{PARENT} <KEY> files the new issue as a sub-task of the child issue <KEY>.
Where a repo's rules ask for a change to ship as more than one pull request, file each step after the first with {BLOCKED_BY} set to the step before it.
{RECORD_DECISION} appends a decision that governs the epic to its description's ## Decisions, under the title, with the markdown piped in as its text."""
def instructions(epic: str, launcher: pathlib.Path, language: str) -> str:
"""What a chunk's first prompt says about filing a finding and recording a decision in the epic with the key epic. launcher is the do-epic that runs the chunk, and language the one the epic's Jira text is in."""
def instructions(epic: str, launcher: pathlib.Path, language: str, issue: EpicIssue | None = None) -> str:
"""What a chunk's first prompt says about filing a finding and recording a decision in the epic with the key epic. launcher is the do-epic that runs the chunk, and language the one the epic's Jira text is in. Where issue is the chunk's own, it also says how to file the next pull request of a change as an issue that waits for it."""
next_step = ""
if issue:
parent = f" {PARENT} {issue.parent}" if issue.parent != epic else ""
label = next((f" {LABEL} {each}" for each in issue.labels if of_label(each)), "")
next_step = f"Where the repo's rules ask for a change to ship as more than one pull request, finish only this issue's pull request, and file only the next one as an issue that waits for it, with `{launcher} {epic} {FILE} \"<summary>\" {BLOCKED_BY} {issue.key}{parent}{label}` and its detail on stdin. "
return (
f"File a finding about one of the epic's goals in the epic, with `{launcher} {epic} {FILE} \"<summary>\" {LABEL} <label>` and its detail on stdin. "
f"The label is {LABELS}; leave it out where you cannot tell, and the next `do-epic` the human runs picks it. "
"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. "
f"Record a decision that governs the epic, such as an answer the human typed, with `{launcher} {epic} {RECORD_DECISION} \"<title>\"` and its text on stdin. "
f"Write the issue and the decision in {language}, the epic's language."
f"{next_step}Write the issue and the decision in {language}, the epic's language."
)
@@ -51,35 +62,47 @@ def decisions_locked(folder: pathlib.Path) -> typing.Iterator[None]:
yield
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."""
@dataclasses.dataclass(frozen=True)
class Write:
"""What the words after the epic's key ask for: the flag, and its summary or title. A finding may also carry labels, the issue that blocks it and the child issue it is a sub-task of."""
flag: str
value: str
labels: tuple[str, ...] = ()
blocked_by: str | None = None
parent: str | None = None
def parsed(words: list[str]) -> Write | None:
"""The Write the words after the epic's key ask for. None where they aren't spelt as USAGE has them. A word that opens with `--` is no summary, title, label or key."""
if not words or words[0] not in (FILE, RECORD_DECISION):
return None
labels: list[str] = []
taken: dict[str, list[str]] = {LABEL: [], BLOCKED_BY: [], PARENT: []}
rest = words[1:]
while words[0] == FILE and LABEL in rest:
at = rest.index(LABEL)
if at + 1 >= len(rest):
return None
labels.append(rest[at + 1])
rest = rest[:at] + rest[at + 2:]
if len(rest) != 1 or any(word.startswith("--") for word in (*rest, *labels)):
for option in taken if words[0] == FILE else ():
while option in rest:
at = rest.index(option)
if at + 1 >= len(rest):
return None
taken[option].append(rest[at + 1])
rest = rest[:at] + rest[at + 2:]
if len(rest) != 1 or len(taken[BLOCKED_BY]) > 1 or len(taken[PARENT]) > 1 or any(word.startswith("--") for word in (*rest, *sum(taken.values(), []))) or any(not word.strip() for option in (BLOCKED_BY, PARENT) for word in taken[option]):
return None
return words[0], rest[0], tuple(labels)
return Write(words[0], rest[0], tuple(taken[LABEL]), *(taken[option][0] if taken[option] else None for option in (BLOCKED_BY, PARENT)))
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."""
def written(epic: str, write: Write, store: EpicStore, record: EpicRecord, stdin: typing.TextIO, folder: pathlib.Path) -> str | Failure:
"""Files the finding or records the decision, as write says, and answers the line to print. folder is the epic's, where the lock for its decisions lies."""
text = piped(stdin)
flag, value, labels = write.flag, write.value, write.labels
if flag == FILE:
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}")
if len(picks := [label for label in labels if of_label(label)]) > 1:
return Failure(f"cannot file the finding in the epic {epic}: {listed(picks, 'and')} each say who works it; write one of them")
key = store.file(epic, value, text, labels)
key = store.file(write.parent or epic, value, text, labels, write.blocked_by)
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 any(of_label(label) for label in labels) else f" It has no label that says where it is worked, so the next `do-epic {epic}` picks one: {LABELS}.")
return f"Filed {key} {f'under {write.parent} in ' if write.parent else 'in '}the epic {epic}." + (f" It is blocked by {write.blocked_by}." if write.blocked_by else "") + ("" if any(of_label(label) for label in labels) else f" It has no label that says where it is worked, so the next `do-epic {epic}` picks one: {LABELS}.")
try:
with decisions_locked(folder):
added = record.append_decision(value, text)
+2 -2
View File
@@ -143,13 +143,13 @@ def status_printed(epic: EpicRun) -> Stop:
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")
def epic_written(key: str, writes: tuple[str, str, tuple[str, ...]] | None, paths: Paths, backend: Backend, stdin: typing.TextIO) -> Stop:
def epic_written(key: str, writes: findings.Write | 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)
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)
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)
+27 -2
View File
@@ -4,6 +4,7 @@ import fcntl
import io
import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
@@ -11,8 +12,8 @@ from do_epic.test_main import DESCRIPTION, DoEpicTest
from do_epic.epic_record import EpicRecord
from failure import Failure
from loop_effects.doubles import FakeEffects
from do_epic import findings, main
from record_store.held import Held
from do_epic import main
from do_epic.backend.fake import MemoryEpic
from loop_state.paths import paths_from
@@ -90,6 +91,23 @@ class FilingAFinding(FindingsTest):
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 has no label that says where it is worked, so the next `do-epic ABC-12` picks one: `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_files_the_next_step_of_a_change_blocked_by_the_issue_before_it(self) -> None:
code, out, err, _ = self.run_with(["ABC-12", "--file", "Change it", "--label", "repo:api", "--blocked-by", "ABC-20"], "Detail.\n")
filed = self.store.issues[-1]
self.assertEqual((code, out, err), (0, f"Filed {filed.key} in the epic ABC-12. It is blocked by ABC-20.\n", ""))
self.assertEqual((filed.parent, filed.blockers, filed.labels), ("ABC-12", ("ABC-20",), ("repo:api",)))
def test_files_a_sub_task_under_a_child_issue_of_the_epic(self) -> None:
code, out, _, _ = self.run_with(["ABC-12", "--file", "--parent", "ABC-20", "Change it", "--label", "repo:api", "--blocked-by", "ABC-21"])
filed = self.store.issues[-1]
self.assertEqual((code, out, filed.parent, filed.blockers), (0, f"Filed {filed.key} under ABC-20 in the epic ABC-12. It is blocked by ABC-21.\n", "ABC-20", ("ABC-21",)))
def test_refuses_a_blocker_or_parent_outside_the_epic(self) -> None:
for argv, reason in ((["--blocked-by", "ZZZ-1"], "ZZZ-1 is neither a child issue of the epic ABC-12 nor a sub-task of one, so it cannot block a new issue"), (["--parent", "ZZZ-1"], "ZZZ-1 is neither the epic ABC-12 nor one of its child issues, so nothing can be filed under it")):
with self.subTest(argv=argv):
code, out, err, _ = self.run_with(["ABC-12", "--file", "Retry", "--label", "repo:api", *argv])
self.assertEqual((code, out, err, len(self.store.issues)), (1, "", f"cannot file the finding in the epic ABC-12: {reason}\n", 2))
def test_refuses_a_label_the_scheduler_doesnt_read(self) -> None:
for label in ("api", "repo:", "repo:a b"):
with self.subTest(label=label):
@@ -114,12 +132,19 @@ class FilingAFinding(FindingsTest):
self.assertIn("config.toml", err)
def test_prints_the_help_for_a_filing_spelt_wrong(self) -> None:
for argv in (["ABC-12", "--file"], ["ABC-12", "--file", "a", "b"], ["ABC-12", "--file", "a", "--label"], ["ABC-12", "--file", "a", "--labels", "x"], ["--file", "ABC-12", "a"], ["ABC-12", "--file", "--label", "x"], ["ABC-12", "--file", "--lable"], ["ABC-12", "--file", "a", "--label", "--x"], ["--chunk", "ABC-20", "ABC-12", "--file", "a"]):
for argv in (["ABC-12", "--file", "a", "--blocked-by", ""], ["ABC-12", "--file", "a", "--parent", " "], ["ABC-12", "--file"], ["ABC-12", "--file", "a", "b"], ["ABC-12", "--file", "a", "--label"], ["ABC-12", "--file", "a", "--labels", "x"], ["--file", "ABC-12", "a"], ["ABC-12", "--file", "--label", "x"], ["ABC-12", "--file", "--lable"], ["ABC-12", "--file", "a", "--blocked-by"], ["ABC-12", "--file", "a", "--blocked-by", "ABC-100", "--blocked-by", "ABC-101"], ["ABC-12", "--file", "a", "--parent", "ABC-100", "--parent", "ABC-101"], ["ABC-12", "--file", "a", "--parent", "--label", "x"], ["ABC-12", "--record-decision", "a", "--blocked-by", "ABC-100"], ["ABC-12", "--file", "a", "--label", "--x"], ["--chunk", "ABC-20", "ABC-12", "--file", "a"]):
with self.subTest(argv=argv):
code, out, err, _ = self.run_with(argv)
self.assertEqual((code, out, err, len(self.store.issues)), (1, "", main.HELP + "\n", 2))
class Instructions(unittest.TestCase):
def test_say_nothing_of_a_next_pull_request_without_the_chunks_issue(self) -> None:
told = findings.instructions("ABC-12", pathlib.Path("/b/do-epic"), "Swedish")
self.assertTrue(told.endswith("its text on stdin. Write the issue and the decision in Swedish, the epic's language."), told)
self.assertNotIn("--blocked-by", told)
class RecordingADecision(FindingsTest):
def test_appends_the_entry_to_the_descriptions_decisions(self) -> None:
code, out, err, fake = self.run_with(["ABC-12", "--record-decision", "Imports retry three times"], "2026-11-18, the human's answer. Valid while the client's API rate-limits.\n")
+9 -2
View File
@@ -345,12 +345,19 @@ class TheFirstPrompt(unittest.TestCase):
told = (
f"File a finding about one of the epic's goals in the epic, with `/b/do-epic ABC-12 --file \"<summary>\" --label <label>` and its detail on stdin. The label is {labels}; leave it out where you cannot tell, and the next `do-epic` the human runs picks it. "
"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."
"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."
)
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.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.removesuffix('Write the issue and the decision in Swedish, the epic\'s language.')}"))
self.assertIn("`/b/do-epic ABC-12 --file \"<summary>\" --blocked-by ABC-20`", task)
self.assertIn(" Write the issue and the decision in Swedish, the epic's language. ", task)
self.assertTrue(task.endswith(" Its summary: Do ABC-20"))
def test_a_sub_task_is_told_to_file_the_next_pull_request_under_its_parent_in_its_repo(self) -> None:
task = chunk_prompt.task(issue("ABC-23", "repo:api", parent="ABC-20"), "ABC-12", "/code/api", pathlib.Path("/b/do-epic"), "Swedish", CONFIG)
self.assertIn("--file \"<summary>\" --blocked-by ABC-23 --parent ABC-20 --label repo:api` and its detail on stdin.", task)
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"))
-18
View File
@@ -17,7 +17,6 @@
| 449 | 0.13.0 | 448 | | **Record do-epic's repo picks and sub-task summaries in the team's own spelling, such as `core-4` and `core-4: Bygg …`, as its config sets them.** | 2 | 2 | 2 | 4 | 3 | 1.6 by 6 | 2.0 |
| 453 | 0.13.0 | | | **Make the issue types that do-epic and `todo-item add` file in Jira settings, since a Jira project such as TW has no Task type.** | 2 | 2 | 1 | 3 | 2 | 1.6 by 5 | 1.8 |
| 450 | 0.13.0 | | | **Add `do-epic <EPIC-KEY> --dry-run`, which prints every Jira write planning would make and each chunk that would start, and makes none of them.** | 2 | 2 | 2 | 4 | 3 | 1.6 by 5 | 1.6 |
| 455 | 0.13.0 | | | **Let a chunk file a follow-up issue that its own issue blocks, with `do-epic --file --blocked-by` and `--parent`, so a change a repo ships as two pull requests gets an issue for each.** | 2 | 2 | 1 | 3 | 2 | 1.6 by 4 | 1.4 |
| 451 | 0.13.0 | | | **Add a project setting `merge = "human"`, under which a chunk leaves its pull request ready for a person to merge, and a do-epic chunk parks until the pull request is merged.** | 3 | 2 | 3 | 6 | 5 | 1.6 by 7 | 1.4 |
| 454 | 0.13.0 | | | **Start a do-epic chunk's issue as the team's board expects, by settings: assigned to the account do-epic works as, moved by a start transition and added to a board's active sprint.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 4 | 1.1 |
| 446 | 0.14.0 | | question | **Kill the process a stuck check names where its verdict is `stuck`, once the human says the recorded verdicts match what they would have done.** | 2 | 2 | 3 | 5 | 3 | 1.5 by 3 | 1.0 |
@@ -180,23 +179,6 @@ Touches:
- `bin/do_epic/test_planning.py`
- `README.md`: `## Tools` (small)
### 455. Let a chunk file a follow-up issue that its own issue blocks, with `do-epic --file --blocked-by` and `--parent`, so a change a repo ships as two pull requests gets an issue for each.
One epic issue is one chunk and one pull request. Some repos ship a change as two pull requests in two releases, as Timewave's legacy repos do: first a pull request that pins and isolates today's behaviour, then the one that changes it, each with its own ticket and the first blocking the second. A chunk in such a repo can't file the second issue so that it waits for the first, so the human must split those issues by hand before the run.
- `do-epic <EPIC-KEY> --file` takes `--blocked-by <KEY>`, which links the new issue as blocked by that issue of the epic, so a chunk files its second step and finishes its own.
- `--file` also files a sub-task, with `--parent <KEY>`, where the chunk's issue is a sub-task of a split item, so the second step stays under the same item.
- The chunk's instructions say when to use it: where the repo's rules ask for a change to ship as more than one pull request.
Touches:
- `bin/do_epic/findings.py`: `parsed`, `written`, `instructions`, `USAGE`, `HELP`
- `bin/do_epic/backend/protocol.py`: `EpicStore` (small)
- `bin/do_epic/backend/jira.py`: `JiraEpic.file`
- `bin/do_epic/backend/fake.py`: `MemoryEpic.file` (small)
- `bin/do_epic/test_findings.py`
- `README.md`: `## Tools` (small)
### 451. Add a project setting `merge = "human"`, under which a chunk leaves its pull request ready for a person to merge, and a do-epic chunk parks until the pull request is merged.
Every chunk merges its own pull request with `chunk-pr merge`. Some teams forbid that: Timewave's conventions say never to merge a pull request without the human's explicit go-ahead for that pull request. The loop can't run in such a team's repos without breaking the rule, and `wait-for-approval` doesn't cover it, since a reviewer's approval is not the go-ahead to merge.