Find an epic repo's checkout and project config by its name, and clone a missing one from the place of the epic's other repos #598

Merged
lilleman merged 11 commits from item-407 into main 2026-11-18 14:03:50 +01:00
11 changed files with 393 additions and 18 deletions
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- do-epic finds an epic repo's checkout and project config by the repo's name, and clones a missing checkout from the host and owner of the epic's other repos, asking the human where they differ or the clone fails.
- do-epic reads its machine-wide settings from ~/.claude-projects/do-epic/config.toml and its repo rule from repo-rule.md beside it, and refuses to start while either is missing or misspelt.
- `project-record save` now writes a goals file kept as a Jira epic's description, except a change to `## Goals` or `## Audience`, which stays an edit in Jira.
- Add do-epic's epic backend: one interface that reads a Jira epic's child issues and their sub-tasks, with labels, assignee, status and parent, and files new ones, met by a Jira backend and an in-memory fake that pass the same contract tests.
+2 -2
View File
@@ -213,8 +213,8 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
- `deploy_release` imports `release_plan`'s `release_standing`.
- `do_epic/` will hold the tool that drives one Jira epic. So far `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section and language line, through `record_store`'s `EpicDescription`.
- `forge/` tells a GitHub origin from a Gitea one and runs that forge's CLI (`commands.py`), and finds a pull request and waits for its checks (`pulls.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release` and `larv_review`.
- `do_epic/` will hold the tool that drives one Jira epic. So far `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section and language line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`.
- `forge/` tells a GitHub origin from a Gitea one, names a repo beside an origin's and runs that forge's CLI (`commands.py`), and finds a pull request and waits for its checks (`pulls.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release`, `do_epic` and `larv_review`.
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
- `judge_replay` imports `loop_claude`'s judge, verdicts, premises and records.
- `loop_claude` runs `chunk-preflight` as a process of its own.
+96
View File
@@ -0,0 +1,96 @@
"""Where an epic's repo is on this machine: its checkout and its project config, found by the repo's name.
A missing checkout is cloned from the host and owner of the epic's other repos (docs/decisions.md → `do-epic: drives one Jira epic …`). Where that is unclear, the answer is an Unsure."""
import dataclasses
import pathlib
import re
import shutil
from project_config.settings import by_name, CONFIG, ProjectConfig, PROJECTS
from do_epic.config import DoEpicConfig
from failure import Failure
from git_cli.git_repo import Git
from forge.commands import url_beside
# One folder name, which can't be a path or a git option.
REPO_NAME = r"\w[\w.-]*"
# The addresses a clone may use: https, ssh, or scp-style `user@host:path`. Not ext:: or file:, which run a program or read this machine's files, and an origin can spell either.
CLONE_ADDRESS = rf"https://[\w.-]+(:\d+)?/\S+|ssh://[\w.@-]+(:\d+)?/\S+|\w[\w.-]*@[\w.-]+:[\w./~-]+"
# A clone that waits longer is stopped.
CLONE_SECONDS = 600
# git's options that make a password or a host key fail at once instead of prompting: an unattended run never waits on a prompt (docs/decisions.md → principle 6).
NO_PROMPTS = ("-c", "core.askPass=true", "-c", "core.sshCommand=ssh -o BatchMode=yes")
@dataclasses.dataclass(frozen=True)
class Located:
"""checkout is the repo's git checkout, and config the project config that names it."""
checkout: pathlib.Path
config: ProjectConfig
@dataclasses.dataclass(frozen=True)
class Unsure(Failure):
"""reason is a question for the human."""
def locate(name: str, others: list[pathlib.Path], config: DoEpicConfig, home: pathlib.Path, git: Git) -> Located | Failure:
"""The checkout and project config of the repo called name; others are the checkouts of the epic's other repos.
A project config names the repo's checkout, and it is cloned where missing. Where no config names the repo, it is cloned into the clone folder, if it isn't there, and the human is asked to write the config, since the repo's plan, goals and records are theirs to place.
A name that is no repo's name, or a config that can't be read, is a plain Failure. Any other fault is an Unsure."""
if not re.fullmatch(REPO_NAME, name):
return Failure(f"{name!r} is not a repo's name: one folder name that starts with a letter, digit or underscore")
found = by_name(name, home)
if isinstance(found, Failure):
return found
checkout = found.top if found else config.clone_folder / name
cloned = ensure(name, checkout, others, git)
if isinstance(cloned, Failure):
return cloned
if found is None:
return Unsure(f"{checkout} {'was cloned' if cloned else 'holds the repo'}, but no project config names it. Write {home / PROJECTS}/<key>/{CONFIG} with `checkout = \"{checkout}\"`, as `project-config --help` shows, and run do-epic again.")
return Located(checkout, found)
def ensure(name: str, checkout: pathlib.Path, others: list[pathlib.Path], git: Git) -> bool | Failure:
"""Whether checkout was cloned just now: False where it is a git checkout already. Else it is cloned there from the host and owner of the others, or an Unsure says why not."""
if (checkout / ".git").exists():
return False
if checkout.exists() and (not checkout.is_dir() or any(checkout.iterdir())):
return Unsure(f"{checkout} exists and is not a git checkout, so {name} cannot be cloned there. Where should it be cloned?")
url = clone_url(name, others, git)
if isinstance(url, Failure):
return url
cloned = git(*NO_PROMPTS, "clone", "--", url, str(checkout), timeout=CLONE_SECONDS)
if isinstance(cloned, Failure):
# What the clone began, and nothing else: checkout was absent or empty. A kept half-clone would pass for the repo on the next run.
shutil.rmtree(checkout, ignore_errors=True)
return Unsure(f"cannot clone {url} to {checkout}: {cloned.reason}. Where does {name} live?")
return True
def without_credentials(url: str) -> str:
"""url without a `user:token@` after its scheme, so that a clone and a question for the team never carry one. The clone then uses git's own credentials."""
return re.sub(r"^(https?://)[^/]*@", r"\1", url)
def clone_url(name: str, others: list[pathlib.Path], git: Git) -> str | Failure:
"""The address of the repo called name, under the host and owner all the others share. An Unsure where they share none or an address can't be built."""
if not others:
return Unsure(f"{name} is missing and no other repo of the epic shows what host to clone it from. Where does it live?")
urls = set()
for other in others:
origin = git("remote", "get-url", "origin", cwd=str(other))
if isinstance(origin, Failure):
return Unsure(f"cannot read the origin of {other}: {origin.reason}. Where does {name} live?")
beside = url_beside(without_credentials(origin.strip()), name)
if beside is None:
return Unsure(f"{other} has an origin, {without_credentials(origin.strip())}, with no host and owner to put another repo under. Where does {name} live?")
urls.add(beside)
if len(urls) > 1:
return Unsure(f"The epic's other repos sit under more than one host or owner, so {name} could be at {' or '.join(sorted(urls))}. Which holds it?")
url = next(iter(urls))
if not re.fullmatch(CLONE_ADDRESS, url):
return Unsure(f"{url} is not an https, ssh or scp-style address. Where does {name} live?")
return url
+184
View File
@@ -0,0 +1,184 @@
import pathlib
import sys
import tempfile
import unittest
import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.config import DoEpicConfig
from failure import Failure
from do_epic.repos import locate, Located, Unsure
from project_config.settings import ProjectConfig
from project_config.test_project_config import write_config
class FakeGit:
"""git as locate calls it: origins maps a checkout to its origin URL, cloned holds each `clone` that worked, and refused names a URL whose clone fails after it made the checkout's `.git`, as a stopped git does."""
def __init__(self, origins: dict[str, str | Failure], refused: str | None = None) -> None:
self.origins, self.refused = origins, refused
self.cloned: list[tuple[str, str]] = []
self.clone_timeouts: list[float | None] = []
self.clone_options: list[tuple[str, ...]] = []
def __call__(self, *args: str, cwd: str | None = None, timeout: float | None = None, guarded: bool = False, errors: str = "strict") -> str | Failure:
if args[:3] == ("remote", "get-url", "origin"):
return self.origins[cwd or ""]
clone = args.index("clone")
self.clone_options.append(args[:clone])
assert args[clone + 1] == "--", args
url, destination = args[clone + 2:clone + 4]
pathlib.Path(destination, ".git").mkdir(parents=True)
if url == self.refused:
return Failure("git clone: repository not found")
self.cloned.append((url, destination))
self.clone_timeouts.append(timeout)
return ""
class LocateTest(unittest.TestCase):
def setUp(self) -> None:
made = tempfile.TemporaryDirectory()
self.addCleanup(made.cleanup)
self.home = pathlib.Path(made.name).resolve()
self.projects = self.home / ".claude-projects"
self.config = DoEpicConfig(self.projects / "do-epic", "https://acme.atlassian.net", self.home / "jira.env", self.home / "clones", "English", "claude-opus-5-5", "rule")
self.billing, self.payments = self.home / "elsewhere" / "billing", self.home / "elsewhere" / "payments"
self.origins: dict[str, str | Failure] = {str(self.billing): "git@github.com:acme/billing.git", str(self.payments): "git@github.com:acme/payments"}
def configure(self) -> None:
write_config(self.home, self.home / "code" / "ledger")
def locate(self, git: FakeGit, name: str = "ledger") -> Located | Failure:
return locate(name, [self.billing, self.payments], self.config, self.home, git)
def unsure(self, git: FakeGit, name: str = "ledger") -> str:
found = self.locate(git, name)
assert isinstance(found, Unsure), found
return found.reason
def test_finds_a_checkout_that_exists_with_its_config_and_clones_nothing(self) -> None:
self.configure()
(self.home / "code" / "ledger" / ".git").mkdir(parents=True)
git = FakeGit(self.origins)
found = self.locate(git)
assert isinstance(found, Located), found
self.assertEqual((found.checkout, found.config.folder, git.cloned), (self.home / "code" / "ledger", self.projects / "ledger", []))
def test_clones_a_checkout_the_config_names_where_it_is_missing_from_the_place_of_the_other_repos(self) -> None:
self.configure()
git = FakeGit(self.origins)
found = self.locate(git)
assert isinstance(found, Located), found
self.assertEqual((found.checkout, git.cloned), (self.home / "code" / "ledger", [("git@github.com:acme/ledger", str(self.home / "code" / "ledger"))]))
assert isinstance(found.config, ProjectConfig)
def test_clones_into_the_clone_folder_and_asks_for_a_config_where_none_names_the_repo(self) -> None:
git = FakeGit(self.origins)
asked = self.unsure(git)
clone = self.home / "clones" / "ledger"
self.assertEqual(git.cloned, [("git@github.com:acme/ledger", str(clone))])
self.assertIn(f"{clone} was cloned, but no project config names it", asked)
self.assertIn(f"{self.projects}/<key>/config.toml with `checkout = \"{clone}\"`", asked)
self.assertEqual(self.unsure(git), asked.replace("was cloned", "holds the repo"), "the second ask finds the clone and clones nothing")
self.assertEqual(len(git.cloned), 1)
def test_asks_where_the_other_repos_sit_in_more_than_one_place(self) -> None:
self.configure()
self.origins[str(self.payments)] = "git@gitea.larvit.se:acme/payments"
git = FakeGit(self.origins)
asked = self.unsure(git)
self.assertIn("git@gitea.larvit.se:acme/ledger or git@github.com:acme/ledger", asked)
self.assertEqual(git.cloned, [])
def test_asks_where_the_other_repos_differ_only_by_owner(self) -> None:
self.configure()
self.origins[str(self.payments)] = "git@github.com:other/payments"
self.assertIn("more than one host or owner", self.unsure(FakeGit(self.origins)))
def test_asks_where_no_other_repo_shows_where_to_clone_from(self) -> None:
self.configure()
found = locate("ledger", [], self.config, self.home, FakeGit({}))
assert isinstance(found, Unsure), found
self.assertIn("no other repo of the epic", found.reason)
def test_asks_where_an_others_origin_cannot_be_read_or_has_no_place(self) -> None:
self.configure()
self.origins[str(self.billing)] = Failure("git remote: no such remote 'origin'")
self.assertIn(f"cannot read the origin of {self.billing}: git remote: no such remote 'origin'", self.unsure(FakeGit(self.origins)))
self.origins[str(self.billing)] = "billing"
self.assertIn(f"{self.billing} has an origin, billing, with no host and owner to put another repo under", self.unsure(FakeGit(self.origins)))
def test_asks_all_the_same_where_the_leftovers_of_a_failed_clone_cannot_be_removed(self) -> None:
self.configure()
with unittest.mock.patch("do_epic.repos.shutil.rmtree", side_effect=lambda path, ignore_errors: None if ignore_errors is True else self.fail("rmtree must ignore errors")):
self.assertIn("cannot clone", self.unsure(FakeGit(self.origins, refused="git@github.com:acme/ledger")))
def test_asks_where_the_clone_fails_naming_the_url_and_the_reason(self) -> None:
self.configure()
asked = self.unsure(FakeGit(self.origins, refused="git@github.com:acme/ledger"))
self.assertIn(f"cannot clone git@github.com:acme/ledger to {self.home / 'code' / 'ledger'}: git clone: repository not found", asked)
def test_asks_where_the_place_to_clone_into_holds_something_that_is_not_a_checkout(self) -> None:
self.configure()
(self.home / "code" / "ledger").mkdir(parents=True)
(self.home / "code" / "ledger" / "notes.txt").write_text("x", encoding="utf-8")
git = FakeGit(self.origins)
self.assertIn(f"{self.home / 'code' / 'ledger'} exists and is not a git checkout", self.unsure(git))
self.assertEqual(git.cloned, [])
def test_refuses_a_name_that_is_not_a_repo_name_before_it_forms_a_path_or_a_command(self) -> None:
for name in ("../escape", "-flag", "a/b", ""):
with self.subTest(name=name):
found = self.locate(FakeGit(self.origins), name)
assert isinstance(found, Failure) and not isinstance(found, Unsure), found
self.assertIn("is not a repo's name", found.reason)
def test_refuses_an_origin_that_is_not_https_ssh_or_an_scp_style_address(self) -> None:
self.configure()
for origin in ("ext::sh -c touch% x/billing", "file:///srv/acme/billing", "/srv/acme/billing", "-oProxy=x:a/b"):
with self.subTest(origin=origin):
self.origins[str(self.billing)] = origin
self.origins[str(self.payments)] = origin
git = FakeGit(self.origins)
self.assertIn("is not an https, ssh or scp-style address", self.unsure(git))
self.assertEqual(git.cloned, [])
def test_clones_and_asks_without_the_credentials_an_origin_holds(self) -> None:
self.configure()
self.origins[str(self.billing)] = "https://bot:s3cret@gitea.larvit.se/acme/billing"
self.origins[str(self.payments)] = "https://other:t0@ken@gitea.larvit.se/acme/payments.git"
git = FakeGit(self.origins)
self.assertIsInstance(self.locate(git), Located)
self.assertEqual(git.cloned, [("https://gitea.larvit.se/acme/ledger", str(self.home / "code" / "ledger"))])
self.origins[str(self.payments)] = "https://other:t0@ken@gitea.larvit.se/acme/payments"
self.origins[str(self.billing)] = "https://bot:s3cret@gitea.larvit.se"
self.assertNotIn("s3cret", self.unsure(FakeGit(self.origins), "stock"))
def test_stops_a_clone_that_waits_and_makes_a_prompt_fail(self) -> None:
self.configure()
git = FakeGit(self.origins)
self.locate(git)
self.assertEqual(git.clone_timeouts, [600])
self.assertEqual(git.clone_options, [("-c", "core.askPass=true", "-c", "core.sshCommand=ssh -o BatchMode=yes")])
def test_removes_what_a_failed_clone_began_so_that_the_next_run_clones_again(self) -> None:
self.configure()
failing = FakeGit(self.origins, refused="git@github.com:acme/ledger")
self.unsure(failing)
self.assertFalse((self.home / "code" / "ledger").exists())
found = self.locate(FakeGit(self.origins))
self.assertIsInstance(found, Located)
def test_asks_where_the_place_to_clone_into_is_a_file(self) -> None:
self.configure()
(self.home / "code").mkdir()
(self.home / "code" / "ledger").write_text("x", encoding="utf-8")
self.assertIn("exists and is not a git checkout", self.unsure(FakeGit(self.origins)))
def test_fails_with_the_config_failure_where_a_config_cannot_be_read(self) -> None:
(self.projects / "broken").mkdir(parents=True)
(self.projects / "broken" / "config.toml").write_text("this is not toml", encoding="utf-8")
found = self.locate(FakeGit(self.origins))
self.assertIsInstance(found, Failure)
self.assertNotIsInstance(found, Unsure)
+9 -1
View File
@@ -1,5 +1,6 @@
"""Which forge a checkout's origin is on, and running that forge's CLI in the checkout."""
"""Which forge a checkout's origin is on, a repo's URL beside that origin's, and running the forge's CLI in the checkout."""
import json
import re
import subprocess
import typing
@@ -16,6 +17,13 @@ def forge_of(origin_url: str) -> Forge:
return "gh" if "github.com" in origin_url else "tea"
def url_beside(origin_url: str, name: str) -> str | None:
"""The origin URL of the repo called name under the same host and owner as origin_url's repo; None where origin_url has no place, such as a bare name. The URL has no `.git`, which git clones without."""
place = re.fullmatch(r"(.+[/:])[^/:]+", origin_url.rstrip("/"))
# An origin of only a scheme and a host, such as `https://host`, has no owner folder to put a name in.
return place.group(1) + name if place and not place.group(1).endswith("//") else None
def runner(cwd: str) -> Run:
def run(command: list[str]) -> str | Failure:
try:
+14 -1
View File
@@ -7,7 +7,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from forge.pulls import checks_passed, open_pull, POLL_SECONDS, required_checks, WAIT_SECONDS
from forge.commands import forge_of, gitea
from forge.commands import forge_of, gitea, url_beside
class ForgeOf(unittest.TestCase):
@@ -16,6 +16,19 @@ class ForgeOf(unittest.TestCase):
self.assertEqual(forge_of("https://gitea.larvit.se/o/r.git"), "tea")
class UrlBeside(unittest.TestCase):
def test_names_a_repo_in_the_same_place_of_the_same_host_in_each_spelling_of_an_origin(self):
self.assertEqual(url_beside("git@github.com:acme/billing.git", "ledger"), "git@github.com:acme/ledger")
self.assertEqual(url_beside("https://gitea.larvit.se/acme/billing", "ledger"), "https://gitea.larvit.se/acme/ledger")
self.assertEqual(url_beside("https://gitea.larvit.se/acme/billing.git/", "ledger"), "https://gitea.larvit.se/acme/ledger")
self.assertEqual(url_beside("gitea:billing", "ledger"), "gitea:ledger", "a host with no owner")
def test_names_none_where_the_origin_has_no_place_to_put_a_repo_in(self):
self.assertIsNone(url_beside("billing", "ledger"))
self.assertIsNone(url_beside("", "ledger"))
self.assertIsNone(url_beside("https://gitea.larvit.se", "ledger"))
# An answer no call can read, longer than the 200 characters of it that a failure quotes.
LONG = "[" + ", ".join(["1"] * 100) + "]"
+14
View File
@@ -350,6 +350,20 @@ def held(folder: pathlib.Path, home: pathlib.Path) -> ProjectConfig | Failure |
return config if isinstance(config, Failure) else load(config[0], config[0], home)
def by_name(name: str, home: pathlib.Path) -> ProjectConfig | Failure | None:
"""The config of the project whose main checkout is a folder called name, though that folder may not exist yet, loaded as `held` does; None where no config names one. A config that cannot be read fails every name, since it may be the one asked for."""
files = []
for file in configs(home):
config = read(file, home)
if isinstance(config, Failure):
return config
if config[0].name == name:
files.append(file)
if len(files) > 1:
return Failure(f"{' and '.join(str(file) for file in files)} each name a checkout called {name}; only one config may")
return held(files[0].parent, home) if files else None
def configs(home: pathlib.Path) -> list[pathlib.Path]:
"""Every project's config file under home, in key order. do-epic's machine-wide config is not a project's."""
return sorted(file for file in (home / PROJECTS).glob(f"*/{CONFIG}") if file.parent.name != DO_EPIC)
+27 -1
View File
@@ -9,7 +9,7 @@ import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from project_config.settings import env_files, Epic, Finish, held, JiraScoring, load, NOTIFIERS, OUTSIDE, Page, ProjectConfig, SETTINGS, Unnamed
from project_config.settings import by_name, env_files, Epic, Finish, held, JiraScoring, load, NOTIFIERS, OUTSIDE, Page, ProjectConfig, SETTINGS, Unnamed
from failure import Failure
from test_env import isolated_env
from project_config.main import located, title_templates
@@ -598,6 +598,32 @@ class HeldTest(ConfigCase):
self.assertIsInstance(held(target, self.home), ProjectConfig, "git names the folder by its resolved path")
class ByNameTest(ConfigCase):
def test_finds_the_config_of_the_project_whose_main_checkout_has_the_name_though_the_checkout_is_missing(self) -> None:
folder = self.write("acme", CLIENT)
found = by_name("acme-billing", self.home)
assert isinstance(found, ProjectConfig), found
self.assertEqual((found.folder, found.top), (folder, self.checkout))
def test_finds_none_where_no_config_names_a_checkout_of_that_name(self) -> None:
self.write("acme", CLIENT)
self.assertIsNone(by_name("billing", self.home), "a part of a name is not the name")
self.assertIsNone(by_name("acme", self.home), "a config's key is not a repo's name")
self.assertIsNone(by_name("do-epic", self.home))
def test_fails_where_two_configs_name_a_checkout_of_that_name(self) -> None:
self.write("acme", CLIENT)
self.write("acme-two", CLIENT.replace("~/code/acme-billing", "~/other/acme-billing"))
found = by_name("acme-billing", self.home)
assert isinstance(found, Failure), found
self.assertIn("acme/config.toml and ", found.reason)
self.assertIn("acme-two/config.toml each name a checkout called acme-billing", found.reason)
def test_fails_where_a_config_cannot_be_read_since_it_may_be_the_one_asked_for(self) -> None:
self.write("acme", "this is not toml")
self.assertIsInstance(by_name("acme-billing", self.home), Failure)
class EnvFilesTest(ConfigCase):
def test_lists_each_readable_configs_env_file_even_one_load_refuses(self) -> None:
self.write("acme", CLIENT + 'env-file = "~/acme.env"\n')
+1 -1
View File
@@ -151,7 +151,7 @@ Valid while `~/.claude` is a checkout of this repo.
- **One item, several repos.** do-epic splits such an item when it plans it, into one Jira sub-task per repo, each labelled for its repo. The parent tracks the whole change. A person's issue is split too, with a comment for the team.
- **Ranking.** Score, then Blocked by, in one weight chain: the epic's achieve goals, then code health, then the repo's goals. Where the epic and a repo disagree, the epic wins. do-epic re-ranks Jira's backlog to match, and people's issues keep their rank.
- **Releases.** An epic item has no release. It ships into its repo's unreleased work: a bullet under `CHANGELOG.md` → `## Unreleased`, or nothing where the repo's plan is in Jira.
- **Repos.** A missing checkout is cloned from the host of the epic's other repos; where unsure, do-epic asks. 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.
- **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.
- **Long gates.** A chunk whose PR waits on a gate, such as a human approval, parks. It keeps its worktree, PR and session, and its state is in a file that survives a reboot. A parked chunk takes no running slot, and the items it blocks wait. do-epic polls the forge and resumes the chunk's session when the gate passes or a reviewer comments. It fixes reasonable feedback, replies to the rest, and changes the setup so review would have caught it. `do-epic <key> --status` and the tmux window names show what each chunk waits on.
- **Human tasks.** do-epic DMs the human when one blocks the next item, and polls until its issue closes.
+44
View File
@@ -2596,3 +2596,47 @@ Read most (opens and searches):
- `docs/decisions.md` 6
- `skills/larv-review/SKILL.md` 5
## Reading cost, chunk 3cc43a838262, finished 2026-11-18T09:22:31Z
57869 new input tokens before the first commit.
Read most (opens and searches):
- `CLAUDE.md` 5
- `skills/larv-review/SKILL.md` 4
- `docs/decisions.md` 1
## Reading cost, chunk e880525b42ae, finished 2026-11-18T09:56:42Z
89443 new input tokens before the first commit.
Read most (opens and searches):
- `README.md` 6
- `bin/plan_store/jira_epic.py` 6
- `bin/plan_store/test_jira_epic.py` 5
- `.gitignore` 4
- `bin/atlassian/client.py` 3
- `bin/plan_store/contract.py` 2
- `docs/decisions.md` 2
- `bin/adf_codec/convert.py` 1
- `bin/do_epic/backend/contract.py` 1
- `bin/do_epic/backend/protocol.py` 1
## Reading cost, chunk 3312afb8e236, finished 2026-11-18T11:56:17Z
502050 new input tokens before the first commit.
Read most (opens and searches):
- `README.md` 14
- `bin/project_config/settings.py` 13
- `docs/decisions.md` 10
- `bin/project_config/main.py` 9
- `.gitignore` 7
- `skills/larv-review/SKILL.md` 7
- `bin/project_config/test_project_config.py` 6
- `bin/model_routing/ladder.py` 3
- `ci.sh` 3
- `docs/reading-cost.md` 3
+1 -12
View File
@@ -12,11 +12,10 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 407 | 0.12.0 | | | **Find an epic repo's checkout and project config by the repo's name, clone a missing one from the host of the epic's other repos, and ask the human where unsure.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 401 | 0.12.0 | | | **Move loop-claude's cycle, judge, interrupt, tmux and routing into a package a second entry point drives, with loop-claude's behaviour unchanged.** | 3 | 2 | 3 | 6 | 6 | 1 by 3, code health by 2 | 1.8 |
| 406 | 0.12.0 | | | **Pick each epic item's repo, or for an item without one whether it is Claude's work or a human task, by `repo-rule.md`, record the pick on the issue, and ask the human where the rule leaves it unclear.** | 2 | 2 | 2 | 4 | 4 | 1 by 5 | 1.6 |
| 408 | 0.12.0 | | | **Rank an epic's items by one weight chain, the epic's achieve goals, then code health, then the item's repo goals, then by Blocked by, and re-rank Jira's backlog to match, with people's issues keeping their rank.** | 3 | 2 | 2 | 5 | 4 | 1 by 5 | 1.6 |
| 410 | 0.12.0 | 401, 406, 407, 408 | | **Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.** | 3 | 2 | 3 | 6 | 6 | 1 by 5 | 0.8 |
| 410 | 0.12.0 | 401, 406, 408 | | **Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.** | 3 | 2 | 3 | 6 | 6 | 1 by 5 | 0.8 |
| 416 | 0.12.0 | 410 | | **Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.** | 1 | 1 | 1 | 1 | 2 | 1 by 5 | 2.1 |
| 413 | 0.12.0 | 410 | | **File a finding about an epic goal in the epic and one about a repo goal by that repo's rules, ask the human where unsure which, and give the judge the epic's records beside the repo's.** | 3 | 2 | 3 | 6 | 4 | 1 by 5 | 1.6 |
| 415 | 0.12.0 | 410, 413 | | **Finish an epic: run release-review passes on each repo it changed, work what they file, have the human confirm each goal, post a summary comment, and close the epic in Jira last.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
@@ -84,16 +83,6 @@
## Details
### 407. Find an epic repo's checkout and project config by the repo's name, clone a missing one from the host of the epic's other repos, and ask the human where unsure.
Unsure means the epic's other repos sit on more than one host, or the clone fails (`docs/decisions.md` → `do-epic: drives one Jira epic …`). A by-name lookup goes beside `held` and `load`.
Touches:
- `bin/project_config/settings.py`: `held` (small)
- `bin/forge/commands.py`: `forge_of` (small)
- `bin/do_epic/repos.py`
### 401. Move loop-claude's cycle, judge, interrupt, tmux and routing into a package a second entry point drives, with loop-claude's behaviour unchanged.
do-epic runs on these, not on a copy (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Move the reusable modules into `bin/agent_cycle/`: `tmux`, `judge`, `interrupt`, `verdicts`, `retry`, `spend`, `worker`, `states`, `stop`, and the parts of `routing` that take a `ProjectRung` and a `Route`. Keep `routed_item`, `loop/`, `project/`, `escalation_mark` and `chunk_items` in `loop_claude`. Decouple `cycle/run.py`'s archive and `Chunk items:` handling, and `cycle/prompts.py`'s goals-file and `todo.md` names, behind parameters. The places the comprehension seats found hard here, `routing.py` `unfinished_route` and `cycle/judge.py` `quotes_checked`, must read no harder after the move.