Merge pull request 'Split review_launches into model_routing's choice of each review's rung and whole prompt sentences that render it' (#359) from item-212 into main

This commit was merged in pull request #359.
This commit is contained in:
2026-10-23 04:06:02 +02:00
10 changed files with 178 additions and 75 deletions
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- loop-claude's first prompt for a chunk that no plan item routed now also names the rung on which the worker launches its reviews for an item it takes in, as the prompt after a step-up or an unfinished verdict already did.
- `loop-claude --help` now describes routing in two short paragraphs for the person running the loop. The rules it used to repeat are now stated once, in the code that enforces them.
- loop-claude now archives the route on each `Worker:` line as a JSON record, such as `{"model": "claude-opus-5-5", "effort": "high", "item": 3, "likelihood": 4, "escape_and_impact": 5, "escalated_at": 12}`, and reads it back field by field. The line used to be a sentence, such as `claude-opus-5-5 at high effort, routed by item 3's L of 4 and E + I of 5`, which loop-claude parsed back word for word: rewording the sentence in the code would have made every archived line unreadable, and a rerun would have routed the open chunk afresh. A rerun and the routing figures still read the sentences archived since loop-claude routed on L. A rerun that finds a `Worker:` line it can't read now says so on stderr. The judge's reply now names the levels the worker took in `highest_likelihood_taken_in` and `highest_escape_and_impact_taken_in`, in place of `bundled` and `bundled_escape_and_impact`.
- A chunk now takes every unblocked item of its release that fires the same review passes, whatever its purpose: one PR title no longer has to state what the items achieve together. An item with R above 5 ships alone. `chunk-preflight` says so for such an item, and never lists one as an item that may join another.
+70 -64
View File
@@ -1,6 +1,7 @@
"""What loop-claude says to the worker each cycle. routed_by, review_launches, escalation and reruns build the sentences about its rungs; rungs_held says the last three again in a prompt after a step-up or an unfinished verdict."""
from model_routing.ladder import climbed, LADDER, position, review_rungs, reviewers_rung, ReviewKind, Rung
from model_routing.route import ESCALATION_MARKER, HIGHEST_ESCAPE_AND_IMPACT, Route
"""What loop-claude says to the worker each cycle. model_routing.review_choice chooses where the reviews run. review_launches and reruns put that choice into sentences, and escalation says where escalated subagents run; rung_sentences returns the sentences of all three. In a chunk's first prompt, routed_by places them after its routing sentences where an item routed the chunk, and fresh places them alone otherwise. rungs_held repeats them at the end of a prompt after a step-up or an unfinished verdict."""
from model_routing.review_choice import chosen, ReviewChoice
from model_routing.ladder import climbed, LADDER, position, Rung
from model_routing.route import ESCALATION_MARKER, Route
from loop_claude.routing import escalation_rungs
from loop_claude.project.records import HUMAN_RULE_NAMES, RECORD_FILES
from markdown_text import listed, quoted
@@ -12,8 +13,10 @@ QUOTE_SOURCES = listed(("README.md's Goals and Audience", *RECORD_FILES, *HUMAN_
# Where the worker may write an answer the human typed, so it counts as recorded.
ANSWER_DESTINATIONS = "README.md's Goals or Audience, " + ", ".join(RECORD_FILES) + ", todo.md or a comment"
ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could need is recorded in {ANSWER_DESTINATIONS} at the one place it governs"
# Each kind of review, as review_launches names those it launches: a row per pass, since a replay may lower one pass alone. "each reviewer" names every pass no replay lowered.
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"))
# How review_launches names the reviews: "each reviewer" covers every pass with an agent that no replay lowered.
EACH_REVIEWER = "each reviewer"
EACH_SEAT = "each comprehension seat"
THE_SECURITY_PASS = "the security pass's subagent"
AFTER_CODE_HEALTH = 'which rank after code health (~/.claude/CLAUDE.md → "Shared goal") unless README.md voids it'
@@ -21,18 +24,22 @@ AFTER_CODE_HEALTH = 'which rank after code health (~/.claude/CLAUDE.md → "Shar
def fresh(task: str, premises: str, route: Route, project: Rung | None, facts: str) -> str:
"""A chunk's first prompt; facts is preflight_facts' or preflight_failed's text."""
escalated = f"{escalation(route, project)}{reruns(route, project)}".lstrip()
routed = f"{routed_by(route, project)}{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, {AFTER_CODE_HEALTH}, choose between ways to deliver that scope, and never widen it.\n\nFrom README.md:\n{premises}"
routed = f"{routed_by(route, project)} {recount(route)}" if route.item else " ".join(rung_sentences(route, project))
opening = f"{routed}\n\n" if routed else ""
return f"{task}\n\nContinue any open draft PR or worktree for the chunk before creating a new one.\n\n{opening}{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, project: Rung | None) -> str:
return f"loop-claude runs you on {route.rung}, routed by item {route.item}'s L of {route.likelihood}. Name each todo.md item this chunk takes, with its L and E + I, whether or not it is item {route.item}.{review_launches(route, project)}{escalation(route, project)}{reruns(route, project)}"
return " ".join((
f"loop-claude runs you on {route.rung}, routed by item {route.item}'s L of {route.likelihood}.",
f"Name each todo.md item this chunk takes, with its L and E + I, whether or not it is item {route.item}.",
*rung_sentences(route, project),
))
def recount(route: Route) -> str:
"""Has the worker count the routing item's size again once it knows the code, since the L that routed it was scored before anyone read that code."""
return f" After your first read of the code, count item {route.item}'s size again: the lines, files and components you will change. Where that count would change its L, have a subagent that scores todo.md items re-score it; a re-score whose L picks a rung above yours is escalation trigger 1."
return f"After your first read of the code, count item {route.item}'s size again: the lines, files and components you will change. Where that count would change its L, have a subagent that scores todo.md items re-score it; a re-score whose L picks a rung above yours is escalation trigger 1."
def preflight_facts(printed: str) -> str:
@@ -45,50 +52,44 @@ def preflight_failed(reason: str) -> str:
return f"loop-claude could not run `~/.claude/bin/chunk-preflight`, so find the chunk's facts yourself. Why it could not run: {reason}"
def review_launches(route: Route, project: Rung | None) -> str:
"""Which reviews to launch on a rung other than the worker's, and on which, then the rung of each pass a replay lowered; below the project's rung also where to launch a subagent that files or scores todo.md items; then taken_in_launches, the reviewers' rung each higher E + I picks. Empty off the ladder.
def review_launches(route: Route, project: Rung | None) -> list[str]:
"""The sentences naming where to launch reviews, in this order; none off the ladder:
- one for each rung, other than the worker's, that a reviewer, a seat or the security pass runs on;
- the rung of each pass a replay lowered;
- where the security pass runs on another rung than the worker's, that a full scan runs only from its subagent;
- where the worker runs below the project's rung, where to launch a subagent that files or scores todo.md items;
- the reviewers' rung each higher E + I picks.
For a worker on Sonnet 5.5 at high, on an Opus 5.5 project, routed by item 3 of E + I 5, it opens: ` Launch each reviewer with the Agent tool set to model opus, effort high, the rung item 3's E + I of 5 picks. Launch each comprehension seat and the security pass's subagent with the Agent tool set to model opus, effort medium, the project's rung.` Where a replay lowered the prose pass to Haiku 5.5 at low, and the E + I steps no review up, a sentence follows: ` Launch each prose-reviewer instead with the Agent tool set to model haiku, effort low, the rung the replay of its pass chose.`
For a worker on Sonnet 5.5 at high, on an Opus 5.5 project, routed by item 3 of E + I 5, they open: `Launch each reviewer with the Agent tool set to model opus, effort high, the rung item 3's E + I of 5 picks.` and `Launch each comprehension seat and the security pass's subagent with the Agent tool set to model opus, effort medium, the project's rung.` Where a replay lowered the prose pass to Haiku 5.5 at low, and the E + I steps no review up, a sentence follows: `Launch each prose-reviewer instead with the Agent tool set to model haiku, effort low, the rung the replay of its pass chose.`
"""
if project is None:
return ""
rungs, reviewers = review_rungs(project, route.rung, route.reviewed_on()), reviewers_rung(project, route.rung, route.reviewed_on())
lowered_launches = "".join(f" Launch {reviews} instead with the Agent tool set to {rung.agent_args()}, the rung the replay of its pass chose." for reviews, rung in lowered(rungs, reviewers))
scan = " Run a full scan only from such a subagent, since the scan's agents run on the model that starts them." if rungs["security"] != route.rung else ""
planning = f" Your rung is below the project's: launch each subagent that files or scores todo.md items on the rung `~/.claude/bin/subagent-rung --plan {project.model} <L>` prints." if position(route.rung) < position(project) else ""
return f"{shared_launches(rungs, reviewers, route, project)}{lowered_launches}{scan}{planning}{taken_in_launches(route, project)}"
return []
choice = chosen(project, route)
lowered = [f"Launch each {REVIEWERS[kind]} instead with the Agent tool set to {rung.agent_args()}, the rung the replay of its pass chose." for kind, rung in choice.lowered.items()]
scan = ["Run a full scan only from such a subagent, since the scan's agents run on the model that starts them."] if choice.security != route.rung else []
planning = [f"Your rung is below the project's: launch each subagent that files or scores todo.md items on the rung `~/.claude/bin/subagent-rung --plan {project.model} <L>` prints."] if position(route.rung) < position(project) else []
return [*shared_launches(choice, route, project), *lowered, *scan, *planning, *taken_in_launches(choice)]
def shared_launches(rungs: dict[ReviewKind, Rung], reviewers: Rung, route: Route, project: Rung) -> str:
"""A sentence for each rung other than the worker's that a review runs on. "each reviewer" names every pass no replay lowered; those run on reviewers."""
together = {"each reviewer": reviewers} | {reviews: rungs[kind] for reviews, kind in REVIEWS if kind not in REVIEWERS}
def shared_launches(choice: ReviewChoice, route: Route, project: Rung) -> list[str]:
"""A sentence for each rung, other than the worker's, that the reviewers no replay lowered, the seats or the security pass run on."""
together = {EACH_REVIEWER: choice.reviewers, EACH_SEAT: choice.seat, THE_SECURITY_PASS: choice.security}
launched: dict[Rung, list[str]] = {}
for reviews, rung in together.items():
if rung != route.rung:
launched.setdefault(rung, []).append(reviews)
return "".join(f" Launch {listed(reviews, 'and')} with the Agent tool set to {rung.agent_args()}, {rung_named(rung, route, project)}." for rung, reviews in launched.items())
return [f"Launch {listed(reviews, 'and')} with the Agent tool set to {rung.agent_args()}, {rung_named(rung, route, project)}." for rung, reviews in launched.items()]
def lowered(rungs: dict[ReviewKind, Rung], reviewers: Rung) -> list[tuple[str, Rung]]:
"""Each pass a replay put below reviewers, the rung of every other pass, as REVIEWS names it, with the rung the replay chose."""
return [(reviews, rungs[kind]) for reviews, kind in REVIEWS if kind in REVIEWERS and rungs[kind] != reviewers]
def taken_in_launches(choice: ReviewChoice) -> list[str]:
"""The sentence naming the reviewers' rung each higher E + I picks, so the worker reviews an item it takes in on that rung in the same run, since the judge reports a taken-in item's E + I only as the cycle ends, and loop-claude routes on it from the next cycle. None where no higher E + I picks a higher rung.
def taken_in_launches(route: Route, project: Rung) -> str:
"""The rung each higher E + I picks for the reviewers, so the worker reviews an item it takes in on that rung in the same run; the judge reports it as the cycle ends, so loop-claude routes on it only from the next cycle. Empty where no higher E + I picks a higher rung.
For a worker on Opus 5.5 at medium, routed by an item of E + I 6, it reads: ` Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort max` from 7 and `model fable, effort max` from 8.`
For a worker on Opus 5.5 at medium, on an Opus 5.5 project, routed by an item of E + I 6, it reads: `Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort max` from 7 and `model fable, effort max` from 8.`
"""
now = review_rungs(project, route.rung, route.reviewed_on())
higher: dict[Rung, int] = {}
for escape_and_impact in range(route.reviewed_on() + 1, HIGHEST_ESCAPE_AND_IMPACT + 1):
# An E + I that lifts any pass puts every pass on reviewers_rung, since a replay lowers a pass only where the E + I steps no review up.
if review_rungs(project, route.rung, escape_and_impact) != now:
higher.setdefault(reviewers_rung(project, route.rung, escape_and_impact), escape_and_impact)
if not higher:
return ""
picks = [f"`{rung.agent_args()}` from {escape_and_impact}" for rung, escape_and_impact in higher.items()]
return f" Where an item you take into the chunk has an E + I of {min(higher.values())} or more, launch each reviewer with the Agent tool set to {listed(picks, 'and')}."
if not choice.higher:
return []
picks = [f"`{rung.agent_args()}` from {escape_and_impact}" for rung, escape_and_impact in choice.higher.items()]
return [f"Where an item you take into the chunk has an E + I of {min(choice.higher.values())} or more, launch {EACH_REVIEWER} with the Agent tool set to {listed(picks, 'and')}."]
def rung_named(rung: Rung, route: Route, project: Rung) -> str:
@@ -100,50 +101,50 @@ def rung_named(rung: Rung, route: Route, project: Rung) -> str:
return f"the rung item {route.item}'s E + I of {route.escape_and_impact} picks"
def escalation(route: Route, project: Rung | None) -> str:
"""The prompt's escalation sentences, the marker's among them, each led by a space. Empty off the ladder or on its top rung. Where escalation_rungs opens none, the worker escalates only with the human's yes.
def escalation(route: Route, project: Rung | None) -> list[str]:
"""The prompt's escalation sentences, the marker's among them. None off the ladder or on its top rung. Where escalation_rungs opens none, the worker escalates only with the human's yes.
Else they name the rungs escalation_rungs opens to a subagent, and offer to resume the worker one rung up for the rest of the chunk, up to the highest of those rungs.
For a worker on Opus 5.5 at high, on an Opus 5.5 project, routed by item 3 of L 4, they read: ` When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort xhigh`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort max`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number. Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model opus, effort max`.`
For a worker on Opus 5.5 at high, on an Opus 5.5 project, routed by item 3 of L 4, they read: `When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort xhigh`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort max`; above that, ask the human first.`, `Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.` and `Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model opus, effort max`.`
"""
if project is None or route.rung not in LADDER[:-1]:
return ""
return []
marked = f"Open the subagent's prompt with `{ESCALATION_MARKER} <n>:`, n the trigger's number."
rungs = [f"`{rung.agent_args()}`" for rung in escalation_rungs(project, route)]
if not rungs:
return " " + " ".join((
return [
f"An escalation trigger in `~/.claude/CLAUDE.md` lets you hand the hard part of a task to a subagent with the Agent tool set to `{climbed(route.rung, 1).agent_args()}`, one rung above yours, only once the human agrees; loop-claude will not resume you higher for a trigger either, so ask the human for that yes.",
marked,
))
]
further = f", and on each further trigger one rung higher, up to {rungs[-1]}" if len(rungs) > 1 else ""
return " " + " ".join((
return [
f"When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to {rungs[0]}, one rung above yours{further}; above that, ask the human first.",
marked,
f"Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to {rungs[-1]}.",
))
]
def reruns(route: Route, project: Rung | None) -> str:
"""The prompt's sentences naming the rung one above a review's, on which it reruns when it asks: shared_reruns' for a reviewer and a seat, then one for each pass a replay lowered. Empty off the ladder.
def reruns(route: Route, project: Rung | None) -> list[str]:
"""The sentences naming the rung one above a review's, on which it reruns when it asks: shared_reruns' for a reviewer and a seat, then one for each pass a replay lowered. None off the ladder.
For a worker on Sonnet 5.5 at high, on an Opus 5.5 project whose prose pass a replay lowered to Haiku 5.5 at low, routed by an item of E + I 4, they read: ` A reviewer or comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `model opus, effort high`. Rerun each prose-reviewer that asks with the Agent tool set to `model haiku, effort medium` instead.`
For a worker on Sonnet 5.5 at high, on an Opus 5.5 project whose prose pass a replay lowered to Haiku 5.5 at low, routed by an item of E + I 4, they read: `A reviewer or comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `model opus, effort high`.` and `Rerun each prose-reviewer that asks with the Agent tool set to `model haiku, effort medium` instead.`
"""
if project is None or route.rung not in LADDER:
return ""
rungs, reviewers = review_rungs(project, route.rung, route.reviewed_on()), reviewers_rung(project, route.rung, route.reviewed_on())
lowered_reruns = "".join(f" Rerun {reviews} that asks with the Agent tool set to `{climbed(rung, 1).agent_args()}` instead." for reviews, rung in lowered(rungs, reviewers))
return f"{shared_reruns(reviewers, rungs['seat'])}{lowered_reruns}"
return []
choice = chosen(project, route)
lowered = [f"Rerun each {REVIEWERS[kind]} that asks with the Agent tool set to `{climbed(rung, 1).agent_args()}` instead." for kind, rung in choice.lowered.items()]
return [*shared_reruns(choice), *lowered]
def shared_reruns(reviewers: Rung, seats: Rung) -> str:
"""The sentence naming the rung one above reviewers, the rung of each pass no replay lowered, and one above seats, leaving out one already on the top rung."""
launched = (("reviewer", reviewers), ("comprehension seat", seats))
def shared_reruns(choice: ReviewChoice) -> list[str]:
"""The sentence naming the rung one above choice.reviewers and the one above choice.seat, leaving out either that is already on the top rung."""
launched = (("reviewer", choice.reviewers), ("comprehension seat", choice.seat))
rerun = {name: climbed(rung, 1) for name, rung in launched if rung != LADDER[-1]}
if not rerun:
return ""
return []
if len(set(rerun.values())) == 1:
return f" A {listed(list(rerun), 'or')} that asks for a rerun one rung up reruns with the Agent tool set to `{next(iter(rerun.values())).agent_args()}`."
return f" A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `{rerun['reviewer'].agent_args()}`, and a comprehension seat with `{rerun['comprehension seat'].agent_args()}`."
return [f"A {listed(list(rerun), 'or')} that asks for a rerun one rung up reruns with the Agent tool set to `{next(iter(rerun.values())).agent_args()}`."]
return [f"A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `{rerun['reviewer'].agent_args()}`, and a comprehension seat with `{rerun['comprehension seat'].agent_args()}`."]
def resumed(unfinished_evidence: str, route: Route, project: Rung | None) -> str:
@@ -153,9 +154,14 @@ def resumed(unfinished_evidence: str, route: Route, project: Rung | None) -> str
return f"Continue the task; the previous run ended before the chunk was finished.{ruled}The chunk is finished once it is merged, or nothing remains that you could do on your own. Even then, it is finished only once {ANSWERS_RECORDED}.{on}{rungs_held(route, project)}"
def rungs_held(route: Route, project: Rung | None) -> str:
def rung_sentences(route: Route, project: Rung | None) -> list[str]:
"""The sentences that depend on the worker's rung: where its reviews run and rerun, and where its escalated subagents run."""
return f"{review_launches(route, project)}{escalation(route, project)}{reruns(route, project)}"
return [*review_launches(route, project), *escalation(route, project), *reruns(route, project)]
def rungs_held(route: Route, project: Rung | None) -> str:
"""rung_sentences, each after a space, to follow the sentence a prompt ends on."""
return "".join(f" {sentence}" for sentence in rung_sentences(route, project))
def answered(question: str, answer: str, route: Route, project: Rung | None, stepped: bool) -> str:
+3 -2
View File
@@ -56,8 +56,9 @@ session /talk opens run on the rung that the chunk's todo.md item picks, and the
models on another; a chunk no item routes runs on the project's model. The worker's prompts name the
rungs it launches its reviews on. The worker's rung steps up as a chunk stays unfinished, or when
the judge finds in the transcript an escalation trigger that fired and the worker asked for a higher
rung. The rules are in bin/loop_claude/routing.py and bin/model_routing/ladder.py, and the prompts'
wording in bin/loop_claude/cycle/prompts.py. Each verdict, interrupt, quoted answer, stop and
rung. The rules are in bin/loop_claude/routing.py and bin/model_routing/ladder.py, the choice of
each review's rung in bin/model_routing/review_choice.py, and the prompts' wording in
bin/loop_claude/cycle/prompts.py. Each verdict, interrupt, quoted answer, stop and
step-up in the archive ends with a Worker: line, the route's JSON record (Route.record in
bin/model_routing/route.py); a rerun resumes an open chunk on the latest route named there. A
todo.md or an archive that cannot be read or parsed is said on stderr, and the chunk is routed
+1 -1
View File
@@ -1173,7 +1173,7 @@ class WorkerArgs(unittest.TestCase):
self.assertIn("hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort max`, one rung above yours;", prompts.resumed("", Route(Rung("claude-opus-5-5", "xhigh"), 3, 4, 5), opus))
self.assertNotIn("escalation", prompts.resumed("", Route(Rung("m")), None))
self.assertNotIn("escalation", prompts.resumed("", Route(Rung("claude-opus-5-5", "low"), 3, 3, 4), opus))
self.assertIn("before creating a new one.\n\nWhen an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort high`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort xhigh`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number. Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model opus, effort xhigh`. A reviewer", prompts.fresh("Do it.", "## Goals", Route(opus), opus, self.FACTS))
self.assertIn("before creating a new one.\n\nWhere an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model opus, effort high` from 5, `model opus, effort xhigh` from 6, `model opus, effort max` from 7 and `model fable, effort max` from 8. When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort high`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort xhigh`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number. Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model opus, effort xhigh`. A reviewer", prompts.fresh("Do it.", "## Goals", Route(opus), opus, self.FACTS))
def test_offers_the_worker_a_higher_rung_for_the_rest_of_the_chunk_up_to_the_escalation_cap(self):
opus = Rung("claude-opus-5-5", "medium")
+6 -1
View File
@@ -105,11 +105,16 @@ def review_rungs(project: Rung, worker: Rung, escape_and_impact: int) -> dict[Re
A pass's reviewer runs on reviewers_rung. Where the E + I steps no review up and the worker runs no higher than the project's rung, a pass whose replay chose a rung for the project's model runs on that rung instead, even below the worker's: the replay compared reviews on the project's rung only, never on a rung an E + I stepped up, nor of a chunk whose worker climbed above the project's rung. A seat and the security pass run on the project's rung, so the seats score every chunk on one rung, and the security pass spends no more than the project chose.
"""
rungs: dict[ReviewKind, Rung] = {**dict.fromkeys(REVIEWERS, reviewers_rung(project, worker, escape_and_impact)), "seat": project, "security": project}
if escape_and_impact not in REVIEW_STEPS and position(worker) <= position(project):
if replay_applies(project, worker, escape_and_impact):
rungs |= {kind: rung for (kind, model), rung in REPLAYED.items() if model == project.model}
return rungs
def replay_applies(project: Rung, worker: Rung, escape_and_impact: int) -> bool:
"""Whether a pass's replay chose its rung for a chunk like this: only where the E + I steps no review up and the worker runs no higher than the project's rung."""
return escape_and_impact not in REVIEW_STEPS and position(worker) <= position(project)
def reviewers_rung(project: Rung, worker: Rung, escape_and_impact: int) -> Rung:
"""The rung of each pass's reviewer that no replay lowered: the higher of the worker's rung and review_floor's."""
return highest(worker, review_floor(project, escape_and_impact))
+32
View File
@@ -0,0 +1,32 @@
"""Where a chunk's reviews run, chosen from its route and the project's rung."""
import dataclasses
from model_routing.route import HIGHEST_ESCAPE_AND_IMPACT, Route
from model_routing.ladder import replay_applies, review_rungs, reviewers_rung, Rung
from review_passes import ReviewedPass, REVIEWERS
@dataclasses.dataclass(frozen=True)
class ReviewChoice:
# The rung of each pass's reviewer that no replay lowered.
reviewers: Rung
# The passes whose replay chose another rung, with that rung.
lowered: dict[ReviewedPass, Rung]
seat: Rung
security: Rung
# Each rung a higher E + I than the route's picks for the reviewers, with the lowest E + I that picks it, in rising order.
higher: dict[Rung, int]
def chosen(project: Rung, route: Route) -> ReviewChoice:
"""The rung each kind of review runs on for a chunk whose route is route, on a project whose rung is project."""
rungs = review_rungs(project, route.rung, route.reviewed_on())
reviewers = reviewers_rung(project, route.rung, route.reviewed_on())
lowered = {kind: rungs[kind] for kind in REVIEWERS if rungs[kind] != reviewers}
higher: dict[Rung, int] = {}
for escape_and_impact in range(route.reviewed_on() + 1, HIGHEST_ESCAPE_AND_IMPACT + 1):
# A higher E + I changes a review by moving the reviewers' rung, or by ending the replay that lowered a pass.
rung = reviewers_rung(project, route.rung, escape_and_impact)
if rung != reviewers or (lowered and not replay_applies(project, route.rung, escape_and_impact)):
higher.setdefault(rung, escape_and_impact)
return ReviewChoice(reviewers, lowered, rungs["seat"], rungs["security"], higher)
+26
View File
@@ -0,0 +1,26 @@
import unittest
import unittest.mock
from model_routing.review_choice import chosen, ReviewChoice
from model_routing import ladder
from model_routing.route import Route
from model_routing.ladder import Rung
HAIKU = Rung("claude-haiku-5-5", "low")
OPUS = Rung("claude-opus-5-5", "medium")
OPUS_MAX = Rung("claude-opus-5-5", "max")
FABLE = Rung("claude-fable-5-1", "max")
SONNET = Rung("claude-sonnet-5-5", "high")
class Chosen(unittest.TestCase):
def test_names_no_higher_rung_on_the_top_one(self):
self.assertEqual(chosen(OPUS, Route(FABLE, 3, 4, 5)).higher, {})
def test_names_the_e_plus_i_that_ends_a_replay_even_where_the_reviewers_are_on_the_top_rung(self):
with unittest.mock.patch.dict(ladder.REPLAYED, {("prose", "claude-fable-5-1"): HAIKU}):
self.assertEqual(chosen(FABLE, Route(OPUS_MAX, 3, 4, 4)), ReviewChoice(FABLE, {"prose": HAIKU}, FABLE, FABLE, {FABLE: 5}))
def test_puts_every_pass_on_the_reviewers_rung_once_an_e_plus_i_steps_a_review_up(self):
with unittest.mock.patch.dict(ladder.REPLAYED, {("prose", "claude-opus-5-5"): HAIKU}):
self.assertEqual(chosen(OPUS, Route(SONNET, 3, 2, 5)).lowered, {})
+29
View File
@@ -2545,3 +2545,32 @@ Inherited architect, decided by:
- Self-sufficiency, Locality: `bin/model_routing/route.py:13` `Record`: the archived worker line is a typed JSON record the outcome writers alone accept, with a warning that renaming a field orphans records; the legacy regex is unannotated and R + C lines fall through `rung_at` as text without a docstring saying so
- Navigation, Self-sufficiency: `bin/loop_claude/verdicts.py:1` "verdicts": its own module, with field comments stating what `entries_read=None` means
- Self-sufficiency: `bin/todo_table.py:205` `ships_alone`: the R above 5 rule is one named function, where the base held it only in the charter
## 2026-10-23T02:05:49Z, PR #359 at 72a63c5, against 545ab3a
Ruling: better
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Mid A | better | better | better | better | better |
| Inherited architect | better | better | better | better | better |
Mid A, decided by:
- Locality, Shape, Overall: `bin/model_routing/review_choice.py:21` `chosen`: the choice of each review's rung has one home, returned as a ReviewChoice; before, three functions in prompts.py each worked it out
- Locality, Shape: `bin/loop_claude/cycle/prompts.py:62` `review_launches`: the sentence builders return lists of sentences and one join adds the spaces, where each fragment had to start with a space
- Shape: `bin/loop_claude/routing.py:331` `first_route`: the parameter anchor is now called project, so docstrings no longer explain it
- Navigation, Self-sufficiency: `bin/loop_claude/routing.py:1` "module docstring": it lists the unit for each routing phase, where the base pointed to docs/decisions.md
- Navigation: `bin/loop_claude/loop/main.py:54` "loop-claude --help": about 90 lines of routing text are one paragraph that names the file for each concern
- Self-sufficiency, Navigation: `bin/loop_claude/cycle/prompts.py:1` "module docstring": new, says which function makes which sentence group and where each lands
- Locality: `bin/model_routing/ladder.py:113` `replay_applies`: the condition for when a replay applies is a named function shared by review_rungs and chosen
Inherited architect, decided by:
- Locality, Shape, Overall: `bin/loop_claude/cycle/prompts.py:55` `review_launches`: the choice is made once in chosen and the prompt code turns it into lists of sentences; the base called review_rungs again in three functions
- Shape: `bin/loop_claude/cycle/prompts.py:17` `EACH_REVIEWER`: the REVIEWS table of wording and kind pairs, filtered in two places, is gone
- Navigation, Self-sufficiency: `bin/loop_claude/routing.py:1` "module docstring": a four-line map of Start, Rerun, Step-up and Judge naming the function for each, in place of about 90 lines of routing prose in the help
- Navigation: `bin/loop_claude/loop/main.py:54` "loop-claude --help": the routing paragraph names a file for each concern
- Navigation: `bin/loop_claude/cycle/prompts.py:1` "module docstring": says which function builds which part of each prompt
- Shape, Locality: `bin/model_routing/ladder.py:113` `replay_applies`: the replay condition has one name, shared by review_rungs and chosen
- Shape: `bin/loop_claude/cycle/run.py:41` `Cycle.project`: the rename from anchor removes the repeated explanation
+8
View File
@@ -799,3 +799,11 @@ Read most (opens and searches):
## Reading cost, chunk a38d4733c268, finished 2026-10-22T20:33:05Z
207415 new input tokens before the first commit.
## Reading cost, chunk f3378f0f2d3d, finished 2026-10-23T01:21:28Z
123377 new input tokens before the first commit.
Read most (opens and searches):
- `skills/larv-review/SKILL.md` 1
+2 -7
View File
@@ -12,7 +12,6 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 212 | 0.4.0 | | | **Split `review_launches` into a choice of each pass's rung, made in `bin/model_routing` beside `ladder.review_rungs`, and whole prompt sentences that render that choice.** | 2 | 2 | 3 | 5 | 4 | code health by 9 | 26.9 |
| 214 | 0.4.0 | | | **Have rule-hook refuse a round commit past round 3 of its pass, unless an override quotes the human's answer, so a program holds the round cap.** | 2 | 1 | 3 | 4 | 3 | code health by 3, 1.1 by 3 | 16.6 |
| 210 | 0.4.0 | | | **Hold the escalation mark in one module that states that one trigger buys one step, so a reader changes it without opening four files.** | 3 | 2 | 3 | 6 | 5 | code health by 9 | 16.2 |
| 190 | 0.4.0 | | | **Rewrite the `docs/decisions.md` entries `todo.md: one table …`, `loop-claude: a judge decides …` and `loop-claude: before it opens claude …` 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 |
@@ -69,16 +68,12 @@
| 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.4 |
| 51 | 0.5.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 |
| 169 | 0.5.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 |
| 174 | 0.5.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 |
| 174 | 0.5.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 | 1 | 1.1 by 1 | 1.7 |
| 197 | 0.5.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`.** | 2 | 2 | 3 | 5 | 2 | 1.5 by 1 | 1.3 |
| 52 | 0.5.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
### 212. Split `review_launches` into a choice of each pass's rung, made in `bin/model_routing` beside `ladder.review_rungs`, and whole prompt sentences that render that choice.
Release 0.3.0's scoring runs named `bin/loop_claude/cycle/prompts.py:46` `review_launches` at three seats in both runs (first run: PR #324 at c713910; rerun: PR #324 rerun at c713910). Junior A, rerun: "with ladder.review_rungs, REPLAYED and escalation_rungs open at once". Mid A: "fragments that each start with a space, so no whole prompt is visible without running it in your head" (first run), and "routing policy and English wording interleaved" (rerun). Maintainability senior, rerun: "which conditional sentences reach which prompt means tracing fresh, routed_by, resumed, rungs_held and stepped_to". This lowers Locality, since choosing a rung needs the ladder's units open, and Shape, since one unit holds both policy and wording. Make `review_launches` easier to read.
### 214. Have rule-hook refuse a round commit past round 3 of its pass, unless an override quotes the human's answer, so a program holds the round cap.
Release 0.3.0's inherited architect named `bin/round_titles.py:4` `CAP` in the first run (PR #324 at c713910): "no program loops the reviewers; the cap lives in SKILL.md prose and the code only counts rounds and prints a note". The same seat named `bin/rule_hook/rules.py:55` `round-title-counts` in the rerun: "no program blocks a fourth review round; rule-hook checks only the counts inside a round's title". This lowers Self-sufficiency: a reader of `CAP` must know larv-review's "Round cap" to learn what holds it. The cap is `docs/decisions.md` → `review: a pass gets at most three rounds per chunk; instead of a fourth, the run asks the human`. Make `CAP` and `round-title-counts` easier to read.
@@ -351,7 +346,7 @@ The hook judges a call before it runs, and `changed` in `bin/rule_hook/todo_chec
### 174. 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.
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.
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 or the judge.
### 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`.