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:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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]
|
||||
@@ -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,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))
|
||||
|
||||
@@ -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
@@ -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:])
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user