Merge pull request 'Rank todo.md items by value per cost, with a Moves column naming how far each item moves each goal' (#283) from plan-148 into main

This commit was merged in pull request #283.
This commit is contained in:
2026-10-16 04:11:54 +02:00
13 changed files with 794 additions and 401 deletions
+1 -1
View File
@@ -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`, which ranks each blocker above the items it blocks; the table's order is the plan's only order
- todo.md: one table of items scored by the formula it states, each README achieve goal weighed by its position, the first heaviest, 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
+4 -1
View File
@@ -2,7 +2,10 @@
## Unreleased
- Every goal in `README.md` → Goals is marked `**Maintain:**`, a state to hold, or `**Achieve:**`, a direction to pursue. Each achieve goal has a signal, a counter-signal and a one-line reason under it. A change that breaks a maintain goal is redesigned or dropped, whatever it scores: `rules/todo-items.md` says so, and larv-review's goal alignment step no longer merges such a PR. `rules/goals-and-audience.md` states the form for every project's README; `rank_todo.py` still reads the goals as before. Expect larv-review to stop a PR on a maintain goal where it asked you before.
- Every goal in `README.md` → Goals is marked `**Maintain:**`, a state to hold, or `**Achieve:**`, a direction to pursue. Each achieve goal has a signal, a counter-signal and a one-line reason under it. A change that breaks a maintain goal is redesigned or dropped, whatever it scores: `rules/todo-items.md` says so, and larv-review's goal alignment step no longer merges such a PR. `rules/goals-and-audience.md` states the form for every project's README. Expect larv-review to stop a PR on a maintain goal where it asked you before.
- Reshape every project's `todo.md` to the new shape below: until it is reshaped, that is the project's only work, as it is while README.md lacks Goals and Audience, and `rank_todo.py` says so. First move every machine to this release: an older release rejects the new formula, so it fails on every reshaped `todo.md`. Then mark the README's goals `**Maintain:**` or `**Achieve:**`, and set a bar on the new scale below the score of every item to keep, since the old bar would drop most items. Until then, an old-shape `todo.md` still ranks by its own formula and weights.
- `todo.md` ranks items by value per cost: this setup's own plan uses `Score = 100 * V / (2**S + 8)`, where 8 is a chunk's fixed cost, about one size-3 change, and `rank_todo.py --help` shows it. A Moves column replaces A, G and Goals, naming each achieve goal an item moves and how far, such as `1.1 by 8, 1.2 by 5`. V sums each named goal's weight times its move. `rank_todo.py` weighs each achieve goal by its position in README.md, the first heaviest, so the goal weights table goes. An item names the most specific goal it moves, never a goal beside its own sub-goal. `rules/todo-items.md` and `rank_todo.py --help` show the new shape.
- An item that restores a maintain goal the project breaks today is exempt as `defect`, and its Moves may name that maintain goal, weighed as the heaviest achieve goal. A defect ranks by its score like any item. Only two kinds rank ahead of the rest of their release: questions first, since an answer may change other items, then security items.
## 0.1.0
+2 -2
View File
@@ -5,7 +5,7 @@
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
- **Until `README.md` has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. Both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count.
- **Plan `todo.md` as one scored table**: every item names the release that ships it. If `todo.md` has another shape, reshaping it is the chunk, and the human approves it.
- **Plan `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, and the human approves it.
- **When the next release has no items and no work has landed towards it, plan it as this chunk.** Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
- **When the next release has no items left and work has landed towards it, it is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix lands, into that release; never start a later release's items or plan a new one.
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that publishes nothing says so once.
@@ -18,7 +18,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
- **Remove a finished item's row and detail from `todo.md`, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record.
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
- **Open each `todo.md` item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and says nothing about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
- **File a security finding the moment it is found.** A security finding — a leaked credential, secret or PII, an auth bypass, an injection — goes under the next release, marked `security`, naming the exposure and the path it reaches. `~/.claude/bin/rank_todo.py` ranks it first in its release. Never among additive or nice-to-have items, never only in a chunk's summary, and never as a question about where it belongs: file it, say you did, and I will unmark it if I disagree. Fixing it inside an unrelated change is a separate call — say whether it is in the blast radius.
- **File a security finding the moment it is found.** A security finding — a leaked credential, secret or PII, an auth bypass, an injection — goes under the next release, marked `security`, naming the exposure and the path it reaches. `~/.claude/bin/rank_todo.py` ranks it first in its release, after only the open questions, which wait for me. Never among additive or nice-to-have items, never only in a chunk's summary, and never as a question about where it belongs: file it, say you did, and I will unmark it if I disagree. Fixing it inside an unrelated change is a separate call — say whether it is in the blast radius.
## Prose
+1 -1
View File
@@ -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", None),), ())
def todo(*rows: str) -> str:
+167 -73
View File
@@ -1,14 +1,14 @@
#!/usr/bin/env python3
"""Score todo.md's items by the formula and goal weights it states, and hold them to its bar.
"""Score todo.md's items by the formula it states, weighing each achieve goal by its position in README.md, and hold them to its bar.
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. 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.
question rows come first, then security rows, then the rest, each group 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:
@@ -16,21 +16,17 @@ A valid todo.md; ## Details and each item's detail are optional:
## Scoring
`Score = -R - S/4 + 2*A + 2*G*W`
`Score = 100 * V / (2**S + 8)`
`Bar = 9`
`Bar = 1`
`Next ID = 2`
| Goal | W |
|---|---|
| 1 | 1.00 |
## Items
| 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 |
| ID | Release | Blocked by | Exempt | Item | R | S | C | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|
| 1 | 0.1.0 | | | **Make the first thing work.** | 2 | 3 | 4 | 1 by 9 | 0 |
## Details
@@ -38,12 +34,19 @@ A valid todo.md; ## Details and each item's detail are optional:
What the tagline cannot say.
- The formula holds numbers, + - * / and parentheses over R, S, A, G and W.
- The formula holds numbers, + - * / ** and parentheses over R, S and V.
- V sums, over the goals in an item's Moves cell, each goal's weight times how far the item moves it.
README.md marks each goal **Maintain:** or **Achieve:**. The one ranked k of n achieve goals, in
reading order, a sub-goal such as 1.1 included, weighs (1/k) / (1 + 1/2 + ... + 1/n). Only an item
marked defect may name a maintain goal, the one it restores, which weighs as the heaviest achieve
goal.
- The bar is judged on the Score as shown, to one decimal.
- A new item takes Next ID, and Next ID then goes up by one; every ID stays below it.
- The goal weights list README.md's numbered goals in order, a sub-goal such as 1.1 included.
- An item's R, S, C, A and G are whole numbers from 1 to 10; Goals lists goal numbers, comma separated.
C, how hard the change is to get right, stays out of the formula.
- An item's R, S and C are whole numbers from 1 to 10. C, how hard the change is to get right, stays
out of the formula.
- An item's Moves cell is empty, or names each goal it moves and how far, a whole number from 1 to
10, such as `1.1 by 8, 1.2 by 5`: the most specific goal, and a parent only for a move none of its
sub-goals covers, so never a goal beside its own sub-goal. An empty cell scores V 0.
- An item's Exempt cell is empty, or names why the bar does not apply: decision, defect, owner,
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.
@@ -55,6 +58,9 @@ A valid todo.md; ## Details and each item's detail are optional:
- ## 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.
- A table in the old shape, with A, G and Goals columns in place of Moves, still ranks, by a formula
over R, S, A, G and W and a | Goal | W | table that weighs every README goal, W being the heaviest
cited goal's weight; ranking it says to reshape it.
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
@@ -66,24 +72,33 @@ import math
import pathlib
import re
import sys
import typing
from todo_table import BLOCKED_BY, cells, COLUMNS, DIVIDER, HEADER_START, Item, ITEMS_HEADER, items_table, parse_row, Table, table_rows
from todo_table import BLOCKED_BY, cells, HEADER_START, Item, items_table, MOVES, OLD_SHAPE, parse_row, Shape, shape_of, Table, table_rows
from failure import Failure
from markdown_text import FENCE, sections
from file_writes import replace_file
LARGEST_FORMULA = 200
LONGEST_FORMULA = 4 * LARGEST_FORMULA
OPERATORS = (ast.Add, ast.BinOp, ast.Div, ast.Expression, ast.Load, ast.Mult, ast.Sub, ast.UAdd, ast.UnaryOp, ast.USub)
VARIABLES = ("A", "G", "R", "S", "W")
OPERATORS = (ast.Add, ast.BinOp, ast.Div, ast.Expression, ast.Load, ast.Mult, ast.Pow, ast.Sub, ast.UAdd, ast.UnaryOp, ast.USub)
WEIGHTS_HEADER = "| Goal | W |"
# The Exempt reasons that rank ahead of the rest of their release, in this order: a question first, since its answer may change other items, then a security finding.
FIRST = {"question": 0, "security": 1}
# How README.md marks a goal; None where it marks it neither way.
Mark = typing.Literal["Maintain", "Achieve"] | None
RESHAPE = f"todo.md's items table is in the old shape, scoring A and G against goal weights todo.md states. Until todo.md has the shape rank_todo.py --help shows, reshaping it is the project's only work, as ~/.claude/CLAUDE.md → 'Working loop' says: mark README.md's goals **Maintain:** or **Achieve:**, name each item's {MOVES}, and set the bar below the score of every item to keep"
@dataclasses.dataclass(frozen=True)
class Scoring:
shape: Shape
formula: ast.Expression
bar: float
next_id: int
# README.md's goals in reading order, each with its mark.
goals: dict[str, Mark]
# The weight of each goal an item may name: in OLD_SHAPE every goal, at the weight todo.md states; else each goal goal_weights weighs.
weights: dict[str, float]
@@ -91,8 +106,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]
# What ranking prints and --check does not: an old-shape table's call to reshape, a README with no achieve goal, and each dropped blocker ID, since a mistyped ID drops the same way.
notes: list[str]
def main(argv: list[str]) -> int:
@@ -118,7 +133,7 @@ def main(argv: list[str]) -> int:
unwritten = write(todo, ranked.text)
if unwritten:
return fail(unwritten)
for line in ranked.dropped + ranked.under_bar:
for line in ranked.notes + ranked.under_bar:
print(f"{todo}: {line}", file=sys.stderr)
return 1 if ranked.under_bar else 0
@@ -171,28 +186,44 @@ def write(path: pathlib.Path, text: str) -> Failure | None:
def rank(text: str, readme: str, decisions: str) -> Ranked | Failure:
lines = text.split("\n")
scoring = read_scoring(text, lines, readme)
if isinstance(scoring, Failure):
return scoring
table = read_items(lines, scoring)
table = read_table(lines)
if isinstance(table, Failure):
return table
items, found = table
shape = shape_of(table.columns)
scoring = read_scoring(text, lines, readme, shape)
if isinstance(scoring, Failure):
return scoring
items = read_items(table, scoring)
if isinstance(items, Failure):
return items
if uncited := check_citations(items, decisions):
return uncited
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])
ranked = rank_details(rewrite_table(lines, table, shape, scored), [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]
return Ranked(ranked, under_bar, notes(items, scoring))
def rewrite_table(lines: list[str], table: Table, shape: Shape, scored: list[tuple[Item, float]]) -> str:
"""lines with the table's rows in scored's order, under a header naming every column of shape, so a table from before BLOCKED_BY joined gains the column."""
columns = shape.columns
header = ["| " + " | ".join(columns) + " |", "|" + "---|" * len(columns)]
rows = [render_item(item, value, shape) for item, value in scored]
return "\n".join(lines[:table.header] + header + rows + lines[table.start + len(table.rows):])
def notes(items: list[Item], scoring: Scoring) -> list[str]:
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)
if scoring.shape is OLD_SHAPE:
return [RESHAPE] + dropped
# Printed so the under-bar lines it causes do not read as items of low value.
unweighed = [] if any(scoring.weights.values()) else ["README.md marks no goal **Achieve:**, so every item scores V 0"]
return unweighed + dropped
def blocked_through(id_: int, items: list[Item]) -> set[int]:
@@ -206,14 +237,14 @@ def blocked_through(id_: int, items: list[Item]) -> set[int]:
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."""
"""Each item with its score, by release, then questions and security findings 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)
value = score(scoring.formula, item, scoring)
if isinstance(value, Failure):
return value
by_score.append((item, value))
by_score.sort(key=lambda pair: (pair[0].release, pair[0].exempt != "security", -pair[1], pair[0].id))
by_score.sort(key=lambda pair: (pair[0].release, FIRST.get(pair[0].exempt, len(FIRST)), -pair[1], pair[0].id))
return blockers_first(by_score)
@@ -223,13 +254,11 @@ def under_the_bar(item: Item, value: float, bar: float, items: list[Item]) -> st
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" not in lines:
return Failure("todo.md is not in the scored-table format; rank_todo.py --help shows a valid one")
def read_scoring(text: str, lines: list[str], readme: str, shape: Shape) -> Scoring | Failure:
goals = readme_goals(readme)
if isinstance(goals, Failure):
return goals
formula = parse_formula(stated(text, "Score"))
formula = parse_formula(stated(text, "Score"), variables(shape))
if isinstance(formula, Failure):
return formula
bar = number(stated(text, "Bar"), "the bar")
@@ -238,14 +267,22 @@ def read_scoring(text: str, lines: list[str], readme: str) -> Scoring | Failure:
next_id = stated(text, "Next ID")
if isinstance(next_id, Failure) or not re.fullmatch(r"[0-9]+", next_id):
return next_id if isinstance(next_id, Failure) else Failure(f"Next ID {next_id!r} is not a whole number")
weights = parse_weights(lines, goals)
numbers = [number for number, _ in goals]
if shape is OLD_SHAPE:
weights = parse_weights(lines, numbers)
elif WEIGHTS_HEADER in lines:
weights = Failure(f"todo.md holds a goal weights table beside a {MOVES} column; drop the table, since rank_todo.py weighs each achieve goal by its position in README.md")
else:
weights = goal_weights(goals)
if isinstance(weights, Failure):
return weights
return Scoring(formula, bar, int(next_id), weights)
return Scoring(shape, formula, bar, int(next_id), dict(goals), weights)
def read_items(lines: list[str], scoring: Scoring) -> tuple[list[Item], Table] | Failure:
"""The items, and the table they were read from."""
def read_table(lines: list[str]) -> Table | Failure:
"""The items table, held to its shape's columns and alone under ## Items."""
if "## Items" not in lines:
return Failure("todo.md is not in the scored-table format; rank_todo.py --help shows a valid one")
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")
@@ -254,14 +291,26 @@ def read_items(lines: list[str], scoring: Scoring) -> tuple[list[Item], Table] |
# 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
return unknown_columns(table) or outside_items(lines, table) or table
def unknown_columns(table: Table) -> Failure | None:
"""Why ranking, which writes only the columns of the table's shape, would drop one of the table's columns; None when it would drop none."""
known = shape_of(table.columns).columns
unknown = [column for column in table.columns if column not in known]
if old := [column for column in unknown if column in OLD_SHAPE.columns]:
listed = old[0] if len(old) == 1 else f"{', '.join(old[:-1])} and {old[-1]}"
kind = f"a column of the old shape that {MOVES} replaced; drop it" if len(old) == 1 else f"columns of the old shape that {MOVES} replaced; drop them"
return Failure(f"todo.md's items table has {listed}, {kind}")
if unknown:
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(known)}. Rename it, or move this machine to the release that added it")
return None
def read_items(table: Table, scoring: Scoring) -> list[Item] | Failure:
items = []
for row in table.rows:
item = parse_item(row, scoring.weights, table.columns)
item = parse_item(row, scoring, table)
if isinstance(item, Failure):
return item
items.append(item)
@@ -273,7 +322,7 @@ def read_items(lines: list[str], scoring: Scoring) -> tuple[list[Item], Table] |
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
return items
def outside_items(lines: list[str], table: Table) -> Failure | None:
@@ -343,25 +392,37 @@ def check_citations(items: list[Item], decisions: str) -> Failure | None:
return None
def readme_goals(readme: str) -> list[str] | Failure:
"""The numbers of README.md's goals in reading order, a sub-goal as 4.1."""
def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
"""README.md's goals in reading order: each one's number, a sub-goal as 4.1, and its mark, Maintain, Achieve or None."""
found = sections(readme).get("Goals", [])
if len(found) != 1:
return Failure(f"README.md has ## Goals {len(found)} times; it needs it once")
goals: list[str] = []
goals: list[tuple[str, Mark]] = []
path: list[tuple[int, str]] = []
for indent, position in re.findall(r"^([ \t]*)(\d+)\. ", found[0].expandtabs(4), re.M):
for indent, position, mark in re.findall(r"^([ \t]*)(\d+)\. (?:\*\*(Maintain|Achieve):\*\*)?", found[0].expandtabs(4), re.M):
while path and path[-1][0] >= len(indent):
path.pop()
path.append((len(indent), position))
goals.append(".".join(part for _, part in path))
goals.append((".".join(part for _, part in path), typing.cast(Mark, mark or None)))
numbers = [number for number, _ in goals]
if not goals:
return Failure("README.md's ## Goals has no numbered goal")
if len(set(goals)) < len(goals):
return Failure(f"README.md's ## Goals numbers {', '.join(goals)}; number each goal by its position")
if len(set(numbers)) < len(numbers):
return Failure(f"README.md's ## Goals numbers {', '.join(numbers)}; number each goal by its position")
return goals
def goal_weights(goals: list[tuple[str, Mark]]) -> dict[str, float] | Failure:
"""Each achieve goal's sum-reciprocal weight: the one ranked k of n in reading order weighs (1/k) / (1 + 1/2 + ... + 1/n). Each maintain goal weighs as the heaviest achieve goal, since a broken one outranks any achieve goal; only a defect that restores it may name it. Every weight is 0 where README.md marks no goal **Achieve:**, so every item scores V 0 and only an exempt one passes the bar."""
if unmarked := [number for number, mark in goals if mark is None]:
return Failure(f"README.md's goal {unmarked[0]} is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score")
achieve = [number for number, mark in goals if mark == "Achieve"]
harmonic = sum(1 / rank for rank in range(1, len(achieve) + 1))
weights = {number: 1 / rank / harmonic for rank, number in enumerate(achieve, 1)}
heaviest = max(weights.values(), default=0.0)
return weights | {number: heaviest for number, mark in goals if mark == "Maintain"}
def cited_items(decisions: str) -> list[int]:
return [int(id_) for cited in re.findall(r"`todo\.md` items? (\d+(?:(?:, | and )\d+)*)", decisions) for id_ in re.findall(r"\d+", cited)]
@@ -373,7 +434,7 @@ def stated(text: str, name: str) -> str | Failure:
return found[0]
def parse_formula(source: str | Failure) -> ast.Expression | Failure:
def parse_formula(source: str | Failure, variables: tuple[str, ...]) -> ast.Expression | Failure:
if isinstance(source, Failure):
return source
# Deep nesting makes the parser itself run out of memory before LARGEST_FORMULA can count the parts.
@@ -388,13 +449,13 @@ def parse_formula(source: str | Failure) -> ast.Expression | Failure:
return Failure(f"the formula {source!r} holds more than {LARGEST_FORMULA} parts")
for node in nodes:
numeric = isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool) and abs(node.value) < 1e300
if not (isinstance(node, OPERATORS) or numeric or (isinstance(node, ast.Name) and node.id in VARIABLES)):
return Failure(f"the formula {source!r} may hold only numbers, {', '.join(VARIABLES)}, + - * / and parentheses")
if not (isinstance(node, OPERATORS) or numeric or (isinstance(node, ast.Name) and node.id in variables)):
return Failure(f"the formula {source!r} may hold only numbers, {', '.join(variables)}, + - * / ** and parentheses")
return tree
def evaluate(node: ast.AST, values: dict[str, float]) -> float:
"""Evaluates a tree parse_formula accepted; a division by zero gives nan."""
"""Evaluates a tree parse_formula accepted; a division by zero, and a power that overflows or has no real value, give nan."""
match node:
case ast.Expression(body):
return evaluate(body, values)
@@ -415,12 +476,37 @@ def evaluate(node: ast.AST, values: dict[str, float]) -> float:
case ast.BinOp(left, ast.Div(), right):
divisor = evaluate(right, values)
return evaluate(left, values) / divisor if divisor else math.nan
case ast.BinOp(left, ast.Pow(), right):
# math.pow raises on a negative base with a fractional exponent, zero to a negative power, and overflow; one catch covers all three.
base, exponent = evaluate(left, values), evaluate(right, values)
# A nan from a zero divisor stays nan, though math.pow(1, nan) and math.pow(nan, 0) give 1.
if math.isnan(base) or math.isnan(exponent):
return math.nan
try:
return math.pow(base, exponent)
except (OverflowError, ValueError):
return math.nan
return math.nan
def score(formula: ast.Expression, item: Item, weights: dict[str, float]) -> float | Failure:
# An item serving several goals is weighed by the heaviest; summing them would reward citing more.
value = evaluate(formula, {**item.scores, "W": max(weights[goal] for goal in item.goals)})
def goal_term(shape: Shape) -> str:
"""The name of the formula's goal term, which score builds: W in OLD_SHAPE, V in the current shape."""
return "W" if shape is OLD_SHAPE else "V"
def variables(shape: Shape) -> tuple[str, ...]:
"""The names the formula may use: the shape's scores but C, which stays out of the formula, and its goal term."""
return tuple(sorted({*shape.score_columns} - {"C"} | {goal_term(shape)}))
def score(formula: ast.Expression, item: Item, scoring: Scoring) -> float | Failure:
if goal_term(scoring.shape) == "W":
# The old shape weighs an item by its heaviest cited goal.
term = max(scoring.weights[goal] for goal, _ in item.moves)
else:
# Only an OLD_SHAPE item names a goal without a move.
term = sum(scoring.weights[goal] * (by or 0) for goal, by in item.moves)
value = evaluate(formula, {**item.scores, goal_term(scoring.shape): term})
return value if math.isfinite(value) else Failure(f"the formula gives item {item.id} no finite score")
@@ -455,18 +541,26 @@ def parse_weights(lines: list[str], goals: list[str]) -> dict[str, float] | Fail
return weights
def parse_item(row: str, weights: dict[str, float], columns: tuple[str, ...]) -> Item | Failure:
item = parse_row(row, columns)
def parse_item(row: str, scoring: Scoring, table: Table) -> Item | Failure:
item = parse_row(row, table)
if isinstance(item, Failure):
return item
if unknown := [goal for goal in item.goals if goal not in weights]:
return Failure(f"item {item.id} cites goal {', '.join(unknown)}, which the goal weights do not list")
if scoring.shape is OLD_SHAPE:
if unknown := [goal for goal, _ in item.moves if goal not in scoring.weights]:
return Failure(f"item {item.id} cites goal {', '.join(unknown)}, which the goal weights do not list")
return item
for goal, _ in item.moves:
if goal not in scoring.goals:
return Failure(f"item {item.id} cites goal {goal}, which README.md's ## Goals does not number")
if scoring.goals[goal] == "Maintain" and item.exempt != "defect":
return Failure(f"item {item.id} cites goal {goal}, a maintain goal, which only a defect that restores it may name; name the achieve goals the item moves")
return item
def render_item(item: Item, value: float) -> str:
scores = " | ".join(str(item.scores[name]) for name in "RSCAG")
return f"| {item.id} | {release_name(item)} | {', '.join(map(str, item.blocked_by))} | {item.exempt} | {item.tagline} | {scores} | {', '.join(item.goals)} | {value:.1f} |"
def render_item(item: Item, value: float, shape: Shape) -> str:
"""The item's row, each cell under its column of shape."""
written = {"ID": str(item.id), "Release": release_name(item), BLOCKED_BY: ", ".join(map(str, item.blocked_by)), "Exempt": item.exempt, "Item": item.tagline, **{name: str(item.scores[name]) for name in shape.score_columns}, shape.goals_column: shape.write_goals(item.moves), "Score": f"{value:.1f}"}
return "| " + " | ".join(written[column] for column in shape.columns) + " |"
def rank_details(text: str, items: list[Item]) -> str | Failure:
+1 -1
View File
@@ -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", None),), ())
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:
+197 -49
View File
@@ -13,7 +13,7 @@ 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"
README = "# P\n\n## Goals\n\n1. **Achieve:** Fast.\n2. **Maintain:** Correct.\n 1. **Achieve:** Tested.\n\n## Audience\n\nMe.\n"
DECISIONS = "## A choice\n\nStands until `todo.md` item 5 ends it.\n"
@@ -21,6 +21,41 @@ TODO = """# todo
## Scoring
`Score = 100 * V / 2**S`
`Bar = 2`
`Next ID = 6`
## Items
| ID | Release | Blocked by | Exempt | Item | R | S | C | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 1 by 9 | 0 |
| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 2.1 by 1 | 0 |
| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 2.1 by 8, 1 by 6 | 0 |
| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 9 | 2 | 3 | 2.1 by 1 | 0 |
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 2.1 by 1 | 0 |
## Details
### 1. stale heading
Later detail.
### 3. Make it fast.
Fast detail.
## Notes
Kept as written.
"""
OLD_SHAPE = """# todo
## Scoring
`Score = -R - S/4 + 2*A + 2*G*W`
`Bar = 9`
@@ -65,56 +100,111 @@ 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 | 2.1 by 1 | 8.3 |
| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 2.1 by 8, 1 by 6 | 2.6 |
| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 2.1 by 1 | 2.1 |
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 2.1 by 1 | 1.0 |
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 1 by 9 | 300.0 |
""", 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, [])
self.assertEqual(ranked.notes, [])
self.assertEqual(self.ranked(ranked.text), ranked)
def test_weighs_each_achieve_goal_by_its_sum_reciprocal_rank(self):
readme = "## Goals\n\n1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
self.assertEqual({goal: round(weight, 4) for goal, weight in rank_todo.goal_weights(rank_todo.readme_goals(readme)).items()}, {"1": 0.5455, "1.1": 0.5455, "1.2": 0.2727, "2": 0.1818})
todo = TODO.replace("2.1 by 8, 1 by 6", "1.2 by 2, 2 by 3").replace("| 2.1 by 1 |", "| 1 by 1 |")
ranked = self.ranked(todo, readme)
self.assertIn("| **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 1.2 by 2, 2 by 3 | 0.4 |", ranked.text)
def test_scores_an_item_that_moves_no_goal_zero(self):
ranked = self.ranked(TODO.replace("| 2 | 4 | 3 | 2.1 by 1 |", "| 2 | 4 | 3 | |"))
self.assertIn("| **Tighten the tests.** | 2 | 4 | 3 | | 0.0 |", ranked.text)
self.assertEqual(ranked.under_bar, ["item 2 scores 0.0, under the bar 2; delete it, or mark it with a reason the bar does not apply"])
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 | 2.1 by 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, 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"])
ranked = self.ranked(TODO.replace("`Bar = 2`", "`Bar = 2.5`"))
self.assertEqual(ranked.under_bar, ["item 2 scores 2.1, under the bar 2.5; delete it, or mark it with a reason the bar does not apply"])
self.assertEqual(self.ranked(TODO.replace("`Bar = 2`", "`Bar = 2.1`")).under_bar, [])
blocking = self.ranked(TODO.replace("`Bar = 2`", "`Bar = 2.5`").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 2.1, under the bar 2.5; 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"])
self.assertEqual(rank_todo.readme_goals(README.replace(" 1.", "\t1.")), ["1", "2", "2.1"])
self.assertEqual(rank_todo.readme_goals(README.replace("2. Correct.", "```\n## Goals\n```\n2. Correct.")), ["1", "2", "2.1"])
self.assertIsInstance(rank_todo.readme_goals(README.replace("2. Correct.", "1. Correct.")), Failure)
self.assertEqual(rank_todo.readme_goals(README), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
self.assertEqual(rank_todo.readme_goals(README.replace(" 1.", "\t1.")), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
self.assertEqual(rank_todo.readme_goals(README.replace("2. **Maintain:** Correct.", "```\n## Goals\n```\n2. Correct.")), [("1", "Achieve"), ("2", None), ("2.1", "Achieve")])
self.assertEqual(rank_todo.readme_goals(README.replace("2. **Maintain:**", "1. **Maintain:**")), Failure("README.md's ## Goals numbers 1, 1, 1.1; number each goal by its position"))
self.assertEqual(rank_todo.readme_goals("## Goals\n\n1. **Achieve:** A.\n 1. **Achieve:** B.\n\t2. **Achieve:** C.\n"), [("1", "Achieve"), ("1.1", "Achieve"), ("1.2", "Achieve")])
def test_prints_the_positional_weights_when_they_stop_listing_the_readmes_goals(self):
failure = self.ranked(readme=README.replace(" 1. Tested.", " 1. Tested.\n3. Small."))
self.assertIn("| 1 | 1.00 |\n| 2 | 0.75 |\n| 2.1 | 0.50 |\n| 3 | 0.25 |", failure.reason)
def test_refuses_a_goal_it_cannot_weigh(self):
cases = {
(TODO.replace("2.1 by 8, 1 by 6", "1 by 8, 2 by 6"), README): "item 3 cites goal 2, a maintain goal, which only a defect that restores it may name; name the achieve goals the item moves",
(TODO.replace("2.1 by 8, 1 by 6", "2.1 by 8, 3 by 6"), README): "item 3 cites goal 3, which README.md's ## Goals does not number",
(TODO.replace("2.1 by 8, 1 by 6", "2.1 by 8, 2.1 by 6"), README): "item 3 cites goal 2.1 twice; name each goal once",
(TODO, README.replace("**Maintain:** Correct", "Correct")): "README.md's goal 2 is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score",
}
for (todo, readme), reason in cases.items():
with self.subTest(reason=reason):
self.assertEqual(self.ranked(todo, readme), Failure(reason))
def test_ranks_questions_first_then_security_whatever_they_score_and_a_defect_by_its_score(self):
todo = TODO.replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | defect |").replace("| 9 | 2 | 3 | 2.1 by 1 |", "| 9 | 8 | 3 | 2.1 by 1 |").replace("| 5 | 0.1.0 | | decision |", "| 5 | 0.1.0 | | question |")
rows = [line.split(" | ")[0] for line in self.ranked(todo, decisions="").text.splitlines() if line.startswith("| ") and " | 0." in line]
self.assertEqual(rows, ["| 5", "| 4", "| 3", "| 2", "| 1"])
def test_weighs_the_maintain_goal_a_defect_restores_as_the_heaviest_achieve_goal(self):
ranked = self.ranked(TODO.replace("| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 2.1 by 1 |", "| 2 | 0.1.0 | | defect | **Tighten the tests.** | 2 | 4 | 3 | 2 by 3 |"))
self.assertIn("| **Tighten the tests.** | 2 | 4 | 3 | 2 by 3 | 12.5 |", ranked.text)
def test_refuses_a_goal_named_beside_its_own_sub_goal(self):
readme = "## Goals\n\n1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
todo = TODO.replace("2.1 by 8, 1 by 6", "1.2 by 2, 1 by 3").replace("| 2.1 by 1 |", "| 2 by 1 |")
self.assertEqual(self.ranked(todo, readme), Failure("item 3 names goal 1 and its sub-goal 1.2; name one, never both: the sub-goal where the move serves it, else the parent"))
self.assertIsInstance(self.ranked(todo.replace("1.2 by 2, 1 by 3", "1.2 by 2, 2 by 3"), readme), rank_todo.Ranked)
def test_scores_every_item_zero_where_readme_marks_no_goal_achieve(self):
ranked = self.ranked(TODO.replace("2.1 by 8, 1 by 6", "").replace("| 2.1 by 1 |", "| |").replace("| 1 by 9 |", "| |"), README.replace("**Achieve:**", "**Maintain:**"))
self.assertEqual([line.split(" scores ")[0] for line in ranked.under_bar], ["item 2", "item 3", "item 1"])
self.assertEqual(ranked.notes, ["README.md marks no goal **Achieve:**, so every item scores V 0"])
def test_accepts_a_move_of_ten_and_a_variable_base(self):
ranked = self.ranked(TODO.replace("| 1 by 9 |", "| 1 by 10 |").replace("100 * V / 2**S", "V * S ** 2"))
self.assertIn("| **Ship the later thing.** | 1 | 1 | 3 | 1 by 10 | 6.7 |", ranked.text)
def test_asks_to_drop_a_goal_weights_table_from_a_table_with_moves(self):
weighted = TODO.replace("## Items\n", "| Goal | W |\n|---|---|\n| 1 | 1.00 |\n\n## Items\n")
self.assertEqual(self.ranked(weighted), Failure("todo.md holds a goal weights table beside a Moves column; drop the table, since rank_todo.py weighs each achieve goal by its position in README.md"))
def test_refuses_a_formula_that_is_more_than_arithmetic_over_the_scores(self):
for formula in ("__import__('os')", "R.real", "X + 1", "C + 1", "R ** 2", "R +", "R / (S - 2)", "R\x00", "1" * 400, " + ".join(["R"] * 300), "-" * 100000 + "R"):
for formula in ("__import__('os')", "R.real", "X + 1", "C + 1", "A + V", "G + V", "W * V", "R ^ 2", "R +", "R / (S - 2)", "R\x00", "1" * 400, " + ".join(["R"] * 300), "-" * 100000 + "R", "10 ** 10 ** 10", "(-8) ** (1 / 3)", "0 ** -1"):
with self.subTest(formula=formula):
self.assertIsInstance(self.ranked(TODO.replace("-R - S/4 + 2*A + 2*G*W", formula)), Failure)
def test_asks_for_a_c_column_in_a_table_without_one(self):
legacy = TODO.split("## Items")[0] + "## Items\n\n| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|\n| 2 | 0.1.0 | | **Tighten the tests.** | 2 | 4 | 5 | 5 | 2.1 | 0 |\n"
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")
self.assertIsInstance(self.ranked(TODO.replace("100 * V / 2**S", formula)), Failure)
self.assertIn("| 1 by 9 | 2.0 |", self.ranked(TODO.replace("100 * V / 2**S", "R + S / S")).text)
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "1 ** (1 / (S - S))")), Failure("the formula gives item 1 no finite score"))
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "(1 / (S - S)) ** 0")), Failure("the formula gives item 1 no finite score"))
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "W")), Failure("the formula 'W' may hold only numbers, R, S, V, + - * / ** and parentheses"))
self.assertEqual(self.ranked(TODO.replace("2.1 by 8, 1 by 6", "2.1: 8, 1: 6")), Failure("item 3's Moves '2.1: 8, 1: 6' is not empty or goals such as `1.1 by 8, 1.2 by 5`, each moved by a whole number from 1 to 10"))
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 | 2.1 by 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",
"| 2 | 4 | 3 | 2.1 by 1 |": "| 2 | 4 | 11 | 2.1 by 1 |",
"Tighten the tests.** | 2 | 4 | 3 | 2.1 by 1": "Tighten the tests.** | 2 | 4 | 3 | 2.1 by 11",
"Move the writes out.** | 5 | 5 | 3 | 2.1 by 1": "Move the writes out.** | 5 | 5 | 3 | 2.1 by 0",
"2.1 by 8, 1 by 6": "2.1: 8, 1: 6",
"2.1 by 8, 1 by 6 ": "2.1 by 8,1 by 6 ",
"| 3 | 8 | 3 | 2.1 by 8, 1 by 6 |": "| 3 | 8 | 3 | 2.1, 1 |",
row + "\n": row.replace("4 | 3", "4 | ²") + "\n",
"| 2.1 by 1 | 0 |\n\n## Details": "| 2.1 by 1 | 0 |\n\n| 9 | 0.1.0 | | | **Stray.** | 1 | 1 | 3 | 1 by 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`",
@@ -122,25 +212,71 @@ class Rank(unittest.TestCase):
"| 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`",
"`Bar = 2`": "`Bar = nan`",
"## Items\n\n| ID | Release | Blocked by |": "## Plan\n\n| ID | Release |",
}
for old, new in broken.items():
with self.subTest(new=new):
self.assertIn(old, TODO)
self.assertIsInstance(self.ranked(TODO.replace(old, new)), Failure)
class OldShape(unittest.TestCase):
"""A table with A, G and Goals, from before the Moves column, ranks by the formula and goal weights it states until its project reshapes it."""
def ranked(self, todo=OLD_SHAPE, readme=README):
return rank_todo.rank(todo, readme, DECISIONS)
def test_scores_by_the_stated_weights_and_says_to_reshape(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 |
""", ranked.text)
self.assertEqual(ranked.notes, [rank_todo.RESHAPE])
self.assertEqual(self.ranked(ranked.text), ranked)
unmarked = "# P\n\n## Goals\n\n1. Fast.\n2. Correct.\n 1. Tested.\n"
self.assertEqual(self.ranked(readme=unmarked), ranked)
def test_prints_the_positional_weights_when_they_stop_listing_the_readmes_goals(self):
failure = self.ranked(readme=README.replace(" 1. **Achieve:** Tested.", " 1. **Achieve:** Tested.\n3. Small."))
self.assertIn("| 1 | 1.00 |\n| 2 | 0.75 |\n| 2.1 | 0.50 |\n| 3 | 0.25 |", failure.reason)
def test_refuses_an_item_citing_a_goal_the_weights_do_not_list(self):
self.assertEqual(self.ranked(OLD_SHAPE.replace("| 2.1, 1 | 0 |", "| 2.1, 9 | 0 |")), Failure("item 3 cites goal 9, which the goal weights do not list"))
def test_refuses_a_formula_over_v(self):
self.assertEqual(self.ranked(OLD_SHAPE.replace("-R - S/4 + 2*A + 2*G*W", "V")), Failure("the formula 'V' may hold only numbers, A, G, R, S, W, + - * / ** and parentheses"))
def test_asks_for_a_c_column_in_a_table_without_one(self):
legacy = OLD_SHAPE.split("## Items")[0] + "## Items\n\n| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|\n| 2 | 0.1.0 | | **Tighten the tests.** | 2 | 4 | 5 | 5 | 2.1 | 0 |\n"
self.assertEqual(rank_todo.rank(legacy, README, "").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_table_with_both_moves_and_goals(self):
both = OLD_SHAPE.replace("| Goals | Score |\n|---|", "| Goals | Moves | Score |\n|---|---|").replace(" | 0 |\n", " | 1 by 1 | 0 |\n")
self.assertEqual(self.ranked(both), Failure("todo.md's items table has A, G and Goals, columns of the old shape that Moves replaced; drop them"))
one = TODO.replace("| Moves | Score |\n|---|", "| Moves | G | Score |\n|---|---|").replace(" | 0 |\n", " | 1 | 0 |\n")
self.assertEqual(self.ranked(one), Failure("todo.md's items table has G, a column of the old shape that Moves replaced; drop it"))
def test_names_the_goals_column_a_table_misspells_by_its_shape(self):
misspelt = TODO.replace("| C | Moves |", "| C | Move |")
self.assertEqual(rank_todo.rank(misspelt, README, DECISIONS), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
self.assertEqual(todo_table.items(misspelt), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
self.assertEqual(self.ranked(OLD_SHAPE.replace("| G | Goals |", "| G | Goal |")), Failure("todo.md's items table has no Goals column; rank_todo.py --help shows a valid one"))
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 |
self.assertIn("""| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 9 | 2 | 3 | 2.1 by 1 | 8.3 |
| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 2.1 by 1 | 2.1 |
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 2.1 by 1 | 1.0 |
| 3 | 0.1.0 | 2, 5 | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 2.1 by 8, 1 by 6 | 2.6 |
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 1 by 9 | 300.0 |
""", ranked.text)
self.assertEqual(self.ranked(ranked.text), ranked)
@@ -154,11 +290,11 @@ class Blockers(unittest.TestCase):
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 |")
finished = TODO.replace("| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 9 | 2 | 3 | 2.1 by 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, [])
self.assertEqual(ranked.notes, ["item 2: dropped 4 from its Blocked by; the table no longer holds it"])
self.assertEqual(self.ranked(ranked.text).notes, [])
def test_refuses_a_blocker_in_a_later_release_a_loop_and_an_id_past_next_id(self):
cases = {
@@ -175,15 +311,17 @@ class Blockers(unittest.TestCase):
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 = 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))
unscored = TODO.replace(" | Score |", " |").replace("|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|").replace(" | 0 |\n", " |\n")
self.assertEqual(self.ranked(unscored), 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"))
extra = TODO.replace("| Moves | Score |\n|---|", "| Moves | 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, Moves, 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 = 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")
@@ -191,7 +329,7 @@ class Blockers(unittest.TestCase):
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"):
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 by 1 | 0 |\n\n## Details", "| 2.1 by 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)
@@ -202,14 +340,14 @@ class Blockers(unittest.TestCase):
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"
header = "| ID | Release | Blocked by | Exempt | Item | R | S | C | Moves | 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")
repeated = TODO.replace("| Moves | Score |\n|---|", "| Moves | 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"), [])
header = "| ID | Release | Blocked by | Exempt | Item | R | S | C | Moves | 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"))
@@ -235,12 +373,22 @@ class Main(unittest.TestCase):
pathlib.Path(temp, "README.md").unlink()
self.assertEqual(self.run_main(str(todo)), (1, f"{temp}/README.md: not found; rank_todo.py weighs goals from the README.md beside todo.md\n"))
def test_says_to_reshape_an_old_shape_table_but_passes_the_check(self):
with tempfile.TemporaryDirectory() as temp:
todo = pathlib.Path(temp, "todo.md")
todo.write_text(OLD_SHAPE)
pathlib.Path(temp, "README.md").write_text(README)
pathlib.Path(temp, "docs").mkdir()
pathlib.Path(temp, "docs", "decisions.md").write_text(DECISIONS)
self.assertEqual(self.run_main(str(todo)), (0, f"{todo}: {rank_todo.RESHAPE}\n"))
self.assertEqual(self.run_main("--check", str(todo)), (0, ""))
def test_shows_a_valid_file_in_help_and_names_arguments_it_cannot_read(self):
self.assertEqual(self.run_main("--help")[0], 0)
skeleton = "\n".join(line[4:] for line in rank_todo.__doc__.split("\n") if line.startswith(" "))
ranked = rank_todo.rank(skeleton, "## Goals\n\n1. Work.\n", "")
ranked = rank_todo.rank(skeleton, "## Goals\n\n1. **Achieve:** Work.\n", "")
self.assertIsInstance(ranked, rank_todo.Ranked)
self.assertEqual(ranked.under_bar, [])
self.assertEqual((ranked.under_bar, ranked.notes), ([], []))
self.assertEqual(self.run_main("--fix"), (1, "rank_todo.py: cannot read the arguments --fix; usage: rank_todo.py [--check] [todo.md]\n"))
+105 -23
View File
@@ -1,21 +1,73 @@
import dataclasses
import re
import typing
from failure import Failure
# Each of R, S, C, A and G runs from 1 to TOP_SCORE.
# Each score a Shape names, and each goal's move, runs from 1 to TOP_SCORE.
TOP_SCORE = 10
EXEMPTIONS = ("", "decision", "defect", "owner", "principle", "question", "security")
# 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) + " |"
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.
# The column naming each achieve goal an item moves and how far, such as `1.1 by 8, 1.2 by 5`.
MOVES = "Moves"
# How the items table's header opens, which tells it from any other table in todo.md.
HEADER_START = "| ID | Release |"
# Each goal an item names, in its order, with how far the item moves it; None in OLD_SHAPE, whose Goals cell names no move.
Moves = tuple[tuple[str, int | None], ...]
@dataclasses.dataclass(frozen=True)
class Shape:
"""A shape of the items table: its columns, and how its goals cell reads and writes."""
# The score columns, in the order the table holds them.
score_columns: tuple[str, ...]
# The column naming the goals an item serves; read_goals reads it, given the item's ID to name in a failure, and write_goals writes it back.
goals_column: str
read_goals: typing.Callable[[str, str], Moves | Failure]
write_goals: typing.Callable[[Moves], str]
@property
def columns(self) -> tuple[str, ...]:
"""Every column of the shape, 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."""
return ("ID", "Release", BLOCKED_BY, "Exempt", "Item", *self.score_columns, self.goals_column, "Score")
@property
def needed(self) -> tuple[str, ...]:
"""The columns without which no row can be read: a missing BLOCKED_BY reads as blocked by nothing, a missing C as no C, and a missing Score as no score yet."""
return tuple(column for column in self.columns if column not in (BLOCKED_BY, "C", "Score"))
def parse_moves(id_: str, cell: str) -> Moves | Failure:
"""A Moves cell: empty, or each goal the item moves, named once, and how far."""
matches = [re.fullmatch(r"([0-9]+(?:\.[0-9]+)*) by ([0-9]+)", move) for move in cell.split(", ")] if cell else []
moves = tuple((match.group(1), int(match.group(2))) for match in matches if match)
if len(moves) < len(matches) or any(not 1 <= by <= TOP_SCORE for _, by in moves):
return Failure(f"item {id_}'s {MOVES} {cell!r} is not empty or goals such as `1.1 by 8, 1.2 by 5`, each moved by a whole number from 1 to {TOP_SCORE}")
goals = [goal for goal, _ in moves]
if repeated := [goal for goal in goals if goals.count(goal) > 1]:
return Failure(f"item {id_} cites goal {repeated[0]} twice; name each goal once")
if nested := [(parent, goal) for parent in goals for goal in goals if goal.startswith(parent + ".")]:
return Failure(f"item {id_} names goal {nested[0][0]} and its sub-goal {nested[0][1]}; name one, never both: the sub-goal where the move serves it, else the parent")
return moves
def write_moves(moves: Moves) -> str:
return ", ".join(f"{goal} by {by}" for goal, by in moves)
def parse_cited(id_: str, cell: str) -> Moves:
"""An old-shape Goals cell, such as `2.1, 1`: each goal it cites, with no move."""
return tuple((goal.strip(), None) for goal in cell.split(","))
def write_cited(moves: Moves) -> str:
return ", ".join(goal for goal, _ in moves)
SHAPE = Shape(("R", "S", "C"), MOVES, parse_moves, write_moves)
# The shape from before MOVES replaced A, G and Goals, which older todo.md files hold.
OLD_SHAPE = Shape(("R", "S", "C", "A", "G"), "Goals", parse_cited, write_cited)
@dataclasses.dataclass(frozen=True)
@@ -25,7 +77,7 @@ class Item:
exempt: str
tagline: str
scores: dict[str, int]
goals: tuple[str, ...]
moves: Moves
blocked_by: tuple[int, ...]
@property
@@ -47,6 +99,12 @@ class Table:
return self.header + 2
def shape_of(columns: tuple[str, ...]) -> Shape:
"""OLD_SHAPE where the columns include A, G or Goals and not MOVES; else SHAPE, so a misspelt MOVES is reported missing."""
old_only = set(OLD_SHAPE.columns) - set(SHAPE.columns)
return OLD_SHAPE if MOVES not in columns and old_only.intersection(columns) else SHAPE
def items(todo: str) -> list[Item] | None | Failure:
"""Each row of a todo.md's items table; None where todo.md holds no items table."""
table = items_table(todo.splitlines())
@@ -54,7 +112,7 @@ def items(todo: str) -> list[Item] | None | Failure:
return table
found = []
for row in table.rows:
item = parse_row(row, table.columns)
item = parse_row(row, table)
if isinstance(item, Failure):
return item
found.append(item)
@@ -73,7 +131,7 @@ def items_table(lines: list[str]) -> Table | None | 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]:
if missing := [column for column in shape_of(table.columns).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
@@ -104,12 +162,30 @@ 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, columns: tuple[str, ...]) -> Item | Failure:
"""An item row under columns, every cell checked but the goals it cites."""
found = cells(row, len(columns))
def parse_row(row: str, table: Table) -> Item | Failure:
"""An item row of table, every cell checked but whether README.md numbers and weighs the goals it names."""
found = cells(row, len(table.columns))
if isinstance(found, Failure):
return found
named = dict(zip(columns, found))
named = dict(zip(table.columns, found))
if misformed := check_cells(row, named):
return misformed
shape = shape_of(table.columns)
scores = parse_scores(named["ID"], named, shape.score_columns)
if isinstance(scores, Failure):
return scores
blocked_by = parse_blockers(named["ID"], named.get(BLOCKED_BY, ""))
if isinstance(blocked_by, Failure):
return blocked_by
moves = shape.read_goals(named["ID"], named[shape.goals_column])
if isinstance(moves, Failure):
return moves
major, minor, patch = (int(part) for part in named["Release"].split("."))
return Item(int(named["ID"]), (major, minor, patch), named["Exempt"], named["Item"], scores, moves, blocked_by)
def check_cells(row: str, named: dict[str, str]) -> Failure | None:
"""Holds the row's ID, Release, Exempt and Item cells to the format: why one breaks it, None when none does."""
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}")
@@ -119,19 +195,25 @@ def parse_row(row: str, columns: tuple[str, ...]) -> Item | Failure:
return Failure(f"item {id_}'s Exempt {exempt!r} is not empty or one of {', '.join(EXEMPTIONS[1:])}")
if not re.fullmatch(r"\*\*[^*].*[^*]\*\*", tagline):
return Failure(f"item {id_}'s Item cell is not one bold tagline: {tagline}")
return None
def parse_scores(id_: str, named: dict[str, str], names: tuple[str, ...]) -> dict[str, int] | Failure:
"""Each score in names that the row holds; only C may be missing, since the table holds every needed column."""
scores: dict[str, int] = {}
for name in ("R", "S", "C", "A", "G"):
for name in names:
if name not in named:
continue
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)
return scores
def parse_blockers(id_: str, cell: str) -> tuple[int, ...] | Failure:
if not re.fullmatch(r"([0-9]+(, [0-9]+)*)?", cell):
return Failure(f"item {id_}'s {BLOCKED_BY} {cell!r} is not empty or IDs separated by \", \"")
blocked_by = tuple(int(blocker) for blocker in cell.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, blocked_by)
return blocked_by
+22
View File
@@ -1939,3 +1939,25 @@ Inherited architect, would restructure first:
- `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
## 2026-10-16T02:11:33Z, PR #283 at 7570af6, against 9aa0d4b
Ruling: worse
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Mid A | same | worse | same | same | worse |
| Inherited architect | same | worse | worse | same | worse |
Mid A, decided by:
- Locality, Overall: `bin/rank_todo.py:502` `score`: the score depends on the table's shape, branched on a string through `goal_term`, with the same old-versus-new check in `notes`, `read_scoring` and `parse_item`
- Locality: `bin/rank_todo.py:94` `Scoring`: `weights` means different things by shape, so a reader of `scoring.weights` must check `scoring.shape` first
- Locality: `bin/todo_table.py:17` `Moves`: an old-shape Goals cell is stored as moves with distance None, so `score` falls back with `(by or 0)`, and `parse_cited` takes an unused `id_`
Inherited architect, decided by:
- Locality: `bin/rank_todo.py:502` `score`: reading one score needs the shape, decided elsewhere; `weights` holds two things by shape and `(by or 0)` holds only because `parse_cited` returns None moves
- Locality, Shape: `bin/rank_todo.py:301` `unknown_columns`: the old-shape path is checked at six sites across `rank_todo.py` with its own reader and writer in `todo_table.py`, and nothing ties them together for whoever retires it
- Shape: `bin/todo_table.py:16` `Moves`: the name lies for old-shape rows, and the goals cell is parsed by a callable stored on a dataclass
- Locality: `bin/todo_table.py:41` `parse_moves`: the rules for a Moves cell are split between `parse_moves` and `rank_todo.py`'s `parse_item`
+12 -4
View File
@@ -4,7 +4,9 @@
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-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.
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. PR #257's scoring run found Shape lowest, at 6.25. The Shape items are `todo.md` items 114, 124 and 125. When PR #283 replaces G, the chunk that ships it carries this rule into the new score.
2026-10-16, PR #283: such an item moves each goal it cites by 9, in place of G 9. lilleman, answering that PR's review: such items compete with the others like any item, so they no longer rank first.
## 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
@@ -120,11 +122,17 @@ 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`, which ranks each blocker above the items it blocks; the table's order is the plan's only order
## todo.md: one table of items scored by the formula it states, each README achieve goal weighed by its position, the first heaviest, 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-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 and bar 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, 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, as this README's Goals now mark them; each project keeps settled decisions to test its goals against. Until these items ship, the formula and bar above hold.
2026-10-15, lilleman: the scores get a researched method, which `todo.md` items 146, 149, 151 and 152 build, after PR #283 shipped the ranking; 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, the cost being 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, as this README's Goals now mark them; each project keeps settled decisions to test its goals against. Each part of this method holds once the item that builds it ships.
2026-10-16, PR #283: items rank by `Score = 100 * V / 2**S`. 2**S is the cost; the 100 lets a score read to one decimal. V sums, over the achieve goals an item's Moves cell names, each goal's weight times how far the item moves it, 1 to 10. The goal ranked k of n achieve goals in reading order weighs (1/k) / (1 + 1/2 + … + 1/n), the sum-reciprocal weight. A Moves column replaces A, G and Goals, and `rank_todo.py` derives the weights from README.md, so the goal weights table and the 2026-10-08 weights are gone. An item that cited only maintain goals now names the achieve goal it moves, or, as a defect restoring one, that maintain goal, as the entry below says. A panel of three readers seated as lilleman picked the spelling: two put a Moves column holding `1.1 by 8, 1.2 by 5` first, and one put `1.1: 8` first; two chose `2**S`, since a Python reader takes `^` for XOR; all three chose one decimal of `100 * V / 2**S` over three significant digits or a log. The bar moved to 0.1, lilleman's call answering the review of PR #283: on one-decimal scores it drops an item scoring under 0.05, in practice one that moves no achieve goal, and item 149 revisits it. A table in the old shape still ranks by the formula and weights it states, and ranking it says to reshape it, so no other project's commits stop; reshaping it is that project's only work until done, as `CLAUDE.md` → "Working loop" says. The C column stays until `todo.md` item 146 drops it. The old shape's ranking is valid until `todo.md` item 156.
2026-10-16, lilleman, answering the review of PR #283. An item that restores a maintain goal the project breaks today is a defect: exempt as `defect`. Its Moves name that maintain goal and how much of it is broken, and the goal weighs as the heaviest achieve goal, since a broken maintain goal outranks any achieve goal. Every defect ranks by its score, so a trivial one waits behind valuable work. Only questions and then security findings rank first in their release: a question's answer may change other items, and a question waits for the human anyway, so ranking it first delays no chunk. An item names the most specific goal it moves, and a parent only for a move none of its sub-goals covers, so a sub-goal's move does not count twice; `rank_todo.py` refuses a goal named beside its own sub-goal. Each project reshapes its own `todo.md`; `CLAUDE.md` → "Working loop" makes the reshape the only work until done, as it makes writing missing premises. An item that makes this project easier to read moves goal 1.4 as well as 1.1, since reading cost is measured in tokens per chunk; a goal of its own for readability is left for later. Cost gains a fixed part, F in `Score = 100 * V / (2**S + F)`: every chunk carries a cost its size does not shrink, the reading before its first commit, about 130k tokens, and its review passes, so `2**S` alone overrated tiny items. F is 8, about one S 3 change, until `todo.md` item 158 measures it.
2026-10-16, lilleman, ruling on the plan in PR #283: release 0.2.0 takes plan items 146, 152, 73, 50, 65, 84, 153, 67, 115 and 140 ahead of their scores, to put budget and efficiency in the other projects first. A standing goal cannot capture that priority for now, so it is a one-time ruling: the later releases, and every release after 0.2.0, fill from the score again.
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.
+34
View File
@@ -418,3 +418,37 @@ Read most (opens and searches):
- `bin/claude_code/entries.py` 2
- `bin/failure.py` 2
- `bin/judge_replay/test_judge_replay.py` 2
## Reading cost, chunk 224f2177e487, finished 2026-10-15T21:46:26Z
133254 new input tokens before the first commit.
Read most (opens and searches):
- `bin/loop_claude/test_loop_claude.py` 7
- `todo.md` 6
- `bin/loop_claude/cycle/judge.py` 4
- `docs/decisions.md` 4
- `bin/loop_claude/cycle/prompts.py` 3
- `bin/loop_claude/test_black_box.py` 3
- `AGENTS.md` 2
- `CHANGELOG.md` 2
- `README.md` 2
- `bin/loop_claude/loop/main.py` 2
## Reading cost, chunk 6b0c8adf366b, finished 2026-10-15T21:55:23Z
139738 new input tokens before the first commit.
Read most (opens and searches):
- `todo.md` 7
- `README.md` 5
- `docs/decisions.md` 5
- `CHANGELOG.md` 3
- `docs/scoring-and-goals-research.md` 3
- `bin/rank_todo.py` 2
- `skills/larv-review/SKILL.md` 2
- `skills/larv-review/standards/readme.md` 2
- `AGENTS.md` 1
- `CLAUDE.md` 1
+5 -6
View File
@@ -5,19 +5,18 @@ 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.
- **`todo.md` is mandatory in every project, in the shape `rank_todo.py --help` shows**, which `~/.claude/bin/rank_todo.py` checks and ranks; its `--help` shows a valid file. `## Scoring` holds the formula and the bar; `## Items` is one table of every item; `## Details` holds each item's detail under its ID. Cite an item by its ID. The formula and bar 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:
- **Score an item when it is filed or edited.** Each of R, S and C is a whole number from 1 to 10:
- **R** — the risk that the change creates serious bugs or issues.
- **S** — the size of the change.
- **C** — how hard the change is to get right: novel design, subtle invariants, many interacting parts. A huge rename is low C; a ten-line lock fix can be high. C stays out of the score.
- **A** — its value to the audience in `README.md` → `## Audience`.
- **G** — its value to the goals it cites in the Goals column; W is the weight of the heaviest of them.
- **Name in Moves each achieve goal in `README.md` → `## Goals` the item moves, and how far,** from 1 to 10, judged by its value to the audience in `## Audience`: `1.1 by 8, 1.2 by 5`. Name the most specific goal it moves, and a parent goal only for a move none of its sub-goals covers, never beside its own sub-goal. Leave out every maintain goal, which vetoes, except on an item marked `defect` that restores it: name that goal, and how much of it is broken. `rank_todo.py --help` says how it weighs each goal.
- **A table with A, G and Goals in place of Moves is in the old shape.** Reshaping it is the project's only work until done, as `CLAUDE.md` → "Working loop" says, and `rank_todo.py` says how. Until then, A is the item's value to the audience and G its value to the goals it cites.
- **Check R, S and C against finished chunks.** Guess them, then run `~/.claude/bin/score-outcomes <R> <S> <C>` in the project. It lists the finished items guessed nearest, what their chunks measured, and the median outcome at each guessed value. Set each score to the value guessed for the finished items whose outcome matches what you expect of this one. Keep your guess when no listed item resembles the one you are scoring.
- **Read the places the comprehension seats found hard before filing an item.** `~/.claude/bin/larv-review places`, run in the project, prints them. Where the item's change touches one, its detail says to make that place easier to read.
- **An item scoring under the bar is deleted, with every item that needs it, and a finding under the bar is not filed.** The chunk's summary names each, with its score.
- **The Exempt cell keeps an item whatever its score:** `security` for a security finding, `defect` for a 🔴 finding, `question` for a question only the human can answer, `decision` for an item `docs/decisions.md` cites, `owner` for an item the human told you to keep, and, where no other reason fits, `principle` for a 🟡 finding against a file under `~/.claude/principles/`, whose item's detail names that principle. Every item `docs/decisions.md` cites carries one of these reasons.
- **The Exempt cell keeps an item whatever its score:** `security` for a security finding, `defect` for a 🔴 finding or an item that restores a maintain goal the project breaks today, `question` for a question only the human can answer, which ranks first in its release, `decision` for an item `docs/decisions.md` cites, `owner` for an item the human told you to keep, and, where no other reason fits, `principle` for a 🟡 finding against a file under `~/.claude/principles/`, whose item's detail names that principle. Every item `docs/decisions.md` cites carries one of these reasons.
- **A maintain goal vetoes an item that breaks it,** whatever the item scores: redesign the item so it holds the goal, or drop it.
- **Unless the project has a reason to differ, weigh goals by position, the first heaviest.** When the weights stop listing the README's goals, `rank_todo.py` fails and prints those weights.
+243 -240
View File
@@ -2,94 +2,93 @@
## Scoring
`Score = -R - S/4 + 2*A + 2*G*W`
`Score = 100 * V / (2**S + 8)`
`Bar = 9`
`Bar = 0.1`
`Next ID = 155`
| Goal | W |
|---|---|
| 1 | 1.00 |
| 1.1 | 0.99 |
| 1.2 | 0.98 |
| 1.3 | 0.97 |
| 1.4 | 0.96 |
| 1.5 | 0.95 |
| 2 | 0.90 |
| 3 | 0.85 |
| 4 | 0.80 |
`Next ID = 159`
## Items
| ID | Release | Blocked by | Exempt | Item | R | S | C | A | G | Goals | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 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 |
| 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 | | 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 |
| ID | Release | Blocked by | Exempt | Item | R | S | C | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|
| 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 | 1.2 by 5 | 7.3 |
| 140 | 0.2.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 | 1.1 by 4, 1.4 by 4 | 10.9 |
| 67 | 0.2.0 | | principle | **Point stability-reviewer at the technical principles in place of its own restatement of them.** | 2 | 3 | 2 | 1.1 by 5 | 6.8 |
| 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 | 1.1 by 8, 1.2 by 8, 1.4 by 8 | 2.8 |
| 152 | 0.2.0 | 146 | 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 | 1.1 by 7 | 6.4 |
| 50 | 0.2.0 | | principle | **Grant the bench's runs only the tools a review needs, in place of skipping every permission.** | 2 | 2 | 3 | 1.1 by 3 | 5.5 |
| 65 | 0.2.0 | | defect | **Archive each judge reply the loop rejects.** | 3 | 4 | 3 | 3 by 3 | 5.5 |
| 84 | 0.2.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 | 1.4 by 5 | 4.6 |
| 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 | 1.2 by 5 | 4.6 |
| 73 | 0.2.0 | | | **Have each reviewer write its full report to a file and return the worker only its findings' one-line summaries.** | 3 | 4 | 4 | 1.4 by 4 | 1.8 |
| 80 | 0.3.0 | | defect | **State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.** | 1 | 1 | 1 | 2 by 4 | 17.5 |
| 21 | 0.3.0 | | defect | **Give `settings.json`'s model one writer, and sort its keys.** | 3 | 3 | 4 | 2 by 5 | 13.7 |
| 29 | 0.3.0 | | | **Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.** | 2 | 2 | 3 | 1.1 by 5, 1.4 by 5 | 13.7 |
| 119 | 0.3.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 | 1.1 by 4, 1.4 by 4 | 13.1 |
| 127 | 0.3.0 | | | **Define seat, place, paired ruling, scoring run and the judge's records in `CLAUDE.md` → "Vocabulary".** | 1 | 1 | 1 | 1.1 by 4, 1.4 by 4 | 13.1 |
| 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 | 1.1 by 4, 1.4 by 4 | 13.1 |
| 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 | 1.1 by 9, 1.4 by 9 | 12.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 | 1.1 by 6, 1.2 by 6, 1.4 by 6 | 11.9 |
| 49 | 0.3.0 | | principle | **Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.** | 1 | 2 | 2 | 1.1 by 6 | 10.9 |
| 82 | 0.3.0 | | principle | **Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.** | 1 | 2 | 2 | 1.1 by 4, 1.4 by 4 | 10.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 | 1.1 by 4, 1.4 by 4 | 10.9 |
| 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 | 1.1 by 4, 1.4 by 4 | 10.9 |
| 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 | 1.1 by 4, 1.4 by 4 | 10.9 |
| 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 | 1.1 by 4, 1.4 by 4 | 10.9 |
| 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 | 1.1 by 4, 1.4 by 4 | 10.9 |
| 154 | 0.3.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 | 1.1 by 6 | 10.9 |
| 157 | 0.3.0 | | | **Split `docs/decisions.md` → `todo.md: one table of items …`'s 2026-10-02 paragraph into one paragraph per choice.** | 1 | 2 | 1 | 1.1 by 4, 1.4 by 4 | 10.9 |
| 106 | 0.3.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 | 1.1 by 5 | 10.9 |
| 139 | 0.4.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 | 1.1 by 5, 1.4 by 5 | 10.3 |
| 158 | 0.4.0 | | decision | **Measure the fixed cost of a chunk from loop-claude's archive, in tokens and hours against its items' S, and set F in `Score = 100 * V / (2**S + F)` to it.** | 1 | 3 | 4 | 1.1 by 5, 1.4 by 5 | 10.3 |
| 149 | 0.4.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 | 1.1 by 7 | 9.6 |
| 116 | 0.4.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 | 1.1 by 5 | 9.1 |
| 110 | 0.4.0 | | | **Count, for each finished chunk, the later changes that fixed code it wrote, and show them beside its guessed E.** | 2 | 4 | 6 | 1.1 by 6, 1.4 by 6 | 8.2 |
| 112 | 0.4.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 | 1.1 by 6 | 8.2 |
| 130 | 0.4.0 | | | **Move the vote counting out of `bin/larv_review/ruling.py`'s `votes`, so reading a votes file decides nothing.** | 2 | 3 | 3 | 1.1 by 4, 1.4 by 4 | 8.2 |
| 137 | 0.4.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 | 1.1 by 4, 1.4 by 4 | 8.2 |
| 125 | 0.4.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 | 1.1 by 9, 1.4 by 9 | 7.4 |
| 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 | 1.1 by 4 | 7.3 |
| 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 | 1.1 by 4 | 7.3 |
| 66 | 0.4.0 | | principle | **Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.** | 3 | 3 | 4 | 1.1 by 5 | 6.8 |
| 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 | 1.1 by 5 | 6.8 |
| 111 | 0.4.0 | | | **Measure the chunks of a project that merges by squash or fast-forward, which `score-outcomes` skips today.** | 3 | 3 | 5 | 1.1 by 5 | 6.8 |
| 113 | 0.4.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 | 1.1 by 5, 1.4 by 5 | 6.8 |
| 121 | 0.4.0 | | | **Check that `bin/round_titles.py`'s `PASSES` lists exactly the passes of larv-review §3's table.** | 1 | 3 | 2 | 1.1 by 5 | 6.8 |
| 122 | 0.4.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 | 1.1 by 5, 1.4 by 5 | 6.8 |
| 4 | 0.5.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 | 1.1 by 3 | 5.5 |
| 12 | 0.5.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 | 1.1 by 6 | 5.5 |
| 105 | 0.5.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 | 1.4 by 6 | 5.5 |
| 135 | 0.5.0 | | | **Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop.** | 3 | 3 | 4 | 1.1 by 4 | 5.5 |
| 156 | 0.5.0 | | decision | **Drop `rank_todo.py`'s ranking of an old-shape table once no project under `~/code` holds one.** | 2 | 3 | 2 | 1.1 by 4 | 5.5 |
| 68 | 0.5.0 | | principle | **Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.** | 2 | 4 | 4 | 1.1 by 5 | 4.6 |
| 59 | 0.5.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 | 1.4 by 6 | 4.1 |
| 123 | 0.5.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 | 1.1 by 5, 1.4 by 5 | 4.1 |
| 132 | 0.5.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 | 1.1 by 5, 1.4 by 5 | 4.1 |
| 155 | 0.5.0 | | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 2 | 3 | 4 | 1.4 by 6 | 4.1 |
| 124 | 0.5.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 | 1.1 by 9, 1.4 by 9 | 4.1 |
| 1 | 0.6.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 | | 0.0 |
| 5 | 0.6.0 | | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 5 | 5 | 7 | 1.1 by 6 | 3.3 |
| 77 | 0.6.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 | 1.1 by 7, 1.4 by 7 | 3.2 |
| 6 | 0.6.0 | | decision | **Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.** | 5 | 5 | 6 | 1.1 by 5 | 2.7 |
| 51 | 0.6.0 | | principle | **Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.** | 3 | 5 | 5 | 1.1 by 5 | 2.7 |
| 151 | 0.6.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 | 1.2 by 7 | 2.6 |
| 52 | 0.6.0 | | principle | **Record why this checkout lives in Claude Code's own directory, or move it out and link it in.** | 6 | 6 | 4 | 1.1 by 4 | 1.2 |
## Details
### 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.
### 115. 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.
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.
`ENOUGH` in `bin/score_outcomes/outcomes.py` matches the 10 figures the reading-cost trend waits for. No published standard sets either, and `CLAUDE.md` → "Web research" asks the human for a threshold a consumer relies on.
### 140. 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.
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.
### 67. Point stability-reviewer at the technical principles in place of its own restatement of them.
DRY, in `principles/technical-principles.md`: `agents/stability-reviewer.md` restates principles in its own words, and the copy has drifted: it asks for "properly randomised UUIDs" where the principle requires UUID v7.
### 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.
@@ -103,7 +102,7 @@ Each level is about ×10 of a real quantity; `docs/decisions.md` → `todo.md:
| 4 | two or more of level 3's, or a rewrite of code with known defects | — | everything down, a backup restore, or a secret or PII exposed |
| 5 | — | — | irreversible: data lost for good, or a one-way door |
`rank_todo.py` accepts a table in the old shape until its project reshapes it, and says so, so no project's commits stop the day this lands. Reshaping is then that project's chunk, as `CLAUDE.md` → "Working loop" says of a `todo.md` in another shape.
`rank_todo.py` ranks a table with C and without L, E and I until its project reshapes it, and says so, as it does for the old shape since PR #283, so no project's commits stop the day this lands. Reshaping is then that project's only work until done, as `CLAUDE.md` → "Working loop" says.
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.
@@ -111,91 +110,82 @@ C goes in the same chunk, so no reshaped table meets bands built for R + C: R al
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.
### 50. Grant the bench's runs only the tools a review needs, in place of skipping every permission.
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.
"Always grant explicit access to data", in `principles/technical-principles.md`: `workflow-bench/bench.py` starts claude with `--dangerously-skip-permissions`, and no rule confines it to a sandbox, so a run on the host reaches the host's credentials and other checkouts.
### 151. Keep 10 to 20 settled decisions per project as its goals' test set, and rerun them after a goal changes.
### 65. Archive each judge reply the loop rejects.
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.
A defect: goal 3, keeping unattended runs' transcripts backed up, does not hold while a rejected judge reply reaches only stderr. Raised by the principles audit of PR #215: the judge runs with `--no-session-persistence`, so the archive cannot answer the 3am question of why the loop rejected a verdict.
### 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.
### 84. 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.
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.
### 110. Count, for each finished chunk, the later changes that fixed code it wrote, and show them beside its guessed E.
`score-outcomes` measures risk only by the 🔴 findings review caught. A serious bug review missed shows later, as a change that fixes code the chunk wrote: the defect that escaped, which E guesses (item 146).
### 115. 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.
`ENOUGH` in `bin/score_outcomes/outcomes.py` matches the 10 figures the reading-cost trend waits for. No published standard sets either, and `CLAUDE.md` → "Web research" asks the human for a threshold a consumer relies on.
### 116. Report L by the share of chunks with a 🔴, once 10 chunks that each shipped one item record finding counts and most record no 🔴.
`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.
Raised by the principles audit of PR #228: the `review: the comprehension check records …` entry in `docs/decisions.md` is valid only while that holds, and `docs/comprehension-history.md` keeps every vote, yet nothing reads the agreement rate. Scoring runs on near-identical code are rare now, so compare with those already in the history, such as PR #224's and PR #225's, or make a second run for the check.
### 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.
### 73. Have each reviewer write its full report to a file and return the worker only its findings' one-line summaries.
`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.
2026-10-08, lilleman: rescored from A10/G8 to A4/G4 on the measurement below, so other items that lower token use go first.
### 113. Compute an item's S from the code it names, where it names any, and show it beside the finished items `score-outcomes` lists.
Measured over the 68 transcripts in loop-claude's archive on 2026-10-08, matching each Agent call to its tool result and to any `<task-notification>` naming its tool-use id. No report reached the worker twice: 813 arrived once as the hand-back, and 363 once as a notification after Claude Code ran the agent in the background. Reports took a median 19k tokens per chunk, 8% of the worker's peak context (24% at most). Lines carrying a severity mark are 9–24% of a reviewer's report, and the worker would still open the file for each 🔴 or 🟡 it fixes. A third of the report volume is the comprehension seats', whose votes and places the worker copies into the history. File reads fill more of the worker's context: `sed -n` output is 30% of its Bash results and `grep` output 11%, which `reading-cost` targets.
`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.
The reports would live in the session's scratchpad, such as `<scratchpad>/larv-review/prose-round-1.md`, so no project's checkout sees them. A later round gets the path of that pass's earlier report in place of the findings pasted in. How a report reaches the file:
### 125. Give "record", "outcome" and "places" one meaning each across `bin/`, and rename `bin/larv_review/git.py` by what it holds.
- **Write access.** Grant each reviewer Write. No reviewer under `agents/` holds it today, an agent's tool list cannot confine Write to one folder, and `~/.claude/CLAUDE.md` → "Working with the codebase" denies edits to a reviewer that only reads. Check whether a PreToolUse hook can tell a subagent's call from the worker's and deny a Write outside the scratchpad.
- **A wrapper.** A general-purpose subagent launches the reviewer, saves the report and returns only the summary lines. Claude Code's documentation says a subagent cannot start another; drop this route unless a test shows one can.
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`.
This risks goal 1.1: a worker fixing from a one-line summary can miss context it needs.
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.
### 80. State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.
A defect: goal 2, keeping the setup shareable between computers, does not hold while a new machine is never told it must be a sandbox. Raised by the principles audit of PR #224. The `settings.json` decision is valid while every machine taking this checkout is a sandbox, but Install asks for a sandbox only for `loop-claude`.
### 21. Give `settings.json`'s model one writer, and sort its keys.
A defect: goal 2, keeping the setup shareable between computers, does not hold while one machine's model choice overwrites every other's. Claude Code rewrites `"model"` in this tracked file whenever a model is picked, so one `/model` dirties the checkout and overrides the synced choice.
Every write Claude Code makes to the file rewrites `"model"`, `claude plugin install` included: Claude Code 2.1.288 turned `"opus"` into `"opus[1m]"`. Each write also puts the keys back in Claude Code's own order, so a sorted file stays sorted only until the next write.
### 29. Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.
State that in `~/.claude/rules/goals-and-audience.md` → "Goals and Audience", and have larv-review's comprehension check name the contributor as the reader it serves. The check then runs in a project whose audience includes the contributor, and a project that drops them skips it.
### 119. 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.
Today's title, "a project lifting itself to the comprehension floor starts at the lowest dimension", reads as either where the project scores or where work begins. Beside the title saying the check blocks no merge, a reader cannot tell whether `Floor:` means stop; a seat named `AGENTS.md:5` among the places it found hard. "First" means within such a chunk, not across a release: since the decision's 2026-10-16 line, items that lift the lowest dimension compete with the others like any item.
### 127. Define seat, place, paired ruling, scoring run and the judge's records in `CLAUDE.md` → "Vocabulary".
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`.
### 129. Explain `bin/rule_hook/rules.py`'s `OVERRIDE` pattern beside it: why the reason is lazy, what the lookahead splits and why `-->` is stripped.
The maintainability senior of PR #257's scoring run named `bin/rule_hook/rules.py:49` `OVERRIDE`: nothing in the code explains the pattern. Make `OVERRIDE` 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`.
Shape is the lowest dimension, so this item moves goal 1.1 by 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.
### 121. Check that `bin/round_titles.py`'s `PASSES` lists exactly the passes of larv-review §3's table.
### 49. Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.
The inherited architect of PR #257's scoring run named `bin/round_titles.py:5` `PASSES`: it repeats `skills/larv-review/SKILL.md:33` with no check tying them. It leaves out the auto-reviewer, whose rounds `SKILL.md:68` counts by hand. A test under `bin/repo_checks/` can hold the two lists together. Make `PASSES` easier to read.
DRY, in `principles/technical-principles.md`: the list is copied by hand, and sessions work from the copy.
### 122. 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.
### 82. Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.
All four seats of PR #257's scoring run named `bin/loop_claude/cycle/judge.py:16` `JUDGE_RULES`. The prompt is spliced from constants in `cycle/prompts.py` (`ANSWER_DESTINATIONS`, `ANSWERS_RECORDED`, `either`) and `project/records.py` (`HUMAN_RULE_NAMES`), so a reader rebuilds it from three files. It says "the agent" where the code and `CLAUDE.md` → "Vocabulary" say "worker". Wording the worker also sees, such as `ANSWER_DESTINATIONS` in `prompts.resumed`, may stay in `cycle/prompts.py`. Make `JUDGE_RULES` easier to read.
"Deterministic order", in `principles/technical-principles.md`, raised by the principles audit of PR #224: their order carries no meaning, so two chunks adding a decision conflict at the end, and a reader cannot find a title by scanning.
### 123. 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.
### 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.
Three seats of PR #257's scoring run named `bin/comprehension_history.py:106` `latest_places`; the logic it rests on is `:114` `worse_places` and `:126` `worse_votes`. They regex the markdown the module writes. `worse_votes` keeps a seat's first row through `setdefault`, because the votes table comes first. `worse_places` recovers the seat with `label.split(",")[0]`. `Entry` still holds scoring seats' places for rulings recorded before PR #255. Make these functions easier to read.
### 139. 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.
The paired ruling on PR #265 ruled worse. Make these places easier to read: `measure.py` `measured` and `render` (token attribution, subagent rungs, round counting, calls and rendering in one module; `measured`, `Measured` and `measure_archive` side by side); `calls` with `archive.py` `raised` and `last_measured`, where a call's identity is its sentence and the measured cycle is read back from rendered markdown; and `Reports.searches`, which holds characters, not searches.
### 127. Define seat, place, paired ruling, scoring run and the judge's records in `CLAUDE.md` → "Vocabulary".
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`.
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.
### 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.
@@ -213,13 +203,41 @@ Junior A, Mid A and the maintainability senior of PR #257's scoring run named `b
Junior A and Mid A of PR #257's scoring run named `bin/shell_command.py:31` `segments`: a hand-rolled tokenizer with dense regexes and a second lexing path for unbalanced quotes, which the rule hook and `reading-cost` both depend on. Its comments state each quirk but not its limits. Make `segments` easier to read.
### 140. 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.
### 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.
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.
`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.
### 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.
### 157. Split `docs/decisions.md` → `todo.md: one table of items …`'s 2026-10-02 paragraph into one paragraph per choice.
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.
Raised by PR #283's prose pass. The paragraph runs about 330 words and holds six choices: the bar, the purge, re-raising findings, the gate check, the `principle` exemption and the 2026-10-08 weights note. A reader after one of them reads all six.
### 106. 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.
Found by the goals audit of PR #245. `skills/larv-review/SKILL.md` §3 → "Security" says Renovate or Dependabot owns dependency CVEs per `CLAUDE.md` → "Working with the codebase", which says nothing about either.
### 139. 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.
The paired ruling on PR #265 ruled worse. Make these places easier to read: `measure.py` `measured` and `render` (token attribution, subagent rungs, round counting, calls and rendering in one module; `measured`, `Measured` and `measure_archive` side by side); `calls` with `archive.py` `raised` and `last_measured`, where a call's identity is its sentence and the measured cycle is read back from rendered markdown; and `Reports.searches`, which holds characters, not searches.
### 158. Measure the fixed cost of a chunk from loop-claude's archive, in tokens and hours against its items' S, and set F in `Score = 100 * V / (2**S + F)` to it.
F is 8 until then, about one S 3 change, lilleman's call in PR #283. A chunk costs more than its size: the worker reads about 130k tokens before its first commit whatever the item, and every chunk takes its review passes. Fit cost against 2**S from the finished chunks `score-outcomes` measures, in the same units `2**S` counts, and say in `docs/decisions.md` → `todo.md: …` how far the fit holds. A chunk bundling tiny items shares F between 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.
### 116. Report L by the share of chunks with a 🔴, once 10 chunks that each shipped one item record finding counts and most record no 🔴.
`score-outcomes` reports risk as the median 🔴 count at each guessed R; after item 146, the part of R a 🔴 tests is L. 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.
### 110. Count, for each finished chunk, the later changes that fixed code it wrote, and show them beside its guessed E.
`score-outcomes` measures risk only by the 🔴 findings review caught. A serious bug review missed shows later, as a change that fixes code the chunk wrote: the defect that escaped, which E guesses (item 146).
### 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.
### 130. Move the vote counting out of `bin/larv_review/ruling.py`'s `votes`, so reading a votes file decides nothing.
@@ -229,63 +247,19 @@ Mid A of PR #257's scoring run named `bin/larv_review/ruling.py:8` `votes`. It c
PR #262's paired ruling found the project reads worse: a rerun resumes on its rung only by parsing `Rung.__str__`'s and `Route.__str__`'s wording back with `bin/loop_claude/routing.py`'s `ROUTED`, a string contract over four files, where a reword silently routes afresh. Write the route as a structured line, such as JSON after `Worker:`, that `transcript_archive` reads into fields. `stepped` both raises to a bundled item's rung and counts towards a one-rung step; `Reply.bundled` names neither R + C nor highest. Make `bin/loop_claude/loop/main.py`'s `run_loop` easier to read where it threads the route.
### 129. Explain `bin/rule_hook/rules.py`'s `OVERRIDE` pattern beside it: why the reason is lazy, what the lookahead splits and why `-->` is stripped.
### 125. Give "record", "outcome" and "places" one meaning each across `bin/`, and rename `bin/larv_review/git.py` by what it holds.
The maintainability senior of PR #257's scoring run named `bin/rule_hook/rules.py:49` `OVERRIDE`: nothing in the code explains the pattern. Make `OVERRIDE` easier to read.
Shape is the lowest dimension, so this item moves goal 1.1 by 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
### 135. Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop.
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.
The maintainability senior and the inherited architect of PR #257's scoring run named `bin/loop_claude/loop/reload.py:38` `fingerprint` and `:50` `exec_if_edited`: the fingerprint covers every `bin/**/*.py`, so editing `statusline.py` or `rank_todo.py` re-execs a running loop. Make `fingerprint` easier to read.
### 81. Have `workflow-bench/bench.py` return each run's failure as a value, so one failed clone does not hide the later runs' results.
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.
"Errors as values", in `principles/technical-principles.md`, raised by the principles audit of PR #224: `bench.py` raises `KeyError` and `CalledProcessError`, and `pool.map` re-raises the first while the other threads run on unreported.
It lives under `~/.claude`, which `.gitignore` keeps from the remote, so a lost disk loses every unattended run's record. Back it up only to a destination private to me and encrypted at rest: the worker runs with permissions bypassed, so the archived tool results can hold credentials it read.
### 102. Give loop-claude's retry delay an environment override, so the black-box test stops replacing `time.sleep` through `sitecustomize`.
2026-10-02, the human: ai-sandbox is the VM `loop-claude` will run on, hosted on the server bender. bender-infra, the infrastructure-as-code project that manages bender, will back up ai-sandbox's data volume once ai-sandbox is rebuilt. The item waits for the human to say the rebuild has landed; do not remind them. Before writing the README line, check that `~/.claude` lives on that volume and that the backup is private and encrypted at rest.
The README line covers the bench's transcripts in `workflow-bench/logs/` too (goal 3).
### 21. Give `settings.json`'s model one writer, and sort its keys.
Claude Code rewrites `"model"` in this tracked file whenever a model is picked, so one `/model` dirties the checkout and overrides the synced choice.
Every write Claude Code makes to the file rewrites `"model"`, `claude plugin install` included: Claude Code 2.1.288 turned `"opus"` into `"opus[1m]"`. Each write also puts the keys back in Claude Code's own order, so a sorted file stays sorted only until the next write.
### 49. Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.
DRY, in `principles/technical-principles.md`: the list is copied by hand, and sessions work from the copy.
### 59. Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.
Raised by the product-owner review of PR #211. The resumed worker gets the judge's quote of the work remaining, but a worker that still thinks the chunk done can answer each cycle the same way, and each cycle costs a worker and a judge run (goal 1.4).
### 12. Run the test suite in CI on every PR, or record in `docs/decisions.md` why the local run is enough.
The repo has no CI, so larv-review's gate is the local run, and larv-review's Gate skips even that when the last stability round left the suite green: an unattended chunk can merge on the worker's own word.
When CI runs a rule check, such as one of `bin/rule-hook`'s, let `<!-- rule-override <rule>: <reason> -->` in the PR body override it.
### 80. State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.
Raised by the principles audit of PR #224. The `settings.json` decision is valid while every machine taking this checkout is a sandbox, but Install asks for a sandbox only for `loop-claude`, so a new machine is never told.
### 5. Key a project on its checkout's full path, and refuse to start while another session uses that key.
The key names the project's session, archive folder and models entry. `project_key` drops the leading `/`, so `~/code/a` and `/a` share all three, and one loop can resume or delete the other's session.
`bin/reading-cost` keys the archive by the main checkout, the parent of git's common dir, since it runs in a chunk's worktree; `loop-claude` keys it by `--show-toplevel`, so a loop started inside a worktree archives where `reading-cost` never looks. Derive both keys one way.
### 84. 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.
Raised by the principles audit of PR #228: the `review: the comprehension check records …` entry in `docs/decisions.md` is valid only while that holds, and `docs/comprehension-history.md` keeps every vote, yet nothing reads the agreement rate. Scoring runs on near-identical code are rare now, so compare with those already in the history, such as PR #224's and PR #225's, or make a second run for the check.
### 67. Point stability-reviewer at the technical principles in place of its own restatement of them.
DRY, in `principles/technical-principles.md`: `agents/stability-reviewer.md` restates principles in its own words, and the copy has drifted: it asks for "properly randomised UUIDs" where the principle requires UUID v7.
### 106. 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.
Found by the goals audit of PR #245. `skills/larv-review/SKILL.md` §3 → "Security" says Renovate or Dependabot owns dependency CVEs per `CLAUDE.md` → "Working with the codebase", which says nothing about either.
Found by the principles audit of PR #242. `bin/loop_claude/test_black_box.py:113-114` swaps the global `time.sleep`, the shape "Functional core, imperative shell" bans. An override of the delay lets the test run the code as production runs it.
### 66. Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.
@@ -295,70 +269,83 @@ KISS, in `principles/technical-principles.md`, which keeps a limit only while re
Found by the principles audit of PR #242, against "Functional core, imperative shell" (`principles/technical-principles.md`). `bin/larv_review/record.py:67` reads `time.time()`, then checks git (`:70`, `commit_exists`) and the history file (`:75`) inside the function that parses the seats file and decides. A test cannot fix the heading's time, and every test of `read_seats` touches the real checkout.
### 132. Lift each dimension still under the comprehension floor after release 0.2.0's scoring run, at the places that run names.
### 111. Measure the chunks of a project that merges by squash or fast-forward, which `score-outcomes` skips today.
Replaces item 62, which release 0.3.0's items split. PR #257's scoring run put Locality and Self-sufficiency at 6.63, Shape at 6.25 and the overall at 6.50, against the floor of 7.0 in `docs/decisions.md` → `comprehension floor: …`. Split this into items, one per place, once 0.3.0's scoring run has named them.
`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.
### 29. Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.
### 113. Compute an item's S from the code it names, where it names any, and show it beside the finished items `score-outcomes` lists.
State that in `~/.claude/rules/goals-and-audience.md` → "Goals and Audience", and have larv-review's comprehension check name the contributor as the reader it serves. The check then runs in a project whose audience includes the contributor, and a project that drops them skips it.
`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.
### 68. Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.
### 121. Check that `bin/round_titles.py`'s `PASSES` lists exactly the passes of larv-review §3's table.
"Most, if not all, code should have automated tests", in `principles/technical-principles.md`: `compare.blind()` keeps the comparison blind, and a version name it misses invalidates the bench silently.
The inherited architect of PR #257's scoring run named `bin/round_titles.py:5` `PASSES`: it repeats `skills/larv-review/SKILL.md:33` with no check tying them. It leaves out the auto-reviewer, whose rounds `SKILL.md:68` counts by hand. A test under `bin/repo_checks/` can hold the two lists together. Make `PASSES` easier to read.
### 119. 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.
### 122. 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.
Today's title, "a project lifting itself to the comprehension floor starts at the lowest dimension", reads as either where the project scores or where work begins. Beside the title saying the check blocks no merge, a reader cannot tell whether `Floor:` means stop; a seat named `AGENTS.md:5` among the places it found hard.
### 65. Archive each judge reply the loop rejects.
Goal 3, raised by the principles audit of PR #215: the judge runs with `--no-session-persistence`, and the first two rejected replies reach only stderr, so the archive cannot answer the 3am question of why the loop rejected a verdict.
### 82. Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.
"Deterministic order", in `principles/technical-principles.md`, raised by the principles audit of PR #224: their order carries no meaning, so two chunks adding a decision conflict at the end, and a reader cannot find a title by scanning.
### 73. Have each reviewer write its full report to a file and return the worker only its findings' one-line summaries.
2026-10-08, lilleman: rescored from A10/G8 to A4/G4 on the measurement below, so other items that lower token use go first.
Measured over the 68 transcripts in loop-claude's archive on 2026-10-08, matching each Agent call to its tool result and to any `<task-notification>` naming its tool-use id. No report reached the worker twice: 813 arrived once as the hand-back, and 363 once as a notification after Claude Code ran the agent in the background. Reports took a median 19k tokens per chunk, 8% of the worker's peak context (24% at most). Lines carrying a severity mark are 9–24% of a reviewer's report, and the worker would still open the file for each 🔴 or 🟡 it fixes. A third of the report volume is the comprehension seats', whose votes and places the worker copies into the history. File reads fill more of the worker's context: `sed -n` output is 30% of its Bash results and `grep` output 11%, which `reading-cost` targets.
The reports would live in the session's scratchpad, such as `<scratchpad>/larv-review/prose-round-1.md`, so no project's checkout sees them. A later round gets the path of that pass's earlier report in place of the findings pasted in. How a report reaches the file:
- **Write access.** Grant each reviewer Write. No reviewer under `agents/` holds it today, an agent's tool list cannot confine Write to one folder, and `~/.claude/CLAUDE.md` → "Working with the codebase" denies edits to a reviewer that only reads. Check whether a PreToolUse hook can tell a subagent's call from the worker's and deny a Write outside the scratchpad.
- **A wrapper.** A general-purpose subagent launches the reviewer, saves the report and returns only the summary lines. Claude Code's documentation says a subagent cannot start another; drop this route unless a test shows one can.
This risks goal 1.1: a worker fixing from a one-line summary can miss context it needs.
### 6. Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.
Claude Code owns that file and writes it. `trust` reads it, changes it and writes it back, so a write that lands in between is lost.
### 51. Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.
"Functional core, imperative shell", in `principles/technical-principles.md`: `archive`, `trust`, `retried`, the worker, `interrupt` and `model_choice` print to stderr themselves, and the tests swap the global stream.
### 102. Give loop-claude's retry delay an environment override, so the black-box test stops replacing `time.sleep` through `sitecustomize`.
Found by the principles audit of PR #242. `bin/loop_claude/test_black_box.py:113-114` swaps the global `time.sleep`, the shape "Functional core, imperative shell" bans. An override of the delay lets the test run the code as production runs it.
### 50. Grant the bench's runs only the tools a review needs, in place of skipping every permission.
"Always grant explicit access to data", in `principles/technical-principles.md`: `workflow-bench/bench.py` starts claude with `--dangerously-skip-permissions`, and no rule confines it to a sandbox, so a run on the host reaches the host's credentials and other checkouts.
### 81. Have `workflow-bench/bench.py` return each run's failure as a value, so one failed clone does not hide the later runs' results.
"Errors as values", in `principles/technical-principles.md`, raised by the principles audit of PR #224: `bench.py` raises `KeyError` and `CalledProcessError`, and `pool.map` re-raises the first while the other threads run on unreported.
All four seats of PR #257's scoring run named `bin/loop_claude/cycle/judge.py:16` `JUDGE_RULES`. The prompt is spliced from constants in `cycle/prompts.py` (`ANSWER_DESTINATIONS`, `ANSWERS_RECORDED`, `either`) and `project/records.py` (`HUMAN_RULE_NAMES`), so a reader rebuilds it from three files. It says "the agent" where the code and `CLAUDE.md` → "Vocabulary" say "worker". Wording the worker also sees, such as `ANSWER_DESTINATIONS` in `prompts.resumed`, may stay in `cycle/prompts.py`. Make `JUDGE_RULES` easier to read.
### 4. Name each chunk's archive folder by the chunk's start time, so `<key>/` lists chunks in the order they ran.
Today the folder is the SHA-256 of the transcript's first timestamped line, which tells the human nothing; that line carries the start time. Drop the fallback to the first line, which every chunk of a project shares, and give the tests' fake transcripts ISO timestamps. `bin/reading-cost` takes a chunk's id from the folder's first 12 characters and skips a chunk whose id `docs/reading-cost.md` holds, so give it a way to match a figure written under the old name.
### 52. Record why this checkout lives in Claude Code's own directory, or move it out and link it in.
### 12. Run the test suite in CI on every PR, or record in `docs/decisions.md` why the local run is enough.
"One owner per value" and "Prefer the vendor-neutral option", in `principles/technical-principles.md`: git, Claude Code and loop-claude all write `~/.claude`, kept apart only by the `.gitignore` allowlist, and the repo's records live in a vendor directory.
The repo has no CI, so larv-review's gate is the local run, and larv-review's Gate skips even that when the last stability round left the suite green: an unattended chunk can merge on the worker's own word.
When CI runs a rule check, such as one of `bin/rule-hook`'s, let `<!-- rule-override <rule>: <reason> -->` in the PR body override it.
### 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.
### 135. Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop.
The maintainability senior and the inherited architect of PR #257's scoring run named `bin/loop_claude/loop/reload.py:38` `fingerprint` and `:50` `exec_if_edited`: the fingerprint covers every `bin/**/*.py`, so editing `statusline.py` or `rank_todo.py` re-execs a running loop. Make `fingerprint` easier to read.
### 156. Drop `rank_todo.py`'s ranking of an old-shape table once no project under `~/code` holds one.
While `rank_todo.py` ranks two shapes, projects follow two sets of scoring rules, against goal 1.3. Once every project has reshaped, drop `OLD_SHAPE`'s weighing from `rank_todo.py`, `RESHAPE`, and the old shape's lines in `rank_todo.py --help` and `rules/todo-items.md`. Keep `todo_table` reading old tables: `score_outcomes` reads every past merge's `todo.md`. PR #283's paired ruling found the old-shape path made `rank_todo.py`'s `score`, `Scoring.weights`, `unknown_columns` and `todo_table.py`'s `Moves` harder to read; leave each easier, with one shape and moves that are always moves, and the Moves cell's rules in one place.
### 68. Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.
"Most, if not all, code should have automated tests", in `principles/technical-principles.md`: `compare.blind()` keeps the comparison blind, and a version name it misses invalidates the bench silently.
### 59. Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.
Raised by the product-owner review of PR #211. The resumed worker gets the judge's quote of the work remaining, but a worker that still thinks the chunk done can answer each cycle the same way, and each cycle costs a worker and a judge run (goal 1.4).
### 123. 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.
Three seats of PR #257's scoring run named `bin/comprehension_history.py:106` `latest_places`; the logic it rests on is `:114` `worse_places` and `:126` `worse_votes`. They regex the markdown the module writes. `worse_votes` keeps a seat's first row through `setdefault`, because the votes table comes first. `worse_places` recovers the seat with `label.split(",")[0]`. `Entry` still holds scoring seats' places for rulings recorded before PR #255. Make these functions easier to read.
### 132. Lift each dimension still under the comprehension floor after release 0.2.0's scoring run, at the places that run names.
Replaces item 62, which release 0.3.0's items split. PR #257's scoring run put Locality and Self-sufficiency at 6.63, Shape at 6.25 and the overall at 6.50, against the floor of 7.0 in `docs/decisions.md` → `comprehension floor: …`. Split this into items, one per place, once 0.3.0's scoring run has named them.
### 155. Lower the reading cost of the files a chunk reads most before its first commit.
`bin/reading-cost` on 2026-10-16: the last 5 chunks' median is 133254 new input tokens before their first commit, the 5 before them 120770. Read most over the last 5, by opens and searches: `todo.md` 30, `README.md` 18, `docs/decisions.md` 17, `bin/loop_claude/test_loop_claude.py` 11, `CHANGELOG.md` 9, `skills/larv-review/SKILL.md` 9, `bin/loop_claude/cycle/prompts.py` 8, `CLAUDE.md` 6, `AGENTS.md` 4, `bin/loop_claude/cycle/judge.py` 4. The chunk that ships this item runs `bin/reading-cost --reset`.
### 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 moves goal 1.1 by 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 with `rank_todo.py`'s formula language and goal weighing, and the comprehension history with round titles. `rank_todo.py` keeps its path, which every project's rules name. The `.gitignore` allowlist and README follow the move.
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.
It lives under `~/.claude`, which `.gitignore` keeps from the remote, so a lost disk loses every unattended run's record. Back it up only to a destination private to me and encrypted at rest: the worker runs with permissions bypassed, so the archived tool results can hold credentials it read.
2026-10-02, the human: ai-sandbox is the VM `loop-claude` will run on, hosted on the server bender. bender-infra, the infrastructure-as-code project that manages bender, will back up ai-sandbox's data volume once ai-sandbox is rebuilt. The item waits for the human to say the rebuild has landed; do not remind them. Before writing the README line, check that `~/.claude` lives on that volume and that the backup is private and encrypted at rest.
The README line covers the bench's transcripts in `workflow-bench/logs/` too (goal 3).
### 5. Key a project on its checkout's full path, and refuse to start while another session uses that key.
The key names the project's session, archive folder and models entry. `project_key` drops the leading `/`, so `~/code/a` and `/a` share all three, and one loop can resume or delete the other's session.
`bin/reading-cost` keys the archive by the main checkout, the parent of git's common dir, since it runs in a chunk's worktree; `loop-claude` keys it by `--show-toplevel`, so a loop started inside a worktree archives where `reading-cost` never looks. Derive both keys one way.
### 77. 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.
@@ -389,3 +376,19 @@ Claude's misses ranked the named units at a coin toss. Top k scores 0.50 by chan
| Change spread | 0.57 | 0.54 |
Claude's answers overlapped the truth by a median Jaccard index of 0.76. A run took in 62,643 new input tokens and cost $0.70; it did not record which model answered. Grep answers these questions whatever the code's shape, so no question enters review; a new question bench would need questions that take understanding the code, not finding it.
### 6. Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.
Claude Code owns that file and writes it. `trust` reads it, changes it and writes it back, so a write that lands in between is lost.
### 51. Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.
"Functional core, imperative shell", in `principles/technical-principles.md`: `archive`, `trust`, `retried`, the worker, `interrupt` and `model_choice` print to stderr themselves, and the tests swap the global stream.
### 151. Keep 10 to 20 settled decisions per project as its goals' test set, and rerun them after a goal changes.
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.
### 52. Record why this checkout lives in Claude Code's own directory, or move it out and link it in.
"One owner per value" and "Prefer the vendor-neutral option", in `principles/technical-principles.md`: git, Claude Code and loop-claude all write `~/.claude`, kept apart only by the `.gitignore` allowlist, and the repo's records live in a vendor directory.