Merge pull request 'State code health as every project's first achieve goal, weighed four times while the comprehension overall is under 7.0, unless a README voids it' (#324) from item-189 into main
This commit was merged in pull request #324.
This commit is contained in:
@@ -15,7 +15,7 @@ Decisions live in `docs/decisions.md`:
|
||||
- review: a fix for a 🔴 or 🟡 reruns the pass that found it and each pass whose trigger names fixes like it; from round 2 a pass reviews only the answers to its last round's findings and any other pass's fix that re-entered it; a fix for a 🟢, a ❓ or a prose finding reruns none
|
||||
- review: the comprehension check records how hard a project is to read and blocks no merge: a paired ruling against the last measured commit where the architecture pass ran, and the four-seat scoring run, once when an item names the floor and twice on one head when a release's items run out
|
||||
- review: a project decision may suspend the comprehension check for the plan items it names
|
||||
- review: a project decision may opt every chunk out of the architect, the product-owner pass or the comprehension check
|
||||
- review: a project decision may opt every chunk out of the architect, the product-owner pass or the comprehension check, and a project opting out of the comprehension check voids code health
|
||||
- review: the principles audit runs on every chunk that changes code, config or tests, and on no other chunk
|
||||
- review: a pass skips only on a precedent: a decision, or a plan item crediting the pass, that the repo held before the chunk began
|
||||
- loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
|
||||
@@ -27,7 +27,7 @@ Decisions live in `docs/decisions.md`:
|
||||
- workflow-bench/: the remote may show the bench cases' names and commit SHAs
|
||||
- settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped
|
||||
- the repo may name bender, bender-infra and ai-sandbox
|
||||
- todo.md: one table of items scored by the formula it states, each README achieve goal weighed by its position, the first heaviest, held to its bar, ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; the table's order is the plan's only order
|
||||
- todo.md: one table of items, scored by the formula it states, held to its bar and ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; each achieve goal weighs by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0 or unmeasured, then README.md's goals; the table's order is the plan's only order
|
||||
- todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan; one below it drafts new items and changes to filed ones for a subagent at or above that rung to apply and score, and removes finished ones
|
||||
- reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to `docs/reading-cost.md` in the next chunk's PR
|
||||
- reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
|
||||
|
||||
@@ -2,6 +2,11 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- Every project now shares one achieve goal, code health: the code is easy to understand and change safely. `CLAUDE.md` → "Shared goal" states it, with its signal and counter-signal. `rank_todo.py` ranks it first among a project's achieve goals. A project's overall is the overall mean of the newest scoring run in `docs/comprehension-history.md`, averaged with every other run on its commit. While that overall is under 7.0, or no run has measured the project, code health weighs four times as much as it does at 7.0 or above. An item's Moves cell names it as in `code health by 6`. A README voids it with `**Void:** code health, since <reason>.` under `## Goals`, and `rank_todo.py` then refuses an item that names it. `larv-review record-scoring` re-ranks `todo.md` after it appends a run, and exits 1 where `rank_todo.py` would, keeping the run. Expect items that make code easier to read to rank higher in every project. On upgrade:
|
||||
1. Move every machine to this release before any of them ranks a plan another machine shares: an older `rank_todo.py` scores it without code health and rejects a `code health` cell.
|
||||
2. Void code health in each project that opts out of the comprehension check, or `rank_todo.py` refuses its plan.
|
||||
3. Run `rank_todo.py` in each project that keeps code health. It re-scores every item, so until then `rank_todo.py --check` fails, and rule-hook holds the project's next `todo.md` commit.
|
||||
4. In each project whose README restates code health as a goal of its own, file an item to drop that goal and point the Moves cells citing it at `code health`. Dropping it renumbers the goals after it, so the same item repoints every Moves cell and decision citing them; `rank_todo.py` cannot tell a cell left pointing at the wrong goal.
|
||||
- `stability-replay <model>` is now `review-replay <pass> <model>`, and replays any pass an agent under `agents/` reviews, such as `review-replay prose claude-opus-5-5`. It now tries every rung below the project's, down to the ladder's lowest. Its runs on the prose and stability passes of Opus 5.5 projects found no rung below the project's that finds every 🔴 and 🟡 the project's rung finds: Sonnet 5.5 at high missed 12 of 27 prose findings and 11 of 20 stability findings. So every pass stays where it runs. A rung a future run finds lowers only its pass, once `REPLAYED` in `bin/model_routing/ladder.py` names it, and only where the chunk's E + I steps no review up and the worker runs no higher than the project's rung; there it may run below the worker's rung.
|
||||
- `chunk-preflight` names the release it finds finished and ready to cut, or to be planned first, wherever todo.md has named that release since the last cut.
|
||||
- Each reviewer under `agents/` now writes its full report to a file that larv-review names in the reviewer's prompt, in a folder per chunk under `~/.local/state/larv-review/`. It returns only its verdict and one line per finding, so a review takes less of the worker's context. The worker reads a finding's full entry before it fixes or answers a 🔴 or 🟡. Each reviewer now holds Write. `rule-hook` refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`; no override waives this rule. Each chunk's folder stays after the merge, so `review-replay` can replay a round that reads an earlier round's report. It replays on a copy of the folder.
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
|
||||
|
||||
- **Until `README.md` has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. Both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count.
|
||||
- **Until `README.md` has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. Both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count; the one exception is code health, which "Shared goal" below states for every project.
|
||||
- **Plan `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, and the human approves it.
|
||||
- **When the next release has no items and no work has landed towards it, plan it as this chunk.** Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
|
||||
- **When the next release has no items left and work has landed towards it, it is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix lands, into that release; never start a later release's items or plan a new one.
|
||||
@@ -20,6 +20,17 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **Open each `todo.md` item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and says nothing about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
|
||||
- **File a security finding the moment it is found.** A security finding — a leaked credential, secret or PII, an auth bypass, an injection — goes under the next release, marked `security`, naming the exposure and the path it reaches. `~/.claude/bin/rank_todo.py` ranks it first in its release, after only the open questions, which wait for me. Never among additive or nice-to-have items, never only in a chunk's summary, and never as a question about where it belongs: file it, say you did, and I will unmark it if I disagree. Fixing it inside an unrelated change is a separate call — say whether it is in the blast radius.
|
||||
|
||||
## Shared goal
|
||||
|
||||
Every project pursues the achieve goal below, ranked above every achieve goal its README states. A project whose code nobody will maintain voids it with one line under `## Goals`, before the numbered goals: `**Void:** code health, since <reason>.` So does a project that opts out of the comprehension check, since the goal then has no signal. An item's Moves cell names it as in `code health by 6`, and `rank_todo.py --help` says how much it weighs.
|
||||
|
||||
**Achieve:** Code health: the code is easy to understand and change safely.
|
||||
- Signal: the comprehension panel's overall score rises, always. Under 7.0 it is very important.
|
||||
- Counter-signal: defects keep reappearing in functionality that already shipped, or reviewers raise blockers because the implementer misunderstood the current system.
|
||||
- Why: a score that rises while changes still misread the code measures the wrong thing.
|
||||
|
||||
Fewer items shipped per release is a price this goal accepts, not a counter-signal.
|
||||
|
||||
## Prose
|
||||
|
||||
Everything written — chat, commit messages, comments, docs, code — is in **English**. Prose meets four priorities, in this order. When two pull against each other, the higher one wins.
|
||||
@@ -100,7 +111,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
|
||||
- **judge** — the headless claude that reads a worker's transcript each cycle and decides whether to interrupt and whether the chunk is finished.
|
||||
- **pass** — one kind of review a chunk may take, run in rounds by its reviewers until clean; `larv-review` §3 lists them.
|
||||
- **plan** — `todo.md`.
|
||||
- **premises** — the goals and audience under `## Goals` and `## Audience` in the project's `README.md`.
|
||||
- **premises** — the goals and audience under `## Goals` and `## Audience` in the project's `README.md`, with code health ("Shared goal") first among the goals unless the README voids it.
|
||||
- **project's rung** — the cheapest rung on loop-claude's routing ladder of the project's model, which is the model loop-claude's prompt names as the project's, or else your own.
|
||||
- **release** — a semver version the human cuts.
|
||||
- **reviewer** — a reporter of findings: an agent under `~/.claude/agents/`, `/security-review` or a forge's auto-reviewer.
|
||||
|
||||
@@ -110,7 +110,7 @@ pytest_add_cli_args=-k
|
||||
|
||||
Then, in the copy: `uvx --with pytest 'mutmut>=3,<4' run && uvx --with pytest 'mutmut>=3,<4' results`, and `uvx --with pytest 'mutmut>=3,<4' show <mutant>` to see a mutant's change. The config keys are mutmut 3's.
|
||||
|
||||
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests; `rank_todo.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge, and `loop_claude` runs `chunk-preflight` as a process of its own. `judge_replay` and `review_replay` share `rung_replay/`: the rung search, the argument reader, the candidate rungs and the exits. `rung_replay/` reads `loop_claude`'s retry count and models file. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
|
||||
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests; `rank_todo.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `larv_review` imports `rank_todo.py`'s ranking, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge, and `loop_claude` runs `chunk-preflight` as a process of its own. `judge_replay` and `review_replay` share `rung_replay/`: the rung search, the argument reader, the candidate rungs and the exits. `rung_replay/` reads `loop_claude`'s retry count and models file. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
|
||||
|
||||
## Tracking a new file
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: "Use this agent for larv-review's overrides pass."
|
||||
tools: Read, Grep, Glob, Write
|
||||
---
|
||||
|
||||
You rule on each override of a rule `~/.claude/bin/rule-hook` enforces. The prompt gives you the lines `rule-hook overrides` printed, each with its rule and reason, and the branch diff. Read each rule and its stated exceptions in `~/.claude/bin/rule_hook/rules.py` → `RULES`, how an override is written and logged in the docstring of `~/.claude/bin/rule_hook/main.py`, and the project's `README.md` → "Goals" and "Audience".
|
||||
You rule on each override of a rule `~/.claude/bin/rule-hook` enforces. The prompt gives you the lines `rule-hook overrides` printed, each with its rule and reason, and the branch diff. Read each rule and its stated exceptions in `~/.claude/bin/rule_hook/rules.py` → `RULES`, how an override is written and logged in the docstring of `~/.claude/bin/rule_hook/main.py`, and the project's `README.md` → "Goals" and "Audience", with code health (`~/.claude/CLAUDE.md` → "Shared goal") among the goals unless the README voids it.
|
||||
|
||||
For each override:
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: "Use this agent for larv-review's principles pass: one yardstick ch
|
||||
tools: Read, Grep, Glob, Write
|
||||
---
|
||||
|
||||
You check one yardstick against the whole project: every principle in the file you are handed, or every goal under the project's `README.md` → `## Goals`.
|
||||
You check one yardstick against the whole project: every principle in the file you are handed, or every goal under the project's `README.md` → `## Goals`, with code health (`~/.claude/CLAUDE.md` → "Shared goal") unless the README voids it.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. Read the yardstick, `README.md`, `docs/decisions.md` and `todo.md` first, then all of the project's code, config, tests and CI.
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ Before anything else, **read the shared principles** at `~/.claude/principles/`.
|
||||
|
||||
## Your Output Format
|
||||
|
||||
Report only a defect a persona hits, a requirement of the plan or the README's goals that the change breaks, or a breach of a technical principle. Friction that is none of these is not a finding.
|
||||
Report only a defect a persona hits, a requirement of the plan, the README's goals or code health (`~/.claude/CLAUDE.md` → "Shared goal", unless the README voids it) that the change breaks, or a breach of a technical principle. Friction that is none of these is not a finding.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict:
|
||||
|
||||
|
||||
@@ -129,7 +129,7 @@ Every PR gets at least this sweep.
|
||||
|
||||
## Output Format
|
||||
|
||||
Report only a defect, a requirement of the plan or the README's goals that the change breaks, a breach of a technical principle, and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
Report only a defect, a requirement of the plan, the README's goals or code health (`~/.claude/CLAUDE.md` → "Shared goal", unless the README voids it) that the change breaks, a breach of a technical principle, and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict, a short **Coverage & Verification** block: what you ran (tests, static analysis, mutation — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then the findings, most severe first, each with:
|
||||
- **Location**: File and line/function
|
||||
|
||||
@@ -17,7 +17,7 @@ from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
|
||||
from chunk_preflight.facts import open_pulls, render
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
README = "# Project\n\n## Goals\n\n1. **Achieve:** Work.\n\n## Audience\n\nMe.\n"
|
||||
README = "# Project\n\n## Goals\n\n**Void:** code health, since the plan's scores weigh goal 1 alone.\n\n1. **Achieve:** Work.\n\n## Audience\n\nMe.\n"
|
||||
# Item 3 is the next release's first item that does not wait; 7 waits only on 3, 5 is a question, 8 waits on 5, 9 is in a later release.
|
||||
TODO = """# todo
|
||||
|
||||
|
||||
@@ -9,6 +9,8 @@ from utc_stamp import utc
|
||||
ARCHITECT = "Inherited architect"
|
||||
DECIDED_BY = "decided by"
|
||||
DIMENSIONS = ("Navigation", "Locality", "Shape", "Self-sufficiency", "Overall")
|
||||
# The comprehension floor, which every dimension and the overall should reach; docs/decisions.md → "comprehension floor" says it blocks nothing.
|
||||
FLOOR = decimal.Decimal("7.0")
|
||||
HARDEST_FIRST = "hardest first"
|
||||
HEADING = re.compile(r"^([^,]+), (.+) at ([0-9a-f]{7,40})(?:, against ([0-9a-f]{7,40}))?$")
|
||||
HISTORY = "docs/comprehension-history.md"
|
||||
@@ -104,15 +106,61 @@ def entries(history: str) -> list[Entry]:
|
||||
|
||||
|
||||
def latest_places(history: str) -> str | None:
|
||||
"""The places seats found hard from the oldest entry on the commit of the newest entry, by time, that is a scoring run or holds scoring seats' places: in it and each later entry, each ruled place opening with a dimension its seat's vote counted as worse, and every scoring seat's place. Each entry's places come under its heading, oldest first; with no such entry, it starts at the oldest entry. None when no place counts."""
|
||||
found = sorted(entries(history), key=lambda entry: entry.time)
|
||||
scored = [index for index, entry in enumerate(found) if not entry.paired or entry.scored_places]
|
||||
newest_commit = found[scored[-1]].commit if scored else None
|
||||
start = next((index for index in scored if found[index].commit == newest_commit), 0)
|
||||
"""The places seats found hard since the newest scored commit, under each entry's heading, oldest first; None when no place counts.
|
||||
|
||||
They start at the first of newest_scored's entries, so a rerun of one head adds to the run before it. Where no entry counts as scoring the project, they start at the oldest entry. From there, each entry gives every scoring seat's place, and each ruled place opening with a dimension its seat voted worse."""
|
||||
found = by_time(entries(history))
|
||||
newest = newest_scored(found)
|
||||
start = found.index(newest[0]) if newest else 0
|
||||
parts = [placed(entry, worse_places(entry) + labelled_bullets(entry.body, SCORED_PLACES)) for entry in found[start:]]
|
||||
return "\n".join(part for part in parts if part) or None
|
||||
|
||||
|
||||
def latest_overall(history: str) -> decimal.Decimal | Failure | None:
|
||||
"""The mean of the overall means of newest_scored's entries, since a rerun of one head measures it again; None where no entry counts as scoring the project."""
|
||||
overalls = []
|
||||
for entry in newest_scored(by_time(entries(history))):
|
||||
overall = run_overall(entry)
|
||||
if isinstance(overall, Failure):
|
||||
return overall
|
||||
overalls.append(overall)
|
||||
return sum(overalls, decimal.Decimal(0)) / len(overalls) if overalls else None
|
||||
|
||||
|
||||
def newest_scored(found: list[Entry]) -> list[Entry]:
|
||||
"""In found's order, the entries that count as scoring the project on the newest scored commit, the commit of the last such entry; empty where none counts. A commit matches by prefix, since a heading may write it at any length from 7 characters."""
|
||||
scoring = [entry for entry in found if scored(entry)]
|
||||
return [entry for entry in scoring if entry.commit.startswith(scoring[-1].commit) or scoring[-1].commit.startswith(entry.commit)] if scoring else []
|
||||
|
||||
|
||||
def run_overall(run: Entry) -> decimal.Decimal | Failure:
|
||||
"""The overall cell of the Mean row of an entry that counts as scoring the project."""
|
||||
try:
|
||||
overall = decimal.Decimal(overall_cells(run).get(MEAN, ""))
|
||||
except decimal.InvalidOperation:
|
||||
overall = None
|
||||
return overall if overall is not None and overall.is_finite() else Failure(f"{HISTORY}'s scoring run {run.heading} has no Mean row ending in its overall, which sets code health's weight")
|
||||
|
||||
|
||||
def overall_cells(entry: Entry) -> dict[str, str]:
|
||||
"""Each table row's last non-empty cell, by its first cell: a seat's overall vote in a ruling table, whether it has five votes or the older single `Vote`, or its overall score, or the Mean row's, in a scoring table."""
|
||||
return {name: cells[-1] for name, cells in table_rows(entry.body).items() if cells and cells[-1]}
|
||||
|
||||
|
||||
def scoring_runs(found: list[Entry]) -> list[Entry]:
|
||||
"""The scoring runs among the entries, oldest first. Unlike scored, it leaves out a ruling from before PR #255 that holds scoring seats' places: there overall_cells reads each voting seat's vote, not its score."""
|
||||
return [entry for entry in by_time(found) if not entry.paired]
|
||||
|
||||
|
||||
def by_time(found: list[Entry]) -> list[Entry]:
|
||||
return sorted(found, key=lambda entry: entry.time)
|
||||
|
||||
|
||||
def scored(entry: Entry) -> bool:
|
||||
"""Whether the entry counts as scoring the project: a scoring run, or a ruling from before PR #255 that holds scoring seats' places."""
|
||||
return not entry.paired or bool(entry.scored_places)
|
||||
|
||||
|
||||
def worse_places(entry: Entry) -> list[tuple[str, list[str]]]:
|
||||
"""Under each of a ruling's seat labels, the bullets that open with a dimension that seat's vote counted as worse; Overall counts as one."""
|
||||
worse = worse_votes(entry.body)
|
||||
|
||||
@@ -1,17 +1,12 @@
|
||||
import decimal
|
||||
|
||||
from comprehension_history import counted_vote, entries, Entry, table_rows
|
||||
from comprehension_history import counted_vote, entries, Entry, overall_cells, scoring_runs
|
||||
from larv_review.seats import FIRST_SEATS
|
||||
|
||||
# Matches score-outcomes, which waits for 10 finished chunks before it shows a median.
|
||||
MIN_PAIRS = 10
|
||||
|
||||
|
||||
def overall_cells(entry: Entry) -> dict[str, str]:
|
||||
"""Each table row's last non-empty cell, by its first cell: a seat's overall vote in a ruling table, whether it has five votes or the older single `Vote`, or its overall score in a scoring table."""
|
||||
return {name: cells[-1] for name, cells in table_rows(entry.body).items() if cells and cells[-1]}
|
||||
|
||||
|
||||
def ruling_agreement(found: list[Entry]) -> list[bool]:
|
||||
"""For each paired ruling that holds both of the first seats' overall votes, whether they counted alike."""
|
||||
first, second = FIRST_SEATS
|
||||
@@ -23,7 +18,7 @@ def run_agreement(found: list[Entry]) -> list[bool]:
|
||||
"""For each commit scored at least twice, whether the first two seats' overall scores moved the same way, up, down or not at all, from its first run to its second. Both runs read one tree, so the pair is the ruling those seats would make from absolute scores on code that did not change."""
|
||||
first, second = FIRST_SEATS
|
||||
runs: dict[str, list[dict[str, decimal.Decimal]]] = {}
|
||||
for entry in sorted((each for each in found if not each.paired), key=lambda each: each.time):
|
||||
for entry in scoring_runs(found):
|
||||
cells = overall_cells(entry)
|
||||
if first in cells and second in cells:
|
||||
runs.setdefault(entry.commit, []).append({first: decimal.Decimal(cells[first]), second: decimal.Decimal(cells[second])})
|
||||
|
||||
@@ -72,7 +72,9 @@ prints `Ruling:` and appends the ruling.
|
||||
record-scoring takes the scores file of a run needs-scoring-run calls, whose first line names no
|
||||
`, against`, and the same item IDs, and exits 1 when they call no run. It appends the seats' scores
|
||||
and their means, rounded half up to two decimals, prints the means and, when a mean is under the
|
||||
floor of {floor}, a line opening `Floor:` naming each one.
|
||||
floor of {floor}, a line opening `Floor:` naming each one. Then it ranks the checkout's todo.md as
|
||||
rank_todo.py does, since the overall sets the weight of code health, the goal every project shares,
|
||||
and exits 1 where rank_todo.py would, with the run recorded.
|
||||
|
||||
places prints the places seats found hard since the newest scored commit: the places of each scoring
|
||||
run on it, and,
|
||||
@@ -91,9 +93,10 @@ time and the seats file's first line. Each commit that line names must be in the
|
||||
when the history already holds an entry on what that line reads.
|
||||
|
||||
Exit 1, saying why, on unknown arguments, an unknown item ID, a seats file it cannot read or that
|
||||
breaks the shape above, or when git cannot start, finds no checkout or no default branch, cannot
|
||||
fetch origin for ruling-base, needs-scoring-run or record-scoring, or cannot read or write the
|
||||
history, todo.md or the review folder.
|
||||
breaks the shape above, a todo.md that fails rank_todo.py after record-scoring records a run, or
|
||||
when git cannot start, finds no checkout or no default branch, cannot fetch origin for ruling-base,
|
||||
needs-scoring-run or record-scoring, or cannot read or write the history, todo.md or the review
|
||||
folder.
|
||||
"""
|
||||
import pathlib
|
||||
import re
|
||||
@@ -103,7 +106,7 @@ import typing
|
||||
from round_titles import CAP, PASSES, round_counts
|
||||
from git_repo import default_branch, git, top
|
||||
from failure import Failure
|
||||
from larv_review.scoring import FLOOR
|
||||
from comprehension_history import FLOOR
|
||||
from larv_review.git import history_changes
|
||||
from larv_review.ruling_base import measured_commit
|
||||
from larv_review.agreement import MIN_PAIRS
|
||||
|
||||
@@ -2,12 +2,13 @@ import pathlib
|
||||
import time
|
||||
|
||||
from larv_review.agreement import agreement_report
|
||||
from comprehension_history import appended, DIMENSIONS, heading, Heading, HISTORY, latest_places, recorded, ruling_entry, scoring_entry, ScoringRun, vote_text
|
||||
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 larv_review.ruling import counted, overall, ruling, split, votes
|
||||
from failure import Failure
|
||||
from larv_review.scoring import FLOOR, means, under_floor
|
||||
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 larv_review.seats import scores, seats_file, SeatsFile
|
||||
|
||||
@@ -47,7 +48,23 @@ def record_scoring(default: str, scores_file: pathlib.Path, ids: list[int]) -> F
|
||||
print(f"Means: {', '.join(f'{name} {value}' for name, value in zip(DIMENSIONS, scoring.means))}.")
|
||||
if under := under_floor(scoring.means):
|
||||
print(f"Floor: {', '.join(under)} under the floor of {FLOOR}.")
|
||||
return append(given.read, scoring_entry(named.title, scoring))
|
||||
if unrecorded := append(given.read, scoring_entry(named.title, scoring)):
|
||||
return unrecorded
|
||||
return rerank()
|
||||
|
||||
|
||||
def rerank() -> Failure | None:
|
||||
"""Rank the checkout's todo.md again as rank_todo.py does, since the overall sets code health's weight, and fail where rank_todo.py would. The run stays recorded whatever happens, so those failures say to settle todo.md and run rank_todo.py on it, not to record the run again."""
|
||||
checkout = top()
|
||||
if isinstance(checkout, Failure):
|
||||
return checkout
|
||||
todo = pathlib.Path(checkout, "todo.md")
|
||||
ranked = rank_todo.rank_file(todo)
|
||||
if isinstance(ranked, Failure):
|
||||
return Failure(f"recorded the run, but rank_todo.py cannot rank {todo}: {ranked.reason}. Fix what that names, then run rank_todo.py on {todo}, not record-scoring again")
|
||||
if ranked.under_bar:
|
||||
return Failure(f"recorded the run and ranked {todo}, but the lines above name items now under the bar. Settle each as its line says, then run rank_todo.py on {todo}, not record-scoring again")
|
||||
return None
|
||||
|
||||
|
||||
def scored_seats(given: SeatsFile) -> ScoringRun | Failure:
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
import decimal
|
||||
|
||||
from comprehension_history import DIMENSIONS
|
||||
|
||||
FLOOR = decimal.Decimal("7.0")
|
||||
from comprehension_history import DIMENSIONS, FLOOR
|
||||
|
||||
|
||||
def means(lines: list[list[str]]) -> list[decimal.Decimal]:
|
||||
|
||||
@@ -161,6 +161,8 @@ class History(unittest.TestCase):
|
||||
first, rerun, other = (run.format(time=time, pr=pr, commit=commit, line=line) for time, pr, commit, line in (("2026-10-08T12:00:00Z", "PR #1", "aaaaaaa", 1), ("2026-10-08T13:00:00Z", "PR #1 rerun", "aaaaaaa", 2), ("2026-10-09T12:00:00Z", "PR #2", "bbbbbbb", 3)))
|
||||
self.assertEqual(latest_places(appended(appended("", first), rerun)), first + "\n" + rerun)
|
||||
self.assertEqual(latest_places(appended(appended(appended("", first), rerun), other)), other)
|
||||
in_full = rerun.replace("aaaaaaa", "aaaaaaa" + "0" * 33)
|
||||
self.assertEqual(latest_places(appended(appended("", first), in_full)), first + "\n" + in_full)
|
||||
|
||||
|
||||
def scored(time: str, pr: str, commit: str, mid: str, architect: str) -> str:
|
||||
@@ -438,6 +440,7 @@ class LarvReviewTool(unittest.TestCase):
|
||||
uncalled = self.run_tool("record-scoring", self.seats_file(f"PR #2 at {self.start}\n" + seats))
|
||||
self.assertEqual(uncalled.returncode, 1)
|
||||
self.assertIn("no plan item or release calls this scoring run", uncalled.stderr)
|
||||
self.plan()
|
||||
ran = self.run_tool("record-scoring", self.seats_file(f"PR #2 at {self.start}\n" + seats), "1")
|
||||
self.assertEqual(ran.returncode, 0, ran.stderr)
|
||||
self.assertIn("\nFloor: Locality 6.50, Self-sufficiency 6.50 under the floor of 7.0.\n", ran.stdout)
|
||||
@@ -447,6 +450,54 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.assertIn("Inherited architect, would restructure first:", text)
|
||||
self.assertEqual(entries(text)[0].scored_places, [Place("bin/a.py", "f")] * 4)
|
||||
|
||||
def plan(self, readme="# P\n\n## Goals\n\n1. **Achieve:** A.\n", bar="0.1"):
|
||||
"""Commit and push the README.md and a todo.md whose item 1, alone in release 0.1.0, moves code health, each item scored as before any scoring run."""
|
||||
header = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
|
||||
# Before any scoring run code health weighs four times its weight at an overall of 7.0: 4 / 1.97 against goal 1's 0.97 / 1.97.
|
||||
rows = "| 1 | 0.1.0 | | | **Read easier.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 101.5 |\n| 2 | 0.2.0 | | | **Do A.** | 1 | 1 | 1 | 1 | 1 | 1 by 3 | 73.9 |\n"
|
||||
self.commit("Plan", {"README.md": readme, "todo.md": f"# todo\n\n## Scoring\n\n`Score = 100 * V / 2**S`\n\n`Bar = {bar}`\n\n`Next ID = 3`\n\n## Items\n\n" + header + rows})
|
||||
self.git("push", "-q", "origin", "HEAD:main")
|
||||
|
||||
def record_sevens(self):
|
||||
"""Run record-scoring for item 1 on a scores file in which every seat scores 7 throughout."""
|
||||
line = "Navigation 7, Locality 7, Shape 7, Self-sufficiency 7, Overall 7"
|
||||
seats = "".join(f"\n{seat}: {line}\n" for seat in ("Junior A", "Mid A", "Maintainability senior", "Inherited architect"))
|
||||
return self.run_tool("record-scoring", self.seats_file(f"PR #2 at {self.start}\n" + seats), "1")
|
||||
|
||||
def test_reports_a_plan_it_cannot_read_yet_keeps_the_run(self):
|
||||
# This checkout has no README.md beside its todo.md.
|
||||
ran = self.record_sevens()
|
||||
self.assertEqual(ran.returncode, 1)
|
||||
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: {self.checkout / 'README.md'}: not found", ran.stderr)
|
||||
self.assertIn("not record-scoring again", ran.stderr)
|
||||
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
|
||||
|
||||
def test_reports_a_plan_it_reads_but_cannot_rank_yet_keeps_the_run(self):
|
||||
self.plan(readme="# P\n\n## Goals\n\n**Void:** code health, since it is a probe.\n\n1. **Achieve:** A.\n")
|
||||
ran = self.record_sevens()
|
||||
self.assertEqual(ran.returncode, 1)
|
||||
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: item 1 names code health, which README.md voids", ran.stderr)
|
||||
self.assertIn("not record-scoring again", ran.stderr)
|
||||
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
|
||||
|
||||
def test_reranks_todo_md_by_the_overall_it_records(self):
|
||||
self.plan()
|
||||
ran = self.record_sevens()
|
||||
self.assertEqual(ran.returncode, 0, ran.stderr)
|
||||
self.assertIn("| code health by 1 | 25.4 |", (self.checkout / "todo.md").read_text())
|
||||
|
||||
def test_fails_once_its_re_rank_leaves_an_item_under_the_bar_yet_keeps_the_run(self):
|
||||
self.plan(bar="30")
|
||||
ran = self.record_sevens()
|
||||
self.assertEqual(ran.returncode, 1)
|
||||
todo = self.checkout / "todo.md"
|
||||
# At an overall of 7.0 item 1 falls from 101.5 to 25.4.
|
||||
self.assertIn(f"{todo}: item 1 scores 25.4, under the bar 30; delete it, or mark it with a reason the bar does not apply\n", ran.stderr)
|
||||
self.assertIn("recorded the run", ran.stderr)
|
||||
self.assertIn("not record-scoring again", ran.stderr)
|
||||
self.assertIn("| code health by 1 | 25.4 |", todo.read_text())
|
||||
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
|
||||
|
||||
def test_prints_the_places_seats_found_hard_since_the_newest_scoring_run(self):
|
||||
self.assertEqual(self.run_tool("places").stdout, "Seats found no places hard.\n")
|
||||
self.commit("Record a scoring run", {"docs/comprehension-history.md": appended("", SCORING + "\nJunior A, hardest first:\n\n- `bin/b.py:4` `h`: long\n")})
|
||||
|
||||
@@ -14,11 +14,14 @@ ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could
|
||||
REVIEWS: tuple[tuple[str, ReviewKind], ...] = (*((f"each {agent}", kind) for kind, agent in REVIEWERS.items()), ("each comprehension seat", "seat"), ("the security pass's subagent", "security"))
|
||||
|
||||
|
||||
AFTER_CODE_HEALTH = 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless README.md voids it'
|
||||
|
||||
|
||||
def fresh(task: str, premises: str, route: Route, anchor: Rung | None, facts: str) -> str:
|
||||
"""A chunk's first prompt; facts is preflight_facts' or preflight_failed's text."""
|
||||
escalated = f"{escalation(route, anchor)}{reruns(route, anchor)}".lstrip()
|
||||
routed = f"{routed_by(route, anchor)}{recount(route)}\n\n" if route.item else (f"{escalated}\n\n" if escalated else "")
|
||||
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one.\n\n{routed}{facts}\n\nThe chunk's todo.md items, or else the task above, set its scope. The goals below choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n{premises}"
|
||||
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one.\n\n{routed}{facts}\n\nThe chunk's todo.md items, or else the task above, set its scope. The goals below, {AFTER_CODE_HEALTH}, choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n{premises}"
|
||||
|
||||
|
||||
def routed_by(route: Route, anchor: Rung | None) -> str:
|
||||
|
||||
@@ -4,10 +4,11 @@ usage: loop-claude <task>
|
||||
|
||||
Run it anywhere inside a project checkout whose README.md has ## Goals and ## Audience, the
|
||||
premises; the task runs at the checkout root. Each cycle a worker runs the task. A chunk's first
|
||||
worker prompt also quotes the premises, which choose between ways to deliver the chunk's todo.md
|
||||
items, or else the task, and never widen them. A judge then reads the transcript's end, the
|
||||
premises, and the records: the project's AGENTS.md and docs/decisions.md, and the human's
|
||||
~/.claude/CLAUDE.md, ~/.claude/rules/*.md and
|
||||
worker prompt also quotes the premises. They, with code health
|
||||
(~/.claude/CLAUDE.md → "Shared goal") ranked first unless README.md voids it, choose between ways
|
||||
to deliver the chunk's todo.md items, or else the task, and never widen them. A judge then reads
|
||||
the transcript's end, the premises, and the records: the project's AGENTS.md and docs/decisions.md,
|
||||
and the human's ~/.claude/CLAUDE.md, ~/.claude/rules/*.md and
|
||||
~/.claude/skills/larv-review/standards/*.md, where they exist. It rules whether the chunk, the work
|
||||
of one PR, is finished. A chunk stays unfinished until each answer the human typed in it that a
|
||||
later chunk could need is recorded: the premises or the records hold it, or the transcript shows the worker
|
||||
|
||||
@@ -371,7 +371,7 @@ class Cycles(unittest.TestCase):
|
||||
self.assertIsNone(argument(workers[1], "--name"))
|
||||
self.assertEqual(argument(workers[2], "--session-id"), session)
|
||||
self.assertTrue(argument(workers[0], "-p").startswith(f"{TASK}\n\nContinue any open draft PR"))
|
||||
self.assertTrue(argument(workers[0], "-p").endswith("The chunk's todo.md items, or else the task above, set its scope. The goals below choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n## Goals\n1. Work.\n\n## Audience\nMe."))
|
||||
self.assertTrue(argument(workers[0], "-p").endswith("The chunk's todo.md items, or else the task above, set its scope. The goals below, " 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless README.md voids it' ", choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n## Goals\n1. Work.\n\n## Audience\nMe."))
|
||||
self.assertIn("main or master", argument(workers[0], "-p"))
|
||||
self.assertNotIn(TASK, argument(workers[1], "-p"))
|
||||
self.assertIn("Even then, it is finished only once every answer the human typed in it", argument(workers[1], "-p"))
|
||||
|
||||
+107
-50
@@ -1,15 +1,15 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Score todo.md's items by the formula it states, weighing each achieve goal by its position in README.md, and hold them to its bar.
|
||||
"""Score todo.md's items by the formula it states, weighing code health first and then README.md's achieve goals by their position, and hold them to its bar.
|
||||
|
||||
usage: rank_todo.py [--check] [todo.md]
|
||||
|
||||
Reads todo.md (default: ./todo.md), the README.md beside it, and docs/decisions.md when there is
|
||||
one. 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.
|
||||
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:
|
||||
|
||||
@@ -37,11 +37,17 @@ A valid todo.md; ## Details and each item's detail are optional:
|
||||
|
||||
- The formula holds numbers, + - * / ** and parentheses over L, E, I, R, S and V.
|
||||
- V sums, over the goals in an item's Moves cell, each goal's weight times how far the item moves it.
|
||||
README.md marks each goal **Maintain:** or **Achieve:**. The achieve goals, in reading order and a
|
||||
sub-goal such as 1.1 included, each weigh 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. Only an item marked defect may name a maintain goal, the one it restores, which weighs as
|
||||
the heaviest achieve goal.
|
||||
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
|
||||
@@ -71,24 +77,33 @@ A valid todo.md; ## Details and each item's detail are optional:
|
||||
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, an item that is not exempt scoring under the bar, or
|
||||
--check finding the file unranked.
|
||||
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 math
|
||||
import pathlib
|
||||
import re
|
||||
import sys
|
||||
import typing
|
||||
|
||||
from todo_table import BLOCKED_BY, cells, DETAILS, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, Shape, SHAPE, shape_of, Table, table_rows, version
|
||||
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, version
|
||||
from failure import Failure
|
||||
from comprehension_history import FLOOR, HISTORY, latest_overall
|
||||
from markdown_text import listed, sections
|
||||
from file_writes import replace_file
|
||||
|
||||
# What each achieve goal weighs of the one above it; docs/decisions.md records the choice.
|
||||
GOAL_STEP = 0.97
|
||||
# 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)
|
||||
@@ -106,9 +121,9 @@ class Scoring:
|
||||
formula: ast.Expression
|
||||
bar: float
|
||||
next_id: int
|
||||
# README.md's goals in reading order, each with its mark.
|
||||
# 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 every goal, at the weight todo.md states; else each goal goal_weights weighs.
|
||||
# The weight of each goal an item may name: in OLD_SHAPE each of README.md's goals, at the weight todo.md states; else each goal goal_weights weighs.
|
||||
weights: dict[str, float]
|
||||
|
||||
|
||||
@@ -116,7 +131,7 @@ class Scoring:
|
||||
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 with no achieve goal, and each dropped blocker ID, since a mistyped ID drops the same way.
|
||||
# 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]
|
||||
|
||||
|
||||
@@ -133,19 +148,25 @@ def main(argv: list[str]) -> int:
|
||||
for line in failures:
|
||||
print(line, file=sys.stderr)
|
||||
return 1 if failures else 0
|
||||
texts = read_all(todo)
|
||||
if isinstance(texts, Failure):
|
||||
return fail(texts)
|
||||
ranked = rank(*texts)
|
||||
ranked = rank_file(todo)
|
||||
if isinstance(ranked, Failure):
|
||||
return fail(ranked)
|
||||
if ranked.text != texts[0]:
|
||||
unwritten = write(todo, ranked.text)
|
||||
if unwritten:
|
||||
return fail(unwritten)
|
||||
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 1 if ranked.under_bar else 0
|
||||
return ranked
|
||||
|
||||
|
||||
def check_failures(todo: pathlib.Path) -> list[str]:
|
||||
@@ -172,10 +193,10 @@ def parse_args(argv: list[str]) -> tuple[bool, pathlib.Path] | Failure:
|
||||
return "--check" in argv, pathlib.Path(paths[0] if paths else "todo.md")
|
||||
|
||||
|
||||
def read_all(todo: pathlib.Path) -> tuple[str, str, str] | Failure:
|
||||
"""todo.md, the README.md beside it, and its docs/decisions.md, empty when there is none."""
|
||||
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)):
|
||||
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:
|
||||
@@ -186,7 +207,7 @@ def read_all(todo: pathlib.Path) -> tuple[str, str, str] | Failure:
|
||||
return Failure(f"{path}: {failure.strerror}")
|
||||
except UnicodeDecodeError:
|
||||
return Failure(f"{path}: not UTF-8")
|
||||
return texts[0], texts[1], texts[2]
|
||||
return texts[0], texts[1], texts[2], texts[3]
|
||||
|
||||
|
||||
def write(path: pathlib.Path, text: str) -> Failure | None:
|
||||
@@ -194,13 +215,13 @@ def write(path: pathlib.Path, text: str) -> Failure | None:
|
||||
return Failure(f"{path}: {unwritten.reason}") if unwritten else None
|
||||
|
||||
|
||||
def rank(text: str, readme: str, decisions: str) -> Ranked | Failure:
|
||||
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, shape)
|
||||
scoring = read_scoring(text, lines, readme, decisions, history, shape)
|
||||
if isinstance(scoring, Failure):
|
||||
return scoring
|
||||
items = read_items(table, scoring)
|
||||
@@ -240,7 +261,7 @@ def notes(items: list[Item], scoring: Scoring) -> list[str]:
|
||||
if scoring.shape is OLD_SHAPE:
|
||||
return [RESHAPE] + dropped
|
||||
# Printed so the under-bar lines it causes do not read as items of low value.
|
||||
unweighed = [] if any(scoring.weights.values()) else ["README.md marks no goal **Achieve:**, so every item scores V 0"]
|
||||
unweighed = [] if any(scoring.weights.values()) else ["README.md voids code health and marks no goal **Achieve:**, so every item scores V 0"]
|
||||
return unweighed + dropped
|
||||
|
||||
|
||||
@@ -272,8 +293,8 @@ def under_the_bar(item: Item, value: float, bar: float, items: list[Item]) -> st
|
||||
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, shape: Shape) -> Scoring | Failure:
|
||||
goals = readme_goals(readme)
|
||||
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))
|
||||
@@ -285,18 +306,41 @@ def read_scoring(text: str, lines: list[str], readme: str, shape: Shape) -> Scor
|
||||
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")
|
||||
numbers = [number for number, _ in goals]
|
||||
if shape is OLD_SHAPE:
|
||||
weights = parse_weights(lines, numbers)
|
||||
elif WEIGHTS_HEADER in lines:
|
||||
weights = Failure(f"todo.md holds a goal weights table beside a {MOVES} column; drop the table, since rank_todo.py weighs each achieve goal by its position in README.md")
|
||||
else:
|
||||
weights = goal_weights(goals)
|
||||
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:
|
||||
@@ -432,13 +476,15 @@ def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
|
||||
return goals
|
||||
|
||||
|
||||
def goal_weights(goals: list[tuple[str, Mark]]) -> dict[str, float] | Failure:
|
||||
"""Each achieve goal's weight: the one ranked k of n in reading order weighs GOAL_STEP ** (k - 1) / (1 + GOAL_STEP + ... + GOAL_STEP ** (n - 1)), so the weights sum to 1. 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 README.md marks no goal **Achieve:**, so every item scores V 0 and only an exempt one passes the bar."""
|
||||
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"}
|
||||
|
||||
@@ -562,20 +608,31 @@ def parse_weights(lines: list[str], goals: list[str]) -> dict[str, float] | Fail
|
||||
|
||||
|
||||
def parse_item(row: str, scoring: Scoring, table: Table) -> Item | Failure:
|
||||
"""The row as an item, 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:
|
||||
if 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")
|
||||
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")
|
||||
# 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"])})
|
||||
return None
|
||||
|
||||
|
||||
def render_item(item: Item, value: float, shape: Shape, columns: tuple[str, ...]) -> str:
|
||||
|
||||
+140
-19
@@ -13,7 +13,10 @@ import rank_todo
|
||||
from repo_checks.test_python_floor import ROOT
|
||||
import todo_table
|
||||
|
||||
README = "# P\n\n## Goals\n\n1. **Achieve:** Fast.\n2. **Maintain:** Correct.\n 1. **Achieve:** Tested.\n\n## Audience\n\nMe.\n"
|
||||
# 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"
|
||||
|
||||
README = "# P\n\n## Goals\n\n" + VOID + "1. **Achieve:** Fast.\n2. **Maintain:** Correct.\n 1. **Achieve:** Tested.\n\n## Audience\n\nMe.\n"
|
||||
|
||||
DECISIONS = "## A choice\n\nStands until `todo.md` item 5 ends it.\n"
|
||||
|
||||
@@ -96,7 +99,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 rank_todo.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()
|
||||
@@ -117,19 +120,20 @@ 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)).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 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})
|
||||
|
||||
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).values())
|
||||
weights = list(rank_todo.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()))
|
||||
|
||||
def test_scores_an_item_by_the_weights_of_the_goals_it_moves(self):
|
||||
readme = "## Goals\n\n1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
|
||||
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, 2 by 3").replace("| 2.1 by 1 |", "| 1 by 1 |")
|
||||
self.assertIn("| **Make it fast, `a \\| b`.** | 2 | 1 | 2 | 3 | 7 | 1.2 by 2, 2 by 3 | 1.3 |", self.ranked(todo, readme).text)
|
||||
|
||||
@@ -180,7 +184,7 @@ class Rank(unittest.TestCase):
|
||||
self.assertIn("| **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2 by 3 | 9.5 |", ranked.text)
|
||||
|
||||
def test_refuses_a_goal_named_beside_its_own_sub_goal(self):
|
||||
readme = "## Goals\n\n1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
|
||||
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)
|
||||
@@ -188,7 +192,7 @@ class Rank(unittest.TestCase):
|
||||
def test_scores_every_item_zero_where_readme_marks_no_goal_achieve(self):
|
||||
ranked = self.ranked(TODO.replace("2.1 by 8, 1 by 6", "").replace("| 2.1 by 1 |", "| |").replace("| 1 by 9 |", "| |"), README.replace("**Achieve:**", "**Maintain:**"))
|
||||
self.assertEqual([line.split(" scores ")[0] for line in ranked.under_bar], ["item 2", "item 3", "item 1"])
|
||||
self.assertEqual(ranked.notes, ["README.md marks no goal **Achieve:**, so every item scores V 0"])
|
||||
self.assertEqual(ranked.notes, ["README.md voids code health and marks no goal **Achieve:**, so every item scores V 0"])
|
||||
|
||||
def test_accepts_a_move_of_ten_and_a_variable_base(self):
|
||||
ranked = self.ranked(TODO.replace("| 1 by 9 |", "| 1 by 10 |").replace("100 * V / 2**S", "V * S ** 2"))
|
||||
@@ -196,7 +200,7 @@ class Rank(unittest.TestCase):
|
||||
|
||||
def test_asks_to_drop_a_goal_weights_table_from_a_table_with_moves(self):
|
||||
weighted = TODO.replace("## Items\n", "| Goal | W |\n|---|---|\n| 1 | 1.00 |\n\n## Items\n")
|
||||
self.assertEqual(self.ranked(weighted), Failure("todo.md holds a goal weights table beside a Moves column; drop the table, since rank_todo.py weighs each achieve goal by its position in README.md"))
|
||||
self.assertEqual(self.ranked(weighted), Failure("todo.md holds a goal weights table beside a Moves column; drop the table, since rank_todo.py weighs the goals itself, as its --help says"))
|
||||
|
||||
def test_refuses_a_formula_that_is_more_than_arithmetic_over_the_scores(self):
|
||||
for formula in ("__import__('os')", "R.real", "X + 1", "C + 1", "A + V", "G + V", "W * V", "R ^ 2", "R +", "R / (S - 2)", "R\x00", "1" * 400, " + ".join(["R"] * 300), "-" * 100000 + "R", "10 ** 10 ** 10", "(-8) ** (1 / 3)", "0 ** -1"):
|
||||
@@ -206,7 +210,7 @@ class Rank(unittest.TestCase):
|
||||
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "1 ** (1 / (S - S))")), Failure("the formula gives item 1 no finite score"))
|
||||
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "(1 / (S - S)) ** 0")), Failure("the formula gives item 1 no finite score"))
|
||||
self.assertEqual(self.ranked(TODO.replace("100 * V / 2**S", "W")), Failure("the formula 'W' may hold only numbers, E, I, L, R, S, V, + - * / ** and parentheses"))
|
||||
self.assertEqual(self.ranked(TODO.replace("2.1 by 8, 1 by 6", "2.1: 8, 1: 6")), Failure("item 3's Moves '2.1: 8, 1: 6' is not empty or goals such as `1.1 by 8, 1.2 by 5`, each moved by a whole number from 1 to 10"))
|
||||
self.assertEqual(self.ranked(TODO.replace("2.1 by 8, 1 by 6", "2.1: 8, 1: 6")), Failure("item 3's Moves '2.1: 8, 1: 6' is not empty or goals such as `1.1 by 8, code health by 5`, each moved by a whole number from 1 to 10"))
|
||||
|
||||
def test_refuses_a_file_off_the_format(self):
|
||||
row = "| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 | 0 |"
|
||||
@@ -240,10 +244,116 @@ class Rank(unittest.TestCase):
|
||||
self.assertIsInstance(self.ranked(TODO.replace(old, new)), Failure)
|
||||
|
||||
|
||||
# A scoring run of the project whose overall mean is {overall}.
|
||||
SCORED = "# Comprehension history\n\n## 2026-10-08T12:00:00Z, PR #1 at aaaaaaa\n\n| Seat | Overall |\n|---|---|\n| Mid A | 6 |\n| Mean | {overall} |\n"
|
||||
|
||||
|
||||
class CodeHealth(unittest.TestCase):
|
||||
readme = "## Goals\n\n1. **Achieve:** A.\n"
|
||||
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)
|
||||
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"):
|
||||
"""A scoring run's entry, without the history's title."""
|
||||
return SCORED.format(overall=overall).removeprefix("# Comprehension history\n\n").replace("2026-10-08T12", at).replace("PR #1 at aaaaaaa", read)
|
||||
|
||||
def test_ranks_code_health_first_among_the_achieve_goals_at_an_overall_of_7_or_above(self):
|
||||
# Code health, then goal 1: weights 1 / 1.97 and 0.97 / 1.97, an item moving one by 1 at S 1 scoring 50 times its weight.
|
||||
self.assertEqual(self.scores(SCORED.format(overall="7.00")), {"| 1": "25.4", "| 2": "24.6"})
|
||||
|
||||
def test_weighs_code_health_four_times_as_much_under_an_overall_of_7_and_before_any_scoring_run(self):
|
||||
for history in (SCORED.format(overall="6.99"), "", "# Comprehension history\n\n## 2026-10-09T12:00:00Z, PR #2 at bbbbbbb, against aaaaaaa\n\nRuling: better\n"):
|
||||
with self.subTest(history=history):
|
||||
self.assertEqual(self.scores(history), {"| 1": "101.5", "| 2": "24.6"})
|
||||
|
||||
def test_weighs_by_the_newest_scored_commit_wherever_the_file_holds_it(self):
|
||||
older = self.entry("6.50")
|
||||
newer = self.entry("7.25", "2026-10-10T12", "PR #1 at bbbbbbb")
|
||||
for history in (f"{older}\n{newer}", f"{newer}\n{older}"):
|
||||
with self.subTest(history=history):
|
||||
self.assertEqual(self.scores(history)["| 1"], "25.4")
|
||||
|
||||
def test_weighs_by_the_mean_overall_of_every_run_on_the_newest_scored_commit(self):
|
||||
# 7.13 and 6.88 average 7.005, at the floor or above; 7.10 and 6.80 average 6.95, under it.
|
||||
for first, rerun, value in (("7.13", "6.88", "25.4"), ("7.10", "6.80", "101.5")):
|
||||
with self.subTest(first=first, rerun=rerun):
|
||||
self.assertEqual(self.scores(f"{self.entry(first)}\n{self.entry(rerun, '2026-10-08T13', 'PR #1 rerun at aaaaaaa')}")["| 1"], value)
|
||||
later = self.entry("6.50", "2026-10-09T12", "PR #2 at bbbbbbb")
|
||||
self.assertEqual(self.scores(f"{self.entry('7.13')}\n{self.entry('6.88', '2026-10-08T13', 'PR #1 rerun at aaaaaaa')}\n{later}")["| 1"], "101.5")
|
||||
|
||||
def test_matches_a_commit_whichever_length_a_heading_writes_it_at(self):
|
||||
full = "aaaaaaa" + "0" * 33
|
||||
# As runs of one commit, 7.13 and 6.88 average 7.005; the newer alone is under the floor.
|
||||
for first, rerun in (("aaaaaaa", full), (full, "aaaaaaa")):
|
||||
with self.subTest(first=first, rerun=rerun):
|
||||
self.assertEqual(self.scores(f"{self.entry('7.13', read=f'PR #1 at {first}')}\n{self.entry('6.88', '2026-10-08T13', f'PR #1 rerun at {rerun}')}")["| 1"], "25.4")
|
||||
|
||||
def test_weighs_by_a_ruling_that_holds_scoring_seats_places(self):
|
||||
# A ruling recorded before PR #255 scored the project too: below its votes, a scores table with a Mean row, and each scoring seat's places.
|
||||
ruling = "## 2026-10-10T12:00:00Z, PR #2 at bbbbbbb, against aaaaaaa\n\nRuling: better\n\n| Seat | Overall |\n|---|---|\n| Mid A | better |\n\n| Seat | Overall |\n|---|---|\n| Mid A | 7.5 |\n| Mean | 7.25 |\n\nJunior A, hardest first:\n\n- `bin/a.py:1` `f`: long\n"
|
||||
self.assertEqual(self.scores(f"{self.entry('6.50')}\n{ruling}")["| 1"], "25.4")
|
||||
|
||||
def test_refuses_a_newest_scoring_run_with_no_overall_mean(self):
|
||||
for history in (SCORED.format(overall="high"), SCORED.split("| Mean")[0]):
|
||||
with self.subTest(history=history):
|
||||
self.assertEqual(self.scores(history), Failure("docs/comprehension-history.md's scoring run 2026-10-08T12:00:00Z, PR #1 at aaaaaaa has no Mean row ending in its overall, which sets code health's weight"))
|
||||
|
||||
def test_drops_code_health_where_readme_voids_it(self):
|
||||
voided = "## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** A.\n"
|
||||
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, "", "")
|
||||
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):
|
||||
readme = "## Goals\n\n1. **Achieve:** A.\n2. **Maintain:** B.\n"
|
||||
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)
|
||||
|
||||
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)
|
||||
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)
|
||||
|
||||
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)
|
||||
|
||||
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>.`"))
|
||||
|
||||
def test_shows_the_spelling_of_a_void_of_code_health_that_misses_it(self):
|
||||
for void in ("code health.", "Code health, since it is a one-off script.", "code health since it is a one-off script."):
|
||||
with self.subTest(void=void):
|
||||
self.assertEqual(self.scores("", f"## Goals\n\n**Void:** {void}\n\n1. **Achieve:** A.\n"), Failure(f"README.md's ## Goals voids code health as `{void}`; spell the void exactly `**Void:** code health, since <reason>.`"))
|
||||
|
||||
def test_parses_code_health_in_a_moves_cell(self):
|
||||
self.assertEqual(todo_table.parse_moves("1", "code health by 4, 1.1 by 2"), (("code health", 4), ("1.1", 2)))
|
||||
self.assertIsInstance(todo_table.parse_moves("1", "code health by 11"), Failure)
|
||||
self.assertIsInstance(todo_table.parse_moves("1", "health by 4"), Failure)
|
||||
|
||||
def test_reads_the_history_beside_todo_md(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
todo.write_text(self.todo)
|
||||
pathlib.Path(temp, "README.md").write_text(self.readme)
|
||||
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.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 rank_todo.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
|
||||
@@ -292,7 +402,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 rank_todo.rank(todo, readme, DECISIONS, "")
|
||||
|
||||
def test_scores_by_the_stated_weights_and_says_to_reshape(self):
|
||||
ranked = self.ranked()
|
||||
@@ -319,7 +429,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(rank_todo.rank(legacy, README, "", "").notes, [rank_todo.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")
|
||||
@@ -329,14 +439,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(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(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 rank_todo.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 |"))
|
||||
@@ -436,15 +546,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 = rank_todo.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(rank_todo.rank(TODO + "\n## Renamed\n\n- 0.3.0 renamed to 0.4.0\n", README, DECISIONS, ""), rank_todo.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 = rank_todo.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)
|
||||
|
||||
@@ -472,6 +582,17 @@ class Main(unittest.TestCase):
|
||||
pathlib.Path(temp, "README.md").unlink()
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"{temp}/README.md: not found; rank_todo.py weighs goals from the README.md beside todo.md\n"))
|
||||
|
||||
def test_writes_the_ranked_file_yet_fails_on_an_item_under_the_bar(self):
|
||||
under = "item 2 scores 3.1, under the bar 4; delete it, or mark it with a reason the bar does not apply"
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
todo.write_text(TODO.replace("`Bar = 2`", "`Bar = 4`"))
|
||||
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)), (1, f"{todo}: {under}\n"))
|
||||
self.assertEqual(self.run_main("--check", str(todo)), (1, f"{todo}: {under}\n"))
|
||||
|
||||
def test_says_to_reshape_an_old_shape_table_but_passes_the_check(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
@@ -485,7 +606,7 @@ class Main(unittest.TestCase):
|
||||
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", "")
|
||||
ranked = rank_todo.rank(skeleton, "## Goals\n\n1. **Achieve:** Work.\n", "", "")
|
||||
self.assertIsInstance(ranked, rank_todo.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"))
|
||||
@@ -494,5 +615,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 / "README.md").read_text(encoding="utf-8"), (ROOT / "docs" / "decisions.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, [], []))
|
||||
|
||||
+5
-3
@@ -15,6 +15,8 @@ EXEMPTIONS = ("", "decision", "defect", "owner", "principle", "question", "secur
|
||||
BLOCKED_BY = "Blocked by"
|
||||
# The column naming each achieve goal an item moves and how far, such as `1.1 by 8, 1.2 by 5`.
|
||||
MOVES = "Moves"
|
||||
# The achieve goal every project shares, which ~/.claude/CLAUDE.md → "Shared goal" states, and a Moves cell names by these words, since it has no number in any README.
|
||||
CODE_HEALTH = "code health"
|
||||
# How the items table's header opens, which tells it from any other table in todo.md.
|
||||
HEADER_START = "| ID | Release |"
|
||||
# todo.md's ## Details section, its body the first group.
|
||||
@@ -55,11 +57,11 @@ class Shape:
|
||||
|
||||
|
||||
def parse_moves(id_: str, cell: str) -> Moves | Failure:
|
||||
"""A Moves cell: empty, or each goal the item moves, named once, and how far."""
|
||||
matches = [re.fullmatch(r"([0-9]+(?:\.[0-9]+)*) by ([0-9]+)", move) for move in cell.split(", ")] if cell else []
|
||||
"""A Moves cell: empty, or each goal the item moves, named once, and how far. rank_todo.py's cited_goals_failure holds the rules that need README.md."""
|
||||
matches = [re.fullmatch(rf"([0-9]+(?:\.[0-9]+)*|{CODE_HEALTH}) by ([0-9]+)", move) for move in cell.split(", ")] if cell else []
|
||||
moves = tuple((match.group(1), int(match.group(2))) for match in matches if match)
|
||||
if len(moves) < len(matches) or any(not 1 <= by <= TOP_SCORE for _, by in moves):
|
||||
return Failure(f"item {id_}'s {MOVES} {cell!r} is not empty or goals such as `1.1 by 8, 1.2 by 5`, each moved by a whole number from 1 to {TOP_SCORE}")
|
||||
return Failure(f"item {id_}'s {MOVES} {cell!r} is not empty or goals such as `1.1 by 8, {CODE_HEALTH} by 5`, each moved by a whole number from 1 to {TOP_SCORE}")
|
||||
goals = [goal for goal, _ in moves]
|
||||
if repeated := [goal for goal in goals if goals.count(goal) > 1]:
|
||||
return Failure(f"item {id_} cites goal {repeated[0]} twice; name each goal once")
|
||||
|
||||
@@ -2303,3 +2303,135 @@ Junior A, decided by:
|
||||
- Locality, Shape: `bin/review_replay/main.py:208` `reviewed_in`: four jobs and seven arguments became named units with docstrings, and `main`'s loop and lambdas are named
|
||||
- Navigation: `README.md:113`: the import map now names every reader of `model_routing/` and what `rung_replay/` holds, and the tool's name leads to it for any pass
|
||||
- Shape: `bin/loop_claude/cycle/prompts.py:57` `shared_launches`: five helpers, a made-up `"each reviewer"` key and paths an empty `REPLAYED` never runs, against `ReviewKind` naming the real passes
|
||||
|
||||
## 2026-10-18T19:59:26Z, PR #324 at c713910, against e6223f7
|
||||
|
||||
Ruling: same
|
||||
|
||||
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
||||
|---|---|---|---|---|---|
|
||||
| Mid A | same | worse | better | same | same |
|
||||
| Inherited architect | same | worse | better | same | same |
|
||||
|
||||
Mid A, decided by:
|
||||
|
||||
- Locality: `bin/larv_review/record.py:56` `rerank`: recording a scoring run now also rewrites the checkout's todo.md and can exit 1 on items under the bar, so changing record-scoring needs rank_todo.rank_file's whole contract, where the base only appended to the history
|
||||
- Locality: `bin/rank_todo.py:338` `weigh`: an item's score now depends on docs/comprehension-history.md's newest scored commit and on a `## review opt-out:` title in docs/decisions.md, so scores and --check can change without anyone editing todo.md or README.md
|
||||
- Shape: `bin/rank_todo.py:315` `ranked_goals`: the base's inline three-way weights branch in read_scoring is a named weigh, with the code-health and void rules in ranked_goals, each easier alone, at the cost of three similar names weigh, goal_weights and parse_weights
|
||||
- Shape: `bin/rank_todo.py:623` `cited_goals_failure`: the base's parse_item mixed goal checks with writing R, and main inlined read, rank, write and print; each is now a unit with one purpose, and rank_file is reusable
|
||||
- Shape: `bin/comprehension_history.py:130` `newest_scored`: the base's index arithmetic in latest_places is a named helper latest_overall shares, and overall_cells and FLOOR moved to the module that parses the table they read
|
||||
|
||||
Inherited architect, decided by:
|
||||
|
||||
- Locality: `bin/rank_todo.py:196` `read_all`: ranking now also depends on the newest scoring run in docs/comprehension-history.md, so a passing --check can fail with nobody touching todo.md, and nothing at the call site shows that a history append moves code health's weight
|
||||
- Locality: `bin/larv_review/record.py:56` `rerank`: recording a scoring run now writes todo.md through rank_todo.rank_file, which prints its notes to stderr, and the message pointing at "the lines above" reads right only if rank_file printed first
|
||||
- Locality: `bin/rank_todo.py:106` `OPTED_OUT`: ranking now matches a docs/decisions.md title spelled in larv-review's SKILL.md → "Opt-out", so rewording that heading silently changes whether rank_todo refuses a plan
|
||||
- Locality: `bin/loop_claude/cycle/prompts.py:17` `AFTER_CODE_HEALTH`: the caveat that code health ranks first unless the README voids it is repeated in prose across about eight files, so one change to the shared goal edits all of them
|
||||
- Shape: `bin/comprehension_history.py:130` `newest_scored`: replaces the base's index juggling in latest_places with two truthfully named predicates serving latest_places and latest_overall
|
||||
- Shape: `bin/comprehension_history.py:145` `overall_cells`: FLOOR and overall_cells now have one home next to DIMENSIONS, and agreement's inline sort became the named scoring_runs
|
||||
- Shape: `bin/rank_todo.py:332` `weigh`: weigh, cited_goals_failure and rank_file are pulled out of read_scoring, parse_item and main, each doing one thing
|
||||
|
||||
## 2026-10-18T19:59:40Z, PR #324 at c713910
|
||||
|
||||
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
||||
|---|---|---|---|---|---|
|
||||
| Junior A | 7 | 5.5 | 6 | 6.5 | 6 |
|
||||
| Mid A | 7 | 5.5 | 6 | 6.5 | 6 |
|
||||
| Maintainability senior | 7 | 6 | 6.5 | 6.5 | 6.5 |
|
||||
| Inherited architect | 7 | 6 | 6 | 7 | 6.5 |
|
||||
| Mean | 7.00 | 5.75 | 6.13 | 6.63 | 6.25 |
|
||||
|
||||
Junior A, hardest first:
|
||||
|
||||
- `bin/model_routing/route.py:66` `Route.escalated_at`: the escalation mark lives in six units across four files, with judge_once stamping entries_read, escalation_mark, stepped and judge_prompt's STEP_LINE held at once
|
||||
- `bin/loop_claude/loop/main.py:1` "loop-claude --help": a 164-line docstring is the loop's real spec, its routing paragraphs packing every rule into one block that routed and after_verdict need open
|
||||
- `bin/loop_claude/cycle/prompts.py:46` `review_launches`: prompt sentences assembled from rung comparisons over replay-lowered passes, the project's rung, the top rung and higher E + I
|
||||
- `bin/model_routing/route.py:13` `ROUTED`: stored state persisted as prose and parsed back by regexes in four places, so rewording one string silently changes routing
|
||||
- `bin/rank_todo.py:568` `score`: a 660-line file carrying two table shapes, with OLD_SHAPE forks in scoring, weights, goal parsing and column checks
|
||||
- `bin/chunk_pick.py:97` `standing`: five inputs become five outcomes, and chunk_pick.Finished shares its name with judge.Finished
|
||||
- `bin/review_replay/rounds.py:73` `reviewed_path`: rebuilds the code a past reviewer read from prompt text and author times, a heuristic
|
||||
- `bin/comprehension_history.py:159` `scored`: legacy formats from before PR #255 and #232 leak into the reading
|
||||
|
||||
Mid A, hardest first:
|
||||
|
||||
- `bin/loop_claude/routing.py:64` `stepped`: seven small functions, each defined through another, with six inputs held at once to predict one rung, and an import cycle shaping the signature
|
||||
- `bin/loop_claude/loop/main.py:259` `after_verdict`: the 164-line docstring is the only full map of routing, and after_verdict chains it all in one expression
|
||||
- `bin/loop_claude/cycle/run.py:45` `Cycle.stepped_from`: the route changes outside the state machine, cleared on every event but HumanTyped, so it outlives exactly one hop
|
||||
- `bin/loop_claude/cycle/judge.py:216` `quotes_checked`: three bodies of text to check quotes against, fuzzy matching, and three ways a failed check is handled
|
||||
- `bin/loop_claude/cycle/prompts.py:46` `review_launches`: fragments that each start with a space, so no whole prompt is visible without running it in your head
|
||||
- `bin/model_routing/route.py:13` `ROUTED`: a saved string format parsed back by a verbose regex that still accepts an older format
|
||||
- `bin/rank_todo.py:568` `score`: two table shapes share every path, the goal term W in one and V in the other
|
||||
- `bin/loop_claude/loop/reload.py:43` `decoded_as`: a generic decoder with two sentinels and a duck-typed fits hook defined on Route
|
||||
|
||||
Maintainability senior, hardest first:
|
||||
|
||||
- `bin/loop_claude/routing.py:64` `stepped`: four things held at once, the unfinished count, the taken-in L, the escalation cap from item_rung and the mark threaded through judge.py's escalation_mark, STEP_LINE and Grounds.since_step
|
||||
- `bin/model_routing/route.py:86` `Route.__str__`: the route written as English and parsed back by ROUTED and outcomes.workers, so a sentence's wording is a storage schema shared by four tools
|
||||
- `bin/loop_claude/loop/main.py:1` "loop-claude --help": a 160-line spec whose routing paragraph carries about 15 rules, re-describing what routing.py, ladder.py and retry.py enforce
|
||||
- `bin/loop_claude/cycle/prompts.py:46` `review_launches`: each sentence built conditionally with a leading-space convention, and taken_in_launches scanning every higher E + I
|
||||
- `bin/loop_claude/cycle/judge.py:216` `quotes_checked`: three grounds with three failure consequences, and the demotion to an interrupt loses release_ready
|
||||
- `bin/review_replay/rounds.py:73` `reviewed_path`: guesses which removed worktree a reviewer read, and redirected depends on the order of its replacements
|
||||
- `bin/comprehension_history.py:150` `scoring_runs`: near-synonyms scored and scoring_runs differ only on a ruling from before PR #255
|
||||
- `bin/rank_todo.py:332` `weigh`: the goal term is W or V by shape, so every scoring path asks which shape
|
||||
|
||||
Inherited architect, would restructure first:
|
||||
|
||||
- `bin/round_titles.py:4` `CAP`: no program loops the reviewers; the cap lives in SKILL.md prose and the code only counts rounds and prints a note
|
||||
- `bin/git_command.py:16` `commits`: parses git commit messages for rule-hook while git_repo.py, rule_hook/git.py, larv_review/git.py and Effects.git each run git, and git_repo bypasses Effects
|
||||
- `bin/transcript_archive/outcomes.py:39` `outcomes`: shares its name with score_outcomes/outcomes.py, which measures finished chunks instead
|
||||
- `bin/loop_claude/routing.py:64` `stepped`: routing has four homes, ladder.py, route.py, routing.py and routing_check with routing_figures, and prompts.py restates the ladder as sentences
|
||||
- `bin/rank_todo.py:196` `read_all`: a 658-line library as well as a tool, imported by rule_hook and larv_review, and now reading four documents, so a todo.md commit in any project depends on its comprehension history
|
||||
- `bin/loop_claude/cycle/judge.py:68` `Reply.bundled`: the taken-in L is also called bundled, and the project's rung is also called anchor
|
||||
- `bin/chunk_pick.py:97` `standing`: "next release" is computed two ways, here and in larv_review/plan.py's scoring_run_due, which may diverge after a rename
|
||||
|
||||
## 2026-10-18T19:59:40Z, PR #324 rerun at c713910
|
||||
|
||||
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
||||
|---|---|---|---|---|---|
|
||||
| Junior A | 7 | 5.5 | 6.5 | 6 | 6 |
|
||||
| Mid A | 7.5 | 6 | 6.5 | 7 | 6.5 |
|
||||
| Maintainability senior | 7.5 | 6 | 6.5 | 6.5 | 6.5 |
|
||||
| Inherited architect | 6.5 | 6 | 5.5 | 6.5 | 6 |
|
||||
| Mean | 7.13 | 5.88 | 6.25 | 6.50 | 6.25 |
|
||||
|
||||
Junior A, hardest first:
|
||||
|
||||
- `bin/loop_claude/cycle/prompts.py:46` `review_launches`: the worker's English instructions built from how the worker's, the project's, the reviewers' and any replay-lowered rung relate, with ladder.review_rungs, REPLAYED and escalation_rungs open at once
|
||||
- `bin/loop_claude/routing.py:64` `stepped`: seven small functions defined through each other, bundled learned only from judge.Reply, and escalated_at both an argument and a Route field with different meanings
|
||||
- `bin/model_routing/route.py:13` `ROUTED`: routing state lives as English sentences in outcomes.md, read back by a regex, with the newest file by mtime deciding
|
||||
- `bin/loop_claude/loop/main.py:1` "loop-claude --help": about 160 lines and the only full account of routing, step-ups, the archive layout, reloads and the routing figures in one unbroken paragraph
|
||||
- `bin/loop_claude/cycle/run.py:69` `escalated`: stepped_from must survive a HumanTyped event and reset on every other, and archive_stepped writes one outcome or two depending on it
|
||||
- `bin/loop_claude/cycle/judge.py:216` `quotes_checked`: three quote checks follow different rules, and an escalation that fails is silently dropped
|
||||
- `bin/chunk_pick.py:97` `standing`: two separate notions of the next release and of work having landed, here and in larv_review/plan.py's scoring_run_due
|
||||
- `bin/rank_todo.py:332` `weigh`: old-shape support forks behaviour throughout a 659-line file
|
||||
|
||||
Mid A, hardest first:
|
||||
|
||||
- `bin/model_routing/route.py:66` `Route.escalated_at`: the escalation mark is one concept spread over five files, the entry count, the injected step line, a double quote check and the cap from item_rung held at once
|
||||
- `bin/loop_claude/cycle/run.py:69` `escalated`: state outside the state machine, cleared on every event but HumanTyped and read by ask, keep_answer and archive_stepped, depending on its order before transition
|
||||
- `bin/loop_claude/cycle/prompts.py:46` `review_launches`: routing policy and English wording interleaved, much of the branching serving an empty REPLAYED
|
||||
- `bin/loop_claude/loop/main.py:210` `run_loop`: the route passed as lazy thunks and re-derived every cycle, with an anchor-is-None branch in three places
|
||||
- `bin/model_routing/route.py:86` `Route.__str__`: the archive's human-readable lines are what reruns, the routing figures and the replays parse back
|
||||
- `bin/comprehension_history.py:150` `scoring_runs`: two near-identical predicates differing only for a ruling from before PR #255
|
||||
- `bin/rank_todo.py:568` `score`: every rule exists twice for the old table shape
|
||||
- `bin/review_replay/main.py:149` `code_of`: rebuilds which worktree a reviewer read by the first missing directory among its prompt's paths
|
||||
|
||||
Maintainability senior, hardest first:
|
||||
|
||||
- `bin/loop_claude/routing.py:64` `stepped`: seven one-line rung functions each defined by the others, four inputs held together, and an import cycle steering the interface
|
||||
- `bin/loop_claude/cycle/judge.py:153` `escalation_mark`: the escalation mark spread over route.py, judge.py's Grounds and judge_prompt and run.py's escalated, and no single place states that one trigger buys one step
|
||||
- `bin/loop_claude/cycle/prompts.py:46` `review_launches`: which conditional sentences reach which prompt means tracing fresh, routed_by, resumed, rungs_held and stepped_to
|
||||
- `bin/loop_claude/loop/main.py:1` "loop-claude --help": the routing paragraph is one block covering the ladder, the judge, replays, rule-hook's variables, step rules, archive lines and legacy R + C
|
||||
- `bin/model_routing/route.py:13` `ROUTED`: routing state survives restarts as English sentences parsed back by regex, a hidden contract across three packages
|
||||
- `bin/rank_todo.py:218` `rank`: every stage branches on the old table shape, about half a 660-line file read and then discarded
|
||||
- `bin/comprehension_history.py:130` `newest_scored`: four near-identical names over two concepts, split by a legacy case only the docstrings explain
|
||||
- `bin/chunk_pick.py:97` `standing`: five inputs, three of which may be Failure, produce five outcomes, the order of the Failure checks carrying meaning
|
||||
|
||||
Inherited architect, would restructure first:
|
||||
|
||||
- `bin/round_titles.py:5` `PASSES`: the pass list lives in four places, PASSES, ladder.ReviewedPass, REVIEWERS and SKILL.md's table, kept in sync by hand
|
||||
- `bin/rule_hook/rules.py:55` `round-title-counts`: no program blocks a fourth review round; rule-hook checks only the counts inside a round's title
|
||||
- `bin/git_repo.py:8` `git`: bin/'s root holds about 43 entries, with 13 loose modules such as git_repo, git_command, chunk_pick and todo_table not grouped by purpose
|
||||
- `bin/loop_claude/cycle/judge.py:68` `Reply.bundled`: the taken-in L and E + I are bundled in the judge's reply and taken in on Route and in routing.taken_in
|
||||
- `bin/model_routing/route.py:86` `Route.__str__`: the archive's text format is written in two modules and parsed back by ROUTED, routing_figures, reading_cost, score_outcomes and judge_replay
|
||||
- `bin/todo_table.py:89` `OLD_SHAPE`: the old todo.md shape is the largest dead weight in rank_todo.py
|
||||
|
||||
+6
-4
@@ -90,9 +90,9 @@ Valid while the ladder orders its rungs by competence.
|
||||
|
||||
2026-10-04, lilleman. Serves goal 1.4. In a restructure, each step's scoring run measures code the next step deletes. It costs a run and, below the floor, blocks the step, yet says nothing about what the restructure buys. The scoring run after the last step measures that. 2026-10-08: the paired ruling replaced the scoring run in most chunks, and the suspension covers it too; the ruling after the last step compares with the commit measured before the first step. 2026-10-13, lilleman: the comprehension check blocks nothing now, so a suspension saves only the runs. Valid while such a decision names its items and the plan item that ends it.
|
||||
|
||||
## review: a project decision may opt every chunk out of the architect, the product-owner pass or the comprehension check
|
||||
## review: a project decision may opt every chunk out of the architect, the product-owner pass or the comprehension check, and a project opting out of the comprehension check voids code health
|
||||
|
||||
2026-10-11, lilleman. Serves goal 1.4. A research repo's PR, in a repo with no consumer for the product-owner pass and no product for the architect, spent rounds of both, and of the comprehension check, on a probe. The opt-out is the project's to make, and only an entry titled `review opt-out:` makes it, so a project without one is reviewed as before (goal 1.3). No opted-out reviewer works against a goal or a technical principle: the principles audit, which has no opt-out, still judges KISS and every other principle, so the entry names no plan item that ends it. 2026-10-13, lilleman: an opt-out of the comprehension check no longer ends with a chunk that ships an item naming the floor, since the floor blocks nothing. Valid while the principles audit judges every chunk that changes code, config or tests, and while the architect's and the product-owner's findings matter only to a product with consumers.
|
||||
2026-10-11, lilleman. Serves goal 1.4. A research repo's PR, in a repo with no consumer for the product-owner pass and no product for the architect, spent rounds of both, and of the comprehension check, on a probe. The opt-out is the project's to make, and only an entry titled `review opt-out:` makes it, so a project without one is reviewed as before (goal 1.3). No opted-out reviewer works against a goal or a technical principle: the principles audit, which has no opt-out, still judges KISS and every other principle, so the entry names no plan item that ends it. 2026-10-13, lilleman: an opt-out of the comprehension check no longer ends with a chunk that ships an item naming the floor, since the floor blocks nothing. 2026-10-18, lilleman, answering the review of PR #324: a project that opts out of the comprehension check voids code health in its README too: without the check the goal has no signal, and, never measured, it would weigh four times its weight forever. `rank_todo.py` refuses the plan of such a project until its README voids it. Valid while the principles audit judges every chunk that changes code, config or tests, and while the architect's and the product-owner's findings matter only to a product with consumers.
|
||||
|
||||
## review: the principles audit runs on every chunk that changes code, config or tests, and on no other chunk
|
||||
|
||||
@@ -132,7 +132,7 @@ Valid while the ladder orders its rungs by competence.
|
||||
|
||||
2026-10-02, lilleman. Serves goal 4, which keeps credentials, transcripts and memory files off the remote; a private project's name and commit ids are none of those. Valid while the bench names only cases and commits, never their code or results.
|
||||
|
||||
## todo.md: one table of items scored by the formula it states, each README achieve goal weighed by its position, the first heaviest, held to its bar, ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; the table's order is the plan's only order
|
||||
## todo.md: one table of items, scored by the formula it states, held to its bar and ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; each achieve goal weighs by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0 or unmeasured, then README.md's goals; the table's order is the plan's only order
|
||||
|
||||
2026-10-02, lilleman. Serves goal 1: findings were filed faster than chunks closed them, so the plan grew without telling what mattered. Each item is scored as `~/.claude/rules/todo-items.md` says; this repo's formula counts value highest and size least. An item under the bar is not kept; this repo's bar started at 10 and was set to 9 the same day, purging the 17 items under it. An Exempt cell keeps a row past the bar where a rule needs it kept. lilleman retired the two decisions whose plans the purge removed: the stats line in the transcript archive, and three benches before a workflow change merges. A finding under the bar is recorded nowhere, so a later review may raise it again, and the run rescores it. That costs one scoring; a ledger of dropped findings would regrow the list the bar caps. larv-review's "Round cap" → "Done" counts a finding named under the bar as settled, so one raised again holds no pass open. `rank_todo.py --check` is part of larv-review's gate, since only a check keeps the stored Score from going stale. The format is mandatory in every project, as the premises are (goal 1.3); the formula and bar are each project's own. A script ranks the table so a re-rank after each addition or edit is deterministic and cheap. A 🟡 against a technical principle is exempt as `principle`, because its audience value scores low and the bar would drop every one. A 🟢 against a principle is scored like any other finding. 2026-10-08, lilleman: the goal weights in `todo.md` depart from an even spread by position, which would weigh goal 4, leaking nothing, at 0.11. Valid while one human sets the bar and reads the ranking, and while the items marked `principle` stay few enough to rank.
|
||||
|
||||
@@ -140,10 +140,12 @@ Valid while the ladder orders its rungs by competence.
|
||||
|
||||
2026-10-16, PR #283: items rank by `Score = 100 * V / 2**S`. 2**S is the cost; the 100 lets a score read to one decimal. V sums, over the achieve goals an item's Moves cell names, each goal's weight times how far the item moves it, 1 to 10. Each achieve goal, in reading order, weighs 0.97 times the one before it, and the weights sum to 1. 2026-10-18, lilleman: goals should weigh almost the same. This replaced the sum-reciprocal weight, under which the goal ranked k of n achieve goals weighed (1/k) / (1 + 1/2 + … + 1/n), so the last of twelve goals weighed a twelfth of the first. The step departs from `docs/scoring-and-goals-research.md`, where sum-reciprocal weights came closest to the weights people gave. PR #319 restored the sum-reciprocal weights on a misreading of lilleman's answer, and lilleman then confirmed the step, so the sum-reciprocal weights stay dropped. The worker picked 0.97; `GOAL_STEP` sets it. A Moves column replaces A, G and Goals, and `rank_todo.py` derives the weights from README.md, so the goal weights table and the 2026-10-08 weights are gone. An item that cited only maintain goals now names the achieve goal it moves, or, as a defect restoring one, that maintain goal, as the entry below says. A panel of three readers seated as lilleman picked the spelling: two put a Moves column holding `1.1 by 8, 1.2 by 5` first, and one put `1.1: 8` first; two chose `2**S`, since a Python reader takes `^` for XOR; all three chose one decimal of `100 * V / 2**S` over three significant digits or a log. The bar moved to 0.1, lilleman's call answering the review of PR #283: on one-decimal scores it drops an item scoring under 0.05, in practice one that moves no achieve goal, and item 149 revisits it. A table in the old shape still ranks by the formula and weights it states, and ranking it says to reshape it, so no other project's commits stop; reshaping it is that project's only work until done, as `CLAUDE.md` → "Working loop" says. PR #296 dropped the C column, and put L, E and I right before R, which `rank_todo.py` writes from them: of three readers seated as lilleman, two ranked that order first, since a reader meets each level before the R it builds and R sits beside S, and the third ranked it second, after an order with S before the levels. The old shape's ranking is valid until `todo.md` item 156.
|
||||
|
||||
2026-10-16, lilleman, answering the review of PR #283. An item that restores a maintain goal the project breaks today is a defect: exempt as `defect`. Its Moves name that maintain goal and how much of it is broken, and the goal weighs as the heaviest achieve goal, since a broken maintain goal outranks any achieve goal. Every defect ranks by its score, so a trivial one waits behind valuable work. Only questions and then security findings rank first in their release: a question's answer may change other items, and a question waits for the human anyway, so ranking it first delays no chunk. An item names the most specific goal it moves, and a parent only for a move none of its sub-goals covers, so a sub-goal's move does not count twice; `rank_todo.py` refuses a goal named beside its own sub-goal. Each project reshapes its own `todo.md`; `CLAUDE.md` → "Working loop" makes the reshape the only work until done, as it makes writing missing premises. An item that makes this project easier to read moves goal 1.4 as well as 1.1, since reading cost is measured in tokens per chunk; a goal of its own for readability is left for later. Cost gains a fixed part, F in `Score = 100 * V / (2**S + F)`: every chunk carries a cost its size does not shrink, the reading before its first commit, about 130k tokens, and its review passes, so `2**S` alone overrated tiny items. F is 8, about one S 3 change, until `todo.md` item 158 measures it.
|
||||
2026-10-16, lilleman, answering the review of PR #283. An item that restores a maintain goal the project breaks today is a defect: exempt as `defect`. Its Moves name that maintain goal and how much of it is broken, and the goal weighs as the heaviest achieve goal, since a broken maintain goal outranks any achieve goal. Every defect ranks by its score, so a trivial one waits behind valuable work. Only questions and then security findings rank first in their release: a question's answer may change other items, and a question waits for the human anyway, so ranking it first delays no chunk. An item names the most specific goal it moves, and a parent only for a move none of its sub-goals covers, so a sub-goal's move does not count twice; `rank_todo.py` refuses a goal named beside its own sub-goal. Each project reshapes its own `todo.md`; `CLAUDE.md` → "Working loop" makes the reshape the only work until done, as it makes writing missing premises. An item that makes this project easier to read moves code health, as the 2026-10-18 paragraph below says, and goal 1.4, since reading cost is measured in tokens per chunk. Cost gains a fixed part, F in `Score = 100 * V / (2**S + F)`: every chunk carries a cost its size does not shrink, the reading before its first commit, about 130k tokens, and its review passes, so `2**S` alone overrated tiny items. F is 8, about one S 3 change, until `todo.md` item 158 measures it.
|
||||
|
||||
2026-10-16, lilleman, ruling on the plan in PR #283: release 0.2.0 takes plan items 146, 152, 73, 50, 65, 84, 153 and 67, the split of `routing: one ladder`, and the question of how many chunks `score-outcomes` and the reading-cost trend wait for, ahead of their scores, to put budget and efficiency in the other projects first. A standing goal cannot capture that priority for now, so it is a one-time ruling: the later releases, and every release after 0.2.0, fill from the score again.
|
||||
|
||||
2026-10-18, lilleman. Serves goal 1.1: every project shares one achieve goal, code health, which `CLAUDE.md` → "Shared goal" states once and which replaces each project's own readability goal. It ranks first among a project's achieve goals, since lilleman rates it very important while the comprehension panel's overall is under 7.0. While that overall is under 7.0, or no scoring run has measured the project, it weighs four times its weight at 7.0 or above, as `UNDER_FLOOR` sets. The overall is the mean of the overall means of every scoring run on the newest scored commit in `docs/comprehension-history.md`, as `newest_scored` finds them. Two runs of one head measure it twice, and the newest alone would let their noise flip the weight: 7.13 and 6.88 on one head of another project would have. The review of PR #324 raised this choice. Weighing code health four times as much leaves the other achieve goals' weights as they are. So crossing 7.0 changes only the scores of the items that move code health, and of the defects, since a broken maintain goal weighs as the heaviest achieve goal. `larv-review record-scoring` re-ranks `todo.md` after it appends a run. A project that opts out of the comprehension check voids the goal, as `review: a project decision may opt every chunk out …` records. A README voids the goal with `**Void:** code health, since <reason>.` under `## Goals`, and an item's Moves cell names it as in `code health by 6`. A panel of three readers seated as lilleman picked both 3-0: `code health` over `code`, `health`, `C` and `0`, and the bold `Void:` line over a sentence under `## Goals` or a line under `## Audience`. The counter-signal is stated now and counted once `todo.md` item 198 ships, since no tool yet records why a finding arose. Valid while the comprehension panel's overall is how a project measures how hard it is to read.
|
||||
|
||||
2026-10-15, lilleman. Serves goal 1.4: loop-claude routes a chunk's first cycle on the item the chunk takes (`routing: a chunk's worker runs on the rung its item's L picks`). An item lists the items that must be done before it starts in a Blocked by column, and `rank_todo.py` ranks each blocker above every item it blocks. The table's order is `todo.md`'s only order: `rank_todo.py` fails on text beside the table under `## Items`, since a prose order there, "Release 0.3.0 takes items 125, 114 and 124 first", contradicted the table and loop-claude could not read it. A decision that wants an order sets the scores instead. An item waits while it is marked `question` or a blocker of it is still in the table, whatever the rows' order, so a release's first row that does not wait is the item a chunk takes. A blocker the table no longer holds was finished or deleted, and is dropped, so the cell shows what still blocks. A panel of three readers seated as lilleman picked the spelling: two ranked "Blocked by" first, as the cell lists only what still blocks, and all three chose bare IDs such as `12, 14` in a column right after Release, read before the tagline and kept apart from the scores. `rank_todo.py` adds the column to a table without it. The tools read cells by column name, so a later column leaves a reader on an older release working; `rank_todo.py`, which writes every column, fails on one it does not know rather than drop it.
|
||||
|
||||
2026-10-18, PR #312. Serves goals 1.5 and 1.1: adf-codec renamed its next release, 0.2.1, to 0.3.0, and `chunk-preflight` then called 0.2.1 finished and stopped the loop on every cycle. A change that moves a release's last items elsewhere reads the same whether it renamed the release or deferred its leftovers, so the plan says which: a `## Renamed` section holds one line `- 0.2.1 renamed to 0.3.0` per rename, which `bin/todo_table.py`'s `renames` reads. `chunk-preflight`, `loop-claude` and larv-review's scoring-run trigger skip a marked release; they read only the first version. A release whose items moved unmarked reads as finished: the loop stops, says so and names the fix, and the trigger calls a scoring run once work has landed. So a forgotten mark costs one interrupt and never lets a release end unmeasured. `rank_todo.py` fails on a line of another shape and on an item filed under a marked release, and a newest plan whose marks do not parse leaves the next release unknown. A line goes once a tag at or past its release is cut. Only a rename is marked, since an unmarked move is the deferral. A panel of three readers seated as lilleman picked the spelling 3-0 over `- 0.2.1 → 0.3.0` under `## Releases` and a `Renamed 0.2.1 = 0.3.0` line under `## Scoring`: plain words need no special character to type. Valid while a rename is the only move of a release's items that the tools must tell from finishing it.
|
||||
|
||||
@@ -7,4 +7,5 @@ paths:
|
||||
|
||||
- **Goals** state the project's aim and intent, not promises: one numbered line each, like slogans, in priority order; a sub-goal is indented under its goal — "1. Blazing fast performance. 2. Correctness is more important than many features." A goal names no step of the work, such as a check to run first, and rarely an implementation. How a goal is met goes in a method section further down the README and names the goal it serves. BANNED as a goal: `Kill weak candidates early, with the cheap checks first.` GOOD: the goal `Keep research on a budget, so it scales in both time and cost.`, with the cheap checks moved to the method section, naming that goal.
|
||||
- **Mark each goal `**Maintain:**` or `**Achieve:**`.** A maintain goal is a state to hold: a change that breaks it is redesigned or dropped, whatever its value to other goals. An achieve goal is a direction to pursue, weighed against the other achieve goals. Under each achieve goal, three indented bullets: `Signal:` what moving towards it looks like, `Counter-signal:` what shows it is bought at a wrong price, and `Why:` one line on how the two connect. A goal with sub-goals states its own signal. A maintain goal has no bullets. BANNED: an unmarked goal; an achieve goal with no signal; `**Achieve:** Delivery speed.` with the signal `faster`. GOOD: `**Achieve:** Delivery speed.` with `Signal: hours from a chunk's start to its merge fall.`, `Counter-signal: 🔴 findings per chunk rise.` and `Why: speed bought by skipping review shows up as defects.`
|
||||
- **Leave code health out of the README.** `~/.claude/CLAUDE.md` → "Shared goal" states it for every project, ranked first, and says when and how a README voids it. File an item to drop a README goal that restates it: the goals after it renumber, and every Moves cell and decision citing them must follow.
|
||||
- **Audience** names who depends on the project and what they may rely on.
|
||||
|
||||
+1
-1
@@ -20,7 +20,7 @@ paths:
|
||||
| 5 | — | — | irreversible: data lost for good, or a one-way door |
|
||||
|
||||
- **I's reach counts every project and session that runs the change.** A change to a hook or a tool that every session runs is I level 3, every consumer affected, even where one person uses it.
|
||||
- **Name in Moves each achieve goal in `README.md` → `## Goals` the item moves, and how far,** from 1 to 10, judged by its value to the audience in `## Audience`: `1.1 by 8, 1.2 by 5`. Name the most specific goal it moves, and a parent goal only for a move none of its sub-goals covers, never beside its own sub-goal. Leave out every maintain goal, which vetoes, except on an item marked `defect` that restores it: name that goal, and how much of it is broken. `rank_todo.py --help` says how it weighs each goal.
|
||||
- **Name in Moves each achieve goal in `README.md` → `## Goals` the item moves, and how far,** from 1 to 10, judged by its value to the audience in `## Audience`: `1.1 by 8, 1.2 by 5`. Where the item moves code health, the goal in `CLAUDE.md` → "Shared goal", name it as in `code health by 6`, unless the README voids it. Name the most specific goal it moves, and a parent goal only for a move none of its sub-goals covers, never beside its own sub-goal. Leave out every maintain goal, which vetoes, except on an item marked `defect` that restores it: name that goal, and how much of it is broken. `rank_todo.py --help` says how it weighs each goal.
|
||||
- **A table with C, A, G and Goals in place of L, E, I and Moves is in the old shape.** Reshaping it is the project's only work until done, as `CLAUDE.md` → "Working loop" says, and `rank_todo.py` says how. Until then, A is the item's value to the audience and G its value to the goals it cites.
|
||||
- **Score L, E and I against the project's anchors, and check every score against finished chunks.** Guess the scores, then run `~/.claude/bin/score-outcomes <L> <E> <I> <S>` in the project. It lists the finished items guessed nearest and the project's anchors, the shipped items its `docs/score-anchors.md` names for each level, each with what its chunk measured; then the median outcome at each guessed R and S, and how well L, E and I each order the chunks by review rounds and 🔴 findings. Compare the item with each anchor in turn: is it more or less likely to hold a defect, to let one escape, or to do damage? Give it the level whose anchors it matches; where a level has no anchor, judge by the level's words in the table above. Set S to the value guessed for the finished items whose outcome matches what you expect of this one. Keep your guess when no listed item resembles the one you are scoring.
|
||||
- **Anchor each level of L, E and I with two or three items the project shipped,** in `docs/score-anchors.md`: a table whose Level column names a level, such as `L 1`, and whose Items column lists the anchors' IDs, such as `12, 14`. Choose an L anchor whose chunk, as `score-outcomes` measured it, fits the level's words: its lines changed and the components it touched. Choose an E or I anchor by the level's words and what followed its release, since no tool measures either yet. Leave out a level no shipped item shows. Replace a level's anchors when the items scored at it turn out about ten times more likely, or ten times less likely, than its words say: to hold a defect, to let one escape, or to do damage.
|
||||
|
||||
@@ -57,7 +57,7 @@ Give a reviewer without Bash the branch diff and `git ls-files`'s output in its
|
||||
|
||||
**Opt-out** — for the architect, the product-owner pass and the comprehension check:
|
||||
|
||||
- **Entry.** A project opts out only through a `docs/decisions.md` entry, held before the chunk began, whose title opens `review opt-out:` and names one or more of the three. The entry names the project goal that skipping them serves.
|
||||
- **Entry.** A project opts out only through a `docs/decisions.md` entry, held before the chunk began, whose title opens `review opt-out:` and names one or more of the three. The entry names the project goal that skipping them serves. A project that opts out of the comprehension check voids code health in its README, as `~/.claude/CLAUDE.md` → "Shared goal" says; `rank_todo.py` refuses its plan until it does.
|
||||
- **Skip.** Every chunk skips each reviewer the entry names, even where its trigger, a 🔀 or a due scoring run calls for it, and the chunk's summary cites the entry. Unlike a suspension, an opt-out needs no plan item to end it.
|
||||
- **Malformed.** A title naming another reviewer, or an entry naming no goal, is a finding of the pass the chunk runs, and the chunk runs every pass its trigger fires.
|
||||
|
||||
@@ -102,7 +102,7 @@ Launch systems-architect: review the system as a whole entered through this chan
|
||||
|
||||
### Principles
|
||||
|
||||
Launch principles-auditor on the trigger in §3: one for the README's goals, and one per file in `~/.claude/principles/` whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff. A file without the line applies to every project. Unsure → launch it.
|
||||
Launch principles-auditor on the trigger in §3: one for the README's goals and code health (`~/.claude/CLAUDE.md` → "Shared goal") unless the README voids it, and one per file in `~/.claude/principles/` whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff. A file without the line applies to every project. Unsure → launch it.
|
||||
|
||||
### Comprehension check
|
||||
|
||||
@@ -120,7 +120,7 @@ The comprehension check records how hard the project is to read, and blocks no m
|
||||
- **Second run.** Where `needs-scoring-run` printed that the chunk `leaves release … with no plan item`, launch the same four seats afresh on the same head. Their scores file's first line is `<PR or branch> rerun at <commit>`. Record it with the same `record-scoring` command.
|
||||
- **Agreement.** After the second run, run `~/.claude/bin/larv-review agreement` and put its counts in the summary. On `Assumption fails:`, ask the user whether to keep the paired ruling or change the decision `review: the comprehension check records …`. Record the answer as a decision in the repo whose history was counted, with the counts that led to the ask. A later run asks again only when the rulings' rate falls, or the runs' rate rises, against the recorded counts.
|
||||
|
||||
**Record.** `docs/comprehension-history.md` keeps every paired ruling and scoring run, which `larv-review` appends; never edit one. Commit what it appends in one commit titled `Record the comprehension check: …`, push it, and wait for the forge's checks (§4 step 4), not for an auto-review; it re-enters no pass. Resolve a merge conflict in the file by putting the default branch's entries first. Put each ruling with its base and votes, and each run's five scores, in the summary.
|
||||
**Record.** `docs/comprehension-history.md` keeps every paired ruling and scoring run, which `larv-review` appends; never edit one. Commit what it appends, with the `todo.md` that `record-scoring` re-ranks, in one commit titled `Record the comprehension check: …`, push it, and wait for the forge's checks (§4 step 4), not for an auto-review; it re-enters no pass. Resolve a merge conflict in the file by putting the default branch's entries first. Put each ruling with its base and votes, and each run's five scores, in the summary.
|
||||
|
||||
**Places.** Give systems-architect and stability-reviewer what `~/.claude/bin/larv-review places` prints: the places seats found hard since the newest scored commit. Ask each to report, as a 🟡, each of those places the change touches without making it easier to read, matching a place by its path and the function or section it names, since its line may have moved. Fix such a 🟡, or say in the PR summary why not; that reason settles it in place of a decline's record.
|
||||
|
||||
@@ -160,7 +160,7 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
||||
|
||||
## 5. Goal alignment, then merge
|
||||
|
||||
1. Read the finished PR against the README goals: does anything in it work against one? It breaks a maintain goal → do not merge; redesign the change or drop its item. It works against an achieve goal → do not merge; ask the human, stating the conflict.
|
||||
1. Read the finished PR against the README goals and code health, unless the README voids it: does anything in it work against one? It breaks a maintain goal → do not merge; redesign the change or drop its item. It works against an achieve goal → do not merge; ask the human, stating the conflict.
|
||||
2. Run the comprehension check (§3) where it runs; it runs once. When `origin/<default branch>` moves after that, return to §4, and keep the ruling and scoring run already recorded.
|
||||
3. Aligned, every pass done and everything green → **merge**. Follow the repo's merge method (`AGENTS.md`; ff-only where that is the convention). A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it.
|
||||
4. Merged → remove the chunk's items from `todo.md` per `~/.claude/CLAUDE.md` → "Working loop".
|
||||
|
||||
@@ -6,106 +6,92 @@
|
||||
|
||||
`Bar = 0.1`
|
||||
|
||||
`Next ID = 198`
|
||||
`Next ID = 199`
|
||||
|
||||
## Items
|
||||
|
||||
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 189 | 0.2.0 | | | **State one achieve goal for the health of a project's code in `~/.claude`, which every project's ranking weighs, most while its comprehension panel's overall is under 7.0, unless its README voids it.** | 4 | 2 | 3 | 7 | 6 | 1.1 by 6 | 1.7 |
|
||||
| 29 | 0.3.0 | | | **Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.** | 2 | 2 | 3 | 5 | 2 | 1.1 by 5, 1.4 by 5 | 16.7 |
|
||||
| 119 | 0.3.0 | | | **Retitle the comprehension-floor decision so it says a chunk lifting a project towards the floor works first on its lowest-scoring dimension, and that the floor blocks nothing.** | 1 | 2 | 1 | 2 | 1 | 1.1 by 4, 1.4 by 4 | 16.0 |
|
||||
| 127 | 0.3.0 | | | **Define seat, place, paired ruling, scoring run and the judge's records in `CLAUDE.md` → "Vocabulary".** | 1 | 2 | 3 | 4 | 1 | 1.1 by 4, 1.4 by 4 | 16.0 |
|
||||
| 129 | 0.3.0 | | | **Explain `bin/rule_hook/rules.py`'s `OVERRIDE` pattern beside it: why the reason is lazy, what the lookahead splits and why `-->` is stripped.** | 1 | 2 | 1 | 2 | 1 | 1.1 by 4, 1.4 by 4 | 16.0 |
|
||||
| 114 | 0.3.0 | | decision | **Run git through `git_repo.py` in `rule_hook`, `metric_bench`, `reading_cost`, `review_replay` and `loop_claude`, keeping rule-hook's guards as an option, so one module owns how a tool runs git.** | 3 | 1 | 3 | 5 | 4 | 1.1 by 9, 1.4 by 9 | 15.0 |
|
||||
| 120 | 0.3.0 | | | **Rewrite larv-review §3's "Round cap" and "Re-entry" as one table that says, for each kind of fix, which passes rerun and what a round reviews.** | 2 | 2 | 3 | 5 | 4 | 1.1 by 6, 1.2 by 6, 1.4 by 6 | 15.0 |
|
||||
| 117 | 0.3.0 | | | **Give `todo_table.items` one way to say a plan has no items table, so no caller tells it from an empty plan by truthiness.** | 1 | 1 | 3 | 3 | 2 | 1.1 by 4, 1.4 by 4 | 13.3 |
|
||||
| 126 | 0.3.0 | | | **State when work has landed towards a release once, in `bin/larv_review/plan.py`, and have larv-review's help point to it.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 4, 1.4 by 4 | 13.3 |
|
||||
| 131 | 0.3.0 | | | **Describe the transcript archive's layout in `bin/transcript_archive/`, which owns it, and have loop-claude's help point there.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 4, 1.4 by 4 | 13.3 |
|
||||
| 133 | 0.3.0 | | | **Show, beside `bin/rule_hook/override_log.py`'s `this_chunks`, one example per case it decides: an amended or rebased commit, a renamed branch, and a commit on the default branch.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 4, 1.4 by 4 | 13.3 |
|
||||
| 134 | 0.3.0 | | | **Name in `bin/shell_command.py`'s `segments` the shell forms it does not parse, so a caller knows what it misses.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 4, 1.4 by 4 | 13.3 |
|
||||
| 157 | 0.3.0 | | | **Split `docs/decisions.md` → `todo.md: one table of items …`'s 2026-10-02 paragraph into one paragraph per choice.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 4, 1.4 by 4 | 13.3 |
|
||||
| 49 | 0.3.0 | | principle | **Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.** | 1 | 1 | 1 | 1 | 2 | 1.1 by 6 | 10.3 |
|
||||
| 106 | 0.3.0 | | | **Make larv-review's "Do not over-read a clean result" cite a rule that says Renovate or Dependabot owns dependency CVEs, or drop the citation.** | 1 | 2 | 1 | 2 | 1 | 1.1 by 5 | 10.3 |
|
||||
| 154 | 0.3.0 | | defect | **Have `bin/shell_command.py`'s `segments` keep a command's words together across a redirect, so `git > out commit` reads as one git commit.** | 1 | 1 | 3 | 3 | 2 | 1.1 by 6 | 10.3 |
|
||||
| 162 | 0.3.0 | | owner | **Script each step that 0.2.0's chunks repeated by hand and a program can compute, filing one item per step, and file this audit again for the next release.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 4, 1.5 by 4 | 9.5 |
|
||||
| 175 | 0.3.0 | | | **Compare the first five chunks loop-claude starts with `chunk-preflight` against the five before them, and file an item where the preflight did not pay off.** | 1 | 2 | 1 | 2 | 2 | 1.4 by 3, 1.5 by 3 | 9.5 |
|
||||
| 80 | 0.3.0 | | defect | **State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.** | 1 | 2 | 1 | 2 | 1 | 2 by 4 | 8.5 |
|
||||
| 176 | 0.3.0 | | | **Give `loop-claude --help`'s routing paragraph sub-headings, such as Routing, Judge rung and Routing figures, so a reader finds a rule without reading 39 lines.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 3, 1.4 by 2 | 8.4 |
|
||||
| 186 | 0.3.0 | | | **Point every file a session parks outside its checkout, such as the comprehension panel's detached worktree and a build probe's output, at a folder a headless session has, since loop-claude's sessions have no scratchpad.** | 1 | 2 | 2 | 3 | 2 | 1.1 by 3, 1.5 by 2 | 8.3 |
|
||||
| 172 | 0.3.0 | | | **Name the project's rung `project` across `bin/loop_claude`, in place of `anchor`, as `bin/model_routing/ladder.py` names it.** | 2 | 1 | 3 | 4 | 3 | 1.1 by 3, 1.4 by 3 | 7.5 |
|
||||
| 167 | 0.3.0 | | | **Refuse a `/security-review` or `/claude-security` Skill call below the project's rung, as rule-hook refuses such an Agent call.** | 3 | 2 | 3 | 6 | 2 | 1.1 by 4 | 6.9 |
|
||||
| 82 | 0.3.0 | | principle | **Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.** | 2 | 2 | 1 | 3 | 4 | 1.1 by 4, 1.4 by 4 | 6.7 |
|
||||
| 173 | 0.3.0 | | | **Have rule-hook's `todo-rank-check` run a worktree's own `bin/rank_todo.py` when the worktree is of this repo, so a branch that changes `todo.md`'s shape commits without an override.** | 2 | 1 | 3 | 4 | 2 | 1.1 by 2, 1.4 by 2 | 6.7 |
|
||||
| 21 | 0.3.0 | | defect | **Give `settings.json`'s model one writer, and sort its keys.** | 3 | 3 | 3 | 7 | 3 | 2 by 5 | 6.6 |
|
||||
| 190 | 0.3.0 | | | **Rewrite the `docs/decisions.md` entries `todo.md: one table …` and `loop-claude: a judge decides …` as the current state, so a reader no longer replays superseded paragraphs to learn what holds.** | 2 | 2 | 1 | 3 | 3 | 1.1 by 3, 1.4 by 2 | 6.3 |
|
||||
| 171 | 0.3.0 | | decision | **Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.** | 3 | 2 | 2 | 5 | 4 | 1.2 by 3, 1.4 by 3 | 4.9 |
|
||||
| 196 | 0.3.0 | | decision | **Replay the architecture, principles, overrides and product-owner passes with `review-replay` on Opus 5.5 projects, record each run in the review-replay routing decision, and add any rung a run qualifies to `REPLAYED`.** | 2 | 2 | 3 | 5 | 2 | 1.4 by 3 | 4.8 |
|
||||
| 181 | 0.3.0 | | principle | **Have the test of a quoted answer's step-up assert the stepped rung's facts as literals, not through `prompts.rungs_held`.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 2 | 4.1 |
|
||||
| 192 | 0.3.0 | | principle | **Sort `.gitignore`'s allowlist block, from `!.claude/` to `!workflow-bench/test_review_git.py`, by code point, so rule-hook's `ignorefile-sorted` checks later edits to it again.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 2 | 4.1 |
|
||||
| 193 | 0.3.0 | | | **Narrow `readme_goals`'s mark to `Mark` by a typed lookup in place of `typing.cast`, so a mark added to the regex but not the lookup fails at run time, and one added to the lookup but not `Mark` fails mypy.** | 1 | 1 | 3 | 3 | 1 | 1.1 by 2 | 4.1 |
|
||||
| 194 | 0.3.0 | | | **Make `test_waits_out_a_usage_limit_which_ends_a_run_of_failures` expect a usage-limit wait independent of the wall-clock time that passes during the run.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 2 | 4.1 |
|
||||
| 187 | 0.3.0 | | | **Count the tokens a worker spends reading reviewers' reports, so goal 1.4's signal shows whether report files lowered what a review costs the worker's context.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 3 | 3.6 |
|
||||
| 165 | 0.3.0 | | | **Make this repo's tests assert the facts a prompt or help text carries in place of its sentences, and drop the tests that scan source or assert a constant.** | 3 | 2 | 1 | 4 | 5 | 1.1 by 4, 1.4 by 3 | 3.5 |
|
||||
| 182 | 0.3.0 | | | **Let the human edit an interrupt's answer with the arrow keys, so Left moves the cursor instead of typing ^[[D into the answer.** | 2 | 2 | 1 | 3 | 2 | 1.1 by 2 | 3.4 |
|
||||
| 169 | 0.3.0 | | | **Have rule-hook's `todo-rank-check` catch a `todo.md` that the same Bash call edits and then commits.** | 3 | 1 | 3 | 5 | 3 | 1.1 by 2 | 2.6 |
|
||||
| 183 | 0.3.0 | | | **Merge the two 2026-10-13 paragraphs of `docs/decisions.md` → `loop-claude: a judge decides each interrupt …` into one.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 1 | 2.1 |
|
||||
| 184 | 0.3.0 | | | **Rewrap the lines of `loop-claude --help` that run past the column the rest of it wraps at.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 1 | 2.1 |
|
||||
| 197 | 0.3.0 | | | **Let the human edit what they type at loop-claude's terminal questions with the arrow keys, so Left moves the cursor in place of printing `^[[D`.** | 1 | 2 | 3 | 4 | 1 | 1.5 by 1 | 1.9 |
|
||||
| 174 | 0.3.0 | | | **In a chunk no item routed, ask the worker to name each todo.md item it takes, with its L and E + I, so loop-claude can route on an item it takes in.** | 1 | 2 | 3 | 4 | 2 | 1.1 by 1 | 1.7 |
|
||||
| 170 | 0.4.0 | | decision | **Re-tune `WORKER_STEPS` and `REVIEW_STEPS` once 10 chunks have shipped under them, from how well L, E and I order their review rounds and 🔴 findings.** | 2 | 2 | 3 | 5 | 2 | 1.1 by 3, 1.4 by 5 | 13.2 |
|
||||
| 122 | 0.4.0 | | | **Assemble the judge's prompt in `bin/loop_claude/cycle/judge.py`, importing only wording the worker also sees, and call the worker "the worker" in it.** | 2 | 2 | 3 | 5 | 3 | 1.1 by 5, 1.4 by 5 | 12.5 |
|
||||
| 158 | 0.4.0 | | decision | **Measure the fixed cost of a chunk from loop-claude's archive, in tokens and hours against its items' S, and set F in `Score = 100 * V / (2**S + F)` to it.** | 2 | 2 | 1 | 3 | 3 | 1.1 by 5, 1.4 by 5 | 12.5 |
|
||||
| 130 | 0.4.0 | | | **Move the vote counting out of `bin/larv_review/ruling.py`'s `votes`, so reading a votes file decides nothing.** | 2 | 1 | 2 | 3 | 3 | 1.1 by 4, 1.4 by 4 | 10.0 |
|
||||
| 125 | 0.4.0 | | decision | **Give "record", "outcome" and "places" one meaning each across `bin/`, and rename `bin/larv_review/git.py` by what it holds.** | 3 | 1 | 3 | 5 | 5 | 1.1 by 9, 1.4 by 9 | 9.0 |
|
||||
| 116 | 0.4.0 | | | **Report L by the share of chunks with a 🔴, once 10 chunks that each shipped one item record finding counts and most record no 🔴.** | 1 | 1 | 2 | 2 | 2 | 1.1 by 5 | 8.6 |
|
||||
| 121 | 0.4.0 | | | **Check that `bin/round_titles.py`'s `PASSES` lists exactly the passes of larv-review §3's table.** | 1 | 1 | 1 | 1 | 2 | 1.1 by 5 | 8.6 |
|
||||
| 113 | 0.4.0 | | | **Compute an item's S from the code it names, where it names any, and show it beside the finished items `score-outcomes` lists.** | 3 | 2 | 2 | 5 | 4 | 1.1 by 5, 1.4 by 5 | 8.3 |
|
||||
| 112 | 0.4.0 | | | **Count an item as shipped only where its chunk built it, so an item a chunk dropped from the plan gets no outcome.** | 3 | 2 | 2 | 5 | 3 | 1.1 by 6 | 7.7 |
|
||||
| 81 | 0.4.0 | | principle | **Have `workflow-bench/bench.py` return each run's failure as a value, so one failed clone does not hide the later runs' results.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 4 | 6.9 |
|
||||
| 102 | 0.4.0 | | | **Give loop-claude's retry delay an environment override, so the black-box test stops replacing `time.sleep` through `sitecustomize`.** | 1 | 1 | 2 | 2 | 2 | 1.1 by 4 | 6.9 |
|
||||
| 137 | 0.4.0 | | | **Archive a chunk's route as a record loop-claude reads back field by field, in place of the `Worker:` prose `ROUTED` parses, and name `stepped` and the judge's `bundled` by what they do.** | 4 | 2 | 3 | 7 | 4 | 1.1 by 4, 1.4 by 4 | 6.7 |
|
||||
| 66 | 0.4.0 | | principle | **Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.** | 2 | 2 | 3 | 5 | 3 | 1.1 by 5 | 6.4 |
|
||||
| 101 | 0.4.0 | | principle | **Have `larv_review/record.py`'s `read_seats` take the time, the commit check and the history as inputs, so it parses and decides without effects.** | 2 | 1 | 2 | 3 | 3 | 1.1 by 5 | 6.4 |
|
||||
| 111 | 0.4.0 | | | **Measure the chunks of a project that merges by squash or fast-forward, which `score-outcomes` skips today.** | 3 | 2 | 2 | 5 | 3 | 1.1 by 5 | 6.4 |
|
||||
| 110 | 0.4.0 | | | **Count, for each finished chunk, the later changes that fixed code it wrote, and show them beside its guessed E.** | 3 | 2 | 2 | 5 | 5 | 1.1 by 6, 1.4 by 6 | 6.0 |
|
||||
| 139 | 0.4.0 | | | **Split `bin/routing_figures/measure.py` by concern, and keep the figures' measured cycle and each raised call as fields loop-claude reads back, not as the prose it renders.** | 3 | 1 | 2 | 4 | 5 | 1.1 by 5, 1.4 by 5 | 5.0 |
|
||||
| 149 | 0.4.0 | | decision | **Fill each release by priority up to a capacity it states, in place of the bar, and move what does not fit to a later release.** | 4 | 2 | 3 | 7 | 5 | 1.1 by 7 | 3.6 |
|
||||
| 105 | 0.5.0 | | decision | **Compare review rounds per pass and reading cost for the five chunks before and after the `worker:` decision moved the principles out of the worker's context, and file an item if either rose.** | 1 | 2 | 1 | 2 | 2 | 1.4 by 6 | 9.7 |
|
||||
| 59 | 0.5.0 | | | **Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.** | 2 | 1 | 3 | 4 | 3 | 1.4 by 6 | 7.3 |
|
||||
| 12 | 0.5.0 | | | **Run the test suite in CI on every PR, or record in `docs/decisions.md` why the local run is enough.** | 3 | 2 | 1 | 4 | 4 | 1.1 by 6 | 5.1 |
|
||||
| 135 | 0.5.0 | | | **Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop.** | 2 | 2 | 3 | 5 | 3 | 1.1 by 4 | 5.1 |
|
||||
| 123 | 0.5.0 | | | **Have `bin/comprehension_history.py` parse each history entry once into seats, votes and places, so `latest_places`, `worse_places` and `worse_votes` neither depend on table order nor split a label to find a seat.** | 2 | 1 | 2 | 3 | 5 | 1.1 by 5, 1.4 by 5 | 5.0 |
|
||||
| 124 | 0.5.0 | | decision | **Group the shared modules at `bin/`'s root into packages named by purpose, so the root holds only launchers and stand-alone tools.** | 4 | 1 | 3 | 6 | 6 | 1.1 by 9, 1.4 by 9 | 5.0 |
|
||||
| 132 | 0.5.0 | | | **Lift each dimension still under the comprehension floor after release 0.2.0's scoring run, at the places that run names.** | 3 | 2 | 2 | 5 | 5 | 1.1 by 5, 1.4 by 5 | 5.0 |
|
||||
| 68 | 0.5.0 | | principle | **Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.** | 2 | 1 | 1 | 2 | 4 | 1.1 by 5 | 4.3 |
|
||||
| 4 | 0.5.0 | | | **Name each chunk's archive folder by the chunk's start time, so `<key>/` lists chunks in the order they ran.** | 3 | 2 | 3 | 6 | 3 | 1.1 by 3 | 3.9 |
|
||||
| 156 | 0.5.0 | | decision | **Drop `rank_todo.py`'s ranking of an old-shape table once no project under `~/code` holds one.** | 2 | 1 | 3 | 4 | 4 | 1.1 by 4 | 3.4 |
|
||||
| 155 | 0.5.0 | | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 3 | 2 | 2 | 5 | 5 | 1.4 by 6 | 2.9 |
|
||||
| 119 | 0.3.0 | | | **Retitle the comprehension-floor decision so it says a chunk lifting a project towards the floor works first on its lowest-scoring dimension, and that the floor blocks nothing.** | 1 | 2 | 1 | 2 | 1 | code health by 4, 1.4 by 4 | 35.1 |
|
||||
| 127 | 0.3.0 | | | **Define seat, place, paired ruling, scoring run and the judge's records in `CLAUDE.md` → "Vocabulary".** | 1 | 2 | 3 | 4 | 1 | code health by 4, 1.4 by 4 | 35.1 |
|
||||
| 129 | 0.3.0 | | | **Explain `bin/rule_hook/rules.py`'s `OVERRIDE` pattern beside it: why the reason is lazy, what the lookahead splits and why `-->` is stripped.** | 1 | 2 | 1 | 2 | 1 | code health by 4, 1.4 by 4 | 35.1 |
|
||||
| 114 | 0.3.0 | | decision | **Run git through `git_repo.py` in `rule_hook`, `metric_bench`, `reading_cost`, `review_replay` and `loop_claude`, keeping rule-hook's guards as an option, so one module owns how a tool runs git.** | 3 | 1 | 3 | 5 | 4 | code health by 9, 1.4 by 9 | 32.9 |
|
||||
| 117 | 0.3.0 | | | **Give `todo_table.items` one way to say a plan has no items table, so no caller tells it from an empty plan by truthiness.** | 1 | 1 | 3 | 3 | 2 | code health by 4, 1.4 by 4 | 29.2 |
|
||||
| 126 | 0.3.0 | | | **State when work has landed towards a release once, in `bin/larv_review/plan.py`, and have larv-review's help point to it.** | 1 | 2 | 1 | 2 | 2 | code health by 4, 1.4 by 4 | 29.2 |
|
||||
| 131 | 0.3.0 | | | **Describe the transcript archive's layout in `bin/transcript_archive/`, which owns it, and have loop-claude's help point there.** | 1 | 2 | 1 | 2 | 2 | code health by 4, 1.4 by 4 | 29.2 |
|
||||
| 133 | 0.3.0 | | | **Show, beside `bin/rule_hook/override_log.py`'s `this_chunks`, one example per case it decides: an amended or rebased commit, a renamed branch, and a commit on the default branch.** | 1 | 2 | 1 | 2 | 2 | code health by 4, 1.4 by 4 | 29.2 |
|
||||
| 134 | 0.3.0 | | | **Name in `bin/shell_command.py`'s `segments` the shell forms it does not parse, so a caller knows what it misses.** | 1 | 2 | 1 | 2 | 2 | code health by 4, 1.4 by 4 | 29.2 |
|
||||
| 157 | 0.3.0 | | | **Split `docs/decisions.md` → `todo.md: one table of items …`'s 2026-10-02 paragraph into one paragraph per choice.** | 1 | 2 | 1 | 2 | 2 | code health by 4, 1.4 by 4 | 29.2 |
|
||||
| 80 | 0.3.0 | | defect | **State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.** | 1 | 2 | 1 | 2 | 1 | 2 by 4 | 28.7 |
|
||||
| 120 | 0.3.0 | | | **Rewrite larv-review §3's "Round cap" and "Re-entry" as one table that says, for each kind of fix, which passes rerun and what a round reviews.** | 2 | 2 | 3 | 5 | 4 | code health by 6, 1.2 by 6, 1.4 by 6 | 26.0 |
|
||||
| 21 | 0.3.0 | | defect | **Give `settings.json`'s model one writer, and sort its keys.** | 3 | 3 | 3 | 7 | 3 | 2 by 5 | 22.5 |
|
||||
| 176 | 0.3.0 | | | **Give `loop-claude --help`'s routing paragraph sub-headings, such as Routing, Judge rung and Routing figures, so a reader finds a rule without reading 39 lines.** | 1 | 2 | 1 | 2 | 2 | code health by 3, 1.4 by 2 | 20.6 |
|
||||
| 172 | 0.3.0 | | | **Name the project's rung `project` across `bin/loop_claude`, in place of `anchor`, as `bin/model_routing/ladder.py` names it.** | 2 | 1 | 3 | 4 | 3 | code health by 3, 1.4 by 3 | 16.5 |
|
||||
| 190 | 0.3.0 | | | **Rewrite the `docs/decisions.md` entries `todo.md: one table …` and `loop-claude: a judge decides …` as the current state, so a reader no longer replays superseded paragraphs to learn what holds.** | 2 | 2 | 1 | 3 | 3 | code health by 3, 1.4 by 2 | 15.5 |
|
||||
| 82 | 0.3.0 | | principle | **Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.** | 2 | 2 | 1 | 3 | 4 | code health by 4, 1.4 by 4 | 14.6 |
|
||||
| 29 | 0.3.0 | | | **Make the contributor a standing member of every project's audience, unless its README voids code health.** | 2 | 2 | 3 | 5 | 2 | 1.1 by 5, 1.4 by 5 | 13.7 |
|
||||
| 106 | 0.3.0 | | | **Make larv-review's "Do not over-read a clean result" cite a rule that says Renovate or Dependabot owns dependency CVEs, or drop the citation.** | 1 | 2 | 1 | 2 | 1 | 1.1 by 5 | 8.4 |
|
||||
| 49 | 0.3.0 | | principle | **Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.** | 1 | 1 | 1 | 1 | 2 | 1.1 by 6 | 8.4 |
|
||||
| 154 | 0.3.0 | | defect | **Have `bin/shell_command.py`'s `segments` keep a command's words together across a redirect, so `git > out commit` reads as one git commit.** | 1 | 1 | 3 | 3 | 2 | 1.1 by 6 | 8.4 |
|
||||
| 162 | 0.3.0 | | owner | **Script each step that 0.2.0's chunks repeated by hand and a program can compute, filing one item per step, and file this audit again for the next release.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 4, 1.5 by 4 | 7.8 |
|
||||
| 175 | 0.3.0 | | | **Compare the first five chunks loop-claude starts with `chunk-preflight` against the five before them, and file an item where the preflight did not pay off.** | 1 | 2 | 1 | 2 | 2 | 1.4 by 3, 1.5 by 3 | 7.8 |
|
||||
| 183 | 0.3.0 | | | **Merge the two 2026-10-13 paragraphs of `docs/decisions.md` → `loop-claude: a judge decides each interrupt …` into one.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 7.2 |
|
||||
| 184 | 0.3.0 | | | **Rewrap the lines of `loop-claude --help` that run past the column the rest of it wraps at.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 7.2 |
|
||||
| 186 | 0.3.0 | | | **Point every file a session parks outside its checkout, such as the comprehension panel's detached worktree and a build probe's output, at a folder a headless session has, since loop-claude's sessions have no scratchpad.** | 1 | 2 | 2 | 3 | 2 | 1.1 by 3, 1.5 by 2 | 6.8 |
|
||||
| 198 | 0.3.0 | | decision | **Count, per finished chunk, the findings that arose from misreading code that had already shipped, so code health's counter-signal shows.** | 3 | 2 | 2 | 5 | 5 | code health by 3, 1.1 by 2 | 6.2 |
|
||||
| 167 | 0.3.0 | | | **Refuse a `/security-review` or `/claude-security` Skill call below the project's rung, as rule-hook refuses such an Agent call.** | 3 | 2 | 3 | 6 | 2 | 1.1 by 4 | 5.6 |
|
||||
| 173 | 0.3.0 | | | **Have rule-hook's `todo-rank-check` run a worktree's own `bin/rank_todo.py` when the worktree is of this repo, so a branch that changes `todo.md`'s shape commits without an override.** | 2 | 1 | 3 | 4 | 2 | 1.1 by 2, 1.4 by 2 | 5.5 |
|
||||
| 171 | 0.3.0 | | decision | **Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.** | 3 | 2 | 2 | 5 | 4 | 1.2 by 3, 1.4 by 3 | 4.0 |
|
||||
| 196 | 0.3.0 | | decision | **Replay the architecture, principles, overrides and product-owner passes with `review-replay` on Opus 5.5 projects, record each run in the review-replay routing decision, and add any rung a run qualifies to `REPLAYED`.** | 2 | 2 | 3 | 5 | 2 | 1.4 by 3 | 4.0 |
|
||||
| 181 | 0.3.0 | | principle | **Have the test of a quoted answer's step-up assert the stepped rung's facts as literals, not through `prompts.rungs_held`.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 2 | 3.4 |
|
||||
| 192 | 0.3.0 | | principle | **Sort `.gitignore`'s allowlist block, from `!.claude/` to `!workflow-bench/test_review_git.py`, by code point, so rule-hook's `ignorefile-sorted` checks later edits to it again.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 2 | 3.4 |
|
||||
| 193 | 0.3.0 | | | **Narrow `readme_goals`'s mark to `Mark` by a typed lookup in place of `typing.cast`, so a mark added to the regex but not the lookup fails at run time, and one added to the lookup but not `Mark` fails mypy.** | 1 | 1 | 3 | 3 | 1 | 1.1 by 2 | 3.4 |
|
||||
| 194 | 0.3.0 | | | **Make `test_waits_out_a_usage_limit_which_ends_a_run_of_failures` expect a usage-limit wait independent of the wall-clock time that passes during the run.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 2 | 3.4 |
|
||||
| 187 | 0.3.0 | | | **Count the tokens a worker spends reading reviewers' reports, so goal 1.4's signal shows whether report files lowered what a review costs the worker's context.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 3 | 3.0 |
|
||||
| 165 | 0.3.0 | | | **Make this repo's tests assert the facts a prompt or help text carries in place of its sentences, and drop the tests that scan source or assert a constant.** | 3 | 2 | 1 | 4 | 5 | 1.1 by 4, 1.4 by 3 | 2.9 |
|
||||
| 182 | 0.3.0 | | | **Let the human edit an interrupt's answer with the arrow keys, so Left moves the cursor instead of typing ^[[D into the answer.** | 2 | 2 | 1 | 3 | 2 | 1.1 by 2 | 2.8 |
|
||||
| 155 | 0.3.0 | | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 3 | 2 | 2 | 5 | 5 | 1.4 by 6 | 2.4 |
|
||||
| 169 | 0.3.0 | | | **Have rule-hook's `todo-rank-check` catch a `todo.md` that the same Bash call edits and then commits.** | 3 | 1 | 3 | 5 | 3 | 1.1 by 2 | 2.1 |
|
||||
| 197 | 0.3.0 | | | **Let the human edit what they type at loop-claude's terminal questions with the arrow keys, so Left moves the cursor in place of printing `^[[D`.** | 1 | 2 | 3 | 4 | 1 | 1.5 by 1 | 1.5 |
|
||||
| 174 | 0.3.0 | | | **In a chunk no item routed, ask the worker to name each todo.md item it takes, with its L and E + I, so loop-claude can route on an item it takes in.** | 1 | 2 | 3 | 4 | 2 | 1.1 by 1 | 1.4 |
|
||||
| 122 | 0.4.0 | | | **Assemble the judge's prompt in `bin/loop_claude/cycle/judge.py`, importing only wording the worker also sees, and call the worker "the worker" in it.** | 2 | 2 | 3 | 5 | 3 | code health by 5, 1.4 by 5 | 27.4 |
|
||||
| 130 | 0.4.0 | | | **Move the vote counting out of `bin/larv_review/ruling.py`'s `votes`, so reading a votes file decides nothing.** | 2 | 1 | 2 | 3 | 3 | code health by 4, 1.4 by 4 | 21.9 |
|
||||
| 125 | 0.4.0 | | decision | **Give "record", "outcome" and "places" one meaning each across `bin/`, and rename `bin/larv_review/git.py` by what it holds.** | 3 | 1 | 3 | 5 | 5 | code health by 9, 1.4 by 9 | 19.7 |
|
||||
| 137 | 0.4.0 | | | **Archive a chunk's route as a record loop-claude reads back field by field, in place of the `Worker:` prose `ROUTED` parses, and name `stepped` and the judge's `bundled` by what they do.** | 4 | 2 | 3 | 7 | 4 | code health by 4, 1.4 by 4 | 14.6 |
|
||||
| 139 | 0.4.0 | | | **Split `bin/routing_figures/measure.py` by concern, and keep the figures' measured cycle and each raised call as fields loop-claude reads back, not as the prose it renders.** | 3 | 1 | 2 | 4 | 5 | code health by 5, 1.4 by 5 | 11.0 |
|
||||
| 170 | 0.4.0 | | decision | **Re-tune `WORKER_STEPS` and `REVIEW_STEPS` once 10 chunks have shipped under them, from how well L, E and I order their review rounds and 🔴 findings.** | 2 | 2 | 3 | 5 | 2 | 1.1 by 3, 1.4 by 5 | 10.9 |
|
||||
| 158 | 0.4.0 | | decision | **Measure the fixed cost of a chunk from loop-claude's archive, in tokens and hours against its items' S, and set F in `Score = 100 * V / (2**S + F)` to it.** | 2 | 2 | 1 | 3 | 3 | 1.1 by 5, 1.4 by 5 | 10.3 |
|
||||
| 116 | 0.4.0 | | | **Report L by the share of chunks with a 🔴, once 10 chunks that each shipped one item record finding counts and most record no 🔴.** | 1 | 1 | 2 | 2 | 2 | 1.1 by 5 | 7.0 |
|
||||
| 121 | 0.4.0 | | | **Check that `bin/round_titles.py`'s `PASSES` lists exactly the passes of larv-review §3's table.** | 1 | 1 | 1 | 1 | 2 | 1.1 by 5 | 7.0 |
|
||||
| 113 | 0.4.0 | | | **Compute an item's S from the code it names, where it names any, and show it beside the finished items `score-outcomes` lists.** | 3 | 2 | 2 | 5 | 4 | 1.1 by 5, 1.4 by 5 | 6.8 |
|
||||
| 112 | 0.4.0 | | | **Count an item as shipped only where its chunk built it, so an item a chunk dropped from the plan gets no outcome.** | 3 | 2 | 2 | 5 | 3 | 1.1 by 6 | 6.3 |
|
||||
| 81 | 0.4.0 | | principle | **Have `workflow-bench/bench.py` return each run's failure as a value, so one failed clone does not hide the later runs' results.** | 1 | 2 | 1 | 2 | 2 | 1.1 by 4 | 5.6 |
|
||||
| 102 | 0.4.0 | | | **Give loop-claude's retry delay an environment override, so the black-box test stops replacing `time.sleep` through `sitecustomize`.** | 1 | 1 | 2 | 2 | 2 | 1.1 by 4 | 5.6 |
|
||||
| 66 | 0.4.0 | | principle | **Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.** | 2 | 2 | 3 | 5 | 3 | 1.1 by 5 | 5.3 |
|
||||
| 101 | 0.4.0 | | principle | **Have `larv_review/record.py`'s `read_seats` take the time, the commit check and the history as inputs, so it parses and decides without effects.** | 2 | 1 | 2 | 3 | 3 | 1.1 by 5 | 5.3 |
|
||||
| 111 | 0.4.0 | | | **Measure the chunks of a project that merges by squash or fast-forward, which `score-outcomes` skips today.** | 3 | 2 | 2 | 5 | 3 | 1.1 by 5 | 5.3 |
|
||||
| 110 | 0.4.0 | | | **Count, for each finished chunk, the later changes that fixed code it wrote, and show them beside its guessed E.** | 3 | 2 | 2 | 5 | 5 | 1.1 by 6, 1.4 by 6 | 4.9 |
|
||||
| 149 | 0.4.0 | | decision | **Fill each release by priority up to a capacity it states, in place of the bar, and move what does not fit to a later release.** | 4 | 2 | 3 | 7 | 5 | 1.1 by 7 | 3.0 |
|
||||
| 123 | 0.5.0 | | | **Have `bin/comprehension_history.py` parse each history entry once into seats, votes and places, so `latest_places`, `worse_places` and `worse_votes` neither depend on table order nor split a label to find a seat.** | 2 | 1 | 2 | 3 | 5 | code health by 5, 1.4 by 5 | 11.0 |
|
||||
| 124 | 0.5.0 | | decision | **Group the shared modules at `bin/`'s root into packages named by purpose, so the root holds only launchers and stand-alone tools.** | 4 | 1 | 3 | 6 | 6 | code health by 9, 1.4 by 9 | 11.0 |
|
||||
| 132 | 0.5.0 | | | **Lift each dimension still under the comprehension floor after release 0.2.0's scoring run, at the places that run names.** | 3 | 2 | 2 | 5 | 5 | code health by 5, 1.4 by 5 | 11.0 |
|
||||
| 105 | 0.5.0 | | decision | **Compare review rounds per pass and reading cost for the five chunks before and after the `worker:` decision moved the principles out of the worker's context, and file an item if either rose.** | 1 | 2 | 1 | 2 | 2 | 1.4 by 6 | 8.0 |
|
||||
| 59 | 0.5.0 | | | **Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.** | 2 | 1 | 3 | 4 | 3 | 1.4 by 6 | 6.0 |
|
||||
| 12 | 0.5.0 | | | **Run the test suite in CI on every PR, or record in `docs/decisions.md` why the local run is enough.** | 3 | 2 | 1 | 4 | 4 | 1.1 by 6 | 4.2 |
|
||||
| 135 | 0.5.0 | | | **Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop.** | 2 | 2 | 3 | 5 | 3 | 1.1 by 4 | 4.2 |
|
||||
| 68 | 0.5.0 | | principle | **Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.** | 2 | 1 | 1 | 2 | 4 | 1.1 by 5 | 3.5 |
|
||||
| 4 | 0.5.0 | | | **Name each chunk's archive folder by the chunk's start time, so `<key>/` lists chunks in the order they ran.** | 3 | 2 | 3 | 6 | 3 | 1.1 by 3 | 3.2 |
|
||||
| 156 | 0.5.0 | | decision | **Drop `rank_todo.py`'s ranking of an old-shape table once no project under `~/code` holds one.** | 2 | 1 | 3 | 4 | 4 | 1.1 by 4 | 2.8 |
|
||||
| 1 | 0.6.0 | | question | **Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.** | 1 | 2 | 1 | 2 | 1 | | 0.0 |
|
||||
| 6 | 0.6.0 | | decision | **Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.** | 3 | 3 | 3 | 7 | 3 | 1.1 by 5 | 6.4 |
|
||||
| 77 | 0.6.0 | | | **Teach `bin/metric-bench` Go and TypeScript, rerun it once two projects' comprehension histories name places, and bring into review only a metric that tracks the panel.** | 4 | 2 | 1 | 5 | 6 | 1.1 by 7, 1.4 by 7 | 3.9 |
|
||||
| 151 | 0.6.0 | | decision | **Keep 10 to 20 settled decisions per project as its goals' test set, and rerun them after a goal changes.** | 3 | 2 | 2 | 5 | 5 | 1.2 by 7 | 3.5 |
|
||||
| 5 | 0.6.0 | | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 4 | 2 | 3 | 7 | 5 | 1.1 by 6 | 3.1 |
|
||||
| 51 | 0.6.0 | | principle | **Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.** | 2 | 1 | 3 | 4 | 5 | 1.1 by 5 | 2.6 |
|
||||
| 52 | 0.6.0 | | principle | **Record why this checkout lives in Claude Code's own directory, or move it out and link it in.** | 4 | 3 | 4 | 9 | 6 | 1.1 by 4 | 1.1 |
|
||||
| 6 | 0.6.0 | | decision | **Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.** | 3 | 3 | 3 | 7 | 3 | 1.1 by 5 | 5.3 |
|
||||
| 77 | 0.6.0 | | | **Teach `bin/metric-bench` Go and TypeScript, rerun it once two projects' comprehension histories name places, and bring into review only a metric that tracks the panel.** | 4 | 2 | 1 | 5 | 6 | 1.1 by 7, 1.4 by 7 | 3.2 |
|
||||
| 151 | 0.6.0 | | decision | **Keep 10 to 20 settled decisions per project as its goals' test set, and rerun them after a goal changes.** | 3 | 2 | 2 | 5 | 5 | 1.2 by 7 | 2.9 |
|
||||
| 5 | 0.6.0 | | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 4 | 2 | 3 | 7 | 5 | 1.1 by 6 | 2.5 |
|
||||
| 51 | 0.6.0 | | principle | **Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.** | 2 | 1 | 3 | 4 | 5 | 1.1 by 5 | 2.1 |
|
||||
| 52 | 0.6.0 | | principle | **Record why this checkout lives in Claude Code's own directory, or move it out and link it in.** | 4 | 3 | 4 | 9 | 6 | 1.1 by 4 | 0.9 |
|
||||
|
||||
## Details
|
||||
|
||||
### 189. State one achieve goal for the health of a project's code in `~/.claude`, which every project's ranking weighs, most while its comprehension panel's overall is under 7.0, unless its README voids it.
|
||||
|
||||
lilleman, 2026-10-18: every project shares the goal, so it lives in `~/.claude` once, and a project for which it is not relevant voids it explicitly in its README. It replaces each project's own readability goal, such as fejkdata's goal 3, visthus's goal 8 and adf-codec's goal 10: once it merges, file an item in each such project's `todo.md` to drop its own goal, since a project's Blocked by cannot name an item of this repo.
|
||||
|
||||
- Signal: the comprehension panel's overall score rises, always. Under 7.0 it is very important.
|
||||
- Counter-signal: defects keep reappearing in functionality that already shipped, or reviewers raise blockers because the implementer misunderstood the current system.
|
||||
- Not a counter-signal: fewer items shipped per release. Getting the design and architecture right can be expensive, and that is fine when the goal is a maintainable project.
|
||||
|
||||
The chunk settles, with lilleman: where the goal ranks among a project's own goals, how much more it weighs while the overall is under 7.0, how a README spells voiding it, and how the counter-signal is counted, since no tool records why a reviewer's finding arose. Revise the decision entry of 2026-10-16 answering the review of PR #283, which left a goal of its own for readability for later. Reading the latest overall touches `latest_places` in `bin/comprehension_history.py`, which the comprehension seats found hard: make it easier to read where the change touches it.
|
||||
|
||||
### 29. Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.
|
||||
|
||||
State that in `~/.claude/rules/goals-and-audience.md` → "Goals and Audience", and have larv-review's comprehension check name the contributor as the reader it serves. The check then runs in a project whose audience includes the contributor, and a project that drops them skips it.
|
||||
|
||||
### 119. Retitle the comprehension-floor decision so it says a chunk lifting a project towards the floor works first on its lowest-scoring dimension, and that the floor blocks nothing.
|
||||
|
||||
Today's title, "a project lifting itself to the comprehension floor starts at the lowest dimension", reads as either where the project scores or where work begins. Beside the title saying the check blocks no merge, a reader cannot tell whether `Floor:` means stop; a seat named `AGENTS.md:5` among the places it found hard. "First" means within such a chunk, not across a release: since the decision's 2026-10-16 line, items that lift the lowest dimension compete with the others like any item.
|
||||
@@ -120,14 +106,10 @@ The maintainability senior of PR #257's scoring run named `bin/rule_hook/rules.p
|
||||
|
||||
### 114. Run git through `git_repo.py` in `rule_hook`, `metric_bench`, `reading_cost`, `review_replay` and `loop_claude`, keeping rule-hook's guards as an option, so one module owns how a tool runs git.
|
||||
|
||||
Shape is the lowest dimension, so this item moves goal 1.1 by 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
Shape is the lowest dimension, so this item moves code health by 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
The comprehension seats on PR #254 found five git runners with different contracts: `git_repo.git`, `rule_hook/git.py`'s guarded one, `metric_bench/main.py`'s, `reading_cost/main.py`'s `located` and `loop_claude/effects.py`'s. PR #276 added a sixth, `review_replay/main.py`'s `git`. The inherited architect of PR #257's scoring run named `bin/git_repo.py:8` `git` again. Make `git_repo.git` easier to read.
|
||||
|
||||
### 120. Rewrite larv-review §3's "Round cap" and "Re-entry" as one table that says, for each kind of fix, which passes rerun and what a round reviews.
|
||||
|
||||
Junior A, Mid A and the maintainability senior of PR #257's scoring run named `skills/larv-review/SKILL.md:63` "Round cap" hardest, two of them with `:74` "Re-entry"; the inherited architect named `:71` "Cap". A reader holds the trigger table's "a fix, only where …" clauses, the cap, later rounds' scope and the prose, 🟢 and ❓ exceptions at once. Junior A could not say what a fix to a stability 🟡 that also touches a comment reruns. Make those sections easier to read.
|
||||
|
||||
### 117. Give `todo_table.items` one way to say a plan has no items table, so no caller tells it from an empty plan by truthiness.
|
||||
|
||||
The comprehension seats on PR #254 found `items` returning a list, None or a Failure, and `larv_review/plan.py` `plan_reasons` reading None through `items(before) or []`, which works only because a Failure is truthy.
|
||||
@@ -152,14 +134,48 @@ Junior A and Mid A of PR #257's scoring run named `bin/shell_command.py:31` `seg
|
||||
|
||||
Raised by PR #283's prose pass. The paragraph runs about 330 words and holds six choices: the bar, the purge, re-raising findings, the gate check, the `principle` exemption and the 2026-10-08 weights note. A reader after one of them reads all six.
|
||||
|
||||
### 49. Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.
|
||||
### 80. State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.
|
||||
|
||||
DRY, in `principles/technical-principles.md`: the list is copied by hand, and sessions work from the copy.
|
||||
A defect: goal 2, keeping the setup shareable between computers, does not hold while a new machine is never told it must be a sandbox. Raised by the principles audit of PR #224. The `settings.json` decision is valid while every machine taking this checkout is a sandbox, but Install asks for a sandbox only for `loop-claude`.
|
||||
|
||||
### 120. Rewrite larv-review §3's "Round cap" and "Re-entry" as one table that says, for each kind of fix, which passes rerun and what a round reviews.
|
||||
|
||||
Junior A, Mid A and the maintainability senior of PR #257's scoring run named `skills/larv-review/SKILL.md:63` "Round cap" hardest, two of them with `:74` "Re-entry"; the inherited architect named `:71` "Cap". A reader holds the trigger table's "a fix, only where …" clauses, the cap, later rounds' scope and the prose, 🟢 and ❓ exceptions at once. Junior A could not say what a fix to a stability 🟡 that also touches a comment reruns. Make those sections easier to read.
|
||||
|
||||
### 21. Give `settings.json`'s model one writer, and sort its keys.
|
||||
|
||||
A defect: goal 2, keeping the setup shareable between computers, does not hold while one machine's model choice overwrites every other's. Claude Code rewrites `"model"` in this tracked file whenever a model is picked, so one `/model` dirties the checkout and overrides the synced choice.
|
||||
|
||||
Every write Claude Code makes to the file rewrites `"model"`, `claude plugin install` included: Claude Code 2.1.288 turned `"opus"` into `"opus[1m]"`. Each write also puts the keys back in Claude Code's own order, so a sorted file stays sorted only until the next write.
|
||||
|
||||
### 176. Give `loop-claude --help`'s routing paragraph sub-headings, such as Routing, Judge rung and Routing figures, so a reader finds a rule without reading 39 lines.
|
||||
|
||||
Raised by the prose pass of PR #302: the help, the docstring of `bin/loop_claude/loop/main.py`, is 145 lines, and its routing paragraph one block of 39, from the ladder through the judge's rung to the routing figures. A reader looking for one rule, such as when the worker steps up, reads it all. The comprehension seats already found the help hard (`larv-review places`: "loop-claude --help": a 120-line contract with no pointers to the modules it maps onto).
|
||||
|
||||
### 172. Name the project's rung `project` across `bin/loop_claude`, in place of `anchor`, as `bin/model_routing/ladder.py` names it.
|
||||
|
||||
The architecture pass of PR #296 found one rung under two names: `bin/model_routing/ladder.py` calls it `project`, while `bin/loop_claude/routing.py`, `cycle/prompts.py`, `cycle/run.py`'s `Cycle.anchor` and `loop/main.py` call it `anchor`, and gloss it as "anchor, the project's rung" in docstring after docstring. A reader works out that the two are one rung each time. Make `bin/loop_claude/routing.py`'s `first_route` easier to read.
|
||||
|
||||
### 190. Rewrite the `docs/decisions.md` entries `todo.md: one table …` and `loop-claude: a judge decides …` as the current state, so a reader no longer replays superseded paragraphs to learn what holds.
|
||||
|
||||
Found by the prose review of PR #312, which judged both entries to read as amendment logs, each paragraph correcting an earlier one. The rewrite keeps each paragraph's date and reason only where it still explains a rule that holds, and drops superseded states. It covers items 157 and 183, which reshape paragraphs of the same two entries.
|
||||
|
||||
### 82. Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.
|
||||
|
||||
"Deterministic order", in `principles/technical-principles.md`, raised by the principles audit of PR #224: their order carries no meaning, so two chunks adding a decision conflict at the end, and a reader cannot find a title by scanning.
|
||||
|
||||
### 29. Make the contributor a standing member of every project's audience, unless its README voids code health.
|
||||
|
||||
State that in `~/.claude/rules/goals-and-audience.md` → "Goals and Audience", and have larv-review's comprehension check name the contributor as the reader it serves. The `**Void:** code health` line (`~/.claude/CLAUDE.md` → "Shared goal") is the one place a project says maintainability does not matter: it drops the contributor. A project that opts out of the comprehension check must already write that line.
|
||||
|
||||
### 106. Make larv-review's "Do not over-read a clean result" cite a rule that says Renovate or Dependabot owns dependency CVEs, or drop the citation.
|
||||
|
||||
Found by the goals audit of PR #245. `skills/larv-review/SKILL.md` §3 → "Security" says Renovate or Dependabot owns dependency CVEs per `CLAUDE.md` → "Working with the codebase", which says nothing about either.
|
||||
|
||||
### 49. Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.
|
||||
|
||||
DRY, in `principles/technical-principles.md`: the list is copied by hand, and sessions work from the copy.
|
||||
|
||||
### 154. Have `bin/shell_command.py`'s `segments` keep a command's words together across a redirect, so `git > out commit` reads as one git commit.
|
||||
|
||||
`segments('echo hi > f arg')` returns `arg` as a command of its own, and `segments('git > /tmp/x commit -m hi')` returns `git` and `commit -m hi` apart, though the shell runs one `git commit`. rule-hook's commit rules read the commands `segments` finds, so such a commit escapes `commit-one-line`, `no-ai-attribution`, `round-title-counts` and `todo-rank-check`. The comprehension seats' scoring run in PR #280 found it.
|
||||
@@ -174,44 +190,30 @@ The chunk that ships this item files a copy of it in the release after the one i
|
||||
|
||||
Item 161 put `chunk-preflight`'s facts into a fresh worker's prompt, so the worker no longer finds them itself. Before that, in item 140's chunk, the worker spent 5 min 46 s of 30 min, 16 of its 68 messages and 226k of its 491k fresh tokens before its first edit, through 12 Bash and 5 Read calls. Measure those figures from loop-claude's archive, as medians over the first five chunks that started with the preflight and the five before them: one chunk is too noisy a baseline, as `docs/decisions.md` → `reading cost: a rise is …` records. Measure the counter-signals beside them: goal 1.4's review rounds and unfinished verdicts, and goal 1.5's 🔴 findings, per chunk, since a worker that reads less may start sooner and need more rounds or let more defects through. Where time or tokens did not fall, or a counter-signal rose, file an item naming the facts the workers still found by hand, or what the preflight got wrong.
|
||||
|
||||
### 80. State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.
|
||||
### 183. Merge the two 2026-10-13 paragraphs of `docs/decisions.md` → `loop-claude: a judge decides each interrupt …` into one.
|
||||
|
||||
A defect: goal 2, keeping the setup shareable between computers, does not hold while a new machine is never told it must be a sandbox. Raised by the principles audit of PR #224. The `settings.json` decision is valid while every machine taking this checkout is a sandbox, but Install asks for a sandbox only for `loop-claude`.
|
||||
They say the same thing for `~/.claude/rules/` (item 95) and `~/.claude/skills/larv-review/standards/` (item 104), and the entry grows a paragraph per chunk. Raised by the prose review of PR #308.
|
||||
|
||||
### 176. Give `loop-claude --help`'s routing paragraph sub-headings, such as Routing, Judge rung and Routing figures, so a reader finds a rule without reading 39 lines.
|
||||
### 184. Rewrap the lines of `loop-claude --help` that run past the column the rest of it wraps at.
|
||||
|
||||
Raised by the prose pass of PR #302: the help, the docstring of `bin/loop_claude/loop/main.py`, is 145 lines, and its routing paragraph one block of 39, from the ladder through the judge's rung to the routing figures. A reader looking for one rule, such as when the worker steps up, reads it all. The comprehension seats already found the help hard (`larv-review places`: "loop-claude --help": a 120-line contract with no pointers to the modules it maps onto).
|
||||
In `bin/loop_claude/loop/main.py`'s docstring, the line holding "of one PR, is finished" and the one ending "Each of these opens with its UTC time." run to 107 and 159 columns. Raised by the prose review of PR #308.
|
||||
|
||||
### 186. Point every file a session parks outside its checkout, such as the comprehension panel's detached worktree and a build probe's output, at a folder a headless session has, since loop-claude's sessions have no scratchpad.
|
||||
|
||||
`skills/comprehension-panel/SKILL.md` puts the base version's detached worktree "in your scratchpad", and `CLAUDE.md` → "Working with the codebase" lets a build-probing subagent write "only to the session scratchpad". A probe on 2026-10-18 found no `scratchpad_dir` in a headless `claude -p` session's hook input, and neither the session nor its subagent knew a scratchpad path. larv-review now parks its reports and votes file in the chunk's review folder under `~/.local/state/larv-review/`, per `docs/decisions.md` → `review: each reviewer under agents/ writes its full report into the chunk's review folder`. Found by the architecture review of PR #310.
|
||||
|
||||
### 172. Name the project's rung `project` across `bin/loop_claude`, in place of `anchor`, as `bin/model_routing/ladder.py` names it.
|
||||
### 198. Count, per finished chunk, the findings that arose from misreading code that had already shipped, so code health's counter-signal shows.
|
||||
|
||||
The architecture pass of PR #296 found one rung under two names: `bin/model_routing/ladder.py` calls it `project`, while `bin/loop_claude/routing.py`, `cycle/prompts.py`, `cycle/run.py`'s `Cycle.anchor` and `loop/main.py` call it `anchor`, and gloss it as "anchor, the project's rung" in docstring after docstring. A reader works out that the two are one rung each time. Make `bin/loop_claude/routing.py`'s `first_route` easier to read.
|
||||
Code health's counter-signal (`CLAUDE.md` → "Shared goal") has no count, since no tool records why a finding arose. Have each reviewer tag a finding that arose because the implementer misread code that had already shipped, and have `score-outcomes` count the tagged findings per finished chunk. Item 110's later fixes stand for the defects that keep reappearing.
|
||||
|
||||
### 167. Refuse a `/security-review` or `/claude-security` Skill call below the project's rung, as rule-hook refuses such an Agent call.
|
||||
|
||||
rule-hook checks Agent calls (item 163) but no Skill calls. A worker that invokes `/security-review` in its own context, instead of in a subagent, runs the pass on its own rung, and nothing blocks it. Check Skill calls too: `breaches_of` in bin/rule_hook/main.py takes a Skill call whose skill is `security-review` or `claude-security` as a review launch, and settings.json's PreToolUse matcher gains Skill. Found by the systems-architect's review of PR #295.
|
||||
|
||||
### 82. Sort `AGENTS.md`'s decision titles and `docs/decisions.md`'s entries by title.
|
||||
|
||||
"Deterministic order", in `principles/technical-principles.md`, raised by the principles audit of PR #224: their order carries no meaning, so two chunks adding a decision conflict at the end, and a reader cannot find a title by scanning.
|
||||
|
||||
### 173. Have rule-hook's `todo-rank-check` run a worktree's own `bin/rank_todo.py` when the worktree is of this repo, so a branch that changes `todo.md`'s shape commits without an override.
|
||||
|
||||
Raised by the overrides pass of PR #296. The hook imports the main checkout's `rank_todo.py`, so while a branch of this repo changes the table's shape, every commit touching `todo.md` needs a `todo-rank-check` override: 33 log lines across four branches, the score-outcomes, plan-136, plan-148 and item-146 ones. The hook then checks nothing, and the rule rests on the worker chaining the branch's own check. Run another repo's `bin/rank_todo.py` never: that would run its code before every commit.
|
||||
|
||||
### 21. Give `settings.json`'s model one writer, and sort its keys.
|
||||
|
||||
A defect: goal 2, keeping the setup shareable between computers, does not hold while one machine's model choice overwrites every other's. Claude Code rewrites `"model"` in this tracked file whenever a model is picked, so one `/model` dirties the checkout and overrides the synced choice.
|
||||
|
||||
Every write Claude Code makes to the file rewrites `"model"`, `claude plugin install` included: Claude Code 2.1.288 turned `"opus"` into `"opus[1m]"`. Each write also puts the keys back in Claude Code's own order, so a sorted file stays sorted only until the next write.
|
||||
|
||||
### 190. Rewrite the `docs/decisions.md` entries `todo.md: one table …` and `loop-claude: a judge decides …` as the current state, so a reader no longer replays superseded paragraphs to learn what holds.
|
||||
|
||||
Found by the prose review of PR #312, which judged both entries to read as amendment logs, each paragraph correcting an earlier one. The rewrite keeps each paragraph's date and reason only where it still explains a rule that holds, and drops superseded states. It covers items 157 and 183, which reshape paragraphs of the same two entries.
|
||||
|
||||
### 171. Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.
|
||||
|
||||
Raised by the goals audit of PR #296. `bin/routing_figures/measure.py` groups a chunk's review rounds by the rung its worker started on, and calls for a routing change when a lower rung took more of them. Since PR #296 the reviewers may run above the worker's rung, on the one their item's E + I picks, and no figure groups rounds by it, though the archived worker line names the E + I it follows from. A cheap worker on an item of high E + I gets stronger reviewers, who may raise more rounds, and a call could then blame the worker's rung for them: an interrupt of lilleman that settles nothing (goal 1.2).
|
||||
@@ -248,18 +250,14 @@ A test audit across lilleman's projects on 2026-10-16 found 10 of 33 sampled tes
|
||||
|
||||
`bin/loop_claude/cycle/interrupt.py`'s `put_question` reads the answer with `input()`, and nothing under `bin/` imports `readline`, so Left types `^[[D` into the answer the worker gets. Importing `readline` gives line editing, at two costs. It writes the prompt to stdout, not stderr. And its bracketed paste can return several lines, while `prompts.typed_answer` ends the answer at its first blank line and shows the judge the rest as loop-claude's words. Raised by the product-owner review of PR #308.
|
||||
|
||||
### 155. Lower the reading cost of the files a chunk reads most before its first commit.
|
||||
|
||||
`bin/reading-cost` on 2026-10-18: the median of the last 5 chunks is 163,028 new input tokens before their first commit, up from 100,998 for the 5 before them. Read most over the last 5, by opens and searches: `rules/decisions.md` 1. The chunk that ships this item runs `bin/reading-cost --reset`.
|
||||
|
||||
### 169. Have rule-hook's `todo-rank-check` catch a `todo.md` that the same Bash call edits and then commits.
|
||||
|
||||
The hook judges a call before it runs, and `changed` in `bin/rule_hook/todo_check.py` compares `todo.md` with the index and HEAD as they stand then. A call that edits `todo.md` and commits it, such as a heredoc script followed by `git commit`, passes unchecked: PR #296's commit 149108e did, and the override marker it carried was never logged. larv-review's gate still runs `rank_todo.py --check`, so an unranked plan stops at merge rather than at commit. A git pre-commit hook would see the staged file.
|
||||
|
||||
### 183. Merge the two 2026-10-13 paragraphs of `docs/decisions.md` → `loop-claude: a judge decides each interrupt …` into one.
|
||||
|
||||
They say the same thing for `~/.claude/rules/` (item 95) and `~/.claude/skills/larv-review/standards/` (item 104), and the entry grows a paragraph per chunk. Raised by the prose review of PR #308.
|
||||
|
||||
### 184. Rewrap the lines of `loop-claude --help` that run past the column the rest of it wraps at.
|
||||
|
||||
In `bin/loop_claude/loop/main.py`'s docstring, the line holding "of one PR, is finished" and the one ending "Each of these opens with its UTC time." run to 107 and 159 columns. Raised by the prose review of PR #308.
|
||||
|
||||
### 197. Let the human edit what they type at loop-claude's terminal questions with the arrow keys, so Left moves the cursor in place of printing `^[[D`.
|
||||
|
||||
`bin/loop_claude/effects.py` reads each answer with Python's builtin `input`, and nothing imports `readline`, so the terminal gets no line editing: fixing a typo means erasing back to it. Importing `readline` in `effects.py` gives `input` that editing, for the interrupt's answer and the question that asks for the project's model alike. lilleman, 2026-10-18: "Not super-important, but a bit irritating."
|
||||
@@ -268,28 +266,36 @@ In `bin/loop_claude/loop/main.py`'s docstring, the line holding "of one PR, is f
|
||||
|
||||
The principles pass of PR #301 found that only `routed_by` in `bin/loop_claude/cycle/prompts.py` asks the worker to name each item it takes with its L and E + I, and `fresh` uses it only where an item routed the chunk. In an unrouted chunk the judge has no levels to report, so neither the taken-in L nor the taken-in E + I lifts the worker, the reviewers or the judge, and the first prompt names no reviewers' rung for a higher E + I.
|
||||
|
||||
### 170. Re-tune `WORKER_STEPS` and `REVIEW_STEPS` once 10 chunks have shipped under them, from how well L, E and I order their review rounds and 🔴 findings.
|
||||
|
||||
`docs/decisions.md` → `routing: one ladder…` calls the steps lilleman approved on 2026-10-16 a first guess. Once 10 chunks that each shipped one item scored with L, E and I have merged, read `score-outcomes`' rank correlations for L, E and I and the routed-chunks table of `routing-figures.md`, and propose new steps to lilleman, whose call they are.
|
||||
|
||||
### 122. Assemble the judge's prompt in `bin/loop_claude/cycle/judge.py`, importing only wording the worker also sees, and call the worker "the worker" in it.
|
||||
|
||||
All four seats of PR #257's scoring run named `bin/loop_claude/cycle/judge.py:16` `JUDGE_RULES`. The prompt is spliced from constants in `cycle/prompts.py` (`ANSWER_DESTINATIONS`, `ANSWERS_RECORDED`, `either`) and `project/records.py` (`HUMAN_RULE_NAMES`), so a reader rebuilds it from three files. It says "the agent" where the code and `CLAUDE.md` → "Vocabulary" say "worker". Wording the worker also sees, such as `ANSWER_DESTINATIONS` in `prompts.resumed`, may stay in `cycle/prompts.py`. Make `JUDGE_RULES` easier to read.
|
||||
|
||||
### 158. Measure the fixed cost of a chunk from loop-claude's archive, in tokens and hours against its items' S, and set F in `Score = 100 * V / (2**S + F)` to it.
|
||||
|
||||
F is 8 until then, about one S 3 change, lilleman's call in PR #283. A chunk costs more than its size: the worker reads about 130k tokens before its first commit whatever the item, and every chunk takes its review passes. Fit cost against 2**S from the finished chunks `score-outcomes` measures, in the same units `2**S` counts, and say in `docs/decisions.md` → `todo.md: …` how far the fit holds. A chunk bundling tiny items shares F between them.
|
||||
|
||||
### 130. Move the vote counting out of `bin/larv_review/ruling.py`'s `votes`, so reading a votes file decides nothing.
|
||||
|
||||
Mid A of PR #257's scoring run named `bin/larv_review/ruling.py:8` `votes`. It calls `counted` while validating, to reject the maintainability senior's and Junior A's lines when Mid A and the inherited architect already agree overall: a ruling hidden in a parser. The counting rule is spread over `seats.py`, `ruling.py`, `comprehension_history.place_dimensions` and the help. Make `votes` easier to read.
|
||||
|
||||
### 125. Give "record", "outcome" and "places" one meaning each across `bin/`, and rename `bin/larv_review/git.py` by what it holds.
|
||||
|
||||
Shape is the lowest dimension, so this item moves goal 1.1 by 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
Shape is the lowest dimension, so this item moves code health by 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
The inherited architect of PR #257's scoring run named `bin/reading_cost/measure.py:16` `Reading` and `bin/larv_review/git.py:6` `history_changes`, and found each word used for several concepts. "Record": the history writer `larv_review/record.py`, the judge's `loop_claude/project/records.py`, and `reading_cost/figures.py`'s `RECORD`. "Outcome": `transcript_archive/outcomes.py`, `score_outcomes/outcomes.py` `Outcome` and `rule_hook/rules.py` `Outcome`. "Places": `comprehension_history.Place` and `Reading.places`. `larv_review/git.py` holds history logic, not a git runner. Make `Reading` and `history_changes` easier to read.
|
||||
|
||||
### 137. Archive a chunk's route as a record loop-claude reads back field by field, in place of the `Worker:` prose `ROUTED` parses, and name `stepped` and the judge's `bundled` by what they do.
|
||||
|
||||
PR #262's paired ruling found the project reads worse: a rerun resumes on its rung only by parsing `Rung.__str__`'s and `Route.__str__`'s wording back with `bin/loop_claude/routing.py`'s `ROUTED`, a string contract over four files, where a reword silently routes afresh. Write the route as a structured line, such as JSON after `Worker:`, that `transcript_archive` reads into fields. `stepped` both raises to a bundled item's rung and counts towards a one-rung step; `Reply.bundled` names neither L nor highest. Make `bin/loop_claude/loop/main.py`'s `run_loop` easier to read where it threads the route. The structured line must keep the escalation's mark, archived today as `escalated at transcript entry N`: without it, a trigger that already stepped the worker could step it again.
|
||||
|
||||
### 139. Split `bin/routing_figures/measure.py` by concern, and keep the figures' measured cycle and each raised call as fields loop-claude reads back, not as the prose it renders.
|
||||
|
||||
The paired ruling on PR #265 ruled worse. Make these places easier to read: `measure.py` `measured` and `render` (token attribution, subagent rungs, round counting, calls and rendering in one module; `measured`, `Measured` and `measure_archive` side by side); `calls` with `archive.py` `raised` and `last_measured`, where a call's identity is its sentence and the measured cycle is read back from rendered markdown; and `Reports.searches`, which holds characters, not searches.
|
||||
|
||||
### 170. Re-tune `WORKER_STEPS` and `REVIEW_STEPS` once 10 chunks have shipped under them, from how well L, E and I order their review rounds and 🔴 findings.
|
||||
|
||||
`docs/decisions.md` → `routing: one ladder…` calls the steps lilleman approved on 2026-10-16 a first guess. Once 10 chunks that each shipped one item scored with L, E and I have merged, read `score-outcomes`' rank correlations for L, E and I and the routed-chunks table of `routing-figures.md`, and propose new steps to lilleman, whose call they are.
|
||||
|
||||
### 158. Measure the fixed cost of a chunk from loop-claude's archive, in tokens and hours against its items' S, and set F in `Score = 100 * V / (2**S + F)` to it.
|
||||
|
||||
F is 8 until then, about one S 3 change, lilleman's call in PR #283. A chunk costs more than its size: the worker reads about 130k tokens before its first commit whatever the item, and every chunk takes its review passes. Fit cost against 2**S from the finished chunks `score-outcomes` measures, in the same units `2**S` counts, and say in `docs/decisions.md` → `todo.md: …` how far the fit holds. A chunk bundling tiny items shares F between them.
|
||||
|
||||
### 116. Report L by the share of chunks with a 🔴, once 10 chunks that each shipped one item record finding counts and most record no 🔴.
|
||||
|
||||
`score-outcomes` reports the median 🔴 count at each guessed R, and how well L orders chunks by 🔴 findings; the part of R a 🔴 tests is L. Where most chunks have no 🔴, every median reads 0 and the rank correlation rests on the few that have one, which tells a scorer little. No round title held counts before PR #254, so how often a chunk has a 🔴 is not yet known.
|
||||
@@ -314,10 +320,6 @@ The inherited architect of PR #257's scoring run named `bin/round_titles.py:5` `
|
||||
|
||||
Found by the principles audit of PR #242. `bin/loop_claude/test_black_box.py:113-114` swaps the global `time.sleep`, the shape "Functional core, imperative shell" bans. An override of the delay lets the test run the code as production runs it.
|
||||
|
||||
### 137. Archive a chunk's route as a record loop-claude reads back field by field, in place of the `Worker:` prose `ROUTED` parses, and name `stepped` and the judge's `bundled` by what they do.
|
||||
|
||||
PR #262's paired ruling found the project reads worse: a rerun resumes on its rung only by parsing `Rung.__str__`'s and `Route.__str__`'s wording back with `bin/loop_claude/routing.py`'s `ROUTED`, a string contract over four files, where a reword silently routes afresh. Write the route as a structured line, such as JSON after `Worker:`, that `transcript_archive` reads into fields. `stepped` both raises to a bundled item's rung and counts towards a one-rung step; `Reply.bundled` names neither L nor highest. Make `bin/loop_claude/loop/main.py`'s `run_loop` easier to read where it threads the route. The structured line must keep the escalation's mark, archived today as `escalated at transcript entry N`: without it, a trigger that already stepped the worker could step it again.
|
||||
|
||||
### 66. Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.
|
||||
|
||||
KISS, in `principles/technical-principles.md`, which keeps a limit only while readers find the flagged code hard. `agents/systems-architect.md` makes cyclomatic 7 and 24 lines gate rules from the first commit, a 🔴 unless a reason is stated.
|
||||
@@ -334,14 +336,24 @@ Found by the principles audit of PR #242, against "Functional core, imperative s
|
||||
|
||||
`score-outcomes` measures risk only by the 🔴 findings review caught. A serious bug review missed shows later, as a change that fixes code the chunk wrote: the defect that escaped, which E guesses.
|
||||
|
||||
### 139. Split `bin/routing_figures/measure.py` by concern, and keep the figures' measured cycle and each raised call as fields loop-claude reads back, not as the prose it renders.
|
||||
|
||||
The paired ruling on PR #265 ruled worse. Make these places easier to read: `measure.py` `measured` and `render` (token attribution, subagent rungs, round counting, calls and rendering in one module; `measured`, `Measured` and `measure_archive` side by side); `calls` with `archive.py` `raised` and `last_measured`, where a call's identity is its sentence and the measured cycle is read back from rendered markdown; and `Reports.searches`, which holds characters, not searches.
|
||||
|
||||
### 149. Fill each release by priority up to a capacity it states, in place of the bar, and move what does not fit to a later release.
|
||||
|
||||
A release's capacity is a sum of its items' cost, as the formula counts it. Each project states its own; the human sets the first value per project. Nothing is deleted by score.
|
||||
|
||||
### 123. Have `bin/comprehension_history.py` parse each history entry once into seats, votes and places, so `latest_places`, `worse_places` and `worse_votes` neither depend on table order nor split a label to find a seat.
|
||||
|
||||
Three seats of PR #257's scoring run named `bin/comprehension_history.py:106` `latest_places`; the logic it rests on is `:114` `worse_places` and `:126` `worse_votes`. They regex the markdown the module writes. `worse_votes` keeps a seat's first row through `setdefault`, because the votes table comes first. `worse_places` recovers the seat with `label.split(",")[0]`. `Entry` still holds scoring seats' places for rulings recorded before PR #255. Make these functions easier to read.
|
||||
|
||||
### 124. Group the shared modules at `bin/`'s root into packages named by purpose, so the root holds only launchers and stand-alone tools.
|
||||
|
||||
Shape is the lowest dimension, so this item moves code health by 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
PR #257's scoring run put Shape at 6.25, the lowest dimension. `bin/` holds about 30 entries: 6 launchers, 6 tool packages, 3 shared packages and 15 root modules. Two root modules are tools (`rank_todo.py`, `statusline.py`) and 13 are shared libraries, and nothing in the layout tells them apart; only README's import-root paragraph maps them. Candidate packages: git running and parsing, the todo table with `rank_todo.py`'s formula language and goal weighing, and the comprehension history with round titles. `rank_todo.py` keeps its path, which every project's rules name. The `.gitignore` allowlist and README follow the move.
|
||||
|
||||
### 132. Lift each dimension still under the comprehension floor after release 0.2.0's scoring run, at the places that run names.
|
||||
|
||||
Replaces item 62, which release 0.3.0's items split. PR #257's scoring run put Locality and Self-sufficiency at 6.63, Shape at 6.25 and the overall at 6.50, against the floor of 7.0 in `docs/decisions.md` → `comprehension floor: …`. Split this into items, one per place, once 0.3.0's scoring run has named them.
|
||||
|
||||
### 105. Compare review rounds per pass and reading cost for the five chunks before and after the `worker:` decision moved the principles out of the worker's context, and file an item if either rose.
|
||||
|
||||
The `worker:` decision is valid while review rounds per pass do not rise. Count the rounds from each PR's `Answer <pass> round <n>:` commits, and take reading cost from `docs/reading-cost.md`. Run it once five chunks have merged after the one that recorded the decision.
|
||||
@@ -360,20 +372,6 @@ When CI runs a rule check, such as one of `bin/rule-hook`'s, let `<!-- rule-over
|
||||
|
||||
The maintainability senior and the inherited architect of PR #257's scoring run named `bin/loop_claude/loop/reload.py:38` `fingerprint` and `:50` `exec_if_edited`: the fingerprint covers every `bin/**/*.py`, so editing `statusline.py` or `rank_todo.py` re-execs a running loop. Make `fingerprint` easier to read.
|
||||
|
||||
### 123. Have `bin/comprehension_history.py` parse each history entry once into seats, votes and places, so `latest_places`, `worse_places` and `worse_votes` neither depend on table order nor split a label to find a seat.
|
||||
|
||||
Three seats of PR #257's scoring run named `bin/comprehension_history.py:106` `latest_places`; the logic it rests on is `:114` `worse_places` and `:126` `worse_votes`. They regex the markdown the module writes. `worse_votes` keeps a seat's first row through `setdefault`, because the votes table comes first. `worse_places` recovers the seat with `label.split(",")[0]`. `Entry` still holds scoring seats' places for rulings recorded before PR #255. Make these functions easier to read.
|
||||
|
||||
### 124. Group the shared modules at `bin/`'s root into packages named by purpose, so the root holds only launchers and stand-alone tools.
|
||||
|
||||
Shape is the lowest dimension, so this item moves goal 1.1 by 9, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
PR #257's scoring run put Shape at 6.25, the lowest dimension. `bin/` holds about 30 entries: 6 launchers, 6 tool packages, 3 shared packages and 15 root modules. Two root modules are tools (`rank_todo.py`, `statusline.py`) and 13 are shared libraries, and nothing in the layout tells them apart; only README's import-root paragraph maps them. Candidate packages: git running and parsing, the todo table with `rank_todo.py`'s formula language and goal weighing, and the comprehension history with round titles. `rank_todo.py` keeps its path, which every project's rules name. The `.gitignore` allowlist and README follow the move.
|
||||
|
||||
### 132. Lift each dimension still under the comprehension floor after release 0.2.0's scoring run, at the places that run names.
|
||||
|
||||
Replaces item 62, which release 0.3.0's items split. PR #257's scoring run put Locality and Self-sufficiency at 6.63, Shape at 6.25 and the overall at 6.50, against the floor of 7.0 in `docs/decisions.md` → `comprehension floor: …`. Split this into items, one per place, once 0.3.0's scoring run has named them.
|
||||
|
||||
### 68. Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.
|
||||
|
||||
"Most, if not all, code should have automated tests", in `principles/technical-principles.md`: `compare.blind()` keeps the comparison blind, and a version name it misses invalidates the bench silently.
|
||||
@@ -388,10 +386,6 @@ Today the folder is the SHA-256 of the transcript's first timestamped line, whic
|
||||
|
||||
While `rank_todo.py` ranks two shapes, projects follow two sets of scoring rules, against goal 1.3. Once every project has reshaped, drop `OLD_SHAPE`'s weighing from `rank_todo.py`, `RESHAPE`, and the old shape's lines in `rank_todo.py --help` and `rules/todo-items.md`. Keep `todo_table` reading old tables: `score_outcomes` reads every past merge's `todo.md`. PR #283's paired ruling found the old-shape path made `rank_todo.py`'s `score`, `Scoring.weights`, `unknown_columns` and `todo_table.py`'s `Moves` harder to read; leave each easier, with one shape and moves that are always moves, and the Moves cell's rules in one place.
|
||||
|
||||
### 155. Lower the reading cost of the files a chunk reads most before its first commit.
|
||||
|
||||
`bin/reading-cost` on 2026-10-18: the median of the last 5 chunks is 163,028 new input tokens before their first commit, up from 100,998 for the 5 before them. Read most over the last 5, by opens and searches: `rules/decisions.md` 1. The chunk that ships this item runs `bin/reading-cost --reset`.
|
||||
|
||||
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.
|
||||
|
||||
It lives under `~/.claude`, which `.gitignore` keeps from the remote, so a lost disk loses every unattended run's record. Back it up only to a destination private to me and encrypted at rest: the worker runs with permissions bypassed, so the archived tool results can hold credentials it read.
|
||||
|
||||
Reference in New Issue
Block a user