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
CI / tests (pull_request) Successful in 3m17s
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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}")
|
||||
|
||||
@@ -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 |"
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user