Score an epic's items by one chain of goals and order them by score, then blockers #610

Merged
lilleman merged 15 commits from item-408 into main 2026-11-18 17:10:15 +01:00
6 changed files with 322 additions and 16 deletions
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- do-epic's scorer orders an epic's items by score, then by Blocked by: an item's Moves names a goal as `epic 1.1`, `code health` or `repo 2`, and the epic's achieve goals outweigh the achieve goals of every repo. Nothing calls it yet.
- `todo-item add` and `todo-item edit --detail` refuse a detail whose `Touches:` list touch-predictions cannot read, and `rank_todo.py --check` fails on each item holding one, so rule-hook refuses a commit of such a plan: after updating, run `~/.claude/bin/rank_todo.py --check` in each project and fix each list it names.
- loop-claude hands each worker's claude a Bash output ceiling of 6,000 characters that saves a longer result to a file, rule-hook refuses a Read of a session transcript under ~/.claude/projects, and review-replay takes --bash-ceiling and --read-limit to test such a limit against archived review rounds.
- do-epic picks each epic item's repo, or that it is Claude's work or a human task, by repo-rule.md and a headless claude call, records the pick as a label on the issue and reads it back without a new call; where the rule leaves it unclear it returns a question for the human. The epic backends gain a label write.
+1 -1
View File
@@ -213,7 +213,7 @@ 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`. `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`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `backend/` reads and files the epic's issues and adds those labels.
- `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`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `ranking.py` orders an epic's items by score over one chain of goals, the epic's, then code health, then the item's repo's, through `plan`'s ranking. `backend/` reads and files the epic's issues and adds those labels.
- `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.
+128
View File
@@ -0,0 +1,128 @@
"""The order do-epic works an epic's items in: by score, then each blocker above what it blocks (docs/decisions.md → `do-epic: drives one Jira epic …`).
An item scores by the epic's formula over one chain of goals: the epic's goals, then code health, then the goals of the item's repo. An item without a repo has only the epic's goals. Each achieve goal weighs 0.97 of the one above it in the chain, and the epic's achieve goals weigh the same in every repo, so an achieve goal of the epic outweighs every achieve goal of a repo, whichever repos the two items are in. chain_scoring says what code health and a maintain goal weigh.
An item's Moves names a goal by its scope, as plan/todo_table.py's EPIC_GOAL says."""
import ast
import dataclasses
import decimal
from plan.blockers import blockers_first
from plan.todo_table import CODE_HEALTH, EPIC_GOAL, Item, REPO_GOAL, SHAPE
from failure import Failure
from plan.goals_file import GOAL_STEP, goal_weights, Mark, numbered, ranked_goals
from review_rules.comprehension_history import latest_overall
from plan.formula import parse_formula
from plan import ranking
from plan_store.jira_epic import SET_SCORES
MARK_IT = "is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so the epic's items can be scored"
@dataclasses.dataclass(frozen=True)
class RepoRanking:
"""What a repo's own plan is ranked by: its goals file, its decision log and its comprehension history, each as text, and its readability floor."""
goals_text: str
decisions: str
history: str
floor: decimal.Decimal
@dataclasses.dataclass(frozen=True)
class EpicItem:
"""One of an epic's open items. An Item names a release and an epic item has none: give every item of one epic the same release, so that no blocker sits in a later release than what it blocks. repo is the name of the repo the item is worked in; None where it has none."""
item: Item
repo: str | None
def ranked(items: list[EpicItem], formula: str, epic_goals: str, repos: dict[str, RepoRanking]) -> list[tuple[Item, float]] | Failure:
"""Each item with its score: a question first, then a security finding, then by score from highest, then by ID, and then each blocker above every item it blocks. formula is the epic's, epic_goals the text under its ## Goals, and repos holds, by name, each repo an item is in. An item without a score fails, so leave out an issue a person filed and nobody scored."""
parsed = parse_formula(formula, ranking.variables(SHAPE))
if isinstance(parsed, Failure):
return parsed
scorings: dict[str | None, ranking.Scoring] = {}
scored = []
for each in items:
name = f"item {each.item.id}"
if each.repo not in scorings:
if each.repo is not None and each.repo not in repos:
return Failure(f"{name} is in the repo {each.repo}, whose goals were not read")
scoring = chain_scoring(parsed, epic_goals, each.repo, repos[each.repo] if each.repo else None)
if isinstance(scoring, Failure):
return scoring
scorings[each.repo] = scoring
value = unscored(each.item, name) or misnamed_goal(each, scorings[each.repo], name) or ranking.item_score(each.item, scorings[each.repo], name)
if isinstance(value, Failure):
return value
scored.append((each.item, value))
scored.sort(key=lambda pair: (ranking.FIRST.get(pair[0].exempt, len(ranking.FIRST)), -pair[1], pair[0].id))
return blockers_first(scored)
def chain_scoring(formula: ast.Expression, epic_goals: str, repo: str | None, own: RepoRanking | None) -> ranking.Scoring | Failure:
"""How an item in repo scores: the chain's goals, and what each achieve goal weighs. The bar is 0, since a bar decides what is filed, and the order holds every item that was.
goal_weights scales a chain's weights to sum to 1. Here they are scaled so that the epic's achieve goals sum to 1 instead, in every chain, or the chain's first achieve goal weighs 1 where the epic has none, which makes the scores of items in different repos comparable.
Code health and a maintain goal weigh by the rules every project's plan follows, which an epic doesn't change: code health weighs four times its place while its repo is unmeasured or under its readability floor, and plan/ranking.py's weight_of weighs a maintain goal. Either may then outweigh an achieve goal of the epic. "The epic wins" in the decision settles the epic's goals against a repo's, and code health is neither's: it is every project's, and a repo that is hard to read costs each epic item worked in it."""
goals = chain(epic_goals, repo, own)
if isinstance(goals, Failure):
return goals
if unmarked := next((goal for goal, mark in goals if mark is None), None):
whose, _, number = unmarked.partition(" ")
return Failure(f"{'the epic' if whose == 'epic' else repo}'s goal {number} {MARK_IT}")
overall = latest_overall(own.history) if own and CODE_HEALTH in dict(goals) else None
if isinstance(overall, Failure):
return Failure(f"{repo}: {overall.reason}")
# goal_weights fails only on a goal without a mark, and the check above has named that goal as the epic's or the repo's.
weights = goal_weights(goals, overall, own.floor if own else decimal.Decimal(0))
if isinstance(weights, Failure):
return weights
achieve = [goal for goal, mark in goals if mark == "Achieve"]
of_epic = len([goal for goal in achieve if goal.startswith(EPIC_GOAL)])
# Under an epic without an achieve goal, the first achieve goal of each chain weighs 1.
scale = total(len(achieve)) / (total(of_epic) or 1)
return ranking.Scoring(SHAPE, formula, 0, 0, dict(goals), {goal: weight * scale for goal, weight in weights.items()})
def total(goals: int) -> float:
"""What this many achieve goals weigh together before goal_weights scales them, the first 1 and each 0.97 of the one above it."""
return sum(GOAL_STEP**place for place in range(goals))
def chain(epic_goals: str, repo: str | None, own: RepoRanking | None) -> list[tuple[str, Mark]] | Failure:
"""Every goal an item in repo may name, in rank order, each with its mark. The epic's goals come first, as `epic <number>`. For an item with a repo, whose ranking is own, code health follows unless the repo's goals file voids it, then the repo's goals as `repo <number>`."""
epic = numbered(epic_goals)
if isinstance(epic, Failure):
return Failure(epic.reason.replace("the goals file's", "the epic's"))
scoped = [(f"{EPIC_GOAL}{number}", mark) for number, mark in epic]
if own is None:
return scoped
goals = ranked_goals(own.goals_text, own.decisions)
if isinstance(goals, Failure):
return Failure(f"{repo}: {goals.reason}")
return [*scoped, *((goal if goal == CODE_HEALTH else f"{REPO_GOAL}{goal}", mark) for goal, mark in goals)]
def unscored(item: Item, name: str) -> Failure | None:
"""Why the item cannot be scored, such as an issue a person filed and nobody scored; None where it holds each score."""
missing = next((score for score in SET_SCORES if score not in item.scores), None)
return Failure(f"{name} has no {missing}: score it on {', '.join(SET_SCORES[:-1])} and {SET_SCORES[-1]} before it is ranked") if missing else None
def misnamed_goal(each: EpicItem, scoring: ranking.Scoring, name: str) -> Failure | None:
"""Why the item may not name one of the goals it names, in the epic's terms; None where its chain holds each."""
for goal, _ in each.item.moves:
if goal in scoring.goals:
continue
if goal.startswith(EPIC_GOAL):
return Failure(f"{name} names {goal}, which the epic's ## Goals does not number")
if each.repo is None:
scoped = f"; write `{EPIC_GOAL}{goal}` for the epic's goal" if goal[0].isdigit() else f"; name only the epic's goals, as in `{EPIC_GOAL}1 by 5`"
return Failure(f"{name} names {goal}, but isn't worked in a repo{scoped}")
if goal == CODE_HEALTH:
return Failure(f"{name} names {CODE_HEALTH}, which {each.repo}'s goals file voids")
if not goal.startswith(REPO_GOAL):
return Failure(f"{name} names goal {goal} without saying whose it is; write `{EPIC_GOAL}{goal}` for the epic's goal or `{REPO_GOAL}{goal}` for its repo's")
return Failure(f"{name} names {goal}, which the ## Goals of {each.repo}'s goals file does not number")
return None
+159
View File
@@ -0,0 +1,159 @@
import dataclasses
import decimal
import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.ranking import chain, EpicItem, ranked, RepoRanking
from failure import Failure
from plan.todo_table import Item, parse_moves
EPIC_GOALS = "1. **Achieve:** Ship invoices.\n2. **Achieve:** Cut support mail.\n3. **Maintain:** Leak no customer data.\n"
VOIDED = RepoRanking("## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** Fast builds.\n", "", "", decimal.Decimal("7.0"))
HEALTHY = RepoRanking("## Goals\n\n1. **Achieve:** Fast builds.\n2. **Maintain:** Stay on the LTS.\n", "", "", decimal.Decimal("7.0"))
# A scoring run of a repo whose overall mean is {overall}.
SCORED = "# Comprehension history\n\n## 2026-10-08T12:00:00Z, PR #1 at aaaaaaa\n\n| Seat | Overall |\n|---|---|\n| Mid A | 6 |\n| Mean | {overall} |\n"
# What the epic's two achieve goals weigh together before they are scaled to sum to 1, the second 0.97 of the first.
TOTAL = 1 + 0.97
def item(id_: int, moves: str, repo: str | None = "billing-api", exempt: str = "", blocked_by: tuple[int, ...] = ()) -> EpicItem:
parsed = parse_moves(f"item {id_}", moves)
assert not isinstance(parsed, Failure), parsed
return EpicItem(Item(id_, (0, 0, 0), exempt, f"**Item {id_}.**", {"L": 1, "E": 1, "I": 1, "S": 1}, parsed, blocked_by), repo) # type: ignore[arg-type]
def order(items: list[EpicItem], repos: dict[str, RepoRanking], formula: str = "V") -> list[int] | Failure:
found = ranked(items, formula, EPIC_GOALS, repos)
return found if isinstance(found, Failure) else [scored.id for scored, _ in found]
class MovesSpellingTest(unittest.TestCase):
def test_a_moves_cell_names_an_epics_goal_and_a_repos_goal_by_their_scope(self) -> None:
self.assertEqual(parse_moves("item 1", "epic 1.1 by 8, code health by 5, repo 2 by 4"), (("epic 1.1", 8), ("code health", 5), ("repo 2", 4)))
def test_a_moves_cell_refuses_an_epic_goal_beside_its_own_sub_goal(self) -> None:
self.assertIsInstance(parse_moves("item 1", "epic 1 by 8, epic 1.1 by 5"), Failure)
self.assertEqual(parse_moves("item 1", "epic 1 by 8, repo 1.1 by 5"), (("epic 1", 8), ("repo 1.1", 5)))
class ChainTest(unittest.TestCase):
def test_the_chain_is_the_epics_goals_then_code_health_then_the_repos_goals(self) -> None:
self.assertEqual(chain(EPIC_GOALS, "web", HEALTHY), [("epic 1", "Achieve"), ("epic 2", "Achieve"), ("epic 3", "Maintain"), ("code health", "Achieve"), ("repo 1", "Achieve"), ("repo 2", "Maintain")])
def test_a_repo_that_voids_code_health_leaves_it_out_of_its_chain(self) -> None:
self.assertEqual(chain(EPIC_GOALS, "billing-api", VOIDED), [("epic 1", "Achieve"), ("epic 2", "Achieve"), ("epic 3", "Maintain"), ("repo 1", "Achieve")])
def test_an_item_without_a_repo_weighs_only_the_epics_goals(self) -> None:
self.assertEqual(chain(EPIC_GOALS, None, None), [("epic 1", "Achieve"), ("epic 2", "Achieve"), ("epic 3", "Maintain")])
def test_an_epic_without_a_numbered_goal_fails(self) -> None:
self.assertEqual(chain("Ship it.\n", None, None), Failure("the epic's ## Goals has no numbered goal"))
class RankedTest(unittest.TestCase):
def test_each_goal_weighs_0_97_of_the_one_above_it_in_the_chain(self) -> None:
found = ranked([item(1, "repo 1 by 10"), item(2, "epic 2 by 10"), item(3, "epic 1 by 10")], "V", EPIC_GOALS, {"billing-api": VOIDED})
assert not isinstance(found, Failure), found
self.assertEqual([scored.id for scored, _ in found], [3, 2, 1])
for (_, value), expected in zip(found, (10 / TOTAL, 9.7 / TOTAL, 10 * 0.97**2 / TOTAL)):
self.assertAlmostEqual(value, expected)
def test_where_the_epic_and_a_repo_disagree_the_epic_wins(self) -> None:
self.assertEqual(order([item(1, "repo 1 by 5"), item(2, "epic 2 by 5")], {"billing-api": VOIDED}), [2, 1])
def test_items_of_two_repos_rank_in_one_order_each_by_its_own_repos_chain(self) -> None:
repos = {"billing-api": VOIDED, "web": HEALTHY}
self.assertEqual(order([item(1, "repo 1 by 5"), item(2, "repo 1 by 6", repo="web"), item(3, "epic 1 by 9", repo="web")], repos, "V * 0 + S + I"), [1, 2, 3])
self.assertEqual(order([item(1, "repo 1 by 5"), item(2, "repo 2 by 9", repo="web")], repos), [2, 1])
def test_an_item_without_a_repo_scores_by_the_epics_goals_alone(self) -> None:
found = ranked([item(1, "epic 1 by 10", repo=None)], "V", EPIC_GOALS, {})
assert not isinstance(found, Failure), found
self.assertAlmostEqual(found[0][1], 10 / TOTAL)
def test_an_item_without_a_repo_may_not_name_a_repos_goal_or_code_health(self) -> None:
self.assertEqual(order([item(4, "repo 1 by 5", repo=None)], {}), Failure("item 4 names repo 1, but isn't worked in a repo; name only the epic's goals, as in `epic 1 by 5`"))
self.assertEqual(order([item(4, "code health by 5", repo=None)], {}), Failure("item 4 names code health, but isn't worked in a repo; name only the epic's goals, as in `epic 1 by 5`"))
self.assertEqual(order([item(4, "2 by 5", repo=None)], {}), Failure("item 4 names 2, but isn't worked in a repo; write `epic 2` for the epic's goal"))
def test_a_goal_without_its_scope_is_refused(self) -> None:
self.assertEqual(order([item(4, "1 by 5")], {"billing-api": VOIDED}), Failure("item 4 names goal 1 without saying whose it is; write `epic 1` for the epic's goal or `repo 1` for its repo's"))
def test_an_epics_goal_outweighs_a_repos_goal_across_repos_with_chains_of_different_lengths(self) -> None:
long = RepoRanking("## Goals\n\n" + "".join(f"{place}. **Achieve:** Goal {place}.\n" for place in range(1, 10)), "", "", decimal.Decimal("7.0"))
found = ranked([item(1, "repo 1 by 10"), item(2, "epic 2 by 10", repo="web"), item(3, "epic 2 by 10", repo=None)], "V", EPIC_GOALS, {"billing-api": VOIDED, "web": long})
assert not isinstance(found, Failure), found
self.assertEqual([scored.id for scored, _ in found], [2, 3, 1])
for (_, value), expected in zip(found, (9.7 / TOTAL, 9.7 / TOTAL, 10 * 0.97**2 / TOTAL)):
self.assertAlmostEqual(value, expected)
def test_an_epic_without_an_achieve_goal_weighs_each_repos_first_achieve_goal_1(self) -> None:
two = dataclasses.replace(VOIDED, goals_text=VOIDED.goals_text + "2. **Achieve:** Small images.\n")
found = ranked([item(1, "repo 1 by 10"), item(2, "repo 1 by 10", repo="web"), item(3, "repo 2 by 10", repo="web")], "V", "1. **Maintain:** Leak no customer data.\n", {"billing-api": VOIDED, "web": two})
assert not isinstance(found, Failure), found
for (_, value), expected in zip(found, (10, 10, 9.7)):
self.assertAlmostEqual(value, expected)
def test_an_item_without_a_score_fails_naming_it(self) -> None:
unscored = EpicItem(dataclasses.replace(item(4, "").item, scores={}), None)
self.assertEqual(ranked([unscored], "V", EPIC_GOALS, {}), Failure("item 4 has no L: score it on L, E, I and S before it is ranked"))
def test_an_epic_that_numbers_a_goal_twice_fails(self) -> None:
self.assertEqual(chain("1. **Achieve:** A.\n1. **Achieve:** B.\n", None, None), Failure("the epic's ## Goals numbers 1, 1; number each goal by its position"))
def test_a_goal_the_chain_does_not_hold_is_refused(self) -> None:
self.assertEqual(order([item(4, "epic 9 by 5")], {"billing-api": VOIDED}), Failure("item 4 names epic 9, which the epic's ## Goals does not number"))
self.assertEqual(order([item(4, "repo 9 by 5")], {"billing-api": VOIDED}), Failure("item 4 names repo 9, which the ## Goals of billing-api's goals file does not number"))
self.assertEqual(order([item(4, "code health by 5")], {"billing-api": VOIDED}), Failure("item 4 names code health, which billing-api's goals file voids"))
def test_an_item_in_a_repo_without_premises_fails(self) -> None:
self.assertEqual(order([item(4, "epic 1 by 5", repo="ghost")], {}), Failure("item 4 is in the repo ghost, whose goals were not read"))
def test_a_goal_marked_neither_way_fails_naming_whose_it_is(self) -> None:
unmarked = RepoRanking("## Goals\n\n1. Fast builds.\n", "", "", decimal.Decimal("7.0"))
self.assertEqual(order([item(4, "epic 1 by 5")], {"billing-api": unmarked}), Failure("billing-api's goal 1 is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so the epic's items can be scored"))
found = ranked([item(4, "epic 1 by 5", repo=None)], "V", "1. Ship invoices.\n", {})
self.assertEqual(found, Failure("the epic's goal 1 is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so the epic's items can be scored"))
def test_a_repos_goals_file_that_cannot_be_read_fails_naming_the_repo(self) -> None:
self.assertEqual(order([item(4, "epic 1 by 5")], {"billing-api": RepoRanking("# Billing\n", "", "", decimal.Decimal("7.0"))}), Failure("billing-api: the goals file has no ## Goals heading"))
def test_code_health_weighs_four_times_its_place_while_the_repo_is_unmeasured_or_under_its_floor(self) -> None:
for history, times in (("", 4), (SCORED.format(overall="6.9"), 4), (SCORED.format(overall="7.0"), 1)):
with self.subTest(history=history):
found = ranked([item(1, "code health by 10", repo="web"), item(2, "repo 1 by 10", repo="web")], "V", EPIC_GOALS, {"web": dataclasses.replace(HEALTHY, history=history)})
assert not isinstance(found, Failure), found
self.assertAlmostEqual(found[0][1], times * 10 * 0.97**2 / TOTAL)
self.assertAlmostEqual(found[1][1], 10 * 0.97**3 / TOTAL)
def test_code_health_weighs_four_times_its_place_under_a_floor_the_repo_sets_higher(self) -> None:
found = ranked([item(1, "code health by 10", repo="web")], "V", EPIC_GOALS, {"web": dataclasses.replace(HEALTHY, history=SCORED.format(overall="7.5"), floor=decimal.Decimal("8.0"))})
assert not isinstance(found, Failure), found
self.assertAlmostEqual(found[0][1], 4 * 10 * 0.97**2 / TOTAL)
def test_a_history_that_cannot_be_read_fails_naming_the_repo(self) -> None:
found = order([item(1, "code health by 10", repo="web")], {"web": dataclasses.replace(HEALTHY, history=SCORED.format(overall="high"))})
assert isinstance(found, Failure), found
self.assertTrue(found.reason.startswith("web: ") and len(found.reason) > len("web: None"), found.reason)
def test_a_formula_that_gives_an_item_no_finite_score_fails_naming_the_item(self) -> None:
self.assertEqual(order([item(4, "epic 1 by 5")], {"billing-api": VOIDED}, "10 ** 400 * V * 10 ** 400"), Failure("the formula gives item 4 no finite score"))
def test_each_goal_an_item_names_is_checked(self) -> None:
self.assertEqual(order([item(4, "epic 1 by 5, repo 9 by 5")], {"billing-api": VOIDED}), Failure("item 4 names repo 9, which the ## Goals of billing-api's goals file does not number"))
def test_a_question_then_a_security_finding_rank_before_any_score(self) -> None:
self.assertEqual(order([item(1, "epic 1 by 10"), item(2, "epic 2 by 1", exempt="security"), item(3, "", exempt="question")], {"billing-api": VOIDED}), [3, 2, 1])
def test_a_blocker_ranks_above_the_item_it_blocks_and_a_tie_goes_to_the_older_item(self) -> None:
self.assertEqual(order([item(1, "epic 1 by 9", blocked_by=(3,)), item(2, "epic 1 by 2"), item(3, "epic 1 by 1"), item(5, "epic 1 by 2")], {"billing-api": VOIDED}), [3, 1, 2, 5])
def test_a_formula_that_cannot_be_read_fails(self) -> None:
self.assertIsInstance(order([item(1, "epic 1 by 9")], {"billing-api": VOIDED}, "V +"), Failure)
if __name__ == "__main__":
unittest.main()
+4 -1
View File
@@ -22,6 +22,9 @@ BLOCKED_BY = "Blocked by"
MOVES = "Moves"
# The achieve goal every project shares, which ~/.claude/CLAUDE.md → "Shared goal" states, and a Moves cell names by these words, since it has no number in any goals file.
CODE_HEALTH = "code health"
# The scope that opens a goal's name in the Moves of an epic's item, since the epic and the item's repo both number their goals from 1: `epic 1.1 by 8, code health by 5, repo 2 by 4`. Three readers, seated as the human who writes these cells, picked a scope word on both goals, 3-0, over one on either alone and over the repo's name. A todo.md's item may name neither.
EPIC_GOAL = "epic "
REPO_GOAL = "repo "
# How the items table's header opens, which tells it from any other table in todo.md.
HEADER_START = "| ID | Release |"
# todo.md's ## Details section, its body the first group.
@@ -61,7 +64,7 @@ class Shape:
def parse_moves(label: str, cell: str) -> Moves | Failure:
"""A Moves cell: empty, or each goal the item moves, named once, and how far. ranking.py's cited_goals_failure holds the rules that need the goals file."""
matches = [re.fullmatch(rf"([0-9]+(?:\.[0-9]+)*|{CODE_HEALTH}) by ([0-9]+)", move) for move in cell.split(", ")] if cell else []
matches = [re.fullmatch(rf"((?:{EPIC_GOAL}|{REPO_GOAL})?[0-9]+(?:\.[0-9]+)*|{CODE_HEALTH}) by ([0-9]+)", move) for move in cell.split(", ")] if cell else []
moves = tuple((match.group(1), int(match.group(2))) for match in matches if match)
if len(moves) < len(matches) or any(not 1 <= by <= TOP_SCORE for _, by in moves):
return Failure(f"{label}'s {MOVES} {cell!r} is not empty or goals such as `1.1 by 8, {CODE_HEALTH} by 5`, each moved by a whole number from 1 to {TOP_SCORE}")
+29 -14
View File
@@ -6,15 +6,16 @@
`Bar = 0.1`
`Next ID = 426`
`Next ID = 428`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 426 | 0.12.0 | | | **Read each epic issue's scores, its blockers and whether the loop filed it through `EpicStore`, from both backends.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 427 | 0.12.0 | 426 | | **Re-rank Jira's backlog to match an epic's ranking, moving only the issues the loop filed, so people's issues keep their rank.** | 3 | 2 | 3 | 6 | 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 |
| 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, 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, 427 | | **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 |
@@ -82,6 +83,31 @@
## Details
### 426. Read each epic issue's scores, its blockers and whether the loop filed it through `EpicStore`, from both backends.
Today `EpicIssue` holds none of the three, so do-epic cannot score or order an epic's items (item 408) or tell a person's issue from its own (item 427). The Jira backend reads them as `plan_store/jira_epic.py` does: the `plan-item` issue property, its `Filed by` key, and the "is blocked by" links. The contract tests in `contract.py` cover both backends.
Touches:
- `bin/do_epic/backend/protocol.py`: `EpicIssue` (small)
- `bin/do_epic/backend/fake.py`
- `bin/do_epic/backend/jira.py`: `FIELDS`, `JiraEpic.found`
- `bin/do_epic/backend/contract.py`
- `bin/do_epic/backend/test_jira.py`
### 427. Re-rank Jira's backlog to match an epic's ranking, moving only the issues the loop filed, so people's issues keep their rank.
Split from item 408 (`docs/decisions.md` → `do-epic: drives one Jira epic …`). `EpicStore` gains a rank call, in both backends and the contract tests. Lift `JiraPlan.rank_refusal` to a module function both stores call. Walk the target order: where the issue at a position isn't the target's, rank the target's just before it; the slots people's issues hold stay theirs. A rank Jira refuses stops the walk and is reported, since a wrongly ranked team backlog takes hours to restore.
Touches:
- `bin/plan_store/jira_epic.py`: `JiraPlan.rank_refusal` (small)
- `bin/do_epic/backend/protocol.py`: `EpicStore` (small)
- `bin/do_epic/backend/fake.py`
- `bin/do_epic/backend/jira.py`
- `bin/do_epic/backend/contract.py`
- `bin/do_epic/ranking.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.
@@ -109,17 +135,6 @@ Touches:
- `bin/rung_replay/search.py`
- `README.md`: `` ### Packages under `bin/` `` (small)
### 408. 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.
Where the epic and a repo disagree, the epic wins (`docs/decisions.md` → `do-epic: drives one Jira epic …`). An item without a repo weighs only the epic's goals. Reuse `goal_weights` and `weight_of`, and `JiraPlan.rank_refusal` for the rank call. `plan/ranking.py` `score` is a place the seats found hard, so the combiner must not add a branch to it.
Touches:
- `bin/plan/ranking.py`: `weigh`, `weight_of` (small)
- `bin/plan/goals_file.py`: `goal_weights` (small)
- `bin/plan_store/jira_epic.py`: `JiraPlan.rank_refusal` (small)
- `bin/do_epic/ranking.py`
### 410. 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.
The lock that keeps do-epic and loop-claude apart is the per-project `starting` flock, shared by both (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Each chunk routes on its repo's model and ladder, a no-repo chunk on the machine setting's model. `loop/chunk_windows.py` `start_chunks` is a place the seats found hard: make it easier to read where it changes.