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

23
CHANGELOG.md
View file

@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.23.0] - 2026-08-14
### Added
- **`pre-state-line-guard.mjs`: a PreToolUse hook that enforces the documented
~60-line STATE.md convention mechanically.** Dispatched by org-ops
(20260814T144553Z) from an /insights analysis 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 asked
sessions to keep it short, and nothing enforced it. org-ops' work order
proposed a PostToolUse hook; confirmed against the official hooks docs that
PostToolUse fires after the tool has already written the file and cannot
block it — only PreToolUse can. The hook denies (stderr + exit 2, matching
llm-security's `pre-write-pathguard.mjs` convention) a `Write` or `Edit`
whose projected result exceeds 60 lines: for `Write` the projection is the
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, mirroring the real Edit tool), so the replace_all case is counted
correctly rather than only the first occurrence. Wired into
`hooks/hooks.json` as `PreToolUse` on `Write|Edit`. Pinned by
`state-line-guard-selftest.sh` (16 checks). Suite total: coord 191 + board
152 + route 69 + state-line-guard 16 = 428.
## [0.22.0] - 2026-08-13
### Fixed