Answer prose round 1: 0 🔴, 6 🟡 (0 misread); reword the docstrings, the README entries and item 401's detail

This commit is contained in:
2026-11-18 17:07:03 +01:00
parent e6c72550a7
commit f62ea168fe
5 changed files with 10 additions and 9 deletions
+3 -3
View File
@@ -206,10 +206,10 @@ 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 of a headless claude worker and the judge of its transcript (`run.py`), with the judge, the interrupt, the tmux window and the routing of the worker's rung. An entry point hands it its own prompts and file names (`worker_prompts.py`) and its reading of the items a worker took in. `loop_claude` drives it, and `do_epic` will; it doesn't import either.
- `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`.
@@ -217,7 +217,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `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.
- `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 `agent_cycle`'s judge and verdicts, and `loop_claude`'s premises, records and prompt names.
- `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.
+3 -1
View File
@@ -128,12 +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, answer_destinations, which names where the worker may record an answer the human typed, 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
+2 -2
View File
@@ -1,6 +1,6 @@
"""The prompts that resume a worker with an answer to its question, worded with what the entry point driving the cycle supplies.
"""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, such as loop-claude, words the prompts of its own workflow and names the files of its project. WorkerPrompts holds those, so the cycle and the judge name none of them.
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
-1
View File
@@ -180,5 +180,4 @@ def rungs_held(route: Route, project: ProjectRung | None) -> str:
return "".join(f" {sentence}" for sentence in rung_sentences(route, project))
# What loop-claude supplies to the prompts of its cycles.
WORKER = WorkerPrompts(fresh, resumed, rungs_held, QUOTE_SOURCES, ANSWER_DESTINATIONS)
+2 -2
View File
@@ -83,7 +83,7 @@
### 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.
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/`, `chunk_items` and `cycle/prompts.py` in `loop_claude`. `escalation_mark`, `quotes`, `hand_over` and `direct_message` move too, although this item first kept `escalation_mark`: the judge, `routing` and `interrupt` import them, so keeping them would make `agent_cycle` import `loop_claude`, and a second entry point could not drive it alone. `cycle/run.py` moves as well; the archive was already behind `Cycle.project_archive`, a path the entry point hands in. 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.
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/`, `chunk_items` and `cycle/prompts.py` in `loop_claude`. `escalation_mark`, `quotes`, `hand_over` and `direct_message` move too, although this item first kept `escalation_mark`: the judge, `routing` and `interrupt` import them, so keeping them would make `agent_cycle` import `loop_claude`, and a second entry point could not drive it alone. `cycle/run.py` moves as well; its archive was already behind `Cycle.project_archive`, a path the entry point hands in. Put `cycle/run.py`'s `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.
Touches:
@@ -653,7 +653,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 `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. `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.