Merge pull request 'Block a docker run or docker create that sets no memory limit, and read docker's TLS and buildx --builder options as taking a value' (#372) from item-228 into main

This commit was merged in pull request #372.
This commit is contained in:
2026-10-24 01:00:41 +02:00
14 changed files with 180 additions and 49 deletions
+1
View File
@@ -25,6 +25,7 @@
!bin/claude_code/
!bin/claude_code/*.py
!bin/comprehension_history.py
!bin/docker_command.py
!bin/failure.py
!bin/file_writes.py
!bin/git_command.py
+1
View File
@@ -16,6 +16,7 @@ Decisions live in `docs/decisions.md`:
- loop-claude: one session per project, its id derived from the checkout's path relative to `~/code`, or to `/` outside it
- loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
- 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
- machine load: every container a session starts has a memory limit and a swap limit as large as its work needs, which rule-hook's `docker-run-memory` enforces on `docker run` and `docker create`, and no daemon-wide cap limits all containers together
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
- reading cost and `score-outcomes`: each waits for 10 finished chunks before it shows a median
- reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- rule-hook has a new rule, `docker-run-memory`. It blocks a `docker run` or `docker create` that lacks a memory limit or a swap limit, such as `--memory 4g --memory-swap 4g`, sized to what the work needs. `--memory-swap -1`, unlimited swap, counts as none. `CLAUDE.md` asks for the same limits on a container a script or a compose file starts, which rule-hook can't see. rule-hook's `run-heavy` rule also now reads docker's `--tlscacert`, `--tlscert`, `--tlskey` and buildx's `--builder` as options that take a value, and reads `docker container run` as a run: `docker --tlscacert ca.pem build .` was not blocked outside run-heavy before.
- Reviewers now mark a 🔴 or 🟡 `[misread]` where it arose because the implementer misread code that had already shipped. A round's commit title now counts the marked findings, as in `Answer stability round 1: 1 🔴, 2 🟡 (1 misread); …`, and rule-hook's `round-title-counts` blocks a round title without that count. `score-outcomes` shows the count on each finished item, and lists it after the medians for each chunk whose round titles carry it, newest first. A chunk whose round titles predate this change reads as unknown.
- Sessions running at once no longer starve the machine. A new tool, `run-heavy <command>`, runs a heavy command, such as a full gate, mutation tests, an e2e run or a `docker build`, once it holds one of the machine's heavy slots: one per 4 CPUs, shared by every session. `CLAUDE.md` has every session run its heavy commands under it, and rule-hook blocks a `docker build` or a mutation run outside it. loop-claude now waits to start a worker while less than a quarter of the machine's memory is available.
- larv-review's skill now says a commit answering the external auto-reviewer takes no `Answer <pass> round` title, and that `larv-review round-count` doesn't list the auto-reviewer. A worker who followed the skill used to get a "not a pass" warning.
+1
View File
@@ -65,6 +65,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
- Keep the project's main checkout (e.g. `~/code/log`, never a worktree) current: when it is behind `origin` — a merge landed, or a fetch shows it — run `git pull --ff-only` there instead of reporting the lag, never with `--autostash`: a dirty checkout is a finding to report, not to carry along.
- Run a project's language runtime, package manager, and task runner through its container/tooling setup, never directly on the host unless a decision puts them there. Example: `docker compose run --rm app <tool> …`.
- Tear down test containers after a run.
- Give every container you start a memory limit and a swap limit, as large as its work needs: `--memory 4g --memory-swap 4g` on `docker run`, or `mem_limit` and `memswap_limit` in a compose file, scripts included. rule-hook checks only the `docker run` and `docker create` in your Bash commands.
- A heavy command loads the machine for minutes: a full gate, mutation tests, an e2e run, a `docker build`. Run each one under `~/.claude/bin/run-heavy`, as in `~/.claude/bin/run-heavy ./ci.sh`. run-heavy waits for one of the heavy slots that every session on the machine shares. Run it in the background, since the wait can outlast the Bash tool's timeout.
- Delegate a task to a subagent only when you need just its conclusion: a search or read across many files, or work independent enough to run in parallel. Keep edits, and whatever you must check line by line, in your own thread: you would read a delegated diff again to check it. Score the task's L as for a `todo.md` item; a task that changes no file, such as a search, is L 1. `<model>` below is the project's model id, such as `claude-opus-5-5`: the one loop-claude's prompt names as the project's, or else your own. Launch the subagent with the model and effort of the first case that fits:
1. A reviewer, a comprehension seat or the security pass: those loop-claude's prompt gives it. Given none, pass no model or effort, so it runs on your model.
+1 -1
View File
@@ -125,7 +125,7 @@ pytest_add_cli_args=-k
Then, in the copy: `uvx --with pytest 'mutmut>=3,<4' run && uvx --with pytest 'mutmut>=3,<4' results`, and `uvx --with pytest 'mutmut>=3,<4' show <mutant>` to see a mutant's change. The config keys are mutmut 3's.
`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; `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `larv_review` imports `rank_todo.py`'s ranking, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge, and `loop_claude` runs `chunk-preflight` as a process of its own. `judge_replay` and `review_replay` share `rung_replay/`: the rung search, the argument reader, the candidate rungs and the exits. `rung_replay/` reads `loop_claude`'s retry count and models file. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
`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; `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them, `rule_hook` imports `rank_todo.py`'s check, `larv_review` imports `rank_todo.py`'s ranking, `score_outcomes` imports `reading_cost`'s record path, `judge_replay` imports `loop_claude`'s judge, and `loop_claude` runs `chunk-preflight` as a process of its own. `judge_replay` and `review_replay` share `rung_replay/`: the rung search, the argument reader, the candidate rungs and the exits. `rung_replay/` reads `loop_claude`'s retry count and models file. `docker_command.py` reads a docker command's subcommand and memory limits for `rule_hook`, and sits at the root so `run_heavy` can read them too. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool; `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read. `routing_figures/` measures loop-claude's archive for loop-claude's routing calls. `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
## Tracking a new file
+57
View File
@@ -0,0 +1,57 @@
"""What a docker command asks of docker: its subcommand, and whether a container it starts has a memory limit and a swap limit."""
import re
from shell_command import launched
# The options of docker, docker buildx and docker compose that take a value, so the value is not read as a subcommand.
DOCKER_VALUED = frozenset({"--ansi", "--builder", "--config", "--context", "--env-file", "--file", "--host", "--log-level", "--parallel", "--profile", "--progress", "--project-directory", "--project-name", "--tlscacert", "--tlscert", "--tlskey", "-c", "-f", "-H", "-l", "-p"})
# The subcommands that make a container, whose memory limits docker reads from the same options.
STARTS_CONTAINER = (["container", "create"], ["container", "run"], ["create"], ["run"])
# A size as docker reads one, such as 4g, 512M or 1.5GiB: the pattern go-units' RAMInBytes parses.
SIZE = r"\d+(?:\.\d+)*[kKmMgGtTpP]?[iI]?[bB]?"
# A swap limit is a size other than 0: docker reads --memory-swap -1 as unlimited swap, and 0 as unset.
SWAP = rf"(?!0+(?:\.0+)*[kKmMgGtTpP]?[iI]?[bB]?$){SIZE}"
def docker_subcommand(arguments: list[str]) -> list[str]:
"""The subcommand docker's arguments name, past its options: such as ["build"], ["compose", "run"] or ["buildx", "build"]."""
positional: list[str] = []
skip = False
for word in arguments:
if skip:
skip = False
elif word.startswith("-"):
skip = word in DOCKER_VALUED
else:
positional.append(word)
if positional[0] not in ("buildx", "compose", "container") or len(positional) == 2:
break
return positional
def unlimited(arguments: list[str]) -> bool:
"""Whether docker's arguments make a container, with docker run or docker create, and leave its memory or its swap without a limit.
The container's own arguments, past its image, are read too: telling them apart needs every value-taking option of docker run. So a -m 4g there reads as a limit, while python -m pytest does not, since pytest is no size.
"""
subcommand = docker_subcommand(arguments)
limited = given(arguments, ("-m", "--memory"), SIZE) and given(arguments, ("--memory-swap",), SWAP)
return subcommand in STARTS_CONTAINER and not limited and not helped(arguments, subcommand)
def given(arguments: list[str], options: tuple[str, ...], pattern: str) -> bool:
"""Whether the arguments give one of the options a value pattern matches, as its next word or attached, as in -m4g or --memory=4g."""
attached = re.compile("|".join(re.escape(option) + ("" if len(option) == 2 else "=") + f"(?:{pattern})" for option in options))
return any(attached.fullmatch(word) or (word in options and re.fullmatch(pattern, following)) for word, following in zip(arguments, [*arguments[1:], ""]))
def unlimited_container(words: list[str]) -> bool:
"""Whether the simple command, directly or through a launcher, starts a container that lacks a memory limit or a swap limit."""
docker = launched(words, {"docker"})
return docker is not None and unlimited(docker.arguments)
def helped(arguments: list[str], subcommand: list[str]) -> bool:
"""Whether docker only prints its help: a --help before the subcommand or as the first word after it, not one the container's own command takes."""
after = arguments.index(subcommand[-1]) + 1
return "--help" in arguments[:after + 1]
+9 -38
View File
@@ -1,53 +1,24 @@
"""Whether a simple command is a heavy one, for the `run-heavy` rule: a docker build, or a run of a mutation tool."""
import posixpath
import re
from docker_command import docker_subcommand
from shell_command import launched, tool_name
# 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", "time", "uvx", "yarn"})
# Each mutation tool, and the words that make its call a mutation run when one of them follows it within two words; where the set is empty, every call is one.
MUTATORS = {"cargo": {"mutants"}, "infection": set(), "mutmut": {"run"}, "stryker": {"run"}}
# Flags with which a tool only prints its help, version or list, so a call that carries one is light. Not -h, which docker run reads as the container's hostname.
LIGHT_FLAGS = frozenset({"--help", "--list", "--version"})
# The options of docker and docker compose that take a value, so the value is not read as a subcommand.
DOCKER_VALUED = frozenset({"--ansi", "--config", "--context", "--env-file", "--file", "--host", "--log-level", "--parallel", "--profile", "--progress", "--project-directory", "--project-name", "-c", "-f", "-H", "-l", "-p"})
def tool_name(word: str) -> str:
"""The tool a word names, such as mutmut for `mutmut>=3,<4` or `.venv/bin/mutmut`; empty for a word that names none, such as a file name."""
named = re.fullmatch(r"([A-Za-z_-]+)(?:[<>=!~@].*)?", posixpath.basename(word))
return named.group(1) if named else ""
BUILDS = (["build"], ["buildx", "build"], ["compose", "build"])
def heavy(words: list[str]) -> bool:
"""Whether the simple command, run directly or through a launcher, is a docker build or a mutation run, or runs one in a container, and is not under run-heavy."""
names = [tool_name(word) for word in words]
if not names or "run-heavy" in names or LIGHT_FLAGS & set(words):
launch = launched(words, {"docker", *MUTATORS})
if launch is None or "run-heavy" in launch.launchers or LIGHT_FLAGS & set(words):
return False
# Past a launcher, the tool may follow the launcher's own options and assignments, as in nice -n 19 docker build or uvx --with pytest mutmut run; without one, the command itself is the tool.
launched = names[0] in LAUNCHERS
reachable = names if launched else names[:1]
docker_at = reachable.index("docker") if "docker" in reachable else None
if docker_at is not None:
subcommand = docker_subcommand(words[docker_at + 1:])
return subcommand in (["build"], ["buildx", "build"], ["compose", "build"]) or (subcommand[-1:] in (["run"], ["exec"]) and mutation_run(names[docker_at + 1:]))
return (launched or names[0] in MUTATORS) and mutation_run(names)
if launch.tool == "docker":
subcommand = docker_subcommand(launch.arguments)
return subcommand in BUILDS or (subcommand[-1:] in (["run"], ["exec"]) and mutation_run([tool_name(word) for word in launch.arguments]))
return mutation_run([launch.tool, *(tool_name(word) for word in launch.arguments)])
def mutation_run(names: list[str]) -> bool:
return any(name in MUTATORS and (not MUTATORS[name] or MUTATORS[name] & set(names[i + 1:i + 3])) for i, name in enumerate(names))
def docker_subcommand(words: list[str]) -> list[str]:
"""The subcommand docker's words name, past its options: such as ["build"], ["compose", "run"] or ["buildx", "build"]."""
positional: list[str] = []
skip = False
for word in words:
if skip:
skip = False
elif word.startswith("-"):
skip = word in DOCKER_VALUED
else:
positional.append(word)
if positional[0] not in ("buildx", "compose") or len(positional) == 2:
break
return positional
+8 -1
View File
@@ -8,8 +8,9 @@ from git_command import commits
from rule_hook.heavy_command import heavy
from review_folder import REPORTS
from shell_command import Simple
from docker_command import unlimited_container
RuleName = typing.Literal["action-pin", "commit-one-line", "ignorefile-sorted", "image-pin", "no-ai-attribution", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check"]
RuleName = typing.Literal["action-pin", "commit-one-line", "docker-run-memory", "ignorefile-sorted", "image-pin", "no-ai-attribution", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check"]
@dataclasses.dataclass(frozen=True)
@@ -29,6 +30,10 @@ RULES: dict[RuleName, Rule] = {
"a commit message is one line, prefixed with the ticket ID when the work has one",
"git commit takes its message as one -m with no line break; -F, a second -m and a heredoc are blocked",
),
"docker-run-memory": Rule(
"a container made with docker run or docker create has a memory limit and a swap limit, as large as its work needs, such as `--memory 4g --memory-swap 4g`, so a runaway container fails alone instead of starving the machine; a swap limit equal to the memory limit keeps it out of swap",
"docker run, docker create, docker container run and docker container create, whether direct or through a launcher such as nice or timeout. A container a script or docker compose starts is not checked",
),
"ignorefile-sorted": Rule(
"each block of an ignore file is sorted in code-point order, as LC_ALL=C sort does, since its order carries no meaning; where order matters, such as a re-include after its exclude, split the block with a blank line or a comment",
"a .*ignore file; a block already unsorted before the edit is left alone",
@@ -132,6 +137,8 @@ def command_breaches(command: str, simples: list[Simple], home: str) -> list[Bre
for simple in simples:
if heavy(simple.words):
breaches.append(Breach("run-heavy", f"run `{' '.join(simple.words)[:80]}` under `~/.claude/bin/run-heavy`, in the background", simple.directory))
if unlimited_container(simple.words):
breaches.append(Breach("docker-run-memory", f"give `{' '.join(simple.words)[:80]}` a memory limit and a swap limit as large as its work needs", simple.directory))
for commit in found:
if commit.from_file:
breaches.append(Breach("commit-one-line", "pass the message as one -m '<line>', not from a file", commit.directory))
+13 -3
View File
@@ -107,12 +107,22 @@ 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 -v /w:/w rust:1.90.0 cargo mutants", "docker compose exec app npx stryker run", "docker run -h box rust:1.90.0 cargo mutants", "nice -n 19 docker build .", "env DOCKER_BUILDKIT=1 docker build .", "time -p docker compose build"]:
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"]:
with self.subTest(command):
self.assertEqual(checked(command), ["run-heavy"])
def test_a_heavy_command_under_run_heavy_or_a_light_docker_or_mutmut_call_passes(self):
for command in ["~/.claude/bin/run-heavy docker build -t x .", "/home/me/.claude/bin/run-heavy uvx mutmut run", "nice -n 19 ~/.claude/bin/run-heavy docker build .", "env X=1 run-heavy docker compose run app mutmut run", "docker images", "docker compose run --rm app go vet", "docker compose run app make build", "uvx 'mutmut>=3,<4' results", "echo docker build", "npx prettier --check infection.json5", "echo mutmut run", "env", "docker build --help", "cargo mutants --list", "infection --version"]:
for command in ["~/.claude/bin/run-heavy docker build -t x .", "/home/me/.claude/bin/run-heavy uvx mutmut run", "nice -n 19 ~/.claude/bin/run-heavy docker build .", "env X=1 run-heavy docker compose run app mutmut run", "docker images", "docker compose run --rm app go vet", "docker compose run app make build", "uvx 'mutmut>=3,<4' results", "echo docker build", "npx prettier --check infection.json5", "echo mutmut run", "env", "docker build --help", "cargo mutants --list", "infection --version", "uvx mutmut a b run"]:
with self.subTest(command):
self.assertEqual(checked(command), [])
def test_a_docker_run_or_create_without_a_memory_limit_breaks_docker_run_memory(self):
for command in ["docker run --rm node:24.22.1-alpine3.24 node x.js", "cd /w && docker run -v /w:/w alpine:3.22.2 true", "docker create alpine:3.22.2", "docker container run alpine:3.22.2 true", "docker container create alpine:3.22.2", "nice -n 19 docker run alpine:3.22.2 true", "docker -H unix:///d.sock run alpine:3.22.2 true", "docker run --memory-swap 4g alpine:3.22.2 true", "docker run -m 4g alpine:3.22.2 true", "docker run --memory=4g alpine:3.22.2 sh -c 'x --memory-swap 4g'", "docker run -m 4g alpine:3.22.2 tool --memory-swap", "docker run -m 4g --memory-swap -1 alpine:3.22.2 true", "docker run -m 4g --memory-swap=0 alpine:3.22.2 true", "~/.claude/bin/run-heavy docker run alpine:3.22.2 true", "docker run --rm python:3.13.1 python -m pytest", "docker run alpine:3.22.2 git commit -m x", "timeout 60 docker run alpine:3.22.2 true", "docker run node:24.22.1-alpine3.24 node --help", "docker run alpine:3.22.2 --help", "docker run -m 4g alpine:3.22.2 sleep 60"]:
with self.subTest(command):
self.assertEqual(checked(command), ["docker-run-memory"])
def test_a_docker_run_with_a_memory_limit_or_another_docker_call_passes_docker_run_memory(self):
for command in ["docker run -m 4g --memory-swap 4g alpine:3.22.2 true", "docker run -m4g --memory-swap=4g alpine:3.22.2 true", "docker run --memory 512M --memory-swap 1g alpine:3.22.2 true", "docker run -m 1073741824 --memory-swap 2g alpine:3.22.2 true", "timeout 60 docker run -m 4g --memory-swap 4g alpine:3.22.2 true", "docker run --rm --memory=1.5GiB --memory-swap=1.5GiB alpine:3.22.2 true", "docker container create -m 1g --memory-swap 1g alpine:3.22.2", "docker run --help", "docker container run --help", "docker --help", "docker ps", "docker images", "docker container ls", "docker compose run --rm app go vet", "docker exec box true", "echo docker run alpine:3.22.2"]:
with self.subTest(command):
self.assertEqual(checked(command), [])
@@ -467,7 +477,7 @@ class Hook(unittest.TestCase):
def test_help_lists_every_rule(self):
helped = subprocess.run([str(HOOK), "--help"], capture_output=True, check=True, env=isolated_env(), text=True).stdout
for rule in ["action-pin", "commit-one-line", "ignorefile-sorted", "image-pin", "no-ai-attribution", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check"]:
for rule in ["action-pin", "commit-one-line", "docker-run-memory", "ignorefile-sorted", "image-pin", "no-ai-attribution", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check"]:
self.assertIn(f" {rule}\n The rule: ", helped)
self.assertIn("reviewer-report\n The rule: a reviewer writes nothing but its report", helped)
self.assertRegex(helped, r" reviewer-report\n( .*\n){2} Takes no override\.\n")
+29 -1
View File
@@ -1,9 +1,12 @@
"""A shell command's simple commands, each as its words and the directory it runs in."""
"""A shell command's simple commands, each as its words and the directory it runs in, and which tool a simple command runs through which launchers."""
import dataclasses
import posixpath
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"})
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();&|<>")
@@ -13,6 +16,14 @@ REDIRECT = re.compile(r"&>>?|[<>]+[&|]?")
PIECE = re.compile(r"""'[^']*'|"(?:\\.|[^"\\])*"|\\.|(?<![^\s;&|()])#[^\n]*""", re.DOTALL)
@dataclasses.dataclass(frozen=True)
class Launch:
"""A tool a simple command runs: the launchers it runs through, such as nice and run-heavy, and the words it is given."""
launchers: frozenset[str]
tool: str
arguments: list[str]
@dataclasses.dataclass(frozen=True)
class Simple:
words: list[str]
@@ -80,3 +91,20 @@ def uncommented(text: str) -> str:
def resolved(base: str, path: str, home: str) -> str:
return posixpath.normpath(posixpath.join(base, home + path[1:] if path == "~" or path.startswith("~/") else path))
def tool_name(word: str) -> str:
"""The tool a word names, such as mutmut for `mutmut>=3,<4` or `.venv/bin/mutmut`; empty for a word that names none, such as a file name."""
named = re.fullmatch(r"([A-Za-z_-]+)(?:[<>=!~@].*)?", posixpath.basename(word))
return named.group(1) if named else ""
def launched(words: list[str], tools: typing.Collection[str]) -> Launch | None:
"""Which of the given tools the simple command runs, directly or through launchers, taking the first one named; None where it doesn't run any of them."""
names = [tool_name(word) for word in words]
# Past a launcher, the tool may follow the launcher's own options and assignments, as in nice -n 19 docker build; without one, the command itself is the tool.
reachable = names if names[:1] and names[0] in LAUNCHERS else names[:1]
at = next((i for i, name in enumerate(reachable) if name in tools), None)
if at is None:
return None
return Launch(frozenset(LAUNCHERS.intersection(names[:at])), names[at], words[at + 1:])
+40
View File
@@ -2687,3 +2687,43 @@ Inherited architect, decided by:
- Navigation, Shape: `bin/rule_hook/heavy_command.py:1` `heavy_command`: a file name in the `rule_hook/` listing points straight at the unit, which the base buried in the 256-line `rules.py:103-150`
- Locality: `bin/rule_hook/heavy_command.py:27` `heavy`: the rule "past a launcher docker can come anywhere, otherwise only first" reads from two plain lines, where the base held a nested conditional
- Locality, Shape: `bin/rule_hook/heavy_command.py:5` `LAUNCHERS`: the tables sit beside their only consumer, so extending them needs no search for other readers
## 2026-10-23T23:00:27Z, PR #372 at 899e8ed, against d1733a2
Ruling: better
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Mid A | same | better | better | same | better |
| Inherited architect | worse | better | same | same | same |
| Maintainability senior | same | better | better | same | better |
| Junior A | same | better | better | same | better |
Mid A, decided by:
- Locality, Shape: `bin/shell_command.py:102` `launched`: one place finds the tool a command runs past its launchers, where heavy held launched, reachable, docker_at and a MUTATORS special case at once
- Shape, Locality: `bin/rule_hook/heavy_command.py:12` `heavy`: two cases and one early exit, with run-heavy read as a launcher instead of a stray word
- Shape, Navigation: `bin/docker_command.py:1` `docker_command`: named by what it holds and serving both docker rules, but at bin's root while only rule_hook reads it, against README's map
- Locality: `bin/docker_command.py:54` `helped`: unlimited leans on helpers defined below it, and helped finds the subcommand by its first occurrence
Inherited architect, decided by:
- Locality: `bin/rule_hook/heavy_command.py:12` `heavy`: four lines on launched and docker_subcommand, though LAUNCHERS now changes both docker rules together
- Navigation: `bin/docker_command.py:1` `docker_command`: README says root modules serve more than one tool, yet it serves only rule_hook, so a reader looks in rule_hook/ first
- Locality: `bin/docker_command.py:32` `unlimited`: the docstring states that the container's own arguments are read, and why python -m pytest is no limit
- Shape: `bin/shell_command.py:1` `shell_command`: the module now does two things, parsing and launcher reading, which only rule_hook uses
Maintainability senior, decided by:
- Locality, Shape: `bin/shell_command.py:102` `launched`: one function, returning a Launch, finds the tool past its launchers, where heavy did it inline with index arithmetic
- Locality, Shape: `bin/rule_hook/heavy_command.py:12` `heavy`: one branch, docker or a mutation tool, with the module no longer holding general shell and docker parsing
- Shape: `bin/docker_command.py:1` `docker_command`: README says root modules serve more than one tool, yet only rule_hook imports it
- Shape: `bin/docker_command.py:32` `unlimited`: the entry point sits between helpers, and unlimited and unlimited_container differ by an unstated input
- Locality: `bin/docker_command.py:54` `helped`: reads --help by position while heavy's LIGHT_FLAGS reads it anywhere, and neither says whether that is meant
Junior A, decided by:
- Locality, Shape: `bin/shell_command.py:102` `launched`: the steps that find a command's tool past its launchers live in one function both rules share
- Shape, Locality: `bin/rule_hook/heavy_command.py:12` `heavy`: from 13 lines mixing three parsings to 8 with a clear docker-or-mutator branch
- Shape: `bin/docker_command.py:1` `docker_command`: a truthful name and docstring, though it sits at bin's root rather than beside rule_hook's rules
- Locality: `bin/rule_hook/rules.py:140` `command_breaches`: the new rule plugs in beside run-heavy as one parallel if
+6
View File
@@ -76,6 +76,12 @@ The cap is 5, `bin/todo_table.py`'s `BUNDLE_MAX_R`, from the same chunks: by the
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, whether direct or inside a container. 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, which rule-hook's `docker-run-memory` enforces on `docker run` and `docker create`, and no daemon-wide cap limits all containers together
2026-10-24, lilleman. Serves goal 1.5. On 2026-10-23 ai-sandbox, then with 8 CPUs and 7.6 GiB of memory, hung until a hard reset, although its one heavy command held a slot. Beside that mutation run, a reviewer's stress probes ran in `docker run` with no memory limit, each to 2 GiB. A limit makes a runaway container fail alone instead of taking the machine with it. A swap limit is needed too: without one, docker lets a container swap as much again as its memory limit, and swapping is how the machine hung. The session sizes both limits, since lilleman wants a project to run heavier work where it needs to. rule-hook reads only the `docker run` and `docker create` in a session's Bash commands. A container a script starts is out of its sight, and so is a compose service, whose limits live in its compose file. `CLAUDE.md` → "Working with the codebase" asks a session for limits there, and todo item 227 caps the containers a heavy command starts under run-heavy.
A daemon-wide cap would see every container: dockerd's `cgroup-parent`, given a memory limit. lilleman turned it down, since it is host config and would cap a project's heavy work too. Valid while sessions start their work in containers on a machine they share.
## principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
2026-10-22, lilleman asked for a rule of seven that holds at every level and is never a hard rule. Serves code health: a reader new to the project should take in each level at once. The numbers follow the sources below, since no single study sets them.
+4
View File
@@ -863,3 +863,7 @@ Read most (opens and searches):
Read most (opens and searches):
- `rules/decisions.md` 1
## Reading cost, chunk e94dd7a98ff8, finished 2026-10-23T12:59:22Z
71809 new input tokens before the first commit.
+9 -5
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 227`
`Next ID = 229`
## Items
@@ -16,7 +16,7 @@
| 59 | 0.4.0 | | | **Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.** | 2 | 1 | 3 | 4 | 3 | 1.4 by 6 | 6.0 |
| 167 | 0.4.0 | | | **Refuse a `/security-review` or `/claude-security` Skill call below the project's rung, as rule-hook refuses such an Agent call.** | 3 | 2 | 3 | 6 | 2 | 1.1 by 4 | 5.6 |
| 6 | 0.4.0 | | decision | **Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.** | 3 | 3 | 3 | 7 | 3 | 1.1 by 5 | 5.3 |
| 225 | 0.4.0 | | | **Add the value-taking options of docker that `DOCKER_VALUED` lacks, so rule-hook's `run-heavy` rule reads their value as a value and not as the subcommand.** | 1 | 1 | 3 | 3 | 2 | 1.5 by 2 | 2.6 |
| 227 | 0.4.0 | | | **Cap the memory of each container a heavy command starts under run-heavy at its slot's share, and have stability-reviewer size a mutation run's concurrency to fit that cap.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 5 | 1.9 |
| 1 | 0.5.0 | | question | **Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.** | 1 | 2 | 1 | 2 | 1 | | 0.0 |
| 219 | 0.5.0 | | | **Name the project's rung `project` in `bin/judge_replay/main.py`, `bin/subagent_rung/main.py` and `bin/review_replay/main.py`, in place of `anchor`, as `bin/model_routing/ladder.py` and `bin/loop_claude` name it.** | 1 | 1 | 3 | 3 | 2 | code health by 2 | 12.0 |
| 224 | 0.5.0 | | | **Split `docs/decisions.md` → `todo.md: one table of items, …`'s 420-word scoring paragraph into one paragraph per choice, and drop the sentences that tell how the goal weights changed.** | 1 | 1 | 1 | 1 | 2 | code health by 2 | 12.0 |
@@ -87,9 +87,13 @@ rule-hook checks Agent calls (item 163) but no Skill calls. A worker that invoke
Claude Code owns that file and writes it. `trust` reads it, changes it and writes it back, so a write that lands in between is lost.
### 225. Add the value-taking options of docker that `DOCKER_VALUED` lacks, so rule-hook's `run-heavy` rule reads their value as a value and not as the subcommand.
### 227. Cap the memory of each container a heavy command starts under run-heavy at its slot's share, and have stability-reviewer size a mutation run's concurrency to fit that cap.
Found by review of PR #370, against code that moved unchanged into `bin/rule_hook/heavy_command.py`. `DOCKER_VALUED` there lacks `--tlscacert`, `--tlscert` and `--tlskey`, so `docker --tlscacert ca.pem build .` is not blocked outside run-heavy, although `RULES["run-heavy"]` in `bin/rule_hook/rules.py` says a docker build is. It also lacks buildx's `--builder`, so `docker buildx --builder x build` gets through. Test first in `bin/rule_hook/test_rule_hook.py`. Also no test checks the "within two words" limit of `mutation_run`: a mutant that widens it survives mutmut; add one.
On 2026-10-23 ai-sandbox, then with 8 CPUs and 7.6 GiB, hung in swap until a hard reset. One heavy command held its slot, as the decision `machine load: a heavy command waits for one of the machine's heavy slots, …` asks: adf-codec's stability reviewer ran Stryker with concurrency 4, each copy running the whole `node --test` suite, in one container that reached 4 GiB. The container was started by the project's own script, so rule-hook's `docker-run-memory` can't see one like it. The slots cap how many heavy commands run at once, not how much memory one takes.
run-heavy cannot place the command in a cgroup: none is delegated to the user, and dockerd starts the containers outside the command's process tree. So run-heavy puts first on the command's `PATH` a `docker` that adds `--memory` and `--memory-swap`, both at the slot's share, to each `docker run`, `docker create` and `docker container run|create` that leaves either without a limit, then runs the real docker. It tells such a call apart with `bin/docker_command.py`'s `unlimited`, which rule-hook's `docker-run-memory` reads too. A container that sets its own limits keeps them, so a project runs heavier work where it needs to (lilleman, 2026-10-24). A compose service, and a docker named by its full path, keep no cap.
The slot's share is a new choice, to record in the decision `machine load: every container a session starts has …`: that decision's elder, `machine load: a heavy command waits …`, starts a worker only while a quarter of the memory is available, so the share is the other three quarters of MemTotal, split evenly across the slots. Update both decisions, run-heavy's help and stability-reviewer's mutation step, which sizes Stryker's or mutmut's concurrency so the run fits the cap. Once run-heavy caps them, let `docker-run-memory` pass a `docker run` under run-heavy, which `shell_command.launched` reports among a call's launchers. Test first in `bin/run_heavy/test_run_heavy.py`.
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.
@@ -311,7 +315,7 @@ The key names the project's session, archive folder and models entry. `project_k
### 155. Lower the reading cost of the files a chunk reads most before its first commit.
`bin/reading-cost` on 2026-10-22: the median of the last 5 chunks is 100,386 new input tokens before their first commit, up from 73,910 for the 5 before them. The files read most over the last 5 were `skills/larv-review/SKILL.md`, 3 times, and `rules/todo-items.md`, 2 times. The chunk that ships this item runs `bin/reading-cost --reset`.
`bin/reading-cost` on 2026-10-24: the median of the last 5 chunks is 125,323 new input tokens before their first commit, up from 123,377 for the 5 before them. The files read most over the last 5 were `bin/score_outcomes/main.py`, 3 times, then `bin/score_outcomes/outcomes.py`, `docs/decisions.md`, `rules/todo-items.md` and `skills/larv-review/SKILL.md`, 2 times each. The chunk that ships this item runs `bin/reading-cost --reset`.
### 51. Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.