open/repo-mailbox
1
0
Fork 0
Code Issues Releases 2 Activity

feat(hooks): enforce STATE.md's ~60-line convention with a PreToolUse guard

Browse source 
org-ops dispatched a work order (20260814T144553Z) from an /insights sweep
of 160 sessions: a real STATE.md drifted to 155-156 lines before anyone
noticed, and one trim pass on it increased the line count instead of
shrinking it. Prose alone doesn't enforce.

org-ops proposed a PostToolUse hook. Checked against the official hooks
docs first: PostToolUse fires after the tool has already written the file
and cannot block it (confirmed "Can block? No"), only nag afterward. Built
it as PreToolUse instead, the only event that can deny the call before the
file lands.

pre-state-line-guard.mjs denies (stderr + exit 2, matching llm-security's
pre-write-pathguard.mjs) a Write or Edit on any STATE.md whose projected
result exceeds 60 lines. Write projects from the call's own content; Edit
projects from the current on-disk file with old_string replaced by
new_string, honoring replace_all (every occurrence) vs the default (first
occurrence only) the same way the real Edit tool does. Anything the hook
can't project confidently (missing file, old_string not found) is left to
the real tool.

state-line-guard-selftest.sh: 16 checks, including a replace_all fixture
that a first-occurrence-only projection would wrongly allow. Wired into
hooks/hooks.json as PreToolUse on Write|Edit. Version 0.22.0 -> 0.23.0.
Suite total: 191 + 152 + 69 + 16 = 428.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0186kZGKddxfA9N84HqMLbb2
This commit is contained in:
Kjell Tore Guttormsen 2026-08-14 17:01:20 +02:00
commit f39c0df929
12 changed files with 412 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

19
README.md
View file

@ -10,11 +10,11 @@ Session A in repo X leaves a message for repo Y; the next session in repo Y gets
*AI-generated: all code produced by Claude Code through dialog-driven development.*
![Version](https://img.shields.io/badge/version-0.22.0-blue)
![Version](https://img.shields.io/badge/version-0.23.0-blue)
![Hooks](https://img.shields.io/badge/hooks-1-green)
![Skills](https://img.shields.io/badge/skills-3-orange)
![CLI scripts](https://img.shields.io/badge/CLI_scripts-8-blue)
![Selftest checks](https://img.shields.io/badge/selftest_checks-412-blue)
![Selftest checks](https://img.shields.io/badge/selftest_checks-428-blue)
---
@ -94,7 +94,7 @@ It lives here because it is the **writer** for the cost field the board already
Scoring is judgement and belongs to the skill; turning scores into a row is a lookup and costs no model calls. One deliberate side effect is worth more than the tokens saved: a next step that cannot be scored `known` or `partial`, with no design phase planned, is an **underspecified task description** — the answer is to rewrite the step, not to upgrade the model.
**CLI.** The engine is eight user-facing bash scripts in the plugin's `scripts/` directory (plus three selftests); resolve them as `"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/scripts/coord-<name>.sh"` (from a terminal, use the plugin's install path):
**CLI.** The engine is eight user-facing bash scripts in the plugin's `scripts/` directory (plus four selftests); resolve them as `"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/scripts/coord-<name>.sh"` (from a terminal, use the plugin's install path):
coord-send.sh --to <repo> --subject "<subject>" [--message "<text>"] # or body on stdin
coord-send.sh --to <repo> --subject "<subject>" --fyi # a notice: no reply expected
@ -128,6 +128,8 @@ The two consumers want the same information shaped differently, so each block ca
Driving a terminal from this plan deliberately lives **outside this repo**. That work is a version-pinned, undocumented composition on top of a preview API whose documented path is already broken upstream, and its blast radius reaches into other repos' running sessions. The dependency runs one way — the driver consumes the plan, the plan never knows a terminal exists — so if the terminal API breaks, the plan still prints and the operator still pastes.
**The STATE.md line guard (`pre-state-line-guard.mjs`) enforces the ~60-line convention that used to be prose only.** A real STATE.md drifted to 155-156 lines before anyone noticed — and one trim pass on it *increased* the line count instead of shrinking it — because nothing checked the file, only a convention description asked sessions to keep it short. The guard is a **PreToolUse** hook on `Write|Edit`, not PostToolUse: PostToolUse fires after the tool has already written the file and cannot undo it, so PreToolUse is the only event that can actually stop an oversized STATE.md before it lands. For `Write` the projected content is the tool call's own `content`; for `Edit` it is the current on-disk file with `old_string` replaced by `new_string` (every occurrence when `replace_all` is set, matching what the real Edit tool does) — a write projected past 60 lines is denied with the projected count in the message, everything else is left alone. It only ever looks at files named exactly `STATE.md`, at any depth.
## Security Model
Cross-repo message content is untrusted input by design:
@ -156,15 +158,16 @@ Note that raising the inbox's priority (Rule 7) deliberately does **not** widen
## Requirements
- macOS or Linux with bash 3.2+ (the scripts are deliberately bash-3.2-safe and ASCII-only).
- Node.js >= 18 for the SessionStart hook (zero npm dependencies).
- Node.js >= 18 for the SessionStart and PreToolUse hooks (zero npm dependencies).
- `git` is required to derive repo identity automatically. Without it, pass `--from`/`--repo` explicitly; the engine refuses to guess an identity from the working directory.
## Development
bash scripts/coord-selftest.sh # 191 checks against a throwaway mailbox
bash scripts/board-selftest.sh # 152 checks against a throwaway repo tree
bash scripts/route-selftest.sh # 69 checks, incl. the route->board round trip
npm test # all three selftests via node --test
bash scripts/coord-selftest.sh # 191 checks against a throwaway mailbox
bash scripts/board-selftest.sh # 152 checks against a throwaway repo tree
bash scripts/route-selftest.sh # 69 checks, incl. the route->board round trip
bash scripts/state-line-guard-selftest.sh # 16 checks, incl. the Edit replace_all projection
npm test # all four selftests via node --test
TDD is the house rule: every behavior change lands with a failing selftest check first.