Merge pull request 'Score and reshape the plan only on the project's rung or above' (#273) from plan-141 into main
This commit was merged in pull request #273.
This commit is contained in:
@@ -26,6 +26,7 @@ Decisions live in `docs/decisions.md`:
|
||||
- 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 and goal weights it states, held to its bar, ranked by `bin/rank_todo.py`
|
||||
- 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
|
||||
- rule-hook: a PreToolUse hook enforces each rule a program can check, a `# rule-override <rule>: <reason>` marker overrides one, and larv-review's overrides pass rules on each override before merge
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- A session or subagent below the project's rung, the cheapest rung of the project's model, no longer scores or reshapes `todo.md`: it drafts each new item and each change to a filed item, and before its next commit one subagent on the project's rung or above applies and scores the drafts and sets their release. It may still remove finished items. `rules/todo-items.md` states the rule. `CLAUDE.md` has a session launch a subagent that files or scores items on the rung the new `bin/subagent-rung --plan <model> <R+C>` prints, never below the project's rung, and `loop-claude`'s prompt to a worker below that rung names the command. Expect one extra subagent in a chunk that files items while its worker runs below the project's rung.
|
||||
- `loop-claude` runs the judge of an Opus 5.5 project on the rung the chunk's `todo.md` item picks, never below Opus 5.5 at medium effort, the project's rung. Before, the judge ran at the effort `settings.json` sets, xhigh. A replay of 39 archived verdicts found every cheaper rung missing verdicts. The judge keeps its rung when the worker steps up or takes in another item, and runs on the project's rung when no item routed the chunk. A project on another model keeps its judge at its settings' effort. Each verdict in the archive now names the judge's rung on a `Judge:` line. The new `bin/judge-replay <model>` replays the judge on archived verdicts and prints the cheapest rung that returns them. Expect the judge to cost less on items of R + C 12 or less, and more on items of R + C 15 or more.
|
||||
- Every 20 cycles across all projects, `loop-claude` measures every finished chunk in its archive, with no model run, and writes the figures to `routing-figures.md` at the archive's root: tokens by project, subagent type, rung and tool, and, for each chunk a `todo.md` item routed, grouped by the rung it started on: its review rounds past each pass's first, its unfinished verdicts and its subagents' rungs. It interrupts you, with `claude` on the project's model on the terminal in `~/.claude`, when chunks routed onto a rung took more review rounds or unfinished verdicts than chunks routed onto the next rung up, each rung with 5 chunks or more, or when 5 or more subagents of one type wrote reports longer than the tool results they read. Each call is raised once, then listed in `routing-calls-raised.md` beside the figures; the next chunk of this repo files a `todo.md` item for it. Off a terminal, the calls are said on stderr and the loop goes on. They are raised at the next measurement on a terminal. After a routing change, a `- <UTC time> Reset` line in that file makes the figures count only chunks finished after it, and lets its calls be raised again. Expect a pause of about ten seconds at each measurement.
|
||||
- A session delegates a task to a subagent only when it needs just the task's conclusion, such as a search across many files, and keeps edits in its own thread. It scores the task's R and C as for a `todo.md` item, and launches the subagent on the model and effort that the new `bin/subagent-rung <model> <R+C>` picks from the project's model, such as `model sonnet, effort high`. `CLAUDE.md` states the rule. Expect searches to run on cheaper models, and less of each session's context to fill with search output.
|
||||
|
||||
@@ -52,7 +52,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
|
||||
- Keep the project's main checkout (e.g. `~/code/log`, never a worktree) current: when it is behind `origin` — a merge landed, or a fetch shows it — run `git pull --ff-only` there instead of reporting the lag, never with `--autostash`: a dirty checkout is a finding to report, not to carry along.
|
||||
- Run a project's language runtime, package manager, and task runner through its container/tooling setup, never directly on the host unless a decision puts them there. Example: `docker compose run --rm app <tool> …`.
|
||||
- Tear down test containers after a run.
|
||||
- Delegate a task to a subagent only when you need just its conclusion: a search or read across many files, or work independent enough to run in parallel. Keep edits, and whatever you must check line by line, in your own thread: you would read a delegated diff again to check it. Score the task's R and C as for a `todo.md` item. Launch the subagent with the model and effort that `~/.claude/bin/subagent-rung <model> <R+C>` prints. `<model>` is the project's model id, such as `claude-opus-5-5`: the one loop-claude's prompt names as the project's, or else your own. A reviewer, a comprehension seat or the security pass takes the model and effort loop-claude's prompt gives it, or else none.
|
||||
- Delegate a task to a subagent only when you need just its conclusion: a search or read across many files, or work independent enough to run in parallel. Keep edits, and whatever you must check line by line, in your own thread: you would read a delegated diff again to check it. Score the task's R and C as for a `todo.md` item. Launch the subagent with the model and effort that `~/.claude/bin/subagent-rung <model> <R+C>` prints. `<model>` is the project's model id, such as `claude-opus-5-5`: the one loop-claude's prompt names as the project's, or else your own. A reviewer, a comprehension seat or the security pass takes the model and effort loop-claude's prompt gives it; given none, launch it with no model or effort, so it runs on your model. A subagent that files or scores `todo.md` items takes the rung `~/.claude/bin/subagent-rung --plan <model> <R+C>` prints, which is never below the project's.
|
||||
- Give a subagent only the access its job needs, and state the limits in its prompt. One that only reads, such as a prose review, gets no shell and no edits. One that probes a build tags the image as throwaway and removes it afterwards, writes only to the session scratchpad, and removes no image or file it did not create.
|
||||
- Check `README.md` first for build, test, install, and codegen commands, and fix one that misbehaves in the same change. Refresh `README.md` whenever you change what it describes, keeping it true, not longer.
|
||||
- Where `~/.claude/bin/rule-hook` does not check it, such as an image named in test code, a Kubernetes manifest, a `docker run` line or a file a Bash command writes, pin a container image to its full patch version and a GitHub Action to a semver tag.
|
||||
@@ -87,6 +87,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
|
||||
- **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`.
|
||||
- **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.
|
||||
- **round cap** — the rounds one pass may take per chunk; `larv-review` §3 → "Round cap".
|
||||
|
||||
@@ -76,7 +76,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
|
||||
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Bash, Edit, MultiEdit and Write call, and `rule-hook --help` states the rules and the override.
|
||||
- `score-outcomes [R S C]` lists the finished items whose guessed R, S and C sit nearest the given scores, with what their chunks measured, and each score's median outcome; `score-outcomes --help` states the measures.
|
||||
- `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it.
|
||||
- `subagent-rung <model> <R+C>` prints the Agent tool's model and effort for a subagent's task, picked by its R + C from the project's model; `subagent-rung --help` states the rule.
|
||||
- `subagent-rung [--plan] <model> <R+C>` prints the Agent tool's model and effort for a subagent's task, picked by its R + C from the project's model, and with `--plan` never below the project's rung; `subagent-rung --help` states the rule.
|
||||
|
||||
Test on the host, with `uv` on `PATH` to fetch mypy and the Python version Install names (`docs/decisions.md` → `bin/`): `python3 -m unittest discover -s bin -p 'test_*.py'`
|
||||
|
||||
|
||||
@@ -25,13 +25,14 @@ def routed_by(route: Route, anchor: Rung | None) -> str:
|
||||
|
||||
|
||||
def off_the_projects_rung(route: Route, anchor: Rung | None) -> str:
|
||||
"""Which subagents to launch on the project's rung, anchor, while the worker runs off it; empty while it runs on it."""
|
||||
"""Which subagents to launch on the project's rung, anchor, and below it which on the --plan rung; empty while the worker runs on anchor, as every chunk no item routed starts (routing.first_route)."""
|
||||
if anchor is None or route.rung == anchor:
|
||||
return ""
|
||||
# Below the project's rung, the reviewers stay on it to hold quality; above it, the seats score every chunk on one rung, and the security pass spends no more than the project chose.
|
||||
below = highest(route.rung, anchor) == anchor
|
||||
launched = "each reviewer, each comprehension seat and the security pass's subagent" if below else "each comprehension seat and the security pass's subagent"
|
||||
return f" Your rung is {'below' if below else 'above'} the project's, {anchor}: launch {launched} with the Agent tool set to {anchor.agent_args()}. Run a full scan only from such a subagent, since the scan's agents run on the model that starts them."
|
||||
planning = f" Launch each subagent that files or scores todo.md items on the rung `~/.claude/bin/subagent-rung --plan {anchor.model} <R+C>` prints." if below else ""
|
||||
return f" Your rung is {'below' if below else 'above'} the project's, {anchor}: launch {launched} with the Agent tool set to {anchor.agent_args()}. Run a full scan only from such a subagent, since the scan's agents run on the model that starts them.{planning}"
|
||||
|
||||
|
||||
def resumed(unfinished_evidence: str, route: Route, anchor: Rung | None) -> str:
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
import dataclasses
|
||||
|
||||
from failure import Failure
|
||||
from model_routing.ladder import highest, LADDER, picked, project_rung, Rung, stepped_up
|
||||
from model_routing.ladder import floored, highest, LADDER, picked, project_rung, Rung, stepped_up
|
||||
from todo_table import Item, items
|
||||
from model_routing.route import Route
|
||||
|
||||
@@ -34,7 +34,7 @@ def kept(route: Route, anchor: Rung) -> bool:
|
||||
|
||||
|
||||
def item_rung(anchor: Rung, route: Route) -> Rung:
|
||||
"""The rung the route's item's R + C picks from anchor, the project's rung, or anchor itself when no item routed it. The worker may run on a rung below anchor; judge_rung lifts the judge's rung to anchor."""
|
||||
"""The rung the route's item's R + C picks from anchor, the project's rung, or anchor itself when no item routed it. The worker may run on a rung below anchor."""
|
||||
return picked(anchor, route.risk_and_complexity) if route.item else anchor
|
||||
|
||||
|
||||
@@ -58,4 +58,4 @@ def judge_rung(judge_model: str, route: Route) -> Rung:
|
||||
anchor = project_rung(judge_model)
|
||||
if anchor is None or judge_model not in JUDGE_REPLAYED:
|
||||
return Rung(judge_model)
|
||||
return highest(anchor, item_rung(anchor, route))
|
||||
return floored(anchor, route.risk_and_complexity) if route.item else anchor
|
||||
|
||||
@@ -646,7 +646,7 @@ class WorkerArgs(unittest.TestCase):
|
||||
def test_keeps_reviewers_on_the_projects_rung_while_the_worker_runs_below_it(self):
|
||||
opus = Rung("claude-opus-5-5", "medium")
|
||||
below = prompts.fresh("Do it.", "## Goals", Route(Rung("claude-sonnet-5-5", "high"), 3, 5), opus)
|
||||
self.assertIn("whether or not it is item 3. Your rung is below the project's, claude-opus-5-5 at medium effort: launch each reviewer, each comprehension seat and the security pass's subagent with the Agent tool set to model opus, effort medium. Run a full scan only from such a subagent, since the scan's agents run on the model that starts them.\n\n", below)
|
||||
self.assertIn("whether or not it is item 3. Your rung is below the project's, claude-opus-5-5 at medium effort: launch each reviewer, each comprehension seat and the security pass's subagent with the Agent tool set to model opus, effort medium. Run a full scan only from such a subagent, since the scan's agents run on the model that starts them. Launch each subagent that files or scores todo.md items on the rung `~/.claude/bin/subagent-rung --plan claude-opus-5-5 <R+C>` prints.\n\n", below)
|
||||
self.assertNotIn("the project's", prompts.fresh("Do it.", "## Goals", Route(opus, 3, 9), opus))
|
||||
|
||||
def test_keeps_seats_and_the_security_pass_on_the_projects_rung_while_the_worker_runs_above_it(self):
|
||||
|
||||
@@ -49,6 +49,11 @@ def picked(anchor: Rung, risk_and_complexity: int) -> Rung:
|
||||
return climbed(anchor, next((step for highest, step in BANDS if risk_and_complexity <= highest), ABOVE_THE_BANDS))
|
||||
|
||||
|
||||
def floored(anchor: Rung, risk_and_complexity: int) -> Rung:
|
||||
"""The rung a task's R + C picks from anchor, the project's rung, never below anchor."""
|
||||
return highest(anchor, picked(anchor, risk_and_complexity))
|
||||
|
||||
|
||||
def stepped_up(rung: Rung) -> Rung:
|
||||
"""The rung above, or the top one; a rung off the ladder steps to the bottom one."""
|
||||
return climbed(rung, 1)
|
||||
|
||||
@@ -4,7 +4,7 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from model_routing.ladder import highest, LADDER, picked, project_rung, Rung, stepped_up
|
||||
from model_routing.ladder import floored, highest, LADDER, picked, project_rung, Rung, stepped_up
|
||||
|
||||
OPUS = Rung("claude-opus-5-5", "medium")
|
||||
|
||||
@@ -33,6 +33,13 @@ class Ladder(unittest.TestCase):
|
||||
self.assertEqual(stepped_up(LADDER[-1]), LADDER[-1])
|
||||
self.assertEqual(stepped_up(OPUS), Rung("claude-opus-5-5", "high"))
|
||||
|
||||
def test_floors_the_picked_rung_at_the_projects_rung(self):
|
||||
self.assertEqual(floored(OPUS, 2), OPUS)
|
||||
self.assertEqual(floored(OPUS, 12), Rung("claude-opus-5-5", "high"))
|
||||
|
||||
def test_names_each_rung_by_a_family_the_agent_tool_takes(self):
|
||||
self.assertEqual({rung.agent_args().split(",")[0] for rung in LADDER}, {"model haiku", "model sonnet", "model opus", "model fable"})
|
||||
|
||||
def test_ranks_a_rung_off_the_ladder_below_every_rung_on_it(self):
|
||||
self.assertEqual(highest(OPUS, LADDER[-1], LADDER[0]), LADDER[-1])
|
||||
self.assertEqual(highest(Rung("claude-opus-5-5", "low"), LADDER[0]), LADDER[0])
|
||||
|
||||
+16
-10
@@ -1,10 +1,12 @@
|
||||
"""Print the Agent tool's model and effort for a subagent's task: docs/decisions.md → `routing:`.
|
||||
|
||||
usage: subagent-rung <model> <R+C>
|
||||
usage: subagent-rung [--plan] <model> <R+C>
|
||||
|
||||
<model> is the project's model, such as claude-opus-5-5, and <R+C> the task's R + C, a whole
|
||||
number from 2 to 20, scored as for a todo.md item. It prints the rung that R + C picks from the
|
||||
model's cheapest rung, in the Agent tool's words, such as `model sonnet, effort high`. For a model
|
||||
model's cheapest rung, the project's rung, in the Agent tool's words, such as `model sonnet, effort
|
||||
high`. --plan, for a task that files or scores todo.md items, prints the project's rung where that
|
||||
R + C picks a lower one, as ~/.claude/rules/todo-items.md lets only the project's rung or above plan. For a model
|
||||
off the routing ladder, the tool prints nothing on stdout, says so on stderr and exits 0; launch the
|
||||
subagent with no model or effort.
|
||||
|
||||
@@ -13,26 +15,30 @@ Exit 1, saying why, on bad arguments.
|
||||
import re
|
||||
import sys
|
||||
|
||||
from model_routing.ladder import picked, project_rung
|
||||
from model_routing.ladder import floored, picked, project_rung
|
||||
|
||||
USAGE = "usage: subagent-rung <model> <R+C>, R+C a whole number from 2 to 20"
|
||||
USAGE = "usage: subagent-rung [--plan] <model> <R+C>, R+C a whole number from 2 to 20"
|
||||
|
||||
|
||||
def agent_args(model: str, risk_and_complexity: int) -> str | None:
|
||||
"""The Agent tool's model and effort for the rung risk_and_complexity picks from model's cheapest rung; None for a model off the ladder."""
|
||||
def agent_args(model: str, risk_and_complexity: int, planning: bool = False) -> str | None:
|
||||
"""The Agent tool's model and effort for the rung risk_and_complexity picks from model's cheapest rung, never below it when planning; None for a model off the ladder."""
|
||||
anchor = project_rung(model)
|
||||
return picked(anchor, risk_and_complexity).agent_args() if anchor else None
|
||||
if anchor is None:
|
||||
return None
|
||||
return (floored if planning else picked)(anchor, risk_and_complexity).agent_args()
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
if argv[:1] in (["-h"], ["--help"]):
|
||||
print(__doc__.strip())
|
||||
return 0
|
||||
if len(argv) != 2 or not re.fullmatch(r"[2-9]|1[0-9]|20", argv[1]):
|
||||
planning = argv[:1] == ["--plan"]
|
||||
operands = argv[1:] if planning else argv
|
||||
if len(operands) != 2 or not re.fullmatch(r"[2-9]|1[0-9]|20", operands[1]):
|
||||
print(f"subagent-rung: cannot read the arguments{' ' + ' '.join(argv) if argv else ''}; {USAGE}", file=sys.stderr)
|
||||
return 1
|
||||
model, total = argv
|
||||
args = agent_args(model, int(total))
|
||||
model, total = operands
|
||||
args = agent_args(model, int(total), planning)
|
||||
if args is None:
|
||||
print(f"subagent-rung: {model} is not on the routing ladder; pass the Agent tool no model or effort", file=sys.stderr)
|
||||
else:
|
||||
|
||||
@@ -20,14 +20,19 @@ class SubagentRung(unittest.TestCase):
|
||||
self.assertEqual(main.agent_args("claude-opus-5-5", 20), "model fable, effort max")
|
||||
self.assertEqual(main.agent_args("claude-haiku-5-5", 2), "model haiku, effort low")
|
||||
|
||||
def test_a_planning_task_never_runs_below_the_projects_rung(self):
|
||||
self.assertEqual(main.agent_args("claude-opus-5-5", 2, planning=True), "model opus, effort medium")
|
||||
self.assertEqual(main.agent_args("claude-opus-5-5", 12, planning=True), "model opus, effort high")
|
||||
self.assertEqual(self.run_tool("--plan", "claude-opus-5-5", "7").stdout, "model opus, effort medium\n")
|
||||
|
||||
def test_picks_nothing_for_a_model_off_the_ladder(self):
|
||||
self.assertIsNone(main.agent_args("claude-opus-5", 9))
|
||||
|
||||
def test_refuses_an_r_plus_c_outside_2_to_20_or_a_wrong_count_of_arguments(self):
|
||||
for argv in (["claude-opus-5-5", "1"], ["claude-opus-5-5", "02"], ["claude-opus-5-5", "21"], ["claude-opus-5-5", "x"], ["claude-opus-5-5"], ["9", "claude-opus-5-5"]):
|
||||
for argv in (["claude-opus-5-5", "1"], ["claude-opus-5-5", "02"], ["claude-opus-5-5", "21"], ["claude-opus-5-5", "x"], ["claude-opus-5-5"], ["9", "claude-opus-5-5"], ["claude-opus-5-5", "9", "--plan"], ["--planning", "claude-opus-5-5", "9"]):
|
||||
result = self.run_tool(*argv)
|
||||
self.assertEqual((result.returncode, result.stdout), (1, ""), argv)
|
||||
self.assertIn("usage: subagent-rung <model> <R+C>", result.stderr)
|
||||
self.assertIn("usage: subagent-rung [--plan] <model> <R+C>", result.stderr)
|
||||
|
||||
def test_the_launcher_prints_the_rung_and_exits_0_on_and_off_the_ladder(self):
|
||||
on = self.run_tool("claude-opus-5-5", "12")
|
||||
@@ -38,7 +43,7 @@ class SubagentRung(unittest.TestCase):
|
||||
for bound, rung in (("2", "model haiku, effort xhigh\n"), ("20", "model fable, effort max\n")):
|
||||
self.assertEqual(self.run_tool("claude-opus-5-5", bound).stdout, rung)
|
||||
for flag in ("-h", "--help"):
|
||||
self.assertIn("usage: subagent-rung <model> <R+C>", self.run_tool(flag).stdout)
|
||||
self.assertIn("usage: subagent-rung [--plan] <model> <R+C>", self.run_tool(flag).stdout)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -1712,3 +1712,23 @@ Inherited architect, decided by:
|
||||
- Shape: `bin/judge_replay/main.py:31` imports: one launcher reaching into five `loop_claude` internals, balanced by `judge`, `judge_once` and `judge_args` in `bin/loop_claude/cycle/judge.py:123` now three units with truthful names
|
||||
- Locality: `bin/loop_claude/routing.py:51` `judge_rung`: derives its own anchor from the judge model while `Cycle.anchor` is the worker's, so "anchor" means two rungs in one cycle when the models differ
|
||||
- Self-sufficiency: `bin/loop_claude/routing.py:54` `judge_rung` docstring: points into the plan at item 136, and `JUDGE_REPLAYED` and `REFERENCE_EFFORT` rest on a past replay and a past settings value the code cannot show
|
||||
|
||||
## 2026-10-15T14:08:19Z, PR #273 at f13447f, against b281392
|
||||
|
||||
Ruling: same
|
||||
|
||||
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
||||
|---|---|---|---|---|---|
|
||||
| Mid A | same | same | better | same | same |
|
||||
| Inherited architect | same | worse | same | same | same |
|
||||
|
||||
Mid A, decided by:
|
||||
|
||||
- Shape: `bin/model_routing/ladder.py:52` `floored`: names the rule "the rung R + C picks, never below the project's rung" beside `picked`, for two callers, where the base built it inline in `judge_rung` from `highest` and `item_rung`
|
||||
|
||||
Inherited architect, decided by:
|
||||
|
||||
- Locality: `rules/todo-items.md:9` "Plan only on the project's rung or above": the planning rule spans the rule file, `CLAUDE.md:55`, `bin/subagent_rung/main.py`'s help and `ladder.floored`, with no one file holding it whole
|
||||
- Locality: `bin/loop_claude/cycle/prompts.py:34` `off_the_projects_rung`: the prompt spells out another tool's command line, `subagent-rung --plan`, with nothing tying the two, and its docstring points to `routing.first_route` in another module
|
||||
- Locality: `bin/loop_claude/routing.py:61` `judge_rung`: reads in one line and drops the two-way reference with `item_rung`, but writes the no-item branch a second time
|
||||
- Shape, Self-sufficiency: `bin/model_routing/ladder.py:52` `floored`: a truthfully named helper, offset by `bin/subagent_rung/main.py:23` `agent_args`'s boolean `planning` and position-sensitive `--plan` parsing
|
||||
|
||||
@@ -114,6 +114,12 @@
|
||||
|
||||
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, bar and weights 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.
|
||||
|
||||
## todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan; one below it drafts new items and changes to filed ones for a subagent at or above that rung to apply and score, and removes finished ones
|
||||
|
||||
2026-10-15, lilleman. Serves goal 1.1: a cheaper rung writes worse scores, and a wrong score routes a chunk onto the wrong rung, ranks the plan wrong and drops an item under the bar that should stay. Below the project's rung, a session or subagent may not score an item, move it between releases, split a milestone, delete an item under the bar, or rewrite a filed item. It drafts each new item, and each change to a filed item, such as a refresh a rule asks for. Before the next commit, one subagent on the project's rung or above applies and scores the drafts. One launch covers all of a chunk's drafts (goal 1.4). A security finding gets that subagent at once, since it is filed the moment it is found. Removing a finished item closes work and plans none, so any rung does it. Scoring a delegated task's R + C runs on any rung too: a launch on the project's rung to score each delegation would cost more than the cheaper task saves (goal 1.4).
|
||||
|
||||
Three places carry the rule. `rules/todo-items.md` states it and loads with `todo.md`. `CLAUDE.md`'s delegation rule launches the scoring subagent on the rung `bin/subagent-rung --plan` prints: the one the task's R + C picks, never below the project's, so a hard scoring task still climbs. `bin/loop_claude/cycle/prompts.py`'s `off_the_projects_rung` names the same command to a worker below the project's rung, never a fixed rung, which would disagree with `--plan` on a scoring task of R + C 11 or more. Valid while a worker or subagent may run below the project's rung.
|
||||
|
||||
## settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped
|
||||
|
||||
2026-10-04, lilleman, answering the principles audit of PR #215. Serves goal 1: this setup is meant to run in a sandbox and to work autonomously, so tool access is granted by the sandbox, as "Always grant explicit access to data" in `principles/technical-principles.md` asks. Valid while every machine taking this checkout is such a sandbox.
|
||||
|
||||
@@ -333,3 +333,20 @@ Read most (opens and searches):
|
||||
- `bin/claude_code/entries.py` 1
|
||||
- `bin/claude_code/trust.py` 1
|
||||
- `bin/git_command.py` 1
|
||||
|
||||
## Reading cost, chunk d99303ae50a1, finished 2026-10-15T13:40:09Z
|
||||
|
||||
120770 new input tokens before the first commit.
|
||||
|
||||
Read most (opens and searches):
|
||||
|
||||
- `bin/loop_claude/cycle/judge.py` 8
|
||||
- `todo.md` 4
|
||||
- `README.md` 3
|
||||
- `.gitignore` 2
|
||||
- `bin/loop_claude/cycle/run.py` 2
|
||||
- `bin/loop_claude/effects.py` 2
|
||||
- `bin/loop_claude/loop/main.py` 2
|
||||
- `bin/loop_claude/project/model_choice.py` 2
|
||||
- `docs/decisions.md` 2
|
||||
- `rules/todo-items.md` 2
|
||||
|
||||
@@ -6,6 +6,7 @@ paths:
|
||||
# Todo items (`todo.md`)
|
||||
|
||||
- **`todo.md` is mandatory in every project, in one shape**, which `~/.claude/bin/rank_todo.py` checks and ranks; its `--help` shows a valid file. `## Scoring` holds the formula, the bar and the goal weights; `## Items` is one table of every item; `## Details` holds each item's detail under its ID. Cite an item by its ID. The formula, bar and weights are the project's own to tune.
|
||||
- **Plan only on the project's rung or above.** loop-claude's prompt tells you when you run below it. Below it, never score or re-score an item, move it between releases, split a milestone into items, delete an item under the bar, or rewrite a filed item's tagline or detail. Draft each new item, and each change to a filed item, instead. Before your next commit, launch one subagent to apply the drafts, score them and set their release. Launch it on the rung `CLAUDE.md`'s delegation rule gives a subagent that files or scores items. Keep the scores and releases it writes. For a security finding, launch it at once. Any rung may remove a finished item's row and detail, and score a delegated task's R + C. A subagent launched for another task leaves `todo.md` alone.
|
||||
- **An item's release allows the bump that semver read strictly asks for.** An item that changes what exists needs a major, or before 1.0.0 a minor. One that only adds needs a minor, and a fix a patch.
|
||||
- **Score an item when it is filed or edited.** Each of R, S, C, A and G is a whole number from 1 to 10:
|
||||
- **R** — the risk that the change creates serious bugs or issues.
|
||||
|
||||
@@ -22,14 +22,11 @@
|
||||
|
||||
## Items
|
||||
|
||||
Release 0.1.0 takes item 141 first, whatever its score: item 142's first trigger needs its rule.
|
||||
|
||||
Release 0.2.0 takes items 125, 114 and 124 first, whatever their scores: Shape is the lowest dimension, per `docs/decisions.md` → `larv-review: a project lifting itself to the comprehension floor starts at the lowest dimension`.
|
||||
|
||||
| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 142 | 0.1.0 | | **Let a chunk's worker hand a task to a subagent one rung up when an escalation trigger fires, at most two rungs above the rung it started the chunk on without the human's yes.** | 4 | 5 | 6 | 7 | 8 | 1.1, 1.4 | 24.6 |
|
||||
| 141 | 0.1.0 | | **Score and reshape the plan only on the project's rung or above, and let a worker or subagent below it only draft new items and remove finished ones.** | 3 | 4 | 4 | 6 | 8 | 1.1 | 23.8 |
|
||||
| 144 | 0.1.0 | | **Let a reviewer or comprehension seat that rules the work below standard rerun its review one rung up, outside the round cap, and let the worker escalate under item 142.** | 4 | 5 | 6 | 6 | 7 | 1.1 | 20.6 |
|
||||
| 145 | 0.1.0 | | **Run the stability reviewer on the worker's rung while the worker runs below the project's rung, once a replay of past stability rounds on that rung finds the 🔴 and 🟡 findings on record.** | 4 | 5 | 6 | 6 | 7 | 1.4 | 20.2 |
|
||||
| 143 | 0.1.0 | | **Resume a worker one rung up in the next cycle when its run ends asking for a higher rung and the judge finds the escalation trigger it cites in the transcript.** | 5 | 5 | 7 | 6 | 7 | 1.1, 1.4 | 19.6 |
|
||||
@@ -95,7 +92,7 @@ Release 0.2.0 takes items 125, 114 and 124 first, whatever their scores: Shape i
|
||||
|
||||
The human asked for this on 2026-10-15. Four triggers mean a task is too hard for the worker's rung:
|
||||
|
||||
1. A re-score of the item, made on the project's rung per item 141, picks a higher rung than the worker's.
|
||||
1. A re-score of the item, made on the project's rung or above, as `rules/todo-items.md` requires, picks a higher rung than the worker's.
|
||||
2. The same failing test or finding survives two fix attempts.
|
||||
3. A pass reports a 🔴 in round 2 or later, as the `Answer <pass> round <n>:` commit titles show.
|
||||
4. A reviewer or comprehension seat rules the work below standard, per item 144.
|
||||
@@ -104,27 +101,6 @@ When one fires, the worker hands the hard part to a subagent one rung above its
|
||||
|
||||
This revises `docs/decisions.md` → `routing: one ladder`, where the worker routes each subagent by its task's R + C alone, and the delegation rule in `CLAUDE.md`. The comprehension seats found it hard to follow which model a subagent gets: `CLAUDE.md`'s delegation rule, `bin/loop_claude/cycle/prompts.py`'s `off_the_projects_rung` and `bin/model_routing/ladder.py`'s `Rung.agent_args` each hold part of it. Make it easier to read.
|
||||
|
||||
### 141. Score and reshape the plan only on the project's rung or above, and let a worker or subagent below it only draft new items and remove finished ones.
|
||||
|
||||
The human set this rule on 2026-10-15. The project's rung is the cheapest rung of the model `loop-claude-models.json` pins, or of the session's own model outside loop-claude. Below that rung, a worker or subagent may not:
|
||||
|
||||
- score or re-score an item;
|
||||
- move an item between releases;
|
||||
- split a milestone into items;
|
||||
- delete an item under the bar;
|
||||
- rewrite an item's tagline or detail once it is filed.
|
||||
|
||||
Any rung may:
|
||||
|
||||
- remove a finished item's row and detail, which closes work and plans none;
|
||||
- score a delegated task's R + C to pick its subagent's rung, since launching a subagent on the project's rung to score each delegation would cost more than running the task on a cheaper rung saves.
|
||||
|
||||
A worker below the project's rung drafts each new item's tagline and detail. Before its next commit, one subagent on the project's rung files and scores the drafts together and sets their release. A security finding gets that subagent at once, since it is filed the moment it is found.
|
||||
|
||||
Write the rule in `rules/todo-items.md`, which loads with `todo.md`. Add to `CLAUDE.md`'s delegation rule: a scoring or planning subagent runs on the rung `subagent-rung` prints, or on the project's rung where that is higher. In `bin/loop_claude/cycle/prompts.py`'s `off_the_projects_rung`, add the scoring and planning subagent to those a worker below the project's rung launches on the project's rung. Three places carry the rule, so record it in `docs/decisions.md`.
|
||||
|
||||
The comprehension seats found it hard to follow which model a subagent gets: `CLAUDE.md`'s delegation rule, `off_the_projects_rung` and `bin/model_routing/ladder.py`'s `Rung.agent_args` each hold part of it. Make it easier to read.
|
||||
|
||||
### 144. Let a reviewer or comprehension seat that rules the work below standard rerun its review one rung up, outside the round cap, and let the worker escalate under item 142.
|
||||
|
||||
The human asked for this on 2026-10-15, and for the worker to escalate too. A reviewer rules the work below standard when it reports an architect BLOCK or a finding against `skills/larv-review/standards/quality.md`. It may then ask for its pass to rerun one rung up, and that rerun counts toward no round cap. A comprehension seat rules it below standard when it votes "worse" in a paired ruling. It may then ask for the ruling to rerun with its seat one rung up. Either ruling is trigger 4 of item 142. No ruling raises the judge's own rung.
|
||||
@@ -229,7 +205,7 @@ Junior A and Mid A of PR #257's scoring run named `bin/shell_command.py:31` `seg
|
||||
|
||||
### 140. Split `docs/decisions.md` → `routing: one ladder` into one entry per decision, so a reader finds the rules for the ladder, the worker's rung, the routing figures and delegation by their titles.
|
||||
|
||||
The entry holds 7 paragraphs under one title of about 70 words chaining three decisions: the ladder and bands, the worker below the project's rung with its reviewers, the routing figures and calls, delegation, and when the worker changes rung. A reader after one rule reads the whole entry. The prose pass of the chunk that split out the judge's rung asked for the rest.
|
||||
The entry holds 7 paragraphs under one title of about 70 words chaining three decisions: the ladder and bands, the worker below the project's rung with its reviewers, the routing figures and calls, delegation, and when the worker changes rung. A reader after one rule reads the whole entry. The prose pass of the chunk that split out the judge's rung asked for the rest. Once split, the delegation entry's title names the floor that `todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan…` puts under a subagent that files or scores items.
|
||||
|
||||
### 114. Run git through `git_repo.py` in `rule_hook`, `metric_bench`, `reading_cost` and `loop_claude`, keeping rule-hook's guards as an option, so one module owns how a tool runs git.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user