Answer product-owner round 1: 1 🔴, 1 🟡 (0 misread); say when planning stops at a missing repo, mark what the dry run would do, and reword its text and docs (the stability and prose answers are in this commit too)
This commit is contained in:
@@ -198,7 +198,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
|
||||
- `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.
|
||||
- `deploy-release [--cut] [<checkout>]` moves `~/.claude`, or the checkout named, to the newest release, as Update says; with `--cut`, run in the development clone, it first cuts the next release, as Release says.
|
||||
- `do-epic <EPIC-KEY>` runs the chunks of one Jira epic whose items span repos, or have none, each in its own window of the tmux session `epic-<EPIC-KEY>`, on the same cycle, judge and interrupt as loop-claude. The epic's description is its record: goals, audience, scoring and decisions. Before it starts chunks, do-epic plans each open issue that no label places yet, as "Set up a project" says. It files a sub-task per repo where the issue changes several repos. Otherwise it labels the issue with where it is worked, and asks you where that is unclear. It plans no issue your team filed a sub-task under: those sub-tasks run instead, each under a label of its own, and your team closes the issue. Then it puts the scored issues that do-epic itself filed in order of score. An open issue runs once a label names its repo or marks it as Claude's, in Jira's backlog order, as many at once as a line such as `**Max parallel chunks:** 2` in the epic's description allows, 1 without it, and as each repo's `parallel-chunks` allows. A chunk whose pull request waits on a gate parks. An open task of yours that blocks another issue gets a window that DMs you once and reads the epic every minute; once you close the task, the issues it blocked may start. `do-epic <EPIC-KEY> --dry-run` runs the planning and the scheduling against the epic as Jira holds it, and prints each label, sub-task, comment and rank move planning would write, each chunk that would start and why each other issue waits, without writing to Jira, starting a window or asking a question; run it first on a team's epic. do-epic closes the epic only once you confirm every goal. Install → "Set up a project" says how to set it up; `do-epic --help` states the flags and the contract.
|
||||
- `do-epic <EPIC-KEY>` runs the chunks of one Jira epic whose items span repos, or have none, each in its own window of the tmux session `epic-<EPIC-KEY>`, on the same cycle, judge and interrupt as loop-claude. The epic's description is its record: goals, audience, scoring and decisions. Before it starts chunks, do-epic plans each open issue that no label places yet, as "Set up a project" says. It files a sub-task per repo where the issue changes several repos. Otherwise it labels the issue with where it is worked, and asks you where that is unclear. It plans no issue your team filed a sub-task under: those sub-tasks run instead, each under a label of its own, and your team closes the issue. Then it puts the scored issues that do-epic itself filed in order of score. An open issue runs once a label names its repo or marks it as Claude's, in Jira's backlog order, as many at once as a line such as `**Max parallel chunks:** 2` in the epic's description allows, 1 without it, and as each repo's `parallel-chunks` allows. A chunk whose pull request waits on a gate parks. An open task of yours that blocks another issue gets a window that DMs you once and reads the epic every minute; once you close the task, the issues it blocked may start. `do-epic <EPIC-KEY> --dry-run` prints what `do-epic <EPIC-KEY>` would write to Jira and which chunks it would start, and does neither; run it before the first real run on a team's epic. `--help` lists what it prints and leaves out. do-epic closes the epic only once you confirm every goal. Install → "Set up a project" says how to set it up; `do-epic --help` states the flags and the contract.
|
||||
- `do-epic-e2e` runs `do-epic` against a sandbox epic on a real Jira site, as Test says.
|
||||
- `judge-replay <model> [--offline]` replays loop-claude's judge on archived verdicts of the projects run on the model. It prints what each rung a review climbs to misses, and the lowest rung below those that returns every verdict, as each candidate above it does. With `--offline` it doesn't call a judge: it counts what a "?" rule, a decision table and a classifier trained on the archive decide of each verdict's kind from the worker's final message, and how many interrupts each misses. `judge-replay --help` states both replays.
|
||||
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count and the opening of its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""What `do-epic <EPIC-KEY> --dry-run` runs planning and the scheduler on, in place of Jira and tmux: an in-memory copy of the epic that records each write, and a tmux that starts no window. Reads of the epic and of tmux's windows are real, so the run sees the epic and the chunks as they are now."""
|
||||
"""What `do-epic <EPIC-KEY> --dry-run` runs planning and the scheduler on, in place of Jira, tmux and git: an in-memory copy of the epic that records each write, a tmux that starts no window and a git that clones no repo. The copy starts as the epic is in Jira, and tmux's windows are read as they are, so the run sees the epic and the chunks as they are now."""
|
||||
import dataclasses
|
||||
import subprocess
|
||||
|
||||
@@ -16,7 +16,7 @@ STARTS = ("new-session", "new-window")
|
||||
|
||||
@dataclasses.dataclass
|
||||
class DryEpic(MemoryEpic):
|
||||
"""The epic as `store` holds it. A sub-task it files gets a key no Jira issue has, such as ABC-new1, since Jira alone gives the next number."""
|
||||
"""An in-memory epic. A sub-task it files gets a key no Jira issue has, such as ABC-new1, since Jira alone gives the next number."""
|
||||
filed: int = 0
|
||||
|
||||
def next_key(self) -> str:
|
||||
@@ -34,7 +34,7 @@ def seeded(store: EpicStore) -> DryEpic | Failure:
|
||||
|
||||
|
||||
def recording(real: Tmux) -> Tmux:
|
||||
"""real for each read; a command that starts a window is answered as if it had, and the window shows in every later listing, as a window that runs. Any other command, which would change a window, is answered as done."""
|
||||
"""real for each read. A command that starts a window is answered as if it had, and the window then shows in each later listing as a window that runs. Any other command, which would change a session or a window, is answered as done."""
|
||||
started: list[tuple[str, str, str]] = []
|
||||
|
||||
def run(args: list[str]) -> subprocess.CompletedProcess[str]:
|
||||
@@ -62,7 +62,7 @@ def without_clones(real: Git) -> Git:
|
||||
"""real, except that a command with `clone` among its words fails, so that no repo is cloned."""
|
||||
def run(*args: str, cwd: str | None = None, timeout: float | None = None, guarded: bool = False, errors: str = "strict") -> str | Failure:
|
||||
if "clone" in args:
|
||||
return Failure("a dry run clones nothing")
|
||||
return Failure("a dry run doesn't clone a repo, but a real run would")
|
||||
return real(*args, cwd=cwd, timeout=timeout, guarded=guarded, errors=errors)
|
||||
|
||||
return run
|
||||
|
||||
+12
-10
@@ -62,7 +62,8 @@ on once the checks pass, the approval comes or a reviewer comments, and a place
|
||||
name says `awaits a slot`. In a repo whose config sets `merge = "human"`, a chunk never merges: once its pull
|
||||
request is ready, with nothing else to wait on, the window's name says `awaits your merge`, and its worker goes on once you merged it. A parked chunk survives a reboot: run do-epic <EPIC-KEY> again to go on polling.
|
||||
--status doesn't start any chunk. It prints a line per open issue: that its chunk runs or asks you a question, or why it waits, such as the gate a parked chunk awaits and since when.
|
||||
--dry-run runs the planning and the scheduling against the epic as Jira holds it, and writes nothing to Jira, starts no window and asks no question. It prints each label, sub-task, comment and rank move that planning would write, each chunk that would start and why each other issue waits. Planning's claude calls still run, and a repo that is missing isn't cloned. A question planning would ask is printed instead.
|
||||
--dry-run runs the planning and the scheduling against the epic as Jira holds it. It doesn't write anything to Jira, start a window or ask a question. It prints each label, sub-task, comment and rank move that planning would write, each chunk that would start and why each other issue waits. A sub-task not yet filed shows a key such as ABC-new1. A question planning would ask is printed instead of asked. Planning's claude calls still run.
|
||||
A repo that is missing isn't cloned. Planning then stops there, so its writes are only those made before it, and the issues of that repo wait; a real run would clone it and go on.
|
||||
{findings.HELP}
|
||||
{finish.HELP}
|
||||
The Jira site and its credentials are set in ~/.claude-projects/do-epic/config.toml."""
|
||||
@@ -70,7 +71,7 @@ The Jira site and its credentials are set in ~/.claude-projects/do-epic/config.t
|
||||
ARCHIVE = ".claude/do-epic-transcripts"
|
||||
# The flag that prints what each open issue does.
|
||||
STATUS_FLAG = "--status"
|
||||
# The flag that prints what planning and the scheduler would do, and does none of it.
|
||||
# The flag that prints what planning and the scheduler would do, without doing it.
|
||||
DRY_RUN_FLAG = "--dry-run"
|
||||
# How often a parked chunk reads its pull request's gate, and a human task's window reads the epic: a person answers in hours, and each read is a few calls.
|
||||
POLL_SECONDS = 60
|
||||
@@ -178,8 +179,8 @@ def windows_opened(epic: EpicRun) -> Stop:
|
||||
return Stop(1, f"`tmux {' '.join(shown)}` failed; the chunks go on in the tmux session") if epic.effects.tmux_on_terminal(shown) else Stop(0, "")
|
||||
|
||||
|
||||
def planned_and_started(epic: EpicRun) -> scheduler.Started | Stop:
|
||||
"""Plans the epic's open issues, then starts each chunk that may start now."""
|
||||
def planned_and_started(epic: EpicRun, dry: bool = False) -> scheduler.Started | Stop:
|
||||
"""Plans the epic's open issues, then starts each chunk that may start now. Where dry, a planning that stops early says so on stdout, and that the writes shown are those made before it stopped."""
|
||||
read = epic.store.read()
|
||||
if isinstance(read, Failure):
|
||||
return Stop(1, read.reason)
|
||||
@@ -188,13 +189,13 @@ def planned_and_started(epic: EpicRun) -> scheduler.Started | Stop:
|
||||
return Stop(1, f"the epic is not planned, so no chunk started: {stopped.said}")
|
||||
if stopped is not None:
|
||||
# One issue or repo that cannot be planned holds back only itself: each chunk that may start still does.
|
||||
say(f"the epic {epic.key} is not planned in full: {stopped.reason}", epic.effects)
|
||||
say(f"the epic {epic.key} is not planned in full: {stopped.reason}" + (", so the writes below are those it made before it stopped" if dry else ""), epic.effects, stdout=dry)
|
||||
started = chunks_started(epic, issues, None)
|
||||
return Stop(1, started.reason) if isinstance(started, Failure) else started
|
||||
|
||||
|
||||
def chunks_said(epic: EpicRun, started: scheduler.Started, verb: str, where: str) -> None:
|
||||
"""Prints each chunk that started, after verb and before where, else that none did, then why each other open issue waits, and whether the epic is closed."""
|
||||
"""Prints `<verb> <the chunks>` and where, or `<verb> no chunk`, then why each other open issue waits, and that the epic is closed where it is."""
|
||||
say(f"{verb} {', '.join(started.started)}{where}" if started.started else f"{verb} no chunk", epic.effects, stdout=True)
|
||||
for wait in started.waits:
|
||||
say(f"{wait.issue} waits: {wait.reason}", epic.effects, stdout=True)
|
||||
@@ -203,15 +204,16 @@ def chunks_said(epic: EpicRun, started: scheduler.Started, verb: str, where: str
|
||||
|
||||
|
||||
def dry_run_printed(epic: EpicRun) -> Stop:
|
||||
"""What `do-epic <EPIC-KEY> --dry-run` does: runs windows_opened's planning and scheduling on a copy of the epic and a tmux that starts nothing, then prints each Jira write planning made there. It never puts the session on the terminal or asks a question."""
|
||||
"""What `do-epic <EPIC-KEY> --dry-run` does: plans and starts as `windows_opened` does, on a copy of the epic, a tmux that starts no window and a git that clones no repo, then prints each Jira write planning made on the copy, each chunk that would start and why each other issue waits. It doesn't put the session on the terminal or ask a question."""
|
||||
dry = dry_run.seeded(epic.store)
|
||||
if isinstance(dry, Failure):
|
||||
return Stop(1, dry.reason)
|
||||
effects = dataclasses.replace(epic.effects, tmux=dry_run.recording(epic.effects.tmux), git=dry_run.without_clones(epic.effects.git), on_terminal=lambda: False)
|
||||
rehearsal = dataclasses.replace(epic, store=dry, effects=effects)
|
||||
say("dry run: nothing is written to Jira and no window starts", effects, stdout=True)
|
||||
started = planned_and_started(rehearsal)
|
||||
say("planning would write to Jira:\n" + "\n".join(f"- {write}" for write in dry.writes) if dry.writes else "planning would write nothing to Jira", effects, stdout=True)
|
||||
say("dry run: nothing is written to Jira and no window starts, so a line below that says an issue is labelled or split shows what a real run would do", effects, stdout=True)
|
||||
started = planned_and_started(rehearsal, dry=True)
|
||||
writes = "".join("\n- " + write.replace("\n", "\n ") for write in dry.writes)
|
||||
say(f"planning would write to Jira:{writes}" if dry.writes else "planning wouldn't write anything to Jira", effects, stdout=True)
|
||||
if isinstance(started, Stop):
|
||||
return started
|
||||
chunks_said(rehearsal, started, "would start", "")
|
||||
|
||||
@@ -74,7 +74,7 @@ class TheGitThatClonesNothing(unittest.TestCase):
|
||||
ran.append(args)
|
||||
return "ok"
|
||||
git = dry_run.without_clones(real)
|
||||
self.assertEqual(git("-c", "a=b", "clone", "--", "url", "dir"), Failure("a dry run clones nothing"))
|
||||
self.assertEqual(git("-c", "a=b", "clone", "--", "url", "dir"), Failure("a dry run doesn't clone a repo, but a real run would"))
|
||||
self.assertEqual(git("remote", cwd="/c"), "ok")
|
||||
self.assertEqual(ran, [("remote",)])
|
||||
|
||||
|
||||
@@ -970,6 +970,9 @@ class TheStatus(DoEpicTest):
|
||||
self.assertIn("Jira answered 503\n", err)
|
||||
|
||||
|
||||
BANNER = "dry run: nothing is written to Jira and no window starts, so a line below that says an issue is labelled or split shows what a real run would do"
|
||||
|
||||
|
||||
class TheDryRun(DoEpicTest):
|
||||
def setUp(self) -> None:
|
||||
super().setUp()
|
||||
@@ -1006,7 +1009,7 @@ class TheDryRun(DoEpicTest):
|
||||
code, out, _ = self.run_main(["ABC-12", "--dry-run"], FakeEffects(on_terminal=True))
|
||||
self.assertEqual(code, 0)
|
||||
shown = out.replace("<1790000000> ", "")
|
||||
self.assertIn("planning would write nothing to Jira\nwould start ABC-21\n", shown)
|
||||
self.assertIn("planning wouldn't write anything to Jira\nwould start ABC-21\n", shown)
|
||||
self.assertIn("ABC-22 waits: the epic runs as many chunks as its `**Max parallel chunks:**` line allows: 1\n", shown)
|
||||
|
||||
def test_prints_the_question_planning_would_ask_and_asks_none(self) -> None:
|
||||
@@ -1017,7 +1020,7 @@ class TheDryRun(DoEpicTest):
|
||||
self.assertEqual(code, 0)
|
||||
self.assertIn("ABC-20 waits for your answer: Is the importer in api or in web?", out)
|
||||
self.assertEqual([seam for seam, _ in fake.calls if seam == "input"], [])
|
||||
self.assertIn("planning would write nothing to Jira\n", out)
|
||||
self.assertIn("planning wouldn't write anything to Jira\n", out)
|
||||
|
||||
def test_works_without_tmux_and_a_chunk_in_a_missing_repo_waits(self) -> None:
|
||||
self.issues = [issue("ABC-20", "repo:missing"), issue("ABC-21", "do-epic-claude")]
|
||||
@@ -1025,7 +1028,6 @@ class TheDryRun(DoEpicTest):
|
||||
code, out, _ = self.run_main(["ABC-12", "--dry-run"], fake)
|
||||
self.assertEqual(code, 0)
|
||||
self.assertIn("would start ABC-21\n", out)
|
||||
self.assertIn("ABC-20 waits:", out)
|
||||
self.assertIn("ABC-20 waits: missing is missing", out)
|
||||
self.assertEqual([what for seam, what in fake.calls if seam == "git" and "clone" in what], [])
|
||||
|
||||
@@ -1035,9 +1037,26 @@ class TheDryRun(DoEpicTest):
|
||||
fake = FakeEffects(on_terminal=False, git=["git@host.example:team/api.git", ""])
|
||||
code, out, err = self.run_main(["ABC-12", "--dry-run"], fake)
|
||||
self.assertEqual((code, err), (0, ""))
|
||||
self.assertEqual(out.replace("<1790000000> ", ""), f"dry run: nothing is written to Jira and no window starts\nplanning would write nothing to Jira\nwould start ABC-20\nABC-22 waits: cannot clone git@host.example:team/web to {self.home / 'code/web'}: a dry run clones nothing. Where does web live?\n")
|
||||
self.assertEqual(out.replace("<1790000000> ", ""), f"{BANNER}\nplanning wouldn't write anything to Jira\nwould start ABC-20\nABC-22 waits: cannot clone git@host.example:team/web to {self.home / 'code/web'}: a dry run doesn't clone a repo, but a real run would. Where does web live?\n")
|
||||
self.assertEqual([what for seam, what in fake.calls if seam == "git" and "clone" in what], [])
|
||||
|
||||
def test_says_on_stdout_that_planning_stopped_at_a_missing_repo_and_what_the_writes_are(self) -> None:
|
||||
shutil.rmtree(self.home / "code/web")
|
||||
self.issues = [issue("ABC-20"), issue("ABC-22", "repo:api"), issue("ABC-23", "repo:web")]
|
||||
fake = FakeEffects(on_terminal=False, git=["git@host.example:team/api.git", ""])
|
||||
code, out, err = self.run_main(["ABC-12", "--dry-run"], fake)
|
||||
self.assertEqual((code, err), (0, ""))
|
||||
stopped = f"the epic ABC-12 is not planned in full: cannot clone git@host.example:team/web to {self.home / 'code/web'}: a dry run doesn't clone a repo, but a real run would. Where does web live?, so the writes below are those it made before it stopped\n"
|
||||
self.assertIn(stopped, out.replace("<1790000000> ", ""))
|
||||
self.assertIn("planning wouldn't write anything to Jira\n", out)
|
||||
|
||||
def test_indents_the_lines_after_the_first_of_a_comment_under_its_bullet(self) -> None:
|
||||
self.issues = [issue("ABC-20")]
|
||||
parts = structured({"parts": [{"repo": "api", "change": "Add it."}, {"repo": "web", "change": "Call it."}], "comment": "Split by repo.\nSecond line."})
|
||||
code, out, _ = self.run_main(["ABC-12", "--dry-run"], FakeEffects(claude=[parts]))
|
||||
self.assertEqual(code, 0)
|
||||
self.assertIn("\n- comment on ABC-20: Split by repo.\n Second line.\n", out)
|
||||
|
||||
def test_stops_where_the_epic_cannot_be_read(self) -> None:
|
||||
store = MemoryEpic("ABC-12", [], fails="Jira answered 503")
|
||||
self.backend = lambda config, key: (store, EpicRecord(Description(self.description))) # type: ignore[method-assign,arg-type]
|
||||
|
||||
Reference in New Issue
Block a user