Write no changelog bullet for a plan kept in Jira: todo-item finish there needs no changelog flag and refuses --changelog
CI / tests (pull_request) Successful in 3m17s

This commit is contained in:
2026-11-16 23:40:13 +01:00
parent 4b5086153a
commit 3afbb55451
6 changed files with 50 additions and 9 deletions
+1 -1
View File
@@ -18,7 +18,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in the goals file, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the goals file, and record as a choice only what the goal leaves open.
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the goals file's `## Audience`, picks it.
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file in the principles folder the project's config sets (`~/.claude/bin/project-config principles` prints it) only when the item changes it, a finding or a record you write names it, or you decline a finding.
- **Remove a finished item from the plan, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item. A chunk finishes its items as it merges, through `chunk-pr merge --finish <ID>`, which takes the same flags (`larv-review` §5).
- **Remove a finished item from the plan, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. A plan kept in Jira takes no bullet: the issues' history is its changelog, and `todo-item finish` there refuses `--changelog`. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item. A chunk finishes its items as it merges, through `chunk-pr merge --finish <ID>`, which takes the same flags (`larv-review` §5).
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
- **Open each plan item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
- **File a security finding the moment it is found.** A security finding — a leaked credential, secret or PII, an auth bypass, an injection — goes under the next release, marked `security`, naming the exposure and the path it reaches. `~/.claude/bin/rank_todo.py` ranks it first in its release, after only the open questions, which wait for me. Never among additive or nice-to-have items, never only in a chunk's summary, and never as a question about where it belongs: file it, say you did, and I will unmark it if I disagree. Fixing it inside an unrelated change is a separate call — say whether it is in the blast radius.
+1 -1
View File
@@ -190,7 +190,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `settings_filter.py` is git's clean filter for `settings.json`: it drops `"model"` and sorts the keys. `.gitattributes` sets the filter `settings` on `settings.json`, and Install's `git config` line makes this script that filter.
- `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it.
- `subagent-rung [--plan] <model> <L>` prints the Agent tool's model and effort for a subagent's task, picked by its L from the project's model on the project's routing ladder, and with `--plan` never below the project's rung; `subagent-rung --help` states the rule.
- `todo-item` reads and changes a project's plan, whatever holds it: `list` prints the items in the plan's order and `show <ID>` one item's row and detail; `add …` files an item under the next free ID, `edit <ID> …` sets an item's cells or detail, and `move <ID> --release <version>` sets an item's release; `finish <ID>` removes a finished item and adds the bullet passed with `--changelog` to `CHANGELOG.md`. Each change ranks a markdown plan. `todo-item --help` states the flags.
- `todo-item` reads and changes a project's plan, whatever holds it: `list` prints the items in the plan's order and `show <ID>` one item's row and detail; `add …` files an item under the next free ID, `edit <ID> …` sets an item's cells or detail, and `move <ID> --release <version>` sets an item's release; `finish <ID>` removes a finished item and adds the bullet passed with `--changelog` to `CHANGELOG.md`, except for a plan kept in Jira, whose issues' history is its changelog. Each change ranks a markdown plan. `todo-item --help` states the flags.
- `touch-predictions record <ID>...` appends what a chunk's items were predicted to touch, under `Touches:` in their details, beside the files and parts its branch touched, to the record the config names as `touch-predictions`; `touch-predictions --help` shows the spelling and how a part is named. `chunk-preflight` reads the same predictions to name the items that may start chunks at once.
- `wait-for <file> [<pattern>] [--timeout <seconds>]` waits until a file a background job writes holds a line matching the pattern, and prints it.
+2 -2
View File
@@ -29,8 +29,8 @@ merge merges the pull request in its turn: the chunks of one project on this
turns, one at a time. Run it in the background. In its turn it:
1. fetches origin and merges its default branch into the branch, as sync does;
2. finishes each plan item a --finish names with `todo-item finish`, passing on
--changelog or --no-changelog, and commits what that changed in the plan and the
changelog, so both change only at merge time, on top of every chunk merged before;
--changelog or --no-changelog (a Jira plan takes no --changelog, as todo-item says),
and commits what that changed in the plan and the changelog, so both change only at merge time, on top of every chunk merged before;
3. pushes, also where step 2 failed after step 1 brought changes in;
4. waits for the pull request's checks, and those origin's default branch requires, to
pass on the head; where no check reports within a minute, it takes the pull request
+9 -3
View File
@@ -63,7 +63,7 @@ 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.
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.
`project-config --help` shows. It needs neither --changelog nor --no-changelog (it accepts --no-changelog), never reads the changelog, and refuses --changelog, since the issues' history is the changelog. 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. An issue that no chunk built is dropped in Jira, not with finish, which would mark it done.
@@ -116,7 +116,8 @@ def main(argv: list[str], folder: pathlib.Path = pathlib.Path(), stdin: typing.T
case "move":
done = reported(plan.edit(args.id, {"Release": args.release}, None), "not moved", lambda written: f"Moved item {written.id} to release {args.release} in {plan.label}.")
case _:
done = finish(args, plan, store(config, "changelog"))
# A Jira plan keeps no changelog: the issues' history in Jira says what shipped.
done = finish(args, plan, None if config.epic else store(config, "changelog"))
if isinstance(done, Failure):
print(done.reason, file=sys.stderr)
return 1
@@ -217,7 +218,12 @@ def edit(args: argparse.Namespace, plan: PlanStore, text: str) -> str | Failure:
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:
def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore | None) -> str | Failure:
"""Finish item args.id in plan. changelog is where its bullet goes, or None where the plan keeps no changelog."""
if changelog is None:
if args.changelog is not None:
return Failure("not finished: this plan keeps no changelog, since the issues' history is the changelog; drop --changelog")
return reported(plan.finish(args.id), "not finished", lambda written: f"Finished item {written.id} in {plan.label}.")
held = changelog.held()
if isinstance(held, Failure):
return Failure(f"not finished: {held.reason}")
+36 -1
View File
@@ -4,10 +4,11 @@ import pathlib
import sys
import tempfile
import unittest
import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from project_config.test_project_config import configured
from project_config.test_project_config import configured, JIRA_PLAN, JIRA_SCORING
from plan.test_ranking import DECISIONS, README, TODO
from project_config.settings import DEFAULT_FLOOR
from todo_item import edits, main
@@ -266,6 +267,40 @@ class Finish(TodoItem):
self.assertEqual(self.todo.read_text(), before)
class FinishInJira(TodoItem):
"""A plan kept as a Jira epic keeps no changelog: the issues' history in Jira says what shipped."""
def setUp(self):
super().setUp()
self.config.write_text(self.config.read_text().replace('"checkout:todo.md"', f'"{JIRA_PLAN}"') + 'env-file = "~/acme.env"\n' + JIRA_SCORING)
self.plan = MemoryPlan({3: {"Release": "0.1.0", "Item": "**Count the runs.**", "L": "1", "E": "2", "I": "3", "S": "1"}})
patched = unittest.mock.patch.object(main, "plan_store", return_value=self.plan)
patched.start()
self.addCleanup(patched.stop)
def test_finishes_without_either_flag_and_leaves_a_changelog_that_exists_alone(self):
self.changelog.write_text(CHANGELOG)
self.assertEqual(self.run_main("finish", "3"), (0, "Finished item 3 in the plan in memory.\n", ""))
self.assertEqual((self.plan.rows, self.changelog.read_text()), ({}, CHANGELOG))
def test_finishes_with_no_changelog_so_chunk_pr_merge_keeps_working(self):
self.changelog.write_text(CHANGELOG)
self.assertEqual(self.run_main("finish", "3", "--no-changelog"), (0, "Finished item 3 in the plan in memory.\n", ""))
self.assertEqual(self.changelog.read_text(), CHANGELOG)
def test_refuses_a_bullet_writing_nothing_and_says_the_issues_history_is_the_changelog(self):
self.changelog.write_text(CHANGELOG)
code, out, err = self.run_main("finish", "3", "--changelog", "Runs are fast.")
self.assertEqual((code, out), (1, ""))
self.assertTrue(err.startswith("not finished: "), err)
self.assertIn("the issues' history is the changelog", err)
self.assertEqual((list(self.plan.rows), self.changelog.read_text()), ([3], CHANGELOG))
def test_doesnt_read_the_changelog(self):
self.changelog.write_bytes(b"# Changelog\n\n\xff\n")
self.assertEqual(self.run_main("finish", "3")[::2], (0, ""))
class Show(TodoItem):
def test_prints_the_header_the_row_and_the_detail(self):
row = "| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 2 | 1 | 2 | 3 | 7 | 2.1 by 8, 1 by 6 |"
+1 -1
View File
@@ -202,7 +202,7 @@ Launch prose-reviewer with what the diff touched and every section this review c
1. Read the finished PR against the goals file's goals and code health, unless that file voids it: does anything in it work against one? It breaks a maintain goal → do not merge; redesign the change or drop its item. It works against an achieve goal → do not merge; ask the human, stating the conflict.
2. Run the comprehension check (§3) where it runs. When `origin/<default branch>` moves after that, return to §4, and keep the scoring run already recorded. Where the chunk recorded a paired ruling, run it again at the new head and record it: it read the head before the other chunk's merge came in.
3. Run `~/.claude/bin/touch-predictions record <ID>...` in the worktree, naming the chunk's items: it records what they were predicted to touch beside what the branch touched, where the project's config names that record. A later pass through this step, after a return to §4, skips it. Commit and push it; the commit re-enters no pass. Leave the chunk's items in the plan, and write no changelog bullet in the branch: step 4 does both, so that `todo.md` and `CHANGELOG.md` never conflict between chunks. Revise any decision that cites an item now, since `todo-item finish` refuses while one does.
4. Aligned and every pass done → **merge** with `~/.claude/bin/chunk-pr merge`, run in the background with its `timeout` set to 7200000 ms, since its wait can outlast the Bash tool's default. Give it one `--finish <ID>` per item the chunk ships, each with the arguments `todo-item finish` takes (`todo-item --help`), as in `chunk-pr merge --finish 12 --changelog '<bullet>' --finish 13 --no-changelog`. The project's chunks merge one at a time. In its turn, `chunk-pr merge` merges `origin/<default branch>` into the branch, finishes those items, pushes, and waits for the pull request's checks to pass; then it takes the first merge method the repository allows on its forge. Where it stops, do what it asks and run it again with the same arguments:
4. Aligned and every pass done → **merge** with `~/.claude/bin/chunk-pr merge`, run in the background with its `timeout` set to 7200000 ms, since its wait can outlast the Bash tool's default. Give it one `--finish <ID>` per item the chunk ships, each with the arguments `todo-item finish` takes (`todo-item --help`), as in `chunk-pr merge --finish 12 --changelog '<bullet>' --finish 13 --no-changelog`. Where the plan is a Jira epic, give no `--changelog`: the issues' history is the changelog, and `todo-item finish` there refuses a bullet. The project's chunks merge one at a time. In its turn, `chunk-pr merge` merges `origin/<default branch>` into the branch, finishes those items, pushes, and waits for the pull request's checks to pass; then it takes the first merge method the repository allows on its forge. Where it stops, do what it asks and run it again with the same arguments:
- **A merge conflict.** Resolve it, commit and push. Rerun only the passes whose triggers the resolution's own lines meet (§3), each in a round of its own.
- **A paired ruling to run again.** `chunk-pr merge` has merged the default branch in and pushed. Run the ruling at that head, record it, commit and push. Don't return to §4 for it: the next turn waits for the checks at the new head.
- **An owed scoring run, or a queue another pull request holds.** Record the run, or wait, as the message says.