566 lines
34 KiB
Python
566 lines
34 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, 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
|
|
from loop_effects.effects import Effects, say
|
|
from project_config.settings import Epic
|
|
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 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 agent_cycle import tmux
|
|
|
|
HELP = f"""usage: do-epic <EPIC-KEY> [--status]
|
|
{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.
|
|
It then puts the scored issues that do-epic itself filed in order of score, by the `Score = ...` line under the epic's ## Scoring.
|
|
An open issue labelled `repo:<name>` or `do-epic-claude` runs as a chunk once no issue blocks it.
|
|
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.
|
|
{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"
|
|
# 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), 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]
|
|
words = words[:1] if status_asked else words
|
|
# What the words after the epic's key write into the epic, where they are a filing or a decision.
|
|
writes = findings.parsed(words[1:]) if chunk is None else None
|
|
closes = chunk is None and words[1:] == [finish.CLOSE]
|
|
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 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 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()
|
|
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)
|
|
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)
|
|
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."""
|
|
read = epic.store.read()
|
|
if isinstance(read, Failure):
|
|
return Stop(1, read.reason)
|
|
issues, stopped = planning.planned(planning.Planned(epic.key, epic.config, epic.store, epic.record, epic.paths.home, epic.effects), 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: {stopped.reason}", epic.effects)
|
|
started = chunks_started(epic, issues, None)
|
|
if isinstance(started, Failure):
|
|
return Stop(1, started.reason)
|
|
say(f"started {', '.join(started.started)} in the tmux session {epic.session}" if started.started else "started no chunk", epic.effects, stdout=True)
|
|
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():
|
|
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 chunks_started(epic: EpicRun, issues: list[EpicIssue], own: str | None) -> scheduler.Started | Failure:
|
|
"""scheduler.start_chunks on the epic's issues, as read, and its cap, read afresh; own is the issue of the chunk that asks. Where no issue is open, the chunk to start is the epic's finishing, unless the epic is closed."""
|
|
closed = finish.due(issues) and epic.store.closed()
|
|
if isinstance(closed, Failure):
|
|
return closed
|
|
scheduled = scheduled_epic(epic)
|
|
if isinstance(scheduled, Failure):
|
|
return scheduled
|
|
started = scheduler.start_chunks(scheduled, issues, finish.due(issues) and not closed, own, epic.effects.tmux)
|
|
return started if isinstance(started, Failure) else dataclasses.replace(started, closed=closed)
|
|
|
|
|
|
def scheduled_epic(epic: EpicRun) -> scheduler.Epic | Failure:
|
|
"""The epic as scheduler limits its chunks: with its cap, read afresh, and each repo's checkout."""
|
|
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, 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)
|
|
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)
|
|
|
|
|
|
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)
|
|
poll = Poll(key, repo, config.merge == "human", 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)
|
|
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."""
|
|
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) -> 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. 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 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)
|
|
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 "")
|