feat(lessons): a lesson is yours to keep current too (#4195)

The lesson kind shipped with every mechanism for growing and nothing
telling a session to use them. `learned_from` is a list on purpose, the
dedup gate hands back an existing id rather than minting a twin, and
`update_lesson` already names re-keying a bad trigger as the edit that
pays most. None of that was reachable as a habit.

The exclusivity claim was the bug. The skill said "a preference is the
one record you keep current yourself", and by naming only preferences it
put lessons outside the habit. That sentence is now "a preference is
yours to keep current", which says the same thing about preferences
without saying anything false about lessons.

Beside it, a paragraph on what growing a lesson means: another incident
added to what taught it, a claim stated more exactly, or a trigger
re-keyed to the situation that really fired. Written as a practice
rather than a prohibition (rule 165) — the reader is named as the one
person placed to judge the trigger, because they are standing in the
situation it claims to name.

`get_lesson` carries the same prompt at the moment it bites: a session
reading a lesson inside the situation it names is the only reader who
can tell whether the trigger is keyed to what actually fired.

The guidance-ownership registry gains the topic and re-points the
preference topic's statement, since the phrase it pinned is the sentence
this change rewrites — the module asks for exactly that, in the same
commit. No index marker: the index names session-start reflexes and this
one fires mid-work, so `_INSTRUCTIONS` stays at 1998/2000.

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

plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "scribe",
   "description": "Scribe for Claude Code: connects the scribe MCP server, adds the hooks that deliver live project state and relevant records at the right moment, ships the shared client-neutral Scribe skills (using-scribe, writing-plans, reporting-back, systematic-debugging, verification, brainstorming, reusing-code, shape-accounting), and syncs your saved Scribe Processes as skills (/scribe:sync).",
-  "version": "2026.09.19.1614",
+  "version": "2026.09.20.0317",
   "author": {
     "name": "Bryan Van Deusen"
   },

plugin/skills/using-scribe/SKILL.md

@@ -110,15 +110,27 @@ Two constraints on *how* that's achieved:
    silently, because it sometimes answers that what you are holding was never
    a rule — and routing an observation is not losing it.
 
-   **A preference is the one record you keep current yourself.** When the
+   **A preference is yours to keep current.** When the operator corrects you,
-   operator corrects you, or the preference on file no longer matches how they
+   or the preference on file no longer matches how they actually want
-   actually want something done, `update_preference` — that is expected, not a
+   something done, `update_preference` — that is expected, not a liberty, and
-   liberty, and updating one mid-work is the normal case rather than an
+   updating one mid-work is the normal case rather than an interruption of it.
-   interruption of it. It wants the task or note that taught the change. Say in the
+   It wants the task or note that taught the change. Say in the same turn that
-   same turn that you did it, so they can disagree while it is in front of
+   you did it, so they can disagree while it is in front of them. A rule waits
-   them. A rule waits for the operator instead: `create_rule` proposes and
+   for the operator instead: `create_rule` proposes and asks. If what you
-   asks. If what you learned is that something MUST be done a certain way,
+   learned is that something MUST be done a certain way, that is a rule to
-   that is a rule to propose, not a preference to harden in place.
+   propose, not a preference to harden in place.
+
+   **A lesson grows each time it proves itself.** When one arrives and the
+   situation it names is the one you are actually in, you are the single
+   reader placed to tell whether its trigger is keyed right and whether its
+   claim covers what you are seeing. `update_lesson` takes what you now know:
+   another incident added to what taught it, the claim stated more exactly,
+   or — the edit worth most — a trigger re-keyed to the situation that really
+   fired. A lesson nobody reaches is seldom wrong; far more often it is
+   waiting in a situation nobody is in. One claim that has met the same
+   failure four times is worth more than four claims that each met it once,
+   so when a near-duplicate create hands back an existing id, that is the
+   record to grow.
 
    **Preferences shape how work is done, never what gets recorded.** They
    govern your conduct — how you report, how carefully you pace, which form

src/scribe/mcp/tools/lessons.py

@@ -178,7 +178,17 @@ async def create_lesson(
 
 
 async def get_lesson(lesson_id: int) -> dict:
-    """Fetch one lesson by id, with its trigger and sources read back out."""
+    """Fetch one lesson by id, with its trigger and sources read back out.
+
+    IF THIS LESSON JUST PROVED ITSELF, IT IS WORTH MORE THAN IT SAYS. You are
+    reading it inside the situation it names, which makes you the one reader
+    who can tell whether its trigger is keyed to what actually fired and
+    whether its claim covers what you are seeing. `update_lesson` takes
+    another incident into `learned_from`, a claim stated more exactly, or a
+    re-keyed trigger — and the trigger is the edit that pays most, because a
+    lesson keyed to a situation nobody is in looks exactly like one nobody
+    needed.
+    """
     uid = current_user_id()
     note = await lessons_svc.get_lesson(uid, lesson_id)
     if note is None:

tests/test_guidance_ownership.py

@@ -118,7 +118,8 @@ TOPICS: tuple[Topic, ...] = (
           "an empty session is not evidence of an empty rulebook",
           index=('content_type="rule"', "nothing matched")),
     Topic("rules bind, preferences guide and are kept current", U, ("preference", "update_preference"),
-          "a preference is the one record you keep current yourself", index=("preferences guide",)),
+          "updating one mid-work is the normal case rather than an interruption of it",
+          index=("preferences guide",)),
     Topic("kind is force: a rule binds, a preference guides, a lesson informs", U,
           ("lesson", "costs time", "costs consistency"),
           "what happens if someone doesn't do this",
@@ -129,6 +130,14 @@ TOPICS: tuple[Topic, ...] = (
           # mis-routing #3733 recorded happens, and the caller there has not
           # necessarily read the skill.
           shared_with=("docstrings",)),
+    Topic("a lesson grows each time it proves itself", U,
+          ("update_lesson", "re-keyed", "grows each time"),
+          "one claim that has met the same failure four times is worth more "
+          "than four claims that each met it once",
+          # No index marker. The index names session-START reflexes, and this
+          # one fires mid-work, the moment a lesson arrives in a situation it
+          # actually names. `lessons inform` already points at the kind.
+          shared_with=("docstrings",)),
     Topic("preferences shape how work is done, never what is recorded", U,
           ("never what gets recorded",),
           "a preference never makes a task into a note"),