Answer prose round 1: name the override reviewer apart from loop-claude's judge, list the override forms, and say each rule as it holds

This commit is contained in:
2026-10-12 23:29:02 +02:00
parent cf9f6b9e7a
commit 7cf4f54c90
6 changed files with 19 additions and 15 deletions
+1 -1
View File
@@ -2,7 +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` states those rules only where the hook cannot check them; `~/.claude/bin/rule-hook --help` states what it checks. 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 hook blocks each Bash, Edit, MultiEdit and Write call that breaks a rule a program can check: a commit message that is not one line passed with `-m`, 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` states those rules only where the hook cannot check them; `~/.claude/bin/rule-hook --help` states what it checks. A call overrides a rule with `# rule-override <rule>: <reason>`. larv-review lists each override in the PR body, and a reviewer accepts or rejects it; a rejected override means the chunk keeps the rule. An override 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.
+1 -1
View File
@@ -118,7 +118,7 @@ Prose describing the code as it stands — a comment, a README, an `AGENTS.md`,
- 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. 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.
- Pin a container image to its full patch version where `~/.claude/bin/rule-hook` does not check it, such as an image named in test code, 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/`.
+12 -7
View File
@@ -8,8 +8,8 @@ subagent. The rules:
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 that an edit leaves unsorted is sorted; a blank
line or comment ends a block
ignorefile-sorted an edit leaves each block of a .*ignore file sorted, unless the block was
unsorted before; 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
@@ -17,11 +17,16 @@ subagent. The rules:
todo-rank-check a git commit while todo.md has changes, staged or not, needs
rank_todo.py --check to pass on it
The file rules see what an Edit, MultiEdit or Write call writes, not a file a Bash command writes.
action-pin, ignorefile-sorted, image-pin and no-ai-attribution check only what an Edit, MultiEdit or
Write call writes, not a file a Bash command writes.
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, or in Markdown as
`<!-- rule-override <rule>: <reason> -->`. Each override that let a call through is appended to
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
- in Markdown, as `<!-- rule-override <rule>: <reason> -->`
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.
@@ -81,7 +86,7 @@ def main(argv: list[str], stdin: str) -> int:
for rule in sorted({breach.rule for breach in blocking}):
details = "; ".join(breach.detail for breach in blocking if breach.rule == rule)
marker = f"<!-- rule-override {rule}: <reason> -->" if markdown else f"# rule-override {rule}: <reason>"
print(f"Blocked by rule {rule}: {details}. The rule: {RULES[rule]}. Where it does not fit this case, add `{marker}` to {where}; larv-review's judge rules on the reason.", file=sys.stderr)
print(f"Blocked by rule {rule}: {details}. The rule: {RULES[rule]}. Where it does not fit this case, add `{marker}` to {where}; larv-review rules on the reason.", file=sys.stderr)
return 2
+3 -4
View File
@@ -3,12 +3,11 @@ 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",
"action-pin": "a GitHub or Gitea Action is pinned to a semver tag, such as @v3 or @v3.1.2, never to a branch, and to a commit SHA 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, or to a date-stamped tag or an @sha256: digest, so the same commit builds the same image on every day; a bot such as Renovate raises the bumps as reviewable PRs. An image that publishes no three-part tag, such as postgres:16.4, takes an override",
"image-pin": "a container image is pinned to its full patch version, such as node:24.18.1-bookworm-slim, or to a date-stamped tag or an @sha256: digest, so the same commit builds the same image on every day. An image that publishes no three-part tag, such as postgres:16.4, takes an override",
"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": "while todo.md has changes, staged or not, a git commit waits until ~/.claude/bin/rank_todo.py --check passes on it",
}
@@ -51,7 +50,7 @@ def overrides(text: str) -> tuple[dict[str, str], list[str]]:
def segments(command: str) -> list[list[str]] | None:
"""The command's simple commands as words, each heredoc's body cut to a line break, or None when it does not parse."""
"""The command's simple commands as words, with each heredoc's body dropped, or None when it does not parse."""
lexer = shlex.shlex(HEREDOC.sub(lambda heredoc: heredoc.group(0).split("\n", 1)[0], command), posix=True, punctuation_chars="();<>|&\n")
lexer.whitespace = " \t\r"
lexer.whitespace_split = True
+1 -1
View File
@@ -157,7 +157,7 @@ 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. **Overrides.** Run `~/.claude/bin/rule-hook overrides` in the chunk's worktree. When it prints a line no judge has ruled on in this chunk, launch one general-purpose subagent as the judge, with no shell and no edits, given those lines, the rules from `~/.claude/bin/rule-hook --help`, the README's goals and the branch diff. It rules nothing on an override whose breach the branch no longer holds. It accepts or rejects each other 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, such as by rewording the commit or pinning the image, then re-enter per §3 → "Re-entry"; where the rule cannot be kept, ask the user. An outrageous one is asked of the user. List each override with its ruling in the PR body.
2. **Overrides.** Run `~/.claude/bin/rule-hook overrides` in the chunk's worktree. When it prints a line not yet ruled on in this chunk, launch one general-purpose subagent, the override reviewer, with no shell and no edits, given those lines, the rules from `~/.claude/bin/rule-hook --help`, the README's goals and the branch diff. It skips an override whose breach the branch no longer holds. It accepts or rejects each other 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, such as by rewording the commit or pinning the image, then re-enter per §3 → "Re-entry"; where the rule cannot be kept, ask the user. 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.
+1 -1
View File
@@ -169,7 +169,7 @@ 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.
When CI runs a rule check, such as one of `bin/rule-hook`'s, let `<!-- rule-override <rule>: <reason> -->` in the PR body override it.
### 80. State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.