Merge remote-tracking branch 'origin/main' into item-400

This commit is contained in:
2026-11-18 17:22:07 +01:00
60 changed files with 911 additions and 476 deletions
+2
View File
@@ -31,6 +31,8 @@
!bin/adf_codec/node_shim/package-lock.json
!bin/adf_codec/node_shim/package.json
!bin/adf_codec/node_shim/shim.mjs
!bin/agent_cycle/
!bin/agent_cycle/*.py
!bin/atlassian/
!bin/atlassian/*.py
!bin/branch_chunks/
+2
View File
@@ -2,6 +2,8 @@
## Unreleased
- do-epic's scorer orders an epic's items by score, then by Blocked by: an item's Moves names a goal as `epic 1.1`, `code health` or `repo 2`, and the epic's achieve goals outweigh the achieve goals of every repo. Nothing calls it yet.
- `todo-item add` and `todo-item edit --detail` refuse a detail whose `Touches:` list touch-predictions cannot read, and `rank_todo.py --check` fails on each item holding one, so rule-hook refuses a commit of such a plan: after updating, run `~/.claude/bin/rank_todo.py --check` in each project and fix each list it names.
- loop-claude hands each worker's claude a Bash output ceiling of 6,000 characters that saves a longer result to a file, rule-hook refuses a Read of a session transcript under ~/.claude/projects, and review-replay takes --bash-ceiling and --read-limit to test such a limit against archived review rounds.
- do-epic picks each epic item's repo, or that it is Claude's work or a human task, by repo-rule.md and a headless claude call, records the pick as a label on the issue and reads it back without a new call; where the rule leaves it unclear it returns a question for the human. The epic backends gain a label write.
- judge-replay <model> --offline replays every archived verdict through a "?" rule, a decision table and a classifier trained on the archive, with no judge call, and counts the interrupts each misses.
+6 -5
View File
@@ -206,24 +206,25 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
### Packages under `bin/`
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `atlassian/`, `branch_chunks/`, `claude_code/`, `command_lines/`, `forge/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `model_routing/`, `notifier/`, `plan/`, `plan_store/`, `record_store/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool. No package imports one that imports it back, which `repo_checks/test_package_cycles.py` checks.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `agent_cycle/`, `atlassian/`, `branch_chunks/`, `claude_code/`, `command_lines/`, `forge/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `model_routing/`, `notifier/`, `plan/`, `plan_store/`, `record_store/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool. No package imports one that imports it back, which `repo_checks/test_package_cycles.py` checks.
- `adf_codec/` converts markdown to ADF, the rich text of Jira Cloud and Confluence, and back, in a throwaway container running a pinned `@larvit/adf-codec`. It builds the container's image inside a heavy slot.
- `agent_cycle/` runs one cycle (`run.py`): a headless claude worker, then the judge of its transcript. It also holds the interrupt, the tmux window and the routing of the worker's rung. The tool that drives the cycles supplies the prompts and file names of its own workflow (`worker_prompts.py`), and reads which items a worker took in. `loop_claude` drives it, and `do_epic` will; `agent_cycle` doesn't import either.
- `atlassian/` holds what the Jira and Confluence backends share (`client.py`): one Atlassian account's credentials, the request both backends send, and each service's error messages.
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
- `deploy_release` imports `release_plan`'s `release_standing`.
- `do_epic/` will hold the tool that drives one Jira epic. So far `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section and language line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `backend/` reads and files the epic's issues and adds those labels.
- `do_epic/` will hold the tool that drives one Jira epic. So far `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section and language line, through `record_store`'s `EpicDescription`. `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`. `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue. `ranking.py` orders an epic's items by score over one chain of goals, the epic's, then code health, then the item's repo's, through `plan`'s ranking. `backend/` reads and files the epic's issues and adds those labels.
- `forge/` tells a GitHub origin from a Gitea one, names a repo beside an origin's and runs that forge's CLI (`commands.py`), and finds a pull request and waits for its checks (`pulls.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release`, `do_epic` and `larv_review`.
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
- `judge_replay` imports `loop_claude`'s judge, verdicts, premises and records.
- `judge_replay` imports `agent_cycle`'s judge and verdicts, and `loop_claude`'s premises, records and `ANSWER_DESTINATIONS`.
- `loop_claude` runs `chunk-preflight` as a process of its own.
- `loop_effects/` holds `Effects`: the processes, terminal, clock and git a tool reaches, injected so its tests can script them. loop-claude, both replay tools and `reviewer-merge-trials`' driver use it.
- `loop_state/` holds where loop-claude keeps its files (`paths.py`), which `rung_replay` reads too.
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy` and `adf_codec`, and reads the memory share that loop-claude waits for. It also gives `mutate_changes` a slot's CPU count.
- `model_routing/` holds the shipped routing ladder (`routing-ladder.json`) and its steps (`ladder.py`), and reads a ladder from that file or a project's own (`ladder_file.py`), for loop-claude, `rule_hook`, `do_epic`, both replay tools and `subagent-rung`. It finds a project's config folder through `project_config`. It also holds the list prices, which `routing_figures` and `transcript_archive` read.
- `notifier/` sends the human a DM through the notifier a project's config names, for `notify` and for loop-claude through `loop_effects`. Its backends are `mattermost.py` and `slack.py`.
- `plan/` is the plan's core, and imports neither `plan_store` nor `release_plan`. It holds an item and the items table's format (`todo_table.py`), releases (`release.py`), the ranking (`ranking.py`, with its score formula in `formula.py` and its blocker order in `blockers.py`), the paths an item's text names (`named_paths.py`) and `citations.py`, which holds `todo.md` and `docs/decisions.md` to each other. `goals_file.py` reads the goals file's sections, goals and goal weights, for the ranking and for `loop_claude`'s premises.
- `plan/` is the plan's core, and imports neither `plan_store` nor `release_plan`. It holds an item and the items table's format (`todo_table.py`), releases (`release.py`), the ranking (`ranking.py`, with its score formula in `formula.py` and its blocker order in `blockers.py`), the paths an item's text names (`named_paths.py`), an item's `Touches:` prediction and where two overlap (`touches.py`), and `citations.py`, which holds `todo.md` and `docs/decisions.md` to each other. `goals_file.py` reads the goals file's sections, goals and goal weights, for the ranking and for `loop_claude`'s premises.
- `plan_store/` reads and writes a project's plan through the store the project's config names (`stores.py`). Every backend meets `plans.py`'s `PlanStore`: a markdown file (`todo_md.py`, which also ranks and checks the file in place, with its text edits in `markdown_edits.py`) or a Jira epic (`jira_epic.py`). `scoring.py` reads the goal weights that both backends rank by. `contract.py` holds the tests every backend that writes must pass; `jira_epic.py` doesn't yet, and its own tests stand in for Jira. `fakes.py` holds a plan in memory.
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
- `record_store/` reads and writes a project's records, each through the store the project's config names (`stores.py`): a markdown file, a Confluence Cloud page (`confluence_page.py`), or, for the goals, a Jira epic's description (`jira_description.py`). `contract.py` holds the tests every backend must pass, and `fakes.py` a store in memory that the tests of other tools use.
@@ -232,7 +233,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `rest_client/` sends a JSON request to a REST API and reads its credentials from an env file, for `notifier`, `atlassian` and `record_store`.
- `review_rules/` holds the larv-review rules that several tools apply: its passes, its review folder, its round commit titles and the comprehension history's format.
- `routing_figures/` measures loop-claude's archive, and each of its projects' default branches, for loop-claude's routing calls.
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the parallel replay runner, the argument reader, the candidate rungs and the exits, and `judge_replay`'s rung search. It reads `loop_claude`'s retry count and models file, and finds that file through `loop_state`'s paths. Its `archive.py` keeps each replay's runs and its report in a `replays/` folder of loop-claude's archive.
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the parallel replay runner, the argument reader, the candidate rungs and the exits, and `judge_replay`'s rung search. It reads `agent_cycle`'s retry count and `loop_claude`'s models file, and finds that file through `loop_state`'s paths. Its `archive.py` keeps each replay's runs and its report in a `replays/` folder of loop-claude's archive.
- `test_env.py` serves the tests.
- `text_files/` reads a Markdown file's `##` sections, quotes a passage and joins names into a list, stamps times in UTC, replaces a file in one step, private where it is new, and gzips a file beside its plain name, by which it reads it afterwards.
- `transcript_archive/` stores loop-claude's transcripts. Its `project_key.py` names each project's archive folder, loop-claude session and models-file entry.
+4
View File
@@ -0,0 +1,4 @@
"""One cycle of a headless claude worker and the judge of its transcript, for every entry point that drives such cycles: loop-claude today, do-epic next (docs/decisions.md → `do-epic: drives one Jira epic …`).
run.py runs a cycle through the states in states.py: worker.py runs the worker, judge.py rules on its transcript, interrupt.py puts a question to the human in the tmux window tmux.py names, and routing.py picks the rung the worker runs on next. An entry point hands the cycle what is its own: its prompts and file names (worker_prompts.py) and how it reads the plan items a worker took in (run.py's Cycle.taken_in). No module here imports an entry point's package: loop_claude imports this one, so bin/repo_checks/test_package_cycles.py fails on such an import. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
"""
@@ -12,13 +12,13 @@ import typing
from claude_code.transcript import assistant_lines, render, Typed
from claude_code.entries import AssistantTurn, Entry
from loop_claude.verdicts import Escalating, Verdict
from loop_claude.quotes import verbatim
from agent_cycle.verdicts import Escalating, Verdict
from agent_cycle.quotes import verbatim
# 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.
# Reply.escalation's description in agent_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."
@@ -3,14 +3,14 @@ import sys
import typing
import uuid
from loop_claude.hand_over import claude_args, ClaudeCommand, hand_over
from agent_cycle.hand_over import claude_args, ClaudeCommand, hand_over
from loop_effects.effects import Effects, say
from failure import Failure
from claude_code.transcript import human_turns, read_transcript
from loop_claude.stop import needs_human, needs_terminal, Stop
from agent_cycle.stop import needs_human, needs_terminal, Stop
from model_routing.ladder import Rung
from loop_claude.direct_message import tell
from loop_claude import tmux
from agent_cycle.direct_message import tell
from agent_cycle import tmux
ANSWER_QUESTION = "answer the question above"
# TALK, what the human types at loop-claude's terminal to open claude for the question, and ASK_ANSWER were picked on 2026-10-17 by a bench of three readers seated as the README's audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it.
@@ -3,19 +3,19 @@ import json
import re
import typing
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS, ANSWERS_RECORDED, typed_answer
from agent_cycle.worker_prompts import answers_recorded, typed_answer
from claude_code.reply import claude_reply, Limited
from loop_effects.effects import Effects
from claude_code.entries import Entry, structured_output
from loop_claude import escalation_mark
from agent_cycle import escalation_mark
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, Judged, QuotedAnswer, Unfinished, Verdict
from agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, Unfinished, Verdict
from claude_code.transcript import human_answers
from transcript_archive.judge_run import JudgeRun
from loop_claude.quotes import plain, verbatim
from loop_claude.cycle.retry import retried
from agent_cycle.quotes import plain, verbatim
from agent_cycle.retry import retried
from model_routing.ladder import Rung
from loop_claude.stop import Stop
from agent_cycle.stop import Stop
from claude_code.tokens import tokens_of
# At 3 to 4 characters a token, 100,000 to 133,000 tokens, which leaves a 200,000-token context room for the reply; the largest session rendered here was 364,000 characters on 2026-10-03.
@@ -56,15 +56,21 @@ QUOTE_RULES = (
FINISHED_RULES = (
"The chunk is the piece of work the worker is on, shipped as one pull request.\n\n"
"finished=true when the chunk is complete: merged, or nothing remains that the worker could do on "
f"its own. Even then, it is finished only once {ANSWERS_RECORDED}.\n\n"
"its own. Even then, it is finished only once {answers_recorded}.\n\n"
"An answer counts as recorded where the premises or the records above already hold it, the human's rules "
"(~/.claude/CLAUDE.md, ~/.claude/rules/, the project's review standards, each headed by its path) included. "
f"It also counts where the transcript shows the worker writing it into {ANSWER_DESTINATIONS}, "
"It also counts where the transcript shows the worker writing it into {answer_destinations}, "
"but not into one of the human's rules.\n\n"
"finished=false when work remains that a further run can "
"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))
def judge_rules(answer_destinations: str) -> str:
"""The rules that end the judge's prompt. answer_destinations names where the entry point's worker may record an answer the human typed."""
return "\n\n".join((INTERRUPT_RULES, QUOTE_RULES, FINISHED_RULES.format(answers_recorded=answers_recorded(answer_destinations), answer_destinations=answer_destinations)))
# Open the task and the transcript in the prompt; the premises and the records come before the task, the rules after the transcript.
# judge_replay.archived_prompt splits each archived prompt on them, so rewording one makes every run archived before it replay as failed.
TASK_HEADING = "The task the worker was given:\n"
@@ -74,7 +80,7 @@ TRANSCRIPT_HEADING = "What the worker did and said, what the human typed on [hum
@dataclasses.dataclass(frozen=True)
class Reply:
answer: str = dataclasses.field(metadata={"description": "With interrupt false, the passage of the premises or the records that answers the worker's question, quoted verbatim, without elisions. Empty otherwise."})
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: loop_claude/escalation_mark.py.
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: agent_cycle/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."})
@@ -122,11 +128,14 @@ class Grounds(typing.NamedTuple):
class Brief(typing.NamedTuple):
"""What the judge reads: the worker's task, the premises and records the worker is judged by, the transcript's entries, and escalated_at, how many of those entries the session held when an escalation last stepped the worker up a rung, 0 before any."""
"""What the judge reads: the worker's task, the premises and records the worker is judged by, and the transcript's entries."""
task: str
premises: str
records: str
# Where the worker may record an answer the human typed, as the entry point names it.
answer_destinations: str
entries: list[Entry]
# How many of the entries the session held when an escalation last stepped the worker up a rung, 0 before any.
escalated_at: int
@@ -274,7 +283,8 @@ def judge_prompt(brief: Brief) -> tuple[str, Grounds]:
f"{TASK_HEADING}{brief.task}\n\n"
f"{TRANSCRIPT_HEADING}"
)
room = max(0, JUDGE_PROMPT_CHARS - len(head) - len(JUDGE_RULES) - 2)
rules = judge_rules(brief.answer_destinations)
room = max(0, JUDGE_PROMPT_CHARS - len(head) - len(rules) - 2)
transcript = escalation_mark.transcript(brief.entries, brief.escalated_at, typed_answer)
# The tail, where an interrupt or a finish lands; the session's transcript grows cycle over cycle.
shown = transcript[max(0, len(transcript) - room):]
@@ -284,4 +294,4 @@ def judge_prompt(brief: Brief) -> tuple[str, Grounds]:
quotable=f"{brief.premises}\n\n{brief.records}",
typed=tuple(human_answers(brief.entries, typed_answer)),
)
return f"{head}{shown}\n\n{JUDGE_RULES}", grounds
return f"{head}{shown}\n\n{rules}", grounds
@@ -3,7 +3,7 @@ import typing
from loop_effects.effects import Effects, say
from failure import Failure
from claude_code.reply import Limited
from loop_claude.stop import Stop
from agent_cycle.stop import Stop
T = typing.TypeVar("T")
@@ -2,9 +2,9 @@
The worker, and the session /talk opens, run on a Route (model_routing/route.py). A model off the ladder gets a route without an item, and it is never stepped.
- 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.
- Start. The entry point finds the plan item that routes a fresh chunk, as loop_claude/routed_item.py does; 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. next_route raises the route after an unfinished verdict (unfinished_route), or an interrupt or a quoted answer that carries an escalation (escalated_route); escalation_cap bounds an escalation, and loop_claude/escalation_mark.py states the escalation mark's rule. step_up names the change where it changes the worker line, which the archive records.
- Step-up. next_route raises the route after an unfinished verdict (unfinished_route), or an interrupt or a quoted answer that carries an escalation (escalated_route); escalation_cap bounds an escalation, and agent_cycle/escalation_mark.py states the escalation mark's rule. step_up names the change where it changes the worker line, which the archive records.
- Judge. judge_rung picks the rung of the judge of a JUDGE_REPLAYED model.
A step-up weighs five rungs:
@@ -29,13 +29,10 @@ Each verdict then moves the rung by one rule, and the rung never falls. The rung
"""
import dataclasses
from release_plan.release_standing import chunk_item, LastCut, Next
from loop_claude import escalation_mark
from failure import Failure
from loop_claude.verdicts import Interrupt, QuotedAnswer, Unfinished
from plan.todo_table import Item, NoItemsTable
from agent_cycle import escalation_mark
from agent_cycle.verdicts import Interrupt, QuotedAnswer, Unfinished
from plan.todo_table import Item
from model_routing.ladder import Ladder, ProjectRung, Rung
from plan_store.plans import Plan
from model_routing.route import Route
UNFINISHED_PER_STEP = 2
@@ -45,20 +42,6 @@ ESCALATION_CAP = 2
JUDGE_REPLAYED = ("claude-opus-5-5",)
def routed_item(plan: Plan | Failure, cut: LastCut, item_id: int | None = None) -> Item | Failure | None:
"""The plan's item item_id, or without one the item release_standing.chunk_item picks from plan, weighed against the last cut; None when there is none, or it lacks L, E or I."""
if isinstance(plan, NoItemsTable):
return None
if isinstance(plan, Failure):
return plan
if item_id is None:
pick = chunk_item(plan.items, cut)
takes = pick.item if isinstance(pick, Next) else None
else:
takes = next((item for item in plan.items if item.id == item_id), None)
return takes if takes and takes.likelihood and takes.escape_and_impact else None
def first_route(project: ProjectRung, item: Item | None) -> Route:
"""The route a chunk starts on: the rung its item's L picks from the project's rung, or the project's rung without an item."""
if item is None:
@@ -133,7 +116,7 @@ def unfinished_route(project: ProjectRung, route: Route, verdict: Unfinished) ->
def escalated_route(project: ProjectRung, route: Route, verdict: Interrupt | QuotedAnswer) -> Route:
"""The route after an interrupt or a quoted answer. Without an escalation it holds, since neither is an unfinished verdict.
With one, the rung rises to floor_rung, which the verdict's highest L taken in may raise. Where floor_rung lies below escalation_cap, the rung steps one up from it and the mark moves, as loop_claude/escalation_mark.py says; at the cap the rung stays on floor_rung and the mark holds.
With one, the rung rises to floor_rung, which the verdict's highest L taken in may raise. Where floor_rung lies below escalation_cap, the rung steps one up from it and the mark moves, as agent_cycle/escalation_mark.py says; at the cap the rung stays on floor_rung and the mark holds.
"""
mark = escalation_mark.moved_to(verdict)
if mark is None:
@@ -2,32 +2,30 @@ import dataclasses
import pathlib
import typing
from loop_claude.cycle.states import Active, Archived, Closing, Ended, Event, HumanTalked, HumanTyped, Interrupting, Judging, QUOTED_ANSWERS_PER_CYCLE, Ruled, State, to_the_human, transition, TypedAnswer, WorkerRan, Working
from agent_cycle.states import Active, Archived, Closing, Ended, Event, HumanTalked, HumanTyped, Interrupting, Judging, QUOTED_ANSWERS_PER_CYCLE, Ruled, State, to_the_human, transition, TypedAnswer, WorkerRan, Working
from transcript_archive.write import archive
from loop_claude.cycle.worker import AUTO_COMPACT_WINDOW, COMPACT_WINDOW, run_worker, worker_args
from agent_cycle.worker import AUTO_COMPACT_WINDOW, COMPACT_WINDOW, run_worker, worker_args
from claude_code.output_limits import BASH_CEILING, BASH_CEILING_CHARACTERS
from loop_claude.cycle.judge import Brief, judge, Rejected
from loop_claude.cycle import chunk_items
from agent_cycle.judge import Brief, judge, Rejected
from claude_code.session import delete_session, Session, session_open, transcript_file
from loop_effects.effects import Effects, say
from claude_code.entries import Entry
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, Judged, QuotedAnswer, Unfinished, Verdict
from loop_claude.cycle.interrupt import interrupt, Talked, WorkerSession
from agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished, Verdict
from agent_cycle.interrupt import interrupt, Talked, WorkerSession
from transcript_archive.judge_run import JudgeRun
from transcript_archive.read import last_spent
from loop_claude.routing import next_route, step_up, StepUp
from agent_cycle.routing import next_route, step_up, StepUp
from transcript_archive import outcomes
from plan_store.plans import Plan
from model_routing.ladder import ProjectRung, Rung
from loop_claude.cycle import prompts
from claude_code.transcript import read_transcript
from loop_claude.cycle.retry import retried
from agent_cycle.retry import retried
from model_routing.route import Route
from loop_claude.cycle import spend
from loop_claude.stop import Stop
from loop_claude.tmux import Window
from agent_cycle import spend
from agent_cycle.stop import Stop
from agent_cycle.tmux import Window
from model_routing import worker_rungs
from agent_cycle.worker_prompts import WorkerPrompts
@dataclasses.dataclass(frozen=True)
@@ -44,6 +42,8 @@ class Cycle:
# The rung routing.judge_rung picks for the project's judge model.
judge: Rung
premises: str
# The prompts and the file names of the entry point that drives the cycle.
prompts: WorkerPrompts
# The project's rung on the ladder that model_routing/ladder_file.py read as the cycle started; None for a model off the ladder.
project: ProjectRung | None
project_archive: pathlib.Path
@@ -52,8 +52,8 @@ class Cycle:
route: Route
session: Session
task: str
# The plan on the default branch as the cycle starts, which scores the items the worker names.
plan: Plan | Failure
# The plan items a transcript's worker has taken into its chunk, as the entry point reads and scores them.
taken_in: typing.Callable[[list[Entry]], TakenIn]
# Empty when the previous cycle's verdict was not Unfinished.
unfinished_evidence: str
# The tmux window the loop runs in, which an interrupt marks.
@@ -120,7 +120,7 @@ def step(cycle: Cycle, state: Active) -> Event | Stop:
def work(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, stepped: bool) -> WorkerRan | Stop:
if isinstance(answered, QuotedAnswer):
say(f"\n=== {prompts.QUOTE_SOURCES} answered: {answered.question} ===\n{answered.answer}", cycle.effects, stdout=True)
say(f"\n=== {cycle.prompts.quote_sources} answered: {answered.question} ===\n{answered.answer}", cycle.effects, stdout=True)
# 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, stepped), worker_environment(cycle), cycle.effects), cycle.effects):
return stop
@@ -139,24 +139,32 @@ def worker_session(cycle: Cycle, transcript_path: str) -> WorkerSession:
def worker_start(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, stepped: bool) -> list[str]:
if isinstance(answered, QuotedAnswer):
return worker_args(cycle.session, cycle.route.rung, prompts.answered(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.answered(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
if isinstance(answered, TypedAnswer):
return worker_args(cycle.session, cycle.route.rung, prompts.typed(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.typed(answered.question, answered.answer, cycle.route, cycle.project, stepped), 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)
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.resumed(cycle.unfinished_evidence, cycle.route, cycle.project), resume=True)
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.project, cycle.facts), resume=False)
def rule(cycle: Cycle, transcript_path: str, quoted_answers: int) -> Ruled | Stop:
"""The judge's ruling. Unless it is Finished, code stamps it with the items the worker names on its latest `Chunk items:` line. An interrupt or a quoted answer is archived as it is ruled, on the route the worker ran on until then, and then any step-up it makes, so the figures charge each stretch of work to its own rung."""
"""The judge's ruling. Unless it is Finished, code stamps it with the items the worker took in, as cycle.taken_in reads them. An interrupt or a quoted answer is archived as it is ruled, on the route the worker ran on until then, and then any step-up it makes, so the figures charge each stretch of work to its own rung."""
entries = read_transcript(transcript_path)
if isinstance(entries, Failure):
return Stop(1, entries.reason)
verdict = judge(cycle.root, Brief(cycle.task, cycle.premises, cycle.records, entries, cycle.route.escalated_at), cycle.judge, cycle.effects, lambda rejected: keep_rejection(cycle, transcript_path, rejected))
brief = Brief(
task=cycle.task,
premises=cycle.premises,
records=cycle.records,
answer_destinations=cycle.prompts.answer_destinations,
entries=entries,
escalated_at=cycle.route.escalated_at,
)
verdict = judge(cycle.root, brief, cycle.judge, cycle.effects, lambda rejected: keep_rejection(cycle, transcript_path, rejected))
if isinstance(verdict, Stop):
return verdict
if not isinstance(verdict, Finished):
verdict = dataclasses.replace(verdict, taken_in=chunk_items.taken_in(entries, cycle.plan))
verdict = dataclasses.replace(verdict, taken_in=cycle.taken_in(entries))
if not isinstance(verdict, Interrupt | QuotedAnswer):
return Ruled(verdict)
annotation = annotation_of(cycle, transcript_path, entries, verdict.judged)
@@ -183,8 +191,8 @@ def annotation_of(cycle: Cycle, transcript_path: str, entries: list[Entry], judg
def ruling_outcome(cycle: Cycle, ruling: Interrupt | QuotedAnswer, quoted_answers: int, annotation: outcomes.Annotation) -> str:
"""The archive's outcome for a ruling: interrupted where it goes to the human, with the question put to them, and else answered from the premises or the records."""
if isinstance(ruling, QuotedAnswer) and not to_the_human(ruling, quoted_answers):
return outcomes.answered(question=ruling.question, sources=prompts.QUOTE_SOURCES, answer=ruling.answer, evidence=ruling.evidence, escalation=ruling.escalation, judge=str(cycle.judge), worker=cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
return outcomes.interrupted(question_for(ruling), ruling.evidence, str(cycle.judge), ruling.escalation, cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
return outcomes.answered(question=ruling.question, sources=cycle.prompts.quote_sources, answer=ruling.answer, evidence=ruling.evidence, escalation=ruling.escalation, judge=str(cycle.judge), worker=cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
return outcomes.interrupted(question_for(cycle, ruling), ruling.evidence, str(cycle.judge), ruling.escalation, cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> Stop | None:
@@ -197,7 +205,7 @@ def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> St
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) -> HumanTyped | HumanTalked | Stop:
"""The human's answer to a ruling that rule archived as it ruled; the human's answer then grows the transcript."""
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
answer = interrupt(question_for(ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.window, cycle.effects)
answer = interrupt(question_for(cycle, ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.window, cycle.effects)
match answer:
case Stop():
return answer
@@ -221,10 +229,10 @@ def archived_step(project_archive: pathlib.Path, transcript_path: str, task: str
return archived(project_archive, transcript_path, task, outcomes.stepped_up(step_up.after.worker_line()), effects)
def question_for(ruling: Interrupt | QuotedAnswer) -> str:
def question_for(cycle: Cycle, ruling: Interrupt | QuotedAnswer) -> str:
if isinstance(ruling, Interrupt):
return ruling.question
return prompts.past_the_cap(ruling.question, ruling.answer, QUOTED_ANSWERS_PER_CYCLE)
return cycle.prompts.past_the_cap(ruling.question, ruling.answer, QUOTED_ANSWERS_PER_CYCLE)
def close(cycle: Cycle, transcript_path: str, verdict: Finished | Unfinished) -> Archived | Stop:
@@ -1,6 +1,6 @@
import dataclasses
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from model_routing.route import Route
# A backstop for what the judge misses, such as a reworded repeat, so the worker cannot loop unattended on answers quoted from the premises or the records.
@@ -4,7 +4,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from loop_claude import quotes
from agent_cycle import quotes
class Verbatim(unittest.TestCase):
+58
View File
@@ -0,0 +1,58 @@
"""A worker's prompts: those the entry point driving the cycle words, and those that resume a worker with an answer to its question.
An entry point is a tool that drives cycles, such as loop-claude. It words the prompts of its own workflow and names the files of its project. WorkerPrompts holds those, so the cycle doesn't import an entry point to word a prompt.
"""
import dataclasses
import typing
from model_routing.ladder import ProjectRung
from model_routing.route import Route
from claude_code.transcript import Typed
# Opens typed's prompt, with the answer on the line after it, so typed_answer finds the answer at the prompt's start, whatever the question holds.
TYPED_HERE = "The human answered your question at loop-claude's terminal:"
def answers_recorded(destinations: str) -> str:
"""What a chunk owes each answer the human typed, before it is finished. destinations names where an answer may be recorded."""
return f"every answer the human typed in it that a later chunk could need is recorded in {destinations} at the one place it governs"
def typed_answer(prompt: str) -> Typed | None:
"""Splits a prompt from WorkerPrompts.typed into its answer and the rest, so the judge reads the answer as the human's; None for any other prompt."""
opening = f"{TYPED_HERE}\n"
if not prompt.startswith(opening):
return None
answer, _, rest = prompt.removeprefix(opening).partition("\n\n")
return Typed(rest, answer)
@dataclasses.dataclass(frozen=True)
class WorkerPrompts:
"""What an entry point supplies to the prompts of its cycles."""
# The prompt that starts a worker, from its task, the premises, its route, the project's rung and the facts found before the cycle.
fresh: typing.Callable[[str, str, Route, ProjectRung | None, str], str]
# The prompt that resumes a worker whose previous run ended before the chunk was finished, from the evidence of the unfinished verdict, if there was one.
resumed: typing.Callable[[str, Route, ProjectRung | None], str]
# The sentences that depend on the worker's rung, each after a space, to follow the sentence a prompt ends on.
rungs_held: typing.Callable[[Route, ProjectRung | None], str]
# Where the judge may quote an answer from, named as the human and the worker see them.
quote_sources: str
# Where the worker may record an answer the human typed.
answer_destinations: str
def answered(self, question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""stepped is whether the answer's ruling stepped the worker up."""
return f"Your question: {question}\n\n{self.quote_sources} answers it:\n\n{answer}\n\nContinue the task.{self.stepped_to(route, project, stepped)}"
def typed(self, question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The prompt that resumes the worker with the human's answer to an interrupt. answer is one line, as the terminal reads it."""
return f"{TYPED_HERE}\n{answer}\n\nYour question was: {question}\n\nContinue the task. The chunk is finished only once {answers_recorded(self.answer_destinations)}.{self.stepped_to(route, project, stepped)}"
def stepped_to(self, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The sentences naming the worker's new rung, as resumed has them, where the ruling that brought the answer stepped the worker up; empty otherwise."""
return f" Your request for a higher rung went through: loop-claude runs you on {route.rung}. The escalation triggers that fired before this step are spent.{self.rungs_held(route, project)}" if stepped else ""
def past_the_cap(self, question: str, answer: str, cap: int) -> str:
"""The question a quoted answer puts to the human once the cycle's quoted answers reach the cap."""
return f"{question}\n\n{self.quote_sources} says:\n{answer}\n\nThose files have answered {cap} questions this cycle, the most allowed, so this one comes to you."
+128
View File
@@ -0,0 +1,128 @@
"""The order do-epic works an epic's items in: by score, then each blocker above what it blocks (docs/decisions.md → `do-epic: drives one Jira epic …`).
An item scores by the epic's formula over one chain of goals: the epic's goals, then code health, then the goals of the item's repo. An item without a repo has only the epic's goals. Each achieve goal weighs 0.97 of the one above it in the chain, and the epic's achieve goals weigh the same in every repo, so an achieve goal of the epic outweighs every achieve goal of a repo, whichever repos the two items are in. chain_scoring says what code health and a maintain goal weigh.
An item's Moves names a goal by its scope, as plan/todo_table.py's EPIC_GOAL says."""
import ast
import dataclasses
import decimal
from plan.blockers import blockers_first
from plan.todo_table import CODE_HEALTH, EPIC_GOAL, Item, REPO_GOAL, SHAPE
from failure import Failure
from plan.goals_file import GOAL_STEP, goal_weights, Mark, numbered, ranked_goals
from review_rules.comprehension_history import latest_overall
from plan.formula import parse_formula
from plan import ranking
from plan_store.jira_epic import SET_SCORES
MARK_IT = "is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so the epic's items can be scored"
@dataclasses.dataclass(frozen=True)
class RepoRanking:
"""What a repo's own plan is ranked by: its goals file, its decision log and its comprehension history, each as text, and its readability floor."""
goals_text: str
decisions: str
history: str
floor: decimal.Decimal
@dataclasses.dataclass(frozen=True)
class EpicItem:
"""One of an epic's open items. An Item names a release and an epic item has none: give every item of one epic the same release, so that no blocker sits in a later release than what it blocks. repo is the name of the repo the item is worked in; None where it has none."""
item: Item
repo: str | None
def ranked(items: list[EpicItem], formula: str, epic_goals: str, repos: dict[str, RepoRanking]) -> list[tuple[Item, float]] | Failure:
"""Each item with its score: a question first, then a security finding, then by score from highest, then by ID, and then each blocker above every item it blocks. formula is the epic's, epic_goals the text under its ## Goals, and repos holds, by name, each repo an item is in. An item without a score fails, so leave out an issue a person filed and nobody scored."""
parsed = parse_formula(formula, ranking.variables(SHAPE))
if isinstance(parsed, Failure):
return parsed
scorings: dict[str | None, ranking.Scoring] = {}
scored = []
for each in items:
name = f"item {each.item.id}"
if each.repo not in scorings:
if each.repo is not None and each.repo not in repos:
return Failure(f"{name} is in the repo {each.repo}, whose goals were not read")
scoring = chain_scoring(parsed, epic_goals, each.repo, repos[each.repo] if each.repo else None)
if isinstance(scoring, Failure):
return scoring
scorings[each.repo] = scoring
value = unscored(each.item, name) or misnamed_goal(each, scorings[each.repo], name) or ranking.item_score(each.item, scorings[each.repo], name)
if isinstance(value, Failure):
return value
scored.append((each.item, value))
scored.sort(key=lambda pair: (ranking.FIRST.get(pair[0].exempt, len(ranking.FIRST)), -pair[1], pair[0].id))
return blockers_first(scored)
def chain_scoring(formula: ast.Expression, epic_goals: str, repo: str | None, own: RepoRanking | None) -> ranking.Scoring | Failure:
"""How an item in repo scores: the chain's goals, and what each achieve goal weighs. The bar is 0, since a bar decides what is filed, and the order holds every item that was.
goal_weights scales a chain's weights to sum to 1. Here they are scaled so that the epic's achieve goals sum to 1 instead, in every chain, or the chain's first achieve goal weighs 1 where the epic has none, which makes the scores of items in different repos comparable.
Code health and a maintain goal weigh by the rules every project's plan follows, which an epic doesn't change: code health weighs four times its place while its repo is unmeasured or under its readability floor, and plan/ranking.py's weight_of weighs a maintain goal. Either may then outweigh an achieve goal of the epic. "The epic wins" in the decision settles the epic's goals against a repo's, and code health is neither's: it is every project's, and a repo that is hard to read costs each epic item worked in it."""
goals = chain(epic_goals, repo, own)
if isinstance(goals, Failure):
return goals
if unmarked := next((goal for goal, mark in goals if mark is None), None):
whose, _, number = unmarked.partition(" ")
return Failure(f"{'the epic' if whose == 'epic' else repo}'s goal {number} {MARK_IT}")
overall = latest_overall(own.history) if own and CODE_HEALTH in dict(goals) else None
if isinstance(overall, Failure):
return Failure(f"{repo}: {overall.reason}")
# goal_weights fails only on a goal without a mark, and the check above has named that goal as the epic's or the repo's.
weights = goal_weights(goals, overall, own.floor if own else decimal.Decimal(0))
if isinstance(weights, Failure):
return weights
achieve = [goal for goal, mark in goals if mark == "Achieve"]
of_epic = len([goal for goal in achieve if goal.startswith(EPIC_GOAL)])
# Under an epic without an achieve goal, the first achieve goal of each chain weighs 1.
scale = total(len(achieve)) / (total(of_epic) or 1)
return ranking.Scoring(SHAPE, formula, 0, 0, dict(goals), {goal: weight * scale for goal, weight in weights.items()})
def total(goals: int) -> float:
"""What this many achieve goals weigh together before goal_weights scales them, the first 1 and each 0.97 of the one above it."""
return sum(GOAL_STEP**place for place in range(goals))
def chain(epic_goals: str, repo: str | None, own: RepoRanking | None) -> list[tuple[str, Mark]] | Failure:
"""Every goal an item in repo may name, in rank order, each with its mark. The epic's goals come first, as `epic <number>`. For an item with a repo, whose ranking is own, code health follows unless the repo's goals file voids it, then the repo's goals as `repo <number>`."""
epic = numbered(epic_goals)
if isinstance(epic, Failure):
return Failure(epic.reason.replace("the goals file's", "the epic's"))
scoped = [(f"{EPIC_GOAL}{number}", mark) for number, mark in epic]
if own is None:
return scoped
goals = ranked_goals(own.goals_text, own.decisions)
if isinstance(goals, Failure):
return Failure(f"{repo}: {goals.reason}")
return [*scoped, *((goal if goal == CODE_HEALTH else f"{REPO_GOAL}{goal}", mark) for goal, mark in goals)]
def unscored(item: Item, name: str) -> Failure | None:
"""Why the item cannot be scored, such as an issue a person filed and nobody scored; None where it holds each score."""
missing = next((score for score in SET_SCORES if score not in item.scores), None)
return Failure(f"{name} has no {missing}: score it on {', '.join(SET_SCORES[:-1])} and {SET_SCORES[-1]} before it is ranked") if missing else None
def misnamed_goal(each: EpicItem, scoring: ranking.Scoring, name: str) -> Failure | None:
"""Why the item may not name one of the goals it names, in the epic's terms; None where its chain holds each."""
for goal, _ in each.item.moves:
if goal in scoring.goals:
continue
if goal.startswith(EPIC_GOAL):
return Failure(f"{name} names {goal}, which the epic's ## Goals does not number")
if each.repo is None:
scoped = f"; write `{EPIC_GOAL}{goal}` for the epic's goal" if goal[0].isdigit() else f"; name only the epic's goals, as in `{EPIC_GOAL}1 by 5`"
return Failure(f"{name} names {goal}, but isn't worked in a repo{scoped}")
if goal == CODE_HEALTH:
return Failure(f"{name} names {CODE_HEALTH}, which {each.repo}'s goals file voids")
if not goal.startswith(REPO_GOAL):
return Failure(f"{name} names goal {goal} without saying whose it is; write `{EPIC_GOAL}{goal}` for the epic's goal or `{REPO_GOAL}{goal}` for its repo's")
return Failure(f"{name} names {goal}, which the ## Goals of {each.repo}'s goals file does not number")
return None
+159
View File
@@ -0,0 +1,159 @@
import dataclasses
import decimal
import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.ranking import chain, EpicItem, ranked, RepoRanking
from failure import Failure
from plan.todo_table import Item, parse_moves
EPIC_GOALS = "1. **Achieve:** Ship invoices.\n2. **Achieve:** Cut support mail.\n3. **Maintain:** Leak no customer data.\n"
VOIDED = RepoRanking("## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** Fast builds.\n", "", "", decimal.Decimal("7.0"))
HEALTHY = RepoRanking("## Goals\n\n1. **Achieve:** Fast builds.\n2. **Maintain:** Stay on the LTS.\n", "", "", decimal.Decimal("7.0"))
# A scoring run of a repo whose overall mean is {overall}.
SCORED = "# Comprehension history\n\n## 2026-10-08T12:00:00Z, PR #1 at aaaaaaa\n\n| Seat | Overall |\n|---|---|\n| Mid A | 6 |\n| Mean | {overall} |\n"
# What the epic's two achieve goals weigh together before they are scaled to sum to 1, the second 0.97 of the first.
TOTAL = 1 + 0.97
def item(id_: int, moves: str, repo: str | None = "billing-api", exempt: str = "", blocked_by: tuple[int, ...] = ()) -> EpicItem:
parsed = parse_moves(f"item {id_}", moves)
assert not isinstance(parsed, Failure), parsed
return EpicItem(Item(id_, (0, 0, 0), exempt, f"**Item {id_}.**", {"L": 1, "E": 1, "I": 1, "S": 1}, parsed, blocked_by), repo) # type: ignore[arg-type]
def order(items: list[EpicItem], repos: dict[str, RepoRanking], formula: str = "V") -> list[int] | Failure:
found = ranked(items, formula, EPIC_GOALS, repos)
return found if isinstance(found, Failure) else [scored.id for scored, _ in found]
class MovesSpellingTest(unittest.TestCase):
def test_a_moves_cell_names_an_epics_goal_and_a_repos_goal_by_their_scope(self) -> None:
self.assertEqual(parse_moves("item 1", "epic 1.1 by 8, code health by 5, repo 2 by 4"), (("epic 1.1", 8), ("code health", 5), ("repo 2", 4)))
def test_a_moves_cell_refuses_an_epic_goal_beside_its_own_sub_goal(self) -> None:
self.assertIsInstance(parse_moves("item 1", "epic 1 by 8, epic 1.1 by 5"), Failure)
self.assertEqual(parse_moves("item 1", "epic 1 by 8, repo 1.1 by 5"), (("epic 1", 8), ("repo 1.1", 5)))
class ChainTest(unittest.TestCase):
def test_the_chain_is_the_epics_goals_then_code_health_then_the_repos_goals(self) -> None:
self.assertEqual(chain(EPIC_GOALS, "web", HEALTHY), [("epic 1", "Achieve"), ("epic 2", "Achieve"), ("epic 3", "Maintain"), ("code health", "Achieve"), ("repo 1", "Achieve"), ("repo 2", "Maintain")])
def test_a_repo_that_voids_code_health_leaves_it_out_of_its_chain(self) -> None:
self.assertEqual(chain(EPIC_GOALS, "billing-api", VOIDED), [("epic 1", "Achieve"), ("epic 2", "Achieve"), ("epic 3", "Maintain"), ("repo 1", "Achieve")])
def test_an_item_without_a_repo_weighs_only_the_epics_goals(self) -> None:
self.assertEqual(chain(EPIC_GOALS, None, None), [("epic 1", "Achieve"), ("epic 2", "Achieve"), ("epic 3", "Maintain")])
def test_an_epic_without_a_numbered_goal_fails(self) -> None:
self.assertEqual(chain("Ship it.\n", None, None), Failure("the epic's ## Goals has no numbered goal"))
class RankedTest(unittest.TestCase):
def test_each_goal_weighs_0_97_of_the_one_above_it_in_the_chain(self) -> None:
found = ranked([item(1, "repo 1 by 10"), item(2, "epic 2 by 10"), item(3, "epic 1 by 10")], "V", EPIC_GOALS, {"billing-api": VOIDED})
assert not isinstance(found, Failure), found
self.assertEqual([scored.id for scored, _ in found], [3, 2, 1])
for (_, value), expected in zip(found, (10 / TOTAL, 9.7 / TOTAL, 10 * 0.97**2 / TOTAL)):
self.assertAlmostEqual(value, expected)
def test_where_the_epic_and_a_repo_disagree_the_epic_wins(self) -> None:
self.assertEqual(order([item(1, "repo 1 by 5"), item(2, "epic 2 by 5")], {"billing-api": VOIDED}), [2, 1])
def test_items_of_two_repos_rank_in_one_order_each_by_its_own_repos_chain(self) -> None:
repos = {"billing-api": VOIDED, "web": HEALTHY}
self.assertEqual(order([item(1, "repo 1 by 5"), item(2, "repo 1 by 6", repo="web"), item(3, "epic 1 by 9", repo="web")], repos, "V * 0 + S + I"), [1, 2, 3])
self.assertEqual(order([item(1, "repo 1 by 5"), item(2, "repo 2 by 9", repo="web")], repos), [2, 1])
def test_an_item_without_a_repo_scores_by_the_epics_goals_alone(self) -> None:
found = ranked([item(1, "epic 1 by 10", repo=None)], "V", EPIC_GOALS, {})
assert not isinstance(found, Failure), found
self.assertAlmostEqual(found[0][1], 10 / TOTAL)
def test_an_item_without_a_repo_may_not_name_a_repos_goal_or_code_health(self) -> None:
self.assertEqual(order([item(4, "repo 1 by 5", repo=None)], {}), Failure("item 4 names repo 1, but isn't worked in a repo; name only the epic's goals, as in `epic 1 by 5`"))
self.assertEqual(order([item(4, "code health by 5", repo=None)], {}), Failure("item 4 names code health, but isn't worked in a repo; name only the epic's goals, as in `epic 1 by 5`"))
self.assertEqual(order([item(4, "2 by 5", repo=None)], {}), Failure("item 4 names 2, but isn't worked in a repo; write `epic 2` for the epic's goal"))
def test_a_goal_without_its_scope_is_refused(self) -> None:
self.assertEqual(order([item(4, "1 by 5")], {"billing-api": VOIDED}), Failure("item 4 names goal 1 without saying whose it is; write `epic 1` for the epic's goal or `repo 1` for its repo's"))
def test_an_epics_goal_outweighs_a_repos_goal_across_repos_with_chains_of_different_lengths(self) -> None:
long = RepoRanking("## Goals\n\n" + "".join(f"{place}. **Achieve:** Goal {place}.\n" for place in range(1, 10)), "", "", decimal.Decimal("7.0"))
found = ranked([item(1, "repo 1 by 10"), item(2, "epic 2 by 10", repo="web"), item(3, "epic 2 by 10", repo=None)], "V", EPIC_GOALS, {"billing-api": VOIDED, "web": long})
assert not isinstance(found, Failure), found
self.assertEqual([scored.id for scored, _ in found], [2, 3, 1])
for (_, value), expected in zip(found, (9.7 / TOTAL, 9.7 / TOTAL, 10 * 0.97**2 / TOTAL)):
self.assertAlmostEqual(value, expected)
def test_an_epic_without_an_achieve_goal_weighs_each_repos_first_achieve_goal_1(self) -> None:
two = dataclasses.replace(VOIDED, goals_text=VOIDED.goals_text + "2. **Achieve:** Small images.\n")
found = ranked([item(1, "repo 1 by 10"), item(2, "repo 1 by 10", repo="web"), item(3, "repo 2 by 10", repo="web")], "V", "1. **Maintain:** Leak no customer data.\n", {"billing-api": VOIDED, "web": two})
assert not isinstance(found, Failure), found
for (_, value), expected in zip(found, (10, 10, 9.7)):
self.assertAlmostEqual(value, expected)
def test_an_item_without_a_score_fails_naming_it(self) -> None:
unscored = EpicItem(dataclasses.replace(item(4, "").item, scores={}), None)
self.assertEqual(ranked([unscored], "V", EPIC_GOALS, {}), Failure("item 4 has no L: score it on L, E, I and S before it is ranked"))
def test_an_epic_that_numbers_a_goal_twice_fails(self) -> None:
self.assertEqual(chain("1. **Achieve:** A.\n1. **Achieve:** B.\n", None, None), Failure("the epic's ## Goals numbers 1, 1; number each goal by its position"))
def test_a_goal_the_chain_does_not_hold_is_refused(self) -> None:
self.assertEqual(order([item(4, "epic 9 by 5")], {"billing-api": VOIDED}), Failure("item 4 names epic 9, which the epic's ## Goals does not number"))
self.assertEqual(order([item(4, "repo 9 by 5")], {"billing-api": VOIDED}), Failure("item 4 names repo 9, which the ## Goals of billing-api's goals file does not number"))
self.assertEqual(order([item(4, "code health by 5")], {"billing-api": VOIDED}), Failure("item 4 names code health, which billing-api's goals file voids"))
def test_an_item_in_a_repo_without_premises_fails(self) -> None:
self.assertEqual(order([item(4, "epic 1 by 5", repo="ghost")], {}), Failure("item 4 is in the repo ghost, whose goals were not read"))
def test_a_goal_marked_neither_way_fails_naming_whose_it_is(self) -> None:
unmarked = RepoRanking("## Goals\n\n1. Fast builds.\n", "", "", decimal.Decimal("7.0"))
self.assertEqual(order([item(4, "epic 1 by 5")], {"billing-api": unmarked}), Failure("billing-api's goal 1 is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so the epic's items can be scored"))
found = ranked([item(4, "epic 1 by 5", repo=None)], "V", "1. Ship invoices.\n", {})
self.assertEqual(found, Failure("the epic's goal 1 is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so the epic's items can be scored"))
def test_a_repos_goals_file_that_cannot_be_read_fails_naming_the_repo(self) -> None:
self.assertEqual(order([item(4, "epic 1 by 5")], {"billing-api": RepoRanking("# Billing\n", "", "", decimal.Decimal("7.0"))}), Failure("billing-api: the goals file has no ## Goals heading"))
def test_code_health_weighs_four_times_its_place_while_the_repo_is_unmeasured_or_under_its_floor(self) -> None:
for history, times in (("", 4), (SCORED.format(overall="6.9"), 4), (SCORED.format(overall="7.0"), 1)):
with self.subTest(history=history):
found = ranked([item(1, "code health by 10", repo="web"), item(2, "repo 1 by 10", repo="web")], "V", EPIC_GOALS, {"web": dataclasses.replace(HEALTHY, history=history)})
assert not isinstance(found, Failure), found
self.assertAlmostEqual(found[0][1], times * 10 * 0.97**2 / TOTAL)
self.assertAlmostEqual(found[1][1], 10 * 0.97**3 / TOTAL)
def test_code_health_weighs_four_times_its_place_under_a_floor_the_repo_sets_higher(self) -> None:
found = ranked([item(1, "code health by 10", repo="web")], "V", EPIC_GOALS, {"web": dataclasses.replace(HEALTHY, history=SCORED.format(overall="7.5"), floor=decimal.Decimal("8.0"))})
assert not isinstance(found, Failure), found
self.assertAlmostEqual(found[0][1], 4 * 10 * 0.97**2 / TOTAL)
def test_a_history_that_cannot_be_read_fails_naming_the_repo(self) -> None:
found = order([item(1, "code health by 10", repo="web")], {"web": dataclasses.replace(HEALTHY, history=SCORED.format(overall="high"))})
assert isinstance(found, Failure), found
self.assertTrue(found.reason.startswith("web: ") and len(found.reason) > len("web: None"), found.reason)
def test_a_formula_that_gives_an_item_no_finite_score_fails_naming_the_item(self) -> None:
self.assertEqual(order([item(4, "epic 1 by 5")], {"billing-api": VOIDED}, "10 ** 400 * V * 10 ** 400"), Failure("the formula gives item 4 no finite score"))
def test_each_goal_an_item_names_is_checked(self) -> None:
self.assertEqual(order([item(4, "epic 1 by 5, repo 9 by 5")], {"billing-api": VOIDED}), Failure("item 4 names repo 9, which the ## Goals of billing-api's goals file does not number"))
def test_a_question_then_a_security_finding_rank_before_any_score(self) -> None:
self.assertEqual(order([item(1, "epic 1 by 10"), item(2, "epic 2 by 1", exempt="security"), item(3, "", exempt="question")], {"billing-api": VOIDED}), [3, 2, 1])
def test_a_blocker_ranks_above_the_item_it_blocks_and_a_tie_goes_to_the_older_item(self) -> None:
self.assertEqual(order([item(1, "epic 1 by 9", blocked_by=(3,)), item(2, "epic 1 by 2"), item(3, "epic 1 by 1"), item(5, "epic 1 by 2")], {"billing-api": VOIDED}), [3, 1, 2, 5])
def test_a_formula_that_cannot_be_read_fails(self) -> None:
self.assertIsInstance(order([item(1, "epic 1 by 9")], {"billing-api": VOIDED}, "V +"), Failure)
if __name__ == "__main__":
unittest.main()
+5 -4
View File
@@ -1,9 +1,10 @@
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS
from claude_code.entries import Entry
from loop_claude import escalation_mark
from agent_cycle import escalation_mark
from failure import Failure
from loop_claude.cycle.judge import Grounds, JUDGE_RULES, TASK_HEADING, TRANSCRIPT_HEADING
from agent_cycle.judge import Grounds, judge_rules, TASK_HEADING, TRANSCRIPT_HEADING
from claude_code.transcript import human_answers
from loop_claude.cycle.prompts import typed_answer
from agent_cycle.worker_prompts import typed_answer
def grounds_of(prompt: str, entries: list[Entry]) -> Grounds | Failure:
@@ -12,4 +13,4 @@ def grounds_of(prompt: str, entries: list[Entry]) -> Grounds | Failure:
_, transcript_heading, shown = after_task.partition(TRANSCRIPT_HEADING)
if not (task_heading and transcript_heading):
return Failure(f"the archived prompt lacks the heading {TASK_HEADING.strip()!r} or {TRANSCRIPT_HEADING.strip()!r}, which judge_prompt writes")
return Grounds(shown.removesuffix(f"\n\n{JUDGE_RULES}"), escalation_mark.after_mark(entries, 0), before_task, tuple(human_answers(entries, typed_answer)))
return Grounds(shown.removesuffix(f"\n\n{judge_rules(ANSWER_DESTINATIONS)}"), escalation_mark.after_mark(entries, 0), before_task, tuple(human_answers(entries, typed_answer)))
+5 -4
View File
@@ -23,7 +23,7 @@ it, missed none.
Record each run in docs/decisions.md → `routing: on a model judge-replay covered`. Where the
model's cheapest rung misses no interrupt, the run is the evidence to add the model to
JUDGE_REPLAYED in bin/loop_claude/routing.py, which routes that model's judge. judge_rung there
JUDGE_REPLAYED in bin/agent_cycle/routing.py, which routes that model's judge. judge_rung there
keeps the judge to its own model's rungs; a rung above them that misses no interrupt is the
evidence to let the judge climb onto it.
@@ -53,11 +53,12 @@ import pathlib
import sys
import typing
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS
from transcript_archive.location import archive_root, transcript_of
from transcript_archive.read import archived_outcomes
from rung_replay.archive import archiving, print_report, replay_folder
from rung_replay.command import arguments_or_exit, down_from, failed, limited_exit, projects_on
from loop_claude.cycle.judge import Brief, judge_archived, judge_once
from agent_cycle.judge import Brief, judge_archived, judge_once
from judge_replay.replay import Case, case_from, Kind, report, reproduced, sample, verdict_kind
from transcript_archive.project_key import checkout_of
from loop_effects.effects import Effects
@@ -72,7 +73,7 @@ from model_routing.ladder_file import read_ladder, SHIPPED
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from claude_code.transcript import read_transcript
from loop_claude.verdicts import Verdict
from agent_cycle.verdicts import Verdict
TOOL = "judge-replay"
USAGE = f"{TOOL} <model> [--offline]; <model> is a model on the routing ladder"
@@ -171,5 +172,5 @@ def rule(case: Case, rung: Rung, home: pathlib.Path, effects: Effects) -> Kind |
if isinstance(records, Failure):
return verdict_kind(records)
# 0 for the route's mark, as before any step-up: the replay compares verdict kinds, and a mark changes only which escalation quotes count.
verdict = first_reply(lambda: judge_once(case.root, Brief(case.task, premises, records, entries, 0), rung, effects))
verdict = first_reply(lambda: judge_once(case.root, Brief(task=case.task, premises=premises, records=records, answer_destinations=ANSWER_DESTINATIONS, entries=entries, escalated_at=0), rung, effects))
return verdict if isinstance(verdict, Limited) else verdict_kind(verdict)
+1 -1
View File
@@ -6,7 +6,7 @@ import typing
from transcript_archive.outcomes import ANSWERED, FINISHED, first_verdict, INTERRUPTED, judge_run_at, task_of, UNFINISHED
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from rung_replay.search import Replay
from model_routing.ladder import Rung
+6 -4
View File
@@ -9,6 +9,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from loop_claude.cycle.prompts import ANSWER_DESTINATIONS
from transcript_archive.outcomes import ANSWERED, FINISHED, INTERRUPTED, UNFINISHED
from claude_code.entries import AssistantTurn, HumanTurn, LoopPrompt, Text
from judge_replay.replay import Case, case_from, report, reproduced, sample, verdict_kind
@@ -16,9 +17,9 @@ from text_files import compressed
from project_config.test_project_config import configured
from loop_effects.effects import Effects
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
from judge_replay.archived_prompt import grounds_of
from loop_claude.cycle.judge import judge_archived, JUDGE_RULES, Rejected, TASK_HEADING, TRANSCRIPT_HEADING
from agent_cycle.judge import judge_archived, judge_rules, Rejected, TASK_HEADING, TRANSCRIPT_HEADING
from judge_replay import main
from rung_replay.search import Miss, Replay, Tried
from model_routing.ladder import Rung
@@ -158,6 +159,7 @@ class Main(unittest.TestCase):
code, out, err = self.run_main(["claude-opus-5-5"], reply)
self.assertEqual(code, 0, err)
self.assertEqual([prompt for prompt in self.prompts if f"writing it into {ANSWER_DESTINATIONS}," not in prompt], [])
self.assertEqual({cwd for _, _, cwd in self.calls}, {str(self.home / "code" / "proj")})
self.assertEqual([(model, effort) for model, effort, _ in self.calls[::2]], [
("claude-opus-5-5", "xhigh"),
@@ -328,7 +330,7 @@ class Main(unittest.TestCase):
class JudgeArchivedRuns(unittest.TestCase):
"""judge_archived on a prompt as judge_prompt writes it: the premises, the task, the transcript the judge was shown, and the rules."""
PROMPT = f"HEAD: Ship fast.\n\n{TASK_HEADING}Do it.\n\n{TRANSCRIPT_HEADING}Worker chose option B.\n[human] Use Postgres.\n\n{JUDGE_RULES}"
PROMPT = f"HEAD: Ship fast.\n\n{TASK_HEADING}Do it.\n\n{TRANSCRIPT_HEADING}Worker chose option B.\n[human] Use Postgres.\n\n{judge_rules(ANSWER_DESTINATIONS)}"
ENTRIES = [AssistantTurn(parts=(Text("Worker chose option B."),)), HumanTurn(text="Use Postgres."), LoopPrompt(text="Keep going.")]
def judged(self, prompt=PROMPT, **fields):
@@ -361,7 +363,7 @@ class JudgeArchivedRuns(unittest.TestCase):
self.assertEqual((type(rejected), rejected.cost), (Rejected, 0.25))
def test_checks_neither_the_task_nor_the_rules_as_the_transcript_or_the_premises(self):
self.assertIsInstance(self.judged(evidence=JUDGE_RULES)[0], Rejected)
self.assertIsInstance(self.judged(evidence=judge_rules(ANSWER_DESTINATIONS))[0], Rejected)
self.assertIsInstance(self.judged(answer="Do it.", question="Which?")[0], Interrupt)
def test_splits_the_prompt_at_the_first_transcript_heading(self):
+1 -1
View File
@@ -1,4 +1,4 @@
"""loop-claude: headless claude cycles, judged, that interrupt the human only for a decision that is theirs (loop/usage.py's help).
Its packages hold one concern each: cycle/ runs a cycle, loop/ runs the cycles, and project/ reads a checkout's files. Its paths live in bin/loop_state/, and its effects in bin/loop_effects/. Each module at this level is imported by more than one package, or by a module at this level that is. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
Its packages hold one concern each: cycle/ words the worker's prompts and reads the items it names, loop/ runs the cycles, and project/ reads a checkout's files. loop-claude's paths live in bin/loop_state/, and its effects in bin/loop_effects/. The cycle itself, its judge, interrupts and routing live in bin/agent_cycle/, which doesn't import this package, so that a second entry point can drive it. routed_item.py, at this level, reads the plan for the item a chunk starts on.
"""
+2 -2
View File
@@ -3,9 +3,9 @@ import re
from claude_code.entries import AssistantTurn, Entry, Text
from failure import Failure
from loop_claude.quotes import plain
from agent_cycle.quotes import plain
from plan_store.plans import Plan
from loop_claude.verdicts import TakenIn
from agent_cycle.verdicts import TakenIn
# The label opening the line; prompts.NAME_THE_ITEMS asks the worker for it.
CHUNK_ITEMS = "Chunk items:"
+4 -34
View File
@@ -1,19 +1,19 @@
"""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 agent_cycle.worker_prompts import answers_recorded, WorkerPrompts
from model_routing.review_choice import chosen, ReviewChoice
from loop_claude.cycle.chunk_items import CHUNK_ITEMS
from model_routing.route import ESCALATION_MARKER, Route
from loop_claude.routing import escalation_rungs
from agent_cycle.routing import escalation_rungs
from loop_claude.project.records import HUMAN_RULE_NAMES, RECORD_FILES
from review_rules.review_passes import INSTRUCTION_FILES, INSTRUCTION_FOLDERS
from text_files.markdown_text import listed, quoted
from model_routing.ladder import ProjectRung, Rung
from claude_code.transcript import Typed
# Where the judge may quote an answer from, named as the human and the worker see them; of the goals file the judge sees only the premises.
QUOTE_SOURCES = listed(("the goals file's Goals and Audience", *RECORD_FILES, *HUMAN_RULE_NAMES), "or")
# Where the worker may write an answer the human typed, so it counts as recorded.
ANSWER_DESTINATIONS = "the goals file's Goals or Audience, " + ", ".join(RECORD_FILES) + ", the plan 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"
ANSWERS_RECORDED = answers_recorded(ANSWER_DESTINATIONS)
# How review_launches names the reviews: "each reviewer" covers every pass with an agent.
EACH_REVIEWER = "each reviewer"
EACH_SEAT = "each comprehension seat"
@@ -180,34 +180,4 @@ def rungs_held(route: Route, project: ProjectRung | None) -> str:
return "".join(f" {sentence}" for sentence in rung_sentences(route, project))
def answered(question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""stepped is whether the answer's ruling stepped the worker up."""
return f"Your question: {question}\n\n{QUOTE_SOURCES} answers it:\n\n{answer}\n\nContinue the task.{stepped_to(route, project, stepped)}"
def typed(question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The prompt that resumes the worker with the human's answer to an interrupt. answer is one line, as the terminal reads it."""
return f"{TYPED_HERE}\n{answer}\n\nYour question was: {question}\n\nContinue the task. The chunk is finished only once {ANSWERS_RECORDED}.{stepped_to(route, project, stepped)}"
# Opens typed's prompt, with the answer on the line after it, so typed_answer finds the answer at the prompt's start, whatever the question holds.
TYPED_HERE = "The human answered your question at loop-claude's terminal:"
def typed_answer(prompt: str) -> Typed | None:
"""Splits a prompt from typed() into its answer and the rest, so the judge reads the answer as the human's; None for any other prompt."""
opening = f"{TYPED_HERE}\n"
if not prompt.startswith(opening):
return None
answer, _, rest = prompt.removeprefix(opening).partition("\n\n")
return Typed(rest, answer)
def stepped_to(route: Route, project: ProjectRung | None, stepped: bool) -> str:
"""The sentences naming the worker's new rung, as resumed has them, where the ruling that brought the answer stepped the worker up; empty otherwise."""
return f" Your request for a higher rung went through: loop-claude runs you on {route.rung}. The escalation triggers that fired before this step are spent.{rungs_held(route, project)}" if stepped else ""
def past_the_cap(question: str, answer: str, cap: int) -> str:
"""The question a quoted answer puts to the human once the cycle's quoted answers reach the cap."""
return f"{question}\n\n{QUOTE_SOURCES} says:\n{answer}\n\nThose files have answered {cap} questions this cycle, the most allowed, so this one comes to you."
WORKER = WorkerPrompts(fresh, resumed, rungs_held, QUOTE_SOURCES, ANSWER_DESTINATIONS)
+2 -1
View File
@@ -6,7 +6,7 @@ from git_cli.git_repo import default_ref
from release_plan.release_standing import DefaultPlan, project_plan, UNSEEN_RELEASES
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.routing import first_route, kept, routed_item
from agent_cycle.routing import first_route, kept
from loop_claude.loop.chunk_windows import held_beside, item_of
from chunk_preflight.main import ITEM
from plan.todo_table import Item
@@ -17,6 +17,7 @@ from plan_store.plans import Plan
from model_routing.ladder import ProjectRung, Rung
from loop_claude.cycle import prompts
from model_routing.route import Route, route_from
from loop_claude.routed_item import routed_item
from claude_code.session import session_open, transcript_file
# Seconds routing waits for origin to name its default branch, asked only where the checkout records none; past them, the chunk runs on the project's rung.
+2 -2
View File
@@ -14,13 +14,13 @@ from failure import Failure
from project_config.main import located
from loop_claude.loop.reload import LoopRun
from release_plan.next_chunk import NextChunk, NoItem, planned
from touch_predictions.prediction import overlaps, predicted, Touches
from plan.touches import overlaps, predicted, Touches
from loop_state.paths import Paths
from transcript_archive.project_key import project_key
from release_plan.release_standing import project_plan
from claude_code.transcript import read_transcript
from claude_code.session import Session, session_named, transcript_file
from loop_claude import tmux
from agent_cycle import tmux
# Under the home folder, a folder per project key holds LOCK.
STATE = ".local/state/loop-claude"
+4 -4
View File
@@ -2,12 +2,12 @@
import dataclasses
import pathlib
from loop_claude.cycle.run import archived_step, archived_stop, Concluded
from loop_claude.verdicts import Finished
from agent_cycle.run import archived_step, archived_stop, Concluded
from agent_cycle.verdicts import Finished
from loop_claude.loop.this_loop import Loop
from loop_claude.loop.reload import LoopRun
from loop_claude.stop import needs_human, Stop
from loop_claude.routing import next_route, step_up
from agent_cycle.stop import needs_human, Stop
from agent_cycle.routing import next_route, step_up
from model_routing.ladder import ProjectRung
from claude_code.session import transcript_file
+9 -7
View File
@@ -7,25 +7,26 @@ from loop_claude.loop.chunk_start import archived_route, chunk_start, plan_item,
from loop_claude.loop.routing_check import check_routing
from loop_claude.project.checkout import checkout_root
from loop_claude.loop.chunk_windows import CHUNK_FLAG, chunk_session, item_of, start_chunks
from loop_claude.cycle import chunk_items, prompts
from loop_claude.loop.close import closed_cycle
from loop_claude.cycle.run import Cycle, run_cycle
from agent_cycle.run import Cycle, run_cycle
from loop_claude.loop.reload import decode_handed, exec_if_edited, fingerprint, LoopRun, RELOAD_FLAG
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.verdicts import Finished
from agent_cycle.verdicts import Finished
from loop_claude.project.model_choice import get_or_ask_models
from git_cli.git_repo import Git
from loop_claude.loop.usage import HELP
from loop_claude.routing import judge_rung
from agent_cycle.routing import judge_rung
from loop_claude.loop.this_loop import Loop
from loop_state.paths import Paths
from transcript_archive.project_key import project_key
from model_routing.ladder_file import project_ladder_file, read_ladder, SHIPPED
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from loop_claude.stop import Stop
from loop_claude.direct_message import tell
from loop_claude import tmux
from agent_cycle.stop import Stop
from agent_cycle.direct_message import tell
from agent_cycle import tmux
def main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, cwd: pathlib.Path, effects: Effects) -> int:
@@ -129,7 +130,8 @@ def next_cycle(loop_run: LoopRun, loop: Loop) -> Cycle | Stop:
say(f"\n=== cycle {loop_run.cycle_number}, worker on {route.rung} ===", loop.effects, stdout=True)
if ladder_file != SHIPPED:
say(own_ladder(ladder_file, models.worker, project is None), loop.effects)
return Cycle(config=setup_version(loop.paths.claude_dir, loop.effects.git), effects=loop.effects, facts=facts, judge=judge_rung(ladder, models.judge), premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=loop_run.task, plan=scored_plan(default, loop.effects), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
plan = scored_plan(default, loop.effects)
return Cycle(config=setup_version(loop.paths.claude_dir, loop.effects.git), effects=loop.effects, facts=facts, judge=judge_rung(ladder, models.judge), premises=premises, project=project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=loop_run.task, prompts=prompts.WORKER, taken_in=lambda entries: chunk_items.taken_in(entries, plan), unfinished_evidence=loop_run.unfinished_evidence, window=loop.window)
def own_ladder(file: pathlib.Path, model: str, unrouted: bool) -> str:
+1 -1
View File
@@ -8,7 +8,7 @@ import typing
from loop_claude.loop.this_loop import Loop
from model_routing.route import Route, route_of
from loop_effects.effects import say
from loop_claude.stop import Stop
from agent_cycle.stop import Stop
RELOAD_FLAG = "--reloaded"
+3 -3
View File
@@ -3,7 +3,7 @@ import pathlib
from routing_figures import archive
from routing_figures.calls import Call, calls, totals
from loop_claude.hand_over import claude_args, ClaudeCommand, hand_over
from agent_cycle.hand_over import claude_args, ClaudeCommand, hand_over
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.loop.this_loop import Loop
@@ -12,8 +12,8 @@ from model_routing.ladder_file import read_ladder, SHIPPED
from routing_figures.render import render
from model_routing.ladder import Rung
from routing_figures import state
from loop_claude.stop import Stop
from loop_claude.direct_message import tell
from agent_cycle.stop import Stop
from agent_cycle.direct_message import tell
from text_files.utc_stamp import utc
+1 -1
View File
@@ -5,7 +5,7 @@ import typing
from loop_effects.effects import Effects
from loop_state.paths import Paths
from claude_code.session import Session
from loop_claude.tmux import Window
from agent_cycle.tmux import Window
@dataclasses.dataclass(frozen=True)
+8 -8
View File
@@ -49,7 +49,7 @@ claude session is named "A <key> loop-claude <window>", so a rerun resumes a chu
deleted when the chunk finishes. A fresh worker is told the items the project's other chunks hold,
running or stopped: each one's own and those on its latest `Chunk items:` line, and leaves them out.
A question only the human can answer is an interrupt (bin/loop_claude/cycle/interrupt.py).
A question only the human can answer is an interrupt (bin/agent_cycle/interrupt.py).
loop-claude prints the question in the chunk's window and rings its bell. Until it is answered the
window's name ends in " ?", as in "item-372 ?", which tmux's status bar shows. The human answers it
there:
@@ -82,7 +82,7 @@ Before each worker starts, loop-claude waits until at least a quarter of the mac
available (bin/machine_load/memory.py).
Each worker's claude, the session /talk opens and the subagents either launches run with a 200k
auto-compact window (CLAUDE_CODE_AUTO_COMPACT_WINDOW, bin/loop_claude/cycle/worker.py), so each
auto-compact window (CLAUDE_CODE_AUTO_COMPACT_WINDOW, bin/agent_cycle/worker.py), so each
compacts its context at about 170k tokens. They also save a Bash result of more than 6,000
characters to a file and see its path and the first 2,000 characters (BASH_MAX_OUTPUT_LENGTH,
bin/claude_code/output_limits.py).
@@ -101,13 +101,13 @@ models on another; a chunk no item routes runs on the project's model. The worke
rungs it launches its reviews on. The worker's rung steps up as a chunk stays unfinished, when the
worker names on its `Chunk items:` line an item that picks a higher rung, 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, the choice of
rules are in bin/agent_cycle/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 as JSON (Route.worker_line in
bin/model_routing/route.py); a rerun resumes an open chunk on the latest route named there. A
plan or an archive that cannot be read or parsed is said on stderr, and the chunk is routed
without it.
bin/loop_claude/cycle/prompts.py and bin/agent_cycle/worker_prompts.py. Each verdict, interrupt,
quoted answer, stop and step-up in the archive ends with a Worker: line, the route as JSON
(Route.worker_line in bin/model_routing/route.py); a rerun resumes an open chunk on the latest
route named there. A plan or an archive that cannot be read or parsed is said on stderr, and the
chunk is routed without it.
The ladder is a JSON file, each rung a model's full name and an effort of low, medium, high, xhigh
or max:
+1 -1
View File
@@ -3,7 +3,7 @@ import pathlib
from failure import Failure
from loop_effects.effects import Effects
from loop_claude.stop import Stop
from agent_cycle.stop import Stop
def checkout_root(cwd: pathlib.Path, effects: Effects) -> str | Stop:
+1 -1
View File
@@ -7,7 +7,7 @@ import typing
from claude_code.model_catalog import catalog_models
from loop_effects.effects import Effects, say
from failure import Failure
from loop_claude.stop import needs_human, needs_terminal, Stop
from agent_cycle.stop import needs_human, needs_terminal, Stop
from loop_state.paths import Paths
from text_files.file_writes import replace_json
+19
View File
@@ -0,0 +1,19 @@
"""The plan item that routes a fresh chunk of loop-claude's: agent_cycle/routing.py's first_route picks the worker's rung from its L."""
from release_plan.release_standing import chunk_item, LastCut, Next
from failure import Failure
from plan.todo_table import Item, NoItemsTable
from plan_store.plans import Plan
def routed_item(plan: Plan | Failure, cut: LastCut, item_id: int | None = None) -> Item | Failure | None:
"""The plan's item item_id, or without one the item release_standing.chunk_item picks from plan, weighed against the last cut; None when there is none, or it lacks L, E or I."""
if isinstance(plan, NoItemsTable):
return None
if isinstance(plan, Failure):
return plan
if item_id is None:
pick = chunk_item(plan.items, cut)
takes = pick.item if isinstance(pick, Next) else None
else:
takes = next((item for item in plan.items if item.id == item_id), None)
return takes if takes and takes.likelihood and takes.escape_and_impact else None
+75 -61
View File
@@ -11,6 +11,7 @@ import stat
import subprocess
import sys
import tempfile
import types
import unittest
import unittest.mock
import uuid
@@ -28,10 +29,11 @@ from release_plan.release_standing import DefaultPlan, LastCut, UNSEEN_RELEASES
from loop_effects.effects import Effects, PYTHON_TIMEOUT
from claude_code import entries, reply, session
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished
from agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished
from git_cli.git_repo import git
from loop_claude.cycle import interrupt, judge, prompts, retry, run, spend, states, worker
from agent_cycle import interrupt, judge, retry, run, spend, states, worker, worker_prompts
from claude_code.reply import Limited
import loop_claude.routed_item
from loop_claude.loop import main, reload, routing_check, this_loop, usage
from machine_load import memory
from release_plan import next_chunk
@@ -40,15 +42,16 @@ from loop_state import paths
from plan_store.todo_md import plan_of
from transcript_archive.location import project_archive
from model_routing.ladder import ProjectRung, Rung
from loop_claude.cycle import prompts
from model_routing.ladder_file import read_ladder, SHIPPED
from model_routing.route import Route, route_from, WorkerLine
from loop_claude import routing
from loop_claude.stop import Stop
from loop_claude import tmux
from agent_cycle import routing
from agent_cycle.stop import Stop
from agent_cycle import tmux
from claude_code.tokens import Tokens, tokens_of
from touch_predictions.test_touch_predictions import plan as touch_plan
from text_files.utc_stamp import utc
from loop_claude.cycle.judge import verdict_from
from agent_cycle.judge import verdict_from
# How the archive records a worker that runs off the ladder.
LADDER = read_ladder(SHIPPED)
@@ -277,8 +280,9 @@ class Transitions(unittest.TestCase):
class QuestionFor(unittest.TestCase):
def test_puts_an_interrupts_question_as_asked_and_a_quoted_answer_past_the_cap_with_its_quote(self):
self.assertEqual(run.question_for(Interrupt("e", "Which one?")), "Which one?")
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
cycle = types.SimpleNamespace(prompts=prompts.WORKER)
self.assertEqual(run.question_for(cycle, Interrupt("e", "Which one?")), "Which one?")
self.assertEqual(run.question_for(cycle, QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
class Cycles(unittest.TestCase):
@@ -291,7 +295,7 @@ class Cycles(unittest.TestCase):
self.archive = project_archive(str(self.home / "code" / "proj"), self.home, {})
def cycle(self, fake, records="", unfinished_evidence="", facts="- A preflight fact."):
return run.Cycle(config=CONFIG, window=WINDOW, effects=fake.effects(), facts=facts, judge=Rung("judge-model"), premises="## Goals", project=None, project_archive=self.archive, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, task="Do it.", plan=plan_of(""), unfinished_evidence=unfinished_evidence)
return run.Cycle(config=CONFIG, window=WINDOW, effects=fake.effects(), facts=facts, judge=Rung("judge-model"), premises="## Goals", project=None, project_archive=self.archive, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, task="Do it.", prompts=prompts.WORKER, taken_in=lambda entries: chunk_items.taken_in(entries, plan_of("")), unfinished_evidence=unfinished_evidence)
def archived_outcomes(self):
"""Each outcomes file's text without its `Judge run:` lines, which name a file by the hash of a prompt and its reply: the tests of the judge's runs check them."""
@@ -539,6 +543,7 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
self.assertNotIn("the second", judge_prompts[0])
self.assertIn("[human] the second", judge_prompts[1])
self.assertIn("From the goals file, ## Goals", judge_prompts[0])
self.assertIn(f"writing it into {prompts.ANSWER_DESTINATIONS},", judge_prompts[0])
self.assertIn("The task the worker was given:\nDo it.", judge_prompts[0])
def test_a_question_the_records_answer_resumes_the_worker_with_the_answer_three_times_a_cycle(self):
@@ -619,7 +624,7 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
resumed = fake.made("stream_claude")[1]
self.assertEqual(resumed[resumed.index("--resume") + 1], str(self.session.id))
typed = resumed[resumed.index("-p") + 1]
self.assertEqual(prompts.typed_answer(typed).answer, "Use B.")
self.assertEqual(worker_prompts.typed_answer(typed).answer, "Use B.")
self.assertIn("Which one?", typed)
self.assertIn("Continue the task. The chunk is finished only once every answer the human typed in it", typed)
judge_prompts = [stdin for args, stdin in fake.made("claude")]
@@ -1007,8 +1012,8 @@ class ModelPrompt(unittest.TestCase):
# A plan read with no release cut yet.
NO_CUT = LastCut(None, "", 0, [])
def routed_item(todo, cut):
"""routing.routed_item for the plan a todo.md's text holds."""
return routing.routed_item(plan_of(todo), cut)
"""loop_claude.routed_item.routed_item for the plan a todo.md's text holds."""
return loop_claude.routed_item.routed_item(plan_of(todo), cut)
TODO = """# todo
@@ -1710,13 +1715,13 @@ class TypedAnswers(unittest.TestCase):
def test_splits_the_prompt_handing_over_the_answer_into_the_answer_on_the_line_after_its_marker_and_the_rest_and_no_other_prompt(self):
route = Route(Rung("worker-model"))
marked = "The human answered your question at loop-claude's terminal:\nB"
typed = prompts.typed_answer(prompts.typed("Which one?", "Use B.", route, None, False))
typed = worker_prompts.typed_answer(prompts.WORKER.typed("Which one?", "Use B.", route, None, False))
self.assertEqual(typed.answer, "Use B.")
self.assertTrue(typed.loop_words.startswith("Your question was: Which one?\n\nContinue the task."))
self.assertEqual(prompts.typed_answer(prompts.typed(f"Which one?\n{marked}", "Use B.", route, None, False)).answer, "Use B.")
self.assertEqual(prompts.typed_answer(prompts.typed("Which one?", "Use B.", Route(Routing.SONNET, 179, 2, 5), OPUS_PROJECT, True)).answer, "Use B.")
self.assertIsNone(prompts.typed_answer(prompts.answered("Which one?", marked, route, None, False)))
self.assertIsNone(prompts.typed_answer(prompts.resumed(marked, route, None)))
self.assertEqual(worker_prompts.typed_answer(prompts.WORKER.typed(f"Which one?\n{marked}", "Use B.", route, None, False)).answer, "Use B.")
self.assertEqual(worker_prompts.typed_answer(prompts.WORKER.typed("Which one?", "Use B.", Route(Routing.SONNET, 179, 2, 5), OPUS_PROJECT, True)).answer, "Use B.")
self.assertIsNone(worker_prompts.typed_answer(prompts.WORKER.answered("Which one?", marked, route, None, False)))
self.assertIsNone(worker_prompts.typed_answer(prompts.resumed(marked, route, None)))
class WorkerArgs(unittest.TestCase):
@@ -1918,7 +1923,7 @@ class Records(unittest.TestCase):
class JudgePrompt(unittest.TestCase):
def test_shows_the_transcripts_tail_and_returns_what_it_showed(self):
entries = [assistant({"type": "text", "text": "old " + "x" * judge.JUDGE_PROMPT_CHARS}), assistant({"type": "text", "text": "new"})]
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 0))
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 0))
self.assertTrue(grounds.shown.endswith("\n\nnew"))
self.assertNotIn("old", grounds.shown)
self.assertIn(grounds.shown, prompt)
@@ -1927,32 +1932,41 @@ class JudgePrompt(unittest.TestCase):
self.assertEqual(grounds.quotable, "## Goals\n\n")
def test_the_judge_prompt_and_schema_call_the_worker_the_worker(self):
prompt, _ = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(assistant({"type": "text", "text": "done"})), 1))
prompt, _ = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(assistant({"type": "text", "text": "done"})), 1))
self.assertNotRegex(prompt + json.dumps(judge.JUDGE_SCHEMA), r"\b[Aa]gent")
def test_the_judge_prompt_names_the_entry_points_answer_destinations_in_both_rules_on_a_recorded_answer(self):
prompt, _ = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", "the ledger", kinds(assistant({"type": "text", "text": "done"})), 0))
self.assertIn("is recorded in the ledger at the one place it governs", prompt)
self.assertIn("the worker writing it into the ledger, but not into one of the human's rules", prompt)
def test_the_typed_answers_prompt_names_the_entry_points_answer_destinations(self):
ledger = dataclasses.replace(prompts.WORKER, answer_destinations="the ledger")
self.assertIn("is recorded in the ledger at the one place it governs.", ledger.typed("Which one?", "Use B.", Route(Rung("worker-model")), None, False))
def test_the_judge_prompt_names_every_rule_the_judge_reads_from_the_human(self):
self.assertEqual([name for name in records.HUMAN_RULE_NAMES if name not in judge.JUDGE_RULES], [])
self.assertEqual([name for name in records.HUMAN_RULE_NAMES if name not in judge.judge_rules(prompts.ANSWER_DESTINATIONS)], [])
def test_shows_the_judge_where_the_worker_last_stepped_up_and_checks_an_escalation_only_after_it(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "round 3: 🔴"})]
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1))
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1))
self.assertRegex(prompt, "round 2: 🔴\n\n\\[step\\] [^\n]+\n\nround 3: 🔴\n\n")
self.assertEqual(grounds.after_mark, "round 3: 🔴")
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 0))
prompt, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 0))
self.assertNotIn("stepped the worker up", prompt)
self.assertEqual(grounds.shown, "round 2: 🔴\n\nround 3: 🔴")
self.assertEqual(grounds.after_mark, "round 2: 🔴\n\nround 3: 🔴")
def test_drops_an_escalation_quote_from_after_the_step_up_that_the_tail_it_shows_cuts_off(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "old " + "x" * judge.JUDGE_PROMPT_CHARS}), assistant({"type": "text", "text": "new"})]
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1))
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1))
self.assertEqual(judge.quotes_checked(Unfinished("e", "old x", entries_read=3), grounds), Unfinished("e", entries_read=3))
self.assertEqual(judge.quotes_checked(Unfinished("e", "new", entries_read=3), grounds), Unfinished("e", "new", entries_read=3))
def test_shows_a_typed_answer_before_the_step_up_as_the_humans(self):
typed = prompts.typed("Which one?", "Use B.", Route(Rung("worker-model")), None, False)
typed = prompts.WORKER.typed("Which one?", "Use B.", Route(Rung("worker-model")), None, False)
entries = [{**human(typed), "promptSource": "sdk"}, assistant({"type": "text", "text": "round 3: 🔴"})]
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1))
_, grounds = judge.judge_prompt(judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1))
self.assertIn("\n\n[human] Use B.\n\n[step] ", grounds.shown)
@@ -2179,7 +2193,7 @@ class Verdict(unittest.TestCase):
def test_drops_an_escalation_quote_found_only_in_the_transcript_entries_before_the_workers_last_step_up(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "round 3: 🔴"}), assistant({"type": "text", "text": "working"})]
def judged_on(mark, escalation):
return judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", kinds(*entries), mark), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation=escalation)]).effects())
return judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), mark), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation=escalation)]).effects())
self.assertEqual(judged_on(0, "round 2: 🔴"), Unfinished("working", "round 2: 🔴", entries_read=3))
self.assertEqual(judged_on(1, "round 2: 🔴"), Unfinished("working", entries_read=3))
self.assertEqual(judged_on(1, "round 3: 🔴"), Unfinished("working", "round 3: 🔴", entries_read=3))
@@ -2188,12 +2202,12 @@ class Verdict(unittest.TestCase):
def test_drops_an_escalation_quote_that_only_loop_claudes_prompts_or_the_humans_lines_repeat_after_the_step_up(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), {**human("as the work remaining: round 2: 🔴"), "promptSource": "sdk"}, human("round 2: 🔴 again"), assistant({"type": "text", "text": "working"})]
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation="round 2: 🔴")]).effects())
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation="round 2: 🔴")]).effects())
self.assertEqual(verdict, Unfinished("working", entries_read=4))
def test_takes_evidence_from_before_the_workers_last_step_up(self):
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "working"})]
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence="round 2: 🔴")]).effects())
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", prompts.ANSWER_DESTINATIONS, kinds(*entries), 1), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence="round 2: 🔴")]).effects())
self.assertEqual(verdict, Unfinished("round 2: 🔴", entries_read=2))
@@ -2462,41 +2476,41 @@ class ExitContract(unittest.TestCase):
unreadable = f"the goals file, or {', '.join(names[:-1])} or {names[-1]} where they exist, cannot be read or is not UTF-8"
# Every Stop whose code is not a literal 0, 2 or 130, in source order: path, function, code, start of reason, its --help clause.
clauses = [
("cycle/interrupt.py", "claude_open", "1", "f'could not start claude for the interrupt:", "claude cannot start for an interrupt"),
("cycle/interrupt.py", "human_typed", "1", "entries.reason", read),
("cycle/interrupt.py", "human_typed", "1", "f'could not tell whether you typed anything:", read),
("cycle/retry.py", "retried", "1", "f'the {who} failed three times running:", "the worker or the judge fails three times running"),
("cycle/run.py", "archived_stop", "1", "f'{failure.reason}", read),
("cycle/run.py", "work", "1", "f'claude left no transcript for session", "claude leaves no transcript"),
("cycle/run.py", "rule", "1", "entries.reason", read),
("cycle/run.py", "rule", "1", "annotation.reason", read),
("cycle/run.py", "rule", "1", "failure.reason", read),
("cycle/run.py", "keep_rejection", "1", "unkept.reason", read),
("cycle/run.py", "close", "1", "annotation.reason", read),
("cycle/run.py", "close", "1", "failure.reason", read),
("cycle/run.py", "close", "1", "failure.reason", "a finished chunk's session cannot be deleted"),
("loop/close.py", "closed_cycle", "1", "failure.reason", read),
("loop/main.py", "run_loop", "1", "reason", "tmux is missing or older than 3.2"),
("loop/main.py", "run_loop", "1", "f'{CHUNK_FLAG} is how loop-claude starts itself", "--chunk is given outside a tmux window"),
("loop/main.py", "windows_opened", "1", "started.reason", "a chunk's window cannot be started"),
("loop/main.py", "windows_opened", "1", "f\"`tmux {' '.join(shown)}` failed", "the tmux session cannot be put on the terminal"),
("loop/main.py", "handed_on", "1", "f'the chunk finished, but the next could not start", "a chunk's window cannot be started"),
("loop/main.py", "next_cycle", "1", "premises.reason", premises_),
("loop/main.py", "next_cycle", "1", "records.reason", unreadable),
("loop/main.py", "next_cycle", "1", "ladder_file.reason", premises_),
("loop/main.py", "next_cycle", "1", "ladder.reason", "the project's routing ladder cannot be read or holds a fault"),
("loop/main.py", "loop_run_from", "0 if task else 1", "HELP", "no task is given"),
("loop/main.py", "loop_run_from", "1", 'f"the edited loop-claude cannot read the state', "a reload cannot read the state the running script handed it"),
("loop/reload.py", "exec_if_edited", "1", "f'could not reload loop-claude:", "python cannot start for a reload"),
("loop/routing_check.py", "raise_calls", "1", "f\"could not start claude for the routing calls in {loop.paths.config_clone}", "claude cannot start for an interrupt"),
("project/checkout.py", "checkout_root", "1", "found.reason", git),
("project/model_choice.py", "get_or_ask_model", "1", "models.reason", models_),
("project/model_choice.py", "get_or_ask_model", "1", "models.reason", models_),
("project/model_choice.py", "get_or_ask_model", "1", "f'could not save the model in", models_),
("agent_cycle/interrupt.py", "claude_open", "1", "f'could not start claude for the interrupt:", "claude cannot start for an interrupt"),
("agent_cycle/interrupt.py", "human_typed", "1", "entries.reason", read),
("agent_cycle/interrupt.py", "human_typed", "1", "f'could not tell whether you typed anything:", read),
("agent_cycle/retry.py", "retried", "1", "f'the {who} failed three times running:", "the worker or the judge fails three times running"),
("agent_cycle/run.py", "archived_stop", "1", "f'{failure.reason}", read),
("agent_cycle/run.py", "work", "1", "f'claude left no transcript for session", "claude leaves no transcript"),
("agent_cycle/run.py", "rule", "1", "entries.reason", read),
("agent_cycle/run.py", "rule", "1", "annotation.reason", read),
("agent_cycle/run.py", "rule", "1", "failure.reason", read),
("agent_cycle/run.py", "keep_rejection", "1", "unkept.reason", read),
("agent_cycle/run.py", "close", "1", "annotation.reason", read),
("agent_cycle/run.py", "close", "1", "failure.reason", read),
("agent_cycle/run.py", "close", "1", "failure.reason", "a finished chunk's session cannot be deleted"),
("loop_claude/loop/close.py", "closed_cycle", "1", "failure.reason", read),
("loop_claude/loop/main.py", "run_loop", "1", "reason", "tmux is missing or older than 3.2"),
("loop_claude/loop/main.py", "run_loop", "1", "f'{CHUNK_FLAG} is how loop-claude starts itself", "--chunk is given outside a tmux window"),
("loop_claude/loop/main.py", "windows_opened", "1", "started.reason", "a chunk's window cannot be started"),
("loop_claude/loop/main.py", "windows_opened", "1", "f\"`tmux {' '.join(shown)}` failed", "the tmux session cannot be put on the terminal"),
("loop_claude/loop/main.py", "handed_on", "1", "f'the chunk finished, but the next could not start", "a chunk's window cannot be started"),
("loop_claude/loop/main.py", "next_cycle", "1", "premises.reason", premises_),
("loop_claude/loop/main.py", "next_cycle", "1", "records.reason", unreadable),
("loop_claude/loop/main.py", "next_cycle", "1", "ladder_file.reason", premises_),
("loop_claude/loop/main.py", "next_cycle", "1", "ladder.reason", "the project's routing ladder cannot be read or holds a fault"),
("loop_claude/loop/main.py", "loop_run_from", "0 if task else 1", "HELP", "no task is given"),
("loop_claude/loop/main.py", "loop_run_from", "1", 'f"the edited loop-claude cannot read the state', "a reload cannot read the state the running script handed it"),
("loop_claude/loop/reload.py", "exec_if_edited", "1", "f'could not reload loop-claude:", "python cannot start for a reload"),
("loop_claude/loop/routing_check.py", "raise_calls", "1", "f\"could not start claude for the routing calls in {loop.paths.config_clone}", "claude cannot start for an interrupt"),
("loop_claude/project/checkout.py", "checkout_root", "1", "found.reason", git),
("loop_claude/project/model_choice.py", "get_or_ask_model", "1", "models.reason", models_),
("loop_claude/project/model_choice.py", "get_or_ask_model", "1", "models.reason", models_),
("loop_claude/project/model_choice.py", "get_or_ask_model", "1", "f'could not save the model in", models_),
]
root = pathlib.Path(main.__file__).parents[1]
root = pathlib.Path(main.__file__).parents[2]
found = []
for path in sorted(path for path in root.rglob("*.py") if not path.name.startswith("test_")):
for path in sorted(path for package in ("agent_cycle", "loop_claude") for path in (root / package).rglob("*.py") if not path.name.startswith("test_")):
functions = [node for node in ast.walk(ast.parse(path.read_text())) if isinstance(node, ast.FunctionDef)]
stops = [(call.lineno, function.name, ast.unparse(call.args[0]), ast.unparse(call.args[1])) for function in functions for call in ast.walk(function) if isinstance(call, ast.Call) and getattr(call.func, "id", None) == "Stop" and not (isinstance(call.args[0], ast.Constant) and call.args[0].value in (0, 2, 130))]
found += [(str(path.relative_to(root)), function, code, reason) for _, function, code, reason in sorted(stops)]
+1 -1
View File
@@ -52,7 +52,7 @@ class Route:
unfinished: int = 0
# The highest E + I among the items the worker names on its `Chunk items:` line, kept only where it picks a higher review step than the item's; 0 otherwise.
escape_and_impact_taken_in: int = 0
# 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.
# The escalation mark, as agent_cycle/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:
+167
View File
@@ -0,0 +1,167 @@
import pathlib
import shutil
import subprocess
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from adf_codec import convert
from failure import Failure
from plan.touches import overlaps, Part, predicted, rendered, together
DETAIL = """A planning call.
Touches:
- `bin/a.py`: `main`, `Plan.branch` (small)
- `README.md`: `## Goals, and (more): things`
- `bin/run.sh`: lines 10-20
- `docs/new.md`
More prose, with `bin/b.py` named.
"""
needs_docker = unittest.skipIf(shutil.which("docker") is None or subprocess.run(["docker", "info"], capture_output=True, timeout=20).returncode != 0, "adf_codec runs in a container, which needs a docker daemon")
def text(words: str, code: bool = False) -> dict:
return {"type": "text", "text": words, **({"marks": [{"type": "code"}]} if code else {})}
def bullet_of(*spans: dict) -> dict:
return {"type": "listItem", "attrs": {"localId": "i"}, "content": [{"type": "paragraph", "attrs": {"localId": "p"}, "content": list(spans)}]}
# A Touches list as someone types it in Jira's editor: a paragraph, then a bulleted list whose paths and names carry the code mark.
JIRA_TOUCHES = {"type": "doc", "version": 1, "content": [
{"type": "paragraph", "attrs": {"localId": "a"}, "content": [text("A planning call.")]},
{"type": "paragraph", "attrs": {"localId": "b"}, "content": [text("Touches:")]},
{"type": "bulletList", "attrs": {"localId": "c"}, "content": [
bullet_of(text("bin/a.py", True), text(": "), text("main", True), text(", "), text("Plan.branch", True), text(" (small)")),
bullet_of(text("a`b.md", True), text(": "), text("## The `foo` tool", True), text(" (small)"), text(", "), text("`x`", True)),
bullet_of(text("bin/run.sh", True), text(": lines 10-20")),
bullet_of(text("docs/new.md", True)),
]},
{"type": "paragraph", "attrs": {"localId": "d"}, "content": [text("More prose.")]},
]}
class PredictedTest(unittest.TestCase):
def test_reads_each_bullet_of_the_touches_list(self) -> None:
self.assertEqual(predicted(DETAIL), {
"bin/a.py": (Part("main"), Part("Plan.branch", small=True)),
"README.md": (Part("## Goals, and (more): things"),),
"bin/run.sh": (Part("lines 10-20"),),
"docs/new.md": (),
})
def test_a_detail_without_the_list_predicts_nothing(self) -> None:
self.assertIsNone(predicted("Only prose, with `bin/a.py` named."))
def test_a_bullet_it_cannot_read_is_a_failure_that_quotes_it(self) -> None:
for bullet in ("- bin/a.py: main", "- `bin/a.py`: main", "- `bin/a.py`: lines 20-10", "- `bin/a.py`: `main` `other`"):
with self.subTest(bullet):
found = predicted(f"Touches:\n\n{bullet}\n")
assert isinstance(found, Failure)
self.assertIn(bullet, found.reason)
def test_an_empty_list_is_a_failure(self) -> None:
self.assertIsInstance(predicted("Touches:\n\nProse.\n"), Failure)
found = predicted("Touches:\n")
assert isinstance(found, Failure)
self.assertEqual(found.reason, "no bullet follows `Touches:`")
def test_reads_a_list_right_under_its_label_a_one_line_range_and_a_name_of_any_letters(self) -> None:
self.assertEqual(predicted("Touches:\n- `a.py`: `Xray`, lines 5-5\n"), {"a.py": (Part("Xray"), Part("lines 5-5"))})
def test_rendered_reads_back(self) -> None:
touches = predicted(DETAIL)
assert isinstance(touches, dict)
self.assertEqual(predicted(f"Touches:\n\n{rendered(touches)}\n"), touches)
def test_a_name_that_holds_backticks_takes_a_longer_run_with_a_space_inside_each_end(self) -> None:
self.assertEqual(predicted("Touches:\n- `a.md`: `` ## The `foo` tool `` (small), ``` `` ```, `` `x` ``\n"), {"a.md": (Part("## The `foo` tool", small=True), Part("``"), Part("`x`"))})
self.assertEqual(rendered({"a.md": (Part("## The `foo` tool", small=True), Part("``"))}), "- `a.md`: `` ## The `foo` tool `` (small), ``` `` ```")
def test_a_longer_run_without_padding_spaces_is_the_text_between_its_runs(self) -> None:
self.assertEqual(predicted("Touches:\n- ``a`b.md``: ``## The `foo` tool`` (small), ``` `` ```, `` `x` ``\n"), {"a`b.md": (Part("## The `foo` tool", small=True), Part("``"), Part("`x`"))})
def test_a_longer_run_with_a_space_at_one_end_only_keeps_it(self) -> None:
self.assertEqual(predicted("Touches:\n- `a.md`: `` x``, ``y ``, `` a ``\n"), {"a.md": (Part(" x"), Part("y "), Part("a"))})
@needs_docker
def test_a_list_written_in_markdown_and_read_back_from_a_jira_description_reads_as_written(self) -> None:
description = convert.markdown_to_adf(DETAIL)
assert isinstance(description, dict)
self.assertEqual(predicted(convert.adf_to_markdown(description)), predicted(DETAIL))
@needs_docker
def test_a_list_typed_in_jiras_editor_reads_as_its_files_and_parts(self) -> None:
read = convert.adf_to_markdown(JIRA_TOUCHES)
self.assertEqual(predicted(read), {
"bin/a.py": (Part("main"), Part("Plan.branch", small=True)),
"a`b.md": (Part("## The `foo` tool", small=True), Part("`x`")),
"bin/run.sh": (Part("lines 10-20"),),
"docs/new.md": (),
})
def test_a_name_ends_only_at_a_run_as_long_as_the_one_that_opens_it(self) -> None:
self.assertEqual(predicted("Touches:\n- `a.md`: `` a ``` b ``, `c``d`\n"), {"a.md": (Part("a ``` b"), Part("c``d"))})
def test_a_path_holds_any_character_and_a_single_backtick_keeps_a_names_spaces(self) -> None:
self.assertEqual(predicted("Touches:\n- `my file.md`: ` x `\n- `` a`b.md ``\n"), {"my file.md": (Part(" x "),), "a`b.md": ()})
def test_rendered_reads_back_whatever_a_path_or_a_name_holds(self) -> None:
touches = {"my file.md": (Part("## todo.md: under `Touches:` in its detail"), Part("## ``a`` and `b`", small=True), Part("`"), Part("## ends in `x`"), Part(" x "), Part("lines 2-3")), "a`b.md": (), "c, d: e.md": (Part("# T"),)}
self.assertEqual(predicted(f"Touches:\n\n{rendered(touches)}\n"), touches)
def test_a_bullet_with_an_unclosed_run_a_blank_name_or_a_stray_separator_is_a_failure(self) -> None:
for bullet in ("- `a.md`: `` ## A", "- `a.md`: `` ## A `", "- `a.md`: `` ``", "- `a.md`: ", "- `a.md`:", "- `a.md`: `f`, ", "- `a.md`: `f`,`g`", "- ``", "- `a.md` (small)", "- `a.md`: `f` (small) (small)"):
with self.subTest(bullet):
self.assertIsInstance(predicted(f"Touches:\n\n{bullet}\n"), Failure)
def test_a_range_that_runs_backwards_is_a_failure_that_says_so(self) -> None:
found = predicted("Touches:\n\n- `bin/a.py`: `f`, lines 20-10\n")
assert isinstance(found, Failure)
self.assertEqual(found.reason, "the bullet '- `bin/a.py`: `f`, lines 20-10' under `Touches:` holds a line range whose first line comes after its last")
def test_together_joins_items_and_keeps_small_only_where_each_says_so(self) -> None:
joined = together([{"a.py": (Part("f", small=True), Part("g", small=True))}, {"a.py": (Part("f"),), "b.md": ()}, {"b.md": (Part("# T"),)}])
self.assertEqual(joined, {"a.py": (Part("f"), Part("g", small=True)), "b.md": ()})
def test_together_keeps_a_part_not_small_once_one_says_so_and_reads_on_past_a_whole_file(self) -> None:
joined = together([{"a.py": (Part("f"),), "b.md": ()}, {"b.md": (Part("# T"),), "a.py": (Part("f", small=True),), "c.py": (Part("h"),)}])
self.assertEqual(joined, {"a.py": (Part("f"),), "b.md": (), "c.py": (Part("h"),)})
class OverlapsTest(unittest.TestCase):
def test_other_files_and_other_parts_do_not_overlap(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("f"),)}, {"a.py": (Part("g"),), "b.py": ()}), [])
def test_the_same_part_overlaps(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("f"), Part("g"))}, {"a.py": (Part("g"),)}), ["`a.py` `g`"])
def test_a_class_overlaps_its_method_but_not_a_name_it_only_starts(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("Plan"),)}, {"a.py": (Part("Plan.branch"), Part("Planned"))}), ["`a.py` `Plan`"])
def test_a_whole_file_overlaps_any_part_of_it(self) -> None:
self.assertEqual(overlaps({"a.py": ()}, {"a.py": (Part("g", small=True),)}), ["`a.py`"])
def test_reads_on_past_a_file_only_one_touches_and_past_a_whole_file(self) -> None:
theirs = {"a.py": (), "b.py": (Part("g"),)}
self.assertEqual(overlaps({"z.py": (Part("f"),), "a.py": (), "b.py": (Part("g"),)}, theirs), ["`a.py`", "`b.py` `g`"])
def test_line_ranges_overlap_where_they_share_a_line(self) -> None:
self.assertEqual(overlaps({"x.sh": (Part("lines 1-10"),)}, {"x.sh": (Part("lines 10-12"),)}), ["`x.sh` lines 1-10"])
self.assertEqual(overlaps({"x.sh": (Part("lines 1-9"),)}, {"x.sh": (Part("lines 10-12"),)}), [])
self.assertEqual(overlaps({"x.sh": (Part("lines 10-12"),)}, {"x.sh": (Part("lines 1-10"),)}), ["`x.sh` lines 10-12"])
self.assertEqual(overlaps({"x.sh": (Part("lines 11-12"),)}, {"x.sh": (Part("lines 1-10"),)}), [])
def test_a_line_range_overlaps_a_named_part_since_nothing_tells_them_apart(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("lines 1-9"),)}, {"a.py": (Part("f"),)}), ["`a.py` lines 1-9"])
self.assertEqual(overlaps({"a.py": (Part("f"),)}, {"a.py": (Part("lines 1-9"),)}), ["`a.py` `f`"])
def test_a_small_change_on_either_side_is_taken(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("f", small=True),)}, {"a.py": (Part("f"),)}), [])
self.assertEqual(overlaps({"a.py": (Part("f"),)}, {"a.py": (Part("f", small=True),)}), [])
+4 -1
View File
@@ -22,6 +22,9 @@ BLOCKED_BY = "Blocked by"
MOVES = "Moves"
# The achieve goal every project shares, which ~/.claude/CLAUDE.md → "Shared goal" states, and a Moves cell names by these words, since it has no number in any goals file.
CODE_HEALTH = "code health"
# The scope that opens a goal's name in the Moves of an epic's item, since the epic and the item's repo both number their goals from 1: `epic 1.1 by 8, code health by 5, repo 2 by 4`. Three readers, seated as the human who writes these cells, picked a scope word on both goals, 3-0, over one on either alone and over the repo's name. A todo.md's item may name neither.
EPIC_GOAL = "epic "
REPO_GOAL = "repo "
# How the items table's header opens, which tells it from any other table in todo.md.
HEADER_START = "| ID | Release |"
# todo.md's ## Details section, its body the first group.
@@ -61,7 +64,7 @@ class Shape:
def parse_moves(label: str, cell: str) -> Moves | Failure:
"""A Moves cell: empty, or each goal the item moves, named once, and how far. ranking.py's cited_goals_failure holds the rules that need the goals file."""
matches = [re.fullmatch(rf"([0-9]+(?:\.[0-9]+)*|{CODE_HEALTH}) by ([0-9]+)", move) for move in cell.split(", ")] if cell else []
matches = [re.fullmatch(rf"((?:{EPIC_GOAL}|{REPO_GOAL})?[0-9]+(?:\.[0-9]+)*|{CODE_HEALTH}) by ([0-9]+)", move) for move in cell.split(", ")] if cell else []
moves = tuple((match.group(1), int(match.group(2))) for match in matches if match)
if len(moves) < len(matches) or any(not 1 <= by <= TOP_SCORE for _, by in moves):
return Failure(f"{label}'s {MOVES} {cell!r} is not empty or goals such as `1.1 by 8, {CODE_HEALTH} by 5`, each moved by a whole number from 1 to {TOP_SCORE}")
@@ -1,5 +1,7 @@
"""An item's prediction of the files and parts it will touch, as its detail spells it, and where two predictions overlap.
It sits in plan so that plan_store's `FilePlan.check` and todo-item can call `predicted`: touch_predictions imports plan_store, and importing touch_predictions from plan_store would make the two packages import each other.
The spelling, which the decision `todo.md: an item of the next release predicts the files and parts it will touch …` gives the reasons for:
Touches:
@@ -46,7 +48,7 @@ def predicted(detail: str) -> Touches | None | Failure:
break
read = bullet(line)
if read is None:
return Failure(f"the bullet {line!r} under `{LABEL}` is not a path in backticks, then optionally a colon and its parts, each a name in backticks or `lines <first>-<last>`, and optionally `{SMALL}`")
return Failure(f"the bullet {line!r} under `{LABEL}` is not a path in backticks, then optionally a colon and its parts, each a name in backticks or `lines <first>-<last>` that `{SMALL.strip()}` may follow; `{SMALL.strip()}` follows a part, never a bare path")
if any(span and span[0] > span[1] for span in map(line_range, read[1])):
return Failure(f"the bullet {line!r} under `{LABEL}` holds a line range whose first line comes after its last")
touches = together([touches, {read[0]: read[1]}])
+11 -2
View File
@@ -7,6 +7,7 @@ from plan_store.plans import cells, Plan, Written
from failure import Failure
from plan.todo_table import item_details, items, NoItemsTable, renames
from plan_store import markdown_edits
from plan.touches import predicted
from plan import ranking
from record_store.stores import RecordStore
from text_files.file_writes import replace_file
@@ -84,7 +85,7 @@ class FilePlan:
return ranked
def check(self) -> list[str]:
"""Why `rank_todo.py --check` fails on the file, empty when it passes: the file is not ranked, or an item scores under the bar."""
"""Why `rank_todo.py --check` fails on the file, empty when it passes: the file is not ranked, an item scores under the bar, or touch-predictions cannot read an item's `Touches:` list."""
texts = self.texts()
if isinstance(texts, Failure):
return [texts.reason]
@@ -92,7 +93,7 @@ class FilePlan:
if isinstance(ranked, Failure):
return [ranked.reason]
unranked = [] if ranked.text == texts[0] else [f"{self.path}: not ranked; run rank_todo.py on it"]
return unranked + [f"{self.path}: {line}" for line in ranked.under_bar]
return unranked + [f"{self.path}: {line}" for line in ranked.under_bar + unreadable_touches(texts[0])]
def reported(self, ranked: ranking.Ranked) -> list[str]:
"""Ranking's notes and under-bar lines, each prefixed with the file's path, as a tool prints them on stderr."""
@@ -115,6 +116,14 @@ class FilePlan:
return weighing if isinstance(weighing, Failure) else (plan, *weighing)
def unreadable_touches(todo: str) -> list[str]:
"""One line per item whose `Touches:` list touch-predictions cannot read, saying why. Every item is read, not only the next release's: a later item moves into the next release with its detail, and the list is fixed most cheaply where it was written."""
details = item_details(todo)
if isinstance(details, Failure):
return [details.reason]
return [f"item {id_}: {read.reason}" for id_, detail in details.items() if isinstance(read := predicted(detail), Failure)]
def plan_of(todo: str) -> Plan | Failure:
"""The plan a todo.md's text holds."""
found = items(todo)
+3 -2
View File
@@ -11,7 +11,8 @@ question rows come first, then security rows, then the rest, each group by score
then by ID. Then it moves each blocker, an item another's Blocked by cell names, that ranks below
an item it blocks to just above the first such item. Orders the details to match. Writes each
item's R, and adds the Blocked by and R columns to a table without them. --check doesn't write
anything and fails when the file is not ranked as it would be.
anything and fails when the file is not ranked as it would be, or when an item's detail holds a
`Touches:` list not spelt as `touch-predictions --help` shows.
A valid todo.md; ## Details and each item's detail are optional:
@@ -87,7 +88,7 @@ Exit 1, saying why, on bad arguments, a checkout no config names or a config tha
file given that is not the config's plan, a file that cannot be read or written, a todo.md, goals file or docs/decisions.md that breaks the
rules above, a scoring run on docs/comprehension-history.md's newest scored commit with no Mean row
ending in its overall, an item that is not exempt scoring under the bar, or --check finding the file
unranked.
unranked, or an item's `Touches:` list unreadable.
"""
import pathlib
import sys
+1 -1
View File
@@ -5,7 +5,7 @@ import sys
import typing
from failure import Failure
from loop_claude.cycle.retry import FAILURES_RUNNING
from agent_cycle.retry import FAILURES_RUNNING
from claude_code.reply import Limited
from model_routing.ladder import Rung
+20
View File
@@ -12,6 +12,7 @@ from plan.test_ranking import DECISIONS, OLD_SHAPE, README, TODO
from project_config.settings import DEFAULT_FLOOR
from plan import goals_file, ranking
import rank_todo
from todo_item.test_todo_item import READABLE_TOUCHES, UNREADABLE_BULLETS
class Main(unittest.TestCase):
@@ -102,6 +103,25 @@ class Main(unittest.TestCase):
self.assertEqual(self.run_main(str(todo)), (1, f"{todo}: {under}\n"))
self.assertEqual(self.run_main("--check", str(todo)), (1, f"{todo}: {under}\n"))
def test_check_fails_on_each_item_whose_touches_list_it_cannot_read(self):
with tempfile.TemporaryDirectory() as temp:
todo = pathlib.Path(temp, "todo.md")
configured(self, pathlib.Path(temp))
self.enterContext(contextlib.chdir(temp))
pathlib.Path(temp, "README.md").write_text(README)
pathlib.Path(temp, "docs").mkdir()
pathlib.Path(temp, "docs", "decisions.md").write_text(DECISIONS)
for bullet in UNREADABLE_BULLETS:
with self.subTest(bullet):
# Item 1 sits in a later release than item 3: the check reads every item's list, not only the next release's.
todo.write_text(TODO.replace("Fast detail.", READABLE_TOUCHES).replace("Later detail.", f"Touches:\n\n{bullet}"))
self.assertEqual(self.run_main(str(todo))[0], 0)
code, said = self.run_main("--check", str(todo))
self.assertEqual(code, 1)
self.assertTrue(said.startswith(f"{todo}: item 1: "), said)
self.assertIn(repr(bullet), said)
self.assertEqual(said.count("\n"), 1)
def test_says_to_reshape_an_old_shape_table_but_passes_the_check(self):
with tempfile.TemporaryDirectory() as temp:
todo = pathlib.Path(temp, "todo.md")
+14 -4
View File
@@ -27,7 +27,8 @@ list and show read only the plan, and print no Score: an item's place in list's
add files the item under the next free ID, with the tagline in bold, and the detail it reads from
stdin, if any. The detail may hold no ## or ### heading.
It prints `Filed item <ID> in <plan>.` It doesn't write anything where ranking fails or scores the item under the bar.
It prints `Filed item <ID> in <plan>.` It doesn't write anything where ranking fails or scores the item under the bar,
or where the detail holds a `Touches:` list not spelt as `touch-predictions --help` shows.
In a Jira epic, add files a Task under the epic, and <ID> is the new issue's number. The release
must be one of the Jira project's Fix Versions, named as 1.2.0 or v1.2.0 there, and --exempt
security also labels the issue `security`. The item scores by the config's `jira-score-formula`, and
@@ -41,7 +42,8 @@ edit sets the cells whose flag is given and leaves the rest; an empty value, as
empties the cell. --detail replaces the detail with the text on stdin, and --clear-detail removes it.
Text on stdin without --detail, and --detail without text on stdin, are refused, so no detail is
dropped or wiped by mistake. It prints `Edited item <ID> in <plan>.` It doesn't write anything where
ranking fails or scores the item under the bar.
ranking fails or scores the item under the bar, or where a new detail holds a `Touches:` list not
spelt as `touch-predictions --help` shows.
In a Jira epic, edit changes an issue the loop filed: its summary, description and scores, the label
`security` with --exempt, and its "is blocked by" links with --blocked-by: it makes a link for each
blocker added and deletes the link of each blocker dropped. Each blocker must be an open child of the
@@ -89,6 +91,7 @@ from project_config.main import located
from plan_store.plans import no_item, PlanStore, TAGLINE, Written
from plan.release import parsed, Release, version as release_version
from plan_store.stores import store as plan_store
from plan.touches import predicted
from record_store.stores import RecordStore, store
from todo_item.table import shown, table
from todo_item.edits import with_bullet
@@ -115,7 +118,8 @@ def main(argv: list[str], folder: pathlib.Path = pathlib.Path(), stdin: typing.T
case "show":
done = show(args, plan)
case "add":
done = reported(plan.add(fields(args), piped(stdin)), "not filed", lambda written: f"Filed item {written.id} in {plan.label}.")
detail = piped(stdin)
done = unreadable(detail, "not filed") or reported(plan.add(fields(args), detail), "not filed", lambda written: f"Filed item {written.id} in {plan.label}.")
case "edit":
done = edit(args, plan, piped(stdin))
case "move":
@@ -194,6 +198,12 @@ def reported(written: Written | Failure, refusal: str, done: typing.Callable[[Wr
return done(written)
def unreadable(detail: str | None, refusal: str) -> Failure | None:
"""A Failure opened with refusal where detail holds a `Touches:` list touch-predictions cannot read; checked here, before the plan's backend gets the detail, so a plan in Jira is held to it too."""
read = None if detail is None else predicted(detail)
return Failure(f"{refusal}: {read.reason}") if isinstance(read, Failure) else None
def list_(args: argparse.Namespace, plan: PlanStore) -> str | Failure:
read = plan.read()
if isinstance(read, Failure):
@@ -220,7 +230,7 @@ def edit(args: argparse.Namespace, plan: PlanStore, text: str) -> str | Failure:
detail = text if args.detail else "" if args.clear_detail else None
if not fields(args) and detail is None:
return Failure("not edited: no flag names a change; todo-item --help lists them")
return reported(plan.edit(args.id, fields(args), detail, args.comment), "not edited", lambda written: f"Edited item {written.id} in {plan.label}.")
return unreadable(detail, f"not edited: item {args.id}'s detail") or reported(plan.edit(args.id, fields(args), detail, args.comment), "not edited", lambda written: f"Edited item {written.id} in {plan.label}.")
def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore | None) -> str | Failure:
+41
View File
@@ -25,6 +25,16 @@ CHANGELOG = "# Changelog\n\n## Unreleased\n\n- Older news.\n\n## 0.1.0\n\n- Firs
# ## Details of the ranked fixture, without the trailing ## Notes.
HEADER = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves |\n|---|---|---|---|---|---|---|---|---|---|---|\n"
DETAILS = "## Details\n\n### 3. Make it fast, `a | b`.\n\nFast detail.\n\n### 1. Ship the later thing.\n\nLater detail.\n\n"
# The bullets six items held on 2026-11-18, which touch-predictions cannot read: `(small)` after a bare path, and a part not in backticks.
UNREADABLE_BULLETS = (
"- `bin/judge_replay/main.py` (small)",
"- `bin/do_epic/main.py` (small)",
"- `principles/technical-principles.md`: the tests bullet group, `A valuable test checks behaviour` (small)",
"- `README.md`: loop-claude's section (small)",
"- `bin/rule_hook/rules.py`: the rule table (small)",
"- `settings.json`: the PreToolUse matcher (small)",
)
READABLE_TOUCHES = "Why.\n\nTouches:\n\n- `bin/a.py`: `main`, `Plan.branch` (small)\n- `bin/run.sh`: lines 10-20\n- `docs/new.md`\n"
class Terminal(io.StringIO):
@@ -488,6 +498,37 @@ class Edit(TodoItem):
self.assertEqual(self.todo.read_text(), before)
class UnreadableTouches(TodoItem):
"""A `Touches:` list touch-predictions cannot read is refused when written, since loop-claude doesn't start any chunk beside an item whose list it cannot read."""
def test_add_and_edit_refuse_each_bullet_that_stalled_the_loop(self):
for bullet in UNREADABLE_BULLETS:
for argv, refusal in ((ADD, "not filed: "), (["edit", "3", "--detail"], "not edited: item 3's detail: ")):
with self.subTest(bullet=bullet, command=argv[0]):
before = self.todo.read_text()
code, out, err = self.run_main(*argv, stdin=f"Why.\n\nTouches:\n\n- `bin/a.py`: `main`\n{bullet}\n")
self.assertEqual((code, out), (1, ""))
self.assertTrue(err.startswith(refusal), err)
self.assertIn(repr(bullet), err)
self.assertEqual(self.todo.read_text(), before)
def test_add_and_edit_take_a_readable_list_and_a_detail_without_one(self):
for detail in (READABLE_TOUCHES, "Why, without a list.\n"):
with self.subTest(detail):
self.assertEqual(self.run_main(*ADD, stdin=detail)[0], 0)
self.assertEqual(self.run_main("edit", "3", "--detail", stdin=detail)[0], 0)
self.assertIn(detail, self.todo.read_text())
def test_a_plan_in_jira_gets_no_unreadable_list_either(self):
self.config.write_text(self.config.read_text().replace('"checkout:todo.md"', f'"{JIRA_PLAN}"') + 'env-file = "~/acme.env"\n' + JIRA_SCORING)
plan = MemoryPlan({3: {"Release": "0.1.0", "Item": "**Count the runs.**", "L": "1", "E": "2", "I": "3", "S": "1"}})
self.enterContext(unittest.mock.patch.object(main, "plan_store", return_value=plan))
detail = f"Touches:\n\n{UNREADABLE_BULLETS[0]}\n"
self.assertEqual(self.run_main(*ADD, stdin=detail)[:2], (1, ""))
self.assertEqual(self.run_main("edit", "3", "--detail", stdin=detail)[:2], (1, ""))
self.assertEqual((list(plan.rows), plan.details), ([3], {}))
class Move(TodoItem):
def test_sets_the_items_release_and_keeps_the_rest(self):
self.assertEqual(self.run_main("move", "3", "--release", "0.2.0"), (0, f"Moved item 3 to release 0.2.0 in {self.todo}.\n", ""))
+1 -1
View File
@@ -3,7 +3,7 @@ import dataclasses
from failure import Failure
from plan.todo_table import Item, waiting
from touch_predictions.prediction import LABEL, overlaps, predicted, Touches
from plan.touches import LABEL, overlaps, predicted, Touches
@dataclasses.dataclass(frozen=True)
+1 -1
View File
@@ -3,7 +3,7 @@ import re
from failure import Failure
from git_cli.git_repo import git, Git
from touch_predictions.prediction import Part, Touches
from plan.touches import Part, Touches
from touch_predictions.file_parts import part_names
HUNK = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@", re.M)
+1 -1
View File
@@ -49,7 +49,7 @@ import typing
from git_cli.git_repo import default_ref, git, Git
from failure import Failure
from plan_store.stores import store as plan_store
from touch_predictions.prediction import predicted, together, Touches
from plan.touches import predicted, together, Touches
from project_config.main import project
from project_config.settings import ProjectConfig, TOUCH_PREDICTIONS
from touch_predictions import record
+1 -1
View File
@@ -3,7 +3,7 @@ import re
from failure import Failure
from record_store.stores import RecordStore
from touch_predictions.prediction import rendered, Touches
from plan.touches import rendered, Touches
from text_files.utc_stamp import STAMPED
TITLE = "# Touch predictions"
+1 -159
View File
@@ -1,7 +1,6 @@
import os
import pathlib
import re
import shutil
import subprocess
import sys
import tempfile
@@ -10,53 +9,16 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from touch_predictions.beside import Beside, chunks_beside
from adf_codec import convert
from touch_predictions import diff_parts, file_parts, main, record
from failure import Failure
from test_env import isolated_env
from project_config.main import located
from record_store.fakes import MemoryStore
from touch_predictions.prediction import overlaps, Part, predicted, rendered, together
from plan.touches import Part
from plan_store.todo_md import plan_of
from project_config.settings import ProjectConfig
from project_config.test_project_config import write_config
DETAIL = """A planning call.
Touches:
- `bin/a.py`: `main`, `Plan.branch` (small)
- `README.md`: `## Goals, and (more): things`
- `bin/run.sh`: lines 10-20
- `docs/new.md`
More prose, with `bin/b.py` named.
"""
needs_docker = unittest.skipIf(shutil.which("docker") is None or subprocess.run(["docker", "info"], capture_output=True, timeout=20).returncode != 0, "adf_codec runs in a container, which needs a docker daemon")
def text(words: str, code: bool = False) -> dict:
return {"type": "text", "text": words, **({"marks": [{"type": "code"}]} if code else {})}
def bullet_of(*spans: dict) -> dict:
return {"type": "listItem", "attrs": {"localId": "i"}, "content": [{"type": "paragraph", "attrs": {"localId": "p"}, "content": list(spans)}]}
# A Touches list as someone types it in Jira's editor: a paragraph, then a bulleted list whose paths and names carry the code mark.
JIRA_TOUCHES = {"type": "doc", "version": 1, "content": [
{"type": "paragraph", "attrs": {"localId": "a"}, "content": [text("A planning call.")]},
{"type": "paragraph", "attrs": {"localId": "b"}, "content": [text("Touches:")]},
{"type": "bulletList", "attrs": {"localId": "c"}, "content": [
bullet_of(text("bin/a.py", True), text(": "), text("main", True), text(", "), text("Plan.branch", True), text(" (small)")),
bullet_of(text("a`b.md", True), text(": "), text("## The `foo` tool", True), text(" (small)"), text(", "), text("`x`", True)),
bullet_of(text("bin/run.sh", True), text(": lines 10-20")),
bullet_of(text("docs/new.md", True)),
]},
{"type": "paragraph", "attrs": {"localId": "d"}, "content": [text("More prose.")]},
]}
PYTHON = """\"\"\"Docstring.\"\"\"
import os
@@ -98,126 +60,6 @@ Text.
"""
class PredictedTest(unittest.TestCase):
def test_reads_each_bullet_of_the_touches_list(self) -> None:
self.assertEqual(predicted(DETAIL), {
"bin/a.py": (Part("main"), Part("Plan.branch", small=True)),
"README.md": (Part("## Goals, and (more): things"),),
"bin/run.sh": (Part("lines 10-20"),),
"docs/new.md": (),
})
def test_a_detail_without_the_list_predicts_nothing(self) -> None:
self.assertIsNone(predicted("Only prose, with `bin/a.py` named."))
def test_a_bullet_it_cannot_read_is_a_failure_that_quotes_it(self) -> None:
for bullet in ("- bin/a.py: main", "- `bin/a.py`: main", "- `bin/a.py`: lines 20-10", "- `bin/a.py`: `main` `other`"):
with self.subTest(bullet):
found = predicted(f"Touches:\n\n{bullet}\n")
assert isinstance(found, Failure)
self.assertIn(bullet, found.reason)
def test_an_empty_list_is_a_failure(self) -> None:
self.assertIsInstance(predicted("Touches:\n\nProse.\n"), Failure)
found = predicted("Touches:\n")
assert isinstance(found, Failure)
self.assertEqual(found.reason, "no bullet follows `Touches:`")
def test_reads_a_list_right_under_its_label_a_one_line_range_and_a_name_of_any_letters(self) -> None:
self.assertEqual(predicted("Touches:\n- `a.py`: `Xray`, lines 5-5\n"), {"a.py": (Part("Xray"), Part("lines 5-5"))})
def test_rendered_reads_back(self) -> None:
touches = predicted(DETAIL)
assert isinstance(touches, dict)
self.assertEqual(predicted(f"Touches:\n\n{rendered(touches)}\n"), touches)
def test_a_name_that_holds_backticks_takes_a_longer_run_with_a_space_inside_each_end(self) -> None:
self.assertEqual(predicted("Touches:\n- `a.md`: `` ## The `foo` tool `` (small), ``` `` ```, `` `x` ``\n"), {"a.md": (Part("## The `foo` tool", small=True), Part("``"), Part("`x`"))})
self.assertEqual(rendered({"a.md": (Part("## The `foo` tool", small=True), Part("``"))}), "- `a.md`: `` ## The `foo` tool `` (small), ``` `` ```")
def test_a_longer_run_without_padding_spaces_is_the_text_between_its_runs(self) -> None:
self.assertEqual(predicted("Touches:\n- ``a`b.md``: ``## The `foo` tool`` (small), ``` `` ```, `` `x` ``\n"), {"a`b.md": (Part("## The `foo` tool", small=True), Part("``"), Part("`x`"))})
def test_a_longer_run_with_a_space_at_one_end_only_keeps_it(self) -> None:
self.assertEqual(predicted("Touches:\n- `a.md`: `` x``, ``y ``, `` a ``\n"), {"a.md": (Part(" x"), Part("y "), Part("a"))})
@needs_docker
def test_a_list_written_in_markdown_and_read_back_from_a_jira_description_reads_as_written(self) -> None:
description = convert.markdown_to_adf(DETAIL)
assert isinstance(description, dict)
self.assertEqual(predicted(convert.adf_to_markdown(description)), predicted(DETAIL))
@needs_docker
def test_a_list_typed_in_jiras_editor_reads_as_its_files_and_parts(self) -> None:
read = convert.adf_to_markdown(JIRA_TOUCHES)
self.assertEqual(predicted(read), {
"bin/a.py": (Part("main"), Part("Plan.branch", small=True)),
"a`b.md": (Part("## The `foo` tool", small=True), Part("`x`")),
"bin/run.sh": (Part("lines 10-20"),),
"docs/new.md": (),
})
def test_a_name_ends_only_at_a_run_as_long_as_the_one_that_opens_it(self) -> None:
self.assertEqual(predicted("Touches:\n- `a.md`: `` a ``` b ``, `c``d`\n"), {"a.md": (Part("a ``` b"), Part("c``d"))})
def test_a_path_holds_any_character_and_a_single_backtick_keeps_a_names_spaces(self) -> None:
self.assertEqual(predicted("Touches:\n- `my file.md`: ` x `\n- `` a`b.md ``\n"), {"my file.md": (Part(" x "),), "a`b.md": ()})
def test_rendered_reads_back_whatever_a_path_or_a_name_holds(self) -> None:
touches = {"my file.md": (Part("## todo.md: under `Touches:` in its detail"), Part("## ``a`` and `b`", small=True), Part("`"), Part("## ends in `x`"), Part(" x "), Part("lines 2-3")), "a`b.md": (), "c, d: e.md": (Part("# T"),)}
self.assertEqual(predicted(f"Touches:\n\n{rendered(touches)}\n"), touches)
def test_a_bullet_with_an_unclosed_run_a_blank_name_or_a_stray_separator_is_a_failure(self) -> None:
for bullet in ("- `a.md`: `` ## A", "- `a.md`: `` ## A `", "- `a.md`: `` ``", "- `a.md`: ", "- `a.md`:", "- `a.md`: `f`, ", "- `a.md`: `f`,`g`", "- ``", "- `a.md` (small)", "- `a.md`: `f` (small) (small)"):
with self.subTest(bullet):
self.assertIsInstance(predicted(f"Touches:\n\n{bullet}\n"), Failure)
def test_a_range_that_runs_backwards_is_a_failure_that_says_so(self) -> None:
found = predicted("Touches:\n\n- `bin/a.py`: `f`, lines 20-10\n")
assert isinstance(found, Failure)
self.assertEqual(found.reason, "the bullet '- `bin/a.py`: `f`, lines 20-10' under `Touches:` holds a line range whose first line comes after its last")
def test_together_joins_items_and_keeps_small_only_where_each_says_so(self) -> None:
joined = together([{"a.py": (Part("f", small=True), Part("g", small=True))}, {"a.py": (Part("f"),), "b.md": ()}, {"b.md": (Part("# T"),)}])
self.assertEqual(joined, {"a.py": (Part("f"), Part("g", small=True)), "b.md": ()})
def test_together_keeps_a_part_not_small_once_one_says_so_and_reads_on_past_a_whole_file(self) -> None:
joined = together([{"a.py": (Part("f"),), "b.md": ()}, {"b.md": (Part("# T"),), "a.py": (Part("f", small=True),), "c.py": (Part("h"),)}])
self.assertEqual(joined, {"a.py": (Part("f"),), "b.md": (), "c.py": (Part("h"),)})
class OverlapsTest(unittest.TestCase):
def test_other_files_and_other_parts_do_not_overlap(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("f"),)}, {"a.py": (Part("g"),), "b.py": ()}), [])
def test_the_same_part_overlaps(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("f"), Part("g"))}, {"a.py": (Part("g"),)}), ["`a.py` `g`"])
def test_a_class_overlaps_its_method_but_not_a_name_it_only_starts(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("Plan"),)}, {"a.py": (Part("Plan.branch"), Part("Planned"))}), ["`a.py` `Plan`"])
def test_a_whole_file_overlaps_any_part_of_it(self) -> None:
self.assertEqual(overlaps({"a.py": ()}, {"a.py": (Part("g", small=True),)}), ["`a.py`"])
def test_reads_on_past_a_file_only_one_touches_and_past_a_whole_file(self) -> None:
theirs = {"a.py": (), "b.py": (Part("g"),)}
self.assertEqual(overlaps({"z.py": (Part("f"),), "a.py": (), "b.py": (Part("g"),)}, theirs), ["`a.py`", "`b.py` `g`"])
def test_line_ranges_overlap_where_they_share_a_line(self) -> None:
self.assertEqual(overlaps({"x.sh": (Part("lines 1-10"),)}, {"x.sh": (Part("lines 10-12"),)}), ["`x.sh` lines 1-10"])
self.assertEqual(overlaps({"x.sh": (Part("lines 1-9"),)}, {"x.sh": (Part("lines 10-12"),)}), [])
self.assertEqual(overlaps({"x.sh": (Part("lines 10-12"),)}, {"x.sh": (Part("lines 1-10"),)}), ["`x.sh` lines 10-12"])
self.assertEqual(overlaps({"x.sh": (Part("lines 11-12"),)}, {"x.sh": (Part("lines 1-10"),)}), [])
def test_a_line_range_overlaps_a_named_part_since_nothing_tells_them_apart(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("lines 1-9"),)}, {"a.py": (Part("f"),)}), ["`a.py` lines 1-9"])
self.assertEqual(overlaps({"a.py": (Part("f"),)}, {"a.py": (Part("lines 1-9"),)}), ["`a.py` `f`"])
def test_a_small_change_on_either_side_is_taken(self) -> None:
self.assertEqual(overlaps({"a.py": (Part("f", small=True),)}, {"a.py": (Part("f"),)}), [])
self.assertEqual(overlaps({"a.py": (Part("f"),)}, {"a.py": (Part("f", small=True),)}), [])
class FilePartsTest(unittest.TestCase):
def names(self, path: str, text: str, *lines: int) -> set[str] | None:
return file_parts.part_names(path, text, lines)
+8 -6
View File
@@ -208,7 +208,7 @@ Valid while `~/.claude` is a checkout of this repo.
- **The archive and the route needed no change.** The archive keys each chunk by its own transcript's first line, and a rerun's route comes from the latest verdict on that transcript, so both follow the session. The routing figures are measured across all projects, under their own lock.
- **git's own lock serializes the config folder's commits, in place of the file lock the item asked for.** `git commit` holds `.git/index.lock`, so of two commits at once the second fails, and the worker tries again. A wrapper lock would only make it wait, and a command spelled `flock … git commit` would pass rule-hook unchecked, since it reads only a command that starts with `git`. What two chunks could still break is one committing the file the other staged, so each commits only its own file, as `git commit -m <title> -- <file>` (`CLAUDE.md` → "Git, commits, and PRs").
2026-11-16, lilleman's second call of 2026-11-13 splitting item 361: lilleman knows tmux and prefers it. Each chunk runs in its own window of one tmux session per project, `loop-<key>`, up to the number the config's `parallel-chunks` sets, 1 by default. tmux runs even at 1, so every project runs the same workflow (goal 1.3). A window waiting for the human ends its name in ` ?` and rings the bell, and the DM names `<session>:<window>`. The worker's choices, for what the call left open (`bin/loop_claude/tmux.py`, `bin/loop_claude/loop/chunk_windows.py`):
2026-11-16, lilleman's second call of 2026-11-13 splitting item 361: lilleman knows tmux and prefers it. Each chunk runs in its own window of one tmux session per project, `loop-<key>`, up to the number the config's `parallel-chunks` sets, 1 by default. tmux runs even at 1, so every project runs the same workflow (goal 1.3). A window waiting for the human ends its name in ` ?` and rings the bell, and the DM names `<session>:<window>`. The worker's choices, for what the call left open (`bin/agent_cycle/tmux.py`, `bin/loop_claude/loop/chunk_windows.py`):
- **The window, in place of item 372's lock-file slot, names the claude session**, as `A <key> loop-claude item-372`. The loop-claude the human runs starts the windows and attaches; each window runs `loop-claude --chunk <window>`, so a loop knows its chunk before it names its claude session, and a rerun still resumes the chunk left open.
- **A finishing chunk starts the next; only the human restarts a stopped one.** As its chunk finishes, a window's loop starts each chunk that may start then and exits, so its window closes. `remain-on-exit failed` keeps the window of a loop that stopped any other way, Ctrl-C included, with its last lines, and its chunk keeps its items. A finishing chunk never restarts it, since the human may have stopped it on purpose; the next `loop-claude <task>` starts it again before any other chunk. One flock under `~/.local/state/loop-claude/<key>/` serializes the starts, so two chunks finishing together don't start one chunk twice.
@@ -245,7 +245,7 @@ Valid while score-outcomes reads the reversals from the archive.
2026-10-27, lilleman's yes to claude's evaluation through todo todo item 231. Serves goal 1.4; its counter-signal, review rounds and unfinished verdicts per chunk, is the check.
loop-claude hands each worker's claude `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000` (`bin/loop_claude/cycle/worker.py`), and the session /talk opens gets it too. Claude Code compacts before a window fills: a 1M window at about 967k tokens, and in a probe on 2026-10-27 a 100k window at 65k and 80k, so a 200k window compacts at about 170k. The window is not set in `settings.json`, since the archive measured loop-claude's workers and interactive sessions are lilleman's. Subagents inherit the variable, which reaches every process of the session: 68 of the 994 subagent runs since 2026-10-21, 7%, passed 170k, 24 of them principles auditors, so about one in fourteen compacts once. Compacting subagents by choice would cost more than it saves, as below, but the variable cannot leave them out, and `CLAUDE.md` → "Compact instructions" has a reviewer keep the findings it has drafted. That section shapes the summary: in another probe that day, a session whose CLAUDE.md asked for its summary to end with a secret word got a summary ending with that word. Path-scoped rules leave the context at a compaction and return at the next matching read, and rule-hook holds each review launch to its rung whatever the summary keeps. `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`, handed the same way, would compact at the same point but also cap the window at 200k, so a run that Claude Code stops compacting, as it does when one tool result refills the context each time, would hit the limit instead of going on.
loop-claude hands each worker's claude `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000` (`bin/agent_cycle/worker.py`), and the session /talk opens gets it too. Claude Code compacts before a window fills: a 1M window at about 967k tokens, and in a probe on 2026-10-27 a 100k window at 65k and 80k, so a 200k window compacts at about 170k. The window is not set in `settings.json`, since the archive measured loop-claude's workers and interactive sessions are lilleman's. Subagents inherit the variable, which reaches every process of the session: 68 of the 994 subagent runs since 2026-10-21, 7%, passed 170k, 24 of them principles auditors, so about one in fourteen compacts once. Compacting subagents by choice would cost more than it saves, as below, but the variable cannot leave them out, and `CLAUDE.md` → "Compact instructions" has a reviewer keep the findings it has drafted. That section shapes the summary: in another probe that day, a session whose CLAUDE.md asked for its summary to end with a secret word got a summary ending with that word. Path-scoped rules leave the context at a compaction and return at the next matching read, and rule-hook holds each review launch to its rung whatever the summary keeps. `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`, handed the same way, would compact at the same point but also cap the window at 200k, so a run that Claude Code stops compacting, as it does when one tool result refills the context each time, would hit the limit instead of going on.
Why 200k. Item 231 asked for the best means to lower what a chunk spends on context, in dollars, then hours, with no loss of quality. Measured from loop-claude's archive, the 90 chunks with messages after the routing figures' reset of 2026-10-21 cost $1,215 at the list prices read on 2026-10-26 (Opus 5.5: $4 per million input tokens, $5 and $8 for 5-minute and 1-hour cache writes, $0.20 for cache reads, $20 for output; no model but Haiku 5.5 charges more above 200k). That is 0.86 of what the chunks' `cost-state` entries sum to, since some chunks' subagent transcripts are not in the archive. Worker main threads cost $375 (31%): 1-hour cache writes $149, cache reads $153, output $74. Subagents cost $840: 5-minute cache writes $379, output $274, cache reads $187, with the principles auditors at $274 over 342 runs, the stability reviewers $179 and general-purpose subagents $192. A worker starts at 41k tokens of context and peaks at a median 167k, one in ten past 358k, the largest at 848k. The worker's messages above 200k were 32% of its messages and 55% of its cost.
@@ -272,7 +272,7 @@ Valid while cache reads cost a twentieth of input and Claude Code's compaction k
2026-11-18, claude, as the plan item that asked for the ceiling set out. Applies project principle 1; serves goal 1.4.
loop-claude hands each worker's claude `BASH_MAX_OUTPUT_LENGTH=6000` (`worker_environment` in `bin/loop_claude/cycle/run.py`, the value in `bin/claude_code/output_limits.py`). Claude Code then saves a longer Bash result to a file under `~/.claude/projects/<project>/<session>/tool-results/` and hands the model the path and the first 2,000 characters, which a probe on 2026-11-17 confirmed. A subagent inherits the variable, so every reviewer the worker launches gets it too. The archive held 7,870 Bash results over 3,000 characters in workers (about $305 of carried context) and about $145 more in stability reviewers; a ceiling of 6,000 characters would have removed $228 of the workers', 10,000 characters $122.
loop-claude hands each worker's claude `BASH_MAX_OUTPUT_LENGTH=6000` (`worker_environment` in `bin/agent_cycle/run.py`, the value in `bin/claude_code/output_limits.py`). Claude Code then saves a longer Bash result to a file under `~/.claude/projects/<project>/<session>/tool-results/` and hands the model the path and the first 2,000 characters, which a probe on 2026-11-17 confirmed. A subagent inherits the variable, so every reviewer the worker launches gets it too. The archive held 7,870 Bash results over 3,000 characters in workers (about $305 of carried context) and about $145 more in stability reviewers; a ceiling of 6,000 characters would have removed $228 of the workers', 10,000 characters $122.
rule-hook's `transcript-read` rule refuses a Read of a `.jsonl` file under `~/.claude/projects`: a session transcript holds every tool result of its session, and the archive's Reads of old ones cost $46. It doesn't refuse a Read of `tool-results/*.txt`, which the ceiling hands the model, and it checks no Grep or Bash command. It can't be overridden, since a Read carries no text for a marker.
@@ -584,7 +584,7 @@ Valid while delegated searches save more context than their reports cost.
Four escalation triggers in `CLAUDE.md` → "Working with the codebase" mark a task too hard: a re-score of the item on the project's rung or above picks a higher rung, the same failing test or finding survives two fix attempts, a pass reports a 🔴 in round 2 or later, or a reviewer or seat rules the work below standard, unless the fix changes only prose. When one fires, the worker hands the hard part to a subagent one rung above its own, edits included, though the delegation rule keeps edits in the worker's thread: the escalation exists because the worker could not get them right. Each further trigger on that task climbs one more rung. Without lilleman's yes the climb stops two rungs above the rung the chunk started on: the rung its item picks, or the project's rung when no item routed it. A step-up between cycles raises the worker but not that limit: lilleman set the limit from the rung the chunk started on, so a worker that has stepped up may need a yes for its first escalation.
loop-claude's prompt names the rungs a trigger opens, so the worker computes no rung positions, and tells the worker to open each escalated subagent's prompt with `Escalation trigger <n>:`. `bin/loop_claude/routing.py` holds the limit and `bin/model_routing/route.py` the marker. The archive keeps the raw transcript, which holds the marked prompt, and `bin/routing_figures/` counts the escalations by trigger in `routing-figures.md`, per starting rung for routed chunks and in total for every chunk.
loop-claude's prompt names the rungs a trigger opens, so the worker computes no rung positions, and tells the worker to open each escalated subagent's prompt with `Escalation trigger <n>:`. `bin/agent_cycle/routing.py` holds the limit and `bin/model_routing/route.py` the marker. The archive keeps the raw transcript, which holds the marked prompt, and `bin/routing_figures/` counts the escalations by trigger in `routing-figures.md`, per starting rung for routed chunks and in total for every chunk.
Valid while the ladder orders its rungs by competence.
@@ -650,7 +650,7 @@ Valid while workers write the line when asked, and while `todo.md` on the defaul
2026-10-15, lilleman's plan, settled by the replays below. Serves goals 1.1, 1.2 and 1.4, under the ladder and steps of `routing: one ladder`.
On a model listed in `JUDGE_REPLAYED` in `bin/loop_claude/routing.py`, the judge runs on its model's highest rung, whatever the chunk's items score: on an Opus 5.5 project, Opus 5.5 at xhigh. It keeps its rung when the worker steps up. Each archived verdict names the judge's rung on a `Judge:` line.
On a model listed in `JUDGE_REPLAYED` in `bin/agent_cycle/routing.py`, the judge runs on its model's highest rung, whatever the chunk's items score: on an Opus 5.5 project, Opus 5.5 at xhigh. It keeps its rung when the worker steps up. Each archived verdict names the judge's rung on a `Judge:` line.
On 2026-10-15, `bin/judge-replay claude-opus-5-5` replayed the latest 15 archived verdicts of each kind from the Opus 5.5 projects, 39 in all. The reference judge, Opus 5.5 at the xhigh effort `settings.json` gave every judge before, reproduced 31 of them. The other 8 may rest on records or judge rules that have changed since; either way no rung is held to them. On the 31, Haiku 5.5 missed 7 at xhigh and 8 at max. That run tried each judge once. 4 of Haiku's misses, 1 at xhigh and 3 at max, misquoted the transcript, which the loop and `judge-replay` now retry; without them it missed 6 and 5. Sonnet 5.5 at high returned another kind on 3 interrupts, and Opus 5.5 at medium missed none. A missed interrupt lets the worker settle a decision that is lilleman's (goal 1.2), so the judge never runs below the project's rung.
@@ -686,6 +686,8 @@ A project's rung is its model's cheapest rung, which for Opus 5.5 is its default
2026-11-15, lilleman asked for the ladder as a file that a project can replace, on a day when an outage left only Fable 5.2 answering: the rungs were a constant in `bin/model_routing/ladder.py`, so no project could leave Sonnet 5.5 and Opus 5.5 without a release. The shipped ladder is `bin/model_routing/routing-ladder.json`, a JSON list of rungs, least competent first. A project that keeps a `routing-ladder.json` in its config's folder, `~/.claude-projects/<key>/`, runs on that ladder whole, and the steps count on it as on the shipped one. Every project still runs the same routing rules and steps, so the workflow of goal 1.3 holds; the ladder joins what a project's config folder may supply, which that goal's list does not name yet. lilleman chose a file per project over one per machine, so a single project can differ. A ladder holds one model of each family, since the Agent tool launches a subagent or a review by its family's name. The project's file is lilleman's to write, as any change to the ladder is, and the loop never commits it. loop-claude reads the project's ladder as each cycle starts; `subagent-rung` and rule-hook's `reviewer-rung` read it each time they run, from the checkout they run in. A ladder file that holds a fault stops each of them, since work routed on the shipped ladder in its place could run on a model the project cannot reach. The routing figures, `judge-replay` and `review-replay` span every project, so they read the shipped ladder: a rung only a project's own ladder holds is left out of the figures' calls, and no replay qualifies it. lilleman shipped the change as 0.10.1, a patch cut from the tag v0.10.0, on the day of the outage: it adds a file format and an exit 1 to `subagent-rung`, which the technical principles' semantic versioning gives a minor, and lilleman asked for the patch "even if that breaks semver", so that the release in use could run again without taking the unreleased work on `main`.
2026-11-18, lilleman kept the ladder and the steps, settling the call raised on the routing figures measured at 2026-11-18T15:04:48Z: chunks routed onto Sonnet 5.5 at high took more review rounds past each pass's first than chunks routed onto Opus 5.5 at medium. The figures came from 19 chunks finished since the 2026-11-17 reset. The 13 chunks started on Sonnet 5.5 at high took a mean 0.5 rounds and 0.0 unfinished verdicts; the 6 started on Opus 5.5 at medium took 0.5 and 0.2. Neither rung had later fixes, among the 11 and the 4 chunks whose later fixes are known. Both means show 0.5, so the gap is under 0.1 rounds. Sonnet 5.5 did better on unfinished verdicts, and it is the cheaper rung (goal 1.4). loop-claude lists the call in `routing-calls-raised.md` only once the session that put it to lilleman ends, stamped with the time the figures were measured, so this note cites that time.
Valid while the index ranks these models, and while no newer model joins the catalog.
## routing: the offline classifier may decide finished, since lilleman ruled a miss rate of about 1 in 100 decided close enough to none; the judge's model keeps every other verdict kind
@@ -804,7 +806,7 @@ Valid while the worker writes the tests that larv-review's reviewers hold to the
## todo.md: an item of the next release predicts the files and parts it will touch under `Touches:` in its detail; chunk-preflight takes, in the plan's order, the items that overlap none taken before them as the chunks that may run at once, and the optional `touch-predictions` record keeps each chunk's prediction beside what it touched
2026-11-15, lilleman's call of 2026-11-13 in item 373, which split item 361. Serves goal 1.5, held to goal 1.4: several chunks of one project run at once only where they are unlikely to touch the same lines, since a conflict costs a rebase, a gate rerun and often a review round. A session on the project's rung or above writes each prediction, as `rules/todo-items.md` says, and `bin/touch_predictions/` reads it. The choices the call left open:
2026-11-15, lilleman's call of 2026-11-13 in item 373, which split item 361. Serves goal 1.5, held to goal 1.4: several chunks of one project run at once only where they are unlikely to touch the same lines, since a conflict costs a rebase, a gate rerun and often a review round. A session on the project's rung or above writes each prediction, as `rules/todo-items.md` says, and `bin/plan/touches.py` reads it. The choices the call left open:
- **The spelling.** A `Touches:` line, then one bullet per file: the path in backticks, then its parts, each a name in backticks or `lines <first>-<last>`, with `(small)` after a part the item changes only a little; a path or a name that holds a backtick takes a longer run of backticks with a space inside each end, as a Markdown code span does. A path alone is the whole file. Three readers seated as the README's audience picked the bulleted list over one line and over a table, since backticks hold a heading's commas, colons and parentheses. Two of the three put `(small)` after the part and outside the backticks, and two left line ranges unquoted. Each picked a different config key: `touch-predictions` was one reader's first choice and the second choice of the other two.
- **A part's boundaries.** Python's `ast` module names the innermost function or class, a top-level assignment by the name it sets, and `(module)` for the rest. A Markdown file's parts are its headings outside fenced code. Any other file, and Python that doesn't parse, falls back to line ranges. A table row is no part of its own: the item named one, but the tables chunks collide on are the plan's and the changelog's, which don't count.
+1 -1
View File
@@ -30,4 +30,4 @@ paths:
- **The Exempt cell keeps an item whatever its score:** `security` for a security finding, `defect` for a 🔴 finding or an item that restores a maintain goal the project breaks today, `question` for a question only the human can answer, which ranks first in its release, `decision` for an item `docs/decisions.md` cites, `owner` for an item the human told you to keep, and, where no other reason fits, `principle` for a 🟡 finding against a file in the config's principles folder, whose item's detail names that principle. Every item `docs/decisions.md` cites carries one of these reasons.
- **A maintain goal vetoes an item that breaks it,** whatever the item scores: redesign the item so it holds the goal, or drop it.
- **When you remove an item that no chunk built, title the commit `Drop item <ID>: <why>`,** or `Drop items 12, 14 and 15: <why>` for several. Such an item was deleted under the bar, vetoed, superseded or moot; a finished item is not one. Without the title, `score-outcomes` credits the item with the work of the chunk that removed it, where that chunk changed more than `todo.md`.
- **Predict, in the detail of each item of the next release, what the item will touch.** When you plan the next release, or file or move an item into it, give the item's detail a `Touches:` line, then one bullet per file the item will change. Each bullet names the file, then the parts of it the item will change: a function, a class or a section heading, or line ranges where the file has none of these. A path alone means the whole file. Read the code first; a prediction from the item's text alone misses. `~/.claude/bin/touch-predictions --help` shows the spelling and how a part is named; a name that holds a backtick takes a longer run of backticks with a space inside each end, as a Markdown code span does. Mark a part `(small)` where the item changes only a few lines of it. Leave out the plan and the project's records, which every chunk writes. `chunk-preflight` reads the predictions to name the items that may start chunks at once, and `touch-predictions record` keeps each beside what its chunk touched.
- **Predict, in the detail of each item of the next release, what the item will touch.** When you plan the next release, or file or move an item into it, give the item's detail a `Touches:` line, then one bullet per file the item will change. Each bullet names the file, then the parts of it the item will change: a function, a class or a section heading, or line ranges where the file has none of these. A path alone means the whole file. Read the code first; a prediction from the item's text alone misses. `~/.claude/bin/touch-predictions --help` shows the spelling and how a part is named; a name that holds a backtick takes a longer run of backticks with a space inside each end, as a Markdown code span does. Mark a part `(small)` where the item changes only a few lines of it. `(small)` follows a part, never a bare path. A part is a name in backticks, or `lines <first>-<last>`. BANNED: ``- `bin/a.py` (small)``, ``- `README.md`: loop-claude's section (small)``. GOOD: ``- `bin/a.py`: `main` (small)``, ``- `README.md`: `## Tools` (small)``. Leave out the plan and the project's records, which every chunk writes. `chunk-preflight` reads the predictions to name the items that may start chunks at once, and `touch-predictions record` keeps each beside what its chunk touched. `todo-item add`, `todo-item edit` and `rank_todo.py --check` refuse a list touch-predictions cannot read.
+48 -75
View File
@@ -6,16 +6,15 @@
`Bar = 0.1`
`Next ID = 425`
`Next ID = 428`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 424 | 0.12.0 | | principle | **Make each test that skips at run time create the state it needs or fail naming what is missing, so no test in the repo skips at run time.** | 3 | 2 | 1 | 4 | 4 | code health by 3, 1.1 by 3 | 4.8 |
| 401 | 0.12.0 | | | **Move loop-claude's cycle, judge, interrupt, tmux and routing into a package a second entry point drives, with loop-claude's behaviour unchanged.** | 3 | 2 | 3 | 6 | 6 | 1 by 3, code health by 2 | 1.8 |
| 408 | 0.12.0 | | | **Rank an epic's items by one weight chain, the epic's achieve goals, then code health, then the item's repo goals, then by Blocked by, and re-rank Jira's backlog to match, with people's issues keeping their rank.** | 3 | 2 | 2 | 5 | 4 | 1 by 5 | 1.6 |
| 410 | 0.12.0 | 401, 408 | | **Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.** | 3 | 2 | 3 | 6 | 6 | 1 by 5 | 0.8 |
| 426 | 0.12.0 | | | **Read each epic issue's scores, its blockers and whether the loop filed it through `EpicStore`, from both backends.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 427 | 0.12.0 | 426 | | **Re-rank Jira's backlog to match an epic's ranking, moving only the issues the loop filed, so people's issues keep their rank.** | 3 | 2 | 3 | 6 | 3 | 1 by 5 | 1.9 |
| 410 | 0.12.0 | 427 | | **Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.** | 3 | 2 | 3 | 6 | 6 | 1 by 5 | 0.8 |
| 416 | 0.12.0 | 410 | | **Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.** | 1 | 1 | 1 | 1 | 2 | 1 by 5 | 2.1 |
| 413 | 0.12.0 | 410 | | **File a finding about an epic goal in the epic and one about a repo goal by that repo's rules, ask the human where unsure which, and give the judge the epic's records beside the repo's.** | 3 | 2 | 3 | 6 | 4 | 1 by 5 | 1.6 |
| 415 | 0.12.0 | 410, 413 | | **Finish an epic: run release-review passes on each repo it changed, work what they file, have the human confirm each goal, post a summary comment, and close the epic in Jira last.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
@@ -30,7 +29,7 @@
| 421 | 0.12.0 | | | **Refuse in rule-hook a Bash or Monitor wait that has no end: a loop without a time or count cap, and a `pgrep -f` or `pkill -f` whose pattern the same command line contains.** | 2 | 2 | 3 | 5 | 3 | 1.5 by 4 | 1.3 |
| 316 | 0.12.0 | | | **Launch comprehension seats as an agent type of their own under `agents/`, without `CLAUDE.md` and the skill and agent listings a general-purpose subagent carries.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3 | 1.0 |
| 310 | 0.12.0 | | | **Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.** | 3 | 2 | 3 | 6 | 4 | 1.4 by 3 | 0.9 |
| 422 | 0.12.0 | 401, 420 | | **Check every 5 minutes whether a tmux window of the loop looks stuck by other signs than a lingering worker, investigate it with a headless claude, and kill only the process the investigation names.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 4 | 0.8 |
| 422 | 0.12.0 | 420 | | **Check every 5 minutes whether a tmux window of the loop looks stuck by other signs than a lingering worker, investigate it with a headless claude, and kill only the process the investigation names.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 4 | 0.8 |
| 365 | 0.13.0 | | | **Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
| 368 | 0.13.0 | | | **Call a release review due, call a release ready to cut, and tell whether a chunk owes a scoring run, for a plan outside the checkout, from the project repo's history or from Jira.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
| 309 | 0.13.0 | | | **Run a scoring run's second pass on one head with two seats in place of four, once `larv-review agreement` shows the seats agree with each other more than a run agrees with its rerun.** | 2 | 2 | 2 | 4 | 2 | 1.4 by 3 | 1.2 |
@@ -40,6 +39,7 @@
| 341 | 0.13.0 | | | **Hand each worker's claude a lower Read limit through `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`, kept only where replays of the archived review rounds find what two unchanged replays find.** | 2 | 2 | 3 | 5 | 3 | 1.4 by 3 | 1.0 |
| 298 | 0.13.0 | | | **Send the judge only the decision entries and the transcript tail a verdict needs, and keep the cut only where `judge-replay` changes no verdict kind.** | 3 | 3 | 3 | 7 | 4 | 1.4 by 2, 1.5 by 1 | 0.9 |
| 395 | 0.13.0 | | decision | **Keep each block a save didn't change, with its localId, and the spacing paragraphs beside it as Jira or Confluence holds them.** | 3 | 2 | 2 | 5 | 5 | 1.6 by 4 | 0.8 |
| 425 | 0.13.0 | | | **Show on loop-claude's terminal why it doesn't start a chunk beside the next item, as chunk-preflight prints it.** | 1 | 1 | 2 | 2 | 2 | 1.5 by 2 | 0.7 |
| 367 | 0.13.0 | | | **Check that every write to a Jira plan leaves it ranked, as rule-hook's `todo-rank-check` checks `todo.md` today.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 2 | 0.7 |
| 423 | 0.13.0 | | | **Skip the judge's model call on a worker's final message that the offline classifier decides is finished.** | 3 | 3 | 3 | 7 | 5 | 1.4 by 2 | 0.4 |
| 77 | 0.14.0 | | | **Teach `bin/metric-bench` Go and TypeScript, rerun it once two projects' comprehension histories name places, and bring into review only a metric that tracks the panel.** | 4 | 2 | 1 | 5 | 6 | 1.1 by 7, 1.4 by 7 | 2.1 |
@@ -82,78 +82,47 @@
## Details
### 424. Make each test that skips at run time create the state it needs or fail naming what is missing, so no test in the repo skips at run time.
### 426. Read each epic issue's scores, its blockers and whether the loop filed it through `EpicStore`, from both backends.
Follows item 400's bullet in `principles/technical-principles.md` → the tests principle: "A test doesn't decide at run time whether to check anything: no conditional skip, early return, or catch around its assertions. A test that needs a state creates it, or fails and names what is missing." Stability review found the repo's own tests break it in 13 places, each a skip decided at run time:
- root-less permission checks, `skipIf(os.geteuid() == 0, ...)`: 3 in `bin/loop_claude/test_black_box.py`, 3 in `bin/loop_claude/test_loop_claude.py`, 1 in `bin/routing_figures/test_routing_figures.py`, 1 in `bin/plan_store/test_stores.py`;
- pytest: `skipUnless(HAS_PYTEST, ...)` on the class `Run` in `bin/run_tests/test_run_tests.py`;
- docker: the `docker info` skipif on 2 tests in `bin/adf_codec/test_adf_codec.py`, and `needs_docker` in `bin/touch_predictions/test_touch_predictions.py`;
- /proc: `self.skipTest("no /proc/meminfo ...")` in `bin/run_heavy/test_run_heavy.py`.
The choice per case is the implementer's: for example, run the permission tests as a non-root user or drop the permission check in favour of an injected failure, take the docker or /proc state from an injected fake, or let the test fail naming what is missing. Done when a grep for `skipIf`, `skipUnless`, `skipTest` and `mark.skip` in the repo's tests finds none.
Today `EpicIssue` holds none of the three, so do-epic cannot score or order an epic's items (item 408) or tell a person's issue from its own (item 427). The Jira backend reads them as `plan_store/jira_epic.py` does: the `plan-item` issue property, its `Filed by` key, and the "is blocked by" links. The contract tests in `contract.py` cover both backends.
Touches:
- `bin/loop_claude/test_black_box.py`: `Cycles.test_exits_1_when_the_transcript_cannot_be_read`, `Interrupt.test_exits_1_when_the_transcript_cannot_be_read_after_the_interrupt`, `Models.test_exits_1_when_the_models_file_cannot_be_written`
- `bin/loop_claude/test_loop_claude.py`: `Cycles.test_stops_on_a_session_folder_it_cannot_read_whole`, `Cycles.test_stops_keeping_the_transcript_when_the_finished_chunks_session_cannot_be_deleted`, `RoutingCheck.test_says_a_figure_it_cannot_write_and_goes_on`
- `bin/routing_figures/test_routing_figures.py`: `Archive.test_fails_when_it_cannot_keep_the_state` (small)
- `bin/plan_store/test_stores.py`: `FilePlan.test_a_file_it_cannot_write_fails_naming_it` (small)
- `bin/run_tests/test_run_tests.py`: `HAS_PYTEST`, `Run` (small)
- `bin/adf_codec/test_adf_codec.py`: `test_round_trip_through_the_real_container`, `test_the_lossless_pair_gives_back_a_jira_description_identical_and_the_portable_pair_does_not`
- `bin/touch_predictions/test_touch_predictions.py`: `needs_docker`, `PredictedTest.test_a_list_written_in_markdown_and_read_back_from_a_jira_description_reads_as_written`, `PredictedTest.test_a_list_typed_in_jiras_editor_reads_as_its_files_and_parts`
- `bin/run_heavy/test_run_heavy.py`: `RunHeavy.test_a_docker_run_without_limits_gets_three_quarters_of_the_memory_split_across_the_slots` (small)
- `bin/machine_load/memory.py`: `read_memory` (small)
- `bin/do_epic/backend/protocol.py`: `EpicIssue` (small)
- `bin/do_epic/backend/fake.py`
- `bin/do_epic/backend/jira.py`: `FIELDS`, `JiraEpic.found`
- `bin/do_epic/backend/contract.py`
- `bin/do_epic/backend/test_jira.py`
### 401. Move loop-claude's cycle, judge, interrupt, tmux and routing into a package a second entry point drives, with loop-claude's behaviour unchanged.
### 427. Re-rank Jira's backlog to match an epic's ranking, moving only the issues the loop filed, so people's issues keep their rank.
do-epic runs on these, not on a copy (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Move the reusable modules into `bin/agent_cycle/`: `tmux`, `judge`, `interrupt`, `verdicts`, `retry`, `spend`, `worker`, `states`, `stop`, and the parts of `routing` that take a `ProjectRung` and a `Route`. Keep `routed_item`, `loop/`, `project/`, `escalation_mark` and `chunk_items` in `loop_claude`. Decouple `cycle/run.py`'s archive and `Chunk items:` handling, and `cycle/prompts.py`'s goals-file and `todo.md` names, behind parameters. The places the comprehension seats found hard here, `routing.py` `unfinished_route` and `cycle/judge.py` `quotes_checked`, must read no harder after the move.
Split from item 408 (`docs/decisions.md` → `do-epic: drives one Jira epic …`). `EpicStore` gains a rank call, in both backends and the contract tests. Lift `JiraPlan.rank_refusal` to a module function both stores call. Walk the target order: where the issue at a position isn't the target's, rank the target's just before it; the slots people's issues hold stay theirs. A rank Jira refuses stops the walk and is reported, since a wrongly ranked team backlog takes hours to restore.
Touches:
- `bin/loop_claude/tmux.py`
- `bin/loop_claude/cycle/judge.py`
- `bin/loop_claude/cycle/interrupt.py`
- `bin/loop_claude/cycle/retry.py`
- `bin/loop_claude/cycle/spend.py`
- `bin/loop_claude/cycle/worker.py`
- `bin/loop_claude/cycle/states.py`
- `bin/loop_claude/verdicts.py`
- `bin/loop_claude/stop.py`
- `bin/loop_claude/routing.py`
- `bin/loop_claude/cycle/run.py`: `Cycle`, `run_cycle`, `step`, `rule`
- `bin/loop_claude/cycle/prompts.py`: `QUOTE_SOURCES`, `ANSWER_DESTINATIONS`
- `bin/loop_claude/test_loop_claude.py`
- `bin/loop_claude/test_black_box.py`
- `bin/judge_replay/main.py`
- `bin/judge_replay/replay.py`
- `bin/judge_replay/archived_prompt.py`
- `bin/rung_replay/command.py`
- `bin/rung_replay/search.py`
- `README.md`: `` ### Packages under `bin/` `` (small)
### 408. Rank an epic's items by one weight chain, the epic's achieve goals, then code health, then the item's repo goals, then by Blocked by, and re-rank Jira's backlog to match, with people's issues keeping their rank.
Where the epic and a repo disagree, the epic wins (`docs/decisions.md` → `do-epic: drives one Jira epic …`). An item without a repo weighs only the epic's goals. Reuse `goal_weights` and `weight_of`, and `JiraPlan.rank_refusal` for the rank call. `plan/ranking.py` `score` is a place the seats found hard, so the combiner must not add a branch to it.
Touches:
- `bin/plan/ranking.py`: `weigh`, `weight_of` (small)
- `bin/plan/goals_file.py`: `goal_weights` (small)
- `bin/plan_store/jira_epic.py`: `JiraPlan.rank_refusal` (small)
- `bin/do_epic/backend/protocol.py`: `EpicStore` (small)
- `bin/do_epic/backend/fake.py`
- `bin/do_epic/backend/jira.py`
- `bin/do_epic/backend/contract.py`
- `bin/do_epic/ranking.py`
### 410. Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.
The lock that keeps do-epic and loop-claude apart is the per-project `starting` flock, shared by both (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Each chunk routes on its repo's model and ladder, a no-repo chunk on the machine setting's model. `loop/chunk_windows.py` `start_chunks` is a place the seats found hard: make it easier to read where it changes.
The lock that keeps do-epic and loop-claude apart is the per-project `starting` flock, shared by both (`docs/decisions.md` → `do-epic: drives one Jira epic …`). Each chunk routes on its repo's model and ladder, a no-repo chunk on the machine setting's model. `loop/chunk_windows.py` `start_chunks` is a place the seats found hard: make it easier to read where it changes. Where a do-epic cycle's worker, judge or human reads the driver's name, they read do-epic, never loop-claude: item 401 left `agent_cycle`'s own text naming loop-claude, since whether the markers that code matches (`TYPED_HERE`, `TRANSCRIPT_HEADING`) vary by driver depends on what do-epic calls itself and where it archives its cycles. The worker's prompt and the judge's rules share the phrase a worker asks for a higher rung with, so both take it from one place.
Touches:
- `bin/loop_claude/loop/chunk_windows.py`: `starting`, `start_chunks` (small)
- `bin/loop_claude/tmux.py`: `session_name` (small)
- `bin/agent_cycle/tmux.py`: `session_name` (small)
- `bin/do-epic`
- `bin/do_epic/main.py`
- `bin/do_epic/scheduler.py`
- `bin/agent_cycle/worker_prompts.py`: `TYPED_HERE`, `stepped_to` (small)
- `bin/agent_cycle/judge.py`: `TRANSCRIPT_HEADING`, `Reply.escalation` (small)
- `bin/agent_cycle/escalation_mark.py`: `STEP_LINE` (small)
- `bin/agent_cycle/interrupt.py`
- `bin/agent_cycle/stop.py`
### 416. Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.
@@ -171,7 +140,7 @@ Touches:
- `bin/loop_claude/project/records.py`: `read_records` (small)
- `bin/loop_claude/project/premises.py`: `read_premises` (small)
- `bin/loop_claude/cycle/judge.py`: `judge_prompt` (small)
- `bin/agent_cycle/judge.py`: `judge_prompt` (small)
- `bin/loop_claude/cycle/prompts.py`: `ANSWER_DESTINATIONS` (small)
- `skills/larv-review/SKILL.md`: `## 3. Passes` (small)
- `bin/do_epic/findings.py`
@@ -250,7 +219,7 @@ A plain `do-epic <key>` resumes all of them, as after a reboot (`docs/decisions.
Touches:
- `bin/loop_claude/tmux.py`: `WAITS`, `mark` (small)
- `bin/agent_cycle/tmux.py`: `WAITS`, `mark` (small)
- `bin/do_epic/status.py`
### 414. DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.
@@ -259,7 +228,7 @@ do-epic leaves the issue as the team filed it (`docs/decisions.md` → `do-epic:
Touches:
- `bin/loop_claude/direct_message.py`: `tell` (small)
- `bin/agent_cycle/direct_message.py`: `tell` (small)
- `bin/do_epic/human_tasks.py`
### 417. Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.
@@ -315,7 +284,7 @@ lilleman, 2026-11-11: do it on a timer, so an answer that comes in time doesn't
Probe first that `claude -p "/compact" --resume <id>` compacts a session: the Agent SDK documents `/compact` as a prompt, the CLI pages don't show it. Claude Code compacts idle interactive sessions itself ("Compacted while idle"), but not `-p` runs. Check: the cost entries of 20 chunks with an interrupt, before and after.
Touches:
- `bin/loop_claude/cycle/interrupt.py`: `interrupt`, `answered`, `typed_answer`, `WorkerSession`
- `bin/agent_cycle/interrupt.py`: `interrupt`, `answered`, `typed_answer`, `WorkerSession`
- `bin/loop_effects/effects.py`: `Effects`, `system_effects`
- `bin/claude_code/tokens.py`: `tokens_of` (small)
- `bin/claude_code/reply.py`: `claude_reply` (small)
@@ -334,7 +303,7 @@ Run it first as a report that kills nothing, and turn the kill on once its verdi
Touches:
- `bin/loop_claude/loop/stuck_windows.py`
- `bin/loop_claude/tmux.py`: `Listed`, `listed`
- `bin/agent_cycle/tmux.py`: `Listed`, `listed`
- `README.md`: `## Tools` (small)
### 365. Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.
@@ -393,12 +362,12 @@ One of 0.13.0's history ports, per lilleman's call of 2026-11-12.
### 339. Lower the reading cost of the files a chunk reads most before its first commit.
`reading-cost` printed `Rising:` on 2026-11-12: the last 5 chunks' median is 128,199 new input tokens before their first commit, the 5 before them 101,795. Read most over the last 5, as opens and searches: `todo.md` 34, `docs/decisions.md` 26, `README.md` 19, `skills/larv-review/SKILL.md` 13, `bin/loop_claude/routing.py` 8, `CHANGELOG.md` 6. The chunk that ships this runs `reading-cost --reset`.
`reading-cost` printed `Rising:` on 2026-11-12: the last 5 chunks' median is 128,199 new input tokens before their first commit, the 5 before them 101,795. Read most over the last 5, as opens and searches: `todo.md` 34, `docs/decisions.md` 26, `README.md` 19, `skills/larv-review/SKILL.md` 13, `bin/agent_cycle/routing.py` 8, `CHANGELOG.md` 6. The chunk that ships this runs `reading-cost --reset`.
Touches:
- `README.md`
- `skills/larv-review/SKILL.md`
- `bin/loop_claude/routing.py`
- `bin/agent_cycle/routing.py`
### 341. Hand each worker's claude a lower Read limit through `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`, kept only where replays of the archived review rounds find what two unchanged replays find.
@@ -411,7 +380,7 @@ loop-claude can hand it as it hands `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, and subag
The replay: `review-replay <pass> claude-opus-5-5 --read-limit` already replays a pass's archived rounds three times as archived and once at 5,000 tokens (`bin/review_replay/changes.py`, `bin/claude_code/output_limits.py`). Run it for the prose, stability, product-owner and principles rounds. Keeps quality where each pass finds every finding the two unchanged replays both find, or misses no more than the most an unchanged replay misses, as `--omit-claude-md` counts it. Keep it only where the replays' Read characters also fall; the archived runs hold each result. Then hand the variable over in `worker_environment` for what passes.
Touches:
- `bin/loop_claude/cycle/run.py`: `worker_environment` (small)
- `bin/agent_cycle/run.py`: `worker_environment` (small)
- `bin/loop_claude/loop/usage.py`: `HELP` (small)
- `bin/loop_claude/test_loop_claude.py`: `Cycles` (small), `HelpLimits` (small)
@@ -420,7 +389,7 @@ Touches:
153 `Judge cost:` entries total $109.76, a median of about $0.76 a verdict at every rung, and the cost follows the size of the records, not the transcript: about 76k characters in log and 188k in claude-config. In 224 of 251 recent verdicts (89%) the evidence sits in the worker's final message. A missed interrupt is the costly error, so the bar is zero changed interrupts and zero new rejections across the replay. The judge is about 4.5% of dollars, so the saving is small; each cycle also gets faster.
Touches:
- `bin/loop_claude/cycle/judge.py`: `Brief`, `judge_prompt`, `JUDGE_PROMPT_CHARS`
- `bin/agent_cycle/judge.py`: `Brief`, `judge_prompt`, `JUDGE_PROMPT_CHARS`
- `bin/loop_claude/project/records.py`: `read_records`
- `bin/judge_replay/main.py`: `rule` (small)
- `bin/judge_replay/replay.py`: `case_from` (small)
@@ -431,6 +400,10 @@ Touches:
Today a Jira detail edited in one line, or a Confluence record with one entry appended, is written back whole by adf-codec's portable pair, which drops each block's localId and the empty paragraphs Jira uses for spacing. A save whose text is the text a read showed already sends nothing (`docs/decisions.md` → `project config: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, …`). Match the saved markdown's top-level blocks against the held document's, each as the portable pair reads it, and send the held block where they match. The decision's limit on partial saves ends with this item.
### 425. Show on loop-claude's terminal why it doesn't start a chunk beside the next item, as chunk-preflight prints it.
`chunks_beside` names each item it refuses and why, such as an unreadable `Touches:` list, and chunk-preflight prints those lines, but loop-claude's `chunk_windows.may_start` keeps only `picked` and drops them, so idle slots show no reason. Found by item 424's product-owner review; a list a person edits in Jira's UI, or one filed before item 424, still reaches loop-claude unchecked.
### 367. Check that every write to a Jira plan leaves it ranked, as rule-hook's `todo-rank-check` checks `todo.md` today.
One of 0.13.0's history ports, per lilleman's call of 2026-11-12.
@@ -439,7 +412,7 @@ One of 0.13.0's history ports, per lilleman's call of 2026-11-12.
On 2026-11-18 lilleman ruled that the classifier's miss rate of about 1 in 100 decided is close enough to no missed interrupt (`docs/decisions.md` → `routing: the offline classifier may decide finished, since lilleman ruled a miss rate of about 1 in 100 decided close enough to none; the judge's model keeps every other verdict kind`).
Taking the item builds this: before the judge call, loop-claude runs the classifier trained on its archive over the worker's final message. Where the classifier decides finished, loop-claude skips the call. The classifier is re-trained as the archive grows. The judge call sits in `bin/loop_claude/cycle/run.py` → `rule`, a place the comprehension seats found hard, since the order of stamping, archiving and stepping matters across three functions: make it easier to read.
Taking the item builds this: before the judge call, loop-claude runs the classifier trained on its archive over the worker's final message. Where the classifier decides finished, loop-claude skips the call. The classifier is re-trained as the archive grows. The judge call sits in `bin/agent_cycle/run.py` → `rule`, a place the comprehension seats found hard, since the order of stamping, archiving and stepping matters across three functions: make it easier to read.
The judge's model still decides every verdict the classifier leaves, the escalation a worker quotes, and whether a release is ready to cut, since the replay didn't test the classifier on those.
@@ -496,7 +469,7 @@ The prose pass's replay under item 318's new bar, on 2026-11-12, qualified no ru
On 2026-11-08 the human answered notice only: the loop prints that the release is ready to cut and ends; no interrupt, and nothing waits in loop-inbox.
Releases are the human's, and `CLAUDE.md` → "Working loop" already ends the loop once a release is ready to cut, so the ask settles nothing. 15 interrupts in the archive ask whether the human will cut a release, and about 6 of the 45 interrupts from 2026-11-02 to 2026-11-10 said a release was ready to cut; log's 2.5.0 was asked twice within an hour on 2026-11-10. On 2026-11-08 one of the 4 questions waiting in `~/.local/state/loop-claude/` is such an ask, plainpages-plugin-fastjira's 0.3.0 since 2026-11-03. Today a release ready to cut opens claude's session at once (`bin/loop_claude/cycle/run.py` `ask`), and the loop stops if the human leaves it with nothing typed. The change also touches what an interrupt covers in `CLAUDE.md` → "Vocabulary". Where the change touches `ask`, make it easier to read, as the seats named it.
Releases are the human's, and `CLAUDE.md` → "Working loop" already ends the loop once a release is ready to cut, so the ask settles nothing. 15 interrupts in the archive ask whether the human will cut a release, and about 6 of the 45 interrupts from 2026-11-02 to 2026-11-10 said a release was ready to cut; log's 2.5.0 was asked twice within an hour on 2026-11-10. On 2026-11-08 one of the 4 questions waiting in `~/.local/state/loop-claude/` is such an ask, plainpages-plugin-fastjira's 0.3.0 since 2026-11-03. Today a release ready to cut opens claude's session at once (`bin/agent_cycle/run.py` `ask`), and the loop stops if the human leaves it with nothing typed. The change also touches what an interrupt covers in `CLAUDE.md` → "Vocabulary". Where the change touches `ask`, make it easier to read, as the seats named it.
### 171. Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.
@@ -511,16 +484,16 @@ Aim: one ambitious refactor of the areas below, sized so every mean reaches 7.0
Places the seats named, hardest first (`larv-review places`), Locality first:
- Locality, Self-sufficiency: `bin/release_plan/release_standing.py:176` `next_release`, with `:162` `carried`: the cut from a tag, a dated heading or `BEFORE_FIRST_RELEASE`, release names replayed from the plan's history, and renames meet in the `is_earliest` test at `:198`; `carried` is reapplied in `chunk_item` and in `chunk_preflight/choices.py` `planned`, one relying on `zip` keeping order. All eight seats named it; four would least want to change it.
- Locality: `bin/loop_claude/routing.py:116` `unfinished_route`, with `:131` `escalated_route`: five rungs, the unfinished count and the escalation mark, which spans `escalation_mark.py`, `judge.py`, `verdicts.py`, `route.py` and `reload.py`. Seven seats named it; the module table is what makes it readable.
- Locality: `bin/agent_cycle/routing.py:116` `unfinished_route`, with `:131` `escalated_route`: five rungs, the unfinished count and the escalation mark, which spans `escalation_mark.py`, `judge.py`, `verdicts.py`, `route.py` and `reload.py`. Seven seats named it; the module table is what makes it readable.
- Locality: `bin/chunk_pr/main.py:298` `merged`, with `:384` `levelled_and_finished` and `:407` `finished`: a loop around the queue turn binds `done` only under some `if ready` branches, the approval wait is a fall-through, and `finished` destructures five subprocess results by position.
- Locality: `skills/larv-review/SKILL.md:82` "Round cap" and `:90` "Re-entry", with `bin/review_rules/round_titles.py:45` and `:63` `past_cap`, `bin/rule_hook/round_cap.py:10` and `bin/larv_review/reviewer_header.py:73`: the round cap lives in five places, and SKILL.md's Done, Cap, Re-entry and Mechanical answers point at each other as prose.
- Locality: `bin/loop_claude/loop/chunk_windows.py:107` `start_chunks`: under one flock it checks the session's owner, splits running from stopped windows, computes the room, reads the plan with a fallback, gathers held items and filters again, with the limit applied a second time in `may_start`.
- Shape, Locality: `bin/release_plan/ranking.py:239` `score`, `:144` `weigh` and `:250` `weight_of`: every function forks on `SHAPE` versus `OLD_SHAPE`, and one Score depends on five inputs held in other files.
- Locality, Shape: `bin/plan_store/stores.py:1` and `bin/release_plan/todo_table.py:1`: `release_plan` and `plan_store` import each other, the plan has three names, and the goals file sits under `release_plan`.
- Shape: `bin/larv_review/plan.py:22` `scoring_run_due`, with `owed.py`, `unmeasured.py` and `scoring.py`: the scoring-run trigger is spread over four modules, three of whose names don't say it, in a flat 14-module package that mixes rounds, the comprehension check and its triggers.
- Self-sufficiency: `bin/loop_claude/cycle/judge.py:22` `INTERRUPT_RULES`, with `:197` `quotes_checked`: the judge's behaviour is held partly in prompt text and field metadata and partly in Python checks.
- Self-sufficiency: `bin/agent_cycle/judge.py:22` `INTERRUPT_RULES`, with `:197` `quotes_checked`: the judge's behaviour is held partly in prompt text and field metadata and partly in Python checks.
- Shape: `bin/plan_store/jira_epic.py:356` `revision_of`: indexes the untyped tuple `scores` at `:530` returns by position.
- Shape: `bin/loop_claude/cycle/run.py:55` `Cycle.todo`, `bin/loop_claude/hand_over.py:23` `hand_over` and `bin/release_plan/named_code.py:5`: names that say todo.md where the plan may be a Jira epic, a handover that is not the reload's, and a module with no code in it.
- Shape: `bin/agent_cycle/run.py:55` `Cycle.todo`, `bin/agent_cycle/hand_over.py:23` `hand_over` and `bin/release_plan/named_code.py:5`: names that say todo.md where the plan may be a Jira epic, a handover that is not the reload's, and a module with no code in it.
- Navigation, Shape: `README.md:197` the `bin/` package list: 74 entries at one level, with the README's list as the only index.
- Self-sufficiency: every seat names the decision-log titles that code cites for a reason (`routing.py:1`, `ranking.py:20`, `loop/routing_check.py:1`) as a cost; state each reason beside its constant and keep the citation as a footnote.
@@ -621,7 +594,7 @@ Start once 20 chunks have run under the rule. The rule is `READING_RULE` in `bin
### 51. Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.
"Functional core, imperative shell", in `principles/technical-principles.md`: `say` in `bin/loop_effects/effects.py` takes the effects but prints to stderr itself, and `retried` and the rest print through `say`. Two bare `print(file=sys.stderr)` calls remain outside them, in `bin/loop_claude/cycle/interrupt.py` and `bin/loop_claude/project/model_choice.py`. The tests swap the global stream.
"Functional core, imperative shell", in `principles/technical-principles.md`: `say` in `bin/loop_effects/effects.py` takes the effects but prints to stderr itself, and `retried` and the rest print through `say`. Two bare `print(file=sys.stderr)` calls remain outside them, in `bin/agent_cycle/interrupt.py` and `bin/loop_claude/project/model_choice.py`. The tests swap the global stream.
### 201. Save the human's tmux setups and restore them after a reboot, so work is up and running again quickly.
@@ -637,7 +610,7 @@ Weigh the widely used tmux-resurrect and tmux-continuum plugins against a script
### 267. Keep waiting when an interrupt gets an empty answer, at the terminal or in the claude opened for it, in place of stopping the loop.
11 runs in the archive ended with "Stopped: the human is needed to answer the question above, but the interrupt ended without anything typed", each leaving its chunk open until the human restarted the loop. That stop comes from `human_typed` in `bin/loop_claude/cycle/interrupt.py`, after the claude opened for `/talk` or for a release ready to cut ends with no human turn. An empty line at the terminal stops the loop the same way, in `typed_answer`. Item 268 removes one of the cases that opens claude.
11 runs in the archive ended with "Stopped: the human is needed to answer the question above, but the interrupt ended without anything typed", each leaving its chunk open until the human restarted the loop. That stop comes from `human_typed` in `bin/agent_cycle/interrupt.py`, after the claude opened for `/talk` or for a release ready to cut ends with no human turn. An empty line at the terminal stops the loop the same way, in `typed_answer`. Item 268 removes one of the cases that opens claude.
### 4. Name each chunk's archive folder by the chunk's start time, so `<key>/` lists chunks in the order they ran.
@@ -669,7 +642,7 @@ Found by review of PR #317. The black-box test, `bin/loop_claude/test_black_box.
### 265. Archive each wait that costs a chunk wall time, for a usage limit, low memory, a failed worker start or a heavy slot, with its start and end stamps, so goal 1.5's hours split waiting from work.
No record holds these waits today. An outcomes file holds verdicts, stops, step-ups and the judge's cost (`bin/transcript_archive/outcomes.py`), and `~/.local/state/run-heavy/` holds only the slots' lock files. loop-claude waits out a usage limit and low memory in `bin/loop_claude/cycle/retry.py`; run-heavy waits for a slot in `bin/run_heavy/`. A heavy slot's wait happens inside a worker's Bash call, so loop-claude doesn't see it; run-heavy would write it where the archive can find it.
No record holds these waits today. An outcomes file holds verdicts, stops, step-ups and the judge's cost (`bin/transcript_archive/outcomes.py`), and `~/.local/state/run-heavy/` holds only the slots' lock files. loop-claude waits out a usage limit and low memory in `bin/agent_cycle/retry.py`; run-heavy waits for a slot in `bin/run_heavy/`. A heavy slot's wait happens inside a worker's Bash call, so loop-claude doesn't see it; run-heavy would write it where the archive can find it.
### 169. Have rule-hook's `todo-rank-check` catch a `todo.md` that the same Bash call edits and then commits.
@@ -677,7 +650,7 @@ The hook judges a call before it runs, and `changed` in `bin/rule_hook/todo_chec
### 197. Let the human edit what they type at loop-claude's terminal questions with the arrow keys, so Left moves the cursor in place of printing `^[[D`.
`bin/loop_effects/effects.py` hands loop-claude Python's builtin `input`, and nothing under `bin/` imports `readline`, so the terminal gets no line editing: fixing a typo means erasing back to it. loop-claude asks two questions at its terminal. Both read through `effects.input`: the pick of the project's model, in `project/model_choice.py`'s `ask_for_model`, and the interrupt's answer, in `cycle/interrupt.py`'s `typed_answer`. Importing `readline` in `effects.py` gives `input` line editing, at two costs. It moves the prompt from stderr to stdout, while the question above it stays on stderr. `test_black_box.py` waits for the prompt on stderr. `readline`'s bracketed paste takes a pasted block whole, so an answer can hold several lines. `prompts.typed_answer` ends the answer at its first blank line, so the judge would read the rest of such a paste as loop-claude's words. The product-owner review of PR #308 raised the interrupt's case. lilleman, 2026-10-18: "Not super-important, but a bit irritating."
`bin/loop_effects/effects.py` hands loop-claude Python's builtin `input`, and nothing under `bin/` imports `readline`, so the terminal gets no line editing: fixing a typo means erasing back to it. loop-claude asks two questions at its terminal. Both read through `effects.input`: the pick of the project's model, in `project/model_choice.py`'s `ask_for_model`, and the interrupt's answer, in `agent_cycle/interrupt.py`'s `typed_answer`. Importing `readline` in `effects.py` gives `input` line editing, at two costs. It moves the prompt from stderr to stdout, while the question above it stays on stderr. `test_black_box.py` waits for the prompt on stderr. `readline`'s bracketed paste takes a pasted block whole, so an answer can hold several lines. `worker_prompts.typed_answer` ends the answer at its first blank line, so the judge would read the rest of such a paste as loop-claude's words. The product-owner review of PR #308 raised the interrupt's case. lilleman, 2026-10-18: "Not super-important, but a bit irritating."
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.