Answer prose round 1: 0 🔴, 11 🟡; make rank_todo.py's help and docstrings true for code health, define the overall before its use, split the changelog's upgrade steps into a list, retitle the todo.md decision so its bar attaches to the table, and fix the nits

This commit is contained in:
2026-10-18 21:49:01 +02:00
parent 2ea929a8be
commit fcf119ffec
14 changed files with 54 additions and 48 deletions
+1 -1
View File
@@ -27,7 +27,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 it states, each achieve goal weighed by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0, then README.md's goals, 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, held to its bar and ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; each achieve goal weighs by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0 or unmeasured, then README.md's goals; 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
+5 -1
View File
@@ -2,7 +2,11 @@
## Unreleased
- Every project now shares one achieve goal, code health: the code is easy to understand and change safely. `CLAUDE.md` → "Shared goal" states it, with its signal and counter-signal. `rank_todo.py` ranks it first among a project's achieve goals. It weighs four times as much while the project's overall is under 7.0, or while no run has measured the project: the overall mean of the newest scoring run in `docs/comprehension-history.md`, averaged with every other run on its commit. An item's Moves cell names it as in `code health by 6`. A README voids it with `**Void:** code health, since <reason>.` under `## Goals`, and `rank_todo.py` then refuses an item that names it. `larv-review record-scoring` re-ranks `todo.md` after it appends a run, and exits 1 where `rank_todo.py` would, keeping the run. Expect items that make code easier to read to rank higher in every project. This re-scores every item in a project that keeps code health, so each project's `todo.md` fails `rank_todo.py --check` until `rank_todo.py` ranks it again, and rule-hook holds its next `todo.md` commit until then. Move every machine to this release before ranking a plan another machine shares, since an older `rank_todo.py` scores it without code health and rejects a `code health` cell. A project that opts out of the comprehension check must void code health, or `rank_todo.py` refuses its plan. Then, in each project whose README restates code health as a goal of its own, file an item to drop that goal and point the Moves cells citing it at `code health`. Dropping it renumbers the goals after it, so that item also repoints every Moves cell and decision citing them; `rank_todo.py` cannot tell a cell left pointing at the wrong goal.
- Every project now shares one achieve goal, code health: the code is easy to understand and change safely. `CLAUDE.md` → "Shared goal" states it, with its signal and counter-signal. `rank_todo.py` ranks it first among a project's achieve goals. A project's overall is the overall mean of the newest scoring run in `docs/comprehension-history.md`, averaged with every other run on its commit. While that overall is under 7.0, or no run has measured the project, code health weighs four times as much as it does at 7.0 or above. An item's Moves cell names it as in `code health by 6`. A README voids it with `**Void:** code health, since <reason>.` under `## Goals`, and `rank_todo.py` then refuses an item that names it. `larv-review record-scoring` re-ranks `todo.md` after it appends a run, and exits 1 where `rank_todo.py` would, keeping the run. Expect items that make code easier to read to rank higher in every project. On upgrade:
1. Move every machine to this release before any of them ranks a plan another machine shares: an older `rank_todo.py` scores it without code health and rejects a `code health` cell.
2. Void code health in each project that opts out of the comprehension check, or `rank_todo.py` refuses its plan.
3. Run `rank_todo.py` in each project that keeps code health. It re-scores every item, so until then `rank_todo.py --check` fails, and rule-hook holds the project's next `todo.md` commit.
4. In each project whose README restates code health as a goal of its own, file an item to drop that goal and point the Moves cells citing it at `code health`. Dropping it renumbers the goals after it, so the same item repoints every Moves cell and decision citing them; `rank_todo.py` cannot tell a cell left pointing at the wrong goal.
- `stability-replay <model>` is now `review-replay <pass> <model>`, and replays any pass an agent under `agents/` reviews, such as `review-replay prose claude-opus-5-5`. It now tries every rung below the project's, down to the ladder's lowest. Its runs on the prose and stability passes of Opus 5.5 projects found no rung below the project's that finds every 🔴 and 🟡 the project's rung finds: Sonnet 5.5 at high missed 12 of 27 prose findings and 11 of 20 stability findings. So every pass stays where it runs. A rung a future run finds lowers only its pass, once `REPLAYED` in `bin/model_routing/ladder.py` names it, and only where the chunk's E + I steps no review up and the worker runs no higher than the project's rung; there it may run below the worker's rung.
- `chunk-preflight` names the release it finds finished and ready to cut, or to be planned first, wherever todo.md has named that release since the last cut.
- Each reviewer under `agents/` now writes its full report to a file that larv-review names in the reviewer's prompt, in a folder per chunk under `~/.local/state/larv-review/`. It returns only its verdict and one line per finding, so a review takes less of the worker's context. The worker reads a finding's full entry before it fixes or answers a 🔴 or 🟡. Each reviewer now holds Write. `rule-hook` refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`; no override waives this rule. Each chunk's folder stays after the merge, so `review-replay` can replay a round that reads an earlier round's report. It replays on a copy of the folder.
+4 -2
View File
@@ -22,12 +22,14 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
## Shared goal
Every project pursues this achieve goal, ranked first among its README's achieve goals. A project whose code nobody will maintain voids it with one line under `## Goals`, before the numbered goals: `**Void:** code health, since <reason>.` So does a project that opts out of the comprehension check, since the goal then has no signal. An item's Moves cell names it as `code health by 6`, and `rank_todo.py --help` says how much it weighs.
Every project pursues the achieve goal below, ranked above every achieve goal its README states. A project whose code nobody will maintain voids it with one line under `## Goals`, before the numbered goals: `**Void:** code health, since <reason>.` So does a project that opts out of the comprehension check, since the goal then has no signal. An item's Moves cell names it as in `code health by 6`, and `rank_todo.py --help` says how much it weighs.
**Achieve:** Code health: the code is easy to understand and change safely.
- Signal: the comprehension panel's overall score rises, always. Under 7.0 it is very important.
- Counter-signal: defects keep reappearing in functionality that already shipped, or reviewers raise blockers because the implementer misunderstood the current system.
- Why: a score that rises while changes still misread the code measures the wrong thing. Fewer items shipped per release is a price this goal accepts.
- Why: a score that rises while changes still misread the code measures the wrong thing.
Fewer items shipped per release is a price this goal accepts, not a counter-signal.
## Prose
+1 -1
View File
@@ -110,7 +110,7 @@ pytest_add_cli_args=-k
Then, in the copy: `uvx --with pytest 'mutmut>=3,<4' run && uvx --with pytest 'mutmut>=3,<4' results`, and `uvx --with pytest 'mutmut>=3,<4' show <mutant>` to see a mutant's change. The config keys are mutmut 3's.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests; `rank_todo.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `larv_review` ranks `todo.md` through `rank_todo.py` after a scoring run, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge, and `loop_claude` runs `chunk-preflight` as a process of its own. `judge_replay` and `review_replay` share `rung_replay/`: the rung search, the argument reader, the candidate rungs and the exits. `rung_replay/` reads `loop_claude`'s retry count and models file. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests; `rank_todo.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `larv_review` imports `rank_todo.py`'s ranking, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge, and `loop_claude` runs `chunk-preflight` as a process of its own. `judge_replay` and `review_replay` share `rung_replay/`: the rung search, the argument reader, the candidate rungs and the exits. `rung_replay/` reads `loop_claude`'s retry count and models file. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
## Tracking a new file
+2 -2
View File
@@ -108,7 +108,7 @@ def entries(history: str) -> list[Entry]:
def latest_places(history: str) -> str | None:
"""The places seats found hard since the newest scored commit, under each entry's heading, oldest first; None when no place counts.
They start at the first of newest_scored's entries, so a rerun of one head adds to the run before it, or at the oldest entry where no entry counts as scoring the project. From there, each entry gives every scoring seat's place, and each ruled place opening with a dimension its seat voted worse."""
They start at the first of newest_scored's entries, so a rerun of one head adds to the run before it. Where no entry counts as scoring the project, they start at the oldest entry. From there, each entry gives every scoring seat's place, and each ruled place opening with a dimension its seat voted worse."""
found = by_time(entries(history))
newest = newest_scored(found)
start = found.index(newest[0]) if newest else 0
@@ -139,7 +139,7 @@ def run_overall(run: Entry) -> decimal.Decimal | Failure:
overall = decimal.Decimal(overall_cells(run).get(MEAN, ""))
except decimal.InvalidOperation:
overall = None
return overall if overall is not None and overall.is_finite() else Failure(f"{HISTORY}'s scoring run {run.heading} has no Mean row ending in its overall")
return overall if overall is not None and overall.is_finite() else Failure(f"{HISTORY}'s scoring run {run.heading} has no Mean row ending in its overall, which sets code health's weight")
def overall_cells(entry: Entry) -> dict[str, str]:
+2 -2
View File
@@ -61,9 +61,9 @@ def rerank() -> Failure | None:
todo = pathlib.Path(checkout, "todo.md")
ranked = rank_todo.rank_file(todo)
if isinstance(ranked, Failure):
return Failure(f"recorded the run, but rank_todo.py cannot rank {todo}: {ranked.reason}. Repair it and run rank_todo.py on it, not record-scoring again")
return Failure(f"recorded the run, but rank_todo.py cannot rank {todo}: {ranked.reason}. Fix what that names, then run rank_todo.py on {todo}, not record-scoring again")
if ranked.under_bar:
return Failure(f"recorded the run and ranked {todo}, but the lines above name items now under the bar. Settle each as its line says, then run rank_todo.py on it, not record-scoring again")
return Failure(f"recorded the run and ranked {todo}, but the lines above name items now under the bar. Settle each as its line says, then run rank_todo.py on {todo}, not record-scoring again")
return None
+1 -2
View File
@@ -14,8 +14,7 @@ ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could
REVIEWS: tuple[tuple[str, ReviewKind], ...] = (*((f"each {agent}", kind) for kind, agent in REVIEWERS.items()), ("each comprehension seat", "seat"), ("the security pass's subagent", "security"))
# The premises rank code health, the goal every project shares, first among the goals the first prompt quotes.
AFTER_CODE_HEALTH = 'after code health (~/.claude/CLAUDE.md → "Shared goal") unless README.md voids it'
AFTER_CODE_HEALTH = 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless README.md voids it'
def fresh(task: str, premises: str, route: Route, anchor: Rung | None, facts: str) -> str:
+6 -6
View File
@@ -3,12 +3,12 @@
usage: loop-claude <task>
Run it anywhere inside a project checkout whose README.md has ## Goals and ## Audience, the
premises, which rank code health (~/.claude/CLAUDE.md → "Shared goal") first among the goals unless
README.md voids it; the task runs at the checkout root. Each cycle a worker runs the task. A chunk's
first worker prompt also quotes the premises, which choose between ways to deliver the chunk's
todo.md items, or else the task, and never widen them. A judge then reads the transcript's end, the
premises, and the records: the project's AGENTS.md and docs/decisions.md, and the human's
~/.claude/CLAUDE.md, ~/.claude/rules/*.md and
premises; the task runs at the checkout root. Each cycle a worker runs the task. A chunk's first
worker prompt also quotes the premises. They, with code health
(~/.claude/CLAUDE.md → "Shared goal") ranked first unless README.md voids it, choose between ways
to deliver the chunk's todo.md items, or else the task, and never widen them. A judge then reads
the transcript's end, the premises, and the records: the project's AGENTS.md and docs/decisions.md,
and the human's ~/.claude/CLAUDE.md, ~/.claude/rules/*.md and
~/.claude/skills/larv-review/standards/*.md, where they exist. It rules whether the chunk, the work
of one PR, is finished. A chunk stays unfinished until each answer the human typed in it that a
later chunk could need is recorded: the premises or the records hold it, or the transcript shows the worker
+1 -1
View File
@@ -371,7 +371,7 @@ class Cycles(unittest.TestCase):
self.assertIsNone(argument(workers[1], "--name"))
self.assertEqual(argument(workers[2], "--session-id"), session)
self.assertTrue(argument(workers[0], "-p").startswith(f"{TASK}\n\nContinue any open draft PR"))
self.assertTrue(argument(workers[0], "-p").endswith("The chunk's todo.md items, or else the task above, set its scope. The goals below, " 'after code health (~/.claude/CLAUDE.md → "Shared goal") unless README.md voids it' ", choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n## Goals\n1. Work.\n\n## Audience\nMe."))
self.assertTrue(argument(workers[0], "-p").endswith("The chunk's todo.md items, or else the task above, set its scope. The goals below, " 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless README.md voids it' ", choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n## Goals\n1. Work.\n\n## Audience\nMe."))
self.assertIn("main or master", argument(workers[0], "-p"))
self.assertNotIn(TASK, argument(workers[1], "-p"))
self.assertIn("Even then, it is finished only once every answer the human typed in it", argument(workers[1], "-p"))
+21 -20
View File
@@ -1,5 +1,5 @@
#!/usr/bin/env python3
"""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.
"""Score todo.md's items by the formula it states, weighing code health first and then README.md's achieve goals by their position, and hold them to its bar.
usage: rank_todo.py [--check] [todo.md]
@@ -37,17 +37,17 @@ A valid todo.md; ## Details and each item's detail are optional:
- The formula holds numbers, + - * / ** and parentheses over L, E, I, 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 achieve goals rank code health first,
the goal every project shares, which a Moves cell names as `code health by 6`. README.md's achieve
README.md marks each goal **Maintain:** or **Achieve:**. Code health, the achieve goal every
project shares, ranks first; a Moves cell names it as in `code health by 6`. README.md's achieve
goals follow in reading order, a sub-goal such as 1.1 included. Each weighs 0.97 times the one
before, and the weights sum to 1. With 5 achieve goals the first weighs 0.212 and the last 0.188.
With 15 they weigh 0.082 and 0.053. Code health then weighs 4 times that while the overall is
under 7.0, and while docs/comprehension-history.md holds no scoring run. The overall is the mean
of the overall means of every run on the newest run's commit. A line
`**Void:** code health, since <reason>.` in README.md's ## Goals drops code health, and an item
may not name it. A project must void it where its docs/decisions.md has a `## review opt-out:`
title naming the comprehension check. Only an item marked defect may name a maintain goal, the
one it restores, which weighs as the heaviest achieve goal.
With 15 they weigh 0.082 and 0.053. The overall is the mean of the overall means of every scoring
run on docs/comprehension-history.md's newest scored commit. While it is under 7.0, or the history
holds no scoring run, code health weighs 4 times its weight by position, and the other goals keep
theirs. A line `**Void:** code health, since <reason>.` in README.md's ## Goals drops code health,
and an item may not name it. A project must void it where its docs/decisions.md has a
`## review opt-out:` title naming the comprehension check. 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.
- An item's L, E and I are levels that ~/.claude/rules/todo-items.md defines: L from 1 to 4, E from 1
@@ -76,9 +76,10 @@ A valid todo.md; ## Details and each item's detail are optional:
reader. No item may sit under a marked release, and a line goes once a tag at or past its first
release is cut. A release whose items all moved elsewhere without a line reads as finished.
Exit 1, saying why, on bad arguments, a file that cannot be read or written, a todo.md, README.md,
docs/decisions.md or comprehension history that breaks the rules above, an item that is not exempt
scoring under the bar, or --check finding the file unranked.
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, a scoring run on docs/comprehension-history.md's
newest scored commit with no Mean row ending in its overall, an item that is not exempt scoring
under the bar, or --check finding the file unranked.
"""
import ast
import dataclasses
@@ -97,9 +98,9 @@ from file_writes import replace_file
# What each achieve goal weighs of the one above it; docs/decisions.md records the choice.
GOAL_STEP = 0.97
# How many times its weight code health weighs while the comprehension panel's overall is under FLOOR, or unmeasured; lilleman's choice, which docs/decisions.md records.
# Code health weighs this many times its weight by position while the comprehension panel's overall is under FLOOR, or unmeasured; lilleman's choice, which docs/decisions.md records.
UNDER_FLOOR = 4
# The line of README.md's ## Goals that voids code health, as ~/.claude/CLAUDE.md → "Shared goal" spells it.
# Any **Void:** line of README.md's ## Goals; ranked_goals accepts only `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → "Shared goal" spells it.
VOID = re.compile(r"^\*\*Void:\*\* (.*)$", re.M)
# A docs/decisions.md title opting the project out of the comprehension check, as larv-review's SKILL.md → "Opt-out" spells it.
OPTED_OUT = re.compile(r"^## review opt-out:.*\bcomprehension check\b", re.M)
@@ -312,7 +313,7 @@ def read_scoring(text: str, lines: list[str], readme: str, decisions: str, histo
def ranked_goals(readme: str, decisions: str) -> list[tuple[str, Mark]] | Failure:
"""Every goal in rank order, each with its mark: code health first, unless README.md voids it, then README.md's goals in reading order. A void spelled any other way fails, and so does a docs/decisions.md that opts out of the comprehension check where README.md keeps code health, since the goal then has no signal."""
"""Every goal in rank order, each with its mark: code health first, unless README.md voids it, then README.md's goals in reading order. A **Void:** line other than `**Void:** code health, since <reason>.` fails, and so does a docs/decisions.md that opts out of the comprehension check where README.md keeps code health, since the goal then has no signal."""
goals = readme_goals(readme)
if isinstance(goals, Failure):
return goals
@@ -329,11 +330,11 @@ def ranked_goals(readme: str, decisions: str) -> list[tuple[str, Mark]] | Failur
def weigh(lines: list[str], history: str, goals: list[tuple[str, Mark]], shape: Shape) -> dict[str, float] | Failure:
"""Each goal's weight. In OLD_SHAPE, README.md's goals weigh what todo.md states, and code health nothing. Otherwise goal_weights gives each its weight, at the overall latest_overall reads where the goals hold code health."""
"""Each goal's weight. In OLD_SHAPE, README.md's goals weigh what todo.md states, and code health has no weight, so no item may name it. Otherwise goal_weights gives each its weight, at the overall latest_overall reads where the goals hold code health."""
if shape is OLD_SHAPE:
return parse_weights(lines, [number for number, _ in goals if number != CODE_HEALTH])
if WEIGHTS_HEADER in lines:
return 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")
return Failure(f"todo.md holds a goal weights table beside a {MOVES} column; drop the table, since rank_todo.py weighs the goals itself, as its --help says")
overall = latest_overall(history) if CODE_HEALTH in dict(goals) else None
if isinstance(overall, Failure):
return overall
@@ -607,7 +608,7 @@ def parse_weights(lines: list[str], goals: list[str]) -> dict[str, float] | Fail
def parse_item(row: str, scoring: Scoring, table: Table) -> Item | Failure:
"""The row as an item whose goals README.md's hold; in SHAPE, with the R its L, E and I give."""
"""The row as an item, refused where it names a goal it may not; in SHAPE, with the R its L, E and I give."""
item = parse_row(row, table)
if isinstance(item, Failure):
return item
@@ -620,7 +621,7 @@ def parse_item(row: str, scoring: Scoring, table: Table) -> Item | Failure:
def cited_goals_failure(item: Item, scoring: Scoring) -> Failure | None:
"""Why the goals the item names break README.md's; None when they hold. todo_table's parse_moves holds the rules a Moves cell keeps on its own."""
"""Why the item may not name one of the goals it names, such as one README.md voids or does not number; None when it may name each. todo_table's parse_moves holds the rules a Moves cell keeps on its own."""
if scoring.shape is OLD_SHAPE:
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") if unknown else None
+3 -3
View File
@@ -130,7 +130,7 @@ class Rank(unittest.TestCase):
self.assertEqual((round(weights[0], 3), round(weights[-1], 3), round(sum(weights), 6)), (first, last, 1))
for figure in (rank_todo.GOAL_STEP, first, last):
self.assertIn(str(figure), rank_todo.__doc__)
self.assertIn(f"Code health then weighs {rank_todo.UNDER_FLOOR} times that while the overall is\n under {rank_todo.FLOOR},", rank_todo.__doc__)
self.assertIn(f"While it is under {rank_todo.FLOOR}, or the history holds no scoring run, code health weighs {rank_todo.UNDER_FLOOR} times its weight by position, and the other goals keep theirs.", " ".join(rank_todo.__doc__.split()))
def test_scores_an_item_by_the_weights_of_the_goals_it_moves(self):
readme = "## Goals\n\n" + VOID + "1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
@@ -200,7 +200,7 @@ class Rank(unittest.TestCase):
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"))
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 the goals itself, as its --help says"))
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", "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"):
@@ -299,7 +299,7 @@ class CodeHealth(unittest.TestCase):
def test_refuses_a_newest_scoring_run_with_no_overall_mean(self):
for history in (SCORED.format(overall="high"), SCORED.split("| Mean")[0]):
with self.subTest(history=history):
self.assertEqual(self.scores(history), Failure("docs/comprehension-history.md's scoring run 2026-10-08T12:00:00Z, PR #1 at aaaaaaa has no Mean row ending in its overall"))
self.assertEqual(self.scores(history), Failure("docs/comprehension-history.md's scoring run 2026-10-08T12:00:00Z, PR #1 at aaaaaaa has no Mean row ending in its overall, which sets code health's weight"))
def test_drops_code_health_where_readme_voids_it(self):
voided = "## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** A.\n"
+4 -4
View File
@@ -92,7 +92,7 @@ Valid while the ladder orders its rungs by competence.
## review: a project decision may opt every chunk out of the architect, the product-owner pass or the comprehension check, and a project opting out of the comprehension check voids code health
2026-10-11, lilleman. Serves goal 1.4. A research repo's PR, in a repo with no consumer for the product-owner pass and no product for the architect, spent rounds of both, and of the comprehension check, on a probe. The opt-out is the project's to make, and only an entry titled `review opt-out:` makes it, so a project without one is reviewed as before (goal 1.3). No opted-out reviewer works against a goal or a technical principle: the principles audit, which has no opt-out, still judges KISS and every other principle, so the entry names no plan item that ends it. 2026-10-13, lilleman: an opt-out of the comprehension check no longer ends with a chunk that ships an item naming the floor, since the floor blocks nothing. 2026-10-18, lilleman, answering the review of PR #324: a project that opts out of the comprehension check voids code health in its README too, since without the check the goal has no signal, and would weigh four times as much forever as an unmeasured project's does. `rank_todo.py` refuses the plan of such a project until its README voids it. Valid while the principles audit judges every chunk that changes code, config or tests, and while the architect's and the product-owner's findings matter only to a product with consumers.
2026-10-11, lilleman. Serves goal 1.4. A research repo's PR, in a repo with no consumer for the product-owner pass and no product for the architect, spent rounds of both, and of the comprehension check, on a probe. The opt-out is the project's to make, and only an entry titled `review opt-out:` makes it, so a project without one is reviewed as before (goal 1.3). No opted-out reviewer works against a goal or a technical principle: the principles audit, which has no opt-out, still judges KISS and every other principle, so the entry names no plan item that ends it. 2026-10-13, lilleman: an opt-out of the comprehension check no longer ends with a chunk that ships an item naming the floor, since the floor blocks nothing. 2026-10-18, lilleman, answering the review of PR #324: a project that opts out of the comprehension check voids code health in its README too: without the check the goal has no signal, and, never measured, it would weigh four times its weight forever. `rank_todo.py` refuses the plan of such a project until its README voids it. Valid while the principles audit judges every chunk that changes code, config or tests, and while the architect's and the product-owner's findings matter only to a product with consumers.
## review: the principles audit runs on every chunk that changes code, config or tests, and on no other chunk
@@ -132,7 +132,7 @@ 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 it states, each achieve goal weighed by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0, then README.md's goals, 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, held to its bar and ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; each achieve goal weighs by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0 or unmeasured, then README.md's goals; 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 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.
@@ -142,10 +142,10 @@ Valid while the ladder orders its rungs by competence.
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 code health, as the 2026-10-18 paragraph below says, and goal 1.4, since reading cost is measured in tokens per chunk. 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-18, lilleman. Serves goal 1.1: every project shares one achieve goal, code health, which `CLAUDE.md` → "Shared goal" states once and which replaces each project's own readability goal. It ranks first among a project's achieve goals, since under 7.0 it is very important. While the overall is under 7.0, and while no scoring run has measured the project, it weighs four times its weight at 7.0 or above, as `UNDER_FLOOR` sets. The overall is the mean of the overall means of every run on the commit of the newest run in `docs/comprehension-history.md`: two runs of one head measure it twice, and the newest alone would let their noise flip the weight, as 7.13 and 6.88 on one plainpages-plugin-fastjira head would have, a choice the review of PR #324 raised. The other achieve goals keep their weights. Crossing 7.0 changes the scores of the items that move code health, and of the defects, since a broken maintain goal weighs as the heaviest achieve goal; `larv-review record-scoring` re-ranks `todo.md` after it appends a run. A project that opts out of the comprehension check voids the goal, as `review: a project decision may opt every chunk out …` records. A README voids the goal with `**Void:** code health, since <reason>.` under `## Goals`, and an item's Moves cell names it as in `code health by 6`. A panel of three readers seated as lilleman picked both 3-0: `code health` over `code`, `health`, `C` and `0`, and the bold `Void:` line over a sentence under `## Goals` or a line under `## Audience`. The counter-signal is stated now and counted once `todo.md` item 198 ships, since no tool yet records why a finding arose. Valid while the comprehension panel's overall is how a project measures how hard it is to read.
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 and 67, the split of `routing: one ladder`, and the question of how many chunks `score-outcomes` and the reading-cost trend wait for, 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-18, lilleman. Serves goal 1.1: every project shares one achieve goal, code health, which `CLAUDE.md` → "Shared goal" states once and which replaces each project's own readability goal. It ranks first among a project's achieve goals, since lilleman rates it very important while the comprehension panel's overall is under 7.0. While that overall is under 7.0, or no scoring run has measured the project, it weighs four times its weight at 7.0 or above, as `UNDER_FLOOR` sets. The overall is the mean of the overall means of every scoring run on the newest scored commit in `docs/comprehension-history.md`, as `newest_scored` finds them. Two runs of one head measure it twice, and the newest alone would let their noise flip the weight: 7.13 and 6.88 on one plainpages-plugin-fastjira head would have. The review of PR #324 raised this choice. Weighing code health four times as much leaves the other achieve goals' weights as they are. So crossing 7.0 changes only the scores of the items that move code health, and of the defects, since a broken maintain goal weighs as the heaviest achieve goal. `larv-review record-scoring` re-ranks `todo.md` after it appends a run. A project that opts out of the comprehension check voids the goal, as `review: a project decision may opt every chunk out …` records. A README voids the goal with `**Void:** code health, since <reason>.` under `## Goals`, and an item's Moves cell names it as in `code health by 6`. A panel of three readers seated as lilleman picked both 3-0: `code health` over `code`, `health`, `C` and `0`, and the bold `Void:` line over a sentence under `## Goals` or a line under `## Audience`. The counter-signal is stated now and counted once `todo.md` item 198 ships, since no tool yet records why a finding arose. Valid while the comprehension panel's overall is how a project measures how hard it is to read.
2026-10-15, lilleman. Serves goal 1.4: loop-claude routes a chunk's first cycle on the item the chunk takes (`routing: a chunk's worker runs on the rung its item's L picks`). 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.
2026-10-18, PR #312. Serves goals 1.5 and 1.1: adf-codec renamed its next release, 0.2.1, to 0.3.0, and `chunk-preflight` then called 0.2.1 finished and stopped the loop on every cycle. A change that moves a release's last items elsewhere reads the same whether it renamed the release or deferred its leftovers, so the plan says which: a `## Renamed` section holds one line `- 0.2.1 renamed to 0.3.0` per rename, which `bin/todo_table.py`'s `renames` reads. `chunk-preflight`, `loop-claude` and larv-review's scoring-run trigger skip a marked release; they read only the first version. A release whose items moved unmarked reads as finished: the loop stops, says so and names the fix, and the trigger calls a scoring run once work has landed. So a forgotten mark costs one interrupt and never lets a release end unmeasured. `rank_todo.py` fails on a line of another shape and on an item filed under a marked release, and a newest plan whose marks do not parse leaves the next release unknown. A line goes once a tag at or past its release is cut. Only a rename is marked, since an unmarked move is the deferral. A panel of three readers seated as lilleman picked the spelling 3-0 over `- 0.2.1 → 0.3.0` under `## Releases` and a `Renamed 0.2.1 = 0.3.0` line under `## Scoring`: plain words need no special character to type. Valid while a rename is the only move of a release's items that the tools must tell from finishing it.
+1 -1
View File
@@ -20,7 +20,7 @@ paths:
| 5 | — | — | irreversible: data lost for good, or a one-way door |
- **I's reach counts every project and session that runs the change.** A change to a hook or a tool that every session runs is I level 3, every consumer affected, even where one person uses it.
- **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 code health, the goal in `CLAUDE.md` → "Shared goal", as `code health by 6`, unless the README voids it. 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.
- **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`. Where the item moves code health, the goal in `CLAUDE.md` → "Shared goal", name it as in `code health by 6`, unless the README voids it. 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 C, A, G and Goals in place of L, E, I and 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.
- **Score L, E and I against the project's anchors, and check every score against finished chunks.** Guess the scores, then run `~/.claude/bin/score-outcomes <L> <E> <I> <S>` in the project. It lists the finished items guessed nearest and the project's anchors, the shipped items its `docs/score-anchors.md` names for each level, each with what its chunk measured; then the median outcome at each guessed R and S, and how well L, E and I each order the chunks by review rounds and 🔴 findings. Compare the item with each anchor in turn: is it more or less likely to hold a defect, to let one escape, or to do damage? Give it the level whose anchors it matches; where a level has no anchor, judge by the level's words in the table above. Set S 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.
- **Anchor each level of L, E and I with two or three items the project shipped,** in `docs/score-anchors.md`: a table whose Level column names a level, such as `L 1`, and whose Items column lists the anchors' IDs, such as `12, 14`. Choose an L anchor whose chunk, as `score-outcomes` measured it, fits the level's words: its lines changed and the components it touched. Choose an E or I anchor by the level's words and what followed its release, since no tool measures either yet. Leave out a level no shipped item shows. Replace a level's anchors when the items scored at it turn out about ten times more likely, or ten times less likely, than its words say: to hold a defect, to let one escape, or to do damage.
+2 -2
View File
@@ -166,7 +166,7 @@ Found by the prose review of PR #312, which judged both entries to read as amend
### 29. Make the contributor a standing member of every project's audience, unless its README voids code health.
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 `**Void:** code health` line (`~/.claude/CLAUDE.md` → "Shared goal") is the one place a project says maintainability does not matter: it drops the contributor, as a project that opts out of the comprehension check already must.
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 `**Void:** code health` line (`~/.claude/CLAUDE.md` → "Shared goal") is the one place a project says maintainability does not matter: it drops the contributor. A project that opts out of the comprehension check must already write that line.
### 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.
@@ -204,7 +204,7 @@ In `bin/loop_claude/loop/main.py`'s docstring, the line holding "of one PR, is f
### 198. Count, per finished chunk, the findings that arose from misreading code that had already shipped, so code health's counter-signal shows.
Code health's counter-signal (`CLAUDE.md` → "Shared goal") is defects reappearing in functionality that already shipped, and reviewers raising blockers because the implementer misunderstood the current system. No tool records why a finding arose. Have each reviewer tag a finding that arose because the implementer misread code that had already shipped, and have `score-outcomes` count the tagged findings per finished chunk. Item 110's later fixes stand for the defects that keep reappearing.
Code health's counter-signal (`CLAUDE.md` → "Shared goal") has no count, since no tool records why a finding arose. Have each reviewer tag a finding that arose because the implementer misread code that had already shipped, and have `score-outcomes` count the tagged findings per finished chunk. Item 110's later fixes stand for the defects that keep reappearing.
### 167. Refuse a `/security-review` or `/claude-security` Skill call below the project's rung, as rule-hook refuses such an Agent call.