Answer product-owner round 1: 0 🔴, 2 🟡 (0 misread); let the planner compare Scores in the file, name finish --no-changelog for a dropped item, name the plan's path in every refusal and exit 2 on a bad --release
This commit is contained in:
@@ -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 `todo.md`. 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.
|
||||
- **Plan `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 works the same whatever holds the plan. Two readers open the file instead: a reviewer without a shell, and whoever reshapes the table or edits the sections above 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 works the same whatever holds the plan. Three open the file itself: a reviewer without a shell; 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.
|
||||
@@ -58,7 +58,7 @@ Claude Code loads a rule file when a session writes a file its `paths:` frontmat
|
||||
|
||||
- The decision log: `~/.claude/rules/decisions.md`.
|
||||
- Goals and audience: `~/.claude/rules/goals-and-audience.md`.
|
||||
- `todo.md` items, their scores and Exempt reasons: `~/.claude/rules/todo-items.md`. Read it before you file, score, edit or move an item: `todo-item` doesn't touch a path that loads it.
|
||||
- `todo.md` items, their scores and Exempt reasons: `~/.claude/rules/todo-items.md`. Read it before you file, score, edit or move an item: a session that runs `todo-item` never opens `todo.md` itself, so the rule doesn't load.
|
||||
|
||||
The rules only reviewers apply, for quality, comments, READMEs and prose, live in `~/.claude/skills/larv-review/standards/`.
|
||||
|
||||
|
||||
@@ -107,8 +107,4 @@ def plan_reasons(ref: str, ids: list[int] | None, home: pathlib.Path) -> list[st
|
||||
def checkout_plan(plan: PlanStore) -> Plan | Failure:
|
||||
"""The project's plan as it stands."""
|
||||
read = plan.read()
|
||||
if isinstance(read, NoItemsTable):
|
||||
return Failure(f"the project's plan has no items table: {read.reason}")
|
||||
if isinstance(read, Failure):
|
||||
return Failure(f"the project's plan: {read.reason}")
|
||||
return read
|
||||
return Failure(f"the project's plan: {read.reason}") if isinstance(read, Failure) else read
|
||||
|
||||
@@ -154,7 +154,7 @@ class Seats(unittest.TestCase):
|
||||
path = pathlib.Path(checkout, "todo.md")
|
||||
plan = FilePlan(path, "todo.md", pathlib.Path(checkout, "README.md"), MemoryStore(), MemoryStore())
|
||||
with self.subTest("missing"):
|
||||
self.assertIn("no items table", checkout_plan(plan).reason)
|
||||
self.assertEqual(checkout_plan(plan).reason, f"the project's plan: {path}: not found; every project keeps a todo.md, and rank_todo.py --help shows one")
|
||||
with self.subTest("no items table"):
|
||||
path.write_text("# todo\n", encoding="utf-8")
|
||||
self.assertIn("no items table", checkout_plan(plan).reason)
|
||||
@@ -767,7 +767,7 @@ class LarvReviewTool(unittest.TestCase):
|
||||
(self.checkout / "todo.md").write_text("# todo\n")
|
||||
ran = self.run_tool("needs-scoring-run", "2")
|
||||
self.assertEqual(ran.returncode, 1)
|
||||
self.assertIn("the project's plan has no items table", ran.stderr)
|
||||
self.assertIn("the project's plan: ", ran.stderr)
|
||||
|
||||
def test_records_a_ruling_once_four_seats_settle_a_split(self):
|
||||
lines = """\
|
||||
|
||||
@@ -9,7 +9,7 @@ from release_plan.ranking import stated
|
||||
HEADING = re.compile(r"^#{2,3} ", re.M)
|
||||
|
||||
|
||||
def added(todo: str, named: dict[str, str], detail: str) -> tuple[int, str] | Failure:
|
||||
def added(todo: str, named: dict[str, str], detail: str, label: str) -> tuple[int, str] | Failure:
|
||||
"""todo with an item filed under Next ID, and that ID; named holds its cells by column name, its Item cell the tagline, bold or not."""
|
||||
next_id = stated(todo, "Next ID")
|
||||
if isinstance(next_id, Failure):
|
||||
@@ -21,7 +21,7 @@ def added(todo: str, named: dict[str, str], detail: str) -> tuple[int, str] | Fa
|
||||
return unfit
|
||||
id_ = int(next_id)
|
||||
lines = re.sub(r"^`Next ID = [0-9]+`$", f"`Next ID = {id_ + 1}`", todo, count=1, flags=re.M).split("\n")
|
||||
table = held_table(lines)
|
||||
table = held_table(lines, label)
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
row = {**named, "ID": str(id_), "Item": bold_cell(tagline)}
|
||||
@@ -29,13 +29,13 @@ def added(todo: str, named: dict[str, str], detail: str) -> tuple[int, str] | Fa
|
||||
return id_, with_detail("\n".join(lines), id_, tagline, detail)
|
||||
|
||||
|
||||
def edited(todo: str, id_: int, named: dict[str, str], detail: str | None) -> str | Failure:
|
||||
"""todo with item id_'s cells set to those named holds, by column name, and its detail to detail unless None; an empty detail removes it."""
|
||||
def edited(todo: str, id_: int, named: dict[str, str], detail: str | None, label: str) -> str | Failure:
|
||||
"""todo with item id_'s cells set from named, which holds each new value by its column's name, and its detail set to detail unless None; an empty detail removes it. label is what a message calls the file."""
|
||||
lines = todo.split("\n")
|
||||
table = held_table(lines)
|
||||
table = held_table(lines, label)
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
at = row_index(table, id_)
|
||||
at = row_index(table, id_, label)
|
||||
if isinstance(at, Failure):
|
||||
return at
|
||||
if absent := [column for column in named if column not in table.columns]:
|
||||
@@ -56,13 +56,13 @@ def edited(todo: str, id_: int, named: dict[str, str], detail: str | None) -> st
|
||||
return with_detail(without_detail("\n".join(lines), id_), id_, tagline, kept)
|
||||
|
||||
|
||||
def finished(todo: str, id_: int) -> str | Failure:
|
||||
def finished(todo: str, id_: int, label: str) -> str | Failure:
|
||||
"""todo without item id_'s row and its detail."""
|
||||
lines = todo.split("\n")
|
||||
table = held_table(lines)
|
||||
table = held_table(lines, label)
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
at = row_index(table, id_)
|
||||
at = row_index(table, id_, label)
|
||||
if isinstance(at, Failure):
|
||||
return at
|
||||
del lines[at]
|
||||
@@ -105,7 +105,7 @@ def without_detail(text: str, id_: int) -> str:
|
||||
return text[:section.start(1)] + body + text[section.end(1):]
|
||||
|
||||
|
||||
def row_index(table: Table, id_: int) -> int | Failure:
|
||||
def row_index(table: Table, id_: int, label: str) -> int | Failure:
|
||||
"""The index in the file's lines of item id_'s row."""
|
||||
for at, row in enumerate(table.rows, table.start):
|
||||
found = cells(row, len(table.columns))
|
||||
@@ -113,9 +113,9 @@ def row_index(table: Table, id_: int) -> int | Failure:
|
||||
return found
|
||||
if found[0] == str(id_):
|
||||
return at
|
||||
return Failure(f"todo.md holds no item {id_}")
|
||||
return Failure(f"{label} holds no item {id_}")
|
||||
|
||||
|
||||
def held_table(lines: list[str]) -> Table | Failure:
|
||||
def held_table(lines: list[str], label: str) -> Table | Failure:
|
||||
table = items_table(lines)
|
||||
return Failure("todo.md holds no items table; rank_todo.py --help shows one") if table is None else table
|
||||
return Failure(f"{label} holds no items table; rank_todo.py --help shows one") if table is None else table
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
"""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, the only backend so far. `todo-item` is the same door for an agent.
|
||||
The config's `plan` setting names the backend. A path names a markdown file, todo.md, the only backend so far. 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`, parses that commit's todo.md with `plan_of`: only the markdown backend has commits, and todo.md's items 365, 366 and 368 port those tools to the other backends."""
|
||||
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
|
||||
import pathlib
|
||||
import typing
|
||||
@@ -29,16 +29,15 @@ MISSING = "every project keeps a todo.md, and rank_todo.py --help shows one"
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Plan:
|
||||
"""A plan as one read found it."""
|
||||
# Each item with its detail, in the order the backend supplies: by score for a markdown file, by backlog rank for a tracker.
|
||||
# Each item with its detail, in the order the backend supplies: by release and then by rank for a markdown file, by backlog rank for a tracker.
|
||||
items: list[Item]
|
||||
# The releases the plan marks renamed, so never finished.
|
||||
# The releases the plan marks renamed. Such a release holds no item because its items moved, not because it is finished.
|
||||
renamed: frozenset[Release] = frozenset()
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Written:
|
||||
"""A write that landed."""
|
||||
# The item written.
|
||||
id: int
|
||||
# What the backend says of the plan after the write, for stderr, such as an item now under the bar.
|
||||
notes: tuple[str, ...] = ()
|
||||
@@ -91,14 +90,14 @@ class FilePlan:
|
||||
texts = self.texts()
|
||||
if isinstance(texts, Failure):
|
||||
return texts
|
||||
filed = markdown_edits.added(texts[0], cells(fields), detail)
|
||||
filed = markdown_edits.added(texts[0], cells(fields), detail, self.label)
|
||||
return filed if isinstance(filed, Failure) else self.kept(*filed, texts)
|
||||
|
||||
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
|
||||
texts = self.texts()
|
||||
if isinstance(texts, Failure):
|
||||
return texts
|
||||
text = markdown_edits.edited(texts[0], id_, cells(fields), detail)
|
||||
text = markdown_edits.edited(texts[0], id_, cells(fields), detail, self.label)
|
||||
return text if isinstance(text, Failure) else self.kept(id_, text, texts)
|
||||
|
||||
def kept(self, id_: int, text: str, texts: tuple[str, str, str, str]) -> Written | Failure:
|
||||
@@ -106,7 +105,7 @@ class FilePlan:
|
||||
ranked = ranking.rank(text, *texts[1:])
|
||||
if isinstance(ranked, Failure):
|
||||
return ranked
|
||||
# The write may lower another item under the bar, which the notes then say; only the item written refuses the write.
|
||||
# The write may lower another item under the bar, which the notes then say; the write is refused only where the written item itself scores under the bar.
|
||||
if under := [line for line in ranked.under_bar if line.startswith(f"item {id_} ")]:
|
||||
return Failure(under[0])
|
||||
return self.written(id_, ranked)
|
||||
@@ -115,7 +114,7 @@ class FilePlan:
|
||||
texts = self.texts()
|
||||
if isinstance(texts, Failure):
|
||||
return texts
|
||||
text = markdown_edits.finished(texts[0], id_)
|
||||
text = markdown_edits.finished(texts[0], id_, self.label)
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
ranked = ranking.rank(text, *texts[1:])
|
||||
|
||||
+22
-14
@@ -10,14 +10,15 @@ 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, and names it in what it prints. Read and change the plan only through
|
||||
these commands: they work the same whatever holds it. Today that is a markdown file, todo.md, and
|
||||
each command that changes it ranks it as rank_todo.py does, so it also reads the goals file and
|
||||
docs/decisions.md, each where the config puts it.
|
||||
`project-config plan` prints. The commands work the same whatever holds the plan.
|
||||
Today a markdown file, todo.md, holds it. Each command that changes the file 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.
|
||||
|
||||
list prints `From <plan>, in its order:`, then one table row per item, without details: first the
|
||||
earliest release, and within a release the item to take first. --release prints one release's items.
|
||||
list prints `From <plan>, in its order:`, then the table's header and divider and one row per item,
|
||||
without details: first the earliest release, and within a release the item to take first.
|
||||
--release prints one release's items. Where no item fits, it prints `<plan> holds no item.`
|
||||
|
||||
show prints `From <plan>:`, then the table's header and divider, item <ID>'s row, and its detail under
|
||||
`### <ID>. <tagline>`, sub-headings included. It fails, saying so, where the plan holds no item <ID>.
|
||||
@@ -40,6 +41,7 @@ CHANGELOG.md's ## Unreleased, or a ## heading that says unreleased, creating the
|
||||
file, where missing. It refuses where that section holds ### subsections: add the bullet by hand.
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -52,7 +54,7 @@ import typing
|
||||
from release_plan.todo_table import BLOCKED_BY, MOVES
|
||||
from failure import Failure
|
||||
from project_config.main import located
|
||||
from release_plan.release import parsed
|
||||
from release_plan.release import parsed, Release, version as release_version
|
||||
from plan_store.stores import store as plan_store, PlanStore, TAGLINE, Written
|
||||
from record_store.stores import RecordStore, store
|
||||
from todo_item.table import shown, table
|
||||
@@ -97,7 +99,7 @@ def main(argv: list[str], folder: pathlib.Path = pathlib.Path(), stdin: typing.T
|
||||
def parser() -> argparse.ArgumentParser:
|
||||
parsed_ = argparse.ArgumentParser(prog="todo-item")
|
||||
commands = parsed_.add_subparsers(dest="command", required=True)
|
||||
commands.add_parser("list").add_argument("--release")
|
||||
commands.add_parser("list").add_argument("--release", type=version)
|
||||
commands.add_parser("show").add_argument("id", type=int)
|
||||
adding = commands.add_parser("add")
|
||||
adding.add_argument("--release", required=True)
|
||||
@@ -121,6 +123,14 @@ def parser() -> argparse.ArgumentParser:
|
||||
return parsed_
|
||||
|
||||
|
||||
def version(text: str) -> Release:
|
||||
"""The release a --release value names; a bad argument where it is no semver version."""
|
||||
release = parsed(text)
|
||||
if release is None:
|
||||
raise argparse.ArgumentTypeError(f"{text!r} is not a semver version")
|
||||
return release
|
||||
|
||||
|
||||
def cell_flags(command: argparse.ArgumentParser, required: bool) -> None:
|
||||
"""The flags add and edit share. add needs each score; a flag edit is not given stays None, so its cell stays as it is."""
|
||||
for letter in LETTERS:
|
||||
@@ -150,14 +160,12 @@ def reported(written: Written | Failure, refusal: str, done: typing.Callable[[Wr
|
||||
|
||||
|
||||
def list_(args: argparse.Namespace, plan: PlanStore) -> str | Failure:
|
||||
if args.release is not None and parsed(args.release) is None:
|
||||
return Failure(f"--release {args.release!r} is not a semver version")
|
||||
read = plan.read()
|
||||
if isinstance(read, Failure):
|
||||
return read
|
||||
found = [item for item in read.items if args.release is None or item.release == parsed(args.release)]
|
||||
found = [item for item in read.items if args.release is None or item.release == args.release]
|
||||
if not found:
|
||||
return f"{plan.label} holds no item{'' if args.release is None else f' for release {args.release}'}."
|
||||
return f"{plan.label} holds no item{'' if args.release is None else f' for release {release_version(args.release)}'}."
|
||||
return f"From {plan.label}, in its order:\n\n{table(found)}"
|
||||
|
||||
|
||||
@@ -185,8 +193,8 @@ def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore) ->
|
||||
if isinstance(news, Failure):
|
||||
return Failure(f"not finished: {news.reason}")
|
||||
if news and args.changelog is None and not args.no_changelog:
|
||||
return Failure(f"not finished: {changelog.label} exists; pass --changelog <bullet>, or --no-changelog where the repo doesn't publish anything")
|
||||
# The bullet is checked before the plan changes, so a bullet finish refuses leaves both as they were.
|
||||
return Failure(f"not finished: {changelog.label} exists; pass --changelog <bullet>, or --no-changelog where the repo doesn't publish anything or no chunk built the item")
|
||||
# The bullet is checked before the plan changes: where finish refuses the bullet, the plan and the changelog stay as they were.
|
||||
added = None if args.changelog is None else with_bullet(news, args.changelog)
|
||||
if isinstance(added, Failure):
|
||||
return Failure(f"not finished: {added.reason}")
|
||||
|
||||
@@ -278,7 +278,7 @@ class Show(TodoItem):
|
||||
(folder / "news" / "CHANGELOG.md").write_text("# Changelog\n")
|
||||
self.assertEqual(self.run_main("show", "3")[1].split("\n")[0], f"From {folder}/todo.md:")
|
||||
self.assertEqual(self.run_main(*ADD)[:2], (0, f"Filed item 6 in {folder}/todo.md.\n"))
|
||||
self.assertEqual(self.run_main("finish", "3"), (1, "", f"not finished: {folder}/news/CHANGELOG.md exists; pass --changelog <bullet>, or --no-changelog where the repo doesn't publish anything\n"))
|
||||
self.assertEqual(self.run_main("finish", "3"), (1, "", f"not finished: {folder}/news/CHANGELOG.md exists; pass --changelog <bullet>, or --no-changelog where the repo doesn't publish anything or no chunk built the item\n"))
|
||||
self.assertEqual(self.run_main("finish", "3", "--changelog", "Runs are fast."), (0, f"Finished item 3 in {folder}/todo.md.\n", ""))
|
||||
self.assertIn("- Runs are fast.", (folder / "news" / "CHANGELOG.md").read_text())
|
||||
self.assertEqual(self.todo.read_text(), "the project owners' own notes\n")
|
||||
@@ -364,7 +364,7 @@ class List(TodoItem):
|
||||
self.assertEqual(self.run_main("list"), (0, f"{self.todo} holds no item.\n", ""))
|
||||
|
||||
def test_fails_on_a_release_that_is_no_version(self):
|
||||
self.assertEqual(self.run_main("list", "--release", "next"), (1, "", "--release 'next' is not a semver version\n"))
|
||||
self.assertEqual(self.exit_code("list", "--release", "next"), 2)
|
||||
|
||||
def test_changes_no_file(self):
|
||||
before = self.todo.read_text()
|
||||
@@ -422,7 +422,7 @@ class Edit(TodoItem):
|
||||
|
||||
def test_writes_nothing_where_it_refuses(self):
|
||||
before = self.todo.read_text()
|
||||
for argv, reason in ((["99", "--l", "1"], "todo.md holds no item 99"), (["3", "--l", "7"], "item 3's L '7' is not a whole number from 1 to 4"), (["3", "--s", "10"], "item 3 scores")):
|
||||
for argv, reason in ((["99", "--l", "1"], f"{self.todo} holds no item 99"), (["3", "--l", "7"], "item 3's L '7' is not a whole number from 1 to 4"), (["3", "--s", "10"], "item 3 scores")):
|
||||
with self.subTest(argv):
|
||||
code, out, err = self.run_main("edit", *argv)
|
||||
self.assertEqual((code, out), (1, ""))
|
||||
@@ -440,7 +440,7 @@ class Move(TodoItem):
|
||||
def test_writes_nothing_where_it_refuses(self):
|
||||
before = self.todo.read_text()
|
||||
self.assertEqual(self.run_main("move", "3", "--release", "soon"), (1, "", "not moved: item 3's release 'soon' is not a semver version\n"))
|
||||
self.assertEqual(self.run_main("move", "99", "--release", "0.2.0"), (1, "", "not moved: todo.md holds no item 99\n"))
|
||||
self.assertEqual(self.run_main("move", "99", "--release", "0.2.0"), (1, "", f"not moved: {self.todo} holds no item 99\n"))
|
||||
self.assertEqual(self.todo.read_text(), before)
|
||||
|
||||
|
||||
@@ -460,6 +460,11 @@ class Table(unittest.TestCase):
|
||||
self.assertEqual(table(old.items).split("\n")[0], "| ID | Release | Blocked by | Exempt | Item | R | S | C | A | G | Goals |")
|
||||
self.assertEqual(table(old.items).split("\n")[2], "| 3 | 0.2.0 | | | **Do the next thing.** | 5 | 2 | 1 | 2 | 3 | 1 |")
|
||||
|
||||
def test_a_row_lists_the_items_that_block_it_and_leaves_a_score_it_lacks_empty(self):
|
||||
old = plan_of("## Items\n\n| ID | Release | Blocked by | Exempt | Item | R | S | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|\n| 3 | 0.2.0 | 1, 2 | | **Do the next thing.** | 5 | 2 | 2 | 3 | 1 | 1.0 |\n")
|
||||
self.assertEqual(table(old.items).split("\n")[2], "| 3 | 0.2.0 | 1, 2 | | **Do the next thing.** | 5 | 2 | | 2 | 3 | 1 |")
|
||||
|
||||
|
||||
|
||||
class WithBullet(unittest.TestCase):
|
||||
def test_keeps_a_blank_line_before_prose_under_unreleased(self):
|
||||
|
||||
+14
-14
@@ -37,8 +37,8 @@ Each project principle states one rule that the decisions below apply; their ent
|
||||
- tests: each test earns its keep as the technical principles' test bullet says, and the worker takes a test's expected values from its item, never from the code
|
||||
- the repo may name bender, bender-infra and ai-sandbox
|
||||
- todo.md: one table of items, scored by the formula it states, held to its bar and ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; each achieve goal weighs by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0 or unmeasured, then the goals file's goals, and a maintain goal weighs 0.5 per point of the confidence an item's test, gate leg or probe adds to it; the table's order is the plan's only order
|
||||
- todo.md: tools and agents read and change the plan as it stands only through `bin/plan_store` and `todo-item`; a tool that reads what a past commit held, ranks the file or checks its rank still parses `todo.md`
|
||||
- todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan; one below it drafts new items and changes to filed ones for a subagent at or above that rung to apply and score, and removes finished ones
|
||||
- todo.md: tools and agents read and change the plan as it stands only through `bin/plan_store` and `todo-item`; a tool that reads what a past commit held, ranks the file or checks its rank still parses `todo.md`
|
||||
- worker: a chunk's worker writes the simplest change that solves its item, test first wherever a test can check the change, and reads a technical principle only where the item, a finding or its own record names it; larv-review's reviewers hold the change to the principles and to the standards in `skills/larv-review/standards/`
|
||||
- workflow-bench/: the remote may show the bench cases' names and commit SHAs
|
||||
|
||||
@@ -669,25 +669,25 @@ Valid while the worker writes the tests that larv-review's reviewers hold to the
|
||||
|
||||
2026-11-09, lilleman. Serves goal 1.1: a test, gate leg or probe that guards a maintain goal proves the output holds it, and an item that adds one scored V 0 and ranked last. adf-codec's item 170 bundles the package with four bundlers to back its goal 8, runs on any JavaScript engine, and scored 0.0 beside items that move an achieve goal by 2. Such an item now names the maintain goal in Moves, by how much more confident the project becomes that the goal holds, 1 to 10, judged against the confidence it already has; `rules/todo-items.md` holds the scale. The goal weighs 0.5 per point of that move, `MAINTAIN_WEIGHT` in `bin/release_plan/ranking.py`. A defect that restores a broken maintain goal weighs it as the heaviest achieve goal, or 0.5 where that is lighter, since a broken goal outranks any achieve goal and any confidence gain; a maintain goal still vetoes an item that breaks it. The 0.5 comes from 150 distinct item and Moves pairs in 40 random `todo.md` commits from 2026-09-24 to 2026-11-09. The V their scores imply has quartiles 1.4, 2.6 and 4.5, and the median item earns 0.49 per point it moves a goal. At 0.5, a move of 10 is worth 5.0, about the third quartile; a move of 5 is worth 2.5, the median; a move of 1 is worth 0.5, under the tenth percentile, so only a cheap item ships. Valid while the achieve goals' weights and the formula's F keep the typical item's V near that distribution; a change to either revisits the 0.5. 2026-11-10, lilleman: the 0.5 does not change with the number of achieve goals. fejkdata has 11 achieve goals, code health included, and each weighs at most 0.105 per point, or 0.42 for code health while its comprehension overall is under 7.0, so a maintain goal's 0.5 outweighs each of them. Revisit the 0.5 when that becomes a problem, such as maintain items ranking above achieve items the human would take first.
|
||||
|
||||
## todo.md: tools and agents read and change the plan as it stands only through `bin/plan_store` and `todo-item`; a tool that reads what a past commit held, ranks the file or checks its rank still parses `todo.md`
|
||||
|
||||
2026-11-14, the worker of todo item 350. Serves goal 1.6: a client keeps its plan where its team works, so no tool or agent may assume a file. `bin/plan_store/stores.py` holds the interface, `PlanStore`, and its markdown backend, `FilePlan`; `contract.py` holds the tests every backend passes, as `bin/record_store/` does for the records. `todo-item` is the same door for an agent: `list`, `show`, `add`, `edit`, `move` and `finish`.
|
||||
|
||||
Four choices the item left open:
|
||||
|
||||
- **Three kinds of tool still parse `todo.md`.** One reads what a past commit held: `score-outcomes`, the routing figures, `release_standing`'s `todos_since`, and larv-review's plan before the chunk. Only a markdown plan has commits, and todo items 365, 366 and 368 port those tools. One ranks the file, `rank_todo.py`. One checks its rank, rule-hook's `todo-rank-check`, whose Jira twin is todo item 367.
|
||||
- **A plan outside the checkout names no release since the last cut.** `todos_since` returns an empty list there. Before, it read the file as it stood in place of each past commit, which said the same as the plan itself.
|
||||
- **`list` and `show` print no Score.** The store hands items over in the backend's order, and a tracker has no score, so an item's place in `list` says how it ranks.
|
||||
- **The spellings `list [--release]`, `move <ID> --release`, and `edit <ID>` with one flag per cell, `--detail` from stdin and `--clear-detail`** are those a panel of three fresh readers, seated as the audience, picked over a positional release, `set` and `retarget`. `edit` refuses stdin text without `--detail`, and `--detail` without text, so no detail is dropped or wiped by mistake.
|
||||
|
||||
`rules/todo-items.md` loads when a session touches a `todo.md`, which `todo-item` never does, so `CLAUDE.md` → "Topic rules" asks for it before an item is filed, scored, edited or moved. A reviewer without a shell still opens the file; todo item 351 hands it the plan another way. Valid while `todo-item` is the only command that changes a plan's items.
|
||||
|
||||
## todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan; one below it drafts new items and changes to filed ones for a subagent at or above that rung to apply and score, and removes finished ones
|
||||
|
||||
2026-10-15, lilleman. Serves goal 1.1: a cheaper rung writes worse scores, and a wrong score routes a chunk onto the wrong rung, ranks the plan wrong and drops an item under the bar that should stay. Below the project's rung, a session or subagent may not score an item, move it between releases, split a milestone, delete an item under the bar, or rewrite a filed item. It drafts each new item, and each change to a filed item, such as a refresh a rule asks for. Before the next commit, one subagent on the project's rung or above applies and scores the drafts. One launch covers all of a chunk's drafts (goal 1.4). A security finding gets that subagent at once, since it is filed the moment it is found. Removing a finished item closes work and plans none, so any rung does it. Scoring a delegated task's L runs on any rung too: a launch on the project's rung to score each delegation would cost more than the cheaper task saves (goal 1.4).
|
||||
|
||||
Three places carry the rule. `rules/todo-items.md` states it; it loads with `todo.md`, and `CLAUDE.md` → "Topic rules" asks for it before an item is filed or changed. `CLAUDE.md`'s delegation rule launches the scoring subagent on the rung `bin/subagent-rung --plan` prints: the one the task's L picks, never below the project's, so a hard scoring task still climbs. `bin/loop_claude/cycle/prompts.py`'s `review_launches` names the same command to a worker below the project's rung, never a fixed rung, which would disagree with `--plan` on a scoring task of L 4. Valid while a worker or subagent may run below the project's rung.
|
||||
|
||||
## todo.md: tools and agents read and change the plan as it stands only through `bin/plan_store` and `todo-item`; a tool that reads what a past commit held, ranks the file or checks its rank still parses `todo.md`
|
||||
|
||||
2026-11-14, the worker of todo item 350. Serves goal 1.6: a client keeps its plan where its team works, so no tool or agent may assume a file. `bin/plan_store/stores.py` holds the interface, `PlanStore`, and its markdown backend, `FilePlan`; `contract.py` holds the tests every backend passes, as `bin/record_store/` does for the records. An agent reads and changes the plan with `todo-item`: `list`, `show`, `add`, `edit`, `move` and `finish`. `finish <ID> --no-changelog` also drops an item no chunk built.
|
||||
|
||||
Four choices the item left open:
|
||||
|
||||
- **Three kinds of tool still parse `todo.md`.** Four read what a past commit held: `score-outcomes`, the routing figures, `release_standing`'s `todos_since`, and larv-review's plan before the chunk. Only a markdown plan has commits, and todo items 365, 366 and 368 port those tools. Two rank the file: `rank_todo.py` and `larv-review record-scoring`. One checks its rank: rule-hook's `todo-rank-check`, whose Jira twin is todo item 367.
|
||||
- **`todos_since` is empty for a plan outside the checkout,** since no commit holds that plan. Before, it read the file as it stood in place of each past commit, which said the same as the plan itself.
|
||||
- **`list` and `show` print no Score.** The store hands items over in the backend's order, and a tracker has no score, so an item's place in `list` says how it ranks within its release. Whoever plans a release compares Scores across releases, and so opens `todo.md`, until a store hands over a score.
|
||||
- **The spellings `list [--release]`, `move <ID> --release`, and `edit <ID>` with one flag per cell, `--detail` from stdin and `--clear-detail`** are those a panel of three fresh readers, seated as the audience, picked over a positional release, `set` and `retarget`. `edit` refuses stdin text without `--detail`, and `--detail` without text, so no detail is dropped or wiped by mistake.
|
||||
|
||||
`rules/todo-items.md` loads when a session itself reads or writes a `todo.md`, which a session that runs `todo-item` never does, so `CLAUDE.md` → "Topic rules" asks for it before an item is filed, scored, edited or moved. A reviewer without a shell still opens the file; todo item 351 hands it the plan another way. Valid while `todo-item` is the only command that changes a plan's items.
|
||||
|
||||
## worker: a chunk's worker writes the simplest change that solves its item, test first wherever a test can check the change, and reads a technical principle only where the item, a finding or its own record names it; larv-review's reviewers hold the change to the principles and to the standards in `skills/larv-review/standards/`
|
||||
|
||||
2026-10-13, lilleman through todo item 104, implemented by claude. Serves goals 1.4 and 1.5. Like red, green, refactor: the worker makes the item work, and the review passes raise it to the bar. A loop-claude worker loaded `CLAUDE.md` and every file under `rules/`, 4,247 words, and `CLAUDE.md` told it to read `technical-principles.md` too, 2,426 words more. The reviewers read the principles anyway, and a finding against one names it.
|
||||
|
||||
+1
-1
@@ -6,7 +6,7 @@ paths:
|
||||
# Todo items (`todo.md`)
|
||||
|
||||
- **`todo.md` is mandatory in every project, in the shape `rank_todo.py --help` shows**, which `~/.claude/bin/rank_todo.py` checks and ranks; its `--help` shows a valid file. `## 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 each ranks the plan; `todo-item --help` shows the flags. Edit `todo.md` itself only for what `todo-item` has no command for: `## Scoring`, `## Renamed`, and reshaping an old table.
|
||||
- **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 `todo.md` alone.
|
||||
- **An item's release allows the bump that semver read strictly asks for.** An item that changes what exists needs a major, or before 1.0.0 a minor. One that only adds needs a minor, and a fix a patch.
|
||||
|
||||
Reference in New Issue
Block a user