Files
claude-config/bin/rank_todo.py
T

124 lines
6.2 KiB
Python
Executable File

#!/usr/bin/env python3
"""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]
Reads todo.md (default: ./todo.md), the README.md beside it, and docs/decisions.md and
docs/comprehension-history.md where they exist. Rewrites each item's Score from the formula and
sorts the items by release; within a release, 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. Writes each item's R, and adds the Blocked by and R columns to a
table without them. --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:
# todo
## Scoring
`Score = 100 * V / (2**S + 8)`
`Bar = 1`
`Next ID = 2`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | 0.1.0 | | | **Make the first thing work.** | 2 | 2 | 1 | 3 | 3 | 1 by 9 | 0 |
## Details
### 1. Make the first thing work.
What the tagline cannot say.
- 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:**. 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. 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
to 3 and I from 1 to 5.
rank_todo.py writes its R, L + E + I - 2, at least 7 when I is 5 and at least 5 when I is 4. Its S
is a whole number from 1 to 10.
- 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.
- An item's Item cell is one bold tagline; its detail, if any, sits under its ID in ## Details.
- An item's Blocked by cell is empty, or lists IDs such as `12, 14`: each must be done before the
item starts, so no blocker may sit in a later release, and no item may block itself or form a
loop. An ID at or above Next ID fails; one below it that the table no longer holds was finished
or deleted, and is dropped.
- ## Items holds the table and nothing else: an order goes in the scores or the Blocked by column.
- The table holds the columns above. One missing L, E or I 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 C, A, G and Goals columns in place of L, E, I and 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.
- ## Renamed is optional: one line `- 0.2.1 renamed to 0.3.0` per renamed release. chunk-preflight,
loop-claude and larv-review skip the line's first release, and ignore the second, which is for the
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 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 pathlib
import sys
from failure import Failure
from release_plan import ranking
def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
args = parse_args(argv)
if isinstance(args, Failure):
return fail(args)
check, todo = args
if check:
failures = ranking.check_failures(todo)
for line in failures:
print(line, file=sys.stderr)
return 1 if failures else 0
ranked = ranking.rank_file(todo)
if isinstance(ranked, Failure):
return fail(ranked)
return 1 if ranked.under_bar else 0
def fail(failure: Failure) -> int:
print(failure.reason, file=sys.stderr)
return 1
def parse_args(argv: list[str]) -> tuple[bool, pathlib.Path] | Failure:
paths = [arg for arg in argv if arg != "--check"]
if len(paths) > 1 or any(path.startswith("-") for path in paths):
return Failure(f"rank_todo.py: cannot read the arguments {' '.join(argv)}; usage: rank_todo.py [--check] [todo.md]")
return "--check" in argv, pathlib.Path(paths[0] if paths else "todo.md")
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))