Answer stability round 1: 0 🔴, 7 🟡 (0 misread); parse the formula on load, require the scoring, share the bar rule and split add

This commit is contained in:
2026-11-16 03:07:39 +01:00
parent 727ed70ecb
commit cf1180734c
12 changed files with 109 additions and 71 deletions
+6 -2
View File
@@ -111,7 +111,7 @@ A project whose pull requests need a human's approval sets `wait-for-approval =
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows: the plan, the working rules in an `AGENTS.md` I write for the agents, the records, and the goals and audience, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits in the checkout's history, so four things are not supported for it yet. `score-outcomes` and loop-claude's routing figures count a project's chunks only where `todo.md`, `docs/comprehension-history.md` and `docs/reading-cost.md` are at those paths in the checkout; otherwise each says so, and the loop goes on. For a plan or a comprehension history outside the checkout, `larv-review` says it cannot tell whether a scoring run is owed, and for such a history it cannot find a paired ruling's base. For a plan outside the checkout, chunk-preflight and loop-claude don't see a release whose last item has shipped, and say that its release review and its cut are yours to call. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
A client that plans in Jira Cloud names an epic as its project's plan: `plan = "jira:https://acme.atlassian.net/browse/ABC-12"`, which is `jira:` and the epic's address as the browser shows it. The plan is then the epic's open child issues, in Jira's backlog order, which the team sets. An issue in a done status is a finished item. Each part of an item comes from one part of its issue:
A client that plans in Jira Cloud names an epic as its project's plan: `plan = "jira:https://acme.atlassian.net/browse/ABC-12"`, which is `jira:` and the epic's address as the browser shows it. The plan is then the epic's open child issues, in Jira's backlog order, which the team sets, apart from the rank `todo-item add` gives an issue it files. An issue in a done status is a finished item. Each part of an item comes from one part of its issue:
- The ID is the issue's number, so every child must be in the epic's own Jira project.
- The tagline is the summary.
@@ -120,7 +120,11 @@ A client that plans in Jira Cloud names an epic as its project's plan: `plan = "
- A blocker is an "is blocked by" link to another open child.
- The scores are the issue property `plan-item`, a JSON object such as `{"L": 2, "E": 2, "I": 3, "S": 3, "Moves": "1.6 by 4", "Exempt": ""}`. An issue without it reads as an item nobody scored yet.
A read fails, naming the issue, where a child is in another Jira project or names no such Fix Version. The config's `env-file` must hold `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, an API token of that Atlassian account, and only its owner may read that file: `chmod 600` it. The loop reads such a plan and files items into it, each as a Task under the epic. The config also states the formula and the bar that todo.md's `## Scoring` would, such as `jira-score-formula = "100 * V / (2**S + 8)"` and `jira-score-bar = 1`, and fails to load without them. `todo-item add` refuses an item that scores under the bar, unless it is exempt. It ranks the new issue among the issues the loop filed, by score, with security findings first. A person's issues keep the rank the team gave them. `todo-item edit` and `move` change only an issue the loop filed. Of an issue a person filed, `edit` sets only the scores, and posts its `--comment` on the issue to tell the team why; the summary, description and Fix Version stay the team's to change in Jira, as do every issue's links. For `todo-item finish`, the config names the workflow transition that finishes an item and the status it leads to, both as Jira shows them: `jira-finish-transition = "Mark as done"` and `jira-finish-status = "Done"`. Finish then moves the item's issue by that transition. It refuses a transition that leads to another status, or to one Jira doesn't count as done, and fails where the config sets neither. `todo-item add` needs the item's release among the Jira project's Fix Versions, named as `1.2.0` or `v1.2.0`. `rank_todo.py` doesn't rank it, since Jira's backlog does. The four things not supported for a plan outside the checkout, above, are not supported for a plan in Jira either.
A read fails, naming the issue, where a child is in another Jira project or names no such Fix Version. The config's `env-file` must hold `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, an API token of that Atlassian account, and only its owner may read that file: `chmod 600` it.
The loop reads such a plan and files items into it, each as a Task under the epic. `todo-item add` needs the item's release among the Jira project's Fix Versions, named as `1.2.0` or `v1.2.0`. The config states the formula and the bar that a todo.md states under `## Scoring`, such as `jira-score-formula = "100 * V / (2**S + 8)"` and `jira-score-bar = 1`, and fails to load without them. `todo-item add` refuses an item that scores under the bar, unless it is exempt. It ranks the new issue among the issues the loop filed: questions first, then security findings, then by score. A person's issues keep the rank the team gave them, and `rank_todo.py` doesn't rank the plan.
`todo-item edit` and `move` change only an issue the loop filed. Of an issue a person filed, `edit` sets only the scores, and posts its `--comment` on the issue to tell the team why; the summary, description and Fix Version stay the team's to change in Jira, as do every issue's links. For `todo-item finish`, the config names the workflow transition that finishes an item and the status it leads to, both as Jira shows them: `jira-finish-transition = "Mark as done"` and `jira-finish-status = "Done"`. Finish then moves the item's issue by that transition. It refuses a transition that leads to another status, or to one Jira doesn't count as done, and fails where the config sets neither. The four things not supported for a plan outside the checkout, above, are not supported for a plan in Jira either.
A client that keeps its goals and audience in an epic's description names that epic as the goals file: `goals-and-audience = "jira:https://acme.atlassian.net/browse/ABC-12"`, which may be the plan's own epic. Such a config keeps its plan in Jira too, and reads both with the same `env-file`. The description needs `## Goals` and `## Audience` as headings, level-2 headings in Jira's editor. The loop only reads the description, so edit it in Jira; `project-record open goals-and-audience` prints a file holding its text. Whoever may edit that description sets the premises every worker and judge follows, so keep its edit rights to the people who own the project's goals.
+17 -16
View File
@@ -13,7 +13,7 @@ from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused
from release_plan.todo_table import BLOCKED_BY, EXEMPTIONS, is_exempt, Item, MOVES, parse_ids, parse_moves, parse_scores, SHAPE
from plan_store.markdown_edits import bold_cell, plain, unfit_text
from plan_store.stores import cells, Plan, Written
from project_config.settings import Epic, Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION, JIRA_SCORE_BAR, JIRA_SCORE_FORMULA
from project_config.settings import Epic, Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION
from failure import Failure
from rest_client import json_request
from release_plan.release import parsed, Release, tagged
@@ -101,8 +101,8 @@ class JiraPlan:
to_adf: ToAdf = markdown_to_adf
# How a finished item moves; None where the config doesn't say, and then `finish` is a Failure.
finish_by: Finish | None = None
# None where the config states no formula and bar, and then `add` is a Failure.
scoring: ReadsScoring | None = None
# How add scores an item: by the config's formula and bar, with the goal weights the project's records give.
scoring: ReadsScoring = dataclasses.field(kw_only=True)
@property
def label(self) -> str:
@@ -129,8 +129,6 @@ class JiraPlan:
filing = filing_of(fields, detail, self.epic)
if isinstance(filing, Failure):
return filing
if self.scoring is None:
return Failure(f"the config states no formula and bar to score the item by: set `{JIRA_SCORE_FORMULA}` and `{JIRA_SCORE_BAR}`, as `project-config --help` shows")
scoring = self.scoring.read()
if isinstance(scoring, Failure):
return Failure(f"cannot score the item to file: {scoring.reason}")
@@ -163,8 +161,12 @@ class JiraPlan:
key = created.get("key") if isinstance(created, dict) else None
if not isinstance(key, str) or not ISSUE_KEY.fullmatch(key) or project_of(key) != project_of(self.epic.key):
return Failure(f"Jira answered the new issue without an issue key in {project_of(self.epic.key)}; {PERHAPS_FILED.format(epic=self.epic.key)}")
return Written(number(key), self.linked_and_ranked(key, filing.blockers, before, authorization))
def linked_and_ranked(self, key: str, blockers: tuple[str, ...], before: str | None | Failure, authorization: str) -> tuple[str, ...]:
"""Links the filed issue named key as blocked by each of blockers, and ranks it just before the issue named before; a note for each Jira refuses."""
notes = []
for blocker in filing.blockers:
for blocker in blockers:
# Jira names the two ends by the link type's sides: the inward issue blocks the outward one, which then reads "is blocked by" it.
linked = self.http("POST", f"{self.epic.site}/rest/api/3/issueLink", authorization, {"type": {"name": BLOCKS}, "inwardIssue": {"key": blocker}, "outwardIssue": {"key": key}})
if isinstance(linked, Failure):
@@ -173,7 +175,7 @@ class JiraPlan:
notes.append(f"filed {key}, but cannot rank it: {before.reason}; rank it in Jira")
elif before is not None and (refused := self.rank_refusal(key, before, authorization)):
notes.append(f"filed {key}, but cannot rank it before {before}: {refused}; rank it in Jira")
return Written(number(key), tuple(notes))
return tuple(notes)
def rank_refusal(self, key: str, before: str, authorization: str) -> str | None:
"""Ranks the issue named key just before the issue named before; why Jira refused, or None where it didn't. Jira answers a rank it made with no body, and one it refused with an error, or with an entry per issue that holds the errors."""
@@ -311,7 +313,7 @@ def filed_score(item: Item, scoring: ranking.Scoring) -> float | Failure:
if missing := next((name for name in SET_SCORES if name not in item.scores), None):
return Failure(f"the item to file has no {missing}: score it on {', '.join(SET_SCORES[:-1])} and {SET_SCORES[-1]}")
value = ranking.item_score(item, scoring, "the item to file")
if not isinstance(value, Failure) and not item.exempt and round(value, 1) < scoring.bar:
if not isinstance(value, Failure) and ranking.falls_under(item, value, scoring.bar):
return Failure(f"the item to file scores {value:.1f}, under the bar {scoring.bar:g}; don't file it, or mark it with a reason the bar doesn't apply")
return value
@@ -319,7 +321,8 @@ def filed_score(item: Item, scoring: ranking.Scoring) -> float | Failure:
def placing(answered: list[object], new: Item, value: float, scoring: ranking.Scoring) -> str | None | Failure:
"""The key of the issue to rank the new item, which scores value, just before; None where it stays last, where Jira files it. answered is the epic's open children in backlog order.
Only the issues the loop filed count, so the team's rank of every other issue stays as it is. A security finding goes before the first of them that isn't one, and any other item before the first that isn't one and scores lower, as todo.md ranks its items."""
Only the issues the loop filed count, so the team's rank of every other issue stays as it is. The new item goes before the first of them that ranks after it as todo.md orders a release's items, blockers aside: a question first, then a security finding, as ranking.FIRST orders them, then the higher score. A tie goes after the older issue. Release doesn't count, as docs/decisions.md records."""
place = (ranking.FIRST.get(new.exempt, len(ranking.FIRST)), -value)
for raw in answered:
issue = issue_of(raw)
if isinstance(issue, Failure):
@@ -330,16 +333,14 @@ def placing(answered: list[object], new: Item, value: float, scoring: ranking.Sc
if isinstance(scored, Failure):
return scored
levels, moves, exempt = scored
if exempt == SECURITY:
continue
if new.exempt == SECURITY:
return issue.key
if missing := next((name for name in SET_SCORES if name not in levels), None):
return Failure(f"{issue.key} holds no {missing}")
# Only the scores and the moves change a score.
other = ranking.item_score(dataclasses.replace(new, scores=levels, moves=moves), scoring, issue.key)
if isinstance(other, Failure) or other < value:
return other if isinstance(other, Failure) else issue.key
if isinstance(other, Failure):
return other
if (ranking.FIRST.get(exempt, len(ranking.FIRST)), -other) > place:
return issue.key
return None
@@ -436,7 +437,7 @@ def basic_auth(env_file: pathlib.Path) -> str | Failure:
def children(epic: Epic, authorization: str, http: Http) -> list[object] | Failure:
"""The epic's open child issues in backlog order, which is the order the team ranks them in. An issue in a done status is a finished item, so it is no longer in the plan."""
"""The epic's open child issues in backlog order, which the team ranks, apart from where add ranks an issue it files. An issue in a done status is a finished item, so it is no longer in the plan."""
# The search answers no issues for an epic the account cannot see, as for one whose children are all done; asking for the epic itself tells them apart.
seen = http("GET", f"{epic.site}/rest/api/3/issue/{epic.key}?fields=summary", authorization, None)
if isinstance(seen, Failure):
+6 -4
View File
@@ -12,8 +12,8 @@ from release_plan.todo_table import BLOCKED_BY, Item, item_details, items, MOVES
from failure import Failure
from git_cli.git_repo import file_at, git, Git
from record_store.stores import goals_store, store as record_store, RecordStore
from project_config.settings import JiraScoring, ProjectConfig
from plan_store import markdown_edits
from project_config.settings import ProjectConfig, Scoring
from release_plan import ranking
from release_plan.release import Release
from text_files.file_writes import replace_file
@@ -145,8 +145,8 @@ class FilePlan:
@dataclasses.dataclass(frozen=True)
class StatedScoring:
"""The scoring that the project's config states for a plan in Jira, whose goal weights ranking reads from the goals file, the decision log and the comprehension history."""
stated: Scoring
"""The scoring of a plan in Jira: the formula and bar the project's config states, with goal weights that ranking reads from the goals file, the decision log and the comprehension history."""
stated: JiraScoring
goals: RecordStore
decisions: RecordStore
history: RecordStore
@@ -179,7 +179,9 @@ def store(config: ProjectConfig) -> PlanStore:
from plan_store.jira_epic import JiraPlan
# load refuses a config that names an epic and no env-file.
assert config.env_file is not None
scoring = StatedScoring(config.jira_scoring, goals_store(config), record_store(config, "decisions"), record_store(config, "comprehension-history"), config.readability_floor) if config.jira_scoring else None
# load refuses a config that names an epic and no formula or bar.
assert config.jira_scoring is not None
scoring = StatedScoring(config.jira_scoring, goals_store(config), record_store(config, "decisions"), record_store(config, "comprehension-history"), config.readability_floor)
return JiraPlan(config.epic, config.env_file, finish_by=config.jira_finish, scoring=scoring)
+13 -12
View File
@@ -65,7 +65,7 @@ class JiraPlan(unittest.TestCase):
return [text_of(document) for document in documents]
def store(self) -> jira_epic.JiraPlan:
return jira_epic.JiraPlan(EPIC, self.env, self.http, self.to_markdown)
return jira_epic.JiraPlan(EPIC, self.env, self.http, self.to_markdown, scoring=Stated())
def read(self, *issues: dict[str, object]) -> Plan | Failure:
self.pages, self.calls = [{"issues": list(issues)}], []
@@ -183,12 +183,12 @@ class JiraPlan(unittest.TestCase):
self.assertEqual(self.converted, [[adf("One."), adf("Three."), adf("Four.")]])
def test_a_description_the_codec_refuses_fails_the_read_naming_the_issue(self):
store = jira_epic.JiraPlan(EPIC, self.env, self.http, lambda documents: Refused(1, Failure("adf-codec refused")))
store = jira_epic.JiraPlan(EPIC, self.env, self.http, lambda documents: Refused(1, Failure("adf-codec refused")), scoring=Stated())
self.pages = [{"issues": [issue("ABC-33", description=adf("x")), issue("ABC-34"), issue("ABC-35", description=adf("y"))]}]
self.assertEqual(store.read(), Failure("ABC-35's description: adf-codec refused"))
def test_a_codec_that_cannot_run_fails_the_read(self):
store = jira_epic.JiraPlan(EPIC, self.env, self.http, lambda documents: Failure("docker is not installed"))
store = jira_epic.JiraPlan(EPIC, self.env, self.http, lambda documents: Failure("docker is not installed"), scoring=Stated())
self.pages = [{"issues": [issue("ABC-34", description=adf("x"))]}]
self.assertEqual(store.read(), Failure("cannot convert the descriptions of ABC-12's children to markdown: docker is not installed"))
@@ -253,10 +253,10 @@ class Filing(unittest.TestCase):
self.linked: object = None
self.versions: object = [{"name": "0.1.0"}, {"name": "v0.2.0"}, "odd", {"name": ["0.1.0"]}, {"name": {"en": "0.1.0"}}]
self.ranked: object = None
self.scoring: Stated | None = Stated()
self.scoring = Stated()
def http(self, method: str, url: str, authorization: str, body: object) -> object:
"""Stands in for Jira: answers the epic, self.versions for the project's Fix Versions, self.open to the search, self.created to a new issue and self.linked to a new link."""
"""Stands in for Jira: answers the epic, self.versions for the project's Fix Versions, self.open to the search, self.created to a new issue, self.linked to a new link and self.ranked to a rank."""
self.calls.append((method, url, body))
assert authorization == AUTHORIZATION
return {SEARCH: {"issues": self.open}, ISSUES: self.created, LINKS: self.linked, VERSIONS: self.versions, RANK: self.ranked}.get(url, {"key": "ABC-12"})
@@ -421,10 +421,6 @@ class Filing(unittest.TestCase):
self.assertEqual(self.add(), Failure("the formula gives the item to file no finite score"))
self.assertEqual(self.calls, [])
def test_a_config_without_a_formula_fails(self):
self.scoring = None
self.assertEqual(self.add(), Failure("the config states no formula and bar to score the item by: set `jira-score-formula` and `jira-score-bar`, as `project-config --help` shows"))
def test_ranks_the_item_just_before_the_first_issue_the_loop_filed_that_scores_lower(self):
# ABC-30 and ABC-33 are a person's, ABC-31 a security finding, and ABC-32 scores as much as the new item.
self.open = [issue("ABC-30"), filed("ABC-31", s=4, exempt="security"), filed("ABC-32"), issue("ABC-33", scores={"L": 1, "E": 1, "I": 1, "S": 4, "Moves": "1 by 1"}), filed("ABC-34", s=2), filed("ABC-35", s=3)]
@@ -437,6 +433,11 @@ class Filing(unittest.TestCase):
self.assertEqual(self.add(FIELDS | {"Exempt": "security", "S": "4"}), Written(40))
self.assertEqual(self.sent(RANK), [{"issues": ["ABC-40"], "rankBeforeIssue": "ABC-32"}])
def test_ranks_a_question_just_before_the_first_issue_the_loop_filed_that_isnt_one(self):
self.open = [filed("ABC-31", exempt="question"), filed("ABC-32", s=4, exempt="security")]
self.assertEqual(self.add(FIELDS | {"Exempt": "question"}), Written(40))
self.assertEqual(self.sent(RANK), [{"issues": ["ABC-40"], "rankBeforeIssue": "ABC-32"}])
def test_leaves_the_item_last_where_no_issue_the_loop_filed_scores_lower(self):
self.open = [issue("ABC-30", scores={}), filed("ABC-31"), filed("ABC-32", s=2, exempt="security")]
self.assertEqual(self.add(), Written(40))
@@ -499,7 +500,7 @@ class Editing(unittest.TestCase):
return adf(markdown)
def edit(self, id_: int, fields: dict[str, str], detail: str | None = None, comment: str | None = None):
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, self.to_adf).edit(id_, fields, detail, comment)
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, self.to_adf, scoring=Stated()).edit(id_, fields, detail, comment)
def writes(self) -> list[tuple[str, str, object]]:
"""Each request that changes Jira, in order."""
@@ -636,7 +637,7 @@ class Editing(unittest.TestCase):
body = self.writes()[0][2]
held = issue("ABC-34", summary=body["fields"]["summary"], scores=body["properties"][0]["value"], description=body["fields"]["description"]) # type: ignore[index]
self.open = [held]
plan = jira_epic.JiraPlan(EPIC, self.env, self.http, lambda documents: [text_of(document) for document in documents]).read()
plan = jira_epic.JiraPlan(EPIC, self.env, self.http, lambda documents: [text_of(document) for document in documents], scoring=Stated()).read()
assert isinstance(plan, Plan), plan
self.assertEqual((plan.items[0].tagline, plan.items[0].scores["S"], plan.items[0].scores["L"], plan.items[0].detail), ("**Count every run.**", 4, 1, "Why it counts."))
@@ -664,7 +665,7 @@ class Finishing(unittest.TestCase):
return {SEARCH: {"issues": self.open}}.get(url, {"key": "ABC-12"})
def finish(self, id_: int = 34, by: Finish | None = Finish("Mark as done", "Done")):
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, finish_by=by).finish(id_)
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, finish_by=by, scoring=Stated()).finish(id_)
def posts(self) -> list[tuple[str, str, object]]:
return [call for call in self.calls if call[0] == "POST" and call[1] != SEARCH]
+9 -9
View File
@@ -8,7 +8,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from project_config.settings import DEFAULT_FLOOR, Epic, Finish, ProjectConfig, Scoring, SETTINGS
from project_config.settings import DEFAULT_FLOOR, Epic, Finish, JiraScoring, ProjectConfig, SETTINGS
from failure import Failure
from record_store.stores import FileStore, goals_store, store as record_store
from plan_store.contract import FIRST, MOVES, PlanStoreContract, SECOND
@@ -207,37 +207,37 @@ class Store(unittest.TestCase):
def test_an_epic_picks_jira_with_the_env_files_credentials(self):
epic = Epic("https://acme.atlassian.net", "ABC-12")
picked = stores.store(self.config(epic=epic, env_file=pathlib.Path("/secrets/acme.env")))
self.assertEqual(picked, JiraPlan(epic, pathlib.Path("/secrets/acme.env"), picked.http))
picked = stores.store(self.config(epic=epic, env_file=pathlib.Path("/secrets/acme.env"), jira_scoring=JiraScoring("V", 1)))
self.assertEqual(picked, JiraPlan(epic, pathlib.Path("/secrets/acme.env"), picked.http, scoring=picked.scoring))
def test_an_epic_finishes_an_item_as_the_config_says(self):
finish = Finish("Mark as done", "Done")
picked = stores.store(self.config(epic=Epic("https://acme.atlassian.net", "ABC-12"), env_file=pathlib.Path("/secrets/acme.env"), jira_finish=finish))
picked = stores.store(self.config(epic=Epic("https://acme.atlassian.net", "ABC-12"), env_file=pathlib.Path("/secrets/acme.env"), jira_finish=finish, jira_scoring=JiraScoring("V", 1)))
self.assertEqual(picked.finish_by, finish)
def test_an_epic_scores_by_the_configs_formula_and_bar_and_the_projects_records(self):
config = self.config(epic=Epic("https://acme.atlassian.net", "ABC-12"), env_file=pathlib.Path("/secrets/acme.env"), jira_scoring=Scoring("V / 2**S", 1.5), readability_floor=decimal.Decimal("6.5"))
config = self.config(epic=Epic("https://acme.atlassian.net", "ABC-12"), env_file=pathlib.Path("/secrets/acme.env"), jira_scoring=JiraScoring("V / 2**S", 1.5), readability_floor=decimal.Decimal("6.5"))
picked = stores.store(config)
self.assertEqual(picked.scoring, stores.StatedScoring(Scoring("V / 2**S", 1.5), goals_store(config), record_store(config, "decisions"), record_store(config, "comprehension-history"), decimal.Decimal("6.5")))
self.assertEqual(picked.scoring, stores.StatedScoring(JiraScoring("V / 2**S", 1.5), goals_store(config), record_store(config, "decisions"), record_store(config, "comprehension-history"), decimal.Decimal("6.5")))
class StatedScoring(unittest.TestCase):
def test_weighs_the_goals_the_goals_file_holds(self):
scoring = stores.StatedScoring(Scoring("V / 2**S", 1.5), MemoryStore(README), MemoryStore(), MemoryStore(), DEFAULT_FLOOR).read()
scoring = stores.StatedScoring(JiraScoring("V / 2**S", 1.5), MemoryStore(README), MemoryStore(), MemoryStore(), DEFAULT_FLOOR).read()
assert not isinstance(scoring, Failure), scoring
self.assertEqual((scoring.bar, list(scoring.goals)), (1.5, ["1", "2", "2.1"]))
def test_weighs_code_health_by_the_history_and_the_floor_it_is_given(self):
for floor, under in ((DEFAULT_FLOOR, True), (decimal.Decimal("6.0"), False)):
with self.subTest(floor=floor):
scoring = stores.StatedScoring(Scoring("V", 1), MemoryStore("## Goals\n\n1. **Achieve:** A.\n"), MemoryStore(), MemoryStore(SCORED.format(overall="6.99")), floor).read()
scoring = stores.StatedScoring(JiraScoring("V", 1), MemoryStore("## Goals\n\n1. **Achieve:** A.\n"), MemoryStore(), MemoryStore(SCORED.format(overall="6.99")), floor).read()
assert not isinstance(scoring, Failure), scoring
self.assertEqual(scoring.weights["code health"] > scoring.weights["1"] * 2, under)
def test_a_goals_file_that_is_empty_or_cannot_be_read_fails(self):
for goals, reason in ((MemoryStore(), "the record in memory: missing or empty"), (MemoryStore(fails="Jira answered 403"), "Jira answered 403")):
with self.subTest(reason=reason):
read = stores.StatedScoring(Scoring("V", 1), goals, MemoryStore(), MemoryStore(), DEFAULT_FLOOR).read()
read = stores.StatedScoring(JiraScoring("V", 1), goals, MemoryStore(), MemoryStore(), DEFAULT_FLOOR).read()
assert isinstance(read, Failure), read
self.assertTrue(read.reason.startswith(reason), read.reason)
+6 -5
View File
@@ -31,9 +31,9 @@ and readme.md, since the reviewers and the rules name those files.
Jira's backlog order, and `project-config plan` prints the setting as the config spells it. Such a
config must set `env-file`, and that file must hold ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN.
Such a config must also set `jira-score-formula` and `jira-score-bar`, which a todo.md states under
## Scoring as `Score` and `Bar`, as `rank_todo.py --help` shows: the formula that scores an item, and
the lowest score at which `todo-item add` files one that isn't exempt. The bar is a bare number:
Such a config must also set two settings. `jira-score-formula` is the formula that scores an item.
`jira-score-bar` is the lowest score at which `todo-item add` files an item that isn't exempt, as a
bare number. They hold what a todo.md states as `Score` and `Bar`, which `rank_todo.py --help` describes:
jira-score-formula = "100 * V / (2**S + 8)"
jira-score-bar = 1
@@ -128,8 +128,9 @@ Exit 1, naming each fault on stderr, where no config names the checkout, or its
setting, names an unknown one, misspells a path, a language or a template, sets `wait-for-approval` or
`tooling-on-host` to anything but true or false, sets `notifier` to anything but mattermost or slack or
without `env-file`, sets `jira-finish-transition` or `jira-finish-status` to anything but a name, without the other or
without a `plan` in Jira, names a Jira `plan` without `jira-score-formula` and `jira-score-bar`, sets
either without such a plan, or the bar to anything but a number, or sets `readability-floor` to anything but a number
without a `plan` in Jira, names a Jira `plan` and leaves out `jira-score-formula` or `jira-score-bar`, sets
one of those two without a `plan` in Jira, sets the formula to one that doesn't parse or the bar to anything
but a number, or sets `readability-floor` to anything but a number
from 1 to 10, and where `env-file`, `jira-finish-transition`, `jira-finish-status`, `notifier` or `touch-predictions` is asked for and not set. No path setting has a default.
"""
import pathlib
+19 -6
View File
@@ -10,7 +10,10 @@ import tomllib
import typing
from failure import Failure
from release_plan.formula import parse_formula
from release_plan.todo_table import SHAPE
from project_config import templates
from release_plan.ranking import variables
PROJECTS = ".claude-projects"
CONFIG = "config.toml"
@@ -43,7 +46,7 @@ TOUCH_PREDICTIONS = "touch-predictions"
JIRA_FINISH_TRANSITION = "jira-finish-transition"
JIRA_FINISH_STATUS = "jira-finish-status"
JIRA_FINISH = (JIRA_FINISH_TRANSITION, JIRA_FINISH_STATUS)
# Two settings, needed where `plan` names a Jira epic and allowed only there, which a todo.md states under ## Scoring instead: the formula that scores an item, and the bar, the lowest score at which an item is filed. Three readers, seated as the human who writes a client's config, picked the spelling from four candidates: "formula" says the value is no score, and "score-bar" what the bar applies to.
# Two settings, needed where `plan` names a Jira epic and allowed only there: what a todo.md states under ## Scoring.
JIRA_SCORE_FORMULA = "jira-score-formula"
JIRA_SCORE_BAR = "jira-score-bar"
JIRA_SCORE = (JIRA_SCORE_FORMULA, JIRA_SCORE_BAR)
@@ -83,7 +86,7 @@ class Finish:
@dataclasses.dataclass(frozen=True)
class Scoring:
class JiraScoring:
"""How a plan in Jira scores an item: by formula, such as `100 * V / (2**S + 8)`, with bar the lowest score at which one is filed."""
formula: str
bar: float
@@ -127,7 +130,7 @@ class ProjectConfig:
# The config's `jira-finish-transition` and `jira-finish-status`, or None where it sets neither.
jira_finish: Finish | None = None
# The config's `jira-score-formula` and `jira-score-bar`, which it sets where `plan` names an epic.
jira_scoring: Scoring | None = None
jira_scoring: JiraScoring | None = None
# The Confluence page of each record the config keeps on one, by the record's setting.
pages: dict[str, Page] = dataclasses.field(default_factory=dict)
@@ -193,6 +196,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
floor = floor_of(values[READABILITY_FLOOR]) if READABILITY_FLOOR in values else DEFAULT_FLOOR
finish = [name for setting in JIRA_FINISH if (name := name_of(values.get(setting)))]
formula, bar = values.get(JIRA_SCORE_FORMULA), values.get(JIRA_SCORE_BAR)
scoring = JiraScoring(formula, bar_value) if isinstance(formula, str) and (bar_value := bar_of(bar)) is not None else None
checks = {LANGUAGE: language_fault, COMMIT_TITLE: templates.title_fault, PULL_REQUEST_TITLE: templates.title_fault, BRANCH: templates.branch_fault}
faults = [
*(f"`{name}` is missing" for name in SETTINGS if name not in values),
@@ -213,7 +217,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
*(f"`{name}` is set, so `plan` must name a Jira epic" for name in JIRA_FINISH if name in values and not epics["plan"]),
*(f"`plan` names a Jira epic, so `{name}` must be set, as `project-config --help` shows" for name in JIRA_SCORE if epics["plan"] and name not in values),
*(f"`{name}` is set, so `plan` must name a Jira epic" for name in JIRA_SCORE if name in values and not epics["plan"]),
*([f"`{JIRA_SCORE_FORMULA}` is {formula!r}, not a formula, such as \"100 * V / (2**S + 8)\""] if JIRA_SCORE_FORMULA in values and not name_of(formula) else []),
*([f"`{JIRA_SCORE_FORMULA}` is {formula!r}: {fault}"] if JIRA_SCORE_FORMULA in values and (fault := formula_fault(formula)) else []),
*([f"`{JIRA_SCORE_BAR}` is {bar!r}, not a bare number, such as `{JIRA_SCORE_BAR} = 1`"] if JIRA_SCORE_BAR in values and bar_of(bar) is None else []),
*(f"`{name}` is {value!r}, not true or false" for name, value in ((WAIT_FOR_APPROVAL, waits), (TOOLING_ON_HOST, on_host)) if not isinstance(value, bool)),
*([f"`{READABILITY_FLOOR}` is {values[READABILITY_FLOOR]!r}, not a number from 1 to 10; write a bare number, such as `{READABILITY_FLOOR} = 7.0`"] if floor is None else []),
@@ -221,9 +225,18 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
]
if faults:
return Failure(f"{file}: {'; '.join(faults)}. The settings are {', '.join(SETTINGS)}, and optionally {', '.join(OPTIONAL[:-1])} and {OPTIONAL[-1]}.")
# faults names a floor the config misspells.
# faults names a floor the config misspells, and a formula or bar a plan in Jira lacks or misspells.
assert floor is not None
return ProjectConfig(file.parent.name, file.parent, top, {name: path for name, path in paths.items() if path}, env_file, waits is True, on_host is True, floor, **{name.replace("-", "_"): str(values[name]) for name in checks if name in values}, epic=epics["plan"], goals_epic=epics["goals-and-audience"], notifier=notifier, jira_finish=Finish(*finish) if finish else None, jira_scoring=Scoring(typing.cast(str, formula), typing.cast(float, bar_of(bar))) if epics["plan"] else None, pages=pages)
assert scoring is not None or not epics["plan"]
return ProjectConfig(file.parent.name, file.parent, top, {name: path for name, path in paths.items() if path}, env_file, waits is True, on_host is True, floor, **{name.replace("-", "_"): str(values[name]) for name in checks if name in values}, epic=epics["plan"], goals_epic=epics["goals-and-audience"], notifier=notifier, jira_finish=Finish(*finish) if finish else None, jira_scoring=scoring, pages=pages)
def formula_fault(value: object) -> str | None:
"""Why value is no formula that may score an item, as todo.md's `Score` line states one; None where it is one."""
if not isinstance(value, str):
return "not a formula, such as \"100 * V / (2**S + 8)\""
parsed = parse_formula(value, variables(SHAPE))
return parsed.reason if isinstance(parsed, Failure) else None
def bar_of(value: object) -> float | None:
+9 -2
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, load, NOTIFIERS, OUTSIDE, Page, ProjectConfig, Scoring, SETTINGS, Unnamed
from project_config.settings import 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
@@ -325,7 +325,7 @@ class LoadTest(ConfigCase):
self.write("acme", JIRA_CLIENT.replace("jira-score-bar = 1", "jira-score-bar = 0.5"))
named = load(self.checkout, self.checkout, self.home)
assert isinstance(named, ProjectConfig), named
self.assertEqual(named.jira_scoring, Scoring("100 * V / (2**S + 8)", 0.5))
self.assertEqual(named.jira_scoring, JiraScoring("100 * V / (2**S + 8)", 0.5))
def test_a_plan_in_a_file_holds_no_formula_or_bar_of_the_configs(self) -> None:
self.write("acme", CLIENT)
@@ -348,6 +348,13 @@ class LoadTest(ConfigCase):
config.write_text(CLIENT + JIRA_SCORING)
self.assertIn("`jira-score-formula` is set, so `plan` must name a Jira epic; `jira-score-bar` is set, so `plan` must name a Jira epic", self.failure())
def test_a_formula_that_doesnt_parse_fails_naming_the_setting_and_why(self) -> None:
config = self.write("acme", JIRA_CLIENT) / "config.toml"
for formula, why in (("V +", "the formula 'V +' does not parse"), ("X", "the formula 'X' may hold only numbers, E, I, L, R, S, V, + - * / ** and parentheses")):
with self.subTest(formula=formula):
config.write_text(JIRA_CLIENT.replace('"100 * V / (2**S + 8)"', f'"{formula}"'))
self.assertIn(f"`jira-score-formula` is '{formula}': {why}", self.failure())
def test_a_notifier_that_is_unknown_or_has_no_env_file_fails_naming_it(self) -> None:
self.write("acme", CLIENT + 'env-file = "~/acme.env"\nnotifier = "teams"\n')
self.assertIn("`notifier` is 'teams', not mattermost or slack", self.failure())
+6 -1
View File
@@ -70,7 +70,7 @@ def rank(text: str, goals_text: str, decisions: str, history: str, floor: decima
ranked = rank_details(rewrite_table(lines, table, shape, scored), [item for item, _ in scored])
if isinstance(ranked, Failure):
return ranked
under_bar = [under_the_bar(item, value, scoring.bar, items) for item, value in scored if not item.exempt and round(value, 1) < scoring.bar]
under_bar = [under_the_bar(item, value, scoring.bar, items) for item, value in scored if falls_under(item, value, scoring.bar)]
return Ranked(ranked, under_bar, notes(items, scoring))
@@ -302,6 +302,11 @@ def with_risk(item: Item) -> Item:
return dataclasses.replace(item, scores=item.scores | {"R": risk(item.scores["L"], item.scores["E"], item.scores["I"])})
def falls_under(item: Item, value: float, bar: float) -> bool:
"""Whether the item, which scores value, may not be planned: it scores under the bar, rounded as todo.md shows a Score, and isn't exempt."""
return not item.exempt and round(value, 1) < bar
def item_score(item: Item, scoring: Scoring, name: str) -> float | Failure:
"""The score of an item that holds no R, such as an issue in Jira; refused where it names a goal it may not. name is what a message calls the item."""
if broken := cited_goals_failure(item, scoring, name):
+11 -6
View File
@@ -272,12 +272,17 @@ class CodeHealth(unittest.TestCase):
return SCORED.format(overall=overall).removeprefix("# Comprehension history\n\n").replace("2026-10-08T12", at).replace("PR #1 at aaaaaaa", read)
def test_a_plan_in_jira_weighs_the_goals_as_todo_md_does(self):
opted_out = "## review opt-out: the comprehension check\n\nCosts rounds.\n"
for decisions, history, floor in (("", SCORED.format(overall="6.99"), DEFAULT_FLOOR), ("", SCORED.format(overall="6.99"), decimal.Decimal("6.0")), (opted_out, "", DEFAULT_FLOOR)):
with self.subTest(decisions=decisions, history=history, floor=floor):
stated = ranking.config_scoring("V", 1, self.readme, decisions, history, floor)
read = ranking.read_scoring(self.todo, self.todo.split("\n"), self.readme, decisions, history, ranking.SHAPE, floor)
self.assertEqual(stated if isinstance(stated, Failure) else stated.weights, read if isinstance(read, Failure) else read.weights)
# As the two tests below: code health weighs 1 / 1.97 at or over the floor and four times that under it, goal 1 0.97 / 1.97.
for floor, code_health in ((DEFAULT_FLOOR, 4 / 1.97), (decimal.Decimal("6.0"), 1 / 1.97)):
with self.subTest(floor=floor):
stated = ranking.config_scoring("V", 1, self.readme, "", SCORED.format(overall="6.99"), floor)
assert not isinstance(stated, Failure), stated
self.assertEqual(set(stated.weights), {"code health", "1"})
self.assertAlmostEqual(stated.weights["code health"], code_health)
self.assertAlmostEqual(stated.weights["1"], 0.97 / 1.97)
opted_out = ranking.config_scoring("V", 1, self.readme, "## review opt-out: the comprehension check\n\nCosts rounds.\n", "", DEFAULT_FLOOR)
assert isinstance(opted_out, Failure), opted_out
self.assertTrue(opted_out.reason.startswith("docs/decisions.md opts out of the comprehension check"), opted_out.reason)
def test_ranks_code_health_first_among_the_achieve_goals_at_an_overall_of_7_or_above(self):
# Code health, then goal 1: weights 1 / 1.97 and 0.97 / 1.97, an item moving one by 1 at S 1 scoring 50 times its weight.
+5 -6
View File
@@ -31,12 +31,11 @@ It prints `Filed item <ID> in <plan>.` It doesn't write anything where ranking f
In a Jira epic, add files a Task under the epic, and <ID> is the new issue's number. The release
must be one of the Jira project's Fix Versions, named as 1.2.0 or v1.2.0 there, and --exempt
security also labels the issue `security`. The item scores by the config's `jira-score-formula`, and
add refuses it under `jira-score-bar` unless it is exempt. Jira then ranks it among the issues the
loop filed only: just before the first that scores lower, or for a security finding, before the
first that isn't one; else it stays last. A person's issues keep their rank, and a security finding
the loop filed comes before every other issue the loop filed. Where Jira files the issue and then
refuses a --blocked-by link or the rank, add still prints `Filed item <ID> …`, and says on stderr
what to do in Jira.
add refuses it under `jira-score-bar` unless it is exempt. add then asks Jira to rank the new issue
just before the first issue the loop filed that ranks after it: a question before any other, then a
security finding, then the higher score. Where none does, it stays last. A person's issues don't
count, and keep their rank. Where Jira files the issue and then refuses a --blocked-by link or the
rank, add still prints `Filed item <ID> …`, and says on stderr what to do in Jira.
edit sets the cells whose flag is given and leaves the rest; an empty value, as in --blocked-by "",
empties the cell. --detail replaces the detail with the text on stdin, and --clear-detail removes it.
+2 -2
View File
@@ -331,13 +331,13 @@ Messages keep each file's usual name, such as `todo.md`, as its label, since the
2026-11-14, larv-review, on lilleman's calls of 2026-11-12 and 2026-11-14. Serves goal 1.6: a client's team keeps planning in its own Jira. Valid while a client's plan fits one epic in one Jira project.
- **One epic is one project's plan, and Jira's backlog rank orders it.** The team sets the rank, so the loop's score doesn't break ties and the loop never moves an issue once filed (lilleman, 2026-11-12). An item is an open child issue; one in a done status category is finished.
- **One epic is one project's plan, and Jira's backlog rank orders it.** The team sets the rank, so the loop's score doesn't break ties and the loop never reranks an issue once filed (lilleman, 2026-11-12). An item is an open child issue; one in a done status category is finished.
- **A bench of readers picked the spelling.** Three fresh readers, seated as the person who writes a client's `config.toml`, each picked `plan = "jira:https://<site>/browse/<key>"` over the bare address, a `jira:<key>` beside a `jira-site` key, and a `[plan]` table. Each also picked one pair of env-file keys, `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, for Jira and Confluence over a pair for each, since one account's token opens both.
- **An item's ID stays a whole number: the issue's number in the epic's Jira project.** About 30 modules read an ID as an int, and the `branch` and title templates already spell a ticket's name, as `ABC-{id}`. So the store refuses a child issue from another Jira project, and counts a blocker only among the plan's own items (`bin/plan_store/jira_epic.py`).
- **The scores sit in one issue property, `plan-item`**, which needs no Jira admin (lilleman, 2026-11-12). An issue without it reads as an item nobody scored.
- **The release is the earliest Fix Version named as a semver version**, and an issue with none fails the read, naming it.
- **The loop files an item as a Task under the epic, and marks it as its own** (lilleman's calls of 2026-11-12). `"Filed by": "loop"` in the `plan-item` property tells such an issue from one a person filed, whose summary and description the loop never edits. Task is an issue type every Jira Software project template has; a project without it refuses the issue, saying so. The issue takes the project's Fix Version named as the release, with a leading v or without, and the store refuses an item whose release the project has no Fix Version for, before it files anything. A security finding also gets the label `security`, and its text never holds a secret's value. Jira takes a blocker's link only after the issue exists, so the store first checks that each blocker is an open child. A link Jira still refuses leaves the issue filed: the write counts as landed, with a note naming the link to make by hand. A failed create says the issue may exist all the same, since a lost answer doesn't tell.
- **The config states the formula and the bar, and the store ranks a new issue among the loop's own** (lilleman, 2026-11-12; the loop chose the rank rule, 2026-11-16). A plan in Jira has no `## Scoring`, so a config whose `plan` names an epic must set `jira-score-formula` and `jira-score-bar`, and fails to load without them, as without a path setting. A bench of readers picked the spelling: three fresh readers, seated as the person who writes a client's `config.toml`, each picked those keys over `jira-score` and `jira-bar`, `score-formula` and `score-bar`, and bare `score` and `bar`. The prefix matches the other Jira-only settings, "formula" says the value is no score, and "score-bar" says what the bar applies to. The store scores the item as `rank_todo.py` scores a row, with the goal weights from the goals file, the decision log and the comprehension history. It refuses an item under the bar that isn't exempt, or one whose Moves names a goal the goals file lacks, before it files anything. Then it ranks the issue just before the first issue the loop filed that scores lower and isn't a security finding; a security finding goes before the first issue the loop filed that isn't one. A person's issues don't count, so the team's rank of each stays as it is. A rank Jira refuses, or an issue of the loop's that no longer scores, leaves the new issue filed and last, with a note to rank it by hand.
- **The config states the formula and the bar, and the store ranks a new issue among the loop's own** (lilleman, 2026-11-12 and 2026-11-15). A plan in Jira has no `## Scoring`, so a config whose `plan` names an epic must set `jira-score-formula` and `jira-score-bar`. It fails to load without them, or with a formula that doesn't parse, since no setting a config needs has a default. A bench of readers picked the spelling: three fresh readers, seated as the person who writes a client's `config.toml`, each picked those keys over `jira-score` and `jira-bar`, `score-formula` and `score-bar`, and bare `score` and `bar`. The prefix matches the other Jira-only settings, "formula" says the value is no score, and "score-bar" says what the bar applies to. The store scores the item as `rank_todo.py` scores a row, with the goal weights from the goals file, the decision log and the comprehension history. It refuses an item under the bar that isn't exempt, or one whose Moves names a goal the goals file lacks, before it files anything. Then it ranks the issue just before the first issue the loop filed that ranks after it. A person's issues don't count, so the team's rank of each stays as it is. The order is todo.md's within a release: a question first, then a security finding, then the higher score, with a tie after the older issue. Questions go first because `rank_todo.py` ranks them ahead of security findings, since an answer may change other items (the loop's choice, 2026-11-16). Release doesn't count, since lilleman's call ranks by score among the loop's issues. A rank Jira refuses, or an issue of the loop's that no longer scores, leaves the new issue filed and last, with a note to rank it by hand.
- **The store edits and moves only an issue the loop filed, and of an issue a person filed it sets only the scores** (lilleman's calls of 2026-11-12). On its own issue it sets the summary, description, scores and Fix Version in one request, so Jira takes all of an edit or none, and it keeps the label `security` in step with Exempt. Of a person's issue it writes only the `plan-item` property, and a comment: the team's screens don't show the property, so the comment tells the team why the scores changed, and the store refuses the edit without one. The comment's text comes from whoever scores, in the project's `language`. Where Jira takes the edit and then refuses the comment, the edit counts as made, and a note says to post the comment by hand. No edit changes a link, until `todo.md` item 389.
- **The loop may re-score a person's issue that already holds scores, and never moves it.** lilleman's calls of 2026-11-12 cover an issue nobody scored, and say nothing of one that holds scores; larv-review chose on 2026-11-16, through todo item 382. A re-score changes only the loop's own reading of the issue, and not what the person wrote, so it is allowed, with a comment as the first scores need. L, E, I and S are set together, so no issue is left partly scored. The Fix Version says when the team ships the issue, and a release is its team's, so the store refuses the move and `CLAUDE.md` has the worker ask the human to move the issue.
- **`todo-item edit --comment` carries the comment, and a plan in a file takes the flag and keeps no comment**, so one command works in every project, as goal 1.3 asks. A bench of readers picked the spelling: three fresh readers, seated as the consultant who runs the loop in a client's project, each picked `--comment` over `--reason`, `--why` and `--because`. Only it says the text is posted where the team reads it, and `--reason` read as `--exempt`'s reason.