refactor(retrieval): one registry for every surface's floor and budget (#4102)

Groundwork for the step's real change. The operator's decision is that the
floor is chosen and adjusted by the model using it, not shipped as a value
somebody has to defend:

  "we need a model consistent surface for the adjustment of these floor values.
   the user should be able to touch it but the model should be the thing
   handling it 9 times out of 10."

A tuning surface cannot be consistent across six arms that each spell their
configuration differently, so the arms stop owning their numbers.
`retrieval_surfaces.SURFACES` names each one, its floor key and default, its
budget key and default, and — because they are rendered by the tuning tool and
the Settings UI — what it asks, over what corpus, and how often it fires. A
floor cannot be moved responsibly by anyone who does not know those three.

Three things fall out:

- **`k` becomes a real budget everywhere.** Only auto-inject had a configurable
  one; `RULEHINT_LIMIT`, `PROMPTRULE_LIMIT` and `reply_preferences.LIMIT` were
  constants. `k` is what binds under a low floor, so it has to be settable per
  surface — and per surface is the point, since `pre_tool_rule` fires before
  every Bash call while `prompt_rule` fires once a turn.
- **`write_path` gets its own budget, inherited not reset.** It shared
  auto-inject's outright on the argument that "how many titles at once" means
  the same thing on both. It does not, for the same reason. Unset, it still
  reads auto-inject's key, so an install that tuned the shared knob does not
  silently drop to a new default.
- **The duplicated read-and-clamp goes.** That shape is canon #2860 across 295
  of 372 judged siblings. Survivable while the numbers were constants; not once
  they are meant to move.

The long measurement comments stay exactly where they are — #2223's noise-floor
probe, #3853's command-vs-code split, #3851's band measurement. The constants
they annotate now alias the registry, so there is one value and the reasoning
still sits beside it.

Tests build the write-path config from the registry (`helpers.writepath_cfg`)
instead of from hand-written dicts. That is not tidiness: the rule arms read
their numbers inside a fail-open `except`, so a dict missing one key does not
raise where a reader would see it — the arm silently becomes a no-op that reads
exactly like "fired and found nothing". Ten hand-written dicts each looked
complete on the day they were typed.

tests/test_retrieval_surfaces.py pins the identity everything rests on: a
surface's name IS its telemetry source. Nothing in the type system says so —
`record_retrieval(source="pre_tool_rule")` is a literal in another file — and
renaming one without the other yields an arm that can be tuned and not
measured, or measured and not tuned, with no symptom either way.

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

tests/test_rule_usage_wiring.py

@@ -17,7 +17,8 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
-from tests.helpers import fake_note, fake_rule
+from scribe.services import retrieval_surfaces as rs
+from tests.helpers import fake_note, fake_rule, writepath_cfg
 
 # The MCP tool layer reads its caller from a ContextVar the HTTP transport sets
 # per request; a unit test has no request, so it binds the caller itself. The
@@ -59,16 +60,15 @@ def _arm_patches(pc, hits, recorder, prior_art=None, cfg=None, rule_search=None,
     """
     return (
         patch.object(pc, "get_writepath_config",
-                     AsyncMock(return_value=cfg or {
-                         "enabled": True, "threshold": 0.6,
-                         "top_k": 3, "rule_threshold": 0.6,
-                         # The command arm reads its OWN bar since #3853, and
-                         # a stub missing this key does not fail where a
-                         # reader would see it: the arm fails open, so the
-                         # KeyError becomes an empty hint and every case in
-                         # _ARMS reports the arm went silent instead.
-                         "tool_rule_threshold": 0.6,
-                     })),
+                     # Every key, derived from the surface registry (#4102).
+                     # A stub missing one does not fail where a reader would
+                     # see it: the arm fails open, so the KeyError becomes an
+                     # empty hint and every case in _ARMS reports the arm went
+                     # silent instead.
+                     AsyncMock(return_value=cfg or writepath_cfg(
+                         threshold=0.6, rule_threshold=0.6,
+                         tool_rule_threshold=0.6,
+                     ))),
         patch.object(pc.snippets_svc, "list_snippets", AsyncMock(return_value=([], 0))),
         patch.object(pc, "semantic_search_notes",
                      AsyncMock(return_value=_PRIOR_ART if prior_art is None
@@ -156,8 +156,7 @@ async def test_the_arm_searches_on_its_OWN_bar_not_the_code_one():
     with ExitStack() as stack:
         for ctx in _arm_patches(
             pc, [], MagicMock(), rule_search=search,
-            cfg={"enabled": True, "threshold": 0.60,
-                 "top_k": 3, "rule_threshold": 0.81},
+            cfg=writepath_cfg(threshold=0.60, top_k=3, rule_threshold=0.81),
         ):
             stack.enter_context(ctx)
         await pc.build_write_path_hint(
@@ -392,16 +391,15 @@ def test_every_rules_payload_caller_names_itself():
 def _tool_patches(pc, hits, recorder, cfg=None, retrieval_log=None):
     return (
         patch.object(pc, "get_writepath_config",
-                     AsyncMock(return_value=cfg or {
-                         "enabled": True, "threshold": 0.6,
-                         "top_k": 3, "rule_threshold": 0.6,
-                         # The command arm reads its OWN bar since #3853, and
-                         # a stub missing this key does not fail where a
-                         # reader would see it: the arm fails open, so the
-                         # KeyError becomes an empty hint and every case in
-                         # _ARMS reports the arm went silent instead.
-                         "tool_rule_threshold": 0.6,
-                     })),
+                     # Every key, derived from the surface registry (#4102).
+                     # A stub missing one does not fail where a reader would
+                     # see it: the arm fails open, so the KeyError becomes an
+                     # empty hint and every case in _ARMS reports the arm went
+                     # silent instead.
+                     AsyncMock(return_value=cfg or writepath_cfg(
+                         threshold=0.6, rule_threshold=0.6,
+                         tool_rule_threshold=0.6,
+                     ))),
         patch.object(pc, "semantic_search_rules", AsyncMock(return_value=hits)),
         patch.object(pc, "record_retrieval", retrieval_log or MagicMock()),
         patch.object(pc, "record_rule_surfaced", recorder),
@@ -433,9 +431,10 @@ async def _run_tool_arm(hits, recorder, command="curl -s https://git.example/api
 
 def _prompt_patches(pc, hits, recorder, retrieval_log=None):
     return (
-        # The arm reads its own threshold key rather than a shared config
-        # object — a third corpus with a bar nothing has yet tuned for it.
-        patch.object(pc, "get_setting", AsyncMock(return_value="0.6")),
+        # The arm reads its own floor and budget from the surface registry
+        # rather than a shared config object (#4102) — a third corpus, with a
+        # pair nothing has yet tuned for it.
+        patch.object(rs, "get_setting", AsyncMock(return_value="0.6")),
         patch.object(pc, "semantic_search_rules", AsyncMock(return_value=hits)),
         patch.object(pc, "record_retrieval", retrieval_log or MagicMock()),
         patch.object(pc, "record_rule_surfaced", recorder),
@@ -469,7 +468,7 @@ async def test_the_prompt_arm_retrieves_against_what_the_operator_SAID():
     ))])
     from scribe.services import plugin_context as pc
     with ExitStack() as stack:
-        stack.enter_context(patch.object(pc, "get_setting", AsyncMock(return_value="0.6")))
+        stack.enter_context(patch.object(rs, "get_setting", AsyncMock(return_value="0.6")))
         stack.enter_context(patch.object(pc, "semantic_search_rules", search))
         stack.enter_context(patch.object(pc, "record_retrieval", MagicMock()))
         stack.enter_context(patch.object(pc, "record_rule_surfaced", rec))
@@ -503,7 +502,7 @@ async def test_the_prompt_arm_says_nothing_when_asked_nothing():
     log = MagicMock()
     from scribe.services import plugin_context as pc
     with ExitStack() as stack:
-        stack.enter_context(patch.object(pc, "get_setting", AsyncMock(return_value="0.6")))
+        stack.enter_context(patch.object(rs, "get_setting", AsyncMock(return_value="0.6")))
         stack.enter_context(patch.object(pc, "semantic_search_rules", search))
         stack.enter_context(patch.object(pc, "record_retrieval", log))
         stack.enter_context(patch.object(pc, "record_rule_surfaced", MagicMock()))
@@ -1416,7 +1415,7 @@ async def _run_slot(general, preference, recorder=None, retrieval_log=None, **kw
     from scribe.services import plugin_context as pc
     rec = recorder or MagicMock()
     with ExitStack() as stack:
-        stack.enter_context(patch.object(pc, "get_setting", AsyncMock(return_value="0.6")))
+        stack.enter_context(patch.object(rs, "get_setting", AsyncMock(return_value="0.6")))
         stack.enter_context(patch.object(
             pc, "semantic_search_rules", _search_by_kind(general, preference)))
         stack.enter_context(patch.object(
@@ -1480,7 +1479,7 @@ async def test_the_slot_query_can_only_answer_with_a_preference():
     from scribe.services import plugin_context as pc
     search = _search_by_kind(_RULES_FILLING_THE_LIMIT, _PREF_HIT)
     with ExitStack() as stack:
-        stack.enter_context(patch.object(pc, "get_setting", AsyncMock(return_value="0.6")))
+        stack.enter_context(patch.object(rs, "get_setting", AsyncMock(return_value="0.6")))
         stack.enter_context(patch.object(pc, "semantic_search_rules", search))
         stack.enter_context(patch.object(pc, "record_retrieval", MagicMock()))
         stack.enter_context(patch.object(pc, "record_rule_surfaced", MagicMock()))
@@ -1617,8 +1616,7 @@ async def test_each_act_arm_searches_at_its_own_bar():
     """The split, where it actually takes effect."""
     from scribe.services import plugin_context as pc
 
-    cfg = {"enabled": True, "threshold": 0.6, "top_k": 3,
-           "rule_threshold": 0.77, "tool_rule_threshold": 0.61}
+    cfg = writepath_cfg(threshold=0.6, top_k=3, rule_threshold=0.77, tool_rule_threshold=0.61)
 
     search = AsyncMock(return_value=list(_THREE_HITS))
     with ExitStack() as stack:
@@ -1646,8 +1644,7 @@ async def test_an_act_arm_reports_the_bar_it_actually_searched_at():
     """
     from scribe.services import plugin_context as pc
 
-    cfg = {"enabled": True, "threshold": 0.6, "top_k": 3,
-           "rule_threshold": 0.77, "tool_rule_threshold": 0.61}
+    cfg = writepath_cfg(threshold=0.6, top_k=3, rule_threshold=0.77, tool_rule_threshold=0.61)
 
     search = AsyncMock(return_value=list(_THREE_HITS))
     log = MagicMock()
@@ -1712,8 +1709,7 @@ async def test_the_act_arms_scope_their_search_to_the_bound_project(bound, scope
     global rules only, which the search spells as `project_id=None`."""
     from scribe.services import plugin_context as pc
 
-    cfg = {"enabled": True, "threshold": 0.6, "top_k": 3,
-           "rule_threshold": 0.6, "tool_rule_threshold": 0.6}
+    cfg = writepath_cfg(threshold=0.6, top_k=3, rule_threshold=0.6, tool_rule_threshold=0.6)
     tool_search = AsyncMock(return_value=[])
     with ExitStack() as stack:
         stack.enter_context(patch.object(
@@ -1726,7 +1722,7 @@ async def test_the_act_arms_scope_their_search_to_the_bound_project(bound, scope
 
     prompt_search = AsyncMock(return_value=[])
     with ExitStack() as stack:
-        stack.enter_context(patch.object(pc, "get_setting", AsyncMock(return_value="0.6")))
+        stack.enter_context(patch.object(rs, "get_setting", AsyncMock(return_value="0.6")))
         stack.enter_context(patch.object(pc, "semantic_search_rules", prompt_search))
         stack.enter_context(patch.object(pc, "record_retrieval", MagicMock()))
         stack.enter_context(patch.object(pc, "record_rule_surfaced", MagicMock()))