feat(lessons): a lesson reaches the moment it applies, and says it binds nothing (#3732)

WHICH ARM — the two note arms, and no new one.

`write_path` filters kinds, so a lesson was not outranked there but
unreachable, which is #3702's shape: an arm that never had the candidate
reports a healthy bar. It now asks for lessons alongside snippets and
issues. The founding example of the kind is a lesson about a code shape,
and this is the arm that fires when code is written.

`auto_inject` does not filter kinds, so lessons were already candidates —
but scoped to the bound project, which for a kind whose whole claim is
that it transfers is the same silence. Both arms now pass
`include_global_kinds` (#3730).

WHOSE BUDGET — a reserved slot in the prompt menu, none on the write path.

The step's premise needs a correction: the notes menu and the rule hints
are separate functions with separate budgets, so a line reserved here
displaces a note, never a rule. (`RULEHINT_LIMIT` is also 5, not 1, since
#4102 made it a default rather than a cap.)

The trade taken: a note crowded out is a lost convenience and a rule
crowded out still fires at an act arm, but a lesson crowded out is the
feature failing — a lesson exists only to be met at the moment it
applies, so the arm IS its delivery and the loss is total and silent.
That is `preference_slot`'s argument, and the rarity is `reuse_slot`'s.
It buys position, never a lower bar, and it EXTENDS rather than evicting:
a displaced hit sits in the general search's own log row, and evicting it
would make two tables disagree about one call (#3668, #379).

No slot on the write path: that arm fires before every Write and Edit,
where a guaranteed extra line is a guaranteed extra interruption, and its
field is already just snippets, issues and lessons rather than the whole
corpus.

`lesson_slot` logs its own retrieval and its own surfacing from the first
deploy, and the general contest stays open to the kind — otherwise "the
slot earns its line" would be true by construction.

THE VOICE — "they don't always have to be followed".

The menu's register is already the non-binding one. What it lacked is
that a lesson reads as one more title in a list of material when it is
advice someone paid for. One clause, in the header, only when a lesson is
on the menu: weigh it, use your judgement, it is not a rule and binds
nothing. It deliberately does not borrow the rule arms' "before deciding
it does not apply", and a guard asserts that phrase never appears.

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

src/scribe/services/retrieval_surfaces.py

@@ -209,12 +209,20 @@ SURFACES: dict[str, Surface] = {
     ),
 }
 
-# Reserved slots are deliberately absent. `preference_slot` and `reuse_slot`
-# borrow their parent arm's floor and are hard-limited to one hit each, because
-# their entire purpose is to guarantee a single line to a kind of record that
-# keeps losing a general score contest (#2246, #3894). A budget of "1" is the
-# feature; exposing it as tunable would invite setting it to 0 and silently
-# removing the guarantee.
+# Reserved slots are deliberately absent. `preference_slot`, `reuse_slot` and
+# `lesson_slot` borrow their parent arm's floor and are hard-limited to one hit
+# each, because their entire purpose is to guarantee a single line to a kind of
+# record that keeps losing a general score contest (#2246, #3894) — or, for
+# `lesson_slot`, to a kind whose loss is total rather than merely a lost
+# convenience, since a lesson has no act arm to fall back on and nobody browses
+# lessons looking for one (milestone 385). A budget of "1" is the feature;
+# exposing it as tunable would invite setting it to 0 and silently removing the
+# guarantee.
+#
+# They are still logged under their own `source`, which is what keeps them
+# judgeable without being tunable: `best_available_id` names the record each
+# bar refused, so a slot that never places, or one that places weak hits, shows
+# up as evidence rather than as an argument.
 
 
 def surface_names() -> list[str]: