From 11ee0f7bbfba813f22fee4dbc2e171cc7ff6e75a Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 21:37:01 +0100 Subject: [PATCH 01/35] Resume a chunk that awaits a person's merge once its pull request no longer merges into its base --- README.md | 2 +- bin/do_epic/gates.py | 14 ++++++---- bin/do_epic/test_gates.py | 26 +++++++++++++++--- bin/forge/pulls.py | 30 ++++++++++++++++++++- bin/forge/test_forge.py | 38 ++++++++++++++++++++++++++- docs/decisions.md | 2 +- skills/larv-review/standards/prose.md | 1 + 7 files changed, 101 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 0cafcbbf..592eff7f 100644 --- a/README.md +++ b/README.md @@ -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. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. 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. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. Where the pull request meanwhile conflicts with the default branch, or is behind it where GitHub's branch protection requires an up-to-date branch, the chunk resumes and brings the branch level 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:`, 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. diff --git a/bin/do_epic/gates.py b/bin/do_epic/gates.py index dd2877b3..b1f28ebe 100644 --- a/bin/do_epic/gates.py +++ b/bin/do_epic/gates.py @@ -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 @@ -42,7 +42,7 @@ class Unopened(Open): 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, or no longer merges into its base as it stands (`forge.pulls.unmergeable`), so the worker levels it for that person. """ worktree = worktree_of(branch, at(checkout)) if not isinstance(worktree, str): @@ -77,9 +77,13 @@ 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 + # The same flags, since merge passes over an item an earlier run finished, and finishes one that resolving a conflict brought back. + return Open(f"pull request #{pull} {blocked}; run chunk-pr merge again, with the flags it had, to level the branch") if blocked else Gate(worktree, pull, MERGE) def worktree_of(branch: str, run: Run) -> str | None | Failure: diff --git a/bin/do_epic/test_gates.py b/bin/do_epic/test_gates.py index 36a68cdb..df287192 100644 --- a/bin/do_epic/test_gates.py +++ b/bin/do_epic/test_gates.py @@ -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, with the flags it had, to level the branch" + self.assertEqual(Forge(decision="APPROVED", mergeable="CONFLICTING", merge_state="DIRTY").gate(by_human=True), Open(f"pull request #7 conflicts with its base branch; {again}")) + self.assertEqual(Forge(gitea, mergeable="CONFLICTING").gate(by_human=True), Open(f"pull request #7 conflicts with its base branch; {again}")) + self.assertEqual(Forge(decision="", merge_state="BEHIND").gate(by_human=True), Open(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_loop_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: diff --git a/bin/forge/pulls.py b/bin/forge/pulls.py index 42b1bd31..de0b4ccc 100644 --- a/bin/forge/pulls.py +++ b/bin/forge/pulls.py @@ -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 @@ -44,6 +44,34 @@ def pull_at(forge: Forge, branch: str, head: str, state: typing.Literal["open", return Failure(f"tea api listed pull requests in a shape that can't be read: {str(pulls)[:200]}") +# Why a pull request doesn't merge into its base as it stands, as the words after "pull request #". +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. It is also false for the seconds Gitea 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. diff --git a/bin/forge/test_forge.py b/bin/forge/test_forge.py index da917564..4e642923 100644 --- a/bin/forge/test_forge.py +++ b/bin/forge/test_forge.py @@ -6,7 +6,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, required_checks, WAIT_SECONDS +from forge.pulls import BEHIND, CheckFailed, checks_now, checks_passed, CONFLICTS, open_pull, Pending, POLL_SECONDS, required_checks, unmergeable, WAIT_SECONDS from failure import Failure from forge.commands import forge_of, gitea, url_beside @@ -47,6 +47,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) diff --git a/docs/decisions.md b/docs/decisions.md index a5c4b71d..95a56c28 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -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//`. 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 ` 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 --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 ` 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 --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 ` 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 runs `chunk-pr merge` again with the flags it had, which levels the branch, passes over each item already finished, waits for the checks and leaves the pull request ready. While GitHub still computes whether the pull request merges, the chunk stays parked until the next read. Gitea reports a pull request as not mergeable also for the seconds it checks for conflicts; a read in those seconds resumes the chunk for a run that changes nothing, which is cheaper than a second read every minute to rule it out. 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. diff --git a/skills/larv-review/standards/prose.md b/skills/larv-review/standards/prose.md index 43316a18..19112d77 100644 --- a/skills/larv-review/standards/prose.md +++ b/skills/larv-review/standards/prose.md @@ -12,3 +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 anything` or `anyone`, never ` 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 of them.** Where one sentence gives a property to several named tables, fields, flags or files, 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`. From 111cb9248e8af7acb3cd19dc8fa2fa0b8e28ec9c Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 21:44:08 +0100 Subject: [PATCH 02/35] Let do-epic's config name the statuses that unblock an issue and leave the moves to a team's automation --- README.md | 3 +++ bin/do_epic/config.py | 27 ++++++++++++++++++++--- bin/do_epic/human_tasks.py | 10 ++++----- bin/do_epic/main.py | 16 ++++++++------ bin/do_epic/scheduler.py | 41 +++++++++++++++++++++++------------ bin/do_epic/status.py | 4 ++-- bin/do_epic/test_do_epic.py | 21 ++++++++++++++++++ bin/do_epic/test_finish.py | 1 + bin/do_epic/test_main.py | 11 ++++++++++ bin/do_epic/test_scheduler.py | 22 ++++++++++++++++--- bin/do_epic/test_status.py | 12 ++++++++-- 11 files changed, 132 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 0cafcbbf..d94373ee 100644 --- a/README.md +++ b/README.md @@ -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, as CI does from a pull request's merge, with two settings: + - `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", "Done"]`. 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 epic's finishing still waits until Jira counts every issue done, so the release reviews follow the deploy. + - `jira-automation-moves-issues = true` keeps do-epic from moving a finished chunk's issue: the automation does, and `jira-finish-transition` then only closes the epic. It 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:`. 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 ` uses it to pick where each open issue without such a label is worked, and records the pick as a label: `repo:` 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. diff --git a/bin/do_epic/config.py b/bin/do_epic/config.py index cb1856b0..f9cc3732 100644 --- a/bin/do_epic/config.py +++ b/bin/do_epic/config.py @@ -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", "Done"]`. 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 each issue through the workflow, as from a pull request's merge. do-epic then moves no finished chunk's issue, and `jira-finish-transition` only closes the epic. 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:`. 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,10 @@ 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, ...] = () + # The AUTOMATION_MOVES switch. + automation_moves: bool = False def label_repo_faults(table: object) -> list[str]: @@ -72,6 +81,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\", \"Done\"]"] 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 []), + # Without such a status, 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 +122,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 +132,4 @@ 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)) + return DoEpicConfig(folder, url, env_file, clone_folder, language, model, rule, finish_of(values), types.MappingProxyType(labels), tuple(values.get(UNBLOCKING_STATUSES, ())), values.get(AUTOMATION_MOVES) is True) diff --git a/bin/do_epic/human_tasks.py b/bin/do_epic/human_tasks.py index 13efb0c6..070e9d7e 100644 --- a/bin/do_epic/human_tasks.py +++ b/bin/do_epic/human_tasks.py @@ -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) diff --git a/bin/do_epic/main.py b/bin/do_epic/main.py index 88758999..c1d9c71f 100644 --- a/bin/do_epic/main.py +++ b/bin/do_epic/main.py @@ -142,7 +142,7 @@ def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: def status_printed(epic: EpicRun) -> Stop: """What `do-epic --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 +211,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,7 +248,7 @@ 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) + 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) place = chunk_root(key, issue, epic) if isinstance(place, Stop): @@ -424,16 +424,18 @@ def folder_made(root: str) -> Failure | 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 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, it leaves the chunk's issue to the automation, and the issue counts as in the first unblocking status; a split item still moves, 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`. - moved = None if key == epic.key else epic.store.finish_issue(key) + moved = None if key == epic.key or automated 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() 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] + # A search may not show the move yet, nor has the team's automation always made it, so the issue counts as moved here whatever the read says. + moved_as: dict[str, typing.Any] = {"status": epic.config.unblocking[0]} if automated else {"done": True} + issues = [dataclasses.replace(each, **moved_as) if each.key == key else each for each in issues] closed = split_items_closed(epic, issues) if isinstance(closed, Stop): return closed diff --git a/bin/do_epic/scheduler.py b/bin/do_epic/scheduler.py index 61e173c2..b2901a85 100644 --- a/bin/do_epic/scheduler.py +++ b/bin/do_epic/scheduler.py @@ -9,7 +9,8 @@ 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 text_files.markdown_text import listed from do_epic.repo_pick import HumanTask, LabelRepos, Pick, recorded, Repo from project_config.settings import PARALLEL_CHUNKS from do_epic.parked import parked_chunks @@ -73,43 +74,54 @@ 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 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 issue.status in 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, and waits only to be 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 issue.status in unblocking: + waits.append(Waits(issue.key, f"its work is merged: 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 +129,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 +140,8 @@ 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}") + until = f", until {'it' if len(blocking) == 1 else 'each'} is {listed(unblocking, 'or')}" if unblocking 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 +157,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 ` 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] = [] diff --git a/bin/do_epic/status.py b/bin/do_epic/status.py index 65e3ea96..da08d23a 100644 --- a/bin/do_epic/status.py +++ b/bin/do_epic/status.py @@ -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): diff --git a/bin/do_epic/test_do_epic.py b/bin/do_epic/test_do_epic.py index 07910d64..78e69852 100644 --- a/bin/do_epic/test_do_epic.py +++ b/bin/do_epic/test_do_epic.py @@ -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", "Done"]', 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()) diff --git a/bin/do_epic/test_finish.py b/bin/do_epic/test_finish.py index 68da41ee..bd248984 100644 --- a/bin/do_epic/test_finish.py +++ b/bin/do_epic/test_finish.py @@ -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")] diff --git a/bin/do_epic/test_main.py b/bin/do_epic/test_main.py index 49f9a274..e3d5a871 100644 --- a/bin/do_epic/test_main.py +++ b/bin/do_epic/test_main.py @@ -449,6 +449,17 @@ 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_moves_none_and_starts_what_it_blocks(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) + self.assertEqual({each.key: (each.status, each.done) for each in store.issues}, dict.fromkeys(("ABC-20", "ABC-23", "ABC-21", "ABC-22"), ("To Do", 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)] diff --git a/bin/do_epic/test_scheduler.py b/bin/do_epic/test_scheduler.py index 8bed9c06..fa1a554c 100644 --- a/bin/do_epic/test_scheduler.py +++ b/bin/do_epic/test_scheduler.py @@ -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,22 @@ 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 is merged: 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 or Shipped"), + Waits("ABC-24", "ABC-21 and ABC-22 block it, until each is Release Ready or Shipped"), + ])) + 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_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: diff --git a/bin/do_epic/test_status.py b/bin/do_epic/test_status.py index f811e78e..339625e0 100644 --- a/bin/do_epic/test_status.py +++ b/bin/do_epic/test_status.py @@ -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 is merged: 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", + ]) + 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}"]) From 6d7c8b5c25191a3b9608cfbe0ed42b624d511620 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 21:45:44 +0100 Subject: [PATCH 03/35] Sort the scheduler's imports and type the statuses list --- bin/do_epic/config.py | 4 +++- bin/do_epic/scheduler.py | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/bin/do_epic/config.py b/bin/do_epic/config.py index f9cc3732..2740651b 100644 --- a/bin/do_epic/config.py +++ b/bin/do_epic/config.py @@ -132,4 +132,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), tuple(values.get(UNBLOCKING_STATUSES, ())), values.get(AUTOMATION_MOVES) is True) + 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) diff --git a/bin/do_epic/scheduler.py b/bin/do_epic/scheduler.py index b2901a85..f39789a7 100644 --- a/bin/do_epic/scheduler.py +++ b/bin/do_epic/scheduler.py @@ -10,8 +10,8 @@ from chunk_driver.claims import CHUNK_FLAG, epic_chunks, HANDED, loop_chunks, pr from do_epic.backend.protocol import EpicIssue from failure import Failure from do_epic.split import finished, is_split, SPLIT_LABEL -from text_files.markdown_text import listed 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 From 18d28fa4722dc3830392e82abbf4385862b66341 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 21:46:22 +0100 Subject: [PATCH 04/35] =?UTF-8?q?Answer=20security=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(0=20misread);=20no=20findin?= =?UTF-8?q?g?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From fc4b0387d6b9ba9aeac9b2884fe411eec3ded2f8 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 21:58:17 +0100 Subject: [PATCH 05/35] =?UTF-8?q?Answer=20security=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(0=20misread);=20no=20findin?= =?UTF-8?q?g?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 547afc6cf28c409a4d982261d63394ff5e42120f Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:04:59 +0100 Subject: [PATCH 06/35] =?UTF-8?q?Answer=20stability=20round=201:=201=20?= =?UTF-8?q?=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(1=20misread);=20tell=20a=20?= =?UTF-8?q?finished=20chunk's=20worker=20of=20a=20pull=20request=20that=20?= =?UTF-8?q?no=20longer=20merges,=20in=20place=20of=20handing=20the=20chunk?= =?UTF-8?q?=20on?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- bin/do_epic/gates.py | 10 +++++++--- bin/do_epic/main.py | 8 ++++++-- bin/do_epic/test_gates.py | 12 ++++++------ bin/do_epic/test_main.py | 14 ++++++++++++++ docs/decisions.md | 2 +- 5 files changed, 34 insertions(+), 12 deletions(-) diff --git a/bin/do_epic/gates.py b/bin/do_epic/gates.py index b1f28ebe..1c6494cd 100644 --- a/bin/do_epic/gates.py +++ b/bin/do_epic/gates.py @@ -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. The chunk has news again once the pull request is no longer open, or no longer merges into its base as it stands (`forge.pulls.unmergeable`), so the worker levels it for that person. + 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): @@ -82,8 +87,7 @@ def gate(branch: str, checkout: str, at: typing.Callable[[str], Run], by_human: blocked = unmergeable(forge, pull, run) if isinstance(blocked, Failure): return blocked - # The same flags, since merge passes over an item an earlier run finished, and finishes one that resolving a conflict brought back. - return Open(f"pull request #{pull} {blocked}; run chunk-pr merge again, with the flags it had, to level the branch") if blocked else Gate(worktree, pull, MERGE) + 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: diff --git a/bin/do_epic/main.py b/bin/do_epic/main.py index 88758999..cdb738d5 100644 --- a/bin/do_epic/main.py +++ b/bin/do_epic/main.py @@ -287,7 +287,7 @@ def chunk_run(key: str, epic: EpicRun) -> Stop: 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 +305,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) diff --git a/bin/do_epic/test_gates.py b/bin/do_epic/test_gates.py index df287192..0c480e49 100644 --- a/bin/do_epic/test_gates.py +++ b/bin/do_epic/test_gates.py @@ -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" @@ -81,10 +81,10 @@ class GateOfAChunk(unittest.TestCase): 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, with the flags it had, to level the branch" - self.assertEqual(Forge(decision="APPROVED", mergeable="CONFLICTING", merge_state="DIRTY").gate(by_human=True), Open(f"pull request #7 conflicts with its base branch; {again}")) - self.assertEqual(Forge(gitea, mergeable="CONFLICTING").gate(by_human=True), Open(f"pull request #7 conflicts with its base branch; {again}")) - self.assertEqual(Forge(decision="", merge_state="BEHIND").gate(by_human=True), Open(f"pull request #7 is behind its base branch, whose protection requires it up to date; {again}")) + 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)) @@ -94,7 +94,7 @@ class GateOfAChunk(unittest.TestCase): 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_loop_merges_nobody_reads_whether_the_pull_request_merges(self): + 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) diff --git a/bin/do_epic/test_main.py b/bin/do_epic/test_main.py index 49f9a274..4cbe2bcf 100644 --- a/bin/do_epic/test_main.py +++ b/bin/do_epic/test_main.py @@ -746,6 +746,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] diff --git a/docs/decisions.md b/docs/decisions.md index 95a56c28..7d5dffe6 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -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//`. 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 ` 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 --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 ` 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 runs `chunk-pr merge` again with the flags it had, which levels the branch, passes over each item already finished, waits for the checks and leaves the pull request ready. While GitHub still computes whether the pull request merges, the chunk stays parked until the next read. Gitea reports a pull request as not mergeable also for the seconds it checks for conflicts; a read in those seconds resumes the chunk for a run that changes nothing, which is cheaper than a second read every minute to rule it out. 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 --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 ` 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. From e2c4993cc66ed234a97674d58de474adb6dfdbe8 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:04:59 +0100 Subject: [PATCH 07/35] =?UTF-8?q?Answer=20product-owner=20round=201:=201?= =?UTF-8?q?=20=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(1=20misread);=20the=20st?= =?UTF-8?q?ability=20round's=20answer=20fixes=20the=20same=20handed-on=20c?= =?UTF-8?q?hunk?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 0f5e8897e28d809d3b3264054e4b0fd3af524bf8 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:04:59 +0100 Subject: [PATCH 08/35] =?UTF-8?q?Answer=20prose=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=203=20=F0=9F=9F=A1=20(1=20misread);=20drop=20the?= =?UTF-8?q?=20flags=20a=20do-epic=20worker=20never=20passes,=20and=20rewor?= =?UTF-8?q?d=20the=20added=20sentences?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- bin/forge/pulls.py | 2 +- skills/larv-review/standards/prose.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 592eff7f..a9ed27f9 100644 --- a/README.md +++ b/README.md @@ -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. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. Where the pull request meanwhile conflicts with the default branch, or is behind it where GitHub's branch protection requires an up-to-date branch, the chunk resumes and brings the branch level 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. 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. 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:`, 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. diff --git a/bin/forge/pulls.py b/bin/forge/pulls.py index de0b4ccc..7de3e4ca 100644 --- a/bin/forge/pulls.py +++ b/bin/forge/pulls.py @@ -52,7 +52,7 @@ 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. It is also false for the seconds Gitea checks for conflicts after a push to either branch, which reads as CONFLICTS here. + 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"]) diff --git a/skills/larv-review/standards/prose.md b/skills/larv-review/standards/prose.md index 19112d77..3f6ad0a3 100644 --- a/skills/larv-review/standards/prose.md +++ b/skills/larv-review/standards/prose.md @@ -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 anything` or `anyone`, never ` 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 of them.** Where one sentence gives a property to several named tables, fields, flags or files, 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`. +- **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`. From d954fb002628f891e0b1269c51a457bd3b638bcf Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:24:24 +0100 Subject: [PATCH 09/35] =?UTF-8?q?Answer=20security=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(0=20misread);=20keep=20a=20?= =?UTF-8?q?judge's=20evidence=20quote=20from=20running=20across=20the=20ta?= =?UTF-8?q?sk=20and=20the=20tail,=20and=20name=20the=20task=20in=20the=20s?= =?UTF-8?q?chema=20and=20the=20rejection=20message?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- bin/agent_cycle/judge.py | 8 +++++--- bin/agent_cycle/test_judge.py | 1 + bin/agent_cycle/test_run.py | 2 +- bin/loop_claude/loop/test_usage.py | 4 ++-- bin/loop_claude/loop/usage.py | 4 ++-- bin/loop_claude/test_black_box.py | 4 ++-- 6 files changed, 13 insertions(+), 10 deletions(-) diff --git a/bin/agent_cycle/judge.py b/bin/agent_cycle/judge.py index c1edb597..2243075a 100644 --- a/bin/agent_cycle/judge.py +++ b/bin/agent_cycle/judge.py @@ -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 quote runs across the join: plain() keeps it, and a quote has none. +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,7 +250,7 @@ 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) @@ -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: diff --git a/bin/agent_cycle/test_judge.py b/bin/agent_cycle/test_judge.py index 780feece..cd132525 100644 --- a/bin/agent_cycle/test_judge.py +++ b/bin/agent_cycle/test_judge.py @@ -131,6 +131,7 @@ class Verdict(unittest.TestCase): 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): diff --git a/bin/agent_cycle/test_run.py b/bin/agent_cycle/test_run.py index 99f2320a..e8be0e83 100644 --- a/bin/agent_cycle/test_run.py +++ b/bin/agent_cycle/test_run.py @@ -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): diff --git a/bin/loop_claude/loop/test_usage.py b/bin/loop_claude/loop/test_usage.py index af996f1d..1bb4148c 100644 --- a/bin/loop_claude/loop/test_usage.py +++ b/bin/loop_claude/loop/test_usage.py @@ -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), diff --git a/bin/loop_claude/loop/usage.py b/bin/loop_claude/loop/usage.py index 0b73d47f..2dd26fb9 100644 --- a/bin/loop_claude/loop/usage.py +++ b/bin/loop_claude/loop/usage.py @@ -183,8 +183,8 @@ 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; it holds an elided passage when each fragment appears in order. 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 diff --git a/bin/loop_claude/test_black_box.py b/bin/loop_claude/test_black_box.py index 020098ed..7b0d0ab8 100644 --- a/bin/loop_claude/test_black_box.py +++ b/bin/loop_claude/test_black_box.py @@ -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) From 427a2cb7c3a105489e8670b41ba493d0eb1f36a7 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:24:56 +0100 Subject: [PATCH 10/35] =?UTF-8?q?Answer=20stability=20round=202:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(0=20misread);=20no=20findin?= =?UTF-8?q?g?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 8c693ea5de78813c20fd3ee062f3a627fe38ba10 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:24:57 +0100 Subject: [PATCH 11/35] =?UTF-8?q?Answer=20product-owner=20round=202:=200?= =?UTF-8?q?=20=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(0=20misread);=20no=20fin?= =?UTF-8?q?ding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 7c178038c517aebd57316f05030b49f1d9037034 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:27:29 +0100 Subject: [PATCH 12/35] Take the scoring run's values from seat-prompts.md where the working rules hold none --- bin/larv_review/scoring_setup.py | 14 ++++++++++---- bin/larv_review/test_scoring_setup.py | 22 ++++++++++++++++++++++ todo.md | 12 +++++++++++- 3 files changed, 43 insertions(+), 5 deletions(-) diff --git a/bin/larv_review/scoring_setup.py b/bin/larv_review/scoring_setup.py index 806ef509..f36892ab 100644 --- a/bin/larv_review/scoring_setup.py +++ b/bin/larv_review/scoring_setup.py @@ -61,9 +61,13 @@ def score_bullets(skill: str) -> tuple[list[str], list[str]] | Failure: return anchors, [line.replace("**", "") for _, line in dimensions] +# The heading of the section that holds a project's values: `Scoring run`, numbered or not, or `'s values`. +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 `'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 +141,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 + # Where the working rules hold no values, this repo keeps them in seat-prompts.md: .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 diff --git a/bin/larv_review/test_scoring_setup.py b/bin/larv_review/test_scoring_setup.py index 4e3eebc9..4372eb18 100644 --- a/bin/larv_review/test_scoring_setup.py +++ b/bin/larv_review/test_scoring_setup.py @@ -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") diff --git a/todo.md b/todo.md index b00f61c3..a6d7da17 100644 --- a/todo.md +++ b/todo.md @@ -6,13 +6,14 @@ `Bar = 0.1` -`Next ID = 461` +`Next ID = 462` ## 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 | +| 461 | 0.14.0 | | defect | **Take the scoring run's project values from `seat-prompts.md` where the working-rules file holds no "Scoring run" section, so `larv-review prepare-scoring` runs in claude-config again.** | 1 | 1 | 2 | 2 | 1 | code health by 3 | 5.5 | | 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 | | 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 | @@ -91,6 +92,15 @@ Touches: - `bin/agent_cycle/test_judge.py` - `bin/judge_replay/test_judge_replay.py` +### 461. Take the scoring run's project values from `seat-prompts.md` where the working-rules file holds no "Scoring run" section, so `larv-review prepare-scoring` runs in claude-config again. + +`prepare-scoring` falls back to `skills/comprehension-panel/seat-prompts.md` → "claude-config's values" only where the working-rules file is missing. Since claude-config's project config names `docs/decisions.md` as its working rules, that file exists, holds no "Scoring run" section, and `prepare-scoring` exits 1. No chunk can then record the scoring run its merge owes. + +Touches: + +- `bin/larv_review/scoring_setup.py`: `prepare_scoring` (small) +- `bin/larv_review/test_scoring_setup.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. From 24bcb9060bae3e897be0a65a171df381dbf5d125 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:32:53 +0100 Subject: [PATCH 13/35] =?UTF-8?q?Answer=20product-owner=20round=201:=201?= =?UTF-8?q?=20=F0=9F=94=B4,=202=20=F0=9F=9F=A1=20(0=20misread);=20move=20a?= =?UTF-8?q?=20chunk's=20issue=20where=20no=20pull=20request=20carries=20it?= =?UTF-8?q?,=20wait=20for=20the=20automation's=20move,=20and=20match=20sta?= =?UTF-8?q?tuses=20in=20any=20case?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 6 ++--- bin/do_epic/config.py | 7 +++--- bin/do_epic/main.py | 44 +++++++++++++++++++++++++---------- bin/do_epic/scheduler.py | 17 ++++++++++---- bin/do_epic/test_main.py | 24 +++++++++++++++++-- bin/do_epic/test_scheduler.py | 19 ++++++++++++--- bin/do_epic/test_status.py | 4 ++-- 7 files changed, 90 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index d94373ee..365e3073 100644 --- a/README.md +++ b/README.md @@ -155,9 +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, as CI does from a pull request's merge, with two settings: - - `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", "Done"]`. 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 epic's finishing still waits until Jira counts every issue done, so the release reviews follow the deploy. - - `jira-automation-moves-issues = true` keeps do-epic from moving a finished chunk's issue: the automation does, and `jira-finish-transition` then only closes the epic. It needs `jira-unblocking-statuses`, which names the status the automation gives an issue whose pull request merged. +- `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 any 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 ` 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:`. 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 ` uses it to pick where each open issue without such a label is worked, and records the pick as a label: `repo:` 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. diff --git a/bin/do_epic/config.py b/bin/do_epic/config.py index 2740651b..adcbf33d 100644 --- a/bin/do_epic/config.py +++ b/bin/do_epic/config.py @@ -17,8 +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", "Done"]`. 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 each issue through the workflow, as from a pull request's merge. do-epic then moves no finished chunk's issue, and `jira-finish-transition` only closes the epic. It needs `jira-unblocking-statuses`, which then names the status the automation gives an issue whose pull request merged. false where left out. +- `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 any 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:`. 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 @@ -65,7 +65,6 @@ class DoEpicConfig: label_repos: LabelRepos = types.MappingProxyType({}) # The UNBLOCKING_STATUSES list; empty where the config has none. unblocking: tuple[str, ...] = () - # The AUTOMATION_MOVES switch. automation_moves: bool = False @@ -87,7 +86,7 @@ def workflow_faults(values: dict[str, object]) -> list[str]: return [ *([f"`{UNBLOCKING_STATUSES}` is {statuses!r}, not a list of the status names Jira shows, such as [\"Release Ready\", \"Done\"]"] 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 []), - # Without such a status, an issue whose pull request merged would read as open, and its chunk would start again. + # 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 []), ] diff --git a/bin/do_epic/main.py b/bin/do_epic/main.py index c1d9c71f..893d3342 100644 --- a/bin/do_epic/main.py +++ b/bin/do_epic/main.py @@ -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 @@ -249,7 +250,7 @@ def chunk_run(key: str, epic: EpicRun) -> Stop: return issue if issue and isinstance(recorded(issue, epic.config.label_repos), HumanTask): human_tasks.awaited(issue, epic.key, epic.store, epic.config.label_repos, epic.config.unblocking, tmux.Window(epic.session, key, pane), POLL_SECONDS, epic.paths.home, epic.effects) - return handed_on(key, epic) + return handed_on(key, epic, by_others=True) place = chunk_root(key, issue, epic) if isinstance(place, Stop): return place @@ -281,7 +282,7 @@ 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: @@ -423,19 +424,22 @@ 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. Where the team's automation moves issues, it leaves the chunk's issue to the automation, and the issue counts as in the first unblocking status; a split item still moves, once Jira counts each of its sub-tasks done. Its window closes as it exits.""" - automated = epic.config.automation_moves +def handed_on(key: str, epic: EpicRun, by_others: 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. by_others says someone else moves the issue where the team's automation moves issues: the automation from a chunk's pull request, or the human whose task it is. There it waits for that move (`moved_by_automation`) and moves only a split item, once Jira counts each of its sub-tasks done; a chunk without a repo has no pull request, so its issue moves to done as ever. 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 or automated 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() + if key == epic.key: + issues = epic.store.read() + elif by_others and epic.config.automation_moves: + 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, nor has the team's automation always made it, so the issue counts as moved here whatever the read says. - moved_as: dict[str, typing.Any] = {"status": epic.config.unblocking[0]} if automated else {"done": True} - issues = [dataclasses.replace(each, **moved_as) if each.key == key else each for each in issues] closed = split_items_closed(epic, issues) if isinstance(closed, Stop): return closed @@ -446,6 +450,22 @@ def handed_on(key: str, epic: EpicRun) -> Stop: return Stop(0, "") +def moved_by_automation(key: str, epic: EpicRun) -> list[EpicIssue] | Failure: + """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.""" + told = False + while True: + issues = epic.store.read() + if isinstance(issues, Failure): + return issues + 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: diff --git a/bin/do_epic/scheduler.py b/bin/do_epic/scheduler.py index f39789a7..0f5b7e8a 100644 --- a/bin/do_epic/scheduler.py +++ b/bin/do_epic/scheduler.py @@ -82,10 +82,15 @@ class Epic: return self.home / STATE / self.key +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 issue.status in unblocking or bool(tasks) and all(settled(task, by_key, unblocking) for task in tasks) + 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]: @@ -106,7 +111,7 @@ def held_up(issues: list[EpicIssue], unblocking: tuple[str, ...] = ()) -> dict[s 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, and waits only to be done.""" + """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, unblocking) found: list[Chunk] = [] @@ -114,8 +119,8 @@ def chunks(issues: list[EpicIssue], team: LabelRepos, unblocking: tuple[str, ... for issue in issues: if issue.done: continue - if issue.status in unblocking: - waits.append(Waits(issue.key, f"its work is merged: it is {issue.status}, and the epic's finishing waits until Jira counts it done")) + 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): @@ -140,7 +145,9 @@ 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 "" - until = f", until {'it' if len(blocking) == 1 else 'each'} is {listed(unblocking, 'or')}" if unblocking else "" + 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) diff --git a/bin/do_epic/test_main.py b/bin/do_epic/test_main.py index e3d5a871..3eb2423d 100644 --- a/bin/do_epic/test_main.py +++ b/bin/do_epic/test_main.py @@ -449,7 +449,7 @@ 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_moves_none_and_starts_what_it_blocks(self) -> None: + 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",))]) @@ -457,7 +457,8 @@ class AChunksRun(DoEpicTest): 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) - self.assertEqual({each.key: (each.status, each.done) for each in store.issues}, dict.fromkeys(("ABC-20", "ABC-23", "ABC-21", "ABC-22"), ("To Do", False))) + # 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: @@ -774,6 +775,25 @@ 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"]\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) + if len(slept) == 2: + 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]), err) + 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; 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) diff --git a/bin/do_epic/test_scheduler.py b/bin/do_epic/test_scheduler.py index fa1a554c..ff67ed4c 100644 --- a/bin/do_epic/test_scheduler.py +++ b/bin/do_epic/test_scheduler.py @@ -123,13 +123,26 @@ class WhichIssuesAreChunks(unittest.TestCase): 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 is merged: 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 or Shipped"), - Waits("ABC-24", "ABC-21 and ABC-22 block it, until each is Release Ready or Shipped"), + 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_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")]) diff --git a/bin/do_epic/test_status.py b/bin/do_epic/test_status.py index 339625e0..bddbf8cb 100644 --- a/bin/do_epic/test_status.py +++ b/bin/do_epic/test_status.py @@ -33,9 +33,9 @@ class TheStatusLines(unittest.TestCase): 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 is merged: it is Release Ready, and the epic's finishing waits until Jira counts it done", + "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", + "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: From 9caac90a62d9f44189c5f258506fc9f94351d443 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:32:53 +0100 Subject: [PATCH 14/35] =?UTF-8?q?Answer=20prose=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=202=20=F0=9F=9F=A1=20(0=20misread);=20the=20wait?= =?UTF-8?q?=20reasons=20and=20the=20settings'=20wording=20are=20fixed=20in?= =?UTF-8?q?=20the=20product-owner=20answer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From b940f902b86f1a25de3d63869124bab2926a33d7 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:35:03 +0100 Subject: [PATCH 15/35] =?UTF-8?q?Answer=20product-owner=20round=202:=200?= =?UTF-8?q?=20=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(0=20misread);=20read=20t?= =?UTF-8?q?he=20epic=20again=20where=20a=20read=20fails=20during=20the=20w?= =?UTF-8?q?ait,=20and=20reword=20two=20lines?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- bin/do_epic/config.py | 4 ++-- bin/do_epic/main.py | 14 +++++++++----- bin/do_epic/test_do_epic.py | 2 +- bin/do_epic/test_main.py | 6 ++++-- 5 files changed, 17 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 365e3073..54bc475c 100644 --- a/README.md +++ b/README.md @@ -156,7 +156,7 @@ The last line prints each setting's path once the config is complete. - `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 any 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 ` then, to start them. + - `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 ` 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:`. 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 ` uses it to pick where each open issue without such a label is worked, and records the pick as a label: `repo:` 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. diff --git a/bin/do_epic/config.py b/bin/do_epic/config.py index adcbf33d..e1f5f64d 100644 --- a/bin/do_epic/config.py +++ b/bin/do_epic/config.py @@ -17,7 +17,7 @@ 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 any 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-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:`. 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.""" @@ -84,7 +84,7 @@ 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\", \"Done\"]"] if not (isinstance(statuses, list) and statuses and all(name_of(status) for status in statuses)) else []), + *([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 []), diff --git a/bin/do_epic/main.py b/bin/do_epic/main.py index 893d3342..87ba1d12 100644 --- a/bin/do_epic/main.py +++ b/bin/do_epic/main.py @@ -428,7 +428,7 @@ def handed_on(key: str, epic: EpicRun, by_others: 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. by_others says someone else moves the issue where the team's automation moves issues: the automation from a chunk's pull request, or the human whose task it is. There it waits for that move (`moved_by_automation`) and moves only a split item, once Jira counts each of its sub-tasks done; a chunk without a repo has no pull request, so its issue moves to done as ever. Its window closes as it exits.""" # The epic's finishing has no issue to move: the epic is closed by `--close-epic`. if key == epic.key: - issues = epic.store.read() + issues: list[EpicIssue] | Failure = epic.store.read() elif by_others and epic.config.automation_moves: issues = moved_by_automation(key, epic) else: @@ -450,13 +450,17 @@ def handed_on(key: str, epic: EpicRun, by_others: bool = False) -> Stop: return Stop(0, "") -def moved_by_automation(key: str, epic: EpicRun) -> list[EpicIssue] | Failure: - """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.""" - told = False +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): - return issues + 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 diff --git a/bin/do_epic/test_do_epic.py b/bin/do_epic/test_do_epic.py index 78e69852..fbefa73f 100644 --- a/bin/do_epic/test_do_epic.py +++ b/bin/do_epic/test_do_epic.py @@ -93,7 +93,7 @@ class ConfigTest(unittest.TestCase): 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", "Done"]', 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') diff --git a/bin/do_epic/test_main.py b/bin/do_epic/test_main.py index 3eb2423d..b1938ddb 100644 --- a/bin/do_epic/test_main.py +++ b/bin/do_epic/test_main.py @@ -785,11 +785,13 @@ class AChunkWhosePullRequestWaitsOnAGate(DoEpicTest): def sleep(seconds: float) -> None: slept.append(seconds) - if len(slept) == 2: + store.fails = "Jira answered 503" if len(slept) == 1 else None + if len(slept) == 3: 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]), err) + self.assertEqual((code, slept), (0, [60, 60, 60]), err) + self.assertIn("cannot read the epic, so cannot tell whether ABC-20 has moved; trying again every 60 seconds: Jira answered 503\n", 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; move it in Jira if the automation doesn't\n"), 1, out) self.assertIn("the chunk finished; started ABC-22\n", out) From 1845d8ff3788ebe14a5d0b526960235379360192 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:36:14 +0100 Subject: [PATCH 16/35] =?UTF-8?q?Answer=20prose=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=204=20=F0=9F=9F=A1=20(0=20misread);=20say=20that?= =?UTF-8?q?=20the=20task=20and=20the=20transcript=20are=20searched,=20and?= =?UTF-8?q?=20where=20a=20quote=20may=20not=20run=20across=20them?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- bin/agent_cycle/judge.py | 10 +++++----- bin/agent_cycle/test_judge.py | 2 +- bin/judge_replay/archived_prompt.py | 2 +- bin/loop_claude/loop/usage.py | 3 ++- 4 files changed, 9 insertions(+), 8 deletions(-) diff --git a/bin/agent_cycle/judge.py b/bin/agent_cycle/judge.py index 2243075a..a80eae93 100644 --- a/bin/agent_cycle/judge.py +++ b/bin/agent_cycle/judge.py @@ -74,7 +74,7 @@ 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 quote runs across the join: plain() keeps it, and a quote has none. +# 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" @@ -257,13 +257,13 @@ def quotes_checked(verdict: Verdict, grounds: Grounds) -> Verdict | Failure: 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) diff --git a/bin/agent_cycle/test_judge.py b/bin/agent_cycle/test_judge.py index cd132525..2239d010 100644 --- a/bin/agent_cycle/test_judge.py +++ b/bin/agent_cycle/test_judge.py @@ -124,7 +124,7 @@ 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()) diff --git a/bin/judge_replay/archived_prompt.py b/bin/judge_replay/archived_prompt.py index b6d40a3b..af1fccf4 100644 --- a/bin/judge_replay/archived_prompt.py +++ b/bin/judge_replay/archived_prompt.py @@ -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) diff --git a/bin/loop_claude/loop/usage.py b/bin/loop_claude/loop/usage.py index 2dd26fb9..46e4d7ec 100644 --- a/bin/loop_claude/loop/usage.py +++ b/bin/loop_claude/loop/usage.py @@ -184,7 +184,8 @@ Exit 1, saying why, when: 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 that - neither the task nor the transcript holds; it holds an elided passage when each fragment appears in order. + 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 From f9959d25c5fe97ce2301a0cea61d8a5e15ae7ca7 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:40:00 +0100 Subject: [PATCH 17/35] Test that an unblocking status frees a human's task and the issue it blocks --- bin/do_epic/test_human_tasks.py | 16 ++++++++++++++++ bin/do_epic/test_scheduler.py | 4 ++++ 2 files changed, 20 insertions(+) diff --git a/bin/do_epic/test_human_tasks.py b/bin/do_epic/test_human_tasks.py index 631a3851..b24c06be 100644 --- a/bin/do_epic/test_human_tasks.py +++ b/bin/do_epic/test_human_tasks.py @@ -49,6 +49,22 @@ class AHumanTaskThatBlocksAnIssue(DoEpicTest): self.slept = slept return self.run_main(["--chunk", "ABC-19", "ABC-12"], fake, MODELS) + def test_a_task_the_human_moves_to_an_unblocking_status_no_longer_holds_up_an_issue(self) -> None: + with (self.home / ".claude-projects" / "do-epic" / "config.toml").open("a") as config: + config.write('jira-unblocking-statuses = ["Release Ready"]\n') + 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("ABC-19", status="Release Ready") + 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("the chunk finished; started ABC-21\n", out) + 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) diff --git a/bin/do_epic/test_scheduler.py b/bin/do_epic/test_scheduler.py index ff67ed4c..9c656e20 100644 --- a/bin/do_epic/test_scheduler.py +++ b/bin/do_epic/test_scheduler.py @@ -130,6 +130,10 @@ class WhichIssuesAreChunks(unittest.TestCase): 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")])) From 7605094623315a3a7cb8d6f0683e9f0d159ad1ef Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:52:56 +0100 Subject: [PATCH 18/35] =?UTF-8?q?Answer=20security=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(0=20misread);=20no=20findin?= =?UTF-8?q?g?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 4c109b341166b4631600ba5f6cf9c9465dd5949b Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:55:34 +0100 Subject: [PATCH 19/35] =?UTF-8?q?Answer=20stability=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=202=20=F0=9F=9F=A1=20(0=20misread);=20test=20the?= =?UTF-8?q?=20unreadable=20seat-prompts.md=20and=20correct=20prepare-scori?= =?UTF-8?q?ng's=20help?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- bin/larv_review/main.py | 5 +++-- bin/larv_review/test_scoring_setup.py | 8 ++++++++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/bin/larv_review/main.py b/bin/larv_review/main.py index 00e6a1ee..d260a28f 100644 --- a/bin/larv_review/main.py +++ b/bin/larv_review/main.py @@ -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. diff --git a/bin/larv_review/test_scoring_setup.py b/bin/larv_review/test_scoring_setup.py index 4372eb18..07dbee3b 100644 --- a/bin/larv_review/test_scoring_setup.py +++ b/bin/larv_review/test_scoring_setup.py @@ -203,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__": From a357cc7b187fe42fbfba5b22244711d3f3380376 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 22:55:34 +0100 Subject: [PATCH 20/35] =?UTF-8?q?Answer=20prose=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=201=20=F0=9F=9F=A1=20(0=20misread);=20state=20the?= =?UTF-8?q?=20repo's=20fact=20in=20the=20comment=20and=20drop=20the=20one?= =?UTF-8?q?=20that=20restates=20the=20pattern?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- bin/larv_review/scoring_setup.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/bin/larv_review/scoring_setup.py b/bin/larv_review/scoring_setup.py index f36892ab..38cdcdf1 100644 --- a/bin/larv_review/scoring_setup.py +++ b/bin/larv_review/scoring_setup.py @@ -61,7 +61,6 @@ def score_bullets(skill: str) -> tuple[list[str], list[str]] | Failure: return anchors, [line.replace("**", "") for _, line in dimensions] -# The heading of the section that holds a project's values: `Scoring run`, numbered or not, or `'s values`. VALUES_HEADING = r"(\d+\.\s+)?Scoring run|.+'s values" @@ -145,7 +144,7 @@ def prepare_scoring(worktree: str, home: pathlib.Path, run: Git = git) -> str | rules = read(source) if source.is_file() else "" if isinstance(rules, Failure): return rules - # Where the working rules hold no values, this repo keeps them in seat-prompts.md: .claude/rules/this-repo-keeps-no-agents-md.md. + # 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): From daee3c671f75a312f7ffd317e36a316e576696a8 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:05:10 +0100 Subject: [PATCH 21/35] Test the human's task under the automation switch, a repeated failed read and the list of statuses in the wait line --- bin/do_epic/test_human_tasks.py | 17 +++++++++++++++-- bin/do_epic/test_main.py | 12 ++++++------ 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/bin/do_epic/test_human_tasks.py b/bin/do_epic/test_human_tasks.py index b24c06be..db8619cf 100644 --- a/bin/do_epic/test_human_tasks.py +++ b/bin/do_epic/test_human_tasks.py @@ -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,9 +50,10 @@ class AHumanTaskThatBlocksAnIssue(DoEpicTest): self.slept = slept return self.run_main(["--chunk", "ABC-19", "ABC-12"], fake, MODELS) - def test_a_task_the_human_moves_to_an_unblocking_status_no_longer_holds_up_an_issue(self) -> None: + def moved_to_an_unblocking_status(self, switch: str) -> bool: + """Whether Jira counts the task done after its window's run, where the human moved it to an unblocking status and the config ends with switch.""" with (self.home / ".claude-projects" / "do-epic" / "config.toml").open("a") as config: - config.write('jira-unblocking-statuses = ["Release Ready"]\n') + config.write('jira-unblocking-statuses = ["Release Ready"]\n' + switch) fake = FakeEffects(git=UNREAD, windows=WINDOW) slept: list[int] = [] @@ -64,6 +66,17 @@ class AHumanTaskThatBlocksAnIssue(DoEpicTest): code, out, err = self.run_main(["--chunk", "ABC-19", "ABC-12"], fake, MODELS) self.assertEqual((code, err, slept), (0, "", [60, 60])) self.assertIn("the chunk finished; started ABC-21\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_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) diff --git a/bin/do_epic/test_main.py b/bin/do_epic/test_main.py index b1938ddb..8aa0e861 100644 --- a/bin/do_epic/test_main.py +++ b/bin/do_epic/test_main.py @@ -776,7 +776,7 @@ class AChunkWhosePullRequestWaitsOnAGate(DoEpicTest): 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"]\njira-automation-moves-issues = true\n', encoding="utf-8") + (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="")] @@ -785,15 +785,15 @@ class AChunkWhosePullRequestWaitsOnAGate(DoEpicTest): def sleep(seconds: float) -> None: slept.append(seconds) - store.fails = "Jira answered 503" if len(slept) == 1 else None - if len(slept) == 3: + 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]), err) - self.assertIn("cannot read the epic, so cannot tell whether ABC-20 has moved; trying again every 60 seconds: Jira answered 503\n", out) + 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; move it in Jira if the automation doesn't\n"), 1, out) + 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: From 29b1be3fd740969be1faa1d3697e88b34228a52e Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:25:38 +0100 Subject: [PATCH 22/35] Test how grounds_of splits an archived prompt, to kill the mutants that survived on its changed lines --- bin/judge_replay/test_judge_replay.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/bin/judge_replay/test_judge_replay.py b/bin/judge_replay/test_judge_replay.py index 90a26fc4..fd037710 100644 --- a/bin/judge_replay/test_judge_replay.py +++ b/bin/judge_replay/test_judge_replay.py @@ -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)) From 04852c3417bafd3a0812bd31b47b6114f3a92c8d Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:33:46 +0100 Subject: [PATCH 23/35] Record the comprehension check: Navigation 7.00, Locality 6.00, Shape 6.13, Self-sufficiency 6.00, Overall 6.38 --- docs/comprehension-history.md | 60 +++++++++++++++++++++++++++++++++++ todo.md | 36 +++++++++++---------- 2 files changed, 80 insertions(+), 16 deletions(-) diff --git a/docs/comprehension-history.md b/docs/comprehension-history.md index 35aafb66..e828902c 100644 --- a/docs/comprehension-history.md +++ b/docs/comprehension-history.md @@ -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 diff --git a/todo.md b/todo.md index a6d7da17..65bd635c 100644 --- a/todo.md +++ b/todo.md @@ -30,7 +30,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 ` 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 | @@ -307,26 +307,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. From 2efe9145219ce56f9e4969bfe1f27c1808c2138d Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:34:00 +0100 Subject: [PATCH 24/35] Finish item 461 in the plan --- CHANGELOG.md | 4 ++++ todo.md | 10 ---------- 2 files changed, 4 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d9b95cf0..a709e4be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## Unreleased + +- `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. diff --git a/todo.md b/todo.md index 65bd635c..2083d60d 100644 --- a/todo.md +++ b/todo.md @@ -13,7 +13,6 @@ | 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 | -| 461 | 0.14.0 | | defect | **Take the scoring run's project values from `seat-prompts.md` where the working-rules file holds no "Scoring run" section, so `larv-review prepare-scoring` runs in claude-config again.** | 1 | 1 | 2 | 2 | 1 | code health by 3 | 5.5 | | 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 | | 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 | @@ -92,15 +91,6 @@ Touches: - `bin/agent_cycle/test_judge.py` - `bin/judge_replay/test_judge_replay.py` -### 461. Take the scoring run's project values from `seat-prompts.md` where the working-rules file holds no "Scoring run" section, so `larv-review prepare-scoring` runs in claude-config again. - -`prepare-scoring` falls back to `skills/comprehension-panel/seat-prompts.md` → "claude-config's values" only where the working-rules file is missing. Since claude-config's project config names `docs/decisions.md` as its working rules, that file exists, holds no "Scoring run" section, and `prepare-scoring` exits 1. No chunk can then record the scoring run its merge owes. - -Touches: - -- `bin/larv_review/scoring_setup.py`: `prepare_scoring` (small) -- `bin/larv_review/test_scoring_setup.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. From b5597754557efda2bae096ee9fc7ac7f5e82e5ac Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:39:46 +0100 Subject: [PATCH 25/35] Finish item 458 in the plan --- CHANGELOG.md | 1 + todo.md | 17 ----------------- 2 files changed, 1 insertion(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a709e4be..cbe07aae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased +- `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 diff --git a/todo.md b/todo.md index 2083d60d..8e36eda7 100644 --- a/todo.md +++ b/todo.md @@ -15,7 +15,6 @@ | 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 | | 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 --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 | @@ -132,22 +131,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. From 69cf298597c140b9c70d98ad728a2a8321c2d1b1 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:39:46 +0100 Subject: [PATCH 26/35] Finish item 459 in the plan --- CHANGELOG.md | 1 + todo.md | 8 -------- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cbe07aae..0cea3ec0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased +- 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. diff --git a/todo.md b/todo.md index 8e36eda7..cc5ead8e 100644 --- a/todo.md +++ b/todo.md @@ -18,7 +18,6 @@ | 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 --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 | | 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 | @@ -186,13 +185,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. From 3cce40437ef392f76c44aaf612077af5b934f466 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:39:54 +0100 Subject: [PATCH 27/35] Let prepare-scoring read claude-config's scoring-run values from seat-prompts.md where docs/decisions.md holds none --- bin/larv_review/scoring_setup.py | 9 +++++---- bin/larv_review/test_scoring_setup.py | 11 +++++++++++ 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/bin/larv_review/scoring_setup.py b/bin/larv_review/scoring_setup.py index 806ef509..2e7b77ab 100644 --- a/bin/larv_review/scoring_setup.py +++ b/bin/larv_review/scoring_setup.py @@ -137,17 +137,18 @@ 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 + values = project_values(rules, source.name) + # Where the working rules hold no values, as with AGENTS.md missing or this repo's decisions.md head, this repo keeps them in seat-prompts.md: .claude/rules/this-repo-keeps-no-agents-md.md. + if isinstance(values, Failure) and (own := pathlib.Path(worktree) / "skills" / "comprehension-panel" / "seat-prompts.md").is_file(): + own_text = read(own) + values = own_text if isinstance(own_text, Failure) else project_values(own_text, own.name) skill = read(PANEL / "SKILL.md") if isinstance(skill, Failure): return skill - values = project_values(rules, source.name) if isinstance(values, Failure): return values parts = prompt_parts() diff --git a/bin/larv_review/test_scoring_setup.py b/bin/larv_review/test_scoring_setup.py index 4e3eebc9..34561f3f 100644 --- a/bin/larv_review/test_scoring_setup.py +++ b/bin/larv_review/test_scoring_setup.py @@ -157,6 +157,17 @@ class PrepareScoring(unittest.TestCase): self.assertIn("Your background: ~2 years in Go,", junior) self.assertIn("every non-test tracked file: `bin/**`, `AGENTS.md` and `README.md`. Do NOT open plan/todo.md, docs/decisions.md or docs/reading-cost.md (the plan, the decision log and past chunks' reading cost), nor any review output.", junior) + def test_takes_the_values_from_seat_prompts_where_the_working_rules_hold_none_and_the_repo_keeps_them_there(self): + self.commit("# Working rules, with no values\n") + self.assertIsInstance(failed := self.prepare(), Failure, failed) + panel = self.checkout / "skills" / "comprehension-panel" + panel.mkdir(parents=True) + (panel / "seat-prompts.md").write_text("# Seats\n\n## The repo'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() + ran = self.prepare() + assert isinstance(ran, str), ran + self.assertIn("Your background: ~2 years in Go,", pathlib.Path(ran.splitlines()[2]).read_text()) + def test_forbids_any_record_of_a_past_panel_where_the_config_puts_every_record_outside_the_checkout(self): self.config.write_text(self.config.read_text().replace('"checkout:', '"folder:').replace('"folder:README.md"', '"checkout:README.md"')) (self.config.parent / "AGENTS.md").write_text("# A\n\n## Scoring run\n\n- Language: Go\n- Kind: a CLI\n- Domain: parsing\n- Domain docs: the spec\n- 3am question: the parse hangs\n") From 5108ab97b9fe7c3b070781c6cb4f250c5688c2c2 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:46:34 +0100 Subject: [PATCH 28/35] File item 462: run under mutate-changes the tests mutmut's copy leaves out --- todo.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/todo.md b/todo.md index cc5ead8e..dc0ddc99 100644 --- a/todo.md +++ b/todo.md @@ -6,7 +6,7 @@ `Bar = 0.1` -`Next ID = 462` +`Next ID = 463` ## Items @@ -20,6 +20,7 @@ | 450 | 0.14.0 | | | **Add `do-epic --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 | | 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 | @@ -214,6 +215,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. From 535ad7fd6a809435103a858c115017806e3d5b3b Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:54:55 +0100 Subject: [PATCH 29/35] =?UTF-8?q?Answer=20stability=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=201=20=F0=9F=9F=A1=20(1=20misread);=20leave=20a?= =?UTF-8?q?=20human's=20task=20unmoved=20and=20unawaited=20where=20the=20t?= =?UTF-8?q?eam's=20automation=20moves=20issues?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- bin/do_epic/main.py | 13 +++++++------ bin/do_epic/test_human_tasks.py | 11 +++++++---- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/bin/do_epic/main.py b/bin/do_epic/main.py index 87ba1d12..96c7dcc1 100644 --- a/bin/do_epic/main.py +++ b/bin/do_epic/main.py @@ -250,7 +250,7 @@ def chunk_run(key: str, epic: EpicRun) -> Stop: return issue if issue and isinstance(recorded(issue, epic.config.label_repos), HumanTask): human_tasks.awaited(issue, epic.key, epic.store, epic.config.label_repos, epic.config.unblocking, tmux.Window(epic.session, key, pane), POLL_SECONDS, epic.paths.home, epic.effects) - return handed_on(key, epic, by_others=True) + return handed_on(key, epic, humans=True) place = chunk_root(key, issue, epic) if isinstance(place, Stop): return place @@ -424,12 +424,13 @@ def folder_made(root: str) -> Failure | None: return None -def handed_on(key: str, epic: EpicRun, by_others: 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. by_others says someone else moves the issue where the team's automation moves issues: the automation from a chunk's pull request, or the human whose task it is. There it waits for that move (`moved_by_automation`) and moves only a split item, once Jira counts each of its sub-tasks done; a chunk without a repo has no pull request, so its issue moves to done as ever. Its window closes as it exits.""" - # The epic's finishing has no issue to move: the epic is closed by `--close-epic`. - if key == epic.key: +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 by_others and epic.config.automation_moves: + elif in_repo and automated: issues = moved_by_automation(key, epic) else: moved = epic.store.finish_issue(key) diff --git a/bin/do_epic/test_human_tasks.py b/bin/do_epic/test_human_tasks.py index db8619cf..29050405 100644 --- a/bin/do_epic/test_human_tasks.py +++ b/bin/do_epic/test_human_tasks.py @@ -50,8 +50,8 @@ 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) -> bool: - """Whether Jira counts the task done after its window's run, where the human moved it to an unblocking status and the config ends with switch.""" + 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) @@ -61,11 +61,11 @@ class AHumanTaskThatBlocksAnIssue(DoEpicTest): slept.append(seconds) self.assertLess(len(slept), 5, "the window still waits") if len(slept) == 2: - self.epic.change("ABC-19", status="Release Ready") + 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("the chunk finished; started ABC-21\n", out) + 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: @@ -74,6 +74,9 @@ class AHumanTaskThatBlocksAnIssue(DoEpicTest): 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"]) From ecc69835b8eaff802c430f4f730d87f48ee2efa5 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Thu, 19 Nov 2026 23:59:38 +0100 Subject: [PATCH 30/35] File item 463: show the judge the transcript's tail whatever the size of the records --- todo.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/todo.md b/todo.md index dc0ddc99..2b95b9b9 100644 --- a/todo.md +++ b/todo.md @@ -6,13 +6,14 @@ `Bar = 0.1` -`Next ID = 463` +`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 | +| 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 | | 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 | | 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 | | 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 | @@ -90,6 +91,20 @@ Touches: - `bin/agent_cycle/test_judge.py` - `bin/judge_replay/test_judge_replay.py` +### 463. Show the judge the transcript's tail whatever the size of the records. + +`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. + +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`: `JUDGE_PROMPT_CHARS` (small), `judge_prompt` (small) +- `bin/agent_cycle/test_judge.py`: `JudgePrompt` + ### 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. From afc51efb1b8d1d2888949f930e2bc2d536f25ef6 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Fri, 20 Nov 2026 00:01:03 +0100 Subject: [PATCH 31/35] =?UTF-8?q?Answer=20stability=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(0=20misread);=20decline=20t?= =?UTF-8?q?he=20=F0=9F=9F=A2=20on=20a=20NUL=20in=20the=20evidence,=20which?= =?UTF-8?q?=20the=20judge=20does=20not=20write?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 04c67d958e1c4e93b6a008f03adbbf94f6e14e5a Mon Sep 17 00:00:00 2001 From: Lilleman Date: Fri, 20 Nov 2026 00:02:03 +0100 Subject: [PATCH 32/35] =?UTF-8?q?Answer=20stability=20round=202:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=200=20=F0=9F=9F=A1=20(0=20misread);=20tests=20and?= =?UTF-8?q?=20mutants=20clean=20at=203cce4043?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 6fda959b52c69688dfec02a69d953c8aa4e351f7 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Fri, 20 Nov 2026 00:03:18 +0100 Subject: [PATCH 33/35] Parenthesize the condition under which do-epic only reads an issue --- bin/do_epic/main.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bin/do_epic/main.py b/bin/do_epic/main.py index 0e8363fa..29f75396 100644 --- a/bin/do_epic/main.py +++ b/bin/do_epic/main.py @@ -432,7 +432,7 @@ def handed_on(key: str, epic: EpicRun, in_repo: bool = False, humans: bool = Fal """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: + 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) From 4586bfcbea69909abfb9c434047d58522be85e2f Mon Sep 17 00:00:00 2001 From: Lilleman Date: Fri, 20 Nov 2026 00:04:15 +0100 Subject: [PATCH 34/35] Finish item 452 in the plan --- CHANGELOG.md | 1 + todo.md | 24 ------------------------ 2 files changed, 1 insertion(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0cea3ec0..3febc411 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## 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. diff --git a/todo.md b/todo.md index 2b95b9b9..300dca3d 100644 --- a/todo.md +++ b/todo.md @@ -14,7 +14,6 @@ |---|---|---|---|---|---|---|---|---|---|---|---| | 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 | | 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 | -| 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 | | 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 | | 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 | @@ -105,29 +104,6 @@ Touches: - `bin/agent_cycle/judge.py`: `JUDGE_PROMPT_CHARS` (small), `judge_prompt` (small) - `bin/agent_cycle/test_judge.py`: `JudgePrompt` -### 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) - ### 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. do-epic writes its own spelling into a team's Jira: a pick as `repo:core-4` and a sub-task's summary as `[core-4] `. A team with its own convention, such as TW's label `core-4` and summary `core-4: Bygg …` with a capital after the colon, then finds two labels on each issue and summaries in a shape its board doesn't use. Goal 1.6 asks the loop to fit the tracker's conventions, not change them. From 6e221493347ef987d58fc783e2c383f3dc218060 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Fri, 20 Nov 2026 00:10:43 +0100 Subject: [PATCH 35/35] Finish item 460 in the plan --- todo.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/todo.md b/todo.md index 300dca3d..aa6f4f4a 100644 --- a/todo.md +++ b/todo.md @@ -12,7 +12,6 @@ | 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 | | 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 | | 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 | @@ -78,18 +77,6 @@ ## 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. - -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. - -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". - -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` - ### 463. Show the judge the transcript's tail whatever the size of the records. `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: