Files

148 lines
8.0 KiB
Python
Executable File

#!/usr/bin/env python3
"""Score todo.md's items by the formula it states, weighing code health first and then the goals file's achieve goals by their position, and hold them to its bar.
usage: rank_todo.py [--check] [todo.md]
Run inside a checkout. Reads four files at the paths the project's config names, which
`project-config` prints: todo.md, its plan; the goals file; and docs/decisions.md and
docs/comprehension-history.md where they exist. A file given must be that plan.
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 doesn't write
anything and fails when the file is not ranked as it would be, or when an item's detail holds a
`Touches:` list not spelt as `touch-predictions --help` shows.
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.
The goals file 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`. The goals
file'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 the project's
readability floor, or the history holds no scoring run, code health weighs 4 times its weight by
position, and the other goals keep theirs. The config sets the floor as `readability-floor`, 7.0
where left out. A line `**Void:** code health, since <reason>.` in the goals file'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. 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
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 only the table: 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 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 checkout no config names or a config that cannot be read, a
file given that is not the config's plan, a file that cannot be read or written, a todo.md, goals file 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, or an item's `Touches:` list unreadable.
"""
import pathlib
import sys
from failure import Failure
from plan_store.stores import file_plan
from project_config.main import located
def main(argv: list[str], home: pathlib.Path) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
args = parse_args(argv)
if isinstance(args, Failure):
return fail(args)
config = located(None, home)
if isinstance(config, Failure):
return fail(config)
if config.plan_file is None and args == (True, None):
# Jira's backlog ranks a plan kept there, so the check passes, as silently as on a ranked todo.md: chunk-preflight runs it on every project.
return 0
if config.plan_file is None:
return fail(Failure(f"rank_todo.py ranks a todo.md, and this checkout's config keeps the plan in Jira, whose backlog ranks it: {config.plan_label}"))
check, todo = args[0], args[1] or config.plan_file
# The goals, decisions and history are this checkout's project's, so another project's plan would be ranked by them.
if todo.resolve() != config.plan_file.resolve():
return fail(Failure(f"rank_todo.py: {todo} is not the plan this checkout's config names, {config.plan_file.resolve()}; run rank_todo.py in the checkout of the project whose plan it is"))
plan = file_plan(config, todo)
if check:
failures = plan.check()
for line in failures:
print(line, file=sys.stderr)
return 1 if failures else 0
ranked = plan.rank()
if isinstance(ranked, Failure):
return fail(ranked)
for line in plan.reported(ranked):
print(line, file=sys.stderr)
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 | None] | 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 None
if __name__ == "__main__":
sys.exit(main(sys.argv[1:], pathlib.Path.home()))