Answer stability round 1: 1 🔴, 2 🟡 (0 misread); say in CLAUDE.md, the todo rule and the changelog that todo-item finishes an item in Jira, say that a move Jira didn't answer may have landed, and test a transition without a status category
This commit is contained in:
+1
-1
@@ -4,7 +4,7 @@
|
||||
|
||||
- Reviewers and loop-claude's judge read the review standards from the folder a project's config sets as `standards`, in place of `~/.claude/skills/larv-review/standards/`. The setting is required. To upgrade, add `standards = "~/.claude/skills/larv-review/standards"` to every config under `~/.claude-projects/` right after `deploy-release` moves `~/.claude` to this release, and not before.
|
||||
- A project's config may keep each of its five records on a Confluence Cloud page: set, for example, `decisions = "confluence:https://<site>/wiki/spaces/<space>/pages/<page ID>"`, with the credentials in the config's `env-file`. `decisions` and `comprehension-history` may name a page only where `plan` names a Jira epic. The loop reads and writes the page as markdown, so a save replaces a mention or a macro on it with plain text. It never overwrites a teammate's edit: where someone saved the page since the loop read it, `project-record save` refuses and the loop asks you.
|
||||
- `todo-item add` files an item into a plan kept in a Jira epic: a Task under the epic, under the project's Fix Version for the release, labelled `security` for a security finding and linked to each item that blocks it. Editing and finishing an issue still happen in Jira.
|
||||
- `todo-item add` files an item into a plan kept in a Jira epic: a Task under the epic, under the project's Fix Version for the release, labelled `security` for a security finding and linked to each item that blocks it. Editing an issue still happens in Jira.
|
||||
- An item of the next release may predict the files and parts it will touch, under a `Touches:` line in its detail. `chunk-preflight` then names the items that may start chunks at once, and the new `touch-predictions record` keeps each prediction beside what the merged chunk touched, in the record a project's config places with `touch-predictions`.
|
||||
- CLAUDE.md and the todo-items rule define the plan as a todo.md or a Jira epic, and say plan where todo.md was false for a Jira plan.
|
||||
- Reviewers without a shell read the plan from a listing that larv-review writes into the review folder, whichever store holds it.
|
||||
|
||||
@@ -6,7 +6,7 @@ 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 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.
|
||||
- **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.
|
||||
- **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,4 +1,4 @@
|
||||
"""A plan kept as the child issues of one Jira Cloud epic, read and filed into over Jira's REST API.
|
||||
"""A plan kept as the child issues of one Jira Cloud epic, read, filed into 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.
|
||||
|
||||
@@ -29,7 +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 = "a plan in Jira is read, filed into and finished so far: edit its issues in Jira"
|
||||
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.
|
||||
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.
|
||||
@@ -40,6 +40,8 @@ SECURITY = "security"
|
||||
# The key of the status category Jira Cloud gives every done status.
|
||||
DONE = "done"
|
||||
# What a failed create ends with: a request Jira never answered, or answered brokenly, may still have filed the issue.
|
||||
# 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"
|
||||
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, None where the answer has no body, or a Failure saying why there is none.
|
||||
@@ -163,7 +165,7 @@ class JiraPlan:
|
||||
return Failure(READ_ONLY)
|
||||
|
||||
def finish(self, id_: int) -> Written | Failure:
|
||||
"""Moves item id_'s issue by the transition, and to the status, that the config names, since each Jira workflow differs. Any open child of the epic may move, whoever filed it."""
|
||||
"""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."""
|
||||
if self.finish_by is None:
|
||||
return Failure(f"the config names no transition to finish an item by: set `{JIRA_FINISH_TRANSITION}` and `{JIRA_FINISH_STATUS}`, as `project-config --help` shows")
|
||||
authorization = basic_auth(self.env_file)
|
||||
@@ -183,7 +185,7 @@ class JiraPlan:
|
||||
if isinstance(transition, Failure):
|
||||
return transition
|
||||
moved = self.http("POST", url, authorization, {"transition": {"id": transition}})
|
||||
return Failure(f"cannot move {key} by {self.finish_by.transition!r}: {moved.reason}") if isinstance(moved, Failure) else Written(id_)
|
||||
return Failure(f"cannot move {key} by {self.finish_by.transition!r}: {moved.reason}; {PERHAPS_MOVED.format(key=key)}") if isinstance(moved, Failure) else Written(id_)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -240,7 +242,7 @@ def offer_of(raw: object) -> tuple[str, str, str, str] | None:
|
||||
|
||||
|
||||
def transition_of(offered: object, key: str, finish: Finish) -> str | Failure:
|
||||
"""The ID of the transition finish names, among those Jira offers for the issue key in its present status; or why none of them finishes the item."""
|
||||
"""The ID of the transition finish names, among those Jira offered for the issue named key, which are the ones its present status has; or why none of them finishes the item."""
|
||||
raw = offered.get("transitions") if isinstance(offered, dict) else None
|
||||
found = [offer for each in raw if (offer := offer_of(each))] if isinstance(raw, list) else []
|
||||
if not isinstance(raw, list) or len(found) != len(raw):
|
||||
@@ -248,7 +250,7 @@ def transition_of(offered: object, key: str, finish: Finish) -> str | Failure:
|
||||
named = [each for each in found if each[1] == finish.transition]
|
||||
if not named:
|
||||
others = " and ".join(f"{name!r} to {status!r}" for _, name, status, _ in found)
|
||||
return Failure(f"{key} has no transition {finish.transition!r} from its status, " + (f"only {others}: set `{JIRA_FINISH_TRANSITION}` to one of them" if found else "nor any other the account may make"))
|
||||
return Failure(f"{key} has no transition {finish.transition!r} from its status, " + (f"only {others}: move the issue in Jira to a status that has it, or name in `{JIRA_FINISH_TRANSITION}` one that leads to a done status" if found else "nor any other the account may make"))
|
||||
id_, _, status, category = next((each for each in named if each[2] == finish.status), named[0])
|
||||
if status != finish.status:
|
||||
return Failure(f"{key}'s transition {finish.transition!r} leads to the status {status!r}, not to {finish.status!r}, which `{JIRA_FINISH_STATUS}` names")
|
||||
|
||||
@@ -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 a tracker may hold the item all the same, as when Jira's answer to a new issue is lost."""
|
||||
"""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."""
|
||||
|
||||
@property
|
||||
def label(self) -> str:
|
||||
|
||||
@@ -211,7 +211,7 @@ class JiraPlan(unittest.TestCase):
|
||||
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("a plan in Jira is read, filed into and finished so far: edit its issues in Jira"))
|
||||
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):
|
||||
@@ -416,14 +416,14 @@ class Finishing(unittest.TestCase):
|
||||
self.assertEqual(self.posts(), [])
|
||||
|
||||
def test_a_transition_the_issue_does_not_have_fails_naming_those_it_has(self):
|
||||
self.assertEqual(self.finish(by=Finish("Close", "Done")), Failure("ABC-34 has no transition 'Close' from its status, only 'Start' to 'In Progress' and 'Mark as done' to 'Done': set `jira-finish-transition` to one of them"))
|
||||
self.assertEqual(self.finish(by=Finish("Close", "Done")), Failure("ABC-34 has no transition 'Close' from its status, only 'Start' to 'In Progress' and 'Mark as done' to 'Done': move the issue in Jira to a status that has it, or name in `jira-finish-transition` one that leads to a done status"))
|
||||
self.assertEqual(self.posts(), [])
|
||||
|
||||
def test_a_transition_that_leads_to_another_status_fails(self):
|
||||
self.assertEqual(self.finish(by=Finish("Mark as done", "Closed")), Failure("ABC-34's transition 'Mark as done' leads to the status 'Done', not to 'Closed', which `jira-finish-status` names"))
|
||||
self.assertEqual(self.posts(), [])
|
||||
|
||||
def test_picks_among_transitions_of_one_name_the_one_to_the_status(self):
|
||||
def test_two_transitions_share_the_name_and_the_one_to_the_status_is_made(self):
|
||||
self.transitions = {"transitions": [transition("30", "Close", "Rejected"), transition("31", "Close", "Done")]}
|
||||
self.assertEqual(self.finish(by=Finish("Close", "Done")), Written(34))
|
||||
self.assertEqual(self.posts(), [("POST", TRANSITIONS, {"transition": {"id": "31"}})])
|
||||
@@ -441,7 +441,7 @@ class Finishing(unittest.TestCase):
|
||||
self.assertEqual(self.finish(), Failure("cannot read ABC-34's transitions: HTTP 403"))
|
||||
|
||||
def test_transitions_in_another_shape_fail(self):
|
||||
odd = [transition(31, "Mark as done", "Done"), transition("31", None, "Done"), transition("31", "Mark as done", ["Done"]), transition("31", "Mark as done", "Done", 4), {"id": "31", "name": "Mark as done", "to": "Done"}, "odd"] # type: ignore[arg-type]
|
||||
odd = [transition(31, "Mark as done", "Done"), transition("31", None, "Done"), transition("31", "Mark as done", ["Done"]), transition("31", "Mark as done", "Done", 4), {"id": "31", "name": "Mark as done", "to": "Done"}, {"id": "31", "name": "Mark as done", "to": {"name": "Done"}}, "odd"] # type: ignore[arg-type]
|
||||
for answered in ([], {"transitions": "none"}, *({"transitions": [each]} for each in odd)):
|
||||
with self.subTest(answered=answered):
|
||||
self.transitions = answered
|
||||
@@ -449,7 +449,7 @@ class Finishing(unittest.TestCase):
|
||||
|
||||
def test_a_move_jira_refuses_fails_with_jiras_reason(self):
|
||||
self.moved = Failure("HTTP 400: Resolution is required")
|
||||
self.assertEqual(self.finish(), Failure("cannot move ABC-34 by 'Mark as done': HTTP 400: Resolution is required"))
|
||||
self.assertEqual(self.finish(), Failure("cannot move ABC-34 by 'Mark as done': HTTP 400: Resolution is required; unless Jira refused the request, the issue may have moved: look at ABC-34 before finishing the item again"))
|
||||
|
||||
def test_a_missing_env_file_fails_before_any_request(self):
|
||||
self.env.unlink()
|
||||
|
||||
@@ -48,15 +48,17 @@ file, where missing. It refuses where that section holds ### subsections: add th
|
||||
Where CHANGELOG.md holds text, finish needs --changelog or --no-changelog, so no bullet is left out by
|
||||
mistake. It prints `Finished item <ID> in <plan>.` It doesn't write anything while docs/decisions.md cites the item.
|
||||
finish <ID> --no-changelog also drops an item no chunk built.
|
||||
In a Jira epic, finish moves the item's issue instead, by the transition and to the status that the
|
||||
config's `jira-finish-transition` and `jira-finish-status` name, as `project-config --help` shows.
|
||||
In a Jira epic, finish doesn't remove anything: it moves the item's issue by the transition, and to
|
||||
the status, that the config's `jira-finish-transition` and `jira-finish-status` name, as
|
||||
`project-config --help` shows. The --changelog rules hold there too, and docs/decisions.md isn't checked.
|
||||
It fails, moving no issue, where the config sets neither, where the issue has no such transition
|
||||
from its present status, or where the transition leads to another status or to one Jira doesn't
|
||||
count as done. Drop an issue no chunk built in Jira, since this move would mark it done.
|
||||
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 a
|
||||
Jira epic that Jira didn't answer or answered brokenly: the message then says the issue may exist.
|
||||
`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.
|
||||
"""
|
||||
import argparse
|
||||
import pathlib
|
||||
|
||||
+1
-1
@@ -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` 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.
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
Reference in New Issue
Block a user