Answer prose round 1: 1 🔴, 6 🟡 (0 misread); reword the help, comments, docstrings and the decision, and read a Gitea draft in the commits before

This commit is contained in:
2026-11-18 23:55:19 +01:00
parent 7dec775add
commit d49831c387
8 changed files with 20 additions and 20 deletions
+1 -1
View File
@@ -178,7 +178,7 @@ It renames `## Unreleased` in `CHANGELOG.md` to the version and merges that thro
Install puts only `loop-claude` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`. The tools are listed in alphabetical order, and the packages under `bin/` follow under their own heading.
- `chunk-pr open|sync|ready|merge|clean` opens a chunk's pull request as a draft, brings its branch level with origin's default branch, marks it ready and merges it once its checks pass, with `gh` on a GitHub origin and `tea` elsewhere. The chunks of one project merge one at a time: in its turn, `merge` brings the branch level again, finishes the plan items its `--finish` flags name, and waits for the checks; under do-epic it fails at once where the pull request then awaits an approval, since do-epic parks the chunk; once the pull request is merged, `clean` removes the chunk's worktree and branch and fast-forwards the main checkout. `chunk-pr --help` states the steps.
- `chunk-pr open|sync|ready|merge|clean` opens a chunk's pull request as a draft, brings its branch level with origin's default branch, marks it ready and merges it once its checks pass, with `gh` on a GitHub origin and `tea` elsewhere. The chunks of one project merge one at a time: in its turn, `merge` brings the branch level again, finishes the plan items its `--finish` flags name, and waits for the checks; once the pull request is merged, `clean` removes the chunk's worktree and branch and fast-forwards the main checkout. `chunk-pr --help` states the steps.
- `chunk-preflight` finds the mechanical facts a chunk starts from, and with `--worktree` makes its worktree; `loop-claude` runs it with `--worktree` before it routes each chunk, and `chunk-preflight --help` lists the facts.
- `command-patterns [<version>] [--calls <file>]` prints a table of the shell command patterns a release's archived chunks ran, such as `tea pr create`, for an audit of the release, and with `--calls <file>` saves each call as a JSON line; `command-patterns --help` states the columns and the line's keys.
- `compress-archives` gzips each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them; Install's crontab line runs it daily.
+1 -1
View File
@@ -146,7 +146,7 @@ def mark(window: Window, waits: bool, run: Tmux) -> None:
def park(window: Window, on: str, run: Tmux) -> None:
"""Shows window's chunk as parked while its pull request awaits on, such as `an approval`: the name says so, and no checkout counts a window so named as a running chunk."""
"""Shows window's chunk as parked. on is what the chunk awaits, such as `an approval` or `a slot`: the name says so, and no checkout counts a window so named as a running chunk."""
run(["rename-window", "-t", window.pane, window.name + PARKED + on])
+1 -1
View File
@@ -31,7 +31,7 @@ def fresh(task: str, premises: str, route: Route, project: ProjectRung | None, f
WORKER = prompts.worker_prompts(DRIVER, fresh, "")
# What a worker does with a reviewer's feedback, as the decision asks (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
FEEDBACK = 'Where a reviewer left feedback, fix what is reasonable and push it, answer the rest in its thread, and change the setup so review would have caught it (~/.claude/CLAUDE.md → "Working loop", "Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first"). Then merge the pull request as before.'
FEEDBACK = 'Where a reviewer left feedback, fix what is reasonable and push the fix, answer each other comment in its thread, and change the setup so our review would have caught the finding (~/.claude/CLAUDE.md → "Working loop", "Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first"). Then merge the pull request as before.'
def unparked(news: str) -> WorkerPrompts:
+2 -2
View File
@@ -1,6 +1,6 @@
"""What the pull request of a do-epic chunk waits on, read once from its forge (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
A gate is something only time or a person passes: checks that still run, an approval a reviewer has yet to give, or the new review of a reviewer whose requested changes the worker answered. While a chunk's pull request waits on one, its worker has nothing to do, so do-epic parks the chunk (`parked`). Anything else is news the worker acts on."""
A gate is something only time or a person passes: checks that still run, an approval a reviewer has yet to give, or the new review of a reviewer whose requested changes the worker answered. While a chunk's pull request waits on one, its worker doesn't have anything to do, so do-epic parks the chunk (`parked`). Anything else is news the worker acts on."""
import dataclasses
import json
import typing
@@ -39,7 +39,7 @@ class Open:
def gate(branch: str, checkout: str, at: typing.Callable[[str], Run]) -> Gate | Open | Failure:
"""What the chunk on branch waits on, in a worktree of checkout; at gives the runner of commands in a folder. A Failure where git or the forge cannot be read, which says nothing about the gate.
"""What the chunk on branch waits on, in a worktree of checkout; at gives the runner of commands in a folder. 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 (`answered`); from then on the pull request awaits a new review.
"""
+9 -8
View File
@@ -46,14 +46,15 @@ An open issue of the epic runs as a chunk once it has a label and no issue block
The label names the issue's repo, or says the work changes no repo.
As many run at once as the epic's description allows with a line such as `**Max parallel chunks:** 2`, one where it has none.
A repo takes as many chunks as its `parallel-chunks`, and none while loop-claude runs chunks in it.
A chunk whose pull request waits on its checks or on an approval is parked: it frees its place for the next
chunk, its window's name says what it awaits, and it goes on once the checks pass, the approval comes or a
reviewer comments. A parked chunk survives a reboot: run do-epic <EPIC-KEY> again to go on polling.
A chunk whose worker ends its run while its pull request waits on its checks, an approval or a new review
is parked: it frees its place for the next chunk, and its window's name says what it awaits. Its worker goes
on once the checks pass, the approval comes or a reviewer comments, and a place is free; until one is, the
name says `awaits a slot`. A parked chunk survives a reboot: run do-epic <EPIC-KEY> again to go on polling.
--status starts no chunk: it prints each open issue with whether its chunk runs, or why it waits.
The Jira site and its credentials are set in ~/.claude-projects/do-epic/config.toml."""
# Under the home folder, where a chunk's cycles are archived, a folder per epic. It is not loop-claude's archive, since that archive's readers, such as judge-replay and the routing figures, read loop-claude's prompts.
ARCHIVE = ".claude/do-epic-transcripts"
# The flag that prints what each open issue does. lilleman named it when planning release 0.12.0 (the decision's "Long gates").
# The flag that prints what each open issue does.
STATUS_FLAG = "--status"
# How often a parked chunk reads its pull request's gate: a reviewer answers in hours, and each read is three or four calls to the forge.
POLL_SECONDS = 60
@@ -122,7 +123,7 @@ def run(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher:
def status_printed(epic: EpicRun) -> Stop:
"""What `do-epic <EPIC-KEY> --status` does: prints a line per open issue, and starts nothing."""
"""What `do-epic <EPIC-KEY> --status` does: prints a line per open issue, and doesn't start anything."""
issues = epic.store.read()
lines = issues if isinstance(issues, Failure) else scheduler.status(epic.key, epic.paths.home, issues, 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")
@@ -235,9 +236,9 @@ def chunk_run(key: str, epic: EpicRun) -> Stop:
def parked_through(repo: str, loop: Loop, epic: EpicRun, starts: bool) -> str | Stop:
"""Keeps the chunk in loop's window, which changes repo, 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. starts says the window just started, where the chunk is parked only if its file says so: nothing is read from the forge for a chunk that starts afresh.
"""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. starts says the window just started, where the chunk is parked only if its file says so: the forge isn't read for a chunk that starts afresh.
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` takes it a slot, then its file is removed. So a window that ends in between finds the chunk parked when it starts again.
A chunk parks in three steps: its file is written, its window is shown as parked, and the epic's next chunks start in the slot it frees. It resumes in the reverse order: `scheduler.resume` gives it a running slot, then its file is removed. So a window that ends in between finds the chunk parked when it starts again.
"""
key, folder = loop.window.name, epic.paths.home / scheduler.STATE / epic.key
recorded_as = parked.parked_chunks(folder)
@@ -289,7 +290,7 @@ DRIVER_PARKED = f"{chunk_prompt.DRIVER} parked the chunk while"
def resumed(repo: str, loop: Loop, epic: EpicRun) -> str | None:
"""scheduler.resume for the parked chunk in loop's window, which changes repo, on the epic's cap and repos read afresh: None once it holds a running slot, else why it stays parked."""
"""scheduler.resume for the parked chunk in loop's window, whose work is in the repo called repo, on the epic's cap and repos read afresh: None once it holds a running slot, else why it stays parked."""
scheduled = scheduled_epic(epic)
if isinstance(scheduled, Failure):
return scheduled.reason
+4 -5
View File
@@ -1,6 +1,6 @@
"""Which of an epic's issues run as chunks now, each in its own window of the epic's tmux session (docs/decisions.md → `do-epic: drives one Jira epic …`).
Three limits hold a chunk back: the epic's cap of chunks at once, its repo's `parallel-chunks`, counted across every epic, and a loop-claude that runs chunks in its repo. A parked chunk (`parked`) counts toward none of them: its window only polls the forge, and `resume` takes it a slot under the same limits once its worker has something to do. do-epic checks a repo and starts a chunk in it while holding the lock loop-claude holds when it starts one (`chunk_windows.starting`), so the two never start chunks in one checkout together."""
Three limits hold a chunk back: the epic's cap of chunks at once, its repo's `parallel-chunks`, counted across every epic, and a loop-claude that runs chunks in its repo. A parked chunk (`parked`) counts toward none of them: its window only polls the forge, and `resume` gives it a running slot under the same limits once its worker has something to do. do-epic checks a repo and starts a chunk in it while holding the lock loop-claude holds when it starts one (`chunk_windows.starting`), so the two never start chunks in one checkout together."""
import dataclasses
import pathlib
import typing
@@ -149,9 +149,8 @@ def start_chunks(epic: Epic, issues: list[EpicIssue], own: str | None, run: tmux
def start_chunk(epic: Epic, chunk: Chunk, own: str | None, windows: list[tmux.Listed], run: tmux.Tmux) -> list[tmux.Listed] | str | Failure:
"""Starts chunk's window beside windows, the epic's session's, and returns the session's windows afterwards; the reason where its repo takes no chunk now, and a Failure where tmux started none. It holds the repo's lock from the check to the start. Raises OSError where that lock cannot be taken. A chunk without a repo starts in the epic's folder, as a parked chunk does, which takes no room in its repo."""
"""Starts chunk's window beside windows, the epic's session's, and returns the session's windows afterwards; the reason where its repo takes no chunk now, and a Failure where tmux started none. It holds the repo's lock from the check to the start. Raises OSError where that lock cannot be taken. A chunk without a repo starts in the epic's folder. So does a parked chunk, since it takes no room in its repo."""
session = tmux.session_name(tmux.EPIC, epic.key)
# PARKS reaches the chunk's worker, so its `chunk-pr merge` doesn't wait for an approval the parked chunk waits for.
handed = {**{name: value for name, value in epic.env.items() if name.startswith(HANDED)}, PARKS: "1"}
command = [str(epic.launcher), CHUNK_FLAG, chunk.issue, epic.key]
if chunk.repo is None:
@@ -175,7 +174,7 @@ def room_in(checkout: str, limit: int, leaving: tuple[str, str | None], home: pa
def resume(epic: Epic, repo: str, window: tmux.Window, run: tmux.Tmux) -> str | None:
"""Takes a running slot for the parked chunk in window, which changes repo and whose worker has something to do again: None once the window counts as a running chunk, else why the chunk still waits. The limits are those a starting chunk meets, checked under the same locks. The window itself never counts against them: one started again for a parked chunk, as after a reboot, isn't named as parked until its first read of the gate."""
"""Takes a running slot for the parked chunk in window, whose worker has something to do again in the repo called repo: None once the window counts as a running chunk, else why the chunk still waits. The limits are those a starting chunk meets, checked under the same locks. The window itself never counts against them: one started again for a parked chunk, as after a reboot, isn't named as parked until its first read of the gate."""
try:
with starting(epic.folder):
running = [listed for listed in tmux.listed(window.session, run) if not listed.dead and not listed.parked and listed.name != window.name]
@@ -195,7 +194,7 @@ def resume(epic: Epic, repo: str, window: tmux.Window, run: tmux.Tmux) -> str |
def status(key: str, home: pathlib.Path, issues: list[EpicIssue], 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 why it waits. It starts nothing and checks no limit, so a chunk that has yet to start is told apart only from one that stopped."""
"""A line per open issue of the epic called key, in the tracker's rank order: that its chunk runs, or why it waits. It doesn't start anything and checks no limit, so the line of a chunk that has yet to start doesn't say which limit holds it back."""
found, waits = chunks(issues)
parked = parked_chunks(home / STATE / key)
if isinstance(parked, Failure):
+1 -1
View File
@@ -76,7 +76,7 @@ class Pending:
def checks_now(forge: Forge, number: str, head: str, required: set[str], run: Run, settled: bool = True) -> Pending | Failure | None:
"""The checks on pull request number, whose head commit is head, read once: None where every one passed, Pending while one still runs, a CheckFailed where one failed, and any other Failure where the forge cannot be read.
On Gitea a passed check must also match each of required: a check CI has yet to queue is no status at all. A head without any check counts as passed once settled, and as pending before, since CI may not have queued its checks yet. gh reports no check as pending before it starts, so there such a head always counts as passed.
On Gitea a passed check must also match each of required: a check CI has yet to queue is no status at all. A head without any check counts as passed once settled, and as pending before, since CI may not have queued its checks yet. On GitHub such a head always counts as passed: gh cannot tell a head whose checks have yet to start from a head that has none.
"""
if forge == "gh":
listed = run(["gh", "pr", "checks", number, "--json", "bucket"])
+1 -1
View File
@@ -153,7 +153,7 @@ Valid while `~/.claude` is a checkout of this repo.
- **Releases.** An epic item has no release. It ships into its repo's unreleased work: a bullet under `CHANGELOG.md` → `## Unreleased`, or nothing where the repo's plan is in Jira.
- **Repos.** A repo's name is its main checkout's folder name, and a project config names that checkout. A missing checkout is cloned from the host of the epic's other repos; where unsure, do-epic asks. Unsure means the other repos don't all sit under one host and owner (the same host spelt as https and as ssh counts as two), an origin can't be read or isn't an https, ssh or scp-style address, the folder to clone into holds something else, or the clone fails. A repo no config names is cloned into the clone folder, and the human is asked to write its config. Each chunk uses its repo's model, routing, and language for commits and PRs. Jira text is in the epic's language, or else the machine's default.
- **Running.** The epic caps the chunks running at once, and each repo's `parallel-chunks` still applies. do-epic and loop-claude never run chunks in the same repo at once. The cap is a line of the epic's description, `**Max parallel chunks:** 2`, and 1 without it, as `parallel-chunks` is. A repo's `parallel-chunks` counts the chunks of every epic in its checkout. Each window is named for its issue's key, and a tmux window option, `@chunk-root`, names the folder its chunk works in, which is how loop-claude sees do-epic's chunks in a checkout. do-epic and loop-claude each hold the checkout's `starting` lock from checking the checkout's chunks to starting a window there. A chunk without a repo works in `~/.local/state/do-epic/<EPIC-KEY>/`. do-epic archives its cycles under `~/.claude/do-epic-transcripts/`, not in loop-claude's archive, whose readers parse loop-claude's prompts. An open issue runs once a label records its repo; until do-epic picks repos itself, an issue without one waits, and `do-epic <EPIC-KEY>` says so.
- **Long gates.** A chunk whose PR waits on a gate, such as a human approval, parks. It keeps its worktree, PR and session, and its state is in a file that survives a reboot. A parked chunk takes no running slot, and the items it blocks wait. do-epic polls the forge and resumes the chunk's session when the gate passes or a reviewer comments. It fixes reasonable feedback, replies to the rest, and changes the setup so review would have caught it. `do-epic <key> --status` and the tmux window names show what each chunk waits on. A gate is a pull request's pending checks or, on GitHub, the approval its branch protection requires; a draft waits on neither, since its worker has yet to mark it ready. On Gitea a draft is a pull request whose title opens with `WIP:` or `[WIP]`, Gitea's default `WORK_IN_PROGRESS_PREFIXES`. Changes a reviewer requested resume the chunk only while that review was made on the pull request's head commit and the pull request's author has not commented or replied after it; once the worker pushed or replied, the chunk parks on a new review, since GitHub keeps the decision until the reviewer reviews again. The chunk's window reads the forge once a minute, which no forge's rate limit notices. A chunk resumes only into a free slot, under the limits a starting chunk meets, and stays parked until then. `do-epic <key>` starts a parked chunk's window again whatever the limits, since it goes on 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 doesn't hold the slot while it waits.
- **Long gates.** A chunk whose PR waits on a gate, such as a human approval, parks. It keeps its worktree, PR and session, and its state is in a file that survives a reboot. A parked chunk takes no running slot, and the items it blocks wait. do-epic polls the forge and resumes the chunk's session when the gate passes or a reviewer comments. It fixes reasonable feedback, replies to the rest, and changes the setup so review would have caught it. `do-epic <key> --status` and the tmux window names show what each chunk waits on. A gate is a pull request's pending checks or, on GitHub, the approval its branch protection requires; a draft waits on neither, since its worker has yet to mark it ready. On Gitea a draft is a pull request whose title opens with `WIP:` or `[WIP]`, Gitea's default `WORK_IN_PROGRESS_PREFIXES`. Changes a reviewer requested resume the chunk only while that review was made on the pull request's head commit and the pull request's author has not commented or replied after it; once the worker pushed or replied, the chunk parks on a new review, since GitHub keeps the decision until the reviewer reviews again. The chunk's window reads the forge once a minute, which no forge's rate limit notices. A chunk resumes only into a free slot, under the limits a starting chunk meets, and stays parked until then. `do-epic <key>` starts a parked chunk's window again whatever the limits, since the chunk stays parked. do-epic sets `CHUNK_PR_PARKS=1` for each worker, so `chunk-pr merge` fails at once where the pull request awaits an approval, and the worker's run doesn't hold a slot while the pull request waits.
- **Human tasks.** do-epic DMs the human when one blocks the next item, and polls until its issue closes.
- **Findings.** A finding about the epic's goals is filed in the epic. A finding about a repo's goals follows that repo's rules. Where unsure which, do-epic asks. A set of new items toward an epic goal needs the human's approval before work starts; a finding filed during a chunk doesn't.
- **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.