Files
claude-config/bin/do_epic/main.py
T
2026-11-20 19:32:59 +01:00

668 lines
43 KiB
Python

"""The do-epic command (docs/decisions.md → `do-epic: drives one Jira epic …`).
`do-epic <EPIC-KEY>` first plans the epic's open issues (`planning`): each that no label places is split by repo or gets its pick, and the scored issues do-epic filed are re-ranked. Then it starts each of the epic's chunks that may start now, each in a window of the epic's tmux session, as `scheduler` picks them, and puts that session on the terminal. Each window runs `do-epic --chunk <ISSUE-KEY> <EPIC-KEY>`: the cycles of one issue's chunk, run by the code that runs loop-claude's (`agent_cycle`), until the judge rules it finished. Then it starts the chunks that may start now, and its window closes. The window of a human's task runs no cycle: it waits until the task no longer holds up an issue (`human_tasks`), then does the same.
After each cycle of a chunk in a repo, the window reads what the chunk's pull request waits on (`gates`). While that is a gate only time or a person passes, the chunk is parked (`parked`): the window frees its running slot and polls the forge, and the chunk's next cycle starts once the worker has something to do and a slot is free. `do-epic <EPIC-KEY> --status` prints what each open issue does."""
import dataclasses
import pathlib
import sys
import typing
from chunk_driver.cycle_start import announced_route, cycle_of, project_routing, routing_on
from chunk_driver.claims import CHUNK_FLAG
from do_epic import chunk_prompt, dry_run, findings, finish, gates, human_tasks, parked, planning, scheduler, split, status
from chunk_driver.chunk_run import ChunkRun, closed_cycle
from do_epic.repo_pick import ClaudeWork, HumanTask, recorded, Repo
from project_config.main import located as config_located
from chunk_driver.project.records import CONSEQUENCE, read_records
from agent_cycle.run import Cycle, run_cycle
from do_epic.config import DoEpicConfig, load, PULL_MERGED_STATUS
from loop_effects.effects import Effects, say
from project_config.settings import Epic
from git_cli import epic_branch
from record_store.jira_description import EpicDescription
from do_epic.backend.protocol import EpicIssue, EpicStore
from do_epic.epic_record import EpicRecord
from failure import Failure
from agent_cycle.verdicts import Finished, TakenIn
from atlassian.jira import ISSUE_KEY
from do_epic.backend.jira import JiraEpic
from claude_code.reply import Limited
from text_files.markdown_text import listed
from do_epic.repos import locate
from chunk_driver.this_loop import Loop
from chunk_driver.project.model_choice import Models, overridden
from loop_state.paths import Paths
from chunk_driver.project.premises import read_premises
from git_cli.git_repo import record_chunk_base
from forge.commands import Run, runner
from claude_code.session import session_named
from model_routing.ladder_file import SHIPPED
from agent_cycle.stop import Stop
from agent_cycle.direct_message import tell
from project_config import templates
from agent_cycle import tmux
HELP = f"""usage: do-epic <EPIC-KEY> [--status | --dry-run]
{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>.
Before it starts chunks, do-epic <EPIC-KEY> plans each open issue that has none of these labels:
`repo:<name>` for its repo, `do-epic-claude` for work of Claude's that changes no repo, `do-epic-human` for a task of yours.
A label that `[label-repos]` in config.toml maps to a repo counts as that repo's.
Where such an issue changes several repos, it files a sub-task per repo. Otherwise it gives the issue its label, as repo-rule.md says.
An issue under which a person filed a sub-task is not planned: its sub-tasks run, each needs a label of its own, and you close the issue in Jira.
Where the rule leaves the label unclear, it asks you on the terminal. Answer with the label, or with Enter alone to leave the issue waiting.
Where two or more issues may start, it then scores each of them that holds no scores, and tells the issue's team the scores in a comment on the issue. It scores by the `Score = ...` line under the epic's ## Scoring, and moves the issues do-epic itself filed into that order on the board.
An open issue labelled `repo:<name>` or `do-epic-claude` runs as a chunk once no issue blocks it.
The issues start in order of score, highest first, whatever their order on the board. An issue it could not score starts after the others. As its chunk starts, an issue is assigned in Jira to the account do-epic works as, unless someone else holds it. Where config.toml names a start transition or a sprint board, the issue is also moved by that transition and joins that board's active sprint.
A `do-epic-human` issue that blocks another gets a window too. The window DMs you once, then waits without taking a place until you close the issue in Jira.
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.
A chunk whose worker ends its run while its pull request waits on its checks, an approval or a new review
is parked: it frees its place for the next chunk, and its window's name says what it awaits. Its worker goes
on once the checks pass, the approval comes or a reviewer comments, and a place is free; until one is, the
name says `awaits a slot`. In a repo whose config sets `merge = "human"`, a chunk never merges: once its pull
request is ready, with nothing else to wait on, the window's name says `awaits your merge`, and its worker goes on once you merged it. A parked chunk survives a reboot: run do-epic <EPIC-KEY> again to go on polling.
--status doesn't start any chunk. It prints a line per open issue: that its chunk runs or asks you a question, or why it waits, such as the gate a parked chunk awaits and since when.
--dry-run runs the planning and the scheduling against the epic as Jira holds it. It doesn't write anything to Jira, start a window or ask a question, and it doesn't start any issue in Jira as a real run's chunk does. It prints each label, sub-task, comment, score and rank move that planning would write, the order the issues would start in, each chunk that would start and why each other issue waits. A sub-task not yet filed shows a key such as ABC-new1. A question planning would ask is printed instead of asked. Planning's claude calls still run.
A repo that is missing isn't cloned. Planning then stops there, so its writes are only those made before it, and the issues of that repo wait, and a chunk of another repo may start in the place a real run gives them; a real run would clone it and go on.
{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"
# The flag that prints what each open issue does.
STATUS_FLAG = "--status"
# The flag that prints what planning and the scheduler would do, without doing it.
DRY_RUN_FLAG = "--dry-run"
# How often a parked chunk reads its pull request's gate, and a human task's window reads the epic: a person answers in hours, and each read is a few calls.
POLL_SECONDS = 60
# The store of an epic's issues and its record, for the epic with this key.
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, finish=config.finish, finding_type=config.finding_type, review_type=config.review_type, start=config.start), EpicRecord(EpicDescription(epic, config.env_file))
@dataclasses.dataclass(frozen=True)
class EpicRun:
"""What stays the same through one run of do-epic on an epic."""
key: str
config: DoEpicConfig
store: EpicStore
record: EpicRecord
paths: Paths
env: typing.Mapping[str, str]
launcher: pathlib.Path
effects: Effects
# The runner of git's and the forge's commands in a folder.
forge_at: typing.Callable[[str], Run] = runner
@property
def session(self) -> str:
return tmux.session_name(tmux.EPIC, self.key)
def main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, effects: Effects, backend: Backend = jira_backend, stdin: typing.TextIO = sys.stdin, forge_at: typing.Callable[[str], Run] = runner) -> int:
try:
stop = run(argv, env, paths, launcher, effects, backend, stdin, forge_at)
except KeyboardInterrupt:
stop = Stop(130, "")
except Exception as crash:
tell(f"do-epic {' '.join(argv)} crashed: {crash!r}", effects)
raise
if stop.reason:
say(stop.reason, effects, stdout=not stop.code)
# A chunk's stop is DMed, as loop-claude's is, so a chunk left overnight never ends unseen.
if stop.reason and argv[:1] == [CHUNK_FLAG]:
tell(f"do-epic {' '.join(argv)} stopped: {stop.reason}", effects)
return stop.code
def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, effects: Effects, backend: Backend, stdin: typing.TextIO, forge_at: typing.Callable[[str], Run]) -> Stop:
chunk, words = (argv[1], argv[2:]) if len(argv) >= 2 and argv[0] == CHUNK_FLAG else (None, argv)
status_asked = chunk is None and words[1:] == [STATUS_FLAG]
dry_run_asked = chunk is None and words[1:] == [DRY_RUN_FLAG]
words = words[:1] if status_asked or dry_run_asked else words
# What the words after the epic's key write into the epic, where they are a filing or a decision.
writes = findings.parsed(words[1:]) if chunk is None else None
closes = chunk is None and words[1:] == [finish.CLOSE]
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 or closes:
return epic_written(words[0], writes, paths, backend, stdin)
# Before anything starts: a clone, a claude session or a tmux window.
if not dry_run_asked and (reason := tmux.unusable(effects.tmux, chunk_prompt.DRIVER)):
return Stop(1, reason)
config = load(paths.home)
if isinstance(config, Failure):
return Stop(1, config.reason)
store, record = backend(config, words[0])
epic = EpicRun(words[0], config, store, record, paths, env, launcher, effects, forge_at)
if dry_run_asked:
return dry_run_printed(epic)
if status_asked:
return status_printed(epic)
return windows_opened(epic) if chunk is None else chunk_run(chunk, epic)
def status_printed(epic: EpicRun) -> Stop:
"""What `do-epic <EPIC-KEY> --status` does: prints a line per open issue, and doesn't start anything."""
issues = epic.store.read()
# Reading a repo's goals may clone it, which a status doesn't do.
reading = dataclasses.replace(epic, effects=dataclasses.replace(epic.effects, git=dry_run.without_clones(epic.effects.git)))
order = issues if isinstance(issues, Failure) else planning.start_order(planned_epic(reading), issues)
# Where the issues cannot be put in order of score, they start in the backlog's order, as a run says.
lines = issues if isinstance(issues, Failure) else status.lines(epic.key, epic.paths.home, issues, epic.config.label_repos, epic.config.unblocking, epic.effects.tmux, () if isinstance(order, Failure) else tuple(order))
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: 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, config.label_repos, record, stdin, paths.home / scheduler.STATE / key) if writes else finish.closed(key, store, config.label_repos, stdin, config.pull_merged_status)
return Stop(1, done.reason) if isinstance(done, Failure) else Stop(0, done)
def windows_opened(epic: EpicRun) -> Stop:
"""What the do-epic the human runs does: plans the open issues (`planning`), starts each chunk that may start now, says why each other open issue waits, then puts the epic's session on the terminal until the human detaches."""
started = planned_and_started(epic)
if isinstance(started, Stop):
return started
chunks_said(epic, started, "started", f" in the tmux session {epic.session}")
if not tmux.listed(epic.session, epic.effects.tmux):
return Stop(0, "")
if not epic.effects.on_terminal():
say(f"not on a terminal; see the chunks with `tmux attach -t ={epic.session}`", epic.effects, stdout=True)
return Stop(0, "")
shown = tmux.show(epic.session, "TMUX" in epic.env)
return Stop(1, f"`tmux {' '.join(shown)}` failed; the chunks go on in the tmux session") if epic.effects.tmux_on_terminal(shown) else Stop(0, "")
def planned_and_started(epic: EpicRun, dry: bool = False) -> scheduler.Started | Stop:
"""Plans the epic's open issues, then starts each chunk that may start now. Where dry, a planning that stops early says so on stdout, and that the writes shown are those made before it stopped."""
read = epic.store.read()
if isinstance(read, Failure):
return Stop(1, read.reason)
issues, stopped = planning.planned(planned_epic(epic), read)
if isinstance(stopped, Limited):
return Stop(1, f"the epic is not planned, so no chunk started: {stopped.said}")
if stopped is not None:
# One issue or repo that cannot be planned holds back only itself: each chunk that may start still does.
say(f"the epic {epic.key} is not planned in full" + (", so the writes below are those it made before it stopped" if dry else "") + f": {stopped.reason}", epic.effects, stdout=dry)
started = chunks_started(epic, issues, None, stopped.reason if stopped else "")
return Stop(1, started.reason) if isinstance(started, Failure) else started
def chunks_said(epic: EpicRun, started: scheduler.Started, verb: str, where: str) -> None:
"""Prints `<verb> <the chunks>` and where, or `<verb> no chunk`, then why each other open issue waits, and that the epic is closed where it is."""
say(f"{verb} {', '.join(started.started)}{where}" if started.started else f"{verb} 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)
def dry_run_printed(epic: EpicRun) -> Stop:
"""What `do-epic <EPIC-KEY> --dry-run` does: plans and starts as `windows_opened` does, on a copy of the epic, a tmux that starts no window and a git that clones no repo, then prints each Jira write planning made on the copy, the scores among them, the order the scored issues would start in, each chunk that would start and why each other issue waits. It doesn't put the session on the terminal or ask a question."""
dry = dry_run.seeded(epic.store)
if isinstance(dry, Failure):
return Stop(1, dry.reason)
effects = dataclasses.replace(epic.effects, tmux=dry_run.recording(epic.effects.tmux), git=dry_run.without_clones(epic.effects.git), on_terminal=lambda: False)
rehearsal = dataclasses.replace(epic, store=dry, effects=effects)
say("dry run: nothing is written to Jira and no window starts, so a line below that says an issue is labelled, split or scored shows what a real run would do. A real run would also start in Jira the issue of each chunk it starts: assign it and, where config.toml says so, move it and add it to a sprint", effects, stdout=True)
started = planned_and_started(rehearsal, dry=True)
writes = "".join("\n- " + write.replace("\n", "\n ") for write in dry.writes)
say(f"planning would write to Jira:{writes}" if dry.writes else "planning wouldn't write anything to Jira", effects, stdout=True)
if isinstance(started, Stop):
return started
chunks_said(rehearsal, started, "would start", "")
return Stop(0, "")
def chunks_started(epic: EpicRun, issues: list[EpicIssue], own: str | None, told: str = "") -> scheduler.Started | Failure:
"""scheduler.start_chunks on the epic's issues, as read, in order of score, and its cap, read afresh; own is the issue of the chunk that asks, and told is the reason the planning just gave for stopping, which isn't said twice. Where no issue is open, the chunk to start is the epic's finishing, unless the epic is closed."""
due = finish.due(finish.landed(issues, epic.config.pull_merged_status))
closed = due and epic.store.closed()
if isinstance(closed, Failure):
return closed
order = planning.start_order(planned_epic(epic), issues)
if isinstance(order, Failure):
say(f"the issues of {epic.key} start in Jira's backlog order, since they cannot be put in order of score" + ("" if order.reason == told else f": {order.reason}"), epic.effects, stdout=True)
elif len(order) > 1:
say(f"by score, the issues of {epic.key} start in the order {', '.join(order)}", epic.effects, stdout=True)
scheduled = scheduled_epic(epic, () if isinstance(order, Failure) else tuple(order))
if isinstance(scheduled, Failure):
return scheduled
started = scheduler.start_chunks(scheduled, issues, due and not closed, own, epic.effects.tmux)
return started if isinstance(started, Failure) else dataclasses.replace(started, closed=closed)
def planned_epic(epic: EpicRun) -> planning.Planned:
"""The epic as planning reads and writes it."""
return planning.Planned(epic.key, epic.config, epic.store, epic.record, epic.paths.home, epic.effects)
def scheduled_epic(epic: EpicRun, order: tuple[str, ...]) -> scheduler.Epic | Failure:
"""The epic as scheduler limits its chunks: with its cap, read afresh, each repo's checkout, and the order its scored issues start in."""
cap = epic.record.parallel_chunks()
if isinstance(cap, Failure):
return cap
# The checkouts located so far, from whose remotes repos.locate tells where to clone a repo that is missing.
seen: list[pathlib.Path] = []
def located(name: str) -> tuple[pathlib.Path, int] | Failure:
found = locate(name, [checkout for checkout in seen], epic.config, epic.paths.home, epic.effects.git)
if isinstance(found, Failure):
return found
seen.append(found.checkout)
return real(found.checkout), found.config.parallel_chunks
return scheduler.Epic(epic.key, cap, located, epic.paths.home, epic.launcher, epic.env, epic.config.label_repos, order, epic.config.unblocking)
@dataclasses.dataclass(frozen=True)
class RoutingIssue:
"""An issue as what routes its chunk (agent_cycle.routing.Scored)."""
issue: EpicIssue
@property
def id(self) -> int:
"""The number in the issue's key. A Route keeps a number, and one chunk's archive holds one issue, so the number tells the issue without its project's letters."""
return int(self.issue.key.rpartition("-")[2])
@property
def likelihood(self) -> int:
return self.issue.scores["L"]
@property
def escape_and_impact(self) -> int:
return self.issue.scores.get("E", 0) + self.issue.scores.get("I", 0)
def real(checkout: pathlib.Path) -> pathlib.Path:
"""The checkout as loop-claude names it, which is as git does: through no symlink or `..`. Each keys the checkout's lock and its chunks by that path, so a project config that spells it another way hides neither from the other."""
return checkout.resolve()
def chunk_run(key: str, epic: EpicRun) -> Stop:
"""Runs the cycles of the chunk of the issue called key until one stops the loop, or the judge rules the chunk finished. For a human's task it runs no cycle: it waits until the task no longer holds up an issue (`human_tasks.awaited`), then starts the next chunks. A chunk in a repo parks after each cycle that leaves its pull request waiting on a gate, and before its first where it was parked when its window last ended, as at a reboot."""
pane = epic.env.get("TMUX_PANE")
if not pane:
return Stop(1, f"{CHUNK_FLAG} is how do-epic starts itself in a tmux window; run do-epic <EPIC-KEY>")
# None for the epic's finishing, which is no issue.
issue = None if key == epic.key else issue_read(key, epic)
if isinstance(issue, Stop):
return issue
if issue and isinstance(recorded(issue, epic.config.label_repos), HumanTask):
human_tasks.awaited(issue, epic.key, epic.store, epic.config.label_repos, epic.config.unblocking, tmux.Window(epic.session, key, pane), POLL_SECONDS, epic.paths.home, epic.effects)
return handed_on(key, epic, humans=True)
place = chunk_root(key, issue, epic)
if isinstance(place, Stop):
return place
root, repo = place
if unmade := folder_made(root):
return Stop(1, unmade.reason)
if issue:
issue_started(key, epic)
# The epic's working branch the chunk merges into; None where its repo keeps none, as for a chunk without a repo.
based = epic_based(key, root, epic) if repo is not None else None
if isinstance(based, Stop):
return based
session = session_named(f"A {epic.key} do-epic {key}", epic.paths.claude_code_transcripts)
loop = Loop(root=root, session=session, window=tmux.Window(epic.session, key, pane), paths=epic.paths, env=epic.env, launcher=epic.launcher, effects=epic.effects)
run = ChunkRun()
# What a chunk that was parked is told as it resumes; empty for a chunk that wasn't.
news = parked_through(repo, loop, epic, told=None, finished=False) if repo is not None else ""
while True:
if isinstance(news, Stop):
return news
run = dataclasses.replace(run, cycle_number=run.cycle_number + 1)
cycle = next_cycle(run, loop, repo is not None, epic, news)
if isinstance(cycle, Stop):
return cycle
if isinstance(cycle, EpicReopened):
say(f"the epic {epic.key} holds an open issue again, so its finishing chunk ends until none is open", epic.effects, stdout=True)
return handed_on(key, epic)
concluded = run_cycle(cycle)
if isinstance(concluded, Stop):
return concluded
closed = closed_cycle(run, cycle.task, cycle.project, concluded, cycle.project_archive, chunk_prompt.DRIVER, loop)
if isinstance(closed, Stop):
return closed
run = closed
news = parked_through(repo, loop, epic, told=news, finished=isinstance(concluded.verdict, Finished)) if repo is not None else ""
# A chunk that was parked has work again, whatever the judge ruled before its pull request passed the gate.
if isinstance(concluded.verdict, Finished) and news == "":
return handed_on(key, epic, repo is not None, to_epic_branch=based is not None)
def epic_based(key: str, root: str, epic: EpicRun) -> str | None | Stop:
"""Readies the epic's working branch for the chunk called key, whose repo is checked out at root: the branch, or None where the repo's config sets no `epic-branch`. It makes the branch on origin, or brings it level with the default branch, and records it as the base of the chunk's branch. A default branch that doesn't merge into it cleanly stops the loop, since a person resolves the conflict (docs/decisions.md → `epic-branch: an epic's chunks branch off and merge into a working branch …`)."""
config = config_located(root, epic.paths.home)
if isinstance(config, Failure):
return Stop(1, config.reason)
if config.epic_branch is None:
return None
branch = templates.epic_branch(config.epic_branch, epic.key)
default = epic.effects.git("symbolic-ref", "--short", "refs/remotes/origin/HEAD", cwd=root)
level = default if isinstance(default, Failure) else epic_branch.levelled(branch, default.strip(), cwd=root, run=epic.effects.git)
readied = level if isinstance(level, Failure) else record_chunk_base(key, branch, cwd=root, run=epic.effects.git)
if isinstance(readied, Failure):
return Stop(1, f"cannot ready the epic's working branch {branch} in {root} for {key}: {readied.reason}; once that is settled, run `do-epic {epic.key}` to start the chunk again")
say(f"{str(level).rstrip('.')}; {key}'s pull request goes into {branch}", epic.effects, stdout=True)
return branch
def issue_started(key: str, epic: EpicRun) -> None:
"""Starts the issue called key in the tracker, and says who else holds it, or why it didn't start. The chunk runs either way: the tracker shows the team the work, and the work doesn't read it."""
other = epic.store.start_issue(key)
if isinstance(other, Failure):
say(f"not every step that starts {key} in the tracker was made, and its chunk runs all the same: {other.reason}", epic.effects, stdout=True)
elif other:
say(f"{key} stays assigned to {other}", epic.effects, stdout=True)
def parked_through(repo: str, loop: Loop, epic: EpicRun, told: str | None, finished: bool) -> str | Stop:
"""Keeps the chunk in loop's window parked. Its work is in the repo called repo. It stays parked for as long as its pull request waits on a gate, and returns once its worker has something to do: what to tell that worker, or empty where the chunk was never parked. told is the news its last cycle's worker got, None where the window just started, and finished says the judge ruled the chunk finished. A window that just started parks the chunk only if its file says so: the forge isn't read for a chunk that starts afresh.
Where a person merges, a worker ends its run with the pull request open, so the judge may rule the chunk finished before it is. For such a finished chunk, a gate that cannot be read is read again until it can, and a pull request no longer open, in a worktree that still stands, is news the worker hasn't been told: the worker removes the worktree. A pull request that doesn't merge into its base is news after every cycle that leaves it so: the worker levels the branch.
A chunk parks in three steps: its file is written, its window is shown as parked, and the epic's next chunks start in the slot it frees. It resumes in the reverse order: `scheduler.resume` gives it a running slot, then its file is removed. So a window that ends in between finds the chunk parked when it starts again.
"""
key, folder = loop.window.name, epic.paths.home / scheduler.STATE / epic.key
recorded_as = parked.parked_chunks(folder)
if isinstance(recorded_as, Failure):
return Stop(1, recorded_as.reason)
config = config_located(loop.root, epic.paths.home)
if isinstance(config, Failure):
return Stop(1, config.reason)
# A pull request into an epic's working branch merges without a person, whatever `merge` says.
poll = Poll(key, repo, config.merge == "human" and config.epic_branch is None, folder, loop, epic)
if key in recorded_as:
return resumed_news(poll, recorded_as[key].on, shown=None)
entered = None if told is None else poll.first_gate(again=finished)
if not isinstance(entered, gates.Gate):
if isinstance(entered, Failure):
say(f"cannot tell whether the chunk's pull request waits on a gate, so the chunk isn't parked: {entered.reason}", epic.effects, stdout=True)
if not (finished and poll.by_human and isinstance(entered, (gates.Unopened, gates.Unmergeable))):
return ""
if isinstance(entered, gates.Unmergeable):
return f"{chunk_prompt.DRIVER} keeps the chunk open while its pull request doesn't merge into its base: {entered.news}."
uncleaned = f"{chunk_prompt.DRIVER} keeps the chunk open while its worktree stands: {entered.news}."
return "" if uncleaned in (told or "") else uncleaned
if failed := poll.record(entered):
return Stop(1, failed.reason)
if config.epic_branch is not None and (status := epic.config.pull_open_status):
# The team's automation moves an issue only from a pull request into the default branch.
if isinstance(moved := epic.store.move_issue(key, status), Failure):
say(f"{key} did not move to {status!r} though its pull request is open: {moved.reason}", epic.effects, stdout=True)
tmux.park(loop.window, entered.on, epic.effects.tmux)
# Once the window shows as parked, so the chunks that start count it as running nowhere.
issues = epic.store.read()
started = issues if isinstance(issues, Failure) else chunks_started(epic, issues, key)
say(f"could not start the next chunk: {started.reason}" if isinstance(started, Failure) else f"started {', '.join(started.started) or 'no other'}", epic.effects, stdout=True)
epic.effects.sleep(POLL_SECONDS)
return resumed_news(poll, entered.on, shown=entered.on)
@dataclasses.dataclass(frozen=True)
class Poll:
"""What each read of a parked chunk's gate needs: the chunk's key, the repo its work is in, whether a person merges its pull request, the folder of the epic's parked chunks, and the chunk's loop and epic."""
key: str
repo: str
by_human: bool
folder: pathlib.Path
loop: Loop
epic: EpicRun
def gate(self) -> gates.Gate | gates.Open | Failure:
return gates.gate(self.key, self.loop.root, self.epic.forge_at, self.by_human)
def first_gate(self, again: bool) -> gates.Gate | gates.Open | Failure:
"""The gate as a cycle ends. Where again holds and a person merges, one that cannot be read is read again every POLL_SECONDS until it can."""
now = self.gate()
if not again:
return now
if self.by_human and isinstance(now, Failure):
say(f"cannot read the gate of a pull request a person merges: {now.reason}; trying again every {POLL_SECONDS} seconds", self.epic.effects, stdout=True)
while self.by_human and isinstance(now, Failure):
self.epic.effects.sleep(POLL_SECONDS)
now = self.gate()
return now
def record(self, gate: gates.Gate) -> Failure | None:
"""Writes the chunk's file as parked on gate, and says so."""
failed = parked.park(self.folder, parked.Parked(self.key, gate.worktree, gate.pull, str(self.loop.session.id), gate.on))
if failed is None:
say(f"parked: pull request #{gate.pull} awaits {gate.on}", self.epic.effects, stdout=True)
return failed
def resumed_news(poll: Poll, on: str, shown: str | None) -> str | Stop:
"""Reads the gate of the parked chunk every POLL_SECONDS until its worker has something to do and a running slot is free, then removes its file: what to tell that worker. on is the gate the chunk's file says it is parked on, and shown what its window's name says it awaits, None where nothing yet. A gate that cannot be read leaves the chunk parked as it was."""
# The last reason said for staying parked.
said = None
while True:
now = poll.gate()
if isinstance(now, gates.Gate):
awaits, stays = now.on, None
if now.on != on:
if failed := poll.record(now):
return Stop(1, failed.reason)
on = now.on
elif isinstance(now, Failure):
awaits, stays = shown or on, f"cannot read the gate: {now.reason}"
else:
full = resumed(poll.repo, poll.loop, poll.epic)
if full is None:
failed = parked.unpark(poll.folder, poll.key)
return Stop(1, failed.reason) if failed is not None else f"{DRIVER_PARKED} its pull request awaited {"a person's merge" if on == gates.MERGE else on}. It resumes now: {now.news}."
awaits, stays = parked.SLOT, f"{now.news}, but the chunk stays parked: {full}"
if awaits != shown:
tmux.park(poll.loop.window, awaits, poll.epic.effects.tmux)
shown = awaits
if stays is not None and stays != said:
say(f"{stays}; trying again every {POLL_SECONDS} seconds", poll.epic.effects, stdout=True)
said = stays
poll.epic.effects.sleep(POLL_SECONDS)
# How the news for a chunk that was parked opens.
DRIVER_PARKED = f"{chunk_prompt.DRIVER} parked the chunk while"
def resumed(repo: str, loop: Loop, epic: EpicRun) -> str | None:
"""scheduler.resume for the parked chunk in loop's window, whose work is in the repo called repo, on the epic's cap and repos read afresh: None once it holds a running slot, else why it stays parked."""
# A chunk that resumes starts no other, so it needs no start order.
scheduled = scheduled_epic(epic, ())
if isinstance(scheduled, Failure):
return scheduled.reason
return scheduler.resume(scheduled, repo, loop.window, epic.effects.tmux)
def issue_read(key: str, epic: EpicRun) -> EpicIssue | Stop:
"""The epic's issue called key, read afresh."""
issues = epic.store.read()
if isinstance(issues, Failure):
return Stop(1, issues.reason)
found = [issue for issue in issues if issue.key == key]
return found[0] if found else Stop(1, f"{key} is no issue of the epic {epic.key}")
def chunk_root(key: str, issue: EpicIssue | None, epic: EpicRun) -> tuple[str, str | None] | Stop:
"""The folder the chunk called key works in, and the name of the repo whose checkout it is: None for the epic's folder, which holds work without a repo, as the epic's finishing is. issue is None for the epic's finishing. The chunk keeps both to its end, whatever its issue's labels become. The stop where the labels make the issue no chunk."""
pick = recorded(issue, epic.config.label_repos) if issue else ClaudeWork()
if isinstance(pick, Failure):
return Stop(1, pick.reason)
if isinstance(pick, ClaudeWork):
return str(epic.paths.home / scheduler.STATE / epic.key), None
if not isinstance(pick, Repo):
return Stop(1, f"{key} is no chunk: 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)), pick.name)
def folder_made(root: str) -> Failure | None:
"""Makes the folder a chunk works in where it is missing, as the epic's folder is before its first chunk without a repo."""
try:
pathlib.Path(root).mkdir(parents=True, exist_ok=True)
except OSError as failure:
return Failure(f"could not make the chunk's folder {root}: {failure.strerror}")
return None
def handed_on(key: str, epic: EpicRun, in_repo: bool = False, humans: bool = False, to_epic_branch: bool = False) -> Stop:
"""The stop of a do-epic whose chunk finished. It first moves the chunk's issue to done (the epic's finishing has none), and its split item too where that was the last of the item's sub-tasks, so that no finished chunk starts again and what they block may start, then starts each chunk that may start now. Where the team's automation moves issues, others move two kinds of issue. The automation moves the issue of a chunk in a repo, which in_repo marks, from its pull request: the stop waits for that move (`moved_by_automation`). The human moves their own task, which humans marks: the stop moves and awaits nothing. A chunk without a repo has no pull request, so its issue moves to done as ever, and so does a split item, once Jira counts each of its sub-tasks done. The automation doesn't see a pull request that merged into an epic's working branch, which to_epic_branch marks: the stop moves that chunk's issue to the status `jira-pull-request-merged-status` names. Where none is named, it moves the issue to done, or stops where the automation moves issues, since nothing would. Its window closes as it exits."""
automated = epic.config.automation_moves
# The epic's finishing has no issue to move: the epic is closed by `--close-epic`. Nor has a human's task where the human moves it: its window waited until it holds up no issue.
if key == epic.key or (humans and automated):
issues: list[EpicIssue] | Failure = epic.store.read()
elif to_epic_branch and (status := epic.config.pull_merged_status):
moved = epic.store.move_issue(key, status)
if isinstance(moved, Failure):
return Stop(1, f"the chunk finished, but its issue could not move to {status!r}: {moved.reason}; once it has that status in Jira, run `do-epic {epic.key}` to start the chunks it blocks")
issues = epic.store.read()
# A search may not show the move yet, so the issue counts as moved here whatever the read says.
issues = issues if isinstance(issues, Failure) else [dataclasses.replace(each, status=status) if each.key == key else each for each in issues]
elif to_epic_branch and automated:
return Stop(1, f"the chunk finished, but its issue stays as it is: its pull request merged into the epic's working branch, where the team's automation moves no issue, and do-epic's config names no `{PULL_MERGED_STATUS}` to move it to. Move {key} in Jira, then run `do-epic {epic.key}` to start the chunks it blocks")
elif in_repo and automated:
issues = moved_by_automation(key, epic)
else:
moved = epic.store.finish_issue(key)
if isinstance(moved, Failure):
return Stop(1, f"the chunk finished, but its issue could not move to done: {moved.reason}; once it is done in Jira, run `do-epic {epic.key}` to start the chunks it blocks")
issues = epic.store.read()
# A search may not show the move yet, so the issue counts as done here whatever the read says.
issues = issues if isinstance(issues, Failure) else [dataclasses.replace(each, done=True) if each.key == key else each for each in issues]
if isinstance(issues, Failure):
return Stop(1, f"the chunk finished, but the next could not start: {issues.reason}")
closed = split_items_closed(epic, issues)
if isinstance(closed, Stop):
return closed
started = chunks_started(epic, closed, key)
if isinstance(started, Failure):
return Stop(1, f"the chunk finished, but the next could not start: {started.reason}")
say(f"the chunk finished; started {', '.join(started.started) or 'no other'}", epic.effects, stdout=True)
return Stop(0, "")
def moved_by_automation(key: str, epic: EpicRun) -> list[EpicIssue]:
"""The epic's issues once the issue called key no longer holds up another: read every POLL_SECONDS until the team's automation, or a person, has moved it. Until then a read would show it open, and its chunk would start again. A read that fails is made again."""
told, unread = False, ""
while True:
issues = epic.store.read()
if isinstance(issues, Failure):
if issues.reason != unread:
say(f"cannot read the epic, so cannot tell whether {key} has moved; trying again every {POLL_SECONDS} seconds: {issues.reason}", epic.effects, stdout=True)
unread = issues.reason
epic.effects.sleep(POLL_SECONDS)
continue
by_key = {each.key: each for each in issues}
if key not in by_key or scheduler.settled(by_key[key], by_key, epic.config.unblocking):
return issues
if not told:
say(f"{key} is {by_key[key].status}: it waits for the team's automation to move it to {listed(epic.config.unblocking, 'or')}; move it in Jira if the automation doesn't", epic.effects, stdout=True)
told = True
epic.effects.sleep(POLL_SECONDS)
def split_items_closed(epic: EpicRun, issues: list[EpicIssue]) -> list[EpicIssue] | Stop:
"""The issues, with each item split by repo whose sub-tasks are all done moved to done in the tracker and read as done; the stop where one cannot move. Its last sub-task to finish closes it, and one an earlier run left open closes with it."""
for item in issues:
if split.SPLIT_LABEL in item.labels and not item.done and split.finished(issues, item.key):
moved = epic.store.finish_issue(item.key)
if isinstance(moved, Failure):
return Stop(1, f"the chunk finished, but its split item {item.key} could not move to done: {moved.reason}; once it is done in Jira, run `do-epic {epic.key}` to start the chunks it blocks")
issues = [dataclasses.replace(each, done=True) if each.key == item.key else each for each in issues]
return issues
def next_cycle(run: ChunkRun, loop: Loop, in_repo: bool, epic: EpicRun, news: str = "") -> Cycle | EpicReopened | Stop:
"""The cycle 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, and EpicReopened where the epic's finishing has no cycle to run. news is what `parked_through` tells the worker of a chunk that was parked, and opens its prompt. A chunk in a repo routes on that repo's model and ladder, and one without a repo on the machine setting `repoless-model` and the shipped ladder."""
premises = premises_read(loop.root if in_repo else None, epic)
if isinstance(premises, Failure):
return Stop(1, premises.reason)
language = epic.record.language()
if isinstance(language, Failure):
return Stop(1, language.reason)
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, EpicReopened)):
return work
task, issue = work
routing = project_routing(loop, chunk_prompt.DRIVER) if in_repo else routing_on(repoless_models(epic), SHIPPED)
if isinstance(routing, Stop):
return routing
archive_folder = epic.paths.home / ARCHIVE / epic.key
route = announced_route(run.cycle_number, run.route, routing, archive_folder, lambda: issue, loop)
prompts = chunk_prompt.unparked(news) if news else chunk_prompt.restating(task) if loop.window.name == epic.key else chunk_prompt.WORKER
return cycle_of(loop, routing, route, archive_folder, task=task, facts="", premises=premises, records=records, unfinished_evidence=run.unfinished_evidence, prompts=prompts, taken_in=lambda entries: TakenIn())
@dataclasses.dataclass(frozen=True)
class EpicReopened:
"""The epic holds an open issue again, so its finishing chunk has no work until none is open: working that issue comes first."""
def chunk_work(key: str, checkout: str | None, language: str, epic: EpicRun) -> tuple[str, RoutingIssue | None] | EpicReopened | Stop:
"""The task of the chunk called key, and the issue that routes it, or None where that issue has no scores: both from the epic's issues, read afresh. The epic's finishing has no issue, and its work is EpicReopened once the epic holds an open issue again."""
if key != epic.key:
issue = issue_read(key, epic)
if isinstance(issue, Stop):
return issue
config = config_located(checkout, epic.paths.home) if checkout else None
if isinstance(config, Failure):
return Stop(1, config.reason)
return chunk_prompt.task(issue, epic.key, epic.config.label_repos, checkout, epic.launcher, language, config), RoutingIssue(issue) if "L" in issue.scores else None
issues = epic.store.read()
if isinstance(issues, Failure):
return Stop(1, issues.reason)
issues = finish.landed(issues, epic.config.pull_merged_status)
if not finish.due(issues):
return EpicReopened()
return finish.task(epic.key, issues, epic.config.label_repos, epic.launcher, language), None
def repoless_models(epic: EpicRun) -> Models:
"""The models of a chunk without a repo: `repoless-model`, unless the environment names another for the run, as it may for loop-claude."""
return overridden(epic.env, epic.config.repoless_model)
def records_read(root: str | None, epic: EpicRun) -> str | Failure:
"""The epic's Scoring and Decisions, from its description, then the records of the repo checked out at root, where the chunk has one, then the human's rules."""
sections: list[tuple[str, str]] = []
for name in ("Scoring", "Decisions"):
body = epic.record.section(name)
if isinstance(body, Failure):
return Failure(f"the epic {epic.key}'s description: {body.reason} - {CONSEQUENCE}.")
sections.append((f"the epic {epic.key}'s description, ## {name}", body))
return read_records(root, epic.paths.home, epic.paths.claude_dir, tuple(sections))
def premises_read(root: str | None, epic: EpicRun) -> str | Failure:
"""The epic's Goals and Audience, from its description, then those of the repo checked out at root, where the chunk has one. A Failure where the epic lacks either: no chunk runs without premises."""
bodies: list[str] = []
for name in ("Goals", "Audience"):
body = epic.record.section(name)
if isinstance(body, Failure):
return Failure(f"the epic {epic.key}'s description: {body.reason} - no premises.")
if not body.strip():
return Failure(f"the epic {epic.key}'s description has no text under a `## {name}` heading - no premises.")
bodies.append(body)
theirs = read_premises(root, epic.paths.home) if root else ""
if isinstance(theirs, Failure):
return theirs
return f"the epic {epic.key}'s description:\n## Goals\n{bodies[0]}\n\n## Audience\n{bodies[1]}" + (f"\n\nThe repo's goals, which rank after the epic's and after code health, are from {theirs}" if theirs else "")