Answer stability round 1: 0 🔴, 2 🟡 (0 misread); give a maintain goal's weight one owner, weight_of, and fix the stale note on a README with no achieve goal

This commit is contained in:
2026-11-09 12:04:30 +01:00
parent 47f53cd0f7
commit aebe45ef5e
7 changed files with 32 additions and 24 deletions
+1 -1
View File
@@ -59,7 +59,7 @@ Decisions live in `docs/decisions.md`:
- tests: CI runs the suite through `ci.sh` on every pull request, in a pinned Python container, and `main`'s branch protection holds a merge until it passes
- tests: each test earns its keep as the technical principles' test bullet says, and the worker takes a test's expected values from its item, never from the code
- the repo may name bender, bender-infra and ai-sandbox
- todo.md: one table of items, scored by the formula it states, held to its bar and ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; each achieve goal weighs by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0 or unmeasured, then README.md's goals; 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, and a maintain goal weighs 0.5 per point of the confidence an item's test, gate leg or probe adds to it; the table's order is the plan's only order
- todo.md: 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
- worker: a chunk's worker writes the simplest change that solves its item, test first wherever a test can check the change, and reads a technical principle only where the item, a finding or its own record names it; larv-review's reviewers hold the change to the principles and to the standards in `skills/larv-review/standards/`
- workflow-bench/: the remote may show the bench cases' names and commit SHAs
+1 -1
View File
@@ -2,7 +2,7 @@
## Unreleased
- `rank_todo.py` now lets an item name a maintain goal by how much more confident a test, a gate leg or a probe makes the project that the goal holds, weighing it 0.5 per point, 1 to 10, judged against the confidence the project already has.
- `rank_todo.py` now lets an item that adds a test, a gate leg or a probe name the maintain goal it guards, by how much more confident the project becomes that the goal holds, 1 to 10. Each point is worth 0.5.
- `chunk-preflight` now quotes the detail of each item that may join the chunk, so a worker no longer opens `todo.md` to read it.
- `command-patterns [<version>]` prints a table of the shell command patterns a release's chunks ran.
- `deploy-release --cut` reports each step as it finishes, waits for the checks `main`'s protection requires and names them, deletes the merged release branch, and ends on one line saying the release is cut.
+6 -4
View File
@@ -46,10 +46,12 @@ A valid todo.md; ## Details and each item's detail are optional:
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. A maintain goal weighs
0.5 per point of a move that raises confidence in it, 1 to 10, for an item that adds a test, a
gate leg or a probe that fails where the goal breaks. An item marked defect that restores a
maintain goal weighs it as the heaviest achieve goal instead.
`## review opt-out:` title naming the comprehension check. An item that adds a test,
a gate leg or a probe that fails where a maintain goal breaks may name that goal, by how much
more confident the project becomes that the goal holds, 1 to 10. Each point is worth 0.5. An
item marked defect names a maintain goal for how much of it is broken, and each point is worth
the heaviest achieve goal's weight, or 0.5 where that is lighter. The tool does not check that
an item adds a test, a gate leg or a probe; reviewers do.
- 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
+9 -8
View File
@@ -20,7 +20,7 @@ from release_plan.release import version
GOAL_STEP = 0.97
# 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
# A maintain goal weighs this much per point an item raises confidence in it, other than a defect that restores it; docs/decisions.md records the choice and its data.
# What a point of an item's move on a maintain goal is worth. A defect that restores the goal weighs it at least this much per point. docs/decisions.md records the choice and its data.
MAINTAIN_WEIGHT = 0.5
# 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)
@@ -45,7 +45,7 @@ class Scoring:
next_id: int
# 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. In OLD_SHAPE an item may name only the goals weights holds.
goals: dict[str, Mark]
# The weight of each goal an item may name: in OLD_SHAPE each of README.md's goals, at the weight todo.md states; else each goal goal_weights weighs.
# The weight of each goal an item may name: in OLD_SHAPE each of README.md's goals, at the weight todo.md states; else each achieve goal, as goal_weights weighs it. A maintain goal is weighed per item, by weight_of.
weights: dict[str, float]
@@ -152,7 +152,7 @@ def notes(items: list[Item], scoring: Scoring) -> list[str]:
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 voids code health and marks no goal **Achieve:**, so every item scores V 0"]
unweighed = [] if any(scoring.weights.values()) else ["README.md voids code health and marks no goal **Achieve:**, so an item scores V 0 unless it names a maintain goal"]
return unweighed + dropped
@@ -368,7 +368,7 @@ def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
def goal_weights(goals: list[tuple[str, Mark]], overall: decimal.Decimal | None) -> dict[str, float] | Failure:
"""Each achieve goal's weight: the one ranked k of n weighs GOAL_STEP ** (k - 1) / (1 + GOAL_STEP + ... + GOAL_STEP ** (n - 1)), so the weights sum to 1. Code health, where goals holds it, then weighs UNDER_FLOOR times that while the overall is under FLOOR or None, and the other goals keep their weights. Each maintain goal weighs as the heaviest achieve goal, since a broken one outranks any achieve goal, which is the weight of a defect that restores it; any other item weighs it at MAINTAIN_WEIGHT instead, in weight_of. Every weight is 0 where goals holds no achieve goal, as where README.md voids code health and marks no goal **Achieve:**, so every item scores V 0 and only an exempt one passes the bar."""
"""Each achieve goal's weight: the one ranked k of n weighs GOAL_STEP ** (k - 1) / (1 + GOAL_STEP + ... + GOAL_STEP ** (n - 1)), so the weights sum to 1. Code health, where goals holds it, then weighs UNDER_FLOOR times that while the overall is under FLOOR or None, and the other goals keep their weights. Every weight is 0 where goals holds no achieve goal, as where README.md voids code health and marks no goal **Achieve:**; an item then scores V 0 unless it names a maintain goal, and only an exempt one passes the bar. A maintain goal has no weight here: weight_of weighs it per item."""
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"]
@@ -376,8 +376,7 @@ def goal_weights(goals: list[tuple[str, Mark]], overall: decimal.Decimal | None)
weights = {number: GOAL_STEP**rank / total for rank, number in enumerate(achieve)}
if CODE_HEALTH in weights and (overall is None or overall < FLOOR):
weights[CODE_HEALTH] *= UNDER_FLOOR
heaviest = max(weights.values(), default=0.0)
return weights | {number: heaviest for number, mark in goals if mark == "Maintain"}
return weights
def cited_items(decisions: str) -> list[int]:
@@ -468,8 +467,10 @@ def score(formula: ast.Expression, item: Item, scoring: Scoring) -> float | Fail
def weight_of(goal: str, item: Item, scoring: Scoring) -> float:
"""A maintain goal weighs MAINTAIN_WEIGHT for an item that raises confidence in it, and as the heaviest achieve goal only for a defect that restores it."""
return MAINTAIN_WEIGHT if scoring.goals[goal] == "Maintain" and item.exempt != "defect" else scoring.weights[goal]
"""What a point of the item's move on the goal is worth. An achieve goal weighs what goal_weights says. A maintain goal weighs MAINTAIN_WEIGHT, except under an item marked defect, which names it for how much of it is broken: that weighs as the heaviest achieve goal, or MAINTAIN_WEIGHT where that is lighter, since a broken goal outranks every achieve goal and every confidence gain. The code checks only the mark; reviewers check that a non-defect item adds a test, gate leg or probe."""
if scoring.goals[goal] != "Maintain":
return scoring.weights[goal]
return max([MAINTAIN_WEIGHT, *scoring.weights.values()]) if item.exempt == "defect" else MAINTAIN_WEIGHT
def number(text: str | Failure, what: str) -> float | Failure:
+8 -3
View File
@@ -118,9 +118,9 @@ class Rank(unittest.TestCase):
quoting = TODO.replace("Fast detail.", " ## Goals\n\nFast detail.")
self.assertIn("### 3. Make it fast, `a | b`.\n\n ## Goals\n\nFast detail.\n", self.ranked(quoting).text)
def test_weighs_each_achieve_goal_97_percent_of_the_one_above_and_a_defects_maintain_goal_as_the_first(self):
def test_weighs_each_achieve_goal_97_percent_of_the_one_above_and_no_maintain_goal(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 ranking.goal_weights(ranking.readme_goals(readme), None).items()}, {"1": 0.3435, "1.1": 0.3435, "1.2": 0.3332, "2": 0.3232})
self.assertEqual({goal: round(weight, 4) for goal, weight in ranking.goal_weights(ranking.readme_goals(readme), None).items()}, {"1": 0.3435, "1.2": 0.3332, "2": 0.3232})
def test_weighs_5_achieve_goals_from_0212_to_0188_and_15_from_0082_to_0053(self):
for count, first, last in ((5, 0.212, 0.188), (15, 0.082, 0.053)):
@@ -183,6 +183,11 @@ class Rank(unittest.TestCase):
ranked = self.ranked(TODO.replace("| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 |", "| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2 by 3 |"))
self.assertIn("| **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2 by 3 | 9.4 |", ranked.text)
def test_weighs_a_defects_maintain_goal_at_least_as_much_as_a_confidence_gain(self):
readme = README.replace("**Achieve:**", "**Maintain:**")
todo = TODO.replace("2.1 by 8, 1 by 6", "").replace("| 2.1 by 1 |", "| 2 by 3 |").replace("| 1 by 9 |", "| |").replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | defect |")
self.assertIn("| **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2 by 3 | 9.4 |", self.ranked(todo, readme).text)
def test_refuses_a_goal_named_beside_its_own_sub_goal(self):
readme = "## Goals\n\n" + VOID + "1. **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 |")
@@ -192,7 +197,7 @@ class Rank(unittest.TestCase):
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 voids code health and marks no goal **Achieve:**, so every item scores V 0"])
self.assertEqual(ranked.notes, ["README.md voids code health and marks no goal **Achieve:**, so an item scores V 0 unless it names a maintain goal"])
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"))
+6 -6
View File
@@ -452,11 +452,11 @@ Valid while the worker writes the tests that larv-review's reviewers hold to the
2026-10-04, lilleman, answering the principles audit of PR #215. Serves goal 4, which keeps credentials, transcripts and memory files off the remote; the names of the host, its infrastructure project and the sandbox VM are none of those. Valid while the repo names them without their addresses or credentials.
## 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: 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, and a maintain goal weighs 0.5 per point of the confidence an item's test, gate leg or probe adds to it; the table's order is the plan's only order
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. 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. 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, on the bar. An item under the bar is not kept, and an Exempt cell keeps a row past the bar where a rule needs it kept. Since 2026-10-16 the bar is 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.
2026-10-02, lilleman, on the bar. An item under the bar is not kept, and an Exempt cell keeps a row past the bar where a rule needs it kept. Since 2026-10-16 the bar is 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 goal, and item 149 revisits it.
2026-10-02, lilleman, on re-raising findings. 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.
@@ -466,7 +466,7 @@ Valid while the worker writes the tests that larv-review's reviewers hold to the
2026-10-15, lilleman: the scores follow a researched method, built by `todo.md` items 149 and 151 after PR #283 shipped the ranking, PR #296 the risk scores and PR #298 the anchors each project names for each level in `docs/score-anchors.md`; the evidence is in `docs/scoring-and-goals-research.md`. R is 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. R stays out of the ranking and sets how carefully an item is done; an item that lowers risk scores it as value. A task's L and E + I pick its rungs in place of R (2026-10-16, lilleman), as `routing: one ladder` records. There is no C column: what it scored beyond size, spread and novelty, which L already holds, is complexity, and that adds almost nothing once size is accounted for. There is no A column either, since the Audience says whose value the goals serve. 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 mark them. Two parts are not built yet and hold once their items ship: each release fills by priority up to a capacity it states (item 149), and each project keeps 10 to 20 settled decisions to test its goals against (item 151).
2026-10-16, PR #283: items rank by `Score = 100 * V / (2**S + F)`. The 100 lets a score read to one decimal. 2**S is the cost. 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. A Moves column holds `1.1 by 8, 1.2 by 5`. An item names a maintain goal only as a defect restoring it, or by the confidence a test, gate leg or probe adds to it, as the two paragraphs below say.
2026-10-16, PR #283: items rank by `Score = 100 * V / (2**S + F)`. The 100 lets a score read to one decimal. 2**S is the cost. V sums, over the goals an item's Moves cell names, each goal's weight times how far the item moves it, 1 to 10. A Moves column holds `1.1 by 8, 1.2 by 5`. An item names a maintain goal only as a defect restoring it, or by the confidence a test, gate leg or probe adds to it, as the defect paragraph below and the 2026-11-09 paragraph after it say.
2026-10-18, lilleman: `rank_todo.py` derives the goal weights from README.md. Each achieve goal, in reading order, weighs 0.97 times the one before it, and the weights sum to 1; `GOAL_STEP` sets the 0.97. lilleman wanted goals to weigh almost the same, since under the sum-reciprocal weight the goal ranked k of n achieve goals weighed (1/k) / (1 + 1/2 + … + 1/n), so the last of twelve goals weighed a twelfth of the first. The step departs from `docs/scoring-and-goals-research.md`, where sum-reciprocal weights came closest to the weights people gave.
@@ -476,9 +476,7 @@ Valid while the worker writes the tests that larv-review's reviewers hold to the
2026-10-16, PR #283: a table in the old shape, with C, A, G and Goals columns in place of L, E, I and Moves, 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 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 code health, as the paragraph below says, and goal 1.4, since reading cost is measured in tokens per chunk.
2026-11-09, lilleman, answering the plan's question on maintain goals; claude proposed the numbers. An item that adds a test, a gate leg or a probe that fails where a maintain goal breaks may name that goal in Moves, by how much more confident the project becomes that the goal holds, 1 to 10, judged against the confidence it already has: 9 or 10 where nothing yet shows the goal holds, about 5 where a new thing is guarded in an area mostly covered, 1 where it only adds another way to check what is already checked. Without it, work that makes a held goal safer to rely on scored V 0 and ranked last; adf-codec's item 170, which bundles the package with four bundlers to back its goal 8, scored 0.0 beside items that move an achieve goal by 2. Such a goal weighs 0.5 per point, `MAINTAIN_WEIGHT` in `bin/release_plan/ranking.py`, not the heaviest achieve goal's weight, which suits a broken goal and is too much for a confidence gain, and which swings between about 0.8 and 0.2 as the overall crosses 7.0. The 0.5 comes from 150 distinct item and Moves pairs in 40 random `todo.md` commits from 2026-09-24 to 2026-11-09: the V their scores imply has quartiles 1.4, 2.6 and 4.5 and a median of 0.49 per point of a move, so a move of 10 is worth 5.0 (about the third quartile), 5 is worth 2.5 (the median) and 1 is worth 0.5 (under the tenth percentile, so only a cheap item ships). A defect that restores a broken maintain goal keeps the heaviest achieve goal's weight, and a maintain goal still vetoes an item that breaks it.
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.
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_commit_runs` 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 head of another project 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`. `score-outcomes` counts the counter-signal's misread findings per chunk, as `review: a reviewer under …` records. Valid while the comprehension panel's overall is how a project measures how hard it is to read.
@@ -486,6 +484,8 @@ Valid while the worker writes the tests that larv-review's reviewers hold to the
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/release_plan/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.
2026-11-09, lilleman. Serves goal 1.1: a test, gate leg or probe that guards a maintain goal proves the output holds it, and an item that adds one scored V 0 and ranked last. adf-codec's item 170 bundles the package with four bundlers to back its goal 8, runs on any JavaScript engine, and scored 0.0 beside items that move an achieve goal by 2. Such an item now names the maintain goal in Moves, by how much more confident the project becomes that the goal holds, 1 to 10, judged against the confidence it already has; `rules/todo-items.md` holds the scale. The goal weighs 0.5 per point of that move, `MAINTAIN_WEIGHT` in `bin/release_plan/ranking.py`. A defect that restores a broken maintain goal weighs it as the heaviest achieve goal, or 0.5 where that is lighter, since a broken goal outranks any achieve goal and any confidence gain; a maintain goal still vetoes an item that breaks it. The 0.5 comes from 150 distinct item and Moves pairs in 40 random `todo.md` commits from 2026-09-24 to 2026-11-09. The V their scores imply has quartiles 1.4, 2.6 and 4.5, and the median item earns 0.49 per point it moves a goal. At 0.5, a move of 10 is worth 5.0, about the third quartile; a move of 5 is worth 2.5, the median; a move of 1 is worth 0.5, under the tenth percentile, so only a cheap item ships. Valid while the achieve goals' weights and the formula's F keep the typical item's V near that distribution; a change to either revisits the 0.5.
## todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan; one below it drafts new items and changes to filed ones for a subagent at or above that rung to apply and score, and removes finished ones
2026-10-15, lilleman. Serves goal 1.1: a cheaper rung writes worse scores, and a wrong score routes a chunk onto the wrong rung, ranks the plan wrong and drops an item under the bar that should stay. Below the project's rung, a session or subagent may not score an item, move it between releases, split a milestone, delete an item under the bar, or rewrite a filed item. It drafts each new item, and each change to a filed item, such as a refresh a rule asks for. Before the next commit, one subagent on the project's rung or above applies and scores the drafts. One launch covers all of a chunk's drafts (goal 1.4). A security finding gets that subagent at once, since it is filed the moment it is found. Removing a finished item closes work and plans none, so any rung does it. Scoring a delegated task's L runs on any rung too: a launch on the project's rung to score each delegation would cost more than the cheaper task saves (goal 1.4).
+1 -1
View File
@@ -21,7 +21,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`. 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. Name a maintain goal only where the item adds a test, a gate leg or a probe that fails where the goal breaks, or is a `defect` that restores it. For the test, gate leg or probe, the move is how much more confident the project becomes that the goal holds, judged against the confidence it has: 9 or 10 where nothing yet shows the goal holds, about 5 where a new thing is guarded in an area mostly covered, 1 where it only adds another way to check what is already checked. For the defect, it is how much of the goal is broken. A change that only claims the goal moves nothing. `rank_todo.py --help` says how it weighs each goal.
- **Name in Moves each 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. Name a maintain goal only where the item adds a test, a gate leg or a probe that fails where the goal breaks, or is a `defect` that restores it. For the test, gate leg or probe, the move is how much more confident the project becomes that the goal holds, judged against the confidence it already has: 9 or 10 where nothing yet shows the goal holds, about 5 where the item guards something new in an area mostly covered, 1 where it adds another way to check what is already checked. After one such item lands, judge the next against the new confidence. For a defect, the move is how much of the goal is broken. A change that only claims the goal doesn't move it. `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, L by the share of chunks with a 🔴 instead where most hold none. 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 anchor by the level's words and the later fixes `score-outcomes` counts for its chunk, the defects that escaped it. Choose an I anchor by the level's words and what followed its release, since no tool measures I 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.