Merge pull request 'Rank each todo.md blocker above the items it blocks, allow no other order in todo.md, and route loop-claude on the first item that does not wait' (#280) from plan-136 into main
This commit was merged in pull request #280.
This commit is contained in:
@@ -26,7 +26,7 @@ Decisions live in `docs/decisions.md`:
|
||||
- workflow-bench/: the remote may show the bench cases' names and commit SHAs
|
||||
- settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped
|
||||
- the repo may name bender, bender-infra and ai-sandbox
|
||||
- todo.md: one table of items scored by the formula and goal weights it states, held to its bar, ranked by `bin/rank_todo.py`
|
||||
- todo.md: one table of items scored by the formula and goal weights it states, held to its bar, ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; the table's order is the plan's only order
|
||||
- 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
|
||||
- reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to `docs/reading-cost.md` in the next chunk's PR
|
||||
- reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- `todo.md`'s items table has a Blocked by column, right after Release, listing the IDs of the items that must be done before an item starts, such as `12, 14`. Move every machine to this release before any of them ranks a plan another machine shares: an older release reads the new table as no plan. `rank_todo.py` ranks each blocker above every item it blocks, drops an ID once that item leaves the table, and adds the column to a table without it. It does not turn a line such as "Needs 12" in an item's detail into a Blocked by cell; move each into the column by hand. It now fails on text beside the table under `## Items`, such as a line naming items to take first: put an order in the scores or the column. It reads the table's cells by column name, and fails on a column it does not know rather than drop it. `loop-claude` routes a chunk on the next release's first item that is neither marked `question` nor blocked by an item still in the table, which is the item the worker takes, so the first cycle runs on that item's rung.
|
||||
- The new `bin/stability-replay <model>` replays archived stability reviews of the projects run on the model, each on the code it reviewed, first on the project's rung and then on each rung below, and prints the lowest rung that, like each rung above it, finds every 🔴 and 🟡 finding the project's rung finds. It shares its search with `judge-replay`, which now tries rungs from the project's rung down, where it tried them from the cheapest up. Its first run, on Opus 5.5 projects, found none: Sonnet 5.5 at high missed 13 of the 29 findings the project's rung found again. So the stability reviewer stays on the project's rung while the worker runs below it.
|
||||
- A `todo.md` item you tell a session to keep is marked `owner` in its Exempt cell, and stays whatever its score.
|
||||
- A `loop-claude` worker hands a task that proves too hard for its rung to a subagent one rung up, edits included, when a trigger fires: a re-score of the item on the project's rung or above picks a higher rung, the same failing test or finding survives two fix attempts, or a review pass reports a 🔴 in round 2 or later. Each further trigger climbs one more rung, to at most two rungs above the rung the chunk's `todo.md` item picks, unless you agree. `CLAUDE.md` states the rule, and `loop-claude`'s prompt names the rungs a trigger opens. The worker opens the subagent's prompt with `Escalation trigger <n>:`, and `routing-figures.md` counts the escalations by trigger. Expect a chunk that gets stuck to spend more on the stuck part, and fewer unfinished verdicts.
|
||||
|
||||
@@ -11,7 +11,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **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 publishes nothing says so once.
|
||||
- **Read the README's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes. `AGENTS.md` lists every decision's title. Read the entry under a title in `docs/decisions.md` only where the title leaves open what the chunk or the review needs.
|
||||
- **Work one chunk at a time, and make it as large as one purpose allows.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: one PR title states what they achieve together, without listing them; they name one release; and they fire the same review passes (`larv-review` §3). Tiny items, a few lines of change each, need neither a shared purpose nor the same passes: bundle up to ten that name one release into one chunk. Split a milestone into items in `todo.md` before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`. An item marked `question` waits for the human; take the next item.
|
||||
- **Work one chunk at a time, and make it as large as one purpose allows.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which four things hold: one PR title states what they achieve together, without listing them; they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need neither a shared purpose nor the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in `todo.md` before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
|
||||
- **Ask, don't guess.** First check whether the goals already answer the question. 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. Write every answer once, where it belongs, never only in chat: a goal in `README.md`, 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 README, 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 README'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. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file under `~/.claude/principles/` only when the item changes it, a finding or a record you write names it, or you decline a finding.
|
||||
|
||||
@@ -34,7 +34,7 @@ def said(overall: str, locality: str = "same") -> str:
|
||||
|
||||
|
||||
def item(id_: int, release: tuple[int, int, int], tagline: str = "**Do it.**") -> Item:
|
||||
return Item(id_, release, "", tagline, {"R": 1, "S": 1, "C": 3, "A": 1, "G": 1}, ("1",))
|
||||
return Item(id_, release, "", tagline, {"R": 1, "S": 1, "C": 3, "A": 1, "G": 1}, ("1",), ())
|
||||
|
||||
|
||||
def todo(*rows: str) -> str:
|
||||
|
||||
@@ -43,7 +43,8 @@ for the worker and the interrupt; with both set, nothing is asked.
|
||||
|
||||
Where that model is on the routing ladder (bin/model_routing/ladder.py), the worker and the
|
||||
interrupt run on one of the ladder's rungs: a model at an effort. As a chunk starts, the R + C of
|
||||
todo.md's top item in the next release, skipping an item marked question, picks the rung. It
|
||||
todo.md's top item in the next release that does not wait picks the rung: an item waits while it is
|
||||
marked question, or while an item that blocks it is still in the table. The R + C
|
||||
counts from the model's cheapest rung, and an R + C of 8 or less picks a rung below it; without
|
||||
such an item, or with a C missing, the chunk runs on the model's cheapest rung. The worker's first
|
||||
prompt names the rung and the item, and asks the worker to name each item the chunk takes, with its
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
"""Which ladder rung a chunk's worker and judge run on: docs/decisions.md → `routing:`."""
|
||||
import dataclasses
|
||||
|
||||
from model_routing.ladder import climbed, floored, highest, LADDER, picked, position, project_rung, Rung, stepped_up
|
||||
from model_routing.ladder import climbed, highest, LADDER, picked, position, project_rung, Rung, stepped_up
|
||||
from failure import Failure
|
||||
from todo_table import Item, items
|
||||
from todo_table import Item, items, waiting
|
||||
from model_routing.route import Route
|
||||
|
||||
UNFINISHED_PER_STEP = 2
|
||||
@@ -14,12 +14,13 @@ JUDGE_REPLAYED = ("claude-opus-5-5",)
|
||||
|
||||
|
||||
def routed_item(todo: str) -> Item | Failure | None:
|
||||
"""The next release's first row that waits on no question, in the table's order, which rank_todo.py keeps ranked; None when there is none, or it has no C."""
|
||||
"""The next release's first row that does not wait, as todo_table.waiting says, in the table's order; None when there is none, or it has no C."""
|
||||
found = items(todo)
|
||||
if isinstance(found, Failure) or not found:
|
||||
return found if isinstance(found, Failure) else None
|
||||
next_release = min(item.release for item in found)
|
||||
takes = next((item for item in found if item.release == next_release and item.exempt != "question"), None)
|
||||
waits = waiting(found)
|
||||
takes = next((item for item in found if item.release == next_release and item.id not in waits), None)
|
||||
return takes if takes and takes.risk_and_complexity else None
|
||||
|
||||
|
||||
@@ -81,13 +82,13 @@ def taken_in(anchor: Rung, route: Route, bundled: int) -> Rung:
|
||||
|
||||
|
||||
def judge_rung(judge_model: str, route: Route) -> Rung:
|
||||
"""The rung the route's item picks from the judge model's cheapest rung, never below that rung, whatever rung the worker stepped to.
|
||||
"""The rung the route's item picks, counted from the judge model's cheapest rung and never below it, whatever rung the worker stepped to.
|
||||
|
||||
An item the worker takes in moves the worker's rung but not the judge's, until todo.md item 136 routes the chunk on the item the worker takes.
|
||||
An item the worker takes in beyond the routed one lifts the worker's rung, through taken_in, but not the judge's, until todo.md item 153 lifts the judge too.
|
||||
|
||||
A model off the ladder, or not in JUDGE_REPLAYED, gets no effort flag, so claude runs it at the effort its settings give.
|
||||
"""
|
||||
anchor = project_rung(judge_model)
|
||||
if anchor is None or judge_model not in JUDGE_REPLAYED:
|
||||
return Rung(judge_model)
|
||||
return floored(anchor, route.risk_and_complexity) if route.item else anchor
|
||||
return highest(anchor, item_rung(anchor, route))
|
||||
|
||||
@@ -508,6 +508,13 @@ class Routing(unittest.TestCase):
|
||||
self.assertIsNone(routing.routed_item(without_c))
|
||||
self.assertEqual(routing.routed_item(TODO.replace("| 5 | 3 |", "| x | 3 |")), Failure("item 3's R 'x' is not a whole number from 1 to 10"))
|
||||
|
||||
def test_routes_past_an_item_a_waiting_item_blocks(self):
|
||||
todo = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | R | S | C | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n| 7 | 0.2.0 | | question | **Ask first.** | 9 | 1 | 9 | 9 | 9 | 1 | 30 |\n| 8 | 0.2.0 | 7 | | **Use the answer.** | 1 | 1 | 1 | 9 | 9 | 1 | 30 |\n| 9 | 0.2.0 | 8 | | **Build on it.** | 1 | 1 | 1 | 9 | 9 | 1 | 30 |\n| 3 | 0.2.0 | | | **Do the next thing.** | 5 | 3 | 6 | 8 | 9 | 1 | 25 |\n"
|
||||
self.assertEqual(routing.routed_item(todo).id, 3)
|
||||
self.assertEqual(routing.routed_item(todo.replace("| question |", "| |")).id, 7)
|
||||
unranked = todo.replace("| 7 | 0.2.0 | | question | **Ask first.** | 9 | 1 | 9 | 9 | 9 | 1 | 30 |\n", "") + "| 7 | 0.2.0 | | question | **Ask first.** | 9 | 1 | 9 | 9 | 9 | 1 | 30 |\n"
|
||||
self.assertEqual(routing.routed_item(unranked).id, 3)
|
||||
|
||||
def test_starts_a_chunk_on_the_rung_its_items_r_plus_c_picks_below_the_projects_too(self):
|
||||
self.assertEqual(routing.first_route(self.OPUS, routing.routed_item(TODO)), Route(self.HIGH, 3, 11))
|
||||
cheap = routing.routed_item(TODO.replace("| 5 | 3 | 6 |", "| 1 | 3 | 1 |"))
|
||||
|
||||
+129
-35
@@ -5,8 +5,10 @@ usage: rank_todo.py [--check] [todo.md]
|
||||
|
||||
Reads todo.md (default: ./todo.md), the README.md beside it, and docs/decisions.md when there is
|
||||
one. Rewrites each item's Score from the formula and sorts the items by release; within a release,
|
||||
security rows come first, then the rest by score from highest, then by ID. Orders the details to
|
||||
match. --check writes nothing and fails when the file is not ranked as it would be.
|
||||
security rows come first, then the rest by score from highest, then by ID. Then it moves each blocker,
|
||||
an item another's Blocked by cell names, that ranks below an item it blocks to just above the first
|
||||
such item. Orders the details to match. Adds the Blocked by column to a table
|
||||
without it. --check writes nothing and fails when the file is not ranked as it would be.
|
||||
|
||||
A valid todo.md; ## Details and each item's detail are optional:
|
||||
|
||||
@@ -26,9 +28,9 @@ A valid todo.md; ## Details and each item's detail are optional:
|
||||
|
||||
## Items
|
||||
|
||||
| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 1 | 0.1.0 | | **Make the first thing work.** | 2 | 3 | 4 | 8 | 9 | 1 | 0 |
|
||||
| ID | Release | Blocked by | Exempt | Item | R | S | C | A | G | Goals | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 1 | 0.1.0 | | | **Make the first thing work.** | 2 | 3 | 4 | 8 | 9 | 1 | 0 |
|
||||
|
||||
## Details
|
||||
|
||||
@@ -46,6 +48,13 @@ A valid todo.md; ## Details and each item's detail are optional:
|
||||
principle, question or security. An item docs/decisions.md cites as "`todo.md` item N" must be
|
||||
exempt, and a row marked decision must be cited there.
|
||||
- An item's Item cell is one bold tagline; its detail, if any, sits under its ID in ## Details.
|
||||
- An item's Blocked by cell is empty, or lists IDs such as `12, 14`: each must be done before the
|
||||
item starts, so no blocker may sit in a later release, and no item may block itself or form a
|
||||
loop. An ID at or above Next ID fails; one below it that the table no longer holds was finished
|
||||
or deleted, and is dropped.
|
||||
- ## Items holds the table and nothing else: an order goes in the scores or the Blocked by column.
|
||||
- The table holds the columns above. A table without Blocked by gains it. One without C fails, and so
|
||||
does one with a column this version does not know, since writing it would drop that column.
|
||||
|
||||
Exit 1, saying why, on bad arguments, a file that cannot be read or written, a todo.md, README.md or
|
||||
docs/decisions.md that breaks the rules above, an item that is not exempt scoring under the bar, or
|
||||
@@ -58,7 +67,7 @@ import pathlib
|
||||
import re
|
||||
import sys
|
||||
|
||||
from todo_table import cells, Item, ITEMS_HEADER, parse_row, table_rows, WITHOUT_C
|
||||
from todo_table import BLOCKED_BY, cells, COLUMNS, DIVIDER, HEADER_START, Item, ITEMS_HEADER, items_table, parse_row, Table, table_rows
|
||||
from failure import Failure
|
||||
from markdown_text import FENCE, sections
|
||||
from file_writes import replace_file
|
||||
@@ -82,6 +91,8 @@ class Scoring:
|
||||
class Ranked:
|
||||
text: str
|
||||
under_bar: list[str]
|
||||
# Blocker IDs the ranking dropped because the table no longer holds them; printed, since a mistyped ID is dropped the same way.
|
||||
dropped: list[str]
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
@@ -107,7 +118,7 @@ def main(argv: list[str]) -> int:
|
||||
unwritten = write(todo, ranked.text)
|
||||
if unwritten:
|
||||
return fail(unwritten)
|
||||
for line in ranked.under_bar:
|
||||
for line in ranked.dropped + ranked.under_bar:
|
||||
print(f"{todo}: {line}", file=sys.stderr)
|
||||
return 1 if ranked.under_bar else 0
|
||||
|
||||
@@ -166,30 +177,55 @@ def rank(text: str, readme: str, decisions: str) -> Ranked | Failure:
|
||||
table = read_items(lines, scoring)
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
items, start = table
|
||||
items, found = table
|
||||
if uncited := check_citations(items, decisions):
|
||||
return uncited
|
||||
scored = []
|
||||
scored = ordered(items, scoring)
|
||||
if isinstance(scored, Failure):
|
||||
return scored
|
||||
# Every table gets the header of COLUMNS, so one from before BLOCKED_BY joined gains the column.
|
||||
lines[found.header:found.start] = [ITEMS_HEADER, DIVIDER]
|
||||
lines[found.start:found.start + len(scored)] = [render_item(item, value) for item, value in scored]
|
||||
ranked = rank_details("\n".join(lines), [item for item, _ in scored])
|
||||
if isinstance(ranked, Failure):
|
||||
return ranked
|
||||
under_bar = [under_the_bar(item, value, scoring.bar, items) for item, value in scored if not item.exempt and round(value, 1) < scoring.bar]
|
||||
held = {item.id for item in items}
|
||||
dropped = [f"item {item.id}: dropped {', '.join(map(str, gone))} from its {BLOCKED_BY}; the table no longer holds {'it' if len(gone) == 1 else 'them'}" for item in items if (gone := sorted(set(item.blocked_by) - held))]
|
||||
return Ranked(ranked, under_bar, dropped)
|
||||
|
||||
|
||||
def blocked_through(id_: int, items: list[Item]) -> set[int]:
|
||||
"""The IDs of the items id_ blocks, and of those they block in turn."""
|
||||
found: set[int] = set()
|
||||
reached = {id_}
|
||||
while reached:
|
||||
reached = {other.id for other in items if reached.intersection(other.blocked_by)} - found
|
||||
found |= reached
|
||||
return found
|
||||
|
||||
|
||||
def ordered(items: list[Item], scoring: Scoring) -> list[tuple[Item, float]] | Failure:
|
||||
"""Each item with its score, by release, then security first, then by score from highest, then by ID; then each blocker above every item it blocks."""
|
||||
by_score = []
|
||||
for item in items:
|
||||
value = score(scoring.formula, item, scoring.weights)
|
||||
if isinstance(value, Failure):
|
||||
return value
|
||||
scored.append((item, value))
|
||||
scored.sort(key=lambda pair: (pair[0].release, pair[0].exempt != "security", -pair[1], pair[0].id))
|
||||
lines[start:start + len(scored)] = [render_item(item, value) for item, value in scored]
|
||||
ranked = rank_details("\n".join(lines), [item for item, _ in scored])
|
||||
if isinstance(ranked, Failure):
|
||||
return ranked
|
||||
under_bar = [f"item {item.id} scores {value:.1f}, under the bar {scoring.bar:g}; delete it and any item that needs it, or mark it with a reason the bar does not apply" for item, value in scored if not item.exempt and round(value, 1) < scoring.bar]
|
||||
return Ranked(ranked, under_bar)
|
||||
by_score.append((item, value))
|
||||
by_score.sort(key=lambda pair: (pair[0].release, pair[0].exempt != "security", -pair[1], pair[0].id))
|
||||
return blockers_first(by_score)
|
||||
|
||||
|
||||
def under_the_bar(item: Item, value: float, bar: float, items: list[Item]) -> str:
|
||||
blocks = [str(id_) for id_ in sorted(blocked_through(item.id, items))]
|
||||
blocked = f" and the items it blocks, directly or through another ({', '.join(blocks)})" if blocks else ""
|
||||
return f"item {item.id} scores {value:.1f}, under the bar {bar:g}; delete it{blocked}, or mark it with a reason the bar does not apply"
|
||||
|
||||
|
||||
def read_scoring(text: str, lines: list[str], readme: str) -> Scoring | Failure:
|
||||
if ITEMS_HEADER not in lines and "## Items" not in lines:
|
||||
if "## Items" not in lines:
|
||||
return Failure("todo.md is not in the scored-table format; rank_todo.py --help shows a valid one")
|
||||
# A table without C fails, so no chunk starts on an unscored item.
|
||||
if WITHOUT_C in lines:
|
||||
return Failure("todo.md's items table has no C column; add one after S, and score each item's C from 1 to 10 per rank_todo.py --help")
|
||||
goals = readme_goals(readme)
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
@@ -208,16 +244,24 @@ def read_scoring(text: str, lines: list[str], readme: str) -> Scoring | Failure:
|
||||
return Scoring(formula, bar, int(next_id), weights)
|
||||
|
||||
|
||||
def read_items(lines: list[str], scoring: Scoring) -> tuple[list[Item], int] | Failure:
|
||||
"""The items, and the index of the first row in lines."""
|
||||
table = table_rows(lines, ITEMS_HEADER)
|
||||
def read_items(lines: list[str], scoring: Scoring) -> tuple[list[Item], Table] | Failure:
|
||||
"""The items, and the table they were read from."""
|
||||
table = items_table(lines)
|
||||
if table is None:
|
||||
return Failure(f"## Items holds no table whose header opens {HEADER_START}; rank_todo.py --help shows a valid one")
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
if stray_row(lines[table.start + len(table.rows):]):
|
||||
return Failure("## Items holds a row outside its table; keep the rows together under the header")
|
||||
# A table without C fails, so no chunk starts on an unscored item.
|
||||
if "C" not in table.columns:
|
||||
return Failure("todo.md's items table has no C column; add one after S, and score each item's C from 1 to 10 per rank_todo.py --help")
|
||||
# Ranking writes COLUMNS, so it would drop a column it does not know.
|
||||
if unknown := [column for column in table.columns if column not in COLUMNS]:
|
||||
return Failure(f"todo.md's items table has the column {', '.join(unknown)}, which this rank_todo.py does not know; the columns it knows are {', '.join(COLUMNS)}. Rename it, or move this machine to the release that added it")
|
||||
if misplaced := outside_items(lines, table):
|
||||
return misplaced
|
||||
items = []
|
||||
for row in table.rows:
|
||||
item = parse_item(row, scoring.weights)
|
||||
item = parse_item(row, scoring.weights, table.columns)
|
||||
if isinstance(item, Failure):
|
||||
return item
|
||||
items.append(item)
|
||||
@@ -226,13 +270,64 @@ def read_items(lines: list[str], scoring: Scoring) -> tuple[list[Item], int] | F
|
||||
return Failure("two items share an ID")
|
||||
if ids and max(ids) >= scoring.next_id:
|
||||
return Failure(f"item {max(ids)} is not under Next ID {scoring.next_id}; raise Next ID past every ID")
|
||||
return items, table.start
|
||||
for item in items:
|
||||
if unheld := [blocker for blocker in item.blocked_by if blocker >= scoring.next_id]:
|
||||
return Failure(f"item {item.id} is blocked by item {unheld[0]}, which is not under Next ID {scoring.next_id}; name an item the table holds or held")
|
||||
return items, table
|
||||
|
||||
|
||||
def stray_row(after: list[str]) -> bool:
|
||||
"""Whether a table row follows the table before the next ## heading."""
|
||||
def outside_items(lines: list[str], table: Table) -> Failure | None:
|
||||
"""Why the table does not stand alone under ## Items: the table's order is todo.md's only order."""
|
||||
heading = max((index for index in range(table.header) if lines[index].startswith("## ")), default=None)
|
||||
if heading is None:
|
||||
return Failure("the items table sits under no ## heading; move it under ## Items")
|
||||
if lines[heading] != "## Items":
|
||||
return Failure(f"the items table sits under {lines[heading]}, not ## Items; move it under ## Items")
|
||||
after = lines[table.start + len(table.rows):]
|
||||
section = after[:next((index for index, line in enumerate(after) if line.startswith("## ")), len(after))]
|
||||
return any(line.startswith("|") for line in section)
|
||||
if any(line.strip() for line in lines[heading + 1:table.header] + section):
|
||||
return Failure(f"## Items holds text beside its table; an order goes in the scores or the {BLOCKED_BY} column, and a note in the item's detail")
|
||||
return None
|
||||
|
||||
|
||||
def blockers_first(scored: list[tuple[Item, float]]) -> list[tuple[Item, float]] | Failure:
|
||||
"""scored, each blocker that ranks below an item it blocks moved up to just above the first such item; a blocker the table no longer holds was finished or deleted, and is dropped."""
|
||||
held = {item.id: (item, value) for item, value in scored}
|
||||
position = {item.id: index for index, (item, _) in enumerate(scored)}
|
||||
for item, _ in scored:
|
||||
for blocker in item.blocked_by:
|
||||
if blocker in held and held[blocker][0].release > item.release:
|
||||
later, earlier = release_name(held[blocker][0]), release_name(item)
|
||||
return Failure(f"item {item.id}, in release {earlier}, is blocked by item {blocker}, in later release {later}; move item {blocker} to release {earlier} or earlier, or item {item.id} to release {later} or later")
|
||||
result: list[tuple[Item, float]] = []
|
||||
for item, _ in scored:
|
||||
placed = place(item.id, held, position, {placed.id for placed, _ in result}, [])
|
||||
if isinstance(placed, Failure):
|
||||
return placed
|
||||
result += placed
|
||||
return result
|
||||
|
||||
|
||||
def place(id_: int, held: dict[int, tuple[Item, float]], position: dict[int, int], placed: set[int], path: list[int]) -> list[tuple[Item, float]] | Failure:
|
||||
"""The item id_ preceded by those of its blockers not yet placed, each in score order, and theirs before them; path holds the items waiting on this one, to find a loop."""
|
||||
if id_ in path:
|
||||
loop = sorted(path[path.index(id_):])
|
||||
return Failure(f"items {', '.join(map(str, loop[:-1]))} and {loop[-1]} block each other in a loop; drop one of the blockers")
|
||||
if id_ in placed:
|
||||
return []
|
||||
item, value = held[id_]
|
||||
blockers = sorted((blocker for blocker in set(item.blocked_by) if blocker in held), key=position.__getitem__)
|
||||
added: list[tuple[Item, float]] = []
|
||||
for blocker in blockers:
|
||||
before = place(blocker, held, position, placed | {entry.id for entry, _ in added}, [*path, id_])
|
||||
if isinstance(before, Failure):
|
||||
return before
|
||||
added += before
|
||||
return [*added, (dataclasses.replace(item, blocked_by=tuple(sorted(blockers))), value)]
|
||||
|
||||
|
||||
def release_name(item: Item) -> str:
|
||||
return ".".join(str(part) for part in item.release)
|
||||
|
||||
|
||||
def check_citations(items: list[Item], decisions: str) -> Failure | None:
|
||||
@@ -360,8 +455,8 @@ def parse_weights(lines: list[str], goals: list[str]) -> dict[str, float] | Fail
|
||||
return weights
|
||||
|
||||
|
||||
def parse_item(row: str, weights: dict[str, float]) -> Item | Failure:
|
||||
item = parse_row(row)
|
||||
def parse_item(row: str, weights: dict[str, float], columns: tuple[str, ...]) -> Item | Failure:
|
||||
item = parse_row(row, columns)
|
||||
if isinstance(item, Failure):
|
||||
return item
|
||||
if unknown := [goal for goal in item.goals if goal not in weights]:
|
||||
@@ -370,9 +465,8 @@ def parse_item(row: str, weights: dict[str, float]) -> Item | Failure:
|
||||
|
||||
|
||||
def render_item(item: Item, value: float) -> str:
|
||||
release = ".".join(str(part) for part in item.release)
|
||||
scores = " | ".join(str(item.scores[name]) for name in "RSCAG")
|
||||
return f"| {item.id} | {release} | {item.exempt} | {item.tagline} | {scores} | {', '.join(item.goals)} | {value:.1f} |"
|
||||
return f"| {item.id} | {release_name(item)} | {', '.join(map(str, item.blocked_by))} | {item.exempt} | {item.tagline} | {scores} | {', '.join(item.goals)} | {value:.1f} |"
|
||||
|
||||
|
||||
def rank_details(text: str, items: list[Item]) -> str | Failure:
|
||||
|
||||
@@ -23,7 +23,7 @@ def todo(*rows: str, header: str = HEADER) -> str:
|
||||
|
||||
|
||||
def item(id_: int, scores: dict[str, int]) -> Item:
|
||||
return Item(id_, (0, 1, 0), "", f"**Item {id_}.**", scores, ("1",))
|
||||
return Item(id_, (0, 1, 0), "", f"**Item {id_}.**", scores, ("1",), ())
|
||||
|
||||
|
||||
def outcome(id_: int, r: int, s: int, c: int | None, lines: int = 10, rounds: int = 1, findings: tuple[int, int] | None = (0, 0), merged: str = "2026-10-13T10:00:00Z", shipped_with: tuple[int, ...] = ()) -> Outcome:
|
||||
|
||||
+111
-23
@@ -1,6 +1,7 @@
|
||||
import contextlib
|
||||
import io
|
||||
import pathlib
|
||||
import re
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
@@ -10,6 +11,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
from failure import Failure
|
||||
import rank_todo
|
||||
from repo_checks.test_python_floor import ROOT
|
||||
import todo_table
|
||||
|
||||
README = "# P\n\n## Goals\n\n1. Fast.\n2. Correct.\n 1. Tested.\n\n## Audience\n\nMe.\n"
|
||||
|
||||
@@ -33,13 +35,13 @@ TODO = """# todo
|
||||
|
||||
## Items
|
||||
|
||||
| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 1 | 0.2.0 | | **Ship the later thing.** | 1 | 1 | 3 | 9 | 9 | 1 | 0 |
|
||||
| 2 | 0.1.0 | | **Tighten the tests.** | 2 | 4 | 3 | 5 | 5 | 2.1 | 0 |
|
||||
| 3 | 0.1.0 | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 6 | 8 | 2.1, 1 | 0 |
|
||||
| 4 | 0.1.0 | security | **Rotate the leaked key.** | 9 | 2 | 3 | 1 | 1 | 2.1 | 0 |
|
||||
| 5 | 0.1.0 | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 0 |
|
||||
| ID | Release | Blocked by | Exempt | Item | R | S | C | A | G | Goals | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 9 | 9 | 1 | 0 |
|
||||
| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 5 | 5 | 2.1 | 0 |
|
||||
| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 6 | 8 | 2.1, 1 | 0 |
|
||||
| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 9 | 2 | 3 | 1 | 1 | 2.1 | 0 |
|
||||
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 0 |
|
||||
|
||||
## Details
|
||||
|
||||
@@ -63,11 +65,11 @@ class Rank(unittest.TestCase):
|
||||
|
||||
def test_scores_and_sorts_by_release_then_security_then_score_and_orders_the_details_to_match(self):
|
||||
ranked = self.ranked()
|
||||
self.assertIn("""| 4 | 0.1.0 | security | **Rotate the leaked key.** | 9 | 2 | 3 | 1 | 1 | 2.1 | -6.8 |
|
||||
| 3 | 0.1.0 | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 6 | 8 | 2.1, 1 | 23.0 |
|
||||
| 2 | 0.1.0 | | **Tighten the tests.** | 2 | 4 | 3 | 5 | 5 | 2.1 | 10.3 |
|
||||
| 5 | 0.1.0 | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 5.1 |
|
||||
| 1 | 0.2.0 | | **Ship the later thing.** | 1 | 1 | 3 | 9 | 9 | 1 | 34.8 |
|
||||
self.assertIn("""| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 9 | 2 | 3 | 1 | 1 | 2.1 | -6.8 |
|
||||
| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 6 | 8 | 2.1, 1 | 23.0 |
|
||||
| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 5 | 5 | 2.1 | 10.3 |
|
||||
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 5.1 |
|
||||
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 9 | 9 | 1 | 34.8 |
|
||||
""", ranked.text)
|
||||
self.assertTrue(ranked.text.endswith("## Details\n\n### 3. Make it fast, `a | b`.\n\nFast detail.\n\n### 1. Ship the later thing.\n\nLater detail.\n\n## Notes\n\nKept as written.\n"))
|
||||
self.assertEqual(ranked.under_bar, [])
|
||||
@@ -75,14 +77,17 @@ class Rank(unittest.TestCase):
|
||||
|
||||
def test_holds_each_item_a_decision_cites_and_says_how_to_settle_a_finished_one(self):
|
||||
self.assertIsInstance(self.ranked(decisions=DECISIONS + "Until `todo.md` item 4 lands.\n"), rank_todo.Ranked)
|
||||
gone = self.ranked(TODO.replace("| 5 | 0.1.0 | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 0 |\n", ""))
|
||||
gone = self.ranked(TODO.replace("| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 0 |\n", ""))
|
||||
self.assertEqual(gone.reason, "docs/decisions.md cites \"`todo.md` item 5\", which todo.md no longer holds; revise that decision to say what holds now")
|
||||
|
||||
def test_names_each_item_under_the_bar_that_is_not_exempt(self):
|
||||
ranked = self.ranked(TODO.replace("`Bar = 9`", "`Bar = 11`"))
|
||||
self.assertEqual(ranked.under_bar, ["item 2 scores 10.3, under the bar 11; delete it and any item that needs it, or mark it with a reason the bar does not apply"])
|
||||
self.assertEqual(self.ranked(ranked.text.replace("| 2 | 0.1.0 | |", "| 2 | 0.1.0 | principle |")).under_bar, [])
|
||||
self.assertEqual(self.ranked(ranked.text.replace("| 2 | 0.1.0 | |", "| 2 | 0.1.0 | owner |")).under_bar, [])
|
||||
self.assertEqual(ranked.under_bar, ["item 2 scores 10.3, under the bar 11; delete it, or mark it with a reason the bar does not apply"])
|
||||
self.assertEqual(self.ranked(TODO.replace("`Bar = 9`", "`Bar = 10.3`")).under_bar, [])
|
||||
blocking = self.ranked(TODO.replace("`Bar = 9`", "`Bar = 11`").replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 2 |").replace("| 5 | 0.1.0 | |", "| 5 | 0.1.0 | 3 |"))
|
||||
self.assertEqual(blocking.under_bar, ["item 2 scores 10.3, under the bar 11; delete it and the items it blocks, directly or through another (3, 5), or mark it with a reason the bar does not apply"])
|
||||
self.assertEqual(self.ranked(ranked.text.replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | principle |")).under_bar, [])
|
||||
self.assertEqual(self.ranked(ranked.text.replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | owner |")).under_bar, [])
|
||||
|
||||
def test_reads_goals_and_sub_goals_in_reading_order(self):
|
||||
self.assertEqual(rank_todo.readme_goals(README), ["1", "2", "2.1"])
|
||||
@@ -104,27 +109,110 @@ class Rank(unittest.TestCase):
|
||||
self.assertEqual(self.ranked(legacy, decisions="").reason, "todo.md's items table has no C column; add one after S, and score each item's C from 1 to 10 per rank_todo.py --help")
|
||||
|
||||
def test_refuses_a_file_off_the_format(self):
|
||||
row = "| 2 | 0.1.0 | | **Tighten the tests.** | 2 | 4 | 3 | 5 | 5 | 2.1 | 0 |"
|
||||
row = "| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 5 | 5 | 2.1 | 0 |"
|
||||
broken = {
|
||||
row: row.replace("0.1.0", "0.1"),
|
||||
"| 2 | 4 | 3 | 5 | 5 |": "| 2 | 4 | 11 | 5 | 5 |",
|
||||
row + "\n": row.replace("5 | 5", "5 | ²") + "\n",
|
||||
"| 2.1 | 0 |\n\n## Details": "| 2.1 | 0 |\n\n| 9 | 0.1.0 | | **Stray.** | 1 | 1 | 3 | 1 | 1 | 1 | 0 |\n\n## Details",
|
||||
"| 4 | 0.1.0 | security |": "| 4 | 0.1.0 | later |",
|
||||
"| 5 | 0.1.0 | decision |": "| 5 | 0.1.0 | |",
|
||||
"| 2.1 | 0 |\n\n## Details": "| 2.1 | 0 |\n\n| 9 | 0.1.0 | | | **Stray.** | 1 | 1 | 3 | 1 | 1 | 1 | 0 |\n\n## Details",
|
||||
"| 4 | 0.1.0 | | security |": "| 4 | 0.1.0 | | later |",
|
||||
"| 5 | 0.1.0 | | decision |": "| 5 | 0.1.0 | | |",
|
||||
"`Next ID = 6`": "`Next ID = 5`",
|
||||
"`Next ID = 6`\n": "`Next ID = 6.5`\n",
|
||||
"| 4 | 0.1.0 | security | **Rotate": "| 4 | 0.1.0 | decision | **Rotate",
|
||||
"| 4 | 0.1.0 | | security | **Rotate": "| 4 | 0.1.0 | | decision | **Rotate",
|
||||
"Fast detail.": "```\n## Goals\n```",
|
||||
"### 3. Make it fast.": "### 7. Make it fast.",
|
||||
"`Bar = 9`": "`Bar = nan`",
|
||||
"## Items\n\n| ID | Release | Exempt |": "## Plan\n\n| ID | Release |",
|
||||
"## Items\n\n| ID | Release | Blocked by |": "## Plan\n\n| ID | Release |",
|
||||
}
|
||||
for old, new in broken.items():
|
||||
with self.subTest(new=new):
|
||||
self.assertIsInstance(self.ranked(TODO.replace(old, new)), Failure)
|
||||
|
||||
|
||||
class Blockers(unittest.TestCase):
|
||||
def ranked(self, todo):
|
||||
return rank_todo.rank(todo, README, DECISIONS)
|
||||
|
||||
def test_ranks_each_blocker_just_above_the_first_item_it_blocks(self):
|
||||
ranked = self.ranked(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5, 2 |"))
|
||||
self.assertIn("""| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 9 | 2 | 3 | 1 | 1 | 2.1 | -6.8 |
|
||||
| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 5 | 5 | 2.1 | 10.3 |
|
||||
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 5.1 |
|
||||
| 3 | 0.1.0 | 2, 5 | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 6 | 8 | 2.1, 1 | 23.0 |
|
||||
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 9 | 9 | 1 | 34.8 |
|
||||
""", ranked.text)
|
||||
self.assertEqual(self.ranked(ranked.text), ranked)
|
||||
|
||||
def test_ranks_an_items_blockers_in_score_order(self):
|
||||
rows = [line.split(" | ")[0] for line in self.ranked(TODO.replace("| 4 | 0.1.0 | |", "| 4 | 0.1.0 | 2, 3 |")).text.splitlines() if re.match(r"\| \d \| 0\.\d\.0 \|", line)]
|
||||
self.assertEqual(rows, ["| 3", "| 2", "| 4", "| 5", "| 1"])
|
||||
|
||||
def test_ranks_a_blocker_above_its_blockers_blocker_and_takes_one_in_an_earlier_release_as_it_is(self):
|
||||
chained = TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5 |").replace("| 5 | 0.1.0 | |", "| 5 | 0.1.0 | 2 |").replace("| 1 | 0.2.0 | |", "| 1 | 0.2.0 | 3 |")
|
||||
rows = [line.split(" | ")[0] for line in self.ranked(chained).text.splitlines() if re.match(r"\| \d \| 0\.\d\.0 \|", line)]
|
||||
self.assertEqual(rows, ["| 4", "| 2", "| 5", "| 3", "| 1"])
|
||||
|
||||
def test_drops_a_blocker_the_table_no_longer_holds_as_finished(self):
|
||||
finished = TODO.replace("| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 9 | 2 | 3 | 1 | 1 | 2.1 | 0 |\n", "").replace("| 2 | 0.1.0 | |", "| 2 | 0.1.0 | 4 |")
|
||||
ranked = self.ranked(finished)
|
||||
self.assertIn("| 2 | 0.1.0 | | | **Tighten the tests.**", ranked.text)
|
||||
self.assertEqual(ranked.dropped, ["item 2: dropped 4 from its Blocked by; the table no longer holds it"])
|
||||
self.assertEqual(self.ranked(ranked.text).dropped, [])
|
||||
|
||||
def test_refuses_a_blocker_in_a_later_release_a_loop_and_an_id_past_next_id(self):
|
||||
cases = {
|
||||
"| 3 | 0.1.0 | 1 |": "item 3, in release 0.1.0, is blocked by item 1, in later release 0.2.0; move item 1 to release 0.1.0 or earlier, or item 3 to release 0.2.0 or later",
|
||||
"| 3 | 0.1.0 | 3 |": "item 3 is blocked by itself; drop 3 from its Blocked by",
|
||||
"| 3 | 0.1.0 | 9 |": "item 3 is blocked by item 9, which is not under Next ID 6; name an item the table holds or held",
|
||||
"| 3 | 0.1.0 | 6 |": "item 3 is blocked by item 6, which is not under Next ID 6; name an item the table holds or held",
|
||||
}
|
||||
for cell, reason in cases.items():
|
||||
with self.subTest(cell=cell):
|
||||
self.assertEqual(self.ranked(TODO.replace("| 3 | 0.1.0 | |", cell)), Failure(reason))
|
||||
looped = TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 2 |").replace("| 2 | 0.1.0 | |", "| 2 | 0.1.0 | 5 |").replace("| 5 | 0.1.0 | |", "| 5 | 0.1.0 | 3 |")
|
||||
self.assertEqual(self.ranked(looped), Failure("items 2, 3 and 5 block each other in a loop; drop one of the blockers"))
|
||||
self.assertEqual(self.ranked(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 2 and 5 |")), Failure("item 3's Blocked by '2 and 5' is not empty or IDs separated by \", \""))
|
||||
|
||||
def test_adds_the_column_to_a_table_without_it(self):
|
||||
without = TODO.replace("| Blocked by ", "").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|")
|
||||
without = re.sub(r"\| (\d) \| (0\.[12]\.0) \| \| ", r"| \1 | \2 | ", without)
|
||||
self.assertEqual(self.ranked(without), self.ranked(TODO))
|
||||
|
||||
def test_refuses_a_column_it_does_not_know_rather_than_drop_it_and_asks_for_c_beside_blocked_by(self):
|
||||
extra = TODO.replace("| Goals | Score |\n|---|", "| Goals | Score | Later |\n|---|---|").replace(" | 0 |\n", " | 0 | x |\n")
|
||||
self.assertEqual(self.ranked(extra), Failure("todo.md's items table has the column Later, which this rank_todo.py does not know; the columns it knows are ID, Release, Blocked by, Exempt, Item, R, S, C, A, G, Goals, Score. Rename it, or move this machine to the release that added it"))
|
||||
self.assertEqual([item.id for item in todo_table.items(extra)], [1, 2, 3, 4, 5])
|
||||
without_c = TODO.replace("| R | S | C |", "| R | S |").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|")
|
||||
without_c = re.sub(r"(\*\* \| \d+ \| \d+) \| \d+ \|", r"\1 |", without_c)
|
||||
self.assertEqual(self.ranked(without_c).reason, "todo.md's items table has no C column; add one after S, and score each item's C from 1 to 10 per rank_todo.py --help")
|
||||
|
||||
def test_refuses_text_under_items_beside_the_table(self):
|
||||
last = TODO.split("\n## Details")[0] + "\n"
|
||||
self.assertIsInstance(self.ranked(last), rank_todo.Ranked)
|
||||
beside = Failure("## Items holds text beside its table; an order goes in the scores or the Blocked by column, and a note in the item's detail")
|
||||
for ordered in (TODO.replace("## Items\n\n", "## Items\n\nRelease 0.1.0 takes item 5 first.\n\n"), TODO.replace("## Items\n\n", "## Items\nTake item 5 first.\n\n"), TODO.replace("| 2.1 | 0 |\n\n## Details", "| 2.1 | 0 |\n\nTake item 5 first.\n\n## Details"), last + "\nTake item 5 first.\n"):
|
||||
with self.subTest(ordered=ordered[-60:]):
|
||||
self.assertEqual(self.ranked(ordered), beside)
|
||||
|
||||
def test_refuses_an_items_table_outside_items_a_second_one_and_a_repeated_column(self):
|
||||
self.assertEqual(self.ranked(TODO.replace("## Items\n", "## Plan\n")).reason, "todo.md is not in the scored-table format; rank_todo.py --help shows a valid one")
|
||||
outside = TODO.replace("## Items\n\n", "## Items\n\n## Rows\n\n")
|
||||
self.assertEqual(self.ranked(outside).reason, "the items table sits under ## Rows, not ## Items; move it under ## Items")
|
||||
table = TODO[TODO.index("| ID | Release |"):TODO.index("\n\n## Details")] + "\n"
|
||||
above = table + "\n" + TODO.replace(table, "")
|
||||
self.assertEqual(self.ranked(above).reason, "the items table sits under no ## heading; move it under ## Items")
|
||||
header = "| ID | Release | Blocked by | Exempt | Item | R | S | C | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
|
||||
self.assertEqual(todo_table.items(TODO + "\n" + header.replace("| Score |", "| Later |")), Failure("todo.md holds 2 tables whose header opens | ID | Release |; keep one items table"))
|
||||
repeated = TODO.replace("| Goals | Score |\n|---|", "| Goals | Score | Exempt |\n|---|---|").replace(" | 0 |\n", " | 0 | x |\n")
|
||||
self.assertEqual(todo_table.items(repeated), Failure("todo.md's items table names the column Exempt twice; keep one"))
|
||||
|
||||
def test_reads_an_empty_table_and_fails_on_a_header_with_no_divider(self):
|
||||
header = "| ID | Release | Blocked by | Exempt | Item | R | S | C | A | G | Goals | Score |"
|
||||
self.assertEqual(todo_table.items(f"## Items\n\n{header}\n|---|---|---|---|---|---|---|---|---|---|---|---|\n\n## Details\n"), [])
|
||||
self.assertEqual(todo_table.items(f"## Items\n\n{header}"), Failure(f"the table under {header} has no |---| divider line"))
|
||||
|
||||
|
||||
class Main(unittest.TestCase):
|
||||
def run_main(self, *argv):
|
||||
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
@@ -160,4 +248,4 @@ class ThisRepo(unittest.TestCase):
|
||||
def test_todo_md_is_ranked_with_nothing_under_the_bar(self):
|
||||
text = (ROOT / "todo.md").read_text(encoding="utf-8")
|
||||
ranked = rank_todo.rank(text, (ROOT / "README.md").read_text(encoding="utf-8"), (ROOT / "docs" / "decisions.md").read_text(encoding="utf-8"))
|
||||
self.assertEqual(ranked, rank_todo.Ranked(text, []))
|
||||
self.assertEqual(ranked, rank_todo.Ranked(text, [], []))
|
||||
|
||||
+63
-23
@@ -6,10 +6,16 @@ from failure import Failure
|
||||
# Each of R, S, C, A and G runs from 1 to TOP_SCORE.
|
||||
TOP_SCORE = 10
|
||||
EXEMPTIONS = ("", "decision", "defect", "owner", "principle", "question", "security")
|
||||
COLUMNS = ("ID", "Release", "Exempt", "Item", "R", "S", "C", "A", "G", "Goals", "Score")
|
||||
# The column naming the items that block an item: each must be done before the item starts.
|
||||
BLOCKED_BY = "Blocked by"
|
||||
# The columns rank_todo writes, in order. A reader takes cells by column name, so it reads a table from before BLOCKED_BY or C joined, or with a column a later release adds.
|
||||
COLUMNS = ("ID", "Release", BLOCKED_BY, "Exempt", "Item", "R", "S", "C", "A", "G", "Goals", "Score")
|
||||
ITEMS_HEADER = "| " + " | ".join(COLUMNS) + " |"
|
||||
# Tables in git history from before C joined lack it; items() still parses them, though rank_todo refuses one in a checkout.
|
||||
WITHOUT_C = "| " + " | ".join(column for column in COLUMNS if column != "C") + " |"
|
||||
DIVIDER = "|" + "---|" * len(COLUMNS)
|
||||
# The columns without which no row can be read; a missing BLOCKED_BY reads as blocked by nothing, a missing C as no C.
|
||||
NEEDED = ("ID", "Release", "Exempt", "Item", "R", "S", "A", "G", "Goals")
|
||||
# How the items table's header opens, which tells it from the goal weights table.
|
||||
HEADER_START = "| ID | Release |"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -20,6 +26,7 @@ class Item:
|
||||
tagline: str
|
||||
scores: dict[str, int]
|
||||
goals: tuple[str, ...]
|
||||
blocked_by: tuple[int, ...]
|
||||
|
||||
@property
|
||||
def risk_and_complexity(self) -> int:
|
||||
@@ -29,39 +36,67 @@ class Item:
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Table:
|
||||
"""Body rows of a markdown table, and the index of the first row in the file's lines."""
|
||||
start: int
|
||||
"""A markdown table: the index of its header in the file's lines, its column names, and its body rows."""
|
||||
header: int
|
||||
columns: tuple[str, ...]
|
||||
rows: list[str]
|
||||
|
||||
@property
|
||||
def start(self) -> int:
|
||||
"""The index of the first body row, below the header and the divider."""
|
||||
return self.header + 2
|
||||
|
||||
|
||||
def items(todo: str) -> list[Item] | None | Failure:
|
||||
"""Each row of a todo.md's items table, with C or without it; None where todo.md holds no items table."""
|
||||
lines = todo.splitlines()
|
||||
headers = [header for header in (ITEMS_HEADER, WITHOUT_C) if header in lines]
|
||||
if not headers:
|
||||
return None
|
||||
table = table_rows(lines, headers[0])
|
||||
if isinstance(table, Failure):
|
||||
"""Each row of a todo.md's items table; None where todo.md holds no items table."""
|
||||
table = items_table(todo.splitlines())
|
||||
if table is None or isinstance(table, Failure):
|
||||
return table
|
||||
found = []
|
||||
for row in table.rows:
|
||||
item = parse_row(row, headers[0])
|
||||
item = parse_row(row, table.columns)
|
||||
if isinstance(item, Failure):
|
||||
return item
|
||||
found.append(item)
|
||||
return found
|
||||
|
||||
|
||||
def items_table(lines: list[str]) -> Table | None | Failure:
|
||||
"""The table whose header opens with HEADER_START; None where there is none."""
|
||||
headers = [line for line in lines if line.startswith(HEADER_START)]
|
||||
if not headers:
|
||||
return None
|
||||
if len(headers) > 1:
|
||||
return Failure(f"todo.md holds {len(headers)} tables whose header opens {HEADER_START}; keep one items table")
|
||||
table = table_rows(lines, headers[0])
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
if repeated := sorted({column for column in table.columns if table.columns.count(column) > 1}):
|
||||
return Failure(f"todo.md's items table names the column {', '.join(repeated)} twice; keep one")
|
||||
if missing := [column for column in NEEDED if column not in table.columns]:
|
||||
return Failure(f"todo.md's items table has no {', '.join(missing)} column; rank_todo.py --help shows a valid one")
|
||||
return table
|
||||
|
||||
|
||||
def waiting(found: list[Item]) -> set[int]:
|
||||
"""The IDs of the items that wait: each marked question, or blocked by an item the table still holds. Row order does not change the result."""
|
||||
held = {item.id for item in found}
|
||||
return {item.id for item in found if item.exempt == "question" or held.intersection(item.blocked_by)}
|
||||
|
||||
|
||||
def table_rows(lines: list[str], header: str) -> Table | Failure:
|
||||
if lines.count(header) != 1:
|
||||
return Failure(f"todo.md needs the table header {header} once")
|
||||
start = lines.index(header) + 2
|
||||
if start > len(lines) or not re.fullmatch(r"\|(-+\|)+", lines[start - 1].replace(" ", "")):
|
||||
at = lines.index(header)
|
||||
if at + 2 > len(lines) or not re.fullmatch(r"\|(-+\|)+", lines[at + 1].replace(" ", "")):
|
||||
return Failure(f"the table under {header} has no |---| divider line")
|
||||
end = start
|
||||
end = at + 2
|
||||
while end < len(lines) and lines[end].startswith("|"):
|
||||
end += 1
|
||||
return Table(start, lines[start:end])
|
||||
columns = cells(header, header.count("|") - 1)
|
||||
if isinstance(columns, Failure):
|
||||
return columns
|
||||
return Table(at, tuple(columns), lines[at + 2:end])
|
||||
|
||||
|
||||
def cells(row: str, count: int) -> list[str] | Failure:
|
||||
@@ -69,13 +104,12 @@ def cells(row: str, count: int) -> list[str] | Failure:
|
||||
return found if len(found) == count else Failure(f"this row needs {count} cells: {row}")
|
||||
|
||||
|
||||
def parse_row(row: str, header: str = ITEMS_HEADER) -> Item | Failure:
|
||||
"""An item row under header, every cell checked but the goals it cites."""
|
||||
names = header.strip("| ").split(" | ")
|
||||
found = cells(row, len(names))
|
||||
def parse_row(row: str, columns: tuple[str, ...]) -> Item | Failure:
|
||||
"""An item row under columns, every cell checked but the goals it cites."""
|
||||
found = cells(row, len(columns))
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
named = dict(zip(names, found))
|
||||
named = dict(zip(columns, found))
|
||||
id_, release, exempt, tagline = named["ID"], named["Release"], named["Exempt"], named["Item"]
|
||||
if not re.fullmatch(r"[0-9]+", id_) or int(id_) < 1:
|
||||
return Failure(f"the ID {id_!r} is not a positive whole number: {row}")
|
||||
@@ -92,6 +126,12 @@ def parse_row(row: str, header: str = ITEMS_HEADER) -> Item | Failure:
|
||||
if not re.fullmatch(r"[0-9]+", named[name]) or not 1 <= int(named[name]) <= TOP_SCORE:
|
||||
return Failure(f"item {id_}'s {name} {named[name]!r} is not a whole number from 1 to {TOP_SCORE}")
|
||||
scores[name] = int(named[name])
|
||||
blockers = named.get(BLOCKED_BY, "")
|
||||
if not re.fullmatch(r"([0-9]+(, [0-9]+)*)?", blockers):
|
||||
return Failure(f"item {id_}'s {BLOCKED_BY} {blockers!r} is not empty or IDs separated by \", \"")
|
||||
blocked_by = tuple(int(blocker) for blocker in blockers.split(", ") if blocker)
|
||||
if int(id_) in blocked_by:
|
||||
return Failure(f"item {id_} is blocked by itself; drop {id_} from its {BLOCKED_BY}")
|
||||
cited = tuple(goal.strip() for goal in named["Goals"].split(","))
|
||||
major, minor, patch = (int(part) for part in release.split("."))
|
||||
return Item(int(id_), (major, minor, patch), exempt, tagline, scores, cited)
|
||||
return Item(int(id_), (major, minor, patch), exempt, tagline, scores, cited, blocked_by)
|
||||
|
||||
@@ -1845,3 +1845,97 @@ Junior A, decided by:
|
||||
|
||||
- Self-sufficiency, Overall: `bin/loop_claude/cycle/judge.py:149` `run_judge`: the docstring lists the three quote checks, how strictly each is checked and what a misquote does, where the base made the reader work out why grounded and verbatim differ
|
||||
- Self-sufficiency: `bin/loop_claude/routing.py:55` `escalation_cap`: the limit is its own named function whose docstring says why it counts from item_rung, and `stepped` names `counted_out` and `escalates`
|
||||
|
||||
## 2026-10-15T21:39:57Z, PR #280 at 9af5ee7, against 545f3c3
|
||||
|
||||
Ruling: same
|
||||
|
||||
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
||||
|---|---|---|---|---|---|
|
||||
| Mid A | same | better | same | same | better |
|
||||
| Inherited architect | same | same | worse | same | same |
|
||||
| Maintainability senior | same | better | same | same | same |
|
||||
| Junior A | same | better | same | same | better |
|
||||
|
||||
Mid A, decided by:
|
||||
|
||||
- Locality, Overall: `bin/todo_table.py:64` `items_table`: reads the items table once and takes each cell by column name, where the base needed a second header constant that `items`, `read_scoring` and `read_items` each had to know
|
||||
- Locality, Overall: `bin/todo_table.py:81` `waiting`: names the rule for skipping an item once, used by `routed_item`, where the base wrote it inline
|
||||
- Locality: `bin/loop_claude/routing.py:84` `judge_rung`: calls `item_rung`, so the judge's and the worker's rung share one definition
|
||||
|
||||
Inherited architect, decided by:
|
||||
|
||||
- Shape: `bin/rank_todo.py:311` `place`: five parameters, recursion, a set rebuilt per call, and a name that hides that it also finds loops and prunes `blocked_by`
|
||||
- Locality: `bin/rank_todo.py:194` `rank`: the rule that a blocker that left the table no longer counts is worked out here, in `place` and in `todo_table.waiting`
|
||||
- Locality: `bin/rank_todo.py:274` `read_items`: the Blocked by checks are spread over `parse_row`, `read_items`, `blockers_first` and `place`
|
||||
- Locality, Shape: `bin/todo_table.py:64` `items_table`: cells read by column name, with the C check beside the column, where the base split the header text by position
|
||||
- Locality: `bin/loop_claude/routing.py:16` `routed_item`: asks the pure `waiting`, where the base leaned on an order rank_todo kept
|
||||
- Shape: `bin/rank_todo.py:187` `rank`: the two-line header replacement keeps `found.start` right only because header and divider are two lines, and the module's fan-out grows past 25 functions
|
||||
|
||||
Maintainability senior, decided by:
|
||||
|
||||
- Locality: `bin/todo_table.py:107` `parse_row`: reads each cell by the column name in the table's own header, where the base found the table by exact header strings kept in mind across two modules
|
||||
- Locality: `bin/rank_todo.py:247` `read_items`: the C and unknown-column checks sit where the table is read, where the base checked raw lines in the formula reader
|
||||
- Locality: `bin/rank_todo.py:311` `place`: a partial offset; dropping a blocker that left the table happens in `place`, `blockers_first` and `rank`, and `place` threads five parameters
|
||||
- Locality: `bin/loop_claude/routing.py:16` `routed_item`: defers to the named, order-free `todo_table.waiting`, where the base leaned on rank_todo's order
|
||||
|
||||
Junior A, decided by:
|
||||
|
||||
- Locality, Overall: `bin/todo_table.py:64` `items_table`: one function finds the table, checks repeated and missing columns, and rows are read by column name, where the base kept two header variants in step
|
||||
- Locality: `bin/rank_todo.py:247` `read_items`: the table's shape checks sit where the table is read, where the base rejected a table in the scoring reader
|
||||
- Locality: `bin/loop_claude/routing.py:16` `routed_item`: the waiting rule is one named function, `todo_table.waiting`
|
||||
- Locality: `bin/loop_claude/routing.py:84` `judge_rung`: builds the judge's rung from `item_rung`, one definition fewer to keep in step
|
||||
- Locality: `bin/rank_todo.py:311` `place`: the counterweight; a two-stage ranking with a five-parameter recursion, and the dropped-blocker rule written three times
|
||||
|
||||
## 2026-10-15T21:39:57Z, PR #280 at 9af5ee7
|
||||
|
||||
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
||||
|---|---|---|---|---|---|
|
||||
| Junior A | 7 | 6 | 6 | 6 | 6 |
|
||||
| Mid A | 7 | 6.5 | 6.5 | 6 | 6.5 |
|
||||
| Maintainability senior | 7 | 6 | 6 | 7 | 6.5 |
|
||||
| Inherited architect | 7 | 7 | 6 | 7 | 6.5 |
|
||||
| Mean | 7.00 | 6.38 | 6.13 | 6.50 | 6.38 |
|
||||
|
||||
Junior A, hardest first:
|
||||
|
||||
- `bin/loop_claude/routing.py:64` `stepped`: six one-line helpers held at once to learn the next cycle's rung, each docstring defined by the others
|
||||
- `bin/loop_claude/cycle/prompts.py:40` `escalation`: the worker's prompt glued from space-led fragments over several cases, with no example of the final string
|
||||
- `bin/comprehension_history.py:106` `latest_places`: hand-shaped markdown read back by regexes, an in-a-list flag and history from before PR #255
|
||||
- `bin/loop_claude/cycle/judge.py:149` `run_judge`: three quote checks with three consequences, and a JUDGE_RULES prose wall built from constants in other modules
|
||||
- `bin/transcript_archive/outcomes.py:53` `workers`: a chunk resumes its rung by regex-parsing archive prose, with the verdict strings repeated by hand
|
||||
- `bin/routing_figures/measure.py:77` `measured`: timestamps cut to 19 characters, tools carried between iterations, totals into four counters
|
||||
- `bin/stability_replay/rounds.py:70` `reviewed_path`: guesses a removed worktree from absolute paths with a first-prefix-gone rule
|
||||
- `bin/rank_todo.py:311` `place`: recursive placement with a loop-detecting path and a placed set rebuilt per call
|
||||
|
||||
Mid A, hardest first:
|
||||
|
||||
- `bin/loop_claude/routing.py:64` `stepped`: five functions pick a rung from four reference points, and the why is a pointer to the decision log
|
||||
- `bin/loop_claude/cycle/prompts.py:40` `escalation`: conditional f-string fragments relying on leading spaces and lstrip, output unknowable from the code
|
||||
- `bin/transcript_archive/outcomes.py:53` `workers`: resume rests on a parsed Worker line, and NAMES_A_WORKER repeats the verdicts as literals
|
||||
- `bin/comprehension_history.py:106` `latest_places`: a five-clause docstring, table-order dependence and an implicit line state machine
|
||||
- `skills/larv-review/SKILL.md:63` "Round cap": the fourth-round rule lives in cross-referenced prose that no code enforces
|
||||
- `bin/routing_figures/measure.py:77` `measured`: dense one-liners and a timestamp format assumed silently in `rung_at`
|
||||
- `bin/rule_hook/override_log.py:36` `this_chunks`: which overrides belong to the chunk rests on reflog semantics
|
||||
- `bin/rank_todo.py:311` `place`: recursive blocker placement with a loop-detecting path, resolved after one reread
|
||||
|
||||
Maintainability senior, hardest first:
|
||||
|
||||
- `bin/loop_claude/routing.py:64` `stepped`: seven functions over three inputs, and the never-down and two-above rules emerge only from their composition
|
||||
- `bin/loop_claude/cycle/prompts.py:29` `off_the_projects_rung`: prompt fragments and rung arithmetic over three branches in each of three functions
|
||||
- `bin/loop_claude/loop/main.py:1` "loop-claude --help": a 120-line contract, the only end-to-end routing story, with no pointers to the modules it maps onto
|
||||
- `skills/larv-review/SKILL.md:63` "Round cap": which passes rerun after a fix spans the pass table, the fix clauses and the cap
|
||||
- `bin/model_routing/ladder.py:19` `Rung.__str__`: the archive's rung format is written and parsed across four files, and a reworded string breaks resume
|
||||
- `bin/routing_figures/measure.py:77` `measured`: tokens charged to the previous message's tools, and timestamps cut to compare with stamps
|
||||
- `bin/shell_command.py:31` `segments`: a hand-rolled splitter whose words after a redirect target open a new segment
|
||||
- `bin/comprehension_history.py:106` `latest_places`: a four-clause docstring, a seat name split from a label and a votes table assumed first
|
||||
|
||||
Inherited architect, would restructure first:
|
||||
|
||||
- `bin/round_titles.py:4` `CAP`: the round cap lives here for its regex's other readers, and no program enforces it; `SKILL.md` "Round cap" does in prose
|
||||
- `bin/loop_claude/effects.py:18` `Effects`: the process shell, `Stop` and the models-file reader that three other tools reach into loop_claude for
|
||||
- `bin/git_repo.py:8` `git`: one of seven ways to run git, alongside `metric_bench/main.py:150`, `stability_replay/main.py:202` and `reading_cost/main.py:114`
|
||||
- `bin/score_outcomes/outcomes.py:156` `outcomes_of`: shares its name and module name with `transcript_archive`'s, with a different meaning
|
||||
- `bin/loop_claude/routing.py:28` `first_route`: the parameter anchor means the project's rung, re-glossed in nearly every docstring
|
||||
- `bin/model_routing/ladder.py:19` `Rung.__str__`: parsed back to resume routing, so a wording change silently re-routes chunks
|
||||
- `bin/loop_claude/cycle/prompts.py:25` `routed_by`: the routing policy stated a third time, beside main.py's help and routing.py's logic
|
||||
|
||||
+6
-8
@@ -4,11 +4,7 @@
|
||||
|
||||
2026-09-20, lilleman. Serves goal 1. Across six projects scored with the four seats, Locality or Self-sufficiency was the lowest dimension at every seat and Navigation at none, so a layout fix would not lift a project under the floor. Valid while the scoring run keeps those four seats.
|
||||
|
||||
2026-10-13, lilleman: PR #257's scoring run found Shape lowest, at 6.25, so release 0.1.0's chunks take the Shape items, `todo.md` items 114, 124 and 125, before the release's other items, whatever their scores.
|
||||
|
||||
2026-10-14, lilleman: the Shape items moved to release 0.2.0 with the release's other readability items, so 0.1.0 ships the model router first; they still go before 0.2.0's other items.
|
||||
|
||||
2026-10-15, lilleman: the Shape items moved to release 0.3.0 with the readability items, so 0.2.0 ships the outcome measures first; they still go before 0.3.0's other items.
|
||||
2026-10-15, lilleman: an item that lifts the lowest dimension scores G 9, since the lowest dimension caps the overall and lifting it is worth the most to the floor. Today that ranks the Shape items, `todo.md` items 114, 124 and 125, first in release 0.3.0: PR #257's scoring run found Shape lowest, at 6.25. When `todo.md` item 148 replaces G, the chunk that ships it carries this rule into the new score.
|
||||
|
||||
## loop-claude: a judge decides each interrupt and each quoted answer from the transcript, the README's premises, `AGENTS.md`, `docs/decisions.md`, `~/.claude/CLAUDE.md`, `~/.claude/rules/` and larv-review's standards, and holds a chunk open while an answer the human typed in it is recorded nowhere; the worker's own account of which goal settles a choice decides nothing
|
||||
|
||||
@@ -124,12 +120,14 @@ Valid while the ladder orders its rungs by competence.
|
||||
|
||||
2026-10-02, lilleman. Serves goal 4, which keeps credentials, transcripts and memory files off the remote; a private project's name and commit ids are none of those. Valid while the bench names only cases and commits, never their code or results.
|
||||
|
||||
## todo.md: one table of items scored by the formula and goal weights it states, held to its bar, ranked by `bin/rank_todo.py`
|
||||
## todo.md: one table of items scored by the formula and goal weights it states, held to its bar, ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; the table's order is the plan's only order
|
||||
|
||||
2026-10-02, lilleman. Serves goal 1: findings were filed faster than chunks closed them, so the plan grew without telling what mattered. Each item is scored as `~/.claude/rules/todo-items.md` says; this repo's formula counts value highest and size least. An item under the bar is not kept; this repo's bar started at 10 and was set to 9 the same day, purging the 17 items under it. An Exempt cell keeps a row past the bar where a rule needs it kept. lilleman retired the two decisions whose plans the purge removed: the stats line in the transcript archive, and three benches before a workflow change merges. A finding under the bar is recorded nowhere, so a later review may raise it again, and the run rescores it. That costs one scoring; a ledger of dropped findings would regrow the list the bar caps. larv-review's "Round cap" → "Done" counts a finding named under the bar as settled, so one raised again holds no pass open. `rank_todo.py --check` is part of larv-review's gate, since only a check keeps the stored Score from going stale. The format is mandatory in every project, as the premises are (goal 1.3); the formula, bar and weights are each project's own. A script ranks the table so a re-rank after each addition or edit is deterministic and cheap. A 🟡 against a technical principle is exempt as `principle`, because its audience value scores low and the bar would drop every one. A 🟢 against a principle is scored like any other finding. 2026-10-08, lilleman: the goal weights in `todo.md` depart from an even spread by position, which would weigh goal 4, leaking nothing, at 0.11. Valid while one human sets the bar and reads the ranking, and while the items marked `principle` stay few enough to rank.
|
||||
|
||||
2026-10-15, lilleman: the scores get a researched method, which `todo.md` items 146, 148, 149, 150, 151 and 152 build; the evidence is in `docs/scoring-and-goals-research.md`. R becomes L + E + I − 2: the chance the change holds a defect, set first by its size; the chance the defect escapes tests, review and monitoring; and the worst impact dimension, each about ×10 per level. I5, irreversible, holds R at 7 or more, and I4 at 5 or more, since a severe enough consequence outranks how unlikely it is. C goes from every table and tool: what it scored beyond size, spread and novelty, which L already holds, is complexity, which adds almost nothing once size is accounted for. A task's R alone then picks its rung. Items rank by V / C, value per cost: C is 2^S, and V sums each cited achieve goal's sum-reciprocal weight times how far the item moves it. A goes, and the Audience says whose value the goals serve. R stays out of the ranking and sets how carefully an item is done; an item that lowers risk scores it as value. Each release fills by priority up to a capacity it states, in place of the bar. Each README goal is `maintain`, which vetoes an item that breaks it, or `achieve`, with a signal, a counter-signal and a one-line reason, and each project keeps settled decisions to test its goals against. Until these items ship, the formula and bar above hold.
|
||||
|
||||
2026-10-15, lilleman. Serves goal 1.4: loop-claude routes a chunk's first cycle on the item the chunk takes (`routing: one ladder`). An item lists the items that must be done before it starts in a Blocked by column, and `rank_todo.py` ranks each blocker above every item it blocks. The table's order is `todo.md`'s only order: `rank_todo.py` fails on text beside the table under `## Items`, since a prose order there, "Release 0.3.0 takes items 125, 114 and 124 first", contradicted the table and loop-claude could not read it. A decision that wants an order sets the scores instead. An item waits while it is marked `question` or a blocker of it is still in the table, whatever the rows' order, so a release's first row that does not wait is the item a chunk takes. A blocker the table no longer holds was finished or deleted, and is dropped, so the cell shows what still blocks. A panel of three readers seated as lilleman picked the spelling: two ranked "Blocked by" first, as the cell lists only what still blocks, and all three chose bare IDs such as `12, 14` in a column right after Release, read before the tagline and kept apart from the scores. `rank_todo.py` adds the column to a table without it. The tools read cells by column name, so a later column leaves a reader on an older release working; `rank_todo.py`, which writes every column, fails on one it does not know rather than drop it.
|
||||
|
||||
## 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 R + C 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).
|
||||
@@ -206,7 +204,7 @@ A model off the ladder routes nothing: claude runs it at the effort its settings
|
||||
|
||||
The worker delegates a task only when it needs just the task's conclusion: a search or read across many files, or work independent enough to run in parallel. Edits, and whatever it must check line by line, stay in its own thread, since it would read a delegated diff again to check it. Measured over archived worker transcripts, subagent reports cost a median 8% of the worker's peak context, and `sed -n` and `grep` output made up 41% of its Bash results, so delegated searches save the most context. It scores each delegated task's R and C as for an item, and `bin/subagent-rung` turns them into the Agent tool's model and effort, counted from the project's rung. The rule names both, because the Agent tool sets a subagent's effort only when instructions ask. `CLAUDE.md` states the rule, since it holds in every session. A task that proves too hard for the worker's rung goes one rung up instead: `routing: a worker hands a task one rung up`.
|
||||
|
||||
Because a model switch inside a session discards its prompt cache, the worker changes rung only as the chunk starts, after every second unfinished verdict, when the judge reports a taken-in item whose R + C picks a higher rung, or when the judge finds the escalation trigger a worker cites in asking for a higher rung (`routing: a worker whose run ends asking for a higher rung`). loop-claude routes on the first row of the next release in `todo.md`'s table that waits on no question. It reads neither an order the plan states in prose nor the task, so a chunk may start on another item's rung: a higher one costs money, and a lower one holds until the judge reports the item the worker took in, after the first cycle. `todo.md` item 136 ends this, routing on the item the worker says it takes.
|
||||
Because a model switch inside a session discards its prompt cache, the worker changes rung only as the chunk starts, after every second unfinished verdict, when the judge reports a taken-in item whose R + C picks a higher rung, or when the judge finds the escalation trigger a worker cites in asking for a higher rung (`routing: a worker whose run ends asking for a higher rung`). loop-claude routes on the first row of the next release in `todo.md`'s table that does not wait: an item waits while it is marked `question` or a blocker of it is still in the table. Since `todo.md` holds no order but its table's (`todo.md: one table`), that row is the item the worker takes. An item the worker takes in beyond that row lifts the worker's rung once the judge reports it, after the first cycle.
|
||||
|
||||
Valid while the index ranks these models, and while no newer model joins the catalog.
|
||||
|
||||
@@ -240,7 +238,7 @@ On a model listed in `JUDGE_REPLAYED` in `bin/loop_claude/routing.py`, the judge
|
||||
|
||||
On 2026-10-15, `bin/judge-replay claude-opus-5-5` replayed the latest 15 archived verdicts of each kind from the Opus 5.5 projects, 39 in all. The reference judge, Opus 5.5 at the xhigh effort `settings.json` gave every judge before, reproduced 31 of them. The other 8 may rest on records or judge rules that have changed since; either way no rung is held to them. On the 31, Haiku 5.5 missed 7 at xhigh and 8 at max. That run tried each judge once. 4 of Haiku's misses, 1 at xhigh and 3 at max, misquoted the transcript, which the loop and `judge-replay` now retry; without them it missed 6 and 5. Sonnet 5.5 at high returned another kind on 3 interrupts, and Opus 5.5 at medium missed none. A missed interrupt lets the worker settle a decision that is lilleman's (goal 1.2), so the judge never runs below the project's rung.
|
||||
|
||||
Only Opus 5.5 was replayed, so the judge of a project on another model keeps the effort its settings give until `judge-replay` covers that model (goal 1.1). Every routed chunk on record had an item of R + C 9, so the replay could not show that the project's rung suffices for harder items, and the judge climbs with the routed item as the worker does. For R + C 11 to 14 it still runs at or below xhigh (goal 1.4); from 15, `routing: one ladder` records that lilleman wants the highest quality at any price. An item the worker takes in later lifts the worker, not the judge, until `todo.md` item 136 routes a chunk on the item its worker takes.
|
||||
Only Opus 5.5 was replayed, so the judge of a project on another model keeps the effort its settings give until `judge-replay` covers that model (goal 1.1). Every routed chunk on record had an item of R + C 9, so the replay could not show that the project's rung suffices for harder items, and the judge climbs with the routed item as the worker does. For R + C 11 to 14 it still runs at or below xhigh (goal 1.4); from 15, `routing: one ladder` records that lilleman wants the highest quality at any price. An item the worker takes in beyond the routed one lifts the worker's rung but not the judge's, until `todo.md` item 153 lifts the judge too.
|
||||
|
||||
Valid while the archived verdicts show what a judge should return, and until a new model joins the ladder: replay then.
|
||||
|
||||
|
||||
@@ -6,6 +6,7 @@ paths:
|
||||
# Todo items (`todo.md`)
|
||||
|
||||
- **`todo.md` is mandatory in every project, in one shape**, which `~/.claude/bin/rank_todo.py` checks and ranks; its `--help` shows a valid file. `## Scoring` holds the formula, the bar and the goal weights; `## Items` is one table of every item; `## Details` holds each item's detail under its ID. Cite an item by its ID. The formula, bar and weights are the project's own to tune.
|
||||
- **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, or rewrite a filed item's tagline or detail. Draft each new item, and each change to a filed item, 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 R + C. 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.
|
||||
- **Score an item when it is filed or edited.** Each of R, S, C, A and G is a whole number from 1 to 10:
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
`Bar = 9`
|
||||
|
||||
`Next ID = 153`
|
||||
`Next ID = 155`
|
||||
|
||||
| Goal | W |
|
||||
|---|---|
|
||||
@@ -22,94 +22,79 @@
|
||||
|
||||
## Items
|
||||
|
||||
Release 0.3.0 takes items 125, 114 and 124 first, whatever their scores: Shape is the lowest dimension, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 136 | 0.1.0 | decision | **Route a chunk on the item its worker says it takes, in place of the next release's first row.** | 2 | 3 | 4 | 4 | 5 | 1.4 | 14.8 |
|
||||
| 150 | 0.2.0 | decision | **Make each README goal `maintain` or `achieve`, give each achieve goal a signal, a counter-signal and a one-line reason, and have a maintain goal veto an item that breaks it.** | 3 | 3 | 4 | 7 | 8 | 1.2 | 25.9 |
|
||||
| 148 | 0.2.0 | decision | **Rank items by V / C, where C is 2^S and V sums each cited achieve goal's sum-reciprocal weight times how far the item moves it, and drop A.** | 5 | 5 | 6 | 7 | 8 | 1.1, 1.2 | 23.6 |
|
||||
| 152 | 0.2.0 | decision | **Anchor each score level in `rules/todo-items.md` with words, and each project's with two or three items it shipped, and have a scorer compare a new item against them.** | 2 | 4 | 3 | 6 | 7 | 1.1, 1.3 | 22.9 |
|
||||
| 149 | 0.2.0 | decision | **Fill each release by priority up to a capacity it states, in place of the bar, and move what does not fit to a later release.** | 3 | 3 | 3 | 6 | 7 | 1.1 | 22.1 |
|
||||
| 146 | 0.2.0 | decision | **Score R as L + E + I − 2 from anchored levels, at least 7 at I5 and 5 at I4, with L, E and I in their own columns and `rank_todo.py` computing R, drop C, and route a task's model and effort on its R alone.** | 6 | 7 | 7 | 7 | 8 | 1.1, 1.2, 1.4 | 22.1 |
|
||||
| 151 | 0.2.0 | decision | **Keep 10 to 20 settled decisions per project as its goals' test set, and rerun them after a goal changes.** | 3 | 5 | 5 | 6 | 7 | 1.2 | 21.5 |
|
||||
| 105 | 0.2.0 | decision | **Compare review rounds per pass and reading cost for the five chunks before and after the `worker:` decision moved the principles out of the worker's context, and file an item if either rose.** | 1 | 2 | 3 | 5 | 6 | 1.4 | 20.0 |
|
||||
| 112 | 0.2.0 | | **Count an item as shipped only where its chunk built it, so an item a chunk dropped from the plan gets no outcome.** | 2 | 3 | 5 | 5 | 6 | 1.1 | 19.1 |
|
||||
| 110 | 0.2.0 | | **Count, for each finished chunk, the later changes that fixed code it wrote, and show them beside its guessed E.** | 2 | 4 | 6 | 5 | 6 | 1.1, 1.4 | 18.9 |
|
||||
| 115 | 0.2.0 | question | **Confirm or set how many finished chunks that each shipped one item `score-outcomes` waits for before it shows a score's medians, today 10.** | 1 | 1 | 2 | 4 | 5 | 1.2 | 16.6 |
|
||||
| 116 | 0.2.0 | | **Report L by the share of chunks with a 🔴, once 10 chunks that each shipped one item record finding counts and most record no 🔴.** | 1 | 2 | 2 | 4 | 5 | 1.1 | 16.4 |
|
||||
| 111 | 0.2.0 | | **Measure the chunks of a project that merges by squash or fast-forward, which `score-outcomes` skips today.** | 3 | 3 | 5 | 4 | 5 | 1.3 | 13.9 |
|
||||
| 113 | 0.2.0 | | **Compute an item's S from the code it names, where it names any, and show it beside the finished items `score-outcomes` lists.** | 3 | 4 | 6 | 4 | 5 | 1.1, 1.4 | 13.9 |
|
||||
| 120 | 0.3.0 | | **Rewrite larv-review §3's "Round cap" and "Re-entry" as one table that says, for each kind of fix, which passes rerun and what a round reviews.** | 2 | 4 | 5 | 5 | 6 | 1.1, 1.2 | 18.9 |
|
||||
| 121 | 0.3.0 | | **Check that `bin/round_titles.py`'s `PASSES` lists exactly the passes of larv-review §3's table.** | 1 | 3 | 2 | 4 | 5 | 1.1, 1.3 | 16.1 |
|
||||
| 122 | 0.3.0 | | **Assemble the judge's prompt in `bin/loop_claude/cycle/judge.py`, importing only wording the worker also sees, and call the worker "the worker" in it.** | 3 | 4 | 4 | 4 | 5 | 1.1 | 13.9 |
|
||||
| 123 | 0.3.0 | | **Have `bin/comprehension_history.py` parse each history entry once into seats, votes and places, so `latest_places`, `worse_places` and `worse_votes` neither depend on table order nor split a label to find a seat.** | 3 | 5 | 5 | 4 | 5 | 1.1 | 13.7 |
|
||||
| 139 | 0.3.0 | | **Split `bin/routing_figures/measure.py` by concern, and keep the figures' measured cycle and each raised call as fields loop-claude reads back, not as the prose it renders.** | 2 | 3 | 3 | 3 | 5 | 1.1 | 13.2 |
|
||||
| 127 | 0.3.0 | | **Define seat, place, paired ruling, scoring run and the judge's records in `CLAUDE.md` → "Vocabulary".** | 1 | 1 | 1 | 3 | 4 | 1.1 | 12.7 |
|
||||
| 125 | 0.3.0 | decision | **Give "record", "outcome" and "places" one meaning each across `bin/`, and rename `bin/larv_review/git.py` by what it holds.** | 2 | 5 | 3 | 3 | 5 | 1.1 | 12.7 |
|
||||
| 126 | 0.3.0 | | **State when work has landed towards a release once, in `bin/larv_review/plan.py`, and have larv-review's help point to it.** | 1 | 2 | 2 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 131 | 0.3.0 | | **Describe the transcript archive's layout in `bin/transcript_archive/`, which owns it, and have loop-claude's help point there.** | 1 | 2 | 1 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 133 | 0.3.0 | | **Show, beside `bin/rule_hook/override_log.py`'s `this_chunks`, one example per case it decides: an amended or rebased commit, a renamed branch, and a commit on the default branch.** | 1 | 2 | 2 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 134 | 0.3.0 | | **Name in `bin/shell_command.py`'s `segments` the shell forms it does not parse, so a caller knows what it misses.** | 1 | 2 | 2 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 140 | 0.3.0 | | **Split `docs/decisions.md` → `routing: one ladder` into one entry per decision, so a reader finds the rules for the ladder, the worker's rung, the routing figures and delegation by their titles.** | 1 | 2 | 1 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 114 | 0.3.0 | decision | **Run git through `git_repo.py` in `rule_hook`, `metric_bench`, `reading_cost`, `stability_replay` and `loop_claude`, keeping rule-hook's guards as an option, so one module owns how a tool runs git.** | 3 | 4 | 4 | 3 | 5 | 1.1 | 11.9 |
|
||||
| 117 | 0.3.0 | | **Give `todo_table.items` one way to say a plan has no items table, so no caller tells it from an empty plan by truthiness.** | 2 | 2 | 3 | 3 | 4 | 1.1 | 11.4 |
|
||||
| 124 | 0.3.0 | decision | **Group the shared modules at `bin/`'s root into packages named by purpose, so the root holds only launchers and stand-alone tools.** | 3 | 6 | 3 | 3 | 5 | 1.1 | 11.4 |
|
||||
| 130 | 0.3.0 | | **Move the vote counting out of `bin/larv_review/ruling.py`'s `votes`, so reading a votes file decides nothing.** | 2 | 3 | 3 | 3 | 4 | 1.1 | 11.2 |
|
||||
| 137 | 0.3.0 | | **Archive a chunk's route as a record loop-claude reads back field by field, in place of the `Worker:` prose `ROUTED` parses, and name `stepped` and the judge's `bundled` by what they do.** | 2 | 3 | 3 | 3 | 4 | 1.1 | 11.2 |
|
||||
| 129 | 0.3.0 | | **Explain `bin/rule_hook/rules.py`'s `OVERRIDE` pattern beside it: why the reason is lazy, what the lookahead splits and why `-->` is stripped.** | 1 | 1 | 1 | 2 | 4 | 1.1 | 10.7 |
|
||||
| 135 | 0.3.0 | | **Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop.** | 3 | 3 | 4 | 3 | 4 | 1.1 | 10.2 |
|
||||
| 1 | 0.4.0 | question | **Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.** | 3 | 5 | 2 | 8 | 9 | 3, 4 | 27.0 |
|
||||
| 21 | 0.4.0 | | **Give `settings.json`'s model one writer, and sort its keys.** | 3 | 3 | 4 | 6 | 7 | 1.3 | 21.8 |
|
||||
| 49 | 0.4.0 | principle | **Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.** | 1 | 2 | 2 | 5 | 6 | 1.3 | 20.1 |
|
||||
| 59 | 0.4.0 | | **Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.** | 3 | 3 | 5 | 6 | 6 | 1.4 | 19.8 |
|
||||
| 12 | 0.4.0 | | **Run the test suite in CI on every PR, or record in `docs/decisions.md` why the local run is enough.** | 2 | 4 | 3 | 4 | 6 | 1.1 | 16.9 |
|
||||
| 80 | 0.4.0 | | **State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.** | 1 | 1 | 1 | 5 | 5 | 4 | 16.8 |
|
||||
| 5 | 0.4.0 | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 5 | 5 | 7 | 5 | 6 | 1.1 | 15.6 |
|
||||
| 84 | 0.4.0 | | **Check, at each release's scoring run, that seats in a paired ruling agree more often than two scoring runs on near-identical code do, as the paired-ruling decision assumes.** | 2 | 2 | 5 | 4 | 5 | 1.4 | 15.1 |
|
||||
| 67 | 0.4.0 | principle | **Point stability-reviewer at the technical principles in place of its own restatement of them.** | 2 | 3 | 2 | 4 | 5 | 1.3 | 14.9 |
|
||||
| 106 | 0.4.0 | | **Make larv-review's "Do not over-read a clean result" cite a rule that says Renovate or Dependabot owns dependency CVEs, or drop the citation.** | 1 | 1 | 1 | 3 | 5 | 1.1 | 14.7 |
|
||||
| 66 | 0.4.0 | principle | **Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.** | 3 | 3 | 4 | 4 | 5 | 1.1 | 14.2 |
|
||||
| 101 | 0.4.0 | principle | **Have `larv_review/record.py`'s `read_seats` take the time, the commit check and the history as inputs, so it parses and decides without effects.** | 3 | 3 | 3 | 4 | 5 | 1.1 | 14.2 |
|
||||
| 132 | 0.4.0 | | **Lift each dimension still under the comprehension floor after release 0.2.0's scoring run, at the places that run names.** | 3 | 5 | 5 | 4 | 5 | 1.1 | 13.7 |
|
||||
| 29 | 0.4.0 | | **Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.** | 2 | 2 | 3 | 3 | 5 | 1.1, 1.4 | 13.4 |
|
||||
| 68 | 0.4.0 | principle | **Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.** | 2 | 4 | 4 | 3 | 5 | 1.1 | 12.9 |
|
||||
| 119 | 0.4.0 | | **Retitle the comprehension-floor decision so it says a chunk lifting a project towards the floor works first on its lowest-scoring dimension, and that the floor blocks nothing.** | 1 | 1 | 1 | 3 | 4 | 1.1 | 12.7 |
|
||||
| 65 | 0.4.0 | | **Archive each judge reply the loop rejects.** | 3 | 4 | 3 | 4 | 5 | 3 | 12.5 |
|
||||
| 82 | 0.4.0 | principle | **Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.** | 1 | 2 | 2 | 3 | 4 | 1.3 | 12.3 |
|
||||
| 73 | 0.4.0 | | **Have each reviewer write its full report to a file and return the worker only its findings' one-line summaries.** | 3 | 4 | 4 | 4 | 4 | 1.4 | 11.7 |
|
||||
| 6 | 0.4.0 | decision | **Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.** | 5 | 5 | 6 | 4 | 5 | 1.1 | 11.7 |
|
||||
| 51 | 0.4.0 | principle | **Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.** | 3 | 5 | 5 | 3 | 5 | 1.1 | 11.7 |
|
||||
| 102 | 0.4.0 | | **Give loop-claude's retry delay an environment override, so the black-box test stops replacing `time.sleep` through `sitecustomize`.** | 2 | 2 | 2 | 3 | 4 | 1.1 | 11.4 |
|
||||
| 50 | 0.4.0 | principle | **Grant the bench's runs only the tools a review needs, in place of skipping every permission.** | 2 | 2 | 3 | 3 | 4 | 4 | 9.9 |
|
||||
| 81 | 0.4.0 | principle | **Have `workflow-bench/bench.py` return each run's failure as a value, so one failed clone does not hide the later runs' results.** | 2 | 2 | 3 | 3 | 4 | 4 | 9.9 |
|
||||
| 4 | 0.4.0 | | **Name each chunk's archive folder by the chunk's start time, so `<key>/` lists chunks in the order they ran.** | 3 | 2 | 3 | 4 | 3 | 3 | 9.6 |
|
||||
| 52 | 0.4.0 | principle | **Record why this checkout lives in Claude Code's own directory, or move it out and link it in.** | 6 | 6 | 4 | 3 | 5 | 2 | 7.5 |
|
||||
| 77 | 0.5.0 | | **Teach `bin/metric-bench` Go and TypeScript, rerun it once two projects' comprehension histories name places, and bring into review only a metric that tracks the panel.** | 3 | 6 | 6 | 6 | 7 | 1.1, 1.4 | 21.4 |
|
||||
| ID | Release | Blocked by | Exempt | Item | R | S | C | A | G | Goals | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 150 | 0.2.0 | | decision | **Make each README goal `maintain` or `achieve`, give each achieve goal a signal, a counter-signal and a one-line reason, and have a maintain goal veto an item that breaks it.** | 3 | 3 | 4 | 7 | 8 | 1.2 | 25.9 |
|
||||
| 148 | 0.2.0 | 150 | decision | **Rank items by V / C, where C is 2^S and V sums each cited achieve goal's sum-reciprocal weight times how far the item moves it, and drop A.** | 5 | 5 | 6 | 7 | 8 | 1.1, 1.2 | 23.6 |
|
||||
| 146 | 0.2.0 | | decision | **Score R as L + E + I − 2 from anchored levels, at least 7 at I5 and 5 at I4, with L, E and I in their own columns and `rank_todo.py` computing R, drop C, and route a task's model and effort on its R alone.** | 6 | 7 | 7 | 7 | 8 | 1.1, 1.2, 1.4 | 22.1 |
|
||||
| 152 | 0.2.0 | 146, 148 | decision | **Anchor each score level in `rules/todo-items.md` with words, and each project's with two or three items it shipped, and have a scorer compare a new item against them.** | 2 | 4 | 3 | 6 | 7 | 1.1, 1.3 | 22.9 |
|
||||
| 149 | 0.2.0 | 148 | decision | **Fill each release by priority up to a capacity it states, in place of the bar, and move what does not fit to a later release.** | 3 | 3 | 3 | 6 | 7 | 1.1 | 22.1 |
|
||||
| 151 | 0.2.0 | 150 | decision | **Keep 10 to 20 settled decisions per project as its goals' test set, and rerun them after a goal changes.** | 3 | 5 | 5 | 6 | 7 | 1.2 | 21.5 |
|
||||
| 105 | 0.2.0 | | decision | **Compare review rounds per pass and reading cost for the five chunks before and after the `worker:` decision moved the principles out of the worker's context, and file an item if either rose.** | 1 | 2 | 3 | 5 | 6 | 1.4 | 20.0 |
|
||||
| 154 | 0.2.0 | | defect | **Have `bin/shell_command.py`'s `segments` keep a command's words together across a redirect, so `git > out commit` reads as one git commit.** | 2 | 2 | 3 | 5 | 6 | 1.3 | 19.1 |
|
||||
| 112 | 0.2.0 | | | **Count an item as shipped only where its chunk built it, so an item a chunk dropped from the plan gets no outcome.** | 2 | 3 | 5 | 5 | 6 | 1.1 | 19.1 |
|
||||
| 110 | 0.2.0 | | | **Count, for each finished chunk, the later changes that fixed code it wrote, and show them beside its guessed E.** | 2 | 4 | 6 | 5 | 6 | 1.1, 1.4 | 18.9 |
|
||||
| 115 | 0.2.0 | | question | **Confirm or set how many finished chunks that each shipped one item `score-outcomes` waits for before it shows a score's medians, today 10.** | 1 | 1 | 2 | 4 | 5 | 1.2 | 16.6 |
|
||||
| 116 | 0.2.0 | | | **Report L by the share of chunks with a 🔴, once 10 chunks that each shipped one item record finding counts and most record no 🔴.** | 1 | 2 | 2 | 4 | 5 | 1.1 | 16.4 |
|
||||
| 153 | 0.2.0 | | decision | **Run the judge on the rung the highest R + C in its chunk picks, an item the worker takes in included.** | 2 | 3 | 4 | 4 | 5 | 1.2 | 15.1 |
|
||||
| 111 | 0.2.0 | | | **Measure the chunks of a project that merges by squash or fast-forward, which `score-outcomes` skips today.** | 3 | 3 | 5 | 4 | 5 | 1.3 | 13.9 |
|
||||
| 113 | 0.2.0 | | | **Compute an item's S from the code it names, where it names any, and show it beside the finished items `score-outcomes` lists.** | 3 | 4 | 6 | 4 | 5 | 1.1, 1.4 | 13.9 |
|
||||
| 125 | 0.3.0 | | decision | **Give "record", "outcome" and "places" one meaning each across `bin/`, and rename `bin/larv_review/git.py` by what it holds.** | 2 | 5 | 3 | 3 | 9 | 1.1 | 20.6 |
|
||||
| 114 | 0.3.0 | | decision | **Run git through `git_repo.py` in `rule_hook`, `metric_bench`, `reading_cost`, `stability_replay` and `loop_claude`, keeping rule-hook's guards as an option, so one module owns how a tool runs git.** | 3 | 4 | 4 | 3 | 9 | 1.1 | 19.8 |
|
||||
| 124 | 0.3.0 | | decision | **Group the shared modules at `bin/`'s root into packages named by purpose, so the root holds only launchers and stand-alone tools.** | 3 | 6 | 3 | 3 | 9 | 1.1 | 19.3 |
|
||||
| 120 | 0.3.0 | | | **Rewrite larv-review §3's "Round cap" and "Re-entry" as one table that says, for each kind of fix, which passes rerun and what a round reviews.** | 2 | 4 | 5 | 5 | 6 | 1.1, 1.2 | 18.9 |
|
||||
| 121 | 0.3.0 | | | **Check that `bin/round_titles.py`'s `PASSES` lists exactly the passes of larv-review §3's table.** | 1 | 3 | 2 | 4 | 5 | 1.1, 1.3 | 16.1 |
|
||||
| 122 | 0.3.0 | | | **Assemble the judge's prompt in `bin/loop_claude/cycle/judge.py`, importing only wording the worker also sees, and call the worker "the worker" in it.** | 3 | 4 | 4 | 4 | 5 | 1.1 | 13.9 |
|
||||
| 123 | 0.3.0 | | | **Have `bin/comprehension_history.py` parse each history entry once into seats, votes and places, so `latest_places`, `worse_places` and `worse_votes` neither depend on table order nor split a label to find a seat.** | 3 | 5 | 5 | 4 | 5 | 1.1 | 13.7 |
|
||||
| 139 | 0.3.0 | | | **Split `bin/routing_figures/measure.py` by concern, and keep the figures' measured cycle and each raised call as fields loop-claude reads back, not as the prose it renders.** | 2 | 3 | 3 | 3 | 5 | 1.1 | 13.2 |
|
||||
| 127 | 0.3.0 | | | **Define seat, place, paired ruling, scoring run and the judge's records in `CLAUDE.md` → "Vocabulary".** | 1 | 1 | 1 | 3 | 4 | 1.1 | 12.7 |
|
||||
| 126 | 0.3.0 | | | **State when work has landed towards a release once, in `bin/larv_review/plan.py`, and have larv-review's help point to it.** | 1 | 2 | 2 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 131 | 0.3.0 | | | **Describe the transcript archive's layout in `bin/transcript_archive/`, which owns it, and have loop-claude's help point there.** | 1 | 2 | 1 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 133 | 0.3.0 | | | **Show, beside `bin/rule_hook/override_log.py`'s `this_chunks`, one example per case it decides: an amended or rebased commit, a renamed branch, and a commit on the default branch.** | 1 | 2 | 2 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 134 | 0.3.0 | | | **Name in `bin/shell_command.py`'s `segments` the shell forms it does not parse, so a caller knows what it misses.** | 1 | 2 | 2 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 140 | 0.3.0 | | | **Split `docs/decisions.md` → `routing: one ladder` into one entry per decision, so a reader finds the rules for the ladder, the worker's rung, the routing figures and delegation by their titles.** | 1 | 2 | 1 | 3 | 4 | 1.1 | 12.4 |
|
||||
| 117 | 0.3.0 | | | **Give `todo_table.items` one way to say a plan has no items table, so no caller tells it from an empty plan by truthiness.** | 2 | 2 | 3 | 3 | 4 | 1.1 | 11.4 |
|
||||
| 130 | 0.3.0 | | | **Move the vote counting out of `bin/larv_review/ruling.py`'s `votes`, so reading a votes file decides nothing.** | 2 | 3 | 3 | 3 | 4 | 1.1 | 11.2 |
|
||||
| 137 | 0.3.0 | | | **Archive a chunk's route as a record loop-claude reads back field by field, in place of the `Worker:` prose `ROUTED` parses, and name `stepped` and the judge's `bundled` by what they do.** | 2 | 3 | 3 | 3 | 4 | 1.1 | 11.2 |
|
||||
| 129 | 0.3.0 | | | **Explain `bin/rule_hook/rules.py`'s `OVERRIDE` pattern beside it: why the reason is lazy, what the lookahead splits and why `-->` is stripped.** | 1 | 1 | 1 | 2 | 4 | 1.1 | 10.7 |
|
||||
| 135 | 0.3.0 | | | **Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop.** | 3 | 3 | 4 | 3 | 4 | 1.1 | 10.2 |
|
||||
| 1 | 0.4.0 | | question | **Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.** | 3 | 5 | 2 | 8 | 9 | 3, 4 | 27.0 |
|
||||
| 21 | 0.4.0 | | | **Give `settings.json`'s model one writer, and sort its keys.** | 3 | 3 | 4 | 6 | 7 | 1.3 | 21.8 |
|
||||
| 49 | 0.4.0 | | principle | **Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.** | 1 | 2 | 2 | 5 | 6 | 1.3 | 20.1 |
|
||||
| 59 | 0.4.0 | | | **Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.** | 3 | 3 | 5 | 6 | 6 | 1.4 | 19.8 |
|
||||
| 12 | 0.4.0 | | | **Run the test suite in CI on every PR, or record in `docs/decisions.md` why the local run is enough.** | 2 | 4 | 3 | 4 | 6 | 1.1 | 16.9 |
|
||||
| 80 | 0.4.0 | | | **State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.** | 1 | 1 | 1 | 5 | 5 | 4 | 16.8 |
|
||||
| 5 | 0.4.0 | | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 5 | 5 | 7 | 5 | 6 | 1.1 | 15.6 |
|
||||
| 84 | 0.4.0 | | | **Check, at each release's scoring run, that seats in a paired ruling agree more often than two scoring runs on near-identical code do, as the paired-ruling decision assumes.** | 2 | 2 | 5 | 4 | 5 | 1.4 | 15.1 |
|
||||
| 67 | 0.4.0 | | principle | **Point stability-reviewer at the technical principles in place of its own restatement of them.** | 2 | 3 | 2 | 4 | 5 | 1.3 | 14.9 |
|
||||
| 106 | 0.4.0 | | | **Make larv-review's "Do not over-read a clean result" cite a rule that says Renovate or Dependabot owns dependency CVEs, or drop the citation.** | 1 | 1 | 1 | 3 | 5 | 1.1 | 14.7 |
|
||||
| 66 | 0.4.0 | | principle | **Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.** | 3 | 3 | 4 | 4 | 5 | 1.1 | 14.2 |
|
||||
| 101 | 0.4.0 | | principle | **Have `larv_review/record.py`'s `read_seats` take the time, the commit check and the history as inputs, so it parses and decides without effects.** | 3 | 3 | 3 | 4 | 5 | 1.1 | 14.2 |
|
||||
| 132 | 0.4.0 | | | **Lift each dimension still under the comprehension floor after release 0.2.0's scoring run, at the places that run names.** | 3 | 5 | 5 | 4 | 5 | 1.1 | 13.7 |
|
||||
| 29 | 0.4.0 | | | **Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.** | 2 | 2 | 3 | 3 | 5 | 1.1, 1.4 | 13.4 |
|
||||
| 68 | 0.4.0 | | principle | **Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.** | 2 | 4 | 4 | 3 | 5 | 1.1 | 12.9 |
|
||||
| 119 | 0.4.0 | | | **Retitle the comprehension-floor decision so it says a chunk lifting a project towards the floor works first on its lowest-scoring dimension, and that the floor blocks nothing.** | 1 | 1 | 1 | 3 | 4 | 1.1 | 12.7 |
|
||||
| 65 | 0.4.0 | | | **Archive each judge reply the loop rejects.** | 3 | 4 | 3 | 4 | 5 | 3 | 12.5 |
|
||||
| 82 | 0.4.0 | | principle | **Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.** | 1 | 2 | 2 | 3 | 4 | 1.3 | 12.3 |
|
||||
| 73 | 0.4.0 | | | **Have each reviewer write its full report to a file and return the worker only its findings' one-line summaries.** | 3 | 4 | 4 | 4 | 4 | 1.4 | 11.7 |
|
||||
| 6 | 0.4.0 | | decision | **Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.** | 5 | 5 | 6 | 4 | 5 | 1.1 | 11.7 |
|
||||
| 51 | 0.4.0 | | principle | **Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.** | 3 | 5 | 5 | 3 | 5 | 1.1 | 11.7 |
|
||||
| 102 | 0.4.0 | | | **Give loop-claude's retry delay an environment override, so the black-box test stops replacing `time.sleep` through `sitecustomize`.** | 2 | 2 | 2 | 3 | 4 | 1.1 | 11.4 |
|
||||
| 50 | 0.4.0 | | principle | **Grant the bench's runs only the tools a review needs, in place of skipping every permission.** | 2 | 2 | 3 | 3 | 4 | 4 | 9.9 |
|
||||
| 81 | 0.4.0 | | principle | **Have `workflow-bench/bench.py` return each run's failure as a value, so one failed clone does not hide the later runs' results.** | 2 | 2 | 3 | 3 | 4 | 4 | 9.9 |
|
||||
| 4 | 0.4.0 | | | **Name each chunk's archive folder by the chunk's start time, so `<key>/` lists chunks in the order they ran.** | 3 | 2 | 3 | 4 | 3 | 3 | 9.6 |
|
||||
| 52 | 0.4.0 | | principle | **Record why this checkout lives in Claude Code's own directory, or move it out and link it in.** | 6 | 6 | 4 | 3 | 5 | 2 | 7.5 |
|
||||
| 77 | 0.5.0 | | | **Teach `bin/metric-bench` Go and TypeScript, rerun it once two projects' comprehension histories name places, and bring into review only a metric that tracks the panel.** | 3 | 6 | 6 | 6 | 7 | 1.1, 1.4 | 21.4 |
|
||||
|
||||
## Details
|
||||
|
||||
### 136. Route a chunk on the item its worker says it takes, in place of the next release's first row.
|
||||
|
||||
loop-claude routes on the first row of the next release, while the worker takes the item the plan's prose orders first, or a prerequisite, as the chunk that shipped item 88, a prerequisite, took item 88 in place of the first row. A first row of higher R + C pays for a dearer rung all chunk; one of lower R + C holds until the judge reports the item taken in. The judge reports the item the worker takes only after the first cycle, so routing the first cycle right needs the item before the worker starts.
|
||||
|
||||
Once this lands, the judge follows the item the worker takes too, since `judge_rung` routes on the chunk's item.
|
||||
|
||||
### 150. Make each README goal `maintain` or `achieve`, give each achieve goal a signal, a counter-signal and a one-line reason, and have a maintain goal veto an item that breaks it.
|
||||
|
||||
`rules/goals-and-audience.md` states the form, with a GOOD and a BANNED example of each. The Audience says whose value the goals serve. A maintain goal is weighed by none of the scores: an item that breaks one is redesigned or dropped. A new spelling of a goal line is something the human reads and writes, so a panel picks it, as `CLAUDE.md` → "Working loop", "Bench a syntax with the people who write it" says.
|
||||
|
||||
### 148. Rank items by V / C, where C is 2^S and V sums each cited achieve goal's sum-reciprocal weight times how far the item moves it, and drop A.
|
||||
|
||||
Needs 150. A goal ranked k of n weighs (1/k) / (1 + 1/2 + … + 1/n). An item that moves a goal by M, 1 to 10, adds weight × M to V. S stays 1 to 10, each step about ×2.5 in lines changed, which `docs/scoring-and-goals-research.md` → "This repo's own measurements" found. R stays out of the ranking. The Goal weights table goes from `todo.md`, since the rule derives them.
|
||||
|
||||
### 152. Anchor each score level in `rules/todo-items.md` with words, and each project's with two or three items it shipped, and have a scorer compare a new item against them.
|
||||
|
||||
Needs 146 and 148. LLM ratings drift to the middle of an unanchored scale, and worked examples cut estimation error. A project's anchors are shipped items, cited by ID and commit, chosen from what `score-outcomes` measured for them.
|
||||
|
||||
### 149. Fill each release by priority up to a capacity it states, in place of the bar, and move what does not fit to a later release.
|
||||
|
||||
Needs 148. A release's capacity is a sum of its items' C. Each project states its own; the human sets the first value per project. Nothing is deleted by score.
|
||||
A goal ranked k of n weighs (1/k) / (1 + 1/2 + … + 1/n). An item that moves a goal by M, 1 to 10, adds weight × M to V. S stays 1 to 10, each step about ×2.5 in lines changed, which `docs/scoring-and-goals-research.md` → "This repo's own measurements" found. R stays out of the ranking. The Goal weights table goes from `todo.md`, since the rule derives them.
|
||||
|
||||
### 146. Score R as L + E + I − 2 from anchored levels, at least 7 at I5 and 5 at I4, with L, E and I in their own columns and `rank_todo.py` computing R, drop C, and route a task's model and effort on its R alone.
|
||||
|
||||
@@ -127,14 +112,26 @@ Each level is about ×10 of a real quantity; `docs/decisions.md` → `todo.md:
|
||||
|
||||
C goes in the same chunk, so no reshaped table meets bands built for R + C: R alone runs 1 to 10, and the R + C bands would step most tasks well down the ladder. The bands (`docs/decisions.md` → `routing: one ladder…`) become bands over R, spread across the R values the rescored plans hold. The bands are the human's call, so the chunk proposes them and waits, and puts one option beside them: the worker routed on L and its reviewers on E + I, since impact makes a task riskier, not harder. `CLAUDE.md`'s delegation rule, `subagent-rung` and its `--plan`, loop-claude's chunk routing and prompts, the judge's rung, escalation trigger 1 and `score-outcomes` drop C. The routing decision's "S never moves a rung" no longer holds, since size sets L, so the chunk revises it. Once it merges, append a `Reset` to `routing-calls-raised.md`, as `AGENTS.md` says of a band change, so the routing figures count only chunks routed on R.
|
||||
|
||||
### 152. Anchor each score level in `rules/todo-items.md` with words, and each project's with two or three items it shipped, and have a scorer compare a new item against them.
|
||||
|
||||
LLM ratings drift to the middle of an unanchored scale, and worked examples cut estimation error. A project's anchors are shipped items, cited by ID and commit, chosen from what `score-outcomes` measured for them.
|
||||
|
||||
### 149. Fill each release by priority up to a capacity it states, in place of the bar, and move what does not fit to a later release.
|
||||
|
||||
A release's capacity is a sum of its items' C. Each project states its own; the human sets the first value per project. Nothing is deleted by score.
|
||||
|
||||
### 151. Keep 10 to 20 settled decisions per project as its goals' test set, and rerun them after a goal changes.
|
||||
|
||||
Needs 150. Each case is a question the project settled and the answer it chose. A fresh-context agent given only the README's premises answers each case; a case it answers differently says the goals no longer decide it. Written guidance can fail to change behaviour, which is why the goals get a test.
|
||||
Each case is a question the project settled and the answer it chose. A fresh-context agent given only the README's premises answers each case; a case it answers differently says the goals no longer decide it. Written guidance can fail to change behaviour, which is why the goals get a test.
|
||||
|
||||
### 105. Compare review rounds per pass and reading cost for the five chunks before and after the `worker:` decision moved the principles out of the worker's context, and file an item if either rose.
|
||||
|
||||
The `worker:` decision is valid while review rounds per pass do not rise. Count the rounds from each PR's `Answer <pass> round <n>:` commits, and take reading cost from `docs/reading-cost.md`. Run it once five chunks have merged after the one that recorded the decision.
|
||||
|
||||
### 154. Have `bin/shell_command.py`'s `segments` keep a command's words together across a redirect, so `git > out commit` reads as one git commit.
|
||||
|
||||
`segments('echo hi > f arg')` returns `arg` as a command of its own, and `segments('git > /tmp/x commit -m hi')` returns `git` and `commit -m hi` apart, though the shell runs one `git commit`. rule-hook's commit rules read the commands `segments` finds, so such a commit escapes `commit-one-line`, `no-ai-attribution`, `round-title-counts` and `todo-rank-check`. The comprehension seats' scoring run in PR #280 found it.
|
||||
|
||||
### 112. Count an item as shipped only where its chunk built it, so an item a chunk dropped from the plan gets no outcome.
|
||||
|
||||
`score-outcomes` counts every item a merge removed from `todo.md` as shipped. A merge that changed only the plan ships nothing, but one that built an item and also dropped another gives the dropped item the built one's outcome, as PR #253 did with item 69. Mark a dropped item in the change that drops it, such as by the commit or merge title, and leave it out.
|
||||
@@ -151,6 +148,10 @@ The `worker:` decision is valid while review rounds per pass do not rise. Count
|
||||
|
||||
`score-outcomes` reports risk as the median 🔴 count at each guessed R; with item 146 it is L a 🔴 tests. Where most chunks have no 🔴, every median reads 0 and tells a scorer nothing. No round title held counts before PR #254, so how often a chunk has a 🔴 is not yet known.
|
||||
|
||||
### 153. Run the judge on the rung the highest R + C in its chunk picks, an item the worker takes in included.
|
||||
|
||||
The judge reports the R + C of an item the worker takes in, and `routing.stepped` lifts the worker to the rung it picks, but `judge_rung` reads only the routed item's R + C, which the archived route line holds. So when the worker takes in a harder item, the judge stays on a lower rung than the work, where a missed interrupt lets the worker settle a decision that is lilleman's (goal 1.2). The route must carry the highest R + C taken in, archived so a rerun keeps it.
|
||||
|
||||
### 111. Measure the chunks of a project that merges by squash or fast-forward, which `score-outcomes` skips today.
|
||||
|
||||
`score-outcomes` reads a chunk from a merge commit: its branch's round titles, and its change against the first parent. Two of the projects under `~/code` merge without merge commits, so their scorers see no finished item.
|
||||
@@ -159,6 +160,24 @@ The `worker:` decision is valid while review rounds per pass do not rise. Count
|
||||
|
||||
`score-outcomes` grounds R, S and C in finished chunks only. Where an item names files or units, their size bounds what the change can touch.
|
||||
|
||||
### 125. Give "record", "outcome" and "places" one meaning each across `bin/`, and rename `bin/larv_review/git.py` by what it holds.
|
||||
|
||||
Shape is the lowest dimension, so this item scores G 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
The inherited architect of PR #257's scoring run named `bin/reading_cost/measure.py:16` `Reading` and `bin/larv_review/git.py:6` `history_changes`, and found each word used for several concepts. "Record": the history writer `larv_review/record.py`, the judge's `loop_claude/project/records.py`, and `reading_cost/figures.py`'s `RECORD`. "Outcome": `transcript_archive/outcomes.py`, `score_outcomes/outcomes.py` `Outcome` and `rule_hook/rules.py` `Outcome`. "Places": `comprehension_history.Place` and `Reading.places`. `larv_review/git.py` holds history logic, not a git runner. Make `Reading` and `history_changes` easier to read.
|
||||
|
||||
### 114. Run git through `git_repo.py` in `rule_hook`, `metric_bench`, `reading_cost`, `stability_replay` and `loop_claude`, keeping rule-hook's guards as an option, so one module owns how a tool runs git.
|
||||
|
||||
Shape is the lowest dimension, so this item scores G 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
The comprehension seats on PR #254 found five git runners with different contracts: `git_repo.git`, `rule_hook/git.py`'s guarded one, `metric_bench/main.py`'s, `reading_cost/main.py`'s `located` and `loop_claude/effects.py`'s. PR #276 added a sixth, `stability_replay/main.py`'s `git`. The inherited architect of PR #257's scoring run named `bin/git_repo.py:8` `git` again. Make `git_repo.git` easier to read.
|
||||
|
||||
### 124. Group the shared modules at `bin/`'s root into packages named by purpose, so the root holds only launchers and stand-alone tools.
|
||||
|
||||
Shape is the lowest dimension, so this item scores G 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
PR #257's scoring run put Shape at 6.25, the lowest dimension. `bin/` holds about 30 entries: 6 launchers, 6 tool packages, 3 shared packages and 13 root modules. Two root modules are tools (`rank_todo.py`, `statusline.py`) and 11 are shared libraries, and nothing in the layout tells them apart; only README's import-root paragraph maps them. Candidate packages: git running and parsing, the todo table, and the comprehension history with round titles. The `.gitignore` allowlist and README follow the move.
|
||||
|
||||
### 120. Rewrite larv-review §3's "Round cap" and "Re-entry" as one table that says, for each kind of fix, which passes rerun and what a round reviews.
|
||||
|
||||
Junior A, Mid A and the maintainability senior of PR #257's scoring run named `skills/larv-review/SKILL.md:63` "Round cap" hardest, two of them with `:74` "Re-entry"; the inherited architect named `:71` "Cap". A reader holds the trigger table's "a fix, only where …" clauses, the cap, later rounds' scope and the prose, 🟢 and ❓ exceptions at once. Junior A could not say what a fix to a stability 🟡 that also touches a comment reruns. Make those sections easier to read.
|
||||
@@ -183,12 +202,6 @@ The paired ruling on PR #265 ruled worse. Make these places easier to read: `mea
|
||||
|
||||
Two seats of PR #257's scoring run assembled these terms from four files: `bin/larv_review/main.py`'s help, `skills/larv-review/SKILL.md:99`, `bin/comprehension_history.py:82` and `skills/comprehension-panel/seat-prompts.md`. "Records" is defined only in a comment at `bin/loop_claude/project/records.py:6`.
|
||||
|
||||
### 125. Give "record", "outcome" and "places" one meaning each across `bin/`, and rename `bin/larv_review/git.py` by what it holds.
|
||||
|
||||
Shape is the lowest dimension, so this item goes before 0.3.0's other items, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
The inherited architect of PR #257's scoring run named `bin/reading_cost/measure.py:16` `Reading` and `bin/larv_review/git.py:6` `history_changes`, and found each word used for several concepts. "Record": the history writer `larv_review/record.py`, the judge's `loop_claude/project/records.py`, and `reading_cost/figures.py`'s `RECORD`. "Outcome": `transcript_archive/outcomes.py`, `score_outcomes/outcomes.py` `Outcome` and `rule_hook/rules.py` `Outcome`. "Places": `comprehension_history.Place` and `Reading.places`. `larv_review/git.py` holds history logic, not a git runner. Make `Reading` and `history_changes` easier to read.
|
||||
|
||||
### 126. State when work has landed towards a release once, in `bin/larv_review/plan.py`, and have larv-review's help point to it.
|
||||
|
||||
Two seats of PR #257's scoring run named `bin/larv_review/plan.py:9` `scoring_run_due`. It reads the default branch's plan and the chunk's together, and the landed rule is written twice: in its docstring and in `bin/larv_review/main.py`'s help. Make `scoring_run_due` easier to read.
|
||||
@@ -209,22 +222,10 @@ Junior A and Mid A of PR #257's scoring run named `bin/shell_command.py:31` `seg
|
||||
|
||||
The entry holds 7 paragraphs under one title of about 70 words chaining three decisions: the ladder and bands, the worker below the project's rung with its reviewers, the routing figures and calls, delegation, and when the worker changes rung. A reader after one rule reads the whole entry. The prose pass of the chunk that split out the judge's rung asked for the rest. Once split, the delegation entry's title names the floor that `todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan…` puts under a subagent that files or scores items.
|
||||
|
||||
### 114. Run git through `git_repo.py` in `rule_hook`, `metric_bench`, `reading_cost`, `stability_replay` and `loop_claude`, keeping rule-hook's guards as an option, so one module owns how a tool runs git.
|
||||
|
||||
Shape is the lowest dimension, so this item goes before 0.3.0's other items, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
The comprehension seats on PR #254 found five git runners with different contracts: `git_repo.git`, `rule_hook/git.py`'s guarded one, `metric_bench/main.py`'s, `reading_cost/main.py`'s `located` and `loop_claude/effects.py`'s. PR #276 added a sixth, `stability_replay/main.py`'s `git`. The inherited architect of PR #257's scoring run named `bin/git_repo.py:8` `git` again. Make `git_repo.git` easier to read.
|
||||
|
||||
### 117. Give `todo_table.items` one way to say a plan has no items table, so no caller tells it from an empty plan by truthiness.
|
||||
|
||||
The comprehension seats on PR #254 found `items` returning a list, None or a Failure, and `larv_review/plan.py` `plan_reasons` reading None through `items(before) or []`, which works only because a Failure is truthy.
|
||||
|
||||
### 124. Group the shared modules at `bin/`'s root into packages named by purpose, so the root holds only launchers and stand-alone tools.
|
||||
|
||||
Shape is the lowest dimension, so this item goes before 0.3.0's other items, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
PR #257's scoring run put Shape at 6.25, the lowest dimension. `bin/` holds about 30 entries: 6 launchers, 6 tool packages, 3 shared packages and 13 root modules. Two root modules are tools (`rank_todo.py`, `statusline.py`) and 11 are shared libraries, and nothing in the layout tells them apart; only README's import-root paragraph maps them. Candidate packages: git running and parsing, the todo table, and the comprehension history with round titles. The `.gitignore` allowlist and README follow the move.
|
||||
|
||||
### 130. Move the vote counting out of `bin/larv_review/ruling.py`'s `votes`, so reading a votes file decides nothing.
|
||||
|
||||
Mid A of PR #257's scoring run named `bin/larv_review/ruling.py:8` `votes`. It calls `counted` while validating, to reject the maintainability senior's and Junior A's lines when Mid A and the inherited architect already agree overall: a ruling hidden in a parser. The counting rule is spread over `seats.py`, `ruling.py`, `comprehension_history.place_dimensions` and the help. Make `votes` easier to read.
|
||||
|
||||
Reference in New Issue
Block a user