Answer stability round 1: sort imports, share rank_todo's check, scope YAML to compose and workflows, judge only newly unsorted ignore blocks, cut heredoc bodies, check COPY --from and container:, log what each override let through, keep CLAUDE.md lines for what the hook cannot see

This commit is contained in:
2026-10-12 23:15:49 +02:00
parent 3ef8c196cd
commit 2f2a770392
5 changed files with 93 additions and 49 deletions
+3 -1
View File
@@ -117,7 +117,8 @@ Prose describing the code as it stands — a comment, a README, an `AGENTS.md`,
- Tear down test containers after a run.
- Give a subagent only the access its job needs, and state the limits in its prompt. One that only reads, such as a prose review, gets no shell and no edits. One that probes a build tags the image as throwaway and removes it afterwards, writes only to the session scratchpad, and removes no image or file it did not create.
- Check `README.md` first for build, test, install, and codegen commands; one that misbehaves is fixed per "A false claim is a bug". Refresh `README.md` whenever you change what it describes ("Refresh `README.md` to match").
- Sort wherever order carries no meaning (`~/.claude/principles/technical-principles.md`) — attributes, array and object keys, enum members, imports and table rows. Exception: `id` goes first.
- Sort wherever order carries no meaning (`~/.claude/principles/technical-principles.md`) — attributes, array and object keys, enum members, imports, table rows and line-based file lists. Exception: `id` goes first.
- Pin a container image to its full patch version where `~/.claude/bin/rule-hook` does not check it, such as in a test fixture, a Kubernetes manifest or a `docker run` line.
## Naming files & folders
- Name by what's inside. BANNED: `scripts`, `utils`, `helpers`, `misc`, `common`, `lib`, `stuff`. GOOD: `e2e-tests/`, `db-migrations/`, `release-tooling/`.
@@ -128,6 +129,7 @@ Prose describing the code as it stands — a comment, a README, an `AGENTS.md`,
The rules every project follows, compose-not-entangle first: `~/.claude/principles/technical-principles.md`. Read it before writing, designing or reviewing code.
## Git, commits, and PRs
- Mark no commit, PR, issue comment or file as the work of Claude, Anthropic or an agent.
- Commit message and PR title: prefixed with the ticket ID when the work has one. Example: `ABC-123 - Regression tests for GET /v4/clients`. Never include the repo/project name (like "twu-4") — we're already in that context.
- PR summary: short and concise. No test plan (it lives in the ticket), no link to the ticket (it's in the title).
- When the work has a ticket, read it before starting: verify the change matches it and pull useful context from it.
+18 -1
View File
@@ -91,6 +91,11 @@ def main(argv: list[str]) -> int:
if isinstance(args, Failure):
return fail(args)
check, todo = args
if check:
failures = check_failures(todo)
for line in failures:
print(line, file=sys.stderr)
return 1 if failures else 0
texts = read_all(todo)
if isinstance(texts, Failure):
return fail(texts)
@@ -98,7 +103,7 @@ def main(argv: list[str]) -> int:
if isinstance(ranked, Failure):
return fail(ranked)
if ranked.text != texts[0]:
unwritten = Failure(f"{todo}: not ranked; run rank_todo.py on it") if check else write(todo, ranked.text)
unwritten = write(todo, ranked.text)
if unwritten:
return fail(unwritten)
for line in ranked.under_bar:
@@ -106,6 +111,18 @@ def main(argv: list[str]) -> int:
return 1 if ranked.under_bar else 0
def check_failures(todo: pathlib.Path) -> list[str]:
"""Why --check fails on todo, empty when it passes."""
texts = read_all(todo)
if isinstance(texts, Failure):
return [texts.reason]
ranked = rank(*texts)
if isinstance(ranked, Failure):
return [ranked.reason]
unranked = [] if ranked.text == texts[0] else [f"{todo}: not ranked; run rank_todo.py on it"]
return unranked + [f"{todo}: {line}" for line in ranked.under_bar]
def fail(failure: Failure) -> int:
print(failure.reason, file=sys.stderr)
return 1
+23 -29
View File
@@ -6,19 +6,22 @@ usage: rule-hook (a PreToolUse hook: reads the call as JSON on stdin)
settings.json runs it before each Bash, Edit, MultiEdit and Write call, in every session and
subagent. The rules:
action-pin a workflow's `uses:` names a semver tag, such as @v3 or @v3.1.2
action-pin a workflow's or action.yml's `uses:` names a semver tag, such as @v3 or @v3.1.2
commit-one-line git commit takes its message as one -m with no newline
ignorefile-sorted each block of a .*ignore file is sorted; a blank line or comment ends a block
image-pin a Dockerfile FROM or YAML `image:` names a full patch version or a digest
ignorefile-sorted each block of a .*ignore file that an edit leaves unsorted is sorted; a blank
line or comment ends a block
image-pin a Dockerfile FROM or COPY --from, or a compose or workflow `image:` or
`container:`, names a full patch version, a date stamp or a digest
no-ai-attribution no Claude or Anthropic co-author or generated-with line, in a file written or
in a git, gh or tea command
todo-rank-check a commit that stages todo.md, or commits with -a while todo.md has changes,
needs rank_todo.py --check to pass on it
A call overrides a rule with `# rule-override <rule>: <reason>`: in a Bash command, as a trailing
comment; in a file, as a comment line in the text the edit writes. Each override that let a call
through is appended to rule-overrides.tsv in the checkout's git directory: UTC time, branch, rule,
reason. `rule-hook overrides` prints the lines for the current branch.
A call overrides a rule with `# rule-override <rule>: <reason>`: anywhere in a Bash command, such as
a trailing comment; in a file, as a comment line in the text the edit writes. Each override that
let a call through is appended to rule-overrides.tsv in the checkout's git directory: UTC time,
branch, rule, reason, and the file written or the command's first line. `rule-hook overrides`
prints the lines for the current branch.
Exit 2 with the rule, why it holds and how to override it, when a rule blocks the call; 0 otherwise.
Exit 1, a non-blocking error to Claude Code, on input it cannot read.
@@ -31,9 +34,8 @@ import sys
import time
import typing
from failure import Failure
import rank_todo
from rule_hook.rules import Breach, command_breaches, commits, file_breaches, overrides, RULES
import rank_todo
from utc_stamp import utc
LOG = "rule-overrides.tsv"
@@ -58,14 +60,15 @@ def main(argv: list[str], stdin: str) -> int:
if checked is None:
return 0
text, directory, breaches = checked
what = text.split("\n", 1)[0] if tool == "Bash" else str(given.get("file_path"))
granted = overrides(text)
for breach in breaches:
if breach.rule in granted:
log_override(directory, breach.rule, granted[breach.rule])
log_override(directory, breach.rule, granted[breach.rule], what)
blocking = [breach for breach in breaches if breach.rule not in granted]
if not blocking:
return 0
where = "the command, as a trailing comment" if tool == "Bash" else "the text you write, as a comment line"
where = "the command" if tool == "Bash" else "the text you write, as a comment line"
for rule in sorted({breach.rule for breach in blocking}):
details = "; ".join(breach.detail for breach in blocking if breach.rule == rule)
print(f"Blocked by rule {rule}: {details}. The rule: {RULES[rule]}. Where it does not fit this case, add `# rule-override {rule}: <reason>` to {where}; larv-review's judge rules on the reason.", file=sys.stderr)
@@ -75,22 +78,22 @@ def main(argv: list[str], stdin: str) -> int:
def checked_call(tool: str, given: dict[str, typing.Any], cwd: str) -> tuple[str, str, list[Breach]] | None:
"""The text that may carry an override, the directory whose checkout logs it, and the call's breaches."""
if tool == "Bash":
command = given.get("command", "")
command = str(given.get("command") or "")
todo = [breach for commit in commits(command, cwd) for breach in todo_breaches(commit.directory, commit.all)]
return command, cwd, command_breaches(command, cwd) + todo
path = given.get("file_path", "")
path = str(given.get("file_path") or "")
if tool not in ("Edit", "MultiEdit", "Write") or not path:
return None
before = read(path)
edits = [given] if tool == "Edit" else given.get("edits", [])
edits = [given] if tool == "Edit" else [edit for edit in given.get("edits") or [] if isinstance(edit, dict)]
if tool == "Write":
added = after = given.get("content", "")
added = after = str(given.get("content") or "")
else:
after = before
for edit in edits:
old, new = edit.get("old_string", ""), edit.get("new_string", "")
old, new = str(edit.get("old_string") or ""), str(edit.get("new_string") or "")
after = after.replace(old, new) if edit.get("replace_all") else after.replace(old, new, 1)
added = "\n".join(edit.get("new_string", "") for edit in edits)
added = "\n".join(str(edit.get("new_string") or "") for edit in edits)
return added, os.path.dirname(path), file_breaches(path, before, added, after)
@@ -101,25 +104,16 @@ def todo_breaches(directory: str, staged_all: bool) -> list[Breach]:
changed = git(top, "diff", "--cached", "--name-only", "--", "todo.md") or (staged_all and git(top, "diff", "--name-only", "--", "todo.md"))
if not changed:
return []
todo = pathlib.Path(top) / "todo.md"
texts = rank_todo.read_all(todo)
if isinstance(texts, Failure):
return [Breach("todo-rank-check", texts.reason)]
ranked = rank_todo.rank(*texts)
if isinstance(ranked, Failure):
return [Breach("todo-rank-check", ranked.reason)]
if ranked.text != texts[0]:
return [Breach("todo-rank-check", f"{todo} is not ranked")]
return [Breach("todo-rank-check", line) for line in ranked.under_bar]
return [Breach("todo-rank-check", line) for line in rank_todo.check_failures(pathlib.Path(top) / "todo.md")]
def log_override(directory: str, rule: str, reason: str) -> None:
def log_override(directory: str, rule: str, reason: str, what: str) -> None:
common = git(existing(directory), "rev-parse", "--path-format=absolute", "--git-common-dir")
if not common:
return
branch = git(existing(directory), "branch", "--show-current") or "HEAD"
with open(pathlib.Path(common) / LOG, "a", encoding="utf-8") as log:
log.write("\t".join([utc(time.time()), branch, rule, " ".join(reason.split())]) + "\n")
log.write("\t".join([utc(time.time()), branch, rule, " ".join(reason.split()), " ".join(what.split())]) + "\n")
def print_overrides(directory: str) -> int:
+20 -10
View File
@@ -10,15 +10,19 @@ RULES = {
"ignorefile-sorted": "each block of an ignore file is sorted, 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",
"image-pin": "a container image is pinned to its full patch version, such as node:24.18.1-bookworm-slim, so the same commit builds the same image on every day; a bot such as Renovate raises the bumps as reviewable PRs",
"no-ai-attribution": "no commit, PR, issue comment or file carries a Claude or Anthropic attribution, such as a co-author trailer or a generated-with line",
"todo-rank-check": "a committed todo.md passes ~/.claude/bin/rank_todo.py --check; run rank_todo.py on it",
"todo-rank-check": "a committed todo.md passes ~/.claude/bin/rank_todo.py --check",
}
OVERRIDE = re.compile(r"#\s*rule-override ([a-z-]+):[ \t]*(\S[^\n]*)")
# [-] keeps this file from matching itself.
ATTRIBUTION = re.compile(r"co-authored[-]by:[^\n]*\b(?:claude|anthropic)\b|generated with \[?claude code", re.IGNORECASE)
SEMVER = re.compile(r"v?\d+(?:\.\d+){0,2}")
PATCH = re.compile(r"v?\d+\.\d+\.\d+(?:[-+_.].*)?")
# Two-part tags such as postgres:16.4 stay blocked: the rule bans node:24.18, which reads the same, so such an image takes an override.
PATCH = re.compile(r"v?\d+\.\d+\.\d+(?:[-+_.].*)?|.*\d{8}.*")
FROM = re.compile(r"^[ \t]*FROM[ \t]+(?:--\S+[ \t]+)*(\S+)(?:[ \t]+AS[ \t]+(\S+))?", re.IGNORECASE | re.MULTILINE)
IMAGE = re.compile(r"^[ \t]*(?:-[ \t]+)?image:[ \t]*[\"']?([^\s\"'#]+)", re.MULTILINE)
COPIED = re.compile(r"^[ \t]*COPY[ \t].*?--from=(\S+)", re.IGNORECASE | re.MULTILINE)
IMAGE = re.compile(r"^[ \t]*(?:-[ \t]+)?(?:image|container):[ \t]*[\"']?([^\s\"'#{]+)", re.MULTILINE)
BUILD = re.compile(r"^[ \t]*build:", re.MULTILINE)
HEREDOC = re.compile(r"<<-?[ \t]*([\"']?)(\w+)\1[^\n]*\n.*?^[ \t]*\2[ \t]*$", re.DOTALL | re.MULTILINE)
USES = re.compile(r"^[ \t]*(?:-[ \t]+)?uses:[ \t]*[\"']?([^\s\"'#]+)", re.MULTILINE)
ASSIGNMENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*=")
SEPARATORS = {"\n", "&&", "||", ";", "|", "&", "(", ")", ";;", "|&"}
@@ -46,10 +50,11 @@ def overrides(text: str) -> dict[str, str]:
def segments(command: str) -> list[list[str]] | None:
"""The command's simple commands as words, or None when it does not parse."""
lexer = shlex.shlex(command, posix=True, punctuation_chars="();<>|&\n")
"""The command's simple commands as words, each heredoc's body cut to a line break, or None when it does not parse."""
lexer = shlex.shlex(HEREDOC.sub(lambda heredoc: heredoc.group(0).split("\n", 1)[0] + "\n", command), posix=True, punctuation_chars="();<>|&\n")
lexer.whitespace = " \t\r"
lexer.whitespace_split = True
# shlex also ends a word at a # inside it, as in fix#2, which bash does not; after lexing, a quoted # cannot be told apart.
try:
words = list(lexer)
except ValueError:
@@ -142,13 +147,18 @@ def file_breaches(path: str, before: str, added: str, after: str) -> list[Breach
breaches.append(Breach("no-ai-attribution", f"{path} would carry an attribution"))
if name.startswith(("Dockerfile", "Containerfile")) or name.endswith((".dockerfile", ".Dockerfile", ".containerfile")):
stages = {stage.lower() for _, stage in FROM.findall(before + "\n" + after) if stage}
images = [image for image, _ in FROM.findall(added) if image.lower() not in stages | {"scratch"}]
breaches += [Breach("image-pin", f"{path}: FROM {image}") for image in images if not pinned(image)]
if name.endswith((".yml", ".yaml")):
breaches += [Breach("image-pin", f"{path}: image: {image}") for image in IMAGE.findall(added) if not pinned(image)]
images = [image for image, _ in FROM.findall(added)] + COPIED.findall(added)
breaches += [Breach("image-pin", f"{path}: {image}") for image in images if image.lower() not in stages | {"scratch"} and not image.isdigit() and not pinned(image)]
workflow = any(folder in "/" + path for folder in ("/.github/workflows/", "/.gitea/workflows/")) or name in ("action.yml", "action.yaml")
if "compose" in name and name.endswith((".yml", ".yaml")) or workflow:
# A compose service that builds names its own image with image:, untagged.
built = "compose" in name and BUILD.search(after) is not None
breaches += [Breach("image-pin", f"{path}: {image}") for image in IMAGE.findall(added) if not pinned(image) and not (built and ":" not in image)]
if workflow:
breaches += [Breach("action-pin", f"{path}: uses: {action}") for action in USES.findall(added) if not tagged(action)]
if name.startswith(".") and name.endswith("ignore"):
breaches += [Breach("ignorefile-sorted", f"{path}: {block[0]!r} through {block[-1]!r} are out of order") for block in blocks(after) if block != sorted(block)]
already = [block for block in blocks(before) if block != sorted(block)]
breaches += [Breach("ignorefile-sorted", f"{path}: {block[0]!r} through {block[-1]!r} are out of order") for block in blocks(after) if block != sorted(block) and block not in already]
return breaches
+29 -8
View File
@@ -8,8 +8,8 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from rule_hook.rules import blocks, Breach, command_breaches, Commit, commits, file_breaches, overrides
from test_env import isolated_env
from test_rank_todo import DECISIONS, README, TODO
from test_env import isolated_env
HOOK = pathlib.Path(__file__).resolve().parents[1] / "rule-hook"
# Built from parts, so this file carries no attribution of its own.
@@ -58,27 +58,43 @@ class CommandBreaches(unittest.TestCase):
self.assertEqual(rules(command_breaches(f"tea pr create --description '{TRAILER}'", "/r")), ["no-ai-attribution"])
self.assertEqual(command_breaches(f"grep -rn '{TRAILER}' .", "/r"), [])
def test_a_heredoc_body_is_no_shell_text(self):
self.assertEqual(rules(command_breaches("git commit -F - <<'EOF'\nTitle\n\nIt's the body\nEOF\necho done", "/r")), ["commit-one-line"])
self.assertEqual(rules(command_breaches("git commit -m \"$(cat <<'EOF'\nIt's one line\nEOF\n)\"", "/r")), ["commit-one-line"])
def test_a_command_that_does_not_parse_breaks_nothing(self):
self.assertEqual(command_breaches("git commit -m 'open", "/r"), [])
class FileBreaches(unittest.TestCase):
def test_an_image_needs_a_patch_version_or_a_digest(self):
added = "FROM node:24 AS build\nFROM node:24.18.1-bookworm-slim\nFROM alpine@sha256:ab\nFROM build\nFROM scratch\nFROM ${BASE}\nFROM python\n"
self.assertEqual([breach.detail for breach in file_breaches("Dockerfile", "", added, added)], ["Dockerfile: FROM node:24", "Dockerfile: FROM python"])
added = "FROM node:24 AS build\nFROM node:24.18.1-bookworm-slim\nFROM alpine@sha256:ab\nFROM debian:bookworm-20240926-slim\nFROM build\nFROM scratch\nFROM ${BASE}\nFROM python\nCOPY --from=build /a /a\nCOPY --from=0 /b /b\nCOPY --chown=1 --from=alpine:3 /c /c\n"
self.assertEqual([breach.detail for breach in file_breaches("Dockerfile", "", added, added)], ["Dockerfile: node:24", "Dockerfile: python", "Dockerfile: alpine:3"])
def test_a_stage_named_outside_the_edit_is_no_image(self):
self.assertEqual(file_breaches("app.dockerfile", "FROM node:24.1.0 AS base\n", "FROM base\n", "FROM node:24.1.0 AS base\nFROM base\n"), [])
def test_yaml_images_and_actions_are_checked(self):
added = " image: mysql:8.4\n - image: 'mysql:8.4.7'\n - uses: actions/checkout@v4\n - uses: a/b@0123456789abcdef0123456789abcdef01234567\n - uses: ./local\n"
self.assertEqual(rules(file_breaches("ci.yml", "", added, added)), ["image-pin", "action-pin"])
def test_a_workflow_checks_its_images_and_actions(self):
added = " container: node:24\n image: mysql:8.4\n - image: 'mysql:8.4.7'\n - uses: actions/checkout@v4\n - uses: a/b@0123456789abcdef0123456789abcdef01234567\n - uses: ./local\n"
self.assertEqual(rules(file_breaches("/r/.gitea/workflows/ci.yml", "", added, added)), ["image-pin", "image-pin", "action-pin"])
def test_a_compose_file_checks_its_images_but_not_the_one_it_builds(self):
self.assertEqual(rules(file_breaches("compose.yaml", "", " image: redis\n", " image: redis\n")), ["image-pin"])
after = " app:\n build: .\n image: myapp\n"
self.assertEqual(file_breaches("docker-compose.yml", "", after, after), [])
def test_other_yaml_is_not_checked(self):
added = "image: /assets/og.png\nimage: { type: string }\nuses: a/b@main\n"
self.assertEqual(file_breaches("_config.yml", "", added, added), [])
def test_an_ignore_file_sorts_each_block_split_by_blank_lines_and_comments(self):
self.assertEqual(blocks("b\na\n\n# c\nd\n# e\nf\n"), [["b", "a"], ["d"], ["f"]])
self.assertEqual(rules(file_breaches(".dockerignore", "", "x", "b\na\n")), ["ignorefile-sorted"])
self.assertEqual(file_breaches(".gitignore", "", "x", "*\n\n!a\n!b\n"), [])
def test_a_block_unsorted_before_the_edit_is_left_alone(self):
self.assertEqual(file_breaches(".gitignore", "node_modules\n.env\n\ndist\n", "out", "node_modules\n.env\n\ndist\nout\n"), [])
def test_an_attribution_in_any_file_breaks(self):
self.assertEqual(rules(file_breaches("notes.md", "", TRAILER, TRAILER)), ["no-ai-attribution"])
@@ -105,7 +121,7 @@ class Hook(unittest.TestCase):
ran = hook({"cwd": self.repo, "tool_input": {"file_path": f"{self.repo}/sub/Dockerfile", "content": content}, "tool_name": "Write"}, self.repo)
self.assertEqual((ran.returncode, ran.stderr), (0, ""))
listed = subprocess.run([str(HOOK), "overrides"], capture_output=True, check=True, cwd=self.repo, env=isolated_env(), text=True).stdout
self.assertRegex(listed, r"^\S+Z\tchunk\timage-pin\tthe vendor tags no patch versions\n$")
self.assertRegex(listed, r"^\S+Z\tchunk\timage-pin\tthe vendor tags no patch versions\t\S+/sub/Dockerfile\n$")
def test_an_edit_is_judged_on_the_file_it_leaves(self):
pathlib.Path(self.repo, ".gitignore").write_text("a\nc\n")
@@ -123,7 +139,12 @@ class Hook(unittest.TestCase):
git(self.repo, "add", "todo.md")
ran = hook(call, self.repo)
self.assertEqual(ran.returncode, 2)
self.assertIn("todo.md is not ranked", ran.stderr)
self.assertIn("todo.md: not ranked", ran.stderr)
def test_a_missing_field_breaks_nothing(self):
for given in [{"command": None}, {"content": None, "file_path": f"{self.repo}/a.md"}]:
with self.subTest(given):
self.assertEqual(hook({"cwd": self.repo, "tool_input": given, "tool_name": "Write" if "content" in given else "Bash"}, self.repo).returncode, 0)
def test_unreadable_input_does_not_block(self):
ran = subprocess.run([str(HOOK)], capture_output=True, env=isolated_env(), input="{", text=True)