Edit a Jira issue the loop filed, and score a teammate's with a comment saying why
CI / tests (pull_request) Successful in 1m48s

This commit is contained in:
2026-11-16 01:55:57 +01:00
parent 0681e9be17
commit 2e9d9dd714
13 changed files with 326 additions and 27 deletions
+2 -2
View File
@@ -6,10 +6,10 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
- **Until the goals file has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning. In a README both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count; the one exception is code health, which "Shared goal" below states for every project.
- **Keep a plan in `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, and the human approves it.
- **Read and change the plan's items only with `~/.claude/bin/todo-item`**, which lists, shows, files, edits, moves and finishes them; `todo-item --help` says how. It reads a plan in Jira as it does a file, and there it files and finishes an item but doesn't edit or move one yet. Two open the file itself: whoever plans a release, to compare Scores across releases, which `todo-item list` doesn't print; and whoever edits `## Scoring` or `## Renamed`, or reshapes an old table.
- **Read and change the plan's items only with `~/.claude/bin/todo-item`**, which lists, shows, files, edits, moves and finishes them; `todo-item --help` says how. It reads a plan in Jira as it does a file. There it edits and moves only an issue the loop filed; of an issue a person filed it sets only the scores, with `--comment` telling the team why. Two open the file itself: whoever plans a release, to compare Scores across releases, which `todo-item list` doesn't print; and whoever edits `## Scoring` or `## Renamed`, or reshapes an old table.
- **When the next release has no items and no work has landed towards it, plan it as this chunk.** Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
- **When the next release has no items left and work has landed towards it, its release review is the chunk** (`larv-review` §3 → "Release review"). **Once that has merged and the release holds no item, the release is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix, or an item its release review filed, lands, into that release; never start a later release's items or plan a new one.
- **Where someone cut a release that still holds items, those items are the next release's.** Move them there as the chunk's first change and say so in its opening line; where `todo-item` cannot move this plan's items, as in a Jira plan, ask the human in the chunk's summary to move them. Where the plan names no later release, ask the human which one they belong to.
- **Where someone cut a release that still holds items, those items are the next release's.** Move them there as the chunk's first change and say so in its opening line; where `todo-item` cannot move an item, as an issue a person filed in a Jira plan, ask the human in the chunk's summary to move it. Where the plan names no later release, ask the human which one they belong to.
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that doesn't publish anything says so once.
- **A client project's `CLAUDE.md` and `AGENTS.md` in its repo belong to its team.** Read both at the start of each chunk there. Propose each change that aligns them with this setup in a pull request of its own, never inside a chunk's; the one edit a chunk makes there is a decision's title in `AGENTS.md`. Until the team accepts a proposal, and after it declines or doesn't answer, follow the team's rule unless it breaks one of the project's goals. Record each such conflict as a decision in the `decisions` record, as `rules/decisions.md` asks: which rule you follow, why, and the open proposal's PR. Then nobody is asked twice.
- **Read the goals file's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
+1 -1
View File
@@ -120,7 +120,7 @@ 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, and doesn't edit an issue yet. `todo-item edit` and `move` fail, so edit its issues in Jira. 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 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 does 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 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.
+7
View File
@@ -72,6 +72,13 @@ class PlanStoreContract:
self.assertEqual(self.items(store)[id_].release, release_of("0.3.0"))
self.assertEqual(self.items(store)[id_].detail, "")
def test_an_edit_with_a_comment_sets_the_fields_as_one_without(self) -> None:
store = self.new_store()
id_ = self.filed(store, FIRST, "Why it counts.")
self.assertEqual(store.edit(id_, {"L": "2"}, None, "A small change to one module."), Written(id_))
item = self.items(store)[id_]
self.assertEqual((item.scores["L"], item.detail), (2, "Why it counts."))
def test_finish_removes_the_item_and_keeps_the_others(self) -> None:
store = self.new_store()
first, second = self.filed(store, FIRST, "Why it counts."), self.filed(store, SECOND, "Later detail.")
+1 -1
View File
@@ -26,7 +26,7 @@ class MemoryPlan:
def add(self, fields: dict[str, str], detail: str) -> Written | Failure:
return self.put(self.next_id, cells(fields), detail)
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
def edit(self, id_: int, fields: dict[str, str], detail: str | None, comment: str | None = None) -> Written | Failure:
if id_ not in self.rows:
return Failure(f"{self.label} holds no item {id_}")
return self.put(id_, self.rows[id_] | cells(fields), self.details.get(id_, "") if detail is None else detail)
+94 -5
View File
@@ -2,7 +2,7 @@
An item is an open child issue. Its ID is the issue's number, so every child must be in the epic's own Jira project: ABC-34 is item 34 of the plan under ABC-12. The summary is the tagline, the description the detail, the earliest Fix Version the release, and an "is blocked by" link a blocker. L, E, I, S, Moves and Exempt sit in one issue property, PROPERTY, which needs no Jira admin to set up; an issue a teammate filed holds none, and reads as an item without scores.
`add` files an item as a new child issue, marked with FILED_BY, and `finish` moves an item's issue to a done status. edit is a Failure until todo.md's item 382."""
`add` files an item as a new child issue, marked with FILED_BY, and `finish` moves an item's issue to a done status. `edit` changes any field but the links of an issue the loop filed. Of an issue a person filed it sets only the scores, with a comment that tells the team why."""
import base64
import dataclasses
import pathlib
@@ -29,8 +29,7 @@ TIMEOUT = 30
PAGE = 100
# The pages one read asks for at most, so an answer that never names a last page ends the read.
MAX_PAGES = 100
READ_ONLY = "the loop doesn't edit an issue of a plan in Jira yet: edit it in Jira"
# The key in PROPERTY's value that marks an issue the loop filed, and its value. The loop never edits the summary or description of an issue without it, which a person filed.
# The key in PROPERTY's value that marks an issue the loop filed, and its value. Of an issue without it, which a person filed, the loop writes only PROPERTY and a comment.
FILED_BY = ("Filed by", "loop")
# The issue type of an issue the loop files, which Jira Software's project templates all have; a project without it refuses the issue, saying so.
ISSUE_TYPE = "Task"
@@ -43,6 +42,10 @@ DONE = "done"
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under {epic} before filing the item again"
# What a failed move ends with, for the same reason.
PERHAPS_MOVED = "unless Jira refused the request, the issue may have moved: look at {key} before finishing the item again"
# What a failed edit ends with, for the same reason.
PERHAPS_EDITED = "unless Jira refused the request, the issue may have changed: look at {key} before editing the item again"
# The fields of PROPERTY's value that an edit may set.
SCORED = (*SHAPE.score_columns, MOVES, "Exempt")
# Sends a request with the Authorization header given, the body as JSON where there is one, and returns the JSON answer, None where the answer has no body, or a Failure saying why there is none.
Http = typing.Callable[[str, str, str, object], object]
@@ -161,8 +164,48 @@ class JiraPlan:
held = {raw.get("key") for raw in answered if isinstance(raw, dict)}
return next((Failure(f"{self.label} holds no item {number(blocker)} to be blocked by") for blocker in blockers if blocker not in held), None)
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
return Failure(READ_ONLY)
def edit(self, id_: int, fields: dict[str, str], detail: str | None, comment: str | None = None) -> Written | Failure:
"""Sets the fields and the detail in one request, so Jira takes all of the edit or none, and then posts comment on the issue. `revision_of` says what an edit may set.
A comment Jira refuses leaves the edit made, so the write counts as landed, and a note says to post the comment by hand."""
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
answered = children(self.epic, authorization, self.http)
if isinstance(answered, Failure):
return answered
key = f"{project_of(self.epic.key)}-{id_}"
raw = next((raw for raw in answered if isinstance(raw, dict) and raw.get("key") == key), None)
if raw is None:
return Failure(f"{self.label} holds no item {id_}")
issue = issue_of(raw)
if isinstance(issue, Failure):
return issue
revision = revision_of(issue, cells(fields), detail, comment)
if isinstance(revision, Failure):
return revision
body = revision.body
if detail is not None:
description = self.to_adf(detail) if detail.strip() else None
if isinstance(description, Failure):
return Failure(f"cannot convert the item's detail to a Jira description: {description.reason}")
body = body | {"fields": body.get("fields", {}) | {"description": description}}
said = self.to_adf(comment) if comment and comment.strip() else None
if isinstance(said, Failure):
return Failure(f"cannot convert the comment to a Jira comment: {said.reason}")
if revision.release is not None:
version = self.fix_version(revision.release, authorization)
if isinstance(version, Failure):
return version
body = body | {"fields": body.get("fields", {}) | {"fixVersions": [{"name": version}]}}
url = f"{self.epic.site}/rest/api/3/issue/{key}"
edited = self.http("PUT", url, authorization, body)
if isinstance(edited, Failure):
return Failure(f"cannot edit {key}: {edited.reason}; {PERHAPS_EDITED.format(key=key)}")
if said is None:
return Written(id_)
posted = self.http("POST", f"{url}/comment", authorization, {"body": said})
return Written(id_, (f"edited {key}, but cannot post the comment: {posted.reason}; post it in Jira",) if isinstance(posted, Failure) else ())
def finish(self, id_: int) -> Written | Failure:
"""Moves item id_'s issue by the transition that the config names, to the status it names. Any open child of the epic may move, whoever filed it."""
@@ -231,6 +274,52 @@ def filing_of(fields: dict[str, str], detail: str, epic: Epic) -> Filing | Failu
return Filing(issue_fields, release, value, tuple(f"{project}-{blocker}" for blocker in blockers))
@dataclasses.dataclass(frozen=True)
class Revision:
"""An edit checked and ready to send, but for what needs a request or the codec first."""
# The body of the request that edits the issue, without its description and its Fix Version.
body: dict[str, typing.Any]
# The release to move the issue to; None where the edit names none.
release: str | None
def revision_of(issue: Issue, named: dict[str, str], detail: str | None, comment: str | None) -> Revision | Failure:
"""The edit of issue that sets the cells in named, and the detail unless None, or why it cannot be made.
The summary, description and Fix Version of an issue a person filed are the team's, so there an edit may set only SCORED, which the team never sees but in the comment that must come with it. An issue the loop filed also keeps the label SECURITY in step with its Exempt. No edit changes a link."""
held = issue.scores
if not isinstance(held, dict):
return Failure(f"{issue.key}'s issue property {PROPERTY} is not a JSON object")
if BLOCKED_BY in named:
return Failure(f"the loop doesn't change an issue's links: link {issue.key} in Jira")
own = held.get(FILED_BY[0]) == FILED_BY[1]
if not own and ("Item" in named or "Release" in named or detail is not None):
return Failure(f"a person filed {issue.key}, so the loop sets only its scores: change its summary, description and Fix Version in Jira")
if not own and not (comment and comment.strip()):
return Failure(f"a person filed {issue.key}, so its team must read why its scores change: pass a comment saying why")
body: dict[str, typing.Any] = {}
if "Item" in named:
summary = plain(named["Item"]).strip()
if not summary:
return Failure("the item has no tagline")
body["fields"] = {"summary": summary}
if unfit := unfit_text(named.get("Item", ""), detail or ""):
return unfit
release = named.get("Release")
if release is not None and parsed(release) is None:
return Failure(f"the item's Release {release!r} is not a version such as 1.2.0")
if any(name in named for name in SCORED):
texts = {name: str(value) for name, value in held.items()} | {name: named[name] for name in SCORED if name in named}
scored = scores(issue.key, texts)
if isinstance(scored, Failure):
return scored
value = held | scored[0] | {MOVES: texts.get(MOVES, ""), "Exempt": scored[2]}
body["properties"] = [{"key": PROPERTY, "value": value}]
if own and (scored[2] == SECURITY) != (held.get("Exempt") == SECURITY):
body["update"] = {"labels": [{"add" if scored[2] == SECURITY else "remove": SECURITY}]}
return Revision(body, release)
def offer_of(raw: object) -> tuple[str, str, str, str] | None:
"""One transition Jira offers, as its ID, its name, the name of the status it leads to and the key of that status's category; None where raw holds no such transition."""
to = raw.get("to") if isinstance(raw, dict) else None
+6 -4
View File
@@ -47,7 +47,7 @@ class Written:
class PlanStore(typing.Protocol):
"""A project's plan. plan_store.contract holds every backend that writes to the same behaviour; `jira_epic` reads, files and finishes, and fails an edit until todo.md's item 382. A write that fails leaves the plan as it was, except where its Failure says the tracker may have taken the write all the same, as when Jira's answer to a new issue or to a move is lost."""
"""A project's plan. plan_store.contract holds every backend that writes to the same behaviour; `jira_epic` is held by its own tests, since it edits less of an issue a person filed. A write that fails leaves the plan as it was, except where its Failure says the tracker may have taken the write all the same, as when Jira's answer to a new issue, an edit or a move is lost."""
@property
def label(self) -> str:
@@ -63,8 +63,10 @@ class PlanStore(typing.Protocol):
def add(self, fields: dict[str, str], detail: str) -> Written | Failure:
"""Files an item under an ID the backend picks. fields holds each of FIELDS the caller sets; detail may be empty."""
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
"""Sets item id_'s fields to those given, and its detail unless None, leaving the rest. Moving an item sets its Release."""
def edit(self, id_: int, fields: dict[str, str], detail: str | None, comment: str | None = None) -> Written | Failure:
"""Sets item id_'s fields to those given, and its detail unless None, leaving the rest. Moving an item sets its Release.
comment tells the plan's other readers why, in the project's language. A tracker posts it on the item's issue; a backend with no place for comments drops it."""
def finish(self, id_: int) -> Written | Failure:
"""Removes item id_ with its detail."""
@@ -98,7 +100,7 @@ class FilePlan:
filed = markdown_edits.added(texts[0], cells(fields), detail, self.label)
return filed if isinstance(filed, Failure) else self.kept(*filed, texts)
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
def edit(self, id_: int, fields: dict[str, str], detail: str | None, comment: str | None = None) -> Written | Failure:
texts = self.texts()
if isinstance(texts, Failure):
return texts
+157 -4
View File
@@ -210,10 +210,6 @@ class JiraPlan(unittest.TestCase):
self.pages = [{"issues": [issue("OTHER-5")]}]
self.assertNotIn("s3cret", self.store().read().reason) # type: ignore[union-attr]
def test_edit_fails_since_the_store_does_not_edit_yet(self):
self.assertEqual(self.store().edit(34, {"L": "2"}, None), Failure("the loop doesn't edit an issue of a plan in Jira yet: edit it in Jira"))
self.assertEqual(self.calls + self.epic_calls, [])
def test_names_itself_by_the_configs_spelling_and_no_commit_holds_it(self):
self.assertEqual((self.store().label, self.store().tracked), ("jira:https://acme.atlassian.net/browse/ABC-12", None))
@@ -375,6 +371,163 @@ class Filing(unittest.TestCase):
TRANSITIONS = "https://acme.atlassian.net/rest/api/3/issue/ABC-34/transitions"
COMMENT = "Scored for planning: a small change to one module."
PERHAPS_EDITED = "unless Jira refused the request, the issue may have changed: look at ABC-34 before editing the item again"
class Editing(unittest.TestCase):
def setUp(self) -> None:
self.env = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "acme.env"
self.env.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
self.env.chmod(0o600)
self.calls: list[tuple[str, str, object]] = []
# ABC-34 is the loop's, ABC-35 a teammate's that nobody scored, ABC-36 a teammate's that holds scores.
self.open: list[object] = [issue("ABC-34", scores=PROPERTY), issue("ABC-35"), issue("ABC-36", scores={"L": 3, "E": 1, "I": 1, "S": 2})]
self.edited: object = None
self.commented: object = {"id": "10100"}
self.versions: object = [{"name": "0.1.0"}, {"name": "v0.2.0"}]
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.edited to an edit and self.commented to a new comment."""
self.calls.append((method, url, body))
assert authorization == AUTHORIZATION
if method == "PUT":
return self.edited
return self.commented if url.endswith("/comment") else {SEARCH: {"issues": self.open}, VERSIONS: self.versions}.get(url, {"key": "ABC-12"})
def to_adf(self, markdown: str) -> dict[str, object] | Failure:
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)
def writes(self) -> list[tuple[str, str, object]]:
"""Each request that changes Jira, in order."""
return [call for call in self.calls if call[0] == "PUT" or call[1].endswith("/comment")]
def test_sets_the_summary_description_and_scores_of_an_issue_the_loop_filed_in_one_request(self):
self.assertEqual(self.edit(34, {"Tagline": "**Count every run.**", "L": "2", "Moves": ""}, "Why it counts."), Written(34))
self.assertEqual(self.writes(), [("PUT", f"{ISSUES}/ABC-34", {
"fields": {"summary": "Count every run.", "description": adf("Why it counts.")},
"properties": [{"key": "plan-item", "value": PROPERTY | {"L": 2, "Moves": ""}}],
})])
def test_sends_only_what_the_edit_names(self):
self.edit(34, {"Tagline": "Count every run."})
self.edit(34, {"E": "3"})
self.assertEqual([body for _, _, body in self.writes()], [{"fields": {"summary": "Count every run."}}, {"properties": [{"key": "plan-item", "value": PROPERTY | {"E": 3}}]}])
def test_an_empty_detail_removes_the_description(self):
self.edit(34, {}, " \n")
self.assertEqual(self.writes(), [("PUT", f"{ISSUES}/ABC-34", {"fields": {"description": None}})])
def test_an_edit_of_the_release_sets_the_fix_version_as_the_project_spells_it(self):
self.assertEqual(self.edit(34, {"Release": "0.2.0"}), Written(34))
self.assertEqual(self.writes(), [("PUT", f"{ISSUES}/ABC-34", {"fields": {"fixVersions": [{"name": "v0.2.0"}]}})])
def test_a_release_the_project_has_no_fix_version_for_fails_before_any_write(self):
self.assertEqual(self.edit(34, {"Release": "0.3.0"}), Failure("the Jira project ABC has no Fix Version 0.3.0 or v0.3.0; create it in Jira, or file the item under a release it has"))
self.assertEqual(self.writes(), [])
def test_an_exempt_that_becomes_or_stops_being_security_adds_or_removes_the_label(self):
self.edit(34, {"Exempt": "security"})
self.open = [issue("ABC-34", scores=PROPERTY | {"Exempt": "security"})]
self.edit(34, {"Exempt": "owner"})
self.edit(34, {"Exempt": "security"})
self.assertEqual([body.get("update") for _, _, body in self.writes()], [{"labels": [{"add": "security"}]}, {"labels": [{"remove": "security"}]}, None]) # type: ignore[attr-defined]
def test_scores_an_issue_a_teammate_filed_and_comments_why(self):
self.assertEqual(self.edit(35, {"L": "2", "E": "2", "I": "3", "S": "3", "Moves": "1 by 4"}, None, COMMENT), Written(35))
self.assertEqual(self.writes(), [
("PUT", f"{ISSUES}/ABC-35", {"properties": [{"key": "plan-item", "value": {"L": 2, "E": 2, "I": 3, "S": 3, "Moves": "1 by 4", "Exempt": ""}}]}),
("POST", f"{ISSUES}/ABC-35/comment", {"body": adf(COMMENT)}),
])
def test_rescores_a_teammates_issue_that_holds_scores_keeping_the_rest(self):
self.edit(36, {"L": "2"}, None, COMMENT)
self.assertEqual(self.writes()[0][2], {"properties": [{"key": "plan-item", "value": {"L": 2, "E": 1, "I": 1, "S": 2, "Moves": "", "Exempt": ""}}]})
def test_a_teammates_issue_is_never_labelled(self):
self.edit(35, {"Exempt": "security"}, None, COMMENT)
self.assertNotIn("update", self.writes()[0][2]) # type: ignore[operator]
def test_scoring_a_teammates_issue_without_a_comment_fails_before_any_write(self):
for comment in (None, "", " \n"):
with self.subTest(comment=comment):
self.assertEqual(self.edit(35, {"L": "2"}, None, comment), Failure("a person filed ABC-35, so its team must read why its scores change: pass a comment saying why"))
self.assertEqual(self.writes(), [])
def test_what_a_person_wrote_or_planned_is_never_edited(self):
for fields, detail in (({"Tagline": "Count every run."}, None), ({}, "Why."), ({}, ""), ({"Release": "0.2.0"}, None), ({"Tagline": "Count.", "Release": "0.2.0", "L": "1"}, "")):
with self.subTest(fields=fields, detail=detail):
self.assertEqual(self.edit(36, fields, detail, COMMENT), Failure("a person filed ABC-36, so the loop sets only its scores: change its summary, description and Fix Version in Jira"))
self.assertEqual(self.writes(), [])
def test_a_comment_on_an_edit_of_the_loops_own_issue_is_posted_too(self):
self.edit(34, {"L": "2"}, None, COMMENT)
self.assertEqual(self.writes()[1], ("POST", f"{ISSUES}/ABC-34/comment", {"body": adf(COMMENT)}))
def test_a_comment_jira_refuses_leaves_the_edit_made_with_a_note(self):
self.commented = Failure("HTTP 403")
self.assertEqual(self.edit(35, {"L": "2"}, None, COMMENT), Written(35, ("edited ABC-35, but cannot post the comment: HTTP 403; post it in Jira",)))
def test_an_edit_of_the_blockers_fails_since_the_store_changes_no_link(self):
self.assertEqual(self.edit(34, {"Blocked by": "35"}), Failure("the loop doesn't change an issue's links: link ABC-34 in Jira"))
self.assertEqual(self.writes(), [])
def test_an_issue_that_is_no_open_child_of_the_epic_is_not_edited(self):
self.assertEqual(self.edit(40, {"L": "2"}), Failure("jira:https://acme.atlassian.net/browse/ABC-12 holds no item 40"))
self.assertEqual(self.writes(), [])
def test_each_field_out_of_format_fails_before_any_write_saying_how(self):
for fields, detail, reason in (
({"L": "9"}, None, "item ABC-34's L '9' is not a whole number from 1 to 4"),
({"Moves": "much"}, None, "item ABC-34's Moves 'much' is not"),
({"Exempt": "tired"}, None, f"ABC-34's issue property plan-item holds the Exempt 'tired', which is not empty or one of {', '.join(EXEMPTIONS[1:])}"),
({"Release": "soon"}, None, "the item's Release 'soon' is not a version such as 1.2.0"),
({"Tagline": " "}, None, "the item has no tagline"),
({"Tagline": "Count\nruns."}, None, "the tagline holds a line break; keep it on one line"),
({}, "## Why", "the detail holds a ## or ### heading"),
):
with self.subTest(fields=fields, detail=detail):
failed = self.edit(34, fields, detail)
self.assertIsInstance(failed, Failure)
self.assertIn(reason, failed.reason)
self.assertEqual(self.writes(), [])
def test_a_detail_or_a_comment_that_does_not_convert_fails_before_any_write(self):
self.to_adf = lambda markdown: Failure("the codec is down") # type: ignore[method-assign]
self.assertEqual(self.edit(34, {}, "Why."), Failure("cannot convert the item's detail to a Jira description: the codec is down"))
self.assertEqual(self.edit(34, {"L": "2"}, None, COMMENT), Failure("cannot convert the comment to a Jira comment: the codec is down"))
self.assertEqual(self.writes(), [])
def test_an_edit_jira_refuses_fails_with_jiras_reason_and_posts_no_comment(self):
self.edited = Failure("HTTP 400: Summary is too long")
self.assertEqual(self.edit(34, {"L": "2"}, None, COMMENT), Failure(f"cannot edit ABC-34: HTTP 400: Summary is too long; {PERHAPS_EDITED}"))
self.assertEqual(len(self.writes()), 1)
def test_an_issue_in_another_shape_or_a_search_that_fails_fails_the_edit(self):
self.open = [{"key": "ABC-34", "fields": {}}]
self.assertIn("ABC-34 is not in the shape", self.edit(34, {"L": "2"}).reason)
self.open = [issue("ABC-34", scores=["odd"])] # type: ignore[arg-type]
self.assertEqual(self.edit(34, {"L": "2"}), Failure("ABC-34's issue property plan-item is not a JSON object"))
self.assertEqual(self.writes(), [])
def test_a_missing_env_file_fails_before_any_request(self):
self.env.unlink()
self.assertIsInstance(self.edit(34, {"L": "2"}), Failure)
self.assertEqual(self.calls, [])
def test_what_it_edits_reads_back_as_the_item(self):
self.edit(34, {"Tagline": "Count every run.", "S": "4"}, "Why it counts.")
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()
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."))
def transition(id_: str, name: str, status: str, category: str = "done") -> dict[str, object]:
return {"id": id_, "name": name, "to": {"name": status, "statusCategory": {"key": category}}}
+15 -6
View File
@@ -6,12 +6,12 @@ usage: todo-item list [--release <version>]
[--blocked-by <IDs>] [--exempt <reason>] <tagline> [<<'EOF' detail EOF]
todo-item edit <ID> [--tagline <tagline>] [--l <L>] [--e <E>] [--i <I>] [--s <S>] [--moves <moves>]
[--blocked-by <IDs>] [--exempt <reason>] [--detail <<'EOF' detail EOF | --clear-detail]
[--comment <why>]
todo-item move <ID> --release <version>
todo-item finish <ID> [--changelog <bullet> | --no-changelog]
Run inside a checkout. Every command works on the plan the project's config names, which
`project-config plan` prints: a markdown file, todo.md, or a Jira epic. In a Jira epic, list,
show, add and finish work, and edit and move fail so far. Each command that changes
`project-config plan` prints: a markdown file, todo.md, or a Jira epic. Each command that changes
a todo.md ranks it as rank_todo.py does, and so reads the goals file, docs/decisions.md and the
comprehension history, each where the config puts it.
The cells take the format rank_todo.py --help states; the letter flags take upper case too, as --L.
@@ -39,8 +39,16 @@ empties the cell. --detail replaces the detail with the text on stdin, and --cle
Text on stdin without --detail, and --detail without text on stdin, are refused, so no detail is
dropped or wiped by mistake. It prints `Edited item <ID> in <plan>.` It doesn't write anything where
ranking fails or scores the item under the bar.
In a Jira epic, edit changes an issue the loop filed: its summary, description, scores and Fix
Version, and the label `security` with --exempt. It doesn't change a link, so --blocked-by fails.
Of an issue a person filed it sets only the scores, --moves and --exempt, and only with --comment.
--comment is posted as a comment on the Jira issue, for the client's team: say why the edit is
made, in the project's language. A todo.md keeps no comment, so there the flag doesn't do anything.
Where Jira takes the edit and then refuses the comment, edit still prints `Edited item <ID> …`,
and says on stderr to post the comment in Jira.
move sets the item's release, as edit sets a cell. It prints `Moved item <ID> to release <version> in <plan>.`
In a Jira epic, move sets the Fix Version of an issue the loop filed; a person moves their own.
finish removes the item and its detail. With --changelog it adds the bullet first under
CHANGELOG.md's ## Unreleased, or a ## heading that says unreleased, creating the section, or the
@@ -56,9 +64,9 @@ from its present status, or where the transition leads to another status or to o
count as done. An issue that no chunk built is dropped in Jira, not with finish, which would mark it done.
Exit 2 on bad arguments, and 1, saying why, on any other failure. A message opening `not filed:`,
`not edited:`, `not moved:` or `not finished:` means it didn't write anything. The one exception is an add to, or a
finish in, a Jira epic that Jira didn't answer or answered brokenly: the message then says the issue
may exist, or may have moved.
`not edited:`, `not moved:` or `not finished:` means it didn't write anything. The one exception is an add,
an edit or a finish in a Jira epic that Jira didn't answer or answered brokenly: the message then
says the issue may exist, may have changed or may have moved.
"""
import argparse
import pathlib
@@ -126,6 +134,7 @@ def parser() -> argparse.ArgumentParser:
detail = editing.add_mutually_exclusive_group()
detail.add_argument("--detail", action="store_true")
detail.add_argument("--clear-detail", action="store_true")
editing.add_argument("--comment")
moving = commands.add_parser("move")
moving.add_argument("id", type=int)
moving.add_argument("--release", required=True)
@@ -199,7 +208,7 @@ def edit(args: argparse.Namespace, plan: PlanStore, text: str) -> str | Failure:
detail = text if args.detail else "" if args.clear_detail else None
if not fields(args) and detail is None:
return Failure("not edited: no flag names a change; todo-item --help lists them")
return reported(plan.edit(args.id, fields(args), detail), "not edited", lambda written: f"Edited item {written.id} in {plan.label}.")
return reported(plan.edit(args.id, fields(args), detail, args.comment), "not edited", lambda written: f"Edited item {written.id} in {plan.label}.")
def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore) -> str | Failure:
+14 -1
View File
@@ -4,6 +4,7 @@ import pathlib
import sys
import tempfile
import unittest
import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
@@ -14,7 +15,7 @@ from todo_item import edits, main
from failure import Failure
from project_config.main import located
from release_plan import plan_file, ranking
from plan_store.stores import plan_of
from plan_store.stores import plan_of, Written
from todo_item.table import table
ADD = ["add", "--release", "0.1.0", "--l", "1", "--e", "1", "--i", "1", "--s", "1", "--moves", "1 by 9", "Count the `a | b` runs."]
@@ -415,6 +416,18 @@ class Edit(TodoItem):
def test_refuses_an_edit_that_changes_nothing(self):
self.assertEqual(self.run_main("edit", "3"), (1, "", "not edited: no flag names a change; todo-item --help lists them\n"))
self.assertEqual(self.run_main("edit", "3", "--comment", "Why.")[::2], (1, "not edited: no flag names a change; todo-item --help lists them\n"))
def test_an_edit_hands_the_comment_to_the_plan(self):
for argv, comment in ((["--comment", "A small change."], "A small change."), ([], None)):
with self.subTest(argv=argv):
plan = unittest.mock.Mock(label="the plan", edit=unittest.mock.Mock(return_value=Written(3)))
self.assertEqual(main.edit(main.parser().parse_args(["edit", "3", "--l", "3", *argv]), plan, ""), "Edited item 3 in the plan.")
plan.edit.assert_called_once_with(3, {"L": "3"}, None, comment)
def test_a_plan_in_a_file_takes_an_edit_with_a_comment_and_keeps_no_comment(self):
self.assertEqual(self.run_main("edit", "3", "--l", "3", "--comment", "A small change.")[:2], (0, f"Edited item 3 in {self.todo}.\n"))
self.assertNotIn("A small change.", self.todo.read_text())
def test_leaves_the_file_ranked(self):
self.run_main("edit", "1", "--s", "2", "--moves", "1 by 10")
+4 -1
View File
@@ -337,7 +337,10 @@ Messages keep each file's usual name, such as `todo.md`, as its label, since the
- **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 ranks the new issue last, and no bar or goals check applies, until todo.md's item 384 says where a plan in Jira states its formula. 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 store reads, files and finishes, and doesn't edit an issue** until todo.md's item 382. It finishes an item with the transition that the config's `jira-finish-transition` names, which must lead to the status `jira-finish-status` names, since each Jira workflow differs (lilleman's call, 2026-11-12); any open child of the epic may move. It refuses a status outside Jira's done status category: the read counts an issue as finished only in that category, so the item would stay in the plan. Where the issue's present status has no direct transition to the status `jira-finish-status` names, `todo-item finish` fails and a person moves the issue in Jira: the store never walks an issue through other statuses to reach it. lilleman answered on 2026-11-15: "If it is possible to move it to done without a transisiont, that should happen. If not, fail." The implementer read "without a transition" as "without a transition in between". `rank_todo.py` refuses to rank a plan in Jira, and its `--check` passes, since Jira's backlog ranks it; rule-hook's rank check skips it. Each read first asks Jira for the epic itself, since a search under an epic the account cannot see answers no issues, as a finished plan does.
- **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.** The calls name neither; larv-review chose on 2026-11-16, through todo item 382. A re-score needs a comment as the first scores do: the scores are the loop's own reading of the issue, and its scope stays as written. 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.
- **A bench of readers picked `todo-item edit --comment`.** 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. A plan in a file takes the flag and keeps no comment, so one command works in every project, as goal 1.3 asks.
- **The store finishes an item with the transition that the config's `jira-finish-transition` names**, which must lead to the status `jira-finish-status` names, since each Jira workflow differs (lilleman's call, 2026-11-12); any open child of the epic may move. It refuses a status outside Jira's done status category: the read counts an issue as finished only in that category, so the item would stay in the plan. Where the issue's present status has no direct transition to the status `jira-finish-status` names, `todo-item finish` fails and a person moves the issue in Jira: the store never walks an issue through other statuses to reach it. lilleman answered on 2026-11-15: "If it is possible to move it to done without a transisiont, that should happen. If not, fail." The implementer read "without a transition" as "without a transition in between". `rank_todo.py` refuses to rank a plan in Jira, and its `--check` passes, since Jira's backlog ranks it; rule-hook's rank check skips it. Each read first asks Jira for the epic itself, since a search under an epic the account cannot see answers no issues, as a finished plan does.
## project config: `tooling-on-host = true` lets a project with no container setup run its language runtime, package manager, tests and task runner on the host
+13
View File
@@ -2298,3 +2298,16 @@ Read most (opens and searches):
- `docs/decisions.md` 1
- `rules/decisions.md` 1
- `settings.json` 1
## Reading cost, chunk a8246f8e9771, finished 2026-11-16T00:48:07Z
97222 new input tokens before the first commit.
Read most (opens and searches):
- `todo.md` 7
- `bin/project_config/settings.py` 3
- `rules/todo-items.md` 3
- `docs/score-anchors.md` 2
- `bin/release_plan/release.py` 1
- `bin/release_plan/release_standing.py` 1
+1 -1
View File
@@ -5,7 +5,7 @@ paths:
# Todo items (`todo.md`)
- **A plan is mandatory in every project, and a plan kept as `todo.md` has the shape `rank_todo.py --help` shows**, which `~/.claude/bin/rank_todo.py` checks and ranks; its `--help` shows a valid file. A plan in a Jira epic is read from the epic's open child issues. `todo-item add` files an item there as a new child issue, and `todo-item finish` moves an item's issue to done, and `todo-item` can't edit or move an issue yet. Below, `todo.md` means a plan kept as a file, and "the plan" either kind. `## Scoring` holds the formula and the bar; `## Items` is one table of every item; `## Details` holds each item's detail under its ID. `## Renamed` marks each renamed release with a line such as `- 0.2.1 renamed to 0.3.0`; `rank_todo.py --help` says what a mark does. Cite an item by its ID. The formula and bar are the project's own to tune.
- **A plan is mandatory in every project, and a plan kept as `todo.md` has the shape `rank_todo.py --help` shows**, which `~/.claude/bin/rank_todo.py` checks and ranks; its `--help` shows a valid file. A plan in a Jira epic is read from the epic's open child issues. `todo-item add` files an item there as a new child issue, and `todo-item finish` moves an item's issue to done. `todo-item edit` and `move` change only an issue the loop filed; of an issue a person filed, `edit` sets only the scores, and needs `--comment`, which tells the team why. Below, `todo.md` means a plan kept as a file, and "the plan" either kind. `## Scoring` holds the formula and the bar; `## Items` is one table of every item; `## Details` holds each item's detail under its ID. `## Renamed` marks each renamed release with a line such as `- 0.2.1 renamed to 0.3.0`; `rank_todo.py --help` says what a mark does. Cite an item by its ID. The formula and bar are the project's own to tune.
- **File an item with `~/.claude/bin/todo-item add`, and change one with `todo-item edit` or `todo-item move`.** `add` and `edit --detail` read the item's detail from stdin, and all three commands rank the plan; `todo-item --help` shows the flags. `todo-item finish <ID> --no-changelog` drops an item no chunk built. Edit `todo.md` itself only for what `todo-item` has no command for: `## Scoring`, `## Renamed`, and reshaping an old table.
- **Order items only by score and the Blocked by column.** An item's Blocked by cell lists the IDs of the items that must be done before it starts, such as `12, 14`; `rank_todo.py --help` says how it ranks them. No text in `todo.md` outside the table orders items: where an item must go first, score it so, and say why in its detail.
- **Plan only on the project's rung or above.** loop-claude's prompt tells you when you run below it. Below it, never score or re-score an item, move it between releases, split a milestone into items, delete an item under the bar, rewrite a filed item's tagline or detail, or choose or replace an item in `docs/score-anchors.md`. Draft each new item, each change to a filed item, and each change to the anchors, instead. Before your next commit, launch one subagent to apply the drafts, score them and set their release. Launch it on the rung `CLAUDE.md`'s delegation rule gives a subagent that files or scores items. Keep the scores and releases it writes. For a security finding, launch it at once. Any rung may remove a finished item's row and detail, and score a delegated task's L. A subagent launched for another task leaves the plan alone.
+11 -1
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 389`
`Next ID = 390`
## Items
@@ -27,6 +27,7 @@
| 331 | 0.12.0 | | | **Reword four decisions to expire when the rungs their replays tested change, not whenever a model joins the ladder.** | 1 | 1 | 1 | 1 | 2 | 1.4 by 2 | 0.8 |
| 381 | 0.12.0 | | | **Read a `Touches:` list from a plan kept in Jira as from one in todo.md, with a test that converts a description through `adf_codec`.** | 1 | 2 | 1 | 2 | 2 | 1.5 by 2 | 0.7 |
| 327 | 0.12.0 | | | **Have `larv-review` print a round commit's title prefix, counted from the round's report, and have rule-hook refuse a round title whose counts differ from it.** | 3 | 2 | 3 | 6 | 4 | 1.1 by 1, 1.4 by 1 | 0.6 |
| 389 | 0.12.0 | | decision | **Set a Jira issue's "is blocked by" links from `todo-item edit --blocked-by`, on an issue the loop filed.** | 2 | 2 | 2 | 4 | 4 | 1.6 by 2 | 0.5 |
| 365 | 0.13.0 | 382 | | **Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
| 368 | 0.13.0 | 382 | | **Call a release review due, call a release ready to cut, and tell whether a chunk owes a scoring run, for a plan outside the checkout, from the project repo's history or from Jira.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
| 366 | 0.13.0 | 382 | | **Count the chunks of a project whose plan sits outside the checkout in the routing figures, from the project repo's history or from Jira.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.4 by 2 | 1.1 |
@@ -189,6 +190,15 @@ Add a `larv-review` subcommand that prints a round title's prefix, up to and inc
Left with the model: the summary after the `;`, and answering the findings.
### 389. Set a Jira issue's "is blocked by" links from `todo-item edit --blocked-by`, on an issue the loop filed.
Filed by item 382's chunk on 2026-11-16. `JiraPlan.edit` refuses an edit of Blocked by, saying to link the issue in Jira, so a worker cannot mark an item it filed as blocked once it exists. Read each link's id from the search's `issuelinks`, make a link per new blocker as `add` does, and delete one per blocker removed, after `missing_blocker`'s check. Say in `docs/decisions.md` whether the loop may link an issue a person filed; the decision on the Jira epic as a plan says the loop writes only the scores of such an issue.
Touches:
- `bin/plan_store/jira_epic.py`: `Issue`, `issue_of`, `JiraPlan.edit`, `revision_of`
- `bin/plan_store/test_jira_epic.py`: `Editing`
- `bin/todo_item/main.py`: the help
### 365. Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.
lilleman's call, 2026-11-12: 0.10.0 and 0.11.0 switch the history tools off for a plan outside the checkout, and 0.13.0 holds only their ports. In Jira a dropped item, which `Drop item` commit titles mark today, is an issue resolved by a resolution the config names.