feat(plugin): you altered the shape of something — here is everything that reads it (#4215)

Milestone 419 step 4. Five of the milestone's seven misses were the same move:
acting on the thing in hand without reading the contract around it. Lesson
#4207 says so in words, and was written by its author hours before a
structurally identical mistake, having been surfaced twice in the turns
between. Text delivered at the moment of acting is too weak a carrier for a
reflex that has to change what the act IS. This looks it up instead.

Rule 33 one scope down: its checks are between layers, and the same question
exists between a definition and its callers.

THREE KINDS OF EXPOSED NAME, because a contract breaks three ways that look
nothing alike in source — the defined symbol (a rename or removal), its
parameter names (arity), and the quoted keys of its dict literals (the shape
of what it returns).

THE THIRD IS THE ONE A SIGNATURE-WATCHER MISSES, and it is in because of the
miss that produced this step. Two commits ago `get_writepath_config` gained
one dict key; three arms read that dict inside a fail-open `except`, every one
silently became a no-op, and ten tests went red with nothing pointing at the
cause. No signature changed. Run against that exact edit, the check now names
tests/helpers.py — the actual root cause — among six files, before the write.

TWO GATES, AND THE SECOND IS WHAT MAKES IT USABLE. A change to the exposed set
is necessary but not sufficient: a definition nothing else references has no
contract to break, so the readers lookup runs second and an empty result ends
it silently. Body-only edits say nothing, a subject is named once per session,
and the ledger lives in the swept directory under the `.ids` convention, so
the existing compaction-clear guards cover it — checked against
test_session_ledger_clear's own parsers rather than assumed.

LOCAL AND SERVERLESS, like the duplicate-name arm beside it. It needs the
working tree and nothing else; the server has no checkout, so this is the only
place the question can be asked. It is a NUDGE: scribe_prior_art.sh still
returns no permissionDecision, which is the operator's recorded decision that
a recall aid may not stand in the way of a write. A test asserts that here as
well as in test_write_path_trigger.py, because this is the arm most likely to
tempt someone into making it a gate — it reports something that may already be
broken.

The `sym` half delegates to `scribe_defs` rather than repeating its patterns:
those cover nine languages and have been corrected several times, and a second
copy would inherit today's version and quietly stop agreeing with it (#3497).

Verified by lifting the test file's own helpers and driving all 19 cases
against the real shell over a fixture git repo. Two of my own errors were
caught that way and are fixed: the fixtures were arriving as single lines
because Python `repr` inside bash single quotes leaves `\n` as two characters
(the extractor is line-oriented, so the tests would have gone green against
input no editor can produce), and the no-readers case put its subject in a
file that was not the excluded one, so it had a reader and tested the
opposite of its name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy

plugin/hooks/scribe_prior_art.sh

@@ -281,10 +281,49 @@ if [ -n "$local_lines" ] && [ "$reached" = 1 ]; then
   fi
 fi
 
-# Local first. It answers "this already EXISTS", which is a stronger claim than
-# "this resembles something recorded" — and it is the one the recorded arms are
-# structurally unable to make.
-combined="$local_context"
+# ---------------------------------------------------------------------------
+# ARM 0 — THE CONTRACT AROUND THE CHANGE (#4215, milestone 419).
+#
+# "You altered the arity, name or shape of something — here is everything that
+# reads it." Rule 33's interface-contract check one scope down: not between
+# layers but between a definition and its callers.
+#
+# LOCAL AND SERVERLESS, like ARM 1. It needs the working tree and nothing
+# else — the server has no checkout, so this is the only place the question
+# can be asked at all.
+#
+# EDITS ONLY. The comparison is between what the definition exposed before and
+# what it exposes now, so it needs both texts; a Write that creates a file has
+# no "before" and nothing to break.
+contract_context=""
+if [ -n "$repo_root" ] && [ -n "$code" ]; then
+  old_code=$(scribe_json_pick "$event_flat" '.tool_input.old_string')
+  [ -n "$old_code" ] || old_code=$(scribe_json_pick "$event_flat" '.tool_input.old_str')
+  # The SUBJECT is the definition whose contract may have moved. `shapes`
+  # already holds either the definitions in the payload or — for an edit
+  # inside a function body — the one enclosing the edit, which is exactly the
+  # thing whose callers matter. CSS rows are skipped: a class has readers, but
+  # they are markup files and `scribe_local_dups` already speaks for those.
+  subject=$(printf '%s\n' "$shapes" \
+    | awk -F'\t' 'NF>=2 && $1!="css" {print $2; exit}')
+  if [ -n "$old_code" ] && [ -n "$subject" ]; then
+    contract_file=""
+    [ -n "${safe_sid:-}" ] && contract_file="$state_dir/${safe_sid}.contract.ids"
+    contract_context=$(scribe_contract_block \
+      "$repo_root" "$rel_path" "$subject" "$old_code" "$code" "$contract_file" \
+      2>/dev/null) || contract_context=""
+  fi
+fi
+
+# CONTRACT FIRST of the three, and the order is the strength of the claim.
+# This one says something may already be BROKEN by the edit in hand. The local
+# arm says a copy exists. The recorded arms say something resembles this. A
+# reader who reads one line should read that one.
+combined="$contract_context"
+if [ -n "$local_context" ]; then
+  [ -n "$combined" ] && combined="${combined}"$'\n'
+  combined="${combined}${local_context}"
+fi
 if [ -n "$context" ]; then
   [ -n "$combined" ] && combined="${combined}"$'\n'
   combined="${combined}${context}"