diff --git a/.claude/settings.json b/.claude/settings.json index e8d1bd5..2ecacdf 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -7,7 +7,7 @@ { "hooks": [ { - "command": "f=$(jq -r \".tool_input.file_path // .tool_response.filePath // empty\" 2\u003e/dev/null); if [ -n \"$f\" ] \u0026\u0026 echo \"$f\" | grep -q \"/wiki/\"; then python3 tools/brain.py lint-page \"$f\" 2\u003e/dev/null || true; fi", + "command": "f=$(jq -r \".tool_input.file_path // .tool_response.filePath // empty\" 2>/dev/null); if [ -n \"$f\" ] && echo \"$f\" | grep -q \"/wiki/\"; then python3 tools/brain.py lint-page \"$f\" 2>/dev/null || true; fi", "type": "command" } ], @@ -16,7 +16,7 @@ { "hooks": [ { - "command": "f=$(jq -r \".tool_input.file_path // .tool_response.filePath // empty\" 2\u003e/dev/null); if [ -n \"$f\" ] \u0026\u0026 echo \"$f\" | grep -q \"/wiki/\"; then bash tools/ui-build.sh; fi", + "command": "f=$(jq -r \".tool_input.file_path // .tool_response.filePath // empty\" 2>/dev/null); if [ -n \"$f\" ] && echo \"$f\" | grep -q \"/wiki/\"; then bash tools/ui-build.sh; fi", "type": "command" } ], @@ -30,24 +30,42 @@ } ], "matcher": "Edit|Write|MultiEdit" + }, + { + "hooks": [ + { + "command": "\"${CLAUDE_PROJECT_DIR:-.}/tools/hooks/intent-first.sh\" record", + "type": "command" + } + ], + "matcher": "Edit|Write|MultiEdit" } ], "PreToolUse": [ { "hooks": [ { - "command": "cmd=$(jq -r '.tool_input.command // empty' 2\u003e/dev/null); case \"$cmd\" in *\"git push\"*|*\"gh pr create\"*) root=$(git rev-parse --show-toplevel 2\u003e/dev/null || echo .); script=\"$root/tools/preflight.sh\"; if [ -x \"$script\" ]; then \"$script\" \u003e\u00262 || { echo \"preflight blocked: $cmd\" \u003e\u00262; exit 2; }; fi ;; esac; exit 0", + "command": "cmd=$(jq -r '.tool_input.command // empty' 2>/dev/null); case \"$cmd\" in *\"git push\"*|*\"gh pr create\"*) root=$(git rev-parse --show-toplevel 2>/dev/null || echo .); script=\"$root/tools/preflight.sh\"; if [ -x \"$script\" ]; then \"$script\" >&2 || { echo \"preflight blocked: $cmd\" >&2; exit 2; }; fi ;; esac; exit 0", "type": "command" } ], "matcher": "Bash" + }, + { + "hooks": [ + { + "command": "\"${CLAUDE_PROJECT_DIR:-.}/tools/hooks/intent-first.sh\" gate", + "type": "command" + } + ], + "matcher": "Edit|Write|MultiEdit" } ], "SessionStart": [ { "hooks": [ { - "command": "python3 tools/brain.py inbox summary 2\u003e/dev/null || true", + "command": "python3 tools/brain.py inbox summary 2>/dev/null || true", "type": "command" } ] @@ -78,6 +96,24 @@ "type": "command" } ] + }, + { + "hooks": [ + { + "command": "\"${CLAUDE_PROJECT_DIR:-.}/tools/hooks/intent-first.sh\" debt", + "type": "command" + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "command": "\"${CLAUDE_PROJECT_DIR:-.}/tools/hooks/intent-first.sh\" reset", + "type": "command" + } + ] } ] }, @@ -123,4 +159,4 @@ "mcp__claude_ai_Notion__notion-move-pages" ] } -} +} \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 2874373..1b9ebd8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1162,6 +1162,26 @@ or any other direct work in that codebase. Five rules. next agent inheriting the area knows *why* a parallel pattern was warranted instead of an extension of the existing one. +6. **Intent first.** Before code moves in a sibling repo, the + governing specs move — or are confirmed already aligned. Read + the trail with `brain.py enola govern ` (which names the + PRD/ADR/build-notes pages governing the code being touched) and + check the *intended* change against what those pages record. A + deviation is amended into the governing page **before** the + edit, not narrated into build notes afterwards; work nothing + governs is surfaced with the question of whether it should be + shaped. `tools/hooks/intent-first.sh` enforces both ends of the + loop mechanically. Entering: the first Edit/Write into each + sibling repo *per piece of work* is blocked once with the + file's governing trail injected into context, and the retry + proceeds — the gate re-arms on every user message. Leaving: a + Stop-time debt check blocks the turn's end once when sibling + code moved but no governing page did, demanding either the + spec amendment or an explicit statement of why the specs + already cover the change. The gates force the reading and the + accounting, never the verdict; an absent graph degrades to a + named skip. + These rules apply equally to autonomous agent runs and to human-supervised ones. The brain agent operating in any sibling repo is a guest in that codebase; the host repo's conventions are diff --git a/README.md b/README.md index 28feff6..f7b5551 100644 --- a/README.md +++ b/README.md @@ -249,6 +249,22 @@ re-derivation (only pages the stamp itself touched) and the commit — skip-when-absent; its voice is the non-blocking session hook. +### Intent-first session hooks + +`tools/hooks/intent-first.sh` (four modes, registered in +`.claude/settings.json`) is the mechanical half of AGENTS.md +§ Working inside a sibling repo, rule 6. *Entering* a piece of +work: the first Edit/Write into each sibling repo is blocked once, +with the file's governing specs (`brain.py enola govern`) injected +into context and the instruction to align the PRD/ADR/build-notes +before the code moves; the gate re-arms on every user message. +*Leaving* a turn: when sibling code moved and no wiki page did, the +stop is blocked once and the agent must amend the governing page or +state why the specs already cover the change. The gates force the +reading and the accounting, never the verdict; an absent graph +degrades to a named skip. Sibling detection honours +`$BRAIN_PROJECTS_ROOT` (default `~/projects`). + ## Workflow — slash commands | Command | What it does | diff --git a/tools/hooks/intent-first.sh b/tools/hooks/intent-first.sh new file mode 100755 index 0000000..bfdfaa2 --- /dev/null +++ b/tools/hooks/intent-first.sh @@ -0,0 +1,127 @@ +#!/bin/bash +# Intent-first hooks — the mechanical half of AGENTS.md § Working +# inside a sibling repo, rule 6 (intent first). +# +# Modes (all read the Claude Code hook JSON from stdin): +# gate PreToolUse on Edit|Write|MultiEdit — block the first edit +# into each sibling repo *per piece of work* (re-armed on +# every user prompt), surfacing the file's governing specs +# (brain.py enola govern). The retry proceeds: the gate +# forces the reading, never the verdict. Absent graph +# degrades to a named skip. +# record PostToolUse on Edit|Write|MultiEdit — record what moved +# this turn: sibling code vs brain wiki pages (specs). +# reset UserPromptSubmit — a new user message begins a new piece +# of work: clear gate acks and the turn record. +# debt Stop — if sibling code moved this turn and no spec moved, +# block the stop once and demand the accounting: amend the +# governing page, or state why the work is already aligned. +set -u + +mode="${1:-}" +input=$(cat 2>/dev/null || true) +sid=$(jq -r '.session_id // "nosession"' <<<"$input" 2>/dev/null) +statedir="${TMPDIR:-/tmp}/brain-intent-first" +mkdir -p "$statedir" + +brain_dir=$(cd "${CLAUDE_PROJECT_DIR:-.}" && pwd -P) + +classify() { + local f="$1" probe top + case "$f" in + "${BRAIN_PROJECTS_ROOT:-$HOME/projects}"/*) ;; + *) return 1 ;; + esac + probe=$(dirname "$f") + while [ ! -d "$probe" ] && [ "$probe" != "/" ]; do + probe=$(dirname "$probe") + done + top=$(git -C "$probe" rev-parse --show-toplevel 2>/dev/null) || return 1 + top=$(cd "$top" && pwd -P) + if [ "$top" = "$brain_dir" ]; then + case "${f#"$top"/}" in + wiki/_views/*|wiki/_archive/*|wiki/_state/*) return 1 ;; + wiki/*.md) printf 'spec\t%s\t%s\n' "$top" "${f#"$top"/}"; return 0 ;; + *) return 1 ;; + esac + fi + printf 'code\t%s\t%s\n' "$top" "${f#"$top"/}" +} + +case "$mode" in + gate) + f=$(jq -r '.tool_input.file_path // empty' <<<"$input" 2>/dev/null) + [ -z "$f" ] && exit 0 + line=$(classify "$f") || exit 0 + kind=$(cut -f1 <<<"$line") + [ "$kind" = "code" ] || exit 0 + top=$(cut -f2 <<<"$line") + rel=$(cut -f3 <<<"$line") + repo=$(basename "$top") + ack="$statedir/${sid}-${repo}.ack" + [ -e "$ack" ] && exit 0 + touch "$ack" + + govern=$(cd "$brain_dir" && timeout 30 python3 tools/brain.py enola govern "$rel" 2>&1 | head -40) + [ -n "$govern" ] || govern="(enola govern unavailable — named skip; consult the wiki// shelves manually)" + + cat >&2 </dev/null) + [ -z "$f" ] && exit 0 + line=$(classify "$f") || exit 0 + printf '%s\n' "$line" >> "$statedir/${sid}.turn" + exit 0 + ;; + + reset) + rm -f "$statedir/${sid}"-*.ack "$statedir/${sid}.turn" "$statedir/${sid}.debt-blocked" + exit 0 + ;; + + debt) + turn="$statedir/${sid}.turn" + [ -f "$turn" ] || exit 0 + [ -e "$statedir/${sid}.debt-blocked" ] && exit 0 + grep -q '^code' "$turn" || exit 0 + grep -q '^spec' "$turn" && exit 0 + touch "$statedir/${sid}.debt-blocked" + + summary=$(awk -F'\t' '$1 == "code" { n = split($2, a, "/"); print " " $3 " (" a[n] ")" }' "$turn" | sort -u | head -15) + + cat >&2 <&2 + exit 64 + ;; +esac