Merge remote-tracking branch 'origin/main' into item-457
CI / tests (pull_request) Successful in 3m44s

This commit is contained in:
Lilleman
2026-11-20 00:19:09 +01:00
32 changed files with 544 additions and 155 deletions
+7
View File
@@ -1,5 +1,12 @@
# Changelog
## Unreleased
- do-epic reads two new settings from a project's config: `jira-unblocking-statuses` names the statuses at which an issue unblocks the issues it blocks, and `jira-automation-moves-issues` leaves the move out of "In Progress" to the team's own automation.
- The prose standard asks that a sentence about several named things holds for each of them.
- `do-epic` resumes a chunk parked on `your merge` when its pull request no longer merges into its base, so the worker runs `chunk-pr merge` again to level the branch; a finished chunk in that state stays open until its pull request merges.
- `larv-review prepare-scoring` takes the scoring run's project values from the checkout's `skills/comprehension-panel/seat-prompts.md` where the working-rules file holds no "Scoring run" section, not only where that file is missing.
## 0.13.0
- Fix loop-claude stopping after a finished chunk: its judge may now quote the worker's task as evidence, so the loop starts the next chunks instead of exiting.
+4 -1
View File
@@ -119,7 +119,7 @@ A legacy project with no container setup sets `tooling-on-host = true`, so the l
A project whose pull requests need a human's approval sets `wait-for-approval = true` in its config. `chunk-pr merge` then waits, once the checks have passed, until GitHub reports the pull request approved as its branch protection requires, and merges it. It refuses on Gitea, where a reviewer requested changes and where the protection requires no review. While it waits, other chunks merge. It stops where a reviewer's comment waits for an answer, on an approved pull request too; answer it and run it again. It gives up after 90 minutes without an approval; run it again once the pull request is approved. Left out, the setting is false.
A project whose team merges its pull requests itself sets `merge = "human"`. `chunk-pr merge` then brings the branch level with origin's default branch, finishes the chunk's plan items, waits for the checks and marks the pull request ready, but leaves the merge to a person. A plan or changelog kept in the checkout is finished on the branch, so it lands with that merge; one kept in Jira, or in the config's folder, is finished at once; where you close the pull request unmerged, file the item again. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. loop-claude doesn't start a chunk for an item that a ready pull request finishes. Once no item left in the release can start and one awaits a merge, loop-claude stops and names the pull requests to merge; run it again after you merge one. The first chunk after a merge runs `chunk-pr clean` in the worktree the merged pull request left, where nobody pushed to the pull request after the chunk did. Nobody works on a pull request that awaits your merge. To have a reviewer's comment answered, turn the pull request back into a draft: a chunk then takes its item up again. Left out, the setting is `"chunk"`: the chunk merges.
A project whose team merges its pull requests itself sets `merge = "human"`. `chunk-pr merge` then brings the branch level with origin's default branch, finishes the chunk's plan items, waits for the checks and marks the pull request ready, but leaves the merge to a person. A plan or changelog kept in the checkout is finished on the branch, so it lands with that merge; one kept in Jira, or in the config's folder, is finished at once; where you close the pull request unmerged, file the item again. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. The chunk resumes and brings the branch level again once the pull request conflicts with the default branch. It does so too once the branch is behind a default branch whose protection, on GitHub, requires an up-to-date branch. loop-claude doesn't start a chunk for an item that a ready pull request finishes. Once no item left in the release can start and one awaits a merge, loop-claude stops and names the pull requests to merge; run it again after you merge one. The first chunk after a merge runs `chunk-pr clean` in the worktree the merged pull request left, where nobody pushed to the pull request after the chunk did. Nobody works on a pull request that awaits your merge. To have a reviewer's comment answered, turn the pull request back into a draft: a chunk then takes its item up again. Left out, the setting is `"chunk"`: the chunk merges.
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows: the plan, the working rules in an `AGENTS.md` I write for the agents, the records, and the goals and audience, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits in the checkout's history, so four things are not supported for it yet. `score-outcomes` and loop-claude's routing figures count a project's chunks only where `todo.md`, `docs/comprehension-history.md` and `docs/reading-cost.md` are at those paths in the checkout; otherwise each says so, and the loop goes on. For a plan or a comprehension history outside the checkout, `larv-review` says it cannot tell whether a scoring run is owed, and for such a history it cannot find a paired ruling's base. For a plan outside the checkout, chunk-preflight and loop-claude don't see a release whose last item has shipped, and say that its release review and its cut are yours to call. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
@@ -155,6 +155,9 @@ The last line prints each setting's path once the config is complete.
`do-epic` keeps its settings per machine, not per project, in `~/.claude-projects/do-epic/`, two files for every epic:
- `config.toml` sets `jira-url`, the site, such as `https://acme.atlassian.net`; `env-file`, the file holding `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, a path that starts with `/` or `~/`, outside the clone folder and every folder of `~/.claude-projects`; and `repoless-model`, the model that works an item with no repo. It may also set `clone-folder`, where a missing repo is cloned, `~/code` if left out; `language`, the language of Jira text, English if left out; and `jira-finish-transition` with `jira-finish-status`, which name the workflow transition that moves a finished chunk's issue, and closes a finished epic, and the status it leads to, such as `"Mark as done"` and `"Done"`. Set both or neither: without them do-epic moves no issue to done and closes no epic, and a chunk that finishes stops with that reason.
- `config.toml` fits do-epic to a team whose own automation moves issues, such as a CI job that moves an issue when its pull request merges. Two settings do:
- `jira-unblocking-statuses` lists the statuses at which an issue's work has landed though Jira doesn't count it done yet, such as `["Release Ready"]`, in upper or lower case. An issue in one of them takes no chunk and no longer blocks the issues it blocks, and `--status` names the statuses beside each blocker. A status Jira counts as done always does both. The release reviews, which are the epic's last chunk, still wait until Jira counts every issue done: run `do-epic <EPIC-KEY>` then, to start them.
- `jira-automation-moves-issues = true` keeps do-epic from moving the issue of a finished chunk in a repo: the automation moves it, and do-epic waits for that move before it starts what the issue blocks. An issue without a repo has no pull request, so do-epic still moves it, with `jira-finish-transition`. The setting needs `jira-unblocking-statuses`, which names the status the automation gives an issue whose pull request merged.
- `config.toml` may end with a `[label-repos]` table, for a team that already labels its issues by repo. Give it one line for each such label: the label, then the repo's name, such as `twu-4 = "tenant-web-ui-4"`. do-epic reads such a label as it reads its own `repo:<name>`. Where the label is the repo's name, map the name to itself, as in `core-4 = "core-4"`. Write every other setting above the table.
- `repo-rule.md` is prose that says how to tell an item's repo, such as "a label that equals a repo's name names that repo". It may not be blank. `do-epic <EPIC-KEY>` uses it to pick where each open issue without such a label is worked, and records the pick as a label: `repo:<name>` for its repo, `do-epic-claude` for work of Claude's that changes no repo, and `do-epic-human` for a task of yours. Where the rule leaves an issue unclear, do-epic asks you on the terminal. Answer with the label, or with Enter alone to leave the issue waiting. Change a pick by editing the label in Jira.
+9 -7
View File
@@ -74,6 +74,8 @@ def judge_rules(answer_destinations: str, driver: str) -> str:
# 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"
# Between the task and the tail that quotes_checked searches, so that no fragment of a quote runs across the join. plain() keeps it, and the judge's quotes hold no NUL.
PASSAGE_BREAK = "\x00"
def transcript_heading(driver: str) -> str:
@@ -85,7 +87,7 @@ 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 {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."})
evidence: str = dataclasses.field(metadata={"description": "A verbatim quote of the one passage of the task or the transcript 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."})
answered_before: str = dataclasses.field(metadata={"description": "With interrupt true, a [human] line from earlier in the chunk that answered the question the worker asks now, quoted verbatim, without elisions. Empty otherwise."})
@@ -248,20 +250,20 @@ def quotes_checked(verdict: Verdict, grounds: Grounds) -> Verdict | Failure:
Only a misquoted evidence fails. A Failure for any other would exit an unattended loop, so each changes the verdict instead.
"""
if not grounded(verdict.evidence, f"{grounds.task}\n\n{grounds.shown}"):
if not grounded(verdict.evidence, f"{grounds.task}{PASSAGE_BREAK}{grounds.shown}"):
return misquoted_evidence(verdict)
verdict = re_ask_checked(verdict, grounds.shown)
verdict = answer_checked(verdict, grounds.quotable)
return escalation_mark.checked(verdict, after=grounds.after_mark, shown=grounds.shown)
def grounded(evidence: str, rendered_transcript: str) -> bool:
"""Whether the transcript holds the evidence word for word, once emphasis marks are stripped and whitespace is reflowed in both. The judge joins passages with an ellipsis though told to quote one, so each fragment between ellipses must come after the one before it."""
transcript = plain(rendered_transcript)
def grounded(evidence: str, searched: str) -> bool:
"""Whether the searched text holds the evidence word for word, once emphasis marks are stripped and whitespace is reflowed in both. The judge joins passages with an ellipsis though told to quote one, so each fragment between ellipses must come after the one before it."""
searched = plain(searched)
fragments = [fragment.strip() for fragment in re.split(r"\.\.\.|…", plain(evidence)) if fragment.strip()]
after = 0
for fragment in fragments:
at = transcript.find(fragment, after)
at = searched.find(fragment, after)
if at < 0:
return False
after = at + len(fragment)
@@ -271,7 +273,7 @@ def grounded(evidence: str, rendered_transcript: str) -> bool:
def misquoted_evidence(verdict: Verdict) -> Failure:
asked = f", for the question: {verdict.question}" if isinstance(verdict, Interrupt | QuotedAnswer) else ""
return Failure(f"the judge quoted {verdict.evidence!r}, which is not in the transcript{asked}")
return Failure(f"the judge quoted {verdict.evidence!r}, which is not in the task or the transcript{asked}")
def re_ask_checked(verdict: Verdict, shown: str) -> Verdict:
+2 -1
View File
@@ -124,13 +124,14 @@ class Verdict(unittest.TestCase):
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", "the project's decisions", "the plan or a comment", kinds(*entries), 1, "loop-claude"), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence="round 2: 🔴")]).effects())
self.assertEqual(verdict, Unfinished("round 2: 🔴", entries_read=2))
def test_takes_the_task_as_evidence_where_the_tail_it_shows_cuts_off_the_workers_first_prompt(self):
def test_takes_the_task_as_evidence_where_the_tail_it_shows_cuts_off_the_workers_first_prompt_but_no_quote_across_the_join(self):
entries = [human("Do the next chunk. " + "x" * judge.JUDGE_PROMPT_CHARS), assistant({"type": "text", "text": "Merged."})]
def judged_on(evidence):
return judge.judge_once("/r", judge.Brief("Do the next chunk.", "## Goals", "", "the project's decisions", "the plan or a comment", kinds(*entries), 0, "loop-claude"), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence=evidence)] * 3).effects())
self.assertEqual(judged_on("Do the next chunk."), Unfinished("Do the next chunk.", entries_read=2))
self.assertEqual(judged_on("Do the next chunk. ... Merged."), Unfinished("Do the next chunk. ... Merged.", entries_read=2))
self.assertIsInstance(judged_on("Do the next release."), Failure)
self.assertIsInstance(judged_on("next chunk. xxx"), Failure)
class JudgePrompt(unittest.TestCase):
+1 -1
View File
@@ -188,7 +188,7 @@ Worker: {OFF_LADDER}
self.assertEqual(self.archived_outcomes(), [
"Task: Do it.\n\n"
f"{stamp} Judge reply rejected: the judge's reply has no answer of type string\n\nReply:\n> {unfilled.stdout}\n\nJudge: judge-model\n\n"
f"{stamp} Judge reply rejected: the judge quoted 'never said', which is not in the transcript\n\nReply:\n> {misquoted.stdout}\n\nJudge: judge-model\n\n"
f"{stamp} Judge reply rejected: the judge quoted 'never said', which is not in the task or the transcript\n\nReply:\n> {misquoted.stdout}\n\nJudge: judge-model\n\n"
f"{stamp} Verdict: finished\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"])
def test_archives_each_judge_runs_prompt_and_reply_beside_the_rejection_interrupt_and_verdict_it_gave(self):
+25 -3
View File
@@ -17,6 +17,8 @@ One pair per machine, the same for every epic (docs/decisions.md → `do-epic: d
- `clone-folder` is the folder a missing repo is cloned into: a path that starts with / or ~/. `~/code` where left out.
- `language` is the default language of Jira text, by its English name. English where left out.
- `jira-finish-transition` and `jira-finish-status` name the workflow transition that moves a finished chunk's issue and closes a finished epic, such as "Mark as done", and the status it leads to, such as "Done". A project's config names a plan item's the same way. Set both or neither; without them do-epic moves no issue to done and closes no epic.
- `jira-unblocking-statuses` lists the statuses at which an issue's work has landed though Jira doesn't count it done yet, such as `["Release Ready"]`, in upper or lower case. An issue in one of them takes no chunk and no longer blocks the issues it blocks. A status Jira counts as done always does both, listed or not.
- `jira-automation-moves-issues = true` says the team's own automation moves an issue when its pull request merges. do-epic then moves only the issue of a chunk without a repo, which has no pull request, and waits for the automation to move each other. It needs `jira-unblocking-statuses`, which then names the status the automation gives an issue whose pull request merged. false where left out.
- `[label-repos]` has one line for each label of the team's own that names a repo: the label, then that repo's name, such as `twu-4 = "tenant-web-ui-4"`. do-epic reads such a label as it reads its own `repo:<name>`. A team whose label is the repo's name maps the name to itself.
- `repo-rule.md` is prose that says how to tell an item's repo, and mustn't be blank."""
import dataclasses
@@ -24,7 +26,7 @@ import pathlib
import re
import types
from project_config.settings import anywhere, CONFIG, DO_EPIC, ENV_FILE, Finish, finish_faults, finish_of, JIRA_FINISH, LANGUAGE, language_fault, lies_in, parsed, PROJECTS, SITE
from project_config.settings import anywhere, CONFIG, DO_EPIC, ENV_FILE, Finish, finish_faults, finish_of, JIRA_FINISH, LANGUAGE, language_fault, lies_in, name_of, parsed, PROJECTS, SITE
from failure import Failure
from do_epic.backend.protocol import LABEL
from do_epic.repo_pick import LabelRepos, of_label, REPO_NAME, REVIEW_LABEL
@@ -40,7 +42,10 @@ CLONE_FOLDER = "clone-folder"
SETTINGS = (JIRA_URL, ENV_FILE, REPOLESS_MODEL)
# Three readers, seated as those who write and read this config, picked `label-repos` from four candidates, over `repo-aliases`, `repo-labels` and `team-labels`, 2-1. All three readers would misread `repo-labels` as mapping a repo to its label.
LABEL_REPOS = "label-repos"
OPTIONAL = (CLONE_FOLDER, LANGUAGE, *JIRA_FINISH, LABEL_REPOS)
# Three readers, seated as those who write and read this config, picked `jira-unblocking-statuses` from four candidates, 3-0, and `jira-automation-moves-issues` 2-1. `jira-unblock-statuses` reads as statuses do-epic moves an issue to, and `jira-finish-issues = false` as closing no epic either.
UNBLOCKING_STATUSES = "jira-unblocking-statuses"
AUTOMATION_MOVES = "jira-automation-moves-issues"
OPTIONAL = (CLONE_FOLDER, LANGUAGE, *JIRA_FINISH, UNBLOCKING_STATUSES, AUTOMATION_MOVES, LABEL_REPOS)
LISTED = f"The settings are {', '.join(SETTINGS)}, and optionally {listed(OPTIONAL, 'and')}."
@@ -58,6 +63,9 @@ class DoEpicConfig:
finish: Finish | None = None
# The LABEL_REPOS table; empty where the config has none.
label_repos: LabelRepos = types.MappingProxyType({})
# The UNBLOCKING_STATUSES list; empty where the config has none.
unblocking: tuple[str, ...] = ()
automation_moves: bool = False
def label_repo_faults(table: object) -> list[str]:
@@ -72,6 +80,17 @@ def label_repo_faults(table: object) -> list[str]:
]
def workflow_faults(values: dict[str, object]) -> list[str]:
"""What is wrong with the UNBLOCKING_STATUSES list and the AUTOMATION_MOVES switch in values."""
statuses, moves = values.get(UNBLOCKING_STATUSES, ["Done"]), values.get(AUTOMATION_MOVES, False)
return [
*([f"`{UNBLOCKING_STATUSES}` is {statuses!r}, not a list of the status names Jira shows, such as [\"Release Ready\"]"] if not (isinstance(statuses, list) and statuses and all(name_of(status) for status in statuses)) else []),
*([f"`{AUTOMATION_MOVES}` is {moves!r}, not true or false"] if not isinstance(moves, bool) else []),
# With no status listed, an issue whose pull request merged would read as open, and its chunk would start again.
*([f"`{AUTOMATION_MOVES}` is set, so `{UNBLOCKING_STATUSES}` must name the status the automation gives an issue whose pull request merged"] if moves is True and UNBLOCKING_STATUSES not in values else []),
]
def load(home: pathlib.Path, ladder_file: pathlib.Path = SHIPPED) -> DoEpicConfig | Failure:
"""The settings and the repo rule under home; a Failure naming the file it can't read, else each missing or misspelt setting it finds, so that do-epic refuses to start."""
folder = home / PROJECTS / DO_EPIC
@@ -102,6 +121,7 @@ def load(home: pathlib.Path, ladder_file: pathlib.Path = SHIPPED) -> DoEpicConfi
*([f"`{LANGUAGE}` is {language!r}, {fault}"] if LANGUAGE in values and (fault := language_fault(language)) else []),
*([f"`{REPOLESS_MODEL}` is {model!r}, not a model on the routing ladder: {', '.join(models)}"] if REPOLESS_MODEL in values and model not in models else []),
*finish_faults(values),
*workflow_faults(values),
*label_repo_faults(values.get(LABEL_REPOS, {})),
*([rule.reason] if isinstance(rule, Failure) else [f"`{REPO_RULE}` is blank"] if not rule.strip() else []),
]
@@ -111,4 +131,6 @@ def load(home: pathlib.Path, ladder_file: pathlib.Path = SHIPPED) -> DoEpicConfi
assert clone_folder and env_file and isinstance(url, str) and isinstance(model, str) and isinstance(language, str) and isinstance(rule, str)
labels = values.get(LABEL_REPOS, {})
assert isinstance(labels, dict)
return DoEpicConfig(folder, url, env_file, clone_folder, language, model, rule, finish_of(values), types.MappingProxyType(labels))
statuses = values.get(UNBLOCKING_STATUSES, [])
assert isinstance(statuses, list)
return DoEpicConfig(folder, url, env_file, clone_folder, language, model, rule, finish_of(values), types.MappingProxyType(labels), tuple(statuses), values.get(AUTOMATION_MOVES) is True)
+13 -5
View File
@@ -5,7 +5,7 @@ import dataclasses
import typing
from forge.reviews import ANSWERED, APPROVED, CHANGES_REQUESTED, review_decision, REVIEW_REQUIRED, waiting_threads
from forge.pulls import CheckFailed, checks_now, open_pull, Pending, required_checks
from forge.pulls import CheckFailed, checks_now, open_pull, Pending, required_checks, unmergeable
from failure import Failure
from forge.commands import forge_of, Run
@@ -39,10 +39,15 @@ class Unopened(Open):
"""An Open whose worktree stands though no pull request is open at its head: one that was merged or closed, whose chunk still has its worktree to remove."""
@dataclasses.dataclass(frozen=True)
class Unmergeable(Open):
"""An Open whose pull request awaits a person's merge and doesn't merge into its base as it stands: its worker levels the branch."""
def gate(branch: str, checkout: str, at: typing.Callable[[str], Run], by_human: bool) -> Gate | Open | Failure:
"""What the chunk on branch waits on, in a worktree of checkout; at gives the runner of commands in a folder, and by_human says the project's config leaves the merge to a person (`merge = "human"`). A Failure where git or the forge cannot be read, which doesn't say anything about the gate.
A draft never waits on a gate: its worker still works on it. On Gitea only the checks are a gate, since chunk-pr reads approvals on GitHub only (`chunk_pr.approval.awaited`). Changes a reviewer requested are news until the worker answered them (`forge.reviews.answered`); from then on the pull request awaits a new review. Where a person merges, a pull request with nothing else to wait on awaits that merge, and the chunk has news again once the pull request is no longer open.
A draft never waits on a gate: its worker still works on it. On Gitea only the checks are a gate, since chunk-pr reads approvals on GitHub only (`chunk_pr.approval.awaited`). Changes a reviewer requested are news until the worker answered them (`forge.reviews.answered`); from then on the pull request awaits a new review. Where a person merges, a pull request with nothing else to wait on awaits that merge. The chunk has news again once the pull request is no longer open. It has news too once the pull request no longer merges into its base as it stands (`forge.pulls.unmergeable`): the worker then levels the branch for that person.
"""
worktree = worktree_of(branch, at(checkout))
if not isinstance(worktree, str):
@@ -77,9 +82,12 @@ def gate(branch: str, checkout: str, at: typing.Callable[[str], Run], by_human:
return Open(f"a reviewer's comment on pull request #{pull} waits for an answer, in {', '.join(waiting)}")
if decision in (ANSWERED, REVIEW_REQUIRED):
return Gate(worktree, pull, NEW_REVIEW if decision == ANSWERED else APPROVAL)
if by_human:
return Gate(worktree, pull, MERGE)
return Open(f"pull request #{pull} passed its checks" + (" and is approved" if decision == APPROVED else ""))
if not by_human:
return Open(f"pull request #{pull} passed its checks" + (" and is approved" if decision == APPROVED else ""))
blocked = unmergeable(forge, pull, run)
if isinstance(blocked, Failure):
return blocked
return Unmergeable(f"pull request #{pull} {blocked}; run chunk-pr merge again to level the branch") if blocked else Gate(worktree, pull, MERGE)
def worktree_of(branch: str, run: Run) -> str | None | Failure:
+5 -5
View File
@@ -16,11 +16,11 @@ from agent_cycle import tmux
AWAITS = "a human's task"
def holds_up(key: str, issues: list[EpicIssue], team: LabelRepos) -> list[str]:
def holds_up(key: str, issues: list[EpicIssue], team: LabelRepos, unblocking: tuple[str, ...]) -> list[str]:
"""The keys of the open issues that the human's task called key holds up; none where it is no such task, is closed, or an issue blocks it."""
if not any(chunk.human and chunk.issue == key for chunk in scheduler.chunks(issues, team)[0]):
if not any(chunk.human and chunk.issue == key for chunk in scheduler.chunks(issues, team, unblocking)[0]):
return []
return scheduler.held_up(issues)[key]
return scheduler.held_up(issues, unblocking)[key]
def message(task: EpicIssue, epic: str, held: list[str]) -> str:
@@ -37,7 +37,7 @@ def notifier_checkout(issues: list[EpicIssue], team: LabelRepos, home: pathlib.P
return None
def awaited(task: EpicIssue, epic: str, store: EpicStore, team: LabelRepos, window: tmux.Window, poll: int, home: pathlib.Path, effects: Effects) -> None:
def awaited(task: EpicIssue, epic: str, store: EpicStore, team: LabelRepos, unblocking: tuple[str, ...], window: tmux.Window, poll: int, home: pathlib.Path, effects: Effects) -> None:
"""Waits in window for the human to close the human's task `task` of the epic called epic, and returns once it no longer holds up any issue. A read of the epic that fails is said once and tried again."""
tmux.park(window, AWAITS, effects.tmux)
told, said = False, None
@@ -47,7 +47,7 @@ def awaited(task: EpicIssue, epic: str, store: EpicStore, team: LabelRepos, wind
if issues.reason != said:
say(f"cannot read the epic, so cannot tell whether {task.key} is closed; trying again every {poll} seconds: {issues.reason}", effects, stdout=True)
said = issues.reason
elif not (held := holds_up(task.key, issues, team)):
elif not (held := holds_up(task.key, issues, team, unblocking)):
return
elif not told:
text = message(task, epic, held)
+47 -16
View File
@@ -27,6 +27,7 @@ from agent_cycle.verdicts import Finished, TakenIn
from atlassian.jira import ISSUE_KEY
from do_epic.backend.jira import JiraEpic
from claude_code.reply import Limited
from text_files.markdown_text import listed
from do_epic.repos import locate
from chunk_driver.this_loop import Loop
from chunk_driver.project.model_choice import Models, overridden
@@ -142,7 +143,7 @@ def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher:
def status_printed(epic: EpicRun) -> Stop:
"""What `do-epic <EPIC-KEY> --status` does: prints a line per open issue, and doesn't start anything."""
issues = epic.store.read()
lines = issues if isinstance(issues, Failure) else status.lines(epic.key, epic.paths.home, issues, epic.config.label_repos, epic.effects.tmux)
lines = issues if isinstance(issues, Failure) else status.lines(epic.key, epic.paths.home, issues, epic.config.label_repos, epic.config.unblocking, epic.effects.tmux)
return Stop(1, lines.reason) if isinstance(lines, Failure) else Stop(0, "\n".join(lines) or f"the epic {epic.key} has no open issue")
@@ -211,7 +212,7 @@ def scheduled_epic(epic: EpicRun) -> scheduler.Epic | Failure:
seen.append(found.checkout)
return real(found.checkout), found.config.parallel_chunks
return scheduler.Epic(epic.key, cap, located, epic.paths.home, epic.launcher, epic.env, epic.config.label_repos)
return scheduler.Epic(epic.key, cap, located, epic.paths.home, epic.launcher, epic.env, epic.config.label_repos, epic.config.unblocking)
@dataclasses.dataclass(frozen=True)
@@ -248,8 +249,8 @@ def chunk_run(key: str, epic: EpicRun) -> Stop:
if isinstance(issue, Stop):
return issue
if issue and isinstance(recorded(issue, epic.config.label_repos), HumanTask):
human_tasks.awaited(issue, epic.key, epic.store, epic.config.label_repos, tmux.Window(epic.session, key, pane), POLL_SECONDS, epic.paths.home, epic.effects)
return handed_on(key, epic)
human_tasks.awaited(issue, epic.key, epic.store, epic.config.label_repos, epic.config.unblocking, tmux.Window(epic.session, key, pane), POLL_SECONDS, epic.paths.home, epic.effects)
return handed_on(key, epic, humans=True)
place = chunk_root(key, issue, epic)
if isinstance(place, Stop):
return place
@@ -281,13 +282,13 @@ def chunk_run(key: str, epic: EpicRun) -> Stop:
news = parked_through(repo, loop, epic, told=news, finished=isinstance(concluded.verdict, Finished)) if repo is not None else ""
# A chunk that was parked has work again, whatever the judge ruled before its pull request passed the gate.
if isinstance(concluded.verdict, Finished) and news == "":
return handed_on(key, epic)
return handed_on(key, epic, repo is not None)
def parked_through(repo: str, loop: Loop, epic: EpicRun, told: str | None, finished: bool) -> str | Stop:
"""Keeps the chunk in loop's window parked. Its work is in the repo called repo. It stays parked for as long as its pull request waits on a gate, and returns once its worker has something to do: what to tell that worker, or empty where the chunk was never parked. told is the news its last cycle's worker got, None where the window just started, and finished says the judge ruled the chunk finished. A window that just started parks the chunk only if its file says so: the forge isn't read for a chunk that starts afresh.
Where a person merges, a worker ends its run with the pull request open, so the judge may rule the chunk finished before it is. For such a finished chunk, a gate that cannot be read is read again until it can, and a pull request no longer open, in a worktree that still stands, is news the worker hasn't been told: the worker removes the worktree.
Where a person merges, a worker ends its run with the pull request open, so the judge may rule the chunk finished before it is. For such a finished chunk, a gate that cannot be read is read again until it can, and a pull request no longer open, in a worktree that still stands, is news the worker hasn't been told: the worker removes the worktree. A pull request that doesn't merge into its base is news after every cycle that leaves it so: the worker levels the branch.
A chunk parks in three steps: its file is written, its window is shown as parked, and the epic's next chunks start in the slot it frees. It resumes in the reverse order: `scheduler.resume` gives it a running slot, then its file is removed. So a window that ends in between finds the chunk parked when it starts again.
"""
@@ -305,7 +306,11 @@ def parked_through(repo: str, loop: Loop, epic: EpicRun, told: str | None, finis
if not isinstance(entered, gates.Gate):
if isinstance(entered, Failure):
say(f"cannot tell whether the chunk's pull request waits on a gate, so the chunk isn't parked: {entered.reason}", epic.effects, stdout=True)
uncleaned = f"{chunk_prompt.DRIVER} keeps the chunk open while its worktree stands: {entered.news}." if finished and poll.by_human and isinstance(entered, gates.Unopened) else ""
if not (finished and poll.by_human and isinstance(entered, (gates.Unopened, gates.Unmergeable))):
return ""
if isinstance(entered, gates.Unmergeable):
return f"{chunk_prompt.DRIVER} keeps the chunk open while its pull request doesn't merge into its base: {entered.news}."
uncleaned = f"{chunk_prompt.DRIVER} keeps the chunk open while its worktree stands: {entered.news}."
return "" if uncleaned in (told or "") else uncleaned
if failed := poll.record(entered):
return Stop(1, failed.reason)
@@ -423,17 +428,23 @@ def folder_made(root: str) -> Failure | None:
return None
def handed_on(key: str, epic: EpicRun) -> Stop:
"""The stop of a do-epic whose chunk finished. It first moves the chunk's issue to done (the epic's finishing has none), and its split item too where that was the last of the item's sub-tasks, so that no finished chunk starts again and what they block may start, then starts each chunk that may start now. Its window closes as it exits."""
# The epic's finishing has no issue to move: the epic is closed by `--close-epic`.
moved = None if key == epic.key else epic.store.finish_issue(key)
if isinstance(moved, Failure):
return Stop(1, f"the chunk finished, but its issue could not move to done: {moved.reason}; once it is done in Jira, run `do-epic {epic.key}` to start the chunks it blocks")
issues = epic.store.read()
def handed_on(key: str, epic: EpicRun, in_repo: bool = False, humans: bool = False) -> Stop:
"""The stop of a do-epic whose chunk finished. It first moves the chunk's issue to done (the epic's finishing has none), and its split item too where that was the last of the item's sub-tasks, so that no finished chunk starts again and what they block may start, then starts each chunk that may start now. Where the team's automation moves issues, others move two kinds of issue. The automation moves the issue of a chunk in a repo, which in_repo marks, from its pull request: the stop waits for that move (`moved_by_automation`). The human moves their own task, which humans marks: the stop moves and awaits nothing. A chunk without a repo has no pull request, so its issue moves to done as ever, and so does a split item, once Jira counts each of its sub-tasks done. Its window closes as it exits."""
automated = epic.config.automation_moves
# The epic's finishing has no issue to move: the epic is closed by `--close-epic`. Nor has a human's task where the human moves it: its window waited until it holds up no issue.
if key == epic.key or (humans and automated):
issues: list[EpicIssue] | Failure = epic.store.read()
elif in_repo and automated:
issues = moved_by_automation(key, epic)
else:
moved = epic.store.finish_issue(key)
if isinstance(moved, Failure):
return Stop(1, f"the chunk finished, but its issue could not move to done: {moved.reason}; once it is done in Jira, run `do-epic {epic.key}` to start the chunks it blocks")
issues = epic.store.read()
# A search may not show the move yet, so the issue counts as done here whatever the read says.
issues = issues if isinstance(issues, Failure) else [dataclasses.replace(each, done=True) if each.key == key else each for each in issues]
if isinstance(issues, Failure):
return Stop(1, f"the chunk finished, but the next could not start: {issues.reason}")
# A search may not show the move yet, so the issue counts as done here whatever the read says.
issues = [dataclasses.replace(each, done=True) if each.key == key else each for each in issues]
closed = split_items_closed(epic, issues)
if isinstance(closed, Stop):
return closed
@@ -444,6 +455,26 @@ def handed_on(key: str, epic: EpicRun) -> Stop:
return Stop(0, "")
def moved_by_automation(key: str, epic: EpicRun) -> list[EpicIssue]:
"""The epic's issues once the issue called key no longer holds up another: read every POLL_SECONDS until the team's automation, or a person, has moved it. Until then a read would show it open, and its chunk would start again. A read that fails is made again."""
told, unread = False, ""
while True:
issues = epic.store.read()
if isinstance(issues, Failure):
if issues.reason != unread:
say(f"cannot read the epic, so cannot tell whether {key} has moved; trying again every {POLL_SECONDS} seconds: {issues.reason}", epic.effects, stdout=True)
unread = issues.reason
epic.effects.sleep(POLL_SECONDS)
continue
by_key = {each.key: each for each in issues}
if key not in by_key or scheduler.settled(by_key[key], by_key, epic.config.unblocking):
return issues
if not told:
say(f"{key} is {by_key[key].status}: it waits for the team's automation to move it to {listed(epic.config.unblocking, 'or')}; move it in Jira if the automation doesn't", epic.effects, stdout=True)
told = True
epic.effects.sleep(POLL_SECONDS)
def split_items_closed(epic: EpicRun, issues: list[EpicIssue]) -> list[EpicIssue] | Stop:
"""The issues, with each item split by repo whose sub-tasks are all done moved to done in the tracker and read as done; the stop where one cannot move. Its last sub-task to finish closes it, and one an earlier run left open closes with it."""
for item in issues:
+34 -14
View File
@@ -9,8 +9,9 @@ from do_epic.epic_record import CAP
from chunk_driver.claims import CHUNK_FLAG, epic_chunks, HANDED, loop_chunks, project_lock, starting
from do_epic.backend.protocol import EpicIssue
from failure import Failure
from do_epic.split import finished, is_split
from do_epic.split import finished, is_split, SPLIT_LABEL
from do_epic.repo_pick import HumanTask, LabelRepos, Pick, recorded, Repo
from text_files.markdown_text import listed
from project_config.settings import PARALLEL_CHUNKS
from do_epic.parked import parked_chunks
from chunk_pr.approval import PARKS
@@ -73,43 +74,59 @@ class Epic:
env: typing.Mapping[str, str]
# The team's own labels for its repos.
team: LabelRepos
# The statuses `jira-unblocking-statuses` names; `settled` says what they do.
unblocking: tuple[str, ...] = ()
@property
def folder(self) -> pathlib.Path:
return self.home / STATE / self.key
def open_blockers(issue: EpicIssue, by_key: dict[str, EpicIssue]) -> list[str]:
"""The keys of the issues that block issue, or its parent, that are not done. A blocker outside the epic counts, since its state is unknown."""
def unblocks(status: str, unblocking: tuple[str, ...]) -> bool:
"""Whether status is one of the unblocking statuses, whatever its case, so a name typed in another case than Jira shows still matches."""
return status.casefold() in {name.casefold() for name in unblocking}
def settled(issue: EpicIssue, by_key: dict[str, EpicIssue], unblocking: tuple[str, ...]) -> bool:
"""Whether the issue's work has landed, so that it takes no chunk and unblocks what it blocks: the tracker counts it done, or its status is one of unblocking, such as one the team's automation gives an issue whose pull request merged. An item marked SPLIT_LABEL has landed once each of its sub-tasks has, since nobody moves it before they are done."""
tasks = [task for task in by_key.values() if task.parent == issue.key] if SPLIT_LABEL in issue.labels else []
return issue.done or unblocks(issue.status, unblocking) or bool(tasks) and all(settled(task, by_key, unblocking) for task in tasks)
def open_blockers(issue: EpicIssue, by_key: dict[str, EpicIssue], unblocking: tuple[str, ...] = ()) -> list[str]:
"""The keys of the issues that block issue, or its parent, that are not settled. A blocker outside the epic counts, since its state is unknown."""
parent = by_key.get(issue.parent)
return [key for key in (*issue.blockers, *(parent.blockers if parent else ())) if key not in by_key or not by_key[key].done]
return [key for key in (*issue.blockers, *(parent.blockers if parent else ())) if key not in by_key or not settled(by_key[key], by_key, unblocking)]
def held_up(issues: list[EpicIssue]) -> dict[str, list[str]]:
def held_up(issues: list[EpicIssue], unblocking: tuple[str, ...] = ()) -> dict[str, list[str]]:
"""Each blocker's key, mapped to the keys of the open issues it holds up, in the tracker's rank order. A split item's blocker holds up the item's sub-tasks."""
by_key = {issue.key: issue for issue in issues}
held: dict[str, list[str]] = {}
for issue in issues:
if not issue.done and not is_split(issue, issues):
for key in open_blockers(issue, by_key):
if not settled(issue, by_key, unblocking) and not is_split(issue, issues):
for key in open_blockers(issue, by_key, unblocking):
held.setdefault(key, []).append(issue.key)
return held
def chunks(issues: list[EpicIssue], team: LabelRepos) -> tuple[list[Chunk], list[Waits]]:
"""The open issues to work as chunks, in the tracker's rank order, and those that wait. A split item is worked through its sub-tasks, and what blocks it blocks them."""
def chunks(issues: list[EpicIssue], team: LabelRepos, unblocking: tuple[str, ...] = ()) -> tuple[list[Chunk], list[Waits]]:
"""The open issues to work as chunks, in the tracker's rank order, and those that wait. A split item is worked through its sub-tasks, and what blocks it blocks them. An issue in one of the unblocking statuses is worked already: it waits until Jira counts it done."""
by_key = {issue.key: issue for issue in issues}
holding = held_up(issues)
holding = held_up(issues, unblocking)
found: list[Chunk] = []
waits: list[Waits] = []
for issue in issues:
if issue.done:
continue
if unblocks(issue.status, unblocking):
waits.append(Waits(issue.key, f"its work has landed: it is {issue.status}, and the epic's finishing waits until Jira counts it done"))
continue
if is_split(issue, issues):
if all(task.done for task in issues if task.parent == issue.key) and not finished(issues, issue.key):
waits.append(Waits(issue.key, "its sub-tasks are done; close it in Jira"))
continue
turn = turn_of(issue, recorded(issue, team), open_blockers(issue, by_key), by_key, issue.key in holding)
turn = turn_of(issue, recorded(issue, team), open_blockers(issue, by_key, unblocking), by_key, issue.key in holding, unblocking)
if isinstance(turn, Chunk):
found.append(turn)
else:
@@ -117,7 +134,7 @@ def chunks(issues: list[EpicIssue], team: LabelRepos) -> tuple[list[Chunk], list
return found, waits
def turn_of(issue: EpicIssue, pick: Pick | None | Failure, blocking: list[str], by_key: dict[str, EpicIssue], holds: bool) -> Chunk | Waits:
def turn_of(issue: EpicIssue, pick: Pick | None | Failure, blocking: list[str], by_key: dict[str, EpicIssue], holds: bool, unblocking: tuple[str, ...] = ()) -> Chunk | Waits:
"""The open issue's chunk, or why it waits. blocking are its open blockers, and holds says it holds up another open issue. A human's task gets a window only while it holds up another issue and nothing holds it up; that window waits for the human. A blocker outside the epic blocks until the human removes the link, since its state is unknown."""
if isinstance(pick, Failure):
return Waits(issue.key, pick.reason)
@@ -128,7 +145,10 @@ def turn_of(issue: EpicIssue, pick: Pick | None | Failure, blocking: list[str],
if blocking:
outside = [key for key in blocking if key not in by_key]
unseen = 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 ""
return Waits(issue.key, f"{' and '.join(blocking)} block{'s' if len(blocking) == 1 else ''} it{unseen}")
inside = [key for key in blocking if key in by_key]
whom = ("it is" if len(blocking) == 1 else "each is") if not outside else f"{' and '.join(inside)} {'is' if len(inside) == 1 else 'are'}"
until = f", until {whom} {listed((*unblocking, 'done'), 'or')}" if unblocking and inside else ""
return Waits(issue.key, f"{' and '.join(blocking)} block{'s' if len(blocking) == 1 else ''} it{until}{unseen}")
return Chunk(issue.key, pick.name if isinstance(pick, Repo) else None)
@@ -144,7 +164,7 @@ def refusal(repo: str, room: RepoRoom) -> str | None:
def start_chunks(epic: Epic, issues: list[EpicIssue], finishing: bool, own: str | None, run: tmux.Tmux) -> Started | Failure:
"""Starts a do-epic in a new window for each of the epic's chunks that may start now. Where finishing is set, no issue is open, and the one chunk to start is the epic's finishing (finish.py), in a window named for the epic's key. own is the key of the chunk that asks, which has finished or parked: 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 parked chunk waits in its window; one without a live window, as after a reboot, starts again as a stopped chunk does, whatever the limits, since it goes on parked. 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, epic.team)
found, waits = chunks(issues, epic.team, epic.unblocking)
if finishing:
found.append(Chunk(epic.key, None))
started: list[str] = []
+2 -2
View File
@@ -18,9 +18,9 @@ def since(folder: pathlib.Path, chunk: Parked) -> str:
return ""
def lines(key: str, home: pathlib.Path, issues: list[EpicIssue], team: LabelRepos, run: tmux.Tmux) -> list[str] | Failure:
def lines(key: str, home: pathlib.Path, issues: list[EpicIssue], team: LabelRepos, unblocking: tuple[str, ...], run: tmux.Tmux) -> list[str] | Failure:
"""A line per open issue of the epic called key, in the tracker's rank order: that its chunk runs or asks the human, or why it waits. It doesn't start anything or check any limit, so the line of a chunk that has yet to start doesn't say which limit holds it back."""
found, waits = chunks(issues, team)
found, waits = chunks(issues, team, unblocking)
folder = home / STATE / key
parked = parked_chunks(folder)
if isinstance(parked, Failure):
+21
View File
@@ -78,6 +78,27 @@ class ConfigTest(unittest.TestCase):
self.write(SETTINGS + 'jira-finish-status = " "\n')
self.assertIn('`jira-finish-status` is \' \', not the name Jira shows, such as "Done"; `jira-finish-status` is set, so `jira-finish-transition` must be too', self.failure())
def test_reads_the_unblocking_statuses_and_that_the_teams_automation_moves_issues(self) -> None:
self.write(SETTINGS)
found = load(self.home)
assert isinstance(found, DoEpicConfig), found
self.assertEqual((found.unblocking, found.automation_moves), ((), False))
self.write(SETTINGS + 'jira-unblocking-statuses = ["Release Ready", "Done"]\njira-automation-moves-issues = true\n')
found = load(self.home)
assert isinstance(found, DoEpicConfig), found
self.assertEqual((found.unblocking, found.automation_moves), (("Release Ready", "Done"), True))
def test_refuses_unblocking_statuses_that_are_no_list_of_names_and_a_switch_that_is_no_boolean(self) -> None:
for value in ('"Done"', '["Done", " "]', "[]", "[1]"):
with self.subTest(value=value):
self.write(SETTINGS + f"jira-unblocking-statuses = {value}\n")
self.assertIn('`jira-unblocking-statuses` is ', self.failure())
self.assertIn(', not a list of the status names Jira shows, such as ["Release Ready"]', self.failure())
self.write(SETTINGS + "jira-automation-moves-issues = true\n")
self.assertIn("`jira-automation-moves-issues` is set, so `jira-unblocking-statuses` must name the status the automation gives an issue whose pull request merged", self.failure())
self.write(SETTINGS + 'jira-automation-moves-issues = "yes"\n')
self.assertIn("`jira-automation-moves-issues` is 'yes', not true or false", self.failure())
def test_refuses_while_the_config_is_missing(self) -> None:
self.write(None)
self.assertIn(f"cannot read {self.folder / 'config.toml'}", self.failure())
+1
View File
@@ -27,6 +27,7 @@ class WhenTheFinishingIsDue(DoEpicTest):
self.assertIs(finish.due([]), False)
self.assertIs(finish.due([issue("ABC-20", done=True), issue("ABC-21")]), False)
self.assertIs(finish.due([issue("ABC-20", done=True), issue("ABC-21", done=True)]), True)
self.assertIs(finish.due([issue("ABC-20", done=True), issue("ABC-21", status="Release Ready")]), False)
def test_an_item_split_by_repo_is_done_once_its_sub_tasks_are(self) -> None:
split = [issue("ABC-20", "split-by-repo"), issue("ABC-40", "repo:api", done=True, parent="ABC-20")]
+24 -4
View File
@@ -5,7 +5,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.gates import APPROVAL, CHECKS, gate, Gate, MERGE, NEW_REVIEW, Open, Unopened
from do_epic.gates import APPROVAL, CHECKS, gate, Gate, MERGE, NEW_REVIEW, Open, Unmergeable, Unopened
from failure import Failure
WORKTREES = "worktree /code/billing\nHEAD aaa\nbranch refs/heads/main\n\nworktree /code/billing-ABC-21\nHEAD abc\nbranch refs/heads/ABC-21\n"
@@ -28,7 +28,7 @@ def comment(by: str, at: str) -> dict:
class Forge:
"""Stands in for git and the forge's CLI in the checkout and the chunk's worktree; `ran` holds each folder a command ran in. Only the CLI of origin's forge answers: `gh` fails on a Gitea origin, and `tea` on a GitHub one."""
def __init__(self, origin: str = "git@github.com:o/billing.git", pulls: str = f"7\t{HEAD}\tfalse\n", draft: bool = False, decision: str = "REVIEW_REQUIRED", buckets: tuple[str, ...] = ("pass",), threads: tuple[dict, ...] = (), status: str = '{"state": "success", "total_count": 1}', worktrees: str = WORKTREES, fails: str = "", reviews: tuple[dict, ...] = (), comments: tuple[dict, ...] = (), title: str = "Add x") -> None:
def __init__(self, origin: str = "git@github.com:o/billing.git", pulls: str = f"7\t{HEAD}\tfalse\n", draft: bool = False, decision: str = "REVIEW_REQUIRED", buckets: tuple[str, ...] = ("pass",), threads: tuple[dict, ...] = (), status: str = '{"state": "success", "total_count": 1}', mergeable: str = "MERGEABLE", merge_state: str = "CLEAN", worktrees: str = WORKTREES, fails: str = "", reviews: tuple[dict, ...] = (), comments: tuple[dict, ...] = (), title: str = "Add x") -> None:
self.cli = "gh" if "github.com" in origin else "tea"
self.ran: list[str] = []
self.commands: list[list[str]] = []
@@ -39,11 +39,11 @@ class Forge:
"git rev-parse": HEAD + "\n",
"git symbolic-ref": "origin/main\n",
"gh pr list": pulls,
"gh pr view": json.dumps({"isDraft": draft, "reviewDecision": decision, "author": {"login": "worker"}, "reviews": list(reviews), "comments": list(comments)}),
"gh pr view": json.dumps({"isDraft": draft, "reviewDecision": decision, "author": {"login": "worker"}, "reviews": list(reviews), "comments": list(comments), "mergeable": mergeable, "mergeStateStatus": merge_state}),
"gh pr checks": json.dumps([{"bucket": bucket} for bucket in buckets]),
"gh api graphql": json.dumps({"data": {"repository": {"pullRequest": {"author": {"login": "worker"}, "reviewThreads": {"nodes": list(threads)}}}}}),
"tea api repos/{owner}/{repo}/pulls?state=open&limit=50": json.dumps([{"number": 7, "merged": False, "head": {"label": "ABC-21", "sha": HEAD, "repo": {"full_name": "o/billing"}}, "base": {"repo": {"full_name": "o/billing"}}}]),
"tea api repos/{owner}/{repo}/pulls/7": json.dumps({"number": 7, "title": title}),
"tea api repos/{owner}/{repo}/pulls/7": json.dumps({"number": 7, "title": title, "mergeable": mergeable == "MERGEABLE"}),
"tea api repos/{owner}/{repo}/branches/main": '{"name": "main"}',
"tea api repos/{owner}/{repo}/commits/" + HEAD + "/status": status,
}
@@ -79,6 +79,26 @@ class GateOfAChunk(unittest.TestCase):
self.assertEqual(forge.gate(by_human=True), Gate("/code/billing-ABC-21", "7", MERGE))
self.assertEqual(Forge(decision="APPROVED").gate(by_human=False), Open("pull request #7 passed its checks and is approved"))
def test_where_a_person_merges_a_pull_request_that_no_longer_merges_into_its_base_is_news_to_level_it(self):
gitea = "https://gitea.larvit.se/o/billing.git"
again = "run chunk-pr merge again to level the branch"
self.assertEqual(Forge(decision="APPROVED", mergeable="CONFLICTING", merge_state="DIRTY").gate(by_human=True), Unmergeable(f"pull request #7 conflicts with its base branch; {again}"))
self.assertEqual(Forge(gitea, mergeable="CONFLICTING").gate(by_human=True), Unmergeable(f"pull request #7 conflicts with its base branch; {again}"))
self.assertEqual(Forge(decision="", merge_state="BEHIND").gate(by_human=True), Unmergeable(f"pull request #7 is behind its base branch, whose protection requires it up to date; {again}"))
def test_where_a_person_merges_a_pull_request_awaits_that_merge_while_github_computes_whether_it_merges(self):
self.assertEqual(Forge(decision="APPROVED", mergeable="UNKNOWN", merge_state="UNKNOWN").gate(by_human=True), Gate("/code/billing-ABC-21", "7", MERGE))
def test_where_a_person_merges_a_mergeability_that_cannot_be_read_is_a_failure(self):
forge = Forge("https://gitea.larvit.se/o/billing.git")
forge.answers["tea api repos/{owner}/{repo}/pulls/7"] = '{"number": 7, "title": "Add x"}'
self.assertEqual(forge.gate(by_human=True), Failure("tea api answered pull request 7 in a shape that can't be read: {'number': 7, 'title': 'Add x'}"))
def test_where_the_chunk_merges_nobody_reads_whether_the_pull_request_merges(self):
forge = Forge(decision="APPROVED", mergeable="CONFLICTING")
self.assertEqual(forge.gate(), Open("pull request #7 passed its checks and is approved"))
self.assertNotIn(["gh", "pr", "view", "7", "--json", "mergeable,mergeStateStatus"], forge.commands)
def test_where_a_person_merges_every_other_gate_and_all_news_stay_as_they_are(self):
same = (Forge(), Forge(buckets=("pending",)), Forge(draft=True), Forge(decision="CHANGES_REQUESTED"), Forge(threads=(thread(False, "reviewer"),)), Forge(buckets=("fail",)), Forge(pulls=""))
for forge in same:
+32
View File
@@ -11,6 +11,7 @@ from do_epic.test_main import DESCRIPTION, Description, DoEpicTest, MODELS, UNRE
from do_epic.epic_record import EpicRecord
from failure import Failure
from loop_effects.doubles import FakeEffects
from do_epic.human_tasks import holds_up
from do_epic.scheduler import HUMAN_WAIT
from do_epic.test_scheduler import issue
from do_epic.backend.fake import MemoryEpic
@@ -49,6 +50,37 @@ class AHumanTaskThatBlocksAnIssue(DoEpicTest):
self.slept = slept
return self.run_main(["--chunk", "ABC-19", "ABC-12"], fake, MODELS)
def moved_to_an_unblocking_status(self, switch: str, frees: tuple[str, dict[str, object]] = ("ABC-19", {"status": "Release Ready"}), starts: str = "ABC-21") -> bool:
"""Whether Jira counts the task done after its window's run, where the config ends with switch. frees is the change in Jira that ends the wait: by default the human moves the task to an unblocking status. starts is what the window then starts."""
with (self.home / ".claude-projects" / "do-epic" / "config.toml").open("a") as config:
config.write('jira-unblocking-statuses = ["Release Ready"]\n' + switch)
fake = FakeEffects(git=UNREAD, windows=WINDOW)
slept: list[int] = []
def sleep(seconds: int) -> None:
slept.append(seconds)
self.assertLess(len(slept), 5, "the window still waits")
if len(slept) == 2:
self.epic.change(frees[0], **frees[1])
fake.effects = lambda made=fake.effects(): dataclasses.replace(made, sleep=sleep) # type: ignore[method-assign]
code, out, err = self.run_main(["--chunk", "ABC-19", "ABC-12"], fake, MODELS)
self.assertEqual((code, err, slept), (0, "", [60, 60]))
self.assertIn(f"the chunk finished; started {starts}\n", out)
return next(each.done for each in self.epic.issues if each.key == "ABC-19")
def test_a_task_the_human_moves_to_an_unblocking_status_no_longer_holds_up_an_issue_and_moves_to_done(self) -> None:
self.assertTrue(self.moved_to_an_unblocking_status(""))
def test_where_the_teams_automation_moves_issues_the_humans_task_stays_where_the_human_moved_it(self) -> None:
self.assertFalse(self.moved_to_an_unblocking_status("jira-automation-moves-issues = true\n"))
def test_where_the_teams_automation_moves_issues_a_task_that_blocks_no_open_issue_any_more_ends_its_window_unmoved(self) -> None:
self.assertFalse(self.moved_to_an_unblocking_status("jira-automation-moves-issues = true\n", ("ABC-21", {"done": True}), starts="no other"))
def test_a_task_holds_up_only_the_issues_no_unblocking_status_settles(self) -> None:
issues = [issue("ABC-19", "do-epic-human"), issue("ABC-20", "do-epic-claude", blockers=("ABC-19",), status="Release Ready"), issue("ABC-21", "do-epic-claude", blockers=("ABC-19",))]
self.assertEqual(holds_up("ABC-19", issues, {}, ("Release Ready",)), ["ABC-21"])
def test_dms_the_human_once_parks_its_window_and_polls_until_the_issue_closes_then_starts_the_next(self) -> None:
fake = FakeEffects(git=UNREAD, windows=WINDOW)
code, out, err = self.awaited(fake, closes_after=3)
+47
View File
@@ -449,6 +449,18 @@ class AChunksRun(DoEpicTest):
self.assertEqual(code, 0, err)
self.assertIn("the chunk finished; started ABC-22\n", out)
def test_where_the_teams_automation_moves_issues_a_finished_chunk_without_a_repo_still_moves_its_own(self) -> None:
(self.home / ".claude-projects" / "do-epic" / "config.toml").write_text(SETTINGS + 'jira-unblocking-statuses = ["Release Ready"]\njira-automation-moves-issues = true\n', encoding="utf-8")
parent = issue("ABC-23", "split-by-repo")
store = MemoryEpic("ABC-12", [self.issues[0], parent, issue("ABC-21", "do-epic-claude", parent="ABC-23"), issue("ABC-22", "do-epic-claude", blockers=("ABC-23",))])
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, 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)
# No pull request carries ABC-21, so do-epic moves it; its split item, then all done, closes as ever.
self.assertEqual({each.key: each.done for each in store.issues}, {"ABC-20": False, "ABC-23": True, "ABC-21": True, "ABC-22": False})
self.assertIn("the chunk finished; started ABC-22\n", out)
def test_the_last_sub_task_of_a_split_item_to_finish_moves_the_item_to_done_and_starts_what_it_blocks(self) -> None:
parent = issue("ABC-21", "split-by-repo")
tasks = [issue("ABC-23", "do-epic-claude", parent="ABC-21"), issue("ABC-24", "do-epic-claude", parent="ABC-21", done=True)]
@@ -746,6 +758,20 @@ class AChunkWhosePullRequestWaitsOnAGate(DoEpicTest):
self.assertIn(fact, prompts[1].split("\n\n")[0])
self.assertNotIn("parked: ", out)
def test_where_a_person_merges_a_finished_chunk_whose_pull_request_no_longer_merges_is_told_until_it_does(self) -> None:
self.repo_config.write_text(self.repo_config.read_text(encoding="utf-8") + 'merge = "human"\n', encoding="utf-8")
for unmergeable, why in (({"mergeable": "CONFLICTING"}, "conflicts with its base branch"), ({"merge_state": "BEHIND"}, "is behind its base branch")):
with self.subTest(why=why):
self.forges = [awaiting(decision="APPROVED", **unmergeable), awaiting(decision="APPROVED", **unmergeable), CLEANED]
self.gate_reads = 0
fake = FakeEffects(streams=[self.worker(), self.worker(), self.worker()], claude=[judged("finished"), judged("finished"), judged("finished")], git=UNREAD, windows=PARKED_WINDOW)
code, out, err, prompts = self.parked_run(fake)
self.assertEqual((code, len(prompts)), (0, 3), err)
for prompt in prompts[1:]:
for fact in ("keeps the chunk open while its pull request doesn't merge into its base", f"pull request #7 {why}", "run chunk-pr merge again"):
self.assertIn(fact, prompt.split("\n\n")[0])
self.assertNotIn("parked: ", out)
def test_where_a_person_merges_an_unfinished_chunk_goes_on_without_news_or_a_wait(self) -> None:
self.repo_config.write_text(self.repo_config.read_text(encoding="utf-8") + 'merge = "human"\n', encoding="utf-8")
self.forges = [awaiting(pulls=""), awaiting(decision="APPROVED", fails="gh pr checks"), CLEANED]
@@ -763,6 +789,27 @@ class AChunkWhosePullRequestWaitsOnAGate(DoEpicTest):
code, _, err, prompts = self.parked_run(fake)
self.assertEqual((code, len(prompts)), (0, 1), err)
def test_where_the_teams_automation_moves_issues_a_finished_chunk_in_a_repo_moves_none_and_waits_for_the_move(self) -> None:
(self.home / ".claude-projects" / "do-epic" / "config.toml").write_text(SETTINGS + 'jira-unblocking-statuses = ["Release Ready", "Shipped"]\njira-automation-moves-issues = true\n', encoding="utf-8")
store = MemoryEpic("ABC-12", [*self.issues[:-1], issue("ABC-22", "do-epic-claude", blockers=("ABC-20",))])
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
self.forges = [awaiting(pulls="")]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD, windows=PARKED_WINDOW)
slept: list[float] = []
def sleep(seconds: float) -> None:
slept.append(seconds)
store.fails = "Jira answered 503" if len(slept) in (1, 2) else None
if len(slept) == 4:
store.change("ABC-20", status="Release Ready")
fake.effects = lambda made=fake.effects(): dataclasses.replace(made, sleep=sleep) # type: ignore[method-assign]
code, out, err, _ = self.parked_run(fake)
self.assertEqual((code, slept), (0, [60, 60, 60, 60]), err)
self.assertEqual(out.count("cannot read the epic, so cannot tell whether ABC-20 has moved; trying again every 60 seconds: Jira answered 503\n"), 1, out)
self.assertEqual([(each.status, each.done) for each in store.issues if each.key == "ABC-20"], [("Release Ready", False)])
self.assertEqual(out.count("ABC-20 is To Do: it waits for the team's automation to move it to Release Ready or Shipped; move it in Jira if the automation doesn't\n"), 1, out)
self.assertIn("the chunk finished; started ABC-22\n", out)
def test_where_the_chunk_merges_an_approved_pull_request_parks_no_chunk(self) -> None:
self.forges = [awaiting(decision="APPROVED")]
fake = FakeEffects(streams=[self.worker()], claude=[judged("finished")], git=UNREAD, windows=PARKED_WINDOW)
+36 -3
View File
@@ -7,7 +7,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.scheduler import Chunk, chunks, Epic, HUMAN_WAIT, refusal, RepoRoom, resume, start_chunks, Started, Waits
from do_epic.scheduler import Chunk, chunks, Epic, held_up, HUMAN_WAIT, refusal, RepoRoom, resume, start_chunks, Started, Waits
from chunk_driver.claims import CHUNK_FLAG
from do_epic import chunk_prompt
from do_epic.backend.protocol import EpicIssue
@@ -21,8 +21,8 @@ from project_config import settings
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)
def issue(key: str, *labels: str, done: bool = False, blockers: tuple[str, ...] = (), parent: str = "ABC-12", status: str | None = None) -> EpicIssue:
return EpicIssue(key, f"Do {key}", "", tuple(sorted(labels)), None, status or ("Done" if done else "To Do"), done, parent, blockers=blockers)
class TheCapLine(unittest.TestCase):
@@ -120,6 +120,39 @@ class WhichIssuesAreChunks(unittest.TestCase):
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")]))
def test_an_issue_in_an_unblocking_status_unblocks_what_it_blocks_and_waits_to_be_done_itself(self) -> None:
issues = [issue("ABC-19", "repo:api", status="Release Ready"), issue("ABC-20", "repo:api", blockers=("ABC-19",)), issue("ABC-21", "repo:api", status="Code Review"), issue("ABC-22", "repo:api", blockers=("ABC-21",)), issue("ABC-23", "repo:api", done=True), issue("ABC-24", "repo:api", blockers=("ABC-23", "ABC-21", "ABC-22"))]
self.assertEqual(chunks(issues, {}, ("Release Ready", "Shipped")), ([Chunk("ABC-20", "api"), Chunk("ABC-21", "api")], [
Waits("ABC-19", "its work has landed: it is Release Ready, and the epic's finishing waits until Jira counts it done"),
Waits("ABC-22", "ABC-21 blocks it, until it is Release Ready, Shipped or done"),
Waits("ABC-24", "ABC-21 and ABC-22 block it, until each is Release Ready, Shipped or done"),
]))
self.assertEqual(chunks(issues[:2], {}), ([Chunk("ABC-19", "api")], [Waits("ABC-20", "ABC-19 blocks it")]))
self.assertEqual(held_up(issues, ("Release Ready", "Shipped")), {"ABC-21": ["ABC-22", "ABC-24"], "ABC-22": ["ABC-24"]})
def test_a_humans_task_gets_no_window_for_an_issue_it_blocks_that_is_in_an_unblocking_status(self) -> None:
issues = [issue("ABC-19", "do-epic-human"), issue("ABC-20", "repo:api", blockers=("ABC-19",), status="Release Ready")]
self.assertEqual(chunks(issues, {}, ("Release Ready",))[0], [])
def test_an_unblocking_status_matches_whatever_its_case(self) -> None:
issues = [issue("ABC-19", "repo:api", status="Release Ready"), issue("ABC-20", "repo:api", blockers=("ABC-19",))]
self.assertEqual(chunks(issues, {}, ("release ready",)), ([Chunk("ABC-20", "api")], [Waits("ABC-19", "its work has landed: it is Release Ready, and the epic's finishing waits until Jira counts it done")]))
def test_names_an_unblocking_status_only_for_a_blocker_inside_the_epic(self) -> None:
unseen = "outside the epic, finish: remove such a link in Jira once its issue is done"
issues = [issue("ABC-19", "repo:api"), issue("ABC-20", "repo:api", blockers=("XYZ-1",)), issue("ABC-21", "repo:api", blockers=("ABC-19", "XYZ-1")), issue("ABC-22", "repo:api", blockers=("ABC-19", "ABC-20", "XYZ-1"))]
self.assertEqual(chunks(issues, {}, ("Release Ready",))[1], [
Waits("ABC-20", f"XYZ-1 blocks it; do-epic cannot see XYZ-1, {unseen}"),
Waits("ABC-21", f"ABC-19 and XYZ-1 block it, until ABC-19 is Release Ready or done; do-epic cannot see XYZ-1, {unseen}"),
Waits("ABC-22", f"ABC-19 and ABC-20 and XYZ-1 block it, until ABC-19 and ABC-20 are Release Ready or done; do-epic cannot see XYZ-1, {unseen}"),
])
def test_a_split_item_unblocks_what_it_blocks_once_each_sub_task_is_in_an_unblocking_status(self) -> None:
issues = [issue("ABC-20", "split-by-repo"), issue("ABC-23", "repo:api", parent="ABC-20", status="Release Ready"), issue("ABC-24", "repo:web", parent="ABC-20", done=True), issue("ABC-21", "repo:api", blockers=("ABC-20",))]
self.assertEqual(chunks(issues, {}, ("Release Ready",))[0], [Chunk("ABC-21", "api")])
self.assertEqual(chunks(issues, {})[0], [Chunk("ABC-23", "api")])
self.assertEqual(chunks([*issues[:2], issue("ABC-24", "repo:web", parent="ABC-20"), issues[3]], {}, ("Release Ready",))[0], [Chunk("ABC-24", "web")])
class RoomInARepo(unittest.TestCase):
def test_a_repo_with_room_and_no_loop_claude_takes_a_chunk(self) -> None:
+10 -2
View File
@@ -23,13 +23,21 @@ class TheStatusLines(unittest.TestCase):
parked.park(self.folder, parked.Parked(key, f"/code/api-{key}", "7", "s", on))
os.utime(parked.file_of(self.folder, key), (SINCE, SINCE))
def lines(self, issues: list, *windows: tuple[str, str, bool, str]) -> list[str] | Failure:
return status.lines("ABC-12", self.home, issues, {}, Tmux(*windows))
def lines(self, issues: list, *windows: tuple[str, str, bool, str], unblocking: tuple[str, ...] = ()) -> list[str] | Failure:
return status.lines("ABC-12", self.home, issues, {}, unblocking, Tmux(*windows))
def test_a_chunk_that_asks_says_where_to_answer_and_one_that_works_runs(self) -> None:
found = self.lines([issue("ABC-20", "repo:api"), issue("ABC-21", "repo:api")], (EPIC, "ABC-20 ?", False, ""), (EPIC, "ABC-21", False, ""))
self.assertEqual(found, ["ABC-20 asks you: answer its question in the tmux window epic-ABC-12:ABC-20", "ABC-21 runs"])
def test_names_the_status_a_blocker_must_reach_and_the_one_a_merged_issue_is_in(self) -> None:
found = self.lines([issue("ABC-20", "repo:api", status="Release Ready"), issue("ABC-21", "repo:api", status="Code Review"), issue("ABC-22", "repo:api", blockers=("ABC-21",))], (EPIC, "ABC-21", False, ""), unblocking=("Release Ready",))
self.assertEqual(found, [
"ABC-20 waits: its work has landed: it is Release Ready, and the epic's finishing waits until Jira counts it done",
"ABC-21 runs",
"ABC-22 waits: ABC-21 blocks it, until it is Release Ready or done",
])
def test_a_parked_chunk_says_what_it_awaits_and_since_when(self) -> None:
self.park("ABC-20", "an approval")
self.assertEqual(self.lines([issue("ABC-20", "repo:api")], (EPIC, "ABC-20 awaits its checks", False, "")), [f"ABC-20 waits: it is parked: its pull request #7 awaits its checks, since {SINCE_ON}"])
+29 -1
View File
@@ -1,4 +1,4 @@
"""Finding a pull request from origin's own branch, and waiting for the checks on its head commit."""
"""Finding a pull request from origin's own branch, reading whether it merges into its base, and waiting for the checks on its head commit."""
import dataclasses
import fnmatch
import json
@@ -75,6 +75,34 @@ def ready_pulls(forge: Forge, run: Run) -> list[ReadyPull] | Failure:
return [pull for pull in found if pull.number.isascii() and pull.number.isdigit() and isinstance(pull.head, str) and re.fullmatch(r"[0-9a-f]{40,64}", pull.head)]
# Why a pull request doesn't merge into its base as it stands, as the words after "pull request #<N>".
CONFLICTS = "conflicts with its base branch"
BEHIND = "is behind its base branch, whose protection requires it up to date"
def unmergeable(forge: Forge, number: str, run: Run) -> str | None | Failure:
"""Why pull request number doesn't merge into its base as it stands: CONFLICTS or BEHIND. None where it merges, and while GitHub still computes whether it does.
GitHub reports a pull request as behind only where the base's protection requires an up-to-date branch. Gitea's `mergeable` never tells that case. Gitea also answers false for the seconds it checks for conflicts after a push to either branch, which reads as CONFLICTS here.
"""
if forge == "gh":
viewed = run(["gh", "pr", "view", number, "--json", "mergeable,mergeStateStatus"])
if isinstance(viewed, Failure):
return viewed
try:
state = json.loads(viewed)
return CONFLICTS if state["mergeable"] == "CONFLICTING" else BEHIND if state["mergeStateStatus"] == "BEHIND" else None
except (ValueError, KeyError, TypeError):
return Failure(f"gh pr view printed no mergeability: {viewed.strip()[:200]}")
pull = gitea(run, f"repos/{{owner}}/{{repo}}/pulls/{number}")
if isinstance(pull, Failure):
return pull
try:
return CONFLICTS if pull["mergeable"] is False else None
except (KeyError, TypeError):
return Failure(f"tea api answered pull request {number} in a shape that can't be read: {str(pull)[:200]}")
def required_checks(forge: Forge, base: str, run: Run) -> set[str] | Failure:
"""The checks, or glob patterns of checks, that the forge's protection of the branch base requires before a merge. None on GitHub, where gh's watch covers them.
+37 -1
View File
@@ -9,7 +9,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from forge.pulls import CheckFailed, checks_now, checks_passed, open_pull, Pending, POLL_SECONDS, ready_pulls, ReadyPull, required_checks, WAIT_SECONDS
from forge.pulls import BEHIND, CheckFailed, checks_now, checks_passed, CONFLICTS, open_pull, Pending, POLL_SECONDS, ready_pulls, ReadyPull, required_checks, unmergeable, WAIT_SECONDS
from failure import Failure
from forge.commands import forge_of, gitea, runner, url_beside
@@ -50,6 +50,42 @@ class OpenPull(unittest.TestCase):
self.assertEqual(open_pull("tea", "item-3", "abc", lambda command: LONG).reason, f"tea api listed pull requests in a shape that can't be read: {LONG[:200]}")
class Unmergeable(unittest.TestCase):
def gh(self, mergeable: str, state: str) -> str | None | Failure:
commands: list[list[str]] = []
answer = unmergeable("gh", "7", lambda command: commands.append(command) or f'{{"mergeable": "{mergeable}", "mergeStateStatus": "{state}"}}')
self.assertEqual(commands, [["gh", "pr", "view", "7", "--json", "mergeable,mergeStateStatus"]])
return answer
def test_a_github_pull_request_that_conflicts_with_its_base_says_so(self):
self.assertEqual(self.gh("CONFLICTING", "DIRTY"), CONFLICTS)
def test_a_github_pull_request_behind_a_base_that_requires_it_up_to_date_says_so(self):
self.assertEqual(self.gh("MERGEABLE", "BEHIND"), BEHIND)
def test_a_github_pull_request_merges_whatever_else_holds_it_and_while_github_computes(self):
for mergeable, state in (("MERGEABLE", "CLEAN"), ("MERGEABLE", "BLOCKED"), ("MERGEABLE", "UNSTABLE"), ("UNKNOWN", "UNKNOWN")):
with self.subTest(mergeable=mergeable, state=state):
self.assertIsNone(self.gh(mergeable, state))
def test_a_gitea_pull_request_conflicts_only_where_gitea_says_it_is_not_mergeable(self):
commands: list[list[str]] = []
self.assertEqual(unmergeable("tea", "7", lambda command: commands.append(command) or '{"number": 7, "mergeable": false}'), CONFLICTS)
self.assertEqual(commands, [["tea", "api", "repos/{owner}/{repo}/pulls/7"]])
self.assertIsNone(unmergeable("tea", "7", lambda command: '{"number": 7, "mergeable": true}'))
def test_fails_where_the_forge_cannot_be_read_or_answers_in_another_shape(self):
unread = Failure("no network")
for forge in ("gh", "tea"):
with self.subTest(forge=forge):
self.assertIs(unmergeable(forge, "7", lambda command: unread), unread)
self.assertEqual(unmergeable("gh", "7", lambda command: LONG).reason, f"gh pr view printed no mergeability: {LONG[:200]}")
self.assertEqual(unmergeable("gh", "7", lambda command: "not json").reason, "gh pr view printed no mergeability: not json")
self.assertEqual(unmergeable("gh", "7", lambda command: '{"mergeable": "MERGEABLE"}').reason, 'gh pr view printed no mergeability: {"mergeable": "MERGEABLE"}')
self.assertEqual(unmergeable("tea", "7", lambda command: LONG).reason, f"tea api answered pull request 7 in a shape that can't be read: {LONG[:200]}")
self.assertEqual(unmergeable("tea", "7", lambda command: '{"number": 7}').reason, "tea api answered pull request 7 in a shape that can't be read: {'number': 7}")
def tea(statuses: typing.Iterable[str], branch: str = '{"name": "main"}') -> typing.Callable[[list[str]], str]:
"""A tea answering each read of the head's status with the next of statuses, and of branch main with branch."""
answers = iter(statuses)
+1 -1
View File
@@ -9,7 +9,7 @@ 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."""
"""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 task is quotable as the evidence, and 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}")
heading = transcript_heading(LOOP_CLAUDE)
task, found_heading, shown = after_task.partition(heading)
+8
View File
@@ -403,6 +403,14 @@ class JudgeArchivedRuns(unittest.TestCase):
self.assertIsInstance(self.judged(evidence="Do it.")[0], Unfinished)
self.assertIsInstance(self.judged(evidence="Do it. ... Use Postgres.")[0], Unfinished)
def test_splits_the_prompt_into_the_premises_the_task_and_the_transcript_at_the_first_heading_of_each(self):
heading = transcript_heading(LOOP_CLAUDE)
again = self.PROMPT.replace("Worker chose option B.", f"Worker chose option B. {heading}Again.", 1)
for prompt in (self.PROMPT, again):
grounds = grounds_of(prompt, self.ENTRIES)
self.assertEqual((grounds.quotable, grounds.task), ("HEAD: Ship fast.", "Do it."))
self.assertEqual(grounds_of(self.PROMPT, self.ENTRIES).shown, "Worker chose option B.\n[human] Use Postgres.")
def test_keeps_the_cost_and_the_run_of_a_rejected_reply(self):
rejected, _ = self.judged(evidence="Never said.")
self.assertEqual((rejected.cost, rejected.run.prompt), (0.25, self.PROMPT))
+3 -2
View File
@@ -91,8 +91,9 @@ prepare-scoring sets up a scoring run in the chunk's review folder: a detached w
checkout's HEAD, which the seats read, and one prompt file per seat beside it, as
skills/comprehension-panel/seat-prompts.md builds them. It prints the worktree's path and each
prompt's. It takes {{language}}, {{kind}}, {{domain}}, {{domain docs}} and {{3am question}} from the
checkout's AGENTS.md → "Scoring run". claude-config keeps no AGENTS.md, so there it takes them from
seat-prompts.md → "claude-config's values". It fills the other placeholders from the worktree and
project's working-rules file → "Scoring run", which is the checkout's AGENTS.md unless the config
names another. Where that file holds no such section, as in claude-config, it takes them from the
checkout's seat-prompts.md → "claude-config's values". It fills the other placeholders from the worktree and
the panel's SKILL.md. Where any one of the five values is missing, it exits 1 and doesn't write
anything. Where a setup that record-scoring never removed is still there, it removes it first and
says so.
+9 -4
View File
@@ -61,9 +61,12 @@ def score_bullets(skill: str) -> tuple[list[str], list[str]] | Failure:
return anchors, [line.replace("**", "") for _, line in dimensions]
VALUES_HEADING = r"(\d+\.\s+)?Scoring run|.+'s values"
def project_values(text: str, source: str) -> dict[str, str] | Failure:
"""Each value seat-prompts.md fills from the project, from the section of text, read from source, headed `Scoring run` or `<name>'s values`."""
lines = section(text, r"(\d+\.\s+)?Scoring run|.+'s values")
lines = section(text, VALUES_HEADING)
if lines is None:
return Failure(f"{source} has no \"Scoring run\" section to fill the seats' prompts from; add one with {listed([f'{{{name}}}' for name in VALUE_NAMES], 'and')}")
values = {}
@@ -137,13 +140,15 @@ def prepare_scoring(worktree: str, home: pathlib.Path, run: Git = git) -> str |
config = located(worktree, home, run)
if isinstance(config, Failure):
return config
# Where AGENTS.md is missing, this repo keeps the values in seat-prompts.md: .claude/rules/this-repo-keeps-no-agents-md.md.
source = config.paths["working-rules"]
if not source.is_file() and (own := pathlib.Path(worktree) / "skills" / "comprehension-panel" / "seat-prompts.md").is_file():
source = own
rules = read(source) if source.is_file() else ""
if isinstance(rules, Failure):
return rules
# This repo keeps the values in seat-prompts.md, so its working rules hold none: .claude/rules/this-repo-keeps-no-agents-md.md.
if section(rules, VALUES_HEADING) is None and (own := pathlib.Path(worktree) / "skills" / "comprehension-panel" / "seat-prompts.md").is_file():
source, rules = own, read(own)
if isinstance(rules, Failure):
return rules
skill = read(PANEL / "SKILL.md")
if isinstance(skill, Failure):
return skill
+30
View File
@@ -165,6 +165,28 @@ class PrepareScoring(unittest.TestCase):
assert isinstance(ran, str), ran
self.assertIn("every non-test tracked file: `bin/**` and `README.md`. Do NOT open any record of a past panel, nor any review output.", pathlib.Path(ran.splitlines()[2]).read_text())
def test_takes_the_values_from_the_checkouts_seat_prompts_where_the_working_rules_hold_none(self):
own = self.checkout / "skills" / "comprehension-panel" / "seat-prompts.md"
own.parent.mkdir(parents=True)
own.write_text("# Seats\n\n## proj's values\n\n- Language: Go\n- Kind: a CLI\n- Domain: parsing\n- Domain docs: the spec\n- 3am question: the parse hangs\n")
for rules in ("# Working rules, with no values\n", None):
with self.subTest(rules=rules):
(self.checkout / "AGENTS.md").unlink(missing_ok=True)
self.commit(rules)
ran = self.prepare()
assert isinstance(ran, str), ran
self.assertIn("Your background: ~2 years in Go, first codebase of this kind (a CLI)", pathlib.Path(ran.splitlines()[2]).read_text())
self.assertIsNone(removed_setup(str(self.checkout), self.root, functools.partial(git, env=self.env)))
def test_keeps_the_working_rules_values_where_the_checkout_has_seat_prompts_too(self):
own = self.checkout / "skills" / "comprehension-panel" / "seat-prompts.md"
own.parent.mkdir(parents=True)
own.write_text("## proj's values\n\n- Language: Go\n- Kind: a CLI\n- Domain: parsing\n- Domain docs: the spec\n- 3am question: the parse hangs\n")
self.commit("## Scoring run\n\n- Language: Python\n- Kind: a CLI\n- Domain: parsing\n- Domain docs: the spec\n- 3am question: the parse hangs\n")
ran = self.prepare()
assert isinstance(ran, str), ran
self.assertIn("Your background: ~2 years in Python,", pathlib.Path(ran.splitlines()[2]).read_text())
def test_refuses_writing_nothing_where_the_project_gives_no_values(self):
self.commit()
ran = self.run_tool("prepare-scoring")
@@ -181,6 +203,14 @@ class PrepareScoring(unittest.TestCase):
assert isinstance(unread, Failure), unread
self.assertTrue(unread.reason.startswith(f"cannot read {self.checkout}/AGENTS.md: "), unread.reason)
self.assertEqual(len(self.git("worktree", "list").splitlines()), 1)
own = self.checkout / "skills" / "comprehension-panel" / "seat-prompts.md"
own.parent.mkdir(parents=True)
own.write_bytes(b"\xff")
(self.checkout / "AGENTS.md").write_text("# Working rules, with no values\n")
unread = self.prepare()
assert isinstance(unread, Failure), unread
self.assertTrue(unread.reason.startswith(f"cannot read {own}: "), unread.reason)
self.assertEqual(len(self.git("worktree", "list").splitlines()), 1)
if __name__ == "__main__":
+2 -2
View File
@@ -99,8 +99,8 @@ class JudgeFailures(unittest.TestCase):
("verdict_from", "'the judge interrupted without a question'", unasked),
("verdict_from", "'the judge quoted an answer without a question'", unasked),
("run_judge", "verdict.reason", field),
("run_judge", "checked.reason", "quotes a passage the transcript does not hold"),
("misquoted_evidence", "f'the judge quoted {verdict.evidence!r}, which is not in the transcript", "quotes a passage the transcript does not hold"),
("run_judge", "checked.reason", "quotes a passage that neither the task nor the transcript holds"),
("misquoted_evidence", "f'the judge quoted {verdict.evidence!r}, which is not in the task or the transcript", "quotes a passage that neither the task nor the transcript holds"),
("claude_reply", "f'could not start claude:", started),
("claude_reply", "proc.stderr.strip() or f'{who} exited", exited),
("claude_reply", 'f"{who} printed no json reply', unparsed),
+3 -2
View File
@@ -187,8 +187,9 @@ Exit 1, saying why, when:
- the worker or the judge fails three times running, retried a minute apart within the cycle. A
worker fails when claude cannot start, exits non-zero, is killed, or ends without a result event;
a judge when claude cannot start, exits non-zero or prints no json reply, or its reply misses or
mistypes a field, interrupts or quotes an answer without a question, or quotes a passage the
transcript does not hold; it holds an elided passage when each fragment appears in order.
mistypes a field, interrupts or quotes an answer without a question, or quotes a passage that
neither the task nor the transcript holds, where each fragment of an elided quote must appear in
order, in the task then the transcript.
A usage limit is not a failure, and restarts the count of three: the worker or the judge is
retried 2 minutes after the limit resets, or every 10 minutes when the reset time is unknown or
more than 2 minutes past. The judge's reply gives its reset time only as text, so the judge is
+2 -2
View File
@@ -726,8 +726,8 @@ class Cycles(unittest.TestCase):
self.assertEqual(run.code, 130)
self.assertEqual(run.roles(), ["worker", "judge", "judge", "judge", "worker", "judge"])
self.assertEqual(run.sleeps, [60, 60])
self.assertIn("the judge quoted 'never said', which is not in the transcript, for the question: A or B?", run.stderr)
self.assertIn("retrying the judge in a minute: the judge quoted '', which is not in the transcript\n", run.stderr)
self.assertIn("the judge quoted 'never said', which is not in the task or the transcript, for the question: A or B?", run.stderr)
self.assertIn("retrying the judge in a minute: the judge quoted '', which is not in the task or the transcript\n", run.stderr)
def test_retries_a_judge_claude_cannot_start(self):
checkout = Checkout(self)
+60
View File
@@ -4146,3 +4146,63 @@ Inherited architect, decided by:
- Navigation, Shape: `bin/chunk_driver/claims.py:1` module docstring: the lock and the chunk flags sit in one module named for that job, and `starting` yields a `Failure` instead of raising
- Locality, Navigation: `bin/forge/reviews.py:23` `review_decision`: all review-state reading in `forge/`, each field shape-checked; three similar names cost a docstring read each
- Locality: `bin/chunk_driver/project/model_choice.py:28` `overridden`: the model override is one function, where it was spelled out twice
## 2026-11-19T22:33:15Z, PR #646 at a357cc7b
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Junior A | 7 | 5.5 | 6 | 6 | 6 |
| Mid A | 7 | 6 | 6.5 | 6 | 6.5 |
| Maintainability senior | 7 | 6 | 6 | 6 | 6.5 |
| Inherited architect | 7 | 6.5 | 6 | 6 | 6.5 |
| Mean | 7.00 | 6.00 | 6.13 | 6.00 | 6.38 |
Junior A, hardest first:
- Locality, Shape: `bin/do_epic/main.py:287` `parked_through`: the three-step park and resume order, the `told` and `finished` flags and a raw string compare held at once; the docstring gives the order but not why the flags exist
- Locality, Self-sufficiency: `bin/agent_cycle/routing.py:115` `unfinished_route`: floor rung, escalation mark, cap and the count of unfinished verdicts meet in a dozen lines, and the reasons sit in the decision log
- Shape: `bin/agent_cycle/judge.py:237` `quotes_checked`: six checks each quietly turn one verdict type into another, and the call site doesn't show the result type
- Locality: `bin/do_epic/scheduler.py:144` `start_chunks`: four overlapping sets, a five-branch chain, a counter and nested locks shared with loop-claude
- Shape: `bin/agent_cycle/run.py:150` `rule`: runs the judge, stamps, annotates, steps up and orders the archive writes, beside four near-identical archive helpers
- Locality: `bin/agent_cycle/stuck_workers.py:52` `Watch.check`: mutates `self.cpu` and `self.judged` out of sight, and one condition mixes `and` and `or` without parentheses
- Shape: `bin/do_epic/gates.py:42` `gate`: a long ordered chain where a missing value means something different on each line
- Locality: `bin/loop_claude/loop/reload.py:36` `decode_handed`: pops legacy fields from a handover the old process wrote before it replaced itself; nothing enforces the coupling
- Self-sufficiency: `skills/larv-review/SKILL.md:89` "Round cap": three sections must be open at once to tell whether a fix reruns a pass
- Self-sufficiency: `bin/agent_cycle/verdicts.py:41` the comment: points to `cycle.judge.re_ask_checked`, a module path that doesn't exist
Mid A, hardest first:
- Locality: `bin/do_epic/main.py:354` `resumed_news`: a `while True` poll that carries `said` and `shown` across turns, with a nested-quote f-string; no comment says what holds when the loop exits
- Locality, Self-sufficiency: `bin/do_epic/main.py:287` `parked_through`: three steps whose correctness depends on each other; the reason for the order sits in the decision log
- Locality: `bin/do_epic/main.py:241` `chunk_run`: `news`, `told`, `finished` and the reopened-epic exit held across iterations
- Locality: `bin/do_epic/scheduler.py:144` `start_chunks`: a five-branch chain over four sets, counted under nested locks
- Shape: `bin/project_config/settings.py:187` `load`: about twenty comprehension clauses build one `faults` list, so finding what one setting requires means scanning all of them
- Locality: `bin/agent_cycle/routing.py:115` `unfinished_route`: five rung concepts at once, readable only with `bin/model_routing/ladder.py` open beside it
- Shape: `bin/chunk_pr/main.py:447` `levelled_and_finished`: checks whether a scoring run is owed, which its name doesn't suggest
- Locality: `bin/plan/ranking.py:239` `score`: the formula forks on the old and the new table shape, both live
- Self-sufficiency: `bin/larv_review/main.py:1` the module docstring: about 165 lines that restate what `COMMANDS` and the modules it calls enforce
Maintainability senior, hardest first:
- Locality, Shape: `bin/do_epic/main.py:287` `parked_through`: the told, finished and news interplay, the human-merge cases and the three-step order held at once, and no code enforces the order
- Locality, Shape: `bin/do_epic/main.py:354` `resumed_news`: a loop that mutates five locals and builds its message in a nested f-string, with no stated invariant
- Locality: `bin/agent_cycle/routing.py:115` `unfinished_route`: five rungs, an unfinished count, the escalation mark and the cap held together; each threshold's reason sits in the decision log
- Shape, Self-sufficiency: `bin/project_config/settings.py:187` `load`: about 20 comprehension expressions each encode a rule linking two settings; named predicates would make each rule findable
- Shape, Locality: `bin/chunk_pr/main.py:314` `merged`: the merge-queue loop with its flags, where a variable carries either a string or a Failure and each read must work out which
- Locality: `bin/plan/ranking.py:239` `score`: the old and new table shapes run through the whole module, so each change is checked against both
- Locality: `bin/larv_review/plan.py:21` `Emptied`: a `str` subclass whose type carries meaning, lost without warning by any code that rebuilds the string
- Locality: `bin/agent_cycle/judge.py:76` `TASK_HEADING`: an archive key, so rewording it breaks replays in another module, and only a comment warns
- Self-sufficiency: `skills/larv-review/SKILL.md:89` "Round cap": the review rules exist three times, here, in the help at `bin/larv_review/main.py:1` and in rule-hook's code
Inherited architect, would restructure first:
- Locality, Shape: `bin/rule_hook/round_cap.py:10` `round_cap_breaches`: the round cap lives in four places across three packages, and none owns the whole invariant; rounds are counted from commit titles, never from launches
- Navigation, Shape: `README.md:225` "Packages under bin/": 84 entries listed alphabetically in dense prose, with no grouping by layer
- Shape: `bin/loop_claude/loop/reload.py:18` `LoopRun`: loop-claude's core run state defined in a module named for self-reloading
- Shape: `bin/agent_cycle/judge.py:116` `Rejected`: says loop-claude rejected the reply, in a module do-epic shares
- Self-sufficiency: `bin/agent_cycle/run.py:103` the comment: cites `close.py`, which doesn't exist
- Self-sufficiency: `bin/agent_cycle/verdicts.py:41` the comment: cites `cycle.judge.re_ask_checked`, a stale module path
- Navigation: `bin/chunk_driver/drivers.py:1` the module: "entry point" and "driver" name one concept, and `Run`, `ChunkRun` and `LoopRun` are one concept in three types
- Navigation: `bin/do_epic/status.py:1` the module: in no map, and the package's `__init__.py` is empty like 40 others
- Locality: `reviewer-merge-trials/driver.py:4` the imports: a frozen trial imports live code under `bin/`, so a refactor there breaks a record
- Self-sufficiency: `bin/agent_cycle/routing.py:92` the comment: one of 109 citations of the decision log that carry a unit's reason
+1 -1
View File
@@ -153,7 +153,7 @@ Valid while `~/.claude` is a checkout of this repo.
- **Releases.** An epic item has no release. It ships into its repo's unreleased work: where the repo publishes something others consume, a bullet under `CHANGELOG.md` → `## Unreleased`, or nothing where the repo's plan is in Jira. The issue is no item of the repo's plan, so the chunk's worker writes the bullet in its branch and runs `chunk-pr merge` without `--finish`.
- **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. 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. A gate is a pull request's pending checks or, on GitHub, the approval its branch protection requires; a draft waits on neither, since its worker has yet to mark it ready. On Gitea a draft is a pull request whose title opens with `WIP:` or `[WIP]`, Gitea's default `WORK_IN_PROGRESS_PREFIXES`. Changes a reviewer requested resume the chunk only while that review was made on the pull request's head commit and the pull request's author has not commented or replied after it; once the worker pushed or replied, the chunk parks on a new review, since GitHub keeps the decision until the reviewer reviews again. The chunk's window reads the forge once a minute, which no forge's rate limit notices. A chunk resumes only into a free slot, under the limits a starting chunk meets, and stays parked until then. `do-epic <key>` starts a parked chunk's window again whatever the limits, since the chunk stays parked. do-epic sets `CHUNK_PR_PARKS=1` for each worker, so `chunk-pr merge` fails at once where the pull request awaits an approval, and the worker's run doesn't hold a slot while the pull request waits. In a repo whose config sets `merge = "human"`, the merge itself is a gate: `chunk-pr merge` leaves the pull request ready, the chunk parks on `your merge` once nothing else holds the pull request, and it resumes when the forge no longer reports the pull request open, to clean up and finish. The judge may rule such a chunk finished while its pull request is open, since its worker ends each run there. So do-epic reads a gate it could not read again before it hands the chunk on, and tells the worker once to remove a worktree whose pull request is no longer open.
- **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. A gate is a pull request's pending checks or, on GitHub, the approval its branch protection requires; a draft waits on neither, since its worker has yet to mark it ready. On Gitea a draft is a pull request whose title opens with `WIP:` or `[WIP]`, Gitea's default `WORK_IN_PROGRESS_PREFIXES`. Changes a reviewer requested resume the chunk only while that review was made on the pull request's head commit and the pull request's author has not commented or replied after it; once the worker pushed or replied, the chunk parks on a new review, since GitHub keeps the decision until the reviewer reviews again. The chunk's window reads the forge once a minute, which no forge's rate limit notices. A chunk resumes only into a free slot, under the limits a starting chunk meets, and stays parked until then. `do-epic <key>` starts a parked chunk's window again whatever the limits, since the chunk stays parked. do-epic sets `CHUNK_PR_PARKS=1` for each worker, so `chunk-pr merge` fails at once where the pull request awaits an approval, and the worker's run doesn't hold a slot while the pull request waits. In a repo whose config sets `merge = "human"`, the merge itself is a gate: `chunk-pr merge` leaves the pull request ready, the chunk parks on `your merge` once nothing else holds the pull request, and it resumes when the forge no longer reports the pull request open, to clean up and finish. It resumes too once the pull request conflicts with its base branch, or is behind it where GitHub's branch protection requires an up-to-date branch, so the person finds a pull request they can merge. The worker then runs `chunk-pr merge` again, which levels the branch, waits for the checks and leaves the pull request ready. A chunk whose cycle ends on such a pull request is not handed on: its worker is told after each cycle until the pull request merges into its base. While GitHub still computes whether the pull request merges, the chunk stays parked until the next read. Gitea also reports a pull request as not mergeable for the seconds it checks for conflicts. A read in those seconds resumes the chunk for a run that doesn't change anything, which costs less than reading every gate twice to tell the two apart. The judge may rule such a chunk finished while its pull request is open, since its worker ends each run there. So do-epic reads a gate it could not read again before it hands the chunk on, and tells the worker once to remove a worktree whose pull request is no longer open.
- **Human tasks.** do-epic leaves a human task's issue as the team filed it. The task gets a window of its own while it is open, no issue blocks it, and it blocks another open issue. The window DMs the human once, through the notifier of the first repo whose project config names one (the repos of the issues it holds up come first, then those of the epic's other issues; where none does, the window says so), shows as parked (`awaits a human's task`) so that it doesn't take a running slot, and polls the epic every minute until the task no longer holds up an open issue. Then the issues it held up may start. A window that starts again, as after a reboot, DMs again.
- **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.
- **Finishing.** When the epic holds no open item: release-review passes on each repo the epic changed, then the items they file, then the human confirms each achieve goal and that no maintain goal has a defect. For a goal that isn't met, do-epic proposes items for approval. Then a summary comment on the epic, and closing the epic in Jira, as the very last step.
+1 -1
View File
@@ -12,4 +12,4 @@ Everything written — chat, commit messages, comments, docs, code — is in **E
- **Write the thing, not an introduction to it.** A sentence announcing what follows, or flagging that it deserves attention, doesn't carry anything — if it matters, it is in what follows. A bare label is fine. BANNED: `Here's the new audience text, which is the part that needs your eye:`, `One thing I changed that deserves your attention.`, `One judgment call I'd flag rather than bury.`, `Three things came along that would otherwise have been left false.` GOOD: `New audience text:`, or the list alone.
- **Write negations as people say them.** After a verb, or after its preposition, write `doesn't <verb> anything` or `anyone`, never `<verb> nothing` or `no one`; each breach is a 🟡. BANNED: `stops nothing`, `depends on no one`, `so answering in time costs nothing`. GOOD: `doesn't stop anything`, `doesn't depend on anyone`, `so answering in time doesn't cost anything`.
- **No contrastive tail.** `X rather than Y`, `not Y but X`, `instead of Y`: state X and stop. The rejected alternative is noise unless naming it stops a reader choosing Y. BANNED: `verified in CI rather than asserted`. GOOD: `verified in CI`.
- **A sentence about several named things holds for each.** Where a sentence gives one property to several named fields, flags or tables, check the property in each one's source. Where it fails for one, split the sentence. BANNED, where only `users` has the column: `Each row of users and groups has a name`. GOOD: `Each row of users has a name. A row of groups has only an id`.
- **A sentence about several named things holds for each of them.** Where one sentence gives a property to several named fields, files, flags or tables, check the property in each one's source. Where it fails for one, split the sentence. BANNED, where only `repos` has the column: `Each row of the repos and labels tables has a name`. GOOD: `Each row of the repos table has a name. A row of the labels table has only its label`.
+38 -74
View File
@@ -6,22 +6,20 @@
`Bar = 0.1`
`Next ID = 461`
`Next ID = 464`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 460 | 0.14.0 | | | **Review the judge's fix for quoting the worker's task as evidence with every larv-review pass it fires, and adjust it to their findings.** | 2 | 2 | 3 | 5 | 2 | code health by 3, 1.1 by 5 | 7.2 |
| 452 | 0.14.0 | | | **Make do-epic's view of the Jira workflow settings: the statuses at which an issue unblocks the issues it blocks, and the moves the team's own automation makes, so do-epic makes none of those.** | 3 | 2 | 2 | 5 | 5 | 1.6 by 7, 1.5 by 3 | 2.1 |
| 463 | 0.14.0 | | defect | **Show the judge the transcript's tail whatever the size of the records.** | 2 | 2 | 3 | 5 | 3 | 1.2 by 6, 1.5 by 4, 1.4 by 2 | 4.2 |
| 449 | 0.14.0 | | | **Record do-epic's repo picks and sub-task summaries in the team's own spelling, such as `core-4` and `core-4: Bygg …`, as its config sets them.** | 2 | 2 | 2 | 4 | 3 | 1.6 by 6 | 2.0 |
| 458 | 0.14.0 | | | **Resume a chunk whose pull request awaits a person's merge once it no longer merges cleanly into the default branch, so the worker brings it level again.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 4, 1.5 by 3 | 1.9 |
| 453 | 0.14.0 | | | **Make the issue types that do-epic and `todo-item add` file in Jira settings, since a Jira project such as TW has no Task type.** | 2 | 2 | 1 | 3 | 2 | 1.6 by 5 | 1.8 |
| 457 | 0.14.0 | | | **Keep loop-claude from starting a chunk for an item whose pull request is ready and awaits a person's merge under `merge = "human"`.** | 3 | 2 | 2 | 5 | 5 | 1.6 by 5, 1.4 by 3 | 1.7 |
| 450 | 0.14.0 | | | **Add `do-epic <EPIC-KEY> --dry-run`, which prints every Jira write planning would make and each chunk that would start, and makes none of them.** | 2 | 2 | 2 | 4 | 3 | 1.6 by 5 | 1.6 |
| 459 | 0.14.0 | | | **Make the prose standard require that a sentence giving one property to several named tables, fields or flags holds for each of them.** | 1 | 2 | 2 | 3 | 1 | 1.1 by 3 | 1.3 |
| 454 | 0.14.0 | | | **Start a do-epic chunk's issue as the team's board expects, by settings: assigned to the account do-epic works as, moved by a start transition and added to a board's active sprint.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 4 | 1.1 |
| 446 | 0.15.0 | | question | **Kill the process a stuck check names where its verdict is `stuck`, once the human says the recorded verdicts match what they would have done.** | 2 | 2 | 3 | 5 | 3 | 1.5 by 3 | 1.0 |
| 462 | 0.15.0 | | | **Run under `mutate-changes` the tests that today fail in mutmut's copy of the tree, so a mutant of a line only they cover is killed.** | 2 | 1 | 2 | 3 | 3 | code health by 3 | 4.7 |
| 77 | 0.15.0 | | | **Teach `bin/metric-bench` Go and TypeScript, rerun it once two projects' comprehension histories name places, and bring into review only a metric that tracks the panel.** | 4 | 2 | 1 | 5 | 6 | 1.1 by 7, 1.4 by 7 | 2.1 |
| 196 | 0.15.0 | | decision | **Replay the architecture, principles, overrides and product-owner passes with `review-replay` on Opus 5.5 projects, record each run in the review-replay routing decision, and, where a run qualifies a rung, add back the code that lowers a pass to it.** | 2 | 2 | 3 | 5 | 2 | 1.4 by 3 | 1.2 |
| 321 | 0.15.0 | 196 | decision | **Evaluate the review passes that run on a rung `review-replay` qualified, against the chunks before them, and revert any pass whose findings or later fixes worsened.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 3, 1.4 by 2 | 2.0 |
@@ -29,7 +27,7 @@
| 268 | 0.15.0 | | | **End a run whose release is ready to cut with a notice on loop-claude's terminal, in place of an interrupt that waits for an answer.** | 2 | 2 | 3 | 5 | 3 | 1 by 5 | 1.9 |
| 445 | 0.15.0 | | | **Refuse a plan that holds an item a `Finish item <ID>` commit already removed, so a merge resolution cannot bring a finished item back.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3, 1.1 by 2 | 1.8 |
| 171 | 0.15.0 | | decision | **Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.** | 3 | 2 | 2 | 5 | 4 | 1.2 by 3, 1.4 by 3 | 1.8 |
| 300 | 0.15.0 | | owner | **Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Self-sufficiency first; today the scoring runs at 81e8d8a1 scored Navigation 7.13 and 6.75, Locality 6.38 and 5.63, Shape 6.25 and 5.88, Self-sufficiency 5.88 and 5.25, and Overall 6.50 and 5.88.** | 4 | 2 | 3 | 7 | 8 | code health by 8 | 1.7 |
| 300 | 0.15.0 | | owner | **Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Locality and Self-sufficiency first; today the scoring run at a357cc7b scored Navigation 7.00, Locality 6.00, Shape 6.13, Self-sufficiency 6.00 and Overall 6.38.** | 4 | 2 | 3 | 7 | 8 | code health by 8 | 1.7 |
| 264 | 0.15.0 | | | **Report the comprehension seats and the escalated subagents as subagent types of their own in `routing-figures.md`, with their dollars.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 5 | 1.7 |
| 323 | 0.15.0 | | | **Count a release review as landed once its pull request has merged, whatever its commits are titled.** | 3 | 2 | 3 | 6 | 3 | 1.4 by 3, 1.5 by 2 | 1.7 |
| 342 | 0.15.0 | | | **Research the tooling agents read, search and run commands with once more, and file an item for each tool that cuts tokens a replay shows keep quality.** | 1 | 2 | 1 | 2 | 3 | 1.4 by 3, 1.5 by 2 | 1.7 |
@@ -79,40 +77,19 @@
## Details
### 460. Review the judge's fix for quoting the worker's task as evidence with every larv-review pass it fires, and adjust it to their findings.
### 463. Show the judge the transcript's tail whatever the size of the records.
The fix shipped without any larv-review pass, reviewer or comprehension check, at lilleman's request on 2026-11-19, so loop-claude could run unattended again: PR #641, commit "Let the judge quote the worker's task as evidence". Before it, the judge read the task above the transcript's tail but `quotes_checked` checked the evidence only against that tail. Once a session outgrew the tail, a verdict quoting the task, such as `Do the next chunk in 0.13.0`, was rejected three times running, and the loop exited after each merged chunk (items 448, 455 and 451). `Grounds` now carries the task, and the evidence must appear in the task, then the tail.
`judge_prompt` in `bin/agent_cycle/judge.py` gives the transcript only what `JUDGE_PROMPT_CHARS = 400000` leaves after the premises, the records and the rules. In claude-config those now take about 519,000 to 523,000 characters, so `room` clamps to 0 and the judge reads the task above an empty transcript. Every judge prompt archived for claude-config since at least 2026-11-19 17:16 shows none:
- The 0.13.0 chunks of items 448, 455 and 451 each stopped after the judge failed three times.
- The chunk of items 458 and 459 drew four `unfinished` verdicts after it had merged, each quoting only the task.
Run the passes the change fires: security, stability (with `~/.claude/rules/this-machine/cross-repo-review.md` where it applies), prose for the comments and docstrings it changed, and overrides if `rule-hook overrides` prints a line. Run the comprehension check where `larv-review` says one is due. Also weigh whether the evidence schema's description ("a verbatim quote of the one transcript passage") should name the task too, and whether `misquoted_evidence`'s message should say "the task or the transcript".
The judge sees neither a merge nor a worker's question, so every chunk here loops until a human ends it. Item 460's fix, letting the judge quote the task, treated a symptom of this.
Keep the transcript's tail a floor of the budget. Where the head leaves less, cut the records or stop with a message that names their size, rather than send a blind prompt. The constant's comment sizes the budget for a 200,000-token context, so raise it only where the judge's model has room. Item 298 cuts the records for cost; this item only guarantees the transcript room. Write first the test that fails today: a brief whose records exceed the budget still shows the transcript's last message.
Touches:
- `bin/agent_cycle/judge.py`: `Grounds` (small), `quotes_checked` (small), `judge_prompt` (small)
- `bin/judge_replay/archived_prompt.py`: `grounds_of` (small)
- `bin/agent_cycle/test_judge.py`
- `bin/judge_replay/test_judge_replay.py`
### 452. Make do-epic's view of the Jira workflow settings: the statuses at which an issue unblocks the issues it blocks, and the moves the team's own automation makes, so do-epic makes none of those.
do-epic counts an issue as done only where Jira's status category is done, and moves a finished chunk's issue to done itself, by `jira-finish-transition`. On a team whose CI moves issues through the workflow, both are wrong. On TW, CI moves an issue to Code Review when its pull request opens, to Release Ready when it merges, and to Done when it is deployed. So do-epic would move an issue to Done before it is deployed, and would hold every blocked issue until the blocker is deployed, though the team wants blocked work to start once the blocker's pull request merges.
- Settings in do-epic's config.toml name the statuses at which an issue unblocks the issues it blocks, such as `jira-unblock-statuses = ["Release Ready", "Done"]`; without them, Jira's done category counts, as today.
- A setting says which moves the team's workflow makes on its own, so do-epic makes none of them. With the setting, a finished chunk moves no status and stops with no reason; `jira-finish-transition` then only closes the epic.
- The epic's finishing waits until every issue is in Jira's done category, so release reviews follow the deploy.
- `--status` names the status an issue waits to reach.
Touches:
- `bin/do_epic/config.py`: `DoEpicConfig`, `load`
- `bin/do_epic/backend/protocol.py`: `EpicIssue` (small)
- `bin/do_epic/backend/jira.py`: `found_of` (small), `finish_issue`
- `bin/do_epic/scheduler.py`: `open_blockers`
- `bin/do_epic/main.py`: `handed_on`, `split_items_closed`
- `bin/do_epic/finish.py`: `due` (small), `still_open` (small)
- `bin/do_epic/status.py`: `lines` (small)
- `bin/do_epic/test_scheduler.py`
- `bin/do_epic/test_main.py`
- `bin/do_epic/backend/test_jira.py`
- `README.md`: `### Set up a project` (small)
- `bin/agent_cycle/judge.py`: `JUDGE_PROMPT_CHARS` (small), `judge_prompt` (small)
- `bin/agent_cycle/test_judge.py`: `JudgePrompt`
### 449. Record do-epic's repo picks and sub-task summaries in the team's own spelling, such as `core-4` and `core-4: Bygg …`, as its config sets them.
@@ -132,22 +109,6 @@ Touches:
- `bin/do_epic/test_split.py`
- `README.md`: `### Set up a project` (small)
### 458. Resume a chunk whose pull request awaits a person's merge once it no longer merges cleanly into the default branch, so the worker brings it level again.
Under `merge = "human"` a pull request stays ready for hours or days while the default branch moves. A conflict, such as each branch holding its own changelog bullet or plan edit, or a branch protection that requires an up-to-date branch, then blocks the person who would merge it. Yet `gate` in `bin/do_epic/gates.py` reads only the draft state, the checks, the review decision and the waiting threads, so the window and `--status` keep saying `awaits your merge`, and nothing resumes the chunk unless a reviewer comments.
- Where `by_human`, `gate` reads the forge's mergeability before it returns the `your merge` gate: GitHub's `mergeable` and `mergeStateStatus`, Gitea's `mergeable`. No reader exists yet under `bin/forge/`; add one beside `open_pull` in `bin/forge/pulls.py`.
- A pull request that conflicts with the default branch, or is behind it where the branch protection requires an up-to-date branch, gives an `Open` whose news tells the worker to run `chunk-pr merge` again, which levels, pushes, waits for the checks and marks ready. Settle whether that rerun passes `--finish` again, since the items are already finished on the branch.
- GitHub reports `mergeable` as `UNKNOWN` while it computes it: that keeps the `your merge` gate until the next read, rather than resuming the chunk.
- State the new resume in `docs/decisions.md` → "Long gates".
Touches:
- `bin/do_epic/gates.py`: `gate` (small)
- `bin/forge/pulls.py`
- `bin/forge/test_forge.py`
- `bin/do_epic/test_gates.py`
### 453. Make the issue types that do-epic and `todo-item add` file in Jira settings, since a Jira project such as TW has no Task type.
do-epic and `todo-item add` file every new issue as a Task, the name `plan_store/jira_epic.py` sets as `ISSUE_TYPE`. A Jira project without a Task type, such as TW, whose types are Feature, Bug, Chore and Investigation, refuses each one. So `do-epic --file` fails there, and so does the epic's finishing, which files a release review for each repo.
@@ -216,13 +177,6 @@ Touches:
- `bin/do_epic/test_planning.py`
- `README.md`: `## Tools` (small)
### 459. Make the prose standard require that a sentence giving one property to several named tables, fields or flags holds for each of them.
An outside reviewer's finding on a README raised it: a sentence described the rows of two tables, saying each has a `name`, and only one of the two tables has that column. The prose pass read the sentence and not the two sources behind it. Add the rule to `skills/larv-review/standards/prose.md`: a sentence that gives a property to several named things holds for every one, checked in each source; where it fails for one, the sentence splits.
Touches:
- `skills/larv-review/standards/prose.md`
### 454. Start a do-epic chunk's issue as the team's board expects, by settings: assigned to the account do-epic works as, moved by a start transition and added to a board's active sprint.
When a do-epic chunk starts, its issue stays as Jira holds it: unassigned, in New and outside the sprint. A team whose board shows who works on what, such as TW, where an issue being worked is assigned to the person, In Progress and in the active sprint, then sees nothing of the loop's work. Today each worker would have to do this by hand, from rules only some machines hold.
@@ -252,6 +206,12 @@ Touches:
- `bin/loop_effects/child_shells.py`: `stop` (small)
- `bin/loop_claude/loop/usage.py`: `HELP` (small)
### 462. Run under `mutate-changes` the tests that today fail in mutmut's copy of the tree, so a mutant of a line only they cover is killed.
Found while shipping item 461: `mutate-changes` printed `23 mutants on changed lines, 18 not killed. Left out the tests that fail without a mutant, in do_epic/test_main.py, larv_review/test_larv_review.py, larv_review/test_scoring_setup.py, plan/test_ranking.py, repo_checks/…, review_rules/test_review_passes.py, review_rules/test_reviewer_context.py, rule_hook/test_rule_hook.py, test_settings_filter.py`. All 18 survivors were in `bin/larv_review/scoring_setup.py`: `prepare_scoring`, whose tests are among those left out, so the chunk checked four of them by hand and left 14 unchecked. Find why each left-out test fails in mutmut's copy, such as a path to `skills/` or a git checkout it expects, and make it pass there, or report under the count which changed lines no remaining test covers.
Touches `bin/mutate_changes/`, and the tests named above.
### 77. Teach `bin/metric-bench` Go and TypeScript, rerun it once two projects' comprehension histories name places, and bring into review only a metric that tracks the panel.
2026-10-08, lilleman: no metric enters review until a rerun on more data shows it tracking the panel.
@@ -310,26 +270,30 @@ Have the gate, or `rank_todo.py --check` where it runs in a checkout, refuse a p
Raised by the goals audit of PR #296. `bin/routing_figures/calls.py` groups a chunk's review rounds by the rung its worker started on, and calls for a routing change when a lower rung took more of them. Since PR #296 the reviewers may run above the worker's rung, on the one their item's E + I picks, and no figure groups rounds by it, though the archived worker line names the E + I it follows from. A cheap worker on an item of high E + I gets stronger reviewers, who may raise more rounds, and a call could then blame the worker's rung for them: an interrupt of lilleman that settles nothing (goal 1.2).
### 300. Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Self-sufficiency first; today the scoring runs at 81e8d8a1 scored Navigation 7.13 and 6.75, Locality 6.38 and 5.63, Shape 6.25 and 5.88, Self-sufficiency 5.88 and 5.25, and Overall 6.50 and 5.88.
### 300. Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Locality and Self-sufficiency first; today the scoring run at a357cc7b scored Navigation 7.00, Locality 6.00, Shape 6.13, Self-sufficiency 6.00 and Overall 6.38.
Filed by the comprehension check of PR #473 at 13d1550 (`larv-review record-scoring`), which printed `Floor:` and `Next:`, and refreshed from the two runs of PR #633 at 81e8d8a1. The lowest mean is Self-sufficiency: 5.88 in the first run and 5.25 in the second. Every seat says the same thing: the vocabulary lives only in `CLAUDE.md` → "Vocabulary", the why of thresholds and orderings sits behind `docs/decisions.md → …` pointers, and behaviour lives in prose that no code ties to its check. Locality follows, at 6.38 and 5.63: scheduling state lives in tmux window names, state files and flocks across three packages. Refresh this item's places and aim from the newest run before the chunk starts; do not file a second floor item.
Filed by the comprehension check of PR #473 at 13d1550 (`larv-review record-scoring`), which printed `Floor:` and `Next:`, and refreshed from the run of PR #646 at a357cc7b. The lowest means are Locality and Self-sufficiency, both 6.00. Locality: do-epic's parking and scheduling carry order-dependent state across loop turns, state files and flocks, and no code enforces the order. Self-sufficiency: the why of thresholds and orderings sits behind `docs/decisions.md → …` pointers, 109 of them in 79 modules, and the review rules live in prose that several code sites repeat. Refresh this item's places and aim from the newest run before the chunk starts; do not file a second floor item.
Aim: one ambitious refactor of the areas below, sized so every mean reaches 7.0 on the chunk's own scoring run. Where a place is already easier to read when the chunk starts, drop it.
Places the seats named, hardest first (`larv-review places`), Self-sufficiency first:
Places the seats named, hardest first (`larv-review places`), Locality and Self-sufficiency first:
- Self-sufficiency, Locality: `bin/agent_cycle/routing.py:115` `unfinished_route`, with `:131` `escalated_route`: five rungs, a count and the escalation mark held at once. The module table resolves the what, but the why of the caps is only in the decision log. Every seat in both runs named it.
- Self-sufficiency: `bin/agent_cycle/judge.py:235` `quotes_checked`, with `:23` `INTERRUPT_RULES` and `:76` `TASK_HEADING`: six quote kinds fail differently, the prompt is behaviour no code checks, and `TASK_HEADING` is silently an archive format. Seven seats named it.
- Self-sufficiency: `bin/rule_hook/rules.py:27` `RULES`: each rule's only specification is one long English sentence, such as `env-file-read`, and its check lives in a sibling module that nothing ties it to. Five seats named it.
- Self-sufficiency, Locality: `skills/larv-review/SKILL.md:89` "Round cap" and `:97` "Re-entry", with `bin/review_rules/review_passes.py:8` `PASS_AGENTS`: rules with exceptions to exceptions, a cap spread over three packages and this prose, and code constants that must match sentences here.
- Locality: `bin/do_epic/main.py:283` `parked_through`: a polling loop with four mutable locals across three result types, and a crash-ordering invariant across a state file, a window name and Jira. Five seats named it; two would least want to change it.
- Locality: `bin/do_epic/scheduler.py:136` `start_chunks`, with `bin/loop_claude/loop/chunk_windows.py:107` `may_start`: overlapping window sets from two stores feed an elif chain under nested flocks, with the tmux state's schema in `agent_cycle/tmux.py:92` `as_listed`.
- Locality: `bin/chunk_pr/main.py:429` `levelled_and_finished`: a load-bearing order held together by one-liners where a Failure's truthiness carries the control flow.
- Locality, Shape: `bin/agent_cycle/run.py:150` `rule`, with `:32` `Cycle` and `:240` `close`: a 16-field value, very long single-line expressions, and an archive-before-step-up order that only reading order tells.
- Locality: `bin/do_epic/main.py:11` imports, with `bin/loop_claude/loop/reload.py:18` `LoopRun`: do_epic reaches into eight loop_claude modules over a wire format a renamed field breaks.
- Shape, Navigation: `bin/agent_cycle/verdicts.py:1`, `bin/loop_claude/cycle/` and `bin/loop_state/paths.py:6`: stale `cycle.` names, and folders whose names mislead.
- Locality: `bin/project_config/settings.py:182` `load`: one list encodes the whole validation matrix.
- Shape: `bin/agent_cycle/stuck_workers.py:52` `Watch.check`: the condition at line 59 mixes `or` and `and` without parentheses over dicts mutated across ticks.
- Locality, Shape: `bin/do_epic/main.py:287` `parked_through`, with `:354` `resumed_news` and `:241` `chunk_run`: a three-step park and resume order, the `told`, `finished` and `news` flags and a poll that carries five locals across turns. The docstring gives the order, but no code enforces it and no comment states the loop's invariant. Three seats named it hardest; all three would least want to change it.
- Locality, Self-sufficiency: `bin/agent_cycle/routing.py:115` `unfinished_route`, with `:131` `escalated_route`: five rungs, a count, the escalation mark and the cap held at once. The module table resolves the what, but the why of each threshold is only in the decision log. Three seats named it.
- Locality: `bin/do_epic/scheduler.py:144` `start_chunks`: four overlapping sets feed a five-branch chain, counted under nested locks shared with loop-claude. Two seats named it.
- Locality, Shape: `bin/rule_hook/round_cap.py:10` `round_cap_breaches`, with `bin/review_rules/round_titles.py:33` `round_counts`, `bin/larv_review/reviewer_header.py:75` `unanswered_round` and `skills/larv-review/SKILL.md:89` "Round cap": the cap lives in four places across three packages, none owns the whole invariant, and the rules exist a third time in the help at `bin/larv_review/main.py:1`. Three seats named it.
- Shape, Self-sufficiency: `bin/project_config/settings.py:187` `load`: about twenty comprehension clauses in one `faults` list encode the rules that link settings; named predicates would make each findable. Two seats named it.
- Locality, Shape: `bin/chunk_pr/main.py:314` `merged`, with `:447` `levelled_and_finished`: a queue loop whose variables carry a string or a Failure, and a scoring-run check the name doesn't suggest. Two seats named it.
- Locality: `bin/plan/ranking.py:239` `score`, with `:144` `weigh`: the old and new table shapes run through the whole module. Two seats named it.
- Locality: `bin/agent_cycle/judge.py:76` `TASK_HEADING`, with `bin/model_routing/route.py:47` and `bin/loop_claude/loop/reload.py:36` `decode_handed`: archive and handover formats that a reworded heading or a renamed field breaks, guarded only by comments. Three seats named one of them.
- Shape: `bin/agent_cycle/judge.py:237` `quotes_checked`, with `bin/agent_cycle/run.py:150` `rule`: checks that quietly turn one verdict type into another, and one function that runs the judge, steps up and orders the archive writes.
- Locality: `bin/larv_review/plan.py:21` `Emptied`: a `str` subclass whose type carries meaning, lost by any code that rebuilds the string.
- Shape: `bin/do_epic/gates.py:42` `gate`: a long ordered chain where a missing value means something different on each line.
- Shape: `bin/agent_cycle/stuck_workers.py:52` `Watch.check`: the condition at line 59 mixes `or` and `and` without parentheses over state mutated out of sight.
- Self-sufficiency: `bin/agent_cycle/verdicts.py:41` and `bin/agent_cycle/run.py:103`: comments that cite `cycle.judge.re_ask_checked` and `close.py`, neither of which exists; `bin/agent_cycle/judge.py:116` `Rejected` names loop-claude in a module do-epic shares.
- Navigation, Shape: `README.md:225` "Packages under bin/": 84 entries in alphabetical prose with no grouping by layer, two bullets run together at `:239`, and 40 packages whose `__init__.py` is empty.
- Shape: `bin/loop_claude/loop/reload.py:18` `LoopRun`: loop-claude's core run state in a module named for self-reloading; `Run`, `ChunkRun` and `LoopRun` are one concept in three types.
- Locality: `reviewer-merge-trials/driver.py:4`: a frozen trial imports live code under `bin/`, so a refactor there breaks a record.
### 264. Report the comprehension seats and the escalated subagents as subagent types of their own in `routing-figures.md`, with their dollars.