From ba21a1efcdc56c8b0d0188b58b3ff3bbdea6e90d Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Mon, 16 Nov 2026 16:12:36 +0100 Subject: [PATCH] =?UTF-8?q?Answer=20principles=20round=201:=202=20?= =?UTF-8?q?=F0=9F=94=B4,=209=20=F0=9F=9F=A1=20(0=20misread);=20explicit=20?= =?UTF-8?q?record=20versions=20in=20place=20of=20the=20Confluence=20store'?= =?UTF-8?q?s=20hidden=20state,=20the=20routing=20ruling=20filed=20as=20ite?= =?UTF-8?q?m=20393=20for=200.12.0,=20rule-hook=20catching=20heavy=20runs?= =?UTF-8?q?=20through=20uv,=20poetry,=20sudo=20and=20doas,=20one=20unrelea?= =?UTF-8?q?sed=20heading,=20one=20owner=20of=20the=20no-item=20message,=20?= =?UTF-8?q?typed=20Jira=20issues,=20a=20turn=20that=20gives=20its=20failur?= =?UTF-8?q?e=20as=20a=20value,=20outcome=20tests=20for=20the=20Atlassian?= =?UTF-8?q?=20client,=20an=20Emptied=20reason=20type,=20an=20injected=20cl?= =?UTF-8?q?ock=20and=20git=20in=20touch-predictions,=20and=20paired=20reco?= =?UTF-8?q?rd=20names?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4 +- bin/atlassian/test_client.py | 24 ++-- bin/chunk_pr/main.py | 45 ++++--- bin/command_lines/shell_command.py | 4 +- bin/deploy_release/cut.py | 5 +- bin/larv_review/history_commands.py | 22 ++-- bin/larv_review/owed.py | 4 +- bin/larv_review/plan.py | 9 +- bin/larv_review/test_larv_review.py | 7 +- bin/loop_claude/project/records.py | 12 +- bin/loop_claude/tmux.py | 12 +- bin/notifier/notify.py | 6 +- bin/plan/release.py | 2 + bin/plan_store/fakes.py | 6 +- bin/plan_store/jira_epic.py | 72 ++++++----- bin/plan_store/markdown_edits.py | 3 +- bin/plan_store/plans.py | 10 ++ bin/project_record/main.py | 4 +- bin/project_record/test_project_record.py | 5 +- bin/reading_cost/main.py | 13 +- bin/reading_cost/test_reading_cost.py | 3 +- bin/record_store/confluence_page.py | 74 +++++------- bin/record_store/contract.py | 17 ++- bin/record_store/fakes.py | 8 +- bin/record_store/held.py | 9 ++ bin/record_store/jira_description.py | 7 +- bin/record_store/stores.py | 77 ++++++++---- bin/record_store/test_confluence_page.py | 114 +++++++++--------- bin/record_store/test_stores.py | 8 +- bin/release_plan/release_standing.py | 12 +- bin/release_plan/test_release_standing.py | 2 + bin/rest_client/test_json_request.py | 9 +- bin/rule_hook/rules.py | 2 +- bin/rule_hook/test_rule_hook.py | 2 +- bin/todo_item/edits.py | 5 +- bin/todo_item/main.py | 16 +-- bin/touch_predictions/main.py | 17 +-- bin/touch_predictions/record.py | 7 +- .../test_touch_predictions.py | 11 +- docs/decisions.md | 8 +- todo.md | 9 +- 41 files changed, 406 insertions(+), 280 deletions(-) create mode 100644 bin/record_store/held.py diff --git a/README.md b/README.md index 4b810cf4..206678a4 100644 --- a/README.md +++ b/README.md @@ -196,11 +196,11 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a `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/`, `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. -- `atlassian/` holds what the Jira and Confluence backends share (`client.py`): one Atlassian account's credentials, the request they send, and each service's error messages. - `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. +- `atlassian/` holds what the Jira and Confluence backends share (`client.py`): one Atlassian account's credentials, the request they 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`. - `chunk_pr` imports `deploy_release`'s forge calls, and `forge_of` as `deploy_release` does. +- `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 `chunk_preflight`'s `forge_of`, which tells a GitHub origin from a Gitea one, and `release_plan`'s `release_standing`. - `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. diff --git a/bin/atlassian/test_client.py b/bin/atlassian/test_client.py index b553370a..d2e072de 100644 --- a/bin/atlassian/test_client.py +++ b/bin/atlassian/test_client.py @@ -3,14 +3,14 @@ import pathlib import sys import tempfile import unittest -import unittest.mock sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1])) from atlassian import client +from rest_client.json_request import ErrorAnswer from failure import Failure +from rest_client.test_json_request import Served -SEARCH = "https://acme.atlassian.net/rest/api/3/search/jql" AUTHORIZATION = "Basic " + base64.b64encode(b"me@example.com:s3cret").decode() @@ -26,11 +26,12 @@ class Credentials(unittest.TestCase): self.assertIsInstance(client.basic_auth(pathlib.Path("/nonexistent/acme.env")), Failure) -class Jira(unittest.TestCase): - def test_sends_each_request_through_the_shared_client_with_jiras_error_messages(self): - with unittest.mock.patch.object(client.json_request, "http_json", return_value={"issues": []}) as sent: - self.assertEqual(client.jira_json("POST", SEARCH, AUTHORIZATION, {"jql": "x"}), {"issues": []}) - sent.assert_called_once_with("POST", SEARCH, AUTHORIZATION, {"jql": "x"}, 30, client.jira_errors) +class Jira(Served): + def test_an_error_answer_fails_with_jiras_messages_and_its_status(self): + base = self.serve((400, b'{"errorMessages": ["One."], "errors": {"jql": "Two."}}')) + self.assertEqual(client.jira_json("POST", f"{base}/rest/api/3/search/jql", AUTHORIZATION, {"jql": "x"}), ErrorAnswer("POST /rest/api/3/search/jql answered 400: One.; Two.", 400)) + [(_, _, headers, _)] = self.server.got # type: ignore[attr-defined] + self.assertEqual(headers["Authorization"], AUTHORIZATION) def test_reads_jiras_messages_from_an_error_answer(self): cases = ( @@ -45,11 +46,10 @@ class Jira(unittest.TestCase): self.assertEqual(client.jira_errors(answer), message) -class Confluence(unittest.TestCase): - def test_sends_each_request_through_the_shared_client_with_confluences_error_messages(self): - with unittest.mock.patch.object(client.json_request, "http_json", return_value={}) as sent: - self.assertEqual(client.confluence_json("GET", "https://acme.atlassian.net/wiki/api/v2/pages/1", AUTHORIZATION, None), {}) - sent.assert_called_once_with("GET", "https://acme.atlassian.net/wiki/api/v2/pages/1", AUTHORIZATION, None, 30, client.confluence_errors) +class Confluence(Served): + def test_an_error_answer_fails_with_confluences_messages_and_its_status(self): + base = self.serve((409, b'{"errors": [{"status": 409, "title": "Version must be incremented"}]}')) + self.assertEqual(client.confluence_json("PUT", f"{base}/wiki/api/v2/pages/1", AUTHORIZATION, {}), ErrorAnswer("PUT /wiki/api/v2/pages/1 answered 409: Version must be incremented", 409)) def test_reads_confluences_messages_from_an_error_answer(self): self.assertEqual(client.confluence_errors({"errors": [{"status": 409, "title": "Version must be incremented"}, {"title": "and more"}, "odd"]}), "Version must be incremented; and more") diff --git a/bin/chunk_pr/main.py b/bin/chunk_pr/main.py index a27bfb8b..17dd9072 100644 --- a/bin/chunk_pr/main.py +++ b/bin/chunk_pr/main.py @@ -91,6 +91,7 @@ from chunk_preflight.gathered import Forge from chunk_preflight.choices import forge_of from project_config.main import located from project_config.settings import ProjectConfig +from plan_store.plans import says_no_item from project_config import templates BIN = pathlib.Path(__file__).resolve().parents[1] @@ -331,13 +332,8 @@ def merged(run: Run, config: Config, sleep: typing.Callable[[float], None] = tim file = pathlib.Path(queue[0]) / QUEUE pull_request = Merging(forge, number, method, str(base), required, waits) while True: - try: - with turn(file, number, sleep): - taken = merge_turn(pull_request, finishes, loaded, run, sleep) - except Held as held: - return Failure(f"the merge queue stayed held for {QUEUE_SECONDS // 60} minutes, last by pull request #{held.args[0] or '?'}, so this one took no turn; run chunk-pr merge again") - except OSError as failure: - return Failure(f"cannot take a turn in the merge queue, {file}: {failure.strerror}") + with turn(file, number, sleep) as untaken: + taken = untaken or merge_turn(pull_request, finishes, loaded, run, sleep) if not isinstance(taken, AwaitsApproval): return taken if isinstance(taken, Failure) else taken + absent # Out of the queue, so the project's other chunks merge while this one waits. @@ -388,20 +384,28 @@ def unplanned(run: Run, finishes: typing.Sequence[list[str]]) -> str | Failure: absent = [] for finish in finishes: shown = run([str(BIN / "todo-item"), "show", finish[0]]) - if isinstance(shown, Failure) and f"holds no item {finish[0]}" not in shown.reason: + if isinstance(shown, Failure) and not says_no_item(shown.reason, finish[0]): return shown absent += [finish[0]] if isinstance(shown, Failure) else [] return f" The plan held no item {', '.join(absent)} when merge began, so merge left the plan as it was there." if absent else "" -class Held(Exception): - """Other merges kept the queue for QUEUE_SECONDS; the argument is the number of the pull request that held it last.""" - - @contextlib.contextmanager -def turn(queue: pathlib.Path, number: str, sleep: typing.Callable[[float], None]) -> typing.Iterator[None]: - """Hold the project's merge queue as pull request number: wait until no other chunk-pr merge on this machine holds it, and free it on the way out, however that is. Raises Held where another one still holds it after QUEUE_SECONDS, and OSError where the file cannot be opened or locked.""" - fd = os.open(queue, os.O_RDWR | os.O_CREAT, 0o644) +def turn(queue: pathlib.Path, number: str, sleep: typing.Callable[[float], None]) -> typing.Iterator[Failure | None]: + """Hold the project's merge queue as pull request number: wait until no other chunk-pr merge on this machine holds it, and free it on the way out, however that is. Gives None while it holds the queue; a Failure, without the queue, where another merge still holds it after QUEUE_SECONDS or the file cannot be opened or locked.""" + try: + fd = os.open(queue, os.O_RDWR | os.O_CREAT, 0o644) + except OSError as failure: + yield Failure(f"cannot take a turn in the merge queue, {queue}: {failure.strerror}") + return + try: + yield held_turn(fd, queue, number, sleep) + finally: + os.close(fd) + + +def held_turn(fd: int, queue: pathlib.Path, number: str, sleep: typing.Callable[[float], None]) -> Failure | None: + """Lock the open queue file fd for pull request number and write its number there, for a merge that waits to name; None once held, else why it isn't.""" try: for waited in range(0, QUEUE_SECONDS + 1, QUEUE_POLL_SECONDS): try: @@ -409,13 +413,14 @@ def turn(queue: pathlib.Path, number: str, sleep: typing.Callable[[float], None] break except BlockingIOError: if waited == QUEUE_SECONDS: - raise Held(os.pread(fd, 20, 0).decode(errors="replace").strip()) from None + holder = os.pread(fd, 20, 0).decode(errors="replace").strip() + return Failure(f"the merge queue stayed held for {QUEUE_SECONDS // 60} minutes, last by pull request #{holder or '?'}, so this one took no turn; run chunk-pr merge again") sleep(QUEUE_POLL_SECONDS) os.ftruncate(fd, 0) os.pwrite(fd, number.encode(), 0) - yield - finally: - os.close(fd) + except OSError as failure: + return Failure(f"cannot take a turn in the merge queue, {queue}: {failure.strerror}") + return None def levelled_and_finished(run: Run, base: str, finishes: typing.Sequence[list[str]], config: ProjectConfig) -> str | Failure: @@ -444,7 +449,7 @@ def levelled_and_finished(run: Run, base: str, finishes: typing.Sequence[list[st def finished(run: Run, branch: str, finish: list[str], config: ProjectConfig) -> Failure | None: """Finish one plan item with `todo-item finish` and commit what that changed. An item the plan no longer holds was finished by an earlier run of merge, which may have stopped before its commit: so the plan and the changelog are committed either way.""" shown = run([str(BIN / "todo-item"), "show", finish[0]]) - if isinstance(shown, Failure) and f"holds no item {finish[0]}" not in shown.reason: + if isinstance(shown, Failure) and not says_no_item(shown.reason, finish[0]): return shown finishing = "" if isinstance(shown, Failure) else run([str(BIN / "todo-item"), "finish", *finish]) if isinstance(finishing, Failure): diff --git a/bin/command_lines/shell_command.py b/bin/command_lines/shell_command.py index 9da375b4..d853cec2 100644 --- a/bin/command_lines/shell_command.py +++ b/bin/command_lines/shell_command.py @@ -5,8 +5,8 @@ import re import shlex import typing -# Launchers that run the tool named later in their words, such as uvx --with pytest mutmut run. -LAUNCHERS = frozenset({"bunx", "env", "nice", "npx", "pipx", "pnpm", "run-heavy", "time", "timeout", "uvx", "yarn"}) +# Launchers that run the tool named later in their words, such as uvx --with pytest mutmut run, uv run mutmut run or sudo docker build. +LAUNCHERS = frozenset({"bunx", "doas", "env", "nice", "npx", "pipx", "pnpm", "poetry", "run-heavy", "sudo", "time", "timeout", "uv", "uvx", "yarn"}) HEREDOC = re.compile(r"<<-?[ \t]*([\"']?)([A-Za-z_]\w*)\1[^\n]*\n.*?^[ \t]*\2[ \t]*$", re.DOTALL | re.MULTILINE) ASSIGNMENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*=") OPERATOR = set("\n();&|<>") diff --git a/bin/deploy_release/cut.py b/bin/deploy_release/cut.py index 3066debc..c39a8fd6 100644 --- a/bin/deploy_release/cut.py +++ b/bin/deploy_release/cut.py @@ -3,7 +3,6 @@ Each step first checks whether an earlier run did it, so a rerun continues where the last run stopped. """ import pathlib -import re import shutil import sys import tempfile @@ -17,7 +16,7 @@ from plan_store.todo_md import FilePlan from record_store.stores import FileStore from deploy_release import forge from chunk_preflight.choices import forge_of -from plan.release import newest_tag, Release, version +from plan.release import newest_tag, Release, UNRELEASED_HEADING, version from project_config import templates @@ -211,7 +210,7 @@ def push_cut_commit(clone: str, ref: str, branch: str, named: str, title: str, r if isinstance(added := git("worktree", "add", "--quiet", "--detach", str(worktree), ref, cwd=clone), Failure): return added changelog = worktree / "CHANGELOG.md" - renamed, count = re.subn(r"^## Unreleased$", f"## {named}", changelog.read_text() if changelog.exists() else "", count=1, flags=re.MULTILINE) + renamed, count = UNRELEASED_HEADING.subn(f"## {named}", changelog.read_text() if changelog.exists() else "", count=1) if not count: return Failure(f"CHANGELOG.md on {ref} has no ## Unreleased section to rename") changelog.write_text(renamed) diff --git a/bin/larv_review/history_commands.py b/bin/larv_review/history_commands.py index f9c7cfe0..743bc9a8 100644 --- a/bin/larv_review/history_commands.py +++ b/bin/larv_review/history_commands.py @@ -10,6 +10,7 @@ from failure import Failure from plan_store.stores import file_plan, store as plan_store from larv_review.seats import FIRST_SEATS, scores, seats_file, SeatsFile from larv_review.scoring import floor_step, means, under_floor +from record_store.held import Held from project_config.main import located from record_store.stores import RecordStore, store from larv_review.scoring_setup import removed_setup @@ -145,22 +146,27 @@ def read_agreement(home: pathlib.Path) -> str | Failure: def history_file(home: pathlib.Path) -> tuple[RecordStore, str] | Failure: """The store the project's config names for its comprehension history, and the history's text, empty where there is none yet.""" + held = held_history(home) + return held if isinstance(held, Failure) else (held[0], held[1].text) + + +def held_history(home: pathlib.Path) -> tuple[RecordStore, Held] | Failure: + """The store the project's config names for its comprehension history, and the history as it stands, with the version a write over it names.""" config = located(None, home) if isinstance(config, Failure): return config history = store(config, "comprehension-history") - text = history.read() - return text if isinstance(text, Failure) else (history, text) + held = history.held() + return held if isinstance(held, Failure) else (history, held) def append(read: str, entry: str, home: pathlib.Path) -> str | Failure: """Appends entry and returns the line the tool prints; a Failure where the history already holds an entry on what the seats read.""" - read_history = history_file(home) + read_history = held_history(home) if isinstance(read_history, Failure): return read_history - history, text = read_history - if recorded(text, read): + history, held = read_history + if recorded(held.text, read): return Failure(f"{history.label} already holds an entry on {read}; record each ruling or run once") - if unwritten := history.write(appended(text, entry)): - return unwritten - return f"Appended to {history.label}." + written = history.write(appended(held.text, entry), held.version) + return written if isinstance(written, Failure) else f"Appended to {history.label}." diff --git a/bin/larv_review/owed.py b/bin/larv_review/owed.py index c5827841..a1e30dfb 100644 --- a/bin/larv_review/owed.py +++ b/bin/larv_review/owed.py @@ -1,7 +1,7 @@ import pathlib import typing -from larv_review.plan import EMPTIED_WORDS, plan_reasons +from larv_review.plan import Emptied, plan_reasons from review_rules.comprehension_history import entries from failure import Failure from git_cli.git_repo import file_at, git @@ -49,7 +49,7 @@ def owed_scoring_run(default: str, home: pathlib.Path, warn: typing.Callable[[st def shortfall(reasons: list[str], recorded: int) -> Failure | None: """Which scoring runs the plan's reasons call that recorded, the count the branch added to the history, leaves unrecorded; None where it holds them all.""" - needed = 2 if any(reason.endswith(EMPTIED_WORDS) for reason in reasons) else 1 + needed = 2 if any(isinstance(reason, Emptied) for reason in reasons) else 1 if recorded >= needed: return None return Failure(f"the chunk owes {needed} scoring run{'s' if needed > 1 else ''} and the branch's committed history records {max(recorded, 0)}: it {' and '.join(reasons)}. larv-review's SKILL.md → 'Scoring run' says how to run and record {'them' if needed > 1 else 'it'}{"; → 'Second run' says how the second is titled" if needed > 1 else ""}") diff --git a/bin/larv_review/plan.py b/bin/larv_review/plan.py index fef92794..bbe378b8 100644 --- a/bin/larv_review/plan.py +++ b/bin/larv_review/plan.py @@ -14,10 +14,14 @@ from record_store import stores from larv_review.unmeasured import unmeasured_cut -# The words that end the reason a chunk empties a release. Such a chunk is due two scoring runs; a chunk with any other reason, one. +# The words that end the reason a chunk empties a release; SKILL.md → "Second run" quotes them. EMPTIED_WORDS = "with no plan item" +class Emptied(str): + """The reason a chunk empties a release, which makes it due two scoring runs; a chunk with only other reasons is due one.""" + + def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], landed_release: Release | None, renamed: frozenset[Release], unmeasured: str | None = None) -> list[str] | Failure: """Why the plan calls a scoring run, empty when it does not. @@ -34,8 +38,7 @@ def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], lan reasons.append(f"follows {unmeasured}") for release in emptied(before, after, shipped, renamed): if work_landed(release, shipped, landed_release): - # SKILL.md → "Second run" keys on this wording. - reasons.append(f"leaves release {version(release)} {EMPTIED_WORDS}") + reasons.append(Emptied(f"leaves release {version(release)} {EMPTIED_WORDS}")) return reasons diff --git a/bin/larv_review/test_larv_review.py b/bin/larv_review/test_larv_review.py index 2182bec7..19089a50 100644 --- a/bin/larv_review/test_larv_review.py +++ b/bin/larv_review/test_larv_review.py @@ -15,7 +15,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1])) from larv_review.agreement import agreement_report, ruling_agreement, run_agreement from review_rules.comprehension_history import appended, entries, HistoryChange, latest_places, Place, recorded, ruling_entry, scoring_entry, ScoringRun, Seat -from larv_review.plan import checkout_plan, EMPTIED_WORDS, landed_towards, plan_reasons, scoring_run_due +from larv_review.plan import checkout_plan, Emptied, EMPTIED_WORDS, landed_towards, plan_reasons, scoring_run_due from review_rules import comprehension_history from project_config.test_project_config import configured from larv_review.ruling import counted, ruling, split, surplus, votes @@ -464,8 +464,11 @@ class Shortfall(unittest.TestCase): self.assertIn(EMPTIED_WORDS, (pathlib.Path(__file__).resolve().parents[2] / "skills" / "larv-review" / "SKILL.md").read_text(encoding="utf-8")) def test_a_chunk_that_empties_a_release_owes_two_runs_and_any_other_reason_one(self): - emptied = ["leaves release 0.1.0 with no plan item"] + emptied = [Emptied("leaves release 0.1.0 with no plan item")] floor = ["ships item 2, a floor item"] + # The type, not the words, makes a reason call two runs. + self.assertIn("owes 1 scoring run and", shortfall(["leaves release 0.1.0 with no plan item"], 0).reason) + self.assertIsInstance(scoring_run_due([item(1, (0, 1, 0))], [], [], (0, 1, 0), set())[0], Emptied) self.assertIn("owes 2 scoring runs and the branch's committed history records 1", shortfall(emptied + floor, 1).reason) self.assertIn("owes 1 scoring run and", shortfall(floor, 0).reason) self.assertIn("records 0:", shortfall(floor, -1).reason) diff --git a/bin/loop_claude/project/records.py b/bin/loop_claude/project/records.py index 5c058e5d..f2c28226 100644 --- a/bin/loop_claude/project/records.py +++ b/bin/loop_claude/project/records.py @@ -5,10 +5,10 @@ from project_config.main import located from loop_claude.project.text_file import read_utf8 from record_store.stores import store -# The records the judge reads beside the premises: these project files, then the human's rules below. -RECORD_FILES = ("AGENTS.md", "docs/decisions.md") -# The setting in the project's config that places each of RECORD_FILES. -RECORD_SETTINGS = ("working-rules", "decisions") +# The records the judge reads beside the premises, by the name that heads each, with the setting in the project's config that places it; then the human's rules below. +WORKING_RULES = ("AGENTS.md", "working-rules") +DECISIONS = ("docs/decisions.md", "decisions") +RECORD_FILES = (WORKING_RULES[0], DECISIONS[0]) # The human's rules, in the order the judge reads them: ~/.claude/CLAUDE.md, each .md file in ~/.claude/rules/, # then each .md file in the review standards folder the project's config sets. HUMAN_RULES_FILE = "CLAUDE.md" @@ -27,8 +27,8 @@ def read_records(root: str, home: pathlib.Path, claude_dir: pathlib.Path) -> str if isinstance(config, Failure): return Failure(f"{config.reason} - {CONSEQUENCE}.") rules = [claude_dir / HUMAN_RULES_FILE, *sorted((claude_dir / HUMAN_RULE_DIR).glob("*.md")), *sorted(config.paths["standards"].glob("*.md"))] - decisions = store(config, RECORD_SETTINGS[1]).read() - texts = [(RECORD_FILES[0], file_text(config.paths[RECORD_SETTINGS[0]])), (RECORD_FILES[1], Failure(f"{decisions.reason} - {CONSEQUENCE}.") if isinstance(decisions, Failure) else decisions)] + decisions = store(config, DECISIONS[1]).read() + texts = [(WORKING_RULES[0], file_text(config.paths[WORKING_RULES[1]])), (DECISIONS[0], Failure(f"{decisions.reason} - {CONSEQUENCE}.") if isinstance(decisions, Failure) else decisions)] texts += [(named(rule, home, claude_dir), file_text(rule)) for rule in rules] records = [] for heading, text in texts: diff --git a/bin/loop_claude/tmux.py b/bin/loop_claude/tmux.py index 1f2e0519..9b4f1a63 100644 --- a/bin/loop_claude/tmux.py +++ b/bin/loop_claude/tmux.py @@ -66,7 +66,7 @@ def listed(session: str, run: Tmux) -> list[Listed]: def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], first: bool, run: Tmux) -> Failure | None: - """Starts command in a new window of window's session, in cwd with env added to its environment, and leaves the client where it is. first makes the session too. A Failure says why tmux started none.""" + """Starts command in a new window of window's session, in cwd with env added to its environment, and leaves the client where it is. first makes the session too. A Failure says why tmux started none, or why it could not set the options of the window it started, which then runs without them.""" make = ["new-session", "-d", "-s", window.session] if first else ["new-window", "-d", "-t", f"={window.session}:"] variables = [flag for name, value in env.items() for flag in ("-e", f"{name}={value}")] # tmux reads a `;` that ends an argument as the end of the command, unless a backslash precedes it. @@ -74,12 +74,12 @@ def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], comman done = run([*make, "-n", window.name, "-c", cwd, *variables, "-P", "-F", "#{window_id}", "--", *words]) if done.returncode: return Failure(f"tmux could not start the window {window.target}: {done.stderr.strip() or f'it exited {done.returncode}'}") - if first: - # set-option and show-options read a target as a pane's, so `=session` alone names no session. - run(["set-option", "-t", f"={window.session}:", OWNER, cwd]) + # set-option and show-options read a target as a pane's, so `=session` alone names no session. + owned = run(["set-option", "-t", f"={window.session}:", OWNER, cwd]) if first else None # By the ID, since a window of the same name may still be closing. A loop that fails before the option is set closes its window, and its stop is still sent as a DM. - run(["set-option", "-w", "-t", done.stdout.strip(), "remain-on-exit", "failed"]) - return None + kept = run(["set-option", "-w", "-t", done.stdout.strip(), "remain-on-exit", "failed"]) + unset = next((option for option in (owned, kept) if option is not None and option.returncode), None) + return Failure(f"tmux started the window {window.target} but could not set its options: {unset.stderr.strip() or f'it exited {unset.returncode}'}") if unset else None def owner(session: str, run: Tmux) -> str: diff --git a/bin/notifier/notify.py b/bin/notifier/notify.py index ef5abd25..7c8af0bc 100644 --- a/bin/notifier/notify.py +++ b/bin/notifier/notify.py @@ -3,11 +3,11 @@ import dataclasses import pathlib import typing +from project_config.settings import CONFIG, Notifier, NOTIFIER, NOTIFIERS, ProjectConfig from failure import Failure from rest_client.json_request import Http from project_config.main import located from notifier import mattermost, slack -from project_config.settings import Notifier, NOTIFIER, NOTIFIERS, ProjectConfig # Sends one message, with the credentials already read. Sender = typing.Callable[[str], Failure | None] @@ -33,9 +33,9 @@ assert tuple(BACKENDS) == NOTIFIERS def sender_of(project: ProjectConfig, backends: typing.Mapping[Notifier, Backend[typing.Any]]) -> Sender | Failure: """A sender through the project's notifier in backends, with the credentials in its env file read. A Failure where the project names no notifier or its env file cannot be used.""" if project.notifier is None: - return Failure(f"{project.folder / 'config.toml'} sets no `{NOTIFIER}`; set `notifier` to {' or '.join(NOTIFIERS)}, and `env-file` to the file that holds that service's keys ({'; '.join(f'{name}: {', '.join(backend.keys)}' for name, backend in backends.items())})") + return Failure(f"{project.folder / CONFIG} sets no `{NOTIFIER}`; set `notifier` to {' or '.join(NOTIFIERS)}, and `env-file` to the file that holds that service's keys ({'; '.join(f'{name}: {', '.join(backend.keys)}' for name, backend in backends.items())})") if project.env_file is None: - return Failure(f"{project.folder / 'config.toml'} sets `{NOTIFIER}` but no `env-file`, the file that holds its credentials") + return Failure(f"{project.folder / CONFIG} sets `{NOTIFIER}` but no `env-file`, the file that holds its credentials") backend = backends[project.notifier] config = backend.read_config(project.env_file) if isinstance(config, Failure): diff --git a/bin/plan/release.py b/bin/plan/release.py index 53ccc116..b75b91fa 100644 --- a/bin/plan/release.py +++ b/bin/plan/release.py @@ -10,6 +10,8 @@ VERSION = r"[0-9]+\.[0-9]+\.[0-9]+" DATE_DIGITS = (4, 2, 2) DATED = re.compile(rf"({VERSION}) - " + "-".join(f"[0-9]{{{digits}}}" for digits in DATE_DIGITS)) TAG = re.compile(rf"v({VERSION})") +# The heading of CHANGELOG.md's section for news not yet released: ## Unreleased, or a heading that says unreleased, such as `## 0.6.0 (unreleased)`, as a project's own changelog may head it. +UNRELEASED_HEADING = re.compile(r"^## .*unreleased.*$", re.M | re.I) def release_of(version: str) -> Release: diff --git a/bin/plan_store/fakes.py b/bin/plan_store/fakes.py index d59d7d7a..ac74c552 100644 --- a/bin/plan_store/fakes.py +++ b/bin/plan_store/fakes.py @@ -2,7 +2,7 @@ import dataclasses from plan_store.markdown_edits import bold_cell, plain -from plan_store.plans import cells, Plan, Written +from plan_store.plans import cells, no_item, Plan, Written from failure import Failure from plan.todo_table import Item, parse_row, SHAPE, Table @@ -30,7 +30,7 @@ class MemoryPlan: def edit(self, id_: int, fields: dict[str, str], detail: str | None, comment: str | None = None) -> Written | Failure: if id_ not in self.rows: - return Failure(f"{self.label} holds no item {id_}") + return Failure(no_item(self.label, id_)) written = self.put(id_, self.rows[id_] | cells(fields), self.details.get(id_, "") if detail is None else detail) if comment is not None and isinstance(written, Written): self.comments.setdefault(id_, []).append(comment) @@ -38,7 +38,7 @@ class MemoryPlan: def finish(self, id_: int) -> Written | Failure: if self.fails or id_ not in self.rows: - return Failure(self.fails or f"{self.label} holds no item {id_}") + return Failure(self.fails or no_item(self.label, id_)) del self.rows[id_] self.details.pop(id_, None) return Written(id_) diff --git a/bin/plan_store/jira_epic.py b/bin/plan_store/jira_epic.py index cd27f17b..cf9c351b 100644 --- a/bin/plan_store/jira_epic.py +++ b/bin/plan_store/jira_epic.py @@ -12,7 +12,7 @@ from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused from atlassian.client import basic_auth, Http, jira_json, ToAdf, ToMarkdown from plan.todo_table import BLOCKED_BY, Item, item_fields, ItemFields, MOVES, SHAPE from plan_store.markdown_edits import bold_cell, plain, unfit_text -from plan_store.plans import cells, Plan, Written +from plan_store.plans import cells, no_item, Plan, Written from project_config.settings import Epic, Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION from failure import Failure from plan.release import parsed, Release, tagged @@ -60,7 +60,7 @@ class Issue: # The key of each issue this one "is blocked by". blockers: tuple[str, ...] # PROPERTY's value; an empty object where the issue holds none. - scores: object + scores: dict[str, typing.Any] @property def number(self) -> int: @@ -114,12 +114,10 @@ class JiraPlan: authorization = basic_auth(self.env_file) if isinstance(authorization, Failure): return authorization - issue_fields = filing.fields - if detail.strip(): - description = self.to_adf(detail) - if isinstance(description, Failure): - return Failure(f"cannot convert the item's detail to a Jira description: {description.reason}") - issue_fields = issue_fields | {"description": description} + description = self.description_of(detail) + if isinstance(description, Failure): + return description + issue_fields = filing.fields | ({"description": description} if description else {}) version = self.fix_version(filing.release, authorization) if isinstance(version, Failure): return version @@ -171,6 +169,22 @@ class JiraPlan: names = {name for version in versions if isinstance(version, dict) and isinstance(name := version.get("name"), str)} if isinstance(versions, list) else set() return next((name for name in (release, f"v{release}") if name in names), None) or Failure(f"the Jira project {project} has no Fix Version {release} or v{release}; create it in Jira, or name a release it has") + def child(self, id_: int, authorization: str) -> dict[str, typing.Any] | Failure: + """Item id_'s issue, as the epic's open children answer it; a Failure where none of them is item id_.""" + answered = children(self.epic, authorization, self.http) + if isinstance(answered, Failure): + return answered + key = f"{project_of(self.epic.key)}-{id_}" + found = next((raw for raw in answered if isinstance(raw, dict) and raw.get("key") == key), None) + return Failure(no_item(self.label, id_)) if found is None else found + + def description_of(self, detail: str) -> dict[str, typing.Any] | None | Failure: + """The Jira description that holds detail, as ADF; None for a blank detail, which leaves an issue without one.""" + if not detail.strip(): + return None + 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 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. @@ -178,24 +192,21 @@ class JiraPlan: authorization = basic_auth(self.env_file) if isinstance(authorization, Failure): return authorization - answered = children(self.epic, authorization, self.http) - if isinstance(answered, Failure): - return answered - key = f"{project_of(self.epic.key)}-{id_}" - raw = next((raw for raw in answered if isinstance(raw, dict) and raw.get("key") == key), None) - if raw is None: - return Failure(f"{self.label} holds no item {id_}") + raw = self.child(id_, authorization) + if isinstance(raw, Failure): + return raw issue = issue_of(raw) if isinstance(issue, Failure): return issue + key = issue.key revision = revision_of(issue, cells(fields), detail, comment) if isinstance(revision, Failure): return revision body = revision.body if detail is not None: - description = self.to_adf(detail) if detail.strip() else None + description = self.description_of(detail) if isinstance(description, Failure): - return Failure(f"cannot convert the item's detail to a Jira description: {description.reason}") + return description body = body | {"fields": body.get("fields", {}) | {"description": description}} said = self.to_adf(comment) if comment and comment.strip() else None if isinstance(said, Failure): @@ -221,12 +232,10 @@ class JiraPlan: authorization = basic_auth(self.env_file) if isinstance(authorization, Failure): return authorization - answered = children(self.epic, authorization, self.http) - if isinstance(answered, Failure): - return answered + raw = self.child(id_, authorization) + if isinstance(raw, Failure): + return raw key = f"{project_of(self.epic.key)}-{id_}" - if not any(isinstance(raw, dict) and raw.get("key") == key for raw in answered): - return Failure(f"{self.label} holds no item {id_}") url = f"{self.epic.site}/rest/api/3/issue/{key}/transitions" offered = self.http("GET", url, authorization, None) if isinstance(offered, Failure): @@ -292,7 +301,7 @@ def placing(answered: list[object], new: Item, value: float, scoring: ranking.Sc issue = issue_of(raw) if isinstance(issue, Failure): return issue - if not isinstance(issue.scores, dict) or issue.scores.get(FILED_BY[0]) != FILED_BY[1]: + if issue.scores.get(FILED_BY[0]) != FILED_BY[1]: continue scored = scores(issue.key, issue.scores) if isinstance(scored, Failure): @@ -322,8 +331,6 @@ def revision_of(issue: Issue, named: dict[str, str], detail: str | None, comment The summary, description and Fix Version of an issue a person filed are the team's, so there an edit may set only SCORED. Jira's screens don't show PROPERTY, so such an edit needs a comment, which tells the team. L, E, I and S are set together, so no issue is left partly scored. An issue the loop filed also keeps the label SECURITY in step with its Exempt. No edit changes a link.""" held = issue.scores - if not isinstance(held, dict): - return Failure(f"{issue.key}'s issue property {PROPERTY} is not a JSON object") if BLOCKED_BY in named: return Failure(f"the loop doesn't change an issue's links: link {issue.key} in Jira") own = held.get(FILED_BY[0]) == FILED_BY[1] @@ -419,14 +426,19 @@ def children(epic: Epic, authorization: str, http: Http) -> list[object] | Failu def issue_of(raw: object) -> Issue | Failure: """The issue in one entry of the search's answer, or which issue is not in the shape Jira documents, and how.""" key = raw.get("key") if isinstance(raw, dict) else None - if not isinstance(key, str) or not ISSUE_KEY.fullmatch(key): + if not isinstance(raw, dict) or not isinstance(key, str) or not ISSUE_KEY.fullmatch(key): return Failure("the search answered an issue without an issue key") + # The answer's nested fields are read as Jira documents them; one missing or of another type ends the read here, as a Failure, so no later step meets it. try: - fields = typing.cast(dict[str, typing.Any], raw)["fields"] + fields = raw["fields"] blockers = tuple(link["inwardIssue"]["key"] for link in fields["issuelinks"] if "inwardIssue" in link and link["type"]["inward"] == "is blocked by") - issue = Issue(key, fields["summary"].strip(), fields["description"], tuple(version["name"] for version in fields["fixVersions"]), blockers, typing.cast(dict[str, typing.Any], raw).get("properties", {}).get(PROPERTY, {})) + held = raw.get("properties", {}).get(PROPERTY, {}) + summary, description, versions = fields["summary"].strip(), fields["description"], tuple(version["name"] for version in fields["fixVersions"]) except (AttributeError, KeyError, TypeError) as failure: return Failure(f"{key} is not in the shape Jira Cloud's REST API version 3 documents: {failure!r}") + if not isinstance(held, dict): + return Failure(f"{key}'s issue property {PROPERTY} is not a JSON object") + issue = Issue(key, summary, description, versions, blockers, held) if not isinstance(issue.description, dict | None) or not all(isinstance(name, str) for name in issue.fix_versions + issue.blockers) or not all(ISSUE_KEY.fullmatch(blocker) for blocker in issue.blockers): return Failure(f"{key} is not in the shape Jira Cloud's REST API version 3 documents: its description, a Fix Version's name or a linked issue's key holds another kind of value") return issue @@ -481,9 +493,7 @@ def earliest_release(names: tuple[str, ...]) -> Release | None: return min(releases, default=None) -def scores(key: str, held: object) -> ItemFields | Failure: +def scores(key: str, held: dict[str, typing.Any]) -> ItemFields | Failure: """The scores, Moves and Exempt that an issue's PROPERTY value holds, each in the format the items table of a todo.md takes.""" - if not isinstance(held, dict): - return Failure(f"{key}'s issue property {PROPERTY} is not a JSON object") named = {name: str(value) for name, value in held.items() if name in (*SHAPE.score_columns, MOVES, "Exempt")} return item_fields(named, f"item {key}") diff --git a/bin/plan_store/markdown_edits.py b/bin/plan_store/markdown_edits.py index 5d7d816e..67075946 100644 --- a/bin/plan_store/markdown_edits.py +++ b/bin/plan_store/markdown_edits.py @@ -3,6 +3,7 @@ import re from plan.todo_table import cells, detail_heading, DETAILS, item_details, items_table, Table, tagline_text from failure import Failure +from plan_store.plans import no_item from plan.ranking import stated # A line that would end ## Details (##) or could open another item's detail (###). @@ -113,7 +114,7 @@ def row_index(table: Table, id_: int, label: str) -> int | Failure: return found if found[0] == str(id_): return at - return Failure(f"{label} holds no item {id_}") + return Failure(no_item(label, id_)) def held_table(lines: list[str], label: str) -> Table | Failure: diff --git a/bin/plan_store/plans.py b/bin/plan_store/plans.py index 8c0521f9..8dd38ab0 100644 --- a/bin/plan_store/plans.py +++ b/bin/plan_store/plans.py @@ -54,6 +54,16 @@ class PlanStore(typing.Protocol): """Removes item id_ with its detail.""" +def no_item(label: str, id_: int | str) -> str: + """What every store says of an item id_ that the plan label names doesn't hold. `chunk-pr merge` reads `todo-item show`'s answer by it, through says_no_item.""" + return f"{label} holds no item {id_}" + + +def says_no_item(reason: str, id_: int | str) -> bool: + """Whether a failure's reason, such as `todo-item show`'s, says the plan doesn't hold item id_, as no_item words it.""" + return no_item("", id_) in reason + + def cells(fields: dict[str, str]) -> dict[str, str]: """fields by the items table's column names.""" unknown = set(fields) - set(FIELDS) diff --git a/bin/project_record/main.py b/bin/project_record/main.py index b6754166..cf2c56d7 100644 --- a/bin/project_record/main.py +++ b/bin/project_record/main.py @@ -70,9 +70,9 @@ def performed(config: ProjectConfig, command: str, name: str, home: pathlib.Path def opened(config: ProjectConfig, name: str, home: pathlib.Path) -> tuple[RecordStore, pathlib.Path]: - """The store of the record called name, and the copy it gets where it isn't kept as a file. A store that keeps the version it read, for a later save, keeps it beside the copy.""" + """The store of the record called name, and the copy it gets where it isn't kept as a file. `local_file` keeps the version beside the copy, for a later save.""" copy = home / COPIES / config.key / worktree_folder(config.top) / f"{name}.md" - return (goals_store(config) if name == GOALS else store(config, name, copy.with_suffix(".version"))), copy + return (goals_store(config) if name == GOALS else store(config, name)), copy def worktree_folder(top: pathlib.Path) -> str: diff --git a/bin/project_record/test_project_record.py b/bin/project_record/test_project_record.py index da07b45d..5a83f5fb 100644 --- a/bin/project_record/test_project_record.py +++ b/bin/project_record/test_project_record.py @@ -25,13 +25,12 @@ def worktree_config(top: str, **kept: Page) -> ProjectConfig: class Opened(unittest.TestCase): - def test_a_record_on_a_confluence_page_keeps_the_version_it_read_beside_its_copy(self): + def test_a_record_on_a_confluence_page_gets_a_copy_in_a_folder_of_its_worktree(self): page = Page("https://acme.atlassian.net", "2293761", "confluence:https://acme.atlassian.net/wiki/spaces/ENG/pages/2293761") record, copy = main.opened(worktree_config("/code/acme", decisions=page), "decisions", pathlib.Path("/home/me")) self.assertEqual((copy.parent.parent, copy.name), (COPIES, "decisions.md")) self.assertRegex(copy.parent.name, r"^acme-[0-9a-f]{8}$") - assert isinstance(record, ConfluencePage), record - self.assertEqual(record.kept, copy.with_suffix(".version")) + self.assertIsInstance(record, ConfluencePage) def test_the_goals_file_opens_through_the_goals_store(self): record, copy = main.opened(worktree_config("/code/acme"), "goals-and-audience", pathlib.Path("/home/me")) diff --git a/bin/reading_cost/main.py b/bin/reading_cost/main.py index 8f32acda..bed9a5d0 100644 --- a/bin/reading_cost/main.py +++ b/bin/reading_cost/main.py @@ -73,11 +73,11 @@ def main(argv: list[str]) -> int: def update(record: RecordStore, archive: pathlib.Path, checkout: Checkout, home: str, reset_at: str | None) -> Updated | Failure: - text = record.read() - if isinstance(text, Failure): - return text + held = record.held() + if isinstance(held, Failure): + return held # An empty record starts with its title. - text = text or "# Reading cost\n" + text = held.text or "# Reading cost\n" figures = new_figures(text, archive, checkout, home) if isinstance(figures, Failure): return figures @@ -86,9 +86,8 @@ def update(record: RecordStore, archive: pathlib.Path, checkout: Checkout, home: readings = readings_of(text) if isinstance(readings, Failure): return readings - if marks and (unwritten := record.write(text)): - return unwritten - return Updated(len(figures), readings) + written = record.write(text, held.version) if marks else None + return written if isinstance(written, Failure) else Updated(len(figures), readings) def new_figures(record: str, archive: pathlib.Path, checkout: Checkout, home: str) -> list[str] | Failure: diff --git a/bin/reading_cost/test_reading_cost.py b/bin/reading_cost/test_reading_cost.py index dafe4be9..a58e1985 100644 --- a/bin/reading_cost/test_reading_cost.py +++ b/bin/reading_cost/test_reading_cost.py @@ -19,6 +19,7 @@ from reading_cost.measure import Checkout, Reading from failure import Failure from reading_cost import figures, main, measure from transcript_archive.read import finished_chunks, FinishedChunk +from record_store.held import Held from test_env import isolated_env from record_store.fakes import MemoryStore from transcript_archive import outcomes @@ -237,7 +238,7 @@ class Located(unittest.TestCase): class Update(unittest.TestCase): def test_fails_where_the_record_refuses_the_write(self): class Unwritable(MemoryStore): - def write(self, text: str) -> Failure | None: + def write(self, text: str, over: str | None = None) -> Held | Failure: return Failure("the wiki is down") archive = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) diff --git a/bin/record_store/confluence_page.py b/bin/record_store/confluence_page.py index 87c0d892..e984abbf 100644 --- a/bin/record_store/confluence_page.py +++ b/bin/record_store/confluence_page.py @@ -1,6 +1,6 @@ """A record kept on one Confluence Cloud page, read and written as markdown over Confluence's REST API version 2, with the credentials of the config's env-file, and converted by the adf-codec shim. -A write never overwrites a teammate's edit: it sends the version it read, and Confluence refuses it where someone saved the page since. The human then decides (lilleman, 2026-11-12).""" +A write never overwrites a teammate's edit: it sends the version it is handed, the one held() read, and Confluence refuses it where someone saved the page since. The human then decides (lilleman, 2026-11-12). The store keeps no version itself: its caller hands each write the version, as a Held's, and keeps the one the write leaves (lilleman, 2026-11-16).""" import dataclasses import json import pathlib @@ -10,8 +10,8 @@ from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused from atlassian.client import basic_auth, confluence_json, Http, ToAdf, ToMarkdown from rest_client.json_request import ErrorAnswer from failure import Failure +from record_store.held import Held from project_config.settings import Page -from text_files.file_writes import replace_file # What Confluence answers to a write whose version isn't the one after the version it holds. CONFLICT = 409 @@ -20,23 +20,23 @@ 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 the store last read or wrote them. A write needs both.""" + """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.""" version: int title: str + @property + def token(self) -> str: + return json.dumps(dataclasses.asdict(self)) + @dataclasses.dataclass class ConfluencePage: - """The text of page as markdown, read and written with the credentials env_file holds. - - kept is a file that keeps the version the store read for a later process, such as `project-record save` after `project-record open`; None keeps it only in memory.""" + """The text of page as markdown, read and written with the credentials env_file holds.""" page: Page env_file: pathlib.Path - kept: pathlib.Path | None = None http: Http = confluence_json to_markdown: ToMarkdown = adfs_to_markdown to_adf: ToAdf = markdown_to_adf - seen: Seen | None = None @property def label(self) -> str: @@ -52,18 +52,19 @@ class ConfluencePage: def read(self) -> str | Failure: """The page's text as markdown; empty where the page is.""" + held = self.held() + return held if isinstance(held, Failure) else held.text + + def held(self) -> Held | Failure: + """The page's text as markdown, with its version and title as the version a write over it names.""" answer = self.fetched("?body-format=atlas_doc_format") if isinstance(answer, Failure): return answer - seen, held = answer - if not isinstance(held, str): + seen, body = answer + if not isinstance(body, str): return Failure(f"{self.label} is {SHAPE}: it holds no body in atlas_doc_format") - text = self.converted(held) - if isinstance(text, Failure): - return text - # Kept only once the text is in hand: a version kept for a read that failed would let a later write overwrite the save it saw. - unkept = self.keep(seen) - return unkept or text + text = self.converted(body) + return text if isinstance(text, Failure) else Held(text, seen.token) def converted(self, held: str) -> str | Failure: """The markdown of the body held, the JSON of an ADF document; empty where held is.""" @@ -80,14 +81,9 @@ class ConfluencePage: return Failure(f"cannot convert {self.label} to markdown: {texts.reason}") return texts[0] - def write(self, text: str) -> Failure | None: - """Replaces the page's text with text, as the version after the one the store read. Where the store hasn't read the page, it replaces the page as it stands.""" - seen = self.seen or self.recalled() - if seen is None: - fetched = self.fetched("") - if isinstance(fetched, Failure): - return fetched - seen = fetched[0] + def write(self, text: str, over: str | None = None) -> Held | Failure: + """Replaces the page's text with text, as the version after over, the one held() gave. Where over is None, it replaces the page as it stands.""" + seen = self.seen_of(over) if isinstance(seen, Failure): return seen document = self.to_adf(text) @@ -102,7 +98,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 self.keep(Seen(seen.version + 1, seen.title)) + return Held(text, Seen(seen.version + 1, seen.title).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.""" @@ -121,25 +117,13 @@ class ConfluencePage: adf = body.get("atlas_doc_format") if isinstance(body, dict) else None return Seen(number, title), adf.get("value") if isinstance(adf, dict) else None - def keep(self, seen: Seen) -> Failure | None: - self.seen = seen - if self.kept is None: - return None + def seen_of(self, over: str | None) -> Seen | Failure: + """The version and title a write sends: those over holds, else the page's as it stands.""" + if over is None: + fetched = self.fetched("") + return fetched if isinstance(fetched, Failure) else fetched[0] try: - self.kept.parent.mkdir(parents=True, exist_ok=True) - except OSError as failure: - return Failure(f"cannot write {self.kept}: {failure.strerror}") - unwritten = replace_file(self.kept, json.dumps(dataclasses.asdict(seen)).encode()) - return Failure(f"cannot write {self.kept}: {unwritten.reason}") if unwritten else None - - def recalled(self) -> Seen | Failure | None: - """The version and title the file kept holds; None where kept is None or names no file.""" - if self.kept is None: - return None - try: - held: typing.Any = json.loads(self.kept.read_text(encoding="utf-8")) + held: typing.Any = json.loads(over) return Seen(int(held["version"]), str(held["title"])) - except FileNotFoundError: - return None - except (OSError, ValueError, KeyError, TypeError) as failure: - return Failure(f"cannot read the version of {self.label} that {self.kept} keeps: {failure}") + except (ValueError, KeyError, TypeError) as failure: + return Failure(f"cannot read the version of {self.label} to write over, {over!r}: {failure}") diff --git a/bin/record_store/contract.py b/bin/record_store/contract.py index 8a28e9ee..3c912913 100644 --- a/bin/record_store/contract.py +++ b/bin/record_store/contract.py @@ -1,6 +1,7 @@ """What every record backend must hold, as tests. A backend's test case inherits RecordStoreContract and unittest.TestCase, and builds its store in new_store.""" import typing +from record_store.held import Held from record_store.stores import RecordStore @@ -8,6 +9,7 @@ class RecordStoreContract: """Runs against the store new_store returns: one that holds no record yet.""" assertEqual: typing.Callable[..., None] assertIsNone: typing.Callable[..., None] + assertIsInstance: typing.Callable[..., None] assertTrue: typing.Callable[..., None] def new_store(self) -> RecordStore: @@ -19,14 +21,23 @@ class RecordStoreContract: def test_reads_back_what_it_wrote_to_the_character(self) -> None: store = self.new_store() text = "# Decisions\n\n- Å, 🔴 and a | pipe\n\n\n" - self.assertIsNone(store.write(text)) + self.assertEqual(store.write(text), store.held()) self.assertEqual(store.read(), text) def test_a_write_replaces_the_whole_record(self) -> None: store = self.new_store() - store.write("first\nsecond\n") - self.assertIsNone(store.write("third\n")) + first = store.write("first\nsecond\n") + assert isinstance(first, Held), first + # A write over the version the last one left replaces the record, as a later save does. + self.assertIsInstance(store.write("third\n", first.version), Held) self.assertEqual(store.read(), "third\n") + def test_holds_its_text_with_the_version_a_write_over_it_names(self) -> None: + store = self.new_store() + store.write("text\n") + held = store.held() + assert isinstance(held, Held), held + self.assertEqual(held.text, "text\n") + def test_names_itself_for_a_message(self) -> None: self.assertTrue(self.new_store().label.strip()) diff --git a/bin/record_store/fakes.py b/bin/record_store/fakes.py index 07e560bf..96a345df 100644 --- a/bin/record_store/fakes.py +++ b/bin/record_store/fakes.py @@ -2,6 +2,7 @@ import dataclasses from failure import Failure +from record_store.held import Held @dataclasses.dataclass @@ -15,8 +16,11 @@ class MemoryStore: def read(self) -> str | Failure: return Failure(self.fails) if self.fails else self.text - def write(self, text: str) -> Failure | None: + def held(self) -> Held | Failure: + return Failure(self.fails) if self.fails else Held(self.text) + + def write(self, text: str, over: str | None = None) -> Held | Failure: if self.fails: return Failure(self.fails) self.text = text - return None + return Held(text) diff --git a/bin/record_store/held.py b/bin/record_store/held.py new file mode 100644 index 00000000..caf914d2 --- /dev/null +++ b/bin/record_store/held.py @@ -0,0 +1,9 @@ +"""A record as a read found it or a write left it, which every record backend gives.""" +import dataclasses + + +@dataclasses.dataclass(frozen=True) +class Held: + """A record's text as one read found it or one write left it, with its version: what a write over it names, so the write refuses where someone saved the record since. None for a backend whose writes check no version, as a file's.""" + text: str + version: str | None = None diff --git a/bin/record_store/jira_description.py b/bin/record_store/jira_description.py index 37c398b5..a9902f54 100644 --- a/bin/record_store/jira_description.py +++ b/bin/record_store/jira_description.py @@ -8,6 +8,7 @@ from adf_codec.convert import adfs_to_markdown, Refused from atlassian.client import basic_auth, Http, jira_json, ToMarkdown from project_config.settings import Epic from failure import Failure +from record_store.held import Held READ_ONLY = "goals and audience kept in Jira are only read: edit the epic's description in Jira" @@ -49,5 +50,9 @@ class EpicDescription: return Failure(f"cannot convert {key}'s description to markdown: {texts.reason}") return texts[0] - def write(self, text: str) -> Failure | None: + def held(self) -> Held | Failure: + text = self.read() + return text if isinstance(text, Failure) else Held(text) + + def write(self, text: str, over: str | None = None) -> Held | Failure: return Failure(READ_ONLY) diff --git a/bin/record_store/stores.py b/bin/record_store/stores.py index 63c0a31d..20a4adc7 100644 --- a/bin/record_store/stores.py +++ b/bin/record_store/stores.py @@ -9,6 +9,7 @@ from record_store.confluence_page import ConfluencePage from record_store.jira_description import EpicDescription from failure import Failure from git_cli.git_repo import file_at, git, Git +from record_store.held import Held from project_config.settings import ProjectConfig, RECORDS, TOUCH_PREDICTIONS from text_files.file_writes import replace_file @@ -27,8 +28,11 @@ class RecordStore(typing.Protocol): def read(self) -> str | Failure: """The record's text as it stands, empty where it doesn't exist yet.""" - def write(self, text: str) -> Failure | None: - """Replaces the record's whole text, creating the record where it doesn't exist yet.""" + def held(self) -> Held | Failure: + """The record as it stands, with the version a write over it names.""" + + def write(self, text: str, over: str | None = None) -> Held | Failure: + """Replaces the record's whole text, creating the record where it doesn't exist yet, and gives the record as the write left it. over is the version held() gave: where someone saved the record since, the write refuses. None replaces the record as it stands.""" @dataclasses.dataclass(frozen=True) @@ -41,6 +45,10 @@ class FileStore: def label(self) -> str: return str(self.path) + def held(self) -> Held | Failure: + text = self.read() + return text if isinstance(text, Failure) else Held(text) + def read(self) -> str | Failure: try: return self.path.read_text(encoding="utf-8") @@ -51,24 +59,24 @@ class FileStore: except OSError as failure: return Failure(f"cannot read {self.path}: {failure.strerror}") - def write(self, text: str) -> Failure | None: + def write(self, text: str, over: str | None = None) -> Held | Failure: try: self.path.parent.mkdir(parents=True, exist_ok=True) except OSError as failure: return Failure(f"cannot write {self.path}: {failure.strerror}") unwritten = replace_file(self.path, text.encode("utf-8")) - return Failure(f"cannot write {self.path}: {unwritten.reason}") if unwritten else None + return Failure(f"cannot write {self.path}: {unwritten.reason}") if unwritten else Held(text) -def store(config: ProjectConfig, record: str, kept: pathlib.Path | None = None) -> RecordStore: - """The store config names for record, one of RECORDS. A record on a Confluence page keeps the version it read in the file the parameter kept names, for a later process that writes it; where kept is None, the store keeps the version only in memory.""" +def store(config: ProjectConfig, record: str) -> RecordStore: + """The store config names for record, one of RECORDS.""" if record not in RECORDS: raise ValueError(f"{record} is not a record; the records are {', '.join(RECORDS)}") if record not in config.pages: return FileStore(config.paths[record], config.tracked(record)) # load refuses a config that names a page and no env-file. assert config.env_file is not None - return ConfluencePage(config.pages[record], config.env_file, kept) + return ConfluencePage(config.pages[record], config.env_file) def touch_predictions_store(config: ProjectConfig) -> RecordStore | None: @@ -93,27 +101,54 @@ def held_at(revision: str, record: RecordStore, cwd: str, run: Git = git) -> str def local_file(record: RecordStore, copy: pathlib.Path) -> pathlib.Path | Failure: - """A file holding record's text, for an agent, which reads and edits files: the record's own file where a file is its backend, else copy, written with the text as it stands. Neither exists where the record doesn't yet. `stored` puts an edited copy back.""" + """A file holding record's text, for an agent, which reads and edits files: the record's own file where a file is its backend, else copy, written with the text as it stands, and its version beside it, for `stored`, a later process, to write over. Neither exists where the record doesn't yet. `stored` puts an edited copy back.""" if isinstance(record, FileStore): return record.path - text = record.read() - if isinstance(text, Failure): - return text - if text: - return FileStore(copy, None).write(text) or copy - try: - # An earlier copy would read as the record's text, and `stored` would put it back. - copy.unlink(missing_ok=True) - except OSError as failure: - return Failure(f"cannot remove {copy}: {failure.strerror}") - return copy + held = record.held() + if isinstance(held, Failure): + return held + if held.text: + written = FileStore(copy, None).write(held.text) + if isinstance(written, Failure): + return written + else: + try: + # An earlier copy would read as the record's text, and `stored` would put it back. + copy.unlink(missing_ok=True) + except OSError as failure: + return Failure(f"cannot remove {copy}: {failure.strerror}") + # Kept only once the copy holds the text: a version kept for a read that failed would let a later save overwrite the save it saw. + return kept(copy, held.version) or copy def stored(record: RecordStore, copy: pathlib.Path) -> Failure | None: - """Stores in record the text of copy, the file `local_file` gave for it. Where that is the record's own file, the edit is already the record.""" + """Stores in record the text of copy, the file `local_file` gave for it, over the version kept beside it. Where that is the record's own file, the edit is already the record. The version the write left is kept for the next save.""" if isinstance(record, FileStore): return None text = FileStore(copy, None).read() if isinstance(text, Failure): return text - return record.write(text) if text else Failure(f"{copy} is missing or empty, so nothing is stored in {record.label}") + if not text: + return Failure(f"{copy} is missing or empty, so nothing is stored in {record.label}") + over = FileStore(version_file(copy), None).read() + if isinstance(over, Failure): + return over + written = record.write(text, over.strip() or None) + return written if isinstance(written, Failure) else kept(copy, written.version) + + +def version_file(copy: pathlib.Path) -> pathlib.Path: + """The file beside copy that keeps the version of the record copy holds.""" + return copy.with_suffix(".version") + + +def kept(copy: pathlib.Path, version: str | None) -> Failure | None: + """Keeps version beside copy, or removes the file that kept an earlier one where version is None.""" + if version is not None: + written = FileStore(version_file(copy), None).write(version) + return written if isinstance(written, Failure) else None + try: + version_file(copy).unlink(missing_ok=True) + except OSError as failure: + return Failure(f"cannot remove {version_file(copy)}: {failure.strerror}") + return None diff --git a/bin/record_store/test_confluence_page.py b/bin/record_store/test_confluence_page.py index 8ee471e5..68ef65ea 100644 --- a/bin/record_store/test_confluence_page.py +++ b/bin/record_store/test_confluence_page.py @@ -10,9 +10,11 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1])) from record_store.confluence_page import ConfluencePage from rest_client.json_request import ErrorAnswer from failure import Failure +from record_store.held import Held from project_config.settings import Page from record_store.contract import RecordStoreContract from adf_codec.convert import Refused +from record_store import stores PAGE = Page("https://acme.atlassian.net", "2293761", "confluence:https://acme.atlassian.net/wiki/spaces/ENG/pages/2293761") URL = "https://acme.atlassian.net/wiki/api/v2/pages/2293761" @@ -57,11 +59,10 @@ class ConfluenceCase(unittest.TestCase): self.env = folder / "acme.env" self.env.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n") self.env.chmod(0o600) - self.kept = folder / "state" / "acme" / "decisions.version" self.confluence = FakeConfluence() - def new_store(self, kept: pathlib.Path | None = None) -> ConfluencePage: - return ConfluencePage(PAGE, self.env, kept, self.confluence.http, to_markdown, to_adf) + def new_store(self) -> ConfluencePage: + return ConfluencePage(PAGE, self.env, self.confluence.http, to_markdown, to_adf) class ConfluencePageContract(ConfluenceCase, RecordStoreContract): @@ -74,60 +75,80 @@ class ConfluencePageTest(ConfluenceCase): self.assertEqual(self.new_store().read(), "# Decisions\n") self.assertEqual(self.confluence.calls, [("GET", f"{URL}?body-format=atlas_doc_format", AUTHORIZATION, None)]) - def test_writes_markdown_as_the_version_it_read_plus_one(self) -> None: + def test_writes_markdown_as_the_version_it_is_handed_plus_one(self) -> None: self.confluence.version = 7 store = self.new_store() - store.read() - self.assertIsNone(store.write("- a decision\n")) + 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(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_refuses_to_overwrite_a_teammates_save_since_its_read_and_says_to_ask_the_human(self) -> None: - store = self.new_store() - store.read() + 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 = store.write("my 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(self.new_store().read(), "their edit\n") - def test_keeps_the_version_it_read_in_its_file_for_a_later_process(self) -> None: - self.new_store(self.kept).read() + def test_keeps_no_version_itself_so_a_read_never_moves_the_version_a_write_names(self) -> None: + store = self.new_store() + held = store.held() + assert isinstance(held, Held), held self.confluence.teammate_saves("their edit\n") - written = self.new_store(self.kept).write("my edit\n") + self.assertEqual(store.read(), "their edit\n") + written = store.write("my edit\n", held.version) assert isinstance(written, Failure), written self.assertIn("someone saved", written.reason) - def test_a_read_that_fails_keeps_the_version_an_earlier_read_kept(self) -> None: - self.new_store(self.kept).read() - self.confluence.teammate_saves("their edit\n") - failing = ConfluencePage(PAGE, self.env, self.kept, self.confluence.http, lambda _: Refused(0, Failure("adf-codec refused the input")), to_adf) - self.assertIsInstance(failing.read(), Failure) - self.confluence.value = "{not json" - self.assertIsInstance(self.new_store(self.kept).read(), Failure) - written = self.new_store(self.kept).write("my edit\n") - assert isinstance(written, Failure), written - self.assertIn("someone saved", written.reason) - self.assertEqual(self.confluence.version, 2) - - def test_a_later_process_writes_with_the_version_an_earlier_one_read_or_wrote(self) -> None: - self.new_store(self.kept).read() - self.assertIsNone(self.new_store(self.kept).write("first\n")) - self.assertIsNone(self.new_store(self.kept).write("second\n")) + def test_a_later_write_over_the_version_an_earlier_one_left_lands(self) -> None: + held = self.new_store().held() + assert isinstance(held, Held), held + first = self.new_store().write("first\n", held.version) + assert isinstance(first, Held), first + self.assertIsInstance(self.new_store().write("second\n", first.version), Held) self.assertEqual(self.new_store().read(), "second\n") self.assertEqual(self.confluence.title, "Decisions") + def test_each_save_of_an_opened_copy_writes_over_the_version_the_open_or_the_last_save_left(self) -> None: + copy = self.env.parent / "copies" / "decisions.md" + self.confluence.teammate_saves("first\n") + self.assertEqual(stores.local_file(self.new_store(), copy), copy) + for text in ("mine\n", "again\n"): + copy.write_text(text) + self.assertIsNone(stores.stored(self.new_store(), copy)) + self.assertEqual(self.new_store().read(), "again\n") + self.confluence.teammate_saves("theirs\n") + copy.write_text("third\n") + refused = stores.stored(self.new_store(), copy) + assert isinstance(refused, Failure), refused + self.assertIn("someone saved", refused.reason) + self.assertEqual(self.new_store().read(), "theirs\n") + + def test_an_open_that_fails_keeps_the_version_an_earlier_open_kept(self) -> None: + copy = self.env.parent / "copies" / "decisions.md" + stores.local_file(self.new_store(), copy) + self.confluence.teammate_saves("their edit\n") + self.confluence.value = "{not json" + self.assertIsInstance(stores.local_file(self.new_store(), copy), Failure) + copy.write_text("my edit\n") + refused = stores.stored(self.new_store(), copy) + assert isinstance(refused, Failure), refused + self.assertIn("someone saved", refused.reason) + def test_a_write_with_no_read_replaces_the_page_as_it_stands(self) -> None: self.confluence.teammate_saves("earlier\n") - self.assertIsNone(self.new_store().write("replaced\n")) + self.assertIsInstance(self.new_store().write("replaced\n"), Held) self.assertEqual(self.confluence.calls[0], ("GET", URL, AUTHORIZATION, None)) self.assertEqual(self.new_store().read(), "replaced\n") def test_fails_on_an_answer_not_shaped_as_a_page(self) -> None: for answer in ({}, {"title": "Decisions", "version": {}, "body": {"atlas_doc_format": {"value": ""}}}, {"version": {"number": 3}, "body": {"atlas_doc_format": {"value": ""}}}, ["not", "a", "page"]): with self.subTest(answer): - store = ConfluencePage(PAGE, self.env, None, lambda *_: answer, to_markdown, to_adf) + store = ConfluencePage(PAGE, self.env, lambda *_: answer, to_markdown, to_adf) read = store.read() assert isinstance(read, Failure), read self.assertIn("not in the shape Confluence Cloud's REST API version 2 documents", read.reason) @@ -136,7 +157,7 @@ class ConfluencePageTest(ConfluenceCase): for body in ({}, "text", {"atlas_doc_format": "text"}, {"atlas_doc_format": {"value": 3}}): with self.subTest(body): answer = {"title": "Decisions", "version": {"number": 3}, "body": body} - store = ConfluencePage(PAGE, self.env, None, lambda *_: answer, to_markdown, to_adf) + store = ConfluencePage(PAGE, self.env, lambda *_: answer, to_markdown, to_adf) self.assertEqual(store.read(), Failure(f"{PAGE.spelling} is not in the shape Confluence Cloud's REST API version 2 documents: it holds no body in atlas_doc_format")) def test_fails_on_a_body_that_is_not_json(self) -> None: @@ -145,43 +166,28 @@ class ConfluencePageTest(ConfluenceCase): def test_fails_naming_the_page_where_the_text_cannot_be_converted(self) -> None: self.confluence.teammate_saves("text\n") - store = ConfluencePage(PAGE, self.env, None, self.confluence.http, lambda _: Failure("the shim is down"), lambda _: Failure("the shim is down")) + store = ConfluencePage(PAGE, self.env, self.confluence.http, lambda _: Failure("the shim is down"), lambda _: Failure("the shim is down")) self.assertEqual(store.read(), Failure(f"cannot convert {PAGE.spelling} to markdown: the shim is down")) self.assertEqual(store.write("text\n"), Failure(f"cannot convert the text for {PAGE.spelling} to ADF: the shim is down")) def test_fails_naming_the_page_where_adf_codec_refuses_its_document(self) -> None: self.confluence.teammate_saves("text\n") - store = ConfluencePage(PAGE, self.env, None, self.confluence.http, lambda _: Refused(0, Failure("adf-codec refused the input")), to_adf) + store = ConfluencePage(PAGE, self.env, self.confluence.http, lambda _: Refused(0, Failure("adf-codec refused the input")), to_adf) self.assertEqual(store.read(), Failure(f"{PAGE.spelling}: adf-codec refused the input")) - def test_fails_where_the_folder_of_its_file_cannot_be_made(self) -> None: - self.kept.parent.parent.mkdir(parents=True) - self.kept.parent.write_text("a file, not a folder") - read = self.new_store(self.kept).read() - assert isinstance(read, Failure), read - self.assertTrue(read.reason.startswith(f"cannot write {self.kept}: "), read.reason) - def test_a_write_confluence_refuses_otherwise_fails_naming_the_page_and_not_a_teammate(self) -> None: answers = iter([{"title": "Decisions", "version": {"number": 3}}, ErrorAnswer("PUT /wiki/api/v2/pages/2293761 answered 403: Forbidden", 403)]) - store = ConfluencePage(PAGE, self.env, None, lambda *_: next(answers), to_markdown, to_adf) + store = ConfluencePage(PAGE, self.env, lambda *_: next(answers), to_markdown, to_adf) self.assertEqual(store.write("text\n"), Failure(f"cannot write {PAGE.spelling}: PUT /wiki/api/v2/pages/2293761 answered 403: Forbidden")) - def test_fails_where_its_file_cannot_keep_the_version(self) -> None: - self.kept.mkdir(parents=True) - read = self.new_store(self.kept).read() - assert isinstance(read, Failure), read - self.assertTrue(read.reason.startswith(f"cannot write {self.kept}: "), read.reason) - - def test_fails_on_a_kept_version_it_cannot_read_and_writes_nothing(self) -> None: - self.kept.parent.mkdir(parents=True) - self.kept.write_text("{}") - written = self.new_store(self.kept).write("text\n") + def test_fails_on_a_version_it_cannot_read_and_writes_nothing(self) -> None: + written = self.new_store().write("text\n", "{}") assert isinstance(written, Failure), written - self.assertTrue(written.reason.startswith(f"cannot read the version of {PAGE.spelling} that {self.kept} keeps: "), written.reason) + self.assertTrue(written.reason.startswith(f"cannot read the version of {PAGE.spelling} to write over, '{{}}': "), written.reason) self.assertEqual(self.confluence.calls, []) def test_fails_naming_the_page_when_confluence_answers_an_error(self) -> None: - store = ConfluencePage(PAGE, self.env, None, lambda *_: ErrorAnswer("GET /wiki/api/v2/pages/2293761 answered 404: Not Found", 404), to_markdown, to_adf) + 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.read(), Failure(f"cannot read {PAGE.spelling}: GET /wiki/api/v2/pages/2293761 answered 404: Not Found")) def test_fails_without_credentials_before_any_request(self) -> None: diff --git a/bin/record_store/test_stores.py b/bin/record_store/test_stores.py index 64603554..9bcc448e 100644 --- a/bin/record_store/test_stores.py +++ b/bin/record_store/test_stores.py @@ -10,6 +10,7 @@ from record_store.confluence_page import ConfluencePage from project_config.settings import Epic, Page, ProjectConfig from record_store.jira_description import EpicDescription from failure import Failure +from record_store.held import Held from record_store.fakes import MemoryStore from record_store.contract import RecordStoreContract from record_store import stores @@ -62,7 +63,7 @@ class FileStore(unittest.TestCase): def test_a_write_makes_each_folder_the_file_lacks(self): path = self.folder / "records" / "acme" / "decisions.md" - self.assertIsNone(stores.FileStore(path, None).write("text\n")) + self.assertEqual(stores.FileStore(path, None).write("text\n"), Held("text\n")) self.assertEqual(path.read_text(), "text\n") def test_a_write_onto_a_folder_is_a_failure_naming_it(self): @@ -172,11 +173,10 @@ class Store(unittest.TestCase): stores.store(self.config(pathlib.Path("/code/acme"), pathlib.Path("/home/me/.claude-projects/acme")), "plan") self.assertEqual(str(refused.exception), "plan is not a record; the records are decisions, score-anchors, comprehension-history, reading-cost, changelog") - def test_a_record_on_a_confluence_page_is_that_page_keeping_its_version_where_asked(self): + def test_a_record_on_a_confluence_page_is_that_page(self): page = Page("https://acme.atlassian.net", "2293761", "confluence:https://acme.atlassian.net/wiki/spaces/ENG/pages/2293761") config = ProjectConfig("acme", pathlib.Path("/home/me/.claude-projects/acme"), pathlib.Path("/code/acme"), {}, pathlib.Path("/home/me/acme.env"), pages={"decisions": page}) - kept = pathlib.Path("/home/me/decisions.version") - self.assertEqual(stores.store(config, "decisions", kept), ConfluencePage(page, pathlib.Path("/home/me/acme.env"), kept)) + self.assertEqual(stores.store(config, "decisions"), ConfluencePage(page, pathlib.Path("/home/me/acme.env"))) class GoalsStore(unittest.TestCase): diff --git a/bin/release_plan/release_standing.py b/bin/release_plan/release_standing.py index 9465b327..ffd0d233 100644 --- a/bin/release_plan/release_standing.py +++ b/bin/release_plan/release_standing.py @@ -1,8 +1,9 @@ """How the plan stands to the last release cut: the next release, whether work has landed towards it, and whether it is to be planned, reviewed or cut; and, from that standing, the item the next chunk takes first, with what the default branch holds for the pick.""" import dataclasses +import re from git_cli.git_repo import commits_since, file_at, git, Git -from plan.release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged +from plan.release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged, UNRELEASED_HEADING from failure import Failure from plan.todo_table import Item, items, next_item, renames from plan_store.plans import Plan @@ -258,9 +259,12 @@ def unreleased_changes(cut: LastCut) -> int | Failure: def unreleased_entries(changelog: str) -> int | None: - """How many top-level `- ` entries CHANGELOG.md holds under ## Unreleased; None without that section.""" - found = sections(changelog).get("Unreleased") - return None if found is None else sum(line.startswith("- ") for line in found[0].splitlines()) + """How many top-level `- ` entries CHANGELOG.md holds under its unreleased section, as UNRELEASED_HEADING heads it; None without that section.""" + heading = UNRELEASED_HEADING.search(changelog) + if heading is None: + return None + body = re.split(r"^## ", changelog[heading.end():], maxsplit=1, flags=re.M)[0] + return sum(line.startswith("- ") for line in body.splitlines()) def named_releases(todos: list[str] | Failure) -> set[Release] | Failure: diff --git a/bin/release_plan/test_release_standing.py b/bin/release_plan/test_release_standing.py index 639ad0e2..c30dfaf1 100644 --- a/bin/release_plan/test_release_standing.py +++ b/bin/release_plan/test_release_standing.py @@ -352,6 +352,8 @@ class ChunkItem(unittest.TestCase): self.assertEqual(release_standing.unreleased_entries("# Changelog\n\n## Unreleased\n\n- One.\n - A nested line.\n- Two.\n\n## 0.1.0\n\n- Old.\n"), 2) self.assertEqual(release_standing.unreleased_entries("# Changelog\n\n## Unreleased\n\n## 0.1.0\n\n- Old.\n"), 0) self.assertIsNone(release_standing.unreleased_entries("# Changelog\n\n## 0.1.0\n\n- Old.\n")) + # The section todo-item finish files a bullet under, as a project's own changelog may head it. + self.assertEqual(release_standing.unreleased_entries("# Changelog\n\n## 0.6.0 (unreleased)\n\n- One.\n\n## 0.5.0\n\n- Old.\n"), 1) def test_names_each_release_a_todo_md_since_the_last_cut_filed_items_under(self): texts = [HEADER + ROW.format(id=1, release="0.2.0"), "", "not a table | x |", HEADER + ROW.format(id=2, release="0.3.0")] diff --git a/bin/rest_client/test_json_request.py b/bin/rest_client/test_json_request.py index b98a0cc2..3e030eb9 100644 --- a/bin/rest_client/test_json_request.py +++ b/bin/rest_client/test_json_request.py @@ -30,6 +30,9 @@ class Recorded(http.server.BaseHTTPRequestHandler): def do_POST(self) -> None: self.answer() + def do_PUT(self) -> None: + self.answer() + def answer(self) -> None: length = int(self.headers.get("Content-Length") or 0) self.server.got.append((self.command, self.path, dict(self.headers), self.rfile.read(length))) # type: ignore[attr-defined] @@ -50,7 +53,9 @@ class Recorded(http.server.BaseHTTPRequestHandler): pass -class HttpJson(unittest.TestCase): +class Served(unittest.TestCase): + """A test case with a local server that answers by a script; it holds no test itself, so a test elsewhere may build on it.""" + def serve(self, *script: tuple[int, bytes]) -> str: server = http.server.HTTPServer(("127.0.0.1", 0), Recorded) server.script = list(script) # type: ignore[attr-defined] @@ -61,6 +66,8 @@ class HttpJson(unittest.TestCase): self.server = server return f"http://127.0.0.1:{server.server_port}" + +class HttpJson(Served): def test_sends_the_authorization_and_the_body_as_json_and_reads_the_json_answer(self): base = self.serve((201, b'{"id": "post-id"}')) self.assertEqual(send("POST", f"{base}/api/v4/posts", "secret-token", {"message": "hi"}), {"id": "post-id"}) diff --git a/bin/rule_hook/rules.py b/bin/rule_hook/rules.py index 0072286f..c82e4d05 100644 --- a/bin/rule_hook/rules.py +++ b/bin/rule_hook/rules.py @@ -88,7 +88,7 @@ RULES: dict[RuleName, Rule] = { ), "run-heavy": Rule( "a heavy command, which loads the machine for minutes, runs under ~/.claude/bin/run-heavy, so sessions running at once cannot starve the machine", - "a docker build, docker buildx build or docker compose build, and a run of mutate-changes, or of cargo mutants, Infection, mutmut or Stryker, the mutation tools it runs, whether direct, through a launcher such as uvx, or inside docker run, docker exec or docker compose run or exec. A gate script is not checked, since no program can tell it from a light one", + "a docker build, docker buildx build or docker compose build, and a run of mutate-changes, or of cargo mutants, Infection, mutmut or Stryker, the mutation tools it runs, whether direct, through a launcher such as uvx, uv run, poetry run, sudo or doas, or inside docker run, docker exec or docker compose run or exec. A gate script is not checked, since no program can tell it from a light one", ), "todo-rank-check": Rule( "while todo.md has changes, staged or not, a git commit waits until rank_todo.py --check passes on it: the checkout's own bin/rank_todo.py where the checkout is of this setup's repo, else ~/.claude/bin/rank_todo.py", diff --git a/bin/rule_hook/test_rule_hook.py b/bin/rule_hook/test_rule_hook.py index 4a746c73..4ed00ba6 100644 --- a/bin/rule_hook/test_rule_hook.py +++ b/bin/rule_hook/test_rule_hook.py @@ -125,7 +125,7 @@ class CommandBreaches(unittest.TestCase): self.assertEqual(checked("git commit -m 'Answer the question in the README'"), []) def test_a_docker_build_or_a_mutation_run_outside_run_heavy_breaks_run_heavy(self): - for command in ["docker build -t x .", "cd /w && docker buildx build .", "docker compose build", "docker compose -f x.yml --verbose build app", "uvx --with pytest 'mutmut>=3,<4' run", "cargo mutants --in-diff d", "npx stryker run", "vendor/bin/infection --git-diff-lines", "docker compose run --rm app mutmut run", "docker run --rm -m 4g --memory-swap 4g -v /w:/w rust:1.90.0 cargo mutants", "docker compose exec app npx stryker run", "docker run -h box -m 4g --memory-swap 4g rust:1.90.0 cargo mutants", "nice -n 19 docker build .", "env DOCKER_BUILDKIT=1 docker build .", "time -p docker compose build", "docker --tlscacert ca.pem build .", "docker --tlscert c.pem --tlskey k.pem build .", "docker buildx --builder b build .", "docker container run -m 4g --memory-swap 4g rust:1.90.0 cargo mutants", "uvx mutmut --verbose run", "~/.claude/bin/mutate-changes", "cd /w && mutate-changes --base main"]: + for command in ["docker build -t x .", "sudo docker build -t x .", "doas docker build .", "uv run mutmut run", "uv run --with pytest mutmut run", "poetry run mutmut run", "cd /w && docker buildx build .", "docker compose build", "docker compose -f x.yml --verbose build app", "uvx --with pytest 'mutmut>=3,<4' run", "cargo mutants --in-diff d", "npx stryker run", "vendor/bin/infection --git-diff-lines", "docker compose run --rm app mutmut run", "docker run --rm -m 4g --memory-swap 4g -v /w:/w rust:1.90.0 cargo mutants", "docker compose exec app npx stryker run", "docker run -h box -m 4g --memory-swap 4g rust:1.90.0 cargo mutants", "nice -n 19 docker build .", "env DOCKER_BUILDKIT=1 docker build .", "time -p docker compose build", "docker --tlscacert ca.pem build .", "docker --tlscert c.pem --tlskey k.pem build .", "docker buildx --builder b build .", "docker container run -m 4g --memory-swap 4g rust:1.90.0 cargo mutants", "uvx mutmut --verbose run", "~/.claude/bin/mutate-changes", "cd /w && mutate-changes --base main"]: with self.subTest(command): self.assertEqual(checked(command), ["run-heavy"]) diff --git a/bin/todo_item/edits.py b/bin/todo_item/edits.py index 76bff07b..ff17f340 100644 --- a/bin/todo_item/edits.py +++ b/bin/todo_item/edits.py @@ -2,10 +2,11 @@ import re from failure import Failure +from plan.release import UNRELEASED_HEADING UNRELEASED = "## Unreleased" -# The changelog's section for news not yet released: ## Unreleased, or a release heading such as `## 0.6.0 (unreleased)`. -UNRELEASED_SECTION = re.compile(r"^## .*unreleased.*\n+", re.M | re.I) +# UNRELEASED_HEADING with the blank lines below it, after which a bullet goes first. +UNRELEASED_SECTION = re.compile(UNRELEASED_HEADING.pattern + r"\n+", UNRELEASED_HEADING.flags) def with_bullet(changelog: str, bullet: str) -> str | Failure: diff --git a/bin/todo_item/main.py b/bin/todo_item/main.py index 7daeff51..cde0c3ab 100644 --- a/bin/todo_item/main.py +++ b/bin/todo_item/main.py @@ -81,9 +81,9 @@ import typing from plan.todo_table import BLOCKED_BY, MOVES from failure import Failure 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_store.plans import PlanStore, TAGLINE, Written from record_store.stores import RecordStore, store from todo_item.table import shown, table from todo_item.edits import with_bullet @@ -203,7 +203,7 @@ def show(args: argparse.Namespace, plan: PlanStore) -> str | Failure: if isinstance(read, Failure): return read found = next((item for item in read.items if item.id == args.id), None) - return Failure(f"{plan.label} holds no item {args.id}") if found is None else f"From {plan.label}:\n\n{shown(found)}" + return Failure(no_item(plan.label, args.id)) if found is None else f"From {plan.label}:\n\n{shown(found)}" def edit(args: argparse.Namespace, plan: PlanStore, text: str) -> str | Failure: @@ -218,9 +218,10 @@ def edit(args: argparse.Namespace, plan: PlanStore, text: str) -> str | Failure: def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore) -> str | Failure: - news = changelog.read() - if isinstance(news, Failure): - return Failure(f"not finished: {news.reason}") + held = changelog.held() + if isinstance(held, Failure): + return Failure(f"not finished: {held.reason}") + news = held.text if news and args.changelog is None and not args.no_changelog: return Failure(f"not finished: {changelog.label} exists; pass --changelog , or --no-changelog where the repo doesn't publish anything or no chunk built the item") # The bullet is checked before the plan changes: where finish refuses the bullet, the plan and the changelog stay as they were. @@ -228,6 +229,7 @@ def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore) -> if isinstance(added, Failure): return Failure(f"not finished: {added.reason}") done = reported(plan.finish(args.id), "not finished", lambda written: f"Finished item {written.id} in {plan.label}.") - if not isinstance(done, Failure) and added is not None and (unwritten := changelog.write(added)): - return Failure(f"{unwritten.reason}; the plan no longer holds item {args.id}, so add its bullet by hand") + written = changelog.write(added, held.version) if not isinstance(done, Failure) and added is not None else None + if isinstance(written, Failure): + return Failure(f"{written.reason}; the plan no longer holds item {args.id}, so add its bullet by hand") return done diff --git a/bin/touch_predictions/main.py b/bin/touch_predictions/main.py index 03bdc1ac..c24d79c6 100644 --- a/bin/touch_predictions/main.py +++ b/bin/touch_predictions/main.py @@ -44,8 +44,9 @@ cannot be read; or when git cannot name the merge base or the diff. """ import sys import time +import typing -from git_cli.git_repo import default_ref, git +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 @@ -73,8 +74,8 @@ def main(argv: list[str]) -> int: return 0 -def recorded(config: ProjectConfig, ids: list[int]) -> str | Failure: - """Appends the entry of the chunk that takes the items ids, and says so; or says that the project keeps no record.""" +def recorded(config: ProjectConfig, ids: list[int], now: typing.Callable[[], float] = time.time, run: Git = git) -> str | Failure: + """Appends the entry of the chunk that takes the items ids, stamped at now and read from the commits run shows, and says so; or says that the project keeps no record.""" store = touch_predictions_store(config) if store is None: return f"The project's config sets no `{TOUCH_PREDICTIONS}`, so nothing is recorded." @@ -82,17 +83,17 @@ def recorded(config: ProjectConfig, ids: list[int]) -> str | Failure: if isinstance(prediction, Failure): return prediction cwd = str(config.top) - default = default_ref(cwd) - base = default if isinstance(default, Failure) else git("merge-base", default, "HEAD", cwd=cwd) - head = base if isinstance(base, Failure) else git("rev-parse", "--short", "HEAD", cwd=cwd) + default = default_ref(cwd, run=run) + base = default if isinstance(default, Failure) else run("merge-base", default, "HEAD", cwd=cwd) + head = base if isinstance(base, Failure) else run("rev-parse", "--short", "HEAD", cwd=cwd) if isinstance(base, Failure) or isinstance(head, Failure): return head if isinstance(head, Failure) else base # Every chunk writes the plan and the records, so they are left out of what a chunk touched. skipped = {path for name in ("plan", *RECORDS, TOUCH_PREDICTIONS) if (path := config.tracked(name))} - touches = touched(base.strip(), "HEAD", cwd, skipped) + touches = touched(base.strip(), "HEAD", cwd, skipped, run) if isinstance(touches, Failure): return touches - failed = record.append(store, ids, record.entry(ids, utc(time.time()), head.strip(), prediction, touches)) + failed = record.append(store, ids, record.entry(ids, utc(now()), head.strip(), prediction, touches)) return failed or f"Recorded what chunk {', '.join(map(str, ids))} was predicted to touch, and what it touched, in {store.label}." diff --git a/bin/touch_predictions/record.py b/bin/touch_predictions/record.py index ef274388..d0c1f2fc 100644 --- a/bin/touch_predictions/record.py +++ b/bin/touch_predictions/record.py @@ -20,8 +20,9 @@ def listed(label: str, touches: Touches | None) -> str: def append(store: RecordStore, items: list[int], text: str) -> Failure | None: """Appends text, the entry of the chunk that took items, in place of each entry the record holds for the same items: a fix after the first entry changes what the chunk touched.""" - held = store.read() + held = store.held() if isinstance(held, Failure): return held - kept = re.sub(rf"^## Chunk {', '.join(map(str, items))}, {STAMPED},.*?(?=^## |\Z)", "", held, flags=re.M | re.S) - return store.write(f"{kept.rstrip() or TITLE}\n\n{text}") + kept = re.sub(rf"^## Chunk {', '.join(map(str, items))}, {STAMPED},.*?(?=^## |\Z)", "", held.text, flags=re.M | re.S) + written = store.write(f"{kept.rstrip() or TITLE}\n\n{text}", held.version) + return written if isinstance(written, Failure) else None diff --git a/bin/touch_predictions/test_touch_predictions.py b/bin/touch_predictions/test_touch_predictions.py index eb14502c..72146ef1 100644 --- a/bin/touch_predictions/test_touch_predictions.py +++ b/bin/touch_predictions/test_touch_predictions.py @@ -9,12 +9,14 @@ import unittest sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1])) from touch_predictions.beside import Beside, chunks_beside -from touch_predictions import diff_parts, file_parts, record +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_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. @@ -451,6 +453,13 @@ class RecordCommandTest(unittest.TestCase): assert entry is not None self.assertEqual(entry.group(1), "Predicted:\n\n- `app.py`: `run`\n\nTouched:\n\n- `app.py`: `run`, `stop`\n") + def test_stamps_the_entry_at_the_clock_it_is_handed(self) -> None: + path = self.set_record() + config = located(str(self.checkout), self.home) + assert isinstance(config, ProjectConfig), config + self.assertNotIsInstance(main.recorded(config, [3], now=lambda: 0.0), Failure) + self.assertIn("## Chunk 3, 1970-01-01T00:00:00Z, at ", path.read_text(encoding="utf-8")) + def test_a_second_run_replaces_the_entry_and_leaves_the_record_out_of_what_was_touched(self) -> None: path = self.set_record() self.record("record", "3") diff --git a/docs/decisions.md b/docs/decisions.md index dffa9102..70513b86 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -220,7 +220,7 @@ Valid while cache reads cost a twentieth of input and Claude Code's compaction k ## machine load: a heavy command waits for one of the machine's heavy slots, one for every 4 CPUs, which every session shares, and loop-claude starts a worker only while at least a quarter of the machine's memory is available -2026-10-23, lilleman. Serves goal 1.5. On 2026-10-22 ai-sandbox, with 8 CPUs and 16 GiB, thrashed for hours: four to six loops ran mutation tests, full gates, `docker build`s and QEMU-booting e2e tests at once, and nothing told one loop how busy the machine was. lilleman chose both limits; no standard sets either, and GNU parallel's `--memfree`, which does the memory wait's job, has no default. A slot is a file lock, so a session that dies frees its slot. The memory wait reads `/proc/meminfo` only, and off Linux a worker starts at once. `bin/machine_load/` holds the slots and the memory share, `bin/run-heavy` takes a slot, `CLAUDE.md` → "Working with the codebase" has every session use it, and loop-claude's worker waits for the share. rule-hook's rule `run-heavy` blocks a `docker build`, and a run of a mutation tool stability-reviewer names, outside run-heavy, in the forms its `checked` text in `bin/rule_hook/rules.py` lists. 2026-11-04, lilleman: other forms, such as `uv run mutmut run` or `sudo docker build`, pass until one becomes a problem. No program can tell a gate script from a light one, so only `CLAUDE.md` asks a session to run a gate under run-heavy. Valid while one machine runs several loops at once. +2026-10-23, lilleman. Serves goal 1.5. On 2026-10-22 ai-sandbox, with 8 CPUs and 16 GiB, thrashed for hours: four to six loops ran mutation tests, full gates, `docker build`s and QEMU-booting e2e tests at once, and nothing told one loop how busy the machine was. lilleman chose both limits; no standard sets either, and GNU parallel's `--memfree`, which does the memory wait's job, has no default. A slot is a file lock, so a session that dies frees its slot. The memory wait reads `/proc/meminfo` only, and off Linux a worker starts at once. `bin/machine_load/` holds the slots and the memory share, `bin/run-heavy` takes a slot, `CLAUDE.md` → "Working with the codebase" has every session use it, and loop-claude's worker waits for the share. rule-hook's rule `run-heavy` blocks a `docker build`, and a run of a mutation tool stability-reviewer names, outside run-heavy, in the forms its `checked` text in `bin/rule_hook/rules.py` lists. 2026-11-16, lilleman: rule-hook checks a run through `uv run`, `poetry run`, `sudo` and `doas` too, such as `uv run mutmut run` and `sudo docker build`, since project principle 4 has a program enforce a rule it can check; on 2026-11-04 such forms passed until one became a problem. No program can tell a gate script from a light one, so only `CLAUDE.md` asks a session to run a gate under run-heavy. Valid while one machine runs several loops at once. ## machine load: every container a session starts has a memory limit and a swap limit as large as its work needs; rule-hook's `docker-run-memory` blocks a `docker run` or `docker create` without them outside run-heavy, under which a container that lacks them gets the slot's share of three quarters of the memory; and no daemon-wide cap limits all containers together @@ -306,8 +306,8 @@ Valid while the later fixes per finished chunk, which `score-outcomes` and the r - **A bench of readers picked the spelling.** Three fresh readers, seated as the person who writes a client's `config.toml`, each picked `decisions = "confluence:https:///wiki/spaces//pages/"`, pasted from the browser with or without the title at its end, over the bare address, a page ID beside a `confluence-site` key, and a table. Each named the match with `jira:`. Any of the five records may name a page; the goals file, the plan, the working rules and the principles may not. - **`decisions` and `comprehension-history` may name a page only where `plan` names a Jira epic.** rule-hook ranks a plan kept as a file before tool calls, inside its 30-second limit, and ranking reads those two records. A Confluence read and two adf-codec container runs would hold up every guarded tool call, and fail it while Confluence is down. `load` refuses goals in Jira beside a plan in a file for the same reason. -- **A write sends the version number the store read, plus one, and Confluence refuses it with 409 where someone saved the page since.** The store then fails, saying to ask the human, and doesn't write the page; the loop never overwrites a teammate's edit on its own (lilleman, 2026-11-12). A write with no read before it replaces the page as it stands, as the record contract asks. -- **`project-record` keeps the version `open` read in a file beside its copy**, `~/.local/state/project-record///.version`, since `save` runs in a later process. The store keeps the version itself, so `write` still takes only the text. Every other tool reads and writes a record in one process, and its store keeps the version in memory, so a read by another tool, such as larv-review's, never moves the version an edit in `project-record` rests on. The folder `` 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. +- **A write sends the version number it writes over, plus one, and Confluence refuses it with 409 where someone saved the page since.** The store then fails, saying to ask the human, and doesn't write the page; the loop never overwrites a teammate's edit on its own (lilleman, 2026-11-12). A write over no version replaces the page as it stands, as the record contract asks. +- **A store keeps no version: its caller hands each write the version it writes over.** `held()` gives a record's text with its version, and `write(text, over)` takes that version and gives the record as it left it, with the next. 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///.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 `` 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 `_( not included)_`. So the next write replaces it with that text, and a record page should hold only what markdown can. ## project config: a tool that reads a file's commits says where it does not support that file, and the work goes on @@ -600,7 +600,7 @@ A project's rung is its model's cheapest rung, which for Opus 5.5 is its default 2026-11-11, lilleman approved the rungs for Fable 5.2 from the index read that day. Its score and cost per task, for each effort from low to max: Sonnet 5.5 26 $0.51, 31 $0.78, 42 $1.64, 50 $4.09, 55 $10.02; Opus 5.5 35 $0.98, 48 $2.45, 52 $3.46, 57 $6.05, 59 $10.04; Fable 5.2 54 $3.10, 56 $3.80, 62 $9.08, 62 $14.83, 65 $26.54. The cut drops Opus 5.5 at high, since Fable 5.2 at low scores more for less; Opus 5.5 at max, since Fable 5.2 at high scores more for less; and Fable 5.2 at xhigh, which ties Fable 5.2 at high at a higher cost. Sonnet 5.5 at high stays the bottom rung, as the 2026-10-29 note chose. With Haiku 5.5 off, the cut alone would also keep Sonnet 5.5 at low and medium and Opus 5.5 at low, below it. On an Opus 5.5 project, an L 4 worker, an E + I 5 review and a worker's first escalation now run on Fable 5.2 at low, where they ran on Opus 5.5 at high; E + I 8 runs on Fable 5.2 at high, where it ran on Fable 5.1 at max. Three steps land on a rung the index scores lower than before: E + I 6 on Fable 5.2 at medium, 56 against Opus 5.5 at xhigh's 57; E + I 7 on Opus 5.5 at xhigh, 57 against Opus 5.5 at max's 59; and an L 3 worker's escalation stops, without lilleman's yes, at Fable 5.2 at medium, where it stopped at Opus 5.5 at xhigh. On a Sonnet 5.5 project, E + I 6 runs on Fable 5.2 at low, 54 against Opus 5.5 at high's 52; E + I 7 on Fable 5.2 at medium, 56 against Opus 5.5 at xhigh's 57; and E + I 8 on Opus 5.5 at xhigh, 57 against Opus 5.5 at max's 59. Fable 5.2 at max, on top, is reached only one rung up from Fable 5.2 at high, as by a reviewer's rerun. A Fable 5.2 project's rung is Fable 5.2 at low, so its L 1 and L 2 workers run on Opus 5.5 at medium. -2026-11-14, lilleman ruled that L 3 is to step one rung up and L 4 two up, in every project and for delegated subagents. The steps stated above, L 3 none and L 4 one up, hold until `bin/model_routing/ladder.py` changes. Then, on an Opus 5.5 project, an L 3 worker or subagent runs on Fable 5.2 at low, and an escalation stops without lilleman's yes at Opus 5.5 at xhigh. An L 4 one runs on Fable 5.2 at medium, and stops at Fable 5.2 at high. The ruling settles the two calls of the routing figures measured at 2026-11-14T00:59:50Z, which were not yet in `routing-calls-raised.md`; the chunk that settles them cites their stamp there. The figures came from 276 chunks finished since the 2026-10-29 reset. Chunks started on Opus 5.5 at medium, 79 of them, took a mean 0.8 review rounds past each pass's first, 0.3 unfinished verdicts and 0.2 later fixes. Chunks started on Fable 5.2 at low, 5 of them, took 0.4, 0.0 and 0.0. On an Opus 5.5 project only L 4 items start on Fable 5.2 at low, so it did better on harder items. Two things weaken the evidence: 5 chunks is the fewest a call allows, and the Opus 5.5 figures include chunks from before Fable 5.2 joined the ladder. On the 2026-11-11 index, an L 3 task's cost rises about 1.3 times, from $2.45 to $3.10, for fewer rounds and fewer unfinished verdicts (goal 1.4). The chunks started on Sonnet 5.5 at high, 164 of the 276, don't move. +2026-11-14, lilleman ruled that L 3 is to step one rung up and L 4 two up, in every project and for delegated subagents. The steps stated above, L 3 none and L 4 one up, hold until `bin/model_routing/ladder.py` changes, which `todo.md` item 393 does in 0.12.0, as lilleman chose on 2026-11-16. Then, on an Opus 5.5 project, an L 3 worker or subagent runs on Fable 5.2 at low, and an escalation stops without lilleman's yes at Opus 5.5 at xhigh. An L 4 one runs on Fable 5.2 at medium, and stops at Fable 5.2 at high. The ruling settles the two calls of the routing figures measured at 2026-11-14T00:59:50Z, which were not yet in `routing-calls-raised.md`; the chunk that settles them cites their stamp there. The figures came from 276 chunks finished since the 2026-10-29 reset. Chunks started on Opus 5.5 at medium, 79 of them, took a mean 0.8 review rounds past each pass's first, 0.3 unfinished verdicts and 0.2 later fixes. Chunks started on Fable 5.2 at low, 5 of them, took 0.4, 0.0 and 0.0. On an Opus 5.5 project only L 4 items start on Fable 5.2 at low, so it did better on harder items. Two things weaken the evidence: 5 chunks is the fewest a call allows, and the Opus 5.5 figures include chunks from before Fable 5.2 joined the ladder. On the 2026-11-11 index, an L 3 task's cost rises about 1.3 times, from $2.45 to $3.10, for fewer rounds and fewer unfinished verdicts (goal 1.4). The chunks started on Sonnet 5.5 at high, 164 of the 276, don't move. 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//`, 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`. diff --git a/todo.md b/todo.md index 5d47da31..b9b6ee0c 100644 --- a/todo.md +++ b/todo.md @@ -6,7 +6,7 @@ `Bar = 0.1` -`Next ID = 393` +`Next ID = 394` ## Items @@ -21,6 +21,7 @@ | 339 | 0.12.0 | | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 2 | 2 | 1 | 3 | 3 | 1.4 by 3 | 1.0 | | 341 | 0.12.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 | | 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 | +| 393 | 0.12.0 | | decision | **Step an L 3 worker one rung up and an L 4 worker two up from the project's rung, as lilleman ruled on 2026-11-14.** | 2 | 1 | 3 | 4 | 4 | 1.4 by 3 | 0.9 | | 298 | 0.12.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 | | 331 | 0.12.0 | | | **Reword four decisions to expire when the rungs their replays tested change, not whenever a model joins the ladder.** | 1 | 1 | 1 | 1 | 2 | 1.4 by 2 | 0.8 | | 381 | 0.12.0 | | | **Read a `Touches:` list from a plan kept in Jira as from one in todo.md, with a test that converts a description through `adf_codec`.** | 1 | 2 | 1 | 2 | 2 | 1.5 by 2 | 0.7 | @@ -132,6 +133,12 @@ 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 ` 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. +### 393. Step an L 3 worker one rung up and an L 4 worker two up from the project's rung, as lilleman ruled on 2026-11-14. + +lilleman ruled on 2026-11-14 (`docs/decisions.md` → the routing ladder entry, the 2026-11-14 note) that an L 3 task steps one rung up from the project's rung and an L 4 task two up, in every project and for delegated subagents. `bin/model_routing/ladder.py`'s `WORKER_STEPS` still reads `{1: -1, 2: -1, 3: 0, 4: 1}`. The 0.11.0 release review's principles pass found the gap, and lilleman chose on 2026-11-16 to file it for 0.12.0 instead of doing it in that review. + +Set `WORKER_STEPS` to `{1: -1, 2: -1, 3: 1, 4: 2}`. Then re-derive, from the ruling, the expected rungs of the 26 routing tests that pin the old steps: `bin/model_routing/test_ladder.py`, `bin/subagent_rung/test_subagent_rung.py`, and the routing, step and worker-argument tests in `bin/loop_claude/test_loop_claude.py` and `bin/loop_claude/test_black_box.py`. On an Opus 5.5 project, an L 3 worker or subagent then runs on Fable 5.2 at low, and an escalation stops without lilleman's yes at Opus 5.5 at xhigh; an L 4 one runs on Fable 5.2 at medium, and stops at Fable 5.2 at high. Reword the 2026-11-14 note's "hold until" sentence once the steps change, and cite the routing figures' stamp 2026-11-14T00:59:50Z as settled. + ### 298. 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. 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.