Group bin's root modules into packages named by purpose, and make rank_todo.py a launcher of release_plan/ranking.py

This commit is contained in:
2026-11-08 20:35:52 +01:00
parent 25997ba9ec
commit 8d9a39de1c
115 changed files with 915 additions and 927 deletions
+10 -15
View File
@@ -25,15 +25,14 @@
!bin/chunk_preflight/*.py
!bin/claude_code/
!bin/claude_code/*.py
!bin/comprehension_history.py
!bin/command_lines/
!bin/command_lines/*.py
!bin/deploy-release
!bin/deploy_release/
!bin/deploy_release/*.py
!bin/docker_command.py
!bin/failure.py
!bin/file_writes.py
!bin/git_command.py
!bin/git_repo.py
!bin/git_cli/
!bin/git_cli/*.py
!bin/judge-replay
!bin/judge_replay/
!bin/judge_replay/*.py
@@ -49,27 +48,26 @@
!bin/loop_inbox/*.py
!bin/machine_load/
!bin/machine_load/*.py
!bin/markdown_text.py
!bin/metric-bench
!bin/metric_bench/
!bin/metric_bench/*.py
!bin/model_routing/
!bin/model_routing/*.py
!bin/project_key.py
!bin/rank_todo.py
!bin/reading-cost
!bin/reading_cost/
!bin/reading_cost/*.py
!bin/release.py
!bin/release_standing.py
!bin/records/
!bin/records/*.py
!bin/release_plan/
!bin/release_plan/*.py
!bin/repo_checks/
!bin/repo_checks/*.py
!bin/review-replay
!bin/review_folder.py
!bin/review_passes.py
!bin/review_replay/
!bin/review_replay/*.py
!bin/round_titles.py
!bin/review_rules/
!bin/review_rules/*.py
!bin/routing_figures/
!bin/routing_figures/*.py
!bin/rule-hook
@@ -86,16 +84,13 @@
!bin/score_outcomes/
!bin/score_outcomes/*.py
!bin/settings_filter.py
!bin/shell_command.py
!bin/statusline.py
!bin/subagent-rung
!bin/subagent_rung/
!bin/subagent_rung/*.py
!bin/test_*.py
!bin/todo_table.py
!bin/transcript_archive/
!bin/transcript_archive/*.py
!bin/utc_stamp.py
!docs/
!docs/*.md
!principles/
+11 -5
View File
@@ -125,22 +125,28 @@ pytest_add_cli_args=-k
Then, in the copy: `uvx --with pytest==9.2.0 'mutmut>=3,<4' run && uvx --with pytest==9.2.0 'mutmut>=3,<4' results`, and `uvx --with pytest==9.2.0 '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. The non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool.
`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. `bin/`'s root holds only the launchers, the stand-alone tools with their tests, `test_env.py` and `failure.py`. `failure.py` stays there because its `Failure`, the value every module returns for a failed step, fits no one package's purpose. `claude_code/`, `command_lines/`, `git_cli/`, `records/`, `release_plan/`, `review_rules/` and `transcript_archive/` serve more than one tool.
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `deploy_release` imports `chunk_preflight`'s `forge_of`, which tells a GitHub origin from a Gitea one, and `release_standing.py`, which says whether the next release is ready to cut.
- `command_lines/` reads a shell command: its simple commands, and what a docker call in it asks, for `rule_hook`, `run_heavy`, `reading_cost` and `routing_figures`.
- `deploy_release` imports `chunk_preflight`'s `forge_of`, which tells a GitHub origin from a Gitea one, and `release_plan`'s `release_standing`, which says whether the next release is ready to cut.
- `git_cli/` runs git, through `git_repo.py`'s `git`, which every tool starts git with, and reads a git call in a shell command (`git_command.py`).
- `judge_replay` imports `loop_claude`'s judge.
- `larv_review` imports `rank_todo.py`'s ranking.
- `larv_review` imports `release_plan`'s ranking.
- `loop_claude` runs `chunk-preflight` as a process of its own.
- `loop_inbox` imports `loop_claude`'s question files (`waiting/`), the files a running loop lists itself in (`running_loops.py`, `session_lock.py`), its effects and paths, and `hand_over.py`, which opens claude for `/talk`. A change to any of them changes loop-inbox too.
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for.
- `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read.
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
- `rank_todo.py` launches `release_plan/ranking.py`; `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
- `records/` reads the sections of the Markdown records the tools keep, stamps their entries in UTC, and writes the tools' files privately and whole.
- `release_plan/` reads `todo.md`'s items table, parses releases, says how the plan stands to the last release cut, and ranks the plan (`ranking.py`).
- `repo_checks/` tests the repo itself.
- `review_rules/` holds the larv-review rules that several tools apply: its passes, its review folder, its round commit titles and the comprehension history's format.
- `routing_figures/` measures loop-claude's archive, and each of its projects' default branches, for loop-claude's routing calls.
- `rule_hook` imports `rank_todo.py`'s check.
- `rule_hook` imports `release_plan`'s ranking check.
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the rung search, the argument reader, the candidate rungs and the exits. It reads `loop_claude`'s retry count and models file.
- `test_env.py` serves the tests.
- `transcript_archive/` stores loop-claude's transcripts; its `project_key.py` names a project's archive folder, its loop-claude session and its entry in the models file.
## Tracking a new file
+3 -3
View File
@@ -3,10 +3,10 @@ import re
import typing
from failure import Failure
from comprehension_history import HISTORY
from todo_table import Item, items
from review_rules.comprehension_history import HISTORY
from release_plan.todo_table import Item, items
from reading_cost.figures import RECORD
from utc_stamp import utc
from records.utc_stamp import utc
# The plan, and the records tools append to: none of their lines are the chunk's work.
NOT_WORK = ("todo.md", HISTORY, RECORD)
+2 -2
View File
@@ -5,8 +5,8 @@ import re
import typing
from branch_chunks.cut import Branch, BranchChunk, NOT_WORK
from todo_table import Item
from round_titles import title_counts
from release_plan.todo_table import Item
from review_rules.round_titles import title_counts
# The Exempt cells, per ~/.claude/rules/todo-items.md, that mark an item fixing a defect.
FIXES = ("defect", "security")
+1 -1
View File
@@ -1,7 +1,7 @@
from branch_chunks.fixes import blamed, fixing_changes, FixingChange, removed_work, Traced, with_fixes
from branch_chunks.cut import BranchChunk, cut_branch, LOG, plan_revisions, shipped_by
from failure import Failure
from git_repo import Run, text_at
from git_cli.git_repo import Run, text_at
def branch_chunks(default: str, run: Run) -> list[BranchChunk] | Failure:
+2 -2
View File
@@ -13,9 +13,9 @@ from branch_chunks.fixes import blamed, fixing_changes, removed, removed_work, T
from branch_chunks.cut import Branch, chunk_log, Commit, cut_branch, landing, NOT_WORK, shipped, Span
from branch_chunks.read import branch_chunks, traced_to
from failure import Failure
from git_repo import git
from git_cli.git_repo import git
from test_env import isolated_env
from todo_table import Item
from release_plan.todo_table import Item
HEADER = "| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|\n"
WITHOUT_C = "| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|\n"
+3 -3
View File
@@ -2,11 +2,11 @@
import pathlib
import re
from release_standing import chunk_item, Cut, dated_cut, LastCut, ReadyToCut, ReviewDue, Unknown, Unplanned
from release_plan.release_standing import chunk_item, Cut, dated_cut, LastCut, ReadyToCut, ReviewDue, Unknown, Unplanned
from failure import Failure
from chunk_preflight.gathered import Forge, NoItem, Plan
from todo_table import item_details, items, NoItemsTable
from release import version
from release_plan.todo_table import item_details, items, NoItemsTable
from release_plan.release import version
# The command each forge's CLI lists pull requests with; pulls_command adds the flags that pick their rows and fields.
PULLS_LIST: dict[Forge, tuple[str, ...]] = {"gh": ("gh", "pr", "list"), "tea": ("tea", "pulls", "list")}
+4 -4
View File
@@ -1,11 +1,11 @@
"""The lines the preflight prints, stated from what it gathered."""
from todo_table import bundle_candidates, BUNDLE_MAX_R, Item, ships_alone
from release_plan.todo_table import bundle_candidates, BUNDLE_MAX_R, Item, ships_alone
from chunk_preflight.choices import cut_name, PULLS_LIST
from release_standing import dated_cut, LastCut, unreleased_entries
from release_plan.release_standing import dated_cut, LastCut, unreleased_entries
from failure import Failure
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran
from markdown_text import quoted
from release import version
from records.markdown_text import quoted
from release_plan.release import version
def render(found: Gathered) -> list[str]:
+2 -2
View File
@@ -4,8 +4,8 @@ import pathlib
import typing
from failure import Failure
from todo_table import Item
from release_standing import LastCut
from release_plan.todo_table import Item
from release_plan.release_standing import LastCut
# The CLI that lists a forge's pull requests: gh for a github.com origin, tea for any other.
Forge = typing.Literal["gh", "tea"]
+2 -2
View File
@@ -57,8 +57,8 @@ import subprocess
import sys
import typing
from git_repo import commit_exists, default_branch, file_at, git, top
from release_standing import default_plan
from git_cli.git_repo import commit_exists, default_branch, file_at, git, top
from release_plan.release_standing import default_plan
from failure import Failure
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran, Worktree
from chunk_preflight.choices import forge_of, named_paths, planned, pulls_command, worktree_add, worktree_on
+1 -1
View File
@@ -12,7 +12,7 @@ from failure import Failure
from chunk_preflight.choices import forge_of, named_paths, planned, worktree_add
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, NoItem, Ran, Worktree
from test_env import isolated_env
from release_standing import LastCut
from release_plan.release_standing import LastCut
from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
from chunk_preflight.facts import open_pulls, render
View File
@@ -1,6 +1,6 @@
import unittest
from docker_command import capped
from command_lines.docker_command import capped
class Capped(unittest.TestCase):
+4 -4
View File
@@ -8,14 +8,14 @@ import shutil
import sys
import tempfile
from release_standing import chunk_item, Cut, default_plan, Next, ReadyToCut, ReviewDue, Unplanned
from git_repo import default_ref, git
from release_plan.release_standing import chunk_item, Cut, default_plan, Next, ReadyToCut, ReviewDue, Unplanned
from git_cli.git_repo import default_ref, git
from deploy_release.deploy import deploy
from failure import Failure
from deploy_release import forge
from chunk_preflight.choices import forge_of
from todo_table import items
from release import newest_tag, Release, version
from release_plan.todo_table import items
from release_plan.release import newest_tag, Release, version
def cut(clone: str, checkout: str) -> str | Failure:
+3 -3
View File
@@ -1,8 +1,8 @@
"""Move a checkout to this repo's newest release, as a bare `deploy-release` does."""
from failure import Failure
from git_repo import git
from release import newest_tag, parsed, tagged
from markdown_text import sections
from git_cli.git_repo import git
from release_plan.release import newest_tag, parsed, tagged
from records.markdown_text import sections
def deploy(checkout: str) -> str | Failure:
View File
@@ -1,6 +1,6 @@
import dataclasses
from shell_command import resolved, Simple
from command_lines.shell_command import resolved, Simple
# git's global options that take a value as the next word.
GIT_VALUED = {"-C", "-c", "--exec-path", "--git-dir", "--namespace", "--work-tree"}
@@ -5,12 +5,10 @@ import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
import git_repo
from git_cli import git_repo
class Git(unittest.TestCase):
# Each command is a shell alias, so it touches no repository, whatever GIT_DIR the test runs under.
+1 -1
View File
@@ -30,7 +30,7 @@ from transcript_archive.location import archive_root, transcript_of
from transcript_archive.read import archived_outcomes
from rung_replay.command import arguments_or_exit, down_from, failed, limited_exit, projects_on
from judge_replay.replay import Case, case_from, Kind, report, reproduced, sample, verdict_kind
from project_key import checkout_of
from transcript_archive.project_key import checkout_of
from loop_claude.effects import Effects
from failure import Failure
from rung_replay.search import first_reply, replayed
+1 -1
View File
@@ -1,6 +1,6 @@
import decimal
from comprehension_history import by_time, counted_vote, entries, Entry, last_cells
from review_rules.comprehension_history import by_time, counted_vote, entries, Entry, last_cells
from larv_review.seats import FIRST_SEATS
# Matches score-outcomes, which waits for 10 finished chunks before it shows a median.
+2 -2
View File
@@ -1,6 +1,6 @@
from failure import Failure
from git_repo import file_at, full_history, git, top
from comprehension_history import HISTORY, HistoryChange
from git_cli.git_repo import file_at, full_history, git, top
from review_rules.comprehension_history import HISTORY, HistoryChange
def history_changes(default: str) -> list[HistoryChange] | Failure:
+5 -5
View File
@@ -2,15 +2,15 @@ import pathlib
import time
from larv_review.agreement import agreement_report
from comprehension_history import appended, DIMENSIONS, FLOOR, heading, Heading, HISTORY, latest_places, recorded, ruling_entry, scoring_entry, ScoringRun, vote_text
from git_repo import commit_exists, top
from review_rules.comprehension_history import appended, DIMENSIONS, FLOOR, heading, Heading, HISTORY, latest_places, recorded, ruling_entry, scoring_entry, ScoringRun, vote_text
from git_cli.git_repo import commit_exists, top
from larv_review.ruling import counted, overall, ruling, split, surplus, votes
from failure import Failure
from larv_review.seats import FIRST_SEATS, scores, seats_file, SeatsFile
from larv_review.scoring import means, under_floor
from larv_review.plan import plan_reasons
import rank_todo
from file_writes import replace_file
from release_plan import ranking
from records.file_writes import replace_file
def record_ruling(votes_file: pathlib.Path) -> Failure | None:
@@ -61,7 +61,7 @@ def rerank() -> Failure | None:
if isinstance(checkout, Failure):
return checkout
todo = pathlib.Path(checkout, "todo.md")
ranked = rank_todo.rank_file(todo)
ranked = ranking.rank_file(todo)
if isinstance(ranked, Failure):
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:
+5 -5
View File
@@ -103,17 +103,17 @@ import re
import sys
import typing
from git_repo import branch_titles, default_branch, git, top
from round_titles import cap, CAP, RELEASE_REVIEW_CAP, round_counts
from git_cli.git_repo import branch_titles, default_branch, git, top
from review_rules.round_titles import cap, CAP, RELEASE_REVIEW_CAP, round_counts
from failure import Failure
from comprehension_history import FLOOR
from review_rules.comprehension_history import FLOOR
from larv_review.history_changes import history_changes
from larv_review.ruling_base import measured_commit
from larv_review.agreement import MIN_PAIRS
from review_passes import PASSES
from review_rules.review_passes import PASSES
from larv_review.plan import plan_reasons
from larv_review.history_commands import record_ruling, record_scoring, show_agreement, show_places
from review_folder import REPORTS, review_folder
from review_rules.review_folder import REPORTS, review_folder
USAGE = "usage: larv-review review-folder | ruling-base | round-count | needs-scoring-run [<item ID>...] | record-ruling <votes file> | record-scoring <scores file> [<item ID>...] | places | agreement"
+4 -4
View File
@@ -1,10 +1,10 @@
import pathlib
from release_standing import Cut, default_plan, LastCut, next_release, Unknown
from release_plan.release_standing import Cut, default_plan, LastCut, next_release, Unknown
from failure import Failure
from todo_table import Item, items, NoItemsTable, renames
from release import Release, version
from git_repo import top
from release_plan.todo_table import Item, items, NoItemsTable, renames
from release_plan.release import Release, version
from git_cli.git_repo import top
def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], landed_release: Release | None, renamed: set[Release]) -> list[str] | Failure:
+1 -1
View File
@@ -1,4 +1,4 @@
from comprehension_history import DIMENSIONS, PLACE, place_dimensions, Seat
from review_rules.comprehension_history import DIMENSIONS, PLACE, place_dimensions, Seat
from failure import Failure
from larv_review.seats import FIRST_SEATS, SPLIT_SEATS, vote_line
+1 -1
View File
@@ -1,4 +1,4 @@
from comprehension_history import entries, HistoryChange
from review_rules.comprehension_history import entries, HistoryChange
def measured_commit(changes: list[HistoryChange]) -> str | None:
+1 -1
View File
@@ -1,6 +1,6 @@
import decimal
from comprehension_history import DIMENSIONS, FLOOR
from review_rules.comprehension_history import DIMENSIONS, FLOOR
def means(lines: list[list[str]]) -> list[decimal.Decimal]:
+1 -1
View File
@@ -2,7 +2,7 @@ import dataclasses
import decimal
import re
from comprehension_history import ARCHITECT, DIMENSIONS, JUNIOR, MID, Seat, SENIOR
from review_rules.comprehension_history import ARCHITECT, DIMENSIONS, JUNIOR, MID, Seat, SENIOR
from failure import Failure
SCORES = re.compile(", ".join(rf"{name} ([0-9]+(?:\.[0-9]+)?)" for name in DIMENSIONS))
+4 -4
View File
@@ -11,14 +11,14 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from larv_review.agreement import agreement_report, ruling_agreement, run_agreement
from comprehension_history import appended, entries, HistoryChange, latest_places, Place, recorded, ruling_entry, scoring_entry, ScoringRun, Seat
import comprehension_history
from review_rules.comprehension_history import appended, entries, HistoryChange, latest_places, Place, recorded, ruling_entry, scoring_entry, ScoringRun, Seat
from review_rules import comprehension_history
from larv_review.ruling import counted, ruling, split, surplus, votes
from failure import Failure
from test_env import isolated_env
from todo_table import Item, items, NoItemsTable
from release_plan.todo_table import Item, items, NoItemsTable
from larv_review.plan import landed_towards, plan_reasons, scoring_run_due
from release_standing import LastCut
from release_plan.release_standing import LastCut
from larv_review.scoring import means, under_floor
from larv_review.ruling_base import measured_commit
from larv_review.seats import score_line, scores, seats_file
+1 -1
View File
@@ -9,7 +9,7 @@ from loop_claude.effects import Effects
from loop_claude import escalation_mark
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, TakenIn, Unfinished, Verdict
from todo_table import LEVELS
from release_plan.todo_table import LEVELS
from model_routing.route import on_its_scale
from claude_code.transcript import plain, verbatim
from loop_claude.cycle.retry import retried
+2 -2
View File
@@ -4,8 +4,8 @@ from model_routing.ladder import climbed, LADDER, position, Rung
from model_routing.route import ESCALATION_MARKER, Route
from loop_claude.routing import escalation_rungs
from loop_claude.project.records import HUMAN_RULE_NAMES, RECORD_FILES
from review_passes import INSTRUCTION_FILES, INSTRUCTION_FOLDERS
from markdown_text import listed, quoted
from review_rules.review_passes import INSTRUCTION_FILES, INSTRUCTION_FOLDERS
from records.markdown_text import listed, quoted
from claude_code.transcript import Typed
# Where the judge may quote an answer from, named as the human and the worker see them; of README.md the judge sees only the premises.
+1 -1
View File
@@ -10,7 +10,7 @@ import time
import typing
import uuid
import git_repo
from git_cli import git_repo
from machine_load.memory import Memory, read_memory
# Seconds between a loop's looks for an answer from loop-inbox while it reads its terminal, and for the end of the claude loop-inbox opened.
+3 -3
View File
@@ -2,12 +2,12 @@
import pathlib
import typing
from release_standing import default_plan, DefaultPlan
from git_repo import default_ref, file_at
from release_plan.release_standing import default_plan, DefaultPlan
from git_cli.git_repo import default_ref, file_at
from loop_claude.effects import Effects, say
from failure import Failure
from loop_claude.routing import first_route, kept, routed_item
from todo_table import Item
from release_plan.todo_table import Item
from transcript_archive.read import latest_worker
from loop_claude.cycle import prompts
from model_routing.route import Route, route_from
+1 -1
View File
@@ -15,7 +15,7 @@ from loop_claude.project.model_choice import get_or_ask_models
from loop_claude.loop.usage import HELP
from loop_claude.running_loops import Listed, shown_running
from loop_claude.paths import Paths
from project_key import project_key
from transcript_archive.project_key import project_key
from model_routing.ladder import project_rung
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
+1 -1
View File
@@ -13,7 +13,7 @@ from routing_figures.render import render
from model_routing.ladder import Rung
from routing_figures import state
from loop_claude.stop import Stop
from utc_stamp import utc
from records.utc_stamp import utc
def check_routing(root: pathlib.Path, checkout: str, session: str, rung: Rung, paths: Paths, questions: pathlib.Path, effects: Effects) -> Stop | None:
+1 -1
View File
@@ -9,7 +9,7 @@ from loop_claude.effects import Effects, say
from failure import Failure
from loop_claude.stop import needs_human, needs_terminal, Stop
from loop_claude.paths import Paths
from file_writes import replace_json
from records.file_writes import replace_json
@dataclasses.dataclass(frozen=True)
+1 -1
View File
@@ -1,6 +1,6 @@
from failure import Failure
from loop_claude.project.text_file import read_utf8
from markdown_text import sections
from records.markdown_text import sections
def read_premises(root: str) -> str | Failure:
+2 -2
View File
@@ -9,12 +9,12 @@ The worker, and the session /talk opens, run on a Route (model_routing/route.py)
"""
import dataclasses
from release_standing import chunk_item, LastCut, Next
from release_plan.release_standing import chunk_item, LastCut, Next
from model_routing.ladder import climbed, highest, LADDER, position, project_rung, review_floor, Rung, stepped_up, worker_rung
from loop_claude import escalation_mark
from failure import Failure
from loop_claude.verdicts import Interrupt, QuotedAnswer, Unfinished
from todo_table import Item, items, NoItemsTable
from release_plan.todo_table import Item, items, NoItemsTable
from model_routing.route import Route
UNFINISHED_PER_STEP = 2
+2 -2
View File
@@ -19,8 +19,8 @@ import typing
from loop_claude.effects import Effects, say
from loop_claude.session_lock import ended, held, running
from failure import Failure
from todo_table import items
from file_writes import replace_json
from release_plan.todo_table import items
from records.file_writes import replace_json
# How many times, 0.1 s apart, a loop tries to take its lock: loop-inbox takes it for a moment each time it checks whether the loop has ended.
LOCK_TRIES = 10
+1 -1
View File
@@ -9,7 +9,7 @@ import pathlib
import typing
from failure import Failure
from file_writes import make_private
from records.file_writes import make_private
def lock_file(folder: pathlib.Path, session: str) -> pathlib.Path:
+1 -1
View File
@@ -914,7 +914,7 @@ class Reload(unittest.TestCase):
worker(append=["loop-claude", "\ndef\n"]), judge(),
worker(replace=["loop-claude", "\ndef\n", "\n# edited\n"]), judge(),
worker(append=["loop_claude/nested/edited.py", "# edited\n"]), judge(),
worker(append=["file_writes.py", "# edited\n"]), judge(),
worker(append=["records/file_writes.py", "# edited\n"]), judge(),
worker(),
])
self.assertEqual(run.code, 130)
+2 -2
View File
@@ -25,7 +25,7 @@ from routing_figures.calls import Call
from loop_claude.project import checkout, model_choice, records
from loop_claude.loop import chunk_start, close
from loop_claude.waiting.answers import ClaudeEnded, ClaudeOpening, send, Typed
from release_standing import DefaultPlan, LastCut
from release_plan.release_standing import DefaultPlan, LastCut
from loop_claude.effects import Effects, POLL_SECONDS, PYTHON_TIMEOUT, run_python, say, system_effects
from claude_code import entries, reply, session
from failure import Failure
@@ -42,7 +42,7 @@ from transcript_archive.location import project_archive
from model_routing.route import Route, route_from, WorkerLine
from loop_claude.stop import Stop
from loop_claude.running_loops import Taken
from utc_stamp import utc
from records.utc_stamp import utc
from loop_claude.cycle.judge import verdict_from
from loop_claude.waiting.listing import waiting
+1 -1
View File
@@ -7,7 +7,7 @@ import pathlib
from loop_claude.waiting.ask import Ask, tagged
from failure import Failure
from file_writes import replace_json
from records.file_writes import replace_json
@dataclasses.dataclass(frozen=True)
+1 -1
View File
@@ -7,7 +7,7 @@ import pathlib
import typing
from loop_claude.hand_over import ClaudeCommand
from utc_stamp import seconds, utc
from records.utc_stamp import seconds, utc
if typing.TYPE_CHECKING:
from _typeshed import DataclassInstance
+1 -1
View File
@@ -8,7 +8,7 @@ from loop_claude.waiting.ask import Ask, ask_fields, read_ask
from loop_claude.effects import Effects, say
from loop_claude.session_lock import ended, running
from failure import Failure
from file_writes import make_private, replace_json
from records.file_writes import make_private, replace_json
def ask_file(folder: pathlib.Path, session: str) -> pathlib.Path:
+1 -1
View File
@@ -4,7 +4,7 @@ import dataclasses
import os
import statistics
from comprehension_history import Place
from review_rules.comprehension_history import Place
from metric_bench.python_units import Unit
METRICS: dict[str, Callable[[Unit, dict[str, int]], int]] = {
+2 -2
View File
@@ -36,9 +36,9 @@ import statistics
import sys
from metric_bench.bench import bench, co_changed, medians, METRICS, RunScores, Score, tracked_places
from comprehension_history import entries, Entry
from review_rules.comprehension_history import entries, Entry
from failure import Failure
from git_repo import git
from git_cli.git_repo import git
from metric_bench.python_units import measured, python_units, Unit
+1 -1
View File
@@ -11,7 +11,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from metric_bench.bench import auc, bench, co_changed, top_k, tracked_places
from metric_bench.python_units import cognitive, measured, python_units, Unit
from comprehension_history import entries, Place
from review_rules.comprehension_history import entries, Place
from failure import Failure
from test_env import isolated_env
from metric_bench.main import scored_runs
+1 -1
View File
@@ -3,7 +3,7 @@ import dataclasses
import re
import typing
from review_passes import ReviewedPass
from review_rules.review_passes import ReviewedPass
# How Rung.__str__ spells a rung that names an effort, and Rung.parse reads it back.
WORDING = re.compile(r"(?P<model>\S+) at (?P<effort>\S+) effort")
+1 -1
View File
@@ -3,7 +3,7 @@ import dataclasses
import json
import typing
from todo_table import LEVELS
from release_plan.todo_table import LEVELS
from model_routing.ladder import REVIEW_STEPS, Rung
# How a worker opens the prompt of a subagent it escalates a task to, `Escalation trigger 2: …`: docs/decisions.md → `routing: a worker hands a task one rung up`.
+2 -2
View File
@@ -5,8 +5,8 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from model_routing.ladder import highest, LADDER, lowest_worker_rung, planning_rung, project_rung, review_floor, review_rung, Rung, stepped_up, worker_rung, WORKER_STEPS
from todo_table import LEVELS
from review_passes import REVIEWERS
from release_plan.todo_table import LEVELS
from review_rules.review_passes import REVIEWERS
OPUS = Rung("claude-opus-5-5", "medium")
+3 -654
View File
@@ -1,660 +1,9 @@
#!/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 ast
import dataclasses
import decimal
import graphlib
import math
import pathlib
import re
import sys
import typing
from todo_table import BLOCKED_BY, cells, CODE_HEALTH, DETAILS, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, Shape, SHAPE, shape_of, Table, table_rows
from failure import Failure
from comprehension_history import FLOOR, HISTORY, latest_overall
from markdown_text import listed, sections
from file_writes import replace_file
from release import version
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
# What each achieve goal weighs of the one above it; docs/decisions.md records the choice.
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
# 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)
LARGEST_FORMULA = 200
LONGEST_FORMULA = 4 * LARGEST_FORMULA
OPERATORS = (ast.Add, ast.BinOp, ast.Div, ast.Expression, ast.Load, ast.Mult, ast.Pow, ast.Sub, ast.UAdd, ast.UnaryOp, ast.USub)
WEIGHTS_HEADER = "| Goal | W |"
# The Exempt reasons that rank ahead of the rest of their release, in this order: a question first, since its answer may change other items, then a security finding.
FIRST = {"question": 0, "security": 1}
# How README.md marks a goal; None where it marks it neither way.
Mark = typing.Literal["Maintain", "Achieve"] | None
RESHAPE = f"todo.md's items table is in the old shape, scoring A and G against goal weights todo.md states. Until todo.md has the shape rank_todo.py --help shows, reshaping it is the project's only work, as ~/.claude/CLAUDE.md → 'Working loop' says: mark README.md's goals **Maintain:** or **Achieve:**, name each item's {MOVES}, score its L, E and I in place of C, and set the bar below the score of every item to keep"
from release_plan import ranking
@dataclasses.dataclass(frozen=True)
class Scoring:
shape: Shape
formula: ast.Expression
bar: float
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.
weights: dict[str, float]
@dataclasses.dataclass(frozen=True)
class Ranked:
text: str
under_bar: list[str]
# What ranking prints and --check does not: an old-shape table's call to reshape, a README that voids code health and marks no goal **Achieve:**, and each dropped blocker ID, since a mistyped ID drops the same way.
notes: list[str]
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 = check_failures(todo)
for line in failures:
print(line, file=sys.stderr)
return 1 if failures else 0
ranked = rank_file(todo)
if isinstance(ranked, Failure):
return fail(ranked)
return 1 if ranked.under_bar else 0
def rank_file(todo: pathlib.Path) -> Ranked | Failure:
"""Rank todo in place: rank what read_all reads, write todo where that changed it, and print the notes and under-bar lines on stderr."""
texts = read_all(todo)
if isinstance(texts, Failure):
return texts
ranked = rank(*texts)
if isinstance(ranked, Failure):
return ranked
if ranked.text != texts[0] and (unwritten := write(todo, ranked.text)):
return unwritten
for line in ranked.notes + ranked.under_bar:
print(f"{todo}: {line}", file=sys.stderr)
return ranked
def check_failures(todo: pathlib.Path) -> list[str]:
"""Why --check fails on todo, empty when it passes."""
texts = read_all(todo)
if isinstance(texts, Failure):
return [texts.reason]
ranked = rank(*texts)
if isinstance(ranked, Failure):
return [ranked.reason]
unranked = [] if ranked.text == texts[0] else [f"{todo}: not ranked; run rank_todo.py on it"]
return unranked + [f"{todo}: {line}" for line in ranked.under_bar]
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")
def read_all(todo: pathlib.Path) -> tuple[str, str, str, str] | Failure:
"""todo.md, the README.md beside it, and its docs/decisions.md and docs/comprehension-history.md, each empty when there is none."""
texts = []
for path, missing in ((todo, "every project keeps a todo.md beside its README.md, and rank_todo.py --help shows one"), (todo.parent / "README.md", "rank_todo.py weighs goals from the README.md beside todo.md"), (todo.parent / "docs" / "decisions.md", None), (todo.parent / HISTORY, None)):
try:
texts.append(path.read_text(encoding="utf-8"))
except FileNotFoundError:
if missing:
return Failure(f"{path}: not found; {missing}")
texts.append("")
except OSError as failure:
return Failure(f"{path}: {failure.strerror}")
except UnicodeDecodeError:
return Failure(f"{path}: not UTF-8")
return texts[0], texts[1], texts[2], texts[3]
def write(path: pathlib.Path, text: str) -> Failure | None:
unwritten = replace_file(path.resolve(), text.encode("utf-8"))
return Failure(f"{path}: {unwritten.reason}") if unwritten else None
def rank(text: str, readme: str, decisions: str, history: str) -> Ranked | Failure:
lines = text.split("\n")
table = read_table(lines)
if isinstance(table, Failure):
return table
shape = shape_of(table.columns)
scoring = read_scoring(text, lines, readme, decisions, history, shape)
if isinstance(scoring, Failure):
return scoring
items = read_items(table, scoring)
if isinstance(items, Failure):
return items
if uncited := check_citations(items, decisions):
return uncited
if isinstance(marked := renames(text), Failure):
return marked
if live := next((item for item in items if item.release in marked), None):
return Failure(f"todo.md marks release {version(live.release)} renamed but files item {live.id} under it; drop the mark or move the item")
scored = ordered(items, scoring)
if isinstance(scored, Failure):
return scored
ranked = rank_details(rewrite_table(lines, table, shape, scored), [item for item, _ in scored])
if isinstance(ranked, Failure):
return ranked
under_bar = [under_the_bar(item, value, scoring.bar, items) for item, value in scored if not item.exempt and round(value, 1) < scoring.bar]
return Ranked(ranked, under_bar, notes(items, scoring))
# The columns ranking fills itself, so a table without one gains it.
WRITTEN = (BLOCKED_BY, "R", "Score")
def rewrite_table(lines: list[str], table: Table, shape: Shape, scored: list[tuple[Item, float]]) -> str:
"""lines with the table's rows in scored's order, under a header naming, in shape's order, each column the table holds and each of WRITTEN."""
columns = tuple(column for column in shape.columns if column in table.columns or column in WRITTEN)
header = ["| " + " | ".join(columns) + " |", "|" + "---|" * len(columns)]
rows = [render_item(item, value, shape, columns) for item, value in scored]
return "\n".join(lines[:table.header] + header + rows + lines[table.start + len(table.rows):])
def notes(items: list[Item], scoring: Scoring) -> list[str]:
held = {item.id for item in items}
dropped = [f"item {item.id}: dropped {', '.join(map(str, gone))} from its {BLOCKED_BY}; the table no longer holds {'it' if len(gone) == 1 else 'them'}" for item in items if (gone := sorted(set(item.blocked_by) - held))]
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"]
return unweighed + dropped
def blocked_through(id_: int, items: list[Item]) -> set[int]:
"""The IDs of the items id_ blocks, and of those they block in turn."""
found: set[int] = set()
reached = {id_}
while reached:
reached = {other.id for other in items if reached.intersection(other.blocked_by)} - found
found |= reached
return found
def ordered(items: list[Item], scoring: Scoring) -> list[tuple[Item, float]] | Failure:
"""Each item with its score, by release, then questions and security findings first, then by score from highest, then by ID; then each blocker above every item it blocks."""
by_score = []
for item in items:
value = score(scoring.formula, item, scoring)
if isinstance(value, Failure):
return value
by_score.append((item, value))
by_score.sort(key=lambda pair: (pair[0].release, FIRST.get(pair[0].exempt, len(FIRST)), -pair[1], pair[0].id))
return blockers_first(by_score)
def under_the_bar(item: Item, value: float, bar: float, items: list[Item]) -> str:
blocks = [str(id_) for id_ in sorted(blocked_through(item.id, items))]
blocked = f" and the items it blocks, directly or through another ({', '.join(blocks)})" if blocks else ""
return f"item {item.id} scores {value:.1f}, under the bar {bar:g}; delete it{blocked}, or mark it with a reason the bar does not apply"
def read_scoring(text: str, lines: list[str], readme: str, decisions: str, history: str, shape: Shape) -> Scoring | Failure:
goals = ranked_goals(readme, decisions)
if isinstance(goals, Failure):
return goals
formula = parse_formula(stated(text, "Score"), variables(shape))
if isinstance(formula, Failure):
return formula
bar = number(stated(text, "Bar"), "the bar")
if isinstance(bar, Failure):
return bar
next_id = stated(text, "Next ID")
if isinstance(next_id, Failure) or not re.fullmatch(r"[0-9]+", next_id):
return next_id if isinstance(next_id, Failure) else Failure(f"Next ID {next_id!r} is not a whole number")
weights = weigh(lines, history, goals, shape)
if isinstance(weights, Failure):
return weights
return Scoring(shape, formula, bar, int(next_id), dict(goals), weights)
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:** 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
voids = VOID.findall("".join(sections(readme).get("Goals", [])))
if other := [void for void in voids if not void.startswith(f"{CODE_HEALTH}, since ")]:
if other[0].lower().startswith(CODE_HEALTH):
return Failure(f"README.md's ## Goals voids code health as `{other[0]}`; spell the void exactly `**Void:** {CODE_HEALTH}, since <reason>.`")
return Failure(f"README.md's ## Goals voids `{other[0]}`; only code health may be voided, as `**Void:** {CODE_HEALTH}, since <reason>.`")
if voids:
return goals
if OPTED_OUT.search(decisions):
return Failure(f"docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** {CODE_HEALTH}, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says")
return [(CODE_HEALTH, "Achieve"), *goals]
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 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 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
return goal_weights(goals, overall)
def read_table(lines: list[str]) -> Table | Failure:
"""The items table, held to its shape's columns and alone under ## Items."""
if "## Items" not in lines:
return Failure("todo.md is not in the scored-table format; rank_todo.py --help shows a valid one")
table = items_table(lines)
if table is None:
return Failure(f"## Items holds no table whose header opens {HEADER_START}; rank_todo.py --help shows a valid one")
if isinstance(table, Failure):
return table
shape = shape_of(table.columns)
if missing := [column for column in shape.risk_columns if column not in table.columns]:
old = older_columns(table, shape)
dropped = f", and drop {listed(old, 'and')}" if old else ""
columns = f"{listed(missing, 'and')} column; add it" if len(missing) == 1 else f"{listed(missing, 'and')} columns; add them"
return Failure(f"todo.md's items table has no {columns}, scoring each item's {listed(shape.risk_columns, 'and')} as rank_todo.py --help shows{dropped}")
return unknown_columns(table, shape) or outside_items(lines, table) or table
def unknown_columns(table: Table, shape: Shape) -> Failure | None:
"""Why ranking, which writes only the columns of the table's shape, would drop one of the table's columns; None when it would drop none."""
unknown = [column for column in table.columns if column not in shape.columns]
if old := older_columns(table, shape):
kind = "a column of an older shape; drop it" if len(old) == 1 else "columns of an older shape; drop them"
return Failure(f"todo.md's items table has {listed(old, 'and')}, {kind}, as rank_todo.py --help shows")
if unknown:
return Failure(f"todo.md's items table has the column {', '.join(unknown)}, which this rank_todo.py does not know; the columns it knows are {', '.join(shape.columns)}. Rename it, or move this machine to the release that added it")
return None
def older_columns(table: Table, shape: Shape) -> list[str]:
"""The table's columns that only OLD_SHAPE knows, where the table is in SHAPE."""
return [column for column in table.columns if column not in SHAPE.columns and column in OLD_SHAPE.columns] if shape is SHAPE else []
def read_items(table: Table, scoring: Scoring) -> list[Item] | Failure:
items = []
for row in table.rows:
item = parse_item(row, scoring, table)
if isinstance(item, Failure):
return item
items.append(item)
ids = {item.id for item in items}
if len(ids) < len(items):
return Failure("two items share an ID")
if ids and max(ids) >= scoring.next_id:
return Failure(f"item {max(ids)} is not under Next ID {scoring.next_id}; raise Next ID past every ID")
for item in items:
if unheld := [blocker for blocker in item.blocked_by if blocker >= scoring.next_id]:
return Failure(f"item {item.id} is blocked by item {unheld[0]}, which is not under Next ID {scoring.next_id}; name an item the table holds or held")
return items
def outside_items(lines: list[str], table: Table) -> Failure | None:
"""Why the table does not stand alone under ## Items: the table's order is todo.md's only order."""
heading = max((index for index in range(table.header) if lines[index].startswith("## ")), default=None)
if heading is None:
return Failure("the items table sits under no ## heading; move it under ## Items")
if lines[heading] != "## Items":
return Failure(f"the items table sits under {lines[heading]}, not ## Items; move it under ## Items")
after = lines[table.start + len(table.rows):]
section = after[:next((index for index, line in enumerate(after) if line.startswith("## ")), len(after))]
if any(line.strip() for line in lines[heading + 1:table.header] + section):
return Failure(f"## Items holds text beside its table; an order goes in the scores or the {BLOCKED_BY} column, and a note in the item's detail")
return None
def blockers_first(scored: list[tuple[Item, float]]) -> list[tuple[Item, float]] | Failure:
"""scored, each blocker that ranks below an item it blocks moved up to just above the first such item; a blocker the table no longer holds was finished or deleted, and is dropped."""
held = {item.id: (item, value) for item, value in scored}
position = {item.id: index for index, (item, _) in enumerate(scored)}
for item, _ in scored:
for blocker in item.blocked_by:
if blocker in held and held[blocker][0].release > item.release:
later, earlier = version(held[blocker][0].release), version(item.release)
return Failure(f"item {item.id}, in release {earlier}, is blocked by item {blocker}, in later release {later}; move item {blocker} to release {earlier} or earlier, or item {item.id} to release {later} or later")
if loop := blocking_loop(held):
return Failure(f"items {', '.join(map(str, loop[:-1]))} and {loop[-1]} block each other in a loop; drop one of the blockers")
placed: set[int] = set()
return [entry for item, _ in scored for entry in place(item.id, held, position, placed)]
def blocking_loop(held: dict[int, tuple[Item, float]]) -> list[int] | None:
"""The IDs of items that block each other in a loop, sorted; None where there is no loop."""
graph = {id_: {blocker for blocker in item.blocked_by if blocker in held} for id_, (item, _) in held.items()}
try:
graphlib.TopologicalSorter(graph).prepare()
except graphlib.CycleError as cycle:
return sorted(set(cycle.args[1]))
return None
def place(id_: int, held: dict[int, tuple[Item, float]], position: dict[int, int], placed: set[int]) -> list[tuple[Item, float]]:
"""The item id_, unless placed holds it, preceded by those of its blockers placed doesn't hold yet, each in score order, and theirs before them. Each item it returns joins placed. blocking_loop has ruled out a loop."""
if id_ in placed:
return []
placed.add(id_)
item, value = held[id_]
blockers = sorted((blocker for blocker in set(item.blocked_by) if blocker in held), key=position.__getitem__)
before = [entry for blocker in blockers for entry in place(blocker, held, position, placed)]
return [*before, (dataclasses.replace(item, blocked_by=tuple(sorted(blockers))), value)]
def check_citations(items: list[Item], decisions: str) -> Failure | None:
"""Holds todo.md and docs/decisions.md to each other: a cited item is exempt, a decision row is cited."""
cited = set(cited_items(decisions))
if gone := sorted(cited - {item.id for item in items}):
return Failure(f"docs/decisions.md cites \"`todo.md` item {gone[0]}\", which todo.md no longer holds; revise that decision to say what holds now")
for item in sorted(items, key=lambda item: item.id):
if item.id in cited and not item.exempt:
return Failure(f"docs/decisions.md cites \"`todo.md` item {item.id}\"; mark it decision, or another reason the bar does not apply")
if item.exempt == "decision" and item.id not in cited:
return Failure(f"item {item.id} is marked decision, but docs/decisions.md does not cite \"`todo.md` item {item.id}\"; cite it there, or mark it with another reason the bar does not apply")
return None
def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
"""README.md's goals in reading order: each one's number, a sub-goal as 4.1, and its mark, Maintain, Achieve or None."""
found = sections(readme).get("Goals", [])
if len(found) != 1:
return Failure(f"README.md has ## Goals {len(found)} times; it needs it once")
goals: list[tuple[str, Mark]] = []
path: list[tuple[int, str]] = []
for indent, position, mark in re.findall(r"^([ \t]*)(\d+)\. (?:\*\*(Maintain|Achieve):\*\*)?", found[0].expandtabs(4), re.M):
while path and path[-1][0] >= len(indent):
path.pop()
path.append((len(indent), position))
goals.append((".".join(part for _, part in path), typing.cast(Mark, mark or None)))
numbers = [number for number, _ in goals]
if not goals:
return Failure("README.md's ## Goals has no numbered goal")
if len(set(numbers)) < len(numbers):
return Failure(f"README.md's ## Goals numbers {', '.join(numbers)}; number each goal by its position")
return goals
def goal_weights(goals: list[tuple[str, Mark]], 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; only a defect that restores it may name it. 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."""
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"]
total = sum(GOAL_STEP**rank for rank in range(len(achieve)))
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"}
def cited_items(decisions: str) -> list[int]:
return [int(id_) for cited in re.findall(r"`todo\.md` items? (\d+(?:(?:, | and )\d+)*)", decisions) for id_ in re.findall(r"\d+", cited)]
def stated(text: str, name: str) -> str | Failure:
found = re.findall(rf"^`{name} = ([^`]+)`$", text, re.M)
if len(found) != 1:
return Failure(f"todo.md states `{name} = ...` {len(found)} times; state it once, on a line of its own under ## Scoring")
return found[0]
def parse_formula(source: str | Failure, variables: tuple[str, ...]) -> ast.Expression | Failure:
if isinstance(source, Failure):
return source
# Deep nesting makes the parser itself run out of memory before LARGEST_FORMULA can count the parts.
if len(source) > LONGEST_FORMULA:
return Failure(f"the formula {source[:40]!r}... holds more than {LONGEST_FORMULA} characters")
try:
tree = ast.parse(source, mode="eval")
except (SyntaxError, ValueError):
return Failure(f"the formula {source!r} does not parse")
nodes = list(ast.walk(tree))
if len(nodes) > LARGEST_FORMULA:
return Failure(f"the formula {source!r} holds more than {LARGEST_FORMULA} parts")
for node in nodes:
numeric = isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool) and abs(node.value) < 1e300
if not (isinstance(node, OPERATORS) or numeric or (isinstance(node, ast.Name) and node.id in variables)):
return Failure(f"the formula {source!r} may hold only numbers, {', '.join(variables)}, + - * / ** and parentheses")
return tree
def evaluate(node: ast.AST, values: dict[str, float]) -> float:
"""Evaluates a tree parse_formula accepted; a division by zero, and a power that overflows or has no real value, give nan."""
match node:
case ast.Expression(body):
return evaluate(body, values)
case ast.Constant(value) if isinstance(value, (int, float)):
return float(value)
case ast.Name(name):
return values[name]
case ast.UnaryOp(ast.USub(), operand):
return -evaluate(operand, values)
case ast.UnaryOp(ast.UAdd(), operand):
return evaluate(operand, values)
case ast.BinOp(left, ast.Add(), right):
return evaluate(left, values) + evaluate(right, values)
case ast.BinOp(left, ast.Sub(), right):
return evaluate(left, values) - evaluate(right, values)
case ast.BinOp(left, ast.Mult(), right):
return evaluate(left, values) * evaluate(right, values)
case ast.BinOp(left, ast.Div(), right):
divisor = evaluate(right, values)
return evaluate(left, values) / divisor if divisor else math.nan
case ast.BinOp(left, ast.Pow(), right):
# math.pow raises on a negative base with a fractional exponent, zero to a negative power, and overflow; one catch covers all three.
base, exponent = evaluate(left, values), evaluate(right, values)
# A nan from a zero divisor stays nan, though math.pow(1, nan) and math.pow(nan, 0) give 1.
if math.isnan(base) or math.isnan(exponent):
return math.nan
try:
return math.pow(base, exponent)
except (OverflowError, ValueError):
return math.nan
return math.nan
def goal_term(shape: Shape) -> str:
"""The name of the formula's goal term, which score builds: W in OLD_SHAPE, V in the current shape."""
return "W" if shape is OLD_SHAPE else "V"
def variables(shape: Shape) -> tuple[str, ...]:
"""The names the formula may use: the shape's scores but C, which stays out of the formula, and its goal term."""
return tuple(sorted({*shape.score_columns} - {"C"} | {goal_term(shape)}))
def score(formula: ast.Expression, item: Item, scoring: Scoring) -> float | Failure:
if goal_term(scoring.shape) == "W":
# The old shape weighs an item by its heaviest cited goal.
term = max(scoring.weights[goal] for goal, _ in item.moves)
else:
# Only an OLD_SHAPE item names a goal without a move.
term = sum(scoring.weights[goal] * (by or 0) for goal, by in item.moves)
value = evaluate(formula, {**item.scores, goal_term(scoring.shape): term})
return value if math.isfinite(value) else Failure(f"the formula gives item {item.id} no finite score")
def number(text: str | Failure, what: str) -> float | Failure:
if isinstance(text, Failure):
return text
try:
value = float(text)
except ValueError:
value = math.nan
return value if math.isfinite(value) else Failure(f"{what} {text!r} is not a finite number")
def parse_weights(lines: list[str], goals: list[str]) -> dict[str, float] | Failure:
table = table_rows(lines, WEIGHTS_HEADER)
if isinstance(table, Failure):
return table
weights: dict[str, float] = {}
for row in table.rows:
found = cells(row, 2)
if isinstance(found, Failure):
return found
weight = number(found[1], f"goal {found[0]}'s weight")
if isinstance(weight, Failure):
return weight
if found[0] in weights:
return Failure(f"the goal weights list goal {found[0]} twice")
weights[found[0]] = weight
if list(weights) != goals:
default = "\n".join(f"| {goal} | {(len(goals) - index) / len(goals):.2f} |" for index, goal in enumerate(goals))
return Failure(f"the goal weights list {', '.join(weights) or 'no goal'}, but README.md's goals are {', '.join(goals)}; by position they weigh:\n{WEIGHTS_HEADER}\n|---|---|\n{default}")
return weights
def parse_item(row: str, scoring: Scoring, table: Table) -> Item | Failure:
"""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
if broken := cited_goals_failure(item, scoring):
return broken
if scoring.shape is OLD_SHAPE:
return item
# R is written here, as the Score is, so --check finds a stale one, and a reader keeps the R the table stored.
return dataclasses.replace(item, scores=item.scores | {"R": risk(item.scores["L"], item.scores["E"], item.scores["I"])})
def cited_goals_failure(item: Item, scoring: Scoring) -> Failure | None:
"""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
for goal, _ in item.moves:
if goal == CODE_HEALTH and goal not in scoring.goals:
return Failure(f"item {item.id} names {CODE_HEALTH}, which README.md voids; drop it from the item's {MOVES}, or the void from README.md")
if goal not in scoring.goals:
return Failure(f"item {item.id} cites goal {goal}, which README.md's ## Goals does not number")
if scoring.goals[goal] == "Maintain" and item.exempt != "defect":
return Failure(f"item {item.id} cites goal {goal}, a maintain goal, which only a defect that restores it may name; name the achieve goals the item moves")
return None
def render_item(item: Item, value: float, shape: Shape, columns: tuple[str, ...]) -> str:
"""The item's row, each cell under its column."""
written = {"ID": str(item.id), "Release": version(item.release), BLOCKED_BY: ", ".join(map(str, item.blocked_by)), "Exempt": item.exempt, "Item": item.tagline, **{name: str(score) for name, score in item.scores.items()}, shape.goals_column: shape.write_goals(item.moves), "Score": f"{value:.1f}"}
return "| " + " | ".join(written[column] for column in columns) + " |"
def rank_details(text: str, items: list[Item]) -> str | Failure:
section = DETAILS.search(text)
details = item_details(text)
if section is None or isinstance(details, Failure):
return details if isinstance(details, Failure) else text
if unknown := sorted(set(details) - {item.id for item in items}):
return Failure(f"## Details holds item {', '.join(map(str, unknown))}, which the items table does not")
headed = [f"### {item.id}. {item.tagline.strip('*').replace(chr(92) + '|', '|')}\n\n{details[item.id]}\n" for item in items if item.id in details]
ranked = "\n" + "\n".join(headed) if headed else "\n"
tail = "\n" if section.end() < len(text) else ""
return text[:section.start(1)] + ranked + tail + text[section.end():]
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
sys.exit(ranking.main(sys.argv[1:]))
+2 -2
View File
@@ -5,8 +5,8 @@ import statistics
from failure import Failure
from transcript_archive.read import FinishedChunk
from reading_cost.measure import Reading
from markdown_text import sections
from utc_stamp import STAMPED
from records.markdown_text import sections
from records.utc_stamp import STAMPED
FIGURE = re.compile(rf"^Reading cost, chunk (\w+), finished ({STAMPED})$")
FIGURE_FILE = re.compile(r"^- `(.+)` (\d+)$")
+3 -3
View File
@@ -32,10 +32,10 @@ from reading_cost.measure import Checkout, measure, Reading
from failure import Failure
from reading_cost.figures import figure, merged, readings_of, RECORD, RESET, trend, unheld
from transcript_archive.read import finished_chunks, read_threads
from git_repo import git
from git_cli.git_repo import git
from transcript_archive.location import project_archive
from file_writes import replace_file
from utc_stamp import utc
from records.file_writes import replace_file
from records.utc_stamp import utc
@dataclasses.dataclass(frozen=True)
class Updated:
+2 -2
View File
@@ -3,9 +3,9 @@ import dataclasses
import re
from claude_code.entries import assistant_parts, parse_entry, tool_call, usage_count
from git_command import commits
from git_cli.git_command import commits
from reading_cost.shell_reads import Reads, shell_reads
from shell_command import resolved, simple_commands
from command_lines.shell_command import resolved, simple_commands
+1 -1
View File
@@ -3,7 +3,7 @@ import dataclasses
import posixpath
import re
from shell_command import resolved, simple_commands
from command_lines.shell_command import resolved, simple_commands
NOT_A_PATH = re.compile(r"[*?\[\]{}$\\'\",=()<>|;&]|://|^\d+$")
# Their first operand is a pattern or a program, unless -e or -f gives it.
View File
@@ -4,12 +4,10 @@ import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
import file_writes
from records import file_writes
class ReplaceFile(unittest.TestCase):
def test_removes_what_it_staged_when_the_replace_fails(self):
with tempfile.TemporaryDirectory() as root:
@@ -2,11 +2,9 @@ import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
import markdown_text
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from records import markdown_text
class Sections(unittest.TestCase):
def test_keeps_every_headed_section_with_its_bodies(self):
text = "# Title\n\nintro\n\n## Goals\n\n1. one\n```sh\n# not a heading\n```\n### Later\n2. two\n#1 priority\n\n## Empty\n\n## Audience\nme\n## Audience\nagain\n# Appendix\nnot audience\n"
View File
+656
View File
@@ -0,0 +1,656 @@
"""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 ast
import dataclasses
import decimal
import graphlib
import math
import pathlib
import re
import sys
import typing
from release_plan.todo_table import BLOCKED_BY, cells, CODE_HEALTH, DETAILS, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, Shape, SHAPE, shape_of, Table, table_rows
from failure import Failure
from review_rules.comprehension_history import FLOOR, HISTORY, latest_overall
from records.markdown_text import listed, sections
from records.file_writes import replace_file
from release_plan.release import version
# What each achieve goal weighs of the one above it; docs/decisions.md records the choice.
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
# 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)
LARGEST_FORMULA = 200
LONGEST_FORMULA = 4 * LARGEST_FORMULA
OPERATORS = (ast.Add, ast.BinOp, ast.Div, ast.Expression, ast.Load, ast.Mult, ast.Pow, ast.Sub, ast.UAdd, ast.UnaryOp, ast.USub)
WEIGHTS_HEADER = "| Goal | W |"
# The Exempt reasons that rank ahead of the rest of their release, in this order: a question first, since its answer may change other items, then a security finding.
FIRST = {"question": 0, "security": 1}
# How README.md marks a goal; None where it marks it neither way.
Mark = typing.Literal["Maintain", "Achieve"] | None
RESHAPE = f"todo.md's items table is in the old shape, scoring A and G against goal weights todo.md states. Until todo.md has the shape rank_todo.py --help shows, reshaping it is the project's only work, as ~/.claude/CLAUDE.md → 'Working loop' says: mark README.md's goals **Maintain:** or **Achieve:**, name each item's {MOVES}, score its L, E and I in place of C, and set the bar below the score of every item to keep"
@dataclasses.dataclass(frozen=True)
class Scoring:
shape: Shape
formula: ast.Expression
bar: float
next_id: int
# 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.
weights: dict[str, float]
@dataclasses.dataclass(frozen=True)
class Ranked:
text: str
under_bar: list[str]
# What ranking prints and --check does not: an old-shape table's call to reshape, a README that voids code health and marks no goal **Achieve:**, and each dropped blocker ID, since a mistyped ID drops the same way.
notes: list[str]
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 = check_failures(todo)
for line in failures:
print(line, file=sys.stderr)
return 1 if failures else 0
ranked = rank_file(todo)
if isinstance(ranked, Failure):
return fail(ranked)
return 1 if ranked.under_bar else 0
def rank_file(todo: pathlib.Path) -> Ranked | Failure:
"""Rank todo in place: rank what read_all reads, write todo where that changed it, and print the notes and under-bar lines on stderr."""
texts = read_all(todo)
if isinstance(texts, Failure):
return texts
ranked = rank(*texts)
if isinstance(ranked, Failure):
return ranked
if ranked.text != texts[0] and (unwritten := write(todo, ranked.text)):
return unwritten
for line in ranked.notes + ranked.under_bar:
print(f"{todo}: {line}", file=sys.stderr)
return ranked
def check_failures(todo: pathlib.Path) -> list[str]:
"""Why --check fails on todo, empty when it passes."""
texts = read_all(todo)
if isinstance(texts, Failure):
return [texts.reason]
ranked = rank(*texts)
if isinstance(ranked, Failure):
return [ranked.reason]
unranked = [] if ranked.text == texts[0] else [f"{todo}: not ranked; run rank_todo.py on it"]
return unranked + [f"{todo}: {line}" for line in ranked.under_bar]
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")
def read_all(todo: pathlib.Path) -> tuple[str, str, str, str] | Failure:
"""todo.md, the README.md beside it, and its docs/decisions.md and docs/comprehension-history.md, each empty when there is none."""
texts = []
for path, missing in ((todo, "every project keeps a todo.md beside its README.md, and rank_todo.py --help shows one"), (todo.parent / "README.md", "rank_todo.py weighs goals from the README.md beside todo.md"), (todo.parent / "docs" / "decisions.md", None), (todo.parent / HISTORY, None)):
try:
texts.append(path.read_text(encoding="utf-8"))
except FileNotFoundError:
if missing:
return Failure(f"{path}: not found; {missing}")
texts.append("")
except OSError as failure:
return Failure(f"{path}: {failure.strerror}")
except UnicodeDecodeError:
return Failure(f"{path}: not UTF-8")
return texts[0], texts[1], texts[2], texts[3]
def write(path: pathlib.Path, text: str) -> Failure | None:
unwritten = replace_file(path.resolve(), text.encode("utf-8"))
return Failure(f"{path}: {unwritten.reason}") if unwritten else None
def rank(text: str, readme: str, decisions: str, history: str) -> Ranked | Failure:
lines = text.split("\n")
table = read_table(lines)
if isinstance(table, Failure):
return table
shape = shape_of(table.columns)
scoring = read_scoring(text, lines, readme, decisions, history, shape)
if isinstance(scoring, Failure):
return scoring
items = read_items(table, scoring)
if isinstance(items, Failure):
return items
if uncited := check_citations(items, decisions):
return uncited
if isinstance(marked := renames(text), Failure):
return marked
if live := next((item for item in items if item.release in marked), None):
return Failure(f"todo.md marks release {version(live.release)} renamed but files item {live.id} under it; drop the mark or move the item")
scored = ordered(items, scoring)
if isinstance(scored, Failure):
return scored
ranked = rank_details(rewrite_table(lines, table, shape, scored), [item for item, _ in scored])
if isinstance(ranked, Failure):
return ranked
under_bar = [under_the_bar(item, value, scoring.bar, items) for item, value in scored if not item.exempt and round(value, 1) < scoring.bar]
return Ranked(ranked, under_bar, notes(items, scoring))
# The columns ranking fills itself, so a table without one gains it.
WRITTEN = (BLOCKED_BY, "R", "Score")
def rewrite_table(lines: list[str], table: Table, shape: Shape, scored: list[tuple[Item, float]]) -> str:
"""lines with the table's rows in scored's order, under a header naming, in shape's order, each column the table holds and each of WRITTEN."""
columns = tuple(column for column in shape.columns if column in table.columns or column in WRITTEN)
header = ["| " + " | ".join(columns) + " |", "|" + "---|" * len(columns)]
rows = [render_item(item, value, shape, columns) for item, value in scored]
return "\n".join(lines[:table.header] + header + rows + lines[table.start + len(table.rows):])
def notes(items: list[Item], scoring: Scoring) -> list[str]:
held = {item.id for item in items}
dropped = [f"item {item.id}: dropped {', '.join(map(str, gone))} from its {BLOCKED_BY}; the table no longer holds {'it' if len(gone) == 1 else 'them'}" for item in items if (gone := sorted(set(item.blocked_by) - held))]
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"]
return unweighed + dropped
def blocked_through(id_: int, items: list[Item]) -> set[int]:
"""The IDs of the items id_ blocks, and of those they block in turn."""
found: set[int] = set()
reached = {id_}
while reached:
reached = {other.id for other in items if reached.intersection(other.blocked_by)} - found
found |= reached
return found
def ordered(items: list[Item], scoring: Scoring) -> list[tuple[Item, float]] | Failure:
"""Each item with its score, by release, then questions and security findings first, then by score from highest, then by ID; then each blocker above every item it blocks."""
by_score = []
for item in items:
value = score(scoring.formula, item, scoring)
if isinstance(value, Failure):
return value
by_score.append((item, value))
by_score.sort(key=lambda pair: (pair[0].release, FIRST.get(pair[0].exempt, len(FIRST)), -pair[1], pair[0].id))
return blockers_first(by_score)
def under_the_bar(item: Item, value: float, bar: float, items: list[Item]) -> str:
blocks = [str(id_) for id_ in sorted(blocked_through(item.id, items))]
blocked = f" and the items it blocks, directly or through another ({', '.join(blocks)})" if blocks else ""
return f"item {item.id} scores {value:.1f}, under the bar {bar:g}; delete it{blocked}, or mark it with a reason the bar does not apply"
def read_scoring(text: str, lines: list[str], readme: str, decisions: str, history: str, shape: Shape) -> Scoring | Failure:
goals = ranked_goals(readme, decisions)
if isinstance(goals, Failure):
return goals
formula = parse_formula(stated(text, "Score"), variables(shape))
if isinstance(formula, Failure):
return formula
bar = number(stated(text, "Bar"), "the bar")
if isinstance(bar, Failure):
return bar
next_id = stated(text, "Next ID")
if isinstance(next_id, Failure) or not re.fullmatch(r"[0-9]+", next_id):
return next_id if isinstance(next_id, Failure) else Failure(f"Next ID {next_id!r} is not a whole number")
weights = weigh(lines, history, goals, shape)
if isinstance(weights, Failure):
return weights
return Scoring(shape, formula, bar, int(next_id), dict(goals), weights)
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:** 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
voids = VOID.findall("".join(sections(readme).get("Goals", [])))
if other := [void for void in voids if not void.startswith(f"{CODE_HEALTH}, since ")]:
if other[0].lower().startswith(CODE_HEALTH):
return Failure(f"README.md's ## Goals voids code health as `{other[0]}`; spell the void exactly `**Void:** {CODE_HEALTH}, since <reason>.`")
return Failure(f"README.md's ## Goals voids `{other[0]}`; only code health may be voided, as `**Void:** {CODE_HEALTH}, since <reason>.`")
if voids:
return goals
if OPTED_OUT.search(decisions):
return Failure(f"docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** {CODE_HEALTH}, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says")
return [(CODE_HEALTH, "Achieve"), *goals]
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 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 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
return goal_weights(goals, overall)
def read_table(lines: list[str]) -> Table | Failure:
"""The items table, held to its shape's columns and alone under ## Items."""
if "## Items" not in lines:
return Failure("todo.md is not in the scored-table format; rank_todo.py --help shows a valid one")
table = items_table(lines)
if table is None:
return Failure(f"## Items holds no table whose header opens {HEADER_START}; rank_todo.py --help shows a valid one")
if isinstance(table, Failure):
return table
shape = shape_of(table.columns)
if missing := [column for column in shape.risk_columns if column not in table.columns]:
old = older_columns(table, shape)
dropped = f", and drop {listed(old, 'and')}" if old else ""
columns = f"{listed(missing, 'and')} column; add it" if len(missing) == 1 else f"{listed(missing, 'and')} columns; add them"
return Failure(f"todo.md's items table has no {columns}, scoring each item's {listed(shape.risk_columns, 'and')} as rank_todo.py --help shows{dropped}")
return unknown_columns(table, shape) or outside_items(lines, table) or table
def unknown_columns(table: Table, shape: Shape) -> Failure | None:
"""Why ranking, which writes only the columns of the table's shape, would drop one of the table's columns; None when it would drop none."""
unknown = [column for column in table.columns if column not in shape.columns]
if old := older_columns(table, shape):
kind = "a column of an older shape; drop it" if len(old) == 1 else "columns of an older shape; drop them"
return Failure(f"todo.md's items table has {listed(old, 'and')}, {kind}, as rank_todo.py --help shows")
if unknown:
return Failure(f"todo.md's items table has the column {', '.join(unknown)}, which this rank_todo.py does not know; the columns it knows are {', '.join(shape.columns)}. Rename it, or move this machine to the release that added it")
return None
def older_columns(table: Table, shape: Shape) -> list[str]:
"""The table's columns that only OLD_SHAPE knows, where the table is in SHAPE."""
return [column for column in table.columns if column not in SHAPE.columns and column in OLD_SHAPE.columns] if shape is SHAPE else []
def read_items(table: Table, scoring: Scoring) -> list[Item] | Failure:
items = []
for row in table.rows:
item = parse_item(row, scoring, table)
if isinstance(item, Failure):
return item
items.append(item)
ids = {item.id for item in items}
if len(ids) < len(items):
return Failure("two items share an ID")
if ids and max(ids) >= scoring.next_id:
return Failure(f"item {max(ids)} is not under Next ID {scoring.next_id}; raise Next ID past every ID")
for item in items:
if unheld := [blocker for blocker in item.blocked_by if blocker >= scoring.next_id]:
return Failure(f"item {item.id} is blocked by item {unheld[0]}, which is not under Next ID {scoring.next_id}; name an item the table holds or held")
return items
def outside_items(lines: list[str], table: Table) -> Failure | None:
"""Why the table does not stand alone under ## Items: the table's order is todo.md's only order."""
heading = max((index for index in range(table.header) if lines[index].startswith("## ")), default=None)
if heading is None:
return Failure("the items table sits under no ## heading; move it under ## Items")
if lines[heading] != "## Items":
return Failure(f"the items table sits under {lines[heading]}, not ## Items; move it under ## Items")
after = lines[table.start + len(table.rows):]
section = after[:next((index for index, line in enumerate(after) if line.startswith("## ")), len(after))]
if any(line.strip() for line in lines[heading + 1:table.header] + section):
return Failure(f"## Items holds text beside its table; an order goes in the scores or the {BLOCKED_BY} column, and a note in the item's detail")
return None
def blockers_first(scored: list[tuple[Item, float]]) -> list[tuple[Item, float]] | Failure:
"""scored, each blocker that ranks below an item it blocks moved up to just above the first such item; a blocker the table no longer holds was finished or deleted, and is dropped."""
held = {item.id: (item, value) for item, value in scored}
position = {item.id: index for index, (item, _) in enumerate(scored)}
for item, _ in scored:
for blocker in item.blocked_by:
if blocker in held and held[blocker][0].release > item.release:
later, earlier = version(held[blocker][0].release), version(item.release)
return Failure(f"item {item.id}, in release {earlier}, is blocked by item {blocker}, in later release {later}; move item {blocker} to release {earlier} or earlier, or item {item.id} to release {later} or later")
if loop := blocking_loop(held):
return Failure(f"items {', '.join(map(str, loop[:-1]))} and {loop[-1]} block each other in a loop; drop one of the blockers")
placed: set[int] = set()
return [entry for item, _ in scored for entry in place(item.id, held, position, placed)]
def blocking_loop(held: dict[int, tuple[Item, float]]) -> list[int] | None:
"""The IDs of items that block each other in a loop, sorted; None where there is no loop."""
graph = {id_: {blocker for blocker in item.blocked_by if blocker in held} for id_, (item, _) in held.items()}
try:
graphlib.TopologicalSorter(graph).prepare()
except graphlib.CycleError as cycle:
return sorted(set(cycle.args[1]))
return None
def place(id_: int, held: dict[int, tuple[Item, float]], position: dict[int, int], placed: set[int]) -> list[tuple[Item, float]]:
"""The item id_, unless placed holds it, preceded by those of its blockers placed doesn't hold yet, each in score order, and theirs before them. Each item it returns joins placed. blocking_loop has ruled out a loop."""
if id_ in placed:
return []
placed.add(id_)
item, value = held[id_]
blockers = sorted((blocker for blocker in set(item.blocked_by) if blocker in held), key=position.__getitem__)
before = [entry for blocker in blockers for entry in place(blocker, held, position, placed)]
return [*before, (dataclasses.replace(item, blocked_by=tuple(sorted(blockers))), value)]
def check_citations(items: list[Item], decisions: str) -> Failure | None:
"""Holds todo.md and docs/decisions.md to each other: a cited item is exempt, a decision row is cited."""
cited = set(cited_items(decisions))
if gone := sorted(cited - {item.id for item in items}):
return Failure(f"docs/decisions.md cites \"`todo.md` item {gone[0]}\", which todo.md no longer holds; revise that decision to say what holds now")
for item in sorted(items, key=lambda item: item.id):
if item.id in cited and not item.exempt:
return Failure(f"docs/decisions.md cites \"`todo.md` item {item.id}\"; mark it decision, or another reason the bar does not apply")
if item.exempt == "decision" and item.id not in cited:
return Failure(f"item {item.id} is marked decision, but docs/decisions.md does not cite \"`todo.md` item {item.id}\"; cite it there, or mark it with another reason the bar does not apply")
return None
def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
"""README.md's goals in reading order: each one's number, a sub-goal as 4.1, and its mark, Maintain, Achieve or None."""
found = sections(readme).get("Goals", [])
if len(found) != 1:
return Failure(f"README.md has ## Goals {len(found)} times; it needs it once")
goals: list[tuple[str, Mark]] = []
path: list[tuple[int, str]] = []
for indent, position, mark in re.findall(r"^([ \t]*)(\d+)\. (?:\*\*(Maintain|Achieve):\*\*)?", found[0].expandtabs(4), re.M):
while path and path[-1][0] >= len(indent):
path.pop()
path.append((len(indent), position))
goals.append((".".join(part for _, part in path), typing.cast(Mark, mark or None)))
numbers = [number for number, _ in goals]
if not goals:
return Failure("README.md's ## Goals has no numbered goal")
if len(set(numbers)) < len(numbers):
return Failure(f"README.md's ## Goals numbers {', '.join(numbers)}; number each goal by its position")
return goals
def goal_weights(goals: list[tuple[str, Mark]], 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; only a defect that restores it may name it. 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."""
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"]
total = sum(GOAL_STEP**rank for rank in range(len(achieve)))
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"}
def cited_items(decisions: str) -> list[int]:
return [int(id_) for cited in re.findall(r"`todo\.md` items? (\d+(?:(?:, | and )\d+)*)", decisions) for id_ in re.findall(r"\d+", cited)]
def stated(text: str, name: str) -> str | Failure:
found = re.findall(rf"^`{name} = ([^`]+)`$", text, re.M)
if len(found) != 1:
return Failure(f"todo.md states `{name} = ...` {len(found)} times; state it once, on a line of its own under ## Scoring")
return found[0]
def parse_formula(source: str | Failure, variables: tuple[str, ...]) -> ast.Expression | Failure:
if isinstance(source, Failure):
return source
# Deep nesting makes the parser itself run out of memory before LARGEST_FORMULA can count the parts.
if len(source) > LONGEST_FORMULA:
return Failure(f"the formula {source[:40]!r}... holds more than {LONGEST_FORMULA} characters")
try:
tree = ast.parse(source, mode="eval")
except (SyntaxError, ValueError):
return Failure(f"the formula {source!r} does not parse")
nodes = list(ast.walk(tree))
if len(nodes) > LARGEST_FORMULA:
return Failure(f"the formula {source!r} holds more than {LARGEST_FORMULA} parts")
for node in nodes:
numeric = isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool) and abs(node.value) < 1e300
if not (isinstance(node, OPERATORS) or numeric or (isinstance(node, ast.Name) and node.id in variables)):
return Failure(f"the formula {source!r} may hold only numbers, {', '.join(variables)}, + - * / ** and parentheses")
return tree
def evaluate(node: ast.AST, values: dict[str, float]) -> float:
"""Evaluates a tree parse_formula accepted; a division by zero, and a power that overflows or has no real value, give nan."""
match node:
case ast.Expression(body):
return evaluate(body, values)
case ast.Constant(value) if isinstance(value, (int, float)):
return float(value)
case ast.Name(name):
return values[name]
case ast.UnaryOp(ast.USub(), operand):
return -evaluate(operand, values)
case ast.UnaryOp(ast.UAdd(), operand):
return evaluate(operand, values)
case ast.BinOp(left, ast.Add(), right):
return evaluate(left, values) + evaluate(right, values)
case ast.BinOp(left, ast.Sub(), right):
return evaluate(left, values) - evaluate(right, values)
case ast.BinOp(left, ast.Mult(), right):
return evaluate(left, values) * evaluate(right, values)
case ast.BinOp(left, ast.Div(), right):
divisor = evaluate(right, values)
return evaluate(left, values) / divisor if divisor else math.nan
case ast.BinOp(left, ast.Pow(), right):
# math.pow raises on a negative base with a fractional exponent, zero to a negative power, and overflow; one catch covers all three.
base, exponent = evaluate(left, values), evaluate(right, values)
# A nan from a zero divisor stays nan, though math.pow(1, nan) and math.pow(nan, 0) give 1.
if math.isnan(base) or math.isnan(exponent):
return math.nan
try:
return math.pow(base, exponent)
except (OverflowError, ValueError):
return math.nan
return math.nan
def goal_term(shape: Shape) -> str:
"""The name of the formula's goal term, which score builds: W in OLD_SHAPE, V in the current shape."""
return "W" if shape is OLD_SHAPE else "V"
def variables(shape: Shape) -> tuple[str, ...]:
"""The names the formula may use: the shape's scores but C, which stays out of the formula, and its goal term."""
return tuple(sorted({*shape.score_columns} - {"C"} | {goal_term(shape)}))
def score(formula: ast.Expression, item: Item, scoring: Scoring) -> float | Failure:
if goal_term(scoring.shape) == "W":
# The old shape weighs an item by its heaviest cited goal.
term = max(scoring.weights[goal] for goal, _ in item.moves)
else:
# Only an OLD_SHAPE item names a goal without a move.
term = sum(scoring.weights[goal] * (by or 0) for goal, by in item.moves)
value = evaluate(formula, {**item.scores, goal_term(scoring.shape): term})
return value if math.isfinite(value) else Failure(f"the formula gives item {item.id} no finite score")
def number(text: str | Failure, what: str) -> float | Failure:
if isinstance(text, Failure):
return text
try:
value = float(text)
except ValueError:
value = math.nan
return value if math.isfinite(value) else Failure(f"{what} {text!r} is not a finite number")
def parse_weights(lines: list[str], goals: list[str]) -> dict[str, float] | Failure:
table = table_rows(lines, WEIGHTS_HEADER)
if isinstance(table, Failure):
return table
weights: dict[str, float] = {}
for row in table.rows:
found = cells(row, 2)
if isinstance(found, Failure):
return found
weight = number(found[1], f"goal {found[0]}'s weight")
if isinstance(weight, Failure):
return weight
if found[0] in weights:
return Failure(f"the goal weights list goal {found[0]} twice")
weights[found[0]] = weight
if list(weights) != goals:
default = "\n".join(f"| {goal} | {(len(goals) - index) / len(goals):.2f} |" for index, goal in enumerate(goals))
return Failure(f"the goal weights list {', '.join(weights) or 'no goal'}, but README.md's goals are {', '.join(goals)}; by position they weigh:\n{WEIGHTS_HEADER}\n|---|---|\n{default}")
return weights
def parse_item(row: str, scoring: Scoring, table: Table) -> Item | Failure:
"""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
if broken := cited_goals_failure(item, scoring):
return broken
if scoring.shape is OLD_SHAPE:
return item
# R is written here, as the Score is, so --check finds a stale one, and a reader keeps the R the table stored.
return dataclasses.replace(item, scores=item.scores | {"R": risk(item.scores["L"], item.scores["E"], item.scores["I"])})
def cited_goals_failure(item: Item, scoring: Scoring) -> Failure | None:
"""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
for goal, _ in item.moves:
if goal == CODE_HEALTH and goal not in scoring.goals:
return Failure(f"item {item.id} names {CODE_HEALTH}, which README.md voids; drop it from the item's {MOVES}, or the void from README.md")
if goal not in scoring.goals:
return Failure(f"item {item.id} cites goal {goal}, which README.md's ## Goals does not number")
if scoring.goals[goal] == "Maintain" and item.exempt != "defect":
return Failure(f"item {item.id} cites goal {goal}, a maintain goal, which only a defect that restores it may name; name the achieve goals the item moves")
return None
def render_item(item: Item, value: float, shape: Shape, columns: tuple[str, ...]) -> str:
"""The item's row, each cell under its column."""
written = {"ID": str(item.id), "Release": version(item.release), BLOCKED_BY: ", ".join(map(str, item.blocked_by)), "Exempt": item.exempt, "Item": item.tagline, **{name: str(score) for name, score in item.scores.items()}, shape.goals_column: shape.write_goals(item.moves), "Score": f"{value:.1f}"}
return "| " + " | ".join(written[column] for column in columns) + " |"
def rank_details(text: str, items: list[Item]) -> str | Failure:
section = DETAILS.search(text)
details = item_details(text)
if section is None or isinstance(details, Failure):
return details if isinstance(details, Failure) else text
if unknown := sorted(set(details) - {item.id for item in items}):
return Failure(f"## Details holds item {', '.join(map(str, unknown))}, which the items table does not")
headed = [f"### {item.id}. {item.tagline.strip('*').replace(chr(92) + '|', '|')}\n\n{details[item.id]}\n" for item in items if item.id in details]
ranked = "\n" + "\n".join(headed) if headed else "\n"
tail = "\n" if section.end() < len(text) else ""
return text[:section.start(1)] + ranked + tail + text[section.end():]
@@ -2,8 +2,7 @@
import re
from failure import Failure
import git_repo
from git_cli import git_repo
Release = tuple[int, int, int]
VERSION = r"[0-9]+\.[0-9]+\.[0-9]+"
# The digits of a dated heading's year, month and day, which DATED and dated_heading_pattern each render.
@@ -1,11 +1,11 @@
"""How the plan stands to the last release cut: the next release, whether work has landed towards it, and whether it is to be planned, reviewed or cut; and, from that standing, the item the next chunk takes first, with what the default branch holds for the pick."""
import dataclasses
from git_repo import commits_since, file_at, git
from release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged
from git_cli.git_repo import commits_since, file_at, git
from release_plan.release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged
from failure import Failure
from todo_table import Item, items, next_item, renames
from markdown_text import sections
from release_plan.todo_table import Item, items, next_item, renames
from records.markdown_text import sections
# The version a branch with no v* tag and no dated CHANGELOG.md heading counts as cut: below every release, 0.0.0 included, so that every release todo.md names comes after it.
BEFORE_FIRST_RELEASE = (-1, 0, 0)
@@ -6,13 +6,12 @@ import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
import rank_todo
from release_plan import ranking
from repo_checks import ROOT
import todo_table
from release_plan import todo_table
# Voids code health, so these tests weigh only the project's own goals; class CodeHealth weighs it.
VOID = "**Void:** code health, since a test project has no code to read.\n\n"
@@ -99,7 +98,7 @@ Kept as written.
class Rank(unittest.TestCase):
def ranked(self, todo=TODO, readme=README, decisions=DECISIONS):
return rank_todo.rank(todo, readme, decisions, "")
return ranking.rank(todo, readme, decisions, "")
def test_scores_and_sorts_by_release_then_security_then_score_and_orders_the_details_to_match(self):
ranked = self.ranked()
@@ -120,17 +119,17 @@ class Rank(unittest.TestCase):
def test_weighs_each_achieve_goal_97_percent_of_the_one_above_and_a_defects_maintain_goal_as_the_first(self):
readme = "## Goals\n\n1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
self.assertEqual({goal: round(weight, 4) for goal, weight in rank_todo.goal_weights(rank_todo.readme_goals(readme), 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.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_as_the_help_says(self):
for count, first, last in ((5, 0.212, 0.188), (15, 0.082, 0.053)):
with self.subTest(count=count):
goals = rank_todo.readme_goals("## Goals\n\n" + "".join(f"{number}. **Achieve:** G.\n" for number in range(1, count + 1)))
weights = list(rank_todo.goal_weights(goals, None).values())
goals = ranking.readme_goals("## Goals\n\n" + "".join(f"{number}. **Achieve:** G.\n" for number in range(1, count + 1)))
weights = list(ranking.goal_weights(goals, None).values())
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"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()))
for figure in (ranking.GOAL_STEP, first, last):
self.assertIn(str(figure), ranking.__doc__)
self.assertIn(f"While it is under {ranking.FLOOR}, or the history holds no scoring run, code health weighs {ranking.UNDER_FLOOR} times its weight by position, and the other goals keep theirs.", " ".join(ranking.__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"
@@ -143,7 +142,7 @@ class Rank(unittest.TestCase):
self.assertEqual(ranked.under_bar, ["item 2 scores 0.0, under the bar 2; delete it, or mark it with a reason the bar does not apply"])
def test_holds_each_item_a_decision_cites_and_says_how_to_settle_a_finished_one(self):
self.assertIsInstance(self.ranked(decisions=DECISIONS + "Until `todo.md` item 4 lands.\n"), rank_todo.Ranked)
self.assertIsInstance(self.ranked(decisions=DECISIONS + "Until `todo.md` item 4 lands.\n"), ranking.Ranked)
gone = self.ranked(TODO.replace("| 5 | 0.1.0 | | decision | **Move the writes out.** | 1 | 1 | 4 | 5 | 5 | 2.1 by 1 | 0 |\n", ""))
self.assertEqual(gone.reason, "docs/decisions.md cites \"`todo.md` item 5\", which todo.md no longer holds; revise that decision to say what holds now")
@@ -157,11 +156,11 @@ class Rank(unittest.TestCase):
self.assertEqual(self.ranked(ranked.text.replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | owner |")).under_bar, [])
def test_reads_goals_and_sub_goals_in_reading_order(self):
self.assertEqual(rank_todo.readme_goals(README), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
self.assertEqual(rank_todo.readme_goals(README.replace(" 1.", "\t1.")), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
self.assertEqual(rank_todo.readme_goals(README.replace("2. **Maintain:** Correct.", "```\n## Goals\n```\n2. Correct.")), [("1", "Achieve"), ("2", None), ("2.1", "Achieve")])
self.assertEqual(rank_todo.readme_goals(README.replace("2. **Maintain:**", "1. **Maintain:**")), Failure("README.md's ## Goals numbers 1, 1, 1.1; number each goal by its position"))
self.assertEqual(rank_todo.readme_goals("## Goals\n\n1. **Achieve:** A.\n 1. **Achieve:** B.\n\t2. **Achieve:** C.\n"), [("1", "Achieve"), ("1.1", "Achieve"), ("1.2", "Achieve")])
self.assertEqual(ranking.readme_goals(README), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
self.assertEqual(ranking.readme_goals(README.replace(" 1.", "\t1.")), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
self.assertEqual(ranking.readme_goals(README.replace("2. **Maintain:** Correct.", "```\n## Goals\n```\n2. Correct.")), [("1", "Achieve"), ("2", None), ("2.1", "Achieve")])
self.assertEqual(ranking.readme_goals(README.replace("2. **Maintain:**", "1. **Maintain:**")), Failure("README.md's ## Goals numbers 1, 1, 1.1; number each goal by its position"))
self.assertEqual(ranking.readme_goals("## Goals\n\n1. **Achieve:** A.\n 1. **Achieve:** B.\n\t2. **Achieve:** C.\n"), [("1", "Achieve"), ("1.1", "Achieve"), ("1.2", "Achieve")])
def test_refuses_a_goal_it_cannot_weigh(self):
cases = {
@@ -187,7 +186,7 @@ class Rank(unittest.TestCase):
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 |")
self.assertEqual(self.ranked(todo, readme), Failure("item 3 names goal 1 and its sub-goal 1.2; name one, never both: the sub-goal where the move serves it, else the parent"))
self.assertIsInstance(self.ranked(todo.replace("1.2 by 2, 1 by 3", "1.2 by 2, 2 by 3"), readme), rank_todo.Ranked)
self.assertIsInstance(self.ranked(todo.replace("1.2 by 2, 1 by 3", "1.2 by 2, 2 by 3"), readme), ranking.Ranked)
def test_scores_every_item_zero_where_readme_marks_no_goal_achieve(self):
ranked = self.ranked(TODO.replace("2.1 by 8, 1 by 6", "").replace("| 2.1 by 1 |", "| |").replace("| 1 by 9 |", "| |"), README.replace("**Achieve:**", "**Maintain:**"))
@@ -253,7 +252,7 @@ class CodeHealth(unittest.TestCase):
todo = TODO.split("| 1 | 0.2.0", 1)[0].replace("`Bar = 2`", "`Bar = 0.1`") + "| 1 | 0.1.0 | | | **Read easier.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 0 |\n| 2 | 0.1.0 | | | **Do A.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 0 |\n"
def scores(self, history, readme=readme):
ranked = rank_todo.rank(self.todo, readme, "", history)
ranked = ranking.rank(self.todo, readme, "", history)
return ranked if isinstance(ranked, Failure) else {line.split(" | ")[0]: line.rsplit(" | ", 1)[1].rstrip(" |") for line in ranked.text.splitlines() if line.startswith("| ") and " 0.1.0 " in line}
def entry(self, overall, at="2026-10-08T12", read="PR #1 at aaaaaaa"):
@@ -304,7 +303,7 @@ class CodeHealth(unittest.TestCase):
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"
self.assertEqual(self.scores("", voided), Failure("item 1 names code health, which README.md voids; drop it from the item's Moves, or the void from README.md"))
ranked = rank_todo.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", "")
ranked = ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", "")
self.assertIn("| **Read easier.** | 1 | 1 | 1 | 1 | 1 | 1 by 2 | 100.0 |", ranked.text)
def test_weighs_a_defects_maintain_goal_as_code_health_four_times_over_under_an_overall_of_7(self):
@@ -312,18 +311,18 @@ class CodeHealth(unittest.TestCase):
todo = self.todo.replace("| 2 | 0.1.0 | | | **Do A.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 |", "| 2 | 0.1.0 | | defect | **Restore B.** | 1 | 1 | 1 | 1 | 1 | 2 by 1 |")
for history, value in (("", "101.5"), (SCORED.format(overall="7.00"), "25.4")):
with self.subTest(history=history):
self.assertIn(f"| **Restore B.** | 1 | 1 | 1 | 1 | 1 | 2 by 1 | {value} |", rank_todo.rank(todo, readme, "", history).text)
self.assertIn(f"| **Restore B.** | 1 | 1 | 1 | 1 | 1 | 2 by 1 | {value} |", ranking.rank(todo, readme, "", history).text)
def test_refuses_a_plan_whose_project_opts_out_of_the_comprehension_check_yet_keeps_code_health(self):
opted_out = "## review opt-out: the architect and the comprehension check\n\nCosts rounds.\n"
self.assertEqual(rank_todo.rank(self.todo, self.readme, opted_out, ""), Failure("docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says"))
self.assertIsInstance(rank_todo.rank(self.todo, self.readme, opted_out.replace(" and the comprehension check", ""), ""), rank_todo.Ranked)
self.assertEqual(ranking.rank(self.todo, self.readme, opted_out, ""), Failure("docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says"))
self.assertIsInstance(ranking.rank(self.todo, self.readme, opted_out.replace(" and the comprehension check", ""), ""), ranking.Ranked)
voided = "## Goals\n\n**Void:** code health, since nobody reads the probes.\n\n1. **Achieve:** A.\n"
self.assertIsInstance(rank_todo.rank(self.todo.replace("code health by 1", "1 by 2"), voided, opted_out, ""), rank_todo.Ranked)
self.assertIsInstance(ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, opted_out, ""), ranking.Ranked)
def test_ranks_a_project_that_voids_code_health_whatever_its_history_holds(self):
voided = "## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** A.\n"
self.assertIsInstance(rank_todo.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", SCORED.format(overall="high")), rank_todo.Ranked)
self.assertIsInstance(ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", SCORED.format(overall="high")), ranking.Ranked)
def test_refuses_a_void_of_anything_but_code_health(self):
self.assertEqual(self.scores("", "## Goals\n\n**Void:** speed, since nobody waits.\n\n1. **Achieve:** A.\n"), Failure("README.md's ## Goals voids `speed, since nobody waits.`; only code health may be voided, as `**Void:** code health, since <reason>.`"))
@@ -346,14 +345,14 @@ class CodeHealth(unittest.TestCase):
pathlib.Path(temp, "docs").mkdir()
pathlib.Path(temp, "docs", "comprehension-history.md").write_text(SCORED.format(overall="7.00"))
with contextlib.redirect_stderr(io.StringIO()):
self.assertEqual(rank_todo.main([str(todo)]), 0)
self.assertEqual(ranking.main([str(todo)]), 0)
self.assertIn("| code health by 1 | 25.4 |", todo.read_text())
class Risk(unittest.TestCase):
"""R is L + E + I - 2, which rank_todo.py writes, at least 7 when I is 5 and at least 5 when I is 4."""
def ranked(self, todo):
return rank_todo.rank(todo, README, DECISIONS, "")
return ranking.rank(todo, README, DECISIONS, "")
def test_writes_r_from_l_e_and_i_over_a_stale_or_missing_r(self):
ranked = self.ranked(TODO).text
@@ -402,7 +401,7 @@ class Risk(unittest.TestCase):
class OldShape(unittest.TestCase):
"""A table with A, G and Goals, from before the Moves column, ranks by the formula and goal weights it states until its project reshapes it."""
def ranked(self, todo=OLD_SHAPE, readme=README):
return rank_todo.rank(todo, readme, DECISIONS, "")
return ranking.rank(todo, readme, DECISIONS, "")
def test_scores_by_the_stated_weights_and_says_to_reshape(self):
ranked = self.ranked()
@@ -412,7 +411,7 @@ class OldShape(unittest.TestCase):
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 5.1 |
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 9 | 9 | 1 | 34.8 |
""", ranked.text)
self.assertEqual(ranked.notes, [rank_todo.RESHAPE])
self.assertEqual(ranked.notes, [ranking.RESHAPE])
self.assertEqual(self.ranked(ranked.text), ranked)
unmarked = "# P\n\n## Goals\n\n1. Fast.\n2. Correct.\n 1. Tested.\n"
self.assertEqual(self.ranked(readme=unmarked), ranked)
@@ -429,7 +428,7 @@ class OldShape(unittest.TestCase):
def test_ranks_a_table_from_before_c_joined_and_says_to_reshape_it(self):
legacy = OLD_SHAPE.split("## Items")[0] + "## Items\n\n| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|\n| 2 | 0.1.0 | | **Tighten the tests.** | 2 | 4 | 5 | 5 | 2.1 | 0 |\n"
self.assertEqual(rank_todo.rank(legacy, README, "", "").notes, [rank_todo.RESHAPE])
self.assertEqual(ranking.rank(legacy, README, "", "").notes, [ranking.RESHAPE])
def test_refuses_a_table_with_both_moves_and_goals(self):
both = OLD_SHAPE.replace("| Goals | Score |\n|---|", "| Goals | Moves | Score |\n|---|---|").replace(" | 0 |\n", " | 1 by 1 | 0 |\n")
@@ -439,14 +438,14 @@ class OldShape(unittest.TestCase):
def test_names_the_goals_column_a_table_misspells_by_its_shape(self):
misspelt = TODO.replace("| S | Moves |", "| S | Move |")
self.assertEqual(rank_todo.rank(misspelt, README, DECISIONS, ""), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
self.assertEqual(ranking.rank(misspelt, README, DECISIONS, ""), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
self.assertEqual(todo_table.items(misspelt), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
self.assertEqual(self.ranked(OLD_SHAPE.replace("| G | Goals |", "| G | Goal |")), Failure("todo.md's items table has no Goals column; rank_todo.py --help shows a valid one"))
class Blockers(unittest.TestCase):
def ranked(self, todo):
return rank_todo.rank(todo, README, DECISIONS, "")
return ranking.rank(todo, README, DECISIONS, "")
def test_ranks_each_blocker_just_above_the_first_item_it_blocks(self):
ranked = self.ranked(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5, 2 |"))
@@ -525,7 +524,7 @@ class Blockers(unittest.TestCase):
def test_refuses_text_under_items_beside_the_table(self):
last = TODO.split("\n## Details")[0] + "\n"
self.assertIsInstance(self.ranked(last), rank_todo.Ranked)
self.assertIsInstance(self.ranked(last), ranking.Ranked)
beside = Failure("## Items holds text beside its table; an order goes in the scores or the Blocked by column, and a note in the item's detail")
for ordered in (TODO.replace("## Items\n\n", "## Items\n\nRelease 0.1.0 takes item 5 first.\n\n"), TODO.replace("## Items\n\n", "## Items\nTake item 5 first.\n\n"), TODO.replace("| 2.1 by 1 | 0 |\n\n## Details", "| 2.1 by 1 | 0 |\n\nTake item 5 first.\n\n## Details"), last + "\nTake item 5 first.\n"):
with self.subTest(ordered=ordered[-60:]):
@@ -559,15 +558,15 @@ class Renamed(unittest.TestCase):
self.assertIsInstance(todo_table.renames(f"## Renamed\n\n{bad}\n"), Failure)
def test_fails_on_a_renamed_section_that_does_not_parse(self):
failed = rank_todo.rank(TODO + "\n## Renamed\n\nsoon\n", README, DECISIONS, "")
failed = ranking.rank(TODO + "\n## Renamed\n\nsoon\n", README, DECISIONS, "")
self.assertIsInstance(failed, Failure)
self.assertIn("## Renamed", failed.reason)
def test_ranks_a_plan_with_a_valid_renamed_section(self):
self.assertIsInstance(rank_todo.rank(TODO + "\n## Renamed\n\n- 0.3.0 renamed to 0.4.0\n", README, DECISIONS, ""), rank_todo.Ranked)
self.assertIsInstance(ranking.rank(TODO + "\n## Renamed\n\n- 0.3.0 renamed to 0.4.0\n", README, DECISIONS, ""), ranking.Ranked)
def test_fails_on_an_item_filed_under_a_release_the_plan_marks_renamed(self):
live = rank_todo.rank(TODO + "\n## Renamed\n\n- 0.2.0 renamed to 0.3.0\n", README, DECISIONS, "")
live = ranking.rank(TODO + "\n## Renamed\n\n- 0.2.0 renamed to 0.3.0\n", README, DECISIONS, "")
self.assertIsInstance(live, Failure)
self.assertIn("marks release 0.2.0 renamed but files item 1 under it", live.reason)
@@ -576,7 +575,7 @@ class Renamed(unittest.TestCase):
class Main(unittest.TestCase):
def run_main(self, *argv):
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()) as said:
code = rank_todo.main(list(argv))
code = ranking.main(list(argv))
return code, said.getvalue()
def test_ranks_the_file_in_place_and_check_writes_nothing(self):
@@ -613,14 +612,14 @@ class Main(unittest.TestCase):
pathlib.Path(temp, "README.md").write_text(README)
pathlib.Path(temp, "docs").mkdir()
pathlib.Path(temp, "docs", "decisions.md").write_text(DECISIONS)
self.assertEqual(self.run_main(str(todo)), (0, f"{todo}: {rank_todo.RESHAPE}\n"))
self.assertEqual(self.run_main(str(todo)), (0, f"{todo}: {ranking.RESHAPE}\n"))
self.assertEqual(self.run_main("--check", str(todo)), (0, ""))
def test_shows_a_valid_file_in_help_and_names_arguments_it_cannot_read(self):
self.assertEqual(self.run_main("--help")[0], 0)
skeleton = "\n".join(line[4:] for line in rank_todo.__doc__.split("\n") if line.startswith(" "))
ranked = rank_todo.rank(skeleton, "## Goals\n\n1. **Achieve:** Work.\n", "", "")
self.assertIsInstance(ranked, rank_todo.Ranked)
skeleton = "\n".join(line[4:] for line in ranking.__doc__.split("\n") if line.startswith(" "))
ranked = ranking.rank(skeleton, "## Goals\n\n1. **Achieve:** Work.\n", "", "")
self.assertIsInstance(ranked, ranking.Ranked)
self.assertEqual((ranked.under_bar, ranked.notes), ([], []))
self.assertEqual(self.run_main("--fix"), (1, "rank_todo.py: cannot read the arguments --fix; usage: rank_todo.py [--check] [todo.md]\n"))
@@ -628,5 +627,5 @@ class Main(unittest.TestCase):
class ThisRepo(unittest.TestCase):
def test_todo_md_is_ranked_with_nothing_under_the_bar(self):
text = (ROOT / "todo.md").read_text(encoding="utf-8")
ranked = rank_todo.rank(text, *((ROOT / name).read_text(encoding="utf-8") for name in ("README.md", "docs/decisions.md", "docs/comprehension-history.md")))
self.assertEqual(ranked, rank_todo.Ranked(text, [], []))
ranked = ranking.rank(text, *((ROOT / name).read_text(encoding="utf-8") for name in ("README.md", "docs/decisions.md", "docs/comprehension-history.md")))
self.assertEqual(ranked, ranking.Ranked(text, [], []))
@@ -4,10 +4,10 @@ import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from test_env import isolated_env
from release import newest_tag, tagged
from release_plan.release import newest_tag, tagged
class NewestTag(unittest.TestCase):
@@ -4,13 +4,13 @@ import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from failure import Failure
from test_env import isolated_env
import release_standing
import todo_table
from release import version
from release_plan import release_standing
from release_plan import todo_table
from release_plan.release import version
HEADER = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
@@ -3,8 +3,8 @@ import re
import typing
from failure import Failure
from markdown_text import FENCE, sections
from release import parsed, Release, release_of, VERSION
from records.markdown_text import FENCE, sections
from release_plan.release import parsed, Release, release_of, VERSION
# Each score a Shape names, and each goal's move, runs from 1 to TOP_SCORE, but for the levels L, E and I, which run from 1 to their LEVELS: ~/.claude/rules/todo-items.md defines each level.
TOP_SCORE = 10
+1 -1
View File
@@ -5,7 +5,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from review_passes import PASS_AGENTS, PASSES
from review_rules.review_passes import PASS_AGENTS, PASSES
from repo_checks import ROOT
from rule_hook.reviewer_rung import SEAT, SECURITY_OPENER
+1 -1
View File
@@ -6,7 +6,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from settings_filter import cleaned
from git_repo import git
from git_cli.git_repo import git
from repo_checks import ROOT
INSTALL = "git config filter.settings.clean bin/settings_filter.py"
+1 -1
View File
@@ -30,5 +30,5 @@ class Types(unittest.TestCase):
self.assertEqual(ran.returncode, 0, ran.stdout + ran.stderr)
def test_mypy_checks_run_heavy_and_each_root_module(self):
self.assertLessEqual({("-p", "run_heavy"), ("-p", "machine_load"), ("-m", "release_standing"), ("-m", "docker_command")}, set(zip(tools()[::2], tools()[1::2])))
self.assertLessEqual({("-p", "run_heavy"), ("-p", "machine_load"), ("-p", "release_plan"), ("-m", "failure")}, set(zip(tools()[::2], tools()[1::2])))
self.assertNotIn("repo_checks", tools())
+3 -3
View File
@@ -41,7 +41,7 @@ import typing
from transcript_archive.location import archive_root
from rung_replay.command import arguments_or_exit, down_from, failed, limited_exit, projects_on
from review_replay.rounds import authored_by, lost_inputs, report, reviewed_path, Round, round_from, sample, stamp_seconds
from project_key import checkout_of
from transcript_archive.project_key import checkout_of
from claude_code.reply import claude_reply, Limited
from loop_claude.effects import Effects
from failure import Failure
@@ -49,8 +49,8 @@ from rung_replay.search import first_reply, replayed
from claude_code.transcript import first_timestamped_line, read_transcript
from model_routing.ladder import LADDER, project_rung, Rung
from claude_code.entries import parse_entry, structured_output
from review_folder import REPORTS, review_folder
from review_passes import ReviewedPass, REVIEWERS
from review_rules.review_folder import REPORTS, review_folder
from review_rules.review_passes import ReviewedPass, REVIEWERS
TOOL = "review-replay"
USAGE = f"{TOOL} <pass> <model>, <pass> one of {', '.join(REVIEWERS)} and <model> a model on the routing ladder"
+1 -1
View File
@@ -19,7 +19,7 @@ from loop_claude.effects import Effects, system_effects
from failure import Failure
from review_replay import main
from rung_replay.search import Miss, Replay, Tried
from review_passes import REVIEWERS
from review_rules.review_passes import REVIEWERS
from model_routing.ladder import Rung
TOOL = pathlib.Path(__file__).resolve().parents[1] / "review-replay"
View File
@@ -3,8 +3,8 @@ import decimal
import re
from failure import Failure
from markdown_text import sections
from utc_stamp import utc
from records.markdown_text import sections
from records.utc_stamp import utc
ARCHITECT = "Inherited architect"
DECIDED_BY = "decided by"
@@ -2,7 +2,7 @@
import dataclasses
import re
from review_passes import PASSES
from review_rules.review_passes import PASSES
# The most rounds a pass takes per chunk, per `docs/decisions.md` → `review: a pass gets at most two rounds per chunk, …`. rule-hook's `round-cap` refuses a round commit that `past_cap` finds takes its pass past it, and `larv-review round-count` marks a pass that reached it.
CAP = 2
@@ -2,9 +2,9 @@ import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from review_folder import review_folder
from review_rules.review_folder import review_folder
class ReviewFolder(unittest.TestCase):
@@ -3,9 +3,9 @@ import sys
import typing
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from review_passes import PASS_AGENTS, PASSES, prose, ReviewedPass, REVIEWERS
from review_rules.review_passes import PASS_AGENTS, PASSES, prose, ReviewedPass, REVIEWERS
class ReviewPasses(unittest.TestCase):
@@ -14,7 +14,7 @@ class ReviewPasses(unittest.TestCase):
self.assertEqual(list(REVIEWERS), [name for name in PASSES if PASS_AGENTS[name]])
def test_names_each_agent_under_agents(self):
agents = pathlib.Path(__file__).resolve().parents[1] / "agents"
agents = pathlib.Path(__file__).resolve().parents[2] / "agents"
self.assertEqual(sorted(REVIEWERS.values()), sorted(path.stem for path in agents.glob("*.md")))
def test_counts_markdown_an_agent_follows_as_config_and_the_rest_as_prose(self):
@@ -2,9 +2,9 @@ import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from round_titles import Findings, lacks_counts, past_cap, round_counts, round_findings, rounds_past_first
from review_rules.round_titles import Findings, lacks_counts, past_cap, round_counts, round_findings, rounds_past_first
class Rounds(unittest.TestCase):
+3 -3
View File
@@ -10,12 +10,12 @@ import typing
from transcript_archive.read import archived_outcomes, chunk_outcomes, finished_chunks
from branch_chunks.read import branch_chunks
from branch_chunks.cut import BranchChunk
from project_key import checkout_of
from transcript_archive.project_key import checkout_of
from routing_figures.chunk import Chunk, chunk_figures, ChunkFigures, Subagent
from git_repo import default_ref, Git
from git_cli.git_repo import default_ref, Git
from failure import Failure
from claude_code.entries import parse_entry
from file_writes import replace_file
from records.file_writes import replace_file
from transcript_archive.outcomes import VERDICT_AT
FIGURES = "routing-figures.md"
+3 -3
View File
@@ -5,13 +5,13 @@ import re
from claude_code.entries import assistant_parts, parts, tool_call, tool_result
from branch_chunks.cut import BranchChunk
from git_command import commits
from git_cli.git_command import commits
from routing_figures.dollars import costed, Dollars, Message, messages, recorded_costs, Spent
from model_routing.route import ESCALATION_MARKER, Route, route_from
from transcript_archive.outcomes import judge_costs, UNFINISHED_AT, workers
from round_titles import rounds_past_first
from review_rules.round_titles import rounds_past_first
from model_routing.ladder import Rung
from shell_command import simple_commands
from command_lines.shell_command import simple_commands
ESCALATION = re.compile(rf"{ESCALATION_MARKER} ([0-9]+):")
+2 -2
View File
@@ -8,8 +8,8 @@ import re
from routing_figures.calls import Call, SENTENCES
from failure import Failure
from file_writes import replace_file, replace_json
from utc_stamp import STAMPED
from records.file_writes import replace_file, replace_json
from records.utc_stamp import STAMPED
CYCLES_PER_CHECK = 20
RAISED = "routing-calls-raised.md"
+2 -2
View File
@@ -20,9 +20,9 @@ from routing_figures.calls import Call, calls, totals
from routing_figures.chunk import Chunk, chunk_figures, ChunkFigures, Reports, Subagent
from routing_figures.state import due
from failure import Failure
import git_repo
from git_cli import git_repo
from test_env import isolated_env
from todo_table import Item
from release_plan.todo_table import Item
from model_routing.ladder import LADDER, Rung
from transcript_archive import outcomes, write
from routing_figures.render import render
+1 -3
View File
@@ -1,9 +1,7 @@
import pathlib
from failure import Failure
import git_repo
from git_cli import git_repo
def guarded_git(directory: str, *args: str) -> str | Failure:
"""What git printed in directory, stripped, run guarded: the hook runs git in a checkout the call has not yet been allowed to touch."""
ran = git_repo.git(*args, cwd=directory, guarded=True)
+2 -2
View File
@@ -1,6 +1,6 @@
"""Whether a simple command is a heavy one, for the `run-heavy` rule: a docker build, or a run of a mutation tool."""
from docker_command import docker_subcommand
from shell_command import launched, tool_name
from command_lines.docker_command import docker_subcommand
from command_lines.shell_command import launched, tool_name
# Each mutation tool, and the words that make its call a mutation run when one of them follows it within two words; where the set is empty, every call is one.
MUTATORS = {"cargo": {"mutants"}, "infection": set(), "mutmut": {"run"}, "stryker": {"run"}}
+2 -2
View File
@@ -38,14 +38,14 @@ import typing
from rule_hook.call import applied, Call, FILE_TOOLS, parsed_call, text
from rule_hook.rules import Breach, check, Checked, command_breaches, file_breaches, rules_help
from git_command import commits
from git_cli.git_command import commits
from failure import Failure
from rule_hook.override_log import Log, log_path, logged, print_overrides, write_override
from rule_hook.repeat_read import read_breaches
from rule_hook.reviewer_report import report_breaches
from rule_hook.reviewer_rung import reviewer_breaches, skill_breaches
from rule_hook.round_cap import round_cap_breaches
from shell_command import simple_commands
from command_lines.shell_command import simple_commands
from rule_hook.todo_check import todo_breaches
+2 -2
View File
@@ -6,10 +6,10 @@ import sys
import typing
from rule_hook.rules import Breach
from git_repo import default_ref
from git_cli.git_repo import default_ref
from rule_hook.git import existing, guarded_git
from failure import Failure
from utc_stamp import utc
from records.utc_stamp import utc
LOG = "rule-overrides.tsv"
+1 -1
View File
@@ -14,7 +14,7 @@ from rule_hook.call import Call, FILE_TOOLS, text
from claude_code.transcript import current_thread, read_transcript
from failure import Failure
from claude_code.entries import parts, tool_call, tool_result, tool_use_id
from shell_command import resolved, simple_commands
from command_lines.shell_command import resolved, simple_commands
# The lines a Read without a limit returns.
READ_LIMIT = 2000
+1 -1
View File
@@ -4,7 +4,7 @@ import pathlib
from rule_hook.rules import Breach
from rule_hook.call import Call
from review_folder import REPORTS
from review_rules.review_folder import REPORTS
# Each agent under agents/, read from the folder, so an agent the routing tables miss is still confined.
AGENT_FILES = frozenset(path.stem for path in (pathlib.Path(__file__).resolve().parents[2] / "agents").glob("*.md"))
+2 -2
View File
@@ -5,11 +5,11 @@ from rule_hook.rules import Breach
from rule_hook.call import Call, text
from claude_code.entries import content
from failure import Failure
import git_repo
from git_cli import git_repo
from rule_hook.git import guarded_git
from model_routing.worker_rungs import handed
from model_routing.ladder import position, review_rung, ReviewKind, Rung
from review_passes import prose, REVIEWERS
from review_rules.review_passes import prose, REVIEWERS
from claude_code.transcript import read_transcript
# The pass each agent under agents/ reviews.
+4 -4
View File
@@ -1,9 +1,9 @@
from rule_hook.rules import Breach
from round_titles import cap, past_cap, round_counts, round_pass
from git_command import CommitCall
from review_rules.round_titles import cap, past_cap, round_counts, round_pass
from git_cli.git_command import CommitCall
from failure import Failure
import git_repo
from review_passes import PASSES
from git_cli import git_repo
from review_rules.review_passes import PASSES
def round_cap_breaches(commit: CommitCall) -> list[Breach]:
+5 -5
View File
@@ -3,13 +3,13 @@ import posixpath
import re
import typing
from round_titles import CAP, lacks_counts, RELEASE_REVIEW_CAP
from git_command import commits
from review_rules.round_titles import CAP, lacks_counts, RELEASE_REVIEW_CAP
from git_cli.git_command import commits
from run_heavy.capped_docker import finds_this_docker
from rule_hook.heavy_command import heavy
from shell_command import launched, Simple
from review_folder import REPORTS
from docker_command import unlimited
from command_lines.shell_command import launched, Simple
from review_rules.review_folder import REPORTS
from command_lines.docker_command import unlimited
RuleName = typing.Literal["action-pin", "commit-one-line", "docker-run-memory", "ignorefile-sorted", "image-pin", "no-ai-attribution", "repeat-read", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check"]
+3 -3
View File
@@ -15,13 +15,13 @@ from rule_hook.repeat_read import Asked, modified, read_breaches, result_lines
from rule_hook.rules import blocks, Breach, check, command_breaches, file_breaches, overrides
from rule_hook.main import breaches_of
from rule_hook.call import Call, parsed_call
from git_command import commit_message, CommitCall, commits
from test_rank_todo import DECISIONS, README, TODO
from git_cli.git_command import commit_message, CommitCall, commits
from release_plan.test_ranking import DECISIONS, README, TODO
from rule_hook.git import guarded_git
from test_env import isolated_env
from rule_hook.override_log import LogLine, parsed_entry, this_chunks
from rule_hook.reviewer_rung import reviewer_breaches, skill_breaches
from shell_command import segments, simple_commands
from command_lines.shell_command import segments, simple_commands
HOOK = pathlib.Path(__file__).resolve().parents[1] / "rule-hook"
# Built from parts, so this file carries no attribution of its own.

Some files were not shown because too many files have changed in this diff Show More