Enforce the checkable rules in a hook, with one override marker a judge rules on, and drop them from CLAUDE.md

This commit is contained in:
2026-10-12 23:06:23 +02:00
parent 50a98c2262
commit 39437cef6a
13 changed files with 503 additions and 20 deletions
+3
View File
@@ -40,6 +40,9 @@
!bin/reading_cost/*.py
!bin/repo_checks/
!bin/repo_checks/*.py
!bin/rule-hook
!bin/rule_hook/
!bin/rule_hook/*.py
!bin/statusline.py
!bin/test_*.py
!bin/todo_table.py
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- A hook blocks each Bash, Edit, MultiEdit and Write call that breaks a rule a program can check: a multi-line commit message, a Claude or Anthropic attribution, a container image short of a full patch version, an Action pinned to anything but a semver tag, an unsorted block in an ignore file, and a commit of a `todo.md` that `rank_todo.py --check` rejects. `CLAUDE.md` no longer states those rules; `~/.claude/bin/rule-hook --help` does. A call overrides a rule with `# rule-override <rule>: <reason>`. larv-review lists each override in the PR body, and a judge accepts it, or rejects it and the chunk keeps the rule; one that touches a credential, a security rule or a production system, or cannot be undone, is asked of you.
- A project may opt out of larv-review's architect, product-owner pass or comprehension check in every chunk, through a `docs/decisions.md` entry titled `review opt-out: …` that names the goal that skipping them serves. A project without such an entry is reviewed as before. Opting out of the comprehension check also skips the scoring run due at a release's end, so the floor blocks nothing; the opt-out ends with a chunk that ships a plan item naming the floor, which removes the comprehension check from the entry. The principles audit always runs.
- A README goal states the project's aim and intent, and no longer names a step of the work, such as "kill weak candidates early". Such steps go in a method section further down the README and name the goal they serve.
- The stability reviewer keeps its scratch work in a directory it creates for the run, deletes that directory afterwards, and deletes nothing else.
+3 -6
View File
@@ -21,7 +21,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
### Todo items (`todo.md`, tickets, plans)
- **`todo.md` is mandatory in every project, in one shape**, which `~/.claude/bin/rank_todo.py` checks and ranks; its `--help` shows a valid file. `## Scoring` holds the formula, the bar and the goal weights; `## Items` is one table of every item; `## Details` holds each item's detail under its ID. Cite an item by its ID. The formula, bar and weights are the project's own to tune.
- **Score an item when it is filed or edited, then run `rank_todo.py`.** Each of R, S, A and G is a whole number from 1 to 10:
- **Score an item when it is filed or edited.** Each of R, S, A and G is a whole number from 1 to 10:
- **R** — the risk that the change creates serious bugs or issues.
- **S** — the size of the change.
- **A** — its value to the audience in `README.md` → `## Audience`.
@@ -117,9 +117,7 @@ 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, table rows, and line-based file lists such as `.gitignore`/`.dockerignore`. Exception: `id` goes first.
- Pin GitHub Actions to semver tags (`@v3`, `@v3.1.2`), not commit SHAs — including third-party actions. SHA-pin only in special pipelines that test our own specific builds.
- Pin container images to the **full patch version** everywhere they're referenced — Dockerfile `FROM`, compose `image:`, base images in test fixtures: `node:24.18.1-bookworm-slim`, `mysql:8.4.7`, `alpine:3.23.3`. Never a floating major or minor (`node:24`, `node:24.18`, `:latest`, `:lts`): the same commit then builds a different image on different days, so a green pipeline says nothing about the next run, a base change lands with no diff to review, and any size or performance figure measured against it silently goes stale. Let a bot (Renovate/Dependabot) raise the bumps as reviewable PRs — that is where a base change belongs. (Actions are the exception above: a semver tag is fine there, because the action's own release is the reviewable unit.)
- 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.
## Naming files & folders
- Name by what's inside. BANNED: `scripts`, `utils`, `helpers`, `misc`, `common`, `lib`, `stuff`. GOOD: `e2e-tests/`, `db-migrations/`, `release-tooling/`.
@@ -130,8 +128,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
- Never add `Co-Authored-By: Claude ...`, `🤖 Generated with Claude Code`, or any Claude/Anthropic/Agent marker in commits, PR bodies, issue comments, or anywhere else.
- Commit message and PR title: **one line**, 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.
- 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.
- Branch for a ticket: exactly the ticket ID, nothing more. `ABC-123`, never `ABC-123-some-description`.
+1
View File
@@ -72,6 +72,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `metric-bench [history]` benches cheap static metrics of a project's Python against the places its comprehension history names as hardest; `metric-bench --help` states the metrics and the scores.
- `rank_todo.py [--check] [todo.md]` scores and ranks a project's `todo.md`; `rank_todo.py --help` states the format.
- `reading-cost [--reset] [record]` appends a figure for each chunk `loop-claude` finished to a project's `docs/reading-cost.md`, and says whether the figures rise; `reading-cost --help` states the measure.
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Bash, Edit, MultiEdit and Write call, and `rule-hook --help` states the rules and the override.
- `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it.
Test on the host, with `uv` on `PATH` to fetch mypy and the Python version Install names (`docs/decisions.md` → `bin/`): `python3 -m unittest discover -s bin -p 'test_*.py'`
+1 -1
View File
@@ -15,5 +15,5 @@ class Types(unittest.TestCase):
self.assertIsNotNone(floor, "README.md's Install names `Python 3.N or newer`")
if shutil.which("uv") is None:
self.fail("uv on PATH fetches mypy; see README.md's Test line")
ran = subprocess.run(["uv", "tool", "run", "--python", "%d.%d" % floor, "mypy==2.3.1", "--cache-dir=/dev/null", "--check-untyped-defs", "--disallow-untyped-defs", "--exclude", "/test_", "-p", "claude_code", "-m", "comprehension_history", "-p", "larv_review", "-p", "loop_claude", "-m", "markdown_text", "-p", "metric_bench", "-m", "project_key", "-m", "rank_todo", "-p", "reading_cost", "-m", "statusline", "-m", "todo_table", "-p", "transcript_archive", "-m", "utc_stamp"], capture_output=True, cwd=ROOT / "bin", text=True)
ran = subprocess.run(["uv", "tool", "run", "--python", "%d.%d" % floor, "mypy==2.3.1", "--cache-dir=/dev/null", "--check-untyped-defs", "--disallow-untyped-defs", "--exclude", "/test_", "-p", "claude_code", "-m", "comprehension_history", "-p", "larv_review", "-p", "loop_claude", "-m", "markdown_text", "-p", "metric_bench", "-m", "project_key", "-m", "rank_todo", "-p", "reading_cost", "-p", "rule_hook", "-m", "statusline", "-m", "todo_table", "-p", "transcript_archive", "-m", "utc_stamp"], capture_output=True, cwd=ROOT / "bin", text=True)
self.assertEqual(ran.returncode, 0, ran.stdout + ran.stderr)
Executable
+9
View File
@@ -0,0 +1,9 @@
#!/usr/bin/env python3
import pathlib
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from rule_hook import main
sys.exit(main.main(sys.argv[1:], "" if sys.argv[1:] else sys.stdin.read()))
View File
+158
View File
@@ -0,0 +1,158 @@
"""Block a Claude Code tool call that breaks a checkable rule, unless the call overrides the rule.
usage: rule-hook (a PreToolUse hook: reads the call as JSON on stdin)
rule-hook overrides (prints this branch's overrides)
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
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
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.
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.
"""
import json
import os
import pathlib
import subprocess
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
from utc_stamp import utc
LOG = "rule-overrides.tsv"
def main(argv: list[str], stdin: str) -> int:
if argv in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if argv == ["overrides"]:
return print_overrides(os.getcwd())
if argv:
print(f"unknown arguments: {' '.join(argv)}; see rule-hook --help", file=sys.stderr)
return 1
try:
call = json.loads(stdin)
tool, given, cwd = call["tool_name"], call["tool_input"], call["cwd"]
except (json.JSONDecodeError, KeyError, TypeError) as failure:
print(f"rule-hook cannot read the hook input: {failure}", file=sys.stderr)
return 1
checked = checked_call(tool, given, cwd)
if checked is None:
return 0
text, directory, breaches = checked
granted = overrides(text)
for breach in breaches:
if breach.rule in granted:
log_override(directory, breach.rule, granted[breach.rule])
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"
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)
return 2
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", "")
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", "")
if tool not in ("Edit", "MultiEdit", "Write") or not path:
return None
before = read(path)
edits = [given] if tool == "Edit" else given.get("edits", [])
if tool == "Write":
added = after = given.get("content", "")
else:
after = before
for edit in edits:
old, new = edit.get("old_string", ""), edit.get("new_string", "")
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)
return added, os.path.dirname(path), file_breaches(path, before, added, after)
def todo_breaches(directory: str, staged_all: bool) -> list[Breach]:
top = git(directory, "rev-parse", "--show-toplevel")
if not top or not (pathlib.Path(top) / "todo.md").is_file():
return []
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]
def log_override(directory: str, rule: str, reason: 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")
def print_overrides(directory: str) -> int:
common = git(directory, "rev-parse", "--path-format=absolute", "--git-common-dir")
branch = git(directory, "branch", "--show-current")
if not common or not branch:
print("rule-hook overrides runs on a branch of a git checkout", file=sys.stderr)
return 1
log = pathlib.Path(common) / LOG
lines = log.read_text(encoding="utf-8").splitlines() if log.is_file() else []
for line in lines:
if line.split("\t")[1:2] == [branch]:
print(line)
return 0
def git(directory: str, *args: str) -> str:
try:
ran = subprocess.run(["git", "-C", directory, *args], capture_output=True, text=True)
except OSError:
return ""
return ran.stdout.strip() if ran.returncode == 0 else ""
def existing(directory: str) -> str:
path = pathlib.Path(directory or ".").absolute()
while not path.is_dir():
path = path.parent
return str(path)
def read(path: str) -> str:
try:
return pathlib.Path(path).read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError):
return ""
+176
View File
@@ -0,0 +1,176 @@
import dataclasses
import os
import re
import shlex
# Each rule's why, which the block message gives.
RULES = {
"action-pin": "a GitHub or Gitea Action is pinned to a semver tag, such as @v3 or @v3.1.2, never a commit SHA or a branch; SHA-pin only in a pipeline that tests our own specific builds",
"commit-one-line": "a commit message is one line, prefixed with the ticket ID when the work has one",
"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",
}
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+(?:[-+_.].*)?")
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)
USES = re.compile(r"^[ \t]*(?:-[ \t]+)?uses:[ \t]*[\"']?([^\s\"'#]+)", re.MULTILINE)
ASSIGNMENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*=")
SEPARATORS = {"\n", "&&", "||", ";", "|", "&", "(", ")", ";;", "|&"}
# git's global options that take a value as the next word.
GIT_VALUED = {"-c", "--exec-path", "--git-dir", "--namespace", "--work-tree"}
@dataclasses.dataclass(frozen=True)
class Breach:
rule: str
detail: str
@dataclasses.dataclass(frozen=True)
class Commit:
"""A `git commit` in a command: the directory it runs in, its messages and whether it stages tracked changes."""
directory: str
messages: list[str]
from_file: bool
all: bool
def overrides(text: str) -> dict[str, str]:
return {rule: reason.strip() for rule, reason in OVERRIDE.findall(text) if rule in RULES}
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")
lexer.whitespace = " \t\r"
lexer.whitespace_split = True
try:
words = list(lexer)
except ValueError:
return None
split: list[list[str]] = [[]]
for word in words:
if word in SEPARATORS:
split.append([])
else:
split[-1].append(word)
return [segment for segment in split if segment]
def commits(command: str, cwd: str) -> list[Commit]:
directory = cwd
found = []
for segment in segments(command) or []:
if segment[0] == "cd" and len(segment) > 1:
directory = os.path.join(directory, os.path.expanduser(segment[1]))
assignments = next((at for at, word in enumerate(segment) if not ASSIGNMENT.match(word)), len(segment))
words = segment[assignments:]
commit = git_commit(words[1:], directory) if words[:1] == ["git"] else None
if commit:
found.append(commit)
return found
def git_commit(args: list[str], directory: str) -> Commit | None:
at = 0
while at < len(args) and args[at].startswith("-"):
if args[at] == "-C" and at + 1 < len(args):
directory = os.path.join(directory, os.path.expanduser(args[at + 1]))
at += 2 if args[at] == "-C" or args[at] in GIT_VALUED else 1
if args[at:at + 1] != ["commit"]:
return None
messages: list[str] = []
from_file = staged_all = False
rest = args[at + 1:]
at = 0
while at < len(rest):
word = rest[at]
if word == "--":
break
if word in ("--message", "--file") and at + 1 < len(rest):
messages += [rest[at + 1]] if word == "--message" else []
from_file = from_file or word == "--file"
at += 2
continue
if word.startswith("--message="):
messages.append(word.removeprefix("--message="))
elif word.startswith("--file="):
from_file = True
elif word == "--all":
staged_all = True
elif word.startswith("-") and not word.startswith("--"):
# A cluster such as -am: a valued flag takes the rest of the word, or else the next word.
for place, flag in enumerate(word[1:], 1):
if flag in "mF":
value = word[place + 1:]
if not value and at + 1 < len(rest):
at += 1
value = rest[at]
messages += [value] if flag == "m" else []
from_file = from_file or flag == "F"
break
staged_all = staged_all or flag == "a"
at += 1
return Commit(directory, messages, from_file, staged_all)
def command_breaches(command: str, cwd: str) -> list[Breach]:
breaches = []
parsed = segments(command) or []
if any(word in ("gh", "git", "tea") for segment in parsed for word in segment[:1]):
if ATTRIBUTION.search(command):
breaches.append(Breach("no-ai-attribution", "the command carries an attribution"))
for commit in commits(command, cwd):
if commit.from_file:
breaches.append(Breach("commit-one-line", "pass the message as one -m '<line>', not from a file"))
elif len(commit.messages) > 1 or any("\n" in message.strip() for message in commit.messages):
breaches.append(Breach("commit-one-line", "pass the message as one -m '<line>', with no heredoc, second -m or newline"))
return breaches
def file_breaches(path: str, before: str, added: str, after: str) -> list[Breach]:
"""Breaches in an edit of path: added is the text the edit writes, after the whole file it leaves."""
name = os.path.basename(path)
breaches = []
if ATTRIBUTION.search(added):
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)]
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)]
return breaches
def pinned(image: str) -> bool:
if "$" in image or "{{" in image or "@sha256:" in image:
return True
tail = image.rsplit("/", 1)[-1]
return ":" in tail and PATCH.fullmatch(tail.split(":", 1)[1]) is not None
def tagged(action: str) -> bool:
if action.startswith(("./", "docker://")) or "$" in action or "{{" in action:
return True
return "@" in action and SEMVER.fullmatch(action.rsplit("@", 1)[1]) is not None
def blocks(text: str) -> list[list[str]]:
"""An ignore file's runs of patterns, split at each blank line and comment."""
runs: list[list[str]] = [[]]
for line in text.splitlines():
if line.strip() and not line.startswith("#"):
runs[-1].append(line)
elif runs[-1]:
runs.append([])
return [run for run in runs if run]
+130
View File
@@ -0,0 +1,130 @@
import json
import pathlib
import subprocess
import sys
import tempfile
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
HOOK = pathlib.Path(__file__).resolve().parents[1] / "rule-hook"
# Built from parts, so this file carries no attribution of its own.
TRAILER = "Co-Authored-" + "By: Claude <noreply@anthropic.com>"
def rules(breaches: list[Breach]) -> list[str]:
return [breach.rule for breach in breaches]
def hook(call: dict, cwd: str) -> subprocess.CompletedProcess:
return subprocess.run([str(HOOK)], capture_output=True, cwd=cwd, env=isolated_env(), input=json.dumps(call), text=True)
def git(cwd: str, *args: str) -> str:
return subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@t", *args], capture_output=True, check=True, cwd=cwd, env=isolated_env(), text=True).stdout
class Commits(unittest.TestCase):
def test_cd_and_dash_capital_c_move_the_commit(self):
self.assertEqual(commits("cd a && git -C b commit -am 'x'", "/r"), [Commit("/r/a/b", ["x"], False, True)])
def test_each_message_spelling_is_read(self):
self.assertEqual(commits("git commit --message=a -m b=c --message c -mz", "/r")[0].messages, ["a", "b=c", "c", "z"])
def test_a_file_message_is_seen(self):
self.assertTrue(commits("git commit -F - <<EOF\nx\nEOF", "/r")[0].from_file)
def test_other_git_commands_are_no_commit(self):
self.assertEqual(commits("git log --grep commit; echo git commit", "/r"), [])
def test_a_line_break_separates_commands(self):
self.assertEqual(commits("cd a\nGIT_EDITOR=true git commit -m x", "/r"), [Commit("/r/a", ["x"], False, False)])
class CommandBreaches(unittest.TestCase):
def test_one_line_passes(self):
self.assertEqual(command_breaches("git add . && git commit -m 'ABC-1 - Fix it'", "/r"), [])
def test_a_heredoc_a_second_message_or_a_file_breaks_commit_one_line(self):
for command in ["git commit -m \"$(cat <<'EOF'\nTitle\nEOF\n)\"", "git commit -m a -m b", "git commit -F msg.txt"]:
with self.subTest(command):
self.assertEqual(rules(command_breaches(command, "/r")), ["commit-one-line"])
def test_an_attribution_breaks_only_in_a_git_gh_or_tea_command(self):
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_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"])
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_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_an_attribution_in_any_file_breaks(self):
self.assertEqual(rules(file_breaches("notes.md", "", TRAILER, TRAILER)), ["no-ai-attribution"])
class Overrides(unittest.TestCase):
def test_a_marker_names_a_known_rule_and_a_reason(self):
self.assertEqual(overrides("x # rule-override image-pin: vendor ships floating tags only\n# rule-override nope: x\n# rule-override action-pin:"), {"image-pin": "vendor ships floating tags only"})
class Hook(unittest.TestCase):
def setUp(self):
self.repo = tempfile.mkdtemp()
self.addCleanup(subprocess.run, ["rm", "-rf", self.repo])
git(self.repo, "init", "-q", "-b", "chunk")
def test_a_breach_exits_2_naming_the_rule_and_the_override(self):
ran = hook({"cwd": self.repo, "tool_input": {"file_path": f"{self.repo}/Dockerfile", "content": "FROM node:24\n"}, "tool_name": "Write"}, self.repo)
self.assertEqual(ran.returncode, 2)
self.assertIn("Blocked by rule image-pin: ", ran.stderr)
self.assertIn("`# rule-override image-pin: <reason>`", ran.stderr)
def test_an_override_passes_and_is_listed_for_its_branch(self):
content = "# rule-override image-pin: the vendor tags no patch versions\nFROM vendor/tool:2\n"
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$")
def test_an_edit_is_judged_on_the_file_it_leaves(self):
pathlib.Path(self.repo, ".gitignore").write_text("a\nc\n")
call = {"cwd": self.repo, "tool_input": {"file_path": f"{self.repo}/.gitignore", "new_string": "d", "old_string": "a"}, "tool_name": "Edit"}
self.assertEqual(hook(call, self.repo).returncode, 2)
def test_a_commit_staging_an_unranked_todo_is_blocked(self):
pathlib.Path(self.repo, "docs").mkdir()
for name, text in [("README.md", README), ("docs/decisions.md", DECISIONS), ("todo.md", TODO)]:
pathlib.Path(self.repo, name).write_text(text)
git(self.repo, "add", "README.md")
call = {"cwd": self.repo, "tool_input": {"command": "git commit -m x"}, "tool_name": "Bash"}
self.assertEqual(hook(call, self.repo).returncode, 0)
self.assertEqual(hook({**call, "tool_input": {"command": "git commit -am x"}}, self.repo).returncode, 0, "-a stages tracked files only")
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)
def test_unreadable_input_does_not_block(self):
ran = subprocess.run([str(HOOK)], capture_output=True, env=isolated_env(), input="{", text=True)
self.assertEqual(ran.returncode, 1)
+14
View File
@@ -33,6 +33,20 @@
}
}
},
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "~/.claude/bin/rule-hook",
"timeout": 30
}
]
}
]
},
"effortLevel": "xhigh",
"modelSettings": {
"claude-fable-5-1": {
+5 -4
View File
@@ -157,10 +157,11 @@ Launch prose-reviewer with what the diff touched and every section this review c
## 5. Goal alignment, then merge
1. Read the finished PR against the README goals: does anything in it work against one? Misaligned → do not merge; ask the human, stating the conflict.
2. Aligned, every pass done and everything green → **merge**. Follow the repo's merge method (`AGENTS.md`; ff-only where that is the convention). A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it.
3. Merged → remove the chunk's items from `todo.md` per `~/.claude/CLAUDE.md` → "Working loop".
4. Stop. The next chunk gets a fresh session.
2. **Overrides.** Run `~/.claude/bin/rule-hook overrides` in the chunk's worktree. When it prints a line, launch one general-purpose subagent as the judge, with no shell and no edits, given each line, the rule's text from `~/.claude/bin/rule-hook --help`, the README's goals and the diff each override let through. It accepts or rejects each reason by the goals, and calls an override outrageous when it touches a credential, a security rule or a production system, or cannot be undone. An accepted override stands. A rejected one is a 🔴 of this chunk: keep the rule, then re-enter per §3 → "Re-entry". An outrageous one is asked of the user. List each override with its ruling in the PR body.
3. Aligned, every pass done and everything green → **merge**. Follow the repo's merge method (`AGENTS.md`; ff-only where that is the convention). A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it.
4. Merged → remove the chunk's items from `todo.md` per `~/.claude/CLAUDE.md` → "Working loop".
5. Stop. The next chunk gets a fresh session.
## 6. Wrap up
Summarize: PR URL and final state, every reviewer's verdict, rounds per pass, passes skipped, principles files left out with why, findings fixed vs answered vs declined vs open — each answer with what settles it, each decline with its reason, a 🟡's with the goal or technical principle it rests on — CI status, decisions recorded (file paths), `todo.md`/`CHANGELOG.md` updated, and any 🔀 escalation left for the user.
Summarize: PR URL and final state, every reviewer's verdict, rounds per pass, passes skipped, principles files left out with why, findings fixed vs answered vs declined vs open — each answer with what settles it, each decline with its reason, a 🟡's with the goal or technical principle it rests on — CI status, rule overrides with their rulings, decisions recorded (file paths), `todo.md`/`CHANGELOG.md` updated, and any 🔀 escalation left for the user.
+2 -9
View File
@@ -25,7 +25,6 @@
| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |
|---|---|---|---|---|---|---|---|---|---|
| 95 | 0.1.0 | | **Make `CLAUDE.md` a short router: only the rules every session needs, and a pointer to where each topic's rules load.** | 6 | 6 | 8 | 8 | 1.1, 1.3, 1.4 | 24.3 |
| 96 | 0.1.0 | | **Enforce each rule a program can check in a hook or in CI, with one override marker the agent may use and the PR lists, and delete those rules from `CLAUDE.md`.** | 5 | 6 | 7 | 8 | 1.1, 1.3 | 23.3 |
| 98 | 0.1.0 | | **Score R and S from a measurement wherever one exists, and calibrate each guessed score against the finished chunk's measured outcome.** | 2 | 5 | 6 | 7 | 1.1, 1.4 | 22.6 |
| 99 | 0.1.0 | | **Drop the comprehension panel as a merge gate, and keep recording its scores and the places in the code its seats found hard, for later measurement and for other reviewers and agents to improve.** | 4 | 5 | 7 | 7 | 1.1, 1.4, 1.5 | 22.6 |
| 87 | 0.1.0 | | **Score every `todo.md` item's complexity C from 1 to 10, and have `rank_todo.py` fail on an item without one.** | 3 | 4 | 6 | 7 | 1.1, 1.4 | 21.9 |
@@ -74,14 +73,6 @@ Keep in it only what every session needs and no other file loads: the vocabulary
- 🟢 "Ask, don't guess": "If an answer is a goal and something else too, write the goal, and record a choice only for what the goal leaves open." Proposed: `When an answer holds a goal and a choice, write the goal in the README, and record as a choice only what the goal leaves open.`
- 🟢 "Decisions: one home" lists "a comment" as a wrong home, then names a comment as the destination. Proposed: `a comment away from the code it governs`.
Needs 96.
### 96. Enforce each rule a program can check in a hook or in CI, with one override marker the agent may use and the PR lists, and delete those rules from `CLAUDE.md`.
Anthropic's best-practices page: CLAUDE.md is advisory, hooks are deterministic, so a rule that must hold every time belongs in a hook. Candidates include one-line commit messages without authorship trailers, container images pinned to a full patch version, sorted ignore files, and `rank_todo.py --check` on `todo.md`.
A blocking hook exits 2 with a message that names the rule, why it holds, and the override. The override is one marker, the same for every hook and check, that names the rule and gives a reason. A CI check accepts it too, in the PR body. larv-review's PR summary lists every override in the chunk, and a judge rules on each from the rule, the reason and the README's goals: loop-claude's judge in a loop, a judge subagent in a run of larv-review alone. A reason the judge accepts stands, and one it rejects sends the worker back to keep the rule (goal 1.2). The judge interrupts the human only for an outrageous override: one that touches a credential, a security rule or a production system, or that cannot be undone. A rule a project sets for itself, such as fejkdata's Go-only-in-compose, goes in that project's own hook.
### 98. Score R and S from a measurement wherever one exists, and calibrate each guessed score against the finished chunk's measured outcome.
A score that can be computed from the code it touches, such as the files an item names, comes from that computation. Otherwise size and risk are estimated from finished work, the way reference-class forecasting estimates a project from earlier projects like it. When a chunk merges, record its measured outcome beside the item's guessed R and S: lines and files changed, review rounds, 🔴 and 🟡 findings, and fixes the code needed later. Show the scorer, when it files an item, the finished items whose guessed scores sat nearest and what they measured. Once enough chunks are recorded, report how far each guess was from its outcome, so a scorer whose S runs high can be corrected. Item 87's C is scored and calibrated the same way.
@@ -178,6 +169,8 @@ Raised by the product-owner review of PR #211. The resumed worker gets the judge
The repo has no CI, so larv-review's gate is the local run, and larv-review's Gate skips even that when the last stability round left the suite green: an unattended chunk can merge on the worker's own word.
A rule check CI runs, such as one of `bin/rule-hook`'s, accepts `# rule-override <rule>: <reason>` in the PR body.
### 80. State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.
Raised by the principles audit of PR #224. The `settings.json` decision is valid while every machine taking this checkout is a sandbox, but Install asks for a sandbox only for `loop-claude`, so a new machine is never told.