Run do-epic <EPIC-KEY>: a tmux session per epic and a window per chunk #619

Merged
lilleman merged 15 commits from item-410 into main 2026-11-18 23:01:33 +01:00
33 changed files with 1545 additions and 256 deletions
+1
View File
@@ -56,6 +56,7 @@
!bin/deploy-release
!bin/deploy_release/
!bin/deploy_release/*.py
!bin/do-epic
!bin/do_epic/
!bin/do_epic/*.py
!bin/do_epic/backend/
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- Added `do-epic <EPIC-KEY>`: it runs the chunks of one Jira epic, each in its own window of the tmux session `epic-<EPIC-KEY>`. As many run at once as the line `**Max parallel chunks:** 2` in the epic's description allows, one without it; a repo takes as many as its `parallel-chunks`, and none while loop-claude runs chunks in it. loop-claude in turn starts no chunk in a checkout where do-epic runs one.
- Refuse in rule-hook a Bash or Monitor command that waits forever: a sleeping loop with no time or count cap, and a `pgrep -f` or `pkill -f` whose pattern its own command line matches.
- A project's config may list its team's convention files in `coding-conventions`, which larv-review's reviewer agents read beside the principles and the standards, the team's rule winning where they conflict. larv-review opens the pull request after its own review where a push to the branch starts CI, and files an item to add a mutation tool where `mutate-changes` covers none of a language. The technical principles gain rules for tests on a shared environment, "Never mock a service your own team runs" and "Don't loosen a type when refactoring"; stability-reviewer checks a change that stores a value differently; and every finding of an outside reviewer now changes the setup, a deterministic tool first.
- do-epic's epic backends rank a child issue just before another, in Jira and in memory, and do-epic can re-rank Jira's backlog to an epic's ranking: it moves only the issues the loop filed, so each issue a person filed keeps its place, and it stops at the first rank Jira refuses and names it. Nothing calls it yet.
+2 -2
View File
@@ -73,7 +73,7 @@ Then pick a model with `/model`.
Link `loop-claude` onto `PATH`: `ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude`. Every claude it starts, the interactive ones included, skips every permission prompt. loop-claude runs each chunk in its own window of a tmux session per project, so it needs tmux 3.2 or later.
Back up two folders: `~/.claude/loop-claude-transcripts`, where loop-claude keeps every transcript, and `~/.local/state/larv-review`, where larv-review keeps each chunk's reports. To keep them small, add a crontab line that gzips each transcript and review file 30 days after it last changed, and logs each run with its date:
Back up three folders: `~/.claude/loop-claude-transcripts`, where loop-claude keeps every transcript, `~/.claude/do-epic-transcripts`, where do-epic keeps its chunks' transcripts, and `~/.local/state/larv-review`, where larv-review keeps each chunk's reports. To keep loop-claude's transcripts and the reports small, add a crontab line that gzips each transcript and review file 30 days after it last changed, and logs each run with its date:
```sh
17 4 * * * { date; $HOME/.claude/bin/compress-archives; } >> $HOME/.local/state/compress-archives.log 2>&1
@@ -216,7 +216,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
- `deploy_release` imports `release_plan`'s `release_standing`.
- `do_epic/` will hold the tool that drives one Jira epic. So far `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section and language line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `split.py` has claude predict from the code which repos an item changes, and files a sub-task per repo under it where there are several. `ranking.py` orders an epic's items by score over one chain of goals, the epic's, then code health, then the item's repo's, through `plan`'s ranking, and re-ranks the tracker's backlog to that order through `backend/`. `backend/` reads, files and ranks the epic's issues, adds the labels `repo_pick.py` and `split.py` record, and posts comments.
- `do_epic/` holds `do-epic`, the tool that drives one Jira epic. `main.py` starts the epic's chunks and runs one chunk's cycles in its window, through `agent_cycle`. `scheduler.py` says which issues run now: as many as the epic's cap and each repo's `parallel-chunks` allow, and none in a repo where loop-claude runs chunks. Beside it, `chunk_prompt.py` words what a chunk's worker reads. `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section, language line and cap line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `split.py` has claude predict from the code which repos an item changes, and files a sub-task per repo under it where there are several. `ranking.py` orders an epic's items by score over one chain of goals, the epic's, then code health, then the item's repo's, through `plan`'s ranking, and re-ranks the tracker's backlog to that order through `backend/`. `backend/` reads, files and ranks the epic's issues, adds the labels `repo_pick.py` and `split.py` record, and posts comments.
- `forge/` tells a GitHub origin from a Gitea one, names a repo beside an origin's and runs that forge's CLI (`commands.py`), and finds a pull request and waits for its checks (`pulls.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release`, `do_epic` and `larv_review`.
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
- `judge_replay` imports `agent_cycle`'s judge and verdicts, and `loop_claude`'s premises, records and `ANSWER_DESTINATIONS`.
+20 -9
View File
@@ -1,10 +1,10 @@
"""The escalation mark makes one escalation trigger step the worker up one rung, never two (docs/decisions.md → `routing: a worker whose run ends asking for a higher rung`).
A worker whose run ends asking loop-claude for a higher rung cites the trigger that fired, and the judge quotes the passage where it fired as the verdict's escalation. The mark, Route.escalated_at, is how many transcript entries the session held when an escalation last stepped the worker up, 0 before any. The session's transcript only grows, so the mark holds across cycles, and the archive's Worker: lines keep it for a rerun.
A worker whose run ends asking its driver, such as loop-claude, for a higher rung cites the trigger that fired, and the judge quotes the passage where it fired as the verdict's escalation. The mark, Route.escalated_at, is how many transcript entries the session held when an escalation last stepped the worker up, 0 before any. The session's transcript only grows, so the mark holds across cycles, and the archive's Worker: lines keep it for a rerun.
- Stamp. stamped() writes on the judge's verdict how many entries the judge read.
- Step. routing.next_route() steps the worker up on an escalation and moves the mark to moved_to(verdict).
- Show. transcript() puts STEP_LINE after the mark, telling the judge that the triggers before that line are spent. QUOTE_AFTER_STEP, in the judge's schema, tells the judge to quote only the worker's words after that line.
- Show. transcript() puts step_line after the mark, telling the judge that the triggers before that line are spent. quote_after_step, in the judge's schema, tells the judge to quote only the worker's words after that line.
- Check. checked() keeps an escalation only where it quotes both the transcript the judge was shown and the worker's own lines after the mark, which after_mark() renders, so a passage that bought one step cannot buy another.
"""
import dataclasses
@@ -17,9 +17,20 @@ from agent_cycle.quotes import verbatim
# Only the judge reads the step line, so it is not a [loop] line.
STEP_TAG = "[step]"
STEP_LINE = f"{STEP_TAG} loop-claude stepped the worker up a rung here, so the escalation triggers that fired before this line are spent."
# Reply.escalation's description in agent_cycle/judge.py carries this sentence, so the judge reads STEP_LINE as the mark.
QUOTE_AFTER_STEP = f"Where a {STEP_TAG} line says loop-claude stepped the worker up a rung, quote only the worker's own words after it, and leave this empty where the trigger fired only before it."
def asks_higher_rung(driver: str) -> str:
"""How a worker's run ends where it wants the rest of its chunk on a higher rung. The worker's prompt tells it to, and the judge's rules name the same words, so both take them from here. driver is the entry point that drives the cycle, such as `do-epic`."""
return f"asking {driver} for a higher rung"
def step_line(driver: str) -> str:
return f"{STEP_TAG} {driver} stepped the worker up a rung here, so the escalation triggers that fired before this line are spent."
def quote_after_step(driver: str) -> str:
"""Reply.escalation's description in agent_cycle/judge.py carries this sentence, so the judge reads step_line as the mark."""
return f"Where a {STEP_TAG} line says {driver} stepped the worker up a rung, quote only the worker's own words after it, and leave this empty where the trigger fired only before it."
def stamped(verdict: Verdict, entries_read: int) -> Verdict:
@@ -32,13 +43,13 @@ def moved_to(verdict: Escalating) -> int | None:
return verdict.entries_read if verdict.escalation else None
def transcript(entries: list[Entry], at: int, typed_answer: typing.Callable[[str], Typed | None]) -> str:
"""The transcript as the judge sees it. Where the mark, at, is above 0, STEP_LINE comes after that many entries."""
return "\n\n".join(part for part in (render(entries[:at], typed_answer), STEP_LINE if at else "", render(entries[at:], typed_answer)) if part)
def transcript(entries: list[Entry], at: int, typed_answer: typing.Callable[[str], Typed | None], driver: str) -> str:
"""The transcript as the judge sees it. Where the mark, at, is above 0, step_line comes after that many entries."""
return "\n\n".join(part for part in (render(entries[:at], typed_answer), step_line(driver) if at else "", render(entries[at:], typed_answer)) if part)
def after_mark(entries: list[Entry], at: int) -> str:
"""All the text and tool calls of the worker's assistant turns after the mark, even where the judge is shown only the transcript's tail. loop-claude's prompts and the human's lines are left out, since they repeat earlier passages, such as the judge's evidence or the worker's question."""
"""All the text and tool calls of the worker's assistant turns after the mark, even where the judge is shown only the transcript's tail. The driver's prompts and the human's lines are left out, since they repeat earlier passages, such as the judge's evidence or the worker's question."""
return "\n\n".join(line for entry in entries[at:] if isinstance(entry, AssistantTurn) for line in assistant_lines(entry))
+7 -7
View File
@@ -13,14 +13,14 @@ from agent_cycle.direct_message import tell
from agent_cycle import tmux
ANSWER_QUESTION = "answer the question above"
# TALK, what the human types at loop-claude's terminal to open claude for the question, and ASK_ANSWER were picked on 2026-10-17 by a bench of three readers seated as the README's audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it.
# TALK, what the human types at the entry point's terminal to open claude for the question, and ASK_ANSWER were picked on 2026-10-17 by a bench of three readers seated as the README's audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it.
TALK = "/talk"
ASK_ANSWER = f"Answer ({TALK} opens claude, Enter stops the loop): "
@dataclasses.dataclass(frozen=True)
class WorkerSession:
"""The worker's claude session, which /talk opens on loop-claude's terminal."""
"""The worker's claude session, which /talk opens on the entry point's terminal."""
root: str
id: uuid.UUID
rung: Rung
@@ -37,8 +37,8 @@ class Talked:
"""The human typed in the worker's claude session."""
def interrupt(question: str, answer_here: bool, session: WorkerSession, window: tmux.Window, effects: Effects) -> str | Talked | Stop:
"""Prints question for the human, in window, and returns their answer. While it waits, the window's name ends in tmux.WAITS, and the bell it rings shows in tmux's status bar. The answer: where answer_here, the first line typed at loop-claude's terminal, stripped, or Talked once they typed in the worker's claude session, which TALK opens; else Talked once they typed in that session, which opens at once on the terminal. A Stop where loop-claude is off a terminal, or they type no answer, or the input ends."""
def interrupt(question: str, answer_here: bool, session: WorkerSession, window: tmux.Window, driver: str, effects: Effects) -> str | Talked | Stop:
"""Prints question for the human, in window, and returns their answer. While it waits, the window's name ends in tmux.WAITS, and the bell it rings shows in tmux's status bar. The answer: where answer_here, the first line typed at the terminal of driver, the entry point, stripped, or Talked once they typed in the worker's claude session, which TALK opens; else Talked once they typed in that session, which opens at once on the terminal. A Stop where interrupt runs off a terminal, or they type no answer, or the input ends."""
# The bell ends the question's line, so it rings once the question can be read.
say(f"\n{question}{tmux.BELL}", effects)
on_terminal = effects.on_terminal()
@@ -47,8 +47,8 @@ def interrupt(question: str, answer_here: bool, session: WorkerSession, window:
effects.discard_typed()
tmux.mark(window, True, effects.tmux)
# After the discard, so an answer typed while the DM sends counts; before the terminal check, so a loop that cannot ask still tells the human what it would have asked.
tell(f"loop-claude in {session.root} asks, in the tmux window {window.target}:\n\n{question}", effects)
answer = needs_terminal(ANSWER_QUESTION, on_terminal) or answered(answer_here, session, effects)
tell(f"{driver} in {session.root} asks, in the tmux window {window.target}:\n\n{question}", effects)
answer = needs_terminal(ANSWER_QUESTION, on_terminal, driver) or answered(answer_here, session, effects)
# A loop that stops unanswered leaves the mark on its window.
if not isinstance(answer, Stop):
tmux.mark(window, False, effects.tmux)
@@ -64,7 +64,7 @@ def answered(answer_here: bool, session: WorkerSession, effects: Effects) -> str
def typed_answer(effects: Effects) -> str | Stop:
"""The line typed at loop-claude's terminal, stripped. A Stop where they type no answer, or the input ends."""
"""The line typed at the entry point's terminal, stripped. A Stop where they type no answer, or the input ends."""
try:
text = effects.input(ASK_ANSWER).strip()
except EOFError:
+31 -20
View File
@@ -36,8 +36,8 @@ INTERRUPT_RULES = (
"interrupt=false otherwise. A choice in the repo that no rule reserves for the human is the worker's to make, "
"so its taking its own recommendation on one is no reason to interrupt. Where it asks about such a choice and "
"recommends an answer, quote the sentence of that rule telling it to take the option it would recommend, even "
"where a [loop] line quoted that sentence for another question. A run that ends asking loop-claude for a higher "
"rung is no reason to interrupt either; one that asks the human's yes to a higher rung is.\n\n"
"where a [loop] line quoted that sentence for another question. A run that ends {asks_higher_rung} "
"is no reason to interrupt either; one that asks the human's yes to a higher rung is.\n\n"
"The human may have replied inside the transcript, on a [human] line: judge only what "
"is still open, never a question they already answered there. Where a [human] line from earlier in the "
"chunk answered the question the worker asks now, interrupt only if that line's own words leave open what "
@@ -66,22 +66,25 @@ FINISHED_RULES = (
)
def judge_rules(answer_destinations: str) -> str:
"""The rules that end the judge's prompt. answer_destinations names where the entry point's worker may record an answer the human typed."""
return "\n\n".join((INTERRUPT_RULES, QUOTE_RULES, FINISHED_RULES.format(answers_recorded=answers_recorded(answer_destinations), answer_destinations=answer_destinations)))
def judge_rules(answer_destinations: str, driver: str) -> str:
"""The rules that end the judge's prompt. answer_destinations names where the worker of driver, the entry point, may record an answer the human typed."""
return "\n\n".join((INTERRUPT_RULES.format(asks_higher_rung=escalation_mark.asks_higher_rung(driver)), QUOTE_RULES, FINISHED_RULES.format(answers_recorded=answers_recorded(answer_destinations), answer_destinations=answer_destinations)))
# Open the task and the transcript in the prompt; the premises and the records come before the task, the rules after the transcript.
# judge_replay.archived_prompt splits each archived prompt on them, so rewording one makes every run archived before it replay as failed.
TASK_HEADING = "The task the worker was given:\n"
TRANSCRIPT_HEADING = "What the worker did and said, what the human typed on [human] lines and what loop-claude told it on [loop] lines, latest last:\n"
def transcript_heading(driver: str) -> str:
return f"What the worker did and said, what the human typed on [human] lines and what {driver} told it on [loop] lines, latest last:\n"
@dataclasses.dataclass(frozen=True)
class Reply:
answer: str = dataclasses.field(metadata={"description": "With interrupt false, the passage of the premises or the records that answers the worker's question, quoted verbatim, without elisions. Empty otherwise."})
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: agent_cycle/escalation_mark.py.
escalation: str = dataclasses.field(metadata={"description": "Empty unless the chunk is unfinished, interrupt is true or answer quotes a passage, and the worker's run ends asking loop-claude for a higher rung, citing an escalation trigger. Then: a verbatim quote, without elisions, of the transcript passage where the trigger fired, such as a review round's commit title or the worker's report of the finding or failing test. " + escalation_mark.QUOTE_AFTER_STEP + " Never a later mention of the trigger, and never the request itself."})
escalation: str = dataclasses.field(metadata={"description": "Empty unless the chunk is unfinished, interrupt is true or answer quotes a passage, and the worker's run ends {asks_higher_rung}, citing an escalation trigger. Then: a verbatim quote, without elisions, of the transcript passage where the trigger fired, such as a review round's commit title or the worker's report of the finding or failing test. {quote_after_step} Never a later mention of the trigger, and never the request itself."})
evidence: str = dataclasses.field(metadata={"description": "A verbatim quote of the one transcript passage the verdict rests on, without elisions: what triggers the interrupt; for a quoted answer, the worker's question; else what shows the chunk finished or the work remaining."})
finished: bool = dataclasses.field(metadata={"description": "Whether the chunk is finished."})
interrupt: bool = dataclasses.field(metadata={"description": "Whether the human must now be interrupted."})
@@ -96,11 +99,17 @@ class Reply:
REPLY_TYPES = typing.get_type_hints(Reply)
JSON_TYPES: dict[object, dict[str, typing.Any]] = {bool: {"type": "boolean"}, int: {"type": "integer"}, str: {"type": "string"}}
JUDGE_SCHEMA = {
"properties": {field.name: {**field.metadata, **JSON_TYPES[REPLY_TYPES[field.name]]} for field in dataclasses.fields(Reply)},
"required": list(REPLY_TYPES),
"type": "object",
}
def judge_schema(driver: str) -> dict[str, typing.Any]:
"""The schema of the judge's reply, each field described from Reply's metadata, with the words that name driver, the entry point, filled in."""
asks, quote = escalation_mark.asks_higher_rung(driver), escalation_mark.quote_after_step(driver)
described = {field.name: field.metadata["description"].replace("{asks_higher_rung}", asks).replace("{quote_after_step}", quote) for field in dataclasses.fields(Reply)}
return {
"properties": {name: {"description": description, **JSON_TYPES[REPLY_TYPES[name]]} for name, description in described.items()},
"required": list(REPLY_TYPES),
"type": "object",
}
@dataclasses.dataclass(frozen=True)
@@ -137,6 +146,8 @@ class Brief(typing.NamedTuple):
entries: list[Entry]
# How many of the entries the session held when an escalation last stepped the worker up a rung, 0 before any.
escalated_at: int
# The entry point's name, such as `do-epic`, as WorkerPrompts.driver has it.
driver: str
def verdict_from(output: object) -> Verdict | Failure:
@@ -170,21 +181,21 @@ def judge(root: str, brief: Brief, rung: Rung, effects: Effects, keep: typing.Ca
def judge_once(root: str, brief: Brief, rung: Rung, effects: Effects) -> Verdict | Failure | Limited:
"""One judge run on the brief, as judge retries it; judge-replay replays it."""
prompt, grounds = judge_prompt(brief)
verdict = run_judge(root, judge_args(rung), prompt, grounds, effects)
verdict = run_judge(root, judge_args(rung, brief.driver), prompt, grounds, effects)
return verdict if isinstance(verdict, Failure | Limited) else escalation_mark.stamped(verdict, len(brief.entries))
def judge_archived(root: str, prompt: str, grounds: Grounds, entries_read: int, rung: Rung, effects: Effects) -> Verdict | Failure | Limited:
def judge_archived(root: str, prompt: str, grounds: Grounds, entries_read: int, rung: Rung, driver: str, effects: Effects) -> Verdict | Failure | Limited:
"""One judge run on a prompt the archive kept from an earlier run, as judge-replay replays it: the judge reads what it read then, and its quotes are checked against grounds, which judge_replay.archived_prompt makes from that prompt in place of the records of today."""
verdict = run_judge(root, judge_args(rung), prompt, grounds, effects)
verdict = run_judge(root, judge_args(rung, driver), prompt, grounds, effects)
return verdict if isinstance(verdict, Failure | Limited) else escalation_mark.stamped(verdict, entries_read)
def judge_args(rung: Rung) -> list[str]:
def judge_args(rung: Rung, driver: str) -> list[str]:
# --json-schema has claude check its reply against the schema and return it as the json result's structured_output.
# No tools, so the verdict rests on the transcript grounded() checks it against.
return [
"--json-schema", json.dumps(JUDGE_SCHEMA),
"--json-schema", json.dumps(judge_schema(driver)),
*rung.flags(),
"--tools", "",
]
@@ -281,11 +292,11 @@ def judge_prompt(brief: Brief) -> tuple[str, Grounds]:
f"From the goals file, {brief.premises}\n\n"
f"The records: the project's working rules and decisions, then the human's rules for every project:\n{brief.records or 'none'}\n\n"
f"{TASK_HEADING}{brief.task}\n\n"
f"{TRANSCRIPT_HEADING}"
f"{transcript_heading(brief.driver)}"
)
rules = judge_rules(brief.answer_destinations)
rules = judge_rules(brief.answer_destinations, brief.driver)
room = max(0, JUDGE_PROMPT_CHARS - len(head) - len(rules) - 2)
transcript = escalation_mark.transcript(brief.entries, brief.escalated_at, typed_answer)
transcript = escalation_mark.transcript(brief.entries, brief.escalated_at, typed_answer, brief.driver)
# The tail, where an interrupt or a finish lands; the session's transcript grows cycle over cycle.
shown = transcript[max(0, len(transcript) - room):]
grounds = Grounds(
+17 -2
View File
@@ -28,10 +28,10 @@ Each verdict then moves the rung by one rule, and the rung never falls. The rung
| interrupt or quoted answer without one | holds | holds | holds |
"""
import dataclasses
import typing
from agent_cycle import escalation_mark
from agent_cycle.verdicts import Interrupt, QuotedAnswer, Unfinished
from plan.todo_table import Item
from model_routing.ladder import Ladder, ProjectRung, Rung
from model_routing.route import Route
@@ -42,7 +42,22 @@ ESCALATION_CAP = 2
JUDGE_REPLAYED = ("claude-opus-5-5",)
def first_route(project: ProjectRung, item: Item | None) -> Route:
class Scored(typing.Protocol):
"""What routes a chunk: a plan item under loop-claude, an epic's issue under do-epic."""
@property
def id(self) -> int:
"""The number a Route keeps as its item."""
@property
def likelihood(self) -> int:
"""Its L."""
@property
def escape_and_impact(self) -> int:
"""Its E + I."""
def first_route(project: ProjectRung, item: Scored | None) -> Route:
"""The route a chunk starts on: the rung its item's L picks from the project's rung, or the project's rung without an item."""
if item is None:
return Route(project.rung)
+2 -1
View File
@@ -159,6 +159,7 @@ def rule(cycle: Cycle, transcript_path: str, quoted_answers: int) -> Ruled | Sto
answer_destinations=cycle.prompts.answer_destinations,
entries=entries,
escalated_at=cycle.route.escalated_at,
driver=cycle.prompts.driver,
)
verdict = judge(cycle.root, brief, cycle.judge, cycle.effects, lambda rejected: keep_rejection(cycle, transcript_path, rejected))
if isinstance(verdict, Stop):
@@ -205,7 +206,7 @@ def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> St
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) -> HumanTyped | HumanTalked | Stop:
"""The human's answer to a ruling that rule archived as it ruled; the human's answer then grows the transcript."""
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
answer = interrupt(question_for(cycle, ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.window, cycle.effects)
answer = interrupt(question_for(cycle, ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.window, cycle.prompts.driver, cycle.effects)
match answer:
case Stop():
return answer
+4 -3
View File
@@ -4,7 +4,7 @@ import typing
@dataclasses.dataclass(frozen=True)
class Stop:
"""loop-claude exits with code, printing reason."""
"""The entry point exits with code, printing reason."""
code: typing.Literal[0, 1, 2, 130]
reason: str
@@ -13,7 +13,8 @@ def needs_human(need: str, blocker: str) -> Stop:
return Stop(2, f"the human is needed to {need}, but {blocker}")
def needs_terminal(need: str, on_terminal: bool) -> Stop | None:
def needs_terminal(need: str, on_terminal: bool, driver: str) -> Stop | None:
"""driver is the entry point the human reruns, such as `do-epic`."""
if on_terminal:
return None
return needs_human(need, "stdin or stdout is not a terminal; rerun loop-claude on a terminal")
return needs_human(need, f"stdin or stdout is not a terminal; rerun {driver} on a terminal")
+45 -12
View File
@@ -1,4 +1,4 @@
"""The tmux commands loop-claude runs: each chunk's loop runs in its own window of one tmux session named for the project (docs/decisions.md → `loop-claude: each chunk runs in its own tmux window`)."""
"""The tmux commands an entry point runs: each chunk's loop runs in its own window of one tmux session, which loop-claude names for the project and do-epic for the epic (docs/decisions.md → `loop-claude: each chunk runs in its own tmux window`)."""
import dataclasses
import re
import subprocess
@@ -14,8 +14,13 @@ NEEDED = (3, 2)
# What a window's name ends in while its chunk waits for the human. tmux's status bar shows the name, and `!` after it once the bell rang.
WAITS = " ?"
BELL = "\a"
# What a session's name opens with: LOOP for a project's chunks under loop-claude, EPIC for an epic's chunks under do-epic.
LOOP = "loop"
EPIC = "epic"
# The session option that names the checkout whose chunks the session runs, since two checkouts' keys may map to one session name.
OWNER = "@loop-root"
# The window option that names the folder a window's chunk works in, so that loop-claude and every do-epic see the chunks a do-epic runs in a checkout.
ROOT = "@chunk-root"
@dataclasses.dataclass(frozen=True)
@@ -44,18 +49,27 @@ class Listed:
dead: bool
def unusable(run: Tmux) -> str | None:
"""Why loop-claude cannot use this machine's tmux, naming the version found and the one needed; None where it is NEEDED or later."""
@dataclasses.dataclass(frozen=True)
class Placed:
"""A window of any session, as tmux lists it."""
session: str
window: Listed
# The folder its chunk works in, as ROOT names it; empty for a window started before ROOT was set.
root: str
def unusable(run: Tmux, driver: str) -> str | None:
"""Why driver, the entry point, cannot use this machine's tmux, naming the version found and the one needed; None where it is NEEDED or later."""
found = run(["-V"]).stdout.strip()
version = re.search(r"([0-9]+)\.([0-9]+)", found)
if version and (int(version[1]), int(version[2])) >= NEEDED:
return None
return f"loop-claude runs each chunk in a tmux window, and needs tmux {NEEDED[0]}.{NEEDED[1]} or later; it found {found or 'no tmux'}"
return f"{driver} runs each chunk in a tmux window, and needs tmux {NEEDED[0]}.{NEEDED[1]} or later; it found {found or 'no tmux'}"
def session_name(key: str) -> str:
"""The tmux session of the project with this key, such as `loop-claude-config`. tmux reads `.` and `:` in a target as separators, so every character but a letter, a digit, `_` and `-` becomes a dash."""
return "loop-" + re.sub(r"[^A-Za-z0-9_-]", "-", key)
def session_name(kind: str, key: str) -> str:
"""The tmux session an entry point runs its chunks in: kind LOOP with a project's key, such as `loop-claude-config`, or kind EPIC with an epic's key, such as `epic-ABC-12`. tmux reads `.` and `:` in a target as separators, so every character of the key but a letter, a digit, `_` and `-` becomes a dash."""
return f"{kind}-" + re.sub(r"[^A-Za-z0-9_-]", "-", key)
def listed(session: str, run: Tmux) -> list[Listed]:
@@ -65,8 +79,15 @@ def listed(session: str, run: Tmux) -> list[Listed]:
return [Listed(row[0].removesuffix(WAITS), row[2], row[1] == "1") for row in rows if len(row) == 3]
def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], first: bool, run: Tmux) -> Failure | None:
"""Starts command in a new window of window's session, in cwd with env added to its environment, and leaves the client where it is. first makes the session too. A Failure says why tmux started none, or why it could not mark a session it made as this checkout's."""
def everywhere(run: Tmux) -> list[Placed]:
"""The windows of every session; none where no tmux server runs."""
done = run(["list-windows", "-a", "-F", f"#{{session_name}}\t#{{window_name}}\t#{{pane_dead}}\t#{{window_id}}\t#{{{ROOT}}}"])
rows = [line.split("\t") for line in done.stdout.splitlines()] if done.returncode == 0 else []
return [Placed(row[0], Listed(row[1].removesuffix(WAITS), row[3], row[2] == "1"), row[4]) for row in rows if len(row) == 5]
def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], first: bool, owned: bool, run: Tmux) -> Failure | None:
"""Starts command in a new window of window's session, in cwd with env added to its environment, and leaves the client where it is. first makes the session too, and owned marks a session it makes as running the chunks of the checkout cwd. A Failure says why tmux started none, or why it could not mark the session."""
make = ["new-session", "-d", "-s", window.session] if first else ["new-window", "-d", "-t", f"={window.session}:"]
variables = [flag for name, value in env.items() for flag in ("-e", f"{name}={value}")]
# tmux reads a `;` that ends an argument as the end of the command, unless a backslash precedes it.
@@ -75,15 +96,27 @@ def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], comman
if done.returncode:
return Failure(f"tmux could not start the window {window.target}: {done.stderr.strip() or f'it exited {done.returncode}'}")
# set-option and show-options read a target as a pane's, so `=session` alone names no session.
owned = run(["set-option", "-t", f"={window.session}:", OWNER, cwd]) if first else None
marked = run(["set-option", "-t", f"={window.session}:", OWNER, cwd]) if first and owned else None
# A failure leaves the window unseen by loop-claude and by another epic's do-epic, which then may start a chunk beside it; the window still runs.
run(["set-option", "-w", "-t", done.stdout.strip(), ROOT, cwd])
# By the ID, since a window of the same name may still be closing. A failed remain-on-exit doesn't matter: a loop that fails before it is set closes its window, and its stop is still sent as a DM.
run(["set-option", "-w", "-t", done.stdout.strip(), "remain-on-exit", "failed"])
# Without the owner, start_chunks cannot tell this checkout's session from another's, so no further chunk may start in it.
if owned is not None and owned.returncode:
return Failure(f"tmux started the session {window.session} but could not mark it as this checkout's: {owned.stderr.strip() or f'it exited {owned.returncode}'}")
if marked is not None and marked.returncode:
return Failure(f"tmux started the session {window.session} but could not mark it as this checkout's: {marked.stderr.strip() or f'it exited {marked.returncode}'}")
return None
def start_chunk(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], windows: list[Listed], owned: bool, run: Tmux) -> list[Listed] | Failure:
"""Starts a chunk's command in window, in place of each dead window of its name among windows, the session's; the session's windows afterwards, or why tmux started none. start_window says what cwd, env and owned do."""
stale = [listed for listed in windows if listed.name == window.name and listed.dead]
for listed in stale:
close(listed, run)
kept = [listed for listed in windows if listed not in stale]
failed = start_window(window, cwd, env, command, not kept, owned, run)
return failed or [*kept, Listed(window.name, "", False)]
def owner(session: str, run: Tmux) -> str:
"""The checkout whose chunks session runs, as OWNER names it; empty where it names none."""
return run(["show-options", "-qv", "-t", f"={session}:", OWNER]).stdout.strip()
+11 -6
View File
@@ -3,6 +3,7 @@
An entry point is a tool that drives cycles, such as loop-claude. It words the prompts of its own workflow and names the files of its project. WorkerPrompts holds those, so the cycle doesn't import an entry point to word a prompt.
"""
import dataclasses
import re
import typing
from model_routing.ladder import ProjectRung
@@ -10,7 +11,9 @@ from model_routing.route import Route
from claude_code.transcript import Typed
# Opens typed's prompt, with the answer on the line after it, so typed_answer finds the answer at the prompt's start, whatever the question holds.
TYPED_HERE = "The human answered your question at loop-claude's terminal:"
TYPED_HERE = "The human answered your question at {driver}'s terminal:"
# Finds TYPED_HERE whatever the driver, so a transcript reads the same to every tool that renders it.
TYPED_OPENING = re.compile(re.escape(TYPED_HERE).replace(re.escape("{driver}"), r"[\w-]+") + "\n")
def answers_recorded(destinations: str) -> str:
@@ -20,16 +23,18 @@ def answers_recorded(destinations: str) -> str:
def typed_answer(prompt: str) -> Typed | None:
"""Splits a prompt from WorkerPrompts.typed into its answer and the rest, so the judge reads the answer as the human's; None for any other prompt."""
opening = f"{TYPED_HERE}\n"
if not prompt.startswith(opening):
opening = TYPED_OPENING.match(prompt)
if not opening:
return None
answer, _, rest = prompt.removeprefix(opening).partition("\n\n")
answer, _, rest = prompt[opening.end():].partition("\n\n")
return Typed(rest, answer)
@dataclasses.dataclass(frozen=True)
class WorkerPrompts:
"""What an entry point supplies to the prompts of its cycles."""
# The entry point's name as the worker, the judge and the human read it, such as `do-epic`.
driver: str
# The prompt that starts a worker, from its task, the premises, its route, the project's rung and the facts found before the cycle.
fresh: typing.Callable[[str, str, Route, ProjectRung | None, str], str]
# The prompt that resumes a worker whose previous run ended before the chunk was finished, from the evidence of the unfinished verdict, if there was one.
@@ -47,11 +52,11 @@ class WorkerPrompts:
def typed(self, question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The prompt that resumes the worker with the human's answer to an interrupt. answer is one line, as the terminal reads it."""
return f"{TYPED_HERE}\n{answer}\n\nYour question was: {question}\n\nContinue the task. The chunk is finished only once {answers_recorded(self.answer_destinations)}.{self.stepped_to(route, project, stepped)}"
return f"{TYPED_HERE.format(driver=self.driver)}\n{answer}\n\nYour question was: {question}\n\nContinue the task. The chunk is finished only once {answers_recorded(self.answer_destinations)}.{self.stepped_to(route, project, stepped)}"
def stepped_to(self, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The sentences naming the worker's new rung, as resumed has them, where the ruling that brought the answer stepped the worker up; empty otherwise."""
return f" Your request for a higher rung went through: loop-claude runs you on {route.rung}. The escalation triggers that fired before this step are spent.{self.rungs_held(route, project)}" if stepped else ""
return f" Your request for a higher rung went through: {self.driver} runs you on {route.rung}. The escalation triggers that fired before this step are spent.{self.rungs_held(route, project)}" if stepped else ""
def past_the_cap(self, question: str, answer: str, cap: int) -> str:
"""The question a quoted answer puts to the human once the cycle's quoted answers reach the cap."""
+1 -1
View File
@@ -52,5 +52,5 @@ def delete_session(session: Session) -> Failure | None:
try:
shutil.rmtree(sibling) if os.path.isdir(sibling) else os.remove(sibling)
except OSError as failure:
return Failure(f"could not delete {sibling}: {failure.strerror or failure}; delete every file and folder matching {stem}*, then rerun loop-claude; a rerun before that resumes the finished chunk's session")
return Failure(f"could not delete {sibling}: {failure.strerror or failure}; delete every file and folder matching {stem}*, then run it again; a run before that resumes the finished chunk's session")
return None
Executable
+13
View File
@@ -0,0 +1,13 @@
#!/usr/bin/env python3
import os
import pathlib
import sys
LAUNCHER = pathlib.Path(__file__).resolve()
sys.path.insert(0, str(LAUNCHER.parent))
from loop_effects import effects
from do_epic import main
from loop_state import paths
sys.exit(main.main(sys.argv[1:], os.environ, paths.paths_from(pathlib.Path.home()), LAUNCHER, effects.system_effects()))
+28
View File
@@ -0,0 +1,28 @@
"""What a do-epic cycle's worker is told: its task, from the issue, and its first prompt. The resumed prompt and the rung sentences are the ones loop-claude's cycles use, naming do-epic."""
from do_epic.backend.protocol import EpicIssue
from model_routing.ladder import ProjectRung
from loop_claude.cycle import prompts
from model_routing.route import Route
# The entry point's name as the worker, the judge and the human read it.
DRIVER = "do-epic"
def task(issue: EpicIssue, epic: str, checkout: str | None) -> str:
"""The task of the chunk that works issue, of the epic with the key epic: in checkout, or without a repo where it is None."""
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}. Its summary: {issue.summary}" + (f"\n\nIts description:\n\n{issue.detail}" if issue.detail else "")
CODE_HEALTH = '~/.claude/CLAUDE.md → "Shared goal"'
def fresh(task: str, premises: str, route: Route, project: ProjectRung | None, facts: str) -> str:
"""A chunk's first prompt. facts is empty: do-epic runs no preflight."""
routed = f"{DRIVER} runs you on {route.rung}, routed by the issue's L of {route.likelihood}. Where a sentence below names item {route.item}, it means the issue." if route.item else ""
opening = " ".join(filter(None, [routed, *prompts.rung_sentences(DRIVER, route, project)]))
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one. {prompts.READING_RULE}\n\n{opening and f'{opening}{chr(10)}{chr(10)}'}The issue sets the chunk's scope. The goals below choose between ways to deliver that scope, and never widen it. The epic's goals rank first, then code health ({CODE_HEALTH}), then the repo's.\n\nFrom {premises}"
# The worker names no plan items: the chunk's one item is its issue.
WORKER = prompts.worker_prompts(DRIVER, fresh, "")
+24 -2
View File
@@ -1,6 +1,6 @@
"""A Jira epic's description as the record of do-epic, the tool that will drive one epic.
"""A Jira epic's description as the record of do-epic, the tool that drives one epic.
The description holds a language line and the sections Goals, Audience, Scoring (the formula and the bar) and Decisions. They are read and written one at a time through `EpicDescription`, and a write leaves every other line of the markdown as it was. Goals and Audience change only where the human approved in an interrupt, which `write_section` takes as `approved`; `EpicDescription` refuses the change otherwise."""
The description holds a language line, a line that caps the chunks running at once, and the sections Goals, Audience, Scoring (the formula and the bar) and Decisions. They are read and written one at a time through `EpicDescription`, and a write leaves every other line of the markdown as it was. Goals and Audience change only where the human approved in an interrupt, which `write_section` takes as `approved`; `EpicDescription` refuses the change otherwise."""
import dataclasses
import re
import typing
@@ -13,6 +13,11 @@ from project_config.settings import language_fault
SECTIONS = ("Goals", "Audience", "Scoring", "Decisions")
LANGUAGE_LINE = re.compile(r"^\*\*Language:\*\* (.*?)\s*$")
# The line that caps how many of the epic's chunks run at once. Three readers, seated as the human who writes an epic's description, picked this spelling from four candidates, 2-1 over `**Parallel chunks:**`, which reads as a count of what runs now.
CAP = "**Max parallel chunks:**"
CAP_LINE = re.compile(rf"^{re.escape(CAP)}(.*?)\s*$")
# A line that opens with CAP's words in another spelling. It is refused, since the epic would otherwise run on the cap of 1 without a word.
NEAR_CAP_LINE = re.compile(r"^[\s*_>#-]*max parallel chunks", re.IGNORECASE)
def read_section(text: str, name: str) -> str | Failure:
@@ -59,6 +64,19 @@ def language_in(text: str) -> str | None:
return None
def parallel_chunks_in(text: str) -> int | Failure:
"""How many of the epic's chunks may run at once, as the description's CAP line says; 1 where it has none, as a project's `parallel-chunks` is where its config leaves it out."""
for line, fenced in fenced_lines(text):
if not fenced and (found := CAP_LINE.match(line)):
value = found.group(1).strip()
if re.fullmatch(r"[1-9][0-9]*", value):
return int(value)
return Failure(f"the epic's description caps its chunks with `{CAP} {value}`, which is not a whole number of 1 or more, such as `{CAP} 2`")
if not fenced and NEAR_CAP_LINE.match(line):
return Failure(f"the epic's description holds the line `{line.strip()}`, which do-epic doesn't read as the epic's cap: write it as a line of its own, spelt `{CAP} 2`")
return 1
def with_language(text: str, language: str) -> str | Failure:
"""text with its language line naming language, put first where there is none."""
if fault := language_fault(language):
@@ -84,6 +102,10 @@ class EpicRecord:
text = self.description.read()
return text if isinstance(text, Failure) else language_in(text)
def parallel_chunks(self) -> int | Failure:
text = self.description.read()
return text if isinstance(text, Failure) else parallel_chunks_in(text)
def write_section(self, name: str, body: str, approved: bool = False) -> Held | Failure:
"""Writes body as the ## name section. approved says the human approved the change in an interrupt, which Goals and Audience need."""
return self.written(lambda text: with_section(text, name, body), frozenset({name}) if approved else frozenset())
+280
View File
@@ -0,0 +1,280 @@
"""The do-epic command (docs/decisions.md → `do-epic: drives one Jira epic …`).
`do-epic <EPIC-KEY>` 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."""
import dataclasses
import pathlib
import typing
from loop_claude.loop.chunk_start import archived_route, routed
from do_epic import chunk_prompt, scheduler
from do_epic.repo_pick import ClaudeWork, HumanTask, recorded, Repo
from loop_claude.loop.close import closed_cycle
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 loop_claude.project.model_choice import get_or_ask_models, Models
from plan_store.jira_epic import ISSUE_KEY
from do_epic.backend.jira import JiraEpic
from agent_cycle.routing import judge_rung
from do_epic.repos import locate
from loop_claude.loop.this_loop import Loop
from loop_claude.loop.reload import LoopRun
from loop_state.paths import Paths
from transcript_archive.project_key import project_key
from model_routing.ladder_file import project_ladder_file, read_ladder, SHIPPED
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from claude_code.session import session_named
from loop_claude.loop.main import setup_version
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>
Runs the chunks of one Jira epic, such as ABC-12, each in its own window of the tmux session epic-<EPIC-KEY>.
An open issue of the epic runs as a chunk once it has a label and no issue blocks it.
The label names the issue's repo, or says the work changes no repo.
As many run at once as the epic's description allows with a line such as `**Max parallel chunks:** 2`, one where it has none.
A repo takes as many chunks as its `parallel-chunks`, and none while loop-claude runs chunks in it.
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 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), 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
@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) -> int:
try:
stop = run(argv, env, paths, launcher, effects, backend)
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] == [scheduler.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) -> Stop:
chunk, words = (argv[1], argv[2:]) if len(argv) >= 2 and argv[0] == scheduler.CHUNK_FLAG else (None, argv)
if len(words) != 1 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)
# 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)
return windows_opened(epic) if chunk is None else chunk_run(chunk, epic)
def windows_opened(epic: EpicRun) -> Stop:
"""What the do-epic the human runs does: starts each chunk that may start now, says why each other open issue waits, then puts the epic's session on the terminal until the human detaches."""
started = chunks_started(epic, None)
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 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, own: str | None) -> scheduler.Started | Failure:
"""scheduler.start_chunks on the epic's issues and cap, read afresh; own is the issue of the chunk that asks."""
issues = epic.store.read()
if isinstance(issues, Failure):
return issues
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.start_chunks(scheduler.Epic(epic.key, cap, located, epic.paths.home, epic.launcher, epic.env), issues, own, epic.effects.tmux)
@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."""
pane = epic.env.get("TMUX_PANE")
if not pane:
return Stop(1, f"{scheduler.CHUNK_FLAG} is how do-epic starts itself in a tmux window; run do-epic <EPIC-KEY>")
issue = issue_read(key, epic)
if isinstance(issue, Stop):
return issue
place = chunk_root(issue, epic)
if isinstance(place, Stop):
return place
root, in_repo = place
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)
loop_run = LoopRun(0, root, "", "", chunk=key)
while True:
loop_run = dataclasses.replace(loop_run, cycle_number=loop_run.cycle_number + 1)
cycle = next_cycle(loop_run, loop, in_repo, epic)
if isinstance(cycle, Stop):
return cycle
loop_run = dataclasses.replace(loop_run, task=cycle.task)
concluded = run_cycle(cycle)
if isinstance(concluded, Stop):
return concluded
closed = closed_cycle(loop_run, cycle.project, concluded, cycle.project_archive, chunk_prompt.DRIVER, loop)
if isinstance(closed, Stop):
return closed
loop_run = closed
if isinstance(concluded.verdict, Finished):
return handed_on(key, epic)
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(issue: EpicIssue, epic: EpicRun) -> tuple[str, bool] | Stop:
"""The folder the issue's chunk works in, and whether it is a repo's checkout: the epic's folder holds work without a repo. The chunk keeps both to its end, whatever the issue's labels become. The stop where the labels make the issue no chunk."""
pick = recorded(issue)
if isinstance(pick, Failure):
return Stop(1, pick.reason)
if isinstance(pick, ClaudeWork):
folder = epic.paths.home / scheduler.STATE / epic.key
folder.mkdir(parents=True, exist_ok=True)
return str(folder), False
if not isinstance(pick, Repo):
return Stop(1, f"{issue.key} is no chunk: {'it is a human\'s task' if isinstance(pick, HumanTask) else 'no label names its repo'}")
found = locate(pick.name, [], epic.config, epic.paths.home, epic.effects.git)
return Stop(1, found.reason) if isinstance(found, Failure) else (str(real(found.checkout)), True)
def handed_on(key: str, epic: EpicRun) -> Stop:
"""The stop of a do-epic whose chunk finished, once it has started each chunk that may start now. Its window closes as it exits."""
started = chunks_started(epic, key)
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 next_cycle(loop_run: LoopRun, loop: Loop, in_repo: bool, epic: EpicRun) -> Cycle | Stop:
"""The cycle loop_run runs next, from the issue, the premises, the records, the models and the routing ladder read afresh; the stop where one of them cannot be read. A chunk in a repo routes on that repo's model and ladder, and one without a repo on the machine setting `repoless-model` and the shipped ladder."""
issue = issue_read(loop.window.name, epic)
if isinstance(issue, Stop):
return issue
premises = premises_read(loop.root if in_repo else None, epic)
if isinstance(premises, Failure):
return Stop(1, premises.reason)
# The epic's records join the repo's with todo.md item 413; until then a chunk without a repo has none.
records = read_records(loop.root, epic.paths.home, epic.paths.claude_dir) if in_repo else ""
if isinstance(records, Failure):
return Stop(1, records.reason)
models = get_or_ask_models(project_key(loop.root, epic.paths.home), epic.paths, epic.env, chunk_prompt.DRIVER, epic.effects) if in_repo else repoless_models(epic)
if isinstance(models, Stop):
return models
ladder_file = project_ladder_file(loop.root, epic.paths.home) if in_repo else SHIPPED
if isinstance(ladder_file, Failure):
return Stop(1, ladder_file.reason)
ladder = read_ladder(ladder_file)
if isinstance(ladder, Failure):
return Stop(1, ladder.reason)
archive_folder = epic.paths.home / ARCHIVE / epic.key
project = ladder.project_rung(models.worker)
route = routed(loop_run.route, project, models.worker, lambda: archived_route(archive_folder, loop), lambda: RoutingIssue(issue) if "L" in issue.scores else None)
say(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", epic.effects, stdout=True)
return Cycle(config=setup_version(epic.paths.claude_dir, epic.effects.git), effects=epic.effects, facts="", judge=judge_rung(ladder, models.judge), premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=chunk_prompt.task(issue, epic.key, loop.root if in_repo else None), prompts=chunk_prompt.WORKER, taken_in=lambda entries: TakenIn(), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
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 Models(epic.env.get("LOOP_CLAUDE_JUDGE_MODEL") or epic.config.repoless_model, epic.env.get("LOOP_CLAUDE_WORKER_MODEL") or epic.config.repoless_model)
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 "")
+162
View File
@@ -0,0 +1,162 @@
"""Which of an epic's issues run as chunks now, each in its own window of the epic's tmux session (docs/decisions.md → `do-epic: drives one Jira epic …`).
Three limits hold a chunk back: the epic's cap of chunks at once, its repo's `parallel-chunks`, counted across every epic, and a loop-claude that runs chunks in its repo. do-epic checks a repo and starts a chunk in it while holding the lock loop-claude holds when it starts one (`chunk_windows.starting`), so the two never start chunks in one checkout together."""
import dataclasses
import pathlib
import typing
from do_epic.epic_record import CAP
from loop_claude.loop.chunk_windows import epic_chunks, HANDED, LOCK, project_lock, starting
from do_epic.backend.protocol import EpicIssue
from failure import Failure
from do_epic.repo_pick import HumanTask, recorded, Repo
from project_config.settings import PARALLEL_CHUNKS
from transcript_archive.project_key import project_key
from do_epic.split import SPLIT_LABEL
from agent_cycle import tmux
# Under the home folder, a folder per epic key holds the epic's LOCK. A chunk without a repo works there.
STATE = ".local/state/do-epic"
# The flag that tells the do-epic in a window its chunk, as `--chunk ABC-34 ABC-12`. Nobody types it, so no panel picked it.
CHUNK_FLAG = "--chunk"
@dataclasses.dataclass(frozen=True)
class Chunk:
"""An issue to work as one chunk, in the window named for its key."""
issue: str
# The name of the repo it changes; None for work without a repo.
repo: str | None
@dataclasses.dataclass(frozen=True)
class Waits:
"""An open issue that doesn't run now, and why."""
issue: str
reason: str
@dataclasses.dataclass(frozen=True)
class Started:
# The issues whose chunks started.
started: list[str]
waits: list[Waits]
@dataclasses.dataclass(frozen=True)
class RepoRoom:
"""What limits the chunks in one repo's checkout."""
# The repo's `parallel-chunks`.
limit: int
# How many chunks of any epic run there.
running: int
# Whether a loop-claude runs chunks there.
loop_claude: bool
@dataclasses.dataclass(frozen=True)
class Epic:
"""The epic whose chunks start."""
key: str
# How many of its chunks may run at once.
cap: int
# The checkout of the repo with this name and its `parallel-chunks`, or why the repo cannot be used.
locate: typing.Callable[[str], tuple[pathlib.Path, int] | Failure]
home: pathlib.Path
# The do-epic script each window runs.
launcher: pathlib.Path
env: typing.Mapping[str, str]
@property
def folder(self) -> pathlib.Path:
return self.home / STATE / self.key
def chunks(issues: list[EpicIssue]) -> tuple[list[Chunk], list[Waits]]:
"""The open issues to work as chunks, in the tracker's rank order, and those that wait. An item split by repo is worked through its sub-tasks, and what blocks it blocks them. A blocker outside the epic blocks until the human removes the link, since its state is unknown."""
by_key = {issue.key: issue for issue in issues}
found: list[Chunk] = []
waits: list[Waits] = []
for issue in issues:
if issue.done or SPLIT_LABEL in issue.labels:
continue
pick = recorded(issue)
parent = by_key.get(issue.parent)
blocking = [key for key in (*issue.blockers, *(parent.blockers if parent else ())) if key not in by_key or not by_key[key].done]
outside = [key for key in blocking if key not in by_key]
if isinstance(pick, Failure):
waits.append(Waits(issue.key, pick.reason))
elif pick is None:
waits.append(Waits(issue.key, "no label names its repo"))
elif isinstance(pick, HumanTask):
waits.append(Waits(issue.key, "it is a human's task"))
elif blocking:
waits.append(Waits(issue.key, f"{' and '.join(blocking)} block{'s' if len(blocking) == 1 else ''} it" + (f"; do-epic cannot see {' and '.join(outside)}, outside the epic, finish: remove such a link in Jira once its issue is done" if outside else "")))
else:
found.append(Chunk(issue.key, pick.name if isinstance(pick, Repo) else None))
return found, waits
def refusal(repo: str, room: RepoRoom) -> str | None:
"""Why the repo takes no further chunk; None where it takes one."""
if room.loop_claude:
return f"loop-claude runs chunks in {repo}"
if room.running >= room.limit:
return f"{repo} runs as many chunks as its `{PARALLEL_CHUNKS}` allows: {room.limit}"
return None
def start_chunks(epic: Epic, issues: list[EpicIssue], own: str | None, run: tmux.Tmux) -> Started | Failure:
"""Starts a do-epic in a new window for each of the epic's chunks that may start now. own is the issue of the chunk that asks, which has finished: it counts as running nowhere, and no stopped chunk starts again. Where own is None, the human's `do-epic <EPIC-KEY>` asks, and each stopped chunk starts again. A Failure says why a window could not start; those before it run."""
session = tmux.session_name(tmux.EPIC, epic.key)
found, waits = chunks(issues)
started: list[str] = []
try:
with starting(epic.folder):
windows = tmux.listed(session, run)
running = {window.name for window in windows if not window.dead} - {own}
stopped = {window.name for window in windows if window.dead} - running
for chunk in found:
if chunk.issue in running or chunk.issue == own:
continue
if own and chunk.issue in stopped:
waits.append(Waits(chunk.issue, f"its window stopped; run `do-epic {epic.key}` to start it again"))
elif len(running) + len(started) >= epic.cap:
waits.append(Waits(chunk.issue, f"the epic runs as many chunks as its `{CAP}` line allows: {epic.cap}"))
else:
now = start_chunk(epic, chunk, own, windows, run)
if isinstance(now, Failure):
return now
if isinstance(now, str):
waits.append(Waits(chunk.issue, now))
else:
windows = now
started.append(chunk.issue)
except OSError as failure:
return Failure(f"cannot lock {failure.filename or epic.folder / LOCK}: {failure.strerror}")
return Started(started, sorted(waits, key=lambda wait: [issue.key for issue in issues].index(wait.issue)))
def start_chunk(epic: Epic, chunk: Chunk, own: str | None, windows: list[tmux.Listed], run: tmux.Tmux) -> list[tmux.Listed] | str | Failure:
"""Starts chunk's window beside windows, the epic's session's, and returns the session's windows afterwards; the reason where its repo takes no chunk now, and a Failure where tmux started none. It holds the repo's lock from the check to the start. Raises OSError where that lock cannot be taken."""
session = tmux.session_name(tmux.EPIC, epic.key)
handed = {name: value for name, value in epic.env.items() if name.startswith(HANDED)}
command = [str(epic.launcher), CHUNK_FLAG, chunk.issue, epic.key]
if chunk.repo is None:
return tmux.start_chunk(tmux.Window(session, chunk.issue, ""), str(epic.folder), handed, command, windows, False, run)
located = epic.locate(chunk.repo)
if isinstance(located, Failure):
return located.reason
checkout, limit = located
with starting(project_lock(str(checkout), epic.home)):
if reason := refusal(chunk.repo, room_in(str(checkout), limit, (session, own), epic.home, run)):
return reason
return tmux.start_chunk(tmux.Window(session, chunk.issue, ""), str(checkout), handed, command, windows, False, run)
def room_in(checkout: str, limit: int, leaving: tuple[str, str | None], home: pathlib.Path, run: tmux.Tmux) -> RepoRoom:
"""The room in a repo's checkout under its limit. leaving is the session and name of a window whose chunk finished, which no longer counts."""
theirs = [placed for placed in epic_chunks(checkout, run) if (placed.session, placed.window.name) != leaving]
loop_session = tmux.session_name(tmux.LOOP, project_key(checkout, home))
loops = any(not window.dead for window in tmux.listed(loop_session, run)) and tmux.owner(loop_session, run) == checkout
return RepoRoom(limit, len(theirs), loops)
+425
View File
@@ -0,0 +1,425 @@
import contextlib
import dataclasses
import io
import json
import pathlib
import shutil
import subprocess
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic import chunk_prompt, main
from project_config.test_project_config import configured
from do_epic.backend.protocol import EpicIssue
from do_epic.epic_record import EpicRecord
from agent_cycle import escalation_mark, judge, tmux
from failure import Failure
from loop_claude.test_loop_claude import FakeEffects, judged, Worker
from do_epic.test_scheduler import issue
from loop_claude.loop.this_loop import Loop
from loop_claude.loop.reload import LoopRun
from do_epic.backend.fake import MemoryEpic
from loop_state.paths import paths_from
from model_routing.route import Route
from model_routing.ladder import Rung
from do_epic.test_do_epic import SETTINGS
DESCRIPTION = "**Max parallel chunks:** 2\n\n## Goals\nShip the import.\n\n## Audience\nThe client's team.\n"
@dataclasses.dataclass(frozen=True)
class Description:
"""Stands in for an epic's description in Jira."""
text: str | Failure
def read(self) -> str | Failure:
return self.text
class DoEpicTest(unittest.TestCase):
def setUp(self) -> None:
made = tempfile.TemporaryDirectory()
self.addCleanup(made.cleanup)
self.home = pathlib.Path(made.name).resolve()
folder = self.home / ".claude-projects" / "do-epic"
folder.mkdir(parents=True)
(folder / "config.toml").write_text(SETTINGS, encoding="utf-8")
(folder / "repo-rule.md").write_text("A label that equals a repo's name names that repo.\n", encoding="utf-8")
self.issues = [issue("ABC-20"), dataclasses.replace(issue("ABC-21", "do-epic-claude"), detail="Tidy the docs.", scores={"L": 3, "E": 2, "I": 3})]
self.description: str | Failure = DESCRIPTION
def backend(self, config: object, key: str) -> tuple[MemoryEpic, EpicRecord]:
return MemoryEpic(key, list(self.issues)), EpicRecord(Description(self.description)) # type: ignore[arg-type]
def run_main(self, argv: list[str], fake: FakeEffects, env: dict[str, str] | None = None) -> tuple[int, str, str]:
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
code = main.main(argv, env or {}, paths_from(self.home), pathlib.Path("/b/do-epic"), fake.effects(), self.backend)
return code, out.getvalue(), err.getvalue()
class TheLauncher(unittest.TestCase):
def test_the_repo_ships_a_do_epic_that_prints_its_help(self) -> None:
launcher = pathlib.Path(__file__).resolve().parents[1] / "do-epic"
ran = subprocess.run([str(launcher), "--help"], capture_output=True, text=True, timeout=60)
self.assertEqual((ran.returncode, ran.stdout.split(" ", 2)[2]), (0, main.HELP + "\n"))
tracked = subprocess.run(["git", "ls-files", "--error-unmatch", launcher.name], capture_output=True, cwd=launcher.parent)
self.assertEqual(tracked.returncode, 0, "bin/do-epic is not in the repo; .gitignore lists what it keeps")
class TheCommand(DoEpicTest):
def test_prints_the_help_for_anything_but_one_epic_key(self) -> None:
for argv, code in ((["--help"], 0), (["-h"], 0), ([], 1), (["abc"], 1), (["ABC-12", "ABC-13"], 1), (["--chunk", "x", "ABC-12"], 1), (["--chunk", "ABC-12"], 1)):
with self.subTest(argv=argv):
ran_code, out, err = self.run_main(argv, FakeEffects())
self.assertEqual((ran_code, (err if code else out).split(" ", 1)[1]), (code, main.HELP + "\n"))
def test_refuses_a_tmux_too_old_naming_do_epic(self) -> None:
code, _, err = self.run_main(["ABC-12"], FakeEffects(tmux_version="tmux 3.1"))
self.assertEqual(code, 1)
self.assertIn("do-epic runs each chunk in a tmux window, and needs tmux 3.2 or later; it found tmux 3.1", err)
def test_starts_the_chunks_and_says_why_each_other_issue_waits(self) -> None:
fake = FakeEffects(on_terminal=False)
code, out, _ = self.run_main(["ABC-12"], fake, {"LOOP_CLAUDE_WORKER_MODEL": "m"})
self.assertEqual(code, 0)
self.assertIn("started ABC-21 in the tmux session epic-ABC-12\n", out)
self.assertIn("ABC-20 waits: no label names its repo\n", out)
started = [args for args in fake.tmux_calls if args[0] == "new-session"]
self.assertEqual(started, [["new-session", "-d", "-s", "epic-ABC-12", "-n", "ABC-21", "-c", str(self.home / ".local/state/do-epic/ABC-12"), "-e", "LOOP_CLAUDE_WORKER_MODEL=m", "-P", "-F", "#{window_id}", "--", "/b/do-epic", "--chunk", "ABC-21", "ABC-12"]])
# The session is no checkout's, so nothing marks it as one's.
self.assertNotIn(tmux.OWNER, [args[3] for args in fake.tmux_calls if args[0] == "set-option"])
def test_stops_on_an_epic_it_cannot_read(self) -> None:
self.description = Failure("Jira answered 401")
code, _, err = self.run_main(["ABC-12"], FakeEffects())
self.assertEqual(code, 1)
self.assertIn("Jira answered 401\n", err)
def test_a_chunk_outside_a_tmux_window_says_how_to_run_do_epic(self) -> None:
fake = FakeEffects()
code, _, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], fake)
self.assertEqual(code, 1)
self.assertIn("--chunk is how do-epic starts itself in a tmux window; run do-epic <EPIC-KEY>\n", err)
self.assertEqual(fake.dms, ["do-epic --chunk ABC-21 ABC-12 stopped: --chunk is how do-epic starts itself in a tmux window; run do-epic <EPIC-KEY>"])
def test_a_chunk_of_an_issue_the_epic_lacks_stops(self) -> None:
code, _, err = self.run_main(["--chunk", "ABC-99", "ABC-12"], FakeEffects(), {"TMUX_PANE": "%1"})
self.assertEqual(code, 1)
self.assertIn("ABC-99 is no issue of the epic ABC-12\n", err)
class ACycleOfAChunkWithoutARepo(DoEpicTest):
def cycle(self, env: dict[str, str] | None = None) -> main.Cycle:
fake = FakeEffects(git=[Failure("no git"), Failure("no git")])
paths = paths_from(self.home)
config = main.load(self.home)
assert not isinstance(config, Failure)
store, record = self.backend(config, "ABC-12")
epic = main.EpicRun("ABC-12", config, store, record, paths, env or {}, pathlib.Path("/b/do-epic"), fake.effects())
place = main.chunk_root(self.issues[1], epic)
assert isinstance(place, tuple)
root, in_repo = place
loop = Loop(root=root, session=main.session_named("A ABC-12 do-epic ABC-21", paths.claude_code_transcripts), window=tmux.Window("epic-ABC-12", "ABC-21", "%1"), paths=paths, env=env or {}, launcher=pathlib.Path("/b/do-epic"), effects=fake.effects())
with contextlib.redirect_stdout(io.StringIO()):
found = main.next_cycle(LoopRun(1, root, "", "", chunk="ABC-21"), loop, in_repo, epic)
assert isinstance(found, main.Cycle), found
return found
def test_routes_on_the_repoless_model_by_the_issues_scores(self) -> None:
cycle = self.cycle()
assert cycle.project is not None
self.assertEqual(cycle.project.rung.model, "claude-opus-5-5")
self.assertEqual(cycle.route, Route(cycle.project.worker_rung(3), 21, 3, 5))
self.assertEqual(cycle.judge.model, "claude-opus-5-5")
self.assertEqual(self.cycle({"LOOP_CLAUDE_WORKER_MODEL": "off-the-ladder"}).route, Route(Rung("off-the-ladder")))
self.assertEqual(self.cycle({"LOOP_CLAUDE_JUDGE_MODEL": "claude-fable-5-2"}).judge.model, "claude-fable-5-2")
def test_works_in_the_epics_folder_and_archives_apart_from_loop_claude(self) -> None:
cycle = self.cycle()
self.assertEqual((cycle.root, cycle.project_archive, cycle.records), (str(self.home / ".local/state/do-epic/ABC-12"), self.home / ".claude/do-epic-transcripts/ABC-12", ""))
def test_the_premises_are_the_epics_goals_and_audience(self) -> None:
self.assertEqual(self.cycle().premises, "the epic ABC-12's description:\n## Goals\nShip the import.\n\n## Audience\nThe client's team.")
def test_the_task_is_the_issue(self) -> None:
self.assertEqual(self.cycle().task, "Work the Jira issue ABC-21 of the epic ABC-12 as one chunk, which changes no repo: work in the folder you start in. Its summary: Do ABC-21\n\nIts description:\n\nTidy the docs.")
def test_an_issue_without_scores_runs_on_the_projects_rung(self) -> None:
self.issues[1] = dataclasses.replace(self.issues[1], scores={})
cycle = self.cycle()
assert cycle.project is not None
self.assertEqual(cycle.route, Route(cycle.project.rung))
UNREAD = [Failure("no git")] * 20
MODELS = {"LOOP_CLAUDE_JUDGE_MODEL": "claude-opus-5-5", "LOOP_CLAUDE_WORKER_MODEL": "claude-opus-5-5", "TMUX_PANE": "%1"}
class TheHumansRun(DoEpicTest):
def test_shows_the_session_on_a_terminal_and_says_when_tmux_cannot(self) -> None:
fake = FakeEffects(windows="ABC-21\t0\t@9\n")
self.assertEqual(self.run_main(["ABC-12"], fake)[0], 0)
self.assertEqual(fake.tmux_calls[-1], ["attach-session", "-t", "=epic-ABC-12"])
fake.effects = lambda made=fake.effects(): dataclasses.replace(made, tmux_on_terminal=lambda args: 1) # type: ignore[method-assign]
code, _, err = self.run_main(["ABC-12"], fake, {"TMUX": "/tmp/tmux"})
self.assertEqual((code, err.split(" ", 1)[1]), (1, "`tmux switch-client -t =epic-ABC-12` failed; the chunks go on in the tmux session\n"))
def test_off_a_terminal_it_says_how_to_see_the_chunks(self) -> None:
code, out, err = self.run_main(["ABC-12"], FakeEffects(on_terminal=False, windows="ABC-21\t0\t@9\n"))
self.assertEqual((code, err), (0, ""))
self.assertIn("not on a terminal; see the chunks with `tmux attach -t =epic-ABC-12`\n", out)
def test_with_no_window_in_the_session_it_shows_none(self) -> None:
self.issues = self.issues[:1]
fake = FakeEffects()
code, out, _ = self.run_main(["ABC-12"], fake)
self.assertEqual(code, 0)
self.assertIn("started no chunk\n", out)
self.assertNotIn("attach-session", [args[0] for args in fake.tmux_calls])
def test_stops_without_its_settings_or_on_a_cap_it_cannot_read(self) -> None:
self.description = "**Max parallel chunks:** many\n"
code, _, err = self.run_main(["ABC-12"], FakeEffects())
self.assertEqual(code, 1)
self.assertIn("`**Max parallel chunks:** many`, which is not a whole number of 1 or more", err)
(self.home / ".claude-projects/do-epic/config.toml").unlink()
code, out, err = self.run_main(["ABC-12"], FakeEffects())
self.assertEqual((code, out), (1, ""))
self.assertIn("config.toml", err)
def test_an_interrupt_from_the_keyboard_ends_it_quietly_and_a_crash_is_sent_on(self) -> None:
fake = FakeEffects()
fake.tmux = lambda args: (_ for _ in ()).throw(KeyboardInterrupt()) # type: ignore[method-assign]
self.assertEqual(self.run_main(["ABC-12"], fake), (130, "", ""))
fake.tmux = lambda args: (_ for _ in ()).throw(ValueError("boom")) # type: ignore[method-assign]
with self.assertRaises(ValueError):
self.run_main(["ABC-12"], fake)
self.assertEqual(fake.dms, ["do-epic ABC-12 crashed: ValueError('boom')"])
def test_starts_each_chunk_in_its_repos_checkout(self) -> None:
for name in ("api", "web"):
configured(self, self.home / "code" / name, home=self.home)
self.issues = [issue("ABC-20", "repo:api"), issue("ABC-22", "repo:web")]
fake = FakeEffects(on_terminal=False)
code, out, _ = self.run_main(["ABC-12"], fake)
self.assertEqual(code, 0)
self.assertIn("started ABC-20, ABC-22 in the tmux session epic-ABC-12\n", out)
self.assertEqual([args[args.index("-c") + 1] for args in fake.tmux_calls if args[0] in ("new-session", "new-window")], [str(self.home / "code/api"), str(self.home / "code/web")])
def test_clones_a_missing_repo_from_the_host_of_the_repos_located_before_it(self) -> None:
for name in ("api", "web"):
configured(self, self.home / "code" / name, home=self.home)
shutil.rmtree(self.home / "code/web")
self.issues = [issue("ABC-20", "repo:api"), issue("ABC-22", "repo:web")]
fake = FakeEffects(on_terminal=False, git=["git@host.example:team/api.git", ""])
code, out, err = self.run_main(["ABC-12"], fake)
self.assertEqual(code, 0, err)
self.assertIn("started ABC-20, ABC-22 in the tmux session epic-ABC-12\n", out)
clones = [what for seam, what in fake.calls if seam == "git" and "clone" in what]
self.assertEqual([what[what.index("--") + 1:] for what in clones], [["git@host.example:team/web", str(self.home / "code/web")]])
def test_names_a_checkout_as_loop_claude_does_whatever_way_its_config_spells_it(self) -> None:
real = self.home / "code" / "api"
real.mkdir(parents=True)
(self.home / "work").mkdir()
(self.home / "work/api").symlink_to(real)
configured(self, self.home / "work/api", home=self.home)
self.issues = [issue("ABC-20", "repo:api")]
fake = FakeEffects(on_terminal=False)
code, _, err = self.run_main(["ABC-12"], fake)
self.assertEqual(code, 0, err)
self.assertEqual([args[args.index("-c") + 1] for args in fake.tmux_calls if args[0] == "new-session"], [str(real)])
self.assertEqual([args[-2:] for args in fake.tmux_calls if "@chunk-root" in args], [["@chunk-root", str(real)]])
class AChunksRun(DoEpicTest):
def worker(self) -> Worker:
return Worker(paths_from(self.home).claude_code_transcripts.parent)
def test_runs_cycles_until_the_judge_rules_it_finished_then_starts_the_next_chunk(self) -> None:
self.issues.append(issue("ABC-22", "do-epic-claude"))
self.description = DESCRIPTION.replace("2", "1")
fake = FakeEffects(streams=[self.worker(), self.worker()], claude=[judged("unfinished"), judged("finished")], git=UNREAD, windows="ABC-21\t0\t@9\n")
code, out, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
self.assertIn("=== cycle 1, worker on claude-", out)
self.assertIn("=== cycle 2, worker on claude-", out)
self.assertNotIn("=== cycle 3", out)
self.assertIn("the chunk finished; started ABC-22\n", out)
self.assertEqual(fake.dms, [])
archive = self.home / ".claude/do-epic-transcripts/ABC-12"
self.assertTrue(any(archive.iterdir()))
self.assertFalse((self.home / ".claude/loop-claude-transcripts").exists())
streamed = [what for seam, what in fake.calls if seam == "stream_claude"]
self.assertIn("Work the Jira issue ABC-21 of the epic ABC-12 as one chunk", " ".join(streamed[0]))
self.assertNotIn("Work the Jira issue", " ".join(streamed[1]))
def test_every_text_of_a_run_names_do_epic_as_what_drives_it(self) -> None:
fake = FakeEffects(streams=[self.worker()] * 3, claude=[judged("unfinished", escalation="working"), judged("interrupt"), judged("finished")], inputs=["Use B."], git=UNREAD)
code, _, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
prompts = [" ".join(what) for seam, what in fake.calls if seam == "stream_claude"]
judged_with = [" ".join(what[0]) + (what[1] or "") for seam, what in fake.calls if seam == "claude"]
self.assertEqual((len(prompts), len(judged_with)), (3, 3))
for text in (*prompts, *judged_with, *fake.dms, *[str(what) for seam, what in fake.calls if seam == "input"]):
self.assertNotIn("loop-claude", text)
self.assertNotIn("None", text)
self.assertIn(" do-epic runs you on claude-", prompts[1])
self.assertIn("The human answered your question at do-epic's terminal:\nUse B.", prompts[2])
for text in judged_with:
self.assertIn("what do-epic told it on [loop] lines, latest last:\n", text)
self.assertIn("asking do-epic for a higher rung", text)
self.assertIn("do-epic in ", fake.dms[0])
self.assertNotIn("\n\n[step] ", judged_with[0])
self.assertIn("\n\n[step] do-epic stepped the worker up a rung here", judged_with[1])
def test_stops_for_the_human_after_six_unfinished_cycles_naming_do_epic(self) -> None:
fake = FakeEffects(streams=[self.worker()] * 6, claude=[judged("unfinished")] * 6, git=UNREAD)
code, out, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], fake, MODELS)
self.assertEqual(code, 2, out)
self.assertIn("the judge ruled it unfinished 6 cycles running; finish the chunk yourself, or rerun do-epic to give it 6 more cycles", err + out)
def test_a_finished_chunk_says_why_the_next_could_not_start(self) -> None:
store = MemoryEpic("ABC-12", list(self.issues))
reads = iter([self.issues, self.issues, Failure("Jira answered 503")])
store.read = lambda: next(reads) # type: ignore[method-assign]
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD)
code, _, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], fake, MODELS)
self.assertEqual(code, 1)
self.assertIn("the chunk finished, but the next could not start: Jira answered 503\n", err)
def test_a_chunk_in_a_repo_works_in_its_checkout_on_the_repos_premises_and_records(self) -> None:
checkout = self.home / "code" / "api"
configured(self, checkout, home=self.home)
(checkout / "README.md").write_text("## Goals\nServe the API.\n\n## Audience\nIts callers.\n", encoding="utf-8")
(checkout / "AGENTS.md").write_text("Squash every merge.\n", encoding="utf-8")
self.issues = [dataclasses.replace(issue("ABC-20", "repo:api"), scores={"L": 2, "E": 1, "I": 1})]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD)
code, out, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
prompt = " ".join([what for seam, what in fake.calls if seam == "stream_claude"][0])
self.assertIn(f"Work the Jira issue ABC-20 of the epic ABC-12 as one chunk, in the checkout {checkout}, on the branch ABC-20.", prompt)
self.assertIn("Ship the import.", prompt)
self.assertIn("The repo's goals, which rank after the epic's and after code health, are from", prompt)
self.assertIn("Serve the API.", prompt)
self.assertIn("the chunk finished; started no other\n", out)
self.assertIn("Squash every merge.", [what[1] for seam, what in fake.calls if seam == "claude"][0])
def repo_chunk(self) -> pathlib.Path:
"""Makes ABC-20 the one issue, a chunk in the repo api whose checkout holds its premises; the folder of the repo's config."""
checkout = self.home / "code" / "api"
folder = configured(self, checkout, home=self.home)
(checkout / "README.md").write_text("## Goals\nServe the API.\n\n## Audience\nIts callers.\n", encoding="utf-8")
self.issues = [issue("ABC-20", "repo:api")]
return folder
def test_a_chunk_in_a_repo_routes_on_the_repos_model(self) -> None:
folder = self.repo_chunk()
models = self.home / ".claude/loop-claude-models.json"
models.parent.mkdir(parents=True, exist_ok=True)
models.write_text(json.dumps({folder.name: "claude-fable-5-2", "other": "claude-opus-5-5"}), encoding="utf-8")
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD)
code, out, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], fake, {"TMUX_PANE": "%1"})
self.assertEqual(code, 0, err)
self.assertIn("=== cycle 1, worker on claude-fable-5-2 at low effort ===\n", out)
def test_a_chunk_in_a_repo_stops_where_the_repos_ladder_or_records_cannot_be_read(self) -> None:
folder = self.repo_chunk()
(folder / "routing-ladder.json").write_text("[", encoding="utf-8")
code, out, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], FakeEffects(git=UNREAD), MODELS)
self.assertEqual((code, out), (1, ""))
self.assertIn(f"{folder / 'routing-ladder.json'}", err.strip().splitlines()[-1])
(folder / "routing-ladder.json").unlink()
(self.home / "code/api/docs/decisions.md").mkdir(parents=True)
fake = FakeEffects(git=UNREAD)
code, out, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], fake, MODELS)
self.assertEqual((code, out), (1, ""))
self.assertIn("decisions.md", err.strip().splitlines()[-1])
self.assertIn("decisions.md", fake.dms[0])
def test_an_issue_that_is_a_humans_or_names_no_repo_is_no_chunk(self) -> None:
for labels, why in ((("do-epic-human",), "it is a human's task"), ((), "no label names its repo")):
with self.subTest(labels):
self.issues = [issue("ABC-20", *labels)]
fake = FakeEffects(git=UNREAD)
code, _, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], fake, MODELS)
self.assertEqual(code, 1)
self.assertIn(f"ABC-20 is no chunk: {why}\n", err)
self.assertEqual([seam for seam, _ in fake.calls if seam == "stream_claude"], [])
def test_a_chunk_stays_in_its_repo_when_its_labels_change_under_it(self) -> None:
self.repo_chunk()
store = MemoryEpic("ABC-12", list(self.issues))
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
class Relabelling(Worker):
def __call__(inner, *args: object, **kwargs: object) -> object:
store.issues[:] = [issue("ABC-20", "do-epic-claude")]
return super().__call__(*args, **kwargs)
worker = Relabelling(paths_from(self.home).claude_code_transcripts.parent)
fake = FakeEffects(streams=[worker, self.worker()], claude=[judged("unfinished"), judged("finished")], git=UNREAD)
code, _, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], fake, MODELS)
self.assertEqual(code, 0, err)
self.assertIn("Serve the API.", [what[1] for seam, what in fake.calls if seam == "claude"][1])
def test_a_chunk_in_a_repo_without_premises_stops(self) -> None:
configured(self, self.home / "code" / "api", home=self.home)
self.issues = [issue("ABC-20", "repo:api")]
code, _, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], FakeEffects(git=UNREAD), MODELS)
self.assertEqual(code, 1)
self.assertIn("README.md is missing or empty - no premises.\n", err)
def test_a_chunk_stops_where_the_epics_issues_cannot_be_read(self) -> None:
store = MemoryEpic("ABC-12", [])
store.read = lambda: Failure("Jira answered 503") # type: ignore[method-assign]
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
code, _, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], FakeEffects(), MODELS)
self.assertEqual(code, 1)
self.assertIn("Jira answered 503\n", err)
def test_a_chunk_whose_repo_or_premises_cannot_be_read_stops(self) -> None:
self.issues = [issue("ABC-20", "repo:api"), issue("ABC-23", "repo:api", "repo:web")]
code, _, err = self.run_main(["--chunk", "ABC-23", "ABC-12"], FakeEffects(), MODELS)
self.assertEqual(code, 1)
self.assertIn("ABC-23 is labelled with 2 picks", err)
self.issues = [self.issues[0]]
code, _, err = self.run_main(["--chunk", "ABC-20", "ABC-12"], FakeEffects(git=UNREAD), MODELS)
self.assertEqual(code, 1)
self.assertIn("api", err)
self.issues = [issue("ABC-21", "do-epic-claude")]
self.description = "## Goals\nShip.\n"
code, _, err = self.run_main(["--chunk", "ABC-21", "ABC-12"], FakeEffects(git=UNREAD), MODELS)
self.assertEqual(code, 1)
self.assertIn("the epic ABC-12's description has no text under a `## Audience` heading - no premises.\n", err)
class WhatAWorkerJudgeAndHumanRead(DoEpicTest):
def test_every_prompt_names_do_epic_and_never_loop_claude(self) -> None:
cycle = ACycleOfAChunkWithoutARepo.cycle(self) # type: ignore[arg-type]
prompts = cycle.prompts
texts = [
prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.project, ""),
prompts.resumed("the work remaining", cycle.route, cycle.project),
prompts.typed("Which one?", "The first.", cycle.route, cycle.project, True),
judge.judge_rules(prompts.answer_destinations, prompts.driver),
str(judge.judge_schema(prompts.driver)),
]
for text in texts:
self.assertNotIn("loop-claude", text)
self.assertIn(f"do-epic runs you on {cycle.route.rung}, routed by the issue's L of 3. Where a sentence below names item 21, it means the issue.", texts[0])
self.assertRegex(texts[0], r"it means the issue\.( \S|\n\n)")
self.assertNotIn("Chunk items:", texts[1])
# The worker's prompt and the judge's rules word the request for a higher rung alike, from one place.
for text in (texts[0], texts[3]):
self.assertIn("asking do-epic for a higher rung", text)
self.assertEqual(escalation_mark.asks_higher_rung(chunk_prompt.DRIVER), "asking do-epic for a higher rung")
if __name__ == "__main__":
unittest.main()
+226
View File
@@ -0,0 +1,226 @@
import pathlib
import subprocess
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.scheduler import Chunk, CHUNK_FLAG, chunks, Epic, refusal, RepoRoom, start_chunks, Started, Waits
from do_epic import chunk_prompt
from do_epic.backend.protocol import EpicIssue
from failure import Failure
from do_epic.epic_record import parallel_chunks_in
from loop_claude.cycle import prompts
from model_routing.route import Route
from model_routing.ladder import Rung
from agent_cycle import tmux
def issue(key: str, *labels: str, done: bool = False, blockers: tuple[str, ...] = (), parent: str = "ABC-12") -> EpicIssue:
return EpicIssue(key, f"Do {key}", "", tuple(sorted(labels)), None, "Done" if done else "To Do", done, parent, blockers=blockers)
class TheCapLine(unittest.TestCase):
def test_reads_the_epics_cap(self) -> None:
self.assertEqual(parallel_chunks_in("**Language:** Swedish\n**Max parallel chunks:** 3\n\n## Goals\nShip.\n"), 3)
def test_an_epic_without_the_line_runs_one_chunk_at_once(self) -> None:
self.assertEqual(parallel_chunks_in("## Goals\nShip.\n"), 1)
self.assertEqual(parallel_chunks_in("```\n**Max parallel chunks:** 3\n```\n"), 1)
def test_refuses_a_line_that_nearly_spells_the_cap(self) -> None:
for line in ("**Max parallel chunks**: 2", "Max parallel chunks: 2", "**max parallel chunks:** 2", "- **Max parallel chunks:** 2"):
found = parallel_chunks_in(f"## Goals\nShip.\n{line}\n")
assert isinstance(found, Failure), line
self.assertEqual(found.reason, f"the epic's description holds the line `{line}`, which do-epic doesn't read as the epic's cap: write it as a line of its own, spelt `**Max parallel chunks:** 2`")
self.assertEqual(parallel_chunks_in("We raise the max parallel chunks later.\n```\nMax parallel chunks: 2\n```\n"), 1)
def test_refuses_a_cap_that_is_no_whole_number_of_1_or_more(self) -> None:
for value in ("0", "many", "2.5", "-1", ""):
found = parallel_chunks_in(f"**Max parallel chunks:** {value}\n")
assert isinstance(found, Failure)
self.assertEqual(found.reason, f"the epic's description caps its chunks with `**Max parallel chunks:** {value}`, which is not a whole number of 1 or more, such as `**Max parallel chunks:** 2`")
class WhichIssuesAreChunks(unittest.TestCase):
def test_an_open_issue_with_a_repo_or_claude_work_is_a_chunk_in_rank_order(self) -> None:
found = chunks([issue("ABC-20", "repo:api"), issue("ABC-21", "do-epic-claude"), issue("ABC-22", "repo:web", done=True)])
self.assertEqual(found, ([Chunk("ABC-20", "api"), Chunk("ABC-21", None)], []))
def test_a_split_item_is_no_chunk_but_its_sub_tasks_are(self) -> None:
found = chunks([issue("ABC-20", "split-by-repo"), issue("ABC-23", "repo:api", parent="ABC-20"), issue("ABC-24", "repo:web", parent="ABC-20")])
self.assertEqual(found, ([Chunk("ABC-23", "api"), Chunk("ABC-24", "web")], []))
def test_an_issue_waits_for_its_pick_its_human_and_its_blockers(self) -> None:
found = chunks([
issue("ABC-20"),
issue("ABC-21", "do-epic-human"),
issue("ABC-22", "repo:api", "repo:web"),
issue("ABC-23", "repo:api", blockers=("ABC-20", "ABC-30", "XYZ-1")),
issue("ABC-30", "repo:api", done=True),
])
self.assertEqual(found, ([], [
Waits("ABC-20", "no label names its repo"),
Waits("ABC-21", "it is a human's task"),
Waits("ABC-22", "ABC-22 is labelled with 2 picks: repo:api, repo:web; remove all but the right one"),
Waits("ABC-23", "ABC-20 and XYZ-1 block it; do-epic cannot see XYZ-1, outside the epic, finish: remove such a link in Jira once its issue is done"),
]))
def test_what_blocks_a_split_item_blocks_its_sub_tasks(self) -> None:
found = chunks([issue("ABC-19", "repo:api"), issue("ABC-20", "split-by-repo", blockers=("ABC-19",)), issue("ABC-23", "repo:api", parent="ABC-20")])
self.assertEqual(found, ([Chunk("ABC-19", "api")], [Waits("ABC-23", "ABC-19 blocks it")]))
class RoomInARepo(unittest.TestCase):
def test_a_repo_with_room_and_no_loop_claude_takes_a_chunk(self) -> None:
self.assertIsNone(refusal("api", RepoRoom(limit=2, running=1, loop_claude=False)))
def test_a_full_repo_takes_none(self) -> None:
self.assertEqual(refusal("api", RepoRoom(limit=2, running=2, loop_claude=False)), "api runs as many chunks as its `parallel-chunks` allows: 2")
def test_a_repo_loop_claude_runs_chunks_in_takes_none(self) -> None:
self.assertEqual(refusal("api", RepoRoom(limit=2, running=0, loop_claude=True)), "loop-claude runs chunks in api")
class Tmux:
"""Stands in for tmux: `windows` are the rows of `list-windows -a`, as session, name, dead and root; a started window joins them."""
def __init__(self, *windows: tuple[str, str, bool, str], owners: dict[str, str] | None = None) -> None:
self.windows, self.owners, self.calls = list(windows), owners or {}, []
def __call__(self, args: list[str]) -> subprocess.CompletedProcess[str]:
self.calls.append(args)
out = ""
if args[0] == "list-windows" and "-a" in args:
out = "".join(f"{session}\t{name}\t{int(dead)}\t@{at}\t{root}\n" for at, (session, name, dead, root) in enumerate(self.windows))
elif args[0] == "list-windows":
out = "".join(f"{name}\t{int(dead)}\t@{at}\n" for at, (session, name, dead, _) in enumerate(self.windows) if f"={session}" == args[2])
elif args[0] == "show-options":
out = self.owners.get(args[3].removeprefix("=").removesuffix(":"), "") + "\n"
elif args[0] in ("new-session", "new-window"):
session = args[args.index("-s") + 1] if args[0] == "new-session" else args[args.index("-t") + 1].removeprefix("=").removesuffix(":")
self.windows.append((session, args[args.index("-n") + 1], False, args[args.index("-c") + 1]))
out = f"@{len(self.windows) - 1}\n"
elif args[0] == "kill-window":
self.windows[int(args[2].removeprefix("@"))] = ("", "", True, "")
return subprocess.CompletedProcess(args, 0, out, "")
def started(self) -> list[tuple[str, str, str]]:
"""Each window started, as its session, its name and its command's words after the launcher."""
return [(args[3].removeprefix("=").removesuffix(":"), args[args.index("-n") + 1], " ".join(args[args.index("--") + 2:])) for args in self.calls if args[0] in ("new-session", "new-window")]
class StartingAnEpicsChunks(unittest.TestCase):
def setUp(self) -> None:
folder = tempfile.TemporaryDirectory()
self.addCleanup(folder.cleanup)
self.home = pathlib.Path(folder.name)
def epic(self, cap: int, **limits: int) -> Epic:
"""An epic whose repos are checked out under the home folder, each with its `parallel-chunks`."""
def locate(name: str) -> tuple[pathlib.Path, int] | Failure:
return (self.home / "code" / name, limits[name]) if name in limits else Failure(f"no project config names {name}")
return Epic("ABC-12", cap, locate, self.home, pathlib.Path("/bin/do-epic"), {"LOOP_CLAUDE_X": "1", "OTHER": "2"})
def start(self, epic: Epic, issues: list[EpicIssue], run: Tmux, own: str | None = None) -> Started:
found = start_chunks(epic, issues, own, run)
assert not isinstance(found, Failure), found
return found
def test_starts_a_window_per_chunk_up_to_the_epics_cap(self) -> None:
run = Tmux()
found = self.start(self.epic(2, api=1, web=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "do-epic-claude"), issue("ABC-22", "repo:web")], run)
self.assertEqual(found, Started(["ABC-20", "ABC-21"], [Waits("ABC-22", "the epic runs as many chunks as its `**Max parallel chunks:**` line allows: 2")]))
self.assertEqual(run.started(), [("epic-ABC-12", "ABC-20", f"{CHUNK_FLAG} ABC-20 ABC-12"), ("epic-ABC-12", "ABC-21", f"{CHUNK_FLAG} ABC-21 ABC-12")])
self.assertEqual([args[args.index("-c") + 1] for args in run.calls if args[0] in ("new-session", "new-window")], [str(self.home / "code/api"), str(self.home / ".local/state/do-epic/ABC-12")])
self.assertIn("LOOP_CLAUDE_X=1", run.calls[[args[0] for args in run.calls].index("new-session")])
self.assertNotIn("OTHER=2", run.calls[[args[0] for args in run.calls].index("new-session")])
def test_a_running_chunk_counts_and_is_not_started_twice(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20 ?", False, str(self.home / "code/api")))
found = self.start(self.epic(2, api=2), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api"), issue("ABC-22", "repo:api")], run)
self.assertEqual(found, Started(["ABC-21"], [Waits("ABC-22", "the epic runs as many chunks as its `**Max parallel chunks:**` line allows: 2")]))
def test_a_repo_takes_its_parallel_chunks_across_epics(self) -> None:
run = Tmux(("epic-XYZ-1", "XYZ-5", False, str(self.home / "code/api")))
found = self.start(self.epic(3, api=1, web=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:web")], run)
self.assertEqual(found, Started(["ABC-21"], [Waits("ABC-20", "api runs as many chunks as its `parallel-chunks` allows: 1")]))
def test_never_starts_in_a_repo_loop_claude_runs_chunks_in(self) -> None:
run = Tmux(("loop-api", "item-3", False, str(self.home / "code/api")), owners={"loop-api": str(self.home / "code/api")})
found = self.start(self.epic(3, api=2), [issue("ABC-20", "repo:api")], run)
self.assertEqual(found, Started([], [Waits("ABC-20", "loop-claude runs chunks in api")]))
def test_a_stopped_loop_claude_window_keeps_no_repo(self) -> None:
run = Tmux(("loop-api", "item-3", True, str(self.home / "code/api")), owners={"loop-api": str(self.home / "code/api")})
self.assertEqual(self.start(self.epic(3, api=2), [issue("ABC-20", "repo:api")], run).started, ["ABC-20"])
def test_a_repo_that_cannot_be_located_waits_with_the_reason(self) -> None:
found = self.start(self.epic(3), [issue("ABC-20", "repo:api")], Tmux())
self.assertEqual(found, Started([], [Waits("ABC-20", "no project config names api")]))
def test_the_human_restarts_a_stopped_chunk_in_place_of_its_window(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20", True, str(self.home / "code/api")))
self.assertEqual(self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api")], run).started, ["ABC-20"])
self.assertIn(["kill-window", "-t", "@0"], run.calls)
def test_a_finished_chunk_leaves_its_room_and_restarts_no_stopped_chunk(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20", False, str(self.home / "code/api")), ("epic-ABC-12", "ABC-21", True, str(self.home / "code/api")))
found = self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api"), issue("ABC-22", "repo:api")], run, own="ABC-20")
self.assertEqual(found, Started(["ABC-22"], [Waits("ABC-21", "its window stopped; run `do-epic ABC-12` to start it again")]))
def test_holds_each_repos_starting_lock_that_loop_claude_holds(self) -> None:
self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api")], Tmux())
self.assertTrue((self.home / ".local/state/loop-claude/api/starting").is_file())
self.assertTrue((self.home / ".local/state/do-epic/ABC-12/starting").is_file())
def test_the_waits_keep_the_trackers_rank_order(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20", True, str(self.home / "code/api")), ("epic-ABC-12", "ABC-22", False, str(self.home / "code/api")))
found = self.start(self.epic(1, api=1), [issue("ABC-20", "repo:api"), issue("ABC-21"), issue("ABC-22", "repo:api")], run, own="ABC-22")
self.assertEqual([wait.issue for wait in found.waits], ["ABC-20", "ABC-21"])
def test_a_chunks_window_never_marks_the_session_as_a_checkouts(self) -> None:
run = Tmux()
self.start(self.epic(2, api=1), [issue("ABC-20", "repo:api"), issue("ABC-21", "do-epic-claude")], run)
options = [args[-2] for args in run.calls if args[0] == "set-option"]
self.assertIn(tmux.ROOT, options)
self.assertNotIn(tmux.OWNER, options)
def test_says_which_lock_it_could_not_take(self) -> None:
(self.home / ".local/state/do-epic").mkdir(parents=True)
(self.home / ".local/state/do-epic/ABC-12").write_text("", encoding="utf-8")
found = start_chunks(self.epic(1, api=1), [issue("ABC-20", "repo:api")], None, Tmux())
assert isinstance(found, Failure)
self.assertRegex(found.reason, f"^cannot lock {self.home}/.local/state/do-epic/ABC-12: \\w")
class TheFirstPrompt(unittest.TestCase):
def test_the_task_names_the_checkout_and_branch_and_quotes_a_description_only_where_there_is_one(self) -> None:
self.assertEqual(chunk_prompt.task(issue("ABC-20"), "ABC-12", "/code/api"), "Work the Jira issue ABC-20 of the epic ABC-12 as one chunk, in the checkout /code/api, on the branch ABC-20. Its summary: Do ABC-20")
def test_opens_with_the_task_then_the_rung_then_the_premises(self) -> None:
rest = f"The issue sets the chunk's scope. The goals below choose between ways to deliver that scope, and never widen it. The epic's goals rank first, then code health ({chunk_prompt.CODE_HEALTH}), then the repo's.\n\nFrom P"
start = f"T\n\nContinue any open draft PR or worktree for the chunk before creating a new one. {prompts.READING_RULE}\n\n"
self.assertEqual(chunk_prompt.fresh("T", "P", Route(Rung("off-the-ladder")), None, ""), start + rest)
routed = chunk_prompt.fresh("T", "P", Route(Rung("off-the-ladder"), 21, 3, 5), None, "")
self.assertTrue(routed.startswith(start + "do-epic runs you on off-the-ladder, routed by the issue's L of 3. Where a sentence below names item 21, it means the issue."), routed)
self.assertTrue(routed.endswith("\n\n" + rest), routed)
class WindowsAcrossSessions(unittest.TestCase):
def test_lists_each_window_with_its_session_and_root(self) -> None:
run = Tmux(("epic-ABC-12", "ABC-20 ?", False, "/code/api"), ("loop-api", "item-3", True, ""))
self.assertEqual(tmux.everywhere(run), [tmux.Placed("epic-ABC-12", tmux.Listed("ABC-20", "@0", False), "/code/api"), tmux.Placed("loop-api", tmux.Listed("item-3", "@1", True), "")])
self.assertEqual(run.calls, [["list-windows", "-a", "-F", f"#{{session_name}}\t#{{window_name}}\t#{{pane_dead}}\t#{{window_id}}\t#{{{tmux.ROOT}}}"]])
def test_without_a_tmux_server_there_are_none(self) -> None:
self.assertEqual(tmux.everywhere(lambda args: subprocess.CompletedProcess(args, 1, "epic-ABC-12\tABC-20\t0\t@0\t/code/api\n", "")), [])
def test_a_started_chunk_joins_the_sessions_windows_as_running(self) -> None:
found = tmux.start_chunk(tmux.Window("epic-ABC-12", "ABC-20", ""), "/code/api", {}, ["do-epic"], [tmux.Listed("ABC-20", "@0", True), tmux.Listed("ABC-21", "@1", False)], False, Tmux(("epic-ABC-12", "ABC-20", True, "/code/api"), ("epic-ABC-12", "ABC-21", False, "/code/api")))
self.assertEqual(found, [tmux.Listed("ABC-21", "@1", False), tmux.Listed("ABC-20", "", False)])
if __name__ == "__main__":
unittest.main()
+7 -6
View File
@@ -1,8 +1,8 @@
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS, DRIVER
from claude_code.entries import Entry
from agent_cycle import escalation_mark
from failure import Failure
from agent_cycle.judge import Grounds, judge_rules, TASK_HEADING, TRANSCRIPT_HEADING
from agent_cycle.judge import Grounds, judge_rules, TASK_HEADING, transcript_heading
from claude_code.transcript import human_answers
from agent_cycle.worker_prompts import typed_answer
@@ -10,7 +10,8 @@ from agent_cycle.worker_prompts import typed_answer
def grounds_of(prompt: str, entries: list[Entry]) -> Grounds | Failure:
"""What the quotes of a judge run on prompt are checked against, as judge_prompt would have made it for the transcript's entries: the premises and the records before the task are quotable, the transcript the judge was shown comes before the rules. The prompt is split on the headings judge_prompt writes, at the first of each; a Failure where it lacks one. Rules of an earlier wording stay part of the transcript, a slack that lets an evidence quote them pass."""
before_task, task_heading, after_task = prompt.partition(f"\n\n{TASK_HEADING}")
_, transcript_heading, shown = after_task.partition(TRANSCRIPT_HEADING)
if not (task_heading and transcript_heading):
return Failure(f"the archived prompt lacks the heading {TASK_HEADING.strip()!r} or {TRANSCRIPT_HEADING.strip()!r}, which judge_prompt writes")
return Grounds(shown.removesuffix(f"\n\n{judge_rules(ANSWER_DESTINATIONS)}"), escalation_mark.after_mark(entries, 0), before_task, tuple(human_answers(entries, typed_answer)))
heading = transcript_heading(DRIVER)
_, found_heading, shown = after_task.partition(heading)
if not (task_heading and found_heading):
return Failure(f"the archived prompt lacks the heading {TASK_HEADING.strip()!r} or {heading.strip()!r}, which judge_prompt writes")
return Grounds(shown.removesuffix(f"\n\n{judge_rules(ANSWER_DESTINATIONS, DRIVER)}"), escalation_mark.after_mark(entries, 0), before_task, tuple(human_answers(entries, typed_answer)))
+3 -3
View File
@@ -53,7 +53,7 @@ import pathlib
import sys
import typing
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS, DRIVER
from transcript_archive.location import archive_root, transcript_of
from transcript_archive.read import archived_outcomes
from rung_replay.archive import archiving, print_report, replay_folder
@@ -164,7 +164,7 @@ def rule(case: Case, rung: Rung, home: pathlib.Path, effects: Effects) -> Kind |
grounds = grounds_of(kept.prompt, entries)
if isinstance(grounds, Failure):
return verdict_kind(grounds)
verdict: Verdict | Failure | Limited = first_reply(lambda: judge_archived(case.root, kept.prompt, grounds, len(entries), rung, effects))
verdict: Verdict | Failure | Limited = first_reply(lambda: judge_archived(case.root, kept.prompt, grounds, len(entries), rung, DRIVER, effects))
return verdict if isinstance(verdict, Limited) else verdict_kind(verdict)
premises, records = read_premises(case.root, home), read_records(case.root, home, home / ".claude")
if isinstance(premises, Failure):
@@ -172,5 +172,5 @@ def rule(case: Case, rung: Rung, home: pathlib.Path, effects: Effects) -> Kind |
if isinstance(records, Failure):
return verdict_kind(records)
# 0 for the route's mark, as before any step-up: the replay compares verdict kinds, and a mark changes only which escalation quotes count.
verdict = first_reply(lambda: judge_once(case.root, Brief(task=case.task, premises=premises, records=records, answer_destinations=ANSWER_DESTINATIONS, entries=entries, escalated_at=0), rung, effects))
verdict = first_reply(lambda: judge_once(case.root, Brief(task=case.task, premises=premises, records=records, answer_destinations=ANSWER_DESTINATIONS, entries=entries, escalated_at=0, driver=DRIVER), rung, effects))
return verdict if isinstance(verdict, Limited) else verdict_kind(verdict)
+6 -6
View File
@@ -9,7 +9,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS, DRIVER
from transcript_archive.outcomes import ANSWERED, FINISHED, INTERRUPTED, UNFINISHED
from claude_code.entries import AssistantTurn, HumanTurn, LoopPrompt, Text
from judge_replay.replay import Case, case_from, report, reproduced, sample, verdict_kind
@@ -19,7 +19,7 @@ from loop_effects.effects import Effects
from failure import Failure
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from judge_replay.archived_prompt import grounds_of
from agent_cycle.judge import judge_archived, judge_rules, Rejected, TASK_HEADING, TRANSCRIPT_HEADING
from agent_cycle.judge import judge_archived, judge_rules, Rejected, TASK_HEADING, transcript_heading
from judge_replay import main
from rung_replay.search import Miss, Replay, Tried
from model_routing.ladder import Rung
@@ -330,7 +330,7 @@ class Main(unittest.TestCase):
class JudgeArchivedRuns(unittest.TestCase):
"""judge_archived on a prompt as judge_prompt writes it: the premises, the task, the transcript the judge was shown, and the rules."""
PROMPT = f"HEAD: Ship fast.\n\n{TASK_HEADING}Do it.\n\n{TRANSCRIPT_HEADING}Worker chose option B.\n[human] Use Postgres.\n\n{judge_rules(ANSWER_DESTINATIONS)}"
PROMPT = f"HEAD: Ship fast.\n\n{TASK_HEADING}Do it.\n\n{transcript_heading(DRIVER)}Worker chose option B.\n[human] Use Postgres.\n\n{judge_rules(ANSWER_DESTINATIONS, DRIVER)}"
ENTRIES = [AssistantTurn(parts=(Text("Worker chose option B."),)), HumanTurn(text="Use Postgres."), LoopPrompt(text="Keep going.")]
def judged(self, prompt=PROMPT, **fields):
@@ -344,7 +344,7 @@ class JudgeArchivedRuns(unittest.TestCase):
effects = Effects(claude=claude, claude_on_terminal=unused, discard_typed=unused, dm=unused, execv=unused, git=unused, input=unused, local_time=unused, memory=unused, now=lambda: 1790000000.0, on_terminal=unused, python=unused, sleep=unused, stream_claude=unused, tmux=unused, tmux_on_terminal=unused)
grounds = grounds_of(prompt, self.ENTRIES)
return (grounds if isinstance(grounds, Failure) else judge_archived("/code/p", prompt, grounds, len(self.ENTRIES), REFERENCE, effects)), cwds
return (grounds if isinstance(grounds, Failure) else judge_archived("/code/p", prompt, grounds, len(self.ENTRIES), REFERENCE, DRIVER, effects)), cwds
def test_runs_in_the_projects_folder_and_stamps_the_verdict_with_the_entries_read(self):
verdict, cwds = self.judged()
@@ -363,11 +363,11 @@ class JudgeArchivedRuns(unittest.TestCase):
self.assertEqual((type(rejected), rejected.cost), (Rejected, 0.25))
def test_checks_neither_the_task_nor_the_rules_as_the_transcript_or_the_premises(self):
self.assertIsInstance(self.judged(evidence=judge_rules(ANSWER_DESTINATIONS))[0], Rejected)
self.assertIsInstance(self.judged(evidence=judge_rules(ANSWER_DESTINATIONS, DRIVER))[0], Rejected)
self.assertIsInstance(self.judged(answer="Do it.", question="Which?")[0], Interrupt)
def test_splits_the_prompt_at_the_first_transcript_heading(self):
quoting = self.PROMPT.replace("Worker chose", f"Quoted: {TRANSCRIPT_HEADING}Worker chose", 1)
quoting = self.PROMPT.replace("Worker chose", f"Quoted: {transcript_heading(DRIVER)}Worker chose", 1)
self.assertIsInstance(self.judged(quoting, evidence="Quoted:")[0], Unfinished)
def test_splits_the_prompt_at_the_first_task_heading(self):
+28 -17
View File
@@ -1,5 +1,9 @@
"""What loop-claude says to the worker each cycle. model_routing.review_choice chooses where the reviews run. review_launches and reruns put that choice into sentences, and escalation says where escalated subagents run; rung_sentences returns the sentences of all three. In a chunk's first prompt, routed_by places them after its routing sentences where an item routed the chunk, and fresh places them alone otherwise. rungs_held repeats them at the end of a prompt after a step-up or an unfinished verdict."""
import functools
import typing
from agent_cycle.worker_prompts import answers_recorded, WorkerPrompts
from agent_cycle.escalation_mark import asks_higher_rung
from model_routing.review_choice import chosen, ReviewChoice
from loop_claude.cycle.chunk_items import CHUNK_ITEMS
from model_routing.route import ESCALATION_MARKER, Route
@@ -9,6 +13,8 @@ from review_rules.review_passes import INSTRUCTION_FILES, INSTRUCTION_FOLDERS
from text_files.markdown_text import listed, quoted
from model_routing.ladder import ProjectRung, Rung
# loop-claude's name as its workers, its judge and the human read it. A function below that takes a driver words a sentence for any entry point, such as do-epic.
DRIVER = "loop-claude"
# Where the judge may quote an answer from, named as the human and the worker see them; of the goals file the judge sees only the premises.
QUOTE_SOURCES = listed(("the goals file's Goals and Audience", *RECORD_FILES, *HUMAN_RULE_NAMES), "or")
# Where the worker may write an answer the human typed, so it counts as recorded.
@@ -29,17 +35,17 @@ NAME_THE_ITEMS = f"Name every plan item this chunk takes on one line, as in `{CH
AFTER_CODE_HEALTH = 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless the goals file voids it'
def fresh(task: str, premises: str, route: Route, project: ProjectRung | None, facts: str) -> str:
def fresh(driver: str, task: str, premises: str, route: Route, project: ProjectRung | None, facts: str) -> str:
"""A chunk's first prompt; facts is preflight_facts' or preflight_failed's text."""
routed = f"{routed_by(route, project)} {recount(route)}" if route.item else " ".join(rung_sentences(route, project))
routed = f"{routed_by(driver, route, project)} {recount(route)}" if route.item else " ".join(rung_sentences(driver, route, project))
opening = f"{routed}\n\n" if routed else ""
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one. {READING_RULE} {NAME_THE_ITEMS}\n\n{opening}{facts}\n\nThe chunk's plan items, or else the task above, set its scope. The goals below, {AFTER_CODE_HEALTH}, choose between ways to deliver that scope, and never widen it.\n\nFrom the goals file, {premises}"
def routed_by(route: Route, project: ProjectRung | None) -> str:
def routed_by(driver: str, route: Route, project: ProjectRung | None) -> str:
return " ".join((
f"loop-claude runs you on {route.rung}, routed by item {route.item}'s L of {route.likelihood}.",
*rung_sentences(route, project),
f"{driver} runs you on {route.rung}, routed by item {route.item}'s L of {route.likelihood}.",
*rung_sentences(driver, route, project),
))
@@ -123,7 +129,7 @@ def rung_named(rung: Rung, route: Route, project: ProjectRung) -> str:
return f"the rung item {route.item}'s E + I of {route.escape_and_impact} picks"
def escalation(route: Route, project: ProjectRung | None) -> list[str]:
def escalation(driver: str, route: Route, project: ProjectRung | None) -> list[str]:
"""The prompt's escalation sentences, the marker's among them. None off the ladder or on its top rung. Where escalation_rungs opens none, the worker escalates only with the human's yes.
Else they name the rungs escalation_rungs opens to a subagent, and offer to resume the worker one rung up for the rest of the chunk, up to the highest of those rungs.
@@ -135,14 +141,14 @@ def escalation(route: Route, project: ProjectRung | None) -> list[str]:
rungs = [f"`{rung.agent_args()}`" for rung in escalation_rungs(project, route)]
if not rungs:
return [
f"An escalation trigger in `~/.claude/CLAUDE.md` lets you hand the hard part of a task to a subagent with the Agent tool set to `{project.ladder.climbed(route.rung, 1).agent_args()}`, one rung above yours, only once the human agrees; loop-claude will not resume you higher for a trigger either, so ask the human for that yes.",
f"An escalation trigger in `~/.claude/CLAUDE.md` lets you hand the hard part of a task to a subagent with the Agent tool set to `{project.ladder.climbed(route.rung, 1).agent_args()}`, one rung above yours, only once the human agrees; {driver} will not resume you higher for a trigger either, so ask the human for that yes.",
marked,
]
further = f", and on each further trigger one rung higher, up to {rungs[-1]}" if len(rungs) > 1 else ""
return [
f"When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to {rungs[0]}, one rung above yours{further}; above that, ask the human first.",
marked,
f"Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to {rungs[-1]}.",
f"Where the hard part is the rest of the chunk, end your run instead, {asks_higher_rung(driver)} and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to {rungs[-1]}.",
]
@@ -163,21 +169,26 @@ def reruns(route: Route, project: ProjectRung | None) -> list[str]:
return [f"A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `{rerun['reviewer'].agent_args()}`, and a comprehension seat with `{rerun['comprehension seat'].agent_args()}`."]
def resumed(unfinished_evidence: str, route: Route, project: ProjectRung | None) -> str:
"""Names the worker's rung, so it learns whether its request for a higher rung went through, and the project's again, since a step-up between cycles may have taken the worker above it."""
on = f" loop-claude runs you on {route.rung}." if project else ""
def resumed(driver: str, naming: str, unfinished_evidence: str, route: Route, project: ProjectRung | None) -> str:
"""naming is the sentence that asks the worker to name its chunk's items, empty where the entry point reads none. Names the worker's rung, so it learns whether its request for a higher rung went through, and the project's again, since a step-up between cycles may have taken the worker above it."""
on = f" {driver} runs you on {route.rung}." if project else ""
ruled = f" A judge ruled the chunk unfinished, quoting this passage of your transcript as the work remaining:\n\n{quoted(unfinished_evidence)}\n\n" if unfinished_evidence else " "
return f"Continue the task; the previous run ended before the chunk was finished.{ruled}The chunk is finished once it is merged, or nothing remains that you could do on your own. Even then, it is finished only once {ANSWERS_RECORDED}. {NAME_THE_ITEMS}{on}{rungs_held(route, project)}"
return f"Continue the task; the previous run ended before the chunk was finished.{ruled}The chunk is finished once it is merged, or nothing remains that you could do on your own. Even then, it is finished only once {ANSWERS_RECORDED}.{naming and f' {naming}'}{on}{rungs_held(driver, route, project)}"
def rung_sentences(route: Route, project: ProjectRung | None) -> list[str]:
def rung_sentences(driver: str, route: Route, project: ProjectRung | None) -> list[str]:
"""The sentences that depend on the worker's rung: where its reviews run and rerun, and where its escalated subagents run."""
return [*review_launches(route, project), *escalation(route, project), *reruns(route, project)]
return [*review_launches(route, project), *escalation(driver, route, project), *reruns(route, project)]
def rungs_held(route: Route, project: ProjectRung | None) -> str:
def rungs_held(driver: str, route: Route, project: ProjectRung | None) -> str:
"""rung_sentences, each after a space, to follow the sentence a prompt ends on."""
return "".join(f" {sentence}" for sentence in rung_sentences(route, project))
return "".join(f" {sentence}" for sentence in rung_sentences(driver, route, project))
WORKER = WorkerPrompts(fresh, resumed, rungs_held, QUOTE_SOURCES, ANSWER_DESTINATIONS)
def worker_prompts(driver: str, fresh: typing.Callable[[str, str, Route, ProjectRung | None, str], str], naming: str) -> WorkerPrompts:
"""The prompts of an entry point's cycles: its own fresh prompt, and the resumed prompt and rung sentences every entry point shares, each naming driver. resumed says what naming is."""
return WorkerPrompts(driver, fresh, functools.partial(resumed, driver, naming), functools.partial(rungs_held, driver), QUOTE_SOURCES, ANSWER_DESTINATIONS)
WORKER = worker_prompts(DRIVER, functools.partial(fresh, DRIVER), NAME_THE_ITEMS)
+3 -3
View File
@@ -6,7 +6,7 @@ from git_cli.git_repo import default_ref
from release_plan.release_standing import DefaultPlan, project_plan, UNSEEN_RELEASES
from loop_effects.effects import Effects, say
from failure import Failure
from agent_cycle.routing import first_route, kept
from agent_cycle.routing import first_route, kept, Scored
from loop_claude.loop.chunk_windows import held_beside, item_of
from chunk_preflight.main import ITEM
from plan.todo_table import Item
@@ -32,7 +32,7 @@ def scored_plan(default: DefaultPlan | Failure, effects: Effects) -> Plan | Fail
return plan
def routed(route: Route | None, project: ProjectRung | None, model: str, archived: typing.Callable[[], Route | None], item: typing.Callable[[], Item | None]) -> Route:
def routed(route: Route | None, project: ProjectRung | None, model: str, archived: typing.Callable[[], Route | None], item: typing.Callable[[], Scored | None]) -> Route:
"""The route the cycle runs on. project is the project's rung, and model the project's model.
Where project is None, the model is off the ladder, and the worker runs on it. Otherwise the chunk keeps route, or on a rerun the route its archive last names, as routing.kept allows. Else the plan item routes the chunk afresh.
@@ -52,7 +52,7 @@ def archived_route(archive_folder: pathlib.Path, loop: Loop) -> Route | None:
return None
route = route_from(worker) if worker else None
if worker and route is None:
say(f"routing the chunk afresh: the archive's latest Worker: line names no route loop-claude can read: {worker}", loop.effects)
say(f"routing the chunk afresh: the archive's latest Worker: line names no route that can be read: {worker}", loop.effects)
return route
+50 -31
View File
@@ -24,7 +24,7 @@ from agent_cycle import tmux
# Under the home folder, a folder per project key holds LOCK.
STATE = ".local/state/loop-claude"
# The file a loop keeps locked with flock while it lists the project's windows and starts new ones, so two loops whose chunks finish together don't start a chunk twice.
# The file an entry point keeps locked with flock while it lists the windows of a project's chunks and starts new ones. Two loops whose chunks finish together then don't start a chunk twice, and do-epic, which holds the same lock, never starts a chunk in a checkout while loop-claude does.
LOCK = "starting"
# The flag that tells the loop in a window its chunk, as `--chunk item-372`. Nobody types it, so no panel picked it.
CHUNK_FLAG = "--chunk"
@@ -52,15 +52,24 @@ def chunk_session(key: str, chunk: str, claude_code_transcripts: pathlib.Path) -
@contextlib.contextmanager
def starting(home: pathlib.Path, key: str) -> typing.Iterator[None]:
"""Holds the project's LOCK. Raises OSError where the file cannot be opened or locked."""
folder = home / STATE / key
def starting(folder: pathlib.Path) -> typing.Iterator[None]:
"""Holds the LOCK in folder: project_lock's for a project, or do-epic's for an epic. Raises OSError where the file cannot be opened or locked."""
folder.mkdir(parents=True, exist_ok=True)
with open(folder / LOCK, "a") as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
yield
def project_lock(root: str, home: pathlib.Path) -> pathlib.Path:
"""The folder of the LOCK that everything starting a chunk in the checkout root holds."""
return home / STATE / project_key(root, home)
def epic_chunks(root: str, run: tmux.Tmux) -> list[tmux.Placed]:
"""The windows of do-epic's sessions whose chunks run in the checkout root."""
return [placed for placed in tmux.everywhere(run) if placed.session.startswith(f"{tmux.EPIC}-") and placed.root == root and not placed.window.dead]
def held_items(chunks: typing.Iterable[str], key: str, claude_code_transcripts: pathlib.Path) -> set[int]:
"""The plan items these chunks hold: the one each started from, and those its worker names on its latest `Chunk items:` line so far. A chunk whose transcript cannot be read holds the item it started from."""
held: set[int] = set()
@@ -128,51 +137,61 @@ def next_plan(root: str, home: pathlib.Path, effects: Effects) -> NextChunk | No
def start_chunks(loop_run: LoopRun, leaving: bool, paths: Paths, env: typing.Mapping[str, str], launcher: pathlib.Path, effects: Effects) -> list[str] | Failure:
"""Starts a loop-claude in a new window for each chunk of loop_run's project that may start now, and returns the chunks started. leaving says that loop_run's own chunk finished, so its window no longer counts as running; without it, the human started loop-claude. A plan that cannot be read starts NO_ITEM, as a plan without an item does. A Failure says why a chunk could not start; those before it run."""
"""Starts a loop-claude in a new window for each chunk of loop_run's project that may start now, and returns the chunks started. leaving says that loop_run's own chunk finished, so its window no longer counts as running; without it, the human started loop-claude. A Failure says why no chunk may start, or why one could not; those before it run."""
config = located(loop_run.root, paths.home)
if isinstance(config, Failure):
return config
key = project_key(loop_run.root, paths.home)
session = tmux.session_name(key)
session = tmux.session_name(tmux.LOOP, project_key(loop_run.root, paths.home))
handed = {name: value for name, value in env.items() if name.startswith(HANDED)}
lock = project_lock(loop_run.root, paths.home)
try:
with starting(paths.home, key):
with starting(lock):
windows = tmux.listed(session, effects.tmux)
if windows and (owned := tmux.owner(session, effects.tmux)) != loop_run.root:
return Failure(f"the tmux session {session} runs the chunks of {owned or 'another checkout'}, whose key maps to the same session name; rename one of the two checkouts' folders")
room = room_of(windows, loop_run.chunk, leaving, config.parallel_chunks)
chunks = list(room.restart)
if room.left:
plan = next_plan(loop_run.root, paths.home, effects)
if isinstance(plan, Failure):
# Such as in a checkout without a default branch, where chunk-preflight fails too: the worker is told why and finds the facts itself.
say(f"starting a chunk without a plan item, since the plan cannot be read: {plan.reason}", effects)
plan = NoItem(plan.reason)
held = held_items(room.running + room.stopped, key, paths.claude_code_transcripts)
chunks += [chunk for chunk in may_start(plan, room.running + room.restart, held, room.left) if chunk not in room.stopped]
if refused := refusal(session, windows, loop_run.root, effects.tmux):
return refused
chunks = chunks_to_start(windows, loop_run, leaving, config.parallel_chunks, paths, effects)
for chunk in chunks:
stale = [window for window in windows if window.name == chunk and window.dead]
for window in stale:
tmux.close(window, effects.tmux)
windows = [window for window in windows if window not in stale]
command = [str(launcher), CHUNK_FLAG, chunk, loop_run.task]
if failed := tmux.start_window(tmux.Window(session, chunk, ""), loop_run.root, handed, command, not windows, effects.tmux):
return failed
windows.append(tmux.Listed(chunk, "", False))
started = tmux.start_chunk(tmux.Window(session, chunk, ""), loop_run.root, handed, [str(launcher), CHUNK_FLAG, chunk, loop_run.task], windows, True, effects.tmux)
if isinstance(started, Failure):
return started
windows = started
return chunks
except OSError as failure:
return Failure(f"cannot lock {paths.home / STATE / key / LOCK}: {failure.strerror}")
return Failure(f"cannot lock {lock / LOCK}: {failure.strerror}")
def refusal(session: str, windows: list[tmux.Listed], root: str, run: tmux.Tmux) -> Failure | None:
"""Why no chunk of the checkout root may start in session, whose windows are windows: another checkout's chunks run in the session, or do-epic runs chunks in root."""
if windows and (owned := tmux.owner(session, run)) != root:
return Failure(f"the tmux session {session} runs the chunks of {owned or 'another checkout'}, whose key maps to the same session name; rename one of the two checkouts' folders")
if theirs := epic_chunks(root, run):
return Failure(f"do-epic runs chunks in {root}: {', '.join(f'{placed.window.name} of {placed.session}' for placed in theirs)}; loop-claude doesn't start a chunk there until those chunks finish")
return None
def chunks_to_start(windows: list[tmux.Listed], loop_run: LoopRun, leaving: bool, limit: int, paths: Paths, effects: Effects) -> list[str]:
"""The chunks to start beside windows, the session's: the stopped ones room_of restarts, then those of the plan that may_start picks. A plan that cannot be read starts NO_ITEM, as a plan without an item does."""
room = room_of(windows, loop_run.chunk, leaving, limit)
if not room.left:
return room.restart
plan = next_plan(loop_run.root, paths.home, effects)
if isinstance(plan, Failure):
# Such as in a checkout without a default branch, where chunk-preflight fails too: the worker is told why and finds the facts itself.
say(f"starting a chunk without a plan item, since the plan cannot be read: {plan.reason}", effects)
plan = NoItem(plan.reason)
held = held_items(room.running + room.stopped, project_key(loop_run.root, paths.home), paths.claude_code_transcripts)
return room.restart + [chunk for chunk in may_start(plan, room.running + room.restart, held, room.left) if chunk not in room.stopped]
def held_beside(chunk: str, root: str, paths: Paths, effects: Effects) -> list[int]:
"""The plan items that the project's other chunks hold now, running or stopped, which a chunk starting as `chunk` leaves to them. It waits for a loop that is starting windows, so chunks started together see each other. Where the lock cannot be taken, it reads the windows without it."""
key = project_key(root, paths.home)
wait_for_starts(paths.home, key)
others = [window.name for window in tmux.listed(tmux.session_name(key), effects.tmux) if window.name != chunk]
others = [window.name for window in tmux.listed(tmux.session_name(tmux.LOOP, key), effects.tmux) if window.name != chunk]
return sorted(held_items(others, key, paths.claude_code_transcripts))
def wait_for_starts(home: pathlib.Path, key: str) -> None:
"""Returns once no loop of the project is starting windows: start_chunks holds LOCK while it starts them. Where the lock cannot be taken, it returns at once."""
with contextlib.suppress(OSError), starting(home, key):
with contextlib.suppress(OSError), starting(home / STATE / key):
pass
+5 -5
View File
@@ -15,8 +15,8 @@ from claude_code.session import transcript_file
UNFINISHED_LIMIT = 6
def closed_cycle(loop_run: LoopRun, project: ProjectRung | None, concluded: Concluded, archive_folder: pathlib.Path, loop: Loop) -> LoopRun | Stop:
"""The loop run after a cycle concluded, with the step-up archived; the stop that needs the human, archived, once the chunk has had UNFINISHED_LIMIT unfinished verdicts running."""
def closed_cycle(loop_run: LoopRun, project: ProjectRung | None, concluded: Concluded, archive_folder: pathlib.Path, driver: str, loop: Loop) -> LoopRun | Stop:
"""The loop run after a cycle of driver, the entry point, concluded, with the step-up archived; the stop that needs the human, archived, once the chunk has had UNFINISHED_LIMIT unfinished verdicts running."""
after = after_verdict(loop_run, project, concluded)
# A finished chunk drops its route, so it has no step-up, and its run of unfinished verdicts restarts.
if after.route is None:
@@ -25,17 +25,17 @@ def closed_cycle(loop_run: LoopRun, project: ProjectRung | None, concluded: Conc
path = transcript_file(loop.session)
if path and (failure := archived_step(archive_folder, path, after.task, step_up(concluded.route, after.route), loop.effects)):
return Stop(1, failure.reason)
if limit := reached_limit(after):
if limit := reached_limit(after, driver):
# Archived with the route the next cycle would run on, so a rerun resumes there.
return archived_stop(archive_folder, loop.session, after.task, after.route, limit, limit.reason, loop.effects)
return after
def reached_limit(loop_run: LoopRun) -> Stop | None:
def reached_limit(loop_run: LoopRun, driver: str) -> Stop | None:
"""The stop that needs the human once the loop run holds UNFINISHED_LIMIT unfinished verdicts running."""
if loop_run.unfinished_run < UNFINISHED_LIMIT:
return None
return needs_human("go on with the chunk", f"the judge ruled it unfinished {loop_run.unfinished_run} cycles running; finish the chunk yourself, or rerun loop-claude to give it {UNFINISHED_LIMIT} more cycles")
return needs_human("go on with the chunk", f"the judge ruled it unfinished {loop_run.unfinished_run} cycles running; finish the chunk yourself, or rerun {driver} to give it {UNFINISHED_LIMIT} more cycles")
def after_verdict(loop_run: LoopRun, project: ProjectRung | None, concluded: Concluded) -> LoopRun:
+5 -5
View File
@@ -50,7 +50,7 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
if isinstance(loop_run, Stop):
return loop_run
# Before anything starts: a worktree, a claude session or a tmux window.
if reason := tmux.unusable(effects.tmux):
if reason := tmux.unusable(effects.tmux, prompts.DRIVER):
return Stop(1, reason)
if loop_run.chunk is None:
return windows_opened(loop_run, env, paths, launcher, effects)
@@ -59,7 +59,7 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
return Stop(1, f"{CHUNK_FLAG} is how loop-claude starts itself in a tmux window; run loop-claude <task>")
baseline = fingerprint(launcher)
key = project_key(loop_run.root, paths.home)
window = tmux.Window(tmux.session_name(key), loop_run.chunk, pane)
window = tmux.Window(tmux.session_name(tmux.LOOP, key), loop_run.chunk, pane)
loop = Loop(root=loop_run.root, session=chunk_session(key, loop_run.chunk, paths.claude_code_transcripts), window=window, paths=paths, env=env, launcher=launcher, effects=effects)
while True:
if stop := exec_if_edited(loop, baseline, loop_run):
@@ -71,7 +71,7 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
concluded = run_cycle(cycle)
if isinstance(concluded, Stop):
return concluded
closed = closed_cycle(loop_run, cycle.project, concluded, cycle.project_archive, loop)
closed = closed_cycle(loop_run, cycle.project, concluded, cycle.project_archive, prompts.DRIVER, loop)
if isinstance(closed, Stop):
return closed
loop_run = closed
@@ -87,7 +87,7 @@ def windows_opened(loop_run: LoopRun, env: typing.Mapping[str, str], paths: Path
started = start_chunks(loop_run, False, paths, env, launcher, effects)
if isinstance(started, Failure):
return Stop(1, started.reason)
session = tmux.session_name(project_key(loop_run.root, paths.home))
session = tmux.session_name(tmux.LOOP, project_key(loop_run.root, paths.home))
say(f"started {', '.join(started)} in the tmux session {session}" if started else f"the tmux session {session} runs every chunk that may run now, so `{loop_run.task}` started in no new window", effects, stdout=True)
if not effects.on_terminal():
say(f"not on a terminal; see the chunks with `tmux attach -t ={session}`", effects, stdout=True)
@@ -113,7 +113,7 @@ def next_cycle(loop_run: LoopRun, loop: Loop) -> Cycle | Stop:
records = read_records(loop.root, loop.paths.home, loop.paths.claude_dir)
if isinstance(records, Failure):
return Stop(1, records.reason)
models = get_or_ask_models(project_key(loop.root, loop.paths.home), loop.paths, loop.env, loop.effects)
models = get_or_ask_models(project_key(loop.root, loop.paths.home), loop.paths, loop.env, prompts.DRIVER, loop.effects)
if isinstance(models, Stop):
return models
ladder_file = project_ladder_file(loop.root, loop.paths.home)
+6 -6
View File
@@ -18,24 +18,24 @@ class Models:
worker: str
def get_or_ask_models(project_key: str, paths: Paths, env: typing.Mapping[str, str], effects: Effects) -> Models | Stop:
def get_or_ask_models(project_key: str, paths: Paths, env: typing.Mapping[str, str], driver: str, effects: Effects) -> Models | Stop:
judge, worker = env.get("LOOP_CLAUDE_JUDGE_MODEL"), env.get("LOOP_CLAUDE_WORKER_MODEL")
if judge and worker:
return Models(judge, worker)
chosen = get_or_ask_model(project_key, paths, effects)
chosen = get_or_ask_model(project_key, paths, driver, effects)
if isinstance(chosen, Stop):
return chosen
return Models(judge or chosen, worker or chosen)
def get_or_ask_model(project_key: str, paths: Paths, effects: Effects) -> str | Stop:
def get_or_ask_model(project_key: str, paths: Paths, driver: str, effects: Effects) -> str | Stop:
saved = paths.models_file
models = read_models_file(saved)
if isinstance(models, Failure):
return Stop(1, models.reason)
if kept := models.get(project_key):
return kept
chosen = ask_for_model(project_key, saved, paths.model_catalog, effects)
chosen = ask_for_model(project_key, saved, paths.model_catalog, driver, effects)
if isinstance(chosen, Stop):
return chosen
# Reread: another loop may have saved its project while this one waited on the human.
@@ -62,8 +62,8 @@ def read_models_file(saved: pathlib.Path) -> dict[str, str] | Failure:
return models
def ask_for_model(project_key: str, saved: pathlib.Path, folder: pathlib.Path, effects: Effects) -> str | Stop:
if stop := needs_terminal(f"pick {project_key}'s model, or merge {{\"{project_key}\": \"<model>\"}} into {saved}", effects.on_terminal()):
def ask_for_model(project_key: str, saved: pathlib.Path, folder: pathlib.Path, driver: str, effects: Effects) -> str | Stop:
if stop := needs_terminal(f"pick {project_key}'s model, or merge {{\"{project_key}\": \"<model>\"}} into {saved}", effects.on_terminal(), driver):
return stop
offered = catalog_models(folder)
choices = [f" {number}. {label} ({model_id})" for number, (model_id, label) in enumerate(offered, 1)] or [f" no model catalog cached in {folder}"]
+3 -1
View File
@@ -831,8 +831,10 @@ class Windows(unittest.TestCase):
self.assertEqual(run.tmux, [
["-V"],
["list-windows", "-t", "=loop-proj", "-F", "#{window_name}\t#{pane_dead}\t#{window_id}"],
["list-windows", "-a", "-F", "#{session_name}\t#{window_name}\t#{pane_dead}\t#{window_id}\t#{@chunk-root}"],
["new-session", "-d", "-s", "loop-proj", "-n", "item-4", "-c", str(checkout.root), "-e", "LOOP_CLAUDE_JUDGE_MODEL=judge-model", "-e", "LOOP_CLAUDE_WORKER_MODEL=worker-model", "-P", "-F", "#{window_id}", "--", str(checkout.script), "--chunk", "item-4", "ship it"],
["set-option", "-t", "=loop-proj:", "@loop-root", str(checkout.root)],
["set-option", "-w", "-t", "@7", "@chunk-root", str(checkout.root)],
["set-option", "-w", "-t", "@7", "remain-on-exit", "failed"],
])
self.assertEqual(run.stdout, "started item-4 in the tmux session loop-proj\nnot on a terminal; see the chunks with `tmux attach -t =loop-proj`\n")
@@ -1127,7 +1129,7 @@ class Reload(unittest.TestCase):
state = {"cycle_number": 3, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "", "route": None, "slot": 0}
run = checkout.run([worker()], argv=["--reloaded", json.dumps(state)])
self.assertEqual((run.code, run.calls), (0, []))
self.assertEqual([command[0] for command in run.tmux], ["-V", "list-windows", "new-session", "set-option", "set-option"])
self.assertEqual([command[0] for command in run.tmux], ["-V", "list-windows", "list-windows", "new-session", "set-option", "set-option", "set-option"])
self.assertIn("started no-item in the tmux session loop-proj\n", run.stdout)
def test_stops_where_a_reload_hands_no_state(self):
+93 -86
View File
@@ -568,7 +568,7 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
self.assertEqual(concluded.route, Route(Routing.OPUS, 179, 2, 5, escalated_at=3))
first, resumed = fake.made("stream_claude")
self.assertEqual([args[args.index("--effort") + 1] for args in (first, resumed)], ["high", "medium"])
self.assertTrue(resumed[resumed.index("-p") + 1].endswith(f"Continue the task. Your request for a higher rung went through: loop-claude runs you on {Routing.OPUS}. The escalation triggers that fired before this step are spent.{prompts.rungs_held(concluded.route, OPUS_PROJECT)}"))
self.assertTrue(resumed[resumed.index("-p") + 1].endswith(f"Continue the task. Your request for a higher rung went through: loop-claude runs you on {Routing.OPUS}. The escalation triggers that fired before this step are spent.{prompts.WORKER.rungs_held(concluded.route, OPUS_PROJECT)}"))
self.assertNotIn("went through", first[first.index("-p") + 1])
answered = f"Verdict: quoted answer\n\nWhich one?\n\n{prompts.QUOTE_SOURCES} says:\n> Use A.\n\nEvidence:\n> working\n\nEscalation:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {SONNET_179}\n"
stepped = f"Stepped up\n\nWorker: {OPUS_179_AT_3}\n"
@@ -698,7 +698,7 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
self.addCleanup(folder.chmod, 0o700)
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished")])
stop = run.run_cycle(self.cycle(fake))
self.assertEqual(stop, Stop(1, f"could not delete {folder}: Permission denied; delete every file and folder matching {folder}*, then rerun loop-claude; a rerun before that resumes the finished chunk's session"))
self.assertEqual(stop, Stop(1, f"could not delete {folder}: Permission denied; delete every file and folder matching {folder}*, then run it again; a run before that resumes the finished chunk's session"))
self.assertTrue(session.session_open(self.session))
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: finished\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n\n2026-09-21T14:13:20Z Stopped: {stop.reason}\n\nWorker: {OFF_LADDER}\n"])
@@ -795,7 +795,7 @@ class Interrupts(unittest.TestCase):
def put(self, fake, answer_here=True, effects=None, question="Which one?"):
"""interrupt's answer and what it said, without the bell it rang, which self.bells counts."""
with contextlib.redirect_stderr(io.StringIO()) as said:
answer = interrupt.interrupt(question, answer_here, self.session, WINDOW, effects or fake.effects())
answer = interrupt.interrupt(question, answer_here, self.session, WINDOW, prompts.DRIVER, effects or fake.effects())
self.bells = said.getvalue().count(tmux.BELL)
return answer, said.getvalue().replace(tmux.BELL, "")
@@ -1004,10 +1004,10 @@ class ModelPrompt(unittest.TestCase):
def test_asks_again_until_an_answer_picks_a_model(self):
with tempfile.TemporaryDirectory() as empty:
fake = FakeEffects(inputs=["", "my-model"])
self.assertEqual(model_choice.ask_for_model("proj", pathlib.Path("/m.json"), pathlib.Path(empty), fake.effects()), "my-model")
self.assertEqual(model_choice.ask_for_model("proj", pathlib.Path("/m.json"), pathlib.Path(empty), prompts.DRIVER, fake.effects()), "my-model")
self.assertEqual(len(fake.made("input")), 2)
fake = FakeEffects(inputs=[EOFError()])
self.assertEqual(model_choice.ask_for_model("proj", pathlib.Path("/m.json"), pathlib.Path(empty), fake.effects()), Stop(2, "the human is needed to pick proj's model, but the input ended"))
self.assertEqual(model_choice.ask_for_model("proj", pathlib.Path("/m.json"), pathlib.Path(empty), prompts.DRIVER, fake.effects()), Stop(2, "the human is needed to pick proj's model, but the input ended"))
# A plan read with no release cut yet.
@@ -1289,7 +1289,7 @@ class RouteSources(unittest.TestCase):
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.stepped_up(WorkerLine('{"model": "claude-opus-5-5", "rung": 3}')), NOW + 1))
with contextlib.redirect_stderr(io.StringIO()) as stderr:
self.assertIsNone(chunk_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)))
self.assertEqual(stderr.getvalue(), f'{STAMP} routing the chunk afresh: the archive\'s latest Worker: line names no route loop-claude can read: {{"model": "claude-opus-5-5", "rung": 3}}\n')
self.assertEqual(stderr.getvalue(), f'{STAMP} routing the chunk afresh: the archive\'s latest Worker: line names no route that can be read: {{"model": "claude-opus-5-5", "rung": 3}}\n')
(chunk,) = archive.iterdir()
chunk.chmod(0)
try:
@@ -1308,14 +1308,14 @@ class TmuxCommands(unittest.TestCase):
("", "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found no tmux")):
with self.subTest(found=found):
fake = FakeEffects(tmux_version=found)
self.assertEqual(tmux.unusable(fake.tmux), reason)
self.assertEqual(tmux.unusable(fake.tmux, prompts.DRIVER), reason)
self.assertEqual(fake.tmux_calls, [["-V"]])
def test_names_the_session_for_the_project(self):
self.assertEqual(tmux.session_name("claude-config"), "loop-claude-config")
self.assertEqual(tmux.session_name(tmux.LOOP, "claude-config"), "loop-claude-config")
# tmux reads `.` and `:` in a target as separators.
self.assertEqual(tmux.session_name("my.site:2 x"), "loop-my-site-2-x")
self.assertEqual(tmux.session_name("Acme/Billing"), "loop-Acme-Billing")
self.assertEqual(tmux.session_name(tmux.LOOP, "my.site:2 x"), "loop-my-site-2-x")
self.assertEqual(tmux.session_name(tmux.LOOP, "Acme/Billing"), "loop-Acme-Billing")
def test_lists_the_windows_without_the_waiting_mark(self):
fake = FakeEffects(windows="item-372 ?\t0\t@1\nitem-380\t1\t@2\nno-item\t0\t@5\n")
@@ -1328,13 +1328,15 @@ class TmuxCommands(unittest.TestCase):
def test_the_first_window_makes_the_session_and_each_later_one_joins_it(self):
fake = FakeEffects()
window = tmux.Window("loop-proj", "item-7", "")
self.assertIsNone(tmux.start_window(window, "/r", {"LOOP_CLAUDE_X": "1"}, ["/b/loop-claude", "--chunk", "item-7", "ship it;"], True, fake.tmux))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["/b/loop-claude"], False, fake.tmux))
self.assertIsNone(tmux.start_window(window, "/r", {"LOOP_CLAUDE_X": "1"}, ["/b/loop-claude", "--chunk", "item-7", "ship it;"], True, True, fake.tmux))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["/b/loop-claude"], False, True, fake.tmux))
self.assertEqual(fake.tmux_calls, [
["new-session", "-d", "-s", "loop-proj", "-n", "item-7", "-c", "/r", "-e", "LOOP_CLAUDE_X=1", "-P", "-F", "#{window_id}", "--", "/b/loop-claude", "--chunk", "item-7", "ship it\;"],
["set-option", "-t", "=loop-proj:", "@loop-root", "/r"],
["set-option", "-w", "-t", "@9", "@chunk-root", "/r"],
["set-option", "-w", "-t", "@9", "remain-on-exit", "failed"],
["new-window", "-d", "-t", "=loop-proj:", "-n", "item-7", "-c", "/r", "-P", "-F", "#{window_id}", "--", "/b/loop-claude"],
["set-option", "-w", "-t", "@9", "@chunk-root", "/r"],
["set-option", "-w", "-t", "@9", "remain-on-exit", "failed"],
])
@@ -1342,8 +1344,8 @@ class TmuxCommands(unittest.TestCase):
failed = lambda args: subprocess.CompletedProcess(args, 1, "", "duplicate session: loop-proj\n")
silent = lambda args: subprocess.CompletedProcess(args, 2, "", "")
window = tmux.Window("loop-proj", "item-7", "")
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, failed), Failure("tmux could not start the window loop-proj:item-7: duplicate session: loop-proj"))
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, silent), Failure("tmux could not start the window loop-proj:item-7: it exited 2"))
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, True, failed), Failure("tmux could not start the window loop-proj:item-7: duplicate session: loop-proj"))
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, True, silent), Failure("tmux could not start the window loop-proj:item-7: it exited 2"))
def test_fails_where_it_cannot_mark_a_session_it_made_as_the_checkouts_but_not_where_remain_on_exit_fails(self):
def answering(failing: str):
@@ -1352,9 +1354,9 @@ class TmuxCommands(unittest.TestCase):
return subprocess.CompletedProcess(args, 1 if fails else 0, "" if fails else "@9\n", "no such session\n" if fails else "")
return run
window = tmux.Window("loop-proj", "item-7", "")
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, answering(tmux.OWNER)), Failure("tmux started the session loop-proj but could not mark it as this checkout's: no such session"))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], True, answering("remain-on-exit")))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], False, answering(tmux.OWNER)))
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, True, answering(tmux.OWNER)), Failure("tmux started the session loop-proj but could not mark it as this checkout's: no such session"))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], True, True, answering("remain-on-exit")))
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], False, True, answering(tmux.OWNER)))
def test_reads_the_checkout_the_session_names(self):
fake = FakeEffects(owner="/c/proj")
@@ -1511,6 +1513,11 @@ class StartChunks(unittest.TestCase):
self.assertEqual(self.starts(fake), [])
self.assertIn(["show-options", "-qv", "-t", f"={self.session}:", "@loop-root"], fake.tmux_calls)
def test_refuses_a_checkout_do_epic_runs_chunks_in(self):
fake = FakeEffects(windows=f"epic-ABC-12\tABC-34 ?\t0\t@4\t{self.root}\nepic-ABC-12\tABC-35\t0\t@5\t/c/other\nepic-ABC-12\tABC-36\t1\t@6\t{self.root}\nloop-x\titem-1\t0\t@7\t{self.root}\n")
self.assertEqual(self.start(fake), Failure(f"do-epic runs chunks in {self.root}: ABC-34 of epic-ABC-12; loop-claude doesn't start a chunk there until those chunks finish"))
self.assertEqual(self.starts(fake), [])
def test_leaves_out_the_items_a_running_chunk_names_on_its_chunk_items_line(self):
self.limit(2)
transcripts = paths.paths_from(self.home).claude_code_transcripts
@@ -1634,14 +1641,14 @@ class Steps(unittest.TestCase):
before = Route(self.FABLE_LOW, 3, 3, 4)
with contextlib.redirect_stderr(io.StringIO()):
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(before.worker_line(), "working", "j", ""), NOW))
after = close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), archive, a_loop(FakeEffects().effects(), session=opened))
after = close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), archive, prompts.DRIVER, a_loop(FakeEffects().effects(), session=opened))
self.assertEqual(chunk_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), Route(self.FABLE_MEDIUM, 3, 3, 4))
with contextlib.redirect_stderr(io.StringIO()):
close.closed_cycle(after, OPUS_PROJECT, run.Concluded(Finished("done"), after.route), archive, a_loop(FakeEffects().effects(), session=opened))
close.closed_cycle(after, OPUS_PROJECT, run.Concluded(Finished("done"), after.route), archive, prompts.DRIVER, a_loop(FakeEffects().effects(), session=opened))
self.assertEqual(chunk_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), Route(self.FABLE_MEDIUM, 3, 3, 4))
blocked = pathlib.Path(home, "blocked")
blocked.write_text("")
stop = close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), blocked, a_loop(FakeEffects().effects(), session=opened))
stop = close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), blocked, prompts.DRIVER, a_loop(FakeEffects().effects(), session=opened))
self.assertEqual((stop.code, stop.reason.split(":")[0]), (1, "could not archive the transcript"))
def test_names_no_step_up_where_only_the_count_of_unfinished_verdicts_changed(self):
@@ -1659,7 +1666,7 @@ class Steps(unittest.TestCase):
before = Route(self.FABLE_LOW, 3, 3, 4)
with contextlib.redirect_stderr(io.StringIO()):
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(before.worker_line(), "working", "j", ""), NOW))
close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_escape_and_impact=6)), before), archive, a_loop(FakeEffects().effects(), session=opened))
close.closed_cycle(main.LoopRun(cycle_number=1, root="/r", task="Do it.", unfinished_evidence=""), OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_escape_and_impact=6)), before), archive, prompts.DRIVER, a_loop(FakeEffects().effects(), session=opened))
self.assertEqual(chunk_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), Route(self.FABLE_LOW, 3, 3, 4, escape_and_impact_taken_in=6))
@@ -1722,7 +1729,7 @@ class TypedAnswers(unittest.TestCase):
self.assertEqual(worker_prompts.typed_answer(prompts.WORKER.typed(f"Which one?\n{marked}", "Use B.", route, None, False)).answer, "Use B.")
self.assertEqual(worker_prompts.typed_answer(prompts.WORKER.typed("Which one?", "Use B.", Route(Routing.SONNET, 179, 2, 5), OPUS_PROJECT, True)).answer, "Use B.")
self.assertIsNone(worker_prompts.typed_answer(prompts.WORKER.answered("Which one?", marked, route, None, False)))
self.assertIsNone(worker_prompts.typed_answer(prompts.resumed(marked, route, None)))
self.assertIsNone(worker_prompts.typed_answer(prompts.WORKER.resumed(marked, route, None)))
class WorkerArgs(unittest.TestCase):
@@ -1733,24 +1740,24 @@ class WorkerArgs(unittest.TestCase):
FACTS = "- A preflight fact."
def test_names_the_route_in_a_fresh_prompt_only_where_an_item_routed_it(self):
routed = prompts.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, self.FACTS)
routed = prompts.WORKER.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, self.FACTS)
self.assertIn(f"Continue any open draft PR or worktree for the chunk before creating a new one. {prompts.READING_RULE} {prompts.NAME_THE_ITEMS}\n\nloop-claude runs you on m at high effort, routed by item 3's L of 4.", routed)
unrouted = prompts.fresh("Do it.", "## Goals", Route(Rung("m")), None, self.FACTS)
unrouted = prompts.WORKER.fresh("Do it.", "## Goals", Route(Rung("m")), None, self.FACTS)
self.assertIn(f"before creating a new one. {prompts.READING_RULE} {prompts.NAME_THE_ITEMS}\n\n{self.FACTS}\n\nThe chunk's", unrouted)
self.assertNotIn("loop-claude runs you on", unrouted)
def test_has_the_routed_worker_count_its_items_size_again_and_puts_the_facts_before_the_scope(self):
routed = prompts.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, self.FACTS)
routed = prompts.WORKER.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, self.FACTS)
self.assertIn("item 3's size again", routed)
self.assertIn("escalation trigger 1", routed)
self.assertIn(f"\n\n{self.FACTS}\n\nThe chunk's", routed)
self.assertNotIn("size again", prompts.fresh("Do it.", "## Goals", Route(Rung("m")), None, self.FACTS))
self.assertNotIn("size again", prompts.WORKER.fresh("Do it.", "## Goals", Route(Rung("m")), None, self.FACTS))
def test_gives_each_fresh_worker_the_reading_rule_once(self):
rule = "never read more than 80 lines of a file at once, nor take a tool output over 3,000 characters into your context"
for route in (Route(Rung("m", "high"), 3, 4, 5), Route(Rung("m"))):
with self.subTest(route=route):
self.assertEqual(prompts.fresh("Do it.", "## Goals", route, None, self.FACTS).count(rule), 1)
self.assertEqual(prompts.WORKER.fresh("Do it.", "## Goals", route, None, self.FACTS).count(rule), 1)
def test_quotes_what_the_preflight_printed_or_has_the_worker_find_the_facts_itself(self):
self.assertIn("\n\n- A fact.", prompts.preflight_facts("- A fact."))
@@ -1761,95 +1768,95 @@ class WorkerArgs(unittest.TestCase):
def test_has_each_fresh_worker_continue_an_open_draft_pr_or_worktree_once_whatever_the_preflight_found(self):
for facts in (prompts.preflight_facts("- A fact."), prompts.preflight_failed("git could not start")):
with self.subTest(facts=facts):
self.assertEqual(prompts.fresh("Do it.", "## Goals", Route(Rung("m")), None, facts).count("Continue any open draft PR or worktree"), 1)
self.assertEqual(prompts.WORKER.fresh("Do it.", "## Goals", Route(Rung("m")), None, facts).count("Continue any open draft PR or worktree"), 1)
def test_keeps_every_review_on_the_projects_rung_while_the_worker_runs_below_it(self):
opus = Rung("claude-opus-5-5", "medium")
below = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 4), OPUS_PROJECT, self.FACTS)
below = prompts.WORKER.fresh("Do it.", "## Goals", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 4), OPUS_PROJECT, self.FACTS)
self.assertIn(f"item 3's L of 2. Launch each reviewer, each comprehension seat and the security pass's subagent with the Agent tool set to model opus, effort medium, the project's rung.{self.SCAN} Your rung is below the project's: launch each subagent that files or scores plan items on the rung `~/.claude/bin/subagent-rung --plan claude-opus-5-5 <L>` prints. Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model fable, effort low` from 5, `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8. When an escalation trigger", below)
self.assertNotIn("Launch each", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
self.assertNotIn("Launch each", prompts.WORKER.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
def test_launches_reviewers_on_the_rung_the_items_e_plus_i_picks_above_the_workers(self):
opus = Rung("claude-opus-5-5", "medium")
level = prompts.fresh("Do it.", "## Goals", Route(opus, 3, 2, 6), OPUS_PROJECT, self.FACTS)
level = prompts.WORKER.fresh("Do it.", "## Goals", Route(opus, 3, 2, 6), OPUS_PROJECT, self.FACTS)
self.assertIn(f"item 3's L of 2. Launch each reviewer with the Agent tool set to model fable, effort medium, the rung item 3's E + I of 6 picks. Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.{self.MARKDOWN} When an escalation trigger", level)
below = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 5), OPUS_PROJECT, self.FACTS)
below = prompts.WORKER.fresh("Do it.", "## Goals", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 5), OPUS_PROJECT, self.FACTS)
self.assertIn(f"item 3's L of 2. Launch each reviewer with the Agent tool set to model fable, effort low, the rung item 3's E + I of 5 picks.{self.SEATS}{self.SCAN} Your rung is below the project's:", below)
self.assertNotIn("Launch each reviewer", prompts.resumed("", Route(Rung("claude-fable-5-2", "medium"), 3, 4, 6), OPUS_PROJECT))
self.assertNotIn("Launch each reviewer", prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "medium"), 3, 4, 6), OPUS_PROJECT))
def test_names_the_reviewers_rung_each_higher_e_plus_i_an_item_taken_in_picks(self):
opus = Rung("claude-opus-5-5", "medium")
taking_in = " Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model fable, effort low` from 5, `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8."
self.assertIn(f"item 3's L of 2.{taking_in} When an escalation trigger", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
self.assertIn(" Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.", prompts.resumed("", Route(opus, 3, 2, 6), OPUS_PROJECT))
self.assertIn(" Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.", prompts.resumed("", Route(Rung("claude-fable-5-2", "medium"), 3, 4, 4), OPUS_PROJECT))
self.assertNotIn("Where an item you take into", prompts.resumed("", Route(opus, 3, 2, 8), OPUS_PROJECT))
self.assertNotIn("Where an item you take into", prompts.resumed("", Route(Rung("m")), None))
self.assertIn(f"item 3's L of 2.{taking_in} When an escalation trigger", prompts.WORKER.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
self.assertIn(" Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.", prompts.WORKER.resumed("", Route(opus, 3, 2, 6), OPUS_PROJECT))
self.assertIn(" Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.", prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "medium"), 3, 4, 4), OPUS_PROJECT))
self.assertNotIn("Where an item you take into", prompts.WORKER.resumed("", Route(opus, 3, 2, 8), OPUS_PROJECT))
self.assertNotIn("Where an item you take into", prompts.WORKER.resumed("", Route(Rung("m")), None))
def test_launches_reviewers_on_the_rung_the_highest_e_plus_i_taken_in_picks(self):
opus = Rung("claude-opus-5-5", "medium")
self.assertIn(f"loop-claude runs you on claude-opus-5-5 at medium effort. Launch each reviewer with the Agent tool set to model opus, effort xhigh, the rung picked by an item of E + I 7 taken into the chunk. Where an item you take into the chunk has an E + I of 8 or more, launch each reviewer with the Agent tool set to `model fable, effort high` from 8.{self.MARKDOWN} When an escalation trigger", prompts.resumed("", Route(opus, 3, 2, 5, escape_and_impact_taken_in=7), OPUS_PROJECT))
self.assertIn(" Launch each reviewer with the Agent tool set to model fable, effort low, the rung picked by an item of E + I 5 taken into the chunk.", prompts.resumed("", Route(opus, escape_and_impact_taken_in=5), OPUS_PROJECT))
self.assertIn(f"loop-claude runs you on claude-opus-5-5 at medium effort. Launch each reviewer with the Agent tool set to model opus, effort xhigh, the rung picked by an item of E + I 7 taken into the chunk. Where an item you take into the chunk has an E + I of 8 or more, launch each reviewer with the Agent tool set to `model fable, effort high` from 8.{self.MARKDOWN} When an escalation trigger", prompts.WORKER.resumed("", Route(opus, 3, 2, 5, escape_and_impact_taken_in=7), OPUS_PROJECT))
self.assertIn(" Launch each reviewer with the Agent tool set to model fable, effort low, the rung picked by an item of E + I 5 taken into the chunk.", prompts.WORKER.resumed("", Route(opus, escape_and_impact_taken_in=5), OPUS_PROJECT))
def test_keeps_seats_and_the_security_pass_on_the_projects_rung_while_the_worker_runs_above_it(self):
opus = Rung("claude-opus-5-5", "medium")
above = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT, self.FACTS)
stepped_up = prompts.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT)
above = prompts.WORKER.fresh("Do it.", "## Goals", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT, self.FACTS)
stepped_up = prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT)
self.assertIn(f"{prompts.ANSWERS_RECORDED}. {prompts.NAME_THE_ITEMS} loop-claude runs you on claude-fable-5-2 at low effort.{self.SEATS}{self.SCAN} Where an item you take into the chunk has an E + I of 6 or more, launch each reviewer with the Agent tool set to `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.{self.MARKDOWN} When an escalation trigger", stepped_up)
self.assertNotIn("the project's", prompts.resumed("", Route(opus, 3, 2, 4), OPUS_PROJECT))
self.assertNotIn("runs you on", prompts.resumed("", Route(Rung("m")), None))
self.assertNotIn("the project's", prompts.WORKER.resumed("", Route(opus, 3, 2, 4), OPUS_PROJECT))
self.assertNotIn("runs you on", prompts.WORKER.resumed("", Route(Rung("m")), None))
self.assertIn(f"item 3's L of 3.{self.SEATS}{self.SCAN} Where an item you take into the chunk has an E + I of 6 or more, launch each reviewer with the Agent tool set to `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.{self.MARKDOWN} When an escalation trigger", above)
def test_names_the_rungs_an_escalation_trigger_lets_the_worker_hand_a_task_to_at_most_two_above_its_items(self):
opus = Rung("claude-opus-5-5", "medium")
fresh = prompts.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS)
fresh = prompts.WORKER.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS)
self.assertIn("item 3's L of 2. Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model fable, effort low` from 5, `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8. When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort low`, one rung above yours; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", fresh)
self.assertIn(" When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort medium`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort xhigh`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", prompts.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT))
self.assertIn(" When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort xhigh`, one rung above yours; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", prompts.resumed("", Route(Rung("claude-fable-5-2", "medium"), 3, 3, 4), OPUS_PROJECT))
self.assertNotIn("escalation", prompts.resumed("", Route(Rung("claude-fable-5-2", "max"), 3, 4, 8), OPUS_PROJECT))
self.assertIn(" An escalation trigger in `~/.claude/CLAUDE.md` lets you hand the hard part of a task to a subagent with the Agent tool set to `model fable, effort high`, one rung above yours, only once the human agrees;", prompts.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 3, 4), OPUS_PROJECT))
self.assertIn("set to `model fable, effort max`, one rung above yours, only once the human agrees;", prompts.resumed("", Route(Rung("claude-fable-5-2", "high"), 3, 4, 5), OPUS_PROJECT), "one rung below the top still names the rung above")
self.assertNotIn("rerun", prompts.resumed("", Route(Rung("claude-opus-5-5", "low"), 3, 3, 4), OPUS_PROJECT), "a worker off the ladder is told no rerun rung")
self.assertIn("hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort high`, one rung above yours;", prompts.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 4, 5), OPUS_PROJECT))
self.assertNotIn("escalation", prompts.resumed("", Route(Rung("m")), None))
self.assertNotIn("escalation", prompts.resumed("", Route(Rung("claude-opus-5-5", "low"), 3, 3, 4), OPUS_PROJECT))
self.assertIn(f"{prompts.READING_RULE} {prompts.NAME_THE_ITEMS}\n\nWhere an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model fable, effort low` from 5, `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8. When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort low`, one rung above yours, and on each further trigger one rung higher, up to `model fable, effort medium`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number. Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model fable, effort medium`. A reviewer", prompts.fresh("Do it.", "## Goals", Route(opus), OPUS_PROJECT, self.FACTS))
self.assertIn(" When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort medium`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort xhigh`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT))
self.assertIn(" When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort xhigh`, one rung above yours; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "medium"), 3, 3, 4), OPUS_PROJECT))
self.assertNotIn("escalation", prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "max"), 3, 4, 8), OPUS_PROJECT))
self.assertIn(" An escalation trigger in `~/.claude/CLAUDE.md` lets you hand the hard part of a task to a subagent with the Agent tool set to `model fable, effort high`, one rung above yours, only once the human agrees;", prompts.WORKER.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 3, 4), OPUS_PROJECT))
self.assertIn("set to `model fable, effort max`, one rung above yours, only once the human agrees;", prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "high"), 3, 4, 5), OPUS_PROJECT), "one rung below the top still names the rung above")
self.assertNotIn("rerun", prompts.WORKER.resumed("", Route(Rung("claude-opus-5-5", "low"), 3, 3, 4), OPUS_PROJECT), "a worker off the ladder is told no rerun rung")
self.assertIn("hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort high`, one rung above yours;", prompts.WORKER.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 4, 5), OPUS_PROJECT))
self.assertNotIn("escalation", prompts.WORKER.resumed("", Route(Rung("m")), None))
self.assertNotIn("escalation", prompts.WORKER.resumed("", Route(Rung("claude-opus-5-5", "low"), 3, 3, 4), OPUS_PROJECT))
self.assertIn(f"{prompts.READING_RULE} {prompts.NAME_THE_ITEMS}\n\nWhere an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model fable, effort low` from 5, `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8. When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort low`, one rung above yours, and on each further trigger one rung higher, up to `model fable, effort medium`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number. Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model fable, effort medium`. A reviewer", prompts.WORKER.fresh("Do it.", "## Goals", Route(opus), OPUS_PROJECT, self.FACTS))
def test_offers_the_worker_a_higher_rung_for_the_rest_of_the_chunk_up_to_the_escalation_cap(self):
opus = Rung("claude-opus-5-5", "medium")
offer = lambda cap: f" Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `{cap}`."
self.assertIn(f"`Escalation trigger <n>:`, n the trigger's number.{offer('model fable, effort low')}", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
self.assertIn(f"`Escalation trigger <n>:`, n the trigger's number.{offer('model opus, effort xhigh')}", prompts.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT))
self.assertNotIn("Where the hard part", prompts.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 3, 4), OPUS_PROJECT))
self.assertIn(f"`Escalation trigger <n>:`, n the trigger's number.{offer('model fable, effort low')}", prompts.WORKER.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
self.assertIn(f"`Escalation trigger <n>:`, n the trigger's number.{offer('model opus, effort xhigh')}", prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT))
self.assertNotIn("Where the hard part", prompts.WORKER.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 3, 4), OPUS_PROJECT))
def test_lets_a_markdown_only_branch_review_on_the_projects_rung_where_the_reviewers_run_above_it(self):
opus = Rung("claude-opus-5-5", "medium")
markdown = " Where your branch changes only Markdown, none of it `CLAUDE.md`, `AGENTS.md`, `workflow-bench/*-prompt.md` or under `agents/`, `principles/`, `rules/` or `skills/`, launch each reviewer on the project's rung instead, with the Agent tool set to model opus, effort medium."
self.assertIn(markdown, prompts.fresh("Do it.", "## Goals", Route(opus, 3, 2, 7), OPUS_PROJECT, self.FACTS))
self.assertIn(markdown, prompts.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT))
self.assertNotIn("only Markdown", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
self.assertIn(markdown, prompts.WORKER.fresh("Do it.", "## Goals", Route(opus, 3, 2, 7), OPUS_PROJECT, self.FACTS))
self.assertIn(markdown, prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT))
self.assertNotIn("only Markdown", prompts.WORKER.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
def test_names_the_rung_a_reviewer_or_seat_reruns_on_one_above_its_own(self):
opus = Rung("claude-opus-5-5", "medium")
both = " A reviewer or comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort low`."
self.assertTrue(prompts.resumed("", Route(opus, 3, 2, 4), OPUS_PROJECT).endswith(both))
self.assertTrue(prompts.resumed("", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 4), OPUS_PROJECT).endswith(both))
self.assertTrue(prompts.fresh("Do it.", "## Goals", Route(opus), OPUS_PROJECT, self.FACTS).split(f"\n\n{self.FACTS}")[0].endswith(both))
self.assertTrue(prompts.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT).endswith(" A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort medium`, and a comprehension seat with `model fable, effort low`."))
self.assertTrue(prompts.resumed("", Route(opus, 3, 2, 7), OPUS_PROJECT).endswith(" A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort high`, and a comprehension seat with `model fable, effort low`."))
self.assertTrue(prompts.resumed("", Route(Rung("claude-fable-5-2", "max"), 3, 4, 8), OPUS_PROJECT).endswith(" A comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort low`."))
self.assertNotIn("rerun", prompts.resumed("", Route(Rung("m")), None))
self.assertNotIn("rerun", prompts.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, self.FACTS))
self.assertIn(f"{both} After your first read", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
self.assertTrue(prompts.WORKER.resumed("", Route(opus, 3, 2, 4), OPUS_PROJECT).endswith(both))
self.assertTrue(prompts.WORKER.resumed("", Route(Rung("claude-sonnet-5-5", "high"), 3, 2, 4), OPUS_PROJECT).endswith(both))
self.assertTrue(prompts.WORKER.fresh("Do it.", "## Goals", Route(opus), OPUS_PROJECT, self.FACTS).split(f"\n\n{self.FACTS}")[0].endswith(both))
self.assertTrue(prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "low"), 3, 3, 4), OPUS_PROJECT).endswith(" A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort medium`, and a comprehension seat with `model fable, effort low`."))
self.assertTrue(prompts.WORKER.resumed("", Route(opus, 3, 2, 7), OPUS_PROJECT).endswith(" A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort high`, and a comprehension seat with `model fable, effort low`."))
self.assertTrue(prompts.WORKER.resumed("", Route(Rung("claude-fable-5-2", "max"), 3, 4, 8), OPUS_PROJECT).endswith(" A comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort low`."))
self.assertNotIn("rerun", prompts.WORKER.resumed("", Route(Rung("m")), None))
self.assertNotIn("rerun", prompts.WORKER.fresh("Do it.", "## Goals", Route(Rung("m", "high"), 3, 4, 5), None, self.FACTS))
self.assertIn(f"{both} After your first read", prompts.WORKER.fresh("Do it.", "## Goals", Route(opus, 3, 2, 4), OPUS_PROJECT, self.FACTS))
fable = Rung("claude-fable-5-2", "max")
self.assertNotIn("rerun", prompts.resumed("", Route(fable), ProjectRung(LADDER, fable)))
self.assertNotIn("rerun", prompts.WORKER.resumed("", Route(fable), ProjectRung(LADDER, fable)))
def test_opens_a_fresh_session_by_name_and_resumes_an_open_one(self):
opened = session.session_named("A proj loop-claude", pathlib.Path("/h/.claude/projects"))
fresh = worker.worker_args(opened, Rung("m"), prompts.fresh("Do it.", "## Goals\n1. g\n\n## Audience\nme", Route(Rung("m")), None, self.FACTS), resume=False)
fresh = worker.worker_args(opened, Rung("m"), prompts.WORKER.fresh("Do it.", "## Goals\n1. g\n\n## Audience\nme", Route(Rung("m")), None, self.FACTS), resume=False)
self.assertEqual(fresh[fresh.index("--session-id") + 1], str(opened.id))
self.assertEqual(fresh[fresh.index("--name") + 1], "A proj loop-claude")
resumed = worker.worker_args(opened, Rung("m"), prompts.resumed("", Route(Rung("m")), None), resume=True)
resumed = worker.worker_args(opened, Rung("m"), prompts.WORKER.resumed("", Route(Rung("m")), None), resume=True)
self.assertEqual(resumed[resumed.index("--resume") + 1], str(opened.id))
self.assertNotIn("--session-id", resumed)
self.assertTrue(resumed[resumed.index("-p") + 1].startswith("Continue the task; the previous run ended before the chunk was finished. The chunk is finished once"))
@@ -1924,7 +1931,7 @@ class Records(unittest.TestCase):
class JudgePrompt(unittest.TestCase):
def test_shows_the_transcripts_tail_and_returns_what_it_showed(self):
entries = [assistant({"type": "text", "text": "old " + "x" * judge.JUDGE_PROMPT_CHARS}), assistant({"type": "text", "text": "new"})]
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 0))
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 0, prompts.DRIVER))
self.assertTrue(grounds.shown.endswith("\n\nnew"))
self.assertNotIn("old", grounds.shown)
self.assertIn(grounds.shown, prompt)
@@ -1933,11 +1940,11 @@ class JudgePrompt(unittest.TestCase):
self.assertEqual(grounds.quotable, "## Goals\n\n")
def test_the_judge_prompt_and_schema_call_the_worker_the_worker(self):
prompt, _ = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(assistant({"type": "text", "text": "done"})), 1))
self.assertNotRegex(prompt + json.dumps(judge.JUDGE_SCHEMA), r"\b[Aa]gent")
prompt, _ = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(assistant({"type": "text", "text": "done"})), 1, prompts.DRIVER))
self.assertNotRegex(prompt + json.dumps(judge.judge_schema(prompts.DRIVER)), r"\b[Aa]gent")
def test_the_judge_prompt_names_the_entry_points_answer_destinations_in_both_rules_on_a_recorded_answer(self):
prompt, _ = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", "the ledger", kinds(assistant({"type": "text", "text": "done"})), 0))
prompt, _ = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", "the ledger", kinds(assistant({"type": "text", "text": "done"})), 0, prompts.DRIVER))
self.assertIn("is recorded in the ledger at the one place it governs", prompt)
self.assertIn("the worker writing it into the ledger, but not into one of the human's rules", prompt)
@@ -1946,28 +1953,28 @@ class JudgePrompt(unittest.TestCase):
self.assertIn("is recorded in the ledger at the one place it governs.", ledger.typed("Which one?", "Use B.", Route(Rung("worker-model")), None, False))
def test_the_judge_prompt_names_every_rule_the_judge_reads_from_the_human(self):
self.assertEqual([name for name in records.HUMAN_RULE_NAMES if name not in judge.judge_rules(prompts.ANSWER_DESTINATIONS)], [])
self.assertEqual([name for name in records.HUMAN_RULE_NAMES if name not in judge.judge_rules(prompts.ANSWER_DESTINATIONS, prompts.DRIVER)], [])
def test_shows_the_judge_where_the_worker_last_stepped_up_and_checks_an_escalation_only_after_it(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "round 3: 🔴"})]
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1))
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1, prompts.DRIVER))
self.assertRegex(prompt, "round 2: 🔴\n\n\\[step\\] [^\n]+\n\nround 3: 🔴\n\n")
self.assertEqual(grounds.after_mark, "round 3: 🔴")
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 0))
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 0, prompts.DRIVER))
self.assertNotIn("stepped the worker up", prompt)
self.assertEqual(grounds.shown, "round 2: 🔴\n\nround 3: 🔴")
self.assertEqual(grounds.after_mark, "round 2: 🔴\n\nround 3: 🔴")
def test_drops_an_escalation_quote_from_after_the_step_up_that_the_tail_it_shows_cuts_off(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "old " + "x" * judge.JUDGE_PROMPT_CHARS}), assistant({"type": "text", "text": "new"})]
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1))
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1, prompts.DRIVER))
self.assertEqual(judge.quotes_checked(Unfinished("e", "old x", entries_read=3), grounds), Unfinished("e", entries_read=3))
self.assertEqual(judge.quotes_checked(Unfinished("e", "new", entries_read=3), grounds), Unfinished("e", "new", entries_read=3))
def test_shows_a_typed_answer_before_the_step_up_as_the_humans(self):
typed = prompts.WORKER.typed("Which one?", "Use B.", Route(Rung("worker-model")), None, False)
entries = [{**human(typed), "promptSource": "sdk"}, assistant({"type": "text", "text": "round 3: 🔴"})]
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1))
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1, prompts.DRIVER))
self.assertIn("\n\n[human] Use B.\n\n[step] ", grounds.shown)
@@ -2105,7 +2112,7 @@ class ChunkItems(unittest.TestCase):
self.assertEqual(chunk_items.named([said(example)]), (297, 298))
def test_every_prompt_that_starts_or_resumes_a_chunk_asks_for_the_line(self):
self.assertIn("on one line, as in `Chunk items: ", prompts.resumed("", Route(Rung("m")), None))
self.assertIn("on one line, as in `Chunk items: ", prompts.WORKER.resumed("", Route(Rung("m")), None))
def test_reads_only_a_line_the_worker_opens_with_the_label_in_its_own_text(self):
prompt = entries.LoopPrompt(text="Chunk items: 297 (L 3, E + I 5)")
@@ -2194,7 +2201,7 @@ class Verdict(unittest.TestCase):
def test_drops_an_escalation_quote_found_only_in_the_transcript_entries_before_the_workers_last_step_up(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "round 3: 🔴"}), assistant({"type": "text", "text": "working"})]
def judged_on(mark, escalation):
return judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), mark), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation=escalation)]).effects())
return judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), mark, prompts.DRIVER), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation=escalation)]).effects())
self.assertEqual(judged_on(0, "round 2: 🔴"), Unfinished("working", "round 2: 🔴", entries_read=3))
self.assertEqual(judged_on(1, "round 2: 🔴"), Unfinished("working", entries_read=3))
self.assertEqual(judged_on(1, "round 3: 🔴"), Unfinished("working", "round 3: 🔴", entries_read=3))
@@ -2203,12 +2210,12 @@ class Verdict(unittest.TestCase):
def test_drops_an_escalation_quote_that_only_loop_claudes_prompts_or_the_humans_lines_repeat_after_the_step_up(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), {**human("as the work remaining: round 2: 🔴"), "promptSource": "sdk"}, human("round 2: 🔴 again"), assistant({"type": "text", "text": "working"})]
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation="round 2: 🔴")]).effects())
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1, prompts.DRIVER), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation="round 2: 🔴")]).effects())
self.assertEqual(verdict, Unfinished("working", entries_read=4))
def test_takes_evidence_from_before_the_workers_last_step_up(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "working"})]
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence="round 2: 🔴")]).effects())
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1, prompts.DRIVER), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence="round 2: 🔴")]).effects())
self.assertEqual(verdict, Unfinished("round 2: 🔴", entries_read=2))
+1
View File
@@ -16,6 +16,7 @@ PRIVATE = [
"daemon.log",
"daemon/control.key",
"debug/a.txt",
"do-epic-transcripts/a/b.jsonl",
"file-history/a/b.md",
"history.jsonl",
"jobs/a/b.json",
+1 -1
View File
@@ -152,7 +152,7 @@ Valid while `~/.claude` is a checkout of this repo.
- **Ranking.** Score, then Blocked by, in one weight chain: the epic's achieve goals, then code health, then the repo's goals. Where the epic and a repo disagree, the epic wins. do-epic re-ranks Jira's backlog to match, and people's issues keep their rank.
- **Releases.** An epic item has no release. It ships into its repo's unreleased work: a bullet under `CHANGELOG.md` → `## Unreleased`, or nothing where the repo's plan is in Jira.
- **Repos.** A repo's name is its main checkout's folder name, and a project config names that checkout. A missing checkout is cloned from the host of the epic's other repos; where unsure, do-epic asks. Unsure means the other repos don't all sit under one host and owner (the same host spelt as https and as ssh counts as two), an origin can't be read or isn't an https, ssh or scp-style address, the folder to clone into holds something else, or the clone fails. A repo no config names is cloned into the clone folder, and the human is asked to write its config. Each chunk uses its repo's model, routing, and language for commits and PRs. Jira text is in the epic's language, or else the machine's default.
- **Running.** The epic caps the chunks running at once, and each repo's `parallel-chunks` still applies. do-epic and loop-claude never run chunks in the same repo at once.
- **Running.** The epic caps the chunks running at once, and each repo's `parallel-chunks` still applies. do-epic and loop-claude never run chunks in the same repo at once. The cap is a line of the epic's description, `**Max parallel chunks:** 2`, and 1 without it, as `parallel-chunks` is. A repo's `parallel-chunks` counts the chunks of every epic in its checkout. Each window is named for its issue's key, and a tmux window option, `@chunk-root`, names the folder its chunk works in, which is how loop-claude sees do-epic's chunks in a checkout. do-epic and loop-claude each hold the checkout's `starting` lock from checking the checkout's chunks to starting a window there. A chunk without a repo works in `~/.local/state/do-epic/<EPIC-KEY>/`. do-epic archives its cycles under `~/.claude/do-epic-transcripts/`, not in loop-claude's archive, whose readers parse loop-claude's prompts. An open issue runs once a label records its repo; until do-epic picks repos itself, an issue without one waits, and `do-epic <EPIC-KEY>` says so.
- **Long gates.** A chunk whose PR waits on a gate, such as a human approval, parks. It keeps its worktree, PR and session, and its state is in a file that survives a reboot. A parked chunk takes no running slot, and the items it blocks wait. do-epic polls the forge and resumes the chunk's session when the gate passes or a reviewer comments. It fixes reasonable feedback, replies to the rest, and changes the setup so review would have caught it. `do-epic <key> --status` and the tmux window names show what each chunk waits on.
- **Human tasks.** do-epic DMs the human when one blocks the next item, and polls until its issue closes.
- **Findings.** A finding about the epic's goals is filed in the epic. A finding about a repo's goals follows that repo's rules. Where unsure which, do-epic asks. A set of new items toward an epic goal needs the human's approval before work starts; a finding filed during a chunk doesn't.
+34 -21
View File
@@ -6,22 +6,24 @@
`Bar = 0.1`
`Next ID = 440`
`Next ID = 443`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 410 | 0.12.0 | | | **Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.** | 3 | 2 | 3 | 6 | 6 | 1 by 5 | 0.8 |
| 416 | 0.12.0 | 410 | | **Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.** | 1 | 1 | 1 | 1 | 2 | 1 by 5 | 2.1 |
| 413 | 0.12.0 | 410 | | **File a finding about an epic goal in the epic and one about a repo goal by that repo's rules, ask the human where unsure which, and give the judge the epic's records beside the repo's.** | 3 | 2 | 3 | 6 | 4 | 1 by 5 | 1.6 |
| 415 | 0.12.0 | 410, 413 | | **Finish an epic: run release-review passes on each repo it changed, work what they file, have the human confirm each goal, post a summary comment, and close the epic in Jira last.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 441 | 0.12.0 | | | **Move an epic's issue to done in Jira when its chunk finishes, so no finished chunk starts again and what it blocks starts.** | 2 | 2 | 2 | 4 | 3 | 1 by 6 | 2.3 |
| 416 | 0.12.0 | | | **Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.** | 1 | 1 | 1 | 1 | 2 | 1 by 5 | 2.1 |
| 413 | 0.12.0 | | | **File a finding about an epic goal in the epic and one about a repo goal by that repo's rules, ask the human where unsure which, and give the judge the epic's records beside the repo's.** | 3 | 2 | 3 | 6 | 4 | 1 by 5 | 1.6 |
| 415 | 0.12.0 | 413 | | **Finish an epic: run release-review passes on each repo it changed, work what they file, have the human confirm each goal, post a summary comment, and close the epic in Jira last.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 418 | 0.12.0 | 415 | | **Describe do-epic in `README.md`'s tools and setup, with its machine settings and `repo-rule.md`.** | 1 | 2 | 1 | 2 | 2 | 1 by 5 | 2.1 |
| 420 | 0.12.0 | | | **End a worker that printed its final result and lingers, by killing the background shells it left, after a few minutes, and print each kill with its evidence on loop-claude's terminal.** | 2 | 2 | 2 | 4 | 3 | 1.5 by 6 | 2.0 |
| 411 | 0.12.0 | 410 | | **Park a chunk whose PR waits on a long gate, keeping its worktree, PR and session in a state file that survives a reboot, and resume its session when the gate passes or a reviewer comments.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 412 | 0.12.0 | 410, 411 | | **Print each chunk of an epic, running, parked with its gate and since when, or stopped, each human task and each open interrupt with `do-epic <key> --status`, and name a parked chunk's gate in its tmux window's name.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 414 | 0.12.0 | 410 | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 417 | 0.12.0 | 410 | | **Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 411 | 0.12.0 | | | **Park a chunk whose PR waits on a long gate, keeping its worktree, PR and session in a state file that survives a reboot, and resume its session when the gate passes or a reviewer comments.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 412 | 0.12.0 | 411 | | **Print each chunk of an epic, running, parked with its gate and since when, or stopped, each human task and each open interrupt with `do-epic <key> --status`, and name a parked chunk's gate in its tmux window's name.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 414 | 0.12.0 | | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 417 | 0.12.0 | | | **Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 440 | 0.12.0 | | | **End the shell that the interrupt test of `mutate-changes` starts within a minute, so a mutation run of this repo never waits on it for ever.** | 1 | 1 | 2 | 2 | 2 | 1 by 4 | 1.7 |
| 442 | 0.12.0 | | | **Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 310 | 0.12.0 | | | **Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.** | 3 | 2 | 3 | 6 | 4 | 1.4 by 3 | 0.9 |
| 422 | 0.12.0 | 420 | | **Check every 5 minutes whether a tmux window of the loop looks stuck by other signs than a lingering worker, investigate it with a headless claude, and kill only the process the investigation names.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 4 | 0.8 |
| 365 | 0.13.0 | | | **Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
@@ -76,22 +78,16 @@
## Details
### 410. Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.
### 441. Move an epic's issue to done in Jira when its chunk finishes, so no finished chunk starts again and what it blocks starts.
The lock that keeps do-epic and loop-claude apart is the per-project `starting` flock, shared by both (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Each chunk routes on its repo's model and ladder, a no-repo chunk on the machine setting's model. `loop/chunk_windows.py` `start_chunks` is a place the seats found hard: make it easier to read where it changes. Where a do-epic cycle's worker, judge or human reads the driver's name, they read do-epic, never loop-claude: item 401 left `agent_cycle`'s own text naming loop-claude, since whether the markers that code matches (`TYPED_HERE`, `TRANSCRIPT_HEADING`) vary by driver depends on what do-epic calls itself and where it archives its cycles. The worker's prompt and the judge's rules share the phrase a worker asks for a higher rung with, so both take it from one place.
A chunk that finishes leaves its issue open, since `EpicStore` has no way to close one. `scheduler.start_chunks` then counts the issue as a chunk to start: the finished chunk passes over its own issue, but the next chunk that finishes, or the next `do-epic <EPIC-KEY>`, starts it afresh, and an issue it blocks never starts. Both reviewers of item 410's chunk asked about it. Close the issue from `main.handed_on`, before it starts the next chunks, for a chunk in a repo and one without; a Jira workflow that refuses the move stops the chunk with the reason.
Touches:
- `bin/loop_claude/loop/chunk_windows.py`: `starting`, `start_chunks` (small)
- `bin/agent_cycle/tmux.py`: `session_name` (small)
- `bin/do-epic`
- `bin/do_epic/main.py`
- `bin/do_epic/scheduler.py`
- `bin/agent_cycle/worker_prompts.py`: `TYPED_HERE`, `stepped_to` (small)
- `bin/agent_cycle/judge.py`: `TRANSCRIPT_HEADING`, `Reply.escalation` (small)
- `bin/agent_cycle/escalation_mark.py`: `STEP_LINE` (small)
- `bin/agent_cycle/interrupt.py`
- `bin/agent_cycle/stop.py`
- `bin/do_epic/backend/protocol.py`: `EpicStore`
- `bin/do_epic/backend/jira.py`: `JiraEpic`
- `bin/do_epic/backend/fake.py`: `MemoryEpic`
- `bin/do_epic/main.py`: `handed_on` (small)
### 416. Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.
@@ -190,6 +186,23 @@ Touches:
- `bin/do-epic-e2e`
- `bin/do_epic/e2e/`
### 440. End the shell that the interrupt test of `mutate-changes` starts within a minute, so a mutation run of this repo never waits on it for ever.
Today a `mutate-changes` run on this repo can wait for ever: mutmut runs `bin/mutate_changes/test_mutate_changes.py` → `test_an_interrupt_reaches_the_tool_before_the_run_kills_it` inside its own process, where the test's SIGINT doesn't reach the `sh -c "trap … while :; do sleep 0.1; done"` it started. The shell then loops for good as mutmut's child, and mutmut waits for it. Three runs of two chunks hung this way on 2026-11-18, one for over two hours, each holding a heavy slot until someone killed the shell. Give the helper shell a deadline of its own, so it ends where no signal arrives, or leave the test out of what mutmut runs.
Touches:
- `bin/mutate_changes/test_mutate_changes.py`: `test_an_interrupt_reaches_the_tool_before_the_run_kills_it` (small)
### 442. Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.
Today `do-epic <EPIC-KEY>` starts only an issue whose label already records its repo, and prints that every other one waits (`bin/do_epic/scheduler.py` → `chunks`). `split.split`, `repo_pick.picked` and `ranking` exist and nothing calls them. Each is a headless claude call on a rung: route it on `repoless-model`'s rung of the shipped ladder. An `Unclear` pick is an interrupt on the terminal of the `do-epic <EPIC-KEY>` the human runs. A chunk that finishes starts the next chunks without planning again, so no window waits on a question.
Touches:
- `bin/do_epic/main.py`: `windows_opened`, `chunks_started`
- `bin/do_epic/planning.py`
- `bin/do_epic/test_main.py`
### 310. Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.
281 worker resumes after the 1-hour cache expired rewrote a whole context, $379 of the $9,154 measured from 2026-09-30 to 2026-11-11 (4.1%). A compaction while the cache is warm reads the context at a twentieth of the input price and leaves about 20k tokens to rewrite later.