feat(rulings): a command or edit touching an area's files shows its rulings, once per session (milestone 444 step 4, #4757)

A System's rulings (the Rulings section of its description) now reach the
work by path, not by similarity. Both PreToolUse arms resolve the files a
command or edit names to the Systems whose path_patterns cover them, and the
first touch in a session shows each area's rulings in one line; a repeat is
a one-line reference. A lookup, so no floor, no budget, no retrieval_logs row.

- services/system_rulings: parse_rulings, command_paths (reads and writes,
  relative to the repo root from any cwd; flags, URLs, globs skipped),
  rulings_for_paths
- /tool-rules takes root, cwd and seen_ruling_systems; /prior-art takes
  seen_ruling_systems; both return ruling_system_ids
- hooks share <sid>.rulings.ids (cleared on compaction by the ledger naming
  convention); the Bash hook sends the repo root and cwd
- system_usage_events (migration 0114): surfacings by source, pulls from
  get_system; carried by backup (v20) through the system map
- writing-records: rulings also arrive when the area's files are touched

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "scribe",
   "description": "Scribe for Claude Code: connects the scribe MCP server, adds the hooks that deliver live project state and relevant records at the right moment, ships the shared client-neutral Scribe skills (using-scribe, writing-plans, reporting-back, systematic-debugging, verification, brainstorming, reusing-code, shape-accounting), and syncs your saved Scribe Processes as skills (/scribe:sync).",
-  "version": "2026.10.03.0255",
+  "version": "2026.10.03.0308",
   "author": {
     "name": "Bryan Van Deusen"
   },

plugin/hooks/scribe_defs.sh

@@ -1123,6 +1123,20 @@ scribe_held_query() {
   return 0
 }
 
+# The Systems whose rulings this session was already shown in full (milestone
+# 444), as the `seen_ruling_systems` query both PreToolUse hooks send. A flat
+# read, not aged like the rule file: a ruling binds for the whole session, and
+# the server already answers a repeat with one short reference line. The file
+# follows the ledger name convention, so a compaction clears it and the
+# rulings are shown in full again to the context that lost them.
+scribe_rulings_query() {
+  local ids
+  [ -f "$1" ] || return 0
+  ids=$(grep -E '^[0-9]+$' "$1" 2>/dev/null | sort -un | tr '\n' ',' | sed 's/,$//')
+  [ -n "$ids" ] && printf '&seen_ruling_systems=%s' "$ids"
+  return 0
+}
+
 # Drop EVERY per-session ledger, matched by convention rather than listed (#4101).
 #
 # A LIST IS THE BUG. Until now the compact/clear branch named its files one at

plugin/hooks/scribe_prior_art.sh

@@ -192,6 +192,10 @@ mkdir -p "$state_dir" 2>/dev/null || true
 # A FOURTH channel (milestone 307): standing RULES the write resembles. Its own
 # file for the same reason as the others — a rule named once should not be
 # re-offered on every subsequent write in the session.
+#
+# A FIFTH (milestone 444): the Systems whose RULINGS were shown in full. SHARED
+# with scribe_tool_rules.sh, like the rule file: an area's rulings shown before
+# a command must not be repeated in full before the next edit there.
 idfile=""
 syncfile=""
 derivefile=""
@@ -200,6 +204,8 @@ exclude_q=""
 sync_exclude_q=""
 derive_exclude_q=""
 rule_exclude_q=""
+rulingsfile=""
+rulings_q=""
 if [ -n "$session_id" ]; then
   safe_sid=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
   # What this write defined, for the end-of-turn question (milestone 439). A
@@ -214,6 +220,8 @@ if [ -n "$session_id" ]; then
   syncfile="$state_dir/${safe_sid}.sync.ids"
   derivefile="$state_dir/${safe_sid}.derive.ids"
   rulefile="$state_dir/${safe_sid}.rules.ids"
+  rulingsfile="$state_dir/${safe_sid}.rulings.ids"
+  rulings_q=$(scribe_rulings_query "$rulingsfile")
   if [ -f "$idfile" ]; then
     seen=$(tr '\n' ',' < "$idfile" 2>/dev/null | sed 's/,$//')
     [ -n "$seen" ] && exclude_q="&exclude_ids=${seen}"
@@ -242,7 +250,7 @@ fi
 reached=1
 body=$(curl -fsS --max-time 5 \
   -H "Authorization: Bearer ${token}" \
-  "${url%/}/api/plugin/prior-art?path=${path_enc}&code=${code_enc}${repo_q}${exclude_q}${sync_exclude_q}${derive_exclude_q}${rule_exclude_q}${shapes_q}" 2>/dev/null) || { body=""; reached=0; }
+  "${url%/}/api/plugin/prior-art?path=${path_enc}&code=${code_enc}${repo_q}${exclude_q}${sync_exclude_q}${derive_exclude_q}${rule_exclude_q}${rulings_q}${shapes_q}" 2>/dev/null) || { body=""; reached=0; }
 unreached_context=""
 if [ "$reached" = 1 ]; then
   scribe_reached "$state_dir" "${safe_sid:-nosession}"
@@ -271,6 +279,9 @@ if [ -n "$body" ]; then
     if [ -n "$derivefile" ]; then
       scribe_json_list "$body_flat" '.derive_keys' >> "$derivefile" || true
     fi
+    if [ -n "$rulingsfile" ]; then
+      scribe_json_list "$body_flat" '.ruling_system_ids' >> "$rulingsfile" || true
+    fi
   fi
 fi
 

plugin/hooks/scribe_tool_rules.sh

@@ -68,6 +68,15 @@ lookup_dir=${event_cwd:-${CLAUDE_PROJECT_DIR:-$PWD}}
 scope=$(scribe_scope_query "$lookup_dir")
 [ -n "$scope" ] && repo_q="&${scope}"
 
+# Where the command runs, against the repo's root (milestone 444): the paths a
+# command names are relative to its cwd or absolute, and a System's patterns
+# are relative to the root. The server does the arithmetic; this sends both.
+where_q=""
+repo_root=$(git -C "$lookup_dir" rev-parse --show-toplevel 2>/dev/null || true)
+if [ -n "$repo_root" ]; then
+  where_q="&root=$(printf '%s' "$repo_root" | scribe_urlenc)&cwd=$(printf '%s' "$lookup_dir" | scribe_urlenc)"
+fi
+
 # THE SHARED SESSION LEDGER, and the thing most worth getting right here.
 #
 # scribe_prior_art.sh keeps the rules it has already named in
@@ -82,6 +91,8 @@ state_dir="${TMPDIR:-/tmp}/scribe-priorart"
 mkdir -p "$state_dir" 2>/dev/null || true
 rulefile=""
 rule_exclude_q=""
+rulingsfile=""
+rulings_q=""
 if [ -n "$session_id" ]; then
   safe_sid=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
   rulefile="$state_dir/${safe_sid}.rules.ids"
@@ -91,6 +102,10 @@ if [ -n "$session_id" ]; then
   [ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
   # What the session actually OPENED, as against what it was shown (#4100).
   rule_exclude_q="${rule_exclude_q}$(scribe_held_query "$state_dir/${safe_sid}.opened.ids")"
+  # The Systems whose rulings were shown in full — shared with the write-path
+  # hook, for the reason the rule file is.
+  rulingsfile="$state_dir/${safe_sid}.rulings.ids"
+  rulings_q=$(scribe_rulings_query "$rulingsfile")
 fi
 
 # `|| exit 0` here, unlike the prior-art hook: there is no local arm whose
@@ -98,7 +113,7 @@ fi
 # than silence. See the header.
 body=$(curl -fsS --max-time 5 \
   -H "Authorization: Bearer ${token}" \
-  "${url%/}/api/plugin/tool-rules?tool=${tool_enc}&command=${cmd_enc}${repo_q}${rule_exclude_q}" 2>/dev/null) || exit 0
+  "${url%/}/api/plugin/tool-rules?tool=${tool_enc}&command=${cmd_enc}${repo_q}${where_q}${rule_exclude_q}${rulings_q}" 2>/dev/null) || exit 0
 
 body_flat=$(printf '%s' "$body" | scribe_json_flat)
 context=$(scribe_json_pick "$body_flat" '.context')
@@ -111,6 +126,9 @@ context=$(scribe_json_pick "$body_flat" '.context')
 if [ -n "$rulefile" ]; then
   scribe_json_list "$body_flat" '.rule_ids' | scribe_rules_append "$rulefile"
 fi
+if [ -n "$rulingsfile" ]; then
+  scribe_json_list "$body_flat" '.ruling_system_ids' >> "$rulingsfile" || true
+fi
 
 # ── The pre-act checkpoint (#4214, milestone 419) ────────────────────────
 #

plugin/skills/using-scribe/writing-records.md

@@ -96,6 +96,8 @@ one line each — the statement, who decided, when, and the record it came from:
 
 The description arrives with every record filed under that System, so a ruling
 there reaches each session working in the area without having to win a search.
+Once the System names its files (`path_patterns`), its rulings also arrive with
+the first command or edit in a session that touches them.
 A quote inside a work log does not: it surfaces only when a query happens to
 match it, and the passage that matches is usually the prose around it — often a
 session's *reading* of the ruling rather than the ruling.