Score an epic's items by one chain of goals and order them by score, then blockers
CI / tests (pull_request) Failing after 3m22s

This commit is contained in:
2026-11-18 16:24:55 +01:00
parent c62242b787
commit e82e5c3876
6 changed files with 253 additions and 3 deletions
+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.
+104
View File
@@ -0,0 +1,104 @@
"""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. plan/goals_file.py's goal_weights weighs the chain as it weighs one project's goals, so a goal of the epic outweighs every goal of a repo. An item without a repo has only the epic's goals.
The epic and each repo number their goals from 1, so an item's Moves names a goal by its scope: `epic 1.1 by 8, code health by 5, repo 2 by 4`."""
import ast
import dataclasses
import decimal
from failure import Failure
from plan import ranking
from plan.blockers import blockers_first
from plan.formula import parse_formula
from plan.goals_file import goal_weights, Mark, numbered, ranked_goals
from plan.todo_table import CODE_HEALTH, EPIC_GOAL, Item, REPO_GOAL, SHAPE
from review_rules.comprehension_history import latest_overall
MARK_IT = "is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says"
@dataclasses.dataclass(frozen=True)
class RepoPremises:
"""What a repo's own plan is ranked by: its goals file, its decision log and 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 epic item has no release, so every item of one epic holds the same one. repo is the name of the repo it 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, RepoPremises]) -> 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 the premises of each repo an item is in, by name."""
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.get(each.repo or ""))
if isinstance(scoring, Failure):
return scoring
scorings[each.repo] = scoring
value = unnamed_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, premises: RepoPremises | None) -> ranking.Scoring | Failure:
"""How an item in repo scores: the chain's goals, each achieve goal at its weight. The bar is 0, since the bar decides what is filed, not the order of what was."""
goals = chain(epic_goals, repo, premises)
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(premises.history) if premises and CODE_HEALTH in dict(goals) else None
if isinstance(overall, Failure):
return Failure(f"{repo}: {overall.reason}")
weights = goal_weights(goals, overall, premises.floor if premises else decimal.Decimal(0))
return weights if isinstance(weights, Failure) else ranking.Scoring(SHAPE, formula, 0, 0, dict(goals), weights)
def chain(epic_goals: str, repo: str | None, premises: RepoPremises | None) -> list[tuple[str, Mark]] | Failure:
"""Every goal an item may name, in rank order, each with its mark: the epic's goals as `epic <number>`, then, for an item in repo, which has these premises, code health unless the repo's goals file voids it, and 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 premises is None:
return scoped
own = ranked_goals(premises.goals_text, premises.decisions)
if isinstance(own, Failure):
return Failure(f"{repo}: {own.reason}")
return [*scoped, *((goal if goal == CODE_HEALTH else f"{REPO_GOAL}{goal}", mark) for goal, mark in own)]
def unnamed_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 not goal.startswith((EPIC_GOAL, REPO_GOAL)) and goal != CODE_HEALTH:
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")
if goal.startswith(EPIC_GOAL):
return Failure(f"{name} names {goal}, which the epic's ## Goals does not number")
if each.repo is None:
return Failure(f"{name} names {goal}, but has no repo whose {'code' if goal == CODE_HEALTH else 'goal'} that could be; name only the epic's goals, as in `{EPIC_GOAL}1 by 5`")
if goal == CODE_HEALTH:
return Failure(f"{name} names {CODE_HEALTH}, which {each.repo}'s goals file voids")
return Failure(f"{name} names {goal}, which the ## Goals of {each.repo}'s goals file does not number")
return None
+109
View File
@@ -0,0 +1,109 @@
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, RepoPremises
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 = RepoPremises("## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** Fast builds.\n", "", "", decimal.Decimal("7.0"))
HEALTHY = RepoPremises("## Goals\n\n1. **Achieve:** Fast builds.\n2. **Maintain:** Stay on the LTS.\n", "", "", decimal.Decimal("7.0"))
# What the three achieve goals of the chain epic 1, epic 2, repo 1 weigh together before they are scaled to sum to 1, each 0.97 of the one above.
TOTAL = 1 + 0.97 + 0.97**2
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, RepoPremises], 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 / 1.97)
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 has no repo whose goal that could be; 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 has no repo whose code that could be; name only the epic's goals, as in `epic 1 by 5`"))
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_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 = RepoPremises("## 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"))
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"))
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": RepoPremises("# Billing\n", "", "", decimal.Decimal("7.0"))}), Failure("billing-api: the goals file has no ## Goals heading"))
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"
# What opens a goal's name in the Moves of an epic's item, whose epic and 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 reads and writes these cells, picked a scope word on both over one on either alone and over the repo's name, 3-0. do_epic/ranking.py holds the goals such an item may 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}")
+34
View File
@@ -2691,3 +2691,37 @@ Read most (opens and searches):
- `bin/transcript_archive/outcomes.py` 2
- `bin/judge_replay/replay.py` 1
- `bin/rung_replay/archive.py` 1
## Reading cost, chunk f6452ae1f4d1, finished 2026-11-18T15:04:37Z
164779 new input tokens before the first commit.
Read most (opens and searches):
- `README.md` 5
- `CHANGELOG.md` 2
- `bin/claude_code/reply.py` 2
- `bin/do_epic/backend/contract.py` 2
- `bin/do_epic/backend/jira.py` 2
- `bin/do_epic/backend/test_jira.py` 2
- `docs/decisions.md` 2
- `bin/atlassian/client.py` 1
- `bin/do_epic/backend/fake.py` 1
- `bin/do_epic/backend/protocol.py` 1
## Reading cost, chunk a1d1adafc713, finished 2026-11-18T15:13:10Z
257245 new input tokens before the first commit.
Read most (opens and searches):
- `docs/decisions.md` 11
- `bin/review_replay/test_review_replay.py` 9
- `bin/review_replay/replay.py` 7
- `README.md` 6
- `bin/review_replay/change_comparison.py` 5
- `bin/rule_hook/test_rule_hook.py` 4
- `bin/loop_claude/cycle/run.py` 2
- `bin/loop_claude/test_loop_claude.py` 2
- `bin/review_replay/main.py` 2
- `bin/rule_hook/main.py` 2
+1 -1
View File
@@ -99,7 +99,7 @@ Touches:
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. Build the chain as one list for `goal_weights`, score with `ranking.item_score` and order with `blockers_first`. `plan/ranking.py` `score` is a place the seats found hard, so the combiner must not add a branch to it.
The epic's and a repo's goal numbers collide, so a Moves cell needs a spelling for a repo's goal beside the epic's; a panel of readers picks it before it ships (`~/.claude/CLAUDE.md` → "Bench a syntax"). The scorer takes the items and each repo's goals as values; item 424 reads them from the tracker, and item 425 re-ranks Jira by the order.
The epic's and a repo's goal numbers collide, so a Moves cell needs a spelling for a repo's goal beside the epic's; a panel of readers picks it before it ships (`~/.claude/CLAUDE.md` → "Working loop"). The scorer takes the items and each repo's goals as values; item 424 reads them from the tracker, and item 425 re-ranks Jira by the order.
Touches: