276 lines
18 KiB
Python
276 lines
18 KiB
Python
"""What `do-epic <EPIC-KEY>` settles before it starts chunks: where each open issue is worked, and the order the loop's issues come in (docs/decisions.md → `do-epic: drives one Jira epic …`).
|
|
|
|
An open child issue that no label places is first split by repo (`split`), and where it changes one repo or none, its repo is picked (`repo_pick`). Each is a headless claude call on `repoless-model`'s rung of the shipped ladder. Where the repo rule leaves a pick unclear, the human answers on the terminal. Then, where two or more issues may start, each of them that holds no scores is scored (`issue_scores`), a person's too. The issues start in order of score (`start_order`). The issues do-epic filed are re-ranked in Jira's backlog to match (`ranking`), and the rank of a person's issue stays as the team set it.
|
|
|
|
Planning runs only in the `do-epic <EPIC-KEY>` the human starts. A chunk that finishes starts the next chunks from the labels and the scores it finds, so no window waits on a question.
|
|
|
|
Planning holds no lock: one `do-epic <EPIC-KEY>` at a time is assumed. A second one started meanwhile finds the sub-tasks the first filed, since `split` reads them before it files, unless Jira's search lags."""
|
|
import dataclasses
|
|
import pathlib
|
|
import re
|
|
|
|
from do_epic.config import DoEpicConfig
|
|
from loop_effects.effects import Effects, say
|
|
from do_epic.backend.protocol import EpicIssue, EpicStore, no_scores
|
|
from do_epic.epic_record import EpicRecord
|
|
from failure import Failure
|
|
from record_store.stores import goals_store, store as record_store
|
|
from do_epic import issue_scores, ranking, repo_pick, repos, split
|
|
from plan.todo_table import Item
|
|
from claude_code.reply import Limited
|
|
from plan_store.jira_epic import number
|
|
from model_routing.ladder_file import read_ladder, SHIPPED
|
|
from model_routing.ladder import Rung
|
|
from do_epic.scheduler import STATE, unblocks
|
|
from plan_store.scoring import weighing_texts
|
|
|
|
# The epic's formula, stated under its `## Scoring` as a todo.md states its own.
|
|
FORMULA = re.compile(r"^`Score = ([^`]+)`$", re.M)
|
|
# An epic item has no release, and ranking wants every item of one epic in the same one.
|
|
NO_RELEASE = (0, 0, 0)
|
|
# The rule every plan item is scored by, under the home folder, where each machine's setup keeps it.
|
|
RULE = ".claude/rules/todo-items.md"
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Planned:
|
|
"""The epic whose open issues are planned."""
|
|
key: str
|
|
config: DoEpicConfig
|
|
store: EpicStore
|
|
record: EpicRecord
|
|
home: pathlib.Path
|
|
effects: Effects
|
|
|
|
|
|
def planned(epic: Planned, issues: list[EpicIssue]) -> tuple[list[EpicIssue], Failure | Limited | None]:
|
|
"""The epic's issues as far as they are planned, and why the planning stopped early, None where it didn't. issues are the epic's, as just read.
|
|
|
|
Each open child issue that no label places, and that isn't split already, is split or gets its pick. Then each issue that holds no scores is scored, and the issues do-epic filed are re-ranked. What was labelled, filed, scored or ranked before a Failure or a Limited stays, and the issues returned show it."""
|
|
unplaced = [issue for issue in issues if issue.parent == epic.key and not issue.done and not split.is_split(issue, issues) and repo_pick.recorded(issue, epic.config.label_repos) is None]
|
|
added: dict[str, str] = {}
|
|
stopped = placed(epic, issues, unplaced, added) if unplaced else None
|
|
if added:
|
|
read = epic.store.read()
|
|
# A search may not show a label added a moment ago, so each label added here counts whatever the read says. A sub-task the search doesn't show yet starts on the next run.
|
|
issues = [labelled(each, added.get(each.key)) for each in (issues if isinstance(read, Failure) else read)]
|
|
stopped = stopped or (read if isinstance(read, Failure) else None)
|
|
if stopped is not None:
|
|
return issues, stopped
|
|
issues, stopped = scored(epic, issues)
|
|
if stopped is not None:
|
|
return issues, stopped
|
|
starts = start_order(epic, issues)
|
|
if isinstance(starts, Failure):
|
|
return issues, starts
|
|
# The board's rank of a person's issue is the team's, so only the child issues do-epic filed are re-ranked, among themselves.
|
|
ours = {issue.key for issue in issues if issue.by_loop and issue.parent == epic.key}
|
|
order = [key for key in starts if key in ours]
|
|
if [issue.key for issue in issues if issue.key in order] == order:
|
|
return issues, None
|
|
say(f"re-ranking the issues do-epic filed in {epic.key}'s backlog", epic.effects, stdout=True)
|
|
refused = ranking.reranked(epic.store, order)
|
|
if refused:
|
|
return issues, refused
|
|
# A search may not show the new order yet, so the issues are put in it here, as `reranked` put them in Jira: each ranked issue in a position a ranked issue held.
|
|
by_key, ranked = {issue.key: issue for issue in issues}, iter(order)
|
|
return [by_key[next(ranked)] if issue.key in order else issue for issue in issues], None
|
|
|
|
|
|
def labelled(issue: EpicIssue, label: str | None) -> EpicIssue:
|
|
"""issue with label among its labels; issue itself where label is None."""
|
|
return issue if label is None or label in issue.labels else dataclasses.replace(issue, labels=tuple(sorted((*issue.labels, label))))
|
|
|
|
|
|
def placed(epic: Planned, issues: list[EpicIssue], unplaced: list[EpicIssue], added: dict[str, str]) -> None | Failure | Limited:
|
|
"""Splits each of unplaced by repo, or labels it with its pick, and notes in added the label each got, by its key. An issue that claude or the tracker fails on is named and left for the next run, as is one whose question the human doesn't answer; a usage limit ends the planning."""
|
|
rung = planning_rung(epic.config.repoless_model)
|
|
language = epic.record.language()
|
|
# Claude reads every repo a label of the epic names, a finished issue's too, to predict which of them an issue changes.
|
|
places = located(epic, [repo for issue in issues if isinstance(repo := repo_pick.recorded(issue, epic.config.label_repos), repo_pick.Repo)])
|
|
if failed := next((each for each in (rung, language, places) if isinstance(each, Failure)), None):
|
|
return failed
|
|
assert isinstance(rung, Rung) and not isinstance(language, Failure) and isinstance(places, dict)
|
|
folder = epic.home / STATE / epic.key
|
|
folder.mkdir(parents=True, exist_ok=True)
|
|
checkouts = tuple(str(place.checkout) for place in places.values())
|
|
for issue in unplaced:
|
|
say(f"planning {issue.key}", epic.effects, stdout=True)
|
|
parts = split.split(epic.store, issue, epic.config.label_repos, not issue.by_loop, epic.config.repo_rule, language or epic.config.language, checkouts, rung, epic.effects.claude, str(folder), epic.config.sub_task_summary)
|
|
if isinstance(parts, split.Split) and parts.repos:
|
|
added[issue.key] = split.SPLIT_LABEL
|
|
say(f"{issue.key} is split into a sub-task for each of {', '.join(parts.repos)}", epic.effects, stdout=True)
|
|
continue
|
|
pick: repo_pick.Pick | repo_pick.Unclear | Failure | Limited | None = parts if not isinstance(parts, split.Split) else repo_pick.picked(epic.store, issue, epic.config.label_repos, epic.config.repo_rule, rung, epic.effects.claude, str(folder))
|
|
if isinstance(pick, repo_pick.Unclear):
|
|
pick = answered(epic, issue, pick.question)
|
|
if isinstance(pick, Limited):
|
|
return pick
|
|
if isinstance(pick, Failure):
|
|
say(f"{issue.key} is not planned: {pick.reason}", epic.effects, stdout=True)
|
|
elif pick is not None and not isinstance(pick, repo_pick.Unclear):
|
|
added[issue.key] = repo_pick.label_of(pick, epic.config.label_repos)
|
|
say(f"{issue.key} is labelled {added[issue.key]}", epic.effects, stdout=True)
|
|
return None
|
|
|
|
|
|
def planning_rung(model: str) -> Rung | Failure:
|
|
"""The rung each planning call runs on: the model's cheapest on the shipped ladder."""
|
|
ladder = read_ladder(SHIPPED)
|
|
if isinstance(ladder, Failure):
|
|
return ladder
|
|
project = ladder.project_rung(model)
|
|
return project.rung if project else Failure(f"`repoless-model` names {model}, which is not on the routing ladder {SHIPPED}")
|
|
|
|
|
|
def answered(epic: Planned, issue: EpicIssue, question: str) -> repo_pick.Pick | None | Failure:
|
|
"""The pick the human types for an issue the repo rule leaves unclear, once it is recorded; None where nobody is at a terminal to answer, or the human answers with Enter alone, so the issue waits for the next run. The answer is the label to give the issue, so that it is spelt as a person would spell it in Jira.
|
|
|
|
A repo's name is not checked against the repos do-epic knows: an epic's first issue in a repo names one it has not seen."""
|
|
if not epic.effects.on_terminal():
|
|
say(f"{issue.key} waits for your answer: {question} Run `do-epic {epic.key}` on a terminal to answer, or label the issue in Jira.", epic.effects, stdout=True)
|
|
return None
|
|
say(f"\n{issue.key}, {issue.summary}: {question}", epic.effects)
|
|
while True:
|
|
try:
|
|
typed = epic.effects.input(f"The label that says where {issue.key} is worked, `{repo_pick.REPO_PREFIX}<name>`, `{repo_pick.CLAUDE_LABEL}` or `{repo_pick.HUMAN_LABEL}`{repo_pick.also(epic.config.label_repos)}, or Enter alone to leave it waiting: ")
|
|
except EOFError:
|
|
return None
|
|
label = typed.strip()
|
|
if not label:
|
|
return None
|
|
pick = repo_pick.of_label(label, epic.config.label_repos)
|
|
if pick is not None:
|
|
return repo_pick.record(epic.store, issue, pick, epic.config.label_repos)
|
|
named = f"; the repo {label}'s label is `{repo_pick.label_of(repo_pick.Repo(label), epic.config.label_repos)}`" if repo_pick.of_label(repo_pick.REPO_PREFIX + label, {}) else ""
|
|
say(f"`{label}` is none of those labels{named}", epic.effects)
|
|
|
|
|
|
def located(epic: Planned, picks: list[repo_pick.Repo]) -> dict[str, repos.Located] | Failure:
|
|
"""Each picked repo's checkout and project config, by the repo's name."""
|
|
places: dict[str, repos.Located] = {}
|
|
for name in sorted({pick.name for pick in picks}):
|
|
place = repos.locate(name, [each.checkout for each in places.values()], epic.config, epic.home, epic.effects.git)
|
|
if isinstance(place, Failure):
|
|
return place
|
|
places[name] = place
|
|
return places
|
|
|
|
|
|
def chunk_issues(epic: Planned, issues: list[EpicIssue]) -> list[EpicIssue]:
|
|
"""The open issues that may become a chunk: a child issue or a sub-task with one pick. Not an item split by repo, which is worked through its sub-tasks, and not an issue in one of the unblocking statuses, whose work has landed."""
|
|
return [issue for issue in issues if not issue.done and not unblocks(issue.status, epic.config.unblocking) and not split.is_split(issue, issues) and (pick := repo_pick.recorded(issue, epic.config.label_repos)) is not None and not isinstance(pick, Failure)]
|
|
|
|
|
|
def repo_of(epic: Planned, issue: EpicIssue) -> str | None:
|
|
"""The name of the repo the issue's pick names; None where it has no repo."""
|
|
pick = repo_pick.recorded(issue, epic.config.label_repos)
|
|
return pick.name if isinstance(pick, repo_pick.Repo) else None
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Weighing:
|
|
"""What an epic's issues are scored by: its formula, the text under its ## Goals, and the ranking of each repo an issue is in, by name."""
|
|
formula: str
|
|
goals: str
|
|
repos: dict[str, ranking.RepoRanking]
|
|
|
|
|
|
def weighing(epic: Planned, issues: list[EpicIssue]) -> Weighing | Failure:
|
|
"""What an issue of the epic is scored and ranked by: the epic's formula and goals, and each repo's ranking. issues are the ones to put in order."""
|
|
scoring, goals = epic.record.section("Scoring"), epic.record.section("Goals")
|
|
if failed := next((each for each in (scoring, goals) if isinstance(each, Failure)), None):
|
|
return Failure(f"the epic {epic.key}'s description: {failed.reason}")
|
|
assert isinstance(scoring, str) and isinstance(goals, str)
|
|
formulas = FORMULA.findall(scoring)
|
|
if len(formulas) != 1:
|
|
return Failure(f"the epic {epic.key}'s description states `Score = ...` {len(formulas)} times under ## Scoring; state the formula that ranks its issues once, on a line of its own and inside backticks, such as `Score = 100 * V / (2**S + 32)`")
|
|
places = located(epic, [repo_pick.Repo(name) for issue in issues if (name := repo_of(epic, issue))])
|
|
if isinstance(places, Failure):
|
|
return places
|
|
rankings: dict[str, ranking.RepoRanking] = {}
|
|
for name, place in places.items():
|
|
texts = weighing_texts(goals_store(place.config), record_store(place.config, "decisions"), record_store(place.config, "comprehension-history"))
|
|
if isinstance(texts, Failure):
|
|
return Failure(f"{name}: {texts.reason}")
|
|
rankings[name] = ranking.RepoRanking(*texts, place.config.readability_floor)
|
|
return Weighing(formulas[0], goals, rankings)
|
|
|
|
|
|
def scored(epic: Planned, issues: list[EpicIssue]) -> tuple[list[EpicIssue], Failure | Limited | None]:
|
|
"""issues, once claude has scored each open issue that may become a chunk and holds no scores, whoever filed it, and why the scoring stopped early, None where it didn't. Scores an issue holds stay, a person's and an earlier run's alike. Each score is set on the issue with a comment, in the epic's language, that tells its team the scores.
|
|
|
|
A human's task gets no scores, since it starts no work of the loop's. Fewer than two other issues need no order, so none is scored. An issue claude or the tracker fails on is named and stays without scores, so it starts after those that hold them; a usage limit ends the scoring."""
|
|
ours = [issue for issue in chunk_issues(epic, issues) if not isinstance(repo_pick.recorded(issue, epic.config.label_repos), repo_pick.HumanTask)]
|
|
bare = [issue for issue in ours if not issue.scores]
|
|
if not bare or len(ours) < 2:
|
|
return issues, None
|
|
rung, language, rule, weighed = planning_rung(epic.config.repoless_model), epic.record.language(), scoring_rule(epic.home), weighing(epic, bare)
|
|
if failed := next((each for each in (rung, language, rule, weighed) if isinstance(each, Failure)), None):
|
|
return issues, failed
|
|
assert isinstance(rung, Rung) and not isinstance(language, Failure) and isinstance(rule, str) and isinstance(weighed, Weighing)
|
|
folder = epic.home / STATE / epic.key
|
|
folder.mkdir(parents=True, exist_ok=True)
|
|
for issue in bare:
|
|
say(f"scoring {issue.key}", epic.effects, stdout=True)
|
|
repo = repo_of(epic, issue)
|
|
goals = ranking.goals_named(weighed.goals, repo, weighed.repos.get(repo) if repo else None)
|
|
answer = goals if isinstance(goals, Failure) else issue_scores.asked(issue, rule, goals, language or epic.config.language, rung, epic.effects.claude, str(folder))
|
|
if isinstance(answer, Limited):
|
|
return issues, answer
|
|
held = answer if isinstance(answer, Failure) else scores_set(epic, issue, answer, weighed)
|
|
if isinstance(held, Failure):
|
|
say(f"{issue.key} is not scored: {held.reason}", epic.effects, stdout=True)
|
|
continue
|
|
assert isinstance(answer, issue_scores.Scores)
|
|
issues = [held if each.key == issue.key else each for each in issues]
|
|
say(f"{issue.key} is scored {', '.join(f'{name} {value}' for name, value in held.scores.items())}, Moves {answer.moves or 'none'}", epic.effects, stdout=True)
|
|
return issues, None
|
|
|
|
|
|
def scores_set(epic: Planned, issue: EpicIssue, answer: issue_scores.Scores, weighed: Weighing) -> EpicIssue | Failure:
|
|
"""issue holding the scores of answer, once the tracker has set them and told the team. Before the tracker sets them, the answer is held to the plan's format and to the goals the issue may name, since a score that cannot be ranked would stay on the issue."""
|
|
fields = no_scores(issue.key, answer.scores, answer.moves, {})
|
|
if isinstance(fields, Failure):
|
|
return fields
|
|
held = dataclasses.replace(issue, scores=fields.scores, moves=fields.moves)
|
|
ranked = ranking.ranked([ranking.EpicItem(item_of(held, {issue.key: number(issue.key)}, ()), repo_of(epic, issue), issue.key)], weighed.formula, weighed.goals, weighed.repos)
|
|
return ranked if isinstance(ranked, Failure) else epic.store.set_scores(issue.key, answer.scores, answer.moves, answer.comment) or held
|
|
|
|
|
|
def scoring_rule(home: pathlib.Path) -> str | Failure:
|
|
"""The text every plan item is scored by, which says what L, E, I and S mean."""
|
|
try:
|
|
return (home / RULE).read_text(encoding="utf-8")
|
|
except (OSError, UnicodeDecodeError) as failure:
|
|
return Failure(f"cannot read the scoring rule {home / RULE}, so no issue is scored: {failure}")
|
|
|
|
|
|
def start_order(epic: Planned, issues: list[EpicIssue]) -> list[str] | Failure:
|
|
"""The keys of the open issues that may become a chunk and hold scores, in the order they start: by score from the highest, each blocker above what it blocks, as ranking puts them. An issue nobody scored is left out, and starts after these in the tracker's rank order. So is one with no pick yet or with two, which doesn't start."""
|
|
held = [issue for issue in chunk_issues(epic, issues) if not ranking.unscored(item_of(issue, {}, ()), issue.key)]
|
|
if len(held) < 2:
|
|
return [issue.key for issue in held]
|
|
# An issue's place in the tracker is its id in the ranking: keys of two Jira projects may share a number, and issues that score the same keep the tracker's order.
|
|
numbers = {issue.key: at for at, issue in enumerate(held, 1)}
|
|
keys = {id_: key for key, id_ in numbers.items()}
|
|
weighed = weighing(epic, held)
|
|
if isinstance(weighed, Failure):
|
|
return weighed
|
|
by_key = {issue.key: issue for issue in issues}
|
|
items = [ranking.EpicItem(item_of(issue, numbers, before(issue, by_key, issues)), repo_of(epic, issue), issue.key) for issue in held]
|
|
ranked = ranking.ranked(items, weighed.formula, weighed.goals, weighed.repos)
|
|
return ranked if isinstance(ranked, Failure) else [keys[item.id] for item, _ in ranked]
|
|
|
|
|
|
def before(issue: EpicIssue, by_key: dict[str, EpicIssue], issues: list[EpicIssue]) -> tuple[str, ...]:
|
|
"""The keys of the issues that start before issue: what blocks it or its parent, and for a blocker split by repo, its sub-tasks."""
|
|
parent = by_key.get(issue.parent)
|
|
blockers = [by_key[key] for key in (*issue.blockers, *(parent.blockers if parent else ())) if key in by_key]
|
|
return tuple(each.key for blocker in blockers for each in ([task for task in issues if task.parent == blocker.key] if split.is_split(blocker, issues) else [blocker]))
|
|
|
|
|
|
def item_of(issue: EpicIssue, numbers: dict[str, int], blockers: tuple[str, ...]) -> Item:
|
|
"""The issue as ranking scores it. numbers holds the number of each issue ranked with it, by key; the item is blocked by those of them that blockers names."""
|
|
return Item(numbers.get(issue.key, 0), NO_RELEASE, issue.exempt, issue.summary, issue.scores, issue.moves, tuple(sorted(numbers[key] for key in blockers if key in numbers)))
|