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:
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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'`
|
||||
|
||||
@@ -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
@@ -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()))
|
||||
@@ -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 ""
|
||||
@@ -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]
|
||||
@@ -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)
|
||||
@@ -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": {
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user