Leave a Jira description or a Confluence page as it is where a save hands back the text a read showed #573

Merged
lilleman merged 10 commits from item-391 into main 2026-11-17 03:43:01 +01:00
9 changed files with 115 additions and 29 deletions
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- `todo-item edit --detail` and `project-record save` leave a Jira description or a Confluence page exactly as it is, with its block ids and spacing paragraphs, where the text saved is the text a read showed. An unedited save over a page a teammate saved since still refuses.
- Add `compress-archives`, which gzips each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them. The tools that read those folders read a gzipped file by its plain name. A new crontab line in the README's Install section runs it daily.
- review-replay and judge-replay keep each run, with its prompt, claude's exit code and stream, and the report they print, in a `replays/<tool>-<arguments>-<UTC stamp>/` folder of loop-claude's archive, so a replay that decided a rung can be checked and re-priced later; claude's json replies are now stream-json, whose last line is the reply.
- loop-claude's archive keeps each judge run's prompt and json reply in a judge/ folder beside its chunk's transcripts, and names the run on a `Judge run:` line of the outcome it produced; judge-replay replays a verdict on its archived prompt where the archive holds one.
+2 -2
View File
@@ -3,8 +3,8 @@
It runs @larvit/adf-codec, a Node package, in a throwaway container that holds node_shim/shim.mjs; the shim's header says what its exit status means.
adf-codec has two pairs of calls, and each function here names the one it runs:
- The lossless pair, `*_lossless`, for a document that already exists in Jira or Confluence and is edited and saved back. It keeps each block's localId and the empty paragraphs Jira uses for spacing, so a document read and saved unedited comes back identical.
- The portable pair, with no suffix, for new text written from scratch, and for markdown shown to a person. It drops the localId and the empty paragraphs, so saving a document that exists changes it.
- The portable pair, with no suffix, which the loop's tools use. It drops each block's localId and the empty paragraphs Jira uses for spacing, so saving a document read by it changes the document; a tool that saves one unedited sends nothing instead (`docs/decisions.md` → `project config: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, …`).
- The lossless pair, `*_lossless`, which keeps both, so a document read and saved unedited comes back identical. Its markdown wraps every block in `!adf:` marker lines, so no tool reads by it yet.
"""
import contextlib
import dataclasses
+9 -2
View File
@@ -185,6 +185,13 @@ class JiraPlan:
description = self.to_adf(detail)
return Failure(f"cannot convert the item's detail to a Jira description: {description.reason}") if isinstance(description, Failure) else description
def shows(self, issue: Issue, detail: str) -> bool:
"""Whether detail is the issue's description as a read shows it. An edit leaves such a description as Jira holds it, since converting the markdown back would drop each block's localId and Jira's spacing paragraphs."""
if issue.description is None:
return not detail.strip()
texts = self.to_markdown([issue.description])
return isinstance(texts, list) and texts[0].strip() == detail.strip()
def edit(self, id_: int, fields: dict[str, str], detail: str | None, comment: str | None = None) -> Written | Failure:
"""Sets the fields and the detail in one request, so Jira takes all of the edit or none, and then posts comment on the issue. `revision_of` says what an edit may set.
@@ -203,7 +210,7 @@ class JiraPlan:
if isinstance(revision, Failure):
return revision
body = revision.body
if detail is not None:
if detail is not None and not self.shows(issue, detail):
description = self.description_of(detail)
if isinstance(description, Failure):
return description
@@ -217,7 +224,7 @@ class JiraPlan:
return version
body = body | {"fields": body.get("fields", {}) | {"fixVersions": [{"name": version}]}}
url = f"{self.epic.site}/rest/api/3/issue/{key}"
edited = self.http("PUT", url, authorization, body)
edited = self.http("PUT", url, authorization, body) if body else None
if isinstance(edited, Failure):
return Failure(f"cannot edit {key}: {edited.reason}; {PERHAPS_EDITED.format(key=key)}")
if said is None:
+15 -1
View File
@@ -500,7 +500,7 @@ class Editing(unittest.TestCase):
return adf(markdown)
def edit(self, id_: int, fields: dict[str, str], detail: str | None = None, comment: str | None = None):
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, self.to_adf, scoring=Stated()).edit(id_, fields, detail, comment)
return jira_epic.JiraPlan(EPIC, self.env, self.http, lambda documents: [text_of(document) for document in documents], self.to_adf, scoring=Stated()).edit(id_, fields, detail, comment)
def writes(self) -> list[tuple[str, str, object]]:
"""Each request that changes Jira, in order."""
@@ -518,7 +518,21 @@ class Editing(unittest.TestCase):
self.edit(34, {"E": "3"})
self.assertEqual([body for _, _, body in self.writes()], [{"fields": {"summary": "Count every run."}}, {"properties": [{"key": "plan-item", "value": PROPERTY | {"E": 3}}]}])
def test_a_detail_unchanged_since_the_read_leaves_the_description_as_jira_holds_it(self):
# Jira's own spacing paragraph and localIds, which a description converted back from markdown would lose.
held = {"type": "doc", "version": 1, "content": [{"type": "paragraph", "attrs": {"localId": "p-1"}, "content": [{"type": "text", "text": "Why it counts."}]}, {"type": "paragraph", "attrs": {"localId": "p-2"}}]}
self.open = [issue("ABC-34", scores=PROPERTY, description=held)]
self.assertEqual(self.edit(34, {"L": "2"}, "Why it counts.\n"), Written(34))
self.assertEqual(self.edit(34, {}, "Why it counts."), Written(34))
self.assertEqual(self.writes(), [("PUT", f"{ISSUES}/ABC-34", {"properties": [{"key": "plan-item", "value": PROPERTY | {"L": 2}}]})])
def test_an_edited_detail_replaces_the_description(self):
self.open = [issue("ABC-34", scores=PROPERTY, description=adf("Why it counts."))]
self.edit(34, {}, "Why it counts twice.")
self.assertEqual(self.writes(), [("PUT", f"{ISSUES}/ABC-34", {"fields": {"description": adf("Why it counts twice.")}})])
def test_an_empty_detail_removes_the_description(self):
self.open = [issue("ABC-34", scores=PROPERTY, description=adf("Why it counts."))]
self.edit(34, {}, " \n")
self.assertEqual(self.writes(), [("PUT", f"{ISSUES}/ABC-34", {"fields": {"description": None}})])
+23 -5
View File
@@ -2,6 +2,7 @@
A write never overwrites a teammate's edit: it sends the version after the one held() read, and Confluence refuses it where someone saved the page since. The human then decides (lilleman, 2026-11-12)."""
import dataclasses
import hashlib
import json
import pathlib
import typing
@@ -20,9 +21,10 @@ SHAPE = "not in the shape Confluence Cloud's REST API version 2 documents"
@dataclasses.dataclass(frozen=True)
class Seen:
"""The page's version number and title as a read found them or a write left them. A write needs both, so a Held's version holds both, as JSON."""
"""The page's version number and title as a read found them or a write left them, and the digest of the markdown it found or sent. A write needs the version and title, and sends nothing where its text has that digest, so a Held's version holds all three, as JSON. The digest is None where the version came from a request that held no text."""
version: int
title: str
digest: str | None = None
@property
def token(self) -> str:
@@ -64,7 +66,7 @@ class ConfluencePage:
if not isinstance(body, str):
return Failure(f"{self.label} is {SHAPE}: it holds no body in atlas_doc_format")
text = self.converted(body)
return text if isinstance(text, Failure) else Held(text, seen.token)
return text if isinstance(text, Failure) else Held(text, Seen(seen.version, seen.title, digest_of(text)).token)
def converted(self, held: str) -> str | Failure:
"""The markdown of the body held, the JSON of an ADF document; empty where held is."""
@@ -86,6 +88,14 @@ class ConfluencePage:
seen = self.seen_of(over)
if isinstance(seen, Failure):
return seen
# A read's markdown leaves out the localIds and spacing paragraphs Confluence holds, so a write of the same text back would drop them: send nothing. Without a write Confluence answers no 409, so read the version to refuse where a teammate saved since.
if over is not None and seen.digest == digest_of(text):
current = self.fetched("")
if isinstance(current, Failure):
return current
if current[0].version != seen.version:
return self.saved_since(seen.version, f"Confluence holds version {current[0].version}")
return Held(text, over)
document = self.to_adf(text)
if isinstance(document, Failure):
return Failure(f"cannot convert the text for {self.label} to ADF: {document.reason}")
@@ -95,10 +105,14 @@ class ConfluencePage:
body = {"id": self.page.page_id, "status": "current", "title": seen.title, "body": {"representation": "atlas_doc_format", "value": json.dumps(document)}, "version": {"number": seen.version + 1}}
answer = self.http("PUT", self.url, authorization, body)
if isinstance(answer, ErrorAnswer) and answer.status == CONFLICT:
return Failure(f"someone saved {self.label} since the loop read version {seen.version} of it, so the loop didn't write it: never overwrite their edit, but ask the human what to do ({answer.reason})")
return self.saved_since(seen.version, answer.reason)
if isinstance(answer, Failure):
return Failure(f"cannot write {self.label}: {answer.reason}")
return Held(text, Seen(seen.version + 1, seen.title).token)
return Held(text, Seen(seen.version + 1, seen.title, digest_of(text)).token)
def saved_since(self, version: int, evidence: str) -> Failure:
"""The refusal of a write over version, which a teammate's save replaced, as evidence shows."""
return Failure(f"someone saved {self.label} since the loop read version {version} of it, so the loop didn't write it: never overwrite their edit, but ask the human what to do ({evidence})")
def fetched(self, query: str) -> tuple[Seen, object] | Failure:
"""The page's version and title, and the value of its body in atlas_doc_format where query asks for it; None where it doesn't."""
@@ -124,6 +138,10 @@ class ConfluencePage:
return fetched if isinstance(fetched, Failure) else fetched[0]
try:
held: typing.Any = json.loads(over)
return Seen(int(held["version"]), str(held["title"]))
return Seen(int(held["version"]), str(held["title"]), held.get("digest"))
except (ValueError, KeyError, TypeError) as failure:
return Failure(f"cannot read the version of {self.label} to write over, {over!r}: {failure}")
def digest_of(text: str) -> str:
return hashlib.sha256(text.encode("utf-8")).hexdigest()
+37 -5
View File
@@ -80,18 +80,50 @@ class ConfluencePageTest(ConfluenceCase):
store = self.new_store()
held = store.held()
assert isinstance(held, Held), held
self.assertEqual(store.write("- a decision\n", held.version), Held("- a decision\n", '{"version": 8, "title": "Decisions"}'))
written = store.write("- a decision\n", held.version)
assert isinstance(written, Held), written
self.assertEqual(written.text, "- a decision\n")
self.assertEqual(self.confluence.calls[-1], ("PUT", URL, AUTHORIZATION, {"id": PAGE.page_id, "status": "current", "title": "Decisions", "body": {"representation": "atlas_doc_format", "value": json.dumps(to_adf("- a decision\n"))}, "version": {"number": 8}}))
def test_saving_the_text_a_read_found_leaves_the_page_as_confluence_holds_it(self) -> None:
self.confluence.teammate_saves("- a decision\n")
value = self.confluence.value
held = self.new_store().held()
assert isinstance(held, Held), held
self.assertEqual(self.new_store().write(held.text, held.version), held)
self.assertNotIn("PUT", [call[0] for call in self.confluence.calls])
self.assertEqual(self.confluence.calls[-1], ("GET", URL, AUTHORIZATION, None))
self.assertEqual((self.confluence.version, self.confluence.value), (2, value))
def test_refuses_to_save_the_text_a_read_found_where_a_teammate_saved_since(self) -> None:
self.confluence.teammate_saves("- a decision\n")
held = self.new_store().held()
assert isinstance(held, Held), held
self.confluence.teammate_saves("- their decision\n")
written = self.new_store().write(held.text, held.version)
self.assertEqual(written, Failure(f"someone saved {PAGE.spelling} since the loop read version 2 of it, so the loop didn't write it: never overwrite their edit, but ask the human what to do (Confluence holds version 3)"))
self.assertNotIn("PUT", [call[0] for call in self.confluence.calls])
self.assertEqual(self.new_store().read(), "- their decision\n")
def test_an_unedited_save_fails_where_the_pages_version_cannot_be_read(self) -> None:
held = self.new_store().held()
assert isinstance(held, Held), held
store = ConfluencePage(PAGE, self.env, lambda *_: ErrorAnswer("GET /wiki/api/v2/pages/2293761 answered 404: Not Found", 404), to_markdown, to_adf)
self.assertEqual(store.write(held.text, held.version), Failure(f"cannot read {PAGE.spelling}: GET /wiki/api/v2/pages/2293761 answered 404: Not Found"))
def test_saving_an_edited_text_writes_the_page(self) -> None:
self.confluence.teammate_saves("- a decision\n")
held = self.new_store().held()
assert isinstance(held, Held), held
self.assertIsInstance(self.new_store().write("- another decision\n", held.version), Held)
self.assertEqual(self.new_store().read(), "- another decision\n")
def test_refuses_to_overwrite_a_teammates_save_since_the_version_it_is_handed_and_says_to_ask_the_human(self) -> None:
held = self.new_store().held()
assert isinstance(held, Held), held
self.confluence.teammate_saves("their edit\n")
written = self.new_store().write("my edit\n", held.version)
assert isinstance(written, Failure), written
self.assertIn("someone saved", written.reason)
self.assertIn("ask the human", written.reason)
self.assertIn(PAGE.spelling, written.reason)
self.assertEqual(written, Failure(f"someone saved {PAGE.spelling} since the loop read version 1 of it, so the loop didn't write it: never overwrite their edit, but ask the human what to do (PUT /wiki/api/v2/pages/{PAGE.page_id} answered 409: Version must be incremented on update. Current version is: 2)"))
self.assertEqual(self.new_store().read(), "their edit\n")
def test_keeps_no_version_itself_so_a_read_never_moves_the_version_a_write_names(self) -> None:
+5
View File
@@ -27,6 +27,7 @@ Each project principle states one rule that the decisions below apply; their ent
- project config: a tool that reads a file's commits says where it does not support that file, and the work goes on
- project config: `language` names the prose's language by its English name, and `commit-title`, `pull-request-title` and `branch` are brace templates over `{id}` and `{summary}`
- project config: `plan` may name a Jira Cloud epic as `jira:` and its address, the plan is its open child issues in backlog order, and an issue's number is the item's ID
- project config: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, and a save whose text is the text a read showed leaves the document as Jira or Confluence holds it
- project config: `tooling-on-host = true` lets a project with no container setup run its language runtime, package manager, tests and task runner on the host
- review: a release review fixes its findings in the release it reviews, and files under that release only a finding that needs a human answer, adds a feature or outlasts its five rounds
- review: a reviewer or comprehension seat that rules the work below standard may ask to rerun once, one rung up, in the same round; the ruling that stands is an escalation trigger for the worker unless the fix changes only prose, and never for the judge
@@ -380,6 +381,10 @@ Messages keep each file's usual name, such as `todo.md`, as its label, since the
- **`todo-item edit --comment` carries the comment, and a plan in a file takes the flag and keeps no comment**, so one command works in every project, as goal 1.3 asks. A bench of readers picked the spelling: three fresh readers, seated as the consultant who runs the loop in a client's project, each picked `--comment` over `--reason`, `--why` and `--because`. Only it says the text is posted where the team reads it, and `--reason` read as `--exempt`'s reason.
- **The store finishes an item with the transition that the config's `jira-finish-transition` names**, which must lead to the status `jira-finish-status` names, since each Jira workflow differs (lilleman's call, 2026-11-12); any open child of the epic may move. It refuses a status outside Jira's done status category: the read counts an issue as finished only in that category, so the item would stay in the plan. Where the issue's present status has no direct transition to the status `jira-finish-status` names, `todo-item finish` fails and a person moves the issue in Jira: the store never walks an issue through other statuses to reach it. lilleman answered on 2026-11-15: "If it is possible to move it to done without a transisiont, that should happen. If not, fail." The implementer read "without a transition" as "without a transition in between". `rank_todo.py` refuses to rank a plan in Jira, and its `--check` passes, since Jira's backlog ranks it; rule-hook's rank check skips it. Each read first asks Jira for the epic itself, since a search under an epic the account cannot see answers no issues, as a finished plan does.
## project config: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, and a save whose text is the text a read showed leaves the document as Jira or Confluence holds it
2026-11-17, claude, through item 391. Serves goal 1.6: a team's Jira and Confluence keep each block's localId and the empty paragraphs Jira uses for spacing, and agents, the judge and people still read the text easily, which keeps goal 1.4's reading cost down. adf-codec converts markdown and ADF by two pairs of calls, as `bin/adf_codec/convert.py` says. The lossless pair keeps the localIds and spacing paragraphs, but wraps every block in two `!adf:` marker lines: a five-line detail became 17 lines in a trial (larvit/adf-codec#185). The portable pair drops both. So the loop reads by the portable pair, and leaves a document alone where a save's text is the text a read showed. `JiraPlan.shows` compares a new detail with the description converted again. `ConfluencePage` keeps the digest of the text it read in the version a write names, and checks that the page still holds that version. Valid while the lossless markdown wraps every block in marker lines. A save that changes one line still rewrites the whole document by the portable pair, and so drops every localId and spacing paragraph, until `todo.md` item 395 keeps each block the save didn't change.
## project config: `tooling-on-host = true` lets a project with no container setup run its language runtime, package manager, tests and task runner on the host
2026-11-12, lilleman, through todo item 358. Serves goal 1.6: a legacy product may have no container setup, and the loop works in it without its owners adding one. `CLAUDE.md`'s container rule and the stability reviewer follow the setting. rule-hook checks only how a container starts, its memory limits and its image's pin, never where a runtime runs, so it needs no change. A decision may still put one tool on the host where the project has containers, as this repo's `bin/` decision does. Readers seated as the person who writes the config picked the key, 2 of 3. Valid while the loop runs on the machine that holds the checkout.
+17
View File
@@ -2396,3 +2396,20 @@ Read most (opens and searches):
- `bin/transcript_archive/test_transcript_archive.py` 3
- `skills/larv-review/SKILL.md` 3
- `bin/loop_claude/loop/close.py` 2
## Reading cost, chunk f7dbc8c79fac, finished 2026-11-17T01:44:51Z
100764 new input tokens before the first commit.
Read most (opens and searches):
- `docs/decisions.md` 12
- `README.md` 6
- `bin/judge_replay/main.py` 6
- `bin/judge_replay/test_judge_replay.py` 6
- `bin/review_replay/main.py` 5
- `bin/review_replay/test_review_replay.py` 4
- `bin/claude_code/test_claude_code.py` 3
- `bin/loop_claude/cycle/judge.py` 3
- `bin/rung_replay/test_rung_replay.py` 3
- `bin/claude_code/entries.py` 2
+6 -14
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 395`
`Next ID = 396`
## Items
@@ -15,7 +15,6 @@
| 387 | 0.12.0 | | | **Bind a project's rung to its ladder in one value, so the routing functions and `Cycle` take one argument for both.** | 3 | 1 | 3 | 5 | 5 | code health by 3 | 2.9 |
| 338 | 0.12.0 | | owner | **Script each step that 0.9.0's chunks repeated by hand and a program can compute, filing one item per step, and file this audit again for the next release.** | 1 | 2 | 1 | 2 | 2 | 1.4 by 3, 1.5 by 3 | 2.3 |
| 288 | 0.12.0 | | | **Point the two reading-cost decisions at code health and goal 1.4's counter-signal, in place of the goal 1.1 they cite.** | 1 | 2 | 1 | 2 | 1 | code health by 1, 1.4 by 1 | 2.2 |
| 391 | 0.12.0 | | | **Read and write a Jira epic issue's description and a Confluence record page through the lossless pair, so saving an unedited document leaves it unchanged.** | 3 | 2 | 3 | 6 | 5 | 1.6 by 6, 1.1 by 3 | 1.9 |
| 319 | 0.12.0 | | | **Start a fresh session with a brief of the chunk when a rung step changes the worker's model, in place of resuming the old session.** | 3 | 2 | 3 | 6 | 4 | 1.1 by 2, 1.4 by 2 | 1.2 |
| 309 | 0.12.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 |
| 299 | 0.12.0 | | | **Replay the archived judge verdicts through code rules and a classifier trained locally on the archive, and file an item for each verdict kind one of them decides with no missed interrupt.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3 | 1.0 |
@@ -67,6 +66,7 @@
| 193 | 0.14.0 | | | **Narrow `numbered`'s mark to `Mark` by a typed lookup in place of `typing.cast`, so a mark added to the regex but not the lookup fails at run time, and one added to the lookup but not `Mark` fails mypy.** | 1 | 1 | 3 | 3 | 1 | 1.1 by 2 | 0.9 |
| 194 | 0.14.0 | | | **Make `test_waits_out_a_usage_limit_which_ends_a_run_of_failures` expect a usage-limit wait independent of the wall-clock time that passes during the run.** | 1 | 1 | 1 | 1 | 1 | 1.1 by 2 | 0.9 |
| 265 | 0.14.0 | | | **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.** | 3 | 2 | 2 | 5 | 4 | 1.5 by 3 | 0.8 |
| 395 | 0.14.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 |
| 169 | 0.14.0 | | | **Have rule-hook's `todo-rank-check` catch a `todo.md` that the same Bash call edits and then commits.** | 3 | 1 | 3 | 5 | 3 | 1.1 by 2 | 0.7 |
| 197 | 0.14.0 | | | **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`.** | 2 | 2 | 3 | 5 | 2 | 1.5 by 1 | 0.4 |
| 1 | 0.15.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 |
@@ -106,18 +106,6 @@ The chunk that ships this item files a copy of this audit in release 0.15.0, the
Both `docs/decisions.md` entries under `reading cost: a rise is …` and `reading cost: larv-review measures each finished chunk …` open "Serves goal 1.1: comprehension …". No goal says that any more: code health (`CLAUDE.md` → "Shared goal") holds comprehension, and since PR #455 a rising reading cost is goal 1.4's first counter-signal. Raised by the stability review of PR #455 as a 🟢 outside that change.
### 391. Read and write a Jira epic issue's description and a Confluence record page through the lossless pair, so saving an unedited document leaves it unchanged.
`plan_store/jira_epic.py` reads an issue's description and writes it back on an edit, and `record_store/confluence_page.py` reads a page and saves it back; both use the portable pair, which drops each block's `localId` and the empty paragraphs Jira uses for spacing. `record_store/jira_description.py` only reads, to show a person: it stays on the portable pair.
Open before building: the lossless markdown is less readable than the portable one (upstream larvit/adf-codec#185), and agents and the judge read the plan's details from it. Decide how a detail stays readable, for example by reading lossless and showing a person a portable view. Test that an unedited issue and page save back identical. The item ships alone because its R is above 5.
Touches:
- `bin/plan_store/jira_epic.py`: `JiraPlan` (small), `description_of` (small)
- `bin/record_store/confluence_page.py`: `ConfluencePage` (small)
- `bin/plan_store/test_jira_epic.py`: `Editing`, `Filing`
- `bin/record_store/test_confluence_page.py`: `ConfluencePageTest`
### 319. Start a fresh session with a brief of the chunk when a rung step changes the worker's model, in place of resuming the old session.
On SWE-bench Verified with Haiku 4.5 and Opus 4.7, handing the strong model the weak model's transcript solved 69.2% at $1.61 a task; starting the strong model fresh solved 79.2% at $0.90 (arXiv 2608.24358, The Handoff Tax). A model switch also rereads the whole context uncached (Claude Code prompt caching docs). A worker that steps from Sonnet 5.5 to Opus 5.5 by `--resume` is the raw handoff; an effort-only step within one model keeps the cache and isn't. The escalated subagent, which starts fresh with the trigger's evidence, already follows the pattern that won.
@@ -553,6 +541,10 @@ Found by review of PR #317. The black-box test, `bin/loop_claude/test_black_box.
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.
### 395. Keep each block a save didn't change, with its localId, and the spacing paragraphs beside it as Jira or Confluence holds them.
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.
### 169. Have rule-hook's `todo-rank-check` catch a `todo.md` that the same Bash call edits and then commits.
The hook judges a call before it runs, and `changed` in `bin/rule_hook/todo_check.py` compares `todo.md` with the index and HEAD as they stand then. A call that edits `todo.md` and commits it, such as a heredoc script followed by `git commit`, passes unchecked: PR #296's commit 149108e did, and the override marker it carried was never logged. larv-review's gate still runs `rank_todo.py --check`, so an unranked plan stops at merge rather than at commit. A git pre-commit hook would see the staged file.