Leave a Jira description or a Confluence page as it is where a save hands back the text a read showed
CI / tests (pull_request) Successful in 3m1s

This commit is contained in:
2026-11-17 02:53:28 +01:00
parent 75ae8639ab
commit b7ec782282
6 changed files with 66 additions and 10 deletions
+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: converting the markdown back would drop the localIds and spacing paragraphs that the markdown a read shows leaves out."""
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_as_the_description_reads_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}})])
+13 -4
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 all three, so a Held's version holds them, as JSON."""
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,9 @@ class ConfluencePage:
seen = self.seen_of(over)
if isinstance(seen, Failure):
return seen
# The markdown a read shows drops the localIds and spacing paragraphs Confluence holds, so writing the text a read found back would lose them: leave the page alone.
if over is not None and seen.digest == digest_of(text):
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}")
@@ -98,7 +103,7 @@ class ConfluencePage:
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})")
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 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 +129,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()
+18 -2
View File
@@ -7,7 +7,7 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from record_store.confluence_page import ConfluencePage
from record_store.confluence_page import ConfluencePage, digest_of, Seen
from rest_client.json_request import ErrorAnswer
from failure import Failure
from record_store.held import Held
@@ -80,9 +80,25 @@ 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"}'))
self.assertEqual(store.write("- a decision\n", held.version), Held("- a decision\n", Seen(8, "Decisions", digest_of("- a decision\n")).token))
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.assertEqual([call[0] for call in self.confluence.calls], ["GET"])
self.assertEqual((self.confluence.version, self.confluence.value), (2, value))
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
+5
View File
@@ -24,6 +24,7 @@ Each project principle states one rule that the decisions below apply; their ent
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
- project config: a record may name a Confluence Cloud page as `confluence:` and its address, the loop reads and writes it as markdown, and a write never overwrites a save made since the loop's read
- 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: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, and a save that hands back the text it showed leaves the document as Jira or Confluence holds it
- 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: `tooling-on-host = true` lets a project with no container setup run its language runtime, package manager, tests and task runner on the host
@@ -323,6 +324,10 @@ Valid while the later fixes per finished chunk, which `score-outcomes` and the r
- **A store keeps no version: its caller hands each write the version it writes over.** lilleman chose this on 2026-11-16, when 0.11.0's release review found the version kept as the store's hidden state, which made a write rest on whichever read came before it. `project-record` keeps the version `open` read in a file beside its copy, `~/.local/state/project-record/<key>/<worktree>/<record>.version`, since `save` runs in a later process, and each save keeps the version it left for the next. Every other tool writes over the version its own read gave, so a read by another tool, such as larv-review's, never moves the version an edit in `project-record` rests on. The folder `<worktree>` is named for the worktree that ran `open`, and `open` removes the folders of worktrees git no longer lists, so a chunk's copy doesn't outlive its worktree.
- **The page holds ADF, which adf-codec converts both ways**, so a teammate reads the record as Confluence renders it. Where adf-codec cannot convert the markdown, the write fails with adf-codec's error. A node markdown cannot hold reads as text: a mention as its name, a macro as `_(<macro> not included)_`. So the next write replaces it with that text, and a record page should hold only what markdown can.
## project config: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, and a save that hands back the text it showed leaves the document as Jira or Confluence holds it
2026-11-17, claude, through item 391. Serves goal 1.6: a team's own spacing and block ids stay in its Jira and Confluence, and agents, the judge and people still read the text easily (goal 1.4's reading cost). adf-codec's lossless pair keeps each block's localId and Jira's spacing paragraphs, but wraps every block in `!adf:` marker lines, which triples a short detail's lines (larvit/adf-codec#185). So reads stay on the portable pair, and a save leaves the document alone where its text is the text a read showed: `JiraPlan.shows` compares a new detail with the description converted again, and `ConfluencePage` keeps the digest of the text it read in the version a write names. Valid while every edit replaces a whole document: an edit that changes one line still rewrites it by the portable pair, dropping the localIds and spacing paragraphs everywhere, until `todo.md` item 395 keeps each block the edit didn't change.
## project config: a tool that reads a file's commits says where it does not support that file, and the work goes on
2026-11-13, larv-review. Serves goal 1.6: a client's plan and records live in the config's folder, and the loop still runs there. A file the config puts outside the checkout has no commit in the project's history, so a tool that needs the file's commits cannot do its job for it. No such tool blocks the loop or a merge, and each says what it leaves undone:
+6 -1
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 395`
`Next ID = 396`
## Items
@@ -68,6 +68,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 as Jira or Confluence holds it, with its localId and spacing paragraphs.** | 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 |
@@ -577,6 +578,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 as Jira or Confluence holds it, with its localId and spacing paragraphs.
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, so every block loses its localId and Jira's spacing paragraphs go. A save whose text is unchanged already leaves the document alone (`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, as the portable pair reads each, and send the held block where they match. The decision's "Valid while" 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.