feat(telemetry): the rule arm records what it showed, and get_rule records the read (#3316)

Milestone 333 step 2. Step 1 built the table; a counter nobody calls reads zero
and looks exactly like a surface nobody uses, which is #2663's shape.

SURFACED — the standing-rule arm in build_write_path_hint, beside the
record_retrieval it already made. Two tables, and the split is not arbitrary:
retrieval_logs is one row per CALL keyed on the score distribution a threshold
is tuned from; rule_usage_events is one row per RULE per event, the grain "was
this hint ever acted on" needs and the grain a JSONB result_ids array cannot be
indexed at.

The comment there said rule ids had nowhere to go — that note_usage_events
remaps ids on restore, so a rule id would return attached to whatever note took
that number. Still true of the NOTE table, and precisely why step 1 built its
own. Rewritten to say the gap is closed rather than leaving a stale rationale
that would have someone re-derive the same dead end.

Records `fresh`, i.e. AFTER exclude_rule_ids. A rule the session already holds
was considered and not shown; counting it would inflate the denominator with
claims the agent never saw, and the ratio would then fall for a reason that has
nothing to do with whether hints land.

PULLED — two doors, both after their access check so a refused read is not a
pull. mcp_get_rule is the one that matters: the arm's own message ends "Read it
with get_rule(N)", so that call is the exact action a landed hint produces.
rest_rule carries the other prefix, and the prefix is load-bearing — "is this
rule dead weight?" is served by any pull, "did that injected hint land?" by
agent pulls only.

NOT a pull: rule_history. It loads the rule for its title and its own output
says "The current wording is on the rule itself — get_rule(N)", so counting it
would credit a read of the history as a read of the rule and double-count
anyone who then follows that pointer. list_always_on_rules and enter_project
are likewise bulk resident loads, not somebody choosing to open one record.

tests/test_rule_usage_wiring.py is cross-cutting on purpose: the surfaced end
is in plugin_context, the pull end in two other modules, and "both ends meet"
is a property no module-shaped file asserts. It covers the exclusion boundary,
that a failing recorder cannot break the write, that a refused read records
nothing, and two completeness guards — every door records, and the bulk loaders
still do not.

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

src/scribe/mcp/tools/rulebooks.py

@@ -18,6 +18,7 @@ from scribe.mcp._context import current_user_id
 from scribe.services import dedup as dedup_svc
 from scribe.services import rulebooks as rulebooks_svc
 from scribe.services import trash as trash_svc
+from scribe.services.rule_usage import record_rule_pulled
 
 
 # ── Rulebook CRUD ───────────────────────────────────────────────────────
@@ -288,6 +289,11 @@ async def get_rule(rule_id: int) -> dict:
     rule = await rulebooks_svc.get_rule(rule_id, uid)
     if rule is None:
         raise ValueError(f"rule {rule_id} not found")
+    # THE pull that matters. The write-path rule arm's own message ends "Read
+    # it with get_rule(N)", so this is the exact action the hint asks for and
+    # the only evidence that one landed. Recorded after the access check, so a
+    # refused read is not counted as a pull.
+    record_rule_pulled(user_id=uid, rule_id=int(rule.id), source="mcp_get_rule")
     return await rulebooks_svc.rule_detail(uid, rule)
 
 

src/scribe/routes/rulebooks.py

@@ -10,6 +10,7 @@ from quart import Blueprint, jsonify, request
 from scribe.auth import get_current_user_id, login_required
 import scribe.services.rulebooks as rulebooks_svc
 from scribe.services.trash import delete as trash_delete
+from scribe.services.rule_usage import record_rule_pulled
 
 rulebooks_bp = Blueprint("rulebooks", __name__, url_prefix="/api")
 
@@ -182,6 +183,11 @@ async def get_rule(rule_id: int):
     rule = await rulebooks_svc.get_rule(rule_id, uid)
     if rule is None:
         return jsonify({"error": "rule not found"}), 404
+    # `rest_` rather than `mcp_`, and the prefix is load-bearing: "is this rule
+    # dead weight?" is served by any pull, but "did that injected hint land?"
+    # — the question this arm exists to answer — is served by AGENT pulls only.
+    # A person clicking through the rule list says nothing about the hint.
+    record_rule_pulled(user_id=uid, rule_id=int(rule.id), source="rest_rule")
     return jsonify(await rulebooks_svc.rule_detail(uid, rule))
 
 

src/scribe/services/plugin_context.py

@@ -32,6 +32,7 @@ from scribe.services import snippets as snippets_svc
 from scribe.services.access import label_shared_items, owner_names_for
 from scribe.services.embeddings import semantic_search_notes, semantic_search_rules
 from scribe.services.note_usage import record_surfaced
+from scribe.services.rule_usage import record_rule_surfaced
 from scribe.services.supersession import superseded_ids
 from scribe.services.retrieval_telemetry import record_retrieval
 from scribe.services.settings import get_setting
@@ -1140,15 +1141,29 @@ async def build_write_path_hint(
             )
             rule_ids.append(rule.id)
         if fresh:
-            # retrieval_logs, NOT note_usage_events: that table's ids are
-            # remapped on a backup restore, so a rule id there would return
-            # attached to whatever note took that number. This one is never
-            # restored, and `source` already separates the surfaces.
+            # TWO tables, and the split is not arbitrary. retrieval_logs is one
+            # row per CALL, keyed on the score distribution a threshold is
+            # tuned from. rule_usage_events is one row per RULE per event,
+            # which is the grain "was this hint ever acted on" needs and the
+            # grain a JSONB result_ids array cannot be indexed at.
+            #
+            # This comment used to say rule ids had nowhere to go — that
+            # note_usage_events remaps ids on restore, so a rule id there would
+            # return attached to whatever note took that number. That is still
+            # true of the NOTE table, and it is exactly why rule_usage_events
+            # is its own (milestone 333 step 1). The gap it described is closed.
             record_retrieval(
                 user_id=user_id, source="write_path_rule", query=code or path,
                 threshold=cfg["threshold"], limit=2, project_id=project_id,
                 is_task=None, results=fresh,
             )
+            # `rule_ids` is `fresh`, i.e. AFTER exclude_rule_ids. A rule the
+            # session already holds was considered and not shown, and counting
+            # it would inflate the denominator with claims the agent never saw
+            # — which reads as a precision problem this arm does not have.
+            record_rule_surfaced(
+                user_id=user_id, rule_ids=rule_ids, source="write_path_rule",
+            )
     except Exception:
         logger.debug("write-path rule arm failed", exc_info=True)