Merge pull request 'Hold the escalation mark in one module, and carry a ruling's step-up through the cycle's states' (#361) from item-210 into main

This commit was merged in pull request #361.
This commit is contained in:
2026-10-23 05:24:55 +02:00
13 changed files with 208 additions and 104 deletions
+8
View File
@@ -39,6 +39,14 @@ class Render(unittest.TestCase):
self.assertEqual(said, '[human] do it\n\nStarting.\n\n[tool Bash] {"command": "ls"}\n\n[human] yes, merge it\n\n[human] B, while you work\n\n[loop] Continue the task; the previous run stopped before it was finished.\n\n[loop] Your question: A or B?\n\n[human] use B')
class Verbatim(unittest.TestCase):
def test_a_quote_holds_only_word_for_word_less_emphasis_and_whitespace(self):
self.assertTrue(transcript.verbatim("Merge **ff-only**.", "Merge ff-only.\nNever squash."))
self.assertTrue(transcript.verbatim("Merge _ff-only_.", "Merge ff-only.\nNever squash."))
self.assertFalse(transcript.verbatim("Merge ... squash.", "Merge ff-only.\nNever squash."))
self.assertFalse(transcript.verbatim("", "Merge ff-only."))
class FirstTimestampedLine(unittest.TestCase):
def test_skips_the_lines_every_chunk_shares_and_else_takes_the_first(self):
self.assertEqual(transcript.first_timestamped_line(b'{"type": "custom-title"}\nnot JSON\n{"timestamp": "t"}\n{"timestamp": "u"}\n'), b'{"timestamp": "t"}')
+11
View File
@@ -51,3 +51,14 @@ def part_line(part: object, tool_input_chars: int) -> str:
name, arguments = call
return f"[tool {name}] {json.dumps(arguments, ensure_ascii=False)[:tool_input_chars]}"
return ""
def verbatim(quote: str, text: str) -> bool:
"""Whether text holds the judge's quote word for word, once plain strips emphasis and reflows whitespace in both."""
quoted = plain(quote)
return quoted != "" and quoted in plain(text)
def plain(text: str) -> str:
# The judge drops markdown emphasis and reflows whitespace when it quotes.
return " ".join(text.replace("*", "").replace("_", "").split())
+13 -30
View File
@@ -6,12 +6,12 @@ import typing
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS, ANSWERS_RECORDED, typed_answer
from claude_code.reply import claude_reply, Limited
from loop_claude.effects import Effects
from loop_claude import escalation_mark
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from claude_code.entries import human_text, loop_text
from todo_table import LEVELS
from model_routing.route import on_its_scale
from claude_code.transcript import render
from claude_code.transcript import plain, verbatim
from loop_claude.cycle.retry import retried
from model_routing.ladder import Rung
from loop_claude.stop import Stop
@@ -58,8 +58,6 @@ FINISHED_RULES = (
"continue: an open PR, a review not yet run, CI not yet reported, an answer not yet recorded."
)
JUDGE_RULES = "\n\n".join((INTERRUPT_RULES, QUOTE_RULES, FINISHED_RULES))
# The line judge_prompt shows the judge where an escalation last stepped the worker up, which Reply.escalation's description points at. Only the judge reads it, so it is no [loop] line.
STEP_LINE = "[step] loop-claude stepped the worker up a rung here, so the escalation triggers that fired before this line are spent."
@dataclasses.dataclass(frozen=True)
@@ -69,8 +67,8 @@ class Reply:
highest_likelihood_taken_in: int = dataclasses.field(metadata={"description": "The highest L the worker states for a todo.md item it took into this chunk; 0 when it states none."})
# Routes the next cycle's judge and reviewers, as highest_likelihood_taken_in routes the worker.
highest_escape_and_impact_taken_in: int = dataclasses.field(metadata={"description": "The highest E + I the worker states for a todo.md item it took into this chunk; 0 when it states none."})
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: docs/decisions.md → `routing: a worker whose run ends asking for a higher rung`.
escalation: str = dataclasses.field(metadata={"description": "Empty unless the chunk is unfinished, interrupt is true or answer quotes a passage, and the worker's run ends asking loop-claude for a higher rung, citing an escalation trigger. Then: a verbatim quote, without elisions, of the transcript passage where the trigger fired, such as a review round's commit title or the worker's report of the finding or failing test. Where a [step] line says loop-claude stepped the worker up a rung, quote only the worker's own words after it, and leave this empty where the trigger fired only before it. Never a later mention of the trigger, and never the request itself."})
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: loop_claude/escalation_mark.py.
escalation: str = dataclasses.field(metadata={"description": "Empty unless the chunk is unfinished, interrupt is true or answer quotes a passage, and the worker's run ends asking loop-claude for a higher rung, citing an escalation trigger. Then: a verbatim quote, without elisions, of the transcript passage where the trigger fired, such as a review round's commit title or the worker's report of the finding or failing test. " + escalation_mark.QUOTE_AFTER_STEP + " Never a later mention of the trigger, and never the request itself."})
evidence: str = dataclasses.field(metadata={"description": "A verbatim quote of the one transcript passage the verdict rests on, without elisions: what triggers the interrupt; for a quoted answer, the worker's question; else what shows the chunk finished or the work remaining."})
finished: bool = dataclasses.field(metadata={"description": "Whether the chunk is finished."})
interrupt: bool = dataclasses.field(metadata={"description": "Whether the human must now be interrupted."})
@@ -95,13 +93,11 @@ class Rejected(Failure):
reply: str
class Grounds(typing.NamedTuple):
"""What run_judge checks the judge's quotes against, word for word, since stitched fragments can say what their source does not."""
# The transcript as the judge saw it. The evidence must quote it, its fragments in order: a misquote is Rejected, which judge retries.
shown: str
# The worker's own lines after the mark, all of them before any step-up. loop-claude's prompts and the human's lines are left out, since they repeat earlier passages, such as the judge's evidence or the worker's question. An escalation must quote both this and shown: a misquote, or a quote of a passage before the mark, drops the escalation, so the worker's rung holds.
# escalation_mark.since_step's lines. An escalation must quote both these and shown: a misquote drops the escalation, as escalation_mark.checked says.
since_step: str
# README.md's premises and the records. A quoted answer must quote them: a misquote puts the question to the human.
quotable: str
@@ -135,10 +131,10 @@ def judge(root: str, task: str, premises: str, records: str, entries: list[dict]
def judge_once(root: str, task: str, premises: str, records: str, entries: list[dict], escalated_at: int, rung: Rung, effects: Effects) -> Verdict | Failure | Limited:
"""One judge run on the transcript's entries, as judge retries it; judge-replay replays it. escalated_at is the route's mark: an escalation quote counts only from the entries after it."""
"""One judge run on the transcript's entries, as judge retries it; judge-replay replays it. escalated_at is the route's mark, as loop_claude/escalation_mark.py says."""
prompt, grounds = judge_prompt(task, premises, records, entries, escalated_at)
verdict = run_judge(root, judge_args(rung), prompt, grounds, effects)
return dataclasses.replace(verdict, entries_read=len(entries)) if isinstance(verdict, Interrupt | QuotedAnswer | Unfinished) else verdict
return verdict if isinstance(verdict, Failure | Limited) else escalation_mark.stamped(verdict, len(entries))
def judge_args(rung: Rung) -> list[str]:
@@ -152,7 +148,7 @@ def judge_args(rung: Rung) -> list[str]:
def run_judge(root: str, args: list[str], prompt: str, grounds: Grounds, effects: Effects) -> Verdict | Failure | Limited:
"""One judge run, each quote in its verdict checked against grounds as Grounds says. quotes_checked checks the quoted answer and the escalation: neither misquote is a Failure, which would otherwise exit an unattended loop."""
"""One judge run, each quote in its verdict checked against grounds as Grounds says."""
reply = claude_reply(effects.claude, args, root, prompt, "the judge")
if isinstance(reply, Failure | Limited):
return reply
@@ -166,18 +162,15 @@ def run_judge(root: str, args: list[str], prompt: str, grounds: Grounds, effects
def quotes_checked(verdict: Verdict, grounds: Grounds) -> Verdict:
"""The verdict with its quoted answer and its escalation checked, as Grounds says; a quoted answer put to the human keeps the escalation it carried."""
"""The verdict with its quoted answer and its escalation checked. A quoted answer that neither README.md's premises nor the records hold goes to the human as an interrupt, which keeps the escalation the answer carried. Neither misquote is a Failure, which would otherwise exit an unattended loop."""
if isinstance(verdict, QuotedAnswer) and not verbatim(verdict.answer, grounds.quotable):
verdict = Interrupt(verdict.evidence, verdict.question, escalation=verdict.escalation, highest_likelihood_taken_in=verdict.highest_likelihood_taken_in)
if isinstance(verdict, Interrupt | QuotedAnswer | Unfinished) and verdict.escalation and not (verbatim(verdict.escalation, grounds.since_step) and verbatim(verdict.escalation, grounds.shown)):
return dataclasses.replace(verdict, escalation="")
return verdict
return escalation_mark.checked(verdict, since=grounds.since_step, shown=grounds.shown)
def judge_prompt(task: str, premises: str, records: str, entries: list[dict], escalated_at: int) -> tuple[str, Grounds]:
"""The prompt, and what the judge's quotes are checked against. Where escalated_at, the route's mark, is above 0, the prompt shows STEP_LINE after that many entries."""
transcript = "\n\n".join(part for part in (render(entries[:escalated_at], typed_answer), STEP_LINE if escalated_at else "", render(entries[escalated_at:], typed_answer)) if part)
workers_own = [entry for entry in entries[escalated_at:] if human_text(entry) is None and loop_text(entry) is None]
"""The prompt, and what the judge's quotes are checked against."""
transcript = escalation_mark.transcript(entries, escalated_at, typed_answer)
head = (
f"From README.md:\n{premises}\n\n"
f"The records: the project's working rules and decisions, then the human's rules for every project:\n{records or 'none'}\n\n"
@@ -187,7 +180,7 @@ def judge_prompt(task: str, premises: str, records: str, entries: list[dict], es
room = max(0, JUDGE_PROMPT_CHARS - len(head) - len(JUDGE_RULES) - 2)
# The tail, where an interrupt or a finish lands; the session's transcript grows cycle over cycle.
shown = transcript[max(0, len(transcript) - room):]
return f"{head}{shown}\n\n{JUDGE_RULES}", Grounds(shown, render(workers_own, typed_answer), f"{premises}\n\n{records}")
return f"{head}{shown}\n\n{JUDGE_RULES}", Grounds(shown, escalation_mark.since_step(entries, escalated_at), f"{premises}\n\n{records}")
def grounded(evidence: str, rendered_transcript: str) -> bool:
@@ -201,13 +194,3 @@ def grounded(evidence: str, rendered_transcript: str) -> bool:
return False
at = found + len(fragment)
return fragments != []
def verbatim(quote: str, text: str) -> bool:
quoted = plain(quote)
return quoted != "" and quoted in plain(text)
def plain(text: str) -> str:
# The judge drops markdown emphasis and reflows whitespace when it quotes.
return " ".join(text.replace("*", "").replace("_", "").split())
+36 -34
View File
@@ -8,7 +8,7 @@ from transcript_archive.write import archive
from claude_code.session import delete_session, Session, session_open, transcript_file
from loop_claude.effects import Effects
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from loop_claude.cycle.judge import judge, Rejected
from transcript_archive import outcomes
from loop_claude.paths import Paths
@@ -19,6 +19,7 @@ from loop_claude.cycle.retry import retried
from model_routing.route import Route
from loop_claude.cycle.worker import run_worker, worker_args
from model_routing.ladder import Rung
from loop_claude.escalation_mark import StepUp
from loop_claude.stop import Stop
from model_routing import worker_rungs
@@ -41,9 +42,6 @@ class Cycle:
project: Rung | None
# Empty when the previous cycle's verdict was not Unfinished.
unfinished_evidence: str
# Only an interrupt's or a quoted answer's escalation changes the route within a cycle. No transition reads the route or the fields below, so they stay out of the states.
# The route before that ruling stepped it up, for ask and keep_answer to archive and for worker_start to tell the worker; None unless the latest event is that ruling, or the answer the human typed to it.
stepped_from: Route | None = None
@dataclasses.dataclass(frozen=True)
@@ -60,22 +58,21 @@ def run_cycle(cycle: Cycle) -> Stop | Concluded:
event = step(cycle, state)
if isinstance(event, Stop):
return stopped(cycle, event, event.reason)
cycle = escalated(cycle, event)
# Only a ruling's step-up changes the route within a cycle. No transition reads the current route, so Cycle holds it, not the states.
if isinstance(event, Ruled) and event.step_up:
cycle = dataclasses.replace(cycle, route=event.step_up.after)
state = transition(state, event)
except KeyboardInterrupt:
return stopped(cycle, Stop(130, ""), "Ctrl-C")
return Concluded(state.verdict, cycle.route)
def escalated(cycle: Cycle, event: Event) -> Cycle:
"""The cycle after event. Where the judge interrupted or quoted an answer with an escalation, its route steps up before the human is asked or the worker resumes, so the work after the answer runs on it. stepped_from holds through the answer the human types, so the worker resuming with it is told of the step; a copy on TypedAnswer would give the step a second owner."""
if isinstance(event, HumanTyped):
return cycle
cycle = dataclasses.replace(cycle, stepped_from=None)
if not (isinstance(event, Ruled) and isinstance(event.verdict, Interrupt | QuotedAnswer) and cycle.project):
return cycle
route = after_ruling(cycle.project, cycle.route, event.verdict)
return dataclasses.replace(cycle, route=route, stepped_from=cycle.route if route != cycle.route else None)
def ruling_step_up(cycle: Cycle, verdict: Verdict) -> StepUp | None:
"""The step-up an interrupt's or a quoted answer's escalation makes, so the work after the answer runs on the stepped route; None where the route holds."""
if not (isinstance(verdict, Interrupt | QuotedAnswer) and cycle.project):
return None
after = after_ruling(cycle.project, cycle.route, verdict)
return StepUp(cycle.route, after) if after != cycle.route else None
def stopped(cycle: Cycle, stop: Stop, why: str) -> Stop:
@@ -92,12 +89,12 @@ def judge_of(cycle: Cycle) -> Rung:
def step(cycle: Cycle, state: Active) -> Event | Stop:
match state:
case Working(answered, _):
return work(cycle, answered)
case Working(answered, _, step_up):
return work(cycle, answered, step_up)
case Judging(transcript_path, _):
return rule(cycle, transcript_path)
case Interrupting(transcript_path, ruling, _):
return ask(cycle, transcript_path, ruling)
case Interrupting(transcript_path, ruling, _, step_up):
return ask(cycle, transcript_path, ruling, step_up)
case Talking(transcript_path, _):
return talk(cycle.root, cycle.session.id, cycle.route.rung, transcript_path, cycle.paths, worker_environment(cycle), cycle.effects) or HumanTalked()
case Closing(transcript_path, verdict):
@@ -106,13 +103,13 @@ def step(cycle: Cycle, state: Active) -> Event | Stop:
typing.assert_never(state)
def work(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None) -> WorkerRan | Stop:
def work(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, step_up: StepUp | None) -> WorkerRan | Stop:
if isinstance(answered, QuotedAnswer):
print(f"\n=== {prompts.QUOTE_SOURCES} answered: {answered.question} ===\n{answered.answer}", flush=True)
if stop := keep_answer(cycle, answered):
if stop := keep_answer(cycle, answered, step_up):
return stop
# worker_start runs inside the lambda: a failed attempt may have opened the session.
if stop := retried("worker", lambda: run_worker(cycle.root, worker_start(cycle, answered), worker_environment(cycle), cycle.effects), cycle.effects):
if stop := retried("worker", lambda: run_worker(cycle.root, worker_start(cycle, answered, step_up), worker_environment(cycle), cycle.effects), cycle.effects):
return stop
path = transcript_file(cycle.session)
return WorkerRan(path) if path is not None else Stop(1, f"claude left no transcript for session {cycle.session.id}")
@@ -123,23 +120,23 @@ def worker_environment(cycle: Cycle) -> dict[str, str]:
return worker_rungs.environment(cycle.project, cycle.route)
def worker_start(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None) -> list[str]:
def worker_start(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, step_up: StepUp | None) -> list[str]:
if isinstance(answered, QuotedAnswer):
return worker_args(cycle.session, cycle.route.rung, prompts.answered(answered.question, answered.answer, cycle.route, cycle.project, cycle.stepped_from is not None), resume=True)
return worker_args(cycle.session, cycle.route.rung, prompts.answered(answered.question, answered.answer, cycle.route, cycle.project, step_up is not None), resume=True)
if isinstance(answered, TypedAnswer):
return worker_args(cycle.session, cycle.route.rung, prompts.typed(answered.question, answered.answer, cycle.route, cycle.project, cycle.stepped_from is not None), resume=True)
return worker_args(cycle.session, cycle.route.rung, prompts.typed(answered.question, answered.answer, cycle.route, cycle.project, step_up is not None), resume=True)
if session_open(cycle.session):
return worker_args(cycle.session, cycle.route.rung, prompts.resumed(cycle.unfinished_evidence, cycle.route, cycle.project), resume=True)
return worker_args(cycle.session, cycle.route.rung, prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.project, cycle.facts), resume=False)
def keep_answer(cycle: Cycle, answered: QuotedAnswer) -> Stop | None:
def keep_answer(cycle: Cycle, answered: QuotedAnswer, step_up: StepUp | None) -> Stop | None:
path = transcript_file(cycle.session)
if not path:
return None
# As in ask: the answer names the rung the worker ran on until then, and a step-up archived after it names the rung it runs on from then.
quoted = outcomes.answered(answered.question, prompts.QUOTE_SOURCES, answered.answer, answered.evidence, answered.escalation, str(judge_of(cycle)), (cycle.stepped_from or cycle.route).record())
if failure := archive_stepped(cycle, path, quoted):
quoted = outcomes.answered(answered.question, prompts.QUOTE_SOURCES, answered.answer, answered.evidence, answered.escalation, str(judge_of(cycle)), ran_on(cycle, step_up).record())
if failure := archive_stepped(cycle, path, quoted, step_up):
return Stop(1, failure.reason)
return None
@@ -149,7 +146,7 @@ def rule(cycle: Cycle, transcript_path: str) -> Ruled | Stop:
if isinstance(entries, Failure):
return Stop(1, entries.reason)
verdict = judge(cycle.root, cycle.task, cycle.premises, cycle.records, entries, cycle.route.escalated_at, judge_of(cycle), cycle.effects, lambda rejected: keep_rejection(cycle, transcript_path, rejected))
return verdict if isinstance(verdict, Stop) else Ruled(verdict)
return verdict if isinstance(verdict, Stop) else Ruled(verdict, ruling_step_up(cycle, verdict))
def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> Stop | None:
@@ -159,12 +156,12 @@ def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> St
return None
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) -> HumanTyped | TalkChosen | Stop:
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer, step_up: StepUp | None) -> HumanTyped | TalkChosen | Stop:
question = question_for(ruling)
# Archived now, so the transcript the question was asked on is kept with it; the human's answer then grows the transcript.
# The interrupt names the rung the worker ran on before it; a step-up archived after it names the stepped rung, so the figures charge each stretch to its own rung.
interrupted = outcomes.interrupted(question, ruling.evidence, str(judge_of(cycle)), ruling.escalation, (cycle.stepped_from or cycle.route).record())
if failure := archive_stepped(cycle, transcript_path, interrupted):
interrupted = outcomes.interrupted(question, ruling.evidence, str(judge_of(cycle)), ruling.escalation, ran_on(cycle, step_up).record())
if failure := archive_stepped(cycle, transcript_path, interrupted, step_up):
return Stop(1, failure.reason)
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
answer = put_question(question, not (isinstance(ruling, Interrupt) and ruling.release_ready), cycle.effects)
@@ -174,9 +171,14 @@ def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) ->
return TalkChosen() if isinstance(answer, Talk) else HumanTyped(TypedAnswer(ruling.question, answer))
def archive_stepped(cycle: Cycle, transcript_path: str, outcome: str) -> Failure | None:
"""Archives the outcome of a ruling, then the step-up it caused when it stepped the route. The first failure is returned."""
for kept in (outcome, outcomes.stepped_up(cycle.route.record())) if cycle.stepped_from else (outcome,):
def ran_on(cycle: Cycle, step_up: StepUp | None) -> Route:
"""The route the worker ran on until the ruling: the one before its step-up, if it made one."""
return step_up.before if step_up else cycle.route
def archive_stepped(cycle: Cycle, transcript_path: str, outcome: str, step_up: StepUp | None) -> Failure | None:
"""Archives the outcome of a ruling, then the step-up it made, if it made one. The first failure is returned."""
for kept in (outcome, outcomes.stepped_up(step_up.after.record())) if step_up else (outcome,):
if failure := archive(cycle.project_archive, transcript_path, cycle.task, kept, cycle.effects.now()):
return failure
return None
+15 -8
View File
@@ -1,6 +1,7 @@
import dataclasses
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from loop_claude.escalation_mark import StepUp
# A backstop for what the judge misses, such as a reworded repeat, so the worker cannot loop unattended on answers quoted from README.md or the records.
QUOTED_ANSWERS_PER_CYCLE = 3
@@ -18,6 +19,8 @@ class Working:
"""The worker runs, resumed with an answer quoted from README.md or the records, or typed by the human, when there is one."""
answered: QuotedAnswer | TypedAnswer | None = None
quoted_answers: int = 0
# The step-up made by the ruling that brought the answer, so the worker is told of it; None for none.
step_up: StepUp | None = None
@dataclasses.dataclass(frozen=True)
@@ -33,6 +36,8 @@ class Interrupting:
transcript_path: str
ruling: Interrupt | QuotedAnswer
quoted_answers: int = 0
# The step-up the ruling made. It holds through the answer the human types, and drops on /talk.
step_up: StepUp | None = None
@dataclasses.dataclass(frozen=True)
@@ -65,6 +70,8 @@ class WorkerRan:
@dataclasses.dataclass(frozen=True)
class Ruled:
verdict: Verdict
# None unless an interrupt's or a quoted answer's escalation stepped the route; always None for a finished or unfinished verdict.
step_up: StepUp | None = None
@dataclasses.dataclass(frozen=True)
@@ -94,16 +101,16 @@ def transition(state: State, event: Event) -> State:
match state, event:
case Working(_, quoted_answers), WorkerRan(transcript_path):
return Judging(transcript_path, quoted_answers)
case Judging(_, quoted_answers), Ruled(QuotedAnswer() as answered) if quoted_answers < QUOTED_ANSWERS_PER_CYCLE:
return Working(answered, quoted_answers + 1)
case Judging(transcript_path, quoted_answers), Ruled(QuotedAnswer() as ruling) if quoted_answers >= QUOTED_ANSWERS_PER_CYCLE:
return Interrupting(transcript_path, ruling, quoted_answers)
case Judging(transcript_path, quoted_answers), Ruled(Interrupt() as ruling):
return Interrupting(transcript_path, ruling, quoted_answers)
case Judging(_, quoted_answers), Ruled(QuotedAnswer() as answered, step_up) if quoted_answers < QUOTED_ANSWERS_PER_CYCLE:
return Working(answered, quoted_answers + 1, step_up)
case Judging(transcript_path, quoted_answers), Ruled(QuotedAnswer() as ruling, step_up) if quoted_answers >= QUOTED_ANSWERS_PER_CYCLE:
return Interrupting(transcript_path, ruling, quoted_answers, step_up)
case Judging(transcript_path, quoted_answers), Ruled(Interrupt() as ruling, step_up):
return Interrupting(transcript_path, ruling, quoted_answers, step_up)
case Judging(transcript_path, _), Ruled(Finished() | Unfinished() as verdict):
return Closing(transcript_path, verdict)
case Interrupting(_, _, quoted_answers), HumanTyped(typed):
return Working(typed, quoted_answers)
case Interrupting(_, _, quoted_answers, step_up), HumanTyped(typed):
return Working(typed, quoted_answers, step_up)
case Interrupting(transcript_path, _, quoted_answers), TalkChosen():
return Talking(transcript_path, quoted_answers)
# The human worked in the worker's claude session, so the judge rules again on the transcript it leaves.
+57
View File
@@ -0,0 +1,57 @@
"""The escalation mark makes one escalation trigger step the worker up one rung, never two (docs/decisions.md → `routing: a worker whose run ends asking for a higher rung`).
A worker whose run ends asking loop-claude for a higher rung cites the trigger that fired, and the judge quotes the passage where it fired as the verdict's escalation. The mark, Route.escalated_at, is how many transcript entries the session held when an escalation last stepped the worker up, 0 before any. The session's transcript only grows, so the mark holds across cycles, and the archive's Worker: records keep it for a rerun.
- Stamp. stamped() writes on the judge's verdict how many entries the judge read.
- Step. routing.after_unfinished() and routing.after_ruling() step the worker up on an escalation and move the mark to moved_to(verdict). A ruling's StepUp travels through the cycle's states, so the archive and the worker's next prompt name it.
- Show. transcript() puts STEP_LINE after the mark, telling the judge that the triggers before that line are spent. QUOTE_AFTER_STEP, in the judge's schema, tells the judge to quote only the worker's words after that line.
- Check. checked() keeps an escalation only where it quotes both the transcript the judge was shown and the worker's own lines after the mark, which since_step() renders, so a passage that bought one step cannot buy another.
"""
import dataclasses
import typing
from loop_claude.verdicts import Escalating, Verdict
from claude_code.entries import human_text, loop_text
from claude_code.transcript import render, Typed, verbatim
from model_routing.route import Route
# Only the judge reads the step line, so it is not a [loop] line.
STEP_TAG = "[step]"
STEP_LINE = f"{STEP_TAG} loop-claude stepped the worker up a rung here, so the escalation triggers that fired before this line are spent."
# Reply.escalation's description in cycle/judge.py carries this sentence, so the judge reads STEP_LINE as the mark.
QUOTE_AFTER_STEP = f"Where a {STEP_TAG} line says loop-claude stepped the worker up a rung, quote only the worker's own words after it, and leave this empty where the trigger fired only before it."
@dataclasses.dataclass(frozen=True)
class StepUp:
"""An interrupt's or a quoted answer's escalation stepping the route within a cycle: the route the worker ran on until the ruling, and the one it runs on after."""
before: Route
after: Route
def stamped(verdict: Verdict, entries_read: int) -> Verdict:
"""The verdict with how many transcript entries the judge read, where it may carry an escalation."""
return dataclasses.replace(verdict, entries_read=entries_read) if isinstance(verdict, Escalating) else verdict
def moved_to(verdict: Escalating) -> int | None:
"""Where the verdict's escalation would move the mark, if the escalation steps the worker; None for a verdict without one."""
return verdict.entries_read if verdict.escalation else None
def transcript(entries: list[dict], at: int, typed_answer: typing.Callable[[str], Typed | None]) -> str:
"""The transcript as the judge sees it. Where the mark, at, is above 0, STEP_LINE comes after that many entries."""
return "\n\n".join(part for part in (render(entries[:at], typed_answer), STEP_LINE if at else "", render(entries[at:], typed_answer)) if part)
def since_step(entries: list[dict], at: int) -> str:
"""The worker's own lines after the mark, all of them, however much of the transcript the judge is shown. loop-claude's prompts and the human's lines are left out, since they repeat earlier passages, such as the judge's evidence or the worker's question."""
# No loop-claude prompt is left to carry an answer the human typed.
return render([entry for entry in entries[at:] if human_text(entry) is None and loop_text(entry) is None], lambda prompt: None)
def checked(verdict: Verdict, *, since: str, shown: str) -> Verdict:
"""The verdict without its escalation unless the escalation quotes both texts: since, the worker's lines after the mark as since_step renders them, and shown, the transcript the judge was shown. A misquote, or a quote of a passage before the mark, drops the escalation, so the worker's rung holds."""
if isinstance(verdict, Escalating) and verdict.escalation and not (verbatim(verdict.escalation, since) and verbatim(verdict.escalation, shown)):
return dataclasses.replace(verdict, escalation="")
return verdict
+6 -5
View File
@@ -4,15 +4,16 @@ The worker, and the session /talk opens, run on a Route (model_routing/route.py)
- Start. routed_item finds the plan item that routes a fresh chunk, if there is one with L, E and I scored; first_route picks the worker's rung from its L, or the project's rung without an item.
- Rerun. kept decides whether a rerun resumes the route its archive last names.
- Step-up. after_unfinished raises the route after an unfinished verdict, after_ruling after an interrupt or a quoted answer that carries an escalation; escalation_cap bounds an escalation.
- Step-up. after_unfinished raises the route after an unfinished verdict, after_ruling after an interrupt or a quoted answer that carries an escalation; escalation_cap bounds an escalation, and loop_claude/escalation_mark.py states the escalation mark's rule.
- Judge. judge_rung picks the rung of the judge of a JUDGE_REPLAYED model.
"""
import dataclasses
from chunk_pick import chunk_item, LastCut, Next
from model_routing.ladder import climbed, highest, LADDER, position, project_rung, review_floor, Rung, stepped_up, worker_rung
from loop_claude.verdicts import escalation_mark, Interrupt, QuotedAnswer, Unfinished
from loop_claude import escalation_mark
from failure import Failure
from loop_claude.verdicts import Interrupt, QuotedAnswer, Unfinished
from todo_table import Item, items, NoItemsTable
from model_routing.route import Route
@@ -75,10 +76,10 @@ def escalation_cap(project: Rung, route: Route) -> Rung:
def after_unfinished(project: Rung, route: Route, verdict: Unfinished) -> Route:
"""The route the next cycle runs on after an unfinished verdict.
Its rung never falls. It first rises to the rung that the verdict's highest L taken in picks, where that is higher. From there it steps one rung up on every second unfinished verdict, or on an escalation while below escalation_cap; where both fall on one verdict, it steps once. A step on an escalation moves the route's mark, Route.escalated_at, to where the judge stopped reading, so the trigger it quoted buys no second step; a step on the count of unfinished verdicts alone keeps the mark. Last, the route takes in the verdict's highest E + I, as Route.taking_in does.
Its rung never falls. It first rises to the rung that the verdict's highest L taken in picks, where that is higher. From there it steps one rung up on every second unfinished verdict, or on an escalation while below escalation_cap; where both fall on one verdict, it steps once. A step on an escalation moves the mark, as loop_claude/escalation_mark.py says; a step on the count of unfinished verdicts alone keeps it. Last, the route takes in the verdict's highest E + I, as Route.taking_in does.
"""
rung = raised(project, route, verdict.highest_likelihood_taken_in)
mark = escalation_mark(verdict)
mark = escalation_mark.moved_to(verdict)
if route.unfinished + 1 >= UNFINISHED_PER_STEP or (mark is not None and below_cap(project, route, rung)):
after = one_rung_up(route, rung, route.escalated_at if mark is None else mark)
else:
@@ -88,7 +89,7 @@ def after_unfinished(project: Rung, route: Route, verdict: Unfinished) -> Route:
def after_ruling(project: Rung, route: Route, verdict: Interrupt | QuotedAnswer) -> Route:
"""The route after the judge's interrupt or quoted answer: unchanged without an escalation. With one, raised to the rung the highest L taken in picks, and one rung up from there while below escalation_cap, moving the mark as after_unfinished does. Neither is an unfinished verdict, so the count of those restarts only with a step."""
mark = escalation_mark(verdict)
mark = escalation_mark.moved_to(verdict)
if mark is None:
return route
rung = raised(project, route, verdict.highest_likelihood_taken_in)
+18 -9
View File
@@ -22,6 +22,7 @@ from loop_claude.project import checkout, model_choice, records
from chunk_pick import DefaultPlan, LastCut
from loop_claude.effects import Effects, PYTHON_TIMEOUT, run_python
from claude_code import entries, reply, session
from loop_claude import escalation_mark, paths, routing
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from loop_claude.cycle import interrupt, judge, prompts, retry, run, states, worker
@@ -30,7 +31,6 @@ from model_routing.ladder import LADDER, Rung
from claude_code.reply import Limited
from loop_claude.loop import main, reload, routing_check
from transcript_archive import outcomes, write
from loop_claude import paths, routing
from transcript_archive.location import project_archive
from model_routing.route import Record, Route, route_from
from loop_claude.stop import Stop
@@ -193,6 +193,20 @@ class Transitions(unittest.TestCase):
with self.subTest(state=state, event=event), self.assertRaises(ValueError):
states.transition(state, event)
def test_a_rulings_step_up_reaches_the_worker_it_resumes_through_the_answer_the_human_types_and_no_further(self):
step_up = escalation_mark.StepUp(Route(Rung("claude-opus-5-5", "medium")), Route(Rung("claude-opus-5-5", "high"), escalated_at=3))
interrupt, quoted = Interrupt("e", "q", "round 2: 🔴"), QuotedAnswer("e", "q", "A.", "round 2: 🔴")
for state, event, after in (
(states.Judging("/t"), states.Ruled(quoted, step_up), states.Working(quoted, 1, step_up)),
(states.Judging("/t", 3), states.Ruled(quoted, step_up), states.Interrupting("/t", quoted, 3, step_up)),
(states.Judging("/t"), states.Ruled(interrupt, step_up), states.Interrupting("/t", interrupt, 0, step_up)),
(states.Interrupting("/t", interrupt, 0, step_up), states.HumanTyped(TYPED), states.Working(TYPED, 0, step_up)),
(states.Interrupting("/t", interrupt, 0, step_up), states.TalkChosen(), states.Talking("/t")),
(states.Working(TYPED, 0, step_up), states.WorkerRan("/t"), states.Judging("/t")),
):
with self.subTest(state=state, event=event):
self.assertEqual(states.transition(state, event), after)
class QuestionFor(unittest.TestCase):
def test_puts_an_interrupts_question_as_asked_and_a_quoted_answer_past_the_cap_with_its_quote(self):
@@ -392,9 +406,8 @@ class Cycles(unittest.TestCase):
cycle = dataclasses.replace(self.cycle(FakeEffects()), project=Routing.OPUS, route=Route(Routing.OPUS, 3, 3, 4))
for ruling in (Interrupt("e", "q", entries_read=3), QuotedAnswer("e", "q", "A.", entries_read=3)):
with self.subTest(ruling=ruling):
self.assertEqual(run.escalated(cycle, states.Ruled(ruling)), cycle)
stepped = run.escalated(cycle, states.Ruled(Interrupt("e", "q", "round 2: 🔴", 4, entries_read=3)))
self.assertEqual((stepped.route, stepped.stepped_from), (Route(Routing.XHIGH, 3, 3, 4, escalated_at=3), cycle.route))
self.assertIsNone(run.ruling_step_up(cycle, ruling))
self.assertEqual(run.ruling_step_up(cycle, Interrupt("e", "q", "round 2: 🔴", 4, entries_read=3)), escalation_mark.StepUp(cycle.route, Route(Routing.XHIGH, 3, 3, 4, escalated_at=3)))
def test_an_escalation_after_an_interrupt_stepped_the_worker_steps_it_again_in_the_same_cycle(self):
streams = [Worker(self.paths.claude_code_transcripts.parent, text="round 2: 🔴"), Worker(self.paths.claude_code_transcripts.parent), Worker(self.paths.claude_code_transcripts.parent)]
@@ -1293,6 +1306,7 @@ class JudgePrompt(unittest.TestCase):
self.assertEqual(grounds.since_step, "round 3: 🔴")
prompt, grounds = judge.judge_prompt("Do it.", "## Goals", "", entries, 0)
self.assertNotIn("stepped the worker up", prompt)
self.assertEqual(grounds.shown, "round 2: 🔴\n\nround 3: 🔴")
self.assertEqual(grounds.since_step, "round 2: 🔴\n\nround 3: 🔴")
def test_drops_an_escalation_quote_from_after_the_step_up_that_the_tail_it_shows_cuts_off(self):
@@ -1326,11 +1340,6 @@ class Grounded(unittest.TestCase):
self.assertFalse(judge.grounded("Decision for you ... invented", transcript))
self.assertFalse(judge.grounded("... …", transcript))
def test_an_answer_holds_only_word_for_word(self):
self.assertTrue(judge.verbatim("Merge **ff-only**.", "Merge ff-only.\nNever squash."))
self.assertFalse(judge.verbatim("Merge ... squash.", "Merge ff-only.\nNever squash."))
self.assertFalse(judge.verbatim("", "Merge ff-only."))
class Verdict(unittest.TestCase):
def test_needs_every_field_the_schema_requires(self):
+3 -6
View File
@@ -11,7 +11,7 @@ class Interrupt:
# The highest L the judge saw the worker take into the chunk, 0 for none: an escalation steps up from the rung that L picks.
highest_likelihood_taken_in: int = 0
release_ready: bool = False
# How many transcript entries the judge read, which judge_once stamps. An escalation the verdict carries moves the route's mark there. None means judge_once never stamped it, and then its escalation doesn't step the worker.
# How many transcript entries the judge read, which escalation_mark.stamped stamps. An escalation the verdict carries moves the route's mark there. None means it was never stamped, and then its escalation doesn't step the worker.
entries_read: int | None = None
@@ -46,8 +46,5 @@ class Unfinished:
Verdict = Interrupt | QuotedAnswer | Finished | Unfinished
def escalation_mark(verdict: Interrupt | QuotedAnswer | Unfinished) -> int | None:
"""Where the verdict's escalation would move the route's mark, if it steps the worker; None where it carries none."""
return verdict.entries_read if verdict.escalation else None
# The verdicts that may carry an escalation.
Escalating = Interrupt | QuotedAnswer | Unfinished
+1 -1
View File
@@ -50,7 +50,7 @@ class Route:
unfinished: int = 0
# The highest E + I the judge saw the worker take in, kept only where it picks a higher review step than the item's; 0 otherwise.
escape_and_impact_taken_in: int = 0
# The mark: how many transcript entries the session held when an escalation last stepped the worker up, 0 before any. The judge's escalation quote counts only from the entries after it, so a passage that already bought a step cannot buy another; the session's transcript only grows, so the mark holds across cycles.
# The escalation mark, as loop_claude/escalation_mark.py says: how many transcript entries the session held when an escalation last stepped the worker up, 0 before any.
escalated_at: int = 0
def __post_init__(self) -> None:
+25
View File
@@ -2574,3 +2574,28 @@ Inherited architect, decided by:
- 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
## 2026-10-23T03:24:42Z, PR #361 at 6f98a18, against 39dd51b
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: `bin/loop_claude/cycle/run.py:61` `run_cycle`: the step-up rides on Ruled and the states as a StepUp passed to work, ask, keep_answer, worker_start and archive_stepped, where the base's Cycle.stepped_from was hidden state that escalated() cleared on every event but HumanTyped
- Navigation, Self-sufficiency: `bin/loop_claude/escalation_mark.py:1` `escalation_mark`: the mark's rule, once spread over judge.py, verdicts.py, Route.escalated_at's comment and after_unfinished's docstring, sits in one file whose docstring lists Stamp, Step, Show and Check by function
- Shape: `bin/loop_claude/escalation_mark.py:37` `moved_to`: says what it returns, where the base's verdicts.escalation_mark was named after the concept; Escalating replaces the repeated union
- Shape, Locality: `bin/loop_claude/cycle/judge.py:164` `quotes_checked`: shrinks to calls into escalation_mark, so judge.py holds only the judge's own logic, and verbatim and plain sit beside render
- Self-sufficiency: `bin/round_titles.py:6` `CAP`: a bare constant in the base now says what it caps and which two consumers use it
Inherited architect, decided by:
- Locality, Shape: `bin/loop_claude/cycle/run.py:61` `run_cycle`: a StepUp travels through Ruled, Interrupting and Working and drops on /talk in one visible case, where the base's escalated() cleared Cycle.stepped_from by an order-dependent rule; the base's hardest place improved most
- Navigation, Self-sufficiency: `bin/loop_claude/escalation_mark.py:1` `escalation_mark`: from "the worker was stepped up twice" a reader reaches the right unit in one hop, with four labelled steps each naming its function
- Shape: `bin/loop_claude/verdicts.py:50` `Escalating`: the base's escalation_mark function returned where the mark would move; now the module carries the concept's name, moved_to says what it returns, and the type has one name
- Self-sufficiency: `bin/loop_claude/cycle/judge.py:70` `Reply.escalation`: the comment points at code that explains the rule rather than at docs/decisions.md
- Navigation: `bin/round_titles.py:6` `CAP`: names the decision, rule-hook's round-cap and larv-review round-count, so a fourth-round page leads to the code that enforces the cap
+4
View File
@@ -811,3 +811,7 @@ Read most (opens and searches):
## Reading cost, chunk 1bc51e408577, finished 2026-10-23T02:06:21Z
126580 new input tokens before the first commit.
## Reading cost, chunk ed7548905fbb, finished 2026-10-23T02:32:52Z
68233 new input tokens before the first commit.
+11 -11
View File
@@ -6,15 +6,14 @@
`Bar = 0.1`
`Next ID = 221`
`Next ID = 222`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 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 |
| 82 | 0.4.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 |
| 190 | 0.4.0 | | | **Rewrite as the current state the six `docs/decisions.md` entries that read as amendment logs, so a reader no longer replays superseded paragraphs to learn what holds.** | 2 | 2 | 1 | 3 | 4 | code health by 4, 1.4 by 3 | 14.0 |
| 216 | 0.4.0 | | | **Make larv-review's round count agree with itself on the auto-reviewer: either title its round commits so `round-count` counts them as a pass, or have SKILL.md say they carry no `Answer <pass> round` title.** | 1 | 2 | 3 | 4 | 2 | code health by 2 | 12.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 |
| 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 5, 1.4 by 3 | 10.2 |
@@ -35,6 +34,7 @@
| 175 | 0.5.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.5.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.5.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 |
| 221 | 0.5.0 | | | **Parse each transcript entry once, where `bin/claude_code/transcript.py` reads it, into a typed value naming its kind, so no consumer works out an entry's kind from a raw `dict`.** | 3 | 1 | 3 | 5 | 5 | code health by 4 | 7.2 |
| 116 | 0.5.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 |
| 203 | 0.5.0 | | | **Make `bin/repo_checks` fail on a `todo.md` citation of a `docs/decisions.md` title that no heading holds.** | 1 | 1 | 1 | 1 | 2 | 1.1 by 5 | 7.0 |
| 113 | 0.5.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 |
@@ -74,18 +74,14 @@
## Details
### 210. Hold the escalation mark in one module that states that one trigger buys one step, so a reader changes it without opening four files.
Release 0.3.0's scoring runs found the mark spread out (first run: PR #324 at c713910; rerun: PR #324 rerun at c713910). `bin/model_routing/route.py:66` `Route.escalated_at`: "the escalation mark lives in six units across four files" (Junior A, first run), "one concept spread over five files" (Mid A, rerun). `bin/loop_claude/cycle/judge.py:153` `escalation_mark`: "no single place states that one trigger buys one step" (Maintainability senior, rerun). `bin/loop_claude/cycle/run.py:45` `Cycle.stepped_from` and `:69` `escalated`: "state outside the state machine, cleared on every event but HumanTyped" (Mid A, rerun). `bin/loop_claude/cycle/judge.py:216` `quotes_checked` checks the escalation against `Grounds.since_step` beside the quoted answer: "three quote checks follow different rules" (Junior A, rerun). This lowers Locality: changing the mark means opening `route.py`, `judge.py`, `run.py` and `routing.py` together. Move the mark's stamping, `STEP_LINE`, the since-step grounds and their check, and the step's state into one module, and make `stepped_from` part of the cycle's state machine. Make `Route.escalated_at`, `escalation_mark`, `Cycle.stepped_from`, `escalated` and `quotes_checked` easier to read. The archive's `Worker:` record holds the mark as `escalated_at`, so a rerun keeps it; the move keeps that field. `escalation_mark` now lives in `bin/loop_claude/verdicts.py`.
### 190. 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.
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. The prose review of PR #335 found the trust entry, `loop-claude: before it opens claude …`, made of four dated paragraphs, and a 2026-10-21 paragraph on item 120 that records a move which changed no rule; drop that paragraph.
### 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.
### 190. Rewrite as the current state the six `docs/decisions.md` entries that read as amendment logs, so a reader no longer replays superseded paragraphs to learn what holds.
The entries are `todo.md: one table …`, `loop-claude: a judge decides …`, `loop-claude: before it opens claude …`, `review: a pass gets at most three rounds per chunk …`, `review: a fix for a 🔴 or 🟡 reruns the pass …` and `review: the comprehension check records …`. 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 first two entries. The prose review of PR #312 judged those two to read as amendment logs, each paragraph correcting an earlier one. The prose review of PR #335 found the trust entry, `loop-claude: before it opens claude …`, made of four dated paragraphs, and a 2026-10-21 paragraph on item 120 that records a move which changed no rule; drop that paragraph. The prose review of item 210's PR found the last three. The round-cap entry grows one dated paragraph per chunk. The fix-rerun entry's 2026-10-21 paragraph records a move and says the rule is unchanged; drop it. The comprehension-check entry's 2026-10-13 paragraph overrides parts of the 2026-10-08 one.
### 216. Make larv-review's round count agree with itself on the auto-reviewer: either title its round commits so `round-count` counts them as a pass, or have SKILL.md say they carry no `Answer <pass> round` title.
`skills/larv-review/SKILL.md` §3 "Round cap" makes the external auto-reviewer a pass of its own and each review it posts a round, and says each round closes with a commit titled `Answer <pass> round <n>: <k> 🔴, <m> 🟡; …`. It also says the auto-reviewer's count is the number of its reviews on the PR. `larv-review round-count` (`bin/larv_review/main.py` `round_count`) answers an `Answer auto-reviewer round <n>:` commit with "auto-reviewer: <n>, not a pass: check the commit title", because `bin/review_passes.py` `PASSES`, the list `bin/repo_checks/test_reviewer_launches.py` holds SKILL.md's table to, leaves it out on purpose. A worker who follows the skill therefore gets a warning. Found by round 2 of PR #354's principles pass (item 121).
@@ -172,6 +168,10 @@ They say the same thing for `~/.claude/rules/` (item 95) and `~/.claude/skills/l
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.
### 221. Parse each transcript entry once, where `bin/claude_code/transcript.py` reads it, into a typed value naming its kind, so no consumer works out an entry's kind from a raw `dict`.
"Validate data and build DTOs as early as possible", in `principles/technical-principles.md`, raised 🟢 by the principles audit of item 210's PR. `read_transcript` (`bin/claude_code/transcript.py:16`) returns raw `dict`s, so each consumer, such as `render` beside it and `since_step` in `bin/loop_claude/escalation_mark.py`, calls the helpers in `bin/claude_code/entries.py` (`human_text`, `loop_text`, `assistant_parts`, `tool_call`) to work out an entry's kind again. Parse each line once into types such as a human turn, a loop-claude prompt and an assistant turn, and have every consumer of `claude_code.entries` under `bin/` take those types. The change touches the escalation mark, which the comprehension seats found hard at `bin/loop_claude/cycle/judge.py:153` `escalation_mark` before item 210 moved it: make `since_step` in `bin/loop_claude/escalation_mark.py`, and `Grounds.since_step` and `judge_prompt` in `bin/loop_claude/cycle/judge.py`, easier to read.
### 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.