refactor(notes): a snippet's and lesson's stored title is its name; the trigger joins it only in the embedded document (milestone 427)

The title was `subject — trigger` because the stored title WAS the
embedded one, and the join is what makes these kinds rank on the
situation they apply to (#2485). Every surface that shows a title then
showed the trigger too -- menus, lists and search rows ran to kilobytes.

- embeddings.document_title(title, note_type, data, body) joins the
  trigger from `data` (body fallback) at embed time. Idempotent: an
  un-migrated composed title comes out the same, never doubled. The
  embed path, the startup backfill and the dedup gate's semantic signal
  all use it, so the embedded text -- and every vector -- is unchanged.
- Writers store the subject: snippet create/update (service, REST, MCP)
  and lesson_document. Both compose_title helpers are removed.
- Readers: dedup takes `data`; the menus strip the embedded title from a
  passage; list rows project `when_to_use`, which SnippetListView reads.
- 0108 rewrites existing rows on an exact `' — ' || <own trigger>`
  suffix with raw SQL, leaving updated_at alone so the backfill does not
  re-embed the corpus for identical vectors. Downgrade recomposes.

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

alembic/versions/0108_trigger_leaves_the_stored_title.py

@@ -0,0 +1,64 @@
+"""trigger_leaves_the_stored_title — a snippet's and lesson's title is its name (milestone 427)
+
+Revision ID: 0108
+Revises: 0107
+Create Date: 2026-09-23
+
+Snippets and lessons stored their title as `subject — trigger`, because the
+join is what makes these kinds rank on the situation they apply to (#2485) and
+the stored title WAS the embedded one. Every surface that shows a title then
+showed the trigger too: menu lines, lists and search rows ran to 1,500–3,000
+characters, and an injected repeat spent all of it again.
+
+The trigger's home is `data` (decision #4157), and since this milestone the
+join happens at embed time (`embeddings.document_title`). This revision
+rewrites the rows already stored.
+
+EXACT-SUFFIX, READ FROM THE ROW'S OWN MIRROR. A title is only rewritten when
+it ends with `' — ' || <that row's trigger>`, so a subject that legitimately
+contains an em dash is never cut, and a row whose title and mirror disagree —
+hand-edited through the generic note door — is left alone. Such a row still
+embeds correctly (`document_title` is idempotent) and merely shows its old
+title; that is the right way round for a data migration to fail.
+
+NO RE-EMBED, AND `updated_at` IS NOT TOUCHED. The embedded text is identical
+before and after, so the vectors are already right. The startup backfill
+re-embeds any row whose `updated_at` is newer than its vectors, and a raw
+UPDATE that leaves `updated_at` alone is what keeps this from queueing the
+whole snippet corpus for work that would produce the same numbers. There is
+no database trigger on `updated_at`; it is set by the ORM only.
+"""
+from alembic import op
+
+revision = "0108"
+down_revision = "0107"
+branch_labels = None
+depends_on = None
+
+# kind → the `data` key its trigger is mirrored under (embeddings._TRIGGER_DATA_KEYS).
+_KINDS = (("snippet", "when_to_use"), ("lesson", "when_to_apply"))
+_SEP = " — "
+
+
+def upgrade() -> None:
+    for note_type, key in _KINDS:
+        op.execute(f"""
+            UPDATE notes
+               SET title = btrim(left(title, length(title) - length('{_SEP}' || (data->>'{key}'))))
+             WHERE note_type = '{note_type}'
+               AND coalesce(btrim(data->>'{key}'), '') <> ''
+               AND right(title, length('{_SEP}' || (data->>'{key}'))) = '{_SEP}' || (data->>'{key}')
+        """)
+
+
+def downgrade() -> None:
+    # Recompose, on the same condition inverted: only where the trigger is not
+    # already on the end, so a downgrade run twice cannot double it.
+    for note_type, key in _KINDS:
+        op.execute(f"""
+            UPDATE notes
+               SET title = title || '{_SEP}' || (data->>'{key}')
+             WHERE note_type = '{note_type}'
+               AND coalesce(btrim(data->>'{key}'), '') <> ''
+               AND right(title, length('{_SEP}' || (data->>'{key}'))) <> '{_SEP}' || (data->>'{key}')
+        """)

frontend/src/api/snippets.ts

@@ -91,6 +91,9 @@ export interface SnippetListItem {
    *  hit can be flagged as being in a DIFFERENT language than the file being
    *  written, which is a shape to adapt rather than code to paste. */
   language?: string;
+  /** When to reach for it, projected from the `data` mirror. The title is the
+   *  name alone since milestone 427, so this is where the situation lives. */
+  when_to_use?: string;
   /** Always present from the backend, zero-filled for records with no events. */
   usage?: SnippetUsage;
   /** Present on the detail record; the list feed carries it when a check has

frontend/src/views/SnippetListView.vue

@@ -189,11 +189,18 @@ const onLocationInput = onSearchInput;
 
 onMounted(loadSnippets);
 
-/** Titles are stored as "name — when to reach for it"; split for display. */
-function splitTitle(title: string): { name: string; when: string } {
-  const idx = title.indexOf(" — ");
-  if (idx === -1) return { name: title, when: "" };
-  return { name: title.slice(0, idx), when: title.slice(idx + 3) };
+/** A row's name and when-to-use. The title is the name alone since milestone
+ *  427 and the situation arrives as `when_to_use`; a title composed before then
+ *  ("name — when to reach for it") is split, so either shape reads the same. */
+function nameAndWhen(s: { title: string; when_to_use?: string }): { name: string; when: string } {
+  const when = s.when_to_use || "";
+  if (when && s.title.endsWith(` — ${when}`)) {
+    return { name: s.title.slice(0, -(when.length + 3)), when };
+  }
+  if (when) return { name: s.title, when };
+  const idx = s.title.indexOf(" — ");
+  if (idx === -1) return { name: s.title, when: "" };
+  return { name: s.title.slice(0, idx), when: s.title.slice(idx + 3) };
 }
 
 function languageOf(tags: string[]): string {
@@ -313,7 +320,7 @@ function driftTitle(s: SnippetListItem): string {
         <div v-for="(g, i) in duplicateGroups" :key="i" class="dup-group">
           <div class="dup-members">
             <span v-for="s in g.snippets" :key="s.id" class="dup-member">
-              {{ splitTitle(s.title).name }}
+              {{ nameAndWhen(s).name }}
             </span>
           </div>
           <span class="dup-score">{{ Math.round(g.top_score * 100) }}% alike</span>
@@ -413,11 +420,11 @@ function driftTitle(s: SnippetListItem): string {
             :class="{ on: selectedIds.has(s.id) }"
             aria-hidden="true"
           ></span>
-          <span class="snippet-name">{{ splitTitle(s.title).name }}</span>
+          <span class="snippet-name">{{ nameAndWhen(s).name }}</span>
           <span v-if="languageOf(s.tags)" class="lang-pill">{{ languageOf(s.tags) }}</span>
         </div>
-        <p v-if="splitTitle(s.title).when" class="snippet-when">
-          {{ splitTitle(s.title).when }}
+        <p v-if="nameAndWhen(s).when" class="snippet-when">
+          {{ nameAndWhen(s).when }}
         </p>
         <div class="card-footer">
           <span class="meta-date">Updated {{ new Date(s.updated_at).toLocaleDateString() }}</span>
@@ -458,7 +465,7 @@ function driftTitle(s: SnippetListItem): string {
               :class="{ chosen: canonicalId === s.id }"
             >
               <input type="radio" name="canonical" :value="s.id" v-model="canonicalId" />
-              <span class="merge-choice-name">{{ splitTitle(s.title).name }}</span>
+              <span class="merge-choice-name">{{ nameAndWhen(s).name }}</span>
               <span class="merge-choice-tag">{{ canonicalId === s.id ? "keep" : "fold in" }}</span>
             </label>
           </div>

src/scribe/mcp/tools/lessons.py

@@ -168,6 +168,7 @@ async def create_lesson(
         dup = await dedup_svc.find_duplicate_note(
             uid, title, body, project_id=project_id or None,
             is_task=False, note_type=lessons_svc.LESSON_NOTE_TYPE,
+            data=lessons_svc.compose_data(what, when_to_apply),
         )
         if dup is not None:
             return dedup_svc.duplicate_response(dup, "lesson")

src/scribe/mcp/tools/snippets.py

@@ -176,7 +176,9 @@ async def create_snippet(
         raise ValueError("create_snippet requires a non-empty name and code")
     uid = current_user_id()
 
-    title = snippets_svc.compose_title(name, when_to_use)
+    # The NAME is the title (milestone 427); the trigger rides in `data` and
+    # joins the title only in the embedded document.
+    title = name.strip()
     body = snippets_svc.compose_body(
         code=code, language=language, signature=signature,
         when_to_use=when_to_use, repo=repo, path=path, symbol=symbol,
@@ -190,6 +192,7 @@ async def create_snippet(
             # location and code before it compares prose (#2518).
             code=code,
             locations=snippets_svc.resolve_locations(repo, path, symbol, locations),
+            data=snippets_svc.compose_data(name=name, when_to_use=when_to_use),
         )
         if dup is not None:
             return dedup_svc.duplicate_response(dup, "snippet")

src/scribe/routes/lessons.py

@@ -149,6 +149,7 @@ async def create_lesson_route():
             project_id=project_id,
             is_task=False,
             note_type=lessons_svc.LESSON_NOTE_TYPE,
+            data=lessons_svc.compose_data(what, when_to_apply),
         )
         if dup is not None:
             return jsonify(dedup_svc.duplicate_response(dup, "lesson")), 409

src/scribe/routes/snippets.py

@@ -96,7 +96,7 @@ async def create_snippet_route():
     if not data.get("force"):
         dup = await dedup_svc.find_duplicate_note(
             uid,
-            snippets_svc.compose_title(name, data.get("when_to_use", "")),
+            name.strip(),
             snippets_svc.compose_body(
                 code=data.get("code", ""),
                 language=data.get("language", ""),
@@ -119,6 +119,9 @@ async def create_snippet_route():
                 data.get("repo", ""), data.get("path", ""), data.get("symbol", ""),
                 data.get("locations"),
             ),
+            data=snippets_svc.compose_data(
+                name=name, when_to_use=data.get("when_to_use", ""),
+            ),
         )
         if dup is not None:
             return jsonify(dedup_svc.duplicate_response(dup, "snippet")), 409

src/scribe/services/dedup.py

@@ -248,6 +248,7 @@ async def find_duplicate_note(
     note_type: str = "note",
     code: str = "",
     locations: list[dict] | None = None,
+    data: dict | None = None,
 ) -> DuplicateMatch | None:
     """Best near-duplicate of (title, body) within the same owner + project +
     kind, or None. Title match first (cheap, exact), then — for snippets — the
@@ -258,6 +259,11 @@ async def find_duplicate_note(
     `code` and `locations` are the snippet's structured fields. They are ignored
     for every other kind, and passing them is what lets the gate compare
     ARTEFACTS rather than descriptions of artefacts (#2518).
+
+    `data` is the candidate's structured mirror. For a snippet or lesson it
+    carries the trigger, which the TITLE no longer does (milestone 427): the
+    title check compares names, and the semantic check rebuilds the embedded
+    document from `data`.
     """
     norm = " ".join((title or "").split()).lower()
 
@@ -309,7 +315,11 @@ async def find_duplicate_note(
         # section. Capped so one pathological paste can't turn a save into
         # dozens of searches — a duplicate past the cap is the duplicate
         # report's job, not the gate's.
-        for query in embeddings_svc.chunk_document(title, body)[:_GATE_MAX_CHUNKS]:
+        # The EMBEDDED title (milestone 427): a snippet or lesson is stored
+        # under its name and embedded under `name — trigger`, so the query
+        # document is built the way the corpus was, from `data`.
+        doc_title = embeddings_svc.document_title(title, note_type, data, body)
+        for query in embeddings_svc.chunk_document(doc_title, body)[:_GATE_MAX_CHUNKS]:
             # Scope the semantic check the same way as the title check: a record
             # in project P compares only to P; a project-less (orphan) record
             # compares only to other orphans (orphan_only), NOT across every

src/scribe/services/embeddings.py

@@ -214,10 +214,12 @@ TRIGGER_SEP = " — "
 def trigger_title(subject: str | None, trigger: str | None) -> str:
     """`{subject} — {trigger}` — the title half of a situation-keyed document.
 
-    ONE definition, because this join had three. `rule_document` built it for
-    rules, `snippets.compose_title` for snippets, and milestone 385 needed a
-    fourth for lessons — the shape #3207 records, where a fix or an improvement
-    then has to be found in N places by someone who does not know N.
+    ONE definition, because this join had three — rules, snippets, and a
+    fourth for lessons (milestone 385) — the shape #3207 records, where a fix
+    or an improvement then has to be found in N places by someone who does not
+    know N. Since milestone 427 it builds EMBEDDED titles only: `rule_document`
+    for rules and `document_title` for snippets and lessons. No stored title
+    carries it.
 
     WHY THE JOIN MATTERS AT ALL, measured in note #2485: the snippet was the
     only sharp record in the corpus — a 0.153 top-to-second gap against
@@ -265,6 +267,51 @@ def untrigger_title(title: str | None, trigger: str | None) -> str:
     return title
 
 
+# The `data` key each trigger-keyed note kind mirrors its trigger under. Rules
+# are not here: they keep the trigger in a column and `rule_document` builds
+# their document from it.
+_TRIGGER_DATA_KEYS = {"snippet": "when_to_use", "lesson": "when_to_apply"}
+
+
+def document_title(
+    title: str | None, note_type: str | None, data: dict | None = None,
+    body: str | None = None,
+) -> str | None:
+    """The title a note is EMBEDDED under — its stored title, plus its trigger.
+
+    Milestone 427. A snippet's or lesson's STORED title is its subject alone;
+    the trigger lives in `data` (decision #4157). It still has to reach the
+    vector — the `subject — trigger` join is what makes these kinds rank on
+    the situation they apply to (#2485) — so it is joined HERE, at embed time,
+    rather than being carried in a title every listing then has to show.
+
+    IDEMPOTENT, and that is what makes the migration safe: a title that is
+    already composed (a row not yet migrated, an old backup restored) is
+    untriggered first, so it comes out the same and never doubled. The text is
+    byte-identical to what these kinds were embedded as before, so no vector
+    moves and the floors tuned against them stay calibrated.
+
+    `body` is the fallback when the mirror is missing, read by the kind's own
+    parser — the same degrade-to-the-body each kind's reader already has.
+    Every other kind, and a record with no trigger, keeps its title as-is.
+    """
+    key = _TRIGGER_DATA_KEYS.get(note_type or "")
+    if key is None:
+        return title
+    trigger = ((data or {}).get(key) or "").strip() if isinstance(data, dict) else ""
+    if not trigger and body:
+        from types import SimpleNamespace
+        if note_type == "lesson":
+            from scribe.services.lessons import lesson_trigger
+            trigger = lesson_trigger(SimpleNamespace(data=None, body=body))
+        else:
+            from scribe.services.snippets import parse_snippet_fields
+            trigger = parse_snippet_fields(title or "", body).get("when_to_use", "")
+    if not trigger:
+        return title
+    return trigger_title(untrigger_title(title, trigger), trigger)
+
+
 # --- chunking (#280): the document shape ------------------------------------
 #
 # bge-small reads at most 512 tokens and fastembed silently truncates the rest,
@@ -1081,10 +1128,14 @@ async def backfill_note_embeddings() -> None:
     )
     success = 0
     for note_id in notes_to_embed:
-        row = await _current_row((Note.user_id, Note.title, Note.body), Note.id, note_id)
+        row = await _current_row(
+            (Note.user_id, Note.title, Note.body, Note.note_type, Note.data), Note.id, note_id,
+        )
         if row is None:
             continue          # deleted between the scan and here
-        user_id, title, body = row
+        user_id, title, body, note_type, data = row
+        # The EMBEDDED title, as the write path builds it (milestone 427).
+        title = document_title(title, note_type, data, body)
         if not chunk_document(title, body):
             continue
         await upsert_note_embedding(note_id, user_id, title, body)

src/scribe/services/knowledge.py

@@ -267,6 +267,11 @@ def _note_to_item(note: Note, chunks: dict[int, dict] | None = None) -> dict:
     trigger = (note.data or {}).get("when_to_apply") if note.data else None
     if trigger:
         item["when_to_apply"] = trigger
+    # A snippet's, for the same reason — and since milestone 427 the title no
+    # longer carries it, so without this a list shows names with no situation.
+    usage = (note.data or {}).get("when_to_use") if note.data else None
+    if usage:
+        item["when_to_use"] = usage
 
     verdict = (note.data or {}).get("verification") if note.data else None
     if verdict and verdict.get("status"):

src/scribe/services/lessons.py

@@ -26,20 +26,23 @@ while staying a note in every other respect.
 WHERE THE TRIGGER LIVES (decision #4157, milestone 385 step 1)
 
 In ``notes.data`` under ``when_to_apply``, written through a named parameter and
-mirrored into the title and the head of the body — the shape snippets already
-use for ``when_to_use``. Not a column on ``notes``.
+mirrored into the head of the body — the shape snippets already use for
+``when_to_use``. Not a column on ``notes``. Since milestone 427 it is NOT in the
+stored title: the title is the lesson's subject, and the trigger joins it only
+in the embedded document (``embeddings.document_title``).
 
 That decision was measured rather than assumed. The whole snippet corpus —
 164 of 164 — carries a ``when_to_use`` with **no guard anywhere**, which refutes
 the premise that an unenforced field gets skipped. What it does NOT show is that
-an agent types a title convention correctly: ``compose_title`` builds the title
+an agent types a title convention correctly: the service composed the title
 from the parameter, so what is at 100% is a named structured field. A column
 would have bought enforceability at the price of deciding, for every note kind
 at once, a question nothing had measured.
 
-The mirror is what makes the vector sharp, and it is why nothing re-embeds:
-``chunk_document`` is untouched, so ``CHUNKER_VERSION`` does not move. The
-trigger reaches the document by being in the text, exactly as a snippet's is.
+The trigger in the document is what makes the vector sharp. It reaches it
+twice — in the embedded title, joined at embed time, and in the body's first
+line — which is the text these kinds were always embedded as, so nothing
+re-embeds and ``CHUNKER_VERSION`` does not move.
 
 WHAT A LESSON INHERITS, AND THE CELLS LEFT EMPTY ON PURPOSE (#3163)
 
@@ -207,36 +210,17 @@ def sole_source(sources: list[int] | None) -> int | None:
     return ids[0] if len(ids) == 1 else None
 
 
-def compose_title(what: str, when_to_apply: str = "") -> str:
-    """`{what} — {when it applies}`, the half of the document that ranks.
-
-    Built HERE rather than asked of the caller, and that distinction is the
-    whole evidence base for this design: the snippet corpus is at 100% on its
-    trigger because a service composes the title from a named parameter, not
-    because agents type separators reliably. A caller made to spell the
-    convention is the option milestone 385 step 1 rejected.
-
-    The join is `embeddings.trigger_title` — shared with rules and snippets, so
-    the three kinds that rank on a trigger cannot drift apart in how they say
-    so.
-    """
-    from scribe.services.embeddings import trigger_title
-
-    return trigger_title(what, when_to_apply)
-
-
 def compose_body(
     insight: str, when_to_apply: str = "", learned_from: list[int] | None = None,
 ) -> str:
     """The lesson body — the trigger line first, the insight after.
 
-    The mirror of `compose_title` on the other half of the document, and the
-    reason the pair is what makes a lesson findable: `chunk_document` joins
-    them as `{title}\\n{body}`, so a lesson composed here states WHEN IT
-    APPLIES in the title and again in the first line of the body. That is the
-    twice-in-a-short-document shape note #2485 measured as the only sharp one
-    in the corpus, reached the way a snippet reaches it — by being in the text
-    — rather than by a second document builder at embed time.
+    The trigger's home in the text of the document, and half of what makes a
+    lesson findable: `chunk_document` joins `{embedded title}\\n{body}`, and
+    the embedded title is `what — when it applies` (`embeddings.document_title`,
+    milestone 427), so the document states WHEN IT APPLIES in the title and
+    again in the first line of the body. That is the twice-in-a-short-document
+    shape note #2485 measured as the only sharp one in the corpus.
 
     `**When to apply:**` rather than plain text: the body is the READABLE
     form, `data` is the queryable mirror, and `_BODY_TRIGGER_RE` reads this
@@ -275,23 +259,23 @@ def lesson_document(
     what: str, when_to_apply: str = "", insight: str = "",
     learned_from: list[int] | None = None,
 ) -> tuple[str, str]:
-    """The (title, body) a lesson is STORED — and therefore embedded — as.
+    """The (title, body) a lesson is STORED as.
 
-    One call so the two halves cannot be composed apart. A lesson whose title
-    carried the trigger and whose body did not would embed as an ordinary
-    note wearing a label, and nothing would report it: the record would look
-    right in every listing and simply never be retrieved at the moment it
-    applies.
+    One call so the two halves cannot be composed apart. The body's first line
+    carries the trigger; a lesson without it (and without the `data` mirror)
+    would embed as an ordinary note wearing a label, and nothing would report
+    it: the record would look right in every listing and simply never be
+    retrieved at the moment it applies.
 
-    Deliberately returns what is STORED, not a separate embed-time shape.
-    Rules need `rule_document` because a rule keeps its trigger in a column
-    and its title is a plain name, so the sharp document has to be synthesised
-    for the ranker and exists nowhere else. A lesson follows the snippet
-    instead — the stored record IS the sharp document — which is why nothing
-    re-embeds and `CHUNKER_VERSION` does not move.
+    The title is the SUBJECT alone (milestone 427). It used to carry the
+    trigger too, so the stored record was itself the sharp document — and every
+    listing, menu and search row then showed a title that ran to kilobytes.
+    The trigger now joins the title at embed time (`embeddings.document_title`,
+    reading `data`), producing the same text as before, so nothing re-embeds
+    and `CHUNKER_VERSION` does not move.
     """
     return (
-        compose_title(what, when_to_apply),
+        (what or "").strip(),
         compose_body(insight, when_to_apply, learned_from),
     )
 

src/scribe/services/notes.py

@@ -115,11 +115,17 @@ def embed_note(note) -> None:
     try:
         import asyncio
 
-        from scribe.services.embeddings import upsert_note_embedding
+        from scribe.services.embeddings import document_title, upsert_note_embedding
         # Chunking and the empty-record gate live inside upsert_note_embedding —
-        # one path for every writer (#280).
+        # one path for every writer (#280). The title is the EMBEDDED one: a
+        # snippet's or lesson's trigger joins its name here, not in the stored
+        # title (milestone 427).
         asyncio.create_task(
-            upsert_note_embedding(note.id, note.user_id, note.title, note.body)
+            upsert_note_embedding(
+                note.id, note.user_id,
+                document_title(note.title, note.note_type, note.data, note.body),
+                note.body,
+            )
         )
     except RuntimeError:
         pass          # no running loop — a sync caller, not a failure

src/scribe/services/plugin_context.py

@@ -27,7 +27,11 @@ from scribe.services import projects as projects_svc
 from scribe.services import shape_ledger as shape_ledger_svc
 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.embeddings import (
+    document_title,
+    semantic_search_notes,
+    semantic_search_rules,
+)
 from scribe.services.lessons import LESSON_NOTE_TYPE
 from scribe.services.note_usage import record_surfaced
 from scribe.services.rule_usage import record_rule_surfaced
@@ -88,8 +92,10 @@ def _menu_name(title: str | None, note_type: str | None, data=None, body: str |
 def _menu_passage(title: str | None, chunk_text: str | None, name: str = "") -> str:
     """The matched chunk on one line, without the title it was embedded under.
 
-    Every chunk is `title\nsection` (`embeddings.embedding_text`), so the title
-    prefix is stripped exactly. A chunk that WAS only the title — a short
+    Every chunk is `title\nsection` (`embeddings.embedding_text`), and `title`
+    here must be the EMBEDDED one (`embeddings.document_title`) — for a snippet
+    or lesson that is `name — trigger`, not the stored name — so the prefix is
+    stripped exactly. A chunk that WAS only the title — a short
     record, or the head chunk of one — matched on the title, and for a
     trigger-keyed kind the part of it the name line no longer shows is the
     trigger: that is returned, because it is precisely what matched.
@@ -1235,7 +1241,10 @@ async def build_autoinject_hint(
         # queries and so are not in this search's report. No fallback to the
         # body's opening: on a menu that would be a line of preamble dressed as
         # a reason, and a reader cannot tell the two apart once indented alike.
-        passage = _menu_passage(note.title, (menu_chunks.get(nid) or {}).get("text"), name)
+        passage = _menu_passage(
+            document_title(note.title, note.note_type, note.data, note.body),
+            (menu_chunks.get(nid) or {}).get("text"), name,
+        )
         if passage:
             lines.append(f">   ↳ {passage}")
 
@@ -2324,6 +2333,10 @@ async def build_write_path_hint(
                         # (#4364): the line is built from facts, not from
                         # re-reading its own marker.
                         "name": _menu_name(note.title, note.note_type, note.data, note.body),
+                        # What its chunks are prefixed with, for stripping.
+                        "doc_title": document_title(
+                            note.title, note.note_type, note.data, note.body,
+                        ),
                         "seen": int(note.id) in excluded,
                         # Carried, not re-read off the rendered marker. The
                         # marker is prose assembled for a human and it already
@@ -2510,7 +2523,8 @@ async def build_write_path_hint(
         if item.get("seen"):
             continue
         passage = _menu_passage(
-            item.get("title"), (wp_chunks.get(int(item["id"])) or {}).get("text"),
+            item.get("doc_title") or item.get("title"),
+            (wp_chunks.get(int(item["id"])) or {}).get("text"),
             item.get("name") or "",
         )
         if passage:

src/scribe/services/snippets.py

@@ -54,18 +54,6 @@ UNSET: object = object()
 
 # --- serialize: structured fields -> note (title/body/tags) ------------------
 
-def compose_title(name: str, when_to_use: str = "") -> str:
-    """`name — when to use` (or just `name` when no usage note is given).
-
-    The join itself lives in `embeddings.trigger_title`, which rules and
-    lessons build their titles from too. Kept as a named function here because
-    it is this module's public vocabulary and callers say `compose_title`.
-    """
-    from scribe.services.embeddings import trigger_title
-
-    return trigger_title(name, when_to_use)
-
-
 def compose_tags(language: str = "", tags: list[str] | None = None) -> list[str]:
     """Language (lowercased) first, then the `snippet` marker, then caller tags —
     de-duplicated, order preserved."""
@@ -741,7 +729,7 @@ async def create_snippet(
     locations = resolve_locations(repo, path, symbol, locations)
     note = await notes_svc.create_note(
         user_id,
-        title=compose_title(name, when_to_use),
+        title=name.strip(),
         body=compose_body(
             code=code, language=language, signature=signature,
             when_to_use=when_to_use, locations=locations,
@@ -898,7 +886,7 @@ async def update_snippet(
         provenance = cur.get("provenance")
 
     fields: dict = {
-        "title": compose_title(merged["name"], merged["when_to_use"]),
+        "title": (merged["name"] or "").strip(),
         "body": compose_body(
             code=merged["code"], language=merged["language"],
             signature=merged["signature"], when_to_use=merged["when_to_use"],

tests/helpers.py

@@ -212,10 +212,10 @@ def fake_snippet(**attrs) -> MagicMock:
 def fake_lesson(**attrs) -> MagicMock:
     """A stand-in lesson: a note whose `note_type` is what makes it one.
 
-    The title carries the trigger because `compose_title` builds it that way —
-    `{what} — {when it applies}` — so a menu line rendering only the title is
-    already showing the reader when this lesson applies. Tests that used a bare
-    title here would be testing a record the product cannot create.
+    The title is the subject alone and the trigger lives in `data`, because
+    that is the record the product creates (milestone 427) — the trigger joins
+    the title only in the embedded document. A default whose title carried the
+    trigger would be testing a row only an un-migrated database holds.
 
     The check fields and `arose_from_id` are explicitly None for the reason
     `fake_snippet`'s `data` is: `update_note` reads `verify_with` and
@@ -223,12 +223,11 @@ def fake_lesson(**attrs) -> MagicMock:
     auto-created MagicMock attribute is truthy — so a default lesson driven
     through the update path would take a branch no real record takes.
     """
-    attrs.setdefault(
-        "title",
-        "Give absolutely-positioned siblings an explicit stacking order — "
-        "placing two absolutely-positioned elements in the same area",
-    )
-    attrs.setdefault("data", {"when_to_apply": "two absolute siblings overlap"})
+    attrs.setdefault("title", "Give absolutely-positioned siblings an explicit stacking order")
+    attrs.setdefault("data", {
+        "what": "Give absolutely-positioned siblings an explicit stacking order",
+        "when_to_apply": "placing two absolutely-positioned elements in the same area",
+    })
     attrs.setdefault("status", None)
     attrs.setdefault("arose_from_id", None)
     attrs.setdefault("verify_with", None)

tests/test_backfill_reads_current_text.py

@@ -56,7 +56,7 @@ async def test_the_backfill_embeds_the_text_as_it_is_now_not_as_it_was_scanned()
     with (
         patch.object(emb, "async_session", return_value=_ctx(scan)),
         patch.object(emb, "_current_row",
-                     AsyncMock(return_value=(42, "T", *edited))),
+                     AsyncMock(return_value=(42, "T", *edited, "note", None))),
         patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert,
         patch.object(emb.asyncio, "sleep", AsyncMock()),
     ):
@@ -75,7 +75,7 @@ async def test_a_record_deleted_between_the_scan_and_the_loop_is_skipped():
     with (
         patch.object(emb, "async_session", return_value=_ctx(scan)),
         patch.object(emb, "_current_row",
-                     AsyncMock(side_effect=[None, (42, "T", "body")])),
+                     AsyncMock(side_effect=[None, (42, "T", "body", "note", None)])),
         patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert,
         patch.object(emb.asyncio, "sleep", AsyncMock()),
     ):
@@ -99,7 +99,7 @@ async def test_a_record_whose_text_outran_its_vectors_is_re_embedded():
 
     with (
         patch.object(emb, "async_session", return_value=_ctx(scan)),
-        patch.object(emb, "_current_row", AsyncMock(return_value=(42, "T", "b"))),
+        patch.object(emb, "_current_row", AsyncMock(return_value=(42, "T", "b", "note", None))),
         patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert,
         patch.object(emb.asyncio, "sleep", AsyncMock()),
     ):
@@ -119,7 +119,7 @@ async def test_a_task_logged_since_its_vectors_is_re_embedded():
 
     with (
         patch.object(emb, "async_session", return_value=_ctx(scan)),
-        patch.object(emb, "_current_row", AsyncMock(return_value=(42, "T", "b"))),
+        patch.object(emb, "_current_row", AsyncMock(return_value=(42, "T", "b", "note", None))),
         patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert,
         patch.object(emb.asyncio, "sleep", AsyncMock()),
     ):

tests/test_chunking.py

@@ -306,7 +306,7 @@ async def test_backfill_reembeds_notes_with_a_stale_chunker_version():
     with (
         patch.object(emb, "async_session", return_value=ctx),
         patch.object(emb, "_current_row",
-                     AsyncMock(return_value=(42, "stale-version", "body"))),
+                     AsyncMock(return_value=(42, "stale-version", "body", "note", None))),
         patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert,
         patch.object(emb.asyncio, "sleep", AsyncMock()),
     ):

tests/test_derived_mirror_generic_door.py

@@ -164,11 +164,11 @@ def _lesson_body(trigger, insight="Read the job log.", sources=None):
 
 @pytest.mark.asyncio
 async def test_a_body_write_moves_a_lessons_trigger_with_it():
-    from scribe.services.lessons import TRIGGER_KEY, compose_title
+    from scribe.services.lessons import TRIGGER_KEY
 
     what = "Read the job log before waiting longer"
     note = fake_lesson(
-        title=compose_title(what, NEW_TRIGGER),
+        title=what,
         data={TRIGGER_KEY: "a CI run is slow", "what": what},
         project_id=None,
     )
@@ -183,13 +183,16 @@ async def test_a_body_write_moves_a_lessons_trigger_with_it():
 @pytest.mark.asyncio
 async def test_a_subject_containing_an_em_dash_still_splits():
     """Why `untrigger_title` is given the trigger instead of splitting on the
-    separator: a subject may legitimately contain one."""
-    from scribe.services.lessons import TRIGGER_KEY, compose_title
+    separator: a subject may legitimately contain one. The title here is an
+    UN-MIGRATED one, still carrying its trigger (milestone 427), because that
+    is the row the inverse still has to read correctly."""
+    from scribe.services.embeddings import trigger_title
+    from scribe.services.lessons import TRIGGER_KEY
 
     what = "A wait with no deadline — the shape, not the symptom"
     trigger = "you are about to await something crossing a process boundary"
     note = fake_lesson(
-        title=compose_title(what, trigger), data=None, project_id=None,
+        title=trigger_title(what, trigger), data=None, project_id=None,
     )
     await _update(note, body=_lesson_body(trigger))
     assert note.data["what"] == what
@@ -202,10 +205,10 @@ async def test_dropping_the_provenance_line_drops_it_from_the_mirror():
     the failure this recompose exists to prevent, not a courtesy — the
     opposite call from a snippet's `verification`, which is carried because it
     was never in the body to delete."""
-    from scribe.services.lessons import SOURCES_KEY, compose_title
+    from scribe.services.lessons import SOURCES_KEY
 
     note = fake_lesson(
-        title=compose_title("Something learned", "a situation"),
+        title="Something learned",
         data={SOURCES_KEY: [999]},
         project_id=None,
     )
@@ -229,7 +232,7 @@ async def test_an_explicit_data_wins_for_a_lesson_too():
 async def test_a_lesson_title_change_reaches_the_mirror():
     """A lesson's subject lives in its title, so a title edit is a trigger for
     recomposition exactly as it is for a snippet's name."""
-    from scribe.services.lessons import TRIGGER_KEY, compose_title
+    from scribe.services.lessons import TRIGGER_KEY
 
     trigger = "two absolute siblings overlap"
     note = fake_lesson(
@@ -237,7 +240,7 @@ async def test_a_lesson_title_change_reaches_the_mirror():
         data={TRIGGER_KEY: trigger, "what": "the old subject"},
         project_id=None,
     )
-    await _update(note, title=compose_title("the new subject", trigger))
+    await _update(note, title="the new subject")
     assert note.data["what"] == "the new subject"
     assert note.data[TRIGGER_KEY] == trigger
 

tests/test_integration_lesson_kind.py

@@ -67,7 +67,7 @@ async def test_a_lesson_is_a_row_the_database_accepts(owner_id):
     value, and stays correct if it is gated with it."""
     lesson = await notes_svc.create_note(
         owner_id,
-        title=lessons_svc.compose_title(SUBJECT, TRIGGER),
+        title=SUBJECT,
         body=f"**When to apply:** {TRIGGER}\n\nOne change at a time.",
         note_type=lessons_svc.LESSON_NOTE_TYPE,
         data={lessons_svc.TRIGGER_KEY: TRIGGER},
@@ -83,7 +83,8 @@ async def test_a_lesson_is_a_row_the_database_accepts(owner_id):
     # and the readable body — because the vector is built from the text and
     # the queries are built from the mirror.
     assert lessons_svc.lesson_trigger(stored) == TRIGGER
-    assert stored.title == f"{SUBJECT} — {TRIGGER}"
+    # The subject alone (milestone 427): the trigger is in `data` and the body.
+    assert stored.title == SUBJECT
     assert "**When to apply:**" in (stored.body or "")
 
 
@@ -97,7 +98,7 @@ async def test_a_lesson_is_not_a_task(owner_id):
     """
     lesson = await notes_svc.create_note(
         owner_id,
-        title=lessons_svc.compose_title(SUBJECT, TRIGGER),
+        title=SUBJECT,
         body="One change at a time.",
         note_type=lessons_svc.LESSON_NOTE_TYPE,
     )

tests/test_lesson_document_shape.py

@@ -1,4 +1,4 @@
-"""The document a lesson is embedded as (milestone 385 step 3).
+"""The document a lesson is embedded as (milestone 385 step 3; milestone 427).
 
 WHY THIS IS THE STEP THAT DECIDES THE MILESTONE
 
@@ -7,26 +7,20 @@ as ordinary prose is a note wearing a label: it would look right in every
 listing and simply never be retrieved at the moment it applies, and nothing
 anywhere would report that.
 
-WHY THERE IS NO `lesson_document()` BESIDE `rule_document()`
+WHERE THE SHARP SHAPE LIVES
 
-The step anticipated one. There isn't, and the difference is where the sharp
-shape LIVES rather than whether it exists.
+A snippet, which note #2485 measured as the only sharp record in the corpus (a
+0.153 top-to-second gap against 0.010–0.023 for everything else), is sharp
+because its document states its purpose twice: `name — when to use` as the
+title, and again as the body's first line. A lesson follows the snippet.
 
-A rule keeps its trigger in a column and its title is a plain name, so the
-`{title} — {trigger}` document has to be synthesised at embed time and exists
-nowhere else — that is what `rule_document` is for. A snippet, which note #2485
-measured as the only sharp record in the corpus (a 0.153 top-to-second gap
-against 0.010–0.023 for everything else), gets there the other way: its STORED
-title is already the join and its stored body already opens with the trigger,
-so the ordinary `title\\nbody` join is the sharp document. A lesson follows the
-snippet, which is what step 1 decided and step 2 built.
+Until milestone 427 that `subject — trigger` title was also the STORED title,
+so every listing, menu and search row showed the trigger too — kilobytes of it.
+Now the stored title is the subject, and `embeddings.document_title` joins the
+trigger back from `data` at embed time. The embedded TEXT is what it always
+was, which is the property these guards pin: nothing re-embeds, and the floors
+tuned against these vectors stay calibrated.
 
-The consequence worth stating: `chunk_document` is untouched, so
-`CHUNKER_VERSION` does not move and nothing re-embeds. The step's "Re-embed"
-section describes a change this design does not make.
-
-These guards therefore assert the composed record, then assert that the generic
-chunker turns it into the intended document — the two halves of the same claim.
 No similarity number is asserted anywhere: a threshold pins the embedder's
 behaviour rather than this code's, and breaks on a model change that is not a
 regression.
@@ -34,18 +28,46 @@ regression.
 from __future__ import annotations
 
 from scribe.services import lessons as lessons_svc
-from scribe.services.embeddings import chunk_document, embedding_text
+from scribe.services.embeddings import chunk_document, document_title, embedding_text
 
 TRIGGER = "a test fails on code you believe is correct"
 SUBJECT = "Suspect the guard before the code"
 INSIGHT = "Check whether the assertion still describes the property it was written for."
 
 
+def _embedded(what: str, trigger: str, insight: str) -> tuple[str, str]:
+    """The (title, body) the write path EMBEDS a lesson as — built the way
+    `notes.embed_note` builds it, from what `create_lesson` stores."""
+    title, body = lessons_svc.lesson_document(what, trigger, insight)
+    data = lessons_svc.compose_data(what, trigger)
+    return document_title(title, lessons_svc.LESSON_NOTE_TYPE, data, body), body
+
+
+def test_the_stored_title_is_the_subject_alone():
+    """Milestone 427. The trigger lives in `data` and the body's first line; the
+    title a listing shows is what the lesson is ABOUT."""
+    title, _ = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT)
+    assert title == SUBJECT
+
+
+def test_the_embedded_document_is_the_one_it_always_was():
+    """THE no-re-embed guard. The document text must be byte-identical to what
+    a lesson embedded as when its stored title carried the trigger — and an
+    un-migrated row, whose stored title still does, must come out the same
+    rather than with the trigger twice."""
+    legacy_title = f"{SUBJECT} — {TRIGGER}"
+    title, body = _embedded(SUBJECT, TRIGGER, INSIGHT)
+    assert title == legacy_title
+
+    data = lessons_svc.compose_data(SUBJECT, TRIGGER)
+    assert document_title(legacy_title, lessons_svc.LESSON_NOTE_TYPE, data, body) == legacy_title
+
+
 def test_the_trigger_appears_twice_in_the_document():
-    """THE guard. Purpose stated twice in a short document is the entire
-    measured cause of a snippet's sharpness, and it is the one property that
-    distinguishes a lesson's vector from a plain note's."""
-    title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT)
+    """Purpose stated twice in a short document is the entire measured cause of
+    a snippet's sharpness, and it is the one property that distinguishes a
+    lesson's vector from a plain note's."""
+    title, body = _embedded(SUBJECT, TRIGGER, INSIGHT)
     document = embedding_text(title, body)
 
     assert document.count(TRIGGER) == 2
@@ -55,22 +77,28 @@ def test_the_trigger_appears_twice_in_the_document():
 
 
 def test_the_document_leads_with_when_it_applies():
-    """The title is `{what} — {when}` and the body's FIRST line restates it, so
-    the opening of the document is about the situation rather than the topic.
-    A lesson buried behind a paragraph of narrative would rank on the
-    narrative."""
-    title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT)
+    """The embedded title is `{what} — {when}` and the body's FIRST line
+    restates it, so the opening of the document is about the situation rather
+    than the topic."""
+    title, body = _embedded(SUBJECT, TRIGGER, INSIGHT)
 
     assert title == f"{SUBJECT} — {TRIGGER}"
     assert body.splitlines()[0] == f"**When to apply:** {TRIGGER}"
 
 
+def test_the_trigger_reaches_the_document_even_without_the_mirror():
+    """A row whose `data` lost its mirror still embeds sharply: the trigger is
+    read back from the body, the same fallback `lesson_trigger` has."""
+    title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT)
+    assert document_title(title, lessons_svc.LESSON_NOTE_TYPE, None, body) == (
+        f"{SUBJECT} — {TRIGGER}"
+    )
+
+
 def test_a_short_lesson_is_exactly_one_chunk():
     """`chunk_document`'s first contract line: a record inside the window
-    yields one chunk identical to the historical `title\\nbody`. A lesson that
-    split into several would spread the trigger's weight across vectors that
-    each carry less of it."""
-    title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT)
+    yields one chunk identical to the historical `title\\nbody`."""
+    title, body = _embedded(SUBJECT, TRIGGER, INSIGHT)
     chunks = chunk_document(title, body)
 
     assert len(chunks) == 1
@@ -78,26 +106,15 @@ def test_a_short_lesson_is_exactly_one_chunk():
 
 
 def test_a_long_lesson_keeps_the_trigger_on_every_chunk():
-    """The narrative question, answered by the chunker rather than by holding
-    the story out of the record.
-
-    `rule_document` excludes a rule's `why` because long dated narrative made
-    sixteen dev-logs land on the centroid of "development". That finding
-    predates chunking (#280): a body over budget is now split, and EVERY chunk
-    is prefixed with the title — which for a lesson carries the trigger. So the
-    story occupies its own vectors instead of averaging itself into the
-    trigger's, and each of those vectors is still anchored to when the lesson
-    applies.
-
-    This is why the insight stays in the body where a reader can see it. Holding
-    it out would cost the reader the only part that explains the lesson, to buy
-    a sharpness the chunker already provides.
+    """Every chunk is prefixed with the embedded title, which carries the
+    trigger — so a long story occupies its own vectors instead of averaging
+    itself into the trigger's, and each is still anchored to when it applies.
     """
     narrative = "\n\n".join(
         f"## Section {i}\n" + ("An unrelated sentence about deployment. " * 40)
         for i in range(6)
     )
-    title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, narrative)
+    title, body = _embedded(SUBJECT, TRIGGER, narrative)
     chunks = chunk_document(title, body)
 
     assert len(chunks) > 1, "the fixture must actually exceed the chunk budget"
@@ -106,10 +123,8 @@ def test_a_long_lesson_keeps_the_trigger_on_every_chunk():
 
 def test_a_lesson_with_no_trigger_still_embeds():
     """Degrades to title + insight, the way a rule with no trigger does — less
-    sharply, and still findable. That is an argument for prompting hard for a
-    trigger at write time, not for padding the document with whatever text is
-    to hand."""
-    title, body = lessons_svc.lesson_document(SUBJECT, "", INSIGHT)
+    sharply, and still findable."""
+    title, body = _embedded(SUBJECT, "", INSIGHT)
 
     assert title == SUBJECT
     assert body == INSIGHT
@@ -119,8 +134,7 @@ def test_a_lesson_with_no_trigger_still_embeds():
 def test_the_composed_body_is_the_one_the_reader_is_parsed_back_from():
     """`compose_body` writes the trigger line and `lesson_trigger` reads it. A
     lesson whose mirror in `data` is missing still answers correctly, so the
-    two must agree on the exact markdown — which is why neither is written by
-    hand at a call site."""
+    two must agree on the exact markdown."""
     from types import SimpleNamespace
 
     _, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT)
@@ -130,10 +144,8 @@ def test_the_composed_body_is_the_one_the_reader_is_parsed_back_from():
 
 
 def test_the_title_and_body_are_composed_by_one_call():
-    """`lesson_document` returns both halves so they cannot be built apart. A
-    title carrying the trigger over a body that does not would embed as an
-    ordinary note, and every listing would still look correct."""
+    """`lesson_document` returns both halves so they cannot be built apart."""
     assert lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT) == (
-        lessons_svc.compose_title(SUBJECT, TRIGGER),
+        SUBJECT,
         lessons_svc.compose_body(INSIGHT, TRIGGER),
     )

tests/test_lesson_kind.py

@@ -29,7 +29,6 @@ from types import SimpleNamespace
 
 from scribe.services import knowledge as knowledge_svc
 from scribe.services import lessons as lessons_svc
-from scribe.services import snippets as snippets_svc
 from scribe.services.embeddings import trigger_title
 
 
@@ -76,15 +75,18 @@ def test_one_join_builds_every_trigger_title():
     expected = f"{subject} — {trigger}"
 
     assert trigger_title(subject, trigger) == expected
-    assert lessons_svc.compose_title(subject, trigger) == expected
-    assert snippets_svc.compose_title(subject, trigger) == expected
+    # The two note kinds reach it through the EMBEDDED title (milestone 427),
+    # from their own mirror key — never a hand-rolled join.
+    from scribe.services.embeddings import document_title
+    assert document_title(subject, "lesson", {"when_to_apply": trigger}) == expected
+    assert document_title(subject, "snippet", {"when_to_use": trigger}) == expected
 
 
 def test_a_subject_with_no_trigger_degrades_to_the_subject():
     """It still embeds, just less sharply — an argument for backfilling
     triggers, not for padding the title with whatever text is to hand."""
     assert trigger_title("debounce", "") == "debounce"
-    assert lessons_svc.compose_title("  debounce  ") == "debounce"
+    assert lessons_svc.lesson_document("  debounce  ")[0] == "debounce"
     assert trigger_title("", "when it applies") == "when it applies"
 
 

tests/test_lesson_rest_door.py

@@ -214,13 +214,13 @@ def test_the_payload_reads_back_the_composed_fields():
     """A caller that wrote `when_to_apply` reads `when_to_apply` back, not a
     body it has to parse."""
     from tests.helpers import fake_lesson
-    from scribe.services.lessons import compose_body, compose_title, lesson_to_dict
+    from scribe.services.lessons import compose_body, lesson_to_dict
 
     what = "Read the job log before waiting longer"
     trigger = "a CI run has sat in_progress longer than its suite takes"
     note = fake_lesson(
         id=7,
-        title=compose_title(what, trigger),
+        title=what,
         body=compose_body("The work is usually done.", trigger, [4181]),
         data={"what": what, "when_to_apply": trigger, "taught_by": [4181]},
         project_id=None,

tests/test_lesson_write_path.py

@@ -117,7 +117,8 @@ async def test_the_duplicate_gate_runs_before_anything_is_created():
 @pytest.mark.asyncio
 async def test_the_gate_compares_the_composed_document_not_the_raw_fields():
     """What reaches the gate is the title and body a lesson will actually be
-    stored as. Comparing `what` alone would miss that the trigger is half the
+    stored as, plus the `data` its EMBEDDED title is built from (milestone
+    427). Comparing `what` alone would miss that the trigger is half the
     document, and would judge two lessons alike that rank nothing alike."""
     _user_id_ctx.set(7)
     gate = AsyncMock(return_value=None)
@@ -128,8 +129,9 @@ async def test_the_gate_compares_the_composed_document_not_the_raw_fields():
         await create_lesson(what=SUBJECT, when_to_apply=TRIGGER, insight="Look.")
 
     title, body = gate.await_args.args[1], gate.await_args.args[2]
-    assert title == f"{SUBJECT} — {TRIGGER}"
+    assert title == SUBJECT
     assert body.startswith(f"**When to apply:** {TRIGGER}")
+    assert gate.await_args.kwargs["data"]["when_to_apply"] == TRIGGER
     assert gate.await_args.kwargs["note_type"] == "lesson"
 
 
@@ -157,9 +159,11 @@ def test_a_lesson_is_judged_at_the_trigger_dominated_bar():
 
 @pytest.mark.asyncio
 async def test_an_update_recomposes_both_halves_of_the_document():
-    """A new trigger has to reach the title AND the head of the body. Patching
-    one would leave a lesson that reads correctly and ranks on the old
-    situation — the failure mode with no symptom."""
+    """A new trigger has to reach the mirror AND the head of the body — the two
+    places the embedded document reads it from (milestone 427). Patching one
+    would leave a lesson that reads correctly and ranks on the old situation —
+    the failure mode with no symptom. The title stays the subject, even when
+    the stored one was an un-migrated composed title."""
     _user_id_ctx.set(7)
     stored = _stub_note(
         title=f"{SUBJECT} — {TRIGGER}",
@@ -172,7 +176,7 @@ async def test_an_update_recomposes_both_halves_of_the_document():
         await lessons_svc.update_lesson(7, 1, when_to_apply="a guard goes red")
 
     fields = updated.await_args.kwargs
-    assert fields["title"] == f"{SUBJECT} — a guard goes red"
+    assert fields["title"] == SUBJECT
     assert fields["body"].startswith("**When to apply:** a guard goes red")
     assert fields["data"]["when_to_apply"] == "a guard goes red"
 

tests/test_services_snippets.py

@@ -2,10 +2,18 @@
 from scribe.services import snippets as s
 
 
-def test_compose_title_with_and_without_usage():
-    assert s.compose_title("debounce", "rate-limit a callback") == "debounce — rate-limit a callback"
-    assert s.compose_title("  debounce  ", "") == "debounce"
-    assert s.compose_title("debounce") == "debounce"
+def test_the_embedded_title_joins_the_trigger_the_stored_one_does_not_carry():
+    """Milestone 427: stored title = name; the trigger joins it at embed time,
+    idempotently, so an old composed title comes out the same."""
+    from scribe.services.embeddings import document_title
+
+    data = {"name": "debounce", "when_to_use": "rate-limit a callback"}
+    assert document_title("debounce", "snippet", data) == "debounce — rate-limit a callback"
+    assert document_title("debounce — rate-limit a callback", "snippet", data) == (
+        "debounce — rate-limit a callback"
+    )
+    assert document_title("debounce", "snippet", {"name": "debounce"}) == "debounce"
+    assert document_title("a — note", "note", data) == "a — note"
 
 
 def test_compose_tags_lowercases_language_and_dedups():
@@ -32,7 +40,7 @@ def test_compose_body_bare_code_only():
 
 
 def test_parse_round_trips_a_composed_snippet():
-    title = s.compose_title("useDebouncedRef", "debounce a reactive ref")
+    title = "useDebouncedRef"
     body = s.compose_body(
         code="const x = 1", language="ts", signature="useDebouncedRef(v, ms)",
         when_to_use="debounce a reactive ref", repo="scribe",
@@ -241,9 +249,9 @@ def test_data_and_body_round_trip_to_the_same_fields():
     name, when, sig, lang = ("debounce", "rate-limit a callback",
                              "debounce(fn, ms)", "ts")
     locs = [{"repo": "web", "path": "src/util.ts", "symbol": "debounce"}]
-    # compose_body takes no `name` — the name lives in the title — so the two
-    # serializers get their own argument lists rather than a shared spread.
-    title = s.compose_title(name, when)
+    # compose_body takes no `name` — the name IS the title (milestone 427) — so
+    # the two serializers get their own argument lists rather than a shared spread.
+    title = name
     body = s.compose_body(code="const x = 1", language=lang, signature=sig,
                           when_to_use=when, locations=locs, merged_from=[41, 42])
     tags = s.compose_tags(lang)