Answer stability round 1: 2 🔴, 2 🟡 (0 misread); count an item as filed once Jira holds it, try every link, say when a failed create may have filed, and drop README's stale sentence

This commit is contained in:
2026-11-15 03:35:48 +01:00
parent af8e7ad3d1
commit 35f1f5e70f
9 changed files with 86 additions and 42 deletions
+1 -1
View File
@@ -2,7 +2,7 @@
## 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, 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.
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. 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.
+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 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 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 edit`, `move` and `finish` fail, so edit and finish its issues in Jira. `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.
+42 -21
View File
@@ -1,8 +1,8 @@
"""A plan kept as the child issues of one Jira Cloud epic, read over Jira's REST API.
"""A plan kept as the child issues of one Jira Cloud epic, read and filed into 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.
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."""
`add` files an item as a new child issue, marked with FILED_BY. edit and finish are a Failure until todo.md's items 382 and 383."""
import base64
import dataclasses
import pathlib
@@ -30,13 +30,15 @@ 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 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.
# 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.
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.
# 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"
# The name of the link type whose inward side reads "is blocked by", as Jira Cloud ships it.
BLOCKS = "Blocks"
SECURITY = "security"
# What a failed create ends with: a request Jira never answered, or answered brokenly, may still have filed the issue.
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under {epic} before filing the item again"
# 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]
@@ -102,35 +104,51 @@ 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:
"""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."""
"""Files the item as a child issue, which Jira ranks last in the backlog. No bar applies and the goals file isn't read, since a plan in Jira has no place for a formula or a bar yet (todo.md's item 384).
Jira takes the links after the issue. A link it refuses leaves the issue filed, so the write counts as landed, and a note names each link to make by hand."""
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
issue_fields = filing.fields
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
issue_fields = issue_fields | {"description": description}
version = self.fix_version(filing.release, authorization)
if isinstance(version, Failure):
return version
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)
created = self.http("POST", f"{self.epic.site}/rest/api/3/issue", authorization, {"fields": issue_fields | {"fixVersions": [{"name": version}]}, "properties": [{"key": PROPERTY, "value": filing.scores}]})
if isinstance(created, Failure):
return Failure(f"cannot file the item under {self.epic.key}: {created.reason}")
return Failure(f"cannot file the item under {self.epic.key}: {created.reason}; {PERHAPS_FILED.format(epic=self.epic.key)}")
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")
return Failure(f"Jira answered the new issue without an issue key in {project_of(self.epic.key)}; {PERHAPS_FILED.format(epic=self.epic.key)}")
notes = []
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))
notes.append(f"filed {key}, but cannot link it as blocked by {blocker}: {linked.reason}; link it in Jira")
return Written(number(key), tuple(notes))
def fix_version(self, release: str, authorization: str) -> str | Failure:
"""The name of the Jira project's Fix Version for release, which a project may spell with a leading v, as `earliest_release` reads it."""
project = project_of(self.epic.key)
versions = self.http("GET", f"{self.epic.site}/rest/api/3/project/{project}/versions", authorization, None)
if isinstance(versions, Failure):
return Failure(f"cannot read {project}'s Fix Versions: {versions.reason}")
names = {version.get("name") for version in versions if isinstance(version, dict)} 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")
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."""
"""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."""
answered = children(self.epic, authorization, self.http)
if isinstance(answered, Failure):
return answered
@@ -147,14 +165,17 @@ class JiraPlan:
@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 new issue's fields, without its description and its Fix Version.
fields: dict[str, typing.Any]
release: str
# PROPERTY's value.
scores: 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."""
"""The issue to file for an item with these fields under epic, or why a field cannot be filed."""
named = cells(fields)
summary = plain(named.get("Item", "")).strip()
if not summary:
@@ -164,7 +185,7 @@ def filing_of(fields: dict[str, str], detail: str, epic: Epic) -> Filing | Failu
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".
# Named so the shared messages read "item to file's L": they open with "item" and an ID, which this item has none of yet.
levels = parse_scores("to file", named, SHAPE.score_columns)
if isinstance(levels, Failure):
return levels
@@ -177,11 +198,11 @@ def filing_of(fields: dict[str, str], detail: str, epic: Epic) -> Filing | Failu
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}]}
issue_fields: dict[str, typing.Any] = {"project": {"key": project}, "parent": {"key": epic.key}, "issuetype": {"name": ISSUE_TYPE}, "summary": summary}
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))
return Filing(issue_fields, release, value, tuple(f"{project}-{blocker}" for blocker in blockers))
def project_of(key: str) -> str:
@@ -241,8 +262,8 @@ def issue_of(raw: object) -> Issue | Failure:
def plan_of(issues: list[Issue], epic: Epic, to_markdown: ToMarkdown) -> Plan | Failure:
"""The plan the issues hold, in their order."""
project = epic.key.rpartition("-")[0]
if strangers := [issue.key for issue in issues if issue.key.rpartition("-")[0] != project]:
project = project_of(epic.key)
if strangers := [issue.key for issue in issues if project_of(issue.key) != project]:
return Failure(f"{strangers[0]} is a child of {epic.key} in another Jira project, and an item's ID is its number in {project}; move it into {project} or out of the epic")
ids = {issue.number for issue in issues}
items = [item(issue, project, ids) for issue in issues]
@@ -279,7 +300,7 @@ def item(issue: Issue, project: str, ids: set[int]) -> Item | Failure:
scored = scores(issue.key, issue.scores)
if isinstance(scored, Failure):
return scored
blockers = {number(key) for key in issue.blockers if key.rpartition("-")[0] == project}
blockers = {number(key) for key in issue.blockers if project_of(key) == project}
return Item(issue.number, release, scored[2], bold_cell(issue.summary), scored[0], scored[1], tuple(sorted(blockers & ids)), "")
+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 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.
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 are the plan: `jira_epic` reads them, and files an item as a new child issue. 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` 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."""
"""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, except where its Failure says a tracker may hold the item all the same, as when Jira's answer to a new issue is lost."""
@property
def label(self) -> str:
+30 -9
View File
@@ -223,6 +223,8 @@ class JiraPlan(unittest.TestCase):
ISSUES = "https://acme.atlassian.net/rest/api/3/issue"
LINKS = "https://acme.atlassian.net/rest/api/3/issueLink"
VERSIONS = "https://acme.atlassian.net/rest/api/3/project/ABC/versions"
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under ABC-12 before filing the item again"
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"}
@@ -236,12 +238,13 @@ class Filing(unittest.TestCase):
self.open: list[dict[str, object]] = []
self.created: object = {"id": "10040", "key": "ABC-40"}
self.linked: object = None
self.versions: object = [{"name": "0.1.0"}, {"name": "v0.2.0"}, "odd"]
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."""
"""Stands in for Jira: answers the epic, self.versions for the project's Fix Versions, self.open to the search, self.created to a new issue and self.linked to a new link."""
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"})
return {SEARCH: {"issues": self.open}, ISSUES: self.created, LINKS: self.linked, VERSIONS: self.versions}.get(url, {"key": "ABC-12"})
def to_adf(self, markdown: str) -> dict[str, object] | Failure:
return adf(markdown)
@@ -254,7 +257,7 @@ class Filing(unittest.TestCase):
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, {
self.assertEqual(self.calls, [("GET", VERSIONS, None), ("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}],
})])
@@ -324,22 +327,40 @@ class Filing(unittest.TestCase):
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"))
self.assertEqual(self.add(), Failure(f"cannot file the item under ABC-12: POST /rest/api/3/issue answered 400: Version name '0.1.0' is not valid; {PERHAPS_FILED}"))
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"))
self.assertEqual(self.add(), Failure(f"Jira answered the new issue without an issue key in ABC; {PERHAPS_FILED}"))
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_a_link_jira_refuses_leaves_the_item_filed_with_a_note_and_the_other_links_made(self):
refusal = "POST /rest/api/3/issueLink answered 404: No issue link type with name 'Blocks' found."
self.open, self.linked = [issue("ABC-34"), issue("ABC-35")], Failure(refusal)
self.assertEqual(self.add(FIELDS | {"Blocked by": "34, 35"}), Written(40, tuple(f"filed ABC-40, but cannot link it as blocked by ABC-{blocker}: {refusal}; link it in Jira" for blocker in (34, 35))))
self.assertEqual(len(self.sent(LINKS)), 2)
def test_files_under_the_fix_version_as_the_project_spells_it(self):
self.assertEqual(self.add(FIELDS | {"Release": "0.2.0"}), Written(40))
self.assertEqual(self.sent(ISSUES)[0]["fields"]["fixVersions"], [{"name": "v0.2.0"}]) # type: ignore[index]
def test_a_release_the_project_has_no_fix_version_for_fails_before_anything_is_filed(self):
for versions in ([{"name": "0.1.0"}], {"name": "0.3.0"}, []):
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.sent(ISSUES), [])
def test_fix_versions_that_cannot_be_read_fail_before_anything_is_filed(self):
self.versions = Failure("GET /rest/api/3/project/ABC/versions answered 403: Forbidden")
self.assertEqual(self.add(), Failure("cannot read ABC's Fix Versions: GET /rest/api/3/project/ABC/versions answered 403: Forbidden"))
self.assertEqual(self.sent(ISSUES), [])
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]
raw = {"key": "ABC-40", "fields": sent["fields"] | {"issuelinks": []}, "properties": {entry["key"]: entry["value"] for entry in sent["properties"]}} # type: ignore[index, operator, union-attr]
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])
+6 -4
View File
@@ -29,9 +29,10 @@ add files the item under the next free ID, with the tagline in bold, and the det
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.
number. The release must be one of the Jira project's Fix Versions, named as 1.2.0 or v1.2.0 there,
and --exempt security also labels the issue `security`. No bar applies there yet. Where Jira files
the issue and then refuses a --blocked-by link, add still prints `Filed item <ID> …`, and says on
stderr which link to make in Jira.
edit sets the cells whose flag is given and leaves the rest; an empty value, as in --blocked-by "",
empties the cell. --detail replaces the detail with the text on stdin, and --clear-detail removes it.
@@ -49,7 +50,8 @@ mistake. It prints `Finished item <ID> in <plan>.` It doesn't write anything whi
finish <ID> --no-changelog also drops an item no chunk built.
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.
`not edited:`, `not moved:` or `not finished:` means it didn't write anything. The one exception is an add to a
Jira epic that Jira didn't answer or answered brokenly: the message then says the issue may exist.
"""
import argparse
import pathlib
+1 -1
View File
@@ -302,7 +302,7 @@ 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 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 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 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 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; `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.
- **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` can't edit, move or finish 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.
- **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.
+2 -2
View File
@@ -85,7 +85,7 @@
lilleman's calls, 2026-11-12. Without asking, the loop may create child issues in the epic, edit the summary, description and scores of issues it created, and comment on and transition any issue in the epic. It never edits the summary or description of an issue a person filed. A security finding is filed in the epic like any item, labelled `security`, never with a secret's value. R is above 5, so this item ships alone.
Split from the first item 352 on 2026-11-15, which also held what the items it now blocks take: editing and scoring, finishing, and ranking. The filed issue holds the scores in the `plan-item` issue property, with a mark that the loop filed it, which the edit item reads. Jira puts a new issue last in the backlog until the ranking item ships.
On 2026-11-15 this item was split in four. Item 382 took editing and scoring, item 383 finishing, and item 384 ranking. The filed issue holds the scores in the `plan-item` issue property, with a mark that the loop filed it, which item 382 reads. Jira puts a new issue last in the backlog until item 384 ships.
Touches:
- `bin/plan_store/jira_epic.py`: the module docstring, `JiraPlan.add`, and new functions that check the fields and build the issue
@@ -112,7 +112,7 @@ lilleman's call, 2026-11-12: the folder replaces the default, as item 347's prin
### 383. Move a finished item of a Jira plan by the transition, and to the status, that the project's config names.
Split from item 352 on 2026-11-15; lilleman's call, 2026-11-12: a finished item moves by the transition and to the status the config names, since each Jira workflow differs. The loop may transition any issue in the epic. A bench of readers, seated as the person who writes a client's `config.toml`, picks the setting's spelling. `PlanStore`'s docstring then stops saying `jira_epic` only reads, once this item and the edit item have shipped.
Split from item 352 on 2026-11-15; lilleman's call, 2026-11-12: a finished item moves by the transition and to the status the config names, since each Jira workflow differs. The loop may transition any issue in the epic. A bench of readers, seated as the person who writes a client's `config.toml`, picks the setting's spelling. Once this item and item 382 have shipped, `PlanStore`'s docstring stops saying that `jira_epic` fails an edit or a finish.
Touches:
- `bin/plan_store/jira_epic.py`: `JiraPlan.finish`