Quote the detail of each item that may join a chunk in chunk-preflight's facts, so a worker stops opening todo.md for it
CI / tests (pull_request) Successful in 4m38s

This commit is contained in:
2026-11-09 03:24:06 +01:00
parent 4593c2969a
commit 447653fda5
9 changed files with 27 additions and 12 deletions
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- `chunk-preflight` quotes the detail of each item that may join the chunk, so a worker no longer opens `todo.md` to read it.
- `command-patterns [<version>]` prints a table of the shell command patterns a release's chunks ran.
- `deploy-release --cut` reports each step as it finishes, waits for the checks `main`'s protection requires and names them, deletes the merged release branch, and ends on one line saying the release is cut.
- CI runs the test suite on every pull request, and `main` merges nothing until it passes.
+1 -1
View File
@@ -10,7 +10,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
- **When the next release has no items left and work has landed towards it, its release review is the chunk** (`larv-review` §3 → "Release review"). **Once that has merged and the release holds no item, the release is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix, or an item its release review filed, lands, into that release; never start a later release's items or plan a new one.
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that publishes nothing says so once.
- **Read the README's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and the items that may join it; read further only what they leave out. Otherwise run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes. `AGENTS.md` lists every decision's title. Read the entry under a title in `docs/decisions.md` only where the title leaves open what the chunk or the review needs.
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; open `todo.md` only for what they leave out. Otherwise run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes. `AGENTS.md` lists every decision's title. Read the entry under a title in `docs/decisions.md` only where the title leaves open what the chunk or the review needs.
- **Work one chunk at a time, and put every item that can share its review into it.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in `todo.md`, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in `todo.md` before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in `README.md`, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the README, and record as a choice only what the goal leaves open.
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the README's `## Audience`, picks it.
+1 -1
View File
@@ -50,7 +50,7 @@ def planned(todo: str | Failure, cut: LastCut, default: str) -> Plan | NoItem:
return NoItem(f"every item of release {version(pick.release)} in {where} waits." if pick.release is not None else f"{where}'s items table holds no item.")
details = item_details(todo)
detail = details.get(first.id, "") if isinstance(details, dict) else f"(todo.md's details cannot be read: {details.reason})"
return Plan(found, first, f"{first.tagline}\n\n{detail}".strip())
return Plan(found, first, f"{first.tagline}\n\n{detail}".strip(), details if isinstance(details, dict) else {})
def worktree_on(porcelain: str, branch: str) -> pathlib.Path | None:
+1
View File
@@ -42,6 +42,7 @@ def item_lines(default: str, item: ItemFacts) -> list[str]:
*bundled(item.plan),
*named_lines(item.named),
f"\nItem {first.id}'s tagline and detail:\n\n{quoted(item.plan.text)}",
*(f"\nItem {joining.id}'s detail:\n\n{quoted(item.plan.details[joining.id])}" for joining in bundle_candidates(item.plan.items, first) if item.plan.details.get(joining.id)),
*(f"\n{printed(shown, done)}" for shown, done in item.tools),
]
+2
View File
@@ -26,6 +26,8 @@ class Plan:
first: Item
# first's tagline and detail.
text: str
# Every item's detail by its ID; empty where todo.md's details cannot be read.
details: dict[int, str]
@property
def branch(self) -> str:
+1 -1
View File
@@ -34,7 +34,7 @@ todo.md as the default branch holds it, the plan loop-claude routes on. It print
them on a github.com origin, and else as tea does. No title reaches the output;
- the items of that release that a chunk taking the item may take too: those that are not
questions, that have R 5 or less, and that no item outside the chunk blocks; none where the
item's own R is above 5;
item's own R is above 5, each with its detail;
- each file or folder git tracks that the item's tagline or detail names in backticks, with a
file's lines or a folder's files, and the item's tagline and detail;
- where it made or continued the worktree, what `rank_todo.py --check todo.md`,
@@ -340,6 +340,14 @@ class Render(unittest.TestCase):
self.assertIn("item 7, L 1, E + I 2, S 1: **Do the thing after.**", said)
self.assertNotIn("item 8,", said)
def test_quotes_the_detail_of_each_item_that_may_join_the_chunk(self):
said = rendered(item_facts(TODO + "\n### 7. Do the thing after.\n\nTouch `src/other.py`.\n\nRun the e2e leg.\n\n### 8. Do the answered thing.\n\nNot quoted.\n"))
self.assertIn("Item 7's detail:\n\n> Touch `src/other.py`.\n> \n> Run the e2e leg.", said)
self.assertNotIn("Not quoted", said)
def test_quotes_no_detail_for_a_joining_item_that_has_none(self):
self.assertNotIn("Item 7's detail", rendered(item_facts()))
def test_states_the_items_worktree_or_why_none_was_made(self):
self.assertIn("/c/proj-item-3", rendered(item_facts()))
self.assertIn("none made: path taken", rendered(item_facts(worktree=Failure("none made: path taken"))))
+12
View File
@@ -1424,3 +1424,15 @@ Read most (opens and searches):
- `bin/larv_review/history_commands.py` 2
- `bin/larv_review/reviewer_header.py` 2
- `bin/review_replay/rounds.py` 2
## Reading cost, chunk 0d35c9a64c98, finished 2026-11-09T02:21:29Z
58201 new input tokens before the first commit.
Read most (opens and searches):
- `todo.md` 6
- `skills/larv-review/SKILL.md` 4
- `docs/decisions.md` 2
- `README.md` 1
- `bin/repo_checks/test_types.py` 1
-9
View File
@@ -14,7 +14,6 @@
|---|---|---|---|---|---|---|---|---|---|---|---|
| 277 | 0.7.0 | | question | **Map the size of the code an item names onto S, on a scale the human picks, and have `score-outcomes` print that S for the item being scored and for each finished item it lists.** | 3 | 2 | 2 | 5 | 4 | 1.1 by 4, 1.4 by 3 | 2.4 |
| 1 | 0.7.0 | | question | **Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.** | 1 | 2 | 1 | 2 | 1 | | 0.0 |
| 285 | 0.7.0 | | | **Cut a worker's opens and searches of `todo.md` from the median 7 per chunk to at most 3, by finding in the last five chunks' archived transcripts what each read was for and removing its cause.** | 2 | 2 | 3 | 5 | 3 | 1.4 by 4 | 1.6 |
| 281 | 0.7.0 | | | **Remove a merged chunk's worktree and branch and fast-forward the main checkout with one command.** | 3 | 2 | 3 | 6 | 3 | 1.4 by 2, 1.5 by 2 | 1.6 |
| 274 | 0.7.0 | | | **Let an item name a maintain goal it raises confidence in, such as a test leg that guards it, and weigh that move against the achieve goals in `bin/release_plan/ranking.py`.** | 2 | 2 | 3 | 5 | 4 | 1 by 3 | 1.1 |
| 286 | 0.7.0 | | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 3 | 2 | 2 | 5 | 5 | 1.4 by 4 | 1.0 |
@@ -71,14 +70,6 @@ It lives under `~/.claude`, which `.gitignore` keeps from the remote, so a lost
The README line covers the bench's transcripts in `workflow-bench/logs/` too (goal 3).
### 285. Cut a worker's opens and searches of `todo.md` from the median 7 per chunk to at most 3, by finding in the last five chunks' archived transcripts what each read was for and removing its cause.
Item 105 compared the five chunks before and after the `worker:` decision, merged 2026-10-13 at 06:49Z in 21b060e, matching chunks to PRs by finish time. Reading cost, the new input tokens before the first commit, rose: median 56,802 before and 136,132 after. The ranges, 46k to 172k and 50k to 140k, overlap. Review rounds per pass did not rise: 2.26 before and 1.52 after, among the five multi-pass chunks on each side.
Over those chunks the workers opened or searched `todo.md` 11 times before and 31 after, and `docs/decisions.md` 8 and 20. The last five chunks, per `reading-cost`, still opened or searched `todo.md` 34 times, a median of 7 per chunk, and `README.md` 6 times. `chunk-preflight` already puts the item's facts in the worker's prompt.
Some reads serve an edit, since Edit needs a Read first; items 278 and 279 remove those for removing and adding an item. This item follows them but does not wait for them. Find the rest in the transcripts under `~/.claude/loop-claude-transcripts/`, one `<id>.jsonl` per session. Name what each remaining read was for, and fix that cause, such as in `chunk-preflight` or the worker's prompt.
### 281. Remove a merged chunk's worktree and branch and fast-forward the main checkout with one command.
Audit of release 0.2.0's chunks (item 162): 31 chunks ran `git worktree remove`, `git branch -d` and `git pull --ff-only` by hand, 56 calls and about 5k command tokens. The program refuses a dirty main checkout, as `CLAUDE.md` → "Working with the codebase" says, and reports it.