Edit a Jira issue the loop filed, and score a person's with a comment saying why #558

Merged
lilleman merged 9 commits from item-382 into main 2026-11-16 02:19:45 +01:00
14 changed files with 362 additions and 47 deletions
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- `todo-item edit` and `move` work on a plan kept in a Jira epic. They change only an issue the loop filed, and never a link. Of an issue a person filed, `edit` sets only the scores, and posts the new `--comment` on the issue to tell the team why; a plan in a file takes the flag and keeps no comment.
- A release someone else cut while it still held plan items no longer stops the loop: those items count as the next release's, `chunk-preflight` tells the worker to move them there, and `loop-claude` routes on them. Where the plan names no later release and `todo.md` named none since the cut, the loop still asks which release they belong to.
- `project-record open` now writes the copy of a record kept outside a file under a folder of the worktree that ran it, `~/.local/state/project-record/<key>/<worktree>/`, so two chunks of one project no longer overwrite each other's unsaved edit. It also removes the folders of worktrees git no longer lists.
- `chunk-pr merge` merges the chunks of one project on a machine one at a time, and `--finish <ID>` finishes each plan item in the chunk's turn, so `todo.md` and `CHANGELOG.md` no longer conflict between open chunks. A pull request that waits for an approval leaves the queue while it waits, and merge stops where a reviewer's comment waits for an answer.
+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, such 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.
+2 -2
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 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 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.
@@ -205,7 +205,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy` and `adf_codec`, and reads the memory share that loop-claude waits for. It also gives `mutate_changes` a slot's CPU count.
- `model_routing/` holds the shipped routing ladder (`routing-ladder.json`) and its steps (`ladder.py`), and reads a ladder from that file or a project's own (`ladder_file.py`), for loop-claude, `rule_hook`, both replay tools and `subagent-rung`. It finds a project's config folder through `project_config`. It also holds the list prices, which `routing_figures` and `transcript_archive` read.
- `notifier/` sends the human a DM through the notifier a project's config names, for `notify` and for loop-claude through `loop_effects`; `mattermost_dm/` and `slack_dm/` are its two backends.
- `plan_store/` reads and writes a project's plan through the store the project's config names (`stores.py`), with the markdown file's edits in `markdown_edits.py`. `contract.py` holds the tests every backend that writes must pass, which `jira_epic.py` doesn't yet, and `fakes.py` a plan in memory.
- `plan_store/` reads and writes a project's plan through the store the project's config names (`stores.py`), with the markdown file's edits in `markdown_edits.py`. `contract.py` holds the tests every backend that writes must pass, which `jira_epic.py` doesn't yet, since it changes no link, and `fakes.py` a plan in memory.
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
- `record_store/` reads and writes a project's records, each through the store the project's config names (`stores.py`): a markdown file, a Confluence Cloud page (`confluence_page.py`), or, for the goals, a Jira epic's description (`jira_description.py`). `contract.py` holds the tests every backend must pass, and `fakes.py` a store in memory that the tests of other tools use.
- `release_plan/` reads `todo.md`'s items table and release versions, says which release is next and whether it is ready to cut (`release_standing.py`), and ranks the plan (`ranking.py`, with its score formula in `formula.py` and its blocker order in `blockers.py`). `goals_file.py` reads the goals file's sections, goals and goal weights, for the ranking and for `loop_claude`'s premises, and `citations.py` holds `todo.md` and `docs/decisions.md` to each other. `plan_file.py` ranks, checks and writes a `todo.md`, for `larv_review`, `rank_todo.py` and `rule_hook`.
+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.")
+7 -2
View File
@@ -12,6 +12,8 @@ class MemoryPlan:
"""A plan held in memory, as a tracker holds one: in the order filed, unranked, with no bar. Where fails is set, every read and write fails with it as the reason."""
rows: dict[int, dict[str, str]] = dataclasses.field(default_factory=dict)
details: dict[int, str] = dataclasses.field(default_factory=dict)
# Each comment an edit gave, under its item's ID, as a tracker posts them on the item's issue.
comments: dict[int, list[str]] = dataclasses.field(default_factory=dict)
next_id: int = 1
label: str = "the plan in memory"
tracked: str | None = None
@@ -26,10 +28,13 @@ 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)
written = self.put(id_, self.rows[id_] | cells(fields), self.details.get(id_, "") if detail is None else detail)
if comment is not None and isinstance(written, Written):
self.comments.setdefault(id_, []).append(comment)
return written
def finish(self, id_: int) -> Written | Failure:
if self.fails or id_ not in self.rows:
+103 -8
View File
@@ -1,8 +1,8 @@
"""A plan kept as the child issues of one Jira Cloud epic, read, filed into and finished over Jira's REST API.
"""A plan kept as the child issues of one Jira Cloud epic, read, filed into, edited and finished over Jira's REST API.
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.
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 person 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 an issue the loop filed, but never its links. 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. An edit of an issue without it, which a person filed, 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,12 @@ 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 scores a caller sets, L, E, I and S; R is worked out from them.
SET_SCORES = tuple(name for name in SHAPE.score_columns if name not in SHAPE.derived)
# The fields of PROPERTY's value that an edit may set.
SCORED = (*SET_SCORES, 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]
@@ -151,7 +156,7 @@ class JiraPlan:
if isinstance(versions, Failure):
return Failure(f"cannot read {project}'s Fix Versions: {versions.reason}")
names = {name for version in versions if isinstance(version, dict) and isinstance(name := version.get("name"), str)} if isinstance(versions, list) else set()
return next((name for name in (release, f"v{release}") if name in names), None) or Failure(f"the Jira project {project} has no Fix Version {release} or v{release}; create it in Jira, or file the item under a release it has")
return next((name for name in (release, f"v{release}") if name in names), None) or Failure(f"the Jira project {project} has no Fix Version {release} or v{release}; create it in Jira, or name a release it has")
def missing_blocker(self, blockers: tuple[str, ...], authorization: str) -> Failure | None:
"""A Failure naming the first of blockers that is no open child of the epic. `item` reads only an open child as a blocker, so a link to any other issue would be lost on the next read."""
@@ -161,8 +166,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 +276,56 @@ 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 as far as the issue and the flags allow. The description, the comment and the Fix Version's name still need the codec or a request."""
# 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. Jira's screens don't show PROPERTY, so such an edit needs a comment, which tells the team. L, E, I and S are set together, so no issue is left partly scored. 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}, and Jira doesn't show its team the scores: pass a comment saying that it is scored, and 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 not is_exempt(named.get("Exempt", "")):
return Failure(f"the item's Exempt {named['Exempt']!r} is not empty or one of {', '.join(EXEMPTIONS[1:])}")
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
if scored[0] and any(name not in scored[0] for name in SET_SCORES):
return Failure(f"{issue.key} would hold some of {', '.join(SET_SCORES)} and not the rest: set them together")
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` doesn't hold it yet: it changes no link, and its own tests stand in for Jira. 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 finish 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
+171 -5
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))
@@ -346,7 +342,7 @@ class Filing(unittest.TestCase):
for versions in ([{"name": "0.1.0"}], {"name": "0.3.0"}, [], 7):
with self.subTest(versions=versions):
self.versions = versions
self.assertEqual(self.add(FIELDS | {"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.add(FIELDS | {"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 name a release it has"))
self.assertEqual(self.sent(ISSUES), [])
def test_fix_versions_that_cannot_be_read_fail_before_anything_is_filed(self):
@@ -375,6 +371,176 @@ 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]] = []
# The loop filed ABC-34. A person filed ABC-35, which nobody scored, and ABC-36, which 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_an_edit_of_the_release_and_the_tagline_sends_both(self):
self.edit(34, {"Release": "0.2.0", "Tagline": "Count every run."})
self.assertEqual(self.writes()[0][2], {"fields": {"summary": "Count every run.", "fixVersions": [{"name": "v0.2.0"}]}})
def test_an_empty_tagline_fails_before_any_write(self):
self.assertEqual(self.edit(34, {"Tagline": "** **"}), Failure("the item has no tagline"))
self.assertEqual(self.writes(), [])
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 name 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_person_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_persons_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_persons_issue_is_never_labelled(self):
self.edit(36, {"Exempt": "security"}, None, COMMENT)
self.assertNotIn("update", self.writes()[0][2]) # type: ignore[operator]
def test_scoring_a_persons_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, and Jira doesn't show its team the scores: pass a comment saying that it is scored, and 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_scoring_an_unscored_issue_in_part_fails_before_any_write(self):
self.assertEqual(self.edit(35, {"L": "2", "E": "2"}, None, COMMENT), Failure("ABC-35 would hold some of L, E, I, S and not the rest: set them together"))
self.assertEqual(self.edit(35, {"Exempt": "question"}, None, COMMENT), Written(35))
self.assertEqual(len(self.writes()), 2)
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(36, {"L": "2"}, None, COMMENT), Written(36, ("edited ABC-36, 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"the item's Exempt 'tired' 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}}}
+17 -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,18 @@ 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 and scores, 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.
The four scores are set together where the issue holds none yet.
--comment is posted as a comment on the Jira issue, for the client's team, in the project's
language. Jira doesn't show the team the scores, so say that the issue is scored, and why.
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 +66,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, a move 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 +136,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 +210,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:
+13
View File
@@ -13,6 +13,7 @@ from project_config.settings import DEFAULT_FLOOR
from todo_item import edits, main
from failure import Failure
from project_config.main import located
from plan_store.fakes import MemoryPlan
from release_plan import plan_file, ranking
from plan_store.stores import plan_of
from todo_item.table import table
@@ -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, comments in ((["--comment", "A small change."], {3: ["A small change."]}), ([], {})):
with self.subTest(argv=argv):
plan = MemoryPlan({3: {"Release": "0.1.0", "Item": "**Count the runs.**", "L": "1", "E": "2", "I": "3", "S": "1"}})
self.assertEqual(main.edit(main.parser().parse_args(["edit", "3", "--l", "3", *argv]), plan, ""), "Edited item 3 in the plan in memory.")
self.assertEqual((plan.rows[3]["L"], plan.comments), ("3", comments))
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.** 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.
- **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 --help` says what `edit` and `move` change there. 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.
+15 -16
View File
@@ -6,13 +6,12 @@
`Bar = 0.1`
`Next ID = 389`
`Next ID = 390`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 382 | 0.11.0 | | | **Edit a Jira issue the loop filed, and score an unscored issue a teammate filed with a comment saying why.** | 4 | 2 | 3 | 7 | 4 | 1.6 by 3 | 0.8 |
| 384 | 0.11.0 | | | **Rank an issue the loop files in Jira by its score among the issues the loop filed, a security finding first.** | 3 | 2 | 2 | 5 | 3 | 1.6 by 2 | 0.7 |
| 375 | 0.11.0 | | decision | **Run up to the project's configured number of chunks at once, each in its own window of one tmux session named for the project, mark a window whose chunk waits for the human, and refuse to start without tmux at the needed version.** | 4 | 2 | 3 | 7 | 7 | 1.5 by 7 | 0.6 |
| 319 | 0.12.0 | | | **Start a fresh session with a brief of the chunk when a rung step changes the worker's model, in place of resuming the old session.** | 3 | 2 | 3 | 6 | 4 | 1.1 by 2, 1.4 by 2 | 1.2 |
@@ -27,10 +26,11 @@
| 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 |
| 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 |
| 367 | 0.13.0 | 382, 384 | | **Check that every write to a Jira plan leaves it ranked, as rule-hook's `todo-rank-check` checks `todo.md` today.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 2 | 0.7 |
| 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 | | | **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 | | | **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 | | | **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 |
| 367 | 0.13.0 | 384 | | **Check that every write to a Jira plan leaves it ranked, as rule-hook's `todo-rank-check` checks `todo.md` today.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 2 | 0.7 |
| 303 | 0.14.0 | | defect | **Archive each judge run's prompt and json reply beside the verdict it gave, so judge cost, replays and backups cover the judge as they cover the worker.** | 2 | 2 | 3 | 5 | 3 | 1.4 by 3, 3 by 2 | 4.2 |
| 306 | 0.14.0 | | | **Set a strategy that keeps loop-claude's archive and larv-review's review folders backed up and small over the years, compressing older entries without losing any.** | 3 | 2 | 4 | 7 | 5 | 3 by 5 | 3.9 |
| 304 | 0.14.0 | 303 | defect | **Archive each review-replay and judge-replay run's transcript beside its result, so a replay that decided a rung can be checked and re-priced later.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 2, 3 by 2 | 3.8 |
@@ -76,16 +76,6 @@
## Details
### 382. Edit a Jira issue the loop filed, and score an unscored issue a teammate filed with a comment saying why.
Split from item 352 on 2026-11-15; lilleman's calls, 2026-11-12. The loop edits the summary, description and scores of issues it created, which the `Filed by` mark in the `plan-item` property tells apart, and never the summary or description of an issue a person filed. An issue a teammate files without scores gets scored like any item, with a short comment saying it was scored and why; its scope stays as written. The comment reaches the client's team, so it is in the project's `language`, and its reason comes from whoever scores: `PlanStore.edit` and `todo-item edit` gain a way to pass it, whose spelling a bench of readers picks. Say in `docs/decisions.md` whether the loop may re-score or move a person's issue that already holds scores; the calls name neither.
Touches:
- `bin/plan_store/jira_epic.py`: `JiraPlan.edit`
- `bin/plan_store/test_jira_epic.py`: new tests of `edit`
- `bin/plan_store/stores.py`: `PlanStore.edit`, `FilePlan.edit`
- `bin/todo_item/main.py`: the help, `edit`'s flags
### 384. Rank an issue the loop files in Jira by its score among the issues the loop filed, a security finding first.
Split from item 352 on 2026-11-15; lilleman's call, 2026-11-12: an issue the loop files goes into Jira rank by its score among the issues the loop filed, and a security finding ranks first. The team's own rank of every other issue stays as it is.
@@ -189,6 +179,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.