docs(6205): retrieval_registry comments state the reason, not the instance that taught it

Record and milestone citations go. The logs_unconditionally docstring, the
place arm's comment and the fan-out key note state the condition they guard
rather than the bug that once hit it.

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

src/scribe/services/retrieval_registry.py

@@ -1,12 +1,12 @@
-"""Every point that retrieves or surfaces a record, declared (#3431, #3432).
+"""Every point that retrieves or surfaces a record, declared.
 
 WHY A DECLARED LIST WHEN THE ROWS ALREADY NAME THEIR SOURCE. Because the rows
 can only describe arms that FIRED. A surface that emits nothing writes no row,
 so it is indistinguishable from a surface that does not exist — and the two
 call for opposite responses. `retrieval_telemetry` could report perfect health
-for a window in which half the arms never ran. #3430 hit exactly this: its
+for a window in which half the arms never ran, and a "silent surface"
-"silent surface" finding could only be made by a human who happened to know
+finding could only be made by a human who happened to know which arms were
-which arms were supposed to be there.
+supposed to be there.
 
 This module is that knowledge, written down. It carries the two facts the rows
 structurally cannot:
@@ -16,7 +16,7 @@ structurally cannot:
     for a week is an arm that has lost the ability to speak. Same row shape,
     opposite meanings, and only the caller's intent separates them.
   * **expected to emit, or deliberately quiet with a reason.** A justified
-    silence must not read as a gap (#2475). `rest_*` sources fire only when a
+    silence must not read as a gap. `rest_*` sources fire only when a
     person opens the web UI; on an install driven entirely through MCP their
     absence is correct and permanent, and reporting it every window would
     train the reader to ignore the list that also carries the real ones.
@@ -31,15 +31,14 @@ reserved slots belong in it precisely because they are judgeable without being
 tunable. One is a control panel; the other is an inventory. A test asserts
 every tunable surface also appears here, so the two cannot drift apart.
 
-ADDING A RANKED ARM MEANS WRITING ITS SPEC. Since milestone 456 step 5 the
+ADDING A RANKED ARM MEANS WRITING ITS SPEC. The
 ranked rows are read off `retrieval_pipeline.RANKED`, each spec declaring its
 own (`Declared`). Any OTHER point — a lookup, an asked search, an ambient
 carrier, a pull — still means adding a row here. `tests/test_retrieval_registry.py`
 walks the call sites with the ast module and fails on a source it cannot find
 below — deliberately not a grep, because two of the sources in this file
 (`wide_net`, `preference_slot`) reach their recorder through a
-module constant and a grep for `source="` misses both. That is the
+module constant and a grep for `source="` misses both.
-narrowing #3191 warns about, caught here in the act.
 """
 from __future__ import annotations
 
@@ -89,7 +88,7 @@ class Point:
 
     False means "this can be quiet forever and that is correct" — and then
     `quiet_because` must say why, so a reader meets a decision rather than a
-    hole (#2475).
+    hole.
     """
 
     quiet_because: str = ""
@@ -97,11 +96,11 @@ class Point:
     logs_unconditionally: bool = True
     """Whether this arm writes a row even when it returns NOTHING.
 
-    THE #3497 GUARD, and the reason this field is not merely documentation.
+    The reason this field is not merely documentation: an arm that logs only
-    Both rule arms once logged only their hits, so their zero-result count was
+    its hits has a zero-result count that is structurally 0, and a "cannot
-    structurally 0 — and a "cannot decline" warning computed over that would
+    decline" warning computed over that would fire on a LOGGING BUG while
-    have fired on a LOGGING BUG while reporting a ranking problem, sending the
+    reporting a ranking problem, sending the reader to move a floor that was
-    reader to move a floor that was never involved. An arm whose logging has
+    never involved. An arm whose logging has
     not been confirmed unconditional is not eligible for that warning; it is
     excluded from the check rather than trusted.
     """
@@ -114,8 +113,7 @@ def _p(source, kind, what, **kw) -> tuple[str, Point]:
 POINTS: dict[str, Point] = dict([
     # ── Unbidden push arms ───────────────────────────────────────────────
     #
-    # The RANKED ones are read off the pipeline's specs (milestone 456 step
+    # The RANKED ones are read off the pipeline's specs: every arm, and every stage that runs a query of its own and records
-    # 5): every arm, and every stage that runs a query of its own and records
     # under its own name, declares its row where it is defined. What stays
     # here is what no spec describes — the lookups below, and everything asked,
     # ambient or pulled.
@@ -123,7 +121,7 @@ POINTS: dict[str, Point] = dict([
          expects_traffic=not spec.declared.quiet_because,
          quiet_because=spec.declared.quiet_because)
       for spec in RANKED),
-    # A LOOKUP, not a ranker (#4796): a record the operator named by number
+    # A LOOKUP, not a ranker: a record the operator named by number
     # in the message, fetched by id. No score and no bar, so it writes no
     # retrieval_logs row and no score-shaped warning can apply; its rows are
     # in `note_usage_events`, where pull-through says whether naming a record
@@ -133,7 +131,7 @@ POINTS: dict[str, Point] = dict([
        expects_traffic=False,
        quiet_because="speaks only when a message names a record by its id; "
                      "a window in which none did is correctly silent here"),
-    # The moment arm (milestone 458). A LOOKUP, not a ranker: a rule mounted on
+    # The moment arm. A LOOKUP, not a ranker: a rule mounted on
     # a moment arrives when that moment happens, with no score, so it writes no
     # retrieval_logs row and no score-shaped warning can apply. Its rows are in
     # `rule_usage_events`, each carrying the moment in `detail`.
@@ -142,11 +140,11 @@ POINTS: dict[str, Point] = dict([
        expects_traffic=False,
        quiet_because="speaks only once some rule is mounted on a moment; an "
                      "install where none is mounted is correctly silent here"),
-    # The rulings arm (milestone 444). A LOOKUP, not a ranker: a path falls
+    # The rulings arm. A LOOKUP, not a ranker: a path falls
     # under a System's patterns or it does not, so nothing here writes to
     # retrieval_logs and no score-shaped warning can apply. Its rows are in
     # `system_usage_events`, read back as `retrieval_telemetry`'s
-    # `system_usage` block (#4769).
+    # `system_usage` block.
     _p("rulings_pre_tool", UNBIDDEN,
        "an area's rulings, shown because a command touched its files",
        expects_traffic=False,
@@ -179,9 +177,9 @@ POINTS: dict[str, Point] = dict([
     # ── The write-path menu's own arms ───────────────────────────────────
     #
     # These are NOT in retrieval_logs. The place arm carries no score and so
-    # has no row there at all (#2085) — before it was split out, the arm
+    # has no row there at all; declaring it here is what lets the arm making
-    # firing on the strongest possible claim, "there is already a canonical
+    # the strongest possible claim, "there is already a canonical helper in
-    # helper in this exact file", was the one arm nobody could measure.
+    # this exact file", be measured.
     _p("write_path_place", AMBIENT, "a snippet already placed in this very file"),
     _p("write_path_semantic", AMBIENT, "prior art matched by meaning"),
     _p("write_path_sync", AMBIENT,
@@ -225,12 +223,12 @@ POINTS: dict[str, Point] = dict([
 # out would not fail here. What catches that is `assert_registered`, which the
 # recorders call as the row is written.
 # Keyed by the EXACT string the extractor produces, matched by equality rather
-# than by prefix. A prefix match was the first spelling and it silently matched
+# than by prefix. The paths are relative to `src/` and so begin `scribe/`; a
-# nothing, because the paths are relative to `src/` and so begin `scribe/` —
+# prefix spelled any other way silently matches nothing, and every site sails
-# every site sailed through a check that looked like it was running.
+# through a check that looks like it is running.
 FAN_OUT_SITES: dict[str, tuple[str, ...]] = {
     # The write path's two LOOKUPS. Its ranked arm (`write_path_semantic`)
-    # records through the pipeline's site below (milestone 456 step 4).
+    # records through the pipeline's site below.
     "scribe/services/plugin_context.py::record_surfaced(source=arm)": (
         "write_path_place", "write_path_sync",
     ),
@@ -241,7 +239,7 @@ FAN_OUT_SITES: dict[str, tuple[str, ...]] = {
         "enter_project", "start_planning", "get_task", "get_project",
         "get_milestone",
     ),
-    # The one retrieval pipeline (milestone 456): every ranked arm's call row
+    # The one retrieval pipeline: every ranked arm's call row
     # and surfacing rows — both corpora — are written by these sites, so
     # `source` arrives as a value. The values are the pipeline's own specs,
     # read rather than restated, so an arm added there is declared here by
@@ -255,7 +253,7 @@ FAN_OUT_SITES: dict[str, tuple[str, ...]] = {
     "scribe/services/retrieval_pipeline.py::record_rule_surfaced(source=source)": (
         tuple(arm.source for arm in RULE_ARMS)
     ),
-    # The reply moment's mounted half (milestone 458): it records under the
+    # The reply moment's mounted half: it records under the
     # moment arm's source, read from the pipeline's constant so the two doors
     # cannot drift apart on the name.
     "scribe/services/moment_delivery.py::record_rule_surfaced(source=<expression>)": (