File a plan item as a child issue of the project's Jira epic

This commit is contained in:
2026-11-15 03:16:11 +01:00
parent 6804b9496e
commit 8e79cb7dc8
8 changed files with 230 additions and 21 deletions
+2 -2
View File
@@ -2,11 +2,11 @@
## Working loop
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. A rule names a project's files by their usual paths: `todo.md`, `AGENTS.md`, `CHANGELOG.md` and the files under `docs/`. Each is where the project's config puts it, which `~/.claude/bin/project-config` prints and `chunk-preflight`'s facts quote. Where the config names a Jira epic as the plan, the plan is the epic's open child issues, which no tool writes yet. Read and edit a project record in the file `~/.claude/bin/project-record open <record>` prints, and run `project-record save <record>` after each edit. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. A rule names a project's files by their usual paths: `todo.md`, `AGENTS.md`, `CHANGELOG.md` and the files under `docs/`. Each is where the project's config puts it, which `~/.claude/bin/project-config` prints and `chunk-preflight`'s facts quote. Where the config names a Jira epic as the plan, the plan is the epic's open child issues, where `todo-item` files an item as a new one. Read and edit a project record in the file `~/.claude/bin/project-record open <record>` prints, and run `project-record save <record>` after each edit. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
- **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 writes only a file for now. 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, and there it files an item but doesn't edit, move or finish 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.
- **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.
- **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.
+1 -1
View File
@@ -117,7 +117,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 only reads such a plan so far. `todo-item add`, `edit`, `move` and `finish` fail, so file, edit and finish its issues in Jira. `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, and doesn't edit or finish an issue yet. `todo-item add`, `edit`, `move` and `finish` fail, so file, edit and finish its issues in Jira. `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.
+95 -8
View File
@@ -2,21 +2,21 @@
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.
The store only reads so far: every write is a Failure."""
The store reads and files: `add` creates a child issue, and edit and finish are a Failure until todo.md's items 382 and 383. An issue it files holds FILED_BY in PROPERTY, which tells it from one a person filed, whose summary and description the loop never edits."""
import base64
import dataclasses
import pathlib
import re
import typing
from adf_codec.convert import adfs_to_markdown, Refused
from plan_store.markdown_edits import bold_cell
from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused
from plan_store.markdown_edits import bold_cell, plain, unfit_text
from project_config.settings import Epic
from release_plan.todo_table import EXEMPTIONS, is_exempt, Item, MOVES, parse_moves, parse_scores, SHAPE
from release_plan.todo_table import BLOCKED_BY, EXEMPTIONS, is_exempt, Item, MOVES, parse_ids, parse_moves, parse_scores, SHAPE
from failure import Failure
from rest_client import json_request
from release_plan.release import parsed, Release, tagged
from plan_store.stores import Plan, Written
from plan_store.stores import cells, Plan, Written
from rest_client.env_file import read_env
# One pair of keys for Jira and Confluence: one Atlassian account's API token opens both.
@@ -29,11 +29,19 @@ 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 = "a plan in Jira is only read so far: file, edit and finish its issues in Jira"
READ_ONLY = "a plan in Jira is only read and filed into so far: edit and finish its issues in Jira"
# The key in PROPERTY's value that marks an issue the loop filed, and its value.
FILED_BY = ("Filed by", "loop")
# The issue type of an issue the loop files: every Jira Cloud project template has it, and a project without it refuses the issue, saying so.
ISSUE_TYPE = "Task"
# The name of the link type whose inward side reads "is blocked by", as Jira Cloud ships it.
BLOCKS = "Blocks"
SECURITY = "security"
# Sends a request with the Authorization header given, the body as JSON where there is one, and returns the JSON answer, or a Failure saying why there is none.
Http = typing.Callable[[str, str, str, object], object]
ToMarkdown = typing.Callable[[list[dict[str, typing.Any]]], list[str] | Refused | Failure]
ToAdf = typing.Callable[[str], dict[str, typing.Any] | Failure]
def http_json(method: str, url: str, authorization: str, body: object) -> object:
@@ -68,11 +76,12 @@ class Issue:
@dataclasses.dataclass(frozen=True)
class JiraPlan:
"""The plan under epic, read with the credentials env_file holds."""
"""The plan under epic, read and written with the credentials env_file holds."""
epic: Epic
env_file: pathlib.Path
http: Http = http_json
to_markdown: ToMarkdown = adfs_to_markdown
to_adf: ToAdf = markdown_to_adf
@property
def label(self) -> str:
@@ -93,7 +102,40 @@ class JiraPlan:
return next((issue for issue in issues if isinstance(issue, Failure)), None) or plan_of([issue for issue in issues if isinstance(issue, Issue)], self.epic, self.to_markdown)
def add(self, fields: dict[str, str], detail: str) -> Written | Failure:
return Failure(READ_ONLY)
"""Files the item as a child issue, which Jira ranks last in the backlog. It doesn't weigh the item against a bar or the goals file, which a plan in Jira doesn't state yet (todo.md's item 384). Jira takes the links after the issue, so a link it refuses leaves the issue filed, and the Failure says so."""
filing = filing_of(fields, detail, self.epic)
if isinstance(filing, Failure):
return filing
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
if detail.strip():
description = self.to_adf(detail)
if isinstance(description, Failure):
return Failure(f"cannot convert the item's detail to a Jira description: {description.reason}")
filing.body["fields"]["description"] = description
if filing.blockers and (missing := self.missing_blocker(filing.blockers, authorization)):
return missing
created = self.http("POST", f"{self.epic.site}/rest/api/3/issue", authorization, filing.body)
if isinstance(created, Failure):
return Failure(f"cannot file the item under {self.epic.key}: {created.reason}")
key = created.get("key") if isinstance(created, dict) else None
if not isinstance(key, str) or not ISSUE_KEY.fullmatch(key) or project_of(key) != project_of(self.epic.key):
return Failure(f"Jira answered the new issue without an issue key in {project_of(self.epic.key)}; look for it under {self.epic.key} before filing the item again")
for blocker in filing.blockers:
# Jira names the two ends by the link type's sides: the inward issue blocks the outward one, which then reads "is blocked by" it.
linked = self.http("POST", f"{self.epic.site}/rest/api/3/issueLink", authorization, {"type": {"name": BLOCKS}, "inwardIssue": {"key": blocker}, "outwardIssue": {"key": key}})
if isinstance(linked, Failure):
return Failure(f"filed {key}, but cannot link it as blocked by {blocker}: {linked.reason}; link it in Jira, and do not file the item again")
return Written(number(key))
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, since only such a blocker reads back as one."""
answered = children(self.epic, authorization, self.http)
if isinstance(answered, Failure):
return answered
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)
@@ -102,6 +144,51 @@ class JiraPlan:
return Failure(READ_ONLY)
@dataclasses.dataclass(frozen=True)
class Filing:
"""An item checked and ready to file."""
# What Jira's create-issue request takes, without the description.
body: dict[str, typing.Any]
# The key of each issue the item is blocked by.
blockers: tuple[str, ...]
def filing_of(fields: dict[str, str], detail: str, epic: Epic) -> Filing | Failure:
"""The issue that holds an item with these fields under epic, or why a field cannot be filed. It holds only what `item` reads back."""
named = cells(fields)
summary = plain(named.get("Item", "")).strip()
if not summary:
return Failure("the item has no tagline")
if unfit := unfit_text(summary, detail):
return unfit
release = named.get("Release", "")
if parsed(release) is None:
return Failure(f"the item's Release {release!r} is not a version such as 1.2.0")
# Named so the shared messages read "item to file's L".
levels = parse_scores("to file", named, SHAPE.score_columns)
if isinstance(levels, Failure):
return levels
moves, exempt = named.get(MOVES, ""), named.get("Exempt", "")
if isinstance(unfit_moves := parse_moves("to file", moves), Failure):
return unfit_moves
if not is_exempt(exempt):
return Failure(f"the item's Exempt {exempt!r} is not empty or one of {', '.join(EXEMPTIONS[1:])}")
blockers = parse_ids(named.get(BLOCKED_BY, ""))
if blockers is None:
return Failure(f"the item's {BLOCKED_BY} {named[BLOCKED_BY]!r} is not empty or IDs separated by \", \"")
project = project_of(epic.key)
issue_fields: dict[str, typing.Any] = {"project": {"key": project}, "parent": {"key": epic.key}, "issuetype": {"name": ISSUE_TYPE}, "summary": summary, "fixVersions": [{"name": release}]}
if exempt == SECURITY:
issue_fields["labels"] = [SECURITY]
value = levels | {MOVES: moves, "Exempt": exempt, FILED_BY[0]: FILED_BY[1]}
return Filing({"fields": issue_fields, "properties": [{"key": PROPERTY, "value": value}]}, tuple(f"{project}-{blocker}" for blocker in blockers))
def project_of(key: str) -> str:
"""The key of the Jira project an issue key lies in."""
return key.rpartition("-")[0]
def basic_auth(env_file: pathlib.Path) -> str | Failure:
"""The Authorization header for the email and API token that env_file holds."""
values = read_env(env_file, KEYS, "an API token")
+2 -2
View File
@@ -1,6 +1,6 @@
"""The one way a tool reads or writes a project's plan: through the store its config names.
The config's `plan` setting names the backend. A path names a markdown file, todo.md. `jira:` and an epic's address name a Jira epic, whose open child issues `jira_epic` reads and nothing writes yet. An agent reads and changes the plan with `todo-item`, which works through the same store.
The config's `plan` setting names the backend. A path names a markdown file, todo.md. `jira:` and an epic's address name a Jira epic, whose open child issues `jira_epic` reads, and where it files an item as a new one. An agent reads and changes the plan with `todo-item`, which works through the same store.
A tool that reads what a past commit held, such as `score-outcomes`, still parses that commit's todo.md itself, with `release_plan.todo_table`: only the markdown backend has commits, and todo.md's items 365, 366 and 368 port those tools to the other backends."""
import dataclasses
@@ -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` only reads until todo.md's item 352. A write that fails leaves the plan as it was."""
"""A project's plan. plan_store.contract holds every backend that writes to the same behaviour; `jira_epic` reads and files, and fails an edit or a finish until todo.md's items 382 and 383. A write that fails leaves the plan as it was."""
@property
def label(self) -> str:
+121 -4
View File
@@ -10,7 +10,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from project_config.settings import Epic
from failure import Failure
from plan_store import jira_epic
from plan_store.stores import Plan
from plan_store.stores import Plan, Written
from adf_codec.convert import Refused
from release_plan.release import release_of
@@ -209,17 +209,134 @@ class JiraPlan(unittest.TestCase):
self.pages = [{"issues": [issue("OTHER-5")]}]
self.assertNotIn("s3cret", self.store().read().reason) # type: ignore[union-attr]
def test_every_write_fails_since_the_store_only_reads(self):
def test_edit_and_finish_fail_since_the_store_only_files(self):
store = self.store()
for written in (store.add({}, ""), store.edit(34, {"L": "2"}, None), store.finish(34)):
for written in (store.edit(34, {"L": "2"}, None), store.finish(34)):
with self.subTest(written=written):
self.assertEqual(written, Failure("a plan in Jira is only read so far: file, edit and finish its issues in Jira"))
self.assertEqual(written, Failure("a plan in Jira is only read and filed into so far: edit and finish its issues 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))
ISSUES = "https://acme.atlassian.net/rest/api/3/issue"
LINKS = "https://acme.atlassian.net/rest/api/3/issueLink"
FIELDS = {"Release": "0.1.0", "Tagline": "Count the runs.", "L": "1", "E": "2", "I": "3", "S": "1", "Moves": "1 by 9"}
PROPERTY = {"L": 1, "E": 2, "I": 3, "S": 1, "Moves": "1 by 9", "Exempt": "", "Filed by": "loop"}
class Filing(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]] = []
self.open: list[dict[str, object]] = []
self.created: object = {"id": "10040", "key": "ABC-40"}
self.linked: object = None
def http(self, method: str, url: str, authorization: str, body: object) -> object:
"""Stands in for Jira: answers the epic, self.open to the search, self.created to a new issue and self.linked to a new link."""
self.calls.append((method, url, body))
assert authorization == AUTHORIZATION
return {SEARCH: {"issues": self.open}, ISSUES: self.created, LINKS: self.linked}.get(url, {"key": "ABC-12"})
def to_adf(self, markdown: str) -> dict[str, object] | Failure:
return adf(markdown)
def add(self, fields: dict[str, str] = FIELDS, detail: str = ""):
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, self.to_adf).add(fields, detail)
def sent(self, url: str) -> list[object]:
return [body for _, sent_to, body in self.calls if sent_to == url]
def test_files_the_item_as_a_task_under_the_epic_marked_as_the_loops(self):
self.assertEqual(self.add(), Written(40))
self.assertEqual(self.calls, [("POST", ISSUES, {
"fields": {"project": {"key": "ABC"}, "parent": {"key": "ABC-12"}, "issuetype": {"name": "Task"}, "summary": "Count the runs.", "fixVersions": [{"name": "0.1.0"}]},
"properties": [{"key": "plan-item", "value": PROPERTY}],
})])
def test_a_bold_tagline_is_filed_plain(self):
self.add(FIELDS | {"Tagline": "**Count the runs.**"})
self.assertEqual(self.sent(ISSUES)[0]["fields"]["summary"], "Count the runs.") # type: ignore[index]
def test_the_detail_is_the_description_as_adf(self):
self.add(detail="Why it counts.")
self.assertEqual(self.sent(ISSUES)[0]["fields"]["description"], adf("Why it counts.")) # type: ignore[index]
def test_a_security_finding_is_labelled_security(self):
self.add(FIELDS | {"Exempt": "security"})
sent, = self.sent(ISSUES)
self.assertEqual((sent["fields"]["labels"], sent["properties"][0]["value"]["Exempt"]), (["security"], "security")) # type: ignore[index]
def test_no_other_item_is_labelled(self):
self.add(FIELDS | {"Exempt": "owner"})
self.assertNotIn("labels", self.sent(ISSUES)[0]["fields"]) # type: ignore[index]
def test_links_the_issue_as_blocked_by_each_blocker_once_filed(self):
self.open = [issue("ABC-34"), issue("ABC-35")]
self.assertEqual(self.add(FIELDS | {"Blocked by": "34, 35"}), Written(40))
self.assertEqual([url for _, url, _ in self.calls][-3:], [ISSUES, LINKS, LINKS])
self.assertEqual(self.sent(LINKS), [{"type": {"name": "Blocks"}, "inwardIssue": {"key": f"ABC-{blocker}"}, "outwardIssue": {"key": "ABC-40"}} for blocker in (34, 35)])
def test_a_blocker_that_is_no_open_child_fails_before_anything_is_filed(self):
self.open = [issue("ABC-34")]
self.assertEqual(self.add(FIELDS | {"Blocked by": "34, 36"}), Failure("jira:https://acme.atlassian.net/browse/ABC-12 holds no item 36 to be blocked by"))
self.assertEqual(self.sent(ISSUES), [])
def test_a_field_out_of_format_fails_before_any_request(self):
cases = ({"L": "9"}, {"Release": "soon"}, {"Release": ""}, {"Moves": "much"}, {"Exempt": "whim"}, {"Blocked by": "ABC-34"}, {"Tagline": "Count\nthe runs."}, {"Tagline": " "})
for change in cases:
with self.subTest(change=change):
self.assertIsInstance(self.add(FIELDS | change), Failure)
self.assertEqual(self.calls, [])
def test_a_field_the_plan_does_not_have_is_a_programming_error(self):
with self.assertRaises(ValueError):
self.add(FIELDS | {"Colour": "red"})
def test_an_item_without_a_release_fails_naming_the_field(self):
self.assertEqual(self.add({name: value for name, value in FIELDS.items() if name != "Release"}), Failure("the item's Release '' is not a version such as 1.2.0"))
def test_a_detail_that_does_not_convert_fails_before_any_request(self):
self.to_adf = lambda markdown: Failure("docker is not running") # type: ignore[method-assign]
self.assertEqual(self.add(detail="Why."), Failure("cannot convert the item's detail to a Jira description: docker is not running"))
self.assertEqual(self.calls, [])
def test_an_item_jira_refuses_fails_with_jiras_reason(self):
self.created = Failure("POST /rest/api/3/issue answered 400: Version name '0.1.0' is not valid")
self.assertEqual(self.add(), Failure("cannot file the item under ABC-12: POST /rest/api/3/issue answered 400: Version name '0.1.0' is not valid"))
def test_an_answer_that_names_no_issue_of_the_epics_project_fails(self):
for answer in ({}, {"key": 7}, {"key": "OTHER-5"}, ["ABC-40"]):
with self.subTest(answer=answer):
self.created = answer
self.assertEqual(self.add(), Failure("Jira answered the new issue without an issue key in ABC; look for it under ABC-12 before filing the item again"))
def test_a_link_jira_refuses_fails_naming_the_issue_it_filed(self):
self.open, self.linked = [issue("ABC-34")], Failure("POST /rest/api/3/issueLink answered 404: No issue link type with name 'Blocks' found.")
self.assertEqual(self.add(FIELDS | {"Blocked by": "34"}), Failure("filed ABC-40, but cannot link it as blocked by ABC-34: POST /rest/api/3/issueLink answered 404: No issue link type with name 'Blocks' found.; link it in Jira, and do not file the item again"))
def test_what_it_files_reads_back_as_the_item(self):
self.add(FIELDS | {"Exempt": "owner"}, "Why it counts.")
sent, = self.sent(ISSUES)
raw = {"key": "ABC-40", "fields": sent["fields"] | {"issuelinks": []}, "properties": {entry["key"]: entry["value"] for entry in sent["properties"]}} # type: ignore[index]
filed = jira_epic.issue_of(raw)
assert isinstance(filed, jira_epic.Issue), filed
plan = jira_epic.plan_of([filed], EPIC, lambda documents: [text_of(document) for document in documents])
assert isinstance(plan, Plan), plan
item, = plan.items
self.assertEqual((item.id, item.release, item.exempt, item.tagline, item.moves, item.detail), (40, release_of("0.1.0"), "owner", "**Count the runs.**", (("1", 9),), "Why it counts."))
self.assertEqual({name: item.scores[name] for name in "LEIS"}, {"L": 1, "E": 2, "I": 3, "S": 1})
def test_a_missing_env_file_fails_before_any_request(self):
self.env.unlink()
self.assertIsInstance(self.add(), Failure)
self.assertEqual(self.calls, [])
class Requests(unittest.TestCase):
def test_sends_each_request_through_the_shared_client_with_jiras_error_messages(self):
with unittest.mock.patch.object(jira_epic.json_request, "http_json", return_value={"issues": []}) as sent:
+6 -2
View File
@@ -10,8 +10,8 @@ usage: todo-item list [--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. A plan in a Jira epic is
only read so far: list and show work, and add, edit, move and finish fail. Each command that changes
`project-config plan` prints: a markdown file, todo.md, or a Jira epic. In a Jira epic, list,
show and add work, and edit, move and finish fail so far. 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.
@@ -28,6 +28,10 @@ list and show read only the plan, and print no Score: an item's place in list's
add files the item under the next free ID, with the tagline in bold, and the detail it reads from
stdin, if any. The detail may hold no ## or ### heading.
It prints `Filed item <ID> in <plan>.` It doesn't write anything where ranking fails or scores the item under the bar.
In a Jira epic, add files a Task under the epic, last in the backlog, and <ID> is the new issue's
number. The release must be one of the Jira project's Fix Versions, and --exempt security also
labels the issue `security`. No bar applies there yet. Where Jira files the issue and then refuses
a --blocked-by link, add fails, naming the issue: link it in Jira, and don't file it again.
edit sets the cells whose flag is given and leaves the rest; an empty value, as in --blocked-by "",
empties the cell. --detail replaces the detail with the text on stdin, and --clear-detail removes it.
+2 -1
View File
@@ -302,7 +302,8 @@ Messages keep each file's usual name, such as `todo.md`, as its label, since the
- **An item's ID stays a whole number: the issue's number in the epic's Jira project.** About 30 modules read an ID as an int, and the `branch` and title templates already spell a ticket's name, as `ABC-{id}`. So the store refuses a child issue from another Jira project, and counts a blocker only among the plan's own items (`bin/plan_store/jira_epic.py`).
- **The scores sit in one issue property, `plan-item`**, which needs no Jira admin (lilleman, 2026-11-12). An issue without it reads as an item nobody scored.
- **The release is the earliest Fix Version named as a semver version**, and an issue with none fails the read, naming it, until todo.md's item 359 ties releases to something else.
- **The store only reads**, until todo.md's item 352 writes. `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 loop files an item as a Task under the epic, and marks it as its own** (item 352, on 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 the one issue type every Jira Cloud project template has; a project without it refuses the issue, saying so. 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, and a link Jira still refuses leaves the issue filed, which the failure says.
- **The store reads and files, and doesn't edit or finish an issue** until todo.md's items 382 and 383. `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
+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, and `todo-item` can't write one 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 one there, and nothing edits, moves or finishes one 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.
- **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.