Answer prose round 1: 0 🔴, 5 🟡; tighten the escalation mark's comments, item 221's detail, and fold three decision entries into item 190

This commit is contained in:
2026-10-23 05:22:15 +02:00
parent d70cbca594
commit 6f98a1855b
6 changed files with 25 additions and 25 deletions
+1 -1
View File
@@ -54,7 +54,7 @@ def part_line(part: object, tool_input_chars: int) -> str:
def verbatim(quote: str, text: str) -> bool:
"""Whether text holds the judge's quote word for word, as plain reads both."""
"""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)
+4 -4
View File
@@ -97,7 +97,7 @@ 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
# escalation_mark.since_step's lines, which an escalation must quote, as escalation_mark.checked says.
# 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
@@ -148,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. A misquoted evidence is Rejected; quotes_checked handles the other quotes."""
"""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
@@ -162,14 +162,14 @@ 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. A quoted answer the records do not hold goes to the human as an interrupt, keeping the escalation it carried; escalation_mark.checked then checks that escalation. Neither misquote is a Failure, which would otherwise exit an unattended loop."""
"""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)
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. escalated_at is the route's mark, as in judge_once."""
"""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"
+2 -2
View File
@@ -58,7 +58,7 @@ def run_cycle(cycle: Cycle) -> Stop | Concluded:
event = step(cycle, state)
if isinstance(event, Stop):
return stopped(cycle, event, event.reason)
# Only a ruling's step-up changes the route within a cycle. No transition reads the route, so it stays out of the states.
# 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)
@@ -68,7 +68,7 @@ def run_cycle(cycle: Cycle) -> Stop | Concluded:
def ruling_step_up(cycle: Cycle, verdict: Verdict) -> StepUp | None:
"""The step-up an interrupt's or a quoted answer's escalation makes, before the human is asked or the worker resumes, so the work after the answer runs on it; None where the route holds."""
"""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)
+3 -3
View File
@@ -19,7 +19,7 @@ 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 the ruling behind answered made, so the worker is told of it; None for none.
# 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
@@ -36,7 +36,7 @@ class Interrupting:
transcript_path: str
ruling: Interrupt | QuotedAnswer
quoted_answers: int = 0
# As on Working: the step-up holds through the answer the human types, and drops on /talk.
# The step-up the ruling made. It holds through the answer the human types, and drops on /talk.
step_up: StepUp | None = None
@@ -70,7 +70,7 @@ class WorkerRan:
@dataclasses.dataclass(frozen=True)
class Ruled:
verdict: Verdict
# The step-up an interrupt's or a quoted answer's escalation made; None for none, and always for a finished or unfinished 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
+9 -9
View File
@@ -1,11 +1,11 @@
"""The escalation mark: one escalation trigger buys the worker one step up a rung, never a second: docs/decisions.md → `routing: a worker whose run ends asking for a higher rung`.
"""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 records 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, and QUOTE_AFTER_STEP, in the judge's schema, tells the next judge that the triggers before it are spent.
- Check. checked keeps an escalation only where it quotes both since_step, the worker's own lines after the mark, and the transcript the judge was shown, so a passage that bought one step cannot buy another.
- 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
@@ -15,7 +15,7 @@ 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 no [loop] line.
# 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.
@@ -35,12 +35,12 @@ def stamped(verdict: Verdict, entries_read: int) -> Verdict:
def moved_to(verdict: Escalating) -> int | None:
"""Where the verdict's escalation would move the mark, if it steps the worker; None where it carries 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, with STEP_LINE after the first at entries where at, the mark, is above 0."""
"""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)
@@ -51,7 +51,7 @@ def since_step(entries: list[dict], at: int) -> str:
def checked(verdict: Verdict, *, since: str, shown: str) -> Verdict:
"""The verdict without its escalation unless the escalation quotes both since, since_step's lines, and 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; it is no failure, which would otherwise exit an unattended loop."""
"""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 -6
View File
@@ -12,8 +12,8 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 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 |
@@ -74,14 +74,14 @@
## Details
### 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).
@@ -170,7 +170,7 @@ In `bin/loop_claude/loop/main.py`'s docstring, the line holding "of one PR, is f
### 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, and the helpers in `bin/claude_code/entries.py` (`human_text`, `loop_text`, `assistant_parts`, `tool_call`) work out an entry's kind each time a consumer asks, as `render` and `escalation_mark.since_step` (`bin/loop_claude/escalation_mark.py`) do. 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 the comprehension seats found hard in `bin/loop_claude/cycle/judge.py` (`escalation_mark`, `Grounds.since_step`): make that place easier to read.
"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 🔴.