Merge remote-tracking branch origin/main into item-299
CI / tests (pull_request) Successful in 3m59s

This commit is contained in:
2026-11-18 14:09:25 +01:00
15 changed files with 710 additions and 47 deletions
+2
View File
@@ -2,6 +2,8 @@
## 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.
- Fix for an outside reviewer's comment on a PR now ends with a change to the setup that would have caught it, in claude-config first, then the principles and standards, then the project.
+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 `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.
+82
View File
@@ -0,0 +1,82 @@
"""do-epic's machine-wide settings: `~/.claude-projects/do-epic/config.toml`, and `repo-rule.md` beside it.
One pair per machine, the same for every epic (docs/decisions.md → `do-epic: drives one Jira epic …`). The config is TOML:
jira-url = "https://acme.atlassian.net"
env-file = "~/.secrets/acme-jira.env"
repoless-model = "claude-opus-5-5"
clone-folder = "~/code"
language = "Swedish"
- `jira-url` is the Jira site's address: https, a host, and no path.
- `env-file` is the file of Jira credentials: a path that starts with / or ~/, outside every folder of `~/.claude-projects` and outside the clone folder, which hold git checkouts. `~/.claude-projects/<key>.env` is fine.
- `repoless-model` is the model that works an epic item with no repo: a model on the routing ladder, `model_routing/routing-ladder.json`.
- `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.
- `repo-rule.md` is prose that says how to tell an item's repo, and mustn't be blank."""
import dataclasses
import pathlib
import re
from project_config.settings import anywhere, CONFIG, DO_EPIC, ENV_FILE, LANGUAGE, language_fault, lies_in, parsed, PROJECTS, SITE
from failure import Failure
from model_routing.ladder_file import read_ladder, SHIPPED
REPO_RULE = "repo-rule.md"
# Three readers, seated as the human who writes this config, picked these spellings from four candidates each, 3-0: `jira-url` over `site`, `clone-folder` over `repos-folder` (which reads as the folder of repos that already exist) and `repoless-model` over `no-repo-model`. `env-file` and `language` keep the names a project's config gives them.
JIRA_URL = "jira-url"
REPOLESS_MODEL = "repoless-model"
CLONE_FOLDER = "clone-folder"
SETTINGS = (JIRA_URL, ENV_FILE, REPOLESS_MODEL)
OPTIONAL = (CLONE_FOLDER, LANGUAGE)
LISTED = f"The settings are {', '.join(SETTINGS)}, and optionally {' and '.join(OPTIONAL)}."
@dataclasses.dataclass(frozen=True)
class DoEpicConfig:
"""folder is `~/.claude-projects/do-epic`; repo_rule is `repo-rule.md`'s text."""
folder: pathlib.Path
jira_url: str
env_file: pathlib.Path
clone_folder: pathlib.Path
language: str
repoless_model: str
repo_rule: str
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
values = parsed(folder / CONFIG)
if isinstance(values, Failure):
return Failure(f"{values.reason}. {LISTED}")
ladder = read_ladder(ladder_file)
if isinstance(ladder, Failure):
return ladder
models = sorted({rung.model for rung in ladder.rungs})
rule: str | Failure
try:
rule = (folder / REPO_RULE).read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as failure:
rule = Failure(f"cannot read {folder / REPO_RULE}: {failure}")
config_folders = [path for path in (home / PROJECTS).iterdir() if path.is_dir()]
clone_folder = anywhere(values.get(CLONE_FOLDER, "~/code"), home)
env_file = anywhere(values.get(ENV_FILE), home)
language = values.get(LANGUAGE, "English")
url, model = values.get(JIRA_URL), values.get(REPOLESS_MODEL)
faults = [
*(f"`{name}` is missing" for name in SETTINGS if name not in values),
*(f"`{name}` is not a setting" for name in values if name not in (*SETTINGS, *OPTIONAL)),
*([f"`{JIRA_URL}` is {url!r}, not a site's https address without a path, such as \"https://acme.atlassian.net\""] if JIRA_URL in values and not (isinstance(url, str) and re.fullmatch(SITE, url)) else []),
*([f"`{CLONE_FOLDER}` is {values[CLONE_FOLDER]!r}, not a path that starts with / or ~/"] if clone_folder is None else []),
*([f"`{ENV_FILE}` is {values[ENV_FILE]!r}, not a path that starts with / or ~/"] if ENV_FILE in values and env_file is None else []),
*([f"`{ENV_FILE}` is {values[ENV_FILE]!r}, inside a folder of ~/{PROJECTS} or the clone folder, which hold git checkouts"] if env_file and lies_in(env_file, *config_folders, *([clone_folder] if clone_folder else [])) else []),
*([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 []),
*([rule.reason] if isinstance(rule, Failure) else [f"`{REPO_RULE}` is blank"] if not rule.strip() else []),
]
if faults:
return Failure(f"{folder}: {'; '.join(faults)}. {LISTED}")
# Without a fault, each value above is present and of the type asserted here.
assert clone_folder and env_file and isinstance(url, str) and isinstance(model, str) and isinstance(language, str) and isinstance(rule, str)
return DoEpicConfig(folder, url, env_file, clone_folder, language, model, rule)
+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
+132
View File
@@ -0,0 +1,132 @@
import pathlib
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.config import DoEpicConfig, load
from failure import Failure
SETTINGS = """jira-url = "https://acme.atlassian.net"
env-file = "~/jira.env"
repoless-model = "claude-opus-5-5"
"""
class ConfigTest(unittest.TestCase):
def setUp(self) -> None:
made = tempfile.TemporaryDirectory()
self.addCleanup(made.cleanup)
self.home = pathlib.Path(made.name).resolve()
self.folder = self.home / ".claude-projects" / "do-epic"
self.folder.mkdir(parents=True)
def write(self, settings: str | None = SETTINGS, rule: str | None = "A label that equals a repo's name names that repo.\n") -> None:
if settings is not None:
(self.folder / "config.toml").write_text(settings, encoding="utf-8")
if rule is not None:
(self.folder / "repo-rule.md").write_text(rule, encoding="utf-8")
def failure(self) -> str:
found = load(self.home)
assert isinstance(found, Failure), found
return found.reason
def test_reads_the_settings_and_the_rule_and_defaults_the_clone_folder_and_language(self) -> None:
self.write()
self.assertEqual(load(self.home), DoEpicConfig(self.folder, "https://acme.atlassian.net", self.home / "jira.env", self.home / "code", "English", "claude-opus-5-5", "A label that equals a repo's name names that repo.\n"))
def test_reads_a_clone_folder_and_language_the_config_sets(self) -> None:
self.write(SETTINGS + 'clone-folder = "/srv/repos"\nlanguage = "Brazilian Portuguese"\n')
found = load(self.home)
assert isinstance(found, DoEpicConfig), found
self.assertEqual((found.clone_folder, found.language), (pathlib.Path("/srv/repos"), "Brazilian Portuguese"))
def test_refuses_while_the_config_is_missing(self) -> None:
self.write(None)
self.assertIn(f"cannot read {self.folder / 'config.toml'}", self.failure())
def test_lists_the_settings_where_the_config_is_missing(self) -> None:
self.write(None)
self.assertIn("The settings are jira-url, env-file, repoless-model", self.failure())
def test_refuses_while_the_rule_is_missing(self) -> None:
self.write(rule=None)
self.assertIn(f"cannot read {self.folder / 'repo-rule.md'}", self.failure())
def test_refuses_while_the_rule_is_blank(self) -> None:
self.write(rule=" \n")
self.assertIn("`repo-rule.md` is blank", self.failure())
def test_a_missing_rule_does_not_hide_the_settings_faults(self) -> None:
self.write(SETTINGS.replace("claude-opus-5-5", "x"), rule=None)
self.assertIn("`repoless-model` is 'x'", self.failure())
def test_names_each_missing_setting(self) -> None:
self.write("")
reason = self.failure()
for name in ("jira-url", "env-file", "repoless-model"):
self.assertIn(f"`{name}` is missing", reason)
def test_names_a_setting_it_does_not_know(self) -> None:
self.write(SETTINGS + 'checkout = "~/code/acme"\n')
self.assertIn("`checkout` is not a setting", self.failure())
def test_names_each_misspelt_value(self) -> None:
for line, name in (
('jira-url = "http://acme.atlassian.net"', "jira-url"),
('jira-url = "https://acme.atlassian.net/"', "jira-url"),
('env-file = "jira.env"', "env-file"),
('clone-folder = "code"', "clone-folder"),
('language = "sv_SE"', "language"),
('repoless-model = "opus"', "repoless-model"),
('repoless-model = "claude-opsu-5-5"', "repoless-model"),
):
with self.subTest(line):
self.write("\n".join([ln for ln in SETTINGS.splitlines() if not ln.startswith(name)] + [line]))
self.assertIn(f"`{name}` is", self.failure())
def test_keeps_the_credentials_outside_every_config_folder_and_the_clone_folder(self) -> None:
(self.home / ".claude-projects" / "acme").mkdir()
for env_file in ("~/.claude-projects/do-epic/jira.env", "~/.claude-projects/acme/jira.env", "~/code/acme/jira.env"):
with self.subTest(env_file):
self.write(SETTINGS.replace("~/jira.env", env_file))
self.assertIn("`env-file` is", self.failure())
def test_keeps_the_credentials_outside_a_clone_folder_the_config_sets(self) -> None:
self.write(SETTINGS.replace("~/jira.env", "~/clones/jira.env") + 'clone-folder = "~/clones"\n')
self.assertIn("`env-file` is", self.failure())
def test_accepts_credentials_beside_the_config_folders(self) -> None:
self.write(SETTINGS.replace("~/jira.env", "~/.claude-projects/do-epic.env"))
found = load(self.home)
assert isinstance(found, DoEpicConfig), found
self.assertEqual(found.env_file, self.home / ".claude-projects" / "do-epic.env")
def test_refuses_while_the_routing_ladder_cannot_be_read(self) -> None:
self.write()
found = load(self.home, self.home / "no-ladder.json")
assert isinstance(found, Failure), found
self.assertIn("no-ladder.json", found.reason)
def test_reports_every_fault_at_once(self) -> None:
self.write('jira-url = "acme"\nrepoless-model = "x"\n')
reason = self.failure()
for part in ("`jira-url` is", "`env-file` is missing", "`repoless-model` is"):
self.assertIn(part, reason)
self.assertIn("`env-file` is missing; `jira-url` is", reason, "joined by semicolons")
def test_names_the_models_on_the_ladder_where_the_model_is_off_it(self) -> None:
ladder = self.home / "ladder.json"
ladder.write_text('[{"model": "claude-sonnet-5-5", "effort": "low"}, {"model": "claude-opus-5-5", "effort": "low"}]', encoding="utf-8")
self.write(SETTINGS.replace("claude-opus-5-5", "claude-haiku-5-5"))
found = load(self.home, ladder)
assert isinstance(found, Failure), found
self.assertIn("not a model on the routing ladder: claude-opus-5-5, claude-sonnet-5-5.", found.reason)
def test_reads_the_rule_and_the_settings_as_utf8(self) -> None:
self.write(SETTINGS + 'language = "Svenska"\n', rule="Etiketten är repots namn.\n")
found = load(self.home)
assert isinstance(found, DoEpicConfig), found
self.assertEqual(found.repo_rule, "Etiketten är repots namn.\n")
+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) + "]"
+3
View File
@@ -6,6 +6,9 @@ Run inside a checkout, or a worktree of one. It finds the config that names the
~/.claude-projects/<key>/config.toml, and prints each setting and its absolute path, as in
`plan: /home/me/code/acme/todo.md`. Given a setting, it prints only that setting's path.
`~/.claude-projects/do-epic/` holds do-epic's machine-wide settings, not a project's. It needs no `checkout`,
and project-config doesn't read anything from it, so no project may use `do-epic` as its key.
The config is TOML. `checkout` names the project's main checkout, and every setting in the example below is a path:
"checkout:<path>" inside the checkout, "folder:<path>" inside the config's own folder, or one that
starts with / or ~/. In a worktree, a "checkout:" path is the worktree's own file.
+43 -13
View File
@@ -17,6 +17,10 @@ from plan.ranking import variables
PROJECTS = ".claude-projects"
CONFIG = "config.toml"
# The key of do-epic's machine-wide settings: the folder's config.toml has no `checkout`, so no project may use the key.
DO_EPIC = "do-epic"
# A Jira Cloud or Confluence Cloud site's address: only https, so the credentials are never sent in the clear.
SITE = r"https://[A-Za-z0-9.-]+(?::[0-9]+)?"
# Every path a project sets, by its role. Three readers, seated as the human who writes the config, picked the spelling from four candidates. They picked role names over file names, which a client's project doesn't share.
SETTINGS = ("plan", "working-rules", "decisions", "score-anchors", "comprehension-history", "reading-cost", "changelog", "goals-and-audience", "principles", "standards")
# They also picked a prefix over bare relative paths: each line says its own place, and a relative path with no prefix fails instead of landing somewhere by default.
@@ -177,7 +181,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
top is the worktree that asks, and main itself outside a worktree. A `checkout:` path lands in top.
A config that cannot be read fails every project, since it may be the one that names main."""
named: list[tuple[pathlib.Path, dict[str, object]]] = []
for file in sorted((home / PROJECTS).glob(f"*/{CONFIG}")):
for file in configs(home):
config = read(file, home)
if isinstance(config, Failure):
return config
@@ -290,14 +294,14 @@ def name_of(value: object) -> str | None:
def epic_of(value: object) -> Epic | None:
"""The epic a setting's value spells; None where it spells none. Only https, so the credentials are never sent in the clear."""
spelt = isinstance(value, str) and re.fullmatch(rf"{JIRA}(https://[A-Za-z0-9.-]+(?::[0-9]+)?)/browse/([A-Z][A-Z0-9_]*-[0-9]+)", value)
"""The epic a setting's value spells; None where it spells none."""
spelt = isinstance(value, str) and re.fullmatch(rf"{JIRA}({SITE})/browse/([A-Z][A-Z0-9_]*-[0-9]+)", value)
return Epic(spelt.group(1), spelt.group(2)) if spelt else None
def page_of(value: object) -> Page | None:
"""The page a setting's value spells; None where it spells none. Only https, as for an epic."""
spelt = isinstance(value, str) and re.fullmatch(rf"{CONFLUENCE}(https://[A-Za-z0-9.-]+(?::[0-9]+)?)/wiki/spaces/[^/?#]+/pages/([0-9]+)(?:/[^/?#]*)?", value)
"""The page a setting's value spells; None where it spells none."""
spelt = isinstance(value, str) and re.fullmatch(rf"{CONFLUENCE}({SITE})/wiki/spaces/[^/?#]+/pages/([0-9]+)(?:/[^/?#]*)?", value)
return Page(spelt.group(1), spelt.group(2), spelt.string) if spelt else None
@@ -339,25 +343,51 @@ def lies_in(path: pathlib.Path, *places: pathlib.Path) -> bool:
def held(folder: pathlib.Path, home: pathlib.Path) -> ProjectConfig | Failure | None:
"""The config in folder, read as its project's main checkout reads it; None where folder is not a config's folder under home."""
# Matched on resolved paths, as git names a folder, so a config's folder reached through a symlink is still found.
file = next((file for file in (home / PROJECTS).glob(f"*/{CONFIG}") if file.parent.resolve() == folder.resolve()), None)
file = next((file for file in configs(home) if file.parent.resolve() == folder.resolve()), None)
if file is None:
return None
config = read(file, home)
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)
def env_files(home: pathlib.Path) -> list[pathlib.Path]:
"""Every config's env-file, read without the checks load makes, so a config that fails them still keeps its credentials guarded; a config that cannot be read names none."""
configs = [read(file, home) for file in sorted((home / PROJECTS).glob(f"*/{CONFIG}"))]
return [path for config in configs if not isinstance(config, Failure) and (path := anywhere(config[1].get(ENV_FILE), home))]
"""Every config's env-file, do-epic's included. Each is read without the checks load makes, so a config that fails them still keeps its credentials guarded. A config that can't be read doesn't name one."""
values = [parsed(file) for file in (*configs(home), home / PROJECTS / DO_EPIC / CONFIG)]
return [path for found in values if not isinstance(found, Failure) and (path := anywhere(found.get(ENV_FILE), home))]
def parsed(file: pathlib.Path) -> dict[str, object] | Failure:
"""The TOML values in file; a Failure where file can't be read or parsed."""
try:
return tomllib.loads(file.read_text(encoding="utf-8"))
except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError) as failure:
return Failure(f"cannot read {file}: {failure}")
def read(file: pathlib.Path, home: pathlib.Path) -> tuple[pathlib.Path, dict[str, object]] | Failure:
"""The checkout a config names, as an absolute path, and its other values."""
try:
values = tomllib.loads(file.read_text(encoding="utf-8"))
except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError) as failure:
return Failure(f"cannot read {file}: {failure}")
values = parsed(file)
if isinstance(values, Failure):
return values
checkout = anywhere(values.get("checkout"), home)
if checkout is None:
found = f"not {values['checkout']!r}" if "checkout" in values else "and is missing"
+42 -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
@@ -91,6 +91,13 @@ class LoadTest(ConfigCase):
self.assertEqual(found.paths["standards"], self.home / ".claude" / "skills" / "larv-review" / "standards")
self.assertEqual(tuple(found.paths), SETTINGS)
def test_the_do_epic_folder_is_no_projects_config_so_it_needs_no_checkout(self) -> None:
self.write("do-epic", 'jira-url = "https://acme.atlassian.net"\n')
self.write("acme", CLIENT)
found = load(self.checkout, self.checkout, self.home)
assert isinstance(found, ProjectConfig), found
self.assertEqual(found.key, "acme")
def test_a_plan_spelt_as_a_jira_epic_is_no_path(self) -> None:
self.write("acme", JIRA_CLIENT)
found = load(self.checkout, self.checkout, self.home)
@@ -578,6 +585,10 @@ class HeldTest(ConfigCase):
(elsewhere / "config.toml").write_text(CLIENT, encoding="utf-8")
self.assertIsNone(held(elsewhere, self.home), "a config.toml outside ~/.claude-projects/")
def test_the_do_epic_folder_holds_no_projects_config(self) -> None:
folder = self.write("do-epic", CLIENT)
self.assertIsNone(held(folder, self.home))
def test_a_configs_folder_reached_through_a_symlink_holds_its_config(self) -> None:
target = self.home / "kept" / "acme"
target.mkdir(parents=True)
@@ -587,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')
@@ -595,6 +632,10 @@ class EnvFilesTest(ConfigCase):
self.write("none", CLIENT)
self.assertEqual(env_files(self.home), [self.home / "acme.env", pathlib.Path("/srv/other.env")])
def test_lists_do_epics_env_file_though_its_config_names_no_checkout(self) -> None:
self.write("do-epic", 'env-file = "~/jira.env"\n')
self.assertEqual(env_files(self.home), [self.home / "jira.env"])
class ToolTest(ConfigCase):
def test_prints_a_jira_plan_as_the_config_spells_it(self) -> None:
+1 -1
View File
@@ -1,6 +1,6 @@
"""Whether a Read or a Grep reads a credentials file, or a Bash command names it or searches a folder holding it, for the `env-file-read` rule.
The files are `~/.claude/.env` and every config's `env-file`, not only the calling project's: a worker in one client's project must not read another client's credentials either, and listing every config's file needs no git call, as finding the calling project's would.
The files are `~/.claude/.env` and every config's `env-file`, do-epic's included, not only the calling project's: a worker in one client's project must not read another client's credentials either, and listing every config's file needs no git call, as finding the calling project's would.
A Bash command names one where its text spells the file's path, or one of its words, a redirect's target included, leads to the file from the directory `cd` left the command in. Whether the command reads the file is not judged, so one that only mentions the path is refused too.
It searches a folder holding one where `folder_search.searches` finds that an `ag`, `grep -r` or `rg` reaches the file.
This guards against an agent reading the file in passing, not against one that hides the path, such as behind a glob, a variable of its own, `xargs` or `find -exec`."""
+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
+55 -27
View File
@@ -6,33 +6,34 @@
`Bar = 0.1`
`Next ID = 421`
`Next ID = 424`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 404 | 0.12.0 | | | **Read do-epic's machine-wide settings from `~/.claude-projects/do-epic/config.toml` and its prose repo rule from `repo-rule.md` beside it, and refuse to start while either is missing or misspelt.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 407 | 0.12.0 | 404 | | **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 | 404 | | **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 |
| 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, 404, 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 |
| 418 | 0.12.0 | 415 | | **Describe do-epic in `README.md`'s tools and setup, with its machine settings and `repo-rule.md`.** | 1 | 2 | 1 | 2 | 2 | 1 by 5 | 2.1 |
| 400 | 0.12.0 | | | **Forbid a test that decides at run time whether to check anything in `principles/technical-principles.md`, and point stability-reviewer's Tests checks at it.** | 1 | 2 | 3 | 4 | 2 | 1.1 by 5 | 2.0 |
| 420 | 0.12.0 | | | **End a worker that printed its final result and lingers, by killing the background shells it left, after a few minutes, and print each kill with its evidence on loop-claude's terminal.** | 2 | 2 | 2 | 4 | 3 | 1.5 by 6 | 2.0 |
| 409 | 0.12.0 | 406 | | **Split an epic item that changes several repos into one Jira sub-task per repo, each labelled for its repo, with the parent tracking the whole change, when do-epic plans the item.** | 2 | 2 | 3 | 5 | 3 | 1 by 5 | 1.9 |
| 411 | 0.12.0 | 410 | | **Park a chunk whose PR waits on a long gate, keeping its worktree, PR and session in a state file that survives a reboot, and resume its session when the gate passes or a reviewer comments.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 412 | 0.12.0 | 410, 411 | | **Print each chunk of an epic, running, parked with its gate and since when, or stopped, each human task and each open interrupt with `do-epic <key> --status`, and name a parked chunk's gate in its tmux window's name.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 414 | 0.12.0 | 410 | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 417 | 0.12.0 | 410 | | **Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 421 | 0.12.0 | | | **Refuse in rule-hook a Bash or Monitor wait that has no end: a loop without a time or count cap, and a `pgrep -f` or `pkill -f` whose pattern the same command line contains.** | 2 | 2 | 3 | 5 | 3 | 1.5 by 4 | 1.3 |
| 299 | 0.12.0 | | | **Replay the archived judge verdicts through code rules and a classifier trained locally on the archive, and file an item for each verdict kind one of them decides with no missed interrupt.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3 | 1.0 |
| 311 | 0.12.0 | | | **Hand each worker's claude a Bash output ceiling that saves longer output to a file, and refuse a Read of a session transcript under `~/.claude/projects`.** | 2 | 2 | 3 | 5 | 3 | 1.4 by 3 | 1.0 |
| 316 | 0.12.0 | | | **Launch comprehension seats as an agent type of their own under `agents/`, without `CLAUDE.md` and the skill and agent listings a general-purpose subagent carries.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3 | 1.0 |
| 310 | 0.12.0 | | | **Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.** | 3 | 2 | 3 | 6 | 4 | 1.4 by 3 | 0.9 |
| 420 | 0.13.0 | | question | **Skip the judge's model call on a worker's final message that the offline classifier decides is finished, once lilleman rules that its miss rate of about 1 in 100 decided is close enough to no missed interrupt.** | 3 | 3 | 3 | 7 | 5 | 1.4 by 2 | 0.4 |
| 422 | 0.12.0 | 401, 420 | | **Check every 5 minutes whether a tmux window of the loop looks stuck by other signs than a lingering worker, investigate it with a headless claude, and kill only the process the investigation names.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 4 | 0.8 |
| 423 | 0.13.0 | | question | **Skip the judge's model call on a worker's final message that the offline classifier decides is finished, once lilleman rules that its miss rate of about 1 in 100 decided is close enough to no missed interrupt.** | 3 | 3 | 3 | 7 | 5 | 1.4 by 2 | 0.4 |
| 365 | 0.13.0 | | | **Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
| 368 | 0.13.0 | | | **Call a release review due, call a release ready to cut, and tell whether a chunk owes a scoring run, for a plan outside the checkout, from the project repo's history or from Jira.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
| 309 | 0.13.0 | | | **Run a scoring run's second pass on one head with two seats in place of four, once `larv-review agreement` shows the seats agree with each other more than a run agrees with its rerun.** | 2 | 2 | 2 | 4 | 2 | 1.4 by 3 | 1.2 |
@@ -83,26 +84,6 @@
## Details
### 404. Read do-epic's machine-wide settings from `~/.claude-projects/do-epic/config.toml` and its prose repo rule from `repo-rule.md` beside it, and refuse to start while either is missing or misspelt.
Settings: the Jira site, `env-file`, the folder repos are cloned into (`~/code` by default), the default language, and the model for a no-repo item (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Reuse `project_config/settings.py`'s parsing helpers: `read`, `anywhere`, `Scalar`, `language_fault`, and the `env-file` check that keeps credentials outside a checkout.
Touches:
- `bin/project_config/settings.py`: `read`, `anywhere`, `language_fault` (small)
- `bin/project_config/main.py`: `main` (small)
- `bin/do_epic/config.py`
### 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.
@@ -214,6 +195,22 @@ Touches:
- `principles/technical-principles.md`: the tests bullet group, `A valuable test checks behaviour` (small)
- `agents/stability-reviewer.md`: `### 11. Tests` (small)
### 420. End a worker that printed its final result and lingers, by killing the background shells it left, after a few minutes, and print each kill with its evidence on loop-claude's terminal.
On 2026-11-18 the worker of the item 402 chunk merged its pull request at about 11:47, printed its summary and then waited 95 minutes: it had started `until [ -s /tmp/merge-402.log ] && ! pgrep -f "chunk-pr merg"; do sleep 15; done` in the background, and `pgrep -f` matched the loop's own command line, so the condition never held. Its `claude -p` stayed alive ("Waiting for background work to finish"), `loop-claude` waited for it to exit, and the window's slot started no new chunk until the human found it and killed the shell.
Every 5 minutes loop-claude checks each worker it runs: when the worker's last transcript entry is its final result and its `claude -p` is still alive more than 3 minutes later, it kills the background shells that are children of that process, and the worker then exits. Nothing else is killed: no worker that is still working, no process of another session, and no window with a sign short of this one. A worker whose shell is still writing output or holds a `run-heavy` slot is left alone. Each kill is printed on loop-claude's terminal with the process, its age and its command, and appended to the judge's records so the pattern can become a rule-hook ban (item 421). Item 422 handles the vaguer signs of a stuck window.
The check lives in the main run beside the other per-cycle work; item 401 moves that code into a package, and a conflict with it is cheaper than waiting for it.
Before building the check, try the platform's own bound: Claude Code documents `BASH_MAX_TIMEOUT_MS` and `BASH_DEFAULT_TIMEOUT_MS` as the time limit of a background command, 10 minutes by default in `claude -p` (docs: code.claude.com/docs/en/headless.md and env-vars). Nothing in this repo sets them, yet the lingering shell ran 95 minutes on Claude Code 2.1.327, so first find out why the limit did not apply (an explicit timeout in the worker's call, or a gap in the docs). Hand the workers a cap through those variables where that bounds the wait, and build the lingering-worker check only for what the cap leaves.
Touches:
- `bin/loop_claude/loop/main.py`: `run_loop` (small)
- `bin/loop_claude/loop/lingering_workers.py`
- `README.md`: loop-claude's section (small)
### 409. Split an epic item that changes several repos into one Jira sub-task per repo, each labelled for its repo, with the parent tracking the whole change, when do-epic plans the item.
do-epic predicts the repos from the code, as `Touches:` predictions are made. A person's issue is split too, with a comment for the team in the epic's language (`docs/decisions.md` → `do-epic: drives one Jira epic …`). The parent is finished once every sub-task is.
@@ -265,6 +262,23 @@ Touches:
- `bin/do-epic-e2e`
- `bin/do_epic/e2e/`
### 421. Refuse in rule-hook a Bash or Monitor wait that has no end: a loop without a time or count cap, and a `pgrep -f` or `pkill -f` whose pattern the same command line contains.
On 2026-11-18 a worker in the item 402 chunk started `until [ -s /tmp/merge-402.log ] && ! pgrep -f "chunk-pr merg"; do sleep 15; done` in the background. The `pgrep -f` pattern is part of the loop's own command line, so it matched itself and the loop never ended; the worker's `claude -p` waited on it for 95 minutes and its slot started no new chunk (item 420 ends such a worker; item 422 handles other stuck windows). A wait that cannot end is cheaper to refuse before it starts.
rule-hook refuses a Bash command, or a Monitor call, that starts a wait of either kind. A loop (`until`, `while`, `for`) that sleeps and has neither a time limit (`timeout`, a deadline compared with `date`) nor a bounded count (`for i in $(seq …)`); `~/.claude/bin/wait-for` always passes, since it takes `--timeout`. A `pgrep -f` or `pkill -f` whose pattern text also appears in the command line that holds it, quoted or not, so it can match its own shell. The refusal names which kind it found and says to use `wait-for <file> [<pattern>] --timeout <seconds>`, or a `pgrep -x` on the process name.
`settings.json` hooks only `Agent|Bash|Edit|Grep|MultiEdit|Read|Skill|Write`, so rule-hook never sees a Monitor call: add `Monitor` to that matcher, and have rule-hook read a Monitor call's command as it reads a Bash one. Claude Code 2.1.314 and later send Monitor-started commands to a PreToolUse hook; a hook's allow and updatedInput are ignored for them, so rule-hook can refuse but not rewrite (docs: code.claude.com/docs/en/hooks.md).
The test covers each kind refused, a bounded loop that passes, `wait-for` passing, and a `pgrep -f` on a pattern absent from the command passing. The rule's reason goes in rule-hook's rule table beside the other rules.
Touches:
- `bin/rule_hook/rules.py`: the rule table (small)
- `bin/rule_hook/endless_wait.py`
- `bin/rule_hook/test_rule_hook.py`: the new rule's tests (small)
- `settings.json`: the PreToolUse matcher (small)
### 299. Replay the archived judge verdicts through code rules and a classifier trained locally on the archive, and file an item for each verdict kind one of them decides with no missed interrupt.
The judge's LLM still decides three things: the verdict kind, the escalation it quotes, and whether a release is ready to cut (`docs/decisions.md` → `routing: loop-claude reads the items a chunk takes …`). This item replays the verdict kind. No single rule found so far separates interrupts: a "?" in the worker's final message appears in 48 interrupts and misses 66. A smaller LLM already failed the replay (`docs/decisions.md` → `routing: on a model judge-replay covered, …`: Sonnet returned another kind on 3 interrupts, Haiku missed 7). Untested are combined code rules, a decision table, and a small classifier trained and run on this machine on the archived verdicts (372 finished, 234 interrupt, 42 unfinished, 20 quoted). Run each offline, nothing sent to an outside service (goal 4), and count disagreements by kind; the bar is zero missed interrupts. A hosted decision model is out of scope, since it would send transcripts to an outside service.
@@ -322,7 +336,21 @@ Touches:
- `bin/loop_claude/test_loop_claude.py`: `FakeEffects`, `Interrupts`
- `bin/loop_effects/test_effects.py`
### 420. Skip the judge's model call on a worker's final message that the offline classifier decides is finished, once lilleman rules that its miss rate of about 1 in 100 decided is close enough to no missed interrupt.
### 422. Check every 5 minutes whether a tmux window of the loop looks stuck by other signs than a lingering worker, investigate it with a headless claude, and kill only the process the investigation names.
Item 420 ends a worker that printed its final result and lingers. A window can also stall earlier: a test run that hangs on a shell ignoring SIGINT (item 402's first full run), a pane with no output while its process tree does no work, or a background shell older than the chunk's usual length.
Every 5 minutes loop-claude lists its own session's windows and, for one with such a sign, launches a headless claude on the project's rung that reads the pane, the process tree and the chunk's log files and returns `working`, `waiting on a person` or `stuck`, with the process that holds the window and why. Only `stuck` kills, and only the named process, never the worker or the loop. A window waiting on a gate (`run-heavy`, a test run that still writes output) or on the human's answer is not `stuck`. Each check and kill is printed on loop-claude's terminal with the evidence.
Run it first as a report that kills nothing, and turn the kill on once its verdicts over a few days match what the human would have done; record that in the item's decision. Blocked by 401, which moves loop-claude's cycle into a package; this item lands in the package.
Touches:
- `bin/loop_claude/loop/stuck_windows.py`
- `bin/loop_claude/tmux.py`: `Listed`, `listed`
- `README.md`: loop-claude's section (small)
### 423. Skip the judge's model call on a worker's final message that the offline classifier decides is finished, once lilleman rules that its miss rate of about 1 in 100 decided is close enough to no missed interrupt.
Question for lilleman: is a miss rate of about 1 in 100 decided close enough to none? A missed interrupt lets a worker settle a decision that is yours, unasked. Until you rule, the judge's model keeps the verdict kind (`docs/decisions.md` → `routing: the judge's model keeps the verdict kind until lilleman rules on the offline classifier …`).