Answer principles round 1: 2 🔴, 9 🟡 (0 misread); explicit record versions in place of the Confluence store's hidden state, the routing ruling filed as item 393 for 0.12.0, rule-hook catching heavy runs through uv, poetry, sudo and doas, one unreleased heading, one owner of the no-item message, typed Jira issues, a turn that gives its failure as a value, outcome tests for the Atlassian client, an Emptied reason type, an injected clock and git in touch-predictions, and paired record names

This commit is contained in:
2026-11-16 16:12:36 +01:00
parent a60bfdbc1c
commit ba21a1efcd
41 changed files with 406 additions and 280 deletions
+2 -2
View File
@@ -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.
+12 -12
View File
@@ -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")
+25 -20
View File
@@ -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):
+2 -2
View File
@@ -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();&|<>")
+2 -3
View File
@@ -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)
+14 -8
View File
@@ -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}."
+2 -2
View File
@@ -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 ""}")
+6 -3
View File
@@ -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
+5 -2
View File
@@ -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)
+6 -6
View File
@@ -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:
+6 -6
View File
@@ -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:
+3 -3
View File
@@ -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):
+2
View File
@@ -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:
+3 -3
View File
@@ -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_)
+41 -31
View File
@@ -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}")
+2 -1
View File
@@ -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:
+10
View File
@@ -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)
+2 -2
View File
@@ -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:
+2 -3
View File
@@ -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"))
+6 -7
View File
@@ -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:
+2 -1
View File
@@ -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()))
+29 -45
View File
@@ -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}")
+14 -3
View File
@@ -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())
+6 -2
View File
@@ -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)
+9
View File
@@ -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
+6 -1
View File
@@ -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)
+56 -21
View File
@@ -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
+60 -54
View File
@@ -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:
+4 -4
View File
@@ -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):
+8 -4
View File
@@ -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:
@@ -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")]
+8 -1
View File
@@ -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"})
+1 -1
View File
@@ -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",
+1 -1
View File
@@ -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"])
+3 -2
View File
@@ -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:
+9 -7
View File
@@ -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 <bullet>, 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
+9 -8
View File
@@ -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}."
+4 -3
View File
@@ -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
@@ -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")
+4 -4
View File
@@ -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://<site>/wiki/spaces/<space>/pages/<page ID>"`, 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/<key>/<worktree>/<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 `<worktree>` is named for the worktree that ran `open`, and `open` removes the folders of worktrees git no longer lists, so a chunk's copy doesn't outlive its worktree.
- **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/<key>/<worktree>/<record>.version`, since `save` runs in a later process, and each save keeps the version it left for the next. Every other tool writes over the version its own read gave, so a read by another tool, such as larv-review's, never moves the version an edit in `project-record` rests on. The folder `<worktree>` is named for the worktree that ran `open`, and `open` removes the folders of worktrees git no longer lists, so a chunk's copy doesn't outlive its worktree.
- **The page holds ADF, which adf-codec converts both ways**, so a teammate reads the record as Confluence renders it. Where adf-codec cannot convert the markdown, the write fails with adf-codec's error. A node markdown cannot hold reads as text: a mention as its name, a macro as `_(<macro> not included)_`. So the next write replaces it with that text, and a record page should hold only what markdown can.
## project config: 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/<key>/`, 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`.
+8 -1
View File
@@ -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 <id>` 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.